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

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.