# Library Reading Demo

This directory contains scripts to demonstrate the complete LIBRARY ↔ READING workflow for the dreader e-reader application.

## Demo GIF

**File**: [`doc/images/library_reading_demo.gif`](../doc/images/library_reading_demo.gif) (591 KB, 800x1200 pixels)

### What the Demo Shows

The animated GIF demonstrates the complete user workflow:

1. **Library View** (2s)
   - Shows a grid of available books
   - Title: "📚 My Library - Select a book"

2. **Book Selection** (1.5s)
   - Visual tap indicator on the first book
   - Shows where user taps to select

3. **Reading Pages** (5 frames, ~5s total)
   - Opens "Alice's Adventures in Wonderland"
   - Shows 5 consecutive pages
   - Page turns are animated
   - Progress shown in header

4. **Settings Overlay** (2s)
   - Shows settings panel with font controls
   - Highlights "Back to Library" button
   - Visual tap indicator showing where to click

5. **Return to Library** (2s)
   - Book closes, position saved automatically
   - Library view shown again
   - Annotation: "Back to Library (position saved)"

6. **Reopen Book** (1.5s)
   - User taps same book again
   - Visual indicator shows reselection

7. **Auto-Resume** (3s)
   - Book opens at saved position (24.6% progress)
   - Shows the exact page where user left off
   - Annotation: "✅ Auto-resumed at 24.6%"

**Total Duration**: ~17 seconds (looping)

## Scripts

### `generate_library_demo_gif.py`

Generate the demo GIF showing the complete workflow.

**Usage**:
```bash
python generate_library_demo_gif.py path/to/library [output.gif]
```

**Examples**:
```bash
# Generate to default location (doc/images/library_reading_demo.gif)
python generate_library_demo_gif.py tests/data/library-epub/

# Generate to custom location
python generate_library_demo_gif.py tests/data/library-epub/ doc/images/custom_demo.gif
```

**Features**:
- Automatic book scanning and cover extraction
- Visual tap indicators showing user interactions
- Annotations explaining each step
- Configurable frame durations
- Auto-resume demonstration

### `library_reading_integration.py`

Comprehensive integration test for the library ↔ reading workflow.

**Usage**:
```bash
python library_reading_integration.py path/to/library
```

**What it Tests**:
1. Library scanning and rendering
2. Book selection via tap
3. Book loading and reading
4. Page navigation (swipe gestures)
5. Settings overlay
6. Settings adjustments (font size)
7. Back to library button
8. Auto-resume functionality
9. Multiple book selection

**Output**: Generates PNG images for each step (8 images total)

## Implementation Status

### ✅ Complete Features

- **Library Management** ([library.py](../dreader/library.py))
  - Book scanning and metadata extraction
  - Cover image caching
  - Interactive book selection
  - Clickable book rows

- **Reading Mode** ([application.py](../dreader/application.py))
  - EPUB rendering
  - Page navigation (swipe, tap)
  - Progress tracking
  - Position saving/loading

- **State Persistence** ([state.py](../dreader/state.py))
  - Auto-save on page turn
  - Resume at last position
  - Settings persistence
  - Per-book bookmarks

- **Overlays**
  - TOC (Table of Contents) - ✅ Working
  - Settings - ✅ Working
  - Bookmarks - ✅ Working

### 🚧 Known Issues

- **HTML Link Interactivity**: The "Back to Library" button in settings overlay doesn't respond to taps
  - Root cause documented in [HTML_LINKS_INVESTIGATION.md](../HTML_LINKS_INVESTIGATION.md)
  - Workaround: Will be implemented using programmatic UI generation
  - Does not affect the demo GIF (which shows the intended workflow)

## Requirements

- Python 3.8+
- PIL/Pillow (for image generation)
- dreader application
- pyWebLayout library
- Test EPUB files in the library directory

## File Sizes

- Demo GIF: ~622 KB (optimized for quality)
- Integration test PNGs: ~50-170 KB each
- Total demo assets: <2 MB

## Demo Generation Time

- Library scanning: <1 second
- EPUB loading: <1 second
- Page rendering: ~0.5 seconds per page
- Total: ~10-15 seconds to generate complete GIF

## Use Cases

1. **Documentation**: Visual demonstration of application features
2. **Testing**: Verify complete workflow end-to-end
3. **Presentations**: Show stakeholders the user experience
4. **Debugging**: Identify issues in the workflow
5. **Training**: Help users understand the application flow

## See Also

- [REQUIREMENTS.md](../REQUIREMENTS.md) - Full application requirements
- [HTML_GENERATION.md](../HTML_GENERATION.md) - HTML rendering documentation
- [HTML_LINKS_INVESTIGATION.md](../HTML_LINKS_INVESTIGATION.md) - Link interactivity debugging
