fix: duplicate User-Agent header on wolfSSL requests breaks strict servers (aiohttp 400) (#2661)

Updated SCOPE.md to remove unnecessary line breaks and improve readability.

.claude/skills/README.md

@@ -0,0 +1,33 @@
+# CrossPoint Reader: Claude Code skills
+
+Project skills for Claude Code. Claude auto-discovers them and loads one when the
+task matches its `description`; you do not invoke them by hand. They encode how
+this project wants C/C++ written: the judgment calls and self-review gates that
+keep the firmware small, stable, and reviewable.
+
+These are written for capable agents, not beginners. They are principle- and
+decision-focused on purpose. They deliberately avoid line-number citations,
+which drift; they anchor on durable names (APIs, types, macros, files).
+
+This is separate from `.skills/SKILL.md`, the GitHub coding-agent guide that
+mirrors CLAUDE.md. CLAUDE.md stays the always-loaded rule set; these skills are
+the applied decision procedures that load on demand and add the judgment layer
+CLAUDE.md does not carry.
+
+| Skill | Loads when you are... |
+|---|---|
+| `heap-discipline` | allocating memory: new/malloc/vector/string, buffers, caches |
+| `control-flow-clarity` | writing branching logic, state flags, modes, if/else ladders |
+| `hal-and-abstractions` | touching storage, input, display, settings, i18n, rendering |
+| `scope-discipline` | adding a feature, activity, lib, setting, or dependency |
+| `refactor-for-review` | refactoring, cleaning up, or preparing a change for PR |
+
+Each skill ends with a self-review checklist Claude runs against its own diff
+before handing it back. Reviewing a PR? Those checklists double as a fast rubric.
+
+## Maintaining these
+
+Edit the `SKILL.md` under each directory. Keep them tight. Do not restate
+CLAUDE.md; add the judgment CLAUDE.md cannot afford to carry. Trigger quality
+lives in the `description` field: it must name the situations that should pull
+the skill in, in the words a contributor's task would use.

.claude/skills/control-flow-clarity/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: control-flow-clarity
+description: Branching and state-modeling clarity in C/C++. Use when writing or refactoring logic that branches on discrete values: if/else-if ladders, status flags, mode or state ints, or anything that should be an enum plus an exhaustive switch. Covers enum class over magic ints, exhaustive switch over nested if, early-return guard clauses, table dispatch, and when each is the right call.
+---
+
+# Control-Flow Clarity
+
+The goal: a reviewer verifies correctness by reading, not by tracing. Branching
+that mirrors the problem's shape is self-evident; branching that encodes it in
+ad-hoc ints and nesting forces the reader to reconstruct intent.
+
+## Core moves
+
+- **Model a closed set of states/modes as an `enum class`, not ints or bools.**
+  A variable kept honest by a comment ("0 = hidden, 1 = showing, 2 = confirm")
+  is a latent bug. Make it an enum and the comment becomes the type.
+- **Dispatch on an enum with an exhaustive `switch`, no `default`.** This
+  codebase relies on it: omitting `default` lets the compiler flag the
+  unhandled case when someone adds an enum value. A `default:` that swallows the
+  unknown case throws that safety away. Add `default` only when "every other
+  value does nothing" is a deliberate, documented decision.
+- **Replace nested `if/else-if` ladders that branch on one discriminant with a
+  `switch`.** If each branch only maps input to a value, prefer a lookup table
+  (`static constexpr` array) over both.
+- **Prefer early-return guard clauses over nested success bodies.** Handle the
+  error/empty/skip cases first and return; keep the main path at the left
+  margin.
+
+## When NOT to switch
+
+- Branches test unrelated conditions, not one discriminant: a guarded `if`
+  sequence is honest; a switch would be forced.
+- Two outcomes on a genuine boolean: keep the `if`.
+- The discriminant is an open or unbounded set (arbitrary ints, strings): table
+  or map, not a switch.
+
+## Enum hygiene
+
+- `enum class` by default for type safety. Plain `enum` only when values must
+  implicitly convert (e.g. a value that doubles as a UI dropdown index), and
+  then give it a trailing `_COUNT` sentinel for safe bounds/iteration, matching
+  the existing settings enums.
+- Name the discriminant after what it selects, not its storage:
+  `Orientation orientation`, not `uint8_t mode`.
+- No magic numeric codes for states. If you write a comment mapping numbers to
+  meanings, you owe an enum.
+
+## Self-review
+
+- [ ] No int/bool standing in for a closed set of modes; it is an `enum class`.
+- [ ] Enum dispatch is an exhaustive `switch` with no catch-all `default` (or
+      the `default` is a documented deliberate choice).
+- [ ] No nested if/else-if ladder on a single discriminant that should be a
+      switch or a table.
+- [ ] Error/skip cases are early-return guards; the happy path is not buried.
+- [ ] No magic numbers where a named enum or `constexpr` would state the intent.

.claude/skills/hal-and-abstractions/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: hal-and-abstractions
+description: Layering and abstraction discipline for the firmware. Use when touching storage, input, display, settings, i18n, or rendering, or any code that could reach into the SDK. Covers routing through the HAL (HalStorage / HalGPIO / HalDisplay) instead of raw SDK classes, MappedInputManager logical buttons instead of raw GPIO indices, UITheme/GUI for all rendering, the singleton macros, tr() for user-facing text, and where a new abstraction boundary belongs.
+---
+
+# HAL and Abstractions
+
+CLAUDE.md lists the HAL classes and the SdFat-concurrency reason they exist.
+This is when and how to route through them, and where to draw a new boundary.
+
+## Route through the layer, always
+
+- **SD card I/O:** `Storage` (HalStorage) and `HalFile`. Never `SdFat`,
+  `FsFile`, `SdSpiCard`, `FsBaseFile`, or `SDCardManager` directly. The HAL
+  serializes every SD access through one mutex; bypassing it races the SPI state
+  machine and panics FreeRTOS (CLAUDE.md has the failure mode). This is a
+  correctness boundary, not a style preference.
+- **Display:** `HalDisplay` over `EInkDisplay`. **Input:** `HalGPIO` over
+  `InputManager`.
+- **Rendering:** everything through the `GUI` macro (UITheme) and the renderer's
+  oriented metrics. No hardcoded fonts, colors, coordinates, or 800/480
+  literals; ask the renderer for width/height and use the oriented viewable
+  area.
+- **Input in activities:** `MappedInputManager::Button` logical enums
+  (`Button::Confirm`, `Button::PageForward`, ...). Never raw `HalGPIO::BTN_*`
+  indices outside `ButtonRemapActivity`. Logical buttons survive user remapping
+  and orientation; raw indices do not.
+- **Shared state:** the singleton macros (`SETTINGS`, `APP_STATE`, `GUI`,
+  `Storage`, `I18N`), not threaded pointers.
+
+## User-facing text
+
+Every string a user reads goes through `tr(STR_*)`. Add the key to the English
+YAML, regenerate with `scripts/gen_i18n.py`, then use the `StrId`. Log lines
+(`LOG_*`) stay hardcoded.
+
+## Drawing a new boundary
+
+When you need an SDK capability the HAL does not expose yet, **add the method to
+the HAL; do not reach around it.** The new method inherits the mutex, logging,
+and error contract the rest of the HAL carries. A one-off direct SDK call in an
+activity is exactly the layering violation the mutex discipline cannot tolerate.
+
+Keep abstractions thin. A wrapper that only renames an SDK call without adding
+the mutex, logging, or an error contract is dead weight. Add a layer only when
+it carries one of those contracts or hides a real implementation choice.
+
+## Self-review
+
+- [ ] No direct SdFat / FsFile / SDCardManager / EInkDisplay / InputManager use
+      outside `lib/hal`.
+- [ ] File access uses `HalFile`; no `.close()` on a local handle
+      (DESTRUCTOR_CLOSES_FILE); members closed in `onExit`.
+- [ ] Input uses `MappedInputManager::Button`, not raw `BTN_*` indices.
+- [ ] Rendering goes through GUI/UITheme and oriented metrics; no 800/480 or
+      hardcoded fonts/coords.
+- [ ] User-facing strings use `tr(STR_*)`; new keys added to YAML and
+      regenerated.
+- [ ] Any new SDK capability is exposed as a HAL method, not called inline.

.claude/skills/heap-discipline/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: heap-discipline
+description: Memory allocation discipline for the ESP32-C3 (~380KB RAM, no PSRAM, single 48KB framebuffer). Use whenever writing or reviewing code that allocates: new / malloc / std::vector / std::string, buffers, caches, or anything held across a loop or an activity lifecycle. Covers makeUniqueNoThrow vs raw new/malloc, fragmentation avoidance, reserve-before-push_back, alloc-once-reuse, stack vs heap sizing, and the chunked grayscale buffer pattern.
+---
+
+# Heap Discipline (ESP32-C3)
+
+CLAUDE.md states the allocation rules. This is the procedure you run while
+writing the code and the gate you run before handing it back.
+
+The constraint that makes every call matter: ~380KB RAM, no PSRAM, one 48KB
+framebuffer. **Fragmentation, not total usage, is what kills this device.**
+Free-heap can read fine while the largest free block is too small for the next
+allocation. Optimize for not leaving holes, not just for using fewer bytes.
+
+## Allocation decision procedure
+
+Ask in order; stop at the first yes.
+
+1. **Stack?** Local, bounded, under ~256 bytes total: plain array/struct. No
+   heap, no fragmentation. Keep frames lean; the task stack is small.
+2. **Compile-time constant?** `static constexpr` lives in flash, costs zero DRAM.
+3. **Allocated once and reused for an activity's lifetime?** Allocate in
+   `onEnter`, hold in a member, release in `onExit`. Never per-frame, never
+   per-iteration.
+4. **Dynamic and fallible?** `makeUniqueNoThrow<T>(...)` /
+   `makeUniqueNoThrow<T[]>(n)` from `lib/Memory/Memory.h`. Null-check, `LOG_ERR`
+   with the size, return false. It frees on every exit path.
+5. **A C/SDK API takes ownership and frees it itself?** Only then raw
+   `new (std::nothrow)` / `malloc`, with a comment naming who frees it.
+
+Bare `new` / `new[]` is never correct here: under `-fno-exceptions` it calls
+`abort()` on OOM instead of returning null.
+
+## Fragmentation rules
+
+- `std::vector`: `reserve(n)` before any `push_back` loop. Each growth is
+  alloc-copy-free (three heap ops) and leaves a hole. Unknown n: estimate high.
+- No repeated `new`/`delete` or growing containers inside a loop or render path.
+  Hoist the allocation out of the loop.
+- Large contiguous blocks fragment worst. Full-screen-class buffers use the
+  chunked `storeBwBuffer` / `restoreBwBuffer` path in `GfxRenderer` so they
+  never demand one contiguous 48KB block. Reuse that path. Do not malloc a
+  second full-screen buffer.
+- `std::string` / Arduino `String`: acceptable on cold paths (file I/O, one-shot
+  setup). Banned on hot/render paths. Build text with a stack `char[]` +
+  `snprintf`; if a `std::string` is unavoidable, `reserve` it first.
+
+## Justify every allocation
+
+Per CLAUDE.md's evidence rule: when you add a heap allocation, state in one line
+why stack/static/reuse was rejected and the worst-case size. If you cannot name
+the size, you cannot budget it, and you should not allocate it.
+
+## Self-review before handoff
+
+- [ ] No bare `new`/`new[]`. Every fallible alloc is `makeUniqueNoThrow`, or a
+      raw alloc with an explicit owner comment.
+- [ ] Every allocation is null-checked with `LOG_ERR` before the error return.
+- [ ] No allocation inside a loop or render path that could be hoisted.
+- [ ] Every `push_back` loop has a preceding `reserve`.
+- [ ] Anything allocated in `onEnter` is released in `onExit`; member `HalFile`
+      closed there too.
+- [ ] No second full-screen buffer; grayscale uses store/restoreBwBuffer.
+- [ ] Each new allocation carries a one-line size + why-not-stack/static note.

.claude/skills/refactor-for-review/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: refactor-for-review
+description: Producing small, single-concern, reviewable changes. Use when refactoring, cleaning up, restructuring, decomposing, or preparing a change for PR, especially in this multi-contributor AI-assisted codebase that is prone to sprawl diffs. Covers one-concern-per-commit, extracting helpers without widening scope, not bundling unrelated edits, decomposing oversized activities, comment hygiene, and a pre-handoff self-review checklist.
+---
+
+# Refactor for Review
+
+This is a multi-contributor, AI-assisted codebase, and the dominant failure mode
+is the sprawl diff: a one-line intent that touches thirty files. The goal is a
+change a reviewer can verify in one sitting. Cleaner structure that makes the
+next change easier is the win, not lines added.
+
+## One concern per change
+
+- A commit/PR does one thing. A bug fix is not also a rename is not also a
+  reformat. If you spot an unrelated improvement mid-change, leave it or capture
+  it separately; do not fold it in.
+- When the working tree has bundled two changes, separate them with the
+  copy-affected-files-aside, reset, re-apply one concern, restore the rest
+  pattern, not by committing the tangle.
+- Refactor and behavior change do not ride together. A pure refactor must not
+  alter behavior; a behavior change should not drag a refactor along. If both
+  are needed: two commits, refactor first.
+
+## Keep the diff narrow
+
+- Extract a helper to remove real duplication or to name a concept, not to chase
+  abstraction. Three-plus copies, or a block that needs a name to be understood:
+  extract. Two similar lines: leave them.
+- No "while I'm here" scope creep. A signature or type change that ripples to
+  many call sites is its own PR: map every caller first, update them in one
+  topological pass, and land it separately, not as a rider on a feature.
+- Match the surrounding code: comment density, naming, idiom. The diff should
+  read like the file, not like a different author.
+
+## Decompose oversized units
+
+An activity or function that has outgrown one screen of responsibility (multiple
+unrelated state machines, or a file far larger than its siblings) is a
+decomposition candidate. Extract a cohesive sub-responsibility into its own
+unit, as a standalone behavior-preserving refactor, verified on its own, never
+mixed into a feature change.
+
+## Comments earn their place
+
+Comments explain why: an invariant, a defense, a past incident, a non-obvious
+constraint. Never what the next line already says. Delete narration, phase-marker
+comments ("now we loop over..."), and restated function names. If a comment and
+the code it sits on say the same thing, the comment is the thing to cut.
+
+## Self-review before handoff
+
+- [ ] The change does exactly one thing; nothing unrelated rode along.
+- [ ] Refactor and behavior change are not mixed in one commit.
+- [ ] No "while I'm here" creep; rename/signature ripples are split out.
+- [ ] Extractions remove real duplication or name a real concept, not
+      speculative abstraction.
+- [ ] New comments say why, not what; no narration or phase markers.
+- [ ] A reviewer can understand the diff without running it.

.claude/skills/scope-discipline/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: scope-discipline
+description: Feature-scope discipline for a dedicated e-reader (not a Swiss Army knife). Use when adding a feature, a new activity, a new lib, a setting, or a dependency, or when a request would grow the firmware's surface. Covers the SCOPE.md test, the RAM-cost vs reading-benefit gate, preferring no-code or existing-mechanism solutions, awareness of the existing activity surface, and how to push back on out-of-scope asks.
+---
+
+# Scope Discipline
+
+The mission: do one thing exceptionally well, focused reading on constrained
+hardware. `SCOPE.md` is the source of truth for what is in and out. Read it
+before adding surface. This is the gate to run before writing a new feature.
+
+## The gate
+
+Before adding a feature, activity, lib, setting, or dependency, answer in order:
+
+1. **Is it in `SCOPE.md`?** Explicitly out: interactive apps (notepad,
+   calculator, games), active connectivity (RSS, news, browser), media/audio
+   playback. If it is out, say so and stop.
+2. **Does it materially improve focused reading?** If the benefit is
+   "nice to have" or serves a different use case, it is out. This is not a PDA.
+3. **What does it cost in RAM and in the largest-free-block budget?** A feature
+   that adds steady-state RAM or a large transient allocation needs a reading
+   benefit that clearly outweighs it. Quantify with `firmware_size_history.py`
+   and `script_profile_mem.sh` rather than guessing.
+4. **Can it be done with no new code?** Prefer an existing activity, an existing
+   setting, or a doc over a new code path. The cheapest feature is the one
+   already built.
+
+If a request fails the gate, push back with the specific reason and the
+`SCOPE.md` basis, and offer the in-scope alternative. Make the call and say why;
+do not just hand over a menu.
+
+## Surface awareness
+
+The firmware already carries dozens of activities. Each new one is permanent
+RAM, permanent maintenance, and another thing every future refactor must not
+break. Default to extending an existing activity or setting before adding a new
+screen. New top-level surface needs a real justification, not "it would be
+convenient."
+
+## Settings are not free
+
+A new setting is a field to persist, migrate, validate, translate, and render,
+plus combinatorial test burden. Add one only when users genuinely need the
+choice; otherwise pick a sensible fixed default.
+
+## Self-review
+
+- [ ] Checked against `SCOPE.md`; not on the out-of-scope list.
+- [ ] Stated the concrete reading benefit, not a generic "useful."
+- [ ] Named the RAM/size cost (measured, not guessed) and why the benefit wins.
+- [ ] Checked whether an existing activity/setting/doc already covers it.
+- [ ] New setting (if any) is justified by a real user need, not added
+      "just in case."

.githooks/pre-commit

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+# Run formatter from repository root regardless of current directory.
+REPO_ROOT="$(git rev-parse --show-toplevel)"
+cd "${REPO_ROOT}"
+
+# Capture the files already staged for commit so we only re-stage those
+# paths after formatting.
+staged_files=()
+while IFS= read -r -d '' file; do
+  staged_files+=("${file}")
+done < <(git diff --cached --name-only -z --diff-filter=ACMR)
+
+# Intentionally format all currently modified tracked C/C++ files.
+# The helper handles no-op cases and exits 0 when nothing matches.
+echo "Running clang-format fix before commit..."
+./bin/clang-format-fix
+
+# Ensure formatting changes are included in the pending commit without
+# staging unrelated tracked modifications from other files in the
+# working tree.
+if ((${#staged_files[@]})); then
+  git add -- "${staged_files[@]}"
+fi

.github/FUNDING.yml

@@ -1,2 +1 @@
-github: [daveallie]
-ko_fi: daveallie
+custom: ["https://app.royalty.dev/crosspoint-reader/crosspoint-reader"]

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,13 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Scope or Roadmap Question (start here if unsure)
+    url: https://github.com/crosspoint-reader/crosspoint-reader/discussions
+    about: |
+      Not sure if your idea fits CrossPoint's scope? Start a Discussion before filing an issue.
+      See SCOPE.md and ROADMAP.md for what is in, out, and currently paused.
+  - name: Read the Scope document
+    url: https://github.com/crosspoint-reader/crosspoint-reader/blob/master/SCOPE.md
+    about: The authoritative list of what CrossPoint will and will not accept.
+  - name: Read the Roadmap
+    url: https://github.com/crosspoint-reader/crosspoint-reader/blob/master/ROADMAP.md
+    about: Current phase, what is being closed out, and what comes next.

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,80 @@
+name: Feature Request
+description: Propose a new feature, enhancement, or change to CrossPoint
+title: "Short, descriptive title of the request"
+labels: ["enhancement", "needs-scope-review"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to propose a change to CrossPoint!
+
+        **Before you continue, please read [SCOPE.md](../blob/master/SCOPE.md) and [ROADMAP.md](../blob/master/ROADMAP.md).**
+
+        CrossPoint is intentionally narrow. Most rejected proposals are rejected for scope reasons that are already
+        documented. The checklist below exists to save both of us time.
+
+        If you are not sure whether your idea fits, open a [Discussion](../../discussions) first instead of filing
+        this issue.
+
+  - type: checkboxes
+    id: scope-check
+    attributes:
+      label: Scope Self-Check (required)
+      description: Please confirm each of the following. If any are unchecked, your issue will likely be closed.
+      options:
+        - label: I have read SCOPE.md and ROADMAP.md.
+          required: true
+        - label: This is **not** a new theme or theming change (themes are temporarily closed pending the move to SD-loaded themes).
+          required: true
+        - label: This is **not** a new external network connector (sync engine, cloud storage, remote file access, OPDS extensions beyond what exists, or any new "talk to a server" feature).
+          required: true
+        - label: This is **not** an interactive app (game, calculator, notepad), writing/authoring tool, RSS/news/browser feature, media playback feature, or PDF rendering.
+          required: true
+        - label: The stock firmware does **not** already handle this well.
+          required: true
+        - label: No other popular CrossPoint fork already handles this well (or, if one does, I explain below why CrossPoint still needs it).
+          required: true
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem this solves
+      description: What user-facing problem or reading-experience gap does this address? Be concrete.
+      placeholder: e.g., "When reading in landscape, paragraph breaks are inconsistent because..."
+    validations:
+      required: true
+
+  - type: textarea
+    id: stock-gap
+    attributes:
+      label: Why the stock firmware (and other forks) do not already solve this
+      description: Explain which existing solutions you checked and why they fall short. This is the core scope filter.
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed change
+      description: A short description of what you would build or change. Focus on user impact; implementation details can come later.
+    validations:
+      required: true
+
+  - type: textarea
+    id: tradeoffs
+    attributes:
+      label: Memory / flash / complexity cost
+      description: |
+        CrossPoint runs on 380KB of RAM. Roughly how much DRAM, flash, or code complexity does this add?
+        "Don't know" is a valid answer, but please attempt an estimate.
+      placeholder: e.g., "Adds ~2KB flash for the new font tables, no DRAM impact at runtime."
+    validations:
+      required: false
+
+  - type: textarea
+    id: additional-context
+    attributes:
+      label: Additional context
+      description: Anything else relevant (links, screenshots, related discussions).
+    validations:
+      required: false

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,9 +1,36 @@
 ## Summary
 
-* **What is the goal of this PR?** (e.g., Fixes a bug in the user authentication module, Implements the new feature for 
-  file uploading.)
+* **What is the goal of this PR?** (e.g., Implements the new feature for file uploading.)
 * **What changes are included?**
 
+## Scope Check
+
+CrossPoint is intentionally narrow. See [SCOPE.md](../blob/master/SCOPE.md) and [ROADMAP.md](../blob/master/ROADMAP.md).
+Please confirm:
+
+- [ ] I have read SCOPE.md and ROADMAP.md.
+- [ ] This PR is **not** a new built-in theme (themes are temporarily closed pending the move to SD-loaded themes).
+- [ ] This PR is **not** a new external network connector (sync engine, cloud storage, remote file access, etc.).
+- [ ] This PR is **not** an interactive app, writing tool, RSS/news/browser, media playback, or PDF feature.
+- [ ] The stock firmware does not already handle this well, **and** no other popular CrossPoint fork already does
+      (or, if one does, I explain why CrossPoint still needs it below).
+- [ ] If this PR touches `freeink-sdk/`, `lib/hal/`, the bootloader, OTA, or recovery code, I have coordinated with
+      the relevant maintainer.
+
+**If this PR was opened against the previous (broader) scope and was already in flight under Phase 0, link the
+relevant Discussion or issue so reviewers can see the history.**
+
 ## Additional Context
 
-* Add any other information that might be helpful for the reviewer (e.g., performance implications, potential risks, specific areas to focus on).
+* Add any other information that might be helpful for the reviewer (e.g., performance implications, potential risks,
+  specific areas to focus on).
+* Memory / flash impact, if known.
+
+---
+
+### AI Usage
+
+While CrossPoint doesn't have restrictions on AI tools in contributing, please be transparent about their usage as it
+helps set the right context for reviewers.
+
+Did you use AI tools to help write this code? _**< YES | PARTIALLY | NO >**_

.github/skills/crosspoint-reader.md

@@ -0,0 +1 @@
+../../.skills/SKILL.md

.github/workflows/ci.yml

@@ -1,24 +1,25 @@
-name: CI
-'on':
+name: CI (build)
+
+on:
   push:
     branches: [master]
   pull_request:
 
-jobs:
-  build:
-    runs-on: ubuntu-latest
+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 PlatformIO Core
-        run: pip install --upgrade platformio
-
       - name: Install clang-format-21
         run: |
           wget https://apt.llvm.org/llvm.sh
@@ -27,11 +28,140 @@ jobs:
           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 uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          version: "latest"
+          enable-cache: false
+
+      - name: Install PlatformIO Core
+        run: uv pip install --system -U https://github.com/pioarduino/platformio-core/archive/refs/tags/v6.1.19.zip
+
+      - name: Cache PlatformIO packages
+        uses: actions/cache@v4
+        with:
+          path: ~/.platformio
+          key: pio-${{ runner.os }}-${{ hashFiles('platformio.ini') }}
+          restore-keys: pio-${{ runner.os }}-
+
       - 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)
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          submodules: recursive
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: '3.14'
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          version: "latest"
+          enable-cache: false
+
+      - name: Install PlatformIO Core
+        run: uv pip install --system -U https://github.com/pioarduino/platformio-core/archive/refs/tags/v6.1.19.zip
+
+      - name: Cache PlatformIO packages
+        uses: actions/cache@v4
+        with:
+          path: ~/.platformio
+          key: pio-${{ runner.os }}-${{ hashFiles('platformio.ini') }}
+          restore-keys: pio-${{ runner.os }}-
 
       - name: Build CrossPoint
-        run: pio run
+        # Both envs in ONE pio invocation: a second `pio run` can wipe the whole
+        # .pio/build tree (project-checksum mismatch after the S3 toolchain
+        # installs into the restored cache), deleting the default firmware.bin
+        # before the artifact upload.
+        run: |
+          set -euo pipefail
+          pio run -e default -e sticky | 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
+
+  unit-tests:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          submodules: recursive
+
+      - name: Install build tools
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y cmake ninja-build
+
+      - name: Cache googletest source
+        uses: actions/cache@v4
+        with:
+          path: build/test/_deps/googletest-src
+          key: ${{ runner.os }}-googletest-${{ hashFiles('test/CMakeLists.txt') }}
+
+      - name: Configure
+        run: cmake -S test -B build/test -G Ninja -DCMAKE_BUILD_TYPE=Release
+
+      - name: Build
+        run: cmake --build build/test
+
+      - name: Run tests
+        run: ctest --test-dir build/test --output-on-failure -j
+
+  # 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
+      - unit-tests
+    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

@@ -0,0 +1,27 @@
+name: "PR Formatting"
+
+on:
+  pull_request:
+  pull_request_target:
+    types:
+      - opened
+      - reopened
+      - edited
+
+permissions:
+  statuses: write
+
+jobs:
+  title-check:
+    name: Title Check
+    runs-on: ubuntu-latest
+    steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@ec9f2d5744a09debf3a187a3f4f675c53b671911 # v2.13.0
+        with:
+          egress-policy: audit
+
+      - name: Check PR Title
+        uses: amannn/action-semantic-pull-request@v6
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/release-fonts.yml

@@ -0,0 +1,106 @@
+name: Build & Publish SD Card Fonts
+
+# Fonts change rarely — run manually when font sources or the conversion
+# pipeline are updated.  Publishes .cpfont files + fonts.json manifest as
+# GitHub Release assets on the crosspoint-fonts repo so font releases don't
+# clutter the firmware releases page.
+#
+# Requires a repository secret FONTS_REPO_TOKEN — a fine-grained PAT (or
+# classic PAT) with contents:write permission on the target fonts repo.
+on:
+  workflow_dispatch:
+
+env:
+  FONTS_REPO: crosspoint-reader/crosspoint-fonts
+
+jobs:
+  build-fonts:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          submodules: recursive
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: '3.14'
+
+      - name: Install font tools
+        run: pip install freetype-py fonttools pyyaml
+
+      - name: Install system dependencies
+        run: sudo apt-get update && sudo apt-get install -y libfreetype6-dev
+
+      - name: Read version constants
+        id: versions
+        run: |
+          cd lib/EpdFont/scripts
+          echo "binary=$(python3 -c 'from cpfont_version import CPFONT_VERSION; print(CPFONT_VERSION)')" >> "$GITHUB_OUTPUT"
+          echo "metadata=$(python3 -c 'from cpfont_version import FONTS_MANIFEST_VERSION; print(FONTS_MANIFEST_VERSION)')" >> "$GITHUB_OUTPUT"
+
+      - name: Build SD card fonts
+        run: python3 lib/EpdFont/scripts/build-sd-fonts.py --clean --verbose -j 1
+
+      - name: Flatten output for release assets
+        run: |
+          mkdir -p dist
+          find lib/EpdFont/scripts/output -name '*.cpfont' -exec cp {} dist/ \;
+
+      - name: Compute release tags
+        id: tags
+        env:
+          GH_TOKEN: ${{ secrets.FONTS_REPO_TOKEN }}
+        run: |
+          BASE="sd-fonts-m${{ steps.versions.outputs.metadata }}-b${{ steps.versions.outputs.binary }}"
+          echo "base=$BASE" >> "$GITHUB_OUTPUT"
+
+          # Find the highest existing revision for this m/b pair
+          LAST=$(gh release list --repo "${{ env.FONTS_REPO }}" \
+            --json tagName --jq \
+            '[.[] | select(.tagName | startswith("'"${BASE}-r"'")) | .tagName | split("-r")[1] | tonumber] | max // 0')
+          NEXT=$((LAST + 1))
+          echo "revision=$NEXT" >> "$GITHUB_OUTPUT"
+          echo "versioned=${BASE}-r${NEXT}" >> "$GITHUB_OUTPUT"
+
+      - name: Generate manifest
+        run: |
+          python3 scripts/generate-font-manifest.py \
+            --input dist \
+            --base-url "https://github.com/${{ env.FONTS_REPO }}/releases/download/${{ steps.tags.outputs.base }}/" \
+            --output dist/fonts.json \
+            --descriptions-from lib/EpdFont/scripts/sd-fonts.yaml
+
+      - name: Publish versioned release to fonts repo
+        env:
+          GH_TOKEN: ${{ secrets.FONTS_REPO_TOKEN }}
+        run: |
+          VERSIONED="${{ steps.tags.outputs.versioned }}"
+          TITLE="SD Card Fonts (${VERSIONED#sd-fonts-})"
+
+          gh release create "$VERSIONED" dist/* \
+            --repo "${{ env.FONTS_REPO }}" \
+            --title "$TITLE" \
+            --notes "Pre-built \`.cpfont\` font files for CrossPoint Reader.
+
+          Download individual files or use **Settings > System > Manage Fonts** on the device.
+
+          See [SD Card Fonts documentation](https://github.com/${{ github.repository }}/blob/main/docs/sd-card-fonts.md) for details."
+
+      - name: Update stable tag for device downloads
+        env:
+          GH_TOKEN: ${{ secrets.FONTS_REPO_TOKEN }}
+        run: |
+          BASE="${{ steps.tags.outputs.base }}"
+
+          # Delete the old stable release for this m/b pair (the versioned releases are kept)
+          gh release delete "$BASE" --repo "${{ env.FONTS_REPO }}" --yes 2>/dev/null || true
+
+          gh release create "$BASE" dist/* \
+            --repo "${{ env.FONTS_REPO }}" \
+            --title "SD Card Fonts (${BASE#sd-fonts-})" \
+            --notes "Current font build for manifest v${{ steps.versions.outputs.metadata }}, binary format v${{ steps.versions.outputs.binary }}. Devices with this firmware version download from this release.
+
+          This is revision **${{ steps.tags.outputs.revision }}** — see [\`${{ steps.tags.outputs.versioned }}\`](https://github.com/${{ env.FONTS_REPO }}/releases/tag/${{ steps.tags.outputs.versioned }}) for the immutable copy.
+
+          Download individual files or use **Settings > System > Manage fonts** on the device."

.github/workflows/release.yml

@@ -7,23 +7,30 @@ on:
 jobs:
   build-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 uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          version: "latest"
+          enable-cache: false
+
       - name: Install PlatformIO Core
-        run: pip install --upgrade platformio
+        run: uv pip install --system -U https://github.com/pioarduino/platformio-core/archive/refs/tags/v6.1.19.zip
+
+      - name: Cache PlatformIO packages
+        uses: actions/cache@v4
+        with:
+          path: ~/.platformio
+          key: pio-${{ runner.os }}-${{ hashFiles('platformio.ini') }}
+          restore-keys: pio-${{ runner.os }}-
 
       - name: Build CrossPoint
         run: pio run -e gh_release

.github/workflows/release_candidate.yml

@@ -0,0 +1,54 @@
+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/setup-python@v6
+        with:
+          python-version: '3.14'
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          version: "latest"
+          enable-cache: false
+
+      - name: Install PlatformIO Core
+        run: uv pip install --system -U https://github.com/pioarduino/platformio-core/archive/refs/tags/v6.1.19.zip
+
+      - name: Cache PlatformIO packages
+        uses: actions/cache@v4
+        with:
+          path: ~/.platformio
+          key: pio-${{ runner.os }}-${{ hashFiles('platformio.ini') }}
+          restore-keys: pio-${{ runner.os }}-
+
+      - 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

@@ -2,5 +2,26 @@
 .idea
 .DS_Store
 .vscode
+open-x4-sdk
+fs_
 lib/EpdFont/fontsrc
+lib/I18n/I18nKeys.h
+lib/I18n/I18nStrings.h
+lib/I18n/I18nStrings.cpp
 *.generated.h
+.vs
+build
+**/__pycache__/
+/compile_commands.json
+/.cache
+.history/
+/.venv
+*.local*
+*.cpfont
+lib/EpdFont/scripts/downloaded_fonts/
+lib/EpdFont/scripts/instanced_fonts/
+lib/EpdFont/scripts/output/
+# Claude Code: share project skills with the team, keep local agent state
+# (worktrees, scheduled-task locks, settings.local, scout CLEANUP.md) out.
+.claude/*
+!.claude/skills/

.gitmodules

@@ -1,3 +1,4 @@
-[submodule "open-x4-sdk"]
-	path = open-x4-sdk
-	url = https://github.com/open-x4-epaper/community-sdk.git
+[submodule "freeink-sdk"]
+	path = freeink-sdk
+	url = https://github.com/Free-Ink/freeink-sdk.git
+	branch = main

.skills/SKILL.md

@@ -0,0 +1,921 @@
+# CrossPoint Reader Development Guide
+
+Project: Open-source e-reader firmware for Xteink X4 (ESP32-C3)
+Mission: Provide a lightweight, high-performance reading experience focused on EPUB rendering on constrained hardware.
+
+## AI Agent Identity and Cognitive Rules
+* Role: Senior Embedded Systems Engineer (ESP-IDF/Arduino-ESP32 specialized).
+* Primary Constraint: 380KB RAM is the hard ceiling. Stability is non-negotiable.
+* Evidence-Based Reasoning: Before proposing a change, you MUST cite the specific file path and line numbers that justify the modification.
+* Anti-Hallucination: Do not assume the existence of libraries or ESP-IDF functions. If you are unsure of an API's availability for the ESP32-C3 RISC-V target, check the freeink-sdk source or the FreeInk SDK docs (https://freeink.org/llms.txt for an LLM-readable index) first.
+* No Unfounded Claims: Do not claim performance gains or memory savings without explaining the technical mechanism (e.g., DRAM vs IRAM usage).
+* Resource Justification: You must justify any new heap allocation (new, malloc, std::vector) or explain why a stack/static alternative was rejected.
+* Verification: After suggesting a fix, instruct the user on how to verify it (e.g., monitoring heap via Serial or checking a specific cache file).
+---
+
+## Development Environment Awareness
+
+**CRITICAL**: Detect the host platform at session start to choose appropriate tools and commands.
+
+### Platform Detection
+```bash
+# Detect platform (run once per session)
+uname -s
+# Returns: MINGW64_NT-* (Windows Git Bash), Linux, Darwin (macOS)
+```
+
+**Detection Required**: Run `uname -s` at session start to determine platform
+
+### Platform-Specific Behaviors
+- **Windows (Git Bash)**: Unix commands, `C:\` paths in Windows but `/` in bash, limited glob (use `find`+`xargs`)
+- **Linux/WSL**: Full bash, Unix paths, native glob support
+
+**Cross-Platform Code Formatting**:
+```bash
+find src -name "*.cpp" -o -name "*.h" | xargs clang-format -i
+```
+
+---
+
+## Platform and Hardware Constraints
+
+### Hardware Specs
+* MCU: ESP32-C3 (Single-core RISC-V @ 160MHz)
+* RAM: ~380KB usable (VERY LIMITED - primary project constraint)
+  * **NO PSRAM**: ESP32-C3 has no PSRAM capability (unlike ESP32-S3)
+  * **Single Buffer Mode**: Only ONE 48KB framebuffer (not double-buffered)
+* Flash: 16MB (Instruction storage and static data)
+* Display: 800x480 E-Ink (Slow refresh, monochrome, 1-2s full update)
+  * Framebuffer: 48,000 bytes (800 × 480 ÷ 8)
+* Storage: SD Card (Used for books and aggressive caching)
+
+### The Resource Protocol
+1. Stack Safety: Limit local function variables to < 256 bytes. The ESP32-C3 default stack is small; use std::unique_ptr or static pools for larger buffers.
+2. Heap Fragmentation: Avoid repeated new/delete in loops. Allocate buffers once during onEnter() and reuse them.
+3. Flash Persistence: Large constant data (UI strings, lookup tables) MUST be marked static const to stay in Flash (Instruction Bus), freeing DRAM.
+4. String Policy: Prohibit std::string and Arduino String in hot paths. Use std::string_view for read-only access and snprintf with fixed char[] buffers for construction.
+5. UI Strings: All user-facing text must use the `tr()` macro (e.g., `tr(STR_LOADING)`) for i18n support. Never hardcode UI strings directly. For the avoidance of doubt, logging messages (LOG_DBG/LOG_ERR) can be hardcoded, but user-facing text must use `tr()`.
+6. `constexpr` First: Compile-time constants and lookup tables must be `constexpr`, not just `static const`. This moves computation to compile time, enables dead-branch elimination, and guarantees flash placement. Use `static constexpr` for class-level constants.
+7. `std::vector` Pre-allocation: Always call `.reserve(N)` before any `push_back()` loop. Each growth event allocates a new block (2×), copies all elements, then frees the old one — three heap operations that fragment DRAM. When the final size is unknown, estimate conservatively.
+8. SPIFFS Write Throttling: Never write a settings file on every user interaction. Guard all writes with a value-change check (`if (newVal == _current) return;`). Progress saves during reading must be debounced — write on activity exit or every N page turns, not on every turn. SPIFFS sectors have a finite erase cycle limit.
+9. `new` is not nothrow on ESP32: With `-fno-exceptions`, bare `new` that fails calls `abort()` — it does NOT return `nullptr`. Always use `new (std::nothrow)` and null-check the result, or use `makeUniqueNoThrow<T>()` from `lib/Memory/Memory.h`. Never write bare `new` for any fallible allocation.
+
+---
+
+## Project Architecture
+
+### Build System: PlatformIO
+
+**PlatformIO is BOTH a VS Code extension AND a CLI tool**:
+
+1. **VS Code Extension** (Recommended):
+   * Extension ID: `platformio.platformio-ide` (see `.vscode/extensions.json`)
+   * Provides: Toolbar buttons, IntelliSense, integrated build/upload/monitor
+   * Configuration: `.vscode/c_cpp_properties.json`, `.vscode/tasks.json`
+   * Usage: Click Build (✓), Upload (→), or Monitor (🔌) buttons
+
+2. **CLI Tool** (`pio` command):
+   * **Installation**: Python package (typically `pip install platformio`)
+   * **Windows Location**: `C:\Users\<user>\AppData\Local\Programs\Python\Python3xx\Scripts\pio.exe`
+   * **Verify**: `which pio` (Git Bash) or `where.exe pio` (cmd)
+   * **Usage**: `pio run`, `pio run -t upload`, etc.
+
+**Configuration Files**:
+* `platformio.ini`: Main build configuration (committed to git)
+* `platformio.local.ini`: Local overrides (gitignored, create if needed)
+* `partitions.csv`: ESP32 flash partition layout
+
+### Build Environment
+* **Standard**: C++20 (`-std=c++2a`). No Exceptions, No RTTI.
+* **Logging**: ALWAYS use `LOG_INF`, `LOG_DBG`, or `LOG_ERR` from `Logging.h`. Raw Serial output is deprecated.
+* **Environments** (in `platformio.ini`):
+  * `default`: Development (LOG_LEVEL=2, serial enabled)
+  * `gh_release`: Production (LOG_LEVEL=0)
+  * `gh_release_rc`: Release candidate (LOG_LEVEL=1)
+  * `slim`: Minimal build (no serial logging)
+
+### Critical Build Flags
+These flags in `platformio.ini` fundamentally affect firmware behavior:
+
+```cpp
+-DEINK_DISPLAY_SINGLE_BUFFER_MODE=1  // Single framebuffer (saves 48KB RAM!)
+-DARDUINO_USB_MODE=1                 // Enable USB CDC
+-DARDUINO_USB_CDC_ON_BOOT=1          // Serial available immediately at boot
+-DXML_CONTEXT_BYTES=1024             // XML parser memory limit (EPUB parsing)
+-DUSE_UTF8_LONG_NAMES=1              // SD card long filename support
+-DMINIZ_NO_ZLIB_COMPATIBLE_NAMES=1   // Avoid zlib name conflicts
+-DXML_GE=0                           // Disable XML general entities (security)
+-DDESTRUCTOR_CLOSES_FILE=1           // FsFile destructor auto-closes (SdFat)
+```
+
+**DESTRUCTOR_CLOSES_FILE implications**:
+- SdFat's `FsBaseFile` destructor calls `close()` automatically when the object goes out of scope
+- **Do NOT add explicit `file.close()` calls** for local `FsFile` variables — the destructor handles it
+- Explicit `close()` is still required in these cases:
+  1. **Close before delete**: Must close before `Storage.remove()` on the same path
+  2. **Close before reopen**: Must close before reopening the same `FsFile` variable (e.g., write then reopen for read, or rewrite the same path)
+  3. **Member variables**: `FsFile` members persist beyond any single function scope, so close at the intended release point (e.g., in `onExit()`)
+
+**SINGLE_BUFFER_MODE implications**:
+- Only ONE framebuffer exists (not double-buffered)
+- Grayscale rendering requires temporary buffer allocation (`renderer.storeBwBuffer()`)
+- Must call `renderer.restoreBwBuffer()` to free temporary buffers
+- See [lib/GfxRenderer/GfxRenderer.cpp:439-440](../lib/GfxRenderer/GfxRenderer.cpp) for malloc usage
+
+### Directory Structure
+* lib/: Internal libraries (Epub engine, GfxRenderer, UITheme, I18n)
+  * lib/hal/: Hardware Abstraction Layer (HalDisplay, HalGPIO, HalStorage)
+  * lib/I18n/: Internationalization (translations in `translations/*.yaml`, generated string tables)
+* src/activities/: UI logic using the Activity Lifecycle (onEnter, loop, onExit)
+* freeink-sdk/: Low-level SDK (EInkDisplay, InputManager, BatteryMonitor, SDCardManager)
+* .crosspoint/: SD-based binary cache for EPUB metadata and pre-rendered layout sections
+
+### Hardware Abstraction Layer (HAL)
+
+**CRITICAL**: Always use HAL classes, NOT SDK classes directly.
+
+| HAL Class | Wraps SDK Class | Purpose | Singleton Macro |
+|-----------|----------------|---------|-----------------|
+| `HalDisplay` | `EInkDisplay` | E-ink display control | *(none)* |
+| `HalGPIO` | `InputManager` | Button input handling | *(none)* |
+| `HalStorage` | `SDCardManager` | SD card file I/O | `Storage` |
+
+**Location**: [lib/hal/](../lib/hal/)
+
+**Why HAL?**
+- Provides consistent error logging per module
+- Abstracts SDK implementation details
+- Centralizes resource management
+
+**Example - HalStorage**:
+```cpp
+#include <HalStorage.h>
+
+// Use Storage singleton (defined via macro)
+HalFile file;
+if (Storage.openFileForRead("MODULE", "/path/to/file.bin", file)) {
+  // Read from file
+  // No file.close() needed — DESTRUCTOR_CLOSES_FILE=1 handles it at scope exit
+}
+```
+
+**Usage**: Use `HalFile` (the mutex-wrapping handle), NOT raw SdFat `FsFile` or Arduino `File`. Do NOT add `file.close()` for local variables (see DESTRUCTOR_CLOSES_FILE above).
+
+**SdFat is not thread-safe; all SD access MUST go through HalStorage**:
+- SdFat's `SdSpiCard` tracks SPI bus state with an unsynchronized `m_spiActive` bool. Two tasks calling SdFat concurrently can confuse that state machine and end with one task calling `SPIClass::endTransaction()` against a paramLock the *other* task is holding. That trips FreeRTOS's `xTaskPriorityDisinherit` assert (`tasks.c:5156, pxTCB == pxCurrentTCBs[0]`) and panics the system. See SdFat issue #518.
+- `HalStorage` serializes everything via `storageMutex`. Downstream code uses `HalFile` (declared in `<HalStorage.h>`); every method call (read, write, seek, close) takes the mutex. `HalFile`'s destructor also takes the mutex before letting the underlying SdFat `FsFile` close.
+- **Never** call into `SdFat` / `SdSpiCard` / `FsBaseFile` / `SDCardManager` / raw `FsFile` directly — that bypasses the mutex.
+
+---
+
+## Coding Standards
+
+### Naming Conventions
+* Classes: PascalCase (e.g., EpubReaderActivity)
+* Methods/Variables: camelCase (e.g., renderPage())
+* Constants: UPPER_SNAKE_CASE (e.g., MAX_BUFFER_SIZE)
+* Private Members: memberVariable (no prefix)
+* File Names: Match Class names (e.g., EpubReaderActivity.cpp)
+
+### Header Guards
+* Use #pragma once for all header files.
+
+### Memory Safety and RAII
+* Smart Pointers: Prefer std::unique_ptr. Avoid std::shared_ptr (unnecessary atomic overhead for a single-core RISC-V).
+* RAII: Use destructors for cleanup. Call `vTaskDelete()` explicitly for deterministic task release. Do NOT call `file.close()` on local `FsFile` variables — `DESTRUCTOR_CLOSES_FILE=1` handles it at scope exit (see Critical Build Flags).
+
+### ESP32-C3 Platform Pitfalls
+
+#### `std::string_view` and Null Termination
+`string_view` is *not* null-terminated. Passing `.data()` to any C-style API (`drawText`, `snprintf`, `strcmp`, SdFat file paths) is undefined behaviour when the view is a substring or a view of a non-null-terminated buffer.
+
+**Rule**: `string_view` is safe only when passing to C++ APIs that accept `string_view`. For any C API boundary, convert explicitly:
+```cpp
+// WRONG - undefined behaviour if view is a substring:
+renderer.drawText(font, x, y, myView.data(), true);
+
+// CORRECT - guaranteed null-terminated:
+renderer.drawText(font, x, y, std::string(myView).c_str(), true);
+
+// CORRECT - for short strings, use a stack buffer:
+char buf[64];
+snprintf(buf, sizeof(buf), "%.*s", (int)myView.size(), myView.data());
+```
+
+#### `IRAM_ATTR` and Flash Cache Safety
+All code runs from flash via the instruction cache. During SPI flash operations (OTA write, SPIFFS commit, NVS update) the cache is briefly suspended. Any code that can execute during this window — ISRs in particular — must reside in IRAM or it will crash silently.
+
+```cpp
+// ISR handler: must be in IRAM
+void IRAM_ATTR gpioISR() { ... }
+
+// Data accessed from IRAM_ATTR code: must be in DRAM, never a flash const
+static DRAM_ATTR uint32_t isrEventFlags = 0;
+```
+
+**Rules**:
+- All ISR handlers: `IRAM_ATTR`
+- Data read by `IRAM_ATTR` code: `DRAM_ATTR` (a flash-resident `static const` will fault)
+- Normal task code does **not** need `IRAM_ATTR`
+
+#### ISR vs Task Shared State
+`xSemaphoreTake()` (mutex) **cannot** be called from ISR context — it will crash. Use the correct primitive for each communication direction:
+
+| Direction | Correct primitive |
+|---|---|
+| ISR → task (data) | `xQueueSendFromISR()` + `portYIELD_FROM_ISR()` |
+| ISR → task (signal) | `xSemaphoreGiveFromISR()` + `portYIELD_FROM_ISR()` |
+| Task → task | `xSemaphoreTake()` / mutex |
+| Simple flag (single writer ISR) | `volatile bool` + `portENTER_CRITICAL_ISR()` |
+
+#### RISC-V Alignment
+ESP32-C3 faults on unaligned multi-byte loads. Never cast a `uint8_t*` buffer to a wider pointer type and dereference it directly. Use `memcpy` for any unaligned read:
+
+```cpp
+// WRONG — faults if buf is not 4-byte aligned:
+uint32_t val = *reinterpret_cast<const uint32_t*>(buf);
+
+// CORRECT:
+uint32_t val;
+memcpy(&val, buf, sizeof(val));
+```
+
+This applies to all cache deserialization code and any raw buffer-to-struct casting. `__attribute__((packed))` structs have the same hazard when accessed via member reference.
+
+#### Template and `std::function` Bloat
+Each template instantiation generates a separate binary copy. `std::function<void()>` adds ~2–4 KB per unique signature and heap-allocates its closure. Avoid both in library code and any path called from the render loop:
+
+```cpp
+// Avoid — heap-allocating, large binary footprint:
+std::function<void()> callback;
+
+// Prefer — zero overhead:
+void (*callback)() = nullptr;
+
+// For member function + context (common activity callback pattern):
+struct Callback { void* ctx; void (*fn)(void*); };
+```
+
+When a template is necessary, limit instantiations: use explicit template instantiation in a `.cpp` file to prevent the compiler from generating duplicates across translation units.
+
+---
+
+### Error Handling Philosophy
+
+**Source**: [src/main.cpp:132-143](../src/main.cpp), [lib/GfxRenderer/GfxRenderer.cpp:10](../lib/GfxRenderer/GfxRenderer.cpp)
+
+**Pattern Hierarchy**:
+1. **LOG_ERR + return false** (90%): `LOG_ERR("MOD", "Failed: %s", reason); return false;`
+2. **LOG_ERR + fallback**: `LOG_ERR("MOD", "Unavailable"); useDefault();`
+3. **assert(false)**: Only for fatal "impossible" states (framebuffer missing)
+4. **ESP.restart()**: Only for recovery (OTA complete)
+
+**Rules**: NO exceptions, NO abort(), ALWAYS log before error return
+
+### Heap Buffer Allocation
+
+**Prefer `makeUniqueNoThrow` over `malloc`.** Both are nothrow (return `nullptr` on OOM rather than calling `abort()`), but `malloc` requires a manual `free` on every return path — a common source of leaks. `makeUniqueNoThrow<uint8_t[]>(size)` from `lib/Memory/Memory.h` frees automatically when it goes out of scope.
+
+**Preferred pattern**:
+```cpp
+#include <Memory.h>
+
+auto buffer = makeUniqueNoThrow<uint8_t[]>(bufferSize);
+if (!buffer) {
+  LOG_ERR("MODULE", "OOM: %d bytes", bufferSize);
+  return false;
+}
+
+processData(buffer.get(), bufferSize);
+// freed automatically — no manual free needed, no leak on early return
+```
+
+**`malloc` or `new (std::nothrow)` are still acceptable** when the buffer must be passed to a C API that takes ownership and frees it itself (e.g., certain SDK callbacks). In that case follow the manual pattern:
+```cpp
+auto* buffer = static_cast<uint8_t*>(malloc(bufferSize));  // or new (std::nothrow) uint8_t[bufferSize]
+if (!buffer) {
+  LOG_ERR("MODULE", "OOM: %d bytes", bufferSize);
+  return false;
+}
+sdkApiThatTakesOwnership(buffer, bufferSize);  // SDK calls free() / delete[]
+```
+
+**Rules**:
+- **Prefer `makeUniqueNoThrow`** — automatic cleanup eliminates leak risk on error paths
+- **ALWAYS check for nullptr** after any allocation and `LOG_ERR` before returning false
+- **Raw allocation only** when a C API takes ownership; document why in a comment
+
+**Examples in codebase**:
+- Memory utilities: [Memory.h](../lib/Memory/Memory.h) (`makeUniqueNoThrow`)
+- Cover image buffers: [HomeActivity.cpp:166](../src/activities/home/HomeActivity.cpp)
+- Bitmap rendering: [GfxRenderer.cpp:439-440](../lib/GfxRenderer/GfxRenderer.cpp)
+
+### Heap Allocation with `new`: Always Use `makeUniqueNoThrow`
+
+**CRITICAL**: With `-fno-exceptions`, bare `new` on OOM calls `abort()` — it does NOT return `nullptr`. Always use `makeUniqueNoThrow` from `lib/Memory/Memory.h`, which wraps `new (std::nothrow)` and returns a `std::unique_ptr` that is null on OOM and automatically frees on scope exit.
+
+**Preferred pattern**:
+```cpp
+#include <Memory.h>
+
+auto obj = makeUniqueNoThrow<MyClass>(args);
+if (!obj) { LOG_ERR("MOD", "OOM: MyClass"); return false; }
+
+auto buf = makeUniqueNoThrow<uint8_t[]>(size);
+if (!buf) { LOG_ERR("MOD", "OOM: %d bytes", size); return false; }
+
+// Pass to C APIs via .get(); unique_ptr frees automatically on return
+someApi(buf.get(), size);
+```
+
+**`new (std::nothrow)` directly is acceptable** when the object must be passed to a C API that takes ownership and calls `delete` itself:
+```cpp
+auto* obj = new (std::nothrow) MyClass(args);
+if (!obj) { LOG_ERR("MOD", "OOM: MyClass"); return false; }
+sdkApiThatTakesOwnership(obj);  // SDK calls delete
+```
+
+**Rules**:
+- **Prefer `makeUniqueNoThrow`** — automatic cleanup eliminates leak risk on error paths
+- **NEVER use bare `new`** — always `makeUniqueNoThrow` or `new (std::nothrow)`
+- **ALWAYS `LOG_ERR` before returning false** on OOM
+- **Use `.get()`** to pass the raw pointer to C-style APIs; ownership stays with the `unique_ptr`
+- **`new (std::nothrow)` directly only** when a C API takes ownership; document why in a comment
+
+**Examples in codebase**:
+- Memory utilities: [Memory.h](../lib/Memory/Memory.h) (`makeUniqueNoThrow`)
+
+---
+
+## UI and Orientation Guidelines
+
+### Orientation-Aware Logic
+* No Hardcoding: Never assume 800 or 480. Use renderer.getScreenWidth() and renderer.getScreenHeight().
+* Viewable Area: Use renderer.getOrientedViewableTRBL() to stay within physical bezel margins.
+
+### Logical Button Mapping
+
+**Source**: [src/MappedInputManager.cpp:20-55](../src/MappedInputManager.cpp)
+
+Constraint: Physical button positions are fixed on hardware, but their logical functions change based on user settings and screen orientation.
+
+**Button Categories**:
+1. **Physical Fixed** (Up/Down side buttons):
+   - `Button::Up` → Always `HalGPIO::BTN_UP`
+   - `Button::Down` → Always `HalGPIO::BTN_DOWN`
+
+2. **User Remappable** (Front buttons):
+   - `Button::Back` → Maps to `SETTINGS.frontButtonBack` (hardware index)
+   - `Button::Confirm` → Maps to `SETTINGS.frontButtonConfirm`
+   - `Button::Left` → Maps to `SETTINGS.frontButtonLeft`
+   - `Button::Right` → Maps to `SETTINGS.frontButtonRight`
+
+3. **Reader-Specific** (Page navigation with optional swap):
+   - `Button::PageBack` → Uses side button (swappable via `SETTINGS.sideButtonLayout`)
+   - `Button::PageForward` → Uses side button (swappable)
+
+**Implementation**:
+- Activities use **logical buttons** (e.g., `Button::Confirm`)
+- `MappedInputManager` translates to **physical hardware buttons**
+- User can remap front buttons in settings
+- Orientation changes handled separately by renderer coordinate transforms
+
+**Rule**: Always use `MappedInputManager::Button::*` enums, never raw `HalGPIO::BTN_*` indices (except in ButtonRemapActivity).
+
+### UITheme (The GUI Macro)
+* Rule: All UI rendering must go through the GUI macro (UITheme). 
+* Do not hardcode fonts, colors, or positioning. This ensures orientation-aware layout consistency.
+
+---
+
+## Common Patterns
+
+### Singleton Access
+**Available Singletons**:
+```cpp
+#define SETTINGS CrossPointSettings::getInstance()  // User settings
+#define APP_STATE CrossPointState::getInstance()    // Runtime state
+#define GUI UITheme::getInstance()                   // Current theme
+#define Storage HalStorage::getInstance()            // SD card I/O
+#define I18N I18n::getInstance()                     // Internationalization
+```
+
+### Activity Lifecycle and Memory Management
+
+**Source**: [src/main.cpp:132-143](../src/main.cpp)
+
+**CRITICAL**: Activities are **heap-allocated** and **deleted on exit**.
+
+```cpp
+// main.cpp navigation pattern
+void exitActivity() {
+  if (currentActivity) {
+    currentActivity->onExit();
+    delete currentActivity;  // Activity deleted here!
+    currentActivity = nullptr;
+  }
+}
+
+void enterNewActivity(Activity* activity) {
+  currentActivity = activity;  // Heap-allocated activity
+  currentActivity->onEnter();
+}
+```
+
+**Memory Implications**:
+- Activity navigation = `delete` old activity + `new` create next activity
+- Any memory allocated in `onEnter()` MUST be freed in `onExit()`
+- FreeRTOS tasks MUST be deleted in `onExit()` before activity destruction
+- Member `FsFile` handles MUST be closed in `onExit()` (local `FsFile` variables auto-close via destructor)
+
+**Activity Pattern**:
+```cpp
+void onEnter()  { Activity::onEnter(); /* alloc: buffer, tasks */ render(); }
+void loop()     { mappedInput.update(); /* handle input */ }
+void onExit()   { /* free: vTaskDelete, free buffer, close member FsFiles */ Activity::onExit(); }
+```
+
+**Critical**: Free resources in reverse order. Delete tasks BEFORE activity destruction.
+
+### FreeRTOS Task Guidelines
+
+**Source**: [src/activities/util/KeyboardEntryActivity.cpp:45-50](../src/activities/util/KeyboardEntryActivity.cpp)
+
+**Pattern**: See Activity Lifecycle above. `xTaskCreate(&taskTrampoline, "Name", stackSize, this, 1, &handle)`
+
+**Stack Sizing** (in BYTES, not words):
+- **2048**: Simple rendering (most activities)
+- **4096**: Network, EPUB parsing
+- Monitor: `uxTaskGetStackHighWaterMark()` if crashes
+
+**Rules**: Always `vTaskDelete()` in `onExit()` before destruction. Use mutex if shared state.
+
+### Global Font Loading
+
+**Source**: [src/main.cpp:40-115](../src/main.cpp)
+
+**All fonts are loaded as global static objects** at firmware startup:
+- Noto Serif: 12, 14, 16, 18pt (4 styles each: regular, bold, italic, bold-italic)
+- Noto Sans: 12, 14, 16, 18pt (4 styles each)
+- Ubuntu UI fonts: 10, 12pt (2 styles)
+
+**Total**: ~80+ global `EpdFont` and `EpdFontFamily` objects
+
+**Compilation Flag**:
+```cpp
+#ifndef OMIT_FONTS
+  // Most fonts loaded here
+#endif
+```
+
+**Implications**:
+- Fonts stored in **Flash** (marked as `static const` in `lib/EpdFont/builtinFonts/`)
+- Font rendering data cached in **DRAM** when first used
+- `OMIT_FONTS` can reduce binary size for minimal builds
+- Font IDs defined in [src/fontIds.h](../src/fontIds.h)
+
+**Usage**:
+```cpp
+#include "fontIds.h"
+
+renderer.insertFont(FONT_UI_MEDIUM, ui12FontFamily);
+renderer.drawText(FONT_UI_MEDIUM, x, y, "Hello", true);
+```
+
+---
+
+## Testing and Debugging
+
+### Build Commands
+
+**Via CLI**:
+```bash
+# Build firmware (default environment)
+pio run
+
+# Build and upload to device
+pio run -t upload
+
+# Build specific environment
+pio run -e gh_release
+
+# Clean build artifacts
+pio run -t clean
+
+# Upload filesystem data (if using SPIFFS/LittleFS)
+pio run -t uploadfs
+```
+
+**Via VS Code**:
+* Use PlatformIO toolbar: Build (✓), Upload (→), Clean (🗑️)
+* Or Command Palette: `PlatformIO: Build`, `PlatformIO: Upload`, etc.
+
+### Monitoring and Debugging
+
+```bash
+# Enhanced monitor with color/logging (recommended)
+python3 scripts/debugging_monitor.py
+
+# Standard PlatformIO monitor
+pio device monitor
+
+# Combined upload + monitor
+pio run -t upload && pio device monitor
+```
+
+**Via VS Code**: Click Monitor (🔌) button in PlatformIO toolbar
+
+### Code Quality
+
+```bash
+# Static analysis (cppcheck)
+pio check
+
+# Format code (clang-format) - Windows Git Bash
+find src -name "*.cpp" -o -name "*.h" | xargs clang-format -i
+
+# Format code (clang-format) - Linux
+clang-format -i src/**/*.cpp src/**/*.h
+```
+
+### Debugging Crashes
+
+**Common Crash Causes**:
+
+1. **Out of Memory** (Most common):
+   ```cpp
+   LOG_DBG("MEM", "Free heap: %d bytes", ESP.getFreeHeap());
+   ```
+   - Monitor heap usage throughout activity lifecycle
+   - Check if large allocations (>10KB) occur before crash
+   - Verify buffers are freed in `onExit()`
+
+2. **Stack Overflow**:
+   ```cpp
+   LOG_DBG("TASK", "Stack high water: %d", uxTaskGetStackHighWaterMark(taskHandle));
+   ```
+   - Occurs during deep recursion or large local variables
+   - Increase task stack size in `xTaskCreate()` (2048 → 4096)
+   - Move large buffers to heap with malloc
+
+3. **Use-After-Free**:
+   - Activity deleted but task still running
+   - Always `vTaskDelete()` in `onExit()` BEFORE activity destruction
+   - Set pointers to `nullptr` after `free()`
+
+4. **Corrupt Cache Files**:
+   - Delete `.crosspoint/` directory on SD card
+   - Forces clean re-parse of all EPUBs
+   - Check file format versions in [docs/file-formats.md](../docs/file-formats.md)
+
+5. **Watchdog Timeout**:
+   - Loop/task blocked for >5 seconds
+   - Add `vTaskDelay(1)` in tight loops
+   - Check for blocking I/O operations
+
+**Verification Steps**:
+1. Check serial output for stack traces
+2. Monitor heap with `ESP.getFreeHeap()` before/after operations
+3. Verify task deletion with task list (`vTaskList()`)
+4. Test with `LOG_LEVEL=2` (debug logging enabled)
+
+---
+
+## Git Workflow and Repository Awareness
+
+### Repository Detection Protocol
+
+**CRITICAL**: ALWAYS verify repository context before git operations. This could be:
+- A **fork** with `origin` pointing to personal repo, `upstream` to main repo
+- A **direct clone** with `origin` pointing to main repo
+- Multiple collaborator remotes
+
+**Verification Commands** (run at session start):
+```bash
+# Check current branch
+git branch --show-current
+
+# Check all remotes
+git remote -v
+
+# Identify main branch name (could be 'main' or 'master')
+git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@'
+
+# Check working tree status
+git status --short
+```
+
+**Example Output** (forked repository):
+```text
+origin      https://github.com/<your-username>/crosspoint-reader.git (fetch/push)
+upstream    https://github.com/crosspoint-reader/crosspoint-reader.git (fetch/push)
+```
+
+### Git Operation Rules
+
+1. **Never assume branch names**:
+   ```bash
+   # Bad: git push origin main
+   # Good: git push origin $(git branch --show-current)
+   ```
+
+2. **Never assume remote names or write permissions**:
+   - **Forked repos**: Push to `origin` (your fork), submit PR to `upstream`
+   - **Direct contributors**: May push feature branches to `upstream`
+   - **Always ask**: "Should I push to origin or create a PR?"
+
+3. **Check for upstream changes before starting work**:
+   ```bash
+   # Sync fork with upstream (if applicable)
+   git fetch upstream
+   git merge upstream/main  # or upstream/master
+   ```
+
+4. **Use explicit remote and branch names**:
+   ```bash
+   # Check remotes first
+   git remote -v
+
+   # Use explicit syntax
+   git push <remote> <branch>
+   ```
+
+### Branch Naming Convention
+
+**For feature/fix branches**:
+```text
+feature/<short-description>       # New features
+fix/<issue-number>-<description>  # Bug fixes
+refactor/<component-name>         # Code refactoring
+docs/<topic>                      # Documentation updates
+```
+
+**Examples**:
+- `feature/sd-download-progress`
+- `fix/123-orientation-crash`
+- `refactor/hal-storage`
+
+### Commit Message Format
+
+**Pattern**:
+```text
+<type>: <short summary (50 chars max)>
+
+<optional detailed description>
+
+```
+
+**Types**: `feat`, `fix`, `refactor`, `docs`, `test`, `chore`, `perf`
+
+**Example**:
+```text
+feat: add real-time SD download progress bar
+
+Implements progress tracking for book downloads using
+UITheme progress bar component with heap-safe updates.
+
+Tested in all 4 orientations with 5MB+ files.
+```
+
+### When to Commit
+
+**DO commit when**:
+- User explicitly requests: "commit these changes"
+- Feature is complete and tested on device
+- Bug fix is verified working
+- Refactoring preserves all functionality
+- All tests pass (`pio run` succeeds)
+
+**DO NOT commit when**:
+- Changes are untested on actual hardware
+- Build fails or has warnings
+- Experimenting or debugging in progress
+- User hasn't explicitly requested commit
+- Files excluded by `.gitignore` would be included — always run `git status` and cross-check against `.gitignore` before staging (e.g., `*.generated.h`, `.pio/`, `compile_commands.json`, `platformio.local.ini`)
+
+**Rule**: **If uncertain, ASK before committing.**
+
+---
+
+## Generated Files and Build Artifacts
+
+### Files Generated by Build Scripts
+
+**NEVER manually edit these files** - they are regenerated automatically:
+
+1. **HTML Headers** (generated by `scripts/build_html.py`):
+   - `src/network/html/*.generated.h`
+   - **Source**: HTML templates in `data/html/` directory
+   - **Triggered**: During PlatformIO `pre:` build step
+   - **To modify**: Edit source HTML in `data/html/`, not generated headers
+
+2. **I18n Headers** (generated by `scripts/gen_i18n.py`):
+   - `lib/I18n/I18nKeys.h`, `lib/I18n/I18nStrings.h`, `lib/I18n/I18nStrings.cpp`
+   - **Source**: YAML translation files in `lib/I18n/translations/` (one per language)
+   - **To modify**: Edit source YAML files, then run `python scripts/gen_i18n.py lib/I18n/translations lib/I18n/`
+   - **Commit**: Source YAML files only. All three generated files (`I18nKeys.h`, `I18nStrings.h`, `I18nStrings.cpp`) are in `.gitignore` and regenerated at build time.
+
+3. **Build Artifacts** (in `.gitignore`):
+   - `.pio/` - PlatformIO build output
+   - `build/` - Compiled binaries
+   - `*.generated.h` - Any auto-generated headers
+   - `compile_commands.json` - LSP/IDE metadata
+
+### Modifying Generated Content Workflow
+
+**To change HTML pages**:
+1. Edit source: `data/html/<pagename>.html`
+2. Build: `pio run` (auto-triggers `scripts/build_html.py`)
+3. Generated headers update: `src/network/html/<pagename>Html.generated.h`
+4. **Commit ONLY** source HTML, NOT generated `.generated.h` files
+
+**To add/modify translations (i18n)**:
+1. Edit or add YAML file: `lib/I18n/translations/<language>.yaml`
+   - Each file must contain: `_language_name`, `_language_code`, `_order`, and `STR_*` keys
+   - English (`english.yaml`) is the reference; missing keys in other languages fall back to English
+2. Run generator: `python scripts/gen_i18n.py lib/I18n/translations lib/I18n/`
+3. Generated files update: `I18nKeys.h`, `I18nStrings.h`, `I18nStrings.cpp`
+4. **Commit** source YAML files only. All three generated files are in `.gitignore` and regenerated at build time.
+
+**To use translated strings in code**:
+```cpp
+#include <I18n.h>
+// Use tr() macro with StrId enum (defined in generated I18nKeys.h)
+renderer.drawText(FONT_UI, x, y, tr(STR_LOADING), true);
+```
+
+**To add custom fonts**:
+1. Place source fonts in `lib/EpdFont/fontsrc/` (gitignored)
+2. Run conversion script (see `lib/EpdFont/README`)
+3. Update global font objects in `src/main.cpp:40-115`
+4. Add font ID constant to `src/fontIds.h`
+
+---
+
+## Local Development Configuration
+
+### platformio.local.ini (Personal Overrides)
+
+**Purpose**: Personal development settings that should NEVER be committed.
+
+**Use Cases**:
+- Serial port configuration (varies by machine)
+- Debug flags for specific testing
+- Local build optimizations
+- Developer-specific paths
+
+**Example** `platformio.local.ini`:
+```ini
+# platformio.local.ini (gitignored)
+[env:default]
+upload_port = COM7              # Windows: COMx, Linux: /dev/ttyUSBx
+monitor_port = COM7
+
+build_flags =
+  ${base.build_flags}
+  -DMY_DEBUG_FLAG=1             # Personal debug flags
+  -DTEST_FEATURE_ENABLED=1
+```
+
+**Configuration Hierarchy**:
+1. `platformio.ini` - **Committed**, shared project settings
+2. `platformio.local.ini` - **Gitignored**, personal overrides
+3. Local file extends/overrides base config
+
+**Rules**:
+- **NEVER commit** `platformio.local.ini`
+- **NEVER put** personal info (serial ports, credentials) in main `platformio.ini`
+- Use `${base.build_flags}` to extend (not replace) base flags
+
+---
+
+## Testing and Verification Workflow
+
+### Testing Checklist
+
+**AI agent scope** (what you CAN verify):
+1. ✅ **Build**: `pio run -t clean && pio run` (0 errors/warnings)
+2. ✅ **Quality**: `pio check` + `find src -name "*.cpp" -o -name "*.h" | xargs clang-format -i`
+3. ✅ **Format**: Commit messages (`feat:`/`fix:`), no `.gitignore`-excluded files staged (e.g., `*.generated.h`, `.pio/`, `platformio.local.ini`)
+4. ✅ **CI**: Fix GitHub Actions failures before review
+5. ✅ **Code review**: Ensure orientation-aware logic is correct in all 4 modes by inspecting switch/case coverage
+
+**Human tester scope** (flag these for the user):
+6. 🔲 **Device**: Test on hardware
+7. 🔲 **Orientations**: Verify all 4 modes (Portrait/Inverted/Landscape CW/CCW)
+8. 🔲 **Heap**: `ESP.getFreeHeap()` > 50KB, no leaks
+9. 🔲 **Cache**: If EPUB modified, delete `.crosspoint/` and verify re-parse
+
+### CI/CD Pipeline Awareness
+
+**GitHub Actions** run automatically on pull requests:
+
+| Workflow | File | Purpose |
+|----------|------|---------|
+| Build Check | `.github/workflows/ci.yml` | Verifies code compiles |
+| Format Check | `.github/workflows/pr-formatting-check.yml` | Validates clang-format |
+| Release Build | `.github/workflows/release.yml` | Production releases |
+| RC Build | `.github/workflows/release_candidate.yml` | Release candidates |
+
+**Rules**:
+- **Fix CI failures BEFORE** requesting review
+- CI runs on: Push to PR, PR updates
+- Format check fails → Run clang-format locally
+- Build check fails → Fix compile errors
+
+---
+
+## Serial Monitoring and Live Debugging
+
+### Serial Monitor Options
+
+1. **Enhanced**: `python3 scripts/debugging_monitor.py` (color-coded, recommended)
+2. **Standard**: `pio device monitor` (basic, no colors)
+3. **VS Code**: Monitor (🔌) button (IDE-integrated)
+
+### Live Debugging Patterns
+
+**Heap**: `LOG_DBG("MEM", "Free: %d", ESP.getFreeHeap());` (every 5s in loop)
+**Stack**: `uxTaskGetStackHighWaterMark(nullptr)` (< 512 bytes → increase stack)
+**Flush**: `logSerial.flush();` (force output before crash)
+
+**Port Detection**: Windows: `mode` | Linux: `ls /dev/ttyUSB* /dev/ttyACM*` or `dmesg | grep tty`
+
+---
+
+## Cache Management and Invalidation
+
+### Cache Structure on SD Card
+
+**Location**: `.crosspoint/` directory on SD card root
+
+**Structure**: `.crosspoint/epub_<hash>/{book.bin, progress.bin, cover.bmp, sections/*.bin}`
+
+**Hash**: `std::hash<std::string>{}(filepath)` → Moving/renaming file = new hash = lost progress
+
+### Cache Invalidation Rules
+
+**Cache is automatically invalidated when**:
+1. **File format version changes** (see `docs/file-formats.md`)
+   - `book.bin` version number incremented
+   - `section.bin` version number incremented
+2. **Render settings change**:
+   - Font family or size (`SETTINGS.fontFamily`, `SETTINGS.fontSize`)
+   - Line spacing (`SETTINGS.lineSpacing`)
+   - Paragraph spacing (`SETTINGS.extraParagraphSpacing`)
+   - Screen margins (`SETTINGS.screenMargin`)
+3. **Viewport dimensions change**:
+   - Screen orientation change
+   - Display resolution change
+4. **Book file modified**:
+   - Moved, renamed, or content changed (new hash)
+
+**Manual Cache Clear** (safe operations):
+```bash
+# Delete ALL caches (forces full regeneration)
+rm -rf /path/to/sd/.crosspoint/
+
+# Delete specific book cache
+rm -rf /path/to/sd/.crosspoint/epub_<hash>/
+
+# Keep progress, delete only rendered sections
+rm -rf /path/to/sd/.crosspoint/epub_<hash>/sections/
+```
+
+**When to Clear Cache**:
+- EPUB parsing errors after code changes to `lib/Epub/`
+- Corrupt rendering (missing text, wrong layout)
+- Testing cache generation logic
+- After modifying:
+  - `lib/Epub/Epub/Section.cpp`
+  - `lib/Epub/Epub/BookMetadataCache.cpp`
+  - Render settings in `CrossPointSettings`
+
+### Cache File Format Versioning
+
+**Source**: `lib/Epub/Epub/Section.cpp`, `lib/Epub/Epub/BookMetadataCache.cpp`
+
+**Current Versions** (as of docs/file-formats.md):
+- `book.bin`: **Version 7** (metadata structure)
+- `section.bin`: **Version 25** (layout structure)
+
+**Version Increment Rules**:
+1. **ALWAYS increment version** BEFORE changing binary structure
+2. Version mismatch → Cache auto-invalidated and regenerated
+3. Document format changes in `docs/file-formats.md`
+
+**Example** (incrementing section format version):
+```cpp
+// lib/Epub/Epub/Section.cpp
+static constexpr uint8_t SECTION_FILE_VERSION = 26;  // Was 25, now 26
+
+// Add new field to structure
+struct PageLine {
+  // ... existing fields ...
+  uint16_t newField;  // New field added
+};
+```
+
+---
+
+Philosophy: We are building a dedicated e-reader, not a Swiss Army knife. If a feature adds RAM pressure without significantly improving the reading experience, it is Out of Scope.

CLAUDE.md

@@ -0,0 +1 @@
+.skills/SKILL.md

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

@@ -1,147 +1,287 @@
 # CrossPoint Reader
 
-Firmware for the **Xteink X4** e-paper display reader (unaffiliated with Xteink).
-Built using **PlatformIO** and targeting the **ESP32-C3** microcontroller.
+[![Fund contributors](https://img.shields.io/badge/%F0%9F%91%91_Fund_contributors-royalty.dev-BB953A?style=for-the-badge&labelColor=1a1a1a)](https://app.royalty.dev/crosspoint-reader/crosspoint-reader)
 
-CrossPoint Reader is a purpose-built firmware designed to be a drop-in, fully open-source replacement for the official 
-Xteink firmware. It aims to match or improve upon the standard EPUB reading experience.
+CrossPoint is open-source e-reader firmware - community-built, fully hackable, free forever. It's maintained by a growing community of developers and readers who believe your device should do what you want - not what a manufacturer decided for you.
 
-![](./docs/images/cover.jpg)
+**Now running on:** ESP32C3-based Xteink [X4](https://www.xteink.com/products/xteink-x4) and [X3](https://www.xteink.com/products/xteink-x3).
 
-## Motivation
+![CrossPoint Reader running on Xteink device](./docs/images/cover.jpg)
 
-E-paper devices are fantastic for reading, but most commercially available readers are closed systems with limited 
-customisation. The **Xteink X4** is an affordable, e-paper device, however the official firmware remains closed.
-CrossPoint exists partly as a fun side-project and partly to open up the ecosystem and truely unlock the device's
-potential.
+> If you're planning to buy an Xteink device, consider purchasing an **X3/X4 Developer Edition** through https://crosspointreader.com. CrossPoint receives a small share of each sale, helping fund development costs.
 
-CrossPoint Reader aims to:
-* Provide a **fully open-source alternative** to the official firmware.
-* Offer a **document reader** capable of handling EPUB content on constrained hardware.
-* Support **customisable font, layout, and display** options.
-* Run purely on the **Xteink X4 hardware**.
+## What can CrossPoint do?
 
-This project is **not affiliated with Xteink**; it's built as a community project.
+- **Reader engine**: EPUB 2/3 rendering with embedded-style option, image handling, hyphenation, kerning, chapter navigation, footnotes, bookmarks, dictionary lookups ([StarDict](docs/dictionary.md)), go-to-percent, auto page turn, orientation control, focus reading, KOReader progress sync and more. 
 
-## Features & Usage
+- **Various formats**: native handling for `.epub`, `.xtc/.xtch`, `.txt`, and `.bmp`.
 
-- [x] EPUB parsing and rendering
-- [ ] Image support within EPUB
-- [x] Saved reading position
-- [x] File explorer with file picker
-  - [x] Basic EPUB picker from root directory
-  - [x] Support nested folders
-  - [ ] EPUB picker with cover art
-- [x] Custom sleep screen
-  - [ ] Cover sleep screen
-- [x] Wifi book upload
-- [ ] Wifi OTA updates
-- [ ] Configurable font, layout, and display options
-- [ ] Screen rotation
+- **Screenshots.**
 
-See [the user guide](./USER_GUIDE.md) for instructions on operating CrossPoint.
+- **Custom fonts**: install your favorite fonts on the SD card.
 
-## Installing
+- **Tilt page turn (X3 only)**.
 
-### Web (latest firmware)
+- **Library workflow**: folder browser, hidden-file toggle, long-press delete, recent books, SD-cache management.
 
-1. Connect your Xteink X4 to your computer via USB-C
-2. Go to https://xteink.dve.al/ and click "Flash CrossPoint firmware"
+- **Wireless workflows**:
   
-To revert back to the official firmware, you can flash the latest official firmware from https://xteink.dve.al/, or swap
-back to the other partition using the "Swap boot partition" button here https://xteink.dve.al/debug.
+  - File transfer web UI
+  - EPUB Optimizer
+  - Web settings UI/API (edit many device settings from browser)
+  - WebSocket fast uploads
+  - WebDAV handler
+  - AP mode (hotspot) and STA mode (join existing Wi-Fi), both with QR helpers
+  - Calibre wireless connect flow
+  - OPDS browser with saved servers (up to 8), search, pagination, and direct download
+  - OTA update checks and installs from GitHub releases
 
-### Web (specific firmware version)
+- **Customization**: multiple themes (Classic, Lyra, Lyra Extended, RoundedRaff), sleep screen modes, front/side button remapping, status bar controls, power-button behavior, refresh cadence, and more.
 
-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)
-3. Go to https://xteink.dve.al/ and flash the firmware file using the "OTA fast flash controls" section
+- **Localization**: 24 UI languages and counting. RTL support.
 
-To revert back to the official firmware, you can flash the latest official firmware from https://xteink.dve.al/, or swap
-back to the other partition using the "Swap boot partition" button here https://xteink.dve.al/debug.
+### Coming soon:
+
+- More themes.
+
+- Much more! stay tuned.
+
+---
+
+## USB-locked devices (Xteink Unlocker)
+
+Some Xteink units purchased from third-party stores (e.g. AliExpress) ship with USB flashing locked from the factory.
+If your device is locked, you will need to use the **Xteink Unlocker** tool available at
+https://crosspointreader.com/#unlock-tool before you can flash CrossPoint.
+
+**You do not need this tool if you bought your device directly from xteink.com.** Those units are not locked.
+
+**Not sure if your device is locked?** Power it on, connect the USB-C cable, and try flashing via the web flasher first (see
+[Install firmware](#install-firmware) below). If the browser's serial device picker does not show your device, try a different
+USB port or browser before assuming the device is locked. Only reach for the unlocker if the device still doesn't appear.
+
+> ### ⚠️ WARNING: READ THIS BEFORE USING THE UNLOCKER ⚠️
+> 
+> **The only officially supported firmwares in the unlock tool are CrossPoint and CrossInk.**
+> 
+> Flashing any other firmware on a USB-locked device may **permanently brick the device** or leave it **permanently
+> stuck on that firmware with no recovery path**. Once USB flashing is re-locked, your only way back is via OTA, and if
+> the firmware you flashed doesn't support OTA, **there is no way out**.
+
+## Install firmware
+
+### Web installer (recommended)
+
+1. Connect your device to your computer via USB-C and wake/unlock the device
+2. Go to https://crosspointreader.com/#flash-tools, select device (X3 or X4), and choose an official CrossPoint release.
+
+### Web installer (specific version)
+
+1. Connect your device to your computer via USB-C and wake/unlock the device
+2. Download a `firmware.bin` from [Releases](https://github.com/crosspoint-reader/crosspoint-reader/releases), local build, or continuous integration artifact.
+3. Go to https://crosspointreader.com/#flash-tools, select device (X3 or X4), click "Custom .bin" and upload a `firmware.bin`.
+
+### Revert to Official Firmware
+
+To revert to the official firmware, you can also flash the latest official firmware using https://crosspointreader.com/#flash-tools.
+
+### Command line
+
+1. Install [`esptool`](https://github.com/espressif/esptool):
+
+```bash
+pip install esptool
+```
+
+2. Download `firmware.bin` from the [releases page](https://github.com/crosspoint-reader/crosspoint-reader/releases).
+3. Connect your device via USB-C.
+4. Find the device port. On Linux, run `dmesg` after connecting. On macOS:
+
+```bash
+log stream --predicate 'subsystem == "com.apple.iokit"' --info
+```
+
+5. Flash:
+
+```bash
+esptool.py --chip esp32c3 --port /dev/ttyACM0 --baud 921600 write_flash 0x10000 /path/to/firmware.bin
+```
+
+Adjust `/dev/ttyACM0` to match your system.
 
 ### Manual
 
-See [Development](#development) below.
+See [Development quick start](#development-quick-start) below.
 
-## Development
+---
+
+## Custom SD-card fonts
+
+Convert your own TTF/OTF files into `.cpfont` files that load from the SD card. No firmware reflash is needed.
+
+1. Go to https://crosspointreader.com/fonts and open the "SD-card font builder" form.
+2. Upload up to four styles (regular, bold, italic, bold-italic), set the family name, point sizes, and Unicode range.
+3. Download the generated `.cpfont` files.
+4. Copy them to your SD card under `/fonts/YourFont/` (or `/.fonts/YourFont/` to hide the folder).
+5. Select the font on the device from the font settings.
+
+Conversion runs the firmware repo's `lib/EpdFont/scripts/fontconvert_sdcard.py` script unmodified, so output matches a local host build.
+
+---
+
+## Documentation
+
+- [User Guide](./USER_GUIDE.md)
+- [Web server usage](./docs/webserver.md)
+- [Web server endpoints](./docs/webserver-endpoints.md)
+- [Project scope](./SCOPE.md)
+- [Contributing docs](./docs/contributing/README.md)
+- [Touch and UI development](./docs/contributing/touch-and-ui.md) - FreeInkUI components for new screens, the touch bridge for existing ones, and build envs for the non-Xteink touch devices
+
+---
+
+## Development quick start
 
 ### Prerequisites
 
-* **PlatformIO Core** (`pio`) or **VS Code + PlatformIO IDE**
-* Python 3.8+
-* USB-C cable for flashing the ESP32-C3
-* Xteink X4
+- [pioarduino](https://github.com/pioarduino/pioarduino) or VS Code + pioarduino plugin
+- Python 3.8+
+- `clang-format` 21
+- USB-C cable supporting data transfer
 
-### Checking out the code
+### Setup
 
-CrossPoint uses PlatformIO for building and flashing the firmware. To get started, clone the repository:
+```bash
+git clone --recursive https://github.com/crosspoint-reader/crosspoint-reader
+cd crosspoint-reader
 
-```
-git clone --recursive https://github.com/daveallie/crosspoint-reader
-
-# Or, if you've already cloned without --recursive:
+# if cloned without --recursive:
 git submodule update --init --recursive
 ```
 
-### Flashing your device
+### Nix/NixOS
 
-Connect your Xteink X4 to your computer via USB-C and run the following command.
+Nix/NixOS users can enter the development shell with either `nix develop` (flakes) or `nix-shell`:
 
-```sh
+```bash
+nix develop -f nix
+# or
+nix-shell nix
+```
+
+To flash a connected ESP32-C3 device, enable PlatformIO's udev rules in your NixOS configuration:
+
+```nix
+services.udev.packages = with pkgs; [ platformio-core.udev ];
+```
+
+After rebuilding the system configuration, reconnect the device or reload udev rules.
+
+### Build / flash / monitor
+
+```bash
 pio run --target upload
 ```
 
+### Contributor pre-PR checks
+
+```bash
+./bin/clang-format-fix
+pio check -e default
+pio run -e default
+```
+
+### 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
 
-CrossPoint Reader is pretty aggressive about caching data down to the SD card to minimise RAM usage. The ESP32-C3 only
-has ~380KB of usable RAM, so we have to be careful. A lot of the decisions made in the design of the firmware were based
-on this constraint.
+CrossPoint Reader is pretty aggressive about caching data down to the SD card to minimise RAM usage. The ESP32-C3 only has ~380KB of usable RAM, so we have to be careful. A lot of the decisions made in the design of the firmware were based on this constraint.
 
 ### Data caching
 
 The first time chapters of a book are loaded, they are cached to the SD card. Subsequent loads are served from the
 cache. This cache directory exists at `.crosspoint` on the SD card. The structure is as follows:
 
-
-```
+```text
 .crosspoint/
-├── epub_12471232/       # Each EPUB is cached to a subdirectory named `epub_<hash>`
-│   ├── progress.bin     # Stores reading progress (chapter, page, etc.)
-│   ├── cover.bmp        # Book cover image (once generated)
-│   ├── book.bin         # Book metadata (title, author, spine, table of contents, etc.)
-│   └── sections/        # All chapter data is stored in the sections subdirectory
-│       ├── 0.bin        # Chapter data (screen count, all text layout info, etc.)
-│       ├── 1.bin        #     files are named by their index in the spine
+├── epub_<hash>/         # one directory per book, named by content hash
+│   ├── progress.bin     # reading position (chapter, page, etc.)
+│   ├── cover.bmp        # generated cover image
+│   ├── book.bin         # metadata: title, author, spine, TOC
+│   ├── css_rules.cache  # parsed CSS rule cache
+│   ├── img_*            # rendered image cache files
+│   └── sections/        # per-chapter layout cache
+│       ├── 0.bin
+│       ├── 1.bin
 │       └── ...
-│
-└── epub_189013891/
+├── settings.json        # device settings
+├── state.json           # resume/runtime state
+└── recent.json          # recent books list
 ```
 
-Deleting the `.crosspoint` directory will clear the entire cache. 
-
-Due the way it's currently implemented, the cache is not automatically cleared when a book is deleted and moving a book
-file will use a new cache directory, resetting the reading progress.
+Removing `/.crosspoint` clears all cached metadata and forces a full regeneration on next open. Book deletes, overwrites, and moves done through the firmware or web UI clear or re-key matching caches; manual SD-card edits may leave stale cache directories behind.
 
 For more details on the internal file structures, see the [file formats document](./docs/file-formats.md).
 
+---
+
 ## Contributing
 
-Contributions are very welcome!
+Contributions are welcome. If you're new to the codebase, start with the [contributing docs](./docs/contributing/README.md). For things to work on, check the [ideas discussion board](https://github.com/crosspoint-reader/crosspoint-reader/discussions/categories/ideas) — leave a comment before starting so we don't duplicate effort.
 
-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 there's something there you'd like to work on, leave a comment so that we can avoid duplicated effort.
-
-### To submit a contribution:
-
-1. Fork the repo
-2. Create a branch (`feature/dithering-improvement`)
-3. Make changes
-4. Submit a PR
+Everyone here is a volunteer, so please be respectful and patient. For governance and community expectations, see [GOVERNANCE.md](./GOVERNANCE.md).
 
 ---
 
-CrossPoint Reader is **not affiliated with Xteink or any manufacturer of the X4 hardware**.
+## Community forks
 
-Huge shoutout to [**diy-esp32-epub-reader** by atomic14](https://github.com/atomic14/diy-esp32-epub-reader), which was a project I took a lot of inspiration from as I
-was making CrossPoint.
+One of the best things about open source is that anyone can take the code in a different direction. If you need something outside CrossPoint's [scope](./SCOPE.md), check out the community forks:
+
+- [CrossInk](https://github.com/uxjulia/CrossInk) — Typography and reading tracking: Bionic Reading (bolds word stems to create fixation points), guide dots between words, improved paragraph indents, and replaces the default fonts with ChareInk/Lexend/Bitter.
+
+- [papyrix-reader](https://github.com/bigbag/papyrix-reader) — Adds FB2 and MD format support. Actively maintained with Arabic script support. Custom themes via SD card.
+
+- ~~[crosspet](https://github.com/trilwu/crosspet) — A Vietnamese fork that adds a Tamagotchi-style virtual chicken that grows based on your reading milestones (pages read, streaks, care). Also: Flashcards, Weather, Pomodoro timer, and mini-games.~~ (Unmaintained)
+
+- [crosspoint-reader-cjk](https://github.com/aBER0724/crosspoint-reader-cjk) — Purpose-built for Chinese, Japanese, and Korean reading.
+
+- [inx](https://github.com/obijuankenobiii/inx) — Completely reimagines the user interface with tabbed navigation.
+
+- ~~[PlusPoint](https://github.com/ngxson/pluspoint-reader) — custom JS apps support.~~ (Unmaintained)
+
+- [crosspoint-reader-papers3](https://github.com/juicecultus/crosspoint-reader-papers3) — Crosspoint port for M5Stack Paper S3. 
+
+- [t5s3-reader](https://github.com/ShallowGreen123/t5s3-reader) — Crosspoint port for LilyGo T5 ePaper S3 / T5S3 4.7-inch e-paper device.
+
+**Note:** Many of these features will make their way into CrossPoint over time. We maintain a slower pace to ensure rock-solid stability and squash bugs before they reach your device.
+
+Want to build your own device? Be sure to check out the [de-link](https://github.com/iandchasse/de-link) project.
+
+---
+
+CrossPoint Reader is **not affiliated with Xteink or any device manufacturer**.
+
+Huge shoutout to [diy-esp32-epub-reader](https://github.com/atomic14/diy-esp32-epub-reader), which inspired this project.

ROADMAP.md

@@ -0,0 +1,88 @@
+# CrossPoint Reader Roadmap
+
+This roadmap describes how CrossPoint is moving through the tighter scope defined in [SCOPE.md](SCOPE.md). It is
+intentionally phased: Phase 0 closed out the commitments already in flight before locking down to the stricter
+"fill gaps the stock firmware leaves" delineator.
+
+Phases are sequential. We do not start the next phase until the prior one is wrapped or explicitly carried over.
+
+---
+
+## Phase 0 - Close Out Legacy Scope Items — **COMPLETE**
+
+**Goal:** Land the work that was already in motion under the prior, broader scope so contributors are not left
+hanging, and so we enter the stricter phases with a clean slate.
+
+**Landed in Phase 0:**
+
+* **RTL support PRs.** The in-flight right-to-left work was reviewed, iterated, and merged.
+* **Dictionary PR.** The offline dictionary lookup work was reviewed and merged.
+* **Bookmarks** feature. First-class navigation markers in EPUBs.
+* ~~**Transparent sleep screens.**~~ Shelved; not picked back up under the stricter phases.
+
+Phase 0 is closed. The tighter scope in [SCOPE.md](SCOPE.md) is now fully enforced. "But it was on the old roadmap"
+is not a valid argument for accepting a PR.
+
+---
+
+## Phase 1 - Consolidation, Footprint, and Multi-Device Support — **IN PROGRESS**
+
+**Goal:** Reduce memory and flash usage, clean up the codebase, and land the SDK / HAL generalization work so
+CrossPoint runs cleanly on ESP32-based e-reader hardware beyond Xteink (X3 / X4), including ESP32-S3 class devices.
+
+**Focus areas:**
+
+* DRAM and heap fragmentation reduction across the reader core.
+* Flash footprint reduction (dead code, redundant strings, oversized tables).
+* Refactors that tighten the HAL / SDK boundary.
+* Pluggable per-device SDK layers (display, input, storage, battery) and per-device build configuration without
+  forking the reader core.
+* Documentation for adding a new ESP32 e-reader target.
+* E-ink driver refinement (ghosting, partial update behavior).
+
+**Closed during this phase:** new themes built into firmware, new external network connectors (sync engines, cloud
+storage, remote file access).
+
+---
+
+## Phase 2 - Languages, Fonts, and Themes
+
+**Goal:** With the codebase smaller and portable, make reading great in every language: multi-language support,
+better font support with custom fonts, UI translations, and themes loaded from the SD card instead of consuming
+flash.
+
+**Focus areas:**
+
+* Multi-language reading support (underserved languages, complex script support where realistic on ESP32 hardware).
+* Better font support and custom fonts.
+* UI languages and localization.
+* Moving themes off-firmware to SD-loaded assets (see SCOPE.md Section 6).
+* **Moving hyphenation files off-firmware.** Hyphenation rules vary per language and the files are large (German
+  alone is ~200KB). Today these eat flash budget that should be available for the reader core. The plan is to build
+  a downloader analogous to the existing font downloader and store the dictionaries on SD / SPIFFS, loading on
+  demand. This unlocks better hyphenation for long-word languages (German, Finnish, Norwegian, etc.) without paying
+  the flash cost up front.
+
+This phase depends on Phase 1 cleanup landing first; otherwise we generalize a moving target.
+
+---
+
+## Out of Roadmap
+
+The following are explicitly *not* on the roadmap. They may live in other CrossPoint forks; they will not be picked
+up here:
+
+* Interactive apps (games, calculators, notepads).
+* Writing / authoring tools.
+* Active connectivity features (RSS, news, browsers).
+* PDF rendering as a first-class format.
+
+See [SCOPE.md](SCOPE.md) for the full rationale.
+
+---
+
+## How This Roadmap Changes
+
+* Phase boundaries are decided by maintainers, not by individual PRs.
+* If a phase needs to be extended or an item carried over, that is documented here with a short note.
+* Proposals for new phases or reordering should go through a Discussion first.

SCOPE.md

@@ -0,0 +1,100 @@
+# Project Vision & Scope: CrossPoint Reader
+
+The goal of CrossPoint Reader is to create an efficient, open-source reading experience for ESP32-based e-reader devices. Xteink hardware (X3, X4) is where the project started and remains a primary target, but CrossPoint is explicitly broadening to support the wider ecosystem of small ESP32 e-ink readers. 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 ESP32-based e-reader hardware, prioritizing legibility, performance, and usability over "swiss-army-knife" functionality.
+
+CrossPoint is **not** a kitchen-sink firmware, and it is **not** Xteink-only. We want clean, maintainable code that the community can build on, and that runs across the range of ESP32 e-reader devices (ESP32-C3, ESP32-S3, and adjacent variants). Every accepted change should make that goal easier, not harder. Device-specific code should live behind the HAL / SDK boundary so the reader core stays portable.
+
+## 2. Guiding Principle: Fill Gaps the Stock Firmware Leaves
+
+CrossPoint exists to do the things the stock firmware does poorly or not at all. New work is evaluated against that delineator:
+
+* **Does the stock firmware already do this well?** We should hit that bar or surpass it 
+* **Is another popular CrossPoint fork already solving this well?** If yes, we generally defer to that fork if it's not part of the core reading experience. e.g. stats
+* **Does this directly improve the reading experience or the firmware's long-term maintainability?** If no, it is out of scope.
+
+## 3. Current Focus
+
+We are intentionally narrowing scope to consolidate the codebase as we open it up to more ESP32 e-reader devices.
+
+During this period, the priorities are:
+
+* **Memory footprint:** Reducing DRAM usage and heap fragmentation. The ESP32-C3 is the tightest target and sets the ceiling, but the gains benefit every ESP32 variant we run on. 
+* **Flash footprint:** Trimming binary size to leave room for additional device targets and features. 
+* **Code cleanup:** Refactoring, removing dead code, tightening abstractions, and improving readability. 
+* **Reading experience:** EPUB parsing and rendering, typography, hyphenation, line spacing, font handling, and legibility improvements.
+
+### Temporarily Closed Areas
+
+PRs in the following areas will be closed until this notice is lifted. Adding these now makes the cleanup and multi-device work materially harder:
+
+* **New themes.** The existing theming surface is frozen. 
+* **New external network connectors.** This includes sync engines, cloud storage clients, OPDS extensions beyond what exists, remote file access, and any new "talk to a server" feature. We now have our own CrossPoint KOSync server which gives us a way to sync to 3rd party systems like Hardcover at an API level instead of bloating the firmware. If you're interested in helping here, the sync server is also open source.
+
+If you are unsure whether your idea falls into one of these categories, open a Discussion first.
+
+## 4. Scope
+
+### In-Scope
+
+*Features that directly improve the core reading experience or the firmware's maintainability.*
+
+* **EPUB Rendering & Optimization:** Improvements to the rendering engine, CSS/image handling, and parsing performance. 
+* **Typography & Legibility:** Custom font support, hyphenation, line and paragraph spacing, margins. 
+* **E-Ink Driver Refinement:** Reducing full-screen flashes (ghosting management) and improving general rendering. 
+* **Reading UX:** Bookmarks, progress tracking, button mapping, page navigation, and other in-reader interactions. 
+* **Library Management:** Simple, intuitive ways to organize and navigate a local book collection. 
+* **Memory, Flash, and Code Quality:** Refactors and cleanups that reduce resource use or improve maintainability, even without a user-visible feature.
+
+### Out-of-Scope
+
+*Rejected because they compromise the device's stability, maintainability, or core mission.*
+
+* **Interactive Apps:** No notepads, calculators, or games. These belong in other forks and are not part of CrossPoint's focus. 
+* **Writing / Authoring Tools:** No typed notes, journals, or editors. Input hardware and RAM are wrong for this, and other forks already explore this space. 
+* **Active Connectivity:** No RSS readers, news aggregators, or web browsers. Background Wi-Fi drains the battery and complicates the single-core CPU. 
+* **PDF Rendering:** PDFs are fixed-layout documents, so rendering them requires displaying pages as images rather than reflowable text, resulting in constant panning and zooming that makes for a poor reading experience on e-ink. Out of scope on the current hardware class.
+
+## 5. Calls to Action
+
+These are the areas where contributor help is most valuable right now. If you want to take one of these on, open a Discussion or issue first so we can coordinate.
+
+### Theme System: Move Themes Off-Firmware
+
+We want to abstract themes out of the firmware entirely so they no longer consume flash, and instead load from the SD card. This directly supports the current focus on flash footprint and code cleanup.
+
+* **Status:** [@itsthisjustin](https://github.com/itsthisjustin) plans to take this on eventually but is very open to someone else claiming it sooner. 
+* **Why it matters:** Every built-in theme costs flash that we would rather spend on rendering, fonts, or future device support. SD-loaded themes also let users customize without rebuilding firmware. It also leads to SD font loading for better language support in the UI. 
+* **How to claim:** Comment on the relevant Discussion (or open one) before starting.
+
+### Identifying Other Stock-Firmware Gaps
+
+We want help cataloguing things the stock firmware (and other popular CrossPoint forks) handle poorly or not at all, so future work has a clear target list. Particularly interested in:
+
+* **RTL (right-to-left) text support:** Arabic, Hebrew, Persian, and similar scripts. 
+* **Languages with poor stock and fork coverage:** Especially those that need shaping, complex layout, or non-Latin font work that nobody is handling well today. 
+* **Other gaps:** Rendering edge cases, accessibility issues, input quirks, anything stock does badly and existing forks have not fixed.
+
+If you can read or use the device in one of these languages, your feedback (even without code) is genuinely useful. Open a Discussion with concrete examples (screenshots, sample EPUBs, expected vs actual behavior) and we will prioritize from there.
+
+## 6. Funding and Contributor Sustainability
+
+CrossPoint uses [Royalty.dev](https://royalty.dev) (yes, a product built by [@itsthisjustin](https://github.com/itsthisjustin)) to fund contributors. There has been some tension in the community around this, so the intent is being clarified here directly.
+
+**Why we do this:**
+
+* To maintain long-term interest from contributors and maintainers, in direct response to substantial community requests for a way to give back. 
+* To motivate contributors to invest in the *core* project rather than spinning up competing forks. 
+* To help pay for new ESP32 devices so we can port CrossPoint to additional hardware. 
+* To give the project a credible long-term path to sustainability.
+
+**How it works:**
+
+* Funds are distributed automatically to contributors based on impact to the codebase and tenure on the project. 
+* Over **$600** was raised in the first few hours after opening up funding, which is a signal the demand is real. 
+* The exact scoring methodology is published at <https://app.royalty.dev/transparency>.
+
+**This is not fixed in stone.** The weighting, eligibility, and distribution rules can be tweaked as we learn what works for this project. If you have concerns or suggestions about how funds are allocated, open a Discussion. The goal is a system that fairly recognizes the people doing the work, not a perfect one on day one.

USER_GUIDE.md

@@ -1,17 +1,73 @@
 # CrossPoint User Guide
 
-Welcome to the **CrossPoint** firmware. This guide outlines the hardware controls, navigation, and reading features of 
-the device.
+Welcome to the **CrossPoint** firmware. This guide outlines the hardware controls, navigation, and reading features of the device.
+
+- [CrossPoint User Guide](#crosspoint-user-guide)
+  - [1. Hardware Overview](#1-hardware-overview)
+    - [Button Layout](#button-layout)
+    - [Taking a Screenshot](#taking-a-screenshot)
+  - [2. Power \& Startup](#2-power--startup)
+    - [Power On / Off](#power-on--off)
+    - [First Launch](#first-launch)
+  - [3. Screens](#3-screens)
+    - [3.1 Home Screen](#31-home-screen)
+    - [3.2 Reading Mode](#32-reading-mode)
+    - [3.3 Browse Files Screen](#33-browse-files-screen)
+    - [3.4 Recent Books Screen](#34-recent-books-screen)
+    - [3.5 File Transfer Screen](#35-file-transfer-screen)
+    - [3.5.1 Calibre Wireless Transfers](#351-calibre-wireless-transfers)
+      - [Installing the Plugin in Calibre](#installing-the-plugin-in-calibre)
+      - [Configuring the CrossPoint Plugin in Calibre](#configuring-the-crosspoint-plugin-in-calibre)
+      - [Uploading Books](#uploading-books)
+      - [Removing a Book](#removing-a-book)
+    - [3.6 Settings](#36-settings)
+      - [3.6.1 Display](#361-display)
+      - [3.6.2 Reader](#362-reader)
+      - [3.6.3 Controls](#363-controls)
+      - [3.6.4 System](#364-system)
+      - [3.6.5 OPDS Servers (Multiple Libraries)](#365-opds-servers-multiple-libraries)
+      - [3.6.6 Web Settings (Wi-Fi + OPDS)](#366-web-settings-wi-fi--opds)
+      - [3.6.7 KOReader Sync Quick Setup](#367-koreader-sync-quick-setup)
+        - [Option A: CrossPoint Sync Server (`sync.crosspointreader.com`, default)](#option-a-crosspoint-sync-server-synccrosspointreadercom-default)
+        - [Option B: Legacy Public KOReader Server (`sync.koreader.rocks`)](#option-b-legacy-public-koreader-server-synckoreaderrocks)
+        - [Option C: Self-Hosted Server (Docker Compose)](#option-c-self-hosted-server-docker-compose)
+        - [Syncing While Reading](#syncing-while-reading)
+    - [3.7 Sleep Screen](#37-sleep-screen)
+      - [Cover settings](#cover-settings)
+      - [Custom images](#custom-images)
+    - [3.8 Custom Fonts (SD Card)](#38-custom-fonts-sd-card)
+  - [4. Reading Mode](#4-reading-mode)
+    - [Page Turning](#page-turning)
+    - [Chapter Navigation](#chapter-navigation)
+    - [Auto Page Turn](#auto-page-turn)
+    - [Tilt Page Turn (X3 only)](#tilt-page-turn-x3-only)
+    - [Footnote Navigation](#footnote-navigation)
+    - [System Navigation](#system-navigation)
+    - [Supported Languages](#supported-languages)
+  - [5. Reader Menu](#5-reader-menu)
+    - [5.1 Chapter Selection](#51-chapter-selection)
+    - [5.2 Bookmarks](#52-bookmarks)
+  - [6. Current Limitations \& Roadmap](#6-current-limitations--roadmap)
+  - [7. Troubleshooting Issues \& Escaping Bootloop](#7-troubleshooting-issues--escaping-bootloop)
 
 ## 1. Hardware Overview
 
-The device utilises the standard buttons on the Xtink X4 in the same layout:
+The device utilises the standard buttons on the Xteink X4 (in the same layout as the manufacturer firmware, by default):
 
 ### Button Layout
+
 | Location        | Buttons                                              |
-|-----------------|--------------------------------------------|
+| --------------- | ---------------------------------------------------- |
 | **Bottom Edge** | **Back**, **Confirm**, **Left**, **Right**           |
-| **Right Side**  | **Power**, **Volume Up**, **Volume Down**  |
+| **Right Side**  | **Power**, **Volume Up**, **Volume Down**, **Reset** |
+
+Button layout can be customized in the **[Controls Settings](#363-controls)**.
+
+### Taking a Screenshot
+
+When the Power Button and Volume Down button are pressed at the same time, it will take a screenshot and save it in the folder `screenshots/`.
+
+Alternatively, while reading a book, press the **Confirm** button to open the reader menu and select **Take screenshot**.
 
 ---
 
@@ -19,14 +75,17 @@ The device utilises the standard buttons on the Xtink X4 in the same layout:
 
 ### Power On / Off
 
-To turn the device on or off, **press and hold the Power button for half a second**. In **Settings** you can configure
-the power button to trigger on a short press instead of a long one.
+To turn the device on or off, **press and hold the Power button for approximately half a second**.
+In the **[Controls Settings](#363-controls)** you can configure the power button to turn the device off with a short press instead of a long one.
+
+To reboot the device (for example after a firmware update or if it's frozen), press and release the Reset button, and then quickly press and hold the Power button for a few seconds.
 
 ### First Launch
 
-Upon turning the device on for the first time, you will be placed on the **Home** screen.
+Upon turning the device on for the first time, you will be placed on the **[Home](#31-home-screen)** screen.
 
-> **Note:** On subsequent restarts, the firmware will automatically reopen the last book you were reading.
+> [!NOTE]
+> On subsequent restarts, the firmware will automatically reopen the last book you were reading.
 
 ---
 
@@ -34,57 +93,455 @@ Upon turning the device on for the first time, you will be placed on the **Home*
 
 ### 3.1 Home Screen
 
-The Home Screen is the main entry point to the firmware. From here you can navigate to the **Book Selection** screen,
-**Settings** screen, or **File Upload** screen.
+The Home screen is the main entry point to the firmware. From here you can navigate to **[Reading Mode](#4-reading-mode)** with the most recently read book, the **[Browse Files](#33-browse-files-screen)** screen, the **[Recent Books](#34-recent-books-screen)** screen, the **[File Transfer](#35-file-transfer-screen)** screen, or **[Settings](#36-settings)**.
 
-### 3.2 Book Selection (Read)
+### 3.2 Reading Mode
 
-The Book Selection acts as a folder and file browser.
+See [Reading Mode](#4-reading-mode) below for more information.
 
-* **Navigate List:** Use **Left** (or **Volume Up**), or **Right** (or **Volume Down**) to move the selection cursor up 
-  and down through folders and books.
-* **Open Selection:** Press **Confirm** to open a folder or read a selected book.
+### 3.3 Browse Files Screen
 
-### 3.3 Reading Screen
+The Browse Files screen acts as a file and folder browser. The full path to the current directory is shown at the top of the screen. File extensions are displayed alongside each filename, and directories are shown with brackets (e.g. `[folder-name]`). Hidden directories (those beginning with `.`) are also visible.
 
-See [4. Reading Mode](#4-reading-mode) below for more information.
+* **Navigate List:** Use **Left** (or **Volume Up**), or **Right** (or **Volume Down**) to move the selection cursor up and down through folders and books. You can also long-press these buttons to scroll a full page up or down.
+* **Open Selection:** Press **Confirm** to open a folder or start reading a selected book. Selecting a `.bmp` file will open the image viewer.
+* **Delete Files or Folders:** Hold and release **Confirm** to delete the selected file or folder. You will be given an option to either confirm or cancel. Multiple files can be selected for deletion in a single operation.
+* **Rename or Move:** Files can be renamed or moved to a different folder from within the browse screen.
 
-### 3.4 File Upload Screen
+### 3.4 Recent Books Screen
 
-The File Upload screen allows you to upload new e-books to the device. When you enter the screen you'll be prompted with
-a WiFi selection dialog and then your X4 will start hosting a web server.
+The Recent Books screen lists the most recently opened books in a chronological view, displaying title and author.
 
-See the [webserver docs](./docs/webserver.md) for more information on how to connect to the web server and upload files.
+### 3.5 File Transfer Screen
 
-### 3.5 Settings
+The File Transfer screen allows you to upload and manage files on the device. When you enter the screen, choose **Join a Network**, **Calibre Wireless**, or **Create Hotspot**. The reader then starts the web server for the selected mode.
+
+See the [web server docs](./docs/webserver.md) for more information on how to connect to the web server and upload files.
+
+The web interface also supports **WebDAV**, allowing you to mount the device as a network drive and manage files directly from your computer's file manager.
+
+Download links for files already on the device are available in the web interface, so you can retrieve books or screenshots over Wi-Fi without connecting a cable.
+
+A **Wi-Fi signal strength indicator** (dBm) is displayed on-screen during joined-network web server sessions.
+
+> [!TIP]
+> Advanced users can also manage files programmatically or via the command line using `curl`. See the [web server docs](./docs/webserver.md) for details.
+> [!TIP]
+> If your EPUBs have compatibility issues, you can run the built-in **EPUB Optimizer** directly from the device to clean up and reprocess books for better rendering.
+
+### 3.5.1 Calibre Wireless Transfers
+
+CrossPoint supports sending books from Calibre using the CrossPoint Reader device plugin.
+
+#### Installing the Plugin in Calibre
+
+If you don't already have the plugin installed:
+
+1. Head to https://github.com/crosspoint-reader/calibre-plugins/releases to download the latest version of the crosspoint_reader plugin.
+2. Download the zip file.
+3. Open Calibre → Preferences → Plugins → Load plugin from file → Select the zip file.
+4. Restart Calibre.
+
+#### Configuring the CrossPoint Plugin in Calibre
+1. In Calibre select Preferences.
+2. In the Preferences dialog select Plugins.
+3. In Plugins search for "crosspoint".
+4. Click on "Customize plugin".
+5. Update the value for "Host" to match the IP for your device.
+6. Leave the other settings as they are.
+7. [optional] Modify the "Upload path" to point to a subfolder other than the root "/" folder. Enter this as a path relative to the root folder. Example: `/mybooks`
+8. Restart Calibre.
+
+<img width="420" height="385" alt="Image" src="https://github.com/user-attachments/assets/01fc7e33-a9a7-48ba-9e26-2e68d1f9daec" />
+
+#### Uploading Books
+
+To upload a book using the CrossPoint plugin in Calibre:
+
+1. On the device: File Transfer -> Calibre Wireless, then join a network.
+2. Select one or more books.
+3. Right-click on that selection.
+4. Select "Send to Device" > "Send to main memory"
+
+The CrossPoint plugin will connect to your device, create a folder for the book's author in the root folder (or the folder you configured for the plugin), then copy the book into that folder.
+
+<img width="783" height="310" alt="Image" src="https://github.com/user-attachments/assets/741b0909-2e1d-4f16-8af0-2c43fbda5ce6" />
+
+#### Removing a Book
+
+Books cannot be removed from your device through Calibre. Use the web interface instead.
+
+### 3.6 Settings
 
 The Settings screen allows you to configure the device's behavior. There are a few settings you can adjust:
-- **Sleep Screen**: Which sleep screen to display when the device sleeps, options are:
-  - "Dark" (default) - The default dark sleep screen
+
+#### 3.6.1 Display
+
+- **Sleep Screen**: Which sleep screen to display when the device sleeps:
+  
+  - "Dark" (default) - The default dark Crosspoint logo sleep screen
   - "Light" - The same default sleep screen, on a white background
-  - "Custom" - Custom images from the SD card, see [3.6 Sleep Screen](#36-sleep-screen) below for more information
+  - "Custom" - Custom images from the SD card; see [Sleep Screen](#37-sleep-screen) below for more information
   - "Cover" - The book cover image (Note: this is experimental and may not work as expected)
-- **Extra Paragraph Spacing**: If enabled, vertical space will be added between paragraphs in the book, if disabled,
-  paragraphs will not have vertical space between them, but will have first word indentation.
-- **Short Power Button Click**: Whether to trigger the power button on a short press or a long press.
-- **Front Button Layout**: Swap the order of the bottom edge buttons from Back/Confirm/Left/Right to Left/Right/Back/Confirm.
+  - "None" - A blank screen
+  - "Cover + Custom" - The book cover image while actively reading, falls back to "Custom" behavior otherwise
+  - "Quick resume" - The text of the last page read will be displayed on the sleep screen and a moon icon is shown on the edge of the screen. Waking up the device will return to the same page of the opened book. This is useful for quickly resuming reading without waiting for the device to fully wake up and load the book.
 
-### 3.6 Sleep Screen
+- **Sleep Screen Cover Mode**: How to display the book cover when "Cover" sleep screen is selected:
   
-You can customize the sleep screen by placing custom images in specific locations on the SD card:
+  - "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 fill the screen (Note: this is experimental and may not work as expected)
 
-- **Single Image:** Place a file named `sleep.bmp` in the root directory.
-- **Multiple Images:** Create a `sleep` directory in the root of the SD card and place any number of `.bmp` images
-  inside. If images are found in this directory, they will take priority over the `sleep.png` file, and one will be
-  randomly selected each time the device sleeps.
+- **Sleep Screen Cover Filter**: What filter will be applied to the book cover when "Cover" sleep screen is selected:
+  
+  - "None" (default) - The cover image will be converted to a grayscale image and displayed as it is
+  - "Contrast" - The image will be displayed as a black & white image without grayscale conversion
+  - "Inverted" - The image will be inverted as in white & black and will be displayed without grayscale conversion
+
+- **Quick Resume on Timeout**: Whether to enable the "Quick Resume" sleep screen when the device goes to sleep due to inactivity (System > Time to Sleep). This is useful for quickly resuming reading without waiting for the device to fully wake up and load the book. This overwrites the Sleep Screen Cover Mode when enabled.
+
+- **Status Bar**: Configure the status bar displayed while reading:
+  
+  - "None" - No status bar
+  - "No Progress" - Show status bar without 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 percentage display in the status bar; the battery icon will still be shown:
+  
+  - "Never" (default) - Always show battery percentage
+  - "In Reader" - Show battery percentage everywhere except in reading mode
+  - "Always" - Always hide battery percentage
+
+- **Refresh Frequency**: Set how often the screen does a full refresh while reading to reduce ghosting; options are every 1, 5, 10, 15, or 30 pages.
+
+- **UI Theme**: Set which UI theme to use:
+  
+  - "Classic" - The original Crosspoint theme
+  - "Lyra" - The new theme for Crosspoint featuring rounded elements and menu icons
+  - "Lyra Extended" - Lyra, but displays 3 books instead of 1 on the **[Home Screen](#31-home-screen)**
+  - "RoundedRaff" - A rounded theme with additional visual styling
+
+- **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
 
 > [!NOTE]
-> You'll need to set the **Sleep Screen** setting to **Custom** in order to use these images.
+> A battery charging indicator is shown on the battery icon whenever the device is actively charging.
+
+#### 3.6.2 Reader
+
+- **Reader Font Family**: Choose the font used for reading:
+  
+  - "Noto Serif" (default) - Google's serif font
+  - "Noto Sans" - Google's sans-serif font
+
+- **Reader Font Size**: Adjust the text size for reading; options are "Small", "Medium" (default), "Large", or "X Large".
+
+- **Reader Line Spacing**: Adjust the spacing between lines; options are "Tight", "Normal" (default), or "Wide".
+
+- **Reader Screen Margin**: Controls the screen margins in Reading Mode between 5 and 40 pixels in 5-pixel increments.
+
+- **Reader Paragraph Alignment**: Set the alignment of paragraphs; options are "Justified" (default), "Left", "Center", or "Right".
+
+- **Embedded Style**: Whether to use the EPUB file's embedded HTML and CSS stylisation and formatting; options are "ON" or "OFF".
+
+- **Hyphenation**: Whether to hyphenate text in Reading Mode; options are "ON" or "OFF".
+
+- **Reading Orientation**: Set the screen orientation for reading EPUB files:
+  
+  - "Portrait" (default) - Standard portrait orientation
+  - "Landscape CW" - Landscape, rotated clockwise
+  - "Inverted" - Portrait, upside down
+  - "Landscape CCW" - Landscape, rotated counter-clockwise
+
+- **Extra Paragraph Spacing**: Set how to handle paragraph breaks:
+  
+  - "ON" - Vertical space will be added between paragraphs in Reading Mode
+  - "OFF" - Paragraphs will not have vertical space added, but will have first-line indentation
+
+- **Dictionary**: Select the StarDict dictionary used for word lookups while reading, or "None" to disable lookups. *(Only shown when at least one dictionary folder exists under `/dictionaries/` on the SD card — see [docs/dictionary.md](docs/dictionary.md) for setup and usage.)*
+
+- **Text Anti-Aliasing**: Whether to show smooth grey edges (anti-aliasing) on text in reading mode. Note this slows down page turns slightly.
+
+- **Images**: Whether to display embedded images (JPG/PNG) found in EPUB files; options are "ON" (default) or "OFF".
+
+- **Focus Reading**: Bolds the first part of each word to create visual fixation points, similar to Bionic Reading. This can help improve reading speed and focus; options are "ON" or "OFF" (default).
+
+#### 3.6.3 Controls
+
+- **Remap Front Buttons**: A menu for customising the function of each bottom edge button.
+
+- **Side Button Layout (reader)**: Swap the order of the up and down volume buttons from "Prev/Next" (default) to "Next/Prev". You can also disable them entirely. This change is only in effect when reading.
+
+- **Long-press Chapter Skip**: Set whether long-pressing page turn buttons skips to the next/previous chapter:
+  
+  - "Chapter Skip" (default) - Long-pressing skips to next/previous chapter
+  - "Page Scroll" - Long-pressing scrolls a page up/down
+- **Long-press Menu**: Selects the function bound to holding the menu button (Confirm) while reading an EPUB. **Cycles through the available functions** each time the setting is selected — additional functions may be added in future releases, so this is not a binary on/off toggle. A short press of Confirm always opens the reader menu as normal:
+  - "Bookmark" (default) - Hold Confirm (~0.4 second) to drop a bookmark at the current page.
+  - "KOSync" - Hold Confirm (~1 second) to launch KOReader sync directly.
+  - "Dictionary" - Hold Confirm (~0.4 second) to start dictionary word selection on the current page (see [docs/dictionary.md](docs/dictionary.md)).
+  - "Disabled" - Long-press is ignored; only short-press opens the reader menu.
+
+- **Short Power Button Click**: Controls the effect of a short click of the power button:
+  
+  - "Ignore" (default) - Require a long press to turn off the device
+  - "Sleep" - A short press puts the device into sleep mode
+  - "Page Turn" - A short press in reading mode turns to the next page; a long press turns the device off
+  - "Footnotes" - A short press in reading mode opens the footnotes submenu; if only one footnote is present on the page, the referenced page is opened directly. The short press on the power button can be used to select the footnote in the submenu, and to go back to the original page after finish reading the footnote (like the back button).
+  - "Refresh" - A short press triggers a manual full-screen refresh, useful for clearing ghosting
+- **Quick-return from footnotes**: Toggles on and off the quick return functionality from the footnotes. When the functionality it's active, a short press of the power button will act as the back button from the footnotes page.
+
+#### 3.6.4 System
+
+- **Time to Sleep**: Set the duration of inactivity before the device automatically goes to sleep; options are 1, 3, 5, 10 (default), 15 or 30 minutes.
+
+- **Wi-Fi Networks**: Connect to Wi-Fi networks for file transfers and firmware updates.
+
+- **KOReader Sync**: Options for setting up KOReader for syncing book progress. **Smart sync** is the default for new configurations and auto-resolves simple push/pull decisions. Existing credential files retain **Ask every time** when migrated; you can switch Sync Behavior at any time if you prefer manual confirmation.
+
+- **OPDS Servers**: Manage one or more OPDS [(Open Publication Distribution System)](https://en.wikipedia.org/wiki/Open_Publication_Distribution_System) libraries for browsing and downloading books. See [OPDS Servers (Multiple Libraries)](#365-opds-servers-multiple-libraries) below.
+
+- **Clear Reading Cache**: Clear the internal SD card cache.
+
+- **Check for updates**: Check for Crosspoint firmware updates over Wi-Fi. Firmware can also be updated without a USB connection by placing a `firmware.bin` file on the SD card.
+
+- **Language**: Set the UI language. CrossPoint supports 24 languages: English, Spanish, French, German, Czech, Brazilian Portuguese, Russian, Swedish, Romanian, Catalan, Ukrainian, Belarusian, Italian, Polish, Finnish, Danish, Dutch, Turkish, Kazakh, Hungarian, Lithuanian, Slovenian, Valencian, and Hebrew.
+
+- **Manage Fonts**: Browse, download, and manage custom font families installed from the SD card. See [Custom Fonts (SD Card)](#38-custom-fonts-sd-card) for more information.
+
+#### 3.6.5 OPDS Servers (Multiple Libraries)
+
+CrossPoint supports saving multiple OPDS servers and switching between them when browsing catalogs.
+
+1. Open **Settings -> System -> OPDS Servers**.
+
+2. Select **Add Server** to create a new entry, or select an existing server to edit it.
+
+3. Configure these fields:
+   
+   - **Server Name**: Optional display name (for example, "Home Calibre" or "Public Catalog").
+   
+   - **OPDS Server URL**: Full catalog root URL (for Calibre Content Server, usually ends with `/opds`).
+   
+   - **Username / Password**: Optional credentials for authenticated servers.
+
+4. Use **Delete Server** inside a server entry to remove it.
+
+Behavior notes:
+
+- You can store up to 8 OPDS servers.
+- OPDS authentication supports HTTP Basic auth. If you use Calibre Content Server with authentication enabled, set it to Basic (not Digest).
+
+You can also manage OPDS servers from the web interface while in File Transfer mode:
+
+1. Connect to the device web UI.
+2. Open `http://<device-ip>/settings`.
+3. Use the **OPDS Servers** card to add, edit, or delete entries.
+
+For web-based Wi-Fi network management, see [Web Settings (Wi-Fi + OPDS)](#366-web-settings-wi-fi--opds).
+
+#### 3.6.6 Web Settings (Wi-Fi + OPDS)
+
+While in **File Transfer** mode, the web settings page includes management cards for both **Wi-Fi Networks** and **OPDS Servers**.
+
+1. On device: open **File Transfer** and connect through **Join a Network** or **Create Hotspot**.
+2. In a browser, open `http://<device-ip>/settings` or `http://crosspoint.local`.
+3. In **Wi-Fi Networks**, add, edit, or delete saved network entries (SSID + optional password).
+4. In **OPDS Servers**, add, edit, or delete OPDS catalogs.
+
+Behavior notes:
+
+- Passwords are never shown back in the web UI after saving.
+- Leaving Password blank while editing keeps the existing saved password unchanged.
+- The web UI can save hidden-network SSIDs, but connecting to hidden networks still depends on the device-side Wi-Fi connection flow.
+
+#### 3.6.7 KOReader Sync Quick Setup
+
+CrossPoint can sync reading progress with KOReader-compatible sync servers.
+It also interoperates with KOReader apps/devices when they use the same server and credentials.
+
+##### Option A: CrossPoint Sync Server (`sync.crosspointreader.com`, default)
+
+When **Sync Server URL** is left empty, CrossPoint uses the free CrossPoint sync server at `https://sync.crosspointreader.com`. It speaks the standard KOReader sync protocol (so KOReader apps can use it too) and additionally stores an exact spine/page position for lossless CrossPoint-to-CrossPoint sync.
+
+1. On each CrossPoint device:
+
+   - Go to **Settings -> System -> KOReader Sync**.
+
+   - Set **Username** and **Password** (enter the plain password; CrossPoint computes MD5 internally, and use the same values on all devices).
+
+   - Leave **Sync Server URL** empty (or set it to `https://sync.crosspointreader.com`).
+
+   - On the first device, run **Sign Up** once to create the account directly from the device. On every other device, just run **Authenticate**.
+
+Accounts are per server. Existing `sync.koreader.rocks` credentials do not exist on the CrossPoint server; either sign up again with the same username/password or use Option B to keep using the legacy server.
+
+##### Option B: Legacy Public KOReader Server (`sync.koreader.rocks`)
+
+Use this if you already sync KOReader devices against the official public server.
+
+1. On each CrossPoint device:
+
+   - Go to **Settings -> System -> KOReader Sync**.
+
+   - Set **Sync Server URL** to `https://sync.koreader.rocks` (required; an empty URL now points at the CrossPoint server instead).
+
+   - Set **Username** and **Password** to your existing KOReader Sync credentials.
+
+   - Run **Authenticate**.
+
+2. If you do not have an account yet, run **Sign Up** on the device, or register once with curl:
+
+```bash
+USERNAME="user"
+PASSWORD="pass"
+PASSWORD_MD5="$(printf '%s' "$PASSWORD" | openssl md5 | awk '{print $2}')"
+
+curl -i "https://sync.koreader.rocks/users/create" \
+  -H "Accept: application/vnd.koreader.v1+json" \
+  -H "Content-Type: application/json" \
+  --data "{\"username\":\"$USERNAME\",\"password\":\"$PASSWORD_MD5\"}"
+```
+
+When this returns `HTTP 402` with `{"code":2002,"message":"Username is already registered."}`, pick a different username or use that existing account.
+
+##### Option C: Self-Hosted Server (Docker Compose)
+
+1. Start a sync server:
+
+```bash
+mkdir -p kosync-quickstart
+cd kosync-quickstart
+
+cat > compose.yaml <<'YAML'
+services:
+  kosync:
+    image: koreader/kosync:latest
+    ports:
+      - "7200:7200"
+      - "17200:17200"
+    volumes:
+      - ./data/redis:/var/lib/redis
+    environment:
+      - ENABLE_USER_REGISTRATION=true
+    restart: unless-stopped
+YAML
+
+# Docker
+docker compose up -d
+
+# Podman (alternative)
+podman compose up -d
+```
+
+> [!NOTE]
+> `ENABLE_USER_REGISTRATION=true` is convenient for first setup. After creating your users, set it to `false` (or remove it) to avoid unexpected registrations.
+
+2. Verify the server:
+
+```bash
+curl -H "Accept: application/vnd.koreader.v1+json" "http://<server-ip>:17200/healthcheck"
+# Expected: {"state":"OK"}
+```
+
+3. Register a user once.
+   CrossPoint authenticates against KOReader Sync (`koreader/kosync`) using an MD5 key, so register using the MD5 of your password:
+
+> [!WARNING]
+> Sending a reusable MD5-derived password over plain HTTP is insecure.
+> Create unique sync-only credentials and do not reuse main account passwords.
+> Prefer `https://<server-ip>:7200` whenever traffic leaves a fully trusted LAN or when using untrusted networks.
+> Use `curl -k` only for self-signed certificate testing.
+
+```bash
+USERNAME="user"
+PASSWORD="pass"
+PASSWORD_MD5="$(printf '%s' "$PASSWORD" | openssl md5 | awk '{print $2}')"
+
+curl -i "http://<server-ip>:17200/users/create" \
+  -H "Accept: application/vnd.koreader.v1+json" \
+  -H "Content-Type: application/json" \
+  --data "{\"username\":\"$USERNAME\",\"password\":\"$PASSWORD_MD5\"}"
+```
+
+If this returns `HTTP 402` with `{"code":2002,"message":"Username is already registered."}`, the account already exists.
+
+4. On each CrossPoint device:
+   
+   - Go to **Settings -> System -> KOReader Sync**.
+   
+   - Set **Username** and **Password** (enter the plain password; CrossPoint computes MD5 internally, and use the same values on all devices).
+   
+   - Set **Sync Server URL** to `http://<server-ip>:17200`.
+   
+   - Run **Authenticate**.
+
+If you use the HTTPS listener, use `https://<server-ip>:7200` (`curl -k` only for self-signed certificate testing).
+
+##### Syncing While Reading
+
+Once any of the options above is set up, press **Confirm** while reading to open the reader menu, then select **Sync Progress**. Alternatively, set **Settings -> Controls -> Long-press Menu** to **KOSync** and hold Confirm to launch sync directly.
+
+- With **Sync Behavior** set to **Ask every time**, choose **Apply Remote** to jump to remote progress or **Upload Local** to push current progress.
+- With **Sync Behavior** set to **Smart sync**, CrossPoint auto-resolves simple cases: upload when no remote progress exists, confirm and leave both unchanged when local and remote progress are already synchronized, upload when local progress is further ahead, or apply remote when remote progress is further ahead.
+
+### 3.7 Sleep Screen
+
+The **Sleep Screen** setting controls what is displayed when the device goes to sleep:
+
+| Mode               | Behavior                                                                                                                     |
+| ------------------ | ---------------------------------------------------------------------------------------------------------------------------- |
+| **Dark** (default) | The CrossPoint logo on a dark background.                                                                                    |
+| **Light**          | The CrossPoint logo on a white background.                                                                                   |
+| **Custom**         | A custom image from the SD card (see below). Falls back to **Dark** if no custom image is found.                             |
+| **Cover**          | The cover of the currently open book. Falls back to **Dark** if no book is open.                                             |
+| **Cover + Custom** | The cover of the currently open book, shown only while actively reading. Falls back to **Custom** behavior when not reading. |
+| **None**           | A blank screen.                                                                                                              |
+
+#### Cover settings
+
+When using **Cover** or **Cover + Custom**, two additional settings apply:
+
+- **Sleep Screen Cover Mode**: **Fit** (scale to fit, white borders) or **Crop** (scale and crop to fill the screen).
+- **Sleep Screen Cover Filter**: **None** (grayscale), **Contrast** (black & white), or **Inverted** (inverted black & white).
+
+#### Custom images
+
+To use custom sleep images, set the sleep screen mode to **Custom** or **Cover + Custom**, then place images on the SD card:
+
+- **Multiple Images (recommended):** Create a `.sleep` directory in the root of the SD card and place any number of `.bmp` images inside. One will be randomly selected each time the device sleeps. (A directory named `sleep` is also accepted as a fallback.)
+- **Single Image:** Place a file named `sleep.bmp` in the root directory. This is used as a fallback if no valid images are found in the `.sleep`/`sleep` directory.
 
 > [!TIP]
 > For best results:
+> 
 > - Use uncompressed BMP files with 24-bit color depth
-> - Use a resolution of 480x800 pixels to match the device's screen resolution.
+> - X4: Use a resolution of 480x800 pixels to match the device's screen resolution.
+> - X3: Use a resolution of 528x792 pixels to match the device's screen resolution.
+
+> [!TIP]
+> You can set an image as the sleep screen cover directly from the BMP image viewer in the **[Browse Files](#33-browse-files-screen)** screen.
+
+---
+
+### 3.8 Custom Fonts (SD Card)
+
+CrossPoint supports loading additional fonts from the SD card, extending beyond the two built-in families (Noto Serif, Noto Sans). Custom fonts can include extended Unicode coverage, enabling CJK (Chinese, Japanese, Korean) and other scripts.
+
+There are three ways to install fonts:
+
+1. **Download from device (recommended):** Go to **Settings -> System -> Manage Fonts**, browse the available font families, and select one to download over Wi-Fi.
+2. **Upload via web interface:** While in **File Transfer** mode, open the web UI in a browser and navigate to the **Fonts** tab to upload `.cpfont` files.
+3. **Manual SD card copy:** Download font files from the [crosspoint-fonts repository](https://github.com/crosspoint-reader/crosspoint-fonts) and copy them to `/.fonts/` (preferred) or `/fonts/` on your SD card.
+
+Once installed, custom fonts appear in **Settings → Reader → Font Family** alongside the built-in fonts.
+
+See [docs/sd-card-fonts.md](./docs/sd-card-fonts.md) for full installation details and SD card folder structure.
 
 ---
 
@@ -93,24 +550,79 @@ You can customize the sleep screen by placing custom images in specific location
 Once you have opened a book, the button layout changes to facilitate reading.
 
 ### Page Turning
+
 | Action            | Buttons                              |
-|-------------------|--------------------------------------|
+| ----------------- | ------------------------------------ |
 | **Previous Page** | Press **Left** _or_ **Volume Up**    |
 | **Next Page**     | Press **Right** _or_ **Volume Down** |
 
+The role of the volume (side) buttons can be swapped in the **[Controls Settings](#363-controls)**.
+
+If the **Short Power Button Click** setting is set to "Page Turn", you can also turn to the next page by briefly pressing the Power button.
+
 ### Chapter Navigation
+
 * **Next Chapter:** Press and **hold** the **Right** (or **Volume Down**) button briefly, then release.
 * **Previous Chapter:** Press and **hold** the **Left** (or **Volume Up**) button briefly, then release.
 
+This feature can be disabled in the **[Controls Settings](#363-controls)** to help avoid changing chapters by mistake.
+
+### Auto Page Turn
+
+Auto Page Turn automatically advances pages at a set interval, useful for hands-free reading. This feature can be enabled and configured from the **[Reader Menu](#5-reader-menu)** while reading an EPUB.
+
+### Tilt Page Turn (X3 only)
+
+On the **Xteink X3**, the gyroscope can be used to turn pages by tilting the device. This feature is available in the Controls settings.
+
+### Footnote Navigation
+
+When reading an EPUB that contains footnotes, you can navigate to the footnote text by selecting the footnote reference in the book. From the footnote, you can return to your original reading position.
+
+If the device goes to sleep or you close the book while viewing a footnote, the book reopens to your original reading position, not the footnote.
+
 ### System Navigation
-* **Return to Home:** Press **Back** to close the book and return to the Book Selection screen.
-* **Chapter Menu:** Press **Confirm** to open the Table of Contents/Chapter Selection screen.
+
+* **Return to Home:** Press the **Back** button to close the book and return to the **[Home](#31-home-screen)** screen.
+* **Return to Browse Files:** Press and hold the **Back** button to close the book and return to the **[Browse Files](#33-browse-files-screen)** screen.
+* **Reader Menu:** Press **Confirm** to open the **[Reader Menu](#5-reader-menu)**, which includes chapter navigation, reading options, and more.
+* **Long-press Confirm (configurable):** Holding **Confirm** runs the function chosen by the **Long-press Menu** setting in **[Controls Settings](#363-controls)** — "Bookmark" (default) drops a bookmark, "KOSync" launches KOReader Sync, "Dictionary" starts a word lookup, "Disabled" does nothing. A short press always opens the Reader Menu.
+
+### Supported Languages
+
+CrossPoint renders text using the following Unicode character blocks, enabling support for a wide range of languages:
+
+* **Latin Script (Basic, Supplement, Extended-A/B):** Covers English, German, French, Spanish, Portuguese, Italian, Dutch, Swedish, Norwegian, Danish, Finnish, Polish, Czech, Hungarian, Romanian, Slovak, Slovenian, Turkish, Catalan, and others.
+* **Cyrillic Script (Standard and Extended):** Covers Russian, Ukrainian, Belarusian, Bulgarian, Serbian, Macedonian, Kazakh, Kyrgyz, Mongolian, and others.
+* **Vietnamese:** Supported via extended Latin glyph coverage in the built-in reader fonts.
+
+What is not supported with built-in reader fonts: Chinese, Japanese, Korean, Arabic, Greek, Hebrew, and Farsi. However, **CJK, Hebrew, Greek, and other extended scripts can be enabled by installing custom SD card fonts** — see [Custom Fonts (SD Card)](#38-custom-fonts-sd-card).
 
 ---
 
-## 5. Chapter Selection Screen
+## 5. Reader Menu
 
-Accessible by pressing **Confirm** while inside a book.
+Press **Confirm** while reading to open the Reader Menu. From here you can access reading utilities and navigation options without leaving the book.
+
+Available options include:
+
+- **Select Chapter** – Open the table of contents to jump to a specific chapter (see [Chapter Selection](#51-chapter-selection) below).
+- **Footnotes** – Navigate to the footnotes for the current section *(only shown in books that contain footnotes)*.
+- **Look Up** – Select a word on the current page and show its dictionary definition (see [docs/dictionary.md](docs/dictionary.md)). Requires a dictionary to be selected in **Settings → Reader → Dictionary**.
+- **Reading Orientation** – Cycle through screen orientations without leaving the reader.
+- **Auto Turn (Pages Per Minute)** – Cycle through automatic page turn speed options for hands-free reading.
+- **Go to %** – Jump to a specific position in the book by percentage.
+- **Take screenshot** – Save a screenshot of the current page to the `screenshots/` folder.
+- **Show page as QR** – Display a QR code encoding the current reading position.
+- **Go Home** – Close the book and return to the Home screen.
+- **Sync Progress** – Push or pull reading progress with a KOReader sync server (see [KOReader Sync Quick Setup](#367-koreader-sync-quick-setup)).
+- **Delete Book Cache** – Clear the cached layout data for the current book, forcing a re-index on next open.
+
+Press **Back** at any time to close the menu and return to your current page.
+
+### 5.1 Chapter Selection
+
+Accessible by selecting **Chapters** from the Reader Menu.
 
 1. Use **Left** (or **Volume Up**), or **Right** (or **Volume Down**) to highlight the desired chapter.
 2. Press **Confirm** to jump to that chapter.
@@ -118,11 +630,74 @@ Accessible by pressing **Confirm** while inside a book.
 
 ---
 
+### 5.2 Bookmarks
+
+Bookmarks can be created to quickly save and restore your place in a book.
+
+To create a bookmark, hold **Confirm** for about half a second while inside a book. A popup will appear letting you know a bookmark was created. The popup message will automatically disappear in a couple of seconds.
+
+To open bookmarks, press **Confirm** while inside a book. Then navigate to the **Bookmarks** menu. Bookmarks can be opened by navigating to them and pressing **Confirm**, which will redirect you to that place in the book. You can delete bookmarks by holding **Confirm** for about 0.7 seconds, and then pressing **Confirm** again to confirm deletion, or **Back** to cancel.
+
+Bookmarks are stored in the `.crosspoint/bookmarks` folder in the JSON format.
+
 ## 6. Current Limitations & Roadmap
 
-Please note that this firmware is currently in active development. The following features are **not yet supported** but
-are planned for future updates:
+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.
-* **Text Formatting:** There are currently no settings to adjust font type, size, line spacing, or margins.
-* **Rotation**: Different rotation options are not supported.
+* **Cover Images:** Large cover images embedded into EPUB require several seconds (~10s for ~2000 pixel tall image) to convert for sleep screen and home screen thumbnail. Consider optimizing the EPUB with e.g. https://github.com/bigbag/epub-to-xtc-converter to speed this up.
+* **Unsupported Image Formats:** Most JPG and PNG images in EPUBs render correctly. GIFs and progressive JPEGs are not supported and will fall back to an `[Image]` placeholder.
+* 
+* **Dictionary Lookup:** Inline word lookup is not yet implemented.
+
+---
+
+## 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 logs.
+
+**Crash reports on SD card:** After a crash, CrossPoint automatically saves a crash report to the SD card (no USB connection needed). Check the root of the SD card for a crash log file and include it with any bug report.
+
+**Serial monitor logs:** For more detailed debugging, connect the device to a computer and run the custom debugging monitor script (requires Python 3 with `pyserial`, `colorama`, and `matplotlib`; install via `pip3 install pyserial colorama matplotlib`):
+
+```
+python3 scripts/debugging_monitor.py
+```
+
+The script auto-detects the serial port. You can also specify one explicitly:
+
+```
+python3 scripts/debugging_monitor.py /dev/ttyACM0        # Linux
+python3 scripts/debugging_monitor.py /dev/tty.usbmodem1  # macOS
+python3 scripts/debugging_monitor.py COM7                # Windows
+```
+
+**Features:**
+
+- Color-coded log output by category (errors, memory, display, EPUB parsing, etc.)
+- Live memory usage graph (free RAM, total RAM, max contiguous allocation) updated every second
+- Interactive command prompt — type a command and press Enter to send it to the device
+- Screenshot capture — saves the current display to `screenshot.bmp` when triggered by the device
+
+**Options:**
+
+| Option               | Description                                               |
+| -------------------- | --------------------------------------------------------- |
+| `--baud RATE`        | Baud rate (default: 115200)                               |
+| `--filter KEYWORD`   | Show only lines containing the keyword (case-insensitive) |
+| `--suppress KEYWORD` | Hide lines containing the keyword (case-insensitive)      |
+
+**Examples:**
+
+```
+# Show only memory-related log lines
+python3 scripts/debugging_monitor.py --filter MEM
+
+# Hide noisy SD card log lines
+python3 scripts/debugging_monitor.py --suppress "[SD]"
+```
+
+Press **Ctrl-C** or close the graph window to exit.
+
+If the device is stuck in a bootloop, press and release the Reset button. Then, press and hold on to the configured Back button and the Power Button to boot to the Home Screen.
+
+There can be issues with broken cache or config. In this case, delete the `.crosspoint` directory on your SD card (or consider deleting only `settings.json`, `state.json`, or `epub_*` cache directories in the `.crosspoint/` folder).

bin/clang-format-fix

@@ -1,10 +1,35 @@
-#!/bin/bash
+#!/usr/bin/env bash
+
+# Check if clang-format is available and pick the preferred binary.
+if command -v clang-format-21 >/dev/null 2>&1; then
+  CLANG_FORMAT_BIN="clang-format-21"
+elif command -v clang-format >/dev/null 2>&1; then
+  CLANG_FORMAT_BIN="clang-format"
+else
+  printf "'clang-format' not found in current environment\n"
+  printf "Install clang-format-21 (recommended), clang, clang-tools, or clang-format depending on your distro/os and tooling requirements\n"
+  exit 1
+fi
+
+set -euo pipefail
 
 GIT_LS_FILES_FLAGS=""
-if [[ "$1" == "-g" ]]; then
+# -g scopes formatting to tracked files currently modified in git status.
+if [[ "${1:-}" == "-g" ]]; then
   GIT_LS_FILES_FLAGS="--modified"
 fi
 
+CLANG_FORMAT_VERSION_RAW="$(${CLANG_FORMAT_BIN} --version)"
+CLANG_FORMAT_MAJOR="$(printf '%s\n' "${CLANG_FORMAT_VERSION_RAW}" | grep -oE '[0-9]+' | head -n1)"
+
+# Guard against local binaries older than the repo formatting config.
+if [[ -z "${CLANG_FORMAT_MAJOR}" || "${CLANG_FORMAT_MAJOR}" -lt 21 ]]; then
+  echo "Error: ${CLANG_FORMAT_BIN} is too old: ${CLANG_FORMAT_VERSION_RAW}"
+  echo "This repository's .clang-format requires clang-format 21 or newer."
+  echo "Install clang-format-21 and rerun ./bin/clang-format-fix"
+  exit 1
+fi
+
 # --- Main Logic ---
 
 # Format all files (or only modified files if -g is passed)
@@ -13,7 +38,16 @@ fi
 # --modified: files tracked by git that have been modified (staged or unstaged)
 # --exclude-standard: ignores files in .gitignore
 # Additionally exclude files in 'lib/EpdFont/builtinFonts/' as they are script-generated.
+# Also exclude files in 'lib/Epub/Epub/hyphenation/generated/' as they are script-generated.
+# Keep the no-match case non-fatal: grep returns 1 when no files match,
+# which is expected when there are no modified C/C++ files.
+set +o pipefail
 git ls-files  --exclude-standard ${GIT_LS_FILES_FLAGS} \
     | grep -E '\.(c|cpp|h|hpp)$' \
     | grep -v -E '^lib/EpdFont/builtinFonts/' \
-    | xargs -r clang-format -style=file -i
+    | grep -v -E '^lib/Epub/Epub/hyphenation/generated/' \
+    | grep -v -E '^lib/uzlib/' \
+    | grep -v -E '^lib/miniz/third_party/' \
+    | xargs -r "${CLANG_FORMAT_BIN}" -style=file -i
+# Restore strict pipeline failure handling for the rest of the script.
+set -o pipefail

bin/clang-format-fix.ps1

@@ -0,0 +1,155 @@
+<#
+.SYNOPSIS
+    Runs clang-format -i on project *.cpp and *.h files.
+
+.DESCRIPTION
+    Formats all C/C++ source and header files in the repository, excluding
+    generated, vendored, and build directories (freeink-sdk, builtinFonts,
+    hyphenation tries, uzlib, .pio, *.generated.h).
+
+    The clang-format binary path is resolved once and cached in
+    bin/clang-format-fix.local. On first run it checks a default path,
+    then PATH, then common install locations. Edit the .local file to
+    override manually.
+
+.PARAMETER g
+    Format only git-modified files (git diff --name-only HEAD) instead of
+    the full tree.
+
+.PARAMETER h
+    Show this help text.
+
+.EXAMPLE
+    .\clang-format-fix.ps1
+    Format all files.
+
+.EXAMPLE
+    .\clang-format-fix.ps1 -g
+    Format only git-modified files.
+#>
+
+param(
+    [switch]$g,
+    [switch]$h
+)
+
+if ($h) {
+    Get-Help $PSCommandPath -Detailed
+    return
+}
+
+$repoRoot = (Resolve-Path "$PSScriptRoot\..").Path
+$configFile = Join-Path $PSScriptRoot 'clang-format-fix.local'
+$defaultPath = 'C:\Program Files\LLVM\bin\clang-format.exe'
+
+$candidatePaths = @(
+    'C:\Program Files\LLVM\bin\clang-format.exe'
+    'C:\Program Files (x86)\LLVM\bin\clang-format.exe'
+    'C:\msys64\ucrt64\bin\clang-format.exe'
+    'C:\msys64\mingw64\bin\clang-format.exe'
+    "$env:LOCALAPPDATA\LLVM\bin\clang-format.exe"
+)
+
+function Find-ClangFormat {
+    # Try PATH first
+    $inPath = Get-Command clang-format -ErrorAction SilentlyContinue
+    if ($inPath) { return $inPath.Source }
+
+    # Try candidate paths
+    foreach ($p in $candidatePaths) {
+        if (Test-Path $p) { return $p }
+    }
+    return $null
+}
+
+function Resolve-ClangFormat {
+    # 1. Read from config if present
+    if (Test-Path $configFile) {
+        $saved = (Get-Content $configFile -Raw).Trim()
+        if ($saved -and (Test-Path $saved)) { return $saved }
+        Write-Host "Configured path no longer valid: $saved"
+    }
+
+    # 2. Check default
+    if (Test-Path $defaultPath) {
+        $defaultPath | Set-Content $configFile
+        Write-Host "Saved clang-format path to $configFile"
+        return $defaultPath
+    }
+
+    # 3. Search PATH and candidate locations
+    $found = Find-ClangFormat
+    if ($found) {
+        $found | Set-Content $configFile
+        Write-Host "Found clang-format at $found - saved to $configFile"
+        return $found
+    }
+
+    Write-Error "clang-format not found. Install LLVM or add clang-format to PATH."
+    exit 1
+}
+
+$clangFormat = Resolve-ClangFormat
+
+$exclude = @(
+    'freeink-sdk'
+    'lib\EpdFont\builtinFonts'
+    'lib\Epub\Epub\hyphenation\generated'
+    'lib\uzlib'
+    '.pio'
+    '.venv'
+)
+
+function Test-Excluded($fullPath) {
+    foreach ($ex in $exclude) {
+        if ($fullPath -like "*\$ex\*") { return $true }
+    }
+    if ($fullPath -like '*.generated.h') { return $true }
+    return $false
+}
+
+if ($g) {
+    # Only git-modified *.cpp / *.h files
+    # Covers both staged and unstaged changes
+    $files = @(git -C $repoRoot diff --name-only HEAD) +
+             @(git -C $repoRoot diff --name-only --cached) |
+        Sort-Object -Unique |
+        Where-Object { $_ -match '\.(cpp|h)$' } |
+        ForEach-Object { Get-Item (Join-Path $repoRoot $_) -ErrorAction SilentlyContinue } |
+        Where-Object { $_ -and -not (Test-Excluded $_.FullName) }
+} else {
+    $files = Get-ChildItem -Path $repoRoot -Recurse -Include *.cpp, *.h -File |
+        Where-Object { -not (Test-Excluded $_.FullName) }
+}
+
+$files = @($files)
+
+if ($files.Count -eq 0) {
+    Write-Host 'No files to format.'
+    return
+}
+
+Write-Host "Formatting $($files.Count) files..."
+$i = 0
+$changed = 0
+$failures = 0
+foreach ($f in $files) {
+    $i++
+    $rel = $f.FullName.Substring($repoRoot.Length + 1)
+    $hashBefore = (Get-FileHash $f.FullName -Algorithm MD5).Hash
+    & $clangFormat -i $f.FullName
+    if ($LASTEXITCODE -ne 0) {
+        $failures++
+        Write-Host "  [$i/$($files.Count)] $rel (FAILED, exit code $LASTEXITCODE)"
+        continue
+    }
+    $hashAfter = (Get-FileHash $f.FullName -Algorithm MD5).Hash
+    if ($hashBefore -ne $hashAfter) {
+        $changed++
+        Write-Host "  [$i/$($files.Count)] $rel (changed)"
+    } else {
+        Write-Host "  [$i/$($files.Count)] $rel"
+    }
+}
+Write-Host "Done. $changed/$($files.Count) files changed, $failures failed."
+if ($failures -gt 0) { exit 1 }

docs/activity-manager.md

@@ -0,0 +1,472 @@
+# Activity & ActivityManager Migration Guide
+
+This document explains the refactoring from the original per-activity render task model to the centralized `ActivityManager` introduced in [PR #1016](https://github.com/crosspoint-reader/crosspoint-reader/pull/1016). It covers the architectural differences, what changed for activity authors, and the FreeRTOS task and locking model that underpins the system.
+
+## Overview of Changes
+
+| Aspect | Old Model | New Model |
+|--------|-----------|-----------|
+| Render task | One per activity (8KB stack each) | Single shared task in `ActivityManager` |
+| Render mutex | Per-activity `renderingMutex` | Single global mutex in `ActivityManager` |
+| `RenderLock` | Inner class of `Activity` | Standalone class, acquires global mutex |
+| Subactivities | `ActivityWithSubactivity` base class | Activity stack managed by `ActivityManager` |
+| Navigation | Free functions in `main.cpp` | `activityManager.goHome()`, `goToReader()`, etc. |
+| Subactivity results | Callback lambdas stored in parent | `startActivityForResult()` / `setResult()` / `finish()` |
+| `requestUpdate()` | Notifies activity's own render task | Delegates to `ActivityManager` (immediate or deferred) |
+
+## Architecture
+
+### Old Model: Per-Activity Render Tasks
+
+Each activity created its own FreeRTOS render task on entry and destroyed it on exit:
+
+```text
+┌─────────────────────────────────────────────────────────┐
+│ Main Task (Arduino loop)                                │
+│  ┌───────────────────────────────────────────────────┐  │
+│  │ currentActivity->loop()                           │  │
+│  │   ├── handle input                                │  │
+│  │   ├── update state (under RenderLock)             │  │
+│  │   └── requestUpdate()  ──notify──►  Render Task   │  │
+│  │                                      (per-activity)│  │
+│  │                                      8KB stack     │  │
+│  │                                      owns mutex    │  │
+│  └───────────────────────────────────────────────────┘  │
+│                                                         │
+│ ActivityWithSubactivity:                                │
+│  ┌──────────────┐     ┌──────────────┐                  │
+│  │ Parent        │────►│ SubActivity   │                 │
+│  │ (has render   │     │ (has own      │                 │
+│  │  task)        │     │  render task) │                 │
+│  └──────────────┘     └──────────────┘                  │
+└─────────────────────────────────────────────────────────┘
+```
+
+Problems with this approach:
+
+- **8KB per render task**: Each activity allocated an 8KB FreeRTOS stack for its render task, even though only one renders at a time
+- **Dangerous deletion patterns**: `exitActivity()` + `enterNewActivity()` in callbacks led to `delete this` situations where the caller was destroyed while its code was still on the stack
+- **Subactivity coupling**: Parents stored callbacks to child results, creating tight coupling and lifetime hazards
+
+### New Model: Centralized ActivityManager
+
+A single `ActivityManager` owns the render task and manages an activity stack:
+
+```text
+┌──────────────────────────────────────────────────────────┐
+│ Main Task (Arduino loop)                                 │
+│                                                          │
+│  activityManager.loop()                                  │
+│    │                                                     │
+│    ├── currentActivity->loop()                           │
+│    │     ├── handle input                                │
+│    │     ├── update state (under RenderLock)              │
+│    │     └── requestUpdate()                             │
+│    │                                                     │
+│    ├── process pending actions (Push / Pop / Replace)    │
+│    │                                                     │
+│    └── if requestedUpdate: ──notify──► Render Task       │
+│                                         (single, shared) │
+│                                         8KB stack        │
+│                                         global mutex     │
+│                                                          │
+│  Activity Stack:                                         │
+│  ┌──────────┬──────────┬──────────┐    ┌──────────┐     │
+│  │ Home     │ Settings │ Wifi     │    │ Keyboard │     │
+│  │ (stack)  │ (stack)  │ (stack)  │    │ (current)│     │
+│  └──────────┴──────────┴──────────┘    └──────────┘     │
+│   stackActivities[]                    currentActivity   │
+└──────────────────────────────────────────────────────────┘
+```
+
+## Migration Checklist
+
+### 1. Change Base Class
+
+If your activity extended `ActivityWithSubactivity`, change it to extend `Activity`:
+
+```cpp
+// BEFORE
+class MyActivity final : public ActivityWithSubactivity {
+  MyActivity(GfxRenderer& r, MappedInputManager& m, std::function<void()> goBack)
+      : ActivityWithSubactivity("MyActivity", r, m), goBack(goBack) {}
+};
+
+// AFTER
+class MyActivity final : public Activity {
+  MyActivity(GfxRenderer& r, MappedInputManager& m)
+      : Activity("MyActivity", r, m) {}
+};
+```
+
+Note that navigation callbacks like `goBack` are no longer stored — use `finish()` or `activityManager.goHome()` instead.
+
+### 2. Replace Navigation Functions
+
+The free functions `exitActivity()` / `enterNewActivity()` in `main.cpp` are gone. Use `ActivityManager` methods:
+
+```cpp
+// BEFORE (in main.cpp or via stored callbacks)
+exitActivity();
+enterNewActivity(new SettingsActivity(renderer, mappedInput, onGoHome));
+
+// AFTER (from any Activity method)
+activityManager.goToSettings();
+// or for arbitrary navigation:
+activityManager.replaceActivity(std::make_unique<MyActivity>(renderer, mappedInput));
+```
+
+`replaceActivity()` destroys the current activity and clears the stack. Use it for top-level navigation (home, reader, settings, etc.).
+
+### 3. Replace Subactivity Pattern
+
+The `enterNewActivity()` / `exitActivity()` subactivity pattern is replaced by a stack with typed results:
+
+```cpp
+// BEFORE
+void MyActivity::launchWifi() {
+  enterNewActivity(new WifiSelectionActivity(renderer, mappedInput,
+      [this](bool connected) { onWifiDone(connected); }));
+}
+// Child calls: onComplete(true); // triggers callback, which may call exitActivity()
+
+// AFTER
+void MyActivity::launchWifi() {
+  startActivityForResult(
+      std::make_unique<WifiSelectionActivity>(renderer, mappedInput),
+      [this](const ActivityResult& result) {
+        if (result.isCancelled) return;
+        auto& wifi = std::get<WifiResult>(result.data);
+        onWifiDone(wifi.connected);
+      });
+}
+// Child calls:
+//   setResult(WifiResult{.connected = true, .ssid = ssid});
+//   finish();
+```
+
+Key differences:
+
+- **`startActivityForResult()`** pushes the current activity onto the stack and launches the child
+- **`setResult()`** stores a typed result on the child activity
+- **`finish()`** signals the manager to pop the child, call the result handler, and resume the parent
+- The parent is never deleted during this process — it's safely stored on the stack
+
+### 4. Update `render()` Signature
+
+The `RenderLock` type changed from `Activity::RenderLock` (inner class) to standalone `RenderLock`:
+
+```cpp
+// BEFORE
+void render(Activity::RenderLock&&) override;
+
+// AFTER
+void render(RenderLock&&) override;
+```
+
+Include `RenderLock.h` if not transitively included via `Activity.h`.
+
+### 5. Update `onEnter()` / `onExit()`
+
+Activities no longer create or destroy render tasks:
+
+```cpp
+// BEFORE
+void MyActivity::onEnter() {
+  Activity::onEnter();       // created render task + logged
+  // ... allocate resources
+  requestUpdate();
+}
+void MyActivity::onExit() {
+  // ... free resources
+  Activity::onExit();        // acquired RenderLock, deleted render task
+}
+
+// AFTER
+void MyActivity::onEnter() {
+  Activity::onEnter();       // just logs
+  // ... allocate resources
+  requestUpdate();
+}
+void MyActivity::onExit() {
+  // ... free resources
+  Activity::onExit();        // just logs
+}
+```
+
+The render task lifecycle is handled entirely by `ActivityManager::begin()`.
+
+### 6. Update `requestUpdate()` Calls
+
+The signature changed to accept an `immediate` flag:
+
+```cpp
+// BEFORE
+void requestUpdate();  // always immediate notification to per-activity render task
+
+// AFTER
+void requestUpdate(bool immediate = false);
+// immediate=false (default): deferred until end of current loop iteration
+// immediate=true: sends notification to render task right away
+```
+
+**When to use `immediate`**: Almost never. Deferred updates are batched — if `loop()` triggers multiple state changes that each call `requestUpdate()`, only one render happens. Use `immediate` only when you need the render to start before the current function returns (e.g., before a blocking network call).
+
+**`requestUpdateAndWait()`**: Blocks the calling task until the render completes. Use sparingly — it's designed for cases where you need the screen to reflect new state before proceeding (e.g., showing "Checking for update..." before calling a network API).
+
+### 7. Remove Stored Navigation Callbacks
+
+Old activities often stored `std::function` callbacks for navigation:
+
+```cpp
+// BEFORE
+class SettingsActivity : public ActivityWithSubactivity {
+  const std::function<void()> goBack;   // stored callback
+  const std::function<void()> goHome;   // stored callback
+public:
+  SettingsActivity(GfxRenderer& r, MappedInputManager& m,
+                   std::function<void()> goBack, std::function<void()> goHome)
+      : ActivityWithSubactivity("Settings", r, m), goBack(goBack), goHome(goHome) {}
+};
+
+// AFTER
+class SettingsActivity : public Activity {
+public:
+  SettingsActivity(GfxRenderer& r, MappedInputManager& m)
+      : Activity("Settings", r, m) {}
+  // Use finish() to go back, activityManager.goHome() to go home
+};
+```
+
+This removes `std::function` overhead (~2-4KB per unique signature) and eliminates lifetime risks from captured `this` pointers.
+
+## Technical Details
+
+### FreeRTOS Task Model
+
+The firmware runs on an ESP32-C3, a single-core RISC-V microcontroller. FreeRTOS provides cooperative and preemptive multitasking on this single core — only one task executes at any moment, and the scheduler switches between tasks at yield points (blocking calls, `vTaskDelay`, `taskYIELD`) or when a tick interrupt promotes a higher-priority task.
+
+There are two tasks relevant to the activity system:
+
+```text
+┌──────────────────────┐     ┌──────────────────────────┐
+│ Main Task            │     │ Render Task              │
+│ (Arduino loop)       │     │ (ActivityManager-owned)   │
+│ Priority: 1          │     │ Priority: 1              │
+│                      │     │                          │
+│ Runs:                │     │ Runs:                    │
+│ - gpio.update()      │     │ - ulTaskNotifyTake()     │
+│ - activity->loop()   │     │   (blocks until notified)│
+│ - pending actions    │     │ - RenderLock (mutex)     │
+│ - sleep/power mgmt   │     │ - activity->render()     │
+│ - requestUpdate →────┼─────┼─► xTaskNotify()          │
+│   (end of loop)      │     │                          │
+└──────────────────────┘     └──────────────────────────┘
+```
+
+Both tasks run at priority 1. Since the ESP32-C3 is single-core, they alternate execution: the main task runs `loop()`, then at the end of the loop iteration, notifies the render task if an update was requested. The render task wakes, acquires the mutex, calls `render()`, releases the mutex, and blocks again.
+
+Do not use `xTaskCreate` inside activities. If you have a use case that seems to require a background task, open a discussion to propose a lifecycle-aware `Worker` abstraction first.
+
+### The Render Mutex and RenderLock
+
+A single FreeRTOS mutex (`renderingMutex`) protects shared state between `loop()` and `render()`. Since these run on different tasks, any state read by `render()` and written by `loop()` must be guarded.
+
+`RenderLock` is an RAII wrapper:
+
+```cpp
+// Standalone class (not tied to any specific activity)
+class RenderLock {
+  bool isLocked = false;
+public:
+  explicit RenderLock();           // acquires activityManager.renderingMutex
+  explicit RenderLock(Activity&);  // same — Activity& param kept for compatibility
+  ~RenderLock();                   // releases mutex if still held
+  void unlock();                   // early release
+};
+```
+
+**Usage patterns:**
+
+```cpp
+// In loop(): protect state mutations that render() reads
+void MyActivity::loop() {
+  if (somethingChanged) {
+    RenderLock lock;
+    state = newState;        // safe — render() can't run while lock is held
+  }
+  requestUpdate();           // trigger render after lock is released
+}
+
+// In render(): lock is passed in, held for duration of render
+void MyActivity::render(RenderLock&&) {
+  // Lock is held — safe to read shared state
+  renderer.clearScreen();
+  renderer.drawText(..., stateString, ...);
+  renderer.displayBuffer();
+  // Lock released when RenderLock destructor runs
+}
+```
+
+**Critical rule**: Never call `requestUpdateAndWait()` while holding a `RenderLock`. The render task needs the mutex to call `render()`, so holding it while waiting for the render to complete is a deadlock:
+
+```text
+Main Task                    Render Task
+──────────                   ───────────
+RenderLock lock;             (blocked on mutex)
+requestUpdateAndWait();
+  → notify render task
+  → block waiting for
+    render to complete        → wakes up
+                              → tries to acquire mutex
+                              → DEADLOCK: main holds mutex,
+                                waits for render; render
+                                waits for mutex
+```
+
+### requestUpdate() vs requestUpdateAndWait()
+
+```text
+requestUpdate(false)          requestUpdate(true)
+─────────────────             ─────────────────
+Sets flag only.               Notifies render task
+Render happens after          immediately.
+loop() returns and            Render may start
+ActivityManager checks        before the calling
+the flag.                     function returns.
+                              (Does NOT wait for
+                              render to complete.)
+
+requestUpdateAndWait()
+──────────────────────
+Notifies render task AND
+blocks calling task until
+render is done. Uses
+FreeRTOS direct-to-task
+notification on the
+caller's task handle.
+```
+
+`requestUpdateAndWait()` flow in detail:
+
+```text
+Calling Task                 Render Task
+────────────                 ───────────
+requestUpdateAndWait()
+  ├─ assert: not render task
+  ├─ assert: not holding RenderLock
+  ├─ store waitingTaskHandle
+  ├─ xTaskNotify(renderTask)  → wakes render task
+  └─ ulTaskNotifyTake() ─┐
+     (blocked)           │    RenderLock lock;
+                         │    activity->render();
+                         │    // render complete
+                         │    taskENTER_CRITICAL
+                         │    waiter = waitingTaskHandle
+                         │    waitingTaskHandle = nullptr
+                         │    taskEXIT_CRITICAL
+                         │    xTaskNotify(waiter) ───┐
+                         │                           │
+  ┌──────────────────────┘                           │
+  │ (woken by notification) ◄────────────────────────┘
+  └─ return
+```
+
+### Activity Lifecycle Under ActivityManager
+
+```text
+activityManager.replaceActivity(make_unique<MyActivity>(...))
+  │
+  ▼
+╔═══════════════════════════════════════════════════╗
+║  pendingAction = Replace                          ║
+║  pendingActivity = MyActivity                     ║
+╚═══════════════════════════════════════════════════╝
+  │
+  ▼ (next loop iteration)
+  ActivityManager::loop()
+  │
+  ├── currentActivity->loop()     // old activity's last loop
+  │
+  ├── process pending action:
+  │   ├── RenderLock lock;
+  │   ├── oldActivity->onExit()   // cleanup under lock
+  │   ├── delete oldActivity
+  │   ├── clear stack
+  │   ├── currentActivity = MyActivity
+  │   ├── lock.unlock()
+  │   └── MyActivity->onEnter()   // init new activity
+  │
+  └── if requestedUpdate:
+      └── notify render task
+```
+
+For push/pop (subactivity) navigation:
+
+```text
+Parent calls: startActivityForResult(make_unique<Child>(...), handler)
+  │
+  ▼
+╔══════════════════════════════════════╗
+║  pendingAction = Push               ║
+║  pendingActivity = Child            ║
+║  parent->resultHandler = handler    ║
+╚══════════════════════════════════════╝
+  │
+  ▼ (next loop iteration)
+  ├── Parent moved to stackActivities[]
+  ├── currentActivity = Child
+  └── Child->onEnter()
+
+        ... child runs ...
+
+Child calls: setResult(MyResult{...}); finish();
+  │
+  ▼
+╔══════════════════════════════════════╗
+║  pendingAction = Pop                ║
+║  child->result = MyResult{...}      ║
+╚══════════════════════════════════════╝
+  │
+  ▼ (next loop iteration)
+  ├── result = child->result
+  ├── Child->onExit(); delete Child
+  ├── currentActivity = Parent (popped from stack)
+  ├── Parent->resultHandler(result)
+  └── requestUpdate()   // automatic re-render for parent
+```
+
+### Common Pitfalls
+
+**Calling `finish()` and continuing to access `this`**: `finish()` sets `pendingAction = Pop` but does not immediately destroy the activity. The activity is destroyed on the next `ActivityManager::loop()` iteration. It's safe to access member variables after `finish()` within the same function, but don't rely on the activity surviving past the current `loop()` call.
+
+**Modifying shared state without `RenderLock`**: If `render()` reads a variable and `loop()` writes it, the write must be under a `RenderLock`. Without it, `render()` could see a half-written value (e.g., a partially updated string or struct).
+
+**Creating background tasks that outlive the activity**: Any FreeRTOS task created in `onEnter()` must be deleted in `onExit()` before the activity is destroyed. The `ActivityManager` does not track or clean up background tasks.
+
+**Holding `RenderLock` across blocking calls**: The render task is blocked on the mutex while you hold the lock. Keep critical sections short — acquire, mutate state, release, then do blocking work.
+
+```cpp
+// WRONG — blocks render for the entire network call
+void MyActivity::doNetworkStuff() {
+  RenderLock lock;
+  state = LOADING;
+  auto result = http.get(url);  // blocks for seconds with lock held
+  state = DONE;
+}
+
+// CORRECT — release lock before blocking
+void MyActivity::doNetworkStuff() {
+  {
+    RenderLock lock;
+    state = LOADING;
+  }
+  requestUpdate(true);           // render "Loading..." immediately, before we block
+  auto result = http.get(url);   // lock is not held
+  {
+    RenderLock lock;
+    state = DONE;
+  }
+  requestUpdate();
+}
+```

docs/contributing/README.md

@@ -0,0 +1,12 @@
+# Contributing Docs
+
+This section is a lightweight contributor guide for CrossPoint Reader.
+It is written for software developers who may be new to embedded development.
+
+- [Getting Started](./getting-started.md)
+- [Architecture Overview](./architecture.md)
+- [Development Workflow](./development-workflow.md)
+- [Testing and Debugging](./testing-debugging.md)
+- [Touch and UI Development](./touch-and-ui.md)
+
+If you are new, start with [Getting Started](./getting-started.md).

docs/contributing/architecture.md

@@ -0,0 +1,216 @@
+# Architecture Overview
+
+CrossPoint is firmware for the Xteink X4 (unaffiliated with Xteink), built with PlatformIO targeting the ESP32-C3 microcontroller.
+
+At a high level, it is firmware that uses an activity-driven application architecture loop with persistent settings/state, SD-card-first caching, and a rendering pipeline optimized for e-ink constraints.
+
+## System at a glance
+
+```mermaid
+graph TD
+    A[Hardware: ESP32-C3 + SD + E-ink + Buttons] --> B[freeink-sdk]
+    B --> C[lib/hal wrappers]
+    C --> D[src/main.cpp runtime loop]
+    D --> E[Activities layer]
+    D --> F[State and settings]
+    E --> G[Reader flows]
+    E --> H[Home/Library/Settings flows]
+    E --> I[Network/Web server flows]
+    G --> J[lib/Epub parsing + layout + hyphenation]
+    J --> K[SD cache in .crosspoint]
+    E --> L[GfxRenderer]
+    L --> M[E-ink display buffer]
+```
+
+## Runtime lifecycle
+
+Primary entry point is `src/main.cpp`.
+
+```mermaid
+flowchart TD
+    A[Boot] --> B[Init GPIO and optional serial]
+    B --> C[Init SD storage]
+    C --> D[Load settings and app state]
+    D --> E[Init display and fonts]
+    E --> F{Resume reader?}
+    F -->|No| G[Enter Home activity]
+    F -->|Yes| H[Enter Reader activity]
+    G --> I[Main loop]
+    H --> I
+    I --> J[Poll input and run current activity]
+    J --> K{Sleep condition met?}
+    K -->|No| I
+    K -->|Yes| L[Persist state and enter deep sleep]
+```
+
+In each loop iteration, the firmware updates input, runs the active activity, handles auto-sleep/power behavior, and applies a short delay policy to balance responsiveness and power.
+
+## Activity model
+
+Activities are screen-level controllers deriving from `src/activities/Activity.h`.
+Some flows use `src/activities/ActivityWithSubactivity.h` to host nested activities.
+
+- `onEnter()` and `onExit()` manage setup/teardown
+- `loop()` handles per-frame behavior
+- `skipLoopDelay()` and `preventAutoSleep()` are used by long-running flows (for example web server mode)
+
+Top-level activity groups:
+
+- `src/activities/home/`: home and library navigation
+- `src/activities/reader/`: EPUB/XTC/TXT reading flows
+- `src/activities/settings/`: settings menus and configuration
+- `src/activities/network/`: Wi-Fi selection, AP/STA mode, file transfer server
+- `src/activities/boot_sleep/`: boot and sleep transitions
+
+## Reader and content pipeline
+
+Reader orchestration starts in `src/activities/reader/ReaderActivity.h` and dispatches to format-specific readers.
+EPUB processing is implemented in `lib/Epub/`.
+
+```mermaid
+flowchart LR
+    A[Select book] --> B[ReaderActivity]
+    B --> C{Format}
+    C -->|EPUB| D[lib/Epub/Epub]
+    C -->|XTC| E[lib/Xtc reader]
+    C -->|TXT| F[lib/Txt reader]
+    D --> G[Parse OPF/TOC and collect CSS refs]
+    G --> H[Build/load book.bin and css_rules.cache]
+    H --> I[Layout pages/sections]
+    I --> J[Write section cache]
+    J --> K[Render current page via GfxRenderer]
+```
+
+Why caching matters:
+
+- RAM is limited on ESP32-C3, so expensive parsed/layout data is persisted to SD
+- repeat opens/page navigation can reuse cached data instead of full reparsing
+
+## Reader internals call graph
+
+This diagram zooms into the EPUB path to show the main control and data flow from activity entry to on-screen draw.
+
+```mermaid
+flowchart TD
+    A[ReaderActivity onEnter] --> B{File type}
+    B -->|EPUB| C[Create Epub object]
+    B -->|XTC/TXT| Z[Use format-specific reader]
+
+    C --> D[Epub load]
+    D --> E[Locate container and OPF]
+    E --> F[Build or load BookMetadataCache]
+    F --> G[Load TOC and spine]
+    G --> H[Load CSS cache or parse manifest/base-dir CSS]
+
+    H --> I[EpubReaderActivity]
+    I --> J{Section cache exists for current settings?}
+    J -->|Yes| K[Read section bin from SD cache]
+    J -->|No| L[Parse chapter HTML and layout text]
+    L --> M[Apply typography settings and hyphenation]
+    M --> N[Write section cache bin]
+
+    K --> O[Build page model]
+    N --> O
+    O --> P[GfxRenderer draw calls]
+    P --> Q[HAL display framebuffer update]
+    Q --> R[E-ink refresh policy]
+
+    S[SETTINGS singleton] -. influences .-> J
+    S -. influences .-> M
+    T[APP_STATE singleton] -. persists .-> U[Reading progress and resume context]
+    U -. used by .-> I
+```
+
+Notes:
+
+- CSS files are collected from the OPF manifest and, when needed, discovered by
+  streaming ZIP paths under the OPF content base directory; the firmware avoids
+  preloading the full ZIP central directory for large books.
+- "section cache exists" depends on cache-busting parameters such as font,
+  viewport size, paragraph alignment, hyphenation, embedded CSS, image rendering,
+  and Focus Reading settings
+- rendering favors reusing precomputed layout data to keep page turns responsive on constrained hardware
+- progress/session state is persisted so the reader can reopen at the last position after reboot/sleep
+
+## State and persistence
+
+Two singletons are central:
+
+- `src/CrossPointSettings.h` (`SETTINGS`): user preferences and behavior flags
+- `src/CrossPointState.h` (`APP_STATE`): runtime/session state such as current book and sleep context
+
+Typical persisted areas on SD:
+
+```text
+/.crosspoint/
+  epub_<hash>/
+    book.bin
+    css_rules.cache
+    progress.bin
+    cover.bmp
+    sections/*.bin
+    img_* cache files
+  settings.json
+  state.json
+```
+
+`sections/*.bin` contains rendered pages plus anchor, paragraph, and list-item
+lookup tables used for TOC/footnote jumps and KOReader sync refinement. For
+binary cache formats, see `docs/file-formats.md`.
+
+## Networking architecture
+
+Network file transfer is controlled by `src/activities/network/CrossPointWebServerActivity.h` and served by `src/network/CrossPointWebServer.h`.
+
+Modes:
+
+- STA: join existing Wi-Fi network
+- AP: create hotspot
+- Calibre Wireless: STA flow specialized for Calibre plugin uploads
+
+Server behavior:
+
+- HTTP server on port 80
+- WebSocket upload server on port 81
+- WebDAV handler on the HTTP server
+- UDP discovery listener for upload clients
+- file operations backed by SD storage
+- browser APIs for file management, settings, fonts, OPDS servers, and saved Wi-Fi networks
+- activity requests faster loop responsiveness while server is running
+
+Endpoint reference: `docs/webserver-endpoints.md`.
+
+## Build-time generated assets
+
+Some sources are generated and should not be edited manually.
+
+- `scripts/build_html.py` generates `src/network/html/*.generated.h` from HTML files
+- `scripts/gen_i18n.py` generates `lib/I18n/I18nKeys.h`, `I18nStrings.h`, and `I18nStrings.cpp`
+- `scripts/generate_hyphenation_trie.py` generates hyphenation headers under `lib/Epub/Epub/hyphenation/generated/`
+
+When editing related source assets, regenerate via normal build steps/scripts.
+
+## Key directories
+
+- `src/`: app orchestration, settings/state, and activity implementations
+- `src/network/`: web server and OTA/update networking
+- `src/components/`: theming and shared UI components
+- `lib/hal/`: hardware abstraction wrappers around freeink-sdk
+- `lib/Epub/`: EPUB parser, layout, CSS handling, and hyphenation
+- `lib/`: supporting libraries (fonts, text, filesystem helpers, etc.)
+- `freeink-sdk/`: hardware SDK submodule (display, input, storage, battery). Docs: https://freeink.org/docs
+- `docs/`: user and technical documentation
+
+## Embedded constraints that shape design
+
+- constrained RAM drives SD-first caching and careful allocations
+- e-ink refresh cost drives render/update batching choices
+- main loop responsiveness matters for input, power handling, and watchdog safety
+- background/network flows must cooperate with sleep and loop timing logic
+
+## Scope guardrails
+
+Before implementing larger ideas, check:
+
+- [SCOPE.md](../../SCOPE.md)
+- [GOVERNANCE.md](../../GOVERNANCE.md)

docs/contributing/development-workflow.md

@@ -0,0 +1,44 @@
+# Development Workflow
+
+This page defines the expected local workflow before opening a pull request.
+
+## 1) Fork and create a focused branch
+
+- Fork the repository to your own GitHub account
+- Clone your fork locally and add the upstream repository if needed
+- Enable repo hooks once per clone: `git config core.hooksPath .githooks && chmod +x .githooks/pre-commit`
+
+- Branch from `master`
+- Keep each PR focused on one fix or feature area
+
+## 2) Implement with scope in mind
+
+- Confirm your idea is in project scope: [SCOPE.md](../../SCOPE.md)
+- Prefer incremental changes over broad refactors
+
+## 3) Run local checks
+
+```sh
+./bin/clang-format-fix
+pio check --fail-on-defect low --fail-on-defect medium --fail-on-defect high
+pio run
+```
+
+CI enforces formatting, static analysis, and build checks.
+Use clang-format 21+ locally to match CI.
+If `clang-format` is missing or too old locally, see [Getting Started](./getting-started.md).
+
+## 4) Open the PR
+
+- Use a semantic title (example: `fix: avoid crash when opening malformed epub`)
+- Fill out `.github/PULL_REQUEST_TEMPLATE.md`
+- Describe the problem, approach, and any tradeoffs
+- Include reproduction and verification steps for bug fixes
+
+## 5) Review etiquette
+
+- Be explicit and concise in responses
+- Keep discussions technical and respectful
+- Assume good intent and focus on code-level feedback
+
+For community expectations, see [GOVERNANCE.md](../../GOVERNANCE.md).

docs/contributing/getting-started.md

@@ -0,0 +1,87 @@
+# Getting Started
+
+This guide helps you build and run CrossPoint locally.
+
+## Prerequisites
+
+- PlatformIO Core (`pio`) or VS Code + PlatformIO IDE
+- Python 3.8+
+- `clang-format` 21+ in your `PATH` (CI uses clang-format 21)
+- USB-C cable
+- Xteink X4 device for hardware testing
+
+If `./bin/clang-format-fix` fails with either of these errors, install clang-format 21:
+
+- `clang-format: No such file or directory`
+- `.clang-format: error: unknown key 'AlignFunctionDeclarations'`
+
+Examples:
+
+```sh
+# Debian/Ubuntu (try this first)
+sudo apt-get update && sudo apt-get install -y clang-format-21
+
+# If the package is unavailable, add LLVM apt repo and retry
+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
+
+# macOS (Homebrew)
+brew install clang-format
+```
+
+Then verify:
+
+```sh
+clang-format-21 --version
+```
+
+The reported major version must be 21 or newer.
+
+## Clone and initialize
+
+```sh
+git clone --recursive https://github.com/crosspoint-reader/crosspoint-reader
+cd crosspoint-reader
+```
+
+If you already cloned without submodules:
+
+```sh
+git submodule update --init --recursive
+```
+
+Enable the repository-managed Git hooks (required once per clone):
+
+```sh
+git config core.hooksPath .githooks
+chmod +x .githooks/pre-commit
+```
+
+## Build
+
+```sh
+pio run
+```
+
+## Flash
+
+```sh
+pio run --target upload
+```
+
+## First checks before opening a PR
+
+```sh
+./bin/clang-format-fix
+pio check --fail-on-defect low --fail-on-defect medium --fail-on-defect high
+pio run
+```
+
+## What to read next
+
+- [Architecture Overview](./architecture.md)
+- [Development Workflow](./development-workflow.md)
+- [Testing and Debugging](./testing-debugging.md)

docs/contributing/testing-debugging.md

@@ -0,0 +1,48 @@
+# Testing and Debugging
+
+CrossPoint runs on real hardware, so debugging usually combines local build checks and on-device logs.
+
+## Local checks
+
+Make sure `clang-format` 21+ is installed and available in `PATH` before running the formatting step.
+If needed, see [Getting Started](./getting-started.md).
+
+```sh
+./bin/clang-format-fix
+pio check --fail-on-defect low --fail-on-defect medium --fail-on-defect high
+pio run
+```
+
+## Flash and monitor
+
+Flash firmware:
+
+```sh
+pio run --target upload
+```
+
+Open serial monitor:
+
+```sh
+pio device monitor
+```
+
+Optional enhanced monitor:
+
+```sh
+python3 -m pip install pyserial colorama matplotlib
+python3 scripts/debugging_monitor.py
+```
+
+## Useful bug report contents
+
+- Firmware version and build environment
+- Exact steps to reproduce
+- Expected vs actual behavior
+- Serial logs from boot through failure
+- Whether issue reproduces after clearing `.crosspoint/` cache on SD card
+
+## Common troubleshooting references
+
+- [User Guide troubleshooting section](../../USER_GUIDE.md#7-troubleshooting-issues--escaping-bootloop)
+- [Webserver troubleshooting](../troubleshooting.md)

docs/contributing/touch-and-ui.md

@@ -0,0 +1,221 @@
+# Touch and UI Development
+
+CrossPoint now runs on touch devices (Seeed Sticky, M5Paper, LilyGo T5) alongside the button-only Xteink X3/X4. Every screen must work with both input styles. There are two supported ways to get there:
+
+1. **New screens: build them with FreeInkUI components.** Touch hit-testing, tap highlighting, long-press, and button focus navigation come with the component; you never hand-roll coordinate math.
+2. **Existing screens and in-flight features: use the MappedInputManager touch bridge.** A small set of helpers adds tap/hold/swipe support to hand-rolled rendering without restructuring the activity.
+
+If you are starting a new activity, use FreeInkUI. If you have a feature branch with a hand-rolled screen already working on buttons, use the bridge; do not rewrite mid-flight.
+
+---
+
+## Path 1: New screens with FreeInkUI
+
+FreeInkUI (`freeink-sdk/libs/ui/FreeInkUI`, namespace `freeink::ui`) is an immediate-mode component library. The core idea:
+
+- While a component renders, it registers its tappable areas ("hit rects") into the frame's interaction buffer via `Frame::hit(rect, action, value, inputMask, state)`.
+- Each loop you build an `InputSnapshot` from the input manager and route it against that buffer. If a tap (or mapped button press) lands in a registered rect, the routed `ActionEvent` tells you which action fired and with what value.
+- Components query `frame.stateFor(action, value)` while painting, so touch-down highlight and focus states render correctly without any per-activity code.
+
+You get touch, hold highlighting, long-press, minimum touch-target sizing, and orientation-aware coordinates for free. The same action IDs fire from physical buttons, so one code path serves both input styles.
+
+### Component inventory
+
+All under `freeink-sdk/libs/ui/FreeInkUI/include/components/`:
+
+| Category | Components |
+|---|---|
+| Controls | `button`, `checkbox`, `slider`, `progress-bar`, `header` |
+| Lists | `list` (virtualized), `table`, `dropdown`, `radio-group`, `setting-row`, `toggle-row`, `stepper-row` |
+| Keyboard | `keyboard` (QWERTY/AZERTY/QWERTZ/ES layouts), `key-grid` |
+| Overlays | `popup`, `option-dialog`, `context-menu`, `message-panel`, `toast` |
+| Bars | `status-bar`, `tab-bar`, `reader-chrome`, `battery-indicator`, `gesture-bar`, `tap-zones` |
+| Media | `book-card`, `cover-grid`, `cover-carousel`, `metric-card` |
+| Text | `text-field`, `text-area` |
+
+### Integration skeleton
+
+The in-tree reference is [`src/activities/util/KeyboardEntryActivity.cpp`](../../src/activities/util/KeyboardEntryActivity.cpp); it drives the FreeInkUI keyboard component inside a normal Activity. The shape:
+
+```cpp
+#include <FreeInkUIGfxRenderer.h>
+namespace fui = freeink::ui;
+
+// Render step: draw the component and (re)register its hit rects.
+fui::GfxRendererTarget target(renderer);           // adapts GfxRenderer to FreeInkUI's DrawTarget
+target.setFont(fui::GfxRendererTarget::FONT_BODY, UI_12_FONT_ID);
+const fui::DeviceContext device = target.deviceContext();  // orientation, safe area, touch sizing
+
+fui::Frame<48> frame(target, device, fui::InputSnapshot{}, interactions);  // 48 = max hit rects
+fui::KeyboardProps props;
+props.layout = &currentLayout();
+props.keyAction = ACTION_KEY;                      // one action id; the key is the event value
+props.inputMask = fui::InputTouch | fui::InputLongPress;
+fui::keyboard(frame, kbRect, props);               // draws AND registers hit rects
+```
+
+```cpp
+// Input step (each loop): feed touch state, act on routed events.
+int tx, ty, tapX, tapY, hx, hy;
+const bool pressedDown = mappedInput.wasScreenTouchDown(tx, ty);
+const bool tapped      = mappedInput.wasScreenTapped(tapX, tapY);
+const bool inContact   = mappedInput.isScreenTouchHeld(hx, hy);
+
+const auto result = touchRouter.update(interactions, pressedDown, tx, ty,
+                                       tapped, tapX, tapY, inContact, millis());
+if (result.event) {
+  activateValue(result.event.value, result.event.longPress);
+  requestUpdate();
+} else if (result.activeChanged) {
+  requestUpdate();  // repaint touch-down highlight
+}
+```
+
+Notes:
+
+- `Frame<N>` is templated on the max number of hit rects; the buffer is stack/static, no heap.
+- `fui::TouchHoldRouter` (see `components/keyboard/keyboard.h`) synthesizes long-press while the finger is still down and swallows the eventual release. Use it whenever a component distinguishes tap from long-press.
+- For simpler screens without long-press, `FreeInkApp` / `Screen<N>` (`FreeInkApp.h`) is the ergonomic layer: it owns the interaction buffer, offers a top-to-bottom builder (`takeTop`, footer helpers, etc.), and its `render(input)` call routes the snapshot and dispatches registered action callbacks in one step. `snapshotFrom(input, device)` in `FreeInkUIInputManager.h` builds the `InputSnapshot` with orientation-aware touch mapping.
+- Everything stays allocation-free and works on the button-only devices unchanged: physical buttons route through the same interaction table via each hit rect's `inputMask`.
+
+---
+
+## Path 2: Adding touch to existing hand-rolled screens
+
+For activities that draw their own rows, menus, and buttons, `MappedInputManager` ([src/MappedInputManager.h](../../src/MappedInputManager.h)) exposes bridge helpers. They all return **logical screen coordinates** (orientation already applied via `GfxRenderer::tapToLogical`); never touch raw normalized panel coordinates or the SDK `InputManager` directly.
+
+| Helper | Use for |
+|---|---|
+| `wasScreenTapped(x, y)` | A completed tap (press + release), with logical coords |
+| `wasScreenTouchDown(x, y)` | Touch-down (held > 90 ms, not yet released): draw selection highlight |
+| `isScreenTouchHeld(x, y)` | Live contact position while the finger is down (drag tracking) |
+| `wasTapInRect(x, y, w, h)` | One-off hit test on a rectangle (a single button, a banner) |
+| `wasListItemTapped(index, count, selected, listTop, listHeight, hasSubtitle)` | Taps on a standard UITheme list; does the row/paging math for you |
+| `wasListItemTouchedDown(...)` | Same geometry, touch-down phase (highlight before activate) |
+| `rowTouch(row, top, rowStep, rowCount, xStart, xEnd, rowHeight)` | Any custom band of equal-height rows; returns `RowTouch::None/Down/Tap` |
+| `colTouch(col, left, colStep, colCount, yStart, yEnd, colWidth)` | Horizontal button bands (dialogs, prompts) |
+| `wasSwipe()` | Raw swipe direction if you need one beyond the global gestures |
+| `hasTouch()` | True when the device has a touch panel (rarely needed; helpers simply never fire without one) |
+
+### Pattern A: standard themed list
+
+One call per loop; UITheme owns the row geometry ([EpubReaderBookmarksActivity.cpp:123](../../src/activities/reader/EpubReaderBookmarksActivity.cpp)):
+
+```cpp
+int tapped = -1;
+if (mappedInput.wasListItemTapped(tapped, bookmarks.size(), selectorIndex, listY, listHeight, true)) {
+  selectorIndex = tapped;
+  openBookmark();
+  return;
+}
+```
+
+### Pattern B: custom rows with hold highlight
+
+For non-theme row layouts, use `rowTouch` and distinguish `Down` (highlight) from `Tap` (activate), as in [EpubReaderFootnotesActivity.cpp](../../src/activities/reader/EpubReaderFootnotesActivity.cpp):
+
+```cpp
+int row = -1;
+const auto touch = mappedInput.rowTouch(row, listTop, lineHeight, visibleCount,
+                                        contentX, contentX + contentWidth);
+if (touch != MappedInputManager::RowTouch::None) {
+  const int touched = scrollOffset + row;
+  if (touch == MappedInputManager::RowTouch::Down) {
+    if (selectedIndex != touched) { selectedIndex = touched; requestUpdate(); }
+  } else {  // RowTouch::Tap
+    selectedIndex = touched;
+    activateSelection();
+  }
+  return;
+}
+```
+
+The `Down` state exists because e-ink repaints are slow: highlight on touch-down gives immediate feedback, activation happens on release.
+
+### Global gestures: do not reimplement these
+
+Three gestures are handled once, for every screen. Activities must not add their own edge-swipe handling:
+
+| Gesture | Trigger | Where it is handled |
+|---|---|---|
+| Back | Right-swipe starting in the left 25% of the screen | Folded into `Button::Back`, so the existing `wasPressed(Button::Back)` in your activity already fires |
+| Home | Up-swipe starting in the bottom 14% | `ActivityManager::loop()`; pops to Home (activities can override via `handleHomeGesture()`) |
+| Menu | Down-swipe starting in the top 14% | Activities that have a menu check `wasMenuGesture()` themselves (the reader does this) |
+
+Because the back gesture arrives as `Button::Back`, most button-era activities gain back-swipe support with zero changes. That is the bar to aim for: bridge helpers should make touch an additive layer over the button flow, not a second input state machine.
+
+### Bridge rules
+
+- Handle touch in `loop()` next to the existing button handling, one helper call per interaction zone, and `return` after consuming an event (mirrors the button pattern).
+- Never call the SDK `InputManager` or read GPIO directly; the HAL rule from the main guide applies to touch too.
+- Coordinates from the helpers are logical and orientation-correct on all four rotations; test at least Portrait and one Landscape mode before PR.
+- Nothing to clean up in `onExit()`; the helpers are stateless from the activity's point of view.
+
+---
+
+## Building and testing on non-Xteink devices
+
+Each MCU family is its own binary: X3/X4 are ESP32-C3, Sticky and LilyGo T5 are ESP32-S3, M5Paper v1.1 is a classic ESP32. The Sticky env ships in `platformio.ini` (`pio run -e sticky`). Envs for other devices go in **`platformio.local.ini`**, a gitignored file that PlatformIO merges over `platformio.ini` (see `extra_configs`). Create it next to `platformio.ini`; personal envs, ports, and debug flags live there and never get committed.
+
+Both envs below extend the repo's `[base]`, so they build against the `freeink-sdk` submodule with all the normal deps and scripts.
+
+### M5Paper v1.1 (classic ESP32, IT8951 panel)
+
+```ini
+[env:m5paper_v11]
+extends = base
+board = esp32dev
+board_build.mcu = esp32
+board_build.flash_mode = qio
+; CP2104 UART bridge: 921600 drops out on macOS after the stub baud switch
+upload_speed = 460800
+build_unflags =
+  ${base.build_unflags}
+  ; classic ESP32 has UART serial, not USB CDC; Logging.h keys off these
+  -DARDUINO_USB_MODE=1
+  -DARDUINO_USB_CDC_ON_BOOT=1
+build_flags =
+  ${base.build_flags}
+  -DFREEINK_DEVICE_M5PAPER=1
+  ; the 63KB 540x960 framebuffer lives in PSRAM (FREEINK_FB_PSRAM auto-on)
+  -DBOARD_HAS_PSRAM
+  -DCROSSPOINT_VERSION=\"${crosspoint.version}-m5paper\"
+  -DENABLE_SERIAL_LOG
+  -DLOG_LEVEL=2
+  ; touch-first device: hide front-button hint labels
+  -DCROSSPOINT_SHOW_BUTTON_HINTS=0
+  ; archive-scan-order workaround: without these a full relink drops Wire's i2c symbols
+  -Wl,-u,i2cInit
+  -Wl,-u,i2cSlaveInit
+```
+
+### LilyGo T5 S3 (ESP32-S3, controller-less panel via LovyanGFX)
+
+```ini
+[env:lilygo_t5s3]
+extends = base
+board = esp32-s3-devkitc1-n16r8
+board_build.mcu = esp32s3
+build_flags =
+  ${base.build_flags}
+  -DFREEINK_DEVICE_LILYGO=1
+  ; board injects the parallel-bus pins + PMIC power hooks (BoardT5S3)
+  -DFREEINK_LGFX_EPD_CONFIG=lilygoT5S3LgfxConfig
+  -DCROSSPOINT_VERSION=\"${crosspoint.version}-lilygo\"
+  -DENABLE_SERIAL_LOG
+  -DLOG_LEVEL=2
+  -DCROSSPOINT_SHOW_BUTTON_HINTS=0
+lib_deps =
+  ${base.lib_deps}
+  ; LgfxEpdConfig for the T5 S3 (pins, PCA9535/TPS65185 power sequence)
+  BoardT5S3=symlink://freeink-sdk/libs/hardware/BoardT5S3
+  ; LovyanGFX Panel_EPD drives the controller-less ED047TC1 panel
+  m5stack/M5GFX @ 0.2.20
+```
+
+Then `pio run -e m5paper_v11 -t upload` (or `-e lilygo_t5s3`). Gotchas worth knowing:
+
+- **Flash mode matters.** The M5Paper is `qio`; the X4-family standalone envs need `dio`. A wrong flash-mode header boots into a `partition 0 invalid magic number 0xffff` loop even though esptool verified the write.
+- **One `FREEINK_DEVICE_*` flag per env** selects the board profile (pins, panel, touch controller) from the SDK's `BoardConfig`. See `freeink-sdk/platformio.sample.ini` for reference envs of every supported device.
+- **Serial logs:** `[base]` does not enable logging; without `-DENABLE_SERIAL_LOG` a non-default env prints nothing.
+- No touch hardware on your desk? The X4 build still exercises the same code paths through buttons; touch-specific behavior (tap zones, gestures) needs a real device.

docs/dictionary.md

@@ -0,0 +1,51 @@
+# Dictionary
+
+Look up words while reading an EPUB using an offline StarDict dictionary stored on the SD card.
+
+## Supported Format
+
+The reader supports **StarDict** dictionaries. When searching for dictionaries online, look for "StarDict format" or files with `.dict`, `.idx`, and `.ifo` extensions.
+
+A dictionary folder must contain:
+
+- `.idx` — word index (required, **must be uncompressed** — a `.idx.gz` will not work; decompress it on your computer with `gzip -d` first)
+- `.dict` or `.dict.dz` — definition data (`.dict.dz` is supported as-is; entries are decompressed on the fly during lookup)
+- `.ifo` — metadata (optional)
+
+Not supported: `.syn` synonym files (ignored), dictionaries with 64-bit index offsets (`idxoffsetbits=64` in the `.ifo` — rare, and rejected with an error), and HTML-formatted definitions render as raw markup rather than styled text.
+
+## Setting Up a Dictionary
+
+1. Copy your dictionary folder(s) to `/dictionaries/` on the SD card — one dictionary per folder, e.g. `/dictionaries/webster/webster.idx` + `webster.dict.dz`. A hidden `/.dictionaries/` folder (dot-prefixed) works the same way, for keeping it out of the file browser.
+2. Open **Settings → Reader → Dictionary** on the device.
+3. Select a dictionary from the list, or **None** to disable lookups.
+
+The Dictionary setting only appears when at least one usable dictionary folder exists. Folders containing more than one dictionary (multiple `.idx` stems) are skipped as ambiguous.
+
+## Looking Up a Word
+
+Two ways to start a lookup while reading:
+
+- Open the reader menu (**Confirm**) and choose **Look Up**.
+- Or set **Settings → Controls → Long-press Menu** to "Dictionary", then hold **Confirm** (~0.4s) on the reading page.
+
+One word on the page becomes highlighted:
+
+1. Use **Left/Right** to move between words in reading order, and the side **Up/Down** buttons to jump between lines.
+2. Press **Confirm** to look up the highlighted word.
+3. Press **Back** to return to the reader.
+
+On the very first lookup with a dictionary (and again if the dictionary file changes), the reader shows *"Indexing dictionary…"* while it builds a small `.qidx` sidecar file next to the `.idx`. This takes a few seconds for large dictionaries and makes all subsequent lookups fast. The sidecar can be deleted safely at any time — it will simply be rebuilt.
+
+### How Lookup Works
+
+1. **Direct match** — the word is found as-is (case-insensitive) in the dictionary index. Surrounding punctuation is ignored.
+2. **Stemming** — on a miss, common English word forms are retried automatically: possessives and plurals (`dogs` → `dog`, `stories` → `story`) and verb endings (`walked` → `walk`, `running` → `run`, `making` → `make`).
+3. **Not found** — a short popup appears and you return to word selection.
+
+## The Definition Screen
+
+When a word is found, the definition screen shows the matched headword at the top and the definition text below, with a page counter for long definitions.
+
+- **Left/Right** or side **Up/Down** — previous / next page
+- **Back** — return to word selection

docs/file-formats.md

@@ -1,9 +1,326 @@
 # File Formats
 
+These formats describe the SD-card cache files under `/.crosspoint/epub_<hash>/`.
+All POD fields are written in the ESP32 little-endian representation used by
+`Serialization.h`; strings are length-prefixed UTF-8.
+
 ## `book.bin`
 
-![](./images/file-formats/book-bin.png)
+### Version 7
+
+`book.bin` stores EPUB metadata plus lookup tables for spine and TOC entries.
+The current firmware writes this version from `BookMetadataCache`.
+
+ImHex pattern:
+
+```c++
+import std.mem;
+import std.string;
+import std.core;
+
+#define EXPECTED_VERSION 7
+#define MAX_STRING_LENGTH 65535
+
+struct String {
+    u32 length [[hidden, comment("String byte length")]];
+    if (length > MAX_STRING_LENGTH) {
+        std::warning(std::format("Unusually large string length: {} bytes", length));
+    }
+    char data[length] [[comment("UTF-8 string data")]];
+} [[sealed, format("format_string"), comment("Length-prefixed UTF-8 string")]];
+
+fn format_string(String s) {
+    return s.data;
+};
+
+struct Metadata {
+    String title [[comment("Book title")]];
+    String author [[comment("Book author")]];
+    String language [[comment("Book language code")]];
+    String coverItemHref [[comment("Path to cover image")]];
+    String textReferenceHref [[comment("Path to guided first text reference")]];
+};
+
+struct SpineEntry {
+    String href [[comment("Resource path")]];
+    u32 cumulativeSize [[comment("Cumulative uncompressed spine size through this entry")]];
+    s16 tocIndex [[comment("Index into TOC, or inherited/previous TOC index when no direct entry exists")]];
+};
+
+struct TocEntry {
+    String title [[comment("Chapter/section title")]];
+    String href [[comment("Resource path")]];
+    String anchor [[comment("Fragment identifier")]];
+    u8 level [[comment("Nesting level")]];
+    s16 spineIndex [[comment("Index into spine (-1 if none)")]];
+};
+
+struct BookBin {
+    u8 version;
+    if (version != EXPECTED_VERSION) {
+        std::error(std::format("Unsupported version: {} (expected {})", version, EXPECTED_VERSION));
+    }
+
+    u32 lutOffset [[comment("Offset to lookup tables")]];
+    u16 spineCount;
+    u16 tocCount;
+
+    Metadata metadata;
+
+    u32 currentOffset = $;
+    if (currentOffset != lutOffset) {
+        std::warning(std::format("LUT offset mismatch: expected 0x{:X}, got 0x{:X}", lutOffset, currentOffset));
+    }
+
+    u32 spineLut[spineCount] [[comment("Spine entry offsets")]];
+    u32 tocLut[tocCount] [[comment("TOC entry offsets")]];
+
+    SpineEntry spines[spineCount];
+    TocEntry toc[tocCount];
+};
+
+BookBin book @ 0x00;
+
+u32 fileSize = std::mem::size();
+u32 parsedSize = $;
+if (parsedSize != fileSize) {
+    std::warning(std::format("Unparsed data detected: {} bytes remaining at offset 0x{:X}", fileSize - parsedSize, parsedSize));
+}
+```
 
 ## `section.bin`
 
-![](./images/file-formats/section-bin.png)
+### Version 30
+
+Each file in `sections/*.bin` stores one laid-out spine section. The header is
+also the cache-busting key: if any layout-affecting setting differs from the
+current reader settings, the section is discarded and rebuilt.
+
+Version 30 is binary-identical to version 29. The version was bumped because
+Arabic contextual shaping changed text measurement (`getTextAdvanceX` now
+measures the shaped visual text), so word positions cached by v29 no longer
+match what `drawText` renders.
+
+Version 28 introduced serialized word style bits for underline, strikethrough,
+superscript, and subscript. The format also includes:
+
+- cache-busting fields for paragraph alignment, hyphenation, embedded CSS,
+  image rendering mode, and Focus Reading
+- page offset LUT
+- anchor-to-page map for fragment and footnote navigation
+- paragraph and list-item LUTs used by KOReader sync page refinement
+- optional per-word Focus Reading split metadata
+- per-page footnote entries
+- serialized word style bits for underline, strikethrough, superscript, and
+  subscript
+- flat TextBlock word storage (v29): per-word arrays plus one shared
+  NUL-terminated text blob, replacing v28's length-prefixed word strings. The
+  on-disk order mirrors the in-RAM arena so the firmware reads a whole block
+  payload with a single allocation and a single SD read
+
+ImHex pattern:
+
+```c++
+import std.mem;
+import std.string;
+import std.core;
+
+#define EXPECTED_VERSION 30
+#define MAX_STRING_LENGTH 65535
+#define FOOTNOTE_NUMBER_LEN 32
+#define FOOTNOTE_HREF_LEN 96
+
+struct String {
+    u32 length [[hidden, comment("String byte length")]];
+    if (length > MAX_STRING_LENGTH) {
+        std::warning(std::format("Unusually large string length: {} bytes", length));
+    }
+    char data[length] [[comment("UTF-8 string data")]];
+} [[sealed, format("format_string"), comment("Length-prefixed UTF-8 string")]];
+
+fn format_string(String s) {
+    return s.data;
+};
+
+enum PageElementTag : u8 {
+    TAG_PageLine = 1,
+    TAG_PageImage = 2,
+    TAG_PageHorizontalRule = 3
+};
+
+enum WordStyle : u8 {
+    REGULAR = 0,
+    BOLD = 1,
+    ITALIC = 2,
+    BOLD_ITALIC = 3,
+    UNDERLINE = 4,
+    STRIKETHROUGH = 8,
+    SUP = 16,
+    SUB = 32
+};
+
+enum TextAlign : u8 {
+    JUSTIFIED = 0,
+    LEFT_ALIGN = 1,
+    CENTER_ALIGN = 2,
+    RIGHT_ALIGN = 3,
+    NONE = 4
+};
+
+struct BlockStyle {
+    TextAlign alignment;
+    bool textAlignDefined;
+    s16 marginTop;
+    s16 marginBottom;
+    s16 marginLeft;
+    s16 marginRight;
+    s16 paddingTop;
+    s16 paddingBottom;
+    s16 paddingLeft;
+    s16 paddingRight;
+    s16 textIndent;
+    bool textIndentDefined;
+    bool isRtl;
+    bool directionDefined;
+};
+
+struct TextBlock {
+    u16 wordCount;
+    u8 hasFocus;
+    u16 textBytes [[comment("Total size of text[], including one NUL per word")]];
+
+    if (wordCount > 0) {
+        u16 textOff[wordCount] [[comment("Byte offset of word i's text within text[]")]];
+        s16 wordXPos[wordCount];
+        if (hasFocus != 0) {
+            u16 wordFocusSuffixX[wordCount] [[comment("Suffix x offset from word start")]];
+        }
+        WordStyle wordStyle[wordCount];
+        if (hasFocus != 0) {
+            u8 wordFocusBoundary[wordCount] [[comment("UTF-8 byte boundary between bold prefix and suffix")]];
+        }
+        char text[textBytes] [[comment("All words back to back, each NUL-terminated")]];
+    }
+
+    BlockStyle blockStyle;
+};
+
+struct ImageBlock {
+    String imagePath;
+    s16 width;
+    s16 height;
+};
+
+struct PageLine {
+    s16 xPos;
+    s16 yPos;
+    TextBlock block;
+};
+
+struct PageImage {
+    s16 xPos;
+    s16 yPos;
+    ImageBlock image;
+};
+
+struct PageHorizontalRule {
+    s16 xPos;
+    s16 yPos;
+    u16 width;
+    u8 thickness;
+};
+
+struct PageElement {
+    PageElementTag pageElementType;
+    if (pageElementType == TAG_PageLine) {
+        PageLine pageLine [[inline]];
+    } else if (pageElementType == TAG_PageImage) {
+        PageImage pageImage [[inline]];
+    } else if (pageElementType == TAG_PageHorizontalRule) {
+        PageHorizontalRule horizontalRule [[inline]];
+    } else {
+        std::error(std::format("Unknown page element type: {}", pageElementType));
+    }
+};
+
+struct FootnoteEntry {
+    char number[FOOTNOTE_NUMBER_LEN];
+    char href[FOOTNOTE_HREF_LEN];
+};
+
+struct Page {
+    u16 elementCount;
+    PageElement elements[elementCount] [[inline]];
+
+    u16 footnoteCount;
+    FootnoteEntry footnotes[footnoteCount];
+};
+
+struct AnchorEntry {
+    String anchor;
+    u16 page;
+};
+
+struct AnchorMap {
+    u16 count;
+    AnchorEntry entries[count];
+};
+
+struct ParagraphLut {
+    u16 count;
+    u16 paragraphIndex[count];
+};
+
+struct SectionBin {
+    u8 version;
+    if (version != EXPECTED_VERSION) {
+        std::error(std::format("Unsupported version: {} (expected {})", version, EXPECTED_VERSION));
+    }
+
+    s32 fontId;
+    float lineCompression;
+    bool extraParagraphSpacing;
+    u8 paragraphAlignment;
+    u16 viewportWidth;
+    u16 viewportHeight;
+    bool hyphenationEnabled;
+    bool embeddedStyle;
+    u8 imageRendering;
+    bool focusReadingEnabled;
+
+    u16 pageCount;
+    u32 pageLutOffset;
+    u32 anchorMapOffset;
+    u32 paragraphLutOffset;
+    u32 listItemLutOffset;
+
+    Page pages[pageCount];
+
+    u32 currentOffset = $;
+    if (currentOffset != pageLutOffset) {
+        std::warning(std::format("Page LUT offset mismatch: expected 0x{:X}, got 0x{:X}", pageLutOffset, currentOffset));
+    }
+
+    u32 pageLut[pageCount] [[comment("Page data offsets")]];
+
+    if (anchorMapOffset != 0) {
+        AnchorMap anchorMap @ anchorMapOffset;
+    }
+
+    if (paragraphLutOffset != 0) {
+        ParagraphLut paragraphLut @ paragraphLutOffset;
+    }
+
+    if (listItemLutOffset != 0 && paragraphLutOffset != 0) {
+        u16 listItemIndex[paragraphLut.count] @ listItemLutOffset;
+    }
+};
+
+SectionBin section @ 0x00;
+
+u32 fileSize = std::mem::size();
+u32 parsedSize = $;
+if (parsedSize != fileSize) {
+    std::warning(std::format("Unparsed data detected: {} bytes remaining at offset 0x{:X}", fileSize - parsedSize, parsedSize));
+}
+```

docs/focus-reading.md

@@ -0,0 +1,33 @@
+# Focus Reading
+
+Focus Reading is a reading aid that bolds the first portion of each word, guiding your eyes to natural fixation points and helping you read faster with less effort. Some readers — particularly those with ADHD — find it helps them stay engaged with the text and reduces mind-wandering. It is inspired by the Bionic Reading technique.
+
+<img src="./images/focus-reading/focus-reading.jpg" height="500" alt="Comparison of the same page with and without Focus Reading enabled" />
+
+*Left: Focus Reading off. Right: Focus Reading on. Both using Literata.*
+
+## Enabling Focus Reading
+
+1. Open **Settings > Reader**
+2. Toggle **Focus Reading** on
+
+Toggling the setting invalidates affected EPUB section caches for the current layout, the same as changing font settings. Sections are rebuilt on demand, then page turns proceed as normal. No changes are made to your EPUB files.
+
+## Examples
+
+<img src="./images/focus-reading/focus-reading-notoserif.jpg" height="500" alt="Focus Reading with Noto Serif font" />
+
+*Focus Reading with Noto Serif font*
+
+<img src="./images/focus-reading/focus-reading-merriweather.jpg" height="500" alt="Focus Reading with Merriweather font" />
+
+*Focus Reading with Merriweather font*
+
+<img src="./images/focus-reading/focus-reading-atkinson.jpg" height="500" alt="Focus Reading with Atkinson Hyperlegible Next font" />
+
+*Focus Reading with Atkinson Hyperlegible Next font*
+
+## Notes
+
+- Focus Reading only applies to regular body text. Already-bold text (headings, emphasis) is left unchanged.
+- The setting is per-device, not per-book — it applies to all books while enabled.

docs/hyphenation-trie-format.md

@@ -0,0 +1,53 @@
+# Hypher Binary Tries
+
+CrossPoint embeds the exact binary automata produced by
+[Typst's `hypher`](https://github.com/typst/hypher). 
+
+## File layout
+
+Each `.bin` blob is a single self-contained automaton:
+
+```
+uint32_t root_addr_be;  // big-endian offset of the root node
+uint8_t  levels[];      // shared "levels" tape (dist/score pairs)
+uint8_t  nodes[];       // node records packed back-to-back
+```
+
+The size of the `levels` tape is implicit. Individual nodes reference slices
+inside that tape via 12-bit offsets, so no additional pointers are required.
+
+### Node encoding
+
+Every node starts with a single control byte:
+
+- Bit 7 – set when the node stores scores (`levels`).
+- Bits 5-6 – stride of the target deltas (1, 2, or 3 bytes, big-endian).
+- Bits 0-4 – transition count (values ≥ 31 spill into an extra byte).
+
+If the `levels` flag is set, two more bytes follow. Together they encode a
+12-bit offset into the global `levels` tape and a 4-bit length. Each byte in the
+levels tape packs a distance/score pair as `dist * 10 + score`, where `dist`
+counts how many UTF-8 bytes we advanced since the previous digit.
+
+After the optional levels header come the transition labels (one byte per edge)
+followed by the signed target deltas. Targets are stored as relative offsets
+from the current node address. Deltas up to ±128 fit in a single byte, larger
+distances grow to 2 or 3 bytes. The runtime walks the transitions with a simple
+linear scan and materializes the absolute address by adding the decoded delta
+to the current node’s base.
+
+## Embedding blobs into the firmware
+
+The helper script `scripts/generate_hyphenation_trie.py` acts as a thin
+wrapper: it reads the hypher-generated `.bin` files, formats them as `constexpr`
+byte arrays, and emits headers under
+`lib/Epub/Epub/hyphenation/generated/`. Each header defines the raw data plus a
+`SerializedHyphenationPatterns` descriptor so the reader can keep the automaton
+in flash.
+
+A convenient script `update_hyphenation.sh` is used to update all languages.
+To use it, run:
+
+```sh
+./scripts/update_hyphenation.sh
+```

docs/i18n.md

@@ -0,0 +1,260 @@
+# Internationalization (I18N)
+
+This guide explains the multi-language support system in CrossPoint Reader.
+
+## Supported Languages
+
+- English
+- Español
+- Français
+- Deutsch
+- Čeština
+- Português (Brasil)
+- Русский
+- Svenska
+- Română
+- Català
+- Українська
+- Беларуская
+- Italiano
+- Polski
+- Suomi
+- Dansk
+- Nederlands
+- Türkçe
+- Қазақша
+- Magyar
+- Lietuvių
+- Slovenščina
+- Valencià
+- עברית
+
+---
+
+
+## For Developers
+
+### Translation System Architecture
+
+The I18N system uses **per-language YAML files** to maintain translations and a Python script to generate C++ code:
+
+```
+lib/I18n/
+├── translations/                # One YAML file per language
+│   ├── english.yaml
+│   ├── spanish.yaml
+│   ├── french.yaml
+│   └── ...
+├── I18n.h
+├── I18n.cpp
+├── I18nKeys.h                   # Enums (auto-generated)
+├── I18nStrings.h                # String array declarations (auto-generated)
+└── I18nStrings.cpp              # String array definitions (auto-generated)
+
+scripts/
+└── gen_i18n.py                  # Code generator script
+```
+
+**Key principle:** All translations are managed in the YAML files under `lib/I18n/translations/`. The Python script generates the necessary C++ code automatically.
+
+---
+
+### YAML File Format
+
+Each language has its own file in `lib/I18n/translations/` (e.g. `spanish.yaml`).
+
+A file looks like this:
+
+```yaml
+_language_name: "Español"
+_language_code: "ES"
+_order: "1"
+
+STR_CROSSPOINT: "CrossPoint"
+STR_BOOTING: "BOOTING"
+STR_BROWSE_FILES: "Buscar archivos"
+```
+
+**Metadata keys** (prefixed with `_`):
+- `_language_name` — Native display name shown to the user (e.g. "Français")
+- `_language_code` — C++ enum name (e.g. "FR"). Please use the [ISO Code](https://en.wikipedia.org/wiki/List_of_ISO_639_language_codes) of the language. Must be a valid C++ identifier.
+- `_order` — Controls the position in the Language enum (English is always 0)
+
+**Rules:**
+- Use UTF-8 encoding
+- Every line must follow the format: `KEY: "value"`
+- Keys must be valid C++ identifiers (uppercase, starts with STR_)
+- Keys must be unique within a file
+- String values must be quoted
+- Use `\n` for newlines, `\\` for literal backslashes, `\"` for literal quotes inside values
+
+---
+
+### Adding New Strings
+
+To add a new translatable string:
+
+#### 1. Edit the English YAML file
+
+Add the key to `lib/I18n/translations/english.yaml`:
+
+```yaml
+STR_MY_NEW_STRING: "My New String"
+```
+
+Then add translations in each language file. If a key is missing from a
+language file, the generator will automatically use the English text as a
+fallback (and print a warning).
+
+#### 2. Run the generator script
+
+```bash
+python3 scripts/gen_i18n.py lib/I18n/translations lib/I18n/
+```
+
+This automatically:
+- Fills missing translations from English
+- Updates the `StrId` enum in `I18nKeys.h`
+- Regenerates all language arrays in `I18nStrings.cpp`
+
+#### 3. Use in code
+
+```cpp
+#include <CrossPointSettings.h>
+#include <I18n.h>
+#include <Logging.h>
+
+// Using the tr() macro (recommended)
+renderer.drawText(font, x, y, tr(STR_MY_NEW_STRING));
+
+// Using I18N.get() directly
+const char* text = I18N.get(StrId::STR_MY_NEW_STRING);
+```
+
+**That's it!** No manual array synchronization needed.
+
+---
+
+### Adding a New Language
+
+To add support for a new language (e.g., Italian):
+
+#### 1. Create a new YAML file
+
+Create `lib/I18n/translations/italian.yaml`:
+
+```yaml
+_language_name: "Italiano"
+_language_code: "IT"
+_order: "7"
+
+STR_CROSSPOINT: "CrossPoint"
+STR_BOOTING: "AVVIO"
+```
+
+You only need to include the strings you have translations for. Missing
+keys will fall back to English automatically.
+
+#### 2. Run the generator
+
+```bash
+python3 scripts/gen_i18n.py lib/I18n/translations lib/I18n/
+```
+
+This automatically updates all necessary code.
+
+---
+
+### Modifying Existing Translations
+
+Simply edit the relevant YAML file and regenerate:
+
+```bash
+python3 scripts/gen_i18n.py lib/I18n/translations lib/I18n/
+```
+
+---
+
+### UTF-8 Encoding
+
+The YAML files use UTF-8 encoding. Special characters are automatically converted to C++ UTF-8 hex sequences by the generator.
+
+---
+
+### I18N API Reference
+
+```cpp
+// === Convenience Macros (Recommended) ===
+
+// tr(id) - Get translated string without StrId:: prefix
+const char* text = tr(STR_SETTINGS_TITLE);
+renderer.drawText(font, x, y, tr(STR_BROWSE_FILES));
+LOG_INF("I18N", "Status: %s", tr(STR_CONNECTED));
+
+// I18N - Shorthand for I18n::getInstance()
+I18N.setLanguage(Language::ES);
+Language lang = I18N.getLanguage();
+
+// === Full API ===
+
+// Get the singleton instance
+I18n& instance = I18n::getInstance();
+
+// Get translated string (three equivalent ways)
+const char* text = tr(STR_SETTINGS_TITLE);              // Macro (recommended)
+const char* text = I18N.get(StrId::STR_SETTINGS_TITLE);   // Direct call
+const char* text = I18N[StrId::STR_SETTINGS_TITLE];       // Operator overload
+
+// Set runtime language
+I18N.setLanguage(Language::ES);
+
+// Get current language
+Language lang = I18N.getLanguage();
+
+// Get character set for font subsetting (static method)
+const char* chars = I18n::getCharacterSet(Language::FR);
+
+// Persist a user language choice
+SETTINGS.language = static_cast<uint8_t>(Language::ES);
+SETTINGS.saveToFile();
+```
+
+---
+
+## File Storage
+
+The selected language is stored with the rest of the device settings in:
+```text
+/.crosspoint/settings.json
+```
+
+The JSON field is `language`, stored as a stable language code string such as
+`"EN"`, `"DE"`, or `"HE"` rather than a raw enum value.
+
+Older firmware versions used:
+```text
+/.crosspoint/language.bin
+```
+
+On load, current firmware migrates that legacy file into `settings.json` and
+renames it to `language.bin.bak`.
+
+---
+
+## Translation Workflow
+
+### For Developers (Adding Features)
+
+1. Add new strings to `lib/I18n/translations/english.yaml`
+2. Run `python3 scripts/gen_i18n.py lib/I18n/translations lib/I18n/`
+3. Use the new `StrId` in your code
+4. Request translations from translators
+
+### For Translators
+
+1. Open the YAML file for your language in `lib/I18n/translations/`
+2. Add or update translations using the format `STR_KEY: "translated text"`
+3. Keep translations concise (E-ink space constraints)
+4. Make sure the file is in UTF-8 encoding
+5. Run `python3 scripts/gen_i18n.py lib/I18n/translations lib/I18n/` to verify
+6. Test on device or submit for review

docs/sd-card-fonts.md

@@ -0,0 +1,126 @@
+# SD Card Fonts
+
+CrossPoint supports loading additional fonts from the SD card, including fonts
+with extended Unicode coverage (CJK, Cyrillic, Greek, etc.).
+
+## Installing Fonts
+
+There are three ways to install fonts:
+
+### Option 1: Download from device (recommended)
+
+1. Connect your CrossPoint reader to Wi-Fi
+2. Go to **Settings > System > Manage Fonts**
+3. Browse available font families and tap to download
+4. Downloaded fonts appear immediately in **Settings > Reader > Font Family**
+
+### Option 2: Upload via web browser
+
+1. Start **File Transfer** and connect through **Join Network** or **Create Hotspot**
+2. Open the web interface URL shown on the reader
+3. Navigate to the **Fonts** tab
+4. Upload `.cpfont` files using the upload form
+
+### Option 3: Manual SD card copy
+
+1. Download font files from the
+   [crosspoint-fonts repository](https://github.com/crosspoint-reader/crosspoint-fonts)
+2. Copy font family folders to one of two locations on your SD card:
+
+   - `/.fonts/` — hidden directory (preferred; keeps the SD root tidy
+     when mounted on a desktop)
+   - `/fonts/` — visible directory (use this if your OS hides dot-files
+     and you'd rather see the folder in your file manager)
+
+   Both roots are always scanned at boot and the results are merged: a
+   family installed in `/fonts/` shows up even when `/.fonts/` also
+   exists, and vice versa. The two roots only collide if the same family
+   name appears in both — in that case the copy in `/.fonts/` wins and
+   the duplicate in `/fonts/` is ignored.
+
+       SD Card Root/
+       ├── .fonts/                     ← Hidden root (preferred)
+       │   └── Literata/
+       │       ├── Literata_12.cpfont
+       │       ├── Literata_14.cpfont
+       │       ├── Literata_16.cpfont
+       │       └── Literata_18.cpfont
+       └── fonts/                      ← Visible root (equally valid)
+           └── Merriweather/
+               ├── Merriweather_12.cpfont
+               └── ...
+
+3. Insert the SD card and power on your CrossPoint reader
+
+## Available Pre-Built Fonts
+
+The current list of pre-built fonts is maintained in the
+[crosspoint-fonts repository](https://github.com/crosspoint-reader/crosspoint-fonts).
+
+## Converting Custom Fonts
+
+To convert your own TrueType/OpenType fonts:
+
+### Prerequisites
+
+    pip install freetype-py fonttools
+
+### Single font (one style)
+
+    python3 lib/EpdFont/scripts/fontconvert_sdcard.py \
+      MyFont-Regular.ttf \
+      --intervals latin-ext \
+      --sizes 12,14,16,18 \
+      --style regular \
+      --name MyFont \
+      --output-dir ./MyFont/
+
+### Multi-style font
+
+    python3 lib/EpdFont/scripts/fontconvert_sdcard.py \
+      --regular MyFont-Regular.ttf \
+      --bold MyFont-Bold.ttf \
+      --italic MyFont-Italic.ttf \
+      --bolditalic MyFont-BoldItalic.ttf \
+      --intervals latin-ext \
+      --sizes 12,14,16,18 \
+      --name MyFont \
+      --output-dir ./MyFont/
+
+### Available Unicode interval presets
+
+| Preset | Coverage |
+|--------|----------|
+| `ascii` | U+0020–U+007E (Basic Latin) |
+| `latin1` | U+0080–U+00FF (Latin-1 Supplement) |
+| `latin-ext` | European languages (Latin + Extended-A/B + punctuation + ligatures) |
+| `greek` | Greek + Extended Greek |
+| `cyrillic` | Cyrillic + Supplement |
+| `hebrew` | Hebrew + Alphabetic Presentation Forms |
+| `georgian` | Georgian + Georgian Supplement |
+| `armenian` | Armenian |
+| `ethiopic` | Ethiopic + Extended |
+| `vietnamese` | Vietnamese subset (ơ/ư and combining marks) |
+| `punctuation` | General punctuation (U+2000–U+206F) |
+| `cjk` | CJK Unified Ideographs + Hiragana + Katakana + Fullwidth |
+| `hangul` | Korean Hangul syllables + Jamo + Compatibility Jamo |
+| `cherokee` | Cherokee (historic + supplement block) |
+| `tifinagh` | Tifinagh |
+| `symbols` | Math, currency, arrows, box-drawing, misc symbols, dingbats |
+| `reading` | Literary fiction coverage: Latin, Greek, Cyrillic, math/symbol blocks, supplemental punctuation, and CJK quote marks |
+| `builtin` | Matches the firmware's built-in font conversion intervals |
+
+Combine presets with commas: `--intervals latin-ext,greek,cyrillic`
+
+You can also specify arbitrary Unicode ranges directly:
+`--intervals latin-ext,(0x2100-0x214F)`
+
+To list all presets with codepoint counts:
+
+    python3 lib/EpdFont/scripts/fontconvert_sdcard.py --list-presets
+
+### Additional options
+
+`--force-autohint` — force FreeType's auto-hinter instead of the font's native hinting (useful when a font's built-in hints produce poor results at small sizes).
+
+Install custom fonts via the web interface or manual SD card copy.

docs/translators.md

@@ -0,0 +1,66 @@
+# Translators
+
+Below is a list of translator credits for languages with known contributors.
+Official UI language support is determined by the YAML files in
+`lib/I18n/translations/`; see [i18n.md](./i18n.md) for the current supported
+language list.
+
+## Contributing
+
+If you'd like to add your name to this list, please open a PR adding yourself and your Github link. Thank you!
+
+## French
+- [Spigaw](https://github.com/Spigaw)
+- [CaptainFrito](https://github.com/CaptainFrito)
+
+## German
+- [DavidOrtmann](https://github.com/DavidOrtmann)
+
+## Czech
+- [brbla](https://github.com/brbla)
+
+## Portuguese (Brazil)
+- [yagofarias](https://github.com/yagofarias)
+
+## Portuguese (Portugal)
+- [victordomingos](https://github.com/victordomingos)
+
+## Italian
+- [andreaturchet](https://github.com/andreaturchet)
+- [fragolinux](https://github.com/fragolinux)
+- [alan0ford](https://github.com/alan0ford)
+
+## Russian
+- [madebyKir](https://github.com/madebyKir)
+- [mrtnvgr](https://github.com/mrtnvgr)
+
+## Spanish
+- [yeyeto2788](https://github.com/yeyeto2788)
+- [Skrzakk](https://github.com/Skrzakk)
+- [pablohc](https://github.com/pablohc)
+- [DaniPhii](https://github.com/DaniPhii)
+- [lpla](https://github.com/lpla)
+
+## Swedish
+- [dawiik](https://github.com/dawiik)
+- [steka](https://github.com/steka)
+
+## Romanian
+- [ariel-lindemann](https://github.com/ariel-lindemann)
+
+## Catalan
+- [angeldenom](https://github.com/angeldenom)
+- [lpla](https://github.com/lpla)
+
+## Finnish
+- [plahteenlahti](https://github.com/plahteenlahti)
+
+## Ukrainian
+- [mirus-ua](https://github.com/mirus-ua)
+- [KymAndriy](https://github.com/KymAndriy)
+
+## Belarusian
+- [Dexif](https://github.com/dexif)
+
+## Danish
+- [hajisan](https://github.com/hajisan)

docs/troubleshooting.md

@@ -0,0 +1,60 @@
+# Troubleshooting
+
+This document shows common issues and possible solutions while using the device features.
+
+- [Troubleshooting](#troubleshooting)
+    - [Cannot See the Device on the Network](#cannot-see-the-device-on-the-network)
+    - [Connection Drops or Times Out](#connection-drops-or-times-out)
+    - [Upload Fails](#upload-fails)
+    - [Saved Password Not Working](#saved-password-not-working)
+
+### Cannot See the Device on the Network
+
+**Problem:** Browser shows "Cannot connect" or "Site can't be reached"
+
+**Solutions:**
+
+1. Verify both devices are on the correct network
+   - Check your computer/phone Wi-Fi settings
+   - In **Join Network** mode, your computer/phone and CrossPoint Reader must be on the same Wi-Fi network
+   - In **Create Hotspot** mode, your computer/phone must be connected to the `CrossPoint-Reader` hotspot
+2. Double-check the IP address
+   - Make sure you typed it correctly
+   - Include `http://` at the beginning
+   - Try the displayed IP address if `http://crosspoint.local/` does not resolve
+3. Try disabling VPN if you're using one
+4. Some networks have "client isolation" enabled - use Create Hotspot mode or check with your network administrator
+
+### Connection Drops or Times Out
+
+**Problem:** Wi-Fi connection is unstable
+
+**Solutions:**
+
+1. Move closer to the Wi-Fi router, or use Create Hotspot mode for a direct connection
+2. Check signal strength on the device (should be at least `||` or better)
+3. Avoid interference from other devices
+4. Try a different Wi-Fi network if available
+
+### Upload Fails
+
+**Problem:** File upload doesn't complete or shows an error
+
+**Solutions:**
+
+1. Check that the SD card has enough free space
+2. Check that the filename is valid for the SD card filesystem
+3. Try uploading a smaller file first to test
+4. Refresh the browser page and try again
+5. If WebSocket upload fails repeatedly, refresh the page and retry with the HTTP fallback path
+
+### Saved Password Not Working
+
+**Problem:** Device fails to connect with saved credentials
+
+**Solutions:**
+
+1. When connection fails, you'll be prompted to "Forget Network"
+2. Select **Yes** to remove the saved password
+3. Reconnect and enter the password again
+4. Choose to save the new password

docs/webserver-endpoints.md

@@ -0,0 +1,500 @@
+# Webserver Endpoints
+
+This document describes the HTTP, WebSocket, WebDAV, and discovery endpoints
+available while CrossPoint Reader is in File Transfer or Calibre Wireless mode.
+
+- HTTP server: port 80
+- WebSocket upload server: port 81
+- UDP discovery listener: port 8134
+- WebDAV: port 80, handled by the same HTTP server
+
+Examples use `crosspoint.local`. If mDNS does not resolve on your network, use
+the IP address shown on the device screen.
+
+## HTTP Pages
+
+| Method | Path | Purpose |
+|--------|------|---------|
+| `GET` | `/` | Home/status page |
+| `GET` | `/files` | File manager page |
+| `GET` | `/settings` | Web settings page |
+| `GET` | `/fonts` | SD-card font manager page |
+| `GET` | `/js/jszip.min.js` | JavaScript asset used by the file manager |
+
+## Device Status
+
+### `GET /api/status`
+
+```bash
+curl http://crosspoint.local/api/status
+```
+
+Response:
+
+```json
+{
+  "version": "1.0.0",
+  "ip": "192.168.1.100",
+  "mode": "STA",
+  "rssi": -45,
+  "freeHeap": 123456,
+  "uptime": 3600,
+  "device": "X4"
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `version` | string | Firmware version |
+| `ip` | string | Device IP address |
+| `mode` | string | `"STA"` for joined Wi-Fi or `"AP"` for hotspot mode |
+| `rssi` | number | Wi-Fi RSSI in dBm; `0` in AP mode |
+| `freeHeap` | number | Free heap in bytes |
+| `uptime` | number | Seconds since boot |
+| `device` | string | `"X3"` or `"X4"` hardware detection |
+
+## File Management
+
+### `GET /api/files`
+
+Lists files and folders under a directory.
+
+```bash
+curl "http://crosspoint.local/api/files?path=/Books"
+```
+
+Query parameters:
+
+| Parameter | Required | Default | Description |
+|-----------|----------|---------|-------------|
+| `path` | No | `/` | Directory to list |
+
+Response:
+
+```json
+[
+  {"name":"MyBook.epub","size":1234567,"isDirectory":false,"isEpub":true},
+  {"name":"Notes","size":0,"isDirectory":true,"isEpub":false}
+]
+```
+
+Hidden dotfiles are omitted unless the device setting `showHiddenFiles` is
+enabled. `System Volume Information` and `XTCache` are always hidden/protected.
+
+### `GET /download`
+
+Downloads a file from the SD card.
+
+```bash
+curl -OJ "http://crosspoint.local/download?path=/Books/MyBook.epub"
+```
+
+Query parameters:
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `path` | Yes | File path to download |
+
+Protected dotfiles, `System Volume Information`, and `XTCache` cannot be
+downloaded. EPUB files are served as `application/epub+zip`; other files use
+`application/octet-stream`.
+
+### `POST /upload`
+
+Uploads a file with HTTP multipart form data.
+
+```bash
+curl -X POST -F "file=@mybook.epub" "http://crosspoint.local/upload?path=/Books"
+```
+
+Query parameters:
+
+| Parameter | Required | Default | Description |
+|-----------|----------|---------|-------------|
+| `path` | No | `/` | Destination directory |
+
+Successful response:
+
+```text
+File uploaded successfully: mybook.epub
+```
+
+Notes:
+
+- Existing files with the same name are overwritten.
+- EPUB cache data for the uploaded path is cleared after a successful upload.
+- HTTP upload uses a 4 KB write buffer before flushing to the SD card.
+
+### `POST /mkdir`
+
+Creates a folder.
+
+```bash
+curl -X POST -d "name=NewFolder&path=/" http://crosspoint.local/mkdir
+```
+
+Form parameters:
+
+| Parameter | Required | Default | Description |
+|-----------|----------|---------|-------------|
+| `name` | Yes | - | New folder name |
+| `path` | No | `/` | Parent folder |
+
+### `POST /rename`
+
+Renames a file.
+
+```bash
+curl -X POST -d "path=/Books/old.epub&name=new.epub" http://crosspoint.local/rename
+```
+
+Form parameters:
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `path` | Yes | Existing file path |
+| `name` | Yes | New file name, not a path |
+
+Only files can be renamed through this endpoint. The old EPUB cache path is
+cleared before the rename.
+
+### `POST /move`
+
+Moves a file into an existing folder.
+
+```bash
+curl -X POST -d "path=/Books/mybook.epub&dest=/Read" http://crosspoint.local/move
+```
+
+Form parameters:
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `path` | Yes | Existing file path |
+| `dest` | Yes | Existing destination folder |
+
+Only files can be moved through this endpoint. The old EPUB cache path is
+cleared before the move.
+
+### `POST /delete`
+
+Deletes one or more files or empty folders.
+
+```bash
+curl -X POST -d "path=/Books/mybook.epub" http://crosspoint.local/delete
+curl -X POST -d 'paths=["/Books/old.epub","/OldFolder"]' http://crosspoint.local/delete
+```
+
+Form parameters:
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `path` | Yes, unless `paths` is provided | Single path to delete |
+| `paths` | Yes, unless `path` is provided | JSON array of paths to delete |
+
+Protected items cannot be deleted. Non-empty folders are rejected. EPUB cache
+data for deleted files is cleared.
+
+## Settings API
+
+### `GET /api/settings`
+
+Returns a streamed JSON array of editable settings. Each item contains common
+fields plus type-specific fields.
+
+```bash
+curl http://crosspoint.local/api/settings
+```
+
+Example item:
+
+```json
+{
+  "key": "fontSize",
+  "name": "Font Size",
+  "category": "Reader",
+  "type": "enum",
+  "value": 1,
+  "options": ["Small", "Medium", "Large"]
+}
+```
+
+Types:
+
+| Type | Extra fields |
+|------|--------------|
+| `toggle` | `value` (`0` or `1`) |
+| `enum` | `value`, `options` |
+| `value` | `value`, `min`, `max`, `step` |
+| `string` | `value` |
+
+The font-family setting includes SD-card font families when they are installed.
+
+### `POST /api/settings`
+
+Applies a partial settings update from a JSON object.
+
+```bash
+curl -X POST \
+  -H "Content-Type: application/json" \
+  -d '{"fontSize":2,"showHiddenFiles":1}' \
+  http://crosspoint.local/api/settings
+```
+
+Successful response:
+
+```text
+Applied 2 setting(s)
+```
+
+## Font Management API
+
+### `GET /api/fonts`
+
+Lists installed SD-card font families.
+
+```bash
+curl http://crosspoint.local/api/fonts
+```
+
+Response:
+
+```json
+{
+  "maxFamilies": 128,
+  "families": [
+    {
+      "name": "Literata",
+      "sizes": [12, 14, 16, 18],
+      "files": [
+        {"name": "Literata_12.cpfont", "size": 123456}
+      ]
+    }
+  ]
+}
+```
+
+### `POST /api/fonts/upload`
+
+Uploads one `.cpfont` file into a family folder.
+
+```bash
+curl -X POST \
+  -F "family=Literata" \
+  -F "file=@Literata_12.cpfont" \
+  http://crosspoint.local/api/fonts/upload
+```
+
+The handler validates the family name, `.cpfont` filename, and `CPFONT` magic
+bytes before accepting the file.
+
+Successful response:
+
+```json
+{"ok":true}
+```
+
+### `POST /api/fonts/delete`
+
+Deletes an installed font family.
+
+```bash
+curl -X POST \
+  -H "Content-Type: application/json" \
+  -d '{"family":"Literata"}' \
+  http://crosspoint.local/api/fonts/delete
+```
+
+Successful response:
+
+```json
+{"ok":true}
+```
+
+## OPDS Server API
+
+### `GET /api/opds`
+
+Lists saved OPDS servers. Passwords are never returned.
+
+```bash
+curl http://crosspoint.local/api/opds
+```
+
+Response:
+
+```json
+[
+  {
+    "index": 0,
+    "name": "My Catalog",
+    "url": "http://calibre.local:8080/opds",
+    "username": "reader",
+    "hasPassword": true
+  }
+]
+```
+
+### `POST /api/opds`
+
+Adds or updates an OPDS server. Include `index` to update an existing entry.
+If `password` is omitted during an update, the existing password is preserved.
+
+```bash
+curl -X POST \
+  -H "Content-Type: application/json" \
+  -d '{"name":"My Catalog","url":"http://calibre.local:8080/opds","username":"reader","password":"secret"}' \
+  http://crosspoint.local/api/opds
+```
+
+### `POST /api/opds/delete`
+
+Deletes an OPDS server by index.
+
+```bash
+curl -X POST \
+  -H "Content-Type: application/json" \
+  -d '{"index":0}' \
+  http://crosspoint.local/api/opds/delete
+```
+
+## Wi-Fi Credential API
+
+### `GET /api/wifi`
+
+Lists saved Wi-Fi networks. Passwords are never returned.
+
+```bash
+curl http://crosspoint.local/api/wifi
+```
+
+Response:
+
+```json
+[
+  {
+    "index": 0,
+    "ssid": "HomeWiFi",
+    "hasPassword": true,
+    "isLastConnected": true
+  }
+]
+```
+
+### `POST /api/wifi`
+
+Adds or updates a saved Wi-Fi network. Include `index` to update an existing
+entry. If `password` is omitted during an update, the existing password is
+preserved.
+
+```bash
+curl -X POST \
+  -H "Content-Type: application/json" \
+  -d '{"ssid":"HomeWiFi","password":"secret"}' \
+  http://crosspoint.local/api/wifi
+```
+
+### `POST /api/wifi/delete`
+
+Deletes a saved Wi-Fi network by index.
+
+```bash
+curl -X POST \
+  -H "Content-Type: application/json" \
+  -d '{"index":0}' \
+  http://crosspoint.local/api/wifi/delete
+```
+
+## WebSocket Upload
+
+### Port 81
+
+The WebSocket path is used for fast binary uploads from the file manager and
+Calibre plugin workflows.
+
+Connection:
+
+```text
+ws://crosspoint.local:81/
+```
+
+Protocol:
+
+1. Client sends text: `START:<filename>:<size>:<path>`
+2. Server replies `READY`
+3. Client sends binary chunks
+4. Server sends `PROGRESS:<received>:<total>` every 64 KB or at completion
+5. Server sends `DONE` when complete or `ERROR:<message>` on failure
+
+Example session:
+
+```text
+Client -> START:mybook.epub:1234567:/Books
+Server -> READY
+Client -> [binary chunk]
+Server -> PROGRESS:65536:1234567
+...
+Server -> DONE
+```
+
+Error messages include:
+
+| Message | Cause |
+|---------|-------|
+| `ERROR:Upload already in progress` | A second upload was started before the first completed |
+| `ERROR:Invalid START format` | Malformed START message or invalid size token |
+| `ERROR:Failed to create file` | Destination file could not be opened |
+| `ERROR:No upload in progress` | Binary data arrived without a matching START |
+| `ERROR:Upload overflow` | Client sent more bytes than declared |
+| `ERROR:Write failed - disk full?` | SD write failed |
+
+Incomplete WebSocket uploads are deleted on disconnect or error.
+
+## WebDAV
+
+The same HTTP server registers a WebDAV-compatible handler for file manager clients.
+
+Supported methods:
+
+```text
+OPTIONS, GET, HEAD, PUT, DELETE, PROPFIND, MKCOL, MOVE, COPY, LOCK, UNLOCK
+```
+
+Notes:
+
+- `PUT` writes to a temporary `.davtmp` file first, then renames it into place.
+- Protected paths are rejected.
+- `LOCK` and `UNLOCK` are accepted for client compatibility only. The server
+  does not implement full WebDAV Class 2 locking semantics such as persistent
+  locks or lock discovery.
+
+## UDP Discovery
+
+The server listens on UDP port `8134`. When it receives the text payload
+`hello`, it replies to the sender with:
+
+```text
+crosspoint (on <hostname>);81
+```
+
+The final field is the WebSocket upload port.
+
+## Network Modes
+
+### Station Mode (STA)
+
+- Device joins an existing 2.4 GHz Wi-Fi network.
+- `crosspoint.local` is advertised with mDNS when available.
+- `/api/status` returns `"mode": "STA"` and RSSI in dBm.
+
+### Access Point Mode (AP)
+
+- Device creates an open hotspot named `CrossPoint-Reader`.
+- The device shows a Wi-Fi QR code and URL QR code.
+- The fallback IP is typically `192.168.4.1`.
+- `/api/status` returns `"mode": "AP"` and `"rssi": 0`.
+
+### Calibre Wireless
+
+Calibre Wireless starts the same web server in STA mode and displays setup
+instructions plus WebSocket upload progress on the device screen.

docs/webserver.md

@@ -1,272 +1,153 @@
 # Web Server Guide
 
-This guide explains how to connect your CrossPoint Reader to WiFi and use the built-in web server to upload EPUB files from your computer or phone.
+This guide explains how to use CrossPoint Reader's built-in web server for file
+transfer, device settings, Wi-Fi/OPDS management, and SD-card font management.
 
 ## Overview
 
-CrossPoint Reader includes a built-in web server that allows you to:
+The web server is available while the device is in **File Transfer** or
+**Calibre Wireless** mode. It can:
 
-- Upload EPUB files wirelessly from any device on the same WiFi network
-- Browse and manage files on your device's SD card
-- Create folders to organize your ebooks
-- Delete files and folders
+- Upload, download, rename, move, and delete files on the SD card
+- Create folders
+- Edit many device settings from a browser
+- Manage saved Wi-Fi networks and OPDS servers
+- Upload and delete `.cpfont` SD-card font families
+- Accept WebDAV clients and Calibre wireless uploads
 
-## Prerequisites
+The server does not require authentication. Use it only on trusted private
+networks or in hotspot mode when you control who is connected.
 
-- Your CrossPoint Reader device
-- A WiFi network
-- A computer, phone, or tablet connected to the **same WiFi network**
+## Starting File Transfer
 
----
+1. From the Home screen, select **File Transfer**.
+2. Choose one of the available modes:
 
-## Step 1: Accessing the WiFi Screen
+| Mode | Use when |
+|------|----------|
+| **Join Network** | You want the reader to join an existing Wi-Fi network. |
+| **Calibre Wireless** | You want to receive books from the CrossPoint Calibre plugin workflow. |
+| **Create Hotspot** | You want the reader to create its own open Wi-Fi network. |
 
-1. From the main menu or file browser, navigate to the **Settings** screen
-2. Select the **WiFi** option
-3. The device will automatically start scanning for available networks
+## Join Network Mode
 
----
+1. Select **Join Network**.
+2. If you have saved Wi-Fi credentials, CrossPoint first tries the last
+   connected network, then other visible saved networks in signal-strength
+   order. Press **Back** to cancel or **Confirm** to stop auto-connect and show
+   the network list.
+3. If the network list is shown, pick a 2.4 GHz Wi-Fi network from the scan
+   results.
+4. Enter the password if prompted.
+5. Save credentials if you want the reader to reconnect automatically next time.
 
-## Step 2: Connecting to WiFi
+After connection, the reader shows:
 
-### Viewing Available Networks
+- The connected SSID
+- A QR code for the web URL
+- The direct IP URL, for example `http://192.168.1.102/`
+- The mDNS fallback URL, usually `http://crosspoint.local/`
 
-Once the scan completes, you'll see a list of available WiFi networks with the following indicators:
+Use either URL from a phone, tablet, or computer on the same network.
 
-- **Signal strength bars** (`||||`, `|||`, `||`, `|`) - Shows connection quality
-- **`*` symbol** - Indicates the network is password-protected (encrypted)
-- **`+` symbol** - Indicates you have previously saved credentials for this network
+## Create Hotspot Mode
 
-<img src="./images/wifi/wifi_networks.jpeg" height="500">
+1. Select **Create Hotspot**.
+2. Connect your phone or computer to the open Wi-Fi network:
 
-### Selecting a Network
+```text
+CrossPoint-Reader
+```
 
-1. Use the **Left/Right** (or **Volume Up/Down**) buttons to navigate through the network list
-2. Press **Confirm** to select the highlighted network
+3. Open the URL shown on the reader. `http://crosspoint.local/` is preferred
+   when supported; the fallback IP is typically `http://192.168.4.1/`.
 
-### Entering Password (for encrypted networks)
+The reader displays one QR code for joining the hotspot and another QR code for
+opening the web interface.
 
-If the network requires a password:
+## Calibre Wireless Mode
 
-1. An on-screen keyboard will appear
-2. Use the navigation buttons to select characters
-3. Press **Confirm** to enter each character
-4. When complete, select the **Done** option on the keyboard
+Calibre Wireless starts the same web server in station mode, then displays setup
+instructions and upload progress on the reader. Use this mode with the
+CrossPoint Calibre plugin or other clients that speak the documented WebSocket
+upload protocol.
 
-<img src="./images/wifi/wifi_password.jpeg" height="500">
+For Calibre OPDS browsing, add `/opds` to the catalog URL when configuring an
+OPDS server.
 
-**Note:** If you've previously connected to this network, the saved password will be used automatically.
+## Web Interface
 
-### Connection Process
+The browser UI has four primary pages.
 
-The device will display "Connecting..." while establishing the connection. This typically takes 5-10 seconds.
+### Home
 
-### Saving Credentials
-
-If this is a new network, you'll be prompted to save the password:
-
-- Select **Yes** to save credentials for automatic connection next time (NOTE: These are stored in plaintext on the device's SD card. Do not use this for sensitive networks.)
-- Select **No** to connect without saving
-
----
-
-## Step 3: Connection Success
-
-Once connected, the screen will display:
-
-- **Network name** (SSID)
-- **IP Address** (e.g., `192.168.1.102`)
-- **Web server URL** (e.g., `http://192.168.1.102/`)
-
-<img src="./images/wifi/wifi_connected.jpeg" height="500">
-
-**Important:** Make note of the IP address - you'll need this to access the web interface from your computer or phone.
-
----
-
-## Step 4: Accessing the Web Interface
-
-### From a Computer
-
-1. Ensure your computer is connected to the **same WiFi network** as your CrossPoint Reader
-2. Open any web browser (Chrome is recommended)
-3. Type the IP address shown on your device into the browser's address bar
-   - Example: `http://192.168.1.102/`
-4. Press Enter
-
-### From a Phone or Tablet
-
-1. Ensure your phone/tablet is connected to the **same WiFi network** as your CrossPoint Reader
-2. Open your mobile browser (Safari, Chrome, etc.)
-3. Type the IP address into the address bar
-   - Example: `http://192.168.1.102/`
-4. Tap Go
-
----
-
-## Step 5: Using the Web Interface
-
-### Home Page
-
-The home page displays:
-
-- Device status and version information
-- WiFi connection status
-- Current IP address
-- Available memory
-
-Navigation links:
-
-- **Home** - Returns to the status page
-- **File Manager** - Access file management features
-
-<img src="./images/wifi/webserver_homepage.png" width="600">
+The Home page shows firmware status, network mode, IP address, device type,
+uptime, and free heap.
 
 ### File Manager
 
-Click **File Manager** to access file management features.
+The File Manager page can:
 
-#### Browsing Files
+- Browse SD-card folders
+- Upload files, using WebSocket upload when available and HTTP upload as a fallback
+- Create folders
+- Download files
+- Rename files
+- Move files into existing folders
+- Delete one or more selected files or empty folders
 
-- The file manager displays all files and folders on your SD card
-- **Folders** are highlighted in yellow with a 📁 icon
-- **EPUB files** are highlighted in green with a 📗 icon
-- Click on a folder name to navigate into it
-- Use the breadcrumb navigation at the top to go back to parent folders
+Existing files with the same name are overwritten by uploads. When EPUB files
+are overwritten, moved, renamed, or deleted through the web server, the matching
+book cache is cleared so stale metadata is not reused.
 
-<img src="./images/wifi/webserver_files.png" width="600">
+### Settings
 
-#### Uploading EPUB Files
+The Settings page exposes many firmware settings in the browser. It also has
+cards for:
 
-1. Click the **+ Add** button in the top-right corner
-2. Select **Upload eBook** from the dropdown menu
-3. Click **Choose File** and select an `.epub` file from your device
-4. Click **Upload**
-5. A progress bar will show the upload status
-6. The page will automatically refresh when the upload is complete
+- Saved Wi-Fi networks
+- OPDS servers
 
-**Note:** Only `.epub` files are accepted. Other file types will be rejected.
+Passwords are accepted when adding or editing entries, but saved passwords are
+not returned by the API.
 
-<img src="./images/wifi/webserver_upload.png" width="600">
+### Fonts
 
-#### Creating Folders
+The Fonts page lists installed SD-card font families and lets you upload
+`.cpfont` files. Upload files from one font family at a time. The server validates
+the font family name, filename, and `.cpfont` magic bytes before accepting the
+upload.
 
-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)
-4. Click **Create Folder**
+Installed fonts appear in **Settings > Reader > Font Family** after the font
+registry refreshes.
 
-This is useful for organizing your ebooks by genre, author, or series.
+## Command Line Use
 
-#### Deleting Files and Folders
+Power users can use `curl`, WebDAV clients, or WebSocket clients while the web
+server is running.
 
-1. Click the **🗑️** (trash) icon next to any file or folder
-2. Confirm the deletion in the popup dialog
-3. Click **Delete** to permanently remove the item
-
-**Warning:** Deletion is permanent and cannot be undone!
-
-**Note:** Folders must be empty before they can be deleted.
-
----
-
-## Troubleshooting
-
-### Cannot See the Device on the Network
-
-**Problem:** Browser shows "Cannot connect" or "Site can't be reached"
-
-**Solutions:**
-
-1. Verify both devices are on the **same WiFi network**
-   - Check your computer/phone WiFi settings
-   - Confirm the CrossPoint Reader shows "Connected" status
-2. Double-check the IP address
-   - Make sure you typed it correctly
-   - Include `http://` at the beginning
-3. Try disabling VPN if you're using one
-4. Some networks have "client isolation" enabled - check with your network administrator
-
-### Connection Drops or Times Out
-
-**Problem:** WiFi connection is unstable
-
-**Solutions:**
-
-1. Move closer to the WiFi router
-2. Check signal strength on the device (should be at least `||` or better)
-3. Avoid interference from other devices
-4. Try a different WiFi network if available
-
-### Upload Fails
-
-**Problem:** File upload doesn't complete or shows an error
-
-**Solutions:**
-
-1. Ensure the file is a valid `.epub` file
-2. Check that the SD card has enough free space
-3. Try uploading a smaller file first to test
-4. Refresh the browser page and try again
-
-### Saved Password Not Working
-
-**Problem:** Device fails to connect with saved credentials
-
-**Solutions:**
-
-1. When connection fails, you'll be prompted to "Forget Network"
-2. Select **Yes** to remove the saved password
-3. Reconnect and enter the password again
-4. Choose to save the new password
-
----
+Endpoint details are documented in [webserver-endpoints.md](./webserver-endpoints.md).
 
 ## Security Notes
 
-- The web server runs on port 80 (standard HTTP)
-- **No authentication is required** - anyone on the same network can access the interface
-- The web server is only accessible while the WiFi screen shows "Connected"
-- The web server automatically stops when you exit the WiFi screen
-- For security, only use on trusted private networks
+- The HTTP server runs on port 80.
+- The WebSocket upload server runs on port 81.
+- There is no authentication.
+- Anyone on the same network can access the web interface while it is running.
+- The server stops when you exit File Transfer or Calibre Wireless mode.
+- Hotspot mode creates an open network for connectivity fallback; disconnect when done.
 
----
+## Tips
 
-## Technical Details
-
-- **Supported WiFi:** 2.4GHz networks (802.11 b/g/n)
-- **Web Server Port:** 80 (HTTP)
-- **Maximum Upload Size:** Limited by available SD card space
-- **Supported File Format:** `.epub` only
-- **Browser Compatibility:** All modern browsers (Chrome, Firefox, Safari, Edge)
-
----
-
-## Tips and Best Practices
-
-1. **Organize with folders** - Create folders before uploading to keep your library organized
-2. **Check signal strength** - Stronger signals (`|||` or `||||`) provide faster, more reliable uploads
-3. **Upload multiple files** - You can upload files one at a time; the page refreshes after each upload
-4. **Use descriptive names** - Name your folders clearly (e.g., "SciFi", "Mystery", "Non-Fiction")
-5. **Keep credentials saved** - Save your WiFi password for quick reconnection in the future
-6. **Exit when done** - Press **Back** to exit the WiFi screen and save battery
-
----
-
-## Exiting WiFi Mode
-
-When you're finished uploading files:
-
-1. Press the **Back** button on your CrossPoint Reader
-2. The web server will automatically stop
-3. WiFi will disconnect to conserve battery
-4. You'll return to the previous screen
-
-Your uploaded files will be immediately available in the file browser!
-
----
+1. Use **Create Hotspot** when no trusted network is available.
+2. Prefer `crosspoint.local` when available, but keep the displayed IP address as a fallback.
+3. Move closer to the router if upload progress stalls in Join Network mode.
+4. Upload custom fonts through the Fonts page or copy them to `/.fonts/` or `/fonts/` on the SD card.
+5. Exit File Transfer mode when finished to conserve battery.
 
 ## Related Documentation
 
-- [User Guide](../USER_GUIDE.md) - General device operation
-- [README](../README.md) - Project overview and features
+- [User Guide](../USER_GUIDE.md)
+- [Webserver Endpoints](./webserver-endpoints.md)
+- [SD Card Fonts](./sd-card-fonts.md)
+- [Troubleshooting](./troubleshooting.md)

include/README

@@ -1,37 +0,0 @@
-
-This directory is intended for project header files.
-
-A header file is a file containing C declarations and macro definitions
-to be shared between several project source files. You request the use of a
-header file in your project source file (C, C++, etc) located in `src` folder
-by including it, with the C preprocessing directive `#include'.
-
-```src/main.c
-
-#include "header.h"
-
-int main (void)
-{
- ...
-}
-```
-
-Including a header file produces the same results as copying the header file
-into each source file that needs it. Such copying would be time-consuming
-and error-prone. With a header file, the related declarations appear
-in only one place. If they need to be changed, they can be changed in one
-place, and programs that include the header file will automatically use the
-new version when next recompiled. The header file eliminates the labor of
-finding and changing all the copies as well as the risk that a failure to
-find one copy will result in inconsistencies within a program.
-
-In C, the convention is to give header files names that end with `.h'.
-
-Read more about using header files in official GCC documentation:
-
-* Include Syntax
-* Include Operation
-* Once-Only Headers
-* Computed Includes
-
-https://gcc.gnu.org/onlinedocs/cpp/Header-Files.html

lib/EpdFont/EpdFont.cpp

@@ -15,27 +15,60 @@ void EpdFont::getTextBounds(const char* string, const int startX, const int star
     return;
   }
 
-  int cursorX = startX;
-  const int cursorY = startY;
+  int lastBaseX = startX;
+  int lastBaseLeft = 0;
+  int lastBaseWidth = 0;
+  int lastBaseTop = 0;
+  int32_t prevAdvanceFP = 0;  // 12.4 fixed-point: prev glyph's advance + next kern for snap
   uint32_t cp;
+  uint32_t prevCp = 0;
   while ((cp = utf8NextCodepoint(reinterpret_cast<const uint8_t**>(&string)))) {
-    const EpdGlyph* glyph = getGlyph(cp);
+    const bool isCombining = utf8IsCombiningMark(cp);
 
-    if (!glyph) {
-      // TODO: Replace with fallback glyph property?
-      glyph = getGlyph('?');
+    if (!isCombining) {
+      cp = applyLigatures(cp, string);
     }
 
+    const EpdGlyph* glyph = getGlyph(cp);
     if (!glyph) {
-      // TODO: Better handle this?
+      // Keep cursor movement stable when a base glyph is missing, but don't attach subsequent
+      // combining marks to stale base metrics.
+      if (!isCombining) {
+        lastBaseX += fp4::toPixel(prevAdvanceFP);  // flush pending advance before resetting
+        prevCp = 0;
+        prevAdvanceFP = 0;
+        lastBaseLeft = 0;
+        lastBaseWidth = 0;
+        lastBaseTop = 0;
+      }
       continue;
     }
 
-    *minX = std::min(*minX, cursorX + glyph->left);
-    *maxX = std::max(*maxX, cursorX + glyph->left + glyph->width);
-    *minY = std::min(*minY, cursorY + glyph->top - glyph->height);
-    *maxY = std::max(*maxY, cursorY + glyph->top);
-    cursorX += glyph->advanceX;
+    const combiningMark::Anchor anchor = combiningMark::anchorFor(cp);
+    const int raiseBy = isCombining ? combiningMark::raiseAboveBase(anchor, glyph->top, glyph->height, lastBaseTop) : 0;
+
+    if (!isCombining && prevCp != 0) {
+      const auto kernFP = getKerning(prevCp, cp);  // 4.4 fixed-point kern
+      lastBaseX += fp4::toPixel(prevAdvanceFP + kernFP);
+    }
+
+    const int glyphBaseX = isCombining ? combiningMark::anchorOver(anchor, lastBaseX, lastBaseLeft, lastBaseWidth,
+                                                                   glyph->left, glyph->width)
+                                       : lastBaseX;
+    const int glyphBaseY = startY - raiseBy;
+
+    *minX = std::min(*minX, glyphBaseX + glyph->left);
+    *maxX = std::max(*maxX, glyphBaseX + glyph->left + glyph->width);
+    *minY = std::min(*minY, glyphBaseY + glyph->top - glyph->height);
+    *maxY = std::max(*maxY, glyphBaseY + glyph->top);
+
+    if (!isCombining) {
+      lastBaseLeft = glyph->left;
+      lastBaseWidth = glyph->width;
+      lastBaseTop = glyph->top;
+      prevAdvanceFP = glyph->advanceX;  // 12.4 fixed-point
+      prevCp = cp;
+    }
   }
 }
 
@@ -48,38 +81,110 @@ void EpdFont::getTextDimensions(const char* string, int* w, int* h) const {
   *h = maxY - minY;
 }
 
-bool EpdFont::hasPrintableChars(const char* string) const {
-  int w = 0, h = 0;
+static uint8_t lookupKernClass(const EpdKernClassEntry* entries, const uint16_t count, const uint32_t cp) {
+  if (!entries || count == 0 || cp > 0xFFFF) {
+    return 0;
+  }
 
-  getTextDimensions(string, &w, &h);
+  const auto target = static_cast<uint16_t>(cp);
+  const auto* end = entries + count;
 
-  return w > 0 || h > 0;
+  // lower_bound: exact-key lookup. Finds the first entry with codepoint >= target,
+  // then the equality check confirms an exact match exists.
+  const auto it = std::lower_bound(
+      entries, end, target, [](const EpdKernClassEntry& entry, uint16_t value) { return entry.codepoint < value; });
+
+  if (it != end && it->codepoint == target) {
+    return it->classId;
+  }
+
+  return 0;
+}
+
+int8_t EpdFont::getKerning(const uint32_t leftCp, const uint32_t rightCp) const {
+  if (utf8IsCjkBreakable(leftCp) || utf8IsCjkBreakable(rightCp)) {
+    return 0;
+  }
+  if (!data->kernMatrix) {
+    return 0;
+  }
+  const uint8_t lc = lookupKernClass(data->kernLeftClasses, data->kernLeftEntryCount, leftCp);
+  if (lc == 0) return 0;
+  const uint8_t rc = lookupKernClass(data->kernRightClasses, data->kernRightEntryCount, rightCp);
+  if (rc == 0) return 0;
+  return data->kernMatrix[(lc - 1) * data->kernRightClassCount + (rc - 1)];
+}
+
+uint32_t EpdFont::getLigature(const uint32_t leftCp, const uint32_t rightCp) const {
+  const auto* pairs = data->ligaturePairs;
+  const auto count = data->ligaturePairCount;
+  if (!pairs || count == 0 || leftCp > 0xFFFF || rightCp > 0xFFFF) {
+    return 0;
+  }
+
+  const uint32_t key = (leftCp << 16) | rightCp;
+  const auto* end = pairs + count;
+
+  // lower_bound: exact-key lookup. Finds the first entry with pair >= key,
+  // then the equality check confirms an exact match exists.
+  const auto it =
+      std::lower_bound(pairs, end, key, [](const EpdLigaturePair& pair, uint32_t value) { return pair.pair < value; });
+
+  if (it != end && it->pair == key) {
+    return it->ligatureCp;
+  }
+
+  return 0;
+}
+
+uint32_t EpdFont::applyLigatures(uint32_t cp, const char*& text) const {
+  if (!data->ligaturePairs || data->ligaturePairCount == 0) {
+    return cp;
+  }
+  while (true) {
+    const auto saved = reinterpret_cast<const uint8_t*>(text);
+    const uint32_t nextCp = utf8NextCodepoint(reinterpret_cast<const uint8_t**>(&text));
+    if (nextCp == 0) break;
+    const uint32_t lig = getLigature(cp, nextCp);
+    if (lig == 0) {
+      text = reinterpret_cast<const char*>(saved);
+      break;
+    }
+    cp = lig;
+  }
+  return cp;
 }
 
 const EpdGlyph* EpdFont::getGlyph(const uint32_t cp) const {
-  const EpdUnicodeInterval* intervals = data->intervals;
   const int count = data->intervalCount;
+  if (count == 0 && !data->glyphMissHandler) return nullptr;
 
-  if (count == 0) return nullptr;
+  if (count > 0) {
+    const EpdUnicodeInterval* intervals = data->intervals;
+    const auto* end = intervals + count;
 
-  // Binary search for O(log n) lookup instead of O(n)
-  // Critical for Korean fonts with many unicode intervals
-  int left = 0;
-  int right = count - 1;
+    // upper_bound: range lookup. Finds the first interval with first > cp, so the
+    // interval just before it is the last one with first <= cp. That's the only
+    // candidate that could contain cp. Then we verify cp <= candidate.last.
+    const auto it = std::upper_bound(
+        intervals, end, cp, [](uint32_t value, const EpdUnicodeInterval& interval) { return value < interval.first; });
 
-  while (left <= right) {
-    const int mid = left + (right - left) / 2;
-    const EpdUnicodeInterval* interval = &intervals[mid];
-
-    if (cp < interval->first) {
-      right = mid - 1;
-    } else if (cp > interval->last) {
-      left = mid + 1;
-    } else {
-      // Found: cp >= interval->first && cp <= interval->last
-      return &data->glyph[interval->offset + (cp - interval->first)];
+    if (it != intervals) {
+      const auto& interval = *(it - 1);
+      if (cp <= interval.last) {
+        return &data->glyph[interval.offset + (cp - interval.first)];
+      }
     }
   }
 
+  // Codepoint not in interval table — try on-demand loading (SD card fonts).
+  if (data->glyphMissHandler) {
+    const EpdGlyph* loaded = data->glyphMissHandler(data->glyphMissCtx, cp);
+    if (loaded) return loaded;
+  }
+
+  if (cp != REPLACEMENT_GLYPH) {
+    return getGlyph(REPLACEMENT_GLYPH);
+  }
   return nullptr;
 }

lib/EpdFont/EpdFont.h

@@ -9,7 +9,18 @@ class EpdFont {
   explicit EpdFont(const EpdFontData* data) : data(data) {}
   ~EpdFont() = default;
   void getTextDimensions(const char* string, int* w, int* h) const;
-  bool hasPrintableChars(const char* string) const;
 
   const EpdGlyph* getGlyph(uint32_t cp) const;
+
+  /// Returns the kerning adjustment (4.4 fixed-point in pixels) between two codepoints.
+  /// Returns 0 if no kerning data exists for the pair.
+  int8_t getKerning(uint32_t leftCp, uint32_t rightCp) const;
+
+  /// Returns the ligature codepoint for a pair, or 0 if no ligature exists.
+  uint32_t getLigature(uint32_t leftCp, uint32_t rightCp) const;
+
+  /// Greedily applies ligature substitutions starting from cp, consuming
+  /// as many following codepoints from text as possible. Returns the
+  /// (possibly substituted) codepoint; advances text past consumed chars.
+  uint32_t applyLigatures(uint32_t cp, const char*& text) const;
 };

lib/EpdFont/EpdFontData.h

@@ -4,17 +4,149 @@
 #pragma once
 #include <cstdint>
 
+/// Font metrics use "fixed-point 4" (4 fractional bits, i.e. 1/16-pixel
+/// resolution).  Both the 12.4 glyph advances (uint16_t) and the 4.4 kern
+/// values (int8_t) share the same 4 fractional bits, so they can be freely
+/// added before snapping to whole pixels.
+///
+/// Rendering and measurement use "differential rounding": each glyph step
+/// (previous advance + current kern) is combined in fixed-point and snapped
+/// to a pixel as one unit.  This guarantees identical character pairs always
+/// produce the same pixel spacing, regardless of position on the line.
+///
+/// The helpers below eliminate the raw bit-shifts that would otherwise be
+/// scattered across every layout / measurement call site.
+namespace fp4 {
+constexpr int FRAC_BITS = 4;
+constexpr int32_t HALF = 1 << (FRAC_BITS - 1);  // 8, added before shift for round-to-nearest
+
+/// Convert an integer pixel value to 12.4 fixed-point.
+constexpr int32_t fromPixel(int px) { return static_cast<int32_t>(px) << FRAC_BITS; }
+
+/// Snap a fixed-point value to the nearest integer pixel.
+constexpr int toPixel(int32_t fp) { return static_cast<int>((fp + HALF) >> FRAC_BITS); }
+
+/// Convert a fixed-point value to float (mainly useful for debug logging).
+constexpr float toFloat(int32_t fp) { return fp / static_cast<float>(1 << FRAC_BITS); }
+}  // namespace fp4
+
+/// Helpers for positioning Unicode combining marks (U+0300 ff.) over a
+/// preceding base glyph without GPOS anchor tables.
+namespace combiningMark {
+
+constexpr int MIN_GAP_PX = 1;
+
+/// Placement of a mark relative to its base glyph.  The default heuristic —
+/// centered over the base, raised clear of its top — suits Latin diacritics
+/// and Arabic harakat, but misplaces the Hebrew niqqud whose identity depends
+/// on position: dagesh sits inside the letter body, the shin/sin dots
+/// distinguish the letter by sitting over its right/left arm, and holam hangs
+/// over the left corner.  "Native" anchors keep the glyph's font-designed
+/// height (which may overlap the base) instead of raising it.
+enum class Anchor : uint8_t {
+  CenterRaised,  ///< centered over the base, lifted above its top (default)
+  CenterNative,  ///< centered over the base at font-native height
+  RightNative,   ///< right edges aligned, font-native height
+  LeftNative,    ///< left edges aligned, font-native height
+};
+
+constexpr Anchor anchorFor(const uint32_t cp) {
+  switch (cp) {
+    case 0x05BC:  // dagesh / mapiq / shuruk dot: inside the letter body
+    case 0x05BA:  // holam haser for vav: straight above the vav stem
+      return Anchor::CenterNative;
+    case 0x05C1:  // shin dot: over the letter's right arm
+      return Anchor::RightNative;
+    case 0x05B9:  // holam: above the letter's left corner
+    case 0x05C2:  // sin dot: over the letter's left arm
+      return Anchor::LeftNative;
+    default:
+      return Anchor::CenterRaised;
+  }
+}
+
+/// Horizontal offset from the base bitmap's left edge to the mark bitmap's
+/// left edge for a given anchor.
+constexpr int anchorShift(const Anchor anchor, const int baseWidth, const int markWidth) {
+  switch (anchor) {
+    case Anchor::LeftNative:
+      return 0;
+    case Anchor::RightNative:
+      return baseWidth - markWidth;
+    default:
+      return baseWidth / 2 - markWidth / 2;
+  }
+}
+
+/// Compute the cursor-X at which to render a combining mark so its bitmap
+/// lands at its anchor position over the base glyph's bitmap.
+constexpr int anchorOver(const Anchor anchor, const int baseCursorPos, const int baseLeft, const int baseWidth,
+                         const int markLeft, const int markWidth) {
+  return baseCursorPos + baseLeft + anchorShift(anchor, baseWidth, markWidth) - markLeft;
+}
+
+/// Rotated-90CW variant of anchorOver.  In the rotated coordinate system
+/// renderCharImpl uses (cursorY - left) instead of (cursorX + left), so
+/// every left/width term inverts sign.
+constexpr int anchorOverRotated90CW(const Anchor anchor, const int baseCursorPos, const int baseLeft,
+                                    const int baseWidth, const int markLeft, const int markWidth) {
+  return baseCursorPos - baseLeft - anchorShift(anchor, baseWidth, markWidth) + markLeft;
+}
+
+/// For combining marks that sit entirely above the baseline, compute how many
+/// pixels to raise the mark so there is at least MIN_GAP_PX between its bottom
+/// edge and the top of the base glyph.  Returns 0 for marks that extend to or
+/// below the baseline (e.g. cedilla, dot-below, ogonek) and for anchors that
+/// keep the font-native height (dagesh must stay inside the letter, the
+/// shin/sin dots touch its arms).
+constexpr int raiseAboveBase(const Anchor anchor, const int markTop, const int markHeight, const int baseTop) {
+  if (anchor != Anchor::CenterRaised) return 0;
+  if (markTop - markHeight <= 0) return 0;
+  const int gap = markTop - markHeight - baseTop;
+  return (gap < MIN_GAP_PX) ? (MIN_GAP_PX - gap) : 0;
+}
+
+}  // namespace combiningMark
+
+/// GCC/Clang (the ESP32 firmware toolchain) pack structs with __attribute__((packed)).
+/// MSVC (host unit tests) has no equivalent attribute and instead needs a #pragma pack
+/// region achieving the same 1-byte alignment. These macros keep the on-disk font layout
+/// identical across both toolchains.
+#if defined(_MSC_VER)
+#define EPD_PACKED_BEGIN __pragma(pack(push, 1))
+#define EPD_PACKED_END __pragma(pack(pop))
+#define EPD_PACKED_ATTR
+#else
+#define EPD_PACKED_BEGIN
+#define EPD_PACKED_END
+#define EPD_PACKED_ATTR __attribute__((packed))
+#endif
+
+/// Fixed-point conventions used by EpdGlyph and EpdFontData:
+///   advanceX:   12.4 unsigned fixed-point in uint16_t  (use fp4::toPixel)
+///   kernMatrix:  4.4 signed fixed-point in int8_t      (use fp4::toPixel)
+/// Both share 4 fractional bits so they combine directly in an accumulator.
+
 /// Font data stored PER GLYPH
 typedef struct {
   uint8_t width;        ///< Bitmap dimensions in pixels
   uint8_t height;       ///< Bitmap dimensions in pixels
-  uint8_t advanceX;     ///< Distance to advance cursor (x axis)
+  uint16_t advanceX;    ///< Distance to advance cursor (x axis), 12.4 fixed-point in pixels
   int16_t left;         ///< X dist from cursor pos to UL corner
   int16_t top;          ///< Y dist from cursor pos to UL corner
   uint16_t dataLength;  ///< Size of the font data.
-  uint32_t dataOffset;  ///< Pointer into EpdFont->bitmap
+  uint32_t dataOffset;  ///< Pointer into EpdFont->bitmap (or within-group offset for compressed fonts)
 } EpdGlyph;
 
+/// Compressed font group: a DEFLATE-compressed block of glyph bitmaps
+typedef struct {
+  uint32_t compressedOffset;  ///< Byte offset into compressed data array
+  uint32_t compressedSize;    ///< Compressed DEFLATE stream size
+  uint32_t uncompressedSize;  ///< Decompressed size
+  uint16_t glyphCount;        ///< Number of glyphs in this group
+  uint32_t firstGlyphIndex;   ///< First glyph index in the global glyph array
+} EpdFontGroup;
+
 /// Glyph interval structure
 typedef struct {
   uint32_t first;   ///< The first unicode code point of the interval
@@ -22,6 +154,24 @@ typedef struct {
   uint32_t offset;  ///< Index of the first code point into the glyph array
 } EpdUnicodeInterval;
 
+/// Maps a codepoint to a kerning class ID, sorted by codepoint for binary search.
+/// Class IDs are 1-based; codepoints not in the table have implicit class 0 (no kerning).
+EPD_PACKED_BEGIN
+typedef struct {
+  uint16_t codepoint;  ///< Unicode codepoint
+  uint8_t classId;     ///< 1-based kerning class ID
+} EPD_PACKED_ATTR EpdKernClassEntry;
+EPD_PACKED_END
+
+/// Ligature substitution for a specific glyph pair, sorted by `pair` for binary search.
+/// `pair` encodes (leftCodepoint << 16 | rightCodepoint) for single-key lookup.
+EPD_PACKED_BEGIN
+typedef struct {
+  uint32_t pair;        ///< Packed codepoint pair (left << 16 | right)
+  uint32_t ligatureCp;  ///< Codepoint of the replacement ligature glyph
+} EPD_PACKED_ATTR EpdLigaturePair;
+EPD_PACKED_END
+
 /// Data stored for FONT AS A WHOLE
 typedef struct {
   const uint8_t* bitmap;                ///< Glyph bitmaps, concatenated
@@ -32,4 +182,28 @@ typedef struct {
   int ascender;                         ///< Maximal height of a glyph above the base line
   int descender;                        ///< Maximal height of a glyph below the base line
   bool is2Bit;
+  const EpdFontGroup* groups;                 ///< NULL for uncompressed fonts
+  uint16_t groupCount;                        ///< 0 for uncompressed fonts
+  const uint16_t* glyphToGroup;               ///< Per-glyph group ID (nullptr for contiguous-group fonts)
+  const EpdKernClassEntry* kernLeftClasses;   ///< Sorted left-side class map (nullptr if none)
+  const EpdKernClassEntry* kernRightClasses;  ///< Sorted right-side class map (nullptr if none)
+  const int8_t* kernMatrix;              ///< Flat leftClassCount x rightClassCount matrix, 4.4 fixed-point in pixels
+  uint16_t kernLeftEntryCount;           ///< Entries in kernLeftClasses
+  uint16_t kernRightEntryCount;          ///< Entries in kernRightClasses
+  uint8_t kernLeftClassCount;            ///< Number of distinct left classes (matrix rows)
+  uint8_t kernRightClassCount;           ///< Number of distinct right classes (matrix cols)
+  const EpdLigaturePair* ligaturePairs;  ///< Sorted ligature pair table (nullptr if none)
+  uint32_t ligaturePairCount;            ///< Number of entries in ligaturePairs
+
+  /// On-demand glyph loading for fonts that don't keep all glyphs in RAM (e.g. SD card fonts).
+  /// Called by getGlyph() when a codepoint is not found in the interval table.
+  /// Returns a valid EpdGlyph* with correct metadata, or nullptr to fall back to the
+  /// replacement glyph.  The returned pointer is valid until the next glyphMissHandler
+  /// call that causes a ring-buffer eviction — callers must consume it (measure or draw)
+  /// before requesting another missed glyph.
+  const EpdGlyph* (*glyphMissHandler)(void* ctx, uint32_t codepoint);
+
+  /// Context pointer for glyphMissHandler (typically SdCardFont*).  Also used by
+  /// GfxRenderer::getGlyphBitmap() to retrieve overflow bitmaps via SdCardFont.
+  void* glyphMissCtx;
 } EpdFontData;

lib/EpdFont/EpdFontFamily.cpp

@@ -1,37 +1,37 @@
 #include "EpdFontFamily.h"
 
-const EpdFont* EpdFontFamily::getFont(const EpdFontStyle style) const {
-  if (style == BOLD && bold) {
+const EpdFont* EpdFontFamily::getFont(const Style style) const {
+  // Extract font style bits; render-time overlay bits do not affect 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;
 }
 
-void EpdFontFamily::getTextDimensions(const char* string, int* w, int* h, const EpdFontStyle style) const {
+void EpdFontFamily::getTextDimensions(const char* string, int* w, int* h, const Style style) const {
   getFont(style)->getTextDimensions(string, w, h);
 }
 
-bool EpdFontFamily::hasPrintableChars(const char* string, const EpdFontStyle style) const {
-  return getFont(style)->hasPrintableChars(string);
+const EpdFontData* EpdFontFamily::getData(const Style style) const { return getFont(style)->data; }
+
+const EpdGlyph* EpdFontFamily::getGlyph(const uint32_t cp, const Style style) const {
+  return getFont(style)->getGlyph(cp);
 }
 
-const EpdFontData* EpdFontFamily::getData(const EpdFontStyle style) const { return getFont(style)->data; }
+int8_t EpdFontFamily::getKerning(const uint32_t leftCp, const uint32_t rightCp, const Style style) const {
+  return getFont(style)->getKerning(leftCp, rightCp);
+}
 
-const EpdGlyph* EpdFontFamily::getGlyph(const uint32_t cp, const EpdFontStyle style) const {
-  return getFont(style)->getGlyph(cp);
-};
+uint32_t EpdFontFamily::applyLigatures(const uint32_t cp, const char*& text, const Style style) const {
+  return getFont(style)->applyLigatures(cp, text);
+}

lib/EpdFont/EpdFontFamily.h

@@ -1,24 +1,42 @@
 #pragma once
 #include "EpdFont.h"
 
-enum EpdFontStyle { REGULAR, BOLD, ITALIC, BOLD_ITALIC };
-
 class EpdFontFamily {
+ public:
+  // Bitmask of text style flags carried per-word through layout and serialized in page cache.
+  // Bits 0-1 select the font variant (BOLD/ITALIC); bits 2-5 are decoration/positioning overlays
+  // applied at render time without changing the underlying font. getFont() ignores all bits
+  // above bit 1 so decorations compose freely with bold/italic (e.g. BOLD | UNDERLINE | SUP).
+  enum Style : uint8_t {
+    REGULAR = 0,
+    BOLD = 1,
+    ITALIC = 2,
+    BOLD_ITALIC = 3,
+    UNDERLINE = 4,      // drawn as a line below baseline by TextBlock::render()
+    STRIKETHROUGH = 8,  // drawn as a line through midline by TextBlock::render()
+    SUP = 16,           // superscript: glyph scaled 50%, raised ~40% of ascender
+    SUB = 32,           // subscript: glyph scaled 50%, lowered ~25% of ascender
+  };
+  static constexpr uint8_t TEXT_DECORATION_MASK = static_cast<uint8_t>(UNDERLINE | STRIKETHROUGH);
+
+  explicit EpdFontFamily(const EpdFont* regular, const EpdFont* bold = nullptr, const EpdFont* italic = nullptr,
+                         const EpdFont* boldItalic = nullptr)
+      : regular(regular), bold(bold), italic(italic), boldItalic(boldItalic) {}
+  ~EpdFontFamily() = default;
+  void getTextDimensions(const char* string, int* w, int* h, Style style = REGULAR) const;
+  const EpdFontData* getData(Style style = REGULAR) const;
+  const EpdGlyph* getGlyph(uint32_t cp, Style style = REGULAR) const;
+  int8_t getKerning(uint32_t leftCp, uint32_t rightCp, Style style = REGULAR) const;
+  uint32_t applyLigatures(uint32_t cp, const char*& text, Style style = REGULAR) const;
+  static constexpr bool hasTextDecoration(const Style style) {
+    return (static_cast<uint8_t>(style) & TEXT_DECORATION_MASK) != 0;
+  }
+
+ private:
   const EpdFont* regular;
   const EpdFont* bold;
   const EpdFont* italic;
   const EpdFont* boldItalic;
 
-  const EpdFont* getFont(EpdFontStyle style) const;
-
- public:
-  explicit EpdFontFamily(const EpdFont* regular, const EpdFont* bold = nullptr, const EpdFont* italic = nullptr,
-                         const EpdFont* boldItalic = nullptr)
-      : regular(regular), bold(bold), italic(italic), boldItalic(boldItalic) {}
-  ~EpdFontFamily() = default;
-  void getTextDimensions(const char* string, int* w, int* h, EpdFontStyle style = REGULAR) const;
-  bool hasPrintableChars(const char* string, EpdFontStyle style = REGULAR) const;
-
-  const EpdFontData* getData(EpdFontStyle style = REGULAR) const;
-  const EpdGlyph* getGlyph(uint32_t cp, EpdFontStyle style = REGULAR) const;
+  const EpdFont* getFont(Style style) const;
 };

lib/EpdFont/FontDecompressor.cpp

@@ -0,0 +1,524 @@
+#include "FontDecompressor.h"
+
+#include <Arduino.h>
+#include <Logging.h>
+#include <Utf8.h>
+
+#include <cstdlib>
+
+FontDecompressor::~FontDecompressor() { deinit(); }
+
+bool FontDecompressor::init() {
+  clearCache();
+  return true;
+}
+
+void FontDecompressor::deinit() {
+  freePageBuffer();
+  freeHotGroup();
+}
+
+void FontDecompressor::clearCache() {
+  freePageBuffer();
+  freeHotGroup();
+}
+
+void FontDecompressor::freePageBuffer() {
+  for (uint8_t s = 0; s < pageSlotCount; s++) {
+    free(pageSlots[s].buffer);
+    free(pageSlots[s].glyphs);
+    pageSlots[s] = {};
+  }
+  pageSlotCount = 0;
+}
+
+void FontDecompressor::freeHotGroup() {
+  free(hotGroup);
+  hotGroup = nullptr;
+  hotGroupCapacity = 0;
+  hotGroupFont = nullptr;
+  hotGroupIndex = UINT16_MAX;
+  free(hotGlyphBuf);
+  hotGlyphBuf = nullptr;
+  hotGlyphBufCapacity = 0;
+}
+
+bool FontDecompressor::ensureCapacity(uint8_t*& buf, uint32_t& capacity, uint32_t needed) {
+  if (capacity >= needed) return true;
+  // Grow-only, free-then-malloc: every caller fully rewrites the buffer after a grow, so the
+  // old contents are dead -- freeing first gives the allocator its best shot on a tight heap.
+  free(buf);
+  buf = static_cast<uint8_t*>(malloc(needed));  // owned by FontDecompressor, freed in freeHotGroup()
+  capacity = buf ? needed : 0;
+  return buf != nullptr;
+}
+
+uint16_t FontDecompressor::getGroupIndex(const EpdFontData* fontData, uint32_t glyphIndex) {
+  // O(1) path for frequency-grouped fonts with glyphToGroup mapping
+  if (fontData->glyphToGroup != nullptr) {
+    return fontData->glyphToGroup[glyphIndex];
+  }
+
+  // Contiguous-group fonts: linear scan
+  for (uint16_t i = 0; i < fontData->groupCount; i++) {
+    uint32_t first = fontData->groups[i].firstGlyphIndex;
+    if (glyphIndex >= first && glyphIndex < first + fontData->groups[i].glyphCount) {
+      return i;
+    }
+  }
+  return fontData->groupCount;  // sentinel = not found
+}
+
+bool FontDecompressor::decompressGroup(const EpdFontData* fontData, uint16_t groupIndex, uint8_t* outBuf,
+                                       uint32_t outSize) {
+  const EpdFontGroup& group = fontData->groups[groupIndex];
+
+  const uint32_t tDecomp = millis();
+  inflateReader.init(false);
+  inflateReader.setSource(&fontData->bitmap[group.compressedOffset], group.compressedSize);
+  if (!inflateReader.read(outBuf, outSize)) {
+    stats.decompressTimeMs += millis() - tDecomp;
+    LOG_ERR("FDC", "Decompression failed for group %u", groupIndex);
+    return false;
+  }
+  stats.decompressTimeMs += millis() - tDecomp;
+  return true;
+}
+
+// --- Byte-aligned helpers ---
+
+uint32_t FontDecompressor::getAlignedOffset(const EpdFontData* fontData, uint16_t groupIndex, uint32_t glyphIndex) {
+  uint32_t offset = 0;
+
+  auto accumGlyph = [&](const EpdGlyph& g) {
+    if (g.width > 0 && g.height > 0) {
+      offset += ((g.width + 3) / 4) * g.height;
+    }
+  };
+
+  if (fontData->glyphToGroup) {
+    // Frequency-grouped: scan glyphs before glyphIndex that belong to this group
+    for (uint32_t i = 0; i < glyphIndex; i++) {
+      if (fontData->glyphToGroup[i] == groupIndex) {
+        accumGlyph(fontData->glyph[i]);
+      }
+    }
+  } else {
+    // Contiguous-group: sum aligned sizes of preceding glyphs in the group
+    const EpdFontGroup& group = fontData->groups[groupIndex];
+    for (uint32_t i = group.firstGlyphIndex; i < glyphIndex; i++) {
+      accumGlyph(fontData->glyph[i]);
+    }
+  }
+
+  return offset;
+}
+
+void FontDecompressor::compactSingleGlyph(const uint8_t* alignedSrc, uint8_t* packedDst, uint8_t width,
+                                          uint8_t height) {
+  if (width == 0 || height == 0) return;
+  const uint32_t rowStride = (width + 3) / 4;
+  if (width % 4 == 0) {
+    memcpy(packedDst, alignedSrc, rowStride * height);
+    return;
+  }
+  uint8_t outByte = 0, outBits = 0;
+  uint32_t writeIdx = 0;
+  for (uint8_t y = 0; y < height; y++) {
+    for (uint8_t x = 0; x < width; x++) {
+      outByte = (outByte << 2) | ((alignedSrc[y * rowStride + x / 4] >> ((3 - (x % 4)) * 2)) & 0x3);
+      outBits += 2;
+      if (outBits == 8) {
+        packedDst[writeIdx++] = outByte;
+        outByte = 0;
+        outBits = 0;
+      }
+    }
+  }
+  if (outBits > 0) packedDst[writeIdx] = outByte << (8 - outBits);
+}
+
+// --- getBitmap: page buffer → hot group → decompress ---
+
+const uint8_t* FontDecompressor::getBitmap(const EpdFontData* fontData, const EpdGlyph* glyph, uint32_t glyphIndex) {
+  const uint32_t tStart = micros();
+  stats.getBitmapCalls++;
+
+  if (!fontData->groups || fontData->groupCount == 0) {
+    stats.getBitmapTimeUs += micros() - tStart;
+    return &fontData->bitmap[glyph->dataOffset];
+  }
+
+  // Check page buffer slots (populated by prewarmCache — one slot per font style)
+  for (uint8_t s = 0; s < pageSlotCount; s++) {
+    const auto& slot = pageSlots[s];
+    if (slot.fontData != fontData || slot.glyphCount == 0) continue;
+
+    int left = 0, right = slot.glyphCount - 1;
+    while (left <= right) {
+      int mid = left + (right - left) / 2;
+      if (slot.glyphs[mid].glyphIndex == glyphIndex) {
+        if (slot.glyphs[mid].bufferOffset != UINT32_MAX) {
+          stats.cacheHits++;
+          stats.getBitmapTimeUs += micros() - tStart;
+          return &slot.buffer[slot.glyphs[mid].bufferOffset];
+        }
+        break;  // Not extracted during prewarm; fall through to hot-group path
+      }
+      if (slot.glyphs[mid].glyphIndex < glyphIndex)
+        left = mid + 1;
+      else
+        right = mid - 1;
+    }
+    break;  // Found the right slot but glyph wasn't in it; don't check other slots
+  }
+
+  // Fallback: hot group slot
+  uint16_t groupIndex = getGroupIndex(fontData, glyphIndex);
+  if (groupIndex >= fontData->groupCount) {
+    LOG_ERR("FDC", "Glyph %u not found in any group", glyphIndex);
+    stats.getBitmapTimeUs += micros() - tStart;
+    return nullptr;
+  }
+
+  // Check if hot group already has this group decompressed — if not, decompress it
+  if (!(hotGroup != nullptr && hotGroupFont == fontData && hotGroupIndex == groupIndex)) {
+    stats.cacheMisses++;
+    const EpdFontGroup& group = fontData->groups[groupIndex];
+
+    // ensureCapacity may free the buffer, so the cached-group identity dies with it either way.
+    hotGroupFont = nullptr;
+    hotGroupIndex = UINT16_MAX;
+    if (!ensureCapacity(hotGroup, hotGroupCapacity, group.uncompressedSize)) {
+      LOG_ERR("FDC", "Failed to allocate %u bytes for hot group %u", group.uncompressedSize, groupIndex);
+      stats.getBitmapTimeUs += micros() - tStart;
+      return nullptr;
+    }
+
+    if (!decompressGroup(fontData, groupIndex, hotGroup, group.uncompressedSize)) {
+      stats.getBitmapTimeUs += micros() - tStart;
+      return nullptr;
+    }
+
+    hotGroupFont = fontData;
+    hotGroupIndex = groupIndex;
+    stats.hotGroupBytes = group.uncompressedSize;
+  } else {
+    stats.cacheHits++;
+  }
+
+  // Compact just the requested glyph from byte-aligned data into scratch buffer
+  if (!ensureCapacity(hotGlyphBuf, hotGlyphBufCapacity, glyph->dataLength)) {
+    LOG_ERR("FDC", "Failed to allocate %u bytes for glyph scratch", (unsigned)glyph->dataLength);
+    stats.getBitmapTimeUs += micros() - tStart;
+    return nullptr;
+  }
+
+  uint32_t alignedOff = getAlignedOffset(fontData, groupIndex, glyphIndex);
+  compactSingleGlyph(&hotGroup[alignedOff], hotGlyphBuf, glyph->width, glyph->height);
+  stats.getBitmapTimeUs += micros() - tStart;
+  return hotGlyphBuf;
+}
+
+// --- Prewarm: pre-decompress glyph bitmaps for a page of text ---
+
+int32_t FontDecompressor::findGlyphIndex(const EpdFontData* fontData, uint32_t codepoint) {
+  const EpdUnicodeInterval* intervals = fontData->intervals;
+  const int count = fontData->intervalCount;
+
+  if (count == 0) return -1;
+
+  // Binary search
+  int left = 0;
+  int right = count - 1;
+
+  while (left <= right) {
+    const int mid = left + (right - left) / 2;
+    const EpdUnicodeInterval* interval = &intervals[mid];
+
+    if (codepoint < interval->first) {
+      right = mid - 1;
+    } else if (codepoint > interval->last) {
+      left = mid + 1;
+    } else {
+      return static_cast<int32_t>(interval->offset + (codepoint - interval->first));
+    }
+  }
+
+  return -1;
+}
+
+int FontDecompressor::prewarmCache(const EpdFontData* fontData, const char* utf8Text) {
+  if (!fontData || !fontData->groups || !utf8Text) return 0;
+
+  // Allocate the next available slot (caller must call freePageBuffer/clearCache to reset)
+  if (pageSlotCount >= MAX_PAGE_SLOTS) {
+    LOG_ERR("FDC", "All %u page buffer slots full, cannot prewarm fontData=%p", MAX_PAGE_SLOTS, (void*)fontData);
+    return -1;
+  }
+  PageSlot& slot = pageSlots[pageSlotCount];
+
+  // Step 1: Collect unique glyph indices needed for this page
+  uint32_t neededGlyphs[MAX_PAGE_GLYPHS];
+  uint16_t glyphCount = 0;
+  bool glyphCapWarned = false;
+
+  const unsigned char* p = reinterpret_cast<const unsigned char*>(utf8Text);
+  while (*p) {
+    uint32_t cp = utf8NextCodepoint(&p);
+    if (cp == 0) break;
+
+    int32_t glyphIdx = findGlyphIndex(fontData, cp);
+    if (glyphIdx < 0) continue;
+
+    // Deduplicate
+    bool found = false;
+    for (uint16_t i = 0; i < glyphCount; i++) {
+      if (neededGlyphs[i] == static_cast<uint32_t>(glyphIdx)) {
+        found = true;
+        break;
+      }
+    }
+    if (!found) {
+      if (glyphCount < MAX_PAGE_GLYPHS) {
+        neededGlyphs[glyphCount++] = static_cast<uint32_t>(glyphIdx);
+      } else if (!glyphCapWarned) {
+        LOG_DBG("FDC", "Glyph cap (%u) reached during prewarm; excess glyphs will use hot-group fallback",
+                MAX_PAGE_GLYPHS);
+        glyphCapWarned = true;
+      }
+    }
+  }
+
+  // Add ligature output glyphs: if both input codepoints of a ligature pair are
+  // in the needed set, the output glyph will be queried during rendering.
+  if (fontData->ligaturePairs && fontData->ligaturePairCount > 0) {
+    for (uint32_t li = 0; li < fontData->ligaturePairCount && glyphCount < MAX_PAGE_GLYPHS; li++) {
+      uint32_t leftCp = fontData->ligaturePairs[li].pair >> 16;
+      uint32_t rightCp = fontData->ligaturePairs[li].pair & 0xFFFF;
+
+      int32_t leftIdx = findGlyphIndex(fontData, leftCp);
+      int32_t rightIdx = findGlyphIndex(fontData, rightCp);
+      if (leftIdx < 0 || rightIdx < 0) continue;
+
+      // Check if both inputs are in neededGlyphs
+      bool hasLeft = false, hasRight = false;
+      for (uint16_t i = 0; i < glyphCount; i++) {
+        if (neededGlyphs[i] == static_cast<uint32_t>(leftIdx)) hasLeft = true;
+        if (neededGlyphs[i] == static_cast<uint32_t>(rightIdx)) hasRight = true;
+        if (hasLeft && hasRight) break;
+      }
+      if (!hasLeft || !hasRight) continue;
+
+      int32_t outIdx = findGlyphIndex(fontData, fontData->ligaturePairs[li].ligatureCp);
+      if (outIdx < 0) continue;
+
+      // Deduplicate
+      bool found = false;
+      for (uint16_t i = 0; i < glyphCount; i++) {
+        if (neededGlyphs[i] == static_cast<uint32_t>(outIdx)) {
+          found = true;
+          break;
+        }
+      }
+      if (!found) {
+        neededGlyphs[glyphCount++] = static_cast<uint32_t>(outIdx);
+      }
+    }
+  }
+
+  if (glyphCount == 0) return 0;
+
+  // Step 2: Compute total buffer size and collect unique groups
+  uint32_t totalBytes = 0;
+  uint16_t neededGroups[128];
+  uint8_t groupCount = 0;
+  bool groupCapWarned = false;
+
+  for (uint16_t i = 0; i < glyphCount; i++) {
+    totalBytes += fontData->glyph[neededGlyphs[i]].dataLength;
+    uint16_t gi = getGroupIndex(fontData, neededGlyphs[i]);
+    bool found = false;
+    for (uint8_t j = 0; j < groupCount; j++) {
+      if (neededGroups[j] == gi) {
+        found = true;
+        break;
+      }
+    }
+    if (!found) {
+      if (groupCount < 128) {
+        neededGroups[groupCount++] = gi;
+      } else if (!groupCapWarned) {
+        LOG_DBG("FDC", "Group cap (128) reached during prewarm; some groups will use hot-group fallback");
+        groupCapWarned = true;
+      }
+    }
+  }
+
+  stats.uniqueGroupsAccessed = groupCount;
+
+  // Step 3: Allocate page buffer and lookup table for this slot
+  slot.buffer = static_cast<uint8_t*>(malloc(totalBytes));
+  slot.glyphs = static_cast<PageGlyphEntry*>(malloc(glyphCount * sizeof(PageGlyphEntry)));
+  if (!slot.buffer || !slot.glyphs) {
+    LOG_ERR("FDC", "Failed to allocate page buffer (%u bytes, %u glyphs)", totalBytes, glyphCount);
+    free(slot.buffer);
+    free(slot.glyphs);
+    slot = {};
+    return glyphCount;
+  }
+  stats.pageBufferBytes += totalBytes;
+  stats.pageGlyphsBytes += glyphCount * sizeof(PageGlyphEntry);
+
+  slot.fontData = fontData;
+  slot.glyphCount = glyphCount;
+  pageSlotCount++;
+
+  // Initialize lookup entries (bufferOffset = UINT32_MAX means not yet extracted)
+  for (uint16_t i = 0; i < glyphCount; i++) {
+    slot.glyphs[i] = {neededGlyphs[i], UINT32_MAX, 0};
+  }
+
+  // Sort by glyphIndex for binary search in getBitmap()
+  for (uint16_t i = 1; i < glyphCount; i++) {
+    PageGlyphEntry key = slot.glyphs[i];
+    int j = i - 1;
+    while (j >= 0 && slot.glyphs[j].glyphIndex > key.glyphIndex) {
+      slot.glyphs[j + 1] = slot.glyphs[j];
+      j--;
+    }
+    slot.glyphs[j + 1] = key;
+  }
+
+  // Step 3b: Pre-scan to compute each needed glyph's byte-aligned offset within its group.
+  // This avoids recomputing aligned offsets per group during extraction in step 4.
+  uint32_t groupAlignedTracker[128] = {};  // running byte-aligned offset for each needed group
+
+  if (fontData->glyphToGroup) {
+    // Frequency-grouped: single O(totalGlyphs) pass through glyphToGroup
+    const auto& lastInterval = fontData->intervals[fontData->intervalCount - 1];
+    const uint32_t totalGlyphs = lastInterval.offset + (lastInterval.last - lastInterval.first + 1);
+
+    for (uint32_t i = 0; i < totalGlyphs; i++) {
+      const uint16_t gi = fontData->glyphToGroup[i];
+      // Find this glyph's group position in neededGroups
+      uint8_t gpPos = groupCount;
+      for (uint8_t j = 0; j < groupCount; j++) {
+        if (neededGroups[j] == gi) {
+          gpPos = j;
+          break;
+        }
+      }
+      if (gpPos == groupCount) continue;  // not a needed group
+
+      const EpdGlyph& glyph = fontData->glyph[i];
+
+      // Binary search in sorted slot.glyphs to find if glyph i is needed
+      int left = 0, right = (int)slot.glyphCount - 1;
+      while (left <= right) {
+        const int mid = left + (right - left) / 2;
+        if (slot.glyphs[mid].glyphIndex == i) {
+          slot.glyphs[mid].alignedOffset = groupAlignedTracker[gpPos];
+          break;
+        }
+        if (slot.glyphs[mid].glyphIndex < i)
+          left = mid + 1;
+        else
+          right = mid - 1;
+      }
+
+      if (glyph.width > 0 && glyph.height > 0) {
+        groupAlignedTracker[gpPos] += ((glyph.width + 3) / 4) * glyph.height;
+      }
+    }
+  } else {
+    // Contiguous-group: iterate each needed group's glyphs directly
+    for (uint8_t g = 0; g < groupCount; g++) {
+      const EpdFontGroup& group = fontData->groups[neededGroups[g]];
+      uint32_t alignedOff = 0;
+      for (uint16_t j = 0; j < group.glyphCount; j++) {
+        const uint32_t glyphI = group.firstGlyphIndex + j;
+        const EpdGlyph& glyph = fontData->glyph[glyphI];
+
+        int left = 0, right = (int)slot.glyphCount - 1;
+        while (left <= right) {
+          const int mid = left + (right - left) / 2;
+          if (slot.glyphs[mid].glyphIndex == glyphI) {
+            slot.glyphs[mid].alignedOffset = alignedOff;
+            break;
+          }
+          if (slot.glyphs[mid].glyphIndex < glyphI)
+            left = mid + 1;
+          else
+            right = mid - 1;
+        }
+
+        if (glyph.width > 0 && glyph.height > 0) {
+          alignedOff += ((glyph.width + 3) / 4) * glyph.height;
+        }
+      }
+    }
+  }
+
+  // Step 4: For each unique group, decompress to temp buffer and extract needed glyphs
+  uint32_t writeOffset = 0;
+  int missed = 0;
+
+  for (uint8_t g = 0; g < groupCount; g++) {
+    uint16_t groupIdx = neededGroups[g];
+    const EpdFontGroup& group = fontData->groups[groupIdx];
+
+    auto* tempBuf = static_cast<uint8_t*>(malloc(group.uncompressedSize));
+    if (!tempBuf) {
+      LOG_ERR("FDC", "Failed to allocate temp buffer (%u bytes) for group %u", group.uncompressedSize, groupIdx);
+      missed++;
+      continue;
+    }
+    if (group.uncompressedSize > stats.peakTempBytes) {
+      stats.peakTempBytes = group.uncompressedSize;
+    }
+
+    if (!decompressGroup(fontData, groupIdx, tempBuf, group.uncompressedSize)) {
+      free(tempBuf);
+      missed++;
+      continue;
+    }
+
+    // Extract needed glyphs directly from the byte-aligned temp buffer, compacting on the fly.
+    // alignedOffset was pre-computed in step 3b — no full-group compact scan needed.
+    for (uint16_t i = 0; i < slot.glyphCount; i++) {
+      if (slot.glyphs[i].bufferOffset != UINT32_MAX) continue;  // already extracted
+      if (getGroupIndex(fontData, slot.glyphs[i].glyphIndex) != groupIdx) continue;
+
+      const EpdGlyph& glyph = fontData->glyph[slot.glyphs[i].glyphIndex];
+      compactSingleGlyph(&tempBuf[slot.glyphs[i].alignedOffset], &slot.buffer[writeOffset], glyph.width, glyph.height);
+      slot.glyphs[i].bufferOffset = writeOffset;
+      writeOffset += glyph.dataLength;
+    }
+
+    free(tempBuf);
+  }
+
+  LOG_DBG("FDC", "Prewarm: %u glyphs in %u bytes from %u groups (%d missed)", glyphCount, writeOffset, groupCount,
+          missed);
+
+  return missed;
+}
+
+// --- Stats ---
+
+void FontDecompressor::resetStats() { stats = Stats{}; }
+
+void FontDecompressor::logStats(const char* label) {
+  const uint32_t total = stats.cacheHits + stats.cacheMisses;
+  LOG_DBG("FDC", "[%s] hits=%lu misses=%lu (%.1f%% hit rate)", label, stats.cacheHits, stats.cacheMisses,
+          total > 0 ? 100.0f * stats.cacheHits / total : 0.0f);
+  LOG_DBG("FDC", "[%s] decompress=%lums groups_accessed=%u", label, stats.decompressTimeMs, stats.uniqueGroupsAccessed);
+  LOG_DBG("FDC", "[%s] mem: pageBuf=%lu pageGlyphs=%lu hotGroup=%lu peakTemp=%lu", label, stats.pageBufferBytes,
+          stats.pageGlyphsBytes, stats.hotGroupBytes, stats.peakTempBytes);
+  if (stats.getBitmapCalls > 0) {
+    LOG_DBG("FDC", "[%s] getBitmap: %lu calls, %luus total, %luus/call avg", label, stats.getBitmapCalls,
+            stats.getBitmapTimeUs, stats.getBitmapTimeUs / stats.getBitmapCalls);
+  }
+  resetStats();
+}

lib/EpdFont/FontDecompressor.h

@@ -0,0 +1,92 @@
+#pragma once
+
+#include <InflateReader.h>
+
+#include "EpdFontData.h"
+
+class FontDecompressor {
+ public:
+  static constexpr uint16_t MAX_PAGE_GLYPHS = 512;
+  static constexpr uint8_t MAX_PAGE_SLOTS = 4;  // One per font style (R/B/I/BI)
+
+  FontDecompressor() = default;
+  ~FontDecompressor();
+
+  bool init();
+  void deinit();
+
+  // Returns pointer to decompressed bitmap data for the given glyph.
+  // Checks the page buffer (from prewarm) first, then falls back to the hot group slot.
+  const uint8_t* getBitmap(const EpdFontData* fontData, const EpdGlyph* glyph, uint32_t glyphIndex);
+
+  // Free all cached data (page buffer + hot group).
+  void clearCache();
+
+  // Pre-scan UTF-8 text and extract needed glyph bitmaps into a flat page buffer.
+  // Each group is decompressed once into a temp buffer; only needed glyphs are kept.
+  // Returns the number of glyphs that couldn't be loaded (0 on full success).
+  int prewarmCache(const EpdFontData* fontData, const char* utf8Text);
+
+  struct Stats {
+    uint32_t cacheHits = 0;
+    uint32_t cacheMisses = 0;
+    uint32_t decompressTimeMs = 0;
+    uint16_t uniqueGroupsAccessed = 0;
+    uint32_t pageBufferBytes = 0;  // pageBuffer allocation
+    uint32_t pageGlyphsBytes = 0;  // pageGlyphs lookup table allocation
+    uint32_t hotGroupBytes = 0;    // current hot group allocation
+    uint32_t peakTempBytes = 0;    // largest temp buffer in prewarm
+    uint32_t getBitmapTimeUs = 0;  // cumulative getBitmap time (micros)
+    uint32_t getBitmapCalls = 0;   // number of getBitmap calls
+  };
+  void logStats(const char* label = "FDC");
+  void resetStats();
+  const Stats& getStats() const { return stats; }
+
+ private:
+  Stats stats;
+  InflateReader inflateReader;
+
+  // Page buffer slots: each style gets its own flat glyph buffer with sorted lookup.
+  // Up to MAX_PAGE_SLOTS (4) styles can be prewarmed simultaneously.
+  struct PageGlyphEntry {
+    uint32_t glyphIndex;
+    uint32_t bufferOffset;
+    uint32_t alignedOffset;  // byte-aligned offset within its decompressed group (set during prewarm pre-scan)
+  };
+  struct PageSlot {
+    uint8_t* buffer = nullptr;
+    const EpdFontData* fontData = nullptr;
+    PageGlyphEntry* glyphs = nullptr;
+    uint16_t glyphCount = 0;
+  };
+  PageSlot pageSlots[MAX_PAGE_SLOTS] = {};
+  uint8_t pageSlotCount = 0;
+
+  // Hot group: last decompressed group (byte-aligned) for non-prewarmed fallback path.
+  // Kept in byte-aligned format; individual glyphs are compacted on demand into hotGlyphBuf.
+  // Nothrow high-water malloc buffers, NOT std::vector: getBitmap() runs on the render path,
+  // and under -fno-exceptions a vector resize that hits OOM abort()s the firmware instead of
+  // failing (field crash: hotGroup.resize() -> std::bad_alloc -> abort with ~11 KB free).
+  // ensureCapacity() returns false on OOM so the caller can skip the glyph gracefully.
+  const EpdFontData* hotGroupFont = nullptr;
+  uint16_t hotGroupIndex = UINT16_MAX;
+  uint8_t* hotGroup = nullptr;  // owned; freed in freeHotGroup()/dtor
+  uint32_t hotGroupCapacity = 0;
+
+  // Scratch buffer for compacting a single glyph from the hot group.
+  // Valid until the next getBitmap() call. Same ownership/OOM contract as hotGroup.
+  uint8_t* hotGlyphBuf = nullptr;
+  uint32_t hotGlyphBufCapacity = 0;
+
+  // Grow (never shrink) an owned buffer to at least `needed` bytes; false on OOM, buffer freed.
+  static bool ensureCapacity(uint8_t*& buf, uint32_t& capacity, uint32_t needed);
+
+  void freePageBuffer();
+  void freeHotGroup();
+  uint16_t getGroupIndex(const EpdFontData* fontData, uint32_t glyphIndex);
+  uint32_t getAlignedOffset(const EpdFontData* fontData, uint16_t groupIndex, uint32_t glyphIndex);
+  bool decompressGroup(const EpdFontData* fontData, uint16_t groupIndex, uint8_t* outBuf, uint32_t outSize);
+  static void compactSingleGlyph(const uint8_t* alignedSrc, uint8_t* packedDst, uint8_t width, uint8_t height);
+  static int32_t findGlyphIndex(const EpdFontData* fontData, uint32_t codepoint);
+};

lib/EpdFont/SdCardFont.h

@@ -0,0 +1,268 @@
+#pragma once
+
+#include <cstdint>
+#include <string>
+#include <vector>
+
+#include "EpdFont.h"
+#include "EpdFontData.h"
+
+// On-disk binary format version for .cpfont files. Defined as a preprocessor
+// macro (rather than a constexpr) so it can be stringified into the SD-fonts
+// release URL — see FONT_MANIFEST_URL in FontDownloadActivity.h. No integer
+// suffix because stringification would include it (e.g. `4U` → `"4U"`).
+//
+// The canonical version for the build tooling lives in
+// lib/EpdFont/scripts/cpfont_version.py. This firmware-side copy must be
+// bumped manually when the firmware is updated to support a new format.
+// Reader enforcement: SdCardFont::load().
+#define CPFONT_VERSION 4
+
+class SdCardFont {
+ public:
+  static constexpr uint16_t MAX_PAGE_GLYPHS = 512;
+  static constexpr uint8_t MAX_STYLES = 4;
+
+  SdCardFont() = default;
+  ~SdCardFont();
+  // Owns raw buffers freed in dtor — no shallow-copy semantics. Make any
+  // accidental pass-by-value or move a compile-time error.
+  SdCardFont(const SdCardFont&) = delete;
+  SdCardFont& operator=(const SdCardFont&) = delete;
+  SdCardFont(SdCardFont&&) = delete;
+  SdCardFont& operator=(SdCardFont&&) = delete;
+
+  // Load .cpfont file: reads header + intervals into RAM, records file layout offsets.
+  // Supports v4 (multi-style) format.
+  // Returns true on success.
+  bool load(const char* path);
+
+  // Pre-read glyphs needed for the given UTF-8 text from SD card.
+  // styleMask: bitmask of styles to prewarm (bit 0=regular, 1=bold, 2=italic, 3=bolditalic).
+  // Default 0x0F = all present styles.
+  // When metadataOnly=true, only glyph metrics are loaded (no bitmap data).
+  // Returns number of glyphs that couldn't be loaded (0 on full success).
+  int prewarm(const char* utf8Text, uint8_t styleMask = 0x0F, bool metadataOnly = false);
+
+  // Build a compact advance-only table for layout measurement.
+  // Extracts ALL unique codepoints from words (no MAX_PAGE_GLYPHS cap),
+  // batch-reads advanceX from SD, stores in a sorted per-style table.
+  // extraText: optional additional codepoints to warm in the same SD pass
+  // (e.g. shaped Arabic presentation forms the measurement path will look up).
+  // Returns number of codepoints not found in font coverage.
+  int buildAdvanceTable(const char* utf8Text, uint8_t styleMask = 0x0F, const char* extraText = nullptr);
+  int buildAdvanceTable(const std::vector<std::string>& words, bool includeHyphen, uint8_t styleMask = 0x0F,
+                        const char* extraText = nullptr);
+
+  // Look up advanceX for a codepoint from the advance table.
+  // Returns the 12.4 fixed-point advance, or 0 if not found.
+  uint16_t getAdvance(uint32_t codepoint, uint8_t style) const;
+
+  // Returns true if advance table is populated for at least one style.
+  bool hasAdvanceTable() const;
+
+  // Free mini data for all styles and restore stub EpdFontData.
+  // Preserves the persistent advance cache so repeated layout passes can reuse
+  // previously fetched metrics.
+  void clearCache();
+
+  // Drop the persistent advance cache. Call when unloading the SD font or
+  // when font/size/family/glyph-table state changes.
+  void clearPersistentCache();
+
+  // Returns pointer to the managed EpdFont for a given style.
+  // Returns nullptr if the style is not present.
+  EpdFont* getEpdFont(uint8_t style = 0);
+
+  // Returns true if the given style is present in this font file.
+  bool hasStyle(uint8_t style) const;
+
+  // Resolve requested style bits to the closest present style.
+  uint8_t resolveStyle(uint8_t style) const;
+
+  // Resolve every requested style bit through fallback and return the actual
+  // styles that need cache/advance preparation.
+  uint8_t resolveStyleMask(uint8_t styleMask) const;
+
+  // Number of styles present in this font file.
+  uint8_t styleCount() const { return styleCount_; }
+
+  // Returns true if the glyph pointer points into the overflow buffer.
+  bool isOverflowGlyph(const EpdGlyph* glyph) const;
+
+  // Returns the bitmap for an on-demand-loaded (overflow) glyph.
+  const uint8_t* getOverflowBitmap(const EpdGlyph* glyph) const;
+
+  // Extract SdCardFont* from an opaque glyphMissCtx pointer.
+  // Used by GfxRenderer::getGlyphBitmap() to recover the SdCardFont from EpdFontData::glyphMissCtx.
+  static SdCardFont* fromMissCtx(void* ctx);
+
+  struct Stats {
+    uint32_t prewarmTotalMs = 0;
+    uint32_t sdReadTimeMs = 0;
+    uint32_t seekCount = 0;
+    uint32_t uniqueGlyphs = 0;
+    uint32_t bitmapBytes = 0;
+  };
+  void logStats(const char* label = "SDCF");
+  void resetStats();
+  const Stats& getStats() const { return stats_; }
+
+  // Content hash of the file header + style TOC entries (computed during load).
+  // Used to generate deterministic font IDs for section cache invalidation.
+  uint32_t contentHash() const { return contentHash_; }
+
+ private:
+  // Per-style metadata (parsed from file header/TOC)
+  struct CpFontHeader {
+    uint32_t intervalCount = 0;
+    uint32_t glyphCount = 0;
+    uint8_t advanceY = 0;
+    int16_t ascender = 0;
+    int16_t descender = 0;
+    bool is2Bit = false;
+    uint16_t kernLeftEntryCount = 0;
+    uint16_t kernRightEntryCount = 0;
+    uint8_t kernLeftClassCount = 0;
+    uint8_t kernRightClassCount = 0;
+    uint8_t ligaturePairCount = 0;
+  };
+
+  // All per-style data: file offsets, intervals, kern/lig, prewarm cache, EpdFont
+  struct PerStyle {
+    CpFontHeader header{};
+
+    // File layout offsets for this style's data sections
+    uint32_t intervalsFileOffset = 0;
+    uint32_t glyphsFileOffset = 0;
+    uint32_t kernLeftFileOffset = 0;
+    uint32_t kernRightFileOffset = 0;
+    uint32_t kernMatrixFileOffset = 0;
+    uint32_t ligatureFileOffset = 0;
+    uint32_t bitmapFileOffset = 0;
+
+    // Full intervals loaded from file (kept in RAM for codepoint lookup)
+    EpdUnicodeInterval* fullIntervals = nullptr;
+    EPD_PACKED_BEGIN
+    struct BmpInterval16 {
+      uint16_t first;
+      uint16_t last;
+      uint16_t offset;
+    } EPD_PACKED_ATTR;
+    EPD_PACKED_END
+    static_assert(sizeof(BmpInterval16) == 6, "BmpInterval16 must remain compact");
+    BmpInterval16* bmpIntervals = nullptr;
+    bool intervalsAreBmp16 = false;
+
+    // Persistent kern-class + ligature tables (lazy-loaded on first prewarm).
+    // The full kern MATRIX is NOT resident — on Literata-class fonts a single
+    // style's matrix is ~36-42KB contiguous, and 4 styles' worth won't fit
+    // alongside bitmaps + framebuffer on a 380KB device. Only kernLeftClasses
+    // and kernRightClasses (small codepoint→classId tables, ~3KB each) stay
+    // resident; the matrix is reconstructed per-page as miniKernMatrix.
+    EpdKernClassEntry* kernLeftClasses = nullptr;
+    EpdKernClassEntry* kernRightClasses = nullptr;
+    EpdLigaturePair* ligaturePairs = nullptr;
+    bool kernLigLoaded = false;
+
+    // Stub EpdFontData returned when not prewarmed
+    EpdFontData stubData{};
+
+    // Mini EpdFontData built during prewarm
+    EpdFontData miniData{};
+    EpdUnicodeInterval* miniIntervals = nullptr;
+    EpdGlyph* miniGlyphs = nullptr;
+    uint8_t* miniBitmap = nullptr;
+    uint32_t miniIntervalCount = 0;
+    uint32_t miniGlyphCount = 0;
+
+    // Per-page mini kern matrix (built by buildMiniKernMatrix on each full
+    // prewarm). miniKernLeftClasses/miniKernRightClasses map ONLY the codepoints
+    // used on the current page to renumbered class IDs (1..miniKern*ClassCount).
+    // miniKernMatrix is a small miniKernLeftClassCount × miniKernRightClassCount
+    // flat matrix. Typical Latin page: ~25×25 matrix = ~625 bytes per style vs
+    // ~36KB for the full Literata matrix — ~50× reduction.
+    EpdKernClassEntry* miniKernLeftClasses = nullptr;
+    EpdKernClassEntry* miniKernRightClasses = nullptr;
+    uint16_t miniKernLeftEntryCount = 0;
+    uint16_t miniKernRightEntryCount = 0;
+    uint8_t miniKernLeftClassCount = 0;
+    uint8_t miniKernRightClassCount = 0;
+    int8_t* miniKernMatrix = nullptr;
+
+    // The EpdFont whose data pointer we manage
+    EpdFont epdFont{&stubData};
+
+    bool present = false;
+  };
+
+  PerStyle styles_[MAX_STYLES] = {};
+  uint8_t styleCount_ = 0;
+
+  char filePath_[128] = {};
+
+  // Overflow context: glyphMissHandler needs to know which style it's serving
+  struct OverflowContext {
+    SdCardFont* self;
+    uint8_t styleIdx;
+  };
+  OverflowContext overflowCtx_[MAX_STYLES] = {};
+
+  // Shared on-demand overflow buffer (ring buffer of glyphs loaded via glyphMissHandler)
+  static constexpr uint32_t OVERFLOW_CAPACITY = 8;
+  struct OverflowEntry {
+    EpdGlyph glyph;
+    uint8_t* bitmap = nullptr;
+    uint32_t codepoint = 0;
+    uint8_t styleIdx = 0;
+  };
+  OverflowEntry overflow_[OVERFLOW_CAPACITY] = {};
+  uint32_t overflowCount_ = 0;
+  uint32_t overflowNext_ = 0;
+
+  // Compact advance-only table for layout measurement (per-style).
+  // Built by buildAdvanceTable(), queried by getAdvance().
+  struct AdvanceEntry {
+    uint32_t codepoint;
+    uint16_t advanceX;  // 12.4 fixed-point
+  };
+  // Per-style advance table. Sorted by codepoint for binary lookup.
+  // Bounded to ADVANCE_CACHE_LIMIT entries; persists across layout passes
+  // (across calls to clearCache()) so repeated indexing of the same font
+  // amortizes SD reads. Cleared only on font unload or clearPersistentCache().
+  static constexpr uint32_t ADVANCE_CACHE_LIMIT = 768;
+  AdvanceEntry* advanceTable_[MAX_STYLES] = {};
+  uint32_t advanceTableSize_[MAX_STYLES] = {};
+  bool advanceTableLookup(uint8_t styleIdx, uint32_t codepoint, uint16_t* outAdvance) const;
+  // Merge sortedNew (sorted by codepoint, no overlap with existing) into the
+  // advance table for styleIdx, preserving sort order; cap-truncates the tail.
+  void mergeIntoAdvanceTable(uint8_t styleIdx, const AdvanceEntry* sortedNew, uint32_t newCount);
+
+  Stats stats_;
+  uint32_t contentHash_ = 0;
+  bool loaded_ = false;
+
+  // Per-style helpers
+  void freeStyleMiniData(PerStyle& s);
+  void freeStyleAll(PerStyle& s);
+  void freeStyleKernLigatureData(PerStyle& s);
+  void freeStyleMiniKern(PerStyle& s);
+  bool loadStyleKernLigatureData(PerStyle& s);
+  bool buildMiniKernMatrix(PerStyle& s, const uint32_t* codepoints, uint32_t cpCount);
+  void applyKernLigaturePointers(PerStyle& s, EpdFontData& data) const;
+  void applyGlyphMissCallback(uint8_t styleIdx);
+  int32_t findGlobalGlyphIndex(const PerStyle& s, uint32_t codepoint) const;
+  int fetchAdvancesForCodepoints(uint32_t* codepoints, uint32_t cpCount, uint8_t styleMask);
+  template <typename Iter>
+  int buildAdvanceTableRange(Iter begin, Iter end, bool includeSpace, bool includeHyphen, uint8_t styleMask,
+                             const char* extraText = nullptr);
+  int prewarmStyle(uint8_t styleIdx, const uint32_t* codepoints, uint32_t cpCount, bool metadataOnly);
+
+  // Global helpers
+  void freeAll();
+  void clearOverflow();
+  static void computeStyleFileOffsets(PerStyle& s, uint32_t baseOffset);
+
+  // Static callback for EpdFontData::glyphMissHandler (per-style via OverflowContext)
+  static const EpdGlyph* onGlyphMiss(void* ctx, uint32_t codepoint);
+};

lib/EpdFont/SdCardFontManager.cpp

@@ -0,0 +1,94 @@
+#include "SdCardFontManager.h"
+
+#include <EpdFontFamily.h>
+#include <GfxRenderer.h>
+#include <Logging.h>
+#include <SdCardFont.h>
+#include <SdCardFontRegistry.h>
+
+SdCardFontManager::~SdCardFontManager() {
+  for (auto& lf : loaded_) {
+    delete lf.font;
+  }
+}
+
+// FNV-1a continuation: seeds with contentHash, then hashes family name + point size.
+// Produces a deterministic ID that is stable across load/unload cycles and reboots,
+// and changes when font content changes (different header/TOC = different contentHash).
+int SdCardFontManager::computeFontId(uint32_t contentHash, const char* familyName, uint8_t pointSize) {
+  static constexpr uint32_t FNV_PRIME = 16777619u;
+  uint32_t hash = contentHash;
+  while (*familyName) {
+    hash ^= static_cast<uint8_t>(*familyName++);
+    hash *= FNV_PRIME;
+  }
+  hash ^= pointSize;
+  hash *= FNV_PRIME;
+  int id = static_cast<int>(hash);
+  return id != 0 ? id : 1;  // 0 is reserved as "not found" sentinel
+}
+
+bool SdCardFontManager::loadFamily(const SdCardFontFamilyInfo& family, GfxRenderer& renderer, uint8_t fontSizeEnum) {
+  // Unload any previously loaded family first
+  if (!loadedFamilyName_.empty()) {
+    unloadAll(renderer);
+  }
+
+  // Select the physical point size closest to the built-in reader sizes. Some
+  // CJK font packs only ship larger sizes, so ordinal selection can make
+  // MEDIUM load 18pt+ and produce oversized pages on small devices.
+  const SdCardFontFileInfo* selected = family.findClosestReaderSize(fontSizeEnum);
+  if (!selected) {
+    LOG_ERR("SDMGR", "Family %s has no files to load", family.name.c_str());
+    return false;
+  }
+
+  auto* font = new (std::nothrow) SdCardFont();
+  if (!font) {
+    LOG_ERR("SDMGR", "Failed to allocate SdCardFont for %s", selected->path.c_str());
+    return false;
+  }
+
+  if (!font->load(selected->path.c_str())) {
+    LOG_ERR("SDMGR", "Failed to load %s", selected->path.c_str());
+    delete font;
+    return false;
+  }
+
+  int fontId = computeFontId(font->contentHash(), family.name.c_str(), selected->pointSize);
+  // Guard against collision with built-in font IDs (astronomically unlikely
+  // with FNV-1a hashes, but provides a safety net)
+  if (renderer.getFontMap().count(fontId) != 0) {
+    LOG_ERR("SDMGR", "Font ID %d collides with existing font, skipping %s", fontId, selected->path.c_str());
+    delete font;
+    return false;
+  }
+  renderer.registerSdCardFont(fontId, font);
+  loaded_.push_back({font, fontId, selected->pointSize});
+
+  LOG_DBG("SDMGR", "Loaded %s size=%u id=%d styles=%u (sizeEnum=%u)", selected->path.c_str(), selected->pointSize,
+          fontId, font->styleCount(), fontSizeEnum);
+
+  EpdFontFamily fontFamily(font->getEpdFont(0), font->getEpdFont(1), font->getEpdFont(2), font->getEpdFont(3));
+  renderer.insertFont(fontId, fontFamily);
+
+  loadedFamilyName_ = family.name;
+  loadedPointSize_ = selected->pointSize;
+  return true;
+}
+
+void SdCardFontManager::unloadAll(GfxRenderer& renderer) {
+  renderer.clearSdCardFonts();
+  for (auto& lf : loaded_) {
+    renderer.removeFont(lf.fontId);
+    delete lf.font;
+  }
+  loaded_.clear();
+  loadedFamilyName_.clear();
+  loadedPointSize_ = 0;
+}
+
+int SdCardFontManager::getFontId(const std::string& familyName) const {
+  if (familyName != loadedFamilyName_ || loaded_.empty()) return 0;
+  return loaded_.front().fontId;
+}

lib/EpdFont/SdCardFontManager.h

@@ -0,0 +1,50 @@
+#pragma once
+
+#include <cstdint>
+#include <string>
+#include <vector>
+
+class GfxRenderer;
+class SdCardFont;
+struct SdCardFontFamilyInfo;
+
+class SdCardFontManager {
+ public:
+  SdCardFontManager() = default;
+  ~SdCardFontManager();
+  SdCardFontManager(const SdCardFontManager&) = delete;
+  SdCardFontManager& operator=(const SdCardFontManager&) = delete;
+
+  // Load the font file whose physical point size is closest to the reader
+  // fontSizeEnum (SMALL=12, MEDIUM=14, LARGE=16, EXTRA_LARGE=18). Only one
+  // .cpfont file is loaded; other sizes remain on disk. This keeps resident
+  // interval + kern/ligature tables to one size's worth of memory.
+  // Returns true on success.
+  bool loadFamily(const SdCardFontFamilyInfo& family, GfxRenderer& renderer, uint8_t fontSizeEnum);
+
+  // Unload everything, unregister from renderer.
+  void unloadAll(GfxRenderer& renderer);
+
+  // Look up the font ID for the loaded family. Returns 0 if nothing loaded
+  // or familyName doesn't match.
+  int getFontId(const std::string& familyName) const;
+
+  // Get name of currently loaded family (empty if none).
+  const std::string& currentFamilyName() const { return loadedFamilyName_; };
+
+  // Point size that was actually loaded.
+  // 0 if nothing loaded.
+  uint8_t currentPointSize() const { return loadedPointSize_; };
+
+ private:
+  struct LoadedFont {
+    SdCardFont* font;  // heap-allocated, owned
+    int fontId;
+    uint8_t size;
+  };
+  static int computeFontId(uint32_t contentHash, const char* familyName, uint8_t pointSize);
+
+  std::string loadedFamilyName_;
+  uint8_t loadedPointSize_ = 0;
+  std::vector<LoadedFont> loaded_;
+};

lib/EpdFont/SdCardFontRegistry.cpp

@@ -0,0 +1,284 @@
+#include "SdCardFontRegistry.h"
+
+#include <HalStorage.h>
+#include <Logging.h>
+
+#include <algorithm>
+#include <cstring>
+
+// --- SdCardFontFamilyInfo helpers ---
+
+const SdCardFontFileInfo* SdCardFontFamilyInfo::findFile(uint8_t size, uint8_t style) const {
+  for (const auto& f : files) {
+    if (f.pointSize == size && f.style == style) return &f;
+  }
+  return nullptr;
+}
+
+const SdCardFontFileInfo* SdCardFontFamilyInfo::findClosestReaderSize(const uint8_t fontSizeEnum,
+                                                                      const uint8_t style) const {
+  if (files.empty()) return nullptr;
+
+  // Collect sizes matching the requested style, sorted ascending.
+  std::vector<uint8_t> sizes;
+  for (const auto& f : files) {
+    if (f.style != style) continue;
+    sizes.push_back(f.pointSize);
+  }
+  if (sizes.empty()) return nullptr;
+  std::sort(sizes.begin(), sizes.end());
+
+  // When the family provides at least 4 sizes, use ordinal (index-based)
+  // selection so custom-built font sets (e.g. 10/12/14/16) map SMALL to
+  // the smallest file, not to a hardcoded 12pt target.
+  if (sizes.size() >= 4) {
+    uint8_t idx = fontSizeEnum;
+    if (idx >= sizes.size()) idx = sizes.size() - 1;
+    return findFile(sizes[idx], style);
+  }
+
+  // Fewer sizes than enum slots (e.g. CJK packs with only 2-3 sizes):
+  // fall back to closest-match against the built-in reader targets.
+  uint8_t target = 14;
+  switch (fontSizeEnum) {
+    case 0:
+      target = 12;
+      break;
+    case 2:
+      target = 16;
+      break;
+    case 3:
+      target = 18;
+      break;
+    case 1:
+    default:
+      target = 14;
+      break;
+  }
+
+  const SdCardFontFileInfo* best = nullptr;
+  uint8_t bestDelta = 255;
+  for (const auto& f : files) {
+    if (f.style != style) continue;
+    const uint8_t delta = f.pointSize > target ? f.pointSize - target : target - f.pointSize;
+    if (!best || delta < bestDelta || (delta == bestDelta && f.pointSize < best->pointSize)) {
+      best = &f;
+      bestDelta = delta;
+    }
+  }
+  return best;
+}
+
+bool SdCardFontFamilyInfo::hasSize(uint8_t size) const {
+  for (const auto& f : files) {
+    if (f.pointSize == size) return true;
+  }
+  return false;
+}
+
+std::vector<uint8_t> SdCardFontFamilyInfo::availableSizes() const {
+  std::vector<uint8_t> sizes;
+  for (const auto& f : files) {
+    bool found = false;
+    for (uint8_t s : sizes) {
+      if (s == f.pointSize) {
+        found = true;
+        break;
+      }
+    }
+    if (!found) sizes.push_back(f.pointSize);
+  }
+  std::sort(sizes.begin(), sizes.end());
+  return sizes;
+}
+
+// --- SdCardFontRegistry ---
+
+bool SdCardFontRegistry::parseFilename(const char* filename, uint8_t& size, uint8_t& style) {
+  // V4 naming: <name>_<size>.cpfont (e.g. Bookerly-SD_14.cpfont)
+  // Use an ends-with check rather than strstr() so that in-progress downloads
+  // like "Foo_14.cpfont.tmp" or backups like "Foo_14.cpfont~" aren't accepted.
+  static constexpr char kExt[] = ".cpfont";
+  static constexpr size_t kExtLen = sizeof(kExt) - 1;
+  const size_t nameLen = strlen(filename);
+  if (nameLen <= kExtLen) return false;
+  if (strcmp(filename + nameLen - kExtLen, kExt) != 0) return false;
+  const char* ext = filename + nameLen - kExtLen;
+
+  size_t baseLen = ext - filename;
+  if (baseLen == 0 || baseLen > 127) return false;
+
+  char base[128];
+  memcpy(base, filename, baseLen);
+  base[baseLen] = '\0';
+
+  char* lastUnderscore = strrchr(base, '_');
+  if (!lastUnderscore || lastUnderscore == base) return false;
+
+  const char* sizeStr = lastUnderscore + 1;
+  char* endPtr;
+  long sizeVal = strtol(sizeStr, &endPtr, 10);
+  if (endPtr == sizeStr || *endPtr != '\0' || sizeVal < 1 || sizeVal > 255) return false;
+  size = static_cast<uint8_t>(sizeVal);
+  // V4 .cpfont files bundle every style (regular/bold/italic/bold-italic) into
+  // one file, so style is always 0 at the registry level. The per-style
+  // bitstream is selected later by SdCardFont::getEpdFont(style). The `style`
+  // field in SdCardFontFileInfo is reserved for future formats that split
+  // styles across files; scanDirectory() defends against accidental
+  // (pointSize, style) collisions in that scenario.
+  style = 0;
+  return true;
+}
+
+void SdCardFontRegistry::scanDirectory(const char* dirPath, SdCardFontFamilyInfo& family) {
+  HalFile dir = Storage.open(dirPath);
+  if (!dir || !dir.isDirectory()) return;
+
+  char nameBuffer[128];
+  while (true) {
+    HalFile entry = dir.openNextFile();
+    if (!entry) break;
+    if (entry.isDirectory()) {
+      entry.close();
+      continue;
+    }
+
+    entry.getName(nameBuffer, sizeof(nameBuffer));
+    entry.close();
+
+    // Skip macOS resource fork files (._*) and other hidden files
+    if (nameBuffer[0] == '.' || nameBuffer[0] == '_') continue;
+
+    uint8_t size, style;
+    if (!parseFilename(nameBuffer, size, style)) continue;
+
+    // Reject duplicate (pointSize, style) entries in the same family. With
+    // v4's bundle-everything design parseFilename always returns style=0, so
+    // two files at the same size in the same family would silently shadow
+    // each other in findFile(). Skip the duplicate and warn.
+    bool duplicate = false;
+    for (const auto& existing : family.files) {
+      if (existing.pointSize == size && existing.style == style) {
+        duplicate = true;
+        break;
+      }
+    }
+    if (duplicate) {
+      LOG_ERR("SDREG", "Duplicate font %s in %s — skipping", nameBuffer, dirPath);
+      continue;
+    }
+
+    SdCardFontFileInfo info;
+    info.path = std::string(dirPath) + "/" + nameBuffer;
+    info.pointSize = size;
+    info.style = style;
+    family.files.push_back(std::move(info));
+  }
+}
+
+// Scan a single root (e.g. "/.fonts") and append its families to `out`.
+// Skips families whose names already exist in `out` (de-duplicates between
+// the hidden and visible roots — first scan wins).
+void SdCardFontRegistry::scanRoot(const char* rootPath, std::vector<SdCardFontFamilyInfo>& out) {
+  HalFile root = Storage.open(rootPath);
+  if (!root) {
+    LOG_DBG("SDREG", "Fonts directory not found: %s", rootPath);
+    return;
+  }
+  if (!root.isDirectory()) {
+    LOG_ERR("SDREG", "Fonts path is not a directory: %s", rootPath);
+    return;
+  }
+
+  char nameBuffer[128];
+  while (true) {
+    HalFile entry = root.openNextFile();
+    if (!entry) break;
+    if (entry.isDirectory()) {
+      entry.getName(nameBuffer, sizeof(nameBuffer));
+      entry.close();
+
+      // Skip hidden/system directories inside the root (macOS ._*, .Trashes, etc.)
+      if (nameBuffer[0] == '.' || nameBuffer[0] == '_') continue;
+
+      // De-dup by family name across roots.
+      bool exists = false;
+      for (const auto& fam : out) {
+        if (fam.name == nameBuffer) {
+          exists = true;
+          break;
+        }
+      }
+      if (exists) continue;
+
+      SdCardFontFamilyInfo family;
+      family.name = nameBuffer;
+      std::string subDirPath = std::string(rootPath) + "/" + nameBuffer;
+      SdCardFontRegistry::scanDirectory(subDirPath.c_str(), family);
+
+      if (!family.files.empty()) {
+        out.push_back(std::move(family));
+        LOG_DBG("SDREG", "Found family: %s (%d files) in %s", out.back().name.c_str(),
+                static_cast<int>(out.back().files.size()), rootPath);
+      }
+    } else {
+      entry.close();
+    }
+  }
+}
+
+bool SdCardFontRegistry::discover() {
+  families_.clear();
+  families_.reserve(MAX_SD_FAMILIES);
+
+  // Hidden root is scanned first so it wins on name collisions, matching the
+  // sleep-folder pattern (/.sleep preferred over /sleep).
+  scanRoot(FONTS_DIR_HIDDEN, families_);
+  scanRoot(FONTS_DIR_VISIBLE, families_);
+
+  // Sort families alphabetically
+  std::sort(families_.begin(), families_.end(),
+            [](const SdCardFontFamilyInfo& a, const SdCardFontFamilyInfo& b) { return a.name < b.name; });
+
+  // Cap at MAX_SD_FAMILIES
+  if (static_cast<int>(families_.size()) > MAX_SD_FAMILIES) {
+    families_.resize(MAX_SD_FAMILIES);
+  }
+
+  LOG_DBG("SDREG", "Discovery complete: %d families", static_cast<int>(families_.size()));
+  return !families_.empty();
+}
+
+const char* SdCardFontRegistry::findFamilyRoot(const char* familyName) {
+  if (!familyName || !*familyName) return nullptr;
+  char path[160];
+  snprintf(path, sizeof(path), "%s/%s", FONTS_DIR_HIDDEN, familyName);
+  if (Storage.exists(path)) return FONTS_DIR_HIDDEN;
+  snprintf(path, sizeof(path), "%s/%s", FONTS_DIR_VISIBLE, familyName);
+  if (Storage.exists(path)) return FONTS_DIR_VISIBLE;
+  return nullptr;
+}
+
+const char* SdCardFontRegistry::defaultWriteRoot() {
+  // If exactly one of the roots already exists, keep using it. Otherwise
+  // (neither exists, or both exist) prefer the hidden root for new installs.
+  bool hiddenExists = Storage.exists(FONTS_DIR_HIDDEN);
+  bool visibleExists = Storage.exists(FONTS_DIR_VISIBLE);
+  if (hiddenExists) return FONTS_DIR_HIDDEN;
+  if (visibleExists) return FONTS_DIR_VISIBLE;
+  return FONTS_DIR_HIDDEN;
+}
+
+const SdCardFontFamilyInfo* SdCardFontRegistry::findFamily(const std::string& name) const {
+  for (const auto& f : families_) {
+    if (f.name == name) return &f;
+  }
+  return nullptr;
+}
+
+int SdCardFontRegistry::getFamilyIndex(const std::string& name) const {
+  for (int i = 0; i < static_cast<int>(families_.size()); i++) {
+    if (families_[i].name == name) return i;
+  }
+  return -1;
+}

lib/EpdFont/SdCardFontRegistry.h

@@ -0,0 +1,59 @@
+#pragma once
+
+#include <cstdint>
+#include <string>
+#include <vector>
+
+struct SdCardFontFileInfo {
+  std::string path;   // v4 on-disk naming: "/<root>/<Family>/<Family>_<size>.cpfont"
+                      // where <root> is "/.fonts" (preferred, hidden) or "/fonts" (visible).
+                      // e.g. "/.fonts/NotoSansCJK/NotoSansCJK_14.cpfont"
+  uint8_t pointSize;  // parsed from filename: 14
+  uint8_t style;      // always 0 in v4 (all 4 styles bundled in one file);
+                      // kept for potential future formats
+};
+
+struct SdCardFontFamilyInfo {
+  std::string name;  // directory name, e.g. "NotoSansCJK"
+  std::vector<SdCardFontFileInfo> files;
+
+  const SdCardFontFileInfo* findFile(uint8_t size, uint8_t style = 0) const;
+  const SdCardFontFileInfo* findClosestReaderSize(uint8_t fontSizeEnum, uint8_t style = 0) const;
+  bool hasSize(uint8_t size) const;
+  std::vector<uint8_t> availableSizes() const;
+};
+
+class SdCardFontRegistry {
+ public:
+  static constexpr int MAX_SD_FAMILIES = 128;
+  // Two top-level roots are scanned at discovery time. Hidden is preferred
+  // when creating new installs; both are read from if present.
+  static constexpr const char* FONTS_DIR_HIDDEN = "/.fonts";
+  static constexpr const char* FONTS_DIR_VISIBLE = "/fonts";
+
+  // Returns the existing root for `familyName` (the one that contains
+  // /<root>/<familyName>/), or nullptr if the family is not installed in
+  // either root. Used by writers to keep re-installs in their existing dir.
+  static const char* findFamilyRoot(const char* familyName);
+
+  // Returns the root path that should be used when creating a brand-new
+  // family on disk (no prior install): the existing root if exactly one of
+  // the two roots exists, otherwise the hidden root.
+  static const char* defaultWriteRoot();
+
+  // Scan SD card, populate families_. Returns true if any families found.
+  bool discover();
+
+  const std::vector<SdCardFontFamilyInfo>& getFamilies() const { return families_; }
+  const SdCardFontFamilyInfo* findFamily(const std::string& name) const;
+  int getFamilyIndex(const std::string& name) const;
+  int getFamilyCount() const { return static_cast<int>(families_.size()); }
+
+ private:
+  std::vector<SdCardFontFamilyInfo> families_;  // sorted alphabetically
+
+  static bool parseFilename(const char* filename, uint8_t& size, uint8_t& style);
+  static void scanDirectory(const char* dirPath, SdCardFontFamilyInfo& family);
+  // Scan one root (e.g. "/.fonts"), append families to `out`, dedup by name.
+  static void scanRoot(const char* rootPath, std::vector<SdCardFontFamilyInfo>& out);
+};

lib/EpdFont/builtinFonts/all.h

@@ -1,21 +1,21 @@
 #pragma once
 
-#include <builtinFonts/bookerly_12_bold.h>
-#include <builtinFonts/bookerly_12_bolditalic.h>
-#include <builtinFonts/bookerly_12_italic.h>
-#include <builtinFonts/bookerly_12_regular.h>
-#include <builtinFonts/bookerly_14_bold.h>
-#include <builtinFonts/bookerly_14_bolditalic.h>
-#include <builtinFonts/bookerly_14_italic.h>
-#include <builtinFonts/bookerly_14_regular.h>
-#include <builtinFonts/bookerly_16_bold.h>
-#include <builtinFonts/bookerly_16_bolditalic.h>
-#include <builtinFonts/bookerly_16_italic.h>
-#include <builtinFonts/bookerly_16_regular.h>
-#include <builtinFonts/bookerly_18_bold.h>
-#include <builtinFonts/bookerly_18_bolditalic.h>
-#include <builtinFonts/bookerly_18_italic.h>
-#include <builtinFonts/bookerly_18_regular.h>
+#include <builtinFonts/notoserif_12_bold.h>
+#include <builtinFonts/notoserif_12_bolditalic.h>
+#include <builtinFonts/notoserif_12_italic.h>
+#include <builtinFonts/notoserif_12_regular.h>
+#include <builtinFonts/notoserif_14_bold.h>
+#include <builtinFonts/notoserif_14_bolditalic.h>
+#include <builtinFonts/notoserif_14_italic.h>
+#include <builtinFonts/notoserif_14_regular.h>
+#include <builtinFonts/notoserif_16_bold.h>
+#include <builtinFonts/notoserif_16_bolditalic.h>
+#include <builtinFonts/notoserif_16_italic.h>
+#include <builtinFonts/notoserif_16_regular.h>
+#include <builtinFonts/notoserif_18_bold.h>
+#include <builtinFonts/notoserif_18_bolditalic.h>
+#include <builtinFonts/notoserif_18_italic.h>
+#include <builtinFonts/notoserif_18_regular.h>
 #include <builtinFonts/notosans_8_regular.h>
 #include <builtinFonts/notosans_12_bold.h>
 #include <builtinFonts/notosans_12_bolditalic.h>
@@ -33,22 +33,6 @@
 #include <builtinFonts/notosans_18_bolditalic.h>
 #include <builtinFonts/notosans_18_italic.h>
 #include <builtinFonts/notosans_18_regular.h>
-#include <builtinFonts/opendyslexic_10_bold.h>
-#include <builtinFonts/opendyslexic_10_bolditalic.h>
-#include <builtinFonts/opendyslexic_10_italic.h>
-#include <builtinFonts/opendyslexic_10_regular.h>
-#include <builtinFonts/opendyslexic_12_bold.h>
-#include <builtinFonts/opendyslexic_12_bolditalic.h>
-#include <builtinFonts/opendyslexic_12_italic.h>
-#include <builtinFonts/opendyslexic_12_regular.h>
-#include <builtinFonts/opendyslexic_14_bold.h>
-#include <builtinFonts/opendyslexic_14_bolditalic.h>
-#include <builtinFonts/opendyslexic_14_italic.h>
-#include <builtinFonts/opendyslexic_14_regular.h>
-#include <builtinFonts/opendyslexic_8_bold.h>
-#include <builtinFonts/opendyslexic_8_bolditalic.h>
-#include <builtinFonts/opendyslexic_8_italic.h>
-#include <builtinFonts/opendyslexic_8_regular.h>
 #include <builtinFonts/ubuntu_10_bold.h>
 #include <builtinFonts/ubuntu_10_regular.h>
 #include <builtinFonts/ubuntu_12_bold.h>