crosspoint-reader/docs/crosspoint-ef-features.md

CrossPoint-EF Branch Features

This document describes the features and enhancements unique to the crosspoint-ef branch, which diverged from CrossPoint Reader at version 0.15.0.

Overview

The crosspoint-ef branch introduces significant new functionality including:

• Dictionary Support - Offline StarDict dictionary with word selection from reader
• Bookmark System - Per-book bookmarks with visual indicators and management
• Quick Menu - Fast access to common actions via power button
• Library Search - Search across all books by title, author, or filename
• CSS Support - Parse and apply CSS styles from EPUB files
• Inline Images - PNG and Baseline JPEG image rendering within EPUBs
• Custom Fonts - Atkinson Hyperlegible Next and Fern Micro accessibility fonts
• Enhanced Web Server - File management, companion app API, mDNS discovery
• Reading Lists - Create, manage, and pin custom book lists
• Display Enhancements - High contrast mode, bezel compensation, sleep screen improvements

---

Major Features

1. Dictionary Support

Full offline dictionary lookup using the StarDict format with fast prefix-indexed search.

Features:

• Word selection directly from EPUB pages
• Manual word entry via on-screen keyboard
• Rich HTML formatting in definitions (bold, italic, lists)
• Multi-page definitions with pagination
• Synonym support
• Case-insensitive search with prefix optimization

Access Methods:

• Quick Menu → Dictionary
• Power Button (when configured to Dictionary action)

Dictionary Format:

• StarDict format with dictzip compression
• Files located at /dictionaries/dict-data on SD card:
  • dict-data.ifo - Metadata
  • dict-data.idx - Word index
  • dict-data.dict.dz - Compressed definitions
  • dict-data.syn - Synonyms (optional)

Technical Implementation:

• Files: src/activities/dictionary/, lib/StarDict/
• Prefix jump table for near-instant lookups
• On-demand chunk decompression using miniz
• HTML definition parsing with entity decoding

---

2. Bookmark System

Per-book bookmark storage with visual indicators and dedicated management interface.

Features:

• Add/remove bookmarks from current page
• Visual folded-corner indicator on bookmarked pages
• Bookmarks tab in library showing all books with bookmarks
• Long-press to delete bookmarks
• Auto-generated bookmark names ("Chapter Title - Page X")
• Maximum 100 bookmarks per book

Storage:

• Binary file per book: /.crosspoint/{epub_|txt_}<hash>/bookmarks.bin
• Stores: name, spine index, content offset, page number, timestamp

Technical Implementation:

• Files: src/BookmarkStore.cpp/.h, src/activities/home/BookmarkListActivity.cpp/.h
• Bookmark identification by spineIndex + contentOffset (stable across re-renders)

---

3. Quick Menu

In-reader quick access menu for common actions, triggered by short power button press.

Menu Options:

1. Dictionary - Look up a word
2. Bookmark - Add/Remove bookmark (state-aware text)
3. Clear Cache - Free up storage space
4. Settings - Open settings menu

Configuration:

• Settings → Controls → Short Power Button Click → Quick Menu

Technical Implementation:

• File: src/activities/util/QuickMenuActivity.cpp/.h
• Renders overlay with navigation and selection

---

4. Library Search with Character Picker

Search across all books using a dynamic character picker interface.

Features:

• Character picker with dynamically generated character set from library content
• Weighted search scoring:
  • Title match: 100 points (+50 if at start)
  • Author match: 80 points (+40 if at start)
  • Path match: 30 points
• Results sorted by relevance score
• Special controls: SPC (space), ← (backspace), CLR (clear)

Navigation:

• Left/Right: Select character
• Confirm: Add character to query
• Up/Down: Switch between picker and results

Technical Implementation:

• Integrated in src/activities/home/MyLibraryActivity.cpp
• Search tab accessible from library tab bar

---

5. CSS Support for EPUBs

Parse and apply CSS styles from EPUB stylesheets.

Supported Selectors:

• Element selectors: p, div, h1, etc.
• Class selectors: .classname
• Combined selectors: element.classname
• Grouped selectors: h1, h2, h3
• Inline styles: style="..."

Supported Properties:

• text-align (left, center, right, justify)
• font-style (normal, italic)
• font-weight (normal, bold)
• text-decoration (underline)
• text-indent
• margin-top, margin-bottom
• padding-top, padding-bottom

Cascade Order:

1. Element styles
2. Class styles
3. Element.class styles
4. Inline styles

Technical Implementation:

• Files: lib/Epub/Epub/css/CssParser.cpp/.h, CssStyle.h
• CSS files parsed during EPUB loading
• Styles applied during HTML parsing via ChapterHtmlSlimParser

---

6. Inline Image Support (PNG/Baseline JPEG)

Render embedded images within EPUB content.

Supported Formats:

• Baseline JPEG (.jpg, .jpeg)
• PNG (.png)

Features:

• Images decoded to 2-bit grayscale with dithering
• Image caching as .pxc files (2 bits per pixel, packed format)
• Row-by-row rendering to minimize memory usage
• Automatic scaling to fit page width

Technical Implementation:

• Files: lib/Epub/Epub/blocks/ImageBlock.cpp/.h
• Converters: JpegToFramebufferConverter, PngToFramebufferConverter
• Factory: ImageDecoderFactory routes to appropriate decoder

---

7. Custom Fonts

Additional accessibility-focused fonts beyond the standard Bookerly and Noto Sans.

Available Fonts:

1. Atkinson Hyperlegible Next - Designed for low-vision readers
2. Fern Micro - Optimized for small screens

Font Sizes:

• 12pt, 14pt, 16pt, 18pt for each font
• Full style support: Regular, Italic, Bold, Bold Italic

Configuration:

• Settings → Reader → Font Family → Custom
• Settings → Reader → Custom Font → [Select font]
• Settings → Reader → Fallback Font → [Bookerly/Noto Sans]

Technical Implementation:

• Files: src/customFonts.cpp, src/fontIds.h
• Font headers: lib/EpdFont/builtinFonts/custom/
• Conversion scripts: lib/EpdFont/scripts/convert-builtin-fonts.sh

---

8. Enhanced Web Server

Extended web server with file management operations and companion app support.

File Operations:

Endpoint	Method	Description
/api/files	GET	List files with MD5 hashes for EPUBs
/api/status	GET	Device status (version, IP, heap, uptime)
/api/archived	GET	List archived books
/api/hash	GET	Compute/retrieve MD5 hash for sync
/download	GET	Download files
/upload	POST	Upload files (multipart)
/delete	POST	Delete files/folders
/archive	POST	Archive a book
/unarchive	POST	Restore archived book
/rename	POST	Rename files/folders
/copy	POST	Copy files/folders
/move	POST	Move files/folders
/mkdir	POST	Create folders
/list	GET/POST	Manage reading lists

WebSocket Upload (Port 81):

• Fast binary uploads for large files
• Protocol: START:<filename>:<size>:<path> → READY → binary chunks → DONE
• Progress updates: PROGRESS:<received>:<total>

mDNS Discovery:

• Hostname: crosspoint.local
• Service: _http._tcp on port 80
• UDP discovery on port 8134

Deep Link Support:

• URL scheme: crosspoint://<path>?host=<ip>&port=<port>&wsPort=<wsPort>
• Paths: files, library, lists, settings

Technical Implementation:

• Files: src/network/CrossPointWebServer.cpp/.h
• MD5 Utils: src/util/Md5Utils.cpp/.h
• Docs: docs/webserver-api-reference.md, docs/companion-app-deep-link-API.md

---

9. Reading Lists with Pinning

Create and manage custom book lists with pinning support.

Features:

• Create, load, delete lists
• Pin a list to show on home screen
• List contents displayed with book metadata
• Web API for list upload/download (CSV format)

Storage:

• Lists stored in /.lists/ as .bin files
• CSV format for API: order,title,author,path

Configuration:

• Library → Lists tab → Long-press → Pin/Unpin
• Pinned list name shown on home screen Lists button

Technical Implementation:

• Files: src/BookListStore.cpp/.h
• Pinned list stored in SETTINGS.pinnedListName

---

10. Display Enhancements

High Contrast Mode

System-wide display contrast adjustment for improved readability.

• Normal mode: Standard grayscale thresholds
• High contrast mode: Pushes mid-grays toward black/white

Configuration:

• Settings → Display → High Contrast → On/Off

Bezel Compensation

Compensate for physical screen edge defects with configurable margin.

• Range: 0-10 pixels
• Edges: Bottom, Top, Left, Right
• Behavior: Margin rotates with screen orientation

Configuration:

• Settings → Display → Bezel Compensation → [0-10]
• Settings → Display → Bezel Edge → [Bottom/Top/Left/Right]

Sleep Screen Improvements

Enhanced sleep screen with edge-aware color filling.

• Edge luminance detection: Samples edge pixels for dominant color
• Letterbox fill: Fills letterbox regions with edge colors for seamless appearance
• Two-level caching:
  • Per-BMP cache: .bmp.perim files store edge luminance
  • Book-level cache: edge.bin stores cover data

---

11. Recents View Improvements

Enhanced recent books display with metadata and management.

Features:

• Badges: Extension and suffix tags (e.g., "epub", "X4")
• Metadata display: Title and author from EPUB
• Remove from recents: Long-press → Remove from Recents
• Clear all: Long-press → Clear All Recents

Badge Configuration:

• Extension badges: .epub → "epub", .txt → "txt"
• Suffix badges: -x4 → "X4", -x4p → "X4P"

Technical Implementation:

• Files: src/RecentBooksStore.cpp/.h
• Badge config: src/BadgeConfig.h
• String utils: src/util/StringUtils.cpp/.h

---

12. Enhanced Tab Bar

Unified tab bar with scrolling and overflow indicators.

Features:

• Horizontal scrolling when tabs exceed available width
• Overflow indicators (< >) when content extends beyond view
• Selected tab highlighting with underline
• Bullet cursors for focus mode

Tabs:

• Recent, Lists, Bookmarks, Search, Files

Technical Implementation:

• Files: src/ScreenComponents.cpp/.h
• Used in MyLibraryActivity for library navigation

---

13. Progress Bar Status Bar

Additional status bar option showing visual progress bar.

Options:

• Full w/ Progress Bar - Full status bar with progress bar
• Progress Bar - Only progress bar, no other status info

Configuration:

• Settings → Display → Status Bar

---

14. Additional Settings

New configuration options unique to crosspoint-ef:

Setting	Options	Description
Short Power Button Click	Ignore, Sleep, Page Turn, Dictionary, Quick Menu	Map power button to action
Bezel Compensation	0-10 pixels	Edge defect compensation
Bezel Edge	Bottom, Top, Left, Right	Which edge to compensate
High Contrast	Off, On	System-wide contrast boost
Custom Font	[Font list]	Select custom font
Fallback Font	Bookerly, Noto Sans	Fallback for custom fonts

---

15. OPDS Browser Enhancements

Improved OPDS catalog browsing experience.

Features:

• Navigation history stack - Back button navigates through visited feeds
• Page skipping - Hold Up/Down for 700ms to skip 23 items at once
• Error retry mechanism - Retry button on error screens with WiFi status check
• HTTP Basic Authentication - Username/password support for protected OPDS servers

Configuration:

• Settings → System → Calibre Settings → OPDS Server URL
• Settings → System → Calibre Settings → Username/Password

Technical Implementation:

• Files: src/activities/browser/OpdsBookBrowserActivity.cpp
• Authentication: src/network/HttpDownloader.cpp

---

16. Development Tools

Scripts and utilities for firmware development.

Scripts:

Script	Purpose
pre_flash.py	Displays "Flashing firmware..." screen during upload
debugging_monitor.py	Enhanced serial monitor with memory graphs and color output
pio_helper.py	Interactive PlatformIO workflow helper with presets
version_hash.py	Embeds git commit hash in dev builds
build_html.py	Minifies HTML files for web server

Firmware Flashing Screen:

• Full-screen display during firmware upload
• Shows "Flashing firmware..." with version info
• Lock icon indicates USB port location
• Prevents accidental disconnection

Debug/Memory Monitoring:

• DEBUG_MEMORY build mode for heap tracking at activity transitions
• Periodic memory logging every 10 seconds (when Serial connected)
• Loop duration warnings when exceeding 50ms
• Detailed heap fragmentation info

Technical Implementation:

• Scripts: scripts/pre_flash.py, scripts/debugging_monitor.py, scripts/pio_helper.py
• Flash screen: src/main.cpp (lines 138-247)
• Memory monitoring: src/main.cpp (lines 549-562)
• Build config: platformio.ini (debug_memory environment)

---

17. Power Management Enhancements

Optimizations for battery life and responsiveness.

Features:

• Auto-sleep prevention - Background tasks (web server, OTA, downloads) prevent auto-sleep
• USB connection detection - Serial only starts when USB is connected (saves power)
• Skip loop delay - Activities can request faster loop execution for responsive HTTP handling
• Power button release wait - Prevents immediate wake if button is still held

Technical Implementation:

• Files: src/main.cpp, src/activities/Activity.h
• Methods: preventAutoSleep(), skipLoopDelay()

---

Bug Fixes

Unique to crosspoint-ef

1. Grayscale state corruption fix - Prevents ghosting and gray filter artifacts when anti-aliasing is enabled under memory pressure
2. Memory optimization - Graceful degradation when memory is low (skip anti-aliasing instead of corrupting display)

Shared with 0.16.0

• Large EPUB indexing optimization (O(n²) → O(n))
• Settings validation on read
• Line break fixes (flush word before <br/>)
• Rotate origin in drawImage()
• Short-press power button to wakeup
• Add txt books to recent tab
• B&W filters for cover images

---

Missing or Removed Features from 0.16.0

The following features are present in the upstream 0.16.0 release but are missing or were removed in crosspoint-ef:

Removed Features

1. KOReader Sync Support (Removed)

The entire KOReader sync functionality has been removed.

What was removed:

• lib/KOReaderSync/ library (8 files deleted)
• Progress sync with KOReader sync server (sync.koreader.rocks)
• Document MD5 binary matching for progress synchronization
• KOReader credential storage

Impact:

• Cannot sync reading progress with KOReader app
• Chapter Selection UI fixes for KOReader sync (#501) not applicable

Files deleted:

• KOReaderSyncClient.cpp/.h
• KOReaderCredentialStore.cpp/.h
• KOReaderDocumentId.cpp/.h
• ProgressMapper.cpp/.h

---

2. Non-English Hyphenation Patterns (Removed)

Hyphenation pattern files for non-English languages have been removed.

What was removed:

• hyph-es.trie.h - Spanish hyphenation
• hyph-de.trie.h - German hyphenation
• hyph-fr.trie.h - French hyphenation
• hyph-ru.trie.h - Russian hyphenation

Impact:

• Only English hyphenation patterns remain
• Non-English books will not hyphenate correctly
• Spanish hyphenation support (#558) not available

Note: These can be restored by copying the trie files from 0.16.0.

---

3. XTC/XTCH File Support (Removed)

Support for the XTC/XTCH proprietary format has been removed.

What was removed:

• Author extraction from XTC/XTCH files (#563)
• XTC format handling in file browsers

Impact:

• XTC/XTCH files cannot be read
• Author metadata not extracted from these formats

---

Missing Bug Fixes

The following bug fixes from 0.16.0 have not been applied to crosspoint-ef:

PR	Description	Impact
#567	Multi-line keyboard entry	Long text input truncated with "..." instead of wrapping
#569	Italics on image alt text	Image alt placeholders don't render in italics
#564	Front layout in mapLabels()	Button mapping may be incorrect in some layouts
#486	Relative position on settings change	Reader may jump to different location when settings change
#501	Chapter Selection UI (KOReader)	N/A - KOReader sync removed
#529	KOReader MD5 binary matching	N/A - KOReader sync removed

---

Missing UX Enhancements

PR	Description	Impact
#451	Page turn on button press	When long-press chapter skip is disabled, 0.16.0 allows page turn on button press; crosspoint-ef does not

---

Different Implementation: OTA Updates

The OTA update mechanism uses a different implementation:

Aspect	crosspoint-ef	0.16.0
HTTP Client	Arduino HTTPClient	ESP-IDF esp_http_client
OTA Library	Arduino Update	ESP-IDF esp_https_ota
Memory Management	Standard	Improved with custom buffer handling

Impact:

• Both implementations work, but 0.16.0's ESP-IDF approach may be more memory-efficient
• Consider evaluating 0.16.0's OTA rework (#509) for potential adoption

---

Recommendation for Missing Features

High Priority to Cherry-pick:

1. Multi-line keyboard entry (#567) - Improves UX for long inputs
2. Front layout fix (#564) - Bug fix for button mapping
3. Relative position on settings change (#486) - Improves reader UX

Medium Priority: 4. Restore hyphenation patterns for non-English languages 5. Italics on image alt (#569) - Minor visual improvement 6. Page turn on button press (#451) - UX enhancement

Evaluate: 7. OTA rework (#509) - Compare implementations for memory benefits 8. KOReader sync - Restore if sync functionality is desired

---

File Summary

Feature	Primary Files
Dictionary	src/activities/dictionary/, lib/StarDict/
Bookmarks	src/BookmarkStore.*, src/activities/home/BookmarkListActivity.*
Quick Menu	src/activities/util/QuickMenuActivity.*
Search	src/activities/home/MyLibraryActivity.cpp
CSS	lib/Epub/Epub/css/
Images	lib/Epub/Epub/blocks/ImageBlock.*, lib/Epub/Epub/converters/
Custom Fonts	src/customFonts.cpp, lib/EpdFont/builtinFonts/custom/
Web Server	src/network/CrossPointWebServer.*, src/util/Md5Utils.*
Lists	src/BookListStore.*
Settings	src/CrossPointSettings.*
Tab Bar	src/ScreenComponents.*
Recents	src/RecentBooksStore.*, src/BadgeConfig.h
OPDS Browser	src/activities/browser/OpdsBookBrowserActivity.*
Dev Tools	scripts/pre_flash.py, scripts/debugging_monitor.py, scripts/pio_helper.py
Power Management	src/main.cpp, src/activities/Activity.h

---

Version Information

• Base version: 0.15.0
• Branch: crosspoint-ef
• Commits since divergence: 90+
• Files changed: 250+