# 长章节内存优化 — 代码实施清单

> 背景：DTCoreText 文本页已采用"整章上下文布局"，分页与显示边界一致（不可回退）。现状代价：每次翻页/预加载都整章重拷贝 + 重排版后丢弃，且章节缓存里每页常驻一份子串副本。
>
> 总原则：保留"整章参与排版"，去掉"整章按页复制、按页可变、按页缓存"。不改分页器，不上窗口化。

---

## P0：立即可做

### P0-1 削减每页 `content` 子串常驻副本

**现状**：分页产物为每页保存整段 `attributedSubstring`，全章加总约等于又一份整章副本，随邻接窗口（radius 1，共 3 章）常驻。

生成点：

- `Sources/RDReaderView/EPUBUI/ReaderController/ChapterRuntime/RDEPUBChapterLoader.swift:494`（`buildPagesFromRanges`）
- `Sources/RDReaderView/EPUBTextRendering/BuildPipeline/RDEPUBTextBookBuilder.swift:294`
- `Sources/RDReaderView/EPUBTextRendering/RDPlainTextBookBuilder.swift:78`

现存全部消费点（已盘点确认，仅 3 处）：

- `RDEPUBTextContentView.swift:562` — 封面检测 `coverImage(from: page.content)`，仅 `pageIndexInChapter == 0` 且 href 含 "cover"
- `RDEPUBTextContentView.swift:641` — `normalizedPageContent`，仅非 DTCoreText 的 `#else` 回退路径调用
- `RDEPUBTextBookBuilder.swift:93` — 构建期 debug 日志 preview

**任务**：

- [x] 将 `RDEPUBTextPage.content` 改为按需构造：已改为基于 `chapterContent` + `contentRange` 的计算属性（带范围钳制），公开读取 API 不变
- [x] 三个构造点（`RDEPUBChapterLoader` / `RDEPUBTextBookBuilder` / `RDPlainTextBookBuilder`）不再生成每页子串；消费点经计算属性透明按需构造
- [x] `Equatable` 确认：`content` 为派生值，由 `contentRange` + `chapterContent` 判等覆盖，语义不变

**API 兼容性注意**：

- `RDEPUBTextPage` 当前是 `public struct`，`content` 也是公开存储属性；如果 SDK 已存在外部接入方直接读取 `page.content`，则不应直接移除该字段
- 优先方案是保留 `content` 对外访问语义，但将其改为按需构造的计算属性或受控访问器，避免对外 API 断裂
- 若确认当前版本尚无稳定外部依赖，才可以评估把 `content` 从存储属性调整为内部实现细节
- 在实施前应补做一次全仓库与接入侧检索，确认是否有外部调用依赖 `page.content` 的“可变存储”特性

**验收**：打开 3 章窗口后常驻内存下降约"一整章文本规模 × 窗口章数"；封面页显示正常；非 DTCoreText 回退路径回归通过；`--demo-pagination-validate` 命中数不回升。

### P0-2 增加内存打点

- [x] 已新增 `RDEPUBMemoryProbe`（`--demo-memory-probe` 启动参数开启，输出 phys_footprint）；挂载点：`RDEPUBChapterRuntimeStore.insertChapter`、`pageNum` 回调每 20 次翻页、`invalidateAllForSettingsChange`、`viewWillTransition` 转屏完成
- [x] 用 `--demo-memory-probe` 运行 Demo 即可采集对比基线

### P0-3 保持现有缓存限制，防止错误复用

- [x] `shouldAvoidReaderPageCaching`（`RDEPUBTextContentView.swift:319`）保持现状，已补注释说明放开的前置条件是 P1-1 落地
- [x] 本阶段未改 `RDReaderPreloadController` 行为

---

## P1：第二波（P1-1 与 P1-2 必须同批落地）

### P1-1 章节级共享 displayContent

**现状**：`RDEPUBTextContentView.configure` 每次创建整章可变副本（`RDEPUBTextContentView.swift:443`）并按页写入三类属性：页范围主题色（453）、页范围暗黑图附件替换（448）、按页裁剪的高亮属性（459 `applyHighlightsToContent`）。

**约束**：共享字符串一旦被任一页的 `DTCoreTextLayouter`/framesetter 持有，就不得再修改——所有属性必须在共享内容构建时一次性注入，或转为 overlay（见 P1-2）。

**任务**：

- [ ] 在章节运行时侧（建议挂在 `RDEPUBRuntimeChapter` 或新建 `RDEPUBChapterDisplayCache`）新增：
  - `chapterDisplayContent`（`typesetAttributedString` 的一次性拷贝）
  - `displaySignature`（组成：主题、暗黑图配置、字体设置、本章高亮集合版本）
- [ ] 构建共享内容时一次性注入：全章范围主题色；全章范围高亮/下划线属性（若 P1-2 决定转 overlay 则此项取消）
- [ ] 确定暗黑图策略（二选一）：
  - a. 构建时全章一次性替换（依赖 `RDEPUBDarkImageAdjuster` 的 NSCache 兜底解码成本）
  - b. 移到渲染时按可见附件替换，不触碰共享字符串
- [ ] `RDEPUBTextContentView.configure` 改为接收"共享内容引用 + `page.contentRange`"，删除 443 行的整章拷贝
- [ ] 高亮增删、搜索激活、主题/设置变化 → 比对 `displaySignature`，不一致则重建共享内容（禁止原地修改）
- [ ] 章节淘汰（`RDEPUBChapterRuntimeStore.evict` / `handleMemoryWarning` / `invalidateAllForSettingsChange`）同步释放 display cache

**验收**：连续翻页不再出现整章拷贝（打点确认）；翻页延迟下降；高亮显示、高亮点击菜单、underline、搜索 currentMatch、附件点击、选区拖拽全部回归通过。

### P1-2 高亮/下划线剥离为 overlay（与 P1-1 绑定）

**现状**：搜索高亮已走 overlay（`RDEPUBTextContentView.swift:759` 处 `buildDecorations` 传 `highlights: []`，注释明确为避免双画）；普通高亮/下划线仍靠写 `kRDEPUBHighlightAttributeName` / `kRDEPUBUnderlineAttributeName` 属性由 render view 绘制。

**任务**：

- [ ] `buildDecorations` 改为传入真实 highlights，高亮/下划线由 decoration 层绘制
- [ ] 移除 `applyHighlightsToContent`（`RDEPUBTextContentView.swift:617`）及 render view 对两个自定义属性的绘制路径，确认无双画
- [ ] 高亮命中（`highlight(at:)`）与菜单锚点继续走 `interactionController.selectionRects`，坐标保持 chapter-absolute

**验收**：高亮/下划线视觉与改前一致（含跨页高亮的页内裁剪）；高亮点击弹菜单正常；与搜索高亮叠加时无双画。

### P1-3 章节级共享 display layouter

**现状**：每个页面视图各建一个 `DTCoreTextLayouter`（`RDEPUBTextContentView.swift:465`）；章节运行时已有分页用 `RDEPUBTextLayouter`（`RDEPUBRuntimeChapter.layouter`），display layouter 向同一模式靠拢。

**任务**：

- [ ] `DTCoreTextLayouter` 随 `chapterDisplayContent` 一起放入章节级 display cache，与 signature 同生命周期
- [ ] 页面按 `bounds` + `page.contentRange` 取 `layoutFrame`；`RDEPUBTextPageVerticalJustifier.justify` 会修改 layoutFrame，因此 **保持 `shouldCacheLayoutFrames = false`**，layoutFrame 永远按页新建、不共享
- [ ] bounds 变化（横竖屏/双页）纳入失效条件；确认旧 layoutFrame 随页面视图释放
- [ ] `RDEPUBTextPageBoundaryValidator` 校验路径不变

**验收**：翻页时不再重建 framesetter（打点确认）；横竖屏切换后布局正确；`--demo-pagination-validate` 不回升。

### P1-4 评估重新放开文本页预加载缓存

前置：P1-1～P1-3 全部落地后，页面视图不再持有整章副本。

- [ ] 调整 `shouldAvoidReaderPageCaching` 判定，允许轻量化后的文本页进入 `RDReaderPreloadController` 缓存
- [ ] 对比放开前后的翻页流畅度与峰值内存，数据不佳则回退此项

---

## P2：视 P0/P1 打点数据决定

### P2-1 章节级 LRU 分层淘汰

**现状**：`RDEPUBChapterRuntimeStore` 已有邻接窗口（`windowSpineIndices`，radius 1）、`evictableSpineIndices` / `evict` / `evictAllExceptCurrent` / `handleMemoryWarning` / `invalidateAllForSettingsChange`；磁盘侧有 `RDEPUBChapterSummaryDiskCache`（分页结果 + cfiMap + metadata）。当前邻接章节仍持有完整 `RDEPUBRuntimeChapter`（typesetString + pages + layouter）。

**任务**：

- [ ] 邻接章节降级：保留 page map / chapter summary / 分页结果，释放 `typesetAttributedString`、display content、layouter
- [ ] 进入邻接章节时按 summary 重建，测量重建延迟；延迟不可接受则维持现状
- [ ] 远距章节仅保留磁盘缓存 + 轻量 metadata（现有 evict 已覆盖，确认即可）

### P2-2 图片附件深化

**现状**：暗黑图已走 `NSCache`（50 MB / 100 张，`RDEPUBDarkImageAdjuster.swift:9`）且仅处理当前页范围；章节运行时另有 100 MB `imageCache`。

**任务**：

- [ ] 大图按显示尺寸下采样后再参与 attachment
- [ ] 页面离屏后释放 attachment 强引用的已解码大图；避免共享 content 长期持有
- [ ] 回归：图片点击查看、暗黑模式切换、附件位置与命中

---

## P3：仅在 P0–P2 之后数据仍不达标时

- [ ] 上下文窗口化布局（当前页所在段落块 + 前后足以影响断行的文本窗口）。风险最高：易重新引入分页/显示边界不一致（CTTypesetter 断行上下文敏感，为已知已解 bug 的根因），选区/搜索/高亮/附件索引需全部重验。默认不做。

---

## 明确不做

1. 回退"页内子串重新布局"（重新引入显示不全/页末孤字）
2. 取消 chapter-absolute 索引（破坏点击/选区/高亮定位一致性）
3. 先改分页器（正确性与性能问题混杂，无法回归）
4. 未落地 P1 前放开文本页 reader 级缓存（会驻留多份整章副本）

---

## 各阶段统一验收指标

**正确性**：`--demo-pagination-validate` 命中数不回升；长章节页末无孤字/缺字；高亮显示、搜索高亮、附件点击、选区拖拽行为一致。

**内存**（对比 P0-2 基线）：打开长章节后常驻；连续翻页 20 页峰值；设置变更前后峰值；横竖屏切换峰值。

**性能**：首次打开章节耗时；连续翻页帧稳定性；设置切换恢复时间。