ReadViewSDK/.planning/phases/06-page-geometry-and-interaction-hit-layer/06-CONTEXT.md

Phase 6: 页面几何与交互命中层 - Context

Gathered: 2026-05-22 Status: Ready for planning

## Phase Boundary

为 native text 分页结果建立可复用的页面级 layout frame 几何能力，并把 reader 的命中、选区和定位行为逐步迁移到显式几何层，而不是继续主要依赖 UITextView 的黑盒行为。此阶段不替换 RDReaderView，fixed / interactive EPUB 继续走 WKWebView，并且必须保持 pageStartOffset、pageEndOffset、fragmentOffsets、RDEPUBTextOffsetRangeInfo 的既有语义稳定。

## 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 展示层。

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

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

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

---

Phase: 6-页面几何与交互命中层 Context gathered: 2026-05-22