# pyWebLayout-ereader

A complete ebook reader application built with [pyWebLayout](https://github.com/yourusername/pyWebLayout).

This project demonstrates how to build a full-featured ebook reader using pyWebLayout's layout engine. It serves as both a reference implementation and a ready-to-use ereader library.

## Features

- 📖 **EPUB Support** - Load and read EPUB files
- 📄 **Page Navigation** - Forward/backward navigation with smooth rendering
- 🔖 **Bookmarks** - Save and restore reading positions
- 🎨 **Text Highlighting** - Highlight words and selections with notes
- 🔍 **Text Selection** - Select and query text via touch/click
- ⚙️ **Customization** - Font size, line spacing, colors
- 📑 **Chapter Navigation** - Jump to chapters via table of contents
- 👆 **Gesture Support** - Tap, swipe, pinch, long-press handling
- 💾 **Position Persistence** - Stable positions across style changes

## Installation

### From Source

```bash
# Install pyWebLayout first if not already installed
cd /path/to/pyWebLayout
pip install -e .

# Install pyWebLayout-ereader
cd /path/to/pyWebLayout-ereader
pip install -e .
```

### As a Dependency

```bash
pip install pyweblayout-ereader
```

## Quick Start

```python
from pyweblayout_ereader import EbookReader

# Create reader
reader = EbookReader(page_size=(800, 1000))

# Load an EPUB
reader.load_epub("mybook.epub")

# Get current page as image
page = reader.get_current_page()
page.save("current_page.png")

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

# Save position
reader.save_position("bookmark1")

# Later, restore position
reader.load_position("bookmark1")
```

## Examples

See the `examples/` directory for complete examples:

- **simple_ereader_example.py** - Basic ereader usage
- **ereader_demo.py** - Full-featured demo with all capabilities
- **word_selection_highlighting.py** - Text selection and highlighting
- **generate_ereader_gifs.py** - Generate animated demos

## Architecture

This project is a **high-level application layer** that combines pyWebLayout components:

```
pyweblayout_ereader.EbookReader
    ↓
├── pyWebLayout.layout.EreaderLayoutManager  # Layout & pagination
├── pyWebLayout.core.HighlightManager        # Highlighting system
├── pyWebLayout.io.gesture                   # Touch/gesture handling
└── pyWebLayout.io.readers                   # EPUB parsing
```

## API Overview

### Loading Content

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

### Navigation

```python
reader.next_page()
reader.previous_page()
reader.jump_to_chapter("Chapter 1")
reader.get_reading_progress()  # 0.0 to 1.0
```

### Styling

```python
reader.increase_font_size()
reader.decrease_font_size()
reader.set_font_size(1.5)  # 150% scale
reader.set_line_spacing(8)
reader.set_inter_block_spacing(20)
```

### Bookmarks

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

### Highlighting

```python
# Highlight a word at pixel coordinates
highlight_id = reader.highlight_word(x=100, y=200, note="Important!")

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

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

### Gesture Handling

```python
from pyWebLayout.io.gesture import TouchEvent, GestureType

# 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']}")
```

## Use Cases

- **Desktop Ereader Applications** - Build native ereader apps
- **Web-based Readers** - Serve rendered pages via Flask/FastAPI
- **E-ink Device Firmware** - Optimized for e-ink displays
- **Reading Analytics** - Track reading patterns and highlights
- **Educational Tools** - Annotated reading with highlights and notes

## Relationship to pyWebLayout

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

**pyWebLayout-ereader** 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, etc.)
- Handles business logic for gestures and interactions

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

## Development

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

# Run tests
pytest

# Format code
black pyweblayout_ereader/

# Type checking
mypy pyweblayout_ereader/
```

## 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!

## License

MIT License - see LICENSE file for details

## Related Projects

- [pyWebLayout](https://github.com/yourusername/pyWebLayout) - The underlying layout engine
- Add your projects here!