# 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