103 lines
6.1 KiB
Markdown
103 lines
6.1 KiB
Markdown
# Phase 6: 页面几何与交互命中层 - Context
|
||
|
||
**Gathered:** 2026-05-22
|
||
**Status:** Ready for planning
|
||
|
||
<domain>
|
||
## Phase Boundary
|
||
|
||
为 native text 分页结果建立可复用的页面级 layout frame 几何能力，并把 reader 的命中、选区和定位行为逐步迁移到显式几何层，而不是继续主要依赖 `UITextView` 的黑盒行为。此阶段不替换 `RDReaderView`，fixed / interactive EPUB 继续走 `WKWebView`，并且必须保持 `pageStartOffset`、`pageEndOffset`、`fragmentOffsets`、`RDEPUBTextOffsetRangeInfo` 的既有语义稳定。
|
||
|
||
</domain>
|
||
|
||
<decisions>
|
||
## Implementation Decisions
|
||
|
||
### Geometry Coverage
|
||
- **D-01:** 几何 API 以 `selection` 为第一优先级，但实现不能停留在单点能力上；页面几何层应至少覆盖字符串范围矩形查询、矩形反查文本范围、截断检测、命中定位所需的基础 API。
|
||
- **D-02:** 用户明确希望前两项讨论点都“全做”，因此 Phase 6 的几何层不能只做 selection 的局部补丁，而要把 selection 相关的几何查询做成可复用、可持续扩展的基础层。
|
||
|
||
### Interaction Migration
|
||
- **D-03:** 第一条迁移链路选择 `selection`。Phase 6 优先把选区范围获取、选区命中、选区展示和 offset 归一化迁移到 layout frame 几何层。
|
||
- **D-04:** 搜索命中、高亮和点击定位保持兼容，但不作为本阶段的主迁移链路；它们应当复用同一套几何接口，而不是各自再造一层逻辑。
|
||
|
||
### Display Strategy
|
||
- **D-05:** 展示策略选择 `custom overlay`。`UITextView` 继续承担基础文本布局/输入能力，但选区和命中展示不应继续绑定在它的黑盒 selection 表现上。
|
||
- **D-06:** overlay 方案必须与现有 offset-based 语义对齐，不能引入只可视不可追踪的新状态。
|
||
|
||
### Geometry Precision
|
||
- **D-07:** 精度优先级选择 `glyph 级精度`。在兼容性不被破坏的前提下，优先追求更精确的 glyph/fragment 级几何，而不是只做到粗粒度 block 级命中。
|
||
- **D-08:** 兼容性要求仍然保留，但仅作为精度实现的约束条件，不作为本阶段的目标上限。
|
||
|
||
### the agent's Discretion
|
||
- `search`、`highlight`、`tap locate` 在 Phase 6 中保持可接入状态；如果实现 selection 几何时顺手能抽出共享接口，可以一并收口，但不允许为了覆盖面而重写 reader 展示层。
|
||
|
||
</decisions>
|
||
|
||
<canonical_refs>
|
||
## Canonical References
|
||
|
||
**Downstream agents MUST read these before planning or implementing.**
|
||
|
||
### Milestone framing
|
||
- `.planning/ROADMAP.md` — Phase 6 的目标、依赖、成功标准与 cross-cutting constraints
|
||
- `.planning/REQUIREMENTS.md` — LAYOUT-01 / LAYOUT-02 / LAYOUT-03 的具体要求与 out-of-scope 约束
|
||
- `.planning/STATE.md` — 当前里程碑、当前 phase 和规划状态
|
||
|
||
### Native pagination and geometry pipeline
|
||
- `Sources/RDReaderView/EPUBTextRendering/RDEPUBTextLayouter.swift` — 当前分页 frame 的生成、断页原因、attachment/block 诊断逻辑
|
||
- `Sources/RDReaderView/EPUBTextRendering/RDEPUBTextLayoutFrame.swift` — 现有 page frame 结构与元数据承载点
|
||
- `Sources/RDReaderView/EPUBTextRendering/RDEPUBTextPaginationSupport.swift` — 现有分页支持入口和 page range 适配
|
||
- `Sources/RDReaderView/EPUBTextRendering/RDEPUBTextBookBuilder.swift` — page / offset continuity 的构建逻辑
|
||
- `Sources/RDReaderView/EPUBCore/RDEPUBReadingModels.swift` — `pageStartOffset`、`pageEndOffset`、`fragmentOffsets`、`RDEPUBTextOffsetRangeInfo` 等核心语义
|
||
|
||
### Reader integration
|
||
- `Sources/RDReaderView/EPUBUI/RDEPUBTextContentView.swift` — 当前 `UITextView` selection、highlight 与 offset overlap 逻辑
|
||
- `Sources/RDReaderView/EPUBUI/RDEPUBReaderController.swift` — reader 状态编排、位置恢复、搜索和高亮接线点
|
||
|
||
No external specs — requirements are fully captured in decisions above
|
||
|
||
</canonical_refs>
|
||
|
||
<code_context>
|
||
## Existing Code Insights
|
||
|
||
### Reusable Assets
|
||
- `RDEPUBTextLayoutFrame` already carries content range, break reason, block range, attachment ranges, attachment kinds and diagnostics; it is the natural home for extra geometry fields.
|
||
- `RDEPUBTextLayouter` already has a stable frame-generation pipeline and can be extended without changing the upstream chapter preprocessing contract.
|
||
- `RDEPUBTextBookBuilder` already preserves absolute offsets and fragment continuity, which keeps selection and restore compatible with later geometry work.
|
||
- `RDEPUBReaderController` already centralizes reader state and interaction orchestration, so selection migration should route through it instead of creating a parallel controller.
|
||
|
||
### Established Patterns
|
||
- Offset-based consumers already rely on `pageStartOffset` / `pageEndOffset` / `fragmentOffsets` rather than page-local ad hoc state.
|
||
- Existing highlight and search rendering are driven by offset overlap, which is a useful bridge for moving selection to a geometry-backed overlay.
|
||
- Native reflowable EPUB remains the primary target for deeper internals; fixed / interactive EPUB stays on `WKWebView`.
|
||
|
||
### Integration Points
|
||
- Geometry APIs should live next to the page frame and pagination support code, not inside the reader view shell.
|
||
- Selection overlay work must integrate with `RDEPUBTextContentView` and the controller flow that already owns selection restore and highlight updates.
|
||
- Any new geometry result type should be consumable by future search/highlight/tap-locate work without duplicating page traversal or offset math.
|
||
|
||
</code_context>
|
||
|
||
<specifics>
|
||
## Specific Ideas
|
||
|
||
- The user wants Phase 6 to be selection-first and to complete that path fully, not as a partial shim.
|
||
- The user prefers a custom overlay for selection presentation rather than continuing to lean on `UITextView` selection visuals.
|
||
- The geometry target is glyph-level precision, with compatibility kept as a constraint rather than the primary target.
|
||
|
||
</specifics>
|
||
|
||
<deferred>
|
||
## Deferred Ideas
|
||
|
||
None — the discussion stayed within Phase 6 scope. `search` / `highlight` / `tap locate` remain compatible consumers of the same geometry layer, but they are not the primary migrated chain in this phase.
|
||
|
||
</deferred>
|
||
|
||
---
|
||
|
||
*Phase: 6-页面几何与交互命中层*
|
||
*Context gathered: 2026-05-22*
|