140 lines
6.0 KiB
Markdown
140 lines
6.0 KiB
Markdown
# 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:
|
||
|
||
- [x] 01-01：审计当前 `.textReflowable` 路径（`RDEPUBDTCoreTextRenderer` / `RDEPUBTextBookBuilder` / `RDEPUBTextPaginationSupport` / `RDEPUBTextContentView`）
|
||
- [x] 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:
|
||
|
||
- [x] 02-01：设计并实现旧引擎中的 WXRead 风格 stylesheet builder / HTML 预处理增强
|
||
- [x] 02-02：改造 `RDEPUBDTCoreTextRenderer` 与相邻渲染链路，使其承接新的样式分层与章节上下文
|
||
- [x] 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:
|
||
|
||
- [x] 03-01：定义并实现页面级 attributed string 元数据与自定义属性键
|
||
- [x] 03-02：在旧引擎基础上重构分页器，使其具备接近 `WRCoreTextLayouter / WRCoreTextLayoutFrame` 的核心能力
|
||
- [x] 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:
|
||
|
||
- [x] 04-01：将新内核接回 `RDEPUBTextBookBuilder` / `RDEPUBTextContentView` / `RDEPUBReaderController`，不修改 `RDReaderView`
|
||
- [x] 04-02：修复并验证阅读位置映射、高亮、搜索等兼容能力
|
||
- [x] 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:
|
||
|
||
- [x] 05-01：构建样本书验证矩阵与诊断手段（日志/断言/复现清单）
|
||
- [x] 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-Semibold` CoreText substitution note。
|
||
|
||
---
|
||
|
||
_For current project status, see `.planning/ROADMAP.md`_
|
||
|