📚 Library Overhaul
- 🔄 Complete library rewrite — new fixed-record
.datindex replaces JSON for unlimited scalability - 📊 Supports 3,000–4,000+ books — RAM usage is constant (~11 KB) regardless of library size
- 🗂️ Collections/Series support — browse books by series extracted from Calibre and EPUB3 metadata
- 🎨 On-demand cover generation — covers generated per-page with progress indicator, matching Home screen quality
- ⚡ Fast e-ink navigation — partial render optimisation for sub-second page navigation
- 🏷️ Ribbon badges — favourite, completed, and recently-opened status shown on every tile
- 🔍 Full-text search — case-insensitive subtitle search across titles and authors
- 📑 5 filter modes — All, Favourites, Latest Read, Unread, Completed
- 📏 4 grid layouts — 2×2, 3×3, 4×4 with auto-sizing covers and proper crop
- 💾 Persistent state — sort, filter, and search text survive device restarts
- 🧹 Rebuild Library — one-tap full reset of all library data
📖 Collections/Series
- 📚 Extracts
calibre:series/calibre:series_indexfrom EPUB metadata (fast ZIP-based parser) - 📚 EPUB3
belongs-to-collectionfallback with group-position support - 🧭 Browse collections list → enter collection → browse books in series order
- ↩️ Back navigation: collection → collections list → library exit
- 🏷️ Dedicated header labels:
Collections/Collection Name
🔖 Bookmarks & Clippings (v4/v2)
- 🎯 Layout-independent positioning — bookmarks and highlights survive font changes, margin adjustments, and orientation switches
- ✨ Absolute word indexing — each bookmark references a word by its position from chapter start, invariant across layout changes
- 🔍 Word-accurate highlighting — the exact bookmarked word is highlighted on screen regardless of current font or page layout
- 📱 Dedicated browser apps — BookmarksApp and ClippingsApp for browsing all marks across books
- 📋 Text clipping with selection — directional key selection for start/end words, saved with chapter context
- ⚙️ Long-press trigger — configurable front-button long-press for bookmark or clipping mode
- 💡 Inspired by CrossInk's approach — reimagined with layout-independence for Xteink X4/X3
- 🧹 Bookmark persistence v4 — stored in stable
bookdata/directory via BookIdentity hashing
🔄 Upstream Sync
- 🆕 Synced with CPR-vCodex 1.5.0.2 — reading stats fixes, achievements hardening
- ⏰ X3 clock support — DS3231 RTC hardware clock with NTP sync (upstream HalClock)
- 📊 Reading statistics — per-book and global stats with pace tracking (Steroids-enhanced)
- 🏆 Achievements system — reading streaks and milestones
- 🌐 KOReader sync — multi-profile credential store with sendMetadata and syncBehavior
- 🔤 Lexend SD font support — moved from built-in to downloadable format
⚡ Performance & Stability
- 🧠 Constant RAM footprint — library uses ~11 KB fixed, freeing ~40 KB from the old vector-based approach
- 🗜️ External merge-sort — indices built in streaming K-way merge, never loaded entirely in memory
- 🚫 Conrupt EPUB protection — Guru Meditation crash eliminated, graceful failure on damaged files
- 💾 Fixed-record storage — 256-byte records with direct seek, no JSON parsing overhead
- 🖼️ XTC 4×4 cover fix — increased source row buffer to handle small-thumbnail scaling
Detailed Implementation
Library Index System
The library now uses a fixed-length binary record format stored at /.crosspoint/LIBRARY/library.dat. Each record is exactly 256 bytes containing book ID, title (64 bytes), author (48 bytes), path (128 bytes), file size, flags (tombstone/favourite/opened/completed), modification time, and reserved padding. This replaces the previous JSON-based approach that loaded all entries into RAM.
Three index files enable fast lookups: idx_title.bin (sorted by accent-folded lowercase title), idx_author.bin (sorted by author), and idx_collections.bin (unique series/collection names). Indices are built using external K-way merge-sort with configurable chunk size (default 16 records), processing up to 10,000 books with constant RAM.
Collections are built from series.dat which stores per-book series metadata (Calibre series name + index, or EPUB3 collection name). The series.dat is sorted during build and indexed by unique collection name.
Cover Generation
When a page is displayed, the library iterates over visible slots and generates missing cover thumbnails using the full EPUB/XTC parser (same pipeline as the Home screen). Each generated cover triggers a full e-ink refresh so covers appear progressively. The progress text "3/9 Loading..." appears centered below the book author. Generation is blocked during navigation to prevent input conflicts. TXT/MD files are skipped (no cover support).
Collections/Series Extraction
The EPUB fast-parser (EpubParser::readDirectFromZip) now extracts series metadata from the OPF file without loading the full EPUB parser. It searches for <meta name="calibre:series" content="..."/> and <meta name="calibre:series_index" content="..."/> (Calibre format) with a fallback to EPUB3 belongs-to-collection and group-position refines. Both systems coexist with Calibre taking priority.
Layout-Independent Bookmarks
Bookmarks use an absolute word index system (v4) where each bookmark stores absoluteWordStart — the cumulative word position from the chapter start. When the user changes font size, margins, or switches between simplified/integrated CSS modes, the section cache is rebuilt and buildCumulativeWordCounts() recalculates per-page word boundaries. The bookmark's absoluteWordStart is compared against pageStart + wordIndex to find and highlight the exact word in any layout.
Clippings (text highlights) use the same system (v2) with absoluteWordStart + wordCount representing a range of highlighted text. Both systems are stored in stable data directories via BookIdentity hashing to survive path changes.
Upstream CPR-vCodex Base
This release is built on CPR-vCodex 1.5.0.2 from franssjz/cpr-vcodex. The upstream provides: HalClock DS3231 RTC support, ClockSyncActivity with NTP, KOReader multi-profile sync with sendMetadata/syncBehavior, Unicode compose table, progressive EPUB indexing improvements, and various EPUB parser fixes. All Steroids customisations (library, collections, bookmarks, clippings, screensaver, browser settings, OTA branding) are preserved on top.