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

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. 定义页面级 attributed string 元数据与自定义属性键，为 Phase 3 的复杂分页器建立稳定数据契约。

Purpose: 先把“页面语义到底长什么样”固定下来，再让 paginator 和验证围绕这套契约扩展，而不是在分页逻辑里临时发明结构。 Output: richer page/chapter metadata models、attribute key definitions，以及保持 offset continuity 的序列化/传递路径。

<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/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 Task 1: 定义页面元数据与 attributed string 属性键 Sources/RDReaderView/EPUBCore/RDEPUBReadingModels.swift, Sources/RDReaderView/EPUBTextRendering/RDEPUBTextRenderer.swift Sources/RDReaderView/EPUBCore/RDEPUBReadingModels.swift, Sources/RDReaderView/EPUBTextRendering/RDEPUBTextRenderer.swift, Sources/RDReaderView/EPUBUI/RDEPUBTextContentView.swift 在现有 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` 等现有兼容字段。 - `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 rg -n "metadata|attachment|block|pageBreak|pageStartOffset|pageEndOffset|fragmentOffsets" Sources/RDReaderView/EPUBCore/RDEPUBReadingModels.swift Sources/RDReaderView/EPUBTextRendering/RDEPUBTextRenderer.swift native text pipeline now has an explicit metadata vocabulary that later pagination and validation steps can consume. Task 2: 扩展 chapter/page model 以承接新语义但保留 offset continuity Sources/RDReaderView/EPUBTextRendering/RDEPUBTextBookBuilder.swift, Sources/RDReaderView/EPUBTextRendering/RDEPUBTextPaginationSupport.swift Sources/RDReaderView/EPUBTextRendering/RDEPUBTextBookBuilder.swift, Sources/RDReaderView/EPUBTextRendering/RDEPUBTextPaginationSupport.swift, Sources/RDReaderView/EPUBCore/RDEPUBReadingSession.swift, Sources/RDReaderView/EPUBTextRendering/RDEPUBTextSearchEngine.swift 把 `RDEPUBTextChapter` 和 `RDEPUBTextPage` 扩展成可承接新 metadata 的模型，同时保留 `RDEPUBTextBook.pageNumber(for:)`、`location(forPageNumber:)`、search/highlight 所依赖的 offset continuity。若需要新增 page-slice carrier（例如 layout snapshot 或 page metadata payload），它必须最终落回 `RDEPUBTextPage`，不能绕开现有 `RDEPUBTextBook` 契约。 - `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 rg -n "struct RDEPUBTextPage|struct RDEPUBTextChapter|pageStartOffset|pageEndOffset|fragmentOffsets|metadata" Sources/RDReaderView/EPUBTextRendering/RDEPUBTextBookBuilder.swift the page model is richer, but all current consumers still have a stable offset-based contract to target. 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`

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

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