fix: prevent Serial.printf from blocking when USB disconnected

On ESP32-C3 with USB CDC, Serial.printf() blocks indefinitely when USB
is not connected. This caused device freezes when booted without USB.

Solution: Call Serial.setTxTimeoutMs(0) after Serial.begin() to make
all Serial output non-blocking.

Also added if (Serial) guards to high-traffic logging paths in
EpubReaderActivity as belt-and-suspenders protection.

Includes documentation of the debugging process and Serial call inventory.

Also applies clang-format to fix pre-existing formatting issues.

lib/Epub/Epub.cpp

@@ -251,8 +251,8 @@ bool Epub::parseCssFiles() {
     SdMan.remove(tmpCssPath.c_str());
   }
 
-  Serial.printf("[%lu] [EBP] Loaded %zu CSS style rules from %zu files (~%zu bytes)\n", millis(), cssParser->ruleCount(),
-                cssFiles.size(), cssParser->estimateMemoryUsage());
+  Serial.printf("[%lu] [EBP] Loaded %zu CSS style rules from %zu files (~%zu bytes)\n", millis(),
+                cssParser->ruleCount(), cssFiles.size(), cssParser->estimateMemoryUsage());
   return true;
 }
 
@@ -757,8 +757,8 @@ bool Epub::generateAllCovers(const std::function<void(int)>& progressCallback) c
         SdMan.openFileForWrite("EBP", getCoverBmpPath(false), coverBmp)) {
       const int targetWidth = 480;
       const int targetHeight = (480 * jpegHeight) / jpegWidth;
-      const bool success =
-          JpegToBmpConverter::jpegFileToBmpStreamWithSize(coverJpg, coverBmp, targetWidth, targetHeight, makeSubProgress(50, 75));
+      const bool success = JpegToBmpConverter::jpegFileToBmpStreamWithSize(coverJpg, coverBmp, targetWidth,
+                                                                           targetHeight, makeSubProgress(50, 75));
       coverJpg.close();
       coverBmp.close();
       if (!success) {
@@ -776,8 +776,8 @@ bool Epub::generateAllCovers(const std::function<void(int)>& progressCallback) c
         SdMan.openFileForWrite("EBP", getCoverBmpPath(true), coverBmp)) {
       const int targetHeight = 800;
       const int targetWidth = (800 * jpegWidth) / jpegHeight;
-      const bool success =
-          JpegToBmpConverter::jpegFileToBmpStreamWithSize(coverJpg, coverBmp, targetWidth, targetHeight, makeSubProgress(75, 100));
+      const bool success = JpegToBmpConverter::jpegFileToBmpStreamWithSize(coverJpg, coverBmp, targetWidth,
+                                                                           targetHeight, makeSubProgress(75, 100));
       coverJpg.close();
       coverBmp.close();
       if (!success) {

lib/Epub/Epub/Page.h

@@ -57,12 +57,12 @@ class Page {
  public:
   // the list of block index and line numbers on this page
   std::vector<std::shared_ptr<PageElement>> elements;
-  
+
   // Byte offset in source HTML where this page's content begins
   // Used for restoring reading position after re-indexing due to font/setting changes
   // This is stored in the Section file's LUT, not in Page serialization
   uint32_t firstContentOffset = 0;
-  
+
   void render(GfxRenderer& renderer, int fontId, int xOffset, int yOffset) const;
   bool serialize(FsFile& file) const;
   static std::unique_ptr<Page> deserialize(FsFile& file);

lib/Epub/Epub/Section.cpp

@@ -186,7 +186,7 @@ bool Section::createSectionFile(const int fontId, const float lineCompression, c
   }
   writeSectionFileHeader(fontId, lineCompression, extraParagraphSpacing, paragraphAlignment, viewportWidth,
                          viewportHeight, hyphenationEnabled);
-  
+
   // LUT entries: { filePosition, contentOffset } pairs
   struct LutEntry {
     uint32_t filePos;
@@ -202,8 +202,8 @@ bool Section::createSectionFile(const int fontId, const float lineCompression, c
         const uint32_t contentOffset = page->firstContentOffset;
         const uint32_t filePos = this->onPageComplete(std::move(page));
         lut.push_back({filePos, contentOffset});
-      }, progressFn,
-      epub->getCssParser());
+      },
+      progressFn, epub->getCssParser());
   Hyphenator::setPreferredLanguage(epub->getLanguage());
   success = visitor.parseAndBuildPages();
 
@@ -217,7 +217,7 @@ bool Section::createSectionFile(const int fontId, const float lineCompression, c
     // Add placeholder to LUT
     const uint32_t filePos = this->onPageComplete(std::move(placeholderPage));
     lut.push_back({filePos, 0});
-    
+
     // If we still have no pages, the placeholder creation failed
     if (pageCount == 0) {
       Serial.printf("[%lu] [SCT] Failed to create placeholder page\n", millis());
@@ -262,13 +262,13 @@ std::unique_ptr<Page> Section::loadPageFromSectionFile() {
   file.seek(HEADER_SIZE - sizeof(uint32_t));
   uint32_t lutOffset;
   serialization::readPod(file, lutOffset);
-  
+
   // LUT entries are now 8 bytes each: { filePos (4), contentOffset (4) }
   file.seek(lutOffset + LUT_ENTRY_SIZE * currentPage);
   uint32_t pagePos;
   serialization::readPod(file, pagePos);
   // Skip contentOffset for now - we don't need it when just loading the page
-  
+
   file.seek(pagePos);
 
   auto page = Page::deserialize(file);
@@ -300,15 +300,15 @@ int Section::findPageForContentOffset(uint32_t targetOffset) const {
 
   while (left <= right) {
     const int mid = left + (right - left) / 2;
-    
+
     // Read content offset for page 'mid'
     // LUT entry format: { filePos (4), contentOffset (4) }
     f.seek(lutOffset + LUT_ENTRY_SIZE * mid + sizeof(uint32_t));  // Skip filePos
     uint32_t midOffset;
     serialization::readPod(f, midOffset);
-    
+
     if (midOffset <= targetOffset) {
-      result = mid;  // This page could be the answer
+      result = mid;    // This page could be the answer
       left = mid + 1;  // Look for a later page that might also qualify
     } else {
       right = mid - 1;  // Look for an earlier page
@@ -322,7 +322,7 @@ int Section::findPageForContentOffset(uint32_t targetOffset) const {
     f.seek(lutOffset + LUT_ENTRY_SIZE * result + sizeof(uint32_t));
     uint32_t resultOffset;
     serialization::readPod(f, resultOffset);
-    
+
     while (result > 0) {
       f.seek(lutOffset + LUT_ENTRY_SIZE * (result - 1) + sizeof(uint32_t));
       uint32_t prevOffset;

lib/Epub/Epub/Section.h

@@ -36,7 +36,7 @@ class Section {
                          const std::function<void()>& progressSetupFn = nullptr,
                          const std::function<void(int)>& progressFn = nullptr);
   std::unique_ptr<Page> loadPageFromSectionFile();
-  
+
   // Methods for content offset-based position tracking
   // Used to restore reading position after re-indexing due to font/setting changes
   int findPageForContentOffset(uint32_t targetOffset) const;

lib/Epub/Epub/parsers/ChapterHtmlSlimParser.cpp

@@ -83,7 +83,7 @@ void ChapterHtmlSlimParser::updateEffectiveInlineStyle() {
 // Flush the contents of partWordBuffer to currentTextBlock
 void ChapterHtmlSlimParser::flushPartWordBuffer() {
   if (partWordBufferIndex == 0) return;
-  
+
   // Determine font style using effective styles
   EpdFontFamily::Style fontStyle = EpdFontFamily::REGULAR;
   if (effectiveBold && effectiveItalic) {
@@ -93,7 +93,7 @@ void ChapterHtmlSlimParser::flushPartWordBuffer() {
   } else if (effectiveItalic) {
     fontStyle = EpdFontFamily::ITALIC;
   }
-  
+
   // Flush the buffer
   partWordBuffer[partWordBufferIndex] = '\0';
   currentTextBlock->addWord(partWordBuffer, fontStyle, effectiveUnderline);
@@ -290,7 +290,7 @@ void XMLCALL ChapterHtmlSlimParser::startElement(void* userData, const XML_Char*
       } else {
         placeholder = "[Image unavailable]";
       }
-      
+
       self->startNewTextBlock(TextBlock::CENTER_ALIGN);
       self->italicUntilDepth = std::min(self->italicUntilDepth, self->depth);
       self->depth += 1;
@@ -478,7 +478,7 @@ void XMLCALL ChapterHtmlSlimParser::characterData(void* userData, const XML_Char
   if (self->skipUntilDepth < self->depth) {
     return;
   }
-  
+
   // Capture byte offset of this character data for page position tracking
   if (self->xmlParser) {
     self->lastCharDataOffset = XML_GetCurrentByteIndex(self->xmlParser);
@@ -647,7 +647,7 @@ bool ChapterHtmlSlimParser::parseAndBuildPages() {
   const size_t totalSize = file.size();
   size_t bytesRead = 0;
   int lastProgress = -1;
-  
+
   // Initialize offset tracking - first page starts at offset 0
   currentPageStartOffset = 0;
   lastCharDataOffset = 0;
@@ -739,7 +739,7 @@ void ChapterHtmlSlimParser::addLineToPage(std::shared_ptr<TextBlock> line) {
       currentPage->firstContentOffset = static_cast<uint32_t>(currentPageStartOffset);
     }
     completePageFn(std::move(currentPage));
-    
+
     // Start new page - offset will be set when first content is added
     currentPage.reset(new Page());
     currentPageStartOffset = lastCharDataOffset;  // Use offset from when content was parsed

lib/Epub/Epub/parsers/ChapterHtmlSlimParser.h

@@ -58,11 +58,11 @@ class ChapterHtmlSlimParser {
   bool effectiveBold = false;
   bool effectiveItalic = false;
   bool effectiveUnderline = false;
-  
+
   // Byte offset tracking for position restoration after re-indexing
-  XML_Parser xmlParser = nullptr;      // Store parser for getting current byte index
-  size_t currentPageStartOffset = 0;   // Byte offset when current page was started
-  size_t lastCharDataOffset = 0;       // Byte offset of last character data (captured during parsing)
+  XML_Parser xmlParser = nullptr;     // Store parser for getting current byte index
+  size_t currentPageStartOffset = 0;  // Byte offset when current page was started
+  size_t lastCharDataOffset = 0;      // Byte offset of last character data (captured during parsing)
 
   void updateEffectiveInlineStyle();
   void startNewTextBlock(TextBlock::Style style);