107 lines
6.1 KiB
Markdown
107 lines
6.1 KiB
Markdown
---
|
||
phase: 03-page-metadata-pagination
|
||
plan: 02
|
||
type: execute
|
||
wave: 2
|
||
depends_on:
|
||
- "03-01"
|
||
files_modified:
|
||
- Sources/RDReaderView/EPUBTextRendering/RDEPUBTextPaginationSupport.swift
|
||
- Sources/RDReaderView/EPUBTextRendering/RDEPUBTextBookBuilder.swift
|
||
- Sources/RDReaderView/EPUBTextRendering/RDEPUBTextLayouter.swift
|
||
- Sources/RDReaderView/EPUBTextRendering/RDEPUBTextLayoutFrame.swift
|
||
autonomous: true
|
||
requirements:
|
||
- REND-03
|
||
- REND-04
|
||
user_setup: []
|
||
must_haves:
|
||
truths:
|
||
- pagination is no longer implemented as only `CTFrameGetVisibleStringRange` range slicing.
|
||
- layouter/layout-frame responsibilities live inside `EPUBTextRendering`, not in reader UI classes.
|
||
- stronger page edges still resolve to stable `RDEPUBTextPage` offsets and chapter continuity.
|
||
artifacts:
|
||
- .planning/phases/03-page-metadata-pagination/03-02-SUMMARY.md
|
||
key_links:
|
||
- `RDEPUBTextPaginationSupport` remains the entry point for native pagination work.
|
||
- `RDEPUBTextBookBuilder` still assembles final pages and chapters.
|
||
---
|
||
|
||
<objective>
|
||
在旧引擎基础上重构分页器，引入内部 layouter / layout-frame 语义，并把纯 visible-range slicing 升级为更强的页面边界控制。
|
||
|
||
Purpose: 让 native paginator 能表达 block / image / attachment 的页面边界语义，同时不破坏现有 page model 与 chapter offset continuity。
|
||
Output: stronger paginator implementation, internal layouter/frame types, and book-builder wiring onto the new pagination path.
|
||
</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/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
|
||
@Sources/RDReaderView/EPUBTextRendering/RDEPUBTextPaginationSupport.swift
|
||
@Sources/RDReaderView/EPUBTextRendering/RDEPUBTextBookBuilder.swift
|
||
@Sources/RDReaderView/EPUBCore/RDEPUBReadingSession.swift
|
||
@Sources/RDReaderView/EPUBUI/RDEPUBTextContentView.swift
|
||
</context>
|
||
|
||
<tasks>
|
||
|
||
<task type="auto">
|
||
<name>Task 1: 引入 layouter / layout-frame 语义并升级分页入口</name>
|
||
<files>Sources/RDReaderView/EPUBTextRendering/RDEPUBTextPaginationSupport.swift, Sources/RDReaderView/EPUBTextRendering/RDEPUBTextLayouter.swift, Sources/RDReaderView/EPUBTextRendering/RDEPUBTextLayoutFrame.swift</files>
|
||
<read_first>Sources/RDReaderView/EPUBTextRendering/RDEPUBTextPaginationSupport.swift, Sources/RDReaderView/EPUBTextRendering/RDEPUBTextBookBuilder.swift, .planning/phases/01-current-engine-boundaries/01-refactor-entry-strategy.md</read_first>
|
||
<action>把当前 `ss_pageRanges(size:)` 的纯 range slicing 入口升级成内部 layouter / layout-frame 驱动的分页路径；新路径至少要能表达 page break reason、block boundary avoidance、image/attachment boundary handling 这三类语义。新增类型应放在 `EPUBTextRendering` 内部，例如 `RDEPUBTextLayouter` / `RDEPUBTextLayoutFrame`，并由 `RDEPUBTextPaginationSupport` 调用，而不是把复杂分页逻辑堆到 UI controller 里。</action>
|
||
<acceptance_criteria>
|
||
- `Sources/RDReaderView/EPUBTextRendering` contains layouter/frame types or equivalent internal pagination structures
|
||
- paginator code contains semantics beyond plain `CTFrameGetVisibleStringRange` slicing
|
||
- source tree does not move pagination logic into `RDEPUBReaderController` or `RDEPUBTextContentView`
|
||
</acceptance_criteria>
|
||
<verify>rg -n "Layouter|LayoutFrame|pageBreak|attachment|avoid|CTFrameGetVisibleStringRange|CTTypesetter" Sources/RDReaderView/EPUBTextRendering</verify>
|
||
<done>native pagination now has a real internal layout vocabulary rather than one visible-range helper.</done>
|
||
</task>
|
||
|
||
<task type="auto">
|
||
<name>Task 2: 把更强分页结果接回 `RDEPUBTextBookBuilder` 与现有页模型</name>
|
||
<files>Sources/RDReaderView/EPUBTextRendering/RDEPUBTextBookBuilder.swift</files>
|
||
<read_first>Sources/RDReaderView/EPUBTextRendering/RDEPUBTextBookBuilder.swift, Sources/RDReaderView/EPUBCore/RDEPUBReadingSession.swift, Sources/RDReaderView/EPUBTextRendering/RDEPUBTextSearchEngine.swift, Sources/RDReaderView/EPUBUI/RDEPUBTextContentView.swift</read_first>
|
||
<action>让 `RDEPUBTextBookBuilder` 消费新分页结果并把 page-level metadata 落到 `RDEPUBTextPage` / `RDEPUBTextChapter` 上，同时保持 `pageStartOffset` / `pageEndOffset`、chapter order、fragmentOffsets 和 search/highlight overlap 逻辑不变。需要时可以在 builder 内转换 layouter output，但最终输出仍必须是当前 `RDEPUBTextBook` 契约，而不是新的 UI-only page list。</action>
|
||
<acceptance_criteria>
|
||
- `RDEPUBTextBookBuilder` constructs pages from the upgraded pagination output rather than raw `ss_pageRanges(size:)` only
|
||
- page model assembly still emits `RDEPUBTextBook(chapters:pages:)`
|
||
- search/highlight/navigation dependent fields remain present in the built pages
|
||
</acceptance_criteria>
|
||
<verify>rg -n "RDEPUBTextBook\\(|pageStartOffset|pageEndOffset|fragmentOffsets|metadata|layout" Sources/RDReaderView/EPUBTextRendering/RDEPUBTextBookBuilder.swift</verify>
|
||
<done>the richer paginator is wired back into the existing native book contract and remains consumable by later reader phases.</done>
|
||
</task>
|
||
|
||
</tasks>
|
||
|
||
<verification>
|
||
Before declaring plan complete:
|
||
- [ ] `test -f Sources/RDReaderView/EPUBTextRendering/RDEPUBTextPaginationSupport.swift`
|
||
- [ ] `rg -n "Layouter|LayoutFrame|pageBreak|attachment|avoid" Sources/RDReaderView/EPUBTextRendering`
|
||
- [ ] `rg -n "RDEPUBTextBook\\(|pageStartOffset|pageEndOffset|fragmentOffsets" Sources/RDReaderView/EPUBTextRendering/RDEPUBTextBookBuilder.swift`
|
||
</verification>
|
||
|
||
<success_criteria>
|
||
|
||
- All tasks completed
|
||
- All verification checks pass
|
||
- paginator semantics are meaningfully stronger than pure visible-range slicing
|
||
- output still flows through the existing native text book/page model
|
||
|
||
</success_criteria>
|
||
|
||
<output>
|
||
After completion, create `.planning/phases/03-page-metadata-pagination/03-02-SUMMARY.md`
|
||
</output>
|