fix: Port upstream cover extraction fallback and outline improvements

Port PR #838 (epub cover fallback logic) and PR #907 (cover outlines):

- Add fallback cover filename probing when EPUB metadata lacks cover info
- Case-insensitive extension checking for cover images
- Detect and re-generate corrupt/empty thumbnail BMPs
- Always draw outline rect on cover tiles for legibility (PR #907)
- Upgrade Storage.exists() checks to Epub::isValidThumbnailBmp()
- Fallback chain: Real Cover → PlaceholderCoverGenerator → X-pattern marker
- Add epub.load retry logic (cache-only first, then full build)
- Adapt upstream Serial.printf calls to LOG_DBG/LOG_ERR macros

Co-authored-by: Cursor <cursoragent@cursor.com>

README.md

@@ -51,7 +51,7 @@ For more details about the scope of the project, see the [SCOPE.md](SCOPE.md) do
 
 ### Web (latest firmware)
 
-1. Connect your Xteink X4 to your computer via USB-C
+1. Connect your Xteink X4 to your computer via USB-C and wake/unlock the device
 2. Go to https://xteink.dve.al/ and click "Flash CrossPoint firmware"
 
 To revert back to the official firmware, you can flash the latest official firmware from https://xteink.dve.al/, or swap

USER_GUIDE.md

@@ -230,6 +230,7 @@ Accessible by pressing **Confirm** while inside a book.
 Please note that this firmware is currently in active development. The following features are **not yet supported** but are planned for future updates:
 
 * **Images:** Embedded images in e-books will not render.
+* **Cover Images:** Large cover images embedded into EPUB require several seconds (~10s for ~2000 pixel tall image) to convert for sleep screen and home screen thumbnail. Consider optimizing the EPUB with e.g. https://github.com/bigbag/epub-to-xtc-converter to speed this up.
 
 ---
 
@@ -242,3 +243,5 @@ pio device monitor
 ```
 
 If the device is stuck in a bootloop, press and release the Reset button. Then, press and hold on to the configured Back button and the Power Button to boot to the Home Screen.
+
+There can be issues with broken cache or config. In this case, delete the `.crosspoint` directory on your SD card (or consider deleting only `settings.bin`, `state.bin`, or `epub_*` cache directories in the `.crosspoint/` folder).

bin/clang-format-fix

@@ -13,7 +13,9 @@ fi
 # --modified: files tracked by git that have been modified (staged or unstaged)
 # --exclude-standard: ignores files in .gitignore
 # Additionally exclude files in 'lib/EpdFont/builtinFonts/' as they are script-generated.
+# Also exclude files in 'lib/Epub/Epub/hyphenation/generated/' as they are script-generated.
 git ls-files  --exclude-standard ${GIT_LS_FILES_FLAGS} \
     | grep -E '\.(c|cpp|h|hpp)$' \
     | grep -v -E '^lib/EpdFont/builtinFonts/' \
+    | grep -v -E '^lib/Epub/Epub/hyphenation/generated/' \
     | xargs -r clang-format -style=file -i

lib/EpdFont/builtinFonts/all.h

@@ -1,5 +1,6 @@
 #pragma once
 
+#ifndef OMIT_BOOKERLY
 #include <builtinFonts/bookerly_12_bold.h>
 #include <builtinFonts/bookerly_12_bolditalic.h>
 #include <builtinFonts/bookerly_12_italic.h>
@@ -16,7 +17,10 @@
 #include <builtinFonts/bookerly_18_bolditalic.h>
 #include <builtinFonts/bookerly_18_italic.h>
 #include <builtinFonts/bookerly_18_regular.h>
+#endif  // OMIT_BOOKERLY
+
 #include <builtinFonts/notosans_8_regular.h>
+#ifndef OMIT_NOTOSANS
 #include <builtinFonts/notosans_12_bold.h>
 #include <builtinFonts/notosans_12_bolditalic.h>
 #include <builtinFonts/notosans_12_italic.h>
@@ -33,6 +37,9 @@
 #include <builtinFonts/notosans_18_bolditalic.h>
 #include <builtinFonts/notosans_18_italic.h>
 #include <builtinFonts/notosans_18_regular.h>
+#endif  // OMIT_NOTOSANS
+
+#ifndef OMIT_OPENDYSLEXIC
 #include <builtinFonts/opendyslexic_10_bold.h>
 #include <builtinFonts/opendyslexic_10_bolditalic.h>
 #include <builtinFonts/opendyslexic_10_italic.h>
@@ -49,6 +56,8 @@
 #include <builtinFonts/opendyslexic_8_bolditalic.h>
 #include <builtinFonts/opendyslexic_8_italic.h>
 #include <builtinFonts/opendyslexic_8_regular.h>
+#endif  // OMIT_OPENDYSLEXIC
+
 #include <builtinFonts/ubuntu_10_bold.h>
 #include <builtinFonts/ubuntu_10_regular.h>
 #include <builtinFonts/ubuntu_12_bold.h>

lib/Epub/Epub.cpp

@@ -1,11 +1,14 @@
 #include "Epub.h"
 
 #include <FsHelpers.h>
+#include <HalDisplay.h>
 #include <HalStorage.h>
-#include <HardwareSerial.h>
 #include <JpegToBmpConverter.h>
+#include <Logging.h>
 #include <ZipFile.h>
 
+#include <algorithm>
+
 #include "Epub/parsers/ContainerParser.h"
 #include "Epub/parsers/ContentOpfParser.h"
 #include "Epub/parsers/TocNavParser.h"
@@ -17,7 +20,7 @@ bool Epub::findContentOpfFile(std::string* contentOpfFile) const {
 
   // Get file size without loading it all into heap
   if (!getItemSize(containerPath, &containerSize)) {
-    Serial.printf("[%lu] [EBP] Could not find or size META-INF/container.xml\n", millis());
+    LOG_ERR("EBP", "Could not find or size META-INF/container.xml");
     return false;
   }
 
@@ -29,13 +32,13 @@ bool Epub::findContentOpfFile(std::string* contentOpfFile) const {
 
   // Stream read (reusing your existing stream logic)
   if (!readItemContentsToStream(containerPath, containerParser, 512)) {
-    Serial.printf("[%lu] [EBP] Could not read META-INF/container.xml\n", millis());
+    LOG_ERR("EBP", "Could not read META-INF/container.xml");
     return false;
   }
 
   // Extract the result
   if (containerParser.fullPath.empty()) {
-    Serial.printf("[%lu] [EBP] Could not find valid rootfile in container.xml\n", millis());
+    LOG_ERR("EBP", "Could not find valid rootfile in container.xml");
     return false;
   }
 
@@ -46,28 +49,28 @@ bool Epub::findContentOpfFile(std::string* contentOpfFile) const {
 bool Epub::parseContentOpf(BookMetadataCache::BookMetadata& bookMetadata) {
   std::string contentOpfFilePath;
   if (!findContentOpfFile(&contentOpfFilePath)) {
-    Serial.printf("[%lu] [EBP] Could not find content.opf in zip\n", millis());
+    LOG_ERR("EBP", "Could not find content.opf in zip");
     return false;
   }
 
   contentBasePath = contentOpfFilePath.substr(0, contentOpfFilePath.find_last_of('/') + 1);
 
-  Serial.printf("[%lu] [EBP] Parsing content.opf: %s\n", millis(), contentOpfFilePath.c_str());
+  LOG_DBG("EBP", "Parsing content.opf: %s", contentOpfFilePath.c_str());
 
   size_t contentOpfSize;
   if (!getItemSize(contentOpfFilePath, &contentOpfSize)) {
-    Serial.printf("[%lu] [EBP] Could not get size of content.opf\n", millis());
+    LOG_ERR("EBP", "Could not get size of content.opf");
     return false;
   }
 
   ContentOpfParser opfParser(getCachePath(), getBasePath(), contentOpfSize, bookMetadataCache.get());
   if (!opfParser.setup()) {
-    Serial.printf("[%lu] [EBP] Could not setup content.opf parser\n", millis());
+    LOG_ERR("EBP", "Could not setup content.opf parser");
     return false;
   }
 
   if (!readItemContentsToStream(contentOpfFilePath, opfParser, 1024)) {
-    Serial.printf("[%lu] [EBP] Could not read content.opf\n", millis());
+    LOG_ERR("EBP", "Could not read content.opf");
     return false;
   }
 
@@ -90,18 +93,18 @@ bool Epub::parseContentOpf(BookMetadataCache::BookMetadata& bookMetadata) {
     cssFiles = opfParser.cssFiles;
   }
 
-  Serial.printf("[%lu] [EBP] Successfully parsed content.opf\n", millis());
+  LOG_DBG("EBP", "Successfully parsed content.opf");
   return true;
 }
 
 bool Epub::parseTocNcxFile() const {
   // the ncx file should have been specified in the content.opf file
   if (tocNcxItem.empty()) {
-    Serial.printf("[%lu] [EBP] No ncx file specified\n", millis());
+    LOG_DBG("EBP", "No ncx file specified");
     return false;
   }
 
-  Serial.printf("[%lu] [EBP] Parsing toc ncx file: %s\n", millis(), tocNcxItem.c_str());
+  LOG_DBG("EBP", "Parsing toc ncx file: %s", tocNcxItem.c_str());
 
   const auto tmpNcxPath = getCachePath() + "/toc.ncx";
   FsFile tempNcxFile;
@@ -118,14 +121,14 @@ bool Epub::parseTocNcxFile() const {
   TocNcxParser ncxParser(contentBasePath, ncxSize, bookMetadataCache.get());
 
   if (!ncxParser.setup()) {
-    Serial.printf("[%lu] [EBP] Could not setup toc ncx parser\n", millis());
+    LOG_ERR("EBP", "Could not setup toc ncx parser");
     tempNcxFile.close();
     return false;
   }
 
   const auto ncxBuffer = static_cast<uint8_t*>(malloc(1024));
   if (!ncxBuffer) {
-    Serial.printf("[%lu] [EBP] Could not allocate memory for toc ncx parser\n", millis());
+    LOG_ERR("EBP", "Could not allocate memory for toc ncx parser");
     tempNcxFile.close();
     return false;
   }
@@ -136,7 +139,7 @@ bool Epub::parseTocNcxFile() const {
     const auto processedSize = ncxParser.write(ncxBuffer, readSize);
 
     if (processedSize != readSize) {
-      Serial.printf("[%lu] [EBP] Could not process all toc ncx data\n", millis());
+      LOG_ERR("EBP", "Could not process all toc ncx data");
       free(ncxBuffer);
       tempNcxFile.close();
       return false;
@@ -147,18 +150,18 @@ bool Epub::parseTocNcxFile() const {
   tempNcxFile.close();
   Storage.remove(tmpNcxPath.c_str());
 
-  Serial.printf("[%lu] [EBP] Parsed TOC items\n", millis());
+  LOG_DBG("EBP", "Parsed TOC items");
   return true;
 }
 
 bool Epub::parseTocNavFile() const {
   // the nav file should have been specified in the content.opf file (EPUB 3)
   if (tocNavItem.empty()) {
-    Serial.printf("[%lu] [EBP] No nav file specified\n", millis());
+    LOG_DBG("EBP", "No nav file specified");
     return false;
   }
 
-  Serial.printf("[%lu] [EBP] Parsing toc nav file: %s\n", millis(), tocNavItem.c_str());
+  LOG_DBG("EBP", "Parsing toc nav file: %s", tocNavItem.c_str());
 
   const auto tmpNavPath = getCachePath() + "/toc.nav";
   FsFile tempNavFile;
@@ -178,13 +181,13 @@ bool Epub::parseTocNavFile() const {
   TocNavParser navParser(navContentBasePath, navSize, bookMetadataCache.get());
 
   if (!navParser.setup()) {
-    Serial.printf("[%lu] [EBP] Could not setup toc nav parser\n", millis());
+    LOG_ERR("EBP", "Could not setup toc nav parser");
     return false;
   }
 
   const auto navBuffer = static_cast<uint8_t*>(malloc(1024));
   if (!navBuffer) {
-    Serial.printf("[%lu] [EBP] Could not allocate memory for toc nav parser\n", millis());
+    LOG_ERR("EBP", "Could not allocate memory for toc nav parser");
     return false;
   }
 
@@ -193,7 +196,7 @@ bool Epub::parseTocNavFile() const {
     const auto processedSize = navParser.write(navBuffer, readSize);
 
     if (processedSize != readSize) {
-      Serial.printf("[%lu] [EBP] Could not process all toc nav data\n", millis());
+      LOG_ERR("EBP", "Could not process all toc nav data");
       free(navBuffer);
       tempNavFile.close();
       return false;
@@ -204,46 +207,30 @@ bool Epub::parseTocNavFile() const {
   tempNavFile.close();
   Storage.remove(tmpNavPath.c_str());
 
-  Serial.printf("[%lu] [EBP] Parsed TOC nav items\n", millis());
+  LOG_DBG("EBP", "Parsed TOC nav items");
   return true;
 }
 
-std::string Epub::getCssRulesCache() const { return cachePath + "/css_rules.cache"; }
-
-bool Epub::loadCssRulesFromCache() const {
-  FsFile cssCacheFile;
-  if (Storage.openFileForRead("EBP", getCssRulesCache(), cssCacheFile)) {
-    if (cssParser->loadFromCache(cssCacheFile)) {
-      cssCacheFile.close();
-      Serial.printf("[%lu] [EBP] Loaded CSS rules from cache\n", millis());
-      return true;
-    }
-    cssCacheFile.close();
-    Serial.printf("[%lu] [EBP] CSS cache invalid, reparsing\n", millis());
-  }
-  return false;
-}
-
 void Epub::parseCssFiles() const {
   if (cssFiles.empty()) {
-    Serial.printf("[%lu] [EBP] No CSS files to parse, but CssParser created for inline styles\n", millis());
+    LOG_DBG("EBP", "No CSS files to parse, but CssParser created for inline styles");
   }
 
-  // Try to load from CSS cache first
-  if (!loadCssRulesFromCache()) {
-    // Cache miss - parse CSS files
+  // See if we have a cached version of the CSS rules
+  if (!cssParser->hasCache()) {
+    // No cache yet - parse CSS files
     for (const auto& cssPath : cssFiles) {
-      Serial.printf("[%lu] [EBP] Parsing CSS file: %s\n", millis(), cssPath.c_str());
+      LOG_DBG("EBP", "Parsing CSS file: %s", cssPath.c_str());
 
       // Extract CSS file to temp location
       const auto tmpCssPath = getCachePath() + "/.tmp.css";
       FsFile tempCssFile;
       if (!Storage.openFileForWrite("EBP", tmpCssPath, tempCssFile)) {
-        Serial.printf("[%lu] [EBP] Could not create temp CSS file\n", millis());
+        LOG_ERR("EBP", "Could not create temp CSS file");
         continue;
       }
       if (!readItemContentsToStream(cssPath, tempCssFile, 1024)) {
-        Serial.printf("[%lu] [EBP] Could not read CSS file: %s\n", millis(), cssPath.c_str());
+        LOG_ERR("EBP", "Could not read CSS file: %s", cssPath.c_str());
         tempCssFile.close();
         Storage.remove(tmpCssPath.c_str());
         continue;
@@ -252,7 +239,7 @@ void Epub::parseCssFiles() const {
 
       // Parse the CSS file
       if (!Storage.openFileForRead("EBP", tmpCssPath, tempCssFile)) {
-        Serial.printf("[%lu] [EBP] Could not open temp CSS file for reading\n", millis());
+        LOG_ERR("EBP", "Could not open temp CSS file for reading");
         Storage.remove(tmpCssPath.c_str());
         continue;
       }
@@ -262,38 +249,36 @@ void Epub::parseCssFiles() const {
     }
 
     // Save to cache for next time
-    FsFile cssCacheFile;
-    if (Storage.openFileForWrite("EBP", getCssRulesCache(), cssCacheFile)) {
-      cssParser->saveToCache(cssCacheFile);
-      cssCacheFile.close();
+    if (!cssParser->saveToCache()) {
+      LOG_ERR("EBP", "Failed to save CSS rules to cache");
     }
+    cssParser->clear();
 
-    Serial.printf("[%lu] [EBP] Loaded %zu CSS style rules from %zu files\n", millis(), cssParser->ruleCount(),
-                  cssFiles.size());
+    LOG_DBG("EBP", "Loaded %zu CSS style rules from %zu files", cssParser->ruleCount(), cssFiles.size());
   }
 }
 
 // load in the meta data for the epub file
 bool Epub::load(const bool buildIfMissing, const bool skipLoadingCss) {
-  Serial.printf("[%lu] [EBP] Loading ePub: %s\n", millis(), filepath.c_str());
+  LOG_DBG("EBP", "Loading ePub: %s", filepath.c_str());
 
   // Initialize spine/TOC cache
   bookMetadataCache.reset(new BookMetadataCache(cachePath));
   // Always create CssParser - needed for inline style parsing even without CSS files
-  cssParser.reset(new CssParser());
+  cssParser.reset(new CssParser(cachePath));
 
   // Try to load existing cache first
   if (bookMetadataCache->load()) {
-    if (!skipLoadingCss && !loadCssRulesFromCache()) {
-      Serial.printf("[%lu] [EBP] Warning: CSS rules cache not found, attempting to parse CSS files\n", millis());
+    if (!skipLoadingCss && !cssParser->hasCache()) {
+      LOG_DBG("EBP", "Warning: CSS rules cache not found, attempting to parse CSS files");
       // to get CSS file list
       if (!parseContentOpf(bookMetadataCache->coreMetadata)) {
-        Serial.printf("[%lu] [EBP] Could not parse content.opf from cached bookMetadata for CSS files\n", millis());
+        LOG_ERR("EBP", "Could not parse content.opf from cached bookMetadata for CSS files");
         // continue anyway - book will work without CSS and we'll still load any inline style CSS
       }
       parseCssFiles();
     }
-    Serial.printf("[%lu] [EBP] Loaded ePub: %s\n", millis(), filepath.c_str());
+    LOG_DBG("EBP", "Loaded ePub: %s", filepath.c_str());
     return true;
   }
 
@@ -303,14 +288,14 @@ bool Epub::load(const bool buildIfMissing, const bool skipLoadingCss) {
   }
 
   // Cache doesn't exist or is invalid, build it
-  Serial.printf("[%lu] [EBP] Cache not found, building spine/TOC cache\n", millis());
+  LOG_DBG("EBP", "Cache not found, building spine/TOC cache");
   setupCacheDir();
 
   const uint32_t indexingStart = millis();
 
   // Begin building cache - stream entries to disk immediately
   if (!bookMetadataCache->beginWrite()) {
-    Serial.printf("[%lu] [EBP] Could not begin writing cache\n", millis());
+    LOG_ERR("EBP", "Could not begin writing cache");
     return false;
   }
 
@@ -318,23 +303,23 @@ bool Epub::load(const bool buildIfMissing, const bool skipLoadingCss) {
   const uint32_t opfStart = millis();
   BookMetadataCache::BookMetadata bookMetadata;
   if (!bookMetadataCache->beginContentOpfPass()) {
-    Serial.printf("[%lu] [EBP] Could not begin writing content.opf pass\n", millis());
+    LOG_ERR("EBP", "Could not begin writing content.opf pass");
     return false;
   }
   if (!parseContentOpf(bookMetadata)) {
-    Serial.printf("[%lu] [EBP] Could not parse content.opf\n", millis());
+    LOG_ERR("EBP", "Could not parse content.opf");
     return false;
   }
   if (!bookMetadataCache->endContentOpfPass()) {
-    Serial.printf("[%lu] [EBP] Could not end writing content.opf pass\n", millis());
+    LOG_ERR("EBP", "Could not end writing content.opf pass");
     return false;
   }
-  Serial.printf("[%lu] [EBP] OPF pass completed in %lu ms\n", millis(), millis() - opfStart);
+  LOG_DBG("EBP", "OPF pass completed in %lu ms", millis() - opfStart);
 
   // TOC Pass - try EPUB 3 nav first, fall back to NCX
   const uint32_t tocStart = millis();
   if (!bookMetadataCache->beginTocPass()) {
-    Serial.printf("[%lu] [EBP] Could not begin writing toc pass\n", millis());
+    LOG_ERR("EBP", "Could not begin writing toc pass");
     return false;
   }
 
@@ -342,50 +327,50 @@ bool Epub::load(const bool buildIfMissing, const bool skipLoadingCss) {
 
   // Try EPUB 3 nav document first (preferred)
   if (!tocNavItem.empty()) {
-    Serial.printf("[%lu] [EBP] Attempting to parse EPUB 3 nav document\n", millis());
+    LOG_DBG("EBP", "Attempting to parse EPUB 3 nav document");
     tocParsed = parseTocNavFile();
   }
 
   // Fall back to NCX if nav parsing failed or wasn't available
   if (!tocParsed && !tocNcxItem.empty()) {
-    Serial.printf("[%lu] [EBP] Falling back to NCX TOC\n", millis());
+    LOG_DBG("EBP", "Falling back to NCX TOC");
     tocParsed = parseTocNcxFile();
   }
 
   if (!tocParsed) {
-    Serial.printf("[%lu] [EBP] Warning: Could not parse any TOC format\n", millis());
+    LOG_ERR("EBP", "Warning: Could not parse any TOC format");
     // Continue anyway - book will work without TOC
   }
 
   if (!bookMetadataCache->endTocPass()) {
-    Serial.printf("[%lu] [EBP] Could not end writing toc pass\n", millis());
+    LOG_ERR("EBP", "Could not end writing toc pass");
     return false;
   }
-  Serial.printf("[%lu] [EBP] TOC pass completed in %lu ms\n", millis(), millis() - tocStart);
+  LOG_DBG("EBP", "TOC pass completed in %lu ms", millis() - tocStart);
 
   // Close the cache files
   if (!bookMetadataCache->endWrite()) {
-    Serial.printf("[%lu] [EBP] Could not end writing cache\n", millis());
+    LOG_ERR("EBP", "Could not end writing cache");
     return false;
   }
 
   // Build final book.bin
   const uint32_t buildStart = millis();
   if (!bookMetadataCache->buildBookBin(filepath, bookMetadata)) {
-    Serial.printf("[%lu] [EBP] Could not update mappings and sizes\n", millis());
+    LOG_ERR("EBP", "Could not update mappings and sizes");
     return false;
   }
-  Serial.printf("[%lu] [EBP] buildBookBin completed in %lu ms\n", millis(), millis() - buildStart);
-  Serial.printf("[%lu] [EBP] Total indexing completed in %lu ms\n", millis(), millis() - indexingStart);
+  LOG_DBG("EBP", "buildBookBin completed in %lu ms", millis() - buildStart);
+  LOG_DBG("EBP", "Total indexing completed in %lu ms", millis() - indexingStart);
 
   if (!bookMetadataCache->cleanupTmpFiles()) {
-    Serial.printf("[%lu] [EBP] Could not cleanup tmp files - ignoring\n", millis());
+    LOG_DBG("EBP", "Could not cleanup tmp files - ignoring");
   }
 
   // Reload the cache from disk so it's in the correct state
   bookMetadataCache.reset(new BookMetadataCache(cachePath));
   if (!bookMetadataCache->load()) {
-    Serial.printf("[%lu] [EBP] Failed to reload cache after writing\n", millis());
+    LOG_ERR("EBP", "Failed to reload cache after writing");
     return false;
   }
 
@@ -394,22 +379,22 @@ bool Epub::load(const bool buildIfMissing, const bool skipLoadingCss) {
     parseCssFiles();
   }
 
-  Serial.printf("[%lu] [EBP] Loaded ePub: %s\n", millis(), filepath.c_str());
+  LOG_DBG("EBP", "Loaded ePub: %s", filepath.c_str());
   return true;
 }
 
 bool Epub::clearCache() const {
   if (!Storage.exists(cachePath.c_str())) {
-    Serial.printf("[%lu] [EPB] Cache does not exist, no action needed\n", millis());
+    LOG_DBG("EPB", "Cache does not exist, no action needed");
     return true;
   }
 
   if (!Storage.removeDir(cachePath.c_str())) {
-    Serial.printf("[%lu] [EPB] Failed to clear cache\n", millis());
+    LOG_ERR("EPB", "Failed to clear cache");
     return false;
   }
 
-  Serial.printf("[%lu] [EPB] Cache cleared successfully\n", millis());
+  LOG_DBG("EPB", "Cache cleared successfully");
   return true;
 }
 
@@ -458,32 +443,61 @@ std::string Epub::getCoverBmpPath(bool cropped) const {
 }
 
 bool Epub::generateCoverBmp(bool cropped) const {
+  bool invalid = false;
   // Already generated, return true
   if (Storage.exists(getCoverBmpPath(cropped).c_str())) {
-    return true;
+    // is this a valid cover or just an empty file we created to mark generation attempts?
+    invalid = !isValidThumbnailBmp(getCoverBmpPath(cropped));
+    if (invalid) {
+      // Remove the old invalid cover so we can attempt to generate a new one
+      Storage.remove(getCoverBmpPath(cropped).c_str());
+      LOG_DBG("EBP", "Previous cover generation attempt failed for %s mode, retrying", cropped ? "cropped" : "fit");
+    } else {
+      return true;
+    }
   }
 
   if (!bookMetadataCache || !bookMetadataCache->isLoaded()) {
-    Serial.printf("[%lu] [EBP] Cannot generate cover BMP, cache not loaded\n", millis());
+    LOG_ERR("EBP", "Cannot generate cover BMP, cache not loaded");
     return false;
   }
 
   const auto coverImageHref = bookMetadataCache->coreMetadata.coverItemHref;
+  std::string effectiveCoverImageHref = coverImageHref;
   if (coverImageHref.empty()) {
-    Serial.printf("[%lu] [EBP] No known cover image\n", millis());
+    // Fallback: try common cover filenames
+    std::vector<std::string> coverCandidates = getCoverCandidates();
+    for (const auto& candidate : coverCandidates) {
+      effectiveCoverImageHref = candidate;
+      // Try to read a small amount to check if exists
+      uint8_t* test = readItemContentsToBytes(candidate, nullptr, false);
+      if (test) {
+        free(test);
+        break;
+      } else {
+        effectiveCoverImageHref.clear();
+      }
+    }
+  }
+  if (effectiveCoverImageHref.empty()) {
+    LOG_ERR("EBP", "No known cover image");
     return false;
   }
 
-  if (coverImageHref.substr(coverImageHref.length() - 4) == ".jpg" ||
-      coverImageHref.substr(coverImageHref.length() - 5) == ".jpeg") {
-    Serial.printf("[%lu] [EBP] Generating BMP from JPG cover image (%s mode)\n", millis(), cropped ? "cropped" : "fit");
+  // Check for JPG/JPEG extensions (case insensitive)
+  std::string lowerHref = effectiveCoverImageHref;
+  std::transform(lowerHref.begin(), lowerHref.end(), lowerHref.begin(), ::tolower);
+  bool isJpg =
+      lowerHref.substr(lowerHref.length() - 4) == ".jpg" || lowerHref.substr(lowerHref.length() - 5) == ".jpeg";
+  if (isJpg) {
+    LOG_DBG("EBP", "Generating BMP from JPG cover image (%s mode)", cropped ? "cropped" : "fit");
     const auto coverJpgTempPath = getCachePath() + "/.cover.jpg";
 
     FsFile coverJpg;
     if (!Storage.openFileForWrite("EBP", coverJpgTempPath, coverJpg)) {
       return false;
     }
-    readItemContentsToStream(coverImageHref, coverJpg, 1024);
+    readItemContentsToStream(effectiveCoverImageHref, coverJpg, 1024);
     coverJpg.close();
 
     if (!Storage.openFileForRead("EBP", coverJpgTempPath, coverJpg)) {
@@ -501,13 +515,13 @@ bool Epub::generateCoverBmp(bool cropped) const {
     Storage.remove(coverJpgTempPath.c_str());
 
     if (!success) {
-      Serial.printf("[%lu] [EBP] Failed to generate BMP from JPG cover image\n", millis());
+      LOG_ERR("EBP", "Failed to generate BMP from cover image");
       Storage.remove(getCoverBmpPath(cropped).c_str());
     }
-    Serial.printf("[%lu] [EBP] Generated BMP from JPG cover image, success: %s\n", millis(), success ? "yes" : "no");
+    LOG_DBG("EBP", "Generated BMP from cover image, success: %s", success ? "yes" : "no");
     return success;
   } else {
-    Serial.printf("[%lu] [EBP] Cover image is not a JPG, skipping\n", millis());
+    LOG_ERR("EBP", "Cover image is not a supported format, skipping");
   }
 
   return false;
@@ -517,71 +531,269 @@ std::string Epub::getThumbBmpPath() const { return cachePath + "/thumb_[HEIGHT].
 std::string Epub::getThumbBmpPath(int height) const { return cachePath + "/thumb_" + std::to_string(height) + ".bmp"; }
 
 bool Epub::generateThumbBmp(int height) const {
+  bool invalid = false;
   // Already generated, return true
   if (Storage.exists(getThumbBmpPath(height).c_str())) {
-    return true;
+    // is this a valid thumbnail or just an empty file we created to mark generation attempts?
+    invalid = !isValidThumbnailBmp(getThumbBmpPath(height));
+    if (invalid) {
+      // Remove the old invalid thumbnail so we can attempt to generate a new one
+      Storage.remove(getThumbBmpPath(height).c_str());
+      LOG_DBG("EBP", "Previous thumbnail generation attempt failed for height %d, retrying", height);
+    } else {
+      return true;
+    }
   }
 
   if (!bookMetadataCache || !bookMetadataCache->isLoaded()) {
-    Serial.printf("[%lu] [EBP] Cannot generate thumb BMP, cache not loaded\n", millis());
+    LOG_ERR("EBP", "Cannot generate thumb BMP, cache not loaded");
     return false;
   }
 
   const auto coverImageHref = bookMetadataCache->coreMetadata.coverItemHref;
+  std::string effectiveCoverImageHref = coverImageHref;
   if (coverImageHref.empty()) {
-    Serial.printf("[%lu] [EBP] No known cover image for thumbnail\n", millis());
-  } else if (coverImageHref.substr(coverImageHref.length() - 4) == ".jpg" ||
-             coverImageHref.substr(coverImageHref.length() - 5) == ".jpeg") {
-    Serial.printf("[%lu] [EBP] Generating thumb BMP from JPG cover image\n", millis());
-    const auto coverJpgTempPath = getCachePath() + "/.cover.jpg";
-
-    FsFile coverJpg;
-    if (!Storage.openFileForWrite("EBP", coverJpgTempPath, coverJpg)) {
-      return false;
+    // Fallback: try common cover filenames
+    std::vector<std::string> coverCandidates = getCoverCandidates();
+    for (const auto& candidate : coverCandidates) {
+      effectiveCoverImageHref = candidate;
+      // Try to read a small amount to check if exists
+      uint8_t* test = readItemContentsToBytes(candidate, nullptr, false);
+      if (test) {
+        free(test);
+        break;
+      } else {
+        effectiveCoverImageHref.clear();
+      }
     }
-    readItemContentsToStream(coverImageHref, coverJpg, 1024);
-    coverJpg.close();
-
-    if (!Storage.openFileForRead("EBP", coverJpgTempPath, coverJpg)) {
-      return false;
-    }
-
-    FsFile thumbBmp;
-    if (!Storage.openFileForWrite("EBP", getThumbBmpPath(height), thumbBmp)) {
-      coverJpg.close();
-      return false;
-    }
-    // Use smaller target size for Continue Reading card (half of screen: 240x400)
-    // Generate 1-bit BMP for fast home screen rendering (no gray passes needed)
-    int THUMB_TARGET_WIDTH = height * 0.6;
-    int THUMB_TARGET_HEIGHT = height;
-    const bool success = JpegToBmpConverter::jpegFileTo1BitBmpStreamWithSize(coverJpg, thumbBmp, THUMB_TARGET_WIDTH,
-                                                                             THUMB_TARGET_HEIGHT);
-    coverJpg.close();
-    thumbBmp.close();
-    Storage.remove(coverJpgTempPath.c_str());
-
-    if (!success) {
-      Serial.printf("[%lu] [EBP] Failed to generate thumb BMP from JPG cover image\n", millis());
-      Storage.remove(getThumbBmpPath(height).c_str());
-    }
-    Serial.printf("[%lu] [EBP] Generated thumb BMP from JPG cover image, success: %s\n", millis(),
-                  success ? "yes" : "no");
-    return success;
+  }
+  if (effectiveCoverImageHref.empty()) {
+    LOG_DBG("EBP", "No known cover image for thumbnail");
   } else {
-    Serial.printf("[%lu] [EBP] Cover image is not a JPG, skipping thumbnail\n", millis());
+    // Check for JPG/JPEG extensions (case insensitive)
+    std::string lowerHref = effectiveCoverImageHref;
+    std::transform(lowerHref.begin(), lowerHref.end(), lowerHref.begin(), ::tolower);
+    bool isJpg =
+        lowerHref.substr(lowerHref.length() - 4) == ".jpg" || lowerHref.substr(lowerHref.length() - 5) == ".jpeg";
+    if (isJpg) {
+      LOG_DBG("EBP", "Generating thumb BMP from JPG cover image");
+      const auto coverJpgTempPath = getCachePath() + "/.cover.jpg";
+
+      FsFile coverJpg;
+      if (!Storage.openFileForWrite("EBP", coverJpgTempPath, coverJpg)) {
+        return false;
+      }
+      readItemContentsToStream(effectiveCoverImageHref, coverJpg, 1024);
+      coverJpg.close();
+
+      if (!Storage.openFileForRead("EBP", coverJpgTempPath, coverJpg)) {
+        return false;
+      }
+
+      FsFile thumbBmp;
+      if (!Storage.openFileForWrite("EBP", getThumbBmpPath(height), thumbBmp)) {
+        coverJpg.close();
+        return false;
+      }
+      // Use smaller target size for Continue Reading card (half of screen: 240x400)
+      // Generate 1-bit BMP for fast home screen rendering (no gray passes needed)
+      int THUMB_TARGET_WIDTH = height * 0.6;
+      int THUMB_TARGET_HEIGHT = height;
+      const bool success = JpegToBmpConverter::jpegFileTo1BitBmpStreamWithSize(coverJpg, thumbBmp, THUMB_TARGET_WIDTH,
+                                                                               THUMB_TARGET_HEIGHT);
+      coverJpg.close();
+      thumbBmp.close();
+      Storage.remove(coverJpgTempPath.c_str());
+
+      if (!success) {
+        LOG_ERR("EBP", "Failed to generate thumb BMP from JPG cover image");
+        Storage.remove(getThumbBmpPath(height).c_str());
+      }
+      LOG_DBG("EBP", "Generated thumb BMP from JPG cover image, success: %s", success ? "yes" : "no");
+      return success;
+    } else {
+      LOG_ERR("EBP", "Cover image is not a supported format, skipping thumbnail");
+    }
   }
 
-  // Write an empty bmp file to avoid generation attempts in the future
-  FsFile thumbBmp;
-  Storage.openFileForWrite("EBP", getThumbBmpPath(height), thumbBmp);
-  thumbBmp.close();
   return false;
 }
 
+bool Epub::generateInvalidFormatThumbBmp(int height) const {
+  // Create a simple 1-bit BMP with an X pattern to indicate invalid format.
+  // This BMP is a valid 1-bit file used as a marker to prevent repeated
+  // generation attempts when conversion fails (e.g., progressive JPG).
+  const int width = height * 0.6;                // Same aspect ratio as normal thumbnails
+  const int rowBytes = ((width + 31) / 32) * 4;  // 1-bit rows padded to 4-byte boundary
+  const int imageSize = rowBytes * height;
+  const int fileSize = 14 + 40 + 8 + imageSize;  // Header + DIB + palette + data
+  const int dataOffset = 14 + 40 + 8;
+
+  FsFile thumbBmp;
+  if (!Storage.openFileForWrite("EBP", getThumbBmpPath(height), thumbBmp)) {
+    return false;
+  }
+
+  // BMP file header (14 bytes)
+  thumbBmp.write('B');
+  thumbBmp.write('M');
+  thumbBmp.write(reinterpret_cast<const uint8_t*>(&fileSize), 4);
+  uint32_t reserved = 0;
+  thumbBmp.write(reinterpret_cast<const uint8_t*>(&reserved), 4);
+  thumbBmp.write(reinterpret_cast<const uint8_t*>(&dataOffset), 4);
+
+  // DIB header (BITMAPINFOHEADER - 40 bytes)
+  uint32_t dibHeaderSize = 40;
+  thumbBmp.write(reinterpret_cast<const uint8_t*>(&dibHeaderSize), 4);
+  int32_t bmpWidth = width;
+  thumbBmp.write(reinterpret_cast<const uint8_t*>(&bmpWidth), 4);
+  int32_t bmpHeight = -height;  // Negative for top-down
+  thumbBmp.write(reinterpret_cast<const uint8_t*>(&bmpHeight), 4);
+  uint16_t planes = 1;
+  thumbBmp.write(reinterpret_cast<const uint8_t*>(&planes), 2);
+  uint16_t bitsPerPixel = 1;
+  thumbBmp.write(reinterpret_cast<const uint8_t*>(&bitsPerPixel), 2);
+  uint32_t compression = 0;
+  thumbBmp.write(reinterpret_cast<const uint8_t*>(&compression), 4);
+  thumbBmp.write(reinterpret_cast<const uint8_t*>(&imageSize), 4);
+  int32_t ppmX = 2835;  // 72 DPI
+  thumbBmp.write(reinterpret_cast<const uint8_t*>(&ppmX), 4);
+  int32_t ppmY = 2835;
+  thumbBmp.write(reinterpret_cast<const uint8_t*>(&ppmY), 4);
+  uint32_t colorsUsed = 2;
+  thumbBmp.write(reinterpret_cast<const uint8_t*>(&colorsUsed), 4);
+  uint32_t colorsImportant = 2;
+  thumbBmp.write(reinterpret_cast<const uint8_t*>(&colorsImportant), 4);
+
+  // Color palette (2 colors for 1-bit)
+  uint8_t black[4] = {0x00, 0x00, 0x00, 0x00};  // Color 0: Black
+  thumbBmp.write(black, 4);
+  uint8_t white[4] = {0xFF, 0xFF, 0xFF, 0x00};  // Color 1: White
+  thumbBmp.write(white, 4);
+
+  // Generate X pattern bitmap data
+  // In BMP, 0 = black (first color in palette), 1 = white
+  // We'll draw black pixels on white background
+  for (int y = 0; y < height; y++) {
+    std::vector<uint8_t> rowData(rowBytes, 0xFF);  // Initialize to all white (1s)
+
+    // Map this row to a horizontal position for diagonals
+    const int scaledY = (y * width) / height;
+    const int thickness = 2;  // thickness of diagonal lines in pixels
+
+    for (int x = 0; x < width; x++) {
+      bool drawPixel = false;
+      // Main diagonal (top-left to bottom-right)
+      if (std::abs(x - scaledY) <= thickness) drawPixel = true;
+      // Other diagonal (top-right to bottom-left)
+      if (std::abs(x - (width - 1 - scaledY)) <= thickness) drawPixel = true;
+
+      if (drawPixel) {
+        const int byteIndex = x / 8;
+        const int bitIndex = 7 - (x % 8);  // MSB first
+        rowData[byteIndex] &= static_cast<uint8_t>(~(1 << bitIndex));
+      }
+    }
+
+    // Write the row data
+    thumbBmp.write(rowData.data(), rowBytes);
+  }
+
+  thumbBmp.close();
+  LOG_DBG("EBP", "Generated invalid format thumbnail BMP");
+  return true;
+}
+
+bool Epub::generateInvalidFormatCoverBmp(bool cropped) const {
+  // Create a simple 1-bit BMP with an X pattern to indicate invalid format.
+  // This BMP is intentionally a valid image that visually indicates a
+  // malformed/unsupported cover image instead of leaving an empty marker
+  // file that would cause repeated generation attempts.
+  // Derive logical portrait dimensions from the display hardware constants
+  // EInkDisplay reports native panel orientation as 800x480; use min/max
+  const int hwW = HalDisplay::DISPLAY_WIDTH;
+  const int hwH = HalDisplay::DISPLAY_HEIGHT;
+  const int width = std::min(hwW, hwH);          // logical portrait width (480)
+  const int height = std::max(hwW, hwH);         // logical portrait height (800)
+  const int rowBytes = ((width + 31) / 32) * 4;  // 1-bit rows padded to 4-byte boundary
+  const int imageSize = rowBytes * height;
+  const int fileSize = 14 + 40 + 8 + imageSize;  // Header + DIB + palette + data
+  const int dataOffset = 14 + 40 + 8;
+
+  FsFile coverBmp;
+  if (!Storage.openFileForWrite("EBP", getCoverBmpPath(cropped), coverBmp)) {
+    return false;
+  }
+
+  // BMP file header (14 bytes)
+  coverBmp.write('B');
+  coverBmp.write('M');
+  coverBmp.write(reinterpret_cast<const uint8_t*>(&fileSize), 4);
+  uint32_t reserved = 0;
+  coverBmp.write(reinterpret_cast<const uint8_t*>(&reserved), 4);
+  coverBmp.write(reinterpret_cast<const uint8_t*>(&dataOffset), 4);
+
+  // DIB header (BITMAPINFOHEADER - 40 bytes)
+  uint32_t dibHeaderSize = 40;
+  coverBmp.write(reinterpret_cast<const uint8_t*>(&dibHeaderSize), 4);
+  int32_t bmpWidth = width;
+  coverBmp.write(reinterpret_cast<const uint8_t*>(&bmpWidth), 4);
+  int32_t bmpHeight = -height;  // Negative for top-down
+  coverBmp.write(reinterpret_cast<const uint8_t*>(&bmpHeight), 4);
+  uint16_t planes = 1;
+  coverBmp.write(reinterpret_cast<const uint8_t*>(&planes), 2);
+  uint16_t bitsPerPixel = 1;
+  coverBmp.write(reinterpret_cast<const uint8_t*>(&bitsPerPixel), 2);
+  uint32_t compression = 0;
+  coverBmp.write(reinterpret_cast<const uint8_t*>(&compression), 4);
+  coverBmp.write(reinterpret_cast<const uint8_t*>(&imageSize), 4);
+  int32_t ppmX = 2835;  // 72 DPI
+  coverBmp.write(reinterpret_cast<const uint8_t*>(&ppmX), 4);
+  int32_t ppmY = 2835;
+  coverBmp.write(reinterpret_cast<const uint8_t*>(&ppmY), 4);
+  uint32_t colorsUsed = 2;
+  coverBmp.write(reinterpret_cast<const uint8_t*>(&colorsUsed), 4);
+  uint32_t colorsImportant = 2;
+  coverBmp.write(reinterpret_cast<const uint8_t*>(&colorsImportant), 4);
+
+  // Color palette (2 colors for 1-bit)
+  uint8_t black[4] = {0x00, 0x00, 0x00, 0x00};  // Color 0: Black
+  coverBmp.write(black, 4);
+  uint8_t white[4] = {0xFF, 0xFF, 0xFF, 0x00};  // Color 1: White
+  coverBmp.write(white, 4);
+
+  // Generate X pattern bitmap data
+  // In BMP, 0 = black (first color in palette), 1 = white
+  // We'll draw black pixels on white background
+  for (int y = 0; y < height; y++) {
+    std::vector<uint8_t> rowData(rowBytes, 0xFF);  // Initialize to all white (1s)
+
+    const int scaledY = (y * width) / height;
+    const int thickness = 6;  // thicker lines for full-cover visibility
+
+    for (int x = 0; x < width; x++) {
+      bool drawPixel = false;
+      if (std::abs(x - scaledY) <= thickness) drawPixel = true;
+      if (std::abs(x - (width - 1 - scaledY)) <= thickness) drawPixel = true;
+
+      if (drawPixel) {
+        const int byteIndex = x / 8;
+        const int bitIndex = 7 - (x % 8);
+        rowData[byteIndex] &= static_cast<uint8_t>(~(1 << bitIndex));
+      }
+    }
+
+    coverBmp.write(rowData.data(), rowBytes);
+  }
+
+  coverBmp.close();
+  LOG_DBG("EBP", "Generated invalid format cover BMP");
+  return true;
+}
+
 uint8_t* Epub::readItemContentsToBytes(const std::string& itemHref, size_t* size, const bool trailingNullByte) const {
   if (itemHref.empty()) {
-    Serial.printf("[%lu] [EBP] Failed to read item, empty href\n", millis());
+    LOG_DBG("EBP", "Failed to read item, empty href");
     return nullptr;
   }
 
@@ -589,7 +801,7 @@ uint8_t* Epub::readItemContentsToBytes(const std::string& itemHref, size_t* size
 
   const auto content = ZipFile(filepath).readFileToMemory(path.c_str(), size, trailingNullByte);
   if (!content) {
-    Serial.printf("[%lu] [EBP] Failed to read item %s\n", millis(), path.c_str());
+    LOG_DBG("EBP", "Failed to read item %s", path.c_str());
     return nullptr;
   }
 
@@ -598,7 +810,7 @@ uint8_t* Epub::readItemContentsToBytes(const std::string& itemHref, size_t* size
 
 bool Epub::readItemContentsToStream(const std::string& itemHref, Print& out, const size_t chunkSize) const {
   if (itemHref.empty()) {
-    Serial.printf("[%lu] [EBP] Failed to read item, empty href\n", millis());
+    LOG_DBG("EBP", "Failed to read item, empty href");
     return false;
   }
 
@@ -622,12 +834,12 @@ size_t Epub::getCumulativeSpineItemSize(const int spineIndex) const { return get
 
 BookMetadataCache::SpineEntry Epub::getSpineItem(const int spineIndex) const {
   if (!bookMetadataCache || !bookMetadataCache->isLoaded()) {
-    Serial.printf("[%lu] [EBP] getSpineItem called but cache not loaded\n", millis());
+    LOG_ERR("EBP", "getSpineItem called but cache not loaded");
     return {};
   }
 
   if (spineIndex < 0 || spineIndex >= bookMetadataCache->getSpineCount()) {
-    Serial.printf("[%lu] [EBP] getSpineItem index:%d is out of range\n", millis(), spineIndex);
+    LOG_ERR("EBP", "getSpineItem index:%d is out of range", spineIndex);
     return bookMetadataCache->getSpineEntry(0);
   }
 
@@ -636,12 +848,12 @@ BookMetadataCache::SpineEntry Epub::getSpineItem(const int spineIndex) const {
 
 BookMetadataCache::TocEntry Epub::getTocItem(const int tocIndex) const {
   if (!bookMetadataCache || !bookMetadataCache->isLoaded()) {
-    Serial.printf("[%lu] [EBP] getTocItem called but cache not loaded\n", millis());
+    LOG_DBG("EBP", "getTocItem called but cache not loaded");
     return {};
   }
 
   if (tocIndex < 0 || tocIndex >= bookMetadataCache->getTocCount()) {
-    Serial.printf("[%lu] [EBP] getTocItem index:%d is out of range\n", millis(), tocIndex);
+    LOG_DBG("EBP", "getTocItem index:%d is out of range", tocIndex);
     return {};
   }
 
@@ -659,18 +871,18 @@ int Epub::getTocItemsCount() const {
 // work out the section index for a toc index
 int Epub::getSpineIndexForTocIndex(const int tocIndex) const {
   if (!bookMetadataCache || !bookMetadataCache->isLoaded()) {
-    Serial.printf("[%lu] [EBP] getSpineIndexForTocIndex called but cache not loaded\n", millis());
+    LOG_ERR("EBP", "getSpineIndexForTocIndex called but cache not loaded");
     return 0;
   }
 
   if (tocIndex < 0 || tocIndex >= bookMetadataCache->getTocCount()) {
-    Serial.printf("[%lu] [EBP] getSpineIndexForTocIndex: tocIndex %d out of range\n", millis(), tocIndex);
+    LOG_ERR("EBP", "getSpineIndexForTocIndex: tocIndex %d out of range", tocIndex);
     return 0;
   }
 
   const int spineIndex = bookMetadataCache->getTocEntry(tocIndex).spineIndex;
   if (spineIndex < 0) {
-    Serial.printf("[%lu] [EBP] Section not found for TOC index %d\n", millis(), tocIndex);
+    LOG_DBG("EBP", "Section not found for TOC index %d", tocIndex);
     return 0;
   }
 
@@ -688,14 +900,13 @@ size_t Epub::getBookSize() const {
 
 int Epub::getSpineIndexForTextReference() const {
   if (!bookMetadataCache || !bookMetadataCache->isLoaded()) {
-    Serial.printf("[%lu] [EBP] getSpineIndexForTextReference called but cache not loaded\n", millis());
+    LOG_ERR("EBP", "getSpineIndexForTextReference called but cache not loaded");
     return 0;
   }
-  Serial.printf("[%lu] [ERS] Core Metadata: cover(%d)=%s, textReference(%d)=%s\n", millis(),
-                bookMetadataCache->coreMetadata.coverItemHref.size(),
-                bookMetadataCache->coreMetadata.coverItemHref.c_str(),
-                bookMetadataCache->coreMetadata.textReferenceHref.size(),
-                bookMetadataCache->coreMetadata.textReferenceHref.c_str());
+  LOG_DBG("EBP", "Core Metadata: cover(%d)=%s, textReference(%d)=%s",
+          bookMetadataCache->coreMetadata.coverItemHref.size(), bookMetadataCache->coreMetadata.coverItemHref.c_str(),
+          bookMetadataCache->coreMetadata.textReferenceHref.size(),
+          bookMetadataCache->coreMetadata.textReferenceHref.c_str());
 
   if (bookMetadataCache->coreMetadata.textReferenceHref.empty()) {
     // there was no textReference in epub, so we return 0 (the first chapter)
@@ -705,13 +916,13 @@ int Epub::getSpineIndexForTextReference() const {
   // loop through spine items to get the correct index matching the text href
   for (size_t i = 0; i < getSpineItemsCount(); i++) {
     if (getSpineItem(i).href == bookMetadataCache->coreMetadata.textReferenceHref) {
-      Serial.printf("[%lu] [ERS] Text reference %s found at index %d\n", millis(),
-                    bookMetadataCache->coreMetadata.textReferenceHref.c_str(), i);
+      LOG_DBG("EBP", "Text reference %s found at index %d", bookMetadataCache->coreMetadata.textReferenceHref.c_str(),
+              i);
       return i;
     }
   }
   // This should not happen, as we checked for empty textReferenceHref earlier
-  Serial.printf("[%lu] [EBP] Section not found for text reference\n", millis());
+  LOG_DBG("EBP", "Section not found for text reference");
   return 0;
 }
 
@@ -727,3 +938,45 @@ float Epub::calculateProgress(const int currentSpineIndex, const float currentSp
   const float totalProgress = static_cast<float>(prevChapterSize) + sectionProgSize;
   return totalProgress / static_cast<float>(bookSize);
 }
+
+bool Epub::isValidThumbnailBmp(const std::string& bmpPath) {
+  if (!Storage.exists(bmpPath.c_str())) {
+    return false;
+  }
+  FsFile file = Storage.open(bmpPath.c_str());
+  if (!file) {
+    LOG_ERR("EBP", "Failed to open thumbnail BMP at path: %s", bmpPath.c_str());
+    return false;
+  }
+  size_t fileSize = file.size();
+  if (fileSize == 0) {
+    // Empty file is a marker for "no cover available"
+    LOG_DBG("EBP", "Thumbnail BMP is empty (no cover marker) at path: %s", bmpPath.c_str());
+    file.close();
+    return false;
+  }
+  // BMP header starts with 'B' 'M'
+  uint8_t header[2];
+  size_t bytesRead = file.read(header, 2);
+  if (bytesRead != 2) {
+    LOG_ERR("EBP", "Failed to read thumbnail BMP header at path: %s", bmpPath.c_str());
+    file.close();
+    return false;
+  }
+  LOG_DBG("EBP", "Thumbnail BMP header: %c%c", header[0], header[1]);
+  file.close();
+  return header[0] == 'B' && header[1] == 'M';
+}
+
+std::vector<std::string> Epub::getCoverCandidates() const {
+  std::vector<std::string> coverDirectories = {".", "images", "Images", "OEBPS", "OEBPS/images", "OEBPS/Images"};
+  std::vector<std::string> coverExtensions = {".jpg", ".jpeg"};  // add ".png" when PNG cover support is implemented
+  std::vector<std::string> coverCandidates;
+  for (const auto& ext : coverExtensions) {
+    for (const auto& dir : coverDirectories) {
+      std::string candidate = (dir == ".") ? "cover" + ext : dir + "/cover" + ext;
+      coverCandidates.push_back(candidate);
+    }
+  }
+  return coverCandidates;
+}

lib/Epub/Epub.h

@@ -35,8 +35,6 @@ class Epub {
   bool parseTocNcxFile() const;
   bool parseTocNavFile() const;
   void parseCssFiles() const;
-  std::string getCssRulesCache() const;
-  bool loadCssRulesFromCache() const;
 
  public:
   explicit Epub(std::string filepath, const std::string& cacheDir) : filepath(std::move(filepath)) {
@@ -54,10 +52,23 @@ class Epub {
   const std::string& getAuthor() const;
   const std::string& getLanguage() const;
   std::string getCoverBmpPath(bool cropped = false) const;
+  // Generate a 1-bit BMP cover image from the EPUB cover image.
+  // Returns true on success. On conversion failure, callers may use
+  // `generateInvalidFormatCoverBmp` to create a valid marker BMP.
   bool generateCoverBmp(bool cropped = false) const;
+  // Create a valid 1-bit BMP that visually indicates an invalid/unsupported
+  // cover format (an X pattern). This prevents repeated generation attempts
+  // by providing a valid BMP file that `isValidThumbnailBmp` accepts.
+  bool generateInvalidFormatCoverBmp(bool cropped = false) const;
   std::string getThumbBmpPath() const;
   std::string getThumbBmpPath(int height) const;
+  // Generate a thumbnail BMP at the requested `height`. Returns true on
+  // successful conversion. If conversion fails, `generateInvalidFormatThumbBmp`
+  // can be used to write a valid marker image that prevents retries.
   bool generateThumbBmp(int height) const;
+  // Create a valid 1-bit thumbnail BMP with an X marker indicating an
+  // invalid/unsupported cover image instead of leaving an empty marker file.
+  bool generateInvalidFormatThumbBmp(int height) const;
   uint8_t* readItemContentsToBytes(const std::string& itemHref, size_t* size = nullptr,
                                    bool trailingNullByte = false) const;
   bool readItemContentsToStream(const std::string& itemHref, Print& out, size_t chunkSize) const;
@@ -73,5 +84,10 @@ class Epub {
 
   size_t getBookSize() const;
   float calculateProgress(int currentSpineIndex, float currentSpineRead) const;
-  const CssParser* getCssParser() const { return cssParser.get(); }
+  CssParser* getCssParser() const { return cssParser.get(); }
+
+  static bool isValidThumbnailBmp(const std::string& bmpPath);
+
+ private:
+  std::vector<std::string> getCoverCandidates() const;
 };

lib/Epub/Epub/BookMetadataCache.cpp

@@ -1,6 +1,6 @@
 #include "BookMetadataCache.h"
 
-#include <HardwareSerial.h>
+#include <Logging.h>
 #include <Serialization.h>
 #include <ZipFile.h>
 
@@ -21,12 +21,12 @@ bool BookMetadataCache::beginWrite() {
   buildMode = true;
   spineCount = 0;
   tocCount = 0;
-  Serial.printf("[%lu] [BMC] Entering write mode\n", millis());
+  LOG_DBG("BMC", "Entering write mode");
   return true;
 }
 
 bool BookMetadataCache::beginContentOpfPass() {
-  Serial.printf("[%lu] [BMC] Beginning content opf pass\n", millis());
+  LOG_DBG("BMC", "Beginning content opf pass");
 
   // Open spine file for writing
   return Storage.openFileForWrite("BMC", cachePath + tmpSpineBinFile, spineFile);
@@ -38,7 +38,7 @@ bool BookMetadataCache::endContentOpfPass() {
 }
 
 bool BookMetadataCache::beginTocPass() {
-  Serial.printf("[%lu] [BMC] Beginning toc pass\n", millis());
+  LOG_DBG("BMC", "Beginning toc pass");
 
   if (!Storage.openFileForRead("BMC", cachePath + tmpSpineBinFile, spineFile)) {
     return false;
@@ -66,7 +66,7 @@ bool BookMetadataCache::beginTocPass() {
               });
     spineFile.seek(0);
     useSpineHrefIndex = true;
-    Serial.printf("[%lu] [BMC] Using fast index for %d spine items\n", millis(), spineCount);
+    LOG_DBG("BMC", "Using fast index for %d spine items", spineCount);
   } else {
     useSpineHrefIndex = false;
   }
@@ -87,12 +87,12 @@ bool BookMetadataCache::endTocPass() {
 
 bool BookMetadataCache::endWrite() {
   if (!buildMode) {
-    Serial.printf("[%lu] [BMC] endWrite called but not in build mode\n", millis());
+    LOG_DBG("BMC", "endWrite called but not in build mode");
     return false;
   }
 
   buildMode = false;
-  Serial.printf("[%lu] [BMC] Wrote %d spine, %d TOC entries\n", millis(), spineCount, tocCount);
+  LOG_DBG("BMC", "Wrote %d spine, %d TOC entries", spineCount, tocCount);
   return true;
 }
 
@@ -167,7 +167,7 @@ bool BookMetadataCache::buildBookBin(const std::string& epubPath, const BookMeta
   ZipFile zip(epubPath);
   // Pre-open zip file to speed up size calculations
   if (!zip.open()) {
-    Serial.printf("[%lu] [BMC] Could not open EPUB zip for size calculations\n", millis());
+    LOG_ERR("BMC", "Could not open EPUB zip for size calculations");
     bookFile.close();
     spineFile.close();
     tocFile.close();
@@ -185,7 +185,7 @@ bool BookMetadataCache::buildBookBin(const std::string& epubPath, const BookMeta
   bool useBatchSizes = false;
 
   if (spineCount >= LARGE_SPINE_THRESHOLD) {
-    Serial.printf("[%lu] [BMC] Using batch size lookup for %d spine items\n", millis(), spineCount);
+    LOG_DBG("BMC", "Using batch size lookup for %d spine items", spineCount);
 
     std::vector<ZipFile::SizeTarget> targets;
     targets.reserve(spineCount);
@@ -208,7 +208,7 @@ bool BookMetadataCache::buildBookBin(const std::string& epubPath, const BookMeta
 
     spineSizes.resize(spineCount, 0);
     int matched = zip.fillUncompressedSizes(targets, spineSizes);
-    Serial.printf("[%lu] [BMC] Batch lookup matched %d/%d spine items\n", millis(), matched, spineCount);
+    LOG_DBG("BMC", "Batch lookup matched %d/%d spine items", matched, spineCount);
 
     targets.clear();
     targets.shrink_to_fit();
@@ -227,9 +227,8 @@ bool BookMetadataCache::buildBookBin(const std::string& epubPath, const BookMeta
     // Not a huge deal if we don't fine a TOC entry for the spine entry, this is expected behaviour for EPUBs
     // Logging here is for debugging
     if (spineEntry.tocIndex == -1) {
-      Serial.printf(
-          "[%lu] [BMC] Warning: Could not find TOC entry for spine item %d: %s, using title from last section\n",
-          millis(), i, spineEntry.href.c_str());
+      LOG_DBG("BMC", "Warning: Could not find TOC entry for spine item %d: %s, using title from last section", i,
+              spineEntry.href.c_str());
       spineEntry.tocIndex = lastSpineTocIndex;
     }
     lastSpineTocIndex = spineEntry.tocIndex;
@@ -240,13 +239,13 @@ bool BookMetadataCache::buildBookBin(const std::string& epubPath, const BookMeta
       if (itemSize == 0) {
         const std::string path = FsHelpers::normalisePath(spineEntry.href);
         if (!zip.getInflatedFileSize(path.c_str(), &itemSize)) {
-          Serial.printf("[%lu] [BMC] Warning: Could not get size for spine item: %s\n", millis(), path.c_str());
+          LOG_ERR("BMC", "Warning: Could not get size for spine item: %s", path.c_str());
         }
       }
     } else {
       const std::string path = FsHelpers::normalisePath(spineEntry.href);
       if (!zip.getInflatedFileSize(path.c_str(), &itemSize)) {
-        Serial.printf("[%lu] [BMC] Warning: Could not get size for spine item: %s\n", millis(), path.c_str());
+        LOG_ERR("BMC", "Warning: Could not get size for spine item: %s", path.c_str());
       }
     }
 
@@ -270,7 +269,7 @@ bool BookMetadataCache::buildBookBin(const std::string& epubPath, const BookMeta
   spineFile.close();
   tocFile.close();
 
-  Serial.printf("[%lu] [BMC] Successfully built book.bin\n", millis());
+  LOG_DBG("BMC", "Successfully built book.bin");
   return true;
 }
 
@@ -306,7 +305,7 @@ uint32_t BookMetadataCache::writeTocEntry(FsFile& file, const TocEntry& entry) c
 // this is because in this function we're marking positions of the items
 void BookMetadataCache::createSpineEntry(const std::string& href) {
   if (!buildMode || !spineFile) {
-    Serial.printf("[%lu] [BMC] createSpineEntry called but not in build mode\n", millis());
+    LOG_DBG("BMC", "createSpineEntry called but not in build mode");
     return;
   }
 
@@ -318,7 +317,7 @@ void BookMetadataCache::createSpineEntry(const std::string& href) {
 void BookMetadataCache::createTocEntry(const std::string& title, const std::string& href, const std::string& anchor,
                                        const uint8_t level) {
   if (!buildMode || !tocFile || !spineFile) {
-    Serial.printf("[%lu] [BMC] createTocEntry called but not in build mode\n", millis());
+    LOG_DBG("BMC", "createTocEntry called but not in build mode");
     return;
   }
 
@@ -340,7 +339,7 @@ void BookMetadataCache::createTocEntry(const std::string& title, const std::stri
     }
 
     if (spineIndex == -1) {
-      Serial.printf("[%lu] [BMC] createTocEntry: Could not find spine item for TOC href %s\n", millis(), href.c_str());
+      LOG_DBG("BMC", "createTocEntry: Could not find spine item for TOC href %s", href.c_str());
     }
   } else {
     spineFile.seek(0);
@@ -352,7 +351,7 @@ void BookMetadataCache::createTocEntry(const std::string& title, const std::stri
       }
     }
     if (spineIndex == -1) {
-      Serial.printf("[%lu] [BMC] createTocEntry: Could not find spine item for TOC href %s\n", millis(), href.c_str());
+      LOG_DBG("BMC", "createTocEntry: Could not find spine item for TOC href %s", href.c_str());
     }
   }
 
@@ -371,7 +370,7 @@ bool BookMetadataCache::load() {
   uint8_t version;
   serialization::readPod(bookFile, version);
   if (version != BOOK_CACHE_VERSION) {
-    Serial.printf("[%lu] [BMC] Cache version mismatch: expected %d, got %d\n", millis(), BOOK_CACHE_VERSION, version);
+    LOG_DBG("BMC", "Cache version mismatch: expected %d, got %d", BOOK_CACHE_VERSION, version);
     bookFile.close();
     return false;
   }
@@ -387,18 +386,18 @@ bool BookMetadataCache::load() {
   serialization::readString(bookFile, coreMetadata.textReferenceHref);
 
   loaded = true;
-  Serial.printf("[%lu] [BMC] Loaded cache data: %d spine, %d TOC entries\n", millis(), spineCount, tocCount);
+  LOG_DBG("BMC", "Loaded cache data: %d spine, %d TOC entries", spineCount, tocCount);
   return true;
 }
 
 BookMetadataCache::SpineEntry BookMetadataCache::getSpineEntry(const int index) {
   if (!loaded) {
-    Serial.printf("[%lu] [BMC] getSpineEntry called but cache not loaded\n", millis());
+    LOG_ERR("BMC", "getSpineEntry called but cache not loaded");
     return {};
   }
 
   if (index < 0 || index >= static_cast<int>(spineCount)) {
-    Serial.printf("[%lu] [BMC] getSpineEntry index %d out of range\n", millis(), index);
+    LOG_ERR("BMC", "getSpineEntry index %d out of range", index);
     return {};
   }
 
@@ -412,12 +411,12 @@ BookMetadataCache::SpineEntry BookMetadataCache::getSpineEntry(const int index)
 
 BookMetadataCache::TocEntry BookMetadataCache::getTocEntry(const int index) {
   if (!loaded) {
-    Serial.printf("[%lu] [BMC] getTocEntry called but cache not loaded\n", millis());
+    LOG_ERR("BMC", "getTocEntry called but cache not loaded");
     return {};
   }
 
   if (index < 0 || index >= static_cast<int>(tocCount)) {
-    Serial.printf("[%lu] [BMC] getTocEntry index %d out of range\n", millis(), index);
+    LOG_ERR("BMC", "getTocEntry index %d out of range", index);
     return {};
   }
 

lib/Epub/Epub/Page.cpp

@@ -1,8 +1,17 @@
 #include "Page.h"
 
-#include <HardwareSerial.h>
+#include <GfxRenderer.h>
+#include <Logging.h>
 #include <Serialization.h>
 
+// Cell padding in pixels (must match TABLE_CELL_PAD_* in ChapterHtmlSlimParser.cpp)
+static constexpr int TABLE_CELL_PADDING_X = 4;
+static constexpr int TABLE_CELL_PADDING_TOP = 1;
+
+// ---------------------------------------------------------------------------
+// PageLine
+// ---------------------------------------------------------------------------
+
 void PageLine::render(GfxRenderer& renderer, const int fontId, const int xOffset, const int yOffset) {
   block->render(renderer, fontId, xPos + xOffset, yPos + yOffset);
 }
@@ -25,6 +34,142 @@ std::unique_ptr<PageLine> PageLine::deserialize(FsFile& file) {
   return std::unique_ptr<PageLine>(new PageLine(std::move(tb), xPos, yPos));
 }
 
+// ---------------------------------------------------------------------------
+// PageImage
+// ---------------------------------------------------------------------------
+
+void PageImage::render(GfxRenderer& renderer, const int fontId, const int xOffset, const int yOffset) {
+  // Images don't use fontId or text rendering
+  imageBlock->render(renderer, xPos + xOffset, yPos + yOffset);
+}
+
+bool PageImage::serialize(FsFile& file) {
+  serialization::writePod(file, xPos);
+  serialization::writePod(file, yPos);
+
+  // serialize ImageBlock
+  return imageBlock->serialize(file);
+}
+
+std::unique_ptr<PageImage> PageImage::deserialize(FsFile& file) {
+  int16_t xPos;
+  int16_t yPos;
+  serialization::readPod(file, xPos);
+  serialization::readPod(file, yPos);
+
+  auto ib = ImageBlock::deserialize(file);
+  return std::unique_ptr<PageImage>(new PageImage(std::move(ib), xPos, yPos));
+}
+
+// ---------------------------------------------------------------------------
+// PageTableRow
+// ---------------------------------------------------------------------------
+
+void PageTableRow::render(GfxRenderer& renderer, const int fontId, const int xOffset, const int yOffset) {
+  const int baseX = xPos + xOffset;
+  const int baseY = yPos + yOffset;
+
+  // Draw horizontal borders (top and bottom of this row)
+  renderer.drawLine(baseX, baseY, baseX + totalWidth, baseY);
+  renderer.drawLine(baseX, baseY + rowHeight, baseX + totalWidth, baseY + rowHeight);
+
+  // Draw vertical borders and render cell contents
+  // Left edge
+  renderer.drawLine(baseX, baseY, baseX, baseY + rowHeight);
+
+  for (const auto& cell : cells) {
+    // Right vertical border for this cell
+    const int cellRightX = baseX + cell.xOffset + cell.columnWidth;
+    renderer.drawLine(cellRightX, baseY, cellRightX, baseY + rowHeight);
+
+    // Render each text line within the cell
+    const int cellTextX = baseX + cell.xOffset + TABLE_CELL_PADDING_X;
+    int cellLineY = baseY + 1 + TABLE_CELL_PADDING_TOP;  // 1px border + top padding
+
+    for (const auto& line : cell.lines) {
+      line->render(renderer, fontId, cellTextX, cellLineY);
+      cellLineY += lineHeight;
+    }
+  }
+}
+
+bool PageTableRow::serialize(FsFile& file) {
+  serialization::writePod(file, xPos);
+  serialization::writePod(file, yPos);
+  serialization::writePod(file, rowHeight);
+  serialization::writePod(file, totalWidth);
+  serialization::writePod(file, lineHeight);
+
+  const uint16_t cellCount = static_cast<uint16_t>(cells.size());
+  serialization::writePod(file, cellCount);
+
+  for (const auto& cell : cells) {
+    serialization::writePod(file, cell.xOffset);
+    serialization::writePod(file, cell.columnWidth);
+
+    const uint16_t lineCount = static_cast<uint16_t>(cell.lines.size());
+    serialization::writePod(file, lineCount);
+
+    for (const auto& line : cell.lines) {
+      if (!line->serialize(file)) {
+        return false;
+      }
+    }
+  }
+
+  return true;
+}
+
+std::unique_ptr<PageTableRow> PageTableRow::deserialize(FsFile& file) {
+  int16_t xPos, yPos, rowHeight, totalWidth, lineHeight;
+  serialization::readPod(file, xPos);
+  serialization::readPod(file, yPos);
+  serialization::readPod(file, rowHeight);
+  serialization::readPod(file, totalWidth);
+  serialization::readPod(file, lineHeight);
+
+  uint16_t cellCount;
+  serialization::readPod(file, cellCount);
+
+  // Sanity check
+  if (cellCount > 100) {
+    LOG_ERR("PTR", "Deserialization failed: cell count %u exceeds maximum", cellCount);
+    return nullptr;
+  }
+
+  std::vector<PageTableCellData> cells;
+  cells.resize(cellCount);
+
+  for (uint16_t c = 0; c < cellCount; ++c) {
+    serialization::readPod(file, cells[c].xOffset);
+    serialization::readPod(file, cells[c].columnWidth);
+
+    uint16_t lineCount;
+    serialization::readPod(file, lineCount);
+
+    if (lineCount > 1000) {
+      LOG_ERR("PTR", "Deserialization failed: line count %u in cell %u exceeds maximum", lineCount, c);
+      return nullptr;
+    }
+
+    cells[c].lines.reserve(lineCount);
+    for (uint16_t l = 0; l < lineCount; ++l) {
+      auto tb = TextBlock::deserialize(file);
+      if (!tb) {
+        return nullptr;
+      }
+      cells[c].lines.push_back(std::move(tb));
+    }
+  }
+
+  return std::unique_ptr<PageTableRow>(
+      new PageTableRow(std::move(cells), rowHeight, totalWidth, lineHeight, xPos, yPos));
+}
+
+// ---------------------------------------------------------------------------
+// Page
+// ---------------------------------------------------------------------------
+
 void Page::render(GfxRenderer& renderer, const int fontId, const int xOffset, const int yOffset) const {
   for (auto& element : elements) {
     element->render(renderer, fontId, xOffset, yOffset);
@@ -36,8 +181,7 @@ bool Page::serialize(FsFile& file) const {
   serialization::writePod(file, count);
 
   for (const auto& el : elements) {
-    // Only PageLine exists currently
-    serialization::writePod(file, static_cast<uint8_t>(TAG_PageLine));
+    serialization::writePod(file, static_cast<uint8_t>(el->getTag()));
     if (!el->serialize(file)) {
       return false;
     }
@@ -59,11 +203,68 @@ std::unique_ptr<Page> Page::deserialize(FsFile& file) {
     if (tag == TAG_PageLine) {
       auto pl = PageLine::deserialize(file);
       page->elements.push_back(std::move(pl));
+    } else if (tag == TAG_PageTableRow) {
+      auto tr = PageTableRow::deserialize(file);
+      if (!tr) {
+        LOG_ERR("PGE", "Deserialization failed for PageTableRow at element %u", i);
+        return nullptr;
+      }
+      page->elements.push_back(std::move(tr));
+    } else if (tag == TAG_PageImage) {
+      auto pi = PageImage::deserialize(file);
+      page->elements.push_back(std::move(pi));
     } else {
-      Serial.printf("[%lu] [PGE] Deserialization failed: Unknown tag %u\n", millis(), tag);
+      LOG_ERR("PGE", "Deserialization failed: Unknown tag %u", tag);
       return nullptr;
     }
   }
 
   return page;
 }
+
+bool Page::getImageBoundingBox(int& outX, int& outY, int& outWidth, int& outHeight) const {
+  bool firstImage = true;
+  for (const auto& el : elements) {
+    if (el->getTag() == TAG_PageImage) {
+      PageImage* pi = static_cast<PageImage*>(el.get());
+      ImageBlock* ib = pi->getImageBlock();
+
+      if (firstImage) {
+        // Initialize with first image bounds
+        outX = pi->xPos;
+        outY = pi->yPos;
+        outWidth = ib->getWidth();
+        outHeight = ib->getHeight();
+        firstImage = false;
+      } else {
+        // Expand bounding box to include this image
+        int imgX = pi->xPos;
+        int imgY = pi->yPos;
+        int imgW = ib->getWidth();
+        int imgH = ib->getHeight();
+
+        // Expand right boundary
+        if (imgX + imgW > outX + outWidth) {
+          outWidth = (imgX + imgW) - outX;
+        }
+        // Expand left boundary
+        if (imgX < outX) {
+          int oldRight = outX + outWidth;
+          outX = imgX;
+          outWidth = oldRight - outX;
+        }
+        // Expand bottom boundary
+        if (imgY + imgH > outY + outHeight) {
+          outHeight = (imgY + imgH) - outY;
+        }
+        // Expand top boundary
+        if (imgY < outY) {
+          int oldBottom = outY + outHeight;
+          outY = imgY;
+          outHeight = oldBottom - outY;
+        }
+      }
+    }
+  }
+  return !firstImage;  // Return true if at least one image was found
+}

lib/Epub/Epub/Page.h

@@ -1,13 +1,17 @@
 #pragma once
 #include <HalStorage.h>
 
+#include <algorithm>
 #include <utility>
 #include <vector>
 
+#include "blocks/ImageBlock.h"
 #include "blocks/TextBlock.h"
 
 enum PageElementTag : uint8_t {
   TAG_PageLine = 1,
+  TAG_PageTableRow = 2,
+  TAG_PageImage = 3,
 };
 
 // represents something that has been added to a page
@@ -17,6 +21,7 @@ class PageElement {
   int16_t yPos;
   explicit PageElement(const int16_t xPos, const int16_t yPos) : xPos(xPos), yPos(yPos) {}
   virtual ~PageElement() = default;
+  virtual PageElementTag getTag() const = 0;
   virtual void render(GfxRenderer& renderer, int fontId, int xOffset, int yOffset) = 0;
   virtual bool serialize(FsFile& file) = 0;
 };
@@ -28,11 +33,59 @@ class PageLine final : public PageElement {
  public:
   PageLine(std::shared_ptr<TextBlock> block, const int16_t xPos, const int16_t yPos)
       : PageElement(xPos, yPos), block(std::move(block)) {}
+  const std::shared_ptr<TextBlock>& getBlock() const { return block; }
+  PageElementTag getTag() const override { return TAG_PageLine; }
   void render(GfxRenderer& renderer, int fontId, int xOffset, int yOffset) override;
   bool serialize(FsFile& file) override;
   static std::unique_ptr<PageLine> deserialize(FsFile& file);
 };
 
+/// Data for a single cell within a PageTableRow.
+struct PageTableCellData {
+  std::vector<std::shared_ptr<TextBlock>> lines;  // Laid-out text lines for this cell
+  uint16_t columnWidth = 0;                        // Width of this column in pixels
+  uint16_t xOffset = 0;                            // X offset of this cell within the row
+};
+
+/// A table row element that renders cells in a column-aligned grid with borders.
+class PageTableRow final : public PageElement {
+  std::vector<PageTableCellData> cells;
+  int16_t rowHeight;   // Total row height in pixels
+  int16_t totalWidth;  // Total table width in pixels
+  int16_t lineHeight;  // Height of one text line (for vertical positioning of cell lines)
+
+ public:
+  PageTableRow(std::vector<PageTableCellData> cells, int16_t rowHeight, int16_t totalWidth, int16_t lineHeight,
+               int16_t xPos, int16_t yPos)
+      : PageElement(xPos, yPos),
+        cells(std::move(cells)),
+        rowHeight(rowHeight),
+        totalWidth(totalWidth),
+        lineHeight(lineHeight) {}
+
+  int16_t getHeight() const { return rowHeight; }
+  PageElementTag getTag() const override { return TAG_PageTableRow; }
+  void render(GfxRenderer& renderer, int fontId, int xOffset, int yOffset) override;
+  bool serialize(FsFile& file) override;
+  static std::unique_ptr<PageTableRow> deserialize(FsFile& file);
+};
+
+// An image element on a page
+class PageImage final : public PageElement {
+  std::shared_ptr<ImageBlock> imageBlock;
+
+ public:
+  PageImage(std::shared_ptr<ImageBlock> block, const int16_t xPos, const int16_t yPos)
+      : PageElement(xPos, yPos), imageBlock(std::move(block)) {}
+  void render(GfxRenderer& renderer, int fontId, int xOffset, int yOffset) override;
+  bool serialize(FsFile& file) override;
+  PageElementTag getTag() const override { return TAG_PageImage; }
+  static std::unique_ptr<PageImage> deserialize(FsFile& file);
+
+  // Helper to get image block dimensions (needed for bounding box calculation)
+  ImageBlock* getImageBlock() const { return imageBlock.get(); }
+};
+
 class Page {
  public:
   // the list of block index and line numbers on this page
@@ -40,4 +93,15 @@ class Page {
   void render(GfxRenderer& renderer, int fontId, int xOffset, int yOffset) const;
   bool serialize(FsFile& file) const;
   static std::unique_ptr<Page> deserialize(FsFile& file);
+
+  // Check if page contains any images (used to force full refresh)
+  bool hasImages() const {
+    return std::any_of(elements.begin(), elements.end(),
+                       [](const std::shared_ptr<PageElement>& el) { return el->getTag() == TAG_PageImage; });
+  }
+
+  // Get the bounding box of all images on this page.
+  // Returns true if page has images and fills out the bounding box coordinates.
+  // If no images, returns false.
+  bool getImageBoundingBox(int& outX, int& outY, int& outWidth, int& outHeight) const;
 };

lib/Epub/Epub/ParsedText.cpp

@@ -5,7 +5,6 @@
 #include <algorithm>
 #include <cmath>
 #include <functional>
-#include <iterator>
 #include <limits>
 #include <vector>
 
@@ -32,6 +31,9 @@ void stripSoftHyphensInPlace(std::string& word) {
 // Returns the rendered width for a word while ignoring soft hyphen glyphs and optionally appending a visible hyphen.
 uint16_t measureWordWidth(const GfxRenderer& renderer, const int fontId, const std::string& word,
                           const EpdFontFamily::Style style, const bool appendHyphen = false) {
+  if (word.size() == 1 && word[0] == ' ' && !appendHyphen) {
+    return renderer.getSpaceWidth(fontId);
+  }
   const bool hasSoftHyphen = containsSoftHyphen(word);
   if (!hasSoftHyphen && !appendHyphen) {
     return renderer.getTextWidth(fontId, word.c_str(), style);
@@ -60,6 +62,13 @@ void ParsedText::addWord(std::string word, const EpdFontFamily::Style fontStyle,
   }
   wordStyles.push_back(combinedStyle);
   wordContinues.push_back(attachToPrevious);
+  forceBreakAfter.push_back(false);
+}
+
+void ParsedText::addLineBreak() {
+  if (!words.empty()) {
+    forceBreakAfter.back() = true;
+  }
 }
 
 // Consumes data to minimize memory usage
@@ -77,37 +86,26 @@ void ParsedText::layoutAndExtractLines(const GfxRenderer& renderer, const int fo
   const int spaceWidth = renderer.getSpaceWidth(fontId);
   auto wordWidths = calculateWordWidths(renderer, fontId);
 
-  // Build indexed continues vector from the parallel list for O(1) access during layout
-  std::vector<bool> continuesVec(wordContinues.begin(), wordContinues.end());
-
   std::vector<size_t> lineBreakIndices;
   if (hyphenationEnabled) {
     // Use greedy layout that can split words mid-loop when a hyphenated prefix fits.
-    lineBreakIndices = computeHyphenatedLineBreaks(renderer, fontId, pageWidth, spaceWidth, wordWidths, continuesVec);
+    lineBreakIndices = computeHyphenatedLineBreaks(renderer, fontId, pageWidth, spaceWidth, wordWidths, wordContinues);
   } else {
-    lineBreakIndices = computeLineBreaks(renderer, fontId, pageWidth, spaceWidth, wordWidths, continuesVec);
+    lineBreakIndices = computeLineBreaks(renderer, fontId, pageWidth, spaceWidth, wordWidths, wordContinues);
   }
   const size_t lineCount = includeLastLine ? lineBreakIndices.size() : lineBreakIndices.size() - 1;
 
   for (size_t i = 0; i < lineCount; ++i) {
-    extractLine(i, pageWidth, spaceWidth, wordWidths, continuesVec, lineBreakIndices, processLine);
+    extractLine(i, pageWidth, spaceWidth, wordWidths, wordContinues, lineBreakIndices, processLine);
   }
 }
 
 std::vector<uint16_t> ParsedText::calculateWordWidths(const GfxRenderer& renderer, const int fontId) {
-  const size_t totalWordCount = words.size();
-
   std::vector<uint16_t> wordWidths;
-  wordWidths.reserve(totalWordCount);
+  wordWidths.reserve(words.size());
 
-  auto wordsIt = words.begin();
-  auto wordStylesIt = wordStyles.begin();
-
-  while (wordsIt != words.end()) {
-    wordWidths.push_back(measureWordWidth(renderer, fontId, *wordsIt, *wordStylesIt));
-
-    std::advance(wordsIt, 1);
-    std::advance(wordStylesIt, 1);
+  for (size_t i = 0; i < words.size(); ++i) {
+    wordWidths.push_back(measureWordWidth(renderer, fontId, words[i], wordStyles[i]));
   }
 
   return wordWidths;
@@ -132,8 +130,7 @@ std::vector<size_t> ParsedText::computeLineBreaks(const GfxRenderer& renderer, c
     // First word needs to fit in reduced width if there's an indent
     const int effectiveWidth = i == 0 ? pageWidth - firstLineIndent : pageWidth;
     while (wordWidths[i] > effectiveWidth) {
-      if (!hyphenateWordAtIndex(i, effectiveWidth, renderer, fontId, wordWidths, /*allowFallbackBreaks=*/true,
-                                &continuesVec)) {
+      if (!hyphenateWordAtIndex(i, effectiveWidth, renderer, fontId, wordWidths, /*allowFallbackBreaks=*/true)) {
         break;
       }
     }
@@ -158,6 +155,11 @@ std::vector<size_t> ParsedText::computeLineBreaks(const GfxRenderer& renderer, c
     const int effectivePageWidth = i == 0 ? pageWidth - firstLineIndent : pageWidth;
 
     for (size_t j = i; j < totalWordCount; ++j) {
+      // If the previous word has a forced line break, this line cannot include word j
+      if (j > static_cast<size_t>(i) && !forceBreakAfter.empty() && forceBreakAfter[j - 1]) {
+        break;
+      }
+
       // Add space before word j, unless it's the first word on the line or a continuation
       const int gap = j > static_cast<size_t>(i) && !continuesVec[j] ? spaceWidth : 0;
       currlen += wordWidths[j] + gap;
@@ -166,8 +168,11 @@ std::vector<size_t> ParsedText::computeLineBreaks(const GfxRenderer& renderer, c
         break;
       }
 
-      // Cannot break after word j if the next word attaches to it (continuation group)
-      if (j + 1 < totalWordCount && continuesVec[j + 1]) {
+      // Forced line break after word j overrides continuation (must end line here)
+      const bool mustBreakHere = !forceBreakAfter.empty() && forceBreakAfter[j];
+
+      // Cannot break after word j if the next word attaches to it (unless forced)
+      if (!mustBreakHere && j + 1 < totalWordCount && continuesVec[j + 1]) {
         continue;
       }
 
@@ -190,6 +195,11 @@ std::vector<size_t> ParsedText::computeLineBreaks(const GfxRenderer& renderer, c
         dp[i] = cost;
         ans[i] = j;  // j is the index of the last word in this optimal line
       }
+
+      // After evaluating cost, enforce forced break - no more words on this line
+      if (mustBreakHere) {
+        break;
+      }
     }
 
     // Handle oversized word: if no valid configuration found, force single-word line
@@ -264,6 +274,11 @@ std::vector<size_t> ParsedText::computeHyphenatedLineBreaks(const GfxRenderer& r
 
     // Consume as many words as possible for current line, splitting when prefixes fit
     while (currentIndex < wordWidths.size()) {
+      // If the previous word has a forced line break, stop - this word starts a new line
+      if (currentIndex > lineStart && !forceBreakAfter.empty() && forceBreakAfter[currentIndex - 1]) {
+        break;
+      }
+
       const bool isFirstWord = currentIndex == lineStart;
       const int spacing = isFirstWord || continuesVec[currentIndex] ? 0 : spaceWidth;
       const int candidateWidth = spacing + wordWidths[currentIndex];
@@ -272,6 +287,11 @@ std::vector<size_t> ParsedText::computeHyphenatedLineBreaks(const GfxRenderer& r
       if (lineWidth + candidateWidth <= effectivePageWidth) {
         lineWidth += candidateWidth;
         ++currentIndex;
+
+        // If the word we just added has a forced break, end this line now
+        if (!forceBreakAfter.empty() && forceBreakAfter[currentIndex - 1]) {
+          break;
+        }
         continue;
       }
 
@@ -279,8 +299,8 @@ std::vector<size_t> ParsedText::computeHyphenatedLineBreaks(const GfxRenderer& r
       const int availableWidth = effectivePageWidth - lineWidth - spacing;
       const bool allowFallbackBreaks = isFirstWord;  // Only for first word on line
 
-      if (availableWidth > 0 && hyphenateWordAtIndex(currentIndex, availableWidth, renderer, fontId, wordWidths,
-                                                     allowFallbackBreaks, &continuesVec)) {
+      if (availableWidth > 0 &&
+          hyphenateWordAtIndex(currentIndex, availableWidth, renderer, fontId, wordWidths, allowFallbackBreaks)) {
         // Prefix now fits; append it to this line and move to next line
         lineWidth += spacing + wordWidths[currentIndex];
         ++currentIndex;
@@ -297,7 +317,12 @@ std::vector<size_t> ParsedText::computeHyphenatedLineBreaks(const GfxRenderer& r
 
     // Don't break before a continuation word (e.g., orphaned "?" after "question").
     // Backtrack to the start of the continuation group so the whole group moves to the next line.
+    // But don't backtrack past a forced break point.
     while (currentIndex > lineStart + 1 && currentIndex < wordWidths.size() && continuesVec[currentIndex]) {
+      // Don't backtrack past a forced break
+      if (!forceBreakAfter.empty() && forceBreakAfter[currentIndex - 1]) {
+        break;
+      }
       --currentIndex;
     }
 
@@ -312,20 +337,14 @@ std::vector<size_t> ParsedText::computeHyphenatedLineBreaks(const GfxRenderer& r
 // available width.
 bool ParsedText::hyphenateWordAtIndex(const size_t wordIndex, const int availableWidth, const GfxRenderer& renderer,
                                       const int fontId, std::vector<uint16_t>& wordWidths,
-                                      const bool allowFallbackBreaks, std::vector<bool>* continuesVec) {
+                                      const bool allowFallbackBreaks) {
   // Guard against invalid indices or zero available width before attempting to split.
   if (availableWidth <= 0 || wordIndex >= words.size()) {
     return false;
   }
 
-  // Get iterators to target word and style.
-  auto wordIt = words.begin();
-  auto styleIt = wordStyles.begin();
-  std::advance(wordIt, wordIndex);
-  std::advance(styleIt, wordIndex);
-
-  const std::string& word = *wordIt;
-  const auto style = *styleIt;
+  const std::string& word = words[wordIndex];
+  const auto style = wordStyles[wordIndex];
 
   // Collect candidate breakpoints (byte offsets and hyphen requirements).
   auto breakInfos = Hyphenator::breakOffsets(word, allowFallbackBreaks);
@@ -362,31 +381,26 @@ bool ParsedText::hyphenateWordAtIndex(const size_t wordIndex, const int availabl
 
   // Split the word at the selected breakpoint and append a hyphen if required.
   std::string remainder = word.substr(chosenOffset);
-  wordIt->resize(chosenOffset);
+  words[wordIndex].resize(chosenOffset);
   if (chosenNeedsHyphen) {
-    wordIt->push_back('-');
+    words[wordIndex].push_back('-');
   }
 
   // Insert the remainder word (with matching style and continuation flag) directly after the prefix.
-  auto insertWordIt = std::next(wordIt);
-  auto insertStyleIt = std::next(styleIt);
-  words.insert(insertWordIt, remainder);
-  wordStyles.insert(insertStyleIt, style);
+  words.insert(words.begin() + wordIndex + 1, remainder);
+  wordStyles.insert(wordStyles.begin() + wordIndex + 1, style);
 
   // The remainder inherits whatever continuation status the original word had with the word after it.
-  // Find the continues entry for the original word and insert the remainder's entry after it.
-  auto continuesIt = wordContinues.begin();
-  std::advance(continuesIt, wordIndex);
-  const bool originalContinuedToNext = *continuesIt;
+  const bool originalContinuedToNext = wordContinues[wordIndex];
   // The original word (now prefix) does NOT continue to remainder (hyphen separates them)
-  *continuesIt = false;
-  const auto insertContinuesIt = std::next(continuesIt);
-  wordContinues.insert(insertContinuesIt, originalContinuedToNext);
+  wordContinues[wordIndex] = false;
+  wordContinues.insert(wordContinues.begin() + wordIndex + 1, originalContinuedToNext);
 
-  // Keep the indexed vector in sync if provided
-  if (continuesVec) {
-    (*continuesVec)[wordIndex] = false;
-    continuesVec->insert(continuesVec->begin() + wordIndex + 1, originalContinuedToNext);
+  // Forced break belongs to the original whole word; transfer it to the remainder (last part).
+  if (!forceBreakAfter.empty()) {
+    const bool originalForceBreak = forceBreakAfter[wordIndex];
+    forceBreakAfter[wordIndex] = false;  // prefix doesn't force break
+    forceBreakAfter.insert(forceBreakAfter.begin() + wordIndex + 1, originalForceBreak);
   }
 
   // Update cached widths to reflect the new prefix/remainder pairing.
@@ -447,7 +461,8 @@ void ParsedText::extractLine(const size_t breakIndex, const int pageWidth, const
 
   // Pre-calculate X positions for words
   // Continuation words attach to the previous word with no space before them
-  std::list<uint16_t> lineXPos;
+  std::vector<uint16_t> lineXPos;
+  lineXPos.reserve(lineWordCount);
 
   for (size_t wordIdx = 0; wordIdx < lineWordCount; wordIdx++) {
     const uint16_t currentWordWidth = wordWidths[lastBreakAt + wordIdx];
@@ -460,23 +475,10 @@ void ParsedText::extractLine(const size_t breakIndex, const int pageWidth, const
     xpos += currentWordWidth + (nextIsContinuation ? 0 : spacing);
   }
 
-  // Iterators always start at the beginning as we are moving content with splice below
-  auto wordEndIt = words.begin();
-  auto wordStyleEndIt = wordStyles.begin();
-  auto wordContinuesEndIt = wordContinues.begin();
-  std::advance(wordEndIt, lineWordCount);
-  std::advance(wordStyleEndIt, lineWordCount);
-  std::advance(wordContinuesEndIt, lineWordCount);
-
-  // *** CRITICAL STEP: CONSUME DATA USING SPLICE ***
-  std::list<std::string> lineWords;
-  lineWords.splice(lineWords.begin(), words, words.begin(), wordEndIt);
-  std::list<EpdFontFamily::Style> lineWordStyles;
-  lineWordStyles.splice(lineWordStyles.begin(), wordStyles, wordStyles.begin(), wordStyleEndIt);
-
-  // Consume continues flags (not passed to TextBlock, but must be consumed to stay in sync)
-  std::list<bool> lineContinues;
-  lineContinues.splice(lineContinues.begin(), wordContinues, wordContinues.begin(), wordContinuesEndIt);
+  // Build line data by moving from the original vectors using index range
+  std::vector<std::string> lineWords(std::make_move_iterator(words.begin() + lastBreakAt),
+                                     std::make_move_iterator(words.begin() + lineBreak));
+  std::vector<EpdFontFamily::Style> lineWordStyles(wordStyles.begin() + lastBreakAt, wordStyles.begin() + lineBreak);
 
   for (auto& word : lineWords) {
     if (containsSoftHyphen(word)) {
@@ -487,3 +489,22 @@ void ParsedText::extractLine(const size_t breakIndex, const int pageWidth, const
   processLine(
       std::make_shared<TextBlock>(std::move(lineWords), std::move(lineXPos), std::move(lineWordStyles), blockStyle));
 }
+
+uint16_t ParsedText::getNaturalWidth(const GfxRenderer& renderer, const int fontId) const {
+  if (words.empty()) {
+    return 0;
+  }
+
+  const int spaceWidth = renderer.getSpaceWidth(fontId);
+  int totalWidth = 0;
+
+  for (size_t i = 0; i < words.size(); ++i) {
+    totalWidth += measureWordWidth(renderer, fontId, words[i], wordStyles[i]);
+    // Add a space before this word unless it's the first word or a continuation
+    if (i > 0 && !wordContinues[i]) {
+      totalWidth += spaceWidth;
+    }
+  }
+
+  return static_cast<uint16_t>(std::min(totalWidth, static_cast<int>(UINT16_MAX)));
+}

lib/Epub/Epub/ParsedText.h

@@ -3,7 +3,6 @@
 #include <EpdFontFamily.h>
 
 #include <functional>
-#include <list>
 #include <memory>
 #include <string>
 #include <vector>
@@ -14,9 +13,10 @@
 class GfxRenderer;
 
 class ParsedText {
-  std::list<std::string> words;
-  std::list<EpdFontFamily::Style> wordStyles;
-  std::list<bool> wordContinues;  // true = word attaches to previous (no space before it)
+  std::vector<std::string> words;
+  std::vector<EpdFontFamily::Style> wordStyles;
+  std::vector<bool> wordContinues;    // true = word attaches to previous (no space before it)
+  std::vector<bool> forceBreakAfter;  // true = mandatory line break after this word (e.g. <br> in table cells)
   BlockStyle blockStyle;
   bool extraParagraphSpacing;
   bool hyphenationEnabled;
@@ -28,8 +28,7 @@ class ParsedText {
                                                   int spaceWidth, std::vector<uint16_t>& wordWidths,
                                                   std::vector<bool>& continuesVec);
   bool hyphenateWordAtIndex(size_t wordIndex, int availableWidth, const GfxRenderer& renderer, int fontId,
-                            std::vector<uint16_t>& wordWidths, bool allowFallbackBreaks,
-                            std::vector<bool>* continuesVec = nullptr);
+                            std::vector<uint16_t>& wordWidths, bool allowFallbackBreaks);
   void extractLine(size_t breakIndex, int pageWidth, int spaceWidth, const std::vector<uint16_t>& wordWidths,
                    const std::vector<bool>& continuesVec, const std::vector<size_t>& lineBreakIndices,
                    const std::function<void(std::shared_ptr<TextBlock>)>& processLine);
@@ -42,6 +41,10 @@ class ParsedText {
   ~ParsedText() = default;
 
   void addWord(std::string word, EpdFontFamily::Style fontStyle, bool underline = false, bool attachToPrevious = false);
+
+  /// Mark a forced line break after the last word (e.g. for <br> within table cells).
+  /// If no words have been added yet, this is a no-op.
+  void addLineBreak();
   void setBlockStyle(const BlockStyle& blockStyle) { this->blockStyle = blockStyle; }
   BlockStyle& getBlockStyle() { return blockStyle; }
   size_t size() const { return words.size(); }
@@ -49,4 +52,9 @@ class ParsedText {
   void layoutAndExtractLines(const GfxRenderer& renderer, int fontId, uint16_t viewportWidth,
                              const std::function<void(std::shared_ptr<TextBlock>)>& processLine,
                              bool includeLastLine = true);
+
+  /// Returns the "natural" width of the content if it were laid out on a single line
+  /// (sum of word widths + space widths between non-continuation words).
+  /// Used by table layout to determine column widths before line-breaking.
+  uint16_t getNaturalWidth(const GfxRenderer& renderer, int fontId) const;
 };

lib/Epub/Epub/Section.cpp

@@ -1,6 +1,7 @@
 #include "Section.h"
 
 #include <HalStorage.h>
+#include <Logging.h>
 #include <Serialization.h>
 
 #include "Page.h"
@@ -8,7 +9,7 @@
 #include "parsers/ChapterHtmlSlimParser.h"
 
 namespace {
-constexpr uint8_t SECTION_FILE_VERSION = 12;
+constexpr uint8_t SECTION_FILE_VERSION = 13;
 constexpr uint32_t HEADER_SIZE = sizeof(uint8_t) + sizeof(int) + sizeof(float) + sizeof(bool) + sizeof(uint8_t) +
                                  sizeof(uint16_t) + sizeof(uint16_t) + sizeof(uint16_t) + sizeof(bool) + sizeof(bool) +
                                  sizeof(uint32_t);
@@ -16,16 +17,16 @@ constexpr uint32_t HEADER_SIZE = sizeof(uint8_t) + sizeof(int) + sizeof(float) +
 
 uint32_t Section::onPageComplete(std::unique_ptr<Page> page) {
   if (!file) {
-    Serial.printf("[%lu] [SCT] File not open for writing page %d\n", millis(), pageCount);
+    LOG_ERR("SCT", "File not open for writing page %d", pageCount);
     return 0;
   }
 
   const uint32_t position = file.position();
   if (!page->serialize(file)) {
-    Serial.printf("[%lu] [SCT] Failed to serialize page %d\n", millis(), pageCount);
+    LOG_ERR("SCT", "Failed to serialize page %d", pageCount);
     return 0;
   }
-  Serial.printf("[%lu] [SCT] Page %d processed\n", millis(), pageCount);
+  LOG_DBG("SCT", "Page %d processed", pageCount);
 
   pageCount++;
   return position;
@@ -36,7 +37,7 @@ void Section::writeSectionFileHeader(const int fontId, const float lineCompressi
                                      const uint16_t viewportHeight, const bool hyphenationEnabled,
                                      const bool embeddedStyle) {
   if (!file) {
-    Serial.printf("[%lu] [SCT] File not open for writing header\n", millis());
+    LOG_DBG("SCT", "File not open for writing header");
     return;
   }
   static_assert(HEADER_SIZE == sizeof(SECTION_FILE_VERSION) + sizeof(fontId) + sizeof(lineCompression) +
@@ -70,7 +71,7 @@ bool Section::loadSectionFile(const int fontId, const float lineCompression, con
     serialization::readPod(file, version);
     if (version != SECTION_FILE_VERSION) {
       file.close();
-      Serial.printf("[%lu] [SCT] Deserialization failed: Unknown version %u\n", millis(), version);
+      LOG_ERR("SCT", "Deserialization failed: Unknown version %u", version);
       clearCache();
       return false;
     }
@@ -96,7 +97,7 @@ bool Section::loadSectionFile(const int fontId, const float lineCompression, con
         viewportWidth != fileViewportWidth || viewportHeight != fileViewportHeight ||
         hyphenationEnabled != fileHyphenationEnabled || embeddedStyle != fileEmbeddedStyle) {
       file.close();
-      Serial.printf("[%lu] [SCT] Deserialization failed: Parameters do not match\n", millis());
+      LOG_ERR("SCT", "Deserialization failed: Parameters do not match");
       clearCache();
       return false;
     }
@@ -104,23 +105,23 @@ bool Section::loadSectionFile(const int fontId, const float lineCompression, con
 
   serialization::readPod(file, pageCount);
   file.close();
-  Serial.printf("[%lu] [SCT] Deserialization succeeded: %d pages\n", millis(), pageCount);
+  LOG_DBG("SCT", "Deserialization succeeded: %d pages", pageCount);
   return true;
 }
 
 // Your updated class method (assuming you are using the 'SD' object, which is a wrapper for a specific filesystem)
 bool Section::clearCache() const {
   if (!Storage.exists(filePath.c_str())) {
-    Serial.printf("[%lu] [SCT] Cache does not exist, no action needed\n", millis());
+    LOG_DBG("SCT", "Cache does not exist, no action needed");
     return true;
   }
 
   if (!Storage.remove(filePath.c_str())) {
-    Serial.printf("[%lu] [SCT] Failed to clear cache\n", millis());
+    LOG_ERR("SCT", "Failed to clear cache");
     return false;
   }
 
-  Serial.printf("[%lu] [SCT] Cache cleared successfully\n", millis());
+  LOG_DBG("SCT", "Cache cleared successfully");
   return true;
 }
 
@@ -142,7 +143,7 @@ bool Section::createSectionFile(const int fontId, const float lineCompression, c
   uint32_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);
+      LOG_DBG("SCT", "Retrying stream (attempt %d)...", attempt + 1);
       delay(50);  // Brief delay before retry
     }
 
@@ -162,16 +163,16 @@ bool Section::createSectionFile(const int fontId, const float lineCompression, c
     // If streaming failed, remove the incomplete file immediately
     if (!success && Storage.exists(tmpHtmlPath.c_str())) {
       Storage.remove(tmpHtmlPath.c_str());
-      Serial.printf("[%lu] [SCT] Removed incomplete temp file after failed attempt\n", millis());
+      LOG_DBG("SCT", "Removed incomplete temp file after failed attempt");
     }
   }
 
   if (!success) {
-    Serial.printf("[%lu] [SCT] Failed to stream item contents to temp file after retries\n", millis());
+    LOG_ERR("SCT", "Failed to stream item contents to temp file after retries");
     return false;
   }
 
-  Serial.printf("[%lu] [SCT] Streamed temp HTML to %s (%d bytes)\n", millis(), tmpHtmlPath.c_str(), fileSize);
+  LOG_DBG("SCT", "Streamed temp HTML to %s (%d bytes)", tmpHtmlPath.c_str(), fileSize);
 
   if (!Storage.openFileForWrite("SCT", filePath, file)) {
     return false;
@@ -180,19 +181,36 @@ bool Section::createSectionFile(const int fontId, const float lineCompression, c
                          viewportHeight, hyphenationEnabled, embeddedStyle);
   std::vector<uint32_t> lut = {};
 
+  // Derive the content base directory and image cache path prefix for the parser
+  size_t lastSlash = localPath.find_last_of('/');
+  std::string contentBase = (lastSlash != std::string::npos) ? localPath.substr(0, lastSlash + 1) : "";
+  std::string imageBasePath = epub->getCachePath() + "/img_" + std::to_string(spineIndex) + "_";
+
+  CssParser* cssParser = nullptr;
+  if (embeddedStyle) {
+    cssParser = epub->getCssParser();
+    if (cssParser) {
+      if (!cssParser->loadFromCache()) {
+        LOG_ERR("SCT", "Failed to load CSS from cache");
+      }
+    }
+  }
   ChapterHtmlSlimParser visitor(
-      tmpHtmlPath, renderer, fontId, lineCompression, extraParagraphSpacing, paragraphAlignment, viewportWidth,
+      epub, tmpHtmlPath, renderer, fontId, lineCompression, extraParagraphSpacing, paragraphAlignment, viewportWidth,
       viewportHeight, hyphenationEnabled,
       [this, &lut](std::unique_ptr<Page> page) { lut.emplace_back(this->onPageComplete(std::move(page))); },
-      embeddedStyle, popupFn, embeddedStyle ? epub->getCssParser() : nullptr);
+      embeddedStyle, contentBase, imageBasePath, popupFn, cssParser);
   Hyphenator::setPreferredLanguage(epub->getLanguage());
   success = visitor.parseAndBuildPages();
 
   Storage.remove(tmpHtmlPath.c_str());
   if (!success) {
-    Serial.printf("[%lu] [SCT] Failed to parse XML and build pages\n", millis());
+    LOG_ERR("SCT", "Failed to parse XML and build pages");
     file.close();
     Storage.remove(filePath.c_str());
+    if (cssParser) {
+      cssParser->clear();
+    }
     return false;
   }
 
@@ -208,7 +226,7 @@ bool Section::createSectionFile(const int fontId, const float lineCompression, c
   }
 
   if (hasFailedLutRecords) {
-    Serial.printf("[%lu] [SCT] Failed to write LUT due to invalid page positions\n", millis());
+    LOG_ERR("SCT", "Failed to write LUT due to invalid page positions");
     file.close();
     Storage.remove(filePath.c_str());
     return false;
@@ -219,6 +237,9 @@ bool Section::createSectionFile(const int fontId, const float lineCompression, c
   serialization::writePod(file, pageCount);
   serialization::writePod(file, lutOffset);
   file.close();
+  if (cssParser) {
+    cssParser->clear();
+  }
   return true;
 }
 

lib/Epub/Epub/TableData.h

@@ -0,0 +1,29 @@
+#pragma once
+
+#include <memory>
+#include <vector>
+
+#include "ParsedText.h"
+#include "css/CssStyle.h"
+
+/// A single cell in a table row.
+struct TableCell {
+  std::unique_ptr<ParsedText> content;
+  bool isHeader = false;   // true for <th>, false for <td>
+  int colspan = 1;          // number of logical columns this cell spans
+  CssLength widthHint;      // width hint from HTML attribute or CSS (if hasWidthHint)
+  bool hasWidthHint = false;
+};
+
+/// A single row in a table.
+struct TableRow {
+  std::vector<TableCell> cells;
+};
+
+/// Buffered table data collected during SAX parsing.
+/// The entire table must be buffered before layout because column widths
+/// depend on content across all rows.
+struct TableData {
+  std::vector<TableRow> rows;
+  std::vector<CssLength> colWidthHints;  // width hints from <col> tags, indexed by logical column
+};

lib/Epub/Epub/blocks/Block.h

@@ -8,7 +8,7 @@ typedef enum { TEXT_BLOCK, IMAGE_BLOCK } BlockType;
 class Block {
  public:
   virtual ~Block() = default;
-  virtual void layout(GfxRenderer& renderer) = 0;
+
   virtual BlockType getType() = 0;
   virtual bool isEmpty() = 0;
   virtual void finish() {}

lib/Epub/Epub/blocks/ImageBlock.cpp

@@ -0,0 +1,175 @@
+#include "ImageBlock.h"
+
+#include <FsHelpers.h>
+#include <GfxRenderer.h>
+#include <HardwareSerial.h>
+#include <SDCardManager.h>
+#include <Serialization.h>
+
+#include "../converters/DitherUtils.h"
+#include "../converters/ImageDecoderFactory.h"
+
+// Cache file format:
+// - uint16_t width
+// - uint16_t height
+// - uint8_t pixels[...] - 2 bits per pixel, packed (4 pixels per byte), row-major order
+
+ImageBlock::ImageBlock(const std::string& imagePath, int16_t width, int16_t height)
+    : imagePath(imagePath), width(width), height(height) {}
+
+bool ImageBlock::imageExists() const { return Storage.exists(imagePath.c_str()); }
+
+namespace {
+
+std::string getCachePath(const std::string& imagePath) {
+  // Replace extension with .pxc (pixel cache)
+  size_t dotPos = imagePath.rfind('.');
+  if (dotPos != std::string::npos) {
+    return imagePath.substr(0, dotPos) + ".pxc";
+  }
+  return imagePath + ".pxc";
+}
+
+bool renderFromCache(GfxRenderer& renderer, const std::string& cachePath, int x, int y, int expectedWidth,
+                     int expectedHeight) {
+  FsFile cacheFile;
+  if (!Storage.openFileForRead("IMG", cachePath, cacheFile)) {
+    return false;
+  }
+
+  uint16_t cachedWidth, cachedHeight;
+  if (cacheFile.read(&cachedWidth, 2) != 2 || cacheFile.read(&cachedHeight, 2) != 2) {
+    cacheFile.close();
+    return false;
+  }
+
+  // Verify dimensions are close (allow 1 pixel tolerance for rounding differences)
+  int widthDiff = abs(cachedWidth - expectedWidth);
+  int heightDiff = abs(cachedHeight - expectedHeight);
+  if (widthDiff > 1 || heightDiff > 1) {
+    Serial.printf("[%lu] [IMG] Cache dimension mismatch: %dx%d vs %dx%d\n", millis(), cachedWidth, cachedHeight,
+                  expectedWidth, expectedHeight);
+    cacheFile.close();
+    return false;
+  }
+
+  // Use cached dimensions for rendering (they're the actual decoded size)
+  expectedWidth = cachedWidth;
+  expectedHeight = cachedHeight;
+
+  Serial.printf("[%lu] [IMG] Loading from cache: %s (%dx%d)\n", millis(), cachePath.c_str(), cachedWidth, cachedHeight);
+
+  // Read and render row by row to minimize memory usage
+  const int bytesPerRow = (cachedWidth + 3) / 4;  // 2 bits per pixel, 4 pixels per byte
+  uint8_t* rowBuffer = (uint8_t*)malloc(bytesPerRow);
+  if (!rowBuffer) {
+    Serial.printf("[%lu] [IMG] Failed to allocate row buffer\n", millis());
+    cacheFile.close();
+    return false;
+  }
+
+  for (int row = 0; row < cachedHeight; row++) {
+    if (cacheFile.read(rowBuffer, bytesPerRow) != bytesPerRow) {
+      Serial.printf("[%lu] [IMG] Cache read error at row %d\n", millis(), row);
+      free(rowBuffer);
+      cacheFile.close();
+      return false;
+    }
+
+    int destY = y + row;
+    for (int col = 0; col < cachedWidth; col++) {
+      int byteIdx = col / 4;
+      int bitShift = 6 - (col % 4) * 2;  // MSB first within byte
+      uint8_t pixelValue = (rowBuffer[byteIdx] >> bitShift) & 0x03;
+
+      drawPixelWithRenderMode(renderer, x + col, destY, pixelValue);
+    }
+  }
+
+  free(rowBuffer);
+  cacheFile.close();
+  Serial.printf("[%lu] [IMG] Cache render complete\n", millis());
+  return true;
+}
+
+}  // namespace
+
+void ImageBlock::render(GfxRenderer& renderer, const int x, const int y) {
+  Serial.printf("[%lu] [IMG] Rendering image at %d,%d: %s (%dx%d)\n", millis(), x, y, imagePath.c_str(), width, height);
+
+  const int screenWidth = renderer.getScreenWidth();
+  const int screenHeight = renderer.getScreenHeight();
+
+  // Bounds check render position using logical screen dimensions
+  if (x < 0 || y < 0 || x + width > screenWidth || y + height > screenHeight) {
+    Serial.printf("[%lu] [IMG] Invalid render position: (%d,%d) size (%dx%d) screen (%dx%d)\n", millis(), x, y, width,
+                  height, screenWidth, screenHeight);
+    return;
+  }
+
+  // Try to render from cache first
+  std::string cachePath = getCachePath(imagePath);
+  if (renderFromCache(renderer, cachePath, x, y, width, height)) {
+    return;  // Successfully rendered from cache
+  }
+
+  // No cache - need to decode the image
+  // Check if image file exists
+  FsFile file;
+  if (!Storage.openFileForRead("IMG", imagePath, file)) {
+    Serial.printf("[%lu] [IMG] Image file not found: %s\n", millis(), imagePath.c_str());
+    return;
+  }
+  size_t fileSize = file.size();
+  file.close();
+
+  if (fileSize == 0) {
+    Serial.printf("[%lu] [IMG] Image file is empty: %s\n", millis(), imagePath.c_str());
+    return;
+  }
+
+  Serial.printf("[%lu] [IMG] Decoding and caching: %s\n", millis(), imagePath.c_str());
+
+  RenderConfig config;
+  config.x = x;
+  config.y = y;
+  config.maxWidth = width;
+  config.maxHeight = height;
+  config.useGrayscale = true;
+  config.useDithering = true;
+  config.performanceMode = false;
+  config.useExactDimensions = true;  // Use pre-calculated dimensions to avoid rounding mismatches
+  config.cachePath = cachePath;      // Enable caching during decode
+
+  ImageToFramebufferDecoder* decoder = ImageDecoderFactory::getDecoder(imagePath);
+  if (!decoder) {
+    Serial.printf("[%lu] [IMG] No decoder found for image: %s\n", millis(), imagePath.c_str());
+    return;
+  }
+
+  Serial.printf("[%lu] [IMG] Using %s decoder\n", millis(), decoder->getFormatName());
+
+  bool success = decoder->decodeToFramebuffer(imagePath, renderer, config);
+  if (!success) {
+    Serial.printf("[%lu] [IMG] Failed to decode image: %s\n", millis(), imagePath.c_str());
+    return;
+  }
+
+  Serial.printf("[%lu] [IMG] Decode successful\n", millis());
+}
+
+bool ImageBlock::serialize(FsFile& file) {
+  serialization::writeString(file, imagePath);
+  serialization::writePod(file, width);
+  serialization::writePod(file, height);
+  return true;
+}
+
+std::unique_ptr<ImageBlock> ImageBlock::deserialize(FsFile& file) {
+  std::string path;
+  serialization::readString(file, path);
+  int16_t w, h;
+  serialization::readPod(file, w);
+  serialization::readPod(file, h);
+  return std::unique_ptr<ImageBlock>(new ImageBlock(path, w, h));
+}

lib/Epub/Epub/blocks/ImageBlock.h

@@ -0,0 +1,31 @@
+#pragma once
+#include <SdFat.h>
+
+#include <memory>
+#include <string>
+
+#include "Block.h"
+
+class ImageBlock final : public Block {
+ public:
+  ImageBlock(const std::string& imagePath, int16_t width, int16_t height);
+  ~ImageBlock() override = default;
+
+  const std::string& getImagePath() const { return imagePath; }
+  int16_t getWidth() const { return width; }
+  int16_t getHeight() const { return height; }
+
+  bool imageExists() const;
+
+  BlockType getType() override { return IMAGE_BLOCK; }
+  bool isEmpty() override { return false; }
+
+  void render(GfxRenderer& renderer, const int x, const int y);
+  bool serialize(FsFile& file);
+  static std::unique_ptr<ImageBlock> deserialize(FsFile& file);
+
+ private:
+  std::string imagePath;
+  int16_t width;
+  int16_t height;
+};

lib/Epub/Epub/blocks/TextBlock.cpp

@@ -1,26 +1,24 @@
 #include "TextBlock.h"
 
 #include <GfxRenderer.h>
+#include <Logging.h>
 #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());
+    LOG_ERR("TXB", "Render skipped: size mismatch (words=%u, xpos=%u, styles=%u)\n", (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 (size_t i = 0; i < words.size(); i++) {
-    const int wordX = *wordXposIt + x;
-    const EpdFontFamily::Style currentStyle = *wordStylesIt;
-    renderer.drawText(fontId, wordX, y, wordIt->c_str(), true, currentStyle);
+    const int wordX = wordXpos[i] + x;
+    const EpdFontFamily::Style currentStyle = wordStyles[i];
+    renderer.drawText(fontId, wordX, y, words[i].c_str(), true, currentStyle);
 
     if ((currentStyle & EpdFontFamily::UNDERLINE) != 0) {
-      const std::string& w = *wordIt;
+      const std::string& w = words[i];
       const int fullWordWidth = renderer.getTextWidth(fontId, w.c_str(), currentStyle);
       // y is the top of the text line; add ascender to reach baseline, then offset 2px below
       const int underlineY = y + renderer.getFontAscenderSize(fontId) + 2;
@@ -40,17 +38,13 @@ void TextBlock::render(const GfxRenderer& renderer, const int fontId, const int
 
       renderer.drawLine(startX, underlineY, startX + underlineWidth, underlineY, true);
     }
-
-    std::advance(wordIt, 1);
-    std::advance(wordStylesIt, 1);
-    std::advance(wordXposIt, 1);
   }
 }
 
 bool TextBlock::serialize(FsFile& file) const {
   if (words.size() != wordXpos.size() || words.size() != wordStyles.size()) {
-    Serial.printf("[%lu] [TXB] Serialization failed: size mismatch (words=%u, xpos=%u, styles=%u)\n", millis(),
-                  words.size(), wordXpos.size(), wordStyles.size());
+    LOG_ERR("TXB", "Serialization failed: size mismatch (words=%u, xpos=%u, styles=%u)\n", words.size(),
+            wordXpos.size(), wordStyles.size());
     return false;
   }
 
@@ -79,17 +73,17 @@ bool TextBlock::serialize(FsFile& file) const {
 
 std::unique_ptr<TextBlock> TextBlock::deserialize(FsFile& file) {
   uint16_t wc;
-  std::list<std::string> words;
-  std::list<uint16_t> wordXpos;
-  std::list<EpdFontFamily::Style> wordStyles;
+  std::vector<std::string> words;
+  std::vector<uint16_t> wordXpos;
+  std::vector<EpdFontFamily::Style> wordStyles;
   BlockStyle blockStyle;
 
   // Word count
   serialization::readPod(file, wc);
 
-  // Sanity check: prevent allocation of unreasonably large lists (max 10000 words per block)
+  // Sanity check: prevent allocation of unreasonably large vectors (max 10000 words per block)
   if (wc > 10000) {
-    Serial.printf("[%lu] [TXB] Deserialization failed: word count %u exceeds maximum\n", millis(), wc);
+    LOG_ERR("TXB", "Deserialization failed: word count %u exceeds maximum", wc);
     return nullptr;
   }
 

lib/Epub/Epub/blocks/TextBlock.h

@@ -2,9 +2,9 @@
 #include <EpdFontFamily.h>
 #include <HalStorage.h>
 
-#include <list>
 #include <memory>
 #include <string>
+#include <vector>
 
 #include "Block.h"
 #include "BlockStyle.h"
@@ -12,14 +12,14 @@
 // Represents a line of text on a page
 class TextBlock final : public Block {
  private:
-  std::list<std::string> words;
-  std::list<uint16_t> wordXpos;
-  std::list<EpdFontFamily::Style> wordStyles;
+  std::vector<std::string> words;
+  std::vector<uint16_t> wordXpos;
+  std::vector<EpdFontFamily::Style> wordStyles;
   BlockStyle blockStyle;
 
  public:
-  explicit TextBlock(std::list<std::string> words, std::list<uint16_t> word_xpos,
-                     std::list<EpdFontFamily::Style> word_styles, const BlockStyle& blockStyle = BlockStyle())
+  explicit TextBlock(std::vector<std::string> words, std::vector<uint16_t> word_xpos,
+                     std::vector<EpdFontFamily::Style> word_styles, const BlockStyle& blockStyle = BlockStyle())
       : words(std::move(words)),
         wordXpos(std::move(word_xpos)),
         wordStyles(std::move(word_styles)),
@@ -27,8 +27,10 @@ class TextBlock final : public Block {
   ~TextBlock() override = default;
   void setBlockStyle(const BlockStyle& blockStyle) { this->blockStyle = blockStyle; }
   const BlockStyle& getBlockStyle() const { return blockStyle; }
+  const std::vector<std::string>& getWords() const { return words; }
+  const std::vector<uint16_t>& getWordXpos() const { return wordXpos; }
+  const std::vector<EpdFontFamily::Style>& getWordStyles() const { return wordStyles; }
   bool isEmpty() override { return words.empty(); }
-  void layout(GfxRenderer& renderer) override {};
   // given a renderer works out where to break the words into lines
   void render(const GfxRenderer& renderer, int fontId, int x, int y) const;
   BlockType getType() override { return TEXT_BLOCK; }

lib/Epub/Epub/converters/DitherUtils.h

@@ -0,0 +1,40 @@
+#pragma once
+
+#include <GfxRenderer.h>
+#include <stdint.h>
+
+// 4x4 Bayer matrix for ordered dithering
+inline const uint8_t bayer4x4[4][4] = {
+    {0, 8, 2, 10},
+    {12, 4, 14, 6},
+    {3, 11, 1, 9},
+    {15, 7, 13, 5},
+};
+
+// Apply Bayer dithering and quantize to 4 levels (0-3)
+// Stateless - works correctly with any pixel processing order
+inline uint8_t applyBayerDither4Level(uint8_t gray, int x, int y) {
+  int bayer = bayer4x4[y & 3][x & 3];
+  int dither = (bayer - 8) * 5;  // Scale to +/-40 (half of quantization step 85)
+
+  int adjusted = gray + dither;
+  if (adjusted < 0) adjusted = 0;
+  if (adjusted > 255) adjusted = 255;
+
+  if (adjusted < 64) return 0;
+  if (adjusted < 128) return 1;
+  if (adjusted < 192) return 2;
+  return 3;
+}
+
+// Draw a pixel respecting the current render mode for grayscale support
+inline void drawPixelWithRenderMode(GfxRenderer& renderer, int x, int y, uint8_t pixelValue) {
+  GfxRenderer::RenderMode renderMode = renderer.getRenderMode();
+  if (renderMode == GfxRenderer::BW && pixelValue < 3) {
+    renderer.drawPixel(x, y, true);
+  } else if (renderMode == GfxRenderer::GRAYSCALE_MSB && (pixelValue == 1 || pixelValue == 2)) {
+    renderer.drawPixel(x, y, false);
+  } else if (renderMode == GfxRenderer::GRAYSCALE_LSB && pixelValue == 1) {
+    renderer.drawPixel(x, y, false);
+  }
+}

lib/Epub/Epub/converters/ImageDecoderFactory.cpp

@@ -0,0 +1,42 @@
+#include "ImageDecoderFactory.h"
+
+#include <HardwareSerial.h>
+
+#include <memory>
+#include <string>
+
+#include "JpegToFramebufferConverter.h"
+#include "PngToFramebufferConverter.h"
+
+std::unique_ptr<JpegToFramebufferConverter> ImageDecoderFactory::jpegDecoder = nullptr;
+std::unique_ptr<PngToFramebufferConverter> ImageDecoderFactory::pngDecoder = nullptr;
+
+ImageToFramebufferDecoder* ImageDecoderFactory::getDecoder(const std::string& imagePath) {
+  std::string ext = imagePath;
+  size_t dotPos = ext.rfind('.');
+  if (dotPos != std::string::npos) {
+    ext = ext.substr(dotPos);
+    for (auto& c : ext) {
+      c = tolower(c);
+    }
+  } else {
+    ext = "";
+  }
+
+  if (JpegToFramebufferConverter::supportsFormat(ext)) {
+    if (!jpegDecoder) {
+      jpegDecoder.reset(new JpegToFramebufferConverter());
+    }
+    return jpegDecoder.get();
+  } else if (PngToFramebufferConverter::supportsFormat(ext)) {
+    if (!pngDecoder) {
+      pngDecoder.reset(new PngToFramebufferConverter());
+    }
+    return pngDecoder.get();
+  }
+
+  Serial.printf("[%lu] [DEC] No decoder found for image: %s\n", millis(), imagePath.c_str());
+  return nullptr;
+}
+
+bool ImageDecoderFactory::isFormatSupported(const std::string& imagePath) { return getDecoder(imagePath) != nullptr; }

lib/Epub/Epub/converters/ImageDecoderFactory.h

@@ -0,0 +1,20 @@
+#pragma once
+#include <cstdint>
+#include <memory>
+#include <string>
+
+#include "ImageToFramebufferDecoder.h"
+
+class JpegToFramebufferConverter;
+class PngToFramebufferConverter;
+
+class ImageDecoderFactory {
+ public:
+  // Returns non-owning pointer - factory owns the decoder lifetime
+  static ImageToFramebufferDecoder* getDecoder(const std::string& imagePath);
+  static bool isFormatSupported(const std::string& imagePath);
+
+ private:
+  static std::unique_ptr<JpegToFramebufferConverter> jpegDecoder;
+  static std::unique_ptr<PngToFramebufferConverter> pngDecoder;
+};

lib/Epub/Epub/converters/ImageToFramebufferDecoder.cpp

@@ -0,0 +1,18 @@
+#include "ImageToFramebufferDecoder.h"
+
+#include <Arduino.h>
+#include <HardwareSerial.h>
+
+bool ImageToFramebufferDecoder::validateImageDimensions(int width, int height, const std::string& format) {
+  if (width * height > MAX_SOURCE_PIXELS) {
+    Serial.printf("[%lu] [IMG] Image too large (%dx%d = %d pixels %s), max supported: %d pixels\n", millis(), width,
+                  height, width * height, format.c_str(), MAX_SOURCE_PIXELS);
+    return false;
+  }
+  return true;
+}
+
+void ImageToFramebufferDecoder::warnUnsupportedFeature(const std::string& feature, const std::string& imagePath) {
+  Serial.printf("[%lu] [IMG] Warning: Unsupported feature '%s' in image '%s'. Image may not display correctly.\n",
+                millis(), feature.c_str(), imagePath.c_str());
+}

lib/Epub/Epub/converters/ImageToFramebufferDecoder.h

@@ -0,0 +1,40 @@
+#pragma once
+#include <SdFat.h>
+
+#include <memory>
+#include <string>
+
+class GfxRenderer;
+
+struct ImageDimensions {
+  int16_t width;
+  int16_t height;
+};
+
+struct RenderConfig {
+  int x, y;
+  int maxWidth, maxHeight;
+  bool useGrayscale = true;
+  bool useDithering = true;
+  bool performanceMode = false;
+  bool useExactDimensions = false;  // If true, use maxWidth/maxHeight as exact output size (no recalculation)
+  std::string cachePath;            // If non-empty, decoder will write pixel cache to this path
+};
+
+class ImageToFramebufferDecoder {
+ public:
+  virtual ~ImageToFramebufferDecoder() = default;
+
+  virtual bool decodeToFramebuffer(const std::string& imagePath, GfxRenderer& renderer, const RenderConfig& config) = 0;
+
+  virtual bool getDimensions(const std::string& imagePath, ImageDimensions& dims) const = 0;
+
+  virtual const char* getFormatName() const = 0;
+
+ protected:
+  // Size validation helpers
+  static constexpr int MAX_SOURCE_PIXELS = 3145728;  // 2048 * 1536
+
+  bool validateImageDimensions(int width, int height, const std::string& format);
+  void warnUnsupportedFeature(const std::string& feature, const std::string& imagePath);
+};

lib/Epub/Epub/converters/JpegToFramebufferConverter.cpp

@@ -0,0 +1,298 @@
+#include "JpegToFramebufferConverter.h"
+
+#include <GfxRenderer.h>
+#include <HardwareSerial.h>
+#include <SDCardManager.h>
+#include <SdFat.h>
+#include <picojpeg.h>
+
+#include <cstdio>
+#include <cstring>
+
+#include "DitherUtils.h"
+#include "PixelCache.h"
+
+struct JpegContext {
+  FsFile& file;
+  uint8_t buffer[512];
+  size_t bufferPos;
+  size_t bufferFilled;
+  JpegContext(FsFile& f) : file(f), bufferPos(0), bufferFilled(0) {}
+};
+
+bool JpegToFramebufferConverter::getDimensionsStatic(const std::string& imagePath, ImageDimensions& out) {
+  FsFile file;
+  if (!Storage.openFileForRead("JPG", imagePath, file)) {
+    Serial.printf("[%lu] [JPG] Failed to open file for dimensions: %s\n", millis(), imagePath.c_str());
+    return false;
+  }
+
+  JpegContext context(file);
+  pjpeg_image_info_t imageInfo;
+
+  int status = pjpeg_decode_init(&imageInfo, jpegReadCallback, &context, 0);
+  file.close();
+
+  if (status != 0) {
+    Serial.printf("[%lu] [JPG] Failed to init JPEG for dimensions: %d\n", millis(), status);
+    return false;
+  }
+
+  out.width = imageInfo.m_width;
+  out.height = imageInfo.m_height;
+  Serial.printf("[%lu] [JPG] Image dimensions: %dx%d\n", millis(), out.width, out.height);
+  return true;
+}
+
+bool JpegToFramebufferConverter::decodeToFramebuffer(const std::string& imagePath, GfxRenderer& renderer,
+                                                     const RenderConfig& config) {
+  Serial.printf("[%lu] [JPG] Decoding JPEG: %s\n", millis(), imagePath.c_str());
+
+  FsFile file;
+  if (!Storage.openFileForRead("JPG", imagePath, file)) {
+    Serial.printf("[%lu] [JPG] Failed to open file: %s\n", millis(), imagePath.c_str());
+    return false;
+  }
+
+  JpegContext context(file);
+  pjpeg_image_info_t imageInfo;
+
+  int status = pjpeg_decode_init(&imageInfo, jpegReadCallback, &context, 0);
+  if (status != 0) {
+    Serial.printf("[%lu] [JPG] picojpeg init failed: %d\n", millis(), status);
+    file.close();
+    return false;
+  }
+
+  if (!validateImageDimensions(imageInfo.m_width, imageInfo.m_height, "JPEG")) {
+    file.close();
+    return false;
+  }
+
+  // Calculate output dimensions
+  int destWidth, destHeight;
+  float scale;
+
+  if (config.useExactDimensions && config.maxWidth > 0 && config.maxHeight > 0) {
+    // Use exact dimensions as specified (avoids rounding mismatches with pre-calculated sizes)
+    destWidth = config.maxWidth;
+    destHeight = config.maxHeight;
+    scale = (float)destWidth / imageInfo.m_width;
+  } else {
+    // Calculate scale factor to fit within maxWidth/maxHeight
+    float scaleX = (config.maxWidth > 0 && imageInfo.m_width > config.maxWidth)
+                       ? (float)config.maxWidth / imageInfo.m_width
+                       : 1.0f;
+    float scaleY = (config.maxHeight > 0 && imageInfo.m_height > config.maxHeight)
+                       ? (float)config.maxHeight / imageInfo.m_height
+                       : 1.0f;
+    scale = (scaleX < scaleY) ? scaleX : scaleY;
+    if (scale > 1.0f) scale = 1.0f;
+
+    destWidth = (int)(imageInfo.m_width * scale);
+    destHeight = (int)(imageInfo.m_height * scale);
+  }
+
+  Serial.printf("[%lu] [JPG] JPEG %dx%d -> %dx%d (scale %.2f), scan type: %d, MCU: %dx%d\n", millis(),
+                imageInfo.m_width, imageInfo.m_height, destWidth, destHeight, scale, imageInfo.m_scanType,
+                imageInfo.m_MCUWidth, imageInfo.m_MCUHeight);
+
+  if (!imageInfo.m_pMCUBufR || !imageInfo.m_pMCUBufG || !imageInfo.m_pMCUBufB) {
+    Serial.printf("[%lu] [JPG] Null buffer pointers in imageInfo\n", millis());
+    file.close();
+    return false;
+  }
+
+  const int screenWidth = renderer.getScreenWidth();
+  const int screenHeight = renderer.getScreenHeight();
+
+  // Allocate pixel cache if cachePath is provided
+  PixelCache cache;
+  bool caching = !config.cachePath.empty();
+  if (caching) {
+    if (!cache.allocate(destWidth, destHeight, config.x, config.y)) {
+      Serial.printf("[%lu] [JPG] Failed to allocate cache buffer, continuing without caching\n", millis());
+      caching = false;
+    }
+  }
+
+  int mcuX = 0;
+  int mcuY = 0;
+
+  while (mcuY < imageInfo.m_MCUSPerCol) {
+    status = pjpeg_decode_mcu();
+    if (status == PJPG_NO_MORE_BLOCKS) {
+      break;
+    }
+    if (status != 0) {
+      Serial.printf("[%lu] [JPG] MCU decode failed: %d\n", millis(), status);
+      file.close();
+      return false;
+    }
+
+    // Source position in image coordinates
+    int srcStartX = mcuX * imageInfo.m_MCUWidth;
+    int srcStartY = mcuY * imageInfo.m_MCUHeight;
+
+    switch (imageInfo.m_scanType) {
+      case PJPG_GRAYSCALE:
+        for (int row = 0; row < 8; row++) {
+          int srcY = srcStartY + row;
+          int destY = config.y + (int)(srcY * scale);
+          if (destY >= screenHeight || destY >= config.y + destHeight) continue;
+          for (int col = 0; col < 8; col++) {
+            int srcX = srcStartX + col;
+            int destX = config.x + (int)(srcX * scale);
+            if (destX >= screenWidth || destX >= config.x + destWidth) continue;
+            uint8_t gray = imageInfo.m_pMCUBufR[row * 8 + col];
+            uint8_t dithered = config.useDithering ? applyBayerDither4Level(gray, destX, destY) : gray / 85;
+            if (dithered > 3) dithered = 3;
+            drawPixelWithRenderMode(renderer, destX, destY, dithered);
+            if (caching) cache.setPixel(destX, destY, dithered);
+          }
+        }
+        break;
+
+      case PJPG_YH1V1:
+        for (int row = 0; row < 8; row++) {
+          int srcY = srcStartY + row;
+          int destY = config.y + (int)(srcY * scale);
+          if (destY >= screenHeight || destY >= config.y + destHeight) continue;
+          for (int col = 0; col < 8; col++) {
+            int srcX = srcStartX + col;
+            int destX = config.x + (int)(srcX * scale);
+            if (destX >= screenWidth || destX >= config.x + destWidth) continue;
+            uint8_t r = imageInfo.m_pMCUBufR[row * 8 + col];
+            uint8_t g = imageInfo.m_pMCUBufG[row * 8 + col];
+            uint8_t b = imageInfo.m_pMCUBufB[row * 8 + col];
+            uint8_t gray = (uint8_t)((r * 77 + g * 150 + b * 29) >> 8);
+            uint8_t dithered = config.useDithering ? applyBayerDither4Level(gray, destX, destY) : gray / 85;
+            if (dithered > 3) dithered = 3;
+            drawPixelWithRenderMode(renderer, destX, destY, dithered);
+            if (caching) cache.setPixel(destX, destY, dithered);
+          }
+        }
+        break;
+
+      case PJPG_YH2V1:
+        for (int row = 0; row < 8; row++) {
+          int srcY = srcStartY + row;
+          int destY = config.y + (int)(srcY * scale);
+          if (destY >= screenHeight || destY >= config.y + destHeight) continue;
+          for (int col = 0; col < 16; col++) {
+            int srcX = srcStartX + col;
+            int destX = config.x + (int)(srcX * scale);
+            if (destX >= screenWidth || destX >= config.x + destWidth) continue;
+            int blockIndex = (col < 8) ? 0 : 1;
+            int pixelIndex = row * 8 + (col % 8);
+            uint8_t r = imageInfo.m_pMCUBufR[blockIndex * 64 + pixelIndex];
+            uint8_t g = imageInfo.m_pMCUBufG[blockIndex * 64 + pixelIndex];
+            uint8_t b = imageInfo.m_pMCUBufB[blockIndex * 64 + pixelIndex];
+            uint8_t gray = (uint8_t)((r * 77 + g * 150 + b * 29) >> 8);
+            uint8_t dithered = config.useDithering ? applyBayerDither4Level(gray, destX, destY) : gray / 85;
+            if (dithered > 3) dithered = 3;
+            drawPixelWithRenderMode(renderer, destX, destY, dithered);
+            if (caching) cache.setPixel(destX, destY, dithered);
+          }
+        }
+        break;
+
+      case PJPG_YH1V2:
+        for (int row = 0; row < 16; row++) {
+          int srcY = srcStartY + row;
+          int destY = config.y + (int)(srcY * scale);
+          if (destY >= screenHeight || destY >= config.y + destHeight) continue;
+          for (int col = 0; col < 8; col++) {
+            int srcX = srcStartX + col;
+            int destX = config.x + (int)(srcX * scale);
+            if (destX >= screenWidth || destX >= config.x + destWidth) continue;
+            int blockIndex = (row < 8) ? 0 : 1;
+            int pixelIndex = (row % 8) * 8 + col;
+            uint8_t r = imageInfo.m_pMCUBufR[blockIndex * 128 + pixelIndex];
+            uint8_t g = imageInfo.m_pMCUBufG[blockIndex * 128 + pixelIndex];
+            uint8_t b = imageInfo.m_pMCUBufB[blockIndex * 128 + pixelIndex];
+            uint8_t gray = (uint8_t)((r * 77 + g * 150 + b * 29) >> 8);
+            uint8_t dithered = config.useDithering ? applyBayerDither4Level(gray, destX, destY) : gray / 85;
+            if (dithered > 3) dithered = 3;
+            drawPixelWithRenderMode(renderer, destX, destY, dithered);
+            if (caching) cache.setPixel(destX, destY, dithered);
+          }
+        }
+        break;
+
+      case PJPG_YH2V2:
+        for (int row = 0; row < 16; row++) {
+          int srcY = srcStartY + row;
+          int destY = config.y + (int)(srcY * scale);
+          if (destY >= screenHeight || destY >= config.y + destHeight) continue;
+          for (int col = 0; col < 16; col++) {
+            int srcX = srcStartX + col;
+            int destX = config.x + (int)(srcX * scale);
+            if (destX >= screenWidth || destX >= config.x + destWidth) continue;
+            int blockX = (col < 8) ? 0 : 1;
+            int blockY = (row < 8) ? 0 : 1;
+            int blockIndex = blockY * 2 + blockX;
+            int pixelIndex = (row % 8) * 8 + (col % 8);
+            int blockOffset = blockIndex * 64;
+            uint8_t r = imageInfo.m_pMCUBufR[blockOffset + pixelIndex];
+            uint8_t g = imageInfo.m_pMCUBufG[blockOffset + pixelIndex];
+            uint8_t b = imageInfo.m_pMCUBufB[blockOffset + pixelIndex];
+            uint8_t gray = (uint8_t)((r * 77 + g * 150 + b * 29) >> 8);
+            uint8_t dithered = config.useDithering ? applyBayerDither4Level(gray, destX, destY) : gray / 85;
+            if (dithered > 3) dithered = 3;
+            drawPixelWithRenderMode(renderer, destX, destY, dithered);
+            if (caching) cache.setPixel(destX, destY, dithered);
+          }
+        }
+        break;
+    }
+
+    mcuX++;
+    if (mcuX >= imageInfo.m_MCUSPerRow) {
+      mcuX = 0;
+      mcuY++;
+    }
+  }
+
+  Serial.printf("[%lu] [JPG] Decoding complete\n", millis());
+  file.close();
+
+  // Write cache file if caching was enabled
+  if (caching) {
+    cache.writeToFile(config.cachePath);
+  }
+
+  return true;
+}
+
+unsigned char JpegToFramebufferConverter::jpegReadCallback(unsigned char* pBuf, unsigned char buf_size,
+                                                           unsigned char* pBytes_actually_read, void* pCallback_data) {
+  JpegContext* context = reinterpret_cast<JpegContext*>(pCallback_data);
+
+  if (context->bufferPos >= context->bufferFilled) {
+    int readCount = context->file.read(context->buffer, sizeof(context->buffer));
+    if (readCount <= 0) {
+      *pBytes_actually_read = 0;
+      return 0;
+    }
+    context->bufferFilled = readCount;
+    context->bufferPos = 0;
+  }
+
+  unsigned int bytesAvailable = context->bufferFilled - context->bufferPos;
+  unsigned int bytesToCopy = (bytesAvailable < buf_size) ? bytesAvailable : buf_size;
+
+  memcpy(pBuf, &context->buffer[context->bufferPos], bytesToCopy);
+  context->bufferPos += bytesToCopy;
+  *pBytes_actually_read = bytesToCopy;
+
+  return 0;
+}
+
+bool JpegToFramebufferConverter::supportsFormat(const std::string& extension) {
+  std::string ext = extension;
+  for (auto& c : ext) {
+    c = tolower(c);
+  }
+  return (ext == ".jpg" || ext == ".jpeg");
+}

lib/Epub/Epub/converters/JpegToFramebufferConverter.h

@@ -0,0 +1,24 @@
+#pragma once
+#include <stdint.h>
+
+#include <string>
+
+#include "ImageToFramebufferDecoder.h"
+
+class JpegToFramebufferConverter final : public ImageToFramebufferDecoder {
+ public:
+  static bool getDimensionsStatic(const std::string& imagePath, ImageDimensions& out);
+
+  bool decodeToFramebuffer(const std::string& imagePath, GfxRenderer& renderer, const RenderConfig& config) override;
+
+  bool getDimensions(const std::string& imagePath, ImageDimensions& dims) const override {
+    return getDimensionsStatic(imagePath, dims);
+  }
+
+  static bool supportsFormat(const std::string& extension);
+  const char* getFormatName() const override { return "JPEG"; }
+
+ private:
+  static unsigned char jpegReadCallback(unsigned char* pBuf, unsigned char buf_size,
+                                        unsigned char* pBytes_actually_read, void* pCallback_data);
+};

lib/Epub/Epub/converters/PixelCache.h

@@ -0,0 +1,85 @@
+#pragma once
+
+#include <HardwareSerial.h>
+#include <SDCardManager.h>
+#include <SdFat.h>
+#include <stdint.h>
+
+#include <cstring>
+#include <string>
+
+// Cache buffer for storing 2-bit pixels (4 levels) during decode.
+// Packs 4 pixels per byte, MSB first.
+struct PixelCache {
+  uint8_t* buffer;
+  int width;
+  int height;
+  int bytesPerRow;
+  int originX;  // config.x - to convert screen coords to cache coords
+  int originY;  // config.y
+
+  PixelCache() : buffer(nullptr), width(0), height(0), bytesPerRow(0), originX(0), originY(0) {}
+  PixelCache(const PixelCache&) = delete;
+  PixelCache& operator=(const PixelCache&) = delete;
+
+  static constexpr size_t MAX_CACHE_BYTES = 256 * 1024;  // 256KB limit for embedded targets
+
+  bool allocate(int w, int h, int ox, int oy) {
+    width = w;
+    height = h;
+    originX = ox;
+    originY = oy;
+    bytesPerRow = (w + 3) / 4;  // 2 bits per pixel, 4 pixels per byte
+    size_t bufferSize = (size_t)bytesPerRow * h;
+    if (bufferSize > MAX_CACHE_BYTES) {
+      Serial.printf("[%lu] [IMG] Cache buffer too large: %d bytes for %dx%d (limit %d)\n", millis(), bufferSize, w, h,
+                    MAX_CACHE_BYTES);
+      return false;
+    }
+    buffer = (uint8_t*)malloc(bufferSize);
+    if (buffer) {
+      memset(buffer, 0, bufferSize);
+      Serial.printf("[%lu] [IMG] Allocated cache buffer: %d bytes for %dx%d\n", millis(), bufferSize, w, h);
+    }
+    return buffer != nullptr;
+  }
+
+  void setPixel(int screenX, int screenY, uint8_t value) {
+    if (!buffer) return;
+    int localX = screenX - originX;
+    int localY = screenY - originY;
+    if (localX < 0 || localX >= width || localY < 0 || localY >= height) return;
+
+    int byteIdx = localY * bytesPerRow + localX / 4;
+    int bitShift = 6 - (localX % 4) * 2;  // MSB first: pixel 0 at bits 6-7
+    buffer[byteIdx] = (buffer[byteIdx] & ~(0x03 << bitShift)) | ((value & 0x03) << bitShift);
+  }
+
+  bool writeToFile(const std::string& cachePath) {
+    if (!buffer) return false;
+
+    FsFile cacheFile;
+    if (!Storage.openFileForWrite("IMG", cachePath, cacheFile)) {
+      Serial.printf("[%lu] [IMG] Failed to open cache file for writing: %s\n", millis(), cachePath.c_str());
+      return false;
+    }
+
+    uint16_t w = width;
+    uint16_t h = height;
+    cacheFile.write(&w, 2);
+    cacheFile.write(&h, 2);
+    cacheFile.write(buffer, bytesPerRow * height);
+    cacheFile.close();
+
+    Serial.printf("[%lu] [IMG] Cache written: %s (%dx%d, %d bytes)\n", millis(), cachePath.c_str(), width, height,
+                  4 + bytesPerRow * height);
+    return true;
+  }
+
+  ~PixelCache() {
+    if (buffer) {
+      free(buffer);
+      buffer = nullptr;
+    }
+  }
+};

lib/Epub/Epub/converters/PngToFramebufferConverter.cpp

@@ -0,0 +1,364 @@
+#include "PngToFramebufferConverter.h"
+
+#include <GfxRenderer.h>
+#include <HardwareSerial.h>
+#include <PNGdec.h>
+#include <SDCardManager.h>
+#include <SdFat.h>
+
+#include <cstdlib>
+#include <new>
+
+#include "DitherUtils.h"
+#include "PixelCache.h"
+
+namespace {
+
+// Context struct passed through PNGdec callbacks to avoid global mutable state.
+// The draw callback receives this via pDraw->pUser (set by png.decode()).
+// The file I/O callbacks receive the FsFile* via pFile->fHandle (set by pngOpen()).
+struct PngContext {
+  GfxRenderer* renderer;
+  const RenderConfig* config;
+  int screenWidth;
+  int screenHeight;
+
+  // Scaling state
+  float scale;
+  int srcWidth;
+  int srcHeight;
+  int dstWidth;
+  int dstHeight;
+  int lastDstY;  // Track last rendered destination Y to avoid duplicates
+
+  PixelCache cache;
+  bool caching;
+
+  uint8_t* grayLineBuffer;
+
+  PngContext()
+      : renderer(nullptr),
+        config(nullptr),
+        screenWidth(0),
+        screenHeight(0),
+        scale(1.0f),
+        srcWidth(0),
+        srcHeight(0),
+        dstWidth(0),
+        dstHeight(0),
+        lastDstY(-1),
+        caching(false),
+        grayLineBuffer(nullptr) {}
+};
+
+// File I/O callbacks use pFile->fHandle to access the FsFile*,
+// avoiding the need for global file state.
+void* pngOpenWithHandle(const char* filename, int32_t* size) {
+  FsFile* f = new FsFile();
+  if (!Storage.openFileForRead("PNG", std::string(filename), *f)) {
+    delete f;
+    return nullptr;
+  }
+  *size = f->size();
+  return f;
+}
+
+void pngCloseWithHandle(void* handle) {
+  FsFile* f = reinterpret_cast<FsFile*>(handle);
+  if (f) {
+    f->close();
+    delete f;
+  }
+}
+
+int32_t pngReadWithHandle(PNGFILE* pFile, uint8_t* pBuf, int32_t len) {
+  FsFile* f = reinterpret_cast<FsFile*>(pFile->fHandle);
+  if (!f) return 0;
+  return f->read(pBuf, len);
+}
+
+int32_t pngSeekWithHandle(PNGFILE* pFile, int32_t pos) {
+  FsFile* f = reinterpret_cast<FsFile*>(pFile->fHandle);
+  if (!f) return -1;
+  return f->seek(pos);
+}
+
+// The PNG decoder (PNGdec) is ~42 KB due to internal zlib decompression buffers.
+// We heap-allocate it on demand rather than using a static instance, so this memory
+// is only consumed while actually decoding/querying PNG images. This is critical on
+// the ESP32-C3 where total RAM is ~320 KB.
+constexpr size_t PNG_DECODER_APPROX_SIZE = 44 * 1024;                          // ~42 KB + overhead
+constexpr size_t MIN_FREE_HEAP_FOR_PNG = PNG_DECODER_APPROX_SIZE + 16 * 1024;  // decoder + 16 KB headroom
+
+// Convert entire source line to grayscale with alpha blending to white background.
+// For indexed PNGs with tRNS chunk, alpha values are stored at palette[768] onwards.
+// Processing the whole line at once improves cache locality and reduces per-pixel overhead.
+void convertLineToGray(uint8_t* pPixels, uint8_t* grayLine, int width, int pixelType, uint8_t* palette, int hasAlpha) {
+  switch (pixelType) {
+    case PNG_PIXEL_GRAYSCALE:
+      memcpy(grayLine, pPixels, width);
+      break;
+
+    case PNG_PIXEL_TRUECOLOR:
+      for (int x = 0; x < width; x++) {
+        uint8_t* p = &pPixels[x * 3];
+        grayLine[x] = (uint8_t)((p[0] * 77 + p[1] * 150 + p[2] * 29) >> 8);
+      }
+      break;
+
+    case PNG_PIXEL_INDEXED:
+      if (palette) {
+        if (hasAlpha) {
+          for (int x = 0; x < width; x++) {
+            uint8_t idx = pPixels[x];
+            uint8_t* p = &palette[idx * 3];
+            uint8_t gray = (uint8_t)((p[0] * 77 + p[1] * 150 + p[2] * 29) >> 8);
+            uint8_t alpha = palette[768 + idx];
+            grayLine[x] = (uint8_t)((gray * alpha + 255 * (255 - alpha)) / 255);
+          }
+        } else {
+          for (int x = 0; x < width; x++) {
+            uint8_t* p = &palette[pPixels[x] * 3];
+            grayLine[x] = (uint8_t)((p[0] * 77 + p[1] * 150 + p[2] * 29) >> 8);
+          }
+        }
+      } else {
+        memcpy(grayLine, pPixels, width);
+      }
+      break;
+
+    case PNG_PIXEL_GRAY_ALPHA:
+      for (int x = 0; x < width; x++) {
+        uint8_t gray = pPixels[x * 2];
+        uint8_t alpha = pPixels[x * 2 + 1];
+        grayLine[x] = (uint8_t)((gray * alpha + 255 * (255 - alpha)) / 255);
+      }
+      break;
+
+    case PNG_PIXEL_TRUECOLOR_ALPHA:
+      for (int x = 0; x < width; x++) {
+        uint8_t* p = &pPixels[x * 4];
+        uint8_t gray = (uint8_t)((p[0] * 77 + p[1] * 150 + p[2] * 29) >> 8);
+        uint8_t alpha = p[3];
+        grayLine[x] = (uint8_t)((gray * alpha + 255 * (255 - alpha)) / 255);
+      }
+      break;
+
+    default:
+      memset(grayLine, 128, width);
+      break;
+  }
+}
+
+int pngDrawCallback(PNGDRAW* pDraw) {
+  PngContext* ctx = reinterpret_cast<PngContext*>(pDraw->pUser);
+  if (!ctx || !ctx->config || !ctx->renderer || !ctx->grayLineBuffer) return 0;
+
+  int srcY = pDraw->y;
+  int srcWidth = ctx->srcWidth;
+
+  // Calculate destination Y with scaling
+  int dstY = (int)(srcY * ctx->scale);
+
+  // Skip if we already rendered this destination row (multiple source rows map to same dest)
+  if (dstY == ctx->lastDstY) return 1;
+  ctx->lastDstY = dstY;
+
+  // Check bounds
+  if (dstY >= ctx->dstHeight) return 1;
+
+  int outY = ctx->config->y + dstY;
+  if (outY >= ctx->screenHeight) return 1;
+
+  // Convert entire source line to grayscale (improves cache locality)
+  convertLineToGray(pDraw->pPixels, ctx->grayLineBuffer, srcWidth, pDraw->iPixelType, pDraw->pPalette,
+                    pDraw->iHasAlpha);
+
+  // Render scaled row using Bresenham-style integer stepping (no floating-point division)
+  int dstWidth = ctx->dstWidth;
+  int outXBase = ctx->config->x;
+  int screenWidth = ctx->screenWidth;
+  bool useDithering = ctx->config->useDithering;
+  bool caching = ctx->caching;
+
+  int srcX = 0;
+  int error = 0;
+
+  for (int dstX = 0; dstX < dstWidth; dstX++) {
+    int outX = outXBase + dstX;
+    if (outX < screenWidth) {
+      uint8_t gray = ctx->grayLineBuffer[srcX];
+
+      uint8_t ditheredGray;
+      if (useDithering) {
+        ditheredGray = applyBayerDither4Level(gray, outX, outY);
+      } else {
+        ditheredGray = gray / 85;
+        if (ditheredGray > 3) ditheredGray = 3;
+      }
+      drawPixelWithRenderMode(*ctx->renderer, outX, outY, ditheredGray);
+      if (caching) ctx->cache.setPixel(outX, outY, ditheredGray);
+    }
+
+    // Bresenham-style stepping: advance srcX based on ratio srcWidth/dstWidth
+    error += srcWidth;
+    while (error >= dstWidth) {
+      error -= dstWidth;
+      srcX++;
+    }
+  }
+
+  return 1;
+}
+
+}  // namespace
+
+bool PngToFramebufferConverter::getDimensionsStatic(const std::string& imagePath, ImageDimensions& out) {
+  size_t freeHeap = ESP.getFreeHeap();
+  if (freeHeap < MIN_FREE_HEAP_FOR_PNG) {
+    Serial.printf("[%lu] [PNG] Not enough heap for PNG decoder (%u free, need %u)\n", millis(), freeHeap,
+                  MIN_FREE_HEAP_FOR_PNG);
+    return false;
+  }
+
+  PNG* png = new (std::nothrow) PNG();
+  if (!png) {
+    Serial.printf("[%lu] [PNG] Failed to allocate PNG decoder for dimensions\n", millis());
+    return false;
+  }
+
+  int rc = png->open(imagePath.c_str(), pngOpenWithHandle, pngCloseWithHandle, pngReadWithHandle, pngSeekWithHandle,
+                     nullptr);
+
+  if (rc != 0) {
+    Serial.printf("[%lu] [PNG] Failed to open PNG for dimensions: %d\n", millis(), rc);
+    delete png;
+    return false;
+  }
+
+  out.width = png->getWidth();
+  out.height = png->getHeight();
+
+  png->close();
+  delete png;
+  return true;
+}
+
+bool PngToFramebufferConverter::decodeToFramebuffer(const std::string& imagePath, GfxRenderer& renderer,
+                                                    const RenderConfig& config) {
+  Serial.printf("[%lu] [PNG] Decoding PNG: %s\n", millis(), imagePath.c_str());
+
+  size_t freeHeap = ESP.getFreeHeap();
+  if (freeHeap < MIN_FREE_HEAP_FOR_PNG) {
+    Serial.printf("[%lu] [PNG] Not enough heap for PNG decoder (%u free, need %u)\n", millis(), freeHeap,
+                  MIN_FREE_HEAP_FOR_PNG);
+    return false;
+  }
+
+  // Heap-allocate PNG decoder (~42 KB) - freed at end of function
+  PNG* png = new (std::nothrow) PNG();
+  if (!png) {
+    Serial.printf("[%lu] [PNG] Failed to allocate PNG decoder\n", millis());
+    return false;
+  }
+
+  PngContext ctx;
+  ctx.renderer = &renderer;
+  ctx.config = &config;
+  ctx.screenWidth = renderer.getScreenWidth();
+  ctx.screenHeight = renderer.getScreenHeight();
+
+  int rc = png->open(imagePath.c_str(), pngOpenWithHandle, pngCloseWithHandle, pngReadWithHandle, pngSeekWithHandle,
+                     pngDrawCallback);
+  if (rc != PNG_SUCCESS) {
+    Serial.printf("[%lu] [PNG] Failed to open PNG: %d\n", millis(), rc);
+    delete png;
+    return false;
+  }
+
+  if (!validateImageDimensions(png->getWidth(), png->getHeight(), "PNG")) {
+    png->close();
+    delete png;
+    return false;
+  }
+
+  // Calculate output dimensions
+  ctx.srcWidth = png->getWidth();
+  ctx.srcHeight = png->getHeight();
+
+  if (config.useExactDimensions && config.maxWidth > 0 && config.maxHeight > 0) {
+    // Use exact dimensions as specified (avoids rounding mismatches with pre-calculated sizes)
+    ctx.dstWidth = config.maxWidth;
+    ctx.dstHeight = config.maxHeight;
+    ctx.scale = (float)ctx.dstWidth / ctx.srcWidth;
+  } else {
+    // Calculate scale factor to fit within maxWidth/maxHeight
+    float scaleX = (float)config.maxWidth / ctx.srcWidth;
+    float scaleY = (float)config.maxHeight / ctx.srcHeight;
+    ctx.scale = (scaleX < scaleY) ? scaleX : scaleY;
+    if (ctx.scale > 1.0f) ctx.scale = 1.0f;  // Don't upscale
+
+    ctx.dstWidth = (int)(ctx.srcWidth * ctx.scale);
+    ctx.dstHeight = (int)(ctx.srcHeight * ctx.scale);
+  }
+  ctx.lastDstY = -1;  // Reset row tracking
+
+  Serial.printf("[%lu] [PNG] PNG %dx%d -> %dx%d (scale %.2f), bpp: %d\n", millis(), ctx.srcWidth, ctx.srcHeight,
+                ctx.dstWidth, ctx.dstHeight, ctx.scale, png->getBpp());
+
+  if (png->getBpp() != 8) {
+    warnUnsupportedFeature("bit depth (" + std::to_string(png->getBpp()) + "bpp)", imagePath);
+  }
+
+  // Allocate grayscale line buffer on demand (~3.2 KB) - freed after decode
+  const size_t grayBufSize = PNG_MAX_BUFFERED_PIXELS / 2;
+  ctx.grayLineBuffer = static_cast<uint8_t*>(malloc(grayBufSize));
+  if (!ctx.grayLineBuffer) {
+    Serial.printf("[%lu] [PNG] Failed to allocate gray line buffer\n", millis());
+    png->close();
+    delete png;
+    return false;
+  }
+
+  // Allocate cache buffer using SCALED dimensions
+  ctx.caching = !config.cachePath.empty();
+  if (ctx.caching) {
+    if (!ctx.cache.allocate(ctx.dstWidth, ctx.dstHeight, config.x, config.y)) {
+      Serial.printf("[%lu] [PNG] Failed to allocate cache buffer, continuing without caching\n", millis());
+      ctx.caching = false;
+    }
+  }
+
+  unsigned long decodeStart = millis();
+  rc = png->decode(&ctx, 0);
+  unsigned long decodeTime = millis() - decodeStart;
+
+  free(ctx.grayLineBuffer);
+  ctx.grayLineBuffer = nullptr;
+
+  if (rc != PNG_SUCCESS) {
+    Serial.printf("[%lu] [PNG] Decode failed: %d\n", millis(), rc);
+    png->close();
+    delete png;
+    return false;
+  }
+
+  png->close();
+  delete png;
+  Serial.printf("[%lu] [PNG] PNG decoding complete - render time: %lu ms\n", millis(), decodeTime);
+
+  // Write cache file if caching was enabled and buffer was allocated
+  if (ctx.caching) {
+    ctx.cache.writeToFile(config.cachePath);
+  }
+
+  return true;
+}
+
+bool PngToFramebufferConverter::supportsFormat(const std::string& extension) {
+  std::string ext = extension;
+  for (auto& c : ext) {
+    c = tolower(c);
+  }
+  return (ext == ".png");
+}

lib/Epub/Epub/converters/PngToFramebufferConverter.h

@@ -0,0 +1,17 @@
+#pragma once
+
+#include "ImageToFramebufferDecoder.h"
+
+class PngToFramebufferConverter final : public ImageToFramebufferDecoder {
+ public:
+  static bool getDimensionsStatic(const std::string& imagePath, ImageDimensions& out);
+
+  bool decodeToFramebuffer(const std::string& imagePath, GfxRenderer& renderer, const RenderConfig& config) override;
+
+  bool getDimensions(const std::string& imagePath, ImageDimensions& dims) const override {
+    return getDimensionsStatic(imagePath, dims);
+  }
+
+  static bool supportsFormat(const std::string& extension);
+  const char* getFormatName() const override { return "PNG"; }
+};

lib/Epub/Epub/css/CssParser.cpp

@@ -1,144 +1,57 @@
 #include "CssParser.h"
 
-#include <HardwareSerial.h>
+#include <Arduino.h>
+#include <Logging.h>
 
 #include <algorithm>
+#include <array>
 #include <cctype>
+#include <string_view>
 
 namespace {
 
+// Stack-allocated string buffer to avoid heap reallocations during parsing
+// Provides string-like interface with fixed capacity
+struct StackBuffer {
+  static constexpr size_t CAPACITY = 1024;
+  char data[CAPACITY];
+  size_t len = 0;
+
+  void push_back(char c) {
+    if (len < CAPACITY - 1) {
+      data[len++] = c;
+    }
+  }
+
+  void clear() { len = 0; }
+  bool empty() const { return len == 0; }
+  size_t size() const { return len; }
+
+  // Get string view of current content (zero-copy)
+  std::string_view view() const { return std::string_view(data, len); }
+
+  // Convert to string for passing to functions (single allocation)
+  std::string str() const { return std::string(data, len); }
+};
+
 // Buffer size for reading CSS files
 constexpr size_t READ_BUFFER_SIZE = 512;
 
-// Maximum CSS file size we'll process (prevent memory issues)
-constexpr size_t MAX_CSS_SIZE = 64 * 1024;
+// Maximum number of CSS rules to store in the selector map
+// Prevents unbounded memory growth from pathological CSS files
+constexpr size_t MAX_RULES = 1500;
+
+// Minimum free heap required to apply CSS during rendering
+// If below this threshold, we skip CSS to avoid display artifacts.
+constexpr size_t MIN_FREE_HEAP_FOR_CSS = 48 * 1024;
+
+// Maximum length for a single selector string
+// Prevents parsing of extremely long or malformed selectors
+constexpr size_t MAX_SELECTOR_LENGTH = 256;
 
 // Check if character is CSS whitespace
 bool isCssWhitespace(const char c) { return c == ' ' || c == '\t' || c == '\n' || c == '\r' || c == '\f'; }
 
-// Read entire file into string (with size limit)
-std::string readFileContent(FsFile& file) {
-  std::string content;
-  content.reserve(std::min(static_cast<size_t>(file.size()), MAX_CSS_SIZE));
-
-  char buffer[READ_BUFFER_SIZE];
-  while (file.available() && content.size() < MAX_CSS_SIZE) {
-    const int bytesRead = file.read(buffer, sizeof(buffer));
-    if (bytesRead <= 0) break;
-    content.append(buffer, bytesRead);
-  }
-  return content;
-}
-
-// Remove CSS comments (/* ... */) from content
-std::string stripComments(const std::string& css) {
-  std::string result;
-  result.reserve(css.size());
-
-  size_t pos = 0;
-  while (pos < css.size()) {
-    // Look for start of comment
-    if (pos + 1 < css.size() && css[pos] == '/' && css[pos + 1] == '*') {
-      // Find end of comment
-      const size_t endPos = css.find("*/", pos + 2);
-      if (endPos == std::string::npos) {
-        // Unterminated comment - skip rest of file
-        break;
-      }
-      pos = endPos + 2;
-    } else {
-      result.push_back(css[pos]);
-      ++pos;
-    }
-  }
-  return result;
-}
-
-// Skip @-rules (like @media, @import, @font-face)
-// Returns position after the @-rule
-size_t skipAtRule(const std::string& css, const size_t start) {
-  // Find the end - either semicolon (simple @-rule) or matching brace
-  size_t pos = start + 1;  // Skip the '@'
-
-  // Skip identifier
-  while (pos < css.size() && (std::isalnum(css[pos]) || css[pos] == '-')) {
-    ++pos;
-  }
-
-  // Look for { or ;
-  int braceDepth = 0;
-  while (pos < css.size()) {
-    const char c = css[pos];
-    if (c == '{') {
-      ++braceDepth;
-    } else if (c == '}') {
-      --braceDepth;
-      if (braceDepth == 0) {
-        return pos + 1;
-      }
-    } else if (c == ';' && braceDepth == 0) {
-      return pos + 1;
-    }
-    ++pos;
-  }
-  return css.size();
-}
-
-// Extract next rule from CSS content
-// Returns true if a rule was found, with selector and body filled
-bool extractNextRule(const std::string& css, size_t& pos, std::string& selector, std::string& body) {
-  selector.clear();
-  body.clear();
-
-  // Skip whitespace and @-rules until we find a regular rule
-  while (pos < css.size()) {
-    // Skip whitespace
-    while (pos < css.size() && isCssWhitespace(css[pos])) {
-      ++pos;
-    }
-
-    if (pos >= css.size()) return false;
-
-    // Handle @-rules iteratively (avoids recursion/stack overflow)
-    if (css[pos] == '@') {
-      pos = skipAtRule(css, pos);
-      continue;  // Try again after skipping the @-rule
-    }
-
-    break;  // Found start of a regular rule
-  }
-
-  if (pos >= css.size()) return false;
-
-  // Find opening brace
-  const size_t bracePos = css.find('{', pos);
-  if (bracePos == std::string::npos) return false;
-
-  // Extract selector (everything before the brace)
-  selector = css.substr(pos, bracePos - pos);
-
-  // Find matching closing brace
-  int depth = 1;
-  const size_t bodyStart = bracePos + 1;
-  size_t bodyEnd = bodyStart;
-
-  while (bodyEnd < css.size() && depth > 0) {
-    if (css[bodyEnd] == '{')
-      ++depth;
-    else if (css[bodyEnd] == '}')
-      --depth;
-    ++bodyEnd;
-  }
-
-  // Extract body (between braces)
-  if (bodyEnd > bodyStart) {
-    body = css.substr(bodyStart, bodyEnd - bodyStart - 1);
-  }
-
-  pos = bodyEnd;
-  return true;
-}
-
 }  // anonymous namespace
 
 // String utilities implementation
@@ -167,6 +80,28 @@ std::string CssParser::normalized(const std::string& s) {
   return result;
 }
 
+void CssParser::normalizedInto(const std::string& s, std::string& out) {
+  out.clear();
+  out.reserve(s.size());
+
+  bool inSpace = true;  // Start true to skip leading space
+  for (const char c : s) {
+    if (isCssWhitespace(c)) {
+      if (!inSpace) {
+        out.push_back(' ');
+        inSpace = true;
+      }
+    } else {
+      out.push_back(static_cast<char>(std::tolower(static_cast<unsigned char>(c))));
+      inSpace = false;
+    }
+  }
+
+  if (!out.empty() && out.back() == ' ') {
+    out.pop_back();
+  }
+}
+
 std::vector<std::string> CssParser::splitOnChar(const std::string& s, const char delimiter) {
   std::vector<std::string> parts;
   size_t start = 0;
@@ -290,129 +225,98 @@ CssLength CssParser::interpretLength(const std::string& val) {
 
   return CssLength{numericValue, unit};
 }
-
-int8_t CssParser::interpretSpacing(const std::string& val) {
-  const std::string v = normalized(val);
-  if (v.empty()) return 0;
-
-  // For spacing, we convert to "lines" (discrete units for e-ink)
-  // 1em ≈ 1 line, percentages based on ~30 lines per page
-
-  float multiplier = 0.0f;
-  size_t unitStart = v.size();
-
-  for (size_t i = 0; i < v.size(); ++i) {
-    const char c = v[i];
-    if (!std::isdigit(c) && c != '.' && c != '-' && c != '+') {
-      unitStart = i;
-      break;
-    }
-  }
-
-  const std::string numPart = v.substr(0, unitStart);
-  const std::string unitPart = v.substr(unitStart);
-
-  if (unitPart == "em" || unitPart == "rem") {
-    multiplier = 1.0f;  // 1em = 1 line
-  } else if (unitPart == "%") {
-    multiplier = 0.3f;  // ~30 lines per page, so 10% = 3 lines
-  } else {
-    return 0;  // Unsupported unit for spacing
-  }
-
-  char* endPtr = nullptr;
-  const float numericValue = std::strtof(numPart.c_str(), &endPtr);
-
-  if (endPtr == numPart.c_str()) return 0;
-
-  int lines = static_cast<int>(numericValue * multiplier);
-
-  // Clamp to reasonable range (0-2 lines)
-  if (lines < 0) lines = 0;
-  if (lines > 2) lines = 2;
-
-  return static_cast<int8_t>(lines);
-}
-
 // Declaration parsing
 
+void CssParser::parseDeclarationIntoStyle(const std::string& decl, CssStyle& style, std::string& propNameBuf,
+                                          std::string& propValueBuf) {
+  const size_t colonPos = decl.find(':');
+  if (colonPos == std::string::npos || colonPos == 0) return;
+
+  normalizedInto(decl.substr(0, colonPos), propNameBuf);
+  normalizedInto(decl.substr(colonPos + 1), propValueBuf);
+
+  if (propNameBuf.empty() || propValueBuf.empty()) return;
+
+  if (propNameBuf == "text-align") {
+    style.textAlign = interpretAlignment(propValueBuf);
+    style.defined.textAlign = 1;
+  } else if (propNameBuf == "font-style") {
+    style.fontStyle = interpretFontStyle(propValueBuf);
+    style.defined.fontStyle = 1;
+  } else if (propNameBuf == "font-weight") {
+    style.fontWeight = interpretFontWeight(propValueBuf);
+    style.defined.fontWeight = 1;
+  } else if (propNameBuf == "text-decoration" || propNameBuf == "text-decoration-line") {
+    style.textDecoration = interpretDecoration(propValueBuf);
+    style.defined.textDecoration = 1;
+  } else if (propNameBuf == "text-indent") {
+    style.textIndent = interpretLength(propValueBuf);
+    style.defined.textIndent = 1;
+  } else if (propNameBuf == "margin-top") {
+    style.marginTop = interpretLength(propValueBuf);
+    style.defined.marginTop = 1;
+  } else if (propNameBuf == "margin-bottom") {
+    style.marginBottom = interpretLength(propValueBuf);
+    style.defined.marginBottom = 1;
+  } else if (propNameBuf == "margin-left") {
+    style.marginLeft = interpretLength(propValueBuf);
+    style.defined.marginLeft = 1;
+  } else if (propNameBuf == "margin-right") {
+    style.marginRight = interpretLength(propValueBuf);
+    style.defined.marginRight = 1;
+  } else if (propNameBuf == "margin") {
+    const auto values = splitWhitespace(propValueBuf);
+    if (!values.empty()) {
+      style.marginTop = interpretLength(values[0]);
+      style.marginRight = values.size() >= 2 ? interpretLength(values[1]) : style.marginTop;
+      style.marginBottom = values.size() >= 3 ? interpretLength(values[2]) : style.marginTop;
+      style.marginLeft = values.size() >= 4 ? interpretLength(values[3]) : style.marginRight;
+      style.defined.marginTop = style.defined.marginRight = style.defined.marginBottom = style.defined.marginLeft = 1;
+    }
+  } else if (propNameBuf == "padding-top") {
+    style.paddingTop = interpretLength(propValueBuf);
+    style.defined.paddingTop = 1;
+  } else if (propNameBuf == "padding-bottom") {
+    style.paddingBottom = interpretLength(propValueBuf);
+    style.defined.paddingBottom = 1;
+  } else if (propNameBuf == "padding-left") {
+    style.paddingLeft = interpretLength(propValueBuf);
+    style.defined.paddingLeft = 1;
+  } else if (propNameBuf == "padding-right") {
+    style.paddingRight = interpretLength(propValueBuf);
+    style.defined.paddingRight = 1;
+  } else if (propNameBuf == "padding") {
+    const auto values = splitWhitespace(propValueBuf);
+    if (!values.empty()) {
+      style.paddingTop = interpretLength(values[0]);
+      style.paddingRight = values.size() >= 2 ? interpretLength(values[1]) : style.paddingTop;
+      style.paddingBottom = values.size() >= 3 ? interpretLength(values[2]) : style.paddingTop;
+      style.paddingLeft = values.size() >= 4 ? interpretLength(values[3]) : style.paddingRight;
+      style.defined.paddingTop = style.defined.paddingRight = style.defined.paddingBottom = style.defined.paddingLeft =
+          1;
+    }
+  } else if (propNameBuf == "width") {
+    style.width = interpretLength(propValueBuf);
+    style.defined.width = 1;
+  }
+}
+
 CssStyle CssParser::parseDeclarations(const std::string& declBlock) {
   CssStyle style;
+  std::string propNameBuf;
+  std::string propValueBuf;
 
-  // Split declarations by semicolon
-  const auto declarations = splitOnChar(declBlock, ';');
-
-  for (const auto& decl : declarations) {
-    // Find colon separator
-    const size_t colonPos = decl.find(':');
-    if (colonPos == std::string::npos || colonPos == 0) continue;
-
-    std::string propName = normalized(decl.substr(0, colonPos));
-    std::string propValue = normalized(decl.substr(colonPos + 1));
-
-    if (propName.empty() || propValue.empty()) continue;
-
-    // Match property and set value
-    if (propName == "text-align") {
-      style.textAlign = interpretAlignment(propValue);
-      style.defined.textAlign = 1;
-    } else if (propName == "font-style") {
-      style.fontStyle = interpretFontStyle(propValue);
-      style.defined.fontStyle = 1;
-    } else if (propName == "font-weight") {
-      style.fontWeight = interpretFontWeight(propValue);
-      style.defined.fontWeight = 1;
-    } else if (propName == "text-decoration" || propName == "text-decoration-line") {
-      style.textDecoration = interpretDecoration(propValue);
-      style.defined.textDecoration = 1;
-    } else if (propName == "text-indent") {
-      style.textIndent = interpretLength(propValue);
-      style.defined.textIndent = 1;
-    } else if (propName == "margin-top") {
-      style.marginTop = interpretLength(propValue);
-      style.defined.marginTop = 1;
-    } else if (propName == "margin-bottom") {
-      style.marginBottom = interpretLength(propValue);
-      style.defined.marginBottom = 1;
-    } else if (propName == "margin-left") {
-      style.marginLeft = interpretLength(propValue);
-      style.defined.marginLeft = 1;
-    } else if (propName == "margin-right") {
-      style.marginRight = interpretLength(propValue);
-      style.defined.marginRight = 1;
-    } else if (propName == "margin") {
-      // Shorthand: 1-4 values for top, right, bottom, left
-      const auto values = splitWhitespace(propValue);
-      if (!values.empty()) {
-        style.marginTop = interpretLength(values[0]);
-        style.marginRight = values.size() >= 2 ? interpretLength(values[1]) : style.marginTop;
-        style.marginBottom = values.size() >= 3 ? interpretLength(values[2]) : style.marginTop;
-        style.marginLeft = values.size() >= 4 ? interpretLength(values[3]) : style.marginRight;
-        style.defined.marginTop = style.defined.marginRight = style.defined.marginBottom = style.defined.marginLeft = 1;
-      }
-    } else if (propName == "padding-top") {
-      style.paddingTop = interpretLength(propValue);
-      style.defined.paddingTop = 1;
-    } else if (propName == "padding-bottom") {
-      style.paddingBottom = interpretLength(propValue);
-      style.defined.paddingBottom = 1;
-    } else if (propName == "padding-left") {
-      style.paddingLeft = interpretLength(propValue);
-      style.defined.paddingLeft = 1;
-    } else if (propName == "padding-right") {
-      style.paddingRight = interpretLength(propValue);
-      style.defined.paddingRight = 1;
-    } else if (propName == "padding") {
-      // Shorthand: 1-4 values for top, right, bottom, left
-      const auto values = splitWhitespace(propValue);
-      if (!values.empty()) {
-        style.paddingTop = interpretLength(values[0]);
-        style.paddingRight = values.size() >= 2 ? interpretLength(values[1]) : style.paddingTop;
-        style.paddingBottom = values.size() >= 3 ? interpretLength(values[2]) : style.paddingTop;
-        style.paddingLeft = values.size() >= 4 ? interpretLength(values[3]) : style.paddingRight;
-        style.defined.paddingTop = style.defined.paddingRight = style.defined.paddingBottom =
-            style.defined.paddingLeft = 1;
+  size_t start = 0;
+  for (size_t i = 0; i <= declBlock.size(); ++i) {
+    if (i == declBlock.size() || declBlock[i] == ';') {
+      if (i > start) {
+        const size_t len = i - start;
+        std::string decl = declBlock.substr(start, len);
+        if (!decl.empty()) {
+          parseDeclarationIntoStyle(decl, style, propNameBuf, propValueBuf);
+        }
       }
+      start = i + 1;
     }
   }
 
@@ -421,20 +325,33 @@ CssStyle CssParser::parseDeclarations(const std::string& declBlock) {
 
 // Rule processing
 
-void CssParser::processRuleBlock(const std::string& selectorGroup, const std::string& declarations) {
-  const CssStyle style = parseDeclarations(declarations);
-
-  // Only store if any properties were set
-  if (!style.defined.anySet()) return;
+void CssParser::processRuleBlockWithStyle(const std::string& selectorGroup, const CssStyle& style) {
+  // Check if we've reached the rule limit before processing
+  if (rulesBySelector_.size() >= MAX_RULES) {
+    LOG_DBG("CSS", "Reached max rules limit (%zu), stopping CSS parsing", MAX_RULES);
+    return;
+  }
 
   // Handle comma-separated selectors
   const auto selectors = splitOnChar(selectorGroup, ',');
 
   for (const auto& sel : selectors) {
+    // Validate selector length before processing
+    if (sel.size() > MAX_SELECTOR_LENGTH) {
+      LOG_DBG("CSS", "Selector too long (%zu > %zu), skipping", sel.size(), MAX_SELECTOR_LENGTH);
+      continue;
+    }
+
     // Normalize the selector
     std::string key = normalized(sel);
     if (key.empty()) continue;
 
+    // Skip if this would exceed the rule limit
+    if (rulesBySelector_.size() >= MAX_RULES) {
+      LOG_DBG("CSS", "Reached max rules limit, stopping selector processing");
+      return;
+    }
+
     // Store or merge with existing
     auto it = rulesBySelector_.find(key);
     if (it != rulesBySelector_.end()) {
@@ -449,34 +366,162 @@ void CssParser::processRuleBlock(const std::string& selectorGroup, const std::st
 
 bool CssParser::loadFromStream(FsFile& source) {
   if (!source) {
-    Serial.printf("[%lu] [CSS] Cannot read from invalid file\n", millis());
+    LOG_ERR("CSS", "Cannot read from invalid file");
     return false;
   }
 
-  // Read file content
-  const std::string content = readFileContent(source);
-  if (content.empty()) {
-    return true;  // Empty file is valid
+  size_t totalRead = 0;
+
+  // Use stack-allocated buffers for parsing to avoid heap reallocations
+  StackBuffer selector;
+  StackBuffer declBuffer;
+  // Keep these as std::string since they're passed by reference to parseDeclarationIntoStyle
+  std::string propNameBuf;
+  std::string propValueBuf;
+
+  bool inComment = false;
+  bool maybeSlash = false;
+  bool prevStar = false;
+
+  bool inAtRule = false;
+  int atDepth = 0;
+
+  int bodyDepth = 0;
+  bool skippingRule = false;
+  CssStyle currentStyle;
+
+  auto handleChar = [&](const char c) {
+    if (inAtRule) {
+      if (c == '{') {
+        ++atDepth;
+      } else if (c == '}') {
+        if (atDepth > 0) --atDepth;
+        if (atDepth == 0) inAtRule = false;
+      } else if (c == ';' && atDepth == 0) {
+        inAtRule = false;
+      }
+      return;
+    }
+
+    if (bodyDepth == 0) {
+      if (selector.empty() && isCssWhitespace(c)) {
+        return;
+      }
+      if (c == '@' && selector.empty()) {
+        inAtRule = true;
+        atDepth = 0;
+        return;
+      }
+      if (c == '{') {
+        bodyDepth = 1;
+        currentStyle = CssStyle{};
+        declBuffer.clear();
+        if (selector.size() > MAX_SELECTOR_LENGTH * 4) {
+          skippingRule = true;
+        }
+        return;
+      }
+      selector.push_back(c);
+      return;
+    }
+
+    // bodyDepth > 0
+    if (c == '{') {
+      ++bodyDepth;
+      return;
+    }
+    if (c == '}') {
+      --bodyDepth;
+      if (bodyDepth == 0) {
+        if (!skippingRule && !declBuffer.empty()) {
+          parseDeclarationIntoStyle(declBuffer.str(), currentStyle, propNameBuf, propValueBuf);
+        }
+        if (!skippingRule) {
+          processRuleBlockWithStyle(selector.str(), currentStyle);
+        }
+        selector.clear();
+        declBuffer.clear();
+        skippingRule = false;
+        return;
+      }
+      return;
+    }
+    if (bodyDepth > 1) {
+      return;
+    }
+    if (!skippingRule) {
+      if (c == ';') {
+        if (!declBuffer.empty()) {
+          parseDeclarationIntoStyle(declBuffer.str(), currentStyle, propNameBuf, propValueBuf);
+          declBuffer.clear();
+        }
+      } else {
+        declBuffer.push_back(c);
+      }
+    }
+  };
+
+  char buffer[READ_BUFFER_SIZE];
+  while (source.available()) {
+    int bytesRead = source.read(buffer, sizeof(buffer));
+    if (bytesRead <= 0) break;
+
+    totalRead += static_cast<size_t>(bytesRead);
+
+    for (int i = 0; i < bytesRead; ++i) {
+      const char c = buffer[i];
+
+      if (inComment) {
+        if (prevStar && c == '/') {
+          inComment = false;
+          prevStar = false;
+          continue;
+        }
+        prevStar = c == '*';
+        continue;
+      }
+
+      if (maybeSlash) {
+        if (c == '*') {
+          inComment = true;
+          maybeSlash = false;
+          prevStar = false;
+          continue;
+        }
+        handleChar('/');
+        maybeSlash = false;
+        // fall through to process current char
+      }
+
+      if (c == '/') {
+        maybeSlash = true;
+        continue;
+      }
+
+      handleChar(c);
+    }
   }
 
-  // Remove comments
-  const std::string cleaned = stripComments(content);
-
-  // Parse rules
-  size_t pos = 0;
-  std::string selector, body;
-
-  while (extractNextRule(cleaned, pos, selector, body)) {
-    processRuleBlock(selector, body);
+  if (maybeSlash) {
+    handleChar('/');
   }
 
-  Serial.printf("[%lu] [CSS] Parsed %zu rules\n", millis(), rulesBySelector_.size());
+  LOG_DBG("CSS", "Parsed %zu rules from %zu bytes", rulesBySelector_.size(), totalRead);
   return true;
 }
 
 // Style resolution
 
 CssStyle CssParser::resolveStyle(const std::string& tagName, const std::string& classAttr) const {
+  static bool lowHeapWarningLogged = false;
+  if (ESP.getFreeHeap() < MIN_FREE_HEAP_FOR_CSS) {
+    if (!lowHeapWarningLogged) {
+      lowHeapWarningLogged = true;
+      LOG_DBG("CSS", "Warning: low heap (%u bytes) below MIN_FREE_HEAP_FOR_CSS (%u), returning empty style",
+              ESP.getFreeHeap(), static_cast<unsigned>(MIN_FREE_HEAP_FOR_CSS));
+    }
+    return CssStyle{};
+  }
   CssStyle result;
   const std::string tag = normalized(tagName);
 
@@ -521,9 +566,17 @@ CssStyle CssParser::parseInlineStyle(const std::string& styleValue) { return par
 
 // Cache format version - increment when format changes
 constexpr uint8_t CSS_CACHE_VERSION = 2;
+constexpr char rulesCache[] = "/css_rules.cache";
 
-bool CssParser::saveToCache(FsFile& file) const {
-  if (!file) {
+bool CssParser::hasCache() const { return Storage.exists((cachePath + rulesCache).c_str()); }
+
+bool CssParser::saveToCache() const {
+  if (cachePath.empty()) {
+    return false;
+  }
+
+  FsFile file;
+  if (!Storage.openFileForWrite("CSS", cachePath + rulesCache, file)) {
     return false;
   }
 
@@ -582,12 +635,18 @@ bool CssParser::saveToCache(FsFile& file) const {
     file.write(reinterpret_cast<const uint8_t*>(&definedBits), sizeof(definedBits));
   }
 
-  Serial.printf("[%lu] [CSS] Saved %u rules to cache\n", millis(), ruleCount);
+  LOG_DBG("CSS", "Saved %u rules to cache", ruleCount);
+  file.close();
   return true;
 }
 
-bool CssParser::loadFromCache(FsFile& file) {
-  if (!file) {
+bool CssParser::loadFromCache() {
+  if (cachePath.empty()) {
+    return false;
+  }
+
+  FsFile file;
+  if (!Storage.openFileForRead("CSS", cachePath + rulesCache, file)) {
     return false;
   }
 
@@ -597,13 +656,15 @@ bool CssParser::loadFromCache(FsFile& file) {
   // Read and verify version
   uint8_t version = 0;
   if (file.read(&version, 1) != 1 || version != CSS_CACHE_VERSION) {
-    Serial.printf("[%lu] [CSS] Cache version mismatch (got %u, expected %u)\n", millis(), version, CSS_CACHE_VERSION);
+    LOG_DBG("CSS", "Cache version mismatch (got %u, expected %u)", version, CSS_CACHE_VERSION);
+    file.close();
     return false;
   }
 
   // Read rule count
   uint16_t ruleCount = 0;
   if (file.read(&ruleCount, sizeof(ruleCount)) != sizeof(ruleCount)) {
+    file.close();
     return false;
   }
 
@@ -613,6 +674,7 @@ bool CssParser::loadFromCache(FsFile& file) {
     uint16_t selectorLen = 0;
     if (file.read(&selectorLen, sizeof(selectorLen)) != sizeof(selectorLen)) {
       rulesBySelector_.clear();
+      file.close();
       return false;
     }
 
@@ -620,6 +682,7 @@ bool CssParser::loadFromCache(FsFile& file) {
     selector.resize(selectorLen);
     if (file.read(&selector[0], selectorLen) != selectorLen) {
       rulesBySelector_.clear();
+      file.close();
       return false;
     }
 
@@ -629,24 +692,28 @@ bool CssParser::loadFromCache(FsFile& file) {
 
     if (file.read(&enumVal, 1) != 1) {
       rulesBySelector_.clear();
+      file.close();
       return false;
     }
     style.textAlign = static_cast<CssTextAlign>(enumVal);
 
     if (file.read(&enumVal, 1) != 1) {
       rulesBySelector_.clear();
+      file.close();
       return false;
     }
     style.fontStyle = static_cast<CssFontStyle>(enumVal);
 
     if (file.read(&enumVal, 1) != 1) {
       rulesBySelector_.clear();
+      file.close();
       return false;
     }
     style.fontWeight = static_cast<CssFontWeight>(enumVal);
 
     if (file.read(&enumVal, 1) != 1) {
       rulesBySelector_.clear();
+      file.close();
       return false;
     }
     style.textDecoration = static_cast<CssTextDecoration>(enumVal);
@@ -668,6 +735,7 @@ bool CssParser::loadFromCache(FsFile& file) {
         !readLength(style.marginLeft) || !readLength(style.marginRight) || !readLength(style.paddingTop) ||
         !readLength(style.paddingBottom) || !readLength(style.paddingLeft) || !readLength(style.paddingRight)) {
       rulesBySelector_.clear();
+      file.close();
       return false;
     }
 
@@ -675,6 +743,7 @@ bool CssParser::loadFromCache(FsFile& file) {
     uint16_t definedBits = 0;
     if (file.read(&definedBits, sizeof(definedBits)) != sizeof(definedBits)) {
       rulesBySelector_.clear();
+      file.close();
       return false;
     }
     style.defined.textAlign = (definedBits & 1 << 0) != 0;
@@ -694,6 +763,7 @@ bool CssParser::loadFromCache(FsFile& file) {
     rulesBySelector_[selector] = style;
   }
 
-  Serial.printf("[%lu] [CSS] Loaded %u rules from cache\n", millis(), ruleCount);
+  LOG_DBG("CSS", "Loaded %u rules from cache", ruleCount);
+  file.close();
   return true;
 }

lib/Epub/Epub/css/CssParser.h

@@ -4,6 +4,7 @@
 
 #include <string>
 #include <unordered_map>
+#include <utility>
 #include <vector>
 
 #include "CssStyle.h"
@@ -29,7 +30,7 @@
  */
 class CssParser {
  public:
-  CssParser() = default;
+  explicit CssParser(std::string cachePath) : cachePath(std::move(cachePath)) {}
   ~CssParser() = default;
 
   // Non-copyable
@@ -76,28 +77,35 @@ class CssParser {
    */
   void clear() { rulesBySelector_.clear(); }
 
+  /**
+   * Check if CSS rules cache file exists
+   */
+  bool hasCache() const;
+
   /**
    * Save parsed CSS rules to a cache file.
-   * @param file Open file handle to write to
    * @return true if cache was written successfully
    */
-  bool saveToCache(FsFile& file) const;
+  bool saveToCache() const;
 
   /**
    * Load CSS rules from a cache file.
    * Clears any existing rules before loading.
-   * @param file Open file handle to read from
    * @return true if cache was loaded successfully
    */
-  bool loadFromCache(FsFile& file);
+  bool loadFromCache();
 
  private:
   // Storage: maps normalized selector -> style properties
   std::unordered_map<std::string, CssStyle> rulesBySelector_;
 
+  std::string cachePath;
+
   // Internal parsing helpers
-  void processRuleBlock(const std::string& selectorGroup, const std::string& declarations);
+  void processRuleBlockWithStyle(const std::string& selectorGroup, const CssStyle& style);
   static CssStyle parseDeclarations(const std::string& declBlock);
+  static void parseDeclarationIntoStyle(const std::string& decl, CssStyle& style, std::string& propNameBuf,
+                                        std::string& propValueBuf);
 
   // Individual property value parsers
   static CssTextAlign interpretAlignment(const std::string& val);
@@ -105,10 +113,10 @@ class CssParser {
   static CssFontWeight interpretFontWeight(const std::string& val);
   static CssTextDecoration interpretDecoration(const std::string& val);
   static CssLength interpretLength(const std::string& val);
-  static int8_t interpretSpacing(const std::string& val);
 
   // String utilities
   static std::string normalized(const std::string& s);
+  static void normalizedInto(const std::string& s, std::string& out);
   static std::vector<std::string> splitOnChar(const std::string& s, char delimiter);
   static std::vector<std::string> splitWhitespace(const std::string& s);
 };

lib/Epub/Epub/css/CssStyle.h

@@ -69,6 +69,7 @@ struct CssPropertyFlags {
   uint16_t paddingBottom : 1;
   uint16_t paddingLeft : 1;
   uint16_t paddingRight : 1;
+  uint16_t width : 1;
 
   CssPropertyFlags()
       : textAlign(0),
@@ -83,17 +84,19 @@ struct CssPropertyFlags {
         paddingTop(0),
         paddingBottom(0),
         paddingLeft(0),
-        paddingRight(0) {}
+        paddingRight(0),
+        width(0) {}
 
   [[nodiscard]] bool anySet() const {
     return textAlign || fontStyle || fontWeight || textDecoration || textIndent || marginTop || marginBottom ||
-           marginLeft || marginRight || paddingTop || paddingBottom || paddingLeft || paddingRight;
+           marginLeft || marginRight || paddingTop || paddingBottom || paddingLeft || paddingRight || width;
   }
 
   void clearAll() {
     textAlign = fontStyle = fontWeight = textDecoration = textIndent = 0;
     marginTop = marginBottom = marginLeft = marginRight = 0;
     paddingTop = paddingBottom = paddingLeft = paddingRight = 0;
+    width = 0;
   }
 };
 
@@ -115,6 +118,7 @@ struct CssStyle {
   CssLength paddingBottom;  // Padding after
   CssLength paddingLeft;    // Padding left
   CssLength paddingRight;   // Padding right
+  CssLength width;           // Element width (used for table columns/cells)
 
   CssPropertyFlags defined;  // Tracks which properties were explicitly set
 
@@ -173,6 +177,10 @@ struct CssStyle {
       paddingRight = base.paddingRight;
       defined.paddingRight = 1;
     }
+    if (base.hasWidth()) {
+      width = base.width;
+      defined.width = 1;
+    }
   }
 
   [[nodiscard]] bool hasTextAlign() const { return defined.textAlign; }
@@ -188,6 +196,7 @@ struct CssStyle {
   [[nodiscard]] bool hasPaddingBottom() const { return defined.paddingBottom; }
   [[nodiscard]] bool hasPaddingLeft() const { return defined.paddingLeft; }
   [[nodiscard]] bool hasPaddingRight() const { return defined.paddingRight; }
+  [[nodiscard]] bool hasWidth() const { return defined.width; }
 
   void reset() {
     textAlign = CssTextAlign::Left;
@@ -197,6 +206,7 @@ struct CssStyle {
     textIndent = CssLength{};
     marginTop = marginBottom = marginLeft = marginRight = CssLength{};
     paddingTop = paddingBottom = paddingLeft = paddingRight = CssLength{};
+    width = CssLength{};
     defined.clearAll();
   }
 };

lib/Epub/Epub/htmlEntities.cpp

@@ -0,0 +1,76 @@
+// from
+// https://github.com/atomic14/diy-esp32-epub-reader/blob/2c2f57fdd7e2a788d14a0bcb26b9e845a47aac42/lib/Epub/RubbishHtmlParser/htmlEntities.cpp
+
+#include "htmlEntities.h"
+
+#include <cstring>
+
+struct EntityPair {
+  const char* key;
+  const char* value;
+};
+
+static const EntityPair ENTITY_LOOKUP[] = {
+    {"&quot;", "\""},  {"&frasl;", "⁄"},   {"&amp;", "&"},         {"&lt;", "<"},     {"&gt;", ">"},
+    {"&Agrave;", "À"}, {"&Aacute;", "Á"},  {"&Acirc;", "Â"},       {"&Atilde;", "Ã"}, {"&Auml;", "Ä"},
+    {"&Aring;", "Å"},  {"&AElig;", "Æ"},   {"&Ccedil;", "Ç"},      {"&Egrave;", "È"}, {"&Eacute;", "É"},
+    {"&Ecirc;", "Ê"},  {"&Euml;", "Ë"},    {"&Igrave;", "Ì"},      {"&Iacute;", "Í"}, {"&Icirc;", "Î"},
+    {"&Iuml;", "Ï"},   {"&ETH;", "Ð"},     {"&Ntilde;", "Ñ"},      {"&Ograve;", "Ò"}, {"&Oacute;", "Ó"},
+    {"&Ocirc;", "Ô"},  {"&Otilde;", "Õ"},  {"&Ouml;", "Ö"},        {"&Oslash;", "Ø"}, {"&Ugrave;", "Ù"},
+    {"&Uacute;", "Ú"}, {"&Ucirc;", "Û"},   {"&Uuml;", "Ü"},        {"&Yacute;", "Ý"}, {"&THORN;", "Þ"},
+    {"&szlig;", "ß"},  {"&agrave;", "à"},  {"&aacute;", "á"},      {"&acirc;", "â"},  {"&atilde;", "ã"},
+    {"&auml;", "ä"},   {"&aring;", "å"},   {"&aelig;", "æ"},       {"&ccedil;", "ç"}, {"&egrave;", "è"},
+    {"&eacute;", "é"}, {"&ecirc;", "ê"},   {"&euml;", "ë"},        {"&igrave;", "ì"}, {"&iacute;", "í"},
+    {"&icirc;", "î"},  {"&iuml;", "ï"},    {"&eth;", "ð"},         {"&ntilde;", "ñ"}, {"&ograve;", "ò"},
+    {"&oacute;", "ó"}, {"&ocirc;", "ô"},   {"&otilde;", "õ"},      {"&ouml;", "ö"},   {"&oslash;", "ø"},
+    {"&ugrave;", "ù"}, {"&uacute;", "ú"},  {"&ucirc;", "û"},       {"&uuml;", "ü"},   {"&yacute;", "ý"},
+    {"&thorn;", "þ"},  {"&yuml;", "ÿ"},    {"&nbsp;", "\xC2\xA0"}, {"&iexcl;", "¡"},  {"&cent;", "¢"},
+    {"&pound;", "£"},  {"&curren;", "¤"},  {"&yen;", "¥"},         {"&brvbar;", "¦"}, {"&sect;", "§"},
+    {"&uml;", "¨"},    {"&copy;", "©"},    {"&ordf;", "ª"},        {"&laquo;", "«"},  {"&not;", "¬"},
+    {"&shy;", "­"},    {"&reg;", "®"},     {"&macr;", "¯"},        {"&deg;", "°"},    {"&plusmn;", "±"},
+    {"&sup2;", "²"},   {"&sup3;", "³"},    {"&acute;", "´"},       {"&micro;", "µ"},  {"&para;", "¶"},
+    {"&cedil;", "¸"},  {"&sup1;", "¹"},    {"&ordm;", "º"},        {"&raquo;", "»"},  {"&frac14;", "¼"},
+    {"&frac12;", "½"}, {"&frac34;", "¾"},  {"&iquest;", "¿"},      {"&times;", "×"},  {"&divide;", "÷"},
+    {"&forall;", "∀"}, {"&part;", "∂"},    {"&exist;", "∃"},       {"&empty;", "∅"},  {"&nabla;", "∇"},
+    {"&isin;", "∈"},   {"&notin;", "∉"},   {"&ni;", "∋"},          {"&prod;", "∏"},   {"&sum;", "∑"},
+    {"&minus;", "−"},  {"&lowast;", "∗"},  {"&radic;", "√"},       {"&prop;", "∝"},   {"&infin;", "∞"},
+    {"&ang;", "∠"},    {"&and;", "∧"},     {"&or;", "∨"},          {"&cap;", "∩"},    {"&cup;", "∪"},
+    {"&int;", "∫"},    {"&there4;", "∴"},  {"&sim;", "∼"},         {"&cong;", "≅"},   {"&asymp;", "≈"},
+    {"&ne;", "≠"},     {"&equiv;", "≡"},   {"&le;", "≤"},          {"&ge;", "≥"},     {"&sub;", "⊂"},
+    {"&sup;", "⊃"},    {"&nsub;", "⊄"},    {"&sube;", "⊆"},        {"&supe;", "⊇"},   {"&oplus;", "⊕"},
+    {"&otimes;", "⊗"}, {"&perp;", "⊥"},    {"&sdot;", "⋅"},        {"&Alpha;", "Α"},  {"&Beta;", "Β"},
+    {"&Gamma;", "Γ"},  {"&Delta;", "Δ"},   {"&Epsilon;", "Ε"},     {"&Zeta;", "Ζ"},   {"&Eta;", "Η"},
+    {"&Theta;", "Θ"},  {"&Iota;", "Ι"},    {"&Kappa;", "Κ"},       {"&Lambda;", "Λ"}, {"&Mu;", "Μ"},
+    {"&Nu;", "Ν"},     {"&Xi;", "Ξ"},      {"&Omicron;", "Ο"},     {"&Pi;", "Π"},     {"&Rho;", "Ρ"},
+    {"&Sigma;", "Σ"},  {"&Tau;", "Τ"},     {"&Upsilon;", "Υ"},     {"&Phi;", "Φ"},    {"&Chi;", "Χ"},
+    {"&Psi;", "Ψ"},    {"&Omega;", "Ω"},   {"&alpha;", "α"},       {"&beta;", "β"},   {"&gamma;", "γ"},
+    {"&delta;", "δ"},  {"&epsilon;", "ε"}, {"&zeta;", "ζ"},        {"&eta;", "η"},    {"&theta;", "θ"},
+    {"&iota;", "ι"},   {"&kappa;", "κ"},   {"&lambda;", "λ"},      {"&mu;", "μ"},     {"&nu;", "ν"},
+    {"&xi;", "ξ"},     {"&omicron;", "ο"}, {"&pi;", "π"},          {"&rho;", "ρ"},    {"&sigmaf;", "ς"},
+    {"&sigma;", "σ"},  {"&tau;", "τ"},     {"&upsilon;", "υ"},     {"&phi;", "φ"},    {"&chi;", "χ"},
+    {"&psi;", "ψ"},    {"&omega;", "ω"},   {"&thetasym;", "ϑ"},    {"&upsih;", "ϒ"},  {"&piv;", "ϖ"},
+    {"&OElig;", "Œ"},  {"&oelig;", "œ"},   {"&Scaron;", "Š"},      {"&scaron;", "š"}, {"&Yuml;", "Ÿ"},
+    {"&fnof;", "ƒ"},   {"&circ;", "ˆ"},    {"&tilde;", "˜"},       {"&ensp;", " "},   {"&emsp;", " "},
+    {"&thinsp;", " "}, {"&zwnj;", "‌"},  {"&zwj;", "‍"},       {"&lrm;", "‎"},  {"&rlm;", "‏"},
+    {"&ndash;", "–"},  {"&mdash;", "—"},   {"&lsquo;", "‘"},       {"&rsquo;", "’"},  {"&sbquo;", "‚"},
+    {"&ldquo;", "“"},  {"&rdquo;", "”"},   {"&bdquo;", "„"},       {"&dagger;", "†"}, {"&Dagger;", "‡"},
+    {"&bull;", "•"},   {"&hellip;", "…"},  {"&permil;", "‰"},      {"&prime;", "′"},  {"&Prime;", "″"},
+    {"&lsaquo;", "‹"}, {"&rsaquo;", "›"},  {"&oline;", "‾"},       {"&euro;", "€"},   {"&trade;", "™"},
+    {"&larr;", "←"},   {"&uarr;", "↑"},    {"&rarr;", "→"},        {"&darr;", "↓"},   {"&harr;", "↔"},
+    {"&crarr;", "↵"},  {"&lceil;", "⌈"},   {"&rceil;", "⌉"},       {"&lfloor;", "⌊"}, {"&rfloor;", "⌋"},
+    {"&loz;", "◊"},    {"&spades;", "♠"},  {"&clubs;", "♣"},       {"&hearts;", "♥"}, {"&diams;", "♦"}};
+
+static const size_t ENTITY_LOOKUP_COUNT = sizeof(ENTITY_LOOKUP) / sizeof(ENTITY_LOOKUP[0]);
+
+// Lookup a single HTML entity and return its UTF-8 value
+const char* lookupHtmlEntity(const char* entity, int len) {
+  for (size_t i = 0; i < ENTITY_LOOKUP_COUNT; i++) {
+    const char* key = ENTITY_LOOKUP[i].key;
+    const size_t keyLen = strlen(key);
+    if (static_cast<size_t>(len) == keyLen && memcmp(entity, key, keyLen) == 0) {
+      return ENTITY_LOOKUP[i].value;
+    }
+  }
+
+  return nullptr;  // Entity not found
+}

lib/Epub/Epub/htmlEntities.h

@@ -0,0 +1,9 @@
+// from
+// https://github.com/atomic14/diy-esp32-epub-reader/blob/2c2f57fdd7e2a788d14a0bcb26b9e845a47aac42/lib/Epub/RubbishHtmlParser/htmlEntities.cpp
+
+#pragma once
+#include <string>
+
+// Lookup a single HTML entity (including & and ;) and return its UTF-8 value
+// Returns nullptr if entity is not found
+const char* lookupHtmlEntity(const char* entity, int len);

lib/Epub/Epub/hyphenation/LanguageRegistry.cpp

@@ -1,45 +1,84 @@
 #include "LanguageRegistry.h"
 
 #include <algorithm>
-#include <array>
+#include <vector>
 
 #include "HyphenationCommon.h"
+#ifndef OMIT_HYPH_DE
 #include "generated/hyph-de.trie.h"
+#endif
+#ifndef OMIT_HYPH_EN
 #include "generated/hyph-en.trie.h"
+#endif
+#ifndef OMIT_HYPH_ES
 #include "generated/hyph-es.trie.h"
+#endif
+#ifndef OMIT_HYPH_FR
 #include "generated/hyph-fr.trie.h"
+#endif
+#ifndef OMIT_HYPH_IT
+#include "generated/hyph-it.trie.h"
+#endif
+#ifndef OMIT_HYPH_RU
 #include "generated/hyph-ru.trie.h"
+#endif
 
 namespace {
 
+#ifndef OMIT_HYPH_EN
 // English hyphenation patterns (3/3 minimum prefix/suffix length)
 LanguageHyphenator englishHyphenator(en_us_patterns, isLatinLetter, toLowerLatin, 3, 3);
+#endif
+#ifndef OMIT_HYPH_FR
 LanguageHyphenator frenchHyphenator(fr_patterns, isLatinLetter, toLowerLatin);
+#endif
+#ifndef OMIT_HYPH_DE
 LanguageHyphenator germanHyphenator(de_patterns, isLatinLetter, toLowerLatin);
+#endif
+#ifndef OMIT_HYPH_RU
 LanguageHyphenator russianHyphenator(ru_ru_patterns, isCyrillicLetter, toLowerCyrillic);
+#endif
+#ifndef OMIT_HYPH_ES
 LanguageHyphenator spanishHyphenator(es_patterns, isLatinLetter, toLowerLatin);
+#endif
+#ifndef OMIT_HYPH_IT
+LanguageHyphenator italianHyphenator(it_patterns, isLatinLetter, toLowerLatin);
+#endif
 
-using EntryArray = std::array<LanguageEntry, 5>;
-
-const EntryArray& entries() {
-  static const EntryArray kEntries = {{{"english", "en", &englishHyphenator},
-                                       {"french", "fr", &frenchHyphenator},
-                                       {"german", "de", &germanHyphenator},
-                                       {"russian", "ru", &russianHyphenator},
-                                       {"spanish", "es", &spanishHyphenator}}};
-  return kEntries;
+const LanguageEntryView entries() {
+  static const std::vector<LanguageEntry> kEntries = {
+#ifndef OMIT_HYPH_EN
+      {"english", "en", &englishHyphenator},
+#endif
+#ifndef OMIT_HYPH_FR
+      {"french", "fr", &frenchHyphenator},
+#endif
+#ifndef OMIT_HYPH_DE
+      {"german", "de", &germanHyphenator},
+#endif
+#ifndef OMIT_HYPH_RU
+      {"russian", "ru", &russianHyphenator},
+#endif
+#ifndef OMIT_HYPH_ES
+      {"spanish", "es", &spanishHyphenator},
+#endif
+#ifndef OMIT_HYPH_IT
+      {"italian", "it", &italianHyphenator},
+#endif
+  };
+  static const LanguageEntryView view{kEntries.data(), kEntries.size()};
+  return view;
 }
 
 }  // namespace
 
 const LanguageHyphenator* getLanguageHyphenatorForPrimaryTag(const std::string& primaryTag) {
-  const auto& allEntries = entries();
+  const auto allEntries = entries();
   const auto it = std::find_if(allEntries.begin(), allEntries.end(),
                                [&primaryTag](const LanguageEntry& entry) { return primaryTag == entry.primaryTag; });
   return (it != allEntries.end()) ? it->hyphenator : nullptr;
 }
 
 LanguageEntryView getLanguageEntries() {
-  const auto& allEntries = entries();
-  return LanguageEntryView{allEntries.data(), allEntries.size()};
+  return entries();
 }

lib/Epub/Epub/hyphenation/generated/hyph-it.trie.h

@@ -0,0 +1,113 @@
+#pragma once
+
+#include <cstddef>
+#include <cstdint>
+
+#include "../SerializedHyphenationTrie.h"
+
+// Auto-generated by generate_hyphenation_trie.py. Do not edit manually.
+alignas(4) constexpr uint8_t it_trie_data[] = {
+    0x00, 0x00, 0x05, 0xC4, 0x17, 0x0C, 0x33, 0x35, 0x0C, 0x29, 0x22, 0x0D, 0x3E, 0x0B, 0x47, 0x20,
+    0x0D, 0x16, 0x0B, 0x34, 0x0D, 0x21, 0x0C, 0x3D, 0x1F, 0x0C, 0x2A, 0x17, 0x2A, 0x0B, 0x02, 0x0C,
+    0x01, 0x02, 0x16, 0x02, 0x0D, 0x0C, 0x0C, 0x0D, 0x03, 0x0C, 0x01, 0x0C, 0x0E, 0x0D, 0x04, 0x02,
+    0x0B, 0xA0, 0x00, 0x42, 0x21, 0x6E, 0xFD, 0xA0, 0x00, 0x72, 0x21, 0x6E, 0xFD, 0xA1, 0x00, 0x61,
+    0x6D, 0xFD, 0x21, 0x69, 0xFB, 0x21, 0x74, 0xFD, 0x22, 0x70, 0x6E, 0xEC, 0xFD, 0xA0, 0x00, 0x91,
+    0x21, 0x6F, 0xFD, 0x21, 0x69, 0xFD, 0xA0, 0x00, 0xA2, 0x21, 0x73, 0xFD, 0x21, 0x70, 0xFD, 0xA0,
+    0x00, 0xC2, 0x21, 0x6D, 0xFD, 0x21, 0x75, 0xFD, 0x21, 0x63, 0xFD, 0x21, 0x72, 0xFD, 0xA0, 0x00,
+    0xE1, 0x21, 0x6F, 0xFD, 0x21, 0x72, 0xFD, 0x21, 0x74, 0xFD, 0x21, 0x6E, 0xFD, 0xA3, 0x01, 0x11,
+    0x61, 0x69, 0x6F, 0xDF, 0xEE, 0xFD, 0xA0, 0x00, 0xF2, 0x21, 0x65, 0xFD, 0x21, 0x6E, 0xFD, 0x21,
+    0x69, 0xFD, 0x21, 0x63, 0xFD, 0x21, 0x73, 0xFD, 0xA1, 0x01, 0x11, 0x69, 0xFD, 0xA0, 0x01, 0x12,
+    0x21, 0x75, 0xFD, 0x21, 0x65, 0xFD, 0x21, 0x78, 0xFD, 0xA0, 0x01, 0x32, 0x21, 0x6B, 0xFD, 0x21,
+    0x6E, 0xFD, 0xA0, 0x00, 0x71, 0x21, 0x65, 0xFD, 0x22, 0x61, 0x65, 0xF7, 0xFD, 0x21, 0x72, 0xFB,
+    0xA0, 0x01, 0x52, 0x21, 0x61, 0xFD, 0x21, 0x73, 0xFD, 0x21, 0x70, 0xFD, 0x21, 0x69, 0xFD, 0xA0,
+    0x01, 0x71, 0x21, 0x6F, 0xFD, 0x21, 0x63, 0xFD, 0x21, 0x72, 0xFD, 0x21, 0x61, 0xFD, 0xA0, 0x00,
+    0x61, 0x21, 0x6F, 0xFD, 0x21, 0x74, 0xFD, 0x41, 0x70, 0xFF, 0x50, 0x21, 0x6F, 0xFC, 0x21, 0x74,
+    0xFD, 0x22, 0x70, 0x72, 0xF3, 0xFD, 0x21, 0x61, 0xE8, 0x21, 0x72, 0xFD, 0xA0, 0x00, 0xF1, 0x22,
+    0x6C, 0x72, 0xFD, 0xFD, 0x21, 0x69, 0xE3, 0x21, 0x6C, 0xFD, 0x41, 0x65, 0xFF, 0x43, 0xA0, 0x01,
+    0x11, 0x25, 0x61, 0x68, 0x6F, 0x72, 0x73, 0xE8, 0xEE, 0xF6, 0xF9, 0xFD, 0xA0, 0x01, 0x82, 0x21,
+    0x72, 0xFD, 0x21, 0x63, 0xFD, 0x21, 0x73, 0xFD, 0x21, 0x69, 0xFD, 0x21, 0x65, 0xFD, 0xA0, 0x01,
+    0xA2, 0x21, 0x65, 0xFD, 0x21, 0x72, 0xFD, 0x21, 0x61, 0xFD, 0x41, 0x75, 0xFF, 0x4C, 0x42, 0x6C,
+    0x72, 0xFF, 0xFC, 0xFF, 0x48, 0x21, 0x62, 0xF9, 0x22, 0x68, 0x75, 0xEF, 0xFD, 0x47, 0x63, 0x64,
+    0x6C, 0x6E, 0x70, 0x72, 0x74, 0xFF, 0x5C, 0xFF, 0x5C, 0xFF, 0x5C, 0xFF, 0x5C, 0xFF, 0x5C, 0xFF,
+    0x5C, 0xFF, 0x5C, 0x21, 0x73, 0xEA, 0x21, 0x6E, 0xFD, 0x21, 0x61, 0xFD, 0xA1, 0x01, 0x11, 0x72,
+    0xFD, 0x41, 0x6E, 0xFF, 0x15, 0x21, 0x67, 0xFC, 0xA0, 0x01, 0xC2, 0x21, 0x74, 0xFD, 0x21, 0x6C,
+    0xFD, 0x22, 0x61, 0x65, 0xF4, 0xFD, 0x52, 0x61, 0x62, 0x63, 0x64, 0x65, 0x66, 0x6C, 0x6E, 0x6F,
+    0x70, 0x72, 0x73, 0x74, 0x77, 0x68, 0x6A, 0x6B, 0x7A, 0xFE, 0xC2, 0xFE, 0xCD, 0xFE, 0xF7, 0xFF,
+    0x12, 0xFF, 0x20, 0xFF, 0x37, 0xFF, 0x46, 0xFF, 0x55, 0xFF, 0x6B, 0xFF, 0x8B, 0xFF, 0xA5, 0xFF,
+    0xC2, 0xFF, 0xE6, 0xFF, 0xFB, 0xFF, 0x88, 0xFF, 0x88, 0xFF, 0x88, 0xFF, 0x88, 0xA0, 0x01, 0xE2,
+    0xA0, 0x00, 0xD1, 0x24, 0x61, 0x65, 0x6F, 0x75, 0xFD, 0xFD, 0xFD, 0xFD, 0x21, 0x6F, 0xF4, 0x21,
+    0x61, 0xF1, 0xA0, 0x01, 0xE1, 0x21, 0x2E, 0xFD, 0x24, 0x69, 0x75, 0x79, 0x74, 0xEB, 0xF4, 0xF7,
+    0xFD, 0x21, 0x75, 0xDF, 0xA0, 0x00, 0x51, 0x22, 0x69, 0x77, 0xFA, 0xFD, 0x21, 0x69, 0xD7, 0xAE,
+    0x02, 0x01, 0x62, 0x63, 0x64, 0x66, 0x6D, 0x6E, 0x70, 0x73, 0x74, 0x76, 0x6C, 0x72, 0x2E, 0x27,
+    0xE3, 0xE3, 0xE3, 0xE3, 0xE3, 0xE3, 0xE3, 0xE3, 0xE3, 0xE3, 0xF5, 0xF5, 0xE3, 0xE3, 0x22, 0x2E,
+    0x27, 0xC4, 0xC7, 0xC6, 0x00, 0x51, 0x68, 0x2E, 0x27, 0x62, 0x72, 0x6E, 0xFF, 0xBF, 0xFF, 0xBF,
+    0xFF, 0xFB, 0xFF, 0xBF, 0xFE, 0xFB, 0xFF, 0xBF, 0xD0, 0x02, 0x01, 0x62, 0x63, 0x64, 0x66, 0x6B,
+    0x6D, 0x6E, 0x71, 0x73, 0x74, 0x7A, 0x68, 0x6C, 0x72, 0x2E, 0x27, 0xFF, 0xAA, 0xFF, 0xAA, 0xFF,
+    0xAA, 0xFF, 0xAA, 0xFF, 0xAA, 0xFF, 0xAA, 0xFF, 0xAA, 0xFF, 0xAA, 0xFF, 0xAA, 0xFF, 0xAA, 0xFF,
+    0xAA, 0xFF, 0xEB, 0xFF, 0xBC, 0xFF, 0xBC, 0xFF, 0xAA, 0xFF, 0xAA, 0xCE, 0x02, 0x01, 0x62, 0x64,
+    0x67, 0x6C, 0x6D, 0x6E, 0x70, 0x72, 0x73, 0x74, 0x76, 0x77, 0x2E, 0x27, 0xFF, 0x77, 0xFF, 0x77,
+    0xFF, 0x77, 0xFF, 0x77, 0xFF, 0x77, 0xFF, 0x77, 0xFF, 0x77, 0xFF, 0x89, 0xFF, 0x77, 0xFF, 0x77,
+    0xFF, 0x77, 0xFF, 0x77, 0xFF, 0x77, 0xFF, 0x77, 0xCA, 0x02, 0x01, 0x62, 0x67, 0x66, 0x6E, 0x6C,
+    0x72, 0x73, 0x74, 0x2E, 0x27, 0xFF, 0x4A, 0xFF, 0x4A, 0xFF, 0x4A, 0xFF, 0x4A, 0xFF, 0x5C, 0xFF,
+    0x5C, 0xFF, 0x4A, 0xFF, 0x4A, 0xFF, 0x4A, 0xFF, 0x4A, 0xA0, 0x02, 0x12, 0xA1, 0x00, 0x51, 0x74,
+    0xFD, 0xD1, 0x02, 0x01, 0x62, 0x64, 0x66, 0x67, 0x68, 0x6C, 0x6D, 0x6E, 0x70, 0x72, 0x73, 0x74,
+    0x76, 0x77, 0x7A, 0x2E, 0x27, 0xFF, 0x21, 0xFF, 0x21, 0xFF, 0x21, 0xFF, 0x21, 0xFF, 0xFB, 0xFF,
+    0x33, 0xFF, 0x21, 0xFF, 0x33, 0xFF, 0x21, 0xFF, 0x33, 0xFF, 0x21, 0xFF, 0x21, 0xFF, 0x21, 0xFF,
+    0x21, 0xFF, 0x21, 0xFF, 0x21, 0xFF, 0x21, 0x41, 0x70, 0xFD, 0x4D, 0xCB, 0x02, 0x01, 0x62, 0x64,
+    0x68, 0x69, 0x6C, 0x6D, 0x6E, 0x72, 0x76, 0x2E, 0x27, 0xFE, 0xE7, 0xFE, 0xE7, 0xFE, 0xE7, 0xFF,
+    0xFC, 0xFE, 0xF9, 0xFE, 0xE7, 0xFE, 0xE7, 0xFE, 0xE7, 0xFE, 0xE7, 0xFE, 0xE7, 0xFE, 0xE7, 0xC2,
+    0x02, 0x01, 0x2E, 0x27, 0xFE, 0xC3, 0xFE, 0xC3, 0xCB, 0x02, 0x01, 0x67, 0x66, 0x68, 0x6B, 0x6C,
+    0x6D, 0x72, 0x73, 0x74, 0x2E, 0x27, 0xFE, 0xBA, 0xFE, 0xBA, 0xFE, 0xCC, 0xFE, 0xBA, 0xFE, 0xCC,
+    0xFE, 0xBA, 0xFE, 0xCC, 0xFE, 0xBA, 0xFE, 0xBA, 0xFE, 0xBA, 0xFE, 0xBA, 0xA0, 0x02, 0x33, 0x42,
+    0x2E, 0x27, 0xFE, 0x93, 0xFE, 0x93, 0xD5, 0x02, 0x01, 0x62, 0x63, 0x64, 0x66, 0x67, 0x68, 0x6A,
+    0x6B, 0x6C, 0x6D, 0x6E, 0x70, 0x71, 0x72, 0x73, 0x74, 0x76, 0x77, 0x7A, 0x2E, 0x27, 0xFE, 0x8C,
+    0xFE, 0x8C, 0xFE, 0x8C, 0xFF, 0xF6, 0xFE, 0x8C, 0xFE, 0x9E, 0xFE, 0x9E, 0xFE, 0x8C, 0xFE, 0x8C,
+    0xFE, 0x8C, 0xFE, 0x8C, 0xFE, 0x8C, 0xFE, 0x8C, 0xFE, 0x8C, 0xFE, 0x8C, 0xFE, 0x8C, 0xFE, 0x8C,
+    0xFE, 0x8C, 0xFE, 0x8C, 0xFE, 0x8C, 0xFF, 0xF9, 0xCF, 0x02, 0x01, 0x62, 0x63, 0x66, 0x6C, 0x6D,
+    0x6E, 0x70, 0x71, 0x72, 0x73, 0x74, 0x76, 0x77, 0x2E, 0x27, 0xFE, 0x4A, 0xFE, 0x4A, 0xFE, 0x4A,
+    0xFE, 0x4A, 0xFE, 0x4A, 0xFE, 0x4A, 0xFE, 0x4A, 0xFE, 0x4A, 0xFE, 0x4A, 0xFE, 0x4A, 0xFE, 0x4A,
+    0xFE, 0x4A, 0xFE, 0x4A, 0xFE, 0x4A, 0xFE, 0x4A, 0xA0, 0x02, 0x62, 0xA1, 0x01, 0xE1, 0x6E, 0xFD,
+    0x21, 0x72, 0xF8, 0x21, 0x65, 0xFD, 0xA1, 0x01, 0xE1, 0x66, 0xFD, 0x41, 0x74, 0xFE, 0x07, 0x21,
+    0x69, 0xFC, 0x21, 0x65, 0xFD, 0xD3, 0x02, 0x01, 0x62, 0x63, 0x64, 0x66, 0x67, 0x6B, 0x6C, 0x6D,
+    0x6E, 0x70, 0x71, 0x72, 0x73, 0x74, 0x76, 0x7A, 0x68, 0x2E, 0x27, 0xFD, 0xFD, 0xFD, 0xFD, 0xFD,
+    0xFD, 0xFD, 0xFD, 0xFF, 0xE6, 0xFD, 0xFD, 0xFD, 0xFD, 0xFD, 0xFD, 0xFD, 0xFD, 0xFD, 0xFD, 0xFD,
+    0xFD, 0xFD, 0xFD, 0xFF, 0xF1, 0xFD, 0xFD, 0xFD, 0xFD, 0xFD, 0xFD, 0xFF, 0xFD, 0xFD, 0xFD, 0xFD,
+    0xFD, 0xA0, 0x02, 0x82, 0xA1, 0x01, 0xE1, 0x65, 0xFD, 0x21, 0x63, 0xF8, 0xA1, 0x01, 0xE1, 0x69,
+    0xFD, 0xCB, 0x02, 0x01, 0x64, 0x68, 0x6C, 0x6E, 0x70, 0x72, 0x73, 0x74, 0x7A, 0x2E, 0x27, 0xFD,
+    0xB1, 0xFD, 0xC3, 0xFD, 0xC3, 0xFF, 0xF3, 0xFD, 0xB1, 0xFD, 0xC3, 0xFF, 0xFB, 0xFD, 0xB1, 0xFD,
+    0xB1, 0xFD, 0xB1, 0xFD, 0xB1, 0xC3, 0x02, 0x01, 0x71, 0x2E, 0x27, 0xFD, 0x8D, 0xFD, 0x8D, 0xFD,
+    0x8D, 0xA0, 0x02, 0x53, 0xA1, 0x01, 0xE1, 0x73, 0xFD, 0xD5, 0x02, 0x01, 0x62, 0x63, 0x64, 0x66,
+    0x68, 0x67, 0x6B, 0x6C, 0x6D, 0x6E, 0x70, 0x71, 0x72, 0x73, 0x74, 0x76, 0x78, 0x77, 0x7A, 0x2E,
+    0x27, 0xFD, 0x79, 0xFD, 0x79, 0xFD, 0x79, 0xFD, 0x79, 0xFD, 0x8B, 0xFD, 0x79, 0xFD, 0x79, 0xFD,
+    0x79, 0xFD, 0x79, 0xFD, 0x79, 0xFD, 0x79, 0xFD, 0x79, 0xFD, 0x79, 0xFD, 0x79, 0xFF, 0xFB, 0xFD,
+    0x79, 0xFD, 0x79, 0xFD, 0x79, 0xFD, 0x79, 0xFD, 0x79, 0xFD, 0x79, 0x43, 0x6D, 0x2E, 0x27, 0xFD,
+    0x37, 0xFD, 0x37, 0xFD, 0x37, 0xA0, 0x02, 0xC2, 0xA1, 0x02, 0x32, 0x6D, 0xFD, 0x41, 0x6E, 0xFE,
+    0x8F, 0x4B, 0x62, 0x63, 0x64, 0x66, 0x67, 0x6D, 0x6E, 0x70, 0x73, 0x74, 0x76, 0xFD, 0x21, 0xFD,
+    0x21, 0xFD, 0x21, 0xFD, 0x21, 0xFD, 0x21, 0xFD, 0x21, 0xFD, 0x21, 0xFD, 0x21, 0xFD, 0x21, 0xFD,
+    0x21, 0xFD, 0x21, 0xA0, 0x02, 0xE1, 0x22, 0x2E, 0x27, 0xFD, 0xFD, 0xC7, 0x02, 0xA2, 0x68, 0x73,
+    0x70, 0x74, 0x7A, 0x2E, 0x27, 0xFF, 0xC0, 0xFF, 0xCD, 0xFF, 0xD2, 0xFF, 0xD6, 0xFC, 0xF7, 0xFF,
+    0xF8, 0xFF, 0xFB, 0xC1, 0x00, 0x51, 0x2E, 0xFC, 0xDF, 0x41, 0x68, 0xFF, 0x18, 0xA1, 0x00, 0x51,
+    0x63, 0xFC, 0xC1, 0x01, 0xE1, 0x73, 0xFE, 0xB6, 0xC2, 0x00, 0x51, 0x6B, 0x73, 0xFC, 0xCA, 0xFC,
+    0x06, 0xD2, 0x02, 0x01, 0x62, 0x63, 0x64, 0x66, 0x67, 0x68, 0x6C, 0x6D, 0x6E, 0x70, 0x72, 0x73,
+    0x74, 0x76, 0x77, 0x7A, 0x2E, 0x27, 0xFC, 0xC1, 0xFC, 0xC1, 0xFC, 0xC1, 0xFC, 0xC1, 0xFC, 0xC1,
+    0xFF, 0xE2, 0xFC, 0xD3, 0xFC, 0xC1, 0xFC, 0xC1, 0xFC, 0xC1, 0xFC, 0xD3, 0xFF, 0xEC, 0xFF, 0xF1,
+    0xFC, 0xC1, 0xFC, 0xC1, 0xFF, 0xF7, 0xFC, 0xC1, 0xFE, 0x2E, 0xC6, 0x02, 0x01, 0x63, 0x6C, 0x72,
+    0x76, 0x2E, 0x27, 0xFC, 0x88, 0xFC, 0x9A, 0xFC, 0x9A, 0xFC, 0x88, 0xFC, 0x88, 0xFD, 0xF5, 0x41,
+    0x72, 0xFB, 0xAF, 0xA0, 0x02, 0xF2, 0xC5, 0x02, 0x01, 0x68, 0x61, 0x79, 0x2E, 0x27, 0xFC, 0x7E,
+    0xFF, 0xF9, 0xFF, 0xFD, 0xFC, 0x6C, 0xFC, 0x6C, 0xCA, 0x02, 0x01, 0x62, 0x63, 0x66, 0x68, 0x6D,
+    0x70, 0x74, 0x77, 0x2E, 0x27, 0xFC, 0x5A, 0xFC, 0x5A, 0xFC, 0x5A, 0xFC, 0x5A, 0xFC, 0x5A, 0xFC,
+    0x5A, 0xFC, 0x5A, 0xFC, 0x5A, 0xFC, 0x5A, 0xFC, 0x5A, 0x42, 0x6F, 0x69, 0xFC, 0x48, 0xFC, 0x27,
+    0xCB, 0x02, 0x01, 0x62, 0x64, 0x6C, 0x6E, 0x70, 0x74, 0x73, 0x76, 0x7A, 0x2E, 0x27, 0xFC, 0x32,
+    0xFC, 0x32, 0xFC, 0x32, 0xFC, 0x32, 0xFC, 0x32, 0xFC, 0x32, 0xFC, 0x32, 0xFC, 0x32, 0xFC, 0x32,
+    0xFC, 0x32, 0xFD, 0x9F, 0x5A, 0x2E, 0x27, 0x61, 0x65, 0x6F, 0x62, 0x63, 0x64, 0x66, 0x67, 0x68,
+    0x6A, 0x6B, 0x6C, 0x6D, 0x6E, 0x70, 0x71, 0x72, 0x73, 0x74, 0x76, 0x77, 0x78, 0x79, 0x7A, 0xFB,
+    0xC2, 0xFB, 0xF9, 0xFC, 0x14, 0xFC, 0x23, 0xFC, 0x28, 0xFC, 0x2B, 0xFC, 0x64, 0xFC, 0x97, 0xFC,
+    0xC4, 0xFC, 0xED, 0xFD, 0x27, 0xFD, 0x4B, 0xFD, 0x54, 0xFD, 0x82, 0xFD, 0xC4, 0xFE, 0x11, 0xFE,
+    0x5D, 0xFE, 0x81, 0xFE, 0x95, 0xFF, 0x17, 0xFF, 0x4D, 0xFF, 0x86, 0xFF, 0xA2, 0xFF, 0xB4, 0xFF,
+    0xD5, 0xFF, 0xDC,
+};
+
+constexpr SerializedHyphenationPatterns it_patterns = {
+    it_trie_data,
+    sizeof(it_trie_data),
+};

lib/Epub/Epub/parsers/ChapterHtmlSlimParser.cpp

@@ -1,17 +1,24 @@
 #include "ChapterHtmlSlimParser.h"
 
+#include <FsHelpers.h>
 #include <GfxRenderer.h>
 #include <HalStorage.h>
-#include <HardwareSerial.h>
+#include <Logging.h>
 #include <expat.h>
 
+#include <algorithm>
+
+#include "../../Epub.h"
 #include "../Page.h"
+#include "../converters/ImageDecoderFactory.h"
+#include "../converters/ImageToFramebufferDecoder.h"
+#include "../htmlEntities.h"
 
 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 indexing popup - smaller chapters don't benefit from it
-constexpr size_t MIN_SIZE_FOR_POPUP = 50 * 1024;  // 50KB
+constexpr size_t MIN_SIZE_FOR_POPUP = 10 * 1024;  // 10KB
 
 const char* BLOCK_TAGS[] = {"p", "li", "div", "br", "blockquote"};
 constexpr int NUM_BLOCK_TAGS = sizeof(BLOCK_TAGS) / sizeof(BLOCK_TAGS[0]);
@@ -31,8 +38,30 @@ constexpr int NUM_IMAGE_TAGS = sizeof(IMAGE_TAGS) / sizeof(IMAGE_TAGS[0]);
 const char* SKIP_TAGS[] = {"head"};
 constexpr int NUM_SKIP_TAGS = sizeof(SKIP_TAGS) / sizeof(SKIP_TAGS[0]);
 
+// Table tags that are transparent containers (just depth tracking, no special handling)
+const char* TABLE_TRANSPARENT_TAGS[] = {"thead", "tbody", "tfoot", "colgroup"};
+constexpr int NUM_TABLE_TRANSPARENT_TAGS = sizeof(TABLE_TRANSPARENT_TAGS) / sizeof(TABLE_TRANSPARENT_TAGS[0]);
+
+// Table tags to skip entirely (their children produce no useful output)
+const char* TABLE_SKIP_TAGS[] = {"caption"};
+constexpr int NUM_TABLE_SKIP_TAGS = sizeof(TABLE_SKIP_TAGS) / sizeof(TABLE_SKIP_TAGS[0]);
+
 bool isWhitespace(const char c) { return c == ' ' || c == '\r' || c == '\n' || c == '\t'; }
 
+// Parse an HTML width attribute value into a CssLength.
+// "200" -> 200px, "50%" -> 50 percent. Returns false if the value can't be parsed.
+static bool parseHtmlWidthAttr(const char* value, CssLength& out) {
+  char* end = nullptr;
+  const float num = strtof(value, &end);
+  if (end == value || num < 0) return false;
+  if (*end == '%') {
+    out = CssLength(num, CssUnit::Percent);
+  } else {
+    out = CssLength(num, CssUnit::Pixels);
+  }
+  return true;
+}
+
 // given the start and end of a tag, check to see if it matches a known tag
 bool matches(const char* tag_name, const char* possible_tags[], const int possible_tag_count) {
   for (int i = 0; i < possible_tag_count; i++) {
@@ -90,13 +119,37 @@ void ChapterHtmlSlimParser::flushPartWordBuffer() {
 
   // flush the buffer
   partWordBuffer[partWordBufferIndex] = '\0';
-  currentTextBlock->addWord(partWordBuffer, fontStyle, false, nextWordContinues);
+
+  // Handle double-encoded &nbsp; entities (e.g. &amp;nbsp; in source -> literal "&nbsp;" after
+  // XML parsing). Common in Wikipedia and other generated EPUBs. Replace with a space so the text
+  // renders cleanly. The space stays within the word, preserving non-breaking behavior.
+  std::string flushedWord(partWordBuffer);
+  size_t entityPos = 0;
+  while ((entityPos = flushedWord.find("&nbsp;", entityPos)) != std::string::npos) {
+    flushedWord.replace(entityPos, 6, " ");
+    entityPos += 1;
+  }
+
+  currentTextBlock->addWord(flushedWord, fontStyle, false, nextWordContinues);
   partWordBufferIndex = 0;
   nextWordContinues = false;
 }
 
 // start a new text block if needed
 void ChapterHtmlSlimParser::startNewTextBlock(const BlockStyle& blockStyle) {
+  // When inside a table cell, don't lay out to the page -- insert a forced line break
+  // within the cell's ParsedText so that block elements (p, div, br) create visual breaks.
+  if (inTable) {
+    if (partWordBufferIndex > 0) {
+      flushPartWordBuffer();
+    }
+    if (currentTextBlock && !currentTextBlock->isEmpty()) {
+      currentTextBlock->addLineBreak();
+    }
+    nextWordContinues = false;
+    return;
+  }
+
   nextWordContinues = false;  // New block = new paragraph, no continuation
   if (currentTextBlock) {
     // already have a text block running and it is empty - just reuse it
@@ -139,46 +192,304 @@ void XMLCALL ChapterHtmlSlimParser::startElement(void* userData, const XML_Char*
   centeredBlockStyle.textAlignDefined = true;
   centeredBlockStyle.alignment = CssTextAlign::Center;
 
-  // Special handling for tables - show placeholder text instead of dropping silently
+  // --- Table handling ---
   if (strcmp(name, "table") == 0) {
-    // Add placeholder text
-    self->startNewTextBlock(centeredBlockStyle);
+    if (self->inTable) {
+      // Nested table: skip it entirely for v1
+      self->skipUntilDepth = self->depth;
+      self->depth += 1;
+      return;
+    }
+
+    // Flush any pending content before the table
+    if (self->currentTextBlock && !self->currentTextBlock->isEmpty()) {
+      self->makePages();
+    }
+
+    self->inTable = true;
+    self->tableData.reset(new TableData());
+
+    // Create a safe empty currentTextBlock so character data outside cells
+    // (e.g. whitespace between tags) doesn't crash
+    auto tableBlockStyle = BlockStyle();
+    tableBlockStyle.alignment = CssTextAlign::Left;
+    self->currentTextBlock.reset(new ParsedText(self->extraParagraphSpacing, self->hyphenationEnabled, tableBlockStyle));
 
-    self->italicUntilDepth = min(self->italicUntilDepth, self->depth);
-    // Advance depth before processing character data (like you would for an element with text)
     self->depth += 1;
-    self->characterData(userData, "[Table omitted]", strlen("[Table omitted]"));
-
-    // Skip table contents (skip until parent as we pre-advanced depth above)
-    self->skipUntilDepth = self->depth - 1;
     return;
   }
 
-  if (matches(name, IMAGE_TAGS, NUM_IMAGE_TAGS)) {
-    // TODO: Start processing image tags
-    std::string alt = "[Image]";
-    if (atts != nullptr) {
-      for (int i = 0; atts[i]; i += 2) {
-        if (strcmp(atts[i], "alt") == 0) {
-          if (strlen(atts[i + 1]) > 0) {
-            alt = "[Image: " + std::string(atts[i + 1]) + "]";
-          }
-          break;
-        }
-      }
+  // Table structure tags (only when inside a table)
+  if (self->inTable) {
+    if (strcmp(name, "tr") == 0) {
+      self->tableData->rows.push_back(TableRow());
+      self->depth += 1;
+      return;
     }
 
-    Serial.printf("[%lu] [EHP] Image alt: %s\n", millis(), alt.c_str());
+    // <col> — capture width hint for column sizing
+    if (strcmp(name, "col") == 0) {
+      CssLength widthHint;
+      bool hasHint = false;
 
-    self->startNewTextBlock(centeredBlockStyle);
-    self->italicUntilDepth = min(self->italicUntilDepth, self->depth);
-    // Advance depth before processing character data (like you would for an element with text)
-    self->depth += 1;
-    self->characterData(userData, alt.c_str(), alt.length());
+      // Parse HTML width attribute
+      if (atts != nullptr) {
+        for (int i = 0; atts[i]; i += 2) {
+          if (strcmp(atts[i], "width") == 0) {
+            hasHint = parseHtmlWidthAttr(atts[i + 1], widthHint);
+            break;
+          }
+        }
+      }
 
-    // Skip table contents (skip until parent as we pre-advanced depth above)
-    self->skipUntilDepth = self->depth - 1;
-    return;
+      // CSS width (inline style) overrides HTML attribute
+      if (self->cssParser) {
+        std::string styleAttr;
+        if (atts != nullptr) {
+          for (int i = 0; atts[i]; i += 2) {
+            if (strcmp(atts[i], "style") == 0) {
+              styleAttr = atts[i + 1];
+              break;
+            }
+          }
+        }
+        if (!styleAttr.empty()) {
+          CssStyle inlineStyle = CssParser::parseInlineStyle(styleAttr);
+          if (inlineStyle.hasWidth()) {
+            widthHint = inlineStyle.width;
+            hasHint = true;
+          }
+        }
+      }
+
+      if (hasHint) {
+        self->tableData->colWidthHints.push_back(widthHint);
+      } else {
+        // Push a zero-value placeholder to maintain index alignment
+        self->tableData->colWidthHints.push_back(CssLength());
+      }
+
+      self->depth += 1;
+      return;
+    }
+
+    if (strcmp(name, "td") == 0 || strcmp(name, "th") == 0) {
+      const bool isHeader = strcmp(name, "th") == 0;
+
+      // Parse colspan and width attributes
+      int colspan = 1;
+      CssLength cellWidthHint;
+      bool hasCellWidthHint = false;
+      std::string cellStyleAttr;
+
+      if (atts != nullptr) {
+        for (int i = 0; atts[i]; i += 2) {
+          if (strcmp(atts[i], "colspan") == 0) {
+            colspan = atoi(atts[i + 1]);
+            if (colspan < 1) colspan = 1;
+          } else if (strcmp(atts[i], "width") == 0) {
+            hasCellWidthHint = parseHtmlWidthAttr(atts[i + 1], cellWidthHint);
+          } else if (strcmp(atts[i], "style") == 0) {
+            cellStyleAttr = atts[i + 1];
+          }
+        }
+      }
+
+      // CSS width (inline style or stylesheet) overrides HTML attribute
+      if (self->cssParser) {
+        std::string classAttr;
+        if (atts != nullptr) {
+          for (int i = 0; atts[i]; i += 2) {
+            if (strcmp(atts[i], "class") == 0) {
+              classAttr = atts[i + 1];
+              break;
+            }
+          }
+        }
+        CssStyle cellCssStyle = self->cssParser->resolveStyle(name, classAttr);
+        if (!cellStyleAttr.empty()) {
+          CssStyle inlineStyle = CssParser::parseInlineStyle(cellStyleAttr);
+          cellCssStyle.applyOver(inlineStyle);
+        }
+        if (cellCssStyle.hasWidth()) {
+          cellWidthHint = cellCssStyle.width;
+          hasCellWidthHint = true;
+        }
+      }
+
+      // Ensure there's a row to add cells to
+      if (self->tableData->rows.empty()) {
+        self->tableData->rows.push_back(TableRow());
+      }
+
+      // Create a new ParsedText for this cell (characterData will flow into it)
+      auto cellBlockStyle = BlockStyle();
+      cellBlockStyle.alignment = CssTextAlign::Left;
+      cellBlockStyle.textAlignDefined = true;
+      // Explicitly disable paragraph indent for table cells
+      cellBlockStyle.textIndent = 0;
+      cellBlockStyle.textIndentDefined = true;
+      self->currentTextBlock.reset(
+          new ParsedText(self->extraParagraphSpacing, self->hyphenationEnabled, cellBlockStyle));
+      self->nextWordContinues = false;
+
+      // Track the cell
+      auto& currentRow = self->tableData->rows.back();
+      currentRow.cells.push_back(TableCell());
+      currentRow.cells.back().isHeader = isHeader;
+      currentRow.cells.back().colspan = colspan;
+      if (hasCellWidthHint) {
+        currentRow.cells.back().widthHint = cellWidthHint;
+        currentRow.cells.back().hasWidthHint = true;
+      }
+
+      // Apply bold for header cells
+      if (isHeader) {
+        self->boldUntilDepth = std::min(self->boldUntilDepth, self->depth);
+        self->updateEffectiveInlineStyle();
+      }
+
+      self->depth += 1;
+      return;
+    }
+
+    // Transparent table container tags
+    if (matches(name, TABLE_TRANSPARENT_TAGS, NUM_TABLE_TRANSPARENT_TAGS)) {
+      self->depth += 1;
+      return;
+    }
+
+    // Skip colgroup, col, caption
+    if (matches(name, TABLE_SKIP_TAGS, NUM_TABLE_SKIP_TAGS)) {
+      self->skipUntilDepth = self->depth;
+      self->depth += 1;
+      return;
+    }
+
+    // Other tags inside table cells (p, div, span, b, i, etc.) fall through
+    // to the normal handling below. startNewTextBlock is a no-op when inTable.
+  }
+
+  if (matches(name, IMAGE_TAGS, NUM_IMAGE_TAGS)) {
+    std::string src;
+    std::string alt;
+    if (atts != nullptr) {
+      for (int i = 0; atts[i]; i += 2) {
+        if (strcmp(atts[i], "src") == 0) {
+          src = atts[i + 1];
+        } else if (strcmp(atts[i], "alt") == 0) {
+          alt = atts[i + 1];
+        }
+      }
+
+      if (!src.empty()) {
+        LOG_DBG("EHP", "Found image: src=%s", src.c_str());
+
+        {
+          // Resolve the image path relative to the HTML file
+          std::string resolvedPath = FsHelpers::normalisePath(self->contentBase + src);
+
+          // Create a unique filename for the cached image
+          std::string ext;
+          size_t extPos = resolvedPath.rfind('.');
+          if (extPos != std::string::npos) {
+            ext = resolvedPath.substr(extPos);
+          }
+          std::string cachedImagePath = self->imageBasePath + std::to_string(self->imageCounter++) + ext;
+
+          // Extract image to cache file
+          FsFile cachedImageFile;
+          bool extractSuccess = false;
+          if (Storage.openFileForWrite("EHP", cachedImagePath, cachedImageFile)) {
+            extractSuccess = self->epub->readItemContentsToStream(resolvedPath, cachedImageFile, 4096);
+            cachedImageFile.flush();
+            cachedImageFile.close();
+            delay(50);  // Give SD card time to sync
+          }
+
+          if (extractSuccess) {
+            // Get image dimensions
+            ImageDimensions dims = {0, 0};
+            ImageToFramebufferDecoder* decoder = ImageDecoderFactory::getDecoder(cachedImagePath);
+            if (decoder && decoder->getDimensions(cachedImagePath, dims)) {
+              LOG_DBG("EHP", "Image dimensions: %dx%d", dims.width, dims.height);
+
+              // Scale to fit viewport while maintaining aspect ratio
+              int maxWidth = self->viewportWidth;
+              int maxHeight = self->viewportHeight;
+              float scaleX = (dims.width > maxWidth) ? (float)maxWidth / dims.width : 1.0f;
+              float scaleY = (dims.height > maxHeight) ? (float)maxHeight / dims.height : 1.0f;
+              float scale = (scaleX < scaleY) ? scaleX : scaleY;
+              if (scale > 1.0f) scale = 1.0f;
+
+              int displayWidth = (int)(dims.width * scale);
+              int displayHeight = (int)(dims.height * scale);
+
+              LOG_DBG("EHP", "Display size: %dx%d (scale %.2f)", displayWidth, displayHeight, scale);
+
+              // Create page for image - only break if image won't fit remaining space
+              if (self->currentPage && !self->currentPage->elements.empty() &&
+                  (self->currentPageNextY + displayHeight > self->viewportHeight)) {
+                self->completePageFn(std::move(self->currentPage));
+                self->currentPage.reset(new Page());
+                if (!self->currentPage) {
+                  LOG_ERR("EHP", "Failed to create new page");
+                  return;
+                }
+                self->currentPageNextY = 0;
+              } else if (!self->currentPage) {
+                self->currentPage.reset(new Page());
+                if (!self->currentPage) {
+                  LOG_ERR("EHP", "Failed to create initial page");
+                  return;
+                }
+                self->currentPageNextY = 0;
+              }
+
+              // Create ImageBlock and add to page
+              auto imageBlock = std::make_shared<ImageBlock>(cachedImagePath, displayWidth, displayHeight);
+              if (!imageBlock) {
+                LOG_ERR("EHP", "Failed to create ImageBlock");
+                return;
+              }
+              int xPos = (self->viewportWidth - displayWidth) / 2;
+              auto pageImage = std::make_shared<PageImage>(imageBlock, xPos, self->currentPageNextY);
+              if (!pageImage) {
+                LOG_ERR("EHP", "Failed to create PageImage");
+                return;
+              }
+              self->currentPage->elements.push_back(pageImage);
+              self->currentPageNextY += displayHeight;
+
+              self->depth += 1;
+              return;
+            } else {
+              LOG_ERR("EHP", "Failed to get image dimensions");
+              Storage.remove(cachedImagePath.c_str());
+            }
+          } else {
+            LOG_ERR("EHP", "Failed to extract image");
+          }
+        }
+      }
+
+      // Fallback to alt text if image processing fails
+      if (!alt.empty()) {
+        alt = "[Image: " + alt + "]";
+        self->startNewTextBlock(centeredBlockStyle);
+        self->italicUntilDepth = std::min(self->italicUntilDepth, self->depth);
+        self->depth += 1;
+        self->characterData(userData, alt.c_str(), alt.length());
+        // Skip any child content (skip until parent as we pre-advanced depth above)
+        self->skipUntilDepth = self->depth - 1;
+        return;
+      }
+
+      // No alt text, skip
+      self->skipUntilDepth = self->depth;
+      self->depth += 1;
+      return;
+    }
   }
 
   if (matches(name, SKIP_TAGS, NUM_SKIP_TAGS)) {
@@ -359,6 +670,28 @@ void XMLCALL ChapterHtmlSlimParser::characterData(void* userData, const XML_Char
       continue;
     }
 
+    // Detect U+00A0 (non-breaking space): UTF-8 encoding is 0xC2 0xA0
+    // Render a visible space without allowing a line break around it.
+    if (static_cast<uint8_t>(s[i]) == 0xC2 && i + 1 < len && static_cast<uint8_t>(s[i + 1]) == 0xA0) {
+      // Flush any pending text so style is applied correctly.
+      if (self->partWordBufferIndex > 0) {
+        self->flushPartWordBuffer();
+      }
+
+      // Add a standalone space that attaches to the previous word.
+      self->partWordBuffer[0] = ' ';
+      self->partWordBuffer[1] = '\0';
+      self->partWordBufferIndex = 1;
+      self->nextWordContinues = true;  // Attach space to previous word (no break).
+      self->flushPartWordBuffer();
+
+      // Ensure the next real word attaches to this space (no break).
+      self->nextWordContinues = true;
+
+      i++;  // Skip the second byte (0xA0)
+      continue;
+    }
+
     // Skip Zero Width No-Break Space / BOM (U+FEFF) = 0xEF 0xBB 0xBF
     const XML_Char FEFF_BYTE_1 = static_cast<XML_Char>(0xEF);
     const XML_Char FEFF_BYTE_2 = static_cast<XML_Char>(0xBB);
@@ -385,14 +718,31 @@ void XMLCALL ChapterHtmlSlimParser::characterData(void* userData, const XML_Char
   // There should be enough here to build out 1-2 full pages and doing this will free up a lot of
   // memory.
   // Spotted when reading Intermezzo, there are some really long text blocks in there.
-  if (self->currentTextBlock->size() > 750) {
-    Serial.printf("[%lu] [EHP] Text block too long, splitting into multiple pages\n", millis());
+  // Skip this when inside a table - cell content is buffered for later layout.
+  if (!self->inTable && self->currentTextBlock->size() > 750) {
+    LOG_DBG("EHP", "Text block too long, splitting into multiple pages");
     self->currentTextBlock->layoutAndExtractLines(
         self->renderer, self->fontId, self->viewportWidth,
         [self](const std::shared_ptr<TextBlock>& textBlock) { self->addLineToPage(textBlock); }, false);
   }
 }
 
+void XMLCALL ChapterHtmlSlimParser::defaultHandlerExpand(void* userData, const XML_Char* s, const int len) {
+  // Check if this looks like an entity reference (&...;)
+  if (len >= 3 && s[0] == '&' && s[len - 1] == ';') {
+    const char* utf8Value = lookupHtmlEntity(s, len);
+    if (utf8Value != nullptr) {
+      // Known entity: expand to its UTF-8 value
+      characterData(userData, utf8Value, strlen(utf8Value));
+      return;
+    }
+    // Unknown entity: preserve original &...; sequence
+    characterData(userData, s, len);
+    return;
+  }
+  // Not an entity we recognize - skip it
+}
+
 void XMLCALL ChapterHtmlSlimParser::endElement(void* userData, const XML_Char* name) {
   auto* self = static_cast<ChapterHtmlSlimParser*>(userData);
 
@@ -407,15 +757,17 @@ void XMLCALL ChapterHtmlSlimParser::endElement(void* userData, const XML_Char* n
 
   const bool styleWillChange = willPopStyleStack || willClearBold || willClearItalic || willClearUnderline;
   const bool headerOrBlockTag = isHeaderOrBlock(name);
+  const bool isTableCellTag = strcmp(name, "td") == 0 || strcmp(name, "th") == 0;
+  const bool isTableTag = strcmp(name, "table") == 0;
 
   // Flush buffer with current style BEFORE any style changes
   if (self->partWordBufferIndex > 0) {
     // Flush if style will change OR if we're closing a block/structural element
-    const bool isInlineTag = !headerOrBlockTag && strcmp(name, "table") != 0 &&
+    const bool isInlineTag = !headerOrBlockTag && !isTableTag && !isTableCellTag &&
                              !matches(name, IMAGE_TAGS, NUM_IMAGE_TAGS) && self->depth != 1;
     const bool shouldFlush = styleWillChange || headerOrBlockTag || matches(name, BOLD_TAGS, NUM_BOLD_TAGS) ||
                              matches(name, ITALIC_TAGS, NUM_ITALIC_TAGS) ||
-                             matches(name, UNDERLINE_TAGS, NUM_UNDERLINE_TAGS) || strcmp(name, "table") == 0 ||
+                             matches(name, UNDERLINE_TAGS, NUM_UNDERLINE_TAGS) || isTableTag || isTableCellTag ||
                              matches(name, IMAGE_TAGS, NUM_IMAGE_TAGS) || self->depth == 1;
 
     if (shouldFlush) {
@@ -427,6 +779,57 @@ void XMLCALL ChapterHtmlSlimParser::endElement(void* userData, const XML_Char* n
     }
   }
 
+  // --- Table cell/row/table close handling ---
+  if (self->inTable) {
+    if (isTableCellTag) {
+      // Save the current cell content into the table data
+      if (self->tableData && !self->tableData->rows.empty()) {
+        auto& currentRow = self->tableData->rows.back();
+        if (!currentRow.cells.empty()) {
+          currentRow.cells.back().content = std::move(self->currentTextBlock);
+        }
+      }
+
+      // Create a safe empty ParsedText so character data between cells doesn't crash
+      auto safeBlockStyle = BlockStyle();
+      safeBlockStyle.alignment = CssTextAlign::Left;
+      self->currentTextBlock.reset(
+          new ParsedText(self->extraParagraphSpacing, self->hyphenationEnabled, safeBlockStyle));
+      self->nextWordContinues = false;
+    }
+
+    if (isTableTag) {
+      // Process the entire buffered table
+      self->depth -= 1;
+
+      // Clean up style state for this depth
+      if (self->skipUntilDepth == self->depth) self->skipUntilDepth = INT_MAX;
+      if (self->boldUntilDepth == self->depth) self->boldUntilDepth = INT_MAX;
+      if (self->italicUntilDepth == self->depth) self->italicUntilDepth = INT_MAX;
+      if (self->underlineUntilDepth == self->depth) self->underlineUntilDepth = INT_MAX;
+      if (!self->inlineStyleStack.empty() && self->inlineStyleStack.back().depth == self->depth) {
+        self->inlineStyleStack.pop_back();
+        self->updateEffectiveInlineStyle();
+      }
+
+      self->processTable();
+
+      self->inTable = false;
+      self->tableData.reset();
+
+      // Restore a fresh text block for content after the table
+      auto paragraphAlignmentBlockStyle = BlockStyle();
+      paragraphAlignmentBlockStyle.textAlignDefined = true;
+      const auto align = (self->paragraphAlignment == static_cast<uint8_t>(CssTextAlign::None))
+                             ? CssTextAlign::Justify
+                             : static_cast<CssTextAlign>(self->paragraphAlignment);
+      paragraphAlignmentBlockStyle.alignment = align;
+      self->currentTextBlock.reset(
+          new ParsedText(self->extraParagraphSpacing, self->hyphenationEnabled, paragraphAlignmentBlockStyle));
+      return;  // depth already decremented, skip the normal endElement cleanup
+    }
+  }
+
   self->depth -= 1;
 
   // Leaving skip
@@ -477,10 +880,14 @@ bool ChapterHtmlSlimParser::parseAndBuildPages() {
   int done;
 
   if (!parser) {
-    Serial.printf("[%lu] [EHP] Couldn't allocate memory for parser\n", millis());
+    LOG_ERR("EHP", "Couldn't allocate memory for parser");
     return false;
   }
 
+  // Handle HTML entities (like &nbsp;) that aren't in XML spec or DTD
+  // Using DefaultHandlerExpand preserves normal entity expansion from DOCTYPE
+  XML_SetDefaultHandlerExpand(parser, defaultHandlerExpand);
+
   FsFile file;
   if (!Storage.openFileForRead("EHP", filepath, file)) {
     XML_ParserFree(parser);
@@ -499,7 +906,7 @@ bool ChapterHtmlSlimParser::parseAndBuildPages() {
   do {
     void* const buf = XML_GetBuffer(parser, 1024);
     if (!buf) {
-      Serial.printf("[%lu] [EHP] Couldn't allocate memory for buffer\n", millis());
+      LOG_ERR("EHP", "Couldn't allocate memory for buffer");
       XML_StopParser(parser, XML_FALSE);                // Stop any pending processing
       XML_SetElementHandler(parser, nullptr, nullptr);  // Clear callbacks
       XML_SetCharacterDataHandler(parser, nullptr);
@@ -511,7 +918,7 @@ bool ChapterHtmlSlimParser::parseAndBuildPages() {
     const size_t len = file.read(buf, 1024);
 
     if (len == 0 && file.available() > 0) {
-      Serial.printf("[%lu] [EHP] File read error\n", millis());
+      LOG_ERR("EHP", "File read error");
       XML_StopParser(parser, XML_FALSE);                // Stop any pending processing
       XML_SetElementHandler(parser, nullptr, nullptr);  // Clear callbacks
       XML_SetCharacterDataHandler(parser, nullptr);
@@ -523,8 +930,8 @@ bool ChapterHtmlSlimParser::parseAndBuildPages() {
     done = file.available() == 0;
 
     if (XML_ParseBuffer(parser, static_cast<int>(len), done) == XML_STATUS_ERROR) {
-      Serial.printf("[%lu] [EHP] Parse error at line %lu:\n%s\n", millis(), XML_GetCurrentLineNumber(parser),
-                    XML_ErrorString(XML_GetErrorCode(parser)));
+      LOG_ERR("EHP", "Parse error at line %lu:\n%s", XML_GetCurrentLineNumber(parser),
+              XML_ErrorString(XML_GetErrorCode(parser)));
       XML_StopParser(parser, XML_FALSE);                // Stop any pending processing
       XML_SetElementHandler(parser, nullptr, nullptr);  // Clear callbacks
       XML_SetCharacterDataHandler(parser, nullptr);
@@ -568,7 +975,7 @@ void ChapterHtmlSlimParser::addLineToPage(std::shared_ptr<TextBlock> line) {
 
 void ChapterHtmlSlimParser::makePages() {
   if (!currentTextBlock) {
-    Serial.printf("[%lu] [EHP] !! No text block to make pages for !!\n", millis());
+    LOG_ERR("EHP", "!! No text block to make pages for !!");
     return;
   }
 
@@ -610,3 +1017,335 @@ void ChapterHtmlSlimParser::makePages() {
     currentPageNextY += lineHeight / 2;
   }
 }
+
+// ---------------------------------------------------------------------------
+// Table processing
+// ---------------------------------------------------------------------------
+
+// Cell padding in pixels (horizontal space between grid line and cell text)
+static constexpr int TABLE_CELL_PAD_X = 4;
+// Vertical cell padding — asymmetric because font metrics include internal leading (whitespace
+// above glyphs), so the top already has built-in visual space. Less explicit padding on top,
+// more on bottom, produces visually balanced results.
+static constexpr int TABLE_CELL_PAD_TOP = 1;
+static constexpr int TABLE_CELL_PAD_BOTTOM = 3;
+// Minimum usable column width in pixels (below this text is unreadable)
+static constexpr int TABLE_MIN_COL_WIDTH = 30;
+// Grid line width in pixels
+static constexpr int TABLE_GRID_LINE_PX = 1;
+
+void ChapterHtmlSlimParser::addTableRowToPage(std::shared_ptr<PageTableRow> row) {
+  if (!currentPage) {
+    currentPage.reset(new Page());
+    currentPageNextY = 0;
+  }
+
+  const int16_t rowH = row->getHeight();
+
+  // If this row doesn't fit on the current page, start a new one
+  if (currentPageNextY + rowH > viewportHeight) {
+    completePageFn(std::move(currentPage));
+    currentPage.reset(new Page());
+    currentPageNextY = 0;
+  }
+
+  row->xPos = 0;
+  row->yPos = currentPageNextY;
+  currentPage->elements.push_back(std::move(row));
+  currentPageNextY += rowH;
+}
+
+void ChapterHtmlSlimParser::processTable() {
+  if (!tableData || tableData->rows.empty()) {
+    return;
+  }
+
+  if (!currentPage) {
+    currentPage.reset(new Page());
+    currentPageNextY = 0;
+  }
+
+  const int lh = static_cast<int>(renderer.getLineHeight(fontId) * lineCompression);
+
+  // 1. Determine logical column count using colspan.
+  //    Each cell occupies cell.colspan logical columns. The total for a row is the sum of colspans.
+  size_t numCols = 0;
+  for (const auto& row : tableData->rows) {
+    size_t rowLogicalCols = 0;
+    for (const auto& cell : row.cells) {
+      rowLogicalCols += static_cast<size_t>(cell.colspan);
+    }
+    numCols = std::max(numCols, rowLogicalCols);
+  }
+
+  if (numCols == 0) {
+    return;
+  }
+
+  // 2. Measure natural width of each cell and compute per-column max natural width.
+  //    Only non-spanning cells (colspan==1) contribute to individual column widths.
+  //    Spanning cells use the combined width of their spanned columns.
+  std::vector<uint16_t> colNaturalWidth(numCols, 0);
+
+  for (const auto& row : tableData->rows) {
+    size_t logicalCol = 0;
+    for (const auto& cell : row.cells) {
+      if (cell.colspan == 1 && cell.content && !cell.content->isEmpty()) {
+        if (logicalCol < numCols) {
+          const uint16_t w = cell.content->getNaturalWidth(renderer, fontId);
+          if (w > colNaturalWidth[logicalCol]) {
+            colNaturalWidth[logicalCol] = w;
+          }
+        }
+      }
+      logicalCol += static_cast<size_t>(cell.colspan);
+    }
+  }
+
+  // 3. Calculate column widths to fit viewport.
+  //    Available width = viewport - outer borders - internal column borders - cell padding
+  const int totalGridLines = static_cast<int>(numCols) + 1;  // left + between columns + right
+  const int totalPadding = static_cast<int>(numCols) * TABLE_CELL_PAD_X * 2;
+  const int availableForContent = viewportWidth - totalGridLines * TABLE_GRID_LINE_PX - totalPadding;
+
+  // 3a. Resolve width hints per column.
+  //     Priority: <col> hints > max cell hint (colspan=1 only).
+  //     Percentages are relative to availableForContent.
+  const float emSize = static_cast<float>(lh);
+  const float containerW = static_cast<float>(std::max(availableForContent, 0));
+
+  std::vector<int> colHintedWidth(numCols, -1);  // -1 = no hint
+
+  // From <col> tags
+  for (size_t c = 0; c < numCols && c < tableData->colWidthHints.size(); ++c) {
+    const auto& hint = tableData->colWidthHints[c];
+    if (hint.value > 0) {
+      int px = static_cast<int>(hint.toPixels(emSize, containerW));
+      if (px > 0) {
+        colHintedWidth[c] = std::max(px, TABLE_MIN_COL_WIDTH);
+      }
+    }
+  }
+
+  // From <td>/<th> cell width hints (only override if no <col> hint exists for this column)
+  for (const auto& row : tableData->rows) {
+    size_t logicalCol = 0;
+    for (const auto& cell : row.cells) {
+      if (cell.colspan == 1 && cell.hasWidthHint && logicalCol < numCols) {
+        if (colHintedWidth[logicalCol] < 0) {  // no <col> hint yet
+          int px = static_cast<int>(cell.widthHint.toPixels(emSize, containerW));
+          if (px > colHintedWidth[logicalCol]) {
+            colHintedWidth[logicalCol] = std::max(px, TABLE_MIN_COL_WIDTH);
+          }
+        }
+      }
+      logicalCol += static_cast<size_t>(cell.colspan);
+    }
+  }
+
+  // 3b. Distribute column widths: hinted columns get their hint, unhinted use auto-sizing.
+  std::vector<uint16_t> colWidths(numCols, 0);
+
+  if (availableForContent <= 0) {
+    const uint16_t equalWidth = static_cast<uint16_t>(viewportWidth / numCols);
+    for (size_t c = 0; c < numCols; ++c) {
+      colWidths[c] = equalWidth;
+    }
+  } else {
+    // First, assign hinted columns and track how much space they consume
+    int hintedSpaceUsed = 0;
+    size_t unhintedCount = 0;
+    for (size_t c = 0; c < numCols; ++c) {
+      if (colHintedWidth[c] > 0) {
+        hintedSpaceUsed += colHintedWidth[c];
+      } else {
+        unhintedCount++;
+      }
+    }
+
+    // If hinted columns exceed available space, scale them down proportionally
+    if (hintedSpaceUsed > availableForContent && hintedSpaceUsed > 0) {
+      for (size_t c = 0; c < numCols; ++c) {
+        if (colHintedWidth[c] > 0) {
+          colHintedWidth[c] = colHintedWidth[c] * availableForContent / hintedSpaceUsed;
+          colHintedWidth[c] = std::max(colHintedWidth[c], TABLE_MIN_COL_WIDTH);
+        }
+      }
+      // Recalculate
+      hintedSpaceUsed = 0;
+      for (size_t c = 0; c < numCols; ++c) {
+        if (colHintedWidth[c] > 0) {
+          hintedSpaceUsed += colHintedWidth[c];
+        }
+      }
+    }
+
+    // Assign hinted columns
+    for (size_t c = 0; c < numCols; ++c) {
+      if (colHintedWidth[c] > 0) {
+        colWidths[c] = static_cast<uint16_t>(colHintedWidth[c]);
+      }
+    }
+
+    // Distribute remaining space among unhinted columns using the existing algorithm
+    const int remainingForUnhinted = std::max(availableForContent - hintedSpaceUsed, 0);
+
+    if (unhintedCount > 0 && remainingForUnhinted > 0) {
+      // Compute total natural width of unhinted columns
+      int totalNaturalUnhinted = 0;
+      for (size_t c = 0; c < numCols; ++c) {
+        if (colHintedWidth[c] <= 0) {
+          totalNaturalUnhinted += colNaturalWidth[c];
+        }
+      }
+
+      if (totalNaturalUnhinted <= remainingForUnhinted) {
+        // All unhinted content fits — distribute extra space equally among unhinted columns
+        const int extraSpace = remainingForUnhinted - totalNaturalUnhinted;
+        const int perColExtra = extraSpace / static_cast<int>(unhintedCount);
+        for (size_t c = 0; c < numCols; ++c) {
+          if (colHintedWidth[c] <= 0) {
+            colWidths[c] = static_cast<uint16_t>(colNaturalWidth[c] + perColExtra);
+          }
+        }
+      } else {
+        // Unhinted content exceeds remaining space — two-pass fair-share among unhinted columns
+        const int equalShare = remainingForUnhinted / static_cast<int>(unhintedCount);
+
+        int spaceUsedByFitting = 0;
+        int naturalOfWide = 0;
+        size_t wideCount = 0;
+
+        for (size_t c = 0; c < numCols; ++c) {
+          if (colHintedWidth[c] <= 0) {
+            if (static_cast<int>(colNaturalWidth[c]) <= equalShare) {
+              colWidths[c] = colNaturalWidth[c];
+              spaceUsedByFitting += colNaturalWidth[c];
+            } else {
+              naturalOfWide += colNaturalWidth[c];
+              wideCount++;
+            }
+          }
+        }
+
+        const int wideSpace = remainingForUnhinted - spaceUsedByFitting;
+        for (size_t c = 0; c < numCols; ++c) {
+          if (colHintedWidth[c] <= 0 && static_cast<int>(colNaturalWidth[c]) > equalShare) {
+            if (naturalOfWide > 0 && wideCount > 1) {
+              int proportional = static_cast<int>(colNaturalWidth[c]) * wideSpace / naturalOfWide;
+              colWidths[c] = static_cast<uint16_t>(std::max(proportional, TABLE_MIN_COL_WIDTH));
+            } else {
+              colWidths[c] = static_cast<uint16_t>(std::max(wideSpace, TABLE_MIN_COL_WIDTH));
+            }
+          }
+        }
+      }
+    } else if (unhintedCount > 0) {
+      // No remaining space for unhinted columns — give them minimum width
+      for (size_t c = 0; c < numCols; ++c) {
+        if (colHintedWidth[c] <= 0) {
+          colWidths[c] = static_cast<uint16_t>(TABLE_MIN_COL_WIDTH);
+        }
+      }
+    }
+  }
+
+  // Compute column x-offsets (cumulative: border + padding + content width + padding + border ...)
+  std::vector<uint16_t> colXOffsets(numCols, 0);
+  int xAccum = TABLE_GRID_LINE_PX;  // start after left border
+  for (size_t c = 0; c < numCols; ++c) {
+    colXOffsets[c] = static_cast<uint16_t>(xAccum);
+    xAccum += TABLE_CELL_PAD_X + colWidths[c] + TABLE_CELL_PAD_X + TABLE_GRID_LINE_PX;
+  }
+  const int16_t totalTableWidth = static_cast<int16_t>(xAccum);
+
+  // Helper: compute the combined content width for a cell spanning multiple columns.
+  // This includes the content widths plus the internal grid lines and padding between spanned columns.
+  auto spanContentWidth = [&](size_t startCol, int colspan) -> uint16_t {
+    int width = 0;
+    for (int s = 0; s < colspan && startCol + s < numCols; ++s) {
+      width += colWidths[startCol + s];
+      if (s > 0) {
+        // Add internal padding and grid line between spanned columns
+        width += TABLE_CELL_PAD_X * 2 + TABLE_GRID_LINE_PX;
+      }
+    }
+    return static_cast<uint16_t>(std::max(width, 0));
+  };
+
+  // Helper: compute the full cell width (including padding on both sides) for a spanning cell.
+  auto spanFullCellWidth = [&](size_t startCol, int colspan) -> uint16_t {
+    if (colspan <= 0 || startCol >= numCols) return 0;
+    const size_t endCol = std::min(startCol + static_cast<size_t>(colspan), numCols) - 1;
+    // From the left edge of startCol's cell to the right edge of endCol's cell
+    const int leftEdge = colXOffsets[startCol];
+    const int rightEdge = colXOffsets[endCol] + TABLE_CELL_PAD_X + colWidths[endCol] + TABLE_CELL_PAD_X;
+    return static_cast<uint16_t>(rightEdge - leftEdge);
+  };
+
+  // 4. Lay out each row: map cells to logical columns, create PageTableRow
+  for (auto& row : tableData->rows) {
+    // Build cell data for this row, one entry per CELL (not per logical column).
+    // Each PageTableCellData gets the correct x-offset and combined column width.
+    std::vector<PageTableCellData> cellDataVec;
+    size_t maxLinesInRow = 1;
+    size_t logicalCol = 0;
+
+    for (size_t ci = 0; ci < row.cells.size() && logicalCol < numCols; ++ci) {
+      auto& cell = row.cells[ci];
+      const int cs = cell.colspan;
+
+      PageTableCellData cellData;
+      cellData.xOffset = colXOffsets[logicalCol];
+      cellData.columnWidth = spanFullCellWidth(logicalCol, cs);
+
+      if (cell.content && !cell.content->isEmpty()) {
+        // Center-align cells that span the full table width (common for section headers/titles)
+        if (cs >= static_cast<int>(numCols)) {
+          BlockStyle centeredStyle = cell.content->getBlockStyle();
+          centeredStyle.alignment = CssTextAlign::Center;
+          centeredStyle.textAlignDefined = true;
+          cell.content->setBlockStyle(centeredStyle);
+        }
+
+        const uint16_t contentWidth = spanContentWidth(logicalCol, cs);
+        std::vector<std::shared_ptr<TextBlock>> cellLines;
+
+        cell.content->layoutAndExtractLines(
+            renderer, fontId, contentWidth,
+            [&cellLines](const std::shared_ptr<TextBlock>& textBlock) { cellLines.push_back(textBlock); });
+
+        if (cellLines.size() > maxLinesInRow) {
+          maxLinesInRow = cellLines.size();
+        }
+        cellData.lines = std::move(cellLines);
+      }
+
+      cellDataVec.push_back(std::move(cellData));
+      logicalCol += static_cast<size_t>(cs);
+    }
+
+    // Fill remaining logical columns with empty cells (rows shorter than numCols)
+    while (logicalCol < numCols) {
+      PageTableCellData emptyCell;
+      emptyCell.xOffset = colXOffsets[logicalCol];
+      emptyCell.columnWidth = static_cast<uint16_t>(TABLE_CELL_PAD_X + colWidths[logicalCol] + TABLE_CELL_PAD_X);
+      cellDataVec.push_back(std::move(emptyCell));
+      logicalCol++;
+    }
+
+    // Row height = max lines * lineHeight + top/bottom border + asymmetric vertical padding
+    const int16_t rowHeight = static_cast<int16_t>(
+        static_cast<int>(maxLinesInRow) * lh + 2 + TABLE_CELL_PAD_TOP + TABLE_CELL_PAD_BOTTOM);
+
+    auto pageTableRow = std::make_shared<PageTableRow>(
+        std::move(cellDataVec), rowHeight, totalTableWidth, static_cast<int16_t>(lh), 0, 0);
+
+    addTableRowToPage(std::move(pageTableRow));
+  }
+
+  // Add a small gap after the table
+  if (extraParagraphSpacing) {
+    currentPageNextY += lh / 2;
+  }
+}

lib/Epub/Epub/parsers/ChapterHtmlSlimParser.h

@@ -7,16 +7,21 @@
 #include <memory>
 
 #include "../ParsedText.h"
+#include "../TableData.h"
+#include "../blocks/ImageBlock.h"
 #include "../blocks/TextBlock.h"
 #include "../css/CssParser.h"
 #include "../css/CssStyle.h"
 
 class Page;
+class PageTableRow;
 class GfxRenderer;
+class Epub;
 
 #define MAX_WORD_SIZE 200
 
 class ChapterHtmlSlimParser {
+  std::shared_ptr<Epub> epub;
   const std::string& filepath;
   GfxRenderer& renderer;
   std::function<void(std::unique_ptr<Page>)> completePageFn;
@@ -43,6 +48,9 @@ class ChapterHtmlSlimParser {
   bool hyphenationEnabled;
   const CssParser* cssParser;
   bool embeddedStyle;
+  std::string contentBase;
+  std::string imageBasePath;
+  int imageCounter = 0;
 
   // Style tracking (replaces depth-based approach)
   struct StyleStackEntry {
@@ -57,25 +65,34 @@ class ChapterHtmlSlimParser {
   bool effectiveItalic = false;
   bool effectiveUnderline = false;
 
+  // Table buffering state
+  bool inTable = false;
+  std::unique_ptr<TableData> tableData;
+
   void updateEffectiveInlineStyle();
   void startNewTextBlock(const BlockStyle& blockStyle);
   void flushPartWordBuffer();
   void makePages();
+  void processTable();
+  void addTableRowToPage(std::shared_ptr<PageTableRow> row);
   // XML callbacks
   static void XMLCALL startElement(void* userData, const XML_Char* name, const XML_Char** atts);
   static void XMLCALL characterData(void* userData, const XML_Char* s, int len);
+  static void XMLCALL defaultHandlerExpand(void* userData, const XML_Char* s, int len);
   static void XMLCALL endElement(void* userData, const XML_Char* name);
 
  public:
-  explicit ChapterHtmlSlimParser(const std::string& filepath, GfxRenderer& renderer, const int fontId,
-                                 const float lineCompression, const bool extraParagraphSpacing,
+  explicit ChapterHtmlSlimParser(std::shared_ptr<Epub> epub, const std::string& filepath, GfxRenderer& renderer,
+                                 const int fontId, const float lineCompression, const bool extraParagraphSpacing,
                                  const uint8_t paragraphAlignment, const uint16_t viewportWidth,
                                  const uint16_t viewportHeight, const bool hyphenationEnabled,
                                  const std::function<void(std::unique_ptr<Page>)>& completePageFn,
-                                 const bool embeddedStyle, const std::function<void()>& popupFn = nullptr,
+                                 const bool embeddedStyle, const std::string& contentBase,
+                                 const std::string& imageBasePath, const std::function<void()>& popupFn = nullptr,
                                  const CssParser* cssParser = nullptr)
 
-      : filepath(filepath),
+      : epub(epub),
+        filepath(filepath),
         renderer(renderer),
         fontId(fontId),
         lineCompression(lineCompression),
@@ -87,7 +104,9 @@ class ChapterHtmlSlimParser {
         completePageFn(completePageFn),
         popupFn(popupFn),
         cssParser(cssParser),
-        embeddedStyle(embeddedStyle) {}
+        embeddedStyle(embeddedStyle),
+        contentBase(contentBase),
+        imageBasePath(imageBasePath) {}
 
   ~ChapterHtmlSlimParser() = default;
   bool parseAndBuildPages();

lib/Epub/Epub/parsers/ContainerParser.cpp

@@ -1,11 +1,11 @@
 #include "ContainerParser.h"
 
-#include <HardwareSerial.h>
+#include <Logging.h>
 
 bool ContainerParser::setup() {
   parser = XML_ParserCreate(nullptr);
   if (!parser) {
-    Serial.printf("[%lu] [CTR] Couldn't allocate memory for parser\n", millis());
+    LOG_ERR("CTR", "Couldn't allocate memory for parser");
     return false;
   }
 
@@ -34,7 +34,7 @@ size_t ContainerParser::write(const uint8_t* buffer, const size_t size) {
   while (remainingInBuffer > 0) {
     void* const buf = XML_GetBuffer(parser, 1024);
     if (!buf) {
-      Serial.printf("[%lu] [CTR] Couldn't allocate buffer\n", millis());
+      LOG_DBG("CTR", "Couldn't allocate buffer");
       return 0;
     }
 
@@ -42,7 +42,7 @@ size_t ContainerParser::write(const uint8_t* buffer, const size_t size) {
     memcpy(buf, currentBufferPos, toRead);
 
     if (XML_ParseBuffer(parser, static_cast<int>(toRead), remainingSize == toRead) == XML_STATUS_ERROR) {
-      Serial.printf("[%lu] [CTR] Parse error: %s\n", millis(), XML_ErrorString(XML_GetErrorCode(parser)));
+      LOG_ERR("CTR", "Parse error: %s", XML_ErrorString(XML_GetErrorCode(parser)));
       return 0;
     }
 

lib/Epub/Epub/parsers/ContentOpfParser.cpp

@@ -1,7 +1,7 @@
 #include "ContentOpfParser.h"
 
 #include <FsHelpers.h>
-#include <HardwareSerial.h>
+#include <Logging.h>
 #include <Serialization.h>
 
 #include "../BookMetadataCache.h"
@@ -15,7 +15,7 @@ constexpr char itemCacheFile[] = "/.items.bin";
 bool ContentOpfParser::setup() {
   parser = XML_ParserCreate(nullptr);
   if (!parser) {
-    Serial.printf("[%lu] [COF] Couldn't allocate memory for parser\n", millis());
+    LOG_DBG("COF", "Couldn't allocate memory for parser");
     return false;
   }
 
@@ -56,7 +56,7 @@ size_t ContentOpfParser::write(const uint8_t* buffer, const size_t size) {
     void* const buf = XML_GetBuffer(parser, 1024);
 
     if (!buf) {
-      Serial.printf("[%lu] [COF] Couldn't allocate memory for buffer\n", millis());
+      LOG_ERR("COF", "Couldn't allocate memory for buffer");
       XML_StopParser(parser, XML_FALSE);                // Stop any pending processing
       XML_SetElementHandler(parser, nullptr, nullptr);  // Clear callbacks
       XML_SetCharacterDataHandler(parser, nullptr);
@@ -69,8 +69,8 @@ size_t ContentOpfParser::write(const uint8_t* buffer, const size_t size) {
     memcpy(buf, currentBufferPos, toRead);
 
     if (XML_ParseBuffer(parser, static_cast<int>(toRead), remainingSize == toRead) == XML_STATUS_ERROR) {
-      Serial.printf("[%lu] [COF] Parse error at line %lu: %s\n", millis(), XML_GetCurrentLineNumber(parser),
-                    XML_ErrorString(XML_GetErrorCode(parser)));
+      LOG_DBG("COF", "Parse error at line %lu: %s", XML_GetCurrentLineNumber(parser),
+              XML_ErrorString(XML_GetErrorCode(parser)));
       XML_StopParser(parser, XML_FALSE);                // Stop any pending processing
       XML_SetElementHandler(parser, nullptr, nullptr);  // Clear callbacks
       XML_SetCharacterDataHandler(parser, nullptr);
@@ -119,9 +119,7 @@ void XMLCALL ContentOpfParser::startElement(void* userData, const XML_Char* name
   if (self->state == IN_PACKAGE && (strcmp(name, "manifest") == 0 || strcmp(name, "opf:manifest") == 0)) {
     self->state = IN_MANIFEST;
     if (!Storage.openFileForWrite("COF", self->cachePath + itemCacheFile, self->tempItemStore)) {
-      Serial.printf(
-          "[%lu] [COF] Couldn't open temp items file for writing. This is probably going to be a fatal error.\n",
-          millis());
+      LOG_ERR("COF", "Couldn't open temp items file for writing. This is probably going to be a fatal error.");
     }
     return;
   }
@@ -129,9 +127,7 @@ void XMLCALL ContentOpfParser::startElement(void* userData, const XML_Char* name
   if (self->state == IN_PACKAGE && (strcmp(name, "spine") == 0 || strcmp(name, "opf:spine") == 0)) {
     self->state = IN_SPINE;
     if (!Storage.openFileForRead("COF", self->cachePath + itemCacheFile, self->tempItemStore)) {
-      Serial.printf(
-          "[%lu] [COF] Couldn't open temp items file for reading. This is probably going to be a fatal error.\n",
-          millis());
+      LOG_ERR("COF", "Couldn't open temp items file for reading. This is probably going to be a fatal error.");
     }
 
     // Sort item index for binary search if we have enough items
@@ -140,7 +136,7 @@ void XMLCALL ContentOpfParser::startElement(void* userData, const XML_Char* name
         return a.idHash < b.idHash || (a.idHash == b.idHash && a.idLen < b.idLen);
       });
       self->useItemIndex = true;
-      Serial.printf("[%lu] [COF] Using fast index for %zu manifest items\n", millis(), self->itemIndex.size());
+      LOG_DBG("COF", "Using fast index for %zu manifest items", self->itemIndex.size());
     }
     return;
   }
@@ -148,11 +144,9 @@ void XMLCALL ContentOpfParser::startElement(void* userData, const XML_Char* name
   if (self->state == IN_PACKAGE && (strcmp(name, "guide") == 0 || strcmp(name, "opf:guide") == 0)) {
     self->state = IN_GUIDE;
     // TODO Remove print
-    Serial.printf("[%lu] [COF] Entering guide state.\n", millis());
+    LOG_DBG("COF", "Entering guide state.");
     if (!Storage.openFileForRead("COF", self->cachePath + itemCacheFile, self->tempItemStore)) {
-      Serial.printf(
-          "[%lu] [COF] Couldn't open temp items file for reading. This is probably going to be a fatal error.\n",
-          millis());
+      LOG_ERR("COF", "Couldn't open temp items file for reading. This is probably going to be a fatal error.");
     }
     return;
   }
@@ -214,8 +208,7 @@ void XMLCALL ContentOpfParser::startElement(void* userData, const XML_Char* name
       if (self->tocNcxPath.empty()) {
         self->tocNcxPath = href;
       } else {
-        Serial.printf("[%lu] [COF] Warning: Multiple NCX files found in manifest. Ignoring duplicate: %s\n", millis(),
-                      href.c_str());
+        LOG_DBG("COF", "Warning: Multiple NCX files found in manifest. Ignoring duplicate: %s", href.c_str());
       }
     }
 
@@ -229,7 +222,7 @@ void XMLCALL ContentOpfParser::startElement(void* userData, const XML_Char* name
       // Properties is space-separated, check if "nav" is present as a word
       if (properties == "nav" || properties.find("nav ") == 0 || properties.find(" nav") != std::string::npos) {
         self->tocNavPath = href;
-        Serial.printf("[%lu] [COF] Found EPUB 3 nav document: %s\n", millis(), href.c_str());
+        LOG_DBG("COF", "Found EPUB 3 nav document: %s", href.c_str());
       }
     }
 
@@ -310,7 +303,7 @@ void XMLCALL ContentOpfParser::startElement(void* userData, const XML_Char* name
         if (type == "text" || type == "start") {
           continue;
         } else {
-          Serial.printf("[%lu] [COF] Skipping non-text reference in guide: %s\n", millis(), type.c_str());
+          LOG_DBG("COF", "Skipping non-text reference in guide: %s", type.c_str());
           break;
         }
       } else if (strcmp(atts[i], "href") == 0) {
@@ -318,7 +311,7 @@ void XMLCALL ContentOpfParser::startElement(void* userData, const XML_Char* name
       }
     }
     if ((type == "text" || (type == "start" && !self->textReferenceHref.empty())) && (textHref.length() > 0)) {
-      Serial.printf("[%lu] [COF] Found %s reference in guide: %s.\n", millis(), type.c_str(), textHref.c_str());
+      LOG_DBG("COF", "Found %s reference in guide: %s.", type.c_str(), textHref.c_str());
       self->textReferenceHref = textHref;
     }
     return;

lib/Epub/Epub/parsers/TocNavParser.cpp

@@ -1,14 +1,14 @@
 #include "TocNavParser.h"
 
 #include <FsHelpers.h>
-#include <HardwareSerial.h>
+#include <Logging.h>
 
 #include "../BookMetadataCache.h"
 
 bool TocNavParser::setup() {
   parser = XML_ParserCreate(nullptr);
   if (!parser) {
-    Serial.printf("[%lu] [NAV] Couldn't allocate memory for parser\n", millis());
+    LOG_DBG("NAV", "Couldn't allocate memory for parser");
     return false;
   }
 
@@ -39,7 +39,7 @@ size_t TocNavParser::write(const uint8_t* buffer, const size_t size) {
   while (remainingInBuffer > 0) {
     void* const buf = XML_GetBuffer(parser, 1024);
     if (!buf) {
-      Serial.printf("[%lu] [NAV] Couldn't allocate memory for buffer\n", millis());
+      LOG_DBG("NAV", "Couldn't allocate memory for buffer");
       XML_StopParser(parser, XML_FALSE);
       XML_SetElementHandler(parser, nullptr, nullptr);
       XML_SetCharacterDataHandler(parser, nullptr);
@@ -52,8 +52,8 @@ size_t TocNavParser::write(const uint8_t* buffer, const size_t size) {
     memcpy(buf, currentBufferPos, toRead);
 
     if (XML_ParseBuffer(parser, static_cast<int>(toRead), remainingSize == toRead) == XML_STATUS_ERROR) {
-      Serial.printf("[%lu] [NAV] Parse error at line %lu: %s\n", millis(), XML_GetCurrentLineNumber(parser),
-                    XML_ErrorString(XML_GetErrorCode(parser)));
+      LOG_DBG("NAV", "Parse error at line %lu: %s", XML_GetCurrentLineNumber(parser),
+              XML_ErrorString(XML_GetErrorCode(parser)));
       XML_StopParser(parser, XML_FALSE);
       XML_SetElementHandler(parser, nullptr, nullptr);
       XML_SetCharacterDataHandler(parser, nullptr);
@@ -88,7 +88,7 @@ void XMLCALL TocNavParser::startElement(void* userData, const XML_Char* name, co
     for (int i = 0; atts[i]; i += 2) {
       if ((strcmp(atts[i], "epub:type") == 0 || strcmp(atts[i], "type") == 0) && strcmp(atts[i + 1], "toc") == 0) {
         self->state = IN_NAV_TOC;
-        Serial.printf("[%lu] [NAV] Found nav toc element\n", millis());
+        LOG_DBG("NAV", "Found nav toc element");
         return;
       }
     }
@@ -179,7 +179,7 @@ void XMLCALL TocNavParser::endElement(void* userData, const XML_Char* name) {
 
   if (strcmp(name, "nav") == 0 && self->state >= IN_NAV_TOC) {
     self->state = IN_BODY;
-    Serial.printf("[%lu] [NAV] Finished parsing nav toc\n", millis());
+    LOG_DBG("NAV", "Finished parsing nav toc");
     return;
   }
 }

lib/Epub/Epub/parsers/TocNcxParser.cpp

@@ -1,14 +1,14 @@
 #include "TocNcxParser.h"
 
 #include <FsHelpers.h>
-#include <HardwareSerial.h>
+#include <Logging.h>
 
 #include "../BookMetadataCache.h"
 
 bool TocNcxParser::setup() {
   parser = XML_ParserCreate(nullptr);
   if (!parser) {
-    Serial.printf("[%lu] [TOC] Couldn't allocate memory for parser\n", millis());
+    LOG_DBG("TOC", "Couldn't allocate memory for parser");
     return false;
   }
 
@@ -39,7 +39,7 @@ size_t TocNcxParser::write(const uint8_t* buffer, const size_t size) {
   while (remainingInBuffer > 0) {
     void* const buf = XML_GetBuffer(parser, 1024);
     if (!buf) {
-      Serial.printf("[%lu] [TOC] Couldn't allocate memory for buffer\n", millis());
+      LOG_DBG("TOC", "Couldn't allocate memory for buffer");
       XML_StopParser(parser, XML_FALSE);                // Stop any pending processing
       XML_SetElementHandler(parser, nullptr, nullptr);  // Clear callbacks
       XML_SetCharacterDataHandler(parser, nullptr);
@@ -52,8 +52,8 @@ size_t TocNcxParser::write(const uint8_t* buffer, const size_t size) {
     memcpy(buf, currentBufferPos, toRead);
 
     if (XML_ParseBuffer(parser, static_cast<int>(toRead), remainingSize == toRead) == XML_STATUS_ERROR) {
-      Serial.printf("[%lu] [TOC] Parse error at line %lu: %s\n", millis(), XML_GetCurrentLineNumber(parser),
-                    XML_ErrorString(XML_GetErrorCode(parser)));
+      LOG_DBG("TOC", "Parse error at line %lu: %s", XML_GetCurrentLineNumber(parser),
+              XML_ErrorString(XML_GetErrorCode(parser)));
       XML_StopParser(parser, XML_FALSE);                // Stop any pending processing
       XML_SetElementHandler(parser, nullptr, nullptr);  // Clear callbacks
       XML_SetCharacterDataHandler(parser, nullptr);

lib/GfxRenderer/GfxRenderer.cpp

@@ -1,11 +1,12 @@
 #include "GfxRenderer.h"
 
+#include <Logging.h>
 #include <Utf8.h>
 
 void GfxRenderer::begin() {
   frameBuffer = display.getFrameBuffer();
   if (!frameBuffer) {
-    Serial.printf("[%lu] [GFX] !! No framebuffer\n", millis());
+    LOG_ERR("GFX", "!! No framebuffer");
     assert(false);
   }
 }
@@ -57,7 +58,7 @@ void GfxRenderer::drawPixel(const int x, const int y, const bool state) const {
 
   // Bounds checking against physical panel dimensions
   if (phyX < 0 || phyX >= HalDisplay::DISPLAY_WIDTH || phyY < 0 || phyY >= HalDisplay::DISPLAY_HEIGHT) {
-    Serial.printf("[%lu] [GFX] !! Outside range (%d, %d) -> (%d, %d)\n", millis(), x, y, phyX, phyY);
+    LOG_ERR("GFX", "!! Outside range (%d, %d) -> (%d, %d)", x, y, phyX, phyY);
     return;
   }
 
@@ -84,7 +85,7 @@ void GfxRenderer::drawPixelGray(const int x, const int y, const uint8_t val2bit)
 
 int GfxRenderer::getTextWidth(const int fontId, const char* text, const EpdFontFamily::Style style) const {
   if (fontMap.count(fontId) == 0) {
-    Serial.printf("[%lu] [GFX] Font %d not found\n", millis(), fontId);
+    LOG_ERR("GFX", "Font %d not found", fontId);
     return 0;
   }
 
@@ -110,7 +111,7 @@ void GfxRenderer::drawText(const int fontId, const int x, const int y, const cha
   }
 
   if (fontMap.count(fontId) == 0) {
-    Serial.printf("[%lu] [GFX] Font %d not found\n", millis(), fontId);
+    LOG_ERR("GFX", "Font %d not found", fontId);
     return;
   }
   const auto font = fontMap.at(fontId);
@@ -143,7 +144,7 @@ void GfxRenderer::drawLine(int x1, int y1, int x2, int y2, const bool state) con
     }
   } else {
     // TODO: Implement
-    Serial.printf("[%lu] [GFX] Line drawing not supported\n", millis());
+    LOG_ERR("GFX", "Line drawing not supported");
   }
 }
 
@@ -429,8 +430,8 @@ void GfxRenderer::drawBitmap(const Bitmap& bitmap, const int x, const int y, con
   bool isScaled = false;
   int cropPixX = std::floor(bitmap.getWidth() * cropX / 2.0f);
   int cropPixY = std::floor(bitmap.getHeight() * cropY / 2.0f);
-  Serial.printf("[%lu] [GFX] Cropping %dx%d by %dx%d pix, is %s\n", millis(), bitmap.getWidth(), bitmap.getHeight(),
-                cropPixX, cropPixY, bitmap.isTopDown() ? "top-down" : "bottom-up");
+  LOG_DBG("GFX", "Cropping %dx%d by %dx%d pix, is %s", bitmap.getWidth(), bitmap.getHeight(), cropPixX, cropPixY,
+          bitmap.isTopDown() ? "top-down" : "bottom-up");
 
   const float effectiveWidth = (1.0f - cropX) * bitmap.getWidth();
   const float effectiveHeight = (1.0f - cropY) * bitmap.getHeight();
@@ -448,7 +449,7 @@ void GfxRenderer::drawBitmap(const Bitmap& bitmap, const int x, const int y, con
     scale = static_cast<float>(maxHeight) / effectiveHeight;
     isScaled = true;
   }
-  Serial.printf("[%lu] [GFX] Scaling by %f - %s\n", millis(), scale, isScaled ? "scaled" : "not scaled");
+  LOG_DBG("GFX", "Scaling by %f - %s", scale, isScaled ? "scaled" : "not scaled");
 
   // Calculate output row size (2 bits per pixel, packed into bytes)
   // IMPORTANT: Use int, not uint8_t, to avoid overflow for images > 1020 pixels wide
@@ -457,7 +458,7 @@ void GfxRenderer::drawBitmap(const Bitmap& bitmap, const int x, const int y, con
   auto* rowBytes = static_cast<uint8_t*>(malloc(bitmap.getRowBytes()));
 
   if (!outputRow || !rowBytes) {
-    Serial.printf("[%lu] [GFX] !! Failed to allocate BMP row buffers\n", millis());
+    LOG_ERR("GFX", "!! Failed to allocate BMP row buffers");
     free(outputRow);
     free(rowBytes);
     return;
@@ -481,7 +482,7 @@ void GfxRenderer::drawBitmap(const Bitmap& bitmap, const int x, const int y, con
     }
 
     if (bitmap.readNextRow(outputRow, rowBytes) != BmpReaderError::Ok) {
-      Serial.printf("[%lu] [GFX] Failed to read row %d from bitmap\n", millis(), bmpY);
+      LOG_ERR("GFX", "Failed to read row %d from bitmap", bmpY);
       free(outputRow);
       free(rowBytes);
       return;
@@ -564,7 +565,7 @@ void GfxRenderer::drawBitmap1Bit(const Bitmap& bitmap, const int x, const int y,
   auto* rowBytes = static_cast<uint8_t*>(malloc(bitmap.getRowBytes()));
 
   if (!outputRow || !rowBytes) {
-    Serial.printf("[%lu] [GFX] !! Failed to allocate 1-bit BMP row buffers\n", millis());
+    LOG_ERR("GFX", "!! Failed to allocate 1-bit BMP row buffers");
     free(outputRow);
     free(rowBytes);
     return;
@@ -573,7 +574,7 @@ void GfxRenderer::drawBitmap1Bit(const Bitmap& bitmap, const int x, const int y,
   for (int bmpY = 0; bmpY < bitmap.getHeight(); bmpY++) {
     // Read rows sequentially using readNextRow
     if (bitmap.readNextRow(outputRow, rowBytes) != BmpReaderError::Ok) {
-      Serial.printf("[%lu] [GFX] Failed to read row %d from 1-bit bitmap\n", millis(), bmpY);
+      LOG_ERR("GFX", "Failed to read row %d from 1-bit bitmap", bmpY);
       free(outputRow);
       free(rowBytes);
       return;
@@ -654,7 +655,7 @@ void GfxRenderer::fillPolygon(const int* xPoints, const int* yPoints, int numPoi
   // Allocate node buffer for scanline algorithm
   auto* nodeX = static_cast<int*>(malloc(numPoints * sizeof(int)));
   if (!nodeX) {
-    Serial.printf("[%lu] [GFX] !! Failed to allocate polygon node buffer\n", millis());
+    LOG_ERR("GFX", "!! Failed to allocate polygon node buffer");
     return;
   }
 
@@ -721,10 +722,27 @@ void GfxRenderer::invertScreen() const {
 
 void GfxRenderer::displayBuffer(const HalDisplay::RefreshMode refreshMode) const {
   auto elapsed = millis() - start_ms;
-  Serial.printf("[%lu] [GFX] Time = %lu ms from clearScreen to displayBuffer\n", millis(), elapsed);
+  LOG_DBG("GFX", "Time = %lu ms from clearScreen to displayBuffer", elapsed);
   display.displayBuffer(refreshMode, fadingFix);
 }
 
+// EXPERIMENTAL: Display only a rectangular region with specified refresh mode
+void GfxRenderer::displayWindow(int x, int y, int width, int height,
+                                HalDisplay::RefreshMode mode) const {
+  LOG_DBG("GFX", "Displaying window at (%d,%d) size (%dx%d) with mode %d", x, y, width, height,
+          static_cast<int>(mode));
+
+  // Validate bounds
+  if (x < 0 || y < 0 || x + width > getScreenWidth() || y + height > getScreenHeight()) {
+    LOG_ERR("GFX", "Window bounds exceed display dimensions!");
+    return;
+  }
+
+  display.displayWindow(static_cast<uint16_t>(x), static_cast<uint16_t>(y),
+                        static_cast<uint16_t>(width), static_cast<uint16_t>(height), mode,
+                        fadingFix);
+}
+
 std::string GfxRenderer::truncatedText(const int fontId, const char* text, const int maxWidth,
                                        const EpdFontFamily::Style style) const {
   if (!text || maxWidth <= 0) return "";
@@ -775,7 +793,7 @@ int GfxRenderer::getScreenHeight() const {
 
 int GfxRenderer::getSpaceWidth(const int fontId) const {
   if (fontMap.count(fontId) == 0) {
-    Serial.printf("[%lu] [GFX] Font %d not found\n", millis(), fontId);
+    LOG_ERR("GFX", "Font %d not found", fontId);
     return 0;
   }
 
@@ -784,7 +802,7 @@ int GfxRenderer::getSpaceWidth(const int fontId) const {
 
 int GfxRenderer::getTextAdvanceX(const int fontId, const char* text) const {
   if (fontMap.count(fontId) == 0) {
-    Serial.printf("[%lu] [GFX] Font %d not found\n", millis(), fontId);
+    LOG_ERR("GFX", "Font %d not found", fontId);
     return 0;
   }
 
@@ -798,7 +816,7 @@ int GfxRenderer::getTextAdvanceX(const int fontId, const char* text) const {
 
 int GfxRenderer::getFontAscenderSize(const int fontId) const {
   if (fontMap.count(fontId) == 0) {
-    Serial.printf("[%lu] [GFX] Font %d not found\n", millis(), fontId);
+    LOG_ERR("GFX", "Font %d not found", fontId);
     return 0;
   }
 
@@ -807,7 +825,7 @@ int GfxRenderer::getFontAscenderSize(const int fontId) const {
 
 int GfxRenderer::getLineHeight(const int fontId) const {
   if (fontMap.count(fontId) == 0) {
-    Serial.printf("[%lu] [GFX] Font %d not found\n", millis(), fontId);
+    LOG_ERR("GFX", "Font %d not found", fontId);
     return 0;
   }
 
@@ -816,7 +834,7 @@ int GfxRenderer::getLineHeight(const int fontId) const {
 
 int GfxRenderer::getTextHeight(const int fontId) const {
   if (fontMap.count(fontId) == 0) {
-    Serial.printf("[%lu] [GFX] Font %d not found\n", millis(), fontId);
+    LOG_ERR("GFX", "Font %d not found", fontId);
     return 0;
   }
   return fontMap.at(fontId).getData(EpdFontFamily::REGULAR)->ascender;
@@ -830,7 +848,7 @@ void GfxRenderer::drawTextRotated90CW(const int fontId, const int x, const int y
   }
 
   if (fontMap.count(fontId) == 0) {
-    Serial.printf("[%lu] [GFX] Font %d not found\n", millis(), fontId);
+    LOG_ERR("GFX", "Font %d not found", fontId);
     return;
   }
   const auto font = fontMap.at(fontId);
@@ -905,6 +923,92 @@ void GfxRenderer::drawTextRotated90CW(const int fontId, const int x, const int y
   }
 }
 
+void GfxRenderer::drawTextRotated90CCW(const int fontId, const int x, const int y, const char* text, const bool black,
+                                       const EpdFontFamily::Style style) const {
+  // Cannot draw a NULL / empty string
+  if (text == nullptr || *text == '\0') {
+    return;
+  }
+
+  if (fontMap.count(fontId) == 0) {
+    LOG_ERR("GFX", "Font %d not found", fontId);
+    return;
+  }
+  const auto font = fontMap.at(fontId);
+
+  // No printable characters
+  if (!font.hasPrintableChars(text, style)) {
+    return;
+  }
+
+  // For 90° counter-clockwise rotation:
+  // Mirror of CW: glyphY maps to -X direction, glyphX maps to +Y direction
+  // Text reads from top to bottom
+
+  const int advanceY = font.getData(style)->advanceY;
+  const int ascender = font.getData(style)->ascender;
+
+  int yPos = y;  // Current Y position (increases as we draw characters)
+
+  uint32_t cp;
+  while ((cp = utf8NextCodepoint(reinterpret_cast<const uint8_t**>(&text)))) {
+    const EpdGlyph* glyph = font.getGlyph(cp, style);
+    if (!glyph) {
+      glyph = font.getGlyph(REPLACEMENT_GLYPH, style);
+    }
+    if (!glyph) {
+      continue;
+    }
+
+    const int is2Bit = font.getData(style)->is2Bit;
+    const uint32_t offset = glyph->dataOffset;
+    const uint8_t width = glyph->width;
+    const uint8_t height = glyph->height;
+    const int left = glyph->left;
+    const int top = glyph->top;
+
+    const uint8_t* bitmap = &font.getData(style)->bitmap[offset];
+
+    if (bitmap != nullptr) {
+      for (int glyphY = 0; glyphY < height; glyphY++) {
+        for (int glyphX = 0; glyphX < width; glyphX++) {
+          const int pixelPosition = glyphY * width + glyphX;
+
+          // 90° counter-clockwise rotation transformation:
+          // screenX = mirrored CW X (right-to-left within advanceY span)
+          // screenY = yPos + (left + glyphX) (downward)
+          const int screenX = x + advanceY - 1 - (ascender - top + glyphY);
+          const int screenY = yPos + left + glyphX;
+
+          if (is2Bit) {
+            const uint8_t byte = bitmap[pixelPosition / 4];
+            const uint8_t bit_index = (3 - pixelPosition % 4) * 2;
+            const uint8_t bmpVal = 3 - (byte >> bit_index) & 0x3;
+
+            if (renderMode == BW && bmpVal < 3) {
+              drawPixel(screenX, screenY, black);
+            } else if (renderMode == GRAYSCALE_MSB && (bmpVal == 1 || bmpVal == 2)) {
+              drawPixel(screenX, screenY, false);
+            } else if (renderMode == GRAYSCALE_LSB && bmpVal == 1) {
+              drawPixel(screenX, screenY, false);
+            }
+          } else {
+            const uint8_t byte = bitmap[pixelPosition / 8];
+            const uint8_t bit_index = 7 - (pixelPosition % 8);
+
+            if ((byte >> bit_index) & 1) {
+              drawPixel(screenX, screenY, black);
+            }
+          }
+        }
+      }
+    }
+
+    // Move to next character position (going down, so increase Y)
+    yPos += glyph->advanceX;
+  }
+}
+
 uint8_t* GfxRenderer::getFrameBuffer() const { return frameBuffer; }
 
 size_t GfxRenderer::getBufferSize() { return HalDisplay::BUFFER_SIZE; }
@@ -938,8 +1042,7 @@ bool GfxRenderer::storeBwBuffer() {
   for (size_t i = 0; i < BW_BUFFER_NUM_CHUNKS; i++) {
     // Check if any chunks are already allocated
     if (bwBufferChunks[i]) {
-      Serial.printf("[%lu] [GFX] !! BW buffer chunk %zu already stored - this is likely a bug, freeing chunk\n",
-                    millis(), i);
+      LOG_ERR("GFX", "!! BW buffer chunk %zu already stored - this is likely a bug, freeing chunk", i);
       free(bwBufferChunks[i]);
       bwBufferChunks[i] = nullptr;
     }
@@ -948,8 +1051,7 @@ bool GfxRenderer::storeBwBuffer() {
     bwBufferChunks[i] = static_cast<uint8_t*>(malloc(BW_BUFFER_CHUNK_SIZE));
 
     if (!bwBufferChunks[i]) {
-      Serial.printf("[%lu] [GFX] !! Failed to allocate BW buffer chunk %zu (%zu bytes)\n", millis(), i,
-                    BW_BUFFER_CHUNK_SIZE);
+      LOG_ERR("GFX", "!! Failed to allocate BW buffer chunk %zu (%zu bytes)", i, BW_BUFFER_CHUNK_SIZE);
       // Free previously allocated chunks
       freeBwBufferChunks();
       return false;
@@ -958,8 +1060,7 @@ bool GfxRenderer::storeBwBuffer() {
     memcpy(bwBufferChunks[i], frameBuffer + offset, BW_BUFFER_CHUNK_SIZE);
   }
 
-  Serial.printf("[%lu] [GFX] Stored BW buffer in %zu chunks (%zu bytes each)\n", millis(), BW_BUFFER_NUM_CHUNKS,
-                BW_BUFFER_CHUNK_SIZE);
+  LOG_DBG("GFX", "Stored BW buffer in %zu chunks (%zu bytes each)", BW_BUFFER_NUM_CHUNKS, BW_BUFFER_CHUNK_SIZE);
   return true;
 }
 
@@ -986,7 +1087,7 @@ void GfxRenderer::restoreBwBuffer() {
   for (size_t i = 0; i < BW_BUFFER_NUM_CHUNKS; i++) {
     // Check if chunk is missing
     if (!bwBufferChunks[i]) {
-      Serial.printf("[%lu] [GFX] !! BW buffer chunks not stored - this is likely a bug\n", millis());
+      LOG_ERR("GFX", "!! BW buffer chunks not stored - this is likely a bug");
       freeBwBufferChunks();
       return;
     }
@@ -998,7 +1099,7 @@ void GfxRenderer::restoreBwBuffer() {
   display.cleanupGrayscaleBuffers(frameBuffer);
 
   freeBwBufferChunks();
-  Serial.printf("[%lu] [GFX] Restored and freed BW buffer chunks\n", millis());
+  LOG_DBG("GFX", "Restored and freed BW buffer chunks");
 }
 
 /**
@@ -1020,7 +1121,7 @@ void GfxRenderer::renderChar(const EpdFontFamily& fontFamily, const uint32_t cp,
 
   // no glyph?
   if (!glyph) {
-    Serial.printf("[%lu] [GFX] No glyph for codepoint %d\n", millis(), cp);
+    LOG_ERR("GFX", "No glyph for codepoint %d", cp);
     return;
   }
 

lib/GfxRenderer/GfxRenderer.h

@@ -70,7 +70,8 @@ class GfxRenderer {
   int getScreenHeight() const;
   void displayBuffer(HalDisplay::RefreshMode refreshMode = HalDisplay::FAST_REFRESH) const;
   // EXPERIMENTAL: Windowed update - display only a rectangular region
-  // void displayWindow(int x, int y, int width, int height) const;
+  void displayWindow(int x, int y, int width, int height,
+                     HalDisplay::RefreshMode mode = HalDisplay::FAST_REFRESH) const;
   void invertScreen() const;
   void clearScreen(uint8_t color = 0xFF) const;
   void getOrientedViewableTRBL(int* outTop, int* outRight, int* outBottom, int* outLeft) const;
@@ -111,13 +112,16 @@ class GfxRenderer {
   std::string truncatedText(int fontId, const char* text, int maxWidth,
                             EpdFontFamily::Style style = EpdFontFamily::REGULAR) const;
 
-  // Helper for drawing rotated text (90 degrees clockwise, for side buttons)
+  // Helpers for drawing rotated text (for side buttons)
   void drawTextRotated90CW(int fontId, int x, int y, const char* text, bool black = true,
                            EpdFontFamily::Style style = EpdFontFamily::REGULAR) const;
+  void drawTextRotated90CCW(int fontId, int x, int y, const char* text, bool black = true,
+                            EpdFontFamily::Style style = EpdFontFamily::REGULAR) const;
   int getTextHeight(int fontId) const;
 
   // Grayscale functions
   void setRenderMode(const RenderMode mode) { this->renderMode = mode; }
+  RenderMode getRenderMode() const { return renderMode; }
   void copyGrayscaleLsbBuffers() const;
   void copyGrayscaleMsbBuffers() const;
   void displayGrayBuffer() const;

lib/JpegToBmpConverter/JpegToBmpConverter.cpp

@@ -1,7 +1,7 @@
 #include "JpegToBmpConverter.h"
 
 #include <HalStorage.h>
-#include <HardwareSerial.h>
+#include <Logging.h>
 #include <picojpeg.h>
 
 #include <cstdio>
@@ -201,8 +201,7 @@ unsigned char JpegToBmpConverter::jpegReadCallback(unsigned char* pBuf, const un
 // Internal implementation with configurable target size and bit depth
 bool JpegToBmpConverter::jpegFileToBmpStreamInternal(FsFile& jpegFile, Print& bmpOut, int targetWidth, int targetHeight,
                                                      bool oneBit, bool crop) {
-  Serial.printf("[%lu] [JPG] Converting JPEG to %s BMP (target: %dx%d)\n", millis(), oneBit ? "1-bit" : "2-bit",
-                targetWidth, targetHeight);
+  LOG_DBG("JPG", "Converting JPEG to %s BMP (target: %dx%d)", oneBit ? "1-bit" : "2-bit", targetWidth, targetHeight);
 
   // Setup context for picojpeg callback
   JpegReadContext context = {.file = jpegFile, .bufferPos = 0, .bufferFilled = 0};
@@ -211,12 +210,12 @@ bool JpegToBmpConverter::jpegFileToBmpStreamInternal(FsFile& jpegFile, Print& bm
   pjpeg_image_info_t imageInfo;
   const unsigned char status = pjpeg_decode_init(&imageInfo, jpegReadCallback, &context, 0);
   if (status != 0) {
-    Serial.printf("[%lu] [JPG] JPEG decode init failed with error code: %d\n", millis(), status);
+    LOG_ERR("JPG", "JPEG decode init failed with error code: %d", status);
     return false;
   }
 
-  Serial.printf("[%lu] [JPG] JPEG dimensions: %dx%d, components: %d, MCUs: %dx%d\n", millis(), imageInfo.m_width,
-                imageInfo.m_height, imageInfo.m_comps, imageInfo.m_MCUSPerRow, imageInfo.m_MCUSPerCol);
+  LOG_DBG("JPG", "JPEG dimensions: %dx%d, components: %d, MCUs: %dx%d", imageInfo.m_width, imageInfo.m_height,
+          imageInfo.m_comps, imageInfo.m_MCUSPerRow, imageInfo.m_MCUSPerCol);
 
   // Safety limits to prevent memory issues on ESP32
   constexpr int MAX_IMAGE_WIDTH = 2048;
@@ -224,8 +223,8 @@ bool JpegToBmpConverter::jpegFileToBmpStreamInternal(FsFile& jpegFile, Print& bm
   constexpr int MAX_MCU_ROW_BYTES = 65536;
 
   if (imageInfo.m_width > MAX_IMAGE_WIDTH || imageInfo.m_height > MAX_IMAGE_HEIGHT) {
-    Serial.printf("[%lu] [JPG] Image too large (%dx%d), max supported: %dx%d\n", millis(), imageInfo.m_width,
-                  imageInfo.m_height, MAX_IMAGE_WIDTH, MAX_IMAGE_HEIGHT);
+    LOG_DBG("JPG", "Image too large (%dx%d), max supported: %dx%d", imageInfo.m_width, imageInfo.m_height,
+            MAX_IMAGE_WIDTH, MAX_IMAGE_HEIGHT);
     return false;
   }
 
@@ -262,8 +261,8 @@ bool JpegToBmpConverter::jpegFileToBmpStreamInternal(FsFile& jpegFile, Print& bm
     scaleY_fp = (static_cast<uint32_t>(imageInfo.m_height) << 16) / outHeight;
     needsScaling = true;
 
-    Serial.printf("[%lu] [JPG] Pre-scaling %dx%d -> %dx%d (fit to %dx%d)\n", millis(), imageInfo.m_width,
-                  imageInfo.m_height, outWidth, outHeight, targetWidth, targetHeight);
+    LOG_DBG("JPG", "Pre-scaling %dx%d -> %dx%d (fit to %dx%d)", imageInfo.m_width, imageInfo.m_height, outWidth,
+            outHeight, targetWidth, targetHeight);
   }
 
   // Write BMP header with output dimensions
@@ -282,7 +281,7 @@ bool JpegToBmpConverter::jpegFileToBmpStreamInternal(FsFile& jpegFile, Print& bm
   // Allocate row buffer
   auto* rowBuffer = static_cast<uint8_t*>(malloc(bytesPerRow));
   if (!rowBuffer) {
-    Serial.printf("[%lu] [JPG] Failed to allocate row buffer\n", millis());
+    LOG_ERR("JPG", "Failed to allocate row buffer");
     return false;
   }
 
@@ -293,15 +292,14 @@ bool JpegToBmpConverter::jpegFileToBmpStreamInternal(FsFile& jpegFile, Print& bm
 
   // Validate MCU row buffer size before allocation
   if (mcuRowPixels > MAX_MCU_ROW_BYTES) {
-    Serial.printf("[%lu] [JPG] MCU row buffer too large (%d bytes), max: %d\n", millis(), mcuRowPixels,
-                  MAX_MCU_ROW_BYTES);
+    LOG_DBG("JPG", "MCU row buffer too large (%d bytes), max: %d", mcuRowPixels, MAX_MCU_ROW_BYTES);
     free(rowBuffer);
     return false;
   }
 
   auto* mcuRowBuffer = static_cast<uint8_t*>(malloc(mcuRowPixels));
   if (!mcuRowBuffer) {
-    Serial.printf("[%lu] [JPG] Failed to allocate MCU row buffer (%d bytes)\n", millis(), mcuRowPixels);
+    LOG_ERR("JPG", "Failed to allocate MCU row buffer (%d bytes)", mcuRowPixels);
     free(rowBuffer);
     return false;
   }
@@ -349,10 +347,9 @@ bool JpegToBmpConverter::jpegFileToBmpStreamInternal(FsFile& jpegFile, Print& bm
       const unsigned char mcuStatus = pjpeg_decode_mcu();
       if (mcuStatus != 0) {
         if (mcuStatus == PJPG_NO_MORE_BLOCKS) {
-          Serial.printf("[%lu] [JPG] Unexpected end of blocks at MCU (%d, %d)\n", millis(), mcuX, mcuY);
+          LOG_ERR("JPG", "Unexpected end of blocks at MCU (%d, %d)", mcuX, mcuY);
         } else {
-          Serial.printf("[%lu] [JPG] JPEG decode MCU failed at (%d, %d) with error code: %d\n", millis(), mcuX, mcuY,
-                        mcuStatus);
+          LOG_ERR("JPG", "JPEG decode MCU failed at (%d, %d) with error code: %d", mcuX, mcuY, mcuStatus);
         }
         free(mcuRowBuffer);
         free(rowBuffer);
@@ -549,7 +546,7 @@ bool JpegToBmpConverter::jpegFileToBmpStreamInternal(FsFile& jpegFile, Print& bm
   free(mcuRowBuffer);
   free(rowBuffer);
 
-  Serial.printf("[%lu] [JPG] Successfully converted JPEG to BMP\n", millis());
+  LOG_DBG("JPG", "Successfully converted JPEG to BMP");
   return true;
 }
 

lib/KOReaderSync/KOReaderCredentialStore.cpp

@@ -1,7 +1,7 @@
 #include "KOReaderCredentialStore.h"
 
 #include <HalStorage.h>
-#include <HardwareSerial.h>
+#include <Logging.h>
 #include <MD5Builder.h>
 #include <Serialization.h>
 
@@ -44,7 +44,7 @@ bool KOReaderCredentialStore::saveToFile() const {
 
   // Write username (plaintext - not particularly sensitive)
   serialization::writeString(file, username);
-  Serial.printf("[%lu] [KRS] Saving username: %s\n", millis(), username.c_str());
+  LOG_DBG("KRS", "Saving username: %s", username.c_str());
 
   // Write password (obfuscated)
   std::string obfuscatedPwd = password;
@@ -58,14 +58,14 @@ bool KOReaderCredentialStore::saveToFile() const {
   serialization::writePod(file, static_cast<uint8_t>(matchMethod));
 
   file.close();
-  Serial.printf("[%lu] [KRS] Saved KOReader credentials to file\n", millis());
+  LOG_DBG("KRS", "Saved KOReader credentials to file");
   return true;
 }
 
 bool KOReaderCredentialStore::loadFromFile() {
   FsFile file;
   if (!Storage.openFileForRead("KRS", KOREADER_FILE, file)) {
-    Serial.printf("[%lu] [KRS] No credentials file found\n", millis());
+    LOG_DBG("KRS", "No credentials file found");
     return false;
   }
 
@@ -73,7 +73,7 @@ bool KOReaderCredentialStore::loadFromFile() {
   uint8_t version;
   serialization::readPod(file, version);
   if (version != KOREADER_FILE_VERSION) {
-    Serial.printf("[%lu] [KRS] Unknown file version: %u\n", millis(), version);
+    LOG_DBG("KRS", "Unknown file version: %u", version);
     file.close();
     return false;
   }
@@ -110,14 +110,14 @@ bool KOReaderCredentialStore::loadFromFile() {
   }
 
   file.close();
-  Serial.printf("[%lu] [KRS] Loaded KOReader credentials for user: %s\n", millis(), username.c_str());
+  LOG_DBG("KRS", "Loaded KOReader credentials for user: %s", username.c_str());
   return true;
 }
 
 void KOReaderCredentialStore::setCredentials(const std::string& user, const std::string& pass) {
   username = user;
   password = pass;
-  Serial.printf("[%lu] [KRS] Set credentials for user: %s\n", millis(), user.c_str());
+  LOG_DBG("KRS", "Set credentials for user: %s", user.c_str());
 }
 
 std::string KOReaderCredentialStore::getMd5Password() const {
@@ -140,12 +140,12 @@ void KOReaderCredentialStore::clearCredentials() {
   username.clear();
   password.clear();
   saveToFile();
-  Serial.printf("[%lu] [KRS] Cleared KOReader credentials\n", millis());
+  LOG_DBG("KRS", "Cleared KOReader credentials");
 }
 
 void KOReaderCredentialStore::setServerUrl(const std::string& url) {
   serverUrl = url;
-  Serial.printf("[%lu] [KRS] Set server URL: %s\n", millis(), url.empty() ? "(default)" : url.c_str());
+  LOG_DBG("KRS", "Set server URL: %s", url.empty() ? "(default)" : url.c_str());
 }
 
 std::string KOReaderCredentialStore::getBaseUrl() const {
@@ -163,6 +163,5 @@ std::string KOReaderCredentialStore::getBaseUrl() const {
 
 void KOReaderCredentialStore::setMatchMethod(DocumentMatchMethod method) {
   matchMethod = method;
-  Serial.printf("[%lu] [KRS] Set match method: %s\n", millis(),
-                method == DocumentMatchMethod::FILENAME ? "Filename" : "Binary");
+  LOG_DBG("KRS", "Set match method: %s", method == DocumentMatchMethod::FILENAME ? "Filename" : "Binary");
 }

lib/KOReaderSync/KOReaderDocumentId.cpp

@@ -1,7 +1,7 @@
 #include "KOReaderDocumentId.h"
 
 #include <HalStorage.h>
-#include <HardwareSerial.h>
+#include <Logging.h>
 #include <MD5Builder.h>
 
 namespace {
@@ -27,7 +27,7 @@ std::string KOReaderDocumentId::calculateFromFilename(const std::string& filePat
   md5.calculate();
 
   std::string result = md5.toString().c_str();
-  Serial.printf("[%lu] [KODoc] Filename hash: %s (from '%s')\n", millis(), result.c_str(), filename.c_str());
+  LOG_DBG("KODoc", "Filename hash: %s (from '%s')", result.c_str(), filename.c_str());
   return result;
 }
 
@@ -44,12 +44,12 @@ size_t KOReaderDocumentId::getOffset(int i) {
 std::string KOReaderDocumentId::calculate(const std::string& filePath) {
   FsFile file;
   if (!Storage.openFileForRead("KODoc", filePath, file)) {
-    Serial.printf("[%lu] [KODoc] Failed to open file: %s\n", millis(), filePath.c_str());
+    LOG_DBG("KODoc", "Failed to open file: %s", filePath.c_str());
     return "";
   }
 
   const size_t fileSize = file.fileSize();
-  Serial.printf("[%lu] [KODoc] Calculating hash for file: %s (size: %zu)\n", millis(), filePath.c_str(), fileSize);
+  LOG_DBG("KODoc", "Calculating hash for file: %s (size: %zu)", filePath.c_str(), fileSize);
 
   // Initialize MD5 builder
   MD5Builder md5;
@@ -70,7 +70,7 @@ std::string KOReaderDocumentId::calculate(const std::string& filePath) {
 
     // Seek to offset
     if (!file.seekSet(offset)) {
-      Serial.printf("[%lu] [KODoc] Failed to seek to offset %zu\n", millis(), offset);
+      LOG_DBG("KODoc", "Failed to seek to offset %zu", offset);
       continue;
     }
 
@@ -90,7 +90,7 @@ std::string KOReaderDocumentId::calculate(const std::string& filePath) {
   md5.calculate();
   std::string result = md5.toString().c_str();
 
-  Serial.printf("[%lu] [KODoc] Hash calculated: %s (from %zu bytes)\n", millis(), result.c_str(), totalBytesRead);
+  LOG_DBG("KODoc", "Hash calculated: %s (from %zu bytes)", result.c_str(), totalBytesRead);
 
   return result;
 }

lib/KOReaderSync/KOReaderSyncClient.cpp

@@ -2,7 +2,7 @@
 
 #include <ArduinoJson.h>
 #include <HTTPClient.h>
-#include <HardwareSerial.h>
+#include <Logging.h>
 #include <WiFi.h>
 #include <WiFiClientSecure.h>
 
@@ -30,12 +30,12 @@ bool isHttpsUrl(const std::string& url) { return url.rfind("https://", 0) == 0;
 
 KOReaderSyncClient::Error KOReaderSyncClient::authenticate() {
   if (!KOREADER_STORE.hasCredentials()) {
-    Serial.printf("[%lu] [KOSync] No credentials configured\n", millis());
+    LOG_DBG("KOSync", "No credentials configured");
     return NO_CREDENTIALS;
   }
 
   std::string url = KOREADER_STORE.getBaseUrl() + "/users/auth";
-  Serial.printf("[%lu] [KOSync] Authenticating: %s\n", millis(), url.c_str());
+  LOG_DBG("KOSync", "Authenticating: %s", url.c_str());
 
   HTTPClient http;
   std::unique_ptr<WiFiClientSecure> secureClient;
@@ -53,7 +53,7 @@ KOReaderSyncClient::Error KOReaderSyncClient::authenticate() {
   const int httpCode = http.GET();
   http.end();
 
-  Serial.printf("[%lu] [KOSync] Auth response: %d\n", millis(), httpCode);
+  LOG_DBG("KOSync", "Auth response: %d", httpCode);
 
   if (httpCode == 200) {
     return OK;
@@ -68,12 +68,12 @@ KOReaderSyncClient::Error KOReaderSyncClient::authenticate() {
 KOReaderSyncClient::Error KOReaderSyncClient::getProgress(const std::string& documentHash,
                                                           KOReaderProgress& outProgress) {
   if (!KOREADER_STORE.hasCredentials()) {
-    Serial.printf("[%lu] [KOSync] No credentials configured\n", millis());
+    LOG_DBG("KOSync", "No credentials configured");
     return NO_CREDENTIALS;
   }
 
   std::string url = KOREADER_STORE.getBaseUrl() + "/syncs/progress/" + documentHash;
-  Serial.printf("[%lu] [KOSync] Getting progress: %s\n", millis(), url.c_str());
+  LOG_DBG("KOSync", "Getting progress: %s", url.c_str());
 
   HTTPClient http;
   std::unique_ptr<WiFiClientSecure> secureClient;
@@ -99,7 +99,7 @@ KOReaderSyncClient::Error KOReaderSyncClient::getProgress(const std::string& doc
     const DeserializationError error = deserializeJson(doc, responseBody);
 
     if (error) {
-      Serial.printf("[%lu] [KOSync] JSON parse failed: %s\n", millis(), error.c_str());
+      LOG_ERR("KOSync", "JSON parse failed: %s", error.c_str());
       return JSON_ERROR;
     }
 
@@ -110,14 +110,13 @@ KOReaderSyncClient::Error KOReaderSyncClient::getProgress(const std::string& doc
     outProgress.deviceId = doc["device_id"].as<std::string>();
     outProgress.timestamp = doc["timestamp"].as<int64_t>();
 
-    Serial.printf("[%lu] [KOSync] Got progress: %.2f%% at %s\n", millis(), outProgress.percentage * 100,
-                  outProgress.progress.c_str());
+    LOG_DBG("KOSync", "Got progress: %.2f%% at %s", outProgress.percentage * 100, outProgress.progress.c_str());
     return OK;
   }
 
   http.end();
 
-  Serial.printf("[%lu] [KOSync] Get progress response: %d\n", millis(), httpCode);
+  LOG_DBG("KOSync", "Get progress response: %d", httpCode);
 
   if (httpCode == 401) {
     return AUTH_FAILED;
@@ -131,12 +130,12 @@ KOReaderSyncClient::Error KOReaderSyncClient::getProgress(const std::string& doc
 
 KOReaderSyncClient::Error KOReaderSyncClient::updateProgress(const KOReaderProgress& progress) {
   if (!KOREADER_STORE.hasCredentials()) {
-    Serial.printf("[%lu] [KOSync] No credentials configured\n", millis());
+    LOG_DBG("KOSync", "No credentials configured");
     return NO_CREDENTIALS;
   }
 
   std::string url = KOREADER_STORE.getBaseUrl() + "/syncs/progress";
-  Serial.printf("[%lu] [KOSync] Updating progress: %s\n", millis(), url.c_str());
+  LOG_DBG("KOSync", "Updating progress: %s", url.c_str());
 
   HTTPClient http;
   std::unique_ptr<WiFiClientSecure> secureClient;
@@ -163,12 +162,12 @@ KOReaderSyncClient::Error KOReaderSyncClient::updateProgress(const KOReaderProgr
   std::string body;
   serializeJson(doc, body);
 
-  Serial.printf("[%lu] [KOSync] Request body: %s\n", millis(), body.c_str());
+  LOG_DBG("KOSync", "Request body: %s", body.c_str());
 
   const int httpCode = http.PUT(body.c_str());
   http.end();
 
-  Serial.printf("[%lu] [KOSync] Update progress response: %d\n", millis(), httpCode);
+  LOG_DBG("KOSync", "Update progress response: %d", httpCode);
 
   if (httpCode == 200 || httpCode == 202) {
     return OK;

lib/KOReaderSync/ProgressMapper.cpp

@@ -1,6 +1,6 @@
 #include "ProgressMapper.h"
 
-#include <HardwareSerial.h>
+#include <Logging.h>
 
 #include <cmath>
 
@@ -23,8 +23,8 @@ KOReaderPosition ProgressMapper::toKOReader(const std::shared_ptr<Epub>& epub, c
   const int tocIndex = epub->getTocIndexForSpineIndex(pos.spineIndex);
   const std::string chapterName = (tocIndex >= 0) ? epub->getTocItem(tocIndex).title : "unknown";
 
-  Serial.printf("[%lu] [ProgressMapper] CrossPoint -> KOReader: chapter='%s', page=%d/%d -> %.2f%% at %s\n", millis(),
-                chapterName.c_str(), pos.pageNumber, pos.totalPages, result.percentage * 100, result.xpath.c_str());
+  LOG_DBG("ProgressMapper", "CrossPoint -> KOReader: chapter='%s', page=%d/%d -> %.2f%% at %s", chapterName.c_str(),
+          pos.pageNumber, pos.totalPages, result.percentage * 100, result.xpath.c_str());
 
   return result;
 }
@@ -76,8 +76,8 @@ CrossPointPosition ProgressMapper::toCrossPoint(const std::shared_ptr<Epub>& epu
     }
   }
 
-  Serial.printf("[%lu] [ProgressMapper] KOReader -> CrossPoint: %.2f%% at %s -> spine=%d, page=%d\n", millis(),
-                koPos.percentage * 100, koPos.xpath.c_str(), result.spineIndex, result.pageNumber);
+  LOG_DBG("ProgressMapper", "KOReader -> CrossPoint: %.2f%% at %s -> spine=%d, page=%d", koPos.percentage * 100,
+          koPos.xpath.c_str(), result.spineIndex, result.pageNumber);
 
   return result;
 }

lib/Logging/Logging.cpp

@@ -0,0 +1,47 @@
+#include "Logging.h"
+
+// Since logging can take a large amount of flash, we want to make the format string as short as possible.
+// This logPrintf prepend the timestamp, level and origin to the user-provided message, so that the user only needs to
+// provide the format string for the message itself.
+void logPrintf(const char* level, const char* origin, const char* format, ...) {
+  if (!logSerial) {
+    return;  // Serial not initialized, skip logging
+  }
+  va_list args;
+  va_start(args, format);
+  char buf[256];
+  char* c = buf;
+  // add the timestamp
+  {
+    unsigned long ms = millis();
+    int len = snprintf(c, sizeof(buf), "[%lu] ", ms);
+    if (len < 0) {
+      return;  // encoding error, skip logging
+    }
+    c += len;
+  }
+  // add the level
+  {
+    const char* p = level;
+    size_t remaining = sizeof(buf) - (c - buf);
+    while (*p && remaining > 1) {
+      *c++ = *p++;
+      remaining--;
+    }
+    if (remaining > 1) {
+      *c++ = ' ';
+    }
+  }
+  // add the origin
+  {
+    int len = snprintf(c, sizeof(buf) - (c - buf), "[%s] ", origin);
+    if (len < 0) {
+      return;  // encoding error, skip logging
+    }
+    c += len;
+  }
+  // add the user message
+  vsnprintf(c, sizeof(buf) - (c - buf), format, args);
+  va_end(args);
+  logSerial.print(buf);
+}

lib/Logging/Logging.h

@@ -0,0 +1,71 @@
+#pragma once
+
+#include <HardwareSerial.h>
+
+/*
+Define ENABLE_SERIAL_LOG to enable logging
+Can be set in platformio.ini build_flags or as a compile definition
+
+Define LOG_LEVEL to control log verbosity:
+0 = ERR only
+1 = ERR + INF
+2 = ERR + INF + DBG
+If not defined, defaults to 0
+
+If you have a legitimate need for raw Serial access (e.g., binary data,
+special formatting), use the underlying logSerial object directly:
+    logSerial.printf("Special case: %d\n", value);
+    logSerial.write(binaryData, length);
+
+The logSerial reference (defined below) points to the real Serial object and
+won't trigger deprecation warnings.
+*/
+
+#ifndef LOG_LEVEL
+#define LOG_LEVEL 0
+#endif
+
+static HWCDC& logSerial = Serial;
+
+void logPrintf(const char* level, const char* origin, const char* format, ...);
+
+#ifdef ENABLE_SERIAL_LOG
+#if LOG_LEVEL >= 0
+#define LOG_ERR(origin, format, ...) logPrintf("[ERR]", origin, format "\n", ##__VA_ARGS__)
+#else
+#define LOG_ERR(origin, format, ...)
+#endif
+
+#if LOG_LEVEL >= 1
+#define LOG_INF(origin, format, ...) logPrintf("[INF]", origin, format "\n", ##__VA_ARGS__)
+#else
+#define LOG_INF(origin, format, ...)
+#endif
+
+#if LOG_LEVEL >= 2
+#define LOG_DBG(origin, format, ...) logPrintf("[DBG]", origin, format "\n", ##__VA_ARGS__)
+#else
+#define LOG_DBG(origin, format, ...)
+#endif
+#else
+#define LOG_DBG(origin, format, ...)
+#define LOG_ERR(origin, format, ...)
+#define LOG_INF(origin, format, ...)
+#endif
+
+class MySerialImpl : public Print {
+ public:
+  void begin(unsigned long baud) { logSerial.begin(baud); }
+
+  // Support boolean conversion for compatibility with code like:
+  //   if (Serial) or while (!Serial)
+  operator bool() const { return logSerial; }
+
+  __attribute__((deprecated("Use LOG_* macro instead"))) size_t printf(const char* format, ...);
+  size_t write(uint8_t b) override;
+  size_t write(const uint8_t* buffer, size_t size) override;
+  void flush() override;
+  static MySerialImpl instance;
+};
+
+#define Serial MySerialImpl::instance

lib/OpdsParser/OpdsParser.cpp

@@ -1,6 +1,6 @@
 #include "OpdsParser.h"
 
-#include <HardwareSerial.h>
+#include <Logging.h>
 
 #include <cstring>
 
@@ -8,7 +8,7 @@ OpdsParser::OpdsParser() {
   parser = XML_ParserCreate(nullptr);
   if (!parser) {
     errorOccured = true;
-    Serial.printf("[%lu] [OPDS] Couldn't allocate memory for parser\n", millis());
+    LOG_DBG("OPDS", "Couldn't allocate memory for parser");
   }
 }
 
@@ -42,7 +42,7 @@ size_t OpdsParser::write(const uint8_t* xmlData, const size_t length) {
     void* const buf = XML_GetBuffer(parser, chunkSize);
     if (!buf) {
       errorOccured = true;
-      Serial.printf("[%lu] [OPDS] Couldn't allocate memory for buffer\n", millis());
+      LOG_DBG("OPDS", "Couldn't allocate memory for buffer");
       XML_ParserFree(parser);
       parser = nullptr;
       return length;
@@ -53,8 +53,8 @@ size_t OpdsParser::write(const uint8_t* xmlData, const size_t length) {
 
     if (XML_ParseBuffer(parser, static_cast<int>(toRead), 0) == XML_STATUS_ERROR) {
       errorOccured = true;
-      Serial.printf("[%lu] [OPDS] Parse error at line %lu: %s\n", millis(), XML_GetCurrentLineNumber(parser),
-                    XML_ErrorString(XML_GetErrorCode(parser)));
+      LOG_DBG("OPDS", "Parse error at line %lu: %s", XML_GetCurrentLineNumber(parser),
+              XML_ErrorString(XML_GetErrorCode(parser)));
       XML_ParserFree(parser);
       parser = nullptr;
       return length;

lib/PlaceholderCover/BookIcon.h

@@ -0,0 +1,27 @@
+#pragma once
+#include <cstdint>
+
+// Book icon: 48x48, 1-bit packed (MSB first)
+// 0 = black, 1 = white (same format as Logo120.h)
+static constexpr int BOOK_ICON_WIDTH = 48;
+static constexpr int BOOK_ICON_HEIGHT = 48;
+static const uint8_t BookIcon[] = {
+    0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xfc, 0x00, 0x00, 0x00,
+    0x00, 0x1f, 0xfc, 0x00, 0x00, 0x00, 0x00, 0x1f, 0xfc, 0x1f, 0xff, 0xff, 0xff, 0x9f, 0xfc, 0x1f,
+    0xff, 0xff, 0xff, 0x9f, 0xfc, 0x1f, 0xff, 0xff, 0xff, 0x9f, 0xfc, 0x1f, 0xff, 0xff, 0xff, 0x9f,
+    0xfc, 0x1f, 0xff, 0xff, 0xff, 0x9f, 0xfc, 0x1f, 0xff, 0xff, 0xff, 0x9f, 0xfc, 0x1f, 0xff, 0xff,
+    0xff, 0x9f, 0xfc, 0x1f, 0xff, 0xff, 0xff, 0x9f, 0xfc, 0x1c, 0x00, 0x00, 0x01, 0x9f, 0xfc, 0x1f,
+    0xff, 0xff, 0xff, 0x9f, 0xfc, 0x1f, 0xff, 0xff, 0xff, 0x9f, 0xfc, 0x1f, 0xff, 0xff, 0xff, 0x9f,
+    0xfc, 0x1f, 0xff, 0xff, 0xff, 0x9f, 0xfc, 0x1f, 0xff, 0xff, 0xff, 0x9f, 0xfc, 0x1c, 0x00, 0x01,
+    0xff, 0x9f, 0xfc, 0x1f, 0xff, 0xff, 0xff, 0x9f, 0xfc, 0x1f, 0xff, 0xff, 0xff, 0x9f, 0xfc, 0x1f,
+    0xff, 0xff, 0xff, 0x9f, 0xfc, 0x1f, 0xff, 0xff, 0xff, 0x9f, 0xfc, 0x1f, 0xff, 0xff, 0xff, 0x9f,
+    0xfc, 0x1c, 0x00, 0x00, 0x1f, 0x9f, 0xfc, 0x1f, 0xff, 0xff, 0xff, 0x9f, 0xfc, 0x1f, 0xff, 0xff,
+    0xff, 0x9f, 0xfc, 0x1f, 0xff, 0xff, 0xff, 0x9f, 0xfc, 0x1f, 0xff, 0xff, 0xff, 0x9f, 0xfc, 0x1f,
+    0xff, 0xff, 0xff, 0x9f, 0xfc, 0x1f, 0xff, 0xff, 0xff, 0x9f, 0xfc, 0x1f, 0xff, 0xff, 0xff, 0x9f,
+    0xfc, 0x1f, 0xff, 0xff, 0xff, 0x9f, 0xfc, 0x1f, 0xff, 0xff, 0xff, 0x9f, 0xfc, 0x1f, 0xff, 0xff,
+    0xff, 0x9f, 0xfc, 0x1f, 0xff, 0xff, 0xff, 0x9f, 0xfc, 0x1f, 0xff, 0xff, 0xff, 0x9f, 0xfc, 0x1f,
+    0xff, 0xff, 0xff, 0x9f, 0xfc, 0x1f, 0xff, 0xff, 0xff, 0x9f, 0xfc, 0x00, 0x00, 0x00, 0x00, 0x1f,
+    0xfc, 0x00, 0x00, 0x00, 0x00, 0x1f, 0xff, 0x00, 0x00, 0x00, 0x00, 0x3f, 0xff, 0x00, 0x00, 0x00,
+    0x00, 0x3f, 0xff, 0x00, 0x00, 0x00, 0x00, 0x3f, 0xff, 0x00, 0x00, 0x00, 0x00, 0x3f, 0xff, 0xff,
+    0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
+};

lib/PlaceholderCover/PlaceholderCoverGenerator.cpp

@@ -0,0 +1,480 @@
+#include "PlaceholderCoverGenerator.h"
+
+#include <EpdFont.h>
+#include <HalStorage.h>
+#include <Logging.h>
+#include <Utf8.h>
+
+#include <algorithm>
+#include <cstring>
+#include <vector>
+
+// Include the UI fonts directly for self-contained placeholder rendering.
+// These are 1-bit bitmap fonts compiled from Ubuntu TTF.
+#include "builtinFonts/ubuntu_10_regular.h"
+#include "builtinFonts/ubuntu_12_bold.h"
+
+// Book icon bitmap (48x48 1-bit, generated by scripts/generate_book_icon.py)
+#include "BookIcon.h"
+
+namespace {
+
+// BMP writing helpers (same format as JpegToBmpConverter)
+inline void write16(Print& out, const uint16_t value) {
+  out.write(value & 0xFF);
+  out.write((value >> 8) & 0xFF);
+}
+
+inline void write32(Print& out, const uint32_t value) {
+  out.write(value & 0xFF);
+  out.write((value >> 8) & 0xFF);
+  out.write((value >> 16) & 0xFF);
+  out.write((value >> 24) & 0xFF);
+}
+
+inline void write32Signed(Print& out, const int32_t value) {
+  out.write(value & 0xFF);
+  out.write((value >> 8) & 0xFF);
+  out.write((value >> 16) & 0xFF);
+  out.write((value >> 24) & 0xFF);
+}
+
+void writeBmpHeader1bit(Print& bmpOut, const int width, const int height) {
+  const int bytesPerRow = (width + 31) / 32 * 4;
+  const int imageSize = bytesPerRow * height;
+  const uint32_t fileSize = 62 + imageSize;
+
+  // BMP File Header (14 bytes)
+  bmpOut.write('B');
+  bmpOut.write('M');
+  write32(bmpOut, fileSize);
+  write32(bmpOut, 0);   // Reserved
+  write32(bmpOut, 62);  // Offset to pixel data
+
+  // DIB Header (BITMAPINFOHEADER - 40 bytes)
+  write32(bmpOut, 40);
+  write32Signed(bmpOut, width);
+  write32Signed(bmpOut, -height);  // Negative = top-down
+  write16(bmpOut, 1);              // Color planes
+  write16(bmpOut, 1);              // Bits per pixel
+  write32(bmpOut, 0);              // BI_RGB
+  write32(bmpOut, imageSize);
+  write32(bmpOut, 2835);  // xPixelsPerMeter
+  write32(bmpOut, 2835);  // yPixelsPerMeter
+  write32(bmpOut, 2);     // colorsUsed
+  write32(bmpOut, 2);     // colorsImportant
+
+  // Palette: index 0 = black, index 1 = white
+  const uint8_t palette[8] = {
+      0x00, 0x00, 0x00, 0x00,  // Black
+      0xFF, 0xFF, 0xFF, 0x00   // White
+  };
+  for (const uint8_t b : palette) {
+    bmpOut.write(b);
+  }
+}
+
+/// 1-bit pixel buffer that can render text, icons, and shapes, then write as BMP.
+class PixelBuffer {
+ public:
+  PixelBuffer(int width, int height) : width(width), height(height) {
+    bytesPerRow = (width + 31) / 32 * 4;
+    bufferSize = bytesPerRow * height;
+    buffer = static_cast<uint8_t*>(malloc(bufferSize));
+    if (buffer) {
+      memset(buffer, 0xFF, bufferSize);  // White background
+    }
+  }
+
+  ~PixelBuffer() {
+    if (buffer) {
+      free(buffer);
+    }
+  }
+
+  bool isValid() const { return buffer != nullptr; }
+
+  /// Set a pixel to black.
+  void setBlack(int x, int y) {
+    if (x < 0 || x >= width || y < 0 || y >= height) return;
+    const int byteIndex = y * bytesPerRow + x / 8;
+    const uint8_t bitMask = 0x80 >> (x % 8);
+    buffer[byteIndex] &= ~bitMask;
+  }
+
+  /// Set a scaled "pixel" (scale x scale block) to black.
+  void setBlackScaled(int x, int y, int scale) {
+    for (int dy = 0; dy < scale; dy++) {
+      for (int dx = 0; dx < scale; dx++) {
+        setBlack(x + dx, y + dy);
+      }
+    }
+  }
+
+  /// Draw a filled rectangle in black.
+  void fillRect(int x, int y, int w, int h) {
+    for (int row = y; row < y + h && row < height; row++) {
+      for (int col = x; col < x + w && col < width; col++) {
+        setBlack(col, row);
+      }
+    }
+  }
+
+  /// Draw a rectangular border in black.
+  void drawBorder(int x, int y, int w, int h, int thickness) {
+    fillRect(x, y, w, thickness);                  // Top
+    fillRect(x, y + h - thickness, w, thickness);   // Bottom
+    fillRect(x, y, thickness, h);                   // Left
+    fillRect(x + w - thickness, y, thickness, h);   // Right
+  }
+
+  /// Draw a horizontal line in black with configurable thickness.
+  void drawHLine(int x, int y, int length, int thickness = 1) {
+    fillRect(x, y, length, thickness);
+  }
+
+  /// Render a single glyph at (cursorX, baselineY) with integer scaling. Returns advance in X (scaled).
+  int renderGlyph(const EpdFontData* font, uint32_t codepoint, int cursorX, int baselineY, int scale = 1) {
+    const EpdFont fontObj(font);
+    const EpdGlyph* glyph = fontObj.getGlyph(codepoint);
+    if (!glyph) {
+      glyph = fontObj.getGlyph(REPLACEMENT_GLYPH);
+    }
+    if (!glyph) {
+      return 0;
+    }
+
+    const uint8_t* bitmap = &font->bitmap[glyph->dataOffset];
+    const int glyphW = glyph->width;
+    const int glyphH = glyph->height;
+
+    for (int gy = 0; gy < glyphH; gy++) {
+      const int screenY = baselineY - glyph->top * scale + gy * scale;
+      for (int gx = 0; gx < glyphW; gx++) {
+        const int pixelPos = gy * glyphW + gx;
+        const int screenX = cursorX + glyph->left * scale + gx * scale;
+
+        bool isSet = false;
+        if (font->is2Bit) {
+          const uint8_t byte = bitmap[pixelPos / 4];
+          const uint8_t bitIndex = (3 - pixelPos % 4) * 2;
+          const uint8_t val = 3 - ((byte >> bitIndex) & 0x3);
+          isSet = (val < 3);
+        } else {
+          const uint8_t byte = bitmap[pixelPos / 8];
+          const uint8_t bitIndex = 7 - (pixelPos % 8);
+          isSet = ((byte >> bitIndex) & 1);
+        }
+
+        if (isSet) {
+          setBlackScaled(screenX, screenY, scale);
+        }
+      }
+    }
+
+    return glyph->advanceX * scale;
+  }
+
+  /// Render a UTF-8 string at (x, y) where y is the top of the text line, with integer scaling.
+  void drawText(const EpdFontData* font, int x, int y, const char* text, int scale = 1) {
+    const int baselineY = y + font->ascender * scale;
+    int cursorX = x;
+    uint32_t cp;
+    while ((cp = utf8NextCodepoint(reinterpret_cast<const uint8_t**>(&text)))) {
+      cursorX += renderGlyph(font, cp, cursorX, baselineY, scale);
+    }
+  }
+
+  /// Draw a 1-bit icon bitmap (MSB first, 0=black, 1=white) with integer scaling.
+  void drawIcon(const uint8_t* icon, int iconW, int iconH, int x, int y, int scale = 1) {
+    const int bytesPerIconRow = iconW / 8;
+    for (int iy = 0; iy < iconH; iy++) {
+      for (int ix = 0; ix < iconW; ix++) {
+        const int byteIdx = iy * bytesPerIconRow + ix / 8;
+        const uint8_t bitMask = 0x80 >> (ix % 8);
+        // In the icon data: 0 = black (drawn), 1 = white (skip)
+        if (!(icon[byteIdx] & bitMask)) {
+          const int sx = x + ix * scale;
+          const int sy = y + iy * scale;
+          setBlackScaled(sx, sy, scale);
+        }
+      }
+    }
+  }
+
+  /// Write the pixel buffer to a file as a 1-bit BMP.
+  bool writeBmp(Print& out) const {
+    if (!buffer) return false;
+    writeBmpHeader1bit(out, width, height);
+    out.write(buffer, bufferSize);
+    return true;
+  }
+
+  int getWidth() const { return width; }
+  int getHeight() const { return height; }
+
+ private:
+  int width;
+  int height;
+  int bytesPerRow;
+  size_t bufferSize;
+  uint8_t* buffer;
+};
+
+/// Measure the width of a UTF-8 string in pixels (at 1x scale).
+int measureTextWidth(const EpdFontData* font, const char* text) {
+  const EpdFont fontObj(font);
+  int w = 0, h = 0;
+  fontObj.getTextDimensions(text, &w, &h);
+  return w;
+}
+
+/// Get the advance width of a single character.
+int getCharAdvance(const EpdFontData* font, uint32_t cp) {
+  const EpdFont fontObj(font);
+  const EpdGlyph* glyph = fontObj.getGlyph(cp);
+  if (!glyph) return 0;
+  return glyph->advanceX;
+}
+
+/// Split a string into words (splitting on spaces).
+std::vector<std::string> splitWords(const std::string& text) {
+  std::vector<std::string> words;
+  std::string current;
+  for (size_t i = 0; i < text.size(); i++) {
+    if (text[i] == ' ') {
+      if (!current.empty()) {
+        words.push_back(current);
+        current.clear();
+      }
+    } else {
+      current += text[i];
+    }
+  }
+  if (!current.empty()) {
+    words.push_back(current);
+  }
+  return words;
+}
+
+/// Word-wrap text into lines that fit within maxWidth pixels at the given scale.
+std::vector<std::string> wrapText(const EpdFontData* font, const std::string& text, int maxWidth, int scale = 1) {
+  std::vector<std::string> lines;
+  const auto words = splitWords(text);
+  if (words.empty()) return lines;
+
+  const int spaceWidth = getCharAdvance(font, ' ') * scale;
+  std::string currentLine;
+  int currentWidth = 0;
+
+  for (const auto& word : words) {
+    const int wordWidth = measureTextWidth(font, word.c_str()) * scale;
+
+    if (currentLine.empty()) {
+      currentLine = word;
+      currentWidth = wordWidth;
+    } else if (currentWidth + spaceWidth + wordWidth <= maxWidth) {
+      currentLine += " " + word;
+      currentWidth += spaceWidth + wordWidth;
+    } else {
+      lines.push_back(currentLine);
+      currentLine = word;
+      currentWidth = wordWidth;
+    }
+  }
+
+  if (!currentLine.empty()) {
+    lines.push_back(currentLine);
+  }
+
+  return lines;
+}
+
+/// Truncate a string with "..." if it exceeds maxWidth pixels at the given scale.
+std::string truncateText(const EpdFontData* font, const std::string& text, int maxWidth, int scale = 1) {
+  if (measureTextWidth(font, text.c_str()) * scale <= maxWidth) {
+    return text;
+  }
+
+  std::string truncated = text;
+  const char* ellipsis = "...";
+  const int ellipsisWidth = measureTextWidth(font, ellipsis) * scale;
+
+  while (!truncated.empty()) {
+    utf8RemoveLastChar(truncated);
+    if (measureTextWidth(font, truncated.c_str()) * scale + ellipsisWidth <= maxWidth) {
+      return truncated + ellipsis;
+    }
+  }
+
+  return ellipsis;
+}
+
+}  // namespace
+
+bool PlaceholderCoverGenerator::generate(const std::string& outputPath, const std::string& title,
+                                         const std::string& author, int width, int height) {
+  LOG_DBG("PHC", "Generating placeholder cover %dx%d: \"%s\" by \"%s\"", width, height, title.c_str(), author.c_str());
+
+  const EpdFontData* titleFont = &ubuntu_12_bold;
+  const EpdFontData* authorFont = &ubuntu_10_regular;
+
+  PixelBuffer buf(width, height);
+  if (!buf.isValid()) {
+    LOG_ERR("PHC", "Failed to allocate %dx%d pixel buffer (%d bytes)", width, height,
+            (width + 31) / 32 * 4 * height);
+    return false;
+  }
+
+  // Proportional layout constants based on cover dimensions.
+  // The device bezel covers ~2-3px on each edge, so we pad inward from the edge.
+  const int edgePadding = std::max(3, width / 48);    // ~10px at 480w, ~3px at 136w
+  const int borderWidth = std::max(2, width / 96);     // ~5px at 480w, ~2px at 136w
+  const int innerPadding = std::max(4, width / 32);    // ~15px at 480w, ~4px at 136w
+
+  // Text scaling: 2x for full-size covers, 1x for thumbnails
+  const int titleScale = (height >= 600) ? 2 : 1;
+  const int authorScale = (height >= 600) ? 2 : 1;  // Author also larger on full covers
+  // Icon: 2x for full cover, 1x for medium thumb, skip for small
+  const int iconScale = (height >= 600) ? 2 : (height >= 350 ? 1 : 0);
+
+  // Draw border inset from edge
+  buf.drawBorder(edgePadding, edgePadding, width - 2 * edgePadding, height - 2 * edgePadding, borderWidth);
+
+  // Content area (inside border + inner padding)
+  const int contentX = edgePadding + borderWidth + innerPadding;
+  const int contentY = edgePadding + borderWidth + innerPadding;
+  const int contentW = width - 2 * contentX;
+  const int contentH = height - 2 * contentY;
+
+  if (contentW <= 0 || contentH <= 0) {
+    LOG_ERR("PHC", "Cover too small for content (%dx%d)", width, height);
+    FsFile file;
+    if (!Storage.openFileForWrite("PHC", outputPath, file)) {
+      return false;
+    }
+    buf.writeBmp(file);
+    file.close();
+    return true;
+  }
+
+  // --- Layout zones ---
+  // Title zone: top 2/3 of content area (icon + title)
+  // Author zone: bottom 1/3 of content area
+  const int titleZoneH = contentH * 2 / 3;
+  const int authorZoneH = contentH - titleZoneH;
+  const int authorZoneY = contentY + titleZoneH;
+
+  // --- Separator line at the zone boundary ---
+  const int separatorWidth = contentW / 3;
+  const int separatorX = contentX + (contentW - separatorWidth) / 2;
+  buf.drawHLine(separatorX, authorZoneY, separatorWidth);
+
+  // --- Icon dimensions (needed for title text wrapping) ---
+  const int iconW = (iconScale > 0) ? BOOK_ICON_WIDTH * iconScale : 0;
+  const int iconGap = (iconScale > 0) ? std::max(8, width / 40) : 0;  // Gap between icon and title text
+  const int titleTextW = contentW - iconW - iconGap;  // Title wraps in narrower area beside icon
+
+  // --- Prepare title text (wraps within the area to the right of the icon) ---
+  const std::string displayTitle = title.empty() ? "Untitled" : title;
+  auto titleLines = wrapText(titleFont, displayTitle, titleTextW, titleScale);
+
+  constexpr int MAX_TITLE_LINES = 5;
+  if (static_cast<int>(titleLines.size()) > MAX_TITLE_LINES) {
+    titleLines.resize(MAX_TITLE_LINES);
+    titleLines.back() = truncateText(titleFont, titleLines.back(), titleTextW, titleScale);
+  }
+
+  // --- Prepare author text (multi-line, max 3 lines) ---
+  std::vector<std::string> authorLines;
+  if (!author.empty()) {
+    authorLines = wrapText(authorFont, author, contentW, authorScale);
+    constexpr int MAX_AUTHOR_LINES = 3;
+    if (static_cast<int>(authorLines.size()) > MAX_AUTHOR_LINES) {
+      authorLines.resize(MAX_AUTHOR_LINES);
+      authorLines.back() = truncateText(authorFont, authorLines.back(), contentW, authorScale);
+    }
+  }
+
+  // --- Calculate title zone layout (icon LEFT of title) ---
+  // Tighter line spacing so 2-3 title lines fit within the icon height
+  const int titleLineH = titleFont->advanceY * titleScale * 3 / 4;
+  const int iconH = (iconScale > 0) ? BOOK_ICON_HEIGHT * iconScale : 0;
+  const int numTitleLines = static_cast<int>(titleLines.size());
+  // Visual height: distance from top of first line to bottom of last line's glyphs.
+  // Use ascender (not full advanceY) for the last line since trailing line-gap isn't visible.
+  const int titleVisualH = (numTitleLines > 0)
+                               ? (numTitleLines - 1) * titleLineH + titleFont->ascender * titleScale
+                               : 0;
+  const int titleBlockH = std::max(iconH, titleVisualH);  // Taller of icon or text
+
+  int titleStartY = contentY + (titleZoneH - titleBlockH) / 2;
+  if (titleStartY < contentY) {
+    titleStartY = contentY;
+  }
+
+  // If title fits within icon height, center it vertically against the icon.
+  // Otherwise top-align so extra lines overflow below.
+  const int iconY = titleStartY;
+  const int titleTextY = (iconH > 0 && titleVisualH <= iconH)
+                             ? titleStartY + (iconH - titleVisualH) / 2
+                             : titleStartY;
+
+  // --- Horizontal centering: measure the widest title line, then center icon+gap+text block ---
+  int maxTitleLineW = 0;
+  for (const auto& line : titleLines) {
+    const int w = measureTextWidth(titleFont, line.c_str()) * titleScale;
+    if (w > maxTitleLineW) maxTitleLineW = w;
+  }
+  const int titleBlockW = iconW + iconGap + maxTitleLineW;
+  const int titleBlockX = contentX + (contentW - titleBlockW) / 2;
+
+  // --- Draw icon ---
+  if (iconScale > 0) {
+    buf.drawIcon(BookIcon, BOOK_ICON_WIDTH, BOOK_ICON_HEIGHT, titleBlockX, iconY, iconScale);
+  }
+
+  // --- Draw title lines (to the right of the icon) ---
+  const int titleTextX = titleBlockX + iconW + iconGap;
+  int currentY = titleTextY;
+  for (const auto& line : titleLines) {
+    buf.drawText(titleFont, titleTextX, currentY, line.c_str(), titleScale);
+    currentY += titleLineH;
+  }
+
+  // --- Draw author lines (centered vertically in bottom 1/3, centered horizontally) ---
+  if (!authorLines.empty()) {
+    const int authorLineH = authorFont->advanceY * authorScale;
+    const int authorBlockH = static_cast<int>(authorLines.size()) * authorLineH;
+    int authorStartY = authorZoneY + (authorZoneH - authorBlockH) / 2;
+    if (authorStartY < authorZoneY + 4) {
+      authorStartY = authorZoneY + 4;  // Small gap below separator
+    }
+
+    for (const auto& line : authorLines) {
+      const int lineWidth = measureTextWidth(authorFont, line.c_str()) * authorScale;
+      const int lineX = contentX + (contentW - lineWidth) / 2;
+      buf.drawText(authorFont, lineX, authorStartY, line.c_str(), authorScale);
+      authorStartY += authorLineH;
+    }
+  }
+
+  // --- Write to file ---
+  FsFile file;
+  if (!Storage.openFileForWrite("PHC", outputPath, file)) {
+    LOG_ERR("PHC", "Failed to open output file: %s", outputPath.c_str());
+    return false;
+  }
+
+  const bool success = buf.writeBmp(file);
+  file.close();
+
+  if (success) {
+    LOG_DBG("PHC", "Placeholder cover written to %s", outputPath.c_str());
+  } else {
+    LOG_ERR("PHC", "Failed to write placeholder BMP");
+    Storage.remove(outputPath.c_str());
+  }
+
+  return success;
+}

lib/PlaceholderCover/PlaceholderCoverGenerator.h

@@ -0,0 +1,14 @@
+#pragma once
+
+#include <string>
+
+/// Generates simple 1-bit BMP placeholder covers with title/author text
+/// for books that have no embedded cover image.
+class PlaceholderCoverGenerator {
+ public:
+  /// Generate a placeholder cover BMP with title and author text.
+  /// The BMP is written to outputPath as a 1-bit black-and-white image.
+  /// Returns true if the file was written successfully.
+  static bool generate(const std::string& outputPath, const std::string& title, const std::string& author, int width,
+                       int height);
+};

lib/Txt/Txt.cpp

@@ -2,6 +2,7 @@
 
 #include <FsHelpers.h>
 #include <JpegToBmpConverter.h>
+#include <Logging.h>
 
 Txt::Txt(std::string path, std::string cacheBasePath)
     : filepath(std::move(path)), cacheBasePath(std::move(cacheBasePath)) {
@@ -16,13 +17,13 @@ bool Txt::load() {
   }
 
   if (!Storage.exists(filepath.c_str())) {
-    Serial.printf("[%lu] [TXT] File does not exist: %s\n", millis(), filepath.c_str());
+    LOG_ERR("TXT", "File does not exist: %s", filepath.c_str());
     return false;
   }
 
   FsFile file;
   if (!Storage.openFileForRead("TXT", filepath, file)) {
-    Serial.printf("[%lu] [TXT] Failed to open file: %s\n", millis(), filepath.c_str());
+    LOG_ERR("TXT", "Failed to open file: %s", filepath.c_str());
     return false;
   }
 
@@ -30,7 +31,7 @@ bool Txt::load() {
   file.close();
 
   loaded = true;
-  Serial.printf("[%lu] [TXT] Loaded TXT file: %s (%zu bytes)\n", millis(), filepath.c_str(), fileSize);
+  LOG_DBG("TXT", "Loaded TXT file: %s (%zu bytes)", filepath.c_str(), fileSize);
   return true;
 }
 
@@ -74,7 +75,7 @@ std::string Txt::findCoverImage() const {
   for (const auto& ext : extensions) {
     std::string coverPath = folder + "/" + baseName + ext;
     if (Storage.exists(coverPath.c_str())) {
-      Serial.printf("[%lu] [TXT] Found matching cover image: %s\n", millis(), coverPath.c_str());
+      LOG_DBG("TXT", "Found matching cover image: %s", coverPath.c_str());
       return coverPath;
     }
   }
@@ -85,7 +86,7 @@ std::string Txt::findCoverImage() const {
     for (const auto& ext : extensions) {
       std::string coverPath = folder + "/" + std::string(name) + ext;
       if (Storage.exists(coverPath.c_str())) {
-        Serial.printf("[%lu] [TXT] Found fallback cover image: %s\n", millis(), coverPath.c_str());
+        LOG_DBG("TXT", "Found fallback cover image: %s", coverPath.c_str());
         return coverPath;
       }
     }
@@ -96,6 +97,9 @@ std::string Txt::findCoverImage() const {
 
 std::string Txt::getCoverBmpPath() const { return cachePath + "/cover.bmp"; }
 
+std::string Txt::getThumbBmpPath() const { return cachePath + "/thumb_[HEIGHT].bmp"; }
+std::string Txt::getThumbBmpPath(int height) const { return cachePath + "/thumb_" + std::to_string(height) + ".bmp"; }
+
 bool Txt::generateCoverBmp() const {
   // Already generated, return true
   if (Storage.exists(getCoverBmpPath().c_str())) {
@@ -104,7 +108,7 @@ bool Txt::generateCoverBmp() const {
 
   std::string coverImagePath = findCoverImage();
   if (coverImagePath.empty()) {
-    Serial.printf("[%lu] [TXT] No cover image found for TXT file\n", millis());
+    LOG_DBG("TXT", "No cover image found for TXT file");
     return false;
   }
 
@@ -120,7 +124,7 @@ bool Txt::generateCoverBmp() const {
 
   if (isBmp) {
     // Copy BMP file to cache
-    Serial.printf("[%lu] [TXT] Copying BMP cover image to cache\n", millis());
+    LOG_DBG("TXT", "Copying BMP cover image to cache");
     FsFile src, dst;
     if (!Storage.openFileForRead("TXT", coverImagePath, src)) {
       return false;
@@ -136,13 +140,13 @@ bool Txt::generateCoverBmp() const {
     }
     src.close();
     dst.close();
-    Serial.printf("[%lu] [TXT] Copied BMP cover to cache\n", millis());
+    LOG_DBG("TXT", "Copied BMP cover to cache");
     return true;
   }
 
   if (isJpg) {
     // Convert JPG/JPEG to BMP (same approach as Epub)
-    Serial.printf("[%lu] [TXT] Generating BMP from JPG cover image\n", millis());
+    LOG_DBG("TXT", "Generating BMP from JPG cover image");
     FsFile coverJpg, coverBmp;
     if (!Storage.openFileForRead("TXT", coverImagePath, coverJpg)) {
       return false;
@@ -156,16 +160,16 @@ bool Txt::generateCoverBmp() const {
     coverBmp.close();
 
     if (!success) {
-      Serial.printf("[%lu] [TXT] Failed to generate BMP from JPG cover image\n", millis());
+      LOG_ERR("TXT", "Failed to generate BMP from JPG cover image");
       Storage.remove(getCoverBmpPath().c_str());
     } else {
-      Serial.printf("[%lu] [TXT] Generated BMP from JPG cover image\n", millis());
+      LOG_DBG("TXT", "Generated BMP from JPG cover image");
     }
     return success;
   }
 
   // PNG files are not supported (would need a PNG decoder)
-  Serial.printf("[%lu] [TXT] Cover image format not supported (only BMP/JPG/JPEG)\n", millis());
+  LOG_ERR("TXT", "Cover image format not supported (only BMP/JPG/JPEG)");
   return false;
 }
 

lib/Txt/Txt.h

@@ -28,6 +28,10 @@ class Txt {
   [[nodiscard]] bool generateCoverBmp() const;
   [[nodiscard]] std::string findCoverImage() const;
 
+  // Thumbnail paths (matching Epub/Xtc pattern for home screen covers)
+  [[nodiscard]] std::string getThumbBmpPath() const;
+  [[nodiscard]] std::string getThumbBmpPath(int height) const;
+
   // Read content from file
   [[nodiscard]] bool readContent(uint8_t* buffer, size_t offset, size_t length) const;
 };

lib/Xtc/Xtc.cpp

@@ -8,10 +8,10 @@
 #include "Xtc.h"
 
 #include <HalStorage.h>
-#include <HardwareSerial.h>
+#include <Logging.h>
 
 bool Xtc::load() {
-  Serial.printf("[%lu] [XTC] Loading XTC: %s\n", millis(), filepath.c_str());
+  LOG_DBG("XTC", "Loading XTC: %s", filepath.c_str());
 
   // Initialize parser
   parser.reset(new xtc::XtcParser());
@@ -19,28 +19,28 @@ bool Xtc::load() {
   // Open XTC file
   xtc::XtcError err = parser->open(filepath.c_str());
   if (err != xtc::XtcError::OK) {
-    Serial.printf("[%lu] [XTC] Failed to load: %s\n", millis(), xtc::errorToString(err));
+    LOG_ERR("XTC", "Failed to load: %s", xtc::errorToString(err));
     parser.reset();
     return false;
   }
 
   loaded = true;
-  Serial.printf("[%lu] [XTC] Loaded XTC: %s (%lu pages)\n", millis(), filepath.c_str(), parser->getPageCount());
+  LOG_DBG("XTC", "Loaded XTC: %s (%lu pages)", filepath.c_str(), parser->getPageCount());
   return true;
 }
 
 bool Xtc::clearCache() const {
   if (!Storage.exists(cachePath.c_str())) {
-    Serial.printf("[%lu] [XTC] Cache does not exist, no action needed\n", millis());
+    LOG_DBG("XTC", "Cache does not exist, no action needed");
     return true;
   }
 
   if (!Storage.removeDir(cachePath.c_str())) {
-    Serial.printf("[%lu] [XTC] Failed to clear cache\n", millis());
+    LOG_ERR("XTC", "Failed to clear cache");
     return false;
   }
 
-  Serial.printf("[%lu] [XTC] Cache cleared successfully\n", millis());
+  LOG_DBG("XTC", "Cache cleared successfully");
   return true;
 }
 
@@ -119,12 +119,12 @@ bool Xtc::generateCoverBmp() const {
   }
 
   if (!loaded || !parser) {
-    Serial.printf("[%lu] [XTC] Cannot generate cover BMP, file not loaded\n", millis());
+    LOG_ERR("XTC", "Cannot generate cover BMP, file not loaded");
     return false;
   }
 
   if (parser->getPageCount() == 0) {
-    Serial.printf("[%lu] [XTC] No pages in XTC file\n", millis());
+    LOG_ERR("XTC", "No pages in XTC file");
     return false;
   }
 
@@ -134,7 +134,7 @@ bool Xtc::generateCoverBmp() const {
   // Get first page info for cover
   xtc::PageInfo pageInfo;
   if (!parser->getPageInfo(0, pageInfo)) {
-    Serial.printf("[%lu] [XTC] Failed to get first page info\n", millis());
+    LOG_DBG("XTC", "Failed to get first page info");
     return false;
   }
 
@@ -152,14 +152,14 @@ bool Xtc::generateCoverBmp() const {
   }
   uint8_t* pageBuffer = static_cast<uint8_t*>(malloc(bitmapSize));
   if (!pageBuffer) {
-    Serial.printf("[%lu] [XTC] Failed to allocate page buffer (%lu bytes)\n", millis(), bitmapSize);
+    LOG_ERR("XTC", "Failed to allocate page buffer (%lu bytes)", bitmapSize);
     return false;
   }
 
   // Load first page (cover)
   size_t bytesRead = const_cast<xtc::XtcParser*>(parser.get())->loadPage(0, pageBuffer, bitmapSize);
   if (bytesRead == 0) {
-    Serial.printf("[%lu] [XTC] Failed to load cover page\n", millis());
+    LOG_ERR("XTC", "Failed to load cover page");
     free(pageBuffer);
     return false;
   }
@@ -167,7 +167,7 @@ bool Xtc::generateCoverBmp() const {
   // Create BMP file
   FsFile coverBmp;
   if (!Storage.openFileForWrite("XTC", getCoverBmpPath(), coverBmp)) {
-    Serial.printf("[%lu] [XTC] Failed to create cover BMP file\n", millis());
+    LOG_DBG("XTC", "Failed to create cover BMP file");
     free(pageBuffer);
     return false;
   }
@@ -297,7 +297,7 @@ bool Xtc::generateCoverBmp() const {
   coverBmp.close();
   free(pageBuffer);
 
-  Serial.printf("[%lu] [XTC] Generated cover BMP: %s\n", millis(), getCoverBmpPath().c_str());
+  LOG_DBG("XTC", "Generated cover BMP: %s", getCoverBmpPath().c_str());
   return true;
 }
 
@@ -311,12 +311,12 @@ bool Xtc::generateThumbBmp(int height) const {
   }
 
   if (!loaded || !parser) {
-    Serial.printf("[%lu] [XTC] Cannot generate thumb BMP, file not loaded\n", millis());
+    LOG_ERR("XTC", "Cannot generate thumb BMP, file not loaded");
     return false;
   }
 
   if (parser->getPageCount() == 0) {
-    Serial.printf("[%lu] [XTC] No pages in XTC file\n", millis());
+    LOG_ERR("XTC", "No pages in XTC file");
     return false;
   }
 
@@ -326,7 +326,7 @@ bool Xtc::generateThumbBmp(int height) const {
   // Get first page info for cover
   xtc::PageInfo pageInfo;
   if (!parser->getPageInfo(0, pageInfo)) {
-    Serial.printf("[%lu] [XTC] Failed to get first page info\n", millis());
+    LOG_DBG("XTC", "Failed to get first page info");
     return false;
   }
 
@@ -359,7 +359,7 @@ bool Xtc::generateThumbBmp(int height) const {
         }
         src.close();
       }
-      Serial.printf("[%lu] [XTC] Copied cover to thumb (no scaling needed)\n", millis());
+      LOG_DBG("XTC", "Copied cover to thumb (no scaling needed)");
       return Storage.exists(getThumbBmpPath(height).c_str());
     }
     return false;
@@ -368,8 +368,8 @@ bool Xtc::generateThumbBmp(int height) const {
   uint16_t thumbWidth = static_cast<uint16_t>(pageInfo.width * scale);
   uint16_t thumbHeight = static_cast<uint16_t>(pageInfo.height * scale);
 
-  Serial.printf("[%lu] [XTC] Generating thumb BMP: %dx%d -> %dx%d (scale: %.3f)\n", millis(), pageInfo.width,
-                pageInfo.height, thumbWidth, thumbHeight, scale);
+  LOG_DBG("XTC", "Generating thumb BMP: %dx%d -> %dx%d (scale: %.3f)", pageInfo.width, pageInfo.height, thumbWidth,
+          thumbHeight, scale);
 
   // Allocate buffer for page data
   size_t bitmapSize;
@@ -380,14 +380,14 @@ bool Xtc::generateThumbBmp(int height) const {
   }
   uint8_t* pageBuffer = static_cast<uint8_t*>(malloc(bitmapSize));
   if (!pageBuffer) {
-    Serial.printf("[%lu] [XTC] Failed to allocate page buffer (%lu bytes)\n", millis(), bitmapSize);
+    LOG_ERR("XTC", "Failed to allocate page buffer (%lu bytes)", bitmapSize);
     return false;
   }
 
   // Load first page (cover)
   size_t bytesRead = const_cast<xtc::XtcParser*>(parser.get())->loadPage(0, pageBuffer, bitmapSize);
   if (bytesRead == 0) {
-    Serial.printf("[%lu] [XTC] Failed to load cover page for thumb\n", millis());
+    LOG_ERR("XTC", "Failed to load cover page for thumb");
     free(pageBuffer);
     return false;
   }
@@ -395,7 +395,7 @@ bool Xtc::generateThumbBmp(int height) const {
   // Create thumbnail BMP file - use 1-bit format for fast home screen rendering (no gray passes)
   FsFile thumbBmp;
   if (!Storage.openFileForWrite("XTC", getThumbBmpPath(height), thumbBmp)) {
-    Serial.printf("[%lu] [XTC] Failed to create thumb BMP file\n", millis());
+    LOG_DBG("XTC", "Failed to create thumb BMP file");
     free(pageBuffer);
     return false;
   }
@@ -558,8 +558,7 @@ bool Xtc::generateThumbBmp(int height) const {
   thumbBmp.close();
   free(pageBuffer);
 
-  Serial.printf("[%lu] [XTC] Generated thumb BMP (%dx%d): %s\n", millis(), thumbWidth, thumbHeight,
-                getThumbBmpPath(height).c_str());
+  LOG_DBG("XTC", "Generated thumb BMP (%dx%d): %s", thumbWidth, thumbHeight, getThumbBmpPath(height).c_str());
   return true;
 }
 

lib/Xtc/Xtc/XtcParser.cpp

@@ -9,7 +9,7 @@
 
 #include <FsHelpers.h>
 #include <HalStorage.h>
-#include <HardwareSerial.h>
+#include <Logging.h>
 
 #include <cstring>
 
@@ -42,7 +42,7 @@ XtcError XtcParser::open(const char* filepath) {
   // Read header
   m_lastError = readHeader();
   if (m_lastError != XtcError::OK) {
-    Serial.printf("[%lu] [XTC] Failed to read header: %s\n", millis(), errorToString(m_lastError));
+    LOG_DBG("XTC", "Failed to read header: %s", errorToString(m_lastError));
     m_file.close();
     return m_lastError;
   }
@@ -51,13 +51,13 @@ XtcError XtcParser::open(const char* filepath) {
   if (m_header.hasMetadata) {
     m_lastError = readTitle();
     if (m_lastError != XtcError::OK) {
-      Serial.printf("[%lu] [XTC] Failed to read title: %s\n", millis(), errorToString(m_lastError));
+      LOG_DBG("XTC", "Failed to read title: %s", errorToString(m_lastError));
       m_file.close();
       return m_lastError;
     }
     m_lastError = readAuthor();
     if (m_lastError != XtcError::OK) {
-      Serial.printf("[%lu] [XTC] Failed to read author: %s\n", millis(), errorToString(m_lastError));
+      LOG_DBG("XTC", "Failed to read author: %s", errorToString(m_lastError));
       m_file.close();
       return m_lastError;
     }
@@ -66,7 +66,7 @@ XtcError XtcParser::open(const char* filepath) {
   // Read page table
   m_lastError = readPageTable();
   if (m_lastError != XtcError::OK) {
-    Serial.printf("[%lu] [XTC] Failed to read page table: %s\n", millis(), errorToString(m_lastError));
+    LOG_DBG("XTC", "Failed to read page table: %s", errorToString(m_lastError));
     m_file.close();
     return m_lastError;
   }
@@ -74,14 +74,13 @@ XtcError XtcParser::open(const char* filepath) {
   // Read chapters if present
   m_lastError = readChapters();
   if (m_lastError != XtcError::OK) {
-    Serial.printf("[%lu] [XTC] Failed to read chapters: %s\n", millis(), errorToString(m_lastError));
+    LOG_DBG("XTC", "Failed to read chapters: %s", errorToString(m_lastError));
     m_file.close();
     return m_lastError;
   }
 
   m_isOpen = true;
-  Serial.printf("[%lu] [XTC] Opened file: %s (%u pages, %dx%d)\n", millis(), filepath, m_header.pageCount,
-                m_defaultWidth, m_defaultHeight);
+  LOG_DBG("XTC", "Opened file: %s (%u pages, %dx%d)", filepath, m_header.pageCount, m_defaultWidth, m_defaultHeight);
   return XtcError::OK;
 }
 
@@ -106,8 +105,7 @@ XtcError XtcParser::readHeader() {
 
   // Verify magic number (accept both XTC and XTCH)
   if (m_header.magic != XTC_MAGIC && m_header.magic != XTCH_MAGIC) {
-    Serial.printf("[%lu] [XTC] Invalid magic: 0x%08X (expected 0x%08X or 0x%08X)\n", millis(), m_header.magic,
-                  XTC_MAGIC, XTCH_MAGIC);
+    LOG_DBG("XTC", "Invalid magic: 0x%08X (expected 0x%08X or 0x%08X)", m_header.magic, XTC_MAGIC, XTCH_MAGIC);
     return XtcError::INVALID_MAGIC;
   }
 
@@ -120,7 +118,7 @@ XtcError XtcParser::readHeader() {
   const bool validVersion = m_header.versionMajor == 1 && m_header.versionMinor == 0 ||
                             m_header.versionMajor == 0 && m_header.versionMinor == 1;
   if (!validVersion) {
-    Serial.printf("[%lu] [XTC] Unsupported version: %u.%u\n", millis(), m_header.versionMajor, m_header.versionMinor);
+    LOG_DBG("XTC", "Unsupported version: %u.%u", m_header.versionMajor, m_header.versionMinor);
     return XtcError::INVALID_VERSION;
   }
 
@@ -129,9 +127,9 @@ XtcError XtcParser::readHeader() {
     return XtcError::CORRUPTED_HEADER;
   }
 
-  Serial.printf("[%lu] [XTC] Header: magic=0x%08X (%s), ver=%u.%u, pages=%u, bitDepth=%u\n", millis(), m_header.magic,
-                (m_header.magic == XTCH_MAGIC) ? "XTCH" : "XTC", m_header.versionMajor, m_header.versionMinor,
-                m_header.pageCount, m_bitDepth);
+  LOG_DBG("XTC", "Header: magic=0x%08X (%s), ver=%u.%u, pages=%u, bitDepth=%u", m_header.magic,
+          (m_header.magic == XTCH_MAGIC) ? "XTCH" : "XTC", m_header.versionMajor, m_header.versionMinor,
+          m_header.pageCount, m_bitDepth);
 
   return XtcError::OK;
 }
@@ -146,7 +144,7 @@ XtcError XtcParser::readTitle() {
   m_file.read(titleBuf, sizeof(titleBuf) - 1);
   m_title = titleBuf;
 
-  Serial.printf("[%lu] [XTC] Title: %s\n", millis(), m_title.c_str());
+  LOG_DBG("XTC", "Title: %s", m_title.c_str());
   return XtcError::OK;
 }
 
@@ -161,19 +159,19 @@ XtcError XtcParser::readAuthor() {
   m_file.read(authorBuf, sizeof(authorBuf) - 1);
   m_author = authorBuf;
 
-  Serial.printf("[%lu] [XTC] Author: %s\n", millis(), m_author.c_str());
+  LOG_DBG("XTC", "Author: %s", m_author.c_str());
   return XtcError::OK;
 }
 
 XtcError XtcParser::readPageTable() {
   if (m_header.pageTableOffset == 0) {
-    Serial.printf("[%lu] [XTC] Page table offset is 0, cannot read\n", millis());
+    LOG_DBG("XTC", "Page table offset is 0, cannot read");
     return XtcError::CORRUPTED_HEADER;
   }
 
   // Seek to page table
   if (!m_file.seek(m_header.pageTableOffset)) {
-    Serial.printf("[%lu] [XTC] Failed to seek to page table at %llu\n", millis(), m_header.pageTableOffset);
+    LOG_DBG("XTC", "Failed to seek to page table at %llu", m_header.pageTableOffset);
     return XtcError::READ_ERROR;
   }
 
@@ -184,7 +182,7 @@ XtcError XtcParser::readPageTable() {
     PageTableEntry entry;
     size_t bytesRead = m_file.read(reinterpret_cast<uint8_t*>(&entry), sizeof(PageTableEntry));
     if (bytesRead != sizeof(PageTableEntry)) {
-      Serial.printf("[%lu] [XTC] Failed to read page table entry %u\n", millis(), i);
+      LOG_DBG("XTC", "Failed to read page table entry %u", i);
       return XtcError::READ_ERROR;
     }
 
@@ -201,7 +199,7 @@ XtcError XtcParser::readPageTable() {
     }
   }
 
-  Serial.printf("[%lu] [XTC] Read %u page table entries\n", millis(), m_header.pageCount);
+  LOG_DBG("XTC", "Read %u page table entries", m_header.pageCount);
   return XtcError::OK;
 }
 
@@ -307,7 +305,7 @@ XtcError XtcParser::readChapters() {
   }
 
   m_hasChapters = !m_chapters.empty();
-  Serial.printf("[%lu] [XTC] Chapters: %u\n", millis(), static_cast<unsigned int>(m_chapters.size()));
+  LOG_DBG("XTC", "Chapters: %u", static_cast<unsigned int>(m_chapters.size()));
   return XtcError::OK;
 }
 
@@ -334,7 +332,7 @@ size_t XtcParser::loadPage(uint32_t pageIndex, uint8_t* buffer, size_t bufferSiz
 
   // Seek to page data
   if (!m_file.seek(page.offset)) {
-    Serial.printf("[%lu] [XTC] Failed to seek to page %u at offset %lu\n", millis(), pageIndex, page.offset);
+    LOG_DBG("XTC", "Failed to seek to page %u at offset %lu", pageIndex, page.offset);
     m_lastError = XtcError::READ_ERROR;
     return 0;
   }
@@ -343,7 +341,7 @@ size_t XtcParser::loadPage(uint32_t pageIndex, uint8_t* buffer, size_t bufferSiz
   XtgPageHeader pageHeader;
   size_t headerRead = m_file.read(reinterpret_cast<uint8_t*>(&pageHeader), sizeof(XtgPageHeader));
   if (headerRead != sizeof(XtgPageHeader)) {
-    Serial.printf("[%lu] [XTC] Failed to read page header for page %u\n", millis(), pageIndex);
+    LOG_DBG("XTC", "Failed to read page header for page %u", pageIndex);
     m_lastError = XtcError::READ_ERROR;
     return 0;
   }
@@ -351,8 +349,8 @@ size_t XtcParser::loadPage(uint32_t pageIndex, uint8_t* buffer, size_t bufferSiz
   // Verify page magic (XTG for 1-bit, XTH for 2-bit)
   const uint32_t expectedMagic = (m_bitDepth == 2) ? XTH_MAGIC : XTG_MAGIC;
   if (pageHeader.magic != expectedMagic) {
-    Serial.printf("[%lu] [XTC] Invalid page magic for page %u: 0x%08X (expected 0x%08X)\n", millis(), pageIndex,
-                  pageHeader.magic, expectedMagic);
+    LOG_DBG("XTC", "Invalid page magic for page %u: 0x%08X (expected 0x%08X)", pageIndex, pageHeader.magic,
+            expectedMagic);
     m_lastError = XtcError::INVALID_MAGIC;
     return 0;
   }
@@ -370,7 +368,7 @@ size_t XtcParser::loadPage(uint32_t pageIndex, uint8_t* buffer, size_t bufferSiz
 
   // Check buffer size
   if (bufferSize < bitmapSize) {
-    Serial.printf("[%lu] [XTC] Buffer too small: need %u, have %u\n", millis(), bitmapSize, bufferSize);
+    LOG_DBG("XTC", "Buffer too small: need %u, have %u", bitmapSize, bufferSize);
     m_lastError = XtcError::MEMORY_ERROR;
     return 0;
   }
@@ -378,7 +376,7 @@ size_t XtcParser::loadPage(uint32_t pageIndex, uint8_t* buffer, size_t bufferSiz
   // Read bitmap data
   size_t bytesRead = m_file.read(buffer, bitmapSize);
   if (bytesRead != bitmapSize) {
-    Serial.printf("[%lu] [XTC] Page read error: expected %u, got %u\n", millis(), bitmapSize, bytesRead);
+    LOG_DBG("XTC", "Page read error: expected %u, got %u", bitmapSize, bytesRead);
     m_lastError = XtcError::READ_ERROR;
     return 0;
   }

lib/ZipFile/ZipFile.cpp

@@ -1,7 +1,7 @@
 #include "ZipFile.h"
 
 #include <HalStorage.h>
-#include <HardwareSerial.h>
+#include <Logging.h>
 #include <miniz.h>
 
 #include <algorithm>
@@ -10,7 +10,7 @@ bool inflateOneShot(const uint8_t* inputBuf, const size_t deflatedSize, uint8_t*
   // Setup inflator
   const auto inflator = static_cast<tinfl_decompressor*>(malloc(sizeof(tinfl_decompressor)));
   if (!inflator) {
-    Serial.printf("[%lu] [ZIP] Failed to allocate memory for inflator\n", millis());
+    LOG_ERR("ZIP", "Failed to allocate memory for inflator");
     return false;
   }
   memset(inflator, 0, sizeof(tinfl_decompressor));
@@ -23,7 +23,7 @@ bool inflateOneShot(const uint8_t* inputBuf, const size_t deflatedSize, uint8_t*
   free(inflator);
 
   if (status != TINFL_STATUS_DONE) {
-    Serial.printf("[%lu] [ZIP] tinfl_decompress() failed with status %d\n", millis(), status);
+    LOG_ERR("ZIP", "tinfl_decompress() failed with status %d", status);
     return false;
   }
 
@@ -195,13 +195,13 @@ long ZipFile::getDataOffset(const FileStatSlim& fileStat) {
   }
 
   if (read != localHeaderSize) {
-    Serial.printf("[%lu] [ZIP] Something went wrong reading the local header\n", millis());
+    LOG_ERR("ZIP", "Something went wrong reading the local header");
     return -1;
   }
 
   if (pLocalHeader[0] + (pLocalHeader[1] << 8) + (pLocalHeader[2] << 16) + (pLocalHeader[3] << 24) !=
       0x04034b50 /* MZ_ZIP_LOCAL_DIR_HEADER_SIG */) {
-    Serial.printf("[%lu] [ZIP] Not a valid zip file header\n", millis());
+    LOG_ERR("ZIP", "Not a valid zip file header");
     return -1;
   }
 
@@ -222,7 +222,7 @@ bool ZipFile::loadZipDetails() {
 
   const size_t fileSize = file.size();
   if (fileSize < 22) {
-    Serial.printf("[%lu] [ZIP] File too small to be a valid zip\n", millis());
+    LOG_ERR("ZIP", "File too small to be a valid zip");
     if (!wasOpen) {
       close();
     }
@@ -234,7 +234,7 @@ bool ZipFile::loadZipDetails() {
   const int scanRange = fileSize > 1024 ? 1024 : fileSize;
   const auto buffer = static_cast<uint8_t*>(malloc(scanRange));
   if (!buffer) {
-    Serial.printf("[%lu] [ZIP] Failed to allocate memory for EOCD scan buffer\n", millis());
+    LOG_ERR("ZIP", "Failed to allocate memory for EOCD scan buffer");
     if (!wasOpen) {
       close();
     }
@@ -255,7 +255,7 @@ bool ZipFile::loadZipDetails() {
   }
 
   if (foundOffset == -1) {
-    Serial.printf("[%lu] [ZIP] EOCD signature not found in zip file\n", millis());
+    LOG_ERR("ZIP", "EOCD signature not found in zip file");
     free(buffer);
     if (!wasOpen) {
       close();
@@ -407,7 +407,7 @@ uint8_t* ZipFile::readFileToMemory(const char* filename, size_t* size, const boo
   const auto dataSize = trailingNullByte ? inflatedDataSize + 1 : inflatedDataSize;
   const auto data = static_cast<uint8_t*>(malloc(dataSize));
   if (data == nullptr) {
-    Serial.printf("[%lu] [ZIP] Failed to allocate memory for output buffer (%zu bytes)\n", millis(), dataSize);
+    LOG_ERR("ZIP", "Failed to allocate memory for output buffer (%zu bytes)", dataSize);
     if (!wasOpen) {
       close();
     }
@@ -422,7 +422,7 @@ uint8_t* ZipFile::readFileToMemory(const char* filename, size_t* size, const boo
     }
 
     if (dataRead != inflatedDataSize) {
-      Serial.printf("[%lu] [ZIP] Failed to read data\n", millis());
+      LOG_ERR("ZIP", "Failed to read data");
       free(data);
       return nullptr;
     }
@@ -432,7 +432,7 @@ uint8_t* ZipFile::readFileToMemory(const char* filename, size_t* size, const boo
     // Read out deflated content from file
     const auto deflatedData = static_cast<uint8_t*>(malloc(deflatedDataSize));
     if (deflatedData == nullptr) {
-      Serial.printf("[%lu] [ZIP] Failed to allocate memory for decompression buffer\n", millis());
+      LOG_ERR("ZIP", "Failed to allocate memory for decompression buffer");
       if (!wasOpen) {
         close();
       }
@@ -445,7 +445,7 @@ uint8_t* ZipFile::readFileToMemory(const char* filename, size_t* size, const boo
     }
 
     if (dataRead != deflatedDataSize) {
-      Serial.printf("[%lu] [ZIP] Failed to read data, expected %d got %d\n", millis(), deflatedDataSize, dataRead);
+      LOG_ERR("ZIP", "Failed to read data, expected %d got %d", deflatedDataSize, dataRead);
       free(deflatedData);
       free(data);
       return nullptr;
@@ -455,14 +455,14 @@ uint8_t* ZipFile::readFileToMemory(const char* filename, size_t* size, const boo
     free(deflatedData);
 
     if (!success) {
-      Serial.printf("[%lu] [ZIP] Failed to inflate file\n", millis());
+      LOG_ERR("ZIP", "Failed to inflate file");
       free(data);
       return nullptr;
     }
 
     // Continue out of block with data set
   } else {
-    Serial.printf("[%lu] [ZIP] Unsupported compression method\n", millis());
+    LOG_ERR("ZIP", "Unsupported compression method");
     if (!wasOpen) {
       close();
     }
@@ -498,7 +498,7 @@ bool ZipFile::readFileToStream(const char* filename, Print& out, const size_t ch
     // no deflation, just read content
     const auto buffer = static_cast<uint8_t*>(malloc(chunkSize));
     if (!buffer) {
-      Serial.printf("[%lu] [ZIP] Failed to allocate memory for buffer\n", millis());
+      LOG_ERR("ZIP", "Failed to allocate memory for buffer");
       if (!wasOpen) {
         close();
       }
@@ -509,7 +509,7 @@ bool ZipFile::readFileToStream(const char* filename, Print& out, const size_t ch
     while (remaining > 0) {
       const size_t dataRead = file.read(buffer, remaining < chunkSize ? remaining : chunkSize);
       if (dataRead == 0) {
-        Serial.printf("[%lu] [ZIP] Could not read more bytes\n", millis());
+        LOG_ERR("ZIP", "Could not read more bytes");
         free(buffer);
         if (!wasOpen) {
           close();
@@ -532,7 +532,7 @@ bool ZipFile::readFileToStream(const char* filename, Print& out, const size_t ch
     // Setup inflator
     const auto inflator = static_cast<tinfl_decompressor*>(malloc(sizeof(tinfl_decompressor)));
     if (!inflator) {
-      Serial.printf("[%lu] [ZIP] Failed to allocate memory for inflator\n", millis());
+      LOG_ERR("ZIP", "Failed to allocate memory for inflator");
       if (!wasOpen) {
         close();
       }
@@ -544,7 +544,7 @@ bool ZipFile::readFileToStream(const char* filename, Print& out, const size_t ch
     // Setup file read buffer
     const auto fileReadBuffer = static_cast<uint8_t*>(malloc(chunkSize));
     if (!fileReadBuffer) {
-      Serial.printf("[%lu] [ZIP] Failed to allocate memory for zip file read buffer\n", millis());
+      LOG_ERR("ZIP", "Failed to allocate memory for zip file read buffer");
       free(inflator);
       if (!wasOpen) {
         close();
@@ -554,7 +554,7 @@ bool ZipFile::readFileToStream(const char* filename, Print& out, const size_t ch
 
     const auto outputBuffer = static_cast<uint8_t*>(malloc(TINFL_LZ_DICT_SIZE));
     if (!outputBuffer) {
-      Serial.printf("[%lu] [ZIP] Failed to allocate memory for dictionary\n", millis());
+      LOG_ERR("ZIP", "Failed to allocate memory for dictionary");
       free(inflator);
       free(fileReadBuffer);
       if (!wasOpen) {
@@ -605,7 +605,7 @@ bool ZipFile::readFileToStream(const char* filename, Print& out, const size_t ch
       if (outBytes > 0) {
         processedOutputBytes += outBytes;
         if (out.write(outputBuffer + outputCursor, outBytes) != outBytes) {
-          Serial.printf("[%lu] [ZIP] Failed to write all output bytes to stream\n", millis());
+          LOG_ERR("ZIP", "Failed to write all output bytes to stream");
           if (!wasOpen) {
             close();
           }
@@ -619,7 +619,7 @@ bool ZipFile::readFileToStream(const char* filename, Print& out, const size_t ch
       }
 
       if (status < 0) {
-        Serial.printf("[%lu] [ZIP] tinfl_decompress() failed with status %d\n", millis(), status);
+        LOG_ERR("ZIP", "tinfl_decompress() failed with status %d", status);
         if (!wasOpen) {
           close();
         }
@@ -630,8 +630,7 @@ bool ZipFile::readFileToStream(const char* filename, Print& out, const size_t ch
       }
 
       if (status == TINFL_STATUS_DONE) {
-        Serial.printf("[%lu] [ZIP] Decompressed %d bytes into %d bytes\n", millis(), deflatedDataSize,
-                      inflatedDataSize);
+        LOG_ERR("ZIP", "Decompressed %d bytes into %d bytes", deflatedDataSize, inflatedDataSize);
         if (!wasOpen) {
           close();
         }
@@ -643,7 +642,7 @@ bool ZipFile::readFileToStream(const char* filename, Print& out, const size_t ch
     }
 
     // If we get here, EOF reached without TINFL_STATUS_DONE
-    Serial.printf("[%lu] [ZIP] Unexpected EOF\n", millis());
+    LOG_ERR("ZIP", "Unexpected EOF");
     if (!wasOpen) {
       close();
     }
@@ -657,6 +656,6 @@ bool ZipFile::readFileToStream(const char* filename, Print& out, const size_t ch
     close();
   }
 
-  Serial.printf("[%lu] [ZIP] Unsupported compression method\n", millis());
+  LOG_ERR("ZIP", "Unsupported compression method");
   return false;
 }

lib/hal/HalDisplay.cpp

@@ -32,6 +32,13 @@ void HalDisplay::displayBuffer(HalDisplay::RefreshMode mode, bool turnOffScreen)
   einkDisplay.displayBuffer(convertRefreshMode(mode), turnOffScreen);
 }
 
+// EXPERIMENTAL: Display only a rectangular region
+void HalDisplay::displayWindow(uint16_t x, uint16_t y, uint16_t w, uint16_t h,
+                               HalDisplay::RefreshMode mode, bool turnOffScreen) {
+  (void)mode;  // EInkDisplay::displayWindow does not take mode yet
+  einkDisplay.displayWindow(x, y, w, h, turnOffScreen);
+}
+
 void HalDisplay::refreshDisplay(HalDisplay::RefreshMode mode, bool turnOffScreen) {
   einkDisplay.refreshDisplay(convertRefreshMode(mode), turnOffScreen);
 }

lib/hal/HalDisplay.h

@@ -34,6 +34,10 @@ class HalDisplay {
   void displayBuffer(RefreshMode mode = RefreshMode::FAST_REFRESH, bool turnOffScreen = false);
   void refreshDisplay(RefreshMode mode = RefreshMode::FAST_REFRESH, bool turnOffScreen = false);
 
+  // EXPERIMENTAL: Display only a rectangular region
+  void displayWindow(uint16_t x, uint16_t y, uint16_t w, uint16_t h,
+                     RefreshMode mode = RefreshMode::FAST_REFRESH, bool turnOffScreen = false);
+
   // Power management
   void deepSleep();
 

lib/hal/HalGPIO.cpp

@@ -1,11 +1,9 @@
 #include <HalGPIO.h>
 #include <SPI.h>
-#include <esp_sleep.h>
 
 void HalGPIO::begin() {
   inputMgr.begin();
   SPI.begin(EPD_SCLK, SPI_MISO, EPD_MOSI, EPD_CS);
-  pinMode(BAT_GPIO0, INPUT);
   pinMode(UART0_RXD, INPUT);
 }
 
@@ -23,23 +21,6 @@ bool HalGPIO::wasAnyReleased() const { return inputMgr.wasAnyReleased(); }
 
 unsigned long HalGPIO::getHeldTime() const { return inputMgr.getHeldTime(); }
 
-void HalGPIO::startDeepSleep() {
-  // Ensure that the power button has been released to avoid immediately turning back on if you're holding it
-  while (inputMgr.isPressed(BTN_POWER)) {
-    delay(50);
-    inputMgr.update();
-  }
-  // Arm the wakeup trigger *after* the button is released
-  esp_deep_sleep_enable_gpio_wakeup(1ULL << InputManager::POWER_BUTTON_PIN, ESP_GPIO_WAKEUP_GPIO_LOW);
-  // Enter Deep Sleep
-  esp_deep_sleep_start();
-}
-
-int HalGPIO::getBatteryPercentage() const {
-  static const BatteryMonitor battery = BatteryMonitor(BAT_GPIO0);
-  return battery.readPercentage();
-}
-
 bool HalGPIO::isUsbConnected() const {
   // U0RXD/GPIO20 reads HIGH when USB is connected
   return digitalRead(UART0_RXD) == HIGH;

lib/hal/HalGPIO.h

@@ -38,12 +38,6 @@ class HalGPIO {
   bool wasAnyReleased() const;
   unsigned long getHeldTime() const;
 
-  // Setup wake up GPIO and enter deep sleep
-  void startDeepSleep();
-
-  // Get battery percentage (range 0-100)
-  int getBatteryPercentage() const;
-
   // Check if USB is connected
   bool isUsbConnected() const;
 

lib/hal/HalPowerManager.cpp

@@ -0,0 +1,49 @@
+#include "HalPowerManager.h"
+
+#include <Logging.h>
+#include <esp_sleep.h>
+
+#include "HalGPIO.h"
+
+void HalPowerManager::begin() {
+  pinMode(BAT_GPIO0, INPUT);
+  normalFreq = getCpuFrequencyMhz();
+}
+
+void HalPowerManager::setPowerSaving(bool enabled) {
+  if (normalFreq <= 0) {
+    return;  // invalid state
+  }
+  if (enabled && !isLowPower) {
+    LOG_DBG("PWR", "Going to low-power mode");
+    if (!setCpuFrequencyMhz(LOW_POWER_FREQ)) {
+      LOG_DBG("PWR", "Failed to set CPU frequency = %d MHz", LOW_POWER_FREQ);
+      return;
+    }
+  }
+  if (!enabled && isLowPower) {
+    LOG_DBG("PWR", "Restoring normal CPU frequency");
+    if (!setCpuFrequencyMhz(normalFreq)) {
+      LOG_DBG("PWR", "Failed to set CPU frequency = %d MHz", normalFreq);
+      return;
+    }
+  }
+  isLowPower = enabled;
+}
+
+void HalPowerManager::startDeepSleep(HalGPIO& gpio) const {
+  // Ensure that the power button has been released to avoid immediately turning back on if you're holding it
+  while (gpio.isPressed(HalGPIO::BTN_POWER)) {
+    delay(50);
+    gpio.update();
+  }
+  // Arm the wakeup trigger *after* the button is released
+  esp_deep_sleep_enable_gpio_wakeup(1ULL << InputManager::POWER_BUTTON_PIN, ESP_GPIO_WAKEUP_GPIO_LOW);
+  // Enter Deep Sleep
+  esp_deep_sleep_start();
+}
+
+int HalPowerManager::getBatteryPercentage() const {
+  static const BatteryMonitor battery = BatteryMonitor(BAT_GPIO0);
+  return battery.readPercentage();
+}

lib/hal/HalPowerManager.h

@@ -0,0 +1,27 @@
+#pragma once
+
+#include <Arduino.h>
+#include <BatteryMonitor.h>
+#include <InputManager.h>
+
+#include "HalGPIO.h"
+
+class HalPowerManager {
+  int normalFreq = 0;  // MHz
+  bool isLowPower = false;
+
+ public:
+  static constexpr int LOW_POWER_FREQ = 10;                    // MHz
+  static constexpr unsigned long IDLE_POWER_SAVING_MS = 3000;  // ms
+
+  void begin();
+
+  // Control CPU frequency for power saving
+  void setPowerSaving(bool enabled);
+
+  // Setup wake up GPIO and enter deep sleep
+  void startDeepSleep(HalGPIO& gpio) const;
+
+  // Get battery percentage (range 0-100)
+  int getBatteryPercentage() const;
+};

platformio.ini

@@ -27,9 +27,15 @@ build_flags =
 # https://libexpat.github.io/doc/api/latest/#XML_GE
   -DXML_GE=0
   -DXML_CONTEXT_BYTES=1024
-  -std=c++2a
+  -std=gnu++2a
 # Enable UTF-8 long file names in SdFat
   -DUSE_UTF8_LONG_NAMES=1
+# Increase PNG scanline buffer to support up to 800px wide images
+# Default is (320*4+1)*2=2562, we need more for larger images
+  -DPNG_MAX_BUFFERED_PIXELS=6402
+
+build_unflags =
+  -std=gnu++11
 
 ; Board configuration
 board_build.flash_mode = dio
@@ -47,6 +53,7 @@ lib_deps =
   SDCardManager=symlink://open-x4-sdk/libs/hardware/SDCardManager
   bblanchon/ArduinoJson @ 7.4.2
   ricmoo/QRCode @ 0.0.1
+  bitbank2/PNGdec @ ^1.0.0
   links2004/WebSockets @ 2.7.3
 
 [env:default]
@@ -54,15 +61,47 @@ extends = base
 build_flags =
   ${base.build_flags}
   -DCROSSPOINT_VERSION=\"${crosspoint.version}-dev\"
+  -DENABLE_SERIAL_LOG
+  -DLOG_LEVEL=2 ; Set log level to debug for development builds
+
+
+[env:mod]
+extends = base
+extra_scripts =
+  ${base.extra_scripts}
+  pre:scripts/inject_mod_version.py
+build_flags =
+  ${base.build_flags}
+  -DOMIT_OPENDYSLEXIC
+  -DOMIT_HYPH_DE
+  -DOMIT_HYPH_ES
+  -DOMIT_HYPH_FR
+  -DOMIT_HYPH_IT
+  -DOMIT_HYPH_RU
+  -DENABLE_SERIAL_LOG
+  -DLOG_LEVEL=2 ; Set log level to debug for mod builds
 
 [env:gh_release]
 extends = base
 build_flags =
   ${base.build_flags}
   -DCROSSPOINT_VERSION=\"${crosspoint.version}\"
+  -DENABLE_SERIAL_LOG
+  -DLOG_LEVEL=0 ; Set log level to error for release builds  
 
 [env:gh_release_rc]
 extends = base
 build_flags =
   ${base.build_flags}
   -DCROSSPOINT_VERSION=\"${crosspoint.version}-rc+${sysenv.CROSSPOINT_RC_HASH}\"
+  -DENABLE_SERIAL_LOG
+  -DLOG_LEVEL=1 ; Set log level to info for release candidate builds  
+
+[env:slim]
+extends = base
+build_flags =
+  ${base.build_flags}
+  -DCROSSPOINT_VERSION=\"${crosspoint.version}-slim\"
+  ; serial output is disabled in slim builds to save space
+  -UENABLE_SERIAL_LOG
+  

scripts/build_html.py

@@ -1,5 +1,6 @@
 import os
 import re
+import gzip
 
 SRC_DIR = "src"
 
@@ -40,12 +41,34 @@ for root, _, files in os.walk(SRC_DIR):
 
             # minified = regex.sub("\g<1>", html_content)
             minified = minify_html(html_content)
+
+            # Compress with gzip (compresslevel 9 is maximum compression)
+            # IMPORTANT: we don't use brotli because Firefox doesn't support brotli with insecured context (only supported on HTTPS)
+            compressed = gzip.compress(minified.encode('utf-8'), compresslevel=9)
+
             base_name = f"{os.path.splitext(file)[0]}Html"
             header_path = os.path.join(root, f"{base_name}.generated.h")
 
             with open(header_path, "w", encoding="utf-8") as h:
                 h.write(f"// THIS FILE IS AUTOGENERATED, DO NOT EDIT MANUALLY\n\n")
                 h.write(f"#pragma once\n")
-                h.write(f'constexpr char {base_name}[] PROGMEM = R"rawliteral({minified})rawliteral";\n')
+                h.write(f"#include <cstddef>\n\n")
+
+                # Write the compressed data as a byte array
+                h.write(f"constexpr char {base_name}[] PROGMEM = {{\n")
+
+                # Write bytes in rows of 16
+                for i in range(0, len(compressed), 16):
+                    chunk = compressed[i:i+16]
+                    hex_values = ', '.join(f'0x{b:02x}' for b in chunk)
+                    h.write(f"  {hex_values},\n")
+
+                h.write(f"}};\n\n")
+                h.write(f"constexpr size_t {base_name}CompressedSize = {len(compressed)};\n")
+                h.write(f"constexpr size_t {base_name}OriginalSize = {len(minified)};\n")
 
             print(f"Generated: {header_path}")
+            print(f"  Original: {len(html_content)} bytes")
+            print(f"  Minified: {len(minified)} bytes ({100*len(minified)/len(html_content):.1f}%)")
+            print(f"  Compressed: {len(compressed)} bytes ({100*len(compressed)/len(html_content):.1f}%)")
+

scripts/debugging_monitor.py

@@ -1,32 +1,73 @@
-import sys
+#!/usr/bin/env python3
+"""
+ESP32 Serial Monitor with Memory Graph
+
+This script provides a comprehensive real-time serial monitor for ESP32 devices with
+integrated memory usage graphing capabilities. It reads serial output, parses memory
+information, and displays it in both console and graphical form.
+
+Features:
+- Real-time serial output monitoring with color-coded log levels
+- Interactive memory usage graphing with matplotlib
+- Command input interface for sending commands to the ESP32 device
+- Screenshot capture and processing (1-bit black/white format)
+- Graceful shutdown handling with Ctrl-C signal processing
+- Configurable filtering and suppression of log messages
+- Thread-safe operation with coordinated shutdown events
+
+Usage:
+    python debugging_monitor.py [port] [options]
+
+The script will open a matplotlib window showing memory usage over time and provide
+an interactive command prompt for sending commands to the device. Press Ctrl-C or
+close the graph window to exit gracefully.
+"""
+
+from __future__ import annotations
+
 import argparse
+import glob
+import platform
 import re
+import signal
+import sys
 import threading
-from datetime import datetime
 from collections import deque
-import time
+from datetime import datetime
 
 # Try to import potentially missing packages
+PACKAGE_MAPPING: dict[str, str] = {
+    "serial": "pyserial",
+    "colorama": "colorama",
+    "matplotlib": "matplotlib",
+    "PIL": "Pillow",
+}
+
 try:
-    import serial
-    from colorama import init, Fore, Style
     import matplotlib.pyplot as plt
-    import matplotlib.animation as animation
+    import serial
+    from colorama import Fore, Style, init
+    from matplotlib import animation
+
+    try:
+        from PIL import Image
+    except ImportError:
+        Image = None
 except ImportError as e:
-    missing_package = e.name
+    ERROR_MSG = str(e).lower()
+    missing_packages = [pkg for mod, pkg in PACKAGE_MAPPING.items() if mod in ERROR_MSG]
+
+    if not missing_packages:
+        # Fallback if mapping doesn't cover
+        missing_packages = ["pyserial", "colorama", "matplotlib"]
+
     print("\n" + "!" * 50)
-    print(f" Error: The required package '{missing_package}' is not installed.")
+    print(f" Error: Required package(s) not installed: {', '.join(missing_packages)}")
     print("!" * 50)
 
-    print(f"\nTo fix this, please run the following command in your terminal:\n")
-
-    install_cmd = "pip install "
-    packages = []
-    if 'serial' in str(e): packages.append("pyserial")
-    if 'colorama' in str(e): packages.append("colorama")
-    if 'matplotlib' in str(e): packages.append("matplotlib")
-
-    print(f"    {install_cmd}{' '.join(packages)}")
+    print("\nTo fix this, please run the following command in your terminal:\n")
+    INSTALL_CMD = "pip install " if sys.platform.startswith("win") else "pip3 install "
+    print(f"    {INSTALL_CMD}{' '.join(missing_packages)}")
 
     print("\nExiting...")
     sys.exit(1)
@@ -34,50 +75,104 @@ except ImportError as e:
 # --- Global Variables for Data Sharing ---
 # Store last 50 data points
 MAX_POINTS = 50
-time_data = deque(maxlen=MAX_POINTS)
-free_mem_data = deque(maxlen=MAX_POINTS)
-total_mem_data = deque(maxlen=MAX_POINTS)
-data_lock = threading.Lock() # Prevent reading while writing
+time_data: deque[str] = deque(maxlen=MAX_POINTS)
+free_mem_data: deque[float] = deque(maxlen=MAX_POINTS)
+total_mem_data: deque[float] = deque(maxlen=MAX_POINTS)
+data_lock: threading.Lock = threading.Lock()  # Prevent reading while writing
+
+# Global shutdown flag
+shutdown_event = threading.Event()
 
 # Initialize colors
 init(autoreset=True)
 
-def get_color_for_line(line):
+# Color mapping for log lines
+COLOR_KEYWORDS: dict[str, list[str]] = {
+    Fore.RED: ["ERROR", "[ERR]", "[SCT]", "FAILED", "WARNING"],
+    Fore.CYAN: ["[MEM]", "FREE:"],
+    Fore.MAGENTA: [
+        "[GFX]",
+        "[ERS]",
+        "DISPLAY",
+        "RAM WRITE",
+        "RAM COMPLETE",
+        "REFRESH",
+        "POWERING ON",
+        "FRAME BUFFER",
+        "LUT",
+    ],
+    Fore.GREEN: [
+        "[EBP]",
+        "[BMC]",
+        "[ZIP]",
+        "[PARSER]",
+        "[EHP]",
+        "LOADING EPUB",
+        "CACHE",
+        "DECOMPRESSED",
+        "PARSING",
+    ],
+    Fore.YELLOW: ["[ACT]", "ENTERING ACTIVITY", "EXITING ACTIVITY"],
+    Fore.BLUE: ["RENDERED PAGE", "[LOOP]", "DURATION", "WAIT COMPLETE"],
+    Fore.LIGHTYELLOW_EX: [
+        "[CPS]",
+        "SETTINGS",
+        "[CLEAR_CACHE]",
+        "[CHAP]",
+        "[OPDS]",
+        "[COF]",
+    ],
+    Fore.LIGHTBLACK_EX: [
+        "ESP-ROM",
+        "BUILD:",
+        "RST:",
+        "BOOT:",
+        "SPIWP:",
+        "MODE:",
+        "LOAD:",
+        "ENTRY",
+        "[SD]",
+        "STARTING CROSSPOINT",
+        "VERSION",
+    ],
+    Fore.LIGHTCYAN_EX: ["[RBS]"],
+    Fore.LIGHTMAGENTA_EX: [
+        "[KRS]",
+        "EINKDISPLAY:",
+        "STATIC FRAME",
+        "INITIALIZING",
+        "SPI INITIALIZED",
+        "GPIO PINS",
+        "RESETTING",
+        "SSD1677",
+        "E-INK",
+    ],
+    Fore.LIGHTGREEN_EX: ["[FNS]", "FOOTNOTE"],
+}
+
+
+def signal_handler(signum, frame):
+    """Handle SIGINT (Ctrl-C) by setting the shutdown event."""
+    # frame parameter is required by signal handler signature but not used
+    del frame  # Explicitly mark as unused to satisfy linters
+    print(f"\n{Fore.YELLOW}Received signal {signum}. Shutting down...{Style.RESET_ALL}")
+    shutdown_event.set()
+    plt.close("all")
+
+
+# pylint: disable=R0912
+def get_color_for_line(line: str) -> str:
     """
     Classify log lines by type and assign appropriate colors.
     """
     line_upper = line.upper()
-
-    if any(keyword in line_upper for keyword in ["ERROR", "[ERR]", "[SCT]", "FAILED", "WARNING"]):
-        return Fore.RED
-    if "[MEM]" in line_upper or "FREE:" in line_upper:
-        return Fore.CYAN
-    if any(keyword in line_upper for keyword in ["[GFX]", "[ERS]", "DISPLAY", "RAM WRITE", "RAM COMPLETE", "REFRESH", "POWERING ON", "FRAME BUFFER", "LUT"]):
-        return Fore.MAGENTA
-    if any(keyword in line_upper for keyword in ["[EBP]", "[BMC]", "[ZIP]", "[PARSER]", "[EHP]", "LOADING EPUB", "CACHE", "DECOMPRESSED", "PARSING"]):
-        return Fore.GREEN
-    if "[ACT]" in line_upper or "ENTERING ACTIVITY" in line_upper or "EXITING ACTIVITY" in line_upper:
-        return Fore.YELLOW
-    if any(keyword in line_upper for keyword in ["RENDERED PAGE", "[LOOP]", "DURATION", "WAIT COMPLETE"]):
-        return Fore.BLUE
-    if any(keyword in line_upper for keyword in ["[CPS]", "SETTINGS", "[CLEAR_CACHE]"]):
-        return Fore.LIGHTYELLOW_EX
-    if any(keyword in line_upper for keyword in ["ESP-ROM", "BUILD:", "RST:", "BOOT:", "SPIWP:", "MODE:", "LOAD:", "ENTRY", "[SD]", "STARTING CROSSPOINT", "VERSION"]):
-        return Fore.LIGHTBLACK_EX
-    if "[RBS]" in line_upper:
-        return Fore.LIGHTCYAN_EX
-    if "[KRS]" in line_upper:
-        return Fore.LIGHTMAGENTA_EX
-    if any(keyword in line_upper for keyword in ["EINKDISPLAY:", "STATIC FRAME", "INITIALIZING", "SPI INITIALIZED", "GPIO PINS", "RESETTING", "SSD1677", "E-INK"]):
-        return Fore.LIGHTMAGENTA_EX
-    if any(keyword in line_upper for keyword in ["[FNS]", "FOOTNOTE"]):
-        return Fore.LIGHTGREEN_EX
-    if any(keyword in line_upper for keyword in ["[CHAP]", "[OPDS]", "[COF]"]):
-        return Fore.LIGHTYELLOW_EX
-
+    for color, keywords in COLOR_KEYWORDS.items():
+        if any(keyword in line_upper for keyword in keywords):
+            return color
     return Fore.WHITE
 
-def parse_memory_line(line):
+
+def parse_memory_line(line: str) -> tuple[int | None, int | None]:
     """
     Extracts Free and Total bytes from the specific log line.
     Format: [MEM] Free: 196344 bytes, Total: 226412 bytes, Min Free: 112620 bytes
@@ -93,122 +188,321 @@ def parse_memory_line(line):
             return None, None
     return None, None
 
-def serial_worker(port, baud):
+
+def serial_worker(ser, kwargs: dict[str, str]) -> None:
     """
-    Runs in a background thread. Handles reading serial, printing to console,
-    and updating the data lists.
+    Runs in a background thread. Handles reading serial data, printing to console,
+    updating memory usage data for graphing, and processing screenshot data.
+    Monitors the global shutdown event for graceful termination.
     """
-    print(f"{Fore.CYAN}--- Opening {port} at {baud} baud ---{Style.RESET_ALL}")
+    print(f"{Fore.CYAN}--- Opening serial port ---{Style.RESET_ALL}")
+    filter_keyword = kwargs.get("filter", "").lower()
+    suppress = kwargs.get("suppress", "").lower()
+    if filter_keyword and suppress and filter_keyword == suppress:
+        print(
+            f"{Fore.YELLOW}Warning: Filter and Suppress keywords are the same. "
+            f"This may result in no output.{Style.RESET_ALL}"
+        )
+    if filter_keyword:
+        print(
+            f"{Fore.YELLOW}Filtering lines to only show those containing: "
+            f"'{filter_keyword}'{Style.RESET_ALL}"
+        )
+    if suppress:
+        print(
+            f"{Fore.YELLOW}Suppressing lines containing: '{suppress}'{Style.RESET_ALL}"
+        )
+
+    expecting_screenshot = False
+    screenshot_size = 0
+    screenshot_data = b""
 
     try:
-        ser = serial.Serial(port, baud, timeout=0.1)
-        ser.dtr = False
-        ser.rts = False
-    except serial.SerialException as e:
-        print(f"{Fore.RED}Error opening port: {e}{Style.RESET_ALL}")
-        return
-
-    try:
-        while True:
-            try:
-                raw_data = ser.readline().decode('utf-8', errors='replace')
-
-                if not raw_data:
+        while not shutdown_event.is_set():
+            if expecting_screenshot:
+                data = ser.read(screenshot_size - len(screenshot_data))
+                if not data:
                     continue
+                screenshot_data += data
+                if len(screenshot_data) == screenshot_size:
+                    if Image:
+                        img = Image.frombytes("1", (800, 480), screenshot_data)
+                        # We need to rotate the image because the raw data is in landscape mode
+                        img = img.transpose(Image.ROTATE_270)
+                        img.save("screenshot.bmp")
+                        print(
+                            f"{Fore.GREEN}Screenshot saved to screenshot.bmp{Style.RESET_ALL}"
+                        )
+                    else:
+                        with open("screenshot.raw", "wb") as f:
+                            f.write(screenshot_data)
+                        print(
+                            f"{Fore.GREEN}Screenshot saved to screenshot.raw (PIL not available){Style.RESET_ALL}"
+                        )
+                    expecting_screenshot = False
+                    screenshot_data = b""
+            else:
+                try:
+                    raw_data = ser.readline().decode("utf-8", errors="replace")
 
-                clean_line = raw_data.strip()
-                if not clean_line:
-                    continue
+                    if not raw_data:
+                        continue
 
-                # Add PC timestamp
-                pc_time = datetime.now().strftime("%H:%M:%S")
-                formatted_line = re.sub(r"^\[\d+\]", f"[{pc_time}]", clean_line)
+                    clean_line = raw_data.strip()
+                    if not clean_line:
+                        continue
 
-                # Check for Memory Line
-                if "[MEM]" in formatted_line:
-                    free_val, total_val = parse_memory_line(formatted_line)
-                    if free_val is not None:
-                        with data_lock:
-                            time_data.append(pc_time)
-                            free_mem_data.append(free_val / 1024) # Convert to KB
-                            total_mem_data.append(total_val / 1024) # Convert to KB
+                    if clean_line.startswith("SCREENSHOT_START:"):
+                        screenshot_size = int(clean_line.split(":")[1])
+                        expecting_screenshot = True
+                        continue
+                    elif clean_line == "SCREENSHOT_END":
+                        continue  # ignore
 
-                # Print to console
-                line_color = get_color_for_line(formatted_line)
-                print(f"{line_color}{formatted_line}")
+                    # Add PC timestamp
+                    pc_time = datetime.now().strftime("%H:%M:%S")
+                    formatted_line = re.sub(r"^\[\d+\]", f"[{pc_time}]", clean_line)
 
-            except OSError:
-                print(f"{Fore.RED}Device disconnected.{Style.RESET_ALL}")
-                break
-    except Exception as e:
+                    # Check for Memory Line
+                    if "[MEM]" in formatted_line:
+                        free_val, total_val = parse_memory_line(formatted_line)
+                        if free_val is not None and total_val is not None:
+                            with data_lock:
+                                time_data.append(pc_time)
+                                free_mem_data.append(free_val / 1024)  # Convert to KB
+                                total_mem_data.append(total_val / 1024)  # Convert to KB
+                    # Apply filters
+                    if filter_keyword and filter_keyword not in formatted_line.lower():
+                        continue
+                    if suppress and suppress in formatted_line.lower():
+                        continue
+                    # Print to console
+                    line_color = get_color_for_line(formatted_line)
+                    print(f"{line_color}{formatted_line}")
+
+                except (OSError, UnicodeDecodeError):
+                    print(
+                        f"{Fore.RED}Device disconnected or data error.{Style.RESET_ALL}"
+                    )
+                    break
+    except KeyboardInterrupt:
         # If thread is killed violently (e.g. main exit), silence errors
         pass
     finally:
-        if 'ser' in locals() and ser.is_open:
-            ser.close()
+        pass  # ser closed in main
 
-def update_graph(frame):
+
+def input_worker(ser) -> None:
     """
-    Called by Matplotlib animation to redraw the chart.
+    Runs in a background thread. Handles user input to send commands to the ESP32 device.
+    Monitors the global shutdown event for graceful termination on Ctrl-C.
     """
+    while not shutdown_event.is_set():
+        try:
+            cmd = input("Command: ")
+            ser.write(f"CMD:{cmd}\n".encode())
+        except (EOFError, KeyboardInterrupt):
+            break
+
+
+def update_graph(frame) -> list:  # pylint: disable=unused-argument
+    """
+    Called by Matplotlib animation to redraw the memory usage chart.
+    Monitors the global shutdown event and closes the plot when shutdown is requested.
+    """
+    if shutdown_event.is_set():
+        plt.close("all")
+        return []
+
     with data_lock:
         if not time_data:
-            return
+            return []
 
         # Convert deques to lists for plotting
         x = list(time_data)
         y_free = list(free_mem_data)
         y_total = list(total_mem_data)
 
-    plt.cla() # Clear axis
+    plt.cla()  # Clear axis
 
     # Plot Total RAM
-    plt.plot(x, y_total, label='Total RAM (KB)', color='red', linestyle='--')
+    plt.plot(x, y_total, label="Total RAM (KB)", color="red", linestyle="--")
 
     # Plot Free RAM
-    plt.plot(x, y_free, label='Free RAM (KB)', color='green', marker='o')
+    plt.plot(x, y_free, label="Free RAM (KB)", color="green", marker="o")
 
     # Fill area under Free RAM
-    plt.fill_between(x, y_free, color='green', alpha=0.1)
+    plt.fill_between(x, y_free, color="green", alpha=0.1)
 
     plt.title("ESP32 Memory Monitor")
     plt.ylabel("Memory (KB)")
     plt.xlabel("Time")
-    plt.legend(loc='upper left')
-    plt.grid(True, linestyle=':', alpha=0.6)
+    plt.legend(loc="upper left")
+    plt.grid(True, linestyle=":", alpha=0.6)
 
     # Rotate date labels
-    plt.xticks(rotation=45, ha='right')
+    plt.xticks(rotation=45, ha="right")
     plt.tight_layout()
 
-def main():
-    parser = argparse.ArgumentParser(description="ESP32 Monitor with Graph")
-    parser.add_argument("port", nargs="?", default="/dev/ttyACM0", help="Serial port")
-    parser.add_argument("--baud", type=int, default=115200, help="Baud rate")
+    return []
+
+
+def get_auto_detected_port() -> list[str]:
+    """
+    Attempts to auto-detect the serial port for the ESP32 device.
+    Returns a list of all detected ports.
+    If no suitable port is found, the list will be empty.
+    Darwin/Linux logic by jonasdiemer
+    """
+    port_list = []
+    system = platform.system()
+    # Code for darwin (macOS), linux, and windows
+    if system in ("Darwin", "Linux"):
+        pattern = "/dev/tty.usbmodem*" if system == "Darwin" else "/dev/ttyACM*"
+        port_list = sorted(glob.glob(pattern))
+    elif system == "Windows":
+        from serial.tools import list_ports
+
+        # Be careful with this pattern list - it should be specific
+        # enough to avoid picking up unrelated devices, but broad enough
+        # to catch all common USB-serial adapters used with ESP32
+        # Caveat: localized versions of Windows may have different descriptions,
+        # so we also check for specific VID:PID (but that may not cover all clones)
+        pattern_list = ["CP210x", "CH340", "USB Serial"]
+        found_ports = list_ports.comports()
+        port_list = [
+            port.device
+            for port in found_ports
+            if any(pat in port.description for pat in pattern_list)
+            or port.hwid.startswith(
+                "USB VID:PID=303A:1001"
+            )  # Add specific VID:PID for XTEINK X4
+        ]
+
+    return port_list
+
+
+def main() -> None:
+    """
+    Main entry point for the ESP32 monitor application.
+
+    Sets up argument parsing, initializes serial communication, starts background threads
+    for serial monitoring and command input, and launches the memory usage graph.
+    Implements graceful shutdown handling with signal processing for clean termination.
+
+    Features:
+    - Serial port monitoring with color-coded output
+    - Real-time memory usage graphing
+    - Interactive command interface
+    - Screenshot capture capability
+    - Graceful shutdown on Ctrl-C or window close
+    """
+    parser = argparse.ArgumentParser(
+        description="ESP32 Serial Monitor with Memory Graph - Real-time monitoring, graphing, and command interface"
+    )
+    default_baudrate = 115200
+    parser.add_argument(
+        "port",
+        nargs="?",
+        default=None,
+        help="Serial port (leave empty for autodetection)",
+    )
+    parser.add_argument(
+        "--baud",
+        type=int,
+        default=default_baudrate,
+        help=f"Baud rate (default: {default_baudrate})",
+    )
+    parser.add_argument(
+        "--filter",
+        type=str,
+        default="",
+        help="Only display lines containing this keyword (case-insensitive)",
+    )
+    parser.add_argument(
+        "--suppress",
+        type=str,
+        default="",
+        help="Suppress lines containing this keyword (case-insensitive)",
+    )
     args = parser.parse_args()
+    port = args.port
+    if port is None:
+        port_list = get_auto_detected_port()
+        if len(port_list) == 1:
+            port = port_list[0]
+            print(f"{Fore.CYAN}Auto-detected serial port: {port}{Style.RESET_ALL}")
+        elif len(port_list) > 1:
+            print(f"{Fore.YELLOW}Multiple serial ports found:{Style.RESET_ALL}")
+            for p in port_list:
+                print(f"  - {p}")
+            print(
+                f"{Fore.YELLOW}Please specify the desired port as a command-line argument.{Style.RESET_ALL}"
+            )
+    if port is None:
+        print(f"{Fore.RED}Error: No suitable serial port found.{Style.RESET_ALL}")
+        sys.exit(1)
+
+    try:
+        ser = serial.Serial(port, args.baud, timeout=0.1)
+        ser.dtr = False
+        ser.rts = False
+    except serial.SerialException as e:
+        print(f"{Fore.RED}Error opening port: {e}{Style.RESET_ALL}")
+        return
+
+    # Set up signal handler for graceful shutdown
+    signal.signal(signal.SIGINT, signal_handler)
 
     # 1. Start the Serial Reader in a separate thread
     # Daemon=True means this thread dies when the main program closes
-    t = threading.Thread(target=serial_worker, args=(args.port, args.baud), daemon=True)
+    myargs = vars(args)  # Convert Namespace to dict for easier passing
+    t = threading.Thread(target=serial_worker, args=(ser, myargs), daemon=True)
     t.start()
 
+    # Start input thread
+    input_thread = threading.Thread(target=input_worker, args=(ser,), daemon=True)
+    input_thread.start()
+
     # 2. Set up the Graph (Main Thread)
     try:
-        plt.style.use('light_background')
-    except:
+        import matplotlib.style as mplstyle  # pylint: disable=import-outside-toplevel
+
+        default_styles = (
+            "light_background",
+            "ggplot",
+            "seaborn",
+            "dark_background",
+        )
+        styles = list(mplstyle.available)
+        for default_style in default_styles:
+            if default_style in styles:
+                print(
+                    f"\n{Fore.CYAN}--- Using Matplotlib style: {default_style} ---{Style.RESET_ALL}"
+                )
+                mplstyle.use(default_style)
+                break
+    except (AttributeError, ValueError):
         pass
 
     fig = plt.figure(figsize=(10, 6))
 
     # Update graph every 1000ms
-    ani = animation.FuncAnimation(fig, update_graph, interval=1000)
+    _ = animation.FuncAnimation(
+        fig, update_graph, interval=1000, cache_frame_data=False
+    )
 
     try:
-        print(f"{Fore.YELLOW}Starting Graph Window... (Close window to exit){Style.RESET_ALL}")
+        print(
+            f"{Fore.YELLOW}Starting Graph Window... (Close window or press Ctrl-C to exit){Style.RESET_ALL}"
+        )
         plt.show()
     except KeyboardInterrupt:
         print(f"\n{Fore.YELLOW}Exiting...{Style.RESET_ALL}")
-        plt.close('all') # Force close any lingering plot windows
+    finally:
+        shutdown_event.set()  # Ensure all threads know to stop
+        plt.close("all")  # Force close any lingering plot windows
+
 
 if __name__ == "__main__":
     main()

scripts/generate_book_icon.py

@@ -0,0 +1,123 @@
+#!/usr/bin/env python3
+"""Generate a 1-bit book icon bitmap as a C header for PlaceholderCoverGenerator.
+
+The icon is a simplified closed book with a spine on the left and 3 text lines.
+Output format matches Logo120.h: MSB-first packed 1-bit, 0=black, 1=white.
+"""
+
+from PIL import Image, ImageDraw
+import sys
+
+
+def generate_book_icon(size=48):
+    """Create a book icon at the given size."""
+    img = Image.new("1", (size, size), 1)  # White background
+    draw = ImageDraw.Draw(img)
+
+    # Scale helper
+    s = size / 48.0
+
+    # Book body (main rectangle, leaving room for spine and pages)
+    body_left = int(6 * s)
+    body_top = int(2 * s)
+    body_right = int(42 * s)
+    body_bottom = int(40 * s)
+
+    # Draw book body outline (2px thick)
+    for i in range(int(2 * s)):
+        draw.rectangle(
+            [body_left + i, body_top + i, body_right - i, body_bottom - i], outline=0
+        )
+
+    # Spine (thicker left edge)
+    spine_width = int(4 * s)
+    draw.rectangle([body_left, body_top, body_left + spine_width, body_bottom], fill=0)
+
+    # Pages at the bottom (slight offset from body)
+    pages_top = body_bottom
+    pages_bottom = int(44 * s)
+    draw.rectangle(
+        [body_left + int(2 * s), pages_top, body_right - int(1 * s), pages_bottom],
+        outline=0,
+    )
+    # Page edges (a few lines)
+    for i in range(3):
+        y = pages_top + int((i + 1) * 1 * s)
+        if y < pages_bottom:
+            draw.line(
+                [body_left + int(3 * s), y, body_right - int(2 * s), y], fill=0
+            )
+
+    # Text lines on the book cover
+    text_left = body_left + spine_width + int(4 * s)
+    text_right = body_right - int(4 * s)
+    line_thickness = max(1, int(1.5 * s))
+
+    text_lines_y = [int(12 * s), int(18 * s), int(24 * s)]
+    text_widths = [1.0, 0.7, 0.85]  # Relative widths for visual interest
+
+    for y, w_ratio in zip(text_lines_y, text_widths):
+        line_right = text_left + int((text_right - text_left) * w_ratio)
+        for t in range(line_thickness):
+            draw.line([text_left, y + t, line_right, y + t], fill=0)
+
+    return img
+
+
+def image_to_c_array(img, name="BookIcon"):
+    """Convert a 1-bit PIL image to a C header array."""
+    width, height = img.size
+    pixels = img.load()
+
+    bytes_per_row = width // 8
+    data = []
+
+    for y in range(height):
+        for bx in range(bytes_per_row):
+            byte = 0
+            for bit in range(8):
+                x = bx * 8 + bit
+                if x < width:
+                    # 1 = white, 0 = black (matching Logo120.h convention)
+                    if pixels[x, y]:
+                        byte |= 1 << (7 - bit)
+            data.append(byte)
+
+    # Format as C header
+    lines = []
+    lines.append("#pragma once")
+    lines.append("#include <cstdint>")
+    lines.append("")
+    lines.append(f"// Book icon: {width}x{height}, 1-bit packed (MSB first)")
+    lines.append(f"// 0 = black, 1 = white (same format as Logo120.h)")
+    lines.append(f"static constexpr int BOOK_ICON_WIDTH = {width};")
+    lines.append(f"static constexpr int BOOK_ICON_HEIGHT = {height};")
+    lines.append(f"static const uint8_t {name}[] = {{")
+
+    # Format data in rows of 16 bytes
+    for i in range(0, len(data), 16):
+        chunk = data[i : i + 16]
+        hex_str = ", ".join(f"0x{b:02x}" for b in chunk)
+        lines.append(f"    {hex_str},")
+
+    lines.append("};")
+    lines.append("")
+
+    return "\n".join(lines)
+
+
+if __name__ == "__main__":
+    size = int(sys.argv[1]) if len(sys.argv) > 1 else 48
+    img = generate_book_icon(size)
+
+    # Save preview PNG
+    preview_path = f"mod/book_icon_{size}x{size}.png"
+    img.resize((size * 4, size * 4), Image.NEAREST).save(preview_path)
+    print(f"Preview saved to {preview_path}", file=sys.stderr)
+
+    # Generate C header
+    header = image_to_c_array(img, "BookIcon")
+    output_path = "lib/PlaceholderCover/BookIcon.h"
+    with open(output_path, "w") as f:
+        f.write(header)
+    print(f"C header saved to {output_path}", file=sys.stderr)

scripts/generate_test_epub.py

@@ -0,0 +1,501 @@
+#!/usr/bin/env python3
+"""
+Generate test EPUBs for image rendering verification.
+
+Creates EPUBs with annotated JPEG and PNG images to verify:
+- Grayscale rendering (4 levels)
+- Image scaling
+- Image centering
+- Cache performance
+- Page serialization
+"""
+
+import os
+import zipfile
+from pathlib import Path
+
+try:
+    from PIL import Image, ImageDraw, ImageFont
+except ImportError:
+    print("Please install Pillow: pip install Pillow")
+    exit(1)
+
+OUTPUT_DIR = Path(__file__).parent.parent / "test" / "epubs"
+SCREEN_WIDTH = 480
+SCREEN_HEIGHT = 800
+
+def get_font(size=20):
+    """Get a font, falling back to default if needed."""
+    try:
+        return ImageFont.truetype("/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf", size)
+    except:
+        try:
+            return ImageFont.truetype("/usr/share/fonts/TTF/DejaVuSans.ttf", size)
+        except:
+            return ImageFont.load_default()
+
+def draw_text_centered(draw, y, text, font, fill=0):
+    """Draw centered text at given y position."""
+    bbox = draw.textbbox((0, 0), text, font=font)
+    text_width = bbox[2] - bbox[0]
+    x = (draw.im.size[0] - text_width) // 2
+    draw.text((x, y), text, font=font, fill=fill)
+
+def draw_text_wrapped(draw, x, y, text, font, max_width, fill=0):
+    """Draw text with word wrapping."""
+    words = text.split()
+    lines = []
+    current_line = []
+
+    for word in words:
+        test_line = ' '.join(current_line + [word])
+        bbox = draw.textbbox((0, 0), test_line, font=font)
+        if bbox[2] - bbox[0] <= max_width:
+            current_line.append(word)
+        else:
+            if current_line:
+                lines.append(' '.join(current_line))
+            current_line = [word]
+    if current_line:
+        lines.append(' '.join(current_line))
+
+    line_height = font.size + 4 if hasattr(font, 'size') else 20
+    for i, line in enumerate(lines):
+        draw.text((x, y + i * line_height), line, font=font, fill=fill)
+
+    return len(lines) * line_height
+
+def create_grayscale_test_image(filename, is_png=True):
+    """
+    Create image with 4 grayscale squares to verify 4-level rendering.
+    """
+    width, height = 400, 600
+    img = Image.new('L', (width, height), 255)
+    draw = ImageDraw.Draw(img)
+    font = get_font(16)
+    font_small = get_font(14)
+
+    # Title
+    draw_text_centered(draw, 10, "GRAYSCALE TEST", font, fill=0)
+    draw_text_centered(draw, 35, "Verify 4 distinct gray levels", font_small, fill=64)
+
+    # Draw 4 grayscale squares
+    square_size = 70
+    start_y = 65
+    gap = 10
+
+    levels = [
+        (0, "Level 0: BLACK"),
+        (96, "Level 1: DARK GRAY"),
+        (160, "Level 2: LIGHT GRAY"),
+        (255, "Level 3: WHITE"),
+    ]
+
+    for i, (gray_value, label) in enumerate(levels):
+        y = start_y + i * (square_size + gap + 22)
+        x = (width - square_size) // 2
+
+        # Draw square with border
+        draw.rectangle([x-2, y-2, x + square_size + 2, y + square_size + 2], fill=0)
+        draw.rectangle([x, y, x + square_size, y + square_size], fill=gray_value)
+
+        # Label below square
+        bbox = draw.textbbox((0, 0), label, font=font_small)
+        label_width = bbox[2] - bbox[0]
+        draw.text(((width - label_width) // 2, y + square_size + 5), label, font=font_small, fill=0)
+
+    # Instructions at bottom
+    y = height - 70
+    draw_text_centered(draw, y, "PASS: 4 distinct shades visible", font_small, fill=0)
+    draw_text_centered(draw, y + 20, "FAIL: Only black/white or", font_small, fill=64)
+    draw_text_centered(draw, y + 38, "muddy/indistinct grays", font_small, fill=64)
+
+    if is_png:
+        img.save(filename, 'PNG')
+    else:
+        img.save(filename, 'JPEG', quality=95)
+
+def create_centering_test_image(filename, is_png=True):
+    """
+    Create image with border markers to verify centering.
+    """
+    width, height = 350, 400
+    img = Image.new('L', (width, height), 255)
+    draw = ImageDraw.Draw(img)
+    font = get_font(16)
+    font_small = get_font(14)
+
+    # Draw border
+    draw.rectangle([0, 0, width-1, height-1], outline=0, width=3)
+
+    # Corner markers
+    marker_size = 20
+    for x, y in [(0, 0), (width-marker_size, 0), (0, height-marker_size), (width-marker_size, height-marker_size)]:
+        draw.rectangle([x, y, x+marker_size, y+marker_size], fill=0)
+
+    # Center cross
+    cx, cy = width // 2, height // 2
+    draw.line([cx - 30, cy, cx + 30, cy], fill=0, width=2)
+    draw.line([cx, cy - 30, cx, cy + 30], fill=0, width=2)
+
+    # Title
+    draw_text_centered(draw, 40, "CENTERING TEST", font, fill=0)
+
+    # Instructions
+    y = 80
+    draw_text_centered(draw, y, "Image should be centered", font_small, fill=0)
+    draw_text_centered(draw, y + 20, "horizontally on screen", font_small, fill=0)
+
+    y = 150
+    draw_text_centered(draw, y, "Check:", font_small, fill=0)
+    draw_text_centered(draw, y + 25, "- Equal margins left & right", font_small, fill=64)
+    draw_text_centered(draw, y + 45, "- All 4 corners visible", font_small, fill=64)
+    draw_text_centered(draw, y + 65, "- Border is complete rectangle", font_small, fill=64)
+
+    # Pass/fail
+    y = height - 80
+    draw_text_centered(draw, y, "PASS: Centered, all corners visible", font_small, fill=0)
+    draw_text_centered(draw, y + 20, "FAIL: Off-center or cropped", font_small, fill=64)
+
+    if is_png:
+        img.save(filename, 'PNG')
+    else:
+        img.save(filename, 'JPEG', quality=95)
+
+def create_scaling_test_image(filename, is_png=True):
+    """
+    Create large image to verify scaling works.
+    """
+    width, height = 1200, 1500
+    img = Image.new('L', (width, height), 240)
+    draw = ImageDraw.Draw(img)
+    font = get_font(48)
+    font_medium = get_font(32)
+    font_small = get_font(24)
+
+    # Border
+    draw.rectangle([0, 0, width-1, height-1], outline=0, width=8)
+    draw.rectangle([20, 20, width-21, height-21], outline=128, width=4)
+
+    # Title
+    draw_text_centered(draw, 60, "SCALING TEST", font, fill=0)
+    draw_text_centered(draw, 130, f"Original: {width}x{height} (larger than screen)", font_medium, fill=64)
+
+    # Grid pattern
+    grid_start_y = 220
+    grid_size = 400
+    cell_size = 50
+
+    draw_text_centered(draw, grid_start_y - 40, "Grid pattern (check for artifacts):", font_small, fill=0)
+
+    grid_x = (width - grid_size) // 2
+    for row in range(grid_size // cell_size):
+        for col in range(grid_size // cell_size):
+            x = grid_x + col * cell_size
+            y = grid_start_y + row * cell_size
+            if (row + col) % 2 == 0:
+                draw.rectangle([x, y, x + cell_size, y + cell_size], fill=0)
+            else:
+                draw.rectangle([x, y, x + cell_size, y + cell_size], fill=200)
+
+    # Pass/fail
+    y = height - 100
+    draw_text_centered(draw, y, "PASS: Scaled down, readable, complete", font_small, fill=0)
+    draw_text_centered(draw, y + 30, "FAIL: Cropped, distorted, or unreadable", font_small, fill=64)
+
+    if is_png:
+        img.save(filename, 'PNG')
+    else:
+        img.save(filename, 'JPEG', quality=95)
+
+def create_cache_test_image(filename, page_num, is_png=True):
+    """
+    Create image for cache performance testing.
+    """
+    width, height = 400, 300
+    img = Image.new('L', (width, height), 255)
+    draw = ImageDraw.Draw(img)
+    font = get_font(18)
+    font_small = get_font(14)
+    font_large = get_font(36)
+
+    # Border
+    draw.rectangle([0, 0, width-1, height-1], outline=0, width=2)
+
+    # Page number prominent
+    draw_text_centered(draw, 30, f"CACHE TEST PAGE {page_num}", font, fill=0)
+    draw_text_centered(draw, 80, f"#{page_num}", font_large, fill=0)
+
+    # Instructions
+    y = 140
+    draw_text_centered(draw, y, "Navigate away then return", font_small, fill=64)
+    draw_text_centered(draw, y + 25, "Second load should be faster", font_small, fill=64)
+
+    y = 220
+    draw_text_centered(draw, y, "PASS: Faster reload from cache", font_small, fill=0)
+    draw_text_centered(draw, y + 20, "FAIL: Same slow decode each time", font_small, fill=64)
+
+    if is_png:
+        img.save(filename, 'PNG')
+    else:
+        img.save(filename, 'JPEG', quality=95)
+
+def create_format_test_image(filename, format_name, is_png=True):
+    """
+    Create simple image to verify format support.
+    """
+    width, height = 350, 250
+    img = Image.new('L', (width, height), 255)
+    draw = ImageDraw.Draw(img)
+    font = get_font(20)
+    font_large = get_font(36)
+    font_small = get_font(14)
+
+    # Border
+    draw.rectangle([0, 0, width-1, height-1], outline=0, width=3)
+
+    # Format name
+    draw_text_centered(draw, 30, f"{format_name} FORMAT TEST", font, fill=0)
+    draw_text_centered(draw, 80, format_name, font_large, fill=0)
+
+    # Checkmark area
+    y = 140
+    draw_text_centered(draw, y, "If you can read this,", font_small, fill=64)
+    draw_text_centered(draw, y + 20, f"{format_name} decoding works!", font_small, fill=64)
+
+    y = height - 40
+    draw_text_centered(draw, y, f"PASS: {format_name} image visible", font_small, fill=0)
+
+    if is_png:
+        img.save(filename, 'PNG')
+    else:
+        img.save(filename, 'JPEG', quality=95)
+
+def create_epub(epub_path, title, chapters):
+    """
+    Create an EPUB file with the given chapters.
+
+    chapters: list of (chapter_title, html_content, images)
+              images: list of (image_filename, image_data)
+    """
+    with zipfile.ZipFile(epub_path, 'w', zipfile.ZIP_DEFLATED) as epub:
+        # mimetype (must be first, uncompressed)
+        epub.writestr('mimetype', 'application/epub+zip', compress_type=zipfile.ZIP_STORED)
+
+        # Container
+        container_xml = '''<?xml version="1.0" encoding="UTF-8"?>
+<container version="1.0" xmlns="urn:oasis:names:tc:opendocument:xmlns:container">
+  <rootfiles>
+    <rootfile full-path="OEBPS/content.opf" media-type="application/oebps-package+xml"/>
+  </rootfiles>
+</container>'''
+        epub.writestr('META-INF/container.xml', container_xml)
+
+        # Collect all images and chapters
+        manifest_items = []
+        spine_items = []
+
+        # Add chapters and images
+        for i, (chapter_title, html_content, images) in enumerate(chapters):
+            chapter_id = f'chapter{i+1}'
+            chapter_file = f'chapter{i+1}.xhtml'
+
+            # Add images for this chapter
+            for img_filename, img_data in images:
+                media_type = 'image/png' if img_filename.endswith('.png') else 'image/jpeg'
+                manifest_items.append(f'    <item id="{img_filename.replace(".", "_")}" href="images/{img_filename}" media-type="{media_type}"/>')
+                epub.writestr(f'OEBPS/images/{img_filename}', img_data)
+
+            # Add chapter
+            manifest_items.append(f'    <item id="{chapter_id}" href="{chapter_file}" media-type="application/xhtml+xml"/>')
+            spine_items.append(f'    <itemref idref="{chapter_id}"/>')
+            epub.writestr(f'OEBPS/{chapter_file}', html_content)
+
+        # content.opf
+        content_opf = f'''<?xml version="1.0" encoding="UTF-8"?>
+<package xmlns="http://www.idpf.org/2007/opf" version="3.0" unique-identifier="uid">
+  <metadata xmlns:dc="http://purl.org/dc/elements/1.1/">
+    <dc:identifier id="uid">test-epub-{title.lower().replace(" ", "-")}</dc:identifier>
+    <dc:title>{title}</dc:title>
+    <dc:language>en</dc:language>
+  </metadata>
+  <manifest>
+    <item id="nav" href="nav.xhtml" media-type="application/xhtml+xml" properties="nav"/>
+{chr(10).join(manifest_items)}
+  </manifest>
+  <spine>
+{chr(10).join(spine_items)}
+  </spine>
+</package>'''
+        epub.writestr('OEBPS/content.opf', content_opf)
+
+        # Navigation document
+        nav_items = '\n'.join([f'      <li><a href="chapter{i+1}.xhtml">{chapters[i][0]}</a></li>'
+                               for i in range(len(chapters))])
+        nav_xhtml = f'''<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE html>
+<html xmlns="http://www.w3.org/1999/xhtml" xmlns:epub="http://www.idpf.org/2007/ops">
+<head><title>Navigation</title></head>
+<body>
+  <nav epub:type="toc">
+    <h1>Contents</h1>
+    <ol>
+{nav_items}
+    </ol>
+  </nav>
+</body>
+</html>'''
+        epub.writestr('OEBPS/nav.xhtml', nav_xhtml)
+
+def make_chapter(title, body_content):
+    """Create XHTML chapter content."""
+    return f'''<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE html>
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head><title>{title}</title></head>
+<body>
+<h1>{title}</h1>
+{body_content}
+</body>
+</html>'''
+
+def main():
+    OUTPUT_DIR.mkdir(exist_ok=True)
+
+    import tempfile
+    with tempfile.TemporaryDirectory() as tmpdir:
+        tmpdir = Path(tmpdir)
+
+        print("Generating test images...")
+
+        images = {}
+
+        # JPEG tests
+        create_grayscale_test_image(tmpdir / 'grayscale_test.jpg', is_png=False)
+        create_centering_test_image(tmpdir / 'centering_test.jpg', is_png=False)
+        create_scaling_test_image(tmpdir / 'scaling_test.jpg', is_png=False)
+        create_format_test_image(tmpdir / 'jpeg_format.jpg', 'JPEG', is_png=False)
+        create_cache_test_image(tmpdir / 'cache_test_1.jpg', 1, is_png=False)
+        create_cache_test_image(tmpdir / 'cache_test_2.jpg', 2, is_png=False)
+
+        # PNG tests
+        create_grayscale_test_image(tmpdir / 'grayscale_test.png', is_png=True)
+        create_centering_test_image(tmpdir / 'centering_test.png', is_png=True)
+        create_scaling_test_image(tmpdir / 'scaling_test.png', is_png=True)
+        create_format_test_image(tmpdir / 'png_format.png', 'PNG', is_png=True)
+        create_cache_test_image(tmpdir / 'cache_test_1.png', 1, is_png=True)
+        create_cache_test_image(tmpdir / 'cache_test_2.png', 2, is_png=True)
+
+        # Read all images
+        for img_file in tmpdir.glob('*.*'):
+            images[img_file.name] = img_file.read_bytes()
+
+        print("Creating JPEG test EPUB...")
+        jpeg_chapters = [
+            ("Introduction", make_chapter("JPEG Image Tests", """
+<p>This EPUB tests JPEG image rendering.</p>
+<p>Navigate through chapters to verify each test case.</p>
+"""), []),
+            ("1. JPEG Format", make_chapter("JPEG Format Test", """
+<p>Basic JPEG decoding test.</p>
+<img src="images/jpeg_format.jpg" alt="JPEG format test"/>
+<p>If the image above is visible, JPEG decoding works.</p>
+"""), [('jpeg_format.jpg', images['jpeg_format.jpg'])]),
+            ("2. Grayscale", make_chapter("Grayscale Test", """
+<p>Verify 4 distinct gray levels are visible.</p>
+<img src="images/grayscale_test.jpg" alt="Grayscale test"/>
+"""), [('grayscale_test.jpg', images['grayscale_test.jpg'])]),
+            ("3. Centering", make_chapter("Centering Test", """
+<p>Verify image is centered horizontally.</p>
+<img src="images/centering_test.jpg" alt="Centering test"/>
+"""), [('centering_test.jpg', images['centering_test.jpg'])]),
+            ("4. Scaling", make_chapter("Scaling Test", """
+<p>This image is 1200x1500 pixels - larger than the screen.</p>
+<p>It should be scaled down to fit.</p>
+<img src="images/scaling_test.jpg" alt="Scaling test"/>
+"""), [('scaling_test.jpg', images['scaling_test.jpg'])]),
+            ("5. Cache Test A", make_chapter("Cache Test - Page A", """
+<p>First cache test page. Note the load time.</p>
+<img src="images/cache_test_1.jpg" alt="Cache test 1"/>
+<p>Navigate to next page, then come back.</p>
+"""), [('cache_test_1.jpg', images['cache_test_1.jpg'])]),
+            ("6. Cache Test B", make_chapter("Cache Test - Page B", """
+<p>Second cache test page.</p>
+<img src="images/cache_test_2.jpg" alt="Cache test 2"/>
+<p>Navigate back to Page A - it should load faster from cache.</p>
+"""), [('cache_test_2.jpg', images['cache_test_2.jpg'])]),
+        ]
+
+        create_epub(OUTPUT_DIR / 'test_jpeg_images.epub', 'JPEG Image Tests', jpeg_chapters)
+
+        print("Creating PNG test EPUB...")
+        png_chapters = [
+            ("Introduction", make_chapter("PNG Image Tests", """
+<p>This EPUB tests PNG image rendering.</p>
+<p>Navigate through chapters to verify each test case.</p>
+"""), []),
+            ("1. PNG Format", make_chapter("PNG Format Test", """
+<p>Basic PNG decoding test.</p>
+<img src="images/png_format.png" alt="PNG format test"/>
+<p>If the image above is visible and no crash occurred, PNG decoding works.</p>
+"""), [('png_format.png', images['png_format.png'])]),
+            ("2. Grayscale", make_chapter("Grayscale Test", """
+<p>Verify 4 distinct gray levels are visible.</p>
+<img src="images/grayscale_test.png" alt="Grayscale test"/>
+"""), [('grayscale_test.png', images['grayscale_test.png'])]),
+            ("3. Centering", make_chapter("Centering Test", """
+<p>Verify image is centered horizontally.</p>
+<img src="images/centering_test.png" alt="Centering test"/>
+"""), [('centering_test.png', images['centering_test.png'])]),
+            ("4. Scaling", make_chapter("Scaling Test", """
+<p>This image is 1200x1500 pixels - larger than the screen.</p>
+<p>It should be scaled down to fit.</p>
+<img src="images/scaling_test.png" alt="Scaling test"/>
+"""), [('scaling_test.png', images['scaling_test.png'])]),
+            ("5. Cache Test A", make_chapter("Cache Test - Page A", """
+<p>First cache test page. Note the load time.</p>
+<img src="images/cache_test_1.png" alt="Cache test 1"/>
+<p>Navigate to next page, then come back.</p>
+"""), [('cache_test_1.png', images['cache_test_1.png'])]),
+            ("6. Cache Test B", make_chapter("Cache Test - Page B", """
+<p>Second cache test page.</p>
+<img src="images/cache_test_2.png" alt="Cache test 2"/>
+<p>Navigate back to Page A - it should load faster from cache.</p>
+"""), [('cache_test_2.png', images['cache_test_2.png'])]),
+        ]
+
+        create_epub(OUTPUT_DIR / 'test_png_images.epub', 'PNG Image Tests', png_chapters)
+
+        print("Creating mixed format test EPUB...")
+        mixed_chapters = [
+            ("Introduction", make_chapter("Mixed Image Format Tests", """
+<p>This EPUB contains both JPEG and PNG images.</p>
+<p>Tests format detection and mixed rendering.</p>
+"""), []),
+            ("1. JPEG Image", make_chapter("JPEG in Mixed EPUB", """
+<p>This is a JPEG image:</p>
+<img src="images/jpeg_format.jpg" alt="JPEG"/>
+"""), [('jpeg_format.jpg', images['jpeg_format.jpg'])]),
+            ("2. PNG Image", make_chapter("PNG in Mixed EPUB", """
+<p>This is a PNG image:</p>
+<img src="images/png_format.png" alt="PNG"/>
+"""), [('png_format.png', images['png_format.png'])]),
+            ("3. Both Formats", make_chapter("Both Formats on One Page", """
+<p>JPEG image:</p>
+<img src="images/grayscale_test.jpg" alt="JPEG grayscale"/>
+<p>PNG image:</p>
+<img src="images/grayscale_test.png" alt="PNG grayscale"/>
+<p>Both should render with proper grayscale.</p>
+"""), [('grayscale_test.jpg', images['grayscale_test.jpg']),
+       ('grayscale_test.png', images['grayscale_test.png'])]),
+        ]
+
+        create_epub(OUTPUT_DIR / 'test_mixed_images.epub', 'Mixed Format Tests', mixed_chapters)
+
+        print(f"\nTest EPUBs created in: {OUTPUT_DIR}")
+        print("Files:")
+        for f in OUTPUT_DIR.glob('*.epub'):
+            print(f"  - {f.name}")
+
+if __name__ == '__main__':
+    main()

scripts/inject_mod_version.py

@@ -0,0 +1,15 @@
+Import("env")
+import subprocess
+
+config = env.GetProjectConfig()
+version = config.get("crosspoint", "version")
+
+result = subprocess.run(
+    ["git", "rev-parse", "--short", "HEAD"],
+    capture_output=True, text=True
+)
+git_hash = result.stdout.strip()
+
+env.Append(
+    BUILD_FLAGS=[f'-DCROSSPOINT_VERSION=\\"{version}-mod+{git_hash}\\"']
+)

scripts/preview_placeholder_cover.py

@@ -0,0 +1,179 @@
+#!/usr/bin/env python3
+"""Generate a preview of the placeholder cover layout at full cover size (480x800).
+This mirrors the C++ PlaceholderCoverGenerator layout logic for visual verification.
+"""
+
+from PIL import Image, ImageDraw, ImageFont
+import sys
+import os
+
+# Reuse the book icon generator
+sys.path.insert(0, os.path.dirname(__file__))
+from generate_book_icon import generate_book_icon
+
+
+def create_preview(width=480, height=800, title="The Great Gatsby", author="F. Scott Fitzgerald"):
+    img = Image.new("1", (width, height), 1)  # White
+    draw = ImageDraw.Draw(img)
+
+    # Proportional layout constants
+    edge_padding = max(3, width // 48)      # ~10px at 480w
+    border_width = max(2, width // 96)      # ~5px at 480w
+    inner_padding = max(4, width // 32)     # ~15px at 480w
+
+    title_scale = 2 if height >= 600 else 1
+    author_scale = 2 if height >= 600 else 1  # Author also larger on full covers
+    icon_scale = 2 if height >= 600 else (1 if height >= 350 else 0)
+
+    # Draw border inset from edge
+    bx = edge_padding
+    by = edge_padding
+    bw = width - 2 * edge_padding
+    bh = height - 2 * edge_padding
+    for i in range(border_width):
+        draw.rectangle([bx + i, by + i, bx + bw - 1 - i, by + bh - 1 - i], outline=0)
+
+    # Content area
+    content_x = edge_padding + border_width + inner_padding
+    content_y = edge_padding + border_width + inner_padding
+    content_w = width - 2 * content_x
+    content_h = height - 2 * content_y
+
+    # Zones
+    title_zone_h = content_h * 2 // 3
+    author_zone_h = content_h - title_zone_h
+    author_zone_y = content_y + title_zone_h
+
+    # Separator
+    sep_w = content_w // 3
+    sep_x = content_x + (content_w - sep_w) // 2
+    draw.line([sep_x, author_zone_y, sep_x + sep_w, author_zone_y], fill=0)
+
+    # Use a basic font for the preview (won't match exact Ubuntu metrics, but shows layout)
+    try:
+        title_font = ImageFont.truetype("/System/Library/Fonts/Helvetica.ttc", 12 * title_scale)
+        author_font = ImageFont.truetype("/System/Library/Fonts/Helvetica.ttc", 10 * author_scale)
+    except (OSError, IOError):
+        title_font = ImageFont.load_default()
+        author_font = ImageFont.load_default()
+
+    # Icon dimensions (needed for title text wrapping)
+    icon_w_px = 48 * icon_scale if icon_scale > 0 else 0
+    icon_h_px = 48 * icon_scale if icon_scale > 0 else 0
+    icon_gap = max(8, width // 40) if icon_scale > 0 else 0
+    title_text_w = content_w - icon_w_px - icon_gap  # Title wraps in narrower area beside icon
+
+    # Wrap title (within the narrower area to the right of the icon)
+    title_lines = []
+    words = title.split()
+    current_line = ""
+    for word in words:
+        test = f"{current_line} {word}".strip()
+        bbox = draw.textbbox((0, 0), test, font=title_font)
+        if bbox[2] - bbox[0] <= title_text_w:
+            current_line = test
+        else:
+            if current_line:
+                title_lines.append(current_line)
+            current_line = word
+    if current_line:
+        title_lines.append(current_line)
+    title_lines = title_lines[:5]
+
+    # Line spacing: 75% of advanceY (tighter so 2-3 lines fit within icon height)
+    title_line_h = 29 * title_scale * 3 // 4  # Based on C++ ubuntu_12_bold advanceY
+
+    # Measure actual single-line height from the PIL font for accurate centering
+    sample_bbox = draw.textbbox((0, 0), "Ag", font=title_font)  # Tall + descender chars
+    single_line_visual_h = sample_bbox[3] - sample_bbox[1]
+
+    # Visual height: line spacing between lines + actual height of last line's glyphs
+    num_title_lines = len(title_lines)
+    title_visual_h = (num_title_lines - 1) * title_line_h + single_line_visual_h if num_title_lines > 0 else 0
+    title_block_h = max(icon_h_px, title_visual_h)
+
+    title_start_y = content_y + (title_zone_h - title_block_h) // 2
+    if title_start_y < content_y:
+        title_start_y = content_y
+
+    # If title fits within icon height, center it vertically against the icon.
+    # Otherwise top-align so extra lines overflow below.
+    icon_y = title_start_y
+    if icon_h_px > 0 and title_visual_h <= icon_h_px:
+        title_text_y = title_start_y + (icon_h_px - title_visual_h) // 2
+    else:
+        title_text_y = title_start_y
+
+    # Horizontal centering: measure widest title line, center icon+gap+text block
+    max_title_line_w = 0
+    for line in title_lines:
+        bbox = draw.textbbox((0, 0), line, font=title_font)
+        w = bbox[2] - bbox[0]
+        if w > max_title_line_w:
+            max_title_line_w = w
+    title_block_w = icon_w_px + icon_gap + max_title_line_w
+    title_block_x = content_x + (content_w - title_block_w) // 2
+
+    # Draw icon
+    if icon_scale > 0:
+        icon_img = generate_book_icon(48)
+        scaled_icon = icon_img.resize((icon_w_px, icon_h_px), Image.NEAREST)
+        for iy in range(scaled_icon.height):
+            for ix in range(scaled_icon.width):
+                if not scaled_icon.getpixel((ix, iy)):
+                    img.putpixel((title_block_x + ix, icon_y + iy), 0)
+
+    # Draw title (to the right of the icon)
+    title_text_x = title_block_x + icon_w_px + icon_gap
+    current_y = title_text_y
+    for line in title_lines:
+        draw.text((title_text_x, current_y), line, fill=0, font=title_font)
+        current_y += title_line_h
+
+    # Wrap author
+    author_lines = []
+    words = author.split()
+    current_line = ""
+    for word in words:
+        test = f"{current_line} {word}".strip()
+        bbox = draw.textbbox((0, 0), test, font=author_font)
+        if bbox[2] - bbox[0] <= content_w:
+            current_line = test
+        else:
+            if current_line:
+                author_lines.append(current_line)
+            current_line = word
+    if current_line:
+        author_lines.append(current_line)
+    author_lines = author_lines[:3]
+
+    # Draw author centered in bottom 1/3
+    author_line_h = 24 * author_scale  # Ubuntu 10 regular advanceY ~24
+    author_block_h = len(author_lines) * author_line_h
+    author_start_y = author_zone_y + (author_zone_h - author_block_h) // 2
+
+    for line in author_lines:
+        bbox = draw.textbbox((0, 0), line, font=author_font)
+        line_w = bbox[2] - bbox[0]
+        line_x = content_x + (content_w - line_w) // 2
+        draw.text((line_x, author_start_y), line, fill=0, font=author_font)
+        author_start_y += author_line_h
+
+    return img
+
+
+if __name__ == "__main__":
+    # Full cover
+    img = create_preview(480, 800, "A Really Long Book Title That Should Wrap", "Jane Doe")
+    img.save("mod/preview_cover_480x800.png")
+    print("Saved mod/preview_cover_480x800.png", file=sys.stderr)
+
+    # Medium thumbnail
+    img2 = create_preview(240, 400, "A Really Long Book Title That Should Wrap", "Jane Doe")
+    img2.save("mod/preview_thumb_240x400.png")
+    print("Saved mod/preview_thumb_240x400.png", file=sys.stderr)
+
+    # Small thumbnail
+    img3 = create_preview(136, 226, "A Really Long Book Title", "Jane Doe")
+    img3.save("mod/preview_thumb_136x226.png")
+    print("Saved mod/preview_thumb_136x226.png", file=sys.stderr)

src/CrossPointSettings.cpp

@@ -1,7 +1,7 @@
 #include "CrossPointSettings.h"
 
 #include <HalStorage.h>
-#include <HardwareSerial.h>
+#include <Logging.h>
 #include <Serialization.h>
 
 #include <cstring>
@@ -22,7 +22,7 @@ void readAndValidate(FsFile& file, uint8_t& member, const uint8_t maxValue) {
 namespace {
 constexpr uint8_t SETTINGS_FILE_VERSION = 1;
 // Increment this when adding new persisted settings fields
-constexpr uint8_t SETTINGS_COUNT = 32;
+constexpr uint8_t SETTINGS_COUNT = 31;
 constexpr char SETTINGS_FILE[] = "/.crosspoint/settings.bin";
 
 // Validate front button mapping to ensure each hardware button is unique.
@@ -119,11 +119,10 @@ bool CrossPointSettings::saveToFile() const {
   serialization::writePod(outputFile, fadingFix);
   serialization::writePod(outputFile, embeddedStyle);
   serialization::writePod(outputFile, sleepScreenLetterboxFill);
-  serialization::writePod(outputFile, sleepScreenGradientDir);
   // New fields added at end for backward compatibility
   outputFile.close();
 
-  Serial.printf("[%lu] [CPS] Settings saved to file\n", millis());
+  LOG_DBG("CPS", "Settings saved to file");
   return true;
 }
 
@@ -136,7 +135,7 @@ bool CrossPointSettings::loadFromFile() {
   uint8_t version;
   serialization::readPod(inputFile, version);
   if (version != SETTINGS_FILE_VERSION) {
-    Serial.printf("[%lu] [CPS] Deserialization failed: Unknown version %u\n", millis(), version);
+    LOG_ERR("CPS", "Deserialization failed: Unknown version %u", version);
     inputFile.close();
     return false;
   }
@@ -227,7 +226,7 @@ bool CrossPointSettings::loadFromFile() {
     if (++settingsRead >= fileSettingsCount) break;
     readAndValidate(inputFile, sleepScreenLetterboxFill, SLEEP_SCREEN_LETTERBOX_FILL_COUNT);
     if (++settingsRead >= fileSettingsCount) break;
-    readAndValidate(inputFile, sleepScreenGradientDir, SLEEP_SCREEN_GRADIENT_DIR_COUNT);
+    { uint8_t _ignore; serialization::readPod(inputFile, _ignore); }  // legacy: sleepScreenGradientDir
     if (++settingsRead >= fileSettingsCount) break;
     // New fields added at end for backward compatibility
   } while (false);
@@ -239,14 +238,14 @@ bool CrossPointSettings::loadFromFile() {
   }
 
   inputFile.close();
-  Serial.printf("[%lu] [CPS] Settings loaded from file\n", millis());
+  LOG_DBG("CPS", "Settings loaded from file");
   return true;
 }
 
 float CrossPointSettings::getReaderLineCompression() const {
   switch (fontFamily) {
+#ifndef OMIT_BOOKERLY
     case BOOKERLY:
-    default:
       switch (lineSpacing) {
         case TIGHT:
           return 0.95f;
@@ -256,6 +255,8 @@ float CrossPointSettings::getReaderLineCompression() const {
         case WIDE:
           return 1.1f;
       }
+#endif  // OMIT_BOOKERLY
+#ifndef OMIT_NOTOSANS
     case NOTOSANS:
       switch (lineSpacing) {
         case TIGHT:
@@ -266,6 +267,8 @@ float CrossPointSettings::getReaderLineCompression() const {
         case WIDE:
           return 1.0f;
       }
+#endif  // OMIT_NOTOSANS
+#ifndef OMIT_OPENDYSLEXIC
     case OPENDYSLEXIC:
       switch (lineSpacing) {
         case TIGHT:
@@ -276,6 +279,30 @@ float CrossPointSettings::getReaderLineCompression() const {
         case WIDE:
           return 1.0f;
       }
+#endif  // OMIT_OPENDYSLEXIC
+    default:
+      // Fallback: use Bookerly-style compression, or Noto Sans if Bookerly is omitted
+#if !defined(OMIT_BOOKERLY)
+      switch (lineSpacing) {
+        case TIGHT:
+          return 0.95f;
+        case NORMAL:
+        default:
+          return 1.0f;
+        case WIDE:
+          return 1.1f;
+      }
+#else
+      switch (lineSpacing) {
+        case TIGHT:
+          return 0.90f;
+        case NORMAL:
+        default:
+          return 0.95f;
+        case WIDE:
+          return 1.0f;
+      }
+#endif
   }
 }
 
@@ -313,8 +340,8 @@ int CrossPointSettings::getRefreshFrequency() const {
 
 int CrossPointSettings::getReaderFontId() const {
   switch (fontFamily) {
+#ifndef OMIT_BOOKERLY
     case BOOKERLY:
-    default:
       switch (fontSize) {
         case SMALL:
           return BOOKERLY_12_FONT_ID;
@@ -326,6 +353,8 @@ int CrossPointSettings::getReaderFontId() const {
         case EXTRA_LARGE:
           return BOOKERLY_18_FONT_ID;
       }
+#endif  // OMIT_BOOKERLY
+#ifndef OMIT_NOTOSANS
     case NOTOSANS:
       switch (fontSize) {
         case SMALL:
@@ -338,6 +367,8 @@ int CrossPointSettings::getReaderFontId() const {
         case EXTRA_LARGE:
           return NOTOSANS_18_FONT_ID;
       }
+#endif  // OMIT_NOTOSANS
+#ifndef OMIT_OPENDYSLEXIC
     case OPENDYSLEXIC:
       switch (fontSize) {
         case SMALL:
@@ -350,5 +381,17 @@ int CrossPointSettings::getReaderFontId() const {
         case EXTRA_LARGE:
           return OPENDYSLEXIC_14_FONT_ID;
       }
+#endif  // OMIT_OPENDYSLEXIC
+    default:
+      // Fallback to first available font family at medium size
+#if !defined(OMIT_BOOKERLY)
+      return BOOKERLY_14_FONT_ID;
+#elif !defined(OMIT_NOTOSANS)
+      return NOTOSANS_14_FONT_ID;
+#elif !defined(OMIT_OPENDYSLEXIC)
+      return OPENDYSLEXIC_10_FONT_ID;
+#else
+#error "At least one font family must be available"
+#endif
   }
 }

src/CrossPointSettings.h

@@ -32,13 +32,11 @@ class CrossPointSettings {
     SLEEP_SCREEN_COVER_FILTER_COUNT
   };
   enum SLEEP_SCREEN_LETTERBOX_FILL {
-    LETTERBOX_NONE = 0,
+    LETTERBOX_DITHERED = 0,
     LETTERBOX_SOLID = 1,
-    LETTERBOX_BLENDED = 2,
-    LETTERBOX_GRADIENT = 3,
+    LETTERBOX_NONE = 2,
     SLEEP_SCREEN_LETTERBOX_FILL_COUNT
   };
-  enum SLEEP_SCREEN_GRADIENT_DIR { GRADIENT_TO_WHITE = 0, GRADIENT_TO_BLACK = 1, SLEEP_SCREEN_GRADIENT_DIR_COUNT };
 
   // Status bar display type enum
   enum STATUS_BAR_MODE {
@@ -133,10 +131,8 @@ class CrossPointSettings {
   uint8_t sleepScreenCoverMode = FIT;
   // Sleep screen cover filter
   uint8_t sleepScreenCoverFilter = NO_FILTER;
-  // Sleep screen letterbox fill mode (None / Solid / Blended / Gradient)
-  uint8_t sleepScreenLetterboxFill = LETTERBOX_GRADIENT;
-  // Sleep screen gradient direction (towards white or black)
-  uint8_t sleepScreenGradientDir = GRADIENT_TO_WHITE;
+  // Sleep screen letterbox fill mode (Dithered / Solid / None)
+  uint8_t sleepScreenLetterboxFill = LETTERBOX_DITHERED;
   // Status bar settings
   uint8_t statusBar = FULL;
   // Text rendering settings

src/CrossPointState.cpp

@@ -1,7 +1,7 @@
 #include "CrossPointState.h"
 
 #include <HalStorage.h>
-#include <HardwareSerial.h>
+#include <Logging.h>
 #include <Serialization.h>
 
 namespace {
@@ -35,7 +35,7 @@ bool CrossPointState::loadFromFile() {
   uint8_t version;
   serialization::readPod(inputFile, version);
   if (version > STATE_FILE_VERSION) {
-    Serial.printf("[%lu] [CPS] Deserialization failed: Unknown version %u\n", millis(), version);
+    LOG_ERR("CPS", "Deserialization failed: Unknown version %u", version);
     inputFile.close();
     return false;
   }

src/MappedInputManager.h

@@ -15,6 +15,7 @@ class MappedInputManager {
 
   explicit MappedInputManager(HalGPIO& gpio) : gpio(gpio) {}
 
+  void update() const { gpio.update(); }
   bool wasPressed(Button button) const;
   bool wasReleased(Button button) const;
   bool isPressed(Button button) const;

src/RecentBooksStore.cpp

@@ -2,7 +2,7 @@
 
 #include <Epub.h>
 #include <HalStorage.h>
-#include <HardwareSerial.h>
+#include <Logging.h>
 #include <Serialization.h>
 #include <Xtc.h>
 
@@ -38,6 +38,15 @@ void RecentBooksStore::addBook(const std::string& path, const std::string& title
   saveToFile();
 }
 
+void RecentBooksStore::removeBook(const std::string& path) {
+  auto it =
+      std::find_if(recentBooks.begin(), recentBooks.end(), [&](const RecentBook& book) { return book.path == path; });
+  if (it != recentBooks.end()) {
+    recentBooks.erase(it);
+    saveToFile();
+  }
+}
+
 void RecentBooksStore::updateBook(const std::string& path, const std::string& title, const std::string& author,
                                   const std::string& coverBmpPath) {
   auto it =
@@ -72,7 +81,7 @@ bool RecentBooksStore::saveToFile() const {
   }
 
   outputFile.close();
-  Serial.printf("[%lu] [RBS] Recent books saved to file (%d entries)\n", millis(), count);
+  LOG_DBG("RBS", "Recent books saved to file (%d entries)", count);
   return true;
 }
 
@@ -83,12 +92,12 @@ RecentBook RecentBooksStore::getDataFromBook(std::string path) const {
     lastBookFileName = path.substr(lastSlash + 1);
   }
 
-  Serial.printf("Loading recent book: %s\n", path.c_str());
+  LOG_DBG("RBS", "Loading recent book: %s", path.c_str());
 
   // If epub, try to load the metadata for title/author and cover
   if (StringUtils::checkFileExtension(lastBookFileName, ".epub")) {
     Epub epub(path, "/.crosspoint");
-    epub.load(false);
+    epub.load(false, true);
     return RecentBook{path, epub.getTitle(), epub.getAuthor(), epub.getThumbBmpPath()};
   } else if (StringUtils::checkFileExtension(lastBookFileName, ".xtch") ||
              StringUtils::checkFileExtension(lastBookFileName, ".xtc")) {
@@ -136,7 +145,7 @@ bool RecentBooksStore::loadFromFile() {
         }
       }
     } else {
-      Serial.printf("[%lu] [RBS] Deserialization failed: Unknown version %u\n", millis(), version);
+      LOG_ERR("RBS", "Deserialization failed: Unknown version %u", version);
       inputFile.close();
       return false;
     }
@@ -158,6 +167,6 @@ bool RecentBooksStore::loadFromFile() {
   }
 
   inputFile.close();
-  Serial.printf("[%lu] [RBS] Recent books loaded from file (%d entries)\n", millis(), recentBooks.size());
+  LOG_DBG("RBS", "Recent books loaded from file (%d entries)", recentBooks.size());
   return true;
 }

src/RecentBooksStore.h

@@ -30,6 +30,9 @@ class RecentBooksStore {
   void updateBook(const std::string& path, const std::string& title, const std::string& author,
                   const std::string& coverBmpPath);
 
+  // Remove a book from the recent list by path
+  void removeBook(const std::string& path);
+
   // Get the list of recent books (most recent first)
   const std::vector<RecentBook>& getBooks() const { return recentBooks; }
 

src/SettingsList.h

@@ -6,10 +6,36 @@
 #include "KOReaderCredentialStore.h"
 #include "activities/settings/SettingsActivity.h"
 
+// Compile-time table of available font families and their enum values.
+// Used by the DynamicEnum getter/setter to map between list indices and stored FONT_FAMILY values.
+struct FontFamilyMapping {
+  const char* name;
+  uint8_t value;
+};
+inline constexpr FontFamilyMapping kFontFamilyMappings[] = {
+#ifndef OMIT_BOOKERLY
+    {"Bookerly", CrossPointSettings::BOOKERLY},
+#endif
+#ifndef OMIT_NOTOSANS
+    {"Noto Sans", CrossPointSettings::NOTOSANS},
+#endif
+#ifndef OMIT_OPENDYSLEXIC
+    {"Open Dyslexic", CrossPointSettings::OPENDYSLEXIC},
+#endif
+};
+inline constexpr size_t kFontFamilyMappingCount = sizeof(kFontFamilyMappings) / sizeof(kFontFamilyMappings[0]);
+static_assert(kFontFamilyMappingCount > 0, "At least one font family must be available");
+
 // Shared settings list used by both the device settings UI and the web settings API.
 // Each entry has a key (for JSON API) and category (for grouping).
 // ACTION-type entries and entries without a key are device-only.
 inline std::vector<SettingInfo> getSettingsList() {
+  // Build font family options from the compile-time mapping table
+  std::vector<std::string> fontFamilyOptions;
+  for (size_t i = 0; i < kFontFamilyMappingCount; i++) {
+    fontFamilyOptions.push_back(kFontFamilyMappings[i].name);
+  }
+
   return {
       // --- Display ---
       SettingInfo::Enum("Sleep Screen", &CrossPointSettings::sleepScreen,
@@ -19,9 +45,7 @@ inline std::vector<SettingInfo> getSettingsList() {
       SettingInfo::Enum("Sleep Screen Cover Filter", &CrossPointSettings::sleepScreenCoverFilter,
                         {"None", "Contrast", "Inverted"}, "sleepScreenCoverFilter", "Display"),
       SettingInfo::Enum("Letterbox Fill", &CrossPointSettings::sleepScreenLetterboxFill,
-                        {"None", "Solid", "Blended", "Gradient"}, "sleepScreenLetterboxFill", "Display"),
-      SettingInfo::Enum("Gradient Direction", &CrossPointSettings::sleepScreenGradientDir, {"To White", "To Black"},
-                        "sleepScreenGradientDir", "Display"),
+                        {"Dithered", "Solid", "None"}, "sleepScreenLetterboxFill", "Display"),
       SettingInfo::Enum(
           "Status Bar", &CrossPointSettings::statusBar,
           {"None", "No Progress", "Full w/ Percentage", "Full w/ Book Bar", "Book Bar Only", "Full w/ Chapter Bar"},
@@ -34,8 +58,20 @@ inline std::vector<SettingInfo> getSettingsList() {
       SettingInfo::Toggle("Sunlight Fading Fix", &CrossPointSettings::fadingFix, "fadingFix", "Display"),
 
       // --- Reader ---
-      SettingInfo::Enum("Font Family", &CrossPointSettings::fontFamily, {"Bookerly", "Noto Sans", "Open Dyslexic"},
-                        "fontFamily", "Reader"),
+      SettingInfo::DynamicEnum(
+          "Font Family", std::move(fontFamilyOptions),
+          []() -> uint8_t {
+            for (uint8_t i = 0; i < kFontFamilyMappingCount; i++) {
+              if (kFontFamilyMappings[i].value == SETTINGS.fontFamily) return i;
+            }
+            return 0;  // fallback to first available family
+          },
+          [](uint8_t idx) {
+            if (idx < kFontFamilyMappingCount) {
+              SETTINGS.fontFamily = kFontFamilyMappings[idx].value;
+            }
+          },
+          "fontFamily", "Reader"),
       SettingInfo::Enum("Font Size", &CrossPointSettings::fontSize, {"Small", "Medium", "Large", "X Large"}, "fontSize",
                         "Reader"),
       SettingInfo::Enum("Line Spacing", &CrossPointSettings::lineSpacing, {"Tight", "Normal", "Wide"}, "lineSpacing",

src/WifiCredentialStore.cpp

@@ -1,7 +1,7 @@
 #include "WifiCredentialStore.h"
 
 #include <HalStorage.h>
-#include <HardwareSerial.h>
+#include <Logging.h>
 #include <Serialization.h>
 
 // Initialize the static instance
@@ -9,7 +9,7 @@ WifiCredentialStore WifiCredentialStore::instance;
 
 namespace {
 // File format version
-constexpr uint8_t WIFI_FILE_VERSION = 1;
+constexpr uint8_t WIFI_FILE_VERSION = 2;  // Increased version
 
 // WiFi credentials file path
 constexpr char WIFI_FILE[] = "/.crosspoint/wifi.bin";
@@ -21,7 +21,7 @@ constexpr size_t KEY_LENGTH = sizeof(OBFUSCATION_KEY);
 }  // namespace
 
 void WifiCredentialStore::obfuscate(std::string& data) const {
-  Serial.printf("[%lu] [WCS] Obfuscating/deobfuscating %zu bytes\n", millis(), data.size());
+  LOG_DBG("WCS", "Obfuscating/deobfuscating %zu bytes", data.size());
   for (size_t i = 0; i < data.size(); i++) {
     data[i] ^= OBFUSCATION_KEY[i % KEY_LENGTH];
   }
@@ -38,14 +38,14 @@ bool WifiCredentialStore::saveToFile() const {
 
   // Write header
   serialization::writePod(file, WIFI_FILE_VERSION);
+  serialization::writeString(file, lastConnectedSsid);  // Save last connected SSID
   serialization::writePod(file, static_cast<uint8_t>(credentials.size()));
 
   // Write each credential
   for (const auto& cred : credentials) {
     // Write SSID (plaintext - not sensitive)
     serialization::writeString(file, cred.ssid);
-    Serial.printf("[%lu] [WCS] Saving SSID: %s, password length: %zu\n", millis(), cred.ssid.c_str(),
-                  cred.password.size());
+    LOG_DBG("WCS", "Saving SSID: %s, password length: %zu", cred.ssid.c_str(), cred.password.size());
 
     // Write password (obfuscated)
     std::string obfuscatedPwd = cred.password;
@@ -54,7 +54,7 @@ bool WifiCredentialStore::saveToFile() const {
   }
 
   file.close();
-  Serial.printf("[%lu] [WCS] Saved %zu WiFi credentials to file\n", millis(), credentials.size());
+  LOG_DBG("WCS", "Saved %zu WiFi credentials to file", credentials.size());
   return true;
 }
 
@@ -67,12 +67,18 @@ bool WifiCredentialStore::loadFromFile() {
   // Read and verify version
   uint8_t version;
   serialization::readPod(file, version);
-  if (version != WIFI_FILE_VERSION) {
-    Serial.printf("[%lu] [WCS] Unknown file version: %u\n", millis(), version);
+  if (version > WIFI_FILE_VERSION) {
+    LOG_DBG("WCS", "Unknown file version: %u", version);
     file.close();
     return false;
   }
 
+  if (version >= 2) {
+    serialization::readString(file, lastConnectedSsid);
+  } else {
+    lastConnectedSsid.clear();
+  }
+
   // Read credential count
   uint8_t count;
   serialization::readPod(file, count);
@@ -87,16 +93,15 @@ bool WifiCredentialStore::loadFromFile() {
 
     // Read and deobfuscate password
     serialization::readString(file, cred.password);
-    Serial.printf("[%lu] [WCS] Loaded SSID: %s, obfuscated password length: %zu\n", millis(), cred.ssid.c_str(),
-                  cred.password.size());
+    LOG_DBG("WCS", "Loaded SSID: %s, obfuscated password length: %zu", cred.ssid.c_str(), cred.password.size());
     obfuscate(cred.password);  // XOR is symmetric, so same function deobfuscates
-    Serial.printf("[%lu] [WCS] After deobfuscation, password length: %zu\n", millis(), cred.password.size());
+    LOG_DBG("WCS", "After deobfuscation, password length: %zu", cred.password.size());
 
     credentials.push_back(cred);
   }
 
   file.close();
-  Serial.printf("[%lu] [WCS] Loaded %zu WiFi credentials from file\n", millis(), credentials.size());
+  LOG_DBG("WCS", "Loaded %zu WiFi credentials from file", credentials.size());
   return true;
 }
 
@@ -106,19 +111,19 @@ bool WifiCredentialStore::addCredential(const std::string& ssid, const std::stri
                             [&ssid](const WifiCredential& cred) { return cred.ssid == ssid; });
   if (cred != credentials.end()) {
     cred->password = password;
-    Serial.printf("[%lu] [WCS] Updated credentials for: %s\n", millis(), ssid.c_str());
+    LOG_DBG("WCS", "Updated credentials for: %s", ssid.c_str());
     return saveToFile();
   }
 
   // Check if we've reached the limit
   if (credentials.size() >= MAX_NETWORKS) {
-    Serial.printf("[%lu] [WCS] Cannot add more networks, limit of %zu reached\n", millis(), MAX_NETWORKS);
+    LOG_DBG("WCS", "Cannot add more networks, limit of %zu reached", MAX_NETWORKS);
     return false;
   }
 
   // Add new credential
   credentials.push_back({ssid, password});
-  Serial.printf("[%lu] [WCS] Added credentials for: %s\n", millis(), ssid.c_str());
+  LOG_DBG("WCS", "Added credentials for: %s", ssid.c_str());
   return saveToFile();
 }
 
@@ -127,7 +132,10 @@ bool WifiCredentialStore::removeCredential(const std::string& ssid) {
                             [&ssid](const WifiCredential& cred) { return cred.ssid == ssid; });
   if (cred != credentials.end()) {
     credentials.erase(cred);
-    Serial.printf("[%lu] [WCS] Removed credentials for: %s\n", millis(), ssid.c_str());
+    LOG_DBG("WCS", "Removed credentials for: %s", ssid.c_str());
+    if (ssid == lastConnectedSsid) {
+      clearLastConnectedSsid();
+    }
     return saveToFile();
   }
   return false;  // Not found
@@ -146,8 +154,25 @@ const WifiCredential* WifiCredentialStore::findCredential(const std::string& ssi
 
 bool WifiCredentialStore::hasSavedCredential(const std::string& ssid) const { return findCredential(ssid) != nullptr; }
 
+void WifiCredentialStore::setLastConnectedSsid(const std::string& ssid) {
+  if (lastConnectedSsid != ssid) {
+    lastConnectedSsid = ssid;
+    saveToFile();
+  }
+}
+
+const std::string& WifiCredentialStore::getLastConnectedSsid() const { return lastConnectedSsid; }
+
+void WifiCredentialStore::clearLastConnectedSsid() {
+  if (!lastConnectedSsid.empty()) {
+    lastConnectedSsid.clear();
+    saveToFile();
+  }
+}
+
 void WifiCredentialStore::clearAll() {
   credentials.clear();
+  lastConnectedSsid.clear();
   saveToFile();
-  Serial.printf("[%lu] [WCS] Cleared all WiFi credentials\n", millis());
+  LOG_DBG("WCS", "Cleared all WiFi credentials");
 }

src/WifiCredentialStore.h

@@ -16,6 +16,7 @@ class WifiCredentialStore {
  private:
   static WifiCredentialStore instance;
   std::vector<WifiCredential> credentials;
+  std::string lastConnectedSsid;
 
   static constexpr size_t MAX_NETWORKS = 8;
 
@@ -48,6 +49,11 @@ class WifiCredentialStore {
   // Check if a network is saved
   bool hasSavedCredential(const std::string& ssid) const;
 
+  // Last connected network
+  void setLastConnectedSsid(const std::string& ssid);
+  const std::string& getLastConnectedSsid() const;
+  void clearLastConnectedSsid();
+
   // Clear all credentials
   void clearAll();
 };

src/activities/Activity.h

@@ -1,6 +1,6 @@
 #pragma once
 
-#include <HardwareSerial.h>
+#include <Logging.h>
 
 #include <string>
 #include <utility>
@@ -18,8 +18,8 @@ class Activity {
   explicit Activity(std::string name, GfxRenderer& renderer, MappedInputManager& mappedInput)
       : name(std::move(name)), renderer(renderer), mappedInput(mappedInput) {}
   virtual ~Activity() = default;
-  virtual void onEnter() { Serial.printf("[%lu] [ACT] Entering activity: %s\n", millis(), name.c_str()); }
-  virtual void onExit() { Serial.printf("[%lu] [ACT] Exiting activity: %s\n", millis(), name.c_str()); }
+  virtual void onEnter() { LOG_DBG("ACT", "Entering activity: %s", name.c_str()); }
+  virtual void onExit() { LOG_DBG("ACT", "Exiting activity: %s", name.c_str()); }
   virtual void loop() {}
   virtual bool skipLoopDelay() { return false; }
   virtual bool preventAutoSleep() { return false; }

src/activities/ActivityWithSubactivity.h

@@ -14,4 +14,6 @@ class ActivityWithSubactivity : public Activity {
       : Activity(std::move(name), renderer, mappedInput) {}
   void loop() override;
   void onExit() override;
+  bool preventAutoSleep() override { return subActivity && subActivity->preventAutoSleep(); }
+  bool skipLoopDelay() override { return subActivity && subActivity->skipLoopDelay(); }
 };

src/activities/boot_sleep/SleepActivity.cpp

@@ -1,17 +1,20 @@
 #include "SleepActivity.h"
 
-#include <BitmapHelpers.h>
 #include <Epub.h>
 #include <GfxRenderer.h>
 #include <HalStorage.h>
+#include <Logging.h>
+#include <PlaceholderCoverGenerator.h>
 #include <Serialization.h>
 #include <Txt.h>
 #include <Xtc.h>
 
 #include <algorithm>
+#include <cmath>
 
 #include "CrossPointSettings.h"
 #include "CrossPointState.h"
+#include "util/BookSettings.h"
 #include "components/UITheme.h"
 #include "fontIds.h"
 #include "images/Logo120.h"
@@ -19,36 +22,95 @@
 
 namespace {
 
-// Number of source pixels along the image edge to average for the gradient color
+// Number of source pixels along the image edge to average for the dominant color
 constexpr int EDGE_SAMPLE_DEPTH = 20;
 
 // Map a 2-bit quantized pixel value to an 8-bit grayscale value
 constexpr uint8_t val2bitToGray(uint8_t val2bit) { return val2bit * 85; }
 
-// Edge gradient data produced by sampleBitmapEdges and consumed by drawLetterboxGradients.
-// edgeA is the "first" edge (top or left), edgeB is the "second" edge (bottom or right).
-struct LetterboxGradientData {
-  uint8_t* edgeA = nullptr;
-  uint8_t* edgeB = nullptr;
-  int edgeCount = 0;
+// Letterbox fill data: one average gray value per edge (top/bottom or left/right).
+struct LetterboxFillData {
+  uint8_t avgA = 128;       // average gray of edge A (top or left)
+  uint8_t avgB = 128;       // average gray of edge B (bottom or right)
   int letterboxA = 0;       // pixel size of the first letterbox area (top or left)
   int letterboxB = 0;       // pixel size of the second letterbox area (bottom or right)
   bool horizontal = false;  // true = top/bottom letterbox, false = left/right
-
-  void free() {
-    ::free(edgeA);
-    ::free(edgeB);
-    edgeA = nullptr;
-    edgeB = nullptr;
-  }
+  bool valid = false;
 };
 
-// Binary cache version for edge data files
-constexpr uint8_t EDGE_CACHE_VERSION = 1;
+// Snap an 8-bit gray value to the nearest of the 4 e-ink levels: 0, 85, 170, 255.
+uint8_t snapToEinkLevel(uint8_t gray) {
+  // Thresholds at midpoints: 42, 127, 212
+  if (gray < 43) return 0;
+  if (gray < 128) return 85;
+  if (gray < 213) return 170;
+  return 255;
+}
 
-// Load cached edge data from a binary file. Returns true if the cache was valid and loaded successfully.
-// Validates cache version and screen dimensions to detect stale data.
-bool loadEdgeCache(const std::string& path, int screenWidth, int screenHeight, LetterboxGradientData& data) {
+// 4x4 Bayer ordered dithering matrix, values 0-255.
+// Produces a structured halftone pattern for 4-level quantization.
+// clang-format off
+constexpr uint8_t BAYER_4X4[4][4] = {
+  {  0, 128,  32, 160},
+  {192,  64, 224,  96},
+  { 48, 176,  16, 144},
+  {240, 112, 208,  80}
+};
+// clang-format on
+
+// Ordered (Bayer) dithering for 4-level e-ink display.
+// Maps an 8-bit gray value to a 2-bit level (0-3) using the Bayer matrix
+// to produce a structured, repeating halftone pattern.
+uint8_t quantizeBayerDither(int gray, int x, int y) {
+  const int threshold = BAYER_4X4[y & 3][x & 3];
+  const int scaled = gray * 3;
+  if (scaled < 255) {
+    return (scaled + threshold >= 255) ? 1 : 0;
+  } else if (scaled < 510) {
+    return ((scaled - 255) + threshold >= 255) ? 2 : 1;
+  } else {
+    return ((scaled - 510) + threshold >= 255) ? 3 : 2;
+  }
+}
+
+// Check whether a gray value would produce a dithered mix that crosses the
+// level-2 / level-3 boundary.  This is the ONLY boundary where some dithered
+// pixels are BLACK (level ≤ 2) and others are WHITE (level 3) in the BW pass,
+// creating a high-frequency checkerboard that causes e-ink display crosstalk
+// and washes out adjacent content during HALF_REFRESH.
+// Gray values 171-254 produce a level-2/level-3 mix via Bayer dithering.
+bool bayerCrossesBwBoundary(uint8_t gray) {
+  return gray > 170 && gray < 255;
+}
+
+// Hash-based block dithering for BW-boundary gray values (171-254).
+// Each blockSize×blockSize pixel block gets a single uniform level (2 or 3),
+// determined by a deterministic spatial hash.  The proportion of level-3 blocks
+// approximates the target gray.  Unlike Bayer, the pattern is irregular
+// (noise-like), making it much less visually obvious at the same block size.
+// The hash is purely spatial (depends only on x, y, blockSize) so it produces
+// identical levels across BW, LSB, and MSB render passes.
+static constexpr int BW_DITHER_BLOCK = 2;
+
+uint8_t hashBlockDither(uint8_t avg, int x, int y) {
+  const int bx = x / BW_DITHER_BLOCK;
+  const int by = y / BW_DITHER_BLOCK;
+  // Fast mixing hash (splitmix32-inspired)
+  uint32_t h = (uint32_t)bx * 2654435761u ^ (uint32_t)by * 2246822519u;
+  h ^= h >> 16;
+  h *= 0x45d9f3bu;
+  h ^= h >> 16;
+  // Proportion of level-3 blocks needed to approximate the target gray
+  const float ratio = (avg - 170.0f) / 85.0f;
+  const uint32_t threshold = (uint32_t)(ratio * 4294967295.0f);
+  return (h < threshold) ? 3 : 2;
+}
+
+// --- Edge average cache ---
+// Caches the computed edge averages alongside the cover BMP so we don't rescan on every sleep.
+constexpr uint8_t EDGE_CACHE_VERSION = 2;
+
+bool loadEdgeCache(const std::string& path, int screenWidth, int screenHeight, LetterboxFillData& data) {
   FsFile file;
   if (!Storage.openFileForRead("SLP", path, file)) return false;
 
@@ -71,9 +133,8 @@ bool loadEdgeCache(const std::string& path, int screenWidth, int screenHeight, L
   serialization::readPod(file, horizontal);
   data.horizontal = (horizontal != 0);
 
-  uint16_t edgeCount;
-  serialization::readPod(file, edgeCount);
-  data.edgeCount = edgeCount;
+  serialization::readPod(file, data.avgA);
+  serialization::readPod(file, data.avgB);
 
   int16_t lbA, lbB;
   serialization::readPod(file, lbA);
@@ -81,34 +142,14 @@ bool loadEdgeCache(const std::string& path, int screenWidth, int screenHeight, L
   data.letterboxA = lbA;
   data.letterboxB = lbB;
 
-  if (edgeCount == 0 || edgeCount > 2048) {
-    file.close();
-    return false;
-  }
-
-  data.edgeA = static_cast<uint8_t*>(malloc(edgeCount));
-  data.edgeB = static_cast<uint8_t*>(malloc(edgeCount));
-  if (!data.edgeA || !data.edgeB) {
-    data.free();
-    file.close();
-    return false;
-  }
-
-  if (file.read(data.edgeA, edgeCount) != static_cast<int>(edgeCount) ||
-      file.read(data.edgeB, edgeCount) != static_cast<int>(edgeCount)) {
-    data.free();
-    file.close();
-    return false;
-  }
-
   file.close();
-  Serial.printf("[%lu] [SLP] Loaded edge cache from %s (%d edges)\n", millis(), path.c_str(), edgeCount);
+  data.valid = true;
+  LOG_DBG("SLP", "Loaded edge cache from %s (avgA=%d, avgB=%d)", path.c_str(), data.avgA, data.avgB);
   return true;
 }
 
-// Save edge data to a binary cache file for reuse on subsequent sleep screens.
-bool saveEdgeCache(const std::string& path, int screenWidth, int screenHeight, const LetterboxGradientData& data) {
-  if (!data.edgeA || !data.edgeB || data.edgeCount <= 0) return false;
+bool saveEdgeCache(const std::string& path, int screenWidth, int screenHeight, const LetterboxFillData& data) {
+  if (!data.valid) return false;
 
   FsFile file;
   if (!Storage.openFileForWrite("SLP", path, file)) return false;
@@ -117,23 +158,22 @@ bool saveEdgeCache(const std::string& path, int screenWidth, int screenHeight, c
   serialization::writePod(file, static_cast<uint16_t>(screenWidth));
   serialization::writePod(file, static_cast<uint16_t>(screenHeight));
   serialization::writePod(file, static_cast<uint8_t>(data.horizontal ? 1 : 0));
-  serialization::writePod(file, static_cast<uint16_t>(data.edgeCount));
+  serialization::writePod(file, data.avgA);
+  serialization::writePod(file, data.avgB);
   serialization::writePod(file, static_cast<int16_t>(data.letterboxA));
   serialization::writePod(file, static_cast<int16_t>(data.letterboxB));
-  file.write(data.edgeA, data.edgeCount);
-  file.write(data.edgeB, data.edgeCount);
   file.close();
 
-  Serial.printf("[%lu] [SLP] Saved edge cache to %s (%d edges)\n", millis(), path.c_str(), data.edgeCount);
+  LOG_DBG("SLP", "Saved edge cache to %s", path.c_str());
   return true;
 }
 
-// Read the bitmap once to sample the first/last EDGE_SAMPLE_DEPTH rows or columns.
-// Returns edge color arrays in source pixel resolution.  Caller must call data.free() when done.
+// Read the bitmap once to compute a single average gray value for the top/bottom or left/right edges.
+// Only computes running sums -- no per-pixel arrays, no malloc beyond row buffers.
 // After sampling the bitmap is rewound via rewindToData().
-LetterboxGradientData sampleBitmapEdges(const Bitmap& bitmap, int imgX, int imgY, int pageWidth, int pageHeight,
-                                        float scale, float cropX, float cropY) {
-  LetterboxGradientData data;
+LetterboxFillData computeEdgeAverages(const Bitmap& bitmap, int imgX, int imgY, int pageWidth, int pageHeight,
+                                      float scale, float cropX, float cropY) {
+  LetterboxFillData data;
 
   const int cropPixX = static_cast<int>(std::floor(bitmap.getWidth() * cropX / 2.0f));
   const int cropPixY = static_cast<int>(std::floor(bitmap.getHeight() * cropY / 2.0f));
@@ -146,35 +186,22 @@ LetterboxGradientData sampleBitmapEdges(const Bitmap& bitmap, int imgX, int imgY
   auto* outputRow = static_cast<uint8_t*>(malloc(outputRowSize));
   auto* rowBytes = static_cast<uint8_t*>(malloc(bitmap.getRowBytes()));
   if (!outputRow || !rowBytes) {
-    ::free(outputRow);
-    ::free(rowBytes);
+    free(outputRow);
+    free(rowBytes);
     return data;
   }
 
   if (imgY > 0) {
-    // Top/bottom letterboxing -- sample per-column averages of first/last N rows
+    // Top/bottom letterboxing -- compute overall average of first/last EDGE_SAMPLE_DEPTH rows
     data.horizontal = true;
-    data.edgeCount = visibleWidth;
     const int scaledHeight = static_cast<int>(std::round(static_cast<float>(visibleHeight) * scale));
     data.letterboxA = imgY;
     data.letterboxB = pageHeight - imgY - scaledHeight;
     if (data.letterboxB < 0) data.letterboxB = 0;
 
     const int sampleRows = std::min(EDGE_SAMPLE_DEPTH, visibleHeight);
-
-    auto* accumTop = static_cast<uint32_t*>(calloc(visibleWidth, sizeof(uint32_t)));
-    auto* accumBot = static_cast<uint32_t*>(calloc(visibleWidth, sizeof(uint32_t)));
-    data.edgeA = static_cast<uint8_t*>(malloc(visibleWidth));
-    data.edgeB = static_cast<uint8_t*>(malloc(visibleWidth));
-
-    if (!accumTop || !accumBot || !data.edgeA || !data.edgeB) {
-      ::free(accumTop);
-      ::free(accumBot);
-      data.free();
-      ::free(outputRow);
-      ::free(rowBytes);
-      return data;
-    }
+    uint64_t sumTop = 0, sumBot = 0;
+    int countTop = 0, countBot = 0;
 
     for (int bmpY = 0; bmpY < bitmap.getHeight(); bmpY++) {
       if (bitmap.readNextRow(outputRow, rowBytes) != BmpReaderError::Ok) break;
@@ -187,188 +214,130 @@ LetterboxGradientData sampleBitmapEdges(const Bitmap& bitmap, int imgX, int imgY
       if (!inTop && !inBot) continue;
 
       for (int bmpX = cropPixX; bmpX < bitmap.getWidth() - cropPixX; bmpX++) {
-        const int outX = bmpX - cropPixX;
         const uint8_t val = (outputRow[bmpX / 4] >> (6 - ((bmpX * 2) % 8))) & 0x3;
         const uint8_t gray = val2bitToGray(val);
-        if (inTop) accumTop[outX] += gray;
-        if (inBot) accumBot[outX] += gray;
+        if (inTop) {
+          sumTop += gray;
+          countTop++;
+        }
+        if (inBot) {
+          sumBot += gray;
+          countBot++;
+        }
       }
     }
 
-    for (int i = 0; i < visibleWidth; i++) {
-      data.edgeA[i] = static_cast<uint8_t>(accumTop[i] / sampleRows);
-      data.edgeB[i] = static_cast<uint8_t>(accumBot[i] / sampleRows);
-    }
-    ::free(accumTop);
-    ::free(accumBot);
-
+    data.avgA = countTop > 0 ? static_cast<uint8_t>(sumTop / countTop) : 128;
+    data.avgB = countBot > 0 ? static_cast<uint8_t>(sumBot / countBot) : 128;
+    data.valid = true;
   } else if (imgX > 0) {
-    // Left/right letterboxing -- sample per-row averages of first/last N columns
+    // Left/right letterboxing -- compute overall average of first/last EDGE_SAMPLE_DEPTH columns
     data.horizontal = false;
-    data.edgeCount = visibleHeight;
     const int scaledWidth = static_cast<int>(std::round(static_cast<float>(visibleWidth) * scale));
     data.letterboxA = imgX;
     data.letterboxB = pageWidth - imgX - scaledWidth;
     if (data.letterboxB < 0) data.letterboxB = 0;
 
     const int sampleCols = std::min(EDGE_SAMPLE_DEPTH, visibleWidth);
-
-    auto* accumLeft = static_cast<uint32_t*>(calloc(visibleHeight, sizeof(uint32_t)));
-    auto* accumRight = static_cast<uint32_t*>(calloc(visibleHeight, sizeof(uint32_t)));
-    data.edgeA = static_cast<uint8_t*>(malloc(visibleHeight));
-    data.edgeB = static_cast<uint8_t*>(malloc(visibleHeight));
-
-    if (!accumLeft || !accumRight || !data.edgeA || !data.edgeB) {
-      ::free(accumLeft);
-      ::free(accumRight);
-      data.free();
-      ::free(outputRow);
-      ::free(rowBytes);
-      return data;
-    }
+    uint64_t sumLeft = 0, sumRight = 0;
+    int countLeft = 0, countRight = 0;
 
     for (int bmpY = 0; bmpY < bitmap.getHeight(); bmpY++) {
       if (bitmap.readNextRow(outputRow, rowBytes) != BmpReaderError::Ok) break;
       const int logicalY = bitmap.isTopDown() ? bmpY : bitmap.getHeight() - 1 - bmpY;
       if (logicalY < cropPixY || logicalY >= bitmap.getHeight() - cropPixY) continue;
-      const int outY = logicalY - cropPixY;
 
-      // Sample left edge columns
       for (int bmpX = cropPixX; bmpX < cropPixX + sampleCols; bmpX++) {
         const uint8_t val = (outputRow[bmpX / 4] >> (6 - ((bmpX * 2) % 8))) & 0x3;
-        accumLeft[outY] += val2bitToGray(val);
+        sumLeft += val2bitToGray(val);
+        countLeft++;
       }
-      // Sample right edge columns
       for (int bmpX = bitmap.getWidth() - cropPixX - sampleCols; bmpX < bitmap.getWidth() - cropPixX; bmpX++) {
         const uint8_t val = (outputRow[bmpX / 4] >> (6 - ((bmpX * 2) % 8))) & 0x3;
-        accumRight[outY] += val2bitToGray(val);
+        sumRight += val2bitToGray(val);
+        countRight++;
       }
     }
 
-    for (int i = 0; i < visibleHeight; i++) {
-      data.edgeA[i] = static_cast<uint8_t>(accumLeft[i] / sampleCols);
-      data.edgeB[i] = static_cast<uint8_t>(accumRight[i] / sampleCols);
-    }
-    ::free(accumLeft);
-    ::free(accumRight);
+    data.avgA = countLeft > 0 ? static_cast<uint8_t>(sumLeft / countLeft) : 128;
+    data.avgB = countRight > 0 ? static_cast<uint8_t>(sumRight / countRight) : 128;
+    data.valid = true;
   }
 
-  ::free(outputRow);
-  ::free(rowBytes);
   bitmap.rewindToData();
+  free(outputRow);
+  free(rowBytes);
   return data;
 }
 
-// Draw dithered fills in the letterbox areas using the sampled edge colors.
-// fillMode selects the fill algorithm: SOLID (single dominant shade), BLENDED (per-pixel edge color),
-// or GRADIENT (per-pixel edge color interpolated toward targetColor).
-// targetColor is the color the gradient fades toward (255=white, 0=black); only used in GRADIENT mode.
+// Draw letterbox fill in the areas around the cover image.
+// DITHERED: fills with the edge average using Bayer ordered dithering to approximate the color.
+// SOLID: snaps edge average to nearest e-ink level (0/85/170/255) for a clean uniform fill.
 // Must be called once per render pass (BW, GRAYSCALE_LSB, GRAYSCALE_MSB).
-void drawLetterboxFill(GfxRenderer& renderer, const LetterboxGradientData& data, float scale, uint8_t fillMode,
-                       int targetColor) {
-  if (!data.edgeA || !data.edgeB || data.edgeCount <= 0) return;
+void drawLetterboxFill(GfxRenderer& renderer, const LetterboxFillData& data, uint8_t fillMode) {
+  if (!data.valid) return;
 
   const bool isSolid = (fillMode == CrossPointSettings::SLEEP_SCREEN_LETTERBOX_FILL::LETTERBOX_SOLID);
-  const bool isGradient = (fillMode == CrossPointSettings::SLEEP_SCREEN_LETTERBOX_FILL::LETTERBOX_GRADIENT);
 
-  // For SOLID mode, compute the dominant (average) shade for each edge once
-  uint8_t solidColorA = 0, solidColorB = 0;
-  if (isSolid) {
-    uint32_t sumA = 0, sumB = 0;
-    for (int i = 0; i < data.edgeCount; i++) {
-      sumA += data.edgeA[i];
-      sumB += data.edgeB[i];
-    }
-    solidColorA = static_cast<uint8_t>(sumA / data.edgeCount);
-    solidColorB = static_cast<uint8_t>(sumB / data.edgeCount);
-  }
+  // For DITHERED mode with gray values in 171-254 (the level-2/level-3 BW boundary):
+  // Pixel-level Bayer dithering creates a regular high-frequency checkerboard in
+  // the BW pass that causes e-ink display crosstalk during HALF_REFRESH.
+  //
+  // Solution: HASH-BASED BLOCK DITHERING.  Each 2x2 pixel block gets a single
+  // level (2 or 3) determined by a spatial hash, with the proportion of level-3
+  // blocks tuned to approximate the target gray.  The 2px minimum run avoids BW
+  // crosstalk, and the irregular hash pattern is much less visible than a regular
+  // Bayer grid at the same block size.
+  const bool hashA = !isSolid && bayerCrossesBwBoundary(data.avgA);
+  const bool hashB = !isSolid && bayerCrossesBwBoundary(data.avgB);
 
-  // Helper: compute gray value for a pixel given the edge color and interpolation factor t (0..1)
-  // GRADIENT interpolates from edgeColor toward targetColor; SOLID and BLENDED return edgeColor directly.
-  auto computeGray = [&](int edgeColor, float t) -> int {
-    if (isGradient) return edgeColor + static_cast<int>(static_cast<float>(targetColor - edgeColor) * t);
-    return edgeColor;
-  };
+  // For solid mode: snap to nearest e-ink level
+  const uint8_t levelA = isSolid ? snapToEinkLevel(data.avgA) / 85 : 0;
+  const uint8_t levelB = isSolid ? snapToEinkLevel(data.avgB) / 85 : 0;
 
   if (data.horizontal) {
-    // Top letterbox
     if (data.letterboxA > 0) {
-      const int imgTopY = data.letterboxA;
-      for (int screenY = 0; screenY < imgTopY; screenY++) {
-        const float t = static_cast<float>(imgTopY - screenY) / static_cast<float>(imgTopY);
-        for (int screenX = 0; screenX < renderer.getScreenWidth(); screenX++) {
-          int edgeColor;
-          if (isSolid) {
-            edgeColor = solidColorA;
-          } else {
-            int srcCol = static_cast<int>(screenX / scale);
-            srcCol = std::max(0, std::min(srcCol, data.edgeCount - 1));
-            edgeColor = data.edgeA[srcCol];
-          }
-          const int gray = computeGray(edgeColor, t);
-          renderer.drawPixelGray(screenX, screenY, quantizeNoiseDither(gray, screenX, screenY));
+      for (int y = 0; y < data.letterboxA; y++)
+        for (int x = 0; x < renderer.getScreenWidth(); x++) {
+          uint8_t lv;
+          if (isSolid)      lv = levelA;
+          else if (hashA)   lv = hashBlockDither(data.avgA, x, y);
+          else              lv = quantizeBayerDither(data.avgA, x, y);
+          renderer.drawPixelGray(x, y, lv);
         }
-      }
     }
-
-    // Bottom letterbox
     if (data.letterboxB > 0) {
-      const int imgBottomY = renderer.getScreenHeight() - data.letterboxB;
-      for (int screenY = imgBottomY; screenY < renderer.getScreenHeight(); screenY++) {
-        const float t = static_cast<float>(screenY - imgBottomY + 1) / static_cast<float>(data.letterboxB);
-        for (int screenX = 0; screenX < renderer.getScreenWidth(); screenX++) {
-          int edgeColor;
-          if (isSolid) {
-            edgeColor = solidColorB;
-          } else {
-            int srcCol = static_cast<int>(screenX / scale);
-            srcCol = std::max(0, std::min(srcCol, data.edgeCount - 1));
-            edgeColor = data.edgeB[srcCol];
-          }
-          const int gray = computeGray(edgeColor, t);
-          renderer.drawPixelGray(screenX, screenY, quantizeNoiseDither(gray, screenX, screenY));
+      const int start = renderer.getScreenHeight() - data.letterboxB;
+      for (int y = start; y < renderer.getScreenHeight(); y++)
+        for (int x = 0; x < renderer.getScreenWidth(); x++) {
+          uint8_t lv;
+          if (isSolid)      lv = levelB;
+          else if (hashB)   lv = hashBlockDither(data.avgB, x, y);
+          else              lv = quantizeBayerDither(data.avgB, x, y);
+          renderer.drawPixelGray(x, y, lv);
         }
-      }
     }
   } else {
-    // Left letterbox
     if (data.letterboxA > 0) {
-      const int imgLeftX = data.letterboxA;
-      for (int screenX = 0; screenX < imgLeftX; screenX++) {
-        const float t = static_cast<float>(imgLeftX - screenX) / static_cast<float>(imgLeftX);
-        for (int screenY = 0; screenY < renderer.getScreenHeight(); screenY++) {
-          int edgeColor;
-          if (isSolid) {
-            edgeColor = solidColorA;
-          } else {
-            int srcRow = static_cast<int>(screenY / scale);
-            srcRow = std::max(0, std::min(srcRow, data.edgeCount - 1));
-            edgeColor = data.edgeA[srcRow];
-          }
-          const int gray = computeGray(edgeColor, t);
-          renderer.drawPixelGray(screenX, screenY, quantizeNoiseDither(gray, screenX, screenY));
+      for (int x = 0; x < data.letterboxA; x++)
+        for (int y = 0; y < renderer.getScreenHeight(); y++) {
+          uint8_t lv;
+          if (isSolid)      lv = levelA;
+          else if (hashA)   lv = hashBlockDither(data.avgA, x, y);
+          else              lv = quantizeBayerDither(data.avgA, x, y);
+          renderer.drawPixelGray(x, y, lv);
         }
-      }
     }
-
-    // Right letterbox
     if (data.letterboxB > 0) {
-      const int imgRightX = renderer.getScreenWidth() - data.letterboxB;
-      for (int screenX = imgRightX; screenX < renderer.getScreenWidth(); screenX++) {
-        const float t = static_cast<float>(screenX - imgRightX + 1) / static_cast<float>(data.letterboxB);
-        for (int screenY = 0; screenY < renderer.getScreenHeight(); screenY++) {
-          int edgeColor;
-          if (isSolid) {
-            edgeColor = solidColorB;
-          } else {
-            int srcRow = static_cast<int>(screenY / scale);
-            srcRow = std::max(0, std::min(srcRow, data.edgeCount - 1));
-            edgeColor = data.edgeB[srcRow];
-          }
-          const int gray = computeGray(edgeColor, t);
-          renderer.drawPixelGray(screenX, screenY, quantizeNoiseDither(gray, screenX, screenY));
+      const int start = renderer.getScreenWidth() - data.letterboxB;
+      for (int x = start; x < renderer.getScreenWidth(); x++)
+        for (int y = 0; y < renderer.getScreenHeight(); y++) {
+          uint8_t lv;
+          if (isSolid)      lv = levelB;
+          else if (hashB)   lv = hashBlockDither(data.avgB, x, y);
+          else              lv = quantizeBayerDither(data.avgB, x, y);
+          renderer.drawPixelGray(x, y, lv);
         }
-      }
     }
   }
 }
@@ -412,13 +381,13 @@ void SleepActivity::renderCustomSleepScreen() const {
       }
 
       if (filename.substr(filename.length() - 4) != ".bmp") {
-        Serial.printf("[%lu] [SLP] Skipping non-.bmp file name: %s\n", millis(), name);
+        LOG_DBG("SLP", "Skipping non-.bmp file name: %s", name);
         file.close();
         continue;
       }
       Bitmap bitmap(file);
       if (bitmap.parseHeaders() != BmpReaderError::Ok) {
-        Serial.printf("[%lu] [SLP] Skipping invalid BMP file: %s\n", millis(), name);
+        LOG_DBG("SLP", "Skipping invalid BMP file: %s", name);
         file.close();
         continue;
       }
@@ -438,7 +407,7 @@ void SleepActivity::renderCustomSleepScreen() const {
       const auto filename = "/sleep/" + files[randomFileIndex];
       FsFile file;
       if (Storage.openFileForRead("SLP", filename, file)) {
-        Serial.printf("[%lu] [SLP] Randomly loading: /sleep/%s\n", millis(), files[randomFileIndex].c_str());
+        LOG_DBG("SLP", "Randomly loading: /sleep/%s", files[randomFileIndex].c_str());
         delay(100);
         Bitmap bitmap(file, true);
         if (bitmap.parseHeaders() == BmpReaderError::Ok) {
@@ -457,7 +426,7 @@ void SleepActivity::renderCustomSleepScreen() const {
   if (Storage.openFileForRead("SLP", "/sleep.bmp", file)) {
     Bitmap bitmap(file, true);
     if (bitmap.parseHeaders() == BmpReaderError::Ok) {
-      Serial.printf("[%lu] [SLP] Loading: /sleep.bmp\n", millis());
+      LOG_DBG("SLP", "Loading: /sleep.bmp");
       renderBitmapSleepScreen(bitmap);
       return;
     }
@@ -483,43 +452,43 @@ void SleepActivity::renderDefaultSleepScreen() const {
   renderer.displayBuffer(HalDisplay::HALF_REFRESH);
 }
 
-void SleepActivity::renderBitmapSleepScreen(const Bitmap& bitmap, const std::string& edgeCachePath) const {
+void SleepActivity::renderBitmapSleepScreen(const Bitmap& bitmap, const std::string& edgeCachePath,
+                                            uint8_t fillModeOverride) const {
   int x, y;
   const auto pageWidth = renderer.getScreenWidth();
   const auto pageHeight = renderer.getScreenHeight();
   float cropX = 0, cropY = 0;
 
-  Serial.printf("[%lu] [SLP] bitmap %d x %d, screen %d x %d\n", millis(), bitmap.getWidth(), bitmap.getHeight(),
-                pageWidth, pageHeight);
+  LOG_DBG("SLP", "bitmap %d x %d, screen %d x %d", bitmap.getWidth(), bitmap.getHeight(), pageWidth, pageHeight);
 
   // Always compute aspect-ratio-preserving scale and position (supports both larger and smaller images)
   float ratio = static_cast<float>(bitmap.getWidth()) / static_cast<float>(bitmap.getHeight());
   const float screenRatio = static_cast<float>(pageWidth) / static_cast<float>(pageHeight);
 
-  Serial.printf("[%lu] [SLP] bitmap ratio: %f, screen ratio: %f\n", millis(), ratio, screenRatio);
+  LOG_DBG("SLP", "bitmap ratio: %f, screen ratio: %f", ratio, screenRatio);
   if (ratio > screenRatio) {
     // image wider than viewport ratio, needs to be centered vertically
     if (SETTINGS.sleepScreenCoverMode == CrossPointSettings::SLEEP_SCREEN_COVER_MODE::CROP) {
       cropX = 1.0f - (screenRatio / ratio);
-      Serial.printf("[%lu] [SLP] Cropping bitmap x: %f\n", millis(), cropX);
+      LOG_DBG("SLP", "Cropping bitmap x: %f", cropX);
       ratio = (1.0f - cropX) * static_cast<float>(bitmap.getWidth()) / static_cast<float>(bitmap.getHeight());
     }
     x = 0;
     y = std::round((static_cast<float>(pageHeight) - static_cast<float>(pageWidth) / ratio) / 2);
-    Serial.printf("[%lu] [SLP] Centering with ratio %f to y=%d\n", millis(), ratio, y);
+    LOG_DBG("SLP", "Centering with ratio %f to y=%d", ratio, y);
   } else {
     // image taller than or equal to viewport ratio, needs to be centered horizontally
     if (SETTINGS.sleepScreenCoverMode == CrossPointSettings::SLEEP_SCREEN_COVER_MODE::CROP) {
       cropY = 1.0f - (ratio / screenRatio);
-      Serial.printf("[%lu] [SLP] Cropping bitmap y: %f\n", millis(), cropY);
+      LOG_DBG("SLP", "Cropping bitmap y: %f", cropY);
       ratio = static_cast<float>(bitmap.getWidth()) / ((1.0f - cropY) * static_cast<float>(bitmap.getHeight()));
     }
     x = std::round((static_cast<float>(pageWidth) - static_cast<float>(pageHeight) * ratio) / 2);
     y = 0;
-    Serial.printf("[%lu] [SLP] Centering with ratio %f to x=%d\n", millis(), ratio, x);
+    LOG_DBG("SLP", "Centering with ratio %f to x=%d", ratio, x);
   }
 
-  Serial.printf("[%lu] [SLP] drawing to %d x %d\n", millis(), x, y);
+  LOG_DBG("SLP", "drawing to %d x %d", x, y);
 
   // Compute the scale factor (same formula as drawBitmap) so we can map screen coords to source coords
   const float effectiveWidth = (1.0f - cropX) * bitmap.getWidth();
@@ -527,31 +496,36 @@ void SleepActivity::renderBitmapSleepScreen(const Bitmap& bitmap, const std::str
   const float scale =
       std::min(static_cast<float>(pageWidth) / effectiveWidth, static_cast<float>(pageHeight) / effectiveHeight);
 
-  // Determine letterbox fill settings
-  const uint8_t fillMode = SETTINGS.sleepScreenLetterboxFill;
+  // Determine letterbox fill settings (per-book override takes precedence)
+  const uint8_t fillMode = (fillModeOverride != BookSettings::USE_GLOBAL &&
+                            fillModeOverride < CrossPointSettings::SLEEP_SCREEN_LETTERBOX_FILL_COUNT)
+                               ? fillModeOverride
+                               : SETTINGS.sleepScreenLetterboxFill;
   const bool wantFill = (fillMode != CrossPointSettings::SLEEP_SCREEN_LETTERBOX_FILL::LETTERBOX_NONE);
-  const int targetColor =
-      (SETTINGS.sleepScreenGradientDir == CrossPointSettings::SLEEP_SCREEN_GRADIENT_DIR::GRADIENT_TO_BLACK) ? 0 : 255;
 
-  static const char* fillModeNames[] = {"none", "solid", "blended", "gradient"};
-  const char* fillModeName = (fillMode < 4) ? fillModeNames[fillMode] : "unknown";
+  static const char* fillModeNames[] = {"dithered", "solid", "none"};
+  const char* fillModeName = (fillMode < 3) ? fillModeNames[fillMode] : "unknown";
 
-  // Load cached edge data or sample from bitmap (first pass over bitmap, then rewind)
-  LetterboxGradientData gradientData;
+  // Compute edge averages if letterbox fill is requested (try cache first)
+  LetterboxFillData fillData;
   const bool hasLetterbox = (x > 0 || y > 0);
   if (hasLetterbox && wantFill) {
     bool cacheLoaded = false;
     if (!edgeCachePath.empty()) {
-      cacheLoaded = loadEdgeCache(edgeCachePath, pageWidth, pageHeight, gradientData);
+      cacheLoaded = loadEdgeCache(edgeCachePath, pageWidth, pageHeight, fillData);
     }
     if (!cacheLoaded) {
-      Serial.printf("[%lu] [SLP] Letterbox detected (x=%d, y=%d), sampling edges for %s fill\n", millis(), x, y,
-                    fillModeName);
-      gradientData = sampleBitmapEdges(bitmap, x, y, pageWidth, pageHeight, scale, cropX, cropY);
-      if (!edgeCachePath.empty() && gradientData.edgeA) {
-        saveEdgeCache(edgeCachePath, pageWidth, pageHeight, gradientData);
+      LOG_DBG("SLP", "Letterbox detected (x=%d, y=%d), computing edge averages for %s fill", x, y, fillModeName);
+      fillData = computeEdgeAverages(bitmap, x, y, pageWidth, pageHeight, scale, cropX, cropY);
+      if (fillData.valid && !edgeCachePath.empty()) {
+        saveEdgeCache(edgeCachePath, pageWidth, pageHeight, fillData);
       }
     }
+    if (fillData.valid) {
+      LOG_DBG("SLP", "Letterbox fill: %s, horizontal=%d, avgA=%d, avgB=%d, letterboxA=%d, letterboxB=%d",
+              fillModeName, fillData.horizontal, fillData.avgA, fillData.avgB, fillData.letterboxA,
+              fillData.letterboxB);
+    }
   }
 
   renderer.clearScreen();
@@ -560,8 +534,8 @@ void SleepActivity::renderBitmapSleepScreen(const Bitmap& bitmap, const std::str
                             SETTINGS.sleepScreenCoverFilter == CrossPointSettings::SLEEP_SCREEN_COVER_FILTER::NO_FILTER;
 
   // Draw letterbox fill (BW pass)
-  if (gradientData.edgeA) {
-    drawLetterboxFill(renderer, gradientData, scale, fillMode, targetColor);
+  if (fillData.valid) {
+    drawLetterboxFill(renderer, fillData, fillMode);
   }
 
   renderer.drawBitmap(bitmap, x, y, pageWidth, pageHeight, cropX, cropY);
@@ -576,8 +550,8 @@ void SleepActivity::renderBitmapSleepScreen(const Bitmap& bitmap, const std::str
     bitmap.rewindToData();
     renderer.clearScreen(0x00);
     renderer.setRenderMode(GfxRenderer::GRAYSCALE_LSB);
-    if (gradientData.edgeA) {
-      drawLetterboxFill(renderer, gradientData, scale, fillMode, targetColor);
+    if (fillData.valid) {
+      drawLetterboxFill(renderer, fillData, fillMode);
     }
     renderer.drawBitmap(bitmap, x, y, pageWidth, pageHeight, cropX, cropY);
     renderer.copyGrayscaleLsbBuffers();
@@ -585,8 +559,8 @@ void SleepActivity::renderBitmapSleepScreen(const Bitmap& bitmap, const std::str
     bitmap.rewindToData();
     renderer.clearScreen(0x00);
     renderer.setRenderMode(GfxRenderer::GRAYSCALE_MSB);
-    if (gradientData.edgeA) {
-      drawLetterboxFill(renderer, gradientData, scale, fillMode, targetColor);
+    if (fillData.valid) {
+      drawLetterboxFill(renderer, fillData, fillMode);
     }
     renderer.drawBitmap(bitmap, x, y, pageWidth, pageHeight, cropX, cropY);
     renderer.copyGrayscaleMsbBuffers();
@@ -594,8 +568,6 @@ void SleepActivity::renderBitmapSleepScreen(const Bitmap& bitmap, const std::str
     renderer.displayGrayBuffer();
     renderer.setRenderMode(GfxRenderer::BW);
   }
-
-  gradientData.free();
 }
 
 void SleepActivity::renderCoverSleepScreen() const {
@@ -614,6 +586,7 @@ void SleepActivity::renderCoverSleepScreen() const {
   }
 
   std::string coverBmpPath;
+  std::string bookCachePath;
   bool cropped = SETTINGS.sleepScreenCoverMode == CrossPointSettings::SLEEP_SCREEN_COVER_MODE::CROP;
 
   // Check if the current book is XTC, TXT, or EPUB
@@ -622,61 +595,90 @@ void SleepActivity::renderCoverSleepScreen() const {
     // Handle XTC file
     Xtc lastXtc(APP_STATE.openEpubPath, "/.crosspoint");
     if (!lastXtc.load()) {
-      Serial.println("[SLP] Failed to load last XTC");
+      LOG_ERR("SLP", "Failed to load last XTC");
       return (this->*renderNoCoverSleepScreen)();
     }
 
     if (!lastXtc.generateCoverBmp()) {
-      Serial.println("[SLP] Failed to generate XTC cover bmp");
+      LOG_DBG("SLP", "XTC cover generation failed, trying placeholder");
+      PlaceholderCoverGenerator::generate(lastXtc.getCoverBmpPath(), lastXtc.getTitle(), lastXtc.getAuthor(), 480, 800);
+    }
+
+    if (!Storage.exists(lastXtc.getCoverBmpPath().c_str())) {
+      LOG_ERR("SLP", "Failed to generate XTC cover bmp");
       return (this->*renderNoCoverSleepScreen)();
     }
 
     coverBmpPath = lastXtc.getCoverBmpPath();
+    bookCachePath = lastXtc.getCachePath();
   } else if (StringUtils::checkFileExtension(APP_STATE.openEpubPath, ".txt")) {
     // Handle TXT file - looks for cover image in the same folder
     Txt lastTxt(APP_STATE.openEpubPath, "/.crosspoint");
     if (!lastTxt.load()) {
-      Serial.println("[SLP] Failed to load last TXT");
+      LOG_ERR("SLP", "Failed to load last TXT");
       return (this->*renderNoCoverSleepScreen)();
     }
 
     if (!lastTxt.generateCoverBmp()) {
-      Serial.println("[SLP] No cover image found for TXT file");
+      LOG_DBG("SLP", "TXT cover generation failed, trying placeholder");
+      PlaceholderCoverGenerator::generate(lastTxt.getCoverBmpPath(), lastTxt.getTitle(), "", 480, 800);
+    }
+
+    if (!Storage.exists(lastTxt.getCoverBmpPath().c_str())) {
+      LOG_ERR("SLP", "No cover image found for TXT file");
       return (this->*renderNoCoverSleepScreen)();
     }
 
     coverBmpPath = lastTxt.getCoverBmpPath();
+    bookCachePath = lastTxt.getCachePath();
   } else if (StringUtils::checkFileExtension(APP_STATE.openEpubPath, ".epub")) {
     // Handle EPUB file
     Epub lastEpub(APP_STATE.openEpubPath, "/.crosspoint");
     // Skip loading css since we only need metadata here
     if (!lastEpub.load(true, true)) {
-      Serial.println("[SLP] Failed to load last epub");
+      LOG_ERR("SLP", "Failed to load last epub");
       return (this->*renderNoCoverSleepScreen)();
     }
 
     if (!lastEpub.generateCoverBmp(cropped)) {
-      Serial.println("[SLP] Failed to generate cover bmp");
+      LOG_DBG("SLP", "EPUB cover generation failed, trying placeholder");
+      if (!PlaceholderCoverGenerator::generate(lastEpub.getCoverBmpPath(cropped), lastEpub.getTitle(),
+                                               lastEpub.getAuthor(), 480, 800)) {
+        LOG_DBG("SLP", "Placeholder generation failed, creating X-pattern marker");
+        lastEpub.generateInvalidFormatCoverBmp(cropped);
+      }
+    }
+
+    if (!Epub::isValidThumbnailBmp(lastEpub.getCoverBmpPath(cropped))) {
+      LOG_ERR("SLP", "Failed to generate cover bmp");
       return (this->*renderNoCoverSleepScreen)();
     }
 
     coverBmpPath = lastEpub.getCoverBmpPath(cropped);
+    bookCachePath = lastEpub.getCachePath();
   } else {
     return (this->*renderNoCoverSleepScreen)();
   }
 
-  // Derive edge cache path from cover BMP path (e.g. cover.bmp -> cover_edges.bin)
-  std::string edgeCachePath;
-  if (coverBmpPath.size() > 4) {
-    edgeCachePath = coverBmpPath.substr(0, coverBmpPath.size() - 4) + "_edges.bin";
+  // Load per-book letterbox fill override (falls back to global if not set)
+  uint8_t fillModeOverride = BookSettings::USE_GLOBAL;
+  if (!bookCachePath.empty()) {
+    auto bookSettings = BookSettings::load(bookCachePath);
+    fillModeOverride = bookSettings.letterboxFillOverride;
   }
 
   FsFile file;
   if (Storage.openFileForRead("SLP", coverBmpPath, file)) {
     Bitmap bitmap(file);
     if (bitmap.parseHeaders() == BmpReaderError::Ok) {
-      Serial.printf("[SLP] Rendering sleep cover: %s\n", coverBmpPath.c_str());
-      renderBitmapSleepScreen(bitmap, edgeCachePath);
+      LOG_DBG("SLP", "Rendering sleep cover: %s", coverBmpPath.c_str());
+      // Derive edge cache path from cover BMP path (e.g. cover.bmp -> cover_edges.bin)
+      std::string edgeCachePath;
+      const auto dotPos = coverBmpPath.rfind(".bmp");
+      if (dotPos != std::string::npos) {
+        edgeCachePath = coverBmpPath.substr(0, dotPos) + "_edges.bin";
+      }
+      renderBitmapSleepScreen(bitmap, edgeCachePath, fillModeOverride);
       return;
     }
   }

src/activities/boot_sleep/SleepActivity.h

@@ -1,4 +1,5 @@
 #pragma once
+
 #include <string>
 
 #include "../Activity.h"
@@ -15,6 +16,8 @@ class SleepActivity final : public Activity {
   void renderDefaultSleepScreen() const;
   void renderCustomSleepScreen() const;
   void renderCoverSleepScreen() const;
-  void renderBitmapSleepScreen(const Bitmap& bitmap, const std::string& edgeCachePath = "") const;
+  // fillModeOverride: 0xFF = use global setting, otherwise a SLEEP_SCREEN_LETTERBOX_FILL value.
+  void renderBitmapSleepScreen(const Bitmap& bitmap, const std::string& edgeCachePath = "",
+                               uint8_t fillModeOverride = 0xFF) const;
   void renderBlankSleepScreen() const;
 };

src/activities/browser/OpdsBookBrowserActivity.cpp

@@ -2,7 +2,7 @@
 
 #include <Epub.h>
 #include <GfxRenderer.h>
-#include <HardwareSerial.h>
+#include <Logging.h>
 #include <OpdsStream.h>
 #include <WiFi.h>
 
@@ -17,7 +17,6 @@
 
 namespace {
 constexpr int PAGE_ITEMS = 23;
-constexpr int SKIP_PAGE_MS = 700;
 }  // namespace
 
 void OpdsBookBrowserActivity::taskTrampoline(void* param) {
@@ -79,14 +78,14 @@ void OpdsBookBrowserActivity::loop() {
       // Check if WiFi is still connected
       if (WiFi.status() == WL_CONNECTED && WiFi.localIP() != IPAddress(0, 0, 0, 0)) {
         // WiFi connected - just retry fetching the feed
-        Serial.printf("[%lu] [OPDS] Retry: WiFi connected, retrying fetch\n", millis());
+        LOG_DBG("OPDS", "Retry: WiFi connected, retrying fetch");
         state = BrowserState::LOADING;
         statusMessage = "Loading...";
         updateRequired = true;
         fetchFeed(currentPath);
       } else {
         // WiFi not connected - launch WiFi selection
-        Serial.printf("[%lu] [OPDS] Retry: WiFi not connected, launching selection\n", millis());
+        LOG_DBG("OPDS", "Retry: WiFi not connected, launching selection");
         launchWifiSelection();
       }
     } else if (mappedInput.wasReleased(MappedInputManager::Button::Back)) {
@@ -118,12 +117,6 @@ void OpdsBookBrowserActivity::loop() {
 
   // Handle browsing state
   if (state == BrowserState::BROWSING) {
-    const bool prevReleased = mappedInput.wasReleased(MappedInputManager::Button::Up) ||
-                              mappedInput.wasReleased(MappedInputManager::Button::Left);
-    const bool nextReleased = mappedInput.wasReleased(MappedInputManager::Button::Down) ||
-                              mappedInput.wasReleased(MappedInputManager::Button::Right);
-    const bool skipPage = mappedInput.getHeldTime() > SKIP_PAGE_MS;
-
     if (mappedInput.wasReleased(MappedInputManager::Button::Confirm)) {
       if (!entries.empty()) {
         const auto& entry = entries[selectorIndex];
@@ -135,20 +128,29 @@ void OpdsBookBrowserActivity::loop() {
       }
     } else if (mappedInput.wasReleased(MappedInputManager::Button::Back)) {
       navigateBack();
-    } else if (prevReleased && !entries.empty()) {
-      if (skipPage) {
-        selectorIndex = ((selectorIndex / PAGE_ITEMS - 1) * PAGE_ITEMS + entries.size()) % entries.size();
-      } else {
-        selectorIndex = (selectorIndex + entries.size() - 1) % entries.size();
-      }
-      updateRequired = true;
-    } else if (nextReleased && !entries.empty()) {
-      if (skipPage) {
-        selectorIndex = ((selectorIndex / PAGE_ITEMS + 1) * PAGE_ITEMS) % entries.size();
-      } else {
-        selectorIndex = (selectorIndex + 1) % entries.size();
-      }
-      updateRequired = true;
+    }
+
+    // Handle navigation
+    if (!entries.empty()) {
+      buttonNavigator.onNextRelease([this] {
+        selectorIndex = ButtonNavigator::nextIndex(selectorIndex, entries.size());
+        updateRequired = true;
+      });
+
+      buttonNavigator.onPreviousRelease([this] {
+        selectorIndex = ButtonNavigator::previousIndex(selectorIndex, entries.size());
+        updateRequired = true;
+      });
+
+      buttonNavigator.onNextContinuous([this] {
+        selectorIndex = ButtonNavigator::nextPageIndex(selectorIndex, entries.size(), PAGE_ITEMS);
+        updateRequired = true;
+      });
+
+      buttonNavigator.onPreviousContinuous([this] {
+        selectorIndex = ButtonNavigator::previousPageIndex(selectorIndex, entries.size(), PAGE_ITEMS);
+        updateRequired = true;
+      });
     }
   }
 }
@@ -263,7 +265,7 @@ void OpdsBookBrowserActivity::fetchFeed(const std::string& path) {
   }
 
   std::string url = UrlUtils::buildUrl(serverUrl, path);
-  Serial.printf("[%lu] [OPDS] Fetching: %s\n", millis(), url.c_str());
+  LOG_DBG("OPDS", "Fetching: %s", url.c_str());
 
   OpdsParser parser;
 
@@ -285,7 +287,7 @@ void OpdsBookBrowserActivity::fetchFeed(const std::string& path) {
   }
 
   entries = std::move(parser).getEntries();
-  Serial.printf("[%lu] [OPDS] Found %d entries\n", millis(), entries.size());
+  LOG_DBG("OPDS", "Found %d entries", entries.size());
   selectorIndex = 0;
 
   if (entries.empty()) {
@@ -349,7 +351,7 @@ void OpdsBookBrowserActivity::downloadBook(const OpdsEntry& book) {
   }
   std::string filename = "/" + StringUtils::sanitizeFilename(baseName) + ".epub";
 
-  Serial.printf("[%lu] [OPDS] Downloading: %s -> %s\n", millis(), downloadUrl.c_str(), filename.c_str());
+  LOG_DBG("OPDS", "Downloading: %s -> %s", downloadUrl.c_str(), filename.c_str());
 
   const auto result =
       HttpDownloader::downloadToFile(downloadUrl, filename, [this](const size_t downloaded, const size_t total) {
@@ -359,12 +361,12 @@ void OpdsBookBrowserActivity::downloadBook(const OpdsEntry& book) {
       });
 
   if (result == HttpDownloader::OK) {
-    Serial.printf("[%lu] [OPDS] Download complete: %s\n", millis(), filename.c_str());
+    LOG_DBG("OPDS", "Download complete: %s", filename.c_str());
 
     // Invalidate any existing cache for this file to prevent stale metadata issues
     Epub epub(filename, "/.crosspoint");
     epub.clearCache();
-    Serial.printf("[%lu] [OPDS] Cleared cache for: %s\n", millis(), filename.c_str());
+    LOG_DBG("OPDS", "Cleared cache for: %s", filename.c_str());
 
     state = BrowserState::BROWSING;
     updateRequired = true;
@@ -401,13 +403,13 @@ void OpdsBookBrowserActivity::onWifiSelectionComplete(const bool connected) {
   exitActivity();
 
   if (connected) {
-    Serial.printf("[%lu] [OPDS] WiFi connected via selection, fetching feed\n", millis());
+    LOG_DBG("OPDS", "WiFi connected via selection, fetching feed");
     state = BrowserState::LOADING;
     statusMessage = "Loading...";
     updateRequired = true;
     fetchFeed(currentPath);
   } else {
-    Serial.printf("[%lu] [OPDS] WiFi selection cancelled/failed\n", millis());
+    LOG_DBG("OPDS", "WiFi selection cancelled/failed");
     // Force disconnect to ensure clean state for next retry
     // This prevents stale connection status from interfering
     WiFi.disconnect();

src/activities/browser/OpdsBookBrowserActivity.h

@@ -9,6 +9,7 @@
 #include <vector>
 
 #include "../ActivityWithSubactivity.h"
+#include "util/ButtonNavigator.h"
 
 /**
  * Activity for browsing and downloading books from an OPDS server.
@@ -37,6 +38,7 @@ class OpdsBookBrowserActivity final : public ActivityWithSubactivity {
  private:
   TaskHandle_t displayTaskHandle = nullptr;
   SemaphoreHandle_t renderingMutex = nullptr;
+  ButtonNavigator buttonNavigator;
   bool updateRequired = false;
 
   BrowserState state = BrowserState::LOADING;
@@ -62,4 +64,5 @@ class OpdsBookBrowserActivity final : public ActivityWithSubactivity {
   void navigateToEntry(const OpdsEntry& entry);
   void navigateBack();
   void downloadBook(const OpdsEntry& book);
+  bool preventAutoSleep() override { return true; }
 };

src/activities/home/HomeActivity.cpp

@@ -5,6 +5,7 @@
 #include <GfxRenderer.h>
 #include <HalStorage.h>
 #include <Utf8.h>
+#include <PlaceholderCoverGenerator.h>
 #include <Xtc.h>
 
 #include <cstring>
@@ -64,46 +65,61 @@ void HomeActivity::loadRecentCovers(int coverHeight) {
   for (RecentBook& book : recentBooks) {
     if (!book.coverBmpPath.empty()) {
       std::string coverPath = UITheme::getCoverThumbPath(book.coverBmpPath, coverHeight);
-      if (!Storage.exists(coverPath.c_str())) {
-        // If epub, try to load the metadata for title/author and cover
+      if (!Epub::isValidThumbnailBmp(coverPath)) {
+        if (!showingLoading) {
+          showingLoading = true;
+          popupRect = GUI.drawPopup(renderer, "Loading...");
+        }
+        GUI.fillPopupProgress(renderer, popupRect, 10 + progress * (90 / recentBooks.size()));
+
+        bool success = false;
+
+        // Try format-specific thumbnail generation first (Real Cover)
         if (StringUtils::checkFileExtension(book.path, ".epub")) {
           Epub epub(book.path, "/.crosspoint");
-          // Skip loading css since we only need metadata here
-          epub.load(false, true);
-
-          // Try to generate thumbnail image for Continue Reading card
-          if (!showingLoading) {
-            showingLoading = true;
-            popupRect = GUI.drawPopup(renderer, "Loading...");
+          // Try fast cache-only load first; only build cache if missing
+          if (!epub.load(false, true)) {
+            // Cache missing — build it (may take longer)
+            epub.load(true, true);
           }
-          GUI.fillPopupProgress(renderer, popupRect, 10 + progress * (90 / recentBooks.size()));
-          bool success = epub.generateThumbBmp(coverHeight);
-          if (!success) {
-            RECENT_BOOKS.updateBook(book.path, book.title, book.author, "");
-            book.coverBmpPath = "";
+          success = epub.generateThumbBmp(coverHeight);
+          if (success) {
+            const std::string thumbPath = epub.getThumbBmpPath(coverHeight);
+            RECENT_BOOKS.updateBook(book.path, book.title, book.author, thumbPath);
+            book.coverBmpPath = thumbPath;
+          } else {
+            // Fallback: generate a placeholder thumbnail with title/author
+            const int thumbWidth = static_cast<int>(coverHeight * 0.6);
+            success = PlaceholderCoverGenerator::generate(coverPath, book.title, book.author, thumbWidth, coverHeight);
+            if (!success) {
+              // Last resort: X-pattern marker to prevent repeated generation attempts
+              epub.generateInvalidFormatThumbBmp(coverHeight);
+            }
           }
-          coverRendered = false;
-          updateRequired = true;
         } else if (StringUtils::checkFileExtension(book.path, ".xtch") ||
                    StringUtils::checkFileExtension(book.path, ".xtc")) {
-          // Handle XTC file
           Xtc xtc(book.path, "/.crosspoint");
           if (xtc.load()) {
-            // Try to generate thumbnail image for Continue Reading card
-            if (!showingLoading) {
-              showingLoading = true;
-              popupRect = GUI.drawPopup(renderer, "Loading...");
+            success = xtc.generateThumbBmp(coverHeight);
+            if (success) {
+              const std::string thumbPath = xtc.getThumbBmpPath(coverHeight);
+              RECENT_BOOKS.updateBook(book.path, book.title, book.author, thumbPath);
+              book.coverBmpPath = thumbPath;
             }
-            GUI.fillPopupProgress(renderer, popupRect, 10 + progress * (90 / recentBooks.size()));
-            bool success = xtc.generateThumbBmp(coverHeight);
-            if (!success) {
-              RECENT_BOOKS.updateBook(book.path, book.title, book.author, "");
-              book.coverBmpPath = "";
-            }
-            coverRendered = false;
-            updateRequired = true;
           }
+          if (!success) {
+            // Fallback: generate a placeholder thumbnail with title/author
+            const int thumbWidth = static_cast<int>(coverHeight * 0.6);
+            PlaceholderCoverGenerator::generate(coverPath, book.title, book.author, thumbWidth, coverHeight);
+          }
+        } else {
+          // Unknown format: generate a placeholder thumbnail
+          const int thumbWidth = static_cast<int>(coverHeight * 0.6);
+          PlaceholderCoverGenerator::generate(coverPath, book.title, book.author, thumbWidth, coverHeight);
         }
+
+        coverRendered = false;
+        updateRequired = true;
       }
     }
     progress++;
@@ -196,13 +212,18 @@ void HomeActivity::freeCoverBuffer() {
 }
 
 void HomeActivity::loop() {
-  const bool prevPressed = mappedInput.wasPressed(MappedInputManager::Button::Up) ||
-                           mappedInput.wasPressed(MappedInputManager::Button::Left);
-  const bool nextPressed = mappedInput.wasPressed(MappedInputManager::Button::Down) ||
-                           mappedInput.wasPressed(MappedInputManager::Button::Right);
-
   const int menuCount = getMenuItemCount();
 
+  buttonNavigator.onNext([this, menuCount] {
+    selectorIndex = ButtonNavigator::nextIndex(selectorIndex, menuCount);
+    updateRequired = true;
+  });
+
+  buttonNavigator.onPrevious([this, menuCount] {
+    selectorIndex = ButtonNavigator::previousIndex(selectorIndex, menuCount);
+    updateRequired = true;
+  });
+
   if (mappedInput.wasReleased(MappedInputManager::Button::Confirm)) {
     // Calculate dynamic indices based on which options are available
     int idx = 0;
@@ -226,12 +247,6 @@ void HomeActivity::loop() {
     } else if (menuSelectedIndex == settingsIdx) {
       onSettingsOpen();
     }
-  } else if (prevPressed) {
-    selectorIndex = (selectorIndex + menuCount - 1) % menuCount;
-    updateRequired = true;
-  } else if (nextPressed) {
-    selectorIndex = (selectorIndex + 1) % menuCount;
-    updateRequired = true;
   }
 }
 

src/activities/home/HomeActivity.h

@@ -8,6 +8,7 @@
 
 #include "../Activity.h"
 #include "./MyLibraryActivity.h"
+#include "util/ButtonNavigator.h"
 
 struct RecentBook;
 struct Rect;
@@ -15,6 +16,7 @@ struct Rect;
 class HomeActivity final : public Activity {
   TaskHandle_t displayTaskHandle = nullptr;
   SemaphoreHandle_t renderingMutex = nullptr;
+  ButtonNavigator buttonNavigator;
   int selectorIndex = 0;
   bool updateRequired = false;
   bool recentsLoading = false;

src/activities/home/MyLibraryActivity.cpp

@@ -11,17 +11,58 @@
 #include "util/StringUtils.h"
 
 namespace {
-constexpr int SKIP_PAGE_MS = 700;
 constexpr unsigned long GO_HOME_MS = 1000;
 }  // namespace
 
 void sortFileList(std::vector<std::string>& strs) {
   std::sort(begin(strs), end(strs), [](const std::string& str1, const std::string& str2) {
-    if (str1.back() == '/' && str2.back() != '/') return true;
-    if (str1.back() != '/' && str2.back() == '/') return false;
-    return lexicographical_compare(
-        begin(str1), end(str1), begin(str2), end(str2),
-        [](const char& char1, const char& char2) { return tolower(char1) < tolower(char2); });
+    // Directories first
+    bool isDir1 = str1.back() == '/';
+    bool isDir2 = str2.back() == '/';
+    if (isDir1 != isDir2) return isDir1;
+
+    // Start naive natural sort
+    const char* s1 = str1.c_str();
+    const char* s2 = str2.c_str();
+
+    // Iterate while both strings have characters
+    while (*s1 && *s2) {
+      // Check if both are at the start of a number
+      if (isdigit(*s1) && isdigit(*s2)) {
+        // Skip leading zeros and track them
+        const char* start1 = s1;
+        const char* start2 = s2;
+        while (*s1 == '0') s1++;
+        while (*s2 == '0') s2++;
+
+        // Count digits to compare lengths first
+        int len1 = 0, len2 = 0;
+        while (isdigit(s1[len1])) len1++;
+        while (isdigit(s2[len2])) len2++;
+
+        // Different length so return smaller integer value
+        if (len1 != len2) return len1 < len2;
+
+        // Same length so compare digit by digit
+        for (int i = 0; i < len1; i++) {
+          if (s1[i] != s2[i]) return s1[i] < s2[i];
+        }
+
+        // Numbers equal so advance pointers
+        s1 += len1;
+        s2 += len2;
+      } else {
+        // Regular case-insensitive character comparison
+        char c1 = tolower(*s1);
+        char c2 = tolower(*s2);
+        if (c1 != c2) return c1 < c2;
+        s1++;
+        s2++;
+      }
+    }
+
+    // One string is prefix of other
+    return *s1 == '\0' && *s2 != '\0';
   });
 }
 
@@ -109,13 +150,6 @@ void MyLibraryActivity::loop() {
     return;
   }
 
-  const bool upReleased = mappedInput.wasReleased(MappedInputManager::Button::Left) ||
-                          mappedInput.wasReleased(MappedInputManager::Button::Up);
-  ;
-  const bool downReleased = mappedInput.wasReleased(MappedInputManager::Button::Right) ||
-                            mappedInput.wasReleased(MappedInputManager::Button::Down);
-
-  const bool skipPage = mappedInput.getHeldTime() > SKIP_PAGE_MS;
   const int pageItems = UITheme::getInstance().getNumberOfItemsPerPage(renderer, true, false, true, false);
 
   if (mappedInput.wasReleased(MappedInputManager::Button::Confirm)) {
@@ -157,21 +191,26 @@ void MyLibraryActivity::loop() {
   }
 
   int listSize = static_cast<int>(files.size());
-  if (upReleased) {
-    if (skipPage) {
-      selectorIndex = std::max(static_cast<int>((selectorIndex / pageItems - 1) * pageItems), 0);
-    } else {
-      selectorIndex = (selectorIndex + listSize - 1) % listSize;
-    }
+
+  buttonNavigator.onNextRelease([this, listSize] {
+    selectorIndex = ButtonNavigator::nextIndex(static_cast<int>(selectorIndex), listSize);
     updateRequired = true;
-  } else if (downReleased) {
-    if (skipPage) {
-      selectorIndex = std::min(static_cast<int>((selectorIndex / pageItems + 1) * pageItems), listSize - 1);
-    } else {
-      selectorIndex = (selectorIndex + 1) % listSize;
-    }
+  });
+
+  buttonNavigator.onPreviousRelease([this, listSize] {
+    selectorIndex = ButtonNavigator::previousIndex(static_cast<int>(selectorIndex), listSize);
     updateRequired = true;
-  }
+  });
+
+  buttonNavigator.onNextContinuous([this, listSize, pageItems] {
+    selectorIndex = ButtonNavigator::nextPageIndex(static_cast<int>(selectorIndex), listSize, pageItems);
+    updateRequired = true;
+  });
+
+  buttonNavigator.onPreviousContinuous([this, listSize, pageItems] {
+    selectorIndex = ButtonNavigator::previousPageIndex(static_cast<int>(selectorIndex), listSize, pageItems);
+    updateRequired = true;
+  });
 }
 
 void MyLibraryActivity::displayTaskLoop() {
@@ -207,7 +246,7 @@ void MyLibraryActivity::render() const {
   }
 
   // Help text
-  const auto labels = mappedInput.mapLabels("« Home", "Open", "Up", "Down");
+  const auto labels = mappedInput.mapLabels(basepath == "/" ? "« Home" : "« Back", "Open", "Up", "Down");
   GUI.drawButtonHints(renderer, labels.btn1, labels.btn2, labels.btn3, labels.btn4);
 
   renderer.displayBuffer();
@@ -217,4 +256,4 @@ size_t MyLibraryActivity::findEntry(const std::string& name) const {
   for (size_t i = 0; i < files.size(); i++)
     if (files[i] == name) return i;
   return 0;
-}
+}

src/activities/home/MyLibraryActivity.h

@@ -8,11 +8,14 @@
 #include <vector>
 
 #include "../Activity.h"
+#include "RecentBooksStore.h"
+#include "util/ButtonNavigator.h"
 
 class MyLibraryActivity final : public Activity {
  private:
   TaskHandle_t displayTaskHandle = nullptr;
   SemaphoreHandle_t renderingMutex = nullptr;
+  ButtonNavigator buttonNavigator;
 
   size_t selectorIndex = 0;
   bool updateRequired = false;

src/activities/home/RecentBooksActivity.cpp

@@ -12,7 +12,6 @@
 #include "util/StringUtils.h"
 
 namespace {
-constexpr int SKIP_PAGE_MS = 700;
 constexpr unsigned long GO_HOME_MS = 1000;
 }  // namespace
 
@@ -70,18 +69,11 @@ void RecentBooksActivity::onExit() {
 }
 
 void RecentBooksActivity::loop() {
-  const bool upReleased = mappedInput.wasReleased(MappedInputManager::Button::Left) ||
-                          mappedInput.wasReleased(MappedInputManager::Button::Up);
-  ;
-  const bool downReleased = mappedInput.wasReleased(MappedInputManager::Button::Right) ||
-                            mappedInput.wasReleased(MappedInputManager::Button::Down);
-
-  const bool skipPage = mappedInput.getHeldTime() > SKIP_PAGE_MS;
   const int pageItems = UITheme::getInstance().getNumberOfItemsPerPage(renderer, true, false, true, true);
 
   if (mappedInput.wasReleased(MappedInputManager::Button::Confirm)) {
     if (!recentBooks.empty() && selectorIndex < static_cast<int>(recentBooks.size())) {
-      Serial.printf("Selected recent book: %s\n", recentBooks[selectorIndex].path.c_str());
+      LOG_DBG("RBA", "Selected recent book: %s", recentBooks[selectorIndex].path.c_str());
       onSelectBook(recentBooks[selectorIndex].path);
       return;
     }
@@ -92,21 +84,26 @@ void RecentBooksActivity::loop() {
   }
 
   int listSize = static_cast<int>(recentBooks.size());
-  if (upReleased) {
-    if (skipPage) {
-      selectorIndex = std::max(static_cast<int>((selectorIndex / pageItems - 1) * pageItems), 0);
-    } else {
-      selectorIndex = (selectorIndex + listSize - 1) % listSize;
-    }
+
+  buttonNavigator.onNextRelease([this, listSize] {
+    selectorIndex = ButtonNavigator::nextIndex(static_cast<int>(selectorIndex), listSize);
     updateRequired = true;
-  } else if (downReleased) {
-    if (skipPage) {
-      selectorIndex = std::min(static_cast<int>((selectorIndex / pageItems + 1) * pageItems), listSize - 1);
-    } else {
-      selectorIndex = (selectorIndex + 1) % listSize;
-    }
+  });
+
+  buttonNavigator.onPreviousRelease([this, listSize] {
+    selectorIndex = ButtonNavigator::previousIndex(static_cast<int>(selectorIndex), listSize);
     updateRequired = true;
-  }
+  });
+
+  buttonNavigator.onNextContinuous([this, listSize, pageItems] {
+    selectorIndex = ButtonNavigator::nextPageIndex(static_cast<int>(selectorIndex), listSize, pageItems);
+    updateRequired = true;
+  });
+
+  buttonNavigator.onPreviousContinuous([this, listSize, pageItems] {
+    selectorIndex = ButtonNavigator::previousPageIndex(static_cast<int>(selectorIndex), listSize, pageItems);
+    updateRequired = true;
+  });
 }
 
 void RecentBooksActivity::displayTaskLoop() {

src/activities/home/RecentBooksActivity.h

@@ -9,11 +9,13 @@
 
 #include "../Activity.h"
 #include "RecentBooksStore.h"
+#include "util/ButtonNavigator.h"
 
 class RecentBooksActivity final : public Activity {
  private:
   TaskHandle_t displayTaskHandle = nullptr;
   SemaphoreHandle_t renderingMutex = nullptr;
+  ButtonNavigator buttonNavigator;
 
   size_t selectorIndex = 0;
   bool updateRequired = false;

src/activities/network/CalibreConnectActivity.cpp

@@ -96,7 +96,7 @@ void CalibreConnectActivity::startWebServer() {
 
   if (MDNS.begin(HOSTNAME)) {
     // mDNS is optional for the Calibre plugin but still helpful for users.
-    Serial.printf("[%lu] [CAL] mDNS started: http://%s.local/\n", millis(), HOSTNAME);
+    LOG_DBG("CAL", "mDNS started: http://%s.local/", HOSTNAME);
   }
 
   webServer.reset(new CrossPointWebServer());
@@ -131,7 +131,7 @@ void CalibreConnectActivity::loop() {
   if (webServer && webServer->isRunning()) {
     const unsigned long timeSinceLastHandleClient = millis() - lastHandleClientTime;
     if (lastHandleClientTime > 0 && timeSinceLastHandleClient > 100) {
-      Serial.printf("[%lu] [CAL] WARNING: %lu ms gap since last handleClient\n", millis(), timeSinceLastHandleClient);
+      LOG_DBG("CAL", "WARNING: %lu ms gap since last handleClient", timeSinceLastHandleClient);
     }
 
     esp_task_wdt_reset();

src/activities/network/CrossPointWebServerActivity.cpp

@@ -37,7 +37,7 @@ void CrossPointWebServerActivity::taskTrampoline(void* param) {
 void CrossPointWebServerActivity::onEnter() {
   ActivityWithSubactivity::onEnter();
 
-  Serial.printf("[%lu] [WEBACT] [MEM] Free heap at onEnter: %d bytes\n", millis(), ESP.getFreeHeap());
+  LOG_DBG("WEBACT] [MEM", "Free heap at onEnter: %d bytes", ESP.getFreeHeap());
 
   renderingMutex = xSemaphoreCreateMutex();
 
@@ -58,7 +58,7 @@ void CrossPointWebServerActivity::onEnter() {
   );
 
   // Launch network mode selection subactivity
-  Serial.printf("[%lu] [WEBACT] Launching NetworkModeSelectionActivity...\n", millis());
+  LOG_DBG("WEBACT", "Launching NetworkModeSelectionActivity...");
   enterNewActivity(new NetworkModeSelectionActivity(
       renderer, mappedInput, [this](const NetworkMode mode) { onNetworkModeSelected(mode); },
       [this]() { onGoBack(); }  // Cancel goes back to home
@@ -68,7 +68,7 @@ void CrossPointWebServerActivity::onEnter() {
 void CrossPointWebServerActivity::onExit() {
   ActivityWithSubactivity::onExit();
 
-  Serial.printf("[%lu] [WEBACT] [MEM] Free heap at onExit start: %d bytes\n", millis(), ESP.getFreeHeap());
+  LOG_DBG("WEBACT] [MEM", "Free heap at onExit start: %d bytes", ESP.getFreeHeap());
 
   state = WebServerActivityState::SHUTTING_DOWN;
 
@@ -80,7 +80,7 @@ void CrossPointWebServerActivity::onExit() {
 
   // Stop DNS server if running (AP mode)
   if (dnsServer) {
-    Serial.printf("[%lu] [WEBACT] Stopping DNS server...\n", millis());
+    LOG_DBG("WEBACT", "Stopping DNS server...");
     dnsServer->stop();
     delete dnsServer;
     dnsServer = nullptr;
@@ -91,39 +91,39 @@ void CrossPointWebServerActivity::onExit() {
 
   // Disconnect WiFi gracefully
   if (isApMode) {
-    Serial.printf("[%lu] [WEBACT] Stopping WiFi AP...\n", millis());
+    LOG_DBG("WEBACT", "Stopping WiFi AP...");
     WiFi.softAPdisconnect(true);
   } else {
-    Serial.printf("[%lu] [WEBACT] Disconnecting WiFi (graceful)...\n", millis());
+    LOG_DBG("WEBACT", "Disconnecting WiFi (graceful)...");
     WiFi.disconnect(false);  // false = don't erase credentials, send disconnect frame
   }
   delay(30);  // Allow disconnect frame to be sent
 
-  Serial.printf("[%lu] [WEBACT] Setting WiFi mode OFF...\n", millis());
+  LOG_DBG("WEBACT", "Setting WiFi mode OFF...");
   WiFi.mode(WIFI_OFF);
   delay(30);  // Allow WiFi hardware to power down
 
-  Serial.printf("[%lu] [WEBACT] [MEM] Free heap after WiFi disconnect: %d bytes\n", millis(), ESP.getFreeHeap());
+  LOG_DBG("WEBACT] [MEM", "Free heap after WiFi disconnect: %d bytes", ESP.getFreeHeap());
 
   // Acquire mutex before deleting task
-  Serial.printf("[%lu] [WEBACT] Acquiring rendering mutex before task deletion...\n", millis());
+  LOG_DBG("WEBACT", "Acquiring rendering mutex before task deletion...");
   xSemaphoreTake(renderingMutex, portMAX_DELAY);
 
   // Delete the display task
-  Serial.printf("[%lu] [WEBACT] Deleting display task...\n", millis());
+  LOG_DBG("WEBACT", "Deleting display task...");
   if (displayTaskHandle) {
     vTaskDelete(displayTaskHandle);
     displayTaskHandle = nullptr;
-    Serial.printf("[%lu] [WEBACT] Display task deleted\n", millis());
+    LOG_DBG("WEBACT", "Display task deleted");
   }
 
   // Delete the mutex
-  Serial.printf("[%lu] [WEBACT] Deleting mutex...\n", millis());
+  LOG_DBG("WEBACT", "Deleting mutex...");
   vSemaphoreDelete(renderingMutex);
   renderingMutex = nullptr;
-  Serial.printf("[%lu] [WEBACT] Mutex deleted\n", millis());
+  LOG_DBG("WEBACT", "Mutex deleted");
 
-  Serial.printf("[%lu] [WEBACT] [MEM] Free heap at onExit end: %d bytes\n", millis(), ESP.getFreeHeap());
+  LOG_DBG("WEBACT] [MEM", "Free heap at onExit end: %d bytes", ESP.getFreeHeap());
 }
 
 void CrossPointWebServerActivity::onNetworkModeSelected(const NetworkMode mode) {
@@ -133,7 +133,7 @@ void CrossPointWebServerActivity::onNetworkModeSelected(const NetworkMode mode)
   } else if (mode == NetworkMode::CREATE_HOTSPOT) {
     modeName = "Create Hotspot";
   }
-  Serial.printf("[%lu] [WEBACT] Network mode selected: %s\n", millis(), modeName);
+  LOG_DBG("WEBACT", "Network mode selected: %s", modeName);
 
   networkMode = mode;
   isApMode = (mode == NetworkMode::CREATE_HOTSPOT);
@@ -155,11 +155,11 @@ void CrossPointWebServerActivity::onNetworkModeSelected(const NetworkMode mode)
 
   if (mode == NetworkMode::JOIN_NETWORK) {
     // STA mode - launch WiFi selection
-    Serial.printf("[%lu] [WEBACT] Turning on WiFi (STA mode)...\n", millis());
+    LOG_DBG("WEBACT", "Turning on WiFi (STA mode)...");
     WiFi.mode(WIFI_STA);
 
     state = WebServerActivityState::WIFI_SELECTION;
-    Serial.printf("[%lu] [WEBACT] Launching WifiSelectionActivity...\n", millis());
+    LOG_DBG("WEBACT", "Launching WifiSelectionActivity...");
     enterNewActivity(new WifiSelectionActivity(renderer, mappedInput,
                                                [this](const bool connected) { onWifiSelectionComplete(connected); }));
   } else {
@@ -171,7 +171,7 @@ void CrossPointWebServerActivity::onNetworkModeSelected(const NetworkMode mode)
 }
 
 void CrossPointWebServerActivity::onWifiSelectionComplete(const bool connected) {
-  Serial.printf("[%lu] [WEBACT] WifiSelectionActivity completed, connected=%d\n", millis(), connected);
+  LOG_DBG("WEBACT", "WifiSelectionActivity completed, connected=%d", connected);
 
   if (connected) {
     // Get connection info before exiting subactivity
@@ -183,7 +183,7 @@ void CrossPointWebServerActivity::onWifiSelectionComplete(const bool connected)
 
     // Start mDNS for hostname resolution
     if (MDNS.begin(AP_HOSTNAME)) {
-      Serial.printf("[%lu] [WEBACT] mDNS started: http://%s.local/\n", millis(), AP_HOSTNAME);
+      LOG_DBG("WEBACT", "mDNS started: http://%s.local/", AP_HOSTNAME);
     }
 
     // Start the web server
@@ -199,8 +199,8 @@ void CrossPointWebServerActivity::onWifiSelectionComplete(const bool connected)
 }
 
 void CrossPointWebServerActivity::startAccessPoint() {
-  Serial.printf("[%lu] [WEBACT] Starting Access Point mode...\n", millis());
-  Serial.printf("[%lu] [WEBACT] [MEM] Free heap before AP start: %d bytes\n", millis(), ESP.getFreeHeap());
+  LOG_DBG("WEBACT", "Starting Access Point mode...");
+  LOG_DBG("WEBACT] [MEM", "Free heap before AP start: %d bytes", ESP.getFreeHeap());
 
   // Configure and start the AP
   WiFi.mode(WIFI_AP);
@@ -216,7 +216,7 @@ void CrossPointWebServerActivity::startAccessPoint() {
   }
 
   if (!apStarted) {
-    Serial.printf("[%lu] [WEBACT] ERROR: Failed to start Access Point!\n", millis());
+    LOG_ERR("WEBACT", "ERROR: Failed to start Access Point!");
     onGoBack();
     return;
   }
@@ -230,15 +230,15 @@ void CrossPointWebServerActivity::startAccessPoint() {
   connectedIP = ipStr;
   connectedSSID = AP_SSID;
 
-  Serial.printf("[%lu] [WEBACT] Access Point started!\n", millis());
-  Serial.printf("[%lu] [WEBACT] SSID: %s\n", millis(), AP_SSID);
-  Serial.printf("[%lu] [WEBACT] IP: %s\n", millis(), connectedIP.c_str());
+  LOG_DBG("WEBACT", "Access Point started!");
+  LOG_DBG("WEBACT", "SSID: %s", AP_SSID);
+  LOG_DBG("WEBACT", "IP: %s", connectedIP.c_str());
 
   // Start mDNS for hostname resolution
   if (MDNS.begin(AP_HOSTNAME)) {
-    Serial.printf("[%lu] [WEBACT] mDNS started: http://%s.local/\n", millis(), AP_HOSTNAME);
+    LOG_DBG("WEBACT", "mDNS started: http://%s.local/", AP_HOSTNAME);
   } else {
-    Serial.printf("[%lu] [WEBACT] WARNING: mDNS failed to start\n", millis());
+    LOG_DBG("WEBACT", "WARNING: mDNS failed to start");
   }
 
   // Start DNS server for captive portal behavior
@@ -246,16 +246,16 @@ void CrossPointWebServerActivity::startAccessPoint() {
   dnsServer = new DNSServer();
   dnsServer->setErrorReplyCode(DNSReplyCode::NoError);
   dnsServer->start(DNS_PORT, "*", apIP);
-  Serial.printf("[%lu] [WEBACT] DNS server started for captive portal\n", millis());
+  LOG_DBG("WEBACT", "DNS server started for captive portal");
 
-  Serial.printf("[%lu] [WEBACT] [MEM] Free heap after AP start: %d bytes\n", millis(), ESP.getFreeHeap());
+  LOG_DBG("WEBACT] [MEM", "Free heap after AP start: %d bytes", ESP.getFreeHeap());
 
   // Start the web server
   startWebServer();
 }
 
 void CrossPointWebServerActivity::startWebServer() {
-  Serial.printf("[%lu] [WEBACT] Starting web server...\n", millis());
+  LOG_DBG("WEBACT", "Starting web server...");
 
   // Create the web server instance
   webServer.reset(new CrossPointWebServer());
@@ -263,16 +263,16 @@ void CrossPointWebServerActivity::startWebServer() {
 
   if (webServer->isRunning()) {
     state = WebServerActivityState::SERVER_RUNNING;
-    Serial.printf("[%lu] [WEBACT] Web server started successfully\n", millis());
+    LOG_DBG("WEBACT", "Web server started successfully");
 
     // Force an immediate render since we're transitioning from a subactivity
     // that had its own rendering task. We need to make sure our display is shown.
     xSemaphoreTake(renderingMutex, portMAX_DELAY);
     render();
     xSemaphoreGive(renderingMutex);
-    Serial.printf("[%lu] [WEBACT] Rendered File Transfer screen\n", millis());
+    LOG_DBG("WEBACT", "Rendered File Transfer screen");
   } else {
-    Serial.printf("[%lu] [WEBACT] ERROR: Failed to start web server!\n", millis());
+    LOG_ERR("WEBACT", "ERROR: Failed to start web server!");
     webServer.reset();
     // Go back on error
     onGoBack();
@@ -281,9 +281,9 @@ void CrossPointWebServerActivity::startWebServer() {
 
 void CrossPointWebServerActivity::stopWebServer() {
   if (webServer && webServer->isRunning()) {
-    Serial.printf("[%lu] [WEBACT] Stopping web server...\n", millis());
+    LOG_DBG("WEBACT", "Stopping web server...");
     webServer->stop();
-    Serial.printf("[%lu] [WEBACT] Web server stopped\n", millis());
+    LOG_DBG("WEBACT", "Web server stopped");
   }
   webServer.reset();
 }
@@ -309,7 +309,7 @@ void CrossPointWebServerActivity::loop() {
         lastWifiCheck = millis();
         const wl_status_t wifiStatus = WiFi.status();
         if (wifiStatus != WL_CONNECTED) {
-          Serial.printf("[%lu] [WEBACT] WiFi disconnected! Status: %d\n", millis(), wifiStatus);
+          LOG_DBG("WEBACT", "WiFi disconnected! Status: %d", wifiStatus);
           // Show error and exit gracefully
           state = WebServerActivityState::SHUTTING_DOWN;
           updateRequired = true;
@@ -318,7 +318,7 @@ void CrossPointWebServerActivity::loop() {
         // Log weak signal warnings
         const int rssi = WiFi.RSSI();
         if (rssi < -75) {
-          Serial.printf("[%lu] [WEBACT] Warning: Weak WiFi signal: %d dBm\n", millis(), rssi);
+          LOG_DBG("WEBACT", "Warning: Weak WiFi signal: %d dBm", rssi);
         }
       }
     }
@@ -329,8 +329,7 @@ void CrossPointWebServerActivity::loop() {
 
       // Log if there's a significant gap between handleClient calls (>100ms)
       if (lastHandleClientTime > 0 && timeSinceLastHandleClient > 100) {
-        Serial.printf("[%lu] [WEBACT] WARNING: %lu ms gap since last handleClient\n", millis(),
-                      timeSinceLastHandleClient);
+        LOG_DBG("WEBACT", "WARNING: %lu ms gap since last handleClient", timeSinceLastHandleClient);
       }
 
       // Reset watchdog BEFORE processing - HTTP header parsing can be slow
@@ -348,6 +347,9 @@ void CrossPointWebServerActivity::loop() {
         // Yield and check for exit button every 64 iterations
         if ((i & 0x3F) == 0x3F) {
           yield();
+          // Force trigger an update of which buttons are being pressed so be have accurate state
+          // for back button checking
+          mappedInput.update();
           // Check for exit button inside loop for responsiveness
           if (mappedInput.wasPressed(MappedInputManager::Button::Back)) {
             onGoBack();
@@ -398,7 +400,7 @@ void drawQRCode(const GfxRenderer& renderer, const int x, const int y, const std
   // The structure to manage the QR code
   QRCode qrcode;
   uint8_t qrcodeBytes[qrcode_getBufferSize(4)];
-  Serial.printf("[%lu] [WEBACT] QR Code (%lu): %s\n", millis(), data.length(), data.c_str());
+  LOG_DBG("WEBACT", "QR Code (%lu): %s", data.length(), data.c_str());
 
   qrcode_initText(&qrcode, qrcodeBytes, 4, ECC_LOW, data.c_str());
   const uint8_t px = 6;  // pixels per module

src/activities/network/NetworkModeSelectionActivity.cpp

@@ -73,18 +73,15 @@ void NetworkModeSelectionActivity::loop() {
   }
 
   // Handle navigation
-  const bool prevPressed = mappedInput.wasPressed(MappedInputManager::Button::Up) ||
-                           mappedInput.wasPressed(MappedInputManager::Button::Left);
-  const bool nextPressed = mappedInput.wasPressed(MappedInputManager::Button::Down) ||
-                           mappedInput.wasPressed(MappedInputManager::Button::Right);
+  buttonNavigator.onNext([this] {
+    selectedIndex = ButtonNavigator::nextIndex(selectedIndex, MENU_ITEM_COUNT);
+    updateRequired = true;
+  });
 
-  if (prevPressed) {
-    selectedIndex = (selectedIndex + MENU_ITEM_COUNT - 1) % MENU_ITEM_COUNT;
+  buttonNavigator.onPrevious([this] {
+    selectedIndex = ButtonNavigator::previousIndex(selectedIndex, MENU_ITEM_COUNT);
     updateRequired = true;
-  } else if (nextPressed) {
-    selectedIndex = (selectedIndex + 1) % MENU_ITEM_COUNT;
-    updateRequired = true;
-  }
+  });
 }
 
 void NetworkModeSelectionActivity::displayTaskLoop() {

src/activities/network/NetworkModeSelectionActivity.h

@@ -6,6 +6,7 @@
 #include <functional>
 
 #include "../Activity.h"
+#include "util/ButtonNavigator.h"
 
 // Enum for network mode selection
 enum class NetworkMode { JOIN_NETWORK, CONNECT_CALIBRE, CREATE_HOTSPOT };
@@ -22,6 +23,8 @@ enum class NetworkMode { JOIN_NETWORK, CONNECT_CALIBRE, CREATE_HOTSPOT };
 class NetworkModeSelectionActivity final : public Activity {
   TaskHandle_t displayTaskHandle = nullptr;
   SemaphoreHandle_t renderingMutex = nullptr;
+  ButtonNavigator buttonNavigator;
+
   int selectedIndex = 0;
   bool updateRequired = false;
   const std::function<void(NetworkMode)> onModeSelected;

src/activities/network/WifiSelectionActivity.cpp

@@ -1,6 +1,7 @@
 #include "WifiSelectionActivity.h"
 
 #include <GfxRenderer.h>
+#include <Logging.h>
 #include <WiFi.h>
 
 #include <map>
@@ -21,7 +22,8 @@ void WifiSelectionActivity::onEnter() {
 
   renderingMutex = xSemaphoreCreateMutex();
 
-  // Load saved WiFi credentials - SD card operations need lock as we use SPI for both
+  // Load saved WiFi credentials - SD card operations need lock as we use SPI
+  // for both
   xSemaphoreTake(renderingMutex, portMAX_DELAY);
   WIFI_STORE.loadFromFile();
   xSemaphoreGive(renderingMutex);
@@ -37,6 +39,7 @@ void WifiSelectionActivity::onEnter() {
   usedSavedPassword = false;
   savePromptSelection = 0;
   forgetPromptSelection = 0;
+  autoConnecting = false;
 
   // Cache MAC address for display
   uint8_t mac[6];
@@ -46,9 +49,7 @@ void WifiSelectionActivity::onEnter() {
            mac[5]);
   cachedMacAddress = std::string(macStr);
 
-  // Trigger first update to show scanning message
-  updateRequired = true;
-
+  // Task creation
   xTaskCreate(&WifiSelectionActivity::taskTrampoline, "WifiSelectionTask",
               4096,               // Stack size (larger for WiFi operations)
               this,               // Parameters
@@ -56,46 +57,68 @@ void WifiSelectionActivity::onEnter() {
               &displayTaskHandle  // Task handle
   );
 
-  // Start WiFi scan
+  // Attempt to auto-connect to the last network
+  if (allowAutoConnect) {
+    const std::string lastSsid = WIFI_STORE.getLastConnectedSsid();
+    if (!lastSsid.empty()) {
+      const auto* cred = WIFI_STORE.findCredential(lastSsid);
+      if (cred) {
+        LOG_DBG("WIFI", "Attempting to auto-connect to %s", lastSsid.c_str());
+        selectedSSID = cred->ssid;
+        enteredPassword = cred->password;
+        selectedRequiresPassword = !cred->password.empty();
+        usedSavedPassword = true;
+        autoConnecting = true;
+        attemptConnection();
+        updateRequired = true;
+        return;
+      }
+    }
+  }
+
+  // Fallback to scanning
   startWifiScan();
 }
 
 void WifiSelectionActivity::onExit() {
   Activity::onExit();
 
-  Serial.printf("[%lu] [WIFI] [MEM] Free heap at onExit start: %d bytes\n", millis(), ESP.getFreeHeap());
+  LOG_DBG("WIFI] [MEM", "Free heap at onExit start: %d bytes", ESP.getFreeHeap());
 
   // Stop any ongoing WiFi scan
-  Serial.printf("[%lu] [WIFI] Deleting WiFi scan...\n", millis());
+  LOG_DBG("WIFI", "Deleting WiFi scan...");
   WiFi.scanDelete();
-  Serial.printf("[%lu] [WIFI] [MEM] Free heap after scanDelete: %d bytes\n", millis(), ESP.getFreeHeap());
+  LOG_DBG("WIFI] [MEM", "Free heap after scanDelete: %d bytes", ESP.getFreeHeap());
 
-  // Note: We do NOT disconnect WiFi here - the parent activity (CrossPointWebServerActivity)
-  // manages WiFi connection state. We just clean up the scan and task.
+  // Note: We do NOT disconnect WiFi here - the parent activity
+  // (CrossPointWebServerActivity) manages WiFi connection state. We just clean
+  // up the scan and task.
 
   // Acquire mutex before deleting task to ensure task isn't using it
   // This prevents hangs/crashes if the task holds the mutex when deleted
-  Serial.printf("[%lu] [WIFI] Acquiring rendering mutex before task deletion...\n", millis());
+  LOG_DBG("WIFI", "Acquiring rendering mutex before task deletion...");
   xSemaphoreTake(renderingMutex, portMAX_DELAY);
 
-  // Delete the display task (we now hold the mutex, so task is blocked if it needs it)
-  Serial.printf("[%lu] [WIFI] Deleting display task...\n", millis());
+  // Delete the display task (we now hold the mutex, so task is blocked if it
+  // needs it)
+  LOG_DBG("WIFI", "Deleting display task...");
   if (displayTaskHandle) {
     vTaskDelete(displayTaskHandle);
     displayTaskHandle = nullptr;
-    Serial.printf("[%lu] [WIFI] Display task deleted\n", millis());
+    LOG_DBG("WIFI", "Display task deleted");
   }
 
   // Now safe to delete the mutex since we own it
-  Serial.printf("[%lu] [WIFI] Deleting mutex...\n", millis());
+  LOG_DBG("WIFI", "Deleting mutex...");
   vSemaphoreDelete(renderingMutex);
   renderingMutex = nullptr;
-  Serial.printf("[%lu] [WIFI] Mutex deleted\n", millis());
+  LOG_DBG("WIFI", "Mutex deleted");
 
-  Serial.printf("[%lu] [WIFI] [MEM] Free heap at onExit end: %d bytes\n", millis(), ESP.getFreeHeap());
+  LOG_DBG("WIFI] [MEM", "Free heap at onExit end: %d bytes", ESP.getFreeHeap());
 }
 
 void WifiSelectionActivity::startWifiScan() {
+  autoConnecting = false;
   state = WifiSelectionState::SCANNING;
   networks.clear();
   updateRequired = true;
@@ -181,6 +204,7 @@ void WifiSelectionActivity::selectNetwork(const int index) {
   selectedRequiresPassword = network.isEncrypted;
   usedSavedPassword = false;
   enteredPassword.clear();
+  autoConnecting = false;
 
   // Check if we have saved credentials for this network
   const auto* savedCred = WIFI_STORE.findCredential(selectedSSID);
@@ -188,8 +212,7 @@ void WifiSelectionActivity::selectNetwork(const int index) {
     // Use saved password - connect directly
     enteredPassword = savedCred->password;
     usedSavedPassword = true;
-    Serial.printf("[%lu] [WiFi] Using saved password for %s, length: %zu\n", millis(), selectedSSID.c_str(),
-                  enteredPassword.size());
+    LOG_DBG("WiFi", "Using saved password for %s, length: %zu", selectedSSID.c_str(), enteredPassword.size());
     attemptConnection();
     return;
   }
@@ -223,7 +246,7 @@ void WifiSelectionActivity::selectNetwork(const int index) {
 }
 
 void WifiSelectionActivity::attemptConnection() {
-  state = WifiSelectionState::CONNECTING;
+  state = autoConnecting ? WifiSelectionState::AUTO_CONNECTING : WifiSelectionState::CONNECTING;
   connectionStartTime = millis();
   connectedIP.clear();
   connectionError.clear();
@@ -239,7 +262,7 @@ void WifiSelectionActivity::attemptConnection() {
 }
 
 void WifiSelectionActivity::checkConnectionStatus() {
-  if (state != WifiSelectionState::CONNECTING) {
+  if (state != WifiSelectionState::CONNECTING && state != WifiSelectionState::AUTO_CONNECTING) {
     return;
   }
 
@@ -251,6 +274,13 @@ void WifiSelectionActivity::checkConnectionStatus() {
     char ipStr[16];
     snprintf(ipStr, sizeof(ipStr), "%d.%d.%d.%d", ip[0], ip[1], ip[2], ip[3]);
     connectedIP = ipStr;
+    autoConnecting = false;
+
+    // Save this as the last connected network - SD card operations need lock as
+    // we use SPI for both
+    xSemaphoreTake(renderingMutex, portMAX_DELAY);
+    WIFI_STORE.setLastConnectedSsid(selectedSSID);
+    xSemaphoreGive(renderingMutex);
 
     // If we entered a new password, ask if user wants to save it
     // Otherwise, immediately complete so parent can start web server
@@ -260,7 +290,9 @@ void WifiSelectionActivity::checkConnectionStatus() {
       updateRequired = true;
     } else {
       // Using saved password or open network - complete immediately
-      Serial.printf("[%lu] [WIFI] Connected with saved/open credentials, completing immediately\n", millis());
+      LOG_DBG("WIFI",
+              "Connected with saved/open credentials, "
+              "completing immediately");
       onComplete(true);
     }
     return;
@@ -299,7 +331,7 @@ void WifiSelectionActivity::loop() {
   }
 
   // Check connection progress
-  if (state == WifiSelectionState::CONNECTING) {
+  if (state == WifiSelectionState::CONNECTING || state == WifiSelectionState::AUTO_CONNECTING) {
     checkConnectionStatus();
     return;
   }
@@ -368,17 +400,16 @@ void WifiSelectionActivity::loop() {
         }
       }
       // Go back to network list (whether Cancel or Forget network was selected)
-      state = WifiSelectionState::NETWORK_LIST;
-      updateRequired = true;
+      startWifiScan();
     } else if (mappedInput.wasPressed(MappedInputManager::Button::Back)) {
       // Skip forgetting, go back to network list
-      state = WifiSelectionState::NETWORK_LIST;
-      updateRequired = true;
+      startWifiScan();
     }
     return;
   }
 
-  // Handle connected state (should not normally be reached - connection completes immediately)
+  // Handle connected state (should not normally be reached - connection
+  // completes immediately)
   if (state == WifiSelectionState::CONNECTED) {
     // Safety fallback - immediately complete
     onComplete(true);
@@ -389,12 +420,14 @@ void WifiSelectionActivity::loop() {
   if (state == WifiSelectionState::CONNECTION_FAILED) {
     if (mappedInput.wasPressed(MappedInputManager::Button::Back) ||
         mappedInput.wasPressed(MappedInputManager::Button::Confirm)) {
-      // If we used saved credentials, offer to forget the network
-      if (usedSavedPassword) {
+      // If we were auto-connecting or using a saved credential, offer to forget
+      // the network
+      if (autoConnecting || usedSavedPassword) {
+        autoConnecting = false;
         state = WifiSelectionState::FORGET_PROMPT;
         forgetPromptSelection = 0;  // Default to "Cancel"
       } else {
-        // Go back to network list on failure
+        // Go back to network list on failure for non-saved credentials
         state = WifiSelectionState::NETWORK_LIST;
       }
       updateRequired = true;
@@ -420,20 +453,33 @@ void WifiSelectionActivity::loop() {
       return;
     }
 
-    // Handle UP/DOWN navigation
-    if (mappedInput.wasPressed(MappedInputManager::Button::Up) ||
-        mappedInput.wasPressed(MappedInputManager::Button::Left)) {
-      if (selectedNetworkIndex > 0) {
-        selectedNetworkIndex--;
-        updateRequired = true;
-      }
-    } else if (mappedInput.wasPressed(MappedInputManager::Button::Down) ||
-               mappedInput.wasPressed(MappedInputManager::Button::Right)) {
-      if (!networks.empty() && selectedNetworkIndex < static_cast<int>(networks.size()) - 1) {
-        selectedNetworkIndex++;
+    if (mappedInput.wasPressed(MappedInputManager::Button::Right)) {
+      startWifiScan();
+      return;
+    }
+
+    const bool leftPressed = mappedInput.wasPressed(MappedInputManager::Button::Left);
+    if (leftPressed) {
+      const bool hasSavedPassword = !networks.empty() && networks[selectedNetworkIndex].hasSavedPassword;
+      if (hasSavedPassword) {
+        selectedSSID = networks[selectedNetworkIndex].ssid;
+        state = WifiSelectionState::FORGET_PROMPT;
+        forgetPromptSelection = 0;  // Default to "Cancel"
         updateRequired = true;
+        return;
       }
     }
+
+    // Handle navigation
+    buttonNavigator.onNext([this] {
+      selectedNetworkIndex = ButtonNavigator::nextIndex(selectedNetworkIndex, networks.size());
+      updateRequired = true;
+    });
+
+    buttonNavigator.onPrevious([this] {
+      selectedNetworkIndex = ButtonNavigator::previousIndex(selectedNetworkIndex, networks.size());
+      updateRequired = true;
+    });
   }
 }
 
@@ -483,6 +529,9 @@ void WifiSelectionActivity::render() const {
   renderer.clearScreen();
 
   switch (state) {
+    case WifiSelectionState::AUTO_CONNECTING:
+      renderConnecting();
+      break;
     case WifiSelectionState::SCANNING:
       renderConnecting();  // Reuse connecting screen with different message
       break;
@@ -586,7 +635,11 @@ void WifiSelectionActivity::renderNetworkList() const {
 
   // Draw help text
   renderer.drawText(SMALL_FONT_ID, 20, pageHeight - 75, "* = Encrypted | + = Saved");
-  const auto labels = mappedInput.mapLabels("« Back", "Connect", "", "");
+
+  const bool hasSavedPassword = !networks.empty() && networks[selectedNetworkIndex].hasSavedPassword;
+  const char* forgetLabel = hasSavedPassword ? "Forget" : "";
+
+  const auto labels = mappedInput.mapLabels("« Back", "Connect", forgetLabel, "Refresh");
   GUI.drawButtonHints(renderer, labels.btn1, labels.btn2, labels.btn3, labels.btn4);
 }
 
@@ -690,8 +743,7 @@ void WifiSelectionActivity::renderForgetPrompt() const {
   const auto height = renderer.getLineHeight(UI_10_FONT_ID);
   const auto top = (pageHeight - height * 3) / 2;
 
-  renderer.drawCenteredText(UI_12_FONT_ID, top - 40, "Connection Failed", true, EpdFontFamily::BOLD);
-
+  renderer.drawCenteredText(UI_12_FONT_ID, top - 40, "Forget Network", true, EpdFontFamily::BOLD);
   std::string ssidInfo = "Network: " + selectedSSID;
   if (ssidInfo.length() > 28) {
     ssidInfo.replace(25, ssidInfo.length() - 25, "...");

src/activities/network/WifiSelectionActivity.h

@@ -10,6 +10,7 @@
 #include <vector>
 
 #include "activities/ActivityWithSubactivity.h"
+#include "util/ButtonNavigator.h"
 
 // Structure to hold WiFi network information
 struct WifiNetworkInfo {
@@ -21,6 +22,7 @@ struct WifiNetworkInfo {
 
 // WiFi selection states
 enum class WifiSelectionState {
+  AUTO_CONNECTING,    // Trying to connect to the last known network
   SCANNING,           // Scanning for networks
   NETWORK_LIST,       // Displaying available networks
   PASSWORD_ENTRY,     // Entering password for selected network
@@ -45,6 +47,7 @@ enum class WifiSelectionState {
 class WifiSelectionActivity final : public ActivityWithSubactivity {
   TaskHandle_t displayTaskHandle = nullptr;
   SemaphoreHandle_t renderingMutex = nullptr;
+  ButtonNavigator buttonNavigator;
   bool updateRequired = false;
   WifiSelectionState state = WifiSelectionState::SCANNING;
   int selectedNetworkIndex = 0;
@@ -68,6 +71,12 @@ class WifiSelectionActivity final : public ActivityWithSubactivity {
   // Whether network was connected using a saved password (skip save prompt)
   bool usedSavedPassword = false;
 
+  // Whether to attempt auto-connect on entry
+  const bool allowAutoConnect;
+
+  // Whether we are attempting to auto-connect
+  bool autoConnecting = false;
+
   // Save/forget prompt selection (0 = Yes, 1 = No)
   int savePromptSelection = 0;
   int forgetPromptSelection = 0;
@@ -96,8 +105,10 @@ class WifiSelectionActivity final : public ActivityWithSubactivity {
 
  public:
   explicit WifiSelectionActivity(GfxRenderer& renderer, MappedInputManager& mappedInput,
-                                 const std::function<void(bool connected)>& onComplete)
-      : ActivityWithSubactivity("WifiSelection", renderer, mappedInput), onComplete(onComplete) {}
+                                 const std::function<void(bool connected)>& onComplete, bool autoConnect = true)
+      : ActivityWithSubactivity("WifiSelection", renderer, mappedInput),
+        onComplete(onComplete),
+        allowAutoConnect(autoConnect) {}
   void onEnter() override;
   void onExit() override;
   void loop() override;

src/activities/reader/DictionaryDefinitionActivity.cpp

@@ -0,0 +1,545 @@
+#include "DictionaryDefinitionActivity.h"
+
+#include <GfxRenderer.h>
+
+#include <algorithm>
+#include <cctype>
+#include <cstdlib>
+
+#include "CrossPointSettings.h"
+#include "MappedInputManager.h"
+#include "components/UITheme.h"
+#include "fontIds.h"
+
+void DictionaryDefinitionActivity::taskTrampoline(void* param) {
+  auto* self = static_cast<DictionaryDefinitionActivity*>(param);
+  self->displayTaskLoop();
+}
+
+void DictionaryDefinitionActivity::displayTaskLoop() {
+  while (true) {
+    if (updateRequired) {
+      updateRequired = false;
+      xSemaphoreTake(renderingMutex, portMAX_DELAY);
+      renderScreen();
+      xSemaphoreGive(renderingMutex);
+    }
+    vTaskDelay(10 / portTICK_PERIOD_MS);
+  }
+}
+
+void DictionaryDefinitionActivity::onEnter() {
+  Activity::onEnter();
+  renderingMutex = xSemaphoreCreateMutex();
+  wrapText();
+  updateRequired = true;
+  xTaskCreate(&DictionaryDefinitionActivity::taskTrampoline, "DictDefTask", 4096, this, 1, &displayTaskHandle);
+}
+
+void DictionaryDefinitionActivity::onExit() {
+  Activity::onExit();
+  xSemaphoreTake(renderingMutex, portMAX_DELAY);
+  if (displayTaskHandle) {
+    vTaskDelete(displayTaskHandle);
+    displayTaskHandle = nullptr;
+  }
+  vSemaphoreDelete(renderingMutex);
+  renderingMutex = nullptr;
+}
+
+// ---------------------------------------------------------------------------
+// Check if a Unicode codepoint is likely renderable by the e-ink bitmap font.
+// Keeps Latin text, combining marks, common punctuation, currency, and letterlike symbols.
+// Skips IPA extensions, Greek, Cyrillic, Arabic, CJK, and other non-Latin scripts.
+// ---------------------------------------------------------------------------
+bool DictionaryDefinitionActivity::isRenderableCodepoint(uint32_t cp) {
+  if (cp <= 0x024F) return true;                       // Basic Latin + Latin Extended-A/B
+  if (cp >= 0x0300 && cp <= 0x036F) return true;       // Combining Diacritical Marks
+  if (cp >= 0x2000 && cp <= 0x206F) return true;       // General Punctuation
+  if (cp >= 0x20A0 && cp <= 0x20CF) return true;       // Currency Symbols
+  if (cp >= 0x2100 && cp <= 0x214F) return true;       // Letterlike Symbols
+  if (cp >= 0x2190 && cp <= 0x21FF) return true;       // Arrows
+  return false;
+}
+
+// ---------------------------------------------------------------------------
+// HTML entity decoder
+// ---------------------------------------------------------------------------
+std::string DictionaryDefinitionActivity::decodeEntity(const std::string& entity) {
+  // Named entities
+  if (entity == "amp") return "&";
+  if (entity == "lt") return "<";
+  if (entity == "gt") return ">";
+  if (entity == "quot") return "\"";
+  if (entity == "apos") return "'";
+  if (entity == "nbsp" || entity == "thinsp" || entity == "ensp" || entity == "emsp") return " ";
+  if (entity == "ndash") return "\xE2\x80\x93";  // U+2013
+  if (entity == "mdash") return "\xE2\x80\x94";   // U+2014
+  if (entity == "lsquo") return "\xE2\x80\x98";
+  if (entity == "rsquo") return "\xE2\x80\x99";
+  if (entity == "ldquo") return "\xE2\x80\x9C";
+  if (entity == "rdquo") return "\xE2\x80\x9D";
+  if (entity == "hellip") return "\xE2\x80\xA6";
+  if (entity == "lrm" || entity == "rlm" || entity == "zwj" || entity == "zwnj") return "";
+
+  // Numeric entities: &#123; or &#x1F;
+  if (!entity.empty() && entity[0] == '#') {
+    unsigned long cp = 0;
+    if (entity.size() > 1 && (entity[1] == 'x' || entity[1] == 'X')) {
+      cp = std::strtoul(entity.c_str() + 2, nullptr, 16);
+    } else {
+      cp = std::strtoul(entity.c_str() + 1, nullptr, 10);
+    }
+    if (cp > 0 && cp < 0x80) {
+      return std::string(1, static_cast<char>(cp));
+    }
+    if (cp >= 0x80 && cp < 0x800) {
+      char buf[3] = {static_cast<char>(0xC0 | (cp >> 6)), static_cast<char>(0x80 | (cp & 0x3F)), '\0'};
+      return std::string(buf, 2);
+    }
+    if (cp >= 0x800 && cp < 0x10000) {
+      char buf[4] = {static_cast<char>(0xE0 | (cp >> 12)), static_cast<char>(0x80 | ((cp >> 6) & 0x3F)),
+                     static_cast<char>(0x80 | (cp & 0x3F)), '\0'};
+      return std::string(buf, 3);
+    }
+    if (cp >= 0x10000 && cp < 0x110000) {
+      char buf[5] = {static_cast<char>(0xF0 | (cp >> 18)), static_cast<char>(0x80 | ((cp >> 12) & 0x3F)),
+                     static_cast<char>(0x80 | ((cp >> 6) & 0x3F)), static_cast<char>(0x80 | (cp & 0x3F)), '\0'};
+      return std::string(buf, 4);
+    }
+  }
+
+  return "";  // unknown entity — drop it
+}
+
+// ---------------------------------------------------------------------------
+// HTML → TextAtom list
+// ---------------------------------------------------------------------------
+std::vector<DictionaryDefinitionActivity::TextAtom> DictionaryDefinitionActivity::parseHtml(const std::string& html) {
+  std::vector<TextAtom> atoms;
+
+  bool isBold = false;
+  bool isItalic = false;
+  bool inSvg = false;
+  int svgDepth = 0;
+  std::vector<ListState> listStack;
+  std::string currentWord;
+
+  auto currentStyle = [&]() -> EpdFontFamily::Style {
+    if (isBold && isItalic) return EpdFontFamily::BOLD_ITALIC;
+    if (isBold) return EpdFontFamily::BOLD;
+    if (isItalic) return EpdFontFamily::ITALIC;
+    return EpdFontFamily::REGULAR;
+  };
+
+  auto flushWord = [&]() {
+    if (!currentWord.empty() && !inSvg) {
+      atoms.push_back({currentWord, currentStyle(), false, 0});
+      currentWord.clear();
+    }
+  };
+
+  auto indentPx = [&]() -> int {
+    // 15 pixels per nesting level (the first level has no extra indent)
+    int depth = static_cast<int>(listStack.size());
+    return (depth > 1) ? (depth - 1) * 15 : 0;
+  };
+
+  // Skip any leading non-HTML text (e.g. pronunciation guides like "/ˈsɪm.pəl/, /ˈsɪmpəl/")
+  // that appears before the first tag in sametypesequence=h entries.
+  size_t i = 0;
+  {
+    size_t firstTag = html.find('<');
+    if (firstTag != std::string::npos) i = firstTag;
+  }
+
+  while (i < html.size()) {
+    // ------- HTML tag -------
+    if (html[i] == '<') {
+      flushWord();
+
+      size_t tagEnd = html.find('>', i);
+      if (tagEnd == std::string::npos) break;
+
+      std::string tagContent = html.substr(i + 1, tagEnd - i - 1);
+
+      // Extract tag name: first token, lowercased, trailing '/' stripped.
+      size_t space = tagContent.find(' ');
+      std::string tagName = (space != std::string::npos) ? tagContent.substr(0, space) : tagContent;
+      for (auto& c : tagName) c = static_cast<char>(std::tolower(static_cast<unsigned char>(c)));
+      if (!tagName.empty() && tagName.back() == '/') tagName.pop_back();
+
+      // --- SVG handling (skip all content inside <svg>…</svg>) ---
+      if (tagName == "svg") {
+        inSvg = true;
+        svgDepth = 1;
+      } else if (inSvg) {
+        if (tagName == "svg") {
+          svgDepth++;
+        } else if (tagName == "/svg") {
+          svgDepth--;
+          if (svgDepth <= 0) inSvg = false;
+        }
+      }
+
+      if (!inSvg) {
+        // --- Inline style tags ---
+        if (tagName == "b" || tagName == "strong") {
+          isBold = true;
+        } else if (tagName == "/b" || tagName == "/strong") {
+          isBold = false;
+        } else if (tagName == "i" || tagName == "em") {
+          isItalic = true;
+        } else if (tagName == "/i" || tagName == "/em") {
+          isItalic = false;
+
+          // --- Block-level tags → newlines ---
+        } else if (tagName == "p" || tagName == "h1" || tagName == "h2" || tagName == "h3" || tagName == "h4") {
+          atoms.push_back({"", EpdFontFamily::REGULAR, true, indentPx()});
+          // Headings get bold style applied to following text
+          if (tagName != "p") isBold = true;
+        } else if (tagName == "/p" || tagName == "/h1" || tagName == "/h2" || tagName == "/h3" || tagName == "/h4") {
+          atoms.push_back({"", EpdFontFamily::REGULAR, true, indentPx()});
+          isBold = false;
+        } else if (tagName == "br") {
+          atoms.push_back({"", EpdFontFamily::REGULAR, true, indentPx()});
+
+          // --- Separator between definition entries ---
+        } else if (tagName == "/html") {
+          atoms.push_back({"", EpdFontFamily::REGULAR, true, 0});
+          atoms.push_back({"", EpdFontFamily::REGULAR, true, 0});  // extra blank line
+          isBold = false;
+          isItalic = false;
+          // Skip any raw text between </html> and the next tag — this is where
+          // pronunciation guides (e.g. /ˈsɪmpəl/, /ksɛpt/) live in this dictionary.
+          size_t nextTag = html.find('<', tagEnd + 1);
+          i = (nextTag != std::string::npos) ? nextTag : html.size();
+          continue;
+
+          // --- Lists ---
+        } else if (tagName == "ol") {
+          bool alpha = tagContent.find("lower-alpha") != std::string::npos;
+          listStack.push_back({0, alpha});
+        } else if (tagName == "ul") {
+          listStack.push_back({0, false});
+        } else if (tagName == "/ol" || tagName == "/ul") {
+          if (!listStack.empty()) listStack.pop_back();
+        } else if (tagName == "li") {
+          atoms.push_back({"", EpdFontFamily::REGULAR, true, indentPx()});
+          if (!listStack.empty()) {
+            auto& ls = listStack.back();
+            ls.counter++;
+            std::string marker;
+            if (ls.isAlpha && ls.counter >= 1 && ls.counter <= 26) {
+              marker = std::string(1, static_cast<char>('a' + ls.counter - 1)) + ". ";
+            } else if (ls.isAlpha) {
+              marker = std::to_string(ls.counter) + ". ";
+            } else {
+              marker = std::to_string(ls.counter) + ". ";
+            }
+            atoms.push_back({marker, EpdFontFamily::REGULAR, false, 0});
+          } else {
+            // Unordered list or bare <li>
+            atoms.push_back({"\xE2\x80\xA2 ", EpdFontFamily::REGULAR, false, 0});
+          }
+        }
+        // All other tags (span, div, code, sup, sub, table, etc.) are silently ignored;
+        // their text content will still be emitted.
+      }
+
+      i = tagEnd + 1;
+      continue;
+    }
+
+    // Skip content inside SVG
+    if (inSvg) {
+      i++;
+      continue;
+    }
+
+    // ------- HTML entity -------
+    if (html[i] == '&') {
+      size_t semicolon = html.find(';', i);
+      if (semicolon != std::string::npos && semicolon - i < 16) {
+        std::string entity = html.substr(i + 1, semicolon - i - 1);
+        std::string decoded = decodeEntity(entity);
+        if (!decoded.empty()) {
+          // Treat decoded chars like normal text (could be space etc.)
+          for (char dc : decoded) {
+            if (dc == ' ') {
+              flushWord();
+            } else {
+              currentWord += dc;
+            }
+          }
+        }
+        i = semicolon + 1;
+        continue;
+      }
+      // Not a valid entity — emit '&' literally
+      currentWord += '&';
+      i++;
+      continue;
+    }
+
+    // ------- IPA pronunciation (skip /…/ and […] containing non-ASCII) -------
+    if (html[i] == '/' || html[i] == '[') {
+      char closeDelim = (html[i] == '/') ? '/' : ']';
+      size_t end = html.find(closeDelim, i + 1);
+      if (end != std::string::npos && end - i < 80) {
+        bool hasNonAscii = false;
+        for (size_t j = i + 1; j < end; j++) {
+          if (static_cast<unsigned char>(html[j]) > 127) {
+            hasNonAscii = true;
+            break;
+          }
+        }
+        if (hasNonAscii) {
+          flushWord();
+          i = end + 1;  // skip entire IPA section including delimiters
+          continue;
+        }
+      }
+      // Not IPA — fall through to treat as regular character
+    }
+
+    // ------- Whitespace -------
+    if (html[i] == ' ' || html[i] == '\t' || html[i] == '\n' || html[i] == '\r') {
+      flushWord();
+      i++;
+      continue;
+    }
+
+    // ------- Regular character (with non-renderable character filter) -------
+    {
+      unsigned char byte = static_cast<unsigned char>(html[i]);
+      if (byte < 0x80) {
+        // ASCII — always renderable
+        currentWord += html[i];
+        i++;
+      } else {
+        // Multi-byte UTF-8: decode codepoint and check if renderable
+        int seqLen = 1;
+        uint32_t cp = 0;
+        if ((byte & 0xE0) == 0xC0) {
+          seqLen = 2;
+          cp = byte & 0x1F;
+        } else if ((byte & 0xF0) == 0xE0) {
+          seqLen = 3;
+          cp = byte & 0x0F;
+        } else if ((byte & 0xF8) == 0xF0) {
+          seqLen = 4;
+          cp = byte & 0x07;
+        } else {
+          i++;
+          continue;
+        }  // invalid start byte
+
+        if (i + static_cast<size_t>(seqLen) > html.size()) {
+          i++;
+          continue;
+        }
+
+        bool valid = true;
+        for (int j = 1; j < seqLen; j++) {
+          unsigned char cb = static_cast<unsigned char>(html[i + j]);
+          if ((cb & 0xC0) != 0x80) {
+            valid = false;
+            break;
+          }
+          cp = (cp << 6) | (cb & 0x3F);
+        }
+
+        if (valid && isRenderableCodepoint(cp)) {
+          for (int j = 0; j < seqLen; j++) {
+            currentWord += html[i + j];
+          }
+        }
+        // else: silently skip non-renderable character
+
+        i += valid ? seqLen : 1;
+      }
+    }
+  }
+
+  flushWord();
+  return atoms;
+}
+
+// ---------------------------------------------------------------------------
+// Word-wrap the parsed HTML atoms into positioned line segments
+// ---------------------------------------------------------------------------
+void DictionaryDefinitionActivity::wrapText() {
+  wrappedLines.clear();
+
+  const bool landscape = orientation == CrossPointSettings::ORIENTATION::LANDSCAPE_CW ||
+                         orientation == CrossPointSettings::ORIENTATION::LANDSCAPE_CCW;
+  const int screenWidth = renderer.getScreenWidth();
+  const int lineHeight = renderer.getLineHeight(readerFontId);
+  const int sidePadding = landscape ? 50 : 20;
+  constexpr int topArea = 50;
+  constexpr int bottomArea = 50;
+  const int maxWidth = screenWidth - 2 * sidePadding;
+  const int spaceWidth = renderer.getSpaceWidth(readerFontId);
+
+  linesPerPage = (renderer.getScreenHeight() - topArea - bottomArea) / lineHeight;
+  if (linesPerPage < 1) linesPerPage = 1;
+
+  auto atoms = parseHtml(definition);
+
+  std::vector<Segment> currentLine;
+  int currentX = 0;
+  int baseIndent = 0;  // indent for continuation lines within the same block
+
+  for (const auto& atom : atoms) {
+    // ---- Newline directive ----
+    if (atom.isNewline) {
+      // Collapse multiple consecutive blank lines
+      if (currentLine.empty() && !wrappedLines.empty() && wrappedLines.back().empty()) {
+        // Already have a blank line; update indent but don't push another
+        baseIndent = atom.indent;
+        currentX = baseIndent;
+        continue;
+      }
+      wrappedLines.push_back(std::move(currentLine));
+      currentLine.clear();
+      baseIndent = atom.indent;
+      currentX = baseIndent;
+      continue;
+    }
+
+    // ---- Text word ----
+    int wordWidth = renderer.getTextWidth(readerFontId, atom.text.c_str(), atom.style);
+    int gap = (currentX > baseIndent) ? spaceWidth : 0;
+
+    // Wrap if this word won't fit
+    if (currentX + gap + wordWidth > maxWidth && currentX > baseIndent) {
+      wrappedLines.push_back(std::move(currentLine));
+      currentLine.clear();
+      currentX = baseIndent;
+      gap = 0;
+    }
+
+    int16_t x = static_cast<int16_t>(currentX + gap);
+    currentLine.push_back({atom.text, x, atom.style});
+    currentX = x + wordWidth;
+  }
+
+  // Flush last line
+  if (!currentLine.empty()) {
+    wrappedLines.push_back(std::move(currentLine));
+  }
+
+  totalPages = (static_cast<int>(wrappedLines.size()) + linesPerPage - 1) / linesPerPage;
+  if (totalPages < 1) totalPages = 1;
+}
+
+void DictionaryDefinitionActivity::loop() {
+  const bool prevPage = mappedInput.wasReleased(MappedInputManager::Button::PageBack) ||
+                        mappedInput.wasReleased(MappedInputManager::Button::Left);
+  const bool nextPage = mappedInput.wasReleased(MappedInputManager::Button::PageForward) ||
+                        mappedInput.wasReleased(MappedInputManager::Button::Right);
+
+  if (prevPage && currentPage > 0) {
+    currentPage--;
+    updateRequired = true;
+  }
+
+  if (nextPage && currentPage < totalPages - 1) {
+    currentPage++;
+    updateRequired = true;
+  }
+
+  if (mappedInput.wasReleased(MappedInputManager::Button::Confirm)) {
+    if (onDone) {
+      onDone();
+    } else {
+      onBack();
+    }
+    return;
+  }
+
+  if (mappedInput.wasReleased(MappedInputManager::Button::Back)) {
+    onBack();
+    return;
+  }
+}
+
+void DictionaryDefinitionActivity::renderScreen() {
+  renderer.clearScreen();
+
+  const bool landscape = orientation == CrossPointSettings::ORIENTATION::LANDSCAPE_CW ||
+                         orientation == CrossPointSettings::ORIENTATION::LANDSCAPE_CCW;
+  const int sidePadding = landscape ? 50 : 20;
+  constexpr int titleY = 10;
+  const int lineHeight = renderer.getLineHeight(readerFontId);
+  constexpr int bodyStartY = 50;
+
+  // Title: the word in bold (UI font)
+  renderer.drawText(UI_12_FONT_ID, sidePadding, titleY, headword.c_str(), true, EpdFontFamily::BOLD);
+
+  // Separator line
+  renderer.drawLine(sidePadding, 40, renderer.getScreenWidth() - sidePadding, 40);
+
+  // Body: styled definition lines
+  int startLine = currentPage * linesPerPage;
+  for (int i = 0; i < linesPerPage && (startLine + i) < static_cast<int>(wrappedLines.size()); i++) {
+    int y = bodyStartY + i * lineHeight;
+    const auto& line = wrappedLines[startLine + i];
+    for (const auto& seg : line) {
+      renderer.drawText(readerFontId, sidePadding + seg.x, y, seg.text.c_str(), true, seg.style);
+    }
+  }
+
+  // Pagination indicator (bottom right)
+  if (totalPages > 1) {
+    std::string pageInfo = std::to_string(currentPage + 1) + "/" + std::to_string(totalPages);
+    int textWidth = renderer.getTextWidth(SMALL_FONT_ID, pageInfo.c_str());
+    renderer.drawText(SMALL_FONT_ID, renderer.getScreenWidth() - sidePadding - textWidth,
+                      renderer.getScreenHeight() - 50, pageInfo.c_str());
+  }
+
+  // Button hints (bottom face buttons)
+  const auto labels = mappedInput.mapLabels("\xC2\xAB Back", onDone ? "Done" : "", "\xC2\xAB Page", "Page \xC2\xBB");
+  GUI.drawButtonHints(renderer, labels.btn1, labels.btn2, labels.btn3, labels.btn4);
+
+  // Side button hints (drawn in portrait coordinates for correct placement)
+  {
+    const auto origOrientation = renderer.getOrientation();
+    renderer.setOrientation(GfxRenderer::Orientation::Portrait);
+    const int portW = renderer.getScreenWidth();
+
+    constexpr int sideButtonWidth = 30;
+    constexpr int sideButtonHeight = 78;
+    constexpr int sideButtonGap = 5;
+    constexpr int sideTopY = 345;
+    constexpr int cornerRadius = 6;
+    const int sideX = portW - sideButtonWidth;
+    const int sideButtonY[2] = {sideTopY, sideTopY + sideButtonHeight + sideButtonGap};
+    const char* sideLabels[2] = {"\xC2\xAB Page", "Page \xC2\xBB"};
+    const bool useCCW = (orientation == CrossPointSettings::ORIENTATION::LANDSCAPE_CCW);
+
+    for (int i = 0; i < 2; i++) {
+      renderer.fillRect(sideX, sideButtonY[i], sideButtonWidth, sideButtonHeight, false);
+      renderer.drawRoundedRect(sideX, sideButtonY[i], sideButtonWidth, sideButtonHeight, 1, cornerRadius, true, false,
+                               true, false, true);
+
+      const std::string truncated = renderer.truncatedText(SMALL_FONT_ID, sideLabels[i], sideButtonHeight);
+      const int tw = renderer.getTextWidth(SMALL_FONT_ID, truncated.c_str());
+
+      if (useCCW) {
+        renderer.drawTextRotated90CCW(SMALL_FONT_ID, sideX,
+                                      sideButtonY[i] + (sideButtonHeight - tw) / 2, truncated.c_str());
+      } else {
+        renderer.drawTextRotated90CW(SMALL_FONT_ID, sideX,
+                                     sideButtonY[i] + (sideButtonHeight + tw) / 2, truncated.c_str());
+      }
+    }
+
+    renderer.setOrientation(origOrientation);
+  }
+
+  // Use half refresh when entering the screen for cleaner transition; fast refresh for page turns.
+  renderer.displayBuffer(firstRender ? HalDisplay::HALF_REFRESH : HalDisplay::FAST_REFRESH);
+  firstRender = false;
+}