Cut release 0.10.0

## Summary

* The JSON release data from Github contains the entire release
description which can be very large
  * The 0.9.0 release was especially bad
* Use a JSON filter to avoid deserializing anything but the necessary
fields

## Additional Context

*
https://arduinojson.org/v7/how-to/deserialize-a-very-large-document/#filtering
* Fixes https://github.com/daveallie/crosspoint-reader/issues/124

.github/workflows/ci.yml

@@ -12,12 +12,6 @@ jobs:
       - uses: actions/checkout@v6
         with:
           submodules: recursive
-      - uses: actions/cache@v5
-        with:
-          path: |
-            ~/.cache/pip
-            ~/.platformio/.cache
-          key: ${{ runner.os }}-pio
       - uses: actions/setup-python@v6
         with:
           python-version: '3.14'

lib/EpdFont/EpdFont.cpp

@@ -59,14 +59,28 @@ bool EpdFont::hasPrintableChars(const char* string) const {
 
 const EpdGlyph* EpdFont::getGlyph(const uint32_t cp) const {
   const EpdUnicodeInterval* intervals = data->intervals;
-  for (int i = 0; i < data->intervalCount; i++) {
+  const int count = data->intervalCount;
-    const EpdUnicodeInterval* interval = &intervals[i];
+
-    if (cp >= interval->first && cp <= interval->last) {
+  if (count == 0) return nullptr;
+
+  // Binary search for O(log n) lookup instead of O(n)
+  // Critical for Korean fonts with many unicode intervals
+  int left = 0;
+  int right = count - 1;
+
+  while (left <= right) {
+    const int mid = left + (right - left) / 2;
+    const EpdUnicodeInterval* interval = &intervals[mid];
+
+    if (cp < interval->first) {
+      right = mid - 1;
+    } else if (cp > interval->last) {
+      left = mid + 1;
+    } else {
+      // Found: cp >= interval->first && cp <= interval->last
       return &data->glyph[interval->offset + (cp - interval->first)];
     }
-    if (cp < interval->first) {
-      return nullptr;
-    }
   }
+
   return nullptr;
 }

lib/Epub/Epub.cpp

@@ -1,13 +1,11 @@
 #include "Epub.h"
 
+#include <FsHelpers.h>
 #include <HardwareSerial.h>
 #include <JpegToBmpConverter.h>
 #include <SD.h>
 #include <ZipFile.h>
 
-#include <map>
-
-#include "Epub/FsHelpers.h"
 #include "Epub/parsers/ContainerParser.h"
 #include "Epub/parsers/ContentOpfParser.h"
 #include "Epub/parsers/TocNcxParser.h"
@@ -44,7 +42,15 @@ bool Epub::findContentOpfFile(std::string* contentOpfFile) const {
   return true;
 }
 
-bool Epub::parseContentOpf(const std::string& contentOpfFilePath) {
+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());
+    return false;
+  }
+
+  contentBasePath = contentOpfFilePath.substr(0, contentOpfFilePath.find_last_of('/') + 1);
+
   Serial.printf("[%lu] [EBP] Parsing content.opf: %s\n", millis(), contentOpfFilePath.c_str());
 
   size_t contentOpfSize;
@@ -53,7 +59,9 @@ bool Epub::parseContentOpf(const std::string& contentOpfFilePath) {
     return false;
   }
 
-  ContentOpfParser opfParser(getBasePath(), contentOpfSize);
+  ContentOpfParser opfParser(getCachePath(), getBasePath(), contentOpfSize, bookMetadataCache.get());
+  Serial.printf("[%lu] [MEM] Free: %d bytes, Total: %d bytes, Min Free: %d bytes\n", millis(), ESP.getFreeHeap(),
+                ESP.getHeapSize(), ESP.getMinFreeHeap());
 
   if (!opfParser.setup()) {
     Serial.printf("[%lu] [EBP] Could not setup content.opf parser\n", millis());
@@ -66,26 +74,20 @@ bool Epub::parseContentOpf(const std::string& contentOpfFilePath) {
   }
 
   // Grab data from opfParser into epub
-  title = opfParser.title;
+  bookMetadata.title = opfParser.title;
-  if (!opfParser.coverItemId.empty() && opfParser.items.count(opfParser.coverItemId) > 0) {
+  // TODO: Parse author
-    coverImageItem = opfParser.items.at(opfParser.coverItemId);
+  bookMetadata.author = "";
-  }
+  bookMetadata.coverItemHref = opfParser.coverItemHref;
 
   if (!opfParser.tocNcxPath.empty()) {
     tocNcxItem = opfParser.tocNcxPath;
   }
 
-  for (auto& spineRef : opfParser.spineRefs) {
-    if (opfParser.items.count(spineRef)) {
-      spine.emplace_back(spineRef, opfParser.items.at(spineRef));
-    }
-  }
-
   Serial.printf("[%lu] [EBP] Successfully parsed content.opf\n", millis());
   return true;
 }
 
-bool Epub::parseTocNcxFile() {
+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());
@@ -95,13 +97,18 @@ bool Epub::parseTocNcxFile() {
   Serial.printf("[%lu] [EBP] Parsing toc ncx file: %s\n", millis(), tocNcxItem.c_str());
 
   const auto tmpNcxPath = getCachePath() + "/toc.ncx";
-  File tempNcxFile = SD.open(tmpNcxPath.c_str(), FILE_WRITE);
+  File tempNcxFile;
+  if (!FsHelpers::openFileForWrite("EBP", tmpNcxPath, tempNcxFile)) {
+    return false;
+  }
   readItemContentsToStream(tocNcxItem, tempNcxFile, 1024);
   tempNcxFile.close();
-  tempNcxFile = SD.open(tmpNcxPath.c_str(), FILE_READ);
+  if (!FsHelpers::openFileForRead("EBP", tmpNcxPath, tempNcxFile)) {
+    return false;
+  }
   const auto ncxSize = tempNcxFile.size();
 
-  TocNcxParser ncxParser(contentBasePath, ncxSize);
+  TocNcxParser ncxParser(contentBasePath, ncxSize, bookMetadataCache.get());
 
   if (!ncxParser.setup()) {
     Serial.printf("[%lu] [EBP] Could not setup toc ncx parser\n", millis());
@@ -130,9 +137,7 @@ bool Epub::parseTocNcxFile() {
   tempNcxFile.close();
   SD.remove(tmpNcxPath.c_str());
 
-  this->toc = std::move(ncxParser.toc);
+  Serial.printf("[%lu] [EBP] Parsed TOC items\n", millis());
-
-  Serial.printf("[%lu] [EBP] Parsed %d TOC items\n", millis(), this->toc.size());
   return true;
 }
 
@@ -140,48 +145,79 @@ bool Epub::parseTocNcxFile() {
 bool Epub::load() {
   Serial.printf("[%lu] [EBP] Loading ePub: %s\n", millis(), filepath.c_str());
 
-  std::string contentOpfFilePath;
+  // Initialize spine/TOC cache
-  if (!findContentOpfFile(&contentOpfFilePath)) {
+  bookMetadataCache.reset(new BookMetadataCache(cachePath));
-    Serial.printf("[%lu] [EBP] Could not find content.opf in zip\n", millis());
+
+  // Try to load existing cache first
+  if (bookMetadataCache->load()) {
+    Serial.printf("[%lu] [EBP] Loaded ePub: %s\n", millis(), filepath.c_str());
+    return true;
+  }
+
+  // Cache doesn't exist or is invalid, build it
+  Serial.printf("[%lu] [EBP] Cache not found, building spine/TOC cache\n", millis());
+  setupCacheDir();
+
+  // Begin building cache - stream entries to disk immediately
+  if (!bookMetadataCache->beginWrite()) {
+    Serial.printf("[%lu] [EBP] Could not begin writing cache\n", millis());
     return false;
   }
 
-  Serial.printf("[%lu] [EBP] Found content.opf at: %s\n", millis(), contentOpfFilePath.c_str());
+  // OPF Pass
-
+  BookMetadataCache::BookMetadata bookMetadata;
-  contentBasePath = contentOpfFilePath.substr(0, contentOpfFilePath.find_last_of('/') + 1);
+  if (!bookMetadataCache->beginContentOpfPass()) {
-
+    Serial.printf("[%lu] [EBP] Could not begin writing content.opf pass\n", millis());
-  if (!parseContentOpf(contentOpfFilePath)) {
+    return false;
+  }
+  if (!parseContentOpf(bookMetadata)) {
     Serial.printf("[%lu] [EBP] Could not parse content.opf\n", millis());
     return false;
   }
+  if (!bookMetadataCache->endContentOpfPass()) {
+    Serial.printf("[%lu] [EBP] Could not end writing content.opf pass\n", millis());
+    return false;
+  }
 
+  // TOC Pass
+  if (!bookMetadataCache->beginTocPass()) {
+    Serial.printf("[%lu] [EBP] Could not begin writing toc pass\n", millis());
+    return false;
+  }
   if (!parseTocNcxFile()) {
     Serial.printf("[%lu] [EBP] Could not parse toc\n", millis());
     return false;
   }
-
+  if (!bookMetadataCache->endTocPass()) {
-  initializeSpineItemSizes();
+    Serial.printf("[%lu] [EBP] Could not end writing toc pass\n", millis());
-  Serial.printf("[%lu] [EBP] Loaded ePub: %s\n", millis(), filepath.c_str());
+    return false;
-
-  return true;
-}
-
-void Epub::initializeSpineItemSizes() {
-  Serial.printf("[%lu] [EBP] Calculating book size\n", millis());
-
-  const size_t spineItemsCount = getSpineItemsCount();
-  size_t cumSpineItemSize = 0;
-  const ZipFile zip("/sd" + filepath);
-
-  for (size_t i = 0; i < spineItemsCount; i++) {
-    std::string spineItem = getSpineItem(i);
-    size_t s = 0;
-    getItemSize(zip, spineItem, &s);
-    cumSpineItemSize += s;
-    cumulativeSpineItemSize.emplace_back(cumSpineItemSize);
   }
 
-  Serial.printf("[%lu] [EBP] Book size: %lu\n", millis(), cumSpineItemSize);
+  // Close the cache files
+  if (!bookMetadataCache->endWrite()) {
+    Serial.printf("[%lu] [EBP] Could not end writing cache\n", millis());
+    return false;
+  }
+
+  // Build final book.bin
+  if (!bookMetadataCache->buildBookBin(filepath, bookMetadata)) {
+    Serial.printf("[%lu] [EBP] Could not update mappings and sizes\n", millis());
+    return false;
+  }
+
+  if (!bookMetadataCache->cleanupTmpFiles()) {
+    Serial.printf("[%lu] [EBP] Could not cleanup tmp files - ignoring\n", millis());
+  }
+
+  // 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());
+    return false;
+  }
+
+  Serial.printf("[%lu] [EBP] Loaded ePub: %s\n", millis(), filepath.c_str());
+  return true;
 }
 
 bool Epub::clearCache() const {
@@ -217,7 +253,14 @@ const std::string& Epub::getCachePath() const { return cachePath; }
 
 const std::string& Epub::getPath() const { return filepath; }
 
-const std::string& Epub::getTitle() const { return title; }
+const std::string& Epub::getTitle() const {
+  static std::string blank;
+  if (!bookMetadataCache || !bookMetadataCache->isLoaded()) {
+    return blank;
+  }
+
+  return bookMetadataCache->coreMetadata.title;
+}
 
 std::string Epub::getCoverBmpPath() const { return cachePath + "/cover.bmp"; }
 
@@ -227,24 +270,42 @@ bool Epub::generateCoverBmp() const {
     return true;
   }
 
-  if (coverImageItem.empty()) {
+  if (!bookMetadataCache || !bookMetadataCache->isLoaded()) {
+    Serial.printf("[%lu] [EBP] Cannot generate cover BMP, cache not loaded\n", millis());
+    return false;
+  }
+
+  const auto coverImageHref = bookMetadataCache->coreMetadata.coverItemHref;
+  if (coverImageHref.empty()) {
     Serial.printf("[%lu] [EBP] No known cover image\n", millis());
     return false;
   }
 
-  if (coverImageItem.substr(coverImageItem.length() - 4) == ".jpg" ||
+  if (coverImageHref.substr(coverImageHref.length() - 4) == ".jpg" ||
-      coverImageItem.substr(coverImageItem.length() - 5) == ".jpeg") {
+      coverImageHref.substr(coverImageHref.length() - 5) == ".jpeg") {
     Serial.printf("[%lu] [EBP] Generating BMP from JPG cover image\n", millis());
-    File coverJpg = SD.open((getCachePath() + "/.cover.jpg").c_str(), FILE_WRITE, true);
+    const auto coverJpgTempPath = getCachePath() + "/.cover.jpg";
-    readItemContentsToStream(coverImageItem, coverJpg, 1024);
+
+    File coverJpg;
+    if (!FsHelpers::openFileForWrite("EBP", coverJpgTempPath, coverJpg)) {
+      return false;
+    }
+    readItemContentsToStream(coverImageHref, coverJpg, 1024);
     coverJpg.close();
 
-    coverJpg = SD.open((getCachePath() + "/.cover.jpg").c_str(), FILE_READ);
+    if (!FsHelpers::openFileForRead("EBP", coverJpgTempPath, coverJpg)) {
-    File coverBmp = SD.open(getCoverBmpPath().c_str(), FILE_WRITE, true);
+      return false;
+    }
+
+    File coverBmp;
+    if (!FsHelpers::openFileForWrite("EBP", getCoverBmpPath(), coverBmp)) {
+      coverJpg.close();
+      return false;
+    }
     const bool success = JpegToBmpConverter::jpegFileToBmpStream(coverJpg, coverBmp);
     coverJpg.close();
     coverBmp.close();
-    SD.remove((getCachePath() + "/.cover.jpg").c_str());
+    SD.remove(coverJpgTempPath.c_str());
 
     if (!success) {
       Serial.printf("[%lu] [EBP] Failed to generate BMP from JPG cover image\n", millis());
@@ -259,45 +320,9 @@ bool Epub::generateCoverBmp() const {
   return false;
 }
 
-std::string normalisePath(const std::string& path) {
+uint8_t* Epub::readItemContentsToBytes(const std::string& itemHref, size_t* size, const bool trailingNullByte) const {
-  std::vector<std::string> components;
-  std::string component;
-
-  for (const auto c : path) {
-    if (c == '/') {
-      if (!component.empty()) {
-        if (component == "..") {
-          if (!components.empty()) {
-            components.pop_back();
-          }
-        } else {
-          components.push_back(component);
-        }
-        component.clear();
-      }
-    } else {
-      component += c;
-    }
-  }
-
-  if (!component.empty()) {
-    components.push_back(component);
-  }
-
-  std::string result;
-  for (const auto& c : components) {
-    if (!result.empty()) {
-      result += "/";
-    }
-    result += c;
-  }
-
-  return result;
-}
-
-uint8_t* Epub::readItemContentsToBytes(const std::string& itemHref, size_t* size, bool trailingNullByte) const {
   const ZipFile zip("/sd" + filepath);
-  const std::string path = normalisePath(itemHref);
+  const std::string path = FsHelpers::normalisePath(itemHref);
 
   const auto content = zip.readFileToMemory(path.c_str(), size, trailingNullByte);
   if (!content) {
@@ -310,7 +335,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 {
   const ZipFile zip("/sd" + filepath);
-  const std::string path = normalisePath(itemHref);
+  const std::string path = FsHelpers::normalisePath(itemHref);
 
   return zip.readFileToStream(path.c_str(), out, chunkSize);
 }
@@ -321,103 +346,93 @@ bool Epub::getItemSize(const std::string& itemHref, size_t* size) const {
 }
 
 bool Epub::getItemSize(const ZipFile& zip, const std::string& itemHref, size_t* size) {
-  const std::string path = normalisePath(itemHref);
+  const std::string path = FsHelpers::normalisePath(itemHref);
   return zip.getInflatedFileSize(path.c_str(), size);
 }
 
-int Epub::getSpineItemsCount() const { return spine.size(); }
+int Epub::getSpineItemsCount() const {
-
+  if (!bookMetadataCache || !bookMetadataCache->isLoaded()) {
-size_t Epub::getCumulativeSpineItemSize(const int spineIndex) const {
-  if (spineIndex < 0 || spineIndex >= static_cast<int>(cumulativeSpineItemSize.size())) {
-    Serial.printf("[%lu] [EBP] getCumulativeSpineItemSize index:%d is out of range\n", millis(), spineIndex);
     return 0;
   }
-  return cumulativeSpineItemSize.at(spineIndex);
+  return bookMetadataCache->getSpineCount();
 }
 
-std::string& Epub::getSpineItem(const int spineIndex) {
+size_t Epub::getCumulativeSpineItemSize(const int spineIndex) const { return getSpineItem(spineIndex).cumulativeSize; }
-  static std::string emptyString;
+
-  if (spine.empty()) {
+BookMetadataCache::SpineEntry Epub::getSpineItem(const int spineIndex) const {
-    Serial.printf("[%lu] [EBP] getSpineItem called but spine is empty\n", millis());
+  if (!bookMetadataCache || !bookMetadataCache->isLoaded()) {
-    return emptyString;
+    Serial.printf("[%lu] [EBP] getSpineItem called but cache not loaded\n", millis());
+    return {};
   }
-  if (spineIndex < 0 || spineIndex >= static_cast<int>(spine.size())) {
+
+  if (spineIndex < 0 || spineIndex >= bookMetadataCache->getSpineCount()) {
     Serial.printf("[%lu] [EBP] getSpineItem index:%d is out of range\n", millis(), spineIndex);
-    return spine.at(0).second;
+    return bookMetadataCache->getSpineEntry(0);
   }
 
-  return spine.at(spineIndex).second;
+  return bookMetadataCache->getSpineEntry(spineIndex);
 }
 
-EpubTocEntry& Epub::getTocItem(const int tocTndex) {
+BookMetadataCache::TocEntry Epub::getTocItem(const int tocIndex) const {
-  static EpubTocEntry emptyEntry = {};
+  if (!bookMetadataCache || !bookMetadataCache->isLoaded()) {
-  if (toc.empty()) {
+    Serial.printf("[%lu] [EBP] getTocItem called but cache not loaded\n", millis());
-    Serial.printf("[%lu] [EBP] getTocItem called but toc is empty\n", millis());
+    return {};
-    return emptyEntry;
-  }
-  if (tocTndex < 0 || tocTndex >= static_cast<int>(toc.size())) {
-    Serial.printf("[%lu] [EBP] getTocItem index:%d is out of range\n", millis(), tocTndex);
-    return toc.at(0);
   }
 
-  return toc.at(tocTndex);
+  if (tocIndex < 0 || tocIndex >= bookMetadataCache->getTocCount()) {
+    Serial.printf("[%lu] [EBP] getTocItem index:%d is out of range\n", millis(), tocIndex);
+    return {};
+  }
+
+  return bookMetadataCache->getTocEntry(tocIndex);
 }
 
-int Epub::getTocItemsCount() const { return toc.size(); }
+int Epub::getTocItemsCount() const {
+  if (!bookMetadataCache || !bookMetadataCache->isLoaded()) {
+    return 0;
+  }
+
+  return bookMetadataCache->getTocCount();
+}
 
 // work out the section index for a toc index
 int Epub::getSpineIndexForTocIndex(const int tocIndex) const {
-  if (tocIndex < 0 || tocIndex >= toc.size()) {
+  if (!bookMetadataCache || !bookMetadataCache->isLoaded()) {
+    Serial.printf("[%lu] [EBP] getSpineIndexForTocIndex called but cache not loaded\n", millis());
+    return 0;
+  }
+
+  if (tocIndex < 0 || tocIndex >= bookMetadataCache->getTocCount()) {
     Serial.printf("[%lu] [EBP] getSpineIndexForTocIndex: tocIndex %d out of range\n", millis(), tocIndex);
     return 0;
   }
 
-  // the toc entry should have an href that matches the spine item
+  const int spineIndex = bookMetadataCache->getTocEntry(tocIndex).spineIndex;
-  // so we can find the spine index by looking for the href
+  if (spineIndex < 0) {
-  for (int i = 0; i < spine.size(); i++) {
+    Serial.printf("[%lu] [EBP] Section not found for TOC index %d\n", millis(), tocIndex);
-    if (spine[i].second == toc[tocIndex].href) {
+    return 0;
-      return i;
-    }
   }
 
-  Serial.printf("[%lu] [EBP] Section not found\n", millis());
+  return spineIndex;
-  // not found - default to the start of the book
-  return 0;
 }
 
-int Epub::getTocIndexForSpineIndex(const int spineIndex) const {
+int Epub::getTocIndexForSpineIndex(const int spineIndex) const { return getSpineItem(spineIndex).tocIndex; }
-  if (spineIndex < 0 || spineIndex >= spine.size()) {
-    Serial.printf("[%lu] [EBP] getTocIndexForSpineIndex: spineIndex %d out of range\n", millis(), spineIndex);
-    return -1;
-  }
-
-  // the toc entry should have an href that matches the spine item
-  // so we can find the toc index by looking for the href
-  for (int i = 0; i < toc.size(); i++) {
-    if (toc[i].href == spine[spineIndex].second) {
-      return i;
-    }
-  }
-
-  Serial.printf("[%lu] [EBP] TOC item not found\n", millis());
-  return -1;
-}
 
 size_t Epub::getBookSize() const {
-  if (spine.empty()) {
+  if (!bookMetadataCache || !bookMetadataCache->isLoaded() || bookMetadataCache->getSpineCount() == 0) {
     return 0;
   }
   return getCumulativeSpineItemSize(getSpineItemsCount() - 1);
 }
 
 // Calculate progress in book
-uint8_t Epub::calculateProgress(const int currentSpineIndex, const float currentSpineRead) {
+uint8_t Epub::calculateProgress(const int currentSpineIndex, const float currentSpineRead) const {
-  size_t bookSize = getBookSize();
+  const size_t bookSize = getBookSize();
   if (bookSize == 0) {
     return 0;
   }
-  size_t prevChapterSize = (currentSpineIndex >= 1) ? getCumulativeSpineItemSize(currentSpineIndex - 1) : 0;
+  const size_t prevChapterSize = (currentSpineIndex >= 1) ? getCumulativeSpineItemSize(currentSpineIndex - 1) : 0;
-  size_t curChapterSize = getCumulativeSpineItemSize(currentSpineIndex) - prevChapterSize;
+  const size_t curChapterSize = getCumulativeSpineItemSize(currentSpineIndex) - prevChapterSize;
-  size_t sectionProgSize = currentSpineRead * curChapterSize;
+  const size_t sectionProgSize = currentSpineRead * curChapterSize;
   return round(static_cast<float>(prevChapterSize + sectionProgSize) / bookSize * 100.0);
 }

lib/Epub/Epub.h

@@ -1,38 +1,29 @@
 #pragma once
-#include <Print.h>
 
+#include <memory>
 #include <string>
 #include <unordered_map>
 #include <vector>
 
-#include "Epub/EpubTocEntry.h"
+#include "Epub/BookMetadataCache.h"
 
 class ZipFile;
 
 class Epub {
-  // the title read from the EPUB meta data
-  std::string title;
-  // the cover image
-  std::string coverImageItem;
   // the ncx file
   std::string tocNcxItem;
   // where is the EPUBfile?
   std::string filepath;
-  // the spine of the EPUB file
-  std::vector<std::pair<std::string, std::string>> spine;
-  // the file size of the spine items (proxy to book progress)
-  std::vector<size_t> cumulativeSpineItemSize;
-  // the toc of the EPUB file
-  std::vector<EpubTocEntry> toc;
   // the base path for items in the EPUB file
   std::string contentBasePath;
   // Uniq cache key based on filepath
   std::string cachePath;
+  // Spine and TOC cache
+  std::unique_ptr<BookMetadataCache> bookMetadataCache;
 
   bool findContentOpfFile(std::string* contentOpfFile) const;
-  bool parseContentOpf(const std::string& contentOpfFilePath);
+  bool parseContentOpf(BookMetadataCache::BookMetadata& bookMetadata);
-  bool parseTocNcxFile();
+  bool parseTocNcxFile() const;
-  void initializeSpineItemSizes();
   static bool getItemSize(const ZipFile& zip, const std::string& itemHref, size_t* size);
 
  public:
@@ -54,14 +45,14 @@ class Epub {
                                    bool trailingNullByte = false) const;
   bool readItemContentsToStream(const std::string& itemHref, Print& out, size_t chunkSize) const;
   bool getItemSize(const std::string& itemHref, size_t* size) const;
-  std::string& getSpineItem(int spineIndex);
+  BookMetadataCache::SpineEntry getSpineItem(int spineIndex) const;
+  BookMetadataCache::TocEntry getTocItem(int tocIndex) const;
   int getSpineItemsCount() const;
-  size_t getCumulativeSpineItemSize(const int spineIndex) const;
-  EpubTocEntry& getTocItem(int tocIndex);
   int getTocItemsCount() const;
   int getSpineIndexForTocIndex(int tocIndex) const;
   int getTocIndexForSpineIndex(int spineIndex) const;
+  size_t getCumulativeSpineItemSize(int spineIndex) const;
 
   size_t getBookSize() const;
-  uint8_t calculateProgress(const int currentSpineIndex, const float currentSpineRead);
+  uint8_t calculateProgress(const int currentSpineIndex, const float currentSpineRead) const;
 };

lib/Epub/Epub/BookMetadataCache.cpp

@@ -0,0 +1,326 @@
+#include "BookMetadataCache.h"
+
+#include <HardwareSerial.h>
+#include <SD.h>
+#include <Serialization.h>
+#include <ZipFile.h>
+
+#include <vector>
+
+#include "FsHelpers.h"
+
+namespace {
+constexpr uint8_t BOOK_CACHE_VERSION = 1;
+constexpr char bookBinFile[] = "/book.bin";
+constexpr char tmpSpineBinFile[] = "/spine.bin.tmp";
+constexpr char tmpTocBinFile[] = "/toc.bin.tmp";
+}  // namespace
+
+/* ============= WRITING / BUILDING FUNCTIONS ================ */
+
+bool BookMetadataCache::beginWrite() {
+  buildMode = true;
+  spineCount = 0;
+  tocCount = 0;
+  Serial.printf("[%lu] [BMC] Entering write mode\n", millis());
+  return true;
+}
+
+bool BookMetadataCache::beginContentOpfPass() {
+  Serial.printf("[%lu] [BMC] Beginning content opf pass\n", millis());
+
+  // Open spine file for writing
+  return FsHelpers::openFileForWrite("BMC", cachePath + tmpSpineBinFile, spineFile);
+}
+
+bool BookMetadataCache::endContentOpfPass() {
+  spineFile.close();
+  return true;
+}
+
+bool BookMetadataCache::beginTocPass() {
+  Serial.printf("[%lu] [BMC] Beginning toc pass\n", millis());
+
+  // Open spine file for reading
+  if (!FsHelpers::openFileForRead("BMC", cachePath + tmpSpineBinFile, spineFile)) {
+    return false;
+  }
+  if (!FsHelpers::openFileForWrite("BMC", cachePath + tmpTocBinFile, tocFile)) {
+    spineFile.close();
+    return false;
+  }
+  return true;
+}
+
+bool BookMetadataCache::endTocPass() {
+  tocFile.close();
+  spineFile.close();
+  return true;
+}
+
+bool BookMetadataCache::endWrite() {
+  if (!buildMode) {
+    Serial.printf("[%lu] [BMC] endWrite called but not in build mode\n", millis());
+    return false;
+  }
+
+  buildMode = false;
+  Serial.printf("[%lu] [BMC] Wrote %d spine, %d TOC entries\n", millis(), spineCount, tocCount);
+  return true;
+}
+
+bool BookMetadataCache::buildBookBin(const std::string& epubPath, const BookMetadata& metadata) {
+  // Open all three files, writing to meta, reading from spine and toc
+  if (!FsHelpers::openFileForWrite("BMC", cachePath + bookBinFile, bookFile)) {
+    return false;
+  }
+
+  if (!FsHelpers::openFileForRead("BMC", cachePath + tmpSpineBinFile, spineFile)) {
+    bookFile.close();
+    return false;
+  }
+
+  if (!FsHelpers::openFileForRead("BMC", cachePath + tmpTocBinFile, tocFile)) {
+    bookFile.close();
+    spineFile.close();
+    return false;
+  }
+
+  constexpr size_t headerASize =
+      sizeof(BOOK_CACHE_VERSION) + /* LUT Offset */ sizeof(size_t) + sizeof(spineCount) + sizeof(tocCount);
+  const size_t metadataSize =
+      metadata.title.size() + metadata.author.size() + metadata.coverItemHref.size() + sizeof(uint32_t) * 3;
+  const size_t lutSize = sizeof(size_t) * spineCount + sizeof(size_t) * tocCount;
+  const size_t lutOffset = headerASize + metadataSize;
+
+  // Header A
+  serialization::writePod(bookFile, BOOK_CACHE_VERSION);
+  serialization::writePod(bookFile, lutOffset);
+  serialization::writePod(bookFile, spineCount);
+  serialization::writePod(bookFile, tocCount);
+  // Metadata
+  serialization::writeString(bookFile, metadata.title);
+  serialization::writeString(bookFile, metadata.author);
+  serialization::writeString(bookFile, metadata.coverItemHref);
+
+  // Loop through spine entries, writing LUT positions
+  spineFile.seek(0);
+  for (int i = 0; i < spineCount; i++) {
+    auto pos = spineFile.position();
+    auto spineEntry = readSpineEntry(spineFile);
+    serialization::writePod(bookFile, pos + lutOffset + lutSize);
+  }
+
+  // Loop through toc entries, writing LUT positions
+  tocFile.seek(0);
+  for (int i = 0; i < tocCount; i++) {
+    auto pos = tocFile.position();
+    auto tocEntry = readTocEntry(tocFile);
+    serialization::writePod(bookFile, pos + lutOffset + lutSize + spineFile.position());
+  }
+
+  // LUTs complete
+  // Loop through spines from spine file matching up TOC indexes, calculating cumulative size and writing to book.bin
+
+  const ZipFile zip("/sd" + epubPath);
+  size_t cumSize = 0;
+  spineFile.seek(0);
+  for (int i = 0; i < spineCount; i++) {
+    auto spineEntry = readSpineEntry(spineFile);
+
+    tocFile.seek(0);
+    for (int j = 0; j < tocCount; j++) {
+      auto tocEntry = readTocEntry(tocFile);
+      if (tocEntry.spineIndex == i) {
+        spineEntry.tocIndex = j;
+        break;
+      }
+    }
+
+    // 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\n", millis(), i,
+                    spineEntry.href.c_str());
+    }
+
+    // Calculate size for cumulative size
+    size_t itemSize = 0;
+    const std::string path = FsHelpers::normalisePath(spineEntry.href);
+    if (zip.getInflatedFileSize(path.c_str(), &itemSize)) {
+      cumSize += itemSize;
+      spineEntry.cumulativeSize = cumSize;
+    } else {
+      Serial.printf("[%lu] [BMC] Warning: Could not get size for spine item: %s\n", millis(), path.c_str());
+    }
+
+    // Write out spine data to book.bin
+    writeSpineEntry(bookFile, spineEntry);
+  }
+
+  // Loop through toc entries from toc file writing to book.bin
+  tocFile.seek(0);
+  for (int i = 0; i < tocCount; i++) {
+    auto tocEntry = readTocEntry(tocFile);
+    writeTocEntry(bookFile, tocEntry);
+  }
+
+  bookFile.close();
+  spineFile.close();
+  tocFile.close();
+
+  Serial.printf("[%lu] [BMC] Successfully built book.bin\n", millis());
+  return true;
+}
+
+bool BookMetadataCache::cleanupTmpFiles() const {
+  if (SD.exists((cachePath + tmpSpineBinFile).c_str())) {
+    SD.remove((cachePath + tmpSpineBinFile).c_str());
+  }
+  if (SD.exists((cachePath + tmpTocBinFile).c_str())) {
+    SD.remove((cachePath + tmpTocBinFile).c_str());
+  }
+  return true;
+}
+
+size_t BookMetadataCache::writeSpineEntry(File& file, const SpineEntry& entry) const {
+  const auto pos = file.position();
+  serialization::writeString(file, entry.href);
+  serialization::writePod(file, entry.cumulativeSize);
+  serialization::writePod(file, entry.tocIndex);
+  return pos;
+}
+
+size_t BookMetadataCache::writeTocEntry(File& file, const TocEntry& entry) const {
+  const auto pos = file.position();
+  serialization::writeString(file, entry.title);
+  serialization::writeString(file, entry.href);
+  serialization::writeString(file, entry.anchor);
+  serialization::writePod(file, entry.level);
+  serialization::writePod(file, entry.spineIndex);
+  return pos;
+}
+
+// Note: for the LUT to be accurate, this **MUST** be called for all spine items before `addTocEntry` is ever called
+// 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());
+    return;
+  }
+
+  const SpineEntry entry(href, 0, -1);
+  writeSpineEntry(spineFile, entry);
+  spineCount++;
+}
+
+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());
+    return;
+  }
+
+  int spineIndex = -1;
+  // find spine index
+  spineFile.seek(0);
+  for (int i = 0; i < spineCount; i++) {
+    auto spineEntry = readSpineEntry(spineFile);
+    if (spineEntry.href == href) {
+      spineIndex = i;
+      break;
+    }
+  }
+
+  if (spineIndex == -1) {
+    Serial.printf("[%lu] [BMC] addTocEntry: Could not find spine item for TOC href %s\n", millis(), href.c_str());
+  }
+
+  const TocEntry entry(title, href, anchor, level, spineIndex);
+  writeTocEntry(tocFile, entry);
+  tocCount++;
+}
+
+/* ============= READING / LOADING FUNCTIONS ================ */
+
+bool BookMetadataCache::load() {
+  if (!FsHelpers::openFileForRead("BMC", cachePath + bookBinFile, bookFile)) {
+    return false;
+  }
+
+  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);
+    bookFile.close();
+    return false;
+  }
+
+  serialization::readPod(bookFile, lutOffset);
+  serialization::readPod(bookFile, spineCount);
+  serialization::readPod(bookFile, tocCount);
+
+  serialization::readString(bookFile, coreMetadata.title);
+  serialization::readString(bookFile, coreMetadata.author);
+  serialization::readString(bookFile, coreMetadata.coverItemHref);
+
+  loaded = true;
+  Serial.printf("[%lu] [BMC] Loaded cache data: %d spine, %d TOC entries\n", millis(), 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());
+    return {};
+  }
+
+  if (index < 0 || index >= static_cast<int>(spineCount)) {
+    Serial.printf("[%lu] [BMC] getSpineEntry index %d out of range\n", millis(), index);
+    return {};
+  }
+
+  // Seek to spine LUT item, read from LUT and get out data
+  bookFile.seek(lutOffset + sizeof(size_t) * index);
+  size_t spineEntryPos;
+  serialization::readPod(bookFile, spineEntryPos);
+  bookFile.seek(spineEntryPos);
+  return readSpineEntry(bookFile);
+}
+
+BookMetadataCache::TocEntry BookMetadataCache::getTocEntry(const int index) {
+  if (!loaded) {
+    Serial.printf("[%lu] [BMC] getTocEntry called but cache not loaded\n", millis());
+    return {};
+  }
+
+  if (index < 0 || index >= static_cast<int>(tocCount)) {
+    Serial.printf("[%lu] [BMC] getTocEntry index %d out of range\n", millis(), index);
+    return {};
+  }
+
+  // Seek to TOC LUT item, read from LUT and get out data
+  bookFile.seek(lutOffset + sizeof(size_t) * spineCount + sizeof(size_t) * index);
+  size_t tocEntryPos;
+  serialization::readPod(bookFile, tocEntryPos);
+  bookFile.seek(tocEntryPos);
+  return readTocEntry(bookFile);
+}
+
+BookMetadataCache::SpineEntry BookMetadataCache::readSpineEntry(File& file) const {
+  SpineEntry entry;
+  serialization::readString(file, entry.href);
+  serialization::readPod(file, entry.cumulativeSize);
+  serialization::readPod(file, entry.tocIndex);
+  return entry;
+}
+
+BookMetadataCache::TocEntry BookMetadataCache::readTocEntry(File& file) const {
+  TocEntry entry;
+  serialization::readString(file, entry.title);
+  serialization::readString(file, entry.href);
+  serialization::readString(file, entry.anchor);
+  serialization::readPod(file, entry.level);
+  serialization::readPod(file, entry.spineIndex);
+  return entry;
+}

lib/Epub/Epub/BookMetadataCache.h

@@ -0,0 +1,87 @@
+#pragma once
+
+#include <SD.h>
+
+#include <string>
+
+class BookMetadataCache {
+ public:
+  struct BookMetadata {
+    std::string title;
+    std::string author;
+    std::string coverItemHref;
+  };
+
+  struct SpineEntry {
+    std::string href;
+    size_t cumulativeSize;
+    int16_t tocIndex;
+
+    SpineEntry() : cumulativeSize(0), tocIndex(-1) {}
+    SpineEntry(std::string href, const size_t cumulativeSize, const int16_t tocIndex)
+        : href(std::move(href)), cumulativeSize(cumulativeSize), tocIndex(tocIndex) {}
+  };
+
+  struct TocEntry {
+    std::string title;
+    std::string href;
+    std::string anchor;
+    uint8_t level;
+    int16_t spineIndex;
+
+    TocEntry() : level(0), spineIndex(-1) {}
+    TocEntry(std::string title, std::string href, std::string anchor, const uint8_t level, const int16_t spineIndex)
+        : title(std::move(title)),
+          href(std::move(href)),
+          anchor(std::move(anchor)),
+          level(level),
+          spineIndex(spineIndex) {}
+  };
+
+ private:
+  std::string cachePath;
+  size_t lutOffset;
+  uint16_t spineCount;
+  uint16_t tocCount;
+  bool loaded;
+  bool buildMode;
+
+  File bookFile;
+  // Temp file handles during build
+  File spineFile;
+  File tocFile;
+
+  size_t writeSpineEntry(File& file, const SpineEntry& entry) const;
+  size_t writeTocEntry(File& file, const TocEntry& entry) const;
+  SpineEntry readSpineEntry(File& file) const;
+  TocEntry readTocEntry(File& file) const;
+
+ public:
+  BookMetadata coreMetadata;
+
+  explicit BookMetadataCache(std::string cachePath)
+      : cachePath(std::move(cachePath)), lutOffset(0), spineCount(0), tocCount(0), loaded(false), buildMode(false) {}
+  ~BookMetadataCache() = default;
+
+  // Building phase (stream to disk immediately)
+  bool beginWrite();
+  bool beginContentOpfPass();
+  void createSpineEntry(const std::string& href);
+  bool endContentOpfPass();
+  bool beginTocPass();
+  void createTocEntry(const std::string& title, const std::string& href, const std::string& anchor, uint8_t level);
+  bool endTocPass();
+  bool endWrite();
+  bool cleanupTmpFiles() const;
+
+  // Post-processing to update mappings and sizes
+  bool buildBookBin(const std::string& epubPath, const BookMetadata& metadata);
+
+  // Reading phase (read mode)
+  bool load();
+  SpineEntry getSpineEntry(int index);
+  TocEntry getTocEntry(int index);
+  int getSpineCount() const { return spineCount; }
+  int getTocCount() const { return tocCount; }
+  bool isLoaded() const { return loaded; }
+};

lib/Epub/Epub/EpubTocEntry.h

@@ -1,10 +0,0 @@
-#pragma once
-
-#include <string>
-
-struct EpubTocEntry {
-  std::string title;
-  std::string href;
-  std::string anchor;
-  uint8_t level;
-};

lib/Epub/Epub/FsHelpers.cpp

@@ -2,6 +2,26 @@
 
 #include <SD.h>
 
+#include <vector>
+
+bool FsHelpers::openFileForRead(const char* moduleName, const std::string& path, File& file) {
+  file = SD.open(path.c_str(), FILE_READ);
+  if (!file) {
+    Serial.printf("[%lu] [%s] Failed to open file for reading: %s\n", millis(), moduleName, path.c_str());
+    return false;
+  }
+  return true;
+}
+
+bool FsHelpers::openFileForWrite(const char* moduleName, const std::string& path, File& file) {
+  file = SD.open(path.c_str(), FILE_WRITE, true);
+  if (!file) {
+    Serial.printf("[%lu] [%s] Failed to open file for writing: %s\n", millis(), moduleName, path.c_str());
+    return false;
+  }
+  return true;
+}
+
 bool FsHelpers::removeDir(const char* path) {
   // 1. Open the directory
   File dir = SD.open(path);
@@ -34,3 +54,39 @@ bool FsHelpers::removeDir(const char* path) {
 
   return SD.rmdir(path);
 }
+
+std::string FsHelpers::normalisePath(const std::string& path) {
+  std::vector<std::string> components;
+  std::string component;
+
+  for (const auto c : path) {
+    if (c == '/') {
+      if (!component.empty()) {
+        if (component == "..") {
+          if (!components.empty()) {
+            components.pop_back();
+          }
+        } else {
+          components.push_back(component);
+        }
+        component.clear();
+      }
+    } else {
+      component += c;
+    }
+  }
+
+  if (!component.empty()) {
+    components.push_back(component);
+  }
+
+  std::string result;
+  for (const auto& c : components) {
+    if (!result.empty()) {
+      result += "/";
+    }
+    result += c;
+  }
+
+  return result;
+}

lib/Epub/Epub/FsHelpers.h

@@ -1,6 +1,12 @@
 #pragma once
+#include <FS.h>
+
+#include <string>
 
 class FsHelpers {
  public:
+  static bool openFileForRead(const char* moduleName, const std::string& path, File& file);
+  static bool openFileForWrite(const char* moduleName, const std::string& path, File& file);
   static bool removeDir(const char* path);
+  static std::string normalisePath(const std::string& path);
 };

lib/Epub/Epub/Page.cpp

@@ -7,48 +7,50 @@ namespace {
 constexpr uint8_t PAGE_FILE_VERSION = 3;
 }
 
-void PageLine::render(GfxRenderer& renderer, const int fontId) { block->render(renderer, fontId, xPos, yPos); }
+void PageLine::render(GfxRenderer& renderer, const int fontId, const int xOffset, const int yOffset) {
-
+  block->render(renderer, fontId, xPos + xOffset, yPos + yOffset);
-void PageLine::serialize(std::ostream& os) {
-  serialization::writePod(os, xPos);
-  serialization::writePod(os, yPos);
-
-  // serialize TextBlock pointed to by PageLine
-  block->serialize(os);
 }
 
-std::unique_ptr<PageLine> PageLine::deserialize(std::istream& is) {
+void PageLine::serialize(File& file) {
+  serialization::writePod(file, xPos);
+  serialization::writePod(file, yPos);
+
+  // serialize TextBlock pointed to by PageLine
+  block->serialize(file);
+}
+
+std::unique_ptr<PageLine> PageLine::deserialize(File& file) {
   int16_t xPos;
   int16_t yPos;
-  serialization::readPod(is, xPos);
+  serialization::readPod(file, xPos);
-  serialization::readPod(is, yPos);
+  serialization::readPod(file, yPos);
 
-  auto tb = TextBlock::deserialize(is);
+  auto tb = TextBlock::deserialize(file);
   return std::unique_ptr<PageLine>(new PageLine(std::move(tb), xPos, yPos));
 }
 
-void Page::render(GfxRenderer& renderer, const int fontId) const {
+void Page::render(GfxRenderer& renderer, const int fontId, const int xOffset, const int yOffset) const {
   for (auto& element : elements) {
-    element->render(renderer, fontId);
+    element->render(renderer, fontId, xOffset, yOffset);
   }
 }
 
-void Page::serialize(std::ostream& os) const {
+void Page::serialize(File& file) const {
-  serialization::writePod(os, PAGE_FILE_VERSION);
+  serialization::writePod(file, PAGE_FILE_VERSION);
 
   const uint32_t count = elements.size();
-  serialization::writePod(os, count);
+  serialization::writePod(file, count);
 
   for (const auto& el : elements) {
     // Only PageLine exists currently
-    serialization::writePod(os, static_cast<uint8_t>(TAG_PageLine));
+    serialization::writePod(file, static_cast<uint8_t>(TAG_PageLine));
-    el->serialize(os);
+    el->serialize(file);
   }
 }
 
-std::unique_ptr<Page> Page::deserialize(std::istream& is) {
+std::unique_ptr<Page> Page::deserialize(File& file) {
   uint8_t version;
-  serialization::readPod(is, version);
+  serialization::readPod(file, version);
   if (version != PAGE_FILE_VERSION) {
     Serial.printf("[%lu] [PGE] Deserialization failed: Unknown version %u\n", millis(), version);
     return nullptr;
@@ -57,14 +59,14 @@ std::unique_ptr<Page> Page::deserialize(std::istream& is) {
   auto page = std::unique_ptr<Page>(new Page());
 
   uint32_t count;
-  serialization::readPod(is, count);
+  serialization::readPod(file, count);
 
   for (uint32_t i = 0; i < count; i++) {
     uint8_t tag;
-    serialization::readPod(is, tag);
+    serialization::readPod(file, tag);
 
     if (tag == TAG_PageLine) {
-      auto pl = PageLine::deserialize(is);
+      auto pl = PageLine::deserialize(file);
       page->elements.push_back(std::move(pl));
     } else {
       Serial.printf("[%lu] [PGE] Deserialization failed: Unknown tag %u\n", millis(), tag);

lib/Epub/Epub/Page.h

@@ -1,4 +1,6 @@
 #pragma once
+#include <FS.h>
+
 #include <utility>
 #include <vector>
 
@@ -15,8 +17,8 @@ class PageElement {
   int16_t yPos;
   explicit PageElement(const int16_t xPos, const int16_t yPos) : xPos(xPos), yPos(yPos) {}
   virtual ~PageElement() = default;
-  virtual void render(GfxRenderer& renderer, int fontId) = 0;
+  virtual void render(GfxRenderer& renderer, int fontId, int xOffset, int yOffset) = 0;
-  virtual void serialize(std::ostream& os) = 0;
+  virtual void serialize(File& file) = 0;
 };
 
 // a line from a block element
@@ -26,16 +28,16 @@ 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)) {}
-  void render(GfxRenderer& renderer, int fontId) override;
+  void render(GfxRenderer& renderer, int fontId, int xOffset, int yOffset) override;
-  void serialize(std::ostream& os) override;
+  void serialize(File& file) override;
-  static std::unique_ptr<PageLine> deserialize(std::istream& is);
+  static std::unique_ptr<PageLine> deserialize(File& file);
 };
 
 class Page {
  public:
   // the list of block index and line numbers on this page
   std::vector<std::shared_ptr<PageElement>> elements;
-  void render(GfxRenderer& renderer, int fontId) const;
+  void render(GfxRenderer& renderer, int fontId, int xOffset, int yOffset) const;
-  void serialize(std::ostream& os) const;
+  void serialize(File& file) const;
-  static std::unique_ptr<Page> deserialize(std::istream& is);
+  static std::unique_ptr<Page> deserialize(File& file);
 };

lib/Epub/Epub/ParsedText.cpp

@@ -18,14 +18,14 @@ void ParsedText::addWord(std::string word, const EpdFontStyle fontStyle) {
 }
 
 // Consumes data to minimize memory usage
-void ParsedText::layoutAndExtractLines(const GfxRenderer& renderer, const int fontId, const int horizontalMargin,
+void ParsedText::layoutAndExtractLines(const GfxRenderer& renderer, const int fontId, const int viewportWidth,
                                        const std::function<void(std::shared_ptr<TextBlock>)>& processLine,
                                        const bool includeLastLine) {
   if (words.empty()) {
     return;
   }
 
-  const int pageWidth = renderer.getScreenWidth() - horizontalMargin;
+  const int pageWidth = viewportWidth;
   const int spaceWidth = renderer.getSpaceWidth(fontId);
   const auto wordWidths = calculateWordWidths(renderer, fontId);
   const auto lineBreakIndices = computeLineBreaks(pageWidth, spaceWidth, wordWidths);
@@ -106,21 +106,34 @@ std::vector<size_t> ParsedText::computeLineBreaks(const int pageWidth, const int
         ans[i] = j;  // j is the index of the last word in this optimal line
       }
     }
+
+    // Handle oversized word: if no valid configuration found, force single-word line
+    // This prevents cascade failure where one oversized word breaks all preceding words
+    if (dp[i] == MAX_COST) {
+      ans[i] = i;  // Just this word on its own line
+      // Inherit cost from next word to allow subsequent words to find valid configurations
+      if (i + 1 < static_cast<int>(totalWordCount)) {
+        dp[i] = dp[i + 1];
+      } else {
+        dp[i] = 0;
+      }
+    }
   }
 
   // Stores the index of the word that starts the next line (last_word_index + 1)
   std::vector<size_t> lineBreakIndices;
   size_t currentWordIndex = 0;
-  constexpr size_t MAX_LINES = 1000;
 
   while (currentWordIndex < totalWordCount) {
-    if (lineBreakIndices.size() >= MAX_LINES) {
+    size_t nextBreakIndex = ans[currentWordIndex] + 1;
-      break;
+
+    // Safety check: prevent infinite loop if nextBreakIndex doesn't advance
+    if (nextBreakIndex <= currentWordIndex) {
+      // Force advance by at least one word to avoid infinite loop
+      nextBreakIndex = currentWordIndex + 1;
     }
 
-    size_t nextBreakIndex = ans[currentWordIndex] + 1;
     lineBreakIndices.push_back(nextBreakIndex);
-
     currentWordIndex = nextBreakIndex;
   }
 

lib/Epub/Epub/ParsedText.h

@@ -34,7 +34,7 @@ class ParsedText {
   TextBlock::BLOCK_STYLE getStyle() const { return style; }
   size_t size() const { return words.size(); }
   bool isEmpty() const { return words.empty(); }
-  void layoutAndExtractLines(const GfxRenderer& renderer, int fontId, int horizontalMargin,
+  void layoutAndExtractLines(const GfxRenderer& renderer, int fontId, int viewportWidth,
                              const std::function<void(std::shared_ptr<TextBlock>)>& processLine,
                              bool includeLastLine = true);
 };

lib/Epub/Epub/Section.cpp

@@ -1,22 +1,23 @@
 #include "Section.h"
 
+#include <FsHelpers.h>
 #include <SD.h>
 #include <Serialization.h>
 
-#include <fstream>
-
-#include "FsHelpers.h"
 #include "Page.h"
 #include "parsers/ChapterHtmlSlimParser.h"
 
 namespace {
-constexpr uint8_t SECTION_FILE_VERSION = 5;
+constexpr uint8_t SECTION_FILE_VERSION = 6;
-}
+}  // namespace
 
 void Section::onPageComplete(std::unique_ptr<Page> page) {
   const auto filePath = cachePath + "/page_" + std::to_string(pageCount) + ".bin";
 
-  std::ofstream outputFile("/sd" + filePath);
+  File outputFile;
+  if (!FsHelpers::openFileForWrite("SCT", filePath, outputFile)) {
+    return;
+  }
   page->serialize(outputFile);
   outputFile.close();
 
@@ -25,36 +26,30 @@ void Section::onPageComplete(std::unique_ptr<Page> page) {
   pageCount++;
 }
 
-void Section::writeCacheMetadata(const int fontId, const float lineCompression, const int marginTop,
+void Section::writeCacheMetadata(const int fontId, const float lineCompression, const bool extraParagraphSpacing,
-                                 const int marginRight, const int marginBottom, const int marginLeft,
+                                 const int viewportWidth, const int viewportHeight) const {
-                                 const bool extraParagraphSpacing) const {
+  File outputFile;
-  std::ofstream outputFile(("/sd" + cachePath + "/section.bin").c_str());
+  if (!FsHelpers::openFileForWrite("SCT", cachePath + "/section.bin", outputFile)) {
+    return;
+  }
   serialization::writePod(outputFile, SECTION_FILE_VERSION);
   serialization::writePod(outputFile, fontId);
   serialization::writePod(outputFile, lineCompression);
-  serialization::writePod(outputFile, marginTop);
-  serialization::writePod(outputFile, marginRight);
-  serialization::writePod(outputFile, marginBottom);
-  serialization::writePod(outputFile, marginLeft);
   serialization::writePod(outputFile, extraParagraphSpacing);
+  serialization::writePod(outputFile, viewportWidth);
+  serialization::writePod(outputFile, viewportHeight);
   serialization::writePod(outputFile, pageCount);
   outputFile.close();
 }
 
-bool Section::loadCacheMetadata(const int fontId, const float lineCompression, const int marginTop,
+bool Section::loadCacheMetadata(const int fontId, const float lineCompression, const bool extraParagraphSpacing,
-                                const int marginRight, const int marginBottom, const int marginLeft,
+                                const int viewportWidth, const int viewportHeight) {
-                                const bool extraParagraphSpacing) {
-  if (!SD.exists(cachePath.c_str())) {
-    return false;
-  }
-
   const auto sectionFilePath = cachePath + "/section.bin";
-  if (!SD.exists(sectionFilePath.c_str())) {
+  File inputFile;
+  if (!FsHelpers::openFileForRead("SCT", sectionFilePath, inputFile)) {
     return false;
   }
 
-  std::ifstream inputFile(("/sd" + sectionFilePath).c_str());
-
   // Match parameters
   {
     uint8_t version;
@@ -66,20 +61,18 @@ bool Section::loadCacheMetadata(const int fontId, const float lineCompression, c
       return false;
     }
 
-    int fileFontId, fileMarginTop, fileMarginRight, fileMarginBottom, fileMarginLeft;
+    int fileFontId, fileViewportWidth, fileViewportHeight;
     float fileLineCompression;
     bool fileExtraParagraphSpacing;
     serialization::readPod(inputFile, fileFontId);
     serialization::readPod(inputFile, fileLineCompression);
-    serialization::readPod(inputFile, fileMarginTop);
-    serialization::readPod(inputFile, fileMarginRight);
-    serialization::readPod(inputFile, fileMarginBottom);
-    serialization::readPod(inputFile, fileMarginLeft);
     serialization::readPod(inputFile, fileExtraParagraphSpacing);
+    serialization::readPod(inputFile, fileViewportWidth);
+    serialization::readPod(inputFile, fileViewportHeight);
 
-    if (fontId != fileFontId || lineCompression != fileLineCompression || marginTop != fileMarginTop ||
+    if (fontId != fileFontId || lineCompression != fileLineCompression ||
-        marginRight != fileMarginRight || marginBottom != fileMarginBottom || marginLeft != fileMarginLeft ||
+        extraParagraphSpacing != fileExtraParagraphSpacing || viewportWidth != fileViewportWidth ||
-        extraParagraphSpacing != fileExtraParagraphSpacing) {
+        viewportHeight != fileViewportHeight) {
       inputFile.close();
       Serial.printf("[%lu] [SCT] Deserialization failed: Parameters do not match\n", millis());
       clearCache();
@@ -114,31 +107,58 @@ bool Section::clearCache() const {
   return true;
 }
 
-bool Section::persistPageDataToSD(const int fontId, const float lineCompression, const int marginTop,
+bool Section::persistPageDataToSD(const int fontId, const float lineCompression, const bool extraParagraphSpacing,
-                                  const int marginRight, const int marginBottom, const int marginLeft,
+                                  const int viewportWidth, const int viewportHeight,
-                                  const bool extraParagraphSpacing) {
+                                  const std::function<void()>& progressSetupFn,
-  const auto localPath = epub->getSpineItem(spineIndex);
+                                  const std::function<void(int)>& progressFn) {
-
+  constexpr size_t MIN_SIZE_FOR_PROGRESS = 50 * 1024;  // 50KB
-  // TODO: Should we get rid of this file all together?
+  const auto localPath = epub->getSpineItem(spineIndex).href;
-  //       It currently saves us a bit of memory by allowing for all the inflation bits to be released
-  //       before loading the XML parser
   const auto tmpHtmlPath = epub->getCachePath() + "/.tmp_" + std::to_string(spineIndex) + ".html";
-  File f = SD.open(tmpHtmlPath.c_str(), FILE_WRITE, true);
+
-  bool success = epub->readItemContentsToStream(localPath, f, 1024);
+  // Retry logic for SD card timing issues
-  f.close();
+  bool success = false;
+  size_t fileSize = 0;
+  for (int attempt = 0; attempt < 3 && !success; attempt++) {
+    if (attempt > 0) {
+      Serial.printf("[%lu] [SCT] Retrying stream (attempt %d)...\n", millis(), attempt + 1);
+      delay(50);  // Brief delay before retry
+    }
+
+    // Remove any incomplete file from previous attempt before retrying
+    if (SD.exists(tmpHtmlPath.c_str())) {
+      SD.remove(tmpHtmlPath.c_str());
+    }
+
+    File tmpHtml;
+    if (!FsHelpers::openFileForWrite("SCT", tmpHtmlPath, tmpHtml)) {
+      continue;
+    }
+    success = epub->readItemContentsToStream(localPath, tmpHtml, 1024);
+    fileSize = tmpHtml.size();
+    tmpHtml.close();
+
+    // If streaming failed, remove the incomplete file immediately
+    if (!success && SD.exists(tmpHtmlPath.c_str())) {
+      SD.remove(tmpHtmlPath.c_str());
+      Serial.printf("[%lu] [SCT] Removed incomplete temp file after failed attempt\n", millis());
+    }
+  }
 
   if (!success) {
-    Serial.printf("[%lu] [SCT] Failed to stream item contents to temp file\n", millis());
+    Serial.printf("[%lu] [SCT] Failed to stream item contents to temp file after retries\n", millis());
     return false;
   }
 
-  Serial.printf("[%lu] [SCT] Streamed temp HTML to %s\n", millis(), tmpHtmlPath.c_str());
+  Serial.printf("[%lu] [SCT] Streamed temp HTML to %s (%d bytes)\n", millis(), tmpHtmlPath.c_str(), fileSize);
 
-  const auto sdTmpHtmlPath = "/sd" + tmpHtmlPath;
+  // Only show progress bar for larger chapters where rendering overhead is worth it
+  if (progressSetupFn && fileSize >= MIN_SIZE_FOR_PROGRESS) {
+    progressSetupFn();
+  }
 
-  ChapterHtmlSlimParser visitor(sdTmpHtmlPath.c_str(), renderer, fontId, lineCompression, marginTop, marginRight,
+  ChapterHtmlSlimParser visitor(
-                                marginBottom, marginLeft, extraParagraphSpacing,
+      tmpHtmlPath, renderer, fontId, lineCompression, extraParagraphSpacing, viewportWidth, viewportHeight,
-                                [this](std::unique_ptr<Page> page) { this->onPageComplete(std::move(page)); });
+      [this](std::unique_ptr<Page> page) { this->onPageComplete(std::move(page)); }, progressFn);
   success = visitor.parseAndBuildPages();
 
   SD.remove(tmpHtmlPath.c_str());
@@ -147,19 +167,18 @@ bool Section::persistPageDataToSD(const int fontId, const float lineCompression,
     return false;
   }
 
-  writeCacheMetadata(fontId, lineCompression, marginTop, marginRight, marginBottom, marginLeft, extraParagraphSpacing);
+  writeCacheMetadata(fontId, lineCompression, extraParagraphSpacing, viewportWidth, viewportHeight);
 
   return true;
 }
 
 std::unique_ptr<Page> Section::loadPageFromSD() const {
-  const auto filePath = "/sd" + cachePath + "/page_" + std::to_string(currentPage) + ".bin";
+  const auto filePath = cachePath + "/page_" + std::to_string(currentPage) + ".bin";
-  if (!SD.exists(filePath.c_str() + 3)) {
+
-    Serial.printf("[%lu] [SCT] Page file does not exist: %s\n", millis(), filePath.c_str());
+  File inputFile;
+  if (!FsHelpers::openFileForRead("SCT", filePath, inputFile)) {
     return nullptr;
   }
-
-  std::ifstream inputFile(filePath);
   auto page = Page::deserialize(inputFile);
   inputFile.close();
   return page;

lib/Epub/Epub/Section.h

@@ -1,4 +1,5 @@
 #pragma once
+#include <functional>
 #include <memory>
 
 #include "Epub.h"
@@ -12,8 +13,8 @@ class Section {
   GfxRenderer& renderer;
   std::string cachePath;
 
-  void writeCacheMetadata(int fontId, float lineCompression, int marginTop, int marginRight, int marginBottom,
+  void writeCacheMetadata(int fontId, float lineCompression, bool extraParagraphSpacing, int viewportWidth,
-                          int marginLeft, bool extraParagraphSpacing) const;
+                          int viewportHeight) const;
   void onPageComplete(std::unique_ptr<Page> page);
 
  public:
@@ -26,11 +27,12 @@ class Section {
         renderer(renderer),
         cachePath(epub->getCachePath() + "/" + std::to_string(spineIndex)) {}
   ~Section() = default;
-  bool loadCacheMetadata(int fontId, float lineCompression, int marginTop, int marginRight, int marginBottom,
+  bool loadCacheMetadata(int fontId, float lineCompression, bool extraParagraphSpacing, int viewportWidth,
-                         int marginLeft, bool extraParagraphSpacing);
+                         int viewportHeight);
   void setupCacheDir() const;
   bool clearCache() const;
-  bool persistPageDataToSD(int fontId, float lineCompression, int marginTop, int marginRight, int marginBottom,
+  bool persistPageDataToSD(int fontId, float lineCompression, bool extraParagraphSpacing, int viewportWidth,
-                           int marginLeft, bool extraParagraphSpacing);
+                           int viewportHeight, const std::function<void()>& progressSetupFn = nullptr,
+                           const std::function<void(int)>& progressFn = nullptr);
   std::unique_ptr<Page> loadPageFromSD() const;
 };

lib/Epub/Epub/blocks/TextBlock.cpp

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

lib/Epub/Epub/blocks/TextBlock.h

@@ -1,5 +1,6 @@
 #pragma once
 #include <EpdFontFamily.h>
+#include <FS.h>
 
 #include <list>
 #include <memory>
@@ -35,6 +36,6 @@ class TextBlock final : public Block {
   // 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; }
-  void serialize(std::ostream& os) const;
+  void serialize(File& file) const;
-  static std::unique_ptr<TextBlock> deserialize(std::istream& is);
+  static std::unique_ptr<TextBlock> deserialize(File& file);
 };

lib/Epub/Epub/parsers/ChapterHtmlSlimParser.cpp

@@ -1,5 +1,6 @@
 #include "ChapterHtmlSlimParser.h"
 
+#include <FsHelpers.h>
 #include <GfxRenderer.h>
 #include <HardwareSerial.h>
 #include <expat.h>
@@ -10,13 +11,16 @@
 const char* HEADER_TAGS[] = {"h1", "h2", "h3", "h4", "h5", "h6"};
 constexpr int NUM_HEADER_TAGS = sizeof(HEADER_TAGS) / sizeof(HEADER_TAGS[0]);
 
-const char* BLOCK_TAGS[] = {"p", "li", "div", "br"};
+// Minimum file size (in bytes) to show progress bar - smaller chapters don't benefit from it
+constexpr size_t MIN_SIZE_FOR_PROGRESS = 50 * 1024;  // 50KB
+
+const char* BLOCK_TAGS[] = {"p", "li", "div", "br", "blockquote"};
 constexpr int NUM_BLOCK_TAGS = sizeof(BLOCK_TAGS) / sizeof(BLOCK_TAGS[0]);
 
-const char* BOLD_TAGS[] = {"b"};
+const char* BOLD_TAGS[] = {"b", "strong"};
 constexpr int NUM_BOLD_TAGS = sizeof(BOLD_TAGS) / sizeof(BOLD_TAGS[0]);
 
-const char* ITALIC_TAGS[] = {"i"};
+const char* ITALIC_TAGS[] = {"i", "em"};
 constexpr int NUM_ITALIC_TAGS = sizeof(ITALIC_TAGS) / sizeof(ITALIC_TAGS[0]);
 
 const char* IMAGE_TAGS[] = {"img"};
@@ -151,7 +155,7 @@ void XMLCALL ChapterHtmlSlimParser::characterData(void* userData, const XML_Char
   if (self->currentTextBlock->size() > 750) {
     Serial.printf("[%lu] [EHP] Text block too long, splitting into multiple pages\n", millis());
     self->currentTextBlock->layoutAndExtractLines(
-        self->renderer, self->fontId, self->marginLeft + self->marginRight,
+        self->renderer, self->fontId, self->viewportWidth,
         [self](const std::shared_ptr<TextBlock>& textBlock) { self->addLineToPage(textBlock); }, false);
   }
 }
@@ -214,48 +218,75 @@ bool ChapterHtmlSlimParser::parseAndBuildPages() {
     return false;
   }
 
-  XML_SetUserData(parser, this);
+  File file;
-  XML_SetElementHandler(parser, startElement, endElement);
+  if (!FsHelpers::openFileForRead("EHP", filepath, file)) {
-  XML_SetCharacterDataHandler(parser, characterData);
-
-  FILE* file = fopen(filepath, "r");
-  if (!file) {
-    Serial.printf("[%lu] [EHP] Couldn't open file %s\n", millis(), filepath);
     XML_ParserFree(parser);
     return false;
   }
 
+  // Get file size for progress calculation
+  const size_t totalSize = file.size();
+  size_t bytesRead = 0;
+  int lastProgress = -1;
+
+  XML_SetUserData(parser, this);
+  XML_SetElementHandler(parser, startElement, endElement);
+  XML_SetCharacterDataHandler(parser, characterData);
+
   do {
     void* const buf = XML_GetBuffer(parser, 1024);
     if (!buf) {
       Serial.printf("[%lu] [EHP] Couldn't allocate memory for buffer\n", millis());
+      XML_StopParser(parser, XML_FALSE);                // Stop any pending processing
+      XML_SetElementHandler(parser, nullptr, nullptr);  // Clear callbacks
+      XML_SetCharacterDataHandler(parser, nullptr);
       XML_ParserFree(parser);
-      fclose(file);
+      file.close();
       return false;
     }
 
-    const size_t len = fread(buf, 1, 1024, file);
+    const size_t len = file.read(static_cast<uint8_t*>(buf), 1024);
 
-    if (ferror(file)) {
+    if (len == 0) {
       Serial.printf("[%lu] [EHP] File read error\n", millis());
+      XML_StopParser(parser, XML_FALSE);                // Stop any pending processing
+      XML_SetElementHandler(parser, nullptr, nullptr);  // Clear callbacks
+      XML_SetCharacterDataHandler(parser, nullptr);
       XML_ParserFree(parser);
-      fclose(file);
+      file.close();
       return false;
     }
 
-    done = feof(file);
+    // Update progress (call every 10% change to avoid too frequent updates)
+    // Only show progress for larger chapters where rendering overhead is worth it
+    bytesRead += len;
+    if (progressFn && totalSize >= MIN_SIZE_FOR_PROGRESS) {
+      const int progress = static_cast<int>((bytesRead * 100) / totalSize);
+      if (lastProgress / 10 != progress / 10) {
+        lastProgress = progress;
+        progressFn(progress);
+      }
+    }
+
+    done = file.available() == 0;
 
     if (XML_ParseBuffer(parser, static_cast<int>(len), done) == XML_STATUS_ERROR) {
       Serial.printf("[%lu] [EHP] Parse error at line %lu:\n%s\n", millis(), 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);
       XML_ParserFree(parser);
-      fclose(file);
+      file.close();
       return false;
     }
   } while (!done);
 
+  XML_StopParser(parser, XML_FALSE);                // Stop any pending processing
+  XML_SetElementHandler(parser, nullptr, nullptr);  // Clear callbacks
+  XML_SetCharacterDataHandler(parser, nullptr);
   XML_ParserFree(parser);
-  fclose(file);
+  file.close();
 
   // Process last page if there is still text
   if (currentTextBlock) {
@@ -270,15 +301,14 @@ bool ChapterHtmlSlimParser::parseAndBuildPages() {
 
 void ChapterHtmlSlimParser::addLineToPage(std::shared_ptr<TextBlock> line) {
   const int lineHeight = renderer.getLineHeight(fontId) * lineCompression;
-  const int pageHeight = GfxRenderer::getScreenHeight() - marginTop - marginBottom;
 
-  if (currentPageNextY + lineHeight > pageHeight) {
+  if (currentPageNextY + lineHeight > viewportHeight) {
     completePageFn(std::move(currentPage));
     currentPage.reset(new Page());
-    currentPageNextY = marginTop;
+    currentPageNextY = 0;
   }
 
-  currentPage->elements.push_back(std::make_shared<PageLine>(line, marginLeft, currentPageNextY));
+  currentPage->elements.push_back(std::make_shared<PageLine>(line, 0, currentPageNextY));
   currentPageNextY += lineHeight;
 }
 
@@ -290,12 +320,12 @@ void ChapterHtmlSlimParser::makePages() {
 
   if (!currentPage) {
     currentPage.reset(new Page());
-    currentPageNextY = marginTop;
+    currentPageNextY = 0;
   }
 
   const int lineHeight = renderer.getLineHeight(fontId) * lineCompression;
   currentTextBlock->layoutAndExtractLines(
-      renderer, fontId, marginLeft + marginRight,
+      renderer, fontId, viewportWidth,
       [this](const std::shared_ptr<TextBlock>& textBlock) { addLineToPage(textBlock); });
   // Extra paragraph spacing if enabled
   if (extraParagraphSpacing) {

lib/Epub/Epub/parsers/ChapterHtmlSlimParser.h

@@ -15,9 +15,10 @@ class GfxRenderer;
 #define MAX_WORD_SIZE 200
 
 class ChapterHtmlSlimParser {
-  const char* filepath;
+  const std::string& filepath;
   GfxRenderer& renderer;
   std::function<void(std::unique_ptr<Page>)> completePageFn;
+  std::function<void(int)> progressFn;  // Progress callback (0-100)
   int depth = 0;
   int skipUntilDepth = INT_MAX;
   int boldUntilDepth = INT_MAX;
@@ -31,11 +32,9 @@ class ChapterHtmlSlimParser {
   int16_t currentPageNextY = 0;
   int fontId;
   float lineCompression;
-  int marginTop;
-  int marginRight;
-  int marginBottom;
-  int marginLeft;
   bool extraParagraphSpacing;
+  int viewportWidth;
+  int viewportHeight;
 
   void startNewTextBlock(TextBlock::BLOCK_STYLE style);
   void makePages();
@@ -45,20 +44,20 @@ class ChapterHtmlSlimParser {
   static void XMLCALL endElement(void* userData, const XML_Char* name);
 
  public:
-  explicit ChapterHtmlSlimParser(const char* filepath, GfxRenderer& renderer, const int fontId,
+  explicit ChapterHtmlSlimParser(const std::string& filepath, GfxRenderer& renderer, const int fontId,
-                                 const float lineCompression, const int marginTop, const int marginRight,
+                                 const float lineCompression, const bool extraParagraphSpacing, const int viewportWidth,
-                                 const int marginBottom, const int marginLeft, const bool extraParagraphSpacing,
+                                 const int viewportHeight,
-                                 const std::function<void(std::unique_ptr<Page>)>& completePageFn)
+                                 const std::function<void(std::unique_ptr<Page>)>& completePageFn,
+                                 const std::function<void(int)>& progressFn = nullptr)
       : filepath(filepath),
         renderer(renderer),
         fontId(fontId),
         lineCompression(lineCompression),
-        marginTop(marginTop),
-        marginRight(marginRight),
-        marginBottom(marginBottom),
-        marginLeft(marginLeft),
         extraParagraphSpacing(extraParagraphSpacing),
-        completePageFn(completePageFn) {}
+        viewportWidth(viewportWidth),
+        viewportHeight(viewportHeight),
+        completePageFn(completePageFn),
+        progressFn(progressFn) {}
   ~ChapterHtmlSlimParser() = default;
   bool parseAndBuildPages();
   void addLineToPage(std::shared_ptr<TextBlock> line);

lib/Epub/Epub/parsers/ContainerParser.cpp

@@ -16,6 +16,8 @@ bool ContainerParser::setup() {
 
 ContainerParser::~ContainerParser() {
   if (parser) {
+    XML_StopParser(parser, XML_FALSE);                // Stop any pending processing
+    XML_SetElementHandler(parser, nullptr, nullptr);  // Clear callbacks
     XML_ParserFree(parser);
     parser = nullptr;
   }

lib/Epub/Epub/parsers/ContentOpfParser.cpp

@@ -1,11 +1,16 @@
 #include "ContentOpfParser.h"
 
+#include <FsHelpers.h>
 #include <HardwareSerial.h>
+#include <Serialization.h>
 #include <ZipFile.h>
 
+#include "../BookMetadataCache.h"
+
 namespace {
 constexpr char MEDIA_TYPE_NCX[] = "application/x-dtbncx+xml";
-}
+constexpr char itemCacheFile[] = "/.items.bin";
+}  // namespace
 
 bool ContentOpfParser::setup() {
   parser = XML_ParserCreate(nullptr);
@@ -22,9 +27,18 @@ bool ContentOpfParser::setup() {
 
 ContentOpfParser::~ContentOpfParser() {
   if (parser) {
+    XML_StopParser(parser, XML_FALSE);                // Stop any pending processing
+    XML_SetElementHandler(parser, nullptr, nullptr);  // Clear callbacks
+    XML_SetCharacterDataHandler(parser, nullptr);
     XML_ParserFree(parser);
     parser = nullptr;
   }
+  if (tempItemStore) {
+    tempItemStore.close();
+  }
+  if (SD.exists((cachePath + itemCacheFile).c_str())) {
+    SD.remove((cachePath + itemCacheFile).c_str());
+  }
 }
 
 size_t ContentOpfParser::write(const uint8_t data) { return write(&data, 1); }
@@ -40,6 +54,9 @@ size_t ContentOpfParser::write(const uint8_t* buffer, const size_t size) {
 
     if (!buf) {
       Serial.printf("[%lu] [COF] Couldn't allocate memory for buffer\n", millis());
+      XML_StopParser(parser, XML_FALSE);                // Stop any pending processing
+      XML_SetElementHandler(parser, nullptr, nullptr);  // Clear callbacks
+      XML_SetCharacterDataHandler(parser, nullptr);
       XML_ParserFree(parser);
       parser = nullptr;
       return 0;
@@ -51,6 +68,9 @@ size_t ContentOpfParser::write(const uint8_t* buffer, const size_t size) {
     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)));
+      XML_StopParser(parser, XML_FALSE);                // Stop any pending processing
+      XML_SetElementHandler(parser, nullptr, nullptr);  // Clear callbacks
+      XML_SetCharacterDataHandler(parser, nullptr);
       XML_ParserFree(parser);
       parser = nullptr;
       return 0;
@@ -85,11 +105,21 @@ 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 (!FsHelpers::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());
+    }
     return;
   }
 
   if (self->state == IN_PACKAGE && (strcmp(name, "spine") == 0 || strcmp(name, "opf:spine") == 0)) {
     self->state = IN_SPINE;
+    if (!FsHelpers::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());
+    }
     return;
   }
 
@@ -126,7 +156,13 @@ void XMLCALL ContentOpfParser::startElement(void* userData, const XML_Char* name
       }
     }
 
-    self->items[itemId] = href;
+    // Write items down to SD card
+    serialization::writeString(self->tempItemStore, itemId);
+    serialization::writeString(self->tempItemStore, href);
+
+    if (itemId == self->coverItemId) {
+      self->coverItemHref = href;
+    }
 
     if (mediaType == MEDIA_TYPE_NCX) {
       if (self->tocNcxPath.empty()) {
@@ -139,14 +175,29 @@ void XMLCALL ContentOpfParser::startElement(void* userData, const XML_Char* name
     return;
   }
 
-  if (self->state == IN_SPINE && (strcmp(name, "itemref") == 0 || strcmp(name, "opf:itemref") == 0)) {
+  // NOTE: This relies on spine appearing after item manifest (which is pretty safe as it's part of the EPUB spec)
-    for (int i = 0; atts[i]; i += 2) {
+  // Only run the spine parsing if there's a cache to add it to
-      if (strcmp(atts[i], "idref") == 0) {
+  if (self->cache) {
-        self->spineRefs.emplace_back(atts[i + 1]);
+    if (self->state == IN_SPINE && (strcmp(name, "itemref") == 0 || strcmp(name, "opf:itemref") == 0)) {
-        break;
+      for (int i = 0; atts[i]; i += 2) {
+        if (strcmp(atts[i], "idref") == 0) {
+          const std::string idref = atts[i + 1];
+          // Resolve the idref to href using items map
+          self->tempItemStore.seek(0);
+          std::string itemId;
+          std::string href;
+          while (self->tempItemStore.available()) {
+            serialization::readString(self->tempItemStore, itemId);
+            serialization::readString(self->tempItemStore, href);
+            if (itemId == idref) {
+              self->cache->createSpineEntry(href);
+              break;
+            }
+          }
+        }
       }
+      return;
     }
-    return;
   }
 }
 
@@ -165,11 +216,13 @@ void XMLCALL ContentOpfParser::endElement(void* userData, const XML_Char* name)
 
   if (self->state == IN_SPINE && (strcmp(name, "spine") == 0 || strcmp(name, "opf:spine") == 0)) {
     self->state = IN_PACKAGE;
+    self->tempItemStore.close();
     return;
   }
 
   if (self->state == IN_MANIFEST && (strcmp(name, "manifest") == 0 || strcmp(name, "opf:manifest") == 0)) {
     self->state = IN_PACKAGE;
+    self->tempItemStore.close();
     return;
   }
 

lib/Epub/Epub/parsers/ContentOpfParser.h

@@ -1,11 +1,11 @@
 #pragma once
 #include <Print.h>
 
-#include <map>
-
 #include "Epub.h"
 #include "expat.h"
 
+class BookMetadataCache;
+
 class ContentOpfParser final : public Print {
   enum ParserState {
     START,
@@ -16,10 +16,14 @@ class ContentOpfParser final : public Print {
     IN_SPINE,
   };
 
+  const std::string& cachePath;
   const std::string& baseContentPath;
   size_t remainingSize;
   XML_Parser parser = nullptr;
   ParserState state = START;
+  BookMetadataCache* cache;
+  File tempItemStore;
+  std::string coverItemId;
 
   static void startElement(void* userData, const XML_Char* name, const XML_Char** atts);
   static void characterData(void* userData, const XML_Char* s, int len);
@@ -28,12 +32,11 @@ class ContentOpfParser final : public Print {
  public:
   std::string title;
   std::string tocNcxPath;
-  std::string coverItemId;
+  std::string coverItemHref;
-  std::map<std::string, std::string> items;
-  std::vector<std::string> spineRefs;
 
-  explicit ContentOpfParser(const std::string& baseContentPath, const size_t xmlSize)
+  explicit ContentOpfParser(const std::string& cachePath, const std::string& baseContentPath, const size_t xmlSize,
-      : baseContentPath(baseContentPath), remainingSize(xmlSize) {}
+                            BookMetadataCache* cache)
+      : cachePath(cachePath), baseContentPath(baseContentPath), remainingSize(xmlSize), cache(cache) {}
   ~ContentOpfParser() override;
 
   bool setup();

lib/Epub/Epub/parsers/TocNcxParser.cpp

@@ -1,8 +1,9 @@
 #include "TocNcxParser.h"
 
-#include <Esp.h>
 #include <HardwareSerial.h>
 
+#include "../BookMetadataCache.h"
+
 bool TocNcxParser::setup() {
   parser = XML_ParserCreate(nullptr);
   if (!parser) {
@@ -18,6 +19,9 @@ bool TocNcxParser::setup() {
 
 TocNcxParser::~TocNcxParser() {
   if (parser) {
+    XML_StopParser(parser, XML_FALSE);                // Stop any pending processing
+    XML_SetElementHandler(parser, nullptr, nullptr);  // Clear callbacks
+    XML_SetCharacterDataHandler(parser, nullptr);
     XML_ParserFree(parser);
     parser = nullptr;
   }
@@ -35,6 +39,11 @@ size_t TocNcxParser::write(const uint8_t* buffer, const size_t size) {
     void* const buf = XML_GetBuffer(parser, 1024);
     if (!buf) {
       Serial.printf("[%lu] [TOC] Couldn't allocate memory for buffer\n", millis());
+      XML_StopParser(parser, XML_FALSE);                // Stop any pending processing
+      XML_SetElementHandler(parser, nullptr, nullptr);  // Clear callbacks
+      XML_SetCharacterDataHandler(parser, nullptr);
+      XML_ParserFree(parser);
+      parser = nullptr;
       return 0;
     }
 
@@ -44,6 +53,11 @@ size_t TocNcxParser::write(const uint8_t* buffer, const size_t size) {
     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)));
+      XML_StopParser(parser, XML_FALSE);                // Stop any pending processing
+      XML_SetElementHandler(parser, nullptr, nullptr);  // Clear callbacks
+      XML_SetCharacterDataHandler(parser, nullptr);
+      XML_ParserFree(parser);
+      parser = nullptr;
       return 0;
     }
 
@@ -154,8 +168,9 @@ void XMLCALL TocNcxParser::endElement(void* userData, const XML_Char* name) {
         href = href.substr(0, pos);
       }
 
-      // Push to vector
+      if (self->cache) {
-      self->toc.push_back({std::move(self->currentLabel), std::move(href), std::move(anchor), self->currentDepth});
+        self->cache->createTocEntry(self->currentLabel, href, anchor, self->currentDepth);
+      }
 
       // Clear them so we don't re-add them if there are weird XML structures
       self->currentLabel.clear();

lib/Epub/Epub/parsers/TocNcxParser.h

@@ -1,11 +1,10 @@
 #pragma once
 #include <Print.h>
+#include <expat.h>
 
 #include <string>
-#include <vector>
 
-#include "Epub/EpubTocEntry.h"
+class BookMetadataCache;
-#include "expat.h"
 
 class TocNcxParser final : public Print {
   enum ParserState { START, IN_NCX, IN_NAV_MAP, IN_NAV_POINT, IN_NAV_LABEL, IN_NAV_LABEL_TEXT, IN_CONTENT };
@@ -14,6 +13,7 @@ class TocNcxParser final : public Print {
   size_t remainingSize;
   XML_Parser parser = nullptr;
   ParserState state = START;
+  BookMetadataCache* cache;
 
   std::string currentLabel;
   std::string currentSrc;
@@ -24,10 +24,8 @@ class TocNcxParser final : public Print {
   static void endElement(void* userData, const XML_Char* name);
 
  public:
-  std::vector<EpubTocEntry> toc;
+  explicit TocNcxParser(const std::string& baseContentPath, const size_t xmlSize, BookMetadataCache* cache)
-
+      : baseContentPath(baseContentPath), remainingSize(xmlSize), cache(cache) {}
-  explicit TocNcxParser(const std::string& baseContentPath, const size_t xmlSize)
-      : baseContentPath(baseContentPath), remainingSize(xmlSize) {}
   ~TocNcxParser() override;
 
   bool setup();

lib/FsHelpers/FsHelpers.cpp

@@ -0,0 +1,112 @@
+#include "FsHelpers.h"
+
+#include <SD.h>
+
+#include <vector>
+
+bool FsHelpers::openFileForRead(const char* moduleName, const char* path, File& file) {
+  if (!SD.exists(path)) {
+    return false;
+  }
+
+  file = SD.open(path, FILE_READ);
+  if (!file) {
+    Serial.printf("[%lu] [%s] Failed to open file for reading: %s\n", millis(), moduleName, path);
+    return false;
+  }
+  return true;
+}
+
+bool FsHelpers::openFileForRead(const char* moduleName, const std::string& path, File& file) {
+  return openFileForRead(moduleName, path.c_str(), file);
+}
+
+bool FsHelpers::openFileForRead(const char* moduleName, const String& path, File& file) {
+  return openFileForRead(moduleName, path.c_str(), file);
+}
+
+bool FsHelpers::openFileForWrite(const char* moduleName, const char* path, File& file) {
+  file = SD.open(path, FILE_WRITE, true);
+  if (!file) {
+    Serial.printf("[%lu] [%s] Failed to open file for writing: %s\n", millis(), moduleName, path);
+    return false;
+  }
+  return true;
+}
+
+bool FsHelpers::openFileForWrite(const char* moduleName, const std::string& path, File& file) {
+  return openFileForWrite(moduleName, path.c_str(), file);
+}
+
+bool FsHelpers::openFileForWrite(const char* moduleName, const String& path, File& file) {
+  return openFileForWrite(moduleName, path.c_str(), file);
+}
+
+bool FsHelpers::removeDir(const char* path) {
+  // 1. Open the directory
+  File dir = SD.open(path);
+  if (!dir) {
+    return false;
+  }
+  if (!dir.isDirectory()) {
+    return false;
+  }
+
+  File file = dir.openNextFile();
+  while (file) {
+    String filePath = path;
+    if (!filePath.endsWith("/")) {
+      filePath += "/";
+    }
+    filePath += file.name();
+
+    if (file.isDirectory()) {
+      if (!removeDir(filePath.c_str())) {
+        return false;
+      }
+    } else {
+      if (!SD.remove(filePath.c_str())) {
+        return false;
+      }
+    }
+    file = dir.openNextFile();
+  }
+
+  return SD.rmdir(path);
+}
+
+std::string FsHelpers::normalisePath(const std::string& path) {
+  std::vector<std::string> components;
+  std::string component;
+
+  for (const auto c : path) {
+    if (c == '/') {
+      if (!component.empty()) {
+        if (component == "..") {
+          if (!components.empty()) {
+            components.pop_back();
+          }
+        } else {
+          components.push_back(component);
+        }
+        component.clear();
+      }
+    } else {
+      component += c;
+    }
+  }
+
+  if (!component.empty()) {
+    components.push_back(component);
+  }
+
+  std::string result;
+  for (const auto& c : components) {
+    if (!result.empty()) {
+      result += "/";
+    }
+    result += c;
+  }
+
+  return result;
+}

lib/FsHelpers/FsHelpers.h

@@ -0,0 +1,14 @@
+#pragma once
+#include <FS.h>
+
+class FsHelpers {
+ public:
+  static bool openFileForRead(const char* moduleName, const char* path, File& file);
+  static bool openFileForRead(const char* moduleName, const std::string& path, File& file);
+  static bool openFileForRead(const char* moduleName, const String& path, File& file);
+  static bool openFileForWrite(const char* moduleName, const char* path, File& file);
+  static bool openFileForWrite(const char* moduleName, const std::string& path, File& file);
+  static bool openFileForWrite(const char* moduleName, const String& path, File& file);
+  static bool removeDir(const char* path);
+  static std::string normalisePath(const std::string& path);
+};

lib/GfxRenderer/Bitmap.cpp

@@ -3,6 +3,126 @@
 #include <cstdlib>
 #include <cstring>
 
+// ============================================================================
+// IMAGE PROCESSING OPTIONS - Toggle these to test different configurations
+// ============================================================================
+// Note: For cover images, dithering is done in JpegToBmpConverter.cpp
+// This file handles BMP reading - use simple quantization to avoid double-dithering
+constexpr bool USE_FLOYD_STEINBERG = false;  // Disabled - dithering done at JPEG conversion
+constexpr bool USE_NOISE_DITHERING = false;  // Hash-based noise dithering
+// Brightness adjustments:
+constexpr bool USE_BRIGHTNESS = false;    // true: apply brightness/gamma adjustments
+constexpr int BRIGHTNESS_BOOST = 20;      // Brightness offset (0-50), only if USE_BRIGHTNESS=true
+constexpr bool GAMMA_CORRECTION = false;  // Gamma curve, only if USE_BRIGHTNESS=true
+// ============================================================================
+
+// Integer approximation of gamma correction (brightens midtones)
+static inline int applyGamma(int gray) {
+  if (!GAMMA_CORRECTION) return gray;
+  const int product = gray * 255;
+  int x = gray;
+  if (x > 0) {
+    x = (x + product / x) >> 1;
+    x = (x + product / x) >> 1;
+  }
+  return x > 255 ? 255 : x;
+}
+
+// Simple quantization without dithering - just divide into 4 levels
+static inline uint8_t quantizeSimple(int gray) {
+  if (USE_BRIGHTNESS) {
+    gray += BRIGHTNESS_BOOST;
+    if (gray > 255) gray = 255;
+    gray = applyGamma(gray);
+  }
+  return static_cast<uint8_t>(gray >> 6);
+}
+
+// Hash-based noise dithering - survives downsampling without moiré artifacts
+static inline uint8_t quantizeNoise(int gray, int x, int y) {
+  if (USE_BRIGHTNESS) {
+    gray += BRIGHTNESS_BOOST;
+    if (gray > 255) gray = 255;
+    gray = applyGamma(gray);
+  }
+
+  uint32_t hash = static_cast<uint32_t>(x) * 374761393u + static_cast<uint32_t>(y) * 668265263u;
+  hash = (hash ^ (hash >> 13)) * 1274126177u;
+  const int threshold = static_cast<int>(hash >> 24);
+
+  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;
+  }
+}
+
+// Main quantization function
+static inline uint8_t quantize(int gray, int x, int y) {
+  if (USE_NOISE_DITHERING) {
+    return quantizeNoise(gray, x, y);
+  } else {
+    return quantizeSimple(gray);
+  }
+}
+
+// Floyd-Steinberg quantization with error diffusion and serpentine scanning
+// Returns 2-bit value (0-3) and updates error buffers
+static inline uint8_t quantizeFloydSteinberg(int gray, int x, int width, int16_t* errorCurRow, int16_t* errorNextRow,
+                                             bool reverseDir) {
+  // Add accumulated error to this pixel
+  int adjusted = gray + errorCurRow[x + 1];
+
+  // Clamp to valid range
+  if (adjusted < 0) adjusted = 0;
+  if (adjusted > 255) adjusted = 255;
+
+  // Quantize to 4 levels (0, 85, 170, 255)
+  uint8_t quantized;
+  int quantizedValue;
+  if (adjusted < 43) {
+    quantized = 0;
+    quantizedValue = 0;
+  } else if (adjusted < 128) {
+    quantized = 1;
+    quantizedValue = 85;
+  } else if (adjusted < 213) {
+    quantized = 2;
+    quantizedValue = 170;
+  } else {
+    quantized = 3;
+    quantizedValue = 255;
+  }
+
+  // Calculate error
+  int error = adjusted - quantizedValue;
+
+  // Distribute error to neighbors (serpentine: direction-aware)
+  if (!reverseDir) {
+    // Left to right
+    errorCurRow[x + 2] += (error * 7) >> 4;   // Right: 7/16
+    errorNextRow[x] += (error * 3) >> 4;      // Bottom-left: 3/16
+    errorNextRow[x + 1] += (error * 5) >> 4;  // Bottom: 5/16
+    errorNextRow[x + 2] += (error) >> 4;      // Bottom-right: 1/16
+  } else {
+    // Right to left (mirrored)
+    errorCurRow[x] += (error * 7) >> 4;       // Left: 7/16
+    errorNextRow[x + 2] += (error * 3) >> 4;  // Bottom-right: 3/16
+    errorNextRow[x + 1] += (error * 5) >> 4;  // Bottom: 5/16
+    errorNextRow[x] += (error) >> 4;          // Bottom-left: 1/16
+  }
+
+  return quantized;
+}
+
+Bitmap::~Bitmap() {
+  delete[] errorCurRow;
+  delete[] errorNextRow;
+}
+
 uint16_t Bitmap::readLE16(File& f) {
   const int c0 = f.read();
   const int c1 = f.read();
@@ -46,6 +166,8 @@ const char* Bitmap::errorToString(BmpReaderError err) {
       return "UnsupportedCompression (expected BI_RGB or BI_BITFIELDS for 32bpp)";
     case BmpReaderError::BadDimensions:
       return "BadDimensions";
+    case BmpReaderError::ImageTooLarge:
+      return "ImageTooLarge (max 2048x3072)";
     case BmpReaderError::PaletteTooLarge:
       return "PaletteTooLarge";
 
@@ -99,6 +221,13 @@ BmpReaderError Bitmap::parseHeaders() {
 
   if (width <= 0 || height <= 0) return BmpReaderError::BadDimensions;
 
+  // Safety limits to prevent memory issues on ESP32
+  constexpr int MAX_IMAGE_WIDTH = 2048;
+  constexpr int MAX_IMAGE_HEIGHT = 3072;
+  if (width > MAX_IMAGE_WIDTH || height > MAX_IMAGE_HEIGHT) {
+    return BmpReaderError::ImageTooLarge;
+  }
+
   // Pre-calculate Row Bytes to avoid doing this every row
   rowBytes = (width * bpp + 31) / 32 * 4;
 
@@ -115,21 +244,56 @@ BmpReaderError Bitmap::parseHeaders() {
     return BmpReaderError::SeekPixelDataFailed;
   }
 
+  // Allocate Floyd-Steinberg error buffers if enabled
+  if (USE_FLOYD_STEINBERG) {
+    delete[] errorCurRow;
+    delete[] errorNextRow;
+    errorCurRow = new int16_t[width + 2]();  // +2 for boundary handling
+    errorNextRow = new int16_t[width + 2]();
+    lastRowY = -1;
+  }
+
   return BmpReaderError::Ok;
 }
 
 // packed 2bpp output, 0 = black, 1 = dark gray, 2 = light gray, 3 = white
-BmpReaderError Bitmap::readRow(uint8_t* data, uint8_t* rowBuffer) const {
+BmpReaderError Bitmap::readRow(uint8_t* data, uint8_t* rowBuffer, int rowY) const {
   // Note: rowBuffer should be pre-allocated by the caller to size 'rowBytes'
   if (file.read(rowBuffer, rowBytes) != rowBytes) return BmpReaderError::ShortReadRow;
 
+  // Handle Floyd-Steinberg error buffer progression
+  const bool useFS = USE_FLOYD_STEINBERG && errorCurRow && errorNextRow;
+  if (useFS) {
+    // Check if we need to advance to next row (or reset if jumping)
+    if (rowY != lastRowY + 1 && rowY != 0) {
+      // Non-sequential row access - reset error buffers
+      memset(errorCurRow, 0, (width + 2) * sizeof(int16_t));
+      memset(errorNextRow, 0, (width + 2) * sizeof(int16_t));
+    } else if (rowY > 0) {
+      // Sequential access - swap buffers
+      int16_t* temp = errorCurRow;
+      errorCurRow = errorNextRow;
+      errorNextRow = temp;
+      memset(errorNextRow, 0, (width + 2) * sizeof(int16_t));
+    }
+    lastRowY = rowY;
+  }
+
   uint8_t* outPtr = data;
   uint8_t currentOutByte = 0;
   int bitShift = 6;
+  int currentX = 0;
 
   // Helper lambda to pack 2bpp color into the output stream
   auto packPixel = [&](const uint8_t lum) {
-    uint8_t color = (lum >> 6);  // Simple 2-bit reduction: 0-255 -> 0-3
+    uint8_t color;
+    if (useFS) {
+      // Floyd-Steinberg error diffusion
+      color = quantizeFloydSteinberg(lum, currentX, width, errorCurRow, errorNextRow, false);
+    } else {
+      // Simple quantization or noise dithering
+      color = quantize(lum, currentX, rowY);
+    }
     currentOutByte |= (color << bitShift);
     if (bitShift == 0) {
       *outPtr++ = currentOutByte;
@@ -138,6 +302,7 @@ BmpReaderError Bitmap::readRow(uint8_t* data, uint8_t* rowBuffer) const {
     } else {
       bitShift -= 2;
     }
+    currentX++;
   };
 
   uint8_t lum;
@@ -196,5 +361,12 @@ BmpReaderError Bitmap::rewindToData() const {
     return BmpReaderError::SeekPixelDataFailed;
   }
 
+  // Reset Floyd-Steinberg error buffers when rewinding
+  if (USE_FLOYD_STEINBERG && errorCurRow && errorNextRow) {
+    memset(errorCurRow, 0, (width + 2) * sizeof(int16_t));
+    memset(errorNextRow, 0, (width + 2) * sizeof(int16_t));
+    lastRowY = -1;
+  }
+
   return BmpReaderError::Ok;
 }

lib/GfxRenderer/Bitmap.h

@@ -15,6 +15,7 @@ enum class BmpReaderError : uint8_t {
   UnsupportedCompression,
 
   BadDimensions,
+  ImageTooLarge,
   PaletteTooLarge,
 
   SeekPixelDataFailed,
@@ -28,8 +29,9 @@ class Bitmap {
   static const char* errorToString(BmpReaderError err);
 
   explicit Bitmap(File& file) : file(file) {}
+  ~Bitmap();
   BmpReaderError parseHeaders();
-  BmpReaderError readRow(uint8_t* data, uint8_t* rowBuffer) const;
+  BmpReaderError readRow(uint8_t* data, uint8_t* rowBuffer, int rowY) const;
   BmpReaderError rewindToData() const;
   int getWidth() const { return width; }
   int getHeight() const { return height; }
@@ -49,4 +51,9 @@ class Bitmap {
   uint16_t bpp = 0;
   int rowBytes = 0;
   uint8_t paletteLum[256] = {};
+
+  // Floyd-Steinberg dithering state (mutable for const methods)
+  mutable int16_t* errorCurRow = nullptr;
+  mutable int16_t* errorNextRow = nullptr;
+  mutable int lastRowY = -1;  // Track row progression for error propagation
 };

lib/GfxRenderer/GfxRenderer.cpp

@@ -4,6 +4,37 @@
 
 void GfxRenderer::insertFont(const int fontId, EpdFontFamily font) { fontMap.insert({fontId, font}); }
 
+void GfxRenderer::rotateCoordinates(const int x, const int y, int* rotatedX, int* rotatedY) const {
+  switch (orientation) {
+    case Portrait: {
+      // Logical portrait (480x800) → panel (800x480)
+      // Rotation: 90 degrees clockwise
+      *rotatedX = y;
+      *rotatedY = EInkDisplay::DISPLAY_HEIGHT - 1 - x;
+      break;
+    }
+    case LandscapeClockwise: {
+      // Logical landscape (800x480) rotated 180 degrees (swap top/bottom and left/right)
+      *rotatedX = EInkDisplay::DISPLAY_WIDTH - 1 - x;
+      *rotatedY = EInkDisplay::DISPLAY_HEIGHT - 1 - y;
+      break;
+    }
+    case PortraitInverted: {
+      // Logical portrait (480x800) → panel (800x480)
+      // Rotation: 90 degrees counter-clockwise
+      *rotatedX = EInkDisplay::DISPLAY_WIDTH - 1 - y;
+      *rotatedY = x;
+      break;
+    }
+    case LandscapeCounterClockwise: {
+      // Logical landscape (800x480) aligned with panel orientation
+      *rotatedX = x;
+      *rotatedY = y;
+      break;
+    }
+  }
+}
+
 void GfxRenderer::drawPixel(const int x, const int y, const bool state) const {
   uint8_t* frameBuffer = einkDisplay.getFrameBuffer();
 
@@ -13,15 +44,14 @@ void GfxRenderer::drawPixel(const int x, const int y, const bool state) const {
     return;
   }
 
-  // Rotate coordinates: portrait (480x800) -> landscape (800x480)
+  int rotatedX = 0;
-  // Rotation: 90 degrees clockwise
+  int rotatedY = 0;
-  const int rotatedX = y;
+  rotateCoordinates(x, y, &rotatedX, &rotatedY);
-  const int rotatedY = EInkDisplay::DISPLAY_HEIGHT - 1 - x;
 
-  // Bounds checking (portrait: 480x800)
+  // Bounds checking against physical panel dimensions
   if (rotatedX < 0 || rotatedX >= EInkDisplay::DISPLAY_WIDTH || rotatedY < 0 ||
       rotatedY >= EInkDisplay::DISPLAY_HEIGHT) {
-    Serial.printf("[%lu] [GFX] !! Outside range (%d, %d)\n", millis(), x, y);
+    Serial.printf("[%lu] [GFX] !! Outside range (%d, %d) -> (%d, %d)\n", millis(), x, y, rotatedX, rotatedY);
     return;
   }
 
@@ -55,7 +85,7 @@ void GfxRenderer::drawCenteredText(const int fontId, const int y, const char* te
 
 void GfxRenderer::drawText(const int fontId, const int x, const int y, const char* text, const bool black,
                            const EpdFontStyle style) const {
-  const int yPos = y + getLineHeight(fontId);
+  const int yPos = y + getFontAscenderSize(fontId);
   int xpos = x;
 
   // cannot draw a NULL / empty string
@@ -115,8 +145,11 @@ void GfxRenderer::fillRect(const int x, const int y, const int width, const int
 }
 
 void GfxRenderer::drawImage(const uint8_t bitmap[], const int x, const int y, const int width, const int height) const {
-  // Flip X and Y for portrait mode
+  // TODO: Rotate bits
-  einkDisplay.drawImage(bitmap, y, x, height, width);
+  int rotatedX = 0;
+  int rotatedY = 0;
+  rotateCoordinates(x, y, &rotatedX, &rotatedY);
+  einkDisplay.drawImage(bitmap, rotatedX, rotatedY, width, height);
 }
 
 void GfxRenderer::drawBitmap(const Bitmap& bitmap, const int x, const int y, const int maxWidth,
@@ -132,7 +165,9 @@ void GfxRenderer::drawBitmap(const Bitmap& bitmap, const int x, const int y, con
     isScaled = true;
   }
 
-  const uint8_t outputRowSize = (bitmap.getWidth() + 3) / 4;
+  // 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
+  const int outputRowSize = (bitmap.getWidth() + 3) / 4;
   auto* outputRow = static_cast<uint8_t*>(malloc(outputRowSize));
   auto* rowBytes = static_cast<uint8_t*>(malloc(bitmap.getRowBytes()));
 
@@ -154,7 +189,7 @@ void GfxRenderer::drawBitmap(const Bitmap& bitmap, const int x, const int y, con
       break;
     }
 
-    if (bitmap.readRow(outputRow, rowBytes) != BmpReaderError::Ok) {
+    if (bitmap.readRow(outputRow, rowBytes, bmpY) != BmpReaderError::Ok) {
       Serial.printf("[%lu] [GFX] Failed to read row %d from bitmap\n", millis(), bmpY);
       free(outputRow);
       free(rowBytes);
@@ -203,23 +238,34 @@ void GfxRenderer::displayBuffer(const EInkDisplay::RefreshMode refreshMode) cons
   einkDisplay.displayBuffer(refreshMode);
 }
 
-void GfxRenderer::displayWindow(const int x, const int y, const int width, const int height) const {
+// Note: Internal driver treats screen in command orientation; this library exposes a logical orientation
-  // Rotate coordinates from portrait (480x800) to landscape (800x480)
+int GfxRenderer::getScreenWidth() const {
-  // Rotation: 90 degrees clockwise
+  switch (orientation) {
-  // Portrait coordinates: (x, y) with dimensions (width, height)
+    case Portrait:
-  // Landscape coordinates: (rotatedX, rotatedY) with dimensions (rotatedWidth, rotatedHeight)
+    case PortraitInverted:
-
+      // 480px wide in portrait logical coordinates
-  const int rotatedX = y;
+      return EInkDisplay::DISPLAY_HEIGHT;
-  const int rotatedY = EInkDisplay::DISPLAY_HEIGHT - 1 - x - width + 1;
+    case LandscapeClockwise:
-  const int rotatedWidth = height;
+    case LandscapeCounterClockwise:
-  const int rotatedHeight = width;
+      // 800px wide in landscape logical coordinates
-
+      return EInkDisplay::DISPLAY_WIDTH;
-  einkDisplay.displayWindow(rotatedX, rotatedY, rotatedWidth, rotatedHeight);
+  }
+  return EInkDisplay::DISPLAY_HEIGHT;
 }
 
-// Note: Internal driver treats screen in command orientation, this library treats in portrait orientation
+int GfxRenderer::getScreenHeight() const {
-int GfxRenderer::getScreenWidth() { return EInkDisplay::DISPLAY_HEIGHT; }
+  switch (orientation) {
-int GfxRenderer::getScreenHeight() { return EInkDisplay::DISPLAY_WIDTH; }
+    case Portrait:
+    case PortraitInverted:
+      // 800px tall in portrait logical coordinates
+      return EInkDisplay::DISPLAY_WIDTH;
+    case LandscapeClockwise:
+    case LandscapeCounterClockwise:
+      // 480px tall in landscape logical coordinates
+      return EInkDisplay::DISPLAY_HEIGHT;
+  }
+  return EInkDisplay::DISPLAY_WIDTH;
+}
 
 int GfxRenderer::getSpaceWidth(const int fontId) const {
   if (fontMap.count(fontId) == 0) {
@@ -230,6 +276,15 @@ int GfxRenderer::getSpaceWidth(const int fontId) const {
   return fontMap.at(fontId).getGlyph(' ', REGULAR)->advanceX;
 }
 
+int GfxRenderer::getFontAscenderSize(const int fontId) const {
+  if (fontMap.count(fontId) == 0) {
+    Serial.printf("[%lu] [GFX] Font %d not found\n", millis(), fontId);
+    return 0;
+  }
+
+  return fontMap.at(fontId).getData(REGULAR)->ascender;
+}
+
 int GfxRenderer::getLineHeight(const int fontId) const {
   if (fontMap.count(fontId) == 0) {
     Serial.printf("[%lu] [GFX] Font %d not found\n", millis(), fontId);
@@ -239,6 +294,28 @@ int GfxRenderer::getLineHeight(const int fontId) const {
   return fontMap.at(fontId).getData(REGULAR)->advanceY;
 }
 
+void GfxRenderer::drawButtonHints(const int fontId, const char* btn1, const char* btn2, const char* btn3,
+                                  const char* btn4) const {
+  const int pageHeight = getScreenHeight();
+  constexpr int buttonWidth = 106;
+  constexpr int buttonHeight = 40;
+  constexpr int buttonY = 40;     // Distance from bottom
+  constexpr int textYOffset = 7;  // Distance from top of button to text baseline
+  constexpr int buttonPositions[] = {25, 130, 245, 350};
+  const char* labels[] = {btn1, btn2, btn3, btn4};
+
+  for (int i = 0; i < 4; i++) {
+    // Only draw if the label is non-empty
+    if (labels[i] != nullptr && labels[i][0] != '\0') {
+      const int x = buttonPositions[i];
+      drawRect(x, pageHeight - buttonY, buttonWidth, buttonHeight);
+      const int textWidth = getTextWidth(fontId, labels[i]);
+      const int textX = x + (buttonWidth - 1 - textWidth) / 2;
+      drawText(fontId, textX, pageHeight - buttonY + textYOffset, labels[i]);
+    }
+  }
+}
+
 uint8_t* GfxRenderer::getFrameBuffer() const { return einkDisplay.getFrameBuffer(); }
 
 size_t GfxRenderer::getBufferSize() { return EInkDisplay::BUFFER_SIZE; }
@@ -264,12 +341,13 @@ void GfxRenderer::freeBwBufferChunks() {
  * This should be called before grayscale buffers are populated.
  * A `restoreBwBuffer` call should always follow the grayscale render if this method was called.
  * Uses chunked allocation to avoid needing 48KB of contiguous memory.
+ * Returns true if buffer was stored successfully, false if allocation failed.
  */
-void GfxRenderer::storeBwBuffer() {
+bool GfxRenderer::storeBwBuffer() {
   const uint8_t* frameBuffer = einkDisplay.getFrameBuffer();
   if (!frameBuffer) {
     Serial.printf("[%lu] [GFX] !! No framebuffer in storeBwBuffer\n", millis());
-    return;
+    return false;
   }
 
   // Allocate and copy each chunk
@@ -290,7 +368,7 @@ void GfxRenderer::storeBwBuffer() {
                     BW_BUFFER_CHUNK_SIZE);
       // Free previously allocated chunks
       freeBwBufferChunks();
-      return;
+      return false;
     }
 
     memcpy(bwBufferChunks[i], frameBuffer + offset, BW_BUFFER_CHUNK_SIZE);
@@ -298,6 +376,7 @@ void GfxRenderer::storeBwBuffer() {
 
   Serial.printf("[%lu] [GFX] Stored BW buffer in %zu chunks (%zu bytes each)\n", millis(), BW_BUFFER_NUM_CHUNKS,
                 BW_BUFFER_CHUNK_SIZE);
+  return true;
 }
 
 /**
@@ -345,6 +424,17 @@ void GfxRenderer::restoreBwBuffer() {
   Serial.printf("[%lu] [GFX] Restored and freed BW buffer chunks\n", millis());
 }
 
+/**
+ * Cleanup grayscale buffers using the current frame buffer.
+ * Use this when BW buffer was re-rendered instead of stored/restored.
+ */
+void GfxRenderer::cleanupGrayscaleWithFrameBuffer() const {
+  uint8_t* frameBuffer = einkDisplay.getFrameBuffer();
+  if (frameBuffer) {
+    einkDisplay.cleanupGrayscaleBuffers(frameBuffer);
+  }
+}
+
 void GfxRenderer::renderChar(const EpdFontFamily& fontFamily, const uint32_t cp, int* x, const int* y,
                              const bool pixelState, const EpdFontStyle style) const {
   const EpdGlyph* glyph = fontFamily.getGlyph(cp, style);
@@ -408,3 +498,32 @@ void GfxRenderer::renderChar(const EpdFontFamily& fontFamily, const uint32_t cp,
 
   *x += glyph->advanceX;
 }
+
+void GfxRenderer::getOrientedViewableTRBL(int* outTop, int* outRight, int* outBottom, int* outLeft) const {
+  switch (orientation) {
+    case Portrait:
+      *outTop = VIEWABLE_MARGIN_TOP;
+      *outRight = VIEWABLE_MARGIN_RIGHT;
+      *outBottom = VIEWABLE_MARGIN_BOTTOM;
+      *outLeft = VIEWABLE_MARGIN_LEFT;
+      break;
+    case LandscapeClockwise:
+      *outTop = VIEWABLE_MARGIN_LEFT;
+      *outRight = VIEWABLE_MARGIN_TOP;
+      *outBottom = VIEWABLE_MARGIN_RIGHT;
+      *outLeft = VIEWABLE_MARGIN_BOTTOM;
+      break;
+    case PortraitInverted:
+      *outTop = VIEWABLE_MARGIN_BOTTOM;
+      *outRight = VIEWABLE_MARGIN_LEFT;
+      *outBottom = VIEWABLE_MARGIN_TOP;
+      *outLeft = VIEWABLE_MARGIN_RIGHT;
+      break;
+    case LandscapeCounterClockwise:
+      *outTop = VIEWABLE_MARGIN_RIGHT;
+      *outRight = VIEWABLE_MARGIN_BOTTOM;
+      *outBottom = VIEWABLE_MARGIN_LEFT;
+      *outLeft = VIEWABLE_MARGIN_TOP;
+      break;
+  }
+}

lib/GfxRenderer/GfxRenderer.h

@@ -12,6 +12,14 @@ class GfxRenderer {
  public:
   enum RenderMode { BW, GRAYSCALE_LSB, GRAYSCALE_MSB };
 
+  // Logical screen orientation from the perspective of callers
+  enum Orientation {
+    Portrait,                  // 480x800 logical coordinates (current default)
+    LandscapeClockwise,        // 800x480 logical coordinates, rotated 180° (swap top/bottom)
+    PortraitInverted,          // 480x800 logical coordinates, inverted
+    LandscapeCounterClockwise  // 800x480 logical coordinates, native panel orientation
+  };
+
  private:
   static constexpr size_t BW_BUFFER_CHUNK_SIZE = 8000;  // 8KB chunks to allow for non-contiguous memory
   static constexpr size_t BW_BUFFER_NUM_CHUNKS = EInkDisplay::BUFFER_SIZE / BW_BUFFER_CHUNK_SIZE;
@@ -20,24 +28,35 @@ class GfxRenderer {
 
   EInkDisplay& einkDisplay;
   RenderMode renderMode;
+  Orientation orientation;
   uint8_t* bwBufferChunks[BW_BUFFER_NUM_CHUNKS] = {nullptr};
   std::map<int, EpdFontFamily> fontMap;
   void renderChar(const EpdFontFamily& fontFamily, uint32_t cp, int* x, const int* y, bool pixelState,
                   EpdFontStyle style) const;
   void freeBwBufferChunks();
+  void rotateCoordinates(int x, int y, int* rotatedX, int* rotatedY) const;
 
  public:
-  explicit GfxRenderer(EInkDisplay& einkDisplay) : einkDisplay(einkDisplay), renderMode(BW) {}
+  explicit GfxRenderer(EInkDisplay& einkDisplay) : einkDisplay(einkDisplay), renderMode(BW), orientation(Portrait) {}
   ~GfxRenderer() = default;
 
+  static constexpr int VIEWABLE_MARGIN_TOP = 9;
+  static constexpr int VIEWABLE_MARGIN_RIGHT = 3;
+  static constexpr int VIEWABLE_MARGIN_BOTTOM = 3;
+  static constexpr int VIEWABLE_MARGIN_LEFT = 3;
+
   // Setup
   void insertFont(int fontId, EpdFontFamily font);
 
+  // Orientation control (affects logical width/height and coordinate transforms)
+  void setOrientation(const Orientation o) { orientation = o; }
+  Orientation getOrientation() const { return orientation; }
+
   // Screen ops
-  static int getScreenWidth();
+  int getScreenWidth() const;
-  static int getScreenHeight();
+  int getScreenHeight() const;
   void displayBuffer(EInkDisplay::RefreshMode refreshMode = EInkDisplay::FAST_REFRESH) const;
-  // EXPERIMENTAL: Windowed update - display only a rectangular region (portrait coordinates)
+  // EXPERIMENTAL: Windowed update - display only a rectangular region
   void displayWindow(int x, int y, int width, int height) const;
   void invertScreen() const;
   void clearScreen(uint8_t color = 0xFF) const;
@@ -55,18 +74,24 @@ class GfxRenderer {
   void drawCenteredText(int fontId, int y, const char* text, bool black = true, EpdFontStyle style = REGULAR) const;
   void drawText(int fontId, int x, int y, const char* text, bool black = true, EpdFontStyle style = REGULAR) const;
   int getSpaceWidth(int fontId) const;
+  int getFontAscenderSize(int fontId) const;
   int getLineHeight(int fontId) const;
 
+  // UI Components
+  void drawButtonHints(int fontId, const char* btn1, const char* btn2, const char* btn3, const char* btn4) const;
+
   // Grayscale functions
   void setRenderMode(const RenderMode mode) { this->renderMode = mode; }
   void copyGrayscaleLsbBuffers() const;
   void copyGrayscaleMsbBuffers() const;
   void displayGrayBuffer() const;
-  void storeBwBuffer();
+  bool storeBwBuffer();  // Returns true if buffer was stored successfully
   void restoreBwBuffer();
+  void cleanupGrayscaleWithFrameBuffer() const;
 
   // Low level functions
   uint8_t* getFrameBuffer() const;
   static size_t getBufferSize();
   void grayscaleRevert() const;
+  void getOrientedViewableTRBL(int* outTop, int* outRight, int* outBottom, int* outLeft) const;
 };

lib/JpegToBmpConverter/JpegToBmpConverter.cpp

@@ -13,24 +13,296 @@ struct JpegReadContext {
   size_t bufferFilled;
 };
 
-// Helper function: Convert 8-bit grayscale to 2-bit (0-3)
+// ============================================================================
-uint8_t JpegToBmpConverter::grayscaleTo2Bit(const uint8_t grayscale) {
+// IMAGE PROCESSING OPTIONS - Toggle these to test different configurations
-  // Simple threshold mapping:
+// ============================================================================
-  // 0-63 -> 0 (black)
+constexpr bool USE_8BIT_OUTPUT = false;  // true: 8-bit grayscale (no quantization), false: 2-bit (4 levels)
-  // 64-127 -> 1 (dark gray)
+// Dithering method selection (only one should be true, or all false for simple quantization):
-  // 128-191 -> 2 (light gray)
+constexpr bool USE_ATKINSON = true;          // Atkinson dithering (cleaner than F-S, less error diffusion)
-  // 192-255 -> 3 (white)
+constexpr bool USE_FLOYD_STEINBERG = false;  // Floyd-Steinberg error diffusion (can cause "worm" artifacts)
-  return grayscale >> 6;
+constexpr bool USE_NOISE_DITHERING = false;  // Hash-based noise dithering (good for downsampling)
+// Brightness/Contrast adjustments:
+constexpr bool USE_BRIGHTNESS = true;     // true: apply brightness/gamma adjustments
+constexpr int BRIGHTNESS_BOOST = 10;      // Brightness offset (0-50)
+constexpr bool GAMMA_CORRECTION = true;   // Gamma curve (brightens midtones)
+constexpr float CONTRAST_FACTOR = 1.15f;  // Contrast multiplier (1.0 = no change, >1 = more contrast)
+// Pre-resize to target display size (CRITICAL: avoids dithering artifacts from post-downsampling)
+constexpr bool USE_PRESCALE = true;     // true: scale image to target size before dithering
+constexpr int TARGET_MAX_WIDTH = 480;   // Max width for cover images (portrait display width)
+constexpr int TARGET_MAX_HEIGHT = 800;  // Max height for cover images (portrait display height)
+// ============================================================================
+
+// Integer approximation of gamma correction (brightens midtones)
+// Uses a simple curve: out = 255 * sqrt(in/255) ≈ sqrt(in * 255)
+static inline int applyGamma(int gray) {
+  if (!GAMMA_CORRECTION) return gray;
+  // Fast integer square root approximation for gamma ~0.5 (brightening)
+  // This brightens dark/mid tones while preserving highlights
+  const int product = gray * 255;
+  // Newton-Raphson integer sqrt (2 iterations for good accuracy)
+  int x = gray;
+  if (x > 0) {
+    x = (x + product / x) >> 1;
+    x = (x + product / x) >> 1;
+  }
+  return x > 255 ? 255 : x;
 }
 
+// Apply contrast adjustment around midpoint (128)
+// factor > 1.0 increases contrast, < 1.0 decreases
+static inline int applyContrast(int gray) {
+  // Integer-based contrast: (gray - 128) * factor + 128
+  // Using fixed-point: factor 1.15 ≈ 115/100
+  constexpr int factorNum = static_cast<int>(CONTRAST_FACTOR * 100);
+  int adjusted = ((gray - 128) * factorNum) / 100 + 128;
+  if (adjusted < 0) adjusted = 0;
+  if (adjusted > 255) adjusted = 255;
+  return adjusted;
+}
+
+// Combined brightness/contrast/gamma adjustment
+static inline int adjustPixel(int gray) {
+  if (!USE_BRIGHTNESS) return gray;
+
+  // Order: contrast first, then brightness, then gamma
+  gray = applyContrast(gray);
+  gray += BRIGHTNESS_BOOST;
+  if (gray > 255) gray = 255;
+  if (gray < 0) gray = 0;
+  gray = applyGamma(gray);
+
+  return gray;
+}
+
+// Simple quantization without dithering - just divide into 4 levels
+static inline uint8_t quantizeSimple(int gray) {
+  gray = adjustPixel(gray);
+  // Simple 2-bit quantization: 0-63=0, 64-127=1, 128-191=2, 192-255=3
+  return static_cast<uint8_t>(gray >> 6);
+}
+
+// Hash-based noise dithering - survives downsampling without moiré artifacts
+// Uses integer hash to generate pseudo-random threshold per pixel
+static inline uint8_t quantizeNoise(int gray, int x, int y) {
+  gray = adjustPixel(gray);
+
+  // Generate noise threshold using integer hash (no regular pattern to alias)
+  uint32_t hash = static_cast<uint32_t>(x) * 374761393u + static_cast<uint32_t>(y) * 668265263u;
+  hash = (hash ^ (hash >> 13)) * 1274126177u;
+  const int threshold = static_cast<int>(hash >> 24);  // 0-255
+
+  // Map gray (0-255) to 4 levels with dithering
+  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;
+  }
+}
+
+// Main quantization function - selects between methods based on config
+static inline uint8_t quantize(int gray, int x, int y) {
+  if (USE_NOISE_DITHERING) {
+    return quantizeNoise(gray, x, y);
+  } else {
+    return quantizeSimple(gray);
+  }
+}
+
+// Atkinson dithering - distributes only 6/8 (75%) of error for cleaner results
+// Error distribution pattern:
+//     X  1/8 1/8
+// 1/8 1/8 1/8
+//     1/8
+// Less error buildup = fewer artifacts than Floyd-Steinberg
+class AtkinsonDitherer {
+ public:
+  AtkinsonDitherer(int width) : width(width) {
+    errorRow0 = new int16_t[width + 4]();  // Current row
+    errorRow1 = new int16_t[width + 4]();  // Next row
+    errorRow2 = new int16_t[width + 4]();  // Row after next
+  }
+
+  ~AtkinsonDitherer() {
+    delete[] errorRow0;
+    delete[] errorRow1;
+    delete[] errorRow2;
+  }
+
+  uint8_t processPixel(int gray, int x) {
+    // Apply brightness/contrast/gamma adjustments
+    gray = adjustPixel(gray);
+
+    // Add accumulated error
+    int adjusted = gray + errorRow0[x + 2];
+    if (adjusted < 0) adjusted = 0;
+    if (adjusted > 255) adjusted = 255;
+
+    // Quantize to 4 levels
+    uint8_t quantized;
+    int quantizedValue;
+    if (adjusted < 43) {
+      quantized = 0;
+      quantizedValue = 0;
+    } else if (adjusted < 128) {
+      quantized = 1;
+      quantizedValue = 85;
+    } else if (adjusted < 213) {
+      quantized = 2;
+      quantizedValue = 170;
+    } else {
+      quantized = 3;
+      quantizedValue = 255;
+    }
+
+    // Calculate error (only distribute 6/8 = 75%)
+    int error = (adjusted - quantizedValue) >> 3;  // error/8
+
+    // Distribute 1/8 to each of 6 neighbors
+    errorRow0[x + 3] += error;  // Right
+    errorRow0[x + 4] += error;  // Right+1
+    errorRow1[x + 1] += error;  // Bottom-left
+    errorRow1[x + 2] += error;  // Bottom
+    errorRow1[x + 3] += error;  // Bottom-right
+    errorRow2[x + 2] += error;  // Two rows down
+
+    return quantized;
+  }
+
+  void nextRow() {
+    int16_t* temp = errorRow0;
+    errorRow0 = errorRow1;
+    errorRow1 = errorRow2;
+    errorRow2 = temp;
+    memset(errorRow2, 0, (width + 4) * sizeof(int16_t));
+  }
+
+  void reset() {
+    memset(errorRow0, 0, (width + 4) * sizeof(int16_t));
+    memset(errorRow1, 0, (width + 4) * sizeof(int16_t));
+    memset(errorRow2, 0, (width + 4) * sizeof(int16_t));
+  }
+
+ private:
+  int width;
+  int16_t* errorRow0;
+  int16_t* errorRow1;
+  int16_t* errorRow2;
+};
+
+// Floyd-Steinberg error diffusion dithering with serpentine scanning
+// Serpentine scanning alternates direction each row to reduce "worm" artifacts
+// Error distribution pattern (left-to-right):
+//       X   7/16
+// 3/16 5/16 1/16
+// Error distribution pattern (right-to-left, mirrored):
+// 1/16 5/16 3/16
+//      7/16  X
+class FloydSteinbergDitherer {
+ public:
+  FloydSteinbergDitherer(int width) : width(width), rowCount(0) {
+    errorCurRow = new int16_t[width + 2]();  // +2 for boundary handling
+    errorNextRow = new int16_t[width + 2]();
+  }
+
+  ~FloydSteinbergDitherer() {
+    delete[] errorCurRow;
+    delete[] errorNextRow;
+  }
+
+  // Process a single pixel and return quantized 2-bit value
+  // x is the logical x position (0 to width-1), direction handled internally
+  uint8_t processPixel(int gray, int x, bool reverseDirection) {
+    // Add accumulated error to this pixel
+    int adjusted = gray + errorCurRow[x + 1];
+
+    // Clamp to valid range
+    if (adjusted < 0) adjusted = 0;
+    if (adjusted > 255) adjusted = 255;
+
+    // Quantize to 4 levels (0, 85, 170, 255)
+    uint8_t quantized;
+    int quantizedValue;
+    if (adjusted < 43) {
+      quantized = 0;
+      quantizedValue = 0;
+    } else if (adjusted < 128) {
+      quantized = 1;
+      quantizedValue = 85;
+    } else if (adjusted < 213) {
+      quantized = 2;
+      quantizedValue = 170;
+    } else {
+      quantized = 3;
+      quantizedValue = 255;
+    }
+
+    // Calculate error
+    int error = adjusted - quantizedValue;
+
+    // Distribute error to neighbors (serpentine: direction-aware)
+    if (!reverseDirection) {
+      // Left to right: standard distribution
+      // Right: 7/16
+      errorCurRow[x + 2] += (error * 7) >> 4;
+      // Bottom-left: 3/16
+      errorNextRow[x] += (error * 3) >> 4;
+      // Bottom: 5/16
+      errorNextRow[x + 1] += (error * 5) >> 4;
+      // Bottom-right: 1/16
+      errorNextRow[x + 2] += (error) >> 4;
+    } else {
+      // Right to left: mirrored distribution
+      // Left: 7/16
+      errorCurRow[x] += (error * 7) >> 4;
+      // Bottom-right: 3/16
+      errorNextRow[x + 2] += (error * 3) >> 4;
+      // Bottom: 5/16
+      errorNextRow[x + 1] += (error * 5) >> 4;
+      // Bottom-left: 1/16
+      errorNextRow[x] += (error) >> 4;
+    }
+
+    return quantized;
+  }
+
+  // Call at the end of each row to swap buffers
+  void nextRow() {
+    // Swap buffers
+    int16_t* temp = errorCurRow;
+    errorCurRow = errorNextRow;
+    errorNextRow = temp;
+    // Clear the next row buffer
+    memset(errorNextRow, 0, (width + 2) * sizeof(int16_t));
+    rowCount++;
+  }
+
+  // Check if current row should be processed in reverse
+  bool isReverseRow() const { return (rowCount & 1) != 0; }
+
+  // Reset for a new image or MCU block
+  void reset() {
+    memset(errorCurRow, 0, (width + 2) * sizeof(int16_t));
+    memset(errorNextRow, 0, (width + 2) * sizeof(int16_t));
+    rowCount = 0;
+  }
+
+ private:
+  int width;
+  int rowCount;
+  int16_t* errorCurRow;
+  int16_t* errorNextRow;
+};
+
 inline void write16(Print& out, const uint16_t value) {
-  // out.write(reinterpret_cast<const uint8_t *>(&value), 2);
   out.write(value & 0xFF);
   out.write((value >> 8) & 0xFF);
 }
 
 inline void write32(Print& out, const uint32_t value) {
-  // out.write(reinterpret_cast<const uint8_t *>(&value), 4);
   out.write(value & 0xFF);
   out.write((value >> 8) & 0xFF);
   out.write((value >> 16) & 0xFF);
@@ -38,13 +310,49 @@ inline void write32(Print& out, const uint32_t value) {
 }
 
 inline void write32Signed(Print& out, const int32_t value) {
-  // out.write(reinterpret_cast<const uint8_t *>(&value), 4);
   out.write(value & 0xFF);
   out.write((value >> 8) & 0xFF);
   out.write((value >> 16) & 0xFF);
   out.write((value >> 24) & 0xFF);
 }
 
+// Helper function: Write BMP header with 8-bit grayscale (256 levels)
+void writeBmpHeader8bit(Print& bmpOut, const int width, const int height) {
+  // Calculate row padding (each row must be multiple of 4 bytes)
+  const int bytesPerRow = (width + 3) / 4 * 4;  // 8 bits per pixel, padded
+  const int imageSize = bytesPerRow * height;
+  const uint32_t paletteSize = 256 * 4;  // 256 colors * 4 bytes (BGRA)
+  const uint32_t fileSize = 14 + 40 + paletteSize + imageSize;
+
+  // BMP File Header (14 bytes)
+  bmpOut.write('B');
+  bmpOut.write('M');
+  write32(bmpOut, fileSize);
+  write32(bmpOut, 0);                      // Reserved
+  write32(bmpOut, 14 + 40 + paletteSize);  // Offset to pixel data
+
+  // DIB Header (BITMAPINFOHEADER - 40 bytes)
+  write32(bmpOut, 40);
+  write32Signed(bmpOut, width);
+  write32Signed(bmpOut, -height);  // Negative height = top-down bitmap
+  write16(bmpOut, 1);              // Color planes
+  write16(bmpOut, 8);              // Bits per pixel (8 bits)
+  write32(bmpOut, 0);              // BI_RGB (no compression)
+  write32(bmpOut, imageSize);
+  write32(bmpOut, 2835);  // xPixelsPerMeter (72 DPI)
+  write32(bmpOut, 2835);  // yPixelsPerMeter (72 DPI)
+  write32(bmpOut, 256);   // colorsUsed
+  write32(bmpOut, 256);   // colorsImportant
+
+  // Color Palette (256 grayscale entries x 4 bytes = 1024 bytes)
+  for (int i = 0; i < 256; i++) {
+    bmpOut.write(static_cast<uint8_t>(i));  // Blue
+    bmpOut.write(static_cast<uint8_t>(i));  // Green
+    bmpOut.write(static_cast<uint8_t>(i));  // Red
+    bmpOut.write(static_cast<uint8_t>(0));  // Reserved
+  }
+}
+
 // Helper function: Write BMP header with 2-bit color depth
 void JpegToBmpConverter::writeBmpHeader(Print& bmpOut, const int width, const int height) {
   // Calculate row padding (each row must be multiple of 4 bytes)
@@ -135,13 +443,59 @@ bool JpegToBmpConverter::jpegFileToBmpStream(File& jpegFile, Print& bmpOut) {
   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);
 
-  // Write BMP header
+  // Safety limits to prevent memory issues on ESP32
-  writeBmpHeader(bmpOut, imageInfo.m_width, imageInfo.m_height);
+  constexpr int MAX_IMAGE_WIDTH = 2048;
+  constexpr int MAX_IMAGE_HEIGHT = 3072;
+  constexpr int MAX_MCU_ROW_BYTES = 65536;
 
-  // Calculate row parameters
+  if (imageInfo.m_width > MAX_IMAGE_WIDTH || imageInfo.m_height > MAX_IMAGE_HEIGHT) {
-  const int bytesPerRow = (imageInfo.m_width * 2 + 31) / 32 * 4;
+    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);
+    return false;
+  }
 
-  // Allocate row buffer for packed 2-bit pixels
+  // Calculate output dimensions (pre-scale to fit display exactly)
+  int outWidth = imageInfo.m_width;
+  int outHeight = imageInfo.m_height;
+  // Use fixed-point scaling (16.16) for sub-pixel accuracy
+  uint32_t scaleX_fp = 65536;  // 1.0 in 16.16 fixed point
+  uint32_t scaleY_fp = 65536;
+  bool needsScaling = false;
+
+  if (USE_PRESCALE && (imageInfo.m_width > TARGET_MAX_WIDTH || imageInfo.m_height > TARGET_MAX_HEIGHT)) {
+    // Calculate scale to fit within target dimensions while maintaining aspect ratio
+    const float scaleToFitWidth = static_cast<float>(TARGET_MAX_WIDTH) / imageInfo.m_width;
+    const float scaleToFitHeight = static_cast<float>(TARGET_MAX_HEIGHT) / imageInfo.m_height;
+    const float scale = (scaleToFitWidth < scaleToFitHeight) ? scaleToFitWidth : scaleToFitHeight;
+
+    outWidth = static_cast<int>(imageInfo.m_width * scale);
+    outHeight = static_cast<int>(imageInfo.m_height * scale);
+
+    // Ensure at least 1 pixel
+    if (outWidth < 1) outWidth = 1;
+    if (outHeight < 1) outHeight = 1;
+
+    // Calculate fixed-point scale factors (source pixels per output pixel)
+    // scaleX_fp = (srcWidth << 16) / outWidth
+    scaleX_fp = (static_cast<uint32_t>(imageInfo.m_width) << 16) / outWidth;
+    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, TARGET_MAX_WIDTH, TARGET_MAX_HEIGHT);
+  }
+
+  // Write BMP header with output dimensions
+  int bytesPerRow;
+  if (USE_8BIT_OUTPUT) {
+    writeBmpHeader8bit(bmpOut, outWidth, outHeight);
+    bytesPerRow = (outWidth + 3) / 4 * 4;
+  } else {
+    writeBmpHeader(bmpOut, outWidth, outHeight);
+    bytesPerRow = (outWidth * 2 + 31) / 32 * 4;
+  }
+
+  // Allocate row buffer
   auto* rowBuffer = static_cast<uint8_t*>(malloc(bytesPerRow));
   if (!rowBuffer) {
     Serial.printf("[%lu] [JPG] Failed to allocate row buffer\n", millis());
@@ -152,13 +506,48 @@ bool JpegToBmpConverter::jpegFileToBmpStream(File& jpegFile, Print& bmpOut) {
   // This is the minimal memory needed for streaming conversion
   const int mcuPixelHeight = imageInfo.m_MCUHeight;
   const int mcuRowPixels = imageInfo.m_width * mcuPixelHeight;
-  auto* mcuRowBuffer = static_cast<uint8_t*>(malloc(mcuRowPixels));
+
-  if (!mcuRowBuffer) {
+  // Validate MCU row buffer size before allocation
-    Serial.printf("[%lu] [JPG] Failed to allocate MCU row buffer\n", millis());
+  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);
     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);
+    free(rowBuffer);
+    return false;
+  }
+
+  // Create ditherer if enabled (only for 2-bit output)
+  // Use OUTPUT dimensions for dithering (after prescaling)
+  AtkinsonDitherer* atkinsonDitherer = nullptr;
+  FloydSteinbergDitherer* fsDitherer = nullptr;
+  if (!USE_8BIT_OUTPUT) {
+    if (USE_ATKINSON) {
+      atkinsonDitherer = new AtkinsonDitherer(outWidth);
+    } else if (USE_FLOYD_STEINBERG) {
+      fsDitherer = new FloydSteinbergDitherer(outWidth);
+    }
+  }
+
+  // For scaling: accumulate source rows into scaled output rows
+  // We need to track which source Y maps to which output Y
+  // Using fixed-point: srcY_fp = outY * scaleY_fp (gives source Y in 16.16 format)
+  uint32_t* rowAccum = nullptr;    // Accumulator for each output X (32-bit for larger sums)
+  uint16_t* rowCount = nullptr;    // Count of source pixels accumulated per output X
+  int currentOutY = 0;             // Current output row being accumulated
+  uint32_t nextOutY_srcStart = 0;  // Source Y where next output row starts (16.16 fixed point)
+
+  if (needsScaling) {
+    rowAccum = new uint32_t[outWidth]();
+    rowCount = new uint16_t[outWidth]();
+    nextOutY_srcStart = scaleY_fp;  // First boundary is at scaleY_fp (source Y for outY=1)
+  }
+
   // Process MCUs row-by-row and write to BMP as we go (top-down)
   const int mcuPixelWidth = imageInfo.m_MCUWidth;
 
@@ -181,61 +570,164 @@ bool JpegToBmpConverter::jpegFileToBmpStream(File& jpegFile, Print& bmpOut) {
         return false;
       }
 
-      // Process MCU block into MCU row buffer
+      // picojpeg stores MCU data in 8x8 blocks
+      // Block layout: H2V2(16x16)=0,64,128,192 H2V1(16x8)=0,64 H1V2(8x16)=0,128
       for (int blockY = 0; blockY < mcuPixelHeight; blockY++) {
         for (int blockX = 0; blockX < mcuPixelWidth; blockX++) {
           const int pixelX = mcuX * mcuPixelWidth + blockX;
+          if (pixelX >= imageInfo.m_width) continue;
 
-          // Skip pixels outside image width (can happen with MCU alignment)
+          // Calculate proper block offset for picojpeg buffer
-          if (pixelX >= imageInfo.m_width) {
+          const int blockCol = blockX / 8;
-            continue;
+          const int blockRow = blockY / 8;
-          }
+          const int localX = blockX % 8;
+          const int localY = blockY % 8;
+          const int blocksPerRow = mcuPixelWidth / 8;
+          const int blockIndex = blockRow * blocksPerRow + blockCol;
+          const int pixelOffset = blockIndex * 64 + localY * 8 + localX;
 
-          // Get grayscale value
           uint8_t gray;
           if (imageInfo.m_comps == 1) {
-            // Grayscale image
+            gray = imageInfo.m_pMCUBufR[pixelOffset];
-            gray = imageInfo.m_pMCUBufR[blockY * mcuPixelWidth + blockX];
           } else {
-            // RGB image - convert to grayscale
+            const uint8_t r = imageInfo.m_pMCUBufR[pixelOffset];
-            const uint8_t r = imageInfo.m_pMCUBufR[blockY * mcuPixelWidth + blockX];
+            const uint8_t g = imageInfo.m_pMCUBufG[pixelOffset];
-            const uint8_t g = imageInfo.m_pMCUBufG[blockY * mcuPixelWidth + blockX];
+            const uint8_t b = imageInfo.m_pMCUBufB[pixelOffset];
-            const uint8_t b = imageInfo.m_pMCUBufB[blockY * mcuPixelWidth + blockX];
+            gray = (r * 25 + g * 50 + b * 25) / 100;
-            // Luminance formula: Y = 0.299*R + 0.587*G + 0.114*B
-            // Using integer approximation: (30*R + 59*G + 11*B) / 100
-            gray = (r * 30 + g * 59 + b * 11) / 100;
           }
 
-          // Store grayscale value in MCU row buffer
           mcuRowBuffer[blockY * imageInfo.m_width + pixelX] = gray;
         }
       }
     }
 
-    // Write all pixel rows from this MCU row to BMP file
+    // Process source rows from this MCU row
     const int startRow = mcuY * mcuPixelHeight;
     const int endRow = (mcuY + 1) * mcuPixelHeight;
 
     for (int y = startRow; y < endRow && y < imageInfo.m_height; y++) {
-      memset(rowBuffer, 0, bytesPerRow);
+      const int bufferY = y - startRow;
 
-      // Pack 4 pixels per byte (2 bits each)
+      if (!needsScaling) {
-      for (int x = 0; x < imageInfo.m_width; x++) {
+        // No scaling - direct output (1:1 mapping)
-        const int bufferY = y - startRow;
+        memset(rowBuffer, 0, bytesPerRow);
-        const uint8_t gray = mcuRowBuffer[bufferY * imageInfo.m_width + x];
-        const uint8_t twoBit = grayscaleTo2Bit(gray);
 
-        const int byteIndex = (x * 2) / 8;
+        if (USE_8BIT_OUTPUT) {
-        const int bitOffset = 6 - ((x * 2) % 8);  // 6, 4, 2, 0
+          for (int x = 0; x < outWidth; x++) {
-        rowBuffer[byteIndex] |= (twoBit << bitOffset);
+            const uint8_t gray = mcuRowBuffer[bufferY * imageInfo.m_width + x];
+            rowBuffer[x] = adjustPixel(gray);
+          }
+        } else {
+          for (int x = 0; x < outWidth; x++) {
+            const uint8_t gray = mcuRowBuffer[bufferY * imageInfo.m_width + x];
+            uint8_t twoBit;
+            if (atkinsonDitherer) {
+              twoBit = atkinsonDitherer->processPixel(gray, x);
+            } else if (fsDitherer) {
+              twoBit = fsDitherer->processPixel(gray, x, fsDitherer->isReverseRow());
+            } else {
+              twoBit = quantize(gray, x, y);
+            }
+            const int byteIndex = (x * 2) / 8;
+            const int bitOffset = 6 - ((x * 2) % 8);
+            rowBuffer[byteIndex] |= (twoBit << bitOffset);
+          }
+          if (atkinsonDitherer)
+            atkinsonDitherer->nextRow();
+          else if (fsDitherer)
+            fsDitherer->nextRow();
+        }
+        bmpOut.write(rowBuffer, bytesPerRow);
+      } else {
+        // Fixed-point area averaging for exact fit scaling
+        // For each output pixel X, accumulate source pixels that map to it
+        // srcX range for outX: [outX * scaleX_fp >> 16, (outX+1) * scaleX_fp >> 16)
+        const uint8_t* srcRow = mcuRowBuffer + bufferY * imageInfo.m_width;
+
+        for (int outX = 0; outX < outWidth; outX++) {
+          // Calculate source X range for this output pixel
+          const int srcXStart = (static_cast<uint32_t>(outX) * scaleX_fp) >> 16;
+          const int srcXEnd = (static_cast<uint32_t>(outX + 1) * scaleX_fp) >> 16;
+
+          // Accumulate all source pixels in this range
+          int sum = 0;
+          int count = 0;
+          for (int srcX = srcXStart; srcX < srcXEnd && srcX < imageInfo.m_width; srcX++) {
+            sum += srcRow[srcX];
+            count++;
+          }
+
+          // Handle edge case: if no pixels in range, use nearest
+          if (count == 0 && srcXStart < imageInfo.m_width) {
+            sum = srcRow[srcXStart];
+            count = 1;
+          }
+
+          rowAccum[outX] += sum;
+          rowCount[outX] += count;
+        }
+
+        // Check if we've crossed into the next output row
+        // Current source Y in fixed point: y << 16
+        const uint32_t srcY_fp = static_cast<uint32_t>(y + 1) << 16;
+
+        // Output row when source Y crosses the boundary
+        if (srcY_fp >= nextOutY_srcStart && currentOutY < outHeight) {
+          memset(rowBuffer, 0, bytesPerRow);
+
+          if (USE_8BIT_OUTPUT) {
+            for (int x = 0; x < outWidth; x++) {
+              const uint8_t gray = (rowCount[x] > 0) ? (rowAccum[x] / rowCount[x]) : 0;
+              rowBuffer[x] = adjustPixel(gray);
+            }
+          } else {
+            for (int x = 0; x < outWidth; x++) {
+              const uint8_t gray = (rowCount[x] > 0) ? (rowAccum[x] / rowCount[x]) : 0;
+              uint8_t twoBit;
+              if (atkinsonDitherer) {
+                twoBit = atkinsonDitherer->processPixel(gray, x);
+              } else if (fsDitherer) {
+                twoBit = fsDitherer->processPixel(gray, x, fsDitherer->isReverseRow());
+              } else {
+                twoBit = quantize(gray, x, currentOutY);
+              }
+              const int byteIndex = (x * 2) / 8;
+              const int bitOffset = 6 - ((x * 2) % 8);
+              rowBuffer[byteIndex] |= (twoBit << bitOffset);
+            }
+            if (atkinsonDitherer)
+              atkinsonDitherer->nextRow();
+            else if (fsDitherer)
+              fsDitherer->nextRow();
+          }
+
+          bmpOut.write(rowBuffer, bytesPerRow);
+          currentOutY++;
+
+          // Reset accumulators for next output row
+          memset(rowAccum, 0, outWidth * sizeof(uint32_t));
+          memset(rowCount, 0, outWidth * sizeof(uint16_t));
+
+          // Update boundary for next output row
+          nextOutY_srcStart = static_cast<uint32_t>(currentOutY + 1) * scaleY_fp;
+        }
       }
-
-      // Write row with padding
-      bmpOut.write(rowBuffer, bytesPerRow);
     }
   }
 
   // Clean up
+  if (rowAccum) {
+    delete[] rowAccum;
+  }
+  if (rowCount) {
+    delete[] rowCount;
+  }
+  if (atkinsonDitherer) {
+    delete atkinsonDitherer;
+  }
+  if (fsDitherer) {
+    delete fsDitherer;
+  }
   free(mcuRowBuffer);
   free(rowBuffer);
 

lib/JpegToBmpConverter/JpegToBmpConverter.h

@@ -6,7 +6,7 @@ class ZipFile;
 
 class JpegToBmpConverter {
   static void writeBmpHeader(Print& bmpOut, int width, int height);
-  static uint8_t grayscaleTo2Bit(uint8_t grayscale);
+  // [COMMENTED OUT] static uint8_t grayscaleTo2Bit(uint8_t grayscale, int x, int y);
   static unsigned char jpegReadCallback(unsigned char* pBuf, unsigned char buf_size,
                                         unsigned char* pBytes_actually_read, void* pCallback_data);
 

lib/Serialization/Serialization.h

@@ -1,4 +1,6 @@
 #pragma once
+#include <FS.h>
+
 #include <iostream>
 
 namespace serialization {
@@ -7,21 +9,44 @@ static void writePod(std::ostream& os, const T& value) {
   os.write(reinterpret_cast<const char*>(&value), sizeof(T));
 }
 
+template <typename T>
+static void writePod(File& file, const T& value) {
+  file.write(reinterpret_cast<const uint8_t*>(&value), sizeof(T));
+}
+
 template <typename T>
 static void readPod(std::istream& is, T& value) {
   is.read(reinterpret_cast<char*>(&value), sizeof(T));
 }
 
+template <typename T>
+static void readPod(File& file, T& value) {
+  file.read(reinterpret_cast<uint8_t*>(&value), sizeof(T));
+}
+
 static void writeString(std::ostream& os, const std::string& s) {
   const uint32_t len = s.size();
   writePod(os, len);
   os.write(s.data(), len);
 }
 
+static void writeString(File& file, const std::string& s) {
+  const uint32_t len = s.size();
+  writePod(file, len);
+  file.write(reinterpret_cast<const uint8_t*>(s.data()), len);
+}
+
 static void readString(std::istream& is, std::string& s) {
   uint32_t len;
   readPod(is, len);
   s.resize(len);
   is.read(&s[0], len);
 }
+
+static void readString(File& file, std::string& s) {
+  uint32_t len;
+  readPod(file, len);
+  s.resize(len);
+  file.read(reinterpret_cast<uint8_t*>(&s[0]), len);
+}
 }  // namespace serialization

lib/Xtc/README

@@ -0,0 +1,40 @@
+# XTC/XTCH Library
+
+XTC ebook format support for CrossPoint Reader.
+
+## Supported Formats
+
+| Format | Extension | Description                                  |
+|--------|-----------|----------------------------------------------|
+| XTC    | `.xtc`    | Container with XTG pages (1-bit monochrome)  |
+| XTCH   | `.xtch`   | Container with XTH pages (2-bit grayscale)   |
+
+## Format Overview
+
+XTC/XTCH are container formats designed for ESP32 e-paper displays. They store pre-rendered bitmap pages optimized for the XTeink X4 e-reader (480x800 resolution).
+
+### Container Structure (XTC/XTCH)
+
+- 56-byte header with metadata offsets
+- Optional metadata (title, author, etc.)
+- Page index table (16 bytes per page)
+- Page data (XTG or XTH format)
+
+### Page Formats
+
+#### XTG (1-bit monochrome)
+
+- Row-major storage, 8 pixels per byte
+- MSB first (bit 7 = leftmost pixel)
+- 0 = Black, 1 = White
+
+#### XTH (2-bit grayscale)
+
+- Two bit planes stored sequentially
+- Column-major order (right to left)
+- 8 vertical pixels per byte
+- Grayscale: 0=White, 1=Dark Grey, 2=Light Grey, 3=Black
+
+## Reference
+
+Original format info: <https://gist.github.com/CrazyCoder/b125f26d6987c0620058249f59f1327d>

lib/Xtc/Xtc.cpp

@@ -0,0 +1,337 @@
+/**
+ * Xtc.cpp
+ *
+ * Main XTC ebook class implementation
+ * XTC ebook support for CrossPoint Reader
+ */
+
+#include "Xtc.h"
+
+#include <FsHelpers.h>
+#include <HardwareSerial.h>
+#include <SD.h>
+
+bool Xtc::load() {
+  Serial.printf("[%lu] [XTC] Loading XTC: %s\n", millis(), filepath.c_str());
+
+  // Initialize parser
+  parser.reset(new xtc::XtcParser());
+
+  // 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));
+    parser.reset();
+    return false;
+  }
+
+  loaded = true;
+  Serial.printf("[%lu] [XTC] Loaded XTC: %s (%lu pages)\n", millis(), filepath.c_str(), parser->getPageCount());
+  return true;
+}
+
+bool Xtc::clearCache() const {
+  if (!SD.exists(cachePath.c_str())) {
+    Serial.printf("[%lu] [XTC] Cache does not exist, no action needed\n", millis());
+    return true;
+  }
+
+  if (!FsHelpers::removeDir(cachePath.c_str())) {
+    Serial.printf("[%lu] [XTC] Failed to clear cache\n", millis());
+    return false;
+  }
+
+  Serial.printf("[%lu] [XTC] Cache cleared successfully\n", millis());
+  return true;
+}
+
+void Xtc::setupCacheDir() const {
+  if (SD.exists(cachePath.c_str())) {
+    return;
+  }
+
+  // Create directories recursively
+  for (size_t i = 1; i < cachePath.length(); i++) {
+    if (cachePath[i] == '/') {
+      SD.mkdir(cachePath.substr(0, i).c_str());
+    }
+  }
+  SD.mkdir(cachePath.c_str());
+}
+
+std::string Xtc::getTitle() const {
+  if (!loaded || !parser) {
+    return "";
+  }
+
+  // Try to get title from XTC metadata first
+  std::string title = parser->getTitle();
+  if (!title.empty()) {
+    return title;
+  }
+
+  // Fallback: extract filename from path as title
+  size_t lastSlash = filepath.find_last_of('/');
+  size_t lastDot = filepath.find_last_of('.');
+
+  if (lastSlash == std::string::npos) {
+    lastSlash = 0;
+  } else {
+    lastSlash++;
+  }
+
+  if (lastDot == std::string::npos || lastDot <= lastSlash) {
+    return filepath.substr(lastSlash);
+  }
+
+  return filepath.substr(lastSlash, lastDot - lastSlash);
+}
+
+std::string Xtc::getCoverBmpPath() const { return cachePath + "/cover.bmp"; }
+
+bool Xtc::generateCoverBmp() const {
+  // Already generated
+  if (SD.exists(getCoverBmpPath().c_str())) {
+    return true;
+  }
+
+  if (!loaded || !parser) {
+    Serial.printf("[%lu] [XTC] Cannot generate cover BMP, file not loaded\n", millis());
+    return false;
+  }
+
+  if (parser->getPageCount() == 0) {
+    Serial.printf("[%lu] [XTC] No pages in XTC file\n", millis());
+    return false;
+  }
+
+  // Setup cache directory
+  setupCacheDir();
+
+  // 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());
+    return false;
+  }
+
+  // Get bit depth
+  const uint8_t bitDepth = parser->getBitDepth();
+
+  // Allocate buffer for page data
+  // XTG (1-bit): Row-major, ((width+7)/8) * height bytes
+  // XTH (2-bit): Two bit planes, column-major, ((width * height + 7) / 8) * 2 bytes
+  size_t bitmapSize;
+  if (bitDepth == 2) {
+    bitmapSize = ((static_cast<size_t>(pageInfo.width) * pageInfo.height + 7) / 8) * 2;
+  } else {
+    bitmapSize = ((pageInfo.width + 7) / 8) * pageInfo.height;
+  }
+  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);
+    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());
+    free(pageBuffer);
+    return false;
+  }
+
+  // Create BMP file
+  File coverBmp;
+  if (!FsHelpers::openFileForWrite("XTC", getCoverBmpPath(), coverBmp)) {
+    Serial.printf("[%lu] [XTC] Failed to create cover BMP file\n", millis());
+    free(pageBuffer);
+    return false;
+  }
+
+  // Write BMP header
+  // BMP file header (14 bytes)
+  const uint32_t rowSize = ((pageInfo.width + 31) / 32) * 4;  // Row size aligned to 4 bytes
+  const uint32_t imageSize = rowSize * pageInfo.height;
+  const uint32_t fileSize = 14 + 40 + 8 + imageSize;  // Header + DIB + palette + data
+
+  // File header
+  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);
+  uint32_t dataOffset = 14 + 40 + 8;  // 1-bit palette has 2 colors (8 bytes)
+  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 width = pageInfo.width;
+  coverBmp.write(reinterpret_cast<const uint8_t*>(&width), 4);
+  int32_t height = -static_cast<int32_t>(pageInfo.height);  // Negative for top-down
+  coverBmp.write(reinterpret_cast<const uint8_t*>(&height), 4);
+  uint16_t planes = 1;
+  coverBmp.write(reinterpret_cast<const uint8_t*>(&planes), 2);
+  uint16_t bitsPerPixel = 1;  // 1-bit monochrome
+  coverBmp.write(reinterpret_cast<const uint8_t*>(&bitsPerPixel), 2);
+  uint32_t compression = 0;  // BI_RGB (no compression)
+  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)
+  // XTC uses inverted polarity: 0 = black, 1 = white
+  // Color 0: Black (text/foreground in XTC)
+  uint8_t black[4] = {0x00, 0x00, 0x00, 0x00};
+  coverBmp.write(black, 4);
+  // Color 1: White (background in XTC)
+  uint8_t white[4] = {0xFF, 0xFF, 0xFF, 0x00};
+  coverBmp.write(white, 4);
+
+  // Write bitmap data
+  // BMP requires 4-byte row alignment
+  const size_t dstRowSize = (pageInfo.width + 7) / 8;  // 1-bit destination row size
+
+  if (bitDepth == 2) {
+    // XTH 2-bit mode: Two bit planes, column-major order
+    // - Columns scanned right to left (x = width-1 down to 0)
+    // - 8 vertical pixels per byte (MSB = topmost pixel in group)
+    // - First plane: Bit1, Second plane: Bit2
+    // - Pixel value = (bit1 << 1) | bit2
+    const size_t planeSize = (static_cast<size_t>(pageInfo.width) * pageInfo.height + 7) / 8;
+    const uint8_t* plane1 = pageBuffer;                 // Bit1 plane
+    const uint8_t* plane2 = pageBuffer + planeSize;     // Bit2 plane
+    const size_t colBytes = (pageInfo.height + 7) / 8;  // Bytes per column
+
+    // Allocate a row buffer for 1-bit output
+    uint8_t* rowBuffer = static_cast<uint8_t*>(malloc(dstRowSize));
+    if (!rowBuffer) {
+      free(pageBuffer);
+      coverBmp.close();
+      return false;
+    }
+
+    for (uint16_t y = 0; y < pageInfo.height; y++) {
+      memset(rowBuffer, 0xFF, dstRowSize);  // Start with all white
+
+      for (uint16_t x = 0; x < pageInfo.width; x++) {
+        // Column-major, right to left: column index = (width - 1 - x)
+        const size_t colIndex = pageInfo.width - 1 - x;
+        const size_t byteInCol = y / 8;
+        const size_t bitInByte = 7 - (y % 8);  // MSB = topmost pixel
+
+        const size_t byteOffset = colIndex * colBytes + byteInCol;
+        const uint8_t bit1 = (plane1[byteOffset] >> bitInByte) & 1;
+        const uint8_t bit2 = (plane2[byteOffset] >> bitInByte) & 1;
+        const uint8_t pixelValue = (bit1 << 1) | bit2;
+
+        // Threshold: 0=white (1); 1,2,3=black (0)
+        if (pixelValue >= 1) {
+          // Set bit to 0 (black) in BMP format
+          const size_t dstByte = x / 8;
+          const size_t dstBit = 7 - (x % 8);
+          rowBuffer[dstByte] &= ~(1 << dstBit);
+        }
+      }
+
+      // Write converted row
+      coverBmp.write(rowBuffer, dstRowSize);
+
+      // Pad to 4-byte boundary
+      uint8_t padding[4] = {0, 0, 0, 0};
+      size_t paddingSize = rowSize - dstRowSize;
+      if (paddingSize > 0) {
+        coverBmp.write(padding, paddingSize);
+      }
+    }
+
+    free(rowBuffer);
+  } else {
+    // 1-bit source: write directly with proper padding
+    const size_t srcRowSize = (pageInfo.width + 7) / 8;
+
+    for (uint16_t y = 0; y < pageInfo.height; y++) {
+      // Write source row
+      coverBmp.write(pageBuffer + y * srcRowSize, srcRowSize);
+
+      // Pad to 4-byte boundary
+      uint8_t padding[4] = {0, 0, 0, 0};
+      size_t paddingSize = rowSize - srcRowSize;
+      if (paddingSize > 0) {
+        coverBmp.write(padding, paddingSize);
+      }
+    }
+  }
+
+  coverBmp.close();
+  free(pageBuffer);
+
+  Serial.printf("[%lu] [XTC] Generated cover BMP: %s\n", millis(), getCoverBmpPath().c_str());
+  return true;
+}
+
+uint32_t Xtc::getPageCount() const {
+  if (!loaded || !parser) {
+    return 0;
+  }
+  return parser->getPageCount();
+}
+
+uint16_t Xtc::getPageWidth() const {
+  if (!loaded || !parser) {
+    return 0;
+  }
+  return parser->getWidth();
+}
+
+uint16_t Xtc::getPageHeight() const {
+  if (!loaded || !parser) {
+    return 0;
+  }
+  return parser->getHeight();
+}
+
+uint8_t Xtc::getBitDepth() const {
+  if (!loaded || !parser) {
+    return 1;  // Default to 1-bit
+  }
+  return parser->getBitDepth();
+}
+
+size_t Xtc::loadPage(uint32_t pageIndex, uint8_t* buffer, size_t bufferSize) const {
+  if (!loaded || !parser) {
+    return 0;
+  }
+  return const_cast<xtc::XtcParser*>(parser.get())->loadPage(pageIndex, buffer, bufferSize);
+}
+
+xtc::XtcError Xtc::loadPageStreaming(uint32_t pageIndex,
+                                     std::function<void(const uint8_t* data, size_t size, size_t offset)> callback,
+                                     size_t chunkSize) const {
+  if (!loaded || !parser) {
+    return xtc::XtcError::FILE_NOT_FOUND;
+  }
+  return const_cast<xtc::XtcParser*>(parser.get())->loadPageStreaming(pageIndex, callback, chunkSize);
+}
+
+uint8_t Xtc::calculateProgress(uint32_t currentPage) const {
+  if (!loaded || !parser || parser->getPageCount() == 0) {
+    return 0;
+  }
+  return static_cast<uint8_t>((currentPage + 1) * 100 / parser->getPageCount());
+}
+
+xtc::XtcError Xtc::getLastError() const {
+  if (!parser) {
+    return xtc::XtcError::FILE_NOT_FOUND;
+  }
+  return parser->getLastError();
+}

lib/Xtc/Xtc.h

@@ -0,0 +1,97 @@
+/**
+ * Xtc.h
+ *
+ * Main XTC ebook class for CrossPoint Reader
+ * Provides EPUB-like interface for XTC file handling
+ */
+
+#pragma once
+
+#include <memory>
+#include <string>
+
+#include "Xtc/XtcParser.h"
+#include "Xtc/XtcTypes.h"
+
+/**
+ * XTC Ebook Handler
+ *
+ * Handles XTC file loading, page access, and cover image generation.
+ * Interface is designed to be similar to Epub class for easy integration.
+ */
+class Xtc {
+  std::string filepath;
+  std::string cachePath;
+  std::unique_ptr<xtc::XtcParser> parser;
+  bool loaded;
+
+ public:
+  explicit Xtc(std::string filepath, const std::string& cacheDir) : filepath(std::move(filepath)), loaded(false) {
+    // Create cache key based on filepath (same as Epub)
+    cachePath = cacheDir + "/xtc_" + std::to_string(std::hash<std::string>{}(this->filepath));
+  }
+  ~Xtc() = default;
+
+  /**
+   * Load XTC file
+   * @return true on success
+   */
+  bool load();
+
+  /**
+   * Clear cached data
+   * @return true on success
+   */
+  bool clearCache() const;
+
+  /**
+   * Setup cache directory
+   */
+  void setupCacheDir() const;
+
+  // Path accessors
+  const std::string& getCachePath() const { return cachePath; }
+  const std::string& getPath() const { return filepath; }
+
+  // Metadata
+  std::string getTitle() const;
+
+  // Cover image support (for sleep screen)
+  std::string getCoverBmpPath() const;
+  bool generateCoverBmp() const;
+
+  // Page access
+  uint32_t getPageCount() const;
+  uint16_t getPageWidth() const;
+  uint16_t getPageHeight() const;
+  uint8_t getBitDepth() const;  // 1 = XTC (1-bit), 2 = XTCH (2-bit)
+
+  /**
+   * Load page bitmap data
+   * @param pageIndex Page index (0-based)
+   * @param buffer Output buffer
+   * @param bufferSize Buffer size
+   * @return Number of bytes read
+   */
+  size_t loadPage(uint32_t pageIndex, uint8_t* buffer, size_t bufferSize) const;
+
+  /**
+   * Load page with streaming callback
+   * @param pageIndex Page index
+   * @param callback Callback for each chunk
+   * @param chunkSize Chunk size
+   * @return Error code
+   */
+  xtc::XtcError loadPageStreaming(uint32_t pageIndex,
+                                  std::function<void(const uint8_t* data, size_t size, size_t offset)> callback,
+                                  size_t chunkSize = 1024) const;
+
+  // Progress calculation
+  uint8_t calculateProgress(uint32_t currentPage) const;
+
+  // Check if file is loaded
+  bool isLoaded() const { return loaded; }
+
+  // Error information
+  xtc::XtcError getLastError() const;
+};

lib/Xtc/Xtc/XtcParser.cpp

@@ -0,0 +1,316 @@
+/**
+ * XtcParser.cpp
+ *
+ * XTC file parsing implementation
+ * XTC ebook support for CrossPoint Reader
+ */
+
+#include "XtcParser.h"
+
+#include <FsHelpers.h>
+#include <HardwareSerial.h>
+
+#include <cstring>
+
+namespace xtc {
+
+XtcParser::XtcParser()
+    : m_isOpen(false),
+      m_defaultWidth(DISPLAY_WIDTH),
+      m_defaultHeight(DISPLAY_HEIGHT),
+      m_bitDepth(1),
+      m_lastError(XtcError::OK) {
+  memset(&m_header, 0, sizeof(m_header));
+}
+
+XtcParser::~XtcParser() { close(); }
+
+XtcError XtcParser::open(const char* filepath) {
+  // Close if already open
+  if (m_isOpen) {
+    close();
+  }
+
+  // Open file
+  if (!FsHelpers::openFileForRead("XTC", filepath, m_file)) {
+    m_lastError = XtcError::FILE_NOT_FOUND;
+    return m_lastError;
+  }
+
+  // Read header
+  m_lastError = readHeader();
+  if (m_lastError != XtcError::OK) {
+    Serial.printf("[%lu] [XTC] Failed to read header: %s\n", millis(), errorToString(m_lastError));
+    m_file.close();
+    return m_lastError;
+  }
+
+  // Read title if available
+  readTitle();
+
+  // 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));
+    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);
+  return XtcError::OK;
+}
+
+void XtcParser::close() {
+  if (m_isOpen) {
+    m_file.close();
+    m_isOpen = false;
+  }
+  m_pageTable.clear();
+  m_title.clear();
+  memset(&m_header, 0, sizeof(m_header));
+}
+
+XtcError XtcParser::readHeader() {
+  // Read first 56 bytes of header
+  size_t bytesRead = m_file.read(reinterpret_cast<uint8_t*>(&m_header), sizeof(XtcHeader));
+  if (bytesRead != sizeof(XtcHeader)) {
+    return XtcError::READ_ERROR;
+  }
+
+  // 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);
+    return XtcError::INVALID_MAGIC;
+  }
+
+  // Determine bit depth from file magic
+  m_bitDepth = (m_header.magic == XTCH_MAGIC) ? 2 : 1;
+
+  // Check version
+  if (m_header.version > 1) {
+    Serial.printf("[%lu] [XTC] Unsupported version: %d\n", millis(), m_header.version);
+    return XtcError::INVALID_VERSION;
+  }
+
+  // Basic validation
+  if (m_header.pageCount == 0) {
+    return XtcError::CORRUPTED_HEADER;
+  }
+
+  Serial.printf("[%lu] [XTC] Header: magic=0x%08X (%s), ver=%u, pages=%u, bitDepth=%u\n", millis(), m_header.magic,
+                (m_header.magic == XTCH_MAGIC) ? "XTCH" : "XTC", m_header.version, m_header.pageCount, m_bitDepth);
+
+  return XtcError::OK;
+}
+
+XtcError XtcParser::readTitle() {
+  // Title is usually at offset 0x38 (56) for 88-byte headers
+  // Read title as null-terminated UTF-8 string
+  if (m_header.titleOffset == 0) {
+    m_header.titleOffset = 0x38;  // Default offset
+  }
+
+  if (!m_file.seek(m_header.titleOffset)) {
+    return XtcError::READ_ERROR;
+  }
+
+  char titleBuf[128] = {0};
+  m_file.read(reinterpret_cast<uint8_t*>(titleBuf), sizeof(titleBuf) - 1);
+  m_title = titleBuf;
+
+  Serial.printf("[%lu] [XTC] Title: %s\n", millis(), m_title.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());
+    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);
+    return XtcError::READ_ERROR;
+  }
+
+  m_pageTable.resize(m_header.pageCount);
+
+  // Read page table entries
+  for (uint16_t i = 0; i < m_header.pageCount; i++) {
+    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);
+      return XtcError::READ_ERROR;
+    }
+
+    m_pageTable[i].offset = static_cast<uint32_t>(entry.dataOffset);
+    m_pageTable[i].size = entry.dataSize;
+    m_pageTable[i].width = entry.width;
+    m_pageTable[i].height = entry.height;
+    m_pageTable[i].bitDepth = m_bitDepth;
+
+    // Update default dimensions from first page
+    if (i == 0) {
+      m_defaultWidth = entry.width;
+      m_defaultHeight = entry.height;
+    }
+  }
+
+  Serial.printf("[%lu] [XTC] Read %u page table entries\n", millis(), m_header.pageCount);
+  return XtcError::OK;
+}
+
+bool XtcParser::getPageInfo(uint32_t pageIndex, PageInfo& info) const {
+  if (pageIndex >= m_pageTable.size()) {
+    return false;
+  }
+  info = m_pageTable[pageIndex];
+  return true;
+}
+
+size_t XtcParser::loadPage(uint32_t pageIndex, uint8_t* buffer, size_t bufferSize) {
+  if (!m_isOpen) {
+    m_lastError = XtcError::FILE_NOT_FOUND;
+    return 0;
+  }
+
+  if (pageIndex >= m_header.pageCount) {
+    m_lastError = XtcError::PAGE_OUT_OF_RANGE;
+    return 0;
+  }
+
+  const PageInfo& page = m_pageTable[pageIndex];
+
+  // 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);
+    m_lastError = XtcError::READ_ERROR;
+    return 0;
+  }
+
+  // Read page header (XTG for 1-bit, XTH for 2-bit - same structure)
+  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);
+    m_lastError = XtcError::READ_ERROR;
+    return 0;
+  }
+
+  // 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);
+    m_lastError = XtcError::INVALID_MAGIC;
+    return 0;
+  }
+
+  // Calculate bitmap size based on bit depth
+  // XTG (1-bit): Row-major, ((width+7)/8) * height bytes
+  // XTH (2-bit): Two bit planes, column-major, ((width * height + 7) / 8) * 2 bytes
+  size_t bitmapSize;
+  if (m_bitDepth == 2) {
+    // XTH: two bit planes, each containing (width * height) bits rounded up to bytes
+    bitmapSize = ((static_cast<size_t>(pageHeader.width) * pageHeader.height + 7) / 8) * 2;
+  } else {
+    bitmapSize = ((pageHeader.width + 7) / 8) * pageHeader.height;
+  }
+
+  // Check buffer size
+  if (bufferSize < bitmapSize) {
+    Serial.printf("[%lu] [XTC] Buffer too small: need %u, have %u\n", millis(), bitmapSize, bufferSize);
+    m_lastError = XtcError::MEMORY_ERROR;
+    return 0;
+  }
+
+  // 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);
+    m_lastError = XtcError::READ_ERROR;
+    return 0;
+  }
+
+  m_lastError = XtcError::OK;
+  return bytesRead;
+}
+
+XtcError XtcParser::loadPageStreaming(uint32_t pageIndex,
+                                      std::function<void(const uint8_t* data, size_t size, size_t offset)> callback,
+                                      size_t chunkSize) {
+  if (!m_isOpen) {
+    return XtcError::FILE_NOT_FOUND;
+  }
+
+  if (pageIndex >= m_header.pageCount) {
+    return XtcError::PAGE_OUT_OF_RANGE;
+  }
+
+  const PageInfo& page = m_pageTable[pageIndex];
+
+  // Seek to page data
+  if (!m_file.seek(page.offset)) {
+    return XtcError::READ_ERROR;
+  }
+
+  // Read and skip page header (XTG for 1-bit, XTH for 2-bit)
+  XtgPageHeader pageHeader;
+  size_t headerRead = m_file.read(reinterpret_cast<uint8_t*>(&pageHeader), sizeof(XtgPageHeader));
+  const uint32_t expectedMagic = (m_bitDepth == 2) ? XTH_MAGIC : XTG_MAGIC;
+  if (headerRead != sizeof(XtgPageHeader) || pageHeader.magic != expectedMagic) {
+    return XtcError::READ_ERROR;
+  }
+
+  // Calculate bitmap size based on bit depth
+  // XTG (1-bit): Row-major, ((width+7)/8) * height bytes
+  // XTH (2-bit): Two bit planes, ((width * height + 7) / 8) * 2 bytes
+  size_t bitmapSize;
+  if (m_bitDepth == 2) {
+    bitmapSize = ((static_cast<size_t>(pageHeader.width) * pageHeader.height + 7) / 8) * 2;
+  } else {
+    bitmapSize = ((pageHeader.width + 7) / 8) * pageHeader.height;
+  }
+
+  // Read in chunks
+  std::vector<uint8_t> chunk(chunkSize);
+  size_t totalRead = 0;
+
+  while (totalRead < bitmapSize) {
+    size_t toRead = std::min(chunkSize, bitmapSize - totalRead);
+    size_t bytesRead = m_file.read(chunk.data(), toRead);
+
+    if (bytesRead == 0) {
+      return XtcError::READ_ERROR;
+    }
+
+    callback(chunk.data(), bytesRead, totalRead);
+    totalRead += bytesRead;
+  }
+
+  return XtcError::OK;
+}
+
+bool XtcParser::isValidXtcFile(const char* filepath) {
+  File file = SD.open(filepath, FILE_READ);
+  if (!file) {
+    return false;
+  }
+
+  uint32_t magic = 0;
+  size_t bytesRead = file.read(reinterpret_cast<uint8_t*>(&magic), sizeof(magic));
+  file.close();
+
+  if (bytesRead != sizeof(magic)) {
+    return false;
+  }
+
+  return (magic == XTC_MAGIC || magic == XTCH_MAGIC);
+}
+
+}  // namespace xtc

lib/Xtc/Xtc/XtcParser.h

@@ -0,0 +1,96 @@
+/**
+ * XtcParser.h
+ *
+ * XTC file parsing and page data extraction
+ * XTC ebook support for CrossPoint Reader
+ */
+
+#pragma once
+
+#include <SD.h>
+
+#include <functional>
+#include <memory>
+#include <string>
+#include <vector>
+
+#include "XtcTypes.h"
+
+namespace xtc {
+
+/**
+ * XTC File Parser
+ *
+ * Reads XTC files from SD card and extracts page data.
+ * Designed for ESP32-C3's limited RAM (~380KB) using streaming.
+ */
+class XtcParser {
+ public:
+  XtcParser();
+  ~XtcParser();
+
+  // File open/close
+  XtcError open(const char* filepath);
+  void close();
+  bool isOpen() const { return m_isOpen; }
+
+  // Header information access
+  const XtcHeader& getHeader() const { return m_header; }
+  uint16_t getPageCount() const { return m_header.pageCount; }
+  uint16_t getWidth() const { return m_defaultWidth; }
+  uint16_t getHeight() const { return m_defaultHeight; }
+  uint8_t getBitDepth() const { return m_bitDepth; }  // 1 = XTC/XTG, 2 = XTCH/XTH
+
+  // Page information
+  bool getPageInfo(uint32_t pageIndex, PageInfo& info) const;
+
+  /**
+   * Load page bitmap (raw 1-bit data, skipping XTG header)
+   *
+   * @param pageIndex Page index (0-based)
+   * @param buffer Output buffer (caller allocated)
+   * @param bufferSize Buffer size
+   * @return Number of bytes read on success, 0 on failure
+   */
+  size_t loadPage(uint32_t pageIndex, uint8_t* buffer, size_t bufferSize);
+
+  /**
+   * Streaming page load
+   * Memory-efficient method that reads page data in chunks.
+   *
+   * @param pageIndex Page index
+   * @param callback Callback function to receive data chunks
+   * @param chunkSize Chunk size (default: 1024 bytes)
+   * @return Error code
+   */
+  XtcError loadPageStreaming(uint32_t pageIndex,
+                             std::function<void(const uint8_t* data, size_t size, size_t offset)> callback,
+                             size_t chunkSize = 1024);
+
+  // Get title from metadata
+  std::string getTitle() const { return m_title; }
+
+  // Validation
+  static bool isValidXtcFile(const char* filepath);
+
+  // Error information
+  XtcError getLastError() const { return m_lastError; }
+
+ private:
+  File m_file;
+  bool m_isOpen;
+  XtcHeader m_header;
+  std::vector<PageInfo> m_pageTable;
+  std::string m_title;
+  uint16_t m_defaultWidth;
+  uint16_t m_defaultHeight;
+  uint8_t m_bitDepth;  // 1 = XTC/XTG (1-bit), 2 = XTCH/XTH (2-bit)
+  XtcError m_lastError;
+
+  // Internal helper functions
+  XtcError readHeader();
+  XtcError readPageTable();
+  XtcError readTitle();
+};
+
+}  // namespace xtc

lib/Xtc/Xtc/XtcTypes.h

@@ -0,0 +1,147 @@
+/**
+ * XtcTypes.h
+ *
+ * XTC file format type definitions
+ * XTC ebook support for CrossPoint Reader
+ *
+ * XTC is the native binary ebook format for XTeink X4 e-reader.
+ * It stores pre-rendered bitmap images per page.
+ *
+ * Format based on EPUB2XTC converter by Rafal-P-Mazur
+ */
+
+#pragma once
+
+#include <cstdint>
+
+namespace xtc {
+
+// XTC file magic numbers (little-endian)
+// "XTC\0" = 0x58, 0x54, 0x43, 0x00
+constexpr uint32_t XTC_MAGIC = 0x00435458;  // "XTC\0" in little-endian (1-bit fast mode)
+// "XTCH" = 0x58, 0x54, 0x43, 0x48
+constexpr uint32_t XTCH_MAGIC = 0x48435458;  // "XTCH" in little-endian (2-bit high quality mode)
+// "XTG\0" = 0x58, 0x54, 0x47, 0x00
+constexpr uint32_t XTG_MAGIC = 0x00475458;  // "XTG\0" for 1-bit page data
+// "XTH\0" = 0x58, 0x54, 0x48, 0x00
+constexpr uint32_t XTH_MAGIC = 0x00485458;  // "XTH\0" for 2-bit page data
+
+// XTeink X4 display resolution
+constexpr uint16_t DISPLAY_WIDTH = 480;
+constexpr uint16_t DISPLAY_HEIGHT = 800;
+
+// XTC file header (56 bytes)
+#pragma pack(push, 1)
+struct XtcHeader {
+  uint32_t magic;            // 0x00: Magic number "XTC\0" (0x00435458)
+  uint16_t version;          // 0x04: Format version (typically 1)
+  uint16_t pageCount;        // 0x06: Total page count
+  uint32_t flags;            // 0x08: Flags/reserved
+  uint32_t headerSize;       // 0x0C: Size of header section (typically 88)
+  uint32_t reserved1;        // 0x10: Reserved
+  uint32_t tocOffset;        // 0x14: TOC offset (0 if unused) - 4 bytes, not 8!
+  uint64_t pageTableOffset;  // 0x18: Page table offset
+  uint64_t dataOffset;       // 0x20: First page data offset
+  uint64_t reserved2;        // 0x28: Reserved
+  uint32_t titleOffset;      // 0x30: Title string offset
+  uint32_t padding;          // 0x34: Padding to 56 bytes
+};
+#pragma pack(pop)
+
+// Page table entry (16 bytes per page)
+#pragma pack(push, 1)
+struct PageTableEntry {
+  uint64_t dataOffset;  // 0x00: Absolute offset to page data
+  uint32_t dataSize;    // 0x08: Page data size in bytes
+  uint16_t width;       // 0x0C: Page width (480)
+  uint16_t height;      // 0x0E: Page height (800)
+};
+#pragma pack(pop)
+
+// XTG/XTH page data header (22 bytes)
+// Used for both 1-bit (XTG) and 2-bit (XTH) formats
+#pragma pack(push, 1)
+struct XtgPageHeader {
+  uint32_t magic;       // 0x00: File identifier (XTG: 0x00475458, XTH: 0x00485458)
+  uint16_t width;       // 0x04: Image width (pixels)
+  uint16_t height;      // 0x06: Image height (pixels)
+  uint8_t colorMode;    // 0x08: Color mode (0=monochrome)
+  uint8_t compression;  // 0x09: Compression (0=uncompressed)
+  uint32_t dataSize;    // 0x0A: Image data size (bytes)
+  uint64_t md5;         // 0x0E: MD5 checksum (first 8 bytes, optional)
+  // Followed by bitmap data at offset 0x16 (22)
+  //
+  // XTG (1-bit): Row-major, 8 pixels/byte, MSB first
+  //   dataSize = ((width + 7) / 8) * height
+  //
+  // XTH (2-bit): Two bit planes, column-major (right-to-left), 8 vertical pixels/byte
+  //   dataSize = ((width * height + 7) / 8) * 2
+  //   First plane: Bit1 for all pixels
+  //   Second plane: Bit2 for all pixels
+  //   pixelValue = (bit1 << 1) | bit2
+};
+#pragma pack(pop)
+
+// Page information (internal use, optimized for memory)
+struct PageInfo {
+  uint32_t offset;   // File offset to page data (max 4GB file size)
+  uint32_t size;     // Data size (bytes)
+  uint16_t width;    // Page width
+  uint16_t height;   // Page height
+  uint8_t bitDepth;  // 1 = XTG (1-bit), 2 = XTH (2-bit grayscale)
+  uint8_t padding;   // Alignment padding
+};  // 16 bytes total
+
+// Error codes
+enum class XtcError {
+  OK = 0,
+  FILE_NOT_FOUND,
+  INVALID_MAGIC,
+  INVALID_VERSION,
+  CORRUPTED_HEADER,
+  PAGE_OUT_OF_RANGE,
+  READ_ERROR,
+  WRITE_ERROR,
+  MEMORY_ERROR,
+  DECOMPRESSION_ERROR,
+};
+
+// Convert error code to string
+inline const char* errorToString(XtcError err) {
+  switch (err) {
+    case XtcError::OK:
+      return "OK";
+    case XtcError::FILE_NOT_FOUND:
+      return "File not found";
+    case XtcError::INVALID_MAGIC:
+      return "Invalid magic number";
+    case XtcError::INVALID_VERSION:
+      return "Unsupported version";
+    case XtcError::CORRUPTED_HEADER:
+      return "Corrupted header";
+    case XtcError::PAGE_OUT_OF_RANGE:
+      return "Page out of range";
+    case XtcError::READ_ERROR:
+      return "Read error";
+    case XtcError::WRITE_ERROR:
+      return "Write error";
+    case XtcError::MEMORY_ERROR:
+      return "Memory allocation error";
+    case XtcError::DECOMPRESSION_ERROR:
+      return "Decompression error";
+    default:
+      return "Unknown error";
+  }
+}
+
+/**
+ * Check if filename has XTC/XTCH extension
+ */
+inline bool isXtcExtension(const char* filename) {
+  if (!filename) return false;
+  const char* ext = strrchr(filename, '.');
+  if (!ext) return false;
+  return (strcasecmp(ext, ".xtc") == 0 || strcasecmp(ext, ".xtch") == 0);
+}
+
+}  // namespace xtc

platformio.ini

@@ -1,9 +1,9 @@
 [platformio]
-crosspoint_version = 0.8.1
+crosspoint_version = 0.10.0
 default_envs = default
 
 [base]
-platform = espressif32
+platform = espressif32 @ 6.12.0
 board = esp32-c3-devkitm-1
 framework = arduino
 monitor_speed = 115200
@@ -40,6 +40,7 @@ lib_deps =
   InputManager=symlink://open-x4-sdk/libs/hardware/InputManager
   EInkDisplay=symlink://open-x4-sdk/libs/display/EInkDisplay
   ArduinoJson @ 7.4.2
+  QRCode @ 0.0.1
 
 [env:default]
 extends = base

src/CrossPointSettings.cpp

@@ -1,31 +1,36 @@
 #include "CrossPointSettings.h"
 
+#include <FsHelpers.h>
 #include <HardwareSerial.h>
 #include <SD.h>
 #include <Serialization.h>
 
-#include <cstdint>
-#include <fstream>
-
 // Initialize the static instance
 CrossPointSettings CrossPointSettings::instance;
 
 namespace {
 constexpr uint8_t SETTINGS_FILE_VERSION = 1;
-constexpr uint8_t SETTINGS_COUNT = 3;
+// Increment this when adding new persisted settings fields
-constexpr char SETTINGS_FILE[] = "/sd/.crosspoint/settings.bin";
+constexpr uint8_t SETTINGS_COUNT = 5;
+constexpr char SETTINGS_FILE[] = "/.crosspoint/settings.bin";
 }  // namespace
 
 bool CrossPointSettings::saveToFile() const {
   // Make sure the directory exists
   SD.mkdir("/.crosspoint");
 
-  std::ofstream outputFile(SETTINGS_FILE);
+  File outputFile;
+  if (!FsHelpers::openFileForWrite("CPS", SETTINGS_FILE, outputFile)) {
+    return false;
+  }
+
   serialization::writePod(outputFile, SETTINGS_FILE_VERSION);
   serialization::writePod(outputFile, SETTINGS_COUNT);
   serialization::writePod(outputFile, sleepScreen);
   serialization::writePod(outputFile, extraParagraphSpacing);
   serialization::writePod(outputFile, shortPwrBtn);
+  serialization::writePod(outputFile, statusBar);
+  serialization::writePod(outputFile, orientation);
   outputFile.close();
 
   Serial.printf("[%lu] [CPS] Settings saved to file\n", millis());
@@ -33,13 +38,11 @@ bool CrossPointSettings::saveToFile() const {
 }
 
 bool CrossPointSettings::loadFromFile() {
-  if (!SD.exists(SETTINGS_FILE + 3)) {  // +3 to skip "/sd" prefix
+  File inputFile;
-    Serial.printf("[%lu] [CPS] Settings file does not exist, using defaults\n", millis());
+  if (!FsHelpers::openFileForRead("CPS", SETTINGS_FILE, inputFile)) {
     return false;
   }
 
-  std::ifstream inputFile(SETTINGS_FILE);
-
   uint8_t version;
   serialization::readPod(inputFile, version);
   if (version != SETTINGS_FILE_VERSION) {
@@ -51,7 +54,7 @@ bool CrossPointSettings::loadFromFile() {
   uint8_t fileSettingsCount = 0;
   serialization::readPod(inputFile, fileSettingsCount);
 
-  // load settings that exist
+  // load settings that exist (support older files with fewer fields)
   uint8_t settingsRead = 0;
   do {
     serialization::readPod(inputFile, sleepScreen);
@@ -60,6 +63,10 @@ bool CrossPointSettings::loadFromFile() {
     if (++settingsRead >= fileSettingsCount) break;
     serialization::readPod(inputFile, shortPwrBtn);
     if (++settingsRead >= fileSettingsCount) break;
+    serialization::readPod(inputFile, statusBar);
+    if (++settingsRead >= fileSettingsCount) break;
+    serialization::readPod(inputFile, orientation);
+    if (++settingsRead >= fileSettingsCount) break;
   } while (false);
 
   inputFile.close();

src/CrossPointSettings.h

@@ -18,12 +18,27 @@ class CrossPointSettings {
   // Should match with SettingsActivity text
   enum SLEEP_SCREEN_MODE { DARK = 0, LIGHT = 1, CUSTOM = 2, COVER = 3 };
 
+  // Status bar display type enum
+  enum STATUS_BAR_MODE { NONE = 0, NO_PROGRESS = 1, FULL = 2 };
+
+  enum ORIENTATION {
+    PORTRAIT = 0,      // 480x800 logical coordinates (current default)
+    LANDSCAPE_CW = 1,  // 800x480 logical coordinates, rotated 180° (swap top/bottom)
+    INVERTED = 2,      // 480x800 logical coordinates, inverted
+    LANDSCAPE_CCW = 3  // 800x480 logical coordinates, native panel orientation
+  };
+
   // Sleep screen settings
   uint8_t sleepScreen = DARK;
+  // Status bar settings
+  uint8_t statusBar = FULL;
   // Text rendering settings
   uint8_t extraParagraphSpacing = 1;
   // Duration of the power button press
   uint8_t shortPwrBtn = 0;
+  // EPUB reading orientation settings
+  // 0 = portrait (default), 1 = landscape clockwise, 2 = inverted, 3 = landscape counter-clockwise
+  uint8_t orientation = PORTRAIT;
 
   ~CrossPointSettings() = default;
 

src/CrossPointState.cpp

@@ -1,20 +1,22 @@
 #include "CrossPointState.h"
 
+#include <FsHelpers.h>
 #include <HardwareSerial.h>
-#include <SD.h>
 #include <Serialization.h>
 
-#include <fstream>
-
 namespace {
 constexpr uint8_t STATE_FILE_VERSION = 1;
-constexpr char STATE_FILE[] = "/sd/.crosspoint/state.bin";
+constexpr char STATE_FILE[] = "/.crosspoint/state.bin";
 }  // namespace
 
 CrossPointState CrossPointState::instance;
 
 bool CrossPointState::saveToFile() const {
-  std::ofstream outputFile(STATE_FILE);
+  File outputFile;
+  if (!FsHelpers::openFileForWrite("CPS", STATE_FILE, outputFile)) {
+    return false;
+  }
+
   serialization::writePod(outputFile, STATE_FILE_VERSION);
   serialization::writeString(outputFile, openEpubPath);
   outputFile.close();
@@ -22,7 +24,10 @@ bool CrossPointState::saveToFile() const {
 }
 
 bool CrossPointState::loadFromFile() {
-  std::ifstream inputFile(STATE_FILE);
+  File inputFile;
+  if (!FsHelpers::openFileForRead("CPS", STATE_FILE, inputFile)) {
+    return false;
+  }
 
   uint8_t version;
   serialization::readPod(inputFile, version);

src/WifiCredentialStore.cpp

@@ -1,11 +1,10 @@
 #include "WifiCredentialStore.h"
 
+#include <FsHelpers.h>
 #include <HardwareSerial.h>
 #include <SD.h>
 #include <Serialization.h>
 
-#include <fstream>
-
 // Initialize the static instance
 WifiCredentialStore WifiCredentialStore::instance;
 
@@ -14,7 +13,7 @@ namespace {
 constexpr uint8_t WIFI_FILE_VERSION = 1;
 
 // WiFi credentials file path
-constexpr char WIFI_FILE[] = "/sd/.crosspoint/wifi.bin";
+constexpr char WIFI_FILE[] = "/.crosspoint/wifi.bin";
 
 // Obfuscation key - "CrossPoint" in ASCII
 // This is NOT cryptographic security, just prevents casual file reading
@@ -33,9 +32,8 @@ bool WifiCredentialStore::saveToFile() const {
   // Make sure the directory exists
   SD.mkdir("/.crosspoint");
 
-  std::ofstream file(WIFI_FILE, std::ios::binary);
+  File file;
-  if (!file) {
+  if (!FsHelpers::openFileForWrite("WCS", WIFI_FILE, file)) {
-    Serial.printf("[%lu] [WCS] Failed to open wifi.bin for writing\n", millis());
     return false;
   }
 
@@ -62,14 +60,8 @@ bool WifiCredentialStore::saveToFile() const {
 }
 
 bool WifiCredentialStore::loadFromFile() {
-  if (!SD.exists(WIFI_FILE + 3)) {  // +3 to skip "/sd" prefix
+  File file;
-    Serial.printf("[%lu] [WCS] WiFi credentials file does not exist\n", millis());
+  if (!FsHelpers::openFileForRead("WCS", WIFI_FILE, file)) {
-    return false;
-  }
-
-  std::ifstream file(WIFI_FILE, std::ios::binary);
-  if (!file) {
-    Serial.printf("[%lu] [WCS] Failed to open wifi.bin for reading\n", millis());
     return false;
   }
 

src/activities/boot_sleep/BootActivity.cpp

@@ -8,11 +8,11 @@
 void BootActivity::onEnter() {
   Activity::onEnter();
 
-  const auto pageWidth = GfxRenderer::getScreenWidth();
+  const auto pageWidth = renderer.getScreenWidth();
-  const auto pageHeight = GfxRenderer::getScreenHeight();
+  const auto pageHeight = renderer.getScreenHeight();
 
   renderer.clearScreen();
-  renderer.drawImage(CrossLarge, (pageWidth - 128) / 2, (pageHeight - 128) / 2, 128, 128);
+  renderer.drawImage(CrossLarge, (pageWidth + 128) / 2, (pageHeight - 128) / 2, 128, 128);
   renderer.drawCenteredText(UI_FONT_ID, pageHeight / 2 + 70, "CrossPoint", true, BOLD);
   renderer.drawCenteredText(SMALL_FONT_ID, pageHeight / 2 + 95, "BOOTING");
   renderer.drawCenteredText(SMALL_FONT_ID, pageHeight - 30, CROSSPOINT_VERSION);

src/activities/boot_sleep/SleepActivity.cpp

@@ -1,8 +1,10 @@
 #include "SleepActivity.h"
 
 #include <Epub.h>
+#include <FsHelpers.h>
 #include <GfxRenderer.h>
 #include <SD.h>
+#include <Xtc.h>
 
 #include <vector>
 
@@ -11,6 +13,20 @@
 #include "config.h"
 #include "images/CrossLarge.h"
 
+namespace {
+// Check if path has XTC extension (.xtc or .xtch)
+bool isXtcFile(const std::string& path) {
+  if (path.length() < 4) return false;
+  std::string ext4 = path.substr(path.length() - 4);
+  if (ext4 == ".xtc") return true;
+  if (path.length() >= 5) {
+    std::string ext5 = path.substr(path.length() - 5);
+    if (ext5 == ".xtch") return true;
+  }
+  return false;
+}
+}  // namespace
+
 void SleepActivity::onEnter() {
   Activity::onEnter();
   renderPopup("Entering Sleep...");
@@ -76,8 +92,8 @@ void SleepActivity::renderCustomSleepScreen() const {
       // Generate a random number between 1 and numFiles
       const auto randomFileIndex = random(numFiles);
       const auto filename = "/sleep/" + files[randomFileIndex];
-      auto file = SD.open(filename.c_str());
+      File file;
-      if (file) {
+      if (FsHelpers::openFileForRead("SLP", filename, file)) {
         Serial.printf("[%lu] [SLP] Randomly loading: /sleep/%s\n", millis(), files[randomFileIndex].c_str());
         delay(100);
         Bitmap bitmap(file);
@@ -93,8 +109,8 @@ void SleepActivity::renderCustomSleepScreen() const {
 
   // Look for sleep.bmp on the root of the sd card to determine if we should
   // render a custom sleep screen instead of the default.
-  auto file = SD.open("/sleep.bmp");
+  File file;
-  if (file) {
+  if (FsHelpers::openFileForRead("SLP", "/sleep.bmp", file)) {
     Bitmap bitmap(file);
     if (bitmap.parseHeaders() == BmpReaderError::Ok) {
       Serial.printf("[%lu] [SLP] Loading: /sleep.bmp\n", millis());
@@ -111,7 +127,7 @@ void SleepActivity::renderDefaultSleepScreen() const {
   const auto pageHeight = renderer.getScreenHeight();
 
   renderer.clearScreen();
-  renderer.drawImage(CrossLarge, (pageWidth - 128) / 2, (pageHeight - 128) / 2, 128, 128);
+  renderer.drawImage(CrossLarge, (pageWidth + 128) / 2, (pageHeight - 128) / 2, 128, 128);
   renderer.drawCenteredText(UI_FONT_ID, pageHeight / 2 + 70, "CrossPoint", true, BOLD);
   renderer.drawCenteredText(SMALL_FONT_ID, pageHeight / 2 + 95, "SLEEPING");
 
@@ -175,19 +191,41 @@ void SleepActivity::renderCoverSleepScreen() const {
     return renderDefaultSleepScreen();
   }
 
-  Epub lastEpub(APP_STATE.openEpubPath, "/.crosspoint");
+  std::string coverBmpPath;
-  if (!lastEpub.load()) {
+
-    Serial.println("[SLP] Failed to load last epub");
+  // Check if the current book is XTC or EPUB
-    return renderDefaultSleepScreen();
+  if (isXtcFile(APP_STATE.openEpubPath)) {
+    // Handle XTC file
+    Xtc lastXtc(APP_STATE.openEpubPath, "/.crosspoint");
+    if (!lastXtc.load()) {
+      Serial.println("[SLP] Failed to load last XTC");
+      return renderDefaultSleepScreen();
+    }
+
+    if (!lastXtc.generateCoverBmp()) {
+      Serial.println("[SLP] Failed to generate XTC cover bmp");
+      return renderDefaultSleepScreen();
+    }
+
+    coverBmpPath = lastXtc.getCoverBmpPath();
+  } else {
+    // Handle EPUB file
+    Epub lastEpub(APP_STATE.openEpubPath, "/.crosspoint");
+    if (!lastEpub.load()) {
+      Serial.println("[SLP] Failed to load last epub");
+      return renderDefaultSleepScreen();
+    }
+
+    if (!lastEpub.generateCoverBmp()) {
+      Serial.println("[SLP] Failed to generate cover bmp");
+      return renderDefaultSleepScreen();
+    }
+
+    coverBmpPath = lastEpub.getCoverBmpPath();
   }
 
-  if (!lastEpub.generateCoverBmp()) {
+  File file;
-    Serial.println("[SLP] Failed to generate cover bmp");
+  if (FsHelpers::openFileForRead("SLP", coverBmpPath, file)) {
-    return renderDefaultSleepScreen();
-  }
-
-  auto file = SD.open(lastEpub.getCoverBmpPath().c_str(), FILE_READ);
-  if (file) {
     Bitmap bitmap(file);
     if (bitmap.parseHeaders() == BmpReaderError::Ok) {
       renderBitmapSleepScreen(bitmap);

src/activities/home/HomeActivity.cpp

@@ -4,22 +4,24 @@
 #include <InputManager.h>
 #include <SD.h>
 
+#include "CrossPointState.h"
 #include "config.h"
 
-namespace {
-constexpr int menuItemCount = 3;
-}
-
 void HomeActivity::taskTrampoline(void* param) {
   auto* self = static_cast<HomeActivity*>(param);
   self->displayTaskLoop();
 }
 
+int HomeActivity::getMenuItemCount() const { return hasContinueReading ? 4 : 3; }
+
 void HomeActivity::onEnter() {
   Activity::onEnter();
 
   renderingMutex = xSemaphoreCreateMutex();
 
+  // Check if we have a book to continue reading
+  hasContinueReading = !APP_STATE.openEpubPath.empty() && SD.exists(APP_STATE.openEpubPath.c_str());
+
   selectorIndex = 0;
 
   // Trigger first update
@@ -52,19 +54,35 @@ void HomeActivity::loop() {
   const bool nextPressed =
       inputManager.wasPressed(InputManager::BTN_DOWN) || inputManager.wasPressed(InputManager::BTN_RIGHT);
 
-  if (inputManager.wasPressed(InputManager::BTN_CONFIRM)) {
+  const int menuCount = getMenuItemCount();
-    if (selectorIndex == 0) {
+
-      onReaderOpen();
+  if (inputManager.wasReleased(InputManager::BTN_CONFIRM)) {
-    } else if (selectorIndex == 1) {
+    if (hasContinueReading) {
-      onFileTransferOpen();
+      // Menu: Continue Reading, Browse, File transfer, Settings
-    } else if (selectorIndex == 2) {
+      if (selectorIndex == 0) {
-      onSettingsOpen();
+        onContinueReading();
+      } else if (selectorIndex == 1) {
+        onReaderOpen();
+      } else if (selectorIndex == 2) {
+        onFileTransferOpen();
+      } else if (selectorIndex == 3) {
+        onSettingsOpen();
+      }
+    } else {
+      // Menu: Browse, File transfer, Settings
+      if (selectorIndex == 0) {
+        onReaderOpen();
+      } else if (selectorIndex == 1) {
+        onFileTransferOpen();
+      } else if (selectorIndex == 2) {
+        onSettingsOpen();
+      }
     }
   } else if (prevPressed) {
-    selectorIndex = (selectorIndex + menuItemCount - 1) % menuItemCount;
+    selectorIndex = (selectorIndex + menuCount - 1) % menuCount;
     updateRequired = true;
   } else if (nextPressed) {
-    selectorIndex = (selectorIndex + 1) % menuItemCount;
+    selectorIndex = (selectorIndex + 1) % menuCount;
     updateRequired = true;
   }
 }
@@ -85,27 +103,47 @@ void HomeActivity::render() const {
   renderer.clearScreen();
 
   const auto pageWidth = renderer.getScreenWidth();
-  const auto pageHeight = renderer.getScreenHeight();
   renderer.drawCenteredText(READER_FONT_ID, 10, "CrossPoint Reader", true, BOLD);
 
   // Draw selection
-  renderer.fillRect(0, 60 + selectorIndex * 30 + 2, pageWidth - 1, 30);
+  renderer.fillRect(0, 60 + selectorIndex * 30 - 2, pageWidth - 1, 30);
-  renderer.drawText(UI_FONT_ID, 20, 60, "Read", selectorIndex != 0);
-  renderer.drawText(UI_FONT_ID, 20, 90, "File transfer", selectorIndex != 1);
-  renderer.drawText(UI_FONT_ID, 20, 120, "Settings", selectorIndex != 2);
 
-  renderer.drawRect(25, pageHeight - 40, 106, 40);
+  int menuY = 60;
-  renderer.drawText(UI_FONT_ID, 25 + (105 - renderer.getTextWidth(UI_FONT_ID, "Back")) / 2, pageHeight - 35, "Back");
+  int menuIndex = 0;
 
-  renderer.drawRect(130, pageHeight - 40, 106, 40);
+  if (hasContinueReading) {
-  renderer.drawText(UI_FONT_ID, 130 + (105 - renderer.getTextWidth(UI_FONT_ID, "Confirm")) / 2, pageHeight - 35,
+    // Extract filename from path for display
-                    "Confirm");
+    std::string bookName = APP_STATE.openEpubPath;
+    const size_t lastSlash = bookName.find_last_of('/');
+    if (lastSlash != std::string::npos) {
+      bookName = bookName.substr(lastSlash + 1);
+    }
+    // Remove .epub extension
+    if (bookName.length() > 5 && bookName.substr(bookName.length() - 5) == ".epub") {
+      bookName.resize(bookName.length() - 5);
+    }
+    // Truncate if too long
+    if (bookName.length() > 25) {
+      bookName.resize(22);
+      bookName += "...";
+    }
+    std::string continueLabel = "Continue: " + bookName;
+    renderer.drawText(UI_FONT_ID, 20, menuY, continueLabel.c_str(), selectorIndex != menuIndex);
+    menuY += 30;
+    menuIndex++;
+  }
 
-  renderer.drawRect(245, pageHeight - 40, 106, 40);
+  renderer.drawText(UI_FONT_ID, 20, menuY, "Browse", selectorIndex != menuIndex);
-  renderer.drawText(UI_FONT_ID, 245 + (105 - renderer.getTextWidth(UI_FONT_ID, "Left")) / 2, pageHeight - 35, "Left");
+  menuY += 30;
+  menuIndex++;
 
-  renderer.drawRect(350, pageHeight - 40, 106, 40);
+  renderer.drawText(UI_FONT_ID, 20, menuY, "File transfer", selectorIndex != menuIndex);
-  renderer.drawText(UI_FONT_ID, 350 + (105 - renderer.getTextWidth(UI_FONT_ID, "Right")) / 2, pageHeight - 35, "Right");
+  menuY += 30;
+  menuIndex++;
+
+  renderer.drawText(UI_FONT_ID, 20, menuY, "Settings", selectorIndex != menuIndex);
+
+  renderer.drawButtonHints(UI_FONT_ID, "Back", "Confirm", "Left", "Right");
 
   renderer.displayBuffer();
 }

src/activities/home/HomeActivity.h

@@ -12,6 +12,8 @@ class HomeActivity final : public Activity {
   SemaphoreHandle_t renderingMutex = nullptr;
   int selectorIndex = 0;
   bool updateRequired = false;
+  bool hasContinueReading = false;
+  const std::function<void()> onContinueReading;
   const std::function<void()> onReaderOpen;
   const std::function<void()> onSettingsOpen;
   const std::function<void()> onFileTransferOpen;
@@ -19,11 +21,14 @@ class HomeActivity final : public Activity {
   static void taskTrampoline(void* param);
   [[noreturn]] void displayTaskLoop();
   void render() const;
+  int getMenuItemCount() const;
 
  public:
-  explicit HomeActivity(GfxRenderer& renderer, InputManager& inputManager, const std::function<void()>& onReaderOpen,
+  explicit HomeActivity(GfxRenderer& renderer, InputManager& inputManager,
+                        const std::function<void()>& onContinueReading, const std::function<void()>& onReaderOpen,
                         const std::function<void()>& onSettingsOpen, const std::function<void()>& onFileTransferOpen)
       : Activity("Home", renderer, inputManager),
+        onContinueReading(onContinueReading),
         onReaderOpen(onReaderOpen),
         onSettingsOpen(onSettingsOpen),
         onFileTransferOpen(onFileTransferOpen) {}

src/activities/network/CrossPointWebServerActivity.cpp

@@ -1,12 +1,31 @@
 #include "CrossPointWebServerActivity.h"
 
+#include <DNSServer.h>
+#include <ESPmDNS.h>
 #include <GfxRenderer.h>
 #include <InputManager.h>
 #include <WiFi.h>
+#include <qrcode.h>
 
+#include <cstddef>
+
+#include "NetworkModeSelectionActivity.h"
 #include "WifiSelectionActivity.h"
 #include "config.h"
 
+namespace {
+// AP Mode configuration
+constexpr const char* AP_SSID = "CrossPoint-Reader";
+constexpr const char* AP_PASSWORD = nullptr;  // Open network for ease of use
+constexpr const char* AP_HOSTNAME = "crosspoint";
+constexpr uint8_t AP_CHANNEL = 1;
+constexpr uint8_t AP_MAX_CONNECTIONS = 4;
+
+// DNS server for captive portal (redirects all DNS queries to our IP)
+DNSServer* dnsServer = nullptr;
+constexpr uint16_t DNS_PORT = 53;
+}  // namespace
+
 void CrossPointWebServerActivity::taskTrampoline(void* param) {
   auto* self = static_cast<CrossPointWebServerActivity*>(param);
   self->displayTaskLoop();
@@ -20,7 +39,9 @@ void CrossPointWebServerActivity::onEnter() {
   renderingMutex = xSemaphoreCreateMutex();
 
   // Reset state
-  state = WebServerActivityState::WIFI_SELECTION;
+  state = WebServerActivityState::MODE_SELECTION;
+  networkMode = NetworkMode::JOIN_NETWORK;
+  isApMode = false;
   connectedIP.clear();
   connectedSSID.clear();
   lastHandleClientTime = 0;
@@ -33,14 +54,12 @@ void CrossPointWebServerActivity::onEnter() {
               &displayTaskHandle  // Task handle
   );
 
-  // Turn on WiFi immediately
+  // Launch network mode selection subactivity
-  Serial.printf("[%lu] [WEBACT] Turning on WiFi...\n", millis());
+  Serial.printf("[%lu] [WEBACT] Launching NetworkModeSelectionActivity...\n", millis());
-  WiFi.mode(WIFI_STA);
+  enterNewActivity(new NetworkModeSelectionActivity(
-
+      renderer, inputManager, [this](const NetworkMode mode) { onNetworkModeSelected(mode); },
-  // Launch WiFi selection subactivity
+      [this]() { onGoBack(); }  // Cancel goes back to home
-  Serial.printf("[%lu] [WEBACT] Launching WifiSelectionActivity...\n", millis());
+      ));
-  enterNewActivity(new WifiSelectionActivity(renderer, inputManager,
-                                             [this](const bool connected) { onWifiSelectionComplete(connected); }));
 }
 
 void CrossPointWebServerActivity::onExit() {
@@ -53,14 +72,30 @@ void CrossPointWebServerActivity::onExit() {
   // Stop the web server first (before disconnecting WiFi)
   stopWebServer();
 
+  // Stop mDNS
+  MDNS.end();
+
+  // Stop DNS server if running (AP mode)
+  if (dnsServer) {
+    Serial.printf("[%lu] [WEBACT] Stopping DNS server...\n", millis());
+    dnsServer->stop();
+    delete dnsServer;
+    dnsServer = nullptr;
+  }
+
   // CRITICAL: Wait for LWIP stack to flush any pending packets
   Serial.printf("[%lu] [WEBACT] Waiting 500ms for network stack to flush pending packets...\n", millis());
   delay(500);
 
   // Disconnect WiFi gracefully
-  Serial.printf("[%lu] [WEBACT] Disconnecting WiFi (graceful)...\n", millis());
+  if (isApMode) {
-  WiFi.disconnect(false);  // false = don't erase credentials, send disconnect frame
+    Serial.printf("[%lu] [WEBACT] Stopping WiFi AP...\n", millis());
-  delay(100);              // Allow disconnect frame to be sent
+    WiFi.softAPdisconnect(true);
+  } else {
+    Serial.printf("[%lu] [WEBACT] Disconnecting WiFi (graceful)...\n", millis());
+    WiFi.disconnect(false);  // false = don't erase credentials, send disconnect frame
+  }
+  delay(100);  // Allow disconnect frame to be sent
 
   Serial.printf("[%lu] [WEBACT] Setting WiFi mode OFF...\n", millis());
   WiFi.mode(WIFI_OFF);
@@ -89,6 +124,33 @@ void CrossPointWebServerActivity::onExit() {
   Serial.printf("[%lu] [WEBACT] [MEM] Free heap at onExit end: %d bytes\n", millis(), ESP.getFreeHeap());
 }
 
+void CrossPointWebServerActivity::onNetworkModeSelected(const NetworkMode mode) {
+  Serial.printf("[%lu] [WEBACT] Network mode selected: %s\n", millis(),
+                mode == NetworkMode::JOIN_NETWORK ? "Join Network" : "Create Hotspot");
+
+  networkMode = mode;
+  isApMode = (mode == NetworkMode::CREATE_HOTSPOT);
+
+  // Exit mode selection subactivity
+  exitActivity();
+
+  if (mode == NetworkMode::JOIN_NETWORK) {
+    // STA mode - launch WiFi selection
+    Serial.printf("[%lu] [WEBACT] Turning on WiFi (STA mode)...\n", millis());
+    WiFi.mode(WIFI_STA);
+
+    state = WebServerActivityState::WIFI_SELECTION;
+    Serial.printf("[%lu] [WEBACT] Launching WifiSelectionActivity...\n", millis());
+    enterNewActivity(new WifiSelectionActivity(renderer, inputManager,
+                                               [this](const bool connected) { onWifiSelectionComplete(connected); }));
+  } else {
+    // AP mode - start access point
+    state = WebServerActivityState::AP_STARTING;
+    updateRequired = true;
+    startAccessPoint();
+  }
+}
+
 void CrossPointWebServerActivity::onWifiSelectionComplete(const bool connected) {
   Serial.printf("[%lu] [WEBACT] WifiSelectionActivity completed, connected=%d\n", millis(), connected);
 
@@ -96,17 +158,83 @@ void CrossPointWebServerActivity::onWifiSelectionComplete(const bool connected)
     // Get connection info before exiting subactivity
     connectedIP = static_cast<WifiSelectionActivity*>(subActivity.get())->getConnectedIP();
     connectedSSID = WiFi.SSID().c_str();
+    isApMode = false;
 
     exitActivity();
 
+    // Start mDNS for hostname resolution
+    if (MDNS.begin(AP_HOSTNAME)) {
+      Serial.printf("[%lu] [WEBACT] mDNS started: http://%s.local/\n", millis(), AP_HOSTNAME);
+    }
+
     // Start the web server
     startWebServer();
   } else {
-    // User cancelled - go back
+    // User cancelled - go back to mode selection
-    onGoBack();
+    exitActivity();
+    state = WebServerActivityState::MODE_SELECTION;
+    enterNewActivity(new NetworkModeSelectionActivity(
+        renderer, inputManager, [this](const NetworkMode mode) { onNetworkModeSelected(mode); },
+        [this]() { onGoBack(); }));
   }
 }
 
+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());
+
+  // Configure and start the AP
+  WiFi.mode(WIFI_AP);
+  delay(100);
+
+  // Start soft AP
+  bool apStarted;
+  if (AP_PASSWORD && strlen(AP_PASSWORD) >= 8) {
+    apStarted = WiFi.softAP(AP_SSID, AP_PASSWORD, AP_CHANNEL, false, AP_MAX_CONNECTIONS);
+  } else {
+    // Open network (no password)
+    apStarted = WiFi.softAP(AP_SSID, nullptr, AP_CHANNEL, false, AP_MAX_CONNECTIONS);
+  }
+
+  if (!apStarted) {
+    Serial.printf("[%lu] [WEBACT] ERROR: Failed to start Access Point!\n", millis());
+    onGoBack();
+    return;
+  }
+
+  delay(100);  // Wait for AP to fully initialize
+
+  // Get AP IP address
+  const IPAddress apIP = WiFi.softAPIP();
+  char ipStr[16];
+  snprintf(ipStr, sizeof(ipStr), "%d.%d.%d.%d", apIP[0], apIP[1], apIP[2], apIP[3]);
+  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());
+
+  // Start mDNS for hostname resolution
+  if (MDNS.begin(AP_HOSTNAME)) {
+    Serial.printf("[%lu] [WEBACT] mDNS started: http://%s.local/\n", millis(), AP_HOSTNAME);
+  } else {
+    Serial.printf("[%lu] [WEBACT] WARNING: mDNS failed to start\n", millis());
+  }
+
+  // Start DNS server for captive portal behavior
+  // This redirects all DNS queries to our IP, making any domain typed resolve to us
+  dnsServer = new DNSServer();
+  dnsServer->setErrorReplyCode(DNSReplyCode::NoError);
+  dnsServer->start(DNS_PORT, "*", apIP);
+  Serial.printf("[%lu] [WEBACT] DNS server started for captive portal\n", millis());
+
+  Serial.printf("[%lu] [WEBACT] [MEM] Free heap after AP start: %d bytes\n", millis(), ESP.getFreeHeap());
+
+  // Start the web server
+  startWebServer();
+}
+
 void CrossPointWebServerActivity::startWebServer() {
   Serial.printf("[%lu] [WEBACT] Starting web server...\n", millis());
 
@@ -150,6 +278,11 @@ void CrossPointWebServerActivity::loop() {
 
   // Handle different states
   if (state == WebServerActivityState::SERVER_RUNNING) {
+    // Handle DNS requests for captive portal (AP mode only)
+    if (isApMode && dnsServer) {
+      dnsServer->processNextRequest();
+    }
+
     // Handle web server requests - call handleClient multiple times per loop
     // to improve responsiveness and upload throughput
     if (webServer && webServer->isRunning()) {
@@ -193,35 +326,107 @@ void CrossPointWebServerActivity::displayTaskLoop() {
 
 void CrossPointWebServerActivity::render() const {
   // Only render our own UI when server is running
-  // WiFi selection handles its own rendering
+  // Subactivities handle their own rendering
   if (state == WebServerActivityState::SERVER_RUNNING) {
     renderer.clearScreen();
     renderServerRunning();
     renderer.displayBuffer();
+  } else if (state == WebServerActivityState::AP_STARTING) {
+    renderer.clearScreen();
+    const auto pageHeight = renderer.getScreenHeight();
+    renderer.drawCenteredText(READER_FONT_ID, pageHeight / 2 - 20, "Starting Hotspot...", true, BOLD);
+    renderer.displayBuffer();
+  }
+}
+
+void drawQRCode(const GfxRenderer& renderer, const int x, const int y, const std::string& data) {
+  // Implementation of QR code calculation
+  // 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());
+
+  qrcode_initText(&qrcode, qrcodeBytes, 4, ECC_LOW, data.c_str());
+  const uint8_t px = 6;  // pixels per module
+  for (uint8_t cy = 0; cy < qrcode.size; cy++) {
+    for (uint8_t cx = 0; cx < qrcode.size; cx++) {
+      if (qrcode_getModule(&qrcode, cx, cy)) {
+        // Serial.print("**");
+        renderer.fillRect(x + px * cx, y + px * cy, px, px, true);
+      } else {
+        // Serial.print("  ");
+      }
+    }
+    // Serial.print("\n");
   }
 }
 
 void CrossPointWebServerActivity::renderServerRunning() const {
-  const auto pageHeight = renderer.getScreenHeight();
+  // Use consistent line spacing
-  const auto height = renderer.getLineHeight(UI_FONT_ID);
+  constexpr int LINE_SPACING = 28;  // Space between lines
-  const auto top = (pageHeight - height * 5) / 2;
 
-  renderer.drawCenteredText(READER_FONT_ID, top - 30, "File Transfer", true, BOLD);
+  renderer.drawCenteredText(READER_FONT_ID, 15, "File Transfer", true, BOLD);
 
-  std::string ssidInfo = "Network: " + connectedSSID;
+  if (isApMode) {
-  if (ssidInfo.length() > 28) {
+    // AP mode display - center the content block
-    ssidInfo.replace(25, ssidInfo.length() - 25, "...");
+    int startY = 55;
+
+    renderer.drawCenteredText(UI_FONT_ID, startY, "Hotspot Mode", true, BOLD);
+
+    std::string ssidInfo = "Network: " + connectedSSID;
+    renderer.drawCenteredText(UI_FONT_ID, startY + LINE_SPACING, ssidInfo.c_str(), true, REGULAR);
+
+    renderer.drawCenteredText(SMALL_FONT_ID, startY + LINE_SPACING * 2, "Connect your device to this WiFi network",
+                              true, REGULAR);
+
+    renderer.drawCenteredText(SMALL_FONT_ID, startY + LINE_SPACING * 3,
+                              "or scan QR code with your phone to connect to Wifi.", true, REGULAR);
+    // Show QR code for URL
+    std::string wifiConfig = std::string("WIFI:T:WPA;S:") + connectedSSID + ";P:" + "" + ";;";
+    drawQRCode(renderer, (480 - 6 * 33) / 2, startY + LINE_SPACING * 4, wifiConfig);
+
+    startY += 6 * 29 + 3 * LINE_SPACING;
+    // Show primary URL (hostname)
+    std::string hostnameUrl = std::string("http://") + AP_HOSTNAME + ".local/";
+    renderer.drawCenteredText(UI_FONT_ID, startY + LINE_SPACING * 3, hostnameUrl.c_str(), true, BOLD);
+
+    // Show IP address as fallback
+    std::string ipUrl = "or http://" + connectedIP + "/";
+    renderer.drawCenteredText(SMALL_FONT_ID, startY + LINE_SPACING * 4, ipUrl.c_str(), true, REGULAR);
+    renderer.drawCenteredText(SMALL_FONT_ID, startY + LINE_SPACING * 5, "Open this URL in your browser", true, REGULAR);
+
+    // Show QR code for URL
+    renderer.drawCenteredText(SMALL_FONT_ID, startY + LINE_SPACING * 6, "or scan QR code with your phone:", true,
+                              REGULAR);
+    drawQRCode(renderer, (480 - 6 * 33) / 2, startY + LINE_SPACING * 7, hostnameUrl);
+  } else {
+    // STA mode display (original behavior)
+    const int startY = 65;
+
+    std::string ssidInfo = "Network: " + connectedSSID;
+    if (ssidInfo.length() > 28) {
+      ssidInfo.replace(25, ssidInfo.length() - 25, "...");
+    }
+    renderer.drawCenteredText(UI_FONT_ID, startY, ssidInfo.c_str(), true, REGULAR);
+
+    std::string ipInfo = "IP Address: " + connectedIP;
+    renderer.drawCenteredText(UI_FONT_ID, startY + LINE_SPACING, ipInfo.c_str(), true, REGULAR);
+
+    // Show web server URL prominently
+    std::string webInfo = "http://" + connectedIP + "/";
+    renderer.drawCenteredText(UI_FONT_ID, startY + LINE_SPACING * 2, webInfo.c_str(), true, BOLD);
+
+    // Also show hostname URL
+    std::string hostnameUrl = std::string("or http://") + AP_HOSTNAME + ".local/";
+    renderer.drawCenteredText(SMALL_FONT_ID, startY + LINE_SPACING * 3, hostnameUrl.c_str(), true, REGULAR);
+
+    renderer.drawCenteredText(SMALL_FONT_ID, startY + LINE_SPACING * 4, "Open this URL in your browser", true, REGULAR);
+
+    // Show QR code for URL
+    drawQRCode(renderer, (480 - 6 * 33) / 2, startY + LINE_SPACING * 6, webInfo);
+    renderer.drawCenteredText(SMALL_FONT_ID, startY + LINE_SPACING * 5, "or scan QR code with your phone:", true,
+                              REGULAR);
   }
-  renderer.drawCenteredText(UI_FONT_ID, top + 10, ssidInfo.c_str(), true, REGULAR);
 
-  std::string ipInfo = "IP Address: " + connectedIP;
+  renderer.drawButtonHints(UI_FONT_ID, "« Exit", "", "", "");
-  renderer.drawCenteredText(UI_FONT_ID, top + 40, ipInfo.c_str(), true, REGULAR);
-
-  // Show web server URL prominently
-  std::string webInfo = "http://" + connectedIP + "/";
-  renderer.drawCenteredText(UI_FONT_ID, top + 70, webInfo.c_str(), true, BOLD);
-
-  renderer.drawCenteredText(SMALL_FONT_ID, top + 110, "Open this URL in your browser", true, REGULAR);
-
-  renderer.drawCenteredText(SMALL_FONT_ID, pageHeight - 30, "Press BACK to exit", true, REGULAR);
 }

src/activities/network/CrossPointWebServerActivity.h

@@ -7,12 +7,15 @@
 #include <memory>
 #include <string>
 
+#include "NetworkModeSelectionActivity.h"
 #include "activities/ActivityWithSubactivity.h"
 #include "network/CrossPointWebServer.h"
 
 // Web server activity states
 enum class WebServerActivityState {
-  WIFI_SELECTION,  // WiFi selection subactivity is active
+  MODE_SELECTION,  // Choosing between Join Network and Create Hotspot
+  WIFI_SELECTION,  // WiFi selection subactivity is active (for Join Network mode)
+  AP_STARTING,     // Starting Access Point mode
   SERVER_RUNNING,  // Web server is running and handling requests
   SHUTTING_DOWN    // Shutting down server and WiFi
 };
@@ -20,8 +23,10 @@ enum class WebServerActivityState {
 /**
  * CrossPointWebServerActivity is the entry point for file transfer functionality.
  * It:
- * - Immediately turns on WiFi and launches WifiSelectionActivity on enter
+ * - First presents a choice between "Join a Network" (STA) and "Create Hotspot" (AP)
- * - When WifiSelectionActivity completes successfully, starts the CrossPointWebServer
+ * - For STA mode: Launches WifiSelectionActivity to connect to an existing network
+ * - For AP mode: Creates an Access Point that clients can connect to
+ * - Starts the CrossPointWebServer when connected
  * - Handles client requests in its loop() function
  * - Cleans up the server and shuts down WiFi on exit
  */
@@ -29,15 +34,19 @@ class CrossPointWebServerActivity final : public ActivityWithSubactivity {
   TaskHandle_t displayTaskHandle = nullptr;
   SemaphoreHandle_t renderingMutex = nullptr;
   bool updateRequired = false;
-  WebServerActivityState state = WebServerActivityState::WIFI_SELECTION;
+  WebServerActivityState state = WebServerActivityState::MODE_SELECTION;
   const std::function<void()> onGoBack;
 
+  // Network mode
+  NetworkMode networkMode = NetworkMode::JOIN_NETWORK;
+  bool isApMode = false;
+
   // Web server - owned by this activity
   std::unique_ptr<CrossPointWebServer> webServer;
 
   // Server status
   std::string connectedIP;
-  std::string connectedSSID;
+  std::string connectedSSID;  // For STA mode: network name, For AP mode: AP name
 
   // Performance monitoring
   unsigned long lastHandleClientTime = 0;
@@ -47,7 +56,9 @@ class CrossPointWebServerActivity final : public ActivityWithSubactivity {
   void render() const;
   void renderServerRunning() const;
 
+  void onNetworkModeSelected(NetworkMode mode);
   void onWifiSelectionComplete(bool connected);
+  void startAccessPoint();
   void startWebServer();
   void stopWebServer();
 

src/activities/network/NetworkModeSelectionActivity.cpp

@@ -0,0 +1,128 @@
+#include "NetworkModeSelectionActivity.h"
+
+#include <GfxRenderer.h>
+#include <InputManager.h>
+
+#include "config.h"
+
+namespace {
+constexpr int MENU_ITEM_COUNT = 2;
+const char* MENU_ITEMS[MENU_ITEM_COUNT] = {"Join a Network", "Create Hotspot"};
+const char* MENU_DESCRIPTIONS[MENU_ITEM_COUNT] = {"Connect to an existing WiFi network",
+                                                  "Create a WiFi network others can join"};
+}  // namespace
+
+void NetworkModeSelectionActivity::taskTrampoline(void* param) {
+  auto* self = static_cast<NetworkModeSelectionActivity*>(param);
+  self->displayTaskLoop();
+}
+
+void NetworkModeSelectionActivity::onEnter() {
+  Activity::onEnter();
+
+  renderingMutex = xSemaphoreCreateMutex();
+
+  // Reset selection
+  selectedIndex = 0;
+
+  // Trigger first update
+  updateRequired = true;
+
+  xTaskCreate(&NetworkModeSelectionActivity::taskTrampoline, "NetworkModeTask",
+              2048,               // Stack size
+              this,               // Parameters
+              1,                  // Priority
+              &displayTaskHandle  // Task handle
+  );
+}
+
+void NetworkModeSelectionActivity::onExit() {
+  Activity::onExit();
+
+  // Wait until not rendering to delete task
+  xSemaphoreTake(renderingMutex, portMAX_DELAY);
+  if (displayTaskHandle) {
+    vTaskDelete(displayTaskHandle);
+    displayTaskHandle = nullptr;
+  }
+  vSemaphoreDelete(renderingMutex);
+  renderingMutex = nullptr;
+}
+
+void NetworkModeSelectionActivity::loop() {
+  // Handle back button - cancel
+  if (inputManager.wasPressed(InputManager::BTN_BACK)) {
+    onCancel();
+    return;
+  }
+
+  // Handle confirm button - select current option
+  if (inputManager.wasPressed(InputManager::BTN_CONFIRM)) {
+    const NetworkMode mode = (selectedIndex == 0) ? NetworkMode::JOIN_NETWORK : NetworkMode::CREATE_HOTSPOT;
+    onModeSelected(mode);
+    return;
+  }
+
+  // Handle navigation
+  const bool prevPressed =
+      inputManager.wasPressed(InputManager::BTN_UP) || inputManager.wasPressed(InputManager::BTN_LEFT);
+  const bool nextPressed =
+      inputManager.wasPressed(InputManager::BTN_DOWN) || inputManager.wasPressed(InputManager::BTN_RIGHT);
+
+  if (prevPressed) {
+    selectedIndex = (selectedIndex + MENU_ITEM_COUNT - 1) % MENU_ITEM_COUNT;
+    updateRequired = true;
+  } else if (nextPressed) {
+    selectedIndex = (selectedIndex + 1) % MENU_ITEM_COUNT;
+    updateRequired = true;
+  }
+}
+
+void NetworkModeSelectionActivity::displayTaskLoop() {
+  while (true) {
+    if (updateRequired) {
+      updateRequired = false;
+      xSemaphoreTake(renderingMutex, portMAX_DELAY);
+      render();
+      xSemaphoreGive(renderingMutex);
+    }
+    vTaskDelay(10 / portTICK_PERIOD_MS);
+  }
+}
+
+void NetworkModeSelectionActivity::render() const {
+  renderer.clearScreen();
+
+  const auto pageWidth = renderer.getScreenWidth();
+  const auto pageHeight = renderer.getScreenHeight();
+
+  // Draw header
+  renderer.drawCenteredText(READER_FONT_ID, 10, "File Transfer", true, BOLD);
+
+  // Draw subtitle
+  renderer.drawCenteredText(UI_FONT_ID, 50, "How would you like to connect?", true, REGULAR);
+
+  // Draw menu items centered on screen
+  constexpr int itemHeight = 50;  // Height for each menu item (including description)
+  const int startY = (pageHeight - (MENU_ITEM_COUNT * itemHeight)) / 2 + 10;
+
+  for (int i = 0; i < MENU_ITEM_COUNT; i++) {
+    const int itemY = startY + i * itemHeight;
+    const bool isSelected = (i == selectedIndex);
+
+    // Draw selection highlight (black fill) for selected item
+    if (isSelected) {
+      renderer.fillRect(20, itemY - 2, pageWidth - 40, itemHeight - 6);
+    }
+
+    // Draw text: black=false (white text) when selected (on black background)
+    //            black=true (black text) when not selected (on white background)
+    renderer.drawText(UI_FONT_ID, 30, itemY, MENU_ITEMS[i], /*black=*/!isSelected);
+    renderer.drawText(SMALL_FONT_ID, 30, itemY + 22, MENU_DESCRIPTIONS[i], /*black=*/!isSelected);
+  }
+
+  // Draw help text at bottom
+  renderer.drawButtonHints(UI_FONT_ID, "« Back", "Select", "", "");
+
+  renderer.displayBuffer();
+}

src/activities/network/NetworkModeSelectionActivity.h

@@ -0,0 +1,41 @@
+#pragma once
+#include <freertos/FreeRTOS.h>
+#include <freertos/semphr.h>
+#include <freertos/task.h>
+
+#include <functional>
+
+#include "../Activity.h"
+
+// Enum for network mode selection
+enum class NetworkMode { JOIN_NETWORK, CREATE_HOTSPOT };
+
+/**
+ * NetworkModeSelectionActivity presents the user with a choice:
+ * - "Join a Network" - Connect to an existing WiFi network (STA mode)
+ * - "Create Hotspot" - Create an Access Point that others can connect to (AP mode)
+ *
+ * The onModeSelected callback is called with the user's choice.
+ * The onCancel callback is called if the user presses back.
+ */
+class NetworkModeSelectionActivity final : public Activity {
+  TaskHandle_t displayTaskHandle = nullptr;
+  SemaphoreHandle_t renderingMutex = nullptr;
+  int selectedIndex = 0;
+  bool updateRequired = false;
+  const std::function<void(NetworkMode)> onModeSelected;
+  const std::function<void()> onCancel;
+
+  static void taskTrampoline(void* param);
+  [[noreturn]] void displayTaskLoop();
+  void render() const;
+
+ public:
+  explicit NetworkModeSelectionActivity(GfxRenderer& renderer, InputManager& inputManager,
+                                        const std::function<void(NetworkMode)>& onModeSelected,
+                                        const std::function<void()>& onCancel)
+      : Activity("NetworkModeSelection", renderer, inputManager), onModeSelected(onModeSelected), onCancel(onCancel) {}
+  void onEnter() override;
+  void onExit() override;
+  void loop() override;
+};

src/activities/network/WifiSelectionActivity.cpp

@@ -150,6 +150,11 @@ void WifiSelectionActivity::processWifiScanResults() {
   std::sort(networks.begin(), networks.end(),
             [](const WifiNetworkInfo& a, const WifiNetworkInfo& b) { return a.rssi > b.rssi; });
 
+  // Show networks with PW first
+  std::sort(networks.begin(), networks.end(), [](const WifiNetworkInfo& a, const WifiNetworkInfo& b) {
+    return a.hasSavedPassword && !b.hasSavedPassword;
+  });
+
   WiFi.scanDelete();
   state = WifiSelectionState::NETWORK_LIST;
   selectedNetworkIndex = 0;
@@ -182,12 +187,25 @@ void WifiSelectionActivity::selectNetwork(const int index) {
   if (selectedRequiresPassword) {
     // Show password entry
     state = WifiSelectionState::PASSWORD_ENTRY;
-    enterNewActivity(new KeyboardEntryActivity(renderer, inputManager, "Enter WiFi Password",
+    // Don't allow screen updates while changing activity
-                                               "",    // No initial text
+    xSemaphoreTake(renderingMutex, portMAX_DELAY);
-                                               64,    // Max password length
+    enterNewActivity(new KeyboardEntryActivity(
-                                               false  // Show password by default (hard keyboard to use)
+        renderer, inputManager, "Enter WiFi Password",
-                                               ));
+        "",     // No initial text
+        50,     // Y position
+        64,     // Max password length
+        false,  // Show password by default (hard keyboard to use)
+        [this](const std::string& text) {
+          enteredPassword = text;
+          exitActivity();
+        },
+        [this] {
+          state = WifiSelectionState::NETWORK_LIST;
+          updateRequired = true;
+          exitActivity();
+        }));
     updateRequired = true;
+    xSemaphoreGive(renderingMutex);
   } else {
     // Connect directly for open networks
     attemptConnection();
@@ -203,11 +221,6 @@ void WifiSelectionActivity::attemptConnection() {
 
   WiFi.mode(WIFI_STA);
 
-  // Get password from keyboard if we just entered it
-  if (subActivity && !usedSavedPassword) {
-    enteredPassword = static_cast<KeyboardEntryActivity*>(subActivity.get())->getText();
-  }
-
   if (selectedRequiresPassword && !enteredPassword.empty()) {
     WiFi.begin(selectedSSID.c_str(), enteredPassword.c_str());
   } else {
@@ -264,6 +277,11 @@ void WifiSelectionActivity::checkConnectionStatus() {
 }
 
 void WifiSelectionActivity::loop() {
+  if (subActivity) {
+    subActivity->loop();
+    return;
+  }
+
   // Check scan progress
   if (state == WifiSelectionState::SCANNING) {
     processWifiScanResults();
@@ -276,24 +294,9 @@ void WifiSelectionActivity::loop() {
     return;
   }
 
-  // Handle password entry state
+  if (state == WifiSelectionState::PASSWORD_ENTRY) {
-  if (state == WifiSelectionState::PASSWORD_ENTRY && subActivity) {
+    // Reach here once password entry finished in subactivity
-    const auto keyboard = static_cast<KeyboardEntryActivity*>(subActivity.get());
+    attemptConnection();
-    keyboard->handleInput();
-
-    if (keyboard->isComplete()) {
-      attemptConnection();
-      return;
-    }
-
-    if (keyboard->isCancelled()) {
-      state = WifiSelectionState::NETWORK_LIST;
-      exitActivity();
-      updateRequired = true;
-      return;
-    }
-
-    updateRequired = true;
     return;
   }
 
@@ -436,6 +439,10 @@ std::string WifiSelectionActivity::getSignalStrengthIndicator(const int32_t rssi
 
 void WifiSelectionActivity::displayTaskLoop() {
   while (true) {
+    if (subActivity) {
+      continue;
+    }
+
     if (updateRequired) {
       updateRequired = false;
       xSemaphoreTake(renderingMutex, portMAX_DELAY);
@@ -456,9 +463,6 @@ void WifiSelectionActivity::render() const {
     case WifiSelectionState::NETWORK_LIST:
       renderNetworkList();
       break;
-    case WifiSelectionState::PASSWORD_ENTRY:
-      renderPasswordEntry();
-      break;
     case WifiSelectionState::CONNECTING:
       renderConnecting();
       break;
@@ -548,28 +552,12 @@ void WifiSelectionActivity::renderNetworkList() const {
     // Show network count
     char countStr[32];
     snprintf(countStr, sizeof(countStr), "%zu networks found", networks.size());
-    renderer.drawText(SMALL_FONT_ID, 20, pageHeight - 45, countStr);
+    renderer.drawText(SMALL_FONT_ID, 20, pageHeight - 90, countStr);
   }
 
   // Draw help text
-  renderer.drawText(SMALL_FONT_ID, 20, pageHeight - 30, "OK: Connect | * = Encrypted | + = Saved");
+  renderer.drawText(SMALL_FONT_ID, 20, pageHeight - 75, "* = Encrypted | + = Saved");
-}
+  renderer.drawButtonHints(UI_FONT_ID, "« Back", "Connect", "", "");
-
-void WifiSelectionActivity::renderPasswordEntry() const {
-  // Draw header
-  renderer.drawCenteredText(READER_FONT_ID, 5, "WiFi Password", true, BOLD);
-
-  // Draw network name with good spacing from header
-  std::string networkInfo = "Network: " + selectedSSID;
-  if (networkInfo.length() > 30) {
-    networkInfo.replace(27, networkInfo.length() - 27, "...");
-  }
-  renderer.drawCenteredText(UI_FONT_ID, 38, networkInfo.c_str(), true, REGULAR);
-
-  // Draw keyboard
-  if (subActivity) {
-    static_cast<KeyboardEntryActivity*>(subActivity.get())->render(58);
-  }
 }
 
 void WifiSelectionActivity::renderConnecting() const {
@@ -580,7 +568,7 @@ void WifiSelectionActivity::renderConnecting() const {
   if (state == WifiSelectionState::SCANNING) {
     renderer.drawCenteredText(UI_FONT_ID, top, "Scanning...", true, REGULAR);
   } else {
-    renderer.drawCenteredText(READER_FONT_ID, top - 30, "Connecting...", true, BOLD);
+    renderer.drawCenteredText(READER_FONT_ID, top - 40, "Connecting...", true, BOLD);
 
     std::string ssidInfo = "to " + selectedSSID;
     if (ssidInfo.length() > 25) {

src/activities/reader/EpubReaderActivity.cpp

@@ -1,9 +1,9 @@
 #include "EpubReaderActivity.h"
 
 #include <Epub/Page.h>
+#include <FsHelpers.h>
 #include <GfxRenderer.h>
 #include <InputManager.h>
-#include <SD.h>
 
 #include "Battery.h"
 #include "CrossPointSettings.h"
@@ -14,11 +14,10 @@
 namespace {
 constexpr int pagesPerRefresh = 15;
 constexpr unsigned long skipChapterMs = 700;
+constexpr unsigned long goHomeMs = 1000;
 constexpr float lineCompression = 0.95f;
-constexpr int marginTop = 8;
+constexpr int horizontalPadding = 5;
-constexpr int marginRight = 10;
+constexpr int statusBarMargin = 19;
-constexpr int marginBottom = 22;
-constexpr int marginLeft = 10;
 }  // namespace
 
 void EpubReaderActivity::taskTrampoline(void* param) {
@@ -33,12 +32,30 @@ void EpubReaderActivity::onEnter() {
     return;
   }
 
+  // Configure screen orientation based on settings
+  switch (SETTINGS.orientation) {
+    case CrossPointSettings::ORIENTATION::PORTRAIT:
+      renderer.setOrientation(GfxRenderer::Orientation::Portrait);
+      break;
+    case CrossPointSettings::ORIENTATION::LANDSCAPE_CW:
+      renderer.setOrientation(GfxRenderer::Orientation::LandscapeClockwise);
+      break;
+    case CrossPointSettings::ORIENTATION::INVERTED:
+      renderer.setOrientation(GfxRenderer::Orientation::PortraitInverted);
+      break;
+    case CrossPointSettings::ORIENTATION::LANDSCAPE_CCW:
+      renderer.setOrientation(GfxRenderer::Orientation::LandscapeCounterClockwise);
+      break;
+    default:
+      break;
+  }
+
   renderingMutex = xSemaphoreCreateMutex();
 
   epub->setupCacheDir();
 
-  File f = SD.open((epub->getCachePath() + "/progress.bin").c_str());
+  File f;
-  if (f) {
+  if (FsHelpers::openFileForRead("ERS", epub->getCachePath() + "/progress.bin", f)) {
     uint8_t data[4];
     if (f.read(data, 4) == 4) {
       currentSpineIndex = data[0] + (data[1] << 8);
@@ -66,6 +83,9 @@ void EpubReaderActivity::onEnter() {
 void EpubReaderActivity::onExit() {
   ActivityWithSubactivity::onExit();
 
+  // Reset orientation back to portrait for the rest of the UI
+  renderer.setOrientation(GfxRenderer::Orientation::Portrait);
+
   // Wait until not rendering to delete task to avoid killing mid-instruction to EPD
   xSemaphoreTake(renderingMutex, portMAX_DELAY);
   if (displayTaskHandle) {
@@ -86,7 +106,7 @@ void EpubReaderActivity::loop() {
   }
 
   // Enter chapter selection activity
-  if (inputManager.wasPressed(InputManager::BTN_CONFIRM)) {
+  if (inputManager.wasReleased(InputManager::BTN_CONFIRM)) {
     // Don't start activity transition while rendering
     xSemaphoreTake(renderingMutex, portMAX_DELAY);
     exitActivity();
@@ -108,7 +128,14 @@ void EpubReaderActivity::loop() {
     xSemaphoreGive(renderingMutex);
   }
 
-  if (inputManager.wasPressed(InputManager::BTN_BACK)) {
+  // Long press BACK (1s+) goes directly to home
+  if (inputManager.isPressed(InputManager::BTN_BACK) && inputManager.getHeldTime() >= goHomeMs) {
+    onGoHome();
+    return;
+  }
+
+  // Short press BACK goes to file selection
+  if (inputManager.wasReleased(InputManager::BTN_BACK) && inputManager.getHeldTime() < goHomeMs) {
     onGoBack();
     return;
   }
@@ -211,31 +238,70 @@ void EpubReaderActivity::renderScreen() {
     return;
   }
 
+  // Apply screen viewable areas and additional padding
+  int orientedMarginTop, orientedMarginRight, orientedMarginBottom, orientedMarginLeft;
+  renderer.getOrientedViewableTRBL(&orientedMarginTop, &orientedMarginRight, &orientedMarginBottom,
+                                   &orientedMarginLeft);
+  orientedMarginLeft += horizontalPadding;
+  orientedMarginRight += horizontalPadding;
+  orientedMarginBottom += statusBarMargin;
+
   if (!section) {
-    const auto filepath = epub->getSpineItem(currentSpineIndex);
+    const auto filepath = epub->getSpineItem(currentSpineIndex).href;
     Serial.printf("[%lu] [ERS] Loading file: %s, index: %d\n", millis(), filepath.c_str(), currentSpineIndex);
     section = std::unique_ptr<Section>(new Section(epub, currentSpineIndex, renderer));
-    if (!section->loadCacheMetadata(READER_FONT_ID, lineCompression, marginTop, marginRight, marginBottom, marginLeft,
+
-                                    SETTINGS.extraParagraphSpacing)) {
+    const auto viewportWidth = renderer.getScreenWidth() - orientedMarginLeft - orientedMarginRight;
+    const auto viewportHeight = renderer.getScreenHeight() - orientedMarginTop - orientedMarginBottom;
+
+    if (!section->loadCacheMetadata(READER_FONT_ID, lineCompression, SETTINGS.extraParagraphSpacing, viewportWidth,
+                                    viewportHeight)) {
       Serial.printf("[%lu] [ERS] Cache not found, building...\n", millis());
 
+      // Progress bar dimensions
+      constexpr int barWidth = 200;
+      constexpr int barHeight = 10;
+      constexpr int boxMargin = 20;
+      const int textWidth = renderer.getTextWidth(READER_FONT_ID, "Indexing...");
+      const int boxWidthWithBar = (barWidth > textWidth ? barWidth : textWidth) + boxMargin * 2;
+      const int boxWidthNoBar = textWidth + boxMargin * 2;
+      const int boxHeightWithBar = renderer.getLineHeight(READER_FONT_ID) + barHeight + boxMargin * 3;
+      const int boxHeightNoBar = renderer.getLineHeight(READER_FONT_ID) + boxMargin * 2;
+      const int boxXWithBar = (renderer.getScreenWidth() - boxWidthWithBar) / 2;
+      const int boxXNoBar = (renderer.getScreenWidth() - boxWidthNoBar) / 2;
+      constexpr int boxY = 50;
+      const int barX = boxXWithBar + (boxWidthWithBar - barWidth) / 2;
+      const int barY = boxY + renderer.getLineHeight(READER_FONT_ID) + boxMargin * 2;
+
+      // Always show "Indexing..." text first
       {
-        const int textWidth = renderer.getTextWidth(READER_FONT_ID, "Indexing...");
+        renderer.fillRect(boxXNoBar, boxY, boxWidthNoBar, boxHeightNoBar, false);
-        constexpr int margin = 20;
+        renderer.drawText(READER_FONT_ID, boxXNoBar + boxMargin, boxY + boxMargin, "Indexing...");
-        const int x = (GfxRenderer::getScreenWidth() - textWidth - margin * 2) / 2;
+        renderer.drawRect(boxXNoBar + 5, boxY + 5, boxWidthNoBar - 10, boxHeightNoBar - 10);
-        constexpr int y = 50;
-        const int w = textWidth + margin * 2;
-        const int h = renderer.getLineHeight(READER_FONT_ID) + margin * 2;
-        renderer.fillRect(x, y, w, h, false);
-        renderer.drawText(READER_FONT_ID, x + margin, y + margin, "Indexing...");
-        renderer.drawRect(x + 5, y + 5, w - 10, h - 10);
         renderer.displayBuffer();
         pagesUntilFullRefresh = 0;
       }
 
       section->setupCacheDir();
-      if (!section->persistPageDataToSD(READER_FONT_ID, lineCompression, marginTop, marginRight, marginBottom,
+
-                                        marginLeft, SETTINGS.extraParagraphSpacing)) {
+      // Setup callback - only called for chapters >= 50KB, redraws with progress bar
+      auto progressSetup = [this, boxXWithBar, boxWidthWithBar, boxHeightWithBar, barX, barY] {
+        renderer.fillRect(boxXWithBar, boxY, boxWidthWithBar, boxHeightWithBar, false);
+        renderer.drawText(READER_FONT_ID, boxXWithBar + boxMargin, boxY + boxMargin, "Indexing...");
+        renderer.drawRect(boxXWithBar + 5, boxY + 5, boxWidthWithBar - 10, boxHeightWithBar - 10);
+        renderer.drawRect(barX, barY, barWidth, barHeight);
+        renderer.displayBuffer();
+      };
+
+      // Progress callback to update progress bar
+      auto progressCallback = [this, barX, barY, barWidth, barHeight](int progress) {
+        const int fillWidth = (barWidth - 2) * progress / 100;
+        renderer.fillRect(barX + 1, barY + 1, fillWidth, barHeight - 2, true);
+        renderer.displayBuffer(EInkDisplay::FAST_REFRESH);
+      };
+
+      if (!section->persistPageDataToSD(READER_FONT_ID, lineCompression, SETTINGS.extraParagraphSpacing, viewportWidth,
+                                        viewportHeight, progressSetup, progressCallback)) {
         Serial.printf("[%lu] [ERS] Failed to persist page data to SD\n", millis());
         section.reset();
         return;
@@ -256,7 +322,7 @@ void EpubReaderActivity::renderScreen() {
   if (section->pageCount == 0) {
     Serial.printf("[%lu] [ERS] No pages to render\n", millis());
     renderer.drawCenteredText(READER_FONT_ID, 300, "Empty chapter", true, BOLD);
-    renderStatusBar();
+    renderStatusBar(orientedMarginRight, orientedMarginBottom, orientedMarginLeft);
     renderer.displayBuffer();
     return;
   }
@@ -264,7 +330,7 @@ void EpubReaderActivity::renderScreen() {
   if (section->currentPage < 0 || section->currentPage >= section->pageCount) {
     Serial.printf("[%lu] [ERS] Page out of bounds: %d (max %d)\n", millis(), section->currentPage, section->pageCount);
     renderer.drawCenteredText(READER_FONT_ID, 300, "Out of bounds", true, BOLD);
-    renderStatusBar();
+    renderStatusBar(orientedMarginRight, orientedMarginBottom, orientedMarginLeft);
     renderer.displayBuffer();
     return;
   }
@@ -278,23 +344,27 @@ void EpubReaderActivity::renderScreen() {
       return renderScreen();
     }
     const auto start = millis();
-    renderContents(std::move(p));
+    renderContents(std::move(p), orientedMarginTop, orientedMarginRight, orientedMarginBottom, orientedMarginLeft);
     Serial.printf("[%lu] [ERS] Rendered page in %dms\n", millis(), millis() - start);
   }
 
-  File f = SD.open((epub->getCachePath() + "/progress.bin").c_str(), FILE_WRITE);
+  File f;
-  uint8_t data[4];
+  if (FsHelpers::openFileForWrite("ERS", epub->getCachePath() + "/progress.bin", f)) {
-  data[0] = currentSpineIndex & 0xFF;
+    uint8_t data[4];
-  data[1] = (currentSpineIndex >> 8) & 0xFF;
+    data[0] = currentSpineIndex & 0xFF;
-  data[2] = section->currentPage & 0xFF;
+    data[1] = (currentSpineIndex >> 8) & 0xFF;
-  data[3] = (section->currentPage >> 8) & 0xFF;
+    data[2] = section->currentPage & 0xFF;
-  f.write(data, 4);
+    data[3] = (section->currentPage >> 8) & 0xFF;
-  f.close();
+    f.write(data, 4);
+    f.close();
+  }
 }
 
-void EpubReaderActivity::renderContents(std::unique_ptr<Page> page) {
+void EpubReaderActivity::renderContents(std::unique_ptr<Page> page, const int orientedMarginTop,
-  page->render(renderer, READER_FONT_ID);
+                                        const int orientedMarginRight, const int orientedMarginBottom,
-  renderStatusBar();
+                                        const int orientedMarginLeft) {
+  page->render(renderer, READER_FONT_ID, orientedMarginLeft, orientedMarginTop);
+  renderStatusBar(orientedMarginRight, orientedMarginBottom, orientedMarginLeft);
   if (pagesUntilFullRefresh <= 1) {
     renderer.displayBuffer(EInkDisplay::HALF_REFRESH);
     pagesUntilFullRefresh = pagesPerRefresh;
@@ -311,13 +381,13 @@ void EpubReaderActivity::renderContents(std::unique_ptr<Page> page) {
   {
     renderer.clearScreen(0x00);
     renderer.setRenderMode(GfxRenderer::GRAYSCALE_LSB);
-    page->render(renderer, READER_FONT_ID);
+    page->render(renderer, READER_FONT_ID, orientedMarginLeft, orientedMarginTop);
     renderer.copyGrayscaleLsbBuffers();
 
     // Render and copy to MSB buffer
     renderer.clearScreen(0x00);
     renderer.setRenderMode(GfxRenderer::GRAYSCALE_MSB);
-    page->render(renderer, READER_FONT_ID);
+    page->render(renderer, READER_FONT_ID, orientedMarginLeft, orientedMarginTop);
     renderer.copyGrayscaleMsbBuffers();
 
     // display grayscale part
@@ -329,72 +399,90 @@ void EpubReaderActivity::renderContents(std::unique_ptr<Page> page) {
   renderer.restoreBwBuffer();
 }
 
-void EpubReaderActivity::renderStatusBar() const {
+void EpubReaderActivity::renderStatusBar(const int orientedMarginRight, const int orientedMarginBottom,
-  constexpr auto textY = 776;
+                                         const int orientedMarginLeft) const {
+  // determine visible status bar elements
+  const bool showProgress = SETTINGS.statusBar == CrossPointSettings::STATUS_BAR_MODE::FULL;
+  const bool showBattery = SETTINGS.statusBar == CrossPointSettings::STATUS_BAR_MODE::NO_PROGRESS ||
+                           SETTINGS.statusBar == CrossPointSettings::STATUS_BAR_MODE::FULL;
+  const bool showChapterTitle = SETTINGS.statusBar == CrossPointSettings::STATUS_BAR_MODE::NO_PROGRESS ||
+                                SETTINGS.statusBar == CrossPointSettings::STATUS_BAR_MODE::FULL;
 
-  // Calculate progress in book
+  // Position status bar near the bottom of the logical screen, regardless of orientation
-  const float sectionChapterProg = static_cast<float>(section->currentPage) / section->pageCount;
+  const auto screenHeight = renderer.getScreenHeight();
-  const uint8_t bookProgress = epub->calculateProgress(currentSpineIndex, sectionChapterProg);
+  const auto textY = screenHeight - orientedMarginBottom + 2;
+  int percentageTextWidth = 0;
+  int progressTextWidth = 0;
 
-  // Right aligned text for progress counter
+  if (showProgress) {
-  const std::string progress = std::to_string(section->currentPage + 1) + "/" + std::to_string(section->pageCount) +
+    // Calculate progress in book
-                               "  " + std::to_string(bookProgress) + "%";
+    const float sectionChapterProg = static_cast<float>(section->currentPage) / section->pageCount;
-  const auto progressTextWidth = renderer.getTextWidth(SMALL_FONT_ID, progress.c_str());
+    const uint8_t bookProgress = epub->calculateProgress(currentSpineIndex, sectionChapterProg);
-  renderer.drawText(SMALL_FONT_ID, GfxRenderer::getScreenWidth() - marginRight - progressTextWidth, textY,
-                    progress.c_str());
 
-  // Left aligned battery icon and percentage
+    // Right aligned text for progress counter
-  const uint16_t percentage = battery.readPercentage();
+    const std::string progress = std::to_string(section->currentPage + 1) + "/" + std::to_string(section->pageCount) +
-  const auto percentageText = std::to_string(percentage) + "%";
+                                 "  " + std::to_string(bookProgress) + "%";
-  const auto percentageTextWidth = renderer.getTextWidth(SMALL_FONT_ID, percentageText.c_str());
+    progressTextWidth = renderer.getTextWidth(SMALL_FONT_ID, progress.c_str());
-  renderer.drawText(SMALL_FONT_ID, 20 + marginLeft, textY, percentageText.c_str());
+    renderer.drawText(SMALL_FONT_ID, renderer.getScreenWidth() - orientedMarginRight - progressTextWidth, textY,
-
+                      progress.c_str());
-  // 1 column on left, 2 columns on right, 5 columns of battery body
-  constexpr int batteryWidth = 15;
-  constexpr int batteryHeight = 10;
-  constexpr int x = marginLeft;
-  constexpr int y = 783;
-
-  // Top line
-  renderer.drawLine(x, y, x + batteryWidth - 4, y);
-  // Bottom line
-  renderer.drawLine(x, y + batteryHeight - 1, x + batteryWidth - 4, y + batteryHeight - 1);
-  // Left line
-  renderer.drawLine(x, y, x, y + batteryHeight - 1);
-  // Battery end
-  renderer.drawLine(x + batteryWidth - 4, y, x + batteryWidth - 4, y + batteryHeight - 1);
-  renderer.drawLine(x + batteryWidth - 3, y + 2, x + batteryWidth - 1, y + 2);
-  renderer.drawLine(x + batteryWidth - 3, y + batteryHeight - 3, x + batteryWidth - 1, y + batteryHeight - 3);
-  renderer.drawLine(x + batteryWidth - 1, y + 2, x + batteryWidth - 1, y + batteryHeight - 3);
-
-  // The +1 is to round up, so that we always fill at least one pixel
-  int filledWidth = percentage * (batteryWidth - 5) / 100 + 1;
-  if (filledWidth > batteryWidth - 5) {
-    filledWidth = batteryWidth - 5;  // Ensure we don't overflow
   }
-  renderer.fillRect(x + 1, y + 1, filledWidth, batteryHeight - 2);
 
-  // Centered chatper title text
+  if (showBattery) {
-  // Page width minus existing content with 30px padding on each side
+    // Left aligned battery icon and percentage
-  const int titleMarginLeft = 20 + percentageTextWidth + 30 + marginLeft;
+    const uint16_t percentage = battery.readPercentage();
-  const int titleMarginRight = progressTextWidth + 30 + marginRight;
+    const auto percentageText = std::to_string(percentage) + "%";
-  const int availableTextWidth = GfxRenderer::getScreenWidth() - titleMarginLeft - titleMarginRight;
+    percentageTextWidth = renderer.getTextWidth(SMALL_FONT_ID, percentageText.c_str());
-  const int tocIndex = epub->getTocIndexForSpineIndex(currentSpineIndex);
+    renderer.drawText(SMALL_FONT_ID, 20 + orientedMarginLeft, textY, percentageText.c_str());
 
-  std::string title;
+    // 1 column on left, 2 columns on right, 5 columns of battery body
-  int titleWidth;
+    constexpr int batteryWidth = 15;
-  if (tocIndex == -1) {
+    constexpr int batteryHeight = 10;
-    title = "Unnamed";
+    const int x = orientedMarginLeft;
-    titleWidth = renderer.getTextWidth(SMALL_FONT_ID, "Unnamed");
+    const int y = screenHeight - orientedMarginBottom + 5;
-  } else {
+
-    const auto tocItem = epub->getTocItem(tocIndex);
+    // Top line
-    title = tocItem.title;
+    renderer.drawLine(x, y, x + batteryWidth - 4, y);
-    titleWidth = renderer.getTextWidth(SMALL_FONT_ID, title.c_str());
+    // Bottom line
-    while (titleWidth > availableTextWidth && title.length() > 11) {
+    renderer.drawLine(x, y + batteryHeight - 1, x + batteryWidth - 4, y + batteryHeight - 1);
-      title.replace(title.length() - 8, 8, "...");
+    // Left line
-      titleWidth = renderer.getTextWidth(SMALL_FONT_ID, title.c_str());
+    renderer.drawLine(x, y, x, y + batteryHeight - 1);
+    // Battery end
+    renderer.drawLine(x + batteryWidth - 4, y, x + batteryWidth - 4, y + batteryHeight - 1);
+    renderer.drawLine(x + batteryWidth - 3, y + 2, x + batteryWidth - 1, y + 2);
+    renderer.drawLine(x + batteryWidth - 3, y + batteryHeight - 3, x + batteryWidth - 1, y + batteryHeight - 3);
+    renderer.drawLine(x + batteryWidth - 1, y + 2, x + batteryWidth - 1, y + batteryHeight - 3);
+
+    // The +1 is to round up, so that we always fill at least one pixel
+    int filledWidth = percentage * (batteryWidth - 5) / 100 + 1;
+    if (filledWidth > batteryWidth - 5) {
+      filledWidth = batteryWidth - 5;  // Ensure we don't overflow
     }
+    renderer.fillRect(x + 1, y + 1, filledWidth, batteryHeight - 2);
   }
 
-  renderer.drawText(SMALL_FONT_ID, titleMarginLeft + (availableTextWidth - titleWidth) / 2, textY, title.c_str());
+  if (showChapterTitle) {
+    // Centered chatper title text
+    // Page width minus existing content with 30px padding on each side
+    const int titleMarginLeft = 20 + percentageTextWidth + 30 + orientedMarginLeft;
+    const int titleMarginRight = progressTextWidth + 30 + orientedMarginRight;
+    const int availableTextWidth = renderer.getScreenWidth() - titleMarginLeft - titleMarginRight;
+    const int tocIndex = epub->getTocIndexForSpineIndex(currentSpineIndex);
+
+    std::string title;
+    int titleWidth;
+    if (tocIndex == -1) {
+      title = "Unnamed";
+      titleWidth = renderer.getTextWidth(SMALL_FONT_ID, "Unnamed");
+    } else {
+      const auto tocItem = epub->getTocItem(tocIndex);
+      title = tocItem.title;
+      titleWidth = renderer.getTextWidth(SMALL_FONT_ID, title.c_str());
+      while (titleWidth > availableTextWidth && title.length() > 11) {
+        title.replace(title.length() - 8, 8, "...");
+        titleWidth = renderer.getTextWidth(SMALL_FONT_ID, title.c_str());
+      }
+    }
+
+    renderer.drawText(SMALL_FONT_ID, titleMarginLeft + (availableTextWidth - titleWidth) / 2, textY, title.c_str());
+  }
 }

src/activities/reader/EpubReaderActivity.h

@@ -17,17 +17,22 @@ class EpubReaderActivity final : public ActivityWithSubactivity {
   int pagesUntilFullRefresh = 0;
   bool updateRequired = false;
   const std::function<void()> onGoBack;
+  const std::function<void()> onGoHome;
 
   static void taskTrampoline(void* param);
   [[noreturn]] void displayTaskLoop();
   void renderScreen();
-  void renderContents(std::unique_ptr<Page> p);
+  void renderContents(std::unique_ptr<Page> page, int orientedMarginTop, int orientedMarginRight,
-  void renderStatusBar() const;
+                      int orientedMarginBottom, int orientedMarginLeft);
+  void renderStatusBar(int orientedMarginRight, int orientedMarginBottom, int orientedMarginLeft) const;
 
  public:
   explicit EpubReaderActivity(GfxRenderer& renderer, InputManager& inputManager, std::unique_ptr<Epub> epub,
-                              const std::function<void()>& onGoBack)
+                              const std::function<void()>& onGoBack, const std::function<void()>& onGoHome)
-      : ActivityWithSubactivity("EpubReader", renderer, inputManager), epub(std::move(epub)), onGoBack(onGoBack) {}
+      : ActivityWithSubactivity("EpubReader", renderer, inputManager),
+        epub(std::move(epub)),
+        onGoBack(onGoBack),
+        onGoHome(onGoHome) {}
   void onEnter() override;
   void onExit() override;
   void loop() override;

src/activities/reader/EpubReaderChapterSelectionActivity.cpp

@@ -7,10 +7,26 @@
 #include "config.h"
 
 namespace {
-constexpr int PAGE_ITEMS = 24;
+// Time threshold for treating a long press as a page-up/page-down
 constexpr int SKIP_PAGE_MS = 700;
 }  // namespace
 
+int EpubReaderChapterSelectionActivity::getPageItems() const {
+  // Layout constants used in renderScreen
+  constexpr int startY = 60;
+  constexpr int lineHeight = 30;
+
+  const int screenHeight = renderer.getScreenHeight();
+  const int availableHeight = screenHeight - startY;
+  int items = availableHeight / lineHeight;
+
+  // Ensure we always have at least one item per page to avoid division by zero
+  if (items < 1) {
+    items = 1;
+  }
+  return items;
+}
+
 void EpubReaderChapterSelectionActivity::taskTrampoline(void* param) {
   auto* self = static_cast<EpubReaderChapterSelectionActivity*>(param);
   self->displayTaskLoop();
@@ -29,7 +45,7 @@ void EpubReaderChapterSelectionActivity::onEnter() {
   // Trigger first update
   updateRequired = true;
   xTaskCreate(&EpubReaderChapterSelectionActivity::taskTrampoline, "EpubReaderChapterSelectionActivityTask",
-              2048,               // Stack size
+              4096,               // Stack size
               this,               // Parameters
               1,                  // Priority
               &displayTaskHandle  // Task handle
@@ -56,22 +72,23 @@ void EpubReaderChapterSelectionActivity::loop() {
       inputManager.wasReleased(InputManager::BTN_DOWN) || inputManager.wasReleased(InputManager::BTN_RIGHT);
 
   const bool skipPage = inputManager.getHeldTime() > SKIP_PAGE_MS;
+  const int pageItems = getPageItems();
 
-  if (inputManager.wasPressed(InputManager::BTN_CONFIRM)) {
+  if (inputManager.wasReleased(InputManager::BTN_CONFIRM)) {
     onSelectSpineIndex(selectorIndex);
-  } else if (inputManager.wasPressed(InputManager::BTN_BACK)) {
+  } else if (inputManager.wasReleased(InputManager::BTN_BACK)) {
     onGoBack();
   } else if (prevReleased) {
     if (skipPage) {
       selectorIndex =
-          ((selectorIndex / PAGE_ITEMS - 1) * PAGE_ITEMS + epub->getSpineItemsCount()) % epub->getSpineItemsCount();
+          ((selectorIndex / pageItems - 1) * pageItems + epub->getSpineItemsCount()) % epub->getSpineItemsCount();
     } else {
       selectorIndex = (selectorIndex + epub->getSpineItemsCount() - 1) % epub->getSpineItemsCount();
     }
     updateRequired = true;
   } else if (nextReleased) {
     if (skipPage) {
-      selectorIndex = ((selectorIndex / PAGE_ITEMS + 1) * PAGE_ITEMS) % epub->getSpineItemsCount();
+      selectorIndex = ((selectorIndex / pageItems + 1) * pageItems) % epub->getSpineItemsCount();
     } else {
       selectorIndex = (selectorIndex + 1) % epub->getSpineItemsCount();
     }
@@ -95,17 +112,18 @@ void EpubReaderChapterSelectionActivity::renderScreen() {
   renderer.clearScreen();
 
   const auto pageWidth = renderer.getScreenWidth();
+  const int pageItems = getPageItems();
   renderer.drawCenteredText(READER_FONT_ID, 10, "Select Chapter", true, BOLD);
 
-  const auto pageStartIndex = selectorIndex / PAGE_ITEMS * PAGE_ITEMS;
+  const auto pageStartIndex = selectorIndex / pageItems * pageItems;
-  renderer.fillRect(0, 60 + (selectorIndex % PAGE_ITEMS) * 30 + 2, pageWidth - 1, 30);
+  renderer.fillRect(0, 60 + (selectorIndex % pageItems) * 30 - 2, pageWidth - 1, 30);
-  for (int i = pageStartIndex; i < epub->getSpineItemsCount() && i < pageStartIndex + PAGE_ITEMS; i++) {
+  for (int i = pageStartIndex; i < epub->getSpineItemsCount() && i < pageStartIndex + pageItems; i++) {
     const int tocIndex = epub->getTocIndexForSpineIndex(i);
     if (tocIndex == -1) {
-      renderer.drawText(UI_FONT_ID, 20, 60 + (i % PAGE_ITEMS) * 30, "Unnamed", i != selectorIndex);
+      renderer.drawText(UI_FONT_ID, 20, 60 + (i % pageItems) * 30, "Unnamed", i != selectorIndex);
     } else {
       auto item = epub->getTocItem(tocIndex);
-      renderer.drawText(UI_FONT_ID, 20 + (item.level - 1) * 15, 60 + (i % PAGE_ITEMS) * 30, item.title.c_str(),
+      renderer.drawText(UI_FONT_ID, 20 + (item.level - 1) * 15, 60 + (i % pageItems) * 30, item.title.c_str(),
                         i != selectorIndex);
     }
   }

src/activities/reader/EpubReaderChapterSelectionActivity.h

@@ -18,6 +18,10 @@ class EpubReaderChapterSelectionActivity final : public Activity {
   const std::function<void()> onGoBack;
   const std::function<void(int newSpineIndex)> onSelectSpineIndex;
 
+  // Number of items that fit on a page, derived from logical screen height.
+  // This adapts automatically when switching between portrait and landscape.
+  int getPageItems() const;
+
   static void taskTrampoline(void* param);
   [[noreturn]] void displayTaskLoop();
   void renderScreen();

src/activities/reader/FileSelectionActivity.cpp

@@ -9,6 +9,7 @@
 namespace {
 constexpr int PAGE_ITEMS = 23;
 constexpr int SKIP_PAGE_MS = 700;
+constexpr unsigned long GO_HOME_MS = 1000;
 }  // namespace
 
 void sortFileList(std::vector<std::string>& strs) {
@@ -39,8 +40,12 @@ void FileSelectionActivity::loadFiles() {
 
     if (file.isDirectory()) {
       files.emplace_back(filename + "/");
-    } else if (filename.substr(filename.length() - 5) == ".epub") {
+    } else {
-      files.emplace_back(filename);
+      std::string ext4 = filename.length() >= 4 ? filename.substr(filename.length() - 4) : "";
+      std::string ext5 = filename.length() >= 5 ? filename.substr(filename.length() - 5) : "";
+      if (ext5 == ".epub" || ext5 == ".xtch" || ext4 == ".xtc") {
+        files.emplace_back(filename);
+      }
     }
     file.close();
   }
@@ -53,7 +58,7 @@ void FileSelectionActivity::onEnter() {
 
   renderingMutex = xSemaphoreCreateMutex();
 
-  basepath = "/";
+  // basepath is set via constructor parameter (defaults to "/" if not specified)
   loadFiles();
   selectorIndex = 0;
 
@@ -83,6 +88,16 @@ void FileSelectionActivity::onExit() {
 }
 
 void FileSelectionActivity::loop() {
+  // Long press BACK (1s+) goes to root folder
+  if (inputManager.isPressed(InputManager::BTN_BACK) && inputManager.getHeldTime() >= GO_HOME_MS) {
+    if (basepath != "/") {
+      basepath = "/";
+      loadFiles();
+      updateRequired = true;
+    }
+    return;
+  }
+
   const bool prevReleased =
       inputManager.wasReleased(InputManager::BTN_UP) || inputManager.wasReleased(InputManager::BTN_LEFT);
   const bool nextReleased =
@@ -90,7 +105,7 @@ void FileSelectionActivity::loop() {
 
   const bool skipPage = inputManager.getHeldTime() > SKIP_PAGE_MS;
 
-  if (inputManager.wasPressed(InputManager::BTN_CONFIRM)) {
+  if (inputManager.wasReleased(InputManager::BTN_CONFIRM)) {
     if (files.empty()) {
       return;
     }
@@ -103,15 +118,17 @@ void FileSelectionActivity::loop() {
     } else {
       onSelect(basepath + files[selectorIndex]);
     }
-  } else if (inputManager.wasPressed(InputManager::BTN_BACK)) {
+  } else if (inputManager.wasReleased(InputManager::BTN_BACK)) {
-    if (basepath != "/") {
+    // Short press: go up one directory, or go home if at root
-      basepath.replace(basepath.find_last_of('/'), std::string::npos, "");
+    if (inputManager.getHeldTime() < GO_HOME_MS) {
-      if (basepath.empty()) basepath = "/";
+      if (basepath != "/") {
-      loadFiles();
+        basepath.replace(basepath.find_last_of('/'), std::string::npos, "");
-      updateRequired = true;
+        if (basepath.empty()) basepath = "/";
-    } else {
+        loadFiles();
-      // At root level, go back home
+        updateRequired = true;
-      onGoHome();
+      } else {
+        onGoHome();
+      }
     }
   } else if (prevReleased) {
     if (skipPage) {
@@ -145,20 +162,20 @@ void FileSelectionActivity::displayTaskLoop() {
 void FileSelectionActivity::render() const {
   renderer.clearScreen();
 
-  const auto pageWidth = GfxRenderer::getScreenWidth();
+  const auto pageWidth = renderer.getScreenWidth();
   renderer.drawCenteredText(READER_FONT_ID, 10, "Books", true, BOLD);
 
   // Help text
-  renderer.drawText(SMALL_FONT_ID, 20, GfxRenderer::getScreenHeight() - 30, "Press BACK for Home");
+  renderer.drawButtonHints(UI_FONT_ID, "« Home", "Open", "", "");
 
   if (files.empty()) {
-    renderer.drawText(UI_FONT_ID, 20, 60, "No EPUBs found");
+    renderer.drawText(UI_FONT_ID, 20, 60, "No books found");
     renderer.displayBuffer();
     return;
   }
 
   const auto pageStartIndex = selectorIndex / PAGE_ITEMS * PAGE_ITEMS;
-  renderer.fillRect(0, 60 + (selectorIndex % PAGE_ITEMS) * 30 + 2, pageWidth - 1, 30);
+  renderer.fillRect(0, 60 + (selectorIndex % PAGE_ITEMS) * 30 - 2, pageWidth - 1, 30);
   for (int i = pageStartIndex; i < files.size() && i < pageStartIndex + PAGE_ITEMS; i++) {
     auto item = files[i];
     int itemWidth = renderer.getTextWidth(UI_FONT_ID, item.c_str());

src/activities/reader/FileSelectionActivity.h

@@ -27,8 +27,11 @@ class FileSelectionActivity final : public Activity {
  public:
   explicit FileSelectionActivity(GfxRenderer& renderer, InputManager& inputManager,
                                  const std::function<void(const std::string&)>& onSelect,
-                                 const std::function<void()>& onGoHome)
+                                 const std::function<void()>& onGoHome, std::string initialPath = "/")
-      : Activity("FileSelection", renderer, inputManager), onSelect(onSelect), onGoHome(onGoHome) {}
+      : Activity("FileSelection", renderer, inputManager),
+        basepath(initialPath.empty() ? "/" : std::move(initialPath)),
+        onSelect(onSelect),
+        onGoHome(onGoHome) {}
   void onEnter() override;
   void onExit() override;
   void loop() override;

src/activities/reader/ReaderActivity.cpp

@@ -5,8 +5,29 @@
 #include "Epub.h"
 #include "EpubReaderActivity.h"
 #include "FileSelectionActivity.h"
+#include "Xtc.h"
+#include "XtcReaderActivity.h"
 #include "activities/util/FullScreenMessageActivity.h"
 
+std::string ReaderActivity::extractFolderPath(const std::string& filePath) {
+  const auto lastSlash = filePath.find_last_of('/');
+  if (lastSlash == std::string::npos || lastSlash == 0) {
+    return "/";
+  }
+  return filePath.substr(0, lastSlash);
+}
+
+bool ReaderActivity::isXtcFile(const std::string& path) {
+  if (path.length() < 4) return false;
+  std::string ext4 = path.substr(path.length() - 4);
+  if (ext4 == ".xtc") return true;
+  if (path.length() >= 5) {
+    std::string ext5 = path.substr(path.length() - 5);
+    if (ext5 == ".xtch") return true;
+  }
+  return false;
+}
+
 std::unique_ptr<Epub> ReaderActivity::loadEpub(const std::string& path) {
   if (!SD.exists(path.c_str())) {
     Serial.printf("[%lu] [   ] File does not exist: %s\n", millis(), path.c_str());
@@ -22,46 +43,102 @@ std::unique_ptr<Epub> ReaderActivity::loadEpub(const std::string& path) {
   return nullptr;
 }
 
-void ReaderActivity::onSelectEpubFile(const std::string& path) {
+std::unique_ptr<Xtc> ReaderActivity::loadXtc(const std::string& path) {
+  if (!SD.exists(path.c_str())) {
+    Serial.printf("[%lu] [   ] File does not exist: %s\n", millis(), path.c_str());
+    return nullptr;
+  }
+
+  auto xtc = std::unique_ptr<Xtc>(new Xtc(path, "/.crosspoint"));
+  if (xtc->load()) {
+    return xtc;
+  }
+
+  Serial.printf("[%lu] [   ] Failed to load XTC\n", millis());
+  return nullptr;
+}
+
+void ReaderActivity::onSelectBookFile(const std::string& path) {
+  currentBookPath = path;  // Track current book path
   exitActivity();
   enterNewActivity(new FullScreenMessageActivity(renderer, inputManager, "Loading..."));
 
-  auto epub = loadEpub(path);
+  if (isXtcFile(path)) {
-  if (epub) {
+    // Load XTC file
-    onGoToEpubReader(std::move(epub));
+    auto xtc = loadXtc(path);
+    if (xtc) {
+      onGoToXtcReader(std::move(xtc));
+    } else {
+      exitActivity();
+      enterNewActivity(new FullScreenMessageActivity(renderer, inputManager, "Failed to load XTC", REGULAR,
+                                                     EInkDisplay::HALF_REFRESH));
+      delay(2000);
+      onGoToFileSelection();
+    }
   } else {
-    exitActivity();
+    // Load EPUB file
-    enterNewActivity(new FullScreenMessageActivity(renderer, inputManager, "Failed to load epub", REGULAR,
+    auto epub = loadEpub(path);
-                                                   EInkDisplay::HALF_REFRESH));
+    if (epub) {
-    delay(2000);
+      onGoToEpubReader(std::move(epub));
-    onGoToFileSelection();
+    } else {
+      exitActivity();
+      enterNewActivity(new FullScreenMessageActivity(renderer, inputManager, "Failed to load epub", REGULAR,
+                                                     EInkDisplay::HALF_REFRESH));
+      delay(2000);
+      onGoToFileSelection();
+    }
   }
 }
 
-void ReaderActivity::onGoToFileSelection() {
+void ReaderActivity::onGoToFileSelection(const std::string& fromBookPath) {
   exitActivity();
+  // If coming from a book, start in that book's folder; otherwise start from root
+  const auto initialPath = fromBookPath.empty() ? "/" : extractFolderPath(fromBookPath);
   enterNewActivity(new FileSelectionActivity(
-      renderer, inputManager, [this](const std::string& path) { onSelectEpubFile(path); }, onGoBack));
+      renderer, inputManager, [this](const std::string& path) { onSelectBookFile(path); }, onGoBack, initialPath));
 }
 
 void ReaderActivity::onGoToEpubReader(std::unique_ptr<Epub> epub) {
+  const auto epubPath = epub->getPath();
+  currentBookPath = epubPath;
   exitActivity();
-  enterNewActivity(new EpubReaderActivity(renderer, inputManager, std::move(epub), [this] { onGoToFileSelection(); }));
+  enterNewActivity(new EpubReaderActivity(
+      renderer, inputManager, std::move(epub), [this, epubPath] { onGoToFileSelection(epubPath); },
+      [this] { onGoBack(); }));
+}
+
+void ReaderActivity::onGoToXtcReader(std::unique_ptr<Xtc> xtc) {
+  const auto xtcPath = xtc->getPath();
+  currentBookPath = xtcPath;
+  exitActivity();
+  enterNewActivity(new XtcReaderActivity(
+      renderer, inputManager, std::move(xtc), [this, xtcPath] { onGoToFileSelection(xtcPath); },
+      [this] { onGoBack(); }));
 }
 
 void ReaderActivity::onEnter() {
   ActivityWithSubactivity::onEnter();
 
-  if (initialEpubPath.empty()) {
+  if (initialBookPath.empty()) {
-    onGoToFileSelection();
+    onGoToFileSelection();  // Start from root when entering via Browse
     return;
   }
 
-  auto epub = loadEpub(initialEpubPath);
+  currentBookPath = initialBookPath;
-  if (!epub) {
-    onGoBack();
-    return;
-  }
 
-  onGoToEpubReader(std::move(epub));
+  if (isXtcFile(initialBookPath)) {
+    auto xtc = loadXtc(initialBookPath);
+    if (!xtc) {
+      onGoBack();
+      return;
+    }
+    onGoToXtcReader(std::move(xtc));
+  } else {
+    auto epub = loadEpub(initialBookPath);
+    if (!epub) {
+      onGoBack();
+      return;
+    }
+    onGoToEpubReader(std::move(epub));
+  }
 }

src/activities/reader/ReaderActivity.h

@@ -4,21 +4,27 @@
 #include "../ActivityWithSubactivity.h"
 
 class Epub;
+class Xtc;
 
 class ReaderActivity final : public ActivityWithSubactivity {
-  std::string initialEpubPath;
+  std::string initialBookPath;
+  std::string currentBookPath;  // Track current book path for navigation
   const std::function<void()> onGoBack;
   static std::unique_ptr<Epub> loadEpub(const std::string& path);
+  static std::unique_ptr<Xtc> loadXtc(const std::string& path);
+  static bool isXtcFile(const std::string& path);
 
-  void onSelectEpubFile(const std::string& path);
+  static std::string extractFolderPath(const std::string& filePath);
-  void onGoToFileSelection();
+  void onSelectBookFile(const std::string& path);
+  void onGoToFileSelection(const std::string& fromBookPath = "");
   void onGoToEpubReader(std::unique_ptr<Epub> epub);
+  void onGoToXtcReader(std::unique_ptr<Xtc> xtc);
 
  public:
-  explicit ReaderActivity(GfxRenderer& renderer, InputManager& inputManager, std::string initialEpubPath,
+  explicit ReaderActivity(GfxRenderer& renderer, InputManager& inputManager, std::string initialBookPath,
                           const std::function<void()>& onGoBack)
       : ActivityWithSubactivity("Reader", renderer, inputManager),
-        initialEpubPath(std::move(initialEpubPath)),
+        initialBookPath(std::move(initialBookPath)),
         onGoBack(onGoBack) {}
   void onEnter() override;
 };

src/activities/reader/XtcReaderActivity.cpp

@@ -0,0 +1,360 @@
+/**
+ * XtcReaderActivity.cpp
+ *
+ * XTC ebook reader activity implementation
+ * Displays pre-rendered XTC pages on e-ink display
+ */
+
+#include "XtcReaderActivity.h"
+
+#include <FsHelpers.h>
+#include <GfxRenderer.h>
+#include <InputManager.h>
+
+#include "CrossPointSettings.h"
+#include "CrossPointState.h"
+#include "config.h"
+
+namespace {
+constexpr int pagesPerRefresh = 15;
+constexpr unsigned long skipPageMs = 700;
+constexpr unsigned long goHomeMs = 1000;
+}  // namespace
+
+void XtcReaderActivity::taskTrampoline(void* param) {
+  auto* self = static_cast<XtcReaderActivity*>(param);
+  self->displayTaskLoop();
+}
+
+void XtcReaderActivity::onEnter() {
+  Activity::onEnter();
+
+  if (!xtc) {
+    return;
+  }
+
+  renderingMutex = xSemaphoreCreateMutex();
+
+  xtc->setupCacheDir();
+
+  // Load saved progress
+  loadProgress();
+
+  // Save current XTC as last opened book
+  APP_STATE.openEpubPath = xtc->getPath();
+  APP_STATE.saveToFile();
+
+  // Trigger first update
+  updateRequired = true;
+
+  xTaskCreate(&XtcReaderActivity::taskTrampoline, "XtcReaderActivityTask",
+              4096,               // Stack size (smaller than EPUB since no parsing needed)
+              this,               // Parameters
+              1,                  // Priority
+              &displayTaskHandle  // Task handle
+  );
+}
+
+void XtcReaderActivity::onExit() {
+  Activity::onExit();
+
+  // Wait until not rendering to delete task
+  xSemaphoreTake(renderingMutex, portMAX_DELAY);
+  if (displayTaskHandle) {
+    vTaskDelete(displayTaskHandle);
+    displayTaskHandle = nullptr;
+  }
+  vSemaphoreDelete(renderingMutex);
+  renderingMutex = nullptr;
+  xtc.reset();
+}
+
+void XtcReaderActivity::loop() {
+  // Long press BACK (1s+) goes directly to home
+  if (inputManager.isPressed(InputManager::BTN_BACK) && inputManager.getHeldTime() >= goHomeMs) {
+    onGoHome();
+    return;
+  }
+
+  // Short press BACK goes to file selection
+  if (inputManager.wasReleased(InputManager::BTN_BACK) && inputManager.getHeldTime() < goHomeMs) {
+    onGoBack();
+    return;
+  }
+
+  const bool prevReleased =
+      inputManager.wasReleased(InputManager::BTN_UP) || inputManager.wasReleased(InputManager::BTN_LEFT);
+  const bool nextReleased =
+      inputManager.wasReleased(InputManager::BTN_DOWN) || inputManager.wasReleased(InputManager::BTN_RIGHT);
+
+  if (!prevReleased && !nextReleased) {
+    return;
+  }
+
+  // Handle end of book
+  if (currentPage >= xtc->getPageCount()) {
+    currentPage = xtc->getPageCount() - 1;
+    updateRequired = true;
+    return;
+  }
+
+  const bool skipPages = inputManager.getHeldTime() > skipPageMs;
+  const int skipAmount = skipPages ? 10 : 1;
+
+  if (prevReleased) {
+    if (currentPage >= static_cast<uint32_t>(skipAmount)) {
+      currentPage -= skipAmount;
+    } else {
+      currentPage = 0;
+    }
+    updateRequired = true;
+  } else if (nextReleased) {
+    currentPage += skipAmount;
+    if (currentPage >= xtc->getPageCount()) {
+      currentPage = xtc->getPageCount();  // Allow showing "End of book"
+    }
+    updateRequired = true;
+  }
+}
+
+void XtcReaderActivity::displayTaskLoop() {
+  while (true) {
+    if (updateRequired) {
+      updateRequired = false;
+      xSemaphoreTake(renderingMutex, portMAX_DELAY);
+      renderScreen();
+      xSemaphoreGive(renderingMutex);
+    }
+    vTaskDelay(10 / portTICK_PERIOD_MS);
+  }
+}
+
+void XtcReaderActivity::renderScreen() {
+  if (!xtc) {
+    return;
+  }
+
+  // Bounds check
+  if (currentPage >= xtc->getPageCount()) {
+    // Show end of book screen
+    renderer.clearScreen();
+    renderer.drawCenteredText(UI_FONT_ID, 300, "End of book", true, BOLD);
+    renderer.displayBuffer();
+    return;
+  }
+
+  renderPage();
+  saveProgress();
+}
+
+void XtcReaderActivity::renderPage() {
+  const uint16_t pageWidth = xtc->getPageWidth();
+  const uint16_t pageHeight = xtc->getPageHeight();
+  const uint8_t bitDepth = xtc->getBitDepth();
+
+  // Calculate buffer size for one page
+  // XTG (1-bit): Row-major, ((width+7)/8) * height bytes
+  // XTH (2-bit): Two bit planes, column-major, ((width * height + 7) / 8) * 2 bytes
+  size_t pageBufferSize;
+  if (bitDepth == 2) {
+    pageBufferSize = ((static_cast<size_t>(pageWidth) * pageHeight + 7) / 8) * 2;
+  } else {
+    pageBufferSize = ((pageWidth + 7) / 8) * pageHeight;
+  }
+
+  // Allocate page buffer
+  uint8_t* pageBuffer = static_cast<uint8_t*>(malloc(pageBufferSize));
+  if (!pageBuffer) {
+    Serial.printf("[%lu] [XTR] Failed to allocate page buffer (%lu bytes)\n", millis(), pageBufferSize);
+    renderer.clearScreen();
+    renderer.drawCenteredText(UI_FONT_ID, 300, "Memory error", true, BOLD);
+    renderer.displayBuffer();
+    return;
+  }
+
+  // Load page data
+  size_t bytesRead = xtc->loadPage(currentPage, pageBuffer, pageBufferSize);
+  if (bytesRead == 0) {
+    Serial.printf("[%lu] [XTR] Failed to load page %lu\n", millis(), currentPage);
+    free(pageBuffer);
+    renderer.clearScreen();
+    renderer.drawCenteredText(UI_FONT_ID, 300, "Page load error", true, BOLD);
+    renderer.displayBuffer();
+    return;
+  }
+
+  // Clear screen first
+  renderer.clearScreen();
+
+  // Copy page bitmap using GfxRenderer's drawPixel
+  // XTC/XTCH pages are pre-rendered with status bar included, so render full page
+  const uint16_t maxSrcY = pageHeight;
+
+  if (bitDepth == 2) {
+    // XTH 2-bit mode: Two bit planes, column-major order
+    // - Columns scanned right to left (x = width-1 down to 0)
+    // - 8 vertical pixels per byte (MSB = topmost pixel in group)
+    // - First plane: Bit1, Second plane: Bit2
+    // - Pixel value = (bit1 << 1) | bit2
+    // - Grayscale: 0=White, 1=Dark Grey, 2=Light Grey, 3=Black
+
+    const size_t planeSize = (static_cast<size_t>(pageWidth) * pageHeight + 7) / 8;
+    const uint8_t* plane1 = pageBuffer;              // Bit1 plane
+    const uint8_t* plane2 = pageBuffer + planeSize;  // Bit2 plane
+    const size_t colBytes = (pageHeight + 7) / 8;    // Bytes per column (100 for 800 height)
+
+    // Lambda to get pixel value at (x, y)
+    auto getPixelValue = [&](uint16_t x, uint16_t y) -> uint8_t {
+      const size_t colIndex = pageWidth - 1 - x;
+      const size_t byteInCol = y / 8;
+      const size_t bitInByte = 7 - (y % 8);
+      const size_t byteOffset = colIndex * colBytes + byteInCol;
+      const uint8_t bit1 = (plane1[byteOffset] >> bitInByte) & 1;
+      const uint8_t bit2 = (plane2[byteOffset] >> bitInByte) & 1;
+      return (bit1 << 1) | bit2;
+    };
+
+    // Optimized grayscale rendering without storeBwBuffer (saves 48KB peak memory)
+    // Flow: BW display → LSB/MSB passes → grayscale display → re-render BW for next frame
+
+    // Count pixel distribution for debugging
+    uint32_t pixelCounts[4] = {0, 0, 0, 0};
+    for (uint16_t y = 0; y < pageHeight; y++) {
+      for (uint16_t x = 0; x < pageWidth; x++) {
+        pixelCounts[getPixelValue(x, y)]++;
+      }
+    }
+    Serial.printf("[%lu] [XTR] Pixel distribution: White=%lu, DarkGrey=%lu, LightGrey=%lu, Black=%lu\n", millis(),
+                  pixelCounts[0], pixelCounts[1], pixelCounts[2], pixelCounts[3]);
+
+    // Pass 1: BW buffer - draw all non-white pixels as black
+    for (uint16_t y = 0; y < pageHeight; y++) {
+      for (uint16_t x = 0; x < pageWidth; x++) {
+        if (getPixelValue(x, y) >= 1) {
+          renderer.drawPixel(x, y, true);
+        }
+      }
+    }
+
+    // Display BW with conditional refresh based on pagesUntilFullRefresh
+    if (pagesUntilFullRefresh <= 1) {
+      renderer.displayBuffer(EInkDisplay::HALF_REFRESH);
+      pagesUntilFullRefresh = pagesPerRefresh;
+    } else {
+      renderer.displayBuffer();
+      pagesUntilFullRefresh--;
+    }
+
+    // Pass 2: LSB buffer - mark DARK gray only (XTH value 1)
+    // In LUT: 0 bit = apply gray effect, 1 bit = untouched
+    renderer.clearScreen(0x00);
+    for (uint16_t y = 0; y < pageHeight; y++) {
+      for (uint16_t x = 0; x < pageWidth; x++) {
+        if (getPixelValue(x, y) == 1) {  // Dark grey only
+          renderer.drawPixel(x, y, false);
+        }
+      }
+    }
+    renderer.copyGrayscaleLsbBuffers();
+
+    // Pass 3: MSB buffer - mark LIGHT AND DARK gray (XTH value 1 or 2)
+    // In LUT: 0 bit = apply gray effect, 1 bit = untouched
+    renderer.clearScreen(0x00);
+    for (uint16_t y = 0; y < pageHeight; y++) {
+      for (uint16_t x = 0; x < pageWidth; x++) {
+        const uint8_t pv = getPixelValue(x, y);
+        if (pv == 1 || pv == 2) {  // Dark grey or Light grey
+          renderer.drawPixel(x, y, false);
+        }
+      }
+    }
+    renderer.copyGrayscaleMsbBuffers();
+
+    // Display grayscale overlay
+    renderer.displayGrayBuffer();
+
+    // Pass 4: Re-render BW to framebuffer (restore for next frame, instead of restoreBwBuffer)
+    renderer.clearScreen();
+    for (uint16_t y = 0; y < pageHeight; y++) {
+      for (uint16_t x = 0; x < pageWidth; x++) {
+        if (getPixelValue(x, y) >= 1) {
+          renderer.drawPixel(x, y, true);
+        }
+      }
+    }
+
+    // Cleanup grayscale buffers with current frame buffer
+    renderer.cleanupGrayscaleWithFrameBuffer();
+
+    free(pageBuffer);
+
+    Serial.printf("[%lu] [XTR] Rendered page %lu/%lu (2-bit grayscale)\n", millis(), currentPage + 1,
+                  xtc->getPageCount());
+    return;
+  } else {
+    // 1-bit mode: 8 pixels per byte, MSB first
+    const size_t srcRowBytes = (pageWidth + 7) / 8;  // 60 bytes for 480 width
+
+    for (uint16_t srcY = 0; srcY < maxSrcY; srcY++) {
+      const size_t srcRowStart = srcY * srcRowBytes;
+
+      for (uint16_t srcX = 0; srcX < pageWidth; srcX++) {
+        // Read source pixel (MSB first, bit 7 = leftmost pixel)
+        const size_t srcByte = srcRowStart + srcX / 8;
+        const size_t srcBit = 7 - (srcX % 8);
+        const bool isBlack = !((pageBuffer[srcByte] >> srcBit) & 1);  // XTC: 0 = black, 1 = white
+
+        if (isBlack) {
+          renderer.drawPixel(srcX, srcY, true);
+        }
+      }
+    }
+  }
+  // White pixels are already cleared by clearScreen()
+
+  free(pageBuffer);
+
+  // XTC pages already have status bar pre-rendered, no need to add our own
+
+  // Display with appropriate refresh
+  if (pagesUntilFullRefresh <= 1) {
+    renderer.displayBuffer(EInkDisplay::HALF_REFRESH);
+    pagesUntilFullRefresh = pagesPerRefresh;
+  } else {
+    renderer.displayBuffer();
+    pagesUntilFullRefresh--;
+  }
+
+  Serial.printf("[%lu] [XTR] Rendered page %lu/%lu (%u-bit)\n", millis(), currentPage + 1, xtc->getPageCount(),
+                bitDepth);
+}
+
+void XtcReaderActivity::saveProgress() const {
+  File f;
+  if (FsHelpers::openFileForWrite("XTR", xtc->getCachePath() + "/progress.bin", f)) {
+    uint8_t data[4];
+    data[0] = currentPage & 0xFF;
+    data[1] = (currentPage >> 8) & 0xFF;
+    data[2] = (currentPage >> 16) & 0xFF;
+    data[3] = (currentPage >> 24) & 0xFF;
+    f.write(data, 4);
+    f.close();
+  }
+}
+
+void XtcReaderActivity::loadProgress() {
+  File f;
+  if (FsHelpers::openFileForRead("XTR", xtc->getCachePath() + "/progress.bin", f)) {
+    uint8_t data[4];
+    if (f.read(data, 4) == 4) {
+      currentPage = data[0] | (data[1] << 8) | (data[2] << 16) | (data[3] << 24);
+      Serial.printf("[%lu] [XTR] Loaded progress: page %lu\n", millis(), currentPage);
+
+      // Validate page number
+      if (currentPage >= xtc->getPageCount()) {
+        currentPage = 0;
+      }
+    }
+    f.close();
+  }
+}

src/activities/reader/XtcReaderActivity.h

@@ -0,0 +1,41 @@
+/**
+ * XtcReaderActivity.h
+ *
+ * XTC ebook reader activity for CrossPoint Reader
+ * Displays pre-rendered XTC pages on e-ink display
+ */
+
+#pragma once
+
+#include <Xtc.h>
+#include <freertos/FreeRTOS.h>
+#include <freertos/semphr.h>
+#include <freertos/task.h>
+
+#include "activities/Activity.h"
+
+class XtcReaderActivity final : public Activity {
+  std::shared_ptr<Xtc> xtc;
+  TaskHandle_t displayTaskHandle = nullptr;
+  SemaphoreHandle_t renderingMutex = nullptr;
+  uint32_t currentPage = 0;
+  int pagesUntilFullRefresh = 0;
+  bool updateRequired = false;
+  const std::function<void()> onGoBack;
+  const std::function<void()> onGoHome;
+
+  static void taskTrampoline(void* param);
+  [[noreturn]] void displayTaskLoop();
+  void renderScreen();
+  void renderPage();
+  void saveProgress() const;
+  void loadProgress();
+
+ public:
+  explicit XtcReaderActivity(GfxRenderer& renderer, InputManager& inputManager, std::unique_ptr<Xtc> xtc,
+                             const std::function<void()>& onGoBack, const std::function<void()>& onGoHome)
+      : Activity("XtcReader", renderer, inputManager), xtc(std::move(xtc)), onGoBack(onGoBack), onGoHome(onGoHome) {}
+  void onEnter() override;
+  void onExit() override;
+  void loop() override;
+};

src/activities/settings/OtaUpdateActivity.cpp

@@ -0,0 +1,242 @@
+#include "OtaUpdateActivity.h"
+
+#include <GfxRenderer.h>
+#include <InputManager.h>
+#include <WiFi.h>
+
+#include "activities/network/WifiSelectionActivity.h"
+#include "config.h"
+#include "network/OtaUpdater.h"
+
+void OtaUpdateActivity::taskTrampoline(void* param) {
+  auto* self = static_cast<OtaUpdateActivity*>(param);
+  self->displayTaskLoop();
+}
+
+void OtaUpdateActivity::onWifiSelectionComplete(const bool success) {
+  exitActivity();
+
+  if (!success) {
+    Serial.printf("[%lu] [OTA] WiFi connection failed, exiting\n", millis());
+    goBack();
+    return;
+  }
+
+  Serial.printf("[%lu] [OTA] WiFi connected, checking for update\n", millis());
+
+  xSemaphoreTake(renderingMutex, portMAX_DELAY);
+  state = CHECKING_FOR_UPDATE;
+  xSemaphoreGive(renderingMutex);
+  updateRequired = true;
+  vTaskDelay(10 / portTICK_PERIOD_MS);
+  const auto res = updater.checkForUpdate();
+  if (res != OtaUpdater::OK) {
+    Serial.printf("[%lu] [OTA] Update check failed: %d\n", millis(), res);
+    xSemaphoreTake(renderingMutex, portMAX_DELAY);
+    state = FAILED;
+    xSemaphoreGive(renderingMutex);
+    updateRequired = true;
+    return;
+  }
+
+  if (!updater.isUpdateNewer()) {
+    Serial.printf("[%lu] [OTA] No new update available\n", millis());
+    xSemaphoreTake(renderingMutex, portMAX_DELAY);
+    state = NO_UPDATE;
+    xSemaphoreGive(renderingMutex);
+    updateRequired = true;
+    return;
+  }
+
+  xSemaphoreTake(renderingMutex, portMAX_DELAY);
+  state = WAITING_CONFIRMATION;
+  xSemaphoreGive(renderingMutex);
+  updateRequired = true;
+}
+
+void OtaUpdateActivity::onEnter() {
+  ActivityWithSubactivity::onEnter();
+
+  renderingMutex = xSemaphoreCreateMutex();
+
+  xTaskCreate(&OtaUpdateActivity::taskTrampoline, "OtaUpdateActivityTask",
+              2048,               // Stack size
+              this,               // Parameters
+              1,                  // Priority
+              &displayTaskHandle  // Task handle
+  );
+
+  // Turn on WiFi immediately
+  Serial.printf("[%lu] [OTA] Turning on WiFi...\n", millis());
+  WiFi.mode(WIFI_STA);
+
+  // Launch WiFi selection subactivity
+  Serial.printf("[%lu] [OTA] Launching WifiSelectionActivity...\n", millis());
+  enterNewActivity(new WifiSelectionActivity(renderer, inputManager,
+                                             [this](const bool connected) { onWifiSelectionComplete(connected); }));
+}
+
+void OtaUpdateActivity::onExit() {
+  ActivityWithSubactivity::onExit();
+
+  // Turn off wifi
+  WiFi.disconnect(false);  // false = don't erase credentials, send disconnect frame
+  delay(100);              // Allow disconnect frame to be sent
+  WiFi.mode(WIFI_OFF);
+  delay(100);  // Allow WiFi hardware to fully power down
+
+  // Wait until not rendering to delete task to avoid killing mid-instruction to EPD
+  xSemaphoreTake(renderingMutex, portMAX_DELAY);
+  if (displayTaskHandle) {
+    vTaskDelete(displayTaskHandle);
+    displayTaskHandle = nullptr;
+  }
+  vSemaphoreDelete(renderingMutex);
+  renderingMutex = nullptr;
+}
+
+void OtaUpdateActivity::displayTaskLoop() {
+  while (true) {
+    if (updateRequired) {
+      updateRequired = false;
+      xSemaphoreTake(renderingMutex, portMAX_DELAY);
+      render();
+      xSemaphoreGive(renderingMutex);
+    }
+    vTaskDelay(10 / portTICK_PERIOD_MS);
+  }
+}
+
+void OtaUpdateActivity::render() {
+  if (subActivity) {
+    // Subactivity handles its own rendering
+    return;
+  }
+
+  float updaterProgress = 0;
+  if (state == UPDATE_IN_PROGRESS) {
+    Serial.printf("[%lu] [OTA] Update progress: %d / %d\n", millis(), updater.processedSize, updater.totalSize);
+    updaterProgress = static_cast<float>(updater.processedSize) / static_cast<float>(updater.totalSize);
+    // Only update every 2% at the most
+    if (static_cast<int>(updaterProgress * 50) == lastUpdaterPercentage / 2) {
+      return;
+    }
+    lastUpdaterPercentage = static_cast<int>(updaterProgress * 100);
+  }
+
+  const auto pageHeight = renderer.getScreenHeight();
+  const auto pageWidth = renderer.getScreenWidth();
+
+  renderer.clearScreen();
+  renderer.drawCenteredText(READER_FONT_ID, 10, "Update", true, BOLD);
+
+  if (state == CHECKING_FOR_UPDATE) {
+    renderer.drawCenteredText(UI_FONT_ID, 300, "Checking for update...", true, BOLD);
+    renderer.displayBuffer();
+    return;
+  }
+
+  if (state == WAITING_CONFIRMATION) {
+    renderer.drawCenteredText(UI_FONT_ID, 200, "New update available!", true, BOLD);
+    renderer.drawText(UI_FONT_ID, 20, 250, "Current Version: " CROSSPOINT_VERSION);
+    renderer.drawText(UI_FONT_ID, 20, 270, ("New Version: " + updater.getLatestVersion()).c_str());
+
+    renderer.drawRect(25, pageHeight - 40, 106, 40);
+    renderer.drawText(UI_FONT_ID, 25 + (105 - renderer.getTextWidth(UI_FONT_ID, "Cancel")) / 2, pageHeight - 35,
+                      "Cancel");
+
+    renderer.drawRect(130, pageHeight - 40, 106, 40);
+    renderer.drawText(UI_FONT_ID, 130 + (105 - renderer.getTextWidth(UI_FONT_ID, "Update")) / 2, pageHeight - 35,
+                      "Update");
+    renderer.displayBuffer();
+    return;
+  }
+
+  if (state == UPDATE_IN_PROGRESS) {
+    renderer.drawCenteredText(UI_FONT_ID, 310, "Updating...", true, BOLD);
+    renderer.drawRect(20, 350, pageWidth - 40, 50);
+    renderer.fillRect(24, 354, static_cast<int>(updaterProgress * static_cast<float>(pageWidth - 44)), 42);
+    renderer.drawCenteredText(UI_FONT_ID, 420, (std::to_string(static_cast<int>(updaterProgress * 100)) + "%").c_str());
+    renderer.drawCenteredText(
+        UI_FONT_ID, 440, (std::to_string(updater.processedSize) + " / " + std::to_string(updater.totalSize)).c_str());
+    renderer.displayBuffer();
+    return;
+  }
+
+  if (state == NO_UPDATE) {
+    renderer.drawCenteredText(UI_FONT_ID, 300, "No update available", true, BOLD);
+    renderer.displayBuffer();
+    return;
+  }
+
+  if (state == FAILED) {
+    renderer.drawCenteredText(UI_FONT_ID, 300, "Update failed", true, BOLD);
+    renderer.displayBuffer();
+    return;
+  }
+
+  if (state == FINISHED) {
+    renderer.drawCenteredText(UI_FONT_ID, 300, "Update complete", true, BOLD);
+    renderer.drawCenteredText(UI_FONT_ID, 350, "Press and hold power button to turn back on");
+    renderer.displayBuffer();
+    state = SHUTTING_DOWN;
+    return;
+  }
+}
+
+void OtaUpdateActivity::loop() {
+  if (subActivity) {
+    subActivity->loop();
+    return;
+  }
+
+  if (state == WAITING_CONFIRMATION) {
+    if (inputManager.wasPressed(InputManager::BTN_CONFIRM)) {
+      Serial.printf("[%lu] [OTA] New update available, starting download...\n", millis());
+      xSemaphoreTake(renderingMutex, portMAX_DELAY);
+      state = UPDATE_IN_PROGRESS;
+      xSemaphoreGive(renderingMutex);
+      updateRequired = true;
+      vTaskDelay(10 / portTICK_PERIOD_MS);
+      const auto res = updater.installUpdate([this](const size_t, const size_t) { updateRequired = true; });
+
+      if (res != OtaUpdater::OK) {
+        Serial.printf("[%lu] [OTA] Update failed: %d\n", millis(), res);
+        xSemaphoreTake(renderingMutex, portMAX_DELAY);
+        state = FAILED;
+        xSemaphoreGive(renderingMutex);
+        updateRequired = true;
+        return;
+      }
+
+      xSemaphoreTake(renderingMutex, portMAX_DELAY);
+      state = FINISHED;
+      xSemaphoreGive(renderingMutex);
+      updateRequired = true;
+    }
+
+    if (inputManager.wasPressed(InputManager::BTN_BACK)) {
+      goBack();
+    }
+
+    return;
+  }
+
+  if (state == FAILED) {
+    if (inputManager.wasPressed(InputManager::BTN_BACK)) {
+      goBack();
+    }
+    return;
+  }
+
+  if (state == NO_UPDATE) {
+    if (inputManager.wasPressed(InputManager::BTN_BACK)) {
+      goBack();
+    }
+    return;
+  }
+
+  if (state == SHUTTING_DOWN) {
+    ESP.restart();
+  }
+}

src/activities/settings/OtaUpdateActivity.h

@@ -0,0 +1,43 @@
+#pragma once
+#include <freertos/FreeRTOS.h>
+#include <freertos/semphr.h>
+#include <freertos/task.h>
+
+#include "activities/ActivityWithSubactivity.h"
+#include "network/OtaUpdater.h"
+
+class OtaUpdateActivity : public ActivityWithSubactivity {
+  enum State {
+    WIFI_SELECTION,
+    CHECKING_FOR_UPDATE,
+    WAITING_CONFIRMATION,
+    UPDATE_IN_PROGRESS,
+    NO_UPDATE,
+    FAILED,
+    FINISHED,
+    SHUTTING_DOWN
+  };
+
+  // Can't initialize this to 0 or the first render doesn't happen
+  static constexpr unsigned int UNINITIALIZED_PERCENTAGE = 111;
+
+  TaskHandle_t displayTaskHandle = nullptr;
+  SemaphoreHandle_t renderingMutex = nullptr;
+  bool updateRequired = false;
+  const std::function<void()> goBack;
+  State state = WIFI_SELECTION;
+  unsigned int lastUpdaterPercentage = UNINITIALIZED_PERCENTAGE;
+  OtaUpdater updater;
+
+  void onWifiSelectionComplete(bool success);
+  static void taskTrampoline(void* param);
+  [[noreturn]] void displayTaskLoop();
+  void render();
+
+ public:
+  explicit OtaUpdateActivity(GfxRenderer& renderer, InputManager& inputManager, const std::function<void()>& goBack)
+      : ActivityWithSubactivity("OtaUpdate", renderer, inputManager), goBack(goBack), updater() {}
+  void onEnter() override;
+  void onExit() override;
+  void loop() override;
+};

src/activities/settings/SettingsActivity.cpp

@@ -4,16 +4,24 @@
 #include <InputManager.h>
 
 #include "CrossPointSettings.h"
+#include "OtaUpdateActivity.h"
 #include "config.h"
 
 // Define the static settings list
 namespace {
-constexpr int settingsCount = 3;
+constexpr int settingsCount = 6;
 const SettingInfo settingsList[settingsCount] = {
     // Should match with SLEEP_SCREEN_MODE
     {"Sleep Screen", SettingType::ENUM, &CrossPointSettings::sleepScreen, {"Dark", "Light", "Custom", "Cover"}},
+    {"Status Bar", SettingType::ENUM, &CrossPointSettings::statusBar, {"None", "No Progress", "Full"}},
     {"Extra Paragraph Spacing", SettingType::TOGGLE, &CrossPointSettings::extraParagraphSpacing, {}},
-    {"Short Power Button Click", SettingType::TOGGLE, &CrossPointSettings::shortPwrBtn, {}}};
+    {"Short Power Button Click", SettingType::TOGGLE, &CrossPointSettings::shortPwrBtn, {}},
+    {"Reading Orientation",
+     SettingType::ENUM,
+     &CrossPointSettings::orientation,
+     {"Portrait", "Landscape CW", "Inverted", "Landscape CCW"}},
+    {"Check for updates", SettingType::ACTION, nullptr, {}},
+};
 }  // namespace
 
 void SettingsActivity::taskTrampoline(void* param) {
@@ -41,7 +49,7 @@ void SettingsActivity::onEnter() {
 }
 
 void SettingsActivity::onExit() {
-  Activity::onExit();
+  ActivityWithSubactivity::onExit();
 
   // Wait until not rendering to delete task to avoid killing mid-instruction to EPD
   xSemaphoreTake(renderingMutex, portMAX_DELAY);
@@ -54,6 +62,11 @@ void SettingsActivity::onExit() {
 }
 
 void SettingsActivity::loop() {
+  if (subActivity) {
+    subActivity->loop();
+    return;
+  }
+
   // Handle actions with early return
   if (inputManager.wasPressed(InputManager::BTN_CONFIRM)) {
     toggleCurrentSetting();
@@ -81,7 +94,7 @@ void SettingsActivity::loop() {
   }
 }
 
-void SettingsActivity::toggleCurrentSetting() const {
+void SettingsActivity::toggleCurrentSetting() {
   // Validate index
   if (selectedSettingIndex < 0 || selectedSettingIndex >= settingsCount) {
     return;
@@ -96,6 +109,16 @@ void SettingsActivity::toggleCurrentSetting() const {
   } else if (setting.type == SettingType::ENUM && setting.valuePtr != nullptr) {
     const uint8_t currentValue = SETTINGS.*(setting.valuePtr);
     SETTINGS.*(setting.valuePtr) = (currentValue + 1) % static_cast<uint8_t>(setting.enumValues.size());
+  } else if (setting.type == SettingType::ACTION) {
+    if (std::string(setting.name) == "Check for updates") {
+      xSemaphoreTake(renderingMutex, portMAX_DELAY);
+      exitActivity();
+      enterNewActivity(new OtaUpdateActivity(renderer, inputManager, [this] {
+        exitActivity();
+        updateRequired = true;
+      }));
+      xSemaphoreGive(renderingMutex);
+    }
   } else {
     // Only toggle if it's a toggle type and has a value pointer
     return;
@@ -107,7 +130,7 @@ void SettingsActivity::toggleCurrentSetting() const {
 
 void SettingsActivity::displayTaskLoop() {
   while (true) {
-    if (updateRequired) {
+    if (updateRequired && !subActivity) {
       updateRequired = false;
       xSemaphoreTake(renderingMutex, portMAX_DELAY);
       render();
@@ -120,8 +143,8 @@ void SettingsActivity::displayTaskLoop() {
 void SettingsActivity::render() const {
   renderer.clearScreen();
 
-  const auto pageWidth = GfxRenderer::getScreenWidth();
+  const auto pageWidth = renderer.getScreenWidth();
-  const auto pageHeight = GfxRenderer::getScreenHeight();
+  const auto pageHeight = renderer.getScreenHeight();
 
   // Draw header
   renderer.drawCenteredText(READER_FONT_ID, 10, "Settings", true, BOLD);
@@ -151,7 +174,9 @@ void SettingsActivity::render() const {
   }
 
   // Draw help text
-  renderer.drawText(SMALL_FONT_ID, 20, pageHeight - 30, "Press OK to toggle, BACK to save & exit");
+  renderer.drawButtonHints(UI_FONT_ID, "« Save", "Toggle", "", "");
+  renderer.drawText(SMALL_FONT_ID, pageWidth - 20 - renderer.getTextWidth(SMALL_FONT_ID, CROSSPOINT_VERSION),
+                    pageHeight - 30, CROSSPOINT_VERSION);
 
   // Always use standard refresh for settings screen
   renderer.displayBuffer();

src/activities/settings/SettingsActivity.h

@@ -3,16 +3,15 @@
 #include <freertos/semphr.h>
 #include <freertos/task.h>
 
-#include <cstdint>
 #include <functional>
 #include <string>
 #include <vector>
 
-#include "../Activity.h"
+#include "activities/ActivityWithSubactivity.h"
 
 class CrossPointSettings;
 
-enum class SettingType { TOGGLE, ENUM };
+enum class SettingType { TOGGLE, ENUM, ACTION };
 
 // Structure to hold setting information
 struct SettingInfo {
@@ -22,7 +21,7 @@ struct SettingInfo {
   std::vector<std::string> enumValues;
 };
 
-class SettingsActivity final : public Activity {
+class SettingsActivity final : public ActivityWithSubactivity {
   TaskHandle_t displayTaskHandle = nullptr;
   SemaphoreHandle_t renderingMutex = nullptr;
   bool updateRequired = false;
@@ -32,11 +31,11 @@ class SettingsActivity final : public Activity {
   static void taskTrampoline(void* param);
   [[noreturn]] void displayTaskLoop();
   void render() const;
-  void toggleCurrentSetting() const;
+  void toggleCurrentSetting();
 
  public:
   explicit SettingsActivity(GfxRenderer& renderer, InputManager& inputManager, const std::function<void()>& onGoHome)
-      : Activity("Settings", renderer, inputManager), onGoHome(onGoHome) {}
+      : ActivityWithSubactivity("Settings", renderer, inputManager), onGoHome(onGoHome) {}
   void onEnter() override;
   void onExit() override;
   void loop() override;

src/activities/util/FullScreenMessageActivity.cpp

@@ -8,7 +8,7 @@ void FullScreenMessageActivity::onEnter() {
   Activity::onEnter();
 
   const auto height = renderer.getLineHeight(UI_FONT_ID);
-  const auto top = (GfxRenderer::getScreenHeight() - height) / 2;
+  const auto top = (renderer.getScreenHeight() - height) / 2;
 
   renderer.clearScreen();
   renderer.drawCenteredText(UI_FONT_ID, top, text.c_str(), true, style);

src/activities/util/KeyboardEntryActivity.cpp

@@ -10,41 +10,55 @@ const char* const KeyboardEntryActivity::keyboard[NUM_ROWS] = {
 
 // Keyboard layouts - uppercase/symbols
 const char* const KeyboardEntryActivity::keyboardShift[NUM_ROWS] = {"~!@#$%^&*()_+", "QWERTYUIOP{}|", "ASDFGHJKL:\"",
-                                                                    "ZXCVBNM<>?", "^  _____<OK"};
+                                                                    "ZXCVBNM<>?", "SPECIAL ROW"};
 
-void KeyboardEntryActivity::setText(const std::string& newText) {
+void KeyboardEntryActivity::taskTrampoline(void* param) {
-  text = newText;
+  auto* self = static_cast<KeyboardEntryActivity*>(param);
-  if (maxLength > 0 && text.length() > maxLength) {
+  self->displayTaskLoop();
-    text.resize(maxLength);
-  }
 }
 
-void KeyboardEntryActivity::reset(const std::string& newTitle, const std::string& newInitialText) {
+void KeyboardEntryActivity::displayTaskLoop() {
-  if (!newTitle.empty()) {
+  while (true) {
-    title = newTitle;
+    if (updateRequired) {
+      updateRequired = false;
+      xSemaphoreTake(renderingMutex, portMAX_DELAY);
+      render();
+      xSemaphoreGive(renderingMutex);
+    }
+    vTaskDelay(10 / portTICK_PERIOD_MS);
   }
-  text = newInitialText;
-  selectedRow = 0;
-  selectedCol = 0;
-  shiftActive = false;
-  complete = false;
-  cancelled = false;
 }
 
 void KeyboardEntryActivity::onEnter() {
   Activity::onEnter();
 
-  // Reset state when entering the activity
+  renderingMutex = xSemaphoreCreateMutex();
-  complete = false;
+
-  cancelled = false;
+  // Trigger first update
+  updateRequired = true;
+
+  xTaskCreate(&KeyboardEntryActivity::taskTrampoline, "KeyboardEntryActivity",
+              2048,               // Stack size
+              this,               // Parameters
+              1,                  // Priority
+              &displayTaskHandle  // Task handle
+  );
 }
 
-void KeyboardEntryActivity::loop() {
+void KeyboardEntryActivity::onExit() {
-  handleInput();
+  Activity::onExit();
-  render(10);
+
+  // Wait until not rendering to delete task to avoid killing mid-instruction to EPD
+  xSemaphoreTake(renderingMutex, portMAX_DELAY);
+  if (displayTaskHandle) {
+    vTaskDelete(displayTaskHandle);
+    displayTaskHandle = nullptr;
+  }
+  vSemaphoreDelete(renderingMutex);
+  renderingMutex = nullptr;
 }
 
-int KeyboardEntryActivity::getRowLength(int row) const {
+int KeyboardEntryActivity::getRowLength(const int row) const {
   if (row < 0 || row >= NUM_ROWS) return 0;
 
   // Return actual length of each row based on keyboard layout
@@ -58,7 +72,7 @@ int KeyboardEntryActivity::getRowLength(int row) const {
     case 3:
       return 10;  // zxcvbnm,./
     case 4:
-      return 10;  // ^, space (5 wide), backspace, OK (2 wide)
+      return 10;  // caps (2 wide), space (5 wide), backspace (2 wide), OK
     default:
       return 0;
   }
@@ -75,8 +89,8 @@ char KeyboardEntryActivity::getSelectedChar() const {
 
 void KeyboardEntryActivity::handleKeyPress() {
   // Handle special row (bottom row with shift, space, backspace, done)
-  if (selectedRow == SHIFT_ROW) {
+  if (selectedRow == SPECIAL_ROW) {
-    if (selectedCol == SHIFT_COL) {
+    if (selectedCol >= SHIFT_COL && selectedCol < SPACE_COL) {
       // Shift toggle
       shiftActive = !shiftActive;
       return;
@@ -90,7 +104,7 @@ void KeyboardEntryActivity::handleKeyPress() {
       return;
     }
 
-    if (selectedCol == BACKSPACE_COL) {
+    if (selectedCol >= BACKSPACE_COL && selectedCol < DONE_COL) {
       // Backspace
       if (!text.empty()) {
         text.pop_back();
@@ -100,7 +114,6 @@ void KeyboardEntryActivity::handleKeyPress() {
 
     if (selectedCol >= DONE_COL) {
       // Done button
-      complete = true;
       if (onComplete) {
         onComplete(text);
       }
@@ -109,42 +122,61 @@ void KeyboardEntryActivity::handleKeyPress() {
   }
 
   // Regular character
-  char c = getSelectedChar();
+  const char c = getSelectedChar();
-  if (c != '\0' && c != '^' && c != '_' && c != '<') {
+  if (c == '\0') {
-    if (maxLength == 0 || text.length() < maxLength) {
+    return;
-      text += c;
+  }
-      // Auto-disable shift after typing a letter
+
-      if (shiftActive && ((c >= 'A' && c <= 'Z') || (c >= 'a' && c <= 'z'))) {
+  if (maxLength == 0 || text.length() < maxLength) {
-        shiftActive = false;
+    text += c;
-      }
+    // Auto-disable shift after typing a letter
+    if (shiftActive && ((c >= 'A' && c <= 'Z') || (c >= 'a' && c <= 'z'))) {
+      shiftActive = false;
     }
   }
 }
 
-bool KeyboardEntryActivity::handleInput() {
+void KeyboardEntryActivity::loop() {
-  if (complete || cancelled) {
-    return false;
-  }
-
-  bool handled = false;
-
   // Navigation
   if (inputManager.wasPressed(InputManager::BTN_UP)) {
     if (selectedRow > 0) {
       selectedRow--;
       // Clamp column to valid range for new row
-      int maxCol = getRowLength(selectedRow) - 1;
+      const int maxCol = getRowLength(selectedRow) - 1;
       if (selectedCol > maxCol) selectedCol = maxCol;
     }
-    handled = true;
+    updateRequired = true;
-  } else if (inputManager.wasPressed(InputManager::BTN_DOWN)) {
+  }
+
+  if (inputManager.wasPressed(InputManager::BTN_DOWN)) {
     if (selectedRow < NUM_ROWS - 1) {
       selectedRow++;
-      int maxCol = getRowLength(selectedRow) - 1;
+      const int maxCol = getRowLength(selectedRow) - 1;
       if (selectedCol > maxCol) selectedCol = maxCol;
     }
-    handled = true;
+    updateRequired = true;
-  } else if (inputManager.wasPressed(InputManager::BTN_LEFT)) {
+  }
+
+  if (inputManager.wasPressed(InputManager::BTN_LEFT)) {
+    // Special bottom row case
+    if (selectedRow == SPECIAL_ROW) {
+      // Bottom row has special key widths
+      if (selectedCol >= SHIFT_COL && selectedCol < SPACE_COL) {
+        // In shift key, do nothing
+      } else if (selectedCol >= SPACE_COL && selectedCol < BACKSPACE_COL) {
+        // In space bar, move to shift
+        selectedCol = SHIFT_COL;
+      } else if (selectedCol >= BACKSPACE_COL && selectedCol < DONE_COL) {
+        // In backspace, move to space
+        selectedCol = SPACE_COL;
+      } else if (selectedCol >= DONE_COL) {
+        // At done button, move to backspace
+        selectedCol = BACKSPACE_COL;
+      }
+      updateRequired = true;
+      return;
+    }
+
     if (selectedCol > 0) {
       selectedCol--;
     } else if (selectedRow > 0) {
@@ -152,9 +184,31 @@ bool KeyboardEntryActivity::handleInput() {
       selectedRow--;
       selectedCol = getRowLength(selectedRow) - 1;
     }
-    handled = true;
+    updateRequired = true;
-  } else if (inputManager.wasPressed(InputManager::BTN_RIGHT)) {
+  }
-    int maxCol = getRowLength(selectedRow) - 1;
+
+  if (inputManager.wasPressed(InputManager::BTN_RIGHT)) {
+    const int maxCol = getRowLength(selectedRow) - 1;
+
+    // Special bottom row case
+    if (selectedRow == SPECIAL_ROW) {
+      // Bottom row has special key widths
+      if (selectedCol >= SHIFT_COL && selectedCol < SPACE_COL) {
+        // In shift key, move to space
+        selectedCol = SPACE_COL;
+      } else if (selectedCol >= SPACE_COL && selectedCol < BACKSPACE_COL) {
+        // In space bar, move to backspace
+        selectedCol = BACKSPACE_COL;
+      } else if (selectedCol >= BACKSPACE_COL && selectedCol < DONE_COL) {
+        // In backspace, move to done
+        selectedCol = DONE_COL;
+      } else if (selectedCol >= DONE_COL) {
+        // At done button, do nothing
+      }
+      updateRequired = true;
+      return;
+    }
+
     if (selectedCol < maxCol) {
       selectedCol++;
     } else if (selectedRow < NUM_ROWS - 1) {
@@ -162,35 +216,34 @@ bool KeyboardEntryActivity::handleInput() {
       selectedRow++;
       selectedCol = 0;
     }
-    handled = true;
+    updateRequired = true;
   }
 
   // Selection
   if (inputManager.wasPressed(InputManager::BTN_CONFIRM)) {
     handleKeyPress();
-    handled = true;
+    updateRequired = true;
   }
 
   // Cancel
   if (inputManager.wasPressed(InputManager::BTN_BACK)) {
-    cancelled = true;
     if (onCancel) {
       onCancel();
     }
-    handled = true;
+    updateRequired = true;
   }
-
-  return handled;
 }
 
-void KeyboardEntryActivity::render(int startY) const {
+void KeyboardEntryActivity::render() const {
-  const auto pageWidth = GfxRenderer::getScreenWidth();
+  const auto pageWidth = renderer.getScreenWidth();
+
+  renderer.clearScreen();
 
   // Draw title
   renderer.drawCenteredText(UI_FONT_ID, startY, title.c_str(), true, REGULAR);
 
   // Draw input field
-  int inputY = startY + 22;
+  const int inputY = startY + 22;
   renderer.drawText(UI_FONT_ID, 10, inputY, "[");
 
   std::string displayText;
@@ -204,9 +257,9 @@ void KeyboardEntryActivity::render(int startY) const {
   displayText += "_";
 
   // Truncate if too long for display - use actual character width from font
-  int charWidth = renderer.getSpaceWidth(UI_FONT_ID);
+  int approxCharWidth = renderer.getSpaceWidth(UI_FONT_ID);
-  if (charWidth < 1) charWidth = 8;  // Fallback to approximate width
+  if (approxCharWidth < 1) approxCharWidth = 8;  // Fallback to approximate width
-  int maxDisplayLen = (pageWidth - 40) / charWidth;
+  const int maxDisplayLen = (pageWidth - 40) / approxCharWidth;
   if (displayText.length() > static_cast<size_t>(maxDisplayLen)) {
     displayText = "..." + displayText.substr(displayText.length() - maxDisplayLen + 3);
   }
@@ -215,22 +268,22 @@ void KeyboardEntryActivity::render(int startY) const {
   renderer.drawText(UI_FONT_ID, pageWidth - 15, inputY, "]");
 
   // Draw keyboard - use compact spacing to fit 5 rows on screen
-  int keyboardStartY = inputY + 25;
+  const int keyboardStartY = inputY + 25;
-  const int keyWidth = 18;
+  constexpr int keyWidth = 18;
-  const int keyHeight = 18;
+  constexpr int keyHeight = 18;
-  const int keySpacing = 3;
+  constexpr int keySpacing = 3;
 
   const char* const* layout = shiftActive ? keyboardShift : keyboard;
 
   // Calculate left margin to center the longest row (13 keys)
-  int maxRowWidth = KEYS_PER_ROW * (keyWidth + keySpacing);
+  constexpr int maxRowWidth = KEYS_PER_ROW * (keyWidth + keySpacing);
-  int leftMargin = (pageWidth - maxRowWidth) / 2;
+  const int leftMargin = (pageWidth - maxRowWidth) / 2;
 
   for (int row = 0; row < NUM_ROWS; row++) {
-    int rowY = keyboardStartY + row * (keyHeight + keySpacing);
+    const int rowY = keyboardStartY + row * (keyHeight + keySpacing);
 
     // Left-align all rows for consistent navigation
-    int startX = leftMargin;
+    const int startX = leftMargin;
 
     // Handle bottom row (row 4) specially with proper multi-column keys
     if (row == 4) {
@@ -240,69 +293,53 @@ void KeyboardEntryActivity::render(int startY) const {
       int currentX = startX;
 
       // CAPS key (logical col 0, spans 2 key widths)
-      int capsWidth = 2 * keyWidth + keySpacing;
+      const bool capsSelected = (selectedRow == 4 && selectedCol >= SHIFT_COL && selectedCol < SPACE_COL);
-      bool capsSelected = (selectedRow == 4 && selectedCol == SHIFT_COL);
+      renderItemWithSelector(currentX + 2, rowY, shiftActive ? "CAPS" : "caps", capsSelected);
-      if (capsSelected) {
+      currentX += 2 * (keyWidth + keySpacing);
-        renderer.drawText(UI_FONT_ID, currentX - 2, rowY, "[");
-        renderer.drawText(UI_FONT_ID, currentX + capsWidth - 4, rowY, "]");
-      }
-      renderer.drawText(UI_FONT_ID, currentX + 2, rowY, shiftActive ? "CAPS" : "caps");
-      currentX += capsWidth + keySpacing;
 
       // Space bar (logical cols 2-6, spans 5 key widths)
-      int spaceWidth = 5 * keyWidth + 4 * keySpacing;
+      const bool spaceSelected = (selectedRow == 4 && selectedCol >= SPACE_COL && selectedCol < BACKSPACE_COL);
-      bool spaceSelected = (selectedRow == 4 && selectedCol >= SPACE_COL && selectedCol < BACKSPACE_COL);
+      const int spaceTextWidth = renderer.getTextWidth(UI_FONT_ID, "_____");
-      if (spaceSelected) {
+      const int spaceXWidth = 5 * (keyWidth + keySpacing);
-        renderer.drawText(UI_FONT_ID, currentX - 2, rowY, "[");
+      const int spaceXPos = currentX + (spaceXWidth - spaceTextWidth) / 2;
-        renderer.drawText(UI_FONT_ID, currentX + spaceWidth - 4, rowY, "]");
+      renderItemWithSelector(spaceXPos, rowY, "_____", spaceSelected);
-      }
+      currentX += spaceXWidth;
-      // Draw centered underscores for space bar
-      int spaceTextX = currentX + (spaceWidth / 2) - 12;
-      renderer.drawText(UI_FONT_ID, spaceTextX, rowY, "_____");
-      currentX += spaceWidth + keySpacing;
 
       // Backspace key (logical col 7, spans 2 key widths)
-      int bsWidth = 2 * keyWidth + keySpacing;
+      const bool bsSelected = (selectedRow == 4 && selectedCol >= BACKSPACE_COL && selectedCol < DONE_COL);
-      bool bsSelected = (selectedRow == 4 && selectedCol == BACKSPACE_COL);
+      renderItemWithSelector(currentX + 2, rowY, "<-", bsSelected);
-      if (bsSelected) {
+      currentX += 2 * (keyWidth + keySpacing);
-        renderer.drawText(UI_FONT_ID, currentX - 2, rowY, "[");
-        renderer.drawText(UI_FONT_ID, currentX + bsWidth - 4, rowY, "]");
-      }
-      renderer.drawText(UI_FONT_ID, currentX + 6, rowY, "<-");
-      currentX += bsWidth + keySpacing;
 
       // OK button (logical col 9, spans 2 key widths)
-      int okWidth = 2 * keyWidth + keySpacing;
+      const bool okSelected = (selectedRow == 4 && selectedCol >= DONE_COL);
-      bool okSelected = (selectedRow == 4 && selectedCol >= DONE_COL);
+      renderItemWithSelector(currentX + 2, rowY, "OK", okSelected);
-      if (okSelected) {
-        renderer.drawText(UI_FONT_ID, currentX - 2, rowY, "[");
-        renderer.drawText(UI_FONT_ID, currentX + okWidth - 4, rowY, "]");
-      }
-      renderer.drawText(UI_FONT_ID, currentX + 8, rowY, "OK");
-
     } else {
       // Regular rows: render each key individually
       for (int col = 0; col < getRowLength(row); col++) {
-        int keyX = startX + col * (keyWidth + keySpacing);
-
         // Get the character to display
-        char c = layout[row][col];
+        const char c = layout[row][col];
         std::string keyLabel(1, c);
+        const int charWidth = renderer.getTextWidth(UI_FONT_ID, keyLabel.c_str());
 
-        // Draw selection highlight
+        const int keyX = startX + col * (keyWidth + keySpacing) + (keyWidth - charWidth) / 2;
-        bool isSelected = (row == selectedRow && col == selectedCol);
+        const bool isSelected = row == selectedRow && col == selectedCol;
-
+        renderItemWithSelector(keyX, rowY, keyLabel.c_str(), isSelected);
-        if (isSelected) {
-          renderer.drawText(UI_FONT_ID, keyX - 2, rowY, "[");
-          renderer.drawText(UI_FONT_ID, keyX + keyWidth - 4, rowY, "]");
-        }
-
-        renderer.drawText(UI_FONT_ID, keyX + 2, rowY, keyLabel.c_str());
       }
     }
   }
 
   // Draw help text at absolute bottom of screen (consistent with other screens)
-  const auto pageHeight = GfxRenderer::getScreenHeight();
+  const auto pageHeight = renderer.getScreenHeight();
   renderer.drawText(SMALL_FONT_ID, 10, pageHeight - 30, "Navigate: D-pad | Select: OK | Cancel: BACK");
+  renderer.displayBuffer();
+}
+
+void KeyboardEntryActivity::renderItemWithSelector(const int x, const int y, const char* item,
+                                                   const bool isSelected) const {
+  if (isSelected) {
+    const int itemWidth = renderer.getTextWidth(UI_FONT_ID, item);
+    renderer.drawText(UI_FONT_ID, x - 6, y, "[");
+    renderer.drawText(UI_FONT_ID, x + itemWidth, y, "]");
+  }
+  renderer.drawText(UI_FONT_ID, x, y, item);
 }

src/activities/util/KeyboardEntryActivity.h

@@ -1,9 +1,13 @@
 #pragma once
 #include <GfxRenderer.h>
 #include <InputManager.h>
+#include <freertos/FreeRTOS.h>
+#include <freertos/semphr.h>
+#include <freertos/task.h>
 
 #include <functional>
 #include <string>
+#include <utility>
 
 #include "../Activity.h"
 
@@ -30,80 +34,44 @@ class KeyboardEntryActivity : public Activity {
    * @param inputManager Reference to InputManager for handling input
    * @param title Title to display above the keyboard
    * @param initialText Initial text to show in the input field
+   * @param startY Y position to start rendering the keyboard
    * @param maxLength Maximum length of input text (0 for unlimited)
    * @param isPassword If true, display asterisks instead of actual characters
+   * @param onComplete Callback invoked when input is complete
+   * @param onCancel Callback invoked when input is cancelled
    */
-  KeyboardEntryActivity(GfxRenderer& renderer, InputManager& inputManager, const std::string& title = "Enter Text",
+  explicit KeyboardEntryActivity(GfxRenderer& renderer, InputManager& inputManager, std::string title = "Enter Text",
-                        const std::string& initialText = "", const size_t maxLength = 0, const bool isPassword = false)
+                                 std::string initialText = "", const int startY = 10, const size_t maxLength = 0,
+                                 const bool isPassword = false, OnCompleteCallback onComplete = nullptr,
+                                 OnCancelCallback onCancel = nullptr)
       : Activity("KeyboardEntry", renderer, inputManager),
-        title(title),
+        title(std::move(title)),
-        text(initialText),
+        text(std::move(initialText)),
+        startY(startY),
         maxLength(maxLength),
-        isPassword(isPassword) {}
+        isPassword(isPassword),
-
+        onComplete(std::move(onComplete)),
-  /**
+        onCancel(std::move(onCancel)) {}
-   * Handle button input. Call this in your main loop.
-   * @return true if input was handled, false otherwise
-   */
-  bool handleInput();
-
-  /**
-   * Render the keyboard at the specified Y position.
-   * @param startY Y-coordinate where keyboard rendering starts (default 10)
-   */
-  void render(int startY = 10) const;
-
-  /**
-   * Get the current text entered by the user.
-   */
-  const std::string& getText() const { return text; }
-
-  /**
-   * Set the current text.
-   */
-  void setText(const std::string& newText);
-
-  /**
-   * Check if the user has completed text entry (pressed OK on Done).
-   */
-  bool isComplete() const { return complete; }
-
-  /**
-   * Check if the user has cancelled text entry.
-   */
-  bool isCancelled() const { return cancelled; }
-
-  /**
-   * Reset the keyboard state for reuse.
-   */
-  void reset(const std::string& newTitle = "", const std::string& newInitialText = "");
-
-  /**
-   * Set callback for when input is complete.
-   */
-  void setOnComplete(OnCompleteCallback callback) { onComplete = callback; }
-
-  /**
-   * Set callback for when input is cancelled.
-   */
-  void setOnCancel(OnCancelCallback callback) { onCancel = callback; }
 
   // Activity overrides
   void onEnter() override;
+  void onExit() override;
   void loop() override;
 
  private:
   std::string title;
+  int startY;
   std::string text;
   size_t maxLength;
   bool isPassword;
+  TaskHandle_t displayTaskHandle = nullptr;
+  SemaphoreHandle_t renderingMutex = nullptr;
+  bool updateRequired = false;
 
   // Keyboard state
   int selectedRow = 0;
   int selectedCol = 0;
   bool shiftActive = false;
-  bool complete = false;
-  bool cancelled = false;
 
   // Callbacks
   OnCompleteCallback onComplete;
@@ -116,16 +84,17 @@ class KeyboardEntryActivity : public Activity {
   static const char* const keyboardShift[NUM_ROWS];
 
   // Special key positions (bottom row)
-  static constexpr int SHIFT_ROW = 4;
+  static constexpr int SPECIAL_ROW = 4;
   static constexpr int SHIFT_COL = 0;
-  static constexpr int SPACE_ROW = 4;
   static constexpr int SPACE_COL = 2;
-  static constexpr int BACKSPACE_ROW = 4;
   static constexpr int BACKSPACE_COL = 7;
-  static constexpr int DONE_ROW = 4;
   static constexpr int DONE_COL = 9;
 
+  static void taskTrampoline(void* param);
+  [[noreturn]] void displayTaskLoop();
   char getSelectedChar() const;
   void handleKeyPress();
   int getRowLength(int row) const;
+  void render() const;
+  void renderItemWithSelector(int x, int y, const char* item, bool isSelected) const;
 };

src/main.cpp

@@ -142,6 +142,7 @@ void onGoToReader(const std::string& initialEpubPath) {
   enterNewActivity(new ReaderActivity(renderer, inputManager, initialEpubPath, onGoHome));
 }
 void onGoToReaderHome() { onGoToReader(std::string()); }
+void onContinueReading() { onGoToReader(APP_STATE.openEpubPath); }
 
 void onGoToFileTransfer() {
   exitActivity();
@@ -155,12 +156,27 @@ void onGoToSettings() {
 
 void onGoHome() {
   exitActivity();
-  enterNewActivity(new HomeActivity(renderer, inputManager, onGoToReaderHome, onGoToSettings, onGoToFileTransfer));
+  enterNewActivity(new HomeActivity(renderer, inputManager, onContinueReading, onGoToReaderHome, onGoToSettings,
+                                    onGoToFileTransfer));
+}
+
+void setupDisplayAndFonts() {
+  einkDisplay.begin();
+  Serial.printf("[%lu] [   ] Display initialized\n", millis());
+  renderer.insertFont(READER_FONT_ID, bookerlyFontFamily);
+  renderer.insertFont(UI_FONT_ID, ubuntuFontFamily);
+  renderer.insertFont(SMALL_FONT_ID, smallFontFamily);
+  Serial.printf("[%lu] [   ] Fonts setup\n", millis());
 }
 
 void setup() {
   t1 = millis();
-  Serial.begin(115200);
+
+  // Only start serial if USB connected
+  pinMode(UART0_RXD, INPUT);
+  if (digitalRead(UART0_RXD) == HIGH) {
+    Serial.begin(115200);
+  }
 
   Serial.printf("[%lu] [   ] Starting CrossPoint version " CROSSPOINT_VERSION "\n", millis());
 
@@ -172,8 +188,10 @@ void setup() {
   SPI.begin(EPD_SCLK, SD_SPI_MISO, EPD_MOSI, EPD_CS);
 
   // SD Card Initialization
-  if (!SD.begin(SD_SPI_CS, SPI, SPI_FQ)) {
+  // We need 6 open files concurrently when parsing a new chapter
+  if (!SD.begin(SD_SPI_CS, SPI, SPI_FQ, "/sd", 6)) {
     Serial.printf("[%lu] [   ] SD card initialization failed\n", millis());
+    setupDisplayAndFonts();
     exitActivity();
     enterNewActivity(new FullScreenMessageActivity(renderer, inputManager, "SD card error", BOLD));
     return;
@@ -184,14 +202,7 @@ void setup() {
   // verify power button press duration after we've read settings.
   verifyWakeupLongPress();
 
-  // Initialize display
+  setupDisplayAndFonts();
-  einkDisplay.begin();
-  Serial.printf("[%lu] [   ] Display initialized\n", millis());
-
-  renderer.insertFont(READER_FONT_ID, bookerlyFontFamily);
-  renderer.insertFont(UI_FONT_ID, ubuntuFontFamily);
-  renderer.insertFont(SMALL_FONT_ID, smallFontFamily);
-  Serial.printf("[%lu] [   ] Fonts setup\n", millis());
 
   exitActivity();
   enterNewActivity(new BootActivity(renderer, inputManager));

src/network/CrossPointWebServer.cpp

@@ -1,6 +1,7 @@
 #include "CrossPointWebServer.h"
 
 #include <ArduinoJson.h>
+#include <FsHelpers.h>
 #include <SD.h>
 #include <WiFi.h>
 
@@ -30,12 +31,22 @@ void CrossPointWebServer::begin() {
     return;
   }
 
-  if (WiFi.status() != WL_CONNECTED) {
+  // Check if we have a valid network connection (either STA connected or AP mode)
-    Serial.printf("[%lu] [WEB] Cannot start webserver - WiFi not connected\n", millis());
+  const wifi_mode_t wifiMode = WiFi.getMode();
+  const bool isStaConnected = (wifiMode & WIFI_MODE_STA) && (WiFi.status() == WL_CONNECTED);
+  const bool isInApMode = (wifiMode & WIFI_MODE_AP) && (WiFi.softAPgetStationNum() >= 0);  // AP is running
+
+  if (!isStaConnected && !isInApMode) {
+    Serial.printf("[%lu] [WEB] Cannot start webserver - no valid network (mode=%d, status=%d)\n", millis(), wifiMode,
+                  WiFi.status());
     return;
   }
 
+  // Store AP mode flag for later use (e.g., in handleStatus)
+  apMode = isInApMode;
+
   Serial.printf("[%lu] [WEB] [MEM] Free heap before begin: %d bytes\n", millis(), ESP.getFreeHeap());
+  Serial.printf("[%lu] [WEB] Network mode: %s\n", millis(), apMode ? "AP" : "STA");
 
   Serial.printf("[%lu] [WEB] Creating web server on port %d...\n", millis(), port);
   server.reset(new WebServer(port));
@@ -70,7 +81,9 @@ void CrossPointWebServer::begin() {
   running = true;
 
   Serial.printf("[%lu] [WEB] Web server started on port %d\n", millis(), port);
-  Serial.printf("[%lu] [WEB] Access at http://%s/\n", millis(), WiFi.localIP().toString().c_str());
+  // Show the correct IP based on network mode
+  const String ipAddr = apMode ? WiFi.softAPIP().toString() : WiFi.localIP().toString();
+  Serial.printf("[%lu] [WEB] Access at http://%s/\n", millis(), ipAddr.c_str());
   Serial.printf("[%lu] [WEB] [MEM] Free heap after server.begin(): %d bytes\n", millis(), ESP.getFreeHeap());
 }
 
@@ -141,10 +154,14 @@ void CrossPointWebServer::handleNotFound() const {
 }
 
 void CrossPointWebServer::handleStatus() const {
+  // Get correct IP based on AP vs STA mode
+  const String ipAddr = apMode ? WiFi.softAPIP().toString() : WiFi.localIP().toString();
+
   String json = "{";
   json += "\"version\":\"" + String(CROSSPOINT_VERSION) + "\",";
-  json += "\"ip\":\"" + WiFi.localIP().toString() + "\",";
+  json += "\"ip\":\"" + ipAddr + "\",";
-  json += "\"rssi\":" + String(WiFi.RSSI()) + ",";
+  json += "\"mode\":\"" + String(apMode ? "AP" : "STA") + "\",";
+  json += "\"rssi\":" + String(apMode ? 0 : WiFi.RSSI()) + ",";  // RSSI not applicable in AP mode
   json += "\"freeHeap\":" + String(ESP.getFreeHeap()) + ",";
   json += "\"uptime\":" + String(millis() / 1000);
   json += "}";
@@ -323,8 +340,7 @@ void CrossPointWebServer::handleUpload() const {
     }
 
     // Open file for writing
-    uploadFile = SD.open(filePath.c_str(), FILE_WRITE);
+    if (!FsHelpers::openFileForWrite("WEB", filePath, uploadFile)) {
-    if (!uploadFile) {
       uploadError = "Failed to create file on SD card";
       Serial.printf("[%lu] [WEB] [UPLOAD] FAILED to create file: %s\n", millis(), filePath.c_str());
       return;

src/network/CrossPointWebServer.h

@@ -35,6 +35,7 @@ class CrossPointWebServer {
  private:
   std::unique_ptr<WebServer> server = nullptr;
   bool running = false;
+  bool apMode = false;  // true when running in AP mode, false for STA mode
   uint16_t port = 80;
 
   // File scanning

src/network/OtaUpdater.cpp

@@ -0,0 +1,174 @@
+#include "OtaUpdater.h"
+
+#include <ArduinoJson.h>
+#include <HTTPClient.h>
+#include <Update.h>
+#include <WiFiClientSecure.h>
+
+namespace {
+constexpr char latestReleaseUrl[] = "https://api.github.com/repos/daveallie/crosspoint-reader/releases/latest";
+}
+
+OtaUpdater::OtaUpdaterError OtaUpdater::checkForUpdate() {
+  const std::unique_ptr<WiFiClientSecure> client(new WiFiClientSecure);
+  client->setInsecure();
+  HTTPClient http;
+
+  Serial.printf("[%lu] [OTA] Fetching: %s\n", millis(), latestReleaseUrl);
+
+  http.begin(*client, latestReleaseUrl);
+  http.addHeader("User-Agent", "CrossPoint-ESP32-" CROSSPOINT_VERSION);
+
+  const int httpCode = http.GET();
+  if (httpCode != HTTP_CODE_OK) {
+    Serial.printf("[%lu] [OTA] HTTP error: %d\n", millis(), httpCode);
+    http.end();
+    return HTTP_ERROR;
+  }
+
+  JsonDocument doc;
+  JsonDocument filter;
+  filter["tag_name"] = true;
+  filter["assets"][0]["name"] = true;
+  filter["assets"][0]["browser_download_url"] = true;
+  filter["assets"][0]["size"] = true;
+  const DeserializationError error = deserializeJson(doc, *client, DeserializationOption::Filter(filter));
+  http.end();
+  if (error) {
+    Serial.printf("[%lu] [OTA] JSON parse failed: %s\n", millis(), error.c_str());
+    return JSON_PARSE_ERROR;
+  }
+
+  if (!doc["tag_name"].is<std::string>()) {
+    Serial.printf("[%lu] [OTA] No tag_name found\n", millis());
+    return JSON_PARSE_ERROR;
+  }
+  if (!doc["assets"].is<JsonArray>()) {
+    Serial.printf("[%lu] [OTA] No assets found\n", millis());
+    return JSON_PARSE_ERROR;
+  }
+
+  latestVersion = doc["tag_name"].as<std::string>();
+
+  for (int i = 0; i < doc["assets"].size(); i++) {
+    if (doc["assets"][i]["name"] == "firmware.bin") {
+      otaUrl = doc["assets"][i]["browser_download_url"].as<std::string>();
+      otaSize = doc["assets"][i]["size"].as<size_t>();
+      totalSize = otaSize;
+      updateAvailable = true;
+      break;
+    }
+  }
+
+  if (!updateAvailable) {
+    Serial.printf("[%lu] [OTA] No firmware.bin asset found\n", millis());
+    return NO_UPDATE;
+  }
+
+  Serial.printf("[%lu] [OTA] Found update: %s\n", millis(), latestVersion.c_str());
+  return OK;
+}
+
+bool OtaUpdater::isUpdateNewer() {
+  if (!updateAvailable || latestVersion.empty() || latestVersion == CROSSPOINT_VERSION) {
+    return false;
+  }
+
+  // semantic version check (only match on 3 segments)
+  const auto updateMajor = stoi(latestVersion.substr(0, latestVersion.find('.')));
+  const auto updateMinor = stoi(
+      latestVersion.substr(latestVersion.find('.') + 1, latestVersion.find_last_of('.') - latestVersion.find('.') - 1));
+  const auto updatePatch = stoi(latestVersion.substr(latestVersion.find_last_of('.') + 1));
+
+  std::string currentVersion = CROSSPOINT_VERSION;
+  const auto currentMajor = stoi(currentVersion.substr(0, currentVersion.find('.')));
+  const auto currentMinor = stoi(currentVersion.substr(
+      currentVersion.find('.') + 1, currentVersion.find_last_of('.') - currentVersion.find('.') - 1));
+  const auto currentPatch = stoi(currentVersion.substr(currentVersion.find_last_of('.') + 1));
+
+  if (updateMajor > currentMajor) {
+    return true;
+  }
+  if (updateMajor < currentMajor) {
+    return false;
+  }
+
+  if (updateMinor > currentMinor) {
+    return true;
+  }
+  if (updateMinor < currentMinor) {
+    return false;
+  }
+
+  if (updatePatch > currentPatch) {
+    return true;
+  }
+  return false;
+}
+
+const std::string& OtaUpdater::getLatestVersion() { return latestVersion; }
+
+OtaUpdater::OtaUpdaterError OtaUpdater::installUpdate(const std::function<void(size_t, size_t)>& onProgress) {
+  if (!isUpdateNewer()) {
+    return UPDATE_OLDER_ERROR;
+  }
+
+  const std::unique_ptr<WiFiClientSecure> client(new WiFiClientSecure);
+  client->setInsecure();
+  HTTPClient http;
+
+  Serial.printf("[%lu] [OTA] Fetching: %s\n", millis(), otaUrl.c_str());
+
+  http.begin(*client, otaUrl.c_str());
+  http.setFollowRedirects(HTTPC_STRICT_FOLLOW_REDIRECTS);
+  http.addHeader("User-Agent", "CrossPoint-ESP32-" CROSSPOINT_VERSION);
+  const int httpCode = http.GET();
+
+  if (httpCode != HTTP_CODE_OK) {
+    Serial.printf("[%lu] [OTA] Download failed: %d\n", millis(), httpCode);
+    http.end();
+    return HTTP_ERROR;
+  }
+
+  // 2. Get length and stream
+  const size_t contentLength = http.getSize();
+
+  if (contentLength != otaSize) {
+    Serial.printf("[%lu] [OTA] Invalid content length\n", millis());
+    http.end();
+    return HTTP_ERROR;
+  }
+
+  // 3. Begin the ESP-IDF Update process
+  if (!Update.begin(otaSize)) {
+    Serial.printf("[%lu] [OTA] Not enough space. Error: %s\n", millis(), Update.errorString());
+    http.end();
+    return INTERNAL_UPDATE_ERROR;
+  }
+
+  this->totalSize = otaSize;
+  Serial.printf("[%lu] [OTA] Update started\n", millis());
+  Update.onProgress([this, onProgress](const size_t progress, const size_t total) {
+    this->processedSize = progress;
+    this->totalSize = total;
+    onProgress(progress, total);
+  });
+  const size_t written = Update.writeStream(*client);
+  http.end();
+
+  if (written == otaSize) {
+    Serial.printf("[%lu] [OTA] Successfully written %u bytes\n", millis(), written);
+  } else {
+    Serial.printf("[%lu] [OTA] Written only %u/%u bytes. Error: %s\n", millis(), written, otaSize,
+                  Update.errorString());
+    return INTERNAL_UPDATE_ERROR;
+  }
+
+  if (Update.end() && Update.isFinished()) {
+    Serial.printf("[%lu] [OTA] Update complete\n", millis());
+    return OK;
+  } else {
+    Serial.printf("[%lu] [OTA] Error Occurred: %s\n", millis(), Update.errorString());
+    return INTERNAL_UPDATE_ERROR;
+  }
+}

src/network/OtaUpdater.h

@@ -0,0 +1,30 @@
+#pragma once
+
+#include <functional>
+#include <string>
+
+class OtaUpdater {
+  bool updateAvailable = false;
+  std::string latestVersion;
+  std::string otaUrl;
+  size_t otaSize = 0;
+
+ public:
+  enum OtaUpdaterError {
+    OK = 0,
+    NO_UPDATE,
+    HTTP_ERROR,
+    JSON_PARSE_ERROR,
+    UPDATE_OLDER_ERROR,
+    INTERNAL_UPDATE_ERROR,
+    OOM_ERROR,
+  };
+  size_t processedSize = 0;
+  size_t totalSize = 0;
+
+  OtaUpdater() = default;
+  bool isUpdateNewer();
+  const std::string& getLatestVersion();
+  OtaUpdaterError checkForUpdate();
+  OtaUpdaterError installUpdate(const std::function<void(size_t, size_t)>& onProgress);
+};