feat(07): close native text pagination semantics loop

2026-05-22 20:39:26 +08:00
parent 21c8bbb23a
commit d7339aa255
15 changed files with 722 additions and 22 deletions
@@ -0,0 +1,20 @@
+---
+phase: 7
+plan: 07-01
+status: complete
+requirements-completed:
+  - ATTR-01
+  - ATTR-03
+updated: 2026-05-22
+---
+
+# 07-01 Summary
+
+- Added explicit native-text semantic types and attributed-string keys for block kinds, pagination hints, and attachment placement.
+- Extended chapter preprocessing to inject semantic markers for WXRead-style hints such as `avoidPageBreakInside`, `pageBreakBefore`, `pageBreakAfter`, `pageRelate`, and image/body block semantics.
+- Renderer post-processing now strips those markers and applies real attributes before fragment-offset extraction, so semantic metadata is preserved without breaking the existing offset contract.
+
+## Verification
+
+- `build_sim` for `ReadViewDemo` on iOS Simulator succeeded on 2026-05-22.
+
@@ -0,0 +1,21 @@
+---
+phase: 7
+plan: 07-02
+status: complete
+requirements-completed:
+  - ATTR-01
+  - ATTR-02
+  - ATTR-03
+updated: 2026-05-22
+---
+
+# 07-02 Summary
+
+- Taught `RDEPUBTextLayouter` to consume semantic hints and emit `semanticBoundary` breaks when explicit page-break or avoid-break rules should influence pagination.
+- Expanded page metadata and layout frames to retain block kinds, semantic hints, and attachment placements alongside the existing attachment and break diagnostics.
+- Propagated the richer pagination diagnostics through `RDEPUBTextBookBuilder` and `RDPlainTextBookBuilder`, so chapter summaries can now explain attachment-heavy and block-sensitive pagination behavior.
+
+## Verification
+
+- `build_sim` for `ReadViewDemo` on iOS Simulator succeeded on 2026-05-22.
+
@@ -0,0 +1,23 @@
+---
+phase: 7
+plan: 07-03
+status: complete
+requirements-completed:
+  - ATTR-01
+  - ATTR-02
+  - ATTR-03
+updated: 2026-05-22
+---
+
+# 07-03 Summary
+
+- Added reusable semantic diagnostic summaries on `RDEPUBTextBookBuilder` and `RDEPUBReaderController` for the native text path.
+- Updated `ReadViewDemo` startup validation to prioritize a Phase 7 semantic-closure line and a pagination line from native reflowable samples.
+- Verified the simulator runtime log now surfaces explicit semantic evidence for a real sample book, rather than only generic sample-matrix output.
+
+## Verification
+
+- `build_run_sim` for `ReadViewDemo` on iPhone 17 (iOS 26.5 simulator) succeeded on 2026-05-22.
+- Runtime log included `属性闭环诊断：宝山辽墓材料与释读 · 章节 10 · block kinds [attachment,paragraph] · placements [inline,centered] · block kinds: attachment`.
+- Runtime log included `分页诊断：宝山辽墓材料与释读 · 章节 10 · attachment 页 54 · semantic break 页 57 · block kinds [attachment,paragraph] · placements [inline,centered] · reasons [attachmentBoundary:31, blockBoundary:26, frameLimit:17, chapterEnd:4] · page break: blockBoundary`.
+
@@ -0,0 +1,35 @@
+---
+phase: 7
+status: passed
+requirements-verified:
+  - ATTR-01
+  - ATTR-02
+  - ATTR-03
+updated: 2026-05-22
+---
+
+# Phase 7 Verification
+
+## Result
+
+Passed.
+
+## What Was Verified
+
+- HTML/CSS pagination semantics now survive the native text pipeline as explicit attributed-string metadata.
+- Paginator and page metadata consume those semantics and expose them in break reasons and diagnostics.
+- Demo startup validation surfaces semantic-closure evidence for a native reflowable sample book.
+
+## Evidence
+
+- `build_sim` for `ReadViewDemo` succeeded after the semantic extraction and layouter-consumption changes.
+- `build_run_sim` for `ReadViewDemo` succeeded on iPhone 17 (iOS 26.5 simulator).
+- Runtime log surfaced:
+  - `属性闭环诊断：宝山辽墓材料与释读 · 章节 10 · block kinds [attachment,paragraph] · placements [inline,centered] · block kinds: attachment`
+  - `分页诊断：宝山辽墓材料与释读 · 章节 10 · attachment 页 54 · semantic break 页 57 · block kinds [attachment,paragraph] · placements [inline,centered] · reasons [attachmentBoundary:31, blockBoundary:26, frameLimit:17, chapterEnd:4] · page break: blockBoundary`
+
+## Residual Risk
+
+- Current semantic extraction is intentionally conservative and heuristic-driven; future EPUB variants may require additional tag/class/style mappings in Phase 8.
+- The sample evidence currently proves attachment and paragraph semantics clearly; richer code/list/table/blockquote samples should continue to be exercised as later phases tighten quality and automation.
+