dreader-application/README.md

# DReader Application

## Project Status

| Badge | Description |
|-------|-------------|
| ![Test Coverage](https://gitea.tourolle.paris/dtourolle/dreader-application/raw/branch/badges/cov_info/coverage.svg) | **Test Coverage** - Percentage of code covered by unit tests |
| ![Documentation Coverage](https://gitea.tourolle.paris/dtourolle/dreader-application/raw/branch/badges/cov_info/coverage-docs.svg) | **Documentation Coverage** - Percentage of code with docstrings |
| ![License](https://img.shields.io/badge/license-MIT-blue.svg) | **License** - Project licensing information |

> 📋 **Note**: Badges show results from the commit referenced in the URLs. Red "error" badges indicate build failures for that specific step.

## Description

DReader Application is a complete, production-ready ebook reader built on [pyWebLayout](https://gitea.tourolle.paris/dtourolle/pyWebLayout). It demonstrates how to build a full-featured ebook reader with text highlighting, bookmarks, gesture support, and position persistence.

This project serves as both a reference implementation and a ready-to-use ereader library for building desktop, web-based, or embedded reading applications.

## Key Features

### Core Reading Features
- 📖 **EPUB Support** - Load and render EPUB files with full text extraction
- 📄 **Page Rendering** - Render pages as PIL Images optimized for any display
- ⬅️➡️ **Navigation** - Smooth forward and backward page navigation
- 🔖 **Bookmarks** - Save and restore reading positions with persistence
- 📑 **Chapter Navigation** - Jump to chapters by title or index via TOC
- 📋 **TOC Overlay** - Interactive table of contents overlay with gesture support
- 📊 **Progress Tracking** - Real-time reading progress percentage

### Text Interaction
- 🎨 **Text Highlighting** - Highlight words and text selections with custom colors
- 💡 **Highlight Notes** - Attach notes and annotations to highlights
- 🔍 **Text Selection** - Select words or ranges via pixel coordinates
- 👆 **Gesture Support** - Handle tap, swipe, pinch, long-press events
- 🎯 **Pixel Queries** - Query text content at any screen position

### Customization & Display
- 🔤 **Font Control** - Dynamically adjust font size with live preview
- 📏 **Spacing Control** - Customize line and paragraph spacing
- 💾 **Position Persistence** - Stable positions across style changes
- ⚡ **Smart Reflow** - Automatic text reflow on font/spacing changes
- 🎨 **Custom Styling** - Full control over colors, fonts, and layout

## Installation

```bash
# Clone the repository
git clone https://gitea.tourolle.paris/dtourolle/dreader-application.git
cd dreader-application

# Install in development mode
pip install -e .

# Or install with dev dependencies
pip install -e ".[dev]"
```

The pyWebLayout dependency will be automatically installed from the git repository.

## DReader in Action

Here are animated demonstrations of the key features:

<table>
  <tr>
    <td align="center">
      <b>Page Navigation</b><br>
      <img src="docs/images/ereader_page_navigation.gif" width="300" alt="Page Navigation"><br>
      <em>Forward and backward navigation through pages</em>
    </td>
    <td align="center">
      <b>Font Size Adjustment</b><br>
      <img src="docs/images/ereader_font_size.gif" width="300" alt="Font Size"><br>
      <em>Dynamic font size scaling with position preservation</em>
    </td>
  </tr>
  <tr>
    <td align="center">
      <b>Chapter Navigation</b><br>
      <img src="docs/images/ereader_chapter_navigation.gif" width="300" alt="Chapter Navigation"><br>
      <em>Jump directly to chapters by title or index</em>
    </td>
    <td align="center">
      <b>Bookmarks & Positions</b><br>
      <img src="docs/images/ereader_bookmarks.gif" width="300" alt="Bookmarks"><br>
      <em>Save and restore reading positions anywhere in the book</em>
    </td>
  </tr>
  <tr>
    <td align="center">
      <b>Text Highlighting</b><br>
      <img src="docs/images/ereader_highlighting.gif" width="300" alt="Highlighting"><br>
      <em>Highlight words and selections with custom colors and notes</em>
    </td>
    <td align="center">
      <b>TOC Overlay</b><br>
      <img src="docs/images/toc_overlay_demo.gif" width="300" alt="TOC Overlay"><br>
      <em>Interactive table of contents with gesture-based navigation</em>
    </td>
  </tr>
</table>

## Quick Start

```python
from dreader.application import EbookReader

# Create an ebook reader
with EbookReader(page_size=(800, 1000)) as reader:
    # Load an EPUB file
    reader.load_epub("mybook.epub")

    # Get current page as PIL Image
    page = reader.get_current_page()
    page.save("page_001.png")

    # Navigate through pages
    reader.next_page()
    reader.previous_page()

    # Save reading position
    reader.save_position("chapter_3")

    # Jump to a chapter
    reader.jump_to_chapter("Chapter 5")

    # Adjust font size
    reader.increase_font_size()

    # Highlight text at coordinates
    highlight_id = reader.highlight_word(x=200, y=300, note="Important!")

    # Get progress
    progress = reader.get_reading_progress()
    print(f"Progress: {progress*100:.1f}%")
```

## API Overview

### Loading Content

```python
reader.load_epub("book.epub")
reader.is_loaded()  # Check if book loaded
reader.get_book_info()  # Get metadata (title, author, etc.)
```

### Navigation

```python
reader.next_page()
reader.previous_page()
reader.jump_to_chapter("Chapter 1")  # By title
reader.jump_to_chapter(0)  # By index
reader.get_chapters()  # List all chapters
reader.get_current_chapter_info()
reader.get_reading_progress()  # Returns 0.0 to 1.0

# TOC Overlay
overlay_image = reader.open_toc_overlay()  # Returns composited image with TOC
reader.close_overlay()
reader.is_overlay_open()
```

### Styling & Display

```python
reader.increase_font_size()
reader.decrease_font_size()
reader.set_font_size(1.5)  # 150% scale
reader.get_font_size()

reader.set_line_spacing(8)
reader.set_inter_block_spacing(20)
```

### Bookmarks & Position Management

```python
reader.save_position("my_bookmark")
reader.load_position("my_bookmark")
reader.list_saved_positions()
reader.delete_position("my_bookmark")
```

### Text Highlighting

```python
from pyWebLayout.core.highlight import HighlightColor

# Highlight a word at pixel coordinates
highlight_id = reader.highlight_word(
    x=100,
    y=200,
    color=HighlightColor.YELLOW,
    note="Important concept!"
)

# Highlight a text selection
highlight_id = reader.highlight_selection(
    start=(100, 200),
    end=(300, 250),
    color=(255, 255, 0, 128)  # RGBA
)

# Query word at position
result = reader.query_pixel(x=200, y=300)
if result:
    print(f"Word: {result.word.text}")

# Manage highlights
highlights = reader.list_highlights()
reader.remove_highlight(highlight_id)
reader.clear_highlights()
reader.get_highlights_for_current_page()
```

### Gesture Handling

```python
from dreader.gesture import TouchEvent, GestureType, ActionType

# Handle touch input
event = TouchEvent(GestureType.TAP, x=400, y=300)
response = reader.handle_touch(event)

# Response contains action type and data
if response.action == ActionType.PAGE_TURN:
    print(f"Page turned: {response.data['direction']}")
elif response.action == ActionType.WORD_SELECTED:
    print(f"Word selected: {response.data['word']}")
elif response.action == ActionType.CHAPTER_SELECTED:
    print(f"Chapter selected: {response.data['chapter_title']}")

# Supported gestures:
# - TAP: Select words, activate links, navigate TOC
# - LONG_PRESS: Show definitions or context menu
# - SWIPE_LEFT/RIGHT: Page navigation
# - SWIPE_UP: Open TOC overlay (from bottom 20% of screen)
# - SWIPE_DOWN: Close overlay
# - PINCH_IN/OUT: Font size adjustment
# - DRAG: Text selection
```

### File Operations

```python
# Save current page to file
reader.render_to_file("current_page.png")

# Context manager (auto-saves position on close)
with EbookReader(page_size=(800, 1000)) as reader:
    reader.load_epub("book.epub")
    # ... use reader ...
# Position automatically saved on exit
```

## Examples

Check out the `examples/` directory for complete working examples:

- **[simple_ereader_example.py](examples/simple_ereader_example.py)** - Basic ereader usage with EPUB loading and navigation
- **[ereader_demo.py](examples/ereader_demo.py)** - Comprehensive demo showcasing all features
- **[word_selection_highlighting.py](examples/word_selection_highlighting.py)** - Text selection and highlighting
- **[simple_word_highlight.py](examples/simple_word_highlight.py)** - Minimal highlighting example
- **[generate_ereader_gifs.py](examples/generate_ereader_gifs.py)** - Generate animated GIF demonstrations

## Architecture

DReader Application is a **high-level application layer** that combines pyWebLayout's low-level components:

```
dreader.application.EbookReader (High-Level API)
    ↓
├── pyWebLayout.layout.EreaderLayoutManager  # Layout engine & pagination
├── pyWebLayout.layout.EreaderLayout         # Bidirectional layout
├── pyWebLayout.core.HighlightManager        # Highlighting system
├── pyWebLayout.io.gesture                   # Touch/gesture handling
└── pyWebLayout.io.readers.epub_reader       # EPUB parsing
```

### Relationship to pyWebLayout

**pyWebLayout** is a layout engine library providing low-level primitives:
- Text rendering and layout algorithms
- Document structure and pagination
- Query systems for interactive content
- Core rendering infrastructure

**DReader Application** is an application framework that:
- Combines pyWebLayout components into a complete reader
- Provides user-friendly APIs for common ereader tasks
- Manages application state (bookmarks, highlights, positions)
- Handles business logic for gestures and interactions

Think of it like this:
- **pyWebLayout** = React (library)
- **DReader Application** = Next.js (framework)

## Use Cases

- 📱 **Desktop Ereader Applications** - Build native ereader apps with Python
- 🌐 **Web-based Readers** - Serve rendered pages via Flask/FastAPI
- 📟 **E-ink Device Firmware** - Optimized rendering for e-ink displays
- 📊 **Reading Analytics** - Track reading patterns, highlights, and engagement
- 🎓 **Educational Tools** - Create annotated reading experiences with highlights and notes
- 🔬 **Research Applications** - Build specialized reading tools for academic work

## Development

```bash
# Install in development mode with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run tests with coverage
pytest --cov=dreader --cov-report=html

# Format code
black dreader/ tests/

# Type checking
mypy dreader/

# Linting
flake8 dreader/ tests/
```

### Running Examples

```bash
# Ensure you have an EPUB file for testing
cd examples

# Run simple example
python simple_ereader_example.py /path/to/book.epub

# Run comprehensive demo
python ereader_demo.py /path/to/book.epub

# Generate animated GIFs
python generate_ereader_gifs.py /path/to/book.epub
```

## Testing

The project includes comprehensive tests covering:

- **Application API** - All EbookReader methods and workflows
- **System Integration** - Layout manager, bookmarks, and state management
- **Highlighting** - Word and selection highlighting with persistence
- **Edge Cases** - Error handling, boundary conditions, and recovery

```bash
# Run all tests
pytest

# Run specific test file
pytest tests/test_ereader_application.py

# Run with verbose output
pytest -v

# Run with coverage report
pytest --cov=dreader --cov-report=term-missing
```

## Contributing

Contributions welcome! This project demonstrates what's possible with pyWebLayout. If you build something cool or find ways to improve the reader, please share!

### How to Contribute

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Make your changes with tests
4. Run tests and ensure coverage stays high
5. Format code with black
6. Submit a pull request

## License

MIT License - see [LICENSE](LICENSE) file for details

## Author

Duncan Tourolle - duncan@tourolle.paris

## Related Projects

- [pyWebLayout](https://gitea.tourolle.paris/dtourolle/pyWebLayout) - The underlying layout engine library

## Acknowledgments

Built with [pyWebLayout](https://gitea.tourolle.paris/dtourolle/pyWebLayout) - A powerful Python library for HTML-like layout and rendering.