6.0 KiB
Milestone v1.0: WXRead Native Reflowable Foundation
Status: ✅ SHIPPED 2026-05-22 Phases: 1-5 Total Plans: 13
Overview
v1.0 completed the direct evolution of the existing reflowable EPUB native path instead of introducing a parallel engine. The milestone established chapter-level CSS preprocessing, richer page metadata, a stronger paginator, reader-shell reintegration, and sample-corpus regression evidence across native reflowable, fixed/interactive WebKit, and TXT flows.
The milestone was archived with accepted audit gaps: the runtime and source evidence indicate the implementation is broadly complete, but requirement bookkeeping in REQUIREMENTS.md, VERIFICATION.md, and SUMMARY.md was not fully reconciled before close-out.
Phases
Phase 1: 对齐现状、边界与重构切入点
Goal: 把“当前旧引擎是什么、哪些能力必须保留、哪些路径绝对不能动”说清楚，形成直接重构旧引擎的实施基线。
Depends on: Nothing (first phase)
Plans: 2 plans
Plans:
- 01-01：审计当前
.textReflowable路径（RDEPUBDTCoreTextRenderer/RDEPUBTextBookBuilder/RDEPUBTextPaginationSupport/RDEPUBTextContentView） - 01-02：结合
Doc/WXRead/analysis/*提炼旧引擎可直接演进的切入点与必须保留的兼容链路
Details:
- 固定了 native
.textReflowable的真实调用链和WKWebView分流边界。 - 把
RDReaderView明确记录为稳定容器，不纳入这轮重构。 - 产出了后续 Phase 2-4 的实施顺序和硬边界。
Phase 2: 重构 typesetter 与 CSS 分层
Goal: 在现有旧引擎基础上引入 WXRead 风格的 CSS 分层与章节级 HTML → attributed string 增强，让 renderer 输入具备更完整的排版语义。
Depends on: Phase 1
Plans: 3 plans
Plans:
- 02-01：设计并实现旧引擎中的 WXRead 风格 stylesheet builder / HTML 预处理增强
- 02-02：改造
RDEPUBDTCoreTextRenderer与相邻渲染链路，使其承接新的样式分层与章节上下文 - 02-03：验证章节级图片/CSS/基础资源在新渲染输入下可正常解析
Details:
- 建立了
default / replace / dark / epub / user五层 CSS 顺序。 - 把 chapter preprocessing、baseURL、linked CSS 内联、资源标准化接入 native renderer。
- 用 demo 样本书验证了 reflowable 章节资源解析。
Phase 3: 重构属性体系与复杂分页器
Goal: 在旧引擎路径中引入页面级 attributed string 元数据与更复杂的分页/页面布局能力，替代当前简单 pageRanges 切页模式。
Depends on: Phase 2
Plans: 3 plans
Plans:
- 03-01：定义并实现页面级 attributed string 元数据与自定义属性键
- 03-02：在旧引擎基础上重构分页器，使其具备接近
WRCoreTextLayouter / WRCoreTextLayoutFrame的核心能力 - 03-03：验证复杂块元素、图片与分页边界控制在新分页器下可工作
Details:
- 引入了页面元数据、attachment/block break reasons、layout frame 语义。
- 保持
pageStartOffset、pageEndOffset、fragmentOffsets、RDEPUBTextOffsetRangeInfo兼容不变。 - 在真实 EPUB 上输出分页诊断，证明新分页语义已生效。
Phase 4: 接回现有 reader 能力链路
Goal: 让新内核在不新增并行原生引擎、且不修改当前翻页代码的前提下，继续服务现有 reader UI、阅读位置、高亮、搜索与主题切换能力。
Depends on: Phase 3
Plans: 3 plans
Plans:
- 04-01：将新内核接回
RDEPUBTextBookBuilder/RDEPUBTextContentView/RDEPUBReaderController，不修改RDReaderView - 04-02：修复并验证阅读位置映射、高亮、搜索等兼容能力
- 04-03：验证字体、行高、主题切换后的重新分页与状态恢复
Details:
- native text backend 被接回现有 reader shell，
RDReaderView保持不变。 - 位置恢复、高亮、搜索、TOC、重分页行为围绕 absolute offset 契约继续工作。
- demo 输出恢复诊断，证明 semantic location 在主题/字号变化后仍可恢复。
Phase 5: 回归验证与稳定性收敛
Goal: 围绕样本书和主流程做回归，收敛分页正确性、位置映射稳定性与关键阅读交互问题。
Depends on: Phase 4
Plans: 2 plans
Plans:
- 05-01：构建样本书验证矩阵与诊断手段（日志/断言/复现清单）
- 05-02：收敛分页、位置映射、图片/块元素分页与主题切换后的稳定性问题
Details:
- demo 启动摘要扩展为 5 本样本书的矩阵验证。
- 覆盖 native reflowable、fixed/interactive WebKit、TXT 三条主路径。
- 运行时证据确认
样本验证：5/5 通过，并保留分页/恢复诊断。
Milestone Summary
Decimal Phases:
- None
Key Decisions:
- 选择直接演进现有
.textReflowable原生引擎，而不是引入并行原生引擎。 - Fixed Layout 与交互式 EPUB 继续保留
WKWebView路径。 RDReaderView作为稳定分页容器不纳入本轮改造范围。- 兼容链路继续围绕 offset-based location/highlight/search/restore 语义维持。
Issues Resolved:
- chapter-level CSS 分层、preprocessing 和资源标准化接入 native renderer。
- 分页器从纯 visible-range slicing 升级为带 block/attachment-aware 语义的 layouter path。
- native reader shell 与位置恢复、高亮、搜索、主题/字号切换重新打通。
- demo 建立了覆盖 reflowable / WebKit / TXT 的统一样本矩阵。
Issues Deferred:
- requirement bookkeeping 未在 milestone close 前完全回写，详见
v1.0-MILESTONE-AUDIT.md。 - 尚无完整 UI 自动化覆盖所有样本和关键交互。
- Nyquist validation 文档仍存在 draft / partial 状态。
Technical Debt Incurred:
REQUIREMENTS.md、VERIFICATION.md、SUMMARY.md的 requirement evidence chain 需要后续补齐。- simulator 运行仍会出现既有
.SFUI-SemiboldCoreText substitution note。
For current project status, see .planning/ROADMAP.md