V2 Roadmap: 17 features across 6 phases (31 WIs)

[lllyys]

V2 Roadmap (Codex-audited, final)

Full plan: docs/archive/codex-plans/2026-03-15-v2-roadmap.md
Architecture: docs/architecture.md

Dual-Mode Architecture

Both engines support both scroll and paged layout:

Engine	Scroll	Paged
Native	V1 default	CSS columns (EPUB), TextKit containers (TXT/MD), PDFKit (PDF)
Unified	Reflow continuous scroll	Reflow paginated + page turns

Unified scope: TXT, MD, simple EPUB. Complex EPUBs fall back to Native. PDF always PDFKit.

Phase 0 — Foundation (11 WIs)

• WI-F01: ReaderLifecycleCoordinator
• WI-F02: FormatCapabilities flags
• WI-F03: ReflowableTextSource protocol
• WI-F04: BackupProvider protocol
• WI-F05: Bug Bug #30: Reading settings bar too long, covering content #60 — Large TXT streaming open
• WI-F06: Bug Bug #31: Cannot add bookmarks, highlights, or notes #61 — Persistent FTS5 index
• WI-F07: ReadingMode + toggle + dual dispatch
• WI-F08: TextKit 2 reflow engine spike
• WI-F09: Cross-mode locator/anchor normalization
• WI-F10: Mode-switch persistence tests
• WI-F11: PageNavigator protocol

Phase A — Quick Wins (5 WIs)

• WI-A01: Bug #95: Translate opens Summarize panel #22 Search match highlighting
• WI-A02: Bug #103: TOC jumps to wrong chapter + wrong position + position restore broken #30 Custom book covers
• WI-A03: Bug #98: Text transforms fail #25 Configurable tap zones — settings UI added
• WI-A04: Bug #1: CJK search returns no results #32 Reading theme backgrounds — PhotosPicker + opacity added
• WI-A05: Bug #6: Reading settings do not take effect #37 Per-book reading settings — resolve() wired (bug Bug #54: Highlight disappears in large CJK TXT after selecting other text #84 FIXED)

Phase B — Reader Core (13 WIs)

• WI-B01: Bug #96: TTS no sound, no error #23 TXT TOC rules — 14/25 rules enabled (bug Bug #53: Highlight visual not applied in large CJK TXT (chunked reader) #83 FIXED)
• WI-B02: Bug #2: Search results incomplete — only a few shown #33 Dictionary / translate-on-select
• WI-B03: Bug #99: Search highlight missing in some TXT #26 TTS (AVSpeechSynthesizer) — audio session fixed (bug Bug #66: Annotations panel tab placeholders stale in UI test #96 FIXED)
• WI-B04: Bug #94: Keyboard can't dismiss in chat #21 Unified — TXT reflow (scroll + paged) — bug Bug #52: Large CJK TXT annotation panel navigation fails #82 FIXED
• WI-B05: Bug #94: Keyboard can't dismiss in chat #21 Unified — MD reflow (scroll + paged) — bug Bug #52: Large CJK TXT annotation panel navigation fails #82 FIXED
• WI-B06: Bug #94: Keyboard can't dismiss in chat #21 Native — EPUB paged (CSS columns) — bug Bug #52: Large CJK TXT annotation panel navigation fails #82 FIXED
• WI-B07: Bug #94: Keyboard can't dismiss in chat #21 Unified — EPUB simple chapters (scroll + paged) — bug Bug #52: Large CJK TXT annotation panel navigation fails #82 FIXED
• WI-B08: Bug #94: Keyboard can't dismiss in chat #21 Native — TXT/MD paged (TextKit containers) — bug Bug #52: Large CJK TXT annotation panel navigation fails #82 FIXED
• WI-B09: Bug #94: Keyboard can't dismiss in chat #21 Native — PDF page nav (tap zones)
• WI-B10: TXT chapter mode: progress bar shows book progress instead of chapter progress #31 Auto page turning — unblocked by Bug #52: Large CJK TXT annotation panel navigation fails #82 fix
• WI-B11: Bug #94: Keyboard can't dismiss in chat #21 Page turn animations (none/slide/cover) — unblocked by Bug #52: Large CJK TXT annotation panel navigation fails #82 fix
• WI-B12: Bug #94: Keyboard can't dismiss in chat #21 EPUB simple vs complex classifier
• WI-B13: Bug #94: Keyboard can't dismiss in chat #21 Pagination cache invalidation

Phase C — Library (4 WIs)

• WI-C01: Bug #3: TXT reading progress not saved #34 Collections / tags / series — bugs Bug #55: Highlights not visible when file is reopened #85, Bug #56: PDF crash after adding highlight and reopening #86 FIXED
• WI-C02: Bug #4: Text search panel slow to open #35 Export annotations — bug Bug #58: EPUB position only chapter-level, not intra-chapter scroll #88 FIXED
• WI-C03: Bug #4: Text search panel slow to open #35 Import annotations — bug Bug #58: EPUB position only chapter-level, not intra-chapter scroll #88 FIXED
• WI-C04: Bug #5: TXT page slow to open #36 OPDS catalog — needs device verification

Phase D — Web Content (8 WIs)

• WI-D01: Bug #97: TTS bar overlaps bottom bar #24 BookSource model + UI — bugs Bug #70: Cannot scroll content in native mode — all formats #100, Bug #71: Reader top bar ugly — buttons small, inconsistent #101 FIXED (SchemaV4)
• WI-D02: Bug #97: TTS bar overlaps bottom bar #24 HTTP client + encoding + cookies
• WI-D03: Bug #97: TTS bar overlaps bottom bar #24 Rule engine (CSS/XPath/regex)
• WI-D04: Bug #97: TTS bar overlaps bottom bar #24 Pipeline MVP
• WI-D05: Bug #97: TTS bar overlaps bottom bar #24 Legado JSON import/export
• WI-D06: Bug #97: TTS bar overlaps bottom bar #24 Chapter cache + offline
• WI-D07: Bug #97: TTS bar overlaps bottom bar #24 Updates + sharing
• WI-D08: Bug #97: TTS bar overlaps bottom bar #24 Optional: JS execution spike

Phase E — Sync & Text (6 WIs)

• WI-E01: Library navigation bar visible during reader loading transition #29 WebDAV backup — needs device verification
• WI-E02: Bug #83: TXT TOC not detected for some files #10 iCloud backup — WONT DO (not needed)
• WI-E03: Text-mapping layer — bug Bug #68: Toolbar buttons hidden at large Dynamic Type in UI test #98 FIXED (sourceText + didSet re-apply)
• WI-E04: Bug #101: Imported sources not visible #28 Simp/Trad conversion — bug Bug #68: Toolbar buttons hidden at large Dynamic Type in UI test #98 FIXED
• WI-E05: Bug #100: Book source cannot be saved #27 Content replacement rules — bug Bug #68: Toolbar buttons hidden at large Dynamic Type in UI test #98 FIXED
• WI-E06: Bug #99: Search highlight missing in some TXT #26 HTTP TTS — bug Bug #66: Annotations panel tab placeholders stale in UI test #96 FIXED

Remaining Open Items

• feat: implement full feature roadmap (17 WIs, 4 phases) #5 Search auto-dismiss — needs device verification
• Bug #83: TXT TOC not detected for some files #10 iCloud backup — WONT DO (not needed)
• Library navigation bar visible during reader loading transition #29 WebDAV — needs device verification
• Bug #5: TXT page slow to open #36 OPDS — needs device verification
• Bug #60: Large TXT files (~15MB) very slow to open #90 AI buttons visible when consent off
• Bug #61: Search is slow in large TXT files (~15MB) #91 Blank panel on Translate without AI
• Bug #63: Progress bar unresponsive in Native mode #93 Chat sessions not persisted
• Bug #64: All files and all formats slow to load #94 Keyboard dismiss in chat
• Bug #69: PDF reader placeholder not appearing in UI test #99 Search highlight in some TXT files

Quality Gates

• TDD mandatory: Every WI follows RED → GREEN → REFACTOR
• Coverage thresholds: Enforced in xcodebuild
• Codex audit: Architecture review before implementation

[lllyys]

Device-Verified Status Update (2026-03-21)

Verified Working (19 features)

#1-4, #6-9, #12, #14-15, #17, #20, #22, #30, #33, #38

TODO — Code Committed, Failed Device Test (18 features)

#	Feature	Issue
5	Search auto-dismiss	Unchecked
11	EPUB highlights	Bug #77
13	AI summarization	Bug #92
18	AI translation	Bug #95
21	Paged mode	Bug #82
23	TXT TOC	Bug #83
24	Book sources	Bugs #100, #101
25	Tap zone settings	No UI
26	TTS	Bug #96
27	Replacement rules	Bug #98
28	Simp/Trad	Bug #98
29	WebDAV	Unverified
31	Auto page turn	Bug #82
32	Theme bg picker	No UI
34	Collections	Bugs #85, #86
35	Export/import	Unverified
36	OPDS	Unverified
37	Per-book settings	Bug #84

Not Implemented (3 features)

#10 iCloud, #40 TTS highlighting, #41 TTS auto-scroll

See docs/features.md and docs/manual-test-checklist.md for details.