Merge uxjulia/crossink development 3efe61b into development

CHANGELOG.md

@@ -1,4 +1,4 @@
-## [Unreleased]
+## [v1.6.1] - 2026-09-30
 
 ### Added
 
@@ -26,6 +26,7 @@
 - In-reader menu for X3/X4/X4 Classic have been updated to a modified version of the in-reader menu for touch devices
 - Chapter pages and book progress information is displayed in the frontlight drawer when in the reader for X4 Pro
 - Add a Cover Grid Home theme on devices with PSRAM, showing the current book and six library covers.
+- Show small EPUB images within the surrounding text line instead of separating them from the paragraph.
 
 ### Changed
 
@@ -54,6 +55,8 @@
 - The on-screen keyboard now uses wider outlined keys with clearer spacing on touch and button devices.
 - Long status titles shorten faster when they do not fit the screen.
 - Leaving an EPUB or TXT reader releases rebuildable font buffers for other screens.
+- Menu buttons now follow the device layout: Left/Right switch tabs and Up/Down select rows in reader menus and global settings.
+- The KOReader Sync progress choice now shows remote and local progress as clear cards with large percentages, progress bars, and an "Ahead" marker on the further position.
 
 ### Fixed
 
@@ -85,6 +88,7 @@
 - Dragging or scrolling on a list or menu no longer highlights or selects the row under your finger, and a short drag no longer opens it. Rows highlight once your finger rests on them briefly, so long-press still works.
 - Turning from an EPUB image page whose grayscale pass finished to another image page now runs a cleanup refresh, so the previous image no longer ghosts on the X4 Pro. Image pages skipped before their grayscale pass finishes no longer force a flash on the next page.
 - Keyboard rows are shorter on button-only devices so side-button hints no longer cover the keys.
+- EPUB paragraphs now inherit first-line indentation from HTML and body styles while retaining paragraph-level overrides.
 - Saved clipping lists now show a scrollbar when more clippings are available below the visible rows.
 - EPUB Safe Mode no longer pins inherited fonts and page layout as personal book settings.
 - The X4 Pro Home button now steps back through dictionary lookup, chapter selection, and nested settings instead of jumping to Home.
@@ -121,6 +125,14 @@
 - Footnote choices can be selected directly on the reading page, with a list fallback for links without a visible target.
 - Changing global font or page layout settings from the pull-down panel on touch devices now updates the open book when it inherits those settings.
 - KOReader authentication now rejects unexpectedly large server responses to avoid crashes.
+- EPUBs rewritten with alternate XML namespace prefixes now open normally instead of jumping straight to End of Book.
+- Carousel Home screen reuses cached cover artwork after reading and prepares other positions only when viewed, while keeping progress, reading time, and menu choices current.
+- Sleep entry skips unnecessary pauses and repeated session-state writes. PSRAM devices show independent sleep screens before saving reader progress, and Direct grayscale images skip an unused decode.
+- Renaming books in the web portal preserves reading progress, stats, bookmarks, clippings, reader settings, and cached content.
+- Side-button Orientation Aware, optional keyboard layouts, and the XTC reader's touchscreen and reading stats settings now show toggle switches instead of Yes/No or On/Off labels.
+- In-book setting choices now open with the current value highlighted and visible, including fonts and font sizes.
+- Changing the Home theme or UI scale through the frontlight drawer no longer leaves overlapping covers or stale controls.
+- Fix filename-based KOReader sync failing at split-chapter boundaries in optimized EPUBs that already contain sync mapping data.
 
 ### Security
 

docs/controls.md

@@ -28,9 +28,10 @@ Note: Even though some actions assigned to the front buttons could be used globa
 
 ### Side Buttons
 
-- Layout
 - Orientation aware
-- Long-press action
+- Side-button chord (where supported)
+- Left/Up short-press and long-press actions
+- Right/Down short-press and long-press actions
 
 ### Taps & Gestures
 
@@ -40,13 +41,16 @@ Note: Even though some actions assigned to the front buttons could be used globa
 - Two-finger Screen Rotation (on supported multi-touch devices)
 - Tap to Hide Status Bar
 - Two-finger Swipe (on supported multi-touch devices)
+- Edge Gestures
 
 ### Next Page and Previous Page Gestures
 
 On touchscreen devices, **Next Page** and **Previous Page** are in
 **Settings > Controls > Taps & Gestures**. They change page-turn gestures while
-reading and can be configured independently. **Next Page** controls taps and
-left swipes; **Previous Page** controls taps and right swipes.
+reading and can be configured independently. In left-to-right books, **Next
+Page** controls taps and left swipes; **Previous Page** controls taps and right
+swipes. Right-to-left EPUBs reverse the normal tap zones and horizontal swipe
+directions to follow reading order.
 
 Both settings offer the same options:
 
@@ -73,7 +77,7 @@ On touchscreen devices with multi-touch support, enable **Pinch to Resize Font**
 in **Settings > Controls > Taps & Gestures**. While reading an EPUB or TXT
 book, move two fingers apart to increase the font or together to decrease it.
 Each completed pinch changes one available font-size step. Pinch resizing also
-requires **Touch Reader Controls** to be enabled. XTC pages are pre-rendered,
+requires reader touch input to be enabled. XTC pages are pre-rendered,
 so this option cannot resize them.
 
 ## Two-finger Screen Rotation
@@ -91,9 +95,9 @@ read; the four-way **Reading Orientation** setting still works.
 **Tap to Hide Status Bar** is enabled by default. When it is enabled, tap the
 visible status-bar area while reading to show or hide the entire bar for the
 current reading session. The toggle does not change page layout or page breaks;
-tap the same status-bar region again to restore a hidden bar. Use **Customize
-Status Bar** to choose which items the bar contains. The tap is available while
-**Touch Reader Controls** is enabled. For XTC books, when an XTC status bar is
+tap the same status-bar region again to restore a hidden bar. Use **Status
+Bars** to choose which items the top and bottom bars contain. The tap is available while reader touch input
+is enabled. For XTC books, when an XTC status bar is
 enabled, tap its configured top or bottom edge both to hide and to restore it.
 
 ## Two-finger Swipe Actions
@@ -116,37 +120,64 @@ Available actions depend on the device and reader:
 | Next Chapter / Previous Chapter | EPUB readers |
 | Increase Font Size / Decrease Font Size | EPUB and TXT readers |
 
-Use a clear, mostly straight motion so both contacts are recognized as one
-gesture. Configured two-finger swipes are handled separately from the ordinary
-one-finger page-turn mapping. On image-based XTC books, chapter and font-size
+Brightness and warmth respond while you drag, with longer swipes allowing
+finer one-point adjustments. Use a clear, mostly straight motion so both
+contacts are recognized as one gesture. Configured two-finger swipes are
+handled separately from the ordinary one-finger page-turn mapping. On image-based XTC books, chapter and font-size
 actions are consumed but cannot change the pre-rendered pages.
 
-## Side Button Long-press Action
+## Edge Gestures
+
+On touchscreen devices, open **Settings > Controls > Taps & Gestures > Edge
+Gestures**. Assign actions separately to **Left Edge Up**, **Left Edge Down**,
+**Right Edge Up**, and **Right Edge Down**. Start with one finger close to the
+chosen screen edge and slide vertically while staying along that edge. All four
+start as **Not Set**.
+
+The available actions match [Two-finger Swipe Actions](#two-finger-swipe-actions):
+brightness and warmth on supported hardware, chapter changes in EPUBs, and
+font-size changes in EPUB/TXT books. Edge slides do not require multi-touch.
+Brightness and warmth respond while you drag; a longer slide gives finer
+one-point adjustments. Chapter and font-size actions run when you lift your
+finger. XTC pages cannot be resized or use the EPUB chapter actions.
+
+## Side Button Actions
 
-When set to `Change Font Size`, hold a side button for about 2 seconds:
+Open **Settings > Controls > Side Buttons** to assign a **Short-press Action**
+and **Long-press Action** independently to **Left/Up** and **Right/Down**.
+These actions apply while reading. A short action runs on release; a configured
+long action runs after a hold of about **0.7 seconds**, without also running
+the short action. Existing side-button layouts are converted to matching
+individual actions when you update.
 
-- Up increases font size
-- Down decreases font size
+Alongside the usual reader shortcuts, you can choose:
 
-When set to `Orientation Change`, hold a side button for about 2 seconds:
+- **Previous Page** or **Next Page** to swap page-turn directions or make both
+  buttons advance.
+- **Previous Chapter** or **Next Chapter** for EPUB chapter navigation.
+- **Increase Font Size** or **Decrease Font Size** for EPUB/TXT text.
+- **Rotate Page CCW**, **Rotate Page CW**, or **Rotate Page 180°** for EPUB/TXT
+  orientation changes. The labels describe the direction the page turns.
+- **Ignore** to leave a press unassigned.
 
-- Up cycles through the orientations in the following order: `Landscape CCW` -> `Inverted` -> `Landscape CW` -> `Portrait`
-- Down cycles through the orientations in the following order: `Landscape CW` -> `Inverted` -> `Landscape CCW` -> `Portrait`
+XTC books have pre-rendered pages, so font-size and page-rotation actions do not
+apply. **Orientation aware** remains a separate option for side-button mapping.
 
 ## Power, Back, and Menu Button Actions
 
 Defaults:
 
 - Short-press Power Button Action: Ignore
-- Long-press Power Button Action: Sleep
+- Long-press Power Button Action: Sleep/Wake
 - Long-press Back Button Action: Browse Files
 - Long Press Menu Button Action: Ignore
 
 Available actions include:
 
 - Ignore
-- Sleep
-- Page Turn
+- Sleep (also available to chord and Home-button shortcuts)
+- Sleep/Wake or Wake (Power button only)
+- Next Page
 - Refresh Screen
 - Change Font
 - Guide Dots
@@ -165,17 +196,28 @@ Available actions include:
 - Footnotes
 - Dark Mode
 - Browse Files
+- Library
 - Create Clipping
 - Look Up Word
 - Quick Lock
 - Quick Actions
 - Toggle Frontlight (on supported devices)
 - Toggle Touchscreen (on supported devices)
 
+Power short- and long-press actions are separate. A short press wakes the
+device only when its **Short-press Action** is **Sleep/Wake** or **Wake**.
+**Sleep** only puts an awake device to sleep; **Wake** does nothing while it is
+awake. Holding Power always wakes the sleeping device. For the full startup
+instructions, see [Power On / Off](./user-guide.md#power-on--off).
+
+Assign **Library** to a Power, Back/Menu long-press, chord, Home-button, or
+Quick Actions shortcut to open the book list directly, where that shortcut is
+supported.
+
 ## Power + Up Shortcut
 
 The **Power + Up** shortcut runs the action selected in **Settings > Controls >
-Power + Up**. It is disabled by default. Press the **Power** and **Volume Up**
+Power Button > Power + Up**. It is disabled by default. Press the **Power** and **Volume Up**
 buttons together to trigger it, then release both buttons before using another
 shortcut.
 
@@ -210,6 +252,12 @@ pause while Quick Lock is active.
 
 ## Footnote Shortcut
 
-When a shortcut is mapped to Footnotes, the shortcut opens the footnotes submenu while reading. If the current page has only one footnote, CrossInk opens that referenced page directly.
+When a shortcut is mapped to **Footnotes**, it opens the page-reference selector
+(or a list fallback) while reading. If the current page has only one footnote,
+CrossInk opens that referenced page directly.
 
-The **Quick-return from Footnotes** setting controls whether the Power button acts like Back after opening a footnote page, making it faster to return to the original reading position.
+The **Quick-return from Footnotes** setting controls whether the Power button
+acts like Back after opening a footnote page. It appears under **Settings >
+Controls > Power Button** only after assigning **Footnotes** to Power short/long
+press or Back/Menu long press. See [Footnote Navigation](./user-guide.md#footnote-navigation)
+for selecting references on the page.

docs/data-cache.md

@@ -29,7 +29,7 @@ The main data directory is `.crosspoint` on the SD card. It stores render caches
 ├── koreader.json           # KOReader sync credentials
 ├── bookmarks/              # Bookmark files, one per book
 ├── clippings/              # EPUB clipping/highlight files, one per book
-├── home_carousel_cache.bin # Lyra Carousel home-screen snapshot cache
+├── home_carousel_cache_<index>.bin # Lyra Carousel artwork cache for each book position
 ├── sleep_frame.bin         # Temporary sleep overlay framebuffer, when used
 ├── epub_12471232/          # Each EPUB is cached to epub_<hash>
 │   ├── progress.bin        # Reading position slot A (chapter, page, etc.)
@@ -66,7 +66,7 @@ To clear EPUB/XTC render caches from the device UI without deleting settings or
 
 Cache folders are path-based. Moving a book file can create a new cache directory, so the moved copy may start with fresh reading progress unless the firmware migrates the cache for that move. CrossInk migrates cache and bookmark data for the built-in move-to-Read flow and related file-browser move actions.
 
-EPUB reader font, page layout, styling, and reading-aid settings normally come from the global Reader settings. Changes made inside an EPUB override only the fields whose values differ from the global defaults; the other fields continue to inherit later global changes. EPUB render mode is stored separately per book so a problematic title can be switched to Balanced or Light rendering from the File Browser or Recent Books long-press menus before opening it. Older full-snapshot book overrides retain their original behavior until reset or edited again.
+EPUB reader font, page layout, styling, and reading-aid settings normally come from the global Reader settings. Changes made inside an EPUB override only the fields whose values differ from the global defaults; the other fields continue to inherit later global changes. EPUB render mode is stored separately per book so a problematic title can be switched to Balanced or Light rendering from the File Browser or Library long-press menus before opening it. Older full-snapshot book overrides retain their original behavior until reset or edited again.
 
 EPUB clippings and highlights live outside the EPUB render-cache folder in
 `/.crosspoint/clippings/`. Each book gets a binary clipping file named from the
@@ -91,13 +91,15 @@ For binary file layout details, see [File Formats](./file-formats.md).
 
 Library replaces the Recent Books screen.
 
-The Library reconciles its index with the SD card on the first visit after boot,
+The Library reconciles its index with the SD card on the first visit after a cold boot,
 after file changes in File Browser, and after leaving a download or file-transfer
-screen. Ordinary return visits reuse the index. Failed or memory-limited scans are
-retried on the next visit. The Library's refresh action always scans again; use it
-if files were changed externally while the firmware stayed running.
+screen. Ordinary return visits and deep-sleep wakes reuse a successfully scanned
+index. Failed or memory-limited scans are retried on the next visit. The Library's
+refresh action always scans again; use it
+if files were changed externally while the firmware stayed running or the reader
+was asleep.
 Unchanged books reuse their cached metadata.
-**Settings > Display > Use Book Metadata** selects embedded EPUB titles and
+**Library > Settings > Use Book Metadata** selects embedded EPUB titles and
 authors; disabling it uses filenames. TXT, Markdown and XTC files use filename
 fallbacks. CLX1 version 2 adds a first-name author permutation; older Library
 indexes rebuild automatically when Library opens.

docs/dictionary.md

@@ -32,7 +32,7 @@ Example folder structure: `SDCARD/.dictionaries/Cambridge/*.dict`. Make sure the
    - `/dictionaries/`
 2. If no dictionary has been selected before, the first dictionary in the alphabetical device list is selected automatically.
 3. To choose between multiple dictionaries, open **Settings -> Reader -> Dictionary** on the device and select one from the list.
-4. Per book dictionaries can be set from within the in-reader menu `Book Options -> Settings Gear tab -> Book Dictionary`
+4. Per book dictionaries can be set from within the in-reader menu **Reader Menu > Settings (gear) > Book Dictionary**
 
 ### Preparing Compressed or Large Dictionaries
 
@@ -175,7 +175,8 @@ The history screen shows the 50 most recent entries. The on-disk history is appe
 
 ## IPA Phonetic Characters
 
-Dictionary definitions use the active reader font and size by default. If at least one dictionary is installed, you can set the default dictionary font and size in **Settings > Reader > Font Options**. Books inherit those defaults unless you choose a different font or size in **Book Options > Font Options**. Choose **Use Global** in Book Options to return a book to the global defaults. When the reader uses an SD-card font, you can choose a different dictionary size while keeping that same family; built-in reader fonts continue to use their active size. A saved size with no matching file uses the closest available size from the dictionary family.
+Dictionary definitions use the active reader font and size by default. If at least one dictionary is installed, you can set the default dictionary font and size in **Settings > Reader > Font Options**. Books inherit those defaults unless you choose a different font or size in **Reader Menu > Font > Dictionary Font**. Choose **Use Global** there to return a book to the global dictionary font
+and size defaults. When the reader uses an SD-card font, you can choose a different dictionary size while keeping that same family; built-in reader fonts continue to use their active size. A saved size with no matching file uses the closest available size from the dictionary family.
 
 Only one SD-card font family is loaded at a time: CrossInk temporarily swaps to the dictionary font while a definition is open, then restores the reader font when you close it. If a book's selected dictionary font is missing, the definition temporarily uses the global dictionary font. If that is also unavailable, it falls back to the reader font. The per-book selection is kept so it resumes automatically if you reinstall the family.
 

docs/epub-indexing.md

@@ -90,7 +90,7 @@ To change the default for future EPUBs, open **Settings → Reader → Indexing
 Method** and choose **Incremental**, **Full Section**, or **IncreMENTAL**.
 
 To change it only for the EPUB you are reading, open the reader menu, choose
-**Reader Options**, then choose **Indexing Method**. The per-book choice is
+the **Settings** tab, then choose **Indexing Method**. The per-book choice is
 saved with that book and overrides the global default without changing your
 other books.
 

docs/epub-render-modes.md

@@ -131,7 +131,7 @@ Mode** or **Light Mode** over the current page. The message disappears
 automatically and does not change page layout, margins, or reading position.
 
 If Safe Mode also cannot open the book, long-press the book in **File Browser**
-or **Recent Books** and choose **Reset Book Reader Settings**. This clears only
+or **Library** and choose **Reset Book Reader Settings**. This clears only
 that book's reader settings, including a saved Safe Mode or render-mode
 override. It preserves reading progress, bookmarks, clippings, and reading
 stats.
@@ -143,13 +143,13 @@ CrossInk already falls back automatically, but it is useful when you know a book
 is difficult and want it to start in a specific mode:
 
 - Long-press an EPUB in **File Browser**
-- Long-press an EPUB in **Recent Books**
+- Long-press an EPUB in **Library**
 - Choose **EPUB Render Mode**
 
 You can also change it while reading:
 
 1. Open the reader menu.
-2. Choose **Book Options**.
+2. Choose the **Settings** tab.
 3. Choose **EPUB Render Mode**.
 
 Changing render mode rebuilds the affected book layout cache. Your reading