docs(06): capture phase context
This commit is contained in:
shen
parent
bd4978266a
commit
7b5c77cedd
@ -0,0 +1,102 @@
|
||||
# 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*
|
||||
@ -0,0 +1,71 @@
|
||||
# Phase 6: 页面几何与交互命中层 - Discussion Log
|
||||
|
||||
> **Audit trail only.** Do not use as input to planning, research, or execution agents.
|
||||
> Decisions are captured in CONTEXT.md — this log preserves the alternatives considered.
|
||||
|
||||
**Date:** 2026-05-22
|
||||
**Phase:** 6-页面几何与交互命中层
|
||||
**Areas discussed:** Geometry Coverage, Interaction Migration, Display Strategy, Geometry Precision
|
||||
|
||||
---
|
||||
|
||||
## Geometry Coverage
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| `selection` | Prioritize selection geometry first | ✓ |
|
||||
| `search / highlight / tap locate` | Prioritize other interaction geometry first | |
|
||||
| `all` | Spread coverage across all consumers immediately | |
|
||||
|
||||
**User's choice:** `selection`
|
||||
**Notes:** User additionally said the first two discussion areas should be fully done, so this is not a thin one-off patch.
|
||||
|
||||
---
|
||||
|
||||
## Interaction Migration
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| `selection` | Migrate selection range / hit / display flow first | ✓ |
|
||||
| `search hit` | Migrate search hit resolution first | |
|
||||
| `highlight paint` | Migrate highlight painting first | |
|
||||
| `tap locate` | Migrate tap / point locate first | |
|
||||
|
||||
**User's choice:** `selection`
|
||||
**Notes:** The selection chain is the first reader interaction to move onto the geometry layer.
|
||||
|
||||
---
|
||||
|
||||
## Display Strategy
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| `custom overlay` | Add a dedicated overlay for selection/highlight rendering | ✓ |
|
||||
| `UITextView only` | Keep all display logic inside `UITextView` selection behavior | |
|
||||
| `hybrid` | Use `UITextView` plus overlay only for a subset | |
|
||||
|
||||
**User's choice:** `custom overlay`
|
||||
**Notes:** Overlay is preferred for selection presentation; `UITextView` should not remain the main black-box selection renderer.
|
||||
|
||||
---
|
||||
|
||||
## Geometry Precision
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| `glyph 级精度` | Prefer precise glyph-level geometry and reverse mapping | ✓ |
|
||||
| `block 级兼容` | Prefer coarse block-level compatibility first | |
|
||||
| `balanced` | Stop at whatever precision is easiest to ship | |
|
||||
|
||||
**User's choice:** `glyph 级精度`
|
||||
**Notes:** Compatibility remains a constraint, but precision is the target.
|
||||
|
||||
---
|
||||
|
||||
## the agent's Discretion
|
||||
|
||||
- Keep `search` / `highlight` / `tap locate` compatible with the same geometry layer, but do not make them the primary migration target for this phase.
|
||||
|
||||
## Deferred Ideas
|
||||
|
||||
- Broader interaction migration beyond selection can reuse the same geometry layer in later work.
|
||||
Loading…
Reference in New Issue
Block a user