chore: translate empty bookmark state (#3004)

Co-authored-by: Metin Arslan <GITHUB-EPOSTAN>

.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

@@ -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 >**_

.github/workflows/ci.yml

@@ -63,7 +63,8 @@ jobs:
       - name: Run cppcheck
         run: pio check --fail-on-defect low --fail-on-defect medium --fail-on-defect high
 
-  build:
+  build-default:
+    name: Build default
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v6
@@ -90,10 +91,10 @@ jobs:
           key: pio-${{ runner.os }}-${{ hashFiles('platformio.ini') }}
           restore-keys: pio-${{ runner.os }}-
 
-      - name: Build CrossPoint
+      - name: Build default firmware
         run: |
           set -euo pipefail
-          pio run | tee pio.log
+          pio run -e default | tee pio.log
 
       - name: Extract firmware stats
 
@@ -116,6 +117,52 @@ jobs:
           path: .pio/build/default/firmware.bin
           if-no-files-found: error
 
+  build-sticky:
+    name: Build sticky
+    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 sticky firmware
+        run: |
+          set -euo pipefail
+          pio run -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 "## Sticky 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"
+
   unit-tests:
     runs-on: ubuntu-latest
     steps:
@@ -148,7 +195,8 @@ jobs:
   test-status:
     name: Test Status
     needs:
-      - build
+      - build-default
+      - build-sticky
       - clang-format
       - cppcheck
       - unit-tests

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

@@ -1,7 +1,6 @@
 name: "PR Formatting"
 
 on:
-  pull_request:
   pull_request_target:
     types:
       - opened
@@ -9,7 +8,7 @@ on:
       - edited
 
 permissions:
-  statuses: write
+  pull-requests: read
 
 jobs:
   title-check:

.github/workflows/release.yml

@@ -1,47 +0,0 @@
-name: Compile Release
-on:
-  push:
-    tags:
-      - '*'
-
-jobs:
-  build-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: Build CrossPoint
-        run: pio run -e gh_release
-
-      - name: Upload Artifacts
-        uses: actions/upload-artifact@v4
-        with:
-          name: CrossPoint-${{ github.ref_name }}
-          path: |
-            .pio/build/gh_release/bootloader.bin
-            .pio/build/gh_release/firmware.bin
-            .pio/build/gh_release/firmware.elf
-            .pio/build/gh_release/firmware.map
-            .pio/build/gh_release/partitions.bin

.gitignore

@@ -2,6 +2,8 @@
 .idea
 .DS_Store
 .vscode
+open-x4-sdk
+fs_
 lib/EpdFont/fontsrc
 lib/I18n/I18nKeys.h
 lib/I18n/I18nStrings.h
@@ -23,3 +25,10 @@ lib/EpdFont/scripts/output/
 # (worktrees, scheduled-task locks, settings.local, scout CLEANUP.md) out.
 .claude/*
 !.claude/skills/
+/managed_components
+/.dummy
+/CMakeLists.txt
+/dependencies.lock
+/sdkconfig.*
+sdkconfig.sticky
+flake.*

AGENTS.md

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

README.md

@@ -12,7 +12,7 @@ CrossPoint is open-source e-reader firmware - community-built, fully hackable, f
 
 ## What can CrossPoint do?
 
-- **Reader engine**: EPUB 2/3 rendering with embedded-style option, image handling, hyphenation, kerning, chapter navigation, footnotes, bookmarks, go-to-percent, auto page turn, orientation control, focus reading, KOReader progress sync and more. 
+- **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. 
 
 - **Various formats**: native handling for `.epub`, `.xtc/.xtch`, `.txt`, and `.bmp`.
 
@@ -36,14 +36,12 @@ CrossPoint is open-source e-reader firmware - community-built, fully hackable, f
   - OPDS browser with saved servers (up to 8), search, pagination, and direct download
   - OTA update checks and installs from GitHub releases
 
-- **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.
+- **Customization**: multiple themes (Classic, Lyra, Lyra Extended, RoundedRaff), sleep screen modes including transparent overlays, front/side button remapping, status bar controls, power-button behavior, refresh cadence, and more.
 
 - **Localization**: 24 UI languages and counting. RTL support.
 
 ### Coming soon:
 
-- Dictionary lookup — inline word lookup without leaving the reader.
-
 - More themes.
 
 - Much more! stay tuned.
@@ -138,6 +136,7 @@ Conversion runs the firmware repo's `lib/EpdFont/scripts/fontconvert_sdcard.py`
 - [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) - how to build new screens on the FreeInkUI activity bases (UiListActivity and friends), plus build envs for the non-Xteink touch devices
 
 ---
 
@@ -160,6 +159,24 @@ cd crosspoint-reader
 git submodule update --init --recursive
 ```
 
+### Nix/NixOS
+
+Nix/NixOS users can enter the development shell with either `nix develop` (flakes) or `nix-shell`:
+
+```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

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

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

USER_GUIDE.md

@@ -28,8 +28,10 @@ Welcome to the **CrossPoint** firmware. This guide outlines the hardware control
       - [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: Free Public Server (`sync.koreader.rocks`)](#option-a-free-public-server-synckoreaderrocks)
-        - [Option B: Self-Hosted Server (Docker Compose)](#option-b-self-hosted-server-docker-compose)
+        - [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)
@@ -184,7 +186,7 @@ The Settings screen allows you to configure the device's behavior. There are a f
   - "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.
-
+  - "Transparent" - A transparent overlay image drawn over the current screen; see [Sleep Screen](#37-sleep-screen) below for more information
 - **Sleep Screen Cover Mode**: How to display the book cover when "Cover" sleep screen is selected:
   
   - "Fit" (default) - Scale the image down to fit centered on the screen, padding with white borders as necessary
@@ -261,6 +263,8 @@ The Settings screen allows you to configure the device's behavior. There are a f
   - "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".
@@ -280,6 +284,7 @@ The Settings screen allows you to configure the device's behavior. There are a f
 - **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:
@@ -297,7 +302,7 @@ The Settings screen allows you to configure the device's behavior. There are a f
 
 - **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.
+- **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.
 
@@ -360,9 +365,37 @@ Behavior notes:
 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: Free Public Server (`sync.koreader.rocks`)
+##### Option A: CrossPoint Sync Server (`sync.crosspointreader.com`, default)
 
-1. Register a user once (only if needed):
+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). CrossPoint records page starts as chapter-content offsets and sends the corresponding standard KOReader XPath, so devices with different fonts or layouts can return to the same text.
+
+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"
@@ -375,27 +408,9 @@ curl -i "https://sync.koreader.rocks/users/create" \
   --data "{\"username\":\"$USERNAME\",\"password\":\"$PASSWORD_MD5\"}"
 ```
 
-Already have KOReader Sync credentials? Skip registration; basic sync only requires using the same existing username/password on all devices.
-
 When this returns `HTTP 402` with `{"code":2002,"message":"Username is already registered."}`, pick a different username or use that existing account.
 
-2. 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 `https://sync.koreader.rocks`, or leave it empty (both use the same default KOReader sync server).
-   
-   - Run **Authenticate**.
-
-3. While reading, press **Confirm** to open the reader menu, then select **Sync Progress**.
-   
-   - Choose **Apply Remote** to jump to remote progress.
-   
-   - Choose **Upload Local** to push current progress.
-
-##### Option B: Self-Hosted Server (Docker Compose)
+##### Option C: Self-Hosted Server (Docker Compose)
 
 1. Start a sync server:
 
@@ -468,11 +483,12 @@ If this returns `HTTP 402` with `{"code":2002,"message":"Username is already reg
 
 If you use the HTTPS listener, use `https://<server-ip>:7200` (`curl -k` only for self-signed certificate testing).
 
-5. While reading, press **Confirm** to open the reader menu, then select **Sync Progress**.
-   
-   - Choose **Apply Remote** to jump to remote progress.
-   
-   - Choose **Upload Local** to push current progress.
+##### 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
 
@@ -485,6 +501,7 @@ The **Sleep Screen** setting controls what is displayed when the device goes to
 | **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. |
+| **Transparent**    | A BMP overlay drawn over the current screen. Supports alpha transparency in 32-bit BGRA images and treats white as transparent in regular BMPs. Falls back to **Dark** if no valid overlay image is found. |
 | **None**           | A blank screen.                                                                                                              |
 
 #### Cover settings
@@ -499,12 +516,21 @@ When using **Cover** or **Cover + Custom**, two additional settings apply:
 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.
+- **Single Image:** Place a file named `sleep.bmp` in the root directory. This takes priority over the `.sleep`/`sleep` directories.
+
+#### Transparent overlay images
+
+To use transparent sleep overlays, set the sleep screen mode to **Transparent**, then place BMP files on the SD card:
+
+- **Multiple Images (recommended):** Create a `.sleep-overlay` directory in the root of the SD card and place any number of valid overlay `.bmp` images inside. One will be randomly selected each time the device sleeps. A directory named `sleep-overlay` is also accepted as a fallback.
+- **Single Image:** Place a file named `sleep-overlay.bmp` in the root directory. This takes priority over the `.sleep-overlay`/`sleep-overlay` directories.
+
+Transparent overlay files are intentionally separate from normal sleep images. Regular BMP formats supported by CrossPoint are accepted; white pixels leave the existing screen unchanged. For per-pixel alpha transparency, use a 32-bit BGRA BMP with both visible and non-opaque pixels. Opaque white pixels in these alpha images erase the content behind them.
 
 > [!TIP]
 > For best results:
-> 
-> - Use uncompressed BMP files with 24-bit color depth
+> - For non-transparent **Custom** mode, use uncompressed BMP files with 24-bit color depth.
+> - For **Transparent** mode, use a regular BMP for white-as-transparent artwork or an uncompressed 32-bit BGRA BMP for per-pixel alpha.
 > - 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.
 
@@ -570,7 +596,7 @@ If the device goes to sleep or you close the book while viewing a footnote, the
 * **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, "Disabled" does nothing. A short press always opens the Reader Menu.
+* **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
 
@@ -592,6 +618,7 @@ 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.

bin/clang-format-fix

@@ -47,6 +47,7 @@ git ls-files  --exclude-standard ${GIT_LS_FILES_FLAGS} \
     | grep -v -E '^lib/EpdFont/builtinFonts/' \
     | 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

docs/contributing/README.md

@@ -7,5 +7,6 @@ It is written for software developers who may be new to embedded development.
 - [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

@@ -154,9 +154,11 @@ Typical persisted areas on SD:
   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`.
+`sections/*.bin` contains rendered pages plus anchor, paragraph, list-item, and
+page-start visible-text-offset lookup tables. The offset table makes reading
+positions content-based: KOReader XPaths resolve to an exact chapter offset,
+and the current layout derives the corresponding page. For binary cache
+formats, see `docs/file-formats.md`.
 
 ## Networking architecture
 

docs/contributing/touch-and-ui.md

@@ -0,0 +1,202 @@
+# Touch and UI Development
+
+CrossPoint 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 is one supported way to build a new screen: FreeInkUI, hosted through the firmware base classes below.** Touch hit-testing, tap highlighting, long-press, swipe scrolling, and button focus navigation all come from the shared stack; you never hand-roll coordinate math.
+
+The old bridge helpers (`rowTouch`, `colTouch`, `wasTapInRect`, manual rect `contains()` checks) are legacy. They survive only for the two remaining hand-rolled surfaces (the theme-driven home screen and the reader page) and must not appear in new code. PRs that add new uses will be asked to convert.
+
+---
+
+## Picking the right host
+
+| Your screen is... | Use | In-tree reference |
+|---|---|---|
+| A single list of rows | subclass `UiListActivity` | [`LanguageSelectActivity`](../../src/activities/settings/LanguageSelectActivity.cpp) (minimal), [`RecentBooksActivity`](../../src/activities/home/RecentBooksActivity.cpp) (long-press) |
+| Tabbed lists | subclass `UiTabListActivity` | [`SettingsActivity`](../../src/activities/settings/SettingsActivity.cpp) |
+| Custom FUI layout (sliders, prompts, state machines) | inherit `UiAppHost` directly | [`EpubReaderPercentSelectionActivity`](../../src/activities/reader/EpubReaderPercentSelectionActivity.cpp), [`WifiSelectionActivity`](../../src/activities/network/WifiSelectionActivity.cpp) |
+| A modal picker or confirm inside a legacy activity | `OptionPopup` (or push `ConfirmationActivity`) | [`OtaUpdateActivity`](../../src/activities/settings/OtaUpdateActivity.cpp) |
+| A Yes/No prompt inside a FUI screen | build `fui::optionDialog` into the screen | `WifiSelectionActivity::buildPromptDialog` |
+
+All four paths route input through the same SDK interaction table, so touch and physical buttons fire the same actions with no per-screen coordinate code.
+
+## The hosting stack
+
+`UiAppHost` ([src/components/UiAppHost.h](../../src/components/UiAppHost.h)) owns what every FUI screen shares: the font-bound render target, the `FreeInkApp`, and the `uiReady` handshake that lets the loop task route touch snapshots against the interaction table the render task rebuilds. Never re-implement that handshake; it is a cross-task protocol and lives in exactly one place.
+
+`UiListActivity` ([src/activities/UiListActivity.h](../../src/activities/UiListActivity.h)) layers the list protocol on top: swipes scroll the viewport without moving the selection, buttons move the selection and pull the viewport along (`fui::ListNav`), plus the render skeleton (header chrome, app, footer hints). `UiTabListActivity` is the tab-bar sibling; its selection ring puts the tab bar at position 0 and the rows after it.
+
+### New list screen skeleton
+
+Subclasses supply the data; the base owns the loop. The whole contract:
+
+```cpp
+class MyListActivity final : public UiListActivity {
+ public:
+  MyListActivity(GfxRenderer& r, MappedInputManager& in) : UiListActivity("MyList", r, in) {}
+
+ private:
+  std::vector<Entry> entries;       // the activity's data, loaded in onEnter
+  std::vector<fui::ListItem> rows;  // activity-owned row cache: rebuilt only when entries changes, reused every render
+
+  int listCount() const override { return entries.size(); }
+  const char* headerTitle() const override { return tr(STR_MY_TITLE); }
+
+  void onEnter() override {
+    UiListActivity::onEnter();
+    entries = /* ... load from wherever ... */;
+    rebuildRows();
+  }
+
+  // Called whenever entries changes (here, only onEnter; a mutable list would
+  // also call this after any add/remove). NOT called from buildScreen().
+  void rebuildRows() {
+    rows.clear();
+    rows.reserve(entries.size());
+    // ... one fui::ListItem per entry (label, actionValue = index) ...
+  }
+
+  void buildScreen(UiScreen& screen) override {
+    // set content margin from the theme safe area, then:
+    fui::ListProps props;
+    props.items = rows.data();
+    props.count = rows.size();
+    props.action = ACTION_ROW;
+    props.inputMask = fui::InputTouch;  // physical buttons stay in the base loop
+    syncListViewport(screen, props);    // selection/viewport handoff, always right before list()
+    screen.list(props);
+  }
+
+  void activateIndex(int index) override {
+    app.clearTapFlash();  // leaving the screen: a lingering flash would gray the next render
+    // ... open the thing ...
+  }
+};
+```
+
+See [`FileBrowserActivity`](../../src/activities/home/FileBrowserActivity.cpp)'s `rebuildRowItems()` for this pattern applied to a directory listing that can run into the hundreds of entries, and `LanguageSelectActivity.cpp` for the rest of the skeleton (content-margin math, footer, etc.) — note that file still builds its row vector locally inside `buildScreen()`; match `FileBrowserActivity`, not that file, for the row cache. Optional overrides: `onRowLongPress(index)`, `drawFooter()`, `handleButtons()` for extra physical-button handling, and `ACTION_USER`-and-up action ids for non-row elements (register handlers in `onEnter` after the base's).
+
+### Rules that apply to every FUI screen
+
+- Register actions with `app.on(...)` in `onEnter` (after `resetUi()` for direct `UiAppHost` users). Handlers receive a `void* user` you cast back to the activity.
+- Handlers that leave the current screen call `app.clearTapFlash()` first.
+- Theme tokens are shared and bound by `resetUi()`; never call `app.setTheme` yourself. Metrics flow from the active UITheme through [`UIThemeTokens.h`](../../src/components/UIThemeTokens.h), including the per-board bezel insets that keep scrollbars visible.
+- `TextStyle.maxLines` defaults to 1 and truncates with an ellipsis. Set `maxLines` explicitly on any dialog headline or message that can wrap.
+- Everything stays allocation-free in steady state. A local `std::vector` inside `buildScreen()` is **not** allocation-free even with `reserve()` first: it starts at zero capacity on every call, `reserve()` allocates, and the destructor frees that storage before the call returns — real allocator work and fragmentation risk on every repaint (cursor move, tap flash, ...), not just on data changes. Build `ListItem` rows into activity-owned storage instead, reserved once when the underlying data loads (`onEnter()`/a `load*()` — see the skeleton above and `FileBrowserActivity::rebuildRowItems()`), and reused unchanged by every `buildScreen()` call. Use a fixed-capacity array (e.g. `ListItem rows[MAX]`, as `OptionPopup` and `KOReaderSyncActivity`'s action rows do) when the count is small and bounded. Do not hold FUI `props` across renders — only the row storage they point into.
+
+### 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` |
+
+One exception to "always go through a host": `KeyboardEntryActivity` drives the keyboard component with a raw `fui::Frame` and `TouchHoldRouter` because per-key hold repeat needs its own routing. If you think your screen needs that, raise it in the PR first.
+
+---
+
+## 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.
+
+---
+
+## Legacy bridge helpers (do not use in new code)
+
+`MappedInputManager` still exposes raw touch accessors. The FUI stack consumes them internally (via `touchSnapshotFrom` in [`UiAppHelpers.h`](../../src/components/UiAppHelpers.h)); activities should not.
+
+| Helper | Status |
+|---|---|
+| `wasScreenTapped` / `wasScreenTouchDown` / `isScreenTouchHeld` | Consumed by the FUI snapshot builder. Direct use only in the two legacy surfaces |
+| `wasTapInRect(x, y, w, h)` | Legacy one-off hit test |
+| `rowTouch` / `colTouch` | Legacy row/column band math. Sole remaining user: `HomeActivity` (theme-driven layout) |
+| `wasSwipe()` | Raw swipe direction, for behavior beyond the global gestures (reader page turns) |
+| `hasTouch()` | Still fine anywhere: gate touch-only chrome (on-screen Cancel/OK pairs) on it |
+
+The `wasListItemTapped` / `wasListItemTouchedDown` helpers from the button-era bridge have been removed; every themed list is a `UiListActivity` now. If you are porting a branch that still calls them, convert the screen to `UiListActivity` rather than resurrecting the helpers.
+
+As with all input: never call the SDK `InputManager` or read GPIO directly. The HAL rule from the main guide applies to touch too.
+
+---
+
+## 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,71 @@
+# 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)
+- `.syn` — synonym index (optional; maps alternate spellings and irregular forms to their headword)
+- `.ifo` — metadata (optional)
+
+Not supported: dictionaries with 64-bit index offsets (`idxoffsetbits=64` in the `.ifo` — rare, and rejected with an error).
+
+## 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 whenever the `.idx` or `.syn` source file changes), the reader shows *"Indexing dictionary…"* while it builds small sidecar files next to them — a `.qidx` for the word index, and a `.sidx` when a `.syn` synonym file is present. Each sidecar is rebuilt independently, only when its own source changes. This takes a few seconds for large dictionaries and makes all subsequent lookups fast. The sidecars can be deleted safely at any time — they 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. **Synonyms** — on a miss, if the dictionary ships a `.syn` file, alternate spellings and irregular forms recorded there are resolved to their headword (e.g. `oxen` → `ox`, `colour` → `color`). This step is skipped if the `.sidx` sidecar could not be built (e.g. transient low memory during indexing); the dictionary otherwise stays usable, and the build is retried the next time it is opened.
+3. **Stemming** — still no match: common English word forms are retried automatically: possessives and plurals (`dogs` → `dog`, `stories` → `story`) and verb endings (`walked` → `walk`, `running` → `run`, `making` → `make`).
+4. **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.
+
+HTML dictionaries that declare `sametypesequence=h` use the EPUB text-layout engine for semantic formatting such as headings, bold, italics, lists, and line breaks. Images and CSS styling are ignored. Definitions that are too large or cannot be laid out within the available memory fall back to plain text.
+
+- **Left/Right** or side **Up/Down** — previous / next page
+- **Back** — return to word selection
+
+
+
+## Where to find dictionaries
+
+> credit to https://github.com/koreader/koreader/wiki/Dictionary-support for the list.
+
+- The [reader.dict](https://www.reader-dict.com) (ex "BoboTiG/ebook-reader-dict") project provides StarDict version of daily dumps of [Wiktionary](https://www.wiktionary.org/) monolingual dictionaries for a variety of languages. It also provides [non-free multilingual](https://www.reader-dict.com) dictionaries.
+- The [WikDict](https://www.wikdict.com) project provides free bilingual dictionaries based on [Wiktionary](https://www.wiktionary.org/) for a lot of language pairs. StarDict versions can be [downloaded from here](https://download.wikdict.com/dictionaries/stardict/).
+- The [`Vuizur/Wiktionary-Dictionaries`](https://github.com/Vuizur/Wiktionary-Dictionaries) repository contains dictionaries based on [Wiktionary](https://www.wiktionary.org/) from many languages to English, including English-English.
+- The [DictInfo](https://www.dictinfo.com/) website provides outdated monolingual dictionaries based on [Wiktionary](https://www.wiktionary.org/).
+- The [Firedict site](https://tuxor1337.frama.io/firedict/dictionaries.html) contains a list of freely available dictionaries.
+- [wiktionary_stardict](https://xxyzz.github.io/wiktionary_stardict/): update monthly.
+- [Fictionaries](https://fictionary.gumroad.com/) provides dictionaries for various speculative fiction books and series.
+- [World Factbooks Archive](https://github.com/MilkMp/CIA-World-Factbooks-Archive-1990-2025) provides 36 years of CIA's World Factbook dictionaries in StarDict format.
+- [StarDict-Hebrew](https://github.com/Uri-Tauber/StarDict-Hebrew) Hebrew-English StarDict versions of Babylon dictionaries.

docs/file-formats.md

@@ -6,7 +6,7 @@ All POD fields are written in the ESP32 little-endian representation used by
 
 ## `book.bin`
 
-### Version 7
+### Version 10
 
 `book.bin` stores EPUB metadata plus lookup tables for spine and TOC entries.
 The current firmware writes this version from `BookMetadataCache`.
@@ -18,7 +18,7 @@ import std.mem;
 import std.string;
 import std.core;
 
-#define EXPECTED_VERSION 7
+#define EXPECTED_VERSION 10
 #define MAX_STRING_LENGTH 65535
 
 struct String {
@@ -90,19 +90,42 @@ if (parsedSize != fileSize) {
 
 ## `section.bin`
 
-### Version 29
+### Version 37
 
 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 29 includes:
+Version 37 increases the fixed-size footnote href field from 96 to 256 bytes.
+This changes each serialized footnote record from 128 to 288 bytes, so older
+section caches must be discarded and rebuilt.
+
+Version 36 invalidates cached word positions after ruby and CJK justification
+layout changes.
+
+Version 35 adds a header offset and a `uint32_t` entry per page for the
+visible-text offset LUT. The other section LUTs remain unchanged.
+
+Version 34 is binary-identical to version 33. The version was bumped because
+word-gap suppression was narrowed to tokens glued together in the source: v33
+dropped the gap between any two words meeting at a CJK break opportunity, which
+collapsed the spaces between Hangul words, so v33 word positions no longer match
+what the layout engine now produces.
+
+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
+- per-page visible-text offset LUT (zero-based Unicode codepoints in `<body>`)
 - anchor-to-page map for fragment and footnote navigation
-- paragraph and list-item LUTs used by KOReader sync page refinement
+- paragraph and list-item LUTs retained for navigation and legacy sync fallback
 - optional per-word Focus Reading split metadata
 - per-page footnote entries
 - serialized word style bits for underline, strikethrough, superscript, and
@@ -119,10 +142,10 @@ import std.mem;
 import std.string;
 import std.core;
 
-#define EXPECTED_VERSION 29
+#define EXPECTED_VERSION 37
 #define MAX_STRING_LENGTH 65535
 #define FOOTNOTE_NUMBER_LEN 32
-#define FOOTNOTE_HREF_LEN 96
+#define FOOTNOTE_HREF_LEN 256
 
 struct String {
     u32 length [[hidden, comment("String byte length")]];
@@ -287,6 +310,7 @@ struct SectionBin {
     u32 anchorMapOffset;
     u32 paragraphLutOffset;
     u32 listItemLutOffset;
+    u32 visibleTextLutOffset;
 
     Page pages[pageCount];
 
@@ -308,6 +332,10 @@ struct SectionBin {
     if (listItemLutOffset != 0 && paragraphLutOffset != 0) {
         u16 listItemIndex[paragraphLut.count] @ listItemLutOffset;
     }
+
+    if (visibleTextLutOffset != 0) {
+	u32 visibleTextOffset[pageCount] @ visibleTextLutOffset;
+    }
 };
 
 SectionBin section @ 0x00;

docs/fix-bricked-xteink.md

@@ -0,0 +1,131 @@
+# Recovering a Bricked Xteink
+
+![proceed at your own risk](./images/spiflash/fix_bricked.jpg)
+
+This guide covers installing CrossPoint on an Xteink that's bricked, or stuck on firmware with no path to flash a replacement. It works by writing firmware directly to the SPI flash chip with an external programmer, bypassing the ESP32-C3 entirely.
+
+If your device isn't USB-locked, flash it over USB instead — it's safer and much less invasive. What follows should only be a last resort.
+
+*Example: a device stuck on Biscuit firmware, unresponsive to a normal USB flash.*
+
+![biscuit](./images/spiflash/stuck_on_biscuit.jpg)
+
+## Required Tools
+
+- Acetone or another nail polish remover.
+- A SPI flash programmer. On this guide we use a CH341a; A Bus Pirate, Raspberry Pi/Pico or suitable Arduino, also works.
+- Programmer software. flashrom (with libftdi) work on all OSs.
+- esptool.py, but only if you intend to dump firmware from another device to use as your source image.
+  
+## Before You Start
+
+- Lithium batteries are dangerous, do not short or puncture. Be careful.
+- The display is fragile, don't bend or flex it. do not force the ZIF connector.
+- There is no undo here. A mis-wired clip or a short circuit can turn a bricked device into a dead one. Proceed at your own risk.
+
+
+## Procedure
+
+### 1. Obtain a Firmware Image
+
+Two options:
+
+- Use the backup provided by @Uri-Tauber at `crosspoint-reader/docs/images/spiflash/crosspoint_spiflash_backup.tar.xz`, and extract the `.bin` file.
+- Dump one yourself from a working, unlocked device over USB:
+    - Turn the device on, connect the USB cable and do:
+    ```bash
+    ~$ pio pkg exec -p tool-esptoolpy -- esptool.py --chip esp32c3 -p /dev/ttyACM0 -b 921600 read_flash 0x000000     0x1000000 crosspoint_backup.bin
+     # or
+    ~$ esptool.py --chip esp32c3 -p /dev/ttyACM0 -b 921600 read_flash 0x000000 0x1000000 crosspoint_backup.bin
+    ```
+
+### 2. Disconnect Power Sources and Accessories
+
+- Remove and set the SD card aside for reinsertion later.
+- Remove any USB cable.
+- Confirm nothing else is supplying power to the board.
+
+### 3. Remove the Screen
+
+Ordinary nail polish remover softens the adhesive under the screen's edges — it takes some patience, and there's no clean way around that.
+
+- In a well ventilated space, free of any ignition source, apply acetone or nail polish remover to the borders of the screen.
+- Check it from time to time, make sure the borders of the screen stay wet for around 2 hours.
+- Start to pry open from a lower corner, and move around.
+- If necessary, use a non-conductive tool to help you.
+- Flip open the ZIF connector to release the screen from the board.
+
+![screen](./images/spiflash/remove_screen.jpg)
+![inside](./images/spiflash/inside.jpg)
+
+### 4. Disconnect the Battery
+
+Cut a single battery wire close to the board, then cover the cut end with tape to prevent shorting.
+
+![battery](./images/spiflash/disconnect_battery_and_sd_card.jpg)
+
+### 5. Hold the Reset Button Down
+
+Keeping reset held prevents the ESP32-C3 from interfering with SPI communication during the read/write. A piece of pointed plastic works well as a holder.
+
+![reset](./images/spiflash/press_and_hold_reset.jpg)
+
+### 6. Attach the Test Clip
+
+Connect the test clip to the flash chip before connecting the programmer to USB. Notes:
+
+- The clip's red wire aligns with pin 1, marked with a dot on both the chip and the board silkscreen.
+- Confirm each lead is making contact with a chip pin and not the epoxy body.
+- If the programmer has a voltage selector, set it to 3.3V.
+- Verify no other power source is connected — use a multimeter if there's any doubt.
+  
+![chip](./images/spiflash/spi_flash_chip.jpg)
+![connect](./images/spiflash/connect_clip_to_spiflash_chip.jpg)
+
+### 7. Connect the Programmer to the PC
+
+![ready](./images/spiflash/ready.jpg)
+
+### 8. Verify the Connection by Reading Twice
+
+Read the chip twice and compare hashes. If they don't match, something in the clip connection is off — fix that before writing anything to the chip.
+
+```bash
+~$ sudo flashrom --programmer ch341a_spi -r backup_0.bin
+    [...]
+    Reading flash... done.
+~$ sudo flashrom --programmer ch341a_spi -r backup_1.bin
+    [...]
+    Reading flash... done.
+    # lets compare the hashes from the back ups
+~$ md5sum backup_0.bin
+    211522e56616ea46ac9bcf82d3451eb2  backup_0.bin
+~$ md5sum backup_1.bin
+    211522e56616ea46ac9bcf82d3451eb2  backup_1.bin
+```
+
+### 9. Flash the Chip
+
+```bash
+~$ sudo flashrom --programmer ch341a_spi -w crosspoint_backup.bin
+    [...]
+    Reading old flash chip contents... done.
+    Erasing and writing flash chip... Erase/write done.
+    Verifying flash... VERIFIED.
+```
+
+### 10. Power and Test The Device
+
+- Disconnect the programmer from the USB port.
+- Remove the test clip.
+- Release the reset button.
+- Reinsert the SD card.
+- Reconnect the screen.
+- Power the device via USB cable, no need to solder the battery yet.
+- Press the power button for a couple seconds.
+
+![success 0](./images/spiflash/success_0.jpg)
+![success 1](./images/spiflash/success_1.jpg)
+
+If CrossPoint boots successfully, the device can be fully reassembled.
+