Merge branch 'master' into fix/nested-block-styles

# Conflicts:
#	lib/Epub/Epub/parsers/ChapterHtmlSlimParser.cpp

README.md

@@ -12,7 +12,7 @@ Xteink firmware. It aims to match or improve upon the standard EPUB reading expe
 
 E-paper devices are fantastic for reading, but most commercially available readers are closed systems with limited 
 customisation. The **Xteink X4** is an affordable, e-paper device, however the official firmware remains closed.
-CrossPoint exists partly as a fun side-project and partly to open up the ecosystem and truely unlock the device's
+CrossPoint exists partly as a fun side-project and partly to open up the ecosystem and truly unlock the device's
 potential.
 
 CrossPoint Reader aims to:
@@ -68,6 +68,24 @@ back to the other partition using the "Swap boot partition" button here https://
 To revert back to the official firmware, you can flash the latest official firmware from https://xteink.dve.al/, or swap
 back to the other partition using the "Swap boot partition" button here https://xteink.dve.al/debug.
 
+### Command line (specific firmware version)
+
+1. Install [`esptool`](https://github.com/espressif/esptool) :
+```bash
+pip install esptool
+```
+2. Download the `firmware.bin` file from the release of your choice via the [releases page](https://github.com/crosspoint-reader/crosspoint-reader/releases)
+3. Connect your Xteink X4 to your computer via USB-C.
+4. Note the device location. On Linux, run `dmesg` after connecting. On MacOS, run :
+```bash
+log stream --predicate 'subsystem == "com.apple.iokit"' --info
+```
+5. Flash the firmware :
+```bash
+esptool.py --chip esp32c3 --port /dev/ttyACM0 --baud 921600 write_flash 0x10000 /path/to/firmware.bin
+```
+Change `/dev/ttyACM0` to the device for your system.
+
 ### Manual
 
 See [Development](#development) below.
@@ -161,7 +179,7 @@ If you are new to the codebase, start with the [contributing docs](./docs/contri
 If you're looking for a way to help out, take a look at the [ideas discussion board](https://github.com/crosspoint-reader/crosspoint-reader/discussions/categories/ideas).
 If there's something there you'd like to work on, leave a comment so that we can avoid duplicated effort.
 
-Everyone here is a volunteer, so please be respectful and patient. For more details on our goverance and community 
+Everyone here is a volunteer, so please be respectful and patient. For more details on our governance and community 
 principles, please see [GOVERNANCE.md](GOVERNANCE.md).
 
 ### To submit a contribution:

SCOPE.md

@@ -27,6 +27,12 @@ usability over "swiss-army-knife" functionality.
 * **Language Support:** E.g. Support for multiple languages both in the reader and in the interfaces.
 * **Reference Tools:** E.g. Local dictionary lookup. Providing quick, offline definitions to enhance comprehension 
   without breaking focus.
+* **Clock Display (device dependent):** 
+
+| Device | Scope |
+| -- | -- |
+| X3 | The X3 uses a dedicated DS3231 RTC, which maintains accurate time across sleep cycles and can be treated as a reliable wall clock. |
+| X4 | The X4 relies on the ESP32-C3's internal RTC, which drifts significantly during deep sleep. NTP sync could correct this, with an appropriate user experience around connecting to the internet on wake or on demand. This causes some tension with the **Active Connectivity** section below, so please open a discussion about this UX if it's a feature you would find useful. |
 
 ### Out-of-Scope
 
@@ -43,8 +49,6 @@ usability over "swiss-army-knife" functionality.
 
 *These features align with CrossPoint's goals but are impractical on the current hardware or produce poor UX.*
 
-* **Clock Display:** The ESP32-C3's RTC drifts significantly during deep sleep; making the clock untrustworthy after any sleep cycle. NTP sync could help, but CrossPoint doesn't connect to the internet on every boot.
-
 * **PDF Rendering:** PDFs are fixed-layout documents, so rendering them requires displaying pages as images rather than reflowable text — resulting in constant panning and zooming that makes for a poor reading experience on e-ink.
 
 ## 3. Idea Evaluation

USER_GUIDE.md

@@ -336,7 +336,8 @@ To use custom sleep images, set the sleep screen mode to **Custom** or **Cover +
 > [!TIP]
 > For best results:
 > - Use uncompressed BMP files with 24-bit color depth
-> - Use a resolution of 480x800 pixels to match the device's screen resolution.
+> - 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.
 
 ---
 

bin/clang-format-fix.ps1

@@ -97,6 +97,7 @@ $exclude = @(
     'lib\Epub\Epub\hyphenation\generated'
     'lib\uzlib'
     '.pio'
+    '.venv'
 )
 
 function Test-Excluded($fullPath) {

docs/translators.md

@@ -26,6 +26,7 @@ If you'd like to add your name to this list, please open a PR adding yourself an
 ## Italian
 - [andreaturchet](https://github.com/andreaturchet)
 - [fragolinux](https://github.com/fragolinux)
+- [alan0ford](https://github.com/alan0ford)
 
 ## Russian
 - [madebyKir](https://github.com/madebyKir)

lib/EpdFont/EpdFont.cpp

@@ -15,11 +15,11 @@ void EpdFont::getTextBounds(const char* string, const int startX, const int star
     return;
   }
 
-  int32_t cursorXFP = fp4::fromPixel(startX);  // 12.4 fixed-point accumulator
   int lastBaseX = startX;
-  int lastBaseAdvanceFP = 0;  // 12.4 fixed-point
+  int lastBaseLeft = 0;
+  int lastBaseWidth = 0;
   int lastBaseTop = 0;
-  constexpr int MIN_COMBINING_GAP_PX = 1;
+  int32_t prevAdvanceFP = 0;  // 12.4 fixed-point: prev glyph's advance + next kern for snap
   uint32_t cp;
   uint32_t prevCp = 0;
   while ((cp = utf8NextCodepoint(reinterpret_cast<const uint8_t**>(&string)))) {
@@ -31,24 +31,29 @@ void EpdFont::getTextBounds(const char* string, const int startX, const int star
 
     const EpdGlyph* glyph = getGlyph(cp);
     if (!glyph) {
-      prevCp = 0;
+      // Keep cursor movement stable when a base glyph is missing, but don't attach subsequent
+      // combining marks to stale base metrics.
+      if (!isCombining) {
+        lastBaseX += fp4::toPixel(prevAdvanceFP);  // flush pending advance before resetting
+        prevCp = 0;
+        prevAdvanceFP = 0;
+        lastBaseLeft = 0;
+        lastBaseWidth = 0;
+        lastBaseTop = 0;
+      }
       continue;
     }
 
-    int raiseBy = 0;
-    if (isCombining) {
-      const int currentGap = glyph->top - glyph->height - lastBaseTop;
-      if (currentGap < MIN_COMBINING_GAP_PX) {
-        raiseBy = MIN_COMBINING_GAP_PX - currentGap;
-      }
-    }
+    const int raiseBy = isCombining ? combiningMark::raiseAboveBase(glyph->top, glyph->height, lastBaseTop) : 0;
 
     if (!isCombining && prevCp != 0) {
-      cursorXFP += getKerning(prevCp, cp);  // 4.4 fixed-point kern
+      const auto kernFP = getKerning(prevCp, cp);  // 4.4 fixed-point kern
+      lastBaseX += fp4::toPixel(prevAdvanceFP + kernFP);
     }
 
-    const int cursorXPixels = fp4::toPixel(cursorXFP);  // snap 12.4 fixed-point to nearest pixel
-    const int glyphBaseX = isCombining ? (lastBaseX + fp4::toPixel(lastBaseAdvanceFP / 2)) : cursorXPixels;
+    const int glyphBaseX =
+        isCombining ? combiningMark::centerOver(lastBaseX, lastBaseLeft, lastBaseWidth, glyph->left, glyph->width)
+                    : lastBaseX;
     const int glyphBaseY = startY - raiseBy;
 
     *minX = std::min(*minX, glyphBaseX + glyph->left);
@@ -57,10 +62,10 @@ void EpdFont::getTextBounds(const char* string, const int startX, const int star
     *maxY = std::max(*maxY, glyphBaseY + glyph->top);
 
     if (!isCombining) {
-      lastBaseX = cursorXPixels;
-      lastBaseAdvanceFP = glyph->advanceX;  // 12.4 fixed-point
+      lastBaseLeft = glyph->left;
+      lastBaseWidth = glyph->width;
       lastBaseTop = glyph->top;
-      cursorXFP += glyph->advanceX;  // 12.4 fixed-point advance
+      prevAdvanceFP = glyph->advanceX;  // 12.4 fixed-point
       prevCp = cp;
     }
   }

lib/EpdFont/EpdFontData.h

@@ -7,10 +7,12 @@
 /// Font metrics use "fixed-point 4" (4 fractional bits, i.e. 1/16-pixel
 /// resolution).  Both the 12.4 glyph advances (uint16_t) and the 4.4 kern
 /// values (int8_t) share the same 4 fractional bits, so they can be freely
-/// added into a single int32_t accumulator during text layout.  The
-/// accumulator is snapped to the nearest whole pixel only at render time,
-/// which avoids the per-character rounding errors that plagued integer-only
-/// layout.
+/// added before snapping to whole pixels.
+///
+/// Rendering and measurement use "differential rounding": each glyph step
+/// (previous advance + current kern) is combined in fixed-point and snapped
+/// to a pixel as one unit.  This guarantees identical character pairs always
+/// produce the same pixel spacing, regardless of position on the line.
 ///
 /// The helpers below eliminate the raw bit-shifts that would otherwise be
 /// scattered across every layout / measurement call site.
@@ -28,6 +30,37 @@ constexpr int toPixel(int32_t fp) { return static_cast<int>((fp + HALF) >> FRAC_
 constexpr float toFloat(int32_t fp) { return fp / static_cast<float>(1 << FRAC_BITS); }
 }  // namespace fp4
 
+/// Helpers for positioning Unicode combining marks (U+0300 ff.) over a
+/// preceding base glyph without GPOS anchor tables.
+namespace combiningMark {
+
+constexpr int MIN_GAP_PX = 1;
+
+/// Compute the cursor-X at which to render a combining mark so its bitmap
+/// is visually centered over the base glyph's bitmap.
+constexpr int centerOver(int baseCursorPos, int baseLeft, int baseWidth, int markLeft, int markWidth) {
+  return baseCursorPos + baseLeft + baseWidth / 2 - markWidth / 2 - markLeft;
+}
+
+/// Rotated-90CW variant of centerOver.  In the rotated coordinate system
+/// renderCharImpl uses (cursorY - left) instead of (cursorX + left), so
+/// every left/width term inverts sign.
+constexpr int centerOverRotated90CW(int baseCursorPos, int baseLeft, int baseWidth, int markLeft, int markWidth) {
+  return baseCursorPos - baseLeft - baseWidth / 2 + markWidth / 2 + markLeft;
+}
+
+/// For combining marks that sit entirely above the baseline, compute how many
+/// pixels to raise the mark so there is at least MIN_GAP_PX between its bottom
+/// edge and the top of the base glyph.  Returns 0 for marks that extend to or
+/// below the baseline (e.g. cedilla, dot-below, ogonek).
+constexpr int raiseAboveBase(int markTop, int markHeight, int baseTop) {
+  if (markTop - markHeight <= 0) return 0;
+  const int gap = markTop - markHeight - baseTop;
+  return (gap < MIN_GAP_PX) ? (MIN_GAP_PX - gap) : 0;
+}
+
+}  // namespace combiningMark
+
 /// Fixed-point conventions used by EpdGlyph and EpdFontData:
 ///   advanceX:   12.4 unsigned fixed-point in uint16_t  (use fp4::toPixel)
 ///   kernMatrix:  4.4 signed fixed-point in int8_t      (use fp4::toPixel)