Add retry logic and progress bar for chapter indexing (#128)

## Summary

* **What is the goal of this PR?**

Improve reliability and user experience during chapter indexing by
adding retry logic for SD card operations and a visual progress bar.

* **What changes are included?**

- **Retry logic**: Add 3 retry attempts with 50ms delay for ZIP to SD
card streaming to handle timing issues after display refresh
- **Progress bar**: Display a visual progress bar (0-100%) during
chapter indexing based on file read progress, updating every 10% to
balance responsiveness with e-ink display limitations

## Additional Context

* **Problem observed**: When navigating quickly through books with many
chapters (before chapter titles finish rendering), the "Indexing..."
screen would appear frozen. Checking the serial log revealed the
operation had silently failed, but the UI showed no indication of this.
Users would likely assume the device had crashed. Pressing the next
button again would resume operation, but this behavior was confusing and
unexpected.

* **Solution**:
- Retry logic handles transient SD card timing failures automatically,
so users don't need to manually retry
- Progress bar provides visual feedback so users know indexing is
actively working (not frozen)

* **Why timing issues occur**: After display refresh operations, there
can be timing conflicts when immediately starting SD card write
operations. This is more likely to happen when rapidly navigating
through chapters.

* **Progress bar design**: Updates every 10% to avoid excessive e-ink
refreshes while still providing meaningful feedback during long indexing
operations (especially for large chapters with CJK characters).

* **Performance**: Minimal overhead - progress calculation is simple
byte counting, and display updates use `FAST_REFRESH` mode.

lib/Epub/Epub/ParsedText.cpp

@@ -106,6 +106,18 @@ std::vector<size_t> ParsedText::computeLineBreaks(const int pageWidth, const int
         ans[i] = j;  // j is the index of the last word in this optimal line
       }
     }
+
+    // Handle oversized word: if no valid configuration found, force single-word line
+    // This prevents cascade failure where one oversized word breaks all preceding words
+    if (dp[i] == MAX_COST) {
+      ans[i] = i;  // Just this word on its own line
+      // Inherit cost from next word to allow subsequent words to find valid configurations
+      if (i + 1 < static_cast<int>(totalWordCount)) {
+        dp[i] = dp[i + 1];
+      } else {
+        dp[i] = 0;
+      }
+    }
   }
 
   // Stores the index of the word that starts the next line (last_word_index + 1)

lib/Epub/Epub/Section.cpp

@@ -115,26 +115,56 @@ bool Section::clearCache() const {
 
 bool Section::persistPageDataToSD(const int fontId, const float lineCompression, const int marginTop,
                                   const int marginRight, const int marginBottom, const int marginLeft,
-                                  const bool extraParagraphSpacing) {
+                                  const bool extraParagraphSpacing, const std::function<void()>& progressSetupFn,
+                                  const std::function<void(int)>& progressFn) {
+  constexpr size_t MIN_SIZE_FOR_PROGRESS = 50 * 1024;  // 50KB
   const auto localPath = epub->getSpineItem(spineIndex).href;
   const auto tmpHtmlPath = epub->getCachePath() + "/.tmp_" + std::to_string(spineIndex) + ".html";
+
+  // Retry logic for SD card timing issues
+  bool success = false;
+  size_t fileSize = 0;
+  for (int attempt = 0; attempt < 3 && !success; attempt++) {
+    if (attempt > 0) {
+      Serial.printf("[%lu] [SCT] Retrying stream (attempt %d)...\n", millis(), attempt + 1);
+      delay(50);  // Brief delay before retry
+    }
+
+    // Remove any incomplete file from previous attempt before retrying
+    if (SD.exists(tmpHtmlPath.c_str())) {
+      SD.remove(tmpHtmlPath.c_str());
+    }
+
     File tmpHtml;
     if (!FsHelpers::openFileForWrite("SCT", tmpHtmlPath, tmpHtml)) {
-    return false;
+      continue;
     }
-  bool success = epub->readItemContentsToStream(localPath, tmpHtml, 1024);
+    success = epub->readItemContentsToStream(localPath, tmpHtml, 1024);
+    fileSize = tmpHtml.size();
     tmpHtml.close();
 
+    // If streaming failed, remove the incomplete file immediately
+    if (!success && SD.exists(tmpHtmlPath.c_str())) {
+      SD.remove(tmpHtmlPath.c_str());
+      Serial.printf("[%lu] [SCT] Removed incomplete temp file after failed attempt\n", millis());
+    }
+  }
+
   if (!success) {
-    Serial.printf("[%lu] [SCT] Failed to stream item contents to temp file\n", millis());
+    Serial.printf("[%lu] [SCT] Failed to stream item contents to temp file after retries\n", millis());
     return false;
   }
 
-  Serial.printf("[%lu] [SCT] Streamed temp HTML to %s\n", millis(), tmpHtmlPath.c_str());
+  Serial.printf("[%lu] [SCT] Streamed temp HTML to %s (%d bytes)\n", millis(), tmpHtmlPath.c_str(), fileSize);
 
-  ChapterHtmlSlimParser visitor(tmpHtmlPath, renderer, fontId, lineCompression, marginTop, marginRight, marginBottom,
-                                marginLeft, extraParagraphSpacing,
-                                [this](std::unique_ptr<Page> page) { this->onPageComplete(std::move(page)); });
+  // Only show progress bar for larger chapters where rendering overhead is worth it
+  if (progressSetupFn && fileSize >= MIN_SIZE_FOR_PROGRESS) {
+    progressSetupFn();
+  }
+
+  ChapterHtmlSlimParser visitor(
+      tmpHtmlPath, renderer, fontId, lineCompression, marginTop, marginRight, marginBottom, marginLeft,
+      extraParagraphSpacing, [this](std::unique_ptr<Page> page) { this->onPageComplete(std::move(page)); }, progressFn);
   success = visitor.parseAndBuildPages();
 
   SD.remove(tmpHtmlPath.c_str());

lib/Epub/Epub/Section.h

@@ -1,4 +1,5 @@
 #pragma once
+#include <functional>
 #include <memory>
 
 #include "Epub.h"
@@ -31,6 +32,8 @@ class Section {
   void setupCacheDir() const;
   bool clearCache() const;
   bool persistPageDataToSD(int fontId, float lineCompression, int marginTop, int marginRight, int marginBottom,
-                           int marginLeft, bool extraParagraphSpacing);
+                           int marginLeft, bool extraParagraphSpacing,
+                           const std::function<void()>& progressSetupFn = nullptr,
+                           const std::function<void(int)>& progressFn = nullptr);
   std::unique_ptr<Page> loadPageFromSD() const;
 };

lib/Epub/Epub/blocks/TextBlock.cpp

@@ -4,11 +4,18 @@
 #include <Serialization.h>
 
 void TextBlock::render(const GfxRenderer& renderer, const int fontId, const int x, const int y) const {
+  // Validate iterator bounds before rendering
+  if (words.size() != wordXpos.size() || words.size() != wordStyles.size()) {
+    Serial.printf("[%lu] [TXB] Render skipped: size mismatch (words=%u, xpos=%u, styles=%u)\n", millis(),
+                  (uint32_t)words.size(), (uint32_t)wordXpos.size(), (uint32_t)wordStyles.size());
+    return;
+  }
+
   auto wordIt = words.begin();
   auto wordStylesIt = wordStyles.begin();
   auto wordXposIt = wordXpos.begin();
 
-  for (int i = 0; i < words.size(); i++) {
+  for (size_t i = 0; i < words.size(); i++) {
     renderer.drawText(fontId, *wordXposIt + x, y, wordIt->c_str(), true, *wordStylesIt);
 
     std::advance(wordIt, 1);
@@ -46,6 +53,13 @@ std::unique_ptr<TextBlock> TextBlock::deserialize(File& file) {
 
   // words
   serialization::readPod(file, wc);
+
+  // Sanity check: prevent allocation of unreasonably large lists (max 10000 words per block)
+  if (wc > 10000) {
+    Serial.printf("[%lu] [TXB] Deserialization failed: word count %u exceeds maximum\n", millis(), wc);
+    return nullptr;
+  }
+
   words.resize(wc);
   for (auto& w : words) serialization::readString(file, w);
 
@@ -59,6 +73,13 @@ std::unique_ptr<TextBlock> TextBlock::deserialize(File& file) {
   wordStyles.resize(sc);
   for (auto& s : wordStyles) serialization::readPod(file, s);
 
+  // Validate data consistency: all three lists must have the same size
+  if (wc != xc || wc != sc) {
+    Serial.printf("[%lu] [TXB] Deserialization failed: size mismatch (words=%u, xpos=%u, styles=%u)\n", millis(), wc,
+                  xc, sc);
+    return nullptr;
+  }
+
   // style
   serialization::readPod(file, style);
 

lib/Epub/Epub/parsers/ChapterHtmlSlimParser.cpp

@@ -11,6 +11,9 @@
 const char* HEADER_TAGS[] = {"h1", "h2", "h3", "h4", "h5", "h6"};
 constexpr int NUM_HEADER_TAGS = sizeof(HEADER_TAGS) / sizeof(HEADER_TAGS[0]);
 
+// Minimum file size (in bytes) to show progress bar - smaller chapters don't benefit from it
+constexpr size_t MIN_SIZE_FOR_PROGRESS = 50 * 1024;  // 50KB
+
 const char* BLOCK_TAGS[] = {"p", "li", "div", "br", "blockquote"};
 constexpr int NUM_BLOCK_TAGS = sizeof(BLOCK_TAGS) / sizeof(BLOCK_TAGS[0]);
 
@@ -221,6 +224,11 @@ bool ChapterHtmlSlimParser::parseAndBuildPages() {
     return false;
   }
 
+  // Get file size for progress calculation
+  const size_t totalSize = file.size();
+  size_t bytesRead = 0;
+  int lastProgress = -1;
+
   XML_SetUserData(parser, this);
   XML_SetElementHandler(parser, startElement, endElement);
   XML_SetCharacterDataHandler(parser, characterData);
@@ -249,6 +257,17 @@ bool ChapterHtmlSlimParser::parseAndBuildPages() {
       return false;
     }
 
+    // Update progress (call every 10% change to avoid too frequent updates)
+    // Only show progress for larger chapters where rendering overhead is worth it
+    bytesRead += len;
+    if (progressFn && totalSize >= MIN_SIZE_FOR_PROGRESS) {
+      const int progress = static_cast<int>((bytesRead * 100) / totalSize);
+      if (lastProgress / 10 != progress / 10) {
+        lastProgress = progress;
+        progressFn(progress);
+      }
+    }
+
     done = file.available() == 0;
 
     if (XML_ParseBuffer(parser, static_cast<int>(len), done) == XML_STATUS_ERROR) {

lib/Epub/Epub/parsers/ChapterHtmlSlimParser.h

@@ -18,6 +18,7 @@ class ChapterHtmlSlimParser {
   const std::string& filepath;
   GfxRenderer& renderer;
   std::function<void(std::unique_ptr<Page>)> completePageFn;
+  std::function<void(int)> progressFn;  // Progress callback (0-100)
   int depth = 0;
   int skipUntilDepth = INT_MAX;
   int boldUntilDepth = INT_MAX;
@@ -48,7 +49,8 @@ class ChapterHtmlSlimParser {
   explicit ChapterHtmlSlimParser(const std::string& filepath, GfxRenderer& renderer, const int fontId,
                                  const float lineCompression, const int marginTop, const int marginRight,
                                  const int marginBottom, const int marginLeft, const bool extraParagraphSpacing,
-                                 const std::function<void(std::unique_ptr<Page>)>& completePageFn)
+                                 const std::function<void(std::unique_ptr<Page>)>& completePageFn,
+                                 const std::function<void(int)>& progressFn = nullptr)
       : filepath(filepath),
         renderer(renderer),
         fontId(fontId),
@@ -58,7 +60,8 @@ class ChapterHtmlSlimParser {
         marginBottom(marginBottom),
         marginLeft(marginLeft),
         extraParagraphSpacing(extraParagraphSpacing),
-        completePageFn(completePageFn) {}
+        completePageFn(completePageFn),
+        progressFn(progressFn) {}
   ~ChapterHtmlSlimParser() = default;
   bool parseAndBuildPages();
   void addLineToPage(std::shared_ptr<TextBlock> line);

src/activities/reader/EpubReaderActivity.cpp

@@ -227,23 +227,51 @@ void EpubReaderActivity::renderScreen() {
                                     SETTINGS.extraParagraphSpacing)) {
       Serial.printf("[%lu] [ERS] Cache not found, building...\n", millis());
 
-      {
+      // Progress bar dimensions
+      constexpr int barWidth = 200;
+      constexpr int barHeight = 10;
+      constexpr int boxMargin = 20;
       const int textWidth = renderer.getTextWidth(READER_FONT_ID, "Indexing...");
-        constexpr int margin = 20;
-        const int x = (GfxRenderer::getScreenWidth() - textWidth - margin * 2) / 2;
-        constexpr int y = 50;
-        const int w = textWidth + margin * 2;
-        const int h = renderer.getLineHeight(READER_FONT_ID) + margin * 2;
-        renderer.fillRect(x, y, w, h, false);
-        renderer.drawText(READER_FONT_ID, x + margin, y + margin, "Indexing...");
-        renderer.drawRect(x + 5, y + 5, w - 10, h - 10);
+      const int boxWidthWithBar = (barWidth > textWidth ? barWidth : textWidth) + boxMargin * 2;
+      const int boxWidthNoBar = textWidth + boxMargin * 2;
+      const int boxHeightWithBar = renderer.getLineHeight(READER_FONT_ID) + barHeight + boxMargin * 3;
+      const int boxHeightNoBar = renderer.getLineHeight(READER_FONT_ID) + boxMargin * 2;
+      const int boxXWithBar = (GfxRenderer::getScreenWidth() - boxWidthWithBar) / 2;
+      const int boxXNoBar = (GfxRenderer::getScreenWidth() - boxWidthNoBar) / 2;
+      constexpr int boxY = 50;
+      const int barX = boxXWithBar + (boxWidthWithBar - barWidth) / 2;
+      const int barY = boxY + renderer.getLineHeight(READER_FONT_ID) + boxMargin * 2;
+
+      // Always show "Indexing..." text first
+      {
+        renderer.fillRect(boxXNoBar, boxY, boxWidthNoBar, boxHeightNoBar, false);
+        renderer.drawText(READER_FONT_ID, boxXNoBar + boxMargin, boxY + boxMargin, "Indexing...");
+        renderer.drawRect(boxXNoBar + 5, boxY + 5, boxWidthNoBar - 10, boxHeightNoBar - 10);
         renderer.displayBuffer();
         pagesUntilFullRefresh = 0;
       }
 
       section->setupCacheDir();
+
+      // Setup callback - only called for chapters >= 50KB, redraws with progress bar
+      auto progressSetup = [this, boxXWithBar, boxWidthWithBar, boxHeightWithBar, boxMargin, barX, barY, barWidth,
+                            barHeight]() {
+        renderer.fillRect(boxXWithBar, boxY, boxWidthWithBar, boxHeightWithBar, false);
+        renderer.drawText(READER_FONT_ID, boxXWithBar + boxMargin, boxY + boxMargin, "Indexing...");
+        renderer.drawRect(boxXWithBar + 5, boxY + 5, boxWidthWithBar - 10, boxHeightWithBar - 10);
+        renderer.drawRect(barX, barY, barWidth, barHeight);
+        renderer.displayBuffer();
+      };
+
+      // Progress callback to update progress bar
+      auto progressCallback = [this, barX, barY, barWidth, barHeight](int progress) {
+        const int fillWidth = (barWidth - 2) * progress / 100;
+        renderer.fillRect(barX + 1, barY + 1, fillWidth, barHeight - 2, true);
+        renderer.displayBuffer(EInkDisplay::FAST_REFRESH);
+      };
+
       if (!section->persistPageDataToSD(READER_FONT_ID, lineCompression, marginTop, marginRight, marginBottom,
-                                        marginLeft, SETTINGS.extraParagraphSpacing)) {
+                                        marginLeft, SETTINGS.extraParagraphSpacing, progressSetup, progressCallback)) {
         Serial.printf("[%lu] [ERS] Failed to persist page data to SD\n", millis());
         section.reset();
         return;