chore: tidy repository layout and consolidate hardware docs

Root had grown to 30 entries, most of it generated output and one-off scripts. It now holds 12. Docs: - Merge HARDWARE_SETUP, HARDWARE_PINOUT, GPIO_BUTTONS and ACCELEROMETER_PAGE_FLIP into a single docs/HARDWARE.md - Move ARCHITECTURE, REQUIREMENTS and HAL_IMPLEMENTATION_SPEC to docs/, leaving only README.md in the root - Update cross-references in README, setup_rpi.py and install_hardware_drivers.sh, and re-base ARCHITECTURE's source links Merging surfaced three errors, reconciled against hardware_config.json: - The power button was documented as GPIO 21 to GND with a pull-up. It is active high (pull_up: false); wiring it as documented reads as permanently pressed. - GPIO_BUTTONS used GPIO 23 for next-page; it is GPIO 27. - The FT5316 INT pin was routed to GPIO 27, which collides with the next-page button. Now documented as a conflict. Scripts: - Move debug_overlay_links.py and debug_previous_page.py to scripts/debug/ - Rename test_pagination_visual.py to scripts/debug/visualize_pagination.py; it renders output and asserts nothing, so the test_ prefix was misleading - Fix the __file__-relative paths these three relied on - Track update_pyweblayout.sh under scripts/ Tests: - Reword the backward-navigation tests, which described a pyWebLayout bug that is now fixed, as regression tests Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-08 22:27:53 +02:00
parent c62b8eff38
commit f7d59d025f
17 changed files with 942 additions and 1450 deletions
@@ -0,0 +1,196 @@
+# E-Reader Application Requirements
+
+## Overview
+This document defines the core requirements for a full-featured e-reader application built on dreader/pyWebLayout. The application supports library browsing, reading with overlays, state persistence, and gesture-based interaction.
+
+## Application Modes
+
+### LIBRARY Mode
+Browse and select books from the user's library.
+
+**Features**:
+- Grid display of books with covers and metadata (title, author)
+- Book selection via tap/click
+- Visual feedback on selection
+
+**Interactions**:
+- **Tap book**: Open in READING mode
+- **Swipe**: Scroll library (future)
+
+### READING Mode
+Read the current book with page navigation.
+
+**Features**:
+- Page rendering via pyWebLayout
+- Page navigation (next/previous)
+- Access to overlays
+- Progress indicator
+
+**Interactions**:
+- **Tap edges**: Previous/Next page
+- **Swipe left/right**: Page navigation
+- **Swipe up (from bottom)**: Open navigation overlay
+- **Swipe down (from top)**: Open settings overlay
+- **Pinch in/out**: Adjust font size
+- **Long-press on word**: Highlight/lookup (future)
+
+## Overlay System
+
+### Navigation Overlay
+Unified overlay with tabbed interface for navigation.
+
+**Tabs**:
+- **Contents**: Chapter list for TOC navigation
+- **Bookmarks**: Saved positions with jump/delete/add
+
+**Interactions**:
+- **Tap chapter/bookmark**: Jump to location, close overlay
+- **Tap tab**: Switch between Contents and Bookmarks
+- **Swipe down**: Close overlay
+
+### Settings Overlay
+Adjust reading preferences with real-time preview.
+
+**Controls**:
+- Font size (A-, A+)
+- Line spacing (+/-)
+- Block spacing (+/-)
+- Word spacing (+/-)
+- Back to Library button
+
+**Interactions**:
+- **Tap buttons**: Adjust settings immediately
+- **Swipe down**: Close overlay
+
+### Word Lookup Overlay (Planned - Phase 2)
+Provide word definitions and contextual information.
+
+**Features**:
+- **Dictionary**: Word definition, pronunciation
+- **X-Ray**: LLM-generated spoiler-free character/place/concept information up to current reading position
+- **Highlight**: Add colored highlight
+- **Copy**: Copy to clipboard
+
+**X-Ray Behavior**:
+- Pre-generated per book via offline LLM analysis
+- Only shows information revealed up to current page (spoiler-free)
+- Character relationships, place descriptions, concept explanations
+- Entity occurrence tracking
+
+## State Management
+
+### Persistent State Structure
+```json
+{
+  "mode": "reading|library",
+  "overlay": "none|navigation|settings|word_lookup",
+  "current_book": {
+    "path": "/path/to/book.epub",
+    "title": "Book Title",
+    "author": "Author Name"
+  },
+  "library": {
+    "books_path": "/path/to/library",
+    "scan_cache": [...]
+  },
+  "settings": {
+    "font_scale": 1.0,
+    "line_spacing": 5,
+    "inter_block_spacing": 15,
+    "brightness": 8
+  }
+}
+```
+
+**State Location**: `~/.config/dreader/state.json`
+
+**Save Triggers**:
+- Every 60 seconds (auto-save)
+- On mode change
+- On settings change
+- On application shutdown
+
+**Boot Behavior**:
+- **Cold start**: Show library
+- **Resume**: Reopen last book at saved position with restored settings
+- **Error handling**: Fall back to library if book missing or state corrupt
+
+### Position Persistence
+- Per-book positions stored via EbookReader bookmark system
+- Special bookmark `__auto_resume__` for last reading position
+- Position stable across font size and spacing changes
+
+## Library Management
+
+**Features**:
+- Scan directory for EPUB files
+- Extract metadata (title, author) and cover images
+- Cache covers to disk for performance
+- Incremental updates (scan only new/modified files)
+
+**Cache Structure**:
+```
+~/.config/dreader/
+├── state.json              # Application state
+├── covers/                 # Cached cover images
+├── bookmarks/              # Per-book bookmarks
+├── highlights/             # Per-book highlights
+└── xray/                   # X-Ray data (future)
+```
+
+## Gesture Handling
+
+### Reading Mode Gestures
+- `TAP`: Word selection, link following, page turn (edges)
+- `SWIPE_LEFT/RIGHT`: Page navigation
+- `SWIPE_UP` (from bottom 20%): Open navigation overlay
+- `SWIPE_DOWN` (from top 20%): Open settings overlay
+- `PINCH_IN/OUT`: Font size adjustment
+- `LONG_PRESS`: Word lookup (future)
+
+### Overlay Mode Gestures
+- `TAP`: Interact with overlay elements
+- `SWIPE_DOWN`: Close overlay
+
+### Library Mode Gestures
+- `TAP`: Select book
+
+## Technical Requirements
+
+### Performance Targets
+- Boot time: < 3 seconds
+- Page turn: < 200ms
+- Library load: < 1 second (up to 100 books)
+- State save: < 50ms (non-blocking)
+
+### Platform Integration
+Application requires a display HAL (Hardware Abstraction Layer):
+```python
+class DisplayHAL(ABC):
+    def show_image(image: Image.Image)
+    def get_touch_events() -> Iterator[TouchEvent]
+    def set_brightness(level: int)
+```
+
+## Implementation Phases
+
+### Phase 1 (MVP) - Complete ✅
+- Core reading (page navigation, bookmarks)
+- Library browsing and book selection
+- Navigation overlay (TOC + Bookmarks)
+- Settings overlay with persistence
+- State management and auto-resume
+- Gesture handling
+- Highlighting system
+
+### Phase 2 - In Progress
+- Word lookup overlay with dictionary
+- X-Ray feature (spoiler-free contextual info)
+- Enhanced library features (search, sort)
+
+### Phase 3 - Future
+- Night/sepia themes
+- Full-text search within books
+- Cloud sync for bookmarks
+- PDF support
+- Reading statistics