feat: Sleep screen letterbox fill and image upscaling

Add configurable letterbox fill for sleep screen cover images that don't
match the display aspect ratio. Four fill modes are available: Solid
(single dominant edge shade), Blended (per-pixel edge colors), Gradient
(edge colors interpolated toward white/black), and None.

Enable upscaling of cover images smaller than the display in Fit mode by
modifying drawBitmap/drawBitmap1Bit to support both up and downscaling
via a unified block-fill approach.

Edge sampling data is cached to .crosspoint alongside the cover BMP to
avoid redundant bitmap scanning on subsequent sleeps. Cache is validated
against screen dimensions and auto-regenerated when stale.

New settings: Letterbox Fill (None/Solid/Blended/Gradient) and Gradient
Direction (To White/To Black).

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

.github/workflows/ci.yml

@@ -1,10 +1,55 @@
-name: CI
-'on':
+name: CI (build)
+
+on:
   push:
     branches: [master]
   pull_request:
 
+permissions:
+  contents: read
+
 jobs:
+  clang-format:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          submodules: recursive
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: '3.14'
+
+      - name: Install clang-format-21
+        run: |
+          wget https://apt.llvm.org/llvm.sh
+          chmod +x llvm.sh
+          sudo ./llvm.sh 21
+          sudo apt-get update
+          sudo apt-get install -y clang-format-21
+
+      - name: Run clang-format
+        run: |
+          PATH="/usr/lib/llvm-21/bin:$PATH" ./bin/clang-format-fix
+          git diff --exit-code || (echo "Please run 'bin/clang-format-fix' to fix formatting issues" && exit 1)
+
+  cppcheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          submodules: recursive
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: '3.14'
+
+      - name: Install PlatformIO Core
+        run: pip install --upgrade platformio
+
+      - name: Run cppcheck
+        run: pio check --fail-on-defect low --fail-on-defect medium --fail-on-defect high
+
   build:
     runs-on: ubuntu-latest
     steps:
@@ -19,19 +64,46 @@ jobs:
       - name: Install PlatformIO Core
         run: pip install --upgrade platformio
 
-      - name: Install clang-format-21
-        run: |
-          wget https://apt.llvm.org/llvm.sh
-          chmod +x llvm.sh
-          sudo ./llvm.sh 21
-          sudo apt-get update
-          sudo apt-get install -y clang-format-21
-
-      - name: Run cppcheck
-        run: pio check --fail-on-defect low --fail-on-defect medium --fail-on-defect high
-
-      - name: Run clang-format
-        run: PATH="/usr/lib/llvm-21/bin:$PATH" ./bin/clang-format-fix && git diff --exit-code || (echo "Please run 'bin/clang-format-fix' to fix formatting issues" && exit 1)
-
       - name: Build CrossPoint
-        run: pio run
+        run: |
+          set -euo pipefail
+          pio run | tee pio.log
+
+      - name: Extract firmware stats
+
+        run: |
+          set -euo pipefail
+          ram_line="$(grep -E "RAM:\\s" -m1 pio.log || true)"
+          flash_line="$(grep -E "Flash:\\s" -m1 pio.log || true)"
+          echo "ram_line=${ram_line}" >> "$GITHUB_OUTPUT"
+          echo "flash_line=${flash_line}" >> "$GITHUB_OUTPUT"
+          {
+            echo "## Firmware build stats"
+            if [ -n "$ram_line" ]; then echo "- ${ram_line}"; else echo "- RAM: not found"; fi
+            if [ -n "$flash_line" ]; then echo "- ${flash_line}"; else echo "- Flash: not found"; fi
+          } >> "$GITHUB_STEP_SUMMARY"
+
+      - name: Upload firmware.bin artifact
+        uses: actions/upload-artifact@v6
+        with:
+          name: firmware.bin
+          path: .pio/build/default/firmware.bin
+          if-no-files-found: error
+
+  # This job is used as the PR required actions check, allows for changes to other steps in the future without breaking
+  # PR requirements.
+  test-status:
+    name: Test Status
+    needs:
+      - build
+      - clang-format
+      - cppcheck
+    if: always()
+    runs-on: ubuntu-latest
+    steps:
+      - name: Fail because needed jobs failed
+        # Fail if any job failed or was cancelled (skipped jobs are ok)
+        if: ${{ contains(needs.*.result, 'failure') || contains(needs.*.result, 'cancelled') }}
+        run: exit 1
+      - name: Success
+        run: exit 0

.github/workflows/pr-formatting-check.yml

@@ -1,6 +1,7 @@
 name: "PR Formatting"
 
 on:
+  pull_request:
   pull_request_target:
     types:
       - opened

.github/workflows/release_candidate.yml

@@ -0,0 +1,48 @@
+name: Compile Release Candidate
+
+on:
+  workflow_dispatch:
+
+jobs:
+  build-release-candidate:
+    if: startsWith(github.ref_name, 'release/')
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          submodules: recursive
+
+      - uses: actions/cache@v5
+        with:
+          path: |
+            ~/.cache/pip
+            ~/.platformio/.cache
+          key: ${{ runner.os }}-pio
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: '3.14'
+
+      - name: Install PlatformIO Core
+        run: pip install --upgrade platformio
+
+      - name: Extract env
+        run: |
+          echo "SHORT_SHA=${GITHUB_SHA::7}" >> $GITHUB_ENV
+          echo "BRANCH_SUFFIX=${GITHUB_REF_NAME#release/}" >> $GITHUB_ENV
+
+      - name: Build CrossPoint Release Candidate
+        env:
+          CROSSPOINT_RC_HASH: ${{ env.SHORT_SHA }}
+        run: pio run -e gh_release_rc
+
+      - name: Upload Artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: CrossPoint-RC-${{ env.BRANCH_SUFFIX }}
+          path: |
+            .pio/build/gh_release_rc/bootloader.bin
+            .pio/build/gh_release_rc/firmware.bin
+            .pio/build/gh_release_rc/firmware.elf
+            .pio/build/gh_release_rc/firmware.map
+            .pio/build/gh_release_rc/partitions.bin

.gitignore

@@ -9,3 +9,8 @@ build
 **/__pycache__/
 /compile_commands.json
 /.cache
+
+# mod
+mod/*
+.cursor/*
+chat-summaries/*

GOVERNANCE.md

@@ -0,0 +1,38 @@
+# Project Governance & Community Principles
+
+CrossPoint Reader is a community-driven, open-source project. Our goal is to provide a high-quality, open-source
+firmware alternative for the Xteink X4 hardware. To keep this project productive and welcoming as we grow, we ask all
+contributors to follow these principles.
+
+### 1. The "Human First" Rule
+Technical discussions can get heated, but they should never be personal.
+- **Assume good intent:** We are all volunteers working on this in our free time. If a comment seems abrasive, assume
+  it’s a language barrier or a misunderstanding before taking offense.
+- **Focus on the code, not the person:** Critique the implementation, the performance, or the UX. Never the intelligence
+  or character of the contributor.
+- **Inflammatory language:** Personal attacks, trolling, or exclusionary language (based on race, gender, background,
+  etc.) are not welcome here and will be moderated.
+
+### 2. A "Do-ocracy" with Guidance
+CrossPoint thrives because people step up to build what they want to see.
+- If you want a feature, the best way to get it is to start an
+  [Idea Discussion](https://github.com/crosspoint-reader/crosspoint-reader/discussions/categories/ideas) or open a PR.
+- If you want to report a bug, check for duplicates and create an
+  [Issue](https://github.com/crosspoint-reader/crosspoint-reader/issues).
+- While we encourage experimentation, the maintainers reserve the right to guide the project’s technical direction to
+  ensure stability on the ESP32-C3’s constrained hardware.
+- For more guidance on the scope of the project, see the [SCOPE.md](SCOPE.md) document.
+
+### 3. Transparent Communication
+To keep the project healthy, we keep our "work" in the open.
+- **Public by Default:** All technical decisions and project management discussions happen in GitHub Issues, Pull
+  Requests, or the public Discussions tab.
+- **Clarity in Writing:** Because we have a global community with different levels of English proficiency, please be as
+  explicit and clear as possible in your PR descriptions and bug reports.
+
+### 4. Moderation & Safety
+The maintainers are responsible for keeping the community a safe place to contribute.
+- We reserve the right to hide comments, lock threads, or block users who repeatedly violate these principles or engage
+  in harassment.
+- **Reporting:** If you feel you are being harassed or see behavior that is damaging the community, please reach out
+  privately to @daveallie.

README.md

@@ -45,6 +45,8 @@ Multi-language support: Read EPUBs in various languages, including English, Span
 
 See [the user guide](./USER_GUIDE.md) for instructions on operating CrossPoint. 
 
+For more details about the scope of the project, see the [SCOPE.md](SCOPE.md) document.
+
 ## Installing
 
 ### Web (latest firmware)
@@ -58,7 +60,7 @@ back to the other partition using the "Swap boot partition" button here https://
 ### Web (specific firmware version)
 
 1. Connect your Xteink X4 to your computer via USB-C
-2. Download the `firmware.bin` file from the release of your choice via the [releases page](https://github.com/daveallie/crosspoint-reader/releases)
+2. Download the `firmware.bin` file from the release of your choice via the [releases page](https://github.com/crosspoint-reader/crosspoint-reader/releases)
 3. Go to https://xteink.dve.al/ and flash the firmware file using the "OTA fast flash controls" section
 
 To revert back to the official firmware, you can flash the latest official firmware from https://xteink.dve.al/, or swap
@@ -82,7 +84,7 @@ See [Development](#development) below.
 CrossPoint uses PlatformIO for building and flashing the firmware. To get started, clone the repository:
 
 ```
-git clone --recursive https://github.com/daveallie/crosspoint-reader
+git clone --recursive https://github.com/crosspoint-reader/crosspoint-reader
 
 # Or, if you've already cloned without --recursive:
 git submodule update --init --recursive
@@ -95,6 +97,25 @@ Connect your Xteink X4 to your computer via USB-C and run the following command.
 ```sh
 pio run --target upload
 ```
+### Debugging
+
+After flashing the new features, it’s recommended to capture detailed logs from the serial port.
+
+First, make sure all required Python packages are installed:
+
+```python
+python3 -m pip install pyserial colorama matplotlib
+```
+after that run the script:
+```sh
+# For Linux
+# This was tested on Debian and should work on most Linux systems.
+python3 scripts/debugging_monitor.py
+
+# For macOS
+python3 scripts/debugging_monitor.py /dev/cu.usbmodem2101
+```
+Minor adjustments may be required for Windows.
 
 ## Internals
 
@@ -133,9 +154,12 @@ For more details on the internal file structures, see the [file formats document
 
 Contributions are very welcome!
 
-If you're looking for a way to help out, take a look at the [ideas discussion board](https://github.com/daveallie/crosspoint-reader/discussions/categories/ideas).
+If you're looking for a way to help out, take a look at the [ideas discussion board](https://github.com/crosspoint-reader/crosspoint-reader/discussions/categories/ideas).
 If there's something there you'd like to work on, leave a comment so that we can avoid duplicated effort.
 
+Everyone here is a volunteer, so please be respectful and patient. For more details on our goverance and community 
+principles, please see [GOVERNANCE.md](GOVERNANCE.md).
+
 ### To submit a contribution:
 
 1. Fork the repo

SCOPE.md

@@ -0,0 +1,48 @@
+# Project Vision & Scope: CrossPoint Reader
+
+The goal of CrossPoint Reader is to create an efficient, open-source reading experience for the Xteink X4. We believe a
+dedicated e-reader should do one thing exceptionally well: **facilitate focused reading.**
+
+## 1. Core Mission
+
+To provide a lightweight, high-performance firmware that maximizes the potential of the X4, prioritizing legibility and
+usability over "swiss-army-knife" functionality.
+
+## 2. Scope
+
+### In-Scope
+
+*These are features that directly improve the primary purpose of the device.*
+
+* **User Experience:** E.g. User-friendly interfaces, and interactions, both inside the reader and navigating the
+  firmware. This includes things like button mapping, book loading, and book navigation like bookmarks.
+* **Document Rendering:** E.g. Support for rendering documents (primarily EPUB) and improvements to the rendering
+  engine.
+* **Format Optimization:** E.g. Efficiently parsing EPUB (CSS/Images) and other documents within the device's
+  capabilities.
+* **Typography & Legibility:** E.g. Custom font support, hyphenation engines, and adjustable line spacing.
+* **E-Ink Driver Refinement:** E.g. Reducing full-screen flashes (ghosting management) and improving general rendering.
+* **Library Management:** E.g. Simple, intuitive ways to organize and navigate a collection of books.
+* **Local Transfer:** E.g. Simple, "pull" based book loading via a basic web-server or public and widely-used standards.
+* **Language Support:** E.g. Support for multiple languages both in the reader and in the interfaces.
+
+### Out-of-Scope
+
+*These items are rejected because they compromise the device's stability or mission.*
+
+* **Interactive Apps:** No Notepads, Calculators, or Games. This is a reader, not a PDA.
+* **Active Connectivity:** No RSS readers, News aggregators, or Web browsers. Background Wi-Fi tasks drain the battery
+  and complicate the single-core CPU's execution.
+* **Media Playback:** No Audio players or Audio-books.
+* **Complex Reader Features:** No highlighting, notes, or dictionary lookup. These features are better suited for
+  devices with better input capabilities and more powerful chips.
+
+## 3. Idea Evaluation
+
+While I appreciate the desire to add new and exciting features to CrossPoint Reader, CrossPoint Reader is designed to be
+a lightweight, reliable, and performant e-reader. Things which distract or compromise the device's core mission will not
+be accepted. As a guiding question, consider if your idea improve the "core reading experience" for the average user,
+and, critically, not distract from that reading experience.
+
+> **Note to Contributors:** If you are unsure if your idea fits the scope, please open a **Discussion** before you start
+> coding!

USER_GUIDE.md

@@ -13,14 +13,17 @@ Welcome to the **CrossPoint** firmware. This guide outlines the hardware control
     - [3.2 Book Selection](#32-book-selection)
     - [3.3 Reading Mode](#33-reading-mode)
     - [3.4 File Upload Screen](#34-file-upload-screen)
+    - [3.4.1 Calibre Wireless Transfers](#341-calibre-wireless-transfers)
     - [3.5 Settings](#35-settings)
     - [3.6 Sleep Screen](#36-sleep-screen)
   - [4. Reading Mode](#4-reading-mode)
     - [Page Turning](#page-turning)
     - [Chapter Navigation](#chapter-navigation)
     - [System Navigation](#system-navigation)
+    - [Supported Languages](#supported-languages)
   - [5. Chapter Selection Screen](#5-chapter-selection-screen)
   - [6. Current Limitations \& Roadmap](#6-current-limitations--roadmap)
+  - [7. Troubleshooting Issues \& Escaping Bootloop](#7-troubleshooting-issues--escaping-bootloop)
 
 
 ## 1. Hardware Overview
@@ -102,6 +105,7 @@ The Settings screen allows you to configure the device's behavior. There are a f
   - "Custom" - Custom images from the SD card; see [Sleep Screen](#36-sleep-screen) below for more information
   - "Cover" - The book cover image (Note: this is experimental and may not work as expected)
   - "None" - A blank screen
+  - "Cover + Custom" - The book cover image, fallbacks to "Custom" behavior
 - **Sleep Screen Cover Mode**: How to display the book cover when "Cover" sleep screen is selected:
   - "Fit" (default) - Scale the image down to fit centered on the screen, padding with white borders as necessary
   - "Crop" - Scale the image down and crop as necessary to try to to fill the screen (Note: this is experimental and may not work as expected)
@@ -112,7 +116,10 @@ The Settings screen allows you to configure the device's behavior. There are a f
 - **Status Bar**: Configure the status bar displayed while reading:
   - "None" - No status bar
   - "No Progress" - Show status bar without reading progress
-  - "Full" - Show status bar with reading progress
+  - "Full w/ Percentage" - Show status bar with book progress (as percentage)
+  - "Full w/ Book Bar" - Show status bar with book progress (as bar)
+  - "Book Bar Only" - Show book progress (as bar)
+  - "Full w/ Chapter Bar" - Show status bar with chapter progress (as bar)
 - **Hide Battery %**: Configure where to suppress the battery pecentage display in the status bar; the battery icon will still be shown:
   - "Never" - Always show battery percentage (default)
   - "In Reader" - Show battery percentage everywhere except in reading mode
@@ -148,6 +155,9 @@ The Settings screen allows you to configure the device's behavior. There are a f
 - **Reader Paragraph Alignment**: Set the alignment of paragraphs; options are "Justified" (default), "Left", "Center", or "Right".
 - **Time to Sleep**: Set the duration of inactivity before the device automatically goes to sleep.
 - **Refresh Frequency**: Set how often the screen does a full refresh while reading to reduce ghosting.
+- **Sunlight Fading Fix**: Configure whether to enable a software-fix for the issue where white X4 models may fade when used in direct sunlight
+  - "OFF" (default) - Disable the fix
+  - "ON" - Enable the fix
 - **OPDS Browser**: Configure OPDS server settings for browsing and downloading books. Set the server URL (for Calibre Content Server, add `/opds` to the end), and optionally configure username and password for servers requiring authentication. Note: Only HTTP Basic authentication is supported. If using Calibre Content Server with authentication enabled, you must set it to use Basic authentication instead of the default Digest authentication.
 - **Check for updates**: Check for firmware updates over WiFi.
 
@@ -201,7 +211,7 @@ CrossPoint renders text using the following Unicode character blocks, enabling s
 *   **Latin Script (Basic, Supplement, Extended-A):** Covers English, German, French, Spanish, Portuguese, Italian, Dutch, Swedish, Norwegian, Danish, Finnish, Polish, Czech, Hungarian, Romanian, Slovak, Slovenian, Turkish, and others.
 *   **Cyrillic Script (Standard and Extended):** Covers Russian, Ukrainian, Belarusian, Bulgarian, Serbian, Macedonian, Kazakh, Kyrgyz, Mongolian, and others.
 
-What is not supported: Chinese, Japanese, Korean, Vietnamese, Hebrew, Arabic and Farsi.
+What is not supported: Chinese, Japanese, Korean, Vietnamese, Hebrew, Arabic, Greek and Farsi.
 
 ---
 
@@ -220,3 +230,15 @@ Accessible by pressing **Confirm** while inside a book.
 Please note that this firmware is currently in active development. The following features are **not yet supported** but are planned for future updates:
 
 * **Images:** Embedded images in e-books will not render.
+
+---
+
+## 7. Troubleshooting Issues & Escaping Bootloop
+
+If an issue or crash is encountered while using Crosspoint, feel free to raise an issue ticket and attach the serial monitor logs. The logs can be obtained by connecting the device to a computer and starting a serial monitor. Either [Serial Monitor](https://www.serialmonitor.org/) or the following command can be used:
+
+```
+pio device monitor
+```
+
+If the device is stuck in a bootloop, press and release the Reset button. Then, press and hold on to the configured Back button and the Power Button to boot to the Home Screen.

docs/webserver.md

@@ -153,7 +153,7 @@ Click **File Manager** to access file management features.
 
 1. Click the **+ Add** button in the top-right corner
 2. Select **New Folder** from the dropdown menu
-3. Enter a folder name (letters, numbers, underscores, and hyphens only)
+3. Enter a folder name (must not contain characters \" * : < > ? / \\ | and must not be . or ..)
 4. Click **Create Folder**
 
 This is useful for organizing your ebooks by genre, author, or series.

lib/EpdFont/EpdFontFamily.cpp

@@ -1,23 +1,19 @@
 #include "EpdFontFamily.h"
 
 const EpdFont* EpdFontFamily::getFont(const Style style) const {
-  if (style == BOLD && bold) {
+  // Extract font style bits (ignore UNDERLINE bit for font selection)
+  const bool hasBold = (style & BOLD) != 0;
+  const bool hasItalic = (style & ITALIC) != 0;
+
+  if (hasBold && hasItalic) {
+    if (boldItalic) return boldItalic;
+    if (bold) return bold;
+    if (italic) return italic;
+  } else if (hasBold && bold) {
     return bold;
-  }
-  if (style == ITALIC && italic) {
+  } else if (hasItalic && italic) {
     return italic;
   }
-  if (style == BOLD_ITALIC) {
-    if (boldItalic) {
-      return boldItalic;
-    }
-    if (bold) {
-      return bold;
-    }
-    if (italic) {
-      return italic;
-    }
-  }
 
   return regular;
 }

lib/EpdFont/EpdFontFamily.h

@@ -3,7 +3,7 @@
 
 class EpdFontFamily {
  public:
-  enum Style : uint8_t { REGULAR = 0, BOLD = 1, ITALIC = 2, BOLD_ITALIC = 3 };
+  enum Style : uint8_t { REGULAR = 0, BOLD = 1, ITALIC = 2, BOLD_ITALIC = 3, UNDERLINE = 4 };
 
   explicit EpdFontFamily(const EpdFont* regular, const EpdFont* bold = nullptr, const EpdFont* italic = nullptr,
                          const EpdFont* boldItalic = nullptr)

lib/Epub/Epub.cpp

@@ -1,9 +1,9 @@
 #include "Epub.h"
 
 #include <FsHelpers.h>
+#include <HalStorage.h>
 #include <HardwareSerial.h>
 #include <JpegToBmpConverter.h>
-#include <SDCardManager.h>
 #include <ZipFile.h>
 
 #include "Epub/parsers/ContainerParser.h"
@@ -86,6 +86,10 @@ bool Epub::parseContentOpf(BookMetadataCache::BookMetadata& bookMetadata) {
     tocNavItem = opfParser.tocNavPath;
   }
 
+  if (!opfParser.cssFiles.empty()) {
+    cssFiles = opfParser.cssFiles;
+  }
+
   Serial.printf("[%lu] [EBP] Successfully parsed content.opf\n", millis());
   return true;
 }
@@ -101,12 +105,12 @@ bool Epub::parseTocNcxFile() const {
 
   const auto tmpNcxPath = getCachePath() + "/toc.ncx";
   FsFile tempNcxFile;
-  if (!SdMan.openFileForWrite("EBP", tmpNcxPath, tempNcxFile)) {
+  if (!Storage.openFileForWrite("EBP", tmpNcxPath, tempNcxFile)) {
     return false;
   }
   readItemContentsToStream(tocNcxItem, tempNcxFile, 1024);
   tempNcxFile.close();
-  if (!SdMan.openFileForRead("EBP", tmpNcxPath, tempNcxFile)) {
+  if (!Storage.openFileForRead("EBP", tmpNcxPath, tempNcxFile)) {
     return false;
   }
   const auto ncxSize = tempNcxFile.size();
@@ -141,7 +145,7 @@ bool Epub::parseTocNcxFile() const {
 
   free(ncxBuffer);
   tempNcxFile.close();
-  SdMan.remove(tmpNcxPath.c_str());
+  Storage.remove(tmpNcxPath.c_str());
 
   Serial.printf("[%lu] [EBP] Parsed TOC items\n", millis());
   return true;
@@ -158,12 +162,12 @@ bool Epub::parseTocNavFile() const {
 
   const auto tmpNavPath = getCachePath() + "/toc.nav";
   FsFile tempNavFile;
-  if (!SdMan.openFileForWrite("EBP", tmpNavPath, tempNavFile)) {
+  if (!Storage.openFileForWrite("EBP", tmpNavPath, tempNavFile)) {
     return false;
   }
   readItemContentsToStream(tocNavItem, tempNavFile, 1024);
   tempNavFile.close();
-  if (!SdMan.openFileForRead("EBP", tmpNavPath, tempNavFile)) {
+  if (!Storage.openFileForRead("EBP", tmpNavPath, tempNavFile)) {
     return false;
   }
   const auto navSize = tempNavFile.size();
@@ -198,21 +202,97 @@ bool Epub::parseTocNavFile() const {
 
   free(navBuffer);
   tempNavFile.close();
-  SdMan.remove(tmpNavPath.c_str());
+  Storage.remove(tmpNavPath.c_str());
 
   Serial.printf("[%lu] [EBP] Parsed TOC nav items\n", millis());
   return true;
 }
 
+std::string Epub::getCssRulesCache() const { return cachePath + "/css_rules.cache"; }
+
+bool Epub::loadCssRulesFromCache() const {
+  FsFile cssCacheFile;
+  if (Storage.openFileForRead("EBP", getCssRulesCache(), cssCacheFile)) {
+    if (cssParser->loadFromCache(cssCacheFile)) {
+      cssCacheFile.close();
+      Serial.printf("[%lu] [EBP] Loaded CSS rules from cache\n", millis());
+      return true;
+    }
+    cssCacheFile.close();
+    Serial.printf("[%lu] [EBP] CSS cache invalid, reparsing\n", millis());
+  }
+  return false;
+}
+
+void Epub::parseCssFiles() const {
+  if (cssFiles.empty()) {
+    Serial.printf("[%lu] [EBP] No CSS files to parse, but CssParser created for inline styles\n", millis());
+  }
+
+  // Try to load from CSS cache first
+  if (!loadCssRulesFromCache()) {
+    // Cache miss - parse CSS files
+    for (const auto& cssPath : cssFiles) {
+      Serial.printf("[%lu] [EBP] Parsing CSS file: %s\n", millis(), cssPath.c_str());
+
+      // Extract CSS file to temp location
+      const auto tmpCssPath = getCachePath() + "/.tmp.css";
+      FsFile tempCssFile;
+      if (!Storage.openFileForWrite("EBP", tmpCssPath, tempCssFile)) {
+        Serial.printf("[%lu] [EBP] Could not create temp CSS file\n", millis());
+        continue;
+      }
+      if (!readItemContentsToStream(cssPath, tempCssFile, 1024)) {
+        Serial.printf("[%lu] [EBP] Could not read CSS file: %s\n", millis(), cssPath.c_str());
+        tempCssFile.close();
+        Storage.remove(tmpCssPath.c_str());
+        continue;
+      }
+      tempCssFile.close();
+
+      // Parse the CSS file
+      if (!Storage.openFileForRead("EBP", tmpCssPath, tempCssFile)) {
+        Serial.printf("[%lu] [EBP] Could not open temp CSS file for reading\n", millis());
+        Storage.remove(tmpCssPath.c_str());
+        continue;
+      }
+      cssParser->loadFromStream(tempCssFile);
+      tempCssFile.close();
+      Storage.remove(tmpCssPath.c_str());
+    }
+
+    // Save to cache for next time
+    FsFile cssCacheFile;
+    if (Storage.openFileForWrite("EBP", getCssRulesCache(), cssCacheFile)) {
+      cssParser->saveToCache(cssCacheFile);
+      cssCacheFile.close();
+    }
+
+    Serial.printf("[%lu] [EBP] Loaded %zu CSS style rules from %zu files\n", millis(), cssParser->ruleCount(),
+                  cssFiles.size());
+  }
+}
+
 // load in the meta data for the epub file
-bool Epub::load(const bool buildIfMissing) {
+bool Epub::load(const bool buildIfMissing, const bool skipLoadingCss) {
   Serial.printf("[%lu] [EBP] Loading ePub: %s\n", millis(), filepath.c_str());
 
   // Initialize spine/TOC cache
   bookMetadataCache.reset(new BookMetadataCache(cachePath));
+  // Always create CssParser - needed for inline style parsing even without CSS files
+  cssParser.reset(new CssParser());
 
   // Try to load existing cache first
   if (bookMetadataCache->load()) {
+    if (!skipLoadingCss && !loadCssRulesFromCache()) {
+      Serial.printf("[%lu] [EBP] Warning: CSS rules cache not found, attempting to parse CSS files\n", millis());
+      // to get CSS file list
+      if (!parseContentOpf(bookMetadataCache->coreMetadata)) {
+        Serial.printf("[%lu] [EBP] Could not parse content.opf from cached bookMetadata for CSS files\n", millis());
+        // continue anyway - book will work without CSS and we'll still load any inline style CSS
+      }
+      parseCssFiles();
+    }
     Serial.printf("[%lu] [EBP] Loaded ePub: %s\n", millis(), filepath.c_str());
     return true;
   }
@@ -309,17 +389,22 @@ bool Epub::load(const bool buildIfMissing) {
     return false;
   }
 
+  if (!skipLoadingCss) {
+    // Parse CSS files after cache reload
+    parseCssFiles();
+  }
+
   Serial.printf("[%lu] [EBP] Loaded ePub: %s\n", millis(), filepath.c_str());
   return true;
 }
 
 bool Epub::clearCache() const {
-  if (!SdMan.exists(cachePath.c_str())) {
+  if (!Storage.exists(cachePath.c_str())) {
     Serial.printf("[%lu] [EPB] Cache does not exist, no action needed\n", millis());
     return true;
   }
 
-  if (!SdMan.removeDir(cachePath.c_str())) {
+  if (!Storage.removeDir(cachePath.c_str())) {
     Serial.printf("[%lu] [EPB] Failed to clear cache\n", millis());
     return false;
   }
@@ -329,11 +414,11 @@ bool Epub::clearCache() const {
 }
 
 void Epub::setupCacheDir() const {
-  if (SdMan.exists(cachePath.c_str())) {
+  if (Storage.exists(cachePath.c_str())) {
     return;
   }
 
-  SdMan.mkdir(cachePath.c_str());
+  Storage.mkdir(cachePath.c_str());
 }
 
 const std::string& Epub::getCachePath() const { return cachePath; }
@@ -374,7 +459,7 @@ std::string Epub::getCoverBmpPath(bool cropped) const {
 
 bool Epub::generateCoverBmp(bool cropped) const {
   // Already generated, return true
-  if (SdMan.exists(getCoverBmpPath(cropped).c_str())) {
+  if (Storage.exists(getCoverBmpPath(cropped).c_str())) {
     return true;
   }
 
@@ -395,29 +480,29 @@ bool Epub::generateCoverBmp(bool cropped) const {
     const auto coverJpgTempPath = getCachePath() + "/.cover.jpg";
 
     FsFile coverJpg;
-    if (!SdMan.openFileForWrite("EBP", coverJpgTempPath, coverJpg)) {
+    if (!Storage.openFileForWrite("EBP", coverJpgTempPath, coverJpg)) {
       return false;
     }
     readItemContentsToStream(coverImageHref, coverJpg, 1024);
     coverJpg.close();
 
-    if (!SdMan.openFileForRead("EBP", coverJpgTempPath, coverJpg)) {
+    if (!Storage.openFileForRead("EBP", coverJpgTempPath, coverJpg)) {
       return false;
     }
 
     FsFile coverBmp;
-    if (!SdMan.openFileForWrite("EBP", getCoverBmpPath(cropped), coverBmp)) {
+    if (!Storage.openFileForWrite("EBP", getCoverBmpPath(cropped), coverBmp)) {
       coverJpg.close();
       return false;
     }
     const bool success = JpegToBmpConverter::jpegFileToBmpStream(coverJpg, coverBmp, cropped);
     coverJpg.close();
     coverBmp.close();
-    SdMan.remove(coverJpgTempPath.c_str());
+    Storage.remove(coverJpgTempPath.c_str());
 
     if (!success) {
       Serial.printf("[%lu] [EBP] Failed to generate BMP from JPG cover image\n", millis());
-      SdMan.remove(getCoverBmpPath(cropped).c_str());
+      Storage.remove(getCoverBmpPath(cropped).c_str());
     }
     Serial.printf("[%lu] [EBP] Generated BMP from JPG cover image, success: %s\n", millis(), success ? "yes" : "no");
     return success;
@@ -428,11 +513,12 @@ bool Epub::generateCoverBmp(bool cropped) const {
   return false;
 }
 
-std::string Epub::getThumbBmpPath() const { return cachePath + "/thumb.bmp"; }
+std::string Epub::getThumbBmpPath() const { return cachePath + "/thumb_[HEIGHT].bmp"; }
+std::string Epub::getThumbBmpPath(int height) const { return cachePath + "/thumb_" + std::to_string(height) + ".bmp"; }
 
-bool Epub::generateThumbBmp() const {
+bool Epub::generateThumbBmp(int height) const {
   // Already generated, return true
-  if (SdMan.exists(getThumbBmpPath().c_str())) {
+  if (Storage.exists(getThumbBmpPath(height).c_str())) {
     return true;
   }
 
@@ -444,43 +530,40 @@ bool Epub::generateThumbBmp() const {
   const auto coverImageHref = bookMetadataCache->coreMetadata.coverItemHref;
   if (coverImageHref.empty()) {
     Serial.printf("[%lu] [EBP] No known cover image for thumbnail\n", millis());
-    return false;
-  }
-
-  if (coverImageHref.substr(coverImageHref.length() - 4) == ".jpg" ||
-      coverImageHref.substr(coverImageHref.length() - 5) == ".jpeg") {
+  } else if (coverImageHref.substr(coverImageHref.length() - 4) == ".jpg" ||
+             coverImageHref.substr(coverImageHref.length() - 5) == ".jpeg") {
     Serial.printf("[%lu] [EBP] Generating thumb BMP from JPG cover image\n", millis());
     const auto coverJpgTempPath = getCachePath() + "/.cover.jpg";
 
     FsFile coverJpg;
-    if (!SdMan.openFileForWrite("EBP", coverJpgTempPath, coverJpg)) {
+    if (!Storage.openFileForWrite("EBP", coverJpgTempPath, coverJpg)) {
       return false;
     }
     readItemContentsToStream(coverImageHref, coverJpg, 1024);
     coverJpg.close();
 
-    if (!SdMan.openFileForRead("EBP", coverJpgTempPath, coverJpg)) {
+    if (!Storage.openFileForRead("EBP", coverJpgTempPath, coverJpg)) {
       return false;
     }
 
     FsFile thumbBmp;
-    if (!SdMan.openFileForWrite("EBP", getThumbBmpPath(), thumbBmp)) {
+    if (!Storage.openFileForWrite("EBP", getThumbBmpPath(height), thumbBmp)) {
       coverJpg.close();
       return false;
     }
     // Use smaller target size for Continue Reading card (half of screen: 240x400)
     // Generate 1-bit BMP for fast home screen rendering (no gray passes needed)
-    constexpr int THUMB_TARGET_WIDTH = 240;
-    constexpr int THUMB_TARGET_HEIGHT = 400;
+    int THUMB_TARGET_WIDTH = height * 0.6;
+    int THUMB_TARGET_HEIGHT = height;
     const bool success = JpegToBmpConverter::jpegFileTo1BitBmpStreamWithSize(coverJpg, thumbBmp, THUMB_TARGET_WIDTH,
                                                                              THUMB_TARGET_HEIGHT);
     coverJpg.close();
     thumbBmp.close();
-    SdMan.remove(coverJpgTempPath.c_str());
+    Storage.remove(coverJpgTempPath.c_str());
 
     if (!success) {
       Serial.printf("[%lu] [EBP] Failed to generate thumb BMP from JPG cover image\n", millis());
-      SdMan.remove(getThumbBmpPath().c_str());
+      Storage.remove(getThumbBmpPath(height).c_str());
     }
     Serial.printf("[%lu] [EBP] Generated thumb BMP from JPG cover image, success: %s\n", millis(),
                   success ? "yes" : "no");
@@ -489,6 +572,10 @@ bool Epub::generateThumbBmp() const {
     Serial.printf("[%lu] [EBP] Cover image is not a JPG, skipping thumbnail\n", millis());
   }
 
+  // Write an empty bmp file to avoid generation attempts in the future
+  FsFile thumbBmp;
+  Storage.openFileForWrite("EBP", getThumbBmpPath(height), thumbBmp);
+  thumbBmp.close();
   return false;
 }
 

lib/Epub/Epub.h

@@ -8,6 +8,7 @@
 #include <vector>
 
 #include "Epub/BookMetadataCache.h"
+#include "Epub/css/CssParser.h"
 
 class ZipFile;
 
@@ -24,11 +25,18 @@ class Epub {
   std::string cachePath;
   // Spine and TOC cache
   std::unique_ptr<BookMetadataCache> bookMetadataCache;
+  // CSS parser for styling
+  std::unique_ptr<CssParser> cssParser;
+  // CSS files
+  std::vector<std::string> cssFiles;
 
   bool findContentOpfFile(std::string* contentOpfFile) const;
   bool parseContentOpf(BookMetadataCache::BookMetadata& bookMetadata);
   bool parseTocNcxFile() const;
   bool parseTocNavFile() const;
+  void parseCssFiles() const;
+  std::string getCssRulesCache() const;
+  bool loadCssRulesFromCache() const;
 
  public:
   explicit Epub(std::string filepath, const std::string& cacheDir) : filepath(std::move(filepath)) {
@@ -37,7 +45,7 @@ class Epub {
   }
   ~Epub() = default;
   std::string& getBasePath() { return contentBasePath; }
-  bool load(bool buildIfMissing = true);
+  bool load(bool buildIfMissing = true, bool skipLoadingCss = false);
   bool clearCache() const;
   void setupCacheDir() const;
   const std::string& getCachePath() const;
@@ -48,7 +56,8 @@ class Epub {
   std::string getCoverBmpPath(bool cropped = false) const;
   bool generateCoverBmp(bool cropped = false) const;
   std::string getThumbBmpPath() const;
-  bool generateThumbBmp() const;
+  std::string getThumbBmpPath(int height) const;
+  bool generateThumbBmp(int height) const;
   uint8_t* readItemContentsToBytes(const std::string& itemHref, size_t* size = nullptr,
                                    bool trailingNullByte = false) const;
   bool readItemContentsToStream(const std::string& itemHref, Print& out, size_t chunkSize) const;
@@ -64,4 +73,5 @@ class Epub {
 
   size_t getBookSize() const;
   float calculateProgress(int currentSpineIndex, float currentSpineRead) const;
+  const CssParser* getCssParser() const { return cssParser.get(); }
 };

lib/Epub/Epub/BookMetadataCache.cpp

@@ -29,7 +29,7 @@ bool BookMetadataCache::beginContentOpfPass() {
   Serial.printf("[%lu] [BMC] Beginning content opf pass\n", millis());
 
   // Open spine file for writing
-  return SdMan.openFileForWrite("BMC", cachePath + tmpSpineBinFile, spineFile);
+  return Storage.openFileForWrite("BMC", cachePath + tmpSpineBinFile, spineFile);
 }
 
 bool BookMetadataCache::endContentOpfPass() {
@@ -40,10 +40,10 @@ bool BookMetadataCache::endContentOpfPass() {
 bool BookMetadataCache::beginTocPass() {
   Serial.printf("[%lu] [BMC] Beginning toc pass\n", millis());
 
-  if (!SdMan.openFileForRead("BMC", cachePath + tmpSpineBinFile, spineFile)) {
+  if (!Storage.openFileForRead("BMC", cachePath + tmpSpineBinFile, spineFile)) {
     return false;
   }
-  if (!SdMan.openFileForWrite("BMC", cachePath + tmpTocBinFile, tocFile)) {
+  if (!Storage.openFileForWrite("BMC", cachePath + tmpTocBinFile, tocFile)) {
     spineFile.close();
     return false;
   }
@@ -98,16 +98,16 @@ bool BookMetadataCache::endWrite() {
 
 bool BookMetadataCache::buildBookBin(const std::string& epubPath, const BookMetadata& metadata) {
   // Open all three files, writing to meta, reading from spine and toc
-  if (!SdMan.openFileForWrite("BMC", cachePath + bookBinFile, bookFile)) {
+  if (!Storage.openFileForWrite("BMC", cachePath + bookBinFile, bookFile)) {
     return false;
   }
 
-  if (!SdMan.openFileForRead("BMC", cachePath + tmpSpineBinFile, spineFile)) {
+  if (!Storage.openFileForRead("BMC", cachePath + tmpSpineBinFile, spineFile)) {
     bookFile.close();
     return false;
   }
 
-  if (!SdMan.openFileForRead("BMC", cachePath + tmpTocBinFile, tocFile)) {
+  if (!Storage.openFileForRead("BMC", cachePath + tmpTocBinFile, tocFile)) {
     bookFile.close();
     spineFile.close();
     return false;
@@ -275,11 +275,11 @@ bool BookMetadataCache::buildBookBin(const std::string& epubPath, const BookMeta
 }
 
 bool BookMetadataCache::cleanupTmpFiles() const {
-  if (SdMan.exists((cachePath + tmpSpineBinFile).c_str())) {
-    SdMan.remove((cachePath + tmpSpineBinFile).c_str());
+  if (Storage.exists((cachePath + tmpSpineBinFile).c_str())) {
+    Storage.remove((cachePath + tmpSpineBinFile).c_str());
   }
-  if (SdMan.exists((cachePath + tmpTocBinFile).c_str())) {
-    SdMan.remove((cachePath + tmpTocBinFile).c_str());
+  if (Storage.exists((cachePath + tmpTocBinFile).c_str())) {
+    Storage.remove((cachePath + tmpTocBinFile).c_str());
   }
   return true;
 }
@@ -364,7 +364,7 @@ void BookMetadataCache::createTocEntry(const std::string& title, const std::stri
 /* ============= READING / LOADING FUNCTIONS ================ */
 
 bool BookMetadataCache::load() {
-  if (!SdMan.openFileForRead("BMC", cachePath + bookBinFile, bookFile)) {
+  if (!Storage.openFileForRead("BMC", cachePath + bookBinFile, bookFile)) {
     return false;
   }
 

lib/Epub/Epub/BookMetadataCache.h

@@ -1,6 +1,6 @@
 #pragma once
 
-#include <SDCardManager.h>
+#include <HalStorage.h>
 
 #include <algorithm>
 #include <string>

lib/Epub/Epub/Page.h

@@ -1,5 +1,5 @@
 #pragma once
-#include <SdFat.h>
+#include <HalStorage.h>
 
 #include <utility>
 #include <vector>

lib/Epub/Epub/ParsedText.cpp

@@ -49,11 +49,17 @@ uint16_t measureWordWidth(const GfxRenderer& renderer, const int fontId, const s
 
 }  // namespace
 
-void ParsedText::addWord(std::string word, const EpdFontFamily::Style fontStyle) {
+void ParsedText::addWord(std::string word, const EpdFontFamily::Style fontStyle, const bool underline,
+                         const bool attachToPrevious) {
   if (word.empty()) return;
 
   words.push_back(std::move(word));
-  wordStyles.push_back(fontStyle);
+  EpdFontFamily::Style combinedStyle = fontStyle;
+  if (underline) {
+    combinedStyle = static_cast<EpdFontFamily::Style>(combinedStyle | EpdFontFamily::UNDERLINE);
+  }
+  wordStyles.push_back(combinedStyle);
+  wordContinues.push_back(attachToPrevious);
 }
 
 // Consumes data to minimize memory usage
@@ -70,17 +76,21 @@ void ParsedText::layoutAndExtractLines(const GfxRenderer& renderer, const int fo
   const int pageWidth = viewportWidth;
   const int spaceWidth = renderer.getSpaceWidth(fontId);
   auto wordWidths = calculateWordWidths(renderer, fontId);
+
+  // Build indexed continues vector from the parallel list for O(1) access during layout
+  std::vector<bool> continuesVec(wordContinues.begin(), wordContinues.end());
+
   std::vector<size_t> lineBreakIndices;
   if (hyphenationEnabled) {
     // Use greedy layout that can split words mid-loop when a hyphenated prefix fits.
-    lineBreakIndices = computeHyphenatedLineBreaks(renderer, fontId, pageWidth, spaceWidth, wordWidths);
+    lineBreakIndices = computeHyphenatedLineBreaks(renderer, fontId, pageWidth, spaceWidth, wordWidths, continuesVec);
   } else {
-    lineBreakIndices = computeLineBreaks(renderer, fontId, pageWidth, spaceWidth, wordWidths);
+    lineBreakIndices = computeLineBreaks(renderer, fontId, pageWidth, spaceWidth, wordWidths, continuesVec);
   }
   const size_t lineCount = includeLastLine ? lineBreakIndices.size() : lineBreakIndices.size() - 1;
 
   for (size_t i = 0; i < lineCount; ++i) {
-    extractLine(i, pageWidth, spaceWidth, wordWidths, lineBreakIndices, processLine);
+    extractLine(i, pageWidth, spaceWidth, wordWidths, continuesVec, lineBreakIndices, processLine);
   }
 }
 
@@ -104,15 +114,26 @@ std::vector<uint16_t> ParsedText::calculateWordWidths(const GfxRenderer& rendere
 }
 
 std::vector<size_t> ParsedText::computeLineBreaks(const GfxRenderer& renderer, const int fontId, const int pageWidth,
-                                                  const int spaceWidth, std::vector<uint16_t>& wordWidths) {
+                                                  const int spaceWidth, std::vector<uint16_t>& wordWidths,
+                                                  std::vector<bool>& continuesVec) {
   if (words.empty()) {
     return {};
   }
 
+  // Calculate first line indent (only for left/justified text without extra paragraph spacing)
+  const int firstLineIndent =
+      blockStyle.textIndent > 0 && !extraParagraphSpacing &&
+              (blockStyle.alignment == CssTextAlign::Justify || blockStyle.alignment == CssTextAlign::Left)
+          ? blockStyle.textIndent
+          : 0;
+
   // Ensure any word that would overflow even as the first entry on a line is split using fallback hyphenation.
   for (size_t i = 0; i < wordWidths.size(); ++i) {
-    while (wordWidths[i] > pageWidth) {
-      if (!hyphenateWordAtIndex(i, pageWidth, renderer, fontId, wordWidths, /*allowFallbackBreaks=*/true)) {
+    // First word needs to fit in reduced width if there's an indent
+    const int effectiveWidth = i == 0 ? pageWidth - firstLineIndent : pageWidth;
+    while (wordWidths[i] > effectiveWidth) {
+      if (!hyphenateWordAtIndex(i, effectiveWidth, renderer, fontId, wordWidths, /*allowFallbackBreaks=*/true,
+                                &continuesVec)) {
         break;
       }
     }
@@ -130,22 +151,31 @@ std::vector<size_t> ParsedText::computeLineBreaks(const GfxRenderer& renderer, c
   ans[totalWordCount - 1] = totalWordCount - 1;
 
   for (int i = totalWordCount - 2; i >= 0; --i) {
-    int currlen = -spaceWidth;
+    int currlen = 0;
     dp[i] = MAX_COST;
 
-    for (size_t j = i; j < totalWordCount; ++j) {
-      // Current line length: previous width + space + current word width
-      currlen += wordWidths[j] + spaceWidth;
+    // First line has reduced width due to text-indent
+    const int effectivePageWidth = i == 0 ? pageWidth - firstLineIndent : pageWidth;
 
-      if (currlen > pageWidth) {
+    for (size_t j = i; j < totalWordCount; ++j) {
+      // Add space before word j, unless it's the first word on the line or a continuation
+      const int gap = j > static_cast<size_t>(i) && !continuesVec[j] ? spaceWidth : 0;
+      currlen += wordWidths[j] + gap;
+
+      if (currlen > effectivePageWidth) {
         break;
       }
 
+      // Cannot break after word j if the next word attaches to it (continuation group)
+      if (j + 1 < totalWordCount && continuesVec[j + 1]) {
+        continue;
+      }
+
       int cost;
       if (j == totalWordCount - 1) {
         cost = 0;  // Last line
       } else {
-        const int remainingSpace = pageWidth - currlen;
+        const int remainingSpace = effectivePageWidth - currlen;
         // Use long long for the square to prevent overflow
         const long long cost_ll = static_cast<long long>(remainingSpace) * remainingSpace + dp[j + 1];
 
@@ -200,7 +230,11 @@ void ParsedText::applyParagraphIndent() {
     return;
   }
 
-  if (style == TextBlock::JUSTIFIED || style == TextBlock::LEFT_ALIGN) {
+  if (blockStyle.textIndentDefined) {
+    // CSS text-indent is explicitly set (even if 0) - don't use fallback EmSpace
+    // The actual indent positioning is handled in extractLine()
+  } else if (blockStyle.alignment == CssTextAlign::Justify || blockStyle.alignment == CssTextAlign::Left) {
+    // No CSS text-indent defined - use EmSpace fallback for visual indent
     words.front().insert(0, "\xe2\x80\x83");
   }
 }
@@ -208,33 +242,45 @@ void ParsedText::applyParagraphIndent() {
 // Builds break indices while opportunistically splitting the word that would overflow the current line.
 std::vector<size_t> ParsedText::computeHyphenatedLineBreaks(const GfxRenderer& renderer, const int fontId,
                                                             const int pageWidth, const int spaceWidth,
-                                                            std::vector<uint16_t>& wordWidths) {
+                                                            std::vector<uint16_t>& wordWidths,
+                                                            std::vector<bool>& continuesVec) {
+  // Calculate first line indent (only for left/justified text without extra paragraph spacing)
+  const int firstLineIndent =
+      blockStyle.textIndent > 0 && !extraParagraphSpacing &&
+              (blockStyle.alignment == CssTextAlign::Justify || blockStyle.alignment == CssTextAlign::Left)
+          ? blockStyle.textIndent
+          : 0;
+
   std::vector<size_t> lineBreakIndices;
   size_t currentIndex = 0;
+  bool isFirstLine = true;
 
   while (currentIndex < wordWidths.size()) {
     const size_t lineStart = currentIndex;
     int lineWidth = 0;
 
+    // First line has reduced width due to text-indent
+    const int effectivePageWidth = isFirstLine ? pageWidth - firstLineIndent : pageWidth;
+
     // Consume as many words as possible for current line, splitting when prefixes fit
     while (currentIndex < wordWidths.size()) {
       const bool isFirstWord = currentIndex == lineStart;
-      const int spacing = isFirstWord ? 0 : spaceWidth;
+      const int spacing = isFirstWord || continuesVec[currentIndex] ? 0 : spaceWidth;
       const int candidateWidth = spacing + wordWidths[currentIndex];
 
       // Word fits on current line
-      if (lineWidth + candidateWidth <= pageWidth) {
+      if (lineWidth + candidateWidth <= effectivePageWidth) {
         lineWidth += candidateWidth;
         ++currentIndex;
         continue;
       }
 
       // Word would overflow — try to split based on hyphenation points
-      const int availableWidth = pageWidth - lineWidth - spacing;
+      const int availableWidth = effectivePageWidth - lineWidth - spacing;
       const bool allowFallbackBreaks = isFirstWord;  // Only for first word on line
 
-      if (availableWidth > 0 &&
-          hyphenateWordAtIndex(currentIndex, availableWidth, renderer, fontId, wordWidths, allowFallbackBreaks)) {
+      if (availableWidth > 0 && hyphenateWordAtIndex(currentIndex, availableWidth, renderer, fontId, wordWidths,
+                                                     allowFallbackBreaks, &continuesVec)) {
         // Prefix now fits; append it to this line and move to next line
         lineWidth += spacing + wordWidths[currentIndex];
         ++currentIndex;
@@ -249,7 +295,14 @@ std::vector<size_t> ParsedText::computeHyphenatedLineBreaks(const GfxRenderer& r
       break;
     }
 
+    // Don't break before a continuation word (e.g., orphaned "?" after "question").
+    // Backtrack to the start of the continuation group so the whole group moves to the next line.
+    while (currentIndex > lineStart + 1 && currentIndex < wordWidths.size() && continuesVec[currentIndex]) {
+      --currentIndex;
+    }
+
     lineBreakIndices.push_back(currentIndex);
+    isFirstLine = false;
   }
 
   return lineBreakIndices;
@@ -259,7 +312,7 @@ std::vector<size_t> ParsedText::computeHyphenatedLineBreaks(const GfxRenderer& r
 // available width.
 bool ParsedText::hyphenateWordAtIndex(const size_t wordIndex, const int availableWidth, const GfxRenderer& renderer,
                                       const int fontId, std::vector<uint16_t>& wordWidths,
-                                      const bool allowFallbackBreaks) {
+                                      const bool allowFallbackBreaks, std::vector<bool>* continuesVec) {
   // Guard against invalid indices or zero available width before attempting to split.
   if (availableWidth <= 0 || wordIndex >= words.size()) {
     return false;
@@ -314,12 +367,28 @@ bool ParsedText::hyphenateWordAtIndex(const size_t wordIndex, const int availabl
     wordIt->push_back('-');
   }
 
-  // Insert the remainder word (with matching style) directly after the prefix.
+  // Insert the remainder word (with matching style and continuation flag) directly after the prefix.
   auto insertWordIt = std::next(wordIt);
   auto insertStyleIt = std::next(styleIt);
   words.insert(insertWordIt, remainder);
   wordStyles.insert(insertStyleIt, style);
 
+  // The remainder inherits whatever continuation status the original word had with the word after it.
+  // Find the continues entry for the original word and insert the remainder's entry after it.
+  auto continuesIt = wordContinues.begin();
+  std::advance(continuesIt, wordIndex);
+  const bool originalContinuedToNext = *continuesIt;
+  // The original word (now prefix) does NOT continue to remainder (hyphen separates them)
+  *continuesIt = false;
+  const auto insertContinuesIt = std::next(continuesIt);
+  wordContinues.insert(insertContinuesIt, originalContinuedToNext);
+
+  // Keep the indexed vector in sync if provided
+  if (continuesVec) {
+    (*continuesVec)[wordIndex] = false;
+    continuesVec->insert(continuesVec->begin() + wordIndex + 1, originalContinuedToNext);
+  }
+
   // Update cached widths to reflect the new prefix/remainder pairing.
   wordWidths[wordIndex] = static_cast<uint16_t>(chosenWidth);
   const uint16_t remainderWidth = measureWordWidth(renderer, fontId, remainder, style);
@@ -328,49 +397,76 @@ bool ParsedText::hyphenateWordAtIndex(const size_t wordIndex, const int availabl
 }
 
 void ParsedText::extractLine(const size_t breakIndex, const int pageWidth, const int spaceWidth,
-                             const std::vector<uint16_t>& wordWidths, const std::vector<size_t>& lineBreakIndices,
+                             const std::vector<uint16_t>& wordWidths, const std::vector<bool>& continuesVec,
+                             const std::vector<size_t>& lineBreakIndices,
                              const std::function<void(std::shared_ptr<TextBlock>)>& processLine) {
   const size_t lineBreak = lineBreakIndices[breakIndex];
   const size_t lastBreakAt = breakIndex > 0 ? lineBreakIndices[breakIndex - 1] : 0;
   const size_t lineWordCount = lineBreak - lastBreakAt;
 
-  // Calculate total word width for this line
+  // Calculate first line indent (only for left/justified text without extra paragraph spacing)
+  const bool isFirstLine = breakIndex == 0;
+  const int firstLineIndent =
+      isFirstLine && blockStyle.textIndent > 0 && !extraParagraphSpacing &&
+              (blockStyle.alignment == CssTextAlign::Justify || blockStyle.alignment == CssTextAlign::Left)
+          ? blockStyle.textIndent
+          : 0;
+
+  // Calculate total word width for this line and count actual word gaps
+  // (continuation words attach to previous word with no gap)
   int lineWordWidthSum = 0;
-  for (size_t i = lastBreakAt; i < lineBreak; i++) {
-    lineWordWidthSum += wordWidths[i];
+  size_t actualGapCount = 0;
+
+  for (size_t wordIdx = 0; wordIdx < lineWordCount; wordIdx++) {
+    lineWordWidthSum += wordWidths[lastBreakAt + wordIdx];
+    // Count gaps: each word after the first creates a gap, unless it's a continuation
+    if (wordIdx > 0 && !continuesVec[lastBreakAt + wordIdx]) {
+      actualGapCount++;
+    }
   }
 
-  // Calculate spacing
-  const int spareSpace = pageWidth - lineWordWidthSum;
+  // Calculate spacing (account for indent reducing effective page width on first line)
+  const int effectivePageWidth = pageWidth - firstLineIndent;
+  const int spareSpace = effectivePageWidth - lineWordWidthSum;
 
   int spacing = spaceWidth;
   const bool isLastLine = breakIndex == lineBreakIndices.size() - 1;
 
-  if (style == TextBlock::JUSTIFIED && !isLastLine && lineWordCount >= 2) {
-    spacing = spareSpace / (lineWordCount - 1);
+  // For justified text, calculate spacing based on actual gap count
+  if (blockStyle.alignment == CssTextAlign::Justify && !isLastLine && actualGapCount >= 1) {
+    spacing = spareSpace / static_cast<int>(actualGapCount);
   }
 
-  // Calculate initial x position
-  uint16_t xpos = 0;
-  if (style == TextBlock::RIGHT_ALIGN) {
-    xpos = spareSpace - (lineWordCount - 1) * spaceWidth;
-  } else if (style == TextBlock::CENTER_ALIGN) {
-    xpos = (spareSpace - (lineWordCount - 1) * spaceWidth) / 2;
+  // Calculate initial x position (first line starts at indent for left/justified text)
+  auto xpos = static_cast<uint16_t>(firstLineIndent);
+  if (blockStyle.alignment == CssTextAlign::Right) {
+    xpos = spareSpace - static_cast<int>(actualGapCount) * spaceWidth;
+  } else if (blockStyle.alignment == CssTextAlign::Center) {
+    xpos = (spareSpace - static_cast<int>(actualGapCount) * spaceWidth) / 2;
   }
 
   // Pre-calculate X positions for words
+  // Continuation words attach to the previous word with no space before them
   std::list<uint16_t> lineXPos;
-  for (size_t i = lastBreakAt; i < lineBreak; i++) {
-    const uint16_t currentWordWidth = wordWidths[i];
+
+  for (size_t wordIdx = 0; wordIdx < lineWordCount; wordIdx++) {
+    const uint16_t currentWordWidth = wordWidths[lastBreakAt + wordIdx];
+
     lineXPos.push_back(xpos);
-    xpos += currentWordWidth + spacing;
+
+    // Add spacing after this word, unless the next word is a continuation
+    const bool nextIsContinuation = wordIdx + 1 < lineWordCount && continuesVec[lastBreakAt + wordIdx + 1];
+
+    xpos += currentWordWidth + (nextIsContinuation ? 0 : spacing);
   }
 
   // Iterators always start at the beginning as we are moving content with splice below
   auto wordEndIt = words.begin();
   auto wordStyleEndIt = wordStyles.begin();
+  auto wordContinuesEndIt = wordContinues.begin();
   std::advance(wordEndIt, lineWordCount);
   std::advance(wordStyleEndIt, lineWordCount);
+  std::advance(wordContinuesEndIt, lineWordCount);
 
   // *** CRITICAL STEP: CONSUME DATA USING SPLICE ***
   std::list<std::string> lineWords;
@@ -378,11 +474,16 @@ void ParsedText::extractLine(const size_t breakIndex, const int pageWidth, const
   std::list<EpdFontFamily::Style> lineWordStyles;
   lineWordStyles.splice(lineWordStyles.begin(), wordStyles, wordStyles.begin(), wordStyleEndIt);
 
+  // Consume continues flags (not passed to TextBlock, but must be consumed to stay in sync)
+  std::list<bool> lineContinues;
+  lineContinues.splice(lineContinues.begin(), wordContinues, wordContinues.begin(), wordContinuesEndIt);
+
   for (auto& word : lineWords) {
     if (containsSoftHyphen(word)) {
       stripSoftHyphensInPlace(word);
     }
   }
 
-  processLine(std::make_shared<TextBlock>(std::move(lineWords), std::move(lineXPos), std::move(lineWordStyles), style));
-}
+  processLine(
+      std::make_shared<TextBlock>(std::move(lineWords), std::move(lineXPos), std::move(lineWordStyles), blockStyle));
+}

lib/Epub/Epub/ParsedText.h

@@ -8,6 +8,7 @@
 #include <string>
 #include <vector>
 
+#include "blocks/BlockStyle.h"
 #include "blocks/TextBlock.h"
 
 class GfxRenderer;
@@ -15,31 +16,34 @@ class GfxRenderer;
 class ParsedText {
   std::list<std::string> words;
   std::list<EpdFontFamily::Style> wordStyles;
-  TextBlock::Style style;
+  std::list<bool> wordContinues;  // true = word attaches to previous (no space before it)
+  BlockStyle blockStyle;
   bool extraParagraphSpacing;
   bool hyphenationEnabled;
 
   void applyParagraphIndent();
   std::vector<size_t> computeLineBreaks(const GfxRenderer& renderer, int fontId, int pageWidth, int spaceWidth,
-                                        std::vector<uint16_t>& wordWidths);
+                                        std::vector<uint16_t>& wordWidths, std::vector<bool>& continuesVec);
   std::vector<size_t> computeHyphenatedLineBreaks(const GfxRenderer& renderer, int fontId, int pageWidth,
-                                                  int spaceWidth, std::vector<uint16_t>& wordWidths);
+                                                  int spaceWidth, std::vector<uint16_t>& wordWidths,
+                                                  std::vector<bool>& continuesVec);
   bool hyphenateWordAtIndex(size_t wordIndex, int availableWidth, const GfxRenderer& renderer, int fontId,
-                            std::vector<uint16_t>& wordWidths, bool allowFallbackBreaks);
+                            std::vector<uint16_t>& wordWidths, bool allowFallbackBreaks,
+                            std::vector<bool>* continuesVec = nullptr);
   void extractLine(size_t breakIndex, int pageWidth, int spaceWidth, const std::vector<uint16_t>& wordWidths,
-                   const std::vector<size_t>& lineBreakIndices,
+                   const std::vector<bool>& continuesVec, const std::vector<size_t>& lineBreakIndices,
                    const std::function<void(std::shared_ptr<TextBlock>)>& processLine);
   std::vector<uint16_t> calculateWordWidths(const GfxRenderer& renderer, int fontId);
 
  public:
-  explicit ParsedText(const TextBlock::Style style, const bool extraParagraphSpacing,
-                      const bool hyphenationEnabled = false)
-      : style(style), extraParagraphSpacing(extraParagraphSpacing), hyphenationEnabled(hyphenationEnabled) {}
+  explicit ParsedText(const bool extraParagraphSpacing, const bool hyphenationEnabled = false,
+                      const BlockStyle& blockStyle = BlockStyle())
+      : blockStyle(blockStyle), extraParagraphSpacing(extraParagraphSpacing), hyphenationEnabled(hyphenationEnabled) {}
   ~ParsedText() = default;
 
-  void addWord(std::string word, EpdFontFamily::Style fontStyle);
-  void setStyle(const TextBlock::Style style) { this->style = style; }
-  TextBlock::Style getStyle() const { return style; }
+  void addWord(std::string word, EpdFontFamily::Style fontStyle, bool underline = false, bool attachToPrevious = false);
+  void setBlockStyle(const BlockStyle& blockStyle) { this->blockStyle = blockStyle; }
+  BlockStyle& getBlockStyle() { return blockStyle; }
   size_t size() const { return words.size(); }
   bool isEmpty() const { return words.empty(); }
   void layoutAndExtractLines(const GfxRenderer& renderer, int fontId, uint16_t viewportWidth,

lib/Epub/Epub/Section.cpp

@@ -1,6 +1,6 @@
 #include "Section.h"
 
-#include <SDCardManager.h>
+#include <HalStorage.h>
 #include <Serialization.h>
 
 #include "Page.h"
@@ -8,9 +8,9 @@
 #include "parsers/ChapterHtmlSlimParser.h"
 
 namespace {
-constexpr uint8_t SECTION_FILE_VERSION = 10;
+constexpr uint8_t SECTION_FILE_VERSION = 12;
 constexpr uint32_t HEADER_SIZE = sizeof(uint8_t) + sizeof(int) + sizeof(float) + sizeof(bool) + sizeof(uint8_t) +
-                                 sizeof(uint16_t) + sizeof(uint16_t) + sizeof(uint16_t) + sizeof(bool) +
+                                 sizeof(uint16_t) + sizeof(uint16_t) + sizeof(uint16_t) + sizeof(bool) + sizeof(bool) +
                                  sizeof(uint32_t);
 }  // namespace
 
@@ -33,7 +33,8 @@ uint32_t Section::onPageComplete(std::unique_ptr<Page> page) {
 
 void Section::writeSectionFileHeader(const int fontId, const float lineCompression, const bool extraParagraphSpacing,
                                      const uint8_t paragraphAlignment, const uint16_t viewportWidth,
-                                     const uint16_t viewportHeight, const bool hyphenationEnabled) {
+                                     const uint16_t viewportHeight, const bool hyphenationEnabled,
+                                     const bool embeddedStyle) {
   if (!file) {
     Serial.printf("[%lu] [SCT] File not open for writing header\n", millis());
     return;
@@ -41,7 +42,7 @@ void Section::writeSectionFileHeader(const int fontId, const float lineCompressi
   static_assert(HEADER_SIZE == sizeof(SECTION_FILE_VERSION) + sizeof(fontId) + sizeof(lineCompression) +
                                    sizeof(extraParagraphSpacing) + sizeof(paragraphAlignment) + sizeof(viewportWidth) +
                                    sizeof(viewportHeight) + sizeof(pageCount) + sizeof(hyphenationEnabled) +
-                                   sizeof(uint32_t),
+                                   sizeof(embeddedStyle) + sizeof(uint32_t),
                 "Header size mismatch");
   serialization::writePod(file, SECTION_FILE_VERSION);
   serialization::writePod(file, fontId);
@@ -51,14 +52,15 @@ void Section::writeSectionFileHeader(const int fontId, const float lineCompressi
   serialization::writePod(file, viewportWidth);
   serialization::writePod(file, viewportHeight);
   serialization::writePod(file, hyphenationEnabled);
+  serialization::writePod(file, embeddedStyle);
   serialization::writePod(file, pageCount);  // Placeholder for page count (will be initially 0 when written)
   serialization::writePod(file, static_cast<uint32_t>(0));  // Placeholder for LUT offset
 }
 
 bool Section::loadSectionFile(const int fontId, const float lineCompression, const bool extraParagraphSpacing,
                               const uint8_t paragraphAlignment, const uint16_t viewportWidth,
-                              const uint16_t viewportHeight, const bool hyphenationEnabled) {
-  if (!SdMan.openFileForRead("SCT", filePath, file)) {
+                              const uint16_t viewportHeight, const bool hyphenationEnabled, const bool embeddedStyle) {
+  if (!Storage.openFileForRead("SCT", filePath, file)) {
     return false;
   }
 
@@ -79,6 +81,7 @@ bool Section::loadSectionFile(const int fontId, const float lineCompression, con
     bool fileExtraParagraphSpacing;
     uint8_t fileParagraphAlignment;
     bool fileHyphenationEnabled;
+    bool fileEmbeddedStyle;
     serialization::readPod(file, fileFontId);
     serialization::readPod(file, fileLineCompression);
     serialization::readPod(file, fileExtraParagraphSpacing);
@@ -86,11 +89,12 @@ bool Section::loadSectionFile(const int fontId, const float lineCompression, con
     serialization::readPod(file, fileViewportWidth);
     serialization::readPod(file, fileViewportHeight);
     serialization::readPod(file, fileHyphenationEnabled);
+    serialization::readPod(file, fileEmbeddedStyle);
 
     if (fontId != fileFontId || lineCompression != fileLineCompression ||
         extraParagraphSpacing != fileExtraParagraphSpacing || paragraphAlignment != fileParagraphAlignment ||
         viewportWidth != fileViewportWidth || viewportHeight != fileViewportHeight ||
-        hyphenationEnabled != fileHyphenationEnabled) {
+        hyphenationEnabled != fileHyphenationEnabled || embeddedStyle != fileEmbeddedStyle) {
       file.close();
       Serial.printf("[%lu] [SCT] Deserialization failed: Parameters do not match\n", millis());
       clearCache();
@@ -106,12 +110,12 @@ bool Section::loadSectionFile(const int fontId, const float lineCompression, con
 
 // Your updated class method (assuming you are using the 'SD' object, which is a wrapper for a specific filesystem)
 bool Section::clearCache() const {
-  if (!SdMan.exists(filePath.c_str())) {
+  if (!Storage.exists(filePath.c_str())) {
     Serial.printf("[%lu] [SCT] Cache does not exist, no action needed\n", millis());
     return true;
   }
 
-  if (!SdMan.remove(filePath.c_str())) {
+  if (!Storage.remove(filePath.c_str())) {
     Serial.printf("[%lu] [SCT] Failed to clear cache\n", millis());
     return false;
   }
@@ -122,17 +126,15 @@ bool Section::clearCache() const {
 
 bool Section::createSectionFile(const int fontId, const float lineCompression, const bool extraParagraphSpacing,
                                 const uint8_t paragraphAlignment, const uint16_t viewportWidth,
-                                const uint16_t viewportHeight, const bool hyphenationEnabled,
-                                const std::function<void()>& progressSetupFn,
-                                const std::function<void(int)>& progressFn) {
-  constexpr uint32_t MIN_SIZE_FOR_PROGRESS = 50 * 1024;  // 50KB
+                                const uint16_t viewportHeight, const bool hyphenationEnabled, const bool embeddedStyle,
+                                const std::function<void()>& popupFn) {
   const auto localPath = epub->getSpineItem(spineIndex).href;
   const auto tmpHtmlPath = epub->getCachePath() + "/.tmp_" + std::to_string(spineIndex) + ".html";
 
   // Create cache directory if it doesn't exist
   {
     const auto sectionsDir = epub->getCachePath() + "/sections";
-    SdMan.mkdir(sectionsDir.c_str());
+    Storage.mkdir(sectionsDir.c_str());
   }
 
   // Retry logic for SD card timing issues
@@ -145,12 +147,12 @@ bool Section::createSectionFile(const int fontId, const float lineCompression, c
     }
 
     // Remove any incomplete file from previous attempt before retrying
-    if (SdMan.exists(tmpHtmlPath.c_str())) {
-      SdMan.remove(tmpHtmlPath.c_str());
+    if (Storage.exists(tmpHtmlPath.c_str())) {
+      Storage.remove(tmpHtmlPath.c_str());
     }
 
     FsFile tmpHtml;
-    if (!SdMan.openFileForWrite("SCT", tmpHtmlPath, tmpHtml)) {
+    if (!Storage.openFileForWrite("SCT", tmpHtmlPath, tmpHtml)) {
       continue;
     }
     success = epub->readItemContentsToStream(localPath, tmpHtml, 1024);
@@ -158,8 +160,8 @@ bool Section::createSectionFile(const int fontId, const float lineCompression, c
     tmpHtml.close();
 
     // If streaming failed, remove the incomplete file immediately
-    if (!success && SdMan.exists(tmpHtmlPath.c_str())) {
-      SdMan.remove(tmpHtmlPath.c_str());
+    if (!success && Storage.exists(tmpHtmlPath.c_str())) {
+      Storage.remove(tmpHtmlPath.c_str());
       Serial.printf("[%lu] [SCT] Removed incomplete temp file after failed attempt\n", millis());
     }
   }
@@ -171,31 +173,26 @@ bool Section::createSectionFile(const int fontId, const float lineCompression, c
 
   Serial.printf("[%lu] [SCT] Streamed temp HTML to %s (%d bytes)\n", millis(), tmpHtmlPath.c_str(), fileSize);
 
-  // Only show progress bar for larger chapters where rendering overhead is worth it
-  if (progressSetupFn && fileSize >= MIN_SIZE_FOR_PROGRESS) {
-    progressSetupFn();
-  }
-
-  if (!SdMan.openFileForWrite("SCT", filePath, file)) {
+  if (!Storage.openFileForWrite("SCT", filePath, file)) {
     return false;
   }
   writeSectionFileHeader(fontId, lineCompression, extraParagraphSpacing, paragraphAlignment, viewportWidth,
-                         viewportHeight, hyphenationEnabled);
+                         viewportHeight, hyphenationEnabled, embeddedStyle);
   std::vector<uint32_t> lut = {};
 
   ChapterHtmlSlimParser visitor(
       tmpHtmlPath, renderer, fontId, lineCompression, extraParagraphSpacing, paragraphAlignment, viewportWidth,
       viewportHeight, hyphenationEnabled,
       [this, &lut](std::unique_ptr<Page> page) { lut.emplace_back(this->onPageComplete(std::move(page))); },
-      progressFn);
+      embeddedStyle, popupFn, embeddedStyle ? epub->getCssParser() : nullptr);
   Hyphenator::setPreferredLanguage(epub->getLanguage());
   success = visitor.parseAndBuildPages();
 
-  SdMan.remove(tmpHtmlPath.c_str());
+  Storage.remove(tmpHtmlPath.c_str());
   if (!success) {
     Serial.printf("[%lu] [SCT] Failed to parse XML and build pages\n", millis());
     file.close();
-    SdMan.remove(filePath.c_str());
+    Storage.remove(filePath.c_str());
     return false;
   }
 
@@ -213,7 +210,7 @@ bool Section::createSectionFile(const int fontId, const float lineCompression, c
   if (hasFailedLutRecords) {
     Serial.printf("[%lu] [SCT] Failed to write LUT due to invalid page positions\n", millis());
     file.close();
-    SdMan.remove(filePath.c_str());
+    Storage.remove(filePath.c_str());
     return false;
   }
 
@@ -226,7 +223,7 @@ bool Section::createSectionFile(const int fontId, const float lineCompression, c
 }
 
 std::unique_ptr<Page> Section::loadPageFromSectionFile() {
-  if (!SdMan.openFileForRead("SCT", filePath, file)) {
+  if (!Storage.openFileForRead("SCT", filePath, file)) {
     return nullptr;
   }
 

lib/Epub/Epub/Section.h

@@ -15,7 +15,8 @@ class Section {
   FsFile file;
 
   void writeSectionFileHeader(int fontId, float lineCompression, bool extraParagraphSpacing, uint8_t paragraphAlignment,
-                              uint16_t viewportWidth, uint16_t viewportHeight, bool hyphenationEnabled);
+                              uint16_t viewportWidth, uint16_t viewportHeight, bool hyphenationEnabled,
+                              bool embeddedStyle);
   uint32_t onPageComplete(std::unique_ptr<Page> page);
 
  public:
@@ -29,11 +30,10 @@ class Section {
         filePath(epub->getCachePath() + "/sections/" + std::to_string(spineIndex) + ".bin") {}
   ~Section() = default;
   bool loadSectionFile(int fontId, float lineCompression, bool extraParagraphSpacing, uint8_t paragraphAlignment,
-                       uint16_t viewportWidth, uint16_t viewportHeight, bool hyphenationEnabled);
+                       uint16_t viewportWidth, uint16_t viewportHeight, bool hyphenationEnabled, bool embeddedStyle);
   bool clearCache() const;
   bool createSectionFile(int fontId, float lineCompression, bool extraParagraphSpacing, uint8_t paragraphAlignment,
-                         uint16_t viewportWidth, uint16_t viewportHeight, bool hyphenationEnabled,
-                         const std::function<void()>& progressSetupFn = nullptr,
-                         const std::function<void(int)>& progressFn = nullptr);
+                         uint16_t viewportWidth, uint16_t viewportHeight, bool hyphenationEnabled, bool embeddedStyle,
+                         const std::function<void()>& popupFn = nullptr);
   std::unique_ptr<Page> loadPageFromSectionFile();
 };

lib/Epub/Epub/blocks/BlockStyle.h

@@ -0,0 +1,97 @@
+#pragma once
+
+#include <cstdint>
+
+#include "Epub/css/CssStyle.h"
+
+/**
+ * BlockStyle - Block-level styling properties
+ */
+struct BlockStyle {
+  CssTextAlign alignment = CssTextAlign::Justify;
+
+  // Spacing (in pixels)
+  int16_t marginTop = 0;
+  int16_t marginBottom = 0;
+  int16_t marginLeft = 0;
+  int16_t marginRight = 0;
+  int16_t paddingTop = 0;     // treated same as margin for rendering
+  int16_t paddingBottom = 0;  // treated same as margin for rendering
+  int16_t paddingLeft = 0;    // treated same as margin for rendering
+  int16_t paddingRight = 0;   // treated same as margin for rendering
+  int16_t textIndent = 0;
+  bool textIndentDefined = false;  // true if text-indent was explicitly set in CSS
+  bool textAlignDefined = false;   // true if text-align was explicitly set in CSS
+
+  // Combined horizontal insets (margin + padding)
+  [[nodiscard]] int16_t leftInset() const { return marginLeft + paddingLeft; }
+  [[nodiscard]] int16_t rightInset() const { return marginRight + paddingRight; }
+  [[nodiscard]] int16_t totalHorizontalInset() const { return leftInset() + rightInset(); }
+
+  // Combine with another block style. Useful for parent -> child styles, where the child style should be
+  // applied on top of the parent's style to get the combined style.
+  BlockStyle getCombinedBlockStyle(const BlockStyle& child) const {
+    BlockStyle combinedBlockStyle;
+
+    combinedBlockStyle.marginTop = static_cast<int16_t>(child.marginTop + marginTop);
+    combinedBlockStyle.marginBottom = static_cast<int16_t>(child.marginBottom + marginBottom);
+    combinedBlockStyle.marginLeft = static_cast<int16_t>(child.marginLeft + marginLeft);
+    combinedBlockStyle.marginRight = static_cast<int16_t>(child.marginRight + marginRight);
+
+    combinedBlockStyle.paddingTop = static_cast<int16_t>(child.paddingTop + paddingTop);
+    combinedBlockStyle.paddingBottom = static_cast<int16_t>(child.paddingBottom + paddingBottom);
+    combinedBlockStyle.paddingLeft = static_cast<int16_t>(child.paddingLeft + paddingLeft);
+    combinedBlockStyle.paddingRight = static_cast<int16_t>(child.paddingRight + paddingRight);
+    // Text indent: use child's if defined
+    if (child.textIndentDefined) {
+      combinedBlockStyle.textIndent = child.textIndent;
+      combinedBlockStyle.textIndentDefined = true;
+    } else {
+      combinedBlockStyle.textIndent = textIndent;
+      combinedBlockStyle.textIndentDefined = textIndentDefined;
+    }
+    // Text align: use child's if defined
+    if (child.textAlignDefined) {
+      combinedBlockStyle.alignment = child.alignment;
+      combinedBlockStyle.textAlignDefined = true;
+    } else {
+      combinedBlockStyle.alignment = alignment;
+      combinedBlockStyle.textAlignDefined = textAlignDefined;
+    }
+    return combinedBlockStyle;
+  }
+
+  // Create a BlockStyle from CSS style properties, resolving CssLength values to pixels
+  // emSize is the current font line height, used for em/rem unit conversion
+  // paragraphAlignment is the user's paragraphAlignment setting preference
+  static BlockStyle fromCssStyle(const CssStyle& cssStyle, const float emSize, const CssTextAlign paragraphAlignment,
+                                 const uint16_t viewportWidth = 0) {
+    BlockStyle blockStyle;
+    const float vw = viewportWidth;
+    // Resolve all CssLength values to pixels using the current font's em size and viewport width
+    blockStyle.marginTop = cssStyle.marginTop.toPixelsInt16(emSize, vw);
+    blockStyle.marginBottom = cssStyle.marginBottom.toPixelsInt16(emSize, vw);
+    blockStyle.marginLeft = cssStyle.marginLeft.toPixelsInt16(emSize, vw);
+    blockStyle.marginRight = cssStyle.marginRight.toPixelsInt16(emSize, vw);
+
+    blockStyle.paddingTop = cssStyle.paddingTop.toPixelsInt16(emSize, vw);
+    blockStyle.paddingBottom = cssStyle.paddingBottom.toPixelsInt16(emSize, vw);
+    blockStyle.paddingLeft = cssStyle.paddingLeft.toPixelsInt16(emSize, vw);
+    blockStyle.paddingRight = cssStyle.paddingRight.toPixelsInt16(emSize, vw);
+
+    // For textIndent: if it's a percentage we can't resolve (no viewport width),
+    // leave textIndentDefined=false so the EmSpace fallback in applyParagraphIndent() is used
+    if (cssStyle.hasTextIndent() && cssStyle.textIndent.isResolvable(vw)) {
+      blockStyle.textIndent = cssStyle.textIndent.toPixelsInt16(emSize, vw);
+      blockStyle.textIndentDefined = true;
+    }
+    blockStyle.textAlignDefined = cssStyle.hasTextAlign();
+    // User setting overrides CSS, unless "Book's Style" alignment setting is selected
+    if (paragraphAlignment == CssTextAlign::None) {
+      blockStyle.alignment = blockStyle.textAlignDefined ? cssStyle.textAlign : CssTextAlign::Justify;
+    } else {
+      blockStyle.alignment = paragraphAlignment;
+    }
+    return blockStyle;
+  }
+};

lib/Epub/Epub/blocks/TextBlock.cpp

@@ -14,9 +14,32 @@ void TextBlock::render(const GfxRenderer& renderer, const int fontId, const int
   auto wordIt = words.begin();
   auto wordStylesIt = wordStyles.begin();
   auto wordXposIt = wordXpos.begin();
-
   for (size_t i = 0; i < words.size(); i++) {
-    renderer.drawText(fontId, *wordXposIt + x, y, wordIt->c_str(), true, *wordStylesIt);
+    const int wordX = *wordXposIt + x;
+    const EpdFontFamily::Style currentStyle = *wordStylesIt;
+    renderer.drawText(fontId, wordX, y, wordIt->c_str(), true, currentStyle);
+
+    if ((currentStyle & EpdFontFamily::UNDERLINE) != 0) {
+      const std::string& w = *wordIt;
+      const int fullWordWidth = renderer.getTextWidth(fontId, w.c_str(), currentStyle);
+      // y is the top of the text line; add ascender to reach baseline, then offset 2px below
+      const int underlineY = y + renderer.getFontAscenderSize(fontId) + 2;
+
+      int startX = wordX;
+      int underlineWidth = fullWordWidth;
+
+      // if word starts with em-space ("\xe2\x80\x83"), account for the additional indent before drawing the line
+      if (w.size() >= 3 && static_cast<uint8_t>(w[0]) == 0xE2 && static_cast<uint8_t>(w[1]) == 0x80 &&
+          static_cast<uint8_t>(w[2]) == 0x83) {
+        const char* visiblePtr = w.c_str() + 3;
+        const int prefixWidth = renderer.getTextAdvanceX(fontId, std::string("\xe2\x80\x83").c_str());
+        const int visibleWidth = renderer.getTextWidth(fontId, visiblePtr, currentStyle);
+        startX = wordX + prefixWidth;
+        underlineWidth = visibleWidth;
+      }
+
+      renderer.drawLine(startX, underlineY, startX + underlineWidth, underlineY, true);
+    }
 
     std::advance(wordIt, 1);
     std::advance(wordStylesIt, 1);
@@ -37,8 +60,19 @@ bool TextBlock::serialize(FsFile& file) const {
   for (auto x : wordXpos) serialization::writePod(file, x);
   for (auto s : wordStyles) serialization::writePod(file, s);
 
-  // Block style
-  serialization::writePod(file, style);
+  // Style (alignment + margins/padding/indent)
+  serialization::writePod(file, blockStyle.alignment);
+  serialization::writePod(file, blockStyle.textAlignDefined);
+  serialization::writePod(file, blockStyle.marginTop);
+  serialization::writePod(file, blockStyle.marginBottom);
+  serialization::writePod(file, blockStyle.marginLeft);
+  serialization::writePod(file, blockStyle.marginRight);
+  serialization::writePod(file, blockStyle.paddingTop);
+  serialization::writePod(file, blockStyle.paddingBottom);
+  serialization::writePod(file, blockStyle.paddingLeft);
+  serialization::writePod(file, blockStyle.paddingRight);
+  serialization::writePod(file, blockStyle.textIndent);
+  serialization::writePod(file, blockStyle.textIndentDefined);
 
   return true;
 }
@@ -48,7 +82,7 @@ std::unique_ptr<TextBlock> TextBlock::deserialize(FsFile& file) {
   std::list<std::string> words;
   std::list<uint16_t> wordXpos;
   std::list<EpdFontFamily::Style> wordStyles;
-  Style style;
+  BlockStyle blockStyle;
 
   // Word count
   serialization::readPod(file, wc);
@@ -67,8 +101,20 @@ std::unique_ptr<TextBlock> TextBlock::deserialize(FsFile& file) {
   for (auto& x : wordXpos) serialization::readPod(file, x);
   for (auto& s : wordStyles) serialization::readPod(file, s);
 
-  // Block style
-  serialization::readPod(file, style);
+  // Style (alignment + margins/padding/indent)
+  serialization::readPod(file, blockStyle.alignment);
+  serialization::readPod(file, blockStyle.textAlignDefined);
+  serialization::readPod(file, blockStyle.marginTop);
+  serialization::readPod(file, blockStyle.marginBottom);
+  serialization::readPod(file, blockStyle.marginLeft);
+  serialization::readPod(file, blockStyle.marginRight);
+  serialization::readPod(file, blockStyle.paddingTop);
+  serialization::readPod(file, blockStyle.paddingBottom);
+  serialization::readPod(file, blockStyle.paddingLeft);
+  serialization::readPod(file, blockStyle.paddingRight);
+  serialization::readPod(file, blockStyle.textIndent);
+  serialization::readPod(file, blockStyle.textIndentDefined);
 
-  return std::unique_ptr<TextBlock>(new TextBlock(std::move(words), std::move(wordXpos), std::move(wordStyles), style));
+  return std::unique_ptr<TextBlock>(
+      new TextBlock(std::move(words), std::move(wordXpos), std::move(wordStyles), blockStyle));
 }

lib/Epub/Epub/blocks/TextBlock.h

@@ -1,36 +1,32 @@
 #pragma once
 #include <EpdFontFamily.h>
-#include <SdFat.h>
+#include <HalStorage.h>
 
 #include <list>
 #include <memory>
 #include <string>
 
 #include "Block.h"
+#include "BlockStyle.h"
 
 // Represents a line of text on a page
 class TextBlock final : public Block {
- public:
-  enum Style : uint8_t {
-    JUSTIFIED = 0,
-    LEFT_ALIGN = 1,
-    CENTER_ALIGN = 2,
-    RIGHT_ALIGN = 3,
-  };
-
  private:
   std::list<std::string> words;
   std::list<uint16_t> wordXpos;
   std::list<EpdFontFamily::Style> wordStyles;
-  Style style;
+  BlockStyle blockStyle;
 
  public:
   explicit TextBlock(std::list<std::string> words, std::list<uint16_t> word_xpos,
-                     std::list<EpdFontFamily::Style> word_styles, const Style style)
-      : words(std::move(words)), wordXpos(std::move(word_xpos)), wordStyles(std::move(word_styles)), style(style) {}
+                     std::list<EpdFontFamily::Style> word_styles, const BlockStyle& blockStyle = BlockStyle())
+      : words(std::move(words)),
+        wordXpos(std::move(word_xpos)),
+        wordStyles(std::move(word_styles)),
+        blockStyle(blockStyle) {}
   ~TextBlock() override = default;
-  void setStyle(const Style style) { this->style = style; }
-  Style getStyle() const { return style; }
+  void setBlockStyle(const BlockStyle& blockStyle) { this->blockStyle = blockStyle; }
+  const BlockStyle& getBlockStyle() const { return blockStyle; }
   bool isEmpty() override { return words.empty(); }
   void layout(GfxRenderer& renderer) override {};
   // given a renderer works out where to break the words into lines

lib/Epub/Epub/css/CssParser.cpp

@@ -0,0 +1,699 @@
+#include "CssParser.h"
+
+#include <HardwareSerial.h>
+
+#include <algorithm>
+#include <cctype>
+
+namespace {
+
+// Buffer size for reading CSS files
+constexpr size_t READ_BUFFER_SIZE = 512;
+
+// Maximum CSS file size we'll process (prevent memory issues)
+constexpr size_t MAX_CSS_SIZE = 64 * 1024;
+
+// Check if character is CSS whitespace
+bool isCssWhitespace(const char c) { return c == ' ' || c == '\t' || c == '\n' || c == '\r' || c == '\f'; }
+
+// Read entire file into string (with size limit)
+std::string readFileContent(FsFile& file) {
+  std::string content;
+  content.reserve(std::min(static_cast<size_t>(file.size()), MAX_CSS_SIZE));
+
+  char buffer[READ_BUFFER_SIZE];
+  while (file.available() && content.size() < MAX_CSS_SIZE) {
+    const int bytesRead = file.read(buffer, sizeof(buffer));
+    if (bytesRead <= 0) break;
+    content.append(buffer, bytesRead);
+  }
+  return content;
+}
+
+// Remove CSS comments (/* ... */) from content
+std::string stripComments(const std::string& css) {
+  std::string result;
+  result.reserve(css.size());
+
+  size_t pos = 0;
+  while (pos < css.size()) {
+    // Look for start of comment
+    if (pos + 1 < css.size() && css[pos] == '/' && css[pos + 1] == '*') {
+      // Find end of comment
+      const size_t endPos = css.find("*/", pos + 2);
+      if (endPos == std::string::npos) {
+        // Unterminated comment - skip rest of file
+        break;
+      }
+      pos = endPos + 2;
+    } else {
+      result.push_back(css[pos]);
+      ++pos;
+    }
+  }
+  return result;
+}
+
+// Skip @-rules (like @media, @import, @font-face)
+// Returns position after the @-rule
+size_t skipAtRule(const std::string& css, const size_t start) {
+  // Find the end - either semicolon (simple @-rule) or matching brace
+  size_t pos = start + 1;  // Skip the '@'
+
+  // Skip identifier
+  while (pos < css.size() && (std::isalnum(css[pos]) || css[pos] == '-')) {
+    ++pos;
+  }
+
+  // Look for { or ;
+  int braceDepth = 0;
+  while (pos < css.size()) {
+    const char c = css[pos];
+    if (c == '{') {
+      ++braceDepth;
+    } else if (c == '}') {
+      --braceDepth;
+      if (braceDepth == 0) {
+        return pos + 1;
+      }
+    } else if (c == ';' && braceDepth == 0) {
+      return pos + 1;
+    }
+    ++pos;
+  }
+  return css.size();
+}
+
+// Extract next rule from CSS content
+// Returns true if a rule was found, with selector and body filled
+bool extractNextRule(const std::string& css, size_t& pos, std::string& selector, std::string& body) {
+  selector.clear();
+  body.clear();
+
+  // Skip whitespace and @-rules until we find a regular rule
+  while (pos < css.size()) {
+    // Skip whitespace
+    while (pos < css.size() && isCssWhitespace(css[pos])) {
+      ++pos;
+    }
+
+    if (pos >= css.size()) return false;
+
+    // Handle @-rules iteratively (avoids recursion/stack overflow)
+    if (css[pos] == '@') {
+      pos = skipAtRule(css, pos);
+      continue;  // Try again after skipping the @-rule
+    }
+
+    break;  // Found start of a regular rule
+  }
+
+  if (pos >= css.size()) return false;
+
+  // Find opening brace
+  const size_t bracePos = css.find('{', pos);
+  if (bracePos == std::string::npos) return false;
+
+  // Extract selector (everything before the brace)
+  selector = css.substr(pos, bracePos - pos);
+
+  // Find matching closing brace
+  int depth = 1;
+  const size_t bodyStart = bracePos + 1;
+  size_t bodyEnd = bodyStart;
+
+  while (bodyEnd < css.size() && depth > 0) {
+    if (css[bodyEnd] == '{')
+      ++depth;
+    else if (css[bodyEnd] == '}')
+      --depth;
+    ++bodyEnd;
+  }
+
+  // Extract body (between braces)
+  if (bodyEnd > bodyStart) {
+    body = css.substr(bodyStart, bodyEnd - bodyStart - 1);
+  }
+
+  pos = bodyEnd;
+  return true;
+}
+
+}  // anonymous namespace
+
+// String utilities implementation
+
+std::string CssParser::normalized(const std::string& s) {
+  std::string result;
+  result.reserve(s.size());
+
+  bool inSpace = true;  // Start true to skip leading space
+  for (const char c : s) {
+    if (isCssWhitespace(c)) {
+      if (!inSpace) {
+        result.push_back(' ');
+        inSpace = true;
+      }
+    } else {
+      result.push_back(static_cast<char>(std::tolower(static_cast<unsigned char>(c))));
+      inSpace = false;
+    }
+  }
+
+  // Remove trailing space
+  if (!result.empty() && result.back() == ' ') {
+    result.pop_back();
+  }
+  return result;
+}
+
+std::vector<std::string> CssParser::splitOnChar(const std::string& s, const char delimiter) {
+  std::vector<std::string> parts;
+  size_t start = 0;
+
+  for (size_t i = 0; i <= s.size(); ++i) {
+    if (i == s.size() || s[i] == delimiter) {
+      std::string part = s.substr(start, i - start);
+      std::string trimmed = normalized(part);
+      if (!trimmed.empty()) {
+        parts.push_back(trimmed);
+      }
+      start = i + 1;
+    }
+  }
+  return parts;
+}
+
+std::vector<std::string> CssParser::splitWhitespace(const std::string& s) {
+  std::vector<std::string> parts;
+  size_t start = 0;
+  bool inWord = false;
+
+  for (size_t i = 0; i <= s.size(); ++i) {
+    const bool isSpace = i == s.size() || isCssWhitespace(s[i]);
+    if (isSpace && inWord) {
+      parts.push_back(s.substr(start, i - start));
+      inWord = false;
+    } else if (!isSpace && !inWord) {
+      start = i;
+      inWord = true;
+    }
+  }
+  return parts;
+}
+
+// Property value interpreters
+
+CssTextAlign CssParser::interpretAlignment(const std::string& val) {
+  const std::string v = normalized(val);
+
+  if (v == "left" || v == "start") return CssTextAlign::Left;
+  if (v == "right" || v == "end") return CssTextAlign::Right;
+  if (v == "center") return CssTextAlign::Center;
+  if (v == "justify") return CssTextAlign::Justify;
+
+  return CssTextAlign::Left;
+}
+
+CssFontStyle CssParser::interpretFontStyle(const std::string& val) {
+  const std::string v = normalized(val);
+
+  if (v == "italic" || v == "oblique") return CssFontStyle::Italic;
+  return CssFontStyle::Normal;
+}
+
+CssFontWeight CssParser::interpretFontWeight(const std::string& val) {
+  const std::string v = normalized(val);
+
+  // Named values
+  if (v == "bold" || v == "bolder") return CssFontWeight::Bold;
+  if (v == "normal" || v == "lighter") return CssFontWeight::Normal;
+
+  // Numeric values: 100-900
+  // CSS spec: 400 = normal, 700 = bold
+  // We use: 0-400 = normal, 700+ = bold, 500-600 = normal (conservative)
+  char* endPtr = nullptr;
+  const long numericWeight = std::strtol(v.c_str(), &endPtr, 10);
+
+  // If we parsed a number and consumed the whole string
+  if (endPtr != v.c_str() && *endPtr == '\0') {
+    return numericWeight >= 700 ? CssFontWeight::Bold : CssFontWeight::Normal;
+  }
+
+  return CssFontWeight::Normal;
+}
+
+CssTextDecoration CssParser::interpretDecoration(const std::string& val) {
+  const std::string v = normalized(val);
+
+  // text-decoration can have multiple space-separated values
+  if (v.find("underline") != std::string::npos) {
+    return CssTextDecoration::Underline;
+  }
+  return CssTextDecoration::None;
+}
+
+CssLength CssParser::interpretLength(const std::string& val) {
+  const std::string v = normalized(val);
+  if (v.empty()) return CssLength{};
+
+  // Find where the number ends
+  size_t unitStart = v.size();
+  for (size_t i = 0; i < v.size(); ++i) {
+    const char c = v[i];
+    if (!std::isdigit(c) && c != '.' && c != '-' && c != '+') {
+      unitStart = i;
+      break;
+    }
+  }
+
+  const std::string numPart = v.substr(0, unitStart);
+  const std::string unitPart = v.substr(unitStart);
+
+  // Parse numeric value
+  char* endPtr = nullptr;
+  const float numericValue = std::strtof(numPart.c_str(), &endPtr);
+  if (endPtr == numPart.c_str()) return CssLength{};  // No number parsed
+
+  // Determine unit type (preserve for deferred resolution)
+  auto unit = CssUnit::Pixels;
+  if (unitPart == "em") {
+    unit = CssUnit::Em;
+  } else if (unitPart == "rem") {
+    unit = CssUnit::Rem;
+  } else if (unitPart == "pt") {
+    unit = CssUnit::Points;
+  } else if (unitPart == "%") {
+    unit = CssUnit::Percent;
+  }
+  // px and unitless default to Pixels
+
+  return CssLength{numericValue, unit};
+}
+
+int8_t CssParser::interpretSpacing(const std::string& val) {
+  const std::string v = normalized(val);
+  if (v.empty()) return 0;
+
+  // For spacing, we convert to "lines" (discrete units for e-ink)
+  // 1em ≈ 1 line, percentages based on ~30 lines per page
+
+  float multiplier = 0.0f;
+  size_t unitStart = v.size();
+
+  for (size_t i = 0; i < v.size(); ++i) {
+    const char c = v[i];
+    if (!std::isdigit(c) && c != '.' && c != '-' && c != '+') {
+      unitStart = i;
+      break;
+    }
+  }
+
+  const std::string numPart = v.substr(0, unitStart);
+  const std::string unitPart = v.substr(unitStart);
+
+  if (unitPart == "em" || unitPart == "rem") {
+    multiplier = 1.0f;  // 1em = 1 line
+  } else if (unitPart == "%") {
+    multiplier = 0.3f;  // ~30 lines per page, so 10% = 3 lines
+  } else {
+    return 0;  // Unsupported unit for spacing
+  }
+
+  char* endPtr = nullptr;
+  const float numericValue = std::strtof(numPart.c_str(), &endPtr);
+
+  if (endPtr == numPart.c_str()) return 0;
+
+  int lines = static_cast<int>(numericValue * multiplier);
+
+  // Clamp to reasonable range (0-2 lines)
+  if (lines < 0) lines = 0;
+  if (lines > 2) lines = 2;
+
+  return static_cast<int8_t>(lines);
+}
+
+// Declaration parsing
+
+CssStyle CssParser::parseDeclarations(const std::string& declBlock) {
+  CssStyle style;
+
+  // Split declarations by semicolon
+  const auto declarations = splitOnChar(declBlock, ';');
+
+  for (const auto& decl : declarations) {
+    // Find colon separator
+    const size_t colonPos = decl.find(':');
+    if (colonPos == std::string::npos || colonPos == 0) continue;
+
+    std::string propName = normalized(decl.substr(0, colonPos));
+    std::string propValue = normalized(decl.substr(colonPos + 1));
+
+    if (propName.empty() || propValue.empty()) continue;
+
+    // Match property and set value
+    if (propName == "text-align") {
+      style.textAlign = interpretAlignment(propValue);
+      style.defined.textAlign = 1;
+    } else if (propName == "font-style") {
+      style.fontStyle = interpretFontStyle(propValue);
+      style.defined.fontStyle = 1;
+    } else if (propName == "font-weight") {
+      style.fontWeight = interpretFontWeight(propValue);
+      style.defined.fontWeight = 1;
+    } else if (propName == "text-decoration" || propName == "text-decoration-line") {
+      style.textDecoration = interpretDecoration(propValue);
+      style.defined.textDecoration = 1;
+    } else if (propName == "text-indent") {
+      style.textIndent = interpretLength(propValue);
+      style.defined.textIndent = 1;
+    } else if (propName == "margin-top") {
+      style.marginTop = interpretLength(propValue);
+      style.defined.marginTop = 1;
+    } else if (propName == "margin-bottom") {
+      style.marginBottom = interpretLength(propValue);
+      style.defined.marginBottom = 1;
+    } else if (propName == "margin-left") {
+      style.marginLeft = interpretLength(propValue);
+      style.defined.marginLeft = 1;
+    } else if (propName == "margin-right") {
+      style.marginRight = interpretLength(propValue);
+      style.defined.marginRight = 1;
+    } else if (propName == "margin") {
+      // Shorthand: 1-4 values for top, right, bottom, left
+      const auto values = splitWhitespace(propValue);
+      if (!values.empty()) {
+        style.marginTop = interpretLength(values[0]);
+        style.marginRight = values.size() >= 2 ? interpretLength(values[1]) : style.marginTop;
+        style.marginBottom = values.size() >= 3 ? interpretLength(values[2]) : style.marginTop;
+        style.marginLeft = values.size() >= 4 ? interpretLength(values[3]) : style.marginRight;
+        style.defined.marginTop = style.defined.marginRight = style.defined.marginBottom = style.defined.marginLeft = 1;
+      }
+    } else if (propName == "padding-top") {
+      style.paddingTop = interpretLength(propValue);
+      style.defined.paddingTop = 1;
+    } else if (propName == "padding-bottom") {
+      style.paddingBottom = interpretLength(propValue);
+      style.defined.paddingBottom = 1;
+    } else if (propName == "padding-left") {
+      style.paddingLeft = interpretLength(propValue);
+      style.defined.paddingLeft = 1;
+    } else if (propName == "padding-right") {
+      style.paddingRight = interpretLength(propValue);
+      style.defined.paddingRight = 1;
+    } else if (propName == "padding") {
+      // Shorthand: 1-4 values for top, right, bottom, left
+      const auto values = splitWhitespace(propValue);
+      if (!values.empty()) {
+        style.paddingTop = interpretLength(values[0]);
+        style.paddingRight = values.size() >= 2 ? interpretLength(values[1]) : style.paddingTop;
+        style.paddingBottom = values.size() >= 3 ? interpretLength(values[2]) : style.paddingTop;
+        style.paddingLeft = values.size() >= 4 ? interpretLength(values[3]) : style.paddingRight;
+        style.defined.paddingTop = style.defined.paddingRight = style.defined.paddingBottom =
+            style.defined.paddingLeft = 1;
+      }
+    }
+  }
+
+  return style;
+}
+
+// Rule processing
+
+void CssParser::processRuleBlock(const std::string& selectorGroup, const std::string& declarations) {
+  const CssStyle style = parseDeclarations(declarations);
+
+  // Only store if any properties were set
+  if (!style.defined.anySet()) return;
+
+  // Handle comma-separated selectors
+  const auto selectors = splitOnChar(selectorGroup, ',');
+
+  for (const auto& sel : selectors) {
+    // Normalize the selector
+    std::string key = normalized(sel);
+    if (key.empty()) continue;
+
+    // Store or merge with existing
+    auto it = rulesBySelector_.find(key);
+    if (it != rulesBySelector_.end()) {
+      it->second.applyOver(style);
+    } else {
+      rulesBySelector_[key] = style;
+    }
+  }
+}
+
+// Main parsing entry point
+
+bool CssParser::loadFromStream(FsFile& source) {
+  if (!source) {
+    Serial.printf("[%lu] [CSS] Cannot read from invalid file\n", millis());
+    return false;
+  }
+
+  // Read file content
+  const std::string content = readFileContent(source);
+  if (content.empty()) {
+    return true;  // Empty file is valid
+  }
+
+  // Remove comments
+  const std::string cleaned = stripComments(content);
+
+  // Parse rules
+  size_t pos = 0;
+  std::string selector, body;
+
+  while (extractNextRule(cleaned, pos, selector, body)) {
+    processRuleBlock(selector, body);
+  }
+
+  Serial.printf("[%lu] [CSS] Parsed %zu rules\n", millis(), rulesBySelector_.size());
+  return true;
+}
+
+// Style resolution
+
+CssStyle CssParser::resolveStyle(const std::string& tagName, const std::string& classAttr) const {
+  CssStyle result;
+  const std::string tag = normalized(tagName);
+
+  // 1. Apply element-level style (lowest priority)
+  const auto tagIt = rulesBySelector_.find(tag);
+  if (tagIt != rulesBySelector_.end()) {
+    result.applyOver(tagIt->second);
+  }
+
+  // 2. Apply class styles (medium priority)
+  if (!classAttr.empty()) {
+    const auto classes = splitWhitespace(classAttr);
+
+    for (const auto& cls : classes) {
+      std::string classKey = "." + normalized(cls);
+
+      auto classIt = rulesBySelector_.find(classKey);
+      if (classIt != rulesBySelector_.end()) {
+        result.applyOver(classIt->second);
+      }
+    }
+
+    // 3. Apply element.class styles (higher priority)
+    for (const auto& cls : classes) {
+      std::string combinedKey = tag + "." + normalized(cls);
+
+      auto combinedIt = rulesBySelector_.find(combinedKey);
+      if (combinedIt != rulesBySelector_.end()) {
+        result.applyOver(combinedIt->second);
+      }
+    }
+  }
+
+  return result;
+}
+
+// Inline style parsing (static - doesn't need rule database)
+
+CssStyle CssParser::parseInlineStyle(const std::string& styleValue) { return parseDeclarations(styleValue); }
+
+// Cache serialization
+
+// Cache format version - increment when format changes
+constexpr uint8_t CSS_CACHE_VERSION = 2;
+
+bool CssParser::saveToCache(FsFile& file) const {
+  if (!file) {
+    return false;
+  }
+
+  // Write version
+  file.write(CSS_CACHE_VERSION);
+
+  // Write rule count
+  const auto ruleCount = static_cast<uint16_t>(rulesBySelector_.size());
+  file.write(reinterpret_cast<const uint8_t*>(&ruleCount), sizeof(ruleCount));
+
+  // Write each rule: selector string + CssStyle fields
+  for (const auto& pair : rulesBySelector_) {
+    // Write selector string (length-prefixed)
+    const auto selectorLen = static_cast<uint16_t>(pair.first.size());
+    file.write(reinterpret_cast<const uint8_t*>(&selectorLen), sizeof(selectorLen));
+    file.write(reinterpret_cast<const uint8_t*>(pair.first.data()), selectorLen);
+
+    // Write CssStyle fields (all are POD types)
+    const CssStyle& style = pair.second;
+    file.write(static_cast<uint8_t>(style.textAlign));
+    file.write(static_cast<uint8_t>(style.fontStyle));
+    file.write(static_cast<uint8_t>(style.fontWeight));
+    file.write(static_cast<uint8_t>(style.textDecoration));
+
+    // Write CssLength fields (value + unit)
+    auto writeLength = [&file](const CssLength& len) {
+      file.write(reinterpret_cast<const uint8_t*>(&len.value), sizeof(len.value));
+      file.write(static_cast<uint8_t>(len.unit));
+    };
+
+    writeLength(style.textIndent);
+    writeLength(style.marginTop);
+    writeLength(style.marginBottom);
+    writeLength(style.marginLeft);
+    writeLength(style.marginRight);
+    writeLength(style.paddingTop);
+    writeLength(style.paddingBottom);
+    writeLength(style.paddingLeft);
+    writeLength(style.paddingRight);
+
+    // Write defined flags as uint16_t
+    uint16_t definedBits = 0;
+    if (style.defined.textAlign) definedBits |= 1 << 0;
+    if (style.defined.fontStyle) definedBits |= 1 << 1;
+    if (style.defined.fontWeight) definedBits |= 1 << 2;
+    if (style.defined.textDecoration) definedBits |= 1 << 3;
+    if (style.defined.textIndent) definedBits |= 1 << 4;
+    if (style.defined.marginTop) definedBits |= 1 << 5;
+    if (style.defined.marginBottom) definedBits |= 1 << 6;
+    if (style.defined.marginLeft) definedBits |= 1 << 7;
+    if (style.defined.marginRight) definedBits |= 1 << 8;
+    if (style.defined.paddingTop) definedBits |= 1 << 9;
+    if (style.defined.paddingBottom) definedBits |= 1 << 10;
+    if (style.defined.paddingLeft) definedBits |= 1 << 11;
+    if (style.defined.paddingRight) definedBits |= 1 << 12;
+    file.write(reinterpret_cast<const uint8_t*>(&definedBits), sizeof(definedBits));
+  }
+
+  Serial.printf("[%lu] [CSS] Saved %u rules to cache\n", millis(), ruleCount);
+  return true;
+}
+
+bool CssParser::loadFromCache(FsFile& file) {
+  if (!file) {
+    return false;
+  }
+
+  // Clear existing rules
+  clear();
+
+  // Read and verify version
+  uint8_t version = 0;
+  if (file.read(&version, 1) != 1 || version != CSS_CACHE_VERSION) {
+    Serial.printf("[%lu] [CSS] Cache version mismatch (got %u, expected %u)\n", millis(), version, CSS_CACHE_VERSION);
+    return false;
+  }
+
+  // Read rule count
+  uint16_t ruleCount = 0;
+  if (file.read(&ruleCount, sizeof(ruleCount)) != sizeof(ruleCount)) {
+    return false;
+  }
+
+  // Read each rule
+  for (uint16_t i = 0; i < ruleCount; ++i) {
+    // Read selector string
+    uint16_t selectorLen = 0;
+    if (file.read(&selectorLen, sizeof(selectorLen)) != sizeof(selectorLen)) {
+      rulesBySelector_.clear();
+      return false;
+    }
+
+    std::string selector;
+    selector.resize(selectorLen);
+    if (file.read(&selector[0], selectorLen) != selectorLen) {
+      rulesBySelector_.clear();
+      return false;
+    }
+
+    // Read CssStyle fields
+    CssStyle style;
+    uint8_t enumVal;
+
+    if (file.read(&enumVal, 1) != 1) {
+      rulesBySelector_.clear();
+      return false;
+    }
+    style.textAlign = static_cast<CssTextAlign>(enumVal);
+
+    if (file.read(&enumVal, 1) != 1) {
+      rulesBySelector_.clear();
+      return false;
+    }
+    style.fontStyle = static_cast<CssFontStyle>(enumVal);
+
+    if (file.read(&enumVal, 1) != 1) {
+      rulesBySelector_.clear();
+      return false;
+    }
+    style.fontWeight = static_cast<CssFontWeight>(enumVal);
+
+    if (file.read(&enumVal, 1) != 1) {
+      rulesBySelector_.clear();
+      return false;
+    }
+    style.textDecoration = static_cast<CssTextDecoration>(enumVal);
+
+    // Read CssLength fields
+    auto readLength = [&file](CssLength& len) -> bool {
+      if (file.read(&len.value, sizeof(len.value)) != sizeof(len.value)) {
+        return false;
+      }
+      uint8_t unitVal;
+      if (file.read(&unitVal, 1) != 1) {
+        return false;
+      }
+      len.unit = static_cast<CssUnit>(unitVal);
+      return true;
+    };
+
+    if (!readLength(style.textIndent) || !readLength(style.marginTop) || !readLength(style.marginBottom) ||
+        !readLength(style.marginLeft) || !readLength(style.marginRight) || !readLength(style.paddingTop) ||
+        !readLength(style.paddingBottom) || !readLength(style.paddingLeft) || !readLength(style.paddingRight)) {
+      rulesBySelector_.clear();
+      return false;
+    }
+
+    // Read defined flags
+    uint16_t definedBits = 0;
+    if (file.read(&definedBits, sizeof(definedBits)) != sizeof(definedBits)) {
+      rulesBySelector_.clear();
+      return false;
+    }
+    style.defined.textAlign = (definedBits & 1 << 0) != 0;
+    style.defined.fontStyle = (definedBits & 1 << 1) != 0;
+    style.defined.fontWeight = (definedBits & 1 << 2) != 0;
+    style.defined.textDecoration = (definedBits & 1 << 3) != 0;
+    style.defined.textIndent = (definedBits & 1 << 4) != 0;
+    style.defined.marginTop = (definedBits & 1 << 5) != 0;
+    style.defined.marginBottom = (definedBits & 1 << 6) != 0;
+    style.defined.marginLeft = (definedBits & 1 << 7) != 0;
+    style.defined.marginRight = (definedBits & 1 << 8) != 0;
+    style.defined.paddingTop = (definedBits & 1 << 9) != 0;
+    style.defined.paddingBottom = (definedBits & 1 << 10) != 0;
+    style.defined.paddingLeft = (definedBits & 1 << 11) != 0;
+    style.defined.paddingRight = (definedBits & 1 << 12) != 0;
+
+    rulesBySelector_[selector] = style;
+  }
+
+  Serial.printf("[%lu] [CSS] Loaded %u rules from cache\n", millis(), ruleCount);
+  return true;
+}

lib/Epub/Epub/css/CssParser.h

@@ -0,0 +1,114 @@
+#pragma once
+
+#include <HalStorage.h>
+
+#include <string>
+#include <unordered_map>
+#include <vector>
+
+#include "CssStyle.h"
+
+/**
+ * Lightweight CSS parser for EPUB stylesheets
+ *
+ * Parses CSS files and extracts styling information relevant for e-ink display.
+ * Uses a two-phase approach: first tokenizes the CSS content, then builds
+ * a rule database that can be queried during HTML parsing.
+ *
+ * Supported selectors:
+ *   - Element selectors: p, div, h1, etc.
+ *   - Class selectors: .classname
+ *   - Combined: element.classname
+ *   - Grouped: selector1, selector2 { }
+ *
+ * Not supported (silently ignored):
+ *   - Descendant/child selectors
+ *   - Pseudo-classes and pseudo-elements
+ *   - Media queries (content is skipped)
+ *   - @import, @font-face, etc.
+ */
+class CssParser {
+ public:
+  CssParser() = default;
+  ~CssParser() = default;
+
+  // Non-copyable
+  CssParser(const CssParser&) = delete;
+  CssParser& operator=(const CssParser&) = delete;
+
+  /**
+   * Load and parse CSS from a file stream.
+   * Can be called multiple times to accumulate rules from multiple stylesheets.
+   * @param source Open file handle to read from
+   * @return true if parsing completed (even if no rules found)
+   */
+  bool loadFromStream(FsFile& source);
+
+  /**
+   * Look up the style for an HTML element, considering tag name and class attributes.
+   * Applies CSS cascade: element style < class style < element.class style
+   *
+   * @param tagName The HTML element name (e.g., "p", "div")
+   * @param classAttr The class attribute value (may contain multiple space-separated classes)
+   * @return Combined style with all applicable rules merged
+   */
+  [[nodiscard]] CssStyle resolveStyle(const std::string& tagName, const std::string& classAttr) const;
+
+  /**
+   * Parse an inline style attribute string.
+   * @param styleValue The value of a style="" attribute
+   * @return Parsed style properties
+   */
+  [[nodiscard]] static CssStyle parseInlineStyle(const std::string& styleValue);
+
+  /**
+   * Check if any rules have been loaded
+   */
+  [[nodiscard]] bool empty() const { return rulesBySelector_.empty(); }
+
+  /**
+   * Get count of loaded rule sets
+   */
+  [[nodiscard]] size_t ruleCount() const { return rulesBySelector_.size(); }
+
+  /**
+   * Clear all loaded rules
+   */
+  void clear() { rulesBySelector_.clear(); }
+
+  /**
+   * Save parsed CSS rules to a cache file.
+   * @param file Open file handle to write to
+   * @return true if cache was written successfully
+   */
+  bool saveToCache(FsFile& file) const;
+
+  /**
+   * Load CSS rules from a cache file.
+   * Clears any existing rules before loading.
+   * @param file Open file handle to read from
+   * @return true if cache was loaded successfully
+   */
+  bool loadFromCache(FsFile& file);
+
+ private:
+  // Storage: maps normalized selector -> style properties
+  std::unordered_map<std::string, CssStyle> rulesBySelector_;
+
+  // Internal parsing helpers
+  void processRuleBlock(const std::string& selectorGroup, const std::string& declarations);
+  static CssStyle parseDeclarations(const std::string& declBlock);
+
+  // Individual property value parsers
+  static CssTextAlign interpretAlignment(const std::string& val);
+  static CssFontStyle interpretFontStyle(const std::string& val);
+  static CssFontWeight interpretFontWeight(const std::string& val);
+  static CssTextDecoration interpretDecoration(const std::string& val);
+  static CssLength interpretLength(const std::string& val);
+  static int8_t interpretSpacing(const std::string& val);
+
+  // String utilities
+  static std::string normalized(const std::string& s);
+  static std::vector<std::string> splitOnChar(const std::string& s, char delimiter);
+  static std::vector<std::string> splitWhitespace(const std::string& s);
+};

lib/Epub/Epub/css/CssStyle.h

@@ -0,0 +1,202 @@
+#pragma once
+
+#include <cstdint>
+
+// Matches order of PARAGRAPH_ALIGNMENT in CrossPointSettings
+enum class CssTextAlign : uint8_t { Justify = 0, Left = 1, Center = 2, Right = 3, None = 4 };
+enum class CssUnit : uint8_t { Pixels = 0, Em = 1, Rem = 2, Points = 3, Percent = 4 };
+
+// Represents a CSS length value with its unit, allowing deferred resolution to pixels
+struct CssLength {
+  float value = 0.0f;
+  CssUnit unit = CssUnit::Pixels;
+
+  CssLength() = default;
+  CssLength(const float v, const CssUnit u) : value(v), unit(u) {}
+
+  // Convenience constructor for pixel values (most common case)
+  explicit CssLength(const float pixels) : value(pixels) {}
+
+  // Returns true if this length can be resolved to pixels with the given context.
+  // Percentage units require a non-zero containerWidth to resolve.
+  [[nodiscard]] bool isResolvable(const float containerWidth = 0) const {
+    return unit != CssUnit::Percent || containerWidth > 0;
+  }
+
+  // Resolve to pixels given the current em size (font line height)
+  // containerWidth is needed for percentage units (e.g. viewport width)
+  [[nodiscard]] float toPixels(const float emSize, const float containerWidth = 0) const {
+    switch (unit) {
+      case CssUnit::Em:
+      case CssUnit::Rem:
+        return value * emSize;
+      case CssUnit::Points:
+        return value * 1.33f;  // Approximate pt to px conversion
+      case CssUnit::Percent:
+        return value * containerWidth / 100.0f;
+      default:
+        return value;
+    }
+  }
+
+  // Resolve to int16_t pixels (for BlockStyle fields)
+  [[nodiscard]] int16_t toPixelsInt16(const float emSize, const float containerWidth = 0) const {
+    return static_cast<int16_t>(toPixels(emSize, containerWidth));
+  }
+};
+
+// Font style options matching CSS font-style property
+enum class CssFontStyle : uint8_t { Normal = 0, Italic = 1 };
+
+// Font weight options - CSS supports 100-900, we simplify to normal/bold
+enum class CssFontWeight : uint8_t { Normal = 0, Bold = 1 };
+
+// Text decoration options
+enum class CssTextDecoration : uint8_t { None = 0, Underline = 1 };
+
+// Bitmask for tracking which properties have been explicitly set
+struct CssPropertyFlags {
+  uint16_t textAlign : 1;
+  uint16_t fontStyle : 1;
+  uint16_t fontWeight : 1;
+  uint16_t textDecoration : 1;
+  uint16_t textIndent : 1;
+  uint16_t marginTop : 1;
+  uint16_t marginBottom : 1;
+  uint16_t marginLeft : 1;
+  uint16_t marginRight : 1;
+  uint16_t paddingTop : 1;
+  uint16_t paddingBottom : 1;
+  uint16_t paddingLeft : 1;
+  uint16_t paddingRight : 1;
+
+  CssPropertyFlags()
+      : textAlign(0),
+        fontStyle(0),
+        fontWeight(0),
+        textDecoration(0),
+        textIndent(0),
+        marginTop(0),
+        marginBottom(0),
+        marginLeft(0),
+        marginRight(0),
+        paddingTop(0),
+        paddingBottom(0),
+        paddingLeft(0),
+        paddingRight(0) {}
+
+  [[nodiscard]] bool anySet() const {
+    return textAlign || fontStyle || fontWeight || textDecoration || textIndent || marginTop || marginBottom ||
+           marginLeft || marginRight || paddingTop || paddingBottom || paddingLeft || paddingRight;
+  }
+
+  void clearAll() {
+    textAlign = fontStyle = fontWeight = textDecoration = textIndent = 0;
+    marginTop = marginBottom = marginLeft = marginRight = 0;
+    paddingTop = paddingBottom = paddingLeft = paddingRight = 0;
+  }
+};
+
+// Represents a collection of CSS style properties
+// Only stores properties relevant to e-ink text rendering
+// Length values are stored as CssLength (value + unit) for deferred resolution
+struct CssStyle {
+  CssTextAlign textAlign = CssTextAlign::Left;
+  CssFontStyle fontStyle = CssFontStyle::Normal;
+  CssFontWeight fontWeight = CssFontWeight::Normal;
+  CssTextDecoration textDecoration = CssTextDecoration::None;
+
+  CssLength textIndent;     // First-line indent (deferred resolution)
+  CssLength marginTop;      // Vertical spacing before block
+  CssLength marginBottom;   // Vertical spacing after block
+  CssLength marginLeft;     // Horizontal spacing left of block
+  CssLength marginRight;    // Horizontal spacing right of block
+  CssLength paddingTop;     // Padding before
+  CssLength paddingBottom;  // Padding after
+  CssLength paddingLeft;    // Padding left
+  CssLength paddingRight;   // Padding right
+
+  CssPropertyFlags defined;  // Tracks which properties were explicitly set
+
+  // Apply properties from another style, only overwriting if the other style
+  // has that property explicitly defined
+  void applyOver(const CssStyle& base) {
+    if (base.hasTextAlign()) {
+      textAlign = base.textAlign;
+      defined.textAlign = 1;
+    }
+    if (base.hasFontStyle()) {
+      fontStyle = base.fontStyle;
+      defined.fontStyle = 1;
+    }
+    if (base.hasFontWeight()) {
+      fontWeight = base.fontWeight;
+      defined.fontWeight = 1;
+    }
+    if (base.hasTextDecoration()) {
+      textDecoration = base.textDecoration;
+      defined.textDecoration = 1;
+    }
+    if (base.hasTextIndent()) {
+      textIndent = base.textIndent;
+      defined.textIndent = 1;
+    }
+    if (base.hasMarginTop()) {
+      marginTop = base.marginTop;
+      defined.marginTop = 1;
+    }
+    if (base.hasMarginBottom()) {
+      marginBottom = base.marginBottom;
+      defined.marginBottom = 1;
+    }
+    if (base.hasMarginLeft()) {
+      marginLeft = base.marginLeft;
+      defined.marginLeft = 1;
+    }
+    if (base.hasMarginRight()) {
+      marginRight = base.marginRight;
+      defined.marginRight = 1;
+    }
+    if (base.hasPaddingTop()) {
+      paddingTop = base.paddingTop;
+      defined.paddingTop = 1;
+    }
+    if (base.hasPaddingBottom()) {
+      paddingBottom = base.paddingBottom;
+      defined.paddingBottom = 1;
+    }
+    if (base.hasPaddingLeft()) {
+      paddingLeft = base.paddingLeft;
+      defined.paddingLeft = 1;
+    }
+    if (base.hasPaddingRight()) {
+      paddingRight = base.paddingRight;
+      defined.paddingRight = 1;
+    }
+  }
+
+  [[nodiscard]] bool hasTextAlign() const { return defined.textAlign; }
+  [[nodiscard]] bool hasFontStyle() const { return defined.fontStyle; }
+  [[nodiscard]] bool hasFontWeight() const { return defined.fontWeight; }
+  [[nodiscard]] bool hasTextDecoration() const { return defined.textDecoration; }
+  [[nodiscard]] bool hasTextIndent() const { return defined.textIndent; }
+  [[nodiscard]] bool hasMarginTop() const { return defined.marginTop; }
+  [[nodiscard]] bool hasMarginBottom() const { return defined.marginBottom; }
+  [[nodiscard]] bool hasMarginLeft() const { return defined.marginLeft; }
+  [[nodiscard]] bool hasMarginRight() const { return defined.marginRight; }
+  [[nodiscard]] bool hasPaddingTop() const { return defined.paddingTop; }
+  [[nodiscard]] bool hasPaddingBottom() const { return defined.paddingBottom; }
+  [[nodiscard]] bool hasPaddingLeft() const { return defined.paddingLeft; }
+  [[nodiscard]] bool hasPaddingRight() const { return defined.paddingRight; }
+
+  void reset() {
+    textAlign = CssTextAlign::Left;
+    fontStyle = CssFontStyle::Normal;
+    fontWeight = CssFontWeight::Normal;
+    textDecoration = CssTextDecoration::None;
+    textIndent = CssLength{};
+    marginTop = marginBottom = marginLeft = marginRight = CssLength{};
+    paddingTop = paddingBottom = paddingLeft = paddingRight = CssLength{};
+    defined.clearAll();
+  }
+};

lib/Epub/Epub/parsers/ChapterHtmlSlimParser.cpp

@@ -1,8 +1,8 @@
 #include "ChapterHtmlSlimParser.h"
 
 #include <GfxRenderer.h>
+#include <HalStorage.h>
 #include <HardwareSerial.h>
-#include <SDCardManager.h>
 #include <expat.h>
 
 #include "../Page.h"
@@ -10,8 +10,8 @@
 const char* HEADER_TAGS[] = {"h1", "h2", "h3", "h4", "h5", "h6"};
 constexpr int NUM_HEADER_TAGS = sizeof(HEADER_TAGS) / sizeof(HEADER_TAGS[0]);
 
-// Minimum file size (in bytes) to show progress bar - smaller chapters don't benefit from it
-constexpr size_t MIN_SIZE_FOR_PROGRESS = 50 * 1024;  // 50KB
+// Minimum file size (in bytes) to show indexing popup - smaller chapters don't benefit from it
+constexpr size_t MIN_SIZE_FOR_POPUP = 50 * 1024;  // 50KB
 
 const char* BLOCK_TAGS[] = {"p", "li", "div", "br", "blockquote"};
 constexpr int NUM_BLOCK_TAGS = sizeof(BLOCK_TAGS) / sizeof(BLOCK_TAGS[0]);
@@ -22,6 +22,9 @@ constexpr int NUM_BOLD_TAGS = sizeof(BOLD_TAGS) / sizeof(BOLD_TAGS[0]);
 const char* ITALIC_TAGS[] = {"i", "em"};
 constexpr int NUM_ITALIC_TAGS = sizeof(ITALIC_TAGS) / sizeof(ITALIC_TAGS[0]);
 
+const char* UNDERLINE_TAGS[] = {"u", "ins"};
+constexpr int NUM_UNDERLINE_TAGS = sizeof(UNDERLINE_TAGS) / sizeof(UNDERLINE_TAGS[0]);
+
 const char* IMAGE_TAGS[] = {"img"};
 constexpr int NUM_IMAGE_TAGS = sizeof(IMAGE_TAGS) / sizeof(IMAGE_TAGS[0]);
 
@@ -40,35 +43,74 @@ bool matches(const char* tag_name, const char* possible_tags[], const int possib
   return false;
 }
 
+bool isHeaderOrBlock(const char* name) {
+  return matches(name, HEADER_TAGS, NUM_HEADER_TAGS) || matches(name, BLOCK_TAGS, NUM_BLOCK_TAGS);
+}
+
+// Update effective bold/italic/underline based on block style and inline style stack
+void ChapterHtmlSlimParser::updateEffectiveInlineStyle() {
+  // Start with block-level styles
+  effectiveBold = currentCssStyle.hasFontWeight() && currentCssStyle.fontWeight == CssFontWeight::Bold;
+  effectiveItalic = currentCssStyle.hasFontStyle() && currentCssStyle.fontStyle == CssFontStyle::Italic;
+  effectiveUnderline =
+      currentCssStyle.hasTextDecoration() && currentCssStyle.textDecoration == CssTextDecoration::Underline;
+
+  // Apply inline style stack in order
+  for (const auto& entry : inlineStyleStack) {
+    if (entry.hasBold) {
+      effectiveBold = entry.bold;
+    }
+    if (entry.hasItalic) {
+      effectiveItalic = entry.italic;
+    }
+    if (entry.hasUnderline) {
+      effectiveUnderline = entry.underline;
+    }
+  }
+}
+
 // flush the contents of partWordBuffer to currentTextBlock
 void ChapterHtmlSlimParser::flushPartWordBuffer() {
-  // determine font style
+  // Determine font style from depth-based tracking and CSS effective style
+  const bool isBold = boldUntilDepth < depth || effectiveBold;
+  const bool isItalic = italicUntilDepth < depth || effectiveItalic;
+  const bool isUnderline = underlineUntilDepth < depth || effectiveUnderline;
+
+  // Combine style flags using bitwise OR
   EpdFontFamily::Style fontStyle = EpdFontFamily::REGULAR;
-  if (boldUntilDepth < depth && italicUntilDepth < depth) {
-    fontStyle = EpdFontFamily::BOLD_ITALIC;
-  } else if (boldUntilDepth < depth) {
-    fontStyle = EpdFontFamily::BOLD;
-  } else if (italicUntilDepth < depth) {
-    fontStyle = EpdFontFamily::ITALIC;
+  if (isBold) {
+    fontStyle = static_cast<EpdFontFamily::Style>(fontStyle | EpdFontFamily::BOLD);
   }
+  if (isItalic) {
+    fontStyle = static_cast<EpdFontFamily::Style>(fontStyle | EpdFontFamily::ITALIC);
+  }
+  if (isUnderline) {
+    fontStyle = static_cast<EpdFontFamily::Style>(fontStyle | EpdFontFamily::UNDERLINE);
+  }
+
   // flush the buffer
   partWordBuffer[partWordBufferIndex] = '\0';
-  currentTextBlock->addWord(partWordBuffer, fontStyle);
+  currentTextBlock->addWord(partWordBuffer, fontStyle, false, nextWordContinues);
   partWordBufferIndex = 0;
+  nextWordContinues = false;
 }
 
 // start a new text block if needed
-void ChapterHtmlSlimParser::startNewTextBlock(const TextBlock::Style style) {
+void ChapterHtmlSlimParser::startNewTextBlock(const BlockStyle& blockStyle) {
+  nextWordContinues = false;  // New block = new paragraph, no continuation
   if (currentTextBlock) {
     // already have a text block running and it is empty - just reuse it
     if (currentTextBlock->isEmpty()) {
-      currentTextBlock->setStyle(style);
+      // Merge with existing block style to accumulate CSS styling from parent block elements.
+      // This handles cases like <div style="margin-bottom:2em"><h1>text</h1></div> where the
+      // div's margin should be preserved, even though it has no direct text content.
+      currentTextBlock->setBlockStyle(currentTextBlock->getBlockStyle().getCombinedBlockStyle(blockStyle));
       return;
     }
 
     makePages();
   }
-  currentTextBlock.reset(new ParsedText(style, extraParagraphSpacing, hyphenationEnabled));
+  currentTextBlock.reset(new ParsedText(extraParagraphSpacing, hyphenationEnabled, blockStyle));
 }
 
 void XMLCALL ChapterHtmlSlimParser::startElement(void* userData, const XML_Char* name, const XML_Char** atts) {
@@ -80,13 +122,30 @@ void XMLCALL ChapterHtmlSlimParser::startElement(void* userData, const XML_Char*
     return;
   }
 
+  // Extract class and style attributes for CSS processing
+  std::string classAttr;
+  std::string styleAttr;
+  if (atts != nullptr) {
+    for (int i = 0; atts[i]; i += 2) {
+      if (strcmp(atts[i], "class") == 0) {
+        classAttr = atts[i + 1];
+      } else if (strcmp(atts[i], "style") == 0) {
+        styleAttr = atts[i + 1];
+      }
+    }
+  }
+
+  auto centeredBlockStyle = BlockStyle();
+  centeredBlockStyle.textAlignDefined = true;
+  centeredBlockStyle.alignment = CssTextAlign::Center;
+
   // Special handling for tables - show placeholder text instead of dropping silently
   if (strcmp(name, "table") == 0) {
     // Add placeholder text
-    self->startNewTextBlock(TextBlock::CENTER_ALIGN);
+    self->startNewTextBlock(centeredBlockStyle);
 
     self->italicUntilDepth = min(self->italicUntilDepth, self->depth);
-    // Advance depth before processing character data (like you would for a element with text)
+    // Advance depth before processing character data (like you would for an element with text)
     self->depth += 1;
     self->characterData(userData, "[Table omitted]", strlen("[Table omitted]"));
 
@@ -111,9 +170,9 @@ void XMLCALL ChapterHtmlSlimParser::startElement(void* userData, const XML_Char*
 
     Serial.printf("[%lu] [EHP] Image alt: %s\n", millis(), alt.c_str());
 
-    self->startNewTextBlock(TextBlock::CENTER_ALIGN);
+    self->startNewTextBlock(centeredBlockStyle);
     self->italicUntilDepth = min(self->italicUntilDepth, self->depth);
-    // Advance depth before processing character data (like you would for a element with text)
+    // Advance depth before processing character data (like you would for an element with text)
     self->depth += 1;
     self->characterData(userData, alt.c_str(), alt.length());
 
@@ -141,43 +200,139 @@ void XMLCALL ChapterHtmlSlimParser::startElement(void* userData, const XML_Char*
     }
   }
 
-  if (matches(name, HEADER_TAGS, NUM_HEADER_TAGS)) {
-    self->startNewTextBlock(TextBlock::CENTER_ALIGN);
-    self->boldUntilDepth = std::min(self->boldUntilDepth, self->depth);
-    self->depth += 1;
-    return;
+  // Compute CSS style for this element
+  CssStyle cssStyle;
+  if (self->cssParser) {
+    // Get combined tag + class styles
+    cssStyle = self->cssParser->resolveStyle(name, classAttr);
+    // Merge inline style (highest priority)
+    if (!styleAttr.empty()) {
+      CssStyle inlineStyle = CssParser::parseInlineStyle(styleAttr);
+      cssStyle.applyOver(inlineStyle);
+    }
   }
 
-  if (matches(name, BLOCK_TAGS, NUM_BLOCK_TAGS)) {
+  const float emSize = static_cast<float>(self->renderer.getLineHeight(self->fontId)) * self->lineCompression;
+  const auto userAlignmentBlockStyle = BlockStyle::fromCssStyle(
+      cssStyle, emSize, static_cast<CssTextAlign>(self->paragraphAlignment), self->viewportWidth);
+
+  if (matches(name, HEADER_TAGS, NUM_HEADER_TAGS)) {
+    self->currentCssStyle = cssStyle;
+    auto headerBlockStyle = BlockStyle::fromCssStyle(cssStyle, emSize, CssTextAlign::Center, self->viewportWidth);
+    headerBlockStyle.textAlignDefined = true;
+    if (self->embeddedStyle && cssStyle.hasTextAlign()) {
+      headerBlockStyle.alignment = cssStyle.textAlign;
+    }
+    self->startNewTextBlock(headerBlockStyle);
+    self->boldUntilDepth = std::min(self->boldUntilDepth, self->depth);
+    self->updateEffectiveInlineStyle();
+  } else if (matches(name, BLOCK_TAGS, NUM_BLOCK_TAGS)) {
     if (strcmp(name, "br") == 0) {
       if (self->partWordBufferIndex > 0) {
         // flush word preceding <br/> to currentTextBlock before calling startNewTextBlock
         self->flushPartWordBuffer();
       }
-      self->startNewTextBlock(self->currentTextBlock->getStyle());
-      self->depth += 1;
-      return;
+      self->startNewTextBlock(self->currentTextBlock->getBlockStyle());
+    } else {
+      self->currentCssStyle = cssStyle;
+      self->startNewTextBlock(userAlignmentBlockStyle);
+      self->updateEffectiveInlineStyle();
+
+      if (strcmp(name, "li") == 0) {
+        self->currentTextBlock->addWord("\xe2\x80\xa2", EpdFontFamily::REGULAR);
+      }
     }
-
-    self->startNewTextBlock(static_cast<TextBlock::Style>(self->paragraphAlignment));
-    if (strcmp(name, "li") == 0) {
-      self->currentTextBlock->addWord("\xe2\x80\xa2", EpdFontFamily::REGULAR);
+  } else if (matches(name, UNDERLINE_TAGS, NUM_UNDERLINE_TAGS)) {
+    // Flush buffer before style change so preceding text gets current style
+    if (self->partWordBufferIndex > 0) {
+      self->flushPartWordBuffer();
+      self->nextWordContinues = true;
+    }
+    self->underlineUntilDepth = std::min(self->underlineUntilDepth, self->depth);
+    // Push inline style entry for underline tag
+    StyleStackEntry entry;
+    entry.depth = self->depth;  // Track depth for matching pop
+    entry.hasUnderline = true;
+    entry.underline = true;
+    if (cssStyle.hasFontWeight()) {
+      entry.hasBold = true;
+      entry.bold = cssStyle.fontWeight == CssFontWeight::Bold;
+    }
+    if (cssStyle.hasFontStyle()) {
+      entry.hasItalic = true;
+      entry.italic = cssStyle.fontStyle == CssFontStyle::Italic;
+    }
+    self->inlineStyleStack.push_back(entry);
+    self->updateEffectiveInlineStyle();
+  } else if (matches(name, BOLD_TAGS, NUM_BOLD_TAGS)) {
+    // Flush buffer before style change so preceding text gets current style
+    if (self->partWordBufferIndex > 0) {
+      self->flushPartWordBuffer();
+      self->nextWordContinues = true;
     }
-
-    self->depth += 1;
-    return;
-  }
-
-  if (matches(name, BOLD_TAGS, NUM_BOLD_TAGS)) {
     self->boldUntilDepth = std::min(self->boldUntilDepth, self->depth);
-    self->depth += 1;
-    return;
-  }
-
-  if (matches(name, ITALIC_TAGS, NUM_ITALIC_TAGS)) {
+    // Push inline style entry for bold tag
+    StyleStackEntry entry;
+    entry.depth = self->depth;  // Track depth for matching pop
+    entry.hasBold = true;
+    entry.bold = true;
+    if (cssStyle.hasFontStyle()) {
+      entry.hasItalic = true;
+      entry.italic = cssStyle.fontStyle == CssFontStyle::Italic;
+    }
+    if (cssStyle.hasTextDecoration()) {
+      entry.hasUnderline = true;
+      entry.underline = cssStyle.textDecoration == CssTextDecoration::Underline;
+    }
+    self->inlineStyleStack.push_back(entry);
+    self->updateEffectiveInlineStyle();
+  } else if (matches(name, ITALIC_TAGS, NUM_ITALIC_TAGS)) {
+    // Flush buffer before style change so preceding text gets current style
+    if (self->partWordBufferIndex > 0) {
+      self->flushPartWordBuffer();
+      self->nextWordContinues = true;
+    }
     self->italicUntilDepth = std::min(self->italicUntilDepth, self->depth);
-    self->depth += 1;
-    return;
+    // Push inline style entry for italic tag
+    StyleStackEntry entry;
+    entry.depth = self->depth;  // Track depth for matching pop
+    entry.hasItalic = true;
+    entry.italic = true;
+    if (cssStyle.hasFontWeight()) {
+      entry.hasBold = true;
+      entry.bold = cssStyle.fontWeight == CssFontWeight::Bold;
+    }
+    if (cssStyle.hasTextDecoration()) {
+      entry.hasUnderline = true;
+      entry.underline = cssStyle.textDecoration == CssTextDecoration::Underline;
+    }
+    self->inlineStyleStack.push_back(entry);
+    self->updateEffectiveInlineStyle();
+  } else if (strcmp(name, "span") == 0 || !isHeaderOrBlock(name)) {
+    // Handle span and other inline elements for CSS styling
+    if (cssStyle.hasFontWeight() || cssStyle.hasFontStyle() || cssStyle.hasTextDecoration()) {
+      // Flush buffer before style change so preceding text gets current style
+      if (self->partWordBufferIndex > 0) {
+        self->flushPartWordBuffer();
+        self->nextWordContinues = true;
+      }
+      StyleStackEntry entry;
+      entry.depth = self->depth;  // Track depth for matching pop
+      if (cssStyle.hasFontWeight()) {
+        entry.hasBold = true;
+        entry.bold = cssStyle.fontWeight == CssFontWeight::Bold;
+      }
+      if (cssStyle.hasFontStyle()) {
+        entry.hasItalic = true;
+        entry.italic = cssStyle.fontStyle == CssFontStyle::Italic;
+      }
+      if (cssStyle.hasTextDecoration()) {
+        entry.hasUnderline = true;
+        entry.underline = cssStyle.textDecoration == CssTextDecoration::Underline;
+      }
+      self->inlineStyleStack.push_back(entry);
+      self->updateEffectiveInlineStyle();
+    }
   }
 
   // Unprocessed tag, just increasing depth and continue forward
@@ -198,6 +353,8 @@ void XMLCALL ChapterHtmlSlimParser::characterData(void* userData, const XML_Char
       if (self->partWordBufferIndex > 0) {
         self->flushPartWordBuffer();
       }
+      // Whitespace is a real word boundary — reset continuation state
+      self->nextWordContinues = false;
       // Skip the whitespace char
       continue;
     }
@@ -239,18 +396,34 @@ void XMLCALL ChapterHtmlSlimParser::characterData(void* userData, const XML_Char
 void XMLCALL ChapterHtmlSlimParser::endElement(void* userData, const XML_Char* name) {
   auto* self = static_cast<ChapterHtmlSlimParser*>(userData);
 
-  if (self->partWordBufferIndex > 0) {
-    // Only flush out part word buffer if we're closing a block tag or are at the top of the HTML file.
-    // We don't want to flush out content when closing inline tags like <span>.
-    // Currently this also flushes out on closing <b> and <i> tags, but they are line tags so that shouldn't happen,
-    // text styling needs to be overhauled to fix it.
-    const bool shouldBreakText =
-        matches(name, BLOCK_TAGS, NUM_BLOCK_TAGS) || matches(name, HEADER_TAGS, NUM_HEADER_TAGS) ||
-        matches(name, BOLD_TAGS, NUM_BOLD_TAGS) || matches(name, ITALIC_TAGS, NUM_ITALIC_TAGS) ||
-        strcmp(name, "table") == 0 || matches(name, IMAGE_TAGS, NUM_IMAGE_TAGS) || self->depth == 1;
+  // Check if any style state will change after we decrement depth
+  // If so, we MUST flush the partWordBuffer with the CURRENT style first
+  // Note: depth hasn't been decremented yet, so we check against (depth - 1)
+  const bool willPopStyleStack =
+      !self->inlineStyleStack.empty() && self->inlineStyleStack.back().depth == self->depth - 1;
+  const bool willClearBold = self->boldUntilDepth == self->depth - 1;
+  const bool willClearItalic = self->italicUntilDepth == self->depth - 1;
+  const bool willClearUnderline = self->underlineUntilDepth == self->depth - 1;
 
-    if (shouldBreakText) {
+  const bool styleWillChange = willPopStyleStack || willClearBold || willClearItalic || willClearUnderline;
+  const bool headerOrBlockTag = isHeaderOrBlock(name);
+
+  // Flush buffer with current style BEFORE any style changes
+  if (self->partWordBufferIndex > 0) {
+    // Flush if style will change OR if we're closing a block/structural element
+    const bool isInlineTag = !headerOrBlockTag && strcmp(name, "table") != 0 &&
+                             !matches(name, IMAGE_TAGS, NUM_IMAGE_TAGS) && self->depth != 1;
+    const bool shouldFlush = styleWillChange || headerOrBlockTag || matches(name, BOLD_TAGS, NUM_BOLD_TAGS) ||
+                             matches(name, ITALIC_TAGS, NUM_ITALIC_TAGS) ||
+                             matches(name, UNDERLINE_TAGS, NUM_UNDERLINE_TAGS) || strcmp(name, "table") == 0 ||
+                             matches(name, IMAGE_TAGS, NUM_IMAGE_TAGS) || self->depth == 1;
+
+    if (shouldFlush) {
       self->flushPartWordBuffer();
+      // If closing an inline element, the next word fragment continues the same visual word
+      if (isInlineTag) {
+        self->nextWordContinues = true;
+      }
     }
   }
 
@@ -261,19 +434,44 @@ void XMLCALL ChapterHtmlSlimParser::endElement(void* userData, const XML_Char* n
     self->skipUntilDepth = INT_MAX;
   }
 
-  // Leaving bold
+  // Leaving bold tag
   if (self->boldUntilDepth == self->depth) {
     self->boldUntilDepth = INT_MAX;
   }
 
-  // Leaving italic
+  // Leaving italic tag
   if (self->italicUntilDepth == self->depth) {
     self->italicUntilDepth = INT_MAX;
   }
+
+  // Leaving underline tag
+  if (self->underlineUntilDepth == self->depth) {
+    self->underlineUntilDepth = INT_MAX;
+  }
+
+  // Pop from inline style stack if we pushed an entry at this depth
+  // This handles all inline elements: b, i, u, span, etc.
+  if (!self->inlineStyleStack.empty() && self->inlineStyleStack.back().depth == self->depth) {
+    self->inlineStyleStack.pop_back();
+    self->updateEffectiveInlineStyle();
+  }
+
+  // Clear block style when leaving header or block elements
+  if (headerOrBlockTag) {
+    self->currentCssStyle.reset();
+    self->updateEffectiveInlineStyle();
+  }
 }
 
 bool ChapterHtmlSlimParser::parseAndBuildPages() {
-  startNewTextBlock((TextBlock::Style)this->paragraphAlignment);
+  auto paragraphAlignmentBlockStyle = BlockStyle();
+  paragraphAlignmentBlockStyle.textAlignDefined = true;
+  // Resolve None sentinel to Justify for initial block (no CSS context yet)
+  const auto align = (this->paragraphAlignment == static_cast<uint8_t>(CssTextAlign::None))
+                         ? CssTextAlign::Justify
+                         : static_cast<CssTextAlign>(this->paragraphAlignment);
+  paragraphAlignmentBlockStyle.alignment = align;
+  startNewTextBlock(paragraphAlignmentBlockStyle);
 
   const XML_Parser parser = XML_ParserCreate(nullptr);
   int done;
@@ -284,15 +482,15 @@ bool ChapterHtmlSlimParser::parseAndBuildPages() {
   }
 
   FsFile file;
-  if (!SdMan.openFileForRead("EHP", filepath, file)) {
+  if (!Storage.openFileForRead("EHP", filepath, file)) {
     XML_ParserFree(parser);
     return false;
   }
 
-  // Get file size for progress calculation
-  const size_t totalSize = file.size();
-  size_t bytesRead = 0;
-  int lastProgress = -1;
+  // Get file size to decide whether to show indexing popup.
+  if (popupFn && file.size() >= MIN_SIZE_FOR_POPUP) {
+    popupFn();
+  }
 
   XML_SetUserData(parser, this);
   XML_SetElementHandler(parser, startElement, endElement);
@@ -322,17 +520,6 @@ bool ChapterHtmlSlimParser::parseAndBuildPages() {
       return false;
     }
 
-    // Update progress (call every 10% change to avoid too frequent updates)
-    // Only show progress for larger chapters where rendering overhead is worth it
-    bytesRead += len;
-    if (progressFn && totalSize >= MIN_SIZE_FOR_PROGRESS) {
-      const int progress = static_cast<int>((bytesRead * 100) / totalSize);
-      if (lastProgress / 10 != progress / 10) {
-        lastProgress = progress;
-        progressFn(progress);
-      }
-    }
-
     done = file.available() == 0;
 
     if (XML_ParseBuffer(parser, static_cast<int>(len), done) == XML_STATUS_ERROR) {
@@ -373,7 +560,9 @@ void ChapterHtmlSlimParser::addLineToPage(std::shared_ptr<TextBlock> line) {
     currentPageNextY = 0;
   }
 
-  currentPage->elements.push_back(std::make_shared<PageLine>(line, 0, currentPageNextY));
+  // Apply horizontal left inset (margin + padding) as x position offset
+  const int16_t xOffset = line->getBlockStyle().leftInset();
+  currentPage->elements.push_back(std::make_shared<PageLine>(line, xOffset, currentPageNextY));
   currentPageNextY += lineHeight;
 }
 
@@ -389,10 +578,34 @@ void ChapterHtmlSlimParser::makePages() {
   }
 
   const int lineHeight = renderer.getLineHeight(fontId) * lineCompression;
+
+  // Apply top spacing before the paragraph (stored in pixels)
+  const BlockStyle& blockStyle = currentTextBlock->getBlockStyle();
+  if (blockStyle.marginTop > 0) {
+    currentPageNextY += blockStyle.marginTop;
+  }
+  if (blockStyle.paddingTop > 0) {
+    currentPageNextY += blockStyle.paddingTop;
+  }
+
+  // Calculate effective width accounting for horizontal margins/padding
+  const int horizontalInset = blockStyle.totalHorizontalInset();
+  const uint16_t effectiveWidth =
+      (horizontalInset < viewportWidth) ? static_cast<uint16_t>(viewportWidth - horizontalInset) : viewportWidth;
+
   currentTextBlock->layoutAndExtractLines(
-      renderer, fontId, viewportWidth,
+      renderer, fontId, effectiveWidth,
       [this](const std::shared_ptr<TextBlock>& textBlock) { addLineToPage(textBlock); });
-  // Extra paragraph spacing if enabled
+
+  // Apply bottom spacing after the paragraph (stored in pixels)
+  if (blockStyle.marginBottom > 0) {
+    currentPageNextY += blockStyle.marginBottom;
+  }
+  if (blockStyle.paddingBottom > 0) {
+    currentPageNextY += blockStyle.paddingBottom;
+  }
+
+  // Extra paragraph spacing if enabled (default behavior)
   if (extraParagraphSpacing) {
     currentPageNextY += lineHeight / 2;
   }

lib/Epub/Epub/parsers/ChapterHtmlSlimParser.h

@@ -8,6 +8,8 @@
 
 #include "../ParsedText.h"
 #include "../blocks/TextBlock.h"
+#include "../css/CssParser.h"
+#include "../css/CssStyle.h"
 
 class Page;
 class GfxRenderer;
@@ -18,15 +20,17 @@ class ChapterHtmlSlimParser {
   const std::string& filepath;
   GfxRenderer& renderer;
   std::function<void(std::unique_ptr<Page>)> completePageFn;
-  std::function<void(int)> progressFn;  // Progress callback (0-100)
+  std::function<void()> popupFn;  // Popup callback
   int depth = 0;
   int skipUntilDepth = INT_MAX;
   int boldUntilDepth = INT_MAX;
   int italicUntilDepth = INT_MAX;
+  int underlineUntilDepth = INT_MAX;
   // buffer for building up words from characters, will auto break if longer than this
   // leave one char at end for null pointer
   char partWordBuffer[MAX_WORD_SIZE + 1] = {};
   int partWordBufferIndex = 0;
+  bool nextWordContinues = false;  // true when next flushed word attaches to previous (inline element boundary)
   std::unique_ptr<ParsedText> currentTextBlock = nullptr;
   std::unique_ptr<Page> currentPage = nullptr;
   int16_t currentPageNextY = 0;
@@ -37,8 +41,24 @@ class ChapterHtmlSlimParser {
   uint16_t viewportWidth;
   uint16_t viewportHeight;
   bool hyphenationEnabled;
+  const CssParser* cssParser;
+  bool embeddedStyle;
 
-  void startNewTextBlock(TextBlock::Style style);
+  // Style tracking (replaces depth-based approach)
+  struct StyleStackEntry {
+    int depth = 0;
+    bool hasBold = false, bold = false;
+    bool hasItalic = false, italic = false;
+    bool hasUnderline = false, underline = false;
+  };
+  std::vector<StyleStackEntry> inlineStyleStack;
+  CssStyle currentCssStyle;
+  bool effectiveBold = false;
+  bool effectiveItalic = false;
+  bool effectiveUnderline = false;
+
+  void updateEffectiveInlineStyle();
+  void startNewTextBlock(const BlockStyle& blockStyle);
   void flushPartWordBuffer();
   void makePages();
   // XML callbacks
@@ -52,7 +72,9 @@ class ChapterHtmlSlimParser {
                                  const uint8_t paragraphAlignment, const uint16_t viewportWidth,
                                  const uint16_t viewportHeight, const bool hyphenationEnabled,
                                  const std::function<void(std::unique_ptr<Page>)>& completePageFn,
-                                 const std::function<void(int)>& progressFn = nullptr)
+                                 const bool embeddedStyle, const std::function<void()>& popupFn = nullptr,
+                                 const CssParser* cssParser = nullptr)
+
       : filepath(filepath),
         renderer(renderer),
         fontId(fontId),
@@ -63,7 +85,10 @@ class ChapterHtmlSlimParser {
         viewportHeight(viewportHeight),
         hyphenationEnabled(hyphenationEnabled),
         completePageFn(completePageFn),
-        progressFn(progressFn) {}
+        popupFn(popupFn),
+        cssParser(cssParser),
+        embeddedStyle(embeddedStyle) {}
+
   ~ChapterHtmlSlimParser() = default;
   bool parseAndBuildPages();
   void addLineToPage(std::shared_ptr<TextBlock> line);

lib/Epub/Epub/parsers/ContentOpfParser.cpp

@@ -8,6 +8,7 @@
 
 namespace {
 constexpr char MEDIA_TYPE_NCX[] = "application/x-dtbncx+xml";
+constexpr char MEDIA_TYPE_CSS[] = "text/css";
 constexpr char itemCacheFile[] = "/.items.bin";
 }  // namespace
 
@@ -35,8 +36,8 @@ ContentOpfParser::~ContentOpfParser() {
   if (tempItemStore) {
     tempItemStore.close();
   }
-  if (SdMan.exists((cachePath + itemCacheFile).c_str())) {
-    SdMan.remove((cachePath + itemCacheFile).c_str());
+  if (Storage.exists((cachePath + itemCacheFile).c_str())) {
+    Storage.remove((cachePath + itemCacheFile).c_str());
   }
   itemIndex.clear();
   itemIndex.shrink_to_fit();
@@ -117,7 +118,7 @@ void XMLCALL ContentOpfParser::startElement(void* userData, const XML_Char* name
 
   if (self->state == IN_PACKAGE && (strcmp(name, "manifest") == 0 || strcmp(name, "opf:manifest") == 0)) {
     self->state = IN_MANIFEST;
-    if (!SdMan.openFileForWrite("COF", self->cachePath + itemCacheFile, self->tempItemStore)) {
+    if (!Storage.openFileForWrite("COF", self->cachePath + itemCacheFile, self->tempItemStore)) {
       Serial.printf(
           "[%lu] [COF] Couldn't open temp items file for writing. This is probably going to be a fatal error.\n",
           millis());
@@ -127,7 +128,7 @@ void XMLCALL ContentOpfParser::startElement(void* userData, const XML_Char* name
 
   if (self->state == IN_PACKAGE && (strcmp(name, "spine") == 0 || strcmp(name, "opf:spine") == 0)) {
     self->state = IN_SPINE;
-    if (!SdMan.openFileForRead("COF", self->cachePath + itemCacheFile, self->tempItemStore)) {
+    if (!Storage.openFileForRead("COF", self->cachePath + itemCacheFile, self->tempItemStore)) {
       Serial.printf(
           "[%lu] [COF] Couldn't open temp items file for reading. This is probably going to be a fatal error.\n",
           millis());
@@ -148,7 +149,7 @@ void XMLCALL ContentOpfParser::startElement(void* userData, const XML_Char* name
     self->state = IN_GUIDE;
     // TODO Remove print
     Serial.printf("[%lu] [COF] Entering guide state.\n", millis());
-    if (!SdMan.openFileForRead("COF", self->cachePath + itemCacheFile, self->tempItemStore)) {
+    if (!Storage.openFileForRead("COF", self->cachePath + itemCacheFile, self->tempItemStore)) {
       Serial.printf(
           "[%lu] [COF] Couldn't open temp items file for reading. This is probably going to be a fatal error.\n",
           millis());
@@ -218,6 +219,11 @@ void XMLCALL ContentOpfParser::startElement(void* userData, const XML_Char* name
       }
     }
 
+    // Collect CSS files
+    if (mediaType == MEDIA_TYPE_CSS) {
+      self->cssFiles.push_back(href);
+    }
+
     // EPUB 3: Check for nav document (properties contains "nav")
     if (!properties.empty() && self->tocNavPath.empty()) {
       // Properties is space-separated, check if "nav" is present as a word
@@ -226,6 +232,14 @@ void XMLCALL ContentOpfParser::startElement(void* userData, const XML_Char* name
         Serial.printf("[%lu] [COF] Found EPUB 3 nav document: %s\n", millis(), href.c_str());
       }
     }
+
+    // EPUB 3: Check for cover image (properties contains "cover-image")
+    if (!properties.empty() && self->coverItemHref.empty()) {
+      if (properties == "cover-image" || properties.find("cover-image ") == 0 ||
+          properties.find(" cover-image") != std::string::npos) {
+        self->coverItemHref = href;
+      }
+    }
     return;
   }
 

lib/Epub/Epub/parsers/ContentOpfParser.h

@@ -64,6 +64,7 @@ class ContentOpfParser final : public Print {
   std::string tocNavPath;  // EPUB 3 nav document path
   std::string coverItemHref;
   std::string textReferenceHref;
+  std::vector<std::string> cssFiles;  // CSS stylesheet paths
 
   explicit ContentOpfParser(const std::string& cachePath, const std::string& baseContentPath, const size_t xmlSize,
                             BookMetadataCache* cache)

lib/GfxRenderer/Bitmap.h

@@ -1,6 +1,6 @@
 #pragma once
 
-#include <SdFat.h>
+#include <HalStorage.h>
 
 #include <cstdint>
 

lib/GfxRenderer/BitmapHelpers.cpp

@@ -104,3 +104,20 @@ uint8_t quantize1bit(int gray, int x, int y) {
   const int adjustedThreshold = 128 + ((threshold - 128) / 2);  // Range: 64-192
   return (gray >= adjustedThreshold) ? 1 : 0;
 }
+
+// Noise dithering for gradient fills - always uses hash-based noise regardless of global dithering config.
+// Produces smooth-looking gradients on the 4-level e-ink display.
+uint8_t quantizeNoiseDither(int gray, int x, int y) {
+  uint32_t hash = static_cast<uint32_t>(x) * 374761393u + static_cast<uint32_t>(y) * 668265263u;
+  hash = (hash ^ (hash >> 13)) * 1274126177u;
+  const int threshold = static_cast<int>(hash >> 24);
+
+  const int scaled = gray * 3;
+  if (scaled < 255) {
+    return (scaled + threshold >= 255) ? 1 : 0;
+  } else if (scaled < 510) {
+    return ((scaled - 255) + threshold >= 255) ? 2 : 1;
+  } else {
+    return ((scaled - 510) + threshold >= 255) ? 3 : 2;
+  }
+}

lib/GfxRenderer/BitmapHelpers.h

@@ -7,6 +7,7 @@ uint8_t quantize(int gray, int x, int y);
 uint8_t quantizeSimple(int gray);
 uint8_t quantize1bit(int gray, int x, int y);
 int adjustPixel(int gray);
+uint8_t quantizeNoiseDither(int gray, int x, int y);
 
 // 1-bit Atkinson dithering - better quality than noise dithering for thumbnails
 // Error distribution pattern (same as 2-bit but quantizes to 2 levels):

lib/GfxRenderer/GfxRenderer.cpp

@@ -2,61 +2,68 @@
 
 #include <Utf8.h>
 
+void GfxRenderer::begin() {
+  frameBuffer = display.getFrameBuffer();
+  if (!frameBuffer) {
+    Serial.printf("[%lu] [GFX] !! No framebuffer\n", millis());
+    assert(false);
+  }
+}
+
 void GfxRenderer::insertFont(const int fontId, EpdFontFamily font) { fontMap.insert({fontId, font}); }
 
-void GfxRenderer::rotateCoordinates(const int x, const int y, int* rotatedX, int* rotatedY) const {
+// Translate logical (x,y) coordinates to physical panel coordinates based on current orientation
+// This should always be inlined for better performance
+static inline void rotateCoordinates(const GfxRenderer::Orientation orientation, const int x, const int y, int* phyX,
+                                     int* phyY) {
   switch (orientation) {
-    case Portrait: {
+    case GfxRenderer::Portrait: {
       // Logical portrait (480x800) → panel (800x480)
       // Rotation: 90 degrees clockwise
-      *rotatedX = y;
-      *rotatedY = HalDisplay::DISPLAY_HEIGHT - 1 - x;
+      *phyX = y;
+      *phyY = HalDisplay::DISPLAY_HEIGHT - 1 - x;
       break;
     }
-    case LandscapeClockwise: {
+    case GfxRenderer::LandscapeClockwise: {
       // Logical landscape (800x480) rotated 180 degrees (swap top/bottom and left/right)
-      *rotatedX = HalDisplay::DISPLAY_WIDTH - 1 - x;
-      *rotatedY = HalDisplay::DISPLAY_HEIGHT - 1 - y;
+      *phyX = HalDisplay::DISPLAY_WIDTH - 1 - x;
+      *phyY = HalDisplay::DISPLAY_HEIGHT - 1 - y;
       break;
     }
-    case PortraitInverted: {
+    case GfxRenderer::PortraitInverted: {
       // Logical portrait (480x800) → panel (800x480)
       // Rotation: 90 degrees counter-clockwise
-      *rotatedX = HalDisplay::DISPLAY_WIDTH - 1 - y;
-      *rotatedY = x;
+      *phyX = HalDisplay::DISPLAY_WIDTH - 1 - y;
+      *phyY = x;
       break;
     }
-    case LandscapeCounterClockwise: {
+    case GfxRenderer::LandscapeCounterClockwise: {
       // Logical landscape (800x480) aligned with panel orientation
-      *rotatedX = x;
-      *rotatedY = y;
+      *phyX = x;
+      *phyY = y;
       break;
     }
   }
 }
 
+// IMPORTANT: This function is in critical rendering path and is called for every pixel. Please keep it as simple and
+// efficient as possible.
 void GfxRenderer::drawPixel(const int x, const int y, const bool state) const {
-  uint8_t* frameBuffer = display.getFrameBuffer();
+  int phyX = 0;
+  int phyY = 0;
 
-  // Early return if no framebuffer is set
-  if (!frameBuffer) {
-    Serial.printf("[%lu] [GFX] !! No framebuffer\n", millis());
-    return;
-  }
-
-  int rotatedX = 0;
-  int rotatedY = 0;
-  rotateCoordinates(x, y, &rotatedX, &rotatedY);
+  // Note: this call should be inlined for better performance
+  rotateCoordinates(orientation, x, y, &phyX, &phyY);
 
   // Bounds checking against physical panel dimensions
-  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);
+  if (phyX < 0 || phyX >= HalDisplay::DISPLAY_WIDTH || phyY < 0 || phyY >= HalDisplay::DISPLAY_HEIGHT) {
+    Serial.printf("[%lu] [GFX] !! Outside range (%d, %d) -> (%d, %d)\n", millis(), x, y, phyX, phyY);
     return;
   }
 
   // Calculate byte position and bit position
-  const uint16_t byteIndex = rotatedY * HalDisplay::DISPLAY_WIDTH_BYTES + (rotatedX / 8);
-  const uint8_t bitPosition = 7 - (rotatedX % 8);  // MSB first
+  const uint16_t byteIndex = phyY * HalDisplay::DISPLAY_WIDTH_BYTES + (phyX / 8);
+  const uint8_t bitPosition = 7 - (phyX % 8);  // MSB first
 
   if (state) {
     frameBuffer[byteIndex] &= ~(1 << bitPosition);  // Clear bit
@@ -65,6 +72,16 @@ void GfxRenderer::drawPixel(const int x, const int y, const bool state) const {
   }
 }
 
+void GfxRenderer::drawPixelGray(const int x, const int y, const uint8_t val2bit) const {
+  if (renderMode == BW && val2bit < 3) {
+    drawPixel(x, y);
+  } else if (renderMode == GRAYSCALE_MSB && (val2bit == 1 || val2bit == 2)) {
+    drawPixel(x, y, false);
+  } else if (renderMode == GRAYSCALE_LSB && val2bit == 1) {
+    drawPixel(x, y, false);
+  }
+}
+
 int GfxRenderer::getTextWidth(const int fontId, const char* text, const EpdFontFamily::Style style) const {
   if (fontMap.count(fontId) == 0) {
     Serial.printf("[%lu] [GFX] Font %d not found\n", millis(), fontId);
@@ -130,6 +147,12 @@ void GfxRenderer::drawLine(int x1, int y1, int x2, int y2, const bool state) con
   }
 }
 
+void GfxRenderer::drawLine(int x1, int y1, int x2, int y2, const int lineWidth, const bool state) const {
+  for (int i = 0; i < lineWidth; i++) {
+    drawLine(x1, y1 + i, x2, y2 + i, state);
+  }
+}
+
 void GfxRenderer::drawRect(const int x, const int y, const int width, const int height, const bool state) const {
   drawLine(x, y, x + width - 1, y, state);
   drawLine(x + width - 1, y, x + width - 1, y + height - 1, state);
@@ -137,16 +160,240 @@ void GfxRenderer::drawRect(const int x, const int y, const int width, const int
   drawLine(x, y, x, y + height - 1, state);
 }
 
+// Border is inside the rectangle
+void GfxRenderer::drawRect(const int x, const int y, const int width, const int height, const int lineWidth,
+                           const bool state) const {
+  for (int i = 0; i < lineWidth; i++) {
+    drawLine(x + i, y + i, x + width - i, y + i, state);
+    drawLine(x + width - i, y + i, x + width - i, y + height - i, state);
+    drawLine(x + width - i, y + height - i, x + i, y + height - i, state);
+    drawLine(x + i, y + height - i, x + i, y + i, state);
+  }
+}
+
+void GfxRenderer::drawArc(const int maxRadius, const int cx, const int cy, const int xDir, const int yDir,
+                          const int lineWidth, const bool state) const {
+  const int stroke = std::min(lineWidth, maxRadius);
+  const int innerRadius = std::max(maxRadius - stroke, 0);
+  const int outerRadiusSq = maxRadius * maxRadius;
+  const int innerRadiusSq = innerRadius * innerRadius;
+  for (int dy = 0; dy <= maxRadius; ++dy) {
+    for (int dx = 0; dx <= maxRadius; ++dx) {
+      const int distSq = dx * dx + dy * dy;
+      if (distSq > outerRadiusSq || distSq < innerRadiusSq) {
+        continue;
+      }
+      const int px = cx + xDir * dx;
+      const int py = cy + yDir * dy;
+      drawPixel(px, py, state);
+    }
+  }
+};
+
+// Border is inside the rectangle, rounded corners
+void GfxRenderer::drawRoundedRect(const int x, const int y, const int width, const int height, const int lineWidth,
+                                  const int cornerRadius, bool state) const {
+  drawRoundedRect(x, y, width, height, lineWidth, cornerRadius, true, true, true, true, state);
+}
+
+// Border is inside the rectangle, rounded corners
+void GfxRenderer::drawRoundedRect(const int x, const int y, const int width, const int height, const int lineWidth,
+                                  const int cornerRadius, bool roundTopLeft, bool roundTopRight, bool roundBottomLeft,
+                                  bool roundBottomRight, bool state) const {
+  if (lineWidth <= 0 || width <= 0 || height <= 0) {
+    return;
+  }
+
+  const int maxRadius = std::min({cornerRadius, width / 2, height / 2});
+  if (maxRadius <= 0) {
+    drawRect(x, y, width, height, lineWidth, state);
+    return;
+  }
+
+  const int stroke = std::min(lineWidth, maxRadius);
+  const int right = x + width - 1;
+  const int bottom = y + height - 1;
+
+  const int horizontalWidth = width - 2 * maxRadius;
+  if (horizontalWidth > 0) {
+    if (roundTopLeft || roundTopRight) {
+      fillRect(x + maxRadius, y, horizontalWidth, stroke, state);
+    }
+    if (roundBottomLeft || roundBottomRight) {
+      fillRect(x + maxRadius, bottom - stroke + 1, horizontalWidth, stroke, state);
+    }
+  }
+
+  const int verticalHeight = height - 2 * maxRadius;
+  if (verticalHeight > 0) {
+    if (roundTopLeft || roundBottomLeft) {
+      fillRect(x, y + maxRadius, stroke, verticalHeight, state);
+    }
+    if (roundTopRight || roundBottomRight) {
+      fillRect(right - stroke + 1, y + maxRadius, stroke, verticalHeight, state);
+    }
+  }
+
+  if (roundTopLeft) {
+    drawArc(maxRadius, x + maxRadius, y + maxRadius, -1, -1, lineWidth, state);
+  }
+  if (roundTopRight) {
+    drawArc(maxRadius, right - maxRadius, y + maxRadius, 1, -1, lineWidth, state);
+  }
+  if (roundBottomRight) {
+    drawArc(maxRadius, right - maxRadius, bottom - maxRadius, 1, 1, lineWidth, state);
+  }
+  if (roundBottomLeft) {
+    drawArc(maxRadius, x + maxRadius, bottom - maxRadius, -1, 1, lineWidth, state);
+  }
+}
+
 void GfxRenderer::fillRect(const int x, const int y, const int width, const int height, const bool state) const {
   for (int fillY = y; fillY < y + height; fillY++) {
     drawLine(x, fillY, x + width - 1, fillY, state);
   }
 }
 
+// NOTE: Those are in critical path, and need to be templated to avoid runtime checks for every pixel.
+// Any branching must be done outside the loops to avoid performance degradation.
+template <>
+void GfxRenderer::drawPixelDither<Color::Clear>(const int x, const int y) const {
+  // Do nothing
+}
+
+template <>
+void GfxRenderer::drawPixelDither<Color::Black>(const int x, const int y) const {
+  drawPixel(x, y, true);
+}
+
+template <>
+void GfxRenderer::drawPixelDither<Color::White>(const int x, const int y) const {
+  drawPixel(x, y, false);
+}
+
+template <>
+void GfxRenderer::drawPixelDither<Color::LightGray>(const int x, const int y) const {
+  drawPixel(x, y, x % 2 == 0 && y % 2 == 0);
+}
+
+template <>
+void GfxRenderer::drawPixelDither<Color::DarkGray>(const int x, const int y) const {
+  drawPixel(x, y, (x + y) % 2 == 0);  // TODO: maybe find a better pattern?
+}
+
+void GfxRenderer::fillRectDither(const int x, const int y, const int width, const int height, Color color) const {
+  if (color == Color::Clear) {
+  } else if (color == Color::Black) {
+    fillRect(x, y, width, height, true);
+  } else if (color == Color::White) {
+    fillRect(x, y, width, height, false);
+  } else if (color == Color::LightGray) {
+    for (int fillY = y; fillY < y + height; fillY++) {
+      for (int fillX = x; fillX < x + width; fillX++) {
+        drawPixelDither<Color::LightGray>(fillX, fillY);
+      }
+    }
+  } else if (color == Color::DarkGray) {
+    for (int fillY = y; fillY < y + height; fillY++) {
+      for (int fillX = x; fillX < x + width; fillX++) {
+        drawPixelDither<Color::DarkGray>(fillX, fillY);
+      }
+    }
+  }
+}
+
+template <Color color>
+void GfxRenderer::fillArc(const int maxRadius, const int cx, const int cy, const int xDir, const int yDir) const {
+  const int radiusSq = maxRadius * maxRadius;
+  for (int dy = 0; dy <= maxRadius; ++dy) {
+    for (int dx = 0; dx <= maxRadius; ++dx) {
+      const int distSq = dx * dx + dy * dy;
+      const int px = cx + xDir * dx;
+      const int py = cy + yDir * dy;
+      if (distSq <= radiusSq) {
+        drawPixelDither<color>(px, py);
+      }
+    }
+  }
+}
+
+void GfxRenderer::fillRoundedRect(const int x, const int y, const int width, const int height, const int cornerRadius,
+                                  const Color color) const {
+  fillRoundedRect(x, y, width, height, cornerRadius, true, true, true, true, color);
+}
+
+void GfxRenderer::fillRoundedRect(const int x, const int y, const int width, const int height, const int cornerRadius,
+                                  bool roundTopLeft, bool roundTopRight, bool roundBottomLeft, bool roundBottomRight,
+                                  const Color color) const {
+  if (width <= 0 || height <= 0) {
+    return;
+  }
+
+  const int maxRadius = std::min({cornerRadius, width / 2, height / 2});
+  if (maxRadius <= 0) {
+    fillRectDither(x, y, width, height, color);
+    return;
+  }
+
+  const int horizontalWidth = width - 2 * maxRadius;
+  if (horizontalWidth > 0) {
+    fillRectDither(x + maxRadius + 1, y, horizontalWidth - 2, height, color);
+  }
+
+  const int verticalHeight = height - 2 * maxRadius - 2;
+  if (verticalHeight > 0) {
+    fillRectDither(x, y + maxRadius + 1, maxRadius + 1, verticalHeight, color);
+    fillRectDither(x + width - maxRadius - 1, y + maxRadius + 1, maxRadius + 1, verticalHeight, color);
+  }
+
+  auto fillArcTemplated = [this](int maxRadius, int cx, int cy, int xDir, int yDir, Color color) {
+    switch (color) {
+      case Color::Clear:
+        break;
+      case Color::Black:
+        fillArc<Color::Black>(maxRadius, cx, cy, xDir, yDir);
+        break;
+      case Color::White:
+        fillArc<Color::White>(maxRadius, cx, cy, xDir, yDir);
+        break;
+      case Color::LightGray:
+        fillArc<Color::LightGray>(maxRadius, cx, cy, xDir, yDir);
+        break;
+      case Color::DarkGray:
+        fillArc<Color::DarkGray>(maxRadius, cx, cy, xDir, yDir);
+        break;
+    }
+  };
+
+  if (roundTopLeft) {
+    fillArcTemplated(maxRadius, x + maxRadius, y + maxRadius, -1, -1, color);
+  } else {
+    fillRectDither(x, y, maxRadius + 1, maxRadius + 1, color);
+  }
+
+  if (roundTopRight) {
+    fillArcTemplated(maxRadius, x + width - maxRadius - 1, y + maxRadius, 1, -1, color);
+  } else {
+    fillRectDither(x + width - maxRadius - 1, y, maxRadius + 1, maxRadius + 1, color);
+  }
+
+  if (roundBottomRight) {
+    fillArcTemplated(maxRadius, x + width - maxRadius - 1, y + height - maxRadius - 1, 1, 1, color);
+  } else {
+    fillRectDither(x + width - maxRadius - 1, y + height - maxRadius - 1, maxRadius + 1, maxRadius + 1, color);
+  }
+
+  if (roundBottomLeft) {
+    fillArcTemplated(maxRadius, x + maxRadius, y + height - maxRadius - 1, -1, 1, color);
+  } else {
+    fillRectDither(x, y + height - maxRadius - 1, maxRadius + 1, maxRadius + 1, color);
+  }
+}
+
 void GfxRenderer::drawImage(const uint8_t bitmap[], const int x, const int y, const int width, const int height) const {
   int rotatedX = 0;
   int rotatedY = 0;
-  rotateCoordinates(x, y, &rotatedX, &rotatedY);
+  rotateCoordinates(orientation, x, y, &rotatedX, &rotatedY);
   // Rotate origin corner
   switch (orientation) {
     case Portrait:
@@ -166,6 +413,10 @@ void GfxRenderer::drawImage(const uint8_t bitmap[], const int x, const int y, co
   display.drawImage(bitmap, rotatedX, rotatedY, width, height);
 }
 
+void GfxRenderer::drawIcon(const uint8_t bitmap[], const int x, const int y, const int width, const int height) const {
+  display.drawImage(bitmap, y, getScreenWidth() - width - x, height, width);
+}
+
 void GfxRenderer::drawBitmap(const Bitmap& bitmap, const int x, const int y, const int maxWidth, const int maxHeight,
                              const float cropX, const float cropY) const {
   // For 1-bit bitmaps, use optimized 1-bit rendering path (no crop support for 1-bit)
@@ -181,12 +432,20 @@ void GfxRenderer::drawBitmap(const Bitmap& bitmap, const int x, const int y, con
   Serial.printf("[%lu] [GFX] Cropping %dx%d by %dx%d pix, is %s\n", millis(), bitmap.getWidth(), bitmap.getHeight(),
                 cropPixX, cropPixY, bitmap.isTopDown() ? "top-down" : "bottom-up");
 
-  if (maxWidth > 0 && (1.0f - cropX) * bitmap.getWidth() > maxWidth) {
-    scale = static_cast<float>(maxWidth) / static_cast<float>((1.0f - cropX) * bitmap.getWidth());
+  const float effectiveWidth = (1.0f - cropX) * bitmap.getWidth();
+  const float effectiveHeight = (1.0f - cropY) * bitmap.getHeight();
+
+  // Calculate scale factor: supports both downscaling and upscaling when both constraints are provided
+  if (maxWidth > 0 && maxHeight > 0) {
+    const float scaleX = static_cast<float>(maxWidth) / effectiveWidth;
+    const float scaleY = static_cast<float>(maxHeight) / effectiveHeight;
+    scale = std::min(scaleX, scaleY);
+    isScaled = (scale < 0.999f || scale > 1.001f);
+  } else if (maxWidth > 0 && effectiveWidth > static_cast<float>(maxWidth)) {
+    scale = static_cast<float>(maxWidth) / effectiveWidth;
     isScaled = true;
-  }
-  if (maxHeight > 0 && (1.0f - cropY) * bitmap.getHeight() > maxHeight) {
-    scale = std::min(scale, static_cast<float>(maxHeight) / static_cast<float>((1.0f - cropY) * bitmap.getHeight()));
+  } else if (maxHeight > 0 && effectiveHeight > static_cast<float>(maxHeight)) {
+    scale = static_cast<float>(maxHeight) / effectiveHeight;
     isScaled = true;
   }
   Serial.printf("[%lu] [GFX] Scaling by %f - %s\n", millis(), scale, isScaled ? "scaled" : "not scaled");
@@ -207,12 +466,17 @@ void GfxRenderer::drawBitmap(const Bitmap& bitmap, const int x, const int y, con
   for (int bmpY = 0; bmpY < (bitmap.getHeight() - cropPixY); bmpY++) {
     // The BMP's (0, 0) is the bottom-left corner (if the height is positive, top-left if negative).
     // Screen's (0, 0) is the top-left corner.
-    int screenY = -cropPixY + (bitmap.isTopDown() ? bmpY : bitmap.getHeight() - 1 - bmpY);
+    const int logicalY = -cropPixY + (bitmap.isTopDown() ? bmpY : bitmap.getHeight() - 1 - bmpY);
+    int screenYStart, screenYEnd;
     if (isScaled) {
-      screenY = std::floor(screenY * scale);
+      screenYStart = static_cast<int>(std::floor(logicalY * scale)) + y;
+      screenYEnd = static_cast<int>(std::floor((logicalY + 1) * scale)) + y;
+    } else {
+      screenYStart = logicalY + y;
+      screenYEnd = screenYStart + 1;
     }
-    screenY += y;  // the offset should not be scaled
-    if (screenY >= getScreenHeight()) {
+
+    if (screenYStart >= getScreenHeight()) {
       break;
     }
 
@@ -223,7 +487,7 @@ void GfxRenderer::drawBitmap(const Bitmap& bitmap, const int x, const int y, con
       return;
     }
 
-    if (screenY < 0) {
+    if (screenYEnd <= 0) {
       continue;
     }
 
@@ -232,27 +496,42 @@ void GfxRenderer::drawBitmap(const Bitmap& bitmap, const int x, const int y, con
       continue;
     }
 
+    const int syStart = std::max(screenYStart, 0);
+    const int syEnd = std::min(screenYEnd, getScreenHeight());
+
     for (int bmpX = cropPixX; bmpX < bitmap.getWidth() - cropPixX; bmpX++) {
-      int screenX = bmpX - cropPixX;
+      const int outX = bmpX - cropPixX;
+      int screenXStart, screenXEnd;
       if (isScaled) {
-        screenX = std::floor(screenX * scale);
+        screenXStart = static_cast<int>(std::floor(outX * scale)) + x;
+        screenXEnd = static_cast<int>(std::floor((outX + 1) * scale)) + x;
+      } else {
+        screenXStart = outX + x;
+        screenXEnd = screenXStart + 1;
       }
-      screenX += x;  // the offset should not be scaled
-      if (screenX >= getScreenWidth()) {
+
+      if (screenXStart >= getScreenWidth()) {
         break;
       }
-      if (screenX < 0) {
+      if (screenXEnd <= 0) {
         continue;
       }
 
       const uint8_t val = outputRow[bmpX / 4] >> (6 - ((bmpX * 2) % 8)) & 0x3;
 
-      if (renderMode == BW && val < 3) {
-        drawPixel(screenX, screenY);
-      } else if (renderMode == GRAYSCALE_MSB && (val == 1 || val == 2)) {
-        drawPixel(screenX, screenY, false);
-      } else if (renderMode == GRAYSCALE_LSB && val == 1) {
-        drawPixel(screenX, screenY, false);
+      const int sxStart = std::max(screenXStart, 0);
+      const int sxEnd = std::min(screenXEnd, getScreenWidth());
+
+      for (int sy = syStart; sy < syEnd; sy++) {
+        for (int sx = sxStart; sx < sxEnd; sx++) {
+          if (renderMode == BW && val < 3) {
+            drawPixel(sx, sy);
+          } else if (renderMode == GRAYSCALE_MSB && (val == 1 || val == 2)) {
+            drawPixel(sx, sy, false);
+          } else if (renderMode == GRAYSCALE_LSB && val == 1) {
+            drawPixel(sx, sy, false);
+          }
+        }
       }
     }
   }
@@ -265,11 +544,16 @@ void GfxRenderer::drawBitmap1Bit(const Bitmap& bitmap, const int x, const int y,
                                  const int maxHeight) const {
   float scale = 1.0f;
   bool isScaled = false;
-  if (maxWidth > 0 && bitmap.getWidth() > maxWidth) {
+  // Calculate scale factor: supports both downscaling and upscaling when both constraints are provided
+  if (maxWidth > 0 && maxHeight > 0) {
+    const float scaleX = static_cast<float>(maxWidth) / static_cast<float>(bitmap.getWidth());
+    const float scaleY = static_cast<float>(maxHeight) / static_cast<float>(bitmap.getHeight());
+    scale = std::min(scaleX, scaleY);
+    isScaled = (scale < 0.999f || scale > 1.001f);
+  } else if (maxWidth > 0 && bitmap.getWidth() > maxWidth) {
     scale = static_cast<float>(maxWidth) / static_cast<float>(bitmap.getWidth());
     isScaled = true;
-  }
-  if (maxHeight > 0 && bitmap.getHeight() > maxHeight) {
+  } else if (maxHeight > 0 && bitmap.getHeight() > maxHeight) {
     scale = std::min(scale, static_cast<float>(maxHeight) / static_cast<float>(bitmap.getHeight()));
     isScaled = true;
   }
@@ -297,20 +581,37 @@ void GfxRenderer::drawBitmap1Bit(const Bitmap& bitmap, const int x, const int y,
 
     // Calculate screen Y based on whether BMP is top-down or bottom-up
     const int bmpYOffset = bitmap.isTopDown() ? bmpY : bitmap.getHeight() - 1 - bmpY;
-    int screenY = y + (isScaled ? static_cast<int>(std::floor(bmpYOffset * scale)) : bmpYOffset);
-    if (screenY >= getScreenHeight()) {
+    int screenYStart, screenYEnd;
+    if (isScaled) {
+      screenYStart = static_cast<int>(std::floor(bmpYOffset * scale)) + y;
+      screenYEnd = static_cast<int>(std::floor((bmpYOffset + 1) * scale)) + y;
+    } else {
+      screenYStart = bmpYOffset + y;
+      screenYEnd = screenYStart + 1;
+    }
+    if (screenYStart >= getScreenHeight()) {
       continue;  // Continue reading to keep row counter in sync
     }
-    if (screenY < 0) {
+    if (screenYEnd <= 0) {
       continue;
     }
 
+    const int syStart = std::max(screenYStart, 0);
+    const int syEnd = std::min(screenYEnd, getScreenHeight());
+
     for (int bmpX = 0; bmpX < bitmap.getWidth(); bmpX++) {
-      int screenX = x + (isScaled ? static_cast<int>(std::floor(bmpX * scale)) : bmpX);
-      if (screenX >= getScreenWidth()) {
+      int screenXStart, screenXEnd;
+      if (isScaled) {
+        screenXStart = static_cast<int>(std::floor(bmpX * scale)) + x;
+        screenXEnd = static_cast<int>(std::floor((bmpX + 1) * scale)) + x;
+      } else {
+        screenXStart = bmpX + x;
+        screenXEnd = screenXStart + 1;
+      }
+      if (screenXStart >= getScreenWidth()) {
         break;
       }
-      if (screenX < 0) {
+      if (screenXEnd <= 0) {
         continue;
       }
 
@@ -320,7 +621,13 @@ void GfxRenderer::drawBitmap1Bit(const Bitmap& bitmap, const int x, const int y,
       // For 1-bit source: 0 or 1 -> map to black (0,1,2) or white (3)
       // val < 3 means black pixel (draw it)
       if (val < 3) {
-        drawPixel(screenX, screenY, true);
+        const int sxStart = std::max(screenXStart, 0);
+        const int sxEnd = std::min(screenXEnd, getScreenWidth());
+        for (int sy = syStart; sy < syEnd; sy++) {
+          for (int sx = sxStart; sx < sxEnd; sx++) {
+            drawPixel(sx, sy, true);
+          }
+        }
       }
       // White pixels (val == 3) are not drawn (leave background)
     }
@@ -398,30 +705,43 @@ void GfxRenderer::fillPolygon(const int* xPoints, const int* yPoints, int numPoi
   free(nodeX);
 }
 
-void GfxRenderer::clearScreen(const uint8_t color) const { display.clearScreen(color); }
+// For performance measurement (using static to allow "const" methods)
+static unsigned long start_ms = 0;
+
+void GfxRenderer::clearScreen(const uint8_t color) const {
+  start_ms = millis();
+  display.clearScreen(color);
+}
 
 void GfxRenderer::invertScreen() const {
-  uint8_t* buffer = display.getFrameBuffer();
-  if (!buffer) {
-    Serial.printf("[%lu] [GFX] !! No framebuffer in invertScreen\n", millis());
-    return;
-  }
   for (int i = 0; i < HalDisplay::BUFFER_SIZE; i++) {
-    buffer[i] = ~buffer[i];
+    frameBuffer[i] = ~frameBuffer[i];
   }
 }
 
-void GfxRenderer::displayBuffer(const HalDisplay::RefreshMode refreshMode) const { display.displayBuffer(refreshMode); }
+void GfxRenderer::displayBuffer(const HalDisplay::RefreshMode refreshMode) const {
+  auto elapsed = millis() - start_ms;
+  Serial.printf("[%lu] [GFX] Time = %lu ms from clearScreen to displayBuffer\n", millis(), elapsed);
+  display.displayBuffer(refreshMode, fadingFix);
+}
 
 std::string GfxRenderer::truncatedText(const int fontId, const char* text, const int maxWidth,
                                        const EpdFontFamily::Style style) const {
+  if (!text || maxWidth <= 0) return "";
+
   std::string item = text;
-  int itemWidth = getTextWidth(fontId, item.c_str(), style);
-  while (itemWidth > maxWidth && item.length() > 8) {
-    item.replace(item.length() - 5, 5, "...");
-    itemWidth = getTextWidth(fontId, item.c_str(), style);
+  const char* ellipsis = "...";
+  int textWidth = getTextWidth(fontId, item.c_str(), style);
+  if (textWidth <= maxWidth) {
+    // Text fits, return as is
+    return item;
   }
-  return item;
+
+  while (!item.empty() && getTextWidth(fontId, (item + ellipsis).c_str(), style) >= maxWidth) {
+    utf8RemoveLastChar(item);
+  }
+
+  return item.empty() ? ellipsis : item + ellipsis;
 }
 
 // Note: Internal driver treats screen in command orientation; this library exposes a logical orientation
@@ -462,6 +782,20 @@ int GfxRenderer::getSpaceWidth(const int fontId) const {
   return fontMap.at(fontId).getGlyph(' ', EpdFontFamily::REGULAR)->advanceX;
 }
 
+int GfxRenderer::getTextAdvanceX(const int fontId, const char* text) const {
+  if (fontMap.count(fontId) == 0) {
+    Serial.printf("[%lu] [GFX] Font %d not found\n", millis(), fontId);
+    return 0;
+  }
+
+  uint32_t cp;
+  int width = 0;
+  while ((cp = utf8NextCodepoint(reinterpret_cast<const uint8_t**>(&text)))) {
+    width += fontMap.at(fontId).getGlyph(cp, EpdFontFamily::REGULAR)->advanceX;
+  }
+  return width;
+}
+
 int GfxRenderer::getFontAscenderSize(const int fontId) const {
   if (fontMap.count(fontId) == 0) {
     Serial.printf("[%lu] [GFX] Font %d not found\n", millis(), fontId);
@@ -480,85 +814,6 @@ int GfxRenderer::getLineHeight(const int fontId) const {
   return fontMap.at(fontId).getData(EpdFontFamily::REGULAR)->advanceY;
 }
 
-void GfxRenderer::drawButtonHints(const int fontId, const char* btn1, const char* btn2, const char* btn3,
-                                  const char* btn4) {
-  const Orientation orig_orientation = getOrientation();
-  setOrientation(Orientation::Portrait);
-
-  const int pageHeight = getScreenHeight();
-  constexpr int buttonWidth = 106;
-  constexpr int buttonHeight = 40;
-  constexpr int buttonY = 40;     // Distance from bottom
-  constexpr int textYOffset = 7;  // Distance from top of button to text baseline
-  constexpr int buttonPositions[] = {25, 130, 245, 350};
-  const char* labels[] = {btn1, btn2, btn3, btn4};
-
-  for (int i = 0; i < 4; i++) {
-    // Only draw if the label is non-empty
-    if (labels[i] != nullptr && labels[i][0] != '\0') {
-      const int x = buttonPositions[i];
-      fillRect(x, pageHeight - buttonY, buttonWidth, buttonHeight, false);
-      drawRect(x, pageHeight - buttonY, buttonWidth, buttonHeight);
-      const int textWidth = getTextWidth(fontId, labels[i]);
-      const int textX = x + (buttonWidth - 1 - textWidth) / 2;
-      drawText(fontId, textX, pageHeight - buttonY + textYOffset, labels[i]);
-    }
-  }
-
-  setOrientation(orig_orientation);
-}
-
-void GfxRenderer::drawSideButtonHints(const int fontId, const char* topBtn, const char* bottomBtn) const {
-  const int screenWidth = getScreenWidth();
-  constexpr int buttonWidth = 40;   // Width on screen (height when rotated)
-  constexpr int buttonHeight = 80;  // Height on screen (width when rotated)
-  constexpr int buttonX = 5;        // Distance from right edge
-  // Position for the button group - buttons share a border so they're adjacent
-  constexpr int topButtonY = 345;  // Top button position
-
-  const char* labels[] = {topBtn, bottomBtn};
-
-  // Draw the shared border for both buttons as one unit
-  const int x = screenWidth - buttonX - buttonWidth;
-
-  // Draw top button outline (3 sides, bottom open)
-  if (topBtn != nullptr && topBtn[0] != '\0') {
-    drawLine(x, topButtonY, x + buttonWidth - 1, topButtonY);                                       // Top
-    drawLine(x, topButtonY, x, topButtonY + buttonHeight - 1);                                      // Left
-    drawLine(x + buttonWidth - 1, topButtonY, x + buttonWidth - 1, topButtonY + buttonHeight - 1);  // Right
-  }
-
-  // Draw shared middle border
-  if ((topBtn != nullptr && topBtn[0] != '\0') || (bottomBtn != nullptr && bottomBtn[0] != '\0')) {
-    drawLine(x, topButtonY + buttonHeight, x + buttonWidth - 1, topButtonY + buttonHeight);  // Shared border
-  }
-
-  // Draw bottom button outline (3 sides, top is shared)
-  if (bottomBtn != nullptr && bottomBtn[0] != '\0') {
-    drawLine(x, topButtonY + buttonHeight, x, topButtonY + 2 * buttonHeight - 1);  // Left
-    drawLine(x + buttonWidth - 1, topButtonY + buttonHeight, x + buttonWidth - 1,
-             topButtonY + 2 * buttonHeight - 1);                                                             // Right
-    drawLine(x, topButtonY + 2 * buttonHeight - 1, x + buttonWidth - 1, topButtonY + 2 * buttonHeight - 1);  // Bottom
-  }
-
-  // Draw text for each button
-  for (int i = 0; i < 2; i++) {
-    if (labels[i] != nullptr && labels[i][0] != '\0') {
-      const int y = topButtonY + i * buttonHeight;
-
-      // Draw rotated text centered in the button
-      const int textWidth = getTextWidth(fontId, labels[i]);
-      const int textHeight = getTextHeight(fontId);
-
-      // Center the rotated text in the button
-      const int textX = x + (buttonWidth - textHeight) / 2;
-      const int textY = y + (buttonHeight + textWidth) / 2;
-
-      drawTextRotated90CW(fontId, textX, textY, labels[i]);
-    }
-  }
-}
-
 int GfxRenderer::getTextHeight(const int fontId) const {
   if (fontMap.count(fontId) == 0) {
     Serial.printf("[%lu] [GFX] Font %d not found\n", millis(), fontId);
@@ -650,18 +905,18 @@ void GfxRenderer::drawTextRotated90CW(const int fontId, const int x, const int y
   }
 }
 
-uint8_t* GfxRenderer::getFrameBuffer() const { return display.getFrameBuffer(); }
+uint8_t* GfxRenderer::getFrameBuffer() const { return frameBuffer; }
 
 size_t GfxRenderer::getBufferSize() { return HalDisplay::BUFFER_SIZE; }
 
 // unused
 // void GfxRenderer::grayscaleRevert() const { display.grayscaleRevert(); }
 
-void GfxRenderer::copyGrayscaleLsbBuffers() const { display.copyGrayscaleLsbBuffers(display.getFrameBuffer()); }
+void GfxRenderer::copyGrayscaleLsbBuffers() const { display.copyGrayscaleLsbBuffers(frameBuffer); }
 
-void GfxRenderer::copyGrayscaleMsbBuffers() const { display.copyGrayscaleMsbBuffers(display.getFrameBuffer()); }
+void GfxRenderer::copyGrayscaleMsbBuffers() const { display.copyGrayscaleMsbBuffers(frameBuffer); }
 
-void GfxRenderer::displayGrayBuffer() const { display.displayGrayBuffer(); }
+void GfxRenderer::displayGrayBuffer() const { display.displayGrayBuffer(fadingFix); }
 
 void GfxRenderer::freeBwBufferChunks() {
   for (auto& bwBufferChunk : bwBufferChunks) {
@@ -679,12 +934,6 @@ void GfxRenderer::freeBwBufferChunks() {
  * Returns true if buffer was stored successfully, false if allocation failed.
  */
 bool GfxRenderer::storeBwBuffer() {
-  const uint8_t* frameBuffer = display.getFrameBuffer();
-  if (!frameBuffer) {
-    Serial.printf("[%lu] [GFX] !! No framebuffer in storeBwBuffer\n", millis());
-    return false;
-  }
-
   // Allocate and copy each chunk
   for (size_t i = 0; i < BW_BUFFER_NUM_CHUNKS; i++) {
     // Check if any chunks are already allocated
@@ -734,13 +983,6 @@ void GfxRenderer::restoreBwBuffer() {
     return;
   }
 
-  uint8_t* frameBuffer = display.getFrameBuffer();
-  if (!frameBuffer) {
-    Serial.printf("[%lu] [GFX] !! No framebuffer in restoreBwBuffer\n", millis());
-    freeBwBufferChunks();
-    return;
-  }
-
   for (size_t i = 0; i < BW_BUFFER_NUM_CHUNKS; i++) {
     // Check if chunk is missing
     if (!bwBufferChunks[i]) {
@@ -764,7 +1006,6 @@ void GfxRenderer::restoreBwBuffer() {
  * Use this when BW buffer was re-rendered instead of stored/restored.
  */
 void GfxRenderer::cleanupGrayscaleWithFrameBuffer() const {
-  uint8_t* frameBuffer = display.getFrameBuffer();
   if (frameBuffer) {
     display.cleanupGrayscaleBuffers(frameBuffer);
   }

lib/GfxRenderer/GfxRenderer.h

@@ -7,6 +7,10 @@
 
 #include "Bitmap.h"
 
+// Color representation: uint8_t mapped to 4x4 Bayer matrix dithering levels
+// 0 = transparent, 1-16 = gray levels (white to black)
+enum Color : uint8_t { Clear = 0x00, White = 0x01, LightGray = 0x05, DarkGray = 0x0A, Black = 0x10 };
+
 class GfxRenderer {
  public:
   enum RenderMode { BW, GRAYSCALE_LSB, GRAYSCALE_MSB };
@@ -28,15 +32,21 @@ class GfxRenderer {
   HalDisplay& display;
   RenderMode renderMode;
   Orientation orientation;
+  bool fadingFix;
+  uint8_t* frameBuffer = nullptr;
   uint8_t* bwBufferChunks[BW_BUFFER_NUM_CHUNKS] = {nullptr};
   std::map<int, EpdFontFamily> fontMap;
   void renderChar(const EpdFontFamily& fontFamily, uint32_t cp, int* x, const int* y, bool pixelState,
                   EpdFontFamily::Style style) const;
   void freeBwBufferChunks();
-  void rotateCoordinates(int x, int y, int* rotatedX, int* rotatedY) const;
+  template <Color color>
+  void drawPixelDither(int x, int y) const;
+  template <Color color>
+  void fillArc(int maxRadius, int cx, int cy, int xDir, int yDir) const;
 
  public:
-  explicit GfxRenderer(HalDisplay& halDisplay) : display(halDisplay), renderMode(BW), orientation(Portrait) {}
+  explicit GfxRenderer(HalDisplay& halDisplay)
+      : display(halDisplay), renderMode(BW), orientation(Portrait), fadingFix(false) {}
   ~GfxRenderer() { freeBwBufferChunks(); }
 
   static constexpr int VIEWABLE_MARGIN_TOP = 9;
@@ -45,27 +55,44 @@ class GfxRenderer {
   static constexpr int VIEWABLE_MARGIN_LEFT = 3;
 
   // Setup
+  void begin();  // must be called right after display.begin()
   void insertFont(int fontId, EpdFontFamily font);
 
   // Orientation control (affects logical width/height and coordinate transforms)
   void setOrientation(const Orientation o) { orientation = o; }
   Orientation getOrientation() const { return orientation; }
 
+  // Fading fix control
+  void setFadingFix(const bool enabled) { fadingFix = enabled; }
+
   // Screen ops
   int getScreenWidth() const;
   int getScreenHeight() const;
   void displayBuffer(HalDisplay::RefreshMode refreshMode = HalDisplay::FAST_REFRESH) const;
   // EXPERIMENTAL: Windowed update - display only a rectangular region
-  void displayWindow(int x, int y, int width, int height) const;
+  // void displayWindow(int x, int y, int width, int height) const;
   void invertScreen() const;
   void clearScreen(uint8_t color = 0xFF) const;
+  void getOrientedViewableTRBL(int* outTop, int* outRight, int* outBottom, int* outLeft) const;
 
   // Drawing
   void drawPixel(int x, int y, bool state = true) const;
+  void drawPixelGray(int x, int y, uint8_t val2bit) const;
   void drawLine(int x1, int y1, int x2, int y2, bool state = true) const;
+  void drawLine(int x1, int y1, int x2, int y2, int lineWidth, bool state) const;
+  void drawArc(int maxRadius, int cx, int cy, int xDir, int yDir, int lineWidth, bool state) const;
   void drawRect(int x, int y, int width, int height, bool state = true) const;
+  void drawRect(int x, int y, int width, int height, int lineWidth, bool state) const;
+  void drawRoundedRect(int x, int y, int width, int height, int lineWidth, int cornerRadius, bool state) const;
+  void drawRoundedRect(int x, int y, int width, int height, int lineWidth, int cornerRadius, bool roundTopLeft,
+                       bool roundTopRight, bool roundBottomLeft, bool roundBottomRight, bool state) const;
   void fillRect(int x, int y, int width, int height, bool state = true) const;
+  void fillRectDither(int x, int y, int width, int height, Color color) const;
+  void fillRoundedRect(int x, int y, int width, int height, int cornerRadius, Color color) const;
+  void fillRoundedRect(int x, int y, int width, int height, int cornerRadius, bool roundTopLeft, bool roundTopRight,
+                       bool roundBottomLeft, bool roundBottomRight, Color color) const;
   void drawImage(const uint8_t bitmap[], int x, int y, int width, int height) const;
+  void drawIcon(const uint8_t bitmap[], int x, int y, int width, int height) const;
   void drawBitmap(const Bitmap& bitmap, int x, int y, int maxWidth, int maxHeight, float cropX = 0,
                   float cropY = 0) const;
   void drawBitmap1Bit(const Bitmap& bitmap, int x, int y, int maxWidth, int maxHeight) const;
@@ -78,22 +105,17 @@ class GfxRenderer {
   void drawText(int fontId, int x, int y, const char* text, bool black = true,
                 EpdFontFamily::Style style = EpdFontFamily::REGULAR) const;
   int getSpaceWidth(int fontId) const;
+  int getTextAdvanceX(int fontId, const char* text) const;
   int getFontAscenderSize(int fontId) const;
   int getLineHeight(int fontId) const;
   std::string truncatedText(int fontId, const char* text, int maxWidth,
                             EpdFontFamily::Style style = EpdFontFamily::REGULAR) const;
 
-  // UI Components
-  void drawButtonHints(int fontId, const char* btn1, const char* btn2, const char* btn3, const char* btn4);
-  void drawSideButtonHints(int fontId, const char* topBtn, const char* bottomBtn) const;
-
- private:
   // Helper for drawing rotated text (90 degrees clockwise, for side buttons)
   void drawTextRotated90CW(int fontId, int x, int y, const char* text, bool black = true,
                            EpdFontFamily::Style style = EpdFontFamily::REGULAR) const;
   int getTextHeight(int fontId) const;
 
- public:
   // Grayscale functions
   void setRenderMode(const RenderMode mode) { this->renderMode = mode; }
   void copyGrayscaleLsbBuffers() const;
@@ -106,6 +128,4 @@ class GfxRenderer {
   // Low level functions
   uint8_t* getFrameBuffer() const;
   static size_t getBufferSize();
-  void grayscaleRevert() const;
-  void getOrientedViewableTRBL(int* outTop, int* outRight, int* outBottom, int* outLeft) const;
 };

lib/JpegToBmpConverter/JpegToBmpConverter.cpp

@@ -1,7 +1,7 @@
 #include "JpegToBmpConverter.h"
 
+#include <HalStorage.h>
 #include <HardwareSerial.h>
-#include <SdFat.h>
 #include <picojpeg.h>
 
 #include <cstdio>
@@ -567,5 +567,5 @@ bool JpegToBmpConverter::jpegFileToBmpStreamWithSize(FsFile& jpegFile, Print& bm
 // Convert to 1-bit BMP (black and white only, no grays) for fast home screen rendering
 bool JpegToBmpConverter::jpegFileTo1BitBmpStreamWithSize(FsFile& jpegFile, Print& bmpOut, int targetMaxWidth,
                                                          int targetMaxHeight) {
-  return jpegFileToBmpStreamInternal(jpegFile, bmpOut, targetMaxWidth, targetMaxHeight, true);
+  return jpegFileToBmpStreamInternal(jpegFile, bmpOut, targetMaxWidth, targetMaxHeight, true, true);
 }

lib/KOReaderSync/KOReaderCredentialStore.cpp

@@ -1,8 +1,8 @@
 #include "KOReaderCredentialStore.h"
 
+#include <HalStorage.h>
 #include <HardwareSerial.h>
 #include <MD5Builder.h>
-#include <SDCardManager.h>
 #include <Serialization.h>
 
 // Initialize the static instance
@@ -32,10 +32,10 @@ void KOReaderCredentialStore::obfuscate(std::string& data) const {
 
 bool KOReaderCredentialStore::saveToFile() const {
   // Make sure the directory exists
-  SdMan.mkdir("/.crosspoint");
+  Storage.mkdir("/.crosspoint");
 
   FsFile file;
-  if (!SdMan.openFileForWrite("KRS", KOREADER_FILE, file)) {
+  if (!Storage.openFileForWrite("KRS", KOREADER_FILE, file)) {
     return false;
   }
 
@@ -64,7 +64,7 @@ bool KOReaderCredentialStore::saveToFile() const {
 
 bool KOReaderCredentialStore::loadFromFile() {
   FsFile file;
-  if (!SdMan.openFileForRead("KRS", KOREADER_FILE, file)) {
+  if (!Storage.openFileForRead("KRS", KOREADER_FILE, file)) {
     Serial.printf("[%lu] [KRS] No credentials file found\n", millis());
     return false;
   }

lib/KOReaderSync/KOReaderDocumentId.cpp

@@ -1,8 +1,8 @@
 #include "KOReaderDocumentId.h"
 
+#include <HalStorage.h>
 #include <HardwareSerial.h>
 #include <MD5Builder.h>
-#include <SDCardManager.h>
 
 namespace {
 // Extract filename from path (everything after last '/')
@@ -43,7 +43,7 @@ size_t KOReaderDocumentId::getOffset(int i) {
 
 std::string KOReaderDocumentId::calculate(const std::string& filePath) {
   FsFile file;
-  if (!SdMan.openFileForRead("KODoc", filePath, file)) {
+  if (!Storage.openFileForRead("KODoc", filePath, file)) {
     Serial.printf("[%lu] [KODoc] Failed to open file: %s\n", millis(), filePath.c_str());
     return "";
   }

lib/KOReaderSync/KOReaderSyncClient.cpp

@@ -19,6 +19,10 @@ void addAuthHeaders(HTTPClient& http) {
   http.addHeader("Accept", "application/vnd.koreader.v1+json");
   http.addHeader("x-auth-user", KOREADER_STORE.getUsername().c_str());
   http.addHeader("x-auth-key", KOREADER_STORE.getMd5Password().c_str());
+
+  // HTTP Basic Auth (RFC 7617) header. This is needed to support koreader sync server embedded in Calibre Web Automated
+  // (https://github.com/crocodilestick/Calibre-Web-Automated/blob/main/cps/progress_syncing/protocols/kosync.py)
+  http.setAuthorization(KOREADER_STORE.getUsername().c_str(), KOREADER_STORE.getPassword().c_str());
 }
 
 bool isHttpsUrl(const std::string& url) { return url.rfind("https://", 0) == 0; }

lib/Serialization/Serialization.h

@@ -1,5 +1,5 @@
 #pragma once
-#include <SdFat.h>
+#include <HalStorage.h>
 
 #include <iostream>
 

lib/Txt/Txt.cpp

@@ -15,13 +15,13 @@ bool Txt::load() {
     return true;
   }
 
-  if (!SdMan.exists(filepath.c_str())) {
+  if (!Storage.exists(filepath.c_str())) {
     Serial.printf("[%lu] [TXT] File does not exist: %s\n", millis(), filepath.c_str());
     return false;
   }
 
   FsFile file;
-  if (!SdMan.openFileForRead("TXT", filepath, file)) {
+  if (!Storage.openFileForRead("TXT", filepath, file)) {
     Serial.printf("[%lu] [TXT] Failed to open file: %s\n", millis(), filepath.c_str());
     return false;
   }
@@ -48,11 +48,11 @@ std::string Txt::getTitle() const {
 }
 
 void Txt::setupCacheDir() const {
-  if (!SdMan.exists(cacheBasePath.c_str())) {
-    SdMan.mkdir(cacheBasePath.c_str());
+  if (!Storage.exists(cacheBasePath.c_str())) {
+    Storage.mkdir(cacheBasePath.c_str());
   }
-  if (!SdMan.exists(cachePath.c_str())) {
-    SdMan.mkdir(cachePath.c_str());
+  if (!Storage.exists(cachePath.c_str())) {
+    Storage.mkdir(cachePath.c_str());
   }
 }
 
@@ -73,7 +73,7 @@ std::string Txt::findCoverImage() const {
   // First priority: look for image with same name as txt file (e.g., mybook.jpg)
   for (const auto& ext : extensions) {
     std::string coverPath = folder + "/" + baseName + ext;
-    if (SdMan.exists(coverPath.c_str())) {
+    if (Storage.exists(coverPath.c_str())) {
       Serial.printf("[%lu] [TXT] Found matching cover image: %s\n", millis(), coverPath.c_str());
       return coverPath;
     }
@@ -84,7 +84,7 @@ std::string Txt::findCoverImage() const {
   for (const auto& name : coverNames) {
     for (const auto& ext : extensions) {
       std::string coverPath = folder + "/" + std::string(name) + ext;
-      if (SdMan.exists(coverPath.c_str())) {
+      if (Storage.exists(coverPath.c_str())) {
         Serial.printf("[%lu] [TXT] Found fallback cover image: %s\n", millis(), coverPath.c_str());
         return coverPath;
       }
@@ -98,7 +98,7 @@ std::string Txt::getCoverBmpPath() const { return cachePath + "/cover.bmp"; }
 
 bool Txt::generateCoverBmp() const {
   // Already generated, return true
-  if (SdMan.exists(getCoverBmpPath().c_str())) {
+  if (Storage.exists(getCoverBmpPath().c_str())) {
     return true;
   }
 
@@ -122,10 +122,10 @@ bool Txt::generateCoverBmp() const {
     // Copy BMP file to cache
     Serial.printf("[%lu] [TXT] Copying BMP cover image to cache\n", millis());
     FsFile src, dst;
-    if (!SdMan.openFileForRead("TXT", coverImagePath, src)) {
+    if (!Storage.openFileForRead("TXT", coverImagePath, src)) {
       return false;
     }
-    if (!SdMan.openFileForWrite("TXT", getCoverBmpPath(), dst)) {
+    if (!Storage.openFileForWrite("TXT", getCoverBmpPath(), dst)) {
       src.close();
       return false;
     }
@@ -144,10 +144,10 @@ bool Txt::generateCoverBmp() const {
     // Convert JPG/JPEG to BMP (same approach as Epub)
     Serial.printf("[%lu] [TXT] Generating BMP from JPG cover image\n", millis());
     FsFile coverJpg, coverBmp;
-    if (!SdMan.openFileForRead("TXT", coverImagePath, coverJpg)) {
+    if (!Storage.openFileForRead("TXT", coverImagePath, coverJpg)) {
       return false;
     }
-    if (!SdMan.openFileForWrite("TXT", getCoverBmpPath(), coverBmp)) {
+    if (!Storage.openFileForWrite("TXT", getCoverBmpPath(), coverBmp)) {
       coverJpg.close();
       return false;
     }
@@ -157,7 +157,7 @@ bool Txt::generateCoverBmp() const {
 
     if (!success) {
       Serial.printf("[%lu] [TXT] Failed to generate BMP from JPG cover image\n", millis());
-      SdMan.remove(getCoverBmpPath().c_str());
+      Storage.remove(getCoverBmpPath().c_str());
     } else {
       Serial.printf("[%lu] [TXT] Generated BMP from JPG cover image\n", millis());
     }
@@ -175,7 +175,7 @@ bool Txt::readContent(uint8_t* buffer, size_t offset, size_t length) const {
   }
 
   FsFile file;
-  if (!SdMan.openFileForRead("TXT", filepath, file)) {
+  if (!Storage.openFileForRead("TXT", filepath, file)) {
     return false;
   }
 

lib/Txt/Txt.h

@@ -1,6 +1,6 @@
 #pragma once
 
-#include <SDCardManager.h>
+#include <HalStorage.h>
 
 #include <memory>
 #include <string>

lib/Utf8/Utf8.cpp

@@ -29,3 +29,20 @@ uint32_t utf8NextCodepoint(const unsigned char** string) {
 
   return cp;
 }
+
+size_t utf8RemoveLastChar(std::string& str) {
+  if (str.empty()) return 0;
+  size_t pos = str.size() - 1;
+  while (pos > 0 && (static_cast<unsigned char>(str[pos]) & 0xC0) == 0x80) {
+    --pos;
+  }
+  str.resize(pos);
+  return pos;
+}
+
+// Truncate string by removing N UTF-8 characters from the end
+void utf8TruncateChars(std::string& str, const size_t numChars) {
+  for (size_t i = 0; i < numChars && !str.empty(); ++i) {
+    utf8RemoveLastChar(str);
+  }
+}

lib/Utf8/Utf8.h

@@ -1,7 +1,11 @@
 #pragma once
 
 #include <cstdint>
-
+#include <string>
 #define REPLACEMENT_GLYPH 0xFFFD
 
 uint32_t utf8NextCodepoint(const unsigned char** string);
+// Remove the last UTF-8 codepoint from a std::string and return the new size.
+size_t utf8RemoveLastChar(std::string& str);
+// Truncate string by removing N UTF-8 codepoints from the end.
+void utf8TruncateChars(std::string& str, size_t numChars);

lib/Xtc/Xtc.cpp

@@ -7,8 +7,8 @@
 
 #include "Xtc.h"
 
+#include <HalStorage.h>
 #include <HardwareSerial.h>
-#include <SDCardManager.h>
 
 bool Xtc::load() {
   Serial.printf("[%lu] [XTC] Loading XTC: %s\n", millis(), filepath.c_str());
@@ -30,12 +30,12 @@ bool Xtc::load() {
 }
 
 bool Xtc::clearCache() const {
-  if (!SdMan.exists(cachePath.c_str())) {
+  if (!Storage.exists(cachePath.c_str())) {
     Serial.printf("[%lu] [XTC] Cache does not exist, no action needed\n", millis());
     return true;
   }
 
-  if (!SdMan.removeDir(cachePath.c_str())) {
+  if (!Storage.removeDir(cachePath.c_str())) {
     Serial.printf("[%lu] [XTC] Failed to clear cache\n", millis());
     return false;
   }
@@ -45,17 +45,17 @@ bool Xtc::clearCache() const {
 }
 
 void Xtc::setupCacheDir() const {
-  if (SdMan.exists(cachePath.c_str())) {
+  if (Storage.exists(cachePath.c_str())) {
     return;
   }
 
   // Create directories recursively
   for (size_t i = 1; i < cachePath.length(); i++) {
     if (cachePath[i] == '/') {
-      SdMan.mkdir(cachePath.substr(0, i).c_str());
+      Storage.mkdir(cachePath.substr(0, i).c_str());
     }
   }
-  SdMan.mkdir(cachePath.c_str());
+  Storage.mkdir(cachePath.c_str());
 }
 
 std::string Xtc::getTitle() const {
@@ -114,7 +114,7 @@ std::string Xtc::getCoverBmpPath() const { return cachePath + "/cover.bmp"; }
 
 bool Xtc::generateCoverBmp() const {
   // Already generated
-  if (SdMan.exists(getCoverBmpPath().c_str())) {
+  if (Storage.exists(getCoverBmpPath().c_str())) {
     return true;
   }
 
@@ -166,7 +166,7 @@ bool Xtc::generateCoverBmp() const {
 
   // Create BMP file
   FsFile coverBmp;
-  if (!SdMan.openFileForWrite("XTC", getCoverBmpPath(), coverBmp)) {
+  if (!Storage.openFileForWrite("XTC", getCoverBmpPath(), coverBmp)) {
     Serial.printf("[%lu] [XTC] Failed to create cover BMP file\n", millis());
     free(pageBuffer);
     return false;
@@ -301,11 +301,12 @@ bool Xtc::generateCoverBmp() const {
   return true;
 }
 
-std::string Xtc::getThumbBmpPath() const { return cachePath + "/thumb.bmp"; }
+std::string Xtc::getThumbBmpPath() const { return cachePath + "/thumb_[HEIGHT].bmp"; }
+std::string Xtc::getThumbBmpPath(int height) const { return cachePath + "/thumb_" + std::to_string(height) + ".bmp"; }
 
-bool Xtc::generateThumbBmp() const {
+bool Xtc::generateThumbBmp(int height) const {
   // Already generated
-  if (SdMan.exists(getThumbBmpPath().c_str())) {
+  if (Storage.exists(getThumbBmpPath(height).c_str())) {
     return true;
   }
 
@@ -333,13 +334,13 @@ bool Xtc::generateThumbBmp() const {
   const uint8_t bitDepth = parser->getBitDepth();
 
   // Calculate target dimensions for thumbnail (fit within 240x400 Continue Reading card)
-  constexpr int THUMB_TARGET_WIDTH = 240;
-  constexpr int THUMB_TARGET_HEIGHT = 400;
+  int THUMB_TARGET_WIDTH = height * 0.6;
+  int THUMB_TARGET_HEIGHT = height;
 
   // Calculate scale factor
   float scaleX = static_cast<float>(THUMB_TARGET_WIDTH) / pageInfo.width;
   float scaleY = static_cast<float>(THUMB_TARGET_HEIGHT) / pageInfo.height;
-  float scale = (scaleX < scaleY) ? scaleX : scaleY;
+  float scale = (scaleX > scaleY) ? scaleX : scaleY;  // for cropping
 
   // Only scale down, never up
   if (scale >= 1.0f) {
@@ -347,8 +348,8 @@ bool Xtc::generateThumbBmp() const {
     // Copy cover.bmp to thumb.bmp
     if (generateCoverBmp()) {
       FsFile src, dst;
-      if (SdMan.openFileForRead("XTC", getCoverBmpPath(), src)) {
-        if (SdMan.openFileForWrite("XTC", getThumbBmpPath(), dst)) {
+      if (Storage.openFileForRead("XTC", getCoverBmpPath(), src)) {
+        if (Storage.openFileForWrite("XTC", getThumbBmpPath(height), dst)) {
           uint8_t buffer[512];
           while (src.available()) {
             size_t bytesRead = src.read(buffer, sizeof(buffer));
@@ -359,7 +360,7 @@ bool Xtc::generateThumbBmp() const {
         src.close();
       }
       Serial.printf("[%lu] [XTC] Copied cover to thumb (no scaling needed)\n", millis());
-      return SdMan.exists(getThumbBmpPath().c_str());
+      return Storage.exists(getThumbBmpPath(height).c_str());
     }
     return false;
   }
@@ -393,7 +394,7 @@ bool Xtc::generateThumbBmp() const {
 
   // Create thumbnail BMP file - use 1-bit format for fast home screen rendering (no gray passes)
   FsFile thumbBmp;
-  if (!SdMan.openFileForWrite("XTC", getThumbBmpPath(), thumbBmp)) {
+  if (!Storage.openFileForWrite("XTC", getThumbBmpPath(height), thumbBmp)) {
     Serial.printf("[%lu] [XTC] Failed to create thumb BMP file\n", millis());
     free(pageBuffer);
     return false;
@@ -558,7 +559,7 @@ bool Xtc::generateThumbBmp() const {
   free(pageBuffer);
 
   Serial.printf("[%lu] [XTC] Generated thumb BMP (%dx%d): %s\n", millis(), thumbWidth, thumbHeight,
-                getThumbBmpPath().c_str());
+                getThumbBmpPath(height).c_str());
   return true;
 }
 

lib/Xtc/Xtc.h

@@ -65,7 +65,8 @@ class Xtc {
   bool generateCoverBmp() const;
   // Thumbnail support (for Continue Reading card)
   std::string getThumbBmpPath() const;
-  bool generateThumbBmp() const;
+  std::string getThumbBmpPath(int height) const;
+  bool generateThumbBmp(int height) const;
 
   // Page access
   uint32_t getPageCount() const;

lib/Xtc/Xtc/XtcParser.cpp

@@ -8,8 +8,8 @@
 #include "XtcParser.h"
 
 #include <FsHelpers.h>
+#include <HalStorage.h>
 #include <HardwareSerial.h>
-#include <SDCardManager.h>
 
 #include <cstring>
 
@@ -34,7 +34,7 @@ XtcError XtcParser::open(const char* filepath) {
   }
 
   // Open file
-  if (!SdMan.openFileForRead("XTC", filepath, m_file)) {
+  if (!Storage.openFileForRead("XTC", filepath, m_file)) {
     m_lastError = XtcError::FILE_NOT_FOUND;
     return m_lastError;
   }
@@ -444,7 +444,7 @@ XtcError XtcParser::loadPageStreaming(uint32_t pageIndex,
 
 bool XtcParser::isValidXtcFile(const char* filepath) {
   FsFile file;
-  if (!SdMan.openFileForRead("XTC", filepath, file)) {
+  if (!Storage.openFileForRead("XTC", filepath, file)) {
     return false;
   }
 

lib/Xtc/Xtc/XtcParser.h

@@ -7,7 +7,7 @@
 
 #pragma once
 
-#include <SdFat.h>
+#include <HalStorage.h>
 
 #include <functional>
 #include <memory>

lib/ZipFile/ZipFile.cpp

@@ -1,7 +1,7 @@
 #include "ZipFile.h"
 
+#include <HalStorage.h>
 #include <HardwareSerial.h>
-#include <SDCardManager.h>
 #include <miniz.h>
 
 #include <algorithm>
@@ -279,7 +279,7 @@ bool ZipFile::loadZipDetails() {
 }
 
 bool ZipFile::open() {
-  if (!SdMan.openFileForRead("ZIP", filePath, file)) {
+  if (!Storage.openFileForRead("ZIP", filePath, file)) {
     return false;
   }
   return true;

lib/ZipFile/ZipFile.h

@@ -1,5 +1,5 @@
 #pragma once
-#include <SdFat.h>
+#include <HalStorage.h>
 
 #include <string>
 #include <unordered_map>

lib/hal/HalDisplay.cpp

@@ -28,7 +28,9 @@ EInkDisplay::RefreshMode convertRefreshMode(HalDisplay::RefreshMode mode) {
   }
 }
 
-void HalDisplay::displayBuffer(HalDisplay::RefreshMode mode) { einkDisplay.displayBuffer(convertRefreshMode(mode)); }
+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);
@@ -48,4 +50,4 @@ void HalDisplay::copyGrayscaleMsbBuffers(const uint8_t* msbBuffer) { einkDisplay
 
 void HalDisplay::cleanupGrayscaleBuffers(const uint8_t* bwBuffer) { einkDisplay.cleanupGrayscaleBuffers(bwBuffer); }
 
-void HalDisplay::displayGrayBuffer() { einkDisplay.displayGrayBuffer(); }
+void HalDisplay::displayGrayBuffer(bool turnOffScreen) { einkDisplay.displayGrayBuffer(turnOffScreen); }

lib/hal/HalDisplay.h

@@ -31,7 +31,7 @@ class HalDisplay {
   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);
+  void displayBuffer(RefreshMode mode = RefreshMode::FAST_REFRESH, bool turnOffScreen = false);
   void refreshDisplay(RefreshMode mode = RefreshMode::FAST_REFRESH, bool turnOffScreen = false);
 
   // Power management
@@ -45,7 +45,7 @@ class HalDisplay {
   void copyGrayscaleMsbBuffers(const uint8_t* msbBuffer);
   void cleanupGrayscaleBuffers(const uint8_t* bwBuffer);
 
-  void displayGrayBuffer();
+  void displayGrayBuffer(bool turnOffScreen = false);
 
  private:
   EInkDisplay einkDisplay;

lib/hal/HalGPIO.cpp

@@ -24,12 +24,13 @@ 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();
   }
+  // Arm the wakeup trigger *after* the button is released
+  esp_deep_sleep_enable_gpio_wakeup(1ULL << InputManager::POWER_BUTTON_PIN, ESP_GPIO_WAKEUP_GPIO_LOW);
   // Enter Deep Sleep
   esp_deep_sleep_start();
 }
@@ -44,12 +45,20 @@ bool HalGPIO::isUsbConnected() const {
   return digitalRead(UART0_RXD) == HIGH;
 }
 
-bool HalGPIO::isWakeupByPowerButton() const {
+HalGPIO::WakeupReason HalGPIO::getWakeupReason() const {
+  const bool usbConnected = isUsbConnected();
   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);
+
+  if ((wakeupCause == ESP_SLEEP_WAKEUP_UNDEFINED && resetReason == ESP_RST_POWERON && !usbConnected) ||
+      (wakeupCause == ESP_SLEEP_WAKEUP_GPIO && resetReason == ESP_RST_DEEPSLEEP && usbConnected)) {
+    return WakeupReason::PowerButton;
   }
-}
+  if (wakeupCause == ESP_SLEEP_WAKEUP_UNDEFINED && resetReason == ESP_RST_UNKNOWN && usbConnected) {
+    return WakeupReason::AfterFlash;
+  }
+  if (wakeupCause == ESP_SLEEP_WAKEUP_UNDEFINED && resetReason == ESP_RST_POWERON && usbConnected) {
+    return WakeupReason::AfterUSBPower;
+  }
+  return WakeupReason::Other;
+}

lib/hal/HalGPIO.h

@@ -47,8 +47,9 @@ class HalGPIO {
   // Check if USB is connected
   bool isUsbConnected() const;
 
-  // Check if wakeup was caused by power button press
-  bool isWakeupByPowerButton() const;
+  enum class WakeupReason { PowerButton, AfterFlash, AfterUSBPower, Other };
+
+  WakeupReason getWakeupReason() const;
 
   // Button indices
   static constexpr uint8_t BTN_BACK = 0;

lib/hal/HalStorage.cpp

@@ -0,0 +1,65 @@
+#include "HalStorage.h"
+
+#include <SDCardManager.h>
+
+#define SDCard SDCardManager::getInstance()
+
+HalStorage HalStorage::instance;
+
+HalStorage::HalStorage() {}
+
+bool HalStorage::begin() { return SDCard.begin(); }
+
+bool HalStorage::ready() const { return SDCard.ready(); }
+
+std::vector<String> HalStorage::listFiles(const char* path, int maxFiles) { return SDCard.listFiles(path, maxFiles); }
+
+String HalStorage::readFile(const char* path) { return SDCard.readFile(path); }
+
+bool HalStorage::readFileToStream(const char* path, Print& out, size_t chunkSize) {
+  return SDCard.readFileToStream(path, out, chunkSize);
+}
+
+size_t HalStorage::readFileToBuffer(const char* path, char* buffer, size_t bufferSize, size_t maxBytes) {
+  return SDCard.readFileToBuffer(path, buffer, bufferSize, maxBytes);
+}
+
+bool HalStorage::writeFile(const char* path, const String& content) { return SDCard.writeFile(path, content); }
+
+bool HalStorage::ensureDirectoryExists(const char* path) { return SDCard.ensureDirectoryExists(path); }
+
+FsFile HalStorage::open(const char* path, const oflag_t oflag) { return SDCard.open(path, oflag); }
+
+bool HalStorage::mkdir(const char* path, const bool pFlag) { return SDCard.mkdir(path, pFlag); }
+
+bool HalStorage::exists(const char* path) { return SDCard.exists(path); }
+
+bool HalStorage::remove(const char* path) { return SDCard.remove(path); }
+
+bool HalStorage::rmdir(const char* path) { return SDCard.rmdir(path); }
+
+bool HalStorage::openFileForRead(const char* moduleName, const char* path, FsFile& file) {
+  return SDCard.openFileForRead(moduleName, path, file);
+}
+
+bool HalStorage::openFileForRead(const char* moduleName, const std::string& path, FsFile& file) {
+  return openFileForRead(moduleName, path.c_str(), file);
+}
+
+bool HalStorage::openFileForRead(const char* moduleName, const String& path, FsFile& file) {
+  return openFileForRead(moduleName, path.c_str(), file);
+}
+
+bool HalStorage::openFileForWrite(const char* moduleName, const char* path, FsFile& file) {
+  return SDCard.openFileForWrite(moduleName, path, file);
+}
+
+bool HalStorage::openFileForWrite(const char* moduleName, const std::string& path, FsFile& file) {
+  return openFileForWrite(moduleName, path.c_str(), file);
+}
+
+bool HalStorage::openFileForWrite(const char* moduleName, const String& path, FsFile& file) {
+  return openFileForWrite(moduleName, path.c_str(), file);
+}
+
+bool HalStorage::removeDir(const char* path) { return SDCard.removeDir(path); }

lib/hal/HalStorage.h

@@ -0,0 +1,54 @@
+#pragma once
+
+#include <SDCardManager.h>
+
+#include <vector>
+
+class HalStorage {
+ public:
+  HalStorage();
+  bool begin();
+  bool ready() const;
+  std::vector<String> listFiles(const char* path = "/", int maxFiles = 200);
+  // Read the entire file at `path` into a String. Returns empty string on failure.
+  String readFile(const char* path);
+  // Low-memory helpers:
+  // Stream the file contents to a `Print` (e.g. `Serial`, or any `Print`-derived object).
+  // Returns true on success, false on failure.
+  bool readFileToStream(const char* path, Print& out, size_t chunkSize = 256);
+  // Read up to `bufferSize-1` bytes into `buffer`, null-terminating it. Returns bytes read.
+  size_t readFileToBuffer(const char* path, char* buffer, size_t bufferSize, size_t maxBytes = 0);
+  // Write a string to `path` on the SD card. Overwrites existing file.
+  // Returns true on success.
+  bool writeFile(const char* path, const String& content);
+  // Ensure a directory exists, creating it if necessary. Returns true on success.
+  bool ensureDirectoryExists(const char* path);
+
+  FsFile open(const char* path, const oflag_t oflag = O_RDONLY);
+  bool mkdir(const char* path, const bool pFlag = true);
+  bool exists(const char* path);
+  bool remove(const char* path);
+  bool rmdir(const char* path);
+
+  bool openFileForRead(const char* moduleName, const char* path, FsFile& file);
+  bool openFileForRead(const char* moduleName, const std::string& path, FsFile& file);
+  bool openFileForRead(const char* moduleName, const String& path, FsFile& file);
+  bool openFileForWrite(const char* moduleName, const char* path, FsFile& file);
+  bool openFileForWrite(const char* moduleName, const std::string& path, FsFile& file);
+  bool openFileForWrite(const char* moduleName, const String& path, FsFile& file);
+  bool removeDir(const char* path);
+
+  static HalStorage& getInstance() { return instance; }
+
+ private:
+  static HalStorage instance;
+
+  bool initialized = false;
+};
+
+#define Storage HalStorage::getInstance()
+
+// Downstream code must use Storage instead of SdMan
+#ifdef SdMan
+#undef SdMan
+#endif

platformio.ini

@@ -2,7 +2,7 @@
 default_envs = default
 
 [crosspoint]
-version = 0.16.0
+version = 1.0.0
 
 [base]
 platform = espressif32 @ 6.12.0
@@ -60,3 +60,9 @@ extends = base
 build_flags =
   ${base.build_flags}
   -DCROSSPOINT_VERSION=\"${crosspoint.version}\"
+
+[env:gh_release_rc]
+extends = base
+build_flags =
+  ${base.build_flags}
+  -DCROSSPOINT_VERSION=\"${crosspoint.version}-rc+${sysenv.CROSSPOINT_RC_HASH}\"

scripts/debugging_monitor.py

@@ -0,0 +1,214 @@
+import sys
+import argparse
+import re
+import threading
+from datetime import datetime
+from collections import deque
+import time
+
+# Try to import potentially missing packages
+try:
+    import serial
+    from colorama import init, Fore, Style
+    import matplotlib.pyplot as plt
+    import matplotlib.animation as animation
+except ImportError as e:
+    missing_package = e.name
+    print("\n" + "!" * 50)
+    print(f" Error: The required package '{missing_package}' is not installed.")
+    print("!" * 50)
+
+    print(f"\nTo fix this, please run the following command in your terminal:\n")
+
+    install_cmd = "pip install "
+    packages = []
+    if 'serial' in str(e): packages.append("pyserial")
+    if 'colorama' in str(e): packages.append("colorama")
+    if 'matplotlib' in str(e): packages.append("matplotlib")
+
+    print(f"    {install_cmd}{' '.join(packages)}")
+
+    print("\nExiting...")
+    sys.exit(1)
+
+# --- Global Variables for Data Sharing ---
+# Store last 50 data points
+MAX_POINTS = 50
+time_data = deque(maxlen=MAX_POINTS)
+free_mem_data = deque(maxlen=MAX_POINTS)
+total_mem_data = deque(maxlen=MAX_POINTS)
+data_lock = threading.Lock() # Prevent reading while writing
+
+# Initialize colors
+init(autoreset=True)
+
+def get_color_for_line(line):
+    """
+    Classify log lines by type and assign appropriate colors.
+    """
+    line_upper = line.upper()
+
+    if any(keyword in line_upper for keyword in ["ERROR", "[ERR]", "[SCT]", "FAILED", "WARNING"]):
+        return Fore.RED
+    if "[MEM]" in line_upper or "FREE:" in line_upper:
+        return Fore.CYAN
+    if any(keyword in line_upper for keyword in ["[GFX]", "[ERS]", "DISPLAY", "RAM WRITE", "RAM COMPLETE", "REFRESH", "POWERING ON", "FRAME BUFFER", "LUT"]):
+        return Fore.MAGENTA
+    if any(keyword in line_upper for keyword in ["[EBP]", "[BMC]", "[ZIP]", "[PARSER]", "[EHP]", "LOADING EPUB", "CACHE", "DECOMPRESSED", "PARSING"]):
+        return Fore.GREEN
+    if "[ACT]" in line_upper or "ENTERING ACTIVITY" in line_upper or "EXITING ACTIVITY" in line_upper:
+        return Fore.YELLOW
+    if any(keyword in line_upper for keyword in ["RENDERED PAGE", "[LOOP]", "DURATION", "WAIT COMPLETE"]):
+        return Fore.BLUE
+    if any(keyword in line_upper for keyword in ["[CPS]", "SETTINGS", "[CLEAR_CACHE]"]):
+        return Fore.LIGHTYELLOW_EX
+    if any(keyword in line_upper for keyword in ["ESP-ROM", "BUILD:", "RST:", "BOOT:", "SPIWP:", "MODE:", "LOAD:", "ENTRY", "[SD]", "STARTING CROSSPOINT", "VERSION"]):
+        return Fore.LIGHTBLACK_EX
+    if "[RBS]" in line_upper:
+        return Fore.LIGHTCYAN_EX
+    if "[KRS]" in line_upper:
+        return Fore.LIGHTMAGENTA_EX
+    if any(keyword in line_upper for keyword in ["EINKDISPLAY:", "STATIC FRAME", "INITIALIZING", "SPI INITIALIZED", "GPIO PINS", "RESETTING", "SSD1677", "E-INK"]):
+        return Fore.LIGHTMAGENTA_EX
+    if any(keyword in line_upper for keyword in ["[FNS]", "FOOTNOTE"]):
+        return Fore.LIGHTGREEN_EX
+    if any(keyword in line_upper for keyword in ["[CHAP]", "[OPDS]", "[COF]"]):
+        return Fore.LIGHTYELLOW_EX
+
+    return Fore.WHITE
+
+def parse_memory_line(line):
+    """
+    Extracts Free and Total bytes from the specific log line.
+    Format: [MEM] Free: 196344 bytes, Total: 226412 bytes, Min Free: 112620 bytes
+    """
+    # Regex to find 'Free: <digits>' and 'Total: <digits>'
+    match = re.search(r"Free:\s*(\d+).*Total:\s*(\d+)", line)
+    if match:
+        try:
+            free_bytes = int(match.group(1))
+            total_bytes = int(match.group(2))
+            return free_bytes, total_bytes
+        except ValueError:
+            return None, None
+    return None, None
+
+def serial_worker(port, baud):
+    """
+    Runs in a background thread. Handles reading serial, printing to console,
+    and updating the data lists.
+    """
+    print(f"{Fore.CYAN}--- Opening {port} at {baud} baud ---{Style.RESET_ALL}")
+
+    try:
+        ser = serial.Serial(port, baud, timeout=0.1)
+        ser.dtr = False
+        ser.rts = False
+    except serial.SerialException as e:
+        print(f"{Fore.RED}Error opening port: {e}{Style.RESET_ALL}")
+        return
+
+    try:
+        while True:
+            try:
+                raw_data = ser.readline().decode('utf-8', errors='replace')
+
+                if not raw_data:
+                    continue
+
+                clean_line = raw_data.strip()
+                if not clean_line:
+                    continue
+
+                # Add PC timestamp
+                pc_time = datetime.now().strftime("%H:%M:%S")
+                formatted_line = re.sub(r"^\[\d+\]", f"[{pc_time}]", clean_line)
+
+                # Check for Memory Line
+                if "[MEM]" in formatted_line:
+                    free_val, total_val = parse_memory_line(formatted_line)
+                    if free_val is not None:
+                        with data_lock:
+                            time_data.append(pc_time)
+                            free_mem_data.append(free_val / 1024) # Convert to KB
+                            total_mem_data.append(total_val / 1024) # Convert to KB
+
+                # Print to console
+                line_color = get_color_for_line(formatted_line)
+                print(f"{line_color}{formatted_line}")
+
+            except OSError:
+                print(f"{Fore.RED}Device disconnected.{Style.RESET_ALL}")
+                break
+    except Exception as e:
+        # If thread is killed violently (e.g. main exit), silence errors
+        pass
+    finally:
+        if 'ser' in locals() and ser.is_open:
+            ser.close()
+
+def update_graph(frame):
+    """
+    Called by Matplotlib animation to redraw the chart.
+    """
+    with data_lock:
+        if not time_data:
+            return
+
+        # Convert deques to lists for plotting
+        x = list(time_data)
+        y_free = list(free_mem_data)
+        y_total = list(total_mem_data)
+
+    plt.cla() # Clear axis
+
+    # Plot Total RAM
+    plt.plot(x, y_total, label='Total RAM (KB)', color='red', linestyle='--')
+
+    # Plot Free RAM
+    plt.plot(x, y_free, label='Free RAM (KB)', color='green', marker='o')
+
+    # Fill area under Free RAM
+    plt.fill_between(x, y_free, color='green', alpha=0.1)
+
+    plt.title("ESP32 Memory Monitor")
+    plt.ylabel("Memory (KB)")
+    plt.xlabel("Time")
+    plt.legend(loc='upper left')
+    plt.grid(True, linestyle=':', alpha=0.6)
+
+    # Rotate date labels
+    plt.xticks(rotation=45, ha='right')
+    plt.tight_layout()
+
+def main():
+    parser = argparse.ArgumentParser(description="ESP32 Monitor with Graph")
+    parser.add_argument("port", nargs="?", default="/dev/ttyACM0", help="Serial port")
+    parser.add_argument("--baud", type=int, default=115200, help="Baud rate")
+    args = parser.parse_args()
+
+    # 1. Start the Serial Reader in a separate thread
+    # Daemon=True means this thread dies when the main program closes
+    t = threading.Thread(target=serial_worker, args=(args.port, args.baud), daemon=True)
+    t.start()
+
+    # 2. Set up the Graph (Main Thread)
+    try:
+        plt.style.use('light_background')
+    except:
+        pass
+
+    fig = plt.figure(figsize=(10, 6))
+
+    # Update graph every 1000ms
+    ani = animation.FuncAnimation(fig, update_graph, interval=1000)
+
+    try:
+        print(f"{Fore.YELLOW}Starting Graph Window... (Close window to exit){Style.RESET_ALL}")
+        plt.show()
+    except KeyboardInterrupt:
+        print(f"\n{Fore.YELLOW}Exiting...{Style.RESET_ALL}")
+        plt.close('all') # Force close any lingering plot windows
+
+if __name__ == "__main__":
+    main()

src/CrossPointSettings.cpp

@@ -1,7 +1,7 @@
 #include "CrossPointSettings.h"
 
+#include <HalStorage.h>
 #include <HardwareSerial.h>
-#include <SDCardManager.h>
 #include <Serialization.h>
 
 #include <cstring>
@@ -22,16 +22,67 @@ 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 = 23;
+constexpr uint8_t SETTINGS_COUNT = 32;
 constexpr char SETTINGS_FILE[] = "/.crosspoint/settings.bin";
+
+// Validate front button mapping to ensure each hardware button is unique.
+// If duplicates are detected, reset to the default physical order to prevent invalid mappings.
+void validateFrontButtonMapping(CrossPointSettings& settings) {
+  // Snapshot the logical->hardware mapping so we can compare for duplicates.
+  const uint8_t mapping[] = {settings.frontButtonBack, settings.frontButtonConfirm, settings.frontButtonLeft,
+                             settings.frontButtonRight};
+  for (size_t i = 0; i < 4; i++) {
+    for (size_t j = i + 1; j < 4; j++) {
+      if (mapping[i] == mapping[j]) {
+        // Duplicate detected: restore the default physical order (Back, Confirm, Left, Right).
+        settings.frontButtonBack = CrossPointSettings::FRONT_HW_BACK;
+        settings.frontButtonConfirm = CrossPointSettings::FRONT_HW_CONFIRM;
+        settings.frontButtonLeft = CrossPointSettings::FRONT_HW_LEFT;
+        settings.frontButtonRight = CrossPointSettings::FRONT_HW_RIGHT;
+        return;
+      }
+    }
+  }
+}
+
+// Convert legacy front button layout into explicit logical->hardware mapping.
+void applyLegacyFrontButtonLayout(CrossPointSettings& settings) {
+  switch (static_cast<CrossPointSettings::FRONT_BUTTON_LAYOUT>(settings.frontButtonLayout)) {
+    case CrossPointSettings::LEFT_RIGHT_BACK_CONFIRM:
+      settings.frontButtonBack = CrossPointSettings::FRONT_HW_LEFT;
+      settings.frontButtonConfirm = CrossPointSettings::FRONT_HW_RIGHT;
+      settings.frontButtonLeft = CrossPointSettings::FRONT_HW_BACK;
+      settings.frontButtonRight = CrossPointSettings::FRONT_HW_CONFIRM;
+      break;
+    case CrossPointSettings::LEFT_BACK_CONFIRM_RIGHT:
+      settings.frontButtonBack = CrossPointSettings::FRONT_HW_CONFIRM;
+      settings.frontButtonConfirm = CrossPointSettings::FRONT_HW_LEFT;
+      settings.frontButtonLeft = CrossPointSettings::FRONT_HW_BACK;
+      settings.frontButtonRight = CrossPointSettings::FRONT_HW_RIGHT;
+      break;
+    case CrossPointSettings::BACK_CONFIRM_RIGHT_LEFT:
+      settings.frontButtonBack = CrossPointSettings::FRONT_HW_BACK;
+      settings.frontButtonConfirm = CrossPointSettings::FRONT_HW_CONFIRM;
+      settings.frontButtonLeft = CrossPointSettings::FRONT_HW_RIGHT;
+      settings.frontButtonRight = CrossPointSettings::FRONT_HW_LEFT;
+      break;
+    case CrossPointSettings::BACK_CONFIRM_LEFT_RIGHT:
+    default:
+      settings.frontButtonBack = CrossPointSettings::FRONT_HW_BACK;
+      settings.frontButtonConfirm = CrossPointSettings::FRONT_HW_CONFIRM;
+      settings.frontButtonLeft = CrossPointSettings::FRONT_HW_LEFT;
+      settings.frontButtonRight = CrossPointSettings::FRONT_HW_RIGHT;
+      break;
+  }
+}
 }  // namespace
 
 bool CrossPointSettings::saveToFile() const {
   // Make sure the directory exists
-  SdMan.mkdir("/.crosspoint");
+  Storage.mkdir("/.crosspoint");
 
   FsFile outputFile;
-  if (!SdMan.openFileForWrite("CPS", SETTINGS_FILE, outputFile)) {
+  if (!Storage.openFileForWrite("CPS", SETTINGS_FILE, outputFile)) {
     return false;
   }
 
@@ -42,7 +93,7 @@ bool CrossPointSettings::saveToFile() const {
   serialization::writePod(outputFile, shortPwrBtn);
   serialization::writePod(outputFile, statusBar);
   serialization::writePod(outputFile, orientation);
-  serialization::writePod(outputFile, frontButtonLayout);
+  serialization::writePod(outputFile, frontButtonLayout);  // legacy
   serialization::writePod(outputFile, sideButtonLayout);
   serialization::writePod(outputFile, fontFamily);
   serialization::writePod(outputFile, fontSize);
@@ -60,6 +111,15 @@ bool CrossPointSettings::saveToFile() const {
   serialization::writeString(outputFile, std::string(opdsUsername));
   serialization::writeString(outputFile, std::string(opdsPassword));
   serialization::writePod(outputFile, sleepScreenCoverFilter);
+  serialization::writePod(outputFile, uiTheme);
+  serialization::writePod(outputFile, frontButtonBack);
+  serialization::writePod(outputFile, frontButtonConfirm);
+  serialization::writePod(outputFile, frontButtonLeft);
+  serialization::writePod(outputFile, frontButtonRight);
+  serialization::writePod(outputFile, fadingFix);
+  serialization::writePod(outputFile, embeddedStyle);
+  serialization::writePod(outputFile, sleepScreenLetterboxFill);
+  serialization::writePod(outputFile, sleepScreenGradientDir);
   // New fields added at end for backward compatibility
   outputFile.close();
 
@@ -69,7 +129,7 @@ bool CrossPointSettings::saveToFile() const {
 
 bool CrossPointSettings::loadFromFile() {
   FsFile inputFile;
-  if (!SdMan.openFileForRead("CPS", SETTINGS_FILE, inputFile)) {
+  if (!Storage.openFileForRead("CPS", SETTINGS_FILE, inputFile)) {
     return false;
   }
 
@@ -86,6 +146,8 @@ bool CrossPointSettings::loadFromFile() {
 
   // load settings that exist (support older files with fewer fields)
   uint8_t settingsRead = 0;
+  // Track whether remap fields were present in the settings file.
+  bool frontButtonMappingRead = false;
   do {
     readAndValidate(inputFile, sleepScreen, SLEEP_SCREEN_MODE_COUNT);
     if (++settingsRead >= fileSettingsCount) break;
@@ -97,7 +159,7 @@ bool CrossPointSettings::loadFromFile() {
     if (++settingsRead >= fileSettingsCount) break;
     readAndValidate(inputFile, orientation, ORIENTATION_COUNT);
     if (++settingsRead >= fileSettingsCount) break;
-    readAndValidate(inputFile, frontButtonLayout, FRONT_BUTTON_LAYOUT_COUNT);
+    readAndValidate(inputFile, frontButtonLayout, FRONT_BUTTON_LAYOUT_COUNT);  // legacy
     if (++settingsRead >= fileSettingsCount) break;
     readAndValidate(inputFile, sideButtonLayout, SIDE_BUTTON_LAYOUT_COUNT);
     if (++settingsRead >= fileSettingsCount) break;
@@ -148,9 +210,34 @@ bool CrossPointSettings::loadFromFile() {
     if (++settingsRead >= fileSettingsCount) break;
     readAndValidate(inputFile, sleepScreenCoverFilter, SLEEP_SCREEN_COVER_FILTER_COUNT);
     if (++settingsRead >= fileSettingsCount) break;
+    serialization::readPod(inputFile, uiTheme);
+    if (++settingsRead >= fileSettingsCount) break;
+    readAndValidate(inputFile, frontButtonBack, FRONT_BUTTON_HARDWARE_COUNT);
+    if (++settingsRead >= fileSettingsCount) break;
+    readAndValidate(inputFile, frontButtonConfirm, FRONT_BUTTON_HARDWARE_COUNT);
+    if (++settingsRead >= fileSettingsCount) break;
+    readAndValidate(inputFile, frontButtonLeft, FRONT_BUTTON_HARDWARE_COUNT);
+    if (++settingsRead >= fileSettingsCount) break;
+    readAndValidate(inputFile, frontButtonRight, FRONT_BUTTON_HARDWARE_COUNT);
+    frontButtonMappingRead = true;
+    if (++settingsRead >= fileSettingsCount) break;
+    serialization::readPod(inputFile, fadingFix);
+    if (++settingsRead >= fileSettingsCount) break;
+    serialization::readPod(inputFile, embeddedStyle);
+    if (++settingsRead >= fileSettingsCount) break;
+    readAndValidate(inputFile, sleepScreenLetterboxFill, SLEEP_SCREEN_LETTERBOX_FILL_COUNT);
+    if (++settingsRead >= fileSettingsCount) break;
+    readAndValidate(inputFile, sleepScreenGradientDir, SLEEP_SCREEN_GRADIENT_DIR_COUNT);
+    if (++settingsRead >= fileSettingsCount) break;
     // New fields added at end for backward compatibility
   } while (false);
 
+  if (frontButtonMappingRead) {
+    validateFrontButtonMapping(*this);
+  } else {
+    applyLegacyFrontButtonLayout(*this);
+  }
+
   inputFile.close();
   Serial.printf("[%lu] [CPS] Settings loaded from file\n", millis());
   return true;

src/CrossPointSettings.h

@@ -15,7 +15,15 @@ class CrossPointSettings {
   CrossPointSettings(const CrossPointSettings&) = delete;
   CrossPointSettings& operator=(const CrossPointSettings&) = delete;
 
-  enum SLEEP_SCREEN_MODE { DARK = 0, LIGHT = 1, CUSTOM = 2, COVER = 3, BLANK = 4, SLEEP_SCREEN_MODE_COUNT };
+  enum SLEEP_SCREEN_MODE {
+    DARK = 0,
+    LIGHT = 1,
+    CUSTOM = 2,
+    COVER = 3,
+    BLANK = 4,
+    COVER_CUSTOM = 5,
+    SLEEP_SCREEN_MODE_COUNT
+  };
   enum SLEEP_SCREEN_COVER_MODE { FIT = 0, CROP = 1, SLEEP_SCREEN_COVER_MODE_COUNT };
   enum SLEEP_SCREEN_COVER_FILTER {
     NO_FILTER = 0,
@@ -23,14 +31,23 @@ class CrossPointSettings {
     INVERTED_BLACK_AND_WHITE = 2,
     SLEEP_SCREEN_COVER_FILTER_COUNT
   };
+  enum SLEEP_SCREEN_LETTERBOX_FILL {
+    LETTERBOX_NONE = 0,
+    LETTERBOX_SOLID = 1,
+    LETTERBOX_BLENDED = 2,
+    LETTERBOX_GRADIENT = 3,
+    SLEEP_SCREEN_LETTERBOX_FILL_COUNT
+  };
+  enum SLEEP_SCREEN_GRADIENT_DIR { GRADIENT_TO_WHITE = 0, GRADIENT_TO_BLACK = 1, SLEEP_SCREEN_GRADIENT_DIR_COUNT };
 
   // Status bar display type enum
   enum STATUS_BAR_MODE {
     NONE = 0,
     NO_PROGRESS = 1,
     FULL = 2,
-    FULL_WITH_PROGRESS_BAR = 3,
-    ONLY_PROGRESS_BAR = 4,
+    BOOK_PROGRESS_BAR = 3,
+    ONLY_BOOK_PROGRESS_BAR = 4,
+    CHAPTER_PROGRESS_BAR = 5,
     STATUS_BAR_MODE_COUNT
   };
 
@@ -42,7 +59,7 @@ class CrossPointSettings {
     ORIENTATION_COUNT
   };
 
-  // Front button layout options
+  // Front button layout options (legacy)
   // Default: Back, Confirm, Left, Right
   // Swapped: Left, Right, Back, Confirm
   enum FRONT_BUTTON_LAYOUT {
@@ -53,6 +70,15 @@ class CrossPointSettings {
     FRONT_BUTTON_LAYOUT_COUNT
   };
 
+  // Front button hardware identifiers (for remapping)
+  enum FRONT_BUTTON_HARDWARE {
+    FRONT_HW_BACK = 0,
+    FRONT_HW_CONFIRM = 1,
+    FRONT_HW_LEFT = 2,
+    FRONT_HW_RIGHT = 3,
+    FRONT_BUTTON_HARDWARE_COUNT
+  };
+
   // Side button layout options
   // Default: Previous, Next
   // Swapped: Next, Previous
@@ -68,6 +94,7 @@ class CrossPointSettings {
     LEFT_ALIGN = 1,
     CENTER_ALIGN = 2,
     RIGHT_ALIGN = 3,
+    BOOK_STYLE = 4,
     PARAGRAPH_ALIGNMENT_COUNT
   };
 
@@ -97,12 +124,19 @@ class CrossPointSettings {
   // Hide battery percentage
   enum HIDE_BATTERY_PERCENTAGE { HIDE_NEVER = 0, HIDE_READER = 1, HIDE_ALWAYS = 2, HIDE_BATTERY_PERCENTAGE_COUNT };
 
+  // UI Theme
+  enum UI_THEME { CLASSIC = 0, LYRA = 1 };
+
   // Sleep screen settings
   uint8_t sleepScreen = DARK;
   // Sleep screen cover mode settings
   uint8_t sleepScreenCoverMode = FIT;
   // Sleep screen cover filter
   uint8_t sleepScreenCoverFilter = NO_FILTER;
+  // Sleep screen letterbox fill mode (None / Solid / Blended / Gradient)
+  uint8_t sleepScreenLetterboxFill = LETTERBOX_GRADIENT;
+  // Sleep screen gradient direction (towards white or black)
+  uint8_t sleepScreenGradientDir = GRADIENT_TO_WHITE;
   // Status bar settings
   uint8_t statusBar = FULL;
   // Text rendering settings
@@ -113,9 +147,15 @@ class CrossPointSettings {
   // EPUB reading orientation settings
   // 0 = portrait (default), 1 = landscape clockwise, 2 = inverted, 3 = landscape counter-clockwise
   uint8_t orientation = PORTRAIT;
-  // Button layouts
+  // Button layouts (front layout retained for migration only)
   uint8_t frontButtonLayout = BACK_CONFIRM_LEFT_RIGHT;
   uint8_t sideButtonLayout = PREV_NEXT;
+  // Front button remap (logical -> hardware)
+  // Used by MappedInputManager to translate logical buttons into physical front buttons.
+  uint8_t frontButtonBack = FRONT_HW_BACK;
+  uint8_t frontButtonConfirm = FRONT_HW_CONFIRM;
+  uint8_t frontButtonLeft = FRONT_HW_LEFT;
+  uint8_t frontButtonRight = FRONT_HW_RIGHT;
   // Reader font settings
   uint8_t fontFamily = BOOKERLY;
   uint8_t fontSize = MEDIUM;
@@ -137,6 +177,12 @@ class CrossPointSettings {
   uint8_t hideBatteryPercentage = HIDE_NEVER;
   // Long-press chapter skip on side buttons
   uint8_t longPressChapterSkip = 1;
+  // UI Theme
+  uint8_t uiTheme = LYRA;
+  // Sunlight fading compensation
+  uint8_t fadingFix = 0;
+  // Use book's embedded CSS styles for EPUB rendering (1 = enabled, 0 = disabled)
+  uint8_t embeddedStyle = 1;
 
   ~CrossPointSettings() = default;
 

src/CrossPointState.cpp

@@ -1,11 +1,11 @@
 #include "CrossPointState.h"
 
+#include <HalStorage.h>
 #include <HardwareSerial.h>
-#include <SDCardManager.h>
 #include <Serialization.h>
 
 namespace {
-constexpr uint8_t STATE_FILE_VERSION = 2;
+constexpr uint8_t STATE_FILE_VERSION = 4;
 constexpr char STATE_FILE[] = "/.crosspoint/state.bin";
 }  // namespace
 
@@ -13,20 +13,22 @@ CrossPointState CrossPointState::instance;
 
 bool CrossPointState::saveToFile() const {
   FsFile outputFile;
-  if (!SdMan.openFileForWrite("CPS", STATE_FILE, outputFile)) {
+  if (!Storage.openFileForWrite("CPS", STATE_FILE, outputFile)) {
     return false;
   }
 
   serialization::writePod(outputFile, STATE_FILE_VERSION);
   serialization::writeString(outputFile, openEpubPath);
   serialization::writePod(outputFile, lastSleepImage);
+  serialization::writePod(outputFile, readerActivityLoadCount);
+  serialization::writePod(outputFile, lastSleepFromReader);
   outputFile.close();
   return true;
 }
 
 bool CrossPointState::loadFromFile() {
   FsFile inputFile;
-  if (!SdMan.openFileForRead("CPS", STATE_FILE, inputFile)) {
+  if (!Storage.openFileForRead("CPS", STATE_FILE, inputFile)) {
     return false;
   }
 
@@ -45,6 +47,16 @@ bool CrossPointState::loadFromFile() {
     lastSleepImage = 0;
   }
 
+  if (version >= 3) {
+    serialization::readPod(inputFile, readerActivityLoadCount);
+  }
+
+  if (version >= 4) {
+    serialization::readPod(inputFile, lastSleepFromReader);
+  } else {
+    lastSleepFromReader = false;
+  }
+
   inputFile.close();
   return true;
 }

src/CrossPointState.h

@@ -9,6 +9,8 @@ class CrossPointState {
  public:
   std::string openEpubPath;
   uint8_t lastSleepImage;
+  uint8_t readerActivityLoadCount = 0;
+  bool lastSleepFromReader = false;
   ~CrossPointState() = default;
 
   // Get singleton instance

src/MappedInputManager.cpp

@@ -5,26 +5,11 @@
 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},
@@ -33,29 +18,36 @@ constexpr SideLayoutMap kSideLayouts[] = {
 }  // 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:
-      return (gpio.*fn)(front.back);
+      // Logical Back maps to user-configured front button.
+      return (gpio.*fn)(SETTINGS.frontButtonBack);
     case Button::Confirm:
-      return (gpio.*fn)(front.confirm);
+      // Logical Confirm maps to user-configured front button.
+      return (gpio.*fn)(SETTINGS.frontButtonConfirm);
     case Button::Left:
-      return (gpio.*fn)(front.left);
+      // Logical Left maps to user-configured front button.
+      return (gpio.*fn)(SETTINGS.frontButtonLeft);
     case Button::Right:
-      return (gpio.*fn)(front.right);
+      // Logical Right maps to user-configured front button.
+      return (gpio.*fn)(SETTINGS.frontButtonRight);
     case Button::Up:
+      // Side buttons remain fixed for Up/Down.
       return (gpio.*fn)(HalGPIO::BTN_UP);
     case Button::Down:
+      // Side buttons remain fixed for Up/Down.
       return (gpio.*fn)(HalGPIO::BTN_DOWN);
     case Button::Power:
+      // Power button bypasses remapping.
       return (gpio.*fn)(HalGPIO::BTN_POWER);
     case Button::PageBack:
+      // Reader page navigation uses side buttons and can be swapped via settings.
       return (gpio.*fn)(side.pageBack);
     case Button::PageForward:
+      // Reader page navigation uses side buttons and can be swapped via settings.
       return (gpio.*fn)(side.pageForward);
   }
 
@@ -76,17 +68,42 @@ 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 {
-  const auto layout = static_cast<CrossPointSettings::FRONT_BUTTON_LAYOUT>(SETTINGS.frontButtonLayout);
+  // Build the label order based on the configured hardware mapping.
+  auto labelForHardware = [&](uint8_t hw) -> const char* {
+    // Compare against configured logical roles and return the matching label.
+    if (hw == SETTINGS.frontButtonBack) {
+      return back;
+    }
+    if (hw == SETTINGS.frontButtonConfirm) {
+      return confirm;
+    }
+    if (hw == SETTINGS.frontButtonLeft) {
+      return previous;
+    }
+    if (hw == SETTINGS.frontButtonRight) {
+      return next;
+    }
+    return "";
+  };
 
-  switch (layout) {
-    case CrossPointSettings::LEFT_RIGHT_BACK_CONFIRM:
-      return {previous, next, back, confirm};
-    case CrossPointSettings::LEFT_BACK_CONFIRM_RIGHT:
-      return {previous, back, confirm, next};
-    case CrossPointSettings::BACK_CONFIRM_RIGHT_LEFT:
-      return {back, confirm, next, previous};
-    case CrossPointSettings::BACK_CONFIRM_LEFT_RIGHT:
-    default:
-      return {back, confirm, previous, next};
+  return {labelForHardware(HalGPIO::BTN_BACK), labelForHardware(HalGPIO::BTN_CONFIRM),
+          labelForHardware(HalGPIO::BTN_LEFT), labelForHardware(HalGPIO::BTN_RIGHT)};
+}
+
+int MappedInputManager::getPressedFrontButton() const {
+  // Scan the raw front buttons in hardware order.
+  // This bypasses remapping so the remap activity can capture physical presses.
+  if (gpio.wasPressed(HalGPIO::BTN_BACK)) {
+    return HalGPIO::BTN_BACK;
   }
+  if (gpio.wasPressed(HalGPIO::BTN_CONFIRM)) {
+    return HalGPIO::BTN_CONFIRM;
+  }
+  if (gpio.wasPressed(HalGPIO::BTN_LEFT)) {
+    return HalGPIO::BTN_LEFT;
+  }
+  if (gpio.wasPressed(HalGPIO::BTN_RIGHT)) {
+    return HalGPIO::BTN_RIGHT;
+  }
+  return -1;
 }

src/MappedInputManager.h

@@ -22,6 +22,8 @@ class MappedInputManager {
   bool wasAnyReleased() const;
   unsigned long getHeldTime() const;
   Labels mapLabels(const char* back, const char* confirm, const char* previous, const char* next) const;
+  // Returns the raw front button index that was pressed this frame (or -1 if none).
+  int getPressedFrontButton() const;
 
  private:
   HalGPIO& gpio;

src/RecentBooksStore.cpp

@@ -1,20 +1,25 @@
 #include "RecentBooksStore.h"
 
+#include <Epub.h>
+#include <HalStorage.h>
 #include <HardwareSerial.h>
-#include <SDCardManager.h>
 #include <Serialization.h>
+#include <Xtc.h>
 
 #include <algorithm>
 
+#include "util/StringUtils.h"
+
 namespace {
-constexpr uint8_t RECENT_BOOKS_FILE_VERSION = 2;
+constexpr uint8_t RECENT_BOOKS_FILE_VERSION = 3;
 constexpr char RECENT_BOOKS_FILE[] = "/.crosspoint/recent.bin";
 constexpr int MAX_RECENT_BOOKS = 10;
 }  // namespace
 
 RecentBooksStore RecentBooksStore::instance;
 
-void RecentBooksStore::addBook(const std::string& path, const std::string& title, const std::string& author) {
+void RecentBooksStore::addBook(const std::string& path, const std::string& title, const std::string& author,
+                               const std::string& coverBmpPath) {
   // Remove existing entry if present
   auto it =
       std::find_if(recentBooks.begin(), recentBooks.end(), [&](const RecentBook& book) { return book.path == path; });
@@ -23,7 +28,7 @@ void RecentBooksStore::addBook(const std::string& path, const std::string& title
   }
 
   // Add to front
-  recentBooks.insert(recentBooks.begin(), {path, title, author});
+  recentBooks.insert(recentBooks.begin(), {path, title, author, coverBmpPath});
 
   // Trim to max size
   if (recentBooks.size() > MAX_RECENT_BOOKS) {
@@ -33,12 +38,25 @@ void RecentBooksStore::addBook(const std::string& path, const std::string& title
   saveToFile();
 }
 
+void RecentBooksStore::updateBook(const std::string& path, const std::string& title, const std::string& author,
+                                  const std::string& coverBmpPath) {
+  auto it =
+      std::find_if(recentBooks.begin(), recentBooks.end(), [&](const RecentBook& book) { return book.path == path; });
+  if (it != recentBooks.end()) {
+    RecentBook& book = *it;
+    book.title = title;
+    book.author = author;
+    book.coverBmpPath = coverBmpPath;
+    saveToFile();
+  }
+}
+
 bool RecentBooksStore::saveToFile() const {
   // Make sure the directory exists
-  SdMan.mkdir("/.crosspoint");
+  Storage.mkdir("/.crosspoint");
 
   FsFile outputFile;
-  if (!SdMan.openFileForWrite("RBS", RECENT_BOOKS_FILE, outputFile)) {
+  if (!Storage.openFileForWrite("RBS", RECENT_BOOKS_FILE, outputFile)) {
     return false;
   }
 
@@ -50,6 +68,7 @@ bool RecentBooksStore::saveToFile() const {
     serialization::writeString(outputFile, book.path);
     serialization::writeString(outputFile, book.title);
     serialization::writeString(outputFile, book.author);
+    serialization::writeString(outputFile, book.coverBmpPath);
   }
 
   outputFile.close();
@@ -57,16 +76,44 @@ bool RecentBooksStore::saveToFile() const {
   return true;
 }
 
+RecentBook RecentBooksStore::getDataFromBook(std::string path) const {
+  std::string lastBookFileName = "";
+  const size_t lastSlash = path.find_last_of('/');
+  if (lastSlash != std::string::npos) {
+    lastBookFileName = path.substr(lastSlash + 1);
+  }
+
+  Serial.printf("Loading recent book: %s\n", path.c_str());
+
+  // If epub, try to load the metadata for title/author and cover
+  if (StringUtils::checkFileExtension(lastBookFileName, ".epub")) {
+    Epub epub(path, "/.crosspoint");
+    epub.load(false);
+    return RecentBook{path, epub.getTitle(), epub.getAuthor(), epub.getThumbBmpPath()};
+  } else if (StringUtils::checkFileExtension(lastBookFileName, ".xtch") ||
+             StringUtils::checkFileExtension(lastBookFileName, ".xtc")) {
+    // Handle XTC file
+    Xtc xtc(path, "/.crosspoint");
+    if (xtc.load()) {
+      return RecentBook{path, xtc.getTitle(), xtc.getAuthor(), xtc.getThumbBmpPath()};
+    }
+  } else if (StringUtils::checkFileExtension(lastBookFileName, ".txt") ||
+             StringUtils::checkFileExtension(lastBookFileName, ".md")) {
+    return RecentBook{path, lastBookFileName, "", ""};
+  }
+  return RecentBook{path, "", "", ""};
+}
+
 bool RecentBooksStore::loadFromFile() {
   FsFile inputFile;
-  if (!SdMan.openFileForRead("RBS", RECENT_BOOKS_FILE, inputFile)) {
+  if (!Storage.openFileForRead("RBS", RECENT_BOOKS_FILE, inputFile)) {
     return false;
   }
 
   uint8_t version;
   serialization::readPod(inputFile, version);
   if (version != RECENT_BOOKS_FILE_VERSION) {
-    if (version == 1) {
+    if (version == 1 || version == 2) {
       // Old version, just read paths
       uint8_t count;
       serialization::readPod(inputFile, count);
@@ -75,9 +122,18 @@ bool RecentBooksStore::loadFromFile() {
       for (uint8_t i = 0; i < count; i++) {
         std::string path;
         serialization::readString(inputFile, path);
-        // Title and author will be empty, they will be filled when the book is
-        // opened again
-        recentBooks.push_back({path, "", ""});
+
+        // load book to get missing data
+        RecentBook book = getDataFromBook(path);
+        if (book.title.empty() && book.author.empty() && version == 2) {
+          // Fall back to loading what we can from the store
+          std::string title, author;
+          serialization::readString(inputFile, title);
+          serialization::readString(inputFile, author);
+          recentBooks.push_back({path, title, author, ""});
+        } else {
+          recentBooks.push_back(book);
+        }
       }
     } else {
       Serial.printf("[%lu] [RBS] Deserialization failed: Unknown version %u\n", millis(), version);
@@ -92,11 +148,12 @@ bool RecentBooksStore::loadFromFile() {
     recentBooks.reserve(count);
 
     for (uint8_t i = 0; i < count; i++) {
-      std::string path, title, author;
+      std::string path, title, author, coverBmpPath;
       serialization::readString(inputFile, path);
       serialization::readString(inputFile, title);
       serialization::readString(inputFile, author);
-      recentBooks.push_back({path, title, author});
+      serialization::readString(inputFile, coverBmpPath);
+      recentBooks.push_back({path, title, author, coverBmpPath});
     }
   }
 

src/RecentBooksStore.h

@@ -6,6 +6,7 @@ struct RecentBook {
   std::string path;
   std::string title;
   std::string author;
+  std::string coverBmpPath;
 
   bool operator==(const RecentBook& other) const { return path == other.path; }
 };
@@ -23,7 +24,11 @@ class RecentBooksStore {
   static RecentBooksStore& getInstance() { return instance; }
 
   // Add a book to the recent list (moves to front if already exists)
-  void addBook(const std::string& path, const std::string& title, const std::string& author);
+  void addBook(const std::string& path, const std::string& title, const std::string& author,
+               const std::string& coverBmpPath);
+
+  void updateBook(const std::string& path, const std::string& title, const std::string& author,
+                  const std::string& coverBmpPath);
 
   // Get the list of recent books (most recent first)
   const std::vector<RecentBook>& getBooks() const { return recentBooks; }
@@ -34,6 +39,7 @@ class RecentBooksStore {
   bool saveToFile() const;
 
   bool loadFromFile();
+  RecentBook getDataFromBook(std::string path) const;
 };
 
 // Helper macro to access recent books store

src/ScreenComponents.cpp

@@ -1,146 +0,0 @@
-#include "ScreenComponents.h"
-
-#include <GfxRenderer.h>
-
-#include <cstdint>
-#include <string>
-
-#include "Battery.h"
-#include "fontIds.h"
-
-void ScreenComponents::drawBattery(const GfxRenderer& renderer, const int left, const int top,
-                                   const bool showPercentage) {
-  // Left aligned battery icon and percentage
-  const uint16_t percentage = battery.readPercentage();
-  const auto percentageText = showPercentage ? std::to_string(percentage) + "%" : "";
-  renderer.drawText(SMALL_FONT_ID, left + 20, top, percentageText.c_str());
-
-  // 1 column on left, 2 columns on right, 5 columns of battery body
-  constexpr int batteryWidth = 15;
-  constexpr int batteryHeight = 12;
-  const int x = left;
-  const int y = top + 6;
-
-  // Top line
-  renderer.drawLine(x + 1, y, x + batteryWidth - 3, y);
-  // Bottom line
-  renderer.drawLine(x + 1, y + batteryHeight - 1, x + batteryWidth - 3, y + batteryHeight - 1);
-  // Left line
-  renderer.drawLine(x, y + 1, x, y + batteryHeight - 2);
-  // Battery end
-  renderer.drawLine(x + batteryWidth - 2, y + 1, x + batteryWidth - 2, y + batteryHeight - 2);
-  renderer.drawPixel(x + batteryWidth - 1, y + 3);
-  renderer.drawPixel(x + batteryWidth - 1, y + batteryHeight - 4);
-  renderer.drawLine(x + batteryWidth - 0, y + 4, x + batteryWidth - 0, y + batteryHeight - 5);
-
-  // The +1 is to round up, so that we always fill at least one pixel
-  int filledWidth = percentage * (batteryWidth - 5) / 100 + 1;
-  if (filledWidth > batteryWidth - 5) {
-    filledWidth = batteryWidth - 5;  // Ensure we don't overflow
-  }
-
-  renderer.fillRect(x + 2, y + 2, filledWidth, batteryHeight - 4);
-}
-
-void ScreenComponents::drawBookProgressBar(const GfxRenderer& renderer, const size_t bookProgress) {
-  int vieweableMarginTop, vieweableMarginRight, vieweableMarginBottom, vieweableMarginLeft;
-  renderer.getOrientedViewableTRBL(&vieweableMarginTop, &vieweableMarginRight, &vieweableMarginBottom,
-                                   &vieweableMarginLeft);
-
-  const int progressBarMaxWidth = renderer.getScreenWidth() - vieweableMarginLeft - vieweableMarginRight;
-  const int progressBarY = renderer.getScreenHeight() - vieweableMarginBottom - BOOK_PROGRESS_BAR_HEIGHT;
-  const int barWidth = progressBarMaxWidth * bookProgress / 100;
-  renderer.fillRect(vieweableMarginLeft, progressBarY, barWidth, BOOK_PROGRESS_BAR_HEIGHT, true);
-}
-
-int ScreenComponents::drawTabBar(const GfxRenderer& renderer, const int y, const std::vector<TabInfo>& tabs) {
-  constexpr int tabPadding = 20;      // Horizontal padding between tabs
-  constexpr int leftMargin = 20;      // Left margin for first tab
-  constexpr int underlineHeight = 2;  // Height of selection underline
-  constexpr int underlineGap = 4;     // Gap between text and underline
-
-  const int lineHeight = renderer.getLineHeight(UI_12_FONT_ID);
-  const int tabBarHeight = lineHeight + underlineGap + underlineHeight;
-
-  int currentX = leftMargin;
-
-  for (const auto& tab : tabs) {
-    const int textWidth =
-        renderer.getTextWidth(UI_12_FONT_ID, tab.label, tab.selected ? EpdFontFamily::BOLD : EpdFontFamily::REGULAR);
-
-    // Draw tab label
-    renderer.drawText(UI_12_FONT_ID, currentX, y, tab.label, true,
-                      tab.selected ? EpdFontFamily::BOLD : EpdFontFamily::REGULAR);
-
-    // Draw underline for selected tab
-    if (tab.selected) {
-      renderer.fillRect(currentX, y + lineHeight + underlineGap, textWidth, underlineHeight);
-    }
-
-    currentX += textWidth + tabPadding;
-  }
-
-  return tabBarHeight;
-}
-
-void ScreenComponents::drawScrollIndicator(const GfxRenderer& renderer, const int currentPage, const int totalPages,
-                                           const int contentTop, const int contentHeight) {
-  if (totalPages <= 1) {
-    return;  // No need for indicator if only one page
-  }
-
-  const int screenWidth = renderer.getScreenWidth();
-  constexpr int indicatorWidth = 20;
-  constexpr int arrowSize = 6;
-  constexpr int margin = 15;  // Offset from right edge
-
-  const int centerX = screenWidth - indicatorWidth / 2 - margin;
-  const int indicatorTop = contentTop + 60;  // Offset to avoid overlapping side button hints
-  const int indicatorBottom = contentTop + contentHeight - 30;
-
-  // Draw up arrow at top (^) - narrow point at top, wide base at bottom
-  for (int i = 0; i < arrowSize; ++i) {
-    const int lineWidth = 1 + i * 2;
-    const int startX = centerX - i;
-    renderer.drawLine(startX, indicatorTop + i, startX + lineWidth - 1, indicatorTop + i);
-  }
-
-  // Draw down arrow at bottom (v) - wide base at top, narrow point at bottom
-  for (int i = 0; i < arrowSize; ++i) {
-    const int lineWidth = 1 + (arrowSize - 1 - i) * 2;
-    const int startX = centerX - (arrowSize - 1 - i);
-    renderer.drawLine(startX, indicatorBottom - arrowSize + 1 + i, startX + lineWidth - 1,
-                      indicatorBottom - arrowSize + 1 + i);
-  }
-
-  // Draw page fraction in the middle (e.g., "1/3")
-  const std::string pageText = std::to_string(currentPage) + "/" + std::to_string(totalPages);
-  const int textWidth = renderer.getTextWidth(SMALL_FONT_ID, pageText.c_str());
-  const int textX = centerX - textWidth / 2;
-  const int textY = (indicatorTop + indicatorBottom) / 2 - renderer.getLineHeight(SMALL_FONT_ID) / 2;
-
-  renderer.drawText(SMALL_FONT_ID, textX, textY, pageText.c_str());
-}
-
-void ScreenComponents::drawProgressBar(const GfxRenderer& renderer, const int x, const int y, const int width,
-                                       const int height, const size_t current, const size_t total) {
-  if (total == 0) {
-    return;
-  }
-
-  // Use 64-bit arithmetic to avoid overflow for large files
-  const int percent = static_cast<int>((static_cast<uint64_t>(current) * 100) / total);
-
-  // Draw outline
-  renderer.drawRect(x, y, width, height);
-
-  // Draw filled portion
-  const int fillWidth = (width - 4) * percent / 100;
-  if (fillWidth > 0) {
-    renderer.fillRect(x + 2, y + 2, fillWidth, height - 4);
-  }
-
-  // Draw percentage text centered below bar
-  const std::string percentText = std::to_string(percent) + "%";
-  renderer.drawCenteredText(UI_10_FONT_ID, y + height + 15, percentText.c_str());
-}

src/ScreenComponents.h

@@ -1,42 +0,0 @@
-#pragma once
-
-#include <cstddef>
-#include <cstdint>
-#include <vector>
-
-class GfxRenderer;
-
-struct TabInfo {
-  const char* label;
-  bool selected;
-};
-
-class ScreenComponents {
- public:
-  static const int BOOK_PROGRESS_BAR_HEIGHT = 4;
-
-  static void drawBattery(const GfxRenderer& renderer, int left, int top, bool showPercentage = true);
-  static void drawBookProgressBar(const GfxRenderer& renderer, size_t bookProgress);
-
-  // Draw a horizontal tab bar with underline indicator for selected tab
-  // Returns the height of the tab bar (for positioning content below)
-  static int drawTabBar(const GfxRenderer& renderer, int y, const std::vector<TabInfo>& tabs);
-
-  // Draw a scroll/page indicator on the right side of the screen
-  // Shows up/down arrows and current page fraction (e.g., "1/3")
-  static void drawScrollIndicator(const GfxRenderer& renderer, int currentPage, int totalPages, int contentTop,
-                                  int contentHeight);
-
-  /**
-   * Draw a progress bar with percentage text.
-   * @param renderer The graphics renderer
-   * @param x Left position of the bar
-   * @param y Top position of the bar
-   * @param width Width of the bar
-   * @param height Height of the bar
-   * @param current Current progress value
-   * @param total Total value for 100% progress
-   */
-  static void drawProgressBar(const GfxRenderer& renderer, int x, int y, int width, int height, size_t current,
-                              size_t total);
-};

src/SettingsList.h

@@ -0,0 +1,105 @@
+#pragma once
+
+#include <vector>
+
+#include "CrossPointSettings.h"
+#include "KOReaderCredentialStore.h"
+#include "activities/settings/SettingsActivity.h"
+
+// Shared settings list used by both the device settings UI and the web settings API.
+// Each entry has a key (for JSON API) and category (for grouping).
+// ACTION-type entries and entries without a key are device-only.
+inline std::vector<SettingInfo> getSettingsList() {
+  return {
+      // --- Display ---
+      SettingInfo::Enum("Sleep Screen", &CrossPointSettings::sleepScreen,
+                        {"Dark", "Light", "Custom", "Cover", "None", "Cover + Custom"}, "sleepScreen", "Display"),
+      SettingInfo::Enum("Sleep Screen Cover Mode", &CrossPointSettings::sleepScreenCoverMode, {"Fit", "Crop"},
+                        "sleepScreenCoverMode", "Display"),
+      SettingInfo::Enum("Sleep Screen Cover Filter", &CrossPointSettings::sleepScreenCoverFilter,
+                        {"None", "Contrast", "Inverted"}, "sleepScreenCoverFilter", "Display"),
+      SettingInfo::Enum("Letterbox Fill", &CrossPointSettings::sleepScreenLetterboxFill,
+                        {"None", "Solid", "Blended", "Gradient"}, "sleepScreenLetterboxFill", "Display"),
+      SettingInfo::Enum("Gradient Direction", &CrossPointSettings::sleepScreenGradientDir, {"To White", "To Black"},
+                        "sleepScreenGradientDir", "Display"),
+      SettingInfo::Enum(
+          "Status Bar", &CrossPointSettings::statusBar,
+          {"None", "No Progress", "Full w/ Percentage", "Full w/ Book Bar", "Book Bar Only", "Full w/ Chapter Bar"},
+          "statusBar", "Display"),
+      SettingInfo::Enum("Hide Battery %", &CrossPointSettings::hideBatteryPercentage, {"Never", "In Reader", "Always"},
+                        "hideBatteryPercentage", "Display"),
+      SettingInfo::Enum("Refresh Frequency", &CrossPointSettings::refreshFrequency,
+                        {"1 page", "5 pages", "10 pages", "15 pages", "30 pages"}, "refreshFrequency", "Display"),
+      SettingInfo::Enum("UI Theme", &CrossPointSettings::uiTheme, {"Classic", "Lyra"}, "uiTheme", "Display"),
+      SettingInfo::Toggle("Sunlight Fading Fix", &CrossPointSettings::fadingFix, "fadingFix", "Display"),
+
+      // --- Reader ---
+      SettingInfo::Enum("Font Family", &CrossPointSettings::fontFamily, {"Bookerly", "Noto Sans", "Open Dyslexic"},
+                        "fontFamily", "Reader"),
+      SettingInfo::Enum("Font Size", &CrossPointSettings::fontSize, {"Small", "Medium", "Large", "X Large"}, "fontSize",
+                        "Reader"),
+      SettingInfo::Enum("Line Spacing", &CrossPointSettings::lineSpacing, {"Tight", "Normal", "Wide"}, "lineSpacing",
+                        "Reader"),
+      SettingInfo::Value("Screen Margin", &CrossPointSettings::screenMargin, {5, 40, 5}, "screenMargin", "Reader"),
+      SettingInfo::Enum("Paragraph Alignment", &CrossPointSettings::paragraphAlignment,
+                        {"Justify", "Left", "Center", "Right", "Book's Style"}, "paragraphAlignment", "Reader"),
+      SettingInfo::Toggle("Book's Embedded Style", &CrossPointSettings::embeddedStyle, "embeddedStyle", "Reader"),
+      SettingInfo::Toggle("Hyphenation", &CrossPointSettings::hyphenationEnabled, "hyphenationEnabled", "Reader"),
+      SettingInfo::Enum("Reading Orientation", &CrossPointSettings::orientation,
+                        {"Portrait", "Landscape CW", "Inverted", "Landscape CCW"}, "orientation", "Reader"),
+      SettingInfo::Toggle("Extra Paragraph Spacing", &CrossPointSettings::extraParagraphSpacing,
+                          "extraParagraphSpacing", "Reader"),
+      SettingInfo::Toggle("Text Anti-Aliasing", &CrossPointSettings::textAntiAliasing, "textAntiAliasing", "Reader"),
+
+      // --- Controls ---
+      SettingInfo::Enum("Side Button Layout (reader)", &CrossPointSettings::sideButtonLayout,
+                        {"Prev, Next", "Next, Prev"}, "sideButtonLayout", "Controls"),
+      SettingInfo::Toggle("Long-press Chapter Skip", &CrossPointSettings::longPressChapterSkip, "longPressChapterSkip",
+                          "Controls"),
+      SettingInfo::Enum("Short Power Button Click", &CrossPointSettings::shortPwrBtn, {"Ignore", "Sleep", "Page Turn"},
+                        "shortPwrBtn", "Controls"),
+
+      // --- System ---
+      SettingInfo::Enum("Time to Sleep", &CrossPointSettings::sleepTimeout,
+                        {"1 min", "5 min", "10 min", "15 min", "30 min"}, "sleepTimeout", "System"),
+
+      // --- KOReader Sync (web-only, uses KOReaderCredentialStore) ---
+      SettingInfo::DynamicString(
+          "KOReader Username", [] { return KOREADER_STORE.getUsername(); },
+          [](const std::string& v) {
+            KOREADER_STORE.setCredentials(v, KOREADER_STORE.getPassword());
+            KOREADER_STORE.saveToFile();
+          },
+          "koUsername", "KOReader Sync"),
+      SettingInfo::DynamicString(
+          "KOReader Password", [] { return KOREADER_STORE.getPassword(); },
+          [](const std::string& v) {
+            KOREADER_STORE.setCredentials(KOREADER_STORE.getUsername(), v);
+            KOREADER_STORE.saveToFile();
+          },
+          "koPassword", "KOReader Sync"),
+      SettingInfo::DynamicString(
+          "Sync Server URL", [] { return KOREADER_STORE.getServerUrl(); },
+          [](const std::string& v) {
+            KOREADER_STORE.setServerUrl(v);
+            KOREADER_STORE.saveToFile();
+          },
+          "koServerUrl", "KOReader Sync"),
+      SettingInfo::DynamicEnum(
+          "Document Matching", {"Filename", "Binary"},
+          [] { return static_cast<uint8_t>(KOREADER_STORE.getMatchMethod()); },
+          [](uint8_t v) {
+            KOREADER_STORE.setMatchMethod(static_cast<DocumentMatchMethod>(v));
+            KOREADER_STORE.saveToFile();
+          },
+          "koMatchMethod", "KOReader Sync"),
+
+      // --- OPDS Browser (web-only, uses CrossPointSettings char arrays) ---
+      SettingInfo::String("OPDS Server URL", SETTINGS.opdsServerUrl, sizeof(SETTINGS.opdsServerUrl), "opdsServerUrl",
+                          "OPDS Browser"),
+      SettingInfo::String("OPDS Username", SETTINGS.opdsUsername, sizeof(SETTINGS.opdsUsername), "opdsUsername",
+                          "OPDS Browser"),
+      SettingInfo::String("OPDS Password", SETTINGS.opdsPassword, sizeof(SETTINGS.opdsPassword), "opdsPassword",
+                          "OPDS Browser"),
+  };
+}

src/WifiCredentialStore.cpp

@@ -1,7 +1,7 @@
 #include "WifiCredentialStore.h"
 
+#include <HalStorage.h>
 #include <HardwareSerial.h>
-#include <SDCardManager.h>
 #include <Serialization.h>
 
 // Initialize the static instance
@@ -29,10 +29,10 @@ void WifiCredentialStore::obfuscate(std::string& data) const {
 
 bool WifiCredentialStore::saveToFile() const {
   // Make sure the directory exists
-  SdMan.mkdir("/.crosspoint");
+  Storage.mkdir("/.crosspoint");
 
   FsFile file;
-  if (!SdMan.openFileForWrite("WCS", WIFI_FILE, file)) {
+  if (!Storage.openFileForWrite("WCS", WIFI_FILE, file)) {
     return false;
   }
 
@@ -60,7 +60,7 @@ bool WifiCredentialStore::saveToFile() const {
 
 bool WifiCredentialStore::loadFromFile() {
   FsFile file;
-  if (!SdMan.openFileForRead("WCS", WIFI_FILE, file)) {
+  if (!Storage.openFileForRead("WCS", WIFI_FILE, file)) {
     return false;
   }
 

src/activities/Activity.h

@@ -23,4 +23,5 @@ class Activity {
   virtual void loop() {}
   virtual bool skipLoopDelay() { return false; }
   virtual bool preventAutoSleep() { return false; }
+  virtual bool isReaderActivity() const { return false; }
 };

src/activities/boot_sleep/BootActivity.cpp

@@ -3,7 +3,7 @@
 #include <GfxRenderer.h>
 
 #include "fontIds.h"
-#include "images/CrossLarge.h"
+#include "images/Logo120.h"
 
 void BootActivity::onEnter() {
   Activity::onEnter();
@@ -12,7 +12,7 @@ void BootActivity::onEnter() {
   const auto pageHeight = renderer.getScreenHeight();
 
   renderer.clearScreen();
-  renderer.drawImage(CrossLarge, (pageWidth - 128) / 2, (pageHeight - 128) / 2, 128, 128);
+  renderer.drawImage(Logo120, (pageWidth - 120) / 2, (pageHeight - 120) / 2, 120, 120);
   renderer.drawCenteredText(UI_10_FONT_ID, pageHeight / 2 + 70, "CrossPoint", true, EpdFontFamily::BOLD);
   renderer.drawCenteredText(SMALL_FONT_ID, pageHeight / 2 + 95, "BOOTING");
   renderer.drawCenteredText(SMALL_FONT_ID, pageHeight - 30, CROSSPOINT_VERSION);

src/activities/boot_sleep/SleepActivity.cpp

@@ -1,53 +1,400 @@
 #include "SleepActivity.h"
 
+#include <BitmapHelpers.h>
 #include <Epub.h>
 #include <GfxRenderer.h>
-#include <SDCardManager.h>
+#include <HalStorage.h>
+#include <Serialization.h>
 #include <Txt.h>
 #include <Xtc.h>
 
+#include <algorithm>
+
 #include "CrossPointSettings.h"
 #include "CrossPointState.h"
+#include "components/UITheme.h"
 #include "fontIds.h"
-#include "images/CrossLarge.h"
+#include "images/Logo120.h"
 #include "util/StringUtils.h"
 
+namespace {
+
+// Number of source pixels along the image edge to average for the gradient color
+constexpr int EDGE_SAMPLE_DEPTH = 20;
+
+// Map a 2-bit quantized pixel value to an 8-bit grayscale value
+constexpr uint8_t val2bitToGray(uint8_t val2bit) { return val2bit * 85; }
+
+// Edge gradient data produced by sampleBitmapEdges and consumed by drawLetterboxGradients.
+// edgeA is the "first" edge (top or left), edgeB is the "second" edge (bottom or right).
+struct LetterboxGradientData {
+  uint8_t* edgeA = nullptr;
+  uint8_t* edgeB = nullptr;
+  int edgeCount = 0;
+  int letterboxA = 0;       // pixel size of the first letterbox area (top or left)
+  int letterboxB = 0;       // pixel size of the second letterbox area (bottom or right)
+  bool horizontal = false;  // true = top/bottom letterbox, false = left/right
+
+  void free() {
+    ::free(edgeA);
+    ::free(edgeB);
+    edgeA = nullptr;
+    edgeB = nullptr;
+  }
+};
+
+// Binary cache version for edge data files
+constexpr uint8_t EDGE_CACHE_VERSION = 1;
+
+// Load cached edge data from a binary file. Returns true if the cache was valid and loaded successfully.
+// Validates cache version and screen dimensions to detect stale data.
+bool loadEdgeCache(const std::string& path, int screenWidth, int screenHeight, LetterboxGradientData& data) {
+  FsFile file;
+  if (!Storage.openFileForRead("SLP", path, file)) return false;
+
+  uint8_t version;
+  serialization::readPod(file, version);
+  if (version != EDGE_CACHE_VERSION) {
+    file.close();
+    return false;
+  }
+
+  uint16_t cachedW, cachedH;
+  serialization::readPod(file, cachedW);
+  serialization::readPod(file, cachedH);
+  if (cachedW != static_cast<uint16_t>(screenWidth) || cachedH != static_cast<uint16_t>(screenHeight)) {
+    file.close();
+    return false;
+  }
+
+  uint8_t horizontal;
+  serialization::readPod(file, horizontal);
+  data.horizontal = (horizontal != 0);
+
+  uint16_t edgeCount;
+  serialization::readPod(file, edgeCount);
+  data.edgeCount = edgeCount;
+
+  int16_t lbA, lbB;
+  serialization::readPod(file, lbA);
+  serialization::readPod(file, lbB);
+  data.letterboxA = lbA;
+  data.letterboxB = lbB;
+
+  if (edgeCount == 0 || edgeCount > 2048) {
+    file.close();
+    return false;
+  }
+
+  data.edgeA = static_cast<uint8_t*>(malloc(edgeCount));
+  data.edgeB = static_cast<uint8_t*>(malloc(edgeCount));
+  if (!data.edgeA || !data.edgeB) {
+    data.free();
+    file.close();
+    return false;
+  }
+
+  if (file.read(data.edgeA, edgeCount) != static_cast<int>(edgeCount) ||
+      file.read(data.edgeB, edgeCount) != static_cast<int>(edgeCount)) {
+    data.free();
+    file.close();
+    return false;
+  }
+
+  file.close();
+  Serial.printf("[%lu] [SLP] Loaded edge cache from %s (%d edges)\n", millis(), path.c_str(), edgeCount);
+  return true;
+}
+
+// Save edge data to a binary cache file for reuse on subsequent sleep screens.
+bool saveEdgeCache(const std::string& path, int screenWidth, int screenHeight, const LetterboxGradientData& data) {
+  if (!data.edgeA || !data.edgeB || data.edgeCount <= 0) return false;
+
+  FsFile file;
+  if (!Storage.openFileForWrite("SLP", path, file)) return false;
+
+  serialization::writePod(file, EDGE_CACHE_VERSION);
+  serialization::writePod(file, static_cast<uint16_t>(screenWidth));
+  serialization::writePod(file, static_cast<uint16_t>(screenHeight));
+  serialization::writePod(file, static_cast<uint8_t>(data.horizontal ? 1 : 0));
+  serialization::writePod(file, static_cast<uint16_t>(data.edgeCount));
+  serialization::writePod(file, static_cast<int16_t>(data.letterboxA));
+  serialization::writePod(file, static_cast<int16_t>(data.letterboxB));
+  file.write(data.edgeA, data.edgeCount);
+  file.write(data.edgeB, data.edgeCount);
+  file.close();
+
+  Serial.printf("[%lu] [SLP] Saved edge cache to %s (%d edges)\n", millis(), path.c_str(), data.edgeCount);
+  return true;
+}
+
+// Read the bitmap once to sample the first/last EDGE_SAMPLE_DEPTH rows or columns.
+// Returns edge color arrays in source pixel resolution.  Caller must call data.free() when done.
+// After sampling the bitmap is rewound via rewindToData().
+LetterboxGradientData sampleBitmapEdges(const Bitmap& bitmap, int imgX, int imgY, int pageWidth, int pageHeight,
+                                        float scale, float cropX, float cropY) {
+  LetterboxGradientData data;
+
+  const int cropPixX = static_cast<int>(std::floor(bitmap.getWidth() * cropX / 2.0f));
+  const int cropPixY = static_cast<int>(std::floor(bitmap.getHeight() * cropY / 2.0f));
+  const int visibleWidth = bitmap.getWidth() - 2 * cropPixX;
+  const int visibleHeight = bitmap.getHeight() - 2 * cropPixY;
+
+  if (visibleWidth <= 0 || visibleHeight <= 0) return data;
+
+  const int outputRowSize = (bitmap.getWidth() + 3) / 4;
+  auto* outputRow = static_cast<uint8_t*>(malloc(outputRowSize));
+  auto* rowBytes = static_cast<uint8_t*>(malloc(bitmap.getRowBytes()));
+  if (!outputRow || !rowBytes) {
+    ::free(outputRow);
+    ::free(rowBytes);
+    return data;
+  }
+
+  if (imgY > 0) {
+    // Top/bottom letterboxing -- sample per-column averages of first/last N rows
+    data.horizontal = true;
+    data.edgeCount = visibleWidth;
+    const int scaledHeight = static_cast<int>(std::round(static_cast<float>(visibleHeight) * scale));
+    data.letterboxA = imgY;
+    data.letterboxB = pageHeight - imgY - scaledHeight;
+    if (data.letterboxB < 0) data.letterboxB = 0;
+
+    const int sampleRows = std::min(EDGE_SAMPLE_DEPTH, visibleHeight);
+
+    auto* accumTop = static_cast<uint32_t*>(calloc(visibleWidth, sizeof(uint32_t)));
+    auto* accumBot = static_cast<uint32_t*>(calloc(visibleWidth, sizeof(uint32_t)));
+    data.edgeA = static_cast<uint8_t*>(malloc(visibleWidth));
+    data.edgeB = static_cast<uint8_t*>(malloc(visibleWidth));
+
+    if (!accumTop || !accumBot || !data.edgeA || !data.edgeB) {
+      ::free(accumTop);
+      ::free(accumBot);
+      data.free();
+      ::free(outputRow);
+      ::free(rowBytes);
+      return data;
+    }
+
+    for (int bmpY = 0; bmpY < bitmap.getHeight(); bmpY++) {
+      if (bitmap.readNextRow(outputRow, rowBytes) != BmpReaderError::Ok) break;
+      const int logicalY = bitmap.isTopDown() ? bmpY : bitmap.getHeight() - 1 - bmpY;
+      if (logicalY < cropPixY || logicalY >= bitmap.getHeight() - cropPixY) continue;
+      const int outY = logicalY - cropPixY;
+
+      const bool inTop = (outY < sampleRows);
+      const bool inBot = (outY >= visibleHeight - sampleRows);
+      if (!inTop && !inBot) continue;
+
+      for (int bmpX = cropPixX; bmpX < bitmap.getWidth() - cropPixX; bmpX++) {
+        const int outX = bmpX - cropPixX;
+        const uint8_t val = (outputRow[bmpX / 4] >> (6 - ((bmpX * 2) % 8))) & 0x3;
+        const uint8_t gray = val2bitToGray(val);
+        if (inTop) accumTop[outX] += gray;
+        if (inBot) accumBot[outX] += gray;
+      }
+    }
+
+    for (int i = 0; i < visibleWidth; i++) {
+      data.edgeA[i] = static_cast<uint8_t>(accumTop[i] / sampleRows);
+      data.edgeB[i] = static_cast<uint8_t>(accumBot[i] / sampleRows);
+    }
+    ::free(accumTop);
+    ::free(accumBot);
+
+  } else if (imgX > 0) {
+    // Left/right letterboxing -- sample per-row averages of first/last N columns
+    data.horizontal = false;
+    data.edgeCount = visibleHeight;
+    const int scaledWidth = static_cast<int>(std::round(static_cast<float>(visibleWidth) * scale));
+    data.letterboxA = imgX;
+    data.letterboxB = pageWidth - imgX - scaledWidth;
+    if (data.letterboxB < 0) data.letterboxB = 0;
+
+    const int sampleCols = std::min(EDGE_SAMPLE_DEPTH, visibleWidth);
+
+    auto* accumLeft = static_cast<uint32_t*>(calloc(visibleHeight, sizeof(uint32_t)));
+    auto* accumRight = static_cast<uint32_t*>(calloc(visibleHeight, sizeof(uint32_t)));
+    data.edgeA = static_cast<uint8_t*>(malloc(visibleHeight));
+    data.edgeB = static_cast<uint8_t*>(malloc(visibleHeight));
+
+    if (!accumLeft || !accumRight || !data.edgeA || !data.edgeB) {
+      ::free(accumLeft);
+      ::free(accumRight);
+      data.free();
+      ::free(outputRow);
+      ::free(rowBytes);
+      return data;
+    }
+
+    for (int bmpY = 0; bmpY < bitmap.getHeight(); bmpY++) {
+      if (bitmap.readNextRow(outputRow, rowBytes) != BmpReaderError::Ok) break;
+      const int logicalY = bitmap.isTopDown() ? bmpY : bitmap.getHeight() - 1 - bmpY;
+      if (logicalY < cropPixY || logicalY >= bitmap.getHeight() - cropPixY) continue;
+      const int outY = logicalY - cropPixY;
+
+      // Sample left edge columns
+      for (int bmpX = cropPixX; bmpX < cropPixX + sampleCols; bmpX++) {
+        const uint8_t val = (outputRow[bmpX / 4] >> (6 - ((bmpX * 2) % 8))) & 0x3;
+        accumLeft[outY] += val2bitToGray(val);
+      }
+      // Sample right edge columns
+      for (int bmpX = bitmap.getWidth() - cropPixX - sampleCols; bmpX < bitmap.getWidth() - cropPixX; bmpX++) {
+        const uint8_t val = (outputRow[bmpX / 4] >> (6 - ((bmpX * 2) % 8))) & 0x3;
+        accumRight[outY] += val2bitToGray(val);
+      }
+    }
+
+    for (int i = 0; i < visibleHeight; i++) {
+      data.edgeA[i] = static_cast<uint8_t>(accumLeft[i] / sampleCols);
+      data.edgeB[i] = static_cast<uint8_t>(accumRight[i] / sampleCols);
+    }
+    ::free(accumLeft);
+    ::free(accumRight);
+  }
+
+  ::free(outputRow);
+  ::free(rowBytes);
+  bitmap.rewindToData();
+  return data;
+}
+
+// Draw dithered fills in the letterbox areas using the sampled edge colors.
+// fillMode selects the fill algorithm: SOLID (single dominant shade), BLENDED (per-pixel edge color),
+// or GRADIENT (per-pixel edge color interpolated toward targetColor).
+// targetColor is the color the gradient fades toward (255=white, 0=black); only used in GRADIENT mode.
+// Must be called once per render pass (BW, GRAYSCALE_LSB, GRAYSCALE_MSB).
+void drawLetterboxFill(GfxRenderer& renderer, const LetterboxGradientData& data, float scale, uint8_t fillMode,
+                       int targetColor) {
+  if (!data.edgeA || !data.edgeB || data.edgeCount <= 0) return;
+
+  const bool isSolid = (fillMode == CrossPointSettings::SLEEP_SCREEN_LETTERBOX_FILL::LETTERBOX_SOLID);
+  const bool isGradient = (fillMode == CrossPointSettings::SLEEP_SCREEN_LETTERBOX_FILL::LETTERBOX_GRADIENT);
+
+  // For SOLID mode, compute the dominant (average) shade for each edge once
+  uint8_t solidColorA = 0, solidColorB = 0;
+  if (isSolid) {
+    uint32_t sumA = 0, sumB = 0;
+    for (int i = 0; i < data.edgeCount; i++) {
+      sumA += data.edgeA[i];
+      sumB += data.edgeB[i];
+    }
+    solidColorA = static_cast<uint8_t>(sumA / data.edgeCount);
+    solidColorB = static_cast<uint8_t>(sumB / data.edgeCount);
+  }
+
+  // Helper: compute gray value for a pixel given the edge color and interpolation factor t (0..1)
+  // GRADIENT interpolates from edgeColor toward targetColor; SOLID and BLENDED return edgeColor directly.
+  auto computeGray = [&](int edgeColor, float t) -> int {
+    if (isGradient) return edgeColor + static_cast<int>(static_cast<float>(targetColor - edgeColor) * t);
+    return edgeColor;
+  };
+
+  if (data.horizontal) {
+    // Top letterbox
+    if (data.letterboxA > 0) {
+      const int imgTopY = data.letterboxA;
+      for (int screenY = 0; screenY < imgTopY; screenY++) {
+        const float t = static_cast<float>(imgTopY - screenY) / static_cast<float>(imgTopY);
+        for (int screenX = 0; screenX < renderer.getScreenWidth(); screenX++) {
+          int edgeColor;
+          if (isSolid) {
+            edgeColor = solidColorA;
+          } else {
+            int srcCol = static_cast<int>(screenX / scale);
+            srcCol = std::max(0, std::min(srcCol, data.edgeCount - 1));
+            edgeColor = data.edgeA[srcCol];
+          }
+          const int gray = computeGray(edgeColor, t);
+          renderer.drawPixelGray(screenX, screenY, quantizeNoiseDither(gray, screenX, screenY));
+        }
+      }
+    }
+
+    // Bottom letterbox
+    if (data.letterboxB > 0) {
+      const int imgBottomY = renderer.getScreenHeight() - data.letterboxB;
+      for (int screenY = imgBottomY; screenY < renderer.getScreenHeight(); screenY++) {
+        const float t = static_cast<float>(screenY - imgBottomY + 1) / static_cast<float>(data.letterboxB);
+        for (int screenX = 0; screenX < renderer.getScreenWidth(); screenX++) {
+          int edgeColor;
+          if (isSolid) {
+            edgeColor = solidColorB;
+          } else {
+            int srcCol = static_cast<int>(screenX / scale);
+            srcCol = std::max(0, std::min(srcCol, data.edgeCount - 1));
+            edgeColor = data.edgeB[srcCol];
+          }
+          const int gray = computeGray(edgeColor, t);
+          renderer.drawPixelGray(screenX, screenY, quantizeNoiseDither(gray, screenX, screenY));
+        }
+      }
+    }
+  } else {
+    // Left letterbox
+    if (data.letterboxA > 0) {
+      const int imgLeftX = data.letterboxA;
+      for (int screenX = 0; screenX < imgLeftX; screenX++) {
+        const float t = static_cast<float>(imgLeftX - screenX) / static_cast<float>(imgLeftX);
+        for (int screenY = 0; screenY < renderer.getScreenHeight(); screenY++) {
+          int edgeColor;
+          if (isSolid) {
+            edgeColor = solidColorA;
+          } else {
+            int srcRow = static_cast<int>(screenY / scale);
+            srcRow = std::max(0, std::min(srcRow, data.edgeCount - 1));
+            edgeColor = data.edgeA[srcRow];
+          }
+          const int gray = computeGray(edgeColor, t);
+          renderer.drawPixelGray(screenX, screenY, quantizeNoiseDither(gray, screenX, screenY));
+        }
+      }
+    }
+
+    // Right letterbox
+    if (data.letterboxB > 0) {
+      const int imgRightX = renderer.getScreenWidth() - data.letterboxB;
+      for (int screenX = imgRightX; screenX < renderer.getScreenWidth(); screenX++) {
+        const float t = static_cast<float>(screenX - imgRightX + 1) / static_cast<float>(data.letterboxB);
+        for (int screenY = 0; screenY < renderer.getScreenHeight(); screenY++) {
+          int edgeColor;
+          if (isSolid) {
+            edgeColor = solidColorB;
+          } else {
+            int srcRow = static_cast<int>(screenY / scale);
+            srcRow = std::max(0, std::min(srcRow, data.edgeCount - 1));
+            edgeColor = data.edgeB[srcRow];
+          }
+          const int gray = computeGray(edgeColor, t);
+          renderer.drawPixelGray(screenX, screenY, quantizeNoiseDither(gray, screenX, screenY));
+        }
+      }
+    }
+  }
+}
+
+}  // namespace
+
 void SleepActivity::onEnter() {
   Activity::onEnter();
-  renderPopup("Entering Sleep...");
+  GUI.drawPopup(renderer, "Entering Sleep...");
 
-  if (SETTINGS.sleepScreen == CrossPointSettings::SLEEP_SCREEN_MODE::BLANK) {
-    return renderBlankSleepScreen();
+  switch (SETTINGS.sleepScreen) {
+    case (CrossPointSettings::SLEEP_SCREEN_MODE::BLANK):
+      return renderBlankSleepScreen();
+    case (CrossPointSettings::SLEEP_SCREEN_MODE::CUSTOM):
+      return renderCustomSleepScreen();
+    case (CrossPointSettings::SLEEP_SCREEN_MODE::COVER):
+    case (CrossPointSettings::SLEEP_SCREEN_MODE::COVER_CUSTOM):
+      return renderCoverSleepScreen();
+    default:
+      return renderDefaultSleepScreen();
   }
-
-  if (SETTINGS.sleepScreen == CrossPointSettings::SLEEP_SCREEN_MODE::CUSTOM) {
-    return renderCustomSleepScreen();
-  }
-
-  if (SETTINGS.sleepScreen == CrossPointSettings::SLEEP_SCREEN_MODE::COVER) {
-    return renderCoverSleepScreen();
-  }
-
-  renderDefaultSleepScreen();
-}
-
-void SleepActivity::renderPopup(const char* message) const {
-  const int textWidth = renderer.getTextWidth(UI_12_FONT_ID, message, EpdFontFamily::BOLD);
-  constexpr int margin = 20;
-  const int x = (renderer.getScreenWidth() - textWidth - margin * 2) / 2;
-  constexpr int y = 117;
-  const int w = textWidth + margin * 2;
-  const int h = renderer.getLineHeight(UI_12_FONT_ID) + margin * 2;
-  // renderer.clearScreen();
-  renderer.fillRect(x - 5, y - 5, w + 10, h + 10, true);
-  renderer.fillRect(x + 5, y + 5, w - 10, h - 10, false);
-  renderer.drawText(UI_12_FONT_ID, x + margin, y + margin, message, true, EpdFontFamily::BOLD);
-  renderer.displayBuffer();
 }
 
 void SleepActivity::renderCustomSleepScreen() const {
   // Check if we have a /sleep directory
-  auto dir = SdMan.open("/sleep");
+  auto dir = Storage.open("/sleep");
   if (dir && dir.isDirectory()) {
     std::vector<std::string> files;
     char name[500];
@@ -90,7 +437,7 @@ void SleepActivity::renderCustomSleepScreen() const {
       APP_STATE.saveToFile();
       const auto filename = "/sleep/" + files[randomFileIndex];
       FsFile file;
-      if (SdMan.openFileForRead("SLP", filename, file)) {
+      if (Storage.openFileForRead("SLP", filename, file)) {
         Serial.printf("[%lu] [SLP] Randomly loading: /sleep/%s\n", millis(), files[randomFileIndex].c_str());
         delay(100);
         Bitmap bitmap(file, true);
@@ -107,7 +454,7 @@ void SleepActivity::renderCustomSleepScreen() const {
   // Look for sleep.bmp on the root of the sd card to determine if we should
   // render a custom sleep screen instead of the default.
   FsFile file;
-  if (SdMan.openFileForRead("SLP", "/sleep.bmp", file)) {
+  if (Storage.openFileForRead("SLP", "/sleep.bmp", file)) {
     Bitmap bitmap(file, true);
     if (bitmap.parseHeaders() == BmpReaderError::Ok) {
       Serial.printf("[%lu] [SLP] Loading: /sleep.bmp\n", millis());
@@ -124,7 +471,7 @@ void SleepActivity::renderDefaultSleepScreen() const {
   const auto pageHeight = renderer.getScreenHeight();
 
   renderer.clearScreen();
-  renderer.drawImage(CrossLarge, (pageWidth - 128) / 2, (pageHeight - 128) / 2, 128, 128);
+  renderer.drawImage(Logo120, (pageWidth - 120) / 2, (pageHeight - 120) / 2, 120, 120);
   renderer.drawCenteredText(UI_10_FONT_ID, pageHeight / 2 + 70, "CrossPoint", true, EpdFontFamily::BOLD);
   renderer.drawCenteredText(SMALL_FONT_ID, pageHeight / 2 + 95, "SLEEPING");
 
@@ -136,7 +483,7 @@ void SleepActivity::renderDefaultSleepScreen() const {
   renderer.displayBuffer(HalDisplay::HALF_REFRESH);
 }
 
-void SleepActivity::renderBitmapSleepScreen(const Bitmap& bitmap) const {
+void SleepActivity::renderBitmapSleepScreen(const Bitmap& bitmap, const std::string& edgeCachePath) const {
   int x, y;
   const auto pageWidth = renderer.getScreenWidth();
   const auto pageHeight = renderer.getScreenHeight();
@@ -144,45 +491,79 @@ void SleepActivity::renderBitmapSleepScreen(const Bitmap& bitmap) const {
 
   Serial.printf("[%lu] [SLP] bitmap %d x %d, screen %d x %d\n", millis(), bitmap.getWidth(), bitmap.getHeight(),
                 pageWidth, pageHeight);
-  if (bitmap.getWidth() > pageWidth || bitmap.getHeight() > pageHeight) {
-    // image will scale, make sure placement is right
-    float ratio = static_cast<float>(bitmap.getWidth()) / static_cast<float>(bitmap.getHeight());
-    const float screenRatio = static_cast<float>(pageWidth) / static_cast<float>(pageHeight);
 
-    Serial.printf("[%lu] [SLP] bitmap ratio: %f, screen ratio: %f\n", millis(), ratio, screenRatio);
-    if (ratio > screenRatio) {
-      // image wider than viewport ratio, scaled down image needs to be centered vertically
-      if (SETTINGS.sleepScreenCoverMode == CrossPointSettings::SLEEP_SCREEN_COVER_MODE::CROP) {
-        cropX = 1.0f - (screenRatio / ratio);
-        Serial.printf("[%lu] [SLP] Cropping bitmap x: %f\n", millis(), cropX);
-        ratio = (1.0f - cropX) * static_cast<float>(bitmap.getWidth()) / static_cast<float>(bitmap.getHeight());
-      }
-      x = 0;
-      y = std::round((static_cast<float>(pageHeight) - static_cast<float>(pageWidth) / ratio) / 2);
-      Serial.printf("[%lu] [SLP] Centering with ratio %f to y=%d\n", millis(), ratio, y);
-    } else {
-      // image taller than viewport ratio, scaled down image needs to be centered horizontally
-      if (SETTINGS.sleepScreenCoverMode == CrossPointSettings::SLEEP_SCREEN_COVER_MODE::CROP) {
-        cropY = 1.0f - (ratio / screenRatio);
-        Serial.printf("[%lu] [SLP] Cropping bitmap y: %f\n", millis(), cropY);
-        ratio = static_cast<float>(bitmap.getWidth()) / ((1.0f - cropY) * static_cast<float>(bitmap.getHeight()));
-      }
-      x = std::round((static_cast<float>(pageWidth) - static_cast<float>(pageHeight) * ratio) / 2);
-      y = 0;
-      Serial.printf("[%lu] [SLP] Centering with ratio %f to x=%d\n", millis(), ratio, x);
+  // Always compute aspect-ratio-preserving scale and position (supports both larger and smaller images)
+  float ratio = static_cast<float>(bitmap.getWidth()) / static_cast<float>(bitmap.getHeight());
+  const float screenRatio = static_cast<float>(pageWidth) / static_cast<float>(pageHeight);
+
+  Serial.printf("[%lu] [SLP] bitmap ratio: %f, screen ratio: %f\n", millis(), ratio, screenRatio);
+  if (ratio > screenRatio) {
+    // image wider than viewport ratio, needs to be centered vertically
+    if (SETTINGS.sleepScreenCoverMode == CrossPointSettings::SLEEP_SCREEN_COVER_MODE::CROP) {
+      cropX = 1.0f - (screenRatio / ratio);
+      Serial.printf("[%lu] [SLP] Cropping bitmap x: %f\n", millis(), cropX);
+      ratio = (1.0f - cropX) * static_cast<float>(bitmap.getWidth()) / static_cast<float>(bitmap.getHeight());
     }
+    x = 0;
+    y = std::round((static_cast<float>(pageHeight) - static_cast<float>(pageWidth) / ratio) / 2);
+    Serial.printf("[%lu] [SLP] Centering with ratio %f to y=%d\n", millis(), ratio, y);
   } else {
-    // center the image
-    x = (pageWidth - bitmap.getWidth()) / 2;
-    y = (pageHeight - bitmap.getHeight()) / 2;
+    // image taller than or equal to viewport ratio, needs to be centered horizontally
+    if (SETTINGS.sleepScreenCoverMode == CrossPointSettings::SLEEP_SCREEN_COVER_MODE::CROP) {
+      cropY = 1.0f - (ratio / screenRatio);
+      Serial.printf("[%lu] [SLP] Cropping bitmap y: %f\n", millis(), cropY);
+      ratio = static_cast<float>(bitmap.getWidth()) / ((1.0f - cropY) * static_cast<float>(bitmap.getHeight()));
+    }
+    x = std::round((static_cast<float>(pageWidth) - static_cast<float>(pageHeight) * ratio) / 2);
+    y = 0;
+    Serial.printf("[%lu] [SLP] Centering with ratio %f to x=%d\n", millis(), ratio, x);
   }
 
   Serial.printf("[%lu] [SLP] drawing to %d x %d\n", millis(), x, y);
+
+  // Compute the scale factor (same formula as drawBitmap) so we can map screen coords to source coords
+  const float effectiveWidth = (1.0f - cropX) * bitmap.getWidth();
+  const float effectiveHeight = (1.0f - cropY) * bitmap.getHeight();
+  const float scale =
+      std::min(static_cast<float>(pageWidth) / effectiveWidth, static_cast<float>(pageHeight) / effectiveHeight);
+
+  // Determine letterbox fill settings
+  const uint8_t fillMode = SETTINGS.sleepScreenLetterboxFill;
+  const bool wantFill = (fillMode != CrossPointSettings::SLEEP_SCREEN_LETTERBOX_FILL::LETTERBOX_NONE);
+  const int targetColor =
+      (SETTINGS.sleepScreenGradientDir == CrossPointSettings::SLEEP_SCREEN_GRADIENT_DIR::GRADIENT_TO_BLACK) ? 0 : 255;
+
+  static const char* fillModeNames[] = {"none", "solid", "blended", "gradient"};
+  const char* fillModeName = (fillMode < 4) ? fillModeNames[fillMode] : "unknown";
+
+  // Load cached edge data or sample from bitmap (first pass over bitmap, then rewind)
+  LetterboxGradientData gradientData;
+  const bool hasLetterbox = (x > 0 || y > 0);
+  if (hasLetterbox && wantFill) {
+    bool cacheLoaded = false;
+    if (!edgeCachePath.empty()) {
+      cacheLoaded = loadEdgeCache(edgeCachePath, pageWidth, pageHeight, gradientData);
+    }
+    if (!cacheLoaded) {
+      Serial.printf("[%lu] [SLP] Letterbox detected (x=%d, y=%d), sampling edges for %s fill\n", millis(), x, y,
+                    fillModeName);
+      gradientData = sampleBitmapEdges(bitmap, x, y, pageWidth, pageHeight, scale, cropX, cropY);
+      if (!edgeCachePath.empty() && gradientData.edgeA) {
+        saveEdgeCache(edgeCachePath, pageWidth, pageHeight, gradientData);
+      }
+    }
+  }
+
   renderer.clearScreen();
 
   const bool hasGreyscale = bitmap.hasGreyscale() &&
                             SETTINGS.sleepScreenCoverFilter == CrossPointSettings::SLEEP_SCREEN_COVER_FILTER::NO_FILTER;
 
+  // Draw letterbox fill (BW pass)
+  if (gradientData.edgeA) {
+    drawLetterboxFill(renderer, gradientData, scale, fillMode, targetColor);
+  }
+
   renderer.drawBitmap(bitmap, x, y, pageWidth, pageHeight, cropX, cropY);
 
   if (SETTINGS.sleepScreenCoverFilter == CrossPointSettings::SLEEP_SCREEN_COVER_FILTER::INVERTED_BLACK_AND_WHITE) {
@@ -195,23 +576,41 @@ void SleepActivity::renderBitmapSleepScreen(const Bitmap& bitmap) const {
     bitmap.rewindToData();
     renderer.clearScreen(0x00);
     renderer.setRenderMode(GfxRenderer::GRAYSCALE_LSB);
+    if (gradientData.edgeA) {
+      drawLetterboxFill(renderer, gradientData, scale, fillMode, targetColor);
+    }
     renderer.drawBitmap(bitmap, x, y, pageWidth, pageHeight, cropX, cropY);
     renderer.copyGrayscaleLsbBuffers();
 
     bitmap.rewindToData();
     renderer.clearScreen(0x00);
     renderer.setRenderMode(GfxRenderer::GRAYSCALE_MSB);
+    if (gradientData.edgeA) {
+      drawLetterboxFill(renderer, gradientData, scale, fillMode, targetColor);
+    }
     renderer.drawBitmap(bitmap, x, y, pageWidth, pageHeight, cropX, cropY);
     renderer.copyGrayscaleMsbBuffers();
 
     renderer.displayGrayBuffer();
     renderer.setRenderMode(GfxRenderer::BW);
   }
+
+  gradientData.free();
 }
 
 void SleepActivity::renderCoverSleepScreen() const {
+  void (SleepActivity::*renderNoCoverSleepScreen)() const;
+  switch (SETTINGS.sleepScreen) {
+    case (CrossPointSettings::SLEEP_SCREEN_MODE::COVER_CUSTOM):
+      renderNoCoverSleepScreen = &SleepActivity::renderCustomSleepScreen;
+      break;
+    default:
+      renderNoCoverSleepScreen = &SleepActivity::renderDefaultSleepScreen;
+      break;
+  }
+
   if (APP_STATE.openEpubPath.empty()) {
-    return renderDefaultSleepScreen();
+    return (this->*renderNoCoverSleepScreen)();
   }
 
   std::string coverBmpPath;
@@ -224,12 +623,12 @@ void SleepActivity::renderCoverSleepScreen() const {
     Xtc lastXtc(APP_STATE.openEpubPath, "/.crosspoint");
     if (!lastXtc.load()) {
       Serial.println("[SLP] Failed to load last XTC");
-      return renderDefaultSleepScreen();
+      return (this->*renderNoCoverSleepScreen)();
     }
 
     if (!lastXtc.generateCoverBmp()) {
       Serial.println("[SLP] Failed to generate XTC cover bmp");
-      return renderDefaultSleepScreen();
+      return (this->*renderNoCoverSleepScreen)();
     }
 
     coverBmpPath = lastXtc.getCoverBmpPath();
@@ -238,44 +637,51 @@ void SleepActivity::renderCoverSleepScreen() const {
     Txt lastTxt(APP_STATE.openEpubPath, "/.crosspoint");
     if (!lastTxt.load()) {
       Serial.println("[SLP] Failed to load last TXT");
-      return renderDefaultSleepScreen();
+      return (this->*renderNoCoverSleepScreen)();
     }
 
     if (!lastTxt.generateCoverBmp()) {
       Serial.println("[SLP] No cover image found for TXT file");
-      return renderDefaultSleepScreen();
+      return (this->*renderNoCoverSleepScreen)();
     }
 
     coverBmpPath = lastTxt.getCoverBmpPath();
   } else if (StringUtils::checkFileExtension(APP_STATE.openEpubPath, ".epub")) {
     // Handle EPUB file
     Epub lastEpub(APP_STATE.openEpubPath, "/.crosspoint");
-    if (!lastEpub.load()) {
+    // Skip loading css since we only need metadata here
+    if (!lastEpub.load(true, true)) {
       Serial.println("[SLP] Failed to load last epub");
-      return renderDefaultSleepScreen();
+      return (this->*renderNoCoverSleepScreen)();
     }
 
     if (!lastEpub.generateCoverBmp(cropped)) {
       Serial.println("[SLP] Failed to generate cover bmp");
-      return renderDefaultSleepScreen();
+      return (this->*renderNoCoverSleepScreen)();
     }
 
     coverBmpPath = lastEpub.getCoverBmpPath(cropped);
   } else {
-    return renderDefaultSleepScreen();
+    return (this->*renderNoCoverSleepScreen)();
+  }
+
+  // Derive edge cache path from cover BMP path (e.g. cover.bmp -> cover_edges.bin)
+  std::string edgeCachePath;
+  if (coverBmpPath.size() > 4) {
+    edgeCachePath = coverBmpPath.substr(0, coverBmpPath.size() - 4) + "_edges.bin";
   }
 
   FsFile file;
-  if (SdMan.openFileForRead("SLP", coverBmpPath, file)) {
+  if (Storage.openFileForRead("SLP", coverBmpPath, file)) {
     Bitmap bitmap(file);
     if (bitmap.parseHeaders() == BmpReaderError::Ok) {
-      Serial.printf("[SLP] Rendering sleep cover: %s\n", coverBmpPath);
-      renderBitmapSleepScreen(bitmap);
+      Serial.printf("[SLP] Rendering sleep cover: %s\n", coverBmpPath.c_str());
+      renderBitmapSleepScreen(bitmap, edgeCachePath);
       return;
     }
   }
 
-  renderDefaultSleepScreen();
+  return (this->*renderNoCoverSleepScreen)();
 }
 
 void SleepActivity::renderBlankSleepScreen() const {

src/activities/boot_sleep/SleepActivity.h

@@ -1,4 +1,6 @@
 #pragma once
+#include <string>
+
 #include "../Activity.h"
 
 class Bitmap;
@@ -10,10 +12,9 @@ class SleepActivity final : public Activity {
   void onEnter() override;
 
  private:
-  void renderPopup(const char* message) const;
   void renderDefaultSleepScreen() const;
   void renderCustomSleepScreen() const;
   void renderCoverSleepScreen() const;
-  void renderBitmapSleepScreen(const Bitmap& bitmap) const;
+  void renderBitmapSleepScreen(const Bitmap& bitmap, const std::string& edgeCachePath = "") const;
   void renderBlankSleepScreen() const;
 };

src/activities/browser/OpdsBookBrowserActivity.cpp

@@ -8,8 +8,8 @@
 
 #include "CrossPointSettings.h"
 #include "MappedInputManager.h"
-#include "ScreenComponents.h"
 #include "activities/network/WifiSelectionActivity.h"
+#include "components/UITheme.h"
 #include "fontIds.h"
 #include "network/HttpDownloader.h"
 #include "util/StringUtils.h"
@@ -176,7 +176,7 @@ void OpdsBookBrowserActivity::render() const {
   if (state == BrowserState::CHECK_WIFI) {
     renderer.drawCenteredText(UI_10_FONT_ID, pageHeight / 2, statusMessage.c_str());
     const auto labels = mappedInput.mapLabels("« Back", "", "", "");
-    renderer.drawButtonHints(UI_10_FONT_ID, labels.btn1, labels.btn2, labels.btn3, labels.btn4);
+    GUI.drawButtonHints(renderer, labels.btn1, labels.btn2, labels.btn3, labels.btn4);
     renderer.displayBuffer();
     return;
   }
@@ -184,7 +184,7 @@ void OpdsBookBrowserActivity::render() const {
   if (state == BrowserState::LOADING) {
     renderer.drawCenteredText(UI_10_FONT_ID, pageHeight / 2, statusMessage.c_str());
     const auto labels = mappedInput.mapLabels("« Back", "", "", "");
-    renderer.drawButtonHints(UI_10_FONT_ID, labels.btn1, labels.btn2, labels.btn3, labels.btn4);
+    GUI.drawButtonHints(renderer, labels.btn1, labels.btn2, labels.btn3, labels.btn4);
     renderer.displayBuffer();
     return;
   }
@@ -193,7 +193,7 @@ void OpdsBookBrowserActivity::render() const {
     renderer.drawCenteredText(UI_10_FONT_ID, pageHeight / 2 - 20, "Error:");
     renderer.drawCenteredText(UI_10_FONT_ID, pageHeight / 2 + 10, errorMessage.c_str());
     const auto labels = mappedInput.mapLabels("« Back", "Retry", "", "");
-    renderer.drawButtonHints(UI_10_FONT_ID, labels.btn1, labels.btn2, labels.btn3, labels.btn4);
+    GUI.drawButtonHints(renderer, labels.btn1, labels.btn2, labels.btn3, labels.btn4);
     renderer.displayBuffer();
     return;
   }
@@ -206,7 +206,7 @@ void OpdsBookBrowserActivity::render() const {
       constexpr int barHeight = 20;
       constexpr int barX = 50;
       const int barY = pageHeight / 2 + 20;
-      ScreenComponents::drawProgressBar(renderer, barX, barY, barWidth, barHeight, downloadProgress, downloadTotal);
+      GUI.drawProgressBar(renderer, Rect{barX, barY, barWidth, barHeight}, downloadProgress, downloadTotal);
     }
     renderer.displayBuffer();
     return;
@@ -219,7 +219,7 @@ void OpdsBookBrowserActivity::render() const {
     confirmLabel = "Download";
   }
   const auto labels = mappedInput.mapLabels("« Back", confirmLabel, "", "");
-  renderer.drawButtonHints(UI_10_FONT_ID, labels.btn1, labels.btn2, labels.btn3, labels.btn4);
+  GUI.drawButtonHints(renderer, labels.btn1, labels.btn2, labels.btn3, labels.btn4);
 
   if (entries.empty()) {
     renderer.drawCenteredText(UI_10_FONT_ID, pageHeight / 2, "No entries found");

src/activities/home/HomeActivity.cpp

@@ -3,7 +3,8 @@
 #include <Bitmap.h>
 #include <Epub.h>
 #include <GfxRenderer.h>
-#include <SDCardManager.h>
+#include <HalStorage.h>
+#include <Utf8.h>
 #include <Xtc.h>
 
 #include <cstring>
@@ -13,7 +14,8 @@
 #include "CrossPointSettings.h"
 #include "CrossPointState.h"
 #include "MappedInputManager.h"
-#include "ScreenComponents.h"
+#include "RecentBooksStore.h"
+#include "components/UITheme.h"
 #include "fontIds.h"
 #include "util/StringUtils.h"
 
@@ -23,79 +25,112 @@ void HomeActivity::taskTrampoline(void* param) {
 }
 
 int HomeActivity::getMenuItemCount() const {
-  int count = 3;  // My Library, File transfer, Settings
-  if (hasContinueReading) count++;
-  if (hasOpdsUrl) count++;
+  int count = 4;  // My Library, Recents, File transfer, Settings
+  if (!recentBooks.empty()) {
+    count += recentBooks.size();
+  }
+  if (hasOpdsUrl) {
+    count++;
+  }
   return count;
 }
 
+void HomeActivity::loadRecentBooks(int maxBooks) {
+  recentBooks.clear();
+  const auto& books = RECENT_BOOKS.getBooks();
+  recentBooks.reserve(std::min(static_cast<int>(books.size()), maxBooks));
+
+  for (const RecentBook& book : books) {
+    // Limit to maximum number of recent books
+    if (recentBooks.size() >= maxBooks) {
+      break;
+    }
+
+    // Skip if file no longer exists
+    if (!Storage.exists(book.path.c_str())) {
+      continue;
+    }
+
+    recentBooks.push_back(book);
+  }
+}
+
+void HomeActivity::loadRecentCovers(int coverHeight) {
+  recentsLoading = true;
+  bool showingLoading = false;
+  Rect popupRect;
+
+  int progress = 0;
+  for (RecentBook& book : recentBooks) {
+    if (!book.coverBmpPath.empty()) {
+      std::string coverPath = UITheme::getCoverThumbPath(book.coverBmpPath, coverHeight);
+      if (!Storage.exists(coverPath.c_str())) {
+        // If epub, try to load the metadata for title/author and cover
+        if (StringUtils::checkFileExtension(book.path, ".epub")) {
+          Epub epub(book.path, "/.crosspoint");
+          // Skip loading css since we only need metadata here
+          epub.load(false, true);
+
+          // Try to generate thumbnail image for Continue Reading card
+          if (!showingLoading) {
+            showingLoading = true;
+            popupRect = GUI.drawPopup(renderer, "Loading...");
+          }
+          GUI.fillPopupProgress(renderer, popupRect, 10 + progress * (90 / recentBooks.size()));
+          bool success = epub.generateThumbBmp(coverHeight);
+          if (!success) {
+            RECENT_BOOKS.updateBook(book.path, book.title, book.author, "");
+            book.coverBmpPath = "";
+          }
+          coverRendered = false;
+          updateRequired = true;
+        } else if (StringUtils::checkFileExtension(book.path, ".xtch") ||
+                   StringUtils::checkFileExtension(book.path, ".xtc")) {
+          // Handle XTC file
+          Xtc xtc(book.path, "/.crosspoint");
+          if (xtc.load()) {
+            // Try to generate thumbnail image for Continue Reading card
+            if (!showingLoading) {
+              showingLoading = true;
+              popupRect = GUI.drawPopup(renderer, "Loading...");
+            }
+            GUI.fillPopupProgress(renderer, popupRect, 10 + progress * (90 / recentBooks.size()));
+            bool success = xtc.generateThumbBmp(coverHeight);
+            if (!success) {
+              RECENT_BOOKS.updateBook(book.path, book.title, book.author, "");
+              book.coverBmpPath = "";
+            }
+            coverRendered = false;
+            updateRequired = true;
+          }
+        }
+      }
+    }
+    progress++;
+  }
+
+  recentsLoaded = true;
+  recentsLoading = false;
+}
+
 void HomeActivity::onEnter() {
   Activity::onEnter();
 
   renderingMutex = xSemaphoreCreateMutex();
 
-  // Check if we have a book to continue reading
-  hasContinueReading = !APP_STATE.openEpubPath.empty() && SdMan.exists(APP_STATE.openEpubPath.c_str());
-
   // Check if OPDS browser URL is configured
   hasOpdsUrl = strlen(SETTINGS.opdsServerUrl) > 0;
 
-  if (hasContinueReading) {
-    // Extract filename from path for display
-    lastBookTitle = APP_STATE.openEpubPath;
-    const size_t lastSlash = lastBookTitle.find_last_of('/');
-    if (lastSlash != std::string::npos) {
-      lastBookTitle = lastBookTitle.substr(lastSlash + 1);
-    }
-
-    // If epub, try to load the metadata for title/author and cover
-    if (StringUtils::checkFileExtension(lastBookTitle, ".epub")) {
-      Epub epub(APP_STATE.openEpubPath, "/.crosspoint");
-      epub.load(false);
-      if (!epub.getTitle().empty()) {
-        lastBookTitle = std::string(epub.getTitle());
-      }
-      if (!epub.getAuthor().empty()) {
-        lastBookAuthor = std::string(epub.getAuthor());
-      }
-      // Try to generate thumbnail image for Continue Reading card
-      if (epub.generateThumbBmp()) {
-        coverBmpPath = epub.getThumbBmpPath();
-        hasCoverImage = true;
-      }
-    } else if (StringUtils::checkFileExtension(lastBookTitle, ".xtch") ||
-               StringUtils::checkFileExtension(lastBookTitle, ".xtc")) {
-      // Handle XTC file
-      Xtc xtc(APP_STATE.openEpubPath, "/.crosspoint");
-      if (xtc.load()) {
-        if (!xtc.getTitle().empty()) {
-          lastBookTitle = std::string(xtc.getTitle());
-        }
-        if (!xtc.getAuthor().empty()) {
-          lastBookAuthor = std::string(xtc.getAuthor());
-        }
-        // Try to generate thumbnail image for Continue Reading card
-        if (xtc.generateThumbBmp()) {
-          coverBmpPath = xtc.getThumbBmpPath();
-          hasCoverImage = true;
-        }
-      }
-      // Remove extension from title if we don't have metadata
-      if (StringUtils::checkFileExtension(lastBookTitle, ".xtch")) {
-        lastBookTitle.resize(lastBookTitle.length() - 5);
-      } else if (StringUtils::checkFileExtension(lastBookTitle, ".xtc")) {
-        lastBookTitle.resize(lastBookTitle.length() - 4);
-      }
-    }
-  }
-
   selectorIndex = 0;
 
+  auto metrics = UITheme::getInstance().getMetrics();
+  loadRecentBooks(metrics.homeRecentBooksCount);
+
   // Trigger first update
   updateRequired = true;
 
   xTaskCreate(&HomeActivity::taskTrampoline, "HomeActivityTask",
-              4096,               // Stack size (increased for cover image rendering)
+              8192,               // Stack size
               this,               // Parameters
               1,                  // Priority
               &displayTaskHandle  // Task handle
@@ -171,21 +206,24 @@ void HomeActivity::loop() {
   if (mappedInput.wasReleased(MappedInputManager::Button::Confirm)) {
     // Calculate dynamic indices based on which options are available
     int idx = 0;
-    const int continueIdx = hasContinueReading ? idx++ : -1;
+    int menuSelectedIndex = selectorIndex - static_cast<int>(recentBooks.size());
     const int myLibraryIdx = idx++;
+    const int recentsIdx = idx++;
     const int opdsLibraryIdx = hasOpdsUrl ? idx++ : -1;
     const int fileTransferIdx = idx++;
     const int settingsIdx = idx;
 
-    if (selectorIndex == continueIdx) {
-      onContinueReading();
-    } else if (selectorIndex == myLibraryIdx) {
+    if (selectorIndex < recentBooks.size()) {
+      onSelectBook(recentBooks[selectorIndex].path);
+    } else if (menuSelectedIndex == myLibraryIdx) {
       onMyLibraryOpen();
-    } else if (selectorIndex == opdsLibraryIdx) {
+    } else if (menuSelectedIndex == recentsIdx) {
+      onRecentsOpen();
+    } else if (menuSelectedIndex == opdsLibraryIdx) {
       onOpdsBrowserOpen();
-    } else if (selectorIndex == fileTransferIdx) {
+    } else if (menuSelectedIndex == fileTransferIdx) {
       onFileTransferOpen();
-    } else if (selectorIndex == settingsIdx) {
+    } else if (menuSelectedIndex == settingsIdx) {
       onSettingsOpen();
     }
   } else if (prevPressed) {
@@ -210,350 +248,44 @@ void HomeActivity::displayTaskLoop() {
 }
 
 void HomeActivity::render() {
-  // If we have a stored cover buffer, restore it instead of clearing
-  const bool bufferRestored = coverBufferStored && restoreCoverBuffer();
-  if (!bufferRestored) {
-    renderer.clearScreen();
-  }
-
+  auto metrics = UITheme::getInstance().getMetrics();
   const auto pageWidth = renderer.getScreenWidth();
   const auto pageHeight = renderer.getScreenHeight();
 
-  constexpr int margin = 20;
-  constexpr int bottomMargin = 60;
+  renderer.clearScreen();
+  bool bufferRestored = coverBufferStored && restoreCoverBuffer();
 
-  // --- Top "book" card for the current title (selectorIndex == 0) ---
-  const int bookWidth = pageWidth / 2;
-  const int bookHeight = pageHeight / 2;
-  const int bookX = (pageWidth - bookWidth) / 2;
-  constexpr int bookY = 30;
-  const bool bookSelected = hasContinueReading && selectorIndex == 0;
+  GUI.drawHeader(renderer, Rect{0, metrics.topPadding, pageWidth, metrics.homeTopPadding}, nullptr);
 
-  // Bookmark dimensions (used in multiple places)
-  const int bookmarkWidth = bookWidth / 8;
-  const int bookmarkHeight = bookHeight / 5;
-  const int bookmarkX = bookX + bookWidth - bookmarkWidth - 10;
-  const int bookmarkY = bookY + 5;
+  GUI.drawRecentBookCover(renderer, Rect{0, metrics.homeTopPadding, pageWidth, metrics.homeCoverTileHeight},
+                          recentBooks, selectorIndex, coverRendered, coverBufferStored, bufferRestored,
+                          std::bind(&HomeActivity::storeCoverBuffer, this));
 
-  // Draw book card regardless, fill with message based on `hasContinueReading`
-  {
-    // Draw cover image as background if available (inside the box)
-    // Only load from SD on first render, then use stored buffer
-    if (hasContinueReading && hasCoverImage && !coverBmpPath.empty() && !coverRendered) {
-      // First time: load cover from SD and render
-      FsFile file;
-      if (SdMan.openFileForRead("HOME", coverBmpPath, file)) {
-        Bitmap bitmap(file);
-        if (bitmap.parseHeaders() == BmpReaderError::Ok) {
-          // Calculate position to center image within the book card
-          int coverX, coverY;
-
-          if (bitmap.getWidth() > bookWidth || bitmap.getHeight() > bookHeight) {
-            const float imgRatio = static_cast<float>(bitmap.getWidth()) / static_cast<float>(bitmap.getHeight());
-            const float boxRatio = static_cast<float>(bookWidth) / static_cast<float>(bookHeight);
-
-            if (imgRatio > boxRatio) {
-              coverX = bookX;
-              coverY = bookY + (bookHeight - static_cast<int>(bookWidth / imgRatio)) / 2;
-            } else {
-              coverX = bookX + (bookWidth - static_cast<int>(bookHeight * imgRatio)) / 2;
-              coverY = bookY;
-            }
-          } else {
-            coverX = bookX + (bookWidth - bitmap.getWidth()) / 2;
-            coverY = bookY + (bookHeight - bitmap.getHeight()) / 2;
-          }
-
-          // Draw the cover image centered within the book card
-          renderer.drawBitmap(bitmap, coverX, coverY, bookWidth, bookHeight);
-
-          // Draw border around the card
-          renderer.drawRect(bookX, bookY, bookWidth, bookHeight);
-
-          // No bookmark ribbon when cover is shown - it would just cover the art
-
-          // Store the buffer with cover image for fast navigation
-          coverBufferStored = storeCoverBuffer();
-          coverRendered = true;
-
-          // First render: if selected, draw selection indicators now
-          if (bookSelected) {
-            renderer.drawRect(bookX + 1, bookY + 1, bookWidth - 2, bookHeight - 2);
-            renderer.drawRect(bookX + 2, bookY + 2, bookWidth - 4, bookHeight - 4);
-          }
-        }
-        file.close();
-      }
-    } else if (!bufferRestored && !coverRendered) {
-      // No cover image: draw border or fill, plus bookmark as visual flair
-      if (bookSelected) {
-        renderer.fillRect(bookX, bookY, bookWidth, bookHeight);
-      } else {
-        renderer.drawRect(bookX, bookY, bookWidth, bookHeight);
-      }
-
-      // Draw bookmark ribbon when no cover image (visual decoration)
-      if (hasContinueReading) {
-        const int notchDepth = bookmarkHeight / 3;
-        const int centerX = bookmarkX + bookmarkWidth / 2;
-
-        const int xPoints[5] = {
-            bookmarkX,                  // top-left
-            bookmarkX + bookmarkWidth,  // top-right
-            bookmarkX + bookmarkWidth,  // bottom-right
-            centerX,                    // center notch point
-            bookmarkX                   // bottom-left
-        };
-        const int yPoints[5] = {
-            bookmarkY,                                // top-left
-            bookmarkY,                                // top-right
-            bookmarkY + bookmarkHeight,               // bottom-right
-            bookmarkY + bookmarkHeight - notchDepth,  // center notch point
-            bookmarkY + bookmarkHeight                // bottom-left
-        };
-
-        // Draw bookmark ribbon (inverted if selected)
-        renderer.fillPolygon(xPoints, yPoints, 5, !bookSelected);
-      }
-    }
-
-    // If buffer was restored, draw selection indicators if needed
-    if (bufferRestored && bookSelected && coverRendered) {
-      // Draw selection border (no bookmark inversion needed since cover has no bookmark)
-      renderer.drawRect(bookX + 1, bookY + 1, bookWidth - 2, bookHeight - 2);
-      renderer.drawRect(bookX + 2, bookY + 2, bookWidth - 4, bookHeight - 4);
-    } else if (!coverRendered && !bufferRestored) {
-      // Selection border already handled above in the no-cover case
-    }
-  }
-
-  if (hasContinueReading) {
-    // Invert text colors based on selection state:
-    // - With cover: selected = white text on black box, unselected = black text on white box
-    // - Without cover: selected = white text on black card, unselected = black text on white card
-
-    // Split into words (avoid stringstream to keep this light on the MCU)
-    std::vector<std::string> words;
-    words.reserve(8);
-    size_t pos = 0;
-    while (pos < lastBookTitle.size()) {
-      while (pos < lastBookTitle.size() && lastBookTitle[pos] == ' ') {
-        ++pos;
-      }
-      if (pos >= lastBookTitle.size()) {
-        break;
-      }
-      const size_t start = pos;
-      while (pos < lastBookTitle.size() && lastBookTitle[pos] != ' ') {
-        ++pos;
-      }
-      words.emplace_back(lastBookTitle.substr(start, pos - start));
-    }
-
-    std::vector<std::string> lines;
-    std::string currentLine;
-    // Extra padding inside the card so text doesn't hug the border
-    const int maxLineWidth = bookWidth - 40;
-    const int spaceWidth = renderer.getSpaceWidth(UI_12_FONT_ID);
-
-    for (auto& i : words) {
-      // If we just hit the line limit (3), stop processing words
-      if (lines.size() >= 3) {
-        // Limit to 3 lines
-        // Still have words left, so add ellipsis to last line
-        lines.back().append("...");
-
-        while (!lines.back().empty() && renderer.getTextWidth(UI_12_FONT_ID, lines.back().c_str()) > maxLineWidth) {
-          // Remove "..." first, then remove one UTF-8 char, then add "..." back
-          lines.back().resize(lines.back().size() - 3);  // Remove "..."
-          StringUtils::utf8RemoveLastChar(lines.back());
-          lines.back().append("...");
-        }
-        break;
-      }
-
-      int wordWidth = renderer.getTextWidth(UI_12_FONT_ID, i.c_str());
-      while (wordWidth > maxLineWidth && !i.empty()) {
-        // Word itself is too long, trim it (UTF-8 safe)
-        StringUtils::utf8RemoveLastChar(i);
-        // Check if we have room for ellipsis
-        std::string withEllipsis = i + "...";
-        wordWidth = renderer.getTextWidth(UI_12_FONT_ID, withEllipsis.c_str());
-        if (wordWidth <= maxLineWidth) {
-          i = withEllipsis;
-          break;
-        }
-      }
-
-      int newLineWidth = renderer.getTextWidth(UI_12_FONT_ID, currentLine.c_str());
-      if (newLineWidth > 0) {
-        newLineWidth += spaceWidth;
-      }
-      newLineWidth += wordWidth;
-
-      if (newLineWidth > maxLineWidth && !currentLine.empty()) {
-        // New line too long, push old line
-        lines.push_back(currentLine);
-        currentLine = i;
-      } else {
-        currentLine.append(" ").append(i);
-      }
-    }
-
-    // If lower than the line limit, push remaining words
-    if (!currentLine.empty() && lines.size() < 3) {
-      lines.push_back(currentLine);
-    }
-
-    // Book title text
-    int totalTextHeight = renderer.getLineHeight(UI_12_FONT_ID) * static_cast<int>(lines.size());
-    if (!lastBookAuthor.empty()) {
-      totalTextHeight += renderer.getLineHeight(UI_10_FONT_ID) * 3 / 2;
-    }
-
-    // Vertically center the title block within the card
-    int titleYStart = bookY + (bookHeight - totalTextHeight) / 2;
-
-    // If cover image was rendered, draw box behind title and author
-    if (coverRendered) {
-      constexpr int boxPadding = 8;
-      // Calculate the max text width for the box
-      int maxTextWidth = 0;
-      for (const auto& line : lines) {
-        const int lineWidth = renderer.getTextWidth(UI_12_FONT_ID, line.c_str());
-        if (lineWidth > maxTextWidth) {
-          maxTextWidth = lineWidth;
-        }
-      }
-      if (!lastBookAuthor.empty()) {
-        std::string trimmedAuthor = lastBookAuthor;
-        while (renderer.getTextWidth(UI_10_FONT_ID, trimmedAuthor.c_str()) > maxLineWidth && !trimmedAuthor.empty()) {
-          StringUtils::utf8RemoveLastChar(trimmedAuthor);
-        }
-        if (renderer.getTextWidth(UI_10_FONT_ID, trimmedAuthor.c_str()) <
-            renderer.getTextWidth(UI_10_FONT_ID, lastBookAuthor.c_str())) {
-          trimmedAuthor.append("...");
-        }
-        const int authorWidth = renderer.getTextWidth(UI_10_FONT_ID, trimmedAuthor.c_str());
-        if (authorWidth > maxTextWidth) {
-          maxTextWidth = authorWidth;
-        }
-      }
-
-      const int boxWidth = maxTextWidth + boxPadding * 2;
-      const int boxHeight = totalTextHeight + boxPadding * 2;
-      const int boxX = (pageWidth - boxWidth) / 2;
-      const int boxY = titleYStart - boxPadding;
-
-      // Draw box (inverted when selected: black box instead of white)
-      renderer.fillRect(boxX, boxY, boxWidth, boxHeight, bookSelected);
-      // Draw border around the box (inverted when selected: white border instead of black)
-      renderer.drawRect(boxX, boxY, boxWidth, boxHeight, !bookSelected);
-    }
-
-    for (const auto& line : lines) {
-      renderer.drawCenteredText(UI_12_FONT_ID, titleYStart, line.c_str(), !bookSelected);
-      titleYStart += renderer.getLineHeight(UI_12_FONT_ID);
-    }
-
-    if (!lastBookAuthor.empty()) {
-      titleYStart += renderer.getLineHeight(UI_10_FONT_ID) / 2;
-      std::string trimmedAuthor = lastBookAuthor;
-      // Trim author if too long (UTF-8 safe)
-      bool wasTrimmed = false;
-      while (renderer.getTextWidth(UI_10_FONT_ID, trimmedAuthor.c_str()) > maxLineWidth && !trimmedAuthor.empty()) {
-        StringUtils::utf8RemoveLastChar(trimmedAuthor);
-        wasTrimmed = true;
-      }
-      if (wasTrimmed && !trimmedAuthor.empty()) {
-        // Make room for ellipsis
-        while (renderer.getTextWidth(UI_10_FONT_ID, (trimmedAuthor + "...").c_str()) > maxLineWidth &&
-               !trimmedAuthor.empty()) {
-          StringUtils::utf8RemoveLastChar(trimmedAuthor);
-        }
-        trimmedAuthor.append("...");
-      }
-      renderer.drawCenteredText(UI_10_FONT_ID, titleYStart, trimmedAuthor.c_str(), !bookSelected);
-    }
-
-    // "Continue Reading" label at the bottom
-    const int continueY = bookY + bookHeight - renderer.getLineHeight(UI_10_FONT_ID) * 3 / 2;
-    if (coverRendered) {
-      // Draw box behind "Continue Reading" text (inverted when selected: black box instead of white)
-      const char* continueText = "Continue Reading";
-      const int continueTextWidth = renderer.getTextWidth(UI_10_FONT_ID, continueText);
-      constexpr int continuePadding = 6;
-      const int continueBoxWidth = continueTextWidth + continuePadding * 2;
-      const int continueBoxHeight = renderer.getLineHeight(UI_10_FONT_ID) + continuePadding;
-      const int continueBoxX = (pageWidth - continueBoxWidth) / 2;
-      const int continueBoxY = continueY - continuePadding / 2;
-      renderer.fillRect(continueBoxX, continueBoxY, continueBoxWidth, continueBoxHeight, bookSelected);
-      renderer.drawRect(continueBoxX, continueBoxY, continueBoxWidth, continueBoxHeight, !bookSelected);
-      renderer.drawCenteredText(UI_10_FONT_ID, continueY, continueText, !bookSelected);
-    } else {
-      renderer.drawCenteredText(UI_10_FONT_ID, continueY, "Continue Reading", !bookSelected);
-    }
-  } else {
-    // No book to continue reading
-    const int y =
-        bookY + (bookHeight - renderer.getLineHeight(UI_12_FONT_ID) - renderer.getLineHeight(UI_10_FONT_ID)) / 2;
-    renderer.drawCenteredText(UI_12_FONT_ID, y, "No open book");
-    renderer.drawCenteredText(UI_10_FONT_ID, y + renderer.getLineHeight(UI_12_FONT_ID), "Start reading below");
-  }
-
-  // --- Bottom menu tiles ---
   // Build menu items dynamically
-  std::vector<const char*> menuItems = {"My Library", "File Transfer", "Settings"};
+  std::vector<const char*> menuItems = {"Browse Files", "Recents", "File Transfer", "Settings"};
   if (hasOpdsUrl) {
     // Insert OPDS Browser after My Library
-    menuItems.insert(menuItems.begin() + 1, "OPDS Browser");
+    menuItems.insert(menuItems.begin() + 2, "OPDS Browser");
   }
 
-  const int menuTileWidth = pageWidth - 2 * margin;
-  constexpr int menuTileHeight = 45;
-  constexpr int menuSpacing = 8;
-  const int totalMenuHeight =
-      static_cast<int>(menuItems.size()) * menuTileHeight + (static_cast<int>(menuItems.size()) - 1) * menuSpacing;
-
-  int menuStartY = bookY + bookHeight + 15;
-  // Ensure we don't collide with the bottom button legend
-  const int maxMenuStartY = pageHeight - bottomMargin - totalMenuHeight - margin;
-  if (menuStartY > maxMenuStartY) {
-    menuStartY = maxMenuStartY;
-  }
-
-  for (size_t i = 0; i < menuItems.size(); ++i) {
-    const int overallIndex = static_cast<int>(i) + (hasContinueReading ? 1 : 0);
-    constexpr int tileX = margin;
-    const int tileY = menuStartY + static_cast<int>(i) * (menuTileHeight + menuSpacing);
-    const bool selected = selectorIndex == overallIndex;
-
-    if (selected) {
-      renderer.fillRect(tileX, tileY, menuTileWidth, menuTileHeight);
-    } else {
-      renderer.drawRect(tileX, tileY, menuTileWidth, menuTileHeight);
-    }
-
-    const char* label = menuItems[i];
-    const int textWidth = renderer.getTextWidth(UI_10_FONT_ID, label);
-    const int textX = tileX + (menuTileWidth - textWidth) / 2;
-    const int lineHeight = renderer.getLineHeight(UI_10_FONT_ID);
-    const int textY = tileY + (menuTileHeight - lineHeight) / 2;  // vertically centered assuming y is top of text
-
-    // Invert text when the tile is selected, to contrast with the filled background
-    renderer.drawText(UI_10_FONT_ID, textX, textY, label, !selected);
-  }
+  GUI.drawButtonMenu(
+      renderer,
+      Rect{0, metrics.homeTopPadding + metrics.homeCoverTileHeight + metrics.verticalSpacing, pageWidth,
+           pageHeight - (metrics.headerHeight + metrics.homeTopPadding + metrics.verticalSpacing * 2 +
+                         metrics.buttonHintsHeight)},
+      static_cast<int>(menuItems.size()), selectorIndex - recentBooks.size(),
+      [&menuItems](int index) { return std::string(menuItems[index]); }, nullptr);
 
   const auto labels = mappedInput.mapLabels("", "Select", "Up", "Down");
-  renderer.drawButtonHints(UI_10_FONT_ID, labels.btn1, labels.btn2, labels.btn3, labels.btn4);
-
-  const bool showBatteryPercentage =
-      SETTINGS.hideBatteryPercentage != CrossPointSettings::HIDE_BATTERY_PERCENTAGE::HIDE_ALWAYS;
-  // get percentage so we can align text properly
-  const uint16_t percentage = battery.readPercentage();
-  const auto percentageText = showBatteryPercentage ? std::to_string(percentage) + "%" : "";
-  const auto batteryX = pageWidth - 25 - renderer.getTextWidth(SMALL_FONT_ID, percentageText.c_str());
-  ScreenComponents::drawBattery(renderer, batteryX, 10, showBatteryPercentage);
+  GUI.drawButtonHints(renderer, labels.btn1, labels.btn2, labels.btn3, labels.btn4);
 
   renderer.displayBuffer();
+
+  if (!firstRenderDone) {
+    firstRenderDone = true;
+    updateRequired = true;
+  } else if (!recentsLoaded && !recentsLoading) {
+    recentsLoading = true;
+    loadRecentCovers(metrics.homeCoverHeight);
+  }
 }

src/activities/home/HomeActivity.h

@@ -4,25 +4,30 @@
 #include <freertos/task.h>
 
 #include <functional>
+#include <vector>
 
 #include "../Activity.h"
+#include "./MyLibraryActivity.h"
+
+struct RecentBook;
+struct Rect;
 
 class HomeActivity final : public Activity {
   TaskHandle_t displayTaskHandle = nullptr;
   SemaphoreHandle_t renderingMutex = nullptr;
   int selectorIndex = 0;
   bool updateRequired = false;
-  bool hasContinueReading = false;
+  bool recentsLoading = false;
+  bool recentsLoaded = false;
+  bool firstRenderDone = false;
   bool hasOpdsUrl = false;
-  bool hasCoverImage = false;
   bool coverRendered = false;      // Track if cover has been rendered once
   bool coverBufferStored = false;  // Track if cover buffer is stored
   uint8_t* coverBuffer = nullptr;  // HomeActivity's own buffer for cover image
-  std::string lastBookTitle;
-  std::string lastBookAuthor;
-  std::string coverBmpPath;
-  const std::function<void()> onContinueReading;
+  std::vector<RecentBook> recentBooks;
+  const std::function<void(const std::string& path)> onSelectBook;
   const std::function<void()> onMyLibraryOpen;
+  const std::function<void()> onRecentsOpen;
   const std::function<void()> onSettingsOpen;
   const std::function<void()> onFileTransferOpen;
   const std::function<void()> onOpdsBrowserOpen;
@@ -34,15 +39,19 @@ class HomeActivity final : public Activity {
   bool storeCoverBuffer();    // Store frame buffer for cover image
   bool restoreCoverBuffer();  // Restore frame buffer from stored cover
   void freeCoverBuffer();     // Free the stored cover buffer
+  void loadRecentBooks(int maxBooks);
+  void loadRecentCovers(int coverHeight);
 
  public:
   explicit HomeActivity(GfxRenderer& renderer, MappedInputManager& mappedInput,
-                        const std::function<void()>& onContinueReading, const std::function<void()>& onMyLibraryOpen,
+                        const std::function<void(const std::string& path)>& onSelectBook,
+                        const std::function<void()>& onMyLibraryOpen, const std::function<void()>& onRecentsOpen,
                         const std::function<void()>& onSettingsOpen, const std::function<void()>& onFileTransferOpen,
                         const std::function<void()>& onOpdsBrowserOpen)
       : Activity("Home", renderer, mappedInput),
-        onContinueReading(onContinueReading),
+        onSelectBook(onSelectBook),
         onMyLibraryOpen(onMyLibraryOpen),
+        onRecentsOpen(onRecentsOpen),
         onSettingsOpen(onSettingsOpen),
         onFileTransferOpen(onFileTransferOpen),
         onOpdsBrowserOpen(onOpdsBrowserOpen) {}

src/activities/home/MyLibraryActivity.cpp

@@ -1,28 +1,19 @@
 #include "MyLibraryActivity.h"
 
 #include <GfxRenderer.h>
-#include <SDCardManager.h>
+#include <HalStorage.h>
 
 #include <algorithm>
 
 #include "MappedInputManager.h"
-#include "RecentBooksStore.h"
-#include "ScreenComponents.h"
+#include "components/UITheme.h"
 #include "fontIds.h"
 #include "util/StringUtils.h"
 
 namespace {
-// Layout constants
-constexpr int TAB_BAR_Y = 15;
-constexpr int CONTENT_START_Y = 60;
-constexpr int LINE_HEIGHT = 30;
-constexpr int RECENTS_LINE_HEIGHT = 65;  // Increased for two-line items
-constexpr int LEFT_MARGIN = 20;
-constexpr int RIGHT_MARGIN = 40;  // Extra space for scroll indicator
-
-// Timing thresholds
 constexpr int SKIP_PAGE_MS = 700;
 constexpr unsigned long GO_HOME_MS = 1000;
+}  // namespace
 
 void sortFileList(std::vector<std::string>& strs) {
   std::sort(begin(strs), end(strs), [](const std::string& str1, const std::string& str2) {
@@ -33,56 +24,16 @@ void sortFileList(std::vector<std::string>& strs) {
         [](const char& char1, const char& char2) { return tolower(char1) < tolower(char2); });
   });
 }
-}  // namespace
 
-int MyLibraryActivity::getPageItems() const {
-  const int screenHeight = renderer.getScreenHeight();
-  const int bottomBarHeight = 60;  // Space for button hints
-  const int availableHeight = screenHeight - CONTENT_START_Y - bottomBarHeight;
-  int items = availableHeight / LINE_HEIGHT;
-  if (items < 1) {
-    items = 1;
-  }
-  return items;
-}
-
-int MyLibraryActivity::getCurrentItemCount() const {
-  if (currentTab == Tab::Recent) {
-    return static_cast<int>(recentBooks.size());
-  }
-  return static_cast<int>(files.size());
-}
-
-int MyLibraryActivity::getTotalPages() const {
-  const int itemCount = getCurrentItemCount();
-  const int pageItems = getPageItems();
-  if (itemCount == 0) return 1;
-  return (itemCount + pageItems - 1) / pageItems;
-}
-
-int MyLibraryActivity::getCurrentPage() const {
-  const int pageItems = getPageItems();
-  return selectorIndex / pageItems + 1;
-}
-
-void MyLibraryActivity::loadRecentBooks() {
-  recentBooks.clear();
-  const auto& books = RECENT_BOOKS.getBooks();
-  recentBooks.reserve(books.size());
-
-  for (const auto& book : books) {
-    // Skip if file no longer exists
-    if (!SdMan.exists(book.path.c_str())) {
-      continue;
-    }
-    recentBooks.push_back(book);
-  }
+void MyLibraryActivity::taskTrampoline(void* param) {
+  auto* self = static_cast<MyLibraryActivity*>(param);
+  self->displayTaskLoop();
 }
 
 void MyLibraryActivity::loadFiles() {
   files.clear();
 
-  auto root = SdMan.open(basepath.c_str());
+  auto root = Storage.open(basepath.c_str());
   if (!root || !root.isDirectory()) {
     if (root) root.close();
     return;
@@ -114,32 +65,18 @@ void MyLibraryActivity::loadFiles() {
   sortFileList(files);
 }
 
-size_t MyLibraryActivity::findEntry(const std::string& name) const {
-  for (size_t i = 0; i < files.size(); i++) {
-    if (files[i] == name) return i;
-  }
-  return 0;
-}
-
-void MyLibraryActivity::taskTrampoline(void* param) {
-  auto* self = static_cast<MyLibraryActivity*>(param);
-  self->displayTaskLoop();
-}
-
 void MyLibraryActivity::onEnter() {
   Activity::onEnter();
 
   renderingMutex = xSemaphoreCreateMutex();
 
-  // Load data for both tabs
-  loadRecentBooks();
   loadFiles();
 
   selectorIndex = 0;
   updateRequired = true;
 
   xTaskCreate(&MyLibraryActivity::taskTrampoline, "MyLibraryActivityTask",
-              4096,               // Stack size (increased for epub metadata loading)
+              4096,               // Stack size
               this,               // Parameters
               1,                  // Priority
               &displayTaskHandle  // Task handle
@@ -149,8 +86,7 @@ void MyLibraryActivity::onEnter() {
 void MyLibraryActivity::onExit() {
   Activity::onExit();
 
-  // Wait until not rendering to delete task to avoid killing mid-instruction to
-  // EPD
+  // Wait until not rendering to delete task to avoid killing mid-instruction to EPD
   xSemaphoreTake(renderingMutex, portMAX_DELAY);
   if (displayTaskHandle) {
     vTaskDelete(displayTaskHandle);
@@ -163,107 +99,76 @@ void MyLibraryActivity::onExit() {
 }
 
 void MyLibraryActivity::loop() {
-  const int itemCount = getCurrentItemCount();
-  const int pageItems = getPageItems();
+  // Long press BACK (1s+) goes to root folder
+  if (mappedInput.isPressed(MappedInputManager::Button::Back) && mappedInput.getHeldTime() >= GO_HOME_MS &&
+      basepath != "/") {
+    basepath = "/";
+    loadFiles();
+    selectorIndex = 0;
+    updateRequired = true;
+    return;
+  }
 
-  // Long press BACK (1s+) in Files tab goes to root folder
-  if (currentTab == Tab::Files && mappedInput.isPressed(MappedInputManager::Button::Back) &&
-      mappedInput.getHeldTime() >= GO_HOME_MS) {
-    if (basepath != "/") {
-      basepath = "/";
+  const bool upReleased = mappedInput.wasReleased(MappedInputManager::Button::Left) ||
+                          mappedInput.wasReleased(MappedInputManager::Button::Up);
+  ;
+  const bool downReleased = mappedInput.wasReleased(MappedInputManager::Button::Right) ||
+                            mappedInput.wasReleased(MappedInputManager::Button::Down);
+
+  const bool skipPage = mappedInput.getHeldTime() > SKIP_PAGE_MS;
+  const int pageItems = UITheme::getInstance().getNumberOfItemsPerPage(renderer, true, false, true, false);
+
+  if (mappedInput.wasReleased(MappedInputManager::Button::Confirm)) {
+    if (files.empty()) {
+      return;
+    }
+
+    if (basepath.back() != '/') basepath += "/";
+    if (files[selectorIndex].back() == '/') {
+      basepath += files[selectorIndex].substr(0, files[selectorIndex].length() - 1);
       loadFiles();
       selectorIndex = 0;
       updateRequired = true;
-    }
-    return;
-  }
-
-  const bool upReleased = mappedInput.wasReleased(MappedInputManager::Button::Up);
-  const bool downReleased = mappedInput.wasReleased(MappedInputManager::Button::Down);
-  const bool leftReleased = mappedInput.wasReleased(MappedInputManager::Button::Left);
-  const bool rightReleased = mappedInput.wasReleased(MappedInputManager::Button::Right);
-
-  const bool skipPage = mappedInput.getHeldTime() > SKIP_PAGE_MS;
-
-  // Confirm button - open selected item
-  if (mappedInput.wasReleased(MappedInputManager::Button::Confirm)) {
-    if (currentTab == Tab::Recent) {
-      if (!recentBooks.empty() && selectorIndex < static_cast<int>(recentBooks.size())) {
-        onSelectBook(recentBooks[selectorIndex].path, currentTab);
-      }
     } else {
-      // Files tab
-      if (!files.empty() && selectorIndex < static_cast<int>(files.size())) {
-        if (basepath.back() != '/') basepath += "/";
-        if (files[selectorIndex].back() == '/') {
-          // Enter directory
-          basepath += files[selectorIndex].substr(0, files[selectorIndex].length() - 1);
-          loadFiles();
-          selectorIndex = 0;
-          updateRequired = true;
-        } else {
-          // Open file
-          onSelectBook(basepath + files[selectorIndex], currentTab);
-        }
-      }
+      onSelectBook(basepath + files[selectorIndex]);
+      return;
     }
-    return;
   }
 
-  // Back button
   if (mappedInput.wasReleased(MappedInputManager::Button::Back)) {
+    // Short press: go up one directory, or go home if at root
     if (mappedInput.getHeldTime() < GO_HOME_MS) {
-      if (currentTab == Tab::Files && basepath != "/") {
-        // Go up one directory, remembering the directory we came from
+      if (basepath != "/") {
         const std::string oldPath = basepath;
+
         basepath.replace(basepath.find_last_of('/'), std::string::npos, "");
         if (basepath.empty()) basepath = "/";
         loadFiles();
 
-        // Select the directory we just came from
         const auto pos = oldPath.find_last_of('/');
         const std::string dirName = oldPath.substr(pos + 1) + "/";
-        selectorIndex = static_cast<int>(findEntry(dirName));
+        selectorIndex = findEntry(dirName);
 
         updateRequired = true;
       } else {
-        // Go home
         onGoHome();
       }
     }
-    return;
   }
 
-  // Tab switching: Left/Right always control tabs
-  if (leftReleased && currentTab == Tab::Files) {
-    currentTab = Tab::Recent;
-    selectorIndex = 0;
-    updateRequired = true;
-    return;
-  }
-  if (rightReleased && currentTab == Tab::Recent) {
-    currentTab = Tab::Files;
-    selectorIndex = 0;
-    updateRequired = true;
-    return;
-  }
-
-  // Navigation: Up/Down moves through items only
-  const bool prevReleased = upReleased;
-  const bool nextReleased = downReleased;
-
-  if (prevReleased && itemCount > 0) {
+  int listSize = static_cast<int>(files.size());
+  if (upReleased) {
     if (skipPage) {
-      selectorIndex = ((selectorIndex / pageItems - 1) * pageItems + itemCount) % itemCount;
+      selectorIndex = std::max(static_cast<int>((selectorIndex / pageItems - 1) * pageItems), 0);
     } else {
-      selectorIndex = (selectorIndex + itemCount - 1) % itemCount;
+      selectorIndex = (selectorIndex + listSize - 1) % listSize;
     }
     updateRequired = true;
-  } else if (nextReleased && itemCount > 0) {
+  } else if (downReleased) {
     if (skipPage) {
-      selectorIndex = ((selectorIndex / pageItems + 1) * pageItems) % itemCount;
+      selectorIndex = std::min(static_cast<int>((selectorIndex / pageItems + 1) * pageItems), listSize - 1);
     } else {
-      selectorIndex = (selectorIndex + 1) % itemCount;
+      selectorIndex = (selectorIndex + 1) % listSize;
     }
     updateRequired = true;
   }
@@ -284,100 +189,32 @@ void MyLibraryActivity::displayTaskLoop() {
 void MyLibraryActivity::render() const {
   renderer.clearScreen();
 
-  // Draw tab bar
-  std::vector<TabInfo> tabs = {{"Recent", currentTab == Tab::Recent}, {"Files", currentTab == Tab::Files}};
-  ScreenComponents::drawTabBar(renderer, TAB_BAR_Y, tabs);
+  const auto pageWidth = renderer.getScreenWidth();
+  const auto pageHeight = renderer.getScreenHeight();
+  auto metrics = UITheme::getInstance().getMetrics();
 
-  // Draw content based on current tab
-  if (currentTab == Tab::Recent) {
-    renderRecentTab();
+  auto folderName = basepath == "/" ? "SD card" : basepath.substr(basepath.rfind('/') + 1).c_str();
+  GUI.drawHeader(renderer, Rect{0, metrics.topPadding, pageWidth, metrics.headerHeight}, folderName);
+
+  const int contentTop = metrics.topPadding + metrics.headerHeight + metrics.verticalSpacing;
+  const int contentHeight = pageHeight - contentTop - metrics.buttonHintsHeight - metrics.verticalSpacing;
+  if (files.empty()) {
+    renderer.drawText(UI_10_FONT_ID, metrics.contentSidePadding, contentTop + 20, "No books found");
   } else {
-    renderFilesTab();
+    GUI.drawList(
+        renderer, Rect{0, contentTop, pageWidth, contentHeight}, files.size(), selectorIndex,
+        [this](int index) { return files[index]; }, nullptr, nullptr, nullptr);
   }
 
-  // Draw scroll indicator
-  const int screenHeight = renderer.getScreenHeight();
-  const int contentHeight = screenHeight - CONTENT_START_Y - 60;  // 60 for bottom bar
-  ScreenComponents::drawScrollIndicator(renderer, getCurrentPage(), getTotalPages(), CONTENT_START_Y, contentHeight);
-
-  // Draw side button hints (up/down navigation on right side)
-  // Note: text is rotated 90° CW, so ">" appears as "^" and "<" appears as "v"
-  renderer.drawSideButtonHints(UI_10_FONT_ID, ">", "<");
-
-  // Draw bottom button hints
-  const auto labels = mappedInput.mapLabels("« Back", "Open", "<", ">");
-  renderer.drawButtonHints(UI_10_FONT_ID, labels.btn1, labels.btn2, labels.btn3, labels.btn4);
+  // Help text
+  const auto labels = mappedInput.mapLabels("« Home", "Open", "Up", "Down");
+  GUI.drawButtonHints(renderer, labels.btn1, labels.btn2, labels.btn3, labels.btn4);
 
   renderer.displayBuffer();
 }
 
-void MyLibraryActivity::renderRecentTab() const {
-  const auto pageWidth = renderer.getScreenWidth();
-  const int pageItems = getPageItems();
-  const int bookCount = static_cast<int>(recentBooks.size());
-
-  if (bookCount == 0) {
-    renderer.drawText(UI_10_FONT_ID, LEFT_MARGIN, CONTENT_START_Y, "No recent books");
-    return;
-  }
-
-  const auto pageStartIndex = selectorIndex / pageItems * pageItems;
-
-  // Draw selection highlight
-  renderer.fillRect(0, CONTENT_START_Y + (selectorIndex % pageItems) * RECENTS_LINE_HEIGHT - 2,
-                    pageWidth - RIGHT_MARGIN, RECENTS_LINE_HEIGHT);
-
-  // Draw items
-  for (int i = pageStartIndex; i < bookCount && i < pageStartIndex + pageItems; i++) {
-    const auto& book = recentBooks[i];
-    const int y = CONTENT_START_Y + (i % pageItems) * RECENTS_LINE_HEIGHT;
-
-    // Line 1: Title
-    std::string title = book.title;
-    if (title.empty()) {
-      // Fallback for older entries or files without metadata
-      title = book.path;
-      const size_t lastSlash = title.find_last_of('/');
-      if (lastSlash != std::string::npos) {
-        title = title.substr(lastSlash + 1);
-      }
-      const size_t dot = title.find_last_of('.');
-      if (dot != std::string::npos) {
-        title.resize(dot);
-      }
-    }
-    auto truncatedTitle = renderer.truncatedText(UI_12_FONT_ID, title.c_str(), pageWidth - LEFT_MARGIN - RIGHT_MARGIN);
-    renderer.drawText(UI_12_FONT_ID, LEFT_MARGIN, y + 2, truncatedTitle.c_str(), i != selectorIndex);
-
-    // Line 2: Author
-    if (!book.author.empty()) {
-      auto truncatedAuthor =
-          renderer.truncatedText(UI_10_FONT_ID, book.author.c_str(), pageWidth - LEFT_MARGIN - RIGHT_MARGIN);
-      renderer.drawText(UI_10_FONT_ID, LEFT_MARGIN, y + 32, truncatedAuthor.c_str(), i != selectorIndex);
-    }
-  }
-}
-
-void MyLibraryActivity::renderFilesTab() const {
-  const auto pageWidth = renderer.getScreenWidth();
-  const int pageItems = getPageItems();
-  const int fileCount = static_cast<int>(files.size());
-
-  if (fileCount == 0) {
-    renderer.drawText(UI_10_FONT_ID, LEFT_MARGIN, CONTENT_START_Y, "No books found");
-    return;
-  }
-
-  const auto pageStartIndex = selectorIndex / pageItems * pageItems;
-
-  // Draw selection highlight
-  renderer.fillRect(0, CONTENT_START_Y + (selectorIndex % pageItems) * LINE_HEIGHT - 2, pageWidth - RIGHT_MARGIN,
-                    LINE_HEIGHT);
-
-  // Draw items
-  for (int i = pageStartIndex; i < fileCount && i < pageStartIndex + pageItems; i++) {
-    auto item = renderer.truncatedText(UI_10_FONT_ID, files[i].c_str(), pageWidth - LEFT_MARGIN - RIGHT_MARGIN);
-    renderer.drawText(UI_10_FONT_ID, LEFT_MARGIN, CONTENT_START_Y + (i % pageItems) * LINE_HEIGHT, item.c_str(),
-                      i != selectorIndex);
-  }
+size_t MyLibraryActivity::findEntry(const std::string& name) const {
+  for (size_t i = 0; i < files.size(); i++)
+    if (files[i] == name) return i;
+  return 0;
 }

src/activities/home/MyLibraryActivity.h

@@ -8,59 +8,40 @@
 #include <vector>
 
 #include "../Activity.h"
-#include "RecentBooksStore.h"
 
 class MyLibraryActivity final : public Activity {
- public:
-  enum class Tab { Recent, Files };
-
  private:
   TaskHandle_t displayTaskHandle = nullptr;
   SemaphoreHandle_t renderingMutex = nullptr;
 
-  Tab currentTab = Tab::Recent;
-  int selectorIndex = 0;
+  size_t selectorIndex = 0;
   bool updateRequired = false;
 
-  // Recent tab state
-  std::vector<RecentBook> recentBooks;
-
-  // Files tab state (from FileSelectionActivity)
+  // Files state
   std::string basepath = "/";
   std::vector<std::string> files;
 
   // Callbacks
+  const std::function<void(const std::string& path)> onSelectBook;
   const std::function<void()> onGoHome;
-  const std::function<void(const std::string& path, Tab fromTab)> onSelectBook;
 
-  // Number of items that fit on a page
-  int getPageItems() const;
-  int getCurrentItemCount() const;
-  int getTotalPages() const;
-  int getCurrentPage() const;
-
-  // Data loading
-  void loadRecentBooks();
-  void loadFiles();
-  size_t findEntry(const std::string& name) const;
-
-  // Rendering
   static void taskTrampoline(void* param);
   [[noreturn]] void displayTaskLoop();
   void render() const;
-  void renderRecentTab() const;
-  void renderFilesTab() const;
+
+  // Data loading
+  void loadFiles();
+  size_t findEntry(const std::string& name) const;
 
  public:
   explicit MyLibraryActivity(GfxRenderer& renderer, MappedInputManager& mappedInput,
                              const std::function<void()>& onGoHome,
-                             const std::function<void(const std::string& path, Tab fromTab)>& onSelectBook,
-                             Tab initialTab = Tab::Recent, std::string initialPath = "/")
+                             const std::function<void(const std::string& path)>& onSelectBook,
+                             std::string initialPath = "/")
       : Activity("MyLibrary", renderer, mappedInput),
-        currentTab(initialTab),
         basepath(initialPath.empty() ? "/" : std::move(initialPath)),
-        onGoHome(onGoHome),
-        onSelectBook(onSelectBook) {}
+        onSelectBook(onSelectBook),
+        onGoHome(onGoHome) {}
   void onEnter() override;
   void onExit() override;
   void loop() override;

src/activities/home/RecentBooksActivity.cpp

@@ -0,0 +1,151 @@
+#include "RecentBooksActivity.h"
+
+#include <GfxRenderer.h>
+#include <HalStorage.h>
+
+#include <algorithm>
+
+#include "MappedInputManager.h"
+#include "RecentBooksStore.h"
+#include "components/UITheme.h"
+#include "fontIds.h"
+#include "util/StringUtils.h"
+
+namespace {
+constexpr int SKIP_PAGE_MS = 700;
+constexpr unsigned long GO_HOME_MS = 1000;
+}  // namespace
+
+void RecentBooksActivity::taskTrampoline(void* param) {
+  auto* self = static_cast<RecentBooksActivity*>(param);
+  self->displayTaskLoop();
+}
+
+void RecentBooksActivity::loadRecentBooks() {
+  recentBooks.clear();
+  const auto& books = RECENT_BOOKS.getBooks();
+  recentBooks.reserve(books.size());
+
+  for (const auto& book : books) {
+    // Skip if file no longer exists
+    if (!Storage.exists(book.path.c_str())) {
+      continue;
+    }
+    recentBooks.push_back(book);
+  }
+}
+
+void RecentBooksActivity::onEnter() {
+  Activity::onEnter();
+
+  renderingMutex = xSemaphoreCreateMutex();
+
+  // Load data
+  loadRecentBooks();
+
+  selectorIndex = 0;
+  updateRequired = true;
+
+  xTaskCreate(&RecentBooksActivity::taskTrampoline, "RecentBooksActivityTask",
+              4096,               // Stack size
+              this,               // Parameters
+              1,                  // Priority
+              &displayTaskHandle  // Task handle
+  );
+}
+
+void RecentBooksActivity::onExit() {
+  Activity::onExit();
+
+  // Wait until not rendering to delete task to avoid killing mid-instruction to EPD
+  xSemaphoreTake(renderingMutex, portMAX_DELAY);
+  if (displayTaskHandle) {
+    vTaskDelete(displayTaskHandle);
+    displayTaskHandle = nullptr;
+  }
+  vSemaphoreDelete(renderingMutex);
+  renderingMutex = nullptr;
+
+  recentBooks.clear();
+}
+
+void RecentBooksActivity::loop() {
+  const bool upReleased = mappedInput.wasReleased(MappedInputManager::Button::Left) ||
+                          mappedInput.wasReleased(MappedInputManager::Button::Up);
+  ;
+  const bool downReleased = mappedInput.wasReleased(MappedInputManager::Button::Right) ||
+                            mappedInput.wasReleased(MappedInputManager::Button::Down);
+
+  const bool skipPage = mappedInput.getHeldTime() > SKIP_PAGE_MS;
+  const int pageItems = UITheme::getInstance().getNumberOfItemsPerPage(renderer, true, false, true, true);
+
+  if (mappedInput.wasReleased(MappedInputManager::Button::Confirm)) {
+    if (!recentBooks.empty() && selectorIndex < static_cast<int>(recentBooks.size())) {
+      Serial.printf("Selected recent book: %s\n", recentBooks[selectorIndex].path.c_str());
+      onSelectBook(recentBooks[selectorIndex].path);
+      return;
+    }
+  }
+
+  if (mappedInput.wasReleased(MappedInputManager::Button::Back)) {
+    onGoHome();
+  }
+
+  int listSize = static_cast<int>(recentBooks.size());
+  if (upReleased) {
+    if (skipPage) {
+      selectorIndex = std::max(static_cast<int>((selectorIndex / pageItems - 1) * pageItems), 0);
+    } else {
+      selectorIndex = (selectorIndex + listSize - 1) % listSize;
+    }
+    updateRequired = true;
+  } else if (downReleased) {
+    if (skipPage) {
+      selectorIndex = std::min(static_cast<int>((selectorIndex / pageItems + 1) * pageItems), listSize - 1);
+    } else {
+      selectorIndex = (selectorIndex + 1) % listSize;
+    }
+    updateRequired = true;
+  }
+}
+
+void RecentBooksActivity::displayTaskLoop() {
+  while (true) {
+    if (updateRequired) {
+      updateRequired = false;
+      xSemaphoreTake(renderingMutex, portMAX_DELAY);
+      render();
+      xSemaphoreGive(renderingMutex);
+    }
+    vTaskDelay(10 / portTICK_PERIOD_MS);
+  }
+}
+
+void RecentBooksActivity::render() const {
+  renderer.clearScreen();
+
+  const auto pageWidth = renderer.getScreenWidth();
+  const auto pageHeight = renderer.getScreenHeight();
+  auto metrics = UITheme::getInstance().getMetrics();
+
+  GUI.drawHeader(renderer, Rect{0, metrics.topPadding, pageWidth, metrics.headerHeight}, "Recent Books");
+
+  const int contentTop = metrics.topPadding + metrics.headerHeight + metrics.verticalSpacing;
+  const int contentHeight = pageHeight - contentTop - metrics.buttonHintsHeight - metrics.verticalSpacing;
+
+  // Recent tab
+  if (recentBooks.empty()) {
+    renderer.drawText(UI_10_FONT_ID, metrics.contentSidePadding, contentTop + 20, "No recent books");
+  } else {
+    GUI.drawList(
+        renderer, Rect{0, contentTop, pageWidth, contentHeight}, recentBooks.size(), selectorIndex,
+        [this](int index) { return recentBooks[index].title; }, [this](int index) { return recentBooks[index].author; },
+        nullptr, nullptr);
+  }
+
+  // Help text
+  const auto labels = mappedInput.mapLabels("« Home", "Open", "Up", "Down");
+  GUI.drawButtonHints(renderer, labels.btn1, labels.btn2, labels.btn3, labels.btn4);
+
+  renderer.displayBuffer();
+}

src/activities/home/RecentBooksActivity.h

@@ -0,0 +1,43 @@
+#pragma once
+#include <freertos/FreeRTOS.h>
+#include <freertos/semphr.h>
+#include <freertos/task.h>
+
+#include <functional>
+#include <string>
+#include <vector>
+
+#include "../Activity.h"
+#include "RecentBooksStore.h"
+
+class RecentBooksActivity final : public Activity {
+ private:
+  TaskHandle_t displayTaskHandle = nullptr;
+  SemaphoreHandle_t renderingMutex = nullptr;
+
+  size_t selectorIndex = 0;
+  bool updateRequired = false;
+
+  // Recent tab state
+  std::vector<RecentBook> recentBooks;
+
+  // Callbacks
+  const std::function<void(const std::string& path)> onSelectBook;
+  const std::function<void()> onGoHome;
+
+  static void taskTrampoline(void* param);
+  [[noreturn]] void displayTaskLoop();
+  void render() const;
+
+  // Data loading
+  void loadRecentBooks();
+
+ public:
+  explicit RecentBooksActivity(GfxRenderer& renderer, MappedInputManager& mappedInput,
+                               const std::function<void()>& onGoHome,
+                               const std::function<void(const std::string& path)>& onSelectBook)
+      : Activity("RecentBooks", renderer, mappedInput), onSelectBook(onSelectBook), onGoHome(onGoHome) {}
+  void onEnter() override;
+  void onExit() override;
+  void loop() override;
+};

src/activities/network/CalibreConnectActivity.cpp

@@ -6,8 +6,8 @@
 #include <esp_task_wdt.h>
 
 #include "MappedInputManager.h"
-#include "ScreenComponents.h"
 #include "WifiSelectionActivity.h"
+#include "components/UITheme.h"
 #include "fontIds.h"
 
 namespace {
@@ -258,8 +258,7 @@ void CalibreConnectActivity::renderServerRunning() const {
     constexpr int barWidth = 300;
     constexpr int barHeight = 16;
     constexpr int barX = (480 - barWidth) / 2;
-    ScreenComponents::drawProgressBar(renderer, barX, y + 22, barWidth, barHeight, lastProgressReceived,
-                                      lastProgressTotal);
+    GUI.drawProgressBar(renderer, Rect{barX, y + 22, barWidth, barHeight}, lastProgressReceived, lastProgressTotal);
     y += 40;
   }
 
@@ -272,5 +271,5 @@ void CalibreConnectActivity::renderServerRunning() const {
   }
 
   const auto labels = mappedInput.mapLabels("« Exit", "", "", "");
-  renderer.drawButtonHints(UI_10_FONT_ID, labels.btn1, labels.btn2, labels.btn3, labels.btn4);
+  GUI.drawButtonHints(renderer, labels.btn1, labels.btn2, labels.btn3, labels.btn4);
 }

src/activities/network/CrossPointWebServerActivity.cpp

@@ -13,6 +13,7 @@
 #include "NetworkModeSelectionActivity.h"
 #include "WifiSelectionActivity.h"
 #include "activities/network/CalibreConnectActivity.h"
+#include "components/UITheme.h"
 #include "fontIds.h"
 
 namespace {
@@ -479,5 +480,5 @@ void CrossPointWebServerActivity::renderServerRunning() const {
   }
 
   const auto labels = mappedInput.mapLabels("« Exit", "", "", "");
-  renderer.drawButtonHints(UI_10_FONT_ID, labels.btn1, labels.btn2, labels.btn3, labels.btn4);
+  GUI.drawButtonHints(renderer, labels.btn1, labels.btn2, labels.btn3, labels.btn4);
 }

src/activities/network/NetworkModeSelectionActivity.cpp

@@ -3,6 +3,7 @@
 #include <GfxRenderer.h>
 
 #include "MappedInputManager.h"
+#include "components/UITheme.h"
 #include "fontIds.h"
 
 namespace {
@@ -131,7 +132,7 @@ void NetworkModeSelectionActivity::render() const {
 
   // Draw help text at bottom
   const auto labels = mappedInput.mapLabels("« Back", "Select", "", "");
-  renderer.drawButtonHints(UI_10_FONT_ID, labels.btn1, labels.btn2, labels.btn3, labels.btn4);
+  GUI.drawButtonHints(renderer, labels.btn1, labels.btn2, labels.btn3, labels.btn4);
 
   renderer.displayBuffer();
 }

src/activities/network/WifiSelectionActivity.cpp

@@ -8,6 +8,7 @@
 #include "MappedInputManager.h"
 #include "WifiCredentialStore.h"
 #include "activities/util/KeyboardEntryActivity.h"
+#include "components/UITheme.h"
 #include "fontIds.h"
 
 void WifiSelectionActivity::taskTrampoline(void* param) {
@@ -266,9 +267,9 @@ void WifiSelectionActivity::checkConnectionStatus() {
   }
 
   if (status == WL_CONNECT_FAILED || status == WL_NO_SSID_AVAIL) {
-    connectionError = "Connection failed";
+    connectionError = "Error: General failure";
     if (status == WL_NO_SSID_AVAIL) {
-      connectionError = "Network not found";
+      connectionError = "Error: Network not found";
     }
     state = WifiSelectionState::CONNECTION_FAILED;
     updateRequired = true;
@@ -278,7 +279,7 @@ void WifiSelectionActivity::checkConnectionStatus() {
   // Check for timeout
   if (millis() - connectionStartTime > CONNECTION_TIMEOUT_MS) {
     WiFi.disconnect();
-    connectionError = "Connection timeout";
+    connectionError = "Error: Connection timeout";
     state = WifiSelectionState::CONNECTION_FAILED;
     updateRequired = true;
     return;
@@ -520,7 +521,7 @@ void WifiSelectionActivity::renderNetworkList() const {
     const auto height = renderer.getLineHeight(UI_10_FONT_ID);
     const auto top = (pageHeight - height) / 2;
     renderer.drawCenteredText(UI_10_FONT_ID, top, "No networks found");
-    renderer.drawCenteredText(SMALL_FONT_ID, top + height + 10, "Press OK to scan again");
+    renderer.drawCenteredText(SMALL_FONT_ID, top + height + 10, "Press Connect to scan again");
   } else {
     // Calculate how many networks we can display
     constexpr int startY = 60;
@@ -546,8 +547,8 @@ void WifiSelectionActivity::renderNetworkList() const {
 
       // Draw network name (truncate if too long)
       std::string displayName = network.ssid;
-      if (displayName.length() > 16) {
-        displayName.replace(13, displayName.length() - 13, "...");
+      if (displayName.length() > 33) {
+        displayName.replace(30, displayName.length() - 30, "...");
       }
       renderer.drawText(UI_10_FONT_ID, 20, networkY, displayName.c_str());
 
@@ -586,7 +587,7 @@ void WifiSelectionActivity::renderNetworkList() const {
   // Draw help text
   renderer.drawText(SMALL_FONT_ID, 20, pageHeight - 75, "* = Encrypted | + = Saved");
   const auto labels = mappedInput.mapLabels("« Back", "Connect", "", "");
-  renderer.drawButtonHints(UI_10_FONT_ID, labels.btn1, labels.btn2, labels.btn3, labels.btn4);
+  GUI.drawButtonHints(renderer, labels.btn1, labels.btn2, labels.btn3, labels.btn4);
 }
 
 void WifiSelectionActivity::renderConnecting() const {
@@ -625,7 +626,7 @@ void WifiSelectionActivity::renderConnected() const {
 
   // Use centralized button hints
   const auto labels = mappedInput.mapLabels("", "Continue", "", "");
-  renderer.drawButtonHints(UI_10_FONT_ID, labels.btn1, labels.btn2, labels.btn3, labels.btn4);
+  GUI.drawButtonHints(renderer, labels.btn1, labels.btn2, labels.btn3, labels.btn4);
 }
 
 void WifiSelectionActivity::renderSavePrompt() const {
@@ -667,7 +668,7 @@ void WifiSelectionActivity::renderSavePrompt() const {
 
   // Use centralized button hints
   const auto labels = mappedInput.mapLabels("« Skip", "Select", "Left", "Right");
-  renderer.drawButtonHints(UI_10_FONT_ID, labels.btn1, labels.btn2, labels.btn3, labels.btn4);
+  GUI.drawButtonHints(renderer, labels.btn1, labels.btn2, labels.btn3, labels.btn4);
 }
 
 void WifiSelectionActivity::renderConnectionFailed() const {
@@ -680,7 +681,7 @@ void WifiSelectionActivity::renderConnectionFailed() const {
 
   // Use centralized button hints
   const auto labels = mappedInput.mapLabels("« Back", "Continue", "", "");
-  renderer.drawButtonHints(UI_10_FONT_ID, labels.btn1, labels.btn2, labels.btn3, labels.btn4);
+  GUI.drawButtonHints(renderer, labels.btn1, labels.btn2, labels.btn3, labels.btn4);
 }
 
 void WifiSelectionActivity::renderForgetPrompt() const {
@@ -689,7 +690,7 @@ void WifiSelectionActivity::renderForgetPrompt() const {
   const auto height = renderer.getLineHeight(UI_10_FONT_ID);
   const auto top = (pageHeight - height * 3) / 2;
 
-  renderer.drawCenteredText(UI_12_FONT_ID, top - 40, "Forget Network?", true, EpdFontFamily::BOLD);
+  renderer.drawCenteredText(UI_12_FONT_ID, top - 40, "Connection Failed", true, EpdFontFamily::BOLD);
 
   std::string ssidInfo = "Network: " + selectedSSID;
   if (ssidInfo.length() > 28) {
@@ -697,7 +698,7 @@ void WifiSelectionActivity::renderForgetPrompt() const {
   }
   renderer.drawCenteredText(UI_10_FONT_ID, top, ssidInfo.c_str());
 
-  renderer.drawCenteredText(UI_10_FONT_ID, top + 40, "Remove saved password?");
+  renderer.drawCenteredText(UI_10_FONT_ID, top + 40, "Forget network and remove saved password?");
 
   // Draw Cancel/Forget network buttons
   const int buttonY = top + 80;
@@ -722,5 +723,5 @@ void WifiSelectionActivity::renderForgetPrompt() const {
 
   // Use centralized button hints
   const auto labels = mappedInput.mapLabels("« Back", "Select", "Left", "Right");
-  renderer.drawButtonHints(UI_10_FONT_ID, labels.btn1, labels.btn2, labels.btn3, labels.btn4);
+  GUI.drawButtonHints(renderer, labels.btn1, labels.btn2, labels.btn3, labels.btn4);
 }

src/activities/reader/EpubReaderActivity.cpp

@@ -3,14 +3,17 @@
 #include <Epub/Page.h>
 #include <FsHelpers.h>
 #include <GfxRenderer.h>
-#include <SDCardManager.h>
+#include <HalStorage.h>
 
 #include "CrossPointSettings.h"
 #include "CrossPointState.h"
 #include "EpubReaderChapterSelectionActivity.h"
+#include "EpubReaderPercentSelectionActivity.h"
+#include "KOReaderCredentialStore.h"
+#include "KOReaderSyncActivity.h"
 #include "MappedInputManager.h"
 #include "RecentBooksStore.h"
-#include "ScreenComponents.h"
+#include "components/UITheme.h"
 #include "fontIds.h"
 
 namespace {
@@ -20,6 +23,37 @@ constexpr unsigned long goHomeMs = 1000;
 constexpr int statusBarMargin = 19;
 constexpr int progressBarMarginTop = 1;
 
+int clampPercent(int percent) {
+  if (percent < 0) {
+    return 0;
+  }
+  if (percent > 100) {
+    return 100;
+  }
+  return percent;
+}
+
+// Apply the logical reader orientation to the renderer.
+// This centralizes orientation mapping so we don't duplicate switch logic elsewhere.
+void applyReaderOrientation(GfxRenderer& renderer, const uint8_t orientation) {
+  switch (orientation) {
+    case CrossPointSettings::ORIENTATION::PORTRAIT:
+      renderer.setOrientation(GfxRenderer::Orientation::Portrait);
+      break;
+    case CrossPointSettings::ORIENTATION::LANDSCAPE_CW:
+      renderer.setOrientation(GfxRenderer::Orientation::LandscapeClockwise);
+      break;
+    case CrossPointSettings::ORIENTATION::INVERTED:
+      renderer.setOrientation(GfxRenderer::Orientation::PortraitInverted);
+      break;
+    case CrossPointSettings::ORIENTATION::LANDSCAPE_CCW:
+      renderer.setOrientation(GfxRenderer::Orientation::LandscapeCounterClockwise);
+      break;
+    default:
+      break;
+  }
+}
+
 }  // namespace
 
 void EpubReaderActivity::taskTrampoline(void* param) {
@@ -35,29 +69,15 @@ void EpubReaderActivity::onEnter() {
   }
 
   // Configure screen orientation based on settings
-  switch (SETTINGS.orientation) {
-    case CrossPointSettings::ORIENTATION::PORTRAIT:
-      renderer.setOrientation(GfxRenderer::Orientation::Portrait);
-      break;
-    case CrossPointSettings::ORIENTATION::LANDSCAPE_CW:
-      renderer.setOrientation(GfxRenderer::Orientation::LandscapeClockwise);
-      break;
-    case CrossPointSettings::ORIENTATION::INVERTED:
-      renderer.setOrientation(GfxRenderer::Orientation::PortraitInverted);
-      break;
-    case CrossPointSettings::ORIENTATION::LANDSCAPE_CCW:
-      renderer.setOrientation(GfxRenderer::Orientation::LandscapeCounterClockwise);
-      break;
-    default:
-      break;
-  }
+  // NOTE: This affects layout math and must be applied before any render calls.
+  applyReaderOrientation(renderer, SETTINGS.orientation);
 
   renderingMutex = xSemaphoreCreateMutex();
 
   epub->setupCacheDir();
 
   FsFile f;
-  if (SdMan.openFileForRead("ERS", epub->getCachePath() + "/progress.bin", f)) {
+  if (Storage.openFileForRead("ERS", epub->getCachePath() + "/progress.bin", f)) {
     uint8_t data[6];
     int dataSize = f.read(data, 6);
     if (dataSize == 4 || dataSize == 6) {
@@ -85,7 +105,7 @@ void EpubReaderActivity::onEnter() {
   // Save current epub as last opened epub and add to recent books
   APP_STATE.openEpubPath = epub->getPath();
   APP_STATE.saveToFile();
-  RECENT_BOOKS.addBook(epub->getPath(), epub->getTitle(), epub->getAuthor());
+  RECENT_BOOKS.addBook(epub->getPath(), epub->getTitle(), epub->getAuthor(), epub->getThumbBmpPath());
 
   // Trigger first update
   updateRequired = true;
@@ -112,6 +132,8 @@ void EpubReaderActivity::onExit() {
   }
   vSemaphoreDelete(renderingMutex);
   renderingMutex = nullptr;
+  APP_STATE.readerActivityLoadCount = 0;
+  APP_STATE.saveToFile();
   section.reset();
   epub.reset();
 }
@@ -120,53 +142,77 @@ void EpubReaderActivity::loop() {
   // Pass input responsibility to sub activity if exists
   if (subActivity) {
     subActivity->loop();
+    // Deferred exit: process after subActivity->loop() returns to avoid use-after-free
+    if (pendingSubactivityExit) {
+      pendingSubactivityExit = false;
+      exitActivity();
+      updateRequired = true;
+      skipNextButtonCheck = true;  // Skip button processing to ignore stale events
+    }
+    // Deferred go home: process after subActivity->loop() returns to avoid race condition
+    if (pendingGoHome) {
+      pendingGoHome = false;
+      exitActivity();
+      if (onGoHome) {
+        onGoHome();
+      }
+      return;  // Don't access 'this' after callback
+    }
     return;
   }
 
-  // Enter chapter selection activity
+  // Handle pending go home when no subactivity (e.g., from long press back)
+  if (pendingGoHome) {
+    pendingGoHome = false;
+    if (onGoHome) {
+      onGoHome();
+    }
+    return;  // Don't access 'this' after callback
+  }
+
+  // Skip button processing after returning from subactivity
+  // This prevents stale button release events from triggering actions
+  // We wait until: (1) all relevant buttons are released, AND (2) wasReleased events have been cleared
+  if (skipNextButtonCheck) {
+    const bool confirmCleared = !mappedInput.isPressed(MappedInputManager::Button::Confirm) &&
+                                !mappedInput.wasReleased(MappedInputManager::Button::Confirm);
+    const bool backCleared = !mappedInput.isPressed(MappedInputManager::Button::Back) &&
+                             !mappedInput.wasReleased(MappedInputManager::Button::Back);
+    if (confirmCleared && backCleared) {
+      skipNextButtonCheck = false;
+    }
+    return;
+  }
+
+  // Enter reader menu activity.
   if (mappedInput.wasReleased(MappedInputManager::Button::Confirm)) {
     // Don't start activity transition while rendering
     xSemaphoreTake(renderingMutex, portMAX_DELAY);
-    const int currentPage = section ? section->currentPage : 0;
+    const int currentPage = section ? section->currentPage + 1 : 0;
     const int totalPages = section ? section->pageCount : 0;
+    float bookProgress = 0.0f;
+    if (epub && epub->getBookSize() > 0 && section && section->pageCount > 0) {
+      const float chapterProgress = static_cast<float>(section->currentPage) / static_cast<float>(section->pageCount);
+      bookProgress = epub->calculateProgress(currentSpineIndex, chapterProgress) * 100.0f;
+    }
+    const int bookProgressPercent = clampPercent(static_cast<int>(bookProgress + 0.5f));
     exitActivity();
-    enterNewActivity(new EpubReaderChapterSelectionActivity(
-        this->renderer, this->mappedInput, epub, epub->getPath(), currentSpineIndex, currentPage, totalPages,
-        [this] {
-          exitActivity();
-          updateRequired = true;
-        },
-        [this](const int newSpineIndex) {
-          if (currentSpineIndex != newSpineIndex) {
-            currentSpineIndex = newSpineIndex;
-            nextPageNumber = 0;
-            section.reset();
-          }
-          exitActivity();
-          updateRequired = true;
-        },
-        [this](const int newSpineIndex, const int newPage) {
-          // Handle sync position
-          if (currentSpineIndex != newSpineIndex || (section && section->currentPage != newPage)) {
-            currentSpineIndex = newSpineIndex;
-            nextPageNumber = newPage;
-            section.reset();
-          }
-          exitActivity();
-          updateRequired = true;
-        }));
+    enterNewActivity(new EpubReaderMenuActivity(
+        this->renderer, this->mappedInput, epub->getTitle(), currentPage, totalPages, bookProgressPercent,
+        SETTINGS.orientation, [this](const uint8_t orientation) { onReaderMenuBack(orientation); },
+        [this](EpubReaderMenuActivity::MenuAction action) { onReaderMenuConfirm(action); }));
     xSemaphoreGive(renderingMutex);
   }
 
-  // Long press BACK (1s+) goes directly to home
+  // Long press BACK (1s+) goes to file selection
   if (mappedInput.isPressed(MappedInputManager::Button::Back) && mappedInput.getHeldTime() >= goHomeMs) {
-    onGoHome();
+    onGoBack();
     return;
   }
 
-  // Short press BACK goes to file selection
+  // Short press BACK goes directly to home
   if (mappedInput.wasReleased(MappedInputManager::Button::Back) && mappedInput.getHeldTime() < goHomeMs) {
-    onGoBack();
+    onGoHome();
     return;
   }
 
@@ -242,6 +288,227 @@ void EpubReaderActivity::loop() {
   }
 }
 
+void EpubReaderActivity::onReaderMenuBack(const uint8_t orientation) {
+  exitActivity();
+  // Apply the user-selected orientation when the menu is dismissed.
+  // This ensures the menu can be navigated without immediately rotating the screen.
+  applyOrientation(orientation);
+  updateRequired = true;
+}
+
+// Translate an absolute percent into a spine index plus a normalized position
+// within that spine so we can jump after the section is loaded.
+void EpubReaderActivity::jumpToPercent(int percent) {
+  if (!epub) {
+    return;
+  }
+
+  const size_t bookSize = epub->getBookSize();
+  if (bookSize == 0) {
+    return;
+  }
+
+  // Normalize input to 0-100 to avoid invalid jumps.
+  percent = clampPercent(percent);
+
+  // Convert percent into a byte-like absolute position across the spine sizes.
+  // Use an overflow-safe computation: (bookSize / 100) * percent + (bookSize % 100) * percent / 100
+  size_t targetSize =
+      (bookSize / 100) * static_cast<size_t>(percent) + (bookSize % 100) * static_cast<size_t>(percent) / 100;
+  if (percent >= 100) {
+    // Ensure the final percent lands inside the last spine item.
+    targetSize = bookSize - 1;
+  }
+
+  const int spineCount = epub->getSpineItemsCount();
+  if (spineCount == 0) {
+    return;
+  }
+
+  int targetSpineIndex = spineCount - 1;
+  size_t prevCumulative = 0;
+
+  for (int i = 0; i < spineCount; i++) {
+    const size_t cumulative = epub->getCumulativeSpineItemSize(i);
+    if (targetSize <= cumulative) {
+      // Found the spine item containing the absolute position.
+      targetSpineIndex = i;
+      prevCumulative = (i > 0) ? epub->getCumulativeSpineItemSize(i - 1) : 0;
+      break;
+    }
+  }
+
+  const size_t cumulative = epub->getCumulativeSpineItemSize(targetSpineIndex);
+  const size_t spineSize = (cumulative > prevCumulative) ? (cumulative - prevCumulative) : 0;
+  // Store a normalized position within the spine so it can be applied once loaded.
+  pendingSpineProgress =
+      (spineSize == 0) ? 0.0f : static_cast<float>(targetSize - prevCumulative) / static_cast<float>(spineSize);
+  if (pendingSpineProgress < 0.0f) {
+    pendingSpineProgress = 0.0f;
+  } else if (pendingSpineProgress > 1.0f) {
+    pendingSpineProgress = 1.0f;
+  }
+
+  // Reset state so renderScreen() reloads and repositions on the target spine.
+  xSemaphoreTake(renderingMutex, portMAX_DELAY);
+  currentSpineIndex = targetSpineIndex;
+  nextPageNumber = 0;
+  pendingPercentJump = true;
+  section.reset();
+  xSemaphoreGive(renderingMutex);
+}
+
+void EpubReaderActivity::onReaderMenuConfirm(EpubReaderMenuActivity::MenuAction action) {
+  switch (action) {
+    case EpubReaderMenuActivity::MenuAction::SELECT_CHAPTER: {
+      // Calculate values BEFORE we start destroying things
+      const int currentP = section ? section->currentPage : 0;
+      const int totalP = section ? section->pageCount : 0;
+      const int spineIdx = currentSpineIndex;
+      const std::string path = epub->getPath();
+
+      xSemaphoreTake(renderingMutex, portMAX_DELAY);
+
+      // 1. Close the menu
+      exitActivity();
+
+      // 2. Open the Chapter Selector
+      enterNewActivity(new EpubReaderChapterSelectionActivity(
+          this->renderer, this->mappedInput, epub, path, spineIdx, currentP, totalP,
+          [this] {
+            exitActivity();
+            updateRequired = true;
+          },
+          [this](const int newSpineIndex) {
+            if (currentSpineIndex != newSpineIndex) {
+              currentSpineIndex = newSpineIndex;
+              nextPageNumber = 0;
+              section.reset();
+            }
+            exitActivity();
+            updateRequired = true;
+          },
+          [this](const int newSpineIndex, const int newPage) {
+            if (currentSpineIndex != newSpineIndex || (section && section->currentPage != newPage)) {
+              currentSpineIndex = newSpineIndex;
+              nextPageNumber = newPage;
+              section.reset();
+            }
+            exitActivity();
+            updateRequired = true;
+          }));
+
+      xSemaphoreGive(renderingMutex);
+      break;
+    }
+    case EpubReaderMenuActivity::MenuAction::GO_TO_PERCENT: {
+      // Launch the slider-based percent selector and return here on confirm/cancel.
+      float bookProgress = 0.0f;
+      if (epub && epub->getBookSize() > 0 && section && section->pageCount > 0) {
+        const float chapterProgress = static_cast<float>(section->currentPage) / static_cast<float>(section->pageCount);
+        bookProgress = epub->calculateProgress(currentSpineIndex, chapterProgress) * 100.0f;
+      }
+      const int initialPercent = clampPercent(static_cast<int>(bookProgress + 0.5f));
+      xSemaphoreTake(renderingMutex, portMAX_DELAY);
+      exitActivity();
+      enterNewActivity(new EpubReaderPercentSelectionActivity(
+          renderer, mappedInput, initialPercent,
+          [this](const int percent) {
+            // Apply the new position and exit back to the reader.
+            jumpToPercent(percent);
+            exitActivity();
+            updateRequired = true;
+          },
+          [this]() {
+            // Cancel selection and return to the reader.
+            exitActivity();
+            updateRequired = true;
+          }));
+      xSemaphoreGive(renderingMutex);
+      break;
+    }
+    case EpubReaderMenuActivity::MenuAction::GO_HOME: {
+      // Defer go home to avoid race condition with display task
+      pendingGoHome = true;
+      break;
+    }
+    case EpubReaderMenuActivity::MenuAction::DELETE_CACHE: {
+      xSemaphoreTake(renderingMutex, portMAX_DELAY);
+      if (epub) {
+        // 2. BACKUP: Read current progress
+        // We use the current variables that track our position
+        uint16_t backupSpine = currentSpineIndex;
+        uint16_t backupPage = section->currentPage;
+        uint16_t backupPageCount = section->pageCount;
+
+        section.reset();
+        // 3. WIPE: Clear the cache directory
+        epub->clearCache();
+
+        // 4. RESTORE: Re-setup the directory and rewrite the progress file
+        epub->setupCacheDir();
+
+        saveProgress(backupSpine, backupPage, backupPageCount);
+      }
+      xSemaphoreGive(renderingMutex);
+      // Defer go home to avoid race condition with display task
+      pendingGoHome = true;
+      break;
+    }
+    case EpubReaderMenuActivity::MenuAction::SYNC: {
+      if (KOREADER_STORE.hasCredentials()) {
+        xSemaphoreTake(renderingMutex, portMAX_DELAY);
+        const int currentPage = section ? section->currentPage : 0;
+        const int totalPages = section ? section->pageCount : 0;
+        exitActivity();
+        enterNewActivity(new KOReaderSyncActivity(
+            renderer, mappedInput, epub, epub->getPath(), currentSpineIndex, currentPage, totalPages,
+            [this]() {
+              // On cancel - defer exit to avoid use-after-free
+              pendingSubactivityExit = true;
+            },
+            [this](int newSpineIndex, int newPage) {
+              // On sync complete - update position and defer exit
+              if (currentSpineIndex != newSpineIndex || (section && section->currentPage != newPage)) {
+                currentSpineIndex = newSpineIndex;
+                nextPageNumber = newPage;
+                section.reset();
+              }
+              pendingSubactivityExit = true;
+            }));
+        xSemaphoreGive(renderingMutex);
+      }
+      break;
+    }
+  }
+}
+
+void EpubReaderActivity::applyOrientation(const uint8_t orientation) {
+  // No-op if the selected orientation matches current settings.
+  if (SETTINGS.orientation == orientation) {
+    return;
+  }
+
+  // Preserve current reading position so we can restore after reflow.
+  xSemaphoreTake(renderingMutex, portMAX_DELAY);
+  if (section) {
+    cachedSpineIndex = currentSpineIndex;
+    cachedChapterTotalPageCount = section->pageCount;
+    nextPageNumber = section->currentPage;
+  }
+
+  // Persist the selection so the reader keeps the new orientation on next launch.
+  SETTINGS.orientation = orientation;
+  SETTINGS.saveToFile();
+
+  // Update renderer orientation to match the new logical coordinate system.
+  applyReaderOrientation(renderer, SETTINGS.orientation);
+
+  // Reset section to force re-layout in the new orientation.
+  section.reset();
+  xSemaphoreGive(renderingMutex);
+}
+
 void EpubReaderActivity::displayTaskLoop() {
   while (true) {
     if (updateRequired) {
@@ -286,13 +553,16 @@ void EpubReaderActivity::renderScreen() {
   orientedMarginRight += SETTINGS.screenMargin;
   orientedMarginBottom += SETTINGS.screenMargin;
 
+  auto metrics = UITheme::getInstance().getMetrics();
+
   // Add status bar margin
   if (SETTINGS.statusBar != CrossPointSettings::STATUS_BAR_MODE::NONE) {
     // Add additional margin for status bar if progress bar is shown
-    const bool showProgressBar = SETTINGS.statusBar == CrossPointSettings::STATUS_BAR_MODE::FULL_WITH_PROGRESS_BAR ||
-                                 SETTINGS.statusBar == CrossPointSettings::STATUS_BAR_MODE::ONLY_PROGRESS_BAR;
+    const bool showProgressBar = SETTINGS.statusBar == CrossPointSettings::STATUS_BAR_MODE::BOOK_PROGRESS_BAR ||
+                                 SETTINGS.statusBar == CrossPointSettings::STATUS_BAR_MODE::ONLY_BOOK_PROGRESS_BAR ||
+                                 SETTINGS.statusBar == CrossPointSettings::STATUS_BAR_MODE::CHAPTER_PROGRESS_BAR;
     orientedMarginBottom += statusBarMargin - SETTINGS.screenMargin +
-                            (showProgressBar ? (ScreenComponents::BOOK_PROGRESS_BAR_HEIGHT + progressBarMarginTop) : 0);
+                            (showProgressBar ? (metrics.bookProgressBarHeight + progressBarMarginTop) : 0);
   }
 
   if (!section) {
@@ -305,52 +575,14 @@ void EpubReaderActivity::renderScreen() {
 
     if (!section->loadSectionFile(SETTINGS.getReaderFontId(), SETTINGS.getReaderLineCompression(),
                                   SETTINGS.extraParagraphSpacing, SETTINGS.paragraphAlignment, viewportWidth,
-                                  viewportHeight, SETTINGS.hyphenationEnabled)) {
+                                  viewportHeight, SETTINGS.hyphenationEnabled, SETTINGS.embeddedStyle)) {
       Serial.printf("[%lu] [ERS] Cache not found, building...\n", millis());
 
-      // Progress bar dimensions
-      constexpr int barWidth = 200;
-      constexpr int barHeight = 10;
-      constexpr int boxMargin = 20;
-      const int textWidth = renderer.getTextWidth(UI_12_FONT_ID, "Indexing...");
-      const int boxWidthWithBar = (barWidth > textWidth ? barWidth : textWidth) + boxMargin * 2;
-      const int boxWidthNoBar = textWidth + boxMargin * 2;
-      const int boxHeightWithBar = renderer.getLineHeight(UI_12_FONT_ID) + barHeight + boxMargin * 3;
-      const int boxHeightNoBar = renderer.getLineHeight(UI_12_FONT_ID) + boxMargin * 2;
-      const int boxXWithBar = (renderer.getScreenWidth() - boxWidthWithBar) / 2;
-      const int boxXNoBar = (renderer.getScreenWidth() - boxWidthNoBar) / 2;
-      constexpr int boxY = 50;
-      const int barX = boxXWithBar + (boxWidthWithBar - barWidth) / 2;
-      const int barY = boxY + renderer.getLineHeight(UI_12_FONT_ID) + boxMargin * 2;
-
-      // Always show "Indexing..." text first
-      {
-        renderer.fillRect(boxXNoBar, boxY, boxWidthNoBar, boxHeightNoBar, false);
-        renderer.drawText(UI_12_FONT_ID, boxXNoBar + boxMargin, boxY + boxMargin, "Indexing...");
-        renderer.drawRect(boxXNoBar + 5, boxY + 5, boxWidthNoBar - 10, boxHeightNoBar - 10);
-        renderer.displayBuffer();
-        pagesUntilFullRefresh = 0;
-      }
-
-      // Setup callback - only called for chapters >= 50KB, redraws with progress bar
-      auto progressSetup = [this, boxXWithBar, boxWidthWithBar, boxHeightWithBar, barX, barY] {
-        renderer.fillRect(boxXWithBar, boxY, boxWidthWithBar, boxHeightWithBar, false);
-        renderer.drawText(UI_12_FONT_ID, boxXWithBar + boxMargin, boxY + boxMargin, "Indexing...");
-        renderer.drawRect(boxXWithBar + 5, boxY + 5, boxWidthWithBar - 10, boxHeightWithBar - 10);
-        renderer.drawRect(barX, barY, barWidth, barHeight);
-        renderer.displayBuffer();
-      };
-
-      // Progress callback to update progress bar
-      auto progressCallback = [this, barX, barY, barWidth, barHeight](int progress) {
-        const int fillWidth = (barWidth - 2) * progress / 100;
-        renderer.fillRect(barX + 1, barY + 1, fillWidth, barHeight - 2, true);
-        renderer.displayBuffer(HalDisplay::FAST_REFRESH);
-      };
+      const auto popupFn = [this]() { GUI.drawPopup(renderer, "Indexing..."); };
 
       if (!section->createSectionFile(SETTINGS.getReaderFontId(), SETTINGS.getReaderLineCompression(),
                                       SETTINGS.extraParagraphSpacing, SETTINGS.paragraphAlignment, viewportWidth,
-                                      viewportHeight, SETTINGS.hyphenationEnabled, progressSetup, progressCallback)) {
+                                      viewportHeight, SETTINGS.hyphenationEnabled, SETTINGS.embeddedStyle, popupFn)) {
         Serial.printf("[%lu] [ERS] Failed to persist page data to SD\n", millis());
         section.reset();
         return;
@@ -375,6 +607,16 @@ void EpubReaderActivity::renderScreen() {
       }
       cachedChapterTotalPageCount = 0;  // resets to 0 to prevent reading cached progress again
     }
+
+    if (pendingPercentJump && section->pageCount > 0) {
+      // Apply the pending percent jump now that we know the new section's page count.
+      int newPage = static_cast<int>(pendingSpineProgress * static_cast<float>(section->pageCount));
+      if (newPage >= section->pageCount) {
+        newPage = section->pageCount - 1;
+      }
+      section->currentPage = newPage;
+      pendingPercentJump = false;
+    }
   }
 
   renderer.clearScreen();
@@ -407,21 +649,26 @@ void EpubReaderActivity::renderScreen() {
     renderContents(std::move(p), orientedMarginTop, orientedMarginRight, orientedMarginBottom, orientedMarginLeft);
     Serial.printf("[%lu] [ERS] Rendered page in %dms\n", millis(), millis() - start);
   }
+  saveProgress(currentSpineIndex, section->currentPage, section->pageCount);
+}
 
+void EpubReaderActivity::saveProgress(int spineIndex, int currentPage, int pageCount) {
   FsFile f;
-  if (SdMan.openFileForWrite("ERS", epub->getCachePath() + "/progress.bin", f)) {
+  if (Storage.openFileForWrite("ERS", epub->getCachePath() + "/progress.bin", f)) {
     uint8_t data[6];
     data[0] = currentSpineIndex & 0xFF;
     data[1] = (currentSpineIndex >> 8) & 0xFF;
-    data[2] = section->currentPage & 0xFF;
-    data[3] = (section->currentPage >> 8) & 0xFF;
-    data[4] = section->pageCount & 0xFF;
-    data[5] = (section->pageCount >> 8) & 0xFF;
+    data[2] = currentPage & 0xFF;
+    data[3] = (currentPage >> 8) & 0xFF;
+    data[4] = pageCount & 0xFF;
+    data[5] = (pageCount >> 8) & 0xFF;
     f.write(data, 6);
     f.close();
+    Serial.printf("[ERS] Progress saved: Chapter %d, Page %d\n", spineIndex, currentPage);
+  } else {
+    Serial.printf("[ERS] Could not save progress!\n");
   }
 }
-
 void EpubReaderActivity::renderContents(std::unique_ptr<Page> page, const int orientedMarginTop,
                                         const int orientedMarginRight, const int orientedMarginBottom,
                                         const int orientedMarginLeft) {
@@ -463,18 +710,24 @@ void EpubReaderActivity::renderContents(std::unique_ptr<Page> page, const int or
 
 void EpubReaderActivity::renderStatusBar(const int orientedMarginRight, const int orientedMarginBottom,
                                          const int orientedMarginLeft) const {
+  auto metrics = UITheme::getInstance().getMetrics();
+
   // determine visible status bar elements
   const bool showProgressPercentage = SETTINGS.statusBar == CrossPointSettings::STATUS_BAR_MODE::FULL;
-  const bool showProgressBar = SETTINGS.statusBar == CrossPointSettings::STATUS_BAR_MODE::FULL_WITH_PROGRESS_BAR ||
-                               SETTINGS.statusBar == CrossPointSettings::STATUS_BAR_MODE::ONLY_PROGRESS_BAR;
+  const bool showBookProgressBar = SETTINGS.statusBar == CrossPointSettings::STATUS_BAR_MODE::BOOK_PROGRESS_BAR ||
+                                   SETTINGS.statusBar == CrossPointSettings::STATUS_BAR_MODE::ONLY_BOOK_PROGRESS_BAR;
+  const bool showChapterProgressBar = SETTINGS.statusBar == CrossPointSettings::STATUS_BAR_MODE::CHAPTER_PROGRESS_BAR;
   const bool showProgressText = SETTINGS.statusBar == CrossPointSettings::STATUS_BAR_MODE::FULL ||
-                                SETTINGS.statusBar == CrossPointSettings::STATUS_BAR_MODE::FULL_WITH_PROGRESS_BAR;
+                                SETTINGS.statusBar == CrossPointSettings::STATUS_BAR_MODE::BOOK_PROGRESS_BAR;
+  const bool showBookPercentage = SETTINGS.statusBar == CrossPointSettings::STATUS_BAR_MODE::CHAPTER_PROGRESS_BAR;
   const bool showBattery = SETTINGS.statusBar == CrossPointSettings::STATUS_BAR_MODE::NO_PROGRESS ||
                            SETTINGS.statusBar == CrossPointSettings::STATUS_BAR_MODE::FULL ||
-                           SETTINGS.statusBar == CrossPointSettings::STATUS_BAR_MODE::FULL_WITH_PROGRESS_BAR;
+                           SETTINGS.statusBar == CrossPointSettings::STATUS_BAR_MODE::BOOK_PROGRESS_BAR ||
+                           SETTINGS.statusBar == CrossPointSettings::STATUS_BAR_MODE::CHAPTER_PROGRESS_BAR;
   const bool showChapterTitle = SETTINGS.statusBar == CrossPointSettings::STATUS_BAR_MODE::NO_PROGRESS ||
                                 SETTINGS.statusBar == CrossPointSettings::STATUS_BAR_MODE::FULL ||
-                                SETTINGS.statusBar == CrossPointSettings::STATUS_BAR_MODE::FULL_WITH_PROGRESS_BAR;
+                                SETTINGS.statusBar == CrossPointSettings::STATUS_BAR_MODE::BOOK_PROGRESS_BAR ||
+                                SETTINGS.statusBar == CrossPointSettings::STATUS_BAR_MODE::CHAPTER_PROGRESS_BAR;
   const bool showBatteryPercentage =
       SETTINGS.hideBatteryPercentage == CrossPointSettings::HIDE_BATTERY_PERCENTAGE::HIDE_NEVER;
 
@@ -487,7 +740,7 @@ void EpubReaderActivity::renderStatusBar(const int orientedMarginRight, const in
   const float sectionChapterProg = static_cast<float>(section->currentPage) / section->pageCount;
   const float bookProgress = epub->calculateProgress(currentSpineIndex, sectionChapterProg) * 100;
 
-  if (showProgressText || showProgressPercentage) {
+  if (showProgressText || showProgressPercentage || showBookPercentage) {
     // Right aligned text for progress counter
     char progressStr[32];
 
@@ -495,6 +748,8 @@ void EpubReaderActivity::renderStatusBar(const int orientedMarginRight, const in
     if (showProgressPercentage) {
       snprintf(progressStr, sizeof(progressStr), "%d/%d  %.0f%%", section->currentPage + 1, section->pageCount,
                bookProgress);
+    } else if (showBookPercentage) {
+      snprintf(progressStr, sizeof(progressStr), "%.0f%%", bookProgress);
     } else {
       snprintf(progressStr, sizeof(progressStr), "%d/%d", section->currentPage + 1, section->pageCount);
     }
@@ -504,13 +759,21 @@ void EpubReaderActivity::renderStatusBar(const int orientedMarginRight, const in
                       progressStr);
   }
 
-  if (showProgressBar) {
+  if (showBookProgressBar) {
     // Draw progress bar at the very bottom of the screen, from edge to edge of viewable area
-    ScreenComponents::drawBookProgressBar(renderer, static_cast<size_t>(bookProgress));
+    GUI.drawReadingProgressBar(renderer, static_cast<size_t>(bookProgress));
+  }
+
+  if (showChapterProgressBar) {
+    // Draw chapter progress bar at the very bottom of the screen, from edge to edge of viewable area
+    const float chapterProgress =
+        (section->pageCount > 0) ? (static_cast<float>(section->currentPage + 1) / section->pageCount) * 100 : 0;
+    GUI.drawReadingProgressBar(renderer, static_cast<size_t>(chapterProgress));
   }
 
   if (showBattery) {
-    ScreenComponents::drawBattery(renderer, orientedMarginLeft + 1, textY, showBatteryPercentage);
+    GUI.drawBattery(renderer, Rect{orientedMarginLeft + 1, textY, metrics.batteryWidth, metrics.batteryHeight},
+                    showBatteryPercentage);
   }
 
   if (showChapterTitle) {
@@ -542,8 +805,8 @@ void EpubReaderActivity::renderStatusBar(const int orientedMarginRight, const in
         availableTitleSpace = rendererableScreenWidth - titleMarginLeft - titleMarginRight;
         titleMarginLeftAdjusted = titleMarginLeft;
       }
-      while (titleWidth > availableTitleSpace && title.length() > 11) {
-        title.replace(title.length() - 8, 8, "...");
+      if (titleWidth > availableTitleSpace) {
+        title = renderer.truncatedText(SMALL_FONT_ID, title.c_str(), availableTitleSpace);
         titleWidth = renderer.getTextWidth(SMALL_FONT_ID, title.c_str());
       }
     }

src/activities/reader/EpubReaderActivity.h

@@ -5,6 +5,7 @@
 #include <freertos/semphr.h>
 #include <freertos/task.h>
 
+#include "EpubReaderMenuActivity.h"
 #include "activities/ActivityWithSubactivity.h"
 
 class EpubReaderActivity final : public ActivityWithSubactivity {
@@ -17,7 +18,15 @@ class EpubReaderActivity final : public ActivityWithSubactivity {
   int pagesUntilFullRefresh = 0;
   int cachedSpineIndex = 0;
   int cachedChapterTotalPageCount = 0;
+  // Signals that the next render should reposition within the newly loaded section
+  // based on a cross-book percentage jump.
+  bool pendingPercentJump = false;
+  // Normalized 0.0-1.0 progress within the target spine item, computed from book percentage.
+  float pendingSpineProgress = 0.0f;
   bool updateRequired = false;
+  bool pendingSubactivityExit = false;  // Defer subactivity exit to avoid use-after-free
+  bool pendingGoHome = false;           // Defer go home to avoid race condition with display task
+  bool skipNextButtonCheck = false;     // Skip button processing for one frame after subactivity exit
   const std::function<void()> onGoBack;
   const std::function<void()> onGoHome;
 
@@ -27,6 +36,12 @@ class EpubReaderActivity final : public ActivityWithSubactivity {
   void renderContents(std::unique_ptr<Page> page, int orientedMarginTop, int orientedMarginRight,
                       int orientedMarginBottom, int orientedMarginLeft);
   void renderStatusBar(int orientedMarginRight, int orientedMarginBottom, int orientedMarginLeft) const;
+  void saveProgress(int spineIndex, int currentPage, int pageCount);
+  // Jump to a percentage of the book (0-100), mapping it to spine and page.
+  void jumpToPercent(int percent);
+  void onReaderMenuBack(uint8_t orientation);
+  void onReaderMenuConfirm(EpubReaderMenuActivity::MenuAction action);
+  void applyOrientation(uint8_t orientation);
 
  public:
   explicit EpubReaderActivity(GfxRenderer& renderer, MappedInputManager& mappedInput, std::unique_ptr<Epub> epub,

src/activities/reader/EpubReaderChapterSelectionActivity.cpp

@@ -2,9 +2,8 @@
 
 #include <GfxRenderer.h>
 
-#include "KOReaderCredentialStore.h"
-#include "KOReaderSyncActivity.h"
 #include "MappedInputManager.h"
+#include "components/UITheme.h"
 #include "fontIds.h"
 
 namespace {
@@ -12,42 +11,22 @@ namespace {
 constexpr int SKIP_PAGE_MS = 700;
 }  // namespace
 
-bool EpubReaderChapterSelectionActivity::hasSyncOption() const { return KOREADER_STORE.hasCredentials(); }
-
-int EpubReaderChapterSelectionActivity::getTotalItems() const {
-  // Add 2 for sync options (top and bottom) if credentials are configured
-  const int syncCount = hasSyncOption() ? 2 : 0;
-  return epub->getTocItemsCount() + syncCount;
-}
-
-bool EpubReaderChapterSelectionActivity::isSyncItem(int index) const {
-  if (!hasSyncOption()) return false;
-  // First item and last item are sync options
-  return index == 0 || index == getTotalItems() - 1;
-}
-
-int EpubReaderChapterSelectionActivity::tocIndexFromItemIndex(int itemIndex) const {
-  // Account for the sync option at the top
-  const int offset = hasSyncOption() ? 1 : 0;
-  return itemIndex - offset;
-}
+int EpubReaderChapterSelectionActivity::getTotalItems() const { return epub->getTocItemsCount(); }
 
 int EpubReaderChapterSelectionActivity::getPageItems() const {
   // Layout constants used in renderScreen
-  constexpr int startY = 60;
   constexpr int lineHeight = 30;
 
   const int screenHeight = renderer.getScreenHeight();
-  const int endY = screenHeight - lineHeight;
-
-  const int availableHeight = endY - startY;
-  int items = availableHeight / lineHeight;
-
-  // Ensure we always have at least one item per page to avoid division by zero
-  if (items < 1) {
-    items = 1;
-  }
-  return items;
+  const auto orientation = renderer.getOrientation();
+  // In inverted portrait, the button hints are drawn near the logical top.
+  // Reserve vertical space so list items do not collide with the hints.
+  const bool isPortraitInverted = orientation == GfxRenderer::Orientation::PortraitInverted;
+  const int hintGutterHeight = isPortraitInverted ? 50 : 0;
+  const int startY = 60 + hintGutterHeight;
+  const int availableHeight = screenHeight - startY - lineHeight;
+  // Clamp to at least one item to avoid division by zero and empty paging.
+  return std::max(1, availableHeight / lineHeight);
 }
 
 void EpubReaderChapterSelectionActivity::taskTrampoline(void* param) {
@@ -64,13 +43,10 @@ void EpubReaderChapterSelectionActivity::onEnter() {
 
   renderingMutex = xSemaphoreCreateMutex();
 
-  // Account for sync option offset when finding current TOC index
-  const int syncOffset = hasSyncOption() ? 1 : 0;
   selectorIndex = epub->getTocIndexForSpineIndex(currentSpineIndex);
   if (selectorIndex == -1) {
     selectorIndex = 0;
   }
-  selectorIndex += syncOffset;  // Offset for top sync option
 
   // Trigger first update
   updateRequired = true;
@@ -95,24 +71,6 @@ void EpubReaderChapterSelectionActivity::onExit() {
   renderingMutex = nullptr;
 }
 
-void EpubReaderChapterSelectionActivity::launchSyncActivity() {
-  xSemaphoreTake(renderingMutex, portMAX_DELAY);
-  exitActivity();
-  enterNewActivity(new KOReaderSyncActivity(
-      renderer, mappedInput, epub, epubPath, currentSpineIndex, currentPage, totalPagesInSpine,
-      [this]() {
-        // On cancel
-        exitActivity();
-        updateRequired = true;
-      },
-      [this](int newSpineIndex, int newPage) {
-        // On sync complete
-        exitActivity();
-        onSyncPosition(newSpineIndex, newPage);
-      }));
-  xSemaphoreGive(renderingMutex);
-}
-
 void EpubReaderChapterSelectionActivity::loop() {
   if (subActivity) {
     subActivity->loop();
@@ -129,15 +87,7 @@ void EpubReaderChapterSelectionActivity::loop() {
   const int totalItems = getTotalItems();
 
   if (mappedInput.wasReleased(MappedInputManager::Button::Confirm)) {
-    // Check if sync option is selected (first or last item)
-    if (isSyncItem(selectorIndex)) {
-      launchSyncActivity();
-      return;
-    }
-
-    // Get TOC index (account for top sync offset)
-    const int tocIndex = tocIndexFromItemIndex(selectorIndex);
-    const auto newSpineIndex = epub->getSpineIndexForTocIndex(tocIndex);
+    const auto newSpineIndex = epub->getSpineIndexForTocIndex(selectorIndex);
     if (newSpineIndex == -1) {
       onGoBack();
     } else {
@@ -178,38 +128,48 @@ void EpubReaderChapterSelectionActivity::renderScreen() {
   renderer.clearScreen();
 
   const auto pageWidth = renderer.getScreenWidth();
+  const auto orientation = renderer.getOrientation();
+  // Landscape orientation: reserve a horizontal gutter for button hints.
+  const bool isLandscapeCw = orientation == GfxRenderer::Orientation::LandscapeClockwise;
+  const bool isLandscapeCcw = orientation == GfxRenderer::Orientation::LandscapeCounterClockwise;
+  // Inverted portrait: reserve vertical space for hints at the top.
+  const bool isPortraitInverted = orientation == GfxRenderer::Orientation::PortraitInverted;
+  const int hintGutterWidth = (isLandscapeCw || isLandscapeCcw) ? 30 : 0;
+  // Landscape CW places hints on the left edge; CCW keeps them on the right.
+  const int contentX = isLandscapeCw ? hintGutterWidth : 0;
+  const int contentWidth = pageWidth - hintGutterWidth;
+  const int hintGutterHeight = isPortraitInverted ? 50 : 0;
+  const int contentY = hintGutterHeight;
   const int pageItems = getPageItems();
   const int totalItems = getTotalItems();
 
-  const std::string title =
-      renderer.truncatedText(UI_12_FONT_ID, epub->getTitle().c_str(), pageWidth - 40, EpdFontFamily::BOLD);
-  renderer.drawCenteredText(UI_12_FONT_ID, 15, title.c_str(), true, EpdFontFamily::BOLD);
+  // Manual centering to honor content gutters.
+  const int titleX =
+      contentX + (contentWidth - renderer.getTextWidth(UI_12_FONT_ID, "Go to Chapter", EpdFontFamily::BOLD)) / 2;
+  renderer.drawText(UI_12_FONT_ID, titleX, 15 + contentY, "Go to Chapter", true, EpdFontFamily::BOLD);
 
   const auto pageStartIndex = selectorIndex / pageItems * pageItems;
-  renderer.fillRect(0, 60 + (selectorIndex % pageItems) * 30 - 2, pageWidth - 1, 30);
+  // Highlight only the content area, not the hint gutters.
+  renderer.fillRect(contentX, 60 + contentY + (selectorIndex % pageItems) * 30 - 2, contentWidth - 1, 30);
 
   for (int i = 0; i < pageItems; i++) {
     int itemIndex = pageStartIndex + i;
     if (itemIndex >= totalItems) break;
-    const int displayY = 60 + i * 30;
+    const int displayY = 60 + contentY + i * 30;
     const bool isSelected = (itemIndex == selectorIndex);
 
-    if (isSyncItem(itemIndex)) {
-      renderer.drawText(UI_10_FONT_ID, 20, displayY, ">> Sync Progress", !isSelected);
-    } else {
-      const int tocIndex = tocIndexFromItemIndex(itemIndex);
-      auto item = epub->getTocItem(tocIndex);
+    auto item = epub->getTocItem(itemIndex);
 
-      const int indentSize = 20 + (item.level - 1) * 15;
-      const std::string chapterName =
-          renderer.truncatedText(UI_10_FONT_ID, item.title.c_str(), pageWidth - 40 - indentSize);
+    // Indent per TOC level while keeping content within the gutter-safe region.
+    const int indentSize = contentX + 20 + (item.level - 1) * 15;
+    const std::string chapterName =
+        renderer.truncatedText(UI_10_FONT_ID, item.title.c_str(), contentWidth - 40 - indentSize);
 
-      renderer.drawText(UI_10_FONT_ID, indentSize, displayY, chapterName.c_str(), !isSelected);
-    }
+    renderer.drawText(UI_10_FONT_ID, indentSize, displayY, chapterName.c_str(), !isSelected);
   }
 
   const auto labels = mappedInput.mapLabels("« Back", "Select", "Up", "Down");
-  renderer.drawButtonHints(UI_10_FONT_ID, labels.btn1, labels.btn2, labels.btn3, labels.btn4);
+  GUI.drawButtonHints(renderer, labels.btn1, labels.btn2, labels.btn3, labels.btn4);
 
   renderer.displayBuffer();
 }

src/activities/reader/EpubReaderChapterSelectionActivity.h

@@ -26,22 +26,12 @@ class EpubReaderChapterSelectionActivity final : public ActivityWithSubactivity
   // This adapts automatically when switching between portrait and landscape.
   int getPageItems() const;
 
-  // Total items including sync options (top and bottom)
+  // Total TOC items count
   int getTotalItems() const;
 
-  // Check if sync option is available (credentials configured)
-  bool hasSyncOption() const;
-
-  // Check if given item index is a sync option (first or last)
-  bool isSyncItem(int index) const;
-
-  // Convert item index to TOC index (accounting for top sync option offset)
-  int tocIndexFromItemIndex(int itemIndex) const;
-
   static void taskTrampoline(void* param);
   [[noreturn]] void displayTaskLoop();
   void renderScreen();
-  void launchSyncActivity();
 
  public:
   explicit EpubReaderChapterSelectionActivity(GfxRenderer& renderer, MappedInputManager& mappedInput,

src/activities/reader/EpubReaderMenuActivity.cpp

@@ -0,0 +1,146 @@
+#include "EpubReaderMenuActivity.h"
+
+#include <GfxRenderer.h>
+
+#include "MappedInputManager.h"
+#include "components/UITheme.h"
+#include "fontIds.h"
+
+void EpubReaderMenuActivity::onEnter() {
+  ActivityWithSubactivity::onEnter();
+  renderingMutex = xSemaphoreCreateMutex();
+  updateRequired = true;
+
+  xTaskCreate(&EpubReaderMenuActivity::taskTrampoline, "EpubMenuTask", 4096, this, 1, &displayTaskHandle);
+}
+
+void EpubReaderMenuActivity::onExit() {
+  ActivityWithSubactivity::onExit();
+  xSemaphoreTake(renderingMutex, portMAX_DELAY);
+  if (displayTaskHandle) {
+    vTaskDelete(displayTaskHandle);
+    displayTaskHandle = nullptr;
+  }
+  vSemaphoreDelete(renderingMutex);
+  renderingMutex = nullptr;
+}
+
+void EpubReaderMenuActivity::taskTrampoline(void* param) {
+  auto* self = static_cast<EpubReaderMenuActivity*>(param);
+  self->displayTaskLoop();
+}
+
+void EpubReaderMenuActivity::displayTaskLoop() {
+  while (true) {
+    if (updateRequired && !subActivity) {
+      updateRequired = false;
+      xSemaphoreTake(renderingMutex, portMAX_DELAY);
+      renderScreen();
+      xSemaphoreGive(renderingMutex);
+    }
+    vTaskDelay(10 / portTICK_PERIOD_MS);
+  }
+}
+
+void EpubReaderMenuActivity::loop() {
+  if (subActivity) {
+    subActivity->loop();
+    return;
+  }
+
+  // Use local variables for items we need to check after potential deletion
+  if (mappedInput.wasReleased(MappedInputManager::Button::Up) ||
+      mappedInput.wasReleased(MappedInputManager::Button::Left)) {
+    selectedIndex = (selectedIndex + menuItems.size() - 1) % menuItems.size();
+    updateRequired = true;
+  } else if (mappedInput.wasReleased(MappedInputManager::Button::Down) ||
+             mappedInput.wasReleased(MappedInputManager::Button::Right)) {
+    selectedIndex = (selectedIndex + 1) % menuItems.size();
+    updateRequired = true;
+  } else if (mappedInput.wasReleased(MappedInputManager::Button::Confirm)) {
+    const auto selectedAction = menuItems[selectedIndex].action;
+    if (selectedAction == MenuAction::ROTATE_SCREEN) {
+      // Cycle orientation preview locally; actual rotation happens on menu exit.
+      pendingOrientation = (pendingOrientation + 1) % orientationLabels.size();
+      updateRequired = true;
+      return;
+    }
+
+    // 1. Capture the callback and action locally
+    auto actionCallback = onAction;
+
+    // 2. Execute the callback
+    actionCallback(selectedAction);
+
+    // 3. CRITICAL: Return immediately. 'this' is likely deleted now.
+    return;
+  } else if (mappedInput.wasReleased(MappedInputManager::Button::Back)) {
+    // Return the pending orientation to the parent so it can apply on exit.
+    onBack(pendingOrientation);
+    return;  // Also return here just in case
+  }
+}
+
+void EpubReaderMenuActivity::renderScreen() {
+  renderer.clearScreen();
+  const auto pageWidth = renderer.getScreenWidth();
+  const auto orientation = renderer.getOrientation();
+  // Landscape orientation: button hints are drawn along a vertical edge, so we
+  // reserve a horizontal gutter to prevent overlap with menu content.
+  const bool isLandscapeCw = orientation == GfxRenderer::Orientation::LandscapeClockwise;
+  const bool isLandscapeCcw = orientation == GfxRenderer::Orientation::LandscapeCounterClockwise;
+  // Inverted portrait: button hints appear near the logical top, so we reserve
+  // vertical space to keep the header and list clear.
+  const bool isPortraitInverted = orientation == GfxRenderer::Orientation::PortraitInverted;
+  const int hintGutterWidth = (isLandscapeCw || isLandscapeCcw) ? 30 : 0;
+  // Landscape CW places hints on the left edge; CCW keeps them on the right.
+  const int contentX = isLandscapeCw ? hintGutterWidth : 0;
+  const int contentWidth = pageWidth - hintGutterWidth;
+  const int hintGutterHeight = isPortraitInverted ? 50 : 0;
+  const int contentY = hintGutterHeight;
+
+  // Title
+  const std::string truncTitle =
+      renderer.truncatedText(UI_12_FONT_ID, title.c_str(), contentWidth - 40, EpdFontFamily::BOLD);
+  // Manual centering so we can respect the content gutter.
+  const int titleX =
+      contentX + (contentWidth - renderer.getTextWidth(UI_12_FONT_ID, truncTitle.c_str(), EpdFontFamily::BOLD)) / 2;
+  renderer.drawText(UI_12_FONT_ID, titleX, 15 + contentY, truncTitle.c_str(), true, EpdFontFamily::BOLD);
+
+  // Progress summary
+  std::string progressLine;
+  if (totalPages > 0) {
+    progressLine = "Chapter: " + std::to_string(currentPage) + "/" + std::to_string(totalPages) + " pages  |  ";
+  }
+  progressLine += "Book: " + std::to_string(bookProgressPercent) + "%";
+  renderer.drawCenteredText(UI_10_FONT_ID, 45, progressLine.c_str());
+
+  // Menu Items
+  const int startY = 75 + contentY;
+  constexpr int lineHeight = 30;
+
+  for (size_t i = 0; i < menuItems.size(); ++i) {
+    const int displayY = startY + (i * lineHeight);
+    const bool isSelected = (static_cast<int>(i) == selectedIndex);
+
+    if (isSelected) {
+      // Highlight only the content area so we don't paint over hint gutters.
+      renderer.fillRect(contentX, displayY, contentWidth - 1, lineHeight, true);
+    }
+
+    renderer.drawText(UI_10_FONT_ID, contentX + 20, displayY, menuItems[i].label.c_str(), !isSelected);
+
+    if (menuItems[i].action == MenuAction::ROTATE_SCREEN) {
+      // Render current orientation value on the right edge of the content area.
+      const auto value = orientationLabels[pendingOrientation];
+      const auto width = renderer.getTextWidth(UI_10_FONT_ID, value);
+      renderer.drawText(UI_10_FONT_ID, contentX + contentWidth - 20 - width, displayY, value, !isSelected);
+    }
+  }
+
+  // Footer / Hints
+  const auto labels = mappedInput.mapLabels("« Back", "Select", "Up", "Down");
+  GUI.drawButtonHints(renderer, labels.btn1, labels.btn2, labels.btn3, labels.btn4);
+
+  renderer.displayBuffer();
+}

src/activities/reader/EpubReaderMenuActivity.h

@@ -0,0 +1,64 @@
+#pragma once
+#include <Epub.h>
+#include <freertos/FreeRTOS.h>
+#include <freertos/semphr.h>
+#include <freertos/task.h>
+
+#include <functional>
+#include <string>
+#include <vector>
+
+#include "../ActivityWithSubactivity.h"
+
+class EpubReaderMenuActivity final : public ActivityWithSubactivity {
+ public:
+  // Menu actions available from the reader menu.
+  enum class MenuAction { SELECT_CHAPTER, GO_TO_PERCENT, ROTATE_SCREEN, GO_HOME, SYNC, DELETE_CACHE };
+
+  explicit EpubReaderMenuActivity(GfxRenderer& renderer, MappedInputManager& mappedInput, const std::string& title,
+                                  const int currentPage, const int totalPages, const int bookProgressPercent,
+                                  const uint8_t currentOrientation, const std::function<void(uint8_t)>& onBack,
+                                  const std::function<void(MenuAction)>& onAction)
+      : ActivityWithSubactivity("EpubReaderMenu", renderer, mappedInput),
+        title(title),
+        pendingOrientation(currentOrientation),
+        currentPage(currentPage),
+        totalPages(totalPages),
+        bookProgressPercent(bookProgressPercent),
+        onBack(onBack),
+        onAction(onAction) {}
+
+  void onEnter() override;
+  void onExit() override;
+  void loop() override;
+
+ private:
+  struct MenuItem {
+    MenuAction action;
+    std::string label;
+  };
+
+  // Fixed menu layout (order matters for up/down navigation).
+  const std::vector<MenuItem> menuItems = {
+      {MenuAction::SELECT_CHAPTER, "Go to Chapter"}, {MenuAction::ROTATE_SCREEN, "Reading Orientation"},
+      {MenuAction::GO_TO_PERCENT, "Go to %"},        {MenuAction::GO_HOME, "Go Home"},
+      {MenuAction::SYNC, "Sync Progress"},           {MenuAction::DELETE_CACHE, "Delete Book Cache"}};
+
+  int selectedIndex = 0;
+  bool updateRequired = false;
+  TaskHandle_t displayTaskHandle = nullptr;
+  SemaphoreHandle_t renderingMutex = nullptr;
+  std::string title = "Reader Menu";
+  uint8_t pendingOrientation = 0;
+  const std::vector<const char*> orientationLabels = {"Portrait", "Landscape CW", "Inverted", "Landscape CCW"};
+  int currentPage = 0;
+  int totalPages = 0;
+  int bookProgressPercent = 0;
+
+  const std::function<void(uint8_t)> onBack;
+  const std::function<void(MenuAction)> onAction;
+
+  static void taskTrampoline(void* param);
+  [[noreturn]] void displayTaskLoop();
+  void renderScreen();
+};

src/activities/reader/EpubReaderPercentSelectionActivity.cpp

@@ -0,0 +1,139 @@
+#include "EpubReaderPercentSelectionActivity.h"
+
+#include <GfxRenderer.h>
+
+#include "MappedInputManager.h"
+#include "components/UITheme.h"
+#include "fontIds.h"
+
+namespace {
+// Fine/coarse slider step sizes for percent adjustments.
+constexpr int kSmallStep = 1;
+constexpr int kLargeStep = 10;
+}  // namespace
+
+void EpubReaderPercentSelectionActivity::onEnter() {
+  ActivityWithSubactivity::onEnter();
+  // Set up rendering task and mark first frame dirty.
+  renderingMutex = xSemaphoreCreateMutex();
+  updateRequired = true;
+  xTaskCreate(&EpubReaderPercentSelectionActivity::taskTrampoline, "EpubPercentSlider", 4096, this, 1,
+              &displayTaskHandle);
+}
+
+void EpubReaderPercentSelectionActivity::onExit() {
+  ActivityWithSubactivity::onExit();
+  // Ensure the render task is stopped before freeing the mutex.
+  xSemaphoreTake(renderingMutex, portMAX_DELAY);
+  if (displayTaskHandle) {
+    vTaskDelete(displayTaskHandle);
+    displayTaskHandle = nullptr;
+  }
+  vSemaphoreDelete(renderingMutex);
+  renderingMutex = nullptr;
+}
+
+void EpubReaderPercentSelectionActivity::taskTrampoline(void* param) {
+  auto* self = static_cast<EpubReaderPercentSelectionActivity*>(param);
+  self->displayTaskLoop();
+}
+
+void EpubReaderPercentSelectionActivity::displayTaskLoop() {
+  while (true) {
+    // Render only when the view is dirty and no subactivity is running.
+    if (updateRequired && !subActivity) {
+      updateRequired = false;
+      xSemaphoreTake(renderingMutex, portMAX_DELAY);
+      renderScreen();
+      xSemaphoreGive(renderingMutex);
+    }
+    vTaskDelay(10 / portTICK_PERIOD_MS);
+  }
+}
+
+void EpubReaderPercentSelectionActivity::adjustPercent(const int delta) {
+  // Apply delta and clamp within 0-100.
+  percent += delta;
+  if (percent < 0) {
+    percent = 0;
+  } else if (percent > 100) {
+    percent = 100;
+  }
+  updateRequired = true;
+}
+
+void EpubReaderPercentSelectionActivity::loop() {
+  if (subActivity) {
+    subActivity->loop();
+    return;
+  }
+
+  // Back cancels, confirm selects, arrows adjust the percent.
+  if (mappedInput.wasReleased(MappedInputManager::Button::Back)) {
+    onCancel();
+    return;
+  }
+
+  if (mappedInput.wasReleased(MappedInputManager::Button::Confirm)) {
+    onSelect(percent);
+    return;
+  }
+
+  if (mappedInput.wasReleased(MappedInputManager::Button::Left)) {
+    adjustPercent(-kSmallStep);
+    return;
+  }
+
+  if (mappedInput.wasReleased(MappedInputManager::Button::Right)) {
+    adjustPercent(kSmallStep);
+    return;
+  }
+
+  if (mappedInput.wasReleased(MappedInputManager::Button::Up)) {
+    adjustPercent(kLargeStep);
+    return;
+  }
+
+  if (mappedInput.wasReleased(MappedInputManager::Button::Down)) {
+    adjustPercent(-kLargeStep);
+    return;
+  }
+}
+
+void EpubReaderPercentSelectionActivity::renderScreen() {
+  renderer.clearScreen();
+
+  // Title and numeric percent value.
+  renderer.drawCenteredText(UI_12_FONT_ID, 15, "Go to Position", true, EpdFontFamily::BOLD);
+
+  const std::string percentText = std::to_string(percent) + "%";
+  renderer.drawCenteredText(UI_12_FONT_ID, 90, percentText.c_str(), true, EpdFontFamily::BOLD);
+
+  // Draw slider track.
+  const int screenWidth = renderer.getScreenWidth();
+  constexpr int barWidth = 360;
+  constexpr int barHeight = 16;
+  const int barX = (screenWidth - barWidth) / 2;
+  const int barY = 140;
+
+  renderer.drawRect(barX, barY, barWidth, barHeight);
+
+  // Fill slider based on percent.
+  const int fillWidth = (barWidth - 4) * percent / 100;
+  if (fillWidth > 0) {
+    renderer.fillRect(barX + 2, barY + 2, fillWidth, barHeight - 4);
+  }
+
+  // Draw a simple knob centered at the current percent.
+  const int knobX = barX + 2 + fillWidth - 2;
+  renderer.fillRect(knobX, barY - 4, 4, barHeight + 8, true);
+
+  // Hint text for step sizes.
+  renderer.drawCenteredText(SMALL_FONT_ID, barY + 30, "Left/Right: 1%  Up/Down: 10%", true);
+
+  // Button hints follow the current front button layout.
+  const auto labels = mappedInput.mapLabels("« Back", "Select", "-", "+");
+  GUI.drawButtonHints(renderer, labels.btn1, labels.btn2, labels.btn3, labels.btn4);
+
+  renderer.displayBuffer();
+}

src/activities/reader/EpubReaderPercentSelectionActivity.h

@@ -0,0 +1,46 @@
+#pragma once
+#include <freertos/FreeRTOS.h>
+#include <freertos/semphr.h>
+#include <freertos/task.h>
+
+#include <functional>
+
+#include "MappedInputManager.h"
+#include "activities/ActivityWithSubactivity.h"
+
+class EpubReaderPercentSelectionActivity final : public ActivityWithSubactivity {
+ public:
+  // Slider-style percent selector for jumping within a book.
+  explicit EpubReaderPercentSelectionActivity(GfxRenderer& renderer, MappedInputManager& mappedInput,
+                                              const int initialPercent, const std::function<void(int)>& onSelect,
+                                              const std::function<void()>& onCancel)
+      : ActivityWithSubactivity("EpubReaderPercentSelection", renderer, mappedInput),
+        percent(initialPercent),
+        onSelect(onSelect),
+        onCancel(onCancel) {}
+
+  void onEnter() override;
+  void onExit() override;
+  void loop() override;
+
+ private:
+  // Current percent value (0-100) shown on the slider.
+  int percent = 0;
+  // Render dirty flag for the task loop.
+  bool updateRequired = false;
+  // FreeRTOS task and mutex for rendering.
+  TaskHandle_t displayTaskHandle = nullptr;
+  SemaphoreHandle_t renderingMutex = nullptr;
+
+  // Callback invoked when the user confirms a percent.
+  const std::function<void(int)> onSelect;
+  // Callback invoked when the user cancels the slider.
+  const std::function<void()> onCancel;
+
+  static void taskTrampoline(void* param);
+  [[noreturn]] void displayTaskLoop();
+  // Render the slider UI.
+  void renderScreen();
+  // Change the current percent by a delta and clamp within bounds.
+  void adjustPercent(int delta);
+};

src/activities/reader/KOReaderSyncActivity.cpp

@@ -8,6 +8,7 @@
 #include "KOReaderDocumentId.h"
 #include "MappedInputManager.h"
 #include "activities/network/WifiSelectionActivity.h"
+#include "components/UITheme.h"
 #include "fontIds.h"
 
 namespace {
@@ -266,7 +267,7 @@ void KOReaderSyncActivity::render() {
     renderer.drawCenteredText(UI_10_FONT_ID, 320, "Set up KOReader account in Settings");
 
     const auto labels = mappedInput.mapLabels("Back", "", "", "");
-    renderer.drawButtonHints(UI_10_FONT_ID, labels.btn1, labels.btn2, labels.btn3, labels.btn4);
+    GUI.drawButtonHints(renderer, labels.btn1, labels.btn2, labels.btn3, labels.btn4);
     renderer.displayBuffer();
     return;
   }
@@ -316,7 +317,6 @@ void KOReaderSyncActivity::render() {
              localProgress.percentage * 100);
     renderer.drawText(UI_10_FONT_ID, 20, 320, localPageStr);
 
-    // Options
     const int optionY = 350;
     const int optionHeight = 30;
 
@@ -332,14 +332,9 @@ void KOReaderSyncActivity::render() {
     }
     renderer.drawText(UI_10_FONT_ID, 20, optionY + optionHeight, "Upload local progress", selectedOption != 1);
 
-    // Cancel option
-    if (selectedOption == 2) {
-      renderer.fillRect(0, optionY + optionHeight * 2 - 2, pageWidth - 1, optionHeight);
-    }
-    renderer.drawText(UI_10_FONT_ID, 20, optionY + optionHeight * 2, "Cancel", selectedOption != 2);
-
-    const auto labels = mappedInput.mapLabels("", "Select", "", "");
-    renderer.drawButtonHints(UI_10_FONT_ID, labels.btn1, labels.btn2, labels.btn3, labels.btn4);
+    // Bottom button hints: show Back and Select
+    const auto labels = mappedInput.mapLabels("Back", "Select", "", "");
+    GUI.drawButtonHints(renderer, labels.btn1, labels.btn2, labels.btn3, labels.btn4);
     renderer.displayBuffer();
     return;
   }
@@ -348,8 +343,8 @@ void KOReaderSyncActivity::render() {
     renderer.drawCenteredText(UI_10_FONT_ID, 280, "No remote progress found", true, EpdFontFamily::BOLD);
     renderer.drawCenteredText(UI_10_FONT_ID, 320, "Upload current position?");
 
-    const auto labels = mappedInput.mapLabels("Cancel", "Upload", "", "");
-    renderer.drawButtonHints(UI_10_FONT_ID, labels.btn1, labels.btn2, labels.btn3, labels.btn4);
+    const auto labels = mappedInput.mapLabels("Back", "Upload", "", "");
+    GUI.drawButtonHints(renderer, labels.btn1, labels.btn2, labels.btn3, labels.btn4);
     renderer.displayBuffer();
     return;
   }
@@ -358,7 +353,7 @@ void KOReaderSyncActivity::render() {
     renderer.drawCenteredText(UI_10_FONT_ID, 300, "Progress uploaded!", true, EpdFontFamily::BOLD);
 
     const auto labels = mappedInput.mapLabels("Back", "", "", "");
-    renderer.drawButtonHints(UI_10_FONT_ID, labels.btn1, labels.btn2, labels.btn3, labels.btn4);
+    GUI.drawButtonHints(renderer, labels.btn1, labels.btn2, labels.btn3, labels.btn4);
     renderer.displayBuffer();
     return;
   }
@@ -368,7 +363,7 @@ void KOReaderSyncActivity::render() {
     renderer.drawCenteredText(UI_10_FONT_ID, 320, statusMessage.c_str());
 
     const auto labels = mappedInput.mapLabels("Back", "", "", "");
-    renderer.drawButtonHints(UI_10_FONT_ID, labels.btn1, labels.btn2, labels.btn3, labels.btn4);
+    GUI.drawButtonHints(renderer, labels.btn1, labels.btn2, labels.btn3, labels.btn4);
     renderer.displayBuffer();
     return;
   }
@@ -391,11 +386,11 @@ void KOReaderSyncActivity::loop() {
     // Navigate options
     if (mappedInput.wasPressed(MappedInputManager::Button::Up) ||
         mappedInput.wasPressed(MappedInputManager::Button::Left)) {
-      selectedOption = (selectedOption + 2) % 3;  // Wrap around
+      selectedOption = (selectedOption + 1) % 2;  // Wrap around among 2 options
       updateRequired = true;
     } else if (mappedInput.wasPressed(MappedInputManager::Button::Down) ||
                mappedInput.wasPressed(MappedInputManager::Button::Right)) {
-      selectedOption = (selectedOption + 1) % 3;
+      selectedOption = (selectedOption + 1) % 2;  // Wrap around among 2 options
       updateRequired = true;
     }
 
@@ -406,9 +401,6 @@ void KOReaderSyncActivity::loop() {
       } else if (selectedOption == 1) {
         // Upload local progress
         performUpload();
-      } else {
-        // Cancel
-        onCancel();
       }
     }
 

src/activities/reader/KOReaderSyncActivity.h

@@ -18,7 +18,7 @@
  * 1. Connect to WiFi (if not connected)
  * 2. Calculate document hash
  * 3. Fetch remote progress
- * 4. Show comparison and options (Apply/Upload/Cancel)
+ * 4. Show comparison and options (Apply/Upload)
  * 5. Apply or upload progress
  */
 class KOReaderSyncActivity final : public ActivityWithSubactivity {
@@ -82,7 +82,7 @@ class KOReaderSyncActivity final : public ActivityWithSubactivity {
   // Local progress as KOReader format (for display)
   KOReaderPosition localProgress;
 
-  // Selection in result screen (0=Apply, 1=Upload, 2=Cancel)
+  // Selection in result screen (0=Apply, 1=Upload)
   int selectedOption = 0;
 
   OnCancelCallback onCancel;

src/activities/reader/ReaderActivity.cpp

@@ -1,5 +1,7 @@
 #include "ReaderActivity.h"
 
+#include <HalStorage.h>
+
 #include "Epub.h"
 #include "EpubReaderActivity.h"
 #include "Txt.h"
@@ -27,7 +29,7 @@ bool ReaderActivity::isTxtFile(const std::string& path) {
 }
 
 std::unique_ptr<Epub> ReaderActivity::loadEpub(const std::string& path) {
-  if (!SdMan.exists(path.c_str())) {
+  if (!Storage.exists(path.c_str())) {
     Serial.printf("[%lu] [   ] File does not exist: %s\n", millis(), path.c_str());
     return nullptr;
   }
@@ -42,7 +44,7 @@ std::unique_ptr<Epub> ReaderActivity::loadEpub(const std::string& path) {
 }
 
 std::unique_ptr<Xtc> ReaderActivity::loadXtc(const std::string& path) {
-  if (!SdMan.exists(path.c_str())) {
+  if (!Storage.exists(path.c_str())) {
     Serial.printf("[%lu] [   ] File does not exist: %s\n", millis(), path.c_str());
     return nullptr;
   }
@@ -57,7 +59,7 @@ std::unique_ptr<Xtc> ReaderActivity::loadXtc(const std::string& path) {
 }
 
 std::unique_ptr<Txt> ReaderActivity::loadTxt(const std::string& path) {
-  if (!SdMan.exists(path.c_str())) {
+  if (!Storage.exists(path.c_str())) {
     Serial.printf("[%lu] [   ] File does not exist: %s\n", millis(), path.c_str());
     return nullptr;
   }
@@ -74,7 +76,7 @@ std::unique_ptr<Txt> ReaderActivity::loadTxt(const std::string& path) {
 void ReaderActivity::goToLibrary(const std::string& fromBookPath) {
   // If coming from a book, start in that book's folder; otherwise start from root
   const auto initialPath = fromBookPath.empty() ? "/" : extractFolderPath(fromBookPath);
-  onGoToLibrary(initialPath, libraryTab);
+  onGoToLibrary(initialPath);
 }
 
 void ReaderActivity::onGoToEpubReader(std::unique_ptr<Epub> epub) {

src/activities/reader/ReaderActivity.h

@@ -10,10 +10,9 @@ class Txt;
 
 class ReaderActivity final : public ActivityWithSubactivity {
   std::string initialBookPath;
-  std::string currentBookPath;        // Track current book path for navigation
-  MyLibraryActivity::Tab libraryTab;  // Track which tab to return to
+  std::string currentBookPath;  // Track current book path for navigation
   const std::function<void()> onGoBack;
-  const std::function<void(const std::string&, MyLibraryActivity::Tab)> onGoToLibrary;
+  const std::function<void(const std::string&)> onGoToLibrary;
   static std::unique_ptr<Epub> loadEpub(const std::string& path);
   static std::unique_ptr<Xtc> loadXtc(const std::string& path);
   static std::unique_ptr<Txt> loadTxt(const std::string& path);
@@ -28,12 +27,12 @@ class ReaderActivity final : public ActivityWithSubactivity {
 
  public:
   explicit ReaderActivity(GfxRenderer& renderer, MappedInputManager& mappedInput, std::string initialBookPath,
-                          MyLibraryActivity::Tab libraryTab, const std::function<void()>& onGoBack,
-                          const std::function<void(const std::string&, MyLibraryActivity::Tab)>& onGoToLibrary)
+                          const std::function<void()>& onGoBack,
+                          const std::function<void(const std::string&)>& onGoToLibrary)
       : ActivityWithSubactivity("Reader", renderer, mappedInput),
         initialBookPath(std::move(initialBookPath)),
-        libraryTab(libraryTab),
         onGoBack(onGoBack),
         onGoToLibrary(onGoToLibrary) {}
   void onEnter() override;
+  bool isReaderActivity() const override { return true; }
 };

src/activities/reader/TxtReaderActivity.cpp

@@ -1,7 +1,7 @@
 #include "TxtReaderActivity.h"
 
 #include <GfxRenderer.h>
-#include <SDCardManager.h>
+#include <HalStorage.h>
 #include <Serialization.h>
 #include <Utf8.h>
 
@@ -9,7 +9,7 @@
 #include "CrossPointState.h"
 #include "MappedInputManager.h"
 #include "RecentBooksStore.h"
-#include "ScreenComponents.h"
+#include "components/UITheme.h"
 #include "fontIds.h"
 
 namespace {
@@ -58,9 +58,11 @@ void TxtReaderActivity::onEnter() {
   txt->setupCacheDir();
 
   // Save current txt as last opened file and add to recent books
-  APP_STATE.openEpubPath = txt->getPath();
+  auto filePath = txt->getPath();
+  auto fileName = filePath.substr(filePath.rfind('/') + 1);
+  APP_STATE.openEpubPath = filePath;
   APP_STATE.saveToFile();
-  RECENT_BOOKS.addBook(txt->getPath(), "", "");
+  RECENT_BOOKS.addBook(filePath, fileName, "", "");
 
   // Trigger first update
   updateRequired = true;
@@ -89,6 +91,8 @@ void TxtReaderActivity::onExit() {
   renderingMutex = nullptr;
   pageOffsets.clear();
   currentPageLines.clear();
+  APP_STATE.readerActivityLoadCount = 0;
+  APP_STATE.saveToFile();
   txt.reset();
 }
 
@@ -98,15 +102,15 @@ void TxtReaderActivity::loop() {
     return;
   }
 
-  // Long press BACK (1s+) goes directly to home
+  // Long press BACK (1s+) goes to file selection
   if (mappedInput.isPressed(MappedInputManager::Button::Back) && mappedInput.getHeldTime() >= goHomeMs) {
-    onGoHome();
+    onGoBack();
     return;
   }
 
-  // Short press BACK goes to file selection
+  // Short press BACK goes directly to home
   if (mappedInput.wasReleased(MappedInputManager::Button::Back) && mappedInput.getHeldTime() < goHomeMs) {
-    onGoBack();
+    onGoHome();
     return;
   }
 
@@ -168,13 +172,16 @@ void TxtReaderActivity::initializeReader() {
   orientedMarginRight += cachedScreenMargin;
   orientedMarginBottom += cachedScreenMargin;
 
+  auto metrics = UITheme::getInstance().getMetrics();
+
   // Add status bar margin
   if (SETTINGS.statusBar != CrossPointSettings::STATUS_BAR_MODE::NONE) {
     // Add additional margin for status bar if progress bar is shown
-    const bool showProgressBar = SETTINGS.statusBar == CrossPointSettings::STATUS_BAR_MODE::FULL_WITH_PROGRESS_BAR ||
-                                 SETTINGS.statusBar == CrossPointSettings::STATUS_BAR_MODE::ONLY_PROGRESS_BAR;
+    const bool showProgressBar = SETTINGS.statusBar == CrossPointSettings::STATUS_BAR_MODE::BOOK_PROGRESS_BAR ||
+                                 SETTINGS.statusBar == CrossPointSettings::STATUS_BAR_MODE::ONLY_BOOK_PROGRESS_BAR ||
+                                 SETTINGS.statusBar == CrossPointSettings::STATUS_BAR_MODE::CHAPTER_PROGRESS_BAR;
     orientedMarginBottom += statusBarMargin - cachedScreenMargin +
-                            (showProgressBar ? (ScreenComponents::BOOK_PROGRESS_BAR_HEIGHT + progressBarMarginTop) : 0);
+                            (showProgressBar ? (metrics.bookProgressBarHeight + progressBarMarginTop) : 0);
   }
 
   viewportWidth = renderer.getScreenWidth() - orientedMarginLeft - orientedMarginRight;
@@ -207,28 +214,10 @@ void TxtReaderActivity::buildPageIndex() {
 
   size_t offset = 0;
   const size_t fileSize = txt->getFileSize();
-  int lastProgressPercent = -1;
 
   Serial.printf("[%lu] [TRS] Building page index for %zu bytes...\n", millis(), fileSize);
 
-  // Progress bar dimensions (matching EpubReaderActivity style)
-  constexpr int barWidth = 200;
-  constexpr int barHeight = 10;
-  constexpr int boxMargin = 20;
-  const int textWidth = renderer.getTextWidth(UI_12_FONT_ID, "Indexing...");
-  const int boxWidth = (barWidth > textWidth ? barWidth : textWidth) + boxMargin * 2;
-  const int boxHeight = renderer.getLineHeight(UI_12_FONT_ID) + barHeight + boxMargin * 3;
-  const int boxX = (renderer.getScreenWidth() - boxWidth) / 2;
-  constexpr int boxY = 50;
-  const int barX = boxX + (boxWidth - barWidth) / 2;
-  const int barY = boxY + renderer.getLineHeight(UI_12_FONT_ID) + boxMargin * 2;
-
-  // Draw initial progress box
-  renderer.fillRect(boxX, boxY, boxWidth, boxHeight, false);
-  renderer.drawText(UI_12_FONT_ID, boxX + boxMargin, boxY + boxMargin, "Indexing...");
-  renderer.drawRect(boxX + 5, boxY + 5, boxWidth - 10, boxHeight - 10);
-  renderer.drawRect(barX, barY, barWidth, barHeight);
-  renderer.displayBuffer();
+  GUI.drawPopup(renderer, "Indexing...");
 
   while (offset < fileSize) {
     std::vector<std::string> tempLines;
@@ -248,17 +237,6 @@ void TxtReaderActivity::buildPageIndex() {
       pageOffsets.push_back(offset);
     }
 
-    // Update progress bar every 10% (matching EpubReaderActivity logic)
-    int progressPercent = (offset * 100) / fileSize;
-    if (lastProgressPercent / 10 != progressPercent / 10) {
-      lastProgressPercent = progressPercent;
-
-      // Fill progress bar
-      const int fillWidth = (barWidth - 2) * progressPercent / 100;
-      renderer.fillRect(barX + 1, barY + 1, fillWidth, barHeight - 2, true);
-      renderer.displayBuffer(HalDisplay::FAST_REFRESH);
-    }
-
     // Yield to other tasks periodically
     if (pageOffsets.size() % 20 == 0) {
       vTaskDelay(1);
@@ -402,9 +380,6 @@ void TxtReaderActivity::renderScreen() {
 
   // Initialize reader if not done
   if (!initialized) {
-    renderer.clearScreen();
-    renderer.drawCenteredText(UI_12_FONT_ID, 300, "Indexing...", true, EpdFontFamily::BOLD);
-    renderer.displayBuffer();
     initializeReader();
   }
 
@@ -517,29 +492,37 @@ void TxtReaderActivity::renderPage() {
 void TxtReaderActivity::renderStatusBar(const int orientedMarginRight, const int orientedMarginBottom,
                                         const int orientedMarginLeft) const {
   const bool showProgressPercentage = SETTINGS.statusBar == CrossPointSettings::STATUS_BAR_MODE::FULL;
-  const bool showProgressBar = SETTINGS.statusBar == CrossPointSettings::STATUS_BAR_MODE::FULL_WITH_PROGRESS_BAR ||
-                               SETTINGS.statusBar == CrossPointSettings::STATUS_BAR_MODE::ONLY_PROGRESS_BAR;
+  const bool showProgressBar = SETTINGS.statusBar == CrossPointSettings::STATUS_BAR_MODE::BOOK_PROGRESS_BAR ||
+                               SETTINGS.statusBar == CrossPointSettings::STATUS_BAR_MODE::ONLY_BOOK_PROGRESS_BAR;
+  const bool showChapterProgressBar = SETTINGS.statusBar == CrossPointSettings::STATUS_BAR_MODE::CHAPTER_PROGRESS_BAR;
   const bool showProgressText = SETTINGS.statusBar == CrossPointSettings::STATUS_BAR_MODE::FULL ||
-                                SETTINGS.statusBar == CrossPointSettings::STATUS_BAR_MODE::FULL_WITH_PROGRESS_BAR;
+                                SETTINGS.statusBar == CrossPointSettings::STATUS_BAR_MODE::BOOK_PROGRESS_BAR;
+  const bool showBookPercentage = SETTINGS.statusBar == CrossPointSettings::STATUS_BAR_MODE::CHAPTER_PROGRESS_BAR;
   const bool showBattery = SETTINGS.statusBar == CrossPointSettings::STATUS_BAR_MODE::NO_PROGRESS ||
                            SETTINGS.statusBar == CrossPointSettings::STATUS_BAR_MODE::FULL ||
-                           SETTINGS.statusBar == CrossPointSettings::STATUS_BAR_MODE::FULL_WITH_PROGRESS_BAR;
+                           SETTINGS.statusBar == CrossPointSettings::STATUS_BAR_MODE::BOOK_PROGRESS_BAR ||
+                           SETTINGS.statusBar == CrossPointSettings::STATUS_BAR_MODE::CHAPTER_PROGRESS_BAR;
   const bool showTitle = SETTINGS.statusBar == CrossPointSettings::STATUS_BAR_MODE::NO_PROGRESS ||
                          SETTINGS.statusBar == CrossPointSettings::STATUS_BAR_MODE::FULL ||
-                         SETTINGS.statusBar == CrossPointSettings::STATUS_BAR_MODE::FULL_WITH_PROGRESS_BAR;
+                         SETTINGS.statusBar == CrossPointSettings::STATUS_BAR_MODE::BOOK_PROGRESS_BAR ||
+                         SETTINGS.statusBar == CrossPointSettings::STATUS_BAR_MODE::CHAPTER_PROGRESS_BAR;
   const bool showBatteryPercentage =
       SETTINGS.hideBatteryPercentage == CrossPointSettings::HIDE_BATTERY_PERCENTAGE::HIDE_NEVER;
 
+  auto metrics = UITheme::getInstance().getMetrics();
   const auto screenHeight = renderer.getScreenHeight();
+  // Adjust text position upward when progress bar is shown to avoid overlap
   const auto textY = screenHeight - orientedMarginBottom - 4;
   int progressTextWidth = 0;
 
   const float progress = totalPages > 0 ? (currentPage + 1) * 100.0f / totalPages : 0;
 
-  if (showProgressText || showProgressPercentage) {
+  if (showProgressText || showProgressPercentage || showBookPercentage) {
     char progressStr[32];
     if (showProgressPercentage) {
       snprintf(progressStr, sizeof(progressStr), "%d/%d %.0f%%", currentPage + 1, totalPages, progress);
+    } else if (showBookPercentage) {
+      snprintf(progressStr, sizeof(progressStr), "%.0f%%", progress);
     } else {
       snprintf(progressStr, sizeof(progressStr), "%d/%d", currentPage + 1, totalPages);
     }
@@ -551,11 +534,17 @@ void TxtReaderActivity::renderStatusBar(const int orientedMarginRight, const int
 
   if (showProgressBar) {
     // Draw progress bar at the very bottom of the screen, from edge to edge of viewable area
-    ScreenComponents::drawBookProgressBar(renderer, static_cast<size_t>(progress));
+    GUI.drawReadingProgressBar(renderer, static_cast<size_t>(progress));
+  }
+
+  if (showChapterProgressBar) {
+    // For text mode, treat the entire book as one chapter, so chapter progress == book progress
+    GUI.drawReadingProgressBar(renderer, static_cast<size_t>(progress));
   }
 
   if (showBattery) {
-    ScreenComponents::drawBattery(renderer, orientedMarginLeft, textY, showBatteryPercentage);
+    GUI.drawBattery(renderer, Rect{orientedMarginLeft, textY, metrics.batteryWidth, metrics.batteryHeight},
+                    showBatteryPercentage);
   }
 
   if (showTitle) {
@@ -565,8 +554,8 @@ void TxtReaderActivity::renderStatusBar(const int orientedMarginRight, const int
 
     std::string title = txt->getTitle();
     int titleWidth = renderer.getTextWidth(SMALL_FONT_ID, title.c_str());
-    while (titleWidth > availableTextWidth && title.length() > 11) {
-      title.replace(title.length() - 8, 8, "...");
+    if (titleWidth > availableTextWidth) {
+      title = renderer.truncatedText(SMALL_FONT_ID, title.c_str(), availableTextWidth);
       titleWidth = renderer.getTextWidth(SMALL_FONT_ID, title.c_str());
     }
 
@@ -576,7 +565,7 @@ void TxtReaderActivity::renderStatusBar(const int orientedMarginRight, const int
 
 void TxtReaderActivity::saveProgress() const {
   FsFile f;
-  if (SdMan.openFileForWrite("TRS", txt->getCachePath() + "/progress.bin", f)) {
+  if (Storage.openFileForWrite("TRS", txt->getCachePath() + "/progress.bin", f)) {
     uint8_t data[4];
     data[0] = currentPage & 0xFF;
     data[1] = (currentPage >> 8) & 0xFF;
@@ -589,7 +578,7 @@ void TxtReaderActivity::saveProgress() const {
 
 void TxtReaderActivity::loadProgress() {
   FsFile f;
-  if (SdMan.openFileForRead("TRS", txt->getCachePath() + "/progress.bin", f)) {
+  if (Storage.openFileForRead("TRS", txt->getCachePath() + "/progress.bin", f)) {
     uint8_t data[4];
     if (f.read(data, 4) == 4) {
       currentPage = data[0] + (data[1] << 8);
@@ -620,7 +609,7 @@ bool TxtReaderActivity::loadPageIndexCache() {
 
   std::string cachePath = txt->getCachePath() + "/index.bin";
   FsFile f;
-  if (!SdMan.openFileForRead("TRS", cachePath, f)) {
+  if (!Storage.openFileForRead("TRS", cachePath, f)) {
     Serial.printf("[%lu] [TRS] No page index cache found\n", millis());
     return false;
   }
@@ -712,7 +701,7 @@ bool TxtReaderActivity::loadPageIndexCache() {
 void TxtReaderActivity::savePageIndexCache() const {
   std::string cachePath = txt->getCachePath() + "/index.bin";
   FsFile f;
-  if (!SdMan.openFileForWrite("TRS", cachePath, f)) {
+  if (!Storage.openFileForWrite("TRS", cachePath, f)) {
     Serial.printf("[%lu] [TRS] Failed to save page index cache\n", millis());
     return;
   }

src/activities/reader/XtcReaderActivity.cpp

@@ -9,13 +9,14 @@
 
 #include <FsHelpers.h>
 #include <GfxRenderer.h>
-#include <SDCardManager.h>
+#include <HalStorage.h>
 
 #include "CrossPointSettings.h"
 #include "CrossPointState.h"
 #include "MappedInputManager.h"
 #include "RecentBooksStore.h"
 #include "XtcReaderChapterSelectionActivity.h"
+#include "components/UITheme.h"
 #include "fontIds.h"
 
 namespace {
@@ -45,7 +46,7 @@ void XtcReaderActivity::onEnter() {
   // Save current XTC as last opened book and add to recent books
   APP_STATE.openEpubPath = xtc->getPath();
   APP_STATE.saveToFile();
-  RECENT_BOOKS.addBook(xtc->getPath(), xtc->getTitle(), xtc->getAuthor());
+  RECENT_BOOKS.addBook(xtc->getPath(), xtc->getTitle(), xtc->getAuthor(), xtc->getThumbBmpPath());
 
   // Trigger first update
   updateRequired = true;
@@ -69,6 +70,8 @@ void XtcReaderActivity::onExit() {
   }
   vSemaphoreDelete(renderingMutex);
   renderingMutex = nullptr;
+  APP_STATE.readerActivityLoadCount = 0;
+  APP_STATE.saveToFile();
   xtc.reset();
 }
 
@@ -99,15 +102,15 @@ void XtcReaderActivity::loop() {
     }
   }
 
-  // Long press BACK (1s+) goes directly to home
+  // Long press BACK (1s+) goes to file selection
   if (mappedInput.isPressed(MappedInputManager::Button::Back) && mappedInput.getHeldTime() >= goHomeMs) {
-    onGoHome();
+    onGoBack();
     return;
   }
 
-  // Short press BACK goes to file selection
+  // Short press BACK goes directly to home
   if (mappedInput.wasReleased(MappedInputManager::Button::Back) && mappedInput.getHeldTime() < goHomeMs) {
-    onGoBack();
+    onGoHome();
     return;
   }
 
@@ -369,7 +372,7 @@ void XtcReaderActivity::renderPage() {
 
 void XtcReaderActivity::saveProgress() const {
   FsFile f;
-  if (SdMan.openFileForWrite("XTR", xtc->getCachePath() + "/progress.bin", f)) {
+  if (Storage.openFileForWrite("XTR", xtc->getCachePath() + "/progress.bin", f)) {
     uint8_t data[4];
     data[0] = currentPage & 0xFF;
     data[1] = (currentPage >> 8) & 0xFF;
@@ -382,7 +385,7 @@ void XtcReaderActivity::saveProgress() const {
 
 void XtcReaderActivity::loadProgress() {
   FsFile f;
-  if (SdMan.openFileForRead("XTR", xtc->getCachePath() + "/progress.bin", f)) {
+  if (Storage.openFileForRead("XTR", xtc->getCachePath() + "/progress.bin", f)) {
     uint8_t data[4];
     if (f.read(data, 4) == 4) {
       currentPage = data[0] | (data[1] << 8) | (data[2] << 16) | (data[3] << 24);