dreader-application/REQUIREMENTS.md

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

{
  "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):

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