mod: Phase 1 - bring forward mod-exclusive files with ActivityManager migration

Brings ~55 mod-exclusive files to the upstream-based mod/master-resync branch: Activities (migrated to new ActivityManager pattern): - Clock/Time: SetTimeActivity, SetTimezoneOffsetActivity, NtpSyncActivity - Dictionary: DictionaryDefinitionActivity, DictionarySuggestionsActivity, DictionaryWordSelectActivity, LookedUpWordsActivity - Bookmark: EpubReaderBookmarkSelectionActivity - Book management: BookManageMenuActivity, EndOfBookMenuActivity - OPDS: OpdsServerListActivity, OpdsSettingsActivity - Utility: DirectoryPickerActivity, NumericStepperActivity Utilities (unchanged): - BookManager, BookSettings, BookmarkStore, BootNtpSync - Dictionary, LookupHistory, TimeSync, OpdsServerStore Libraries: PlaceholderCover, TableData, ChapterXPathIndexer Scripts: inject_mod_version, generate_book_icon, preview_placeholder_cover Docs: KOReader sync XPath mapping Migration changes: - ActivityWithSubactivity -> Activity base class - Callback constructors -> finish()/setResult() pattern - enterNewActivity() -> startActivityForResult() - Activity::RenderLock&& -> RenderLock&& These files won't compile yet - they reference mod settings and I18n strings that will be added in subsequent phases. Made-with: Cursor
2026-03-07 15:10:00 -05:00
parent 170cc25774
commit dfbc931c14
147 changed files with 112771 additions and 1 deletions
--- a/mod/docs/file-structure.md
+++ b/mod/docs/file-structure.md
@@ -0,0 +1,306 @@
+# CrossPoint Reader -- Project File Structure
+
+This document maps the repository layout and describes where key pieces of code can be found.
+
+## Root Directory
+
+```
+crosspoint-reader-mod/
+├── platformio.ini          # PlatformIO build config (environments, flags, deps)
+├── partitions.csv          # ESP32 flash partition table
+├── .clang-format           # C++ code formatting rules (clang-format 21)
+├── .clangd                 # Language server configuration
+├── .gitmodules             # Git submodule reference (open-x4-sdk)
+├── README.md               # Project overview and getting started
+├── LICENSE                 # MIT License
+├── GOVERNANCE.md           # Community governance principles
+├── SCOPE.md                # Project vision and feature scope
+├── USER_GUIDE.md           # End-user manual
+├── bin/                    # Developer scripts
+├── docs/                   # Upstream documentation
+├── lib/                    # Project libraries (HAL, EPUB, fonts, etc.)
+├── src/                    # Main application source code
+├── scripts/                # Build and utility scripts (Python)
+├── test/                   # Unit/evaluation tests
+├── open-x4-sdk/            # Hardware SDK (git submodule)
+├── include/                # PlatformIO include directory (empty)
+├── mod/                    # Local modifications workspace
+└── .github/                # CI workflows, templates, funding
+```
+
+## `src/` -- Application Source
+
+The main firmware application code. Entry point is `main.cpp`.
+
+```
+src/
+├── main.cpp                    # Arduino setup()/loop(), activity routing, font init
+├── CrossPointSettings.cpp/.h   # User settings (load/save to SD, defaults)
+├── CrossPointState.cpp/.h      # Runtime application state (open book, sleep tracking)
+├── MappedInputManager.cpp/.h   # User-remappable button abstraction over HalGPIO
+├── Battery.h                   # Global BatteryMonitor instance
+├── fontIds.h                   # Numeric font family identifiers
+├── SettingsList.h              # Setting definitions and enums
+├── RecentBooksStore.cpp/.h     # Recently opened books persistence
+├── WifiCredentialStore.cpp/.h  # Saved WiFi network credentials
+│
+├── activities/                 # UI screens (Activity pattern, see below)
+├── components/                 # Shared UI components and themes
+├── network/                    # Web server, HTTP, OTA updater
+├── images/                     # Logo assets (SVG, PNG, compiled header)
+└── util/                       # String and URL utility functions
+```
+
+### `src/activities/` -- UI Activity System
+
+Each screen is an `Activity` subclass with `onEnter()`, `onExit()`, and `loop()` lifecycle methods. Activities are swapped by the routing functions in `main.cpp`.
+
+```
+activities/
+├── Activity.h                              # Base Activity interface
+├── ActivityWithSubactivity.cpp/.h          # Composition: activity that hosts a child
+│
+├── boot_sleep/
+│   ├── BootActivity.cpp/.h                 # Boot splash screen
+│   └── SleepActivity.cpp/.h               # Sleep screen (cover image, clock, etc.)
+│
+├── browser/
+│   └── OpdsBookBrowserActivity.cpp/.h      # OPDS catalog browsing and download
+│
+├── home/
+│   ├── HomeActivity.cpp/.h                 # Main menu / home screen
+│   ├── MyLibraryActivity.cpp/.h            # File browser for books on SD card
+│   └── RecentBooksActivity.cpp/.h          # Recently opened books list
+│
+├── network/
+│   ├── CrossPointWebServerActivity.cpp/.h  # Web server file transfer mode
+│   ├── CalibreConnectActivity.cpp/.h       # Calibre wireless device connection
+│   ├── NetworkModeSelectionActivity.cpp/.h # WiFi/AP/Calibre mode picker
+│   └── WifiSelectionActivity.cpp/.h        # WiFi network scanner and connector
+│
+├── reader/
+│   ├── ReaderActivity.cpp/.h               # Format dispatcher (EPUB, TXT, XTC)
+│   ├── EpubReaderActivity.cpp/.h           # EPUB reading engine
+│   ├── EpubReaderMenuActivity.cpp/.h       # In-reader menu overlay
+│   ├── EpubReaderChapterSelectionActivity.cpp/.h   # Table of contents navigation
+│   ├── EpubReaderPercentSelectionActivity.cpp/.h   # Jump-to-percentage navigation
+│   ├── TxtReaderActivity.cpp/.h            # Plain text reader
+│   ├── XtcReaderActivity.cpp/.h            # XTC format reader
+│   ├── XtcReaderChapterSelectionActivity.cpp/.h    # XTC chapter navigation
+│   └── KOReaderSyncActivity.cpp/.h         # KOReader reading progress sync
+│
+├── settings/
+│   ├── SettingsActivity.cpp/.h             # Main settings screen
+│   ├── ButtonRemapActivity.cpp/.h          # Front button remapping UI
+│   ├── CalibreSettingsActivity.cpp/.h      # Calibre server configuration
+│   ├── ClearCacheActivity.cpp/.h           # Cache clearing utility
+│   ├── KOReaderAuthActivity.cpp/.h         # KOReader auth credential entry
+│   ├── KOReaderSettingsActivity.cpp/.h     # KOReader sync settings
+│   └── OtaUpdateActivity.cpp/.h            # Over-the-air firmware update UI
+│
+└── util/
+    ├── FullScreenMessageActivity.cpp/.h    # Full-screen status/error messages
+    └── KeyboardEntryActivity.cpp/.h        # On-screen keyboard for text input
+```
+
+### `src/components/` -- UI Components and Themes
+
+```
+components/
+├── UITheme.cpp/.h              # Theme manager singleton
+└── themes/
+    ├── BaseTheme.cpp/.h        # Default theme implementation
+    └── lyra/
+        └── LyraTheme.cpp/.h   # Alternative "Lyra" theme
+```
+
+### `src/network/` -- Networking
+
+```
+network/
+├── CrossPointWebServer.cpp/.h  # HTTP web server (file management, upload, settings)
+├── HttpDownloader.cpp/.h       # HTTP/HTTPS file downloader
+├── OtaUpdater.cpp/.h           # OTA firmware update client
+└── html/
+    ├── HomePage.html           # Web UI home page
+    ├── FilesPage.html          # Web UI file browser / upload page
+    └── SettingsPage.html       # Web UI settings page
+```
+
+HTML files are minified at build time by `scripts/build_html.py` into `PROGMEM` C++ headers (`.generated.h`).
+
+### `src/util/` -- Utilities
+
+```
+util/
+├── StringUtils.cpp/.h          # String manipulation helpers
+└── UrlUtils.cpp/.h             # URL encoding/decoding
+```
+
+## `lib/` -- Project Libraries
+
+PlatformIO-managed libraries local to the project.
+
+### `lib/hal/` -- Hardware Abstraction Layer
+
+The HAL wraps the SDK drivers behind a stable API the rest of the firmware consumes.
+
+| File | Purpose |
+|---|---|
+| `HalDisplay.cpp/.h` | E-ink display control (refresh, buffer ops, grayscale, sleep) |
+| `HalGPIO.cpp/.h` | Button input, battery reading, USB detection, deep sleep, wakeup |
+| `HalStorage.cpp/.h` | SD card file operations (`Storage` singleton) |
+
+### `lib/Epub/` -- EPUB Library
+
+The core document parsing and rendering engine.
+
+```
+Epub/
+├── Epub.cpp/.h                     # Top-level EPUB interface
+├── Epub/
+│   ├── Page.cpp/.h                 # Single rendered page
+│   ├── Section.cpp/.h              # Book section (chapter)
+│   ├── ParsedText.cpp/.h           # Parsed text representation
+│   ├── BookMetadataCache.cpp/.h    # Metadata caching to SD card
+│   │
+│   ├── blocks/
+│   │   ├── Block.h                 # Base block type
+│   │   ├── BlockStyle.h            # Block styling
+│   │   └── TextBlock.cpp/.h       # Text block rendering
+│   │
+│   ├── css/
+│   │   ├── CssParser.cpp/.h       # CSS subset parser
+│   │   └── CssStyle.h             # Parsed CSS style representation
+│   │
+│   ├── hyphenation/
+│   │   ├── Hyphenator.cpp/.h       # Main hyphenation API
+│   │   ├── LiangHyphenation.cpp/.h # Liang algorithm implementation
+│   │   ├── HyphenationCommon.cpp/.h # Shared types
+│   │   ├── LanguageHyphenator.h    # Per-language interface
+│   │   ├── LanguageRegistry.cpp/.h # Language detection and routing
+│   │   ├── SerializedHyphenationTrie.h # Trie data format
+│   │   └── generated/             # Pre-built hyphenation tries
+│   │       ├── hyph-de.trie.h     # German
+│   │       ├── hyph-en.trie.h     # English
+│   │       ├── hyph-es.trie.h     # Spanish
+│   │       ├── hyph-fr.trie.h     # French
+│   │       └── hyph-ru.trie.h     # Russian
+│   │
+│   └── parsers/
+│       ├── ChapterHtmlSlimParser.cpp/.h  # Chapter HTML content parser
+│       ├── ContainerParser.cpp/.h        # META-INF/container.xml parser
+│       ├── ContentOpfParser.cpp/.h       # content.opf (spine, manifest) parser
+│       ├── TocNavParser.cpp/.h           # EPUB3 nav TOC parser
+│       └── TocNcxParser.cpp/.h           # EPUB2 NCX TOC parser
+```
+
+### `lib/EpdFont/` -- Font Rendering
+
+```
+EpdFont/
+├── EpdFont.cpp/.h              # Font rendering engine
+├── EpdFontData.h               # Raw font data structure
+├── EpdFontFamily.cpp/.h        # Font family (regular, bold, italic, bold-italic)
+├── builtinFonts/
+│   ├── all.h                   # Aggregate include for all built-in fonts
+│   ├── bookerly_*.h            # Bookerly at sizes 12, 14, 16, 18
+│   ├── notosans_*.h            # Noto Sans at sizes 8, 12, 14, 16, 18
+│   ├── opendyslexic_*.h        # OpenDyslexic at sizes 8, 10, 12, 14
+│   ├── ubuntu_*.h              # Ubuntu at sizes 10, 12 (UI font)
+│   └── source/                 # Original TTF/OTF font files
+└── scripts/
+    ├── fontconvert.py          # TTF/OTF to compiled header converter
+    ├── convert-builtin-fonts.sh # Batch conversion script
+    ├── build-font-ids.sh       # Generate fontIds.h
+    └── requirements.txt        # Python dependencies for font tools
+```
+
+### Other Libraries
+
+| Library | Path | Purpose |
+|---|---|---|
+| `expat/` | `lib/expat/` | XML parser (used by EPUB parsers) |
+| `miniz/` | `lib/miniz/` | Compression/decompression (ZIP support) |
+| `ZipFile/` | `lib/ZipFile/` | ZIP file reading (EPUB is a ZIP) |
+| `picojpeg/` | `lib/picojpeg/` | Lightweight JPEG decoder |
+| `JpegToBmpConverter/` | `lib/JpegToBmpConverter/` | JPEG to bitmap conversion for display |
+| `GfxRenderer/` | `lib/GfxRenderer/` | Graphics renderer, bitmap helpers |
+| `Txt/` | `lib/Txt/` | Plain text (.txt) file reader |
+| `Xtc/` | `lib/Xtc/` | XTC format parser and types |
+| `OpdsParser/` | `lib/OpdsParser/` | OPDS feed XML parser and streaming |
+| `KOReaderSync/` | `lib/KOReaderSync/` | KOReader sync client, credential store, progress mapping |
+| `Utf8/` | `lib/Utf8/` | UTF-8 string utilities |
+| `Serialization/` | `lib/Serialization/` | Binary serialization helper |
+| `FsHelpers/` | `lib/FsHelpers/` | File system utility functions |
+
+## `open-x4-sdk/` -- Hardware SDK (Git Submodule)
+
+Community SDK providing low-level hardware drivers. Referenced in `.gitmodules` from `https://github.com/open-x4-epaper/community-sdk.git`.
+
+Supplies four libraries linked as symlinks in `platformio.ini`:
+
+| Library | SDK Path | Purpose |
+|---|---|---|
+| `BatteryMonitor` | `libs/hardware/BatteryMonitor` | Battery voltage ADC reading |
+| `InputManager` | `libs/hardware/InputManager` | Physical button GPIO management |
+| `EInkDisplay` | `libs/display/EInkDisplay` | E-ink display SPI driver |
+| `SDCardManager` | `libs/hardware/SDCardManager` | SD card SPI initialization |
+
+## `scripts/` -- Build and Utility Scripts
+
+| Script | Language | Purpose |
+|---|---|---|
+| `build_html.py` | Python | **Pre-build step.** Minifies HTML files in `src/` into `PROGMEM` C++ headers (`.generated.h`). Strips comments, collapses whitespace, preserves `<pre>`, `<code>`, `<script>`, `<style>` content. |
+| `generate_hyphenation_trie.py` | Python | Generates serialized hyphenation trie headers from TeX hyphenation patterns. |
+| `debugging_monitor.py` | Python | Enhanced serial monitor for debugging output. |
+
+## `test/` -- Tests
+
+```
+test/
+├── README                              # PlatformIO test directory info
+├── run_hyphenation_eval.sh             # Test runner script
+└── hyphenation_eval/
+    ├── HyphenationEvaluationTest.cpp   # Hyphenation accuracy evaluation
+    └── resources/
+        ├── english_hyphenation_tests.txt
+        ├── french_hyphenation_tests.txt
+        ├── german_hyphenation_tests.txt
+        ├── russian_hyphenation_tests.txt
+        ├── spanish_hyphenation_tests.txt
+        └── generate_hyphenation_test_data.py
+```
+
+## `docs/` -- Upstream Documentation
+
+| File | Topic |
+|---|---|
+| `comparison.md` | Feature comparison with stock firmware |
+| `file-formats.md` | Supported document formats |
+| `hyphenation-trie-format.md` | Hyphenation trie binary format specification |
+| `troubleshooting.md` | Common issues and fixes |
+| `webserver.md` | Web server feature guide |
+| `webserver-endpoints.md` | Web server HTTP API reference |
+| `images/` | Screenshots and cover image |
+
+## `.github/` -- GitHub Configuration
+
+```
+.github/
+├── workflows/
+│   ├── ci.yml                      # Main CI: format check, cppcheck, build
+│   ├── release.yml                 # Tag-triggered release build
+│   ├── release_candidate.yml       # Manual RC build (release/* branches)
+│   └── pr-formatting-check.yml     # Semantic PR title validation
+├── PULL_REQUEST_TEMPLATE.md        # PR template (summary, context, AI usage)
+├── ISSUE_TEMPLATE/
+│   └── bug_report.yml              # Bug report form
+└── FUNDING.yml                     # GitHub Sponsors configuration
+```
+
+## `bin/` -- Developer Tools
+
+| Script | Purpose |
+|---|---|
+| `clang-format-fix` | Runs `clang-format` on all tracked `.c`, `.cpp`, `.h`, `.hpp` files (excluding generated font headers). Pass `-g` to format only modified files. |