225 lines
13 KiB
Markdown
225 lines
13 KiB
Markdown
# Phase 1: 对齐现状、边界与重构切入点 - Research
|
||
|
||
**Researched:** 2026-05-21
|
||
**Domain:** iOS EPUB reader architecture / DTCoreText-based native reflowable rendering
|
||
**Confidence:** HIGH
|
||
|
||
<user_constraints>
|
||
## User Constraints (from CONTEXT.md)
|
||
|
||
No user constraints - all decisions at the agent's discretion.
|
||
</user_constraints>
|
||
|
||
<architectural_responsibility_map>
|
||
## Architectural Responsibility Map
|
||
|
||
| Capability | Primary Tier | Secondary Tier | Rationale |
|
||
|------------|-------------|----------------|-----------|
|
||
| EPUB URL entry and format routing | Browser/Client | — | `RDURLReaderController` decides epub vs txt and embeds the correct reader controller. |
|
||
| EPUB structure parsing and reading-profile split | Browser/Client | — | `RDEPUBParser` and `RDEPUBPublication` classify `.textReflowable` vs `webFixedLayout` / `webInteractive`. |
|
||
| Reflowable native chapter rendering | Browser/Client | — | `RDEPUBDTCoreTextRenderer` and `RDEPUBTextBookBuilder` own HTML to `NSAttributedString` and page slicing. |
|
||
| Fixed-layout and interactive content rendering | Browser/Client | — | `RDEPUBWebView` and `RDEPUBPaginator` keep `WKWebView` as the rendering and measurement path. |
|
||
| Page container and interaction shell | Browser/Client | — | `RDReaderView` is the stable presentation container that Phase 1 must not modify. |
|
||
|
||
</architectural_responsibility_map>
|
||
|
||
<research_summary>
|
||
## Summary
|
||
|
||
当前仓库已经存在一条独立的原生 reflowable 路径，而不是“所有 EPUB 都走 WebView”。`RDEPUBReaderController.paginatePublication` 会在 `publication.readingProfile == .textReflowable` 时改走 `RDEPUBTextBookBuilder`，使用 `RDEPUBDTCoreTextRenderer` 把章节 HTML 转成 `NSAttributedString`，再通过 `ss_pageRanges(size:)` 基于 CoreText 可见范围切页。该路径最终产出 `RDEPUBTextBook` / `RDEPUBTextPage`，并由 `RDEPUBTextContentView` 在现有 `RDReaderView` 容器内展示。
|
||
|
||
Fixed Layout 与交互式 EPUB 的边界已经在代码里清晰存在。`RDEPUBParser.readingProfile()` 将 `metadata.layout == .fixed` 归类为 `.webFixedLayout`，并把包含脚本/多媒体/iframe/form 等交互内容的资源归类为 `.webInteractive`。这两类内容继续走 `RDEPUBWebView` / `RDEPUBPaginator` / `WKWebView` 体系，不应被纳入本次原生重构。
|
||
|
||
WXRead 参考资料说明，目标不是“再包一层轻量 renderer”，而是把当前 DTCoreText 路径升级为完整的 typesetter + layouter + layout frame 体系：五层 CSS 级联、自定义 DTCoreText 属性键、块级避免断页、页面级元数据、图片与背景等页面语义。对本仓库来说，最稳妥的切入点是保留 `RDURLReaderController -> RDEPUBReaderController -> RDReaderView` 外层契约不变，把增强集中在 `EPUBTextRendering` 内部及其与 reader state 的对接点。
|
||
|
||
**Primary recommendation:** Phase 1 应先把当前 `.textReflowable` 调用链、WebView 边界、兼容性约束和可演进触点写成明确文档，再以这些文档作为 Phase 2/3 的实现基线。
|
||
</research_summary>
|
||
|
||
<standard_stack>
|
||
## Standard Stack
|
||
|
||
### Core
|
||
| Library | Version | Purpose | Why Standard |
|
||
|---------|---------|---------|--------------|
|
||
| UIKit | iOS 15+ SDK | Reader container, controllers, text view presentation | 现有 reader UI 与 `RDReaderView` 全部建立在 UIKit 上。 |
|
||
| CoreText | System | Native pagination and text measurement | 当前 `ss_pageRanges(size:)` 直接使用 `CTFramesetterCreateFrame` / `CTFrameGetVisibleStringRange`。 |
|
||
| DTCoreText | 1.6.28 | HTML/CSS to `NSAttributedString` | 当前原生 reflowable 渲染核心已经依赖它，后续定制也必须围绕它展开。 |
|
||
| WebKit | System | Fixed-layout / interactive EPUB rendering and pagination measurement | 非 reflowable-native 路径仍依赖 `WKWebView`。 |
|
||
|
||
### Supporting
|
||
| Library | Version | Purpose | When to Use |
|
||
|---------|---------|---------|-------------|
|
||
| DTFoundation | 1.7.19 | DTCoreText supporting parser/runtime pieces | DTCoreText HTML 解析与附件支持所需。 |
|
||
| ZIPFoundation | 0.9.20 | EPUB archive handling | EPUB 解压与资源访问基础设施。 |
|
||
| SnapKit | 5.7.1 | UI layout helper | Reader UI 周边布局已有依赖，但不是本次内核切入点。 |
|
||
|
||
### Alternatives Considered
|
||
| Instead of | Could Use | Tradeoff |
|
||
|------------|-----------|----------|
|
||
| Directly evolving `EPUBTextRendering` | A second native engine alongside the existing one | 会增加长期双轨维护成本，并破坏 roadmap 已锁定的“旧引擎直接演进”原则。 |
|
||
| DTCoreText-based native rendering | Full `WKWebView` for all EPUB modes | 无法满足 WXRead-style page metadata / page-frame semantics / native selection control goals。 |
|
||
| Keeping `RDReaderView` stable | Reworking page container and gesture stack together | 改动半径过大，Phase 1 明确要求把翻页容器排除出本次重构。 |
|
||
|
||
**Installation:**
|
||
```bash
|
||
pod install
|
||
```
|
||
</standard_stack>
|
||
|
||
<architecture_patterns>
|
||
## Architecture Patterns
|
||
|
||
### System Architecture Diagram
|
||
|
||
```text
|
||
RDURLReaderController
|
||
-> RDEPUBReaderController
|
||
-> RDEPUBParser.parse()
|
||
-> RDEPUBPublication / readingProfile()
|
||
-> textReflowable
|
||
-> RDEPUBTextBookBuilder
|
||
-> RDEPUBDTCoreTextRenderer
|
||
-> DTHTMLAttributedStringBuilder
|
||
-> NSAttributedString
|
||
-> RDEPUBTextPaginationSupport.ss_pageRanges()
|
||
-> RDEPUBTextBook / RDEPUBTextPage
|
||
-> RDEPUBTextContentView
|
||
-> RDReaderView
|
||
-> webFixedLayout
|
||
-> RDEPUBWebView.loadFixedSpread()
|
||
-> RDReaderView
|
||
-> webInteractive
|
||
-> RDEPUBPaginator + RDEPUBWebView.loadPage()
|
||
-> RDReaderView
|
||
```
|
||
|
||
### Recommended Project Structure
|
||
|
||
```text
|
||
Sources/RDReaderView/
|
||
├── EPUBCore/ # Parser, publication, web pagination, render requests
|
||
├── EPUBTextRendering/ # Native reflowable rendering and pagination
|
||
├── EPUBUI/ # Reader controller, content views, settings
|
||
└── RDReaderView.swift # Stable page container and gestures
|
||
```
|
||
|
||
### Pattern 1: Preserve the outer reader contract
|
||
**What:** Keep `RDURLReaderController`, `RDEPUBReaderController`, persistence, location mapping, and `RDReaderView` as the stable shell while replacing internals inside `EPUBTextRendering`.
|
||
**When to use:** Any phase that upgrades the reflowable engine without expanding scope into the page container.
|
||
**Example:** `RDEPUBReaderController.paginatePublication` already branches into text vs web rendering without changing the reader container contract.
|
||
|
||
### Pattern 2: Keep rendering and presentation separate
|
||
**What:** Produce rich `RDEPUBTextBook` / `RDEPUBTextPage` models first, then let `RDEPUBTextContentView` render those models.
|
||
**When to use:** When introducing page-level metadata, selection offsets, image semantics, or new pagination logic.
|
||
**Example:** `RDEPUBTextBookBuilder` owns chapter rendering and page slicing, while `RDEPUBTextContentView` only paints attributed substrings and overlays highlights/search state.
|
||
|
||
### Pattern 3: Branch by publication profile early
|
||
**What:** Decide native reflowable vs fixed vs interactive before rendering work starts.
|
||
**When to use:** Any future entry-point or repagination logic.
|
||
**Example:** `RDEPUBParser.readingProfile()` uses `layout == .fixed` and interactive-content detection to keep `WKWebView` modes out of the native path.
|
||
|
||
### Anti-Patterns to Avoid
|
||
- **Touching `RDReaderView` during engine migration:** Phase 1 explicitly excludes page curl / scroll / gesture container changes.
|
||
- **Building a parallel renderer shell:** The roadmap already rejects a “new engine beside old engine” approach.
|
||
- **Mixing WebView-only semantics into the native path:** `textReflowable` should evolve around `NSAttributedString` and CoreText, not around hidden `WKWebView` dependencies.
|
||
</architecture_patterns>
|
||
|
||
<dont_hand_roll>
|
||
## Don't Hand-Roll
|
||
|
||
| Problem | Don't Build | Use Instead | Why |
|
||
|---------|-------------|-------------|-----|
|
||
| HTML parsing | A brand-new EPUB HTML parser | DTCoreText builder extension points | 仓库已经围绕 DTCoreText 建立基础能力，重写 parser 成本高且风险大。 |
|
||
| EPUB mode classification | Ad-hoc view-layer checks | `RDEPUBParser.readingProfile()` | 当前 profile 分流已经覆盖 fixed / interactive / text reflowable。 |
|
||
| Reader shell replacement | A new page container | Existing `RDReaderView` contract | 现有 container 已承担翻页模式、双页与方向逻辑，超出本次范围。 |
|
||
| Location/highlight transport | A second mapping format | Existing `RDEPUBLocation` + `RDEPUBTextOffsetRangeInfo` | 这些类型已被 highlights / search / restore location 链路依赖。 |
|
||
|
||
**Key insight:** 应该复用现有阅读器契约和数据模型，把新增复杂度集中在旧引擎内部，而不是在外围重造一层基础设施。
|
||
</dont_hand_roll>
|
||
|
||
<common_pitfalls>
|
||
## Common Pitfalls
|
||
|
||
### Pitfall 1: Confusing native reflowable with the WebView paginator
|
||
**What goes wrong:** 把 `RDEPUBPaginator` 当成所有 reflowable 的基础，导致 Phase 2/3 方案偏向继续强化 WebView。
|
||
**Why it happens:** 当前工程同时存在 `textReflowable` 和基于 `WKWebView` 的分页/展示路径。
|
||
**How to avoid:** 在所有 Phase 1 输出里明确：`RDEPUBPaginator` 服务于 fixed 或 interactive/web paths；原生重构主战场是 `EPUBTextRendering`。
|
||
**Warning signs:** 计划任务把 `RDEPUBPaginator` 作为 CSS 五层或页面元数据的主要落点。
|
||
|
||
### Pitfall 2: Breaking `RDReaderView` assumptions while changing pagination
|
||
**What goes wrong:** 新分页结果不再满足现有 page index / container reuse / orientation repagination 约定。
|
||
**Why it happens:** 容易把引擎升级和容器升级绑在一起处理。
|
||
**How to avoid:** 把 `RDEPUBTextBook.pages` / `RDEPUBTextPage` 视为 Phase 2/3 的兼容面，并在策略中显式约束 `RDReaderView` 不改。
|
||
**Warning signs:** 方案需要修改 `RDReaderView.DataSource`、翻页方向、双页逻辑或 content view reuse 协议。
|
||
|
||
### Pitfall 3: Introducing richer layout semantics without preserving location mapping
|
||
**What goes wrong:** 新分页器能排版复杂元素，但阅读位置、高亮、搜索结果定位失效。
|
||
**Why it happens:** 只关注排版帧，不关注 `pageStartOffset/pageEndOffset` 与 `RDEPUBLocation` 的传递。
|
||
**How to avoid:** 把 offset continuity、fragment offset、selection range transport 作为 Phase 2/3 的第一类兼容目标。
|
||
**Warning signs:** 设计里没有说明新页面元数据如何回写 `RDEPUBTextBook`、`RDEPUBSelection`、`RDEPUBHighlight`。
|
||
</common_pitfalls>
|
||
|
||
<code_examples>
|
||
## Code Examples
|
||
|
||
### Current reflowable split
|
||
```swift
|
||
if publication.readingProfile == .textReflowable {
|
||
let renderer = resolvedTextRenderer()
|
||
let builder = RDEPUBTextBookBuilder(renderer: renderer)
|
||
let textBook = try builder.build(
|
||
parser: parser,
|
||
publication: publication,
|
||
pageSize: pageSize,
|
||
style: renderStyle
|
||
)
|
||
}
|
||
```
|
||
|
||
### Current fixed vs interactive boundary
|
||
```swift
|
||
public func readingProfile() -> RDEPUBReadingProfile {
|
||
if metadata.layout == .fixed {
|
||
return .webFixedLayout
|
||
}
|
||
return hasInteractiveContent() ? .webInteractive : .textReflowable
|
||
}
|
||
```
|
||
|
||
### Current native pagination primitive
|
||
```swift
|
||
while visibleRange.location + visibleRange.length < length {
|
||
let frame = CTFramesetterCreateFrame(framesetter, CFRangeMake(location, 0), path, nil)
|
||
visibleRange = CTFrameGetVisibleStringRange(frame)
|
||
ranges.append(NSRange(location: location, length: visibleRange.length))
|
||
location += visibleRange.length
|
||
}
|
||
```
|
||
</code_examples>
|
||
|
||
<sota_updates>
|
||
## State of the Art (2024-2025)
|
||
|
||
| Old Approach | Current Approach | When Changed | Impact |
|
||
|--------------|------------------|--------------|--------|
|
||
| Generic HTML to attributed string only | HTML to attributed string plus page-level layout semantics | 已反映在 WXRead 参考资料中 | 需要把 CSS/HTML 处理与分页语义一起设计，而不是只换 builder options。 |
|
||
| Simple visible-range page slicing | Block-aware layout frames and custom pagination metadata | 已反映在 WXRead 参考资料中 | 当前 `CTFrameGetVisibleStringRange` 模式会成为主要替换对象。 |
|
||
| Styling as a small option bag | Multi-layer stylesheet cascade | 已反映在 WXRead 参考资料中 | `dtOptions` 需要被更明确的 stylesheet pipeline 取代或扩展。 |
|
||
|
||
**New tools/patterns to consider:**
|
||
- DTCoreText attribute extension points: 适合承接 WXRead 风格自定义属性键。
|
||
- Page-level layout model: 需要在 `RDEPUBTextChapter` / `RDEPUBTextPage` 附近引入更丰富的元数据，而不是只保存范围。
|
||
|
||
**Deprecated/outdated:**
|
||
- “Simple DTCoreText renderer + pageRanges” 作为长期方案：对复杂块元素、页面语义和 CSS 分层都不够。
|
||
- “为原生重构同时替换翻页容器”：与当前范围控制相冲突。
|
||
</sota_updates>
|
||
|
||
<open_questions>
|
||
## Open Questions
|
||
|
||
- `LegacyRDReaderController/RDEPUBTextPaging.swift` 与新 `EPUBTextRendering` 之间哪些实现差异仍值得迁移，哪些应直接废弃，需要在 Phase 1 执行阶段做一次并列审计。
|
||
- `Doc/FeatureSolution/ReflowableEPUB_WXReadRenderer_Design.md` 与当前源码是否已经出现偏差，需要在 Plan 01-02 中显式核对。
|
||
- 未来自定义 DTCoreText 属性应优先挂在 `NSAttributedString`、页模型，还是单独的 layout frame 对象上，需要在策略文档中做出建议但不提前定版实现。
|
||
</open_questions>
|