release: ef-1.0.5 - stability, memory, and upstream merges

Webserver: JSON batching, removed MD5 blocking, simplified flow control Memory: QR code caching, WiFi scan optimization, cover buffer leak fix EPUB: Fixed errant underlining before styled inline elements Flash screen: Version string overflow fix, half refresh for cleaner display Upstream merges: - PR #522: HAL abstraction layer (HalDisplay, HalGPIO) - PR #603: Sunlight fading fix toggle in Display settings
feat: implement sunlight fading fix (PR #603 )
2026-01-30 23:20:23 -05:00 · 2026-01-30 23:02:29 -05:00 · 2026-01-30 22:49:52 -05:00 · 2026-01-30 22:22:22 -05:00 · 2026-01-30 22:00:15 -05:00
41 changed files with 1076 additions and 530 deletions
--- a/ef-CHANGELOG.md
+++ b/ef-CHANGELOG.md
@ -6,6 +6,62 @@ Base: CrossPoint Reader 0.15.0

 ---

+## ef-1.0.5
+
+**Stability & Memory Improvements**
+
+### Bug Fixes - Webserver
+
+- **File Transfer Stability**: Removed blocking MD5 hash computation from file listings that caused EAGAIN errors and connection stalls
+- **JSON Batching**: Implemented 2KB batch streaming for file listings with pacing to prevent TCP buffer overflow
+- **Simplified Flow Control**: Removed unnecessary yield/delay logic from content streaming
+
+### Bug Fixes - Memory
+
+- **QR Code Caching**: Generate QR codes once on server start instead of regenerating on each screen render
+- **WiFi Scan Optimization**: Replaced memory-heavy `std::map` deduplication with in-place vector search, limited results to 20 networks, earlier `WiFi.scanDelete()` for faster memory recovery
+- **Cover Buffer Leak**: Fixed 48KB memory leak when navigating from Home to File Transfer (cover buffer now explicitly freed)
+
+### Bug Fixes - EPUB Reader
+
+- **Errant Underlining**: Fixed words before styled inline elements (like `<a>` tags with CSS underline) incorrectly receiving the element's style by flushing the text buffer before style changes
+
+### Bug Fixes - Flashing Screen
+
+- **Version String Overflow**: Fixed flash notification parsing failing on longer version strings (buffer limit increased from 30 to 50 characters)
+- **Display Quality**: Changed flashing screen to half refresh for cleaner appearance
+- **Timing**: Adjusted pre-flash script timing for half refresh completion
+
+### Upstream Merges
+
+- **PR #522 - HAL Abstraction Layer**: Merged hardware abstraction layer refactor introducing `HalDisplay` and `HalGPIO` classes, decoupling application code from direct hardware access
+- **PR #603 - Sunlight Fading Fix**: Added user-toggleable setting to turn off display between refreshes, mitigating the sunlight fading issue on e-ink displays
+  - New "Sunlight Fading Fix" toggle in Display settings (OFF/ON)
+  - Passes `turnOffScreen` parameter through display stack when enabled
+
+### Files Changed
+
+- `src/main.cpp` - flash screen fixes, cover buffer free on File Transfer entry, fading fix integration
+- `scripts/pre_flash.py` - timing adjustments for full refresh
+- `src/network/CrossPointWebServer.cpp` - JSON batching, removed MD5 from listings
+- `src/network/CrossPointWebServer.h` - removed md5 from FileInfo, simplified sendContentSafe
+- `src/activities/network/CrossPointWebServerActivity.cpp` - QR code caching
+- `src/activities/network/CrossPointWebServerActivity.h` - QR code cache members
+- `src/activities/network/WifiSelectionActivity.cpp` - WiFi scan memory optimization
+- `lib/Epub/Epub/parsers/ChapterHtmlSlimParser.cpp` - flush buffer before style changes
+- `lib/hal/HalDisplay.h` - new HAL abstraction for display (PR #522), turnOffScreen parameter (PR #603)
+- `lib/hal/HalDisplay.cpp` - HAL display implementation with fading fix passthrough
+- `lib/hal/HalGPIO.h` - new HAL abstraction for GPIO (PR #522)
+- `lib/hal/HalGPIO.cpp` - HAL GPIO implementation
+- `lib/GfxRenderer/GfxRenderer.h` - updated for HAL layer, added fadingFix member
+- `lib/GfxRenderer/GfxRenderer.cpp` - updated for HAL layer, passes fadingFix to display
+- `src/CrossPointSettings.h` - added fadingFix setting
+- `src/CrossPointSettings.cpp` - fadingFix persistence
+- `src/activities/settings/SettingsActivity.cpp` - added Sunlight Fading Fix toggle
+- `open-x4-sdk` - updated submodule with turnOffScreen support in EInkDisplay
+
+---
+
 ## ef-1.0.4

 **EPUB Rendering & Stability**
--- a/lib/Epub/Epub/ParsedText.cpp
+++ b/lib/Epub/Epub/ParsedText.cpp
@ -380,19 +380,15 @@ void ParsedText::extractLine(const size_t breakIndex, const int pageWidth, const

  // *** CRITICAL STEP: CONSUME DATA USING MOVE + ERASE ***
  // Move first lineWordCount elements from words into lineWords
-  std::vector<std::string> lineWords(
-      std::make_move_iterator(words.begin()),
-      std::make_move_iterator(words.begin() + lineWordCount));
+  std::vector<std::string> lineWords(std::make_move_iterator(words.begin()),
+                                     std::make_move_iterator(words.begin() + lineWordCount));
  words.erase(words.begin(), words.begin() + lineWordCount);

-  std::vector<EpdFontFamily::Style> lineWordStyles(
-      std::make_move_iterator(wordStyles.begin()),
-      std::make_move_iterator(wordStyles.begin() + lineWordCount));
+  std::vector<EpdFontFamily::Style> lineWordStyles(std::make_move_iterator(wordStyles.begin()),
+                                                   std::make_move_iterator(wordStyles.begin() + lineWordCount));
  wordStyles.erase(wordStyles.begin(), wordStyles.begin() + lineWordCount);

-  std::vector<bool> lineWordUnderlines(
-      wordUnderlines.begin(),
-      wordUnderlines.begin() + lineWordCount);
+  std::vector<bool> lineWordUnderlines(wordUnderlines.begin(), wordUnderlines.begin() + lineWordCount);
  wordUnderlines.erase(wordUnderlines.begin(), wordUnderlines.begin() + lineWordCount);

  for (auto& word : lineWords) {
--- a/lib/Epub/Epub/blocks/BlockStyle.h
+++ b/lib/Epub/Epub/blocks/BlockStyle.h
@ -9,11 +9,11 @@
 * Padding is treated similarly to margins for rendering purposes.
 */
 struct BlockStyle {
-  int8_t marginTop = 0;      // 0-2 lines
-  int8_t marginBottom = 0;   // 0-2 lines
-  int8_t paddingTop = 0;     // 0-2 lines (treated same as margin)
-  int8_t paddingBottom = 0;  // 0-2 lines (treated same as margin)
-  int16_t textIndent = 0;    // pixels (first line indent)
-  int16_t marginLeft = 0;    // pixels (horizontal indent for entire block)
+  int8_t marginTop = 0;        // 0-2 lines
+  int8_t marginBottom = 0;     // 0-2 lines
+  int8_t paddingTop = 0;       // 0-2 lines (treated same as margin)
+  int8_t paddingBottom = 0;    // 0-2 lines (treated same as margin)
+  int16_t textIndent = 0;      // pixels (first line indent)
+  int16_t marginLeft = 0;      // pixels (horizontal indent for entire block)
  bool hasLeftBorder = false;  // draw vertical bar in left margin (for blockquotes)
 };
--- a/lib/Epub/Epub/blocks/TextBlock.h
+++ b/lib/Epub/Epub/blocks/TextBlock.h
@ -2,9 +2,9 @@
 #include <EpdFontFamily.h>
 #include <SdFat.h>

-#include <vector>
 #include <memory>
 #include <string>
+#include <vector>

 #include "Block.h"
 #include "BlockStyle.h"
@ -30,7 +30,8 @@ class TextBlock final : public Block {
 public:
  explicit TextBlock(std::vector<std::string> words, std::vector<uint16_t> word_xpos,
                     std::vector<EpdFontFamily::Style> word_styles, const Style style,
-                     const BlockStyle& blockStyle = BlockStyle(), std::vector<bool> word_underlines = std::vector<bool>())
+                     const BlockStyle& blockStyle = BlockStyle(),
+                     std::vector<bool> word_underlines = std::vector<bool>())
      : words(std::move(words)),
        wordXpos(std::move(word_xpos)),
        wordStyles(std::move(word_styles)),
--- a/lib/Epub/Epub/parsers/ChapterHtmlSlimParser.cpp
+++ b/lib/Epub/Epub/parsers/ChapterHtmlSlimParser.cpp
@ -485,6 +485,9 @@ void XMLCALL ChapterHtmlSlimParser::startElement(void* userData, const XML_Char*
      }
    }
  } else if (matches(name, UNDERLINE_TAGS, NUM_UNDERLINE_TAGS)) {
+    // Flush buffer with CURRENT style before changing effective style
+    self->flushPartWordBuffer();
+
    self->underlineUntilDepth = std::min(self->underlineUntilDepth, self->depth);
    // Push inline style entry for underline tag
    StyleStackEntry entry;
@ -502,6 +505,9 @@ void XMLCALL ChapterHtmlSlimParser::startElement(void* userData, const XML_Char*
    self->inlineStyleStack.push_back(entry);
    self->updateEffectiveInlineStyle();
  } else if (matches(name, BOLD_TAGS, NUM_BOLD_TAGS)) {
+    // Flush buffer with CURRENT style before changing effective style
+    self->flushPartWordBuffer();
+
    self->boldUntilDepth = std::min(self->boldUntilDepth, self->depth);
    // Push inline style entry for bold tag
    StyleStackEntry entry;
@ -519,6 +525,9 @@ void XMLCALL ChapterHtmlSlimParser::startElement(void* userData, const XML_Char*
    self->inlineStyleStack.push_back(entry);
    self->updateEffectiveInlineStyle();
  } else if (matches(name, ITALIC_TAGS, NUM_ITALIC_TAGS)) {
+    // Flush buffer with CURRENT style before changing effective style
+    self->flushPartWordBuffer();
+
    self->italicUntilDepth = std::min(self->italicUntilDepth, self->depth);
    // Push inline style entry for italic tag
    StyleStackEntry entry;
@ -538,6 +547,10 @@ void XMLCALL ChapterHtmlSlimParser::startElement(void* userData, const XML_Char*
  } else if (strcmp(name, "span") == 0 || !isBlockElement) {
    // Handle span and other inline elements for CSS styling
    if (cssStyle.hasFontWeight() || cssStyle.hasFontStyle() || cssStyle.hasTextDecoration()) {
+      // Flush buffer with CURRENT style before changing effective style
+      // This prevents text accumulated before this element from getting the new style
+      self->flushPartWordBuffer();
+
      StyleStackEntry entry;
      entry.depth = self->depth;  // Track depth for matching pop
      if (cssStyle.hasFontWeight()) {
@ -573,6 +586,33 @@ void XMLCALL ChapterHtmlSlimParser::characterData(void* userData, const XML_Char
    self->lastCharDataOffset = XML_GetCurrentByteIndex(self->xmlParser);
  }

+  // If we're inside an <li> but no text block was created yet (direct text without inner <p>),
+  // create a text block and add the list marker now
+  if (self->insideListItem && !self->listItemHasContent) {
+    // Apply left margin for list items
+    CssStyle cssStyle;
+    cssStyle.marginLeft = 24.0f;  // Default indent (~1.5em at 16px base)
+    cssStyle.defined.marginLeft = 1;
+
+    BlockStyle blockStyle = createBlockStyleFromCss(cssStyle);
+    self->startNewTextBlock(static_cast<TextBlock::Style>(self->paragraphAlignment), blockStyle);
+
+    // Add the list marker
+    if (!self->listStack.empty()) {
+      const ListContext& ctx = self->listStack.back();
+      if (ctx.isOrdered) {
+        std::string marker = std::to_string(ctx.counter) + ". ";
+        self->currentTextBlock->addWord(marker, EpdFontFamily::REGULAR);
+      } else {
+        self->currentTextBlock->addWord("\xe2\x80\xa2", EpdFontFamily::REGULAR);
+      }
+    } else {
+      // No list context (orphan li), use bullet as fallback
+      self->currentTextBlock->addWord("\xe2\x80\xa2", EpdFontFamily::REGULAR);
+    }
+    self->listItemHasContent = true;
+  }
+
  // Determine font style from depth-based tracking and CSS effective style
  const bool isBold = self->boldUntilDepth < self->depth || self->effectiveBold;
  const bool isItalic = self->italicUntilDepth < self->depth || self->effectiveItalic;
--- a/lib/GfxRenderer/GfxRenderer.cpp
+++ b/lib/GfxRenderer/GfxRenderer.cpp
@ -10,19 +10,19 @@ void GfxRenderer::rotateCoordinates(const int x, const int y, int* rotatedX, int
      // Logical portrait (480x800) → panel (800x480)
      // Rotation: 90 degrees clockwise
      *rotatedX = y;
-      *rotatedY = EInkDisplay::DISPLAY_HEIGHT - 1 - x;
+      *rotatedY = HalDisplay::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;
+      *rotatedX = HalDisplay::DISPLAY_WIDTH - 1 - x;
+      *rotatedY = HalDisplay::DISPLAY_HEIGHT - 1 - y;
      break;
    }
    case PortraitInverted: {
      // Logical portrait (480x800) → panel (800x480)
      // Rotation: 90 degrees counter-clockwise
-      *rotatedX = EInkDisplay::DISPLAY_WIDTH - 1 - y;
+      *rotatedX = HalDisplay::DISPLAY_WIDTH - 1 - y;
      *rotatedY = x;
      break;
    }
@ -36,7 +36,7 @@ void GfxRenderer::rotateCoordinates(const int x, const int y, int* rotatedX, int
 }

 void GfxRenderer::drawPixel(const int x, const int y, const bool state) const {
-  uint8_t* frameBuffer = einkDisplay.getFrameBuffer();
+  uint8_t* frameBuffer = display.getFrameBuffer();

  // Early return if no framebuffer is set
  if (!frameBuffer) {
@ -49,14 +49,13 @@ void GfxRenderer::drawPixel(const int x, const int y, const bool state) const {
  rotateCoordinates(x, y, &rotatedX, &rotatedY);

  // Bounds checking against physical panel dimensions
-  if (rotatedX < 0 || rotatedX >= EInkDisplay::DISPLAY_WIDTH || rotatedY < 0 ||
-      rotatedY >= EInkDisplay::DISPLAY_HEIGHT) {
+  if (rotatedX < 0 || rotatedX >= HalDisplay::DISPLAY_WIDTH || rotatedY < 0 || rotatedY >= HalDisplay::DISPLAY_HEIGHT) {
    Serial.printf("[%lu] [GFX] !! Outside range (%d, %d) -> (%d, %d)\n", millis(), x, y, rotatedX, rotatedY);
    return;
  }

  // Calculate byte position and bit position
-  const uint16_t byteIndex = rotatedY * EInkDisplay::DISPLAY_WIDTH_BYTES + (rotatedX / 8);
+  const uint16_t byteIndex = rotatedY * HalDisplay::DISPLAY_WIDTH_BYTES + (rotatedX / 8);
  const uint8_t bitPosition = 7 - (rotatedX % 8);  // MSB first

  if (state) {
@ -202,7 +201,7 @@ void GfxRenderer::drawImage(const uint8_t bitmap[], const int x, const int y, co
      break;
  }
  // TODO: Rotate bits
-  einkDisplay.drawImage(bitmap, rotatedX, rotatedY, width, height);
+  display.drawImage(bitmap, rotatedX, rotatedY, width, height);
 }

 void GfxRenderer::drawImageRotated(const uint8_t bitmap[], const int x, const int y, const int width, const int height,
@ -519,21 +518,21 @@ void GfxRenderer::fillPolygon(const int* xPoints, const int* yPoints, int numPoi
  free(nodeX);
 }

-void GfxRenderer::clearScreen(const uint8_t color) const { einkDisplay.clearScreen(color); }
+void GfxRenderer::clearScreen(const uint8_t color) const { display.clearScreen(color); }

 void GfxRenderer::invertScreen() const {
-  uint8_t* buffer = einkDisplay.getFrameBuffer();
+  uint8_t* buffer = display.getFrameBuffer();
  if (!buffer) {
    Serial.printf("[%lu] [GFX] !! No framebuffer in invertScreen\n", millis());
    return;
  }
-  for (int i = 0; i < EInkDisplay::BUFFER_SIZE; i++) {
+  for (int i = 0; i < HalDisplay::BUFFER_SIZE; i++) {
    buffer[i] = ~buffer[i];
  }
 }

-void GfxRenderer::displayBuffer(const EInkDisplay::RefreshMode refreshMode) const {
-  einkDisplay.displayBuffer(refreshMode);
+void GfxRenderer::displayBuffer(const HalDisplay::RefreshMode refreshMode) const {
+  display.displayBuffer(refreshMode, fadingFix);
 }

 std::string GfxRenderer::truncatedText(const int fontId, const char* text, const int maxWidth,
@ -553,13 +552,13 @@ int GfxRenderer::getScreenWidth() const {
    case Portrait:
    case PortraitInverted:
      // 480px wide in portrait logical coordinates
-      return EInkDisplay::DISPLAY_HEIGHT;
+      return HalDisplay::DISPLAY_HEIGHT;
    case LandscapeClockwise:
    case LandscapeCounterClockwise:
      // 800px wide in landscape logical coordinates
-      return EInkDisplay::DISPLAY_WIDTH;
+      return HalDisplay::DISPLAY_WIDTH;
  }
-  return EInkDisplay::DISPLAY_HEIGHT;
+  return HalDisplay::DISPLAY_HEIGHT;
 }

 int GfxRenderer::getScreenHeight() const {
@ -567,13 +566,13 @@ int GfxRenderer::getScreenHeight() const {
    case Portrait:
    case PortraitInverted:
      // 800px tall in portrait logical coordinates
-      return EInkDisplay::DISPLAY_WIDTH;
+      return HalDisplay::DISPLAY_WIDTH;
    case LandscapeClockwise:
    case LandscapeCounterClockwise:
      // 480px tall in landscape logical coordinates
-      return EInkDisplay::DISPLAY_HEIGHT;
+      return HalDisplay::DISPLAY_HEIGHT;
  }
-  return EInkDisplay::DISPLAY_WIDTH;
+  return HalDisplay::DISPLAY_WIDTH;
 }

 int GfxRenderer::getSpaceWidth(const int fontId) const {
@ -902,17 +901,18 @@ void GfxRenderer::drawTextRotated90CCW(const int fontId, const int x, const int
  }
 }

-uint8_t* GfxRenderer::getFrameBuffer() const { return einkDisplay.getFrameBuffer(); }
+uint8_t* GfxRenderer::getFrameBuffer() const { return display.getFrameBuffer(); }

-size_t GfxRenderer::getBufferSize() { return EInkDisplay::BUFFER_SIZE; }
+size_t GfxRenderer::getBufferSize() { return HalDisplay::BUFFER_SIZE; }

-void GfxRenderer::grayscaleRevert() const { einkDisplay.grayscaleRevert(); }
+// unused
+// void GfxRenderer::grayscaleRevert() const { display.grayscaleRevert(); }

-void GfxRenderer::copyGrayscaleLsbBuffers() const { einkDisplay.copyGrayscaleLsbBuffers(einkDisplay.getFrameBuffer()); }
+void GfxRenderer::copyGrayscaleLsbBuffers() const { display.copyGrayscaleLsbBuffers(display.getFrameBuffer()); }

-void GfxRenderer::copyGrayscaleMsbBuffers() const { einkDisplay.copyGrayscaleMsbBuffers(einkDisplay.getFrameBuffer()); }
+void GfxRenderer::copyGrayscaleMsbBuffers() const { display.copyGrayscaleMsbBuffers(display.getFrameBuffer()); }

-void GfxRenderer::displayGrayBuffer() const { einkDisplay.displayGrayBuffer(); }
+void GfxRenderer::displayGrayBuffer() const { display.displayGrayBuffer(fadingFix); }

 void GfxRenderer::freeBwBufferChunks() {
  for (auto& bwBufferChunk : bwBufferChunks) {
@ -930,7 +930,7 @@ void GfxRenderer::freeBwBufferChunks() {
 * Returns true if buffer was stored successfully, false if allocation failed.
 */
 bool GfxRenderer::storeBwBuffer() {
-  const uint8_t* frameBuffer = einkDisplay.getFrameBuffer();
+  const uint8_t* frameBuffer = display.getFrameBuffer();
  if (!frameBuffer) {
    Serial.printf("[%lu] [GFX] !! No framebuffer in storeBwBuffer\n", millis());
    return false;
@ -985,14 +985,14 @@ void GfxRenderer::restoreBwBuffer() {
    // CRITICAL: Even if restore fails, we must clean up the grayscale state
    // to prevent grayscaleRevert() from being called with corrupted RAM state
    // Use the current framebuffer content (which may not be ideal but prevents worse issues)
-    uint8_t* frameBuffer = einkDisplay.getFrameBuffer();
+    uint8_t* frameBuffer = display.getFrameBuffer();
    if (frameBuffer) {
-      einkDisplay.cleanupGrayscaleBuffers(frameBuffer);
+      display.cleanupGrayscaleBuffers(frameBuffer);
    }
    return;
  }

-  uint8_t* frameBuffer = einkDisplay.getFrameBuffer();
+  uint8_t* frameBuffer = display.getFrameBuffer();
  if (!frameBuffer) {
    Serial.printf("[%lu] [GFX] !! No framebuffer in restoreBwBuffer\n", millis());
    freeBwBufferChunks();
@ -1005,7 +1005,7 @@ void GfxRenderer::restoreBwBuffer() {
      Serial.printf("[%lu] [GFX] !! BW buffer chunks not stored - this is likely a bug\n", millis());
      freeBwBufferChunks();
      // CRITICAL: Clean up grayscale state even on mid-restore failure
-      einkDisplay.cleanupGrayscaleBuffers(frameBuffer);
+      display.cleanupGrayscaleBuffers(frameBuffer);
      return;
    }

@ -1013,7 +1013,7 @@ void GfxRenderer::restoreBwBuffer() {
    memcpy(frameBuffer + offset, bwBufferChunks[i], BW_BUFFER_CHUNK_SIZE);
  }

-  einkDisplay.cleanupGrayscaleBuffers(frameBuffer);
+  display.cleanupGrayscaleBuffers(frameBuffer);

  freeBwBufferChunks();
  Serial.printf("[%lu] [GFX] Restored and freed BW buffer chunks\n", millis());
@ -1024,9 +1024,9 @@ void GfxRenderer::restoreBwBuffer() {
 * Use this when BW buffer was re-rendered instead of stored/restored.
 */
 void GfxRenderer::cleanupGrayscaleWithFrameBuffer() const {
-  uint8_t* frameBuffer = einkDisplay.getFrameBuffer();
+  uint8_t* frameBuffer = display.getFrameBuffer();
  if (frameBuffer) {
-    einkDisplay.cleanupGrayscaleBuffers(frameBuffer);
+    display.cleanupGrayscaleBuffers(frameBuffer);
  }
 }

--- a/lib/GfxRenderer/GfxRenderer.h
+++ b/lib/GfxRenderer/GfxRenderer.h
@ -1,7 +1,7 @@
 #pragma once

-#include <EInkDisplay.h>
 #include <EpdFontFamily.h>
+#include <HalDisplay.h>

 #include <map>

@ -24,8 +24,8 @@ class GfxRenderer {

 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;
-  static_assert(BW_BUFFER_CHUNK_SIZE * BW_BUFFER_NUM_CHUNKS == EInkDisplay::BUFFER_SIZE,
+  static constexpr size_t BW_BUFFER_NUM_CHUNKS = HalDisplay::BUFFER_SIZE / BW_BUFFER_CHUNK_SIZE;
+  static_assert(BW_BUFFER_CHUNK_SIZE * BW_BUFFER_NUM_CHUNKS == HalDisplay::BUFFER_SIZE,
                "BW buffer chunking does not line up with display buffer size");

  // Base viewable margins (hardware-specific, before bezel compensation)
@ -34,9 +34,10 @@ class GfxRenderer {
  static constexpr int BASE_VIEWABLE_MARGIN_BOTTOM = 3;
  static constexpr int BASE_VIEWABLE_MARGIN_LEFT = 3;

-  EInkDisplay& einkDisplay;
+  HalDisplay& display;
  RenderMode renderMode;
  Orientation orientation;
+  bool fadingFix = false;     // Sunlight fading fix - turn off screen after refresh
  int bezelCompensation = 0;  // Pixels to add for bezel defect compensation
  int bezelEdge = 0;          // Which physical edge (0=bottom, 1=top, 2=left, 3=right in portrait)
  uint8_t* bwBufferChunks[BW_BUFFER_NUM_CHUNKS] = {nullptr};
@ -47,7 +48,7 @@ class GfxRenderer {
  void rotateCoordinates(int x, int y, int* rotatedX, int* rotatedY) const;

 public:
-  explicit GfxRenderer(EInkDisplay& einkDisplay) : einkDisplay(einkDisplay), renderMode(BW), orientation(Portrait) {}
+  explicit GfxRenderer(HalDisplay& halDisplay) : display(halDisplay), renderMode(BW), orientation(Portrait) {}
  ~GfxRenderer() { freeBwBufferChunks(); }

  // Viewable margins (includes bezel compensation applied to the configured edge)
@ -76,10 +77,13 @@ class GfxRenderer {
  void setOrientation(const Orientation o) { orientation = o; }
  Orientation getOrientation() const { return orientation; }

+  // Fading fix control
+  void setFadingFix(const bool enabled) { fadingFix = enabled; }
+
  // Screen ops
  int getScreenWidth() const;
  int getScreenHeight() const;
-  void displayBuffer(EInkDisplay::RefreshMode refreshMode = EInkDisplay::FAST_REFRESH) const;
+  void displayBuffer(HalDisplay::RefreshMode refreshMode = HalDisplay::FAST_REFRESH) const;
  // EXPERIMENTAL: Windowed update - display only a rectangular region
  void displayWindow(int x, int y, int width, int height) const;
  void invertScreen() const;
--- a/lib/StarDict/StarDict.cpp
+++ b/lib/StarDict/StarDict.cpp
@ -299,8 +299,7 @@ bool StarDict::decompressDefinition(uint32_t offset, uint32_t size, std::string&
  const uint32_t endChunk = (offset + size - 1) / dzInfo.chunkLength;
  const uint32_t startOffsetInChunk = offset % dzInfo.chunkLength;

-  Serial.printf("[DICT-DBG] Chunks: start=%lu, end=%lu, total=%u\n", 
-                startChunk, endChunk, dzInfo.chunkCount);
+  Serial.printf("[DICT-DBG] Chunks: start=%lu, end=%lu, total=%u\n", startChunk, endChunk, dzInfo.chunkCount);

  if (endChunk >= dzInfo.chunkCount) {
    Serial.printf("[DICT-DBG] endChunk %lu >= chunkCount %u\n", endChunk, dzInfo.chunkCount);
@ -324,16 +323,16 @@ bool StarDict::decompressDefinition(uint32_t offset, uint32_t size, std::string&

  // Allocate buffers - allocate inflator FIRST (smallest) to reduce fragmentation impact
  // tinfl_decompressor is ~11KB, so total allocations are ~85KB
-  Serial.printf("[DICT-DBG] Allocating inflator=%u, comp=%lu, decomp=%u bytes\n", 
-                sizeof(tinfl_decompressor), maxCompressedSize, dzInfo.chunkLength);
-  
+  Serial.printf("[DICT-DBG] Allocating inflator=%u, comp=%lu, decomp=%u bytes\n", sizeof(tinfl_decompressor),
+                maxCompressedSize, dzInfo.chunkLength);
+
  auto* inflator = static_cast<tinfl_decompressor*>(malloc(sizeof(tinfl_decompressor)));
  if (!inflator) {
    Serial.printf("[DICT-DBG] inflator alloc failed! (need %u bytes)\n", sizeof(tinfl_decompressor));
    file.close();
    return false;
  }
-  
+
  auto* compressedBuf = static_cast<uint8_t*>(malloc(maxCompressedSize));
  if (!compressedBuf) {
    Serial.printf("[DICT-DBG] compressedBuf alloc failed!\n");
@ -469,8 +468,7 @@ StarDict::LookupResult StarDict::lookup(const std::string& word) {
    return result;
  }

-  Serial.printf("[DICT-DBG] Searching for: '%s' (normalized: '%s')\n", 
-                word.c_str(), normalizedSearch.c_str());
+  Serial.printf("[DICT-DBG] Searching for: '%s' (normalized: '%s')\n", word.c_str(), normalizedSearch.c_str());

  // First try .idx (main entries) - use prefix jump table for fast lookup
  const std::string idxPath = basePath + ".idx";
@ -487,8 +485,8 @@ StarDict::LookupResult StarDict::lookup(const std::string& word) {
    const uint16_t prefixIdx = DictPrefixIndex::prefixToIndex(normalizedSearch[0], normalizedSearch[1]);
    position = DictPrefixIndex::dictPrefixOffsets[prefixIdx];
  }
-  Serial.printf("[DICT-DBG] Starting at position %lu (prefix: %c%c)\n", 
-                position, normalizedSearch[0], normalizedSearch[1]);
+  Serial.printf("[DICT-DBG] Starting at position %lu (prefix: %c%c)\n", position, normalizedSearch[0],
+                normalizedSearch[1]);
  bool found = false;
  uint32_t wordCount = 0;

@ -501,20 +499,19 @@ StarDict::LookupResult StarDict::lookup(const std::string& word) {
    }
    wordCount++;
    if (wordCount % 50000 == 0) {
-      Serial.printf("[DICT-DBG] Progress: %lu words scanned, pos=%lu, current='%s'\n",
-                    wordCount, position, currentWord.c_str());
+      Serial.printf("[DICT-DBG] Progress: %lu words scanned, pos=%lu, current='%s'\n", wordCount, position,
+                    currentWord.c_str());
    }

    // Use stardictStrcmp for case-insensitive matching
    const int cmp = stardictStrcmp(normalizedSearch, currentWord);

    if (cmp == 0) {
-      Serial.printf("[DICT-DBG] MATCH: '%s' == '%s' (offset=%lu, size=%lu)\n", 
-                    normalizedSearch.c_str(), currentWord.c_str(), dictOffset, dictSize);
+      Serial.printf("[DICT-DBG] MATCH: '%s' == '%s' (offset=%lu, size=%lu)\n", normalizedSearch.c_str(),
+                    currentWord.c_str(), dictOffset, dictSize);
      std::string definition;
-      const bool loaded = useUncompressed 
-          ? readDefinitionDirect(dictOffset, dictSize, definition)
-          : decompressDefinition(dictOffset, dictSize, definition);
+      const bool loaded = useUncompressed ? readDefinitionDirect(dictOffset, dictSize, definition)
+                                          : decompressDefinition(dictOffset, dictSize, definition);
      if (loaded) {
        Serial.printf("[DICT-DBG] Definition loaded, %u bytes\n", definition.length());
        if (!found) {
@ -537,8 +534,7 @@ StarDict::LookupResult StarDict::lookup(const std::string& word) {
    // may not land exactly at target position
  }

-  Serial.printf("[DICT-DBG] Search complete: %lu words scanned, found=%s\n",
-                wordCount, found ? "YES" : "NO");
+  Serial.printf("[DICT-DBG] Search complete: %lu words scanned, found=%s\n", wordCount, found ? "YES" : "NO");
  idxFile.close();

  // If not found in main index, try synonym file with prefix jump
@ -591,9 +587,8 @@ StarDict::LookupResult StarDict::lookup(const std::string& word) {
              uint32_t dictOffset, dictSize;
              if (readWordAtPosition(idxFile2, pos, mainWord, dictOffset, dictSize)) {
                std::string definition;
-                const bool loaded = useUncompressed 
-                    ? readDefinitionDirect(dictOffset, dictSize, definition)
-                    : decompressDefinition(dictOffset, dictSize, definition);
+                const bool loaded = useUncompressed ? readDefinitionDirect(dictOffset, dictSize, definition)
+                                                    : decompressDefinition(dictOffset, dictSize, definition);
                if (loaded) {
                  result.word = synWord;
                  result.definition = definition;
--- a/lib/hal/HalDisplay.cpp
+++ b/lib/hal/HalDisplay.cpp
@ -0,0 +1,53 @@
+#include <HalDisplay.h>
+#include <HalGPIO.h>
+
+#define SD_SPI_MISO 7
+
+HalDisplay::HalDisplay() : einkDisplay(EPD_SCLK, EPD_MOSI, EPD_CS, EPD_DC, EPD_RST, EPD_BUSY) {}
+
+HalDisplay::~HalDisplay() {}
+
+void HalDisplay::begin() { einkDisplay.begin(); }
+
+void HalDisplay::clearScreen(uint8_t color) const { einkDisplay.clearScreen(color); }
+
+void HalDisplay::drawImage(const uint8_t* imageData, uint16_t x, uint16_t y, uint16_t w, uint16_t h,
+                           bool fromProgmem) const {
+  einkDisplay.drawImage(imageData, x, y, w, h, fromProgmem);
+}
+
+EInkDisplay::RefreshMode convertRefreshMode(HalDisplay::RefreshMode mode) {
+  switch (mode) {
+    case HalDisplay::FULL_REFRESH:
+      return EInkDisplay::FULL_REFRESH;
+    case HalDisplay::HALF_REFRESH:
+      return EInkDisplay::HALF_REFRESH;
+    case HalDisplay::FAST_REFRESH:
+    default:
+      return EInkDisplay::FAST_REFRESH;
+  }
+}
+
+void HalDisplay::displayBuffer(HalDisplay::RefreshMode mode, bool turnOffScreen) {
+  einkDisplay.displayBuffer(convertRefreshMode(mode), turnOffScreen);
+}
+
+void HalDisplay::refreshDisplay(HalDisplay::RefreshMode mode, bool turnOffScreen) {
+  einkDisplay.refreshDisplay(convertRefreshMode(mode), turnOffScreen);
+}
+
+void HalDisplay::deepSleep() { einkDisplay.deepSleep(); }
+
+uint8_t* HalDisplay::getFrameBuffer() const { return einkDisplay.getFrameBuffer(); }
+
+void HalDisplay::copyGrayscaleBuffers(const uint8_t* lsbBuffer, const uint8_t* msbBuffer) {
+  einkDisplay.copyGrayscaleBuffers(lsbBuffer, msbBuffer);
+}
+
+void HalDisplay::copyGrayscaleLsbBuffers(const uint8_t* lsbBuffer) { einkDisplay.copyGrayscaleLsbBuffers(lsbBuffer); }
+
+void HalDisplay::copyGrayscaleMsbBuffers(const uint8_t* msbBuffer) { einkDisplay.copyGrayscaleMsbBuffers(msbBuffer); }
+
+void HalDisplay::cleanupGrayscaleBuffers(const uint8_t* bwBuffer) { einkDisplay.cleanupGrayscaleBuffers(bwBuffer); }
+
+void HalDisplay::displayGrayBuffer(bool turnOffScreen) { einkDisplay.displayGrayBuffer(turnOffScreen); }
--- a/lib/hal/HalDisplay.h
+++ b/lib/hal/HalDisplay.h
@ -0,0 +1,52 @@
+#pragma once
+#include <Arduino.h>
+#include <EInkDisplay.h>
+
+class HalDisplay {
+ public:
+  // Constructor with pin configuration
+  HalDisplay();
+
+  // Destructor
+  ~HalDisplay();
+
+  // Refresh modes
+  enum RefreshMode {
+    FULL_REFRESH,  // Full refresh with complete waveform
+    HALF_REFRESH,  // Half refresh (1720ms) - balanced quality and speed
+    FAST_REFRESH   // Fast refresh using custom LUT
+  };
+
+  // Initialize the display hardware and driver
+  void begin();
+
+  // Display dimensions
+  static constexpr uint16_t DISPLAY_WIDTH = EInkDisplay::DISPLAY_WIDTH;
+  static constexpr uint16_t DISPLAY_HEIGHT = EInkDisplay::DISPLAY_HEIGHT;
+  static constexpr uint16_t DISPLAY_WIDTH_BYTES = DISPLAY_WIDTH / 8;
+  static constexpr uint32_t BUFFER_SIZE = DISPLAY_WIDTH_BYTES * DISPLAY_HEIGHT;
+
+  // Frame buffer operations
+  void clearScreen(uint8_t color = 0xFF) const;
+  void drawImage(const uint8_t* imageData, uint16_t x, uint16_t y, uint16_t w, uint16_t h,
+                 bool fromProgmem = false) const;
+
+  void displayBuffer(RefreshMode mode = RefreshMode::FAST_REFRESH, bool turnOffScreen = false);
+  void refreshDisplay(RefreshMode mode = RefreshMode::FAST_REFRESH, bool turnOffScreen = false);
+
+  // Power management
+  void deepSleep();
+
+  // Access to frame buffer
+  uint8_t* getFrameBuffer() const;
+
+  void copyGrayscaleBuffers(const uint8_t* lsbBuffer, const uint8_t* msbBuffer);
+  void copyGrayscaleLsbBuffers(const uint8_t* lsbBuffer);
+  void copyGrayscaleMsbBuffers(const uint8_t* msbBuffer);
+  void cleanupGrayscaleBuffers(const uint8_t* bwBuffer);
+
+  void displayGrayBuffer(bool turnOffScreen = false);
+
+ private:
+  EInkDisplay einkDisplay;
+};
--- a/lib/hal/HalGPIO.cpp
+++ b/lib/hal/HalGPIO.cpp
@ -0,0 +1,55 @@
+#include <HalGPIO.h>
+#include <SPI.h>
+#include <esp_sleep.h>
+
+void HalGPIO::begin() {
+  inputMgr.begin();
+  SPI.begin(EPD_SCLK, SPI_MISO, EPD_MOSI, EPD_CS);
+  pinMode(BAT_GPIO0, INPUT);
+  pinMode(UART0_RXD, INPUT);
+}
+
+void HalGPIO::update() { inputMgr.update(); }
+
+bool HalGPIO::isPressed(uint8_t buttonIndex) const { return inputMgr.isPressed(buttonIndex); }
+
+bool HalGPIO::wasPressed(uint8_t buttonIndex) const { return inputMgr.wasPressed(buttonIndex); }
+
+bool HalGPIO::wasAnyPressed() const { return inputMgr.wasAnyPressed(); }
+
+bool HalGPIO::wasReleased(uint8_t buttonIndex) const { return inputMgr.wasReleased(buttonIndex); }
+
+bool HalGPIO::wasAnyReleased() const { return inputMgr.wasAnyReleased(); }
+
+unsigned long HalGPIO::getHeldTime() const { return inputMgr.getHeldTime(); }
+
+void HalGPIO::startDeepSleep() {
+  esp_deep_sleep_enable_gpio_wakeup(1ULL << InputManager::POWER_BUTTON_PIN, ESP_GPIO_WAKEUP_GPIO_LOW);
+  // Ensure that the power button has been released to avoid immediately turning back on if you're holding it
+  while (inputMgr.isPressed(BTN_POWER)) {
+    delay(50);
+    inputMgr.update();
+  }
+  // Enter Deep Sleep
+  esp_deep_sleep_start();
+}
+
+int HalGPIO::getBatteryPercentage() const {
+  static const BatteryMonitor battery = BatteryMonitor(BAT_GPIO0);
+  return battery.readPercentage();
+}
+
+bool HalGPIO::isUsbConnected() const {
+  // U0RXD/GPIO20 reads HIGH when USB is connected
+  return digitalRead(UART0_RXD) == HIGH;
+}
+
+bool HalGPIO::isWakeupByPowerButton() const {
+  const auto wakeupCause = esp_sleep_get_wakeup_cause();
+  const auto resetReason = esp_reset_reason();
+  if (isUsbConnected()) {
+    return wakeupCause == ESP_SLEEP_WAKEUP_GPIO;
+  } else {
+    return (wakeupCause == ESP_SLEEP_WAKEUP_UNDEFINED) && (resetReason == ESP_RST_POWERON);
+  }
+}
--- a/lib/hal/HalGPIO.h
+++ b/lib/hal/HalGPIO.h
@ -0,0 +1,61 @@
+#pragma once
+
+#include <Arduino.h>
+#include <BatteryMonitor.h>
+#include <InputManager.h>
+
+// Display SPI pins (custom pins for XteinkX4, not hardware SPI defaults)
+#define EPD_SCLK 8   // SPI Clock
+#define EPD_MOSI 10  // SPI MOSI (Master Out Slave In)
+#define EPD_CS 21    // Chip Select
+#define EPD_DC 4     // Data/Command
+#define EPD_RST 5    // Reset
+#define EPD_BUSY 6   // Busy
+
+#define SPI_MISO 7  // SPI MISO, shared between SD card and display (Master In Slave Out)
+
+#define BAT_GPIO0 0  // Battery voltage
+
+#define UART0_RXD 20  // Used for USB connection detection
+
+class HalGPIO {
+#if CROSSPOINT_EMULATED == 0
+  InputManager inputMgr;
+#endif
+
+ public:
+  HalGPIO() = default;
+
+  // Start button GPIO and setup SPI for screen and SD card
+  void begin();
+
+  // Button input methods
+  void update();
+  bool isPressed(uint8_t buttonIndex) const;
+  bool wasPressed(uint8_t buttonIndex) const;
+  bool wasAnyPressed() const;
+  bool wasReleased(uint8_t buttonIndex) const;
+  bool wasAnyReleased() const;
+  unsigned long getHeldTime() const;
+
+  // Setup wake up GPIO and enter deep sleep
+  void startDeepSleep();
+
+  // Get battery percentage (range 0-100)
+  int getBatteryPercentage() const;
+
+  // Check if USB is connected
+  bool isUsbConnected() const;
+
+  // Check if wakeup was caused by power button press
+  bool isWakeupByPowerButton() const;
+
+  // Button indices
+  static constexpr uint8_t BTN_BACK = 0;
+  static constexpr uint8_t BTN_CONFIRM = 1;
+  static constexpr uint8_t BTN_LEFT = 2;
+  static constexpr uint8_t BTN_RIGHT = 3;
+  static constexpr uint8_t BTN_UP = 4;
+  static constexpr uint8_t BTN_DOWN = 5;
+  static constexpr uint8_t BTN_POWER = 6;
+};
--- a/2
+++ b/2
@ -1 +1 @@
-Subproject commit dede09001c4c7bc96bd3616716cdf80913f57658
+Subproject commit be6ba1b62b1262929cded6ccdae774a098d33010
--- a/platformio.ini
+++ b/platformio.ini
@ -3,7 +3,7 @@ default_envs = default

 [crosspoint]
 # 0.15.0 CrossPoint base, ef-1.0.0 is the first release of the ef branch
-version = 0.15.ef-1.0.4
+version = 0.15.ef-1.0.5

 [base]
 platform = espressif32 @ 6.12.0
--- a/scripts/pre_flash.py
+++ b/scripts/pre_flash.py
@ -5,7 +5,11 @@ This allows the firmware to display "Flashing firmware..." on the e-ink display
 before the actual flash begins. The e-ink retains this message throughout the
 flash process since it doesn't require power to maintain the display.

-Protocol: Sends "FLASH:version\n" where version is read from platformio.ini
+Protocol (Plan A - Simple timing):
+1. Host opens serial port and sends "FLASH:version"
+2. Host keeps port open briefly for device to receive and process
+3. Device displays flash screen when it receives the command
+4. Host proceeds with flash
 """

 Import("env")
@ -15,7 +19,7 @@ from version_utils import get_version


 def before_upload(source, target, env):
-    """Send FLASH command with version to device before upload begins."""
+    """Send FLASH command to device before uploading firmware."""
    port = env.GetProjectOption("upload_port", None)

    if not port:
@ -29,19 +33,20 @@ def before_upload(source, target, env):
        ]
        port = ports[0] if ports else None

-    if port:
-        try:
-            version = get_version(env)
-            ser = serial.Serial(port, 115200, timeout=1)
-            ser.write(f"FLASH:{version}\n".encode())
-            ser.flush()
-            ser.close()
-            time.sleep(0.8)  # Wait for e-ink fast refresh (~500ms) plus margin
-            print(f"[pre_flash] Flash notification sent to {port} (version {version})")
-        except Exception as e:
-            print(f"[pre_flash] Notification skipped: {e}")
-    else:
+    if not port:
        print("[pre_flash] No serial port found, skipping notification")
+        return
+
+    try:
+        version = get_version(env)
+        ser = serial.Serial(port, 115200, timeout=1)
+        ser.write(f"FLASH:{version}\n".encode())
+        ser.flush()
+        time.sleep(4.0)  # Keep port open for device to receive and complete full refresh (~2-3s)
+        ser.close()
+        print(f"[pre_flash] Flash notification sent to {port} (version {version})")
+    except Exception as e:
+        print(f"[pre_flash] Notification skipped: {e}")


 env.AddPreAction("upload", before_upload)
--- a/src/BookManager.cpp
+++ b/src/BookManager.cpp
@ -303,6 +303,86 @@ bool BookManager::deleteBook(const std::string& bookPath, bool isArchived) {
  return true;
 }

+bool BookManager::clearBookCache(const std::string& bookPath, bool preserveProgress) {
+  Serial.printf("[%lu] [%s] Clearing cache for: %s (preserveProgress=%d)\n", millis(), LOG_TAG, bookPath.c_str(),
+                preserveProgress);
+
+  const std::string cacheDir = getCacheDir(bookPath);
+  if (cacheDir.empty()) {
+    Serial.printf("[%lu] [%s] No cache directory for unsupported format\n", millis(), LOG_TAG);
+    return true;  // Nothing to clear, not an error
+  }
+
+  if (!SdMan.exists(cacheDir.c_str())) {
+    Serial.printf("[%lu] [%s] Cache directory doesn't exist: %s\n", millis(), LOG_TAG, cacheDir.c_str());
+    return true;  // Nothing to clear, not an error
+  }
+
+  FsFile dir = SdMan.open(cacheDir.c_str());
+  if (!dir || !dir.isDirectory()) {
+    Serial.printf("[%lu] [%s] Failed to open cache directory\n", millis(), LOG_TAG);
+    if (dir) dir.close();
+    return false;
+  }
+
+  // Files to preserve (always keep bookmarks, optionally keep progress)
+  const auto shouldPreserve = [preserveProgress](const char* name) {
+    // Always preserve bookmarks
+    if (strcmp(name, "bookmarks.bin") == 0) return true;
+    // Optionally preserve progress
+    if (preserveProgress && strcmp(name, "progress.bin") == 0) return true;
+    return false;
+  };
+
+  int deletedCount = 0;
+  int failedCount = 0;
+  char name[128];
+
+  // First pass: delete files (not directories)
+  for (FsFile entry = dir.openNextFile(); entry; entry = dir.openNextFile()) {
+    entry.getName(name, sizeof(name));
+    const bool isDir = entry.isDirectory();
+    entry.close();
+
+    if (!isDir && !shouldPreserve(name)) {
+      std::string fullPath = cacheDir + "/" + name;
+      if (SdMan.remove(fullPath.c_str())) {
+        deletedCount++;
+      } else {
+        Serial.printf("[%lu] [%s] Failed to delete: %s\n", millis(), LOG_TAG, fullPath.c_str());
+        failedCount++;
+      }
+    }
+  }
+  dir.close();
+
+  // Second pass: delete subdirectories (like "sections/")
+  dir = SdMan.open(cacheDir.c_str());
+  if (dir && dir.isDirectory()) {
+    for (FsFile entry = dir.openNextFile(); entry; entry = dir.openNextFile()) {
+      entry.getName(name, sizeof(name));
+      const bool isDir = entry.isDirectory();
+      entry.close();
+
+      if (isDir) {
+        std::string fullPath = cacheDir + "/" + name;
+        if (SdMan.removeDir(fullPath.c_str())) {
+          deletedCount++;
+          Serial.printf("[%lu] [%s] Deleted subdirectory: %s\n", millis(), LOG_TAG, fullPath.c_str());
+        } else {
+          Serial.printf("[%lu] [%s] Failed to delete subdirectory: %s\n", millis(), LOG_TAG, fullPath.c_str());
+          failedCount++;
+        }
+      }
+    }
+    dir.close();
+  }
+
+  Serial.printf("[%lu] [%s] Cache cleared: %d items deleted, %d failed\n", millis(), LOG_TAG, deletedCount,
+                failedCount);
+  return failedCount == 0;
+}
+
 std::vector<std::string> BookManager::listArchivedBooks() {
  std::vector<std::string> archivedBooks;

--- a/src/BookManager.h
+++ b/src/BookManager.h
@ -57,6 +57,14 @@ class BookManager {
   */
  static std::string getCacheDir(const std::string& bookPath);

+  /**
+   * Clear cache for a single book, optionally preserving reading progress
+   * @param bookPath Full path to the book file
+   * @param preserveProgress If true, keeps progress.bin and bookmarks.bin
+   * @return true if successful (or if no cache exists)
+   */
+  static bool clearBookCache(const std::string& bookPath, bool preserveProgress);
+
 private:
  // Extract filename from a full path
  static std::string getFilename(const std::string& path);
--- a/src/CrossPointSettings.cpp
+++ b/src/CrossPointSettings.cpp
@ -23,7 +23,7 @@ void readAndValidate(FsFile& file, uint8_t& member, const uint8_t maxValue) {
 namespace {
 constexpr uint8_t SETTINGS_FILE_VERSION = 1;
 // Increment this when adding new persisted settings fields
-constexpr uint8_t SETTINGS_COUNT = 29;  // 28 + bezelCompensationEdge
+constexpr uint8_t SETTINGS_COUNT = 30;  // 29 + fadingFix
 constexpr char SETTINGS_FILE[] = "/.crosspoint/settings.bin";
 }  // namespace

@ -72,6 +72,8 @@ bool CrossPointSettings::saveToFile() const {
  serialization::writePod(outputFile, bezelCompensation);
  // Which physical edge needs bezel compensation
  serialization::writePod(outputFile, bezelCompensationEdge);
+  // Sunlight fading fix
+  serialization::writePod(outputFile, fadingFix);
  // New fields added at end for backward compatibility
  outputFile.close();

@ -182,6 +184,9 @@ bool CrossPointSettings::loadFromFile() {
    // Which physical edge needs bezel compensation
    readAndValidate(inputFile, bezelCompensationEdge, BEZEL_EDGE_COUNT);
    if (++settingsRead >= fileSettingsCount) break;
+    // Sunlight fading fix
+    serialization::readPod(inputFile, fadingFix);
+    if (++settingsRead >= fileSettingsCount) break;
    // New fields added at end for backward compatibility
  } while (false);

--- a/src/CrossPointSettings.h
+++ b/src/CrossPointSettings.h
@ -144,6 +144,8 @@ class CrossPointSettings {
  uint8_t hideBatteryPercentage = HIDE_NEVER;
  // Long-press chapter skip on side buttons
  uint8_t longPressChapterSkip = 1;
+  // Sunlight fading compensation (0 = off, 1 = on)
+  uint8_t fadingFix = 0;
  // System-wide display contrast (0 = normal, 1 = high)
  uint8_t displayContrast = 0;
  // Bezel compensation - extra margin for physical screen edge defects (0-10px)
--- a/src/MappedInputManager.cpp
+++ b/src/MappedInputManager.cpp
@ -2,103 +2,77 @@

 #include "CrossPointSettings.h"

-decltype(InputManager::BTN_BACK) MappedInputManager::mapButton(const Button button) const {
+namespace {
+using ButtonIndex = uint8_t;
+
+struct FrontLayoutMap {
+  ButtonIndex back;
+  ButtonIndex confirm;
+  ButtonIndex left;
+  ButtonIndex right;
+};
+
+struct SideLayoutMap {
+  ButtonIndex pageBack;
+  ButtonIndex pageForward;
+};
+
+// Order matches CrossPointSettings::FRONT_BUTTON_LAYOUT.
+constexpr FrontLayoutMap kFrontLayouts[] = {
+    {HalGPIO::BTN_BACK, HalGPIO::BTN_CONFIRM, HalGPIO::BTN_LEFT, HalGPIO::BTN_RIGHT},
+    {HalGPIO::BTN_LEFT, HalGPIO::BTN_RIGHT, HalGPIO::BTN_BACK, HalGPIO::BTN_CONFIRM},
+    {HalGPIO::BTN_CONFIRM, HalGPIO::BTN_LEFT, HalGPIO::BTN_BACK, HalGPIO::BTN_RIGHT},
+    {HalGPIO::BTN_BACK, HalGPIO::BTN_CONFIRM, HalGPIO::BTN_RIGHT, HalGPIO::BTN_LEFT},
+};
+
+// Order matches CrossPointSettings::SIDE_BUTTON_LAYOUT.
+constexpr SideLayoutMap kSideLayouts[] = {
+    {HalGPIO::BTN_UP, HalGPIO::BTN_DOWN},
+    {HalGPIO::BTN_DOWN, HalGPIO::BTN_UP},
+};
+}  // namespace
+
+bool MappedInputManager::mapButton(const Button button, bool (HalGPIO::*fn)(uint8_t) const) const {
  const auto frontLayout = static_cast<CrossPointSettings::FRONT_BUTTON_LAYOUT>(SETTINGS.frontButtonLayout);
  const auto sideLayout = static_cast<CrossPointSettings::SIDE_BUTTON_LAYOUT>(SETTINGS.sideButtonLayout);
+  const auto& front = kFrontLayouts[frontLayout];
+  const auto& side = kSideLayouts[sideLayout];

  switch (button) {
    case Button::Back:
-      switch (frontLayout) {
-        case CrossPointSettings::LEFT_RIGHT_BACK_CONFIRM:
-          return InputManager::BTN_LEFT;
-        case CrossPointSettings::LEFT_BACK_CONFIRM_RIGHT:
-          return InputManager::BTN_CONFIRM;
-        case CrossPointSettings::BACK_CONFIRM_LEFT_RIGHT:
-          /* fall through */
-        case CrossPointSettings::BACK_CONFIRM_RIGHT_LEFT:
-          /* fall through */
-        default:
-          return InputManager::BTN_BACK;
-      }
+      return (gpio.*fn)(front.back);
    case Button::Confirm:
-      switch (frontLayout) {
-        case CrossPointSettings::LEFT_RIGHT_BACK_CONFIRM:
-          return InputManager::BTN_RIGHT;
-        case CrossPointSettings::LEFT_BACK_CONFIRM_RIGHT:
-          return InputManager::BTN_LEFT;
-        case CrossPointSettings::BACK_CONFIRM_LEFT_RIGHT:
-          /* fall through */
-        case CrossPointSettings::BACK_CONFIRM_RIGHT_LEFT:
-          /* fall through */
-        default:
-          return InputManager::BTN_CONFIRM;
-      }
+      return (gpio.*fn)(front.confirm);
    case Button::Left:
-      switch (frontLayout) {
-        case CrossPointSettings::LEFT_RIGHT_BACK_CONFIRM:
-          /* fall through */
-        case CrossPointSettings::LEFT_BACK_CONFIRM_RIGHT:
-          return InputManager::BTN_BACK;
-        case CrossPointSettings::BACK_CONFIRM_RIGHT_LEFT:
-          return InputManager::BTN_RIGHT;
-        case CrossPointSettings::BACK_CONFIRM_LEFT_RIGHT:
-          /* fall through */
-        default:
-          return InputManager::BTN_LEFT;
-      }
+      return (gpio.*fn)(front.left);
    case Button::Right:
-      switch (frontLayout) {
-        case CrossPointSettings::LEFT_RIGHT_BACK_CONFIRM:
-          return InputManager::BTN_CONFIRM;
-        case CrossPointSettings::BACK_CONFIRM_RIGHT_LEFT:
-          return InputManager::BTN_LEFT;
-        case CrossPointSettings::BACK_CONFIRM_LEFT_RIGHT:
-          /* fall through */
-        case CrossPointSettings::LEFT_BACK_CONFIRM_RIGHT:
-          /* fall through */
-        default:
-          return InputManager::BTN_RIGHT;
-      }
+      return (gpio.*fn)(front.right);
    case Button::Up:
-      return InputManager::BTN_UP;
+      return (gpio.*fn)(HalGPIO::BTN_UP);
    case Button::Down:
-      return InputManager::BTN_DOWN;
+      return (gpio.*fn)(HalGPIO::BTN_DOWN);
    case Button::Power:
-      return InputManager::BTN_POWER;
+      return (gpio.*fn)(HalGPIO::BTN_POWER);
    case Button::PageBack:
-      switch (sideLayout) {
-        case CrossPointSettings::NEXT_PREV:
-          return InputManager::BTN_DOWN;
-        case CrossPointSettings::PREV_NEXT:
-          /* fall through */
-        default:
-          return InputManager::BTN_UP;
-      }
+      return (gpio.*fn)(side.pageBack);
    case Button::PageForward:
-      switch (sideLayout) {
-        case CrossPointSettings::NEXT_PREV:
-          return InputManager::BTN_UP;
-        case CrossPointSettings::PREV_NEXT:
-          /* fall through */
-        default:
-          return InputManager::BTN_DOWN;
-      }
+      return (gpio.*fn)(side.pageForward);
  }

-  return InputManager::BTN_BACK;
+  return false;
 }

-bool MappedInputManager::wasPressed(const Button button) const { return inputManager.wasPressed(mapButton(button)); }
+bool MappedInputManager::wasPressed(const Button button) const { return mapButton(button, &HalGPIO::wasPressed); }

-bool MappedInputManager::wasReleased(const Button button) const { return inputManager.wasReleased(mapButton(button)); }
+bool MappedInputManager::wasReleased(const Button button) const { return mapButton(button, &HalGPIO::wasReleased); }

-bool MappedInputManager::isPressed(const Button button) const { return inputManager.isPressed(mapButton(button)); }
+bool MappedInputManager::isPressed(const Button button) const { return mapButton(button, &HalGPIO::isPressed); }

-bool MappedInputManager::wasAnyPressed() const { return inputManager.wasAnyPressed(); }
+bool MappedInputManager::wasAnyPressed() const { return gpio.wasAnyPressed(); }

-bool MappedInputManager::wasAnyReleased() const { return inputManager.wasAnyReleased(); }
+bool MappedInputManager::wasAnyReleased() const { return gpio.wasAnyReleased(); }

-unsigned long MappedInputManager::getHeldTime() const { return inputManager.getHeldTime(); }
+unsigned long MappedInputManager::getHeldTime() const { return gpio.getHeldTime(); }

 MappedInputManager::Labels MappedInputManager::mapLabels(const char* back, const char* confirm, const char* previous,
                                                         const char* next) const {
--- a/src/MappedInputManager.h
+++ b/src/MappedInputManager.h
@ -1,6 +1,6 @@
 #pragma once

-#include <InputManager.h>
+#include <HalGPIO.h>

 class MappedInputManager {
 public:
@ -13,7 +13,7 @@ class MappedInputManager {
    const char* btn4;
  };

-  explicit MappedInputManager(InputManager& inputManager) : inputManager(inputManager) {}
+  explicit MappedInputManager(HalGPIO& gpio) : gpio(gpio) {}

  bool wasPressed(Button button) const;
  bool wasReleased(Button button) const;
@ -24,6 +24,7 @@ class MappedInputManager {
  Labels mapLabels(const char* back, const char* confirm, const char* previous, const char* next) const;

 private:
-  InputManager& inputManager;
-  decltype(InputManager::BTN_BACK) mapButton(Button button) const;
+  HalGPIO& gpio;
+
+  bool mapButton(Button button, bool (HalGPIO::*fn)(uint8_t) const) const;
 };
--- a/src/activities/boot_sleep/SleepActivity.cpp
+++ b/src/activities/boot_sleep/SleepActivity.cpp
@ -154,7 +154,7 @@ void SleepActivity::renderDefaultSleepScreen() const {
    renderer.invertScreen();
  }

-  renderer.displayBuffer(EInkDisplay::HALF_REFRESH);
+  renderer.displayBuffer(HalDisplay::HALF_REFRESH);
 }

 void SleepActivity::renderBitmapSleepScreen(const Bitmap& bitmap, const std::string& bmpPath) const {
@ -269,7 +269,7 @@ void SleepActivity::renderBitmapSleepScreen(const Bitmap& bitmap, const std::str
    renderer.invertScreen();
  }

-  renderer.displayBuffer(EInkDisplay::HALF_REFRESH);
+  renderer.displayBuffer(HalDisplay::HALF_REFRESH);

  if (hasGreyscale) {
    // Grayscale LSB pass
@ -400,7 +400,7 @@ void SleepActivity::renderCoverSleepScreen() const {

 void SleepActivity::renderBlankSleepScreen() const {
  renderer.clearScreen();
-  renderer.displayBuffer(EInkDisplay::HALF_REFRESH);
+  renderer.displayBuffer(HalDisplay::HALF_REFRESH);
 }

 std::string SleepActivity::getEdgeCachePath(const std::string& bmpPath) {
--- a/src/activities/dictionary/DictionaryResultActivity.cpp
+++ b/src/activities/dictionary/DictionaryResultActivity.cpp
@ -98,7 +98,7 @@ void DictionaryResultActivity::loop() {
        // At end of cached pages but more content available - parse next chunk
        Serial.printf("[DICT-DBG] Parsing next chunk on navigation (page %d)\n", currentPage);
        parseNextChunk();
-        
+
        // After parsing (and possible page trimming), check if we can advance
        // Note: Don't compare page counts - trimming may keep size the same while adding new content
        if (currentPage < static_cast<int>(pages.size()) - 1) {
@ -143,9 +143,9 @@ void DictionaryResultActivity::paginateDefinition() {
  // With HTML overhead, multiply by ~2, plus buffer for finding break points
  constexpr size_t CHUNK_SIZE_BASE = 1500;  // Base chunk size
  const size_t chunkSize = std::max(CHUNK_SIZE_BASE, static_cast<size_t>(linesPerPage * 120));
-  
-  Serial.printf("[DICT-DBG] Chunked parsing: defLen=%u, chunkSize=%u, linesPerPage=%d\n",
-                rawDefinition.length(), chunkSize, linesPerPage);
+
+  Serial.printf("[DICT-DBG] Chunked parsing: defLen=%u, chunkSize=%u, linesPerPage=%d\n", rawDefinition.length(),
+                chunkSize, linesPerPage);

  // Determine how much to parse for first page
  size_t parseEnd;
@ -158,20 +158,18 @@ void DictionaryResultActivity::paginateDefinition() {
    parseEnd = findHtmlBreakPoint(rawDefinition, chunkSize / 2, chunkSize);
    hasMoreContent = (parseEnd < rawDefinition.length());
  }
-  
+
  // Extract the chunk to parse
  std::string chunk = rawDefinition.substr(0, parseEnd);
  parsePosition = parseEnd;
-  
-  Serial.printf("[DICT-DBG] Parsing first chunk: 0-%u of %u, hasMore=%d\n",
-                parseEnd, rawDefinition.length(), hasMoreContent);
+
+  Serial.printf("[DICT-DBG] Parsing first chunk: 0-%u of %u, hasMore=%d\n", parseEnd, rawDefinition.length(),
+                hasMoreContent);

  // Parse this chunk into TextBlocks
  std::vector<std::shared_ptr<TextBlock>> allBlocks;
  DictHtmlParser::parse(chunk, UI_10_FONT_ID, renderer, textWidth,
-                        [&allBlocks](std::shared_ptr<TextBlock> block) { 
-                          allBlocks.push_back(block); 
-                        });
+                        [&allBlocks](std::shared_ptr<TextBlock> block) { allBlocks.push_back(block); });
  Serial.printf("[DICT-DBG] First chunk parsed, %u TextBlocks\n", allBlocks.size());

  if (allBlocks.empty()) {
@ -209,27 +207,27 @@ void DictionaryResultActivity::paginateDefinition() {
  if (!currentPageBlocks.empty()) {
    pages.push_back(currentPageBlocks);
  }
-  
+
  Serial.printf("[DICT-DBG] Initial pagination: %u pages\n", pages.size());
 }

 size_t DictionaryResultActivity::findHtmlBreakPoint(const std::string& html, size_t searchStart, size_t maxPos) {
  // Search backwards from maxPos for good HTML break points
  // Priority: </li>, </p>, </ol>, </ul>, </div> then any '>' then whitespace
-  
+
  if (maxPos >= html.length()) {
    return html.length();
  }
-  
+
  // Clamp searchStart to not exceed maxPos
  if (searchStart > maxPos) {
    searchStart = maxPos;
  }
-  
+
  // Search for closing block tags (best break points)
  const char* closingTags[] = {"</li>", "</p>", "</ol>", "</ul>", "</div>", "</dd>", "</dt>"};
  size_t bestBreak = std::string::npos;
-  
+
  for (const char* tag : closingTags) {
    size_t pos = html.rfind(tag, maxPos);
    if (pos != std::string::npos && pos >= searchStart) {
@ -240,17 +238,17 @@ size_t DictionaryResultActivity::findHtmlBreakPoint(const std::string& html, siz
      }
    }
  }
-  
+
  if (bestBreak != std::string::npos) {
    return bestBreak;
  }
-  
+
  // Fallback: search for any '>' (end of tag)
  size_t tagEnd = html.rfind('>', maxPos);
  if (tagEnd != std::string::npos && tagEnd >= searchStart) {
    return tagEnd + 1;
  }
-  
+
  // Last resort: search for whitespace
  for (size_t i = maxPos; i >= searchStart && i != std::string::npos; i--) {
    if (std::isspace(static_cast<unsigned char>(html[i]))) {
@ -258,7 +256,7 @@ size_t DictionaryResultActivity::findHtmlBreakPoint(const std::string& html, siz
    }
    if (i == 0) break;
  }
-  
+
  // No good break point found - use maxPos
  return maxPos;
 }
@ -269,8 +267,7 @@ void DictionaryResultActivity::parseNextChunk() {
    return;
  }

-  Serial.printf("[DICT-DBG] parseNextChunk starting at position %u of %u\n",
-                parsePosition, rawDefinition.length());
+  Serial.printf("[DICT-DBG] parseNextChunk starting at position %u of %u\n", parsePosition, rawDefinition.length());

  // Get margins with button hint space for all orientations
  int marginTop, marginRight, marginBottom, marginLeft;
@ -295,7 +292,7 @@ void DictionaryResultActivity::parseNextChunk() {
  // Determine parse range for this chunk
  size_t parseStart = parsePosition;
  size_t parseEnd;
-  
+
  if (parsePosition + chunkSize >= rawDefinition.length()) {
    // This will be the last chunk
    parseEnd = rawDefinition.length();
@ -315,9 +312,7 @@ void DictionaryResultActivity::parseNextChunk() {
  // Parse this chunk into TextBlocks
  std::vector<std::shared_ptr<TextBlock>> allBlocks;
  DictHtmlParser::parse(chunk, UI_10_FONT_ID, renderer, textWidth,
-                        [&allBlocks](std::shared_ptr<TextBlock> block) { 
-                          allBlocks.push_back(block); 
-                        });
+                        [&allBlocks](std::shared_ptr<TextBlock> block) { allBlocks.push_back(block); });

  Serial.printf("[DICT-DBG] Chunk parsed, %u TextBlocks\n", allBlocks.size());

@ -359,39 +354,38 @@ void DictionaryResultActivity::parseNextChunk() {
    Serial.printf("[DICT-DBG] Trimmed old page, firstPageNumber now %d\n", firstPageNumber);
  }

-  Serial.printf("[DICT-DBG] After chunk: %u cached pages (pages %d-%d)\n", 
-                pages.size(), firstPageNumber, firstPageNumber + static_cast<int>(pages.size()) - 1);
+  Serial.printf("[DICT-DBG] After chunk: %u cached pages (pages %d-%d)\n", pages.size(), firstPageNumber,
+                firstPageNumber + static_cast<int>(pages.size()) - 1);
 }

 void DictionaryResultActivity::reparseToPage(int targetPageNumber) {
  // Re-parse from the beginning to reach an earlier page that was trimmed
  // This allows backward navigation through the entire definition
-  
+
  Serial.printf("[DICT-DBG] reparseToPage: target=%d, clearing and re-parsing\n", targetPageNumber);
-  
+
  // Clear current state and start fresh
  pages.clear();
  parsePosition = 0;
  firstPageNumber = 1;
  hasMoreContent = !rawDefinition.empty();
-  
+
  // Parse chunks until we have the target page
  while (hasMoreContent && firstPageNumber + static_cast<int>(pages.size()) - 1 < targetPageNumber) {
    parseNextChunk();
  }
-  
+
  // Now position currentPage to show the target page
-  if (targetPageNumber >= firstPageNumber && 
-      targetPageNumber < firstPageNumber + static_cast<int>(pages.size())) {
+  if (targetPageNumber >= firstPageNumber && targetPageNumber < firstPageNumber + static_cast<int>(pages.size())) {
    currentPage = targetPageNumber - firstPageNumber;
  } else {
    // Target page doesn't exist (definition is shorter than expected)
    currentPage = static_cast<int>(pages.size()) - 1;
    if (currentPage < 0) currentPage = 0;
  }
-  
-  Serial.printf("[DICT-DBG] reparseToPage done: currentPage=%d, firstPageNumber=%d, pages=%u\n",
-                currentPage, firstPageNumber, pages.size());
+
+  Serial.printf("[DICT-DBG] reparseToPage done: currentPage=%d, firstPageNumber=%d, pages=%u\n", currentPage,
+                firstPageNumber, pages.size());
 }

 void DictionaryResultActivity::displayTaskLoop() {
@ -425,8 +419,8 @@ void DictionaryResultActivity::render() const {
    renderer.drawCenteredText(UI_10_FONT_ID, centerY, "Word not found");
  } else if (!pages.empty()) {
    // Draw definition text using TextBlocks with rich formatting
-    constexpr int headerHeight = 55;   // Space for "Dictionary" + lookup word
-    constexpr int footerHeight = 20;   // Space for page indicator
+    constexpr int headerHeight = 55;  // Space for "Dictionary" + lookup word
+    constexpr int footerHeight = 20;  // Space for page indicator
    const int textStartY = marginTop + headerHeight;
    const int textMargin = marginLeft + 10;
    const int lineHeight = renderer.getLineHeight(UI_10_FONT_ID);
--- a/src/activities/dictionary/DictionaryResultActivity.h
+++ b/src/activities/dictionary/DictionaryResultActivity.h
@ -29,8 +29,8 @@ class DictionaryResultActivity final : public Activity {
  // We limit cached pages to prevent memory exhaustion on long definitions
  static constexpr int MAX_CACHED_PAGES = 4;
  std::vector<std::vector<std::shared_ptr<TextBlock>>> pages;
-  int currentPage = 0;       // Index into pages vector
-  int firstPageNumber = 1;   // The page number of pages[0] (1-based for display)
+  int currentPage = 0;      // Index into pages vector
+  int firstPageNumber = 1;  // The page number of pages[0] (1-based for display)
  bool notFound = false;

  // Chunked parsing state - parse definition on-demand as user navigates
--- a/src/activities/dictionary/EpubWordSelectionActivity.cpp
+++ b/src/activities/dictionary/EpubWordSelectionActivity.cpp
@ -1,7 +1,7 @@
 #include "EpubWordSelectionActivity.h"

-#include <EInkDisplay.h>
 #include <GfxRenderer.h>
+#include <HalDisplay.h>

 #include <algorithm>
 #include <cctype>
@ -263,5 +263,5 @@ void EpubWordSelectionActivity::render() const {
  const char* sideBottomHint = (currentLineIndex < lastLine) ? "DOWN" : "";
  renderer.drawSideButtonHints(SMALL_FONT_ID, sideTopHint, sideBottomHint, false);  // No border

-  renderer.displayBuffer(EInkDisplay::FAST_REFRESH);
+  renderer.displayBuffer(HalDisplay::FAST_REFRESH);
 }
--- a/src/activities/home/MyLibraryActivity.cpp
+++ b/src/activities/home/MyLibraryActivity.cpp
@ -503,22 +503,29 @@ void MyLibraryActivity::executeAction() {
  } else if (selectedAction == ActionType::RemoveFromRecents) {
    // Just remove from recents list, don't touch the file
    success = RECENT_BOOKS.removeBook(actionTargetPath);
+  } else if (selectedAction == ActionType::ClearCache) {
+    // Clear cache for this book, optionally preserving progress
+    success = BookManager::clearBookCache(actionTargetPath, clearCachePreserveProgress);
+    // Also clear thumbnail existence cache since thumbnails may have been deleted
+    clearThumbExistsCache();
  }
  // Note: ClearAllRecents is handled directly in loop() via ClearAllRecentsConfirming state

  if (success) {
    // Reload data
    loadRecentBooks();
-    if (selectedAction != ActionType::RemoveFromRecents) {
-      loadFiles();  // Only reload files for Archive/Delete
+    if (selectedAction != ActionType::RemoveFromRecents && selectedAction != ActionType::ClearCache) {
+      loadFiles();  // Only reload files for Archive/Delete (not needed for cache clear)
    }

-    // Adjust selector if needed
-    const int itemCount = getCurrentItemCount();
-    if (selectorIndex >= itemCount && itemCount > 0) {
-      selectorIndex = itemCount - 1;
-    } else if (itemCount == 0) {
-      selectorIndex = 0;
+    // Adjust selector if needed (not needed for ClearCache since item count doesn't change)
+    if (selectedAction != ActionType::ClearCache) {
+      const int itemCount = getCurrentItemCount();
+      if (selectorIndex >= itemCount && itemCount > 0) {
+        selectorIndex = itemCount - 1;
+      } else if (itemCount == 0) {
+        selectorIndex = 0;
+      }
    }
  }

@ -577,8 +584,8 @@ void MyLibraryActivity::executeListAction() {
 void MyLibraryActivity::loop() {
  // Handle action menu state
  if (uiState == UIState::ActionMenu) {
-    // Menu has 4 options in Recent tab, 2 options in Files tab
-    const int maxMenuSelection = (currentTab == Tab::Recent) ? 3 : 1;
+    // Menu has 5 options in Recent tab, 3 options in Files tab
+    const int maxMenuSelection = (currentTab == Tab::Recent) ? 4 : 2;

    if (mappedInput.wasReleased(MappedInputManager::Button::Back)) {
      uiState = UIState::Normal;
@ -608,7 +615,7 @@ void MyLibraryActivity::loop() {

      // Map menu selection to action type
      if (currentTab == Tab::Recent) {
-        // Recent tab: Archive(0), Delete(1), Remove from Recents(2), Clear All Recents(3)
+        // Recent tab: Archive(0), Delete(1), Clear Cache(2), Remove from Recents(3), Clear All Recents(4)
        switch (menuSelection) {
          case 0:
            selectedAction = ActionType::Archive;
@ -617,20 +624,37 @@ void MyLibraryActivity::loop() {
            selectedAction = ActionType::Delete;
            break;
          case 2:
-            selectedAction = ActionType::RemoveFromRecents;
+            selectedAction = ActionType::ClearCache;
            break;
          case 3:
+            selectedAction = ActionType::RemoveFromRecents;
+            break;
+          case 4:
            selectedAction = ActionType::ClearAllRecents;
            break;
        }
      } else {
-        // Files tab: Archive(0), Delete(1)
-        selectedAction = (menuSelection == 0) ? ActionType::Archive : ActionType::Delete;
+        // Files tab: Archive(0), Delete(1), Clear Cache(2)
+        switch (menuSelection) {
+          case 0:
+            selectedAction = ActionType::Archive;
+            break;
+          case 1:
+            selectedAction = ActionType::Delete;
+            break;
+          case 2:
+            selectedAction = ActionType::ClearCache;
+            break;
+        }
      }

      // Clear All Recents needs its own confirmation dialog
      if (selectedAction == ActionType::ClearAllRecents) {
        uiState = UIState::ClearAllRecentsConfirming;
+      } else if (selectedAction == ActionType::ClearCache) {
+        // Clear Cache shows options dialog first
+        clearCachePreserveProgress = true;  // Default to preserving progress
+        uiState = UIState::ClearCacheOptionsConfirming;
      } else {
        uiState = UIState::Confirming;
      }
@ -735,6 +759,30 @@ void MyLibraryActivity::loop() {
    return;
  }

+  // Handle clear cache options confirmation state
+  if (uiState == UIState::ClearCacheOptionsConfirming) {
+    if (mappedInput.wasReleased(MappedInputManager::Button::Back)) {
+      uiState = UIState::ActionMenu;
+      updateRequired = true;
+      return;
+    }
+
+    // Up/Down toggle between Yes/No for preserve progress
+    if (mappedInput.wasReleased(MappedInputManager::Button::Up) ||
+        mappedInput.wasReleased(MappedInputManager::Button::Down)) {
+      clearCachePreserveProgress = !clearCachePreserveProgress;
+      updateRequired = true;
+      return;
+    }
+
+    if (mappedInput.wasReleased(MappedInputManager::Button::Confirm)) {
+      executeAction();
+      return;
+    }
+
+    return;
+  }
+
  // Normal state handling
  const int itemCount = getCurrentItemCount();
  const int pageItems = getPageItems();
@ -1303,6 +1351,12 @@ void MyLibraryActivity::render() const {
    return;
  }

+  if (uiState == UIState::ClearCacheOptionsConfirming) {
+    renderClearCacheOptionsConfirmation();
+    renderer.displayBuffer();
+    return;
+  }
+
  // Calculate bezel-adjusted margins
  const int bezelTop = renderer.getBezelOffsetTop();
  const int bezelBottom = renderer.getBezelOffsetBottom();
@ -1661,40 +1715,46 @@ void MyLibraryActivity::renderActionMenu() const {
      renderer.truncatedText(UI_10_FONT_ID, actionTargetName.c_str(), pageWidth - 40 - bezelLeft - bezelRight);
  renderer.drawCenteredText(UI_10_FONT_ID, filenameY, truncatedName.c_str());

-  // Menu options - 4 for Recent tab, 2 for Files tab
+  // Menu options - 5 for Recent tab, 3 for Files tab
  const bool isRecentTab = (currentTab == Tab::Recent);
-  const int menuItemCount = isRecentTab ? 4 : 2;
+  const int menuItemCount = isRecentTab ? 5 : 3;
  constexpr int menuLineHeight = 35;
  constexpr int menuItemWidth = 160;
  const int menuX = (pageWidth - menuItemWidth) / 2;
  const int menuStartY = pageHeight / 2 - (menuItemCount * menuLineHeight) / 2;

-  // Archive option
+  // Archive option (index 0)
  if (menuSelection == 0) {
    renderer.fillRect(menuX - 10, menuStartY - 5, menuItemWidth + 20, menuLineHeight);
  }
  renderer.drawCenteredText(UI_10_FONT_ID, menuStartY, "Archive", menuSelection != 0);

-  // Delete option
+  // Delete option (index 1)
  if (menuSelection == 1) {
    renderer.fillRect(menuX - 10, menuStartY + menuLineHeight - 5, menuItemWidth + 20, menuLineHeight);
  }
  renderer.drawCenteredText(UI_10_FONT_ID, menuStartY + menuLineHeight, "Delete", menuSelection != 1);

+  // Clear Cache option (index 2) - available in both tabs
+  if (menuSelection == 2) {
+    renderer.fillRect(menuX - 10, menuStartY + menuLineHeight * 2 - 5, menuItemWidth + 20, menuLineHeight);
+  }
+  renderer.drawCenteredText(UI_10_FONT_ID, menuStartY + menuLineHeight * 2, "Clear Cache", menuSelection != 2);
+
  // Recent tab only: Remove from Recents and Clear All Recents
  if (isRecentTab) {
-    // Remove from Recents option
-    if (menuSelection == 2) {
-      renderer.fillRect(menuX - 10, menuStartY + menuLineHeight * 2 - 5, menuItemWidth + 20, menuLineHeight);
-    }
-    renderer.drawCenteredText(UI_10_FONT_ID, menuStartY + menuLineHeight * 2, "Remove from Recents",
-                              menuSelection != 2);
-
-    // Clear All Recents option
+    // Remove from Recents option (index 3)
    if (menuSelection == 3) {
      renderer.fillRect(menuX - 10, menuStartY + menuLineHeight * 3 - 5, menuItemWidth + 20, menuLineHeight);
    }
-    renderer.drawCenteredText(UI_10_FONT_ID, menuStartY + menuLineHeight * 3, "Clear All Recents", menuSelection != 3);
+    renderer.drawCenteredText(UI_10_FONT_ID, menuStartY + menuLineHeight * 3, "Remove from Recents",
+                              menuSelection != 3);
+
+    // Clear All Recents option (index 4)
+    if (menuSelection == 4) {
+      renderer.fillRect(menuX - 10, menuStartY + menuLineHeight * 4 - 5, menuItemWidth + 20, menuLineHeight);
+    }
+    renderer.drawCenteredText(UI_10_FONT_ID, menuStartY + menuLineHeight * 4, "Clear All Recents", menuSelection != 4);
  }

  // Draw side button hints (up/down navigation)
@ -1828,6 +1888,54 @@ void MyLibraryActivity::renderClearAllRecentsConfirmation() const {
  renderer.drawButtonHints(UI_10_FONT_ID, labels.btn1, labels.btn2, labels.btn3, labels.btn4);
 }

+void MyLibraryActivity::renderClearCacheOptionsConfirmation() const {
+  const auto pageWidth = renderer.getScreenWidth();
+  const auto pageHeight = renderer.getScreenHeight();
+
+  // Bezel compensation
+  const int bezelTop = renderer.getBezelOffsetTop();
+
+  // Title
+  renderer.drawCenteredText(UI_12_FONT_ID, 20 + bezelTop, "Clear Book Cache", true, EpdFontFamily::BOLD);
+
+  // Show filename
+  const int filenameY = 60 + bezelTop;
+  const int bezelLeft = renderer.getBezelOffsetLeft();
+  const int bezelRight = renderer.getBezelOffsetRight();
+  auto truncatedName =
+      renderer.truncatedText(UI_10_FONT_ID, actionTargetName.c_str(), pageWidth - 40 - bezelLeft - bezelRight);
+  renderer.drawCenteredText(UI_10_FONT_ID, filenameY, truncatedName.c_str());
+
+  // Question text
+  const int questionY = pageHeight / 2 - 50;
+  renderer.drawCenteredText(UI_10_FONT_ID, questionY, "Preserve reading progress?");
+
+  // Yes/No options
+  constexpr int optionLineHeight = 35;
+  constexpr int optionWidth = 100;
+  const int optionX = (pageWidth - optionWidth) / 2;
+  const int optionStartY = questionY + 40;
+
+  // Yes option
+  if (clearCachePreserveProgress) {
+    renderer.fillRect(optionX - 10, optionStartY - 5, optionWidth + 20, optionLineHeight);
+  }
+  renderer.drawCenteredText(UI_10_FONT_ID, optionStartY, "Yes", !clearCachePreserveProgress);
+
+  // No option
+  if (!clearCachePreserveProgress) {
+    renderer.fillRect(optionX - 10, optionStartY + optionLineHeight - 5, optionWidth + 20, optionLineHeight);
+  }
+  renderer.drawCenteredText(UI_10_FONT_ID, optionStartY + optionLineHeight, "No", clearCachePreserveProgress);
+
+  // Draw side button hints (up/down navigation)
+  renderer.drawSideButtonHints(UI_10_FONT_ID, ">", "<");
+
+  // Draw bottom button hints
+  const auto labels = mappedInput.mapLabels("« Cancel", "Clear", "", "");
+  renderer.drawButtonHints(UI_10_FONT_ID, labels.btn1, labels.btn2, labels.btn3, labels.btn4);
+}
+
 void MyLibraryActivity::renderBookmarksTab() const {
  const auto pageWidth = renderer.getScreenWidth();
  const int pageItems = getPageItems();
--- a/src/activities/home/MyLibraryActivity.h
+++ b/src/activities/home/MyLibraryActivity.h
@ -44,9 +44,10 @@ class MyLibraryActivity final : public Activity {
    Confirming,
    ListActionMenu,
    ListConfirmingDelete,
-    ClearAllRecentsConfirming
+    ClearAllRecentsConfirming,
+    ClearCacheOptionsConfirming
  };
-  enum class ActionType { Archive, Delete, RemoveFromRecents, ClearAllRecents };
+  enum class ActionType { Archive, Delete, RemoveFromRecents, ClearCache, ClearAllRecents };

 private:
  TaskHandle_t displayTaskHandle = nullptr;
@ -62,8 +63,9 @@ class MyLibraryActivity final : public Activity {
  ActionType selectedAction = ActionType::Archive;
  std::string actionTargetPath;
  std::string actionTargetName;
-  int menuSelection = 0;                  // 0 = Archive, 1 = Delete
-  bool ignoreNextConfirmRelease = false;  // Prevents immediate selection after long-press opens menu
+  int menuSelection = 0;                   // 0 = Archive, 1 = Delete
+  bool ignoreNextConfirmRelease = false;   // Prevents immediate selection after long-press opens menu
+  bool clearCachePreserveProgress = true;  // For Clear Cache: whether to preserve reading progress

  // Recent tab state
  std::vector<RecentBook> recentBooks;
@ -153,6 +155,9 @@ class MyLibraryActivity final : public Activity {
  // Clear all recents confirmation
  void renderClearAllRecentsConfirmation() const;

+  // Clear cache options confirmation
+  void renderClearCacheOptionsConfirmation() const;
+
 public:
  explicit MyLibraryActivity(
      GfxRenderer& renderer, MappedInputManager& mappedInput, const std::function<void()>& onGoHome,
--- a/src/activities/network/CrossPointWebServerActivity.cpp
+++ b/src/activities/network/CrossPointWebServerActivity.cpp
@ -300,6 +300,36 @@ void CrossPointWebServerActivity::startAccessPoint() {
  startWebServer();
 }

+void CrossPointWebServerActivity::generateQRCodes() {
+  Serial.printf("[%lu] [WEBACT] Generating QR codes (cached)...\n", millis());
+  const unsigned long startTime = millis();
+
+  // Web browser URL QR code
+  std::string webUrl = "http://" + connectedIP + "/";
+  qrcode_initText(&qrWebBrowser, qrWebBrowserBuffer, 4, ECC_LOW, webUrl.c_str());
+  Serial.printf("[%lu] [WEBACT] QR cached: %s\n", millis(), webUrl.c_str());
+
+  // Companion App (Files) deep link QR code
+  std::string filesUrl = getCompanionAppUrl();
+  qrcode_initText(&qrCompanionApp, qrCompanionAppBuffer, 4, ECC_LOW, filesUrl.c_str());
+  Serial.printf("[%lu] [WEBACT] QR cached: %s\n", millis(), filesUrl.c_str());
+
+  // Companion App (Library) deep link QR code
+  std::string libraryUrl = getCompanionAppLibraryUrl();
+  qrcode_initText(&qrCompanionAppLibrary, qrCompanionAppLibraryBuffer, 4, ECC_LOW, libraryUrl.c_str());
+  Serial.printf("[%lu] [WEBACT] QR cached: %s\n", millis(), libraryUrl.c_str());
+
+  // WiFi config QR code (for AP mode)
+  if (isApMode) {
+    std::string wifiConfig = std::string("WIFI:S:") + connectedSSID + ";;";
+    qrcode_initText(&qrWifiConfig, qrWifiConfigBuffer, 4, ECC_LOW, wifiConfig.c_str());
+    Serial.printf("[%lu] [WEBACT] QR cached: %s\n", millis(), wifiConfig.c_str());
+  }
+
+  qrCacheValid = true;
+  Serial.printf("[%lu] [WEBACT] QR codes cached in %lu ms\n", millis(), millis() - startTime);
+}
+
 void CrossPointWebServerActivity::startWebServer() {
  Serial.printf("[%lu] [WEBACT] Starting web server...\n", millis());

@ -311,6 +341,9 @@ void CrossPointWebServerActivity::startWebServer() {
    state = WebServerActivityState::SERVER_RUNNING;
    Serial.printf("[%lu] [WEBACT] Web server started successfully\n", millis());

+    // Generate and cache QR codes now that we have IP and server ports
+    generateQRCodes();
+
    // Force an immediate render since we're transitioning from a subactivity
    // that had its own rendering task. We need to make sure our display is shown.
    xSemaphoreTake(renderingMutex, portMAX_DELAY);
@ -468,23 +501,18 @@ void CrossPointWebServerActivity::render() const {
  }
 }

-// Draw QR code at specified position with configurable pixel size per module
+// Draw QR code from pre-computed QRCode data at specified position
 // Returns the size of the QR code in pixels (width = height = size * pixelsPerModule)
-int drawQRCode(const GfxRenderer& renderer, const int x, const int y, const std::string& data,
-               const uint8_t pixelsPerModule = 7) {
-  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());
-  for (uint8_t cy = 0; cy < qrcode.size; cy++) {
-    for (uint8_t cx = 0; cx < qrcode.size; cx++) {
-      if (qrcode_getModule(&qrcode, cx, cy)) {
+int drawQRCodeCached(const GfxRenderer& renderer, const int x, const int y, QRCode* qrcode,
+                     const uint8_t pixelsPerModule = 7) {
+  for (uint8_t cy = 0; cy < qrcode->size; cy++) {
+    for (uint8_t cx = 0; cx < qrcode->size; cx++) {
+      if (qrcode_getModule(qrcode, cx, cy)) {
        renderer.fillRect(x + pixelsPerModule * cx, y + pixelsPerModule * cy, pixelsPerModule, pixelsPerModule, true);
      }
    }
  }
-  return qrcode.size * pixelsPerModule;
+  return qrcode->size * pixelsPerModule;
 }

 // Helper to format bytes into human-readable sizes
@ -612,8 +640,7 @@ void CrossPointWebServerActivity::renderWebBrowserScreen() const {

  if (isApMode) {
    // AP mode: Show WiFi QR code on left, connection info on right
-    const std::string wifiConfig = std::string("WIFI:S:") + connectedSSID + ";;";
-    drawQRCode(renderer, QR_X, QR_Y, wifiConfig, QR_PX);
+    drawQRCodeCached(renderer, QR_X, QR_Y, &qrWifiConfig, QR_PX);

    std::string ssidInfo = "Network: " + connectedSSID;
    renderer.drawText(NOTOSANS_12_FONT_ID, TEXT_X, textY, ssidInfo.c_str());
@ -635,8 +662,7 @@ void CrossPointWebServerActivity::renderWebBrowserScreen() const {
    renderer.drawText(UI_12_FONT_ID, TEXT_X, textY, hostnameUrl.c_str());
  } else {
    // STA mode: Show URL QR code on left, connection info on right
-    std::string webUrl = "http://" + connectedIP + "/";
-    drawQRCode(renderer, QR_X, QR_Y, webUrl, QR_PX);
+    drawQRCodeCached(renderer, QR_X, QR_Y, &qrWebBrowser, QR_PX);

    std::string ssidInfo = "Network: " + connectedSSID;
    if (ssidInfo.length() > 35) {
@ -650,6 +676,7 @@ void CrossPointWebServerActivity::renderWebBrowserScreen() const {
    renderer.drawText(NOTOSANS_12_FONT_ID, TEXT_X, textY, ipInfo.c_str());
    textY += LINE_SPACING + 8;

+    std::string webUrl = "http://" + connectedIP + "/";
    renderer.drawText(UI_12_FONT_ID, TEXT_X, textY, webUrl.c_str(), true, EpdFontFamily::BOLD);
    textY += LINE_SPACING - 4;

@ -704,12 +731,12 @@ void CrossPointWebServerActivity::renderCompanionAppScreen() const {
  std::string webUrl = "http://" + connectedIP + "/files";
  renderer.drawText(UI_12_FONT_ID, TEXT_X, textY, webUrl.c_str());

-  // Draw QR code on left
-  const std::string appUrl = getCompanionAppUrl();
-  drawQRCode(renderer, QR_X, QR_Y, appUrl, QR_PX);
+  // Draw cached QR code on left
+  drawQRCodeCached(renderer, QR_X, QR_Y, &qrCompanionApp, QR_PX);

  // Show deep link URL below QR code
  const int urlY = QR_Y + QR_SIZE + 10;
+  const std::string appUrl = getCompanionAppUrl();
  renderer.drawText(UI_12_FONT_ID, QR_X, urlY, appUrl.c_str(), true, EpdFontFamily::BOLD);
 }

@ -754,11 +781,11 @@ void CrossPointWebServerActivity::renderCompanionAppLibraryScreen() const {
  std::string webUrl = "http://" + connectedIP + "/";
  renderer.drawText(UI_12_FONT_ID, TEXT_X, textY, webUrl.c_str());

-  // Draw QR code on left
-  const std::string appUrl = getCompanionAppLibraryUrl();
-  drawQRCode(renderer, QR_X, QR_Y, appUrl, QR_PX);
+  // Draw cached QR code on left
+  drawQRCodeCached(renderer, QR_X, QR_Y, &qrCompanionAppLibrary, QR_PX);

  // Show deep link URL below QR code
  const int urlY = QR_Y + QR_SIZE + 10;
+  const std::string appUrl = getCompanionAppLibraryUrl();
  renderer.drawText(UI_12_FONT_ID, QR_X, urlY, appUrl.c_str(), true, EpdFontFamily::BOLD);
 }
--- a/src/activities/network/CrossPointWebServerActivity.h
+++ b/src/activities/network/CrossPointWebServerActivity.h
@ -2,6 +2,7 @@
 #include <freertos/FreeRTOS.h>
 #include <freertos/semphr.h>
 #include <freertos/task.h>
+#include <qrcode.h>

 #include <functional>
 #include <memory>
@ -11,6 +12,10 @@
 #include "activities/ActivityWithSubactivity.h"
 #include "network/CrossPointWebServer.h"

+// QR code cache - version 4 QR codes (33x33 modules)
+// Buffer size for version 4: qrcode_getBufferSize(4) ≈ 185 bytes
+constexpr size_t QR_BUFFER_SIZE = 185;
+
 // Web server activity states
 enum class WebServerActivityState {
  MODE_SELECTION,  // Choosing between Join Network and Create Hotspot
@ -62,6 +67,19 @@ class CrossPointWebServerActivity final : public ActivityWithSubactivity {
  FileTransferScreen currentScreen = FileTransferScreen::COMPANION_APP_LIBRARY;
  unsigned long lastStatsRefresh = 0;

+  // Cached QR codes - generated once when server starts
+  // Avoids recomputing QR data on every render (every 30s stats refresh)
+  // Marked mutable since QR drawing doesn't modify logical state but qrcode_getModule takes non-const
+  bool qrCacheValid = false;
+  mutable QRCode qrWebBrowser = {};
+  mutable QRCode qrCompanionApp = {};
+  mutable QRCode qrCompanionAppLibrary = {};
+  mutable QRCode qrWifiConfig = {};  // For AP mode WiFi connection QR
+  uint8_t qrWebBrowserBuffer[QR_BUFFER_SIZE] = {};
+  uint8_t qrCompanionAppBuffer[QR_BUFFER_SIZE] = {};
+  uint8_t qrCompanionAppLibraryBuffer[QR_BUFFER_SIZE] = {};
+  uint8_t qrWifiConfigBuffer[QR_BUFFER_SIZE] = {};
+
  static void taskTrampoline(void* param);
  [[noreturn]] void displayTaskLoop();
  void render() const;
@ -78,6 +96,7 @@ class CrossPointWebServerActivity final : public ActivityWithSubactivity {
  void startAccessPoint();
  void startWebServer();
  void stopWebServer();
+  void generateQRCodes();

 public:
  explicit CrossPointWebServerActivity(GfxRenderer& renderer, MappedInputManager& mappedInput,
--- a/src/activities/network/WifiSelectionActivity.cpp
+++ b/src/activities/network/WifiSelectionActivity.cpp
@ -3,7 +3,7 @@
 #include <GfxRenderer.h>
 #include <WiFi.h>

-#include <map>
+#include <algorithm>

 #include "MappedInputManager.h"
 #include "WifiCredentialStore.h"
@ -124,48 +124,55 @@ void WifiSelectionActivity::processWifiScanResults() {
  }

  // Scan complete, process results
-  // Use a map to deduplicate networks by SSID, keeping the strongest signal
-  std::map<std::string, WifiNetworkInfo> uniqueNetworks;
+  // Deduplicate directly into the networks vector (avoids std::map overhead)
+  networks.clear();
+  networks.reserve(std::min(scanResult, static_cast<int16_t>(20)));  // Limit to 20 networks max

  for (int i = 0; i < scanResult; i++) {
-    std::string ssid = WiFi.SSID(i).c_str();
+    String ssidStr = WiFi.SSID(i);
    const int32_t rssi = WiFi.RSSI(i);

    // Skip hidden networks (empty SSID)
-    if (ssid.empty()) {
+    if (ssidStr.isEmpty()) {
      continue;
    }

-    // Check if we've already seen this SSID
-    auto it = uniqueNetworks.find(ssid);
-    if (it == uniqueNetworks.end() || rssi > it->second.rssi) {
-      // New network or stronger signal than existing entry
+    std::string ssid = ssidStr.c_str();
+
+    // Check if we've already seen this SSID (linear search is fine for small lists)
+    auto existing = std::find_if(networks.begin(), networks.end(),
+                                 [&ssid](const WifiNetworkInfo& net) { return net.ssid == ssid; });
+
+    if (existing != networks.end()) {
+      // Update if stronger signal
+      if (rssi > existing->rssi) {
+        existing->rssi = rssi;
+        existing->isEncrypted = (WiFi.encryptionType(i) != WIFI_AUTH_OPEN);
+      }
+    } else if (networks.size() < 20) {
+      // New network - only add if under limit
      WifiNetworkInfo network;
-      network.ssid = ssid;
+      network.ssid = std::move(ssid);
      network.rssi = rssi;
      network.isEncrypted = (WiFi.encryptionType(i) != WIFI_AUTH_OPEN);
      network.hasSavedPassword = WIFI_STORE.hasSavedCredential(network.ssid);
-      uniqueNetworks[ssid] = network;
+      networks.push_back(std::move(network));
    }
  }

-  // Convert map to vector
-  networks.clear();
-  for (const auto& pair : uniqueNetworks) {
-    // cppcheck-suppress useStlAlgorithm
-    networks.push_back(pair.second);
-  }
+  // Free WiFi scan memory immediately (before sorting)
+  WiFi.scanDelete();

-  // Sort by signal strength (strongest first)
-  std::sort(networks.begin(), networks.end(),
-            [](const WifiNetworkInfo& a, const WifiNetworkInfo& b) { return a.rssi > b.rssi; });
-
-  // Show networks with PW first
+  // Sort by signal strength (strongest first), then by saved password
  std::sort(networks.begin(), networks.end(), [](const WifiNetworkInfo& a, const WifiNetworkInfo& b) {
-    return a.hasSavedPassword && !b.hasSavedPassword;
+    // Primary: saved passwords first
+    if (a.hasSavedPassword != b.hasSavedPassword) {
+      return a.hasSavedPassword;
+    }
+    // Secondary: strongest signal first
+    return a.rssi > b.rssi;
  });

-  WiFi.scanDelete();
  state = WifiSelectionState::NETWORK_LIST;
  selectedNetworkIndex = 0;
  updateRequired = true;
--- a/src/activities/reader/EpubReaderActivity.cpp
+++ b/src/activities/reader/EpubReaderActivity.cpp
@ -89,7 +89,7 @@ void EpubReaderActivity::onEnter() {
    renderer.fillRect(boxX, boxY, boxWidth, boxHeight, false);
    renderer.drawRect(boxX + 5, boxY + 5, boxWidth - 10, boxHeight - 10);
    renderer.drawText(UI_12_FONT_ID, boxX + boxMargin, boxY + boxMargin, "Preparing book... [0%]");
-    renderer.displayBuffer(EInkDisplay::FAST_REFRESH);
+    renderer.displayBuffer(HalDisplay::FAST_REFRESH);

    // Generate covers with progress callback
    epub->generateAllCovers([&](int percent) {
@ -103,7 +103,7 @@ void EpubReaderActivity::onEnter() {
        char progressStr[32];
        snprintf(progressStr, sizeof(progressStr), "Preparing book... [%d%%]", percent);
        renderer.drawText(UI_12_FONT_ID, boxX + boxMargin, boxY + boxMargin, progressStr);
-        renderer.displayBuffer(EInkDisplay::FAST_REFRESH);
+        renderer.displayBuffer(HalDisplay::FAST_REFRESH);
      }
    });
  }
@ -138,7 +138,7 @@ void EpubReaderActivity::onEnter() {
          nextPageNumber = data[2] + (data[3] << 8);
          hasContentOffset = false;
          Serial.printf("[%lu] [ERS] Loaded legacy progress (unknown version %d): spine %d, page %d\n", millis(),
-                      version, currentSpineIndex, nextPageNumber);
+                        version, currentSpineIndex, nextPageNumber);
        }
      }
    } else if (fileSize >= 4) {
@ -717,7 +717,7 @@ void EpubReaderActivity::renderScreen() {
      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);
+        renderer.displayBuffer(HalDisplay::FAST_REFRESH);
      };

      if (!section->createSectionFile(SETTINGS.getReaderFontId(), SETTINGS.getReaderLineCompression(),
@ -761,8 +761,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);
+    Serial.printf("[%lu] [ERS] Page out of bounds: %d (max %d)\n", millis(), section->currentPage, section->pageCount);
    renderer.drawCenteredText(UI_12_FONT_ID, 300, "Out of bounds", true, EpdFontFamily::BOLD);
    renderStatusBar(orientedMarginRight, orientedMarginBottom, orientedMarginLeft);
    renderer.displayBuffer();
@ -835,7 +834,7 @@ void EpubReaderActivity::renderContents(std::unique_ptr<Page> page, const int or

  renderStatusBar(orientedMarginRight, orientedMarginBottom, orientedMarginLeft);
  if (pagesUntilFullRefresh <= 1) {
-    renderer.displayBuffer(EInkDisplay::HALF_REFRESH);
+    renderer.displayBuffer(HalDisplay::HALF_REFRESH);
    pagesUntilFullRefresh = SETTINGS.getRefreshFrequency();
  } else {
    renderer.displayBuffer();
--- a/src/activities/reader/TxtReaderActivity.cpp
+++ b/src/activities/reader/TxtReaderActivity.cpp
@ -85,7 +85,7 @@ void TxtReaderActivity::onEnter() {
    renderer.fillRect(boxX, boxY, boxWidth, boxHeight, false);
    renderer.drawRect(boxX + 5, boxY + 5, boxWidth - 10, boxHeight - 10);
    renderer.drawText(UI_12_FONT_ID, boxX + boxMargin, boxY + boxMargin, "Preparing book... [0%]");
-    renderer.displayBuffer(EInkDisplay::FAST_REFRESH);
+    renderer.displayBuffer(HalDisplay::FAST_REFRESH);

    // Generate covers with progress callback
    (void)txt->generateAllCovers([&](int percent) {
@ -99,7 +99,7 @@ void TxtReaderActivity::onEnter() {
        char progressStr[32];
        snprintf(progressStr, sizeof(progressStr), "Preparing book... [%d%%]", percent);
        renderer.drawText(UI_12_FONT_ID, boxX + boxMargin, boxY + boxMargin, progressStr);
-        renderer.displayBuffer(EInkDisplay::FAST_REFRESH);
+        renderer.displayBuffer(HalDisplay::FAST_REFRESH);
      }
    });
  }
@ -339,7 +339,7 @@ void TxtReaderActivity::buildPageIndex() {
      // Fill progress bar
      const int fillWidth = (barWidth - 2) * progressPercent / 100;
      renderer.fillRect(barX + 1, barY + 1, fillWidth, barHeight - 2, true);
-      renderer.displayBuffer(EInkDisplay::FAST_REFRESH);
+      renderer.displayBuffer(HalDisplay::FAST_REFRESH);
    }

    // Yield to other tasks periodically
@ -571,7 +571,7 @@ void TxtReaderActivity::renderPage() {
  renderStatusBar(orientedMarginRight, orientedMarginBottom, orientedMarginLeft);

  if (pagesUntilFullRefresh <= 1) {
-    renderer.displayBuffer(EInkDisplay::HALF_REFRESH);
+    renderer.displayBuffer(HalDisplay::HALF_REFRESH);
    pagesUntilFullRefresh = SETTINGS.getRefreshFrequency();
  } else {
    renderer.displayBuffer();
--- a/src/activities/settings/ClearCacheActivity.cpp
+++ b/src/activities/settings/ClearCacheActivity.cpp
@ -4,6 +4,9 @@
 #include <HardwareSerial.h>
 #include <SDCardManager.h>

+#include <string>
+#include <vector>
+
 #include "MappedInputManager.h"
 #include "activities/home/HomeActivity.h"
 #include "activities/home/MyLibraryActivity.h"
@ -19,6 +22,7 @@ void ClearCacheActivity::onEnter() {

  renderingMutex = xSemaphoreCreateMutex();
  state = WARNING;
+  preserveProgress = true;  // Default to preserving progress
  updateRequired = true;

  xTaskCreate(&ClearCacheActivity::taskTrampoline, "ClearCacheActivityTask",
@ -56,6 +60,7 @@ void ClearCacheActivity::displayTaskLoop() {
 }

 void ClearCacheActivity::render() {
+  const auto pageWidth = renderer.getScreenWidth();
  const auto pageHeight = renderer.getScreenHeight();

  // Bezel compensation
@ -67,11 +72,32 @@ void ClearCacheActivity::render() {
  renderer.drawCenteredText(UI_12_FONT_ID, 15 + bezelTop, "Clear Cache", true, EpdFontFamily::BOLD);

  if (state == WARNING) {
-    renderer.drawCenteredText(UI_10_FONT_ID, centerY - 60, "This will clear all cached book data.", true);
-    renderer.drawCenteredText(UI_10_FONT_ID, centerY - 30, "All reading progress will be lost!", true,
-                              EpdFontFamily::BOLD);
-    renderer.drawCenteredText(UI_10_FONT_ID, centerY + 10, "Books will need to be re-indexed", true);
-    renderer.drawCenteredText(UI_10_FONT_ID, centerY + 30, "when opened again.", true);
+    renderer.drawCenteredText(UI_10_FONT_ID, centerY - 70, "This will clear all cached book data.", true);
+    renderer.drawCenteredText(UI_10_FONT_ID, centerY - 45, "Books will need to be re-indexed.", true);
+
+    // Preserve progress option
+    renderer.drawCenteredText(UI_10_FONT_ID, centerY - 5, "Preserve reading progress?");
+
+    // Yes/No options
+    constexpr int optionLineHeight = 30;
+    constexpr int optionWidth = 80;
+    const int optionX = (pageWidth - optionWidth) / 2;
+    const int optionStartY = centerY + 25;
+
+    // Yes option
+    if (preserveProgress) {
+      renderer.fillRect(optionX - 10, optionStartY - 5, optionWidth + 20, optionLineHeight);
+    }
+    renderer.drawCenteredText(UI_10_FONT_ID, optionStartY, "Yes", !preserveProgress);
+
+    // No option
+    if (!preserveProgress) {
+      renderer.fillRect(optionX - 10, optionStartY + optionLineHeight - 5, optionWidth + 20, optionLineHeight);
+    }
+    renderer.drawCenteredText(UI_10_FONT_ID, optionStartY + optionLineHeight, "No", preserveProgress);
+
+    // Draw side button hints (up/down navigation)
+    renderer.drawSideButtonHints(UI_10_FONT_ID, ">", "<");

    const auto labels = mappedInput.mapLabels("« Cancel", "Clear", "", "");
    renderer.drawButtonHints(UI_10_FONT_ID, labels.btn1, labels.btn2, labels.btn3, labels.btn4);
@ -110,8 +136,68 @@ void ClearCacheActivity::render() {
  }
 }

+void ClearCacheActivity::clearCacheDirectory(const char* dirPath) {
+  // Helper to check if a file should be preserved
+  const auto shouldPreserve = [this](const char* name) {
+    if (!preserveProgress) return false;
+    // Preserve progress and bookmarks when preserveProgress is enabled
+    return (strcmp(name, "progress.bin") == 0 || strcmp(name, "bookmarks.bin") == 0);
+  };
+
+  FsFile dir = SdMan.open(dirPath);
+  if (!dir || !dir.isDirectory()) {
+    if (dir) dir.close();
+    failedCount++;
+    return;
+  }
+
+  char name[128];
+  std::vector<std::string> filesToDelete;
+  std::vector<std::string> dirsToDelete;
+
+  // First pass: collect files and directories to delete
+  for (FsFile entry = dir.openNextFile(); entry; entry = dir.openNextFile()) {
+    entry.getName(name, sizeof(name));
+    const bool isDir = entry.isDirectory();
+    entry.close();
+
+    std::string fullPath = std::string(dirPath) + "/" + name;
+    if (isDir) {
+      dirsToDelete.push_back(fullPath);
+    } else if (!shouldPreserve(name)) {
+      filesToDelete.push_back(fullPath);
+    }
+  }
+  dir.close();
+
+  // Delete files
+  for (const auto& path : filesToDelete) {
+    if (SdMan.remove(path.c_str())) {
+      clearedCount++;
+    } else {
+      Serial.printf("[%lu] [CLEAR_CACHE] Failed to delete file: %s\n", millis(), path.c_str());
+      failedCount++;
+    }
+  }
+
+  // Delete subdirectories (like "sections/")
+  for (const auto& path : dirsToDelete) {
+    if (SdMan.removeDir(path.c_str())) {
+      clearedCount++;
+    } else {
+      Serial.printf("[%lu] [CLEAR_CACHE] Failed to delete dir: %s\n", millis(), path.c_str());
+      failedCount++;
+    }
+  }
+
+  // If not preserving progress, try to remove the now-empty directory
+  if (!preserveProgress) {
+    SdMan.rmdir(dirPath);  // This will fail if directory is not empty, which is fine
+  }
+}
+
 void ClearCacheActivity::clearCache() {
-  Serial.printf("[%lu] [CLEAR_CACHE] Clearing cache...\n", millis());
+  Serial.printf("[%lu] [CLEAR_CACHE] Clearing cache (preserveProgress=%d)...\n", millis(), preserveProgress);

  // Open .crosspoint directory
  auto root = SdMan.open("/.crosspoint");
@ -127,35 +213,32 @@ void ClearCacheActivity::clearCache() {
  failedCount = 0;
  char name[128];

-  // Iterate through all entries in the directory
+  // Collect all book cache directories first
+  std::vector<std::string> cacheDirs;
  for (auto file = root.openNextFile(); file; file = root.openNextFile()) {
    file.getName(name, sizeof(name));
    String itemName(name);

-    // Only delete directories starting with epub_ or txt_
+    // Only process directories starting with epub_ or txt_
    if (file.isDirectory() && (itemName.startsWith("epub_") || itemName.startsWith("txt_"))) {
-      String fullPath = "/.crosspoint/" + itemName;
-      Serial.printf("[%lu] [CLEAR_CACHE] Removing cache: %s\n", millis(), fullPath.c_str());
-
-      file.close();  // Close before attempting to delete
-
-      if (SdMan.removeDir(fullPath.c_str())) {
-        clearedCount++;
-      } else {
-        Serial.printf("[%lu] [CLEAR_CACHE] Failed to remove: %s\n", millis(), fullPath.c_str());
-        failedCount++;
-      }
-    } else {
-      file.close();
+      cacheDirs.push_back("/.crosspoint/" + std::string(name));
    }
+    file.close();
  }
  root.close();

+  // Now clear each cache directory
+  for (const auto& cacheDir : cacheDirs) {
+    Serial.printf("[%lu] [CLEAR_CACHE] Clearing: %s\n", millis(), cacheDir.c_str());
+    clearCacheDirectory(cacheDir.c_str());
+  }
+
  // Also clear in-memory caches since disk cache is gone
  HomeActivity::freeCoverBufferIfAllocated();
  MyLibraryActivity::clearThumbExistsCache();

-  Serial.printf("[%lu] [CLEAR_CACHE] Cache cleared: %d removed, %d failed\n", millis(), clearedCount, failedCount);
+  Serial.printf("[%lu] [CLEAR_CACHE] Cache cleared: %d items removed, %d failed\n", millis(), clearedCount,
+                failedCount);

  state = SUCCESS;
  updateRequired = true;
@ -163,8 +246,17 @@ void ClearCacheActivity::clearCache() {

 void ClearCacheActivity::loop() {
  if (state == WARNING) {
+    // Up/Down toggle preserve progress option
+    if (mappedInput.wasPressed(MappedInputManager::Button::Up) ||
+        mappedInput.wasPressed(MappedInputManager::Button::Down)) {
+      preserveProgress = !preserveProgress;
+      updateRequired = true;
+      return;
+    }
+
    if (mappedInput.wasPressed(MappedInputManager::Button::Confirm)) {
-      Serial.printf("[%lu] [CLEAR_CACHE] User confirmed, starting cache clear\n", millis());
+      Serial.printf("[%lu] [CLEAR_CACHE] User confirmed (preserveProgress=%d), starting cache clear\n", millis(),
+                    preserveProgress);
      xSemaphoreTake(renderingMutex, portMAX_DELAY);
      state = CLEARING;
      xSemaphoreGive(renderingMutex);
--- a/src/activities/settings/ClearCacheActivity.h
+++ b/src/activities/settings/ClearCacheActivity.h
@ -29,9 +29,11 @@ class ClearCacheActivity final : public ActivityWithSubactivity {

  int clearedCount = 0;
  int failedCount = 0;
+  bool preserveProgress = true;  // Whether to keep progress.bin and bookmarks.bin

  static void taskTrampoline(void* param);
  [[noreturn]] void displayTaskLoop();
  void render();
  void clearCache();
+  void clearCacheDirectory(const char* dirPath);  // Helper to clear a single book's cache
 };
--- a/src/activities/settings/SettingsActivity.cpp
+++ b/src/activities/settings/SettingsActivity.cpp
@ -15,7 +15,7 @@ namespace {
 // Visibility condition for bezel edge setting (only show when compensation > 0)
 bool isBezelCompensationEnabled() { return SETTINGS.bezelCompensation > 0; }

-constexpr int displaySettingsCount = 9;
+constexpr int displaySettingsCount = 10;
 const SettingInfo displaySettings[displaySettingsCount] = {
    // Should match with SLEEP_SCREEN_MODE
    SettingInfo::Enum("Sleep Screen", &CrossPointSettings::sleepScreen, {"Dark", "Light", "Custom", "Cover", "None"}),
@ -28,6 +28,7 @@ const SettingInfo displaySettings[displaySettingsCount] = {
    SettingInfo::Enum("Hide Battery %", &CrossPointSettings::hideBatteryPercentage, {"Never", "In Reader", "Always"}),
    SettingInfo::Enum("Refresh Frequency", &CrossPointSettings::refreshFrequency,
                      {"1 page", "5 pages", "10 pages", "15 pages", "30 pages"}),
+    SettingInfo::Enum("Sunlight Fading Fix", &CrossPointSettings::fadingFix, {"OFF", "ON"}),
    SettingInfo::Value("Bezel Compensation", &CrossPointSettings::bezelCompensation, {0, 10, 1}),
    SettingInfo::Enum("Bezel Edge", &CrossPointSettings::bezelCompensationEdge, {"Bottom", "Top", "Left", "Right"},
                      isBezelCompensationEnabled)};
--- a/src/activities/util/FullScreenMessageActivity.h
+++ b/src/activities/util/FullScreenMessageActivity.h
@ -1,6 +1,6 @@
 #pragma once
-#include <EInkDisplay.h>
 #include <EpdFontFamily.h>
+#include <HalDisplay.h>

 #include <string>
 #include <utility>
@ -10,12 +10,12 @@
 class FullScreenMessageActivity final : public Activity {
  std::string text;
  EpdFontFamily::Style style;
-  EInkDisplay::RefreshMode refreshMode;
+  HalDisplay::RefreshMode refreshMode;

 public:
  explicit FullScreenMessageActivity(GfxRenderer& renderer, MappedInputManager& mappedInput, std::string text,
                                     const EpdFontFamily::Style style = EpdFontFamily::REGULAR,
-                                     const EInkDisplay::RefreshMode refreshMode = EInkDisplay::FAST_REFRESH)
+                                     const HalDisplay::RefreshMode refreshMode = HalDisplay::FAST_REFRESH)
      : Activity("FullScreenMessage", renderer, mappedInput),
        text(std::move(text)),
        style(style),
--- a/src/activities/util/KeyboardEntryActivity.cpp
+++ b/src/activities/util/KeyboardEntryActivity.cpp
@ -1,7 +1,7 @@
 #include "KeyboardEntryActivity.h"

-#include "activities/dictionary/DictionaryMargins.h"
 #include "MappedInputManager.h"
+#include "activities/dictionary/DictionaryMargins.h"
 #include "fontIds.h"

 // Keyboard layouts - lowercase
--- a/src/activities/util/QuickMenuActivity.h
+++ b/src/activities/util/QuickMenuActivity.h
@ -29,9 +29,9 @@ class QuickMenuActivity final : public Activity {
  const bool isPageBookmarked;  // True if current page already has a bookmark

  // Edit mode state
-  bool editMode = false;         // True when in edit mode
-  int movingIndex = -1;          // Index of item being moved (-1 if none)
-  uint8_t localOrder[5] = {0};   // Local copy of order for editing
+  bool editMode = false;        // True when in edit mode
+  int movingIndex = -1;         // Index of item being moved (-1 if none)
+  uint8_t localOrder[5] = {0};  // Local copy of order for editing

  static void taskTrampoline(void* param);
  [[noreturn]] void displayTaskLoop();
--- a/src/main.cpp
+++ b/src/main.cpp
@ -1,9 +1,9 @@
 #include <Arduino.h>
 #include <BitmapHelpers.h>
-#include <EInkDisplay.h>
 #include <Epub.h>
 #include <GfxRenderer.h>
-#include <InputManager.h>
+#include <HalDisplay.h>
+#include <HalGPIO.h>
 #include <SDCardManager.h>
 #include <SPI.h>
 #include <builtinFonts/all.h>
@ -32,23 +32,10 @@
 #include "fontIds.h"
 #include "images/LockIcon.h"

-#define SPI_FQ 40000000
-// Display SPI pins (custom pins for XteinkX4, not hardware SPI defaults)
-#define EPD_SCLK 8   // SPI Clock
-#define EPD_MOSI 10  // SPI MOSI (Master Out Slave In)
-#define EPD_CS 21    // Chip Select
-#define EPD_DC 4     // Data/Command
-#define EPD_RST 5    // Reset
-#define EPD_BUSY 6   // Busy
-
-#define UART0_RXD 20  // Used for USB connection detection
-
-#define SD_SPI_MISO 7
-
-EInkDisplay einkDisplay(EPD_SCLK, EPD_MOSI, EPD_CS, EPD_DC, EPD_RST, EPD_BUSY);
-InputManager inputManager;
-MappedInputManager mappedInputManager(inputManager);
-GfxRenderer renderer(einkDisplay);
+HalDisplay display;
+HalGPIO gpio;
+MappedInputManager mappedInputManager(gpio);
+GfxRenderer renderer(display);
 Activity* currentActivity;

 // Fonts
@ -130,11 +117,14 @@ void logMemoryState(const char* tag, const char* context) {
 #define logMemoryState(tag, context) ((void)0)
 #endif

-// Flash command detection - receives "FLASH\n" from pre_flash.py script
+// Flash command detection - receives "FLASH:version\n" from pre_flash.py script
+// Plan A: Simple polling - host sends command, device checks when Serial is connected
 static String flashCmdBuffer;

 void checkForFlashCommand() {
-  if (!Serial) return;  // Early exit if Serial not initialized
+  // Only check when Serial is connected (host has port open)
+  if (!Serial) return;
+
  while (Serial.available()) {
    char c = Serial.read();
    if (c == '\n') {
@ -165,56 +155,51 @@ void checkForFlashCommand() {
        const int screenH = renderer.getScreenHeight();

        // Show current version in bottom-left corner (orientation-aware)
-        // "Bottom-left" is relative to the current orientation
        constexpr int versionMargin = 10;
        const int textWidth = renderer.getTextWidth(SMALL_FONT_ID, CROSSPOINT_VERSION);
        int versionX, versionY;
        switch (renderer.getOrientation()) {
-          case GfxRenderer::Portrait:  // Bottom-left is actual bottom-left
+          case GfxRenderer::Portrait:
            versionX = versionMargin;
            versionY = screenH - 30;
            break;
-          case GfxRenderer::PortraitInverted:  // Bottom-left is actual top-right
+          case GfxRenderer::PortraitInverted:
            versionX = screenW - textWidth - versionMargin;
            versionY = 20;
            break;
-          case GfxRenderer::LandscapeClockwise:  // Bottom-left is actual bottom-right
+          case GfxRenderer::LandscapeClockwise:
            versionX = screenW - textWidth - versionMargin;
            versionY = screenH - 30;
            break;
-          case GfxRenderer::LandscapeCounterClockwise:  // Bottom-left is actual bottom-left
+          case GfxRenderer::LandscapeCounterClockwise:
            versionX = versionMargin;
            versionY = screenH - 30;
            break;
        }
        renderer.drawText(SMALL_FONT_ID, versionX, versionY, CROSSPOINT_VERSION, false);

-        // Position and rotate lock icon based on current orientation (USB port location)
-        // USB port locations: Portrait=bottom-left, PortraitInverted=top-right,
-        //                     LandscapeCW=top-left, LandscapeCCW=bottom-right
-        // Position offsets: edge margin + half-width offset to center on USB port
-        constexpr int edgeMargin = 28;                  // Distance from screen edge
-        constexpr int halfWidth = LOCK_ICON_WIDTH / 2;  // 16px offset for centering
+        // Position and rotate lock icon based on current orientation
+        constexpr int edgeMargin = 28;
+        constexpr int halfWidth = LOCK_ICON_WIDTH / 2;
        int iconX, iconY;
        GfxRenderer::ImageRotation rotation;
-        // Note: 90/270 rotation swaps output dimensions (W<->H)
        switch (renderer.getOrientation()) {
-          case GfxRenderer::Portrait:  // USB at bottom-left, shackle points right
+          case GfxRenderer::Portrait:
            rotation = GfxRenderer::ROTATE_90;
            iconX = edgeMargin;
            iconY = screenH - LOCK_ICON_WIDTH - edgeMargin - halfWidth;
            break;
-          case GfxRenderer::PortraitInverted:  // USB at top-right, shackle points left
+          case GfxRenderer::PortraitInverted:
            rotation = GfxRenderer::ROTATE_270;
            iconX = screenW - LOCK_ICON_HEIGHT - edgeMargin;
            iconY = edgeMargin + halfWidth;
            break;
-          case GfxRenderer::LandscapeClockwise:  // USB at top-left, shackle points down
+          case GfxRenderer::LandscapeClockwise:
            rotation = GfxRenderer::ROTATE_180;
            iconX = edgeMargin + halfWidth;
            iconY = edgeMargin;
            break;
-          case GfxRenderer::LandscapeCounterClockwise:  // USB at bottom-right, shackle points up
+          case GfxRenderer::LandscapeCounterClockwise:
            rotation = GfxRenderer::ROTATE_0;
            iconX = screenW - LOCK_ICON_WIDTH - edgeMargin - halfWidth;
            iconY = screenH - LOCK_ICON_HEIGHT - edgeMargin;
@ -222,13 +207,13 @@ void checkForFlashCommand() {
        }
        renderer.drawImageRotated(LockIcon, iconX, iconY, LOCK_ICON_WIDTH, LOCK_ICON_HEIGHT, rotation);

-        renderer.displayBuffer(EInkDisplay::FAST_REFRESH);
+        // Use full refresh for clean display before flash overwrites firmware
+        renderer.displayBuffer(HalDisplay::HALF_REFRESH);
      }
      flashCmdBuffer = "";
    } else if (c != '\r') {
      flashCmdBuffer += c;
-      // Prevent buffer overflow from random serial data (increased for version info)
-      if (flashCmdBuffer.length() > 30) {
+      if (flashCmdBuffer.length() > 50) {
        flashCmdBuffer = "";
      }
    }
@ -274,21 +259,20 @@ void verifyPowerButtonDuration() {
  const uint16_t calibratedPressDuration =
      (calibration < SETTINGS.getPowerButtonDuration()) ? SETTINGS.getPowerButtonDuration() - calibration : 1;

-  inputManager.update();
-  // Verify the user has actually pressed
+  gpio.update();
  // Needed because inputManager.isPressed() may take up to ~500ms to return the correct state
-  while (!inputManager.isPressed(InputManager::BTN_POWER) && millis() - start < 1000) {
+  while (!gpio.isPressed(HalGPIO::BTN_POWER) && millis() - start < 1000) {
    delay(10);  // only wait 10ms each iteration to not delay too much in case of short configured duration.
-    inputManager.update();
+    gpio.update();
  }

  t2 = millis();
-  if (inputManager.isPressed(InputManager::BTN_POWER)) {
+  if (gpio.isPressed(HalGPIO::BTN_POWER)) {
    do {
      delay(10);
-      inputManager.update();
-    } while (inputManager.isPressed(InputManager::BTN_POWER) && inputManager.getHeldTime() < calibratedPressDuration);
-    abort = inputManager.getHeldTime() < calibratedPressDuration;
+      gpio.update();
+    } while (gpio.isPressed(HalGPIO::BTN_POWER) && gpio.getHeldTime() < calibratedPressDuration);
+    abort = gpio.getHeldTime() < calibratedPressDuration;
  } else {
    abort = true;
  }
@ -296,16 +280,15 @@ void verifyPowerButtonDuration() {
  if (abort) {
    // Button released too early. Returning to sleep.
    // IMPORTANT: Re-arm the wakeup trigger before sleeping again
-    esp_deep_sleep_enable_gpio_wakeup(1ULL << InputManager::POWER_BUTTON_PIN, ESP_GPIO_WAKEUP_GPIO_LOW);
-    esp_deep_sleep_start();
+    gpio.startDeepSleep();
  }
 }

 void waitForPowerRelease() {
-  inputManager.update();
-  while (inputManager.isPressed(InputManager::BTN_POWER)) {
+  gpio.update();
+  while (gpio.isPressed(HalGPIO::BTN_POWER)) {
    delay(50);
-    inputManager.update();
+    gpio.update();
  }
 }

@ -314,14 +297,11 @@ void enterDeepSleep() {
  exitActivity();
  enterNewActivity(new SleepActivity(renderer, mappedInputManager));

-  einkDisplay.deepSleep();
+  display.deepSleep();
  Serial.printf("[%lu] [   ] Power button press calibration value: %lu ms\n", millis(), t2 - t1);
  Serial.printf("[%lu] [   ] Entering deep sleep.\n", millis());
-  esp_deep_sleep_enable_gpio_wakeup(1ULL << InputManager::POWER_BUTTON_PIN, ESP_GPIO_WAKEUP_GPIO_LOW);
-  // Ensure that the power button has been released to avoid immediately turning back on if you're holding it
-  waitForPowerRelease();
-  // Enter Deep Sleep
-  esp_deep_sleep_start();
+
+  gpio.startDeepSleep();
 }

 void onGoHome();
@ -388,6 +368,7 @@ void onGoToFileTransfer() {
  APP_STATE.openBookTitle.shrink_to_fit();
  APP_STATE.openBookAuthor.clear();
  APP_STATE.openBookAuthor.shrink_to_fit();
+  HomeActivity::freeCoverBufferIfAllocated();  // Free 48KB cover buffer
  Serial.printf("[%lu] [FT] Cleared non-essential memory before File Transfer\n", millis());

  enterNewActivity(new CrossPointWebServerActivity(renderer, mappedInputManager, onGoHome));
@ -445,7 +426,7 @@ void onGoHome() {
 }

 void setupDisplayAndFonts() {
-  einkDisplay.begin();
+  display.begin();
  Serial.printf("[%lu] [   ] Display initialized\n", millis());
  renderer.insertFont(BOOKERLY_14_FONT_ID, bookerly14FontFamily);
 #ifndef OMIT_FONTS
@ -467,42 +448,24 @@ void setupDisplayAndFonts() {
  Serial.printf("[%lu] [   ] Fonts setup\n", millis());
 }

-bool isUsbConnected() {
-  // U0RXD/GPIO20 reads HIGH when USB is connected
-  return digitalRead(UART0_RXD) == HIGH;
-}
-
-bool isWakeupByPowerButton() {
-  const auto wakeupCause = esp_sleep_get_wakeup_cause();
-  const auto resetReason = esp_reset_reason();
-  if (isUsbConnected()) {
-    return wakeupCause == ESP_SLEEP_WAKEUP_GPIO;
-  } else {
-    return (wakeupCause == ESP_SLEEP_WAKEUP_UNDEFINED) && (resetReason == ESP_RST_POWERON);
-  }
-}
-
 void setup() {
  t1 = millis();

-  // Only start serial if USB connected
-  pinMode(UART0_RXD, INPUT);
-  if (isUsbConnected()) {
-    Serial.begin(115200);
-    // Wait up to 3 seconds for Serial to be ready to catch early logs
+  gpio.begin();
+
+  // Always initialize Serial - safe on ESP32-C3 USB CDC even without USB connected
+  // (the peripheral just remains idle).
+  Serial.begin(115200);
+
+  // Only wait for terminal connection if USB is physically connected
+  // This allows catching early debug logs when a serial monitor is attached
+  if (gpio.isUsbConnected()) {
    unsigned long start = millis();
    while (!Serial && (millis() - start) < 3000) {
      delay(10);
    }
  }

-  inputManager.begin();
-  // Initialize pins
-  pinMode(BAT_GPIO0, INPUT);
-
-  // Initialize SPI with custom pins
-  SPI.begin(EPD_SCLK, SD_SPI_MISO, EPD_MOSI, EPD_CS);
-
  // SD Card Initialization
  // We need 6 open files concurrently when parsing a new chapter
  if (!SdMan.begin()) {
@ -519,7 +482,7 @@ void setup() {
  // Apply bezel compensation from settings
  renderer.setBezelCompensation(SETTINGS.bezelCompensation, SETTINGS.bezelCompensationEdge);

-  if (isWakeupByPowerButton()) {
+  if (gpio.isWakeupByPowerButton()) {
    // For normal wakeups, verify power button press duration
    Serial.printf("[%lu] [   ] Verifying power button press duration\n", millis());
    verifyPowerButtonDuration();
@ -559,7 +522,9 @@ void loop() {
  const unsigned long loopStartTime = millis();
  static unsigned long lastMemPrint = 0;

-  inputManager.update();
+  gpio.update();
+
+  renderer.setFadingFix(SETTINGS.fadingFix);

  if (Serial && millis() - lastMemPrint >= 10000) {
    // Basic heap info
@ -577,8 +542,7 @@ void loop() {

  // Check for any user activity (button press or release) or active background work
  static unsigned long lastActivityTime = millis();
-  if (inputManager.wasAnyPressed() || inputManager.wasAnyReleased() ||
-      (currentActivity && currentActivity->preventAutoSleep())) {
+  if (gpio.wasAnyPressed() || gpio.wasAnyReleased() || (currentActivity && currentActivity->preventAutoSleep())) {
    lastActivityTime = millis();  // Reset inactivity timer
  }

@ -590,8 +554,7 @@ void loop() {
    return;
  }

-  if (inputManager.isPressed(InputManager::BTN_POWER) &&
-      inputManager.getHeldTime() > SETTINGS.getPowerButtonDuration()) {
+  if (gpio.isPressed(HalGPIO::BTN_POWER) && gpio.getHeldTime() > SETTINGS.getPowerButtonDuration()) {
    enterDeepSleep();
    // This should never be hit as `enterDeepSleep` calls esp_deep_sleep_start
    return;
--- a/src/network/CrossPointWebServer.cpp
+++ b/src/network/CrossPointWebServer.cpp
@ -371,27 +371,10 @@ void CrossPointWebServer::scanFiles(const char* path, const std::function<void(F
      if (info.isDirectory) {
        info.size = 0;
        info.isEpub = false;
-        // md5 remains empty for directories
      } else {
        info.size = file.size();
        info.isEpub = isEpubFile(info.name);
-
-        // For EPUBs, try to get cached MD5 hash
-        if (info.isEpub) {
-          // Build full file path
-          String fullPath = String(path);
-          if (!fullPath.endsWith("/")) {
-            fullPath += "/";
-          }
-          fullPath += fileName;
-
-          const std::string cachedMd5 =
-              Md5Utils::getCachedMd5(fullPath.c_str(), BookManager::CROSSPOINT_DIR, info.size);
-          if (!cachedMd5.empty()) {
-            info.md5 = String(cachedMd5.c_str());
-          }
-          // If not cached, md5 remains empty (companion app can request via /api/hash)
-        }
+        // MD5 not included in listing - clients can request via /api/hash endpoint
      }

      callback(info);
@ -435,89 +418,72 @@ void CrossPointWebServer::handleFileListData() const {
    }
  }

-  // Check if we should show hidden files
-  bool showHidden = false;
-  if (server->hasArg("showHidden")) {
-    showHidden = server->arg("showHidden") == "true";
-  }
-
-  // Check client connection before starting
-  if (!server->client().connected()) {
-    Serial.printf("[%lu] [WEB] Client disconnected before file list could start\n", millis());
-    return;
-  }
+  // Check if we should show hidden files (fork addition)
+  bool showHidden = server->hasArg("showHidden") && server->arg("showHidden") == "true";

  server->setContentLength(CONTENT_LENGTH_UNKNOWN);
  server->send(200, "application/json", "");
-  if (!sendContentSafe("[")) {
-    Serial.printf("[%lu] [WEB] Client disconnected at start of file list\n", millis());
-    return;
-  }

-  char output[512];
+  // Batch JSON entries to reduce number of sendContent calls
+  // This helps prevent TCP buffer overflow on memory-constrained systems
+  constexpr size_t BATCH_SIZE = 2048;
+  char batch[BATCH_SIZE];
+  size_t batchPos = 0;
+  batch[batchPos++] = '[';
+
+  char output[256];  // Single entry buffer (reduced from 512)
  constexpr size_t outputSize = sizeof(output);
  bool seenFirst = false;
-  bool clientDisconnected = false;
  JsonDocument doc;

  scanFiles(
      currentPath.c_str(),
-      [this, &output, &doc, &seenFirst, &clientDisconnected](const FileInfo& info) mutable {
-        // Skip remaining files if client already disconnected
-        if (clientDisconnected) {
-          return;
-        }
-
+      [this, &batch, &batchPos, &output, &doc, &seenFirst](const FileInfo& info) mutable {
        doc.clear();
        doc["name"] = info.name;
        doc["size"] = info.size;
        doc["isDirectory"] = info.isDirectory;
        doc["isEpub"] = info.isEpub;

-        // Include md5 field for EPUBs (null if not cached, hash string if available)
-        if (info.isEpub) {
-          if (info.md5.isEmpty()) {
-            doc["md5"] = nullptr;  // JSON null
-          } else {
-            doc["md5"] = info.md5;
-          }
-        }
-
        const size_t written = serializeJson(doc, output, outputSize);
        if (written >= outputSize) {
-          // JSON output truncated; skip this entry to avoid sending malformed JSON
          Serial.printf("[%lu] [WEB] Skipping file entry with oversized JSON for name: %s\n", millis(),
                        info.name.c_str());
          return;
        }

-        // Send comma separator before all entries except the first
+        // Calculate space needed: comma (if not first) + entry
+        const size_t needed = (seenFirst ? 1 : 0) + written;
+
+        // If batch would overflow, send it first
+        if (batchPos + needed >= BATCH_SIZE - 1) {
+          batch[batchPos] = '\0';
+          server->sendContent(batch);
+          delay(5);  // Brief delay between batch sends
+          batchPos = 0;
+        }
+
+        // Add comma separator if not first entry
        if (seenFirst) {
-          if (!sendContentSafe(",")) {
-            clientDisconnected = true;
-            Serial.printf("[%lu] [WEB] Client disconnected during file list\n", millis());
-            return;
-          }
+          batch[batchPos++] = ',';
        } else {
          seenFirst = true;
        }

-        // Send the JSON entry with flow control
-        if (!sendContentSafe(output)) {
-          clientDisconnected = true;
-          Serial.printf("[%lu] [WEB] Client disconnected during file list\n", millis());
-          return;
-        }
+        // Copy entry to batch
+        memcpy(batch + batchPos, output, written);
+        batchPos += written;
      },
      showHidden);

-  // Only send closing bracket if client is still connected
-  if (!clientDisconnected) {
-    sendContentSafe("]");
-    // End of streamed response, empty chunk to signal client
-    server->sendContent("");
-    Serial.printf("[%lu] [WEB] Served file listing page for path: %s\n", millis(), currentPath.c_str());
-  }
+  // Send remaining batch with closing bracket
+  batch[batchPos++] = ']';
+  batch[batchPos] = '\0';
+  server->sendContent(batch);
+
+  // End of streamed response, empty chunk to signal client
+  server->sendContent("");
+  Serial.printf("[%lu] [WEB] Served file listing page for path: %s\n", millis(), currentPath.c_str());
 }

 // Static variables for upload handling
@ -1295,39 +1261,15 @@ void CrossPointWebServer::handleRename() const {
  }
 }

-// Counter for flow control pacing
-static uint8_t sendContentCounter = 0;
-
 bool CrossPointWebServer::sendContentSafe(const char* content) const {
  if (!server || !server->client().connected()) {
    return false;
  }
-
-  // Send the content
  server->sendContent(content);
-
-  // Flow control: give TCP stack time to transmit data and drain the send buffer
-  // The ESP32 TCP buffer is limited and fills quickly when streaming many small chunks.
-  // We use progressive delays:
-  // - yield() after every send to allow WiFi processing
-  // - delay(5ms) every send to allow buffer draining
-  // - delay(50ms) every 10 sends to allow larger buffer flush
-  yield();
-  sendContentCounter++;
-
-  if (sendContentCounter >= 10) {
-    sendContentCounter = 0;
-    delay(50);  // Longer pause every 10 sends for buffer catchup
-  } else {
-    delay(5);   // Short pause each send
-  }
-
  return server->client().connected();
 }

-bool CrossPointWebServer::sendContentSafe(const String& content) const {
-  return sendContentSafe(content.c_str());
-}
+bool CrossPointWebServer::sendContentSafe(const String& content) const { return sendContentSafe(content.c_str()); }

 bool CrossPointWebServer::copyFile(const String& srcPath, const String& destPath) const {
  FsFile srcFile;
--- a/src/network/CrossPointWebServer.h
+++ b/src/network/CrossPointWebServer.h
@ -14,7 +14,6 @@ struct FileInfo {
  size_t size;
  bool isEpub;
  bool isDirectory;
-  String md5;  // MD5 hash for EPUBs (empty if not cached/available)
 };

 class CrossPointWebServer {
@ -108,7 +107,7 @@ class CrossPointWebServer {
  bool copyFile(const String& srcPath, const String& destPath) const;
  bool copyFolder(const String& srcPath, const String& destPath) const;

-  // Helper for safe content sending with flow control
+  // Helper for safe content sending with connection check
  // Returns false if client disconnected, true otherwise
  bool sendContentSafe(const char* content) const;
  bool sendContentSafe(const String& content) const;
Author	SHA1	Message	Date
cottongin	fbe7d2feb4	release: ef-1.0.5 - stability, memory, and upstream merges All checks were successful CI / build (push) Successful in 4m51s Details Compile Release / build-release (push) Successful in 1m18s Details Webserver: JSON batching, removed MD5 blocking, simplified flow control Memory: QR code caching, WiFi scan optimization, cover buffer leak fix EPUB: Fixed errant underlining before styled inline elements Flash screen: Version string overflow fix, half refresh for cleaner display Upstream merges: - PR #522: HAL abstraction layer (HalDisplay, HalGPIO) - PR #603: Sunlight fading fix toggle in Display settings	2026-01-30 23:20:23 -05:00
cottongin	520a0cb124	feat: implement sunlight fading fix (PR #603 ) Add user-toggleable setting to turn off display between refreshes, which helps mitigate the sunlight fading issue on e-ink displays. Changes: - Add turnOffScreen parameter to HalDisplay methods - Add fadingFix member and setFadingFix() to GfxRenderer - Add fadingFix setting to CrossPointSettings with persistence - Add "Sunlight Fading Fix" toggle in Display settings - Update SDK submodule with turnOffScreen support	2026-01-30 23:02:29 -05:00
cottongin	be8b02efd6	feat: merge PR #522 - add HalDisplay and HalGPIO abstraction layer Cherry-picked upstream PR #522 (da4d3b5) with conflict resolution: - Added new lib/hal/ files (HalDisplay, HalGPIO) - Updated GfxRenderer to use HalDisplay, preserving base viewable margins - Adopted PR #522's MappedInputManager lookup table implementation - Updated main.cpp to use HAL while preserving custom Serial initialization - Updated all EInkDisplay::RefreshMode references to HalDisplay::RefreshMode This introduces a Hardware Abstraction Layer for display and GPIO, enabling easier emulation and testing.	2026-01-30 22:49:52 -05:00
cottongin	448ce55bb4	Add individual book cache clearing with preserve progress option - Add "Clear Cache" option to book action menu in MyLibrary (both Recent and Files tabs) - Prompt user to preserve reading progress when clearing cache - Always preserve bookmarks when clearing individual book cache - Add preserve progress option to system-level Clear Cache in Settings - Implement BookManager::clearBookCache() for selective cache clearing	2026-01-30 22:22:22 -05:00
cottongin	5464d9de3a	fix: webserver stability, memory leaks, epub underlining, flash screen Webserver: - Remove MD5 hash computation from file listings (caused EAGAIN errors) - Implement JSON batching (2KB) with pacing for file listings - Simplify sendContentSafe() flow control Memory: - Cache QR codes on server start instead of regenerating per render - Optimize WiFi scan: vector deduplication, 20 network limit, early scanDelete() - Fix 48KB cover buffer leak when navigating Home -> File Transfer EPUB Reader: - Fix errant underlining by flushing partWordBuffer before style changes - Text before styled inline elements (e.g., <a> with CSS underline) no longer incorrectly receives the element's styling Flash Screen: - Fix version string buffer overflow (30 -> 50 char limit) - Use half refresh for cleaner display - Adjust pre_flash.py timing for half refresh completion	2026-01-30 22:00:15 -05:00