# Text & EPUB Reader Integration for Meck Firmware ## Overview This adds a text reader accessible via the **E** key from the home screen. **Features:** - Browse `.txt` and `.epub` files from `/books/` folder on SD card - Automatic EPUB-to-text conversion on first open (cached for instant re-opens) - Word-wrapped text rendering using tiny font (maximum text density) - Page navigation with W/S/A/D keys - Automatic reading position resume (persisted to SD card) - Index files cached to SD for instant re-opens - Bookmark indicator (`*`) on files with saved positions **Key Mapping (T-Deck Pro):** | Context | Key | Action | |---------|-----|--------| | Home screen | E | Open text reader | | File list | W/S | Navigate up/down | | File list | Tap / Enter | Open selected file | | File list | Q | Back to home screen | | Reading | W/A | Previous page | | Reading | S/D/Space | Next page | | Reading | Enter | Go to page number (type digits, Enter to confirm, Q to cancel) | | Reading | Q | Close book → file list | **Touch Gestures (T5S3):** | Context | Gesture | Action | |---------|---------|--------| | File list | Swipe up/down | Scroll file list | | File list | Tap | Open selected book | | Reading | Tap | Next page | | Reading | Swipe left/right | Next / previous page | | Reading | Tap footer | Go to page number (via virtual keyboard) | | Reading | Long press | Close book → file list | --- ## SD Card Setup Place `.txt` or `.epub` files in a `/books/` folder on the SD card root. The reader will: - Auto-create `/books/` if it doesn't exist - Auto-create `/.indexes/` for page index cache files - Auto-create `/books/.epub_cache/` for converted EPUB text - Skip macOS hidden files (`._*`, `.DS_Store`) - Support up to 50 files **Index format** is compatible with the standalone reader (version 4), so if you've used the standalone reader previously, bookmarks and indexes will carry over. --- ## EPUB Support ### How It Works EPUB files are transparently converted to plain text on first open. The conversion pipeline is: 1. **File list** — `scanFiles()` picks up both `.txt` and `.epub` files from `/books/` 2. **First open** — `openBook()` detects the `.epub` extension and triggers conversion: - Shows a "Converting EPUB..." splash screen - Extracts the ZIP structure using ESP32-S3's built-in ROM `tinfl` decompressor (no external library needed) - Parses `META-INF/container.xml` → finds the OPF file - Parses the OPF manifest and spine to get chapters in reading order - Extracts each XHTML chapter, strips tags, decodes HTML entities - Writes concatenated plain text to `/books/.epub_cache/.txt` 3. **Subsequent opens** — the cached `.txt` is found immediately and opened like any regular text file ### Cache Structure ``` /books/ MyBook.epub ← original EPUB (untouched) SomeStory.txt ← regular text file .epub_cache/ MyBook.txt ← auto-generated from MyBook.epub /.indexes/ MyBook.txt.idx ← page index for the converted text ``` - The original `.epub` file is never modified - Deleting a cached `.txt` from `.epub_cache/` forces re-conversion on next open - Index files (`.idx`) work identically for both regular and EPUB-derived text files - Boot scan picks up previously cached EPUB text files so they appear in the file list even before the EPUB is re-opened ### EPUB Processing Details The conversion is handled by three components: | Component | Role | |-----------|------| | `EpubZipReader.h` | ZIP central directory parsing + `tinfl` decompression (supports Store and Deflate) | | `EpubProcessor.h` | EPUB structure parsing (container.xml → OPF → spine) and XHTML tag stripping | | `TextReaderScreen.h` | Integration: detects `.epub`, triggers conversion, redirects to cached `.txt` | **XHTML stripping handles:** - Tag removal with block-element newlines (`

`, `
`, `

`, `

`–`

`, `
`, etc.) - ``, `