91 lines
5.7 KiB
Markdown
91 lines
5.7 KiB
Markdown
---
|
||
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>
|