ReadViewSDK/.planning/phases/03-page-metadata-pagination/03-03-PLAN.md

phase: 03-page-metadata-pagination plan: 03 type: execute wave: 3 depends_on: - "03-02" files_modified: - Sources/RDReaderView/EPUBTextRendering/RDEPUBTextBookBuilder.swift - Sources/RDReaderView/EPUBTextRendering/RDEPUBTextPaginationSupport.swift - Sources/RDReaderView/EPUBUI/RDEPUBTextContentView.swift - ReadViewDemo/ReadViewDemo/ViewController.swift autonomous: true requirements: - REND-03 - REND-04 user_setup: [] must_haves: truths: - sample EPUBs with images or large blocks can prove stronger page-edge semantics through real diagnostics, not only visual inspection. - offset-based highlight/search compatibility survives the stronger paginator. - the current demo app remains the validation entry point. artifacts: - .planning/phases/03-page-metadata-pagination/03-03-SUMMARY.md key_links: - ReadViewDemo/ReadViewDemo/book/ remains the regression corpus. - RDEPUBTextContentView still derives overlaps from pageStartOffset / pageEndOffset. 用真实样本验证复杂块元素、图片与分页边界控制在新分页器下可工作，并确认 offset-compatible highlight/search 行为没有被破坏。

Purpose: 证明 Phase 3 的 richer metadata 和 stronger paginator 不只是结构升级，而是能在真实 EPUB 上给出可解释、可回归的分页结果。 Output: demo-visible diagnostics, sample-book spot-check path, and source assertions around metadata + offset compatibility.

<execution_context> @$HOME/.codex/get-shit-done/workflows/execute-plan.md @$HOME/.codex/get-shit-done/templates/summary.md </execution_context>

@.planning/ROADMAP.md @.planning/STATE.md @.planning/phases/03-page-metadata-pagination/03-RESEARCH.md @.planning/phases/03-page-metadata-pagination/03-PATTERNS.md @.planning/phases/03-page-metadata-pagination/03-01-PLAN.md @.planning/phases/03-page-metadata-pagination/03-02-PLAN.md @Sources/RDReaderView/EPUBTextRendering/RDEPUBTextBookBuilder.swift @Sources/RDReaderView/EPUBTextRendering/RDEPUBTextPaginationSupport.swift @Sources/RDReaderView/EPUBUI/RDEPUBTextContentView.swift @ReadViewDemo/ReadViewDemo/ViewController.swift @ReadViewDemo/ReadViewDemo/book/ Task 1: 对真实 EPUB 暴露分页诊断并验证图片/块元素边界 Sources/RDReaderView/EPUBTextRendering/RDEPUBTextBookBuilder.swift, Sources/RDReaderView/EPUBTextRendering/RDEPUBTextPaginationSupport.swift, ReadViewDemo/ReadViewDemo/ViewController.swift Sources/RDReaderView/EPUBTextRendering/RDEPUBTextBookBuilder.swift, Sources/RDReaderView/EPUBTextRendering/RDEPUBTextPaginationSupport.swift, ReadViewDemo/ReadViewDemo/ViewController.swift, ReadViewDemo/ReadViewDemo/book/ 基于现有 demo 样本书，为 stronger paginator 增加最小但可观察的分页诊断输出，至少能报告 page metadata / page break reason / image-or-block boundary evidence 中的一部分，并用 `ReadViewDemo/ReadViewDemo/book/` 的 reflowable EPUB 验证复杂块元素和图片没有回退到不可解释的纯 slicing 行为。不要新增并行 reader shell。 - demo or runtime logs expose pagination diagnostics tied to the new metadata or page-break semantics - source tree still uses `ReadViewDemo/ReadViewDemo/ViewController.swift` as the validation entry point - `ReadViewDemo/ReadViewDemo/book` remains the sample corpus referenced by the validation path rg -n "diagnostic|metadata|page break|attachment|image|block" Sources/RDReaderView/EPUBTextRendering ReadViewDemo/ReadViewDemo sample books can demonstrate that new pagination semantics are active and inspectable. Task 2: 验证 offset-compatible 高亮/搜索页内映射没有退化 Sources/RDReaderView/EPUBUI/RDEPUBTextContentView.swift, Sources/RDReaderView/EPUBTextRendering/RDEPUBTextBookBuilder.swift Sources/RDReaderView/EPUBUI/RDEPUBTextContentView.swift, Sources/RDReaderView/EPUBTextRendering/RDEPUBTextBookBuilder.swift, Sources/RDReaderView/EPUBTextRendering/RDEPUBTextSearchEngine.swift, Sources/RDReaderView/EPUBCore/RDEPUBReadingModels.swift 确认 stronger paginator 产出的 page metadata 仍能支持 `RDEPUBTextContentView` 的 highlight/search overlap 计算和 `RDEPUBTextOffsetRangeInfo` 的绝对 offset 语义；如果需要，可补充最小的 source-level guard 或 diagnostics，但不要把兼容修复扩展成 Phase 4 的 reader reintegration。重点是验证 page-local presentation 依然能从 absolute chapter offsets 正确切出相对范围。 - `RDEPUBTextContentView` still computes overlaps from `pageStartOffset` / `pageEndOffset` - `RDEPUBTextOffsetRangeInfo` remains decodable and tied to absolute chapter offsets - no code path replaces highlight/search overlap logic with page-local-only identifiers rg -n "pageStartOffset|pageEndOffset|RDEPUBTextOffsetRangeInfo|rangeInfo|searchState" Sources/RDReaderView/EPUBUI/RDEPUBTextContentView.swift Sources/RDReaderView/EPUBTextRendering Sources/RDReaderView/EPUBCore Phase 3 finishes with stronger pagination semantics and intact offset-based presentation compatibility. Before declaring plan complete: - [ ] `test -d ReadViewDemo/ReadViewDemo/book` - [ ] `rg -n "diagnostic|metadata|page break|attachment|image|block" Sources/RDReaderView ReadViewDemo/ReadViewDemo` - [ ] `rg -n "pageStartOffset|pageEndOffset|RDEPUBTextOffsetRangeInfo|rangeInfo" Sources/RDReaderView/EPUBUI/RDEPUBTextContentView.swift Sources/RDReaderView/EPUBTextRendering Sources/RDReaderView/EPUBCore`

<success_criteria>

• All tasks completed
• All verification checks pass
• sample books prove stronger paginator behavior is both active and inspectable
• offset-based highlight/search presentation compatibility remains intact for Phase 4 handoff

</success_criteria>

After completion, create `.planning/phases/03-page-metadata-pagination/03-03-SUMMARY.md`