crosspoint-reader/chat-summaries/epub-compliance-feature-prioritization_2026-01-23_19-46-02.md

# EPUB 3.3 Compliance Feature Prioritization

**Date:** 2026-01-23 19:46:02  
**Based on:** EPUB 3.3 Compliance Audit

---

## Overview

This document reviews the audit findings from the CrossPoint Reader EPUB 3.3 compliance audit and prioritizes features for implementation based on:

1. **User Impact** - How much the feature improves the reading experience
2. **Implementation Complexity** - Level of effort required
3. **Existing Infrastructure** - Available code that can be leveraged
4. **Hardware Feasibility** - Whether the e-ink display can support it

---

## Priority 1: High Impact, Infrastructure Ready

These features have existing code that can be leveraged and provide significant user value.

### 1.1 Inline Image Rendering

**Current State:** Images show placeholder text `[Image: alt_text]`

**Infrastructure Available:**
- `Bitmap` class (`lib/GfxRenderer/Bitmap.h`) - BMP parsing with grayscale conversion and dithering
- `JpegToBmpConverter` (`lib/JpegToBmpConverter/`) - JPEG to BMP conversion with prescaling
- `GfxRenderer::drawBitmap()` - Already renders bitmaps to e-ink display
- `ZipFile` - Can extract images from EPUB archive

**Implementation Approach:**
1. Extend `ChapterHtmlSlimParser` to extract image `src` attributes
2. Create `PageImage` element (alongside existing `PageLine`)
3. Extract and cache images from EPUB ZIP to SD card as BMP
4. Integrate image blocks into page layout calculations
5. Render images inline with text during page display

**Complexity:** Medium  
**User Impact:** High - Many EPUBs have important diagrams, illustrations, and decorative images

**Supported Formats:**
- JPEG (via `picojpeg`) - Most common in EPUBs
- BMP (native support)
- PNG - **Not currently supported** (would need `pngle` or similar library)

---

### 1.2 List Markers (Bullets and Numbers)

**Current State:** List items render without visual markers; `<li>` already adds bullet character

**Infrastructure Available:**
- `ChapterHtmlSlimParser` already handles `<li>` tags (line 248 adds bullet)
- Font system supports Unicode characters

**Implementation Approach:**
1. Track list type (`<ol>` vs `<ul>`) in parser state
2. For `<ol>`: maintain counter, render as "1.", "2.", etc.
3. For `<ul>`: use bullet character (already implemented: `\xe2\x80\xa2`)
4. Apply text indentation for list item content

**Current Code (already adds bullet):**
```cpp
if (strcmp(name, "li") == 0) {
  self->currentTextBlock->addWord("\xe2\x80\xa2", EpdFontFamily::REGULAR);
}
```

**Complexity:** Low  
**User Impact:** Medium - Improves readability of enumerated content

---

### 1.3 Nested List Indentation

**Current State:** Nested lists are flattened to same indentation level

**Implementation Approach:**
1. Track nesting depth in parser (`listDepth` counter)
2. Apply progressive `text-indent` based on depth (e.g., 20px per level)
3. Store depth in `BlockStyle` for rendering

**Complexity:** Low  
**User Impact:** Medium - Important for technical documentation and outlines

---

## Priority 2: Medium Impact, Moderate Complexity

### 2.1 Basic Table Rendering

**Current State:** Tables show `[Table omitted]` placeholder

**Implementation Approach:**
1. Parse table structure (`<table>`, `<tr>`, `<td>`, `<th>`)
2. Calculate column widths based on content or proportional division
3. Render as text rows with column separators (e.g., `|` character)
4. Apply header styling (bold) for `<th>` elements

**Constraints:**
- Fixed-width font may be needed for alignment
- Complex tables (colspan, rowspan) would remain unsupported
- Wide tables may need horizontal truncation

**Complexity:** Medium-High  
**User Impact:** Medium - Some EPUBs have data tables, but many don't

---

### 2.2 Internal Link Navigation

**Current State:** Links render as plain text, not interactive

**Implementation Approach:**
1. Parse `<a href="#id">` attributes during HTML parsing
2. Store link targets in page elements
3. Add UI for link selection (highlight/underline links)
4. Implement navigation to target anchor when activated
5. Handle cross-chapter links (resolve to spine + anchor)

**Complexity:** Medium-High (requires UI changes)  
**User Impact:** Medium - Important for reference material, footnotes

---

### 2.3 Line Height CSS Support

**Current State:** Line height is fixed based on font metrics

**Implementation Approach:**
1. Add `line-height` property to `CssParser`
2. Store in `CssStyle` struct
3. Apply multiplier to `getLineHeight()` during layout

**Complexity:** Low  
**User Impact:** Medium - Improves text density matching to publisher intent

---

## Priority 3: Lower Impact or Higher Complexity

### 3.1 Font Size CSS Support

**Current State:** Font size controlled by reader settings only

**Implementation Approach:**
1. Parse `font-size` in `CssParser` (relative units: em, rem, %)
2. Map to available font sizes (snap to nearest)
3. Apply during text rendering

**Constraints:**
- Limited font size options in bitmap fonts
- Large size changes may cause layout issues

**Complexity:** Medium  
**User Impact:** Low-Medium - Most content uses default sizing

---

### 3.2 Page-List Navigation

**Current State:** Only TOC navigation supported

**Implementation Approach:**
1. Parse `<nav epub:type="page-list">` in navigation document
2. Store page reference mappings
3. Add UI to jump to specific page numbers

**Complexity:** Medium  
**User Impact:** Low - Useful for academic/reference texts with page citations

---

### 3.3 Landmarks Navigation

**Current State:** Not implemented

**Implementation Approach:**
1. Parse `<nav epub:type="landmarks">` 
2. Extract semantic markers (cover, toc, bodymatter, etc.)
3. Add quick-nav UI

**Complexity:** Low-Medium  
**User Impact:** Low - Convenience feature

---

## Features NOT Recommended for Implementation

These features are either hardware-limited or provide minimal value for the target use case.

### Hardware Limited (Cannot Implement)

| Feature | Reason |
|---------|--------|
| Color images/CSS | Monochrome 4-level grayscale display |
| Audio playback | No audio hardware |
| Video playback | No video hardware, e-ink refresh too slow |
| Animations | E-ink refresh latency incompatible |
| Media Overlays | Requires audio hardware |

### Not Worth Implementing

| Feature | Reason |
|---------|--------|
| JavaScript | Security concerns, minimal EPUB use, high complexity |
| Fixed Layout (FXL) | Designed for tablets; poor e-ink experience |
| SVG | Complex parser needed, limited use in text EPUBs |
| MathML | Extremely complex, niche use case |
| CSS Grid/Flexbox | Overkill for text layout |
| @font-face | Memory constraints, limited benefit |
| DRM | Licensing complexity, user expectation of DRM-free |
| Forms | Interactive elements unsuitable for e-ink |

---

## Implementation Roadmap

### Phase 1: Quick Wins (Low Effort, High Value)
1. ~~List bullet rendering~~ (already implemented)
2. Ordered list numbering
3. Nested list indentation
4. Line-height CSS support

### Phase 2: Image Support (Medium Effort, High Value)
1. JPEG image extraction and caching
2. BMP image support
3. `PageImage` element integration
4. Image scaling to viewport width
5. (Optional) PNG support via external library

### Phase 3: Enhanced Navigation (Medium Effort, Medium Value)
1. Internal link parsing
2. Link highlighting/selection UI
3. Anchor navigation within chapters
4. Cross-chapter link navigation

### Phase 4: Table Support (High Effort, Medium Value)
1. Basic table parsing
2. Simple column layout
3. Text-based table rendering
4. Header styling

---

## Summary

| Priority | Feature | Complexity | Impact | Dependencies |
|----------|---------|------------|--------|--------------|
| 1.1 | Inline Images | Medium | High | Bitmap, JpegToBmpConverter |
| 1.2 | Ordered List Numbers | Low | Medium | None |
| 1.3 | Nested List Indent | Low | Medium | None |
| 2.1 | Basic Tables | Medium-High | Medium | None |
| 2.2 | Internal Links | Medium-High | Medium | UI changes |
| 2.3 | Line Height CSS | Low | Medium | CssParser |
| 3.1 | Font Size CSS | Medium | Low-Medium | Font system |
| 3.2 | Page-List Nav | Medium | Low | Navigation system |
| 3.3 | Landmarks Nav | Low-Medium | Low | Navigation system |

**Recommended First Implementation:** Start with Phase 1 quick wins (list improvements, line-height), then proceed to Image Support as it has the highest user-visible impact and leverages existing infrastructure.