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

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

Reusable Patterns

Offset continuity is already the compatibility contract

• Sources/RDReaderView/EPUBTextRendering/RDEPUBTextBookBuilder.swift and Sources/RDReaderView/LegacyRDReaderController/RDEPUBTextPaging.swift both preserve pageStartOffset, pageEndOffset, and fragmentOffsets.
• Sources/RDReaderView/EPUBCore/RDEPUBReadingModels.swift keeps RDEPUBTextOffsetRangeInfo as the absolute-offset payload used by selection and highlight consumers.
• Phase 6 should keep that contract intact even after a geometry overlay is introduced.

The layouter already knows more than the view layer

• Sources/RDReaderView/EPUBTextRendering/RDEPUBTextLayouter.swift already determines blockRange, attachmentRanges, attachmentKinds, breakReason, and trailingFragmentID.
• That makes the layouter the right place to enrich RDEPUBTextLayoutFrame with queryable page geometry instead of re-deriving page rules inside RDEPUBTextContentView.

Reader coordination already belongs to the controller

• Sources/RDReaderView/EPUBUI/RDEPUBReaderController.swift already owns selection persistence, current-location updates, highlight creation, search state, and repagination.
• Any new geometry-backed selection flow should plug into the controller rather than creating a second reader state owner.

Content view should become a thin host

• Sources/RDReaderView/EPUBUI/RDEPUBTextContentView.swift currently mixes display, selection, highlight painting, and offset conversion.
• For this phase, the safest direction is to let the view host text plus an overlay and keep the selection model conversion in one place.

Closest Existing Analogs

• RDEPUBTextLayoutFrame is the natural home for page geometry metadata.
• RDEPUBTextBookBuilder is the natural place to lift geometry results into page-level book state.
• RDEPUBReaderController is the natural adapter layer for user interactions and persistence.
• RDEPUBTextContentView is the natural host for an overlay layer because it already owns the page view composition.

Design Guardrails

• Do not move fixed/interactive EPUB off WKWebView.
• Do not change RDReaderView.
• Do not break the existing offset-based consumers while introducing geometry queries.
• Do not let search/highlight/tap-locate become separate geometry implementations; they should reuse the same page geometry API later.