---
phase: 7
plan: 07-02
type: execute
wave: 2
depends_on:
  - 07-01
files_modified:
  - Sources/RDReaderView/EPUBTextRendering/RDEPUBTextLayouter.swift
  - Sources/RDReaderView/EPUBTextRendering/RDEPUBTextLayoutFrame.swift
  - Sources/RDReaderView/EPUBTextRendering/RDEPUBTextBookBuilder.swift
  - Sources/RDReaderView/EPUBCore/RDEPUBReadingModels.swift
autonomous: true
requirements:
  - ATTR-01
  - ATTR-02
  - ATTR-03
---

# Phase 7-02: 分页器消费与页级元数据接线

<objective>
让 native text 分页器与页级元数据真正消费 Phase 7 的自定义语义，使块分类、附件语义和分页 hint 能影响分页边界决策并保留到 page metadata。
</objective>

<must_haves>
- `avoidPageBreakInside`、`pageBreakBefore`、`pageBreakAfter` 不只是“记录下来”，而是能进入分页边界决策或分页诊断。
- 图片/附件的垂直居中等语义必须被保留到 page metadata 或可消费结构中。
- 块类型需要进入 page/frame 级诊断，使 `table / code / list / blockquote` 能被区分。
</must_haves>

<tasks>
<task id="07-02-01">
<type>execute</type>
<action>扩展 `RDEPUBTextLayouter` 与 `RDEPUBTextLayoutFrame`，在现有 attachment boundary / block boundary 逻辑上接入分页 hint：处理强制分页前后断点、avoid-break 优先回退，以及附件语义对边界选择的影响。需要同时把命中的规则写进 diagnostics，避免变成不可解释的隐式行为。</action>
<read_first>
- Sources/RDReaderView/EPUBTextRendering/RDEPUBTextLayouter.swift
- Sources/RDReaderView/EPUBTextRendering/RDEPUBTextLayoutFrame.swift
- Sources/RDReaderView/EPUBTextRendering/RDEPUBTextRendererSupport.swift
- .planning/phases/07-wxread/07-RESEARCH.md
</read_first>
<acceptance_criteria>
- 命中的 `pageBreakBefore` / `pageBreakAfter` / `avoidPageBreakInside` 规则会改变 break 决策或至少改变诊断结果，不能完全无效。
- 分页 diagnostics 能说明当前页面为何提前断页、避免断页或跟随附件边界调整。
- 现有 page offset 兼容语义不回归，native text 仍能完成章节分页。
</acceptance_criteria>
</task>

<task id="07-02-02">
<type>execute</type>
<action>在 `RDEPUBTextBookBuilder` 与 `RDEPUBReadingModels.swift` 中提升并暴露新的页级语义元数据，包括块类型摘要、附件垂直居中/附件分页语义、强制分页命中信息与复杂块分页诊断。保证 chapter/page 级诊断输出对 Demo 和后续回归可复用。</action>
<read_first>
- Sources/RDReaderView/EPUBTextRendering/RDEPUBTextBookBuilder.swift
- Sources/RDReaderView/EPUBCore/RDEPUBReadingModels.swift
- Sources/RDReaderView/EPUBTextRendering/RDEPUBTextLayoutFrame.swift
- Sources/RDReaderView/EPUBTextRendering/RDEPUBTextLayouter.swift
</read_first>
<acceptance_criteria>
- `RDEPUBTextPageMetadata` 或其配套结构能表达块类型、附件语义和分页 hint 命中摘要。
- `RDEPUBTextChapterPaginationDiagnostic` 能输出至少一组与 Phase 7 语义直接相关的诊断信息。
- 图片/附件语义不会在 attributed string → layouter → page metadata 这条链路中丢失。
</acceptance_criteria>
</task>
</tasks>

<verification>
- Build and run `ReadViewDemo` on the simulator.
- 打开包含图片和复杂块元素的 native reflowable 样本，确认分页完成且 diagnostics 中能看见新语义。
- 对比分页前后 page count、offset 映射与现有 restore/search 路径，确认没有基础回归。
</verification>

<success_criteria>
- 自定义分页语义被分页器实际消费。
- 页级元数据可以解释复杂块和附件的分页行为。
- Phase 8 可以在不重复定义语义的前提下继续优化分页质量与附件规则。
</success_criteria>