feat: EPUB阅读器搜索、注释、CFI模块及大书远距跳转优化

- 实现EPUB阅读器搜索功能及选中注释功能
- 优化CFI模块，修复代码审查发现的11个问题
- 实现大书远距目录跳转与后台补全优化方案
- 优化设置面板与章节运行时联动
- 重构及大量改进优化

Sources/RDReaderView/EPUBCore/CFI/RDEPUBCFIDOMPathBuilder.swift

@@ -75,7 +75,7 @@ public enum RDEPUBCFIDOMPathBuilder {
               match.numberOfRanges > 2 else {
             return nil
         }
-        return nsAttributes.substring(with: match.range(at: 2)).nilIfEmpty
+        return nsAttributes.substring(with: match.range(at: 2)).rd_cfiNilIfEmpty
     }
 
     static func isIgnorableTag(_ tagName: String) -> Bool {
@@ -162,7 +162,7 @@ enum RDEPUBCFITextNodeMapBuilder {
         }
 
         // Use comment/CDATA-stripped HTML for both path building and tag matching
-        let cleanedHTML = stripCommentsAndCDATA(rawHTML)
+        let cleanedHTML = RDEPUBCFIDOMPathBuilder.stripCommentsAndCDATA(rawHTML)
 
         let fragments = RDEPUBCFIDOMPathBuilder.fragmentPaths(in: rawHTML)
         var markers: [RDEPUBCFIMarker] = fragmentMarkers(fragmentOffsets: fragmentOffsets, paths: fragments)
@@ -516,6 +516,14 @@ private struct RDEPUBNormalizedTextIndex {
     }
 }
 
+extension String {
+    var rd_cfiNilIfEmpty: String? {
+        let trimmed = trimmingCharacters(in: .whitespacesAndNewlines)
+        return trimmed.isEmpty ? nil : trimmed
+    }
+
+}
+
 private extension String {
     var fnv1a64: UInt64 {
         let offsetBasis: UInt64 = 14695981039346656037

Sources/RDReaderView/EPUBCore/CFI/RDEPUBCFIParser.swift

@@ -114,7 +114,7 @@ public enum RDEPUBCFIParser {
         if let open = rawStep.firstIndex(of: "["),
            let close = rawStep.lastIndex(of: "]"),
            open < close {
-            idAssertion = String(rawStep[rawStep.index(after: open)..<close]).nilIfEmpty
+            idAssertion = String(rawStep[rawStep.index(after: open)..<close]).rd_cfiNilIfEmpty
         } else {
             idAssertion = nil
         }

Sources/RDReaderView/EPUBCore/CFI/RDEPUBCFIPath.swift

@@ -34,6 +34,6 @@ public struct RDEPUBCFIStep: Codable, Equatable, Hashable {
 
     public init(index: Int, idAssertion: String? = nil) {
         self.index = index
-        self.idAssertion = idAssertion?.nilIfEmpty
+        self.idAssertion = idAssertion?.rd_cfiNilIfEmpty
     }
 }

Sources/RDReaderView/EPUBCore/CFI/RDEPUBCFIRecoveryEngine.swift

@@ -48,7 +48,13 @@ enum RDEPUBCFIRecoveryEngine {
             )
         }
 
-        if let token = tokenRecoveredResult(cfi: cfi, cfiMap: cfiMap, chapterText: chapterText, lastOffset: lastOffset) {
+        if let token = tokenRecoveredResult(
+            cfi: cfi,
+            cfiMap: cfiMap,
+            chapterText: chapterText,
+            fallbackOffset: resolved.chapterOffset,
+            lastOffset: lastOffset
+        ) {
             return token
         }
 
@@ -123,6 +129,7 @@ enum RDEPUBCFIRecoveryEngine {
         cfi: RDEPUBCFI,
         cfiMap: RDEPUBCFIMap?,
         chapterText: String?,
+        fallbackOffset: Int?,
         lastOffset: Int
     ) -> RDEPUBCFIRecoveryResult? {
         guard let cfiMap,
@@ -149,6 +156,7 @@ enum RDEPUBCFIRecoveryEngine {
         let normalizedText = RDEPUBCFITextNodeMapBuilder.normalizedText(from: chapterText)
         guard !normalizedText.isEmpty else { return nil }
 
+        let preferredOffset = fallbackOffset.map { clamp($0, lastOffset: lastOffset) }
         var bestOffset: Int?
         var bestScore = Int.max
 
@@ -161,7 +169,14 @@ enum RDEPUBCFIRecoveryEngine {
                 lastOffset: lastOffset,
                 windowRadius: 768
             )
-            let score = abs(calibrated - approximateOffset)
+            let score = tokenRecoveryScore(
+                for: anchor,
+                targetPath: cfi.contentPath,
+                approximateOffset: approximateOffset,
+                calibratedOffset: calibrated,
+                preferredOffset: preferredOffset,
+                allAnchors: cfiMap.recoveryMetadata.tokenIndex
+            )
             if score < bestScore {
                 bestScore = score
                 bestOffset = calibrated
@@ -317,4 +332,49 @@ enum RDEPUBCFIRecoveryEngine {
     private static func clamp(_ offset: Int, lastOffset: Int) -> Int {
         min(max(offset, 0), max(lastOffset, 0))
     }
+
+    private static func tokenRecoveryScore(
+        for anchor: RDEPUBCFITokenAnchor,
+        targetPath: RDEPUBCFIPath,
+        approximateOffset: Int,
+        calibratedOffset: Int,
+        preferredOffset: Int?,
+        allAnchors: [RDEPUBCFITokenAnchor]
+    ) -> Int {
+        var score = abs(calibratedOffset - approximateOffset)
+        score += pathDistance(anchor.cfiPath, targetPath) * 1_024
+
+        if let preferredOffset {
+            score += abs(approximateOffset - preferredOffset)
+            let expectedOccurrence = nearestOccurrence(
+                forToken: anchor.token,
+                preferredOffset: preferredOffset,
+                anchors: allAnchors
+            )
+            score += abs(anchor.occurrence - expectedOccurrence) * 256
+        }
+
+        return score
+    }
+
+    private static func nearestOccurrence(
+        forToken token: String,
+        preferredOffset: Int,
+        anchors: [RDEPUBCFITokenAnchor]
+    ) -> Int {
+        anchors
+            .filter { $0.token == token }
+            .min(by: { abs($0.chapterOffset - preferredOffset) < abs($1.chapterOffset - preferredOffset) })?
+            .occurrence ?? 0
+    }
+
+    private static func pathDistance(_ lhs: RDEPUBCFIPath, _ rhs: RDEPUBCFIPath) -> Int {
+        let prefix = lhs.commonPrefix(with: rhs).steps.count
+        let remainingLHS = lhs.steps.dropFirst(prefix)
+        let remainingRHS = rhs.steps.dropFirst(prefix)
+        let stepDistance = zip(remainingLHS, remainingRHS).reduce(0) { partial, pair in
+            partial + abs(pair.0.index - pair.1.index)
+        }
+        return stepDistance + abs(lhs.steps.count - rhs.steps.count) * 2
+    }
 }

Sources/RDReaderView/EPUBCore/CFI/RDEPUBCFIResolver.swift

@@ -28,7 +28,7 @@ public enum RDEPUBCFIResolver {
         if cfi.packagePath.steps.count >= 3 {
             manifestStep = cfi.packagePath.steps[2]
         } else {
-            manifestStep = cfi.packagePath.steps.last(where: { $0.idAssertion?.nilIfEmpty != nil })
+            manifestStep = cfi.packagePath.steps.last(where: { $0.idAssertion?.rd_cfiNilIfEmpty != nil })
         }
         let href = manifestStep?.idAssertion
 
@@ -40,7 +40,7 @@ public enum RDEPUBCFIResolver {
             fileIndex = nil
         }
 
-        let fragmentID = cfi.contentPath.steps.last(where: { $0.idAssertion?.nilIfEmpty != nil })?.idAssertion
+        let fragmentID = cfi.contentPath.steps.last(where: { $0.idAssertion?.rd_cfiNilIfEmpty != nil })?.idAssertion
         return RDEPUBCFIResolverResult(
             href: href,
             fileIndex: fileIndex,
@@ -48,4 +48,4 @@ public enum RDEPUBCFIResolver {
             fragmentID: fragmentID
         )
     }
-}
+}

Sources/RDReaderView/EPUBCore/CFI/RDEPUBCFITextAssertion.swift

@@ -9,8 +9,14 @@ public struct RDEPUBCFITextAssertion: Codable, Equatable, Hashable {
     public var suffix: String?
 
     public init(prefix: String? = nil, exact: String? = nil, suffix: String? = nil) {
-        self.prefix = prefix?.nilIfEmpty
-        self.exact = exact?.nilIfEmpty
-        self.suffix = suffix?.nilIfEmpty
+        self.prefix = Self.trimmedOrNil(prefix)
+        self.exact = Self.trimmedOrNil(exact)
+        self.suffix = Self.trimmedOrNil(suffix)
+    }
+
+    private static func trimmedOrNil(_ value: String?) -> String? {
+        guard let value else { return nil }
+        let trimmed = value.trimmingCharacters(in: .whitespacesAndNewlines)
+        return trimmed.isEmpty ? nil : trimmed
     }
 }

Sources/RDReaderView/EPUBCore/Models/RDEPUBAnnotationModels.swift

@@ -1,26 +1,20 @@
 import Foundation
 import UIKit
 
-// MARK: - 自定义 NSAttributedString 属性（对齐 WXRead 的 com.weread.highlight / com.weread.underline）
-
-/// 高亮自定义属性名，注入到 NSAttributedString 中供 CoreText 绘制时读取
-/// 对齐 WXRead 的 kWRHighlightAttributeName = "com.weread.highlight"
 public let kRDEPUBHighlightAttributeName = NSAttributedString.Key("com.rdreader.highlight")
 
-/// 下划线自定义属性名
-/// 对齐 WXRead 的 kWRUnderlineAttributeName = "com.weread.underline"
 public let kRDEPUBUnderlineAttributeName = NSAttributedString.Key("com.rdreader.underline")
 
 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(
@@ -37,51 +31,38 @@ public struct RDEPUBSelection: Codable, Equatable {
         self.createdAt = createdAt
     }
 
-    /// 判断是否为空选择（无文本内容）
     public var isEmpty: Bool {
         text.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty
     }
 }
 
-/// 高亮样式类型
-/// - highlight: 背景色高亮
-/// - underline: 下划线标记
 public enum RDEPUBHighlightStyle: String, Codable {
     case highlight
     case underline
 }
 
-/// 统一标注类型，对标 WXRead 的 WRBookmark 语义分层。
 public enum RDEPUBAnnotationKind: String, Codable, Equatable {
     case bookmark
     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
@@ -89,19 +70,16 @@ 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),
@@ -114,25 +92,24 @@ public struct RDEPUBTextOffsetRangeInfo: Codable, Equatable {
     }
 }
 
-/// 文本分页截断原因，描述为什么在当前位置分页
 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(
@@ -157,18 +134,15 @@ public struct RDEPUBHighlight: Codable, Equatable {
         self.createdAt = createdAt
     }
 
-    /// 是否包含用户备注
     public var hasNote: Bool {
         note?.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty == false
     }
 
-    /// 将 CSS hex 颜色转为 UIColor（对齐 WXRead 的 UIColorForHighlightColor，35% alpha）
     public var uiColor: UIColor {
         UIColor(rdHexString: color, alpha: 0.35)
             ?? UIColor(red: 248 / 255, green: 225 / 255, blue: 108 / 255, alpha: 0.35)
     }
 
-    /// 编码键，用于 Codable 序列化/反序列化
     private enum CodingKeys: String, CodingKey {
         case id
         case bookIdentifier
@@ -181,7 +155,6 @@ 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)
@@ -200,7 +173,6 @@ 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)
@@ -219,19 +191,18 @@ 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(
@@ -250,7 +221,6 @@ public struct RDEPUBBookmark: Codable, Equatable {
         self.createdAt = createdAt
     }
 
-    /// 是否包含用户备注
     public var hasNote: Bool {
         note?.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty == false
     }
@@ -260,7 +230,6 @@ public struct RDEPUBBookmark: Codable, Equatable {
     }
 }
 
-/// 统一标注模型，对标 WXRead 的 WRBookmark。
 public struct RDEPUBAnnotation: Codable, Equatable {
     public var id: String
     public var bookIdentifier: String?
@@ -358,7 +327,6 @@ public struct RDEPUBAnnotation: Codable, Equatable {
     }
 }
 
-
 private extension String {
     var nilIfEmpty: String? {
         let trimmed = trimmingCharacters(in: .whitespacesAndNewlines)

Sources/RDReaderView/EPUBCore/Models/RDEPUBPaginationModels.swift

@@ -1,46 +1,43 @@
 import Foundation
 
 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(
@@ -66,13 +63,12 @@ public struct RDEPUBTextPageMetadata: Codable, Equatable {
     }
 }
 
-/// 高亮模型，表示用户在阅读中标记的文本片段
 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) {
@@ -82,20 +78,18 @@ 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(
@@ -115,15 +109,14 @@ 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) {
@@ -134,38 +127,24 @@ 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(
@@ -204,13 +183,10 @@ 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
@@ -226,4 +202,3 @@ public struct EPUBFixedSpread: Codable, Equatable {
         }
     }
 }
-

Sources/RDReaderView/EPUBCore/Models/RDEPUBReadingLocationModels.swift

@@ -1,26 +1,35 @@
 import Foundation
 
 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 var cfi: String?
+
+    public var lastCFI: String?
+
+    public var rangeCFI: String?
+
     public init(
         bookIdentifier: String? = nil,
         href: String,
         progression: Double,
         lastProgression: Double? = nil,
         fragment: String? = nil,
-        rangeAnchor: RDEPUBTextRangeAnchor? = nil
+        rangeAnchor: RDEPUBTextRangeAnchor? = nil,
+        cfi: String? = nil,
+        lastCFI: String? = nil,
+        rangeCFI: String? = nil
     ) {
         self.bookIdentifier = bookIdentifier
         self.href = href
@@ -28,10 +37,11 @@ public struct RDEPUBLocation: Codable, Equatable {
         self.lastProgression = lastProgression.map(Self.clamp)
         self.fragment = fragment?.nilIfEmpty
         self.rangeAnchor = rangeAnchor
+        self.cfi = cfi?.nilIfEmpty
+        self.lastCFI = lastCFI?.nilIfEmpty
+        self.rangeCFI = rangeCFI?.nilIfEmpty
     }
 
-    /// 导航用的中间进度值，取 progression 和 lastProgression 的中点
-    /// 用于在字号/横竖屏变化后估算最接近的页号
     public var navigationProgression: Double {
         let end = lastProgression ?? progression
         if end.isNaN || end.isInfinite {
@@ -40,24 +50,22 @@ 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(
@@ -75,16 +83,14 @@ 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(
@@ -100,16 +106,14 @@ 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(
@@ -125,8 +129,6 @@ public struct RDEPUBReadingContext: Codable, Equatable {
     }
 }
 
-/// 文本选择模型，由 JS 桥接 ssReaderSelectionChanged 消息触发创建
-
 private extension String {
     var nilIfEmpty: String? {
         let trimmed = trimmingCharacters(in: .whitespacesAndNewlines)

Sources/RDReaderView/EPUBCore/Notes/RDEPUBNoteDetector.swift

@@ -0,0 +1,63 @@
+import Foundation
+
+public enum RDEPUBNoteDetector {
+
+    private static let noteTokens = [
+        "noteref",      
+        "footnote",     
+        "endnote",      
+        "rearnote",     
+        "fnref",        
+        "fn-",          
+        "fn_",          
+        "note",         
+        "annotation"    
+    ]
+
+    public static func makeReferenceIfLikelyNote(
+        sourceHref: String,
+        sourceCFI: String?,
+        targetHref: String,
+        targetFragment: String?,
+        targetCFI: String?,
+        targetElementHTML: String?
+    ) -> RDEPUBNoteReference? {
+
+        let haystack = [
+            targetHref,
+            targetFragment ?? "",
+            targetElementHTML ?? ""
+        ].joined(separator: " ").lowercased()
+
+        guard noteTokens.contains(where: { haystack.contains($0) }) ||
+              hasEPUBType("footnote", in: targetElementHTML) ||
+              hasEPUBType("endnote", in: targetElementHTML) ||
+              hasEPUBType("rearnote", in: targetElementHTML) else {
+            return nil
+        }
+
+        return RDEPUBNoteReference(
+            sourceHref: sourceHref,
+            sourceCFI: sourceCFI,
+            targetHref: targetHref,
+            targetFragment: targetFragment,
+            targetCFI: targetCFI,
+            label: targetFragment,
+            kind: kind(from: haystack)
+        )
+    }
+
+    public static func kind(from text: String) -> RDEPUBNoteKind {
+        let lowered = text.lowercased()
+        if lowered.contains("endnote") { return .endnote }
+        if lowered.contains("rearnote") { return .rearnote }
+        if lowered.contains("footnote") || lowered.contains("fn") { return .footnote }
+        return .unknown
+    }
+
+    private static func hasEPUBType(_ type: String, in html: String?) -> Bool {
+        guard let html else { return false }
+        let pattern = #"epub:type\s*=\s*['"][^'"]*\b"# + NSRegularExpression.escapedPattern(for: type) + #"\b[^'"]*['"]"#
+        return html.range(of: pattern, options: [.regularExpression, .caseInsensitive]) != nil
+    }
+}

Sources/RDReaderView/EPUBCore/Notes/RDEPUBNoteModels.swift

@@ -0,0 +1,85 @@
+import Foundation
+
+public enum RDEPUBNoteKind: String, Codable, Equatable {
+
+    case footnote
+
+    case endnote
+
+    case rearnote
+
+    case unknown
+}
+
+public struct RDEPUBNoteReference: Codable, Equatable {
+
+    public var sourceHref: String
+
+    public var sourceCFI: String?
+
+    public var targetHref: String
+
+    public var targetFragment: String?
+
+    public var targetCFI: String?
+
+    public var label: String?
+
+    public var kind: RDEPUBNoteKind
+
+    public init(
+        sourceHref: String,
+        sourceCFI: String? = nil,
+        targetHref: String,
+        targetFragment: String? = nil,
+        targetCFI: String? = nil,
+        label: String? = nil,
+        kind: RDEPUBNoteKind = .unknown
+    ) {
+        self.sourceHref = sourceHref
+        self.sourceCFI = sourceCFI
+        self.targetHref = targetHref
+        self.targetFragment = targetFragment
+        self.targetCFI = targetCFI
+        self.label = label?.nilIfEmpty
+        self.kind = kind
+    }
+}
+
+public struct RDEPUBResolvedNote: Equatable {
+
+    public var reference: RDEPUBNoteReference
+
+    public var sourceLocation: RDEPUBLocation?
+
+    public var targetLocation: RDEPUBLocation
+
+    public var title: String?
+
+    public var html: String
+
+    public var plainText: String
+
+    public init(
+        reference: RDEPUBNoteReference,
+        sourceLocation: RDEPUBLocation? = nil,
+        targetLocation: RDEPUBLocation,
+        title: String? = nil,
+        html: String,
+        plainText: String
+    ) {
+        self.reference = reference
+        self.sourceLocation = sourceLocation
+        self.targetLocation = targetLocation
+        self.title = title?.nilIfEmpty
+        self.html = html
+        self.plainText = plainText
+    }
+}
+
+private extension String {
+    var nilIfEmpty: String? {
+        let trimmed = trimmingCharacters(in: .whitespacesAndNewlines)
+        return trimmed.isEmpty ? nil : trimmed
+    }
+}

Sources/RDReaderView/EPUBCore/Notes/RDEPUBNoteResolver.swift

@@ -0,0 +1,159 @@
+import Foundation
+
+public final class RDEPUBNoteResolver {
+
+    private let resourceResolver: RDEPUBResourceResolver
+
+    public init(resourceResolver: RDEPUBResourceResolver) {
+        self.resourceResolver = resourceResolver
+    }
+
+    public func resolveInternalLink(
+        sourceHref: String,
+        sourceCFI: String?,
+        targetLocation: RDEPUBLocation,
+        sourceLocation: RDEPUBLocation? = nil,
+        relativeToSpineIndex spineIndex: Int?
+    ) -> RDEPUBResolvedNote? {
+        guard let normalizedTarget = resourceResolver.normalizedLocation(
+            targetLocation,
+            relativeToSpineIndex: spineIndex,
+            bookIdentifier: targetLocation.bookIdentifier
+        ) else {
+            return nil
+        }
+
+        let fragment = normalizedTarget.fragment
+        guard let elementHTML = extractElementHTML(href: normalizedTarget.href, fragment: fragment) else {
+            return nil
+        }
+
+        guard let reference = RDEPUBNoteDetector.makeReferenceIfLikelyNote(
+            sourceHref: sourceHref,
+            sourceCFI: sourceCFI,
+            targetHref: normalizedTarget.href,
+            targetFragment: fragment,
+            targetCFI: normalizedTarget.cfi,
+            targetElementHTML: elementHTML
+        ) else {
+            return nil
+        }
+
+        let sanitizedHTML = stripBacklinks(from: elementHTML)
+        let plainText = plainText(from: sanitizedHTML)
+        guard !plainText.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty else {
+            return nil
+        }
+
+        return RDEPUBResolvedNote(
+            reference: reference,
+            sourceLocation: sourceLocation,
+            targetLocation: normalizedTarget,
+            title: title(for: reference),
+            html: sanitizedHTML,
+            plainText: plainText
+        )
+    }
+
+    public func extractElementHTML(href: String, fragment: String?) -> String? {
+        guard let fragment,
+              !fragment.isEmpty,
+              let fileURL = resourceResolver.fileURL(forRelativePath: href),
+              let html = try? String(contentsOf: fileURL, encoding: .utf8) else {
+            return nil
+        }
+
+        return elementHTML(withID: fragment, in: html)
+    }
+
+    private func elementHTML(withID id: String, in html: String) -> String? {
+        let escapedID = NSRegularExpression.escapedPattern(for: id)
+        let pattern = #"<([A-Za-z][A-Za-z0-9:_-]*)(?=[^>]*(?:id|xml:id)\s*=\s*(['"])"# + escapedID + #"\2)[^>]*>"#
+        guard let regex = try? NSRegularExpression(pattern: pattern, options: [.caseInsensitive]) else {
+            return nil
+        }
+        let nsRange = NSRange(html.startIndex..<html.endIndex, in: html)
+        guard let match = regex.firstMatch(in: html, options: [], range: nsRange),
+              let startRange = Range(match.range, in: html),
+              let tagRange = Range(match.range(at: 1), in: html) else {
+            return nil
+        }
+        let tagName = String(html[tagRange])
+        guard !String(html[startRange]).hasSuffix("/>") else {
+            return String(html[startRange])
+        }
+        guard let endRange = matchingEndTagRange(
+            tagName: tagName,
+            in: html,
+            after: startRange.upperBound
+        ) else {
+            return String(html[startRange])
+        }
+        return String(html[startRange.lowerBound..<endRange.upperBound])
+    }
+
+    private func stripBacklinks(from html: String) -> String {
+        let backlinkPattern = #"<a\b[^>]*(?:rev\s*=\s*['"]footnote['"]|epub:type\s*=\s*['"][^'"]*(?:backlink|return)[^'"]*['"]|class\s*=\s*['"][^'"]*(?:backlink|return)[^'"]*['"])[^>]*>[\s\S]*?</a>"#
+        guard let regex = try? NSRegularExpression(pattern: backlinkPattern, options: [.caseInsensitive]) else {
+            return html
+        }
+        let nsRange = NSRange(html.startIndex..<html.endIndex, in: html)
+        return regex.stringByReplacingMatches(in: html, options: [], range: nsRange, withTemplate: "")
+    }
+
+    private func plainText(from html: String) -> String {
+        let withoutScripts = html
+            .replacingOccurrences(of: #"<script[\s\S]*?</script>"#, with: "", options: .regularExpression)
+            .replacingOccurrences(of: #"<style[\s\S]*?</style>"#, with: "", options: .regularExpression)
+        let withoutTags = withoutScripts.replacingOccurrences(of: #"<[^>]+>"#, with: " ", options: .regularExpression)
+        return withoutTags
+            .replacingOccurrences(of: "&nbsp;", with: " ")
+            .replacingOccurrences(of: "&lt;", with: "<")
+            .replacingOccurrences(of: "&gt;", with: ">")
+            .replacingOccurrences(of: "&amp;", with: "&")
+            .components(separatedBy: .whitespacesAndNewlines)
+            .filter { !$0.isEmpty }
+            .joined(separator: " ")
+    }
+
+    private func title(for reference: RDEPUBNoteReference) -> String {
+        switch reference.kind {
+        case .footnote:
+            return "脚注"
+        case .endnote:
+            return "尾注"
+        case .rearnote:
+            return "后注"
+        case .unknown:
+            return "注释"
+        }
+    }
+
+    private func matchingEndTagRange(
+        tagName: String,
+        in html: String,
+        after startIndex: String.Index
+    ) -> Range<String.Index>? {
+        let escapedTagName = NSRegularExpression.escapedPattern(for: tagName)
+        let pattern = #"</?\s*"# + escapedTagName + #"\b[^>]*>"#
+        guard let regex = try? NSRegularExpression(pattern: pattern, options: [.caseInsensitive]) else {
+            return nil
+        }
+
+        let searchRange = NSRange(startIndex..<html.endIndex, in: html)
+        var depth = 1
+        for match in regex.matches(in: html, options: [], range: searchRange) {
+            guard let range = Range(match.range, in: html) else { continue }
+            let tag = String(html[range])
+            if tag.hasPrefix("</") {
+                depth -= 1
+            } else if !tag.hasSuffix("/>") {
+                depth += 1
+            }
+            if depth == 0 {
+                return range
+            }
+        }
+        return nil
+    }
+}

Sources/RDReaderView/EPUBCore/RDEPUBAssetRepository.swift

@@ -1,34 +1,28 @@
-// RDEPUBAssetRepository.swift
-// EPUBCore 静态资源仓库
-// 负责从资源包中加载 EPUB 渲染所需的 JS 桥接脚本和固定版式 HTML 模板，
-// 支持模板变量替换（{{token}} 占位符）。
 
 import Foundation
 
-/// EPUB 内置资源枚举，定义桥接脚本和固定版式模板的文件名及扩展名
 enum RDEPUBAsset: String {
-    /// Rangy core 等价桥接脚本，负责提供 Web range/selection 基础能力
+
     case rangyCoreScript = "rangy-core"
-    /// Rangy serializer 等价桥接脚本，负责 DOM range 序列化/反序列化
+
     case rangySerializerScript = "rangy-serializer"
-    /// WXRead 对齐的动态 CSS 注入脚本
+
     case cssInjectorScript = "cssInjector"
-    /// WXRead 对齐的 WeReadApi JS-Native 桥接脚本
+
     case weReadAPIScript = "WeReadApi"
-    /// JS 桥接脚本（epub-bridge.js），注入到 WebView 中实现原生-JS 通信
+
     case bridgeScript = "epub-bridge"
-    /// 固定版式 HTML 模板（epub-fixed-layout.html），用于渲染 pre-paginated 类型的 EPUB
+
     case fixedLayoutTemplate = "epub-fixed-layout"
-    /// WXRead 对齐的 default.css
+
     case wxReadDefaultCSS = "wxread-default"
-    /// WXRead 对齐的 replace.css
+
     case wxReadReplaceCSS = "wxread-replace"
-    /// WXRead 对齐的 dark.css
+
     case wxReadDarkCSS = "wxread-dark"
-    /// WXRead 对齐的 replaceForLatinLanguageBook.css
+
     case wxReadLatinReplaceCSS = "wxread-replace-latin"
 
-    /// 对应的文件扩展名
     var fileExtension: String {
         switch self {
         case .rangyCoreScript, .rangySerializerScript, .cssInjectorScript, .weReadAPIScript, .bridgeScript:
@@ -41,13 +35,8 @@ 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 {
@@ -61,7 +50,6 @@ enum RDEPUBAssetRepository {
         return content
     }
 
-    /// 获取资源所在的 Bundle（优先使用已解析的子 bundle，兜底到宿主 bundle）
     private static var resourceBundle: Bundle {
         if let bundle = resolvedBundle {
             return bundle
@@ -69,7 +57,6 @@ 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 {
@@ -82,5 +69,4 @@ enum RDEPUBAssetRepository {
     }()
 }
 
-/// 用于定位当前模块 Bundle 的标记类
 private final class RDEPUBAssetBundleToken {}

Sources/RDReaderView/EPUBCore/RDEPUBFixedLayoutTemplate.swift

@@ -1,25 +1,15 @@
-// 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"
@@ -36,7 +26,6 @@ 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)))
@@ -44,7 +33,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,35 +1,27 @@
-// 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: .rangyCoreScript),
@@ -50,10 +42,6 @@ enum RDEPUBJavaScriptBridge {
         ].joined(separator: "\n\n")
     }
 
-    /// 生成重排模式下的分页渲染脚本
-    /// 注入 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)
@@ -87,10 +75,6 @@ enum RDEPUBJavaScriptBridge {
         """
     }
 
-    /// 生成固定版式模式下的主题应用脚本
-    /// 仅应用共享主题（背景色），不涉及分页逻辑（固定版式由 HTML 自身布局决定）
-    /// - Parameter request: 固定版式渲染请求，包含背景色等信息
-    /// - Returns: 可直接通过 evaluateJavaScript 执行的脚本字符串
     static func applyFixedPresentationScript(for request: RDEPUBFixedRenderRequest) -> String {
         """
         (function() {
@@ -105,11 +89,6 @@ enum RDEPUBJavaScriptBridge {
         """
     }
 
-    /// 生成搜索高亮脚本
-    /// 在当前文档和所有 iframe 中查找关键词并用 span 标记高亮，
-    /// 活跃匹配项使用特殊样式并自动滚动到视图中央
-    /// - Parameter presentation: 搜索展示信息（关键词、各资源的匹配数量等）
-    /// - Returns: 搜索高亮脚本字符串
     static func applySearchScript(for presentation: RDEPUBSearchPresentation?) -> String {
         let payload = jsonString(from: searchPayload(presentation), fallback: "null")
         return """
@@ -121,9 +100,6 @@ enum RDEPUBJavaScriptBridge {
         """
     }
 
-    /// 生成获取当前装饰数据的脚本
-    /// 从 WebView 中读取高亮和搜索高亮的 DOM 装饰信息，用于同步原生标注状态
-    /// - Returns: 可直接通过 evaluateJavaScript 执行的脚本字符串，返回包含 highlights 和 search 的对象
     static func resolveDecorationsScript() -> String {
         """
         (function() {
@@ -133,14 +109,12 @@ 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 }
@@ -153,7 +127,6 @@ enum RDEPUBJavaScriptBridge {
         }
     }
 
-    /// 将目标位置转换为 JS 可用的字典（含 progression、fragment）
     private static func targetLocationPayload(_ location: RDEPUBLocation?) -> [String: Any]? {
         guard let location else { return nil }
         return [
@@ -163,7 +136,6 @@ enum RDEPUBJavaScriptBridge {
         ]
     }
 
-    /// 将搜索展示信息转换为 JS 可用的字典
     private static func searchPayload(_ presentation: RDEPUBSearchPresentation?) -> [String: Any]? {
         guard let presentation else { return nil }
         return [
@@ -178,7 +150,6 @@ enum RDEPUBJavaScriptBridge {
         ]
     }
 
-    /// 将任意对象序列化为 JSON 字符串，失败时返回 fallback
     private static func jsonString(from object: Any?, fallback: String) -> String {
         guard let object else { return fallback }
         guard JSONSerialization.isValidJSONObject(object),
@@ -189,8 +160,6 @@ enum RDEPUBJavaScriptBridge {
         return string
     }
 
-    /// 将 Swift 字符串转换为 JavaScript 字符串字面量
-    /// nil 值转为 "null"，非空值序列化为 JSON 字符串后去除外层方括号
     private static func javaScriptStringLiteral(_ value: String?) -> String {
         guard let value else { return "null" }
         return jsonString(from: [value], fallback: "[null]")

Sources/RDReaderView/EPUBCore/RDEPUBModels.swift

@@ -1,71 +1,45 @@
-//
-//  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(
@@ -89,22 +63,20 @@ 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(
@@ -125,37 +97,31 @@ 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(
@@ -179,14 +145,12 @@ 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] = []) {
@@ -196,23 +160,22 @@ 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
-    /// 归档条目路径包含路径穿越或非法字符
+
     case invalidArchiveEntryPath(String)
 
     public var errorDescription: String? {

Sources/RDReaderView/EPUBCore/RDEPUBNavigatorLayoutContext.swift

@@ -1,22 +1,16 @@
-// 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(
@@ -33,7 +27,6 @@ public struct RDEPUBNavigatorLayoutContext: Equatable {
         self.reflowableContentInsets = reflowableContentInsets
     }
 
-    /// 计算单页视口尺寸（双页模式下宽度除以 2）
     public var viewportSize: CGSize {
         let width: CGFloat
         if pagesPerScreen > 1 {
@@ -44,7 +37,6 @@ 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,33 +1,20 @@
-//
-//  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,45 +1,38 @@
-// 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()
@@ -70,12 +63,6 @@ public final class RDEPUBPaginator: NSObject {
         webView.removeFromSuperview()
     }
 
-    /// 计算所有 spine 项的分页数
-    /// - Parameters:
-    ///   - parser: EPUB 解析器
-    ///   - hostingView: 承载 WebView 的父视图
-    ///   - presentation: 展示样式（视口、内边距、字号、行高）
-    ///   - completion: 完成回调，返回每个 spine 项的页数数组
     public func calculate(
         parser: RDEPUBParser,
         hostingView: UIView,
@@ -106,7 +93,6 @@ public final class RDEPUBPaginator: NSObject {
         measureNextSpineItem()
     }
 
-    /// 便捷方法：使用独立参数计算所有 spine 项的分页数
     public func calculate(
         parser: RDEPUBParser,
         hostingView: UIView,
@@ -129,13 +115,6 @@ public final class RDEPUBPaginator: NSObject {
         )
     }
 
-    /// 仅计算单个 spine 项的分页数
-    /// - Parameters:
-    ///   - parser: EPUB 解析器
-    ///   - spineIndex: 要测量的 spine 项索引
-    ///   - hostingView: 承载 WebView 的父视图
-    ///   - presentation: 展示样式
-    ///   - completion: 完成回调，返回该 spine 项的页数
     public func calculateSingleSpinePageCount(
         parser: RDEPUBParser,
         spineIndex: Int,
@@ -167,7 +146,6 @@ public final class RDEPUBPaginator: NSObject {
         measureNextSpineItem()
     }
 
-    /// 便捷方法：使用独立参数计算单个 spine 项的分页数
     public func calculateSingleSpinePageCount(
         parser: RDEPUBParser,
         spineIndex: Int,
@@ -192,7 +170,6 @@ public final class RDEPUBPaginator: NSObject {
         )
     }
 
-    /// 静态方法：将分页 CSS 注入到 HTML 字符串中（用于预渲染场景）
     public static func injectPaginationCSS(
         into html: String,
         viewportSize: CGSize,
@@ -215,7 +192,6 @@ public final class RDEPUBPaginator: NSObject {
         )
     }
 
-    /// 测量下一个 spine 项：加载文件到 WebView，跳过不可渲染或文件缺失的项
     private func measureNextSpineItem() {
         guard let parser else {
             finishIfNeeded()
@@ -253,12 +229,10 @@ 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
@@ -273,7 +247,6 @@ public final class RDEPUBPaginator: NSObject {
         cleanupMeasurementState()
     }
 
-    /// 清理测量状态，释放 WebView 和所有引用
     private func cleanupMeasurementState() {
         parser = nil
         hostingView = nil
@@ -289,16 +262,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")
     }
 
-    /// 各轮测量记录值（用于稳定性日志）
     private var measurementPassValues: [Int] = []
 
-    /// 调度多轮测量：0ms/80ms/180ms 三轮延迟，取最大值以应对布局抖动
     private func scheduleMeasurementPass() {
         let sessionID = activeSessionID
         let delays: [TimeInterval] = [0.0, 0.08, 0.18]
@@ -308,7 +278,7 @@ public final class RDEPUBPaginator: NSObject {
                 return
             }
             let finalValue = max(1, pendingMeasurementValue)
-            // 测量稳定性日志：三轮差异过大时告警
+
             if measurementPassValues.count >= 2 {
                 let minVal = measurementPassValues.min() ?? 1
                 let maxVal = measurementPassValues.max() ?? 1
@@ -331,7 +301,6 @@ 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)")
@@ -357,6 +326,7 @@ public final class RDEPUBPaginator: NSObject {
 }
 
 extension RDEPUBPaginator: WKNavigationDelegate {
+
     public func webView(_ webView: WKWebView, decidePolicyFor navigationAction: WKNavigationAction, decisionHandler: @escaping (WKNavigationActionPolicy) -> Void) {
         guard let url = navigationAction.request.url else {
             decisionHandler(.cancel)
@@ -402,7 +372,6 @@ 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,15 +1,9 @@
-// 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)
@@ -30,10 +24,6 @@ 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)
@@ -66,17 +56,12 @@ extension RDEPUBParser {
         return extractionURL
     }
 
-    /// 校验归档条目路径，防止路径穿越攻击
-    /// - Parameters:
-    ///   - entryPath: 归档中的原始条目路径
-    ///   - extractionRoot: 解压根目录
-    /// - Returns: 校验通过的目标 URL，非法路径返回 nil
     private func validatedExtractionDestination(for entryPath: String, extractionRoot: URL) -> URL? {
-        // 拒绝绝对路径
+
         if entryPath.hasPrefix("/") {
             return nil
         }
-        // 拒绝包含 .. 的路径段
+
         let components = entryPath.split(separator: "/", omittingEmptySubsequences: true)
         if components.contains(where: { $0 == ".." }) {
             return nil
@@ -84,15 +69,13 @@ extension RDEPUBParser {
         let destinationURL = extractionRoot.appendingPathComponent(entryPath)
         let standardizedDest = destinationURL.standardizedFileURL.path
         let standardizedRoot = extractionRoot.standardizedFileURL.path
-        // 确保最终路径位于解压根目录下
+
         guard standardizedDest.hasPrefix(standardizedRoot) else {
             return nil
         }
         return destinationURL
     }
 
-    /// 计算 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)
@@ -106,14 +89,12 @@ 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 = [:]
@@ -122,9 +103,8 @@ 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,18 +1,8 @@
-// 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
@@ -62,47 +52,52 @@ 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] = []
+
     private var spineReferences: [OPFSpineReference] = []
+
     private let xmlContext = XMLParserContext()
+
     private var uniqueIdentifierID: String?
+
     private var currentIdentifierElementID: String?
+
     private var currentMetaProperty: String?
+
     private var identifierByID: [String: String] = [:]
+
     private var manifestTitleByID: [String: String] = [:]
+
     private var currentMetaRefinesID: String?
+
     private var ncxID: String?
 
-    /// 将解析中间结果组装为 OPFPackageDocument 结构体
     func packageDocument() -> OPFPackageDocument {
         if metadata.identifier == nil, let fallbackIdentifier = identifierByID.values.first {
             metadata.identifier = fallbackIdentifier
@@ -251,7 +246,6 @@ final class OPFPackageParserDelegate: NSObject, XMLParserDelegate {
         xmlContext.endElement()
     }
 
-    /// 当前解析所在的 OPF 区域（metadata/manifest/spine/other）
     private var currentSection: XMLSection {
         if xmlContext.containsElement(named: "manifest") {
             return .manifest
@@ -265,7 +259,6 @@ 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 {
@@ -290,7 +283,6 @@ 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") {
@@ -320,13 +312,11 @@ 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
@@ -334,14 +324,12 @@ 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
@@ -349,7 +337,6 @@ enum XMLName {
             .map(String.init)
     }
 
-    /// 从 refines 属性值中提取 ID（去掉 "#" 前缀）
     static func refinedID(from rawValue: String) -> String? {
         let trimmed = rawValue.trimmingCharacters(in: .whitespacesAndNewlines)
         guard trimmed.hasPrefix("#") else {
@@ -359,14 +346,12 @@ 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,13 +1,8 @@
-// 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
@@ -15,9 +10,6 @@ extension RDEPUBParser {
         return hasInteractiveContent() ? .webInteractive : .textReflowable
     }
 
-    /// 检测出版物是否包含交互内容
-    /// 通过 manifest 中的脚本媒体类型和 "scripted" 属性，
-    /// 以及扫描 HTML 中的 script/iframe/video/audio/canvas/svg/form 等标签
     public func hasInteractiveContent() -> Bool {
         let interactiveMediaTypes = [
             "application/javascript",
@@ -42,8 +34,6 @@ extension RDEPUBParser {
         return false
     }
 
-    /// 检测 HTML 是否包含需要走 Web 交互渲染的特征。
-    /// 注意：普通小说 EPUB 常用静态 SVG 包封面图，不能仅因 `<svg>` 就误判为 interactive。
     private func containsInteractiveMarkup(_ html: String) -> Bool {
         let interactivePattern = #"<(script|iframe|video|audio|canvas|object|embed)\b|\bon(load|click|touchstart|touchend|mouseover|submit|change|input)=|hype_generated_script|swiper|webview"#
         if html.range(of: interactivePattern, options: [.regularExpression, .caseInsensitive]) != nil {

Sources/RDReaderView/EPUBCore/RDEPUBParser+Resources.swift

@@ -1,18 +1,13 @@
-// 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
@@ -20,13 +15,11 @@ 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
@@ -41,7 +34,6 @@ 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 }
@@ -55,7 +47,6 @@ 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 {
@@ -65,7 +56,6 @@ 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")
@@ -79,7 +69,6 @@ extension RDEPUBParser {
         return nil
     }
 
-    /// 通过 spine 索引读取 HTML 内容
     public func htmlString(forSpineIndex index: Int) -> String? {
         guard spine.indices.contains(index) else {
             return nil
@@ -87,7 +76,6 @@ 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
@@ -95,7 +83,6 @@ 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,14 +1,8 @@
-// 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()
 
@@ -31,7 +25,6 @@ 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 {
@@ -49,7 +42,6 @@ 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 {
@@ -67,7 +59,6 @@ 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
@@ -91,13 +82,11 @@ 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 {
@@ -111,14 +100,12 @@ 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() }
     }
@@ -151,7 +138,6 @@ 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?
@@ -216,7 +202,6 @@ 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?
@@ -303,7 +288,6 @@ 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,41 +1,30 @@
-// 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()
 
@@ -56,8 +45,6 @@ public final class RDEPUBParser {
         try parseOPF(at: packageURL)
     }
 
-    /// 解析 OPF 文件：metadata/manifest/spine/TOC
-    /// - Parameter opfURL: OPF 文件路径
     public func parseOPF(at opfURL: URL) throws {
         resetPublicationState()
 
@@ -81,12 +68,10 @@ 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,33 +1,28 @@
-// 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 var numberOfColumns: Int
-    /// 多栏排版栏间距
+
     public var columnGap: CGFloat
 
     public init(
@@ -56,7 +51,6 @@ public struct RDEPUBPreferences: Equatable {
         self.fixedLayoutSpreadMode = fixedLayoutSpreadMode
     }
 
-    /// 从偏好设置生成重排模式的展示样式
     public func presentationStyle(viewportSize: CGSize) -> RDEPUBPresentationStyle {
         RDEPUBPresentationStyle(
             viewportSize: viewportSize,
@@ -70,7 +64,6 @@ public struct RDEPUBPreferences: Equatable {
         )
     }
 
-    /// 根据页面和偏好设置生成对应的渲染请求（自动区分固定版式和重排）
     public func renderRequest(
         for page: EPUBPage,
         publication: RDEPUBPublication,

Sources/RDReaderView/EPUBCore/RDEPUBPublication.swift

@@ -1,67 +1,49 @@
-// 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
 
-    /// 基于解析器创建出版物门面对象
-    /// - Parameter parser: 已完成解析的 EPUB 解析器
     public init(parser: RDEPUBParser) {
         self.parser = parser
         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
@@ -80,7 +62,6 @@ public final class RDEPUBPublication {
         }
     }
 
-    /// 根据偏好和视口生成固定版式的 spread 数组
     public func makeFixedSpreads(preferences: RDEPUBPreferences, viewportSize: CGSize) -> [EPUBFixedSpread] {
         EPUBFixedSpread.makeSpreads(
             spine: spine,

Sources/RDReaderView/EPUBCore/RDEPUBReadingSession.swift

@@ -1,58 +1,46 @@
-// 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?
-    /// 挂起的高亮 Range 信息（仅 Web 渲染路径使用）
+
     public private(set) var pendingNavigationHighlightRangeInfo: String?
-    /// 当前视口信息
+
     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 = []
@@ -63,20 +51,17 @@ 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
@@ -84,7 +69,6 @@ public final class RDEPUBReadingSession {
         return (stagedPages, stagedChapters)
     }
 
-    /// 如果状态稳定且有暂存快照，则消费并返回（原子操作）
     public func consumeStagedSnapshotIfAllowed() -> (snapshot: PaginationSnapshot, restoreLocation: RDEPUBLocation?)? {
         guard navigatorState.isStableForSnapshotApplication,
               let stagedPages,
@@ -96,21 +80,18 @@ public final class RDEPUBReadingSession {
         return ((stagedPages, stagedChapters), restoreLocation)
     }
 
-    /// 清除暂存快照
     public func clearStagedSnapshot() {
         stagedPages = nil
         stagedChapters = nil
         stagedRestoreLocation = nil
     }
 
-    /// 清除挂起的导航请求
     public func clearPendingNavigation() {
         pendingNavigationLocation = nil
         pendingNavigationPageNum = nil
         pendingNavigationHighlightRangeInfo = nil
     }
 
-    /// 检查指定页码和 spine 索引是否有挂起的导航位置
     public func pendingLocation(forPageNumber pageNumber: Int, spineIndex: Int?) -> RDEPUBLocation? {
         guard pendingNavigationPageNum == pageNumber,
               let pendingNavigationLocation else {
@@ -126,7 +107,6 @@ public final class RDEPUBReadingSession {
         return pendingNavigationLocation
     }
 
-    /// 查询指定页是否存在待消费的高亮 Range 信息。
     public func pendingHighlightRangeInfo(forPageNumber pageNumber: Int, spineIndex: Int?) -> String? {
         guard pendingNavigationPageNum == pageNumber,
               let pendingNavigationHighlightRangeInfo,
@@ -146,7 +126,6 @@ public final class RDEPUBReadingSession {
         return pendingNavigationHighlightRangeInfo
     }
 
-    /// 判断指定页面是否包含给定的 spine 索引（固定版式需检查 spread 内所有资源）
     public func pageContains(spineIndex: Int, in page: EPUBPage) -> Bool {
         if let fixedSpread = page.fixedSpread {
             return fixedSpread.resources.contains(where: { $0.spineIndex == spineIndex })
@@ -154,7 +133,6 @@ public final class RDEPUBReadingSession {
         return page.spineIndex == spineIndex
     }
 
-    /// 根据页面信息生成回退位置（用于无精确位置时的兜底）
     public func fallbackLocation(for page: EPUBPage, bookIdentifier: String?) -> RDEPUBLocation? {
         if let fixedSpread = page.fixedSpread {
             return RDEPUBLocation(
@@ -184,7 +162,6 @@ public final class RDEPUBReadingSession {
         )
     }
 
-    /// 获取当前可见页面对应的位置
     public func currentVisibleLocation(currentPageNumber: Int, bookIdentifier: String?) -> RDEPUBLocation? {
         guard currentPageNumber > 0,
               activePages.indices.contains(currentPageNumber - 1) else {
@@ -193,7 +170,6 @@ 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),
@@ -203,7 +179,6 @@ 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
@@ -244,7 +219,6 @@ public final class RDEPUBReadingSession {
         return candidates[localIndex].offset
     }
 
-    /// 排队导航到指定位置：规范化位置、查找页面索引、设置挂起导航、切换到 jumping 状态
     public func queueNavigation(
         to location: RDEPUBLocation,
         relativeToSpineIndex spineIndex: Int? = nil,
@@ -271,7 +245,6 @@ public final class RDEPUBReadingSession {
         return pageIndex + 1
     }
 
-    /// 更新阅读上下文：规范化位置、设置视口和阅读上下文、清除挂起导航、回到 idle 状态
     public func updateReadingContext(
         pageNumber: Int,
         location: RDEPUBLocation,
@@ -320,13 +293,10 @@ 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,53 +1,34 @@
-//
-//  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
-    /// 栏数，对标 WXRead 的多栏分页配置
+
     public var numberOfColumns: Int
-    /// 栏间距，对标 WXRead 的 columnGap
+
     public var columnGap: CGFloat
-    /// 主题背景色（CSS 颜色值，如 "#FFFFFF"）
+
     public var themeBackgroundColor: String?
-    /// 主题文字色（CSS 颜色值，如 "#000000"）
+
     public var themeTextColor: String?
 
     public init(
@@ -71,25 +52,24 @@ 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?
-    /// 目标高亮的 DOM Range 信息，用于 Web 渲染路径下的精确跳转
+
     public var targetHighlightRangeInfo: String?
-    /// 高亮列表
+
     public var highlights: [RDEPUBHighlight]
-    /// 搜索结果展示信息
+
     public var searchPresentation: RDEPUBSearchPresentation?
 
     public init(
@@ -115,19 +95,18 @@ 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(
@@ -147,15 +126,12 @@ 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
@@ -163,7 +139,6 @@ public enum RDEPUBRenderRequest: Equatable {
         return false
     }
 
-    /// 主资源的 spine 索引
     public var primarySpineIndex: Int {
         switch self {
         case .reflowable(let request):
@@ -173,7 +148,6 @@ public enum RDEPUBRenderRequest: Equatable {
         }
     }
 
-    /// 主资源的路径
     public var primaryHref: String {
         switch self {
         case .reflowable(let request):

Sources/RDReaderView/EPUBCore/RDEPUBResourceResolver.swift

@@ -1,41 +1,30 @@
-// 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
@@ -70,7 +59,6 @@ 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
@@ -93,7 +81,6 @@ 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
@@ -101,7 +88,6 @@ public final class RDEPUBResourceResolver {
         return fileURL(forRelativePath: normalizedHref)
     }
 
-    /// 规范化位置对象：解析 href、保留 progression 和 fragment
     public func normalizedLocation(
         _ location: RDEPUBLocation,
         relativeToSpineIndex spineIndex: Int? = nil,
@@ -131,18 +117,19 @@ public final class RDEPUBResourceResolver {
             progression: location.progression,
             lastProgression: location.lastProgression,
             fragment: fragment,
-            rangeAnchor: location.rangeAnchor
+            rangeAnchor: location.rangeAnchor,
+            cfi: location.cfi,
+            lastCFI: location.lastCFI,
+            rangeCFI: location.rangeCFI
         )
     }
 
-    /// 通过规范化 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
@@ -150,7 +137,6 @@ 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
@@ -158,7 +144,6 @@ 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
@@ -166,7 +151,6 @@ 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,12 +1,7 @@
-// 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 {
     struct DebugMetrics {
         let streamedResponses: Int
@@ -14,18 +9,16 @@ public final class RDEPUBResourceURLSchemeHandler: NSObject, WKURLSchemeHandler
         let failures: Int
     }
 
-    /// 自定义协议名
     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] = [:]
     private static let debugMetricsQueue = DispatchQueue(label: "com.ssreaderview.epub.scheme-handler.metrics")
     private static var streamedResponseCount = 0
@@ -55,8 +48,6 @@ public final class RDEPUBResourceURLSchemeHandler: NSObject, WKURLSchemeHandler
         }
     }
 
-    /// 处理 URL Scheme 请求：解析文件路径、读取数据、返回响应
-    /// 对缺失的可选资源（字体/图片/CSS/JS）返回空响应，其他返回 404 错误
     public func webView(_ webView: WKWebView, start urlSchemeTask: any WKURLSchemeTask) {
         let taskID = ObjectIdentifier(urlSchemeTask as AnyObject)
         syncQueue.sync {
@@ -100,20 +91,17 @@ public final class RDEPUBResourceURLSchemeHandler: NSObject, WKURLSchemeHandler
         }
     }
 
-    /// 取消 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
@@ -203,7 +191,6 @@ public final class RDEPUBResourceURLSchemeHandler: NSObject, WKURLSchemeHandler
         }
     }
 
-    /// 根据文件扩展名推断 MIME 类型
     private static func mimeType(for pathExtension: String) -> String {
         switch pathExtension.lowercased() {
         case "html", "htm":
@@ -243,7 +230,6 @@ 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":
@@ -253,7 +239,6 @@ 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,37 +1,23 @@
-// RDEPUBSearchEngine.swift
-// EPUB 全文搜索引擎
-// 遍历 spine 中的线性 HTML/XHTML 资源，提取纯文本后执行大小写不敏感的关键词搜索，
-// 返回匹配项列表（含 href、progression、previewText 等）。
 
 import Foundation
 import UIKit
 
-/// 搜索引擎协议，定义全文搜索接口
 protocol RDEPUBSearchEngine {
-    /// 执行全文搜索
-    /// - Parameter keyword: 搜索关键词
-    /// - Returns: 匹配结果列表
+
     func search(keyword: String) -> [RDEPUBSearchMatch]
 }
 
-/// HTML 全文搜索引擎实现
-/// 通过解析 HTML 为纯文本，逐章执行关键词匹配
 final class RDEPUBHTMLSearchEngine: RDEPUBSearchEngine {
-    /// EPUB 解析器（用于读取 HTML 内容）
+
     private let parser: RDEPUBParser
-    /// EPUB 出版物（用于遍历 spine 和规范化 href）
+
     private let publication: RDEPUBPublication
 
-    /// 创建 HTML 全文搜索引擎
-    /// - Parameters:
-    ///   - parser: EPUB 解析器（用于读取 HTML 内容）
-    ///   - publication: EPUB 出版物（用于遍历 spine 和规范化 href）
     init(parser: RDEPUBParser, publication: RDEPUBPublication) {
         self.parser = parser
         self.publication = publication
     }
 
-    /// 执行全文搜索：遍历所有线性 spine 项，提取纯文本后匹配关键词
     func search(keyword: String) -> [RDEPUBSearchMatch] {
         let normalizedKeyword = keyword.trimmingCharacters(in: .whitespacesAndNewlines)
         guard !normalizedKeyword.isEmpty else {
@@ -53,7 +39,6 @@ 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)
@@ -73,7 +58,6 @@ 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
@@ -85,7 +69,6 @@ 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
@@ -127,7 +110,6 @@ 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,27 +1,26 @@
-// 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 var cfi: String?
+
+    public var rangeCFI: String?
+
     public init(
         href: String,
         progression: Double,
@@ -29,7 +28,9 @@ public struct RDEPUBSearchMatch: Codable, Equatable {
         localMatchIndex: Int,
         rangeLocation: Int? = nil,
         rangeLength: Int,
-        rangeAnchor: RDEPUBTextRangeAnchor? = nil
+        rangeAnchor: RDEPUBTextRangeAnchor? = nil,
+        cfi: String? = nil,
+        rangeCFI: String? = nil
     ) {
         self.href = href
         self.progression = progression
@@ -38,18 +39,19 @@ public struct RDEPUBSearchMatch: Codable, Equatable {
         self.rangeLocation = rangeLocation
         self.rangeLength = rangeLength
         self.rangeAnchor = rangeAnchor
+        self.cfi = cfi
+        self.rangeCFI = rangeCFI
     }
 }
 
-/// 搜索结果摘要，包含关键词、总匹配数和当前匹配项
 public struct RDEPUBSearchResult: Codable, Equatable {
-    /// 搜索关键词
+
     public var keyword: String
-    /// 总匹配数量
+
     public var totalMatchCount: Int
-    /// 当前匹配项的索引（从 1 开始）
+
     public var currentMatchIndex: Int?
-    /// 当前高亮的匹配项
+
     public var currentMatch: RDEPUBSearchMatch?
 
     public init(
@@ -65,13 +67,12 @@ 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) {
@@ -80,7 +81,6 @@ public struct RDEPUBSearchState: Codable, Equatable {
         self.currentMatchIndex = currentMatchIndex
     }
 
-    /// 获取当前匹配项
     public var currentMatch: RDEPUBSearchMatch? {
         guard let currentMatchIndex,
               matches.indices.contains(currentMatchIndex) else {
@@ -89,7 +89,6 @@ public struct RDEPUBSearchState: Codable, Equatable {
         return matches[currentMatchIndex]
     }
 
-    /// 转换为搜索结果摘要
     public var result: RDEPUBSearchResult {
         RDEPUBSearchResult(
             keyword: keyword,
@@ -100,13 +99,12 @@ 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) {
@@ -116,11 +114,10 @@ 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,13 +1,8 @@
-// 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
@@ -22,8 +17,6 @@ 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;" } ?? ""
@@ -106,7 +99,6 @@ 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;" } ?? ""
@@ -153,7 +145,6 @@ public enum RDEPUBStyleSheetBuilder {
         """
     }
 
-    /// 生成分页测量脚本（JS）：注入 CSS 后测量 scrollWidth，计算页数
     public static func measurementScript(for presentation: RDEPUBPresentationStyle) -> String {
         let style = measurementCSS(for: presentation)
             .replacingOccurrences(of: "\\", with: "\\\\")
@@ -185,7 +176,6 @@ public enum RDEPUBStyleSheetBuilder {
         """
     }
 
-    /// 从展示样式计算所有 CSS 变量值（视口尺寸、内边距、字号、行高等）
     private static func cssValues(for presentation: RDEPUBPresentationStyle) -> (
         viewportWidth: String,
         viewportHeight: String,

Sources/RDReaderView/EPUBCore/RDEPUBTextAnchor.swift

@@ -1,26 +1,18 @@
-// 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(
@@ -67,11 +59,10 @@ public struct RDEPUBTextAnchor: Codable, Equatable {
     }
 }
 
-/// 文本范围锚点，由起止锚点组成的区间
 public struct RDEPUBTextRangeAnchor: Codable, Equatable {
-    /// 起始锚点
+
     public let start: RDEPUBTextAnchor
-    /// 结束锚点
+
     public let end: RDEPUBTextAnchor
 
     public init(start: RDEPUBTextAnchor, end: RDEPUBTextAnchor) {
@@ -79,7 +70,6 @@ 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/RDEPUBWebView+Configuration.swift

@@ -1,14 +1,9 @@
-// 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
@@ -73,18 +68,15 @@ 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 {
@@ -106,7 +98,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,13 +1,9 @@
-// RDEPUBWebView+FixedLayout.swift
-// RDEPUBWebView 的固定版式渲染扩展
-// 处理固定版式（Fixed Layout）的加载流程：生成 HTML 模板、
-// 计算加载签名（去重）、设置固定版式就绪回退定时器等。
 
 import UIKit
 import WebKit
 
 extension RDEPUBWebView {
-    /// 便捷方法：加载固定版式的 spread 页面
+
     public func loadFixedSpread(
         parser: RDEPUBParser,
         spread: EPUBFixedSpread,
@@ -28,7 +24,6 @@ extension RDEPUBWebView {
         load(publication: parser.makePublication(), request: request)
     }
 
-    /// 处理固定版式加载：设置状态、生成 HTML、加载到 WebView
     func handleFixedLayoutLoad(
         publication: RDEPUBPublication,
         request: RDEPUBFixedRenderRequest,
@@ -55,11 +50,10 @@ extension RDEPUBWebView {
         RDEPUBWebViewDebug.log(debugScope, message: "load fixed spread resources=\(request.spread.resources.map(\.href).joined(separator: ",")) fit=\(request.fit.rawValue)")
         webView.loadHTMLString(
             html,
-            baseURL: URL(string: "\(RDEPUBResourceURLSchemeHandler.scheme)://\(RDEPUBResourceURLSchemeHandler.host)/")
+            baseURL: URL(string: "\(RDEPUBResourceURLSchemeHandler.scheme):///")
         )
     }
 
-    /// 生成固定版式加载签名（用于去重相同请求）
     func fixedLayoutLoadSignature(publicationKey: String, request: RDEPUBFixedRenderRequest) -> String {
         let searchSignature = [
             request.searchPresentation?.keyword ?? "",
@@ -87,7 +81,6 @@ extension RDEPUBWebView {
         ].joined(separator: "#")
     }
 
-    /// 调度固定版式就绪回退定时器（1 秒后如果未收到 ready 消息则手动触发渲染完成）
     func scheduleFixedLayoutReadyFallback() {
         let workItem = DispatchWorkItem { [weak self] in
             RDEPUBWebViewDebug.log(self?.debugScope ?? "ReaderWebView", message: "fixed ready fallback fired")
@@ -101,7 +94,6 @@ extension RDEPUBWebView {
         DispatchQueue.main.asyncAfter(deadline: .now() + 1.0, execute: workItem)
     }
 
-    /// 取消固定版式就绪回退定时器
     func cancelFixedLayoutReadyFallback() {
         fixedLayoutReadyWorkItem?.cancel()
         fixedLayoutReadyWorkItem = nil

Sources/RDReaderView/EPUBCore/RDEPUBWebView+JavaScriptBridge.swift

@@ -1,14 +1,9 @@
-// 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
@@ -16,7 +11,6 @@ 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
@@ -52,7 +46,6 @@ 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,
@@ -79,7 +72,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,14 +1,9 @@
-// RDEPUBWebView+Reflowable.swift
-// RDEPUBWebView 的重排模式渲染扩展
-// 处理重排（Reflowable）模式的加载流程：构建渲染请求、
-// 生成加载签名（去重）、通过 JS 桥接应用分页样式和高亮、
-// 处理重复请求跳过和已有文档复用等优化逻辑。
 
 import UIKit
 import WebKit
 
 extension RDEPUBWebView {
-    /// 便捷方法：加载重排模式的指定页面
+
     public func loadPage(
         parser: RDEPUBParser,
         spineIndex: Int,
@@ -46,7 +41,6 @@ extension RDEPUBWebView {
         load(publication: parser.makePublication(), request: request)
     }
 
-    /// 处理重排模式加载：设置状态、去重检查、加载资源或直接应用样式
     func handleReflowableLoad(
         publication: RDEPUBPublication,
         request: RDEPUBReflowableRenderRequest,
@@ -91,7 +85,6 @@ extension RDEPUBWebView {
         webView.load(URLRequest(url: requestURL))
     }
 
-    /// 生成重排模式加载签名（包含所有渲染参数的哈希，用于去重）
     func reflowableLoadSignature(publicationKey: String, request: RDEPUBReflowableRenderRequest) -> String {
         let targetSignature = [
             request.targetLocation?.href ?? "",
@@ -139,7 +132,6 @@ 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,3 @@
-// RDEPUBWebView+Search.swift
-// RDEPUBWebView 的搜索高亮扩展
-// 从当前渲染请求中提取搜索展示信息，生成搜索高亮脚本并注入到 WebView 中执行。
 
 import UIKit
 import WebKit
@@ -14,7 +11,6 @@ extension RDEPUBWebView {
         UIColor(red: 0.14, green: 0.42, blue: 0.95, alpha: 0.34)
     }
 
-    /// 如果当前渲染请求包含搜索信息，注入搜索高亮脚本到 WebView
     func applySearchDecorationsIfNeeded(completion: (() -> Void)? = nil) {
         guard let webView else {
             completion?()

Sources/RDReaderView/EPUBCore/RDEPUBWebView.swift

@@ -1,39 +1,30 @@
-// 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 {
@@ -64,63 +55,60 @@ 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 onDecorationsResolved: (([RDEPUBTextOverlayDecoration]) -> 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) {
@@ -141,7 +129,6 @@ public final class RDEPUBWebView: UIView {
         webView?.frame = bounds
     }
 
-    /// 重置所有状态并销毁 WebView
     public func reset() {
         delegate = nil
         onRendered = nil
@@ -167,7 +154,6 @@ public final class RDEPUBWebView: UIView {
         teardownWebView()
     }
 
-    /// 加载渲染请求：配置 WebView、生成签名、分发到固定版式或重排处理
     public func load(publication: RDEPUBPublication, request: RDEPUBRenderRequest) {
         configureWebViewIfNeeded(publication: publication)
         guard let webView else { return }
@@ -194,7 +180,6 @@ public final class RDEPUBWebView: UIView {
         }
     }
 
-    /// 生成页面加载签名
     func pageLoadSignature(
         publicationKey: String,
         request: RDEPUBRenderRequest
@@ -207,7 +192,6 @@ public final class RDEPUBWebView: UIView {
         }
     }
 
-    /// 标记渲染完成：通知委托和回调，延迟 100ms 确保布局稳定
     func rendered() {
         guard !didRenderCurrentRequest else { return }
         didRenderCurrentRequest = true

Sources/RDReaderView/EPUBCore/RDEPUBWebViewDebug.swift

@@ -1,15 +1,9 @@
-// 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
@@ -21,8 +15,6 @@ enum RDEPUBWebViewDebug {
 #endif
     }()
 
-    /// 详细日志模式是否启用（默认关闭，可通过 UserDefaults "RDEPUBWebViewVerboseEnabled" 开启）
-    /// 开启后 logMessage 将输出完整消息体，关闭时仅输出消息名、字段名和文本长度
     static var isVerboseEnabled: Bool = {
         if let configured = UserDefaults.standard.object(forKey: "RDEPUBWebViewVerboseEnabled") as? Bool {
             return configured
@@ -30,8 +22,6 @@ enum RDEPUBWebViewDebug {
         return false
     }()
 
-    /// 是否允许开启 inspectable。
-    /// 默认关闭，仅在阅读器配置显式允许或 UserDefaults 覆盖时开启。
     static var isInspectableEnabled: Bool = {
         if let configured = UserDefaults.standard.object(forKey: "RDEPUBInspectableWebViewsEnabled") as? Bool {
             return configured
@@ -39,25 +29,21 @@ enum RDEPUBWebViewDebug {
         return false
     }()
 
-    /// 将阅读器配置同步到调试策略，保证默认安全策略由配置显式控制。
     static func applyDebugPolicy(inspectableEnabled: Bool, verboseLoggingEnabled: Bool) {
         isInspectableEnabled = inspectableEnabled
         isVerboseEnabled = verboseLoggingEnabled
     }
 
-    /// 获取 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)
@@ -69,13 +55,11 @@ 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 消息接收日志（默认仅输出字段名和文本长度，verbose 模式输出完整消息体）
     static func logMessage(_ scope: String, webView: WKWebView?, name: String, body: Any) {
         guard isEnabled else { return }
         if isVerboseEnabled {
@@ -97,7 +81,6 @@ enum RDEPUBWebViewDebug {
         }
     }
 
-    /// 输出 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)
@@ -109,7 +92,6 @@ 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-fixed-layout.html

@@ -89,6 +89,60 @@
         }
       }
 
+      function parseCssPixelValue(value) {
+        if (!value) { return 0; }
+        var match = String(value).match(/([0-9]+(?:\.[0-9]+)?)px?/);
+        return match ? Number.parseFloat(match[1]) : 0;
+      }
+
+      function sizeFromElement(element) {
+        if (!element) { return null; }
+        var width = parseCssPixelValue(element.style && element.style.width);
+        var height = parseCssPixelValue(element.style && element.style.height);
+        if (!width || !height) {
+          width = parseCssPixelValue(element.getAttribute && element.getAttribute('width'));
+          height = parseCssPixelValue(element.getAttribute && element.getAttribute('height'));
+        }
+        if (!width || !height) {
+          var rect = element.getBoundingClientRect ? element.getBoundingClientRect() : null;
+          if (rect) {
+            width = width || rect.width;
+            height = height || rect.height;
+          }
+        }
+        if (width > 1 && height > 1) {
+          return { width: width, height: height };
+        }
+        return null;
+      }
+
+      function parsePageSizeFromDocumentBox(iframe) {
+        try {
+          var doc = iframe.contentWindow.document;
+          return sizeFromElement(doc.body) ||
+            sizeFromElement(doc.documentElement) ||
+            sizeFromElement(doc.querySelector('[id$="_hype_container"]')) ||
+            sizeFromElement(doc.querySelector('iframe')) ||
+            null;
+        } catch (error) {
+          return null;
+        }
+      }
+
+      function parsePageSizeFromNestedFrame(iframe) {
+        try {
+          var nestedFrame = iframe.contentWindow.document.querySelector('iframe');
+          if (!nestedFrame || !nestedFrame.contentWindow || !nestedFrame.contentWindow.document) {
+            return null;
+          }
+          return parsePageSizeFromViewportMetaTag(nestedFrame) ||
+            parsePageSizeFromDocumentBox(nestedFrame) ||
+            parsePageSizeFromEmbeddedImage(nestedFrame);
+        } catch (error) {
+          return null;
+        }
+      }
+
       function parsePageSizeFromEmbeddedImage(iframe) {
         try {
           var img = iframe.contentWindow.document.querySelector('img');
@@ -176,9 +230,14 @@
         function onLoad() {
           iframe.__ssPageSize =
             parsePageSizeFromViewportMetaTag(iframe) ||
+            parsePageSizeFromDocumentBox(iframe) ||
+            parsePageSizeFromNestedFrame(iframe) ||
             parsePageSizeFromEmbeddedImage(iframe) ||
             pageViewportSize(iframe);
           layoutPage(iframe);
+          window.setTimeout(function() {
+            layoutPage(iframe);
+          }, 250);
           finalizeLoad();
         }
 
@@ -204,4 +263,4 @@
     })();
   </script>
 </body>
-</html>
+</html>