---
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:)`
---

<objective>
修复并验证 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.
</objective>

<context>
@.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
</context>

<tasks>

<task type="auto">
  <name>Task 1: 收敛 native text 的 location / selection / highlight 兼容语义</name>
  <files>Sources/RDReaderView/EPUBUI/RDEPUBReaderController.swift, Sources/RDReaderView/EPUBUI/RDEPUBTextContentView.swift, Sources/RDReaderView/EPUBCore/RDEPUBReadingModels.swift</files>
  <read_first>Sources/RDReaderView/EPUBUI/RDEPUBReaderController.swift, Sources/RDReaderView/EPUBUI/RDEPUBTextContentView.swift, Sources/RDReaderView/EPUBCore/RDEPUBReadingModels.swift, Sources/RDReaderView/EPUBTextRendering/RDEPUBTextBookBuilder.swift</read_first>
  <action>验证并修复 native text selection/highlight 链路，重点围绕 `normalizedTextSelection`、`RDEPUBTextOffsetRangeInfo`、`pageStartOffset` / `pageEndOffset` overlap 计算和 reader persistence 语义展开。若要补充 guard 或 normalization，必须继续以 chapter href + absolute offsets 为核心，而不是引入 page-local-only id。</action>
  <acceptance_criteria>
    - `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
  </acceptance_criteria>
  <verify>rg -n "RDEPUBTextOffsetRangeInfo|normalizedTextSelection|pageStartOffset|pageEndOffset|rangeInfo" Sources/RDReaderView/EPUBUI/RDEPUBReaderController.swift Sources/RDReaderView/EPUBUI/RDEPUBTextContentView.swift Sources/RDReaderView/EPUBCore</verify>
  <done>native text highlight and selection persistence remain offset-compatible.</done>
</task>

<task type="auto">
  <name>Task 2: 修复并验证 native text 搜索 / TOC / 跳转页号解析</name>
  <files>Sources/RDReaderView/EPUBUI/RDEPUBReaderController.swift, Sources/RDReaderView/EPUBCore/RDEPUBReadingSession.swift, Sources/RDReaderView/EPUBTextRendering/RDEPUBTextSearchEngine.swift</files>
  <read_first>Sources/RDReaderView/EPUBUI/RDEPUBReaderController.swift, Sources/RDReaderView/EPUBCore/RDEPUBReadingSession.swift, Sources/RDReaderView/EPUBTextRendering/RDEPUBTextSearchEngine.swift</read_first>
  <action>核对 native text path 的 `pageNumber(for:)`、`search`、`navigateToCurrentSearchMatch`、TOC 页号解析与内部链接跳转，确保 richer page model 下这些 reader feature 仍能落到正确页。需要时可以增强 lookup/normalization，但不要把 Web 路径逻辑硬搬到 native path。</action>
  <acceptance_criteria>
    - 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
  </acceptance_criteria>
  <verify>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</verify>
  <done>native text search, TOC, and jumps remain believable after reintegration.</done>
</task>

</tasks>

<verification>
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`
</verification>

<output>
After completion, create `.planning/phases/04-reader-capabilities/04-02-SUMMARY.md`
</output>