feat: add the library text core — unicode fold, filename parse, author keys (#2885)

## Summary

Reduces active-reading power draw ~3.2x, measured end-to-end on an X3
with a [Nordic
PPK2](https://www.nordicsemi.com/Products/Development-hardware/Power-Profiler-Kit-2)
at the battery terminals (slim build, USB cable removed, 3.8v). Three
independent changes:

1. **Light-sleep between input polls when idle** (the big one): after 1
s of inactivity the main loop replaces its busy `delay(50)` with 50 ms
timer-paced `esp_light_sleep_start()` slices. Poll cadence and input
latency are unchanged — the CPU sleeps between polls instead of spinning
at 10 MHz. Guards: never sleeps while a `HalPowerManager::Lock` is held
(render in flight), WiFi is up, or USB is connected (light sleep kills
the CDC link).
2. **Two-stage idle backoff**: downclock at 500 ms, light sleep at 1 s,
replacing the flat 3 s full-speed window. Renders re-raise the clock via
`Lock` the moment they start, so the full-speed tail only ever served
loop bookkeeping. (The 3 s value in #852 was a placeholder;
responsiveness verified on device against stock.)
3. **Refresh BUSY-wait downclock**: drops the CPU to 10 MHz while
`pollBusy()` polls the BUSY pin (0.3–2 s per refresh), via new optional
hooks in the SDK — **depends on Free-Ink/freeink-sdk/pull/8**. Plus a 1
Hz throttle on the X3's I2C-based USB detection (was polled every loop).

(1+2) reduced average static-page-current from 9.68mA to 3.45mA.
Reducing the battery-monitor polling frequency further reduced it to
2.78mA.

Before merging, we'll need to update the submodule reference.

## Measured results (PPK2, X3)

| Metric | Before | After |
|---|---|---|
| Idle on a static page | 9.68 mA | **2.78 mA** |
| Fast page turn (incl. post-turn behavior) | ~100 mC | **28.98 mC** |
| Post-turn 160 MHz tail | 21.2 mA x 3 s | eliminated |
| Session average @ 30 s/page | ~11.6 mA | **~3.6 mA (~3.2x reading
time)** |
| Deep sleep | 12.8 µA | unchanged |

## Typical-day profiles

Assuming someone spends 30s per page.

- **Light**: 1 h reading, 10 lock/wake cycles, remaining ~23 h deep
sleep
- **Heavy**: 2 h reading, 20 lock/wake cycles, remaining ~22 h deep
sleep
- Per-day cost components: reading 11.6 → 3.6 mA (session avg),
lock+wake cycle
0.113 → 0.099 mAh each (sleep-screen mode), deep sleep 12.8 µA
(unchanged,
  ~0.29 mAh/day)
- Excluded: WiFi sessions, cold chapter indexing, self-discharge

### Days per charge (650mAh)

| Profile | Before | After | Ratio |
|---|---|---|---|
| Light (1 h/day, 10 locks) | 13.0 mAh/day → ~50 days | 4.9 mAh/day →
~133 days | 2.7× |
| Heavy (2 h/day, 20 locks) | 25.7 mAh/day → ~25 days | 9.5 mAh/day →
~68 days | 2.7× |
| Pure active reading | 11.6 mA → ~56 h | 3.6 mA → ~180 h | 3.2× |

### Caveats

- "After" saturates in reality: Li-ion self-discharge (~2–3%/month) is
not modeled
  and becomes the limiter once firmware draw is this low.
- Faster page-turners trend toward ~2.8×, slower readers slightly above
3.2×.
- Frequent locking dilutes the ratio (wake = full cold boot, barely
touched by the
power branch): at 10–20 locks/day, cycles are ~20% of the "after"
budget.
---

### AI Usage

While CrossPoint doesn't have restrictions on AI tools in contributing,
please be transparent about their usage as it
helps set the right context for reviewers.

Did you use AI tools to help write this code? _**YES**_

---------

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

AGENTS.md

@@ -1 +1 @@
-/home/urit/Documents/CrossPoint/crosspoint-reader/.skills/SKILL.md
+.skills/SKILL.md

README.md

@@ -36,7 +36,7 @@ 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.
 
@@ -136,7 +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) - FreeInkUI components for new screens, the touch bridge for existing ones, and build envs for the non-Xteink touch devices
+- [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
 
 ---
 

USER_GUIDE.md

@@ -186,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
@@ -501,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
@@ -515,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.
 

docs/contributing/touch-and-ui.md

@@ -1,23 +1,88 @@
 # Touch and UI Development
 
-CrossPoint now runs on touch devices (Seeed Sticky, M5Paper, LilyGo T5) alongside the button-only Xteink X3/X4. Every screen must work with both input styles. There are two supported ways to get there:
+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.
 
-1. **New screens: build them with FreeInkUI components.** Touch hit-testing, tap highlighting, long-press, and button focus navigation come with the component; you never hand-roll coordinate math.
-2. **Existing screens and in-flight features: use the MappedInputManager touch bridge.** A small set of helpers adds tap/hold/swipe support to hand-rolled rendering without restructuring the activity.
+**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.
 
-If you are starting a new activity, use FreeInkUI. If you have a feature branch with a hand-rolled screen already working on buttons, use the bridge; do not rewrite mid-flight.
+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.
 
 ---
 
-## Path 1: New screens with FreeInkUI
+## Picking the right host
 
-FreeInkUI (`freeink-sdk/libs/ui/FreeInkUI`, namespace `freeink::ui`) is an immediate-mode component library. The core idea:
+| 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` |
 
-- While a component renders, it registers its tappable areas ("hit rects") into the frame's interaction buffer via `Frame::hit(rect, action, value, inputMask, state)`.
-- Each loop you build an `InputSnapshot` from the input manager and route it against that buffer. If a tap (or mapped button press) lands in a registered rect, the routed `ActionEvent` tells you which action fired and with what value.
-- Components query `frame.stateFor(action, value)` while painting, so touch-down highlight and focus states render correctly without any per-activity code.
+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.
 
-You get touch, hold highlighting, long-press, minimum touch-target sizing, and orientation-aware coordinates for free. The same action IDs fire from physical buttons, so one code path serves both input styles.
+## 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
 
@@ -33,106 +98,11 @@ All under `freeink-sdk/libs/ui/FreeInkUI/include/components/`:
 | Media | `book-card`, `cover-grid`, `cover-carousel`, `metric-card` |
 | Text | `text-field`, `text-area` |
 
-### Integration skeleton
-
-The in-tree reference is [`src/activities/util/KeyboardEntryActivity.cpp`](../../src/activities/util/KeyboardEntryActivity.cpp); it drives the FreeInkUI keyboard component inside a normal Activity. The shape:
-
-```cpp
-#include <FreeInkUIGfxRenderer.h>
-namespace fui = freeink::ui;
-
-// Render step: draw the component and (re)register its hit rects.
-fui::GfxRendererTarget target(renderer);           // adapts GfxRenderer to FreeInkUI's DrawTarget
-target.setFont(fui::GfxRendererTarget::FONT_BODY, UI_12_FONT_ID);
-const fui::DeviceContext device = target.deviceContext();  // orientation, safe area, touch sizing
-
-fui::Frame<48> frame(target, device, fui::InputSnapshot{}, interactions);  // 48 = max hit rects
-fui::KeyboardProps props;
-props.layout = &currentLayout();
-props.keyAction = ACTION_KEY;                      // one action id; the key is the event value
-props.inputMask = fui::InputTouch | fui::InputLongPress;
-fui::keyboard(frame, kbRect, props);               // draws AND registers hit rects
-```
-
-```cpp
-// Input step (each loop): feed touch state, act on routed events.
-int tx, ty, tapX, tapY, hx, hy;
-const bool pressedDown = mappedInput.wasScreenTouchDown(tx, ty);
-const bool tapped      = mappedInput.wasScreenTapped(tapX, tapY);
-const bool inContact   = mappedInput.isScreenTouchHeld(hx, hy);
-
-const auto result = touchRouter.update(interactions, pressedDown, tx, ty,
-                                       tapped, tapX, tapY, inContact, millis());
-if (result.event) {
-  activateValue(result.event.value, result.event.longPress);
-  requestUpdate();
-} else if (result.activeChanged) {
-  requestUpdate();  // repaint touch-down highlight
-}
-```
-
-Notes:
-
-- `Frame<N>` is templated on the max number of hit rects; the buffer is stack/static, no heap.
-- `fui::TouchHoldRouter` (see `components/keyboard/keyboard.h`) synthesizes long-press while the finger is still down and swallows the eventual release. Use it whenever a component distinguishes tap from long-press.
-- For simpler screens without long-press, `FreeInkApp` / `Screen<N>` (`FreeInkApp.h`) is the ergonomic layer: it owns the interaction buffer, offers a top-to-bottom builder (`takeTop`, footer helpers, etc.), and its `render(input)` call routes the snapshot and dispatches registered action callbacks in one step. `snapshotFrom(input, device)` in `FreeInkUIInputManager.h` builds the `InputSnapshot` with orientation-aware touch mapping.
-- Everything stays allocation-free and works on the button-only devices unchanged: physical buttons route through the same interaction table via each hit rect's `inputMask`.
+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.
 
 ---
 
-## Path 2: Adding touch to existing hand-rolled screens
-
-For activities that draw their own rows, menus, and buttons, `MappedInputManager` ([src/MappedInputManager.h](../../src/MappedInputManager.h)) exposes bridge helpers. They all return **logical screen coordinates** (orientation already applied via `GfxRenderer::tapToLogical`); never touch raw normalized panel coordinates or the SDK `InputManager` directly.
-
-| Helper | Use for |
-|---|---|
-| `wasScreenTapped(x, y)` | A completed tap (press + release), with logical coords |
-| `wasScreenTouchDown(x, y)` | Touch-down (held > 90 ms, not yet released): draw selection highlight |
-| `isScreenTouchHeld(x, y)` | Live contact position while the finger is down (drag tracking) |
-| `wasTapInRect(x, y, w, h)` | One-off hit test on a rectangle (a single button, a banner) |
-| `wasListItemTapped(index, count, selected, listTop, listHeight, hasSubtitle)` | Taps on a standard UITheme list; does the row/paging math for you |
-| `wasListItemTouchedDown(...)` | Same geometry, touch-down phase (highlight before activate) |
-| `rowTouch(row, top, rowStep, rowCount, xStart, xEnd, rowHeight)` | Any custom band of equal-height rows; returns `RowTouch::None/Down/Tap` |
-| `colTouch(col, left, colStep, colCount, yStart, yEnd, colWidth)` | Horizontal button bands (dialogs, prompts) |
-| `wasSwipe()` | Raw swipe direction if you need one beyond the global gestures |
-| `hasTouch()` | True when the device has a touch panel (rarely needed; helpers simply never fire without one) |
-
-### Pattern A: standard themed list
-
-One call per loop; UITheme owns the row geometry ([EpubReaderBookmarksActivity.cpp:123](../../src/activities/reader/EpubReaderBookmarksActivity.cpp)):
-
-```cpp
-int tapped = -1;
-if (mappedInput.wasListItemTapped(tapped, bookmarks.size(), selectorIndex, listY, listHeight, true)) {
-  selectorIndex = tapped;
-  openBookmark();
-  return;
-}
-```
-
-### Pattern B: custom rows with hold highlight
-
-For non-theme row layouts, use `rowTouch` and distinguish `Down` (highlight) from `Tap` (activate), as in [EpubReaderFootnotesActivity.cpp](../../src/activities/reader/EpubReaderFootnotesActivity.cpp):
-
-```cpp
-int row = -1;
-const auto touch = mappedInput.rowTouch(row, listTop, lineHeight, visibleCount,
-                                        contentX, contentX + contentWidth);
-if (touch != MappedInputManager::RowTouch::None) {
-  const int touched = scrollOffset + row;
-  if (touch == MappedInputManager::RowTouch::Down) {
-    if (selectedIndex != touched) { selectedIndex = touched; requestUpdate(); }
-  } else {  // RowTouch::Tap
-    selectedIndex = touched;
-    activateSelection();
-  }
-  return;
-}
-```
-
-The `Down` state exists because e-ink repaints are slow: highlight on touch-down gives immediate feedback, activation happens on release.
-
-### Global gestures: do not reimplement these
+## Global gestures: do not reimplement these
 
 Three gestures are handled once, for every screen. Activities must not add their own edge-swipe handling:
 
@@ -142,14 +112,25 @@ Three gestures are handled once, for every screen. Activities must not add their
 | Home | Up-swipe starting in the bottom 14% | `ActivityManager::loop()`; pops to Home (activities can override via `handleHomeGesture()`) |
 | Menu | Down-swipe starting in the top 14% | Activities that have a menu check `wasMenuGesture()` themselves (the reader does this) |
 
-Because the back gesture arrives as `Button::Back`, most button-era activities gain back-swipe support with zero changes. That is the bar to aim for: bridge helpers should make touch an additive layer over the button flow, not a second input state machine.
+Because the back gesture arrives as `Button::Back`, most button-era activities gain back-swipe support with zero changes.
 
-### Bridge rules
+---
 
-- Handle touch in `loop()` next to the existing button handling, one helper call per interaction zone, and `return` after consuming an event (mirrors the button pattern).
-- Never call the SDK `InputManager` or read GPIO directly; the HAL rule from the main guide applies to touch too.
-- Coordinates from the helpers are logical and orientation-correct on all four rotations; test at least Portrait and one Landscape mode before PR.
-- Nothing to clean up in `onExit()`; the helpers are stateless from the activity's point of view.
+## 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.
 
 ---
 

docs/dictionary.md

@@ -13,7 +13,7 @@ A dictionary folder must contain:
 - `.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), and HTML-formatted definitions render as raw markup rather than styled text.
+Not supported: dictionaries with 64-bit index offsets (`idxoffsetbits=64` in the `.ifo` — rare, and rejected with an error).
 
 ## Setting Up a Dictionary
 
@@ -49,6 +49,8 @@ On the very first lookup with a dictionary (and again whenever the `.idx` or `.s
 
 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
 

lib/Epub/Epub/Section.cpp

@@ -33,10 +33,7 @@ namespace {
 // v35: Persist a uint32_t visible-text start offset for every page.
 // v36: Ruby and CJK justification layout changes invalidate cached word positions.
 // v37: Footnote href records grew from 96 to 256 bytes.
-// v38: Image top margin is clamped so a full-viewport-height image cannot
-//      overflow the page bottom; older caches can hold placements that panels
-//      with no bottom inset refuse to draw.
-constexpr uint8_t SECTION_FILE_VERSION = 38;
+constexpr uint8_t SECTION_FILE_VERSION = 37;
 // Written into the version field while a build is in progress; patched to
 // SECTION_FILE_VERSION only when the build is finalized. An abandoned /
 // crash-interrupted .bin therefore carries version 0, which loadSectionFile rejects

lib/Epub/Epub/converters/ImageToFramebufferDecoder.cpp

@@ -1,28 +1,16 @@
 #include "ImageToFramebufferDecoder.h"
 
-#include <Arduino.h>
 #include <Logging.h>
 
 bool ImageToFramebufferDecoder::validateImageDimensions(int width, int height, const std::string& format) {
-  // 64-bit multiply: a malformed header (e.g. 40000x60000) overflows a plain
-  // int product before the comparison can reject it.
-  const int64_t pixels = static_cast<int64_t>(width) * static_cast<int64_t>(height);
-  if (pixels > MAX_SOURCE_PIXELS) {
-    LOG_ERR("IMG", "Image too large (%dx%d = %lld pixels %s), max supported: %lld pixels", width, height,
-            static_cast<long long>(pixels), format.c_str(), static_cast<long long>(MAX_SOURCE_PIXELS));
+  if (width * height > MAX_SOURCE_PIXELS) {
+    LOG_ERR("IMG", "Image too large (%dx%d = %d pixels %s), max supported: %d pixels", width, height, width * height,
+            format.c_str(), MAX_SOURCE_PIXELS);
     return false;
   }
   return true;
 }
 
-void ImageToFramebufferDecoder::yieldDuringDecode(uint32_t& lastYieldMs) {
-  const uint32_t now = millis();
-  if (now - lastYieldMs >= 250) {
-    lastYieldMs = now;
-    vTaskDelay(1);
-  }
-}
-
 void ImageToFramebufferDecoder::warnUnsupportedFeature(const std::string& feature, const std::string& imagePath) {
   LOG_ERR("IMG", "Warning: Unsupported feature '%s' in image '%s'. Image may not display correctly.", feature.c_str(),
           imagePath.c_str());

lib/Epub/Epub/converters/ImageToFramebufferDecoder.h

@@ -31,21 +31,9 @@ class ImageToFramebufferDecoder {
 
   virtual const char* getFormatName() const = 0;
 
-  // Call from per-row/per-MCU decode callbacks (free functions, hence public):
-  // yields one tick at most every 250 ms so multi-second decodes keep the idle
-  // task (and its watchdog) fed. `lastYieldMs` is caller-held state,
-  // initialized to the decode start time.
-  static void yieldDuringDecode(uint32_t& lastYieldMs);
-
  protected:
-  // Size validation helpers. The cap bounds decode TIME, not memory: both decoders
-  // stream (JPEG in MCU bands at 1/2..1/8 coarse scale, PNG scanline-by-scanline
-  // with its own width-based row-buffer guard), so RAM never scales with source
-  // area. 8 MP admits real-world ebook covers (KDP recommends 1600x2560 and
-  // 2000x3000) while keeping a worst-case single decode in single-digit seconds;
-  // the row callbacks yield periodically so a long decode cannot starve the idle
-  // task's watchdog.
-  static constexpr int64_t MAX_SOURCE_PIXELS = 8388608;  // 8 MP (e.g. 2048 * 4096)
+  // Size validation helpers
+  static constexpr int MAX_SOURCE_PIXELS = 3145728;  // 2048 * 1536
 
   bool validateImageDimensions(int width, int height, const std::string& format);
   void warnUnsupportedFeature(const std::string& feature, const std::string& imagePath);

lib/Epub/Epub/converters/JpegToFramebufferConverter.cpp

@@ -46,8 +46,6 @@ struct JpegContext {
 
   PixelCache cache;
   bool caching{false};
-
-  uint32_t lastYieldMs{0};  // throttle state for yieldDuringDecode()
 };
 
 // File I/O callbacks use pFile->fHandle to access the HalFile*,
@@ -124,8 +122,6 @@ int jpegDrawCallback(JPEGDRAW* pDraw) {
   JpegContext* ctx = reinterpret_cast<JpegContext*>(pDraw->pUser);
   if (!ctx || !ctx->config || !ctx->renderer) return 0;
 
-  ImageToFramebufferDecoder::yieldDuringDecode(ctx->lastYieldMs);
-
   // In EIGHT_BIT_GRAYSCALE mode, pPixels contains 8-bit grayscale values
   // Buffer is densely packed: stride = pDraw->iWidth, valid columns = pDraw->iWidthUsed
   uint8_t* pixels = reinterpret_cast<uint8_t*>(pDraw->pPixels);
@@ -498,7 +494,6 @@ bool JpegToFramebufferConverter::decodeToFramebuffer(const std::string& imagePat
   }
 
   unsigned long decodeStart = millis();
-  ctx.lastYieldMs = decodeStart;
   rc = jpeg->decode(0, 0, jpegScaleOption);
   unsigned long decodeTime = millis() - decodeStart;
 

lib/Epub/Epub/converters/PngToFramebufferConverter.cpp

@@ -38,8 +38,6 @@ struct PngContext {
   bool caching{false};
 
   uint8_t* grayLineBuffer{nullptr};
-
-  uint32_t lastYieldMs{0};  // throttle state for yieldDuringDecode()
 };
 
 // File I/O callbacks use pFile->fHandle to access the HalFile*,
@@ -208,8 +206,6 @@ int pngDrawCallback(PNGDRAW* pDraw) {
   PngContext* ctx = reinterpret_cast<PngContext*>(pDraw->pUser);
   if (!ctx || !ctx->config || !ctx->renderer || !ctx->grayLineBuffer) return 0;
 
-  ImageToFramebufferDecoder::yieldDuringDecode(ctx->lastYieldMs);
-
   int srcY = pDraw->y;
   int srcWidth = ctx->srcWidth;
 
@@ -436,7 +432,6 @@ bool PngToFramebufferConverter::decodeToFramebuffer(const std::string& imagePath
   }
 
   unsigned long decodeStart = millis();
-  ctx.lastYieldMs = decodeStart;
   rc = png->decode(&ctx, 0);
   unsigned long decodeTime = millis() - decodeStart;
 

lib/Epub/Epub/parsers/ChapterHtmlSlimParser.cpp

@@ -793,18 +793,7 @@ void XMLCALL ChapterHtmlSlimParser::startElement(void* userData, const XML_Char*
                   self->currentPageVisibleOffsetSet = false;
                 }
 
-                // Apply top margin from container block. Clamp it so the image never
-                // overflows the page bottom: a full-viewport-height image leaves no room
-                // for the margin, and the break above only fires on non-empty pages, so a
-                // fresh page would otherwise place the image at y=marginTop and run
-                // marginTop pixels past viewportHeight. A large bottom reserve (status
-                // bar / big screen margin) absorbs that overflow silently, but with a
-                // thin reserve it crosses the physical screen edge and fails
-                // ImageBlock::render's bounds check, dropping the image entirely.
-                if (self->currentPageNextY + imageMarginTop + displayHeight > self->viewportHeight) {
-                  const int room = self->viewportHeight - displayHeight - self->currentPageNextY;
-                  imageMarginTop = static_cast<int16_t>(room > 0 ? room : 0);
-                }
+                // Apply top margin from container block
                 self->currentPageNextY += imageMarginTop;
 
                 // Create ImageBlock and add to page

lib/GfxRenderer/GfxRenderer.cpp

@@ -727,11 +727,14 @@ void GfxRenderer::drawRect(const int x, const int y, const int width, const int
 // Border is inside the rectangle
 void GfxRenderer::drawRect(const int x, const int y, const int width, const int height, const int lineWidth,
                            const bool state) const {
+  // Keep the border inside [x, x+width) like the thin overload: the previous
+  // right/bottom edges at x+width / y+height sat one pixel outside the rect,
+  // so stroked boxes looked shifted against fills computed from the rect.
   for (int i = 0; i < lineWidth; i++) {
-    drawLine(x + i, y + i, x + width - i, y + i, state);
-    drawLine(x + width - i, y + i, x + width - i, y + height - i, state);
-    drawLine(x + width - i, y + height - i, x + i, y + height - i, state);
-    drawLine(x + i, y + height - i, x + i, y + i, state);
+    drawLine(x + i, y + i, x + width - 1 - i, y + i, state);
+    drawLine(x + width - 1 - i, y + i, x + width - 1 - i, y + height - 1 - i, state);
+    drawLine(x + width - 1 - i, y + height - 1 - i, x + i, y + height - 1 - i, state);
+    drawLine(x + i, y + height - 1 - i, x + i, y + i, state);
   }
 }
 

lib/I18n/translations/catalan.yaml

@@ -278,6 +278,7 @@ STR_BOOKMARK_REMOVED: "S'ha eliminat el punt de llibre."
 STR_OPDS_BROWSER: "Navegador OPDS"
 STR_COVER_CUSTOM: "Portada + Personalitzat"
 STR_QUICK_RESUME: "Represa ràpida"
+STR_TRANSPARENT: "Transparent"
 STR_MENU_RECENT_BOOKS: "Llibres recents"
 STR_REMOVE_FROM_RECENTS: "Vols suprimir-lo de Llibres recents?"
 STR_NO_RECENT_BOOKS: "No hi ha llibres recents"

lib/I18n/translations/english.yaml

@@ -299,12 +299,14 @@ STR_THEME_LYRA_EXTENDED: "Lyra Extended"
 STR_SUNLIGHT_FADING_FIX: "Sunlight Fading Fix"
 STR_REMAP_FRONT_BUTTONS: "Remap Front Buttons"
 STR_BOOKMARKS: "Bookmarks"
+STR_NO_BOOKMARKS: "No bookmarks"
 STR_BOOKMARK_ADDED: "Bookmark added."
 STR_BOOKMARK_REMOVED: "Bookmark removed."
 STR_OPDS_BROWSER: "OPDS Browser"
 STR_SEARCH: "Search"
 STR_COVER_CUSTOM: "Cover + Custom"
 STR_QUICK_RESUME: "Quick Resume"
+STR_TRANSPARENT: "Transparent"
 STR_MENU_RECENT_BOOKS: "Recent Books"
 STR_REMOVE_FROM_RECENTS: "Remove from Recent Books?"
 STR_NO_RECENT_BOOKS: "No recent books"

lib/I18n/translations/orangutan.yaml

@@ -0,0 +1,328 @@
+_language_name: "Orangutan"
+_language_code: "OOK"
+_order: "34"
+
+STR_CROSSPOINT: "CrossPoint"
+STR_BOOTING: "OOK"
+STR_SLEEPING: "Oooook"
+STR_ENTERING_SLEEP: "Ook..."
+STR_BROWSE_FILES: "Ook? OOK"
+STR_FILE_TRANSFER: "Oook!"
+STR_SETTINGS_TITLE: "OOK!"
+STR_CONTINUE_READING: "Oooook ook"
+STR_RESUME: "OOk!"
+STR_NO_OPEN_BOOK: "OOK?"
+STR_START_READING: "Ook ook"
+STR_NO_FILES_FOUND: "Oook?"
+STR_SELECT_CHAPTER: "Ook? Oook OOK!"
+STR_NO_CHAPTERS: "Ook..."
+STR_END_OF_BOOK: "Oooook."
+STR_EMPTY_CHAPTER: "OOk?"
+STR_INDEXING: "Oook..."
+STR_LOADING: "Ooook..."
+STR_LOADING_POPUP: "Oook"
+STR_LOOKUP: "Ook? Oook! OOK"
+STR_WIFI_NETWORKS: "Wi-Fi OOK"
+STR_NO_NETWORKS: "Oook?"
+STR_NETWORKS_FOUND: "%zu OOK"
+STR_SCANNING: "Oook..."
+STR_FINDING_SAVED_WIFI: "Oook Wi-Fi..."
+STR_CONNECTING: "Ooook..."
+STR_CONNECTING_SAVED_WIFI: "OOk Wi-Fi..."
+STR_SHOW_NETWORKS: "OOK"
+STR_CONNECTED: "Oook!"
+STR_CONNECTION_FAILED: "OOk?"
+STR_FORGET_NETWORK: "Oook?"
+STR_SAVE_PASSWORD: "OOK?"
+STR_PRESS_OK_SCAN: "OOk OK"
+STR_JOIN_NETWORK: "Oook!"
+STR_CREATE_HOTSPOT: "Ooook"
+STR_JOIN_DESC: "Oook Wi-Fi"
+STR_HOTSPOT_DESC: "Oooook Wi-Fi"
+STR_STARTING_HOTSPOT: "Ooook..."
+STR_HOTSPOT_MODE: "OOk!"
+STR_CONNECT_WIFI_HINT: "Oook Wi-Fi"
+STR_OPEN_URL_HINT: "Oook URL"
+STR_SCAN_QR_HINT: "Oook QR:"
+STR_CALIBRE_WIRELESS: "Calibre OOK"
+STR_NETWORK_LEGEND: "* = OOK | + = OOk"
+STR_MAC_ADDRESS: "MAC!"
+STR_CHECKING_WIFI: "OOk Wi-Fi..."
+STR_ENTER_WIFI_PASSWORD: "Oook Wi-Fi"
+STR_ADD_HIDDEN_NETWORK: "Oook..."
+STR_ENTER_WIFI_SSID: "OOk (SSID)"
+STR_TO_PREFIX: "Oo "
+STR_CALIBRE_RECEIVING: "Oook: "
+STR_CALIBRE_RECEIVED: "OOK!: "
+STR_CAT_DISPLAY: "OOK"
+STR_CAT_READER: "OOk"
+STR_CAT_CONTROLS: "Ook!"
+STR_CAT_SYSTEM: "Oook"
+STR_SLEEP_SCREEN: "Oooook"
+STR_NIGHT_MODE: "Ook!"
+STR_QUICK_RESUME_TIMEOUT: "Oook ook"
+STR_SLEEP_COVER_MODE: "Ook ook"
+STR_HIDE_BATTERY: "OOk %"
+STR_EXTRA_SPACING: "Oook ook"
+STR_TEXT_AA: "Ook-ook"
+STR_IMAGES: "OOk!"
+STR_IMAGES_DISPLAY: "Oook"
+STR_IMAGES_PLACEHOLDER: "Ooook"
+STR_IMAGES_SUPPRESS: "OOK"
+STR_EOB_HOME: "Oook"
+STR_EOB_CONTINUE_WITH: "Oook ook"
+STR_SHORT_PWR_BTN: "Oooook OOK"
+STR_ORIENTATION: "Ook? Oooook OOK"
+STR_SIDE_BTN_LAYOUT: "Oook ook"
+STR_TOUCH_READER_CONTROLS: "OOk! OOK"
+STR_FRONT_BTN_FOLLOW_ORIENTATION: "Oook OOK"
+STR_LONG_PRESS_BEHAVIOR: "Oooook OOK"
+STR_LONG_PRESS_BEHAVIOR_OFF: "OFF"
+STR_LONG_PRESS_BEHAVIOR_SKIP: "Oook!"
+STR_LONG_PRESS_BEHAVIOR_ORIENTATION: "Ook? OOK"
+STR_LONG_PRESS_MENU: "Oooook!"
+STR_FONT_PREVIEW_TEXT: "Ook ook ook."
+STR_FONT_FAMILY: "Oook OOK"
+STR_FONT_SIZE: "OOk OOK"
+STR_TEXT_SETTINGS: "Oooook OOK: Ook!"
+STR_FONT: "OOk!"
+STR_SIZE: "OOK"
+STR_LAYOUT: "Oook"
+STR_ALIGNMENT: "Oooook"
+STR_STYLE: "OOk!"
+STR_NOT_IN_PREVIEW: "Oook?"
+STR_LINE_SPACING: "Oook ook"
+STR_SCREEN_MARGIN: "OOk ook"
+STR_PARA_ALIGNMENT: "Ook OOK"
+STR_HYPHENATION: "Ooook"
+STR_TIME_TO_SLEEP: "Oook..."
+STR_SHOW_HIDDEN_FILES: "OOk?"
+STR_REMOVE_READ_FROM_RECENTS: "Oook OOK"
+STR_MOVE_FINISHED_TO_READ: "Ook! OOK"
+STR_REFRESH_FREQ: "Oook!"
+STR_KOREADER_SYNC: "KOReader OOK"
+STR_CHECK_UPDATES: "Oook!"
+STR_LANGUAGE: "OOk?"
+STR_CLEAR_READING_CACHE: "Oook OOK"
+STR_USERNAME: "Oook"
+STR_PASSWORD: "OOk!"
+STR_SYNC_SERVER_URL: "Oook URL"
+STR_DOCUMENT_MATCHING: "Oook OOK"
+STR_SEND_METADATA: "Ook! OOK"
+STR_SYNC_BEHAVIOR: "OOk ook"
+STR_ASK_EVERY_TIME: "Oook?"
+STR_SMART_SYNC: "Oook!"
+STR_AUTHENTICATE: "Oooook"
+STR_SIGN_UP: "OOk!"
+STR_KOREADER_USERNAME: "KOReader OOK"
+STR_KOREADER_PASSWORD: "KOReader OOk"
+STR_FILENAME: "Oook"
+STR_KOREADER_AUTH: "KOReader OOK"
+STR_DONE: "Oook"
+STR_DARK: "OOk!"
+STR_LIGHT: "Oook"
+STR_CUSTOM: "Ooook"
+STR_COVER: "OOk?"
+STR_NONE_OPT: "OOk!"
+STR_FIT: "OOk"
+STR_CROP: "OOK!"
+STR_NEVER: "Oook!"
+STR_IN_READER: "Ook? OOK"
+STR_ALWAYS: "Oooook"
+STR_IGNORE: "OOk?"
+STR_SLEEP: "Oook!"
+STR_PAGE_TURN: "Oook OOK"
+STR_FORCE_REFRESH: "Ook! OOK"
+STR_PORTRAIT: "Oook"
+STR_LANDSCAPE_CW: "Oook OOK"
+STR_INVERTED: "OOk!"
+STR_ORIENTATION_INVERTED: "Ook 180°"
+STR_LANDSCAPE_CCW: "OOk OOK"
+STR_PREV_NEXT: "OOk/OOK"
+STR_NEXT_PREV: "OOK/OOk"
+STR_KOSYNC: "KOSync"
+STR_BOOKMARK_OPTION: "Oook!"
+STR_DICTIONARY: "Oooook"
+STR_DISABLED: "OOk!"
+STR_NOTO_SERIF: "Noto OOK"
+STR_NOTO_SANS: "Noto OOk"
+STR_TIGHT: "OOk!"
+STR_NORMAL: "Oook"
+STR_WIDE: "OOk!"
+STR_JUSTIFY: "Ooook!"
+STR_ALIGN_LEFT: "OOk"
+STR_CENTER: "Oook"
+STR_ALIGN_RIGHT: "OOK!"
+STR_PAGES_1: "1 OOK"
+STR_PAGES_5: "5 OOk"
+STR_PAGES_10: "10 OOK"
+STR_PAGES_15: "15 OOk"
+STR_PAGES_30: "30 OooK"
+
+STR_UPDATE: "Oook!"
+STR_CURRENT_VERSION: "OOK: "
+STR_NEW_VERSION: "OOk: "
+STR_DOWNLOADING: "Oooook..."
+STR_UNNAMED: "OOk?"
+STR_HOLD_OPEN_TO_DELETE: "Oook OOK"
+STR_NEXT_PAGE: "OOk »"
+STR_PREV_PAGE: "« OOK"
+STR_NETWORK_PREFIX: "OOk: "
+STR_IP_ADDRESS_PREFIX: "IP: "
+STR_SD_CARD: "SD OOK"
+STR_BACK: "« OOK"
+STR_EXIT: "« OOk"
+STR_HOME: "« Oook"
+STR_SELECT: "OOk!"
+STR_SELECTED: "Oooook"
+STR_TOGGLE: "Oook!"
+STR_TOGGLE_BOOKMARK: "Ook? OOK! Oooook"
+STR_CONFIRM: "Oooook"
+STR_CANCEL: "OOk?"
+STR_CONNECT: "Oooook"
+STR_OPEN: "Oook"
+STR_DOWNLOAD: "Oooook"
+STR_RETRY: "Oook!"
+STR_YES: "OOk"
+STR_NO: "Oo"
+STR_SHOW: "Oook"
+STR_HIDE: "OOk!"
+STR_STATE_ON: "OK"
+STR_STATE_OFF: "OOk"
+STR_NOT_SET: "Oook"
+STR_DIR_LEFT: "OOk!"
+STR_DIR_RIGHT: "OOK!"
+STR_DIR_UP: "OK"
+STR_DIR_DOWN: "OOk!"
+STR_OK_BUTTON: "OK"
+STR_KEY_SHIFT: "OOk!"
+STR_KEY_MODE_SYMBOLS: "?123"
+STR_KEY_MODE_ABC: "abc"
+
+STR_SLEEP_COVER_FILTER: "Oook OOK"
+STR_FILTER_CONTRAST: "Oooook"
+STR_CUSTOMISE_STATUS_BAR: "Oook OOK"
+STR_CHAPTER_PAGE_COUNT: "OOk OOK"
+STR_BOOK_PROGRESS_PERCENTAGE: "Oook OOK"
+STR_PROGRESS_BAR: "Oook OOK"
+STR_PROGRESS_BAR_THICKNESS: "Oook OOK"
+STR_PROGRESS_BAR_THIN: "OOk!"
+STR_PROGRESS_BAR_MEDIUM: "Oook"
+STR_PROGRESS_BAR_THICK: "Oook!"
+STR_BOOK: "Oook"
+STR_CHAPTER: "OOk!"
+STR_EXAMPLE_CHAPTER: "OOk 21"
+STR_EXAMPLE_BOOK: "Oook OOK"
+STR_PREVIEW: "Oook!"
+STR_TITLE: "OOk?"
+STR_BATTERY: "Oook"
+STR_XTC_STATUS_BAR: "XTC OOK"
+STR_BOTTOM: "Oooook"
+STR_TOP: "OOk"
+STR_CLOCK: "Oook!"
+STR_CLOCK_UTC_OFFSET: "Oook OOK"
+STR_CLOCK_FORMAT: "OOk OOK"
+STR_CLOCK_FORMAT_24H: "24-OOK"
+STR_CLOCK_FORMAT_12H: "12-OOk"
+STR_CURRENT_TIME: "OOk:"
+STR_NEXT_FIELD: "Oook"
+STR_CLOCK_SYNC: "OOk OOK"
+STR_CLOCK_SYNC_NOW: "Oook OOK"
+STR_CLOCK_SYNCING: "Oooook..."
+STR_CLOCK_SYNC_OK: "Oook!"
+STR_CLOCK_SYNC_FAIL: "OOk?"
+STR_CLOCK_SYNC_NO_WIFI: "Wi-Fi OOK"
+STR_CLOCK_SYNCED: "Oooook"
+STR_UI_THEME: "OOk OOK"
+STR_THEME_CLASSIC: "Oook!"
+STR_THEME_LYRA: "OOk!"
+STR_THEME_ROUNDEDRAFF: "Oook"
+STR_THEME_LYRA_EXTENDED: "Oook OOK"
+STR_SUNLIGHT_FADING_FIX: "Oook OOK"
+STR_REMAP_FRONT_BUTTONS: "Oook OOK"
+
+STR_BOOKMARKS: "Ook! OOK Oooook"
+STR_NO_BOOKMARKS: "OOk?"
+STR_BOOKMARK_ADDED: "Ook!"
+STR_BOOKMARK_REMOVED: "Oook!"
+STR_OPDS_BROWSER: "OPDS OOK"
+STR_SEARCH: "Oook!"
+STR_COVER_CUSTOM: "OOk + OOK"
+STR_QUICK_RESUME: "Oook OOK"
+STR_MENU_RECENT_BOOKS: "Oook OOK"
+STR_REMOVE_FROM_RECENTS: "OOk?"
+STR_NO_RECENT_BOOKS: "Oook?"
+STR_CALIBRE_DESC: "Calibre OOK"
+STR_FORGET_AND_REMOVE: "Oook?"
+STR_FORGET_BUTTON: "Oook!"
+STR_CALIBRE_STARTING: "Calibre OOK"
+STR_CALIBRE_SETUP: "OOk!"
+STR_CALIBRE_STATUS: "Oook"
+STR_CLEAR_BUTTON: "Oook!"
+STR_DEFAULT_VALUE: "OOk OOK"
+STR_UNASSIGNED: "OOk?"
+STR_ALREADY_ASSIGNED: "Oook OOK"
+STR_GO_TO_PERCENT: "Oook! Ook? %"
+STR_GO_HOME_BUTTON: "Oook OOK! Oooook"
+STR_SYNC_PROGRESS: "Oooook OOK! Ook!"
+STR_DELETE_CACHE: "Oook OOK? Oooook!"
+STR_DELETE: "Oooook"
+STR_CONFIRM_DELETE_BOOKMARK: "Oook?"
+STR_DISPLAY_QR: "Oooook OOK QR!"
+STR_CHAPTER_PREFIX: "OOk: "
+STR_BOOK_PREFIX: "Oook: "
+STR_SYNCING_TIME: "Oook..."
+STR_FETCH_PROGRESS: "OOk..."
+STR_UPLOAD_PROGRESS: "Oooook..."
+STR_KOREADER_SETUP_HINT: "KOReader OOK"
+STR_PROGRESS_FOUND: "Oook!"
+STR_REMOTE_LABEL: "OOk:"
+STR_LOCAL_LABEL: "Oook:"
+STR_PAGE_OVERALL_FORMAT: "OOk %d, %.2f%%"
+STR_PAGE_TOTAL_OVERALL_FORMAT: "Oook %d/%d, %.2f%%"
+STR_DEVICE_FROM_FORMAT: "OOk: %s"
+STR_APPLY_REMOTE: "Oook OOK"
+STR_UPLOAD_LOCAL: "OOk OOK"
+STR_UPLOAD_PROMPT: "Oook?"
+STR_UPLOAD_SUCCESS: "Oooook!"
+STR_ALREADY_SYNCED: "Oook!"
+STR_SECTION_PREFIX: "OOk "
+STR_UPLOAD: "Oooook"
+STR_BOOK_S_STYLE: "Oook OOK"
+STR_EMBEDDED_STYLE: "OOk OOK"
+STR_FOCUS_READING: "Oook OOK"
+STR_OPDS_SERVER_URL: "OPDS OOK"
+STR_PWR_BTN_FOOTNOTE_BACK: "Oook OOK"
+STR_BACK_SHORT_TO_FILE_BROWSER: "OOk OOK"
+STR_SET_SLEEP_COVER: "Oook OOK"
+STR_FOOTNOTES: "Ook! Oook OOK"
+STR_NO_FOOTNOTES: "Oook?"
+STR_LINK: "[Ook]"
+STR_SCREENSHOT_BUTTON: "Oook! OOK? Ook!"
+STR_SLEEP_TIMER_VALUE_FORMAT: "%u OOK"
+STR_SLEEP_NEVER: "Oook!"
+STR_ADD_SERVER: "Oook!"
+STR_SERVER_NAME: "OOk OOK"
+STR_DELETE_SERVER: "Oook OOK"
+STR_OPDS_SERVERS: "OPDS OOK"
+STR_OPDS_DOWNLOAD_FOLDER: "Oook OOK"
+STR_OPDS_FILENAME_FORMAT: "OOk OOK"
+STR_FMT_AUTHOR_TITLE: "OOk - OOK"
+STR_FMT_TITLE_AUTHOR: "OOK - OOk"
+STR_FMT_TITLE: "Oook"
+STR_OPDS_SD_ROOT: "SD OOK"
+STR_AUTO_TURN_ENABLED: "OOk: "
+STR_AUTO_TURN_PAGES_PER_MIN: "Oooook OOK (Ook!)"
+STR_MANAGE_FONTS: "Oook OOK"
+STR_FONT_BROWSER: "OOk OOK"
+STR_LOADING_FONT_LIST: "Oooook..."
+STR_NO_FONTS_AVAILABLE: "Oook?"
+STR_FONT_INSTALLED: "Oook!"
+STR_INSTALLED: "OOk!"
+STR_DOWNLOAD_ALL: "Oook OOK"
+STR_UPDATE_ALL: "OOk OOK"
+STR_UPDATE_AVAILABLE: "Oook!"
+STR_TILT_PAGE_TURN: "Oook OOK"
+STR_SD_FIRMWARE_UPDATE: "SD Oooook Ooook Ooooook"
+STR_STEP_HINT_FRONT: "Ooook Ooooook:"
+STR_STEP_HINT_SIDE: "OOK Oook:"

lib/I18n/translations/spanish.yaml

@@ -303,6 +303,7 @@ STR_OPDS_BROWSER: "Navegador OPDS"
 STR_SEARCH: "Buscar"
 STR_COVER_CUSTOM: "Portada + Pers."
 STR_QUICK_RESUME: "Reanudación rápida"
+STR_TRANSPARENT: "Transparente"
 STR_MENU_RECENT_BOOKS: "Libros recientes"
 STR_REMOVE_FROM_RECENTS: "¿Eliminar de Libros recientes?"
 STR_NO_RECENT_BOOKS: "No hay libros recientes"

lib/I18n/translations/valencian.yaml

@@ -283,6 +283,7 @@ STR_BOOKMARK_REMOVED: "S'ha eliminat el punt de llibre."
 STR_OPDS_BROWSER: "Navegador OPDS"
 STR_COVER_CUSTOM: "Portada + Personalitzat"
 STR_QUICK_RESUME: "Represa ràpida"
+STR_TRANSPARENT: "Transparent"
 STR_MENU_RECENT_BOOKS: "Llibres recents"
 STR_REMOVE_FROM_RECENTS: "Vols eliminar-lo de Llibres recents?"
 STR_NO_RECENT_BOOKS: "No hi ha llibres recents"

lib/LibraryIndex/LibraryText.cpp

@@ -0,0 +1,346 @@
+#include "LibraryText.h"
+
+#include <Utf8.h>
+
+#include <algorithm>
+#include <array>
+#include <cstring>
+
+namespace library {
+namespace {
+
+// Letters with no canonical decomposition, plus the punctuation that would
+// otherwise become a space and break word shapes. Everything here is a distinct
+// letter in Unicode, so no amount of NFD gets us the ASCII form.
+struct CharMap {
+  uint32_t cp;
+  const char* replacement;
+};
+constexpr CharMap EXPLICIT_MAP[] = {
+    {0x00D8, "o"},   // Ø
+    {0x00F8, "o"},   // ø  — "Søren" folds to "soren", not "nesb"
+    {0x00C6, "ae"},  // Æ
+    {0x00E6, "ae"},  // æ
+    {0x0152, "oe"},  // Œ
+    {0x0153, "oe"},  // œ
+    {0x00DF, "ss"},  // ß
+    {0x0141, "l"},   // Ł
+    {0x0142, "l"},   // ł
+    {0x00D0, "d"},   // Ð
+    {0x00F0, "d"},   // ð
+    {0x0110, "d"},   // Đ
+    {0x0111, "d"},   // đ
+    {0x00DE, "th"},  // Þ
+    {0x00FE, "th"},  // þ
+    {0x0131, "i"},   // ı
+    {0x0027, "'"},   // ' — kept, not turned into a space, so "O'Brien" stays one word
+    {0x2019, "'"},   // ’ — and so the curly form folds to the same thing
+    {0x2018, "'"},   // ‘
+};
+
+const char* explicitMapping(const uint32_t cp) {
+  for (const auto& e : EXPLICIT_MAP) {
+    if (e.cp == cp) return e.replacement;
+  }
+  return nullptr;
+}
+
+// Reverse lookup in the NFC table: given a precomposed codepoint, return the
+// base letter it was composed from, or 0.
+//
+// The table is sorted by (base, mark) so this is a linear scan rather than a
+// binary search. It runs once per non-ASCII character at index-build time and
+// over a short query per keystroke, never over the whole index, so the scan is
+// not on any hot path. Reusing the generated table costs no extra flash — it is
+// already linked for utf8ComposeNfc().
+// Fully decompose: é -> e, and the rare doubly-accented forms (ế -> ê -> e).
+uint32_t stripDiacritics(uint32_t cp) {
+  for (int guard = 0; guard < 4; guard++) {
+    const uint32_t base = utf8DecomposedBase(cp);
+    if (base == 0) break;
+    cp = base;
+  }
+  return cp;
+}
+
+bool isAsciiAlnum(const uint32_t cp) {
+  return (cp >= '0' && cp <= '9') || (cp >= 'a' && cp <= 'z') || (cp >= 'A' && cp <= 'Z');
+}
+
+void appendLowerAscii(const uint32_t cp, std::string& out) {
+  out.push_back(static_cast<char>(cp >= 'A' && cp <= 'Z' ? cp - 'A' + 'a' : cp));
+}
+
+// Articles stripped from the head of sort and search keys. Display text never
+// goes through this.
+constexpr const char* ARTICLES[] = {"the ", "a ",   "an ", "le ",  "la ",  "les ", "l'",   "un ",
+                                    "une ", "de ",  "du ", "des ", "der ", "die ", "das ", "el ",
+                                    "los ", "las ", "il ", "lo ",  "gli ", "i ",   "o ",   "os "};
+
+// Views into `folded`, not copies: the caller keeps that string alive for as
+// long as the tokens, and a std::string per token costs an allocation each plus
+// 24 bytes of stack apiece -- 288 B for the twelve, over the 256 B this repo
+// asks callers to justify.
+void splitTokens(std::string_view folded, std::string_view* out, size_t maxTokens, size_t& count) {
+  count = 0;
+  size_t i = 0;
+  while (i < folded.size() && count < maxTokens) {
+    while (i < folded.size() && folded[i] == ' ') i++;
+    const size_t start = i;
+    while (i < folded.size() && folded[i] != ' ') i++;
+    if (i > start) out[count++] = folded.substr(start, i - start);
+  }
+}
+
+}  // namespace
+
+std::string fold(const std::string_view text, const bool stripArticle) {
+  std::string out;
+  out.reserve(text.size());
+
+  const auto* cursor = reinterpret_cast<const unsigned char*>(text.data());
+  const auto* end = cursor + text.size();
+  bool pendingSpace = false;
+
+  while (cursor < end) {
+    // The shared decoder stops on NUL and every std::string source is
+    // NUL-terminated, but fold's contract is string_view — and a view may end
+    // mid-sequence. Refuse to decode a lead byte whose continuation bytes lie
+    // past the end rather than trusting whatever sits there.
+    const unsigned char lead = *cursor;
+    const ptrdiff_t promised = lead < 0x80           ? 1
+                               : (lead >> 5) == 0x06 ? 2
+                               : (lead >> 4) == 0x0E ? 3
+                               : (lead >> 3) == 0x1E ? 4
+                                                     : 1;
+    if (promised > end - cursor) break;
+    const uint32_t cp = utf8NextCodepoint(&cursor);
+    if (cp == 0) break;
+
+    if (utf8IsCombiningMark(cp)) continue;  // already-decomposed input
+
+    const char* mapped = explicitMapping(cp);
+    if (mapped != nullptr) {
+      if (pendingSpace && !out.empty()) out.push_back(' ');
+      pendingSpace = false;
+      out.append(mapped);
+      continue;
+    }
+
+    const uint32_t base = stripDiacritics(cp);
+    if (isAsciiAlnum(base)) {
+      if (pendingSpace && !out.empty()) out.push_back(' ');
+      pendingSpace = false;
+      appendLowerAscii(base, out);
+      continue;
+    }
+
+    // Everything else — punctuation, symbols, unmapped scripts — separates
+    // words. Deferring the space keeps runs collapsed and drops trailing ones.
+    if (!out.empty()) pendingSpace = true;
+  }
+
+  if (stripArticle) {
+    for (const char* article : ARTICLES) {
+      const size_t len = strlen(article);
+      if (out.size() > len && out.compare(0, len, article) == 0) {
+        out.erase(0, len);
+        break;
+      }
+    }
+  }
+  return out;
+}
+
+std::string cleanPersonName(const std::string_view author) {
+  std::string out;
+  out.reserve(author.size());
+  int depth = 0;
+  for (size_t i = 0; i < author.size(); i++) {
+    const char c = author[i];
+    if (c == '[' || c == '(') {
+      depth++;
+      continue;
+    }
+    if (c == ']' || c == ')') {
+      if (depth > 0) depth--;
+      continue;
+    }
+    if (c == ';') break;  // secondary authors
+    if (depth > 0) continue;
+    if (c == '_') {
+      // "Herbert G_ Wells" — the underscore stands in for a full stop the
+      // filesystem would not take. Between letters it is an abbreviation dot;
+      // at the end of a word it is just noise.
+      const bool betweenLetters = i > 0 && i + 1 < author.size() &&
+                                  isalpha(static_cast<unsigned char>(author[i - 1])) &&
+                                  isalpha(static_cast<unsigned char>(author[i + 1]));
+      out.push_back(betweenLetters ? '.' : ' ');
+      continue;
+    }
+    out.push_back(c);
+  }
+
+  while (!out.empty() &&
+         (out.back() == ' ' || out.back() == ',' || out.back() == '-' || out.back() == '.' || out.back() == '_')) {
+    out.pop_back();
+  }
+  size_t start = 0;
+  while (start < out.size() && out[start] == ' ') start++;
+  out.erase(0, start);
+
+  // Collapse the space runs left behind by the removals.
+  std::string collapsed;
+  collapsed.reserve(out.size());
+  bool space = false;
+  for (const char c : out) {
+    if (c == ' ') {
+      space = true;
+      continue;
+    }
+    if (space && !collapsed.empty()) collapsed.push_back(' ');
+    space = false;
+    collapsed.push_back(c);
+  }
+
+  // "Austen, Jane" is the same person as "Jane Austen", and publishers use both.
+  // The spelling vote cannot settle it — with one book per author there is no
+  // majority — so the inverted form is turned round here instead. Only a single
+  // comma qualifies: "Smith, John, Jr." and lists of several authors are left
+  // exactly as they are rather than being scrambled.
+  const size_t comma = collapsed.find(',');
+  if (comma != std::string::npos && collapsed.find(',', comma + 1) == std::string::npos) {
+    std::string_view last(collapsed.data(), comma);
+    std::string_view first(collapsed.data() + comma + 1, collapsed.size() - comma - 1);
+    while (!first.empty() && first.front() == ' ') first.remove_prefix(1);
+    while (!last.empty() && last.back() == ' ') last.remove_suffix(1);
+    if (!first.empty() && !last.empty()) {
+      std::string swapped;
+      swapped.reserve(collapsed.size());
+      swapped.append(first);
+      swapped.push_back(' ');
+      swapped.append(last);
+      return swapped;
+    }
+  }
+  return collapsed;
+}
+
+std::string authorKey(const std::string_view author) {
+  // Drop bracketed spans ("George Sand [Sand, George]") and everything after
+  // a multi-author separator.
+  std::string cleaned;
+  cleaned.reserve(author.size());
+  int depth = 0;
+  for (const char c : author) {
+    if (c == '[' || c == '(') {
+      depth++;
+      continue;
+    }
+    if (c == ']' || c == ')') {
+      if (depth > 0) depth--;
+      continue;
+    }
+    if (c == ';') break;
+    if (depth == 0) cleaned.push_back(c);
+  }
+
+  const std::string folded = fold(cleaned);
+
+  constexpr size_t MAX_TOKENS = 12;
+  std::string_view tokens[MAX_TOKENS];
+  size_t count = 0;
+  splitTokens(folded, tokens, MAX_TOKENS, count);
+
+  // Initials carry no identity and appear inconsistently ("Herbert G Wells" vs
+  // "Herbert Wells"), so they must not change the key.
+  size_t kept = 0;
+  for (size_t i = 0; i < count; i++) {
+    if (tokens[i].size() > 1) tokens[kept++] = tokens[i];
+  }
+  std::sort(tokens, tokens + kept);
+
+  std::string key;
+  for (size_t i = 0; i < kept; i++) {
+    if (!key.empty()) key.push_back(' ');
+    key.append(tokens[i]);
+  }
+  // Truncate on bytes, not on a token boundary. Sorting puts a short forename
+  // first, so a whole-token cut would reduce "Wollstonecraft, Mary" to the key
+  // "alex" and merge every Alex in the library; the byte cut keeps
+  // "mary wollsto", which stays a prefix of the full key and discriminates.
+  if (key.size() > AUTHOR_KEY_MAX_BYTES) key.resize(AUTHOR_KEY_MAX_BYTES);
+  while (!key.empty() && key.back() == ' ') key.pop_back();
+  return key;
+}
+
+// fold() keeps the apostrophe, which is right for sorting — "L'Eneide" belongs
+// under L. For searching it is wrong: in French the word worth typing is the one
+// AFTER the apostrophe, so "eneide" must reach "L'Eneide" and "cote" must
+// reach "d'a cote". Treating it as a word boundary here leaves the sort untouched.
+bool isWordBreak(const char c) { return c == ' ' || c == '\''; }
+
+bool matchesQuery(const std::string_view haystack, const std::string_view needle) {
+  if (needle.empty()) return true;
+
+  // Walk the query one word at a time, and for each one scan the book's words for
+  // a prefix hit. Both strings are at most a couple of hundred bytes and this
+  // runs once per book per keypress, so a plain scan is cheaper than anything
+  // that would need building first.
+  size_t qs = 0;
+  while (qs < needle.size()) {
+    while (qs < needle.size() && isWordBreak(needle[qs])) qs++;
+    if (qs >= needle.size()) break;
+    size_t qe = qs;
+    while (qe < needle.size() && !isWordBreak(needle[qe])) qe++;
+    const std::string_view word = needle.substr(qs, qe - qs);
+
+    bool found = false;
+    size_t hs = 0;
+    while (hs < haystack.size() && !found) {
+      while (hs < haystack.size() && isWordBreak(haystack[hs])) hs++;
+      if (hs >= haystack.size()) break;
+      if (haystack.compare(hs, word.size(), word) == 0) {
+        found = true;
+        break;
+      }
+      while (hs < haystack.size() && !isWordBreak(haystack[hs])) hs++;
+    }
+    if (!found) return false;
+    qs = qe;
+  }
+  return true;
+}
+
+std::string surnameKey(const std::string_view displayAuthor) {
+  const std::string folded = fold(displayAuthor);
+  if (folded.empty()) return {};
+
+  size_t lastStart = std::string::npos;
+  size_t lastEnd = folded.size();
+  size_t i = folded.size();
+  while (i > 0) {
+    i--;
+    if (folded[i] != ' ') {
+      if (lastStart == std::string::npos) lastEnd = i + 1;
+      lastStart = i;
+    } else if (lastStart != std::string::npos) {
+      break;
+    }
+  }
+  if (lastStart == std::string::npos) return {};
+
+  std::string key;
+  key.reserve(folded.size() + 1);
+  key.append(folded, lastStart, lastEnd - lastStart);
+  // The given names follow, so two people sharing a surname stay in a stable,
+  // readable order rather than whichever the disk walk happened to produce.
+  if (lastStart > 0) {
+    key.push_back(' ');
+    key.append(folded, 0, lastStart);
+    while (!key.empty() && key.back() == ' ') key.pop_back();
+  }
+  return key;
+}
+
+}  // namespace library