107 lines
6.1 KiB
Markdown
107 lines
6.1 KiB
Markdown
---
|
||
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>
|