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