1.5.0.2-dev1-cpr-vcodex-steroids

📚 Library Overhaul

• 🔄 Complete library rewrite — new fixed-record .dat index 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_index from EPUB metadata (fast ZIP-based parser)
• 📚 EPUB3 belongs-to-collection fallback 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.

---