197 lines
5.3 KiB
Markdown
197 lines
5.3 KiB
Markdown
# 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
|