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

phase: 04-reader-capabilities plan: 02 type: execute wave: 2 depends_on: - "04-01" files_modified: - Sources/RDReaderView/EPUBUI/RDEPUBReaderController.swift - Sources/RDReaderView/EPUBCore/RDEPUBReadingSession.swift - Sources/RDReaderView/EPUBUI/RDEPUBTextContentView.swift - Sources/RDReaderView/EPUBTextRendering/RDEPUBTextSearchEngine.swift - Sources/RDReaderView/EPUBCore/RDEPUBReadingModels.swift autonomous: true requirements: - COMP-03 user_setup: [] must_haves: truths: - native text highlight/search behavior remains grounded in absolute chapter offsets. - location mapping and page-number lookup stay coherent after the reader integration cleanup. - no page-local-only persistence identifier replaces RDEPUBTextOffsetRangeInfo. artifacts: - .planning/phases/04-reader-capabilities/04-02-SUMMARY.md key_links: - RDEPUBReaderController.normalizedTextSelection - RDEPUBReaderController.search - RDEPUBReadingSession.pageIndex(for:) 修复并验证 native text reader 下的位置映射、高亮、选区、搜索和 TOC/跳转兼容能力，确保 Phase 3 的 richer paginator 不会破坏这些用户能力。

Purpose: 把 offset-compatible 的底层契约真正接回 reader 行为链路。 Output: source fixes and verification around native location lookup, selection normalization, search navigation, and persisted highlights.

@.planning/ROADMAP.md @.planning/STATE.md @.planning/phases/04-reader-capabilities/04-RESEARCH.md @.planning/phases/04-reader-capabilities/04-PATTERNS.md @Sources/RDReaderView/EPUBUI/RDEPUBReaderController.swift @Sources/RDReaderView/EPUBCore/RDEPUBReadingSession.swift @Sources/RDReaderView/EPUBUI/RDEPUBTextContentView.swift @Sources/RDReaderView/EPUBTextRendering/RDEPUBTextSearchEngine.swift @Sources/RDReaderView/EPUBCore/RDEPUBReadingModels.swift Task 1: 收敛 native text 的 location / selection / highlight 兼容语义 Sources/RDReaderView/EPUBUI/RDEPUBReaderController.swift, Sources/RDReaderView/EPUBUI/RDEPUBTextContentView.swift, Sources/RDReaderView/EPUBCore/RDEPUBReadingModels.swift Sources/RDReaderView/EPUBUI/RDEPUBReaderController.swift, Sources/RDReaderView/EPUBUI/RDEPUBTextContentView.swift, Sources/RDReaderView/EPUBCore/RDEPUBReadingModels.swift, Sources/RDReaderView/EPUBTextRendering/RDEPUBTextBookBuilder.swift 验证并修复 native text selection/highlight 链路，重点围绕 `normalizedTextSelection`、`RDEPUBTextOffsetRangeInfo`、`pageStartOffset` / `pageEndOffset` overlap 计算和 reader persistence 语义展开。若要补充 guard 或 normalization，必须继续以 chapter href + absolute offsets 为核心，而不是引入 page-local-only id。 - `RDEPUBTextOffsetRangeInfo` remains the persisted native text range format - native selection/highlight restore still maps through absolute chapter offsets - `RDEPUBTextContentView` still derives visible ranges from page offsets rg -n "RDEPUBTextOffsetRangeInfo|normalizedTextSelection|pageStartOffset|pageEndOffset|rangeInfo" Sources/RDReaderView/EPUBUI/RDEPUBReaderController.swift Sources/RDReaderView/EPUBUI/RDEPUBTextContentView.swift Sources/RDReaderView/EPUBCore native text highlight and selection persistence remain offset-compatible. Task 2: 修复并验证 native text 搜索 / TOC / 跳转页号解析 Sources/RDReaderView/EPUBUI/RDEPUBReaderController.swift, Sources/RDReaderView/EPUBCore/RDEPUBReadingSession.swift, Sources/RDReaderView/EPUBTextRendering/RDEPUBTextSearchEngine.swift Sources/RDReaderView/EPUBUI/RDEPUBReaderController.swift, Sources/RDReaderView/EPUBCore/RDEPUBReadingSession.swift, Sources/RDReaderView/EPUBTextRendering/RDEPUBTextSearchEngine.swift 核对 native text path 的 `pageNumber(for:)`、`search`、`navigateToCurrentSearchMatch`、TOC 页号解析与内部链接跳转，确保 richer page model 下这些 reader feature 仍能落到正确页。需要时可以增强 lookup/normalization，但不要把 Web 路径逻辑硬搬到 native path。 - native text search still produces usable page navigation - TOC/page-number resolution stays coherent for `RDEPUBTextBook` - reader state and page lookup are not duplicated into a second custom navigation stack rg -n "search\\(|navigateToCurrentSearchMatch|pageNumber\\(for: searchMatch\\)|flattenedTableOfContentsItems|pageIndex\\(for:" Sources/RDReaderView/EPUBUI/RDEPUBReaderController.swift Sources/RDReaderView/EPUBCore/RDEPUBReadingSession.swift Sources/RDReaderView/EPUBTextRendering/RDEPUBTextSearchEngine.swift native text search, TOC, and jumps remain believable after reintegration. Before declaring plan complete: - [ ] `rg -n "RDEPUBTextOffsetRangeInfo|normalizedTextSelection|pageStartOffset|pageEndOffset|rangeInfo" Sources/RDReaderView/EPUBUI/RDEPUBReaderController.swift Sources/RDReaderView/EPUBUI/RDEPUBTextContentView.swift Sources/RDReaderView/EPUBCore` - [ ] `rg -n "search\\(|navigateToCurrentSearchMatch|pageNumber\\(for: searchMatch\\)|flattenedTableOfContentsItems|pageIndex\\(for:" Sources/RDReaderView/EPUBUI/RDEPUBReaderController.swift Sources/RDReaderView/EPUBCore/RDEPUBReadingSession.swift Sources/RDReaderView/EPUBTextRendering/RDEPUBTextSearchEngine.swift` After completion, create `.planning/phases/04-reader-capabilities/04-02-SUMMARY.md`