Feature #42: Foliate-js unified reader engine (EPUB + AZW3/MOBI)

[lllyys]

Feature #42: Foliate-js Unified Reader Engine

Priority: High | Status: PLANNED

Summary

Replace VReader's custom EPUB WKWebView bridge with Foliate-js — a battle-tested JS library that natively parses both EPUB and MOBI/AZW3 via a <foliate-view> web component. AZW3/MOBI support comes for free. PDF stays on PDFKit, TXT stays on UITextView.

Architecture

ReaderContainerView
  ├── FoliateReaderHost (EPUB, AZW3, MOBI)  ← NEW
  │     └── WKWebView + <foliate-view>
  │           ├── epub.js (EPUB parser)
  │           ├── mobi.js (AZW3/MOBI parser)
  │           ├── paginator.js + overlayer.js + search.js + tts.js
  │           └── foliate-host.js (Swift↔JS bridge)
  ├── PDFReaderHost (unchanged — PDFKit)
  └── TXTReaderHost (unchanged — UITextView)

Why Foliate-js Instead of Native Swift Parser

1. One engine for two formats (epub.js + mobi.js share same interface)
2. Battle-tested (used by Foliate GNOME reader)
3. Built-in features (pagination, highlights, search, TTS, progress)
4. Less code (delete ~2100 LOC, add ~1700 LOC, net -400)
5. No external dependencies (pure JS, vendored)

Work Items (13)

Phase 1 — Foundation:

• WI-1: BookFormat .azw3 + AZW3MetadataExtractor
• WI-2: Vendor Foliate-js bundle + foliate-host.js + foliate-reader.html
• WI-3: FoliateURLSchemeHandler (custom WKURLSchemeHandler)

Phase 2 — Core Rendering:

• WI-4: FoliateViewBridge + FoliateViewCoordinator
• WI-5: FoliateReaderViewModel (CFI-based positions)

Phase 3 — Container + Integration:

• WI-6: FoliateReaderContainerView + Highlights + Navigation
• WI-7: FoliateHighlightRenderer
• WI-8: FoliateReaderHost + dispatch

Phase 4 — Features:

• WI-9: TOC integration
• WI-10: Search (FTS5 for EPUB, Foliate-js for AZW3)
• WI-11: TTS (SSML → AVSpeechSynthesizer)
• WI-12: Theme/layout configuration

Phase 5 — Cleanup:

• WI-13: Delete old EPUB bridge code

Key Technical Decision

WKURLSchemeHandler (vreader-resource://) serves both JS modules (from app bundle) and book files (from sandbox), solving the dual-directory access problem for ES modules in WKWebView.

Formats Supported

Extension	Format	Renderer
.epub	EPUB	Foliate-js (replaces current bridge)
.azw3	KF8	Foliate-js (NEW)
.azw	KF8/MOBI	Foliate-js (NEW, DRM-free only)
.mobi	KF7/KF8	Foliate-js (NEW)
.pdf	PDF	PDFKit (unchanged)
.txt	TXT	UITextView (unchanged)

Plans

• Full plan: .claude/plans/snug-painting-barto.md
• Summary: docs/2026-03-24-azw3-support-plan.md

Refs #6