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

<objective>
用真实样本验证复杂块元素、图片与分页边界控制在新分页器下可工作，并确认 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.
</objective>

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

<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/
</context>

<tasks>

<task type="auto">
  <name>Task 1: 对真实 EPUB 暴露分页诊断并验证图片/块元素边界</name>
  <files>Sources/RDReaderView/EPUBTextRendering/RDEPUBTextBookBuilder.swift, Sources/RDReaderView/EPUBTextRendering/RDEPUBTextPaginationSupport.swift, ReadViewDemo/ReadViewDemo/ViewController.swift</files>
  <read_first>Sources/RDReaderView/EPUBTextRendering/RDEPUBTextBookBuilder.swift, Sources/RDReaderView/EPUBTextRendering/RDEPUBTextPaginationSupport.swift, ReadViewDemo/ReadViewDemo/ViewController.swift, ReadViewDemo/ReadViewDemo/book/</read_first>
  <action>基于现有 demo 样本书，为 stronger paginator 增加最小但可观察的分页诊断输出，至少能报告 page metadata / page break reason / image-or-block boundary evidence 中的一部分，并用 `ReadViewDemo/ReadViewDemo/book/` 的 reflowable EPUB 验证复杂块元素和图片没有回退到不可解释的纯 slicing 行为。不要新增并行 reader shell。</action>
  <acceptance_criteria>
    - 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
  </acceptance_criteria>
  <verify>rg -n "diagnostic|metadata|page break|attachment|image|block" Sources/RDReaderView/EPUBTextRendering ReadViewDemo/ReadViewDemo</verify>
  <done>sample books can demonstrate that new pagination semantics are active and inspectable.</done>
</task>

<task type="auto">
  <name>Task 2: 验证 offset-compatible 高亮/搜索页内映射没有退化</name>
  <files>Sources/RDReaderView/EPUBUI/RDEPUBTextContentView.swift, Sources/RDReaderView/EPUBTextRendering/RDEPUBTextBookBuilder.swift</files>
  <read_first>Sources/RDReaderView/EPUBUI/RDEPUBTextContentView.swift, Sources/RDReaderView/EPUBTextRendering/RDEPUBTextBookBuilder.swift, Sources/RDReaderView/EPUBTextRendering/RDEPUBTextSearchEngine.swift, Sources/RDReaderView/EPUBCore/RDEPUBReadingModels.swift</read_first>
  <action>确认 stronger paginator 产出的 page metadata 仍能支持 `RDEPUBTextContentView` 的 highlight/search overlap 计算和 `RDEPUBTextOffsetRangeInfo` 的绝对 offset 语义；如果需要，可补充最小的 source-level guard 或 diagnostics，但不要把兼容修复扩展成 Phase 4 的 reader reintegration。重点是验证 page-local presentation 依然能从 absolute chapter offsets 正确切出相对范围。</action>
  <acceptance_criteria>
    - `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
  </acceptance_criteria>
  <verify>rg -n "pageStartOffset|pageEndOffset|RDEPUBTextOffsetRangeInfo|rangeInfo|searchState" Sources/RDReaderView/EPUBUI/RDEPUBTextContentView.swift Sources/RDReaderView/EPUBTextRendering Sources/RDReaderView/EPUBCore</verify>
  <done>Phase 3 finishes with stronger pagination semantics and intact offset-based presentation compatibility.</done>
</task>

</tasks>

<verification>
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`
</verification>

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

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