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):

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.