ma-r-s · ma-r-s · Sep 4, 2026 · Aug 18, 2026 · Aug 18, 2026 · Aug 18, 2026
diff --git a/.github/workflows/pr-formatting-check.yml b/.github/workflows/pr-formatting-check.yml
@@ -6,6 +6,7 @@ on:
       - opened
       - reopened
       - edited
+      - synchronize
 
 permissions:
   pull-requests: read

diff --git a/.gitmodules b/.gitmodules
@@ -1,4 +1,4 @@
 [submodule "freeink-sdk"]
 	path = freeink-sdk
 	url = https://github.com/ma-r-s/freeink-sdk.git
-	branch = x4pro-measured-insets
+	branch = fix/sd-free-space
diff --git a/AGENTS.md b/AGENTS.md
@@ -887,9 +887,7 @@ Tested in all 4 orientations with 5MB+ files.
 **To add/modify translations (i18n)**:
 
 1. Edit or add YAML file: `lib/I18n/translations/<language>.yaml`
-
-   - Each file must contain: `_language_name`, `_language_code`, `_order`, and `STR_*` keys
-
+   - Each file must contain: `_language_name`, `_language_code`, `_order`, `_bcp47`, and `STR_*` keys
    - English (`english.yaml`) is the reference; missing keys in other languages fall back to English
 
 2. Run generator: `python scripts/gen_i18n.py lib/I18n/translations lib/I18n/`

diff --git a/SCOPE.md b/SCOPE.md
@@ -35,7 +35,7 @@ During this period, the priorities are:
 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.
+* **New external network connectors.** This includes sync engines, cloud storage clients, remote file access, and any new "talk to a server" feature. Fixes and improvements to the *existing* OPDS support (usability, performance, compatibility with more catalogs) remain in scope and welcome; what is closed is adding entirely new protocols or connectors. 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.
 

diff --git a/USER_GUIDE.md b/USER_GUIDE.md
@@ -6,6 +6,7 @@ Welcome to the **CrossPlay** firmware, a fork of CrossPoint for the Xteink X4 Pr
   - [1. Hardware Overview](#1-hardware-overview)
     - [Button Layout](#button-layout)
     - [Taking a Screenshot](#taking-a-screenshot)
+    - [Frontlight (X4 Pro only)](#frontlight-x4-pro-only)
   - [2. Power \& Startup](#2-power--startup)
     - [Power On / Off](#power-on--off)
     - [First Launch](#first-launch)
@@ -42,6 +43,7 @@ Welcome to the **CrossPlay** firmware, a fork of CrossPoint for the Xteink X4 Pr
     - [Auto Page Turn](#auto-page-turn)
     - [Tilt Page Turn (X3 only)](#tilt-page-turn-x3-only)
     - [Footnote Navigation](#footnote-navigation)
+    - [Dictionary Lookup](#dictionary-lookup)
     - [System Navigation](#system-navigation)
     - [Supported Languages](#supported-languages)
   - [5. Reader Menu](#5-reader-menu)
@@ -59,16 +61,28 @@ The device utilises the standard buttons on the Xteink X4 (in the same layout as
 | Location        | Buttons                                              |
 | --------------- | ---------------------------------------------------- |
 | **Bottom Edge** | **Back**, **Confirm**, **Left**, **Right**           |
-| **Right Side**  | **Power**, **Volume Up**, **Volume Down**, **Reset** |
+| **Right Side**  | **Power**, **Side Up**, **Side Down**, **Reset** |
 
 Button layout can be customized in the **[Controls Settings](#363-controls)**.
 
 ### Taking a Screenshot
 
-When the Power Button and Volume Down button are pressed at the same time, it will take a screenshot and save it in the folder `screenshots/`.
+When the Power button and the lower side button (Side Down) are pressed at the same time, it will take a screenshot and save it in the folder `screenshots/`.
 
 Alternatively, while reading a book, press the **Confirm** button to open the reader menu and select **Take screenshot**.
 
+### Frontlight (X4 Pro only)
+
+The X4 Pro has a built-in frontlight with adjustable brightness and warmth. It is controlled from a swipe panel rather than the Settings menu:
+
+* **Open the frontlight panel:** Swipe down from the top edge of the screen, from almost any screen (Home, Browse Files, Reading Mode, etc.). Drag the brightness and warmth sliders to adjust the light live, or tap the sun icon to turn it on or off.
+* **Quick toggle:** Double-click the **Power** button to turn the frontlight on or off instantly, without opening the panel.
+
+> [!NOTE]
+> Frontlight brightness and warmth are intentionally not listed in **[Display Settings](#361-display)** — the swipe panel is the only place to adjust them. The on/off state can also be toggled with the Power-button double-click above.
+
+If the frontlight doesn't come back on after the device wakes from sleep, check **Restore Light on Wake** in **[Display Settings](#361-display)** (on by default). Turning it off is intentional if you'd rather have the light stay off on wake and switch it on yourself each time — but it's easy to forget you changed it.
+
 ---
 
 ## 2. Power & Startup
@@ -103,7 +117,7 @@ See [Reading Mode](#4-reading-mode) below for more information.
 
 The Browse Files screen acts as a file and folder browser. The full path to the current directory is shown at the top of the screen. File extensions are displayed alongside each filename, and directories are shown with brackets (e.g. `[folder-name]`). Hidden directories (those beginning with `.`) are also visible.
 
-* **Navigate List:** Use **Left** (or **Volume Up**), or **Right** (or **Volume Down**) to move the selection cursor up and down through folders and books. You can also long-press these buttons to scroll a full page up or down.
+* **Navigate List:** Use **Left** (or **Side Up**), or **Right** (or **Side Down**) to move the selection cursor up and down through folders and books. You can also long-press these buttons to scroll a full page up or down.
 * **Open Selection:** Press **Confirm** to open a folder or start reading a selected book. Selecting a `.bmp` file will open the image viewer.
 * **Delete Files or Folders:** Hold and release **Confirm** to delete the selected file or folder. You will be given an option to either confirm or cancel. Multiple files can be selected for deletion in a single operation.
 * **Rename or Move:** Files can be renamed or moved to a different folder from within the browse screen.
@@ -275,7 +289,7 @@ The Settings screen allows you to configure the device's behavior. There are a f
 
 - **Remap Front Buttons**: A menu for customising the function of each bottom edge button.
 
-- **Side Button Layout (reader)**: Swap the order of the up and down volume buttons from "Prev/Next" (default) to "Next/Prev". You can also disable them entirely. This change is only in effect when reading.
+- **Side Button Layout (reader)**: Swap the order of the up and down side buttons from "Prev/Next" (default) to "Next/Prev". You can also disable them entirely. This change is only in effect when reading.
 
 - **Long-press Chapter Skip**: Set whether long-pressing page turn buttons skips to the next/previous chapter:
 
@@ -631,17 +645,17 @@ Once you have opened a book, the button layout changes to facilitate reading.
 
 | Action            | Buttons                              |
 | ----------------- | ------------------------------------ |
-| **Previous Page** | Press **Left** _or_ **Volume Up**    |
-| **Next Page**     | Press **Right** _or_ **Volume Down** |
+| **Previous Page** | Press **Left** _or_ **Side Up**    |
+| **Next Page**     | Press **Right** _or_ **Side Down** |
 
-The role of the volume (side) buttons can be swapped in the **[Controls Settings](#363-controls)**.
+The role of the side buttons can be swapped in the **[Controls Settings](#363-controls)**.
 
 If the **Short Power Button Click** setting is set to "Page Turn", you can also turn to the next page by briefly pressing the Power button.
 
 ### Chapter Navigation
 
-* **Next Chapter:** Press and **hold** the **Right** (or **Volume Down**) button briefly, then release.
-* **Previous Chapter:** Press and **hold** the **Left** (or **Volume Up**) button briefly, then release.
+* **Next Chapter:** Press and **hold** the **Right** (or **Side Down**) button briefly, then release.
+* **Previous Chapter:** Press and **hold** the **Left** (or **Side Up**) button briefly, then release.
 
 This feature can be disabled in the **[Controls Settings](#363-controls)** to help avoid changing chapters by mistake.
 
@@ -659,6 +673,12 @@ When reading an EPUB that contains footnotes, you can navigate to the footnote t
 
 If the device goes to sleep or you close the book while viewing a footnote, the book reopens to your original reading position, not the footnote.
 
+### Dictionary Lookup
+
+Words on the current page can be looked up in an offline StarDict dictionary stored on the SD card. Copy a dictionary to the `/dictionaries/` folder, select it in **Settings → Reader → Dictionary**, then start a lookup by choosing **Look Up** in the **[Reader Menu](#5-reader-menu)** (or by holding **Confirm**, if the **Long-press Menu** setting in **[Controls Settings](#363-controls)** is set to "Dictionary"). Use **Left/Right** to highlight a word and press **Confirm** to show its definition.
+
+See [docs/dictionary.md](docs/dictionary.md) for supported formats, setup, and where to find dictionaries.
+
 ### System Navigation
 
 * **Return to Home:** Press the **Back** button to close the book and return to the **[Home](#31-home-screen)** screen.
@@ -702,7 +722,7 @@ Press **Back** at any time to close the menu and return to your current page.
 
 Accessible by selecting **Chapters** from the Reader Menu.
 
-1. Use **Left** (or **Volume Up**), or **Right** (or **Volume Down**) to highlight the desired chapter.
+1. Use **Left** (or **Side Up**), or **Right** (or **Side Down**) to highlight the desired chapter.
 2. Press **Confirm** to jump to that chapter.
 3. *Alternatively, press **Back** to cancel and return to your current page.*
 
@@ -724,8 +744,6 @@ Please note that this firmware is currently in active development. The following
 
 * **Cover Images:** Large cover images embedded into EPUB require several seconds (~10s for ~2000 pixel tall image) to convert for sleep screen and home screen thumbnail. Consider optimizing the EPUB with e.g. https://github.com/bigbag/epub-to-xtc-converter to speed this up.
 * **Unsupported Image Formats:** Most JPG and PNG images in EPUBs render correctly. GIFs and progressive JPEGs are not supported and will fall back to an `[Image]` placeholder.
-* 
-* **Dictionary Lookup:** Inline word lookup is not yet implemented.
 
 ---
 

diff --git a/docs/bezel-insets.md b/docs/bezel-insets.md
@@ -85,12 +85,44 @@ edge), the readers, and every screen laid out from
 What made the flip safe for the screens that DO honor it, in the order the
 traps were found:
 
-1. **The ~23 absolute-margin `setContentMargin` sites** (reader menus,
-   settings lists, wifi, sliders) build margins in the full screen frame
-   from `getScreenSafeArea()`. They now call `setContentMarginAbsolute()`,
-   which insets from `screen()` rather than `safeRect()` -- same geometry as
-   before the flip, insets applied exactly once. Never hand absolute margins
-   to plain `setContentMargin()`; that applies the safe area twice.
+1. **The ~23 absolute-margin sites** (reader menus, settings lists, wifi,
+   sliders) build margins in the full screen frame from `getScreenSafeArea()`.
+   Since the 2026-09-04 upstream sync they call upstream's
+   `setContentMarginFromScreen()`. Never hand absolute margins to plain
+   `setContentMargin()`; that applies the safe area twice.
+
+   `setContentMarginFromScreen()` does NOT apply it twice, which is why the
+   fork could adopt it and delete its own `setContentMarginAbsolute()` from
+   every screen upstream also has. The arithmetic, from `FreeInkApp.h`:
+
+   ```
+   marginBeyondSafeArea(m, s) = m > s ? m - s : 0
+   setContentMarginFromScreen(m) -> screen inset by s + max(0, m - s) = max(m, s)
+   setContentMarginAbsolute(m)   -> screen inset by m
+   ```
+
+   `max(m, s)` is idempotent: a margin that already folds the safe area in
+   (every one of these sites does, they derive from `getScreenSafeArea()`)
+   comes back unchanged. The two calls differ only where a margin is BELOW
+   the safe area on some side.
+
+   **That one difference is why `setContentMarginAbsolute()` still exists**,
+   with exactly two callers left, both in `src/apps_local/`:
+
+   - `toybox::absoluteChrome()` passes `Insets{}` -- all zeros, deliberately
+     the full frame. `FromScreen({})` would give `max(0, safe)` = the safe
+     rect, pushing every game's chrome down by the top inset. That is the
+     regression described above, found on the device twice.
+   - `XkcdScreens.cpp` passes a band that may sit on the true panel edge.
+     On the X4 Pro `safe.bottom` is 0 so the two agree, but on a board using
+     the inherited `{9, 3, 3, 3}` default `max(m, s)` would clamp a
+     deliberate full-bleed bottom by 3px.
+
+   Upstream has no way to express "content rect = the full frame": `Screen`
+   seeds `content_` from `safeRect()`, and both upstream calls inset from
+   `safeRect()`. So this is a capability the fork needs, not a style
+   preference -- but it is now confined to fork-only screens, and no screen
+   shared with upstream diverges.
 2. **The divider rule** under header bands is `toybox::headerRule(screen)`
    (ToyboxScreen.h), derived from `screen.body().y` right after
    `screen.header(...)`. The old idiom (a fill at absolute

diff --git a/docs/contributing/touch-and-ui.md b/docs/contributing/touch-and-ui.md
@@ -92,7 +92,7 @@ All under `freeink-sdk/libs/ui/FreeInkUI/include/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` |
+| Keyboard | `keyboard` (Latin, Cyrillic and Hebrew 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` |

diff --git a/docs/file-formats.md b/docs/file-formats.md
@@ -90,18 +90,51 @@ if (parsedSize != fileSize) {
 
 ## `section.bin`
 
-### Version 37
+### Version 45
+
+Version 45 keeps the version 44 serialized layout unchanged. It was bumped
+because internal EPUB links now preserve CSS superscript and subscript styles,
+changing their cached word-style flags and page layout.
+
+### Version 44
 
 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 44 appends the internal-link rectangles produced during text layout to
+each serialized page. The reader uses these rectangles for touch navigation;
+older caches are rebuilt because they contain no link geometry.
+
+Version 43 keeps the version 42 serialized layout unchanged. It was bumped
+because paragraph base direction now excludes direction changes from inline
+elements.
+
+Version 42 keeps the version 41 serialized layout unchanged. It was bumped
+because closing a block now strips inherited vertical margins and padding.
+
+Version 41 keeps the version 40 serialized layout unchanged. It was bumped
+because simple HTML table rows are now laid out as positioned columns rather
+than flattened paragraphs with synthetic row/cell labels.
+
+Version 40 keeps the version 39 serialized layout unchanged. It was bumped
+because ruby groups now remain intact when large text blocks are soft-flushed.
+
+Version 39 keeps the version 38 serialized layout unchanged. It was bumped
+because image top margins are now clamped to keep full-height images within the
+page viewport.
+
+Version 38 keeps the version 37 serialized layout unchanged. It was bumped
+because Focus Reading now permits line breaks at visible hyphens and dashes
+and hyphenates focus-split words as a whole, changing cached page layout.
+
 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 36 keeps the version 35 serialized layout unchanged. It was bumped
+because ruby and justified text positioning and CJK line breaking now use
+corrected word measurements, so version 35 cached page layouts no longer match.
 
 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.
@@ -142,7 +175,7 @@ import std.mem;
 import std.string;
 import std.core;
 
-#define EXPECTED_VERSION 37
+#define EXPECTED_VERSION 41
 #define MAX_STRING_LENGTH 65535
 #define FOOTNOTE_NUMBER_LEN 32
 #define FOOTNOTE_HREF_LEN 256
@@ -224,6 +257,7 @@ struct TextBlock {
 
 struct ImageBlock {
     String imagePath;
+    String srcPath;
     s16 width;
     s16 height;
 };

diff --git a/docs/i18n.md b/docs/i18n.md
@@ -69,6 +69,7 @@ A file looks like this:
 _language_name: "Español"
 _language_code: "ES"
 _order: "1"
+_bcp47: "es"
 
 STR_CROSSPLAY: "CrossPlay"
 STR_BOOTING: "BOOTING"
@@ -78,7 +79,8 @@ STR_BROWSE_FILES: "Buscar archivos"
 **Metadata keys** (prefixed with `_`):
 - `_language_name` — Native display name shown to the user (e.g. "Français")
 - `_language_code` — C++ enum name (e.g. "FR"). Please use the [ISO Code](https://en.wikipedia.org/wiki/List_of_ISO_639_language_codes) of the language. Must be a valid C++ identifier.
-- `_order` — Controls the position in the Language enum (English is always 0)
+- `_order` — Historical metadata, still validated for uniqueness but no longer used to compute the `Language` enum order (see `_bcp47` below).
+- `_bcp47` — [BCP 47](https://www.rfc-editor.org/rfc/rfc5646) language tag (e.g. `"pt-PT"`, `"ca-valencia"`). Must be unique. Controls the position in the `Language` enum and the visible Settings menu order (English is always first, then the rest sorted alphabetically by this tag). Persisted user language preferences are stored by `_language_code` string, not by the enum ordinal, so changing `_bcp47` (and thus the enum/menu order) does not reset anyone's saved language.
 
 **Rules:**
 - Use UTF-8 encoding
@@ -147,6 +149,7 @@ Create `lib/I18n/translations/italian.yaml`:
 _language_name: "Italiano"
 _language_code: "IT"
 _order: "7"
+_bcp47: "it"
 
 STR_CROSSPLAY: "CrossPlay"
 STR_BOOTING: "AVVIO"

diff --git a/docs/sd-card-fonts.md b/docs/sd-card-fonts.md
@@ -10,7 +10,7 @@ There are three ways to install fonts:
 ### Option 1: Download from device (recommended)
 
 1. Connect your CrossPoint reader to Wi-Fi
-2. Go to **Settings > System > Manage Fonts**
+2. Go to **Settings > Reader > Manage Fonts**
 3. Browse available font families and tap to download
 4. Downloaded fonts appear immediately in **Settings > Reader > Font Family**
 
@@ -149,6 +149,7 @@ To convert your own TrueType/OpenType fonts:
 | `greek` | Greek + Extended Greek |
 | `cyrillic` | Cyrillic + Supplement |
 | `hebrew` | Hebrew + Alphabetic Presentation Forms |
+| `arabic` | Arabic + Supplement + Extended-A + Presentation Forms A/B (RTL, contextual shaping) |
 | `georgian` | Georgian + Georgian Supplement |
 | `armenian` | Armenian |
 | `ethiopic` | Ethiopic + Extended |