# 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*