106 lines
6.5 KiB
Markdown
106 lines
6.5 KiB
Markdown
---
|
||
phase: 03-page-metadata-pagination
|
||
plan: 01
|
||
type: execute
|
||
wave: 1
|
||
depends_on: []
|
||
files_modified:
|
||
- Sources/RDReaderView/EPUBCore/RDEPUBReadingModels.swift
|
||
- Sources/RDReaderView/EPUBTextRendering/RDEPUBTextRenderer.swift
|
||
- Sources/RDReaderView/EPUBTextRendering/RDEPUBTextBookBuilder.swift
|
||
- Sources/RDReaderView/EPUBTextRendering/RDEPUBTextPaginationSupport.swift
|
||
autonomous: true
|
||
requirements:
|
||
- REND-03
|
||
user_setup: []
|
||
must_haves:
|
||
truths:
|
||
- `RDEPUBTextPage` / `RDEPUBTextChapter` gain explicit page metadata hooks for blocks, attachments, and page-edge reasoning.
|
||
- `pageStartOffset`, `pageEndOffset`, chapter text continuity, and fragment offsets remain first-class compatibility fields.
|
||
- new metadata is serializable or structurally accessible from current native rendering models rather than hidden inside temporary layout locals.
|
||
artifacts:
|
||
- .planning/phases/03-page-metadata-pagination/03-01-SUMMARY.md
|
||
key_links:
|
||
- `RDEPUBTextOffsetRangeInfo` remains compatible with absolute chapter offsets.
|
||
- `RDEPUBTextBookBuilder` stays the owner of chapter/page assembly.
|
||
---
|
||
|
||
<objective>
|
||
定义页面级 attributed string 元数据与自定义属性键，为 Phase 3 的复杂分页器建立稳定数据契约。
|
||
|
||
Purpose: 先把“页面语义到底长什么样”固定下来，再让 paginator 和验证围绕这套契约扩展，而不是在分页逻辑里临时发明结构。
|
||
Output: richer page/chapter metadata models、attribute key definitions，以及保持 offset continuity 的序列化/传递路径。
|
||
</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/REQUIREMENTS.md
|
||
@.planning/phases/01-current-engine-boundaries/01-refactor-entry-strategy.md
|
||
@.planning/phases/02-typesetter-css/02-RESEARCH.md
|
||
@.planning/phases/03-page-metadata-pagination/03-RESEARCH.md
|
||
@.planning/phases/03-page-metadata-pagination/03-PATTERNS.md
|
||
@Sources/RDReaderView/EPUBCore/RDEPUBReadingModels.swift
|
||
@Sources/RDReaderView/EPUBTextRendering/RDEPUBTextRenderer.swift
|
||
@Sources/RDReaderView/EPUBTextRendering/RDEPUBTextBookBuilder.swift
|
||
@Sources/RDReaderView/EPUBTextRendering/RDEPUBTextPaginationSupport.swift
|
||
@Sources/RDReaderView/EPUBUI/RDEPUBTextContentView.swift
|
||
</context>
|
||
|
||
<tasks>
|
||
|
||
<task type="auto">
|
||
<name>Task 1: 定义页面元数据与 attributed string 属性键</name>
|
||
<files>Sources/RDReaderView/EPUBCore/RDEPUBReadingModels.swift, Sources/RDReaderView/EPUBTextRendering/RDEPUBTextRenderer.swift</files>
|
||
<read_first>Sources/RDReaderView/EPUBCore/RDEPUBReadingModels.swift, Sources/RDReaderView/EPUBTextRendering/RDEPUBTextRenderer.swift, Sources/RDReaderView/EPUBUI/RDEPUBTextContentView.swift</read_first>
|
||
<action>在现有 native text 模型旁定义 page metadata 契约和 attributed string 语义键，至少覆盖 block boundary、attachment/image semantic、page break reason、future page style hook 这几类能力；把它们放在 `RDEPUBReadingModels.swift` 或与之紧邻的 native rendering 模型里，并保持 `RDEPUBTextOffsetRangeInfo` 继续基于绝对 chapter offsets 工作。不要删除或弱化 `pageStartOffset`、`pageEndOffset`、`fragmentOffsets`、`href` 等现有兼容字段。</action>
|
||
<acceptance_criteria>
|
||
- `Sources/RDReaderView/EPUBCore/RDEPUBReadingModels.swift` contains new page metadata types or fields for block / attachment / page break semantics
|
||
- `Sources/RDReaderView/EPUBTextRendering/RDEPUBTextRenderer.swift` or adjacent rendering models contain explicit native metadata/attribute-key definitions
|
||
- `RDEPUBTextOffsetRangeInfo` remains present and still serializes absolute offset ranges
|
||
</acceptance_criteria>
|
||
<verify>rg -n "metadata|attachment|block|pageBreak|pageStartOffset|pageEndOffset|fragmentOffsets" Sources/RDReaderView/EPUBCore/RDEPUBReadingModels.swift Sources/RDReaderView/EPUBTextRendering/RDEPUBTextRenderer.swift</verify>
|
||
<done>native text pipeline now has an explicit metadata vocabulary that later pagination and validation steps can consume.</done>
|
||
</task>
|
||
|
||
<task type="auto">
|
||
<name>Task 2: 扩展 chapter/page model 以承接新语义但保留 offset continuity</name>
|
||
<files>Sources/RDReaderView/EPUBTextRendering/RDEPUBTextBookBuilder.swift, Sources/RDReaderView/EPUBTextRendering/RDEPUBTextPaginationSupport.swift</files>
|
||
<read_first>Sources/RDReaderView/EPUBTextRendering/RDEPUBTextBookBuilder.swift, Sources/RDReaderView/EPUBTextRendering/RDEPUBTextPaginationSupport.swift, Sources/RDReaderView/EPUBCore/RDEPUBReadingSession.swift, Sources/RDReaderView/EPUBTextRendering/RDEPUBTextSearchEngine.swift</read_first>
|
||
<action>把 `RDEPUBTextChapter` 和 `RDEPUBTextPage` 扩展成可承接新 metadata 的模型，同时保留 `RDEPUBTextBook.pageNumber(for:)`、`location(forPageNumber:)`、search/highlight 所依赖的 offset continuity。若需要新增 page-slice carrier（例如 layout snapshot 或 page metadata payload），它必须最终落回 `RDEPUBTextPage`，不能绕开现有 `RDEPUBTextBook` 契约。</action>
|
||
<acceptance_criteria>
|
||
- `RDEPUBTextPage` includes explicit metadata payloads or fields beyond bare range/offsets
|
||
- `RDEPUBTextBook.pageNumber(for:)` and `location(forPageNumber:)` still use offset-compatible fields
|
||
- source code still contains `pageStartOffset`, `pageEndOffset`, and `fragmentOffsets` after the refactor
|
||
</acceptance_criteria>
|
||
<verify>rg -n "struct RDEPUBTextPage|struct RDEPUBTextChapter|pageStartOffset|pageEndOffset|fragmentOffsets|metadata" Sources/RDReaderView/EPUBTextRendering/RDEPUBTextBookBuilder.swift</verify>
|
||
<done>the page model is richer, but all current consumers still have a stable offset-based contract to target.</done>
|
||
</task>
|
||
|
||
</tasks>
|
||
|
||
<verification>
|
||
Before declaring plan complete:
|
||
- [ ] `rg -n "metadata|attachment|block|pageBreak" Sources/RDReaderView/EPUBCore/RDEPUBReadingModels.swift Sources/RDReaderView/EPUBTextRendering`
|
||
- [ ] `rg -n "pageStartOffset|pageEndOffset|fragmentOffsets" Sources/RDReaderView/EPUBTextRendering/RDEPUBTextBookBuilder.swift Sources/RDReaderView/EPUBCore/RDEPUBReadingModels.swift`
|
||
- [ ] no changes route page presentation around `RDEPUBTextBook`
|
||
</verification>
|
||
|
||
<success_criteria>
|
||
|
||
- All tasks completed
|
||
- All verification checks pass
|
||
- No compatibility field needed by highlight/search/navigation is removed
|
||
- Phase 3.2 can consume the metadata contract without redefining the page model again
|
||
|
||
</success_criteria>
|
||
|
||
<output>
|
||
After completion, create `.planning/phases/03-page-metadata-pagination/03-01-SUMMARY.md`
|
||
</output>
|