ReadViewSDK/.planning/phases/04-reader-capabilities/04-03-PLAN.md

phase: 04-reader-capabilities plan: 03 type: execute wave: 3 depends_on: - "04-02" files_modified: - Sources/RDReaderView/EPUBUI/RDEPUBReaderController.swift - Sources/RDReaderView/EPUBUI/RDEPUBReaderConfiguration.swift - Sources/RDReaderView/RDURLReaderController.swift - ReadViewDemo/ReadViewDemo/ViewController.swift autonomous: true requirements: - COMP-04 user_setup: [] must_haves: truths: - repagination after font, line-height, theme, or viewport changes restores semantic reading state. - the demo app remains the primary runtime verification entry point. - RDReaderView does not need modification to validate these flows. artifacts: - .planning/phases/04-reader-capabilities/04-03-SUMMARY.md key_links: - RDEPUBReaderController.configuration.didSet - RDEPUBReaderController.handleViewportChangeIfNeeded - RDEPUBReaderController.rebuildExternalTextBook 验证并收敛字体、行高、主题和 viewport 变化导致的重新分页与状态恢复，让 reader 在 Phase 4 完成后可以稳定承接 repagination。

Purpose: 证明新 native backend 在真实 reader 交互下能够重新分页而不丢失位置、搜索和高亮上下文。 Output: re-pagination/state-restore fixes, plus demo-visible validation hooks or diagnostics where needed.

@.planning/ROADMAP.md @.planning/STATE.md @.planning/phases/04-reader-capabilities/04-RESEARCH.md @.planning/phases/04-reader-capabilities/04-PATTERNS.md @.planning/phases/03-page-metadata-pagination/03-VERIFICATION.md @Sources/RDReaderView/EPUBUI/RDEPUBReaderController.swift @Sources/RDReaderView/EPUBUI/RDEPUBReaderConfiguration.swift @Sources/RDReaderView/RDURLReaderController.swift @ReadViewDemo/ReadViewDemo/ViewController.swift Task 1: 收敛 repagination 触发器与状态恢复逻辑 Sources/RDReaderView/EPUBUI/RDEPUBReaderController.swift, Sources/RDReaderView/EPUBUI/RDEPUBReaderConfiguration.swift, Sources/RDReaderView/RDURLReaderController.swift Sources/RDReaderView/EPUBUI/RDEPUBReaderController.swift, Sources/RDReaderView/EPUBUI/RDEPUBReaderConfiguration.swift, Sources/RDReaderView/RDURLReaderController.swift 围绕 `configuration.didSet`、`requiresRepagination`、`refreshVisibleContentPreservingLocation`、`rebuildExternalTextBook`、`handleViewportChangeIfNeeded` 和 TXT/native 入口收敛 repagination 行为，使 reader 在设置变化与 viewport 变化后恢复到语义位置，而不是错误页或空状态。 - font size / line height changes trigger repagination through semantic location restore - theme changes refresh visible content without dropping current reader state - viewport changes do not require `RDReaderView` changes to preserve location rg -n "requiresRepagination|refreshVisibleContentPreservingLocation|rebuildExternalTextBook|handleViewportChangeIfNeeded|configuration" Sources/RDReaderView/EPUBUI/RDEPUBReaderController.swift Sources/RDReaderView/EPUBUI/RDEPUBReaderConfiguration.swift Sources/RDReaderView/RDURLReaderController.swift repagination triggers are stable and state-preserving. Task 2: 在 demo 中验证 reader-level repagination 与状态恢复 ReadViewDemo/ReadViewDemo/ViewController.swift, Sources/RDReaderView/EPUBUI/RDEPUBReaderController.swift ReadViewDemo/ReadViewDemo/ViewController.swift, Sources/RDReaderView/EPUBUI/RDEPUBReaderController.swift, ReadViewDemo/ReadViewDemo/book/ 用现有 demo 入口补充最小但可观察的 reader-level 验证路径或日志，证明 Phase 4 关注的 repagination / location restore / search-highlight continuity 可以被检查。不要新建并行 demo shell。 - demo remains the validation entry point - runtime checks can confirm at least part of the repagination/state-restore behavior - sample corpus under `ReadViewDemo/ReadViewDemo/book/` remains the verification source test -d ReadViewDemo/ReadViewDemo/book && rg -n "restore|repagination|search|highlight|location|theme|font" ReadViewDemo/ReadViewDemo Sources/RDReaderView/EPUBUI/RDEPUBReaderController.swift Phase 4 finishes with a real runtime path to prove state-preserving repagination. Before declaring plan complete: - [ ] `rg -n "requiresRepagination|refreshVisibleContentPreservingLocation|rebuildExternalTextBook|handleViewportChangeIfNeeded|configuration" Sources/RDReaderView/EPUBUI/RDEPUBReaderController.swift Sources/RDReaderView/EPUBUI/RDEPUBReaderConfiguration.swift Sources/RDReaderView/RDURLReaderController.swift` - [ ] `test -d ReadViewDemo/ReadViewDemo/book` - [ ] `rg -n "restore|repagination|search|highlight|location|theme|font" ReadViewDemo/ReadViewDemo Sources/RDReaderView/EPUBUI/RDEPUBReaderController.swift` After completion, create `.planning/phases/04-reader-capabilities/04-03-SUMMARY.md`