undo mis-commit

examples/LIBRARY_DEMO.md

@@ -0,0 +1,164 @@
+# 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