V2 Roadmap: 17 features across 6 phases (31 WIs) #6
Description
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