46 lines
3.4 KiB
Markdown
46 lines
3.4 KiB
Markdown
# Phase 6: 页面几何与交互命中层 - Research
|
|
|
|
**Date:** 2026-05-22
|
|
**Phase:** 6
|
|
|
|
## Research Question
|
|
|
|
What do we need to know to plan page geometry and interaction hit handling well for the native text path?
|
|
|
|
## Current State
|
|
|
|
- `Sources/RDReaderView/EPUBUI/RDEPUBTextContentView.swift` still renders native text through `UITextView` and derives selection from `selectedRange`.
|
|
- `RDEPUBTextContentView` currently converts the selected range into `RDEPUBSelection` by using page-relative offsets plus `RDEPUBTextOffsetRangeInfo` absolute offsets.
|
|
- `Sources/RDReaderView/EPUBUI/RDEPUBReaderController.swift` normalizes selections, persists them, and remains the central coordination point for reader interactions.
|
|
- `Sources/RDReaderView/EPUBTextRendering/RDEPUBTextLayouter.swift` already computes page boundaries, break reasons, block ranges, attachment ranges, and trailing fragment IDs from CoreText frames.
|
|
- `Sources/RDReaderView/EPUBTextRendering/RDEPUBTextLayoutFrame.swift` is currently only a metadata wrapper around `contentRange` plus pagination diagnostics.
|
|
- `Sources/RDReaderView/EPUBTextRendering/RDEPUBTextBookBuilder.swift` preserves absolute offsets, page continuity, and fragment offsets when assembling `RDEPUBTextBook`.
|
|
- `Sources/RDReaderView/EPUBCore/RDEPUBReadingModels.swift` already keeps the offset-based reader contract alive through `pageStartOffset`, `pageEndOffset`, `fragmentOffsets`, and `RDEPUBTextOffsetRangeInfo`.
|
|
|
|
## What This Means
|
|
|
|
1. The missing abstraction is a page-level geometry layer, not a new pagination pipeline.
|
|
2. The right insertion point is beside the layout frame / pagination code, because that layer already knows page boundaries and fragment continuity.
|
|
3. Selection should move first because the current user decision explicitly made selection the primary migrated interaction chain.
|
|
4. `custom overlay` is the right display model for Phase 6 because `UITextView` selection visuals are still the black-box dependency we are trying to reduce.
|
|
5. Precision target should be glyph-level or fragment-level geometry, with the existing offset contract kept as the compatibility anchor.
|
|
|
|
## Recommended Planning Shape
|
|
|
|
- **Plan 06-01:** add page geometry query APIs to the page frame / book layer.
|
|
- **Plan 06-02:** move selection presentation and hit handling onto a custom overlay while keeping offset-based selection data intact.
|
|
- **Plan 06-03:** verify selection geometry, offset continuity, and restore/search/highlight compatibility across the existing sample books.
|
|
|
|
## Technical Risks
|
|
|
|
- `UITextView` can provide selection behavior, but it is not a reliable source for a stable custom overlay pipeline if the overlay needs richer glyph-level rects.
|
|
- If geometry is bolted into the reader controller, the phase will become a UI-layer patch instead of a reusable page geometry layer.
|
|
- Any new geometry result must remain consumable by future `search`, `highlight`, and `tap locate` work without re-deriving offsets or page boundaries.
|
|
|
|
## Validation Implications
|
|
|
|
- There is no dedicated test target in the repo, so plan verification will need to rely on simulator build/run plus observable runtime behavior.
|
|
- The phase should define concrete UI and log checks for selection overlay behavior, offset preservation, and current-location compatibility.
|
|
- The verification strategy should keep one manual check for glyph-level selection/overlay behavior because that is the user-visible risk area for this phase.
|
|
|