refactor: unify control settings models

feat: group Settings -> Controls into submenus
The Controls category had grown to a flat list of a dozen unrelated entries. Split it into Power Button, Front Buttons and Side Buttons groups, reached through a new SUBMENU row type that swaps the visible list in place rather than pushing another activity. - Front Buttons only exists on devices that have them. On touch devices the entries that still apply (long-press behaviour, which also covers the touch page-turn zones) stay at the top level. - Tilt Page Turn and Tilt Direction sit at the top level, and only on IMU-capable boards. - Quick-return from footnotes now appears whenever any shortcut targets footnotes, not only the short power press. Back leaves a group before it leaves Settings, and the header names the open group. Choosing which list is on screen was duplicated between the rebuild and the input handler; both now call one method. Ported from CrossInk. Co-Authored-By: Julia Nguyen <julia@uxj.io>
2026-08-13 14:21:57 -07:00 · 2026-08-09 12:24:05 +03:00 · 2026-08-07 19:09:51 +03:00 · 2026-08-07 19:04:19 +03:00 · 2026-08-07 18:55:39 +03:00 · 2026-08-07 18:50:11 +03:00
476 changed files with 71393 additions and 64068 deletions
@@ -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.
@@ -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.
@@ -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.
@@ -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.
@@ -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.
@@ -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."
@@ -1,2 +1 @@
-github: [daveallie]
-ko_fi: daveallie
+custom: ["https://app.royalty.dev/crosspoint-reader/crosspoint-reader"]
@@ -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.
@@ -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
@@ -3,16 +3,34 @@
 * **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, 
+* 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 
+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 >**_
@@ -53,6 +53,13 @@ jobs:
      - 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

@@ -76,10 +83,21 @@ jobs:
      - 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
+        # 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 | tee pio.log
+          pio run -e default -e sticky | tee pio.log

      - name: Extract firmware stats

@@ -102,6 +120,33 @@ jobs:
          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:
@@ -110,6 +155,7 @@ jobs:
      - build
      - clang-format
      - cppcheck
+      - unit-tests
    if: always()
    runs-on: ubuntu-latest
    steps:
@@ -25,6 +25,13 @@ jobs:
      - 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 -e gh_release

@@ -25,6 +25,13 @@ jobs:
      - 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
@@ -2,6 +2,8 @@
 .idea
 .DS_Store
 .vscode
+open-x4-sdk
+fs_
 lib/EpdFont/fontsrc
 lib/I18n/I18nKeys.h
 lib/I18n/I18nStrings.h
@@ -19,3 +21,13 @@ build
 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/
+/managed_components
+/.dummy
+/CMakeLists.txt
+/dependencies.lock
+/sdkconfig.*
+sdkconfig.sticky
@@ -1,3 +1,4 @@
-[submodule "open-x4-sdk"]
-	path = open-x4-sdk
-	url = https://github.com/crosspoint-reader/community-sdk.git
+[submodule "freeink-sdk"]
+	path = freeink-sdk
+	url = https://github.com/Free-Ink/freeink-sdk.git
+	branch = main
@@ -7,7 +7,7 @@ Mission: Provide a lightweight, high-performance reading experience focused on E
 * 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 open-x4-sdk or official docs first.
+* 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).
@@ -58,6 +58,7 @@ find src -name "*.cpp" -o -name "*.h" | xargs clang-format -i
 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.

 ---

@@ -126,7 +127,7 @@ These flags in `platformio.ini` fundamentally affect firmware behavior:
  * 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)
-* open-x4-sdk/: Low-level SDK (EInkDisplay, InputManager, BatteryMonitor, SDCardManager)
+* 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)
@@ -151,14 +152,19 @@ These flags in `platformio.ini` fundamentally affect firmware behavior:
 #include <HalStorage.h>

 // Use Storage singleton (defined via macro)
-FsFile file;
+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**: See example above. Uses `FsFile` (SdFat), NOT Arduino `File`. Do NOT add `file.close()` for local variables (see DESTRUCTOR_CLOSES_FILE above).
+**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.

 ---

@@ -266,43 +272,78 @@ When a template is necessary, limit instantiations: use explicit template instan

 **Rules**: NO exceptions, NO abort(), ALWAYS log before error return

-### Acceptable malloc/free Patterns
+### Heap Buffer Allocation

-**Source**: [src/activities/home/HomeActivity.cpp:166](../src/activities/home/HomeActivity.cpp), [lib/GfxRenderer/GfxRenderer.cpp:439-440](../lib/GfxRenderer/GfxRenderer.cpp)
+**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.

-Despite "prefer stack allocation," malloc is acceptable for:
-1. **Large temporary buffers** (> 256 bytes, won't fit on stack)
-2. **One-time allocations** during activity initialization
-3. **Bitmap rendering buffers** (variable size, used briefly)
-
-**Pattern**:
+**Preferred pattern**:
 ```cpp
-// Allocate
-auto* buffer = static_cast<uint8_t*>(malloc(bufferSize));
+#include <Memory.h>
+
+auto buffer = makeUniqueNoThrow<uint8_t[]>(bufferSize);
 if (!buffer) {
-  LOG_ERR("MODULE", "malloc failed: %d bytes", bufferSize);
-  return false;  // Handle allocation failure
+  LOG_ERR("MODULE", "OOM: %d bytes", bufferSize);
+  return false;
 }

-// Use buffer
-processData(buffer, bufferSize);
+processData(buffer.get(), bufferSize);
+// freed automatically — no manual free needed, no leak on early return
+```

-// Free immediately after use
-free(buffer);
-buffer = nullptr;
+**`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**:
- **ALWAYS check for nullptr** after malloc
- **Free immediately** after use (don't hold across multiple operations)
- **Set to nullptr** after free (avoid use-after-free)
- **Document size**: Comment why stack allocation was rejected
+- **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)
- Text chunk buffers: [TxtReaderActivity.cpp:259](../src/activities/reader/TxtReaderActivity.cpp)
 - Bitmap rendering: [GfxRenderer.cpp:439-440](../lib/GfxRenderer/GfxRenderer.cpp)
- OTA update buffer: [OtaUpdater.cpp:40](../src/network/OtaUpdater.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`)

 ---

@@ -416,7 +457,6 @@ void onExit()   { /* free: vTaskDelete, free buffer, close member FsFiles */ Act
 **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)
- OpenDyslexic: 8, 10, 12, 14pt (4 styles each)
 - Ubuntu UI fonts: 10, 12pt (2 styles)

 **Total**: ~80+ global `EpdFont` and `EpdFontFamily` objects
@@ -856,8 +896,8 @@ rm -rf /path/to/sd/.crosspoint/epub_<hash>/sections/
 **Source**: `lib/Epub/Epub/Section.cpp`, `lib/Epub/Epub/BookMetadataCache.cpp`

 **Current Versions** (as of docs/file-formats.md):
- `book.bin`: **Version 5** (metadata structure)
- `section.bin`: **Version 12** (layout structure)
+- `book.bin`: **Version 7** (metadata structure)
+- `section.bin`: **Version 25** (layout structure)

 **Version Increment Rules**:
 1. **ALWAYS increment version** BEFORE changing binary structure
@@ -867,7 +907,7 @@ rm -rf /path/to/sd/.crosspoint/epub_<hash>/sections/
 **Example** (incrementing section format version):
 ```cpp
 // lib/Epub/Epub/Section.cpp
-static constexpr uint8_t SECTION_FILE_VERSION = 13;  // Was 12, now 13
+static constexpr uint8_t SECTION_FILE_VERSION = 26;  // Was 25, now 26

 // Add new field to structure
 struct PageLine {
@@ -878,4 +918,4 @@ struct PageLine {

 ---

-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.
+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.
@@ -1,122 +1,196 @@
 # 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 truly 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 (EPUB 2 and EPUB 3)
- [x] 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
-  - [x] Cover sleep screen
- [x] Wifi book upload
- [x] Wifi OTA updates
- [x] KOReader Sync integration for cross-device reading progress
- [x] Configurable font, layout, and display options
-  - [ ] User provided fonts
-  - [ ] Full UTF support
- [x] Screen rotation
+- **Screenshots.**

-Multi-language support: Read EPUBs in various languages, including English, Spanish, French, German, Italian, Portuguese, Russian, Ukrainian, Polish, Swedish, Norwegian, [and more](./USER_GUIDE.md#supported-languages).
+- **Custom fonts**: install your favorite fonts on the SD card.

-See [the user guide](./USER_GUIDE.md) for instructions on operating CrossPoint, including the
-[KOReader Sync quick setup](./USER_GUIDE.md#367-koreader-sync-quick-setup).
+- **Tilt page turn (X3 only)**.

-For more details about the scope of the project, see the [SCOPE.md](SCOPE.md) document.
+- **Library workflow**: folder browser, hidden-file toggle, long-press delete, recent books, SD-cache management.

-## Installing
+- **Wireless workflows**:
+  
+  - 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 (latest firmware)
+- **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 and wake/unlock the device
-2. Go to https://xteink.dve.al/ and click "Flash CrossPoint firmware"
+- **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:

-### Web (specific firmware version)
+- More themes.

-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/crosspoint-reader/crosspoint-reader/releases)
-3. Go to https://xteink.dve.al/ and flash the firmware file using the "OTA fast flash controls" section
+- Much more! stay tuned.

-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.
+---

-### Command line (specific firmware version)
+## 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):

-1. Install [`esptool`](https://github.com/espressif/esptool) :
 ```bash
 pip install esptool
 ```
-2. Download the `firmware.bin` file from the release of your choice via the [releases page](https://github.com/crosspoint-reader/crosspoint-reader/releases)
-3. Connect your Xteink X4 to your computer via USB-C.
-4. Note the device location. On Linux, run `dmesg` after connecting. On MacOS, run :
+
+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 the firmware :
+
+5. Flash:
+
 ```bash
 esptool.py --chip esp32c3 --port /dev/ttyACM0 --baud 921600 write_flash 0x10000 /path/to/firmware.bin
 ```
-Change `/dev/ttyACM0` to the device for your system.
+
+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

-# 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.
@@ -126,7 +200,9 @@ First, make sure all required Python packages are installed:
 ```python
 python3 -m pip install pyserial colorama matplotlib
 ```
-after that run the script:
+
+After that run the script:
+
 ```sh
 # For Linux
 # This was tested on Debian and should work on most Linux systems.
@@ -135,63 +211,77 @@ 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.
-
-### 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:
-
-
-```
-.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_189013891/
-```
-
-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.
-
-For more details on the internal file structures, see the [file formats document](./docs/file-formats.md).
-
-## Contributing
-
-Contributions are very welcome!
-
-If you are new to the codebase, start with the [contributing docs](./docs/contributing/README.md).
-
-If you're looking for a way to help out, take a look at the [ideas discussion board](https://github.com/crosspoint-reader/crosspoint-reader/discussions/categories/ideas).
-If there's something there you'd like to work on, leave a comment so that we can avoid duplicated effort.
-
-Everyone here is a volunteer, so please be respectful and patient. For more details on our governance and community 
-principles, please see [GOVERNANCE.md](GOVERNANCE.md).
-
-### To submit a contribution:
-
-1. Fork the repo
-2. Create a branch (`feature/dithering-improvement`)
-3. Make changes
-4. Submit a PR
-
 ---

-CrossPoint Reader is **not affiliated with Xteink or any manufacturer of the X4 hardware**.
+## Internals

-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.
+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_<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
+│       └── ...
+├── settings.json        # device settings
+├── state.json           # resume/runtime state
+└── recent.json          # recent books list
+```
+
+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 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.
+
+Everyone here is a volunteer, so please be respectful and patient. For governance and community expectations, see [GOVERNANCE.md](./GOVERNANCE.md).
+
+---
+
+## Community forks
+
+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.
@@ -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.
@@ -1,62 +1,100 @@
 # Project Vision & Scope: CrossPoint Reader

-The goal of CrossPoint Reader is to create an efficient, open-source reading experience for the Xteink X4. We believe a
-dedicated e-reader should do one thing exceptionally well: **facilitate focused reading.**
+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 the X4, prioritizing legibility and
-usability over "swiss-army-knife" functionality.
+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.

-## 2. Scope
+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

-*These are features that directly improve the primary purpose of the device.*
+*Features that directly improve the core reading experience or the firmware's maintainability.*

-* **User Experience:** E.g. User-friendly interfaces, and interactions, both inside the reader and navigating the
-  firmware. This includes things like button mapping, book loading, and book navigation like bookmarks.
-* **Document Rendering:** E.g. Support for rendering documents (primarily EPUB) and improvements to the rendering
-  engine.
-* **Format Optimization:** E.g. Efficiently parsing EPUB (CSS/Images) and other documents within the device's
-  capabilities.
-* **Typography & Legibility:** E.g. Custom font support, hyphenation engines, and adjustable line spacing.
-* **E-Ink Driver Refinement:** E.g. Reducing full-screen flashes (ghosting management) and improving general rendering.
-* **Library Management:** E.g. Simple, intuitive ways to organize and navigate a collection of books.
-* **Local Transfer:** E.g. Simple, "pull" based book loading via a basic web-server or public and widely-used standards.
-* **Language Support:** E.g. Support for multiple languages both in the reader and in the interfaces.
-* **Reference Tools:** E.g. Local dictionary lookup. Providing quick, offline definitions to enhance comprehension 
-  without breaking focus.
-* **Clock Display (device dependent):** 
-
-| Device | Scope |
-| -- | -- |
-| X3 | The X3 uses a dedicated DS3231 RTC, which maintains accurate time across sleep cycles and can be treated as a reliable wall clock. |
-| X4 | The X4 relies on the ESP32-C3's internal RTC, which drifts significantly during deep sleep. NTP sync could correct this, with an appropriate user experience around connecting to the internet on wake or on demand. This causes some tension with the **Active Connectivity** section below, so please open a discussion about this UX if it's a feature you would find useful. |
+* **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

-*These items are rejected because they compromise the device's stability or mission.*
+*Rejected because they compromise the device's stability, maintainability, or core mission.*

-* **Interactive Apps:** No Notepads, Calculators, or Games. This is a reader, not a PDA.
-* **Active Connectivity:** No RSS readers, News aggregators, or Web browsers. Background Wi-Fi tasks drain the battery
-  and complicate the single-core CPU's execution.
-* **Media Playback:** No Audio players or Audio-books.
-* **Complex Annotation:** No typed out notes. These features are better suited for devices with better input
-  capabilities and more powerful chips.
+* **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.

-### In-scope — Technically Unsupported
+## 5. Calls to Action

-*These features align with CrossPoint's goals but are impractical on the current hardware or produce poor UX.*
+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.

-* **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.
+### Theme System: Move Themes Off-Firmware

-## 3. Idea Evaluation
+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.

-While I appreciate the desire to add new and exciting features to CrossPoint Reader, CrossPoint Reader is designed to be
-a lightweight, reliable, and performant e-reader. Things which distract or compromise the device's core mission will not
-be accepted. As a guiding question, consider if your idea improve the "core reading experience" for the average user,
-and, critically, not distract from that reading experience.
+* **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.

-> **Note to Contributors:** If you are unsure if your idea fits the scope, please open a **Discussion** before you start
-> coding!
+### 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.