feat: focus reading (#1670)

## Summary This PR introduces **Focus Reading**, a generic implementation of artificial fixation points (similar to Bionic Reading) designed to improve reading speed and focus by bolding the initial characters of words. This is achieved by dynamically bolding characters during indexing. <img width="500" alt="Focus Reading on X3" src="https://github.com/user-attachments/assets/94a632a5-82da-47be-957c-538b35bf84d9" /> ### Implementation Details #### Core Text Engine (`ParsedText`) - Modified `ParsedText::addWord` to implement a custom bolding algorithm. It uses a 45% ratio for bolding, with a minimum of 1 character and a maximum of 9. - UTF-8 Safety: Integrated `utf8NextCodepoint` to ensure character counting and string slicing occur at safe byte boundaries, preventing corruption of multi-byte characters (e.g., accented letters or smart quotes). - Intelligent Tokenization: This correctly identifies and separates "word" characters (letters, apostrophes, hyphens) from "non-word" characters (numbers, brackets, smart quotes). - Formatting Preservation: The logic ensures that punctuation is not "stolen" for the bolding count and that existing styles (like italics or underlines) are preserved across the bold/regular split. - Processing at indexing stage reduces CPU load at render-time and ensures layout/fit is unaffected. - Split details are tracked with `wordIsFocusSuffix`. After splitting and layout, suffixes are merged back into their preceding word entries to prevent a doubling of RAM usage. #### Settings and UI - Version Management: Bumped `SECTION_FILE_VERSION` to `21` - Global Settings: Added `focusReadingEnabled` to `CrossPointSettings`. - User Interface: Added a new toggle in the "Reader" section of the settings menu, positioned after the "Embedded Style" option. - Localization: Added the `STR_FOCUS_READING` string #### Plumbing - Plumbed the `focusReadingEnabled` boolean through `EpubReaderActivity`, `Section`, and `ChapterHtmlSlimParser` to ensure the user's setting reaches the `ParsedText` constructor during chapter indexing. ## Additional Context ### Files Changed - `lib/Epub/Epub/ParsedText.h / .cpp`: Core fixation logic and UTF-8 tokenization. - `lib/Epub/Epub/Section.h / .cpp`: Cache header updates and invalidation logic. - `lib/Epub/Epub/parsers/ChapterHtmlSlimParser.h / .cpp`: Plumbing the setting to text blocks. - `src/CrossPointSettings.h`: Data persistence for the new setting. - `src/SettingsList.h`: UI toggle implementation. - `src/activities/reader/EpubReaderActivity.cpp`: Handling settings changes during reading sessions. - `lib/I18n/translations/*.yaml`: UI strings. --- ### 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**_
2026-05-10 20:02:14 +02:00
parent 2ff63884d6
commit 4e5e2fe40a
39 changed files with 389 additions and 42 deletions
@@ -4,18 +4,44 @@
 #include <Logging.h>
 #include <Serialization.h>

+#include <cstring>
+
 void TextBlock::render(const GfxRenderer& renderer, const int fontId, const int x, const int y) const {
-  // Validate iterator bounds before rendering
-  if (words.size() != wordXpos.size() || words.size() != wordStyles.size()) {
-    LOG_ERR("TXB", "Render skipped: size mismatch (words=%u, xpos=%u, styles=%u)\n", (uint32_t)words.size(),
-            (uint32_t)wordXpos.size(), (uint32_t)wordStyles.size());
+  // Focus annotations are optional: empty vectors mean no word in this block has a split.
+  // When present, they must be sized in lockstep with words[].
+  const bool hasFocus = !wordFocusBoundary.empty();
+  if (words.size() != wordXpos.size() || words.size() != wordStyles.size() ||
+      (hasFocus && (words.size() != wordFocusBoundary.size() || words.size() != wordFocusSuffixX.size()))) {
+    LOG_ERR("TXB", "Render skipped: size mismatch (words=%u, xpos=%u, styles=%u, boundary=%u, suffixX=%u)\n",
+            (uint32_t)words.size(), (uint32_t)wordXpos.size(), (uint32_t)wordStyles.size(),
+            (uint32_t)wordFocusBoundary.size(), (uint32_t)wordFocusSuffixX.size());
    return;
  }

  for (size_t i = 0; i < words.size(); i++) {
    const int wordX = wordXpos[i] + x;
    const EpdFontFamily::Style currentStyle = wordStyles[i];
-    renderer.drawText(fontId, wordX, y, words[i].c_str(), true, currentStyle);
+    const uint8_t boundary = hasFocus ? wordFocusBoundary[i] : 0;
+
+    if (boundary > 0) {
+      // Focus split: draw bold prefix, then the regular suffix at a pre-computed x offset.
+      // The bold prefix is bounded to 9 codepoints by the clamp on targetBoldChars in
+      // ParsedText::addWord; 9 UTF-8 codepoints occupy at most 9 * 4 = 36 bytes, +1 for null = 37.
+      // suffixX is computed at cache-creation time to avoid font metric lookups at render time.
+      static constexpr size_t MAX_FOCUS_PREFIX_BYTES = 9 * 4 + 1;
+      char boldBuf[40];
+      static_assert(sizeof(boldBuf) >= MAX_FOCUS_PREFIX_BYTES,
+                    "boldBuf too small for max focus prefix (9 codepoints * 4 UTF-8 bytes + null)");
+      const auto boldStyle = static_cast<EpdFontFamily::Style>(currentStyle | EpdFontFamily::BOLD);
+      const size_t boldLen = std::min<size_t>({static_cast<size_t>(boundary), words[i].size(), sizeof(boldBuf) - 1});
+      memcpy(boldBuf, words[i].c_str(), boldLen);
+      boldBuf[boldLen] = '\0';
+      renderer.drawText(fontId, wordX, y, boldBuf, true, boldStyle);
+      const int suffixX = wordX + wordFocusSuffixX[i];
+      renderer.drawText(fontId, suffixX, y, words[i].c_str() + boldLen, true, currentStyle);
+    } else {
+      renderer.drawText(fontId, wordX, y, words[i].c_str(), true, currentStyle);
+    }

    if ((currentStyle & EpdFontFamily::UNDERLINE) != 0) {
      const std::string& w = words[i];
@@ -42,9 +68,15 @@ void TextBlock::render(const GfxRenderer& renderer, const int fontId, const int
 }

 bool TextBlock::serialize(FsFile& file) const {
-  if (words.size() != wordXpos.size() || words.size() != wordStyles.size()) {
-    LOG_ERR("TXB", "Serialization failed: size mismatch (words=%u, xpos=%u, styles=%u)\n", words.size(),
-            wordXpos.size(), wordStyles.size());
+  // Focus annotations are optional; vectors are either empty (no splits in this block)
+  // or sized in lockstep with words[].
+  const bool hasFocus = !wordFocusBoundary.empty();
+  if (words.size() != wordXpos.size() || words.size() != wordStyles.size() ||
+      (hasFocus && (words.size() != wordFocusBoundary.size() || words.size() != wordFocusSuffixX.size()))) {
+    LOG_ERR("TXB", "Serialization failed: size mismatch (words=%u, xpos=%u, styles=%u, boundary=%u, suffixX=%u)\n",
+            static_cast<uint32_t>(words.size()), static_cast<uint32_t>(wordXpos.size()),
+            static_cast<uint32_t>(wordStyles.size()), static_cast<uint32_t>(wordFocusBoundary.size()),
+            static_cast<uint32_t>(wordFocusSuffixX.size()));
    return false;
  }

@@ -53,6 +85,13 @@ bool TextBlock::serialize(FsFile& file) const {
  for (const auto& w : words) serialization::writeString(file, w);
  for (auto x : wordXpos) serialization::writePod(file, x);
  for (auto s : wordStyles) serialization::writePod(file, s);
+  // Focus block: 1-byte presence flag, followed by per-word vectors only when present.
+  // Saves 3 bytes/word when focus reading is disabled or no word on this line was split.
+  serialization::writePod(file, static_cast<uint8_t>(hasFocus ? 1 : 0));
+  if (hasFocus) {
+    for (auto b : wordFocusBoundary) serialization::writePod(file, b);
+    for (auto sx : wordFocusSuffixX) serialization::writePod(file, sx);
+  }

  // Style (alignment + margins/padding/indent)
  serialization::writePod(file, blockStyle.alignment);
@@ -76,6 +115,8 @@ std::unique_ptr<TextBlock> TextBlock::deserialize(FsFile& file) {
  std::vector<std::string> words;
  std::vector<int16_t> wordXpos;
  std::vector<EpdFontFamily::Style> wordStyles;
+  std::vector<uint8_t> wordFocusBoundary;
+  std::vector<uint16_t> wordFocusSuffixX;
  BlockStyle blockStyle;

  // Word count
@@ -94,6 +135,16 @@ std::unique_ptr<TextBlock> TextBlock::deserialize(FsFile& file) {
  for (auto& w : words) serialization::readString(file, w);
  for (auto& x : wordXpos) serialization::readPod(file, x);
  for (auto& s : wordStyles) serialization::readPod(file, s);
+  // Focus block: presence flag, then vectors only if present. Empty vectors when absent
+  // signal "no splits in this block" to render() (zero per-word RAM cost).
+  uint8_t hasFocus;
+  serialization::readPod(file, hasFocus);
+  if (hasFocus) {
+    wordFocusBoundary.resize(wc);
+    wordFocusSuffixX.resize(wc);
+    for (auto& b : wordFocusBoundary) serialization::readPod(file, b);
+    for (auto& sx : wordFocusSuffixX) serialization::readPod(file, sx);
+  }

  // Style (alignment + margins/padding/indent)
  serialization::readPod(file, blockStyle.alignment);
@@ -109,6 +160,7 @@ std::unique_ptr<TextBlock> TextBlock::deserialize(FsFile& file) {
  serialization::readPod(file, blockStyle.textIndent);
  serialization::readPod(file, blockStyle.textIndentDefined);

-  return std::unique_ptr<TextBlock>(
-      new TextBlock(std::move(words), std::move(wordXpos), std::move(wordStyles), blockStyle));
+  return std::unique_ptr<TextBlock>(new TextBlock(std::move(words), std::move(wordXpos), std::move(wordStyles),
+                                                  std::move(wordFocusBoundary), std::move(wordFocusSuffixX),
+                                                  blockStyle));
 }
@@ -15,14 +15,28 @@ class TextBlock final : public Block {
  std::vector<std::string> words;
  std::vector<int16_t> wordXpos;
  std::vector<EpdFontFamily::Style> wordStyles;
+  // Per-word focus boundary: N > 0 means the first N bytes of words[i] are rendered bold,
+  // the remainder in the base style. 0 means no split (whole word uses wordStyles[i]).
+  // N encodes the bold PREFIX length only — bounded to 9 codepoints (≤36 UTF-8 bytes) by
+  // FOCUS_READING_PERCENT's 1..9 clamp in ParsedText::addWord, so it always fits in uint8_t.
+  // Vector is empty when no focus splits exist anywhere in the block (zero per-word RAM cost
+  // when focus reading is disabled, or on lines that happen to contain no splittable words).
+  std::vector<uint8_t> wordFocusBoundary;
+  // Pre-computed pixel offset from word start to the regular suffix, stored when boundary > 0.
+  // Eliminates getTextAdvanceX from the render path. 0 when boundary == 0.
+  // Empty in lockstep with wordFocusBoundary.
+  std::vector<uint16_t> wordFocusSuffixX;
  BlockStyle blockStyle;

 public:
  explicit TextBlock(std::vector<std::string> words, std::vector<int16_t> word_xpos,
-                     std::vector<EpdFontFamily::Style> word_styles, const BlockStyle& blockStyle = BlockStyle())
+                     std::vector<EpdFontFamily::Style> word_styles, std::vector<uint8_t> focus_boundary,
+                     std::vector<uint16_t> focus_suffix_x, const BlockStyle& blockStyle = BlockStyle())
      : words(std::move(words)),
        wordXpos(std::move(word_xpos)),
        wordStyles(std::move(word_styles)),
+        wordFocusBoundary(std::move(focus_boundary)),
+        wordFocusSuffixX(std::move(focus_suffix_x)),
        blockStyle(blockStyle) {}
  ~TextBlock() override = default;
  void setBlockStyle(const BlockStyle& blockStyle) { this->blockStyle = blockStyle; }