diff --git a/.planning/STATE.md b/.planning/STATE.md index a9bf529..e8b07a6 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -2,7 +2,7 @@ gsd_state_version: 1.0 milestone: v1.1 milestone_name: WXRead 深化对齐 -status: planning +status: ready_to_execute last_updated: "2026-05-22T05:54:18.839Z" last_activity: 2026-05-22 progress: @@ -23,7 +23,7 @@ progress: 参见：`.planning/PROJECT.md`（更新于 2026-05-22） **核心价值：** 稳定可用的 EPUB/TXT 阅读体验 -**当前关注：** `v1.1` 已初始化，下一步进入 Phase 6 讨论与规划 +**当前关注：** `v1.1` 已完成 Phase 6 规划，下一步进入执行 ## 当前结论（摘要） @@ -58,6 +58,6 @@ progress: ## Current Position Phase: 6 -Plan: — -Status: Ready for discuss-phase -Last activity: 2026-05-22 — Milestone v1.1 requirements and roadmap created +Plan: 06-01 / 06-02 / 06-03 +Status: Ready for execute-phase +Last activity: 2026-05-22 — Phase 6 context, research, validation, and plans created diff --git a/.planning/phases/06-page-geometry-and-interaction-hit-layer/06-01-PLAN.md b/.planning/phases/06-page-geometry-and-interaction-hit-layer/06-01-PLAN.md new file mode 100644 index 0000000..373a62e --- /dev/null +++ b/.planning/phases/06-page-geometry-and-interaction-hit-layer/06-01-PLAN.md @@ -0,0 +1,76 @@ +--- +phase: 6 +plan: 06-01 +type: execute +wave: 1 +depends_on: [] +files_modified: + - Sources/RDReaderView/EPUBTextRendering/RDEPUBTextLayoutFrame.swift + - Sources/RDReaderView/EPUBTextRendering/RDEPUBTextLayouter.swift + - Sources/RDReaderView/EPUBTextRendering/RDEPUBTextPaginationSupport.swift + - Sources/RDReaderView/EPUBTextRendering/RDEPUBTextBookBuilder.swift + - Sources/RDReaderView/EPUBCore/RDEPUBReadingModels.swift +autonomous: true +requirements: + - LAYOUT-01 + - LAYOUT-03 +--- + +# Phase 6-01: Page Geometry Model + + +Add a reusable page geometry layer on top of native text pagination so callers can query page-relative rectangles and map rectangles back to text ranges without breaking offset continuity. + + + +- `RDEPUBTextLayoutFrame` can expose page geometry derived from CoreText, not guessed from offsets. +- `pageStartOffset`, `pageEndOffset`, `fragmentOffsets`, and `RDEPUBTextOffsetRangeInfo` semantics remain stable. +- The geometry API is reusable by selection, search, highlight, and tap-locate work in later plans. + + + + +execute +Extend `RDEPUBTextLayoutFrame` and the page model with explicit geometry value types, including a page-level geometry container and line or fragment geometry records. Populate them from `RDEPUBTextLayouter` using CoreText line data so the page can answer range-to-rect and rect-to-range queries without changing pagination break rules. + +- Sources/RDReaderView/EPUBTextRendering/RDEPUBTextLayoutFrame.swift +- Sources/RDReaderView/EPUBTextRendering/RDEPUBTextLayouter.swift +- Sources/RDReaderView/EPUBTextRendering/RDEPUBTextPaginationSupport.swift +- Sources/RDReaderView/EPUBCore/RDEPUBReadingModels.swift + + +- `RDEPUBTextLayoutFrame` or its companion geometry type exposes a query path for at least string-range rectangles and reverse lookup from rects to `NSRange`. +- Existing metadata fields (`contentRange`, `breakReason`, `blockRange`, `attachmentRanges`, `attachmentKinds`, `trailingFragmentID`, `diagnostics`) remain present and unchanged in meaning. +- `RDEPUBTextLayouter` still emits the same page boundaries for the sample books after the geometry data is added. + + + + +execute +Thread the new geometry data through `RDEPUBTextBookBuilder` and `RDEPUBTextBook` so each page retains its geometry alongside `pageStartOffset`, `pageEndOffset`, and `fragmentOffsets`. Keep `pageNumber(for:)` and `location(forPageNumber:)` compatible with the existing absolute-offset contract. + +- Sources/RDReaderView/EPUBTextRendering/RDEPUBTextBookBuilder.swift +- Sources/RDReaderView/EPUBCore/RDEPUBReadingModels.swift +- Sources/RDReaderView/EPUBTextRendering/RDEPUBTextLayouter.swift +- Sources/RDReaderView/LegacyRDReaderController/RDEPUBTextPaging.swift + + +- `RDEPUBTextBook` pages still map absolute offsets to pages through `pageStartOffset` / `pageEndOffset`. +- `RDEPUBTextBook.location(forPageNumber:)` still returns a stable `RDEPUBLocation` for native text pages. +- The sample text book builds successfully with the new geometry fields attached to each page. + + + + + +- Build the `ReadViewDemo` workspace with the `ReadViewDemo` scheme. +- Confirm the new page geometry API compiles and the sample book still paginates. +- Confirm no existing offset-based selection or restore code needs to change to keep building. + + + +- Native text pages expose reusable geometry data. +- The offset-based page contract remains intact. +- Later selection overlay work can consume the geometry layer without re-deriving page boundaries. + + diff --git a/.planning/phases/06-page-geometry-and-interaction-hit-layer/06-02-PLAN.md b/.planning/phases/06-page-geometry-and-interaction-hit-layer/06-02-PLAN.md new file mode 100644 index 0000000..8d15be6 --- /dev/null +++ b/.planning/phases/06-page-geometry-and-interaction-hit-layer/06-02-PLAN.md @@ -0,0 +1,76 @@ +--- +phase: 6 +plan: 06-02 +type: execute +wave: 2 +depends_on: + - 06-01 +files_modified: + - Sources/RDReaderView/EPUBUI/RDEPUBTextContentView.swift + - Sources/RDReaderView/EPUBUI/RDEPUBReaderController.swift + - Sources/RDReaderView/EPUBUI/RDEPUBSelectionOverlayView.swift + - Sources/RDReaderView/EPUBCore/RDEPUBReadingModels.swift +autonomous: true +requirements: + - LAYOUT-02 + - LAYOUT-03 +--- + +# Phase 6-02: Selection Overlay and Hit Flow + + +Move native text selection presentation onto a custom overlay backed by page geometry while keeping the controller-owned selection state, persistence, and absolute offset payload unchanged. + + + +- Selection rendering is driven by overlay geometry, not by the default `UITextView` selection chrome. +- `RDEPUBReaderController` remains the single owner of current selection, persistence, and menu actions. +- Selections still round-trip through `RDEPUBTextOffsetRangeInfo` and preserve absolute offsets. + + + + +execute +Add `RDEPUBSelectionOverlayView` and embed it in `RDEPUBTextContentView` as the visual selection surface. Use the page geometry from 06-01 to draw the selected range and page-local hit regions, while leaving `UITextView` as the text host and input source. + +- Sources/RDReaderView/EPUBUI/RDEPUBTextContentView.swift +- Sources/RDReaderView/EPUBUI/RDEPUBReaderController.swift +- Sources/RDReaderView/EPUBCore/RDEPUBReadingModels.swift +- Sources/RDReaderView/EPUBTextRendering/RDEPUBTextLayoutFrame.swift + + +- A dedicated overlay view or layer exists for native selection presentation. +- Overlay updates when a new selection is made, when the page is reconfigured, and when selection is cleared. +- The visible selection treatment no longer depends on `UITextView`'s default selection chrome as the primary presentation path. + + + + +execute +Update the `RDEPUBTextContentView` delegate flow so selection changes still produce `RDEPUBSelection` objects with absolute offsets, `RDEPUBReaderController` still normalizes and persists them, and copy/highlight/annotate menu actions continue to work through the same controller-owned selection state. + +- Sources/RDReaderView/EPUBUI/RDEPUBTextContentView.swift +- Sources/RDReaderView/EPUBUI/RDEPUBReaderController.swift +- Sources/RDReaderView/EPUBCore/RDEPUBReadingModels.swift +- Sources/RDReaderView/EPUBTextRendering/RDEPUBTextBookBuilder.swift + + +- `currentSelection` still updates when the user changes the selection. +- Selection menu actions still route through the controller and continue to create highlights or annotations. +- Clearing the selection clears both the overlay state and the controller's current selection. + + + + + +- Build and run `ReadViewDemo` on the simulator. +- Select text in a native reflowable sample and confirm the overlay is the visible selection surface. +- Trigger copy/highlight/annotate actions and confirm the controller still receives a valid selection payload. + + + +- Selection presentation is overlay-backed. +- Selection state still round-trips through absolute offsets. +- Reader interaction behavior remains stable for native text pages. + + diff --git a/.planning/phases/06-page-geometry-and-interaction-hit-layer/06-03-PLAN.md b/.planning/phases/06-page-geometry-and-interaction-hit-layer/06-03-PLAN.md new file mode 100644 index 0000000..bff47cf --- /dev/null +++ b/.planning/phases/06-page-geometry-and-interaction-hit-layer/06-03-PLAN.md @@ -0,0 +1,78 @@ +--- +phase: 6 +plan: 06-03 +type: execute +wave: 3 +depends_on: + - 06-01 + - 06-02 +files_modified: + - ReadViewDemo/ReadViewDemo/ViewController.swift + - Sources/RDReaderView/EPUBUI/RDEPUBReaderController.swift + - Sources/RDReaderView/EPUBUI/RDEPUBTextContentView.swift + - Sources/RDReaderView/EPUBCore/RDEPUBReadingModels.swift +autonomous: true +requirements: + - LAYOUT-01 + - LAYOUT-02 + - LAYOUT-03 +--- + +# Phase 6-03: Geometry Verification and Diagnostics + + +Expose concrete demo diagnostics for the new geometry and selection overlay path, then verify that page geometry, restore, search, and selection remain compatible on real sample books. + + + +- The demo can report geometry and selection evidence for a native reflowable page. +- Offset-based restore and page lookup continue to resolve the same content after geometry and overlay changes. +- Any geometry regression is visible in simulator logs or the demo status text. + + + + +execute +Add a geometry diagnostic hook to `RDEPUBReaderController` or `RDEPUBTextContentView` that reports the active page index, the selected absolute offset range, and the geometry summary for the current native page. Keep the diagnostic format deterministic so the demo can surface it in startup logs. + +- Sources/RDReaderView/EPUBUI/RDEPUBReaderController.swift +- Sources/RDReaderView/EPUBUI/RDEPUBTextContentView.swift +- Sources/RDReaderView/EPUBCore/RDEPUBReadingModels.swift +- Sources/RDReaderView/EPUBTextRendering/RDEPUBTextLayoutFrame.swift + + +- A runtime call can produce a geometry summary string for the current native page. +- The summary includes the selected absolute range or an explicit no-selection state. +- The summary is deterministic enough to compare across rebuilds on the same sample book. + + + + +execute +Extend `ReadViewDemo/ViewController.swift` startup validation so the native reflowable sample output includes the new geometry summary alongside the existing pagination and restore diagnostics. Keep the TXT and fixed/interactive matrix paths intact. + +- ReadViewDemo/ReadViewDemo/ViewController.swift +- Sources/RDReaderView/EPUBUI/RDEPUBReaderController.swift +- Sources/RDReaderView/EPUBTextRendering/RDEPUBTextBookBuilder.swift +- Sources/RDReaderView/EPUBCore/RDEPUBReadingModels.swift + + +- The simulator startup log includes a geometry/selection summary for at least one native reflowable sample. +- The existing sample validation matrix still reports the native, fixed/interactive, and TXT paths. +- Font or theme changes still preserve the same href and absolute-offset semantics in the restore diagnostic output. + + + + + +- Build and launch `ReadViewDemo` in the simulator. +- Open a native reflowable sample, select text, and confirm the geometry summary matches the overlay selection. +- Change font size or theme and confirm restore diagnostics still report stable href and offset behavior. + + + +- Geometry and overlay behavior are visible in the demo. +- Selection, restore, and sample validation remain compatible after the phase 6 changes. +- The phase produces reusable diagnostics for later phases without requiring a second demo shell. + + diff --git a/.planning/phases/06-page-geometry-and-interaction-hit-layer/06-PATTERNS.md b/.planning/phases/06-page-geometry-and-interaction-hit-layer/06-PATTERNS.md new file mode 100644 index 0000000..9c54fc1 --- /dev/null +++ b/.planning/phases/06-page-geometry-and-interaction-hit-layer/06-PATTERNS.md @@ -0,0 +1,39 @@ +# 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. + diff --git a/.planning/phases/06-page-geometry-and-interaction-hit-layer/06-RESEARCH.md b/.planning/phases/06-page-geometry-and-interaction-hit-layer/06-RESEARCH.md new file mode 100644 index 0000000..8516af4 --- /dev/null +++ b/.planning/phases/06-page-geometry-and-interaction-hit-layer/06-RESEARCH.md @@ -0,0 +1,45 @@ +# 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. + diff --git a/.planning/phases/06-page-geometry-and-interaction-hit-layer/06-VALIDATION.md b/.planning/phases/06-page-geometry-and-interaction-hit-layer/06-VALIDATION.md new file mode 100644 index 0000000..156a1f3 --- /dev/null +++ b/.planning/phases/06-page-geometry-and-interaction-hit-layer/06-VALIDATION.md @@ -0,0 +1,80 @@ +--- +phase: 6 +slug: page-geometry-and-interaction-hit-layer +status: draft +nyquist_compliant: true +wave_0_complete: false +created: 2026-05-22 +--- + +# Phase 6 — Validation Strategy + +> Per-phase validation contract for page geometry and selection overlay work. + +--- + +## Test Infrastructure + +| Property | Value | +|----------|-------| +| **Framework** | none — simulator build/run and manual UAT | +| **Config file** | none | +| **Quick run command** | `xcodebuild -workspace ReadViewDemo/ReadViewDemo.xcworkspace -scheme ReadViewDemo -configuration Debug -destination 'platform=iOS Simulator,name=iPhone 17' build` | +| **Full suite command** | `xcodebuild -workspace ReadViewDemo/ReadViewDemo.xcworkspace -scheme ReadViewDemo -configuration Debug -destination 'platform=iOS Simulator,name=iPhone 17' build && build_run_sim` | +| **Estimated runtime** | ~180 seconds | + +--- + +## Sampling Rate + +- After every task commit: run the quick build command. +- After every plan wave: run the full simulator build/run path and confirm reader startup. +- Before execution handoff: confirm the selection overlay and offset preservation checks below. +- Max feedback latency: 180 seconds. + +--- + +## Per-Task Verification Map + +| Task ID | Plan | Wave | Requirement | Threat Ref | Secure Behavior | Test Type | Automated Command | File Exists | Status | +|---------|------|------|-------------|------------|-----------------|-----------|-------------------|-------------|--------| +| 06-01-01 | 06-01 | 1 | LAYOUT-01 | — | N/A | build | `xcodebuild ... build` | ✅ | ⬜ pending | +| 06-01-02 | 06-01 | 1 | LAYOUT-03 | — | N/A | build | `xcodebuild ... build` | ✅ | ⬜ pending | +| 06-02-01 | 06-02 | 2 | LAYOUT-02 | — | N/A | simulator | `build_run_sim` | ✅ | ⬜ pending | +| 06-02-02 | 06-02 | 2 | LAYOUT-03 | — | N/A | simulator | `build_run_sim` | ✅ | ⬜ pending | +| 06-03-01 | 06-03 | 3 | LAYOUT-01 | — | N/A | manual | simulator inspection | ✅ | ⬜ pending | +| 06-03-02 | 06-03 | 3 | LAYOUT-02 | — | N/A | manual | simulator inspection | ✅ | ⬜ pending | +| 06-03-03 | 06-03 | 3 | LAYOUT-03 | — | N/A | manual | simulator inspection | ✅ | ⬜ pending | + +*Status: ⬜ pending · ✅ green · ❌ red · ⚠️ flaky* + +--- + +## Wave 0 Requirements + +- Existing build path covers the phase requirements; no new test target is required. +- Manual checks must be available in the demo app using the native text sample books. + +--- + +## Manual-Only Verifications + +| Behavior | Requirement | Why Manual | Test Instructions | +|----------|-------------|------------|-------------------| +| Selection overlay appears and tracks the selected text range | LAYOUT-02 | Overlay geometry is visible behavior, not a source-only assertion | Open a native text sample, select text, verify overlay bounds follow the selected text and not the default `UITextView` selection chrome | +| Selection still serializes through `RDEPUBTextOffsetRangeInfo` | LAYOUT-03 | Offset continuity is best verified through persisted selection state and runtime logs | Create a selection, refresh the page, and confirm restored selection points to the same absolute offsets | +| Geometry queries do not break page navigation / current location | LAYOUT-01 | Page geometry must be validated through runtime behavior and current-location flow | Move between pages, search, and restore location after repagination; confirm page mapping stays stable | + +--- + +## Validation Sign-Off + +- [ ] All tasks have `` or manual checks +- [ ] Sampling continuity: no 3 consecutive tasks without a build or simulator check +- [ ] Wave 0 covers missing infrastructure +- [ ] No watch-mode flags +- [ ] Feedback latency < 180s +- [ ] `nyquist_compliant: true` set in frontmatter + +**Approval:** pending +