chore(release): 1.2.0 Release Candidate (#1483)

## Summary

It's been a little while since the last release, but the community has
been incredibly busy. With 155 changes from 48 contributors (30 of which
were new!), there was a lot to cover. Here are some of the highlights:

**🔤 Kerning, Ligatures, and Font Improvements**
Text rendering gets a significant upgrade with proper kerning and
ligature support, fixed-point fractional x-advance for more accurate
character placement, and font compression improvements that reduce flash
usage.

**📝 Footnotes**
Footnote anchor navigation lets you select a footnote reference and jump
to the footnote text, then jump back. Slim footnotes support is also
available for books that use inline footnotes.

**📖 EPUB Optimizer**
A new integrated EPUB optimizer can clean up and reprocess books for
better compatibility with the reader, directly from the device.

**🔋 Battery Charging Indicator**
You can now see when your device is actively charging, with a visual
indicator on the battery icon.

**💾 Crash Diagnostics**
When something goes wrong, the firmware now dumps a crash report to the
SD card — even without USB plugged in. This makes it much easier to
report and diagnose issues.

**🌐 New Languages**
The community continues to expand language support. New in this release:
Turkish, Danish, Finnish, Polish, Dutch, Belarusian, Italian, Ukrainian,
Romanian, Catalan, Vietnamese, and Kazakh — along with significant
improvements to existing translations.

**📂 File Management**
Multi-select file deletion, BMP image viewer in the file browser, hidden
directory browsing, and long-click file deletion from the file browser.

**⚡ Performance**
Under the hood, text layout switched from `std::list` to `std::vector`,
HTML entity lookups are now O(log(n)), font rendering is faster, image
decode is 5-20% faster with per-pixel overhead eliminated, and multiple
string allocation hot paths were eliminated. Pre-indexing of the next
chapter also reduces page-turn latency at chapter boundaries.

---

Along with all of the above, there are many other additions including
**WebDAV support**, **auto page turn**, **QR code for current page**,
**split status bar settings**, **screenshot capture**, **JSON-based
settings migration**, **light/dark theme groundwork**, and a long list
of stability fixes and translation improvements.

## What's Changed
### Features
* feat: Support for kerning and ligatures by @znelson in
https://github.com/crosspoint-reader/crosspoint-reader/pull/873
* feat: footnote anchor navigation by @Uri-Tauber in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1245
* feat: slim footnotes support by @Uri-Tauber in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1031
* feat: integrated epub optimizer by @zgredex and @pablohc in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1224
* feat: battery charging indicator (mirroring PR #537) by @jpirnay in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1427
* feat: dump crash report to sdcard by @ngxson in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1145
* feat: Implement silent pre-indexing for the next chapter in
EpubReaderActivity by @LSTAR1900 in
https://github.com/crosspoint-reader/crosspoint-reader/pull/979
* feat: upgrade platform and support webdav by @dexif in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1047
* feat: Auto Page Turn for Epub Reader by @GenesiaW in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1219
* feat: enhance file deletion functionality with multi-select by
@Jessica765 in
https://github.com/crosspoint-reader/crosspoint-reader/pull/682
* feat: Long Click for File Deletion through File Browser by @Levrk in
https://github.com/crosspoint-reader/crosspoint-reader/pull/909
* feat: Take screenshots by @el in
https://github.com/crosspoint-reader/crosspoint-reader/pull/759
* feat: Current page as QR by @el in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1099
* feat: Download links for web server by @el in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1039
* feat: Added BmpViewer activity for viewing .bmp images in file browser
by @Levrk in
https://github.com/crosspoint-reader/crosspoint-reader/pull/887
* feat: User setting for image display by @jpirnay in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1291
* feat: Show hidden directories in browser by @jpirnay in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1288
* feat: Prefer ".sleep" over "sleep" for custom image directory by
@jpirnay in
https://github.com/crosspoint-reader/crosspoint-reader/pull/948
* feat: Allow a local configuration file for custom compiles by @jpirnay
in https://github.com/crosspoint-reader/crosspoint-reader/pull/879
* feat: Migrate binary settings to json by @jpirnay in
https://github.com/crosspoint-reader/crosspoint-reader/pull/920
* feat: split status bar setting by @whyte-j in
https://github.com/crosspoint-reader/crosspoint-reader/pull/733
* feat: wrapped text in GfxRender, implemented in themes so far by
@iandchasse in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1141
* feat: Themed language screen by @CaptainFrito in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1020
* feat: set WiFi hostname to CrossPoint-Reader-XXXXXXXXXXXX by @dexif in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1107
* feat: Add maxAlloc to memory information by @jpirnay in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1152
* feat: replace picojpeg with JPEGDEC for JPEG image decoding by
@martinbrook in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1136
* feat: Add git branch to version information on settings screen by
@jpirnay in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1225
* feat: sort languages in selection menu by @ariel-lindemann in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1071
* feat: Latin Extended-B European glyphs by @znelson in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1157
* feat: Latin Extended-B European glyphs by @znelson in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1167
* feat: Vietnamese glyphs support by @danoooob in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1147
* feat: add Turkish translation by @barbarhan in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1192
* feat: add full Danish translation by @hajisan in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1146
* feat: Add Finnish translations by @plahteenlahti in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1133
* feat: Add Polish Language by @th0m4sek in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1155
* feat: add Dutch translation by @basvdploeg in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1204
* feat: add Belarusian translation by @dexif in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1120
* feat: Add full Italian translations by @andreaturchet in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1144
* feat: add Ukrainian translation by @mirus-ua in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1065
* feat: Add Kazakh (kk) language support by @fsocietyipa in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1377
* feat: added Romanian strings by @ariel-lindemann in
https://github.com/crosspoint-reader/crosspoint-reader/pull/987
* feat: add Catalan strings by @angeldenom in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1049
* feat: Make directories stand out more in local file browser: "[dir]"
instead of "dir" by @jpirnay in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1339
* feat: Add Polish strings for commits #1219,#1169,#1031 +tweaks by
@th0m4sek in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1227
* feat: Polish translation tweaks by @th0m4sek in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1193
### Fixes
* fix: Fix img layout issue / support CSS display:none for elements and
images by @jpirnay in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1443
* fix: Overlapping battery percentage on image pages with anti-aliasing
by @znelson in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1452
* fix: Fix prewarm perf when a page contains many styles by
@adriancaruana in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1451
* fix: use sleep routine from the original firmware by @ngxson in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1298
* fix: Prevent line breaks on common English contractions by @znelson in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1405
* fix: Build with -fno-exceptions by @znelson in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1412
* fix: Reduce flash usage by cleaning up I18n translations by @steka in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1401
* fix: jpeg resource cleanup by @jpirnay in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1320
* fix: back button in settings returns to tab bar first by @Cache8063 in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1354
* fix: Init lastSleepImage (edge case) by @jpirnay in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1360
* fix: Add special handling for apostrophe hyphenation by @jpirnay in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1318
* fix: Fix inter-word spacing rounding error in text layout by @znelson
in https://github.com/crosspoint-reader/crosspoint-reader/pull/1311
* fix: load access fault crash by @Uri-Tauber in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1370
* fix: Fix bootloop logging crash by @jpirnay in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1357
* fix: dump crash log without usb plugged, bump release log to INFO by
@ngxson in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1332
* fix: avoid zip filename overflow by @jpirnay in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1321
* fix: Hanging indent (negative text-indent) and em-unit sizing by
@jpirnay in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1229
* fix: Use fixed-point fractional x-advance and kerning for better text
layout by @znelson in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1168
* fix: use HTTPClient::writeToStream for downloading files from OPDS by
@osteotek in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1207
* fix: make file system operations thread-safe (HalFile) by @ngxson in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1212
* fix: properly implement requestUpdateAndWait() by @ngxson in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1218
* fix: prevent infinite render loop in Calibre Wireless after file
transfer by @pablohc in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1070
* fix: WiFi lifecycle and hyphenation heap defragmentation for KOReader
sync by @jpirnay in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1151
* fix: Fix coverRendered flag by @jpirnay in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1154
* fix: Handle non-ASCII characters in sanitizeFilename by @znelson in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1132
* fix: Update activity was missing "Back" button label by @znelson in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1128
* fix: force auto-hinting for Bookerly to fix inconsistent stem widths
by @adriancaruana in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1098
* fix: image centering bleed by @martinbrook in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1096
* fix: double free WebDAVHandler by @ngxson in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1093
* fix: Consider extra quotation styles when hyphenating quoted words by
@cbix in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1077
* fix: acquire power lock before sleeping by @ngxson in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1125
* fix: Unify inconsistent Wi-Fi/WiFi in Czech translation by @pepastach
in https://github.com/crosspoint-reader/crosspoint-reader/pull/1138
* fix: sdfat warning about redefinition of macro by @ngxson in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1135
* fix: Close leaked file descriptors in SleepActivity and web server by
@brbla in
https://github.com/crosspoint-reader/crosspoint-reader/pull/869
* fix: Enable DESTRUCTOR_CLOSES_FILE flag by @daveallie in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1075
* fix: Change "UI Font Size" to "Reader Font Size" by @divinitycove in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1171
* fix: Hide unusable button hints when viewing empty directory by @Levrk
in https://github.com/crosspoint-reader/crosspoint-reader/pull/1253
* fix: broken translations in status bar settings by @ariel-lindemann in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1188
* fix: clarity issue with ambiguous string `SET` by @ariel-lindemann in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1169
* fix: Crash (Load access fault) when indexing chapters containing
characters unsupported by bold/italic font variants by @Uri-Tauber in
https://github.com/crosspoint-reader/crosspoint-reader/pull/997
* fix: Increase PNGdec buffer size to support wide images by @osteotek
in https://github.com/crosspoint-reader/crosspoint-reader/pull/995
* fix: Use HalPowerManager for battery percentage by @vjapolitzer in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1005
* fix: Fix dangling pointer by @Uri-Tauber in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1010
* fix: re-implementing Cover Outlines for the new Lyra Themes by @Levrk
in https://github.com/crosspoint-reader/crosspoint-reader/pull/1017
* fix: use double FAST_REFRESH to prevent washout on large grey images
by @martinbrook in
https://github.com/crosspoint-reader/crosspoint-reader/pull/957
* fix: Fixed Image Sizing When No Width is Set by @DestinySpeaker in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1002
* fix: Strip unused CSS rules by @daveallie in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1014
* fix: continue reading card classic theme by @pablohc in
https://github.com/crosspoint-reader/crosspoint-reader/pull/990
* fix: Destroy CSS Cache file when invalid by @daveallie in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1018
* fix: Shorten "Forget Wifi" button labels to fit on button by
@lukestein in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1045
* fix: improve Spanish translations by @pablohc in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1054
* fix: Fixed book title in home screen by @DestinySpeaker in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1013
* fix: Fix hyphenation and rendering of decomposed characters by
@jpirnay in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1037
* fix: Improve and add Spanish translations by @DaniPhii in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1338
* fix: improve and add Spanish translations by @DaniPhii in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1254
* fix: improve and add Swedish translations by @steka in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1317
* fix: Extend missing / amend existing German translations by @jpirnay
in https://github.com/crosspoint-reader/crosspoint-reader/pull/1226
* fix: update french.yaml file to have a better French translation of
the CFW by @Spigaw in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1130
* fix: added romanian translation to new strings by @ariel-lindemann in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1105
* fix: add missing romanian strings by @ariel-lindemann in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1187
* fix: add new Ukrainian translation line for STR_SCREENSHOT_BUTTON by
@mirus-ua in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1149
* fix: Dutch translation prefix correction by @basvdploeg in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1223
* fix: Small typo in i18n.md regarding C++ identifiers by
@victordomingos in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1210
* fix: typo in USER_GUIDE.md by @arnaugamez in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1036
* fix: add missing keyboard metrics to Lyra3CoversTheme by @dexif in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1101

### Internal
* perf: font-compression improvements by @adriancaruana in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1056
* perf: Improve font drawing performance by @jpirnay in
https://github.com/crosspoint-reader/crosspoint-reader/pull/978
* perf: Replace std::list with std::vector in text layout by @znelson in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1038
* perf: Optimize HTML entities lookup to O(log(n)) by @Uri-Tauber in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1194
* perf: UITheme::getMetrics const and const-ref usage by @znelson in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1094
* perf: Avoid creating strings for file extension checks by @znelson in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1303
* perf: Eliminate per-pixel overheads in image rendering by @martinbrook
in https://github.com/crosspoint-reader/crosspoint-reader/pull/1293
* perf: Update github actions for optimal performance with pioarduino by
@Jason2866 in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1080
* style: Phase 1 - Simple light dark themes by @cdmoro in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1006
* refactor: implement ActivityManager by @ngxson in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1016
* refactor: Simplify REPLACEMENT_GLYPH fallback by @znelson in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1119
* refactor: Simplify new setting introduction by @jpirnay in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1086
* refactor: Use std binary search algorithms for font lookups by
@znelson in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1202
* refactor: rename MyLibrary to FileBrowser by @osteotek in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1260
* refactor: Avoid rebuilding cache path strings by @znelson in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1300
* refactor: reader utils by @Uri-Tauber in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1329
* chore: Remove miniz and modularise inflation logic by @daveallie in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1073
* chore: Resolve several build warnings by @daveallie in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1076
* chore: Removed generated language headers by @znelson in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1156
* chore: Added generated lang headers to .gitignore by @znelson in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1158
* chore: remove redundant xTaskCreate by @ngxson in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1264
* chore: Removed unused PlatformIO include directory placeholder by
@znelson in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1417
* chore: micro-optimisation: early exit on fillUncompressedSizes by
@jpirnay in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1322
* chore: change label while on settings tab actions by @jpirnay in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1325
* chore: add firmware size history script by @znelson in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1235
* chore: Add powershell script for clang-formatting by @jpirnay in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1472
* chore: Removed unused ConfirmationActivity member by @znelson in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1234
* chore: Update russian.yaml by @madebyKir in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1198
* chore: new Ukrainian translation lines by @mirus-ua in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1199
* chore: new Ukrainian localization strings by @mirus-ua in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1270
* chore: Polish localization for STR_DELETE by @JonaszPotoniec in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1323
* chore: Image settings Polish localization by @znelson in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1299
* chore: add missing Catalan strings by @angeldenom in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1302
* chore: add missing translations for Romanian by @ariel-lindemann in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1265
* chore: Add Portuguese (Portugal) translator to the list by
@victordomingos in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1211
* chore: Reduce flash usage by cleaning up I18n translations by @steka
in https://github.com/crosspoint-reader/crosspoint-reader/pull/1401
* docs: Add lightweight contributor onboarding documentation by @bilalix
in https://github.com/crosspoint-reader/crosspoint-reader/pull/894
* docs: ActivityManager migration guide by @znelson in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1222
* docs: USER_GUIDE.md update for 1.1.0 by @divinitycove in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1108
* docs: add quick KOReader sync setup guide by @wjhrdy in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1181
* docs: image support marked as completed by @ariel-lindemann in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1008
* feat: aiagent context definition by @jpirnay in
https://github.com/crosspoint-reader/crosspoint-reader/pull/922
* chore: Update SKILL.md to reflect generated i18n files are gitignored
by @znelson in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1423
* fix: ActivityManager tweaks by @znelson in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1220
* fix: Correct relative file paths in SKILL.md documentation by @pablohc
in https://github.com/crosspoint-reader/crosspoint-reader/pull/1304
* fix: add Technically Unsupported section to SCOPE.md by @Uri-Tauber in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1295

## New Contributors
* @DestinySpeaker made their first contribution in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1002
* @arnaugamez made their first contribution in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1036
* @angeldenom made their first contribution in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1049
* @cdmoro made their first contribution in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1006
* @bilalix made their first contribution in
https://github.com/crosspoint-reader/crosspoint-reader/pull/894
* @Jessica765 made their first contribution in
https://github.com/crosspoint-reader/crosspoint-reader/pull/682
* @brbla made their first contribution in
https://github.com/crosspoint-reader/crosspoint-reader/pull/869
* @dexif made their first contribution in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1047
* @mirus-ua made their first contribution in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1065
* @cbix made their first contribution in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1077
* @divinitycove made their first contribution in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1108
* @pepastach made their first contribution in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1138
* @Jason2866 made their first contribution in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1080
* @andreaturchet made their first contribution in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1144
* @Spigaw made their first contribution in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1130
* @iandchasse made their first contribution in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1141
* @th0m4sek made their first contribution in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1155
* @plahteenlahti made their first contribution in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1133
* @hajisan made their first contribution in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1146
* @madebyKir made their first contribution in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1198
* @victordomingos made their first contribution in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1210
* @basvdploeg made their first contribution in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1204
* @wjhrdy made their first contribution in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1181
* @DaniPhii made their first contribution in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1254
* @steka made their first contribution in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1317
* @barbarhan made their first contribution in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1192
* @JonaszPotoniec made their first contribution in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1323
* @Cache8063 made their first contribution in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1354
* @fsocietyipa made their first contribution in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1377
* @LSTAR1900 made their first contribution in
https://github.com/crosspoint-reader/crosspoint-reader/pull/979
* @zgredex made their first contribution in
https://github.com/crosspoint-reader/crosspoint-reader/pull/1224

**Full Changelog**:
https://github.com/crosspoint-reader/crosspoint-reader/compare/1.1.1...release/1.2.0

---------

Co-authored-by: jpirnay <jens@pirnay.com>
Co-authored-by: Dani Poveda <daniphii@outlook.com>
Co-authored-by: Baris Albayrak <80099286+barbarhan@users.noreply.github.com>
Co-authored-by: Barış Albayrak <barisa@pop-os.lan>
Co-authored-by: Stefan Blixten Karlsson <sbkarlsson@gmail.com>
Co-authored-by: Àngel <153315454+angeldenom@users.noreply.github.com>
Co-authored-by: Jonasz Potoniec <jonasz@potoniec.eu>
Co-authored-by: Егор Мартынов <martynovegorOF@yandex.ru>
Co-authored-by: Mirus <mirusim@gmail.com>
Co-authored-by: Spigaw <73850535+Spigaw@users.noreply.github.com>
Co-authored-by: ariel-lindemann <41641978+ariel-lindemann@users.noreply.github.com>
Co-authored-by: Nima Salami <54304457+hajisan@users.noreply.github.com>
Co-authored-by: Arthur Tazhitdinov <lisnake@gmail.com>
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-authored-by: Bas van der Ploeg <bas@basvanderploeg.nl>
Co-authored-by: martin brook <martin.brook100@googlemail.com>

.github/skills/crosspoint-reader.md

@@ -0,0 +1 @@
+../../.skills/SKILL.md

.github/workflows/ci.yml

@@ -1,10 +1,61 @@
-name: CI
-'on':
+name: CI (build)
+
+on:
   push:
     branches: [master]
   pull_request:
 
+permissions:
+  contents: read
+
 jobs:
+  clang-format:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          submodules: recursive
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: '3.14'
+
+      - name: Install clang-format-21
+        run: |
+          wget https://apt.llvm.org/llvm.sh
+          chmod +x llvm.sh
+          sudo ./llvm.sh 21
+          sudo apt-get update
+          sudo apt-get install -y clang-format-21
+
+      - name: Run clang-format
+        run: |
+          PATH="/usr/lib/llvm-21/bin:$PATH" ./bin/clang-format-fix
+          git diff --exit-code || (echo "Please run 'bin/clang-format-fix' to fix formatting issues" && exit 1)
+
+  cppcheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          submodules: recursive
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: '3.14'
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          version: "latest"
+          enable-cache: false
+
+      - name: Install PlatformIO Core
+        run: uv pip install --system -U https://github.com/pioarduino/platformio-core/archive/refs/tags/v6.1.19.zip
+
+      - name: Run cppcheck
+        run: pio check --fail-on-defect low --fail-on-defect medium --fail-on-defect high
+
   build:
     runs-on: ubuntu-latest
     steps:
@@ -16,22 +67,55 @@ jobs:
         with:
           python-version: '3.14'
 
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          version: "latest"
+          enable-cache: false
+
       - name: Install PlatformIO Core
-        run: pip install --upgrade platformio
-
-      - name: Install clang-format-21
-        run: |
-          wget https://apt.llvm.org/llvm.sh
-          chmod +x llvm.sh
-          sudo ./llvm.sh 21
-          sudo apt-get update
-          sudo apt-get install -y clang-format-21
-
-      - name: Run cppcheck
-        run: pio check --fail-on-defect low --fail-on-defect medium --fail-on-defect high
-
-      - name: Run clang-format
-        run: PATH="/usr/lib/llvm-21/bin:$PATH" ./bin/clang-format-fix && git diff --exit-code || (echo "Please run 'bin/clang-format-fix' to fix formatting issues" && exit 1)
+        run: uv pip install --system -U https://github.com/pioarduino/platformio-core/archive/refs/tags/v6.1.19.zip
 
       - name: Build CrossPoint
-        run: pio run
+        run: |
+          set -euo pipefail
+          pio run | tee pio.log
+
+      - name: Extract firmware stats
+
+        run: |
+          set -euo pipefail
+          ram_line="$(grep -E "RAM:\\s" -m1 pio.log || true)"
+          flash_line="$(grep -E "Flash:\\s" -m1 pio.log || true)"
+          echo "ram_line=${ram_line}" >> "$GITHUB_OUTPUT"
+          echo "flash_line=${flash_line}" >> "$GITHUB_OUTPUT"
+          {
+            echo "## Firmware build stats"
+            if [ -n "$ram_line" ]; then echo "- ${ram_line}"; else echo "- RAM: not found"; fi
+            if [ -n "$flash_line" ]; then echo "- ${flash_line}"; else echo "- Flash: not found"; fi
+          } >> "$GITHUB_STEP_SUMMARY"
+
+      - name: Upload firmware.bin artifact
+        uses: actions/upload-artifact@v6
+        with:
+          name: firmware.bin
+          path: .pio/build/default/firmware.bin
+          if-no-files-found: error
+
+  # This job is used as the PR required actions check, allows for changes to other steps in the future without breaking
+  # PR requirements.
+  test-status:
+    name: Test Status
+    needs:
+      - build
+      - clang-format
+      - cppcheck
+    if: always()
+    runs-on: ubuntu-latest
+    steps:
+      - name: Fail because needed jobs failed
+        # Fail if any job failed or was cancelled (skipped jobs are ok)
+        if: ${{ contains(needs.*.result, 'failure') || contains(needs.*.result, 'cancelled') }}
+        run: exit 1
+      - name: Success
+        run: exit 0

.github/workflows/pr-formatting-check.yml

@@ -0,0 +1,27 @@
+name: "PR Formatting"
+
+on:
+  pull_request:
+  pull_request_target:
+    types:
+      - opened
+      - reopened
+      - edited
+
+permissions:
+  statuses: write
+
+jobs:
+  title-check:
+    name: Title Check
+    runs-on: ubuntu-latest
+    steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@ec9f2d5744a09debf3a187a3f4f675c53b671911 # v2.13.0
+        with:
+          egress-policy: audit
+
+      - name: Check PR Title
+        uses: amannn/action-semantic-pull-request@v6
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/release.yml

@@ -12,19 +12,18 @@ jobs:
         with:
           submodules: recursive
 
-      - uses: actions/cache@v5
-        with:
-          path: |
-            ~/.cache/pip
-            ~/.platformio/.cache
-          key: ${{ runner.os }}-pio
-
       - uses: actions/setup-python@v6
         with:
           python-version: '3.14'
 
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          version: "latest"
+          enable-cache: false
+
       - name: Install PlatformIO Core
-        run: pip install --upgrade platformio
+        run: uv pip install --system -U https://github.com/pioarduino/platformio-core/archive/refs/tags/v6.1.19.zip
 
       - name: Build CrossPoint
         run: pio run -e gh_release

.github/workflows/release_candidate.yml

@@ -0,0 +1,47 @@
+name: Compile Release Candidate
+
+on:
+  workflow_dispatch:
+
+jobs:
+  build-release-candidate:
+    if: startsWith(github.ref_name, 'release/')
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          submodules: recursive
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: '3.14'
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          version: "latest"
+          enable-cache: false
+
+      - name: Install PlatformIO Core
+        run: uv pip install --system -U https://github.com/pioarduino/platformio-core/archive/refs/tags/v6.1.19.zip
+
+      - name: Extract env
+        run: |
+          echo "SHORT_SHA=${GITHUB_SHA::7}" >> $GITHUB_ENV
+          echo "BRANCH_SUFFIX=${GITHUB_REF_NAME#release/}" >> $GITHUB_ENV
+
+      - name: Build CrossPoint Release Candidate
+        env:
+          CROSSPOINT_RC_HASH: ${{ env.SHORT_SHA }}
+        run: pio run -e gh_release_rc
+
+      - name: Upload Artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: CrossPoint-RC-${{ env.BRANCH_SUFFIX }}
+          path: |
+            .pio/build/gh_release_rc/bootloader.bin
+            .pio/build/gh_release_rc/firmware.bin
+            .pio/build/gh_release_rc/firmware.elf
+            .pio/build/gh_release_rc/firmware.map
+            .pio/build/gh_release_rc/partitions.bin

.gitignore

@@ -3,4 +3,15 @@
 .DS_Store
 .vscode
 lib/EpdFont/fontsrc
+lib/I18n/I18nKeys.h
+lib/I18n/I18nStrings.h
+lib/I18n/I18nStrings.cpp
 *.generated.h
+.vs
+build
+**/__pycache__/
+/compile_commands.json
+/.cache
+.history/
+/.venv
+*.local*

.skills/SKILL.md

@@ -0,0 +1,872 @@
+# CrossPoint Reader Development Guide
+
+Project: Open-source e-reader firmware for Xteink X4 (ESP32-C3)
+Mission: Provide a lightweight, high-performance reading experience focused on EPUB rendering on constrained hardware.
+
+## AI Agent Identity and Cognitive Rules
+* Role: Senior Embedded Systems Engineer (ESP-IDF/Arduino-ESP32 specialized).
+* Primary Constraint: 380KB RAM is the hard ceiling. Stability is non-negotiable.
+* Evidence-Based Reasoning: Before proposing a change, you MUST cite the specific file path and line numbers that justify the modification.
+* Anti-Hallucination: Do not assume the existence of libraries or ESP-IDF functions. If you are unsure of an API's availability for the ESP32-C3 RISC-V target, check the open-x4-sdk or official docs first.
+* No Unfounded Claims: Do not claim performance gains or memory savings without explaining the technical mechanism (e.g., DRAM vs IRAM usage).
+* Resource Justification: You must justify any new heap allocation (new, malloc, std::vector) or explain why a stack/static alternative was rejected.
+* Verification: After suggesting a fix, instruct the user on how to verify it (e.g., monitoring heap via Serial or checking a specific cache file).
+---
+
+## Development Environment Awareness
+
+**CRITICAL**: Detect the host platform at session start to choose appropriate tools and commands.
+
+### Platform Detection
+```bash
+# Detect platform (run once per session)
+uname -s
+# Returns: MINGW64_NT-* (Windows Git Bash), Linux, Darwin (macOS)
+```
+
+**Detection Required**: Run `uname -s` at session start to determine platform
+
+### Platform-Specific Behaviors
+- **Windows (Git Bash)**: Unix commands, `C:\` paths in Windows but `/` in bash, limited glob (use `find`+`xargs`)
+- **Linux/WSL**: Full bash, Unix paths, native glob support
+
+**Cross-Platform Code Formatting**:
+```bash
+find src -name "*.cpp" -o -name "*.h" | xargs clang-format -i
+```
+
+---
+
+## Platform and Hardware Constraints
+
+### Hardware Specs
+* MCU: ESP32-C3 (Single-core RISC-V @ 160MHz)
+* RAM: ~380KB usable (VERY LIMITED - primary project constraint)
+  * **NO PSRAM**: ESP32-C3 has no PSRAM capability (unlike ESP32-S3)
+  * **Single Buffer Mode**: Only ONE 48KB framebuffer (not double-buffered)
+* Flash: 16MB (Instruction storage and static data)
+* Display: 800x480 E-Ink (Slow refresh, monochrome, 1-2s full update)
+  * Framebuffer: 48,000 bytes (800 × 480 ÷ 8)
+* Storage: SD Card (Used for books and aggressive caching)
+
+### The Resource Protocol
+1. Stack Safety: Limit local function variables to < 256 bytes. The ESP32-C3 default stack is small; use std::unique_ptr or static pools for larger buffers.
+2. Heap Fragmentation: Avoid repeated new/delete in loops. Allocate buffers once during onEnter() and reuse them.
+3. Flash Persistence: Large constant data (UI strings, lookup tables) MUST be marked static const to stay in Flash (Instruction Bus), freeing DRAM.
+4. String Policy: Prohibit std::string and Arduino String in hot paths. Use std::string_view for read-only access and snprintf with fixed char[] buffers for construction.
+5. UI Strings: All user-facing text must use the `tr()` macro (e.g., `tr(STR_LOADING)`) for i18n support. Never hardcode UI strings directly. For the avoidance of doubt, logging messages (LOG_DBG/LOG_ERR) can be hardcoded, but user-facing text must use `tr()`.
+6. `constexpr` First: Compile-time constants and lookup tables must be `constexpr`, not just `static const`. This moves computation to compile time, enables dead-branch elimination, and guarantees flash placement. Use `static constexpr` for class-level constants.
+7. `std::vector` Pre-allocation: Always call `.reserve(N)` before any `push_back()` loop. Each growth event allocates a new block (2×), copies all elements, then frees the old one — three heap operations that fragment DRAM. When the final size is unknown, estimate conservatively.
+8. SPIFFS Write Throttling: Never write a settings file on every user interaction. Guard all writes with a value-change check (`if (newVal == _current) return;`). Progress saves during reading must be debounced — write on activity exit or every N page turns, not on every turn. SPIFFS sectors have a finite erase cycle limit.
+
+---
+
+## Project Architecture
+
+### Build System: PlatformIO
+
+**PlatformIO is BOTH a VS Code extension AND a CLI tool**:
+
+1. **VS Code Extension** (Recommended):
+   * Extension ID: `platformio.platformio-ide` (see `.vscode/extensions.json`)
+   * Provides: Toolbar buttons, IntelliSense, integrated build/upload/monitor
+   * Configuration: `.vscode/c_cpp_properties.json`, `.vscode/tasks.json`
+   * Usage: Click Build (✓), Upload (→), or Monitor (🔌) buttons
+
+2. **CLI Tool** (`pio` command):
+   * **Installation**: Python package (typically `pip install platformio`)
+   * **Windows Location**: `C:\Users\<user>\AppData\Local\Programs\Python\Python3xx\Scripts\pio.exe`
+   * **Verify**: `which pio` (Git Bash) or `where.exe pio` (cmd)
+   * **Usage**: `pio run`, `pio run -t upload`, etc.
+
+**Configuration Files**:
+* `platformio.ini`: Main build configuration (committed to git)
+* `platformio.local.ini`: Local overrides (gitignored, create if needed)
+* `partitions.csv`: ESP32 flash partition layout
+
+### Build Environment
+* **Standard**: C++20 (`-std=c++2a`). No Exceptions, No RTTI.
+* **Logging**: ALWAYS use `LOG_INF`, `LOG_DBG`, or `LOG_ERR` from `Logging.h`. Raw Serial output is deprecated.
+* **Environments** (in `platformio.ini`):
+  * `default`: Development (LOG_LEVEL=2, serial enabled)
+  * `gh_release`: Production (LOG_LEVEL=0)
+  * `gh_release_rc`: Release candidate (LOG_LEVEL=1)
+  * `slim`: Minimal build (no serial logging)
+
+### Critical Build Flags
+These flags in `platformio.ini` fundamentally affect firmware behavior:
+
+```cpp
+-DEINK_DISPLAY_SINGLE_BUFFER_MODE=1  // Single framebuffer (saves 48KB RAM!)
+-DARDUINO_USB_MODE=1                 // Enable USB CDC
+-DARDUINO_USB_CDC_ON_BOOT=1          // Serial available immediately at boot
+-DXML_CONTEXT_BYTES=1024             // XML parser memory limit (EPUB parsing)
+-DUSE_UTF8_LONG_NAMES=1              // SD card long filename support
+-DMINIZ_NO_ZLIB_COMPATIBLE_NAMES=1   // Avoid zlib name conflicts
+-DXML_GE=0                           // Disable XML general entities (security)
+```
+
+**SINGLE_BUFFER_MODE implications**:
+- Only ONE framebuffer exists (not double-buffered)
+- Grayscale rendering requires temporary buffer allocation (`renderer.storeBwBuffer()`)
+- Must call `renderer.restoreBwBuffer()` to free temporary buffers
+- See [lib/GfxRenderer/GfxRenderer.cpp:439-440](../lib/GfxRenderer/GfxRenderer.cpp) for malloc usage
+
+### Directory Structure
+* lib/: Internal libraries (Epub engine, GfxRenderer, UITheme, I18n)
+  * lib/hal/: Hardware Abstraction Layer (HalDisplay, HalGPIO, HalStorage)
+  * lib/I18n/: Internationalization (translations in `translations/*.yaml`, generated string tables)
+* src/activities/: UI logic using the Activity Lifecycle (onEnter, loop, onExit)
+* open-x4-sdk/: Low-level SDK (EInkDisplay, InputManager, BatteryMonitor, SDCardManager)
+* .crosspoint/: SD-based binary cache for EPUB metadata and pre-rendered layout sections
+
+### Hardware Abstraction Layer (HAL)
+
+**CRITICAL**: Always use HAL classes, NOT SDK classes directly.
+
+| HAL Class | Wraps SDK Class | Purpose | Singleton Macro |
+|-----------|----------------|---------|-----------------|
+| `HalDisplay` | `EInkDisplay` | E-ink display control | *(none)* |
+| `HalGPIO` | `InputManager` | Button input handling | *(none)* |
+| `HalStorage` | `SDCardManager` | SD card file I/O | `Storage` |
+
+**Location**: [lib/hal/](../lib/hal/)
+
+**Why HAL?**
+- Provides consistent error logging per module
+- Abstracts SDK implementation details
+- Centralizes resource management
+
+**Example - HalStorage**:
+```cpp
+#include <HalStorage.h>
+
+// Use Storage singleton (defined via macro)
+FsFile file;
+if (Storage.openFileForRead("MODULE", "/path/to/file.bin", file)) {
+  // Read from file
+  file.close();  // Explicit close required
+}
+```
+
+**Usage**: See example above. Uses `FsFile` (SdFat), NOT Arduino `File`.
+
+---
+
+## Coding Standards
+
+### Naming Conventions
+* Classes: PascalCase (e.g., EpubReaderActivity)
+* Methods/Variables: camelCase (e.g., renderPage())
+* Constants: UPPER_SNAKE_CASE (e.g., MAX_BUFFER_SIZE)
+* Private Members: memberVariable (no prefix)
+* File Names: Match Class names (e.g., EpubReaderActivity.cpp)
+
+### Header Guards
+* Use #pragma once for all header files.
+
+### Memory Safety and RAII
+* Smart Pointers: Prefer std::unique_ptr. Avoid std::shared_ptr (unnecessary atomic overhead for a single-core RISC-V).
+* RAII: Use destructors for cleanup, but call file.close() or vTaskDelete() explicitly for deterministic resource release.
+
+### ESP32-C3 Platform Pitfalls
+
+#### `std::string_view` and Null Termination
+`string_view` is *not* null-terminated. Passing `.data()` to any C-style API (`drawText`, `snprintf`, `strcmp`, SdFat file paths) is undefined behaviour when the view is a substring or a view of a non-null-terminated buffer.
+
+**Rule**: `string_view` is safe only when passing to C++ APIs that accept `string_view`. For any C API boundary, convert explicitly:
+```cpp
+// WRONG - undefined behaviour if view is a substring:
+renderer.drawText(font, x, y, myView.data(), true);
+
+// CORRECT - guaranteed null-terminated:
+renderer.drawText(font, x, y, std::string(myView).c_str(), true);
+
+// CORRECT - for short strings, use a stack buffer:
+char buf[64];
+snprintf(buf, sizeof(buf), "%.*s", (int)myView.size(), myView.data());
+```
+
+#### `IRAM_ATTR` and Flash Cache Safety
+All code runs from flash via the instruction cache. During SPI flash operations (OTA write, SPIFFS commit, NVS update) the cache is briefly suspended. Any code that can execute during this window — ISRs in particular — must reside in IRAM or it will crash silently.
+
+```cpp
+// ISR handler: must be in IRAM
+void IRAM_ATTR gpioISR() { ... }
+
+// Data accessed from IRAM_ATTR code: must be in DRAM, never a flash const
+static DRAM_ATTR uint32_t isrEventFlags = 0;
+```
+
+**Rules**:
+- All ISR handlers: `IRAM_ATTR`
+- Data read by `IRAM_ATTR` code: `DRAM_ATTR` (a flash-resident `static const` will fault)
+- Normal task code does **not** need `IRAM_ATTR`
+
+#### ISR vs Task Shared State
+`xSemaphoreTake()` (mutex) **cannot** be called from ISR context — it will crash. Use the correct primitive for each communication direction:
+
+| Direction | Correct primitive |
+|---|---|
+| ISR → task (data) | `xQueueSendFromISR()` + `portYIELD_FROM_ISR()` |
+| ISR → task (signal) | `xSemaphoreGiveFromISR()` + `portYIELD_FROM_ISR()` |
+| Task → task | `xSemaphoreTake()` / mutex |
+| Simple flag (single writer ISR) | `volatile bool` + `portENTER_CRITICAL_ISR()` |
+
+#### RISC-V Alignment
+ESP32-C3 faults on unaligned multi-byte loads. Never cast a `uint8_t*` buffer to a wider pointer type and dereference it directly. Use `memcpy` for any unaligned read:
+
+```cpp
+// WRONG — faults if buf is not 4-byte aligned:
+uint32_t val = *reinterpret_cast<const uint32_t*>(buf);
+
+// CORRECT:
+uint32_t val;
+memcpy(&val, buf, sizeof(val));
+```
+
+This applies to all cache deserialization code and any raw buffer-to-struct casting. `__attribute__((packed))` structs have the same hazard when accessed via member reference.
+
+#### Template and `std::function` Bloat
+Each template instantiation generates a separate binary copy. `std::function<void()>` adds ~2–4 KB per unique signature and heap-allocates its closure. Avoid both in library code and any path called from the render loop:
+
+```cpp
+// Avoid — heap-allocating, large binary footprint:
+std::function<void()> callback;
+
+// Prefer — zero overhead:
+void (*callback)() = nullptr;
+
+// For member function + context (common activity callback pattern):
+struct Callback { void* ctx; void (*fn)(void*); };
+```
+
+When a template is necessary, limit instantiations: use explicit template instantiation in a `.cpp` file to prevent the compiler from generating duplicates across translation units.
+
+---
+
+### Error Handling Philosophy
+
+**Source**: [src/main.cpp:132-143](../src/main.cpp), [lib/GfxRenderer/GfxRenderer.cpp:10](../lib/GfxRenderer/GfxRenderer.cpp)
+
+**Pattern Hierarchy**:
+1. **LOG_ERR + return false** (90%): `LOG_ERR("MOD", "Failed: %s", reason); return false;`
+2. **LOG_ERR + fallback**: `LOG_ERR("MOD", "Unavailable"); useDefault();`
+3. **assert(false)**: Only for fatal "impossible" states (framebuffer missing)
+4. **ESP.restart()**: Only for recovery (OTA complete)
+
+**Rules**: NO exceptions, NO abort(), ALWAYS log before error return
+
+### Acceptable malloc/free Patterns
+
+**Source**: [src/activities/home/HomeActivity.cpp:166](../src/activities/home/HomeActivity.cpp), [lib/GfxRenderer/GfxRenderer.cpp:439-440](../lib/GfxRenderer/GfxRenderer.cpp)
+
+Despite "prefer stack allocation," malloc is acceptable for:
+1. **Large temporary buffers** (> 256 bytes, won't fit on stack)
+2. **One-time allocations** during activity initialization
+3. **Bitmap rendering buffers** (variable size, used briefly)
+
+**Pattern**:
+```cpp
+// Allocate
+auto* buffer = static_cast<uint8_t*>(malloc(bufferSize));
+if (!buffer) {
+  LOG_ERR("MODULE", "malloc failed: %d bytes", bufferSize);
+  return false;  // Handle allocation failure
+}
+
+// Use buffer
+processData(buffer, bufferSize);
+
+// Free immediately after use
+free(buffer);
+buffer = nullptr;
+```
+
+**Rules**:
+- **ALWAYS check for nullptr** after malloc
+- **Free immediately** after use (don't hold across multiple operations)
+- **Set to nullptr** after free (avoid use-after-free)
+- **Document size**: Comment why stack allocation was rejected
+
+**Examples in codebase**:
+- Cover image buffers: [HomeActivity.cpp:166](../src/activities/home/HomeActivity.cpp)
+- Text chunk buffers: [TxtReaderActivity.cpp:259](../src/activities/reader/TxtReaderActivity.cpp)
+- Bitmap rendering: [GfxRenderer.cpp:439-440](../lib/GfxRenderer/GfxRenderer.cpp)
+- OTA update buffer: [OtaUpdater.cpp:40](../src/network/OtaUpdater.cpp)
+
+---
+
+## UI and Orientation Guidelines
+
+### Orientation-Aware Logic
+* No Hardcoding: Never assume 800 or 480. Use renderer.getScreenWidth() and renderer.getScreenHeight().
+* Viewable Area: Use renderer.getOrientedViewableTRBL() to stay within physical bezel margins.
+
+### Logical Button Mapping
+
+**Source**: [src/MappedInputManager.cpp:20-55](../src/MappedInputManager.cpp)
+
+Constraint: Physical button positions are fixed on hardware, but their logical functions change based on user settings and screen orientation.
+
+**Button Categories**:
+1. **Physical Fixed** (Up/Down side buttons):
+   - `Button::Up` → Always `HalGPIO::BTN_UP`
+   - `Button::Down` → Always `HalGPIO::BTN_DOWN`
+
+2. **User Remappable** (Front buttons):
+   - `Button::Back` → Maps to `SETTINGS.frontButtonBack` (hardware index)
+   - `Button::Confirm` → Maps to `SETTINGS.frontButtonConfirm`
+   - `Button::Left` → Maps to `SETTINGS.frontButtonLeft`
+   - `Button::Right` → Maps to `SETTINGS.frontButtonRight`
+
+3. **Reader-Specific** (Page navigation with optional swap):
+   - `Button::PageBack` → Uses side button (swappable via `SETTINGS.sideButtonLayout`)
+   - `Button::PageForward` → Uses side button (swappable)
+
+**Implementation**:
+- Activities use **logical buttons** (e.g., `Button::Confirm`)
+- `MappedInputManager` translates to **physical hardware buttons**
+- User can remap front buttons in settings
+- Orientation changes handled separately by renderer coordinate transforms
+
+**Rule**: Always use `MappedInputManager::Button::*` enums, never raw `HalGPIO::BTN_*` indices (except in ButtonRemapActivity).
+
+### UITheme (The GUI Macro)
+* Rule: All UI rendering must go through the GUI macro (UITheme). 
+* Do not hardcode fonts, colors, or positioning. This ensures orientation-aware layout consistency.
+
+---
+
+## Common Patterns
+
+### Singleton Access
+**Available Singletons**:
+```cpp
+#define SETTINGS CrossPointSettings::getInstance()  // User settings
+#define APP_STATE CrossPointState::getInstance()    // Runtime state
+#define GUI UITheme::getInstance()                   // Current theme
+#define Storage HalStorage::getInstance()            // SD card I/O
+#define I18N I18n::getInstance()                     // Internationalization
+```
+
+### Activity Lifecycle and Memory Management
+
+**Source**: [src/main.cpp:132-143](../src/main.cpp)
+
+**CRITICAL**: Activities are **heap-allocated** and **deleted on exit**.
+
+```cpp
+// main.cpp navigation pattern
+void exitActivity() {
+  if (currentActivity) {
+    currentActivity->onExit();
+    delete currentActivity;  // Activity deleted here!
+    currentActivity = nullptr;
+  }
+}
+
+void enterNewActivity(Activity* activity) {
+  currentActivity = activity;  // Heap-allocated activity
+  currentActivity->onEnter();
+}
+```
+
+**Memory Implications**:
+- Activity navigation = `delete` old activity + `new` create next activity
+- Any memory allocated in `onEnter()` MUST be freed in `onExit()`
+- FreeRTOS tasks MUST be deleted in `onExit()` before activity destruction
+- File handles MUST be closed in `onExit()`
+
+**Activity Pattern**:
+```cpp
+void onEnter()  { Activity::onEnter(); /* alloc: buffer, tasks */ render(); }
+void loop()     { mappedInput.update(); /* handle input */ }
+void onExit()   { /* free: vTaskDelete, free buffer, close files */ Activity::onExit(); }
+```
+
+**Critical**: Free resources in reverse order. Delete tasks BEFORE activity destruction.
+
+### FreeRTOS Task Guidelines
+
+**Source**: [src/activities/util/KeyboardEntryActivity.cpp:45-50](../src/activities/util/KeyboardEntryActivity.cpp)
+
+**Pattern**: See Activity Lifecycle above. `xTaskCreate(&taskTrampoline, "Name", stackSize, this, 1, &handle)`
+
+**Stack Sizing** (in BYTES, not words):
+- **2048**: Simple rendering (most activities)
+- **4096**: Network, EPUB parsing
+- Monitor: `uxTaskGetStackHighWaterMark()` if crashes
+
+**Rules**: Always `vTaskDelete()` in `onExit()` before destruction. Use mutex if shared state.
+
+### Global Font Loading
+
+**Source**: [src/main.cpp:40-115](../src/main.cpp)
+
+**All fonts are loaded as global static objects** at firmware startup:
+- Bookerly: 12, 14, 16, 18pt (4 styles each: regular, bold, italic, bold-italic)
+- Noto Sans: 12, 14, 16, 18pt (4 styles each)
+- OpenDyslexic: 8, 10, 12, 14pt (4 styles each)
+- Ubuntu UI fonts: 10, 12pt (2 styles)
+
+**Total**: ~80+ global `EpdFont` and `EpdFontFamily` objects
+
+**Compilation Flag**:
+```cpp
+#ifndef OMIT_FONTS
+  // Most fonts loaded here
+#endif
+```
+
+**Implications**:
+- Fonts stored in **Flash** (marked as `static const` in `lib/EpdFont/builtinFonts/`)
+- Font rendering data cached in **DRAM** when first used
+- `OMIT_FONTS` can reduce binary size for minimal builds
+- Font IDs defined in [src/fontIds.h](../src/fontIds.h)
+
+**Usage**:
+```cpp
+#include "fontIds.h"
+
+renderer.insertFont(FONT_UI_MEDIUM, ui12FontFamily);
+renderer.drawText(FONT_UI_MEDIUM, x, y, "Hello", true);
+```
+
+---
+
+## Testing and Debugging
+
+### Build Commands
+
+**Via CLI**:
+```bash
+# Build firmware (default environment)
+pio run
+
+# Build and upload to device
+pio run -t upload
+
+# Build specific environment
+pio run -e gh_release
+
+# Clean build artifacts
+pio run -t clean
+
+# Upload filesystem data (if using SPIFFS/LittleFS)
+pio run -t uploadfs
+```
+
+**Via VS Code**:
+* Use PlatformIO toolbar: Build (✓), Upload (→), Clean (🗑️)
+* Or Command Palette: `PlatformIO: Build`, `PlatformIO: Upload`, etc.
+
+### Monitoring and Debugging
+
+```bash
+# Enhanced monitor with color/logging (recommended)
+python3 scripts/debugging_monitor.py
+
+# Standard PlatformIO monitor
+pio device monitor
+
+# Combined upload + monitor
+pio run -t upload && pio device monitor
+```
+
+**Via VS Code**: Click Monitor (🔌) button in PlatformIO toolbar
+
+### Code Quality
+
+```bash
+# Static analysis (cppcheck)
+pio check
+
+# Format code (clang-format) - Windows Git Bash
+find src -name "*.cpp" -o -name "*.h" | xargs clang-format -i
+
+# Format code (clang-format) - Linux
+clang-format -i src/**/*.cpp src/**/*.h
+```
+
+### Debugging Crashes
+
+**Common Crash Causes**:
+
+1. **Out of Memory** (Most common):
+   ```cpp
+   LOG_DBG("MEM", "Free heap: %d bytes", ESP.getFreeHeap());
+   ```
+   - Monitor heap usage throughout activity lifecycle
+   - Check if large allocations (>10KB) occur before crash
+   - Verify buffers are freed in `onExit()`
+
+2. **Stack Overflow**:
+   ```cpp
+   LOG_DBG("TASK", "Stack high water: %d", uxTaskGetStackHighWaterMark(taskHandle));
+   ```
+   - Occurs during deep recursion or large local variables
+   - Increase task stack size in `xTaskCreate()` (2048 → 4096)
+   - Move large buffers to heap with malloc
+
+3. **Use-After-Free**:
+   - Activity deleted but task still running
+   - Always `vTaskDelete()` in `onExit()` BEFORE activity destruction
+   - Set pointers to `nullptr` after `free()`
+
+4. **Corrupt Cache Files**:
+   - Delete `.crosspoint/` directory on SD card
+   - Forces clean re-parse of all EPUBs
+   - Check file format versions in [docs/file-formats.md](../docs/file-formats.md)
+
+5. **Watchdog Timeout**:
+   - Loop/task blocked for >5 seconds
+   - Add `vTaskDelay(1)` in tight loops
+   - Check for blocking I/O operations
+
+**Verification Steps**:
+1. Check serial output for stack traces
+2. Monitor heap with `ESP.getFreeHeap()` before/after operations
+3. Verify task deletion with task list (`vTaskList()`)
+4. Test with `LOG_LEVEL=2` (debug logging enabled)
+
+---
+
+## Git Workflow and Repository Awareness
+
+### Repository Detection Protocol
+
+**CRITICAL**: ALWAYS verify repository context before git operations. This could be:
+- A **fork** with `origin` pointing to personal repo, `upstream` to main repo
+- A **direct clone** with `origin` pointing to main repo
+- Multiple collaborator remotes
+
+**Verification Commands** (run at session start):
+```bash
+# Check current branch
+git branch --show-current
+
+# Check all remotes
+git remote -v
+
+# Identify main branch name (could be 'main' or 'master')
+git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@'
+
+# Check working tree status
+git status --short
+```
+
+**Example Output** (forked repository):
+```text
+origin      https://github.com/<your-username>/crosspoint-reader.git (fetch/push)
+upstream    https://github.com/crosspoint-reader/crosspoint-reader.git (fetch/push)
+```
+
+### Git Operation Rules
+
+1. **Never assume branch names**:
+   ```bash
+   # Bad: git push origin main
+   # Good: git push origin $(git branch --show-current)
+   ```
+
+2. **Never assume remote names or write permissions**:
+   - **Forked repos**: Push to `origin` (your fork), submit PR to `upstream`
+   - **Direct contributors**: May push feature branches to `upstream`
+   - **Always ask**: "Should I push to origin or create a PR?"
+
+3. **Check for upstream changes before starting work**:
+   ```bash
+   # Sync fork with upstream (if applicable)
+   git fetch upstream
+   git merge upstream/main  # or upstream/master
+   ```
+
+4. **Use explicit remote and branch names**:
+   ```bash
+   # Check remotes first
+   git remote -v
+
+   # Use explicit syntax
+   git push <remote> <branch>
+   ```
+
+### Branch Naming Convention
+
+**For feature/fix branches**:
+```text
+feature/<short-description>       # New features
+fix/<issue-number>-<description>  # Bug fixes
+refactor/<component-name>         # Code refactoring
+docs/<topic>                      # Documentation updates
+```
+
+**Examples**:
+- `feature/sd-download-progress`
+- `fix/123-orientation-crash`
+- `refactor/hal-storage`
+
+### Commit Message Format
+
+**Pattern**:
+```text
+<type>: <short summary (50 chars max)>
+
+<optional detailed description>
+
+```
+
+**Types**: `feat`, `fix`, `refactor`, `docs`, `test`, `chore`, `perf`
+
+**Example**:
+```text
+feat: add real-time SD download progress bar
+
+Implements progress tracking for book downloads using
+UITheme progress bar component with heap-safe updates.
+
+Tested in all 4 orientations with 5MB+ files.
+```
+
+### When to Commit
+
+**DO commit when**:
+- User explicitly requests: "commit these changes"
+- Feature is complete and tested on device
+- Bug fix is verified working
+- Refactoring preserves all functionality
+- All tests pass (`pio run` succeeds)
+
+**DO NOT commit when**:
+- Changes are untested on actual hardware
+- Build fails or has warnings
+- Experimenting or debugging in progress
+- User hasn't explicitly requested commit
+- Files excluded by `.gitignore` would be included — always run `git status` and cross-check against `.gitignore` before staging (e.g., `*.generated.h`, `.pio/`, `compile_commands.json`, `platformio.local.ini`)
+
+**Rule**: **If uncertain, ASK before committing.**
+
+---
+
+## Generated Files and Build Artifacts
+
+### Files Generated by Build Scripts
+
+**NEVER manually edit these files** - they are regenerated automatically:
+
+1. **HTML Headers** (generated by `scripts/build_html.py`):
+   - `src/network/html/*.generated.h`
+   - **Source**: HTML templates in `data/html/` directory
+   - **Triggered**: During PlatformIO `pre:` build step
+   - **To modify**: Edit source HTML in `data/html/`, not generated headers
+
+2. **I18n Headers** (generated by `scripts/gen_i18n.py`):
+   - `lib/I18n/I18nKeys.h`, `lib/I18n/I18nStrings.h`, `lib/I18n/I18nStrings.cpp`
+   - **Source**: YAML translation files in `lib/I18n/translations/` (one per language)
+   - **To modify**: Edit source YAML files, then run `python scripts/gen_i18n.py lib/I18n/translations lib/I18n/`
+   - **Commit**: Source YAML files only. All three generated files (`I18nKeys.h`, `I18nStrings.h`, `I18nStrings.cpp`) are in `.gitignore` and regenerated at build time.
+
+3. **Build Artifacts** (in `.gitignore`):
+   - `.pio/` - PlatformIO build output
+   - `build/` - Compiled binaries
+   - `*.generated.h` - Any auto-generated headers
+   - `compile_commands.json` - LSP/IDE metadata
+
+### Modifying Generated Content Workflow
+
+**To change HTML pages**:
+1. Edit source: `data/html/<pagename>.html`
+2. Build: `pio run` (auto-triggers `scripts/build_html.py`)
+3. Generated headers update: `src/network/html/<pagename>Html.generated.h`
+4. **Commit ONLY** source HTML, NOT generated `.generated.h` 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
+   - 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/`
+3. Generated files update: `I18nKeys.h`, `I18nStrings.h`, `I18nStrings.cpp`
+4. **Commit** source YAML files only. All three generated files are in `.gitignore` and regenerated at build time.
+
+**To use translated strings in code**:
+```cpp
+#include <I18n.h>
+// Use tr() macro with StrId enum (defined in generated I18nKeys.h)
+renderer.drawText(FONT_UI, x, y, tr(STR_LOADING), true);
+```
+
+**To add custom fonts**:
+1. Place source fonts in `lib/EpdFont/fontsrc/` (gitignored)
+2. Run conversion script (see `lib/EpdFont/README`)
+3. Update global font objects in `src/main.cpp:40-115`
+4. Add font ID constant to `src/fontIds.h`
+
+---
+
+## Local Development Configuration
+
+### platformio.local.ini (Personal Overrides)
+
+**Purpose**: Personal development settings that should NEVER be committed.
+
+**Use Cases**:
+- Serial port configuration (varies by machine)
+- Debug flags for specific testing
+- Local build optimizations
+- Developer-specific paths
+
+**Example** `platformio.local.ini`:
+```ini
+# platformio.local.ini (gitignored)
+[env:default]
+upload_port = COM7              # Windows: COMx, Linux: /dev/ttyUSBx
+monitor_port = COM7
+
+build_flags =
+  ${base.build_flags}
+  -DMY_DEBUG_FLAG=1             # Personal debug flags
+  -DTEST_FEATURE_ENABLED=1
+```
+
+**Configuration Hierarchy**:
+1. `platformio.ini` - **Committed**, shared project settings
+2. `platformio.local.ini` - **Gitignored**, personal overrides
+3. Local file extends/overrides base config
+
+**Rules**:
+- **NEVER commit** `platformio.local.ini`
+- **NEVER put** personal info (serial ports, credentials) in main `platformio.ini`
+- Use `${base.build_flags}` to extend (not replace) base flags
+
+---
+
+## Testing and Verification Workflow
+
+### Testing Checklist
+
+**AI agent scope** (what you CAN verify):
+1. ✅ **Build**: `pio run -t clean && pio run` (0 errors/warnings)
+2. ✅ **Quality**: `pio check` + `find src -name "*.cpp" -o -name "*.h" | xargs clang-format -i`
+3. ✅ **Format**: Commit messages (`feat:`/`fix:`), no `.gitignore`-excluded files staged (e.g., `*.generated.h`, `.pio/`, `platformio.local.ini`)
+4. ✅ **CI**: Fix GitHub Actions failures before review
+5. ✅ **Code review**: Ensure orientation-aware logic is correct in all 4 modes by inspecting switch/case coverage
+
+**Human tester scope** (flag these for the user):
+6. 🔲 **Device**: Test on hardware
+7. 🔲 **Orientations**: Verify all 4 modes (Portrait/Inverted/Landscape CW/CCW)
+8. 🔲 **Heap**: `ESP.getFreeHeap()` > 50KB, no leaks
+9. 🔲 **Cache**: If EPUB modified, delete `.crosspoint/` and verify re-parse
+
+### CI/CD Pipeline Awareness
+
+**GitHub Actions** run automatically on pull requests:
+
+| Workflow | File | Purpose |
+|----------|------|---------|
+| Build Check | `.github/workflows/ci.yml` | Verifies code compiles |
+| Format Check | `.github/workflows/pr-formatting-check.yml` | Validates clang-format |
+| Release Build | `.github/workflows/release.yml` | Production releases |
+| RC Build | `.github/workflows/release_candidate.yml` | Release candidates |
+
+**Rules**:
+- **Fix CI failures BEFORE** requesting review
+- CI runs on: Push to PR, PR updates
+- Format check fails → Run clang-format locally
+- Build check fails → Fix compile errors
+
+---
+
+## Serial Monitoring and Live Debugging
+
+### Serial Monitor Options
+
+1. **Enhanced**: `python3 scripts/debugging_monitor.py` (color-coded, recommended)
+2. **Standard**: `pio device monitor` (basic, no colors)
+3. **VS Code**: Monitor (🔌) button (IDE-integrated)
+
+### Live Debugging Patterns
+
+**Heap**: `LOG_DBG("MEM", "Free: %d", ESP.getFreeHeap());` (every 5s in loop)
+**Stack**: `uxTaskGetStackHighWaterMark(nullptr)` (< 512 bytes → increase stack)
+**Flush**: `logSerial.flush();` (force output before crash)
+
+**Port Detection**: Windows: `mode` | Linux: `ls /dev/ttyUSB* /dev/ttyACM*` or `dmesg | grep tty`
+
+---
+
+## Cache Management and Invalidation
+
+### Cache Structure on SD Card
+
+**Location**: `.crosspoint/` directory on SD card root
+
+**Structure**: `.crosspoint/epub_<hash>/{book.bin, progress.bin, cover.bmp, sections/*.bin}`
+
+**Hash**: `std::hash<std::string>{}(filepath)` → Moving/renaming file = new hash = lost progress
+
+### Cache Invalidation Rules
+
+**Cache is automatically invalidated when**:
+1. **File format version changes** (see `docs/file-formats.md`)
+   - `book.bin` version number incremented
+   - `section.bin` version number incremented
+2. **Render settings change**:
+   - Font family or size (`SETTINGS.fontFamily`, `SETTINGS.fontSize`)
+   - Line spacing (`SETTINGS.lineSpacing`)
+   - Paragraph spacing (`SETTINGS.extraParagraphSpacing`)
+   - Screen margins (`SETTINGS.screenMargin`)
+3. **Viewport dimensions change**:
+   - Screen orientation change
+   - Display resolution change
+4. **Book file modified**:
+   - Moved, renamed, or content changed (new hash)
+
+**Manual Cache Clear** (safe operations):
+```bash
+# Delete ALL caches (forces full regeneration)
+rm -rf /path/to/sd/.crosspoint/
+
+# Delete specific book cache
+rm -rf /path/to/sd/.crosspoint/epub_<hash>/
+
+# Keep progress, delete only rendered sections
+rm -rf /path/to/sd/.crosspoint/epub_<hash>/sections/
+```
+
+**When to Clear Cache**:
+- EPUB parsing errors after code changes to `lib/Epub/`
+- Corrupt rendering (missing text, wrong layout)
+- Testing cache generation logic
+- After modifying:
+  - `lib/Epub/Epub/Section.cpp`
+  - `lib/Epub/Epub/BookMetadataCache.cpp`
+  - Render settings in `CrossPointSettings`
+
+### Cache File Format Versioning
+
+**Source**: `lib/Epub/Epub/Section.cpp`, `lib/Epub/Epub/BookMetadataCache.cpp`
+
+**Current Versions** (as of docs/file-formats.md):
+- `book.bin`: **Version 5** (metadata structure)
+- `section.bin`: **Version 12** (layout structure)
+
+**Version Increment Rules**:
+1. **ALWAYS increment version** BEFORE changing binary structure
+2. Version mismatch → Cache auto-invalidated and regenerated
+3. Document format changes in `docs/file-formats.md`
+
+**Example** (incrementing section format version):
+```cpp
+// lib/Epub/Epub/Section.cpp
+static constexpr uint8_t SECTION_FILE_VERSION = 13;  // Was 12, now 13
+
+// Add new field to structure
+struct PageLine {
+  // ... existing fields ...
+  uint16_t newField;  // New field added
+};
+```
+
+---
+
+Philosophy: We are building a dedicated e-reader, not a Swiss Army knife. If a feature adds RAM pressure without significantly improving the reading experience, it is Out of Scope.

CLAUDE.md

@@ -0,0 +1 @@
+.skills/SKILL.md

GOVERNANCE.md

@@ -0,0 +1,38 @@
+# Project Governance & Community Principles
+
+CrossPoint Reader is a community-driven, open-source project. Our goal is to provide a high-quality, open-source
+firmware alternative for the Xteink X4 hardware. To keep this project productive and welcoming as we grow, we ask all
+contributors to follow these principles.
+
+### 1. The "Human First" Rule
+Technical discussions can get heated, but they should never be personal.
+- **Assume good intent:** We are all volunteers working on this in our free time. If a comment seems abrasive, assume
+  it’s a language barrier or a misunderstanding before taking offense.
+- **Focus on the code, not the person:** Critique the implementation, the performance, or the UX. Never the intelligence
+  or character of the contributor.
+- **Inflammatory language:** Personal attacks, trolling, or exclusionary language (based on race, gender, background,
+  etc.) are not welcome here and will be moderated.
+
+### 2. A "Do-ocracy" with Guidance
+CrossPoint thrives because people step up to build what they want to see.
+- If you want a feature, the best way to get it is to start an
+  [Idea Discussion](https://github.com/crosspoint-reader/crosspoint-reader/discussions/categories/ideas) or open a PR.
+- If you want to report a bug, check for duplicates and create an
+  [Issue](https://github.com/crosspoint-reader/crosspoint-reader/issues).
+- While we encourage experimentation, the maintainers reserve the right to guide the project’s technical direction to
+  ensure stability on the ESP32-C3’s constrained hardware.
+- For more guidance on the scope of the project, see the [SCOPE.md](SCOPE.md) document.
+
+### 3. Transparent Communication
+To keep the project healthy, we keep our "work" in the open.
+- **Public by Default:** All technical decisions and project management discussions happen in GitHub Issues, Pull
+  Requests, or the public Discussions tab.
+- **Clarity in Writing:** Because we have a global community with different levels of English proficiency, please be as
+  explicit and clear as possible in your PR descriptions and bug reports.
+
+### 4. Moderation & Safety
+The maintainers are responsible for keeping the community a safe place to contribute.
+- We reserve the right to hide comments, lock threads, or block users who repeatedly violate these principles or engage
+  in harassment.
+- **Reporting:** If you feel you are being harassed or see behavior that is damaging the community, please reach out
+  privately to @daveallie.

README.md

@@ -26,7 +26,7 @@ This project is **not affiliated with Xteink**; it's built as a community projec
 ## Features & Usage
 
 - [x] EPUB parsing and rendering (EPUB 2 and EPUB 3)
-- [ ] Image support within EPUB
+- [x] Image support within EPUB
 - [x] Saved reading position
 - [x] File explorer with file picker
   - [x] Basic EPUB picker from root directory
@@ -36,18 +36,24 @@ This project is **not affiliated with Xteink**; it's built as a community projec
   - [x] Cover sleep screen
 - [x] Wifi book upload
 - [x] Wifi OTA updates
+- [x] KOReader Sync integration for cross-device reading progress
 - [x] Configurable font, layout, and display options
   - [ ] User provided fonts
   - [ ] Full UTF support
 - [x] Screen rotation
 
-See [the user guide](./USER_GUIDE.md) for instructions on operating CrossPoint.
+Multi-language support: Read EPUBs in various languages, including English, Spanish, French, German, Italian, Portuguese, Russian, Ukrainian, Polish, Swedish, Norwegian, [and more](./USER_GUIDE.md#supported-languages).
+
+See [the user guide](./USER_GUIDE.md) for instructions on operating CrossPoint, including the
+[KOReader Sync quick setup](./USER_GUIDE.md#365-koreader-sync-quick-setup).
+
+For more details about the scope of the project, see the [SCOPE.md](SCOPE.md) document.
 
 ## Installing
 
 ### Web (latest firmware)
 
-1. Connect your Xteink X4 to your computer via USB-C
+1. Connect your Xteink X4 to your computer via USB-C and wake/unlock the device
 2. Go to https://xteink.dve.al/ and click "Flash CrossPoint firmware"
 
 To revert back to the official firmware, you can flash the latest official firmware from https://xteink.dve.al/, or swap
@@ -56,7 +62,7 @@ back to the other partition using the "Swap boot partition" button here https://
 ### Web (specific firmware version)
 
 1. Connect your Xteink X4 to your computer via USB-C
-2. Download the `firmware.bin` file from the release of your choice via the [releases page](https://github.com/daveallie/crosspoint-reader/releases)
+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. Go to https://xteink.dve.al/ and flash the firmware file using the "OTA fast flash controls" section
 
 To revert back to the official firmware, you can flash the latest official firmware from https://xteink.dve.al/, or swap
@@ -80,7 +86,7 @@ See [Development](#development) below.
 CrossPoint uses PlatformIO for building and flashing the firmware. To get started, clone the repository:
 
 ```
-git clone --recursive https://github.com/daveallie/crosspoint-reader
+git clone --recursive https://github.com/crosspoint-reader/crosspoint-reader
 
 # Or, if you've already cloned without --recursive:
 git submodule update --init --recursive
@@ -93,6 +99,25 @@ Connect your Xteink X4 to your computer via USB-C and run the following command.
 ```sh
 pio run --target upload
 ```
+### Debugging
+
+After flashing the new features, it’s recommended to capture detailed logs from the serial port.
+
+First, make sure all required Python packages are installed:
+
+```python
+python3 -m pip install pyserial colorama matplotlib
+```
+after that run the script:
+```sh
+# For Linux
+# This was tested on Debian and should work on most Linux systems.
+python3 scripts/debugging_monitor.py
+
+# For macOS
+python3 scripts/debugging_monitor.py /dev/cu.usbmodem2101
+```
+Minor adjustments may be required for Windows.
 
 ## Internals
 
@@ -131,9 +156,14 @@ For more details on the internal file structures, see the [file formats document
 
 Contributions are very welcome!
 
-If you're looking for a way to help out, take a look at the [ideas discussion board](https://github.com/daveallie/crosspoint-reader/discussions/categories/ideas).
+If you are new to the codebase, start with the [contributing docs](./docs/contributing/README.md).
+
+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 
+principles, please see [GOVERNANCE.md](GOVERNANCE.md).
+
 ### To submit a contribution:
 
 1. Fork the repo

SCOPE.md

@@ -0,0 +1,58 @@
+# Project Vision & Scope: CrossPoint Reader
+
+The goal of CrossPoint Reader is to create an efficient, open-source reading experience for the Xteink X4. We believe a
+dedicated e-reader should do one thing exceptionally well: **facilitate focused reading.**
+
+## 1. Core Mission
+
+To provide a lightweight, high-performance firmware that maximizes the potential of the X4, prioritizing legibility and
+usability over "swiss-army-knife" functionality.
+
+## 2. Scope
+
+### In-Scope
+
+*These are features that directly improve the primary purpose of the device.*
+
+* **User Experience:** E.g. User-friendly interfaces, and interactions, both inside the reader and navigating the
+  firmware. This includes things like button mapping, book loading, and book navigation like bookmarks.
+* **Document Rendering:** E.g. Support for rendering documents (primarily EPUB) and improvements to the rendering
+  engine.
+* **Format Optimization:** E.g. Efficiently parsing EPUB (CSS/Images) and other documents within the device's
+  capabilities.
+* **Typography & Legibility:** E.g. Custom font support, hyphenation engines, and adjustable line spacing.
+* **E-Ink Driver Refinement:** E.g. Reducing full-screen flashes (ghosting management) and improving general rendering.
+* **Library Management:** E.g. Simple, intuitive ways to organize and navigate a collection of books.
+* **Local Transfer:** E.g. Simple, "pull" based book loading via a basic web-server or public and widely-used standards.
+* **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.
+
+### Out-of-Scope
+
+*These items are rejected because they compromise the device's stability or mission.*
+
+* **Interactive Apps:** No Notepads, Calculators, or Games. This is a reader, not a PDA.
+* **Active Connectivity:** No RSS readers, News aggregators, or Web browsers. Background Wi-Fi tasks drain the battery
+  and complicate the single-core CPU's execution.
+* **Media Playback:** No Audio players or Audio-books.
+* **Complex Annotation:** No typed out notes. These features are better suited for devices with better input
+  capabilities and more powerful chips.
+
+### In-scope — Technically Unsupported
+
+*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
+
+While I appreciate the desire to add new and exciting features to CrossPoint Reader, CrossPoint Reader is designed to be
+a lightweight, reliable, and performant e-reader. Things which distract or compromise the device's core mission will not
+be accepted. As a guiding question, consider if your idea improve the "core reading experience" for the average user,
+and, critically, not distract from that reading experience.
+
+> **Note to Contributors:** If you are unsure if your idea fits the scope, please open a **Discussion** before you start
+> coding!

USER_GUIDE.md

@@ -2,9 +2,39 @@
 
 Welcome to the **CrossPoint** firmware. This guide outlines the hardware controls, navigation, and reading features of the device.
 
+- [CrossPoint User Guide](#crosspoint-user-guide)
+  - [1. Hardware Overview](#1-hardware-overview)
+    - [Button Layout](#button-layout)
+  - [2. Power \& Startup](#2-power--startup)
+    - [Power On / Off](#power-on--off)
+    - [First Launch](#first-launch)
+  - [3. Screens](#3-screens)
+    - [3.1 Home Screen](#31-home-screen)
+    - [3.2 Reading Mode](#32-reading-mode)
+    - [3.3 Browse Files Screen](#33-browse-files-screen)
+    - [3.4 Recent Books Screen](#34-recent-books-screen)
+    - [3.5 File Transfer Screen](#35-file-transfer-screen)
+      - [3.5.1 Calibre Wireless Transfers](#351-calibre-wireless-transfers)
+    - [3.6 Settings](#36-settings)
+      - [3.6.1 Display](#361-display)
+      - [3.6.2 Reader](#362-reader)
+      - [3.6.3 Controls](#363-controls)
+      - [3.6.4 System](#364-system)
+      - [3.6.5 KOReader Sync Quick Setup](#365-koreader-sync-quick-setup)
+    - [3.7 Sleep Screen](#37-sleep-screen)
+  - [4. Reading Mode](#4-reading-mode)
+    - [Page Turning](#page-turning)
+    - [Chapter Navigation](#chapter-navigation)
+    - [System Navigation](#system-navigation)
+    - [Supported Languages](#supported-languages)
+  - [5. Chapter Selection Screen](#5-chapter-selection-screen)
+  - [6. Current Limitations \& Roadmap](#6-current-limitations--roadmap)
+  - [7. Troubleshooting Issues \& Escaping Bootloop](#7-troubleshooting-issues--escaping-bootloop)
+
+
 ## 1. Hardware Overview
 
-The device utilises the standard buttons on the Xtink X4 (in the same layout as the manufacturer firmware, by default):
+The device utilises the standard buttons on the Xteink X4 (in the same layout as the manufacturer firmware, by default):
 
 ### Button Layout
 | Location        | Buttons                                              |
@@ -12,7 +42,12 @@ The device utilises the standard buttons on the Xtink X4 (in the same layout as
 | **Bottom Edge** | **Back**, **Confirm**, **Left**, **Right**           |
 | **Right Side**  | **Power**, **Volume Up**, **Volume Down**, **Reset** |
 
-Button layout can be customized in **[Settings](#35-settings)**.
+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/`.
+
+Alternatively, while reading a book, press the **Confirm** button to open the reader menu and select **Take screenshot**.
 
 ---
 
@@ -20,9 +55,10 @@ Button layout can be customized in **[Settings](#35-settings)**.
 
 ### Power On / Off
 
-To turn the device on or off, **press and hold the Power button for half a second**. In **[Settings](#35-settings)** you can configure the power button to trigger on a short press instead of a long one.
+To turn the device on or off, **press and hold the Power button for approximately half a second**.
+In the **[Controls Settings](#363-controls)** you can configure the power button to turn the device off with a short press instead of a long one.
 
-To reboot the device (for example if it's frozen, or after a firmware update), press and release the Reset button, and then hold the Power button for a few seconds.
+To reboot the device (for example after a firmware update or if it's frozen), press and release the Reset button, and then quickly press and hold the Power button for a few seconds.
 
 ### First Launch
 
@@ -37,73 +73,265 @@ Upon turning the device on for the first time, you will be placed on the **[Home
 
 ### 3.1 Home Screen
 
-The Home Screen is the main entry point to the firmware. From here you can navigate to **[Reading Mode](#4-reading-mode)** with the most recently read book, **[Book Selection](#32-book-selection)**, **[Settings](#35-settings)**, or the **[File Upload](#34-file-upload-screen)** screen.
+The Home screen is the main entry point to the firmware. From here you can navigate to **[Reading Mode](#4-reading-mode)** with the most recently read book, the **[Browse Files](#33-browse-files-screen)** screen, the **[Recent Books](#34-recent-books-screen)** screen, the **[File Transfer](#35-file-transfer-screen)** screen, or **[Settings](#36-settings)**.
 
-### 3.2 Book Selection
-
-The Book Selection acts as a folder and file browser.
-
-* **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.
-* **Open Selection:** Press **Confirm** to open a folder or read a selected book.
-
-### 3.3 Reading Mode
+### 3.2 Reading Mode
 
 See [Reading Mode](#4-reading-mode) below for more information.
 
-### 3.4 File Upload Screen
+### 3.3 Browse Files Screen
 
-The File Upload screen allows you to upload new e-books to the device. When you enter the screen, you'll be prompted with a WiFi selection dialog and then your X4 will start hosting a web server.
+The Browse Files screen acts as a file and folder browser.
+
+* **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.
+* **Open Selection:** Press **Confirm** to open a folder or read a selected book. 
+* **Delete Files:** Hold and release **Confirm** to delete the selected file. You will be given an option to either confirm or cancel deletion. Folder deletion is not supported.
+
+### 3.4 Recent Books Screen
+
+The Recent Books screen lists the most recently opened books in a chronological view, displaying title and author.
+
+### 3.5 File Transfer Screen
+
+The File Transfer screen allows you to upload new e-books to the device. When you enter the screen, you'll be prompted with a WiFi selection dialog and then your X4 will start hosting a web server.
 
 See the [webserver docs](./docs/webserver.md) for more information on how to connect to the web server and upload files.
 
 > [!TIP]
 > Advanced users can also manage files programmatically or via the command line using `curl`. See the [webserver docs](./docs/webserver.md) for details.
 
-### 3.5 Settings
+### 3.5.1 Calibre Wireless Transfers
+
+CrossPoint supports sending books from Calibre using the CrossPoint Reader device plugin.
+
+1. Install the plugin in Calibre:
+   - Head to https://github.com/crosspoint-reader/calibre-plugins/releases to download the latest version of the crosspoint_reader plugin.
+   - Download the zip file.
+   - Open Calibre → Preferences → Plugins → Load plugin from file → Select the zip file.
+2. On the device: File Transfer → Connect to Calibre → Join a network.
+3. Make sure your computer is on the same WiFi network.
+4. In Calibre, click "Send to device" to transfer books.
+
+### 3.6 Settings
 
 The Settings screen allows you to configure the device's behavior. There are a few settings you can adjust:
+
+#### 3.6.1 Display
+
 - **Sleep Screen**: Which sleep screen to display when the device sleeps:
-  - "Dark" (default) - The default dark sleep screen
+  - "Dark" (default) - The default dark Crosspoint logo sleep screen
   - "Light" - The same default sleep screen, on a white background
-  - "Custom" - Custom images from the SD card, see [Sleep Screen](#36-sleep-screen) below for more information
+  - "Custom" - Custom images from the SD card; see [Sleep Screen](#37-sleep-screen) below for more information
   - "Cover" - The book cover image (Note: this is experimental and may not work as expected)
-  - "Blank" - A blank screen
+  - "None" - A blank screen
+  - "Cover + Custom" - The book cover image, falls back to "Custom" behavior
+- **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
+  - "Crop" - Scale the image down and crop as necessary to try to fill the screen (Note: this is experimental and may not work as expected)
+- **Sleep Screen Cover Filter**: What filter will be applied to the book cover when "Cover" sleep screen is selected:
+  - "None" (default) - The cover image will be converted to a grayscale image and displayed as it is
+  - "Contrast" - The image will be displayed as a black & white image without grayscale conversion
+  - "Inverted" - The image will be inverted as in white & black and will be displayed without grayscale conversion
 - **Status Bar**: Configure the status bar displayed while reading:
   - "None" - No status bar
   - "No Progress" - Show status bar without reading progress
-  - "Full" - Show status bar with reading progress
-- **Extra Paragraph Spacing**: If enabled, vertical space will be added between paragraphs in the book. If disabled, paragraphs will not have vertical space between them, but will have first-line indentation.
-- **Short Power Button Click**: Whether to trigger the power button on a short press or a long press.
-- **Reading Orientation**: Set the screen orientation for reading:
-  - "Portrait" (default) - Standard portrait orientation
-  - "Landscape CW" - Landscape, rotated clockwise
-  - "Inverted" - Portrait, upside down
-  - "Landscape CCW" - Landscape, rotated counter-clockwise
-- **Front Button Layout**: Configure the order of the bottom edge buttons:
-  - Back, Confirm, Left, Right (default)
-  - Left, Right, Back, Confirm
-  - Left, Back, Confirm, Right
-- **Side Button Layout**: Swap the order of the up and down volume buttons from Previous/Next to Next/Previous. This change is only in effect when reading.
+  - "Full w/ Percentage" - Show status bar with book progress (as percentage)
+  - "Full w/ Book Bar" - Show status bar with book progress (as bar)
+  - "Book Bar Only" - Show book progress (as bar)
+  - "Full w/ Chapter Bar" - Show status bar with chapter progress (as bar)
+- **Hide Battery %**: Configure where to suppress the battery percentage display in the status bar; the battery icon will still be shown:
+  - "Never" (default) - Always show battery percentage
+  - "In Reader" - Show battery percentage everywhere except in reading mode
+  - "Always" - Always hide battery percentage
+- **Refresh Frequency**: Set how often the screen does a full refresh while reading to reduce ghosting; options are every 1, 5, 10, 15, or 30 pages.
+
+- **UI Theme**: Set which UI theme to use:
+  - "Classic" - The original Crosspoint theme
+  - "Lyra" - The new theme for Crosspoint featuring rounded elements and menu icons
+  - "Lyra Extended" - Lyra, but displays 3 books instead of 1 on the **[Home Screen](#31-home-screen)**
+- **Sunlight Fading Fix**: Configure whether to enable a software-fix for the issue where white X4 models may fade when used in direct sunlight:
+  - "OFF" (default) - Disable the fix
+  - "ON" - Enable the fix
+
+#### 3.6.2 Reader
 - **Reader Font Family**: Choose the font used for reading:
   - "Bookerly" (default) - Amazon's reading font
   - "Noto Sans" - Google's sans-serif font
   - "Open Dyslexic" - Font designed for readers with dyslexia
-- **Reader Font Size**: Adjust the text size for reading; options are "Small", "Medium", "Large", or "X Large".
-- **Reader Line Spacing**: Adjust the spacing between lines; options are "Tight", "Normal", or "Wide".
+- **Reader Font Size**: Adjust the text size for reading; options are "Small", "Medium" (default), "Large", or "X Large".
+
+- **Reader Line Spacing**: Adjust the spacing between lines; options are "Tight", "Normal" (default), or "Wide".
+- **Reader Screen Margin**: Controls the screen margins in Reading Mode between 5 and 40 pixels in 5-pixel increments.
 - **Reader Paragraph Alignment**: Set the alignment of paragraphs; options are "Justified" (default), "Left", "Center", or "Right".
-- **Time to Sleep**: Set the duration of inactivity before the device automatically goes to sleep.
-- **Refresh Frequency**: Set how often the screen does a full refresh while reading to reduce ghosting.
-- **Check for updates**: Check for firmware updates over WiFi.
+- **Embedded Style**: Whether to use the EPUB file's embedded HTML and CSS stylisation and formatting; options are "ON" or "OFF".
+- **Hyphenation**: Whether to hyphenate text in Reading Mode; options are "ON" or "OFF".
+- **Reading Orientation**: Set the screen orientation for reading EPUB files:
+  - "Portrait" (default) - Standard portrait orientation
+  - "Landscape CW" - Landscape, rotated clockwise
+  - "Inverted" - Portrait, upside down
+  - "Landscape CCW" - Landscape, rotated counter-clockwise
+- **Extra Paragraph Spacing**: Set how to handle paragraph breaks:
+  - "ON" - Vertical space will be added between paragraphs in Reading Mode
+  - "OFF" - Paragraphs will not have vertical space added, but will have first-line indentation
+- **Text Anti-Aliasing**: Whether to show smooth grey edges (anti-aliasing) on text in reading mode. Note this slows down page turns slightly.
 
-### 3.6 Sleep Screen
+#### 3.6.3 Controls
 
-You can customize the sleep screen by placing custom images in specific locations on the SD card:
+- **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". This change is only in effect when reading.
 
-- **Single Image:** Place a file named `sleep.bmp` in the root directory.
-- **Multiple Images:** Create a `sleep` directory in the root of the SD card and place any number of `.bmp` images inside. If images are found in this directory, they will take priority over the `sleep.bmp` file, and one will be randomly selected each time the device sleeps.
+- **Long-press Chapter Skip**: Set whether long-pressing page turn buttons skips to the next/previous chapter:
+  - "Chapter Skip" (default) - Long-pressing skips to next/previous chapter
+  - "Page Scroll" - Long-pressing scrolls a page up/down
+- **Short Power Button Click**: Controls the effect of a short click of the power button:
+  - "Ignore" (default) - Require a long press to turn off the device
+  - "Sleep" - A short press puts the device into sleep mode
+  - "Page Turn" - A short press in reading mode turns to the next page; a long press turns the device off
+
+#### 3.6.4 System
+
+- **Time to Sleep**: Set the duration of inactivity before the device automatically goes to sleep; options are 1, 5, 10 (default), 15 or 30 minutes.
+
+- **WiFi Networks**: Connect to WiFi networks for file transfers and firmware updates.
+- **KOReader Sync**: Options for setting up KOReader for syncing book progress.
+- **OPDS Browser**: Configure OPDS server settings for browsing and downloading books. Set the server URL (for Calibre Content Server, add `/opds` to the end), and optionally configure username and password for servers requiring authentication. Note: Only HTTP Basic authentication is supported. If using Calibre Content Server with authentication enabled, you must set it to use Basic authentication instead of the default Digest authentication.
+- **Clear Reading Cache**: Clear the internal SD card cache.
+- **Check for updates**: Check for Crosspoint firmware updates over WiFi.
+- **Language**: Set the system language (see **[Supported Languages](#supported-languages)** for more information).
+
+#### 3.6.5 KOReader Sync Quick Setup
+
+CrossPoint can sync reading progress with KOReader-compatible sync servers.
+It also interoperates with KOReader apps/devices when they use the same server and credentials.
+
+##### Option A: Free Public Server (`sync.koreader.rocks`)
+
+1. Register a user once (only if needed):
+
+```bash
+USERNAME="user"
+PASSWORD="pass"
+PASSWORD_MD5="$(printf '%s' "$PASSWORD" | openssl md5 | awk '{print $2}')"
+
+curl -i "https://sync.koreader.rocks/users/create" \
+  -H "Accept: application/vnd.koreader.v1+json" \
+  -H "Content-Type: application/json" \
+  --data "{\"username\":\"$USERNAME\",\"password\":\"$PASSWORD_MD5\"}"
+```
+
+Already have KOReader Sync credentials? Skip registration; basic sync only requires using the same existing username/password on all devices.
+
+When this returns `HTTP 402` with `{"code":2002,"message":"Username is already registered."}`, pick a different username or use that existing account.
+
+2. On each CrossPoint device:
+   - Go to **Settings -> System -> KOReader Sync**.
+   - Set **Username** and **Password** (enter the plain password; CrossPoint computes MD5 internally, and use the same values on all devices).
+   - Set **Sync Server URL** to `https://sync.koreader.rocks`, or leave it empty (both use the same default KOReader sync server).
+   - Run **Authenticate**.
+
+3. While reading, press **Confirm** to open the reader menu, then select **Sync Progress**.
+   - Choose **Apply Remote** to jump to remote progress.
+   - Choose **Upload Local** to push current progress.
+
+##### Option B: Self-Hosted Server (Docker Compose)
+
+1. Start a sync server:
+
+```bash
+mkdir -p kosync-quickstart
+cd kosync-quickstart
+
+cat > compose.yaml <<'YAML'
+services:
+  kosync:
+    image: koreader/kosync:latest
+    ports:
+      - "7200:7200"
+      - "17200:17200"
+    volumes:
+      - ./data/redis:/var/lib/redis
+    environment:
+      - ENABLE_USER_REGISTRATION=true
+    restart: unless-stopped
+YAML
+
+# Docker
+docker compose up -d
+
+# Podman (alternative)
+podman compose up -d
+```
 
 > [!NOTE]
-> You'll need to set the **Sleep Screen** setting to **Custom** in order to use these images.
+> `ENABLE_USER_REGISTRATION=true` is convenient for first setup. After creating your users, set it to `false` (or remove it) to avoid unexpected registrations.
+
+2. Verify the server:
+
+```bash
+curl -H "Accept: application/vnd.koreader.v1+json" "http://<server-ip>:17200/healthcheck"
+# Expected: {"state":"OK"}
+```
+
+3. Register a user once.
+CrossPoint authenticates against KOReader Sync (`koreader/kosync`) using an MD5 key, so register using the MD5 of your password:
+
+> [!WARNING]
+> Sending a reusable MD5-derived password over plain HTTP is insecure.
+> Create unique sync-only credentials and do not reuse main account passwords.
+> Prefer `https://<server-ip>:7200` whenever traffic leaves a fully trusted LAN or when using untrusted networks.
+> Use `curl -k` only for self-signed certificate testing.
+
+```bash
+USERNAME="user"
+PASSWORD="pass"
+PASSWORD_MD5="$(printf '%s' "$PASSWORD" | openssl md5 | awk '{print $2}')"
+
+curl -i "http://<server-ip>:17200/users/create" \
+  -H "Accept: application/vnd.koreader.v1+json" \
+  -H "Content-Type: application/json" \
+  --data "{\"username\":\"$USERNAME\",\"password\":\"$PASSWORD_MD5\"}"
+```
+
+If this returns `HTTP 402` with `{"code":2002,"message":"Username is already registered."}`, the account already exists.
+
+4. On each CrossPoint device:
+   - Go to **Settings -> System -> KOReader Sync**.
+   - Set **Username** and **Password** (enter the plain password; CrossPoint computes MD5 internally, and use the same values on all devices).
+   - Set **Sync Server URL** to `http://<server-ip>:17200`.
+   - Run **Authenticate**.
+
+If you use the HTTPS listener, use `https://<server-ip>:7200` (`curl -k` only for self-signed certificate testing).
+
+5. While reading, press **Confirm** to open the reader menu, then select **Sync Progress**.
+   - Choose **Apply Remote** to jump to remote progress.
+   - Choose **Upload Local** to push current progress.
+
+### 3.7 Sleep Screen
+
+The **Sleep Screen** setting controls what is displayed when the device goes to sleep:
+
+| Mode | Behavior |
+|------|----------|
+| **Dark** (default) | The CrossPoint logo on a dark background. |
+| **Light** | The CrossPoint logo on a white background. |
+| **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. Falls back to **Custom** behavior if no book is open. |
+| **None** | A blank screen. |
+
+#### Cover settings
+
+When using **Cover** or **Cover + Custom**, two additional settings apply:
+
+- **Sleep Screen Cover Mode**: **Fit** (scale to fit, white borders) or **Crop** (scale and crop to fill the screen).
+- **Sleep Screen Cover Filter**: **None** (grayscale), **Contrast** (black & white), or **Inverted** (inverted black & white).
+
+#### Custom images
+
+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.
 
 > [!TIP]
 > For best results:
@@ -122,16 +350,30 @@ Once you have opened a book, the button layout changes to facilitate reading.
 | **Previous Page** | Press **Left** _or_ **Volume Up**    |
 | **Next Page**     | Press **Right** _or_ **Volume Down** |
 
-The role of the volume (side) buttons can be swapped in **[Settings](#35-settings)**.
+The role of the volume (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.
 
+This feature can be disabled in the **[Controls Settings](#363-controls)** to help avoid changing chapters by mistake.
+
+
 ### System Navigation
-* **Return to Book Selection:** Press **Back** to close the book and return to the **[Book Selection](#32-book-selection)** screen.
-* **Return to Home:** Press and **hold** the **Back** button to close the book and return to the **[Home](#31-home-screen)** screen.
-* **Chapter Menu:** Press **Confirm** to open the **[Table of Contents/Chapter Selection](#5-chapter-selection-screen)**.
+* **Return to Home:** Press the **Back** button to close the book and return to the **[Home](#31-home-screen)** screen.
+* **Return to Browse Files:** Press and hold the **Back** button to close the book and return to the **[Browse Files](#33-browse-files-screen)** screen.
+* **Chapter Menu:** Press **Confirm** to open the **[Table of Contents/Chapter Selection](#5-chapter-selection-screen)** screen.
+
+### Supported Languages
+
+CrossPoint renders text using the following Unicode character blocks, enabling support for a wide range of languages:
+
+*   **Latin Script (Basic, Supplement, Extended-A):** Covers English, German, French, Spanish, Portuguese, Italian, Dutch, Swedish, Norwegian, Danish, Finnish, Polish, Czech, Hungarian, Romanian, Slovak, Slovenian, Turkish, and others.
+*   **Cyrillic Script (Standard and Extended):** Covers Russian, Ukrainian, Belarusian, Bulgarian, Serbian, Macedonian, Kazakh, Kyrgyz, Mongolian, and others.
+
+What is not supported: Chinese, Japanese, Korean, Vietnamese, Hebrew, Arabic, Greek and Farsi.
 
 ---
 
@@ -150,3 +392,18 @@ Accessible by pressing **Confirm** while inside a book.
 Please note that this firmware is currently in active development. The following features are **not yet supported** but are planned for future updates:
 
 * **Images:** Embedded images in e-books will not render.
+* **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.
+
+---
+
+## 7. Troubleshooting Issues & Escaping Bootloop
+
+If an issue or crash is encountered while using Crosspoint, feel free to raise an issue ticket and attach the serial monitor logs. The logs can be obtained by connecting the device to a computer and starting a serial monitor. Either [Serial Monitor](https://www.serialmonitor.org/) or the following command can be used:
+
+```
+pio device monitor
+```
+
+If the device is stuck in a bootloop, press and release the Reset button. Then, press and hold on to the configured Back button and the Power Button to boot to the Home Screen.
+
+There can be issues with broken cache or config. In this case, delete the `.crosspoint` directory on your SD card (or consider deleting only `settings.bin`, `state.bin`, or `epub_*` cache directories in the `.crosspoint/` folder).

bin/clang-format-fix

@@ -1,10 +1,33 @@
-#!/bin/bash
+#!/usr/bin/env bash
+
+# Check if clang-format is available and pick the preferred binary.
+if command -v clang-format-21 >/dev/null 2>&1; then
+  CLANG_FORMAT_BIN="clang-format-21"
+elif command -v clang-format >/dev/null 2>&1; then
+  CLANG_FORMAT_BIN="clang-format"
+else
+  printf "'clang-format' not found in current environment\n"
+  printf "Install clang-format-21 (recommended), clang, clang-tools, or clang-format depending on your distro/os and tooling requirements\n"
+  exit 1
+fi
+
+set -euo pipefail
 
 GIT_LS_FILES_FLAGS=""
-if [[ "$1" == "-g" ]]; then
+if [[ "${1:-}" == "-g" ]]; then
   GIT_LS_FILES_FLAGS="--modified"
 fi
 
+CLANG_FORMAT_VERSION_RAW="$(${CLANG_FORMAT_BIN} --version)"
+CLANG_FORMAT_MAJOR="$(printf '%s\n' "${CLANG_FORMAT_VERSION_RAW}" | grep -oE '[0-9]+' | head -n1)"
+
+if [[ -z "${CLANG_FORMAT_MAJOR}" || "${CLANG_FORMAT_MAJOR}" -lt 21 ]]; then
+  echo "Error: ${CLANG_FORMAT_BIN} is too old: ${CLANG_FORMAT_VERSION_RAW}"
+  echo "This repository's .clang-format requires clang-format 21 or newer."
+  echo "Install clang-format-21 and rerun ./bin/clang-format-fix"
+  exit 1
+fi
+
 # --- Main Logic ---
 
 # Format all files (or only modified files if -g is passed)
@@ -13,7 +36,10 @@ fi
 # --modified: files tracked by git that have been modified (staged or unstaged)
 # --exclude-standard: ignores files in .gitignore
 # Additionally exclude files in 'lib/EpdFont/builtinFonts/' as they are script-generated.
+# Also exclude files in 'lib/Epub/Epub/hyphenation/generated/' as they are script-generated.
 git ls-files  --exclude-standard ${GIT_LS_FILES_FLAGS} \
     | grep -E '\.(c|cpp|h|hpp)$' \
     | grep -v -E '^lib/EpdFont/builtinFonts/' \
-    | xargs -r clang-format -style=file -i
+    | grep -v -E '^lib/Epub/Epub/hyphenation/generated/' \
+    | grep -v -E '^lib/uzlib/' \
+    | xargs -r "${CLANG_FORMAT_BIN}" -style=file -i

bin/clang-format-fix.ps1

@@ -0,0 +1,154 @@
+<#
+.SYNOPSIS
+    Runs clang-format -i on project *.cpp and *.h files.
+
+.DESCRIPTION
+    Formats all C/C++ source and header files in the repository, excluding
+    generated, vendored, and build directories (open-x4-sdk, builtinFonts,
+    hyphenation tries, uzlib, .pio, *.generated.h).
+
+    The clang-format binary path is resolved once and cached in
+    bin/clang-format-fix.local. On first run it checks a default path,
+    then PATH, then common install locations. Edit the .local file to
+    override manually.
+
+.PARAMETER g
+    Format only git-modified files (git diff --name-only HEAD) instead of
+    the full tree.
+
+.PARAMETER h
+    Show this help text.
+
+.EXAMPLE
+    .\clang-format-fix.ps1
+    Format all files.
+
+.EXAMPLE
+    .\clang-format-fix.ps1 -g
+    Format only git-modified files.
+#>
+
+param(
+    [switch]$g,
+    [switch]$h
+)
+
+if ($h) {
+    Get-Help $PSCommandPath -Detailed
+    return
+}
+
+$repoRoot = (Resolve-Path "$PSScriptRoot\..").Path
+$configFile = Join-Path $PSScriptRoot 'clang-format-fix.local'
+$defaultPath = 'C:\Program Files\LLVM\bin\clang-format.exe'
+
+$candidatePaths = @(
+    'C:\Program Files\LLVM\bin\clang-format.exe'
+    'C:\Program Files (x86)\LLVM\bin\clang-format.exe'
+    'C:\msys64\ucrt64\bin\clang-format.exe'
+    'C:\msys64\mingw64\bin\clang-format.exe'
+    "$env:LOCALAPPDATA\LLVM\bin\clang-format.exe"
+)
+
+function Find-ClangFormat {
+    # Try PATH first
+    $inPath = Get-Command clang-format -ErrorAction SilentlyContinue
+    if ($inPath) { return $inPath.Source }
+
+    # Try candidate paths
+    foreach ($p in $candidatePaths) {
+        if (Test-Path $p) { return $p }
+    }
+    return $null
+}
+
+function Resolve-ClangFormat {
+    # 1. Read from config if present
+    if (Test-Path $configFile) {
+        $saved = (Get-Content $configFile -Raw).Trim()
+        if ($saved -and (Test-Path $saved)) { return $saved }
+        Write-Host "Configured path no longer valid: $saved"
+    }
+
+    # 2. Check default
+    if (Test-Path $defaultPath) {
+        $defaultPath | Set-Content $configFile
+        Write-Host "Saved clang-format path to $configFile"
+        return $defaultPath
+    }
+
+    # 3. Search PATH and candidate locations
+    $found = Find-ClangFormat
+    if ($found) {
+        $found | Set-Content $configFile
+        Write-Host "Found clang-format at $found - saved to $configFile"
+        return $found
+    }
+
+    Write-Error "clang-format not found. Install LLVM or add clang-format to PATH."
+    exit 1
+}
+
+$clangFormat = Resolve-ClangFormat
+
+$exclude = @(
+    'open-x4-sdk'
+    'lib\EpdFont\builtinFonts'
+    'lib\Epub\Epub\hyphenation\generated'
+    'lib\uzlib'
+    '.pio'
+)
+
+function Test-Excluded($fullPath) {
+    foreach ($ex in $exclude) {
+        if ($fullPath -like "*\$ex\*") { return $true }
+    }
+    if ($fullPath -like '*.generated.h') { return $true }
+    return $false
+}
+
+if ($g) {
+    # Only git-modified *.cpp / *.h files
+    # Covers both staged and unstaged changes
+    $files = @(git -C $repoRoot diff --name-only HEAD) +
+             @(git -C $repoRoot diff --name-only --cached) |
+        Sort-Object -Unique |
+        Where-Object { $_ -match '\.(cpp|h)$' } |
+        ForEach-Object { Get-Item (Join-Path $repoRoot $_) -ErrorAction SilentlyContinue } |
+        Where-Object { $_ -and -not (Test-Excluded $_.FullName) }
+} else {
+    $files = Get-ChildItem -Path $repoRoot -Recurse -Include *.cpp, *.h -File |
+        Where-Object { -not (Test-Excluded $_.FullName) }
+}
+
+$files = @($files)
+
+if ($files.Count -eq 0) {
+    Write-Host 'No files to format.'
+    return
+}
+
+Write-Host "Formatting $($files.Count) files..."
+$i = 0
+$changed = 0
+$failures = 0
+foreach ($f in $files) {
+    $i++
+    $rel = $f.FullName.Substring($repoRoot.Length + 1)
+    $hashBefore = (Get-FileHash $f.FullName -Algorithm MD5).Hash
+    & $clangFormat -i $f.FullName
+    if ($LASTEXITCODE -ne 0) {
+        $failures++
+        Write-Host "  [$i/$($files.Count)] $rel (FAILED, exit code $LASTEXITCODE)"
+        continue
+    }
+    $hashAfter = (Get-FileHash $f.FullName -Algorithm MD5).Hash
+    if ($hashBefore -ne $hashAfter) {
+        $changed++
+        Write-Host "  [$i/$($files.Count)] $rel (changed)"
+    } else {
+        Write-Host "  [$i/$($files.Count)] $rel"
+    }
+}
+Write-Host "Done. $changed/$($files.Count) files changed, $failures failed."
+if ($failures -gt 0) { exit 1 }

docs/activity-manager.md

@@ -0,0 +1,472 @@
+# Activity & ActivityManager Migration Guide
+
+This document explains the refactoring from the original per-activity render task model to the centralized `ActivityManager` introduced in [PR #1016](https://github.com/crosspoint-reader/crosspoint-reader/pull/1016). It covers the architectural differences, what changed for activity authors, and the FreeRTOS task and locking model that underpins the system.
+
+## Overview of Changes
+
+| Aspect | Old Model | New Model |
+|--------|-----------|-----------|
+| Render task | One per activity (8KB stack each) | Single shared task in `ActivityManager` |
+| Render mutex | Per-activity `renderingMutex` | Single global mutex in `ActivityManager` |
+| `RenderLock` | Inner class of `Activity` | Standalone class, acquires global mutex |
+| Subactivities | `ActivityWithSubactivity` base class | Activity stack managed by `ActivityManager` |
+| Navigation | Free functions in `main.cpp` | `activityManager.goHome()`, `goToReader()`, etc. |
+| Subactivity results | Callback lambdas stored in parent | `startActivityForResult()` / `setResult()` / `finish()` |
+| `requestUpdate()` | Notifies activity's own render task | Delegates to `ActivityManager` (immediate or deferred) |
+
+## Architecture
+
+### Old Model: Per-Activity Render Tasks
+
+Each activity created its own FreeRTOS render task on entry and destroyed it on exit:
+
+```text
+┌─────────────────────────────────────────────────────────┐
+│ Main Task (Arduino loop)                                │
+│  ┌───────────────────────────────────────────────────┐  │
+│  │ currentActivity->loop()                           │  │
+│  │   ├── handle input                                │  │
+│  │   ├── update state (under RenderLock)             │  │
+│  │   └── requestUpdate()  ──notify──►  Render Task   │  │
+│  │                                      (per-activity)│  │
+│  │                                      8KB stack     │  │
+│  │                                      owns mutex    │  │
+│  └───────────────────────────────────────────────────┘  │
+│                                                         │
+│ ActivityWithSubactivity:                                │
+│  ┌──────────────┐     ┌──────────────┐                  │
+│  │ Parent        │────►│ SubActivity   │                 │
+│  │ (has render   │     │ (has own      │                 │
+│  │  task)        │     │  render task) │                 │
+│  └──────────────┘     └──────────────┘                  │
+└─────────────────────────────────────────────────────────┘
+```
+
+Problems with this approach:
+
+- **8KB per render task**: Each activity allocated an 8KB FreeRTOS stack for its render task, even though only one renders at a time
+- **Dangerous deletion patterns**: `exitActivity()` + `enterNewActivity()` in callbacks led to `delete this` situations where the caller was destroyed while its code was still on the stack
+- **Subactivity coupling**: Parents stored callbacks to child results, creating tight coupling and lifetime hazards
+
+### New Model: Centralized ActivityManager
+
+A single `ActivityManager` owns the render task and manages an activity stack:
+
+```text
+┌──────────────────────────────────────────────────────────┐
+│ Main Task (Arduino loop)                                 │
+│                                                          │
+│  activityManager.loop()                                  │
+│    │                                                     │
+│    ├── currentActivity->loop()                           │
+│    │     ├── handle input                                │
+│    │     ├── update state (under RenderLock)              │
+│    │     └── requestUpdate()                             │
+│    │                                                     │
+│    ├── process pending actions (Push / Pop / Replace)    │
+│    │                                                     │
+│    └── if requestedUpdate: ──notify──► Render Task       │
+│                                         (single, shared) │
+│                                         8KB stack        │
+│                                         global mutex     │
+│                                                          │
+│  Activity Stack:                                         │
+│  ┌──────────┬──────────┬──────────┐    ┌──────────┐     │
+│  │ Home     │ Settings │ Wifi     │    │ Keyboard │     │
+│  │ (stack)  │ (stack)  │ (stack)  │    │ (current)│     │
+│  └──────────┴──────────┴──────────┘    └──────────┘     │
+│   stackActivities[]                    currentActivity   │
+└──────────────────────────────────────────────────────────┘
+```
+
+## Migration Checklist
+
+### 1. Change Base Class
+
+If your activity extended `ActivityWithSubactivity`, change it to extend `Activity`:
+
+```cpp
+// BEFORE
+class MyActivity final : public ActivityWithSubactivity {
+  MyActivity(GfxRenderer& r, MappedInputManager& m, std::function<void()> goBack)
+      : ActivityWithSubactivity("MyActivity", r, m), goBack(goBack) {}
+};
+
+// AFTER
+class MyActivity final : public Activity {
+  MyActivity(GfxRenderer& r, MappedInputManager& m)
+      : Activity("MyActivity", r, m) {}
+};
+```
+
+Note that navigation callbacks like `goBack` are no longer stored — use `finish()` or `activityManager.goHome()` instead.
+
+### 2. Replace Navigation Functions
+
+The free functions `exitActivity()` / `enterNewActivity()` in `main.cpp` are gone. Use `ActivityManager` methods:
+
+```cpp
+// BEFORE (in main.cpp or via stored callbacks)
+exitActivity();
+enterNewActivity(new SettingsActivity(renderer, mappedInput, onGoHome));
+
+// AFTER (from any Activity method)
+activityManager.goToSettings();
+// or for arbitrary navigation:
+activityManager.replaceActivity(std::make_unique<MyActivity>(renderer, mappedInput));
+```
+
+`replaceActivity()` destroys the current activity and clears the stack. Use it for top-level navigation (home, reader, settings, etc.).
+
+### 3. Replace Subactivity Pattern
+
+The `enterNewActivity()` / `exitActivity()` subactivity pattern is replaced by a stack with typed results:
+
+```cpp
+// BEFORE
+void MyActivity::launchWifi() {
+  enterNewActivity(new WifiSelectionActivity(renderer, mappedInput,
+      [this](bool connected) { onWifiDone(connected); }));
+}
+// Child calls: onComplete(true); // triggers callback, which may call exitActivity()
+
+// AFTER
+void MyActivity::launchWifi() {
+  startActivityForResult(
+      std::make_unique<WifiSelectionActivity>(renderer, mappedInput),
+      [this](const ActivityResult& result) {
+        if (result.isCancelled) return;
+        auto& wifi = std::get<WifiResult>(result.data);
+        onWifiDone(wifi.connected);
+      });
+}
+// Child calls:
+//   setResult(WifiResult{.connected = true, .ssid = ssid});
+//   finish();
+```
+
+Key differences:
+
+- **`startActivityForResult()`** pushes the current activity onto the stack and launches the child
+- **`setResult()`** stores a typed result on the child activity
+- **`finish()`** signals the manager to pop the child, call the result handler, and resume the parent
+- The parent is never deleted during this process — it's safely stored on the stack
+
+### 4. Update `render()` Signature
+
+The `RenderLock` type changed from `Activity::RenderLock` (inner class) to standalone `RenderLock`:
+
+```cpp
+// BEFORE
+void render(Activity::RenderLock&&) override;
+
+// AFTER
+void render(RenderLock&&) override;
+```
+
+Include `RenderLock.h` if not transitively included via `Activity.h`.
+
+### 5. Update `onEnter()` / `onExit()`
+
+Activities no longer create or destroy render tasks:
+
+```cpp
+// BEFORE
+void MyActivity::onEnter() {
+  Activity::onEnter();       // created render task + logged
+  // ... allocate resources
+  requestUpdate();
+}
+void MyActivity::onExit() {
+  // ... free resources
+  Activity::onExit();        // acquired RenderLock, deleted render task
+}
+
+// AFTER
+void MyActivity::onEnter() {
+  Activity::onEnter();       // just logs
+  // ... allocate resources
+  requestUpdate();
+}
+void MyActivity::onExit() {
+  // ... free resources
+  Activity::onExit();        // just logs
+}
+```
+
+The render task lifecycle is handled entirely by `ActivityManager::begin()`.
+
+### 6. Update `requestUpdate()` Calls
+
+The signature changed to accept an `immediate` flag:
+
+```cpp
+// BEFORE
+void requestUpdate();  // always immediate notification to per-activity render task
+
+// AFTER
+void requestUpdate(bool immediate = false);
+// immediate=false (default): deferred until end of current loop iteration
+// immediate=true: sends notification to render task right away
+```
+
+**When to use `immediate`**: Almost never. Deferred updates are batched — if `loop()` triggers multiple state changes that each call `requestUpdate()`, only one render happens. Use `immediate` only when you need the render to start before the current function returns (e.g., before a blocking network call).
+
+**`requestUpdateAndWait()`**: Blocks the calling task until the render completes. Use sparingly — it's designed for cases where you need the screen to reflect new state before proceeding (e.g., showing "Checking for update..." before calling a network API).
+
+### 7. Remove Stored Navigation Callbacks
+
+Old activities often stored `std::function` callbacks for navigation:
+
+```cpp
+// BEFORE
+class SettingsActivity : public ActivityWithSubactivity {
+  const std::function<void()> goBack;   // stored callback
+  const std::function<void()> goHome;   // stored callback
+public:
+  SettingsActivity(GfxRenderer& r, MappedInputManager& m,
+                   std::function<void()> goBack, std::function<void()> goHome)
+      : ActivityWithSubactivity("Settings", r, m), goBack(goBack), goHome(goHome) {}
+};
+
+// AFTER
+class SettingsActivity : public Activity {
+public:
+  SettingsActivity(GfxRenderer& r, MappedInputManager& m)
+      : Activity("Settings", r, m) {}
+  // Use finish() to go back, activityManager.goHome() to go home
+};
+```
+
+This removes `std::function` overhead (~2-4KB per unique signature) and eliminates lifetime risks from captured `this` pointers.
+
+## Technical Details
+
+### FreeRTOS Task Model
+
+The firmware runs on an ESP32-C3, a single-core RISC-V microcontroller. FreeRTOS provides cooperative and preemptive multitasking on this single core — only one task executes at any moment, and the scheduler switches between tasks at yield points (blocking calls, `vTaskDelay`, `taskYIELD`) or when a tick interrupt promotes a higher-priority task.
+
+There are two tasks relevant to the activity system:
+
+```text
+┌──────────────────────┐     ┌──────────────────────────┐
+│ Main Task            │     │ Render Task              │
+│ (Arduino loop)       │     │ (ActivityManager-owned)   │
+│ Priority: 1          │     │ Priority: 1              │
+│                      │     │                          │
+│ Runs:                │     │ Runs:                    │
+│ - gpio.update()      │     │ - ulTaskNotifyTake()     │
+│ - activity->loop()   │     │   (blocks until notified)│
+│ - pending actions    │     │ - RenderLock (mutex)     │
+│ - sleep/power mgmt   │     │ - activity->render()     │
+│ - requestUpdate →────┼─────┼─► xTaskNotify()          │
+│   (end of loop)      │     │                          │
+└──────────────────────┘     └──────────────────────────┘
+```
+
+Both tasks run at priority 1. Since the ESP32-C3 is single-core, they alternate execution: the main task runs `loop()`, then at the end of the loop iteration, notifies the render task if an update was requested. The render task wakes, acquires the mutex, calls `render()`, releases the mutex, and blocks again.
+
+Do not use `xTaskCreate` inside activities. If you have a use case that seems to require a background task, open a discussion to propose a lifecycle-aware `Worker` abstraction first.
+
+### The Render Mutex and RenderLock
+
+A single FreeRTOS mutex (`renderingMutex`) protects shared state between `loop()` and `render()`. Since these run on different tasks, any state read by `render()` and written by `loop()` must be guarded.
+
+`RenderLock` is an RAII wrapper:
+
+```cpp
+// Standalone class (not tied to any specific activity)
+class RenderLock {
+  bool isLocked = false;
+public:
+  explicit RenderLock();           // acquires activityManager.renderingMutex
+  explicit RenderLock(Activity&);  // same — Activity& param kept for compatibility
+  ~RenderLock();                   // releases mutex if still held
+  void unlock();                   // early release
+};
+```
+
+**Usage patterns:**
+
+```cpp
+// In loop(): protect state mutations that render() reads
+void MyActivity::loop() {
+  if (somethingChanged) {
+    RenderLock lock;
+    state = newState;        // safe — render() can't run while lock is held
+  }
+  requestUpdate();           // trigger render after lock is released
+}
+
+// In render(): lock is passed in, held for duration of render
+void MyActivity::render(RenderLock&&) {
+  // Lock is held — safe to read shared state
+  renderer.clearScreen();
+  renderer.drawText(..., stateString, ...);
+  renderer.displayBuffer();
+  // Lock released when RenderLock destructor runs
+}
+```
+
+**Critical rule**: Never call `requestUpdateAndWait()` while holding a `RenderLock`. The render task needs the mutex to call `render()`, so holding it while waiting for the render to complete is a deadlock:
+
+```text
+Main Task                    Render Task
+──────────                   ───────────
+RenderLock lock;             (blocked on mutex)
+requestUpdateAndWait();
+  → notify render task
+  → block waiting for
+    render to complete        → wakes up
+                              → tries to acquire mutex
+                              → DEADLOCK: main holds mutex,
+                                waits for render; render
+                                waits for mutex
+```
+
+### requestUpdate() vs requestUpdateAndWait()
+
+```text
+requestUpdate(false)          requestUpdate(true)
+─────────────────             ─────────────────
+Sets flag only.               Notifies render task
+Render happens after          immediately.
+loop() returns and            Render may start
+ActivityManager checks        before the calling
+the flag.                     function returns.
+                              (Does NOT wait for
+                              render to complete.)
+
+requestUpdateAndWait()
+──────────────────────
+Notifies render task AND
+blocks calling task until
+render is done. Uses
+FreeRTOS direct-to-task
+notification on the
+caller's task handle.
+```
+
+`requestUpdateAndWait()` flow in detail:
+
+```text
+Calling Task                 Render Task
+────────────                 ───────────
+requestUpdateAndWait()
+  ├─ assert: not render task
+  ├─ assert: not holding RenderLock
+  ├─ store waitingTaskHandle
+  ├─ xTaskNotify(renderTask)  → wakes render task
+  └─ ulTaskNotifyTake() ─┐
+     (blocked)           │    RenderLock lock;
+                         │    activity->render();
+                         │    // render complete
+                         │    taskENTER_CRITICAL
+                         │    waiter = waitingTaskHandle
+                         │    waitingTaskHandle = nullptr
+                         │    taskEXIT_CRITICAL
+                         │    xTaskNotify(waiter) ───┐
+                         │                           │
+  ┌──────────────────────┘                           │
+  │ (woken by notification) ◄────────────────────────┘
+  └─ return
+```
+
+### Activity Lifecycle Under ActivityManager
+
+```text
+activityManager.replaceActivity(make_unique<MyActivity>(...))
+  │
+  ▼
+╔═══════════════════════════════════════════════════╗
+║  pendingAction = Replace                          ║
+║  pendingActivity = MyActivity                     ║
+╚═══════════════════════════════════════════════════╝
+  │
+  ▼ (next loop iteration)
+  ActivityManager::loop()
+  │
+  ├── currentActivity->loop()     // old activity's last loop
+  │
+  ├── process pending action:
+  │   ├── RenderLock lock;
+  │   ├── oldActivity->onExit()   // cleanup under lock
+  │   ├── delete oldActivity
+  │   ├── clear stack
+  │   ├── currentActivity = MyActivity
+  │   ├── lock.unlock()
+  │   └── MyActivity->onEnter()   // init new activity
+  │
+  └── if requestedUpdate:
+      └── notify render task
+```
+
+For push/pop (subactivity) navigation:
+
+```text
+Parent calls: startActivityForResult(make_unique<Child>(...), handler)
+  │
+  ▼
+╔══════════════════════════════════════╗
+║  pendingAction = Push               ║
+║  pendingActivity = Child            ║
+║  parent->resultHandler = handler    ║
+╚══════════════════════════════════════╝
+  │
+  ▼ (next loop iteration)
+  ├── Parent moved to stackActivities[]
+  ├── currentActivity = Child
+  └── Child->onEnter()
+
+        ... child runs ...
+
+Child calls: setResult(MyResult{...}); finish();
+  │
+  ▼
+╔══════════════════════════════════════╗
+║  pendingAction = Pop                ║
+║  child->result = MyResult{...}      ║
+╚══════════════════════════════════════╝
+  │
+  ▼ (next loop iteration)
+  ├── result = child->result
+  ├── Child->onExit(); delete Child
+  ├── currentActivity = Parent (popped from stack)
+  ├── Parent->resultHandler(result)
+  └── requestUpdate()   // automatic re-render for parent
+```
+
+### Common Pitfalls
+
+**Calling `finish()` and continuing to access `this`**: `finish()` sets `pendingAction = Pop` but does not immediately destroy the activity. The activity is destroyed on the next `ActivityManager::loop()` iteration. It's safe to access member variables after `finish()` within the same function, but don't rely on the activity surviving past the current `loop()` call.
+
+**Modifying shared state without `RenderLock`**: If `render()` reads a variable and `loop()` writes it, the write must be under a `RenderLock`. Without it, `render()` could see a half-written value (e.g., a partially updated string or struct).
+
+**Creating background tasks that outlive the activity**: Any FreeRTOS task created in `onEnter()` must be deleted in `onExit()` before the activity is destroyed. The `ActivityManager` does not track or clean up background tasks.
+
+**Holding `RenderLock` across blocking calls**: The render task is blocked on the mutex while you hold the lock. Keep critical sections short — acquire, mutate state, release, then do blocking work.
+
+```cpp
+// WRONG — blocks render for the entire network call
+void MyActivity::doNetworkStuff() {
+  RenderLock lock;
+  state = LOADING;
+  auto result = http.get(url);  // blocks for seconds with lock held
+  state = DONE;
+}
+
+// CORRECT — release lock before blocking
+void MyActivity::doNetworkStuff() {
+  {
+    RenderLock lock;
+    state = LOADING;
+  }
+  requestUpdate(true);           // render "Loading..." immediately, before we block
+  auto result = http.get(url);   // lock is not held
+  {
+    RenderLock lock;
+    state = DONE;
+  }
+  requestUpdate();
+}
+```

docs/contributing/README.md

@@ -0,0 +1,11 @@
+# Contributing Docs
+
+This section is a lightweight contributor guide for CrossPoint Reader.
+It is written for software developers who may be new to embedded development.
+
+- [Getting Started](./getting-started.md)
+- [Architecture Overview](./architecture.md)
+- [Development Workflow](./development-workflow.md)
+- [Testing and Debugging](./testing-debugging.md)
+
+If you are new, start with [Getting Started](./getting-started.md).

docs/contributing/architecture.md

@@ -0,0 +1,199 @@
+# Architecture Overview
+
+CrossPoint is firmware for the Xteink X4 (unaffiliated with Xteink), built with PlatformIO targeting the ESP32-C3 microcontroller.
+
+At a high level, it is firmware that uses an activity-driven application architecture loop with persistent settings/state, SD-card-first caching, and a rendering pipeline optimized for e-ink constraints.
+
+## System at a glance
+
+```mermaid
+graph TD
+    A[Hardware: ESP32-C3 + SD + E-ink + Buttons] --> B[open-x4-sdk HAL]
+    B --> C[src/main.cpp runtime loop]
+    C --> D[Activities layer]
+    C --> E[State and settings]
+    D --> F[Reader flows]
+    D --> G[Home/Library/Settings flows]
+    D --> H[Network/Web server flows]
+    F --> I[lib/Epub parsing + layout + hyphenation]
+    I --> J[SD cache in .crosspoint]
+    D --> K[GfxRenderer]
+    K --> L[E-ink display buffer]
+```
+
+## Runtime lifecycle
+
+Primary entry point is `src/main.cpp`.
+
+```mermaid
+flowchart TD
+    A[Boot] --> B[Init GPIO and optional serial]
+    B --> C[Init SD storage]
+    C --> D[Load settings and app state]
+    D --> E[Init display and fonts]
+    E --> F{Resume reader?}
+    F -->|No| G[Enter Home activity]
+    F -->|Yes| H[Enter Reader activity]
+    G --> I[Main loop]
+    H --> I
+    I --> J[Poll input and run current activity]
+    J --> K{Sleep condition met?}
+    K -->|No| I
+    K -->|Yes| L[Persist state and enter deep sleep]
+```
+
+In each loop iteration, the firmware updates input, runs the active activity, handles auto-sleep/power behavior, and applies a short delay policy to balance responsiveness and power.
+
+## Activity model
+
+Activities are screen-level controllers deriving from `src/activities/Activity.h`.
+Some flows use `src/activities/ActivityWithSubactivity.h` to host nested activities.
+
+- `onEnter()` and `onExit()` manage setup/teardown
+- `loop()` handles per-frame behavior
+- `skipLoopDelay()` and `preventAutoSleep()` are used by long-running flows (for example web server mode)
+
+Top-level activity groups:
+
+- `src/activities/home/`: home and library navigation
+- `src/activities/reader/`: EPUB/XTC/TXT reading flows
+- `src/activities/settings/`: settings menus and configuration
+- `src/activities/network/`: WiFi selection, AP/STA mode, file transfer server
+- `src/activities/boot_sleep/`: boot and sleep transitions
+
+## Reader and content pipeline
+
+Reader orchestration starts in `src/activities/reader/ReaderActivity.h` and dispatches to format-specific readers.
+EPUB processing is implemented in `lib/Epub/`.
+
+```mermaid
+flowchart LR
+    A[Select book] --> B[ReaderActivity]
+    B --> C{Format}
+    C -->|EPUB| D[lib/Epub/Epub]
+    C -->|XTC| E[lib/Xtc reader]
+    C -->|TXT| F[lib/Txt reader]
+    D --> G[Parse OPF/TOC/CSS]
+    G --> H[Layout pages/sections]
+    H --> I[Write section and metadata caches]
+    I --> J[Render current page via GfxRenderer]
+```
+
+Why caching matters:
+
+- RAM is limited on ESP32-C3, so expensive parsed/layout data is persisted to SD
+- repeat opens/page navigation can reuse cached data instead of full reparsing
+
+## Reader internals call graph
+
+This diagram zooms into the EPUB path to show the main control and data flow from activity entry to on-screen draw.
+
+```mermaid
+flowchart TD
+    A[ReaderActivity onEnter] --> B{File type}
+    B -->|EPUB| C[Create Epub object]
+    B -->|XTC/TXT| Z[Use format-specific reader]
+
+    C --> D[Epub load]
+    D --> E[Locate container and OPF]
+    E --> F[Build or load BookMetadataCache]
+    F --> G[Load TOC and spine]
+    G --> H[Load or parse CSS rules]
+
+    H --> I[EpubReaderActivity]
+    I --> J{Section cache exists for current settings?}
+    J -->|Yes| K[Read section bin from SD cache]
+    J -->|No| L[Parse chapter HTML and layout text]
+    L --> M[Apply typography settings and hyphenation]
+    M --> N[Write section cache bin]
+
+    K --> O[Build page model]
+    N --> O
+    O --> P[GfxRenderer draw calls]
+    P --> Q[HAL display framebuffer update]
+    Q --> R[E-ink refresh policy]
+
+    S[SETTINGS singleton] -. influences .-> J
+    S -. influences .-> M
+    T[APP_STATE singleton] -. persists .-> U[Reading progress and resume context]
+    U -. used by .-> I
+```
+
+Notes:
+
+- "section cache exists" depends on cache-busting parameters such as font and layout-related settings
+- rendering favors reusing precomputed layout data to keep page turns responsive on constrained hardware
+- progress/session state is persisted so the reader can reopen at the last position after reboot/sleep
+
+## State and persistence
+
+Two singletons are central:
+
+- `src/CrossPointSettings.h` (`SETTINGS`): user preferences and behavior flags
+- `src/CrossPointState.h` (`APP_STATE`): runtime/session state such as current book and sleep context
+
+Typical persisted areas on SD:
+
+```text
+/.crosspoint/
+  epub_<hash>/
+    book.bin
+    progress.bin
+    cover.bmp
+    sections/*.bin
+  settings.bin
+  state.bin
+```
+
+For binary cache formats, see `docs/file-formats.md`.
+
+## Networking architecture
+
+Network file transfer is controlled by `src/activities/network/CrossPointWebServerActivity.h` and served by `src/network/CrossPointWebServer.h`.
+
+Modes:
+
+- STA: join existing WiFi network
+- AP: create hotspot
+
+Server behavior:
+
+- HTTP server on port 80
+- WebSocket upload server on port 81
+- file operations backed by SD storage
+- activity requests faster loop responsiveness while server is running
+
+Endpoint reference: `docs/webserver-endpoints.md`.
+
+## Build-time generated assets
+
+Some sources are generated and should not be edited manually.
+
+- `scripts/build_html.py` generates `src/network/html/*.generated.h` from HTML files
+- `scripts/generate_hyphenation_trie.py` generates hyphenation headers under `lib/Epub/Epub/hyphenation/generated/`
+
+When editing related source assets, regenerate via normal build steps/scripts.
+
+## Key directories
+
+- `src/`: app orchestration, settings/state, and activity implementations
+- `src/network/`: web server and OTA/update networking
+- `src/components/`: theming and shared UI components
+- `lib/Epub/`: EPUB parser, layout, CSS handling, and hyphenation
+- `lib/`: supporting libraries (fonts, text, filesystem helpers, etc.)
+- `open-x4-sdk/`: hardware SDK submodule (display, input, storage, battery)
+- `docs/`: user and technical documentation
+
+## Embedded constraints that shape design
+
+- constrained RAM drives SD-first caching and careful allocations
+- e-ink refresh cost drives render/update batching choices
+- main loop responsiveness matters for input, power handling, and watchdog safety
+- background/network flows must cooperate with sleep and loop timing logic
+
+## Scope guardrails
+
+Before implementing larger ideas, check:
+
+- [SCOPE.md](../../SCOPE.md)
+- [GOVERNANCE.md](../../GOVERNANCE.md)

docs/contributing/development-workflow.md

@@ -0,0 +1,43 @@
+# Development Workflow
+
+This page defines the expected local workflow before opening a pull request.
+
+## 1) Fork and create a focused branch
+
+- Fork the repository to your own GitHub account
+- Clone your fork locally and add the upstream repository if needed
+
+- Branch from `master`
+- Keep each PR focused on one fix or feature area
+
+## 2) Implement with scope in mind
+
+- Confirm your idea is in project scope: [SCOPE.md](../../SCOPE.md)
+- Prefer incremental changes over broad refactors
+
+## 3) Run local checks
+
+```sh
+./bin/clang-format-fix
+pio check --fail-on-defect low --fail-on-defect medium --fail-on-defect high
+pio run
+```
+
+CI enforces formatting, static analysis, and build checks.
+Use clang-format 21+ locally to match CI.
+If `clang-format` is missing or too old locally, see [Getting Started](./getting-started.md).
+
+## 4) Open the PR
+
+- Use a semantic title (example: `fix: avoid crash when opening malformed epub`)
+- Fill out `.github/PULL_REQUEST_TEMPLATE.md`
+- Describe the problem, approach, and any tradeoffs
+- Include reproduction and verification steps for bug fixes
+
+## 5) Review etiquette
+
+- Be explicit and concise in responses
+- Keep discussions technical and respectful
+- Assume good intent and focus on code-level feedback
+
+For community expectations, see [GOVERNANCE.md](../../GOVERNANCE.md).

docs/contributing/getting-started.md

@@ -0,0 +1,80 @@
+# Getting Started
+
+This guide helps you build and run CrossPoint locally.
+
+## Prerequisites
+
+- PlatformIO Core (`pio`) or VS Code + PlatformIO IDE
+- Python 3.8+
+- `clang-format` 21+ in your `PATH` (CI uses clang-format 21)
+- USB-C cable
+- Xteink X4 device for hardware testing
+
+If `./bin/clang-format-fix` fails with either of these errors, install clang-format 21:
+
+- `clang-format: No such file or directory`
+- `.clang-format: error: unknown key 'AlignFunctionDeclarations'`
+
+Examples:
+
+```sh
+# Debian/Ubuntu (try this first)
+sudo apt-get update && sudo apt-get install -y clang-format-21
+
+# If the package is unavailable, add LLVM apt repo and retry
+wget https://apt.llvm.org/llvm.sh
+chmod +x llvm.sh
+sudo ./llvm.sh 21
+sudo apt-get update
+sudo apt-get install -y clang-format-21
+
+# macOS (Homebrew)
+brew install clang-format
+```
+
+Then verify:
+
+```sh
+clang-format-21 --version
+```
+
+The reported major version must be 21 or newer.
+
+## Clone and initialize
+
+```sh
+git clone --recursive https://github.com/crosspoint-reader/crosspoint-reader
+cd crosspoint-reader
+```
+
+If you already cloned without submodules:
+
+```sh
+git submodule update --init --recursive
+```
+
+## Build
+
+```sh
+pio run
+```
+
+## Flash
+
+```sh
+pio run --target upload
+```
+
+## First checks before opening a PR
+
+```sh
+./bin/clang-format-fix
+pio check --fail-on-defect low --fail-on-defect medium --fail-on-defect high
+pio run
+```
+
+## What to read next
+
+- [Architecture Overview](./architecture.md)
+- [Development Workflow](./development-workflow.md)
+- [Testing and Debugging](./testing-debugging.md)

docs/contributing/testing-debugging.md

@@ -0,0 +1,48 @@
+# Testing and Debugging
+
+CrossPoint runs on real hardware, so debugging usually combines local build checks and on-device logs.
+
+## Local checks
+
+Make sure `clang-format` 21+ is installed and available in `PATH` before running the formatting step.
+If needed, see [Getting Started](./getting-started.md).
+
+```sh
+./bin/clang-format-fix
+pio check --fail-on-defect low --fail-on-defect medium --fail-on-defect high
+pio run
+```
+
+## Flash and monitor
+
+Flash firmware:
+
+```sh
+pio run --target upload
+```
+
+Open serial monitor:
+
+```sh
+pio device monitor
+```
+
+Optional enhanced monitor:
+
+```sh
+python3 -m pip install pyserial colorama matplotlib
+python3 scripts/debugging_monitor.py
+```
+
+## Useful bug report contents
+
+- Firmware version and build environment
+- Exact steps to reproduce
+- Expected vs actual behavior
+- Serial logs from boot through failure
+- Whether issue reproduces after clearing `.crosspoint/` cache on SD card
+
+## Common troubleshooting references
+
+- [User Guide troubleshooting section](../../USER_GUIDE.md#7-troubleshooting-issues--escaping-bootloop)
+- [Webserver troubleshooting](../troubleshooting.md)

docs/hyphenation-trie-format.md

@@ -0,0 +1,53 @@
+# Hypher Binary Tries
+
+CrossPoint embeds the exact binary automata produced by
+[Typst's `hypher`](https://github.com/typst/hypher). 
+
+## File layout
+
+Each `.bin` blob is a single self-contained automaton:
+
+```
+uint32_t root_addr_be;  // big-endian offset of the root node
+uint8_t  levels[];      // shared "levels" tape (dist/score pairs)
+uint8_t  nodes[];       // node records packed back-to-back
+```
+
+The size of the `levels` tape is implicit. Individual nodes reference slices
+inside that tape via 12-bit offsets, so no additional pointers are required.
+
+### Node encoding
+
+Every node starts with a single control byte:
+
+- Bit 7 – set when the node stores scores (`levels`).
+- Bits 5-6 – stride of the target deltas (1, 2, or 3 bytes, big-endian).
+- Bits 0-4 – transition count (values ≥ 31 spill into an extra byte).
+
+If the `levels` flag is set, two more bytes follow. Together they encode a
+12-bit offset into the global `levels` tape and a 4-bit length. Each byte in the
+levels tape packs a distance/score pair as `dist * 10 + score`, where `dist`
+counts how many UTF-8 bytes we advanced since the previous digit.
+
+After the optional levels header come the transition labels (one byte per edge)
+followed by the signed target deltas. Targets are stored as relative offsets
+from the current node address. Deltas up to ±128 fit in a single byte, larger
+distances grow to 2 or 3 bytes. The runtime walks the transitions with a simple
+linear scan and materializes the absolute address by adding the decoded delta
+to the current node’s base.
+
+## Embedding blobs into the firmware
+
+The helper script `scripts/generate_hyphenation_trie.py` acts as a thin
+wrapper: it reads the hypher-generated `.bin` files, formats them as `constexpr`
+byte arrays, and emits headers under
+`lib/Epub/Epub/hyphenation/generated/`. Each header defines the raw data plus a
+`SerializedHyphenationPatterns` descriptor so the reader can keep the automaton
+in flash.
+
+A convenient script `update_hyphenation.sh` is used to update all languages.
+To use it, run:
+
+```sh
+./scripts/update_hypenation.sh
+```

docs/i18n.md

@@ -0,0 +1,241 @@
+# Internationalization (I18N)
+
+This guide explains the multi-language support system in CrossPoint Reader.
+
+## Supported Languages
+
+- English
+- French
+- German
+- Portuguese
+- Spanish
+- Swedish
+- Czech
+- Russian
+- Ukrainian
+- Polish
+- Danish
+- Turkish
+
+---
+
+
+## For Developers
+
+### Translation System Architecture
+
+The I18N system uses **per-language YAML files** to maintain translations and a Python script to generate C++ code:
+
+```
+lib/I18n/
+├── translations/                # One YAML file per language
+│   ├── english.yaml
+│   ├── spanish.yaml
+│   ├── french.yaml
+│   └── ...
+├── I18n.h
+├── I18n.cpp
+├── I18nKeys.h                   # Enums (auto-generated)
+├── I18nStrings.h                # String array declarations (auto-generated)
+└── I18nStrings.cpp              # String array definitions (auto-generated)
+
+scripts/
+└── gen_i18n.py                  # Code generator script
+```
+
+**Key principle:** All translations are managed in the YAML files under `lib/I18n/translations/`. The Python script generates the necessary C++ code automatically.
+
+---
+
+### YAML File Format
+
+Each language has its own file in `lib/I18n/translations/` (e.g. `spanish.yaml`).
+
+A file looks like this:
+
+```yaml
+_language_name: "Español"
+_language_code: "ES"
+_order: "1"
+
+STR_CROSSPOINT: "CrossPoint"
+STR_BOOTING: "BOOTING"
+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)
+
+**Rules:**
+- Use UTF-8 encoding
+- Every line must follow the format: `KEY: "value"`
+- Keys must be valid C++ identifiers (uppercase, starts with STR_)
+- Keys must be unique within a file
+- String values must be quoted
+- Use `\n` for newlines, `\\` for literal backslashes, `\"` for literal quotes inside values
+
+---
+
+### Adding New Strings
+
+To add a new translatable string:
+
+#### 1. Edit the English YAML file
+
+Add the key to `lib/I18n/translations/english.yaml`:
+
+```yaml
+STR_MY_NEW_STRING: "My New String"
+```
+
+Then add translations in each language file. If a key is missing from a
+language file, the generator will automatically use the English text as a
+fallback (and print a warning).
+
+#### 2. Run the generator script
+
+```bash
+python3 scripts/gen_i18n.py lib/I18n/translations lib/I18n/
+```
+
+This automatically:
+- Fills missing translations from English
+- Updates the `StrId` enum in `I18nKeys.h`
+- Regenerates all language arrays in `I18nStrings.cpp`
+
+#### 3. Use in code
+
+```cpp
+#include <I18n.h>
+
+// Using the tr() macro (recommended)
+renderer.drawText(font, x, y, tr(STR_MY_NEW_STRING));
+
+// Using I18N.get() directly
+const char* text = I18N.get(StrId::STR_MY_NEW_STRING);
+```
+
+**That's it!** No manual array synchronization needed.
+
+---
+
+### Adding a New Language
+
+To add support for a new language (e.g., Italian):
+
+#### 1. Create a new YAML file
+
+Create `lib/I18n/translations/italian.yaml`:
+
+```yaml
+_language_name: "Italiano"
+_language_code: "IT"
+_order: "7"
+
+STR_CROSSPOINT: "CrossPoint"
+STR_BOOTING: "AVVIO"
+```
+
+You only need to include the strings you have translations for. Missing
+keys will fall back to English automatically.
+
+#### 2. Run the generator
+
+```bash
+python3 scripts/gen_i18n.py lib/I18n/translations lib/I18n/
+```
+
+This automatically updates all necessary code.
+
+---
+
+### Modifying Existing Translations
+
+Simply edit the relevant YAML file and regenerate:
+
+```bash
+python3 scripts/gen_i18n.py lib/I18n/translations lib/I18n/
+```
+
+---
+
+### UTF-8 Encoding
+
+The YAML files use UTF-8 encoding. Special characters are automatically converted to C++ UTF-8 hex sequences by the generator.
+
+---
+
+### I18N API Reference
+
+```cpp
+// === Convenience Macros (Recommended) ===
+
+// tr(id) - Get translated string without StrId:: prefix
+const char* text = tr(STR_SETTINGS_TITLE);
+renderer.drawText(font, x, y, tr(STR_BROWSE_FILES));
+Serial.printf("Status: %s\n", tr(STR_CONNECTED));
+
+// I18N - Shorthand for I18n::getInstance()
+I18N.setLanguage(Language::ES);
+Language lang = I18N.getLanguage();
+
+// === Full API ===
+
+// Get the singleton instance
+I18n& instance = I18n::getInstance();
+
+// Get translated string (three equivalent ways)
+const char* text = tr(STR_SETTINGS_TITLE);              // Macro (recommended)
+const char* text = I18N.get(StrId::STR_SETTINGS_TITLE);   // Direct call
+const char* text = I18N[StrId::STR_SETTINGS_TITLE];       // Operator overload
+
+// Set language
+I18N.setLanguage(Language::ES);
+
+// Get current language
+Language lang = I18N.getLanguage();
+
+// Save language setting to file
+I18N.saveSettings();
+
+// Load language setting from file
+I18N.loadSettings();
+
+// Get character set for font subsetting (static method)
+const char* chars = I18n::getCharacterSet(Language::FR);
+```
+
+---
+
+## File Storage
+
+Language settings are stored in:
+```
+/.crosspoint/language.bin
+```
+
+This file contains:
+- Version byte
+- Current language selection (1 byte)
+
+---
+
+## Translation Workflow
+
+### For Developers (Adding Features)
+
+1. Add new strings to `lib/I18n/translations/english.yaml`
+2. Run `python3 scripts/gen_i18n.py lib/I18n/translations lib/I18n/`
+3. Use the new `StrId` in your code
+4. Request translations from translators
+
+### For Translators
+
+1. Open the YAML file for your language in `lib/I18n/translations/`
+2. Add or update translations using the format `STR_KEY: "translated text"`
+3. Keep translations concise (E-ink space constraints)
+4. Make sure the file is in UTF-8 encoding
+5. Run `python3 scripts/gen_i18n.py lib/I18n/translations lib/I18n/` to verify
+6. Test on device or submit for review

docs/translators.md

@@ -0,0 +1,60 @@
+# Translators
+
+Below is a list of users and languages CrossPoint may support in the future.
+Note because a language is below does not mean there is official support for the language at this time.
+
+## Contributing
+
+If you'd like to add your name to this list, please open a PR adding yourself and your Github link. Thank you!
+
+## French
+- [Spigaw](https://github.com/Spigaw)
+- [CaptainFrito](https://github.com/CaptainFrito)
+
+## German
+- [DavidOrtmann](https://github.com/DavidOrtmann)
+
+## Czech
+- [brbla](https://github.com/brbla)
+
+## Portuguese (Brazil)
+- [yagofarias](https://github.com/yagofarias)
+
+## Portuguese (Portugal)
+- [victordomingos](https://github.com/victordomingos)
+
+## Italian
+- [andreaturchet](https://github.com/andreaturchet)
+- [fragolinux](https://github.com/fragolinux)
+
+## Russian
+- [madebyKir](https://github.com/madebyKir)
+- [mrtnvgr](https://github.com/mrtnvgr)
+
+## Spanish
+- [yeyeto2788](https://github.com/yeyeto2788)
+- [Skrzakk](https://github.com/Skrzakk)
+- [pablohc](https://github.com/pablohc)
+- [DaniPhii](https://github.com/DaniPhii)
+
+## Swedish
+- [dawiik](https://github.com/dawiik)
+- [steka](https://github.com/steka)
+
+## Romanian
+- [ariel-lindemann](https://github.com/ariel-lindemann)
+
+## Catalan
+- [angeldenom](https://github.com/angeldenom)
+
+## Finnish
+- [plahteenlahti](https://github.com/plahteenlahti)
+
+## Ukrainian
+- [mirus-ua](https://github.com/mirus-ua)
+
+## Belarusian
+- [Dexif](https://github.com/dexif)
+
+## Danish
+- [hajisan](https://github.com/hajisan)

docs/troubleshooting.md

@@ -0,0 +1,57 @@
+# Troubleshooting
+
+This document show most common issues and possible solutions while using the device features.
+
+- [Troubleshooting](#troubleshooting)
+    - [Cannot See the Device on the Network](#cannot-see-the-device-on-the-network)
+    - [Connection Drops or Times Out](#connection-drops-or-times-out)
+    - [Upload Fails](#upload-fails)
+    - [Saved Password Not Working](#saved-password-not-working)
+
+### Cannot See the Device on the Network
+
+**Problem:** Browser shows "Cannot connect" or "Site can't be reached"
+
+**Solutions:**
+
+1. Verify both devices are on the **same WiFi network**
+   - Check your computer/phone WiFi settings
+   - Confirm the CrossPoint Reader shows "Connected" status
+2. Double-check the IP address
+   - Make sure you typed it correctly
+   - Include `http://` at the beginning
+3. Try disabling VPN if you're using one
+4. Some networks have "client isolation" enabled - check with your network administrator
+
+### Connection Drops or Times Out
+
+**Problem:** WiFi connection is unstable
+
+**Solutions:**
+
+1. Move closer to the WiFi router
+2. Check signal strength on the device (should be at least `||` or better)
+3. Avoid interference from other devices
+4. Try a different WiFi network if available
+
+### Upload Fails
+
+**Problem:** File upload doesn't complete or shows an error
+
+**Solutions:**
+
+1. Ensure the file is a valid `.epub` file
+2. Check that the SD card has enough free space
+3. Try uploading a smaller file first to test
+4. Refresh the browser page and try again
+
+### Saved Password Not Working
+
+**Problem:** Device fails to connect with saved credentials
+
+**Solutions:**
+
+1. When connection fails, you'll be prompted to "Forget Network"
+2. Select **Yes** to remove the saved password
+3. Reconnect and enter the password again
+4. Choose to save the new password

docs/webserver-endpoints.md

@@ -0,0 +1,331 @@
+# Webserver Endpoints
+
+This document describes all HTTP and WebSocket endpoints available on the CrossPoint Reader webserver.
+
+- [Webserver Endpoints](#webserver-endpoints)
+  - [Overview](#overview)
+  - [HTTP Endpoints](#http-endpoints)
+    - [GET `/` - Home Page](#get----home-page)
+    - [GET `/files` - File Browser Page](#get-files---file-browser-page)
+    - [GET `/api/status` - Device Status](#get-apistatus---device-status)
+    - [GET `/api/files` - List Files](#get-apifiles---list-files)
+    - [POST `/upload` - Upload File](#post-upload---upload-file)
+    - [POST `/mkdir` - Create Folder](#post-mkdir---create-folder)
+    - [POST `/delete` - Delete File or Folder](#post-delete---delete-file-or-folder)
+  - [WebSocket Endpoint](#websocket-endpoint)
+    - [Port 81 - Fast Binary Upload](#port-81---fast-binary-upload)
+  - [Network Modes](#network-modes)
+    - [Station Mode (STA)](#station-mode-sta)
+    - [Access Point Mode (AP)](#access-point-mode-ap)
+  - [Notes](#notes)
+
+
+## Overview
+
+The CrossPoint Reader exposes a webserver for file management and device monitoring:
+
+- **HTTP Server**: Port 80
+- **WebSocket Server**: Port 81 (for fast binary uploads)
+
+---
+
+## HTTP Endpoints
+
+### GET `/` - Home Page
+
+Serves the home page HTML interface.
+
+**Request:**
+```bash
+curl http://crosspoint.local/
+```
+
+**Response:** HTML page (200 OK)
+
+---
+
+### GET `/files` - File Browser Page
+
+Serves the file browser HTML interface.
+
+**Request:**
+```bash
+curl http://crosspoint.local/files
+```
+
+**Response:** HTML page (200 OK)
+
+---
+
+### GET `/api/status` - Device Status
+
+Returns JSON with device status information.
+
+**Request:**
+```bash
+curl http://crosspoint.local/api/status
+```
+
+**Response (200 OK):**
+```json
+{
+  "version": "1.0.0",
+  "ip": "192.168.1.100",
+  "mode": "STA",
+  "rssi": -45,
+  "freeHeap": 123456,
+  "uptime": 3600
+}
+```
+
+| Field      | Type   | Description                                               |
+| ---------- | ------ | --------------------------------------------------------- |
+| `version`  | string | CrossPoint firmware version                               |
+| `ip`       | string | Device IP address                                         |
+| `mode`     | string | `"STA"` (connected to WiFi) or `"AP"` (access point mode) |
+| `rssi`     | number | WiFi signal strength in dBm (0 in AP mode)                |
+| `freeHeap` | number | Free heap memory in bytes                                 |
+| `uptime`   | number | Seconds since device boot                                 |
+
+---
+
+### GET `/api/files` - List Files
+
+Returns a JSON array of files and folders in the specified directory.
+
+**Request:**
+```bash
+# List root directory
+curl http://crosspoint.local/api/files
+
+# List specific directory
+curl "http://crosspoint.local/api/files?path=/Books"
+```
+
+**Query Parameters:**
+
+| Parameter | Required | Default | Description            |
+| --------- | -------- | ------- | ---------------------- |
+| `path`    | No       | `/`     | Directory path to list |
+
+**Response (200 OK):**
+```json
+[
+  {"name": "MyBook.epub", "size": 1234567, "isDirectory": false, "isEpub": true},
+  {"name": "Notes", "size": 0, "isDirectory": true, "isEpub": false},
+  {"name": "document.pdf", "size": 54321, "isDirectory": false, "isEpub": false}
+]
+```
+
+| Field         | Type    | Description                              |
+| ------------- | ------- | ---------------------------------------- |
+| `name`        | string  | File or folder name                      |
+| `size`        | number  | Size in bytes (0 for directories)        |
+| `isDirectory` | boolean | `true` if the item is a folder           |
+| `isEpub`      | boolean | `true` if the file has `.epub` extension |
+
+**Notes:**
+- Hidden files (starting with `.`) are automatically filtered out
+- System folders (`System Volume Information`, `XTCache`) are hidden
+
+---
+
+### POST `/upload` - Upload File
+
+Uploads a file to the SD card via multipart form data.
+
+**Request:**
+```bash
+# Upload to root directory
+curl -X POST -F "file=@mybook.epub" http://crosspoint.local/upload
+
+# Upload to specific directory
+curl -X POST -F "file=@mybook.epub" "http://crosspoint.local/upload?path=/Books"
+```
+
+**Query Parameters:**
+
+| Parameter | Required | Default | Description                     |
+| --------- | -------- | ------- | ------------------------------- |
+| `path`    | No       | `/`     | Target directory for the upload |
+
+**Response (200 OK):**
+```
+File uploaded successfully: mybook.epub
+```
+
+**Error Responses:**
+
+| Status | Body                                            | Cause                       |
+| ------ | ----------------------------------------------- | --------------------------- |
+| 400    | `Failed to create file on SD card`              | Cannot create file          |
+| 400    | `Failed to write to SD card - disk may be full` | Write error during upload   |
+| 400    | `Failed to write final data to SD card`         | Error flushing final buffer |
+| 400    | `Upload aborted`                                | Client aborted the upload   |
+| 400    | `Unknown error during upload`                   | Unspecified error           |
+
+**Notes:**
+- Existing files with the same name will be overwritten
+- Uses a 4KB buffer for efficient SD card writes
+
+---
+
+### POST `/mkdir` - Create Folder
+
+Creates a new folder on the SD card.
+
+**Request:**
+```bash
+curl -X POST -d "name=NewFolder&path=/" http://crosspoint.local/mkdir
+```
+
+**Form Parameters:**
+
+| Parameter | Required | Default | Description                  |
+| --------- | -------- | ------- | ---------------------------- |
+| `name`    | Yes      | -       | Name of the folder to create |
+| `path`    | No       | `/`     | Parent directory path        |
+
+**Response (200 OK):**
+```
+Folder created: NewFolder
+```
+
+**Error Responses:**
+
+| Status | Body                          | Cause                         |
+| ------ | ----------------------------- | ----------------------------- |
+| 400    | `Missing folder name`         | `name` parameter not provided |
+| 400    | `Folder name cannot be empty` | Empty folder name             |
+| 400    | `Folder already exists`       | Folder with same name exists  |
+| 500    | `Failed to create folder`     | SD card error                 |
+
+---
+
+### POST `/delete` - Delete File or Folder
+
+Deletes a file or folder from the SD card.
+
+**Request:**
+```bash
+# Delete a file
+curl -X POST -d "path=/Books/mybook.epub&type=file" http://crosspoint.local/delete
+
+# Delete an empty folder
+curl -X POST -d "path=/OldFolder&type=folder" http://crosspoint.local/delete
+```
+
+**Form Parameters:**
+
+| Parameter | Required | Default | Description                      |
+| --------- | -------- | ------- | -------------------------------- |
+| `path`    | Yes      | -       | Path to the item to delete       |
+| `type`    | No       | `file`  | Type of item: `file` or `folder` |
+
+**Response (200 OK):**
+```
+Deleted successfully
+```
+
+**Error Responses:**
+
+| Status | Body                                          | Cause                         |
+| ------ | --------------------------------------------- | ----------------------------- |
+| 400    | `Missing path`                                | `path` parameter not provided |
+| 400    | `Cannot delete root directory`                | Attempted to delete `/`       |
+| 400    | `Folder is not empty. Delete contents first.` | Non-empty folder              |
+| 403    | `Cannot delete system files`                  | Hidden file (starts with `.`) |
+| 403    | `Cannot delete protected items`               | Protected system folder       |
+| 404    | `Item not found`                              | Path does not exist           |
+| 500    | `Failed to delete item`                       | SD card error                 |
+
+**Protected Items:**
+- Files/folders starting with `.`
+- `System Volume Information`
+- `XTCache`
+
+---
+
+## WebSocket Endpoint
+
+### Port 81 - Fast Binary Upload
+
+A WebSocket endpoint for high-speed binary file uploads. More efficient than HTTP multipart for large files.
+
+**Connection:**
+```
+ws://crosspoint.local:81/
+```
+
+**Protocol:**
+
+1. **Client** sends TEXT message: `START:<filename>:<size>:<path>`
+2. **Server** responds with TEXT: `READY`
+3. **Client** sends BINARY messages with file data chunks
+4. **Server** sends TEXT progress updates: `PROGRESS:<received>:<total>`
+5. **Server** sends TEXT when complete: `DONE` or `ERROR:<message>`
+
+**Example Session:**
+
+```
+Client -> "START:mybook.epub:1234567:/Books"
+Server -> "READY"
+Client -> [binary chunk 1]
+Client -> [binary chunk 2]
+Server -> "PROGRESS:65536:1234567"
+Client -> [binary chunk 3]
+...
+Server -> "PROGRESS:1234567:1234567"
+Server -> "DONE"
+```
+
+**Error Messages:**
+
+| Message                           | Cause                              |
+| --------------------------------- | ---------------------------------- |
+| `ERROR:Failed to create file`     | Cannot create file on SD card      |
+| `ERROR:Invalid START format`      | Malformed START message            |
+| `ERROR:No upload in progress`     | Binary data received without START |
+| `ERROR:Write failed - disk full?` | SD card write error                |
+
+**Example with `websocat`:**
+```bash
+# Interactive session
+websocat ws://crosspoint.local:81
+
+# Then type:
+START:mybook.epub:1234567:/Books
+# Wait for READY, then send binary data
+```
+
+**Notes:**
+- Progress updates are sent every 64KB or at completion
+- Disconnection during upload will delete the incomplete file
+- Existing files with the same name will be overwritten
+
+---
+
+## Network Modes
+
+The device can operate in two network modes:
+
+### Station Mode (STA)
+- Device connects to an existing WiFi network
+- IP address assigned by router/DHCP
+- `mode` field in `/api/status` returns `"STA"`
+- `rssi` field shows signal strength
+
+### Access Point Mode (AP)
+- Device creates its own WiFi hotspot
+- Default IP is typically `192.168.4.1`
+- `mode` field in `/api/status` returns `"AP"`
+- `rssi` field returns `0`
+
+---
+
+## Notes
+
+- These examples use `crosspoint.local`. If your network does not support mDNS or the address does not resolve, replace it with the specific **IP Address** displayed on your device screen (e.g., `http://192.168.1.102/`).
+- All paths on the SD card start with `/`
+- Trailing slashes are automatically stripped (except for root `/`)
+- The webserver uses chunked transfer encoding for file listings

docs/webserver.md

@@ -1,14 +1,14 @@
 # Web Server Guide
 
-This guide explains how to connect your CrossPoint Reader to WiFi and use the built-in web server to upload EPUB files from your computer or phone.
+This guide explains how to connect your CrossPoint Reader to WiFi and use the built-in web server to upload files from your computer or phone.
 
 ## Overview
 
 CrossPoint Reader includes a built-in web server that allows you to:
 
-- Upload EPUB files wirelessly from any device on the same WiFi network
+- Upload files wirelessly from any device on the same WiFi network
 - Browse and manage files on your device's SD card
-- Create folders to organize your ebooks
+- Create folders to organize your library
 - Delete files and folders
 
 ## Prerequisites
@@ -129,34 +129,31 @@ Click **File Manager** to access file management features.
 #### Browsing Files
 
 - The file manager displays all files and folders on your SD card
-- **Folders** are highlighted in yellow with a 📁 icon
-- **EPUB files** are highlighted in green with a 📗 icon
+- **Folders** are highlighted in yellow and indicated with a 📁 icon
+- **EPUB Files** are highlighted in green and indicated with a 📗 icon
+- **All Other Files** are not highlighted and indicated with a 📄 icon
 - Click on a folder name to navigate into it
 - Use the breadcrumb navigation at the top to go back to parent folders
 
 <img src="./images/wifi/webserver_files.png" width="600">
 
-#### Uploading EPUB Files
+#### Uploading Files
 
-1. Click the **+ Add** button in the top-right corner
-2. Select **Upload eBook** from the dropdown menu
-3. Click **Choose File** and select an `.epub` file from your device
-4. Click **Upload**
-5. A progress bar will show the upload status
-6. The page will automatically refresh when the upload is complete
-
-**Note:** Only `.epub` files are accepted. Other file types will be rejected.
+1. Click the **📤 Upload** button in the top-right corner
+2. Click **Choose File** and select a file from your device
+3. Click **Upload**
+4. A progress bar will show the upload status
+5. The page will automatically refresh when the upload is complete
 
 <img src="./images/wifi/webserver_upload.png" width="600">
 
 #### Creating Folders
 
-1. Click the **+ Add** button in the top-right corner
-2. Select **New Folder** from the dropdown menu
-3. Enter a folder name (letters, numbers, underscores, and hyphens only)
-4. Click **Create Folder**
+1. Click the **📁 New Folder** button in the top-right corner
+2. Enter a folder name (must not contain characters \" * : < > ? / \\ | and must not be . or ..)
+3. Click **Create Folder**
 
-This is useful for organizing your ebooks by genre, author, or series.
+This is useful for organizing your library by genre, author, series or file type.
 
 #### Deleting Files and Folders
 
@@ -168,93 +165,25 @@ This is useful for organizing your ebooks by genre, author, or series.
 
 **Note:** Folders must be empty before they can be deleted.
 
+#### Moving Files
+
+1. Click the **📂** (folder) icon next to any file
+2. Enter a folder name or select one from the dropdown
+3. Click **Move** to relocate the file
+
+**Note:** Typing in a nonexistent folder name will result in the following error: "Failed to move: Destination not found"
+
+#### Renaming Files
+
+1. Click the **✏️** (pencil) icon next to any file
+2. Enter a file name (must not contain characters \" * : < > ? / \\ | and must not be . or ..)
+3. Click **Rename** to permanently rename the file
+
 ---
 
 ## Command Line File Management
 
-For power users, you can manage files directly from your terminal using `curl` while the device is in File Upload mode. 
-
-### Uploading a File
-To upload a file to the root directory, use the following command:
-```bash
-curl -F "file=@book.epub" "http://crosspoint.local/upload?path=/"
-```
-
-* **`-F "file=@filename"`**: Points to the local file on your computer.
-* **`path=/`**: The destination folder on the device SD card.
-
-### Deleting a File
-
-To delete a specific file, provide the full path on the SD card:
-
-```bash
-curl -F "path=/folder/file.epub" "http://crosspoint.local/delete"
-```
-
-### Advanced Flags
-
-For more reliable transfers of large EPUB files, consider adding these flags:
-
-* `-#`: Shows a simple progress bar.
-* `--connect-timeout 30`: Limits how long curl waits to establish a connection (in seconds).
-* `--max-time 300`: Sets a maximum duration for the entire transfer (5 minutes).
-
-> [!NOTE]
-> These examples use `crosspoint.local`. If your network does not support mDNS or the address does not resolve, replace it with the specific **IP Address** displayed on your device screen (e.g., `http://192.168.1.102/`).
-
----
-
-## Troubleshooting
-
-### Cannot See the Device on the Network
-
-**Problem:** Browser shows "Cannot connect" or "Site can't be reached"
-
-**Solutions:**
-
-1. Verify both devices are on the **same WiFi network**
-   - Check your computer/phone WiFi settings
-   - Confirm the CrossPoint Reader shows "Connected" status
-2. Double-check the IP address
-   - Make sure you typed it correctly
-   - Include `http://` at the beginning
-3. Try disabling VPN if you're using one
-4. Some networks have "client isolation" enabled - check with your network administrator
-
-### Connection Drops or Times Out
-
-**Problem:** WiFi connection is unstable
-
-**Solutions:**
-
-1. Move closer to the WiFi router
-2. Check signal strength on the device (should be at least `||` or better)
-3. Avoid interference from other devices
-4. Try a different WiFi network if available
-
-### Upload Fails
-
-**Problem:** File upload doesn't complete or shows an error
-
-**Solutions:**
-
-1. Ensure the file is a valid `.epub` file
-2. Check that the SD card has enough free space
-3. Try uploading a smaller file first to test
-4. Refresh the browser page and try again
-
-### Saved Password Not Working
-
-**Problem:** Device fails to connect with saved credentials
-
-**Solutions:**
-
-1. When connection fails, you'll be prompted to "Forget Network"
-2. Select **Yes** to remove the saved password
-3. Reconnect and enter the password again
-4. Choose to save the new password
-
----
+For power users, you can manage files directly from your terminal using `curl` while the device is in File Upload mode. Detailed documentation can be found [here](./webserver-endpoints.md). 
 
 ## Security Notes
 
@@ -271,7 +200,6 @@ For more reliable transfers of large EPUB files, consider adding these flags:
 - **Supported WiFi:** 2.4GHz networks (802.11 b/g/n)
 - **Web Server Port:** 80 (HTTP)
 - **Maximum Upload Size:** Limited by available SD card space
-- **Supported File Format:** `.epub` only
 - **Browser Compatibility:** All modern browsers (Chrome, Firefox, Safari, Edge)
 
 ---
@@ -280,7 +208,7 @@ For more reliable transfers of large EPUB files, consider adding these flags:
 
 1. **Organize with folders** - Create folders before uploading to keep your library organized
 2. **Check signal strength** - Stronger signals (`|||` or `||||`) provide faster, more reliable uploads
-3. **Upload multiple files** - You can upload files one at a time; the page refreshes after each upload
+3. **Upload multiple files** - You can select and upload multiple files at once; the manager will queue them and refresh when the batch is finished
 4. **Use descriptive names** - Name your folders clearly (e.g., "SciFi", "Mystery", "Non-Fiction")
 5. **Keep credentials saved** - Save your WiFi password for quick reconnection in the future
 6. **Exit when done** - Press **Back** to exit the WiFi screen and save battery
@@ -303,4 +231,5 @@ Your uploaded files will be immediately available in the file browser!
 ## Related Documentation
 
 - [User Guide](../USER_GUIDE.md) - General device operation
+- [Troubleshooting](./troubleshooting.md) - Troubleshooting
 - [README](../README.md) - Project overview and features

include/README

@@ -1,37 +0,0 @@
-
-This directory is intended for project header files.
-
-A header file is a file containing C declarations and macro definitions
-to be shared between several project source files. You request the use of a
-header file in your project source file (C, C++, etc) located in `src` folder
-by including it, with the C preprocessing directive `#include'.
-
-```src/main.c
-
-#include "header.h"
-
-int main (void)
-{
- ...
-}
-```
-
-Including a header file produces the same results as copying the header file
-into each source file that needs it. Such copying would be time-consuming
-and error-prone. With a header file, the related declarations appear
-in only one place. If they need to be changed, they can be changed in one
-place, and programs that include the header file will automatically use the
-new version when next recompiled. The header file eliminates the labor of
-finding and changing all the copies as well as the risk that a failure to
-find one copy will result in inconsistencies within a program.
-
-In C, the convention is to give header files names that end with `.h'.
-
-Read more about using header files in official GCC documentation:
-
-* Include Syntax
-* Include Operation
-* Once-Only Headers
-* Computed Includes
-
-https://gcc.gnu.org/onlinedocs/cpp/Header-Files.html

lib/EpdFont/EpdFont.cpp

@@ -15,27 +15,54 @@ void EpdFont::getTextBounds(const char* string, const int startX, const int star
     return;
   }
 
-  int cursorX = startX;
-  const int cursorY = startY;
+  int32_t cursorXFP = fp4::fromPixel(startX);  // 12.4 fixed-point accumulator
+  int lastBaseX = startX;
+  int lastBaseAdvanceFP = 0;  // 12.4 fixed-point
+  int lastBaseTop = 0;
+  constexpr int MIN_COMBINING_GAP_PX = 1;
   uint32_t cp;
+  uint32_t prevCp = 0;
   while ((cp = utf8NextCodepoint(reinterpret_cast<const uint8_t**>(&string)))) {
-    const EpdGlyph* glyph = getGlyph(cp);
+    const bool isCombining = utf8IsCombiningMark(cp);
 
-    if (!glyph) {
-      // TODO: Replace with fallback glyph property?
-      glyph = getGlyph('?');
+    if (!isCombining) {
+      cp = applyLigatures(cp, string);
     }
 
+    const EpdGlyph* glyph = getGlyph(cp);
     if (!glyph) {
-      // TODO: Better handle this?
+      prevCp = 0;
       continue;
     }
 
-    *minX = std::min(*minX, cursorX + glyph->left);
-    *maxX = std::max(*maxX, cursorX + glyph->left + glyph->width);
-    *minY = std::min(*minY, cursorY + glyph->top - glyph->height);
-    *maxY = std::max(*maxY, cursorY + glyph->top);
-    cursorX += glyph->advanceX;
+    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;
+      }
+    }
+
+    if (!isCombining && prevCp != 0) {
+      cursorXFP += getKerning(prevCp, cp);  // 4.4 fixed-point kern
+    }
+
+    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 glyphBaseY = startY - raiseBy;
+
+    *minX = std::min(*minX, glyphBaseX + glyph->left);
+    *maxX = std::max(*maxX, glyphBaseX + glyph->left + glyph->width);
+    *minY = std::min(*minY, glyphBaseY + glyph->top - glyph->height);
+    *maxY = std::max(*maxY, glyphBaseY + glyph->top);
+
+    if (!isCombining) {
+      lastBaseX = cursorXPixels;
+      lastBaseAdvanceFP = glyph->advanceX;  // 12.4 fixed-point
+      lastBaseTop = glyph->top;
+      cursorXFP += glyph->advanceX;  // 12.4 fixed-point advance
+      prevCp = cp;
+    }
   }
 }
 
@@ -48,38 +75,99 @@ void EpdFont::getTextDimensions(const char* string, int* w, int* h) const {
   *h = maxY - minY;
 }
 
-bool EpdFont::hasPrintableChars(const char* string) const {
-  int w = 0, h = 0;
+static uint8_t lookupKernClass(const EpdKernClassEntry* entries, const uint16_t count, const uint32_t cp) {
+  if (!entries || count == 0 || cp > 0xFFFF) {
+    return 0;
+  }
 
-  getTextDimensions(string, &w, &h);
+  const auto target = static_cast<uint16_t>(cp);
+  const auto* end = entries + count;
 
-  return w > 0 || h > 0;
+  // lower_bound: exact-key lookup. Finds the first entry with codepoint >= target,
+  // then the equality check confirms an exact match exists.
+  const auto it = std::lower_bound(
+      entries, end, target, [](const EpdKernClassEntry& entry, uint16_t value) { return entry.codepoint < value; });
+
+  if (it != end && it->codepoint == target) {
+    return it->classId;
+  }
+
+  return 0;
+}
+
+int8_t EpdFont::getKerning(const uint32_t leftCp, const uint32_t rightCp) const {
+  if (!data->kernMatrix) {
+    return 0;
+  }
+  const uint8_t lc = lookupKernClass(data->kernLeftClasses, data->kernLeftEntryCount, leftCp);
+  if (lc == 0) return 0;
+  const uint8_t rc = lookupKernClass(data->kernRightClasses, data->kernRightEntryCount, rightCp);
+  if (rc == 0) return 0;
+  return data->kernMatrix[(lc - 1) * data->kernRightClassCount + (rc - 1)];
+}
+
+uint32_t EpdFont::getLigature(const uint32_t leftCp, const uint32_t rightCp) const {
+  const auto* pairs = data->ligaturePairs;
+  const auto count = data->ligaturePairCount;
+  if (!pairs || count == 0 || leftCp > 0xFFFF || rightCp > 0xFFFF) {
+    return 0;
+  }
+
+  const uint32_t key = (leftCp << 16) | rightCp;
+  const auto* end = pairs + count;
+
+  // lower_bound: exact-key lookup. Finds the first entry with pair >= key,
+  // then the equality check confirms an exact match exists.
+  const auto it =
+      std::lower_bound(pairs, end, key, [](const EpdLigaturePair& pair, uint32_t value) { return pair.pair < value; });
+
+  if (it != end && it->pair == key) {
+    return it->ligatureCp;
+  }
+
+  return 0;
+}
+
+uint32_t EpdFont::applyLigatures(uint32_t cp, const char*& text) const {
+  if (!data->ligaturePairs || data->ligaturePairCount == 0) {
+    return cp;
+  }
+  while (true) {
+    const auto saved = reinterpret_cast<const uint8_t*>(text);
+    const uint32_t nextCp = utf8NextCodepoint(reinterpret_cast<const uint8_t**>(&text));
+    if (nextCp == 0) break;
+    const uint32_t lig = getLigature(cp, nextCp);
+    if (lig == 0) {
+      text = reinterpret_cast<const char*>(saved);
+      break;
+    }
+    cp = lig;
+  }
+  return cp;
 }
 
 const EpdGlyph* EpdFont::getGlyph(const uint32_t cp) const {
-  const EpdUnicodeInterval* intervals = data->intervals;
   const int count = data->intervalCount;
-
   if (count == 0) return nullptr;
 
-  // Binary search for O(log n) lookup instead of O(n)
-  // Critical for Korean fonts with many unicode intervals
-  int left = 0;
-  int right = count - 1;
+  const EpdUnicodeInterval* intervals = data->intervals;
+  const auto* end = intervals + count;
 
-  while (left <= right) {
-    const int mid = left + (right - left) / 2;
-    const EpdUnicodeInterval* interval = &intervals[mid];
+  // upper_bound: range lookup. Finds the first interval with first > cp, so the
+  // interval just before it is the last one with first <= cp. That's the only
+  // candidate that could contain cp. Then we verify cp <= candidate.last.
+  const auto it = std::upper_bound(
+      intervals, end, cp, [](uint32_t value, const EpdUnicodeInterval& interval) { return value < interval.first; });
 
-    if (cp < interval->first) {
-      right = mid - 1;
-    } else if (cp > interval->last) {
-      left = mid + 1;
-    } else {
-      // Found: cp >= interval->first && cp <= interval->last
-      return &data->glyph[interval->offset + (cp - interval->first)];
+  if (it != intervals) {
+    const auto& interval = *(it - 1);
+    if (cp <= interval.last) {
+      return &data->glyph[interval.offset + (cp - interval.first)];
     }
   }
 
+  if (cp != REPLACEMENT_GLYPH) {
+    return getGlyph(REPLACEMENT_GLYPH);
+  }
   return nullptr;
 }

lib/EpdFont/EpdFont.h

@@ -9,7 +9,18 @@ class EpdFont {
   explicit EpdFont(const EpdFontData* data) : data(data) {}
   ~EpdFont() = default;
   void getTextDimensions(const char* string, int* w, int* h) const;
-  bool hasPrintableChars(const char* string) const;
 
   const EpdGlyph* getGlyph(uint32_t cp) const;
+
+  /// Returns the kerning adjustment (4.4 fixed-point in pixels) between two codepoints.
+  /// Returns 0 if no kerning data exists for the pair.
+  int8_t getKerning(uint32_t leftCp, uint32_t rightCp) const;
+
+  /// Returns the ligature codepoint for a pair, or 0 if no ligature exists.
+  uint32_t getLigature(uint32_t leftCp, uint32_t rightCp) const;
+
+  /// Greedily applies ligature substitutions starting from cp, consuming
+  /// as many following codepoints from text as possible. Returns the
+  /// (possibly substituted) codepoint; advances text past consumed chars.
+  uint32_t applyLigatures(uint32_t cp, const char*& text) const;
 };

lib/EpdFont/EpdFontData.h

@@ -4,17 +4,55 @@
 #pragma once
 #include <cstdint>
 
+/// 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.
+///
+/// The helpers below eliminate the raw bit-shifts that would otherwise be
+/// scattered across every layout / measurement call site.
+namespace fp4 {
+constexpr int FRAC_BITS = 4;
+constexpr int32_t HALF = 1 << (FRAC_BITS - 1);  // 8, added before shift for round-to-nearest
+
+/// Convert an integer pixel value to 12.4 fixed-point.
+constexpr int32_t fromPixel(int px) { return static_cast<int32_t>(px) << FRAC_BITS; }
+
+/// Snap a fixed-point value to the nearest integer pixel.
+constexpr int toPixel(int32_t fp) { return static_cast<int>((fp + HALF) >> FRAC_BITS); }
+
+/// Convert a fixed-point value to float (mainly useful for debug logging).
+constexpr float toFloat(int32_t fp) { return fp / static_cast<float>(1 << FRAC_BITS); }
+}  // namespace fp4
+
+/// 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)
+/// Both share 4 fractional bits so they combine directly in an accumulator.
+
 /// Font data stored PER GLYPH
 typedef struct {
   uint8_t width;        ///< Bitmap dimensions in pixels
   uint8_t height;       ///< Bitmap dimensions in pixels
-  uint8_t advanceX;     ///< Distance to advance cursor (x axis)
+  uint16_t advanceX;    ///< Distance to advance cursor (x axis), 12.4 fixed-point in pixels
   int16_t left;         ///< X dist from cursor pos to UL corner
   int16_t top;          ///< Y dist from cursor pos to UL corner
   uint16_t dataLength;  ///< Size of the font data.
-  uint32_t dataOffset;  ///< Pointer into EpdFont->bitmap
+  uint32_t dataOffset;  ///< Pointer into EpdFont->bitmap (or within-group offset for compressed fonts)
 } EpdGlyph;
 
+/// Compressed font group: a DEFLATE-compressed block of glyph bitmaps
+typedef struct {
+  uint32_t compressedOffset;  ///< Byte offset into compressed data array
+  uint32_t compressedSize;    ///< Compressed DEFLATE stream size
+  uint32_t uncompressedSize;  ///< Decompressed size
+  uint16_t glyphCount;        ///< Number of glyphs in this group
+  uint32_t firstGlyphIndex;   ///< First glyph index in the global glyph array
+} EpdFontGroup;
+
 /// Glyph interval structure
 typedef struct {
   uint32_t first;   ///< The first unicode code point of the interval
@@ -22,6 +60,20 @@ typedef struct {
   uint32_t offset;  ///< Index of the first code point into the glyph array
 } EpdUnicodeInterval;
 
+/// Maps a codepoint to a kerning class ID, sorted by codepoint for binary search.
+/// Class IDs are 1-based; codepoints not in the table have implicit class 0 (no kerning).
+typedef struct {
+  uint16_t codepoint;  ///< Unicode codepoint
+  uint8_t classId;     ///< 1-based kerning class ID
+} __attribute__((packed)) EpdKernClassEntry;
+
+/// Ligature substitution for a specific glyph pair, sorted by `pair` for binary search.
+/// `pair` encodes (leftCodepoint << 16 | rightCodepoint) for single-key lookup.
+typedef struct {
+  uint32_t pair;        ///< Packed codepoint pair (left << 16 | right)
+  uint32_t ligatureCp;  ///< Codepoint of the replacement ligature glyph
+} __attribute__((packed)) EpdLigaturePair;
+
 /// Data stored for FONT AS A WHOLE
 typedef struct {
   const uint8_t* bitmap;                ///< Glyph bitmaps, concatenated
@@ -32,4 +84,16 @@ typedef struct {
   int ascender;                         ///< Maximal height of a glyph above the base line
   int descender;                        ///< Maximal height of a glyph below the base line
   bool is2Bit;
+  const EpdFontGroup* groups;                 ///< NULL for uncompressed fonts
+  uint16_t groupCount;                        ///< 0 for uncompressed fonts
+  const uint16_t* glyphToGroup;               ///< Per-glyph group ID (nullptr for contiguous-group fonts)
+  const EpdKernClassEntry* kernLeftClasses;   ///< Sorted left-side class map (nullptr if none)
+  const EpdKernClassEntry* kernRightClasses;  ///< Sorted right-side class map (nullptr if none)
+  const int8_t* kernMatrix;              ///< Flat leftClassCount x rightClassCount matrix, 4.4 fixed-point in pixels
+  uint16_t kernLeftEntryCount;           ///< Entries in kernLeftClasses
+  uint16_t kernRightEntryCount;          ///< Entries in kernRightClasses
+  uint8_t kernLeftClassCount;            ///< Number of distinct left classes (matrix rows)
+  uint8_t kernRightClassCount;           ///< Number of distinct right classes (matrix cols)
+  const EpdLigaturePair* ligaturePairs;  ///< Sorted ligature pair table (nullptr if none)
+  uint32_t ligaturePairCount;            ///< Number of entries in ligaturePairs
 } EpdFontData;

lib/EpdFont/EpdFontFamily.cpp

@@ -1,23 +1,19 @@
 #include "EpdFontFamily.h"
 
 const EpdFont* EpdFontFamily::getFont(const Style style) const {
-  if (style == BOLD && bold) {
+  // Extract font style bits (ignore UNDERLINE bit for font selection)
+  const bool hasBold = (style & BOLD) != 0;
+  const bool hasItalic = (style & ITALIC) != 0;
+
+  if (hasBold && hasItalic) {
+    if (boldItalic) return boldItalic;
+    if (bold) return bold;
+    if (italic) return italic;
+  } else if (hasBold && bold) {
     return bold;
-  }
-  if (style == ITALIC && italic) {
+  } else if (hasItalic && italic) {
     return italic;
   }
-  if (style == BOLD_ITALIC) {
-    if (boldItalic) {
-      return boldItalic;
-    }
-    if (bold) {
-      return bold;
-    }
-    if (italic) {
-      return italic;
-    }
-  }
 
   return regular;
 }
@@ -26,12 +22,16 @@ void EpdFontFamily::getTextDimensions(const char* string, int* w, int* h, const
   getFont(style)->getTextDimensions(string, w, h);
 }
 
-bool EpdFontFamily::hasPrintableChars(const char* string, const Style style) const {
-  return getFont(style)->hasPrintableChars(string);
-}
-
 const EpdFontData* EpdFontFamily::getData(const Style style) const { return getFont(style)->data; }
 
 const EpdGlyph* EpdFontFamily::getGlyph(const uint32_t cp, const Style style) const {
   return getFont(style)->getGlyph(cp);
-};
+}
+
+int8_t EpdFontFamily::getKerning(const uint32_t leftCp, const uint32_t rightCp, const Style style) const {
+  return getFont(style)->getKerning(leftCp, rightCp);
+}
+
+uint32_t EpdFontFamily::applyLigatures(const uint32_t cp, const char*& text, const Style style) const {
+  return getFont(style)->applyLigatures(cp, text);
+}

lib/EpdFont/EpdFontFamily.h

@@ -3,16 +3,17 @@
 
 class EpdFontFamily {
  public:
-  enum Style : uint8_t { REGULAR = 0, BOLD = 1, ITALIC = 2, BOLD_ITALIC = 3 };
+  enum Style : uint8_t { REGULAR = 0, BOLD = 1, ITALIC = 2, BOLD_ITALIC = 3, UNDERLINE = 4 };
 
   explicit EpdFontFamily(const EpdFont* regular, const EpdFont* bold = nullptr, const EpdFont* italic = nullptr,
                          const EpdFont* boldItalic = nullptr)
       : regular(regular), bold(bold), italic(italic), boldItalic(boldItalic) {}
   ~EpdFontFamily() = default;
   void getTextDimensions(const char* string, int* w, int* h, Style style = REGULAR) const;
-  bool hasPrintableChars(const char* string, Style style = REGULAR) const;
   const EpdFontData* getData(Style style = REGULAR) const;
   const EpdGlyph* getGlyph(uint32_t cp, Style style = REGULAR) const;
+  int8_t getKerning(uint32_t leftCp, uint32_t rightCp, Style style = REGULAR) const;
+  uint32_t applyLigatures(uint32_t cp, const char*& text, Style style = REGULAR) const;
 
  private:
   const EpdFont* regular;

lib/EpdFont/FontDecompressor.cpp

@@ -0,0 +1,481 @@
+#include "FontDecompressor.h"
+
+#include <Arduino.h>
+#include <Logging.h>
+#include <Utf8.h>
+
+#include <cstdlib>
+
+FontDecompressor::~FontDecompressor() { deinit(); }
+
+bool FontDecompressor::init() {
+  clearCache();
+  return true;
+}
+
+void FontDecompressor::deinit() {
+  freePageBuffer();
+  freeHotGroup();
+}
+
+void FontDecompressor::clearCache() {
+  freePageBuffer();
+  freeHotGroup();
+}
+
+void FontDecompressor::freePageBuffer() {
+  for (uint8_t s = 0; s < pageSlotCount; s++) {
+    free(pageSlots[s].buffer);
+    free(pageSlots[s].glyphs);
+    pageSlots[s] = {};
+  }
+  pageSlotCount = 0;
+}
+
+void FontDecompressor::freeHotGroup() {
+  hotGroup.clear();
+  hotGroup.shrink_to_fit();
+  hotGroupFont = nullptr;
+  hotGroupIndex = UINT16_MAX;
+  hotGlyphBuf.clear();
+  hotGlyphBuf.shrink_to_fit();
+}
+
+uint16_t FontDecompressor::getGroupIndex(const EpdFontData* fontData, uint32_t glyphIndex) {
+  // O(1) path for frequency-grouped fonts with glyphToGroup mapping
+  if (fontData->glyphToGroup != nullptr) {
+    return fontData->glyphToGroup[glyphIndex];
+  }
+
+  // Contiguous-group fonts: linear scan
+  for (uint16_t i = 0; i < fontData->groupCount; i++) {
+    uint32_t first = fontData->groups[i].firstGlyphIndex;
+    if (glyphIndex >= first && glyphIndex < first + fontData->groups[i].glyphCount) {
+      return i;
+    }
+  }
+  return fontData->groupCount;  // sentinel = not found
+}
+
+bool FontDecompressor::decompressGroup(const EpdFontData* fontData, uint16_t groupIndex, uint8_t* outBuf,
+                                       uint32_t outSize) {
+  const EpdFontGroup& group = fontData->groups[groupIndex];
+
+  const uint32_t tDecomp = millis();
+  inflateReader.init(false);
+  inflateReader.setSource(&fontData->bitmap[group.compressedOffset], group.compressedSize);
+  if (!inflateReader.read(outBuf, outSize)) {
+    stats.decompressTimeMs += millis() - tDecomp;
+    LOG_ERR("FDC", "Decompression failed for group %u", groupIndex);
+    return false;
+  }
+  stats.decompressTimeMs += millis() - tDecomp;
+  return true;
+}
+
+// --- Byte-aligned helpers ---
+
+uint32_t FontDecompressor::getAlignedOffset(const EpdFontData* fontData, uint16_t groupIndex, uint32_t glyphIndex) {
+  uint32_t offset = 0;
+
+  auto accumGlyph = [&](const EpdGlyph& g) {
+    if (g.width > 0 && g.height > 0) {
+      offset += ((g.width + 3) / 4) * g.height;
+    }
+  };
+
+  if (fontData->glyphToGroup) {
+    // Frequency-grouped: scan glyphs before glyphIndex that belong to this group
+    for (uint32_t i = 0; i < glyphIndex; i++) {
+      if (fontData->glyphToGroup[i] == groupIndex) {
+        accumGlyph(fontData->glyph[i]);
+      }
+    }
+  } else {
+    // Contiguous-group: sum aligned sizes of preceding glyphs in the group
+    const EpdFontGroup& group = fontData->groups[groupIndex];
+    for (uint32_t i = group.firstGlyphIndex; i < glyphIndex; i++) {
+      accumGlyph(fontData->glyph[i]);
+    }
+  }
+
+  return offset;
+}
+
+void FontDecompressor::compactSingleGlyph(const uint8_t* alignedSrc, uint8_t* packedDst, uint8_t width,
+                                          uint8_t height) {
+  if (width == 0 || height == 0) return;
+  const uint32_t rowStride = (width + 3) / 4;
+  if (width % 4 == 0) {
+    memcpy(packedDst, alignedSrc, rowStride * height);
+    return;
+  }
+  uint8_t outByte = 0, outBits = 0;
+  uint32_t writeIdx = 0;
+  for (uint8_t y = 0; y < height; y++) {
+    for (uint8_t x = 0; x < width; x++) {
+      outByte = (outByte << 2) | ((alignedSrc[y * rowStride + x / 4] >> ((3 - (x % 4)) * 2)) & 0x3);
+      outBits += 2;
+      if (outBits == 8) {
+        packedDst[writeIdx++] = outByte;
+        outByte = 0;
+        outBits = 0;
+      }
+    }
+  }
+  if (outBits > 0) packedDst[writeIdx] = outByte << (8 - outBits);
+}
+
+// --- getBitmap: page buffer → hot group → decompress ---
+
+const uint8_t* FontDecompressor::getBitmap(const EpdFontData* fontData, const EpdGlyph* glyph, uint32_t glyphIndex) {
+  const uint32_t tStart = micros();
+  stats.getBitmapCalls++;
+
+  if (!fontData->groups || fontData->groupCount == 0) {
+    stats.getBitmapTimeUs += micros() - tStart;
+    return &fontData->bitmap[glyph->dataOffset];
+  }
+
+  // Check page buffer slots (populated by prewarmCache — one slot per font style)
+  for (uint8_t s = 0; s < pageSlotCount; s++) {
+    const auto& slot = pageSlots[s];
+    if (slot.fontData != fontData || slot.glyphCount == 0) continue;
+
+    int left = 0, right = slot.glyphCount - 1;
+    while (left <= right) {
+      int mid = left + (right - left) / 2;
+      if (slot.glyphs[mid].glyphIndex == glyphIndex) {
+        if (slot.glyphs[mid].bufferOffset != UINT32_MAX) {
+          stats.cacheHits++;
+          stats.getBitmapTimeUs += micros() - tStart;
+          return &slot.buffer[slot.glyphs[mid].bufferOffset];
+        }
+        break;  // Not extracted during prewarm; fall through to hot-group path
+      }
+      if (slot.glyphs[mid].glyphIndex < glyphIndex)
+        left = mid + 1;
+      else
+        right = mid - 1;
+    }
+    break;  // Found the right slot but glyph wasn't in it; don't check other slots
+  }
+
+  // Fallback: hot group slot
+  uint16_t groupIndex = getGroupIndex(fontData, glyphIndex);
+  if (groupIndex >= fontData->groupCount) {
+    LOG_ERR("FDC", "Glyph %u not found in any group", glyphIndex);
+    stats.getBitmapTimeUs += micros() - tStart;
+    return nullptr;
+  }
+
+  // Check if hot group already has this group decompressed — if not, decompress it
+  if (!(!hotGroup.empty() && hotGroupFont == fontData && hotGroupIndex == groupIndex)) {
+    stats.cacheMisses++;
+    const EpdFontGroup& group = fontData->groups[groupIndex];
+
+    hotGroup.resize(group.uncompressedSize);
+    if (hotGroup.empty()) {
+      LOG_ERR("FDC", "Failed to allocate %u bytes for hot group %u", group.uncompressedSize, groupIndex);
+      hotGroupFont = nullptr;
+      hotGroupIndex = UINT16_MAX;
+      stats.getBitmapTimeUs += micros() - tStart;
+      return nullptr;
+    }
+
+    if (!decompressGroup(fontData, groupIndex, hotGroup.data(), group.uncompressedSize)) {
+      hotGroup.clear();
+      hotGroup.shrink_to_fit();
+      hotGroupFont = nullptr;
+      hotGroupIndex = UINT16_MAX;
+      stats.getBitmapTimeUs += micros() - tStart;
+      return nullptr;
+    }
+
+    hotGroupFont = fontData;
+    hotGroupIndex = groupIndex;
+    stats.hotGroupBytes = group.uncompressedSize;
+  } else {
+    stats.cacheHits++;
+  }
+
+  // Compact just the requested glyph from byte-aligned data into scratch buffer
+  if (glyph->dataLength > hotGlyphBuf.size()) {
+    hotGlyphBuf.resize(glyph->dataLength);
+  }
+  if (hotGlyphBuf.empty()) {
+    stats.getBitmapTimeUs += micros() - tStart;
+    return nullptr;
+  }
+
+  uint32_t alignedOff = getAlignedOffset(fontData, groupIndex, glyphIndex);
+  compactSingleGlyph(&hotGroup[alignedOff], hotGlyphBuf.data(), glyph->width, glyph->height);
+  stats.getBitmapTimeUs += micros() - tStart;
+  return hotGlyphBuf.data();
+}
+
+// --- Prewarm: pre-decompress glyph bitmaps for a page of text ---
+
+int32_t FontDecompressor::findGlyphIndex(const EpdFontData* fontData, uint32_t codepoint) {
+  const EpdUnicodeInterval* intervals = fontData->intervals;
+  const int count = fontData->intervalCount;
+
+  if (count == 0) return -1;
+
+  // Binary search
+  int left = 0;
+  int right = count - 1;
+
+  while (left <= right) {
+    const int mid = left + (right - left) / 2;
+    const EpdUnicodeInterval* interval = &intervals[mid];
+
+    if (codepoint < interval->first) {
+      right = mid - 1;
+    } else if (codepoint > interval->last) {
+      left = mid + 1;
+    } else {
+      return static_cast<int32_t>(interval->offset + (codepoint - interval->first));
+    }
+  }
+
+  return -1;
+}
+
+int FontDecompressor::prewarmCache(const EpdFontData* fontData, const char* utf8Text) {
+  if (!fontData || !fontData->groups || !utf8Text) return 0;
+
+  // Allocate the next available slot (caller must call freePageBuffer/clearCache to reset)
+  if (pageSlotCount >= MAX_PAGE_SLOTS) {
+    LOG_ERR("FDC", "All %u page buffer slots full, cannot prewarm fontData=%p", MAX_PAGE_SLOTS, (void*)fontData);
+    return -1;
+  }
+  PageSlot& slot = pageSlots[pageSlotCount];
+
+  // Step 1: Collect unique glyph indices needed for this page
+  uint32_t neededGlyphs[MAX_PAGE_GLYPHS];
+  uint16_t glyphCount = 0;
+  bool glyphCapWarned = false;
+
+  const unsigned char* p = reinterpret_cast<const unsigned char*>(utf8Text);
+  while (*p) {
+    uint32_t cp = utf8NextCodepoint(&p);
+    if (cp == 0) break;
+
+    int32_t glyphIdx = findGlyphIndex(fontData, cp);
+    if (glyphIdx < 0) continue;
+
+    // Deduplicate
+    bool found = false;
+    for (uint16_t i = 0; i < glyphCount; i++) {
+      if (neededGlyphs[i] == static_cast<uint32_t>(glyphIdx)) {
+        found = true;
+        break;
+      }
+    }
+    if (!found) {
+      if (glyphCount < MAX_PAGE_GLYPHS) {
+        neededGlyphs[glyphCount++] = static_cast<uint32_t>(glyphIdx);
+      } else if (!glyphCapWarned) {
+        LOG_DBG("FDC", "Glyph cap (%u) reached during prewarm; excess glyphs will use hot-group fallback",
+                MAX_PAGE_GLYPHS);
+        glyphCapWarned = true;
+      }
+    }
+  }
+
+  if (glyphCount == 0) return 0;
+
+  // Step 2: Compute total buffer size and collect unique groups
+  uint32_t totalBytes = 0;
+  uint16_t neededGroups[128];
+  uint8_t groupCount = 0;
+  bool groupCapWarned = false;
+
+  for (uint16_t i = 0; i < glyphCount; i++) {
+    totalBytes += fontData->glyph[neededGlyphs[i]].dataLength;
+    uint16_t gi = getGroupIndex(fontData, neededGlyphs[i]);
+    bool found = false;
+    for (uint8_t j = 0; j < groupCount; j++) {
+      if (neededGroups[j] == gi) {
+        found = true;
+        break;
+      }
+    }
+    if (!found) {
+      if (groupCount < 128) {
+        neededGroups[groupCount++] = gi;
+      } else if (!groupCapWarned) {
+        LOG_DBG("FDC", "Group cap (128) reached during prewarm; some groups will use hot-group fallback");
+        groupCapWarned = true;
+      }
+    }
+  }
+
+  stats.uniqueGroupsAccessed = groupCount;
+
+  // Step 3: Allocate page buffer and lookup table for this slot
+  slot.buffer = static_cast<uint8_t*>(malloc(totalBytes));
+  slot.glyphs = static_cast<PageGlyphEntry*>(malloc(glyphCount * sizeof(PageGlyphEntry)));
+  if (!slot.buffer || !slot.glyphs) {
+    LOG_ERR("FDC", "Failed to allocate page buffer (%u bytes, %u glyphs)", totalBytes, glyphCount);
+    free(slot.buffer);
+    free(slot.glyphs);
+    slot = {};
+    return glyphCount;
+  }
+  stats.pageBufferBytes += totalBytes;
+  stats.pageGlyphsBytes += glyphCount * sizeof(PageGlyphEntry);
+
+  slot.fontData = fontData;
+  slot.glyphCount = glyphCount;
+  pageSlotCount++;
+
+  // Initialize lookup entries (bufferOffset = UINT32_MAX means not yet extracted)
+  for (uint16_t i = 0; i < glyphCount; i++) {
+    slot.glyphs[i] = {neededGlyphs[i], UINT32_MAX, 0};
+  }
+
+  // Sort by glyphIndex for binary search in getBitmap()
+  for (uint16_t i = 1; i < glyphCount; i++) {
+    PageGlyphEntry key = slot.glyphs[i];
+    int j = i - 1;
+    while (j >= 0 && slot.glyphs[j].glyphIndex > key.glyphIndex) {
+      slot.glyphs[j + 1] = slot.glyphs[j];
+      j--;
+    }
+    slot.glyphs[j + 1] = key;
+  }
+
+  // Step 3b: Pre-scan to compute each needed glyph's byte-aligned offset within its group.
+  // This avoids recomputing aligned offsets per group during extraction in step 4.
+  uint32_t groupAlignedTracker[128] = {};  // running byte-aligned offset for each needed group
+
+  if (fontData->glyphToGroup) {
+    // Frequency-grouped: single O(totalGlyphs) pass through glyphToGroup
+    const auto& lastInterval = fontData->intervals[fontData->intervalCount - 1];
+    const uint32_t totalGlyphs = lastInterval.offset + (lastInterval.last - lastInterval.first + 1);
+
+    for (uint32_t i = 0; i < totalGlyphs; i++) {
+      const uint16_t gi = fontData->glyphToGroup[i];
+      // Find this glyph's group position in neededGroups
+      uint8_t gpPos = groupCount;
+      for (uint8_t j = 0; j < groupCount; j++) {
+        if (neededGroups[j] == gi) {
+          gpPos = j;
+          break;
+        }
+      }
+      if (gpPos == groupCount) continue;  // not a needed group
+
+      const EpdGlyph& glyph = fontData->glyph[i];
+
+      // Binary search in sorted slot.glyphs to find if glyph i is needed
+      int left = 0, right = (int)slot.glyphCount - 1;
+      while (left <= right) {
+        const int mid = left + (right - left) / 2;
+        if (slot.glyphs[mid].glyphIndex == i) {
+          slot.glyphs[mid].alignedOffset = groupAlignedTracker[gpPos];
+          break;
+        }
+        if (slot.glyphs[mid].glyphIndex < i)
+          left = mid + 1;
+        else
+          right = mid - 1;
+      }
+
+      if (glyph.width > 0 && glyph.height > 0) {
+        groupAlignedTracker[gpPos] += ((glyph.width + 3) / 4) * glyph.height;
+      }
+    }
+  } else {
+    // Contiguous-group: iterate each needed group's glyphs directly
+    for (uint8_t g = 0; g < groupCount; g++) {
+      const EpdFontGroup& group = fontData->groups[neededGroups[g]];
+      uint32_t alignedOff = 0;
+      for (uint16_t j = 0; j < group.glyphCount; j++) {
+        const uint32_t glyphI = group.firstGlyphIndex + j;
+        const EpdGlyph& glyph = fontData->glyph[glyphI];
+
+        int left = 0, right = (int)slot.glyphCount - 1;
+        while (left <= right) {
+          const int mid = left + (right - left) / 2;
+          if (slot.glyphs[mid].glyphIndex == glyphI) {
+            slot.glyphs[mid].alignedOffset = alignedOff;
+            break;
+          }
+          if (slot.glyphs[mid].glyphIndex < glyphI)
+            left = mid + 1;
+          else
+            right = mid - 1;
+        }
+
+        if (glyph.width > 0 && glyph.height > 0) {
+          alignedOff += ((glyph.width + 3) / 4) * glyph.height;
+        }
+      }
+    }
+  }
+
+  // Step 4: For each unique group, decompress to temp buffer and extract needed glyphs
+  uint32_t writeOffset = 0;
+  int missed = 0;
+
+  for (uint8_t g = 0; g < groupCount; g++) {
+    uint16_t groupIdx = neededGroups[g];
+    const EpdFontGroup& group = fontData->groups[groupIdx];
+
+    auto* tempBuf = static_cast<uint8_t*>(malloc(group.uncompressedSize));
+    if (!tempBuf) {
+      LOG_ERR("FDC", "Failed to allocate temp buffer (%u bytes) for group %u", group.uncompressedSize, groupIdx);
+      missed++;
+      continue;
+    }
+    if (group.uncompressedSize > stats.peakTempBytes) {
+      stats.peakTempBytes = group.uncompressedSize;
+    }
+
+    if (!decompressGroup(fontData, groupIdx, tempBuf, group.uncompressedSize)) {
+      free(tempBuf);
+      missed++;
+      continue;
+    }
+
+    // Extract needed glyphs directly from the byte-aligned temp buffer, compacting on the fly.
+    // alignedOffset was pre-computed in step 3b — no full-group compact scan needed.
+    for (uint16_t i = 0; i < slot.glyphCount; i++) {
+      if (slot.glyphs[i].bufferOffset != UINT32_MAX) continue;  // already extracted
+      if (getGroupIndex(fontData, slot.glyphs[i].glyphIndex) != groupIdx) continue;
+
+      const EpdGlyph& glyph = fontData->glyph[slot.glyphs[i].glyphIndex];
+      compactSingleGlyph(&tempBuf[slot.glyphs[i].alignedOffset], &slot.buffer[writeOffset], glyph.width, glyph.height);
+      slot.glyphs[i].bufferOffset = writeOffset;
+      writeOffset += glyph.dataLength;
+    }
+
+    free(tempBuf);
+  }
+
+  LOG_DBG("FDC", "Prewarm: %u glyphs in %u bytes from %u groups (%d missed)", glyphCount, writeOffset, groupCount,
+          missed);
+
+  return missed;
+}
+
+// --- Stats ---
+
+void FontDecompressor::resetStats() { stats = Stats{}; }
+
+void FontDecompressor::logStats(const char* label) {
+  const uint32_t total = stats.cacheHits + stats.cacheMisses;
+  LOG_DBG("FDC", "[%s] hits=%lu misses=%lu (%.1f%% hit rate)", label, stats.cacheHits, stats.cacheMisses,
+          total > 0 ? 100.0f * stats.cacheHits / total : 0.0f);
+  LOG_DBG("FDC", "[%s] decompress=%lums groups_accessed=%u", label, stats.decompressTimeMs, stats.uniqueGroupsAccessed);
+  LOG_DBG("FDC", "[%s] mem: pageBuf=%lu pageGlyphs=%lu hotGroup=%lu peakTemp=%lu", label, stats.pageBufferBytes,
+          stats.pageGlyphsBytes, stats.hotGroupBytes, stats.peakTempBytes);
+  if (stats.getBitmapCalls > 0) {
+    LOG_DBG("FDC", "[%s] getBitmap: %lu calls, %luus total, %luus/call avg", label, stats.getBitmapCalls,
+            stats.getBitmapTimeUs, stats.getBitmapTimeUs / stats.getBitmapCalls);
+  }
+  resetStats();
+}

lib/EpdFont/FontDecompressor.h

@@ -0,0 +1,85 @@
+#pragma once
+
+#include <InflateReader.h>
+
+#include <vector>
+
+#include "EpdFontData.h"
+
+class FontDecompressor {
+ public:
+  static constexpr uint16_t MAX_PAGE_GLYPHS = 512;
+  static constexpr uint8_t MAX_PAGE_SLOTS = 4;  // One per font style (R/B/I/BI)
+
+  FontDecompressor() = default;
+  ~FontDecompressor();
+
+  bool init();
+  void deinit();
+
+  // Returns pointer to decompressed bitmap data for the given glyph.
+  // Checks the page buffer (from prewarm) first, then falls back to the hot group slot.
+  const uint8_t* getBitmap(const EpdFontData* fontData, const EpdGlyph* glyph, uint32_t glyphIndex);
+
+  // Free all cached data (page buffer + hot group).
+  void clearCache();
+
+  // Pre-scan UTF-8 text and extract needed glyph bitmaps into a flat page buffer.
+  // Each group is decompressed once into a temp buffer; only needed glyphs are kept.
+  // Returns the number of glyphs that couldn't be loaded (0 on full success).
+  int prewarmCache(const EpdFontData* fontData, const char* utf8Text);
+
+  struct Stats {
+    uint32_t cacheHits = 0;
+    uint32_t cacheMisses = 0;
+    uint32_t decompressTimeMs = 0;
+    uint16_t uniqueGroupsAccessed = 0;
+    uint32_t pageBufferBytes = 0;  // pageBuffer allocation
+    uint32_t pageGlyphsBytes = 0;  // pageGlyphs lookup table allocation
+    uint32_t hotGroupBytes = 0;    // current hot group allocation
+    uint32_t peakTempBytes = 0;    // largest temp buffer in prewarm
+    uint32_t getBitmapTimeUs = 0;  // cumulative getBitmap time (micros)
+    uint32_t getBitmapCalls = 0;   // number of getBitmap calls
+  };
+  void logStats(const char* label = "FDC");
+  void resetStats();
+  const Stats& getStats() const { return stats; }
+
+ private:
+  Stats stats;
+  InflateReader inflateReader;
+
+  // Page buffer slots: each style gets its own flat glyph buffer with sorted lookup.
+  // Up to MAX_PAGE_SLOTS (4) styles can be prewarmed simultaneously.
+  struct PageGlyphEntry {
+    uint32_t glyphIndex;
+    uint32_t bufferOffset;
+    uint32_t alignedOffset;  // byte-aligned offset within its decompressed group (set during prewarm pre-scan)
+  };
+  struct PageSlot {
+    uint8_t* buffer = nullptr;
+    const EpdFontData* fontData = nullptr;
+    PageGlyphEntry* glyphs = nullptr;
+    uint16_t glyphCount = 0;
+  };
+  PageSlot pageSlots[MAX_PAGE_SLOTS] = {};
+  uint8_t pageSlotCount = 0;
+
+  // Hot group: last decompressed group (byte-aligned) for non-prewarmed fallback path.
+  // Kept in byte-aligned format; individual glyphs are compacted on demand into hotGlyphBuf.
+  const EpdFontData* hotGroupFont = nullptr;
+  uint16_t hotGroupIndex = UINT16_MAX;
+  std::vector<uint8_t> hotGroup;
+
+  // Scratch buffer for compacting a single glyph from the hot group.
+  // Valid until the next getBitmap() call.
+  std::vector<uint8_t> hotGlyphBuf;
+
+  void freePageBuffer();
+  void freeHotGroup();
+  uint16_t getGroupIndex(const EpdFontData* fontData, uint32_t glyphIndex);
+  uint32_t getAlignedOffset(const EpdFontData* fontData, uint16_t groupIndex, uint32_t glyphIndex);
+  bool decompressGroup(const EpdFontData* fontData, uint16_t groupIndex, uint8_t* outBuf, uint32_t outSize);
+  static void compactSingleGlyph(const uint8_t* alignedSrc, uint8_t* packedDst, uint8_t width, uint8_t height);
+  static int32_t findGlyphIndex(const EpdFontData* fontData, uint32_t codepoint);
+};

lib/EpdFont/scripts/convert-builtin-fonts.sh

@@ -14,7 +14,7 @@ for size in ${BOOKERLY_FONT_SIZES[@]}; do
     font_name="bookerly_${size}_$(echo $style | tr '[:upper:]' '[:lower:]')"
     font_path="../builtinFonts/source/Bookerly/Bookerly-${style}.ttf"
     output_path="../builtinFonts/${font_name}.h"
-    python fontconvert.py $font_name $size $font_path --2bit > $output_path
+    python fontconvert.py $font_name $size $font_path --2bit --compress > $output_path
     echo "Generated $output_path"
   done
 done
@@ -24,7 +24,7 @@ for size in ${NOTOSANS_FONT_SIZES[@]}; do
     font_name="notosans_${size}_$(echo $style | tr '[:upper:]' '[:lower:]')"
     font_path="../builtinFonts/source/NotoSans/NotoSans-${style}.ttf"
     output_path="../builtinFonts/${font_name}.h"
-    python fontconvert.py $font_name $size $font_path --2bit > $output_path
+    python fontconvert.py $font_name $size $font_path --2bit --compress > $output_path
     echo "Generated $output_path"
   done
 done
@@ -34,7 +34,7 @@ for size in ${OPENDYSLEXIC_FONT_SIZES[@]}; do
     font_name="opendyslexic_${size}_$(echo $style | tr '[:upper:]' '[:lower:]')"
     font_path="../builtinFonts/source/OpenDyslexic/OpenDyslexic-${style}.otf"
     output_path="../builtinFonts/${font_name}.h"
-    python fontconvert.py $font_name $size $font_path --2bit > $output_path
+    python fontconvert.py $font_name $size $font_path --2bit --compress > $output_path
     echo "Generated $output_path"
   done
 done
@@ -53,3 +53,7 @@ for size in ${UI_FONT_SIZES[@]}; do
 done
 
 python fontconvert.py notosans_8_regular 8 ../builtinFonts/source/NotoSans/NotoSans-Regular.ttf > ../builtinFonts/notosans_8_regular.h
+
+echo ""
+echo "Running compression verification..."
+python verify_compression.py ../builtinFonts/

lib/EpdFont/scripts/fontconvert.py

@@ -6,6 +6,7 @@ import re
 import math
 import argparse
 from collections import namedtuple
+from fontTools.ttLib import TTFont
 
 # Originally from https://github.com/vroland/epdiy
 
@@ -15,6 +16,8 @@ parser.add_argument("size", type=int, help="font size to use.")
 parser.add_argument("fontstack", action="store", nargs='+', help="list of font files, ordered by descending priority.")
 parser.add_argument("--2bit", dest="is2Bit", action="store_true", help="generate 2-bit greyscale bitmap instead of 1-bit black and white.")
 parser.add_argument("--additional-intervals", dest="additional_intervals", action="append", help="Additional code point intervals to export as min,max. This argument can be repeated.")
+parser.add_argument("--compress", dest="compress", action="store_true", help="Compress glyph bitmaps using DEFLATE with group-based compression.")
+parser.add_argument("--force-autohint", dest="force_autohint", action="store_true", help="Force FreeType auto-hinter instead of native font hinting. Improves stem width consistency for fonts with weak or no native TrueType hints.")
 args = parser.parse_args()
 
 GlyphProps = namedtuple("GlyphProps", ["width", "height", "advance_x", "left", "top", "data_length", "data_offset", "code_point"])
@@ -23,6 +26,9 @@ font_stack = [freetype.Face(f) for f in args.fontstack]
 is2Bit = args.is2Bit
 size = args.size
 font_name = args.name
+load_flags = freetype.FT_LOAD_RENDER
+if args.force_autohint:
+    load_flags |= freetype.FT_LOAD_FORCE_AUTOHINT
 
 # inclusive unicode code point intervals
 # must not overlap and be in ascending order
@@ -36,6 +42,18 @@ intervals = [
     ### Latin Extended-A ###
     # Eastern European and Baltic languages
     (0x0100, 0x017F),
+    ### Latin Extended-B (Vietnamese subset only) ###
+    # Only Ơ/ơ (U+01A0-01A1), Ư/ư (U+01AF-01B0) for Vietnamese
+    (0x01A0, 0x01A1),
+    (0x01AF, 0x01B0),
+    ### Latin Extended-B (European subset only) ###
+    # Croatian digraphs (DŽ/Lj/Nj), Pinyin caron variants,
+    # European diacritical variants, Romanian (Ș/ș/Ț/ț)
+    (0x01C4, 0x021F),
+    ### Vietnamese Extended ###
+    # All precomposed Vietnamese characters with tone marks
+    # Ả Ấ Ầ Ẩ Ẫ Ậ Ắ Ằ Ẳ Ẵ Ặ Ẹ Ẻ Ẽ Ế Ề Ể Ễ Ệ Ỉ Ị Ọ Ỏ Ố Ồ Ổ Ỗ Ộ Ớ Ờ Ở Ỡ Ợ Ụ Ủ Ứ Ừ Ử Ữ Ự Ỳ Ỵ Ỷ Ỹ
+    (0x1EA0, 0x1EF9),
     ### General Punctuation (core subset) ###
     # Smart quotes, en dash, em dash, ellipsis, NO-BREAK SPACE
     (0x2000, 0x206F),
@@ -56,6 +74,8 @@ intervals = [
     # Russian, Ukrainian, Bulgarian, etc.
     (0x0400, 0x04FF),
     ### Math Symbols (common subset) ###
+    # Superscripts and Subscripts
+    (0x2070, 0x209F),
     # General math operators
     (0x2200, 0x22FF),
     # Arrows
@@ -99,6 +119,12 @@ intervals = [
     # (0xFE30, 0xFE4F),
     # # CJK Compatibility Ideographs
     # (0xF900, 0xFAFF),
+    ### Alphabetic Presentation Forms (Latin ligatures) ###
+    # ff, fi, fl, ffi, ffl, long-st, st
+    (0xFB00, 0xFB06),
+    ### Specials
+    # Replacement Character
+    (0xFFFD, 0xFFFD),
 ]
 
 add_ints = []
@@ -111,6 +137,33 @@ def norm_floor(val):
 def norm_ceil(val):
     return int(math.ceil(val / (1 << 6)))
 
+# Fixed-point (fp4) output conventions (must match EpdFontData.h / fp4 namespace):
+#
+#   advanceX    12.4 unsigned fixed-point (uint16_t).
+#               12 integer bits, 4 fractional bits = 1/16-pixel resolution.
+#               Encoded from FreeType's 16.16 linearHoriAdvance.
+#
+#   kernMatrix  4.4 signed fixed-point (int8_t).
+#               4 integer bits, 4 fractional bits = 1/16-pixel resolution.
+#               Range: -8.0 to +7.9375 pixels.
+#               Encoded from font design-unit kerning values.
+#
+# Both share 4 fractional bits so the renderer can add them directly into a
+# single int32_t accumulator and defer rounding until pixel placement.
+
+def fp4_from_ft16_16(val):
+    """Convert FreeType 16.16 fixed-point to 12.4 fixed-point with rounding."""
+    return (val + (1 << 11)) >> 12
+
+def fp4_from_design_units(du, scale):
+    """Convert a font design-unit value to 4.4 fixed-point, clamped to int8_t.
+
+    Multiplies by scale (ppem / units_per_em) and shifts into 4 fractional
+    bits.  The result is rounded to nearest and clamped to [-128, 127].
+    """
+    raw = round(du * scale * 16)
+    return max(-128, min(127, raw))
+
 def chunks(l, n):
     for i in range(0, len(l), n):
         yield l[i:i + n]
@@ -121,10 +174,9 @@ def load_glyph(code_point):
         face = font_stack[face_index]
         glyph_index = face.get_char_index(code_point)
         if glyph_index > 0:
-            face.load_glyph(glyph_index, freetype.FT_LOAD_RENDER)
+            face.load_glyph(glyph_index, load_flags)
             return face
         face_index += 1
-    print(f"code point {code_point} ({hex(code_point)}) not found in font stack!", file=sys.stderr)
     return None
 
 unmerged_intervals = sorted(intervals + add_ints)
@@ -245,7 +297,9 @@ for i_start, i_end in intervals:
         glyph = GlyphProps(
             width = bitmap.width,
             height = bitmap.rows,
-            advance_x = norm_floor(face.glyph.advance.x),
+            # We use linearHoriAdvance (16.16 fixed-point, unhinted) instead of
+            # advance.x (26.6 fixed-point, grid-fitted to whole pixels by hinter)
+            advance_x = fp4_from_ft16_16(face.glyph.linearHoriAdvance),
             left = face.glyph.bitmap_left,
             top = face.glyph.bitmap_top,
             data_length = len(packed),
@@ -265,17 +319,528 @@ for index, glyph in enumerate(all_glyphs):
     glyph_data.extend([b for b in packed])
     glyph_props.append(props)
 
-print(f"/**\n * generated by fontconvert.py\n * name: {font_name}\n * size: {size}\n * mode: {'2-bit' if is2Bit else '1-bit'}\n */")
-print("#pragma once")
-print("#include \"EpdFontData.h\"\n")
-print(f"static const uint8_t {font_name}Bitmaps[{len(glyph_data)}] = {{")
-for c in chunks(glyph_data, 16):
-    print ("    " + " ".join(f"0x{b:02X}," for b in c))
-print ("};\n");
+# --- Kerning pair extraction ---
+# Modern fonts store kerning in the OpenType GPOS table, which FreeType's
+# get_kerning() does not read. We use fonttools to parse both the legacy
+# kern table and the GPOS 'kern' feature (PairPos lookups, including
+# Extension wrappers).
+
+COMBINING_MARKS_START = 0x0300
+COMBINING_MARKS_END = 0x036F
+all_codepoints = [g.code_point for g in glyph_props]
+kernable_codepoints = set(cp for cp in all_codepoints
+                          if not (COMBINING_MARKS_START <= cp <= COMBINING_MARKS_END))
+
+# Map each kernable codepoint to the font-stack index that serves it
+# (same priority logic as load_glyph).
+cp_to_face_idx = {}
+for cp in kernable_codepoints:
+    for face_idx, f in enumerate(font_stack):
+        if f.get_char_index(cp) > 0:
+            cp_to_face_idx[cp] = face_idx
+            break
+
+# Group codepoints by face index
+face_idx_cps = {}
+for cp, fi in cp_to_face_idx.items():
+    face_idx_cps.setdefault(fi, set()).add(cp)
+
+def _extract_pairpos_subtable(subtable, glyph_to_cp, raw_kern):
+    """Extract kerning from a PairPos subtable (Format 1 or 2)."""
+    if subtable.Format == 1:
+        # Individual pairs
+        for i, coverage_glyph in enumerate(subtable.Coverage.glyphs):
+            if coverage_glyph not in glyph_to_cp:
+                continue
+            pair_set = subtable.PairSet[i]
+            for pvr in pair_set.PairValueRecord:
+                if pvr.SecondGlyph not in glyph_to_cp:
+                    continue
+                xa = 0
+                if hasattr(pvr, 'Value1') and pvr.Value1:
+                    xa = getattr(pvr.Value1, 'XAdvance', 0) or 0
+                if xa != 0:
+                    key = (coverage_glyph, pvr.SecondGlyph)
+                    raw_kern[key] = raw_kern.get(key, 0) + xa
+    elif subtable.Format == 2:
+        # Class-based pairs
+        class_def1 = subtable.ClassDef1.classDefs if subtable.ClassDef1 else {}
+        class_def2 = subtable.ClassDef2.classDefs if subtable.ClassDef2 else {}
+        coverage_set = set(subtable.Coverage.glyphs)
+        for left_glyph in glyph_to_cp:
+            if left_glyph not in coverage_set:
+                continue
+            c1 = class_def1.get(left_glyph, 0)
+            if c1 >= len(subtable.Class1Record):
+                continue
+            class1_rec = subtable.Class1Record[c1]
+            for right_glyph in glyph_to_cp:
+                c2 = class_def2.get(right_glyph, 0)
+                if c2 >= len(class1_rec.Class2Record):
+                    continue
+                c2_rec = class1_rec.Class2Record[c2]
+                xa = 0
+                if hasattr(c2_rec, 'Value1') and c2_rec.Value1:
+                    xa = getattr(c2_rec.Value1, 'XAdvance', 0) or 0
+                if xa != 0:
+                    key = (left_glyph, right_glyph)
+                    raw_kern[key] = raw_kern.get(key, 0) + xa
+
+def extract_kerning_fonttools(font_path, codepoints, ppem):
+    """Extract kerning pairs from a font file using fonttools.
+
+    Returns dict of {(leftCp, rightCp): pixel_adjust} for the given
+    codepoints.  Values are scaled from font design units to integer
+    pixels at ppem.
+    """
+    font = TTFont(font_path)
+    units_per_em = font['head'].unitsPerEm
+    cmap = font.getBestCmap() or {}
+
+    # Build glyph_name -> codepoint map (only for requested codepoints)
+    glyph_to_cp = {}
+    for cp in codepoints:
+        gname = cmap.get(cp)
+        if gname:
+            glyph_to_cp[gname] = cp
+
+    # Collect raw kerning values in font design units
+    raw_kern = {}  # (left_glyph_name, right_glyph_name) -> design_units
+
+    # 1. Legacy kern table
+    if 'kern' in font:
+        for subtable in font['kern'].kernTables:
+            if hasattr(subtable, 'kernTable'):
+                for (lg, rg), val in subtable.kernTable.items():
+                    if lg in glyph_to_cp and rg in glyph_to_cp:
+                        raw_kern[(lg, rg)] = raw_kern.get((lg, rg), 0) + val
+
+    # 2. GPOS 'kern' feature
+    if 'GPOS' in font:
+        gpos = font['GPOS'].table
+        kern_lookup_indices = set()
+        if gpos.FeatureList:
+            for fr in gpos.FeatureList.FeatureRecord:
+                if fr.FeatureTag == 'kern':
+                    kern_lookup_indices.update(fr.Feature.LookupListIndex)
+        for li in kern_lookup_indices:
+            lookup = gpos.LookupList.Lookup[li]
+            for st in lookup.SubTable:
+                actual = st
+                # Unwrap Extension (lookup type 9) wrappers
+                if lookup.LookupType == 9 and hasattr(st, 'ExtSubTable'):
+                    actual = st.ExtSubTable
+                if hasattr(actual, 'Format'):
+                    _extract_pairpos_subtable(actual, glyph_to_cp, raw_kern)
+
+    font.close()
+
+    # Scale design-unit kerning values to 4.4 fixed-point pixels.
+    scale = ppem / units_per_em
+    result = {}  # (leftCp, rightCp) -> 4.4 fixed-point adjust
+    for (lg, rg), du in raw_kern.items():
+        lcp = glyph_to_cp[lg]
+        rcp = glyph_to_cp[rg]
+        adjust = fp4_from_design_units(du, scale)
+        if adjust != 0:
+            result[(lcp, rcp)] = adjust
+    return result
+
+# The ppem used by the existing glyph rasterization:
+#   face.set_char_size(size << 6, size << 6, 150, 150)
+# means size_pt at 150 DPI -> ppem = size * 150 / 72
+ppem = size * 150.0 / 72.0
+
+kern_map = {}  # (leftCp, rightCp) -> adjust
+for face_idx, cps in face_idx_cps.items():
+    font_path = args.fontstack[face_idx]
+    kern_map.update(extract_kerning_fonttools(font_path, cps, ppem))
+
+print(f"kerning: {len(kern_map)} pairs extracted", file=sys.stderr)
+
+# --- Derive class-based kerning from pairs ---
+kern_left_classes = []   # list of (codepoint, classId)
+kern_right_classes = []  # list of (codepoint, classId)
+kern_matrix = []         # flat list of int8_t values
+kern_left_class_count = 0
+kern_right_class_count = 0
+
+if kern_map:
+    all_left_cps = {lcp for lcp, _ in kern_map}
+    all_right_cps = {rcp for _, rcp in kern_map}
+
+    sorted_right_cps = sorted(all_right_cps)
+    sorted_left_cps = sorted(all_left_cps)
+
+    # Group left codepoints by identical adjustment row
+    left_profile_to_class = {}
+    left_class_map = {}
+    left_class_id = 1
+    for lcp in sorted(all_left_cps):
+        row = tuple(kern_map.get((lcp, rcp), 0) for rcp in sorted_right_cps)
+        if row not in left_profile_to_class:
+            left_profile_to_class[row] = left_class_id
+            left_class_id += 1
+        left_class_map[lcp] = left_profile_to_class[row]
+
+    # Group right codepoints by identical adjustment column
+    right_profile_to_class = {}
+    right_class_map = {}
+    right_class_id = 1
+    for rcp in sorted(all_right_cps):
+        col = tuple(kern_map.get((lcp, rcp), 0) for lcp in sorted_left_cps)
+        if col not in right_profile_to_class:
+            right_profile_to_class[col] = right_class_id
+            right_class_id += 1
+        right_class_map[rcp] = right_profile_to_class[col]
+
+    kern_left_class_count = left_class_id - 1
+    kern_right_class_count = right_class_id - 1
+
+    if kern_left_class_count > 255 or kern_right_class_count > 255:
+        print(f"WARNING: kerning class count exceeds uint8_t range "
+              f"(left={kern_left_class_count}, right={kern_right_class_count})",
+              file=sys.stderr)
+
+    # Build the class x class matrix
+    kern_matrix = [0] * (kern_left_class_count * kern_right_class_count)
+    for (lcp, rcp), adjust in kern_map.items():
+        lc = left_class_map[lcp] - 1
+        rc = right_class_map[rcp] - 1
+        kern_matrix[lc * kern_right_class_count + rc] = adjust
+
+    # Build sorted class entry lists
+    kern_left_classes = sorted(left_class_map.items())
+    kern_right_classes = sorted(right_class_map.items())
+
+    matrix_size = kern_left_class_count * kern_right_class_count
+    entries_size = (len(kern_left_classes) + len(kern_right_classes)) * 3
+    print(f"kerning: {kern_left_class_count} left classes, {kern_right_class_count} right classes, "
+          f"{matrix_size + entries_size} bytes", file=sys.stderr)
+
+# --- Ligature pair extraction ---
+# Parse the OpenType GSUB table for LigatureSubst (type 4) lookups.
+# Multi-character ligatures (3+ codepoints) are decomposed into chained
+# pairs when an intermediate ligature exists (e.g., ffi = ff + i where ff
+# is itself a ligature). Only pairs where both input codepoints and the
+# output codepoint are in the generated glyph set are included.
+
+all_codepoints_set = set(all_codepoints)
+
+# Standard Unicode ligature codepoints for known input sequences.
+# Used as a fallback when the GSUB substitute glyph has no cmap entry.
+STANDARD_LIGATURE_MAP = {
+    (0x66, 0x66):       0xFB00,  # ff
+    (0x66, 0x69):       0xFB01,  # fi
+    (0x66, 0x6C):       0xFB02,  # fl
+    (0x66, 0x66, 0x69): 0xFB03,  # ffi
+    (0x66, 0x66, 0x6C): 0xFB04,  # ffl
+    (0x17F, 0x74):      0xFB05,  # long-s + t
+    (0x73, 0x74):       0xFB06,  # st
+}
+
+def extract_ligatures_fonttools(font_path, codepoints):
+    """Extract ligature substitution pairs from a font file using fonttools.
+
+    Returns list of (packed_pair, ligature_codepoint) for the given codepoints.
+    Multi-character ligatures are decomposed into chained pairs.
+    """
+    font = TTFont(font_path)
+    cmap = font.getBestCmap() or {}
+
+    # Build glyph_name -> codepoint and codepoint -> glyph_name maps
+    glyph_to_cp = {}
+    cp_to_glyph = {}
+    for cp, gname in cmap.items():
+        glyph_to_cp[gname] = cp
+        cp_to_glyph[cp] = gname
+
+    # Collect raw ligature rules: (sequence_of_codepoints) -> ligature_codepoint
+    raw_ligatures = {}  # tuple of codepoints -> ligature codepoint
+
+    if 'GSUB' in font:
+        gsub = font['GSUB'].table
+
+        # Find lookup indices for ligature features.
+        # Currently extracts 'liga' (standard) and 'rlig' (required) only.
+        # To also extract discretionary or historical ligatures, add:
+        #   'dlig' - Discretionary Ligatures (e.g., ft, st in Bookerly)
+        #   'hlig' - Historical Ligatures (e.g., long-s+t in OpenDyslexic)
+        # These are off by default in standard text renderers.
+        LIGATURE_FEATURES = ('liga', 'rlig')
+        liga_lookup_indices = set()
+        if gsub.FeatureList:
+            for fr in gsub.FeatureList.FeatureRecord:
+                if fr.FeatureTag in LIGATURE_FEATURES:
+                    liga_lookup_indices.update(fr.Feature.LookupListIndex)
+
+        for li in liga_lookup_indices:
+            lookup = gsub.LookupList.Lookup[li]
+            for st in lookup.SubTable:
+                actual = st
+                # Unwrap Extension (lookup type 7) wrappers
+                if lookup.LookupType == 7 and hasattr(st, 'ExtSubTable'):
+                    actual = st.ExtSubTable
+                # LigatureSubst is lookup type 4
+                if not hasattr(actual, 'ligatures'):
+                    continue
+                for first_glyph, ligature_list in actual.ligatures.items():
+                    if first_glyph not in glyph_to_cp:
+                        continue
+                    first_cp = glyph_to_cp[first_glyph]
+                    for lig in ligature_list:
+                        # lig.Component is a list of subsequent glyph names
+                        # lig.LigGlyph is the substitute glyph name
+                        component_cps = []
+                        valid = True
+                        for comp_glyph in lig.Component:
+                            if comp_glyph not in glyph_to_cp:
+                                valid = False
+                                break
+                            component_cps.append(glyph_to_cp[comp_glyph])
+                        if not valid:
+                            continue
+                        seq = tuple([first_cp] + component_cps)
+                        if lig.LigGlyph in glyph_to_cp:
+                            lig_cp = glyph_to_cp[lig.LigGlyph]
+                        elif seq in STANDARD_LIGATURE_MAP:
+                            lig_cp = STANDARD_LIGATURE_MAP[seq]
+                        else:
+                            seq_str = ', '.join(f'U+{cp:04X}' for cp in seq)
+                            print(f"ligatures: WARNING: dropping ligature ({seq_str}) -> "
+                                  f"glyph '{lig.LigGlyph}': output glyph has no cmap entry "
+                                  f"and input sequence is not in STANDARD_LIGATURE_MAP",
+                                  file=sys.stderr)
+                            continue
+                        raw_ligatures[seq] = lig_cp
+
+    font.close()
+
+    # Filter: only keep ligatures where all input and output codepoints are
+    # in our generated glyph set
+    filtered = {}
+    for seq, lig_cp in raw_ligatures.items():
+        if lig_cp not in codepoints and lig_cp not in all_codepoints_set:
+            continue
+        if all(cp in codepoints for cp in seq):
+            filtered[seq] = lig_cp
+
+    # Decompose into chained pairs
+    # For 2-codepoint sequences: direct pair (a, b) -> lig
+    # For 3+ codepoint sequences: chain through intermediates
+    #   e.g., (f, f, i) -> ffi requires (f, f) -> ff to exist,
+    #   then we add (ff, i) -> ffi
+    pairs = []
+    # First pass: collect all 2-codepoint ligatures
+    two_char = {seq: lig_cp for seq, lig_cp in filtered.items() if len(seq) == 2}
+    for seq, lig_cp in two_char.items():
+        packed = (seq[0] << 16) | seq[1]
+        pairs.append((packed, lig_cp))
+
+    # Second pass: decompose 3+ codepoint ligatures into chained pairs
+    for seq, lig_cp in filtered.items():
+        if len(seq) < 3:
+            continue
+        # Try to find an intermediate: check if the first N-1 codepoints
+        # form a known ligature, then chain (intermediate, last) -> lig
+        prefix = seq[:-1]
+        last_cp = seq[-1]
+        if prefix in filtered:
+            intermediate_cp = filtered[prefix]
+            packed = (intermediate_cp << 16) | last_cp
+            pairs.append((packed, lig_cp))
+        else:
+            print(f"ligatures: skipping {len(seq)}-char ligature "
+                  f"({', '.join(f'U+{cp:04X}' for cp in seq)}) -> U+{lig_cp:04X}: "
+                  f"no intermediate ligature for prefix", file=sys.stderr)
+
+    return pairs
+
+ligature_codepoints = set(cp for cp in all_codepoints
+                          if not (COMBINING_MARKS_START <= cp <= COMBINING_MARKS_END))
+
+# Map ligature codepoints to the font-stack index that serves them
+lig_cp_to_face_idx = {}
+for cp in ligature_codepoints:
+    for face_idx, f in enumerate(font_stack):
+        if f.get_char_index(cp) > 0:
+            lig_cp_to_face_idx[cp] = face_idx
+            break
+
+# Group by face index
+lig_face_idx_cps = {}
+for cp, fi in lig_cp_to_face_idx.items():
+    lig_face_idx_cps.setdefault(fi, set()).add(cp)
+
+ligature_pairs = []
+for face_idx, cps in lig_face_idx_cps.items():
+    font_path = args.fontstack[face_idx]
+    ligature_pairs.extend(extract_ligatures_fonttools(font_path, cps))
+
+# Deduplicate (keep first occurrence) and sort
+seen_lig_keys = set()
+unique_ligature_pairs = []
+for packed, lig_cp in ligature_pairs:
+    if packed not in seen_lig_keys:
+        seen_lig_keys.add(packed)
+        unique_ligature_pairs.append((packed, lig_cp))
+ligature_pairs = sorted(unique_ligature_pairs, key=lambda p: p[0])
+print(f"ligatures: {len(ligature_pairs)} pairs extracted", file=sys.stderr)
+
+compress = args.compress
+
+
+def to_byte_aligned(packed, width, height):
+    """Convert packed 2-bit bitmap to byte-aligned format (rows padded to byte boundary).
+
+    In packed format, pixels flow continuously across row boundaries (4 pixels/byte).
+    In byte-aligned format, each row starts at a byte boundary, padding the last byte
+    of each row with zero bits if width % 4 != 0. This improves DEFLATE compression
+    because identical pixel rows produce identical byte patterns regardless of position.
+    """
+    if width == 0 or height == 0:
+        return b''
+    row_stride = (width + 3) // 4  # bytes per byte-aligned row
+    aligned = bytearray(row_stride * height)
+    for y in range(height):
+        for x in range(width):
+            # Read pixel from packed format (continuous bit stream)
+            packed_pos = y * width + x
+            packed_byte_idx = packed_pos // 4
+            packed_shift = (3 - (packed_pos % 4)) * 2
+            pixel = (packed[packed_byte_idx] >> packed_shift) & 0x3
+
+            # Write pixel to byte-aligned format (row-aligned)
+            aligned_byte_idx = y * row_stride + x // 4
+            aligned_shift = (3 - (x % 4)) * 2
+            aligned[aligned_byte_idx] |= (pixel << aligned_shift)
+    return bytes(aligned)
+
+
+# Build groups for compression
+if compress and not is2Bit:
+    print("Error: --compress requires --2bit (byte-aligned compression only supports 2-bit format)", file=sys.stderr)
+    sys.exit(1)
+if compress:
+    # Script-based grouping: glyphs that co-occur in typical text rendering
+    # are grouped together for efficient LRU caching on the embedded target.
+    # Since glyphs are in codepoint order, glyphs in the same Unicode block
+    # are contiguous in the array and form natural groups.
+    SCRIPT_GROUP_RANGES = [
+        (0x0000, 0x007F),   # ASCII
+        (0x0080, 0x00FF),   # Latin-1 Supplement
+        (0x0100, 0x017F),   # Latin Extended-A
+        (0x0180, 0x024F),   # Latin Extended-B
+        (0x0300, 0x036F),   # Combining Diacritical Marks
+        (0x0400, 0x04FF),   # Cyrillic
+        (0x1EA0, 0x1EF9),   # Vietnamese Extended
+        (0x2000, 0x206F),   # General Punctuation
+        (0x2070, 0x209F),   # Superscripts & Subscripts
+        (0x20A0, 0x20CF),   # Currency Symbols
+        (0x2190, 0x21FF),   # Arrows
+        (0x2200, 0x22FF),   # Math Operators
+        (0xFB00, 0xFB06),   # Alphabetic Presentation Forms (ligatures)
+        (0xFFFD, 0xFFFD),   # Replacement Character
+    ]
+
+    def get_script_group(code_point):
+        for i, (start, end) in enumerate(SCRIPT_GROUP_RANGES):
+            if start <= code_point <= end:
+                return i
+        return -1
+
+    groups = []  # list of (first_glyph_index, glyph_count)
+    current_group_id = None
+    group_start = 0
+    group_count = 0
+
+    for i, (props, packed) in enumerate(all_glyphs):
+        sg = get_script_group(props.code_point)
+        if sg != current_group_id:
+            if group_count > 0:
+                groups.append((group_start, group_count))
+            current_group_id = sg
+            group_start = i
+            group_count = 1
+        else:
+            group_count += 1
+
+    if group_count > 0:
+        groups.append((group_start, group_count))
+
+    # Compress each group
+    compressed_groups = []  # list of (compressed_bytes, uncompressed_size, glyph_count, first_glyph_index)
+    compressed_bitmap_data = []
+    compressed_offset = 0
+
+    # Also build modified glyph props with within-group offsets
+    modified_glyph_props = list(glyph_props)
+
+    for first_idx, count in groups:
+        # Concatenate bitmap data for this group
+        packed_len = 0
+        group_aligned = bytearray()
+        for gi in range(first_idx, first_idx + count):
+            props, packed = all_glyphs[gi]
+            # Update glyph's dataOffset to be within-group offset (packed offset)
+            within_group_offset = packed_len
+            old_props = modified_glyph_props[gi]
+            modified_glyph_props[gi] = GlyphProps(
+                width=old_props.width,
+                height=old_props.height,
+                advance_x=old_props.advance_x,
+                left=old_props.left,
+                top=old_props.top,
+                data_length=old_props.data_length,
+                data_offset=within_group_offset,
+                code_point=old_props.code_point,
+            )
+            packed_len += len(packed)
+            group_aligned.extend(to_byte_aligned(packed, old_props.width, old_props.height))
+
+        # Compress byte-aligned data with raw DEFLATE (no zlib/gzip header)
+        compressor = zlib.compressobj(level=9, wbits=-15)
+        compressed = compressor.compress(bytes(group_aligned)) + compressor.flush()
+
+        compressed_groups.append((compressed, len(group_aligned), count, first_idx))
+        compressed_bitmap_data.extend(compressed)
+        compressed_offset += len(compressed)
+
+    glyph_props = modified_glyph_props
+    total_compressed = len(compressed_bitmap_data)
+    total_uncompressed = len(glyph_data)
+    print(f"// Compression: {total_uncompressed} -> {total_compressed} bytes ({100*total_compressed/total_uncompressed:.1f}%), {len(groups)} groups", file=sys.stderr)
+
+print(f"""/**
+ * generated by fontconvert.py
+ * name: {font_name}
+ * size: {size}
+ * mode: {'2-bit' if is2Bit else '1-bit'}{'  compressed: true' if compress else ''}
+ * Command used: {' '.join(sys.argv)}
+ */
+#pragma once
+#include "EpdFontData.h"
+""")
+
+if compress:
+    print(f"static const uint8_t {font_name}Bitmaps[{len(compressed_bitmap_data)}] = {{")
+    for c in chunks(compressed_bitmap_data, 16):
+        print ("    " + " ".join(f"0x{b:02X}," for b in c))
+    print ("};\n");
+else:
+    print(f"static const uint8_t {font_name}Bitmaps[{len(glyph_data)}] = {{")
+    for c in chunks(glyph_data, 16):
+        print ("    " + " ".join(f"0x{b:02X}," for b in c))
+    print ("};\n");
+
+def cp_label(cp):
+    if cp == 0x5C:
+        return '<backslash>'
+    return chr(cp) if 0x20 < cp < 0x7F else f'U+{cp:04X}'
 
 print(f"static const EpdGlyph {font_name}Glyphs[] = {{")
 for i, g in enumerate(glyph_props):
-    print ("    { " + ", ".join([f"{a}" for a in list(g[:-1])]),"},", f"// {chr(g.code_point) if g.code_point != 92 else '<backslash>'}")
+    print ("    { " + ", ".join([f"{a}" for a in list(g[:-1])]),"},", f"// {cp_label(g.code_point)}")
 print ("};\n");
 
 print(f"static const EpdUnicodeInterval {font_name}Intervals[] = {{")
@@ -285,6 +850,38 @@ for i_start, i_end in intervals:
     offset += i_end - i_start + 1
 print ("};\n");
 
+if compress:
+    print(f"static const EpdFontGroup {font_name}Groups[] = {{")
+    compressed_offset = 0
+    for compressed, uncompressed_size, count, first_idx in compressed_groups:
+        print(f"    {{ {compressed_offset}, {len(compressed)}, {uncompressed_size}, {count}, {first_idx} }},")
+        compressed_offset += len(compressed)
+    print("};\n")
+
+if kern_map:
+    print(f"static const EpdKernClassEntry {font_name}KernLeftClasses[] = {{")
+    for cp, cls in kern_left_classes:
+        print(f"    {{ 0x{cp:04X}, {cls} }}, // {cp_label(cp)}")
+    print("};\n")
+
+    print(f"static const EpdKernClassEntry {font_name}KernRightClasses[] = {{")
+    for cp, cls in kern_right_classes:
+        print(f"    {{ 0x{cp:04X}, {cls} }}, // {cp_label(cp)}")
+    print("};\n")
+
+    print(f"static const int8_t {font_name}KernMatrix[] = {{")
+    for row in range(kern_left_class_count):
+        row_start = row * kern_right_class_count
+        row_vals = kern_matrix[row_start:row_start + kern_right_class_count]
+        print("    " + ", ".join(f"{v:4d}" for v in row_vals) + ",")
+    print("};\n")
+
+if ligature_pairs:
+    print(f"static const EpdLigaturePair {font_name}LigaturePairs[] = {{")
+    for packed_pair, lig_cp in ligature_pairs:
+        print(f"    {{ 0x{packed_pair:08X}, 0x{lig_cp:04X} }}, // {cp_label(packed_pair >> 16)} {cp_label(packed_pair & 0xFFFF)} -> {cp_label(lig_cp)}")
+    print("};\n")
+
 print(f"static const EpdFontData {font_name} = {{")
 print(f"    {font_name}Bitmaps,")
 print(f"    {font_name}Glyphs,")
@@ -294,4 +891,34 @@ print(f"    {norm_ceil(face.size.height)},")
 print(f"    {norm_ceil(face.size.ascender)},")
 print(f"    {norm_floor(face.size.descender)},")
 print(f"    {'true' if is2Bit else 'false'},")
+if compress:
+    print(f"    {font_name}Groups,")
+    print(f"    {len(compressed_groups)},")
+else:
+    print("    nullptr,")
+    print("    0,")
+# glyphToGroup (not used for script-grouped fonts)
+print("    nullptr,")
+if kern_map:
+    print(f"    {font_name}KernLeftClasses,")
+    print(f"    {font_name}KernRightClasses,")
+    print(f"    {font_name}KernMatrix,")
+    print(f"    {len(kern_left_classes)},")
+    print(f"    {len(kern_right_classes)},")
+    print(f"    {kern_left_class_count},")
+    print(f"    {kern_right_class_count},")
+else:
+    print(f"    nullptr,")
+    print(f"    nullptr,")
+    print(f"    nullptr,")
+    print(f"    0,")
+    print(f"    0,")
+    print(f"    0,")
+    print(f"    0,")
+if ligature_pairs:
+    print(f"    {font_name}LigaturePairs,")
+    print(f"    {len(ligature_pairs)},")
+else:
+    print(f"    nullptr,")
+    print(f"    0,")
 print("};")

lib/EpdFont/scripts/verify_compression.py

@@ -0,0 +1,268 @@
+#!/usr/bin/env python3
+"""
+Round-trip verification for compressed font headers.
+
+Parses each generated .h file in the given directory, identifies compressed fonts
+(those with a Groups array), decompresses each group (byte-aligned bitmap format),
+compacts to packed format, and verifies the data matches expected glyph sizes.
+
+Supports both contiguous-group fonts (Latin) and frequency-grouped fonts (CJK)
+with glyphToGroup mapping arrays.
+"""
+import math
+import os
+import re
+import sys
+import zlib
+
+
+def parse_hex_array(text):
+    """Extract bytes from a C hex array string like '{ 0xAB, 0xCD, ... }'"""
+    hex_vals = re.findall(r'0x([0-9A-Fa-f]{2})', text)
+    return bytes(int(h, 16) for h in hex_vals)
+
+
+def parse_uint8_array(text):
+    """Extract uint8/uint16 values from a C array string like '{ 0, 1, 0xFF, ... }'"""
+    return [int(v, 0) for v in re.findall(r'\b0x[0-9A-Fa-f]+\b|\b\d+\b', text)]
+
+
+def parse_groups(text):
+    """Parse EpdFontGroup array entries: { compressedOffset, compressedSize, uncompressedSize, glyphCount, firstGlyphIndex }"""
+    groups = []
+    for match in re.finditer(r'\{\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)\s*\}', text):
+        groups.append({
+            'compressedOffset': int(match.group(1)),
+            'compressedSize': int(match.group(2)),
+            'uncompressedSize': int(match.group(3)),
+            'glyphCount': int(match.group(4)),
+            'firstGlyphIndex': int(match.group(5)),
+        })
+    return groups
+
+
+def parse_glyphs(text):
+    """Parse EpdGlyph array entries: { width, height, advanceX, left, top, dataLength, dataOffset }"""
+    glyphs = []
+    for match in re.finditer(r'\{\s*(-?\d+)\s*,\s*(-?\d+)\s*,\s*(-?\d+)\s*,\s*(-?\d+)\s*,\s*(-?\d+)\s*,\s*(-?\d+)\s*,\s*(-?\d+)\s*\}', text):
+        glyphs.append({
+            'width': int(match.group(1)),
+            'height': int(match.group(2)),
+            'advanceX': int(match.group(3)),
+            'left': int(match.group(4)),
+            'top': int(match.group(5)),
+            'dataLength': int(match.group(6)),
+            'dataOffset': int(match.group(7)),
+        })
+    return glyphs
+
+
+def get_group_glyph_indices(group, group_index, glyphs, glyph_to_group):
+    """Get the ordered list of glyph indices belonging to a group."""
+    if glyph_to_group is not None:
+        # Frequency-grouped: scan all glyphs
+        return [i for i in range(len(glyphs)) if glyph_to_group[i] == group_index]
+    else:
+        # Contiguous: sequential from firstGlyphIndex
+        first = group['firstGlyphIndex']
+        return list(range(first, first + group['glyphCount']))
+
+
+def compact_aligned_to_packed(aligned_data, width, height):
+    """Convert byte-aligned 2-bit bitmap to packed format (reverse of to_byte_aligned).
+
+    In byte-aligned format, each row starts at a byte boundary.
+    In packed format, pixels flow continuously across row boundaries (4 pixels/byte).
+    """
+    if width == 0 or height == 0:
+        return b''
+    packed_size = math.ceil(width * height / 4)
+    packed = bytearray(packed_size)
+    row_stride = (width + 3) // 4  # bytes per byte-aligned row
+
+    for y in range(height):
+        for x in range(width):
+            # Read pixel from byte-aligned format (row-aligned)
+            aligned_byte_idx = y * row_stride + x // 4
+            aligned_shift = (3 - (x % 4)) * 2
+            pixel = (aligned_data[aligned_byte_idx] >> aligned_shift) & 0x3
+
+            # Write pixel to packed format (continuous bit stream)
+            packed_pos = y * width + x
+            packed_byte_idx = packed_pos // 4
+            packed_shift = (3 - (packed_pos % 4)) * 2
+            packed[packed_byte_idx] |= (pixel << packed_shift)
+
+    return bytes(packed)
+
+
+def verify_font_file(filepath):
+    """Verify a single font header file. Returns (font_name, success, message)."""
+    with open(filepath, 'r') as f:
+        content = f.read()
+
+    # Check if this is a compressed font (has Groups array)
+    groups_match = re.search(r'static const EpdFontGroup (\w+)Groups\[\]', content)
+    if not groups_match:
+        return (os.path.basename(filepath), None, "uncompressed, skipping")
+
+    font_name = groups_match.group(1)
+
+    # Extract bitmap data
+    bitmap_match = re.search(
+        r'static const uint8_t ' + re.escape(font_name) + r'Bitmaps\[\d+\]\s*=\s*\{([^}]+)\}',
+        content, re.DOTALL
+    )
+    if not bitmap_match:
+        return (font_name, False, "could not find Bitmaps array")
+
+    compressed_data = parse_hex_array(bitmap_match.group(1))
+
+    # Extract groups
+    groups_array_match = re.search(
+        r'static const EpdFontGroup ' + re.escape(font_name) + r'Groups\[\]\s*=\s*\{(.+?)\};',
+        content, re.DOTALL
+    )
+    if not groups_array_match:
+        return (font_name, False, "could not find Groups array")
+
+    groups = parse_groups(groups_array_match.group(1))
+    if not groups:
+        return (font_name, False, "Groups array parsed to 0 entries; check format")
+
+    # Extract glyphs
+    glyphs_match = re.search(
+        r'static const EpdGlyph ' + re.escape(font_name) + r'Glyphs\[\]\s*=\s*\{(.+?)\};',
+        content, re.DOTALL
+    )
+    if not glyphs_match:
+        return (font_name, False, "could not find Glyphs array")
+
+    glyphs = parse_glyphs(glyphs_match.group(1))
+
+    # Check for glyphToGroup array (frequency-grouped fonts)
+    glyph_to_group = None
+    g2g_match = re.search(
+        r'static const uint16_t ' + re.escape(font_name) + r'GlyphToGroup\[\]\s*=\s*\{(.+?)\};',
+        content, re.DOTALL
+    )
+    if g2g_match:
+        glyph_to_group = parse_uint8_array(g2g_match.group(1))
+        if len(glyph_to_group) != len(glyphs):
+            return (font_name, False, f"glyphToGroup length ({len(glyph_to_group)}) != glyph count ({len(glyphs)})")
+        max_group_id = max(glyph_to_group)
+        if max_group_id >= len(groups):
+            return (font_name, False, f"glyphToGroup contains group ID {max_group_id} but only {len(groups)} groups exist")
+
+    # Verify each group
+    for gi, group in enumerate(groups):
+        # Extract compressed chunk
+        chunk = compressed_data[group['compressedOffset']:group['compressedOffset'] + group['compressedSize']]
+        if len(chunk) != group['compressedSize']:
+            return (font_name, False, f"group {gi}: compressed data truncated (expected {group['compressedSize']}, got {len(chunk)})")
+
+        # Decompress with raw DEFLATE — result is byte-aligned data
+        try:
+            decompressed = zlib.decompress(chunk, -15)
+        except zlib.error as e:
+            return (font_name, False, f"group {gi}: decompression failed: {e}")
+
+        if len(decompressed) != group['uncompressedSize']:
+            return (font_name, False, f"group {gi}: size mismatch (expected {group['uncompressedSize']}, got {len(decompressed)})")
+
+        # Get glyph indices for this group
+        group_glyph_indices = get_group_glyph_indices(group, gi, glyphs, glyph_to_group)
+        if glyph_to_group is not None and len(group_glyph_indices) != group['glyphCount']:
+            return (font_name, False,
+                    f"group {gi}: glyphCount {group['glyphCount']} != mapping count {len(group_glyph_indices)}")
+
+        # Walk through byte-aligned data, compact each glyph, and verify against packed format
+        byte_aligned_offset = 0
+        packed_offset = 0
+
+        for glyph_idx in group_glyph_indices:
+            if glyph_idx >= len(glyphs):
+                return (font_name, False, f"group {gi}: glyph index {glyph_idx} out of range")
+            glyph = glyphs[glyph_idx]
+            width = glyph['width']
+            height = glyph['height']
+
+            if width == 0 or height == 0:
+                # Zero-size glyphs should have dataOffset == current packed_offset and dataLength == 0
+                if glyph['dataOffset'] != packed_offset:
+                    return (font_name, False, f"group {gi}, glyph {glyph_idx}: zero-size glyph dataOffset {glyph['dataOffset']} != expected packed offset {packed_offset}")
+                if glyph['dataLength'] != 0:
+                    return (font_name, False, f"group {gi}, glyph {glyph_idx}: zero-size glyph dataLength {glyph['dataLength']} != expected 0")
+                continue
+
+            aligned_size = ((width + 3) // 4) * height
+            packed_size = math.ceil(width * height / 4)
+
+            # Verify packed offset and size match glyph metadata
+            if glyph['dataOffset'] != packed_offset:
+                return (font_name, False, f"group {gi}, glyph {glyph_idx}: dataOffset {glyph['dataOffset']} != expected packed offset {packed_offset}")
+            if glyph['dataLength'] != packed_size:
+                return (font_name, False, f"group {gi}, glyph {glyph_idx}: dataLength {glyph['dataLength']} != expected packed length {packed_size} "
+                        f"(width={width}, height={height})")
+
+            # Extract byte-aligned data for this glyph
+            if byte_aligned_offset + aligned_size > len(decompressed):
+                return (font_name, False, f"group {gi}, glyph {glyph_idx}: byte-aligned data extends beyond decompressed buffer "
+                        f"(offset={byte_aligned_offset}, size={aligned_size}, buf_size={len(decompressed)})")
+
+            aligned_glyph = decompressed[byte_aligned_offset:byte_aligned_offset + aligned_size]
+
+            # Compact to packed and verify pixel values are valid (0-3 for 2-bit)
+            packed_glyph = compact_aligned_to_packed(aligned_glyph, width, height)
+            if len(packed_glyph) != packed_size:
+                return (font_name, False, f"group {gi}, glyph {glyph_idx}: compacted size {len(packed_glyph)} != expected {packed_size}")
+
+            byte_aligned_offset += aligned_size
+            packed_offset += packed_size
+
+        # Verify total byte-aligned size matches uncompressedSize
+        if byte_aligned_offset != group['uncompressedSize']:
+            return (font_name, False, f"group {gi}: total byte-aligned size {byte_aligned_offset} != uncompressedSize {group['uncompressedSize']}")
+
+    extra_info = ""
+    if glyph_to_group is not None:
+        extra_info = " (frequency-grouped)"
+    return (font_name, True, f"{len(groups)} groups, {len(glyphs)} glyphs OK{extra_info}")
+
+
+def main():
+    if len(sys.argv) < 2:
+        print(f"Usage: {sys.argv[0]} <font_headers_directory>", file=sys.stderr)
+        sys.exit(1)
+
+    font_dir = sys.argv[1]
+    if not os.path.isdir(font_dir):
+        print(f"Error: {font_dir} is not a directory", file=sys.stderr)
+        sys.exit(1)
+
+    files = sorted(f for f in os.listdir(font_dir) if f.endswith('.h') and f != 'all.h')
+    passed = 0
+    failed = 0
+    skipped = 0
+
+    for filename in files:
+        filepath = os.path.join(font_dir, filename)
+        _font_name, success, message = verify_font_file(filepath)
+
+        if success is None:
+            skipped += 1
+        elif success:
+            passed += 1
+            print(f"  PASS: {filename} ({message})")
+        else:
+            failed += 1
+            print(f"  FAIL: {filename} - {message}")
+
+    print(f"\nResults: {passed} passed, {failed} failed, {skipped} skipped (uncompressed)")
+
+    if failed > 0:
+        sys.exit(1)
+
+
+if __name__ == '__main__':
+    main()

lib/Epub/Epub.cpp

@@ -1,9 +1,10 @@
 #include "Epub.h"
 
 #include <FsHelpers.h>
-#include <HardwareSerial.h>
+#include <HalStorage.h>
 #include <JpegToBmpConverter.h>
-#include <SDCardManager.h>
+#include <Logging.h>
+#include <PngToBmpConverter.h>
 #include <ZipFile.h>
 
 #include "Epub/parsers/ContainerParser.h"
@@ -17,7 +18,7 @@ bool Epub::findContentOpfFile(std::string* contentOpfFile) const {
 
   // Get file size without loading it all into heap
   if (!getItemSize(containerPath, &containerSize)) {
-    Serial.printf("[%lu] [EBP] Could not find or size META-INF/container.xml\n", millis());
+    LOG_ERR("EBP", "Could not find or size META-INF/container.xml");
     return false;
   }
 
@@ -29,13 +30,13 @@ bool Epub::findContentOpfFile(std::string* contentOpfFile) const {
 
   // Stream read (reusing your existing stream logic)
   if (!readItemContentsToStream(containerPath, containerParser, 512)) {
-    Serial.printf("[%lu] [EBP] Could not read META-INF/container.xml\n", millis());
+    LOG_ERR("EBP", "Could not read META-INF/container.xml");
     return false;
   }
 
   // Extract the result
   if (containerParser.fullPath.empty()) {
-    Serial.printf("[%lu] [EBP] Could not find valid rootfile in container.xml\n", millis());
+    LOG_ERR("EBP", "Could not find valid rootfile in container.xml");
     return false;
   }
 
@@ -46,35 +47,81 @@ bool Epub::findContentOpfFile(std::string* contentOpfFile) const {
 bool Epub::parseContentOpf(BookMetadataCache::BookMetadata& bookMetadata) {
   std::string contentOpfFilePath;
   if (!findContentOpfFile(&contentOpfFilePath)) {
-    Serial.printf("[%lu] [EBP] Could not find content.opf in zip\n", millis());
+    LOG_ERR("EBP", "Could not find content.opf in zip");
     return false;
   }
 
   contentBasePath = contentOpfFilePath.substr(0, contentOpfFilePath.find_last_of('/') + 1);
 
-  Serial.printf("[%lu] [EBP] Parsing content.opf: %s\n", millis(), contentOpfFilePath.c_str());
+  LOG_DBG("EBP", "Parsing content.opf: %s", contentOpfFilePath.c_str());
 
   size_t contentOpfSize;
   if (!getItemSize(contentOpfFilePath, &contentOpfSize)) {
-    Serial.printf("[%lu] [EBP] Could not get size of content.opf\n", millis());
+    LOG_ERR("EBP", "Could not get size of content.opf");
     return false;
   }
 
   ContentOpfParser opfParser(getCachePath(), getBasePath(), contentOpfSize, bookMetadataCache.get());
   if (!opfParser.setup()) {
-    Serial.printf("[%lu] [EBP] Could not setup content.opf parser\n", millis());
+    LOG_ERR("EBP", "Could not setup content.opf parser");
     return false;
   }
 
   if (!readItemContentsToStream(contentOpfFilePath, opfParser, 1024)) {
-    Serial.printf("[%lu] [EBP] Could not read content.opf\n", millis());
+    LOG_ERR("EBP", "Could not read content.opf");
     return false;
   }
 
   // Grab data from opfParser into epub
   bookMetadata.title = opfParser.title;
   bookMetadata.author = opfParser.author;
+  bookMetadata.language = opfParser.language;
   bookMetadata.coverItemHref = opfParser.coverItemHref;
+
+  // Guide-based cover fallback: if no cover found via metadata/properties,
+  // try extracting the image reference from the guide's cover page XHTML
+  if (bookMetadata.coverItemHref.empty() && !opfParser.guideCoverPageHref.empty()) {
+    LOG_DBG("EBP", "No cover from metadata, trying guide cover page: %s", opfParser.guideCoverPageHref.c_str());
+    size_t coverPageSize;
+    uint8_t* coverPageData = readItemContentsToBytes(opfParser.guideCoverPageHref, &coverPageSize, true);
+    if (coverPageData) {
+      const std::string coverPageHtml(reinterpret_cast<char*>(coverPageData), coverPageSize);
+      free(coverPageData);
+
+      // Determine base path of the cover page for resolving relative image references
+      std::string coverPageBase;
+      const auto lastSlash = opfParser.guideCoverPageHref.rfind('/');
+      if (lastSlash != std::string::npos) {
+        coverPageBase = opfParser.guideCoverPageHref.substr(0, lastSlash + 1);
+      }
+
+      // Search for image references: xlink:href="..." (SVG) and src="..." (img)
+      std::string imageRef;
+      for (const char* pattern : {"xlink:href=\"", "src=\""}) {
+        auto pos = coverPageHtml.find(pattern);
+        while (pos != std::string::npos) {
+          pos += strlen(pattern);
+          const auto endPos = coverPageHtml.find('"', pos);
+          if (endPos != std::string::npos) {
+            const auto ref = std::string_view{coverPageHtml}.substr(pos, endPos - pos);
+            // Check if it's an image file
+            if (FsHelpers::hasPngExtension(ref) || FsHelpers::hasJpgExtension(ref) || FsHelpers::hasGifExtension(ref)) {
+              imageRef = ref;
+              break;
+            }
+          }
+          pos = coverPageHtml.find(pattern, pos);
+        }
+        if (!imageRef.empty()) break;
+      }
+
+      if (!imageRef.empty()) {
+        bookMetadata.coverItemHref = FsHelpers::normalisePath(coverPageBase + imageRef);
+        LOG_DBG("EBP", "Found cover image from guide: %s", bookMetadata.coverItemHref.c_str());
+      }
+    }
+  }
+
   bookMetadata.textReferenceHref = opfParser.textReferenceHref;
 
   if (!opfParser.tocNcxPath.empty()) {
@@ -85,27 +132,31 @@ bool Epub::parseContentOpf(BookMetadataCache::BookMetadata& bookMetadata) {
     tocNavItem = opfParser.tocNavPath;
   }
 
-  Serial.printf("[%lu] [EBP] Successfully parsed content.opf\n", millis());
+  if (!opfParser.cssFiles.empty()) {
+    cssFiles = opfParser.cssFiles;
+  }
+
+  LOG_DBG("EBP", "Successfully parsed content.opf");
   return true;
 }
 
 bool Epub::parseTocNcxFile() const {
   // the ncx file should have been specified in the content.opf file
   if (tocNcxItem.empty()) {
-    Serial.printf("[%lu] [EBP] No ncx file specified\n", millis());
+    LOG_DBG("EBP", "No ncx file specified");
     return false;
   }
 
-  Serial.printf("[%lu] [EBP] Parsing toc ncx file: %s\n", millis(), tocNcxItem.c_str());
+  LOG_DBG("EBP", "Parsing toc ncx file: %s", tocNcxItem.c_str());
 
   const auto tmpNcxPath = getCachePath() + "/toc.ncx";
   FsFile tempNcxFile;
-  if (!SdMan.openFileForWrite("EBP", tmpNcxPath, tempNcxFile)) {
+  if (!Storage.openFileForWrite("EBP", tmpNcxPath, tempNcxFile)) {
     return false;
   }
   readItemContentsToStream(tocNcxItem, tempNcxFile, 1024);
   tempNcxFile.close();
-  if (!SdMan.openFileForRead("EBP", tmpNcxPath, tempNcxFile)) {
+  if (!Storage.openFileForRead("EBP", tmpNcxPath, tempNcxFile)) {
     return false;
   }
   const auto ncxSize = tempNcxFile.size();
@@ -113,14 +164,14 @@ bool Epub::parseTocNcxFile() const {
   TocNcxParser ncxParser(contentBasePath, ncxSize, bookMetadataCache.get());
 
   if (!ncxParser.setup()) {
-    Serial.printf("[%lu] [EBP] Could not setup toc ncx parser\n", millis());
+    LOG_ERR("EBP", "Could not setup toc ncx parser");
     tempNcxFile.close();
     return false;
   }
 
   const auto ncxBuffer = static_cast<uint8_t*>(malloc(1024));
   if (!ncxBuffer) {
-    Serial.printf("[%lu] [EBP] Could not allocate memory for toc ncx parser\n", millis());
+    LOG_ERR("EBP", "Could not allocate memory for toc ncx parser");
     tempNcxFile.close();
     return false;
   }
@@ -131,7 +182,7 @@ bool Epub::parseTocNcxFile() const {
     const auto processedSize = ncxParser.write(ncxBuffer, readSize);
 
     if (processedSize != readSize) {
-      Serial.printf("[%lu] [EBP] Could not process all toc ncx data\n", millis());
+      LOG_ERR("EBP", "Could not process all toc ncx data");
       free(ncxBuffer);
       tempNcxFile.close();
       return false;
@@ -140,29 +191,29 @@ bool Epub::parseTocNcxFile() const {
 
   free(ncxBuffer);
   tempNcxFile.close();
-  SdMan.remove(tmpNcxPath.c_str());
+  Storage.remove(tmpNcxPath.c_str());
 
-  Serial.printf("[%lu] [EBP] Parsed TOC items\n", millis());
+  LOG_DBG("EBP", "Parsed TOC items");
   return true;
 }
 
 bool Epub::parseTocNavFile() const {
   // the nav file should have been specified in the content.opf file (EPUB 3)
   if (tocNavItem.empty()) {
-    Serial.printf("[%lu] [EBP] No nav file specified\n", millis());
+    LOG_DBG("EBP", "No nav file specified");
     return false;
   }
 
-  Serial.printf("[%lu] [EBP] Parsing toc nav file: %s\n", millis(), tocNavItem.c_str());
+  LOG_DBG("EBP", "Parsing toc nav file: %s", tocNavItem.c_str());
 
   const auto tmpNavPath = getCachePath() + "/toc.nav";
   FsFile tempNavFile;
-  if (!SdMan.openFileForWrite("EBP", tmpNavPath, tempNavFile)) {
+  if (!Storage.openFileForWrite("EBP", tmpNavPath, tempNavFile)) {
     return false;
   }
   readItemContentsToStream(tocNavItem, tempNavFile, 1024);
   tempNavFile.close();
-  if (!SdMan.openFileForRead("EBP", tmpNavPath, tempNavFile)) {
+  if (!Storage.openFileForRead("EBP", tmpNavPath, tempNavFile)) {
     return false;
   }
   const auto navSize = tempNavFile.size();
@@ -173,13 +224,13 @@ bool Epub::parseTocNavFile() const {
   TocNavParser navParser(navContentBasePath, navSize, bookMetadataCache.get());
 
   if (!navParser.setup()) {
-    Serial.printf("[%lu] [EBP] Could not setup toc nav parser\n", millis());
+    LOG_ERR("EBP", "Could not setup toc nav parser");
     return false;
   }
 
   const auto navBuffer = static_cast<uint8_t*>(malloc(1024));
   if (!navBuffer) {
-    Serial.printf("[%lu] [EBP] Could not allocate memory for toc nav parser\n", millis());
+    LOG_ERR("EBP", "Could not allocate memory for toc nav parser");
     return false;
   }
 
@@ -188,7 +239,7 @@ bool Epub::parseTocNavFile() const {
     const auto processedSize = navParser.write(navBuffer, readSize);
 
     if (processedSize != readSize) {
-      Serial.printf("[%lu] [EBP] Could not process all toc nav data\n", millis());
+      LOG_ERR("EBP", "Could not process all toc nav data");
       free(navBuffer);
       tempNavFile.close();
       return false;
@@ -197,22 +248,115 @@ bool Epub::parseTocNavFile() const {
 
   free(navBuffer);
   tempNavFile.close();
-  SdMan.remove(tmpNavPath.c_str());
+  Storage.remove(tmpNavPath.c_str());
 
-  Serial.printf("[%lu] [EBP] Parsed TOC nav items\n", millis());
+  LOG_DBG("EBP", "Parsed TOC nav items");
   return true;
 }
 
+void Epub::parseCssFiles() const {
+  // Maximum CSS file size we'll attempt to parse (uncompressed)
+  // Larger files risk memory exhaustion on ESP32
+  constexpr size_t MAX_CSS_FILE_SIZE = 128 * 1024;  // 128KB
+  // Minimum heap required before attempting CSS parsing
+  constexpr size_t MIN_HEAP_FOR_CSS_PARSING = 64 * 1024;  // 64KB
+
+  if (cssFiles.empty()) {
+    LOG_DBG("EBP", "No CSS files to parse, but CssParser created for inline styles");
+  }
+
+  LOG_DBG("EBP", "CSS files to parse: %zu", cssFiles.size());
+
+  // See if we have a cached version of the CSS rules
+  if (cssParser->hasCache()) {
+    LOG_DBG("EBP", "CSS cache exists, skipping parseCssFiles");
+    return;
+  }
+
+  // No cache yet - parse CSS files
+  for (const auto& cssPath : cssFiles) {
+    LOG_DBG("EBP", "Parsing CSS file: %s", cssPath.c_str());
+
+    // Check heap before parsing - CSS parsing allocates heavily
+    const uint32_t freeHeap = ESP.getFreeHeap();
+    if (freeHeap < MIN_HEAP_FOR_CSS_PARSING) {
+      LOG_ERR("EBP", "Insufficient heap for CSS parsing (%u bytes free, need %zu), skipping: %s", freeHeap,
+              MIN_HEAP_FOR_CSS_PARSING, cssPath.c_str());
+      continue;
+    }
+
+    // Check CSS file size before decompressing - skip files that are too large
+    size_t cssFileSize = 0;
+    if (getItemSize(cssPath, &cssFileSize)) {
+      if (cssFileSize > MAX_CSS_FILE_SIZE) {
+        LOG_ERR("EBP", "CSS file too large (%zu bytes > %zu max), skipping: %s", cssFileSize, MAX_CSS_FILE_SIZE,
+                cssPath.c_str());
+        continue;
+      }
+    }
+
+    // Extract CSS file to temp location
+    const auto tmpCssPath = getCachePath() + "/.tmp.css";
+    FsFile tempCssFile;
+    if (!Storage.openFileForWrite("EBP", tmpCssPath, tempCssFile)) {
+      LOG_ERR("EBP", "Could not create temp CSS file");
+      continue;
+    }
+    if (!readItemContentsToStream(cssPath, tempCssFile, 1024)) {
+      LOG_ERR("EBP", "Could not read CSS file: %s", cssPath.c_str());
+      tempCssFile.close();
+      Storage.remove(tmpCssPath.c_str());
+      continue;
+    }
+    tempCssFile.close();
+
+    // Parse the CSS file
+    if (!Storage.openFileForRead("EBP", tmpCssPath, tempCssFile)) {
+      LOG_ERR("EBP", "Could not open temp CSS file for reading");
+      Storage.remove(tmpCssPath.c_str());
+      continue;
+    }
+    cssParser->loadFromStream(tempCssFile);
+    tempCssFile.close();
+    Storage.remove(tmpCssPath.c_str());
+  }
+
+  // Save to cache for next time
+  if (!cssParser->saveToCache()) {
+    LOG_ERR("EBP", "Failed to save CSS rules to cache");
+  }
+  cssParser->clear();
+
+  LOG_DBG("EBP", "Loaded %zu CSS style rules from %zu files", cssParser->ruleCount(), cssFiles.size());
+}
+
 // load in the meta data for the epub file
-bool Epub::load(const bool buildIfMissing) {
-  Serial.printf("[%lu] [EBP] Loading ePub: %s\n", millis(), filepath.c_str());
+bool Epub::load(const bool buildIfMissing, const bool skipLoadingCss) {
+  LOG_DBG("EBP", "Loading ePub: %s", filepath.c_str());
 
   // Initialize spine/TOC cache
   bookMetadataCache.reset(new BookMetadataCache(cachePath));
+  // Always create CssParser - needed for inline style parsing even without CSS files
+  cssParser.reset(new CssParser(cachePath));
 
   // Try to load existing cache first
   if (bookMetadataCache->load()) {
-    Serial.printf("[%lu] [EBP] Loaded ePub: %s\n", millis(), filepath.c_str());
+    if (!skipLoadingCss) {
+      // Rebuild CSS cache when missing or when cache version changed (loadFromCache removes stale file)
+      if (!cssParser->hasCache() || !cssParser->loadFromCache()) {
+        LOG_DBG("EBP", "CSS rules cache missing or stale, attempting to parse CSS files");
+        cssParser->deleteCache();
+
+        if (!parseContentOpf(bookMetadataCache->coreMetadata)) {
+          LOG_ERR("EBP", "Could not parse content.opf from cached bookMetadata for CSS files");
+          // continue anyway - book will work without CSS and we'll still load any inline style CSS
+        }
+        parseCssFiles();
+        // Invalidate section caches so they are rebuilt with the new CSS
+        Storage.removeDir((cachePath + "/sections").c_str());
+      }
+    }
+    LOG_DBG("EBP", "Loaded ePub: %s", filepath.c_str());
     return true;
   }
 
@@ -222,33 +366,38 @@ bool Epub::load(const bool buildIfMissing) {
   }
 
   // Cache doesn't exist or is invalid, build it
-  Serial.printf("[%lu] [EBP] Cache not found, building spine/TOC cache\n", millis());
+  LOG_DBG("EBP", "Cache not found, building spine/TOC cache");
   setupCacheDir();
 
+  const uint32_t indexingStart = millis();
+
   // Begin building cache - stream entries to disk immediately
   if (!bookMetadataCache->beginWrite()) {
-    Serial.printf("[%lu] [EBP] Could not begin writing cache\n", millis());
+    LOG_ERR("EBP", "Could not begin writing cache");
     return false;
   }
 
   // OPF Pass
+  const uint32_t opfStart = millis();
   BookMetadataCache::BookMetadata bookMetadata;
   if (!bookMetadataCache->beginContentOpfPass()) {
-    Serial.printf("[%lu] [EBP] Could not begin writing content.opf pass\n", millis());
+    LOG_ERR("EBP", "Could not begin writing content.opf pass");
     return false;
   }
   if (!parseContentOpf(bookMetadata)) {
-    Serial.printf("[%lu] [EBP] Could not parse content.opf\n", millis());
+    LOG_ERR("EBP", "Could not parse content.opf");
     return false;
   }
   if (!bookMetadataCache->endContentOpfPass()) {
-    Serial.printf("[%lu] [EBP] Could not end writing content.opf pass\n", millis());
+    LOG_ERR("EBP", "Could not end writing content.opf pass");
     return false;
   }
+  LOG_DBG("EBP", "OPF pass completed in %lu ms", millis() - opfStart);
 
   // TOC Pass - try EPUB 3 nav first, fall back to NCX
+  const uint32_t tocStart = millis();
   if (!bookMetadataCache->beginTocPass()) {
-    Serial.printf("[%lu] [EBP] Could not begin writing toc pass\n", millis());
+    LOG_ERR("EBP", "Could not begin writing toc pass");
     return false;
   }
 
@@ -256,74 +405,84 @@ bool Epub::load(const bool buildIfMissing) {
 
   // Try EPUB 3 nav document first (preferred)
   if (!tocNavItem.empty()) {
-    Serial.printf("[%lu] [EBP] Attempting to parse EPUB 3 nav document\n", millis());
+    LOG_DBG("EBP", "Attempting to parse EPUB 3 nav document");
     tocParsed = parseTocNavFile();
   }
 
   // Fall back to NCX if nav parsing failed or wasn't available
   if (!tocParsed && !tocNcxItem.empty()) {
-    Serial.printf("[%lu] [EBP] Falling back to NCX TOC\n", millis());
+    LOG_DBG("EBP", "Falling back to NCX TOC");
     tocParsed = parseTocNcxFile();
   }
 
   if (!tocParsed) {
-    Serial.printf("[%lu] [EBP] Warning: Could not parse any TOC format\n", millis());
+    LOG_ERR("EBP", "Warning: Could not parse any TOC format");
     // Continue anyway - book will work without TOC
   }
 
   if (!bookMetadataCache->endTocPass()) {
-    Serial.printf("[%lu] [EBP] Could not end writing toc pass\n", millis());
+    LOG_ERR("EBP", "Could not end writing toc pass");
     return false;
   }
+  LOG_DBG("EBP", "TOC pass completed in %lu ms", millis() - tocStart);
 
   // Close the cache files
   if (!bookMetadataCache->endWrite()) {
-    Serial.printf("[%lu] [EBP] Could not end writing cache\n", millis());
+    LOG_ERR("EBP", "Could not end writing cache");
     return false;
   }
 
   // Build final book.bin
+  const uint32_t buildStart = millis();
   if (!bookMetadataCache->buildBookBin(filepath, bookMetadata)) {
-    Serial.printf("[%lu] [EBP] Could not update mappings and sizes\n", millis());
+    LOG_ERR("EBP", "Could not update mappings and sizes");
     return false;
   }
+  LOG_DBG("EBP", "buildBookBin completed in %lu ms", millis() - buildStart);
+  LOG_DBG("EBP", "Total indexing completed in %lu ms", millis() - indexingStart);
 
   if (!bookMetadataCache->cleanupTmpFiles()) {
-    Serial.printf("[%lu] [EBP] Could not cleanup tmp files - ignoring\n", millis());
+    LOG_DBG("EBP", "Could not cleanup tmp files - ignoring");
   }
 
   // Reload the cache from disk so it's in the correct state
   bookMetadataCache.reset(new BookMetadataCache(cachePath));
   if (!bookMetadataCache->load()) {
-    Serial.printf("[%lu] [EBP] Failed to reload cache after writing\n", millis());
+    LOG_ERR("EBP", "Failed to reload cache after writing");
     return false;
   }
 
-  Serial.printf("[%lu] [EBP] Loaded ePub: %s\n", millis(), filepath.c_str());
+  if (!skipLoadingCss) {
+    // Parse CSS files after cache reload
+    parseCssFiles();
+    Storage.removeDir((cachePath + "/sections").c_str());
+  }
+
+  LOG_DBG("EBP", "Loaded ePub: %s", filepath.c_str());
   return true;
 }
 
 bool Epub::clearCache() const {
-  if (!SdMan.exists(cachePath.c_str())) {
-    Serial.printf("[%lu] [EPB] Cache does not exist, no action needed\n", millis());
+  if (!Storage.exists(cachePath.c_str())) {
+    LOG_DBG("EPB", "Cache does not exist, no action needed");
     return true;
   }
 
-  if (!SdMan.removeDir(cachePath.c_str())) {
-    Serial.printf("[%lu] [EPB] Failed to clear cache\n", millis());
+  if (!Storage.removeDir(cachePath.c_str())) {
+    LOG_ERR("EPB", "Failed to clear cache");
     return false;
   }
 
-  Serial.printf("[%lu] [EPB] Cache cleared successfully\n", millis());
+  LOG_DBG("EPB", "Cache cleared successfully");
   return true;
 }
 
 void Epub::setupCacheDir() const {
-  if (SdMan.exists(cachePath.c_str())) {
+  if (Storage.exists(cachePath.c_str())) {
     return;
   }
 
-  SdMan.mkdir(cachePath.c_str());
+  Storage.mkdir(cachePath.c_str());
 }
 
 const std::string& Epub::getCachePath() const { return cachePath; }
@@ -348,70 +507,208 @@ const std::string& Epub::getAuthor() const {
   return bookMetadataCache->coreMetadata.author;
 }
 
+const std::string& Epub::getLanguage() const {
+  static std::string blank;
+  if (!bookMetadataCache || !bookMetadataCache->isLoaded()) {
+    return blank;
+  }
+
+  return bookMetadataCache->coreMetadata.language;
+}
+
 std::string Epub::getCoverBmpPath(bool cropped) const {
-  const auto coverFileName = "cover" + cropped ? "_crop" : "";
+  const auto coverFileName = std::string("cover") + (cropped ? "_crop" : "");
   return cachePath + "/" + coverFileName + ".bmp";
 }
 
 bool Epub::generateCoverBmp(bool cropped) const {
   // Already generated, return true
-  if (SdMan.exists(getCoverBmpPath(cropped).c_str())) {
+  if (Storage.exists(getCoverBmpPath(cropped).c_str())) {
     return true;
   }
 
   if (!bookMetadataCache || !bookMetadataCache->isLoaded()) {
-    Serial.printf("[%lu] [EBP] Cannot generate cover BMP, cache not loaded\n", millis());
+    LOG_ERR("EBP", "Cannot generate cover BMP, cache not loaded");
     return false;
   }
 
   const auto coverImageHref = bookMetadataCache->coreMetadata.coverItemHref;
   if (coverImageHref.empty()) {
-    Serial.printf("[%lu] [EBP] No known cover image\n", millis());
+    LOG_ERR("EBP", "No known cover image");
     return false;
   }
 
-  if (coverImageHref.substr(coverImageHref.length() - 4) == ".jpg" ||
-      coverImageHref.substr(coverImageHref.length() - 5) == ".jpeg") {
-    Serial.printf("[%lu] [EBP] Generating BMP from JPG cover image\n", millis());
+  if (FsHelpers::hasJpgExtension(coverImageHref)) {
+    LOG_DBG("EBP", "Generating BMP from JPG cover image (%s mode)", cropped ? "cropped" : "fit");
     const auto coverJpgTempPath = getCachePath() + "/.cover.jpg";
 
     FsFile coverJpg;
-    if (!SdMan.openFileForWrite("EBP", coverJpgTempPath, coverJpg)) {
+    if (!Storage.openFileForWrite("EBP", coverJpgTempPath, coverJpg)) {
       return false;
     }
     readItemContentsToStream(coverImageHref, coverJpg, 1024);
     coverJpg.close();
 
-    if (!SdMan.openFileForRead("EBP", coverJpgTempPath, coverJpg)) {
+    if (!Storage.openFileForRead("EBP", coverJpgTempPath, coverJpg)) {
       return false;
     }
 
     FsFile coverBmp;
-    if (!SdMan.openFileForWrite("EBP", getCoverBmpPath(cropped), coverBmp)) {
+    if (!Storage.openFileForWrite("EBP", getCoverBmpPath(cropped), coverBmp)) {
       coverJpg.close();
       return false;
     }
-    const bool success = JpegToBmpConverter::jpegFileToBmpStream(coverJpg, coverBmp);
+    const bool success = JpegToBmpConverter::jpegFileToBmpStream(coverJpg, coverBmp, cropped);
     coverJpg.close();
     coverBmp.close();
-    SdMan.remove(coverJpgTempPath.c_str());
+    Storage.remove(coverJpgTempPath.c_str());
 
     if (!success) {
-      Serial.printf("[%lu] [EBP] Failed to generate BMP from JPG cover image\n", millis());
-      SdMan.remove(getCoverBmpPath(cropped).c_str());
+      LOG_ERR("EBP", "Failed to generate BMP from cover image");
+      Storage.remove(getCoverBmpPath(cropped).c_str());
     }
-    Serial.printf("[%lu] [EBP] Generated BMP from JPG cover image, success: %s\n", millis(), success ? "yes" : "no");
+    LOG_DBG("EBP", "Generated BMP from JPG cover image, success: %s", success ? "yes" : "no");
     return success;
-  } else {
-    Serial.printf("[%lu] [EBP] Cover image is not a JPG, skipping\n", millis());
   }
 
+  if (FsHelpers::hasPngExtension(coverImageHref)) {
+    LOG_DBG("EBP", "Generating BMP from PNG cover image (%s mode)", cropped ? "cropped" : "fit");
+    const auto coverPngTempPath = getCachePath() + "/.cover.png";
+
+    FsFile coverPng;
+    if (!Storage.openFileForWrite("EBP", coverPngTempPath, coverPng)) {
+      return false;
+    }
+    readItemContentsToStream(coverImageHref, coverPng, 1024);
+    coverPng.close();
+
+    if (!Storage.openFileForRead("EBP", coverPngTempPath, coverPng)) {
+      return false;
+    }
+
+    FsFile coverBmp;
+    if (!Storage.openFileForWrite("EBP", getCoverBmpPath(cropped), coverBmp)) {
+      coverPng.close();
+      return false;
+    }
+    const bool success = PngToBmpConverter::pngFileToBmpStream(coverPng, coverBmp, cropped);
+    coverPng.close();
+    coverBmp.close();
+    Storage.remove(coverPngTempPath.c_str());
+
+    if (!success) {
+      LOG_ERR("EBP", "Failed to generate BMP from PNG cover image");
+      Storage.remove(getCoverBmpPath(cropped).c_str());
+    }
+    LOG_DBG("EBP", "Generated BMP from PNG cover image, success: %s", success ? "yes" : "no");
+    return success;
+  }
+
+  LOG_ERR("EBP", "Cover image is not a supported format, skipping");
+  return false;
+}
+
+std::string Epub::getThumbBmpPath() const { return cachePath + "/thumb_[HEIGHT].bmp"; }
+std::string Epub::getThumbBmpPath(int height) const { return cachePath + "/thumb_" + std::to_string(height) + ".bmp"; }
+
+bool Epub::generateThumbBmp(int height) const {
+  // Already generated, return true
+  if (Storage.exists(getThumbBmpPath(height).c_str())) {
+    return true;
+  }
+
+  if (!bookMetadataCache || !bookMetadataCache->isLoaded()) {
+    LOG_ERR("EBP", "Cannot generate thumb BMP, cache not loaded");
+    return false;
+  }
+
+  const auto coverImageHref = bookMetadataCache->coreMetadata.coverItemHref;
+  if (coverImageHref.empty()) {
+    LOG_DBG("EBP", "No known cover image for thumbnail");
+  } else if (FsHelpers::hasJpgExtension(coverImageHref)) {
+    LOG_DBG("EBP", "Generating thumb BMP from JPG cover image");
+    const auto coverJpgTempPath = getCachePath() + "/.cover.jpg";
+
+    FsFile coverJpg;
+    if (!Storage.openFileForWrite("EBP", coverJpgTempPath, coverJpg)) {
+      return false;
+    }
+    readItemContentsToStream(coverImageHref, coverJpg, 1024);
+    coverJpg.close();
+
+    if (!Storage.openFileForRead("EBP", coverJpgTempPath, coverJpg)) {
+      return false;
+    }
+
+    FsFile thumbBmp;
+    if (!Storage.openFileForWrite("EBP", getThumbBmpPath(height), thumbBmp)) {
+      coverJpg.close();
+      return false;
+    }
+    // Use smaller target size for Continue Reading card (half of screen: 240x400)
+    // Generate 1-bit BMP for fast home screen rendering (no gray passes needed)
+    int THUMB_TARGET_WIDTH = height * 0.6;
+    int THUMB_TARGET_HEIGHT = height;
+    const bool success = JpegToBmpConverter::jpegFileTo1BitBmpStreamWithSize(coverJpg, thumbBmp, THUMB_TARGET_WIDTH,
+                                                                             THUMB_TARGET_HEIGHT);
+    coverJpg.close();
+    thumbBmp.close();
+    Storage.remove(coverJpgTempPath.c_str());
+
+    if (!success) {
+      LOG_ERR("EBP", "Failed to generate thumb BMP from JPG cover image");
+      Storage.remove(getThumbBmpPath(height).c_str());
+    }
+    LOG_DBG("EBP", "Generated thumb BMP from JPG cover image, success: %s", success ? "yes" : "no");
+    return success;
+  } else if (FsHelpers::hasPngExtension(coverImageHref)) {
+    LOG_DBG("EBP", "Generating thumb BMP from PNG cover image");
+    const auto coverPngTempPath = getCachePath() + "/.cover.png";
+
+    FsFile coverPng;
+    if (!Storage.openFileForWrite("EBP", coverPngTempPath, coverPng)) {
+      return false;
+    }
+    readItemContentsToStream(coverImageHref, coverPng, 1024);
+    coverPng.close();
+
+    if (!Storage.openFileForRead("EBP", coverPngTempPath, coverPng)) {
+      return false;
+    }
+
+    FsFile thumbBmp;
+    if (!Storage.openFileForWrite("EBP", getThumbBmpPath(height), thumbBmp)) {
+      coverPng.close();
+      return false;
+    }
+    int THUMB_TARGET_WIDTH = height * 0.6;
+    int THUMB_TARGET_HEIGHT = height;
+    const bool success =
+        PngToBmpConverter::pngFileTo1BitBmpStreamWithSize(coverPng, thumbBmp, THUMB_TARGET_WIDTH, THUMB_TARGET_HEIGHT);
+    coverPng.close();
+    thumbBmp.close();
+    Storage.remove(coverPngTempPath.c_str());
+
+    if (!success) {
+      LOG_ERR("EBP", "Failed to generate thumb BMP from PNG cover image");
+      Storage.remove(getThumbBmpPath(height).c_str());
+    }
+    LOG_DBG("EBP", "Generated thumb BMP from PNG cover image, success: %s", success ? "yes" : "no");
+    return success;
+  } else {
+    LOG_ERR("EBP", "Cover image is not a supported format, skipping thumbnail");
+  }
+
+  // Write an empty bmp file to avoid generation attempts in the future
+  FsFile thumbBmp;
+  Storage.openFileForWrite("EBP", getThumbBmpPath(height), thumbBmp);
+  thumbBmp.close();
   return false;
 }
 
 uint8_t* Epub::readItemContentsToBytes(const std::string& itemHref, size_t* size, const bool trailingNullByte) const {
   if (itemHref.empty()) {
-    Serial.printf("[%lu] [EBP] Failed to read item, empty href\n", millis());
+    LOG_DBG("EBP", "Failed to read item, empty href");
     return nullptr;
   }
 
@@ -419,7 +716,7 @@ uint8_t* Epub::readItemContentsToBytes(const std::string& itemHref, size_t* size
 
   const auto content = ZipFile(filepath).readFileToMemory(path.c_str(), size, trailingNullByte);
   if (!content) {
-    Serial.printf("[%lu] [EBP] Failed to read item %s\n", millis(), path.c_str());
+    LOG_DBG("EBP", "Failed to read item %s", path.c_str());
     return nullptr;
   }
 
@@ -428,7 +725,7 @@ uint8_t* Epub::readItemContentsToBytes(const std::string& itemHref, size_t* size
 
 bool Epub::readItemContentsToStream(const std::string& itemHref, Print& out, const size_t chunkSize) const {
   if (itemHref.empty()) {
-    Serial.printf("[%lu] [EBP] Failed to read item, empty href\n", millis());
+    LOG_DBG("EBP", "Failed to read item, empty href");
     return false;
   }
 
@@ -452,12 +749,12 @@ size_t Epub::getCumulativeSpineItemSize(const int spineIndex) const { return get
 
 BookMetadataCache::SpineEntry Epub::getSpineItem(const int spineIndex) const {
   if (!bookMetadataCache || !bookMetadataCache->isLoaded()) {
-    Serial.printf("[%lu] [EBP] getSpineItem called but cache not loaded\n", millis());
+    LOG_ERR("EBP", "getSpineItem called but cache not loaded");
     return {};
   }
 
   if (spineIndex < 0 || spineIndex >= bookMetadataCache->getSpineCount()) {
-    Serial.printf("[%lu] [EBP] getSpineItem index:%d is out of range\n", millis(), spineIndex);
+    LOG_ERR("EBP", "getSpineItem index:%d is out of range", spineIndex);
     return bookMetadataCache->getSpineEntry(0);
   }
 
@@ -466,12 +763,12 @@ BookMetadataCache::SpineEntry Epub::getSpineItem(const int spineIndex) const {
 
 BookMetadataCache::TocEntry Epub::getTocItem(const int tocIndex) const {
   if (!bookMetadataCache || !bookMetadataCache->isLoaded()) {
-    Serial.printf("[%lu] [EBP] getTocItem called but cache not loaded\n", millis());
+    LOG_DBG("EBP", "getTocItem called but cache not loaded");
     return {};
   }
 
   if (tocIndex < 0 || tocIndex >= bookMetadataCache->getTocCount()) {
-    Serial.printf("[%lu] [EBP] getTocItem index:%d is out of range\n", millis(), tocIndex);
+    LOG_DBG("EBP", "getTocItem index:%d is out of range", tocIndex);
     return {};
   }
 
@@ -489,18 +786,18 @@ int Epub::getTocItemsCount() const {
 // work out the section index for a toc index
 int Epub::getSpineIndexForTocIndex(const int tocIndex) const {
   if (!bookMetadataCache || !bookMetadataCache->isLoaded()) {
-    Serial.printf("[%lu] [EBP] getSpineIndexForTocIndex called but cache not loaded\n", millis());
+    LOG_ERR("EBP", "getSpineIndexForTocIndex called but cache not loaded");
     return 0;
   }
 
   if (tocIndex < 0 || tocIndex >= bookMetadataCache->getTocCount()) {
-    Serial.printf("[%lu] [EBP] getSpineIndexForTocIndex: tocIndex %d out of range\n", millis(), tocIndex);
+    LOG_ERR("EBP", "getSpineIndexForTocIndex: tocIndex %d out of range", tocIndex);
     return 0;
   }
 
   const int spineIndex = bookMetadataCache->getTocEntry(tocIndex).spineIndex;
   if (spineIndex < 0) {
-    Serial.printf("[%lu] [EBP] Section not found for TOC index %d\n", millis(), tocIndex);
+    LOG_DBG("EBP", "Section not found for TOC index %d", tocIndex);
     return 0;
   }
 
@@ -518,14 +815,13 @@ size_t Epub::getBookSize() const {
 
 int Epub::getSpineIndexForTextReference() const {
   if (!bookMetadataCache || !bookMetadataCache->isLoaded()) {
-    Serial.printf("[%lu] [EBP] getSpineIndexForTextReference called but cache not loaded\n", millis());
+    LOG_ERR("EBP", "getSpineIndexForTextReference called but cache not loaded");
     return 0;
   }
-  Serial.printf("[%lu] [ERS] Core Metadata: cover(%d)=%s, textReference(%d)=%s\n", millis(),
-                bookMetadataCache->coreMetadata.coverItemHref.size(),
-                bookMetadataCache->coreMetadata.coverItemHref.c_str(),
-                bookMetadataCache->coreMetadata.textReferenceHref.size(),
-                bookMetadataCache->coreMetadata.textReferenceHref.c_str());
+  LOG_DBG("EBP", "Core Metadata: cover(%d)=%s, textReference(%d)=%s",
+          bookMetadataCache->coreMetadata.coverItemHref.size(), bookMetadataCache->coreMetadata.coverItemHref.c_str(),
+          bookMetadataCache->coreMetadata.textReferenceHref.size(),
+          bookMetadataCache->coreMetadata.textReferenceHref.c_str());
 
   if (bookMetadataCache->coreMetadata.textReferenceHref.empty()) {
     // there was no textReference in epub, so we return 0 (the first chapter)
@@ -535,24 +831,52 @@ int Epub::getSpineIndexForTextReference() const {
   // loop through spine items to get the correct index matching the text href
   for (size_t i = 0; i < getSpineItemsCount(); i++) {
     if (getSpineItem(i).href == bookMetadataCache->coreMetadata.textReferenceHref) {
-      Serial.printf("[%lu] [ERS] Text reference %s found at index %d\n", millis(),
-                    bookMetadataCache->coreMetadata.textReferenceHref.c_str(), i);
+      LOG_DBG("EBP", "Text reference %s found at index %d", bookMetadataCache->coreMetadata.textReferenceHref.c_str(),
+              i);
       return i;
     }
   }
   // This should not happen, as we checked for empty textReferenceHref earlier
-  Serial.printf("[%lu] [EBP] Section not found for text reference\n", millis());
+  LOG_DBG("EBP", "Section not found for text reference");
   return 0;
 }
 
-// Calculate progress in book
-uint8_t Epub::calculateProgress(const int currentSpineIndex, const float currentSpineRead) const {
+// Calculate progress in book (returns 0.0-1.0)
+float Epub::calculateProgress(const int currentSpineIndex, const float currentSpineRead) const {
   const size_t bookSize = getBookSize();
   if (bookSize == 0) {
-    return 0;
+    return 0.0f;
   }
   const size_t prevChapterSize = (currentSpineIndex >= 1) ? getCumulativeSpineItemSize(currentSpineIndex - 1) : 0;
   const size_t curChapterSize = getCumulativeSpineItemSize(currentSpineIndex) - prevChapterSize;
-  const size_t sectionProgSize = currentSpineRead * curChapterSize;
-  return round(static_cast<float>(prevChapterSize + sectionProgSize) / bookSize * 100.0);
+  const float sectionProgSize = currentSpineRead * static_cast<float>(curChapterSize);
+  const float totalProgress = static_cast<float>(prevChapterSize) + sectionProgSize;
+  return totalProgress / static_cast<float>(bookSize);
+}
+
+int Epub::resolveHrefToSpineIndex(const std::string& href) const {
+  if (!bookMetadataCache || !bookMetadataCache->isLoaded()) return -1;
+
+  // Extract filename (remove #anchor)
+  std::string target = href;
+  size_t hashPos = target.find('#');
+  if (hashPos != std::string::npos) target = target.substr(0, hashPos);
+
+  // Same-file reference (anchor-only)
+  if (target.empty()) return -1;
+
+  // Extract just the filename for comparison
+  size_t targetSlash = target.find_last_of('/');
+  std::string targetFilename = (targetSlash != std::string::npos) ? target.substr(targetSlash + 1) : target;
+
+  for (int i = 0; i < getSpineItemsCount(); i++) {
+    const auto& spineHref = getSpineItem(i).href;
+    // Try exact match first
+    if (spineHref == target) return i;
+    // Then filename-only match
+    size_t spineSlash = spineHref.find_last_of('/');
+    std::string spineFilename = (spineSlash != std::string::npos) ? spineHref.substr(spineSlash + 1) : spineHref;
+    if (spineFilename == targetFilename) return i;
+  }
+  return -1;
 }

lib/Epub/Epub.h

@@ -8,6 +8,7 @@
 #include <vector>
 
 #include "Epub/BookMetadataCache.h"
+#include "Epub/css/CssParser.h"
 
 class ZipFile;
 
@@ -24,11 +25,16 @@ class Epub {
   std::string cachePath;
   // Spine and TOC cache
   std::unique_ptr<BookMetadataCache> bookMetadataCache;
+  // CSS parser for styling
+  std::unique_ptr<CssParser> cssParser;
+  // CSS files
+  std::vector<std::string> cssFiles;
 
   bool findContentOpfFile(std::string* contentOpfFile) const;
   bool parseContentOpf(BookMetadataCache::BookMetadata& bookMetadata);
   bool parseTocNcxFile() const;
   bool parseTocNavFile() const;
+  void parseCssFiles() const;
 
  public:
   explicit Epub(std::string filepath, const std::string& cacheDir) : filepath(std::move(filepath)) {
@@ -37,15 +43,19 @@ class Epub {
   }
   ~Epub() = default;
   std::string& getBasePath() { return contentBasePath; }
-  bool load(bool buildIfMissing = true);
+  bool load(bool buildIfMissing = true, bool skipLoadingCss = false);
   bool clearCache() const;
   void setupCacheDir() const;
   const std::string& getCachePath() const;
   const std::string& getPath() const;
   const std::string& getTitle() const;
   const std::string& getAuthor() const;
+  const std::string& getLanguage() const;
   std::string getCoverBmpPath(bool cropped = false) const;
   bool generateCoverBmp(bool cropped = false) const;
+  std::string getThumbBmpPath() const;
+  std::string getThumbBmpPath(int height) const;
+  bool generateThumbBmp(int height) const;
   uint8_t* readItemContentsToBytes(const std::string& itemHref, size_t* size = nullptr,
                                    bool trailingNullByte = false) const;
   bool readItemContentsToStream(const std::string& itemHref, Print& out, size_t chunkSize) const;
@@ -60,5 +70,7 @@ class Epub {
   int getSpineIndexForTextReference() const;
 
   size_t getBookSize() const;
-  uint8_t calculateProgress(int currentSpineIndex, float currentSpineRead) const;
+  float calculateProgress(int currentSpineIndex, float currentSpineRead) const;
+  CssParser* getCssParser() const { return cssParser.get(); }
+  int resolveHrefToSpineIndex(const std::string& href) const;
 };

lib/Epub/Epub/BookMetadataCache.cpp

@@ -1,6 +1,6 @@
 #include "BookMetadataCache.h"
 
-#include <HardwareSerial.h>
+#include <Logging.h>
 #include <Serialization.h>
 #include <ZipFile.h>
 
@@ -9,7 +9,7 @@
 #include "FsHelpers.h"
 
 namespace {
-constexpr uint8_t BOOK_CACHE_VERSION = 4;
+constexpr uint8_t BOOK_CACHE_VERSION = 5;
 constexpr char bookBinFile[] = "/book.bin";
 constexpr char tmpSpineBinFile[] = "/spine.bin.tmp";
 constexpr char tmpTocBinFile[] = "/toc.bin.tmp";
@@ -21,15 +21,15 @@ bool BookMetadataCache::beginWrite() {
   buildMode = true;
   spineCount = 0;
   tocCount = 0;
-  Serial.printf("[%lu] [BMC] Entering write mode\n", millis());
+  LOG_DBG("BMC", "Entering write mode");
   return true;
 }
 
 bool BookMetadataCache::beginContentOpfPass() {
-  Serial.printf("[%lu] [BMC] Beginning content opf pass\n", millis());
+  LOG_DBG("BMC", "Beginning content opf pass");
 
   // Open spine file for writing
-  return SdMan.openFileForWrite("BMC", cachePath + tmpSpineBinFile, spineFile);
+  return Storage.openFileForWrite("BMC", cachePath + tmpSpineBinFile, spineFile);
 }
 
 bool BookMetadataCache::endContentOpfPass() {
@@ -38,48 +38,76 @@ bool BookMetadataCache::endContentOpfPass() {
 }
 
 bool BookMetadataCache::beginTocPass() {
-  Serial.printf("[%lu] [BMC] Beginning toc pass\n", millis());
+  LOG_DBG("BMC", "Beginning toc pass");
 
-  // Open spine file for reading
-  if (!SdMan.openFileForRead("BMC", cachePath + tmpSpineBinFile, spineFile)) {
+  if (!Storage.openFileForRead("BMC", cachePath + tmpSpineBinFile, spineFile)) {
     return false;
   }
-  if (!SdMan.openFileForWrite("BMC", cachePath + tmpTocBinFile, tocFile)) {
+  if (!Storage.openFileForWrite("BMC", cachePath + tmpTocBinFile, tocFile)) {
     spineFile.close();
     return false;
   }
+
+  if (spineCount >= LARGE_SPINE_THRESHOLD) {
+    spineHrefIndex.clear();
+    spineHrefIndex.reserve(spineCount);
+    spineFile.seek(0);
+    for (int i = 0; i < spineCount; i++) {
+      auto entry = readSpineEntry(spineFile);
+      SpineHrefIndexEntry idx;
+      idx.hrefHash = fnvHash64(entry.href);
+      idx.hrefLen = static_cast<uint16_t>(entry.href.size());
+      idx.spineIndex = static_cast<int16_t>(i);
+      spineHrefIndex.push_back(idx);
+    }
+    std::sort(spineHrefIndex.begin(), spineHrefIndex.end(),
+              [](const SpineHrefIndexEntry& a, const SpineHrefIndexEntry& b) {
+                return a.hrefHash < b.hrefHash || (a.hrefHash == b.hrefHash && a.hrefLen < b.hrefLen);
+              });
+    spineFile.seek(0);
+    useSpineHrefIndex = true;
+    LOG_DBG("BMC", "Using fast index for %d spine items", spineCount);
+  } else {
+    useSpineHrefIndex = false;
+  }
+
   return true;
 }
 
 bool BookMetadataCache::endTocPass() {
   tocFile.close();
   spineFile.close();
+
+  spineHrefIndex.clear();
+  spineHrefIndex.shrink_to_fit();
+  useSpineHrefIndex = false;
+
   return true;
 }
 
 bool BookMetadataCache::endWrite() {
   if (!buildMode) {
-    Serial.printf("[%lu] [BMC] endWrite called but not in build mode\n", millis());
+    LOG_DBG("BMC", "endWrite called but not in build mode");
     return false;
   }
 
   buildMode = false;
-  Serial.printf("[%lu] [BMC] Wrote %d spine, %d TOC entries\n", millis(), spineCount, tocCount);
+  LOG_DBG("BMC", "Wrote %d spine, %d TOC entries", spineCount, tocCount);
   return true;
 }
 
 bool BookMetadataCache::buildBookBin(const std::string& epubPath, const BookMetadata& metadata) {
   // Open all three files, writing to meta, reading from spine and toc
-  if (!SdMan.openFileForWrite("BMC", cachePath + bookBinFile, bookFile)) {
+  if (!Storage.openFileForWrite("BMC", cachePath + bookBinFile, bookFile)) {
     return false;
   }
 
-  if (!SdMan.openFileForRead("BMC", cachePath + tmpSpineBinFile, spineFile)) {
+  if (!Storage.openFileForRead("BMC", cachePath + tmpSpineBinFile, spineFile)) {
     bookFile.close();
     return false;
   }
 
-  if (!SdMan.openFileForRead("BMC", cachePath + tmpTocBinFile, tocFile)) {
+  if (!Storage.openFileForRead("BMC", cachePath + tmpTocBinFile, tocFile)) {
     bookFile.close();
     spineFile.close();
     return false;
@@ -87,8 +115,9 @@ bool BookMetadataCache::buildBookBin(const std::string& epubPath, const BookMeta
 
   constexpr uint32_t headerASize =
       sizeof(BOOK_CACHE_VERSION) + /* LUT Offset */ sizeof(uint32_t) + sizeof(spineCount) + sizeof(tocCount);
-  const uint32_t metadataSize = metadata.title.size() + metadata.author.size() + metadata.coverItemHref.size() +
-                                metadata.textReferenceHref.size() + sizeof(uint32_t) * 4;
+  const uint32_t metadataSize = metadata.title.size() + metadata.author.size() + metadata.language.size() +
+                                metadata.coverItemHref.size() + metadata.textReferenceHref.size() +
+                                sizeof(uint32_t) * 5;
   const uint32_t lutSize = sizeof(uint32_t) * spineCount + sizeof(uint32_t) * tocCount;
   const uint32_t lutOffset = headerASize + metadataSize;
 
@@ -100,6 +129,7 @@ bool BookMetadataCache::buildBookBin(const std::string& epubPath, const BookMeta
   // Metadata
   serialization::writeString(bookFile, metadata.title);
   serialization::writeString(bookFile, metadata.author);
+  serialization::writeString(bookFile, metadata.language);
   serialization::writeString(bookFile, metadata.coverItemHref);
   serialization::writeString(bookFile, metadata.textReferenceHref);
 
@@ -122,61 +152,106 @@ bool BookMetadataCache::buildBookBin(const std::string& epubPath, const BookMeta
   // LUTs complete
   // Loop through spines from spine file matching up TOC indexes, calculating cumulative size and writing to book.bin
 
+  // Build spineIndex->tocIndex mapping in one pass (O(n) instead of O(n*m))
+  std::vector<int16_t> spineToTocIndex(spineCount, -1);
+  tocFile.seek(0);
+  for (int j = 0; j < tocCount; j++) {
+    auto tocEntry = readTocEntry(tocFile);
+    if (tocEntry.spineIndex >= 0 && tocEntry.spineIndex < spineCount) {
+      if (spineToTocIndex[tocEntry.spineIndex] == -1) {
+        spineToTocIndex[tocEntry.spineIndex] = static_cast<int16_t>(j);
+      }
+    }
+  }
+
   ZipFile zip(epubPath);
   // Pre-open zip file to speed up size calculations
   if (!zip.open()) {
-    Serial.printf("[%lu] [BMC] Could not open EPUB zip for size calculations\n", millis());
+    LOG_ERR("BMC", "Could not open EPUB zip for size calculations");
     bookFile.close();
     spineFile.close();
     tocFile.close();
     return false;
   }
-  // TODO: For large ZIPs loading the all localHeaderOffsets will crash.
-  //       However not having them loaded is extremely slow. Need a better solution here.
-  //       Perhaps only a cache of spine items or a better way to speedup lookups?
-  if (!zip.loadAllFileStatSlims()) {
-    Serial.printf("[%lu] [BMC] Could not load zip local header offsets for size calculations\n", millis());
-    bookFile.close();
-    spineFile.close();
-    tocFile.close();
-    zip.close();
-    return false;
+  // NOTE: We intentionally skip calling loadAllFileStatSlims() here.
+  // For large EPUBs (2000+ chapters), pre-loading all ZIP central directory entries
+  // into memory causes OOM crashes on ESP32-C3's limited ~380KB RAM.
+  // Instead, for large books we use a one-pass batch lookup that scans the ZIP
+  // central directory once and matches against spine targets using hash comparison.
+  // This is O(n*log(m)) instead of O(n*m) while avoiding memory exhaustion.
+  // See: https://github.com/crosspoint-reader/crosspoint-reader/issues/134
+
+  std::vector<uint32_t> spineSizes;
+  bool useBatchSizes = false;
+
+  if (spineCount >= LARGE_SPINE_THRESHOLD) {
+    LOG_DBG("BMC", "Using batch size lookup for %d spine items", spineCount);
+
+    std::vector<ZipFile::SizeTarget> targets;
+    targets.reserve(spineCount);
+
+    spineFile.seek(0);
+    for (int i = 0; i < spineCount; i++) {
+      auto entry = readSpineEntry(spineFile);
+      std::string path = FsHelpers::normalisePath(entry.href);
+
+      ZipFile::SizeTarget t;
+      t.hash = ZipFile::fnvHash64(path.c_str(), path.size());
+      t.len = static_cast<uint16_t>(path.size());
+      t.index = static_cast<uint16_t>(i);
+      targets.push_back(t);
+    }
+
+    std::sort(targets.begin(), targets.end(), [](const ZipFile::SizeTarget& a, const ZipFile::SizeTarget& b) {
+      return a.hash < b.hash || (a.hash == b.hash && a.len < b.len);
+    });
+
+    spineSizes.resize(spineCount, 0);
+    int matched = zip.fillUncompressedSizes(targets, spineSizes);
+    LOG_DBG("BMC", "Batch lookup matched %d/%d spine items", matched, spineCount);
+
+    targets.clear();
+    targets.shrink_to_fit();
+
+    useBatchSizes = true;
   }
+
   uint32_t cumSize = 0;
   spineFile.seek(0);
   int lastSpineTocIndex = -1;
   for (int i = 0; i < spineCount; i++) {
     auto spineEntry = readSpineEntry(spineFile);
 
-    tocFile.seek(0);
-    for (int j = 0; j < tocCount; j++) {
-      auto tocEntry = readTocEntry(tocFile);
-      if (tocEntry.spineIndex == i) {
-        spineEntry.tocIndex = j;
-        break;
-      }
-    }
+    spineEntry.tocIndex = spineToTocIndex[i];
 
     // Not a huge deal if we don't fine a TOC entry for the spine entry, this is expected behaviour for EPUBs
     // Logging here is for debugging
     if (spineEntry.tocIndex == -1) {
-      Serial.printf(
-          "[%lu] [BMC] Warning: Could not find TOC entry for spine item %d: %s, using title from last section\n",
-          millis(), i, spineEntry.href.c_str());
+      LOG_DBG("BMC", "Warning: Could not find TOC entry for spine item %d: %s, using title from last section", i,
+              spineEntry.href.c_str());
       spineEntry.tocIndex = lastSpineTocIndex;
     }
     lastSpineTocIndex = spineEntry.tocIndex;
 
-    // Calculate size for cumulative size
     size_t itemSize = 0;
-    const std::string path = FsHelpers::normalisePath(spineEntry.href);
-    if (zip.getInflatedFileSize(path.c_str(), &itemSize)) {
-      cumSize += itemSize;
-      spineEntry.cumulativeSize = cumSize;
+    if (useBatchSizes) {
+      itemSize = spineSizes[i];
+      if (itemSize == 0) {
+        const std::string path = FsHelpers::normalisePath(spineEntry.href);
+        if (!zip.getInflatedFileSize(path.c_str(), &itemSize)) {
+          LOG_ERR("BMC", "Warning: Could not get size for spine item: %s", path.c_str());
+        }
+      }
     } else {
-      Serial.printf("[%lu] [BMC] Warning: Could not get size for spine item: %s\n", millis(), path.c_str());
+      const std::string path = FsHelpers::normalisePath(spineEntry.href);
+      if (!zip.getInflatedFileSize(path.c_str(), &itemSize)) {
+        LOG_ERR("BMC", "Warning: Could not get size for spine item: %s", path.c_str());
+      }
     }
 
+    cumSize += itemSize;
+    spineEntry.cumulativeSize = cumSize;
+
     // Write out spine data to book.bin
     writeSpineEntry(bookFile, spineEntry);
   }
@@ -194,16 +269,18 @@ bool BookMetadataCache::buildBookBin(const std::string& epubPath, const BookMeta
   spineFile.close();
   tocFile.close();
 
-  Serial.printf("[%lu] [BMC] Successfully built book.bin\n", millis());
+  LOG_DBG("BMC", "Successfully built book.bin");
   return true;
 }
 
 bool BookMetadataCache::cleanupTmpFiles() const {
-  if (SdMan.exists((cachePath + tmpSpineBinFile).c_str())) {
-    SdMan.remove((cachePath + tmpSpineBinFile).c_str());
+  const auto spineBinFile = cachePath + tmpSpineBinFile;
+  if (Storage.exists(spineBinFile.c_str())) {
+    Storage.remove(spineBinFile.c_str());
   }
-  if (SdMan.exists((cachePath + tmpTocBinFile).c_str())) {
-    SdMan.remove((cachePath + tmpTocBinFile).c_str());
+  const auto tocBinFile = cachePath + tmpTocBinFile;
+  if (Storage.exists(tocBinFile.c_str())) {
+    Storage.remove(tocBinFile.c_str());
   }
   return true;
 }
@@ -230,7 +307,7 @@ uint32_t BookMetadataCache::writeTocEntry(FsFile& file, const TocEntry& entry) c
 // this is because in this function we're marking positions of the items
 void BookMetadataCache::createSpineEntry(const std::string& href) {
   if (!buildMode || !spineFile) {
-    Serial.printf("[%lu] [BMC] createSpineEntry called but not in build mode\n", millis());
+    LOG_DBG("BMC", "createSpineEntry called but not in build mode");
     return;
   }
 
@@ -242,25 +319,42 @@ void BookMetadataCache::createSpineEntry(const std::string& href) {
 void BookMetadataCache::createTocEntry(const std::string& title, const std::string& href, const std::string& anchor,
                                        const uint8_t level) {
   if (!buildMode || !tocFile || !spineFile) {
-    Serial.printf("[%lu] [BMC] createTocEntry called but not in build mode\n", millis());
+    LOG_DBG("BMC", "createTocEntry called but not in build mode");
     return;
   }
 
-  int spineIndex = -1;
-  // find spine index
-  // TODO: This lookup is slow as need to scan through all items each time. We can't hold it all in memory due to size.
-  //       But perhaps we can load just the hrefs in a vector/list to do an index lookup?
-  spineFile.seek(0);
-  for (int i = 0; i < spineCount; i++) {
-    auto spineEntry = readSpineEntry(spineFile);
-    if (spineEntry.href == href) {
-      spineIndex = i;
+  int16_t spineIndex = -1;
+
+  if (useSpineHrefIndex) {
+    uint64_t targetHash = fnvHash64(href);
+    uint16_t targetLen = static_cast<uint16_t>(href.size());
+
+    auto it =
+        std::lower_bound(spineHrefIndex.begin(), spineHrefIndex.end(), SpineHrefIndexEntry{targetHash, targetLen, 0},
+                         [](const SpineHrefIndexEntry& a, const SpineHrefIndexEntry& b) {
+                           return a.hrefHash < b.hrefHash || (a.hrefHash == b.hrefHash && a.hrefLen < b.hrefLen);
+                         });
+
+    while (it != spineHrefIndex.end() && it->hrefHash == targetHash && it->hrefLen == targetLen) {
+      spineIndex = it->spineIndex;
       break;
     }
-  }
 
-  if (spineIndex == -1) {
-    Serial.printf("[%lu] [BMC] addTocEntry: Could not find spine item for TOC href %s\n", millis(), href.c_str());
+    if (spineIndex == -1) {
+      LOG_DBG("BMC", "createTocEntry: Could not find spine item for TOC href %s", href.c_str());
+    }
+  } else {
+    spineFile.seek(0);
+    for (int i = 0; i < spineCount; i++) {
+      auto spineEntry = readSpineEntry(spineFile);
+      if (spineEntry.href == href) {
+        spineIndex = static_cast<int16_t>(i);
+        break;
+      }
+    }
+    if (spineIndex == -1) {
+      LOG_DBG("BMC", "createTocEntry: Could not find spine item for TOC href %s", href.c_str());
+    }
   }
 
   const TocEntry entry(title, href, anchor, level, spineIndex);
@@ -271,14 +365,14 @@ void BookMetadataCache::createTocEntry(const std::string& title, const std::stri
 /* ============= READING / LOADING FUNCTIONS ================ */
 
 bool BookMetadataCache::load() {
-  if (!SdMan.openFileForRead("BMC", cachePath + bookBinFile, bookFile)) {
+  if (!Storage.openFileForRead("BMC", cachePath + bookBinFile, bookFile)) {
     return false;
   }
 
   uint8_t version;
   serialization::readPod(bookFile, version);
   if (version != BOOK_CACHE_VERSION) {
-    Serial.printf("[%lu] [BMC] Cache version mismatch: expected %d, got %d\n", millis(), BOOK_CACHE_VERSION, version);
+    LOG_DBG("BMC", "Cache version mismatch: expected %d, got %d", BOOK_CACHE_VERSION, version);
     bookFile.close();
     return false;
   }
@@ -289,22 +383,23 @@ bool BookMetadataCache::load() {
 
   serialization::readString(bookFile, coreMetadata.title);
   serialization::readString(bookFile, coreMetadata.author);
+  serialization::readString(bookFile, coreMetadata.language);
   serialization::readString(bookFile, coreMetadata.coverItemHref);
   serialization::readString(bookFile, coreMetadata.textReferenceHref);
 
   loaded = true;
-  Serial.printf("[%lu] [BMC] Loaded cache data: %d spine, %d TOC entries\n", millis(), spineCount, tocCount);
+  LOG_DBG("BMC", "Loaded cache data: %d spine, %d TOC entries", spineCount, tocCount);
   return true;
 }
 
 BookMetadataCache::SpineEntry BookMetadataCache::getSpineEntry(const int index) {
   if (!loaded) {
-    Serial.printf("[%lu] [BMC] getSpineEntry called but cache not loaded\n", millis());
+    LOG_ERR("BMC", "getSpineEntry called but cache not loaded");
     return {};
   }
 
   if (index < 0 || index >= static_cast<int>(spineCount)) {
-    Serial.printf("[%lu] [BMC] getSpineEntry index %d out of range\n", millis(), index);
+    LOG_ERR("BMC", "getSpineEntry index %d out of range", index);
     return {};
   }
 
@@ -318,12 +413,12 @@ BookMetadataCache::SpineEntry BookMetadataCache::getSpineEntry(const int index)
 
 BookMetadataCache::TocEntry BookMetadataCache::getTocEntry(const int index) {
   if (!loaded) {
-    Serial.printf("[%lu] [BMC] getTocEntry called but cache not loaded\n", millis());
+    LOG_ERR("BMC", "getTocEntry called but cache not loaded");
     return {};
   }
 
   if (index < 0 || index >= static_cast<int>(tocCount)) {
-    Serial.printf("[%lu] [BMC] getTocEntry index %d out of range\n", millis(), index);
+    LOG_ERR("BMC", "getTocEntry index %d out of range", index);
     return {};
   }
 

lib/Epub/Epub/BookMetadataCache.h

@@ -1,14 +1,17 @@
 #pragma once
 
-#include <SDCardManager.h>
+#include <HalStorage.h>
 
+#include <algorithm>
 #include <string>
+#include <vector>
 
 class BookMetadataCache {
  public:
   struct BookMetadata {
     std::string title;
     std::string author;
+    std::string language;
     std::string coverItemHref;
     std::string textReferenceHref;
   };
@@ -52,6 +55,27 @@ class BookMetadataCache {
   FsFile spineFile;
   FsFile tocFile;
 
+  // Index for fast href→spineIndex lookup (used only for large EPUBs)
+  struct SpineHrefIndexEntry {
+    uint64_t hrefHash;  // FNV-1a 64-bit hash
+    uint16_t hrefLen;   // length for collision reduction
+    int16_t spineIndex;
+  };
+  std::vector<SpineHrefIndexEntry> spineHrefIndex;
+  bool useSpineHrefIndex = false;
+
+  static constexpr uint16_t LARGE_SPINE_THRESHOLD = 400;
+
+  // FNV-1a 64-bit hash function
+  static uint64_t fnvHash64(const std::string& s) {
+    uint64_t hash = 14695981039346656037ull;
+    for (char c : s) {
+      hash ^= static_cast<uint8_t>(c);
+      hash *= 1099511628211ull;
+    }
+    return hash;
+  }
+
   uint32_t writeSpineEntry(FsFile& file, const SpineEntry& entry) const;
   uint32_t writeTocEntry(FsFile& file, const TocEntry& entry) const;
   SpineEntry readSpineEntry(FsFile& file) const;

lib/Epub/Epub/FootnoteEntry.h

@@ -0,0 +1,13 @@
+#pragma once
+
+#include <cstring>
+
+struct FootnoteEntry {
+  char number[24];
+  char href[64];
+
+  FootnoteEntry() {
+    number[0] = '\0';
+    href[0] = '\0';
+  }
+};

lib/Epub/Epub/Page.cpp

@@ -1,6 +1,6 @@
 #include "Page.h"
 
-#include <HardwareSerial.h>
+#include <Logging.h>
 #include <Serialization.h>
 
 void PageLine::render(GfxRenderer& renderer, const int fontId, const int xOffset, const int yOffset) {
@@ -25,6 +25,29 @@ std::unique_ptr<PageLine> PageLine::deserialize(FsFile& file) {
   return std::unique_ptr<PageLine>(new PageLine(std::move(tb), xPos, yPos));
 }
 
+void PageImage::render(GfxRenderer& renderer, const int fontId, const int xOffset, const int yOffset) {
+  // Images don't use fontId or text rendering
+  imageBlock->render(renderer, xPos + xOffset, yPos + yOffset);
+}
+
+bool PageImage::serialize(FsFile& file) {
+  serialization::writePod(file, xPos);
+  serialization::writePod(file, yPos);
+
+  // serialize ImageBlock
+  return imageBlock->serialize(file);
+}
+
+std::unique_ptr<PageImage> PageImage::deserialize(FsFile& file) {
+  int16_t xPos;
+  int16_t yPos;
+  serialization::readPod(file, xPos);
+  serialization::readPod(file, yPos);
+
+  auto ib = ImageBlock::deserialize(file);
+  return std::unique_ptr<PageImage>(new PageImage(std::move(ib), xPos, yPos));
+}
+
 void Page::render(GfxRenderer& renderer, const int fontId, const int xOffset, const int yOffset) const {
   for (auto& element : elements) {
     element->render(renderer, fontId, xOffset, yOffset);
@@ -36,13 +59,26 @@ bool Page::serialize(FsFile& file) const {
   serialization::writePod(file, count);
 
   for (const auto& el : elements) {
-    // Only PageLine exists currently
-    serialization::writePod(file, static_cast<uint8_t>(TAG_PageLine));
+    // Use getTag() method to determine type
+    serialization::writePod(file, static_cast<uint8_t>(el->getTag()));
+
     if (!el->serialize(file)) {
       return false;
     }
   }
 
+  // Serialize footnotes (clamp to MAX_FOOTNOTES_PER_PAGE to match addFootnote/deserialize limits)
+  const uint16_t fnCount = std::min<uint16_t>(footnotes.size(), MAX_FOOTNOTES_PER_PAGE);
+  serialization::writePod(file, fnCount);
+  for (uint16_t i = 0; i < fnCount; i++) {
+    const auto& fn = footnotes[i];
+    if (file.write(fn.number, sizeof(fn.number)) != sizeof(fn.number) ||
+        file.write(fn.href, sizeof(fn.href)) != sizeof(fn.href)) {
+      LOG_ERR("PGE", "Failed to write footnote");
+      return false;
+    }
+  }
+
   return true;
 }
 
@@ -59,11 +95,33 @@ std::unique_ptr<Page> Page::deserialize(FsFile& file) {
     if (tag == TAG_PageLine) {
       auto pl = PageLine::deserialize(file);
       page->elements.push_back(std::move(pl));
+    } else if (tag == TAG_PageImage) {
+      auto pi = PageImage::deserialize(file);
+      page->elements.push_back(std::move(pi));
     } else {
-      Serial.printf("[%lu] [PGE] Deserialization failed: Unknown tag %u\n", millis(), tag);
+      LOG_ERR("PGE", "Deserialization failed: Unknown tag %u", tag);
       return nullptr;
     }
   }
 
+  // Deserialize footnotes
+  uint16_t fnCount;
+  serialization::readPod(file, fnCount);
+  if (fnCount > MAX_FOOTNOTES_PER_PAGE) {
+    LOG_ERR("PGE", "Invalid footnote count %u", fnCount);
+    return nullptr;
+  }
+  page->footnotes.resize(fnCount);
+  for (uint16_t i = 0; i < fnCount; i++) {
+    auto& entry = page->footnotes[i];
+    if (file.read(entry.number, sizeof(entry.number)) != sizeof(entry.number) ||
+        file.read(entry.href, sizeof(entry.href)) != sizeof(entry.href)) {
+      LOG_ERR("PGE", "Failed to read footnote %u", i);
+      return nullptr;
+    }
+    entry.number[sizeof(entry.number) - 1] = '\0';
+    entry.href[sizeof(entry.href) - 1] = '\0';
+  }
+
   return page;
 }

lib/Epub/Epub/Page.h

@@ -1,13 +1,18 @@
 #pragma once
-#include <SdFat.h>
+#include <HalStorage.h>
 
+#include <algorithm>
+#include <string>
 #include <utility>
 #include <vector>
 
+#include "FootnoteEntry.h"
+#include "blocks/ImageBlock.h"
 #include "blocks/TextBlock.h"
 
 enum PageElementTag : uint8_t {
   TAG_PageLine = 1,
+  TAG_PageImage = 2,  // New tag
 };
 
 // represents something that has been added to a page
@@ -19,6 +24,7 @@ class PageElement {
   virtual ~PageElement() = default;
   virtual void render(GfxRenderer& renderer, int fontId, int xOffset, int yOffset) = 0;
   virtual bool serialize(FsFile& file) = 0;
+  virtual PageElementTag getTag() const = 0;  // Add type identification
 };
 
 // a line from a block element
@@ -28,16 +34,79 @@ class PageLine final : public PageElement {
  public:
   PageLine(std::shared_ptr<TextBlock> block, const int16_t xPos, const int16_t yPos)
       : PageElement(xPos, yPos), block(std::move(block)) {}
+  const std::shared_ptr<TextBlock>& getBlock() const { return block; }
   void render(GfxRenderer& renderer, int fontId, int xOffset, int yOffset) override;
   bool serialize(FsFile& file) override;
+  PageElementTag getTag() const override { return TAG_PageLine; }
   static std::unique_ptr<PageLine> deserialize(FsFile& file);
 };
 
+// New PageImage class
+class PageImage final : public PageElement {
+  std::shared_ptr<ImageBlock> imageBlock;
+
+ public:
+  PageImage(std::shared_ptr<ImageBlock> block, const int16_t xPos, const int16_t yPos)
+      : PageElement(xPos, yPos), imageBlock(std::move(block)) {}
+  void render(GfxRenderer& renderer, int fontId, int xOffset, int yOffset) override;
+  bool serialize(FsFile& file) override;
+  PageElementTag getTag() const override { return TAG_PageImage; }
+  static std::unique_ptr<PageImage> deserialize(FsFile& file);
+  const ImageBlock& getImageBlock() const { return *imageBlock; }
+};
+
 class Page {
  public:
   // the list of block index and line numbers on this page
   std::vector<std::shared_ptr<PageElement>> elements;
+  std::vector<FootnoteEntry> footnotes;
+  static constexpr uint16_t MAX_FOOTNOTES_PER_PAGE = 16;
+
+  void addFootnote(const char* number, const char* href) {
+    if (footnotes.size() >= MAX_FOOTNOTES_PER_PAGE) return;  // Cap per-page footnotes
+    FootnoteEntry entry;
+    strncpy(entry.number, number, sizeof(entry.number) - 1);
+    entry.number[sizeof(entry.number) - 1] = '\0';
+    strncpy(entry.href, href, sizeof(entry.href) - 1);
+    entry.href[sizeof(entry.href) - 1] = '\0';
+    footnotes.push_back(entry);
+  }
+
   void render(GfxRenderer& renderer, int fontId, int xOffset, int yOffset) const;
   bool serialize(FsFile& file) const;
   static std::unique_ptr<Page> deserialize(FsFile& file);
+
+  // Check if page contains any images (used to force full refresh)
+  bool hasImages() const {
+    return std::any_of(elements.begin(), elements.end(),
+                       [](const std::shared_ptr<PageElement>& el) { return el->getTag() == TAG_PageImage; });
+  }
+
+  // Get bounding box of all images on the page (union of image rects)
+  // Returns false if no images. Coordinates are relative to page origin.
+  bool getImageBoundingBox(int16_t& outX, int16_t& outY, int16_t& outW, int16_t& outH) const {
+    bool found = false;
+    int16_t minX = INT16_MAX, minY = INT16_MAX, maxX = INT16_MIN, maxY = INT16_MIN;
+    for (const auto& el : elements) {
+      if (el->getTag() == TAG_PageImage) {
+        const auto& img = static_cast<const PageImage&>(*el);
+        int16_t x = img.xPos;
+        int16_t y = img.yPos;
+        int16_t right = x + img.getImageBlock().getWidth();
+        int16_t bottom = y + img.getImageBlock().getHeight();
+        minX = std::min(minX, x);
+        minY = std::min(minY, y);
+        maxX = std::max(maxX, right);
+        maxY = std::max(maxY, bottom);
+        found = true;
+      }
+    }
+    if (found) {
+      outX = minX;
+      outY = minY;
+      outW = maxX - minX;
+      outH = maxY - minY;
+    }
+    return found;
+  }
 };

lib/Epub/Epub/ParsedText.cpp

@@ -1,6 +1,7 @@
 #include "ParsedText.h"
 
 #include <GfxRenderer.h>
+#include <Utf8.h>
 
 #include <algorithm>
 #include <cmath>
@@ -8,13 +9,84 @@
 #include <limits>
 #include <vector>
 
+#include "hyphenation/Hyphenator.h"
+
 constexpr int MAX_COST = std::numeric_limits<int>::max();
 
-void ParsedText::addWord(std::string word, const EpdFontFamily::Style fontStyle) {
+namespace {
+
+// Soft hyphen byte pattern used throughout EPUBs (UTF-8 for U+00AD).
+constexpr char SOFT_HYPHEN_UTF8[] = "\xC2\xAD";
+constexpr size_t SOFT_HYPHEN_BYTES = 2;
+
+// Returns the first rendered codepoint of a word (skipping leading soft hyphens).
+uint32_t firstCodepoint(const std::string& word) {
+  const auto* ptr = reinterpret_cast<const unsigned char*>(word.c_str());
+  while (true) {
+    const uint32_t cp = utf8NextCodepoint(&ptr);
+    if (cp == 0) return 0;
+    if (cp != 0x00AD) return cp;  // skip soft hyphens
+  }
+}
+
+// Returns the last codepoint of a word by scanning backward for the start of the last UTF-8 sequence.
+uint32_t lastCodepoint(const std::string& word) {
+  if (word.empty()) return 0;
+  // UTF-8 continuation bytes start with 10xxxxxx; scan backward to find the leading byte.
+  size_t i = word.size() - 1;
+  while (i > 0 && (static_cast<uint8_t>(word[i]) & 0xC0) == 0x80) {
+    --i;
+  }
+  const auto* ptr = reinterpret_cast<const unsigned char*>(word.c_str() + i);
+  return utf8NextCodepoint(&ptr);
+}
+
+bool containsSoftHyphen(const std::string& word) { return word.find(SOFT_HYPHEN_UTF8) != std::string::npos; }
+
+// Removes every soft hyphen in-place so rendered glyphs match measured widths.
+void stripSoftHyphensInPlace(std::string& word) {
+  size_t pos = 0;
+  while ((pos = word.find(SOFT_HYPHEN_UTF8, pos)) != std::string::npos) {
+    word.erase(pos, SOFT_HYPHEN_BYTES);
+  }
+}
+
+// Returns the advance width for a word while ignoring soft hyphen glyphs and optionally appending a visible hyphen.
+// Uses advance width (sum of glyph advances + kerning) rather than bounding box width so that italic glyph overhangs
+// don't inflate inter-word spacing.
+uint16_t measureWordWidth(const GfxRenderer& renderer, const int fontId, const std::string& word,
+                          const EpdFontFamily::Style style, const bool appendHyphen = false) {
+  if (word.size() == 1 && word[0] == ' ' && !appendHyphen) {
+    return renderer.getSpaceWidth(fontId, style);
+  }
+  const bool hasSoftHyphen = containsSoftHyphen(word);
+  if (!hasSoftHyphen && !appendHyphen) {
+    return renderer.getTextAdvanceX(fontId, word.c_str(), style);
+  }
+
+  std::string sanitized = word;
+  if (hasSoftHyphen) {
+    stripSoftHyphensInPlace(sanitized);
+  }
+  if (appendHyphen) {
+    sanitized.push_back('-');
+  }
+  return renderer.getTextAdvanceX(fontId, sanitized.c_str(), style);
+}
+
+}  // namespace
+
+void ParsedText::addWord(std::string word, const EpdFontFamily::Style fontStyle, const bool underline,
+                         const bool attachToPrevious) {
   if (word.empty()) return;
 
   words.push_back(std::move(word));
-  wordStyles.push_back(fontStyle);
+  EpdFontFamily::Style combinedStyle = fontStyle;
+  if (underline) {
+    combinedStyle = static_cast<EpdFontFamily::Style>(combinedStyle | EpdFontFamily::UNDERLINE);
+  }
+  wordStyles.push_back(combinedStyle);
+  wordContinues.push_back(attachToPrevious);
 }
 
 // Consumes data to minimize memory usage
@@ -25,44 +97,72 @@ void ParsedText::layoutAndExtractLines(const GfxRenderer& renderer, const int fo
     return;
   }
 
+  // Apply fixed transforms before any per-line layout work.
+  applyParagraphIndent();
+
   const int pageWidth = viewportWidth;
-  const int spaceWidth = renderer.getSpaceWidth(fontId);
-  const auto wordWidths = calculateWordWidths(renderer, fontId);
-  const auto lineBreakIndices = computeLineBreaks(pageWidth, spaceWidth, wordWidths);
+  auto wordWidths = calculateWordWidths(renderer, fontId);
+
+  std::vector<size_t> lineBreakIndices;
+  if (hyphenationEnabled) {
+    // Use greedy layout that can split words mid-loop when a hyphenated prefix fits.
+    lineBreakIndices = computeHyphenatedLineBreaks(renderer, fontId, pageWidth, wordWidths, wordContinues);
+  } else {
+    lineBreakIndices = computeLineBreaks(renderer, fontId, pageWidth, wordWidths, wordContinues);
+  }
   const size_t lineCount = includeLastLine ? lineBreakIndices.size() : lineBreakIndices.size() - 1;
 
   for (size_t i = 0; i < lineCount; ++i) {
-    extractLine(i, pageWidth, spaceWidth, wordWidths, lineBreakIndices, processLine);
+    extractLine(i, pageWidth, wordWidths, wordContinues, lineBreakIndices, processLine, renderer, fontId);
+  }
+
+  // Remove consumed words so size() reflects only remaining words
+  if (lineCount > 0) {
+    const size_t consumed = lineBreakIndices[lineCount - 1];
+    words.erase(words.begin(), words.begin() + consumed);
+    wordStyles.erase(wordStyles.begin(), wordStyles.begin() + consumed);
+    wordContinues.erase(wordContinues.begin(), wordContinues.begin() + consumed);
   }
 }
 
 std::vector<uint16_t> ParsedText::calculateWordWidths(const GfxRenderer& renderer, const int fontId) {
-  const size_t totalWordCount = words.size();
-
   std::vector<uint16_t> wordWidths;
-  wordWidths.reserve(totalWordCount);
+  wordWidths.reserve(words.size());
 
-  // add em-space at the beginning of first word in paragraph to indent
-  if (!extraParagraphSpacing) {
-    std::string& first_word = words.front();
-    first_word.insert(0, "\xe2\x80\x83");
-  }
-
-  auto wordsIt = words.begin();
-  auto wordStylesIt = wordStyles.begin();
-
-  while (wordsIt != words.end()) {
-    wordWidths.push_back(renderer.getTextWidth(fontId, wordsIt->c_str(), *wordStylesIt));
-
-    std::advance(wordsIt, 1);
-    std::advance(wordStylesIt, 1);
+  for (size_t i = 0; i < words.size(); ++i) {
+    wordWidths.push_back(measureWordWidth(renderer, fontId, words[i], wordStyles[i]));
   }
 
   return wordWidths;
 }
 
-std::vector<size_t> ParsedText::computeLineBreaks(const int pageWidth, const int spaceWidth,
-                                                  const std::vector<uint16_t>& wordWidths) const {
+std::vector<size_t> ParsedText::computeLineBreaks(const GfxRenderer& renderer, const int fontId, const int pageWidth,
+                                                  std::vector<uint16_t>& wordWidths, std::vector<bool>& continuesVec) {
+  if (words.empty()) {
+    return {};
+  }
+
+  // Calculate first line indent (only for left/justified text).
+  // Positive text-indent (paragraph indent) is suppressed when extraParagraphSpacing is on.
+  // Negative text-indent (hanging indent, e.g. margin-left:3em; text-indent:-1em) always applies —
+  // it is structural (positions the bullet/marker), not decorative.
+  const int firstLineIndent =
+      blockStyle.textIndentDefined && (blockStyle.textIndent < 0 || !extraParagraphSpacing) &&
+              (blockStyle.alignment == CssTextAlign::Justify || blockStyle.alignment == CssTextAlign::Left)
+          ? blockStyle.textIndent
+          : 0;
+
+  // Ensure any word that would overflow even as the first entry on a line is split using fallback hyphenation.
+  for (size_t i = 0; i < wordWidths.size(); ++i) {
+    // First word needs to fit in reduced width if there's an indent
+    const int effectiveWidth = i == 0 ? pageWidth - firstLineIndent : pageWidth;
+    while (wordWidths[i] > effectiveWidth) {
+      if (!hyphenateWordAtIndex(i, effectiveWidth, renderer, fontId, wordWidths, /*allowFallbackBreaks=*/true)) {
+        break;
+      }
+    }
+  }
+
   const size_t totalWordCount = words.size();
 
   // DP table to store the minimum badness (cost) of lines starting at index i
@@ -75,22 +175,38 @@ std::vector<size_t> ParsedText::computeLineBreaks(const int pageWidth, const int
   ans[totalWordCount - 1] = totalWordCount - 1;
 
   for (int i = totalWordCount - 2; i >= 0; --i) {
-    int currlen = -spaceWidth;
+    int currlen = 0;
     dp[i] = MAX_COST;
 
-    for (size_t j = i; j < totalWordCount; ++j) {
-      // Current line length: previous width + space + current word width
-      currlen += wordWidths[j] + spaceWidth;
+    // First line has reduced width due to text-indent
+    const int effectivePageWidth = i == 0 ? pageWidth - firstLineIndent : pageWidth;
 
-      if (currlen > pageWidth) {
+    for (size_t j = i; j < totalWordCount; ++j) {
+      // Add space before word j, unless it's the first word on the line or a continuation
+      int gap = 0;
+      if (j > static_cast<size_t>(i) && !continuesVec[j]) {
+        gap =
+            renderer.getSpaceAdvance(fontId, lastCodepoint(words[j - 1]), firstCodepoint(words[j]), wordStyles[j - 1]);
+      } else if (j > static_cast<size_t>(i) && continuesVec[j]) {
+        // Cross-boundary kerning for continuation words (e.g. nonbreaking spaces, attached punctuation)
+        gap = renderer.getKerning(fontId, lastCodepoint(words[j - 1]), firstCodepoint(words[j]), wordStyles[j - 1]);
+      }
+      currlen += wordWidths[j] + gap;
+
+      if (currlen > effectivePageWidth) {
         break;
       }
 
+      // Cannot break after word j if the next word attaches to it (continuation group)
+      if (j + 1 < totalWordCount && continuesVec[j + 1]) {
+        continue;
+      }
+
       int cost;
       if (j == totalWordCount - 1) {
         cost = 0;  // Last line
       } else {
-        const int remainingSpace = pageWidth - currlen;
+        const int remainingSpace = effectivePageWidth - currlen;
         // Use long long for the square to prevent overflow
         const long long cost_ll = static_cast<long long>(remainingSpace) * remainingSpace + dp[j + 1];
 
@@ -140,56 +256,286 @@ std::vector<size_t> ParsedText::computeLineBreaks(const int pageWidth, const int
   return lineBreakIndices;
 }
 
-void ParsedText::extractLine(const size_t breakIndex, const int pageWidth, const int spaceWidth,
-                             const std::vector<uint16_t>& wordWidths, const std::vector<size_t>& lineBreakIndices,
-                             const std::function<void(std::shared_ptr<TextBlock>)>& processLine) {
+void ParsedText::applyParagraphIndent() {
+  if (extraParagraphSpacing || words.empty()) {
+    return;
+  }
+
+  if (blockStyle.textIndentDefined) {
+    // CSS text-indent is explicitly set (even if 0) - don't use fallback EmSpace
+    // The actual indent positioning is handled in extractLine()
+  } else if (blockStyle.alignment == CssTextAlign::Justify || blockStyle.alignment == CssTextAlign::Left) {
+    // No CSS text-indent defined - use EmSpace fallback for visual indent
+    words.front().insert(0, "\xe2\x80\x83");
+  }
+}
+
+// Builds break indices while opportunistically splitting the word that would overflow the current line.
+std::vector<size_t> ParsedText::computeHyphenatedLineBreaks(const GfxRenderer& renderer, const int fontId,
+                                                            const int pageWidth, std::vector<uint16_t>& wordWidths,
+                                                            std::vector<bool>& continuesVec) {
+  // Calculate first line indent (only for left/justified text).
+  // Positive text-indent (paragraph indent) is suppressed when extraParagraphSpacing is on.
+  // Negative text-indent (hanging indent, e.g. margin-left:3em; text-indent:-1em) always applies —
+  // it is structural (positions the bullet/marker), not decorative.
+  const int firstLineIndent =
+      blockStyle.textIndentDefined && (blockStyle.textIndent < 0 || !extraParagraphSpacing) &&
+              (blockStyle.alignment == CssTextAlign::Justify || blockStyle.alignment == CssTextAlign::Left)
+          ? blockStyle.textIndent
+          : 0;
+
+  std::vector<size_t> lineBreakIndices;
+  size_t currentIndex = 0;
+  bool isFirstLine = true;
+
+  while (currentIndex < wordWidths.size()) {
+    const size_t lineStart = currentIndex;
+    int lineWidth = 0;
+
+    // First line has reduced width due to text-indent
+    const int effectivePageWidth = isFirstLine ? pageWidth - firstLineIndent : pageWidth;
+
+    // Consume as many words as possible for current line, splitting when prefixes fit
+    while (currentIndex < wordWidths.size()) {
+      const bool isFirstWord = currentIndex == lineStart;
+      int spacing = 0;
+      if (!isFirstWord && !continuesVec[currentIndex]) {
+        spacing = renderer.getSpaceAdvance(fontId, lastCodepoint(words[currentIndex - 1]),
+                                           firstCodepoint(words[currentIndex]), wordStyles[currentIndex - 1]);
+      } else if (!isFirstWord && continuesVec[currentIndex]) {
+        // Cross-boundary kerning for continuation words (e.g. nonbreaking spaces, attached punctuation)
+        spacing = renderer.getKerning(fontId, lastCodepoint(words[currentIndex - 1]),
+                                      firstCodepoint(words[currentIndex]), wordStyles[currentIndex - 1]);
+      }
+      const int candidateWidth = spacing + wordWidths[currentIndex];
+
+      // Word fits on current line
+      if (lineWidth + candidateWidth <= effectivePageWidth) {
+        lineWidth += candidateWidth;
+        ++currentIndex;
+        continue;
+      }
+
+      // Word would overflow — try to split based on hyphenation points
+      const int availableWidth = effectivePageWidth - lineWidth - spacing;
+      const bool allowFallbackBreaks = isFirstWord;  // Only for first word on line
+
+      if (availableWidth > 0 &&
+          hyphenateWordAtIndex(currentIndex, availableWidth, renderer, fontId, wordWidths, allowFallbackBreaks)) {
+        // Prefix now fits; append it to this line and move to next line
+        lineWidth += spacing + wordWidths[currentIndex];
+        ++currentIndex;
+        break;
+      }
+
+      // Could not split: force at least one word per line to avoid infinite loop
+      if (currentIndex == lineStart) {
+        lineWidth += candidateWidth;
+        ++currentIndex;
+      }
+      break;
+    }
+
+    // Don't break before a continuation word (e.g., orphaned "?" after "question").
+    // Backtrack to the start of the continuation group so the whole group moves to the next line.
+    while (currentIndex > lineStart + 1 && currentIndex < wordWidths.size() && continuesVec[currentIndex]) {
+      --currentIndex;
+    }
+
+    lineBreakIndices.push_back(currentIndex);
+    isFirstLine = false;
+  }
+
+  return lineBreakIndices;
+}
+
+// Splits words[wordIndex] into prefix (adding a hyphen only when needed) and remainder when a legal breakpoint fits the
+// available width.
+bool ParsedText::hyphenateWordAtIndex(const size_t wordIndex, const int availableWidth, const GfxRenderer& renderer,
+                                      const int fontId, std::vector<uint16_t>& wordWidths,
+                                      const bool allowFallbackBreaks) {
+  // Guard against invalid indices or zero available width before attempting to split.
+  if (availableWidth <= 0 || wordIndex >= words.size()) {
+    return false;
+  }
+
+  const std::string& word = words[wordIndex];
+  const auto style = wordStyles[wordIndex];
+
+  // Collect candidate breakpoints (byte offsets and hyphen requirements).
+  auto breakInfos = Hyphenator::breakOffsets(word, allowFallbackBreaks);
+  if (breakInfos.empty()) {
+    return false;
+  }
+
+  size_t chosenOffset = 0;
+  int chosenWidth = -1;
+  bool chosenNeedsHyphen = true;
+
+  // Iterate over each legal breakpoint and retain the widest prefix that still fits.
+  for (const auto& info : breakInfos) {
+    const size_t offset = info.byteOffset;
+    if (offset == 0 || offset >= word.size()) {
+      continue;
+    }
+
+    const bool needsHyphen = info.requiresInsertedHyphen;
+    const int prefixWidth = measureWordWidth(renderer, fontId, word.substr(0, offset), style, needsHyphen);
+    if (prefixWidth > availableWidth || prefixWidth <= chosenWidth) {
+      continue;  // Skip if too wide or not an improvement
+    }
+
+    chosenWidth = prefixWidth;
+    chosenOffset = offset;
+    chosenNeedsHyphen = needsHyphen;
+  }
+
+  if (chosenWidth < 0) {
+    // No hyphenation point produced a prefix that fits in the remaining space.
+    return false;
+  }
+
+  // Split the word at the selected breakpoint and append a hyphen if required.
+  std::string remainder = word.substr(chosenOffset);
+  words[wordIndex].resize(chosenOffset);
+  if (chosenNeedsHyphen) {
+    words[wordIndex].push_back('-');
+  }
+
+  // Insert the remainder word (with matching style and continuation flag) directly after the prefix.
+  words.insert(words.begin() + wordIndex + 1, remainder);
+  wordStyles.insert(wordStyles.begin() + wordIndex + 1, style);
+
+  // Continuation flag handling after splitting a word into prefix + remainder.
+  //
+  // The prefix keeps the original word's continuation flag so that no-break-space groups
+  // stay linked. The remainder always gets continues=false because it starts on the next
+  // line and is not attached to the prefix.
+  //
+  // Example: "200&#xA0;Quadratkilometer" produces tokens:
+  //   [0] "200"               continues=false
+  //   [1] " "                 continues=true
+  //   [2] "Quadratkilometer"  continues=true   <-- the word being split
+  //
+  // After splitting "Quadratkilometer" at "Quadrat-" / "kilometer":
+  //   [0] "200"         continues=false
+  //   [1] " "           continues=true
+  //   [2] "Quadrat-"    continues=true   (KEPT — still attached to the no-break group)
+  //   [3] "kilometer"   continues=false  (NEW — starts fresh on the next line)
+  //
+  // This lets the backtracking loop keep the entire prefix group ("200 Quadrat-") on one
+  // line, while "kilometer" moves to the next line.
+  // wordContinues[wordIndex] is intentionally left unchanged — the prefix keeps its original attachment.
+  wordContinues.insert(wordContinues.begin() + wordIndex + 1, false);
+
+  // Update cached widths to reflect the new prefix/remainder pairing.
+  wordWidths[wordIndex] = static_cast<uint16_t>(chosenWidth);
+  const uint16_t remainderWidth = measureWordWidth(renderer, fontId, remainder, style);
+  wordWidths.insert(wordWidths.begin() + wordIndex + 1, remainderWidth);
+  return true;
+}
+
+void ParsedText::extractLine(const size_t breakIndex, const int pageWidth, const std::vector<uint16_t>& wordWidths,
+                             const std::vector<bool>& continuesVec, const std::vector<size_t>& lineBreakIndices,
+                             const std::function<void(std::shared_ptr<TextBlock>)>& processLine,
+                             const GfxRenderer& renderer, const int fontId) {
   const size_t lineBreak = lineBreakIndices[breakIndex];
   const size_t lastBreakAt = breakIndex > 0 ? lineBreakIndices[breakIndex - 1] : 0;
   const size_t lineWordCount = lineBreak - lastBreakAt;
 
-  // Calculate total word width for this line
+  // Calculate first line indent (only for left/justified text).
+  // Positive text-indent (paragraph indent) is suppressed when extraParagraphSpacing is on.
+  // Negative text-indent (hanging indent, e.g. margin-left:3em; text-indent:-1em) always applies —
+  // it is structural (positions the bullet/marker), not decorative.
+  const bool isFirstLine = breakIndex == 0;
+  const int firstLineIndent =
+      isFirstLine && blockStyle.textIndentDefined && (blockStyle.textIndent < 0 || !extraParagraphSpacing) &&
+              (blockStyle.alignment == CssTextAlign::Justify || blockStyle.alignment == CssTextAlign::Left)
+          ? blockStyle.textIndent
+          : 0;
+
+  // Calculate total word width for this line, count actual word gaps,
+  // and accumulate total natural gap widths (including space kerning adjustments).
   int lineWordWidthSum = 0;
-  for (size_t i = lastBreakAt; i < lineBreak; i++) {
-    lineWordWidthSum += wordWidths[i];
+  size_t actualGapCount = 0;
+  int totalNaturalGaps = 0;
+
+  for (size_t wordIdx = 0; wordIdx < lineWordCount; wordIdx++) {
+    lineWordWidthSum += wordWidths[lastBreakAt + wordIdx];
+    // Count gaps: each word after the first creates a gap, unless it's a continuation
+    if (wordIdx > 0 && !continuesVec[lastBreakAt + wordIdx]) {
+      actualGapCount++;
+      totalNaturalGaps +=
+          renderer.getSpaceAdvance(fontId, lastCodepoint(words[lastBreakAt + wordIdx - 1]),
+                                   firstCodepoint(words[lastBreakAt + wordIdx]), wordStyles[lastBreakAt + wordIdx - 1]);
+    } else if (wordIdx > 0 && continuesVec[lastBreakAt + wordIdx]) {
+      // Cross-boundary kerning for continuation words (e.g. nonbreaking spaces, attached punctuation)
+      totalNaturalGaps +=
+          renderer.getKerning(fontId, lastCodepoint(words[lastBreakAt + wordIdx - 1]),
+                              firstCodepoint(words[lastBreakAt + wordIdx]), wordStyles[lastBreakAt + wordIdx - 1]);
+    }
   }
 
-  // Calculate spacing
-  const int spareSpace = pageWidth - lineWordWidthSum;
-
-  int spacing = spaceWidth;
+  // Calculate spacing (account for indent reducing effective page width on first line)
+  const int effectivePageWidth = pageWidth - firstLineIndent;
   const bool isLastLine = breakIndex == lineBreakIndices.size() - 1;
 
-  if (style == TextBlock::JUSTIFIED && !isLastLine && lineWordCount >= 2) {
-    spacing = spareSpace / (lineWordCount - 1);
-  }
+  // For justified text, compute per-gap extra to distribute remaining space evenly
+  const int spareSpace = effectivePageWidth - lineWordWidthSum - totalNaturalGaps;
+  const int justifyExtra = (blockStyle.alignment == CssTextAlign::Justify && !isLastLine && actualGapCount >= 1)
+                               ? spareSpace / static_cast<int>(actualGapCount)
+                               : 0;
 
-  // Calculate initial x position
-  uint16_t xpos = 0;
-  if (style == TextBlock::RIGHT_ALIGN) {
-    xpos = spareSpace - (lineWordCount - 1) * spaceWidth;
-  } else if (style == TextBlock::CENTER_ALIGN) {
-    xpos = (spareSpace - (lineWordCount - 1) * spaceWidth) / 2;
+  // Calculate initial x position (first line starts at indent for left/justified text;
+  // may be negative for hanging indents, e.g. margin-left:3em; text-indent:-1em).
+  auto xpos = static_cast<int16_t>(firstLineIndent);
+  if (blockStyle.alignment == CssTextAlign::Right) {
+    xpos = effectivePageWidth - lineWordWidthSum - totalNaturalGaps;
+  } else if (blockStyle.alignment == CssTextAlign::Center) {
+    xpos = (effectivePageWidth - lineWordWidthSum - totalNaturalGaps) / 2;
   }
 
   // Pre-calculate X positions for words
-  std::list<uint16_t> lineXPos;
-  for (size_t i = lastBreakAt; i < lineBreak; i++) {
-    const uint16_t currentWordWidth = wordWidths[i];
+  // Continuation words attach to the previous word with no space before them
+  std::vector<int16_t> lineXPos;
+  lineXPos.reserve(lineWordCount);
+
+  for (size_t wordIdx = 0; wordIdx < lineWordCount; wordIdx++) {
     lineXPos.push_back(xpos);
-    xpos += currentWordWidth + spacing;
+
+    const bool nextIsContinuation = wordIdx + 1 < lineWordCount && continuesVec[lastBreakAt + wordIdx + 1];
+    if (nextIsContinuation) {
+      int advance = wordWidths[lastBreakAt + wordIdx];
+      // Cross-boundary kerning for continuation words (e.g. nonbreaking spaces, attached punctuation)
+      advance +=
+          renderer.getKerning(fontId, lastCodepoint(words[lastBreakAt + wordIdx]),
+                              firstCodepoint(words[lastBreakAt + wordIdx + 1]), wordStyles[lastBreakAt + wordIdx]);
+      xpos += advance;
+    } else {
+      int gap = 0;
+      if (wordIdx + 1 < lineWordCount) {
+        gap = renderer.getSpaceAdvance(fontId, lastCodepoint(words[lastBreakAt + wordIdx]),
+                                       firstCodepoint(words[lastBreakAt + wordIdx + 1]),
+                                       wordStyles[lastBreakAt + wordIdx]);
+      }
+      if (blockStyle.alignment == CssTextAlign::Justify && !isLastLine) {
+        gap += justifyExtra;
+      }
+      xpos += wordWidths[lastBreakAt + wordIdx] + gap;
+    }
   }
 
-  // Iterators always start at the beginning as we are moving content with splice below
-  auto wordEndIt = words.begin();
-  auto wordStyleEndIt = wordStyles.begin();
-  std::advance(wordEndIt, lineWordCount);
-  std::advance(wordStyleEndIt, lineWordCount);
+  // Build line data by moving from the original vectors using index range
+  std::vector<std::string> lineWords(std::make_move_iterator(words.begin() + lastBreakAt),
+                                     std::make_move_iterator(words.begin() + lineBreak));
+  std::vector<EpdFontFamily::Style> lineWordStyles(wordStyles.begin() + lastBreakAt, wordStyles.begin() + lineBreak);
 
-  // *** CRITICAL STEP: CONSUME DATA USING SPLICE ***
-  std::list<std::string> lineWords;
-  lineWords.splice(lineWords.begin(), words, words.begin(), wordEndIt);
-  std::list<EpdFontFamily::Style> lineWordStyles;
-  lineWordStyles.splice(lineWordStyles.begin(), wordStyles, wordStyles.begin(), wordStyleEndIt);
+  for (auto& word : lineWords) {
+    if (containsSoftHyphen(word)) {
+      stripSoftHyphensInPlace(word);
+    }
+  }
 
-  processLine(std::make_shared<TextBlock>(std::move(lineWords), std::move(lineXPos), std::move(lineWordStyles), style));
+  processLine(
+      std::make_shared<TextBlock>(std::move(lineWords), std::move(lineXPos), std::move(lineWordStyles), blockStyle));
 }