refactor: 添加中文注释 + 优化模块结构

- 给全部 78 个 Swift 源文件添加详细的中文注释（文件级、类级、方法级）
- 删除 LegacyRDReaderController/ 死代码目录（16 文件 4592 行）
- 根目录翻页容器文件移入 ReaderView/ 目录
- Resources/ 移入 EPUBCore/Resources/（与使用者归属一致）
- RDEPUBTextIndexTable.swift 移入 EPUBTextRendering/（消除反向依赖）
- RDURLReaderController.swift 移入 EPUBUI/（入口控制器归入 UI 层）
- 更新 podspec 资源路径

Sources/RDReaderView/EPUBCore/RDEPUBAssetRepository.swift

@@ -1,9 +1,18 @@
+// RDEPUBAssetRepository.swift
+// EPUBCore 静态资源仓库
+// 负责从资源包中加载 EPUB 渲染所需的 JS 桥接脚本和固定版式 HTML 模板，
+// 支持模板变量替换（{{token}} 占位符）。
+
 import Foundation
 
+/// EPUB 内置资源枚举，定义桥接脚本和固定版式模板的文件名及扩展名
 enum RDEPUBAsset: String {
+    /// JS 桥接脚本（epub-bridge.js），注入到 WebView 中实现原生-JS 通信
     case bridgeScript = "epub-bridge"
+    /// 固定版式 HTML 模板（epub-fixed-layout.html），用于渲染 pre-paginated 类型的 EPUB
     case fixedLayoutTemplate = "epub-fixed-layout"
 
+    /// 对应的文件扩展名
     var fileExtension: String {
         switch self {
         case .bridgeScript:
@@ -14,7 +23,13 @@ enum RDEPUBAsset: String {
     }
 }
 
+/// 静态资源加载器，负责从资源包中读取模板文件并执行变量替换
 enum RDEPUBAssetRepository {
+    /// 加载指定资源文件的内容，并将 {{key}} 占位符替换为对应的值
+    /// - Parameters:
+    ///   - asset: 要加载的资源类型
+    ///   - replacements: 模板变量字典，key 为占位符名称，value 为替换值
+    /// - Returns: 替换后的文件内容字符串
     static func string(for asset: RDEPUBAsset, replacements: [String: String] = [:]) -> String {
         guard let url = resourceBundle.url(forResource: asset.rawValue, withExtension: asset.fileExtension),
               var content = try? String(contentsOf: url, encoding: .utf8) else {
@@ -28,6 +43,7 @@ enum RDEPUBAssetRepository {
         return content
     }
 
+    /// 获取资源所在的 Bundle（优先使用已解析的子 bundle，兜底到宿主 bundle）
     private static var resourceBundle: Bundle {
         if let bundle = resolvedBundle {
             return bundle
@@ -35,6 +51,7 @@ enum RDEPUBAssetRepository {
         return Bundle(for: RDEPUBAssetBundleToken.self)
     }
 
+    /// 延迟解析 RDReaderViewAssets.bundle 的位置，在宿主 bundle 和所有 framework 中查找
     private static var resolvedBundle: Bundle? = {
         let hostBundles = [Bundle(for: RDEPUBAssetBundleToken.self), Bundle.main] + Bundle.allFrameworks + Bundle.allBundles
         for hostBundle in hostBundles {
@@ -47,4 +64,5 @@ enum RDEPUBAssetRepository {
     }()
 }
 
+/// 用于定位当前模块 Bundle 的标记类
 private final class RDEPUBAssetBundleToken {}

Sources/RDReaderView/EPUBCore/RDEPUBFixedLayoutTemplate.swift

@@ -1,12 +1,25 @@
+// RDEPUBFixedLayoutTemplate.swift
+// 固定版式（Fixed Layout）HTML 模板生成器
+// 根据渲染请求和 Publication 信息，将 iframe 拼装到 HTML 模板中，
+// 生成适配视口尺寸和内边距的固定版式页面 HTML。
+
 import Foundation
 
+/// 固定版式模板生成器，负责将 spine 资源渲染为 iframe 嵌套的 HTML 页面
 enum RDEPUBFixedLayoutTemplate {
+    /// 根据渲染请求和 Publication 生成固定版式页面的完整 HTML
+    /// - Parameters:
+    ///   - request: 固定版式渲染请求（含 spread、视口尺寸、内边距、适配模式等）
+    ///   - publication: EPUB 出版物，用于解析资源 URL
+    /// - Returns: 完整的 HTML 字符串
     static func html(for request: RDEPUBFixedRenderRequest, publication: RDEPUBPublication) -> String {
+        // 遍历 spread 中的每个资源，生成对应的 iframe pane HTML
         let panes = request.spread.resources.enumerated().compactMap { index, resource -> String? in
             guard let url = publication.resourceResolver.resourceURL(forRelativePath: resource.href)?.absoluteString else {
                 return nil
             }
 
+            // 根据 spread 中的资源数量判断页面类型：单页/左页/右页/居中
             let pageType: String
             if request.spread.resources.count == 1 {
                 pageType = "single"
@@ -23,6 +36,7 @@ enum RDEPUBFixedLayoutTemplate {
             """
         }.joined()
 
+        // 计算视口区域（去除内边距后的可用区域）
         let background = request.backgroundColorCSS ?? "#FFFFFF"
         let viewportWidth = max(1, Int((request.viewportSize.width - request.contentInset.left - request.contentInset.right).rounded(.down)))
         let viewportHeight = max(1, Int((request.viewportSize.height - request.contentInset.top - request.contentInset.bottom).rounded(.down)))
@@ -30,6 +44,7 @@ enum RDEPUBFixedLayoutTemplate {
         let insetRight = Int(request.contentInset.right.rounded(.down))
         let insetBottom = Int(request.contentInset.bottom.rounded(.down))
         let insetLeft = Int(request.contentInset.left.rounded(.down))
+        // 从资源仓库加载 HTML 模板并替换占位符
         return RDEPUBAssetRepository.string(
             for: .fixedLayoutTemplate,
             replacements: [

Sources/RDReaderView/EPUBCore/RDEPUBJavaScriptBridge.swift

@@ -1,19 +1,35 @@
+// RDEPUBJavaScriptBridge.swift
+// 原生与 WebView 之间的 JavaScript 桥接层
+// 定义所有 JS 消息类型（progression/selection/link/error 等），
+// 生成注入到 WebView 的用户脚本，以及分页渲染、搜索高亮等执行脚本。
+
 import Foundation
 
+/// JS 桥接消息类型枚举，每种消息对应 WebView 向原生发送的一种事件
 enum RDEPUBJavaScriptBridgeMessage: String, CaseIterable {
+    /// 阅读进度变化事件
     case progressionChanged = "ssReaderProgressionChanged"
+    /// 文本选择变化事件
     case selectionChanged = "ssReaderSelectionChanged"
+    /// 内部链接点击事件（ss-reader:// 协议）
     case internalLink = "ssReaderInternalLink"
+    /// 外部链接点击事件（http/https/mailto/tel）
     case externalLink = "ssReaderExternalLink"
+    /// JavaScript 运行时错误事件
     case javaScriptError = "ssReaderJSError"
+    /// 固定版式渲染就绪事件
     case fixedLayoutReady = "ssReaderFixedLayoutReady"
 }
 
+/// JavaScript 桥接工具集，负责生成注入脚本和执行脚本
 enum RDEPUBJavaScriptBridge {
+    /// 所有需要注册的 JS 消息名称列表，用于 WKUserContentController 注册
     static var messageNames: [String] {
         RDEPUBJavaScriptBridgeMessage.allCases.map(\.rawValue)
     }
 
+    /// 获取注入到 WebView 的桥接用户脚本（在 document end 注入）
+    /// 将消息类型占位符替换为实际值，使 JS 端能通过 window.webkit.messageHandlers 发送消息
     static var userScript: String {
         RDEPUBAssetRepository.string(
             for: .bridgeScript,
@@ -28,6 +44,10 @@ enum RDEPUBJavaScriptBridge {
         )
     }
 
+    /// 生成重排模式下的分页渲染脚本
+    /// 注入 CSS 分页样式、设置页码参数、高亮和目标位置，最后触发进度汇报
+    /// - Parameter request: 重排渲染请求，包含展示样式、高亮、目标位置等信息
+    /// - Returns: 可直接通过 evaluateJavaScript 执行的脚本字符串
     static func applyPresentationScript(for request: RDEPUBReflowableRenderRequest) -> String {
         let style = escapedJavaScriptTemplateLiteral(RDEPUBStyleSheetBuilder.renderCSS(for: request.presentation))
         let pageStride = max(1, request.presentation.viewportSize.width)
@@ -52,6 +72,11 @@ enum RDEPUBJavaScriptBridge {
         """
     }
 
+    /// 生成搜索高亮脚本
+    /// 在当前文档和所有 iframe 中查找关键词并用 span 标记高亮，
+    /// 活跃匹配项使用特殊样式并自动滚动到视图中央
+    /// - Parameter presentation: 搜索展示信息（关键词、各资源的匹配数量等）
+    /// - Returns: 搜索高亮脚本字符串
     static func applySearchScript(for presentation: RDEPUBSearchPresentation?) -> String {
         let payload = jsonString(from: searchPayload(presentation), fallback: "null")
         return """
@@ -213,12 +238,14 @@ enum RDEPUBJavaScriptBridge {
         """
     }
 
+    /// 转义字符串中的反斜杠和反引号，避免 JS 模板字面量语法错误
     private static func escapedJavaScriptTemplateLiteral(_ string: String) -> String {
         string
             .replacingOccurrences(of: "\\", with: "\\\\")
             .replacingOccurrences(of: "`", with: "\\`")
     }
 
+    /// 将高亮数组转换为 JS 可用的字典数组
     private static func highlightsPayload(_ highlights: [RDEPUBHighlight]) -> [[String: String]] {
         highlights.compactMap { highlight in
             guard let rangeInfo = highlight.rangeInfo, !rangeInfo.isEmpty else { return nil }
@@ -231,6 +258,7 @@ enum RDEPUBJavaScriptBridge {
         }
     }
 
+    /// 将目标位置转换为 JS 可用的字典（含 progression、fragment）
     private static func targetLocationPayload(_ location: RDEPUBLocation?) -> [String: Any]? {
         guard let location else { return nil }
         return [
@@ -240,6 +268,7 @@ enum RDEPUBJavaScriptBridge {
         ]
     }
 
+    /// 将搜索展示信息转换为 JS 可用的字典
     private static func searchPayload(_ presentation: RDEPUBSearchPresentation?) -> [String: Any]? {
         guard let presentation else { return nil }
         return [
@@ -254,6 +283,7 @@ enum RDEPUBJavaScriptBridge {
         ]
     }
 
+    /// 将任意对象序列化为 JSON 字符串，失败时返回 fallback
     private static func jsonString(from object: Any?, fallback: String) -> String {
         guard let object else { return fallback }
         guard JSONSerialization.isValidJSONObject(object),

Sources/RDReaderView/EPUBCore/RDEPUBModels.swift

@@ -1,36 +1,71 @@
+//
+//  RDEPUBModels.swift
+//  RDReaderView
+//
+//  EPUBCore 层核心数据模型定义文件。
+//  包含 EPUB 解析过程中所需的全部基础枚举和数据结构：
+//  布局类型、阅读方向、页面分布、元数据、清单项、Spine 项、目录项及解析错误类型。
+//  这些模型由 RDEPUBParser 解析后填充，并由 RDEPUBPublication 聚合对外暴露。
+//
+
 import Foundation
 
+/// EPUB 版面布局类型
+/// - reflowable: 可重排布局，内容根据屏幕尺寸和字号自动分页（小说类 EPUB）
+/// - fixed: 固定版式布局，页面尺寸固定不变（漫画、绘本类 EPUB）
 public enum RDEPUBLayout: String, Codable {
     case reflowable
     case fixed
 }
 
+/// 阅读配置文件类型，决定使用哪种渲染路径
+/// - webInteractive: 可重排 + 含交互脚本，使用 WKWebView 渲染
+/// - webFixedLayout: 固定版式 EPUB（漫画、绘本），使用 WKWebView 渲染
+/// - textReflowable: 纯文本可重排 EPUB，使用 DTCoreText 渲染（性能更优）
 public enum RDEPUBReadingProfile: String, Codable {
     case webInteractive
     case webFixedLayout
     case textReflowable
 }
 
+/// 阅读方向（文字排版方向）
+/// - ltr: 从左到右（英文、中文横排）
+/// - rtl: 从右到左（日文竖排、阿拉伯文）
+/// - auto: 根据语言自动判断
 public enum RDEPUBReadingProgression: String, Codable {
     case ltr
     case rtl
     case auto
 }
 
+/// 固定版式页面在 spread（双页展开）中的位置
+/// - left: 左页
+/// - right: 右页
+/// - center: 居中（跨页或单页居中）
 public enum RDEPUBPageSpread: String, Codable {
     case left
     case right
     case center
 }
 
+/// EPUB 出版物元数据，对应 OPF 文档中 <metadata> 节点的内容
+/// 包含书籍的基本信息：标识符、标题、作者、语言、版本、布局类型等
 public struct RDEPUBMetadata: Codable, Equatable {
+    /// 书籍唯一标识符（对应 <dc:identifier>）
     public var identifier: String?
+    /// 书名（对应 <dc:title>）
     public var title: String
+    /// 作者（对应 <dc:creator>）
     public var author: String?
+    /// 语言代码（对应 <dc:language>，如 "zh"、"en"）
     public var language: String?
+    /// EPUB 版本号（如 "2.0"、"3.0"）
     public var version: String?
+    /// 版面布局类型（reflowable 或 fixed）
     public var layout: RDEPUBLayout
+    /// spread 模式设置（对应 <meta property="rendition:spread">）
     public var spread: String?
+    /// 阅读方向（ltr / rtl / auto）
     public var readingProgression: RDEPUBReadingProgression
 
     public init(
@@ -54,13 +89,22 @@ public struct RDEPUBMetadata: Codable, Equatable {
     }
 }
 
+/// EPUB 清单项，对应 OPF 文档 <manifest> 中的每个 <item>
+/// 描述一个资源文件的 ID、路径、MIME 类型和附加属性
 public struct RDEPUBManifestItem: Codable, Equatable {
+    /// 清单项的唯一标识符（对应 <item id="...">）
     public var id: String
+    /// 资源文件路径，相对于 OPF 文件所在目录
     public var href: String
+    /// MIME 类型（如 "application/xhtml+xml"、"image/jpeg"、"text/css"）
     public var mediaType: String
+    /// 属性列表（如 "nav" 表示导航文档、"scripted" 表示含脚本、"cover-image" 表示封面）
     public var properties: [String]
+    /// 回退项 ID（对应 <item fallback="...">）
     public var fallback: String?
+    /// 媒体叠加文件 ID（EPUB 3 有声书功能）
     public var mediaOverlay: String?
+    /// 资源标题（用于搜索结果展示等辅助用途）
     public var title: String?
 
     public init(
@@ -81,23 +125,37 @@ public struct RDEPUBManifestItem: Codable, Equatable {
         self.title = title
     }
 
+    /// 是否为 EPUB 3 导航文档（Nav Document）
+    /// 通过检查 properties 中是否包含 "nav" 标记判断
     public var isNavigationDocument: Bool {
         properties.contains("nav")
     }
 
+    /// 是否为 NCX 目录文件（EPUB 2 格式）
+    /// 通过 MIME 类型 "application/x-dtbncx+xml" 判断
     public var isNCX: Bool {
         mediaType == "application/x-dtbncx+xml"
     }
 }
 
+/// EPUB Spine 项，对应 OPF 文档 <spine> 中的每个 <itemref>
+/// Spine 定义了阅读器中章节内容的线性阅读顺序
 public struct RDEPUBSpineItem: Codable, Equatable {
+    /// 对应 manifest 中的 item id（用于关联资源）
     public var idref: String
+    /// 标准化后的资源路径（相对于 OPF 文件所在目录）
     public var href: String
+    /// MIME 类型
     public var mediaType: String
+    /// 章节标题（从目录或 manifest 推断）
     public var title: String
+    /// 是否为线性内容（"no" 表示补充材料，不影响主线阅读进度）
     public var linear: Bool
+    /// 属性列表（如 rendition:layout-* 用于单页布局覆盖）
     public var properties: [String]
+    /// 页面在 spread 中的位置偏好（左页/右页/居中）
     public var pageSpread: RDEPUBPageSpread?
+    /// 单页布局覆盖（显式属性可覆盖出版级别的 layout 设置）
     public var layout: RDEPUBLayout?
 
     public init(
@@ -121,9 +179,14 @@ public struct RDEPUBSpineItem: Codable, Equatable {
     }
 }
 
+/// EPUB 目录项，支持树形层级结构
+/// 来源于 NCX 文件（EPUB 2）或 Nav Document（EPUB 3）的解析结果
 public struct EPUBTableOfContentsItem: Codable, Equatable {
+    /// 目录项标题（显示在目录面板中）
     public var title: String
+    /// 目标资源路径（含可能的 fragment 锚点）
     public var href: String
+    /// 子目录项列表（递归结构，支持多级目录）
     public var children: [EPUBTableOfContentsItem]
 
     public init(title: String, href: String, children: [EPUBTableOfContentsItem] = []) {
@@ -133,13 +196,21 @@ public struct EPUBTableOfContentsItem: Codable, Equatable {
     }
 }
 
+/// EPUB 解析器错误类型，涵盖从 ZIP 解压到 OPF 解析全链路的异常情况
 public enum RDEPUBParserError: LocalizedError {
+    /// ZIP 文件无法打开（文件损坏或格式不支持）
     case archiveOpenFailed(URL)
+    /// 缺少 META-INF/container.xml 文件（EPUB 格式不合规）
     case missingContainerXML
+    /// container.xml 中未找到 <rootfile> 元素
     case missingRootFile
+    /// OPF 根文件路径无效（文件不存在）
     case invalidRootFilePath(String)
+    /// XML 解析失败（格式错误或编码问题）
     case invalidXML(URL)
+    /// spine 中引用的 manifest 项不存在（idref 不匹配）
     case missingManifestItem(idref: String)
+    /// 构建完成的 spine 为空（无可阅读的内容）
     case emptySpine
 
     public var errorDescription: String? {

Sources/RDReaderView/EPUBCore/RDEPUBNavigatorLayoutContext.swift

@@ -1,10 +1,22 @@
+// RDEPUBNavigatorLayoutContext.swift
+// 导航器布局上下文
+// 封装阅读器容器的布局参数：容器尺寸、每屏页数、安全区域、设备类型、
+// 重排内容内边距等，供 Paginator 和渲染层使用。
+
 import UIKit
 
+/// 导航器布局上下文，描述阅读器容器的布局参数
+/// 在 Paginator 计算分页和 WebView 渲染时作为核心输入
 public struct RDEPUBNavigatorLayoutContext: Equatable {
+    /// 容器视图的总尺寸
     public var containerSize: CGSize
+    /// 每屏显示的页数（横屏双页模式为 2）
     public var pagesPerScreen: Int
+    /// 安全区域内边距（刘海屏、Home Indicator 等）
     public var safeAreaInsets: UIEdgeInsets
+    /// 用户界面设备类型（phone/pad）
     public var userInterfaceIdiom: UIUserInterfaceIdiom
+    /// 重排模式下的内容内边距（上下左右留白）
     public var reflowableContentInsets: UIEdgeInsets
 
     public init(
@@ -21,6 +33,7 @@ public struct RDEPUBNavigatorLayoutContext: Equatable {
         self.reflowableContentInsets = reflowableContentInsets
     }
 
+    /// 计算单页视口尺寸（双页模式下宽度除以 2）
     public var viewportSize: CGSize {
         let width: CGFloat
         if pagesPerScreen > 1 {
@@ -31,6 +44,7 @@ public struct RDEPUBNavigatorLayoutContext: Equatable {
         return CGSize(width: width, height: containerSize.height)
     }
 
+    /// 固定版式模式下的内容内边距（仅手机端使用安全区域，Pad 端归零；左右取较大值对称）
     public var fixedContentInset: UIEdgeInsets {
         var insets = safeAreaInsets
         if userInterfaceIdiom != .phone {

Sources/RDReaderView/EPUBCore/RDEPUBNavigatorState.swift

@@ -1,13 +1,33 @@
+//
+//  RDEPUBNavigatorState.swift
+//  RDReaderView
+//
+//  EPUBCore 层导航状态机定义文件。
+//  定义了阅读器导航器的状态枚举，状态流转遵循：
+//  initializing → loading → idle ↔ jumping/moving/repaginating
+//  由 RDEPUBReadingSession 管理状态跃迁，控制分页快照的应用时机。
+//
+
 import Foundation
 
+/// 导航状态枚举，描述阅读器的当前操作状态
+/// 状态机流转：initializing → loading → idle ↔ jumping/moving/repaginating
 public enum RDEPUBNavigatorState: String, Codable {
+    /// 初始化状态，刚打开书籍，等待初始恢复位置
     case initializing
+    /// 加载状态，正在生成首轮分页模型
     case loading
+    /// 空闲状态，显示稳定，可接受用户操作和快照应用
     case idle
+    /// 跳转状态，正在执行目录/内部链接跳转
     case jumping
+    /// 翻页状态，用户正在翻页操作中
     case moving
+    /// 重排状态，正在重新分页（字号/横竖屏变化触发）
     case repaginating
 
+    /// 是否处于可应用分页快照的稳定状态
+    /// 只有 idle 状态才允许消费 staged snapshot
     public var isStableForSnapshotApplication: Bool {
         self == .idle
     }

Sources/RDReaderView/EPUBCore/RDEPUBPaginator.swift

@@ -1,25 +1,45 @@
+// RDEPUBPaginator.swift
+// EPUB 离屏分页计算器
+// 使用隐藏的 WKWebView 加载每个 spine 项，通过 JS 测量 scrollWidth
+// 计算每章的页数。采用多轮延迟测量（0ms/80ms/180ms）确保布局稳定。
+// 固定版式（Fixed Layout）直接返回 1 页。
+
 import UIKit
 import WebKit
 
+/// EPUB 分页计算器，通过离屏 WebView 测量每个 spine 项的分页数
 public final class RDEPUBPaginator: NSObject {
+    /// 当前解析器引用
     private var parser: RDEPUBParser?
+    /// 承载 WebView 的父视图（弱引用）
     private weak var hostingView: UIView?
+    /// 当前展示样式（视口尺寸、内边距、字号、行高）
     private var presentation = RDEPUBPresentationStyle(
         viewportSize: .zero,
         contentInsets: .zero,
         fontSize: 16,
         lineHeightMultiple: 1.5
     )
+    /// 全量分页完成回调（返回每个 spine 项的页数数组）
     private var completion: (([Int]) -> Void)?
+    /// 单个 spine 项分页完成回调
     private var singlePageCountCompletion: ((Int) -> Void)?
+    /// 各 spine 项的页数结果
     private var pageCounts: [Int] = []
+    /// 待测量的 spine 项索引列表
     private var measurementIndices: [Int] = []
+    /// 当前测量偏移量（在 measurementIndices 中的位置）
     private var currentMeasurementOffset = 0
+    /// 当前 spine 项的待定页数（多轮测量取最大值）
     private var pendingMeasurementValue = 1
+    /// 当前测量轮次（0/1/2 对应延迟 0ms/80ms/180ms）
     private var measurementPass = 0
+    /// 当前测量会话 ID，用于防并发和取消过期任务
     private var activeSessionID = UUID()
+    /// 调试日志作用域标识
     private let debugScope = "PaginatorWebView"
 
+    /// 用于分页测量的隐藏 WebView（非持久化数据存储，禁止用户交互）
     private lazy var webView: WKWebView = {
         let configuration = WKWebViewConfiguration()
         configuration.websiteDataStore = .nonPersistent()
@@ -52,6 +72,12 @@ public final class RDEPUBPaginator: NSObject {
         webView.removeFromSuperview()
     }
 
+    /// 计算所有 spine 项的分页数
+    /// - Parameters:
+    ///   - parser: EPUB 解析器
+    ///   - hostingView: 承载 WebView 的父视图
+    ///   - presentation: 展示样式（视口、内边距、字号、行高）
+    ///   - completion: 完成回调，返回每个 spine 项的页数数组
     public func calculate(
         parser: RDEPUBParser,
         hostingView: UIView,
@@ -82,6 +108,7 @@ public final class RDEPUBPaginator: NSObject {
         measureNextSpineItem()
     }
 
+    /// 便捷方法：使用独立参数计算所有 spine 项的分页数
     public func calculate(
         parser: RDEPUBParser,
         hostingView: UIView,
@@ -104,6 +131,13 @@ public final class RDEPUBPaginator: NSObject {
         )
     }
 
+    /// 仅计算单个 spine 项的分页数
+    /// - Parameters:
+    ///   - parser: EPUB 解析器
+    ///   - spineIndex: 要测量的 spine 项索引
+    ///   - hostingView: 承载 WebView 的父视图
+    ///   - presentation: 展示样式
+    ///   - completion: 完成回调，返回该 spine 项的页数
     public func calculateSingleSpinePageCount(
         parser: RDEPUBParser,
         spineIndex: Int,
@@ -135,6 +169,7 @@ public final class RDEPUBPaginator: NSObject {
         measureNextSpineItem()
     }
 
+    /// 便捷方法：使用独立参数计算单个 spine 项的分页数
     public func calculateSingleSpinePageCount(
         parser: RDEPUBParser,
         spineIndex: Int,
@@ -159,6 +194,7 @@ public final class RDEPUBPaginator: NSObject {
         )
     }
 
+    /// 静态方法：将分页 CSS 注入到 HTML 字符串中（用于预渲染场景）
     public static func injectPaginationCSS(
         into html: String,
         viewportSize: CGSize,
@@ -181,6 +217,7 @@ public final class RDEPUBPaginator: NSObject {
         )
     }
 
+    /// 测量下一个 spine 项：加载文件到 WebView，跳过不可渲染或文件缺失的项
     private func measureNextSpineItem() {
         guard let parser else {
             finishIfNeeded()
@@ -218,10 +255,12 @@ public final class RDEPUBPaginator: NSObject {
         webView.loadFileURL(fileURL, allowingReadAccessTo: readAccessURL)
     }
 
+    /// 获取当前正在测量的 spine 项索引
     private func currentSpineIndexForMeasurement() -> Int? {
         measurementIndices[safe: currentMeasurementOffset]
     }
 
+    /// 检查是否所有 spine 项都已测量完毕，触发对应的完成回调
     private func finishIfNeeded() {
         if let singlePageCountCompletion {
             let measuredSpineIndex = measurementIndices.first ?? 0
@@ -236,6 +275,7 @@ public final class RDEPUBPaginator: NSObject {
         cleanupMeasurementState()
     }
 
+    /// 清理测量状态，释放 WebView 和所有引用
     private func cleanupMeasurementState() {
         parser = nil
         hostingView = nil
@@ -251,11 +291,13 @@ public final class RDEPUBPaginator: NSObject {
         webView.removeFromSuperview()
     }
 
+    /// 判断 spine 项是否可渲染（仅 HTML/XHTML/XML 类型可分页）
     private func isRenderablePage(item: RDEPUBSpineItem) -> Bool {
         let mediaType = item.mediaType.lowercased()
         return mediaType.contains("html") || mediaType.contains("xhtml") || mediaType.contains("xml")
     }
 
+    /// 调度多轮测量：0ms/80ms/180ms 三轮延迟，取最大值以应对布局抖动
     private func scheduleMeasurementPass() {
         let sessionID = activeSessionID
         let delays: [TimeInterval] = [0.0, 0.08, 0.18]
@@ -278,6 +320,7 @@ public final class RDEPUBPaginator: NSObject {
         }
     }
 
+    /// 执行当前文档的测量：通过 JS 获取 scrollWidth 并计算页数
     private func measureCurrentDocument(sessionID: UUID) {
         let script = RDEPUBStyleSheetBuilder.measurementScript(for: presentation)
         RDEPUBWebViewDebug.logJavaScript(debugScope, webView: webView, action: "measure", details: "session=\(sessionID) pass=\(measurementPass)")
@@ -332,6 +375,7 @@ extension RDEPUBPaginator: WKNavigationDelegate {
     }
 }
 
+/// Array 安全下标扩展，越界时返回 nil 而非崩溃
 private extension Array {
     subscript(safe index: Int) -> Element? {
         indices.contains(index) ? self[index] : nil

Sources/RDReaderView/EPUBCore/RDEPUBParser+Archive.swift

@@ -1,7 +1,15 @@
+// RDEPUBParser+Archive.swift
+// EPUB 归档解压与 container.xml 解析
+// 负责将 EPUB ZIP 文件解压到缓存目录（~/Library/Caches/ssreaderview-epub/），
+// 并解析 META-INF/container.xml 获取 OPF 文件路径。
+
 import Foundation
 import ZIPFoundation
 
 extension RDEPUBParser {
+    /// 解析 container.xml，提取 OPF（Package Document）的相对路径
+    /// - Parameter containerURL: container.xml 的文件路径
+    /// - Returns: OPF 文件的相对路径（如 "OEBPS/content.opf"）
     func parseContainerRootFile(at containerURL: URL) throws -> String {
         guard let parser = XMLParser(contentsOf: containerURL) else {
             throw RDEPUBParserError.invalidXML(containerURL)
@@ -22,6 +30,10 @@ extension RDEPUBParser {
         return rootFilePath
     }
 
+    /// 解压 EPUB ZIP 文件到缓存目录（幂等：已存在则跳过）
+    /// 目录名由 slug + 文件大小 + 修改时间戳组成，避免冲突
+    /// - Parameter epubURL: EPUB 文件路径
+    /// - Returns: 解压目标目录 URL
     func extractArchiveIfNeeded(epubURL: URL) throws -> URL {
         let fileManager = FileManager.default
         let extractionURL = temporaryExtractionDirectory(for: epubURL)
@@ -52,6 +64,8 @@ extension RDEPUBParser {
         return extractionURL
     }
 
+    /// 计算 EPUB 的临时解压目录路径
+    /// 路径格式：~/Library/Caches/ssreaderview-epub/{slug}-{fileSize}-{modifiedTimestamp}/
     func temporaryExtractionDirectory(for epubURL: URL) -> URL {
         let baseURL = FileManager.default.urls(for: .cachesDirectory, in: .userDomainMask).first?
             .appendingPathComponent("ssreaderview-epub", isDirectory: true)
@@ -65,12 +79,14 @@ extension RDEPUBParser {
         return baseURL.appendingPathComponent("\(slug)-\(fileSize)-\(signature)", isDirectory: true)
     }
 
+    /// 重置解析器状态（清除解压路径和出版物数据）
     func reset() {
         extractionRootURL = nil
         opfURL = nil
         resetPublicationState()
     }
 
+    /// 重置出版物相关状态（metadata、manifest、spine、目录）
     func resetPublicationState() {
         metadata = RDEPUBMetadata()
         manifest = [:]
@@ -79,7 +95,9 @@ extension RDEPUBParser {
     }
 }
 
+/// container.xml 的 SAX 解析代理，提取 <rootfile> 元素的 full-path 属性
 private final class ContainerXMLParserDelegate: NSObject, XMLParserDelegate {
+    /// 解析得到的 OPF 文件相对路径
     private(set) var rootFilePath: String?
 
     func parser(

Sources/RDReaderView/EPUBCore/RDEPUBParser+Package.swift

@@ -1,6 +1,18 @@
+// RDEPUBParser+Package.swift
+// OPF（Package Document）解析与 Spine 构建
+// 包含 OPFPackageParserDelegate（SAX 解析 metadata/manifest/spine），
+// 从解析结果构建 RDEPUBSpineItem 数组，处理 rendition:layout、page-spread 等属性。
+// 同时定义 XMLName、XMLSection、XMLParserContext 等 XML 解析辅助工具。
+
 import Foundation
 
 extension RDEPUBParser {
+    /// 从 OPF 解析结果构建 spine 阅读顺序数组
+    /// 逐项匹配 manifest，解析 href、布局模式（fixed/reflowable）、page-spread 等属性
+    /// - Parameters:
+    ///   - packageDocument: OPF 解析结果（含 metadata、manifest、spineReferences）
+    ///   - opfURL: OPF 文件路径
+    /// - Returns: spine 项数组
     func buildSpine(from packageDocument: OPFPackageDocument, opfURL: URL) throws -> [RDEPUBSpineItem] {
         let opfDirectoryURL = opfURL.deletingLastPathComponent()
         let publicationLayout = packageDocument.metadata.layout
@@ -50,22 +62,33 @@ extension RDEPUBParser {
     }
 }
 
+/// OPF 包文档的解析结果，包含 metadata、manifest、spine 引用及 NCX/nav 项
 struct OPFPackageDocument {
     var metadata: RDEPUBMetadata
     var manifest: [RDEPUBManifestItem]
     var manifestByID: [String: RDEPUBManifestItem]
     var spineReferences: [OPFSpineReference]
+    /// NCX 目录文件的 manifest 项（EPUB 2）
     var ncxItem: RDEPUBManifestItem?
+    /// Navigation Document 的 manifest 项（EPUB 3）
     var navigationItem: RDEPUBManifestItem?
 }
 
+/// OPF 中 spine/itemref 元素的解析结果
 struct OPFSpineReference {
+    /// 对应 manifest 中的 item id
     var idref: String
+    /// 是否为线性阅读项（"no" 表示辅助内容）
     var linear: Bool
+    /// 属性列表（如 rendition:layout-pre-paginated、page-spread-left 等）
     var properties: [String]
+    /// 页面展开方向（左/右/居中）
     var pageSpread: RDEPUBPageSpread?
 }
 
+/// OPF 文档的 SAX 解析代理
+/// 解析 metadata（identifier/title/creator/language/rendition:layout 等）、
+/// manifest（item 元素）、spine（itemref 元素）三个主要区域
 final class OPFPackageParserDelegate: NSObject, XMLParserDelegate {
     private var metadata = RDEPUBMetadata()
     private var manifestItems: [RDEPUBManifestItem] = []
@@ -79,6 +102,7 @@ final class OPFPackageParserDelegate: NSObject, XMLParserDelegate {
     private var currentMetaRefinesID: String?
     private var ncxID: String?
 
+    /// 将解析中间结果组装为 OPFPackageDocument 结构体
     func packageDocument() -> OPFPackageDocument {
         if metadata.identifier == nil, let fallbackIdentifier = identifierByID.values.first {
             metadata.identifier = fallbackIdentifier
@@ -227,6 +251,7 @@ final class OPFPackageParserDelegate: NSObject, XMLParserDelegate {
         xmlContext.endElement()
     }
 
+    /// 当前解析所在的 OPF 区域（metadata/manifest/spine/other）
     private var currentSection: XMLSection {
         if xmlContext.containsElement(named: "manifest") {
             return .manifest
@@ -240,6 +265,7 @@ final class OPFPackageParserDelegate: NSObject, XMLParserDelegate {
         return .other
     }
 
+    /// 处理 <meta> 元素的文本内容，提取 rendition:layout、rendition:spread、identifier 等
     private func applyMetaValue(_ value: String) {
         let normalizedValue = value.trimmingCharacters(in: .whitespacesAndNewlines)
         guard !normalizedValue.isEmpty, let property = currentMetaProperty?.lowercased() else {
@@ -264,6 +290,7 @@ final class OPFPackageParserDelegate: NSObject, XMLParserDelegate {
         }
     }
 
+    /// 从属性字典中提取 page-spread 信息（支持 properties 和 page-spread 两种写法）
     private func pageSpread(from attributes: [String: String]) -> RDEPUBPageSpread? {
         if let properties = attributes["properties"]?.lowercased() {
             if properties.contains("page-spread-left") {
@@ -293,11 +320,13 @@ final class OPFPackageParserDelegate: NSObject, XMLParserDelegate {
         return nil
     }
 
+    /// 将 rendition:layout 原始值转换为布局枚举
     private func layout(from rawValue: String) -> RDEPUBLayout {
         rawValue.lowercased().contains("pre-paginated") ? .fixed : .reflowable
     }
 }
 
+/// OPF 文档的区域枚举，用于区分当前解析位置
 enum XMLSection {
     case metadata
     case manifest
@@ -305,11 +334,14 @@ enum XMLSection {
     case other
 }
 
+/// XML 名称解析工具：提取本地名、分词、提取 refines ID
 enum XMLName {
+    /// 从带命名空间前缀的名称中提取本地名（如 "dc:title" -> "title"）
     static func localName(from rawName: String) -> String {
         rawName.split(separator: ":").last.map(String.init) ?? rawName
     }
 
+    /// 将空格分隔的属性值拆分为 token 数组
     static func tokenize(_ rawValue: String?) -> [String] {
         guard let rawValue else { return [] }
         return rawValue
@@ -317,6 +349,7 @@ enum XMLName {
             .map(String.init)
     }
 
+    /// 从 refines 属性值中提取 ID（去掉 "#" 前缀）
     static func refinedID(from rawValue: String) -> String? {
         let trimmed = rawValue.trimmingCharacters(in: .whitespacesAndNewlines)
         guard trimmed.hasPrefix("#") else {
@@ -326,10 +359,14 @@ enum XMLName {
     }
 }
 
+/// XML 解析上下文，维护元素栈和当前文本内容
 final class XMLParserContext {
+    /// 元素名称栈，用于追踪嵌套层级
     private var elementStack: [String] = []
+    /// 当前元素累积的文本内容
     private var currentCharacters = ""
 
+    /// 去除空白后的当前文本
     var trimmedCharacters: String {
         currentCharacters.trimmingCharacters(in: .whitespacesAndNewlines)
     }

Sources/RDReaderView/EPUBCore/RDEPUBParser+ReadingProfile.swift

@@ -1,6 +1,13 @@
+// RDEPUBParser+ReadingProfile.swift
+// EPUB 阅读配置文件判断
+// 根据 metadata 的 layout 属性和 manifest/spine 内容，
+// 将出版物分类为 webFixedLayout（固定版式）、webInteractive（含脚本/多媒体）或 textReflowable（纯文本重排）。
+
 import Foundation
 
 extension RDEPUBParser {
+    /// 判断出版物的阅读配置文件
+    /// 优先判断固定版式，其次检测交互内容（脚本/iframe/视频等），默认为文本重排
     public func readingProfile() -> RDEPUBReadingProfile {
         if metadata.layout == .fixed {
             return .webFixedLayout
@@ -8,6 +15,9 @@ extension RDEPUBParser {
         return hasInteractiveContent() ? .webInteractive : .textReflowable
     }
 
+    /// 检测出版物是否包含交互内容
+    /// 通过 manifest 中的脚本媒体类型和 "scripted" 属性，
+    /// 以及扫描 HTML 中的 script/iframe/video/audio/canvas/svg/form 等标签
     public func hasInteractiveContent() -> Bool {
         let interactiveMediaTypes = [
             "application/javascript",

Sources/RDReaderView/EPUBCore/RDEPUBParser+Resources.swift

@@ -1,11 +1,18 @@
+// RDEPUBParser+Resources.swift
+// EPUB 资源查询与 URL 解析
+// 提供按 ID、href 查询 manifest 项，spine 索引与 href 互转，
+// 文件路径与 ss-reader:// 协议 URL 互转，封面图提取，HTML 内容读取等能力。
+
 import Foundation
 import UIKit
 
 extension RDEPUBParser {
+    /// 按 ID 查询 manifest 项
     public func manifestItem(for id: String) -> RDEPUBManifestItem? {
         manifest[id]
     }
 
+    /// 按 href 查询 manifest 项（忽略 fragment）
     public func manifestItem(forHref href: String) -> RDEPUBManifestItem? {
         let target = href.components(separatedBy: "#").first ?? href
         return manifest.values.first { item in
@@ -13,11 +20,13 @@ extension RDEPUBParser {
         }
     }
 
+    /// 通过 spine 索引获取 href
     public func href(forSpineIndex index: Int) -> String? {
         guard spine.indices.contains(index) else { return nil }
         return spine[index].href
     }
 
+    /// 将相对路径转换为本地文件 URL，并校验是否在解压根目录内（防路径遍历攻击）
     public func fileURL(forRelativePath relativePath: String) -> URL? {
         guard let opfDirectoryURL else { return nil }
         let path = relativePath.components(separatedBy: "#").first ?? relativePath
@@ -32,6 +41,7 @@ extension RDEPUBParser {
         return resolvedURL
     }
 
+    /// 将相对路径转换为 ss-reader://book/ 协议的 URL（用于 WebView 加载资源）
     public func resourceURL(forRelativePath relativePath: String) -> URL? {
         let normalizedPath = relativePath.trimmingCharacters(in: CharacterSet(charactersIn: "/"))
         guard !normalizedPath.isEmpty else { return nil }
@@ -45,6 +55,7 @@ extension RDEPUBParser {
         return components.url
     }
 
+    /// 将 ss-reader://book/ 协议的 URL 还原为本地文件 URL
     public func fileURL(forResourceURL resourceURL: URL) -> URL? {
         guard resourceURL.scheme == RDEPUBResourceURLSchemeHandler.scheme,
               resourceURL.host == RDEPUBResourceURLSchemeHandler.host else {
@@ -54,6 +65,7 @@ extension RDEPUBParser {
         return fileURL(forRelativePath: relativePath)
     }
 
+    /// 提取封面图片（优先查找含 "cover-image" 属性或 ID 含 "cover" 的 manifest 项）
     public func coverImage() -> UIImage? {
         let coverCandidates = manifest.values.filter { item in
             item.properties.contains("cover-image") || item.id.lowercased().contains("cover")
@@ -67,6 +79,7 @@ extension RDEPUBParser {
         return nil
     }
 
+    /// 通过 spine 索引读取 HTML 内容
     public func htmlString(forSpineIndex index: Int) -> String? {
         guard spine.indices.contains(index) else {
             return nil
@@ -74,6 +87,7 @@ extension RDEPUBParser {
         return htmlString(forRelativePath: spine[index].href)
     }
 
+    /// 通过相对路径读取 HTML 内容
     public func htmlString(forRelativePath relativePath: String) -> String? {
         guard let fileURL = fileURL(forRelativePath: relativePath) else {
             return nil
@@ -81,6 +95,7 @@ extension RDEPUBParser {
         return try? String(contentsOf: fileURL)
     }
 
+    /// 将 href 相对于目录 URL 解析为标准化的相对路径
     func normalize(href: String, relativeTo directoryURL: URL) -> String {
         guard let resolvedURL = URL(string: href, relativeTo: directoryURL)?.standardizedFileURL else {
             return href

Sources/RDReaderView/EPUBCore/RDEPUBParser+TOC.swift

@@ -1,6 +1,14 @@
+// RDEPUBParser+TOC.swift
+// EPUB 目录解析
+// 支持两种目录格式：NCX（EPUB 2）和 Navigation Document（EPUB 3），
+// 优先使用 NCX，其次 Nav Document，最终回退到 spine 列表。
+// 内部使用 TOCTreeBuilder 构建树状目录结构。
+
 import Foundation
 
 extension RDEPUBParser {
+    /// 从 OPF 解析结果中解析目录
+    /// 优先尝试 NCX，再尝试 Nav Document，两者都失败则回退到 spine 列表
     func parseTOC(from packageDocument: OPFPackageDocument, opfURL: URL) -> [EPUBTableOfContentsItem] {
         let opfDirectoryURL = opfURL.deletingLastPathComponent()
 
@@ -23,6 +31,7 @@ extension RDEPUBParser {
         return spine.map { EPUBTableOfContentsItem(title: $0.title, href: $0.href) }
     }
 
+    /// 解析 NCX（EPUB 2）目录文件
     func parseNCXDocumentItems(at ncxURL: URL) -> [EPUBTableOfContentsItem] {
         guard FileManager.default.fileExists(atPath: ncxURL.path),
               let parser = XMLParser(contentsOf: ncxURL) else {
@@ -40,6 +49,7 @@ extension RDEPUBParser {
         return delegate.items
     }
 
+    /// 解析 Navigation Document（EPUB 3）目录文件
     func parseNavDocumentItems(at navURL: URL, baseURL: URL) -> [EPUBTableOfContentsItem] {
         guard FileManager.default.fileExists(atPath: navURL.path),
               let parser = XMLParser(contentsOf: navURL) else {
@@ -57,6 +67,7 @@ extension RDEPUBParser {
         return delegate.items
     }
 
+    /// 标准化目录 href（拆分路径和 fragment，对路径部分做相对路径解析）
     func normalizeTOCHref(_ href: String, relativeTo baseURL: URL) -> String? {
         let components = href.split(separator: "#", maxSplits: 1, omittingEmptySubsequences: false)
         let pathPart = components.first.map(String.init) ?? href
@@ -80,11 +91,13 @@ extension RDEPUBParser {
     }
 }
 
+/// 目录树节点，存储标题、href 和子节点，最终转换为 EPUBTableOfContentsItem
 private final class TOCNode {
     var title = ""
     var href: String?
     var children: [TOCNode] = []
 
+    /// 将节点及其子节点递归转换为目录项
     func asItem() -> EPUBTableOfContentsItem? {
         let trimmedTitle = title.trimmingCharacters(in: .whitespacesAndNewlines)
         guard let href, !href.isEmpty else {
@@ -98,10 +111,14 @@ private final class TOCNode {
     }
 }
 
+/// 目录树构建器：通过 beginNode/endNode 操作维护节点栈，构建嵌套目录结构
 private final class TOCTreeBuilder {
+    /// 当前嵌套路径上的节点栈
     private var nodeStack: [TOCNode] = []
+    /// 顶层根节点列表
     private var rootNodes: [TOCNode] = []
 
+    /// 获取构建完成的目录项列表
     var items: [EPUBTableOfContentsItem] {
         rootNodes.compactMap { $0.asItem() }
     }
@@ -134,6 +151,7 @@ private final class TOCTreeBuilder {
     }
 }
 
+/// NCX 文档的 SAX 解析代理，解析 <navPoint>、<content>、<text> 元素
 private final class NCXParserDelegate: NSObject, XMLParserDelegate {
     private let baseURL: URL
     private let hrefNormalizer: (String, URL) -> String?
@@ -198,6 +216,7 @@ private final class NCXParserDelegate: NSObject, XMLParserDelegate {
     }
 }
 
+/// Navigation Document 的 SAX 解析代理，解析含 epub:type="toc" 的 <nav> 元素
 private final class NavDocumentParserDelegate: NSObject, XMLParserDelegate {
     private let baseURL: URL
     private let hrefNormalizer: (String, URL) -> String?
@@ -284,6 +303,7 @@ private final class NavDocumentParserDelegate: NSObject, XMLParserDelegate {
         }
     }
 
+    /// 判断 <nav> 元素是否为 TOC 导航（检查 epub:type、type、role 属性）
     private func isTOCNav(attributes: [String: String]) -> Bool {
         if let epubType = attributes["epub:type"]?.lowercased(), epubType.contains("toc") {
             return true

Sources/RDReaderView/EPUBCore/RDEPUBParser.swift

@@ -1,23 +1,41 @@
+// RDEPUBParser.swift
+// EPUB 解析器入口
+// 解析链路：epubURL → ZIP 解压 → container.xml → OPF → spine/TOC
+// 是 EPUBCore Publication 层的核心，解析完成后通过 makePublication() 生成 RDEPUBPublication。
+// 具体解析逻辑分散在 +Archive、+Package、+TOC、+Resources、+ReadingProfile 扩展中。
+
 import Foundation
 
+/// EPUB 解析器，执行从 epub 文件到出版物数据的完整解析流程
+/// 主链路：epubURL → extractArchiveIfNeeded → container.xml → OPF → metadata/manifest/spine/TOC
 public final class RDEPUBParser {
+    /// 出版物元数据（标题、作者、语言、布局模式等）
     public internal(set) var metadata = RDEPUBMetadata()
+    /// 资源清单字典（key 为 manifest item ID）
     public internal(set) var manifest: [String: RDEPUBManifestItem] = [:]
+    /// 阅读顺序列表（按 spine 排列的资源项）
     public internal(set) var spine: [RDEPUBSpineItem] = []
+    /// 目录树（从 NCX 或 Nav Document 解析得到）
     public internal(set) var tableOfContents: [EPUBTableOfContentsItem] = []
+    /// EPUB 解压后的根目录路径
     public internal(set) var extractionRootURL: URL?
+    /// OPF 文件的完整路径
     public internal(set) var opfURL: URL?
 
+    /// OPF 文件所在目录的 URL（用于解析相对路径）
     public var opfDirectoryURL: URL? {
         opfURL?.deletingLastPathComponent()
     }
 
     public init() {}
 
+    /// 基于当前解析结果创建 RDEPUBPublication（门面对象）
     public func makePublication() -> RDEPUBPublication {
         RDEPUBPublication(parser: self)
     }
 
+    /// 完整解析 EPUB 文件：解压 → container.xml → OPF
+    /// - Parameter epubURL: EPUB 文件的本地路径
     public func parse(epubURL: URL) throws {
         reset()
 
@@ -38,6 +56,8 @@ public final class RDEPUBParser {
         try parseOPF(at: packageURL)
     }
 
+    /// 解析 OPF 文件：metadata/manifest/spine/TOC
+    /// - Parameter opfURL: OPF 文件路径
     public func parseOPF(at opfURL: URL) throws {
         resetPublicationState()
 
@@ -61,10 +81,12 @@ public final class RDEPUBParser {
         self.tableOfContents = parseTOC(from: packageDocument, opfURL: opfURL)
     }
 
+    /// 获取已解析的目录
     public func parseTOC() -> [EPUBTableOfContentsItem] {
         tableOfContents
     }
 
+    /// 解析指定的 Navigation Document 文件
     public func parseNavDocument(_ navURL: URL, baseURL: URL? = nil) -> [EPUBTableOfContentsItem] {
         parseNavDocumentItems(at: navURL, baseURL: baseURL ?? navURL.deletingLastPathComponent())
     }

Sources/RDReaderView/EPUBCore/RDEPUBPreferences.swift

@@ -1,14 +1,29 @@
+// RDEPUBPreferences.swift
+// EPUB 阅读偏好设置
+// 封装字号、行高、内容内边距、主题颜色、固定版式适配模式等展示参数，
+// 并提供从偏好设置生成渲染请求和展示样式的便捷方法。
+
 import UIKit
 
+/// EPUB 阅读偏好设置，包含所有影响渲染效果的展示参数
 public struct RDEPUBPreferences: Equatable {
+    /// 字体大小（pt）
     public var fontSize: CGFloat
+    /// 行高倍数（如 1.5 表示 1.5 倍行高）
     public var lineHeightMultiple: CGFloat
+    /// 重排模式下的内容内边距
     public var reflowableContentInsets: UIEdgeInsets
+    /// 固定版式下的内容内边距
     public var fixedContentInset: UIEdgeInsets
+    /// 主题背景色（CSS 颜色值，如 "#FFFFFF"）
     public var themeBackgroundColor: String?
+    /// 主题文字色（CSS 颜色值）
     public var themeTextColor: String?
+    /// 固定版式背景色
     public var fixedBackgroundColor: String?
+    /// 固定版式适配模式（page/width/height/contain/cover）
     public var fixedLayoutFit: RDEPUBFixedLayoutFit
+    /// 固定版式双页展开模式（never/always/automatic）
     public var fixedLayoutSpreadMode: RDEPUBFixedLayoutSpreadMode
 
     public init(
@@ -33,6 +48,7 @@ public struct RDEPUBPreferences: Equatable {
         self.fixedLayoutSpreadMode = fixedLayoutSpreadMode
     }
 
+    /// 从偏好设置生成重排模式的展示样式
     public func presentationStyle(viewportSize: CGSize) -> RDEPUBPresentationStyle {
         RDEPUBPresentationStyle(
             viewportSize: viewportSize,
@@ -44,6 +60,7 @@ public struct RDEPUBPreferences: Equatable {
         )
     }
 
+    /// 根据页面和偏好设置生成对应的渲染请求（自动区分固定版式和重排）
     public func renderRequest(
         for page: EPUBPage,
         publication: RDEPUBPublication,

Sources/RDReaderView/EPUBCore/RDEPUBPublication.swift

@@ -1,7 +1,16 @@
+// RDEPUBPublication.swift
+// EPUB 出版物门面（Facade）
+// 对 RDEPUBParser 的高层封装，提供 metadata、spine、TOC 等只读访问，
+// 以及固定版式双页展开判断和 spread 生成等业务逻辑。
+// 是 EPUBCore Publication 层对外暴露的主要接口。
+
 import Foundation
 
+/// EPUB 出版物门面对象，封装解析结果并提供高层访问接口
 public final class RDEPUBPublication {
+    /// 底层解析器（持有解析数据）
     public let parser: RDEPUBParser
+    /// 资源解析器（URL 转换和路径规范化）
     public let resourceResolver: RDEPUBResourceResolver
 
     public init(parser: RDEPUBParser) {
@@ -9,38 +18,48 @@ public final class RDEPUBPublication {
         self.resourceResolver = RDEPUBResourceResolver(parser: parser)
     }
 
+    /// 元数据代理
     public var metadata: RDEPUBMetadata {
         parser.metadata
     }
 
+    /// 资源清单代理
     public var manifest: [String: RDEPUBManifestItem] {
         parser.manifest
     }
 
+    /// 阅读顺序代理
     public var spine: [RDEPUBSpineItem] {
         parser.spine
     }
 
+    /// 目录代理
     public var tableOfContents: [EPUBTableOfContentsItem] {
         parser.tableOfContents
     }
 
+    /// 布局模式（fixed/reflowable）
     public var layout: RDEPUBLayout {
         metadata.layout
     }
 
+    /// 阅读配置文件（webFixedLayout/webInteractive/textReflowable）
     public var readingProfile: RDEPUBReadingProfile {
         parser.readingProfile()
     }
 
+    /// 阅读方向（ltr/rtl/auto）
     public var readingProgression: RDEPUBReadingProgression {
         metadata.readingProgression
     }
 
+    /// 书籍唯一标识符
     public var bookIdentifier: String? {
         metadata.identifier
     }
 
+    /// 判断固定版式是否启用双页展开模式
+    /// 综合考虑 metadata.spread、偏好设置和视口方向
     public func fixedLayoutSpreadEnabled(for preferences: RDEPUBPreferences, viewportSize: CGSize) -> Bool {
         guard layout == .fixed else {
             return false
@@ -59,6 +78,7 @@ public final class RDEPUBPublication {
         }
     }
 
+    /// 根据偏好和视口生成固定版式的 spread 数组
     public func makeFixedSpreads(preferences: RDEPUBPreferences, viewportSize: CGSize) -> [EPUBFixedSpread] {
         EPUBFixedSpread.makeSpreads(
             spine: spine,

Sources/RDReaderView/EPUBCore/RDEPUBReadingModels.swift

@@ -1,11 +1,30 @@
+//
+//  RDEPUBReadingModels.swift
+//  RDReaderView
+//
+//  EPUBCore 层阅读会话相关数据模型定义文件。
+//  包含阅读位置（Location）、视口（Viewport）、阅读上下文（ReadingContext）、
+//  文本选择（Selection）、高亮（Highlight）、书签（Bookmark）、
+//  章节信息（ChapterInfo）、页面模型（Page）、固定版式 Spread 模型等。
+//  这些模型由 RDEPUBReadingSession 管理，贯穿整个阅读生命周期。
+//
+
 import Foundation
 
+/// 阅读位置模型，EPUB 是可重排内容，使用 href + progression 而非页号来定位
+/// progression 取值 [0, 1]，表示当前视口在章节中的相对位置
 public struct RDEPUBLocation: Codable, Equatable {
+    /// 书籍唯一标识符，用于隔离不同书的阅读进度
     public var bookIdentifier: String?
+    /// OPF 相对路径，对应 spine 中的资源文件
     public var href: String
+    /// 视口起始位置在章节中的相对进度 [0, 1]
     public var progression: Double
+    /// 视口末尾位置在章节中的相对进度 [0, 1]（可选）
     public var lastProgression: Double?
+    /// 锚点标识符（如 #section1），用于精确跳转
     public var fragment: String?
+    /// 文本范围锚点（用于文本 EPUB 的高亮定位）
     public var rangeAnchor: RDEPUBTextRangeAnchor?
 
     public init(
@@ -24,6 +43,8 @@ public struct RDEPUBLocation: Codable, Equatable {
         self.rangeAnchor = rangeAnchor
     }
 
+    /// 导航用的中间进度值，取 progression 和 lastProgression 的中点
+    /// 用于在字号/横竖屏变化后估算最接近的页号
     public var navigationProgression: Double {
         let end = lastProgression ?? progression
         if end.isNaN || end.isInfinite {
@@ -32,17 +53,24 @@ public struct RDEPUBLocation: Codable, Equatable {
         return Self.clamp((progression + end) / 2.0)
     }
 
+    /// 将进度值限制在 [0, 1] 范围内，防止越界
     private static func clamp(_ value: Double) -> Double {
         guard value.isFinite else { return 0 }
         return min(1, max(0, value))
     }
 }
 
+/// 视口中的单个资源信息，表示当前屏幕可见区域覆盖的某个 spine 资源
 public struct RDEPUBViewportResource: Codable, Equatable {
+    /// 资源路径（相对于 OPF 目录）
     public var href: String
+    /// 对应的 spine 索引
     public var spineIndex: Int
+    /// 该资源在视口中的起始进度 [0, 1]
     public var progression: Double
+    /// 该资源在视口中的结束进度 [0, 1]
     public var lastProgression: Double?
+    /// 锚点标识符
     public var fragment: String?
 
     public init(
@@ -60,10 +88,16 @@ public struct RDEPUBViewportResource: Codable, Equatable {
     }
 }
 
+/// 视口模型，描述当前屏幕可见区域的完整状态
+/// 可能跨越多个 spine 资源（如分栏布局时）
 public struct RDEPUBViewport: Codable, Equatable {
+    /// 当前视口覆盖的资源列表（可能有多个，如分栏或跨页场景）
     public var resources: [RDEPUBViewportResource]
+    /// 当前可见的页码
     public var visiblePageNumber: Int
+    /// 当前章节索引
     public var chapterIndex: Int?
+    /// 是否为固定版式内容
     public var isFixedLayout: Bool
 
     public init(
@@ -79,10 +113,16 @@ public struct RDEPUBViewport: Codable, Equatable {
     }
 }
 
+/// 阅读上下文，聚合了位置、视口和页码等完整阅读状态
+/// 由 RDEPUBReadingSession 维护，是翻页容器层获取当前阅读状态的主要数据源
 public struct RDEPUBReadingContext: Codable, Equatable {
+    /// 当前阅读位置（href + progression）
     public var location: RDEPUBLocation
+    /// 当前视口状态
     public var viewport: RDEPUBViewport
+    /// 当前扁平页码（跨章节累计）
     public var pageNumber: Int
+    /// 当前章节索引
     public var chapterIndex: Int?
 
     public init(
@@ -98,11 +138,17 @@ public struct RDEPUBReadingContext: Codable, Equatable {
     }
 }
 
+/// 文本选择模型，由 JS 桥接 ssReaderSelectionChanged 消息触发创建
 public struct RDEPUBSelection: Codable, Equatable {
+    /// 书籍标识符
     public var bookIdentifier: String?
+    /// 选择发生的位置
     public var location: RDEPUBLocation
+    /// 选中的文本内容
     public var text: String
+    /// DOM Range 信息（JSON 序列化字符串，用于精确重建选区）
     public var rangeInfo: String?
+    /// 选择创建时间
     public var createdAt: Date
 
     public init(
@@ -119,28 +165,44 @@ public struct RDEPUBSelection: Codable, Equatable {
         self.createdAt = createdAt
     }
 
+    /// 判断是否为空选择（无文本或无范围信息）
     public var isEmpty: Bool {
         text.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty || rangeInfo?.isEmpty != false
     }
 }
 
+/// 高亮样式类型
+/// - highlight: 背景色高亮
+/// - underline: 下划线标记
 public enum RDEPUBHighlightStyle: String, Codable {
     case highlight
     case underline
 }
 
+/// 标注菜单操作类型，用于用户长按选中文本后的操作选项
 public enum RDEPUBAnnotationMenuAction: Equatable {
     case copy
     case highlight
     case annotate
 }
 
+/// 文本偏移范围信息，用于文本 EPUB 的高亮精确定位
+/// 使用字符偏移量而非 DOM Range，适用于 DTCoreText 渲染的纯文本内容
 public struct RDEPUBTextOffsetRangeInfo: Codable, Equatable {
+    /// 类型标识符，固定为 "text-offset"
     public var kind: String
+    /// 资源路径
     public var href: String
+    /// 起始字符偏移量
     public var start: Int
+    /// 结束字符偏移量
     public var end: Int
 
+    /// 初始化文本偏移范围
+    /// - Parameters:
+    ///   - href: 资源路径
+    ///   - start: 起始字符偏移量
+    ///   - end: 结束字符偏移量
     public init(href: String, start: Int, end: Int) {
         self.kind = "text-offset"
         self.href = href
@@ -148,16 +210,19 @@ public struct RDEPUBTextOffsetRangeInfo: Codable, Equatable {
         self.end = end
     }
 
+    /// 转换为 NSRange（用于 NSAttributedString 操作）
     public var nsRange: NSRange? {
         guard end > start else { return nil }
         return NSRange(location: start, length: end - start)
     }
 
+    /// 序列化为 JSON 字符串
     public func jsonString() -> String? {
         guard let data = try? JSONEncoder().encode(self) else { return nil }
         return String(data: data, encoding: .utf8)
     }
 
+    /// 从 JSON 字符串反序列化，校验 kind 和范围有效性
     public static func decode(from string: String?) -> RDEPUBTextOffsetRangeInfo? {
         guard let string,
               let data = string.data(using: .utf8),
@@ -170,28 +235,48 @@ public struct RDEPUBTextOffsetRangeInfo: Codable, Equatable {
     }
 }
 
+/// 文本分页截断原因，描述为什么在当前位置分页
 public enum RDEPUBTextPageBreakReason: String, Codable, Equatable {
+    /// 章节自然结束
     case chapterEnd
+    /// 达到帧容量限制
     case frameLimit
+    /// 块级元素边界（如段落、标题）
     case blockBoundary
+    /// 附件（图片等）边界
     case attachmentBoundary
+    /// 语义边界（如列表、引用块）
     case semanticBoundary
 }
 
+/// 文本附件类型
 public enum RDEPUBTextAttachmentKind: String, Codable, Equatable {
+    /// 图片附件
     case image
+    /// 通用附件
     case generic
 }
 
+/// 文本页元数据，记录分页时的上下文信息
+/// 用于调试分页问题和优化分页质量
 public struct RDEPUBTextPageMetadata: Codable, Equatable {
+    /// 分页截断原因
     public var breakReason: RDEPUBTextPageBreakReason
+    /// 本页覆盖的块级元素范围
     public var blockRange: NSRange?
+    /// 本页包含的附件范围列表
     public var attachmentRanges: [NSRange]
+    /// 附件类型列表
     public var attachmentKinds: [RDEPUBTextAttachmentKind]
+    /// 块级元素类型列表
     public var blockKinds: [RDEPUBTextBlockKind]
+    /// 语义提示信息
     public var semanticHints: [RDEPUBTextSemanticHint]
+    /// 附件布局位置信息
     public var attachmentPlacements: [RDEPUBTextAttachmentPlacement]
+    /// 本页末尾的 fragment ID（用于恢复位置）
     public var trailingFragmentID: String?
+    /// 诊断信息列表（调试用）
     public var diagnostics: [String]
 
     public init(
@@ -217,15 +302,26 @@ public struct RDEPUBTextPageMetadata: Codable, Equatable {
     }
 }
 
+/// 高亮模型，表示用户在阅读中标记的文本片段
+/// 支持 Web EPUB（DOM Range 定位）和文本 EPUB（字符偏移定位）两种模式
 public struct RDEPUBHighlight: Codable, Equatable {
+    /// 高亮唯一标识符
     public var id: String
+    /// 书籍标识符
     public var bookIdentifier: String?
+    /// 高亮发生的位置
     public var location: RDEPUBLocation
+    /// 高亮的文本内容
     public var text: String
+    /// 范围信息（Web EPUB 为 DOM Range JSON，文本 EPUB 为字符偏移 JSON）
     public var rangeInfo: String?
+    /// 高亮样式（背景色高亮或下划线）
     public var style: RDEPUBHighlightStyle
+    /// 高亮颜色（CSS 颜色值，如 "#F8E16C"）
     public var color: String
+    /// 用户备注
     public var note: String?
+    /// 创建时间
     public var createdAt: Date
 
     public init(
@@ -250,10 +346,12 @@ public struct RDEPUBHighlight: Codable, Equatable {
         self.createdAt = createdAt
     }
 
+    /// 是否包含用户备注
     public var hasNote: Bool {
         note?.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty == false
     }
 
+    /// 编码键，用于 Codable 序列化/反序列化
     private enum CodingKeys: String, CodingKey {
         case id
         case bookIdentifier
@@ -266,6 +364,7 @@ public struct RDEPUBHighlight: Codable, Equatable {
         case createdAt
     }
 
+    /// 自定义解码器，兼容旧版本数据格式（缺失字段使用默认值）
     public init(from decoder: Decoder) throws {
         let container = try decoder.container(keyedBy: CodingKeys.self)
         id = try container.decode(String.self, forKey: .id)
@@ -284,6 +383,7 @@ public struct RDEPUBHighlight: Codable, Equatable {
         createdAt = try container.decodeIfPresent(Date.self, forKey: .createdAt) ?? Date()
     }
 
+    /// 自定义编码器
     public func encode(to encoder: Encoder) throws {
         var container = encoder.container(keyedBy: CodingKeys.self)
         try container.encode(id, forKey: .id)
@@ -298,12 +398,19 @@ public struct RDEPUBHighlight: Codable, Equatable {
     }
 }
 
+/// 书签模型，记录用户标记的阅读位置
 public struct RDEPUBBookmark: Codable, Equatable {
+    /// 书签唯一标识符
     public var id: String
+    /// 书籍标识符
     public var bookIdentifier: String?
+    /// 书签位置
     public var location: RDEPUBLocation
+    /// 章节标题（用于书签列表展示）
     public var chapterTitle: String?
+    /// 用户备注
     public var note: String?
+    /// 创建时间
     public var createdAt: Date
 
     public init(
@@ -322,14 +429,19 @@ public struct RDEPUBBookmark: Codable, Equatable {
         self.createdAt = createdAt
     }
 
+    /// 是否包含用户备注
     public var hasNote: Bool {
         note?.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty == false
     }
 }
 
+/// 章节信息模型，描述单个章节的元数据
 public struct EPUBChapterInfo: Codable, Equatable {
+    /// 对应的 spine 索引
     public var spineIndex: Int
+    /// 章节标题
     public var title: String
+    /// 该章节的总页数
     public var pageCount: Int
 
     public init(spineIndex: Int, title: String, pageCount: Int) {
@@ -339,12 +451,20 @@ public struct EPUBChapterInfo: Codable, Equatable {
     }
 }
 
+/// 页面模型，描述单页的完整信息
+/// 由 RDEPUBReadingSession 根据分页结果构建，是翻页容器层的数据单元
 public struct EPUBPage: Codable, Equatable {
+    /// 对应的 spine 索引
     public var spineIndex: Int
+    /// 章节索引（从 0 开始的章节序号）
     public var chapterIndex: Int
+    /// 页在章节中的索引（从 0 开始）
     public var pageIndexInChapter: Int
+    /// 该章节的总页数
     public var totalPagesInChapter: Int
+    /// 章节标题
     public var chapterTitle: String
+    /// 固定版式 Spread 数据（仅 fixed layout 书籍有值）
     public var fixedSpread: EPUBFixedSpread?
 
     public init(
@@ -364,10 +484,15 @@ public struct EPUBPage: Codable, Equatable {
     }
 }
 
+/// 固定版式 Spread 中的单个资源
 public struct EPUBFixedSpreadResource: Codable, Equatable {
+    /// 对应的 spine 索引
     public var spineIndex: Int
+    /// 资源路径
     public var href: String
+    /// 资源标题
     public var title: String
+    /// 在 spread 中的位置偏好
     public var pageSpread: RDEPUBPageSpread?
 
     public init(spineIndex: Int, href: String, title: String, pageSpread: RDEPUBPageSpread? = nil) {
@@ -378,23 +503,38 @@ public struct EPUBFixedSpreadResource: Codable, Equatable {
     }
 }
 
+/// 固定版式 Spread（双页展开）模型
+/// 将 1-2 个 spine 资源组合为一个显示单元
 public struct EPUBFixedSpread: Codable, Equatable {
+    /// 该 spread 包含的资源列表（通常 1-2 个）
     public var resources: [EPUBFixedSpreadResource]
 
     public init(resources: [EPUBFixedSpreadResource]) {
         self.resources = resources
     }
 
+    /// 主资源（列表中的第一个），用于标识和定位
     public var primaryResource: EPUBFixedSpreadResource {
         resources.first ?? EPUBFixedSpreadResource(spineIndex: 0, href: "", title: "")
     }
 
+    /// 判断指定 href 的资源是否属于此 spread
+    /// - Parameters:
+    ///   - normalizedHref: 标准化后的 href
+    ///   - normalizer: href 标准化函数
+    /// - Returns: 是否包含该资源
     public func contains(normalizedHref: String, normalizer: (String) -> String?) -> Bool {
         resources.contains { resource in
             normalizer(resource.href) == normalizedHref
         }
     }
 
+    /// 根据 spine 列表和 spread 设置生成 Spread 数组
+    /// 根据 pageSpread 属性（left/right/center）决定资源配对
+    /// - Parameters:
+    ///   - spine: spine 项列表
+    ///   - spreadEnabled: 是否启用 spread 模式
+    /// - Returns: spread 数组
     public static func makeSpreads(spine: [RDEPUBSpineItem], spreadEnabled: Bool) -> [EPUBFixedSpread] {
         let resources = spine.enumerated().map { index, item in
             EPUBFixedSpreadResource(
@@ -433,10 +573,13 @@ public struct EPUBFixedSpread: Codable, Equatable {
         return spreads
     }
 
+    /// 便捷方法：从 parser 构建 spread
     public static func makeSpreads(parser: RDEPUBParser, spreadEnabled: Bool) -> [EPUBFixedSpread] {
         makeSpreads(spine: parser.spine, spreadEnabled: spreadEnabled)
     }
 
+    /// 判断两个资源是否应该配对为一个 spread
+    /// center 类型不参与配对，left+right 或 right+left 配对
     private static func shouldPair(current: EPUBFixedSpreadResource, next: EPUBFixedSpreadResource) -> Bool {
         if current.pageSpread == .center || next.pageSpread == .center {
             return false
@@ -453,7 +596,9 @@ public struct EPUBFixedSpread: Codable, Equatable {
     }
 }
 
+/// String 扩展：空字符串转为 nil，用于 Codable 容错处理
 private extension String {
+    /// 空白字符修剪后如果是空字符串则返回 nil
     var nilIfEmpty: String? {
         let trimmed = trimmingCharacters(in: .whitespacesAndNewlines)
         return trimmed.isEmpty ? nil : trimmed

Sources/RDReaderView/EPUBCore/RDEPUBReadingSession.swift

@@ -1,33 +1,56 @@
+// RDEPUBReadingSession.swift
+// EPUB 阅读会话（状态机）
+// 管理阅读器的运行时状态：导航状态（initializing/loading/idle/jumping/moving/repaginating）、
+// 活跃页面列表、待应用的分页快照、挂起的导航请求、当前视口和阅读上下文。
+// 提供分页快照生成、位置计算、导航队列、阅读上下文更新等核心业务方法。
+
 import Foundation
 
+/// EPUB 阅读会话，管理导航状态、页面列表和阅读进度
+/// 状态机：initializing → loading → idle ↔ jumping/moving/repaginating
 public final class RDEPUBReadingSession {
+    /// 分页快照类型别名（页面数组 + 章节信息数组）
     public typealias PaginationSnapshot = (pages: [EPUBPage], chapters: [EPUBChapterInfo])
 
+    /// 关联的出版物
     public let publication: RDEPUBPublication
 
+    /// 当前导航状态
     public private(set) var navigatorState: RDEPUBNavigatorState = .initializing
+    /// 当前生效的页面列表
     public private(set) var activePages: [EPUBPage] = []
+    /// 当前生效的章节信息列表
     public private(set) var activeChapters: [EPUBChapterInfo] = []
+    /// 暂存的待应用页面列表（分页计算完成后暂存，等状态允许时才生效）
     public private(set) var stagedPages: [EPUBPage]?
+    /// 暂存的待应用章节信息列表
     public private(set) var stagedChapters: [EPUBChapterInfo]?
+    /// 暂存快照对应的恢复位置
     public private(set) var stagedRestoreLocation: RDEPUBLocation?
+    /// 挂起的导航目标位置（用于 fragment 精确定位）
     public private(set) var pendingNavigationLocation: RDEPUBLocation?
+    /// 挂起的导航目标页码
     public private(set) var pendingNavigationPageNum: Int?
+    /// 当前视口信息
     public private(set) var currentViewport: RDEPUBViewport?
+    /// 当前阅读上下文（位置 + 视口 + 页码 + 章节）
     public private(set) var currentReadingContext: RDEPUBReadingContext?
 
     public init(publication: RDEPUBPublication) {
         self.publication = publication
     }
 
+    /// 资源解析器快捷访问
     public var resourceResolver: RDEPUBResourceResolver {
         publication.resourceResolver
     }
 
+    /// 状态机转换
     public func transition(to state: RDEPUBNavigatorState) {
         navigatorState = state
     }
 
+    /// 重置所有运行时状态（回到 initializing）
     public func resetRuntimeState() {
         navigatorState = .initializing
         activePages = []
@@ -38,17 +61,20 @@ public final class RDEPUBReadingSession {
         currentReadingContext = nil
     }
 
+    /// 设置当前生效的分页快照
     public func setActiveSnapshot(_ snapshot: PaginationSnapshot) {
         activePages = snapshot.pages
         activeChapters = snapshot.chapters
     }
 
+    /// 暂存分页快照（待状态允许时才生效）
     public func stageSnapshot(_ snapshot: PaginationSnapshot, restoreLocation: RDEPUBLocation?) {
         stagedPages = snapshot.pages
         stagedChapters = snapshot.chapters
         stagedRestoreLocation = restoreLocation
     }
 
+    /// 获取暂存的分页快照
     public func stagedSnapshot() -> PaginationSnapshot? {
         guard let stagedPages, let stagedChapters else {
             return nil
@@ -56,6 +82,7 @@ public final class RDEPUBReadingSession {
         return (stagedPages, stagedChapters)
     }
 
+    /// 如果状态稳定且有暂存快照，则消费并返回（原子操作）
     public func consumeStagedSnapshotIfAllowed() -> (snapshot: PaginationSnapshot, restoreLocation: RDEPUBLocation?)? {
         guard navigatorState.isStableForSnapshotApplication,
               let stagedPages,
@@ -67,17 +94,20 @@ public final class RDEPUBReadingSession {
         return ((stagedPages, stagedChapters), restoreLocation)
     }
 
+    /// 清除暂存快照
     public func clearStagedSnapshot() {
         stagedPages = nil
         stagedChapters = nil
         stagedRestoreLocation = nil
     }
 
+    /// 清除挂起的导航请求
     public func clearPendingNavigation() {
         pendingNavigationLocation = nil
         pendingNavigationPageNum = nil
     }
 
+    /// 检查指定页码和 spine 索引是否有挂起的导航位置
     public func pendingLocation(forPageNumber pageNumber: Int, spineIndex: Int?) -> RDEPUBLocation? {
         guard pendingNavigationPageNum == pageNumber,
               let pendingNavigationLocation else {
@@ -93,6 +123,7 @@ public final class RDEPUBReadingSession {
         return pendingNavigationLocation
     }
 
+    /// 判断指定页面是否包含给定的 spine 索引（固定版式需检查 spread 内所有资源）
     public func pageContains(spineIndex: Int, in page: EPUBPage) -> Bool {
         if let fixedSpread = page.fixedSpread {
             return fixedSpread.resources.contains(where: { $0.spineIndex == spineIndex })
@@ -100,6 +131,7 @@ public final class RDEPUBReadingSession {
         return page.spineIndex == spineIndex
     }
 
+    /// 根据页面信息生成回退位置（用于无精确位置时的兜底）
     public func fallbackLocation(for page: EPUBPage, bookIdentifier: String?) -> RDEPUBLocation? {
         if let fixedSpread = page.fixedSpread {
             return RDEPUBLocation(
@@ -129,6 +161,7 @@ public final class RDEPUBReadingSession {
         )
     }
 
+    /// 获取当前可见页面对应的位置
     public func currentVisibleLocation(currentPageNumber: Int, bookIdentifier: String?) -> RDEPUBLocation? {
         guard currentPageNumber > 0,
               activePages.indices.contains(currentPageNumber - 1) else {
@@ -137,6 +170,7 @@ public final class RDEPUBReadingSession {
         return fallbackLocation(for: activePages[currentPageNumber - 1], bookIdentifier: bookIdentifier)
     }
 
+    /// 根据位置获取初始 spine 索引
     public func initialSpineIndex(for location: RDEPUBLocation?) -> Int {
         guard let location,
               let normalizedHref = resourceResolver.normalizedHref(location.href),
@@ -146,6 +180,7 @@ public final class RDEPUBReadingSession {
         return spineIndex
     }
 
+    /// 根据位置计算对应的页面索引（支持固定版式和重排模式）
     public func pageIndex(for location: RDEPUBLocation, bookIdentifier: String?) -> Int? {
         guard location.bookIdentifier == nil || location.bookIdentifier == bookIdentifier else {
             return nil
@@ -186,6 +221,7 @@ public final class RDEPUBReadingSession {
         return candidates[localIndex].offset
     }
 
+    /// 排队导航到指定位置：规范化位置、查找页面索引、设置挂起导航、切换到 jumping 状态
     public func queueNavigation(
         to location: RDEPUBLocation,
         relativeToSpineIndex spineIndex: Int? = nil,
@@ -205,6 +241,7 @@ public final class RDEPUBReadingSession {
         return pageIndex + 1
     }
 
+    /// 更新阅读上下文：规范化位置、设置视口和阅读上下文、清除挂起导航、回到 idle 状态
     public func updateReadingContext(
         pageNumber: Int,
         location: RDEPUBLocation,
@@ -253,10 +290,13 @@ public final class RDEPUBReadingSession {
         }
     }
 
+    /// 获取当前阅读位置（优先从阅读上下文获取，回退到可见位置）
     public func currentReadingLocation(bookIdentifier: String?) -> RDEPUBLocation? {
         currentReadingContext?.location ?? currentVisibleLocation(currentPageNumber: currentViewport?.visiblePageNumber ?? 0, bookIdentifier: bookIdentifier)
     }
 
+    /// 根据分页计数和偏好设置生成分页快照
+    /// 固定版式按 spread 分页，重排模式按 spine 索引逐章分页
     public func makePaginationSnapshot(
         pageCounts: [Int],
         preferences: RDEPUBPreferences,

Sources/RDReaderView/EPUBCore/RDEPUBRenderRequest.swift

@@ -1,23 +1,49 @@
+//
+//  RDEPUBRenderRequest.swift
+//  RDReaderView
+//
+//  EPUBCore 层渲染请求模型定义文件。
+//  包含渲染所需的展示样式（PresentationStyle）、可重排/固定版式渲染请求（RenderRequest）、
+//  固定版式适配模式（Fit）和 Spread 模式（SpreadMode）。
+//  由 RDEPUBPreferences 构建，传递给 RDEPUBWebView 执行渲染。
+//
+
 import UIKit
 
+/// 固定版式页面适配模式
+/// - auto: 自动选择最佳适配策略
+/// - page: 适配整页（缩放至屏幕大小）
+/// - width: 适配宽度（按宽度等比缩放）
 public enum RDEPUBFixedLayoutFit: String, Codable {
     case auto
     case page
     case width
 }
 
+/// 固定版式 Spread（双页）显示模式
+/// - automatic: 根据设备方向和屏幕尺寸自动判断
+/// - always: 始终启用双页显示
+/// - never: 始终单页显示
 public enum RDEPUBFixedLayoutSpreadMode: String, Codable {
     case automatic
     case always
     case never
 }
 
+/// 渲染展示样式，WebView 和 Paginator 共用的视觉参数
+/// 由 RDEPUBPreferences 根据用户设置构建
 public struct RDEPUBPresentationStyle: Equatable {
+    /// 视口尺寸（容器的可见区域大小）
     public var viewportSize: CGSize
+    /// 内容内边距（上下左右的安全区域偏移）
     public var contentInsets: UIEdgeInsets
+    /// 字号（pt）
     public var fontSize: CGFloat
+    /// 行距倍数（1.0 为默认行距）
     public var lineHeightMultiple: CGFloat
+    /// 主题背景色（CSS 颜色值，如 "#FFFFFF"）
     public var themeBackgroundColor: String?
+    /// 主题文字色（CSS 颜色值，如 "#000000"）
     public var themeTextColor: String?
 
     public init(
@@ -37,14 +63,23 @@ public struct RDEPUBPresentationStyle: Equatable {
     }
 }
 
+/// 可重排内容渲染请求，包含加载和渲染一个 reflowable spine 项所需的全部参数
 public struct RDEPUBReflowableRenderRequest: Equatable {
+    /// spine 索引
     public var spineIndex: Int
+    /// 资源路径
     public var href: String
+    /// 目标页在章节中的索引
     public var pageIndex: Int
+    /// 该章节的总页数
     public var totalPagesInChapter: Int
+    /// 展示样式
     public var presentation: RDEPUBPresentationStyle
+    /// 目标跳转位置（用于恢复阅读位置或锚点跳转）
     public var targetLocation: RDEPUBLocation?
+    /// 高亮列表
     public var highlights: [RDEPUBHighlight]
+    /// 搜索结果展示信息
     public var searchPresentation: RDEPUBSearchPresentation?
 
     public init(
@@ -68,12 +103,19 @@ public struct RDEPUBReflowableRenderRequest: Equatable {
     }
 }
 
+/// 固定版式渲染请求，包含加载和渲染一个 fixed spread 所需的全部参数
 public struct RDEPUBFixedRenderRequest: Equatable {
+    /// 要渲染的 spread（包含 1-2 个资源）
     public var spread: EPUBFixedSpread
+    /// 视口尺寸
     public var viewportSize: CGSize
+    /// 内容内边距
     public var contentInset: UIEdgeInsets
+    /// 背景色 CSS 值
     public var backgroundColorCSS: String?
+    /// 页面适配模式（auto/page/width）
     public var fit: RDEPUBFixedLayoutFit
+    /// 搜索结果展示信息
     public var searchPresentation: RDEPUBSearchPresentation?
 
     public init(
@@ -93,10 +135,15 @@ public struct RDEPUBFixedRenderRequest: Equatable {
     }
 }
 
+/// 渲染请求枚举，统一可重排和固定版式两种渲染模式
+/// RDEPUBWebView 根据此请求类型选择对应的加载和渲染路径
 public enum RDEPUBRenderRequest: Equatable {
+    /// 可重排内容渲染请求
     case reflowable(RDEPUBReflowableRenderRequest)
+    /// 固定版式渲染请求
     case fixed(RDEPUBFixedRenderRequest)
 
+    /// 是否为固定版式渲染
     public var isFixedLayout: Bool {
         if case .fixed = self {
             return true
@@ -104,6 +151,7 @@ public enum RDEPUBRenderRequest: Equatable {
         return false
     }
 
+    /// 主资源的 spine 索引
     public var primarySpineIndex: Int {
         switch self {
         case .reflowable(let request):
@@ -113,6 +161,7 @@ public enum RDEPUBRenderRequest: Equatable {
         }
     }
 
+    /// 主资源的路径
     public var primaryHref: String {
         switch self {
         case .reflowable(let request):

Sources/RDReaderView/EPUBCore/RDEPUBResourceResolver.swift

@@ -1,28 +1,41 @@
+// RDEPUBResourceResolver.swift
+// EPUB 资源解析器
+// 封装 RDEPUBParser 的资源查询能力，提供 href 规范化、
+// spine 索引查找、位置规范化等高层接口。是 Services 层的核心组件，
+// 被 RDEPUBPublication 和 RDEPUBReadingSession 广泛使用。
+
 import Foundation
 
+/// EPUB 资源解析器，负责 URL 转换、href 规范化和位置解析
 public final class RDEPUBResourceResolver {
+    /// 底层解析器引用
     private let parser: RDEPUBParser
 
     public init(parser: RDEPUBParser) {
         self.parser = parser
     }
 
+    /// OPF 文件所在目录的 URL
     public var opfDirectoryURL: URL? {
         parser.opfDirectoryURL
     }
 
+    /// 将相对路径转换为本地文件 URL
     public func fileURL(forRelativePath relativePath: String) -> URL? {
         parser.fileURL(forRelativePath: relativePath)
     }
 
+    /// 将相对路径转换为 ss-reader://book/ 协议 URL
     public func resourceURL(forRelativePath relativePath: String) -> URL? {
         parser.resourceURL(forRelativePath: relativePath)
     }
 
+    /// 将 ss-reader://book/ 协议 URL 还原为本地文件 URL
     public func fileURL(forResourceURL resourceURL: URL) -> URL? {
         parser.fileURL(forResourceURL: resourceURL)
     }
 
+    /// 规范化 href：基于 OPF 目录和可选的 spine 索引，将相对路径解析为标准化的 OPF 内路径
     public func normalizedHref(_ href: String, relativeToSpineIndex spineIndex: Int? = nil) -> String? {
         guard let opfDirectoryURL else {
             return href.components(separatedBy: "#").first
@@ -57,6 +70,7 @@ public final class RDEPUBResourceResolver {
         return pathPart
     }
 
+    /// 规范化 href：基于另一个 href 作为基准路径
     public func normalizedHref(_ href: String, relativeToHref baseHref: String) -> String? {
         guard let opfDirectoryURL else {
             return href.components(separatedBy: "#").first
@@ -79,6 +93,7 @@ public final class RDEPUBResourceResolver {
         return pathPart
     }
 
+    /// 将相对于另一个 href 的引用转换为本地文件 URL
     public func fileURL(forReference href: String, relativeToHref baseHref: String) -> URL? {
         guard let normalizedHref = normalizedHref(href, relativeToHref: baseHref) else {
             return nil
@@ -86,6 +101,7 @@ public final class RDEPUBResourceResolver {
         return fileURL(forRelativePath: normalizedHref)
     }
 
+    /// 规范化位置对象：解析 href、保留 progression 和 fragment
     public func normalizedLocation(
         _ location: RDEPUBLocation,
         relativeToSpineIndex spineIndex: Int? = nil,
@@ -119,12 +135,14 @@ public final class RDEPUBResourceResolver {
         )
     }
 
+    /// 通过规范化 href 查找对应的 spine 索引
     public func spineIndex(forNormalizedHref normalizedHref: String) -> Int? {
         parser.spine.firstIndex { item in
             self.normalizedHref(item.href) == normalizedHref
         }
     }
 
+    /// 通过位置查找对应的 spine 索引
     public func spineIndex(for location: RDEPUBLocation) -> Int? {
         guard let normalizedHref = normalizedHref(location.href) else {
             return nil
@@ -132,6 +150,7 @@ public final class RDEPUBResourceResolver {
         return spineIndex(forNormalizedHref: normalizedHref)
     }
 
+    /// 通过 spine 索引获取 href
     public func href(forSpineIndex spineIndex: Int) -> String? {
         guard parser.spine.indices.contains(spineIndex) else {
             return nil
@@ -139,6 +158,7 @@ public final class RDEPUBResourceResolver {
         return parser.spine[spineIndex].href
     }
 
+    /// 通过 spine 索引获取标题
     public func title(forSpineIndex spineIndex: Int) -> String? {
         guard parser.spine.indices.contains(spineIndex) else {
             return nil
@@ -146,6 +166,7 @@ public final class RDEPUBResourceResolver {
         return parser.spine[spineIndex].title
     }
 
+    /// 通过 href 查询 manifest 项
     public func manifestItem(forHref href: String) -> RDEPUBManifestItem? {
         let targetHref = normalizedHref(href) ?? href.components(separatedBy: "#").first ?? href
         return parser.manifest.values.first {

Sources/RDReaderView/EPUBCore/RDEPUBResourceURLSchemeHandler.swift

@@ -1,13 +1,25 @@
+// RDEPUBResourceURLSchemeHandler.swift
+// ss-reader:// 自定义 URL 协议处理器
+// 实现 WKURLSchemeHandler 协议，拦截 ss-reader://book/<path> 请求，
+// 将其映射到本地解压的 EPUB 资源文件。支持 MIME 类型推断和可选资源的空响应处理。
+
 import Foundation
 import WebKit
 
+/// 自定义 URL 协议处理器，将 ss-reader://book/ 请求映射到本地 EPUB 资源文件
 public final class RDEPUBResourceURLSchemeHandler: NSObject, WKURLSchemeHandler {
+    /// 自定义协议名
     public static let scheme = "ss-reader"
+    /// 自定义主机名
     public static let host = "book"
 
+    /// 底层解析器引用（弱引用，避免循环持有）
     private weak var parser: RDEPUBParser?
+    /// 文件管理器实例
     private let fileManager = FileManager.default
+    /// 串行队列，用于同步访问活跃任务字典
     private let syncQueue = DispatchQueue(label: "com.ssreaderview.epub.scheme-handler")
+    /// 活跃的 URL Scheme 任务集合（用于任务取消检测）
     private var activeTasks: [ObjectIdentifier: Bool] = [:]
 
     public init(parser: RDEPUBParser) {
@@ -15,6 +27,8 @@ public final class RDEPUBResourceURLSchemeHandler: NSObject, WKURLSchemeHandler
         super.init()
     }
 
+    /// 处理 URL Scheme 请求：解析文件路径、读取数据、返回响应
+    /// 对缺失的可选资源（字体/图片/CSS/JS）返回空响应，其他返回 404 错误
     public func webView(_ webView: WKWebView, start urlSchemeTask: any WKURLSchemeTask) {
         let taskID = ObjectIdentifier(urlSchemeTask as AnyObject)
         syncQueue.sync {
@@ -72,23 +86,27 @@ public final class RDEPUBResourceURLSchemeHandler: NSObject, WKURLSchemeHandler
         clearTask(taskID)
     }
 
+    /// 取消 URL Scheme 任务
     public func webView(_ webView: WKWebView, stop urlSchemeTask: any WKURLSchemeTask) {
         RDEPUBWebViewDebug.logSchemeTask("ResourceScheme", requestURL: urlSchemeTask.request.url, event: "stop")
         clearTask(ObjectIdentifier(urlSchemeTask as AnyObject))
     }
 
+    /// 从活跃任务集合中移除已完成的任务
     private func clearTask(_ id: ObjectIdentifier) {
         syncQueue.sync {
             activeTasks[id] = nil
         }
     }
 
+    /// 检查任务是否仍然活跃（防止取消后继续发送数据）
     private func isTaskActive(_ id: ObjectIdentifier) -> Bool {
         syncQueue.sync {
             activeTasks[id] == true
         }
     }
 
+    /// 根据文件扩展名推断 MIME 类型
     private static func mimeType(for pathExtension: String) -> String {
         switch pathExtension.lowercased() {
         case "html", "htm":
@@ -128,6 +146,7 @@ public final class RDEPUBResourceURLSchemeHandler: NSObject, WKURLSchemeHandler
         }
     }
 
+    /// 根据文件扩展名推断文本编码（文本类文件返回 UTF-8）
     private static func textEncodingName(for pathExtension: String) -> String? {
         switch pathExtension.lowercased() {
         case "html", "htm", "xhtml", "css", "js", "xml", "opf", "ncx", "txt":
@@ -137,6 +156,7 @@ public final class RDEPUBResourceURLSchemeHandler: NSObject, WKURLSchemeHandler
         }
     }
 
+    /// 判断是否为可选资源（字体/图片/CSS/JS 等缺失时不报错，返回空响应）
     private static func isOptionalResource(_ url: URL) -> Bool {
         switch url.pathExtension.lowercased() {
         case "ttf", "otf", "woff", "woff2", "css", "js", "jpg", "jpeg", "png", "gif", "webp", "svg":

Sources/RDReaderView/EPUBCore/RDEPUBSearchEngine.swift

@@ -1,12 +1,22 @@
+// RDEPUBSearchEngine.swift
+// EPUB 全文搜索引擎
+// 遍历 spine 中的线性 HTML/XHTML 资源，提取纯文本后执行大小写不敏感的关键词搜索，
+// 返回匹配项列表（含 href、progression、previewText 等）。
+
 import Foundation
 import UIKit
 
+/// 搜索引擎协议，定义全文搜索接口
 protocol RDEPUBSearchEngine {
     func search(keyword: String) -> [RDEPUBSearchMatch]
 }
 
+/// HTML 全文搜索引擎实现
+/// 通过解析 HTML 为纯文本，逐章执行关键词匹配
 final class RDEPUBHTMLSearchEngine: RDEPUBSearchEngine {
+    /// EPUB 解析器（用于读取 HTML 内容）
     private let parser: RDEPUBParser
+    /// EPUB 出版物（用于遍历 spine 和规范化 href）
     private let publication: RDEPUBPublication
 
     init(parser: RDEPUBParser, publication: RDEPUBPublication) {
@@ -14,6 +24,7 @@ final class RDEPUBHTMLSearchEngine: RDEPUBSearchEngine {
         self.publication = publication
     }
 
+    /// 执行全文搜索：遍历所有线性 spine 项，提取纯文本后匹配关键词
     func search(keyword: String) -> [RDEPUBSearchMatch] {
         let normalizedKeyword = keyword.trimmingCharacters(in: .whitespacesAndNewlines)
         guard !normalizedKeyword.isEmpty else {
@@ -35,6 +46,7 @@ final class RDEPUBHTMLSearchEngine: RDEPUBSearchEngine {
         return searchMatches
     }
 
+    /// 将 HTML 转换为纯文本（优先使用 NSAttributedString，失败时用正则兜底）
     private func plainText(fromHTML html: String, baseURL: URL?) -> String {
         guard let data = html.data(using: .utf8) else {
             return fallbackPlainText(fromHTML: html)
@@ -54,6 +66,7 @@ final class RDEPUBHTMLSearchEngine: RDEPUBSearchEngine {
         return fallbackPlainText(fromHTML: html)
     }
 
+    /// 兜底方案：用正则去除 HTML 标签并解码 HTML 实体
     private func fallbackPlainText(fromHTML html: String) -> String {
         let stripped = html.replacingOccurrences(of: "<[^>]+>", with: " ", options: .regularExpression)
         return stripped
@@ -65,6 +78,7 @@ final class RDEPUBHTMLSearchEngine: RDEPUBSearchEngine {
             .replacingOccurrences(of: "&quot;", with: "\"")
     }
 
+    /// 在纯文本中查找所有关键词匹配项（大小写不敏感）
     private func matches(in text: String, href: String, keyword: String) -> [RDEPUBSearchMatch] {
         let source = text as NSString
         let fullLength = source.length
@@ -106,6 +120,7 @@ final class RDEPUBHTMLSearchEngine: RDEPUBSearchEngine {
         return results
     }
 
+    /// 截取匹配位置前后的文本作为预览（前后各 12 个字符）
     private func previewText(in text: NSString, matchRange: NSRange) -> String {
         let previewRadius = 12
         let start = max(matchRange.location - previewRadius, 0)

Sources/RDReaderView/EPUBCore/RDEPUBSearchModels.swift

@@ -1,12 +1,25 @@
+// RDEPUBSearchModels.swift
+// EPUB 搜索相关数据模型
+// 定义搜索匹配项（RDEPUBSearchMatch）、搜索结果（RDEPUBSearchResult）、
+// 搜索状态（RDEPUBSearchState）和搜索展示（RDEPUBSearchPresentation）等数据结构。
+
 import Foundation
 
+/// 搜索匹配项，包含匹配位置、进度、预览文本和范围信息
 public struct RDEPUBSearchMatch: Codable, Equatable {
+    /// 匹配所在资源的规范化 href
     public var href: String
+    /// 匹配位置在文本中的进度比例（0.0 ~ 1.0）
     public var progression: Double
+    /// 匹配位置前后的预览文本
     public var previewText: String
+    /// 在当前资源内的本地匹配索引
     public var localMatchIndex: Int
+    /// 匹配范围的起始位置（字符偏移量）
     public var rangeLocation: Int?
+    /// 匹配范围的长度
     public var rangeLength: Int
+    /// 文本范围锚点（用于精确定位）
     public var rangeAnchor: RDEPUBTextRangeAnchor?
 
     public init(
@@ -28,10 +41,15 @@ public struct RDEPUBSearchMatch: Codable, Equatable {
     }
 }
 
+/// 搜索结果摘要，包含关键词、总匹配数和当前匹配项
 public struct RDEPUBSearchResult: Codable, Equatable {
+    /// 搜索关键词
     public var keyword: String
+    /// 总匹配数量
     public var totalMatchCount: Int
+    /// 当前匹配项的索引（从 1 开始）
     public var currentMatchIndex: Int?
+    /// 当前高亮的匹配项
     public var currentMatch: RDEPUBSearchMatch?
 
     public init(
@@ -47,9 +65,13 @@ public struct RDEPUBSearchResult: Codable, Equatable {
     }
 }
 
+/// 搜索状态，管理关键词、匹配列表和当前索引
 public struct RDEPUBSearchState: Codable, Equatable {
+    /// 搜索关键词
     public var keyword: String
+    /// 所有匹配项列表
     public var matches: [RDEPUBSearchMatch]
+    /// 当前匹配项索引（从 0 开始）
     public var currentMatchIndex: Int?
 
     public init(keyword: String, matches: [RDEPUBSearchMatch], currentMatchIndex: Int? = nil) {
@@ -58,6 +80,7 @@ public struct RDEPUBSearchState: Codable, Equatable {
         self.currentMatchIndex = currentMatchIndex
     }
 
+    /// 获取当前匹配项
     public var currentMatch: RDEPUBSearchMatch? {
         guard let currentMatchIndex,
               matches.indices.contains(currentMatchIndex) else {
@@ -66,6 +89,7 @@ public struct RDEPUBSearchState: Codable, Equatable {
         return matches[currentMatchIndex]
     }
 
+    /// 转换为搜索结果摘要
     public var result: RDEPUBSearchResult {
         RDEPUBSearchResult(
             keyword: keyword,
@@ -76,9 +100,13 @@ public struct RDEPUBSearchState: Codable, Equatable {
     }
 }
 
+/// 搜索展示的单个资源信息
 public struct RDEPUBSearchPresentationResource: Codable, Equatable {
+    /// 资源的规范化 href
     public var href: String
+    /// 该资源内的匹配数量
     public var matchCount: Int
+    /// 当前活跃的本地匹配索引
     public var activeLocalMatchIndex: Int?
 
     public init(href: String, matchCount: Int, activeLocalMatchIndex: Int? = nil) {
@@ -88,8 +116,11 @@ public struct RDEPUBSearchPresentationResource: Codable, Equatable {
     }
 }
 
+/// 搜索展示信息，传递给 JS 桥接脚本用于渲染搜索高亮
 public struct RDEPUBSearchPresentation: Codable, Equatable {
+    /// 搜索关键词
     public var keyword: String
+    /// 各资源的搜索展示信息列表
     public var resources: [RDEPUBSearchPresentationResource]
 
     public init(keyword: String, resources: [RDEPUBSearchPresentationResource]) {

Sources/RDReaderView/EPUBCore/RDEPUBStyleSheetBuilder.swift

@@ -1,6 +1,13 @@
+// RDEPUBStyleSheetBuilder.swift
+// EPUB CSS 样式构建器
+// 负责生成重排模式下的分页 CSS（多列布局）和测量 CSS，
+// 以及将分页样式注入到 HTML 中。还提供测量脚本（JS）用于计算页数。
+
 import Foundation
 
+/// CSS 样式构建工具集，生成分页、渲染和测量所需的 CSS/JS
 public enum RDEPUBStyleSheetBuilder {
+    /// 将分页 CSS 注入到 HTML 字符串中（插入 </head> 或 <body 之前）
     public static func injectPaginationCSS(
         into html: String,
         presentation: RDEPUBPresentationStyle
@@ -15,6 +22,8 @@ public enum RDEPUBStyleSheetBuilder {
         return styleTag + html
     }
 
+    /// 生成重排模式的渲染 CSS（视口、body、#ss-reader-viewport、#ss-reader-content 等）
+    /// 包含多列布局、字号、行高、主题色、高亮样式等
     public static func renderCSS(for presentation: RDEPUBPresentationStyle) -> String {
         let values = cssValues(for: presentation)
         let backgroundCSS = presentation.themeBackgroundColor.map { "background: \($0) !important;" } ?? ""
@@ -95,6 +104,7 @@ public enum RDEPUBStyleSheetBuilder {
         """
     }
 
+    /// 生成分页测量用的 CSS（与渲染 CSS 类似但不含 transform/will-change 等优化属性）
     public static func measurementCSS(for presentation: RDEPUBPresentationStyle) -> String {
         let values = cssValues(for: presentation)
         let backgroundCSS = presentation.themeBackgroundColor.map { "background: \($0) !important;" } ?? ""
@@ -139,6 +149,7 @@ public enum RDEPUBStyleSheetBuilder {
         """
     }
 
+    /// 生成分页测量脚本（JS）：注入 CSS 后测量 scrollWidth，计算页数
     public static func measurementScript(for presentation: RDEPUBPresentationStyle) -> String {
         let style = measurementCSS(for: presentation)
             .replacingOccurrences(of: "\\", with: "\\\\")
@@ -170,6 +181,7 @@ public enum RDEPUBStyleSheetBuilder {
         """
     }
 
+    /// 从展示样式计算所有 CSS 变量值（视口尺寸、内边距、字号、行高等）
     private static func cssValues(for presentation: RDEPUBPresentationStyle) -> (
         viewportWidth: String,
         viewportHeight: String,

Sources/RDReaderView/EPUBCore/RDEPUBTextAnchor.swift

@@ -1,12 +1,26 @@
+// RDEPUBTextAnchor.swift
+// EPUB 文本锚点和范围锚点
+// 定义精确的文本位置锚点（RDEPUBTextAnchor，含 fileIndex/row/column/chapterOffset/fragmentID），
+// 以及文本范围锚点（RDEPUBTextRangeAnchor，起止锚点对）。
+// 支持 Codable 序列化（兼容 spineIndex/fileIndex 两种 key）。
+
 import Foundation
 
+/// 文本锚点，精确定位到 EPUB 中的某个字符位置
+/// 包含文件索引、行号、列号、章节内偏移和可选的 fragment ID
 public struct RDEPUBTextAnchor: Codable, Equatable {
+    /// 文件索引（等同于 spineIndex）
     public let fileIndex: Int
+    /// 行号
     public let row: Int
+    /// 列号（行内偏移）
     public let column: Int
+    /// 章节内的绝对字符偏移量
     public let chapterOffset: Int
+    /// 最近的 fragment ID（用于 URL 锚点定位）
     public let fragmentID: String?
 
+    /// spine 索引的别名（与 fileIndex 等价）
     public var spineIndex: Int { fileIndex }
 
     public init(
@@ -53,8 +67,11 @@ public struct RDEPUBTextAnchor: Codable, Equatable {
     }
 }
 
+/// 文本范围锚点，由起止锚点组成的区间
 public struct RDEPUBTextRangeAnchor: Codable, Equatable {
+    /// 起始锚点
     public let start: RDEPUBTextAnchor
+    /// 结束锚点
     public let end: RDEPUBTextAnchor
 
     public init(start: RDEPUBTextAnchor, end: RDEPUBTextAnchor) {
@@ -62,6 +79,7 @@ public struct RDEPUBTextRangeAnchor: Codable, Equatable {
         self.end = end
     }
 
+    /// 转换为 NSRange（基于 chapterOffset）
     public var nsRange: NSRange {
         NSRange(location: start.chapterOffset, length: max(end.chapterOffset - start.chapterOffset, 0))
     }

Sources/RDReaderView/EPUBCore/RDEPUBTextIndexTable.swift

@@ -1,249 +0,0 @@
-import Foundation
-
-public struct RDEPUBRowColumnIndex: Codable, Equatable {
-    public let row: Int
-    public let startOffset: Int
-    public let endOffset: Int
-
-    public init(row: Int, startOffset: Int, endOffset: Int) {
-        self.row = row
-        self.startOffset = startOffset
-        self.endOffset = endOffset
-    }
-
-    public func contains(_ offset: Int) -> Bool {
-        offset >= startOffset && offset <= endOffset
-    }
-}
-
-public struct RDEPUBTextIndexTable {
-    public let chapterStartOffsets: [Int]
-    public let chapterLengths: [Int]
-    public let hrefToChapterIndex: [String: Int]
-    public let hrefToFileIndex: [String: Int]
-    public let fragmentOffsetsByHref: [String: [String: Int]]
-    public let fileIndexToHref: [Int: String]
-    public let fileRowColumnMap: [Int: [RDEPUBRowColumnIndex]]
-
-    public init(chapters: [RDEPUBTextChapter]) {
-        var offsets: [Int] = []
-        var lengths: [Int] = []
-        var hrefMap: [String: Int] = [:]
-        var hrefToFileMap: [String: Int] = [:]
-        var fragmentMap: [String: [String: Int]] = [:]
-        var fileIndexMap: [Int: String] = [:]
-        var rowColumnMap: [Int: [RDEPUBRowColumnIndex]] = [:]
-        var running = 0
-
-        for (index, chapter) in chapters.enumerated() {
-            hrefMap[chapter.href] = index
-            hrefToFileMap[chapter.href] = chapter.spineIndex
-            offsets.append(running)
-            lengths.append(chapter.attributedContent.length)
-            running += chapter.attributedContent.length
-            fragmentMap[chapter.href] = chapter.fragmentOffsets
-            fileIndexMap[chapter.spineIndex] = chapter.href
-            rowColumnMap[chapter.spineIndex] = Self.makeRowColumnIndices(for: chapter.attributedContent.string)
-        }
-
-        self.chapterStartOffsets = offsets
-        self.chapterLengths = lengths
-        self.hrefToChapterIndex = hrefMap
-        self.hrefToFileIndex = hrefToFileMap
-        self.fragmentOffsetsByHref = fragmentMap
-        self.fileIndexToHref = fileIndexMap
-        self.fileRowColumnMap = rowColumnMap
-    }
-
-    public func anchor(forAbsoluteIndex index: Int, in chapter: RDEPUBTextChapter) -> RDEPUBTextAnchor {
-        let normalizedIndex = clampedOffset(index, in: chapter)
-        let fragmentID = nearestFragmentID(beforeOrAt: normalizedIndex, in: chapter)
-        let row = row(forAbsoluteIndex: normalizedIndex, inFileIndex: chapter.spineIndex)
-        let column = column(forAbsoluteIndex: normalizedIndex, inFileIndex: chapter.spineIndex)
-        return RDEPUBTextAnchor(
-            fileIndex: chapter.spineIndex,
-            row: row,
-            column: column,
-            chapterOffset: normalizedIndex,
-            fragmentID: fragmentID
-        )
-    }
-
-    public func anchor(for location: RDEPUBLocation) -> RDEPUBTextAnchor? {
-        if let anchor = location.rangeAnchor?.start {
-            return anchor
-        }
-
-        guard let chapterIndex = hrefToChapterIndex[location.href],
-              let fileIndex = hrefToFileIndex[location.href] else { return nil }
-        let fragments = fragmentOffsetsByHref[location.href] ?? [:]
-        let chapterOffset: Int
-
-        if let fragment = location.fragment, let fragmentOffset = fragments[fragment] {
-            chapterOffset = fragmentOffset
-        } else {
-            let estimatedLength = max(chapterLengths.indices.contains(chapterIndex) ? chapterLengths[chapterIndex] : 0, 1)
-            let lastOffset = max(estimatedLength - 1, 0)
-            chapterOffset = min(lastOffset, max(0, Int(round(Double(lastOffset) * location.navigationProgression))))
-        }
-
-        return RDEPUBTextAnchor(
-            fileIndex: fileIndex,
-            row: row(forAbsoluteIndex: chapterOffset, inFileIndex: fileIndex),
-            column: column(forAbsoluteIndex: chapterOffset, inFileIndex: fileIndex),
-            chapterOffset: chapterOffset,
-            fragmentID: location.fragment
-        )
-    }
-
-    public func pageNumber(for anchor: RDEPUBTextAnchor, in book: RDEPUBTextBook) -> Int? {
-        guard let chapter = book.chapters.first(where: { $0.spineIndex == anchor.fileIndex }) else { return nil }
-        let basePageIndex = chapter.pages.first?.absolutePageIndex ?? 0
-        let resolvedOffset = absoluteIndex(for: anchor)
-        return chapter.pages.firstIndex { page in
-            NSLocationInRange(resolvedOffset, page.contentRange)
-        }.map { $0 + basePageIndex }
-    }
-
-    public func href(for fileIndex: Int) -> String? {
-        fileIndexToHref[fileIndex]
-    }
-
-    public func chapterIndex(for href: String) -> Int? {
-        hrefToChapterIndex[href]
-    }
-
-    public func absoluteIndex(for anchor: RDEPUBTextAnchor) -> Int {
-        absoluteIndex(
-            fileIndex: anchor.fileIndex,
-            row: anchor.row,
-            column: anchor.column
-        ) ?? anchor.chapterOffset
-    }
-
-    public func absoluteRange(for rangeAnchor: RDEPUBTextRangeAnchor) -> NSRange {
-        let start = absoluteIndex(for: rangeAnchor.start)
-        let end = max(start, absoluteIndex(for: rangeAnchor.end))
-        return NSRange(location: start, length: max(end - start, 0))
-    }
-
-    public func location(
-        for anchor: RDEPUBTextAnchor,
-        in chapter: RDEPUBTextChapter,
-        bookIdentifier: String?
-    ) -> RDEPUBLocation {
-        let absoluteOffset = absoluteIndex(for: anchor)
-        let totalLength = max(chapter.attributedContent.length - 1, 1)
-        let progression = Double(min(max(absoluteOffset, 0), totalLength)) / Double(totalLength)
-        return RDEPUBLocation(
-            bookIdentifier: bookIdentifier,
-            href: chapter.href,
-            progression: progression,
-            lastProgression: progression,
-            fragment: anchor.fragmentID,
-            rangeAnchor: RDEPUBTextRangeAnchor(start: anchor, end: anchor)
-        )
-    }
-
-    public func location(
-        for rangeAnchor: RDEPUBTextRangeAnchor,
-        in chapter: RDEPUBTextChapter,
-        bookIdentifier: String?
-    ) -> RDEPUBLocation {
-        let start = absoluteIndex(for: rangeAnchor.start)
-        let end = max(start, absoluteIndex(for: rangeAnchor.end))
-        let totalLength = max(chapter.attributedContent.length - 1, 1)
-        let clampedStart = min(max(start, 0), totalLength)
-        let clampedEnd = min(max(end, clampedStart), totalLength)
-        return RDEPUBLocation(
-            bookIdentifier: bookIdentifier,
-            href: chapter.href,
-            progression: Double(clampedStart) / Double(totalLength),
-            lastProgression: Double(clampedEnd) / Double(totalLength),
-            fragment: rangeAnchor.start.fragmentID,
-            rangeAnchor: rangeAnchor
-        )
-    }
-
-    public func row(forAbsoluteIndex index: Int, inFileIndex fileIndex: Int) -> Int {
-        guard let rows = fileRowColumnMap[fileIndex], !rows.isEmpty else { return 0 }
-        if let rowIndex = rows.first(where: { $0.contains(index) })?.row {
-            return rowIndex
-        }
-        return rows.last?.row ?? 0
-    }
-
-    public func column(forAbsoluteIndex index: Int, inFileIndex fileIndex: Int) -> Int {
-        guard let rows = fileRowColumnMap[fileIndex], !rows.isEmpty else { return 0 }
-        if let rowEntry = rows.first(where: { $0.contains(index) }) {
-            return max(index - rowEntry.startOffset, 0)
-        }
-        guard let lastRow = rows.last else { return 0 }
-        return max(index - lastRow.startOffset, 0)
-    }
-
-    public func absoluteIndex(fileIndex: Int, row: Int, column: Int) -> Int? {
-        guard let rows = fileRowColumnMap[fileIndex], !rows.isEmpty else { return nil }
-        let normalizedRow = min(max(row, 0), rows.count - 1)
-        let rowEntry = rows[normalizedRow]
-        let maxColumn = max(rowEntry.endOffset - rowEntry.startOffset, 0)
-        return rowEntry.startOffset + min(max(column, 0), maxColumn)
-    }
-
-    private func clampedOffset(_ index: Int, in chapter: RDEPUBTextChapter) -> Int {
-        let lastOffset = max(chapter.attributedContent.length - 1, 0)
-        return min(max(index, 0), lastOffset)
-    }
-
-    private func nearestFragmentID(beforeOrAt offset: Int, in chapter: RDEPUBTextChapter) -> String? {
-        var bestID: String?
-        var bestOffset = -1
-
-        for (id, fragOffset) in chapter.fragmentOffsets {
-            if fragOffset <= offset && fragOffset > bestOffset {
-                bestOffset = fragOffset
-                bestID = id
-            }
-        }
-
-        return bestID
-    }
-
-    private static func makeRowColumnIndices(for text: String) -> [RDEPUBRowColumnIndex] {
-        let nsText = text as NSString
-        let length = nsText.length
-        guard length > 0 else {
-            return [RDEPUBRowColumnIndex(row: 0, startOffset: 0, endOffset: 0)]
-        }
-
-        var rows: [RDEPUBRowColumnIndex] = []
-        var rowNumber = 0
-        var lineStart = 0
-
-        nsText.enumerateSubstrings(
-            in: NSRange(location: 0, length: length),
-            options: [.byLines, .substringNotRequired]
-        ) { _, substringRange, enclosingRange, _ in
-            let startOffset = enclosingRange.location
-            let lineLength = max(substringRange.length, 0)
-            let endOffset = max(startOffset + max(lineLength - 1, 0), startOffset)
-            rows.append(
-                RDEPUBRowColumnIndex(
-                    row: rowNumber,
-                    startOffset: startOffset,
-                    endOffset: min(endOffset, max(length - 1, 0))
-                )
-            )
-            rowNumber += 1
-            lineStart = enclosingRange.location + enclosingRange.length
-        }
-
-        if rows.isEmpty {
-            rows.append(RDEPUBRowColumnIndex(row: 0, startOffset: 0, endOffset: max(length - 1, 0)))
-        } else if lineStart == length, text.hasSuffix("\n") {
-            rows.append(RDEPUBRowColumnIndex(row: rowNumber, startOffset: length, endOffset: length))
-        }
-
-        return rows
-    }
-}

Sources/RDReaderView/EPUBCore/RDEPUBWebView+Configuration.swift

@@ -1,7 +1,14 @@
+// RDEPUBWebView+Configuration.swift
+// RDEPUBWebView 的 WKWebView 配置扩展
+// 负责按需创建和配置 WKWebView 实例：注册 JS 桥接消息处理器、
+// 注入用户脚本、设置自定义 URL Scheme 处理器、配置滚动和外观属性。
+// 同时处理选择菜单（拷贝/高亮/批注）和 WebView 销毁清理。
+
 import UIKit
 import WebKit
 
 extension RDEPUBWebView {
+    /// 按需配置 WKWebView（仅在 Publication 变更或 WebView 不存在时重建）
     func configureWebViewIfNeeded(publication: RDEPUBPublication) {
         let parser = publication.parser
         let publicationKey = parser.opfURL?.path ?? parser.extractionRootURL?.path ?? UUID().uuidString
@@ -66,15 +73,18 @@ extension RDEPUBWebView {
         RDEPUBWebViewDebug.log(debugScope, message: "configured webView=\(RDEPUBWebViewDebug.webViewID(webView)) publicationKey=\(publicationKey)")
     }
 
+    /// 处理选择菜单动作（拷贝/高亮/批注），通知委托并清除选择
     func handleSelectionMenuAction(_ action: RDEPUBAnnotationMenuAction) {
         delegate?.epubWebView(self, didRequestSelectionAction: action)
         clearWebSelection()
     }
 
+    /// 清除 WebView 中的文本选择
     func clearWebSelection() {
         webView?.evaluateJavaScript("window.getSelection && window.getSelection().removeAllRanges();")
     }
 
+    /// 销毁 WebView，移除所有消息处理器和引用
     func teardownWebView() {
         cancelFixedLayoutReadyFallback()
         if let webView {
@@ -96,6 +106,7 @@ extension RDEPUBWebView {
 }
 
 extension UIColor {
+    /// 将 UIColor 转换为 CSS 十六进制颜色字符串（如 "#FF0000"）
     var ss_hexString: String {
         var red: CGFloat = 0
         var green: CGFloat = 0

Sources/RDReaderView/EPUBCore/RDEPUBWebView+FixedLayout.swift

@@ -1,7 +1,13 @@
+// RDEPUBWebView+FixedLayout.swift
+// RDEPUBWebView 的固定版式渲染扩展
+// 处理固定版式（Fixed Layout）的加载流程：生成 HTML 模板、
+// 计算加载签名（去重）、设置固定版式就绪回退定时器等。
+
 import UIKit
 import WebKit
 
 extension RDEPUBWebView {
+    /// 便捷方法：加载固定版式的 spread 页面
     public func loadFixedSpread(
         parser: RDEPUBParser,
         spread: EPUBFixedSpread,
@@ -22,6 +28,7 @@ extension RDEPUBWebView {
         load(publication: parser.makePublication(), request: request)
     }
 
+    /// 处理固定版式加载：设置状态、生成 HTML、加载到 WebView
     func handleFixedLayoutLoad(
         publication: RDEPUBPublication,
         request: RDEPUBFixedRenderRequest,
@@ -52,6 +59,7 @@ extension RDEPUBWebView {
         )
     }
 
+    /// 生成固定版式加载签名（用于去重相同请求）
     func fixedLayoutLoadSignature(publicationKey: String, request: RDEPUBFixedRenderRequest) -> String {
         [
             publicationKey,
@@ -68,6 +76,7 @@ extension RDEPUBWebView {
         ].joined(separator: "#")
     }
 
+    /// 调度固定版式就绪回退定时器（1 秒后如果未收到 ready 消息则手动触发渲染完成）
     func scheduleFixedLayoutReadyFallback() {
         let workItem = DispatchWorkItem { [weak self] in
             RDEPUBWebViewDebug.log(self?.debugScope ?? "ReaderWebView", message: "fixed ready fallback fired")
@@ -79,6 +88,7 @@ extension RDEPUBWebView {
         DispatchQueue.main.asyncAfter(deadline: .now() + 1.0, execute: workItem)
     }
 
+    /// 取消固定版式就绪回退定时器
     func cancelFixedLayoutReadyFallback() {
         fixedLayoutReadyWorkItem?.cancel()
         fixedLayoutReadyWorkItem = nil

Sources/RDReaderView/EPUBCore/RDEPUBWebView+JavaScriptBridge.swift

@@ -1,7 +1,14 @@
+// RDEPUBWebView+JavaScriptBridge.swift
+// RDEPUBWebView 的 JS 桥接和导航委托扩展
+// 实现 WKNavigationDelegate 处理页面加载生命周期，
+// 实现 WKScriptMessageHandler 接收 JS 消息（进度/选择/链接/错误/固定版式就绪），
+// 并将内部链接和外部链接路由到委托方法。
+
 import Foundation
 import WebKit
 
 extension RDEPUBWebView {
+    /// 从 URL 解析内部位置（ss-reader:// 协议的链接）
     func internalLocation(from url: URL) -> RDEPUBLocation? {
         let href = url.path.removingPercentEncoding?.trimmingCharacters(in: CharacterSet(charactersIn: "/")) ?? ""
         let fragment = url.fragment
@@ -9,6 +16,7 @@ extension RDEPUBWebView {
         return RDEPUBLocation(href: href, progression: 0, fragment: fragment)
     }
 
+    /// 从 JS 消息体中构建当前位置对象
     func currentLocation(from body: [String: Any]) -> RDEPUBLocation {
         let progression = (body["progression"] as? NSNumber)?.doubleValue ?? 0
         let lastProgression = (body["lastProgression"] as? NSNumber)?.doubleValue
@@ -43,6 +51,7 @@ extension RDEPUBWebView: WKNavigationDelegate {
         RDEPUBWebViewDebug.logNavigationEvent(debugScope, webView: webView, event: "didFailProvisional", url: webView.url, error: error)
     }
 
+    /// 导航策略决策：区分内部链接（ss-reader://）、外部链接（http/https/mailto/tel）和其他导航
     public func webView(_ webView: WKWebView, decidePolicyFor navigationAction: WKNavigationAction, decisionHandler: @escaping (WKNavigationActionPolicy) -> Void) {
         RDEPUBWebViewDebug.logNavigationEvent(debugScope, webView: webView, event: "decidePolicy", url: navigationAction.request.url)
         guard navigationAction.navigationType == .linkActivated,
@@ -69,6 +78,7 @@ extension RDEPUBWebView: WKNavigationDelegate {
 }
 
 extension RDEPUBWebView: WKScriptMessageHandler {
+    /// 接收 JS 桥接消息，根据消息类型路由到对应的委托方法
     public func userContentController(_ userContentController: WKUserContentController, didReceive message: WKScriptMessage) {
         RDEPUBWebViewDebug.logMessage(debugScope, webView: message.webView, name: message.name, body: message.body)
         switch message.name {

Sources/RDReaderView/EPUBCore/RDEPUBWebView+Reflowable.swift

@@ -1,7 +1,14 @@
+// RDEPUBWebView+Reflowable.swift
+// RDEPUBWebView 的重排模式渲染扩展
+// 处理重排（Reflowable）模式的加载流程：构建渲染请求、
+// 生成加载签名（去重）、通过 JS 桥接应用分页样式和高亮、
+// 处理重复请求跳过和已有文档复用等优化逻辑。
+
 import UIKit
 import WebKit
 
 extension RDEPUBWebView {
+    /// 便捷方法：加载重排模式的指定页面
     public func loadPage(
         parser: RDEPUBParser,
         spineIndex: Int,
@@ -39,6 +46,7 @@ extension RDEPUBWebView {
         load(publication: parser.makePublication(), request: request)
     }
 
+    /// 处理重排模式加载：设置状态、去重检查、加载资源或直接应用样式
     func handleReflowableLoad(
         publication: RDEPUBPublication,
         request: RDEPUBReflowableRenderRequest,
@@ -83,6 +91,7 @@ extension RDEPUBWebView {
         webView.load(URLRequest(url: requestURL))
     }
 
+    /// 生成重排模式加载签名（包含所有渲染参数的哈希，用于去重）
     func reflowableLoadSignature(publicationKey: String, request: RDEPUBReflowableRenderRequest) -> String {
         let targetSignature = [
             request.targetLocation?.href ?? "",
@@ -116,6 +125,7 @@ extension RDEPUBWebView {
         ].joined(separator: "#")
     }
 
+    /// 应用分页展示样式：通过 JS 桥接注入 CSS、设置分页参数和高亮，然后触发渲染完成
     func applyPresentation() {
         guard let webView, let currentRenderRequest else { return }
         guard case .reflowable(let request) = currentRenderRequest else {

Sources/RDReaderView/EPUBCore/RDEPUBWebView+Search.swift

@@ -1,6 +1,11 @@
+// RDEPUBWebView+Search.swift
+// RDEPUBWebView 的搜索高亮扩展
+// 从当前渲染请求中提取搜索展示信息，生成搜索高亮脚本并注入到 WebView 中执行。
+
 import WebKit
 
 extension RDEPUBWebView {
+    /// 如果当前渲染请求包含搜索信息，注入搜索高亮脚本到 WebView
     func applySearchDecorationsIfNeeded(completion: (() -> Void)? = nil) {
         guard let webView else {
             completion?()

Sources/RDReaderView/EPUBCore/RDEPUBWebView.swift

@@ -1,21 +1,39 @@
+// RDEPUBWebView.swift
+// EPUB WebView 主类
+// 封装 WKWebView 的 EPUB 渲染能力，是 Resource View 层的核心组件。
+// 统一管理固定版式和重排模式的加载流程，持有当前渲染状态（spineIndex、pageIndex、
+// 主题色、高亮等），并通过委托模式通知上层页面渲染和交互事件。
+// 具体逻辑分散在 +Configuration、+FixedLayout、+Reflowable、+JavaScriptBridge、+Search 扩展中。
+
 import UIKit
 import WebKit
 
+/// RDEPUBWebView 委托协议，定义 WebView 向上层通知的事件
 public protocol RDEPUBWebViewDelegate: AnyObject {
+    /// 阅读位置更新事件
     func epubWebView(_ webView: RDEPUBWebView, didUpdateLocation location: RDEPUBLocation, spineIndex: Int)
+    /// 文本选择变化事件
     func epubWebView(_ webView: RDEPUBWebView, didChangeSelection selection: RDEPUBSelection?, spineIndex: Int)
+    /// 选择菜单动作请求事件
     func epubWebView(_ webView: RDEPUBWebView, didRequestSelectionAction action: RDEPUBAnnotationMenuAction)
+    /// 内部链接点击事件
     func epubWebView(_ webView: RDEPUBWebView, didActivateInternalLink location: RDEPUBLocation, fromSpineIndex: Int)
+    /// 外部链接点击事件
     func epubWebView(_ webView: RDEPUBWebView, didActivateExternalLink url: URL)
+    /// JavaScript 错误事件
     func epubWebView(_ webView: RDEPUBWebView, didLogJavaScriptError message: String)
+    /// 页面渲染完成事件
     func epubWebViewDidFinishRendering(_ webView: RDEPUBWebView)
 }
 
+/// 委托协议的默认实现（选择菜单动作为可选）
 public extension RDEPUBWebViewDelegate {
     func epubWebView(_ webView: RDEPUBWebView, didRequestSelectionAction action: RDEPUBAnnotationMenuAction) {}
 }
 
+/// 自定义 WKWebView 子类，支持拷贝/高亮/批注选择菜单
 final class RDEPUBAnnotationWebView: WKWebView {
+    /// 选择菜单动作回调
     var onSelectionAction: ((RDEPUBAnnotationMenuAction) -> Void)?
 
     override var canBecomeFirstResponder: Bool {
@@ -46,33 +64,61 @@ final class RDEPUBAnnotationWebView: WKWebView {
     }
 }
 
+/// EPUB WebView 主类，封装 WKWebView 的 EPUB 渲染能力
+/// Resource View 层核心组件，统一管理固定版式和重排模式的渲染
 public final class RDEPUBWebView: UIView {
+    /// 委托对象，接收渲染和交互事件
     public weak var delegate: RDEPUBWebViewDelegate?
+    /// 渲染完成回调（与 delegate 并行使用）
     public var onRendered: (() -> Void)?
 
+        /// 当前关联的出版物
         var publication: RDEPUBPublication?
+        /// 当前渲染请求
         var currentRenderRequest: RDEPUBRenderRequest?
+        /// 内部 WKWebView 实例
         var webView: WKWebView?
+        /// URL Scheme 处理器
         var schemeHandler: RDEPUBResourceURLSchemeHandler?
+        /// 已配置的出版物标识（用于判断是否需要重建 WebView）
         var configuredPublicationKey: String?
+        /// 当前加载签名（用于去重相同请求）
         var currentLoadSignature: String?
+        /// 当前 spine 索引
         var currentSpineIndex = 0
+        /// 当前资源 href
         var currentHref = ""
+        /// 当前页码（从 0 开始）
         var currentPageIndex = 0
+        /// 当前章节总页数
         var currentTotalPagesInChapter = 1
+        /// 当前视口尺寸
         var viewportSize: CGSize = .zero
+        /// 当前内容内边距
         var currentPadding: UIEdgeInsets = .zero
+        /// 当前字号
         var currentFontSize: CGFloat = 16
+        /// 当前行高倍数
         var currentLineHeightMultiple: CGFloat = 1.5
+        /// 当前主题背景色
         var currentThemeBackgroundColor: String?
+        /// 当前主题文字色
         var currentThemeTextColor: String?
+        /// 目标跳转位置
         var targetLocation: RDEPUBLocation?
+        /// 待应用的高亮列表
         var pendingHighlights: [RDEPUBHighlight] = []
+        /// 当前固定版式 spread（固定版式时非空）
         var fixedSpread: EPUBFixedSpread?
+        /// 是否为固定版式模式
         var isFixedLayout = false
+        /// 是否有待处理的进度汇报请求
         var pendingProgressionRequest = false
+        /// 固定版式就绪回退定时器
         var fixedLayoutReadyWorkItem: DispatchWorkItem?
+        /// 当前请求是否已完成渲染
         var didRenderCurrentRequest = false
+        /// 调试日志作用域
         let debugScope = "ReaderWebView"
 
     public override init(frame: CGRect) {
@@ -93,6 +139,7 @@ public final class RDEPUBWebView: UIView {
         webView?.frame = bounds
     }
 
+    /// 重置所有状态并销毁 WebView
     public func reset() {
         delegate = nil
         onRendered = nil
@@ -117,6 +164,7 @@ public final class RDEPUBWebView: UIView {
         teardownWebView()
     }
 
+    /// 加载渲染请求：配置 WebView、生成签名、分发到固定版式或重排处理
     public func load(publication: RDEPUBPublication, request: RDEPUBRenderRequest) {
         configureWebViewIfNeeded(publication: publication)
         guard let webView else { return }
@@ -143,6 +191,7 @@ public final class RDEPUBWebView: UIView {
         }
     }
 
+    /// 生成页面加载签名
     func pageLoadSignature(
         publicationKey: String,
         request: RDEPUBRenderRequest
@@ -155,6 +204,7 @@ public final class RDEPUBWebView: UIView {
         }
     }
 
+    /// 标记渲染完成：通知委托和回调，延迟 100ms 确保布局稳定
     func rendered() {
         guard !didRenderCurrentRequest else { return }
         didRenderCurrentRequest = true

Sources/RDReaderView/EPUBCore/RDEPUBWebViewDebug.swift

@@ -1,7 +1,15 @@
+// RDEPUBWebViewDebug.swift
+// WebView 调试日志工具
+// 提供统一的调试日志输出接口，支持导航事件、JS 执行、
+// 消息接收、URL Scheme 任务等场景的日志记录。
+// DEBUG 模式默认开启，Release 模式默认关闭，可通过 UserDefaults 覆盖。
+
 import Foundation
 import WebKit
 
+/// WebView 调试日志工具集
 enum RDEPUBWebViewDebug {
+    /// 调试日志是否启用（DEBUG 默认开启，可通过 UserDefaults "RDEPUBWebViewDebugEnabled" 覆盖）
     static var isEnabled: Bool = {
         if let configured = UserDefaults.standard.object(forKey: "RDEPUBWebViewDebugEnabled") as? Bool {
             return configured
@@ -13,16 +21,19 @@ enum RDEPUBWebViewDebug {
 #endif
     }()
 
+    /// 获取 WebView 的十六进制标识符（用于日志区分多个 WebView 实例）
     static func webViewID(_ webView: WKWebView?) -> String {
         guard let webView else { return "nil-webview" }
         return String(ObjectIdentifier(webView).hashValue, radix: 16)
     }
 
+    /// 输出通用日志
     static func log(_ scope: String, message: String) {
         guard isEnabled else { return }
         print("[RDReaderWK][\(scope)] \(message)")
     }
 
+    /// 输出导航事件日志（含 WebView ID、事件类型、URL、错误信息）
     static func logNavigationEvent(_ scope: String, webView: WKWebView?, event: String, url: URL? = nil, error: Error? = nil) {
         guard isEnabled else { return }
         let webViewToken = webViewID(webView)
@@ -34,16 +45,19 @@ enum RDEPUBWebViewDebug {
         }
     }
 
+    /// 输出 JavaScript 执行日志
     static func logJavaScript(_ scope: String, webView: WKWebView?, action: String, details: String) {
         guard isEnabled else { return }
         log(scope, message: "webView=\(webViewID(webView)) js=\(action) \(details)")
     }
 
+    /// 输出 JS 消息接收日志（含消息名称和消息体）
     static func logMessage(_ scope: String, webView: WKWebView?, name: String, body: Any) {
         guard isEnabled else { return }
         log(scope, message: "webView=\(webViewID(webView)) message=\(name) body=\(String(describing: body))")
     }
 
+    /// 输出 URL Scheme 任务日志（含请求 URL、文件 URL、事件类型、错误信息）
     static func logSchemeTask(_ scope: String, requestURL: URL?, fileURL: URL? = nil, event: String, error: Error? = nil) {
         guard isEnabled else { return }
         let requestText = summarizedURL(requestURL)
@@ -55,6 +69,7 @@ enum RDEPUBWebViewDebug {
         }
     }
 
+    /// 截取 URL 的摘要信息（ss-reader:// 协议显示完整 URL，其他显示最后路径组件）
     static func summarizedURL(_ url: URL?) -> String {
         guard let url else { return "nil" }
         if let scheme = url.scheme, scheme == RDEPUBResourceURLSchemeHandler.scheme {

Sources/RDReaderView/EPUBCore/Resources/epub-bridge.js

@@ -0,0 +1,297 @@
+(function() {
+  if (window.RDReaderBridge) { return; }
+  window.addEventListener('error', function(event) {
+    try {
+      var message = event && (event.message || (event.error && event.error.message)) || 'Unknown JavaScript error';
+      window.webkit.messageHandlers.{{JAVASCRIPT_ERROR_MESSAGE}}.postMessage(message);
+    } catch (error) {
+    }
+  });
+  function nodePath(node) {
+    var path = [];
+    var current = node;
+    while (current && current !== document) {
+      var parent = current.parentNode;
+      if (!parent) { break; }
+      var index = Array.prototype.indexOf.call(parent.childNodes, current);
+      path.unshift(index);
+      current = parent;
+    }
+    return path;
+  }
+  function nodeFromPath(path) {
+    var current = document;
+    for (var i = 0; i < path.length; i += 1) {
+      if (!current || !current.childNodes || current.childNodes.length <= path[i]) { return null; }
+      current = current.childNodes[path[i]];
+    }
+    return current;
+  }
+  function serializeRange(range) {
+    return JSON.stringify({
+      kind: 'dom-range',
+      startPath: nodePath(range.startContainer),
+      startOffset: range.startOffset,
+      endPath: nodePath(range.endContainer),
+      endOffset: range.endOffset
+    });
+  }
+  function rangeFromInfo(rangeInfo) {
+    try {
+      var payload = typeof rangeInfo === 'string' ? JSON.parse(rangeInfo) : rangeInfo;
+      var startNode = nodeFromPath(payload.startPath || []);
+      var endNode = nodeFromPath(payload.endPath || []);
+      if (!startNode || !endNode) { return null; }
+      var range = document.createRange();
+      range.setStart(startNode, payload.startOffset || 0);
+      range.setEnd(endNode, payload.endOffset || 0);
+      return range;
+    } catch (error) {
+      return null;
+    }
+  }
+  var visiblePageIndex = 0;
+  var configuredPageCount = 1;
+  var configuredPageStride = 1;
+  var relayoutTimer = null;
+  var fixedLayoutDocument = false;
+  function isFixedLayoutDocument() {
+    if (fixedLayoutDocument) { return true; }
+    fixedLayoutDocument = !!document.getElementById('ss-fixed-root') || !!document.querySelector('.ss-fixed-page');
+    return fixedLayoutDocument;
+  }
+  function ensurePaginationStructure() {
+    if (isFixedLayoutDocument()) {
+      return null;
+    }
+    var viewport = document.getElementById('ss-reader-viewport');
+    var content = document.getElementById('ss-reader-content');
+    if (viewport && content) {
+      return content;
+    }
+
+    viewport = document.createElement('div');
+    viewport.id = 'ss-reader-viewport';
+    content = document.createElement('div');
+    content.id = 'ss-reader-content';
+
+    while (document.body.firstChild) {
+      content.appendChild(document.body.firstChild);
+    }
+
+    viewport.appendChild(content);
+    document.body.appendChild(viewport);
+    return content;
+  }
+  function paginationContent() {
+    if (isFixedLayoutDocument()) {
+      return null;
+    }
+    return ensurePaginationStructure();
+  }
+  function effectivePageStride() {
+    return Math.max(1, configuredPageStride || 1);
+  }
+  function measuredPageCount() {
+    if (isFixedLayoutDocument()) {
+      return 1;
+    }
+    var content = paginationContent();
+    var scrollingElement = document.scrollingElement || document.documentElement || document.body;
+    var scrollWidth = Math.max(
+      content ? content.scrollWidth : 0,
+      content ? content.offsetWidth : 0,
+      scrollingElement ? scrollingElement.scrollWidth : 0,
+      document.documentElement ? document.documentElement.scrollWidth : 0,
+      document.body ? document.body.scrollWidth : 0,
+      effectivePageStride()
+    );
+    return Math.max(1, Math.ceil(scrollWidth / effectivePageStride()));
+  }
+  function totalPageCount() {
+    return Math.max(configuredPageCount, measuredPageCount());
+  }
+  function currentPageOffset() {
+    return Math.round(visiblePageIndex * effectivePageStride());
+  }
+  function reportProgression(fragment) {
+    var pageCount = totalPageCount();
+    var progression = pageCount <= 1 ? 0 : visiblePageIndex / Math.max(pageCount - 1, 1);
+    var lastProgression = progression;
+    window.webkit.messageHandlers.{{PROGRESSION_CHANGED_MESSAGE}}.postMessage({
+      progression: progression,
+      lastProgression: lastProgression,
+      fragment: fragment || null
+    });
+  }
+  function setVisiblePageIndex(pageIndex) {
+    if (isFixedLayoutDocument()) {
+      visiblePageIndex = 0;
+      return;
+    }
+    var pageCount = totalPageCount();
+    var maxPageIndex = Math.max(0, pageCount - 1);
+    var safePageIndex = Math.max(0, Math.min(maxPageIndex, Math.round(pageIndex || 0)));
+    visiblePageIndex = safePageIndex;
+    var content = paginationContent();
+    if (content) {
+      content.style.transform = 'translate3d(' + (-currentPageOffset()) + 'px, 0, 0)';
+    }
+  }
+  function scheduleRelayout() {
+    if (isFixedLayoutDocument()) { return; }
+    clearTimeout(relayoutTimer);
+    relayoutTimer = setTimeout(function() {
+      setVisiblePageIndex(visiblePageIndex);
+      reportProgression(null);
+    }, 60);
+  }
+  function pageIndexForElement(target) {
+    if (isFixedLayoutDocument()) { return 0; }
+    if (!target) { return 0; }
+    var rect = target.getBoundingClientRect();
+    var absoluteLeft = Math.max(0, rect.left + currentPageOffset());
+    return Math.max(0, Math.floor(absoluteLeft / effectivePageStride()));
+  }
+  function unwrapHighlights() {
+    document.querySelectorAll('mark.ss-reader-highlight').forEach(function(mark) {
+      var parent = mark.parentNode;
+      if (!parent) { return; }
+      while (mark.firstChild) {
+        parent.insertBefore(mark.firstChild, mark);
+      }
+      parent.removeChild(mark);
+    });
+  }
+  function setHighlights(items) {
+    unwrapHighlights();
+    if (!Array.isArray(items)) { return; }
+    items.forEach(function(item) {
+      if (!item || !item.rangeInfo) { return; }
+      var range = rangeFromInfo(item.rangeInfo);
+      if (!range || range.collapsed) { return; }
+      try {
+        var mark = document.createElement('mark');
+        var style = item.style || 'highlight';
+        mark.className = 'ss-reader-highlight ss-reader-highlight-' + style;
+        mark.style.color = 'inherit';
+        if (style === 'underline') {
+          mark.style.background = 'transparent';
+          mark.style.textDecorationLine = 'underline';
+          mark.style.textDecorationStyle = 'solid';
+          mark.style.textDecorationThickness = '2px';
+          mark.style.textDecorationColor = item.color || '#F8E16C';
+        } else {
+          mark.style.background = item.color || '#F8E16C';
+        }
+        mark.dataset.highlightId = item.id || '';
+        var fragment = range.extractContents();
+        mark.appendChild(fragment);
+        range.insertNode(mark);
+        if (mark.parentNode && mark.parentNode.normalize) {
+          mark.parentNode.normalize();
+        }
+      } catch (error) {
+      }
+    });
+  }
+  function selectionPayload() {
+    var selection = window.getSelection();
+    if (!selection || selection.rangeCount === 0 || selection.isCollapsed) {
+      return null;
+    }
+    var range = selection.getRangeAt(0);
+    var text = selection.toString();
+    if (!text || !text.trim()) { return null; }
+    var pageCount = totalPageCount();
+    var progression = pageCount <= 1 ? 0 : visiblePageIndex / Math.max(pageCount - 1, 1);
+    var lastProgression = progression;
+    return {
+      text: text,
+      rangeInfo: serializeRange(range),
+      progression: progression,
+      lastProgression: lastProgression
+    };
+  }
+  var selectionTimer = null;
+  document.addEventListener('selectionchange', function() {
+    clearTimeout(selectionTimer);
+    selectionTimer = setTimeout(function() {
+      var payload = selectionPayload();
+      window.webkit.messageHandlers.{{SELECTION_CHANGED_MESSAGE}}.postMessage(payload);
+    }, 120);
+  });
+  window.addEventListener('resize', function() {
+    if (isFixedLayoutDocument()) { return; }
+    setVisiblePageIndex(visiblePageIndex);
+    reportProgression(null);
+  }, { passive: true });
+  window.addEventListener('load', scheduleRelayout, { passive: true });
+  if (!isFixedLayoutDocument() && document.fonts && document.fonts.ready) {
+    document.fonts.ready.then(scheduleRelayout).catch(function() {});
+  }
+  if (!isFixedLayoutDocument()) {
+    Array.prototype.forEach.call(document.querySelectorAll('img, iframe, video'), function(node) {
+      node.addEventListener('load', scheduleRelayout, { passive: true });
+      node.addEventListener('error', scheduleRelayout, { passive: true });
+    });
+  }
+  document.addEventListener('click', function(event) {
+    var anchor = event.target.closest ? event.target.closest('a[href]') : null;
+    if (!anchor) { return; }
+    var href = anchor.getAttribute('href');
+    if (!href) { return; }
+    if (/^(https?:|mailto:|tel:)/i.test(href)) {
+      event.preventDefault();
+      window.webkit.messageHandlers.{{EXTERNAL_LINK_MESSAGE}}.postMessage({ url: href });
+      return;
+    }
+    event.preventDefault();
+    window.webkit.messageHandlers.{{INTERNAL_LINK_MESSAGE}}.postMessage({ href: href });
+  }, true);
+  window.RDReaderBridge = {
+    applyPagination: function(styleText) {
+      if (isFixedLayoutDocument()) { return; }
+      var style = document.getElementById('ss-reader-pagination');
+      if (!style) {
+        style = document.createElement('style');
+        style.id = 'ss-reader-pagination';
+        document.head.appendChild(style);
+      }
+      style.textContent = styleText;
+      ensurePaginationStructure();
+    },
+    setPageMetrics: function(pageCount, pageStride) {
+      if (isFixedLayoutDocument()) { return; }
+      configuredPageCount = Math.max(1, Math.round(pageCount || 1));
+      configuredPageStride = Math.max(1, Number(pageStride) || configuredPageStride || 1);
+      setVisiblePageIndex(visiblePageIndex);
+      scheduleRelayout();
+    },
+    scrollToPage: function(pageIndex) {
+      if (isFixedLayoutDocument()) { return; }
+      setVisiblePageIndex(pageIndex);
+      reportProgression(null);
+    },
+    scrollToLocation: function(location, fallbackPageIndex) {
+      if (location && location.fragment) {
+        var target = document.getElementById(location.fragment) || document.querySelector('[name="' + location.fragment.replace(/"/g, '\\"') + '"]');
+        if (target) {
+          setVisiblePageIndex(pageIndexForElement(target));
+          reportProgression(location.fragment);
+          return;
+        }
+      }
+      var pageCount = totalPageCount();
+      var progression = location && typeof location.progression === 'number' ? location.progression : 0;
+      var derivedPageIndex = progression > 0 && pageCount > 1
+        ? Math.round(progression * Math.max(pageCount - 1, 0))
+        : (fallbackPageIndex || 0);
+      this.scrollToPage(derivedPageIndex);
+    },
+    setHighlights: setHighlights,
+    clearHighlights: unwrapHighlights,
+    reportProgression: reportProgression,
+    selectionPayload: selectionPayload
+  };
+})();

Sources/RDReaderView/EPUBCore/Resources/epub-fixed-layout.html

@@ -0,0 +1,207 @@
+<!doctype html>
+<html>
+<head>
+  <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no">
+  <style>
+    html, body { margin: 0; padding: 0; width: 100%; height: 100%; overflow: hidden; background: {{BACKGROUND}}; }
+    body { position: relative; }
+    #ss-fixed-root {
+      position: absolute;
+      top: {{INSET_TOP}}px;
+      right: {{INSET_RIGHT}}px;
+      bottom: {{INSET_BOTTOM}}px;
+      left: {{INSET_LEFT}}px;
+      display: flex;
+      flex-direction: row;
+      align-items: stretch;
+      justify-content: center;
+      overflow: hidden;
+    }
+    .ss-fixed-viewport {
+      position: relative;
+      flex: 1 1 0;
+      min-width: 0;
+      min-height: 0;
+      overflow: hidden;
+    }
+    .ss-fixed-page {
+      position: absolute;
+      top: 50%;
+      width: 0;
+      height: 0;
+      border: 0;
+      background: transparent;
+      transform-origin: top left;
+    }
+    .ss-fixed-page[data-page-type="single"],
+    .ss-fixed-page[data-page-type="center"] {
+      left: 50%;
+      transform: translate(-50%, -50%);
+    }
+    .ss-fixed-page[data-page-type="left"] {
+      right: 0;
+      transform: translateY(-50%);
+      transform-origin: top right;
+    }
+    .ss-fixed-page[data-page-type="right"] {
+      left: 0;
+      transform: translateY(-50%);
+      transform-origin: top left;
+    }
+  </style>
+</head>
+<body>
+  <div id="ss-fixed-root">{{PANES}}</div>
+  <script>
+    (function() {
+      var Fit = { AUTO: 'auto', PAGE: 'page', WIDTH: 'width' };
+      var safeAreaInsets = { top: {{INSET_TOP}}, right: {{INSET_RIGHT}}, bottom: {{INSET_BOTTOM}}, left: {{INSET_LEFT}} };
+      var viewportSize = { width: {{VIEWPORT_WIDTH}}, height: {{VIEWPORT_HEIGHT}} };
+      var fit = '{{FIT_MODE}}';
+      var pendingFrames = 0;
+      var readySent = false;
+
+      function notifyReady() {
+        if (readySent) { return; }
+        readySent = true;
+        try {
+          window.webkit.messageHandlers.{{FIXED_LAYOUT_READY_MESSAGE}}.postMessage({ loaded: true });
+        } catch (error) {
+        }
+      }
+
+      function parsePageSizeFromViewportMetaTag(iframe) {
+        try {
+          var viewport = iframe.contentWindow.document.querySelector('meta[name="viewport"]');
+          if (!viewport) { return null; }
+          var regex = /(\w+) *= *([^\s,]+)/g;
+          var properties = {};
+          var match;
+          while ((match = regex.exec(viewport.content))) {
+            properties[match[1]] = match[2];
+          }
+          var width = Number.parseFloat(properties.width);
+          var height = Number.parseFloat(properties.height);
+          if (!width || !height) { return null; }
+          return { width: width, height: height };
+        } catch (error) {
+          return null;
+        }
+      }
+
+      function parsePageSizeFromEmbeddedImage(iframe) {
+        try {
+          var img = iframe.contentWindow.document.querySelector('img');
+          if (!img || !img.naturalWidth || !img.naturalHeight) { return null; }
+          return { width: img.naturalWidth, height: img.naturalHeight };
+        } catch (error) {
+          return null;
+        }
+      }
+
+      function pageViewportSize(iframe) {
+        var viewport = iframe.closest('.ss-fixed-viewport');
+        if (!viewport) { return viewportSize; }
+        var width = Math.max(1, viewport.clientWidth);
+        var height = Math.max(1, viewport.clientHeight);
+        if (width <= 1 || height <= 1) {
+          return viewportSize;
+        }
+        return {
+          width: width,
+          height: height
+        };
+      }
+
+      function usesWidthFit(pageSize, localViewport) {
+        if (fit === Fit.WIDTH) {
+          return true;
+        }
+        if (fit !== Fit.AUTO) {
+          return false;
+        }
+
+        var widthRatio = localViewport.width / pageSize.width;
+        var heightRatio = localViewport.height / pageSize.height;
+        return widthRatio <= heightRatio;
+      }
+
+      function layoutPage(iframe) {
+        var pageSize = iframe.__ssPageSize;
+        if (!pageSize) { return; }
+
+        var pageType = iframe.dataset.pageType || 'single';
+        var localViewport = pageViewportSize(iframe);
+        iframe.style.width = pageSize.width + 'px';
+        iframe.style.height = pageSize.height + 'px';
+
+        var widthRatio = localViewport.width / pageSize.width;
+        var heightRatio = localViewport.height / pageSize.height;
+        var widthFit = usesWidthFit(pageSize, localViewport);
+        var scale = widthFit ? widthRatio : Math.min(widthRatio, heightRatio);
+        var scaledWidth = pageSize.width * scale;
+        var scaledHeight = pageSize.height * scale;
+
+        var offsetX, offsetY;
+        if (pageType === 'left') {
+          offsetX = localViewport.width - scaledWidth;
+        } else if (pageType === 'right') {
+          offsetX = 0;
+        } else {
+          offsetX = (localViewport.width - scaledWidth) / 2;
+        }
+
+        if (widthFit && scaledHeight > localViewport.height) {
+          offsetY = safeAreaInsets.top;
+        } else {
+          offsetY = (localViewport.height - scaledHeight) / 2;
+          offsetY += (safeAreaInsets.top - safeAreaInsets.bottom) / 2;
+        }
+
+        iframe.style.left = offsetX + 'px';
+        iframe.style.top = offsetY + 'px';
+        iframe.style.transform = 'scale(' + scale + ')';
+      }
+
+      function preparePage(iframe) {
+        pendingFrames += 1;
+
+        function finalizeLoad() {
+          pendingFrames = Math.max(0, pendingFrames - 1);
+          if (pendingFrames === 0) {
+            notifyReady();
+          }
+        }
+
+        function onLoad() {
+          iframe.__ssPageSize =
+            parsePageSizeFromViewportMetaTag(iframe) ||
+            parsePageSizeFromEmbeddedImage(iframe) ||
+            pageViewportSize(iframe);
+          layoutPage(iframe);
+          finalizeLoad();
+        }
+
+        iframe.addEventListener('load', function() {
+          window.setTimeout(onLoad, 100);
+        });
+
+        iframe.addEventListener('error', function() {
+          iframe.__ssPageSize = pageViewportSize(iframe);
+          layoutPage(iframe);
+          finalizeLoad();
+        });
+      }
+
+      var pages = document.querySelectorAll('.ss-fixed-page');
+      Array.prototype.forEach.call(pages, preparePage);
+      if (pages.length === 0) {
+        notifyReady();
+      }
+      window.addEventListener('resize', function() {
+        Array.prototype.forEach.call(document.querySelectorAll('.ss-fixed-page'), layoutPage);
+      });
+    })();
+  </script>
+</body>
+</html>