chore: checkpoint current milestone work

.planning/ROADMAP.md

@@ -7,10 +7,10 @@
 ## Phases
 
 - [x] **Phase 1: 对齐现状、边界与重构切入点** - 明确当前旧引擎的真实调用链、分流边界与必须保留的兼容能力 (completed 2026-05-21)
-- [ ] **Phase 2: 重构 typesetter 与 CSS 分层** - 在旧引擎基础上引入 WXRead 风格样式组织与章节级 HTML → attributed string 转换增强
-- [ ] **Phase 3: 重构属性体系与复杂分页器** - 引入页面级 attributed string 元数据与更强的分页/布局能力
-- [ ] **Phase 4: 接回现有 reader 能力链路** - 让新内核与阅读位置、高亮、搜索、主题切换等现有功能继续协作
-- [ ] **Phase 5: 回归验证与稳定性收敛** - 以样本书和主流程为核心完成回归、修复与验收
+- [x] **Phase 2: 重构 typesetter 与 CSS 分层** - 在旧引擎基础上引入 WXRead 风格样式组织与章节级 HTML → attributed string 转换增强 (completed 2026-05-22)
+- [x] **Phase 3: 重构属性体系与复杂分页器** - 引入页面级 attributed string 元数据与更强的分页/布局能力 (completed 2026-05-22)
+- [x] **Phase 4: 接回现有 reader 能力链路** - 让新内核与阅读位置、高亮、搜索、主题切换等现有功能继续协作 (completed 2026-05-22)
+- [x] **Phase 5: 回归验证与稳定性收敛** - 以样本书和主流程为核心完成回归、修复与验收 (completed 2026-05-22)
 
 ## Phase Details
 
@@ -40,9 +40,9 @@ Plans:
 **Plans**: 3 plans
 
 Plans:
-- [ ] 02-01：设计并实现旧引擎中的 WXRead 风格 stylesheet builder / HTML 预处理增强
-- [ ] 02-02：改造 `RDEPUBDTCoreTextRenderer` 与相邻渲染链路，使其承接新的样式分层与章节上下文
-- [ ] 02-03：验证章节级图片/CSS/基础资源在新渲染输入下可正常解析
+- [x] 02-01：设计并实现旧引擎中的 WXRead 风格 stylesheet builder / HTML 预处理增强
+- [x] 02-02：改造 `RDEPUBDTCoreTextRenderer` 与相邻渲染链路，使其承接新的样式分层与章节上下文
+- [x] 02-03：验证章节级图片/CSS/基础资源在新渲染输入下可正常解析
 
 ### Phase 3: 重构属性体系与复杂分页器
 **Goal**: 在旧引擎路径中引入页面级 attributed string 元数据与更复杂的分页/页面布局能力，替代当前简单 `pageRanges` 切页模式。  
@@ -55,9 +55,18 @@ Plans:
 **Plans**: 3 plans
 
 Plans:
-- [ ] 03-01：定义并实现页面级 attributed string 元数据与自定义属性键
-- [ ] 03-02：在旧引擎基础上重构分页器，使其具备接近 `WRCoreTextLayouter / WRCoreTextLayoutFrame` 的核心能力
-- [ ] 03-03：验证复杂块元素、图片与分页边界控制在新分页器下可工作
+**Wave 1**
+- [x] 03-01：定义并实现页面级 attributed string 元数据与自定义属性键
+
+**Wave 2** *(blocked on Wave 1 completion)*
+- [x] 03-02：在旧引擎基础上重构分页器，使其具备接近 `WRCoreTextLayouter / WRCoreTextLayoutFrame` 的核心能力
+
+**Wave 3** *(blocked on Wave 2 completion)*
+- [x] 03-03：验证复杂块元素、图片与分页边界控制在新分页器下可工作
+
+Cross-cutting constraints:
+- `pageStartOffset`、`pageEndOffset`、chapter text continuity、`fragmentOffsets` 必须保持为稳定兼容字段
+- 不修改 `RDReaderView`，不碰 fixed / interactive `WKWebView` 路径
 
 ### Phase 4: 接回现有 reader 能力链路
 **Goal**: 让新内核在不新增并行原生引擎、且不修改当前翻页代码的前提下，继续服务现有 reader UI、阅读位置、高亮、搜索与主题切换能力。  
@@ -71,9 +80,14 @@ Plans:
 **Plans**: 3 plans
 
 Plans:
-- [ ] 04-01：将新内核接回 `RDEPUBTextBookBuilder` / `RDEPUBTextContentView` / `RDEPUBReaderController`，不修改 `RDReaderView`
-- [ ] 04-02：修复并验证阅读位置映射、高亮、搜索等兼容能力
-- [ ] 04-03：验证字体、行高、主题切换后的重新分页与状态恢复
+- [x] 04-01：将新内核接回 `RDEPUBTextBookBuilder` / `RDEPUBTextContentView` / `RDEPUBReaderController`，不修改 `RDReaderView`
+- [x] 04-02：修复并验证阅读位置映射、高亮、搜索等兼容能力
+- [x] 04-03：验证字体、行高、主题切换后的重新分页与状态恢复
+
+Cross-cutting constraints:
+- `RDReaderView` 继续只作为现有翻页容器使用，不承接新的 native page metadata 责任
+- native text 兼容能力必须继续围绕 `RDEPUBLocation`、`pageStartOffset` / `pageEndOffset`、`RDEPUBTextOffsetRangeInfo` 工作
+- 主题 / 字号 / 行高 / viewport 变化后的恢复应以 semantic location 为主，而不是 page number
 
 ### Phase 5: 回归验证与稳定性收敛
 **Goal**: 围绕样本书和主流程做回归，收敛分页正确性、位置映射稳定性与关键阅读交互问题。  
@@ -86,15 +100,20 @@ Plans:
 **Plans**: 2 plans
 
 Plans:
-- [ ] 05-01：构建样本书验证矩阵与诊断手段（日志/断言/复现清单）
-- [ ] 05-02：收敛分页、位置映射、图片/块元素分页与主题切换后的稳定性问题
+- [x] 05-01：构建样本书验证矩阵与诊断手段（日志/断言/复现清单）
+- [x] 05-02：收敛分页、位置映射、图片/块元素分页与主题切换后的稳定性问题
+
+Cross-cutting constraints:
+- Phase 5 以验证和收敛修复为主，不重新打开更大范围的架构改造
+- 样本矩阵必须覆盖 native reflowable、fixed/interactive WebKit 路径，以及 TXT 兼容路径
+- 每项回归结论都应尽量附着到可重复证据：runtime summary、日志、断言或清单
 
 ## Progress
 
 | Phase | Plans Complete | Status | Completed |
 |---|---:|---|---|
 | 1. 对齐现状、边界与重构切入点 | 2/2 | Complete   | 2026-05-21 |
-| 2. 重构 typesetter 与 CSS 分层 | 0/3 | Not started | - |
-| 3. 重构属性体系与复杂分页器 | 0/3 | Not started | - |
-| 4. 接回现有 reader 能力链路 | 0/3 | Not started | - |
-| 5. 回归验证与稳定性收敛 | 0/2 | Not started | - |
+| 2. 重构 typesetter 与 CSS 分层 | 3/3 | Complete | 2026-05-22 |
+| 3. 重构属性体系与复杂分页器 | 3/3 | Complete | 2026-05-22 |
+| 4. 接回现有 reader 能力链路 | 3/3 | Complete | 2026-05-22 |
+| 5. 回归验证与稳定性收敛 | 2/2 | Complete | 2026-05-22 |