# 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`_