dreader-application/HTML_GENERATION.md

# HTML Generation for dreader

This document describes how to use the HTML generation features in dreader to create UI for e-reader applications.

## Overview

The dreader library now includes HTML generation capabilities that allow you to create complete user interfaces programmatically. This is designed to work with a Hardware Abstraction Layer (HAL) that handles the actual display rendering and input processing.

## Architecture

```
┌─────────────────────────────────────┐
│  dreader Library                    │
│  ├─ EbookReader (book rendering)    │
│  ├─ html_generator (UI generation)  │
│  └─ book_utils (scanning/metadata)  │
└─────────────────────────────────────┘
          ↓ HTML strings
┌─────────────────────────────────────┐
│  HAL (Hardware Abstraction Layer)   │
│  - Receives HTML strings            │
│  - Renders to display               │
│  - Captures touch/button input      │
│  - Calls back to dreader            │
└─────────────────────────────────────┘
```

## Page and Overlay Concept

The UI uses a **page/overlay** architecture:

- **Page (background)**: The main book content rendered as an image
- **Overlay (foreground)**: UI elements like settings, table of contents, bookmarks, etc.

## Available Modules

### 1. html_generator

Functions for generating HTML strings:

- `generate_library_html(books)` - Grid view of all books with covers
- `generate_reader_html(title, author, page_data)` - Book reading view
- `generate_settings_overlay()` - Settings panel
- `generate_toc_overlay(chapters)` - Table of contents
- `generate_bookmarks_overlay(bookmarks)` - Bookmarks list

### 2. book_utils

Utilities for managing books:

- `scan_book_directory(path)` - Scan directory for EPUB files
- `extract_book_metadata(epub_path)` - Get title, author, cover
- `get_chapter_list(reader)` - Format chapters for TOC
- `get_bookmark_list(reader)` - Format bookmarks
- `page_image_to_base64(image)` - Convert page image to base64

## Usage Example

```python
from pathlib import Path
from dreader import create_ebook_reader
from dreader.html_generator import (
    generate_library_html,
    generate_reader_html,
    generate_toc_overlay
)
from dreader.book_utils import (
    scan_book_directory,
    get_chapter_list,
    page_image_to_base64
)

# 1. Show library view
books_dir = Path('books')
books = scan_book_directory(books_dir)
library_html = generate_library_html(books)
# Pass library_html to HAL for rendering

# 2. User selects a book
selected_book = books[0]
reader = create_ebook_reader(page_size=(800, 1000))
reader.load_epub(selected_book['path'])

# 3. Show reader view
page_image = reader.get_current_page()
page_base64 = page_image_to_base64(page_image)
reader_html = generate_reader_html(
    book_title=reader.book_title,
    book_author=reader.book_author,
    page_image_data=page_base64
)
# Pass reader_html to HAL for rendering

# 4. User presses "Contents" button - show TOC overlay
chapters = get_chapter_list(reader)
toc_html = generate_toc_overlay(chapters)
# Pass toc_html to HAL for rendering on top of page
```

## HTML Structure

### Library View

The library uses an HTML table for grid layout:

```html
<table class="library-grid">
  <tr>
    <td class="book-item">
      <table>
        <tr><td class="cover-cell"><img src="..."></td></tr>
        <tr><td class="title-cell">Book Title</td></tr>
        <tr><td class="author-cell">Author Name</td></tr>
      </table>
    </td>
    <!-- More books... -->
  </tr>
</table>
```

### Reader View

The reader view has three sections:

- Header: Book info + buttons (Library, Contents, Settings)
- Page container: Centered book page image
- Footer: Navigation buttons (Previous, Next)

### Overlays

Overlays use:

- Semi-transparent background (`rgba(0, 0, 0, 0.7)`)
- Centered white panel
- Close button
- Table-based layout for content

## Button/Link Interaction

All interactive elements have:

- `id` attributes for buttons (e.g., `id="btn-next"`)
- `data-*` attributes for dynamic content (e.g., `data-chapter-index="5"`)
- CSS classes for styling (e.g., `class="nav-button"`)

Your HAL should:

1. Parse the HTML to identify interactive elements
2. Map touch/click coordinates to elements
3. Call appropriate dreader methods
4. Regenerate and render updated HTML

## Demo

Run the included demo to see all features:

```bash
source venv/bin/activate
python examples/html_generation_demo.py
```

This will generate example HTML files in the `output/` directory that you can open in a browser to preview.

## Integration with HAL

Your HAL should implement:

1. **HTML Rendering**: Parse and display HTML strings
2. **Touch Input**: Map touch coordinates to HTML elements
3. **State Management**: Maintain reader state between interactions
4. **Re-rendering**: Update display when state changes

Example HAL flow:

```
User touches screen
    ↓
HAL identifies touched element (e.g., "btn-next")
    ↓
HAL calls reader.next_page()
    ↓
HAL regenerates reader_html with new page
    ↓
HAL renders updated HTML
```

## Styling

All HTML includes inline CSS for complete styling. The design is:

- Clean, minimal interface
- Dark theme for reader (reduces eye strain)
- Large touch targets for buttons
- Responsive layout using tables (widely supported)

## Customization

To customize the UI:

1. Edit functions in `dreader/html_generator.py`
2. Modify CSS in the `<style>` blocks
3. Change layout structure in the HTML templates
4. Adjust colors, fonts, spacing as needed

## Files

- `dreader/html_generator.py` - HTML generation functions
- `dreader/book_utils.py` - Book scanning and utilities
- `examples/html_generation_demo.py` - Complete demonstration
- `output/` - Generated HTML examples (after running demo)