docs: 同步 Doc 文档与当前代码状态

- 更新模块文件数（EPUBCore 31+2, EPUBTextRendering 13, ReaderView 5, EPUBUI 19）
- 更新 Swift 版本（5.10）、iOS 版本（15.0）、行数等基本信息
- 补充新增文件文档（TextAnchor, RenderRequest, WebViewDebug, AssetRepository,
  TextIndexTable, TextPerformanceSampler, ChapterData, PageInteractionController 等）
- 更新 RDEPUBLocation 模型（新增 rangeAnchor 字段）
- 更新 RDEPUBReaderConfiguration（13 项配置）、Delegate 签名、Persistence（8 方法）
- 修正 RDURLReaderController 归属（ReaderView → EPUBUI）
- 移除过时的 LegacyRDReaderController 引用
- 标记 SS→RD 命名迁移为已完成

Doc/ARCHITECTURE.md

@@ -4,8 +4,8 @@
 
 RDReaderView 是一个 iOS 阅读器组件库（CocoaPods），提供开箱即用的 EPUB 阅读能力，并保留对纯文本翻页的支持。
 
-- **最低 iOS 版本**：15.0（podspec 仍标注 9.0，实际 demo Podfile 要求 15.0）
-- **Swift 版本**：5.0+
+- **最低 iOS 版本**：15.0
+- **Swift 版本**：5.10+
 - **依赖**：ZIPFoundation（EPUB 解压）、DTCoreText（文本 EPUB 渲染）
 - **Demo 额外依赖**：SnapKit、SSAlertSwift
 
@@ -21,10 +21,13 @@ RDReaderView 是一个 iOS 阅读器组件库（CocoaPods），提供开箱即
                             │
 ┌───────────────────────────▼─────────────────────────────┐
 │                EPUBUI 层（library 级读者 UI）              │
-│  RDEPUBReaderController（开箱即用入口）                    │
-│  RDEPUBReaderConfiguration / Theme / Persistence         │
-│  TopToolView / BottomToolView / ChapterList / Settings   │
+│  RDEPUBReaderController（开箱即用入口，~1995 行）          │
+│  RDEPUBReaderConfiguration / Theme / Settings / Persistence│
+│  TopToolView / BottomToolView / ToolView 基类             │
+│  ChapterList / Highlights / Bookmarks / Settings 面板     │
 │  RDEPUBTextContentView / RDEPUBWebContentView            │
+│  RDEPUBPageInteractionController / SelectionOverlayView   │
+│  RDEPUBPageLayoutSnapshot / RDURLReaderController         │
 └───────────────────────────┬─────────────────────────────┘
                             │
 ┌───────────────────────────▼─────────────────────────────┐
@@ -40,10 +43,13 @@ RDReaderView 是一个 iOS 阅读器组件库（CocoaPods），提供开箱即
 │                 EPUBCore 层（EPUB 引擎）                   │
 │                                                          │
 │  Publication 层                                          │
-│    RDEPUBParser（+Archive / +Package / +TOC / …）        │
+│    RDEPUBParser（+Archive / +Package / +TOC /            │
+│                  +ReadingProfile / +Resources）           │
 │    RDEPUBPublication（出版物聚合对象）                     │
 │    RDEPUBModels（metadata / manifest / spine 模型）       │
 │    RDEPUBReadingModels（location / viewport / highlight） │
+│    RDEPUBTextAnchor / RDEPUBTextRangeAnchor（文本锚点）    │
+│    RDEPUBRenderRequest（渲染请求模型）                     │
 │                                                          │
 │  Services 层                                             │
 │    RDEPUBResourceResolver（资源 URL 统一入口）             │
@@ -57,11 +63,12 @@ RDReaderView 是一个 iOS 阅读器组件库（CocoaPods），提供开箱即
 │                                                          │
 │  Resource View 层                                        │
 │    RDEPUBWebView（+Configuration / +Reflowable /         │
-│                  +FixedLayout / +JavaScriptBridge）       │
+│                  +FixedLayout / +JavaScriptBridge /       │
+│                  +Search）                                │
 │    RDEPUBResourceURLSchemeHandler（ss-reader:// 协议）    │
 │    RDEPUBStyleSheetBuilder / RDEPUBJavaScriptBridge       │
 │    RDEPUBFixedLayoutTemplate / RDEPUBAssetRepository      │
-│    RDEPUBRenderRequest                                    │
+│    RDEPUBWebViewDebug（调试日志工具）                      │
 │                                                          │
 │  Search 层                                               │
 │    RDEPUBSearchEngine（协议）/ RDEPUBHTMLSearchEngine     │
@@ -75,15 +82,10 @@ RDReaderView 是一个 iOS 阅读器组件库（CocoaPods），提供开箱即
 │  RDEPUBTextRendererSupport / RDEPUBTextPaginationSupport  │
 │  RDEPUBTextBookBuilder / RDPlainTextBookBuilder           │
 │  RDEPUBTextLayouter / RDEPUBTextLayoutFrame               │
+│  RDEPUBTextBookCache / RDEPUBChapterData                  │
+│  RDEPUBTextIndexTable / RDEPUBTextPerformanceSampler      │
 │  RDEPUBTextSearchEngine                                   │
 └──────────────────────────────────────────────────────────┘
-
-┌──────────────────────────────────────────────────────────┐
-│         LegacyRDReaderController/（旧版阅读器，保留兼容）   │
-│  RDReaderController（旧版）/ RDReaderManager               │
-│  RDReaderContentView / RDReaderEPUBContentView             │
-│  SSChapterListController / SSEventTrigger                  │
-└──────────────────────────────────────────────────────────┘
 ```
 
 ---
@@ -239,6 +241,7 @@ session.clearPendingNavigation()                    // 取消待执行跳转
 | `+Reflowable` | 注入分页 CSS、滚动到指定 progression、接收 JS 事件 |
 | `+FixedLayout` | fixed-layout HTML wrapper 生成和加载 |
 | `+JavaScriptBridge` | JS ↔ Swift 消息路由、选区、高亮、进度上报 |
+| `+Search` | 搜索高亮装饰 |
 
 #### ss-reader:// 协议
 
@@ -323,7 +326,10 @@ present(controller, animated: true)
 | `showsTableOfContents` | `true` | 是否显示目录入口 |
 | `allowsHighlights` | `true` | 是否显示高亮入口 |
 | `showsSettingsPanel` | `true` | 是否显示设置入口 |
+| `reflowableContentInsets` | (40,16,40,16) | 可重排内容内边距 |
+| `fixedContentInset` | .zero | 固定版式内容内边距 |
 | `theme` | `.light` | 主题 |
+| `fixedLayoutFit` | `.page` | 固定版式适配模式 |
 | `fixedLayoutSpreadMode` | `.automatic` | fixed-layout spread 模式 |
 | `textRenderingEngine` | `.dtCoreText` | 文本 EPUB 渲染引擎 |
 
@@ -377,6 +383,7 @@ struct RDEPUBLocation: Codable, Equatable {
     var progression: Double      // 视口起始位置 [0, 1]
     var lastProgression: Double? // 视口末尾位置 [0, 1]
     var fragment: String?        // 锚点
+    var rangeAnchor: RDEPUBTextRangeAnchor?  // 文本范围锚点（用于文本 EPUB 高亮定位）
 }
 ```
 
@@ -393,8 +400,8 @@ struct RDEPUBLocation: Codable, Equatable {
 
 | 问题 | 说明 |
 |------|------|
-| Demo 层 RDReaderController 过大 | 约 1900+ 行，仍混有 EPUB 加载、UI 管理、数据源逻辑，待进一步拆分 |
-| RDEPUBParser.swift 仍偏大 | 约 900 行，虽已拆出多个扩展文件，OPF metadata 细节仍集中 |
+| RDEPUBReaderController 过大 | 约 1995 行，仍混有 EPUB 加载、UI 管理、数据源逻辑，待进一步拆分 |
+| 部分 UI 文件仍然偏大 | RDEPUBTextContentView ~728 行、RDEPUBTextBookBuilder ~717 行，需继续拆分 |
 | 横竖屏切换已接入一阶段支持 | `RDEPUBReaderController.viewWillTransition()` 统一接管正文重分页，`RDReaderView` 保留容器级双页布局刷新；仍需补齐固定回归矩阵 |
 | 固定手势分区比例 | 三等分固定写死，不支持自定义 |
 | 自动化测试为首批接入状态 | 已有 `ReadViewSDKDemoTests` / `ReadViewSDKDemoUITests` 与 parser / resolver / persistence / smoke 用例，分页、恢复链路和更多 UI 闭环仍需继续补齐 |
@@ -416,7 +423,7 @@ pod install
 
 | 依赖 | 用途 | 使用层 |
 |------|------|--------|
-| ZIPFoundation | EPUB ZIP 解压 | RDEPUBParser+Archive |
+| ZIPFoundation (~> 0.9) | EPUB ZIP 解压 | RDEPUBParser+Archive |
 | DTCoreText | HTML → NSAttributedString | RDEPUBDTCoreTextRenderer |
 | SnapKit | Demo 布局 | Demo 层 |
 | SSAlertSwift | Demo 弹窗 | Demo 层 |

Doc/CODING_STYLE.md

@@ -1,8 +1,8 @@
-# ReadSDK 代码规范
+# ReadViewSDK 代码规范
 
 ## 适用范围
 
-本文档适用于 `ReadSDK` 新增代码与重构代码。
+本文档适用于 `ReadViewSDK` 新增代码与重构代码。
 
 - 规范覆盖 `Sources/` 与 `RDReaderDemo/` 中的 Swift 代码。
 - 命名、分层与职责边界以 SDK 可维护性和可扩展性为优先。
@@ -225,15 +225,17 @@ RDEPUBWebView+Reflowable.swift
 - 命名先定前缀再落代码：类型一律 `RD` 开头。
 - 若需迁移历史 `SS` 前缀，按模块渐进替换，优先替换新增与重构触达文件。
 
-## 旧 SS 命名迁移到 RD 的分阶段执行清单
+## 旧 SS 命名迁移到 RD 的执行状态
 
-### 阶段 0：冻结新增 SS 命名（立即执行）
+**迁移已完成**：源码中已无 `SS` 前缀类型定义，全部使用 `RD`/`RDEPUB` 前缀。新增代码必须继续遵守此规则。
+
+### 阶段 0：冻结新增 SS 命名（已完成）
 
 - 目标：从当前时点开始，不再引入新的 `SS`/`RDEPUB` 类型名。
 - 动作：
   - 新增类型统一使用 `RD`/`RDEPUB` 前缀。
   - Code Review 增加命名检查项：发现新增 `SS` 命名必须驳回。
-  - 在 PR 模板中加入“本次是否新增旧前缀命名”勾选项。
+  - 在 PR 模板中加入”本次是否新增旧前缀命名”勾选项。
 - 验收：
   - 新提交代码中，新增类型 `SS` 前缀数量为 `0`。
 

Doc/EPUBCore_功能实现逻辑.md

@@ -2,7 +2,7 @@
 
 ## 1. 范围与目标
 
-- 代码范围：`Sources/RDReaderView/EPUBCore/`（30 个 Swift 文件 + 2 个资源文件）
+- 代码范围：`Sources/RDReaderView/EPUBCore/`（31 个 Swift 文件 + 2 个资源文件）
 - 目标：说明 EPUBCore 如何完成 EPUB 解析、资源定位、阅读会话管理、离屏分页、JS 桥接渲染和全文搜索。
 - 主链路关键词：`epubURL -> RDEPUBParser.parse -> container.xml -> OPF -> spine/TOC -> RDEPUBPublication -> RDEPUBReadingSession -> RDEPUBWebView/Paginator -> 分页/渲染`。
 
@@ -40,7 +40,7 @@
 
 ### 2.4 WebView 渲染层 `RDEPUBWebView`
 
-- 文件：`EPUBCore/RDEPUBWebView.swift` + 5 个扩展文件
+- 文件：`EPUBCore/RDEPUBWebView.swift` + 5 个扩展文件（+Configuration / +Reflowable / +FixedLayout / +JavaScriptBridge / +Search）
 - 职责：
   - 内部持有 WKWebView，配置自定义 scheme handler 和 JS 桥接
   - 可重排内容加载：`loadPage(parser:spineIndex:pageIndex:...)`（`+Reflowable.swift`）
@@ -77,13 +77,13 @@
   - `ssReaderFixedLayoutReady`：固定版式渲染完成
 - JS 端 `window.RDReaderBridge` 暴露：`applyPagination`、`setPageMetrics`、`scrollToPage`、`scrollToLocation`、`setHighlights`、`clearHighlights`、`reportProgression`、`selectionPayload`
 
-### 2.8 搜索引擎 `RDEPUBHTMLSearchEngine`
+### 2.8 搜索引擎 `RDEPUBSearchEngine` / `RDEPUBHTMLSearchEngine`
 
 - 文件：`EPUBCore/RDEPUBSearchEngine.swift`、`EPUBCore/RDEPUBSearchModels.swift`
 - 职责：
-  - 将 HTML 转为纯文本（NSAttributedString 或正则兜底）
-  - 执行大小写不敏感的全文搜索
-  - 返回 `RDEPUBSearchMatch` 数组（含 progression 偏移和预览文本）
+  - `RDEPUBSearchEngine`：搜索协议定义
+  - `RDEPUBHTMLSearchEngine`：WebView 路径实现，将 HTML 转为纯文本（NSAttributedString 或正则兜底），执行大小写不敏感的全文搜索
+  - 搜索模型：`RDEPUBSearchMatch`、`RDEPUBSearchResult`、`RDEPUBSearchState`、`RDEPUBSearchPresentation`
 
 ### 2.9 配置与样式
 
@@ -92,6 +92,42 @@
 - `RDEPUBStyleSheetBuilder`（`EPUBCore/RDEPUBStyleSheetBuilder.swift`）：生成分页 CSS、渲染 CSS 和测量 JS 脚本
 - `RDEPUBFixedLayoutTemplate`（`EPUBCore/RDEPUBFixedLayoutTemplate.swift`）：生成固定版式 HTML 模板
 
+### 2.10 文本锚点 `RDEPUBTextAnchor` / `RDEPUBTextRangeAnchor`
+
+- 文件：`EPUBCore/RDEPUBTextAnchor.swift`
+- 职责：
+  - `RDEPUBTextAnchor`：精确定位到 EPUB 中的某个字符位置，包含 fileIndex（spine 索引）、row（行号）、column（列号）、chapterOffset（章节内字符偏移）、fragmentID（最近的 fragment）
+  - `RDEPUBTextRangeAnchor`：由起止锚点组成的文本区间，可转换为 NSRange
+  - 支持 Codable 序列化，兼容 `fileIndex` 和 `spineIndex` 两种 key
+  - 用于文本 EPUB 的高亮精确锚定和跨会话恢复
+
+### 2.11 渲染请求模型 `RDEPUBRenderRequest`
+
+- 文件：`EPUBCore/RDEPUBRenderRequest.swift`
+- 职责：
+  - `RDEPUBFixedLayoutFit`：固定版式适配模式枚举（`.auto` / `.page` / `.width`）
+  - `RDEPUBFixedLayoutSpreadMode`：Spread 显示模式枚举（`.automatic` / `.always` / `.never`）
+  - `RDEPUBPresentationStyle`：WebView 和 Paginator 共用的视觉参数（viewportSize、contentInsets、fontSize、lineHeightMultiple、主题色）
+  - `RDEPUBReflowableRenderRequest`：可重排内容渲染请求（spineIndex、href、pageIndex、presentation、highlights、searchPresentation）
+  - `RDEPUBFixedRenderRequest`：固定版式渲染请求（spread、viewportSize、fit、searchPresentation）
+  - `RDEPUBRenderRequest`：统一枚举（`.reflowable` / `.fixed`），WebView 根据此类型选择渲染路径
+
+### 2.12 调试工具 `RDEPUBWebViewDebug`
+
+- 文件：`EPUBCore/RDEPUBWebViewDebug.swift`
+- 职责：
+  - WebView 调试日志工具集，DEBUG 模式默认开启
+  - 支持导航事件、JS 执行、消息接收、URL Scheme 任务的日志记录
+  - 可通过 UserDefaults `"RDEPUBWebViewDebugEnabled"` 覆盖开关
+
+### 2.13 资源加载器 `RDEPUBAssetRepository`
+
+- 文件：`EPUBCore/RDEPUBAssetRepository.swift`
+- 职责：
+  - 从资源包加载 JS 桥接脚本（`epub-bridge.js`）和固定版式 HTML 模板（`epub-fixed-layout.html`）
+  - 支持 `{{token}}` 模板变量替换
+  - 自动定位 `RDReaderViewAssets.bundle`（优先已解析子 bundle，兜底宿主 bundle）
+
 ## 3. 主流程（代码级）
 
 ### 3.1 EPUB 解析全流程
@@ -237,6 +273,7 @@ RDEPUBLocation
   ├── progression: Double?       (0..1，章节内起始位置)
   ├── lastProgression: Double?   (0..1，章节内结束位置)
   ├── fragment: String?          (#anchor)
+  ├── rangeAnchor: RDEPUBTextRangeAnchor?  (文本范围锚点，用于高亮精确定位)
   └── navigationProgression      (computed: midpoint of progression and lastProgression)
 ```
 
@@ -279,7 +316,8 @@ RDEPUBRenderRequest (enum)
 RDEPUBHighlight
   ├── id, bookIdentifier
   ├── location: RDEPUBLocation
-  ├── text, rangeInfo (JSON-serialized DOM range)
+  ├── text, rangeInfo (JSON-serialized DOM range 或 text-offset)
+  ├── style: RDEPUBHighlightStyle (.highlight | .underline)
   ├── color: String, note: String
   └── createdAt: Date
 
@@ -288,6 +326,13 @@ RDEPUBSelection
   ├── location: RDEPUBLocation
   ├── text, rangeInfo
   └── createdAt: Date
+
+RDEPUBBookmark
+  ├── id, bookIdentifier
+  ├── location: RDEPUBLocation
+  ├── title: String?
+  ├── note: String?
+  └── createdAt: Date
 ```
 
 ### 5.6 搜索模型

Doc/EPUBTextRendering_功能实现逻辑.md

@@ -2,7 +2,7 @@
 
 ## 1. 范围与目标
 
-- 代码范围：`Sources/RDReaderView/EPUBTextRendering/`（9 个 Swift 文件）
+- 代码范围：`Sources/RDReaderView/EPUBTextRendering/`（13 个 Swift 文件）
 - 目标：说明文本渲染路径如何将 EPUB HTML 转换为 NSAttributedString、按字符范围分页、构建书籍模型，并支持全文搜索与 textReflowable 标注定位。
 - 主链路关键词：`RDEPUBParser HTML -> DTCoreText 渲染 -> 片段标记注入/提取 -> CoreText 分页 -> RDEPUBTextBook -> 页面查找/位置转换`。
 - 适用范围：仅用于 `textReflowable` 阅读配置文件（纯文本可重排 EPUB，如小说）。固定版式和交互式 EPUB 使用 WebView 渲染路径。
@@ -64,6 +64,14 @@
   - 在已渲染的 NSAttributedString 纯文本上执行线性搜索
   - 返回 `RDEPUBSearchMatch` 数组（含 href、progression、预览文本、匹配位置）
 
+### 2.6.1 章节数据模型 `RDEPUBChapterData`
+
+- 文件：`EPUBTextRendering/RDEPUBChapterData.swift`
+- 职责：
+  - 每章节的数据聚合模型，管理高亮、搜索结果和页面查询
+  - 支持按页码范围过滤当前页的高亮列表
+  - 支持搜索结果在章节内的定位和匹配索引计算
+
 ### 2.7 CoreText 分页引擎 `RDEPUBTextLayouter` / `RDEPUBTextLayoutFrame`
 
 - 文件：`EPUBTextRendering/RDEPUBTextLayouter.swift`、`EPUBTextRendering/RDEPUBTextLayoutFrame.swift`
@@ -80,6 +88,28 @@
   - 将纯文本按段落切分后渲染为 NSAttributedString
   - 按页面尺寸分页，输出与 EPUB 文本路径一致的书籍模型
 
+### 2.9 文本索引表 `RDEPUBTextIndexTable`
+
+- 文件：`EPUBTextRendering/RDEPUBTextIndexTable.swift`
+- 职责：
+  - 构建全书的文本结构映射：章节起始偏移、href 与章节/spine 索引对应、fragment 偏移映射、行列索引映射
+  - `RDEPUBRowColumnIndex`：行-列索引条目，记录每行的字符范围
+  - 支持锚点与位置之间的双向转换：
+    - `anchor(forAbsoluteIndex:in:)`：绝对索引 → 文本锚点
+    - `anchor(for:)`：阅读位置 → 文本锚点（优先 rangeAnchor，其次 fragment/progression）
+    - `absoluteIndex(for:)`：锚点 → 全书绝对索引
+    - `location(for:in:bookIdentifier:)`：锚点/范围锚点 → 阅读位置
+  - 支持页码查找：`pageNumber(for:in:)` 通过锚点定位到对应页面
+
+### 2.10 性能采样器 `RDEPUBTextPerformanceSampler`
+
+- 文件：`EPUBTextRendering/RDEPUBTextPerformanceSampler.swift`
+- 职责：
+  - `RDEPUBTextPerformanceSample`：单章节性能数据（chapterHref、renderDuration、paginateDuration、pageCount、attributedStringLength、cacheHit）
+  - `RDEPUBTextPerformanceSampler`：书籍构建过程的性能采样器
+  - 由 `RDEPUBTextBookBuilder` 在构建过程中使用，每章记录一个采样点
+  - `summary()` 输出汇总报告：总渲染/分页耗时和缓存命中率
+
 ## 3. 主流程（代码级）
 
 ### 3.1 完整渲染-分页流程
@@ -295,7 +325,8 @@ RDEPUBTextBook
 - **内存**：`RDEPUBTextBook` 同时持有 chapters（含完整 attributedContent）和 pages（含子串切片），存在一定程度的内存重复
 - **后台执行**：`build` 方法在 `DispatchQueue.global(qos: .userInitiated)` 执行，不阻塞主线程
 - **搜索性能**：线性扫描每章的 `attributedContent.string`，无索引，搜索时间与总文本量线性相关
-- **无分页缓存**：字号/行高变化时全书重新渲染和分页，无增量更新
+- **分页缓存**：`RDEPUBTextBookCache` 支持磁盘缓存分页结果，字号/行高变化时优先从缓存恢复
+- **性能采样**：`RDEPUBTextPerformanceSampler` 记录每章的渲染和分页耗时，支持缓存命中率统计
 
 ## 9. 联调与排查建议
 

Doc/EPUBUI_功能实现逻辑.md

@@ -2,7 +2,7 @@
 
 ## 1. 范围与目标
 
-- 代码范围：`Sources/RDReaderView/EPUBUI/`（16 个 Swift 文件）
+- 代码范围：`Sources/RDReaderView/EPUBUI/`（19 个 Swift 文件）
 - 目标：说明 EPUBUI 如何作为开箱即用的阅读器 UI 层，协调 EPUBCore 解析、EPUBTextRendering 文本渲染、RDReaderView 分页容器，提供完整的阅读体验（工具栏、目录、高亮批注、设置面板、阅读位置持久化、搜索）。
 - 主链路关键词：`RDEPUBReaderController.init -> 解析 EPUB -> 分页 -> 渲染 -> 用户交互（翻页/工具栏/设置/高亮/搜索）-> 持久化`。
 
@@ -10,7 +10,7 @@
 
 ### 2.1 主控制器 `RDEPUBReaderController`
 
-- 文件：`EPUBUI/RDEPUBReaderController.swift`（~1255 行）
+- 文件：`EPUBUI/RDEPUBReaderController.swift`（~1995 行）
 - 入口方法：
   - `init(epubURL:configuration:persistence:)` — 标准 EPUB 阅读入口
   - `init(textBook:bookIdentifier:title:textFileURL:configuration:)` — 纯文本书籍阅读入口（由 `RDPlainTextBookBuilder` 构建 `RDEPUBTextBook` 后传入）
@@ -29,7 +29,7 @@
   - `fontSize`（默认 15）、`lineHeightMultiple`（默认 1.6）
   - `displayType`（默认 .pageCurl）、`landscapeDualPageEnabled`（默认 true）
   - `showsTableOfContents`（默认 true）、`allowsHighlights`（默认 true）、`showsSettingsPanel`（默认 true）
-  - `reflowableContentInsets`（默认 40/16/40/16）、`fixedContentInset`（默认 .zero）
+  - `reflowableContentInsets`（默认 top:40 left:16 bottom:40 right:16）、`fixedContentInset`（默认 .zero）
   - `theme`（默认 .light）
   - `fixedLayoutFit`（默认 .page）、`fixedLayoutSpreadMode`（默认 .automatic）
   - `textRenderingEngine`（默认 .dtCoreText）
@@ -41,45 +41,47 @@
 
 - 文件：`EPUBUI/RDEPUBReaderDelegate.swift`
 - 12 个可选方法（全部有默认空实现）：
-  - `didOpen`：成功打开出版物
-  - `didUpdateLocation`：翻页或滚动时位置更新
-  - `didReachEnd`：到达最后一页
-  - `didChangeSelection`：文本选择变化或清除
-  - `didUpdateHighlights`：高亮增删改
-  - `didUpdateBookmarks`：书签增删改
-  - `didUpdateSearchResult`：搜索状态变化
-  - `didChangeCurrentSearchMatch`：当前搜索匹配项变化
-  - `didUpdateCurrentTableOfContentsItem`：翻页时匹配的目录项
-  - `didActivateExternalLink`：外部链接点击
-  - `didFailWithError`：解析或分页错误
-  - `configureTopToolView`：自定义顶部工具栏
+  - `epubReader(_:didOpen:)`：成功打开出版物
+  - `epubReader(_:didUpdateLocation:)`：翻页或滚动时位置更新
+  - `epubReaderDidReachEnd(_:)`：到达最后一页
+  - `epubReader(_:didChangeSelection:)`：文本选择变化或清除
+  - `epubReader(_:didUpdateHighlights:)`：高亮增删改
+  - `epubReader(_:didUpdateBookmarks:)`：书签增删改
+  - `epubReader(_:didUpdateSearchResult:)`：搜索状态变化
+  - `epubReader(_:didChangeCurrentSearchMatch:)`：当前搜索匹配项变化
+  - `epubReader(_:didUpdateCurrentTableOfContentsItem:)`：翻页时匹配的目录项
+  - `epubReader(_:didActivateExternalLink:)`：外部链接点击
+  - `epubReader(_:didFailWithError:)`：解析或分页错误
+  - `epubReader(_:configureTopToolView:)`：自定义顶部工具栏
 
 ### 2.4 持久化 `RDEPUBReaderPersistence`
 
 - 文件：`EPUBUI/RDEPUBReaderPersistence.swift`
-- 协议定义 6 个方法：loadLocation / saveLocation / loadHighlights / saveHighlights / loadReaderSettings / saveReaderSettings
+- 协议定义 8 个方法：loadLocation / saveLocation / loadHighlights / saveHighlights / loadBookmarks / saveBookmarks / loadReaderSettings / saveReaderSettings
 - 默认实现 `RDEPUBUserDefaultsPersistence`：
   - 位置：`ssreader.epub.location.<bookIdentifier>`（JSON 编码）
   - 高亮：`ssreader.epub.highlights.<bookIdentifier>`（JSON 编码）
+  - 书签：`ssreader.epub.bookmarks.<bookIdentifier>`（JSON 编码）
   - 设置：`ssreader.epub.settings`（全局，非按书）
 
 ### 2.5 主题 `RDEPUBReaderTheme`
 
-- 文件：`EPUBUI/RDEPUBReaderTheme.swift`
+- 文件：`EPUBUI/RDEPUBReaderTheme.swift`（~125 行）
 - 6 个颜色属性：contentBackgroundColor、contentTextColor、toolBackgroundColor、toolControlTextColor、toolControlBorderUnselectColor、toolLineColor
 - 6 个内置预设：`.light`、`.dark`、`.yellow`、`.green`、`.pink`、`.blue`
+- `RDEPUBReaderThemePreset` 枚举将预设映射为可序列化值，用于持久化
 - 计算属性 `themeBackgroundColorCSS` / `themeTextColorCSS` 用于 Web 渲染路径
 
 ### 2.6 设置面板 `RDEPUBReaderSettingsViewController`
 
-- 文件：`EPUBUI/RDEPUBReaderSettingsViewController.swift`
+- 文件：`EPUBUI/RDEPUBReaderSettingsViewController.swift`（~311 行）
 - 5 个控制项：
   - 亮度滑块（0-1）
   - 字号 A-/A+（范围 12-36，步长 1）
   - 行高分段（紧凑 1.3 / 标准 1.6 / 宽松 1.9）
   - 显示模式分段（仿真 / 横滑 / 竖滑 / 覆盖）
   - 主题选择（6 个圆形色块按钮）
-- 所有变更通过闭包实时回调
+- 所有变更通过闭包实时回调：onBrightnessChange / onFontSizeChange / onLineHeightChange / onDisplayTypeChange / onThemeChange
 
 ### 2.7 内容视图
 
@@ -88,10 +90,17 @@
 
 ### 2.8 其他 UI 组件
 
-- `RDEPUBReaderTopToolView`：顶部导航栏（返回按钮 + 标题）
-- `RDEPUBReaderBottomToolView`：底部工具栏（目录 / 批注 / 标注 / 设置 4 个按钮）
+- `RDEPUBReaderToolView`（`EPUBUI/RDEPUBReaderToolView.swift`）：工具栏基类，提供分隔线和主题适配的通用逻辑
+- `RDEPUBReaderTopToolView`：顶部导航栏（返回按钮 + 书签切换 + 标题）
+- `RDEPUBReaderBottomToolView`：底部工具栏（目录 / 书签 / 标注 / 设置 4 个按钮）
 - `RDEPUBReaderChapterListController`：目录列表（modal UITableViewController，当前项高亮 systemBlue）
 - `RDEPUBReaderHighlightsViewController`：标注管理（全部 / 批注 / 划线过滤，列表 + 编辑备注 + 删除 + 跳转，空态按过滤条件提示）
+- `RDEPUBReaderSettings`（`EPUBUI/RDEPUBReaderSettings.swift`）：可持久化用户设置模型（brightness / fontSize / lineHeightMultiple / displayMode / themePreset），含 `RDEPUBReaderDisplayMode` 和 `RDEPUBReaderThemePreset` 枚举
+- `RDEPUBReaderTableOfContentsItem`（`EPUBUI/RDEPUBReaderTableOfContentsItem.swift`）：展平后的目录条目（title / href / depth / pageNumber）
+- `RDEPUBPageInteractionController`（`EPUBUI/RDEPUBPageInteractionController.swift`）：CoreText 页面级交互控制器，处理文本选区和高亮装饰
+- `RDEPUBSelectionOverlayView`（`EPUBUI/RDEPUBSelectionOverlayView.swift`）：选区覆盖视图，显示选中文本的高亮装饰
+- `RDEPUBPageLayoutSnapshot`（`EPUBUI/RDEPUBPageLayoutSnapshot.swift`）：页面几何模型，存储 CoreText 渲染的页面布局信息
+- `RDURLReaderController`（`EPUBUI/RDURLReaderController.swift`，~221 行）：最简 URL 入口，传入 URL 即可打开书籍（.epub → RDEPUBReaderController，其他 → RDPlainTextBookBuilder 构建后传入），分页失败时回退到纯 UITextView 展示
 
 ## 3. 主流程（代码级）
 
@@ -229,22 +238,26 @@
 | 书签列表 | `ssreader.epub.bookmarks.<bookIdentifier>` | JSON → `[RDEPUBBookmark]` |
 | 阅读设置 | `ssreader.epub.settings` | JSON → `RDEPUBReaderSettings` |
 
-### 5.2 Book Identifier
-
-- 优先使用 `parser.metadata.identifier`
-- 回退使用 `epubURL.lastPathComponent`
-
-### 5.3 设置快照
+### 5.2 设置模型
 
 ```swift
 RDEPUBReaderSettings (Codable)
-  ├── brightness: CGFloat
-  ├── fontSize: CGFloat
-  ├── lineHeightMultiple: CGFloat
-  ├── displayMode: RDEPUBReaderDisplayMode
+  ├── brightness: CGFloat?
+  ├── fontSize: CGFloat?
+  ├── lineHeightMultiple: CGFloat?
+  ├── displayMode: RDEPUBReaderDisplayMode?
   └── themePreset: RDEPUBReaderThemePreset?
 ```
 
+`RDEPUBReaderDisplayMode`：可序列化的翻页模式枚举（pageCurl / horizontalScroll / verticalScroll / horizontalCoverScroll），与 `RDReaderView.DisplayType` 相互转换。
+
+`RDEPUBReaderThemePreset`：可序列化的主题预设枚举（light / yellow / green / pink / blue / dark），与 `RDEPUBReaderTheme` 相互转换。
+
+### 5.3 Book Identifier
+
+- 优先使用 `parser.metadata.identifier`
+- 回退使用 `epubURL.lastPathComponent`
+
 ### 5.4 目录扁平化项
 
 ```swift

Doc/EPUB_MAINTENANCE.md

@@ -15,20 +15,27 @@
 
 | 文件 | 职责 |
 |------|------|
-| `RDEPUBParser.swift` + 扩展 | EPUB 解压、container.xml、OPF、manifest、spine、TOC/NCX 解析 |
+| `RDEPUBParser.swift` + 5 扩展 | EPUB 解压、container.xml、OPF、manifest、spine、TOC/NCX 解析、阅读配置文件判断 |
 | `RDEPUBPublication.swift` | 解析结果的唯一聚合入口，外部不直接访问 parser 字段 |
 | `RDEPUBModels.swift` | metadata / manifest / spine / TOC 基础模型 |
-| `RDEPUBReadingModels.swift` | RDEPUBLocation、RDEPUBViewport、RDEPUBHighlight、选区模型 |
+| `RDEPUBReadingModels.swift` | RDEPUBLocation、RDEPUBViewport、RDEPUBHighlight、RDEPUBBookmark、选区模型 |
 | `RDEPUBResourceResolver.swift` | href → fileURL / schemeURL 的统一入口，`normalizedHref` 标准化路径 |
 | `RDEPUBPaginator.swift` | 离屏 WKWebView 分页，计算每个 spine 资源被视口切成多少页 |
 | `RDEPUBReadingSession.swift` | 状态机 + 会话协调，管理 staged/active/pending 页模型 |
 | `RDEPUBNavigatorState.swift` | 状态枚举（initializing/loading/idle/jumping/moving/repaginating） |
-| `RDEPUBWebView.swift` + 扩展 | 承载 spine 资源的 WKWebView，分页 CSS 注入、JS bridge、fixed wrapper |
+| `RDEPUBWebView.swift` + 5 扩展 | 承载 spine 资源的 WKWebView，分页 CSS 注入、JS bridge、fixed wrapper、搜索装饰 |
 | `RDEPUBResourceURLSchemeHandler.swift` | `ss-reader://` 协议，从本地解压目录提供所有 EPUB 资源 |
 | `RDEPUBStyleSheetBuilder.swift` | 生成注入 WebView 的 CSS |
 | `RDEPUBJavaScriptBridge.swift` | JS ↔ Swift 消息定义和编解码 |
 | `RDEPUBSearchEngine.swift` | 搜索协议定义 + WebView 全文搜索引擎 |
 | `RDEPUBSearchModels.swift` | 搜索模型（SearchMatch/Result/State/Presentation） |
+| `RDEPUBTextAnchor.swift` | 文本锚点和范围锚点（精确定位字符位置） |
+| `RDEPUBRenderRequest.swift` | 渲染请求模型、展示样式、固定版式适配/Spread 枚举 |
+| `RDEPUBWebViewDebug.swift` | WebView 调试日志工具（导航/JS/消息/Scheme） |
+| `RDEPUBAssetRepository.swift` | 静态资源加载器（JS 脚本、HTML 模板、模板变量替换） |
+| `RDEPUBPreferences.swift` | 用户阅读偏好聚合 |
+| `RDEPUBNavigatorLayoutContext.swift` | 容器布局上下文 |
+| `RDEPUBFixedLayoutTemplate.swift` | 固定版式 HTML 模板生成 |
 
 ### 2.2 EPUBTextRendering 层
 
@@ -39,17 +46,38 @@
 | `RDEPUBTextRendererSupport.swift` | fragment 标记注入、fragment offset 提取、属性标准化 |
 | `RDEPUBTextPaginationSupport.swift` | NSAttributedString 切页算法 |
 | `RDEPUBTextBookBuilder.swift` | 驱动逐章节渲染和分页，生成 RDEPUBTextBook |
+| `RDEPUBTextLayouter.swift` | CoreText 分页引擎（~810 行，含 4 级语义边界调整） |
+| `RDEPUBTextLayoutFrame.swift` | 单帧分页结果模型（contentRange、breakReason、语义提示） |
+| `RDEPUBTextBookCache.swift` | 分页结果磁盘缓存 |
+| `RDEPUBChapterData.swift` | 章节数据聚合模型（高亮、搜索结果、页面查询） |
+| `RDEPUBTextSearchEngine.swift` | 纯文本全文搜索引擎 |
+| `RDPlainTextBookBuilder.swift` | 纯文本（.txt）书籍构建器 |
+| `RDEPUBTextIndexTable.swift` | 全书文本索引表（章节偏移、行列映射、锚点转换） |
+| `RDEPUBTextPerformanceSampler.swift` | 性能采样器（渲染/分页耗时、缓存命中率） |
 
 ### 2.3 EPUBUI 层
 
 | 文件 | 职责 |
 |------|------|
-| `RDEPUBReaderController.swift` | 开箱即用读者控制器，整合 session / readerView / UI |
-| `RDEPUBReaderConfiguration.swift` | 外部配置项（字号、主题、翻页模式等） |
-| `RDEPUBReaderPersistence.swift` | 阅读位置和高亮的本地持久化 |
-| `RDEPUBReaderSettings.swift` | 运行时设置状态 |
+| `RDEPUBReaderController.swift` | 开箱即用读者控制器（~1995 行），整合 session / readerView / UI |
+| `RDEPUBReaderConfiguration.swift` | 外部配置项（13 个：字号、主题、翻页模式等） |
+| `RDEPUBReaderPersistence.swift` | 阅读位置、高亮、书签的本地持久化（8 个方法） |
+| `RDEPUBReaderSettings.swift` | 可持久化用户设置模型 + DisplayMode/ThemePreset 枚举 |
+| `RDEPUBReaderTheme.swift` | 6 个内置主题预设 + 颜色属性 |
+| `RDEPUBReaderDelegate.swift` | 12 个可选委托方法 |
+| `RDEPUBReaderToolView.swift` | 工具栏基类（分隔线 + 主题适配） |
+| `RDEPUBReaderTopToolView.swift` | 顶部导航栏（返回 + 书签 + 标题） |
+| `RDEPUBReaderBottomToolView.swift` | 底部工具栏（目录/书签/标注/设置） |
+| `RDEPUBReaderChapterListController.swift` | 目录列表面板 |
+| `RDEPUBReaderHighlightsViewController.swift` | 标注管理面板（过滤、编辑、删除、跳转） |
+| `RDEPUBReaderSettingsViewController.swift` | 设置面板（亮度、字号、行高、模式、主题） |
+| `RDEPUBReaderTableOfContentsItem.swift` | 展平目录条目模型 |
 | `RDEPUBWebContentView.swift` | WKWebView 内容视图，供 RDReaderView 渲染 WebView 类 spine |
-| `RDEPUBTextContentView.swift` | 文本内容视图，供 RDReaderView 渲染文本类 spine |
+| `RDEPUBTextContentView.swift` | 文本内容视图（~728 行），供 RDReaderView 渲染文本类 spine |
+| `RDEPUBPageInteractionController.swift` | CoreText 页面级交互控制器 |
+| `RDEPUBSelectionOverlayView.swift` | 选区覆盖视图 |
+| `RDEPUBPageLayoutSnapshot.swift` | 页面几何模型 |
+| `RDURLReaderController.swift` | 最简 URL 入口（.epub/.txt 自动识别） |
 
 ---
 
@@ -289,7 +317,7 @@ webView.loadHTMLString(htmlString, baseURL: nil)
 
 ## 7. 后续扩展建议
 
-1. **拆分 demo 层 RDReaderController**：约 1900+ 行，EPUB 加载、UI、数据源职责仍混在一起，建议继续向 library 层迁移
+1. **拆分 RDEPUBReaderController**：约 1995 行，EPUB 加载、UI、数据源职责仍混在一起，建议继续向 library 层迁移
 2. **基线验证**：用四本样书跑一轮分页耗时、目录命中率、末页事件、设置恢复稳定性数据
 3. **横竖屏支持回归矩阵**：控制器级 `viewWillTransition()` 与 viewport 去重已接入，下一步重点是补齐 pageCurl / scroll、三条正文路径和 iPad 视口变化场景的固定回归
 4. **Pod 分层**：评估是否将 EPUBCore / EPUBTextRendering / EPUBUI 拆为独立 subspec

Doc/RDReaderView_功能实现逻辑.md

@@ -2,7 +2,7 @@
 
 ## 1. 范围与目标
 
-- 代码范围：`Sources/RDReaderView/` 根目录（6 个 Swift 文件）
+- 代码范围：`Sources/RDReaderView/ReaderView/`（5 个 Swift 文件）
 - 目标：说明分页阅读器容器如何管理四种显示模式、DataSource/Delegate 协议、翻页交互、工具栏动画、双屏适配和 RTL 支持。
 - 主链路关键词：`RDReaderDataSource -> reloadData -> DisplayType 切换 -> 翻页/滚动 -> RDReaderDelegate.pageNum -> 工具栏显隐`。
 
@@ -10,7 +10,7 @@
 
 ### 2.1 核心容器 `RDReaderView`
 
-- 文件：`Sources/RDReaderView/RDReaderView.swift`（~717 行）
+- 文件：`Sources/RDReaderView/ReaderView/RDReaderView.swift`（~1219 行）
 - 入口方法：`reloadData()`
 - 职责：
   - 管理四种显示模式的视图层级切换
@@ -23,7 +23,7 @@
 
 ### 2.2 自定义布局 `RDReaderFlowLayout`
 
-- 文件：`Sources/RDReaderView/RDReaderFlowLayout.swift`（~387 行）
+- 文件：`Sources/RDReaderView/ReaderView/RDReaderFlowLayout.swift`（~375 行）
 - 职责：
   - 继承 `UICollectionViewFlowLayout`，为三种滚动模式提供布局计算
   - 水平滚动：全屏宽 item，pagingEnabled
@@ -33,7 +33,7 @@
 
 ### 2.3 内容 Cell `RDReaderContentCell`
 
-- 文件：`Sources/RDReaderView/RDReaderContentCell.swift`（~37 行）
+- 文件：`Sources/RDReaderView/ReaderView/RDReaderContentCell.swift`（~55 行）
 - 职责：
   - `UICollectionViewCell` 子类，作为内容视图的薄壳宿主
   - `containerView` 属性 setter 自动移除旧视图、添加新视图
@@ -41,7 +41,7 @@
 
 ### 2.4 页面子控制器 `RDReaderPageChildViewController`
 
-- 文件：`Sources/RDReaderView/RDReaderPageChildViewController.swift`（~65 行）
+- 文件：`Sources/RDReaderView/ReaderView/RDReaderPageChildViewController.swift`（~89 行）
 - 职责：
   - 仅用于 pageCurl 模式，作为 `UIPageViewController` 的子控制器
   - 持有 `contentView: UIView?` 和 `pageNum: Int`
@@ -49,21 +49,11 @@
 
 ### 2.5 手势控制器 `RDReaderGestureController`
 
-- 文件：`Sources/RDReaderView/RDReaderGestureController.swift`（~42 行）
+- 文件：`Sources/RDReaderView/ReaderView/RDReaderGestureController.swift`（~58 行）
 - 职责：
   - 当前为占位组件，存储 topToolView / bottomToolView 引用
   - 实际手势逻辑在 `RDReaderView.tapCenter()` 中实现
 
-### 2.6 URL 入口 `RDURLReaderController`
-
-- 文件：`Sources/RDReaderView/RDURLReaderController.swift`（~105 行）
-- 职责：
-  - 最简入口：传入 URL 即可打开书籍
-  - `.epub` 扩展名 → 创建 `RDEPUBReaderController(epubURL:configuration:)`
-  - 其他扩展名 → 使用 `RDPlainTextBookBuilder` 构建 `RDEPUBTextBook`，然后创建 `RDEPUBReaderController(textBook:bookIdentifier:title:textFileURL:configuration:)`
-  - 分页失败时回退到纯 `UITextView` 展示（尝试 UTF-8 → GBK → GB2312 解码）
-  - 导航栏标题设为文件名（去掉扩展名）
-
 ## 3. 主流程（代码级）
 
 ### 3.1 协议定义

Doc/index.md

@@ -12,10 +12,10 @@
 
 | 文档 | 对应模块 | 说明 |
 |------|----------|------|
-| [EPUBCore_功能实现逻辑.md](EPUBCore_功能实现逻辑.md) | `Sources/RDReaderView/EPUBCore/`（30 文件） | EPUB 解析全流程（ZIP→container.xml→OPF→spine/TOC）、阅读会话状态机、离屏分页测量、`ss-reader://` 资源协议、JS 桥接（6 种消息）、WebView 渲染管线、缓存策略 |
-| [EPUBTextRendering_功能实现逻辑.md](EPUBTextRendering_功能实现逻辑.md) | `Sources/RDReaderView/EPUBTextRendering/`（9 文件） | DTCoreText HTML→NSAttributedString 渲染管线、片段标记注入/提取、CoreText 分页引擎（含语义边界调整）、Location↔PageNumber 双向转换、全文搜索引擎、纯文本构建器 |
-| [RDReaderView_功能实现逻辑.md](RDReaderView_功能实现逻辑.md) | `Sources/RDReaderView/` 根目录（6 文件） | 四种显示模式（pageCurl/horizontalScroll/verticalScroll/horizontalCoverScroll）、DataSource/Delegate 协议、点击三区域翻页、工具栏动画、双页配对与哨兵页、横竖屏适配、RTL 支持 |
-| [EPUBUI_功能实现逻辑.md](EPUBUI_功能实现逻辑.md) | `Sources/RDReaderView/EPUBUI/`（16 文件） | RDEPUBReaderController 全生命周期、三条渲染路径分发、配置变更检测与响应、工具栏/目录/高亮/搜索/设置面板交互流、阅读位置持久化、主题管理 |
+| [EPUBCore_功能实现逻辑.md](EPUBCore_功能实现逻辑.md) | `Sources/RDReaderView/EPUBCore/`（31 Swift + 2 资源） | EPUB 解析全流程（ZIP→container.xml→OPF→spine/TOC）、阅读会话状态机、离屏分页测量、`ss-reader://` 资源协议、JS 桥接（6 种消息）、WebView 渲染管线、文本锚点定位、渲染请求模型、缓存策略 |
+| [EPUBTextRendering_功能实现逻辑.md](EPUBTextRendering_功能实现逻辑.md) | `Sources/RDReaderView/EPUBTextRendering/`（13 文件） | DTCoreText HTML→NSAttributedString 渲染管线、片段标记注入/提取、CoreText 分页引擎（含语义边界调整）、文本索引表、Location↔PageNumber 双向转换、分页缓存、性能采样、全文搜索引擎、纯文本构建器 |
+| [RDReaderView_功能实现逻辑.md](RDReaderView_功能实现逻辑.md) | `Sources/RDReaderView/ReaderView/`（5 文件） | 四种显示模式（pageCurl/horizontalScroll/verticalScroll/horizontalCoverScroll）、DataSource/Delegate 协议、点击三区域翻页、工具栏动画、双页配对与哨兵页、横竖屏适配、RTL 支持 |
+| [EPUBUI_功能实现逻辑.md](EPUBUI_功能实现逻辑.md) | `Sources/RDReaderView/EPUBUI/`（19 文件） | RDEPUBReaderController 全生命周期、三条渲染路径分发、配置变更检测与响应、工具栏/目录/高亮/书签/搜索/设置面板交互流、阅读位置持久化、主题管理、CoreText 页面交互 |
 
 ## 方案讨论文档