diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md index b7a3923..fe2e535 100644 --- a/.planning/ROADMAP.md +++ b/.planning/ROADMAP.md @@ -6,7 +6,7 @@ ## Phases -- [ ] **Phase 1: 对齐现状、边界与重构切入点** - 明确当前旧引擎的真实调用链、分流边界与必须保留的兼容能力 +- [x] **Phase 1: 对齐现状、边界与重构切入点** - 明确当前旧引擎的真实调用链、分流边界与必须保留的兼容能力 (completed 2026-05-21) - [ ] **Phase 2: 重构 typesetter 与 CSS 分层** - 在旧引擎基础上引入 WXRead 风格样式组织与章节级 HTML → attributed string 转换增强 - [ ] **Phase 3: 重构属性体系与复杂分页器** - 引入页面级 attributed string 元数据与更强的分页/布局能力 - [ ] **Phase 4: 接回现有 reader 能力链路** - 让新内核与阅读位置、高亮、搜索、主题切换等现有功能继续协作 @@ -27,7 +27,7 @@ Plans: - [x] 01-01:审计当前 `.textReflowable` 路径(`RDEPUBDTCoreTextRenderer` / `RDEPUBTextBookBuilder` / `RDEPUBTextPaginationSupport` / `RDEPUBTextContentView`) -- [ ] 01-02:结合 `Doc/WXRead/analysis/*` 提炼旧引擎可直接演进的切入点与必须保留的兼容链路 +- [x] 01-02:结合 `Doc/WXRead/analysis/*` 提炼旧引擎可直接演进的切入点与必须保留的兼容链路 ### Phase 2: 重构 typesetter 与 CSS 分层 **Goal**: 在现有旧引擎基础上引入 WXRead 风格的 CSS 分层与章节级 HTML → attributed string 增强,让 renderer 输入具备更完整的排版语义。 @@ -93,7 +93,7 @@ Plans: | Phase | Plans Complete | Status | Completed | |---|---:|---|---| -| 1. 对齐现状、边界与重构切入点 | 1/2 | In Progress| | +| 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 | - | diff --git a/.planning/phases/01-current-engine-boundaries/01-02-SUMMARY.md b/.planning/phases/01-current-engine-boundaries/01-02-SUMMARY.md new file mode 100644 index 0000000..5be8ecd --- /dev/null +++ b/.planning/phases/01-current-engine-boundaries/01-02-SUMMARY.md @@ -0,0 +1,87 @@ +--- +phase: 01-current-engine-boundaries +plan: 02 +subsystem: testing +tags: [epub, wxread, refactor, pagination, strategy] +requires: + - phase: 01-current-engine-boundaries + provides: "当前 reflowable 引擎与 WebView 边界审计" +provides: + - "旧引擎直接演进的实施顺序" + - "WXRead 能力到当前源码触点的映射" + - "后续 phase 的非目标与硬边界" +affects: [phase-02, phase-03, phase-04, refactor-sequencing] +tech-stack: + added: [] + patterns: ["typesetter-first refactor", "page-model-preserving pagination upgrade"] +key-files: + created: + - .planning/phases/01-current-engine-boundaries/01-refactor-entry-strategy.md + modified: [] +key-decisions: + - "Phase 2 只升级 renderer/typesetter 与 CSS 分层,不把分页器和 reader 回接一并混入。" + - "Phase 3 再升级 `RDEPUBTextPaginationSupport`、`RDEPUBTextPage` 与 `RDEPUBTextChapter` 的页面语义。" + - "Phase 4 才处理位置、高亮、搜索、主题切换后的重分页兼容回接。" +patterns-established: + - "先提升 HTML/CSS 输入质量,再定位分页语义问题。" + - "扩展现有 `RDEPUBTextBook` 契约,而不是引入第二套 page model。" +requirements-completed: [COMP-02] +duration: 2min +completed: 2026-05-21 +--- + +# Phase 01 Plan 02: Refactor Entry Strategy Summary + +**把 WXRead 风格能力拆解成当前旧引擎可直接落地的文件触点与实施顺序,并固定了 `WKWebView` 与 `RDReaderView` 的非目标边界** + +## Performance + +- **Duration:** 2 min +- **Started:** 2026-05-21T13:56:10Z +- **Completed:** 2026-05-21T13:58:09Z +- **Tasks:** 2 +- **Files modified:** 1 + +## Accomplishments +- 建立了 `WXRead capability -> current file touchpoint -> target phase` 的执行映射 +- 固定了 Phase 2 先做 typesetter / CSS 分层,Phase 3 再做 page model / pagination semantics,Phase 4 再做 reader compatibility 回接的实施顺序 +- 把 `WKWebView` retention boundary、`RDReaderView` 不修改、位置/高亮/搜索/重分页兼容性列成后续 phase 的硬约束 + +## Task Commits + +This plan was closed out with a documentation-only metadata commit after both tasks completed: + +1. **Task 1: 提炼 WXRead 目标能力到当前引擎触点** - included in final docs commit +2. **Task 2: 固化范围边界和兼容性保留链路** - included in final docs commit + +**Plan metadata:** pending commit hash at close-out + +## Files Created/Modified + +- `.planning/phases/01-current-engine-boundaries/01-refactor-entry-strategy.md` - 旧引擎直接演进的切入策略文档 + +## Decisions Made + +- 选择“typesetter first”而不是“pagination first”,避免把输入质量问题和布局语义问题混在一起排查 +- 把 `RDEPUBReaderController` 定义为 reader capability 编排点,而不是新的排版实现承载层 + +## Deviations from Plan + +None - plan executed exactly as written. + +## Issues Encountered + +None + +## User Setup Required + +None - no external service configuration required. + +## Next Phase Readiness + +- Phase 1 的审计与策略文档都已齐备,已能直接支撑 Phase 2 开始 renderer/typesetter 升级工作 +- 后续 phase 可以把 `.planning/phases/01-current-engine-boundaries/01-reflowable-audit.md` 和 `01-refactor-entry-strategy.md` 作为固定输入 + +--- +*Phase: 01-current-engine-boundaries* +*Completed: 2026-05-21* diff --git a/.planning/phases/01-current-engine-boundaries/01-refactor-entry-strategy.md b/.planning/phases/01-current-engine-boundaries/01-refactor-entry-strategy.md new file mode 100644 index 0000000..bae4f01 --- /dev/null +++ b/.planning/phases/01-current-engine-boundaries/01-refactor-entry-strategy.md @@ -0,0 +1,268 @@ +# Phase 1 Strategy: Direct Refactor Entry Points for the Existing Reflowable Engine + +**Phase:** 01-current-engine-boundaries +**Date:** 2026-05-21 +**Purpose:** 把“旧引擎直接演进”的切入点、顺序和硬边界固定下来,供 Phase 2/3 实施使用。 + +## 1. Strategy in One Sentence + +后续实现应保留现有 `RDURLReaderController -> RDEPUBReaderController -> RDReaderView` 外层契约不变,把升级集中在 `EPUBTextRendering` 内部:先增强 typesetter / CSS 分层,再增强页面级属性与分页语义,最后回接并验证 reader 兼容能力。 + +## 2. Why the Strategy Is “Direct Evolution,” Not “Parallel Engine” + +根据当前源码审计,native `.textReflowable` 主路径已经具备以下骨架: + +- `RDEPUBParser.readingProfile()` 已经把普通 reflowable EPUB 分到 `.textReflowable` +- `RDEPUBReaderController.paginatePublication()` 已经把 `.textReflowable` 接到 `RDEPUBTextBookBuilder` +- `RDEPUBDTCoreTextRenderer` 已经承担章节 HTML -> `NSAttributedString` +- `RDEPUBTextPaginationSupport.ss_pageRanges(size:)` 已经承担最小可用分页 +- `RDEPUBTextContentView` 与 `RDReaderView` 已经承担原生页面展示 + +因此,新增第二套原生引擎只会制造双轨维护问题: + +- duplicate reader integration +- duplicate location/highlight/search transport +- duplicate pagination data model +- duplicate regression matrix + +正确策略是:**沿着现有 native text 路径升级内部能力,而不是复制一条新路径。** + +## 3. Target Capability Map: WXRead -> Current Touchpoints + +下表把 WXRead 目标能力映射到当前仓库中真正应该改动的触点。 + +| WXRead-style capability | Current touchpoint | Target phase | Why this file is the right entry point | +|-------------------------|-------------------|--------------|----------------------------------------| +| 五层 CSS 级联(default / replace / dark / epub / user) | `Sources/RDReaderView/EPUBTextRendering/RDEPUBDTCoreTextRenderer.swift` | Phase 2 | 当前 renderer 已拥有 HTML、baseURL、style 三要素,是升级 stylesheet pipeline 的最直接入口。 | +| HTML 预处理与资源引用兜底 | `Sources/RDReaderView/EPUBTextRendering/RDEPUBTextBookBuilder.swift` 或新建 `RDEPUBWXReadHTMLPreprocessor.swift` | Phase 2 | builder 已掌握章节原始 HTML 与章节 baseURL,适合做 `` CSS 内联或章节级规范化。 | +| 统一 stylesheet 生成器 | 新建 `Sources/RDReaderView/EPUBTextRendering/RDEPUBWXReadStyleSheetBuilder.swift` | Phase 2 | 避免把 layered CSS 逻辑塞进 renderer,使样式层可测试、可替换、可调试。 | +| 页面级 attributed string 元数据 | `Sources/RDReaderView/EPUBTextRendering/RDEPUBTextBookBuilder.swift`、`RDEPUBTextChapter`、`RDEPUBTextPage` | Phase 3 | 当前 page model 只有范围和 offset,后续页面语义需要在这里承接。 | +| 更强分页语义(块级避免断页、图片/附件边界) | `Sources/RDReaderView/EPUBTextRendering/RDEPUBTextPaginationSupport.swift` | Phase 3 | 当前 `ss_pageRanges(size:)` 是唯一分页核心,增强必须从这里开始。 | +| Layout frame / layouter 责任分离 | 新建 `EPUBTextRendering` 内部 layouter/frame 类型 | Phase 3 | 不应把复杂页面布局逻辑继续堆在 `RDEPUBReaderController` 或 content view。 | +| Reader 兼容性回接(位置、高亮、搜索、重分页) | `Sources/RDReaderView/EPUBUI/RDEPUBReaderController.swift` | Phase 4 | 这是现有 reader state 的唯一编排点,适合接回而不是承担新排版实现。 | + +## 4. Phase 2 Entry Strategy: Upgrade Typesetter First + +Phase 2 的目标不是“立刻实现 WXRead 全量布局器”,而是把渲染输入从“简单 DTCoreText options”升级为“WXRead 风格 typesetter”。 + +### 4.1 Primary code touchpoints + +优先改动: + +- `Sources/RDReaderView/EPUBTextRendering/RDEPUBDTCoreTextRenderer.swift` +- `Sources/RDReaderView/EPUBTextRendering/RDEPUBTextBookBuilder.swift` +- 新建 `Sources/RDReaderView/EPUBTextRendering/RDEPUBWXReadStyleSheetBuilder.swift` + +### 4.2 Concrete target state + +Phase 2 应把当前 renderer 升级到以下状态: + +1. 合成 layered CSS + - SDK default CSS + - SDK replace/enhancement CSS + - dark theme override + - EPUB embedded CSS + - user CSS from `RDEPUBTextRenderStyle` + +2. 使用章节目录 `baseURL` + - 保留当前 baseURL 计算方式 + - 确保图片与章节级 CSS 相对路径继续可解析 + +3. 维持 fragment marker / fragment offset 体系 + - 不能破坏 `injectFragmentMarkers` + - 不能破坏 `extractFragmentOffsets` + +4. 不改 reader integration surface + - `RDEPUBTextBookBuilder.build(...)` 的高层职责保持不变 + - `RDEPUBReaderController.paginatePublication()` 的分支结构保持不变 + +### 4.3 Why Phase 2 should stop there + +如果在 Phase 2 就同时引入: + +- 全新分页器 +- 大量新 page model +- reader compatibility 回接修复 + +就会把“渲染输入提升”与“分页语义重构”混为一体,定位回归原因会非常困难。Phase 2 应该先把章节渲染输入变得更接近 WXRead,再观察真实样本书暴露的分页问题。 + +## 5. Phase 3 Entry Strategy: Upgrade Pagination Semantics + +Phase 3 才是“把 pageRanges 模式升级为更强页面语义”的阶段。 + +### 5.1 Primary code touchpoints + +优先改动: + +- `Sources/RDReaderView/EPUBTextRendering/RDEPUBTextPaginationSupport.swift` +- `Sources/RDReaderView/EPUBTextRendering/RDEPUBTextBookBuilder.swift` +- `RDEPUBTextPage` +- `RDEPUBTextChapter` +- 必要时新建内部 layouter/layout-frame 类型 + +### 5.2 Concrete target state + +Phase 3 应逐步实现: + +1. 当前 range-only page model -> richer page metadata + - block boundaries + - image/attachment semantics + - page-level layout markers + - future page background or page-style metadata hooks + +2. 当前 visible-range slicing -> stronger pagination semantics + - avoid page break inside for large blocks + - image and attachment boundary handling + - better page edge control than pure `CTFrameGetVisibleStringRange` + +3. 保留 offset continuity + - `pageStartOffset` + - `pageEndOffset` + - chapter-level text continuity + - fragment offset compatibility + +### 5.3 What not to do in Phase 3 + +不要把分页器升级等同于: + +- 改写 `RDReaderView` +- 改写 fixed/interactive 渲染链路 +- 绕开 `RDEPUBTextBook` 直接输出新的 UI 专用模型 + +Phase 3 的正确做法是:让更强的分页语义仍然最终落到现有 book/chapter/page 契约上,必要时是“扩展”这些模型,而不是抛弃它们。 + +## 6. Compatibility Surface That Must Be Preserved + +以下能力必须视为后续 phase 的硬约束: + +### 6.1 `WKWebView` retention boundary + +保留不动: + +- `webFixedLayout` +- `webInteractive` +- `RDEPUBWebView+FixedLayout.swift` +- `RDEPUBWebView+Reflowable.swift` +- `RDEPUBPaginator.swift` 所属的 WebView 测量职责 + +原因: + +- Fixed layout 依赖 spread HTML 表示 +- interactive EPUB 依赖 JS/bridge/iframe/form/multimedia 支持 +- 它们不属于 native reflowable 的目标问题域 + +### 6.2 Stable reader container + +`RDReaderView` 与现有翻页模式保持不变: + +- page curl +- horizontal scroll +- vertical scroll +- page direction +- dual-page / cover page behavior +- orientation-driven container refresh + +原因: + +- 它是 native text 与 web content 的共同外壳 +- 改它会同时扩大 regression surface + +### 6.3 Reader capability continuity + +以下链路必须继续通过现有 `RDEPUBReaderController` 契约工作: + +- 阅读位置恢复 +- `RDEPUBLocation` 映射 +- 高亮 / 选区 +- 搜索结果定位 +- 字号/行高/主题切换后的重分页 + +这要求后续 phase 继续维护: + +- `fragmentOffsets` +- `pageStartOffset` +- `pageEndOffset` +- `RDEPUBTextOffsetRangeInfo` +- `RDEPUBTextContentView` 所依赖的页内容语义 + +## 7. Recommended Implementation Sequence + +建议执行顺序如下: + +### Step 1: Strengthen renderer / typesetter + +目标: + +- layered CSS +- HTML preprocessing +- stable resource resolution +- normalized style injection + +原因: + +- 先把“输入质量”提升,才能判断现有分页问题到底是样式输入问题还是分页算法问题 + +### Step 2: Strengthen pagination semantics + +目标: + +- richer page metadata +- avoid-break logic +- attachment-aware page boundaries + +原因: + +- 在更稳定的 attributed string 输入上做分页升级,结果更可解释 + +### Step 3: Reconnect and validate reader capability chain + +目标: + +- 位置映射 +- highlight/search +- repagination after settings change + +原因: + +- 这一步应基于已经稳定的 renderer + page model,而不是把所有问题都混在一起排查 + +## 8. File-Level Recommendations for Next Phases + +### 8.1 Files Phase 2 should read first + +- `Sources/RDReaderView/EPUBTextRendering/RDEPUBDTCoreTextRenderer.swift` +- `Sources/RDReaderView/EPUBTextRendering/RDEPUBTextBookBuilder.swift` +- `Doc/WXRead/analysis/EPUB渲染管线详解.md` +- `Doc/WXRead/analysis/DTCoreText自定义修改分析.md` +- `.planning/phases/01-current-engine-boundaries/01-reflowable-audit.md` + +### 8.2 Files Phase 3 should read first + +- `Sources/RDReaderView/EPUBTextRendering/RDEPUBTextPaginationSupport.swift` +- `Sources/RDReaderView/EPUBTextRendering/RDEPUBTextBookBuilder.swift` +- `Sources/RDReaderView/EPUBUI/RDEPUBTextContentView.swift` +- `.planning/phases/01-current-engine-boundaries/01-reflowable-audit.md` +- `Doc/WXRead/analysis/02_符号恢复与核心算法.md` + +### 8.3 Files Phase 4 should read first + +- `Sources/RDReaderView/EPUBUI/RDEPUBReaderController.swift` +- `Sources/RDReaderView/EPUBUI/RDEPUBTextContentView.swift` +- `Sources/RDReaderView/RDReaderView.swift` +- Any Phase 2/3 summaries produced from the pagination work + +## 9. Non-Goals and Refusal Rules + +后续 phase 默认拒绝以下方向,除非 roadmap 被显式修改: + +1. 把 Fixed Layout EPUB 改成 native renderer +2. 把 interactive EPUB 改成 native renderer +3. 新建并长期维护第二套 reflowable 原生引擎 +4. 修改 `RDReaderView` 的外部容器契约 +5. 在还没完成 Phase 2 renderer 升级前,就全面重写 reader integration + +## 10. Final Strategy Decision + +最终策略决议如下: + +> Phase 2 先把 `RDEPUBDTCoreTextRenderer` 从“简单 DTCoreText options”升级成“WXRead 风格 typesetter + layered CSS pipeline”;Phase 3 再升级 `RDEPUBTextPaginationSupport`、`RDEPUBTextBookBuilder` 与 page model 的页面语义;Phase 4 才处理 reader capability 链路的兼容回接。整个过程中,`WKWebView` 边界和 `RDReaderView` 容器契约都保持不变。