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

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

Sources/RDReaderView/EPUBTextRendering/BuildPipeline/RDEPUBBuildDiagnosticsReporter.swift

@@ -1,16 +1,18 @@
 import Foundation
 
-/// Builds diagnostics and human-readable summaries for a text book build.
 struct RDEPUBBuildDiagnosticsReporter {
+
     func phase7SemanticSummary(
         title: String?,
         diagnostics: [RDEPUBTextChapterPaginationDiagnostic]
     ) -> String? {
+
         guard !diagnostics.isEmpty else { return nil }
 
         let blockKinds = uniqueValues(from: diagnostics.flatMap(\.blockKinds))
         let semanticHints = uniqueValues(from: diagnostics.flatMap(\.semanticHints))
         let attachmentPlacements = uniqueValues(from: diagnostics.flatMap(\.attachmentPlacements))
+
         let note = diagnostics
             .flatMap(\.sampleNotes)
             .first(where: { $0.contains("semantic") || $0.contains("attachment") || $0.contains("block kinds") })
@@ -22,6 +24,7 @@ struct RDEPUBBuildDiagnosticsReporter {
             semanticHints.isEmpty ? nil : "hints [\(semanticHints.map(\.rawValue).joined(separator: ","))]",
             attachmentPlacements.isEmpty ? nil : "placements [\(attachmentPlacements.map(\.rawValue).joined(separator: ","))]"
         ].compactMap { $0 }
+
         if let note {
             parts.append(note)
         }
@@ -38,11 +41,14 @@ struct RDEPUBBuildDiagnosticsReporter {
             title: title,
             pageCount: pages.count,
             breakReasons: pages.map(\.metadata.breakReason),
+
             attachmentPageCount: pages.filter { !$0.metadata.attachmentKinds.isEmpty }.count,
+
             blockAdjustedPageCount: pages.filter { $0.metadata.breakReason == .blockBoundary || $0.metadata.breakReason == .attachmentBoundary }.count,
             blockKinds: uniqueValues(from: pages.flatMap(\.metadata.blockKinds)),
             semanticHints: uniqueValues(from: pages.flatMap(\.metadata.semanticHints)),
             attachmentPlacements: uniqueValues(from: pages.flatMap(\.metadata.attachmentPlacements)),
+
             sampleNotes: Array(pages.flatMap(\.metadata.diagnostics).prefix(4))
         )
     }

Sources/RDReaderView/EPUBTextRendering/BuildPipeline/RDEPUBChapterTailNormalizer.swift

@@ -1,12 +1,13 @@
 import Foundation
 
-/// Normalizes suspicious trailing or whitespace-only page frames after pagination.
 struct RDEPUBChapterTailNormalizer {
+
     func normalize(
         _ frames: [RDEPUBTextLayoutFrame],
         content: NSAttributedString,
         href: String
     ) -> [RDEPUBTextLayoutFrame] {
+
         guard frames.count > 1 else { return frames }
 
         var normalized = frames
@@ -16,10 +17,12 @@ struct RDEPUBChapterTailNormalizer {
         for frame in normalized {
             if shouldDropWhitespaceOnlyFrame(frame, in: content) {
                 let note = "normalized: dropped whitespace-only intermediate page \(NSStringFromRange(frame.contentRange))"
+
                 if var previous = compacted.popLast() {
                     previous.diagnostics.append(note)
                     compacted.append(previous)
                 } else {
+
                     #if DEBUG
                     print("[EPUB][Pagination] href=\(href) dropped leading/intermediate whitespace frame \(NSStringFromRange(frame.contentRange))")
                     #endif
@@ -73,6 +76,7 @@ struct RDEPUBChapterTailNormalizer {
         previousFrame: RDEPUBTextLayoutFrame,
         in content: NSAttributedString
     ) -> Bool {
+
         guard trailingFrame.contentRange.length > 0,
               NSMaxRange(previousFrame.contentRange) == trailingFrame.contentRange.location else {
             return false
@@ -80,6 +84,7 @@ struct RDEPUBChapterTailNormalizer {
 
         let visibleCount = visibleCharacterCount(in: content, range: trailingFrame.contentRange)
         let trailingAttachmentCount = attachmentCount(in: content, range: trailingFrame.contentRange)
+
         guard visibleCount <= 2,
               trailingFrame.contentRange.length <= 2,
               visibleCount > 0 || trailingAttachmentCount > 0 else {
@@ -94,6 +99,7 @@ struct RDEPUBChapterTailNormalizer {
         _ previousFrame: RDEPUBTextLayoutFrame,
         with trailingFrame: RDEPUBTextLayoutFrame
     ) -> RDEPUBTextLayoutFrame {
+
         let mergedRange = NSRange(
             location: previousFrame.contentRange.location,
             length: NSMaxRange(trailingFrame.contentRange) - previousFrame.contentRange.location
@@ -109,6 +115,7 @@ struct RDEPUBChapterTailNormalizer {
             semanticHints: uniqueValues(from: previousFrame.semanticHints + trailingFrame.semanticHints),
             attachmentPlacements: uniqueValues(from: previousFrame.attachmentPlacements + trailingFrame.attachmentPlacements),
             trailingFragmentID: trailingFrame.trailingFragmentID ?? previousFrame.trailingFragmentID,
+
             diagnostics: previousFrame.diagnostics
                 + trailingFrame.diagnostics
                 + ["normalized: merged short trailing page \(NSStringFromRange(trailingFrame.contentRange)) into previous page"]
@@ -121,6 +128,7 @@ struct RDEPUBChapterTailNormalizer {
     ) -> Int {
         guard range.length > 0 else { return 0 }
         let string = content.attributedSubstring(from: range).string
+
         let filteredScalars = string.unicodeScalars.filter { scalar in
             !CharacterSet.whitespacesAndNewlines.contains(scalar)
                 && !CharacterSet.controlCharacters.contains(scalar)

Sources/RDReaderView/EPUBTextRendering/BuildPipeline/RDEPUBPaginationCacheCoordinator.swift

@@ -1,8 +1,9 @@
 import UIKit
 
-/// Keeps pagination cache key generation and cache IO in one BuildPipeline role.
 struct RDEPUBPaginationCacheCoordinator {
+
     private let cache: RDEPUBTextBookCache?
+
     private let layoutConfig: RDEPUBTextLayoutConfig
 
     init(cache: RDEPUBTextBookCache?, layoutConfig: RDEPUBTextLayoutConfig) {
@@ -32,11 +33,13 @@ struct RDEPUBPaginationCacheCoordinator {
 
     func save(chapters: [RDEPUBTextChapter], key: String?) {
         guard let key else { return }
+
         let paginationCache = chapters.map { chapter in
             RDEPUBTextChapterPaginationCache(
                 href: chapter.href,
                 pageRanges: chapter.pages.map(\.contentRange),
                 breakReasons: chapter.pages.map(\.metadata.breakReason),
+
                 semanticHints: Array(Set(chapter.pages.flatMap(\.metadata.semanticHints)))
             )
         }

Sources/RDReaderView/EPUBTextRendering/BuildPipeline/RDEPUBTextBookBuilder.swift

@@ -1,6 +1,5 @@
 import UIKit
 
-/// EPUB 文本书籍构建器，负责将 EPUB publication 渲染、分页并组装为 `RDEPUBTextBook`。
 public final class RDEPUBTextBookBuilder {
     private let renderer: RDEPUBTextRenderer
     private let cache: RDEPUBTextBookCache?
@@ -12,20 +11,14 @@ public final class RDEPUBTextBookBuilder {
     private let cacheCoordinator: RDEPUBPaginationCacheCoordinator
     private let diagnosticsReporter: RDEPUBBuildDiagnosticsReporter
 
-    /// 最后一次构建的资源引用诊断（样式表、图片等）
     public private(set) var lastBuildResourceDiagnostics: [RDEPUBTextResourceReferenceDiagnostic] = []
-    /// 最后一次构建的分页诊断（每章一页的分页原因、附件统计等）
+
     public private(set) var lastBuildPaginationDiagnostics: [RDEPUBTextChapterPaginationDiagnostic] = []
-    /// 最后一次构建的性能采样数据
+
     public private(set) var lastBuildPerformanceSamples: [RDEPUBTextPerformanceSample] = []
-    /// 最后一次构建的缓存命中/未命中统计
+
     public private(set) var lastBuildCacheStats: (hits: Int, misses: Int) = (0, 0)
 
-    /// 创建书籍构建器。
-    /// - Parameters:
-    ///   - renderer: 文本渲染器
-    ///   - cache: 分页缓存（可选）
-    ///   - layoutConfig: 页面布局配置
     public init(
         renderer: RDEPUBTextRenderer,
         cache: RDEPUBTextBookCache? = nil,
@@ -42,7 +35,6 @@ public final class RDEPUBTextBookBuilder {
         self.diagnosticsReporter = RDEPUBBuildDiagnosticsReporter()
     }
 
-    /// 默认构造器，使用 DTCoreText 渲染器
     public convenience init() {
         self.init(renderer: RDEPUBDTCoreTextRenderer())
     }
@@ -51,7 +43,6 @@ public final class RDEPUBTextBookBuilder {
         ProcessInfo.processInfo.arguments.contains("--demo-pagination-debug")
     }
 
-    /// 生成最近一次构建的语义摘要，用于 Phase 7 质量检测日志
     public func phase7SemanticSummary(title: String? = nil) -> String? {
         diagnosticsReporter.phase7SemanticSummary(
             title: title,
@@ -59,16 +50,6 @@ public final class RDEPUBTextBookBuilder {
         )
     }
 
-    /// 核心构建方法：从 EPUB publication 构建分页书籍。
-    ///
-    /// 流程：
-    /// 1. 生成缓存键，尝试加载分页缓存
-    /// 2. 遍历 spine 中的线性 HTML 章节
-    /// 3. 渲染每章 HTML → NSAttributedString
-    /// 4. 跳过空白的封面/扉页章节
-    /// 5. 分页：缓存命中则使用缓存的页范围，否则调用 CoreText 分页引擎
-    /// 6. 尾页规范化：丢弃纯空白尾页、合并过短尾页
-    /// 7. 构建 RDEPUBTextBook 并保存分页缓存
     public func build(
         parser: RDEPUBParser,
         publication: RDEPUBPublication,
@@ -88,7 +69,6 @@ public final class RDEPUBTextBookBuilder {
 
         let buildStart = CFAbsoluteTimeGetCurrent()
 
-        // 缓存查询 — WXRead 模式：只加载每章的页范围，不缓存富文本
         let bookID = publication.metadata.identifier ?? publication.metadata.title
         let cacheKey = cacheCoordinator.cacheKey(bookID: bookID, pageSize: pageSize, style: style)
         let cachedPagination = cacheCoordinator.load(key: cacheKey)
@@ -134,7 +114,6 @@ public final class RDEPUBTextBookBuilder {
 
         sampler.totalBuildDuration = CFAbsoluteTimeGetCurrent() - buildStart
 
-        // 保存分页缓存（只缓存页范围和分页原因，不缓存富文本）
         cacheCoordinator.save(chapters: chapters, key: cacheKey)
 
         #if DEBUG
@@ -145,7 +124,6 @@ public final class RDEPUBTextBookBuilder {
         return book
     }
 
-    /// 构建指定 spine 章节，用于大书快速首屏和后台增量补齐。
     public func buildChapter(
         parser: RDEPUBParser,
         publication: RDEPUBPublication,
@@ -192,6 +170,7 @@ public final class RDEPUBTextBookBuilder {
         let request = RDEPUBTextTypesetterPipeline().makeRequest(
             from: RDEPUBTypesettingInput(
                 href: item.href,
+                spineIndex: spineIndex,
                 title: chapterTitle,
                 rawHTML: rawHTML,
                 baseURL: parser.fileURL(forRelativePath: item.href)?.deletingLastPathComponent(),
@@ -281,11 +260,13 @@ public final class RDEPUBTextBookBuilder {
         }
 
         let paginateDuration = CFAbsoluteTimeGetCurrent() - paginateStart
+
         let normalizedFrames = tailNormalizer.normalize(
             layoutFrames,
             content: content,
             href: item.href
         )
+
         let effectiveFrames = normalizedFrames.isEmpty && content.length > 0
             ? [
                 RDEPUBTextLayoutFrame(
@@ -339,6 +320,12 @@ public final class RDEPUBTextBookBuilder {
             title: chapterTitle,
             attributedContent: chapterAttributedContent,
             fragmentOffsets: rendered.fragmentOffsets,
+            cfiMap: RDEPUBCFITextNodeMapBuilder.makeMap(
+                href: item.href,
+                rawHTML: rawHTML,
+                chapterText: chapterAttributedContent.string,
+                fragmentOffsets: rendered.fragmentOffsets
+            ),
             pageBreakReasons: pages.map(\.metadata.breakReason),
             pages: pages
         )
@@ -365,9 +352,6 @@ public final class RDEPUBTextBookBuilder {
         )
     }
 
-    // MARK: - 章节标题解析
-
-    /// 从目录表中查找章节标题，找不到则回退到 spine item 的 title 或 href
     private func resolvedChapterTitle(for item: RDEPUBSpineItem, toc: [EPUBTableOfContentsItem]) -> String {
         if let title = flattenedTOCItems(from: toc).first(where: { tocItem in
             tocItem.href.components(separatedBy: "#").first == item.href
@@ -378,16 +362,12 @@ public final class RDEPUBTextBookBuilder {
         return trimmedTitle.isEmpty ? item.href : trimmedTitle
     }
 
-    /// 递归展开嵌套目录为扁平列表
     private func flattenedTOCItems(from items: [EPUBTableOfContentsItem]) -> [EPUBTableOfContentsItem] {
         items.flatMap { item in
             [item] + flattenedTOCItems(from: item.children)
         }
     }
 
-    // MARK: - 章节过滤
-
-    /// 判断是否应跳过该章节（空白的封面/扉页，无文本且无附件）
     private func shouldSkipChapter(item: RDEPUBSpineItem, content: NSAttributedString, text: String) -> Bool {
         let lowercasedHref = item.href.lowercased()
         var hasAttachment = false
@@ -404,9 +384,6 @@ public final class RDEPUBTextBookBuilder {
         return false
     }
 
-    // MARK: - 附件统计
-
-    /// 统计富文本中的附件数量
     private func attachmentCount(in content: NSAttributedString) -> Int {
         guard content.length > 0 else { return 0 }
         var count = 0
@@ -418,7 +395,6 @@ public final class RDEPUBTextBookBuilder {
         return count
     }
 
-    /// 获取富文本中所有附件的 NSRange 列表
     private func attachmentRanges(in content: NSAttributedString) -> [NSRange] {
         guard content.length > 0 else { return [] }
         var ranges: [NSRange] = []
@@ -430,9 +406,6 @@ public final class RDEPUBTextBookBuilder {
         return ranges
     }
 
-    // MARK: - 封面章节检测
-
-    /// 判断是否为纯图片封面章节（href 包含 cover 且有附件但几乎无文本）
     private func isAttachmentOnlyCoverChapter(
         item: RDEPUBSpineItem,
         content: NSAttributedString,
@@ -445,6 +418,7 @@ public final class RDEPUBTextBookBuilder {
     }
 
     private func debugPreview(for content: NSAttributedString, limit: Int) -> String {
+
         let collapsed = content.string
             .replacingOccurrences(of: "\n", with: " ")
             .replacingOccurrences(of: "\r", with: " ")

Sources/RDReaderView/EPUBTextRendering/BuildPipeline/RDEPUBTextBookCache.swift

@@ -1,19 +1,14 @@
 import Foundation
 import CryptoKit
 
-// MARK: - 分页缓存数据模型（WXRead 模式：只缓存页范围，不缓存富文本）
-
-/// 单个章节的分页元数据缓存，用于磁盘持久化。
-///
-/// 对标 WXRead 的 WRChapterPageCount 缓存策略：只存储每页的 NSRange + 分页原因，
-/// 不缓存完整的 NSAttributedString。缓存命中时重新渲染 HTML，但跳过 CoreText 分页步骤。
 public struct RDEPUBTextChapterPaginationCache: Equatable {
-    /// 章节文件相对路径
+
     public var href: String
-    /// 每页在章节富文本中的字符范围
+
     public var pageRanges: [NSRange]
-    /// 每页的分页原因（语义边界、帧限制等）
+
     public var breakReasons: [RDEPUBTextPageBreakReason]
+
     public var semanticHints: [RDEPUBTextSemanticHint]
 
     public init(
@@ -29,11 +24,8 @@ public struct RDEPUBTextChapterPaginationCache: Equatable {
     }
 }
 
-// MARK: - NSCoding 归档层（只使用字符串和整数类型）
-
-/// 整本书的分页缓存归档，用于 NSKeyedArchiver 序列化。
-/// 包含所有章节的分页归档数据。
 final class PaginationCacheArchive: NSObject, NSSecureCoding {
+
     static var supportsSecureCoding: Bool { true }
 
     let chapters: [ChapterPaginationArchive]
@@ -52,20 +44,20 @@ final class PaginationCacheArchive: NSObject, NSSecureCoding {
     }
 }
 
-/// 单个章节的分页归档，将 NSRange 拆分为 location/length 数组以便 NSSecureCoding 编码。
 final class ChapterPaginationArchive: NSObject, NSSecureCoding {
+
     static var supportsSecureCoding: Bool { true }
+
     let href: String
-    /// 页范围的起始位置数组（与 rangeLengths 一一对应）
+
     let rangeLocations: [NSNumber]
-    /// 页范围的长度数组
+
     let rangeLengths: [NSNumber]
-    /// 分页原因的原始字符串数组
+
     let breakReasons: [String]
-    /// 语义提示的原始字符串数组
+
     let semanticHints: [String]
 
-    /// 从缓存模型构建归档对象
     init(from cache: RDEPUBTextChapterPaginationCache) {
         self.href = cache.href
         self.rangeLocations = cache.pageRanges.map { NSNumber(value: $0.location) }
@@ -97,7 +89,6 @@ final class ChapterPaginationArchive: NSObject, NSSecureCoding {
         self.semanticHints = semanticHints
     }
 
-    /// 将归档数据转换回缓存模型
     func toCache() -> RDEPUBTextChapterPaginationCache {
         let pageRanges = zip(rangeLocations, rangeLengths).map { loc, len in
             NSRange(location: loc.intValue, length: len.intValue)
@@ -111,28 +102,14 @@ final class ChapterPaginationArchive: NSObject, NSSecureCoding {
     }
 }
 
-// MARK: - 分页缓存管理器
-
-/// 磁盘持久化的分页缓存层，对标 WXRead 的 WRChapterPageCount 缓存模式。
-///
-/// 缓存策略：
-/// - 缓存键 = SHA256(书籍ID + 字号 + 行距 + 内边距 + 页面尺寸 + schema版本)
-/// - 缓存值 = 每章的页 NSRange 列表 + 分页原因（NSKeyedArchiver 序列化）
-/// - 富文本不缓存：缓存命中时重新渲染 HTML，但跳过 CoreText 分页步骤
-/// - 线程安全：所有读写操作通过 serial DispatchQueue 串行执行
 public final class RDEPUBTextBookCache {
 
-    /// 缓存模式版本号，变更时旧缓存自动失效
-    // 分页算法调整后需要提升版本，避免继续复用旧页范围缓存。
     public var schemaVersion: Int = 6
 
-    /// 串行队列，保证缓存读写的线程安全
     private let queue = DispatchQueue(label: "com.rdreader.textbookcache", qos: .utility)
-    /// 缓存文件目录
+
     private let cacheDirectory: URL
 
-    /// 初始化缓存管理器，自动创建缓存目录
-    /// - Parameter subdirectory: Caches 目录下的子目录名
     public init(subdirectory: String = "RDEPUBTextBookCache") {
         let baseURL = FileManager.default.urls(for: .cachesDirectory, in: .userDomainMask).first?
             .appendingPathComponent(subdirectory, isDirectory: true)
@@ -141,13 +118,6 @@ public final class RDEPUBTextBookCache {
         try? FileManager.default.createDirectory(at: cacheDirectory, withIntermediateDirectories: true)
     }
 
-    // MARK: - 缓存键生成
-    // 对标 WRChapterPageCount.currentCacheKeyWithBookId：
-    // 编码 bookID + fontSize + lineHeightMultiple + contentInsets + pageSize
-
-    /// 生成缓存文件名（SHA256 哈希 + ".cache" 后缀）。
-    ///
-    /// 任意布局参数变更都会导致缓存键不同，从而自动失效。
     public func cacheKey(
         bookID: String,
         fontSize: CGFloat,
@@ -162,10 +132,6 @@ public final class RDEPUBTextBookCache {
         return hex + ".cache"
     }
 
-    // MARK: - 加载/保存（只缓存分页元数据）
-
-    /// 从磁盘加载缓存的分页元数据，返回以章节 href 为键的字典。
-    /// 缓存未命中或反序列化失败时返回 nil。
     public func load(key: String) -> [String: RDEPUBTextChapterPaginationCache]? {
         queue.sync {
             let fileURL = cacheDirectory.appendingPathComponent(key)
@@ -203,7 +169,6 @@ public final class RDEPUBTextBookCache {
         }
     }
 
-    /// 将分页元数据保存到磁盘（原子写入，防止损坏）
     public func save(_ chapters: [RDEPUBTextChapterPaginationCache], key: String) {
         queue.sync {
             let fileURL = cacheDirectory.appendingPathComponent(key)
@@ -223,9 +188,6 @@ public final class RDEPUBTextBookCache {
         }
     }
 
-    // MARK: - 缓存失效
-
-    /// 清除所有缓存文件
     public func invalidateAll() {
         queue.sync {
             let fileManager = FileManager.default

Sources/RDReaderView/EPUBTextRendering/BuildPipeline/RDEPUBTextBookModels.swift

@@ -1,93 +1,99 @@
 import UIKit
 
-// MARK: - 章节分页诊断数据
-
-/// 单个章节的分页诊断信息，用于调试和质量检测。
-/// 记录页数、分页原因、附件/块级元素统计等。
 public struct RDEPUBTextChapterPaginationDiagnostic: Equatable {
+
     public var href: String
+
     public var title: String
+
     public var pageCount: Int
-    /// 每页的分页原因列表
+
     public var breakReasons: [RDEPUBTextPageBreakReason]
-    /// 包含附件的页数
+
     public var attachmentPageCount: Int
-    /// 因块级/附件边界调整而分页的页数
+
     public var blockAdjustedPageCount: Int
+
     public var blockKinds: [RDEPUBTextBlockKind]
+
     public var semanticHints: [RDEPUBTextSemanticHint]
+
     public var attachmentPlacements: [RDEPUBTextAttachmentPlacement]
-    /// 采样诊断日志（最多 4 条）
+
     public var sampleNotes: [String]
 }
 
-// MARK: - 章节构建结果
-
-/// 单章构建结果，用于大书快速进入阅读器和后台增量补齐。
 public struct RDEPUBTextChapterBuildResult {
+
     public var chapter: RDEPUBTextChapter
+
     public var resourceDiagnostics: [RDEPUBTextResourceReferenceDiagnostic]
+
     public var paginationDiagnostic: RDEPUBTextChapterPaginationDiagnostic
+
     public var performanceSample: RDEPUBTextPerformanceSample
+
     public var cacheHit: Bool
 }
 
-// MARK: - 页面数据模型
-
-/// 分页后的单页数据，包含全书绝对页码、所属章节、内容范围等。
-///
-/// 每个 `RDEPUBTextPage` 由 `RDEPUBTextLayoutFrame` 生成，
-/// `contentRange` 标记了该页在章节富文本中的字符范围。
 public struct RDEPUBTextPage: Equatable {
-    /// 全书绝对页码（从 0 开始）
+
     public var absolutePageIndex: Int
+
     public var chapterIndex: Int
+
     public var spineIndex: Int
+
     public var href: String
+
     public var chapterTitle: String
-    /// 该页在所属章节中的相对页码（从 0 开始）
+
     public var pageIndexInChapter: Int
+
     public var totalPagesInChapter: Int
-    /// 所属章节的完整富文本内容（用于跨页查询）
+
     public var chapterContent: NSAttributedString
-    /// 该页的富文本片段
+
     public var content: NSAttributedString
-    /// 该页在章节富文本中的范围
+
     public var contentRange: NSRange
+
     public var pageStartOffset: Int
+
     public var pageEndOffset: Int
-    /// 页的元数据（分页原因、附件、语义标记等）
+
     public var metadata: RDEPUBTextPageMetadata
 }
 
-// MARK: - 章节数据模型
-
-/// 渲染并分页后的单个章节，包含完整富文本和分页结果。
 public struct RDEPUBTextChapter: Equatable {
+
     public var chapterIndex: Int
+
     public var spineIndex: Int
+
     public var href: String
+
     public var title: String
-    /// 章节完整富文本内容
+
     public var attributedContent: NSAttributedString
-    /// fragment ID → 字符偏移量映射（用于锚点定位）
+
     public var fragmentOffsets: [String: Int]
+
+    public var cfiMap: RDEPUBCFIMap?
+
     public var pageBreakReasons: [RDEPUBTextPageBreakReason]
+
     public var pages: [RDEPUBTextPage]
 }
 
-// MARK: - 分页书籍模型
-
-/// 整本 EPUB 的分页书籍模型，包含所有章节、页面和全局索引表。
-///
-/// 这是 EPUBTextRendering 层的最终产物，由 `RDEPUBTextBookBuilder.build()` 生成。
-/// 通过 `chapterData(for:)` 或 `chapterData(atChapterIndex:)` 获取 `RDEPUBChapterData` 进行查询。
 public struct RDEPUBTextBook {
+
     public var chapters: [RDEPUBTextChapter]
+
     public var pages: [RDEPUBTextPage]
-    /// 全局索引表：fileIndex/row/column → 绝对字符偏移量
+
     public let indexTable: RDEPUBTextIndexTable
-    /// 对标 WXRead 的位置转换器（文件位置 <-> 全书字符位置 <-> 页码）
+
     public var positionConverter: RDEPUBTextPositionConverter {
         RDEPUBTextPositionConverter(book: self)
     }
@@ -102,31 +108,26 @@ public struct RDEPUBTextBook {
         lhs.chapters == rhs.chapters && lhs.pages == rhs.pages
     }
 
-    /// 按 href 获取章节的数据访问层（包含索引表）
     public func chapterData(for href: String) -> RDEPUBChapterData? {
         guard let chapter = chapters.first(where: { $0.href == href }) else { return nil }
         return RDEPUBChapterData(chapter: chapter, indexTable: indexTable)
     }
 
-    /// 按 spine 索引获取章节的数据访问层。
     public func chapterData(forSpineIndex spineIndex: Int) -> RDEPUBChapterData? {
         guard let chapter = chapters.first(where: { $0.spineIndex == spineIndex }) else { return nil }
         return RDEPUBChapterData(chapter: chapter, indexTable: indexTable)
     }
 
-    /// 按章节序号获取章节的数据访问层
     public func chapterData(atChapterIndex index: Int) -> RDEPUBChapterData? {
         guard chapters.indices.contains(index) else { return nil }
         return RDEPUBChapterData(chapter: chapters[index], indexTable: indexTable)
     }
 
-    /// 按绝对页码（从 1 开始）获取章节的数据访问层。
     public func chapterData(forPageNumber pageNumber: Int) -> RDEPUBChapterData? {
         guard let page = page(at: pageNumber) else { return nil }
         return chapterData(forSpineIndex: page.spineIndex)
     }
 
-    /// 根据持久化位置解析所属章节的数据访问层。
     public func chapterData(
         for location: RDEPUBLocation,
         resolver: RDEPUBResourceResolver,
@@ -138,7 +139,6 @@ public struct RDEPUBTextBook {
         return chapterData(for: normalizedLocation.href)
     }
 
-    /// 全书章节信息快照；对标 WXRead 由章节模型直接提供章节元数据。
     public var chapterInfos: [EPUBChapterInfo] {
         chapters.map { chapter in
             EPUBChapterInfo(
@@ -149,7 +149,6 @@ public struct RDEPUBTextBook {
         }
     }
 
-    /// 按页码（从 1 开始）获取对应页面
     public func page(at pageNumber: Int) -> RDEPUBTextPage? {
         guard pageNumber > 0, pages.indices.contains(pageNumber - 1) else {
             return nil
@@ -157,12 +156,6 @@ public struct RDEPUBTextBook {
         return pages[pageNumber - 1]
     }
 
-    /// 根据持久化位置计算对应页码（从 1 开始）。
-    ///
-    /// 解析优先级：
-    /// 1. rangeAnchor 锚点定位
-    /// 2. fragment 片段 ID
-    /// 3. navigationProgression 进度百分比回退
     public func pageNumber(for location: RDEPUBLocation, resolver: RDEPUBResourceResolver, bookIdentifier: String?) -> Int? {
         guard let normalizedLocation = resolver.normalizedLocation(location, bookIdentifier: bookIdentifier),
               let chapterData = chapterData(for: normalizedLocation.href) else {
@@ -182,7 +175,6 @@ public struct RDEPUBTextBook {
         return chapterData.pageNumber(for: normalizedLocation)
     }
 
-    /// 根据页码生成持久化位置（RDEPUBLocation），包含起止锚点
     public func location(forPageNumber pageNumber: Int, bookIdentifier: String?) -> RDEPUBLocation? {
         guard let chapterData = chapterData(forPageNumber: pageNumber),
               let page = page(at: pageNumber) else {

Sources/RDReaderView/EPUBTextRendering/BuildPipeline/RDEPUBTextBuildPipelineInterfaces.swift

@@ -1,10 +1,8 @@
-// RDEPUBTextBuildPipelineInterfaces.swift
-// EPUB 文本构建管线接口定义，包括全书构建、章节渲染与分页管线。
 
 import UIKit
 
-/// EPUB 全书文本构建接口，将 EPUB 出版物解析为可分页的文本书籍。
 protocol RDEPUBTextBookBuilding {
+
     func build(
         parser: RDEPUBParser,
         publication: RDEPUBPublication,
@@ -13,41 +11,25 @@ protocol RDEPUBTextBookBuilding {
     ) throws -> RDEPUBTextBook
 }
 
-/// 章节渲染管线，将章节渲染请求委托给底层文本渲染器。
 struct RDEPUBChapterRenderPipeline {
     private let renderer: RDEPUBTextRenderer
 
-    /// 初始化渲染管线。
-    /// - Parameter renderer: 文本渲染器实例
     init(renderer: RDEPUBTextRenderer) {
         self.renderer = renderer
     }
 
-    /// 渲染单个章节，返回渲染后的富文本内容。
-    /// - Parameter request: 章节渲染请求
-    /// - Returns: 渲染完成的章节内容
     func render(_ request: RDEPUBTextChapterRenderRequest) throws -> RDEPUBRenderedChapterContent {
         try renderer.renderChapter(request: request)
     }
 }
 
-/// 章节分页管线，将渲染后的富文本按页面尺寸拆分为文本帧数组。
 struct RDEPUBChapterPaginationPipeline {
     private let frameFactory: RDEPUBPageFrameBuilding
 
-    /// 初始化分页管线。
-    /// - Parameter frameFactory: 页面帧工厂，默认使用 CoreText 实现
     init(frameFactory: RDEPUBPageFrameBuilding = RDEPUBCoreTextPageFrameFactory()) {
         self.frameFactory = frameFactory
     }
 
-    /// 将富文本内容分页，返回页面帧数组。
-    /// - Parameters:
-    ///   - content: 待分页的富文本
-    ///   - pageSize: 页面尺寸
-    ///   - config: 排版配置
-    ///   - fragmentOffsets: fragment 锚点偏移映射
-    /// - Returns: 页面帧数组
     func frames(
         for content: NSAttributedString,
         pageSize: CGSize,

Sources/RDReaderView/EPUBTextRendering/BuildPipeline/RDEPUBTextPerformanceSampler.swift

@@ -1,20 +1,17 @@
 import Foundation
 
-// MARK: - 性能采样数据模型
-
-/// 单个章节的性能采样数据，记录渲染和分页的耗时。
 public struct RDEPUBTextPerformanceSample: Equatable {
-    /// 章节文件路径
+
     public var chapterHref: String
-    /// HTML 渲染耗时（秒）
+
     public var renderDuration: TimeInterval
-    /// CoreText 分页耗时（秒）
+
     public var paginateDuration: TimeInterval
-    /// 分页后的页数
+
     public var pageCount: Int
-    /// 富文本字符长度
+
     public var attributedStringLength: Int
-    /// 是否命中分页缓存
+
     public var cacheHit: Bool
 
     public init(
@@ -34,21 +31,14 @@ public struct RDEPUBTextPerformanceSample: Equatable {
     }
 }
 
-// MARK: - 性能采样器
-
-/// 书籍构建过程的性能采样器，用于监控每章的渲染和分页耗时。
-///
-/// 由 `RDEPUBTextBookBuilder` 在构建过程中使用，每章记录一个采样点，
-/// 构建完成后输出汇总报告。
 public final class RDEPUBTextPerformanceSampler {
-    /// 所有章节的采样数据列表
+
     public private(set) var samples: [RDEPUBTextPerformanceSample] = []
-    /// 整本书构建的总耗时（秒）
+
     public var totalBuildDuration: TimeInterval = 0
 
     public init() {}
 
-    /// 记录单个章节的性能采样，并输出日志
     public func record(_ sample: RDEPUBTextPerformanceSample) {
         samples.append(sample)
         #if DEBUG
@@ -56,7 +46,6 @@ public final class RDEPUBTextPerformanceSampler {
         #endif
     }
 
-    /// 生成性能汇总报告，包含总渲染/分页耗时和缓存命中率
     public func summary() -> String {
         let totalRender = samples.reduce(0) { $0 + $1.renderDuration }
         let totalPaginate = samples.reduce(0) { $0 + $1.paginateDuration }
@@ -64,13 +53,11 @@ public final class RDEPUBTextPerformanceSampler {
         return "[PERF] chapters=\(samples.count) render=\(formatMS(totalRender)) paginate=\(formatMS(totalPaginate)) total=\(formatMS(totalBuildDuration)) cacheHits=\(hitCount)/\(samples.count)"
     }
 
-    /// 重置所有采样数据
     public func reset() {
         samples.removeAll()
         totalBuildDuration = 0
     }
 
-    /// 将秒转换为毫秒格式字符串
     private func formatMS(_ duration: TimeInterval) -> String {
         String(format: "%.0fms", duration * 1000)
     }

Sources/RDReaderView/EPUBTextRendering/Pagination/RDEPUBChapterPageCounter.swift

@@ -5,24 +5,20 @@ import UIKit
 import DTCoreText
 #endif
 
-/// 章节分页计数器：顶层编排循环，将富文本按页面尺寸拆分为多帧。
-///
-/// 分页策略优先级（从高到低）：
-/// 1. avoidPageBreakInside — 不在保护块内分页（WXRead 行级回退扫描）
-/// 2. keepWithNext — 标题等元素需与下一段同页
-/// 3. 语义边界 — pageBreakBefore/After 等显式分页标记
-/// 4. pageRelate — 微信读书式的跨页关联元素
-/// 5. 附件边界 — 块级附件应整体移到下一页
-/// 6. 帧限制 — 默认按 CoreText 可视范围分页
 struct RDEPUBChapterPageCounter {
+
     private let factory: RDEPUBCoreTextPageFrameFactory
+
     private let attributedString: NSAttributedString
+
     private let pageSize: CGSize
+
     private let config: RDEPUBTextLayoutConfig
+
     private let pageBreakPolicy: RDEPUBPageBreakPolicy
+
     private let framesetter: CTFramesetter
 
-    /// DTCoreText 路径可直接消费的单矩形布局区域
     private let dtLayoutRect: CGRect
 
     init(factory: RDEPUBCoreTextPageFrameFactory) {
@@ -35,7 +31,6 @@ struct RDEPUBChapterPageCounter {
         self.dtLayoutRect = factory.config.contentRect(fallback: factory.pageSize)
     }
 
-    /// 执行分页，返回布局帧列表（每帧对应一页）。
     func layoutFrames(fragmentOffsets: [String: Int] = [:]) -> [RDEPUBTextLayoutFrame] {
         guard attributedString.length > 0, pageSize.width > 0, pageSize.height > 0 else {
             return []
@@ -48,8 +43,6 @@ struct RDEPUBChapterPageCounter {
 #endif
     }
 
-    // MARK: - CoreText 分页路径（回退方案）
-
     private func layoutFramesUsingCoreText(fragmentOffsets: [String: Int]) -> [RDEPUBTextLayoutFrame] {
         guard attributedString.length > 0, pageSize.width > 0, pageSize.height > 0 else {
             return []
@@ -129,9 +122,8 @@ struct RDEPUBChapterPageCounter {
         return frames
     }
 
-    // MARK: - DTCoreText 分页路径（首选方案）
-
 #if canImport(DTCoreText)
+
     private func layoutFramesUsingDTCoreText(fragmentOffsets: [String: Int]) -> [RDEPUBTextLayoutFrame] {
         guard config.numberOfColumns == 1 else {
             return layoutFramesUsingCoreText(fragmentOffsets: fragmentOffsets)
@@ -252,9 +244,6 @@ struct RDEPUBChapterPageCounter {
     }
 #endif
 
-    // MARK: - WXRead 分页对齐
-
-    /// 读取 CoreText frame 当前可见的字符范围；多栏 path 下也能返回整页可见区。
     private func proposedVisibleRange(
         from frame: CTFrame,
         start location: Int,

Sources/RDReaderView/EPUBTextRendering/Pagination/RDEPUBCoreTextPageFrameFactory.swift

@@ -5,13 +5,14 @@ import UIKit
 import DTCoreText
 #endif
 
-/// CoreText 帧工厂：负责帧创建、行级裁剪、属性查询和诊断构建。
-///
-/// 叶节点组件，被 RDEPUBChapterPageCounter 和 RDEPUBPageBreakPolicy 调用。
 struct RDEPUBCoreTextPageFrameFactory: RDEPUBPageFrameBuilding {
+
     let attributedString: NSAttributedString
+
     let pageSize: CGSize
+
     let config: RDEPUBTextLayoutConfig
+
     private let pageBreakPolicy: RDEPUBPageBreakPolicy
 
     init(attributedString: NSAttributedString, pageSize: CGSize, config: RDEPUBTextLayoutConfig = .default) {
@@ -21,13 +22,10 @@ struct RDEPUBCoreTextPageFrameFactory: RDEPUBPageFrameBuilding {
         self.pageBreakPolicy = RDEPUBPageBreakPolicy(attributedString: attributedString)
     }
 
-    /// 协议要求的便捷初始化（使用默认配置）
     init() {
         self.init(attributedString: NSAttributedString(), pageSize: .zero, config: .default)
     }
 
-    // MARK: - RDEPUBPageFrameBuilding 协议
-
     func makeFrames(
         attributedString: NSAttributedString,
         pageSize: CGSize,
@@ -39,9 +37,6 @@ struct RDEPUBCoreTextPageFrameFactory: RDEPUBPageFrameBuilding {
         return counter.layoutFrames(fragmentOffsets: fragmentOffsets)
     }
 
-    // MARK: - 帧构建
-
-    /// 从列矩形构建 CGPath（用于 CTFramesetterCreateFrame）。
     static func makeLayoutPath(pageSize: CGSize, config: RDEPUBTextLayoutConfig) -> CGPath {
         let columnRects = config.columnRects(fallback: pageSize)
         guard columnRects.count > 1 else {
@@ -55,9 +50,6 @@ struct RDEPUBCoreTextPageFrameFactory: RDEPUBPageFrameBuilding {
         return path
     }
 
-    // MARK: - 行级裁剪
-
-    /// 从 CTFrame 最后一行向前扫描，移除落在 avoidPageBreakInside 保护块内的尾部行。
     func trimmedRangeForAvoidPageBreakInside(
         from frame: CTFrame,
         proposed: NSRange
@@ -74,7 +66,6 @@ struct RDEPUBCoreTextPageFrameFactory: RDEPUBPageFrameBuilding {
         return trimmedRangeForAvoidPageBreakInside(proposed: proposed, lineRanges: lineRanges)
     }
 
-    /// CoreText 路径的 keepWithNext 处理：从最后行向前扫描
     func trimmedRangeForKeepWithNext(
         from frame: CTFrame,
         proposed: NSRange
@@ -88,7 +79,7 @@ struct RDEPUBCoreTextPageFrameFactory: RDEPUBPageFrameBuilding {
     }
 
 #if canImport(DTCoreText)
-    /// DTCoreText 路径的 avoidPageBreakInside 处理
+
     func trimmedRangeForAvoidPageBreakInside(
         from layoutFrame: DTCoreTextLayoutFrame,
         proposed: NSRange
@@ -102,7 +93,6 @@ struct RDEPUBCoreTextPageFrameFactory: RDEPUBPageFrameBuilding {
         return trimmedRangeForAvoidPageBreakInside(proposed: proposed, lineRanges: lineRanges)
     }
 
-    /// DTCoreText 路径的 keepWithNext 处理
     func trimmedRangeForKeepWithNext(
         from layoutFrame: DTCoreTextLayoutFrame,
         proposed: NSRange
@@ -115,7 +105,6 @@ struct RDEPUBCoreTextPageFrameFactory: RDEPUBPageFrameBuilding {
     }
 #endif
 
-    /// 从最后行向前扫描，移除落在 avoidPageBreakInside 保护块内的尾部行（通用路径）。
     func trimmedRangeForAvoidPageBreakInside(
         proposed: NSRange,
         lineRanges: [NSRange]
@@ -155,7 +144,6 @@ struct RDEPUBCoreTextPageFrameFactory: RDEPUBPageFrameBuilding {
         return NSRange(location: proposed.location, length: adjustedLength)
     }
 
-    /// 从最后行向前扫描，移除落在 keepWithNext 保护块内的尾部行。
     func trimmedRangeForKeepWithNext(
         proposed: NSRange,
         lineRanges: [NSRange]
@@ -195,7 +183,6 @@ struct RDEPUBCoreTextPageFrameFactory: RDEPUBPageFrameBuilding {
         return NSRange(location: proposed.location, length: adjustedLength)
     }
 
-    /// 根据 avoidWidows / avoidOrphans 修正页尾断点，避免段首孤悬页尾或段末独悬下一页。
     func trimmedRangeForWidowAndOrphanControl(
         proposed: NSRange,
         lineRanges: [NSRange]
@@ -227,9 +214,6 @@ struct RDEPUBCoreTextPageFrameFactory: RDEPUBPageFrameBuilding {
         return adjusted
     }
 
-    // MARK: - 行信息提取
-
-    /// 获取 CTFrame 中所有行的字符范围
     static func lineRanges(from frame: CTFrame) -> [NSRange] {
         let lines = CTFrameGetLines(frame) as! [CTLine]
         return lines.map {
@@ -239,7 +223,7 @@ struct RDEPUBCoreTextPageFrameFactory: RDEPUBPageFrameBuilding {
     }
 
 #if canImport(DTCoreText)
-    /// 获取 DTCoreTextLayoutFrame 中所有行的字符范围
+
     static func lineRanges(from layoutFrame: DTCoreTextLayoutFrame) -> [NSRange] {
         guard let lines = layoutFrame.lines as? [DTCoreTextLayoutLine] else {
             return []
@@ -248,9 +232,6 @@ struct RDEPUBCoreTextPageFrameFactory: RDEPUBPageFrameBuilding {
     }
 #endif
 
-    // MARK: - 属性查询
-
-    /// 获取指定位置的块级元素范围
     func blockRange(at location: Int) -> NSRange? {
         guard location >= 0, location < attributedString.length else { return nil }
         let attributes = attributedString.attributes(at: location, effectiveRange: nil)
@@ -260,7 +241,6 @@ struct RDEPUBCoreTextPageFrameFactory: RDEPUBPageFrameBuilding {
         return nil
     }
 
-    /// 获取指定位置的块级元素类型
     func blockKind(at location: Int) -> RDEPUBTextBlockKind? {
         guard location >= 0, location < attributedString.length else { return nil }
         let attributes = attributedString.attributes(at: location, effectiveRange: nil)
@@ -268,7 +248,6 @@ struct RDEPUBCoreTextPageFrameFactory: RDEPUBPageFrameBuilding {
         return RDEPUBTextBlockKind(rawValue: rawValue)
     }
 
-    /// 获取指定位置的附件布局方式
     func attachmentPlacement(at location: Int) -> RDEPUBTextAttachmentPlacement? {
         guard location >= 0, location < attributedString.length else { return nil }
         let attributes = attributedString.attributes(at: location, effectiveRange: nil)
@@ -276,7 +255,6 @@ struct RDEPUBCoreTextPageFrameFactory: RDEPUBPageFrameBuilding {
         return RDEPUBTextAttachmentPlacement(rawValue: rawValue)
     }
 
-    /// 获取包含指定位置的段落范围
     func paragraphRange(containing location: Int) -> NSRange {
         let source = attributedString.string as NSString
         guard source.length > 0 else { return NSRange(location: 0, length: 0) }
@@ -284,7 +262,6 @@ struct RDEPUBCoreTextPageFrameFactory: RDEPUBPageFrameBuilding {
         return source.paragraphRange(for: NSRange(location: safeLocation, length: 0))
     }
 
-    /// 获取指定范围内的所有附件字符范围
     func attachmentRanges(in range: NSRange) -> [NSRange] {
         guard let safeRange = clampedRange(range), safeRange.length > 0 else {
             return []
@@ -297,7 +274,6 @@ struct RDEPUBCoreTextPageFrameFactory: RDEPUBPageFrameBuilding {
         return results
     }
 
-    /// 获取指定位置的语义提示列表
     func semanticHints(at location: Int) -> [RDEPUBTextSemanticHint] {
         guard location >= 0, location < attributedString.length else { return [] }
         let attributes = attributedString.attributes(at: location, effectiveRange: nil)
@@ -307,8 +283,6 @@ struct RDEPUBCoreTextPageFrameFactory: RDEPUBPageFrameBuilding {
             .compactMap { RDEPUBTextSemanticHint(rawValue: String($0)) }
     }
 
-    // MARK: - Widow / Orphan 控制
-
     private func trimmedRangeAvoidingWidow(
         proposed: NSRange,
         lineRanges: [NSRange]
@@ -408,7 +382,6 @@ struct RDEPUBCoreTextPageFrameFactory: RDEPUBPageFrameBuilding {
         return lineCount
     }
 
-    /// 获取指定范围内的附件类型列表（去重）
     func attachmentKinds(in range: NSRange) -> [RDEPUBTextAttachmentKind] {
         guard let safeRange = clampedRange(range), safeRange.length > 0 else {
             return []
@@ -425,7 +398,6 @@ struct RDEPUBCoreTextPageFrameFactory: RDEPUBPageFrameBuilding {
         return kinds
     }
 
-    /// 获取指定范围内的块级元素类型列表（去重）
     func blockKinds(in range: NSRange) -> [RDEPUBTextBlockKind] {
         guard let safeRange = clampedRange(range), safeRange.length > 0 else {
             return []
@@ -442,7 +414,6 @@ struct RDEPUBCoreTextPageFrameFactory: RDEPUBPageFrameBuilding {
         return kinds
     }
 
-    /// 获取指定范围内的语义提示列表（去重）
     func semanticHints(in range: NSRange) -> [RDEPUBTextSemanticHint] {
         guard let safeRange = clampedRange(range), safeRange.length > 0 else {
             return []
@@ -457,7 +428,6 @@ struct RDEPUBCoreTextPageFrameFactory: RDEPUBPageFrameBuilding {
         return hints
     }
 
-    /// 获取指定范围内的附件布局方式列表（去重）
     func attachmentPlacements(in range: NSRange) -> [RDEPUBTextAttachmentPlacement] {
         guard let safeRange = clampedRange(range), safeRange.length > 0 else {
             return []
@@ -474,7 +444,6 @@ struct RDEPUBCoreTextPageFrameFactory: RDEPUBPageFrameBuilding {
         return placements
     }
 
-    /// 将范围裁剪到 attributedString 的合法边界内。
     func clampedRange(_ range: NSRange) -> NSRange? {
         guard range.location >= 0, range.length >= 0 else { return nil }
         guard attributedString.length > 0 else {
@@ -486,7 +455,6 @@ struct RDEPUBCoreTextPageFrameFactory: RDEPUBPageFrameBuilding {
         return NSRange(location: range.location, length: min(range.length, maxLength))
     }
 
-    /// 查找指定位置之前最近的 fragment ID（用于阅读位置恢复）
     func nearestTrailingFragmentID(
         endingAt location: Int,
         fragmentOffsets: [String: Int]
@@ -497,9 +465,6 @@ struct RDEPUBCoreTextPageFrameFactory: RDEPUBPageFrameBuilding {
             .key
     }
 
-    // MARK: - 诊断日志
-
-    /// 生成分页诊断日志
     func diagnostics(
         reason: RDEPUBTextPageBreakReason,
         range: NSRange,

Sources/RDReaderView/EPUBTextRendering/Pagination/RDEPUBPageBreakPolicy.swift

@@ -1,19 +1,14 @@
 import Foundation
 import UIKit
 
-/// 分页规则策略：语义边界搜索、行级保护检查、范围调整调度器。
-///
-/// 不构建 CoreText frame，只基于 attributed string 属性做规则判定。
 struct RDEPUBPageBreakPolicy {
+
     private let attributedString: NSAttributedString
 
     init(attributedString: NSAttributedString) {
         self.attributedString = attributedString
     }
 
-    // MARK: - 行级保护检查
-
-    /// 检查指定行范围是否落在 avoidPageBreakInside 保护块内。
     func lineIsInAvoidPageBreakInsideBlock(_ lineRange: NSRange) -> Bool {
         guard let probeRange = clampedProbeRange(for: lineRange) else {
             return false
@@ -35,7 +30,6 @@ struct RDEPUBPageBreakPolicy {
         return found
     }
 
-    /// 检查指定行范围是否落在 keepWithNext 保护块内。
     func lineIsInKeepWithNextBlock(_ lineRange: NSRange) -> Bool {
         guard let probeRange = clampedProbeRange(for: lineRange) else {
             return false
@@ -54,14 +48,6 @@ struct RDEPUBPageBreakPolicy {
         return found
     }
 
-    // MARK: - 范围调整调度器
-
-    /// 对 CoreText/DTCoreText 提出的分页范围进行语义边界调整。
-    ///
-    /// 调整优先级：
-    /// 1. 若已达章节末尾，直接返回 chapterEnd
-    /// 2. pageRelate 跨页关联边界
-    /// 3. 以上都不满足时，使用原始帧限制分页
     func adjustedRange(
         from proposedRange: NSRange,
         totalLength: Int,
@@ -111,8 +97,6 @@ struct RDEPUBPageBreakPolicy {
         let currentSemanticHints = proposedSemanticHints
         let currentAttachmentPlacements = proposedAttachmentPlacements
 
-        // 对齐 WXRead：默认按 CTFrame 已经容纳的行数分页，仅保留 pageRelate 这种
-        // 微信读书特有的跨页关联规则。
         if let pageRelateBoundary = preferredPageRelateBoundary(
             after: proposedRange,
             minimumEnd: proposedRange.location + 1,
@@ -142,7 +126,6 @@ struct RDEPUBPageBreakPolicy {
             )
         }
 
-        // 帧限制（默认分页）
         return (
             range: proposedRange,
             breakReason: .frameLimit,
@@ -164,9 +147,6 @@ struct RDEPUBPageBreakPolicy {
         )
     }
 
-    // MARK: - 语义边界查找
-
-    /// 查找 pageRelate 跨页关联边界。
     func preferredPageRelateBoundary(
         after range: NSRange,
         minimumEnd: Int,
@@ -192,8 +172,6 @@ struct RDEPUBPageBreakPolicy {
         return lastLineStart
     }
 
-    // MARK: - 内部工具
-
     private func shouldTreatAvoidHintAsBlockProtection(_ attributes: [NSAttributedString.Key: Any]) -> Bool {
         guard let rawValue = attributes[.rdPageSemanticHints] as? String else {
             return false

Sources/RDReaderView/EPUBTextRendering/Pagination/RDEPUBTextLayoutFrame.swift

@@ -1,33 +1,27 @@
 import Foundation
 
-/// CoreText 分页引擎产生的单帧（单页）布局数据。
-///
-/// 由 `RDEPUBTextLayouter` 在分页过程中生成，记录了该页的内容范围、分页原因、
-/// 附件信息和语义标记。`RDEPUBTextBookBuilder` 会将 `RDEPUBTextLayoutFrame` 转换为
-/// `RDEPUBTextPage`，并纳入最终的 `RDEPUBTextBook` 模型。
 struct RDEPUBTextLayoutFrame: Equatable {
-    /// 该帧在章节富文本中的字符范围
+
     var contentRange: NSRange
-    /// 分页原因（语义边界、附件边界、帧限制等）
+
     var breakReason: RDEPUBTextPageBreakReason
-    /// 所属 HTML 块级元素的范围（用于调试）
+
     var blockRange: NSRange?
-    /// 帧内附件的字符范围列表
+
     var attachmentRanges: [NSRange]
-    /// 帧内附件类型列表（图片、通用附件等）
+
     var attachmentKinds: [RDEPUBTextAttachmentKind]
-    /// 帧内包含的 HTML 块级元素类型列表（段落、列表、表格等）
+
     var blockKinds: [RDEPUBTextBlockKind]
-    /// 帧内语义提示列表（避免分页、保持与下一段同页等）
+
     var semanticHints: [RDEPUBTextSemanticHint]
-    /// 帧内附件的布局方式（行内、基线、居中）
+
     var attachmentPlacements: [RDEPUBTextAttachmentPlacement]
-    /// 帧尾部最近的 fragment ID（用于恢复阅读位置）
+
     var trailingFragmentID: String?
-    /// 诊断日志列表（分页原因详情、范围信息等）
+
     var diagnostics: [String]
 
-    /// 将布局帧数据转换为页元数据模型
     var metadata: RDEPUBTextPageMetadata {
         RDEPUBTextPageMetadata(
             breakReason: breakReason,

Sources/RDReaderView/EPUBTextRendering/Pagination/RDEPUBTextLayouter.swift

@@ -5,12 +5,6 @@ import UIKit
 import DTCoreText
 #endif
 
-/// CoreText 分页引擎 Facade：将富文本按页面尺寸拆分为多帧（每帧对应一页）。
-///
-/// 内部委托给三个组件：
-/// - RDEPUBCoreTextPageFrameFactory — 帧创建、属性查询、诊断
-/// - RDEPUBPageBreakPolicy — 分页规则（语义保护、keepWithNext）
-/// - RDEPUBChapterPageCounter — 顶层分页循环编排
 struct RDEPUBTextLayouter {
     private let counter: RDEPUBChapterPageCounter
 
@@ -19,7 +13,6 @@ struct RDEPUBTextLayouter {
         self.counter = RDEPUBChapterPageCounter(factory: factory)
     }
 
-    /// 执行分页，返回布局帧列表（每帧对应一页）。
     func layoutFrames(fragmentOffsets: [String: Int] = [:]) -> [RDEPUBTextLayoutFrame] {
         counter.layoutFrames(fragmentOffsets: fragmentOffsets)
     }

Sources/RDReaderView/EPUBTextRendering/Pagination/RDEPUBTextPaginationInterfaces.swift

@@ -1,30 +1,18 @@
-// RDEPUBTextPaginationInterfaces.swift
-// EPUB 分页接口定义，包括断页决策、章节数页和页面帧构建协议。
 
 import Foundation
 import UIKit
 
-// MARK: - 分页接口定义
-
-/// 单次断页决策，记录断页位置、原因及诊断信息。
 struct RDEPUBPageBreakDecision {
-    /// 本页在富文本中的字符范围
+
     var range: NSRange
-    /// 断页原因
+
     var reason: RDEPUBTextPageBreakReason
-    /// 分页过程中的诊断日志
+
     var diagnostics: [String]
 }
 
-/// 章节页数计算接口，将富文本按页面尺寸拆分为断页决策序列。
 protocol RDEPUBChapterPageCounting {
-    /// 计算章节中每页的断页位置。
-    /// - Parameters:
-    ///   - attributedString: 章节富文本
-    ///   - pageSize: 页面尺寸
-    ///   - config: 排版配置
-    ///   - fragmentOffsets: fragment 锚点偏移映射
-    /// - Returns: 断页决策数组，每个元素对应一页
+
     func pageRanges(
         for attributedString: NSAttributedString,
         pageSize: CGSize,
@@ -33,15 +21,8 @@ protocol RDEPUBChapterPageCounting {
     ) -> [RDEPUBPageBreakDecision]
 }
 
-/// 页面帧构建接口，将富文本转换为可渲染的页面帧数组。
 protocol RDEPUBPageFrameBuilding {
-    /// 将富文本构建为页面帧数组。
-    /// - Parameters:
-    ///   - attributedString: 待分页的富文本
-    ///   - pageSize: 页面尺寸
-    ///   - config: 排版配置
-    ///   - fragmentOffsets: fragment 锚点偏移映射
-    /// - Returns: 页面帧数组
+
     func makeFrames(
         attributedString: NSAttributedString,
         pageSize: CGSize,

Sources/RDReaderView/EPUBTextRendering/Pagination/RDEPUBTextPaginationSupport.swift

@@ -1,18 +1,8 @@
 import CoreText
 import UIKit
 
-// MARK: - NSAttributedString 分页扩展
-
-/// 为 NSAttributedString 提供便捷的分页方法，是渲染链路中 CoreText 分页的入口点。
 extension NSAttributedString {
-    /// 将富文本按指定页面尺寸分页，返回布局帧列表（每帧对应一页）。
-    ///
-    /// 这是 `RDEPUBTextBookBuilder` 和 `RDPlainTextBookBuilder` 调用的核心分页方法。
-    /// - Parameters:
-    ///   - size: 页面尺寸
-    ///   - fragmentOffsets: fragment ID → 字符偏移量映射（用于阅读位置恢复）
-    ///   - config: 布局配置（孤行控制、avoidPageBreakInside 等）
-    /// - Returns: 分页后的布局帧列表
+
     func rd_paginatedFrames(
         size: CGSize,
         fragmentOffsets: [String: Int] = [:],
@@ -23,17 +13,13 @@ extension NSAttributedString {
         return counter.layoutFrames(fragmentOffsets: fragmentOffsets)
     }
 
-    /// 简化版分页：只返回每页的 NSRange 列表（不含语义元数据）
     func ss_pageRanges(size: CGSize) -> [NSRange] {
         rd_paginatedFrames(size: size).map(\.contentRange)
     }
 }
 
-// MARK: - UIColor CSS 转换扩展
-
-/// 为 UIColor 提供 CSS 颜色字符串转换，用于动态生成暗色模式 CSS。
 extension UIColor {
-    /// 将 UIColor 转换为 CSS rgba() 字符串格式
+
     var ss_cssString: String {
         var red: CGFloat = 0
         var green: CGFloat = 0

Sources/RDReaderView/EPUBTextRendering/RDEPUBChapterData.swift

@@ -1,14 +1,9 @@
 import UIKit
 
-/// 章节数据访问层：为已分页章节提供便捷的查询接口。
-///
-/// 本类是 `RDEPUBTextChapter` 的轻量级封装，持有 `indexTable`（全局索引表），
-/// 将分页数据、fragment 锚点、高亮、搜索结果等统一到同一套查询 API 中。
-/// 由 `RDEPUBTextBook.chapterData(for:)` 或 `chapterData(atChapterIndex:)` 创建。
 public final class RDEPUBChapterData {
-    /// 底层章节模型（只读）
+
     public let chapter: RDEPUBTextChapter
-    /// 全局索引表，用于 fileIndex/row/column 到绝对偏移量的映射
+
     public let indexTable: RDEPUBTextIndexTable
 
     public init(chapter: RDEPUBTextChapter, indexTable: RDEPUBTextIndexTable) {
@@ -16,88 +11,66 @@ public final class RDEPUBChapterData {
         self.indexTable = indexTable
     }
 
-    // MARK: - 便捷属性（转发自 chapter）
-
-    /// 章节在全书中的序号
     public var chapterIndex: Int { chapter.chapterIndex }
-    /// spine 顺序索引
+
     public var spineIndex: Int { chapter.spineIndex }
-    /// 章节文件相对路径（如 "OEBPS/chapter1.xhtml"）
+
     public var href: String { chapter.href }
-    /// 章节标题
+
     public var title: String { chapter.title }
-    /// 章节完整的富文本内容
+
     public var attributedContent: NSAttributedString { chapter.attributedContent }
-    /// 分页后的页面列表
+
     public var pages: [RDEPUBTextPage] { chapter.pages }
-    /// 章节总页数
+
     public var pageCount: Int { chapter.pages.count }
-    /// fragment ID → 字符偏移量的映射表（用于锚点定位）
+
     public var fragmentOffsets: [String: Int] { chapter.fragmentOffsets }
-    /// 章节信息快照（供阅读会话/目录面板复用）
+
     public var chapterInfo: EPUBChapterInfo {
         EPUBChapterInfo(spineIndex: spineIndex, title: title, pageCount: pageCount)
     }
-    /// 章节覆盖的绝对页码范围（闭区间）
+
     public var absolutePageRange: ClosedRange<Int>? {
         guard let firstPage = pages.first, let lastPage = pages.last else { return nil }
         return firstPage.absolutePageIndex...lastPage.absolutePageIndex
     }
 
-    // MARK: - 页面查询
-
-    /// 查找包含指定绝对字符偏移量的页面
-    /// - Parameter absoluteOffset: 全书绝对字符偏移量
-    /// - Returns: 包含该偏移量的页面，未找到返回 nil
     public func page(containing absoluteOffset: Int) -> RDEPUBTextPage? {
         chapter.pages.first { NSLocationInRange(absoluteOffset, $0.contentRange) }
     }
 
-    /// 获取指定绝对偏移量所在页的绝对页码（从 0 开始）
     public func pageNumber(containing absoluteOffset: Int) -> Int? {
         page(containing: absoluteOffset)?.absolutePageIndex
     }
 
-    /// 按绝对页码查找页面
     public func page(atAbsolutePageIndex absolutePageIndex: Int) -> RDEPUBTextPage? {
         chapter.pages.first { $0.absolutePageIndex == absolutePageIndex }
     }
 
-    /// 按章节内页码查找页面（从 1 开始）
     public func page(atPageNumber pageNumber: Int) -> RDEPUBTextPage? {
         guard pageNumber > 0, pages.indices.contains(pageNumber - 1) else { return nil }
         return pages[pageNumber - 1]
     }
 
-    // MARK: - 锚点与位置映射
-
-    /// 将章节内字符索引转换为语义锚点（fileIndex/row/column 三元组）
     public func anchor(forAbsoluteIndex index: Int) -> RDEPUBTextAnchor {
         indexTable.anchor(forAbsoluteIndex: index, in: chapter)
     }
 
-    /// 将全书字符索引转换为语义锚点。
     public func anchor(forGlobalIndex index: Int) -> RDEPUBTextAnchor? {
         indexTable.anchor(forGlobalIndex: index)
     }
 
-    /// 将章节内字符范围转换为起止锚点对
     public func rangeAnchor(for absoluteRange: NSRange) -> RDEPUBTextRangeAnchor {
         let start = anchor(forAbsoluteIndex: absoluteRange.location)
         let end = anchor(forAbsoluteIndex: absoluteRange.location + absoluteRange.length)
         return RDEPUBTextRangeAnchor(start: start, end: end)
     }
 
-    /// 将锚点范围转换为全书字符范围。
     public func globalRange(for rangeAnchor: RDEPUBTextRangeAnchor) -> NSRange {
         indexTable.globalRange(for: rangeAnchor)
     }
 
-    /// 从绝对字符范围构建选区对象（用于复制/高亮分享）
-    /// - Parameters:
-    ///   - absoluteRange: 选区在全书中的字符范围
-    ///   - bookIdentifier: 书籍标识符
-    /// - Returns: 选区对象，若起始偏移量不在任何页面内则返回 nil
     public func selection(from absoluteRange: NSRange, bookIdentifier: String?) -> RDEPUBSelection? {
         guard page(containing: absoluteRange.location) != nil else { return nil }
         let location = self.location(for: absoluteRange, bookIdentifier: bookIdentifier)
@@ -115,7 +88,6 @@ public final class RDEPUBChapterData {
         )
     }
 
-    /// 将绝对字符范围转换为持久化位置对象（RDEPUBLocation）
     public func location(for absoluteRange: NSRange, bookIdentifier: String?) -> RDEPUBLocation {
         indexTable.location(
             for: rangeAnchor(for: absoluteRange),
@@ -124,32 +96,31 @@ public final class RDEPUBChapterData {
         )
     }
 
-    /// 将页面转换为对应的 RDEPUBLocation
     public func location(forPage page: RDEPUBTextPage, bookIdentifier: String?) -> RDEPUBLocation {
         location(for: page.contentRange, bookIdentifier: bookIdentifier)
     }
 
-    /// 根据持久化位置定位所属页面。
     public func page(for location: RDEPUBLocation) -> RDEPUBTextPage? {
         guard let range = absoluteRange(for: location) else { return nil }
         return page(containing: range.location)
     }
 
-    /// 根据搜索结果定位所属页面。
     public func page(for searchMatch: RDEPUBSearchMatch) -> RDEPUBTextPage? {
         guard let range = absoluteRange(for: searchMatch) else { return nil }
         return page(containing: range.location)
     }
 
-    // MARK: - 位置反向解析（Location → 绝对偏移量）
-
-    /// 将持久化位置还原为章节内的字符范围。
-    ///
-    /// 解析优先级：
-    /// 1. rangeAnchor（锚点定位，最精确）
-    /// 2. fragment（片段 ID 定位）
-    /// 3. navigationProgression（进度百分比回退）
     public func absoluteRange(for location: RDEPUBLocation) -> NSRange? {
+        if let cfiRange = RDEPUBCFICompatibility.parseRangeLossy(location.rangeCFI),
+           let rangeAnchor = indexTable.rangeAnchor(for: cfiRange) {
+            return indexTable.chapterRange(for: rangeAnchor)
+        }
+
+        if let cfi = RDEPUBCFICompatibility.parseLossy(location.cfi),
+           let anchor = indexTable.anchor(for: cfi) {
+            return NSRange(location: indexTable.chapterOffset(for: anchor), length: 1)
+        }
+
         if let rangeAnchor = location.rangeAnchor {
             return indexTable.chapterRange(for: rangeAnchor)
         }
@@ -164,16 +135,35 @@ public final class RDEPUBChapterData {
         return NSRange(location: offset, length: 1)
     }
 
-    /// 从高亮的持久化位置还原绝对字符范围
     public func absoluteRange(for highlight: RDEPUBHighlight) -> NSRange? {
+        if let cfiRange = RDEPUBCFICompatibility.parseRangeLossy(highlight.location.rangeCFI),
+           let rangeAnchor = indexTable.rangeAnchor(for: cfiRange) {
+            return indexTable.chapterRange(for: rangeAnchor)
+        }
+
+        if let endpointRange = chapterRange(fromLocationCFIEndpoints: highlight.location) {
+            return endpointRange
+        }
+
         if let rangeAnchor = highlight.location.rangeAnchor {
             return indexTable.chapterRange(for: rangeAnchor)
         }
         return RDEPUBTextOffsetRangeInfo.decode(from: highlight.rangeInfo)?.nsRange
     }
 
-    /// 从搜索结果还原绝对字符范围
     public func absoluteRange(for searchMatch: RDEPUBSearchMatch) -> NSRange? {
+        if let cfiRange = RDEPUBCFICompatibility.parseRangeLossy(searchMatch.rangeCFI),
+           let rangeAnchor = indexTable.rangeAnchor(for: cfiRange) {
+            return indexTable.chapterRange(for: rangeAnchor)
+        }
+        if let cfi = RDEPUBCFICompatibility.parseLossy(searchMatch.cfi),
+           let anchor = indexTable.anchor(for: cfi) {
+            let location = indexTable.chapterOffset(for: anchor)
+            return NSRange(
+                location: location,
+                length: recoveredSearchRangeLength(for: searchMatch, cfi: cfi, startOffset: location)
+            )
+        }
         if let location = searchMatch.rangeLocation {
             return NSRange(location: location, length: max(searchMatch.rangeLength, 1))
         }
@@ -183,8 +173,17 @@ public final class RDEPUBChapterData {
         return nil
     }
 
-    /// 将持久化位置还原为全书字符范围。
     public func globalRange(for location: RDEPUBLocation) -> NSRange? {
+        if let cfiRange = RDEPUBCFICompatibility.parseRangeLossy(location.rangeCFI),
+           let rangeAnchor = indexTable.rangeAnchor(for: cfiRange) {
+            return indexTable.globalRange(for: rangeAnchor)
+        }
+
+        if let cfi = RDEPUBCFICompatibility.parseLossy(location.cfi),
+           let anchor = indexTable.anchor(for: cfi) {
+            return NSRange(location: indexTable.globalIndex(for: anchor), length: 1)
+        }
+
         if let rangeAnchor = location.rangeAnchor {
             return indexTable.globalRange(for: rangeAnchor)
         }
@@ -195,8 +194,16 @@ public final class RDEPUBChapterData {
         return NSRange(location: chapterStart + chapterRange.location, length: chapterRange.length)
     }
 
-    /// 从高亮的持久化位置还原全书字符范围。
     public func globalRange(for highlight: RDEPUBHighlight) -> NSRange? {
+        if let cfiRange = RDEPUBCFICompatibility.parseRangeLossy(highlight.location.rangeCFI),
+           let rangeAnchor = indexTable.rangeAnchor(for: cfiRange) {
+            return indexTable.globalRange(for: rangeAnchor)
+        }
+
+        if let endpointRange = globalRange(fromLocationCFIEndpoints: highlight.location) {
+            return endpointRange
+        }
+
         if let rangeAnchor = highlight.location.rangeAnchor {
             return indexTable.globalRange(for: rangeAnchor)
         }
@@ -207,8 +214,19 @@ public final class RDEPUBChapterData {
         return NSRange(location: chapterStart + chapterRange.location, length: chapterRange.length)
     }
 
-    /// 从搜索结果还原全书字符范围。
     public func globalRange(for searchMatch: RDEPUBSearchMatch) -> NSRange? {
+        if let cfiRange = RDEPUBCFICompatibility.parseRangeLossy(searchMatch.rangeCFI),
+           let rangeAnchor = indexTable.rangeAnchor(for: cfiRange) {
+            return indexTable.globalRange(for: rangeAnchor)
+        }
+        if let cfi = RDEPUBCFICompatibility.parseLossy(searchMatch.cfi),
+           let anchor = indexTable.anchor(for: cfi) {
+            let chapterLocation = indexTable.chapterOffset(for: anchor)
+            return NSRange(
+                location: indexTable.globalIndex(for: anchor),
+                length: recoveredSearchRangeLength(for: searchMatch, cfi: cfi, startOffset: chapterLocation)
+            )
+        }
         if let rangeAnchor = searchMatch.rangeAnchor {
             return indexTable.globalRange(for: rangeAnchor)
         }
@@ -219,13 +237,14 @@ public final class RDEPUBChapterData {
         return NSRange(location: chapterStart + chapterRange.location, length: chapterRange.length)
     }
 
-    // MARK: - 高亮/搜索结果与页面的交叉查询
-
-    /// 获取指定页面上出现的所有高亮
     public func highlights(on page: RDEPUBTextPage, from allHighlights: [RDEPUBHighlight]) -> [RDEPUBHighlight] {
         let pageRange = absoluteOffsetRange(for: page)
         return allHighlights.filter { highlight in
             guard highlight.location.href == chapter.href else { return false }
+            if let cfiRange = RDEPUBCFICompatibility.parseRangeLossy(highlight.location.rangeCFI),
+               let rangeAnchor = indexTable.rangeAnchor(for: cfiRange) {
+                return NSIntersectionRange(indexTable.chapterRange(for: rangeAnchor), page.contentRange).length > 0
+            }
             if let anchor = highlight.location.rangeAnchor?.start {
                 return pageRange.contains(absoluteOffset(for: anchor))
             }
@@ -236,7 +255,6 @@ public final class RDEPUBChapterData {
         }
     }
 
-    /// 获取指定页面上出现的所有搜索匹配结果
     public func searchMatches(on page: RDEPUBTextPage, from matches: [RDEPUBSearchMatch]) -> [RDEPUBSearchMatch] {
         return matches.filter { match in
             guard match.href == chapter.href else { return false }
@@ -247,26 +265,20 @@ public final class RDEPUBChapterData {
         }
     }
 
-    /// `searchMatches(on:from:)` 的别名；保持和文档/WXRead 语义一致。
     public func searchResults(on page: RDEPUBTextPage, from matches: [RDEPUBSearchMatch]) -> [RDEPUBSearchMatch] {
         searchMatches(on: page, from: matches)
     }
 
-    /// 根据持久化位置获取对应页码（从 1 开始），用于阅读进度跳转
     public func pageNumber(for location: RDEPUBLocation) -> Int? {
         guard let page = page(for: location) else { return nil }
         return page.absolutePageIndex + 1
     }
 
-    /// 根据搜索结果获取对应页码（从 1 开始）。
     public func pageNumber(for searchMatch: RDEPUBSearchMatch) -> Int? {
         guard let page = page(for: searchMatch) else { return nil }
         return page.absolutePageIndex + 1
     }
 
-    // MARK: - 目录与章节语义
-
-    /// 判断某个 TOC 条目是否属于当前章节。
     public func contains(
         tableOfContentsItem item: EPUBTableOfContentsItem,
         normalizer: (String) -> String?
@@ -278,7 +290,6 @@ public final class RDEPUBChapterData {
         return chapterHref == itemHref
     }
 
-    /// 过滤出当前章节命中的目录条目。
     public func tableOfContentsItems(
         from items: [EPUBTableOfContentsItem],
         normalizer: (String) -> String?
@@ -289,7 +300,6 @@ public final class RDEPUBChapterData {
         }
     }
 
-    /// 当前章节最合适的目录条目（通常取命中的首个最近条目）。
     public func primaryTableOfContentsItem(
         from items: [EPUBTableOfContentsItem],
         normalizer: (String) -> String?
@@ -297,10 +307,6 @@ public final class RDEPUBChapterData {
         tableOfContentsItems(from: items, normalizer: normalizer).first
     }
 
-    // MARK: - 高亮属性注入（对齐 WXRead 的 WRChapterData.addHighlightInRange:key:itemId:color:）
-
-    /// 将高亮/下划线作为自定义属性注入 NSAttributedString，
-    /// 供 CoreText 渲染时读取绘制（对齐 WXRead 的 com.weread.highlight / com.weread.underline）
     public func applyHighlights(
         to content: NSMutableAttributedString,
         page: RDEPUBTextPage,
@@ -324,17 +330,51 @@ public final class RDEPUBChapterData {
         }
     }
 
-    // MARK: - 私有工具方法
-
-    /// 将页面的起止偏移量转换为半开区间 [start, end+1)
     private func absoluteOffsetRange(for page: RDEPUBTextPage) -> Range<Int> {
         let lowerBound = page.pageStartOffset
         let upperBound = page.pageEndOffset + 1
         return lowerBound..<max(upperBound, lowerBound)
     }
 
-    /// 将语义锚点转换为章节内字符偏移量，若索引表无法解析则回退到 chapterOffset
     private func absoluteOffset(for anchor: RDEPUBTextAnchor) -> Int {
         indexTable.chapterOffset(for: anchor)
     }
+
+    private func chapterRange(fromLocationCFIEndpoints location: RDEPUBLocation) -> NSRange? {
+        guard let startCFI = RDEPUBCFICompatibility.parseLossy(location.cfi),
+              let endCFI = RDEPUBCFICompatibility.parseLossy(location.lastCFI ?? location.cfi),
+              let startAnchor = indexTable.anchor(for: startCFI),
+              let endAnchor = indexTable.anchor(for: endCFI),
+              startAnchor.fileIndex == endAnchor.fileIndex else {
+            return nil
+        }
+        let start = indexTable.chapterOffset(for: startAnchor)
+        let end = indexTable.chapterOffset(for: endAnchor)
+        return NSRange(location: min(start, end), length: max(abs(end - start), 1))
+    }
+
+    private func globalRange(fromLocationCFIEndpoints location: RDEPUBLocation) -> NSRange? {
+        guard let startCFI = RDEPUBCFICompatibility.parseLossy(location.cfi),
+              let endCFI = RDEPUBCFICompatibility.parseLossy(location.lastCFI ?? location.cfi),
+              let startAnchor = indexTable.anchor(for: startCFI),
+              let endAnchor = indexTable.anchor(for: endCFI),
+              startAnchor.fileIndex == endAnchor.fileIndex else {
+            return nil
+        }
+        let start = indexTable.globalIndex(for: startAnchor)
+        let end = indexTable.globalIndex(for: endAnchor)
+        return NSRange(location: min(start, end), length: max(abs(end - start), 1))
+    }
+
+    private func recoveredSearchRangeLength(
+        for searchMatch: RDEPUBSearchMatch,
+        cfi: RDEPUBCFI,
+        startOffset: Int
+    ) -> Int {
+        let exactLength = cfi.textAssertion?.exact?.utf16.count ?? 0
+        let fallbackLength = max(searchMatch.rangeLength, 1)
+        let candidateLength = exactLength > 0 ? exactLength : fallbackLength
+        let remainingLength = max(attributedContent.length - startOffset, 1)
+        return min(max(candidateLength, 1), remainingLength)
+    }
 }

Sources/RDReaderView/EPUBTextRendering/RDEPUBDTCoreTextRenderer.swift

@@ -4,18 +4,9 @@ import UIKit
 import DTCoreText
 #endif
 
-/// DTCoreText 渲染器实现：将 EPUB 章节 HTML 转换为富文本（NSAttributedString）。
-///
-/// 这是 `RDEPUBTextRenderer` 协议的默认实现，位于渲染链路的第二步：
-/// 章节 HTML → DTCoreText 渲染 → NSAttributedString → 提取 fragment 偏移量 → 统一字体/行距
-///
-/// DTCoreText 库负责将 HTML 解析为带有排版属性的富文本，
-/// 渲染过程中会通过 `willFlushCallback` 回调对每个 DOM 元素做布局规范化（图片尺寸等）。
-/// 当 DTCoreText 不可用时（条件编译失败），回退到纯文本渲染。
 public struct RDEPUBDTCoreTextRenderer: RDEPUBTextRenderer {
     public init() {}
 
-    /// DTCoreText 库是否在当前编译环境中可用
     public static var isAvailable: Bool {
 #if canImport(DTCoreText)
         return true
@@ -24,7 +15,6 @@ public struct RDEPUBDTCoreTextRenderer: RDEPUBTextRenderer {
 #endif
     }
 
-    /// 渲染单个章节：HTML → NSAttributedString，同时提取 fragment 和语义标记。
     public func renderChapter(
         request: RDEPUBTextChapterRenderRequest
     ) throws -> RDEPUBRenderedChapterContent {
@@ -56,7 +46,6 @@ public struct RDEPUBDTCoreTextRenderer: RDEPUBTextRenderer {
 #endif
     }
 
-    /// 便捷方法：直接传入 HTML 字符串进行渲染（不含上下文信息）
     public func renderChapter(
         html: String,
         baseURL: URL?,
@@ -65,6 +54,7 @@ public struct RDEPUBDTCoreTextRenderer: RDEPUBTextRenderer {
         let request = RDEPUBTextTypesetterPipeline().makeRequest(
             from: RDEPUBTypesettingInput(
                 href: "",
+                spineIndex: nil,
                 title: "",
                 rawHTML: html,
                 baseURL: baseURL,
@@ -75,7 +65,6 @@ public struct RDEPUBDTCoreTextRenderer: RDEPUBTextRenderer {
         return try renderChapter(request: request)
     }
 
-    /// 回退渲染：当 DTCoreText 不可用时，将 HTML 源码当作纯文本处理
     private func fallbackRenderedContent(request: RDEPUBTextChapterRenderRequest) -> RDEPUBRenderedChapterContent {
         let attributedString = RDEPUBTextRendererSupport.fallbackAttributedString(for: request.context.html, style: request.style)
         RDEPUBSemanticMarkerInjector.applyPaginationSemantics(in: attributedString)
@@ -93,7 +82,7 @@ public struct RDEPUBDTCoreTextRenderer: RDEPUBTextRenderer {
     }
 
 #if canImport(DTCoreText)
-    /// 使用 DTCoreText 将 HTML Data 解析为富文本。
+
     private func makeAttributedString(from data: Data, request: RDEPUBTextChapterRenderRequest) -> NSAttributedString? {
         let builder = DTHTMLAttributedStringBuilder(
             html: data,
@@ -111,7 +100,6 @@ public struct RDEPUBDTCoreTextRenderer: RDEPUBTextRenderer {
         return builder?.generatedAttributedString()
     }
 
-    /// 构建 DTCoreText 的解析选项字典，包括字体、行高、图片尺寸限制等。
     private func dtOptions(request: RDEPUBTextChapterRenderRequest) -> [AnyHashable: Any] {
         let style = request.style
         let maxImageSize = resolvedMaxImageSize(for: request)

Sources/RDReaderView/EPUBTextRendering/RDEPUBTextPositionConverter.swift

@@ -1,84 +1,46 @@
-// RDEPUBTextPositionConverter.swift
-// EPUB 全书文本位置转换器，在多种坐标体系之间进行双向映射。
 
 import Foundation
 
-/// 对标 WXRead `WREpubPositionConverter` 的全书位置转换器。
-///
-/// 负责在四套坐标之间做双向转换：
-/// - `(fileIndex, row, column)` 文件级语义锚点
-/// - 章节内字符偏移
-/// - 全书字符偏移
-/// - 页码 / `RDEPUBLocation`
 public struct RDEPUBTextPositionConverter {
-    /// 当前转换器所关联的 EPUB 文本对象。
+
     public let book: RDEPUBTextBook
 
-    /// 创建指定 EPUB 文本对象的位置转换器。
-    /// - Parameter book: 要关联的 EPUB 文本对象。
     public init(book: RDEPUBTextBook) {
         self.book = book
     }
 
-    /// 全书字符总数（跨所有文件累计）。
     public var totalCharacterCount: Int {
         book.indexTable.totalCharacterCount
     }
 
-    /// 将语义锚点转换为全书字符偏移。
-    /// - Parameter anchor: 由文件索引、行号、列号组成的语义锚点。
-    /// - Returns: 对应的全书字符偏移量。
     public func globalIndex(for anchor: RDEPUBTextAnchor) -> Int {
         book.indexTable.globalIndex(for: anchor)
     }
 
-    /// 将语义范围锚点转换为全书字符范围。
-    /// - Parameter rangeAnchor: 由起止锚点组成的语义范围。
-    /// - Returns: 对应的全书字符范围（`NSRange`）。
     public func globalRange(for rangeAnchor: RDEPUBTextRangeAnchor) -> NSRange {
         book.indexTable.globalRange(for: rangeAnchor)
     }
 
-    /// 根据全书字符偏移查找所属文件的索引。
-    /// - Parameter index: 全书字符偏移量。
-    /// - Returns: 对应的文件索引，超出范围时返回 `nil`。
     public func fileIndex(forCharacterPosition index: Int) -> Int? {
         book.indexTable.fileIndex(forCharacterPosition: index)
     }
 
-    /// 将全书字符偏移转换为指定文件内的本地偏移。
-    /// - Parameters:
-    ///   - fileIndex: 目标文件索引。
-    ///   - index: 全书字符偏移量。
-    /// - Returns: 文件内的本地字符偏移，越界时返回 `nil`。
     public func localOffsetInFile(at fileIndex: Int, forGlobalPosition index: Int) -> Int? {
         book.indexTable.localOffsetInFile(at: fileIndex, forGlobalPosition: index)
     }
 
-    /// 将全书字符偏移转换为语义锚点。
-    /// - Parameter index: 全书字符偏移量。
-    /// - Returns: 对应的语义锚点，无效位置时返回 `nil`。
     public func anchor(forCharacterPosition index: Int) -> RDEPUBTextAnchor? {
         book.indexTable.anchor(forGlobalIndex: index)
     }
 
-    /// 将 `RDEPUBLocation` 转换为语义锚点。
-    /// - Parameter location: EPUB 位置对象。
-    /// - Returns: 对应的语义锚点，无法映射时返回 `nil`。
     public func anchor(for location: RDEPUBLocation) -> RDEPUBTextAnchor? {
         book.indexTable.anchor(for: location)
     }
 
-    /// 根据语义锚点获取页码（从 1 开始）。
-    /// - Parameter anchor: 由文件索引、行号、列号组成的语义锚点。
-    /// - Returns: 对应的页码，无法定位时返回 `nil`。
     public func pageNumber(for anchor: RDEPUBTextAnchor) -> Int? {
         book.indexTable.pageNumber(for: anchor, in: book).map { $0 + 1 }
     }
 
-    /// 根据全书字符偏移获取页码（从 1 开始）。
-    /// - Parameter index: 全书字符偏移量。
-    /// - Returns: 对应的页码，无效位置时返回 `nil`。
     public func pageNumber(forCharacterPosition index: Int) -> Int? {
         guard let anchor = anchor(forCharacterPosition: index) else {
             return nil
@@ -86,11 +48,6 @@ public struct RDEPUBTextPositionConverter {
         return pageNumber(for: anchor)
     }
 
-    /// 将语义锚点转换为可序列化的 `RDEPUBLocation`。
-    /// - Parameters:
-    ///   - anchor: 由文件索引、行号、列号组成的语义锚点。
-    ///   - bookIdentifier: 书籍标识符，会写入 location 的 `bookId` 字段。
-    /// - Returns: 对应的 `RDEPUBLocation`，无法映射时返回 `nil`。
     public func location(
         for anchor: RDEPUBTextAnchor,
         bookIdentifier: String?
@@ -101,11 +58,6 @@ public struct RDEPUBTextPositionConverter {
         return book.indexTable.location(for: anchor, in: chapter, bookIdentifier: bookIdentifier)
     }
 
-    /// 将语义范围锚点转换为可序列化的 `RDEPUBLocation`。
-    /// - Parameters:
-    ///   - rangeAnchor: 由起止锚点组成的语义范围。
-    ///   - bookIdentifier: 书籍标识符，会写入 location 的 `bookId` 字段。
-    /// - Returns: 对应的 `RDEPUBLocation`，无法映射时返回 `nil`。
     public func location(
         for rangeAnchor: RDEPUBTextRangeAnchor,
         bookIdentifier: String?

Sources/RDReaderView/EPUBTextRendering/RDEPUBTextRenderer.swift

@@ -1,71 +1,54 @@
 import UIKit
 
-// MARK: - 自定义富文本属性键
-
-/// EPUBTextRendering 层使用的自定义 NSAttributedString 属性键。
-/// 这些属性由 `RDEPUBTextRendererSupport` 在渲染阶段注入，
-/// 供 `RDEPUBTextLayouter` 分页时读取语义信息。
 public extension NSAttributedString.Key {
-    /// 块级元素在富文本中的字符范围（NSString 编码的 NSRange）
+
     static let rdPageBlockRange = NSAttributedString.Key("com.rdreader.epub.pageBlockRange")
-    /// 块级元素在章节中的序号
+
     static let rdPageBlockIndex = NSAttributedString.Key("com.rdreader.epub.pageBlockIndex")
-    /// fragment 锚点 ID
+
     static let rdPageFragmentID = NSAttributedString.Key("com.rdreader.epub.pageFragmentID")
-    /// 附件类型（图片/通用附件）
+
     static let rdPageAttachmentKind = NSAttributedString.Key("com.rdreader.epub.pageAttachmentKind")
-    /// 块级元素类型（段落/列表/表格/代码等）
+
     static let rdPageBlockKind = NSAttributedString.Key("com.rdreader.epub.pageBlockKind")
-    /// 语义提示标记（避免分页、保持与下一段同页等，逗号分隔）
+
     static let rdPageSemanticHints = NSAttributedString.Key("com.rdreader.epub.pageSemanticHints")
-    /// 附件布局方式（行内/基线/居中）
+
     static let rdPageAttachmentPlacement = NSAttributedString.Key("com.rdreader.epub.pageAttachmentPlacement")
 }
 
-// MARK: - 块级元素类型枚举
-
-/// HTML 块级元素的类型分类，用于分页时判断语义边界。
 public enum RDEPUBTextBlockKind: String, Codable, Equatable, CaseIterable {
-    case paragraph   // <p>
-    case list        // <ul>, <ol>, <li>
-    case table       // <table> 系列
-    case code        // <pre>, <code>
-    case blockquote  // <blockquote>
-    case attachment  // 附件块（图片、figure 等）
-    case generic     // 通用块（<div>, <h1>-<h6> 等）
+    case paragraph   
+    case list        
+    case table       
+    case code        
+    case blockquote  
+    case attachment  
+    case generic     
 }
 
-// MARK: - 语义提示枚举
-
-/// 分页语义提示，指导分页引擎在何处/何处不进行分页。
 public enum RDEPUBTextSemanticHint: String, Codable, Equatable, CaseIterable {
-    case avoidPageBreakInside  // 禁止在块内分页（如代码块、表格）
-    case keepWithNext          // 与下一段保持同页（如标题）
-    case pageBreakBefore       // 在此元素前强制分页
-    case pageBreakAfter        // 在此元素后强制分页
-    case pageRelate            // 微信读书式跨页关联元素
+    case avoidPageBreakInside  
+    case keepWithNext          
+    case pageBreakBefore       
+    case pageBreakAfter        
+    case pageRelate            
 }
 
-// MARK: - 附件布局方式枚举
-
-/// 富文本附件（图片等）的垂直布局方式。
 public enum RDEPUBTextAttachmentPlacement: String, Codable, Equatable {
-    case inline     // 行内布局
-    case baseline   // 基线对齐
-    case centered   // 垂直居中（块级）
+    case inline     
+    case baseline   
+    case centered   
 }
 
-// MARK: - 渲染样式
-
-/// 阅读器渲染样式配置，控制字体、行距、颜色等。
 public struct RDEPUBTextRenderStyle {
-    /// 基础字体（大小和字族将覆盖 EPUB 原始样式）
+
     public var font: UIFont
-    /// 行间距（pt）
+
     public var lineSpacing: CGFloat
-    /// 文本颜色（nil 则使用 EPUB 原始颜色）
+
     public var textColor: UIColor?
-    /// 背景颜色（nil 则透明，用于暗色模式判断）
+
     public var backgroundColor: UIColor?
 
     public init(font: UIFont, lineSpacing: CGFloat, textColor: UIColor? = nil, backgroundColor: UIColor? = nil) {
@@ -76,31 +59,28 @@ public struct RDEPUBTextRenderStyle {
     }
 }
 
-// MARK: - 布局配置
-
-/// 分页引擎的布局控制参数。
 public struct RDEPUBTextLayoutConfig: Equatable {
-    /// 页面帧宽度；传 0 时回退为分页入口传入的 pageSize.width
+
     public var frameWidth: CGFloat
-    /// 页面帧高度；传 0 时回退为分页入口传入的 pageSize.height
+
     public var frameHeight: CGFloat
-    /// 页面内容内边距，对标 WXRead 的 WRCoreTextLayoutConfig.edgeInsets
+
     public var edgeInsets: UIEdgeInsets
-    /// 栏数，对标 WXRead 的 numberOfColumns
+
     public var numberOfColumns: Int
-    /// 栏间距，对标 WXRead 的 columnGap
+
     public var columnGap: CGFloat
-    /// 是否避免孤行（段落最后一行单独在下一页顶部）
+
     public var avoidOrphans: Bool
-    /// 是否避免寡行（段落第一行单独在上一页底部）
+
     public var avoidWidows: Bool
-    /// 是否启用 avoidPageBreakInside 保护（对标 WXRead 的行级回退扫描）
+
     public var avoidPageBreakInsideEnabled: Bool
-    /// 是否启用连字符断字，对标 WXRead 的 hyphenation
+
     public var hyphenation: Bool
-    /// 图片最大高度占页面高度的比例
+
     public var imageMaxHeightRatio: CGFloat
-    /// 当调用方暂时拿不到 pageSize 时，用于估算附件尺寸的兜底 viewport。
+
     public var fallbackViewportSize: CGSize
 
     public init(
@@ -129,10 +109,8 @@ public struct RDEPUBTextLayoutConfig: Equatable {
         self.fallbackViewportSize = fallbackViewportSize
     }
 
-    /// 默认配置
     public static let `default` = RDEPUBTextLayoutConfig()
 
-    /// 结合调用方 pageSize 解析后的实际页面尺寸。
     public func resolvedFrameSize(fallback pageSize: CGSize) -> CGSize {
         CGSize(
             width: max(frameWidth > 0 ? frameWidth : pageSize.width, 1),
@@ -140,13 +118,11 @@ public struct RDEPUBTextLayoutConfig: Equatable {
         )
     }
 
-    /// 实际内容区域；对标 WXRead 的 frame + edgeInsets 组合。
     public func contentRect(fallback pageSize: CGSize) -> CGRect {
         let size = resolvedFrameSize(fallback: pageSize)
         return CGRect(origin: .zero, size: size).inset(by: edgeInsets)
     }
 
-    /// 多栏布局时的列矩形数组。
     public func columnRects(fallback pageSize: CGSize) -> [CGRect] {
         let rect = contentRect(fallback: pageSize)
         let columns = max(1, numberOfColumns)
@@ -161,7 +137,6 @@ public struct RDEPUBTextLayoutConfig: Equatable {
         }
     }
 
-    /// 持久化/缓存键使用的稳定签名。
     public var cacheSignature: String {
         [
             String(format: "%.3f", frameWidth),
@@ -183,18 +158,14 @@ public struct RDEPUBTextLayoutConfig: Equatable {
     }
 }
 
-// MARK: - CSS 样式表层级
-
-/// 样式表层级类型，用于 CSS 层叠优先级管理。
 public enum RDEPUBTextStyleSheetLayerKind: String, CaseIterable, Equatable {
-    case `default`  // 基础重置样式（margin、padding 等）
-    case replace    // 元素替换样式（图片居中、标题分页等）
-    case dark       // 暗色模式覆盖
-    case epub       // EPUB 原始样式表
-    case user       // 用户自定义样式（字号、行距、颜色等）
+    case `default`  
+    case replace    
+    case dark       
+    case epub       
+    case user       
 }
 
-/// 单个 CSS 样式表层，包含层级类型和 CSS 内容。
 public struct RDEPUBTextStyleSheetLayer: Equatable {
     public var kind: RDEPUBTextStyleSheetLayerKind
     public var css: String
@@ -205,9 +176,6 @@ public struct RDEPUBTextStyleSheetLayer: Equatable {
     }
 }
 
-/// CSS 样式表包，管理多层 CSS 的合并与注入顺序。
-///
-/// CSS 层叠顺序（从低到高）：default → replace → dark → epub → user
 public struct RDEPUBTextStyleSheetPackage: Equatable {
     public var layers: [RDEPUBTextStyleSheetLayer]
 
@@ -215,7 +183,6 @@ public struct RDEPUBTextStyleSheetPackage: Equatable {
         self.layers = layers
     }
 
-    /// 合并所有非空层的 CSS，每层添加注释头标记
     public var combinedCSS: String {
         layers
             .filter { !$0.css.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty }
@@ -226,15 +193,11 @@ public struct RDEPUBTextStyleSheetPackage: Equatable {
     }
 }
 
-// MARK: - 资源引用诊断
-
-/// 资源引用类型（样式表或图片）
 public enum RDEPUBTextResourceReferenceKind: String, Equatable {
     case stylesheet
     case image
 }
 
-/// 单个资源引用的诊断信息，用于检测 EPUB 中的资源是否正确引用。
 public struct RDEPUBTextResourceReferenceDiagnostic: Equatable {
     public var kind: RDEPUBTextResourceReferenceKind
     public var chapterHref: String
@@ -260,9 +223,6 @@ public struct RDEPUBTextResourceReferenceDiagnostic: Equatable {
     }
 }
 
-// MARK: - 章节渲染上下文与请求
-
-/// 章节渲染上下文：包含 HTML 源码、样式表和资源诊断信息。
 public struct RDEPUBTextChapterContext: Equatable {
     public var href: String
     public var title: String
@@ -270,6 +230,7 @@ public struct RDEPUBTextChapterContext: Equatable {
     public var baseURL: URL?
     public var stylesheet: RDEPUBTextStyleSheetPackage
     public var resourceDiagnostics: [RDEPUBTextResourceReferenceDiagnostic]
+    public var styleCompatibilityReport: RDEPUBCSSCompatibilityReport
 
     public init(
         href: String,
@@ -277,7 +238,8 @@ public struct RDEPUBTextChapterContext: Equatable {
         html: String,
         baseURL: URL?,
         stylesheet: RDEPUBTextStyleSheetPackage,
-        resourceDiagnostics: [RDEPUBTextResourceReferenceDiagnostic]
+        resourceDiagnostics: [RDEPUBTextResourceReferenceDiagnostic],
+        styleCompatibilityReport: RDEPUBCSSCompatibilityReport = RDEPUBCSSCompatibilityReport()
     ) {
         self.href = href
         self.title = title
@@ -285,16 +247,16 @@ public struct RDEPUBTextChapterContext: Equatable {
         self.baseURL = baseURL
         self.stylesheet = stylesheet
         self.resourceDiagnostics = resourceDiagnostics
+        self.styleCompatibilityReport = styleCompatibilityReport
     }
 }
 
-/// 章节渲染请求：打包上下文和渲染样式，传递给 `RDEPUBTextRenderer`。
 public struct RDEPUBTextChapterRenderRequest {
     public var context: RDEPUBTextChapterContext
     public var style: RDEPUBTextRenderStyle
-    /// 当前章节将被分页到的页面尺寸；用于让附件缩放贴近真实 page size。
+
     public var pageSize: CGSize?
-    /// 当前分页布局配置；用于生成与 WXRead 更接近的内容区尺寸。
+
     public var layoutConfig: RDEPUBTextLayoutConfig?
 
     public init(
@@ -310,15 +272,12 @@ public struct RDEPUBTextChapterRenderRequest {
     }
 }
 
-// MARK: - 渲染结果
-
-/// 章节渲染的输出结果，包含富文本、fragment 偏移量和资源诊断。
 public struct RDEPUBRenderedChapterContent {
-    /// 渲染后的富文本
+
     public var attributedString: NSAttributedString
-    /// fragment ID → 字符偏移量映射
+
     public var fragmentOffsets: [String: Int]
-    /// 资源引用诊断列表
+
     public var resourceDiagnostics: [RDEPUBTextResourceReferenceDiagnostic]
 
     public init(
@@ -332,18 +291,12 @@ public struct RDEPUBRenderedChapterContent {
     }
 }
 
-// MARK: - 渲染器协议
-
-/// EPUB 文本渲染器协议，定义 HTML → NSAttributedString 的转换接口。
-///
-/// 默认实现：`RDEPUBDTCoreTextRenderer`（基于 DTCoreText 库）
 public protocol RDEPUBTextRenderer {
-    /// 渲染单个章节
+
     func renderChapter(
         request: RDEPUBTextChapterRenderRequest
     ) throws -> RDEPUBRenderedChapterContent
 
-    /// 便捷方法：直接渲染 HTML 字符串
     func renderChapter(
         html: String,
         baseURL: URL?,
@@ -351,7 +304,6 @@ public protocol RDEPUBTextRenderer {
     ) throws -> RDEPUBRenderedChapterContent
 }
 
-/// 协议默认实现：将便捷方法委托给完整方法
 public extension RDEPUBTextRenderer {
     func renderChapter(
         html: String,
@@ -370,12 +322,9 @@ public extension RDEPUBTextRenderer {
     }
 }
 
-// MARK: - 渲染错误
-
-/// EPUB 文本渲染过程中可能出现的错误类型。
 public enum RDEPUBTextRenderingError: LocalizedError {
-    case htmlEncodingFailed  // HTML 字符串编码为 Data 失败
-    case htmlImportFailed    // HTML 富文本解析失败
+    case htmlEncodingFailed  
+    case htmlImportFailed    
 
     public var errorDescription: String? {
         switch self {

Sources/RDReaderView/EPUBTextRendering/RDEPUBTextSearchEngine.swift

@@ -1,10 +1,5 @@
 import Foundation
 
-/// EPUB 文本搜索引擎：在分页书籍中执行全文搜索。
-///
-/// 实现 `RDEPUBSearchEngine` 协议，遍历所有章节的富文本内容，
-/// 使用大小写不敏感匹配查找关键词，返回搜索结果列表。
-/// 每个搜索结果包含进度位置、预览文本和语义锚点。
 final class RDEPUBTextSearchEngine: RDEPUBSearchEngine {
     private let textBook: RDEPUBTextBook
     private let publication: RDEPUBPublication
@@ -14,14 +9,6 @@ final class RDEPUBTextSearchEngine: RDEPUBSearchEngine {
         self.publication = publication
     }
 
-    /// 在全书中搜索关键词，返回所有匹配结果。
-    ///
-    /// 搜索流程：
-    /// 1. 遍历所有章节
-    /// 2. 在每章的富文本字符串中执行大小写不敏感搜索
-    /// 3. 计算匹配位置的阅读进度（progression）
-    /// 4. 生成预览文本（匹配位置前后各 12 个字符）
-    /// 5. 生成语义锚点（用于跨设备/跨字体精确定位）
     func search(keyword: String) -> [RDEPUBSearchMatch] {
         let normalizedKeyword = keyword.trimmingCharacters(in: .whitespacesAndNewlines)
         guard !normalizedKeyword.isEmpty else {
@@ -49,6 +36,7 @@ final class RDEPUBTextSearchEngine: RDEPUBSearchEngine {
 
                 let progressionDenominator = max(fullLength - 1, 1)
                 let progression = Double(foundRange.location) / Double(progressionDenominator)
+                let rangeAnchor = chapterData.rangeAnchor(for: foundRange)
                 matches.append(
                     RDEPUBSearchMatch(
                         href: normalizedHref,
@@ -57,7 +45,9 @@ final class RDEPUBTextSearchEngine: RDEPUBSearchEngine {
                         localMatchIndex: localMatchIndex,
                         rangeLocation: foundRange.location,
                         rangeLength: foundRange.length,
-                        rangeAnchor: chapterData.rangeAnchor(for: foundRange)
+                        rangeAnchor: rangeAnchor,
+                        cfi: chapterData.indexTable.cfi(for: rangeAnchor.start)?.rawValue,
+                        rangeCFI: chapterData.indexTable.cfiRange(for: rangeAnchor)?.rawValue
                     )
                 )
 
@@ -73,7 +63,6 @@ final class RDEPUBTextSearchEngine: RDEPUBSearchEngine {
         return matches
     }
 
-    /// 生成搜索结果的预览文本：匹配位置前后各取 12 个字符
     private func previewText(in text: NSString, matchRange: NSRange) -> String {
         let previewRadius = 12
         let start = max(matchRange.location - previewRadius, 0)
@@ -82,13 +71,16 @@ final class RDEPUBTextSearchEngine: RDEPUBSearchEngine {
         return text.substring(with: range).trimmingCharacters(in: .whitespacesAndNewlines)
     }
 
-    /// 无 publication 时的搜索（用于 txt 等外部文本文件）
     static func searchWithoutPublication(textBook: RDEPUBTextBook, keyword: String) -> [RDEPUBSearchMatch] {
         let normalizedKeyword = keyword.trimmingCharacters(in: .whitespacesAndNewlines)
         guard !normalizedKeyword.isEmpty else { return [] }
 
         var matches: [RDEPUBSearchMatch] = []
         for chapter in textBook.chapters {
+            let chapterData = RDEPUBChapterData(
+                chapter: chapter,
+                indexTable: RDEPUBTextIndexTable(chapters: [chapter])
+            )
             let source = chapter.attributedContent.string as NSString
             let fullLength = source.length
             guard fullLength > 0 else { continue }
@@ -102,6 +94,9 @@ final class RDEPUBTextSearchEngine: RDEPUBSearchEngine {
 
                 let progressionDenominator = max(fullLength - 1, 1)
                 let progression = Double(foundRange.location) / Double(progressionDenominator)
+                let rangeAnchor = chapterData.rangeAnchor(for: foundRange)
+                let cfi = chapterData.indexTable.cfi(for: rangeAnchor.start)
+                let cfiRange = chapterData.indexTable.cfiRange(for: rangeAnchor)
                 let previewRadius = 12
                 let previewStart = max(foundRange.location - previewRadius, 0)
                 let previewEnd = min(foundRange.location + foundRange.length + previewRadius, fullLength)
@@ -116,7 +111,9 @@ final class RDEPUBTextSearchEngine: RDEPUBSearchEngine {
                         localMatchIndex: localMatchIndex,
                         rangeLocation: foundRange.location,
                         rangeLength: foundRange.length,
-                        rangeAnchor: nil
+                        rangeAnchor: rangeAnchor,
+                        cfi: cfi?.rawValue ?? cfiRange?.start.rawValue,
+                        rangeCFI: cfiRange?.rawValue
                     )
                 )
 

Sources/RDReaderView/EPUBTextRendering/RDPlainTextBookBuilder.swift

@@ -1,16 +1,5 @@
 import UIKit
 
-/// 纯文本书籍构建器：将 TXT 文件构建为 RDEPUBTextBook，复用 EPUB 文本渲染和分页管线。
-///
-/// 本类将纯文本文件（.txt）转换为与 EPUB 相同的分页书籍模型，
-/// 使得纯文本阅读器可以复用 EPUBReader 的分页、导航、搜索等全部功能。
-///
-/// 处理流程：
-/// 1. 解码文本文件（UTF-8 → GB18030 → GBK 兼容编码）
-/// 2. 按中文章节正则拆分为多个章节
-/// 3. 将纯文本包装为 HTML 段落
-/// 4. 通过渲染器（DTCoreText）渲染为富文本
-/// 5. CoreText 分页 → RDEPUBTextBook
 public final class RDPlainTextBookBuilder {
     private let renderer: RDEPUBTextRenderer
     private let layoutConfig: RDEPUBTextLayoutConfig
@@ -23,13 +12,6 @@ public final class RDPlainTextBookBuilder {
         self.layoutConfig = layoutConfig
     }
 
-    /// 从纯文本文件构建分页书籍。
-    ///
-    /// - Parameters:
-    ///   - textFileURL: 纯文本文件的本地 URL
-    ///   - pageSize: 页面尺寸
-    ///   - style: 渲染样式（字体、行距、颜色）
-    /// - Returns: 分页后的书籍模型
     public func build(
         textFileURL: URL,
         pageSize: CGSize,
@@ -109,6 +91,7 @@ public final class RDPlainTextBookBuilder {
                     title: spec.title ?? "第 \(index + 1) 章",
                     attributedContent: chapterAttributedContent,
                     fragmentOffsets: [:],
+                    cfiMap: nil,
                     pageBreakReasons: pages.map { $0.metadata.breakReason },
                     pages: pages
                 )
@@ -119,16 +102,11 @@ public final class RDPlainTextBookBuilder {
         return RDEPUBTextBook(chapters: chapters, pages: flatPages)
     }
 
-    // MARK: - 章节拆分
-
-    /// 章节规格：标题 + 内容
     private struct ChapterSpec {
         let title: String?
         let content: String
     }
 
-    /// 按中文章节正则拆分文本。匹配 "第X章/节/回/卷" 格式，
-    /// 无匹配时将整篇文本作为一章处理。
     private func splitChapters(from text: String) -> [ChapterSpec] {
         let pattern = #"^(第[零一二三四五六七八九十百千万\d]+[章节回卷].*)$"#
         guard let regex = try? NSRegularExpression(pattern: pattern, options: [.anchorsMatchLines]) else {
@@ -154,25 +132,18 @@ public final class RDPlainTextBookBuilder {
             }
         }
 
-        // 拆分结果为空（所有章节内容为空），整体作为一章
         if specs.isEmpty {
             return [ChapterSpec(title: nil, content: text)]
         }
         return specs
     }
 
-    // MARK: - HTML 包装
-
-    /// 将纯文本包装为 HTML 段落：每行一个 `<p>` 标签
     private func wrapTextAsHTML(_ text: String) -> String {
         let paragraphs = text.components(separatedBy: "\n").filter { !$0.isEmpty }
         let body = paragraphs.map { "<p>\($0)</p>" }.joined(separator: "\n")
         return "<html><body>\(body)</body></html>"
     }
 
-    // MARK: - 文本解码
-
-    /// 解码文本文件，按优先级尝试 UTF-8 → GB18030 → GBK 编码
     private func rd_decodeTextFile(url: URL) -> String {
         if let content = try? NSString(contentsOf: url, encoding: String.Encoding.utf8.rawValue) as String {
             return content

Sources/RDReaderView/EPUBTextRendering/Typesetter/Compatibility/RDEPUBCSSCompatibilityLayer.swift

@@ -0,0 +1,136 @@
+import Foundation
+
+struct RDEPUBCSSCompatibilityLayer {
+
+    var policy = RDEPUBStyleCompatibilityPolicy()
+
+    func sanitize(_ css: String) -> RDEPUBCSSCompatibilityResult {
+        var rewritten = css
+        var normalized: [String] = []
+        var unsupported: [String] = []
+
+        if policy.normalizeLineHeight {
+            let result = clampNumericProperty(
+                in: rewritten,
+                property: "line-height",
+                minValue: 0.9,
+                maxValue: 2.4
+            )
+            rewritten = result.css
+            normalized += result.normalizedRules
+        }
+
+        if policy.normalizeTextIndent {
+            let result = clampLengthProperty(
+                in: rewritten,
+                property: "text-indent",
+                maxAbsolutePX: 64
+            )
+            rewritten = result.css
+            normalized += result.normalizedRules
+        }
+
+        if !policy.allowPublisherMargins {
+            let result = clampLengthProperty(
+                in: rewritten,
+                property: "margin",
+                maxAbsolutePX: 64
+            )
+            rewritten = result.css
+            normalized += result.normalizedRules
+        }
+
+        if policy.fallbackUnsupportedWritingModes,
+           rewritten.range(of: "writing-mode", options: [.caseInsensitive]) != nil {
+            unsupported.append("writing-mode")
+            rewritten += "\n\nhtml, body { writing-mode: horizontal-tb !important; }"
+            normalized.append("writing-mode")
+        }
+
+        if policy.clampImagesToViewport {
+            rewritten += """
+
+            img, svg, table, video, canvas {
+              max-width: 100% !important;
+              height: auto !important;
+              box-sizing: border-box !important;
+            }
+            table {
+              overflow-wrap: anywhere;
+              border-collapse: collapse;
+            }
+            """
+            normalized.append("media-size-clamp")
+        }
+
+        return RDEPUBCSSCompatibilityResult(
+            css: rewritten,
+            report: RDEPUBCSSCompatibilityReport(
+                unsupportedRules: unsupported,
+                normalizedRules: normalized,
+                fontFailures: []
+            )
+        )
+    }
+
+    private func clampNumericProperty(
+        in css: String,
+        property: String,
+        minValue: Double,
+        maxValue: Double
+    ) -> (css: String, normalizedRules: [String]) {
+        guard let regex = try? NSRegularExpression(
+            pattern: #"(?i)\b"# + NSRegularExpression.escapedPattern(for: property) + #"\s*:\s*([0-9]*\.?[0-9]+)\s*;"#
+        ) else {
+            return (css, [])
+        }
+
+        let nsCSS = css as NSString
+        var rewritten = css
+        var normalized: [String] = []
+
+        for match in regex.matches(in: css, range: NSRange(location: 0, length: nsCSS.length)).reversed() {
+            guard match.numberOfRanges > 1 else { continue }
+            let rawValue = nsCSS.substring(with: match.range(at: 1))
+
+            guard let value = Double(rawValue), value < minValue || value > maxValue else { continue }
+
+            let clamped = min(max(value, minValue), maxValue)
+            if let range = Range(match.range, in: rewritten) {
+                rewritten.replaceSubrange(range, with: "\(property): \(String(format: "%.3f", clamped));")
+                normalized.append(property)
+            }
+        }
+        return (rewritten, normalized)
+    }
+
+    private func clampLengthProperty(
+        in css: String,
+        property: String,
+        maxAbsolutePX: Double
+    ) -> (css: String, normalizedRules: [String]) {
+        guard let regex = try? NSRegularExpression(
+            pattern: #"(?i)\b"# + NSRegularExpression.escapedPattern(for: property) + #"\s*:\s*(-?[0-9]*\.?[0-9]+)px\s*;"#
+        ) else {
+            return (css, [])
+        }
+
+        let nsCSS = css as NSString
+        var rewritten = css
+        var normalized: [String] = []
+
+        for match in regex.matches(in: css, range: NSRange(location: 0, length: nsCSS.length)).reversed() {
+            guard match.numberOfRanges > 1 else { continue }
+            let rawValue = nsCSS.substring(with: match.range(at: 1))
+
+            guard let value = Double(rawValue), abs(value) > maxAbsolutePX else { continue }
+
+            let clamped = value < 0 ? -maxAbsolutePX : maxAbsolutePX
+            if let range = Range(match.range, in: rewritten) {
+                rewritten.replaceSubrange(range, with: "\(property): \(String(format: "%.0f", clamped))px;")
+                normalized.append(property)
+            }
+        }
+        return (rewritten, normalized)
+    }
+}

Sources/RDReaderView/EPUBTextRendering/Typesetter/Compatibility/RDEPUBFontFallbackResolver.swift

@@ -0,0 +1,21 @@
+import UIKit
+
+struct RDEPUBFontFallbackResolver {
+
+    static func fallbackChain(requestedFamily: String?, embeddedFamily: String?) -> RDEPUBFontFallbackChain {
+
+        let preferredCJK = ["PingFang SC", "Heiti SC", "Songti SC"]
+
+        let preferredLatin = ["Times New Roman", "Georgia", "Helvetica Neue"]
+        return RDEPUBFontFallbackChain(
+            requestedFamily: requestedFamily,
+            embeddedFamily: embeddedFamily,
+            systemFallbacks: preferredCJK + preferredLatin,
+            finalFallback: UIFont.systemFont(ofSize: UIFont.systemFontSize).familyName
+        )
+    }
+
+    static func resolveFont(sourceFont: UIFont?, baseFont: UIFont) -> UIFont {
+        RDEPUBFontNormalizer.normalizedFont(from: sourceFont, baseFont: baseFont)
+    }
+}

Sources/RDReaderView/EPUBTextRendering/Typesetter/Compatibility/RDEPUBStyleCompatibilityModels.swift

@@ -0,0 +1,101 @@
+import Foundation
+
+public struct RDEPUBStyleCompatibilityPolicy: Equatable {
+
+    public var allowPublisherFonts: Bool
+
+    public var allowPublisherMargins: Bool
+
+    public var normalizeLineHeight: Bool
+
+    public var normalizeTextIndent: Bool
+
+    public var clampImagesToViewport: Bool
+
+    public var fallbackUnsupportedWritingModes: Bool
+
+    public init(
+        allowPublisherFonts: Bool = true,
+        allowPublisherMargins: Bool = true,
+        normalizeLineHeight: Bool = true,
+        normalizeTextIndent: Bool = true,
+        clampImagesToViewport: Bool = true,
+        fallbackUnsupportedWritingModes: Bool = true
+    ) {
+        self.allowPublisherFonts = allowPublisherFonts
+        self.allowPublisherMargins = allowPublisherMargins
+        self.normalizeLineHeight = normalizeLineHeight
+        self.normalizeTextIndent = normalizeTextIndent
+        self.clampImagesToViewport = clampImagesToViewport
+        self.fallbackUnsupportedWritingModes = fallbackUnsupportedWritingModes
+    }
+}
+
+public struct RDEPUBFontFallbackChain: Codable, Equatable {
+
+    public var requestedFamily: String?
+
+    public var embeddedFamily: String?
+
+    public var systemFallbacks: [String]
+
+    public var finalFallback: String
+
+    public init(
+        requestedFamily: String? = nil,
+        embeddedFamily: String? = nil,
+        systemFallbacks: [String] = ["PingFang SC", "Heiti SC", "Times New Roman"],
+        finalFallback: String = ".AppleSystemUIFont"
+    ) {
+        self.requestedFamily = requestedFamily
+        self.embeddedFamily = embeddedFamily
+        self.systemFallbacks = systemFallbacks
+        self.finalFallback = finalFallback
+    }
+}
+
+public struct RDEPUBEmbeddedFontDescriptor: Codable, Equatable {
+
+    public var family: String?
+
+    public var href: String
+
+    public var format: String?
+
+    public var weight: Int?
+
+    public var style: String?
+}
+
+public struct RDEPUBFontRegistrationResult: Codable, Equatable {
+
+    public var descriptor: RDEPUBEmbeddedFontDescriptor
+
+    public var fileURL: URL?
+
+    public var didRegister: Bool
+
+    public var errorDescription: String?
+}
+
+public struct RDEPUBCSSCompatibilityReport: Codable, Equatable {
+
+    public var unsupportedRules: [String]
+
+    public var normalizedRules: [String]
+
+    public var fontFailures: [String]
+
+    public init(unsupportedRules: [String] = [], normalizedRules: [String] = [], fontFailures: [String] = []) {
+        self.unsupportedRules = unsupportedRules
+        self.normalizedRules = normalizedRules
+        self.fontFailures = fontFailures
+    }
+}
+
+struct RDEPUBCSSCompatibilityResult {
+
+    var css: String
+
+    var report: RDEPUBCSSCompatibilityReport
+}

Sources/RDReaderView/EPUBTextRendering/Typesetter/RDEPUBAttachmentNormalizer.swift

@@ -4,14 +4,14 @@ import UIKit
 import DTCoreText
 #endif
 
-/// 附件布局规范化器，负责缩放脚注、封面和通用图片的显示尺寸。
 struct RDEPUBAttachmentNormalizer {
-    /// 脚注附件日志已输出标记（避免重复日志）
+
     private static var didLogFootnoteAttachment = false
-    /// 封面附件日志已输出标记（避免重复日志）
+
     private static var didLogCoverAttachment = false
 
 #if canImport(DTCoreText)
+
     func normalize(
         _ attachment: DTTextAttachment,
         fontPointSize: CGFloat,
@@ -25,23 +25,28 @@ struct RDEPUBAttachmentNormalizer {
     }
 #endif
 
-    // MARK: - DTCoreText 附件布局规范化
-
 #if canImport(DTCoreText)
-    /// 对 DTTextAttachment 做尺寸规范化：脚注缩放、封面缩放、通用图片缩放。
+
     static func normalizeAttachmentLayoutForWXRead(
         _ attachment: DTTextAttachment,
         fontPointSize: CGFloat,
         maxImageSize: CGSize? = nil
     ) {
+
         let pointSize = max(fontPointSize, 1)
+
         let originalSize = attachment.originalSize
 
         if isFootnoteAttachment(attachment) {
+
             let targetWidth = max(round(pointSize), 1)
+
             let aspectRatio = originalSize.height > 0 ? originalSize.width / originalSize.height : 1
+
             let targetHeight = max(round(targetWidth / max(aspectRatio, 0.1)), 1)
+
             attachment.displaySize = CGSize(width: targetWidth, height: targetHeight)
+
             attachment.verticalAlignment = .baseline
 
             if !didLogFootnoteAttachment {
@@ -54,16 +59,20 @@ struct RDEPUBAttachmentNormalizer {
         }
 
         if isCoverAttachment(attachment) {
+
             let maxSize = maxImageSize ?? defaultMaxImageSize(fontPointSize: pointSize)
             if originalSize.width > 0, originalSize.height > 0 {
+
                 let scale = min(maxSize.width / originalSize.width, maxSize.height / originalSize.height)
                 attachment.displaySize = CGSize(
                     width: round(originalSize.width * scale),
                     height: round(originalSize.height * scale)
                 )
             } else {
+
                 attachment.displaySize = maxSize
             }
+
             attachment.verticalAlignment = .baseline
 
             if !didLogCoverAttachment {
@@ -76,9 +85,11 @@ struct RDEPUBAttachmentNormalizer {
         }
 
         var resolvedSize = attachment.displaySize
+
         if resolvedSize.width <= 0 || resolvedSize.height <= 0 {
             resolvedSize = originalSize
         }
+
         if resolvedSize.width <= 0 || resolvedSize.height <= 0 {
             resolvedSize = CGSize(width: pointSize, height: pointSize)
         }
@@ -87,6 +98,7 @@ struct RDEPUBAttachmentNormalizer {
            resolvedSize.width > 0,
            resolvedSize.height > 0,
            (resolvedSize.width > maxImageSize.width || resolvedSize.height > maxImageSize.height) {
+
             let scale = min(maxImageSize.width / resolvedSize.width, maxImageSize.height / resolvedSize.height)
             resolvedSize = CGSize(
                 width: round(resolvedSize.width * scale),
@@ -95,26 +107,31 @@ struct RDEPUBAttachmentNormalizer {
         }
 
         attachment.displaySize = CGSize(width: round(resolvedSize.width), height: round(resolvedSize.height))
+
         attachment.verticalAlignment = .center
     }
 
-    /// DTCoreText 元素配置：在 willFlushCallback 中调用。
     static func prepareHTMLElementForReaderRendering(
         _ element: DTHTMLElement,
         style: RDEPUBTextRenderStyle,
         maxImageSize: CGSize? = nil
     ) {
+
         guard let attachment = element.textAttachment else { return }
+
         let pointSize = max(element.fontDescriptor.pointSize, style.font.pointSize)
+
         let fallbackSize = CGSize(
             width: defaultMaxImageSize(fontPointSize: pointSize).width,
             height: defaultMaxImageSize(fontPointSize: pointSize).height
         )
+
         normalizeAttachmentLayoutForWXRead(
             attachment,
             fontPointSize: pointSize,
             maxImageSize: maxImageSize ?? fallbackSize
         )
+
         if isFootnoteAttachment(attachment) {
             element.displayStyle = .inline
         } else if isCoverAttachment(attachment) {
@@ -123,23 +140,31 @@ struct RDEPUBAttachmentNormalizer {
     }
 
     private static func isFootnoteAttachment(_ attachment: DTTextAttachment) -> Bool {
+
         let lowercasedClasses = ((attachment.attributes["class"] as? String) ?? "").lowercased()
+
         let lowercasedPath = attachment.contentURL?.lastPathComponent.lowercased()
             ?? ((attachment.attributes["src"] as? String) ?? "").lowercased()
         return lowercasedClasses.contains("qqreader-footnote") || lowercasedPath == "note.png"
     }
 
     private static func isCoverAttachment(_ attachment: DTTextAttachment) -> Bool {
+
         let lowercasedClasses = ((attachment.attributes["class"] as? String) ?? "").lowercased()
+
         let lowercasedPath = attachment.contentURL?.lastPathComponent.lowercased()
             ?? ((attachment.attributes["src"] as? String) ?? "").lowercased()
         return lowercasedClasses.contains("rd-front-cover-image") || lowercasedPath == "cover.jpg"
     }
 
     private static func defaultMaxImageSize(fontPointSize: CGFloat) -> CGSize {
+
         let referenceViewport = CGSize(width: 375, height: 667)
+
         let horizontalInset = max(round(fontPointSize), 16)
+
         let verticalInset = max(round(fontPointSize * 1.5), 28)
+
         return CGSize(
             width: max(round(referenceViewport.width - horizontalInset * 2), 1),
             height: max(round((referenceViewport.height - verticalInset * 2) * 0.85), 1)
@@ -147,16 +172,15 @@ struct RDEPUBAttachmentNormalizer {
     }
 #endif
 
-    // MARK: - 通用附件规范化
-
-    /// 规范化 NSAttributedString 中附件的显示尺寸。
     static func normalizeAttachmentDisplayIfNeeded(
         in attributes: inout [NSAttributedString.Key: Any],
         font: UIFont
     ) {
+
         guard let attachment = attributes[.attachment] else { return }
 
 #if canImport(DTCoreText)
+
         if let textAttachment = attachment as? DTTextAttachment {
             normalizeAttachmentLayoutForWXRead(textAttachment, fontPointSize: font.pointSize)
             attributes[.attachment] = textAttachment
@@ -165,15 +189,17 @@ struct RDEPUBAttachmentNormalizer {
 #endif
 
         if let textAttachment = attachment as? NSTextAttachment, textAttachment.bounds.height <= 0 {
+
             let targetHeight = max(round(font.pointSize * 0.86), 1)
             textAttachment.bounds = CGRect(x: 0, y: 0, width: targetHeight, height: targetHeight)
             attributes[.attachment] = textAttachment
         }
     }
 
-    /// 推断附件类型。
     static func attachmentKind(for attributes: [NSAttributedString.Key: Any]) -> RDEPUBTextAttachmentKind? {
+
         if let attachment = attributes[.attachment] as? NSTextAttachment {
+
             if attachment.image != nil || attachment.fileType?.lowercased().contains("image") == true {
                 return .image
             }
@@ -182,6 +208,7 @@ struct RDEPUBAttachmentNormalizer {
 
         for value in attributes.values {
             let typeName = String(describing: type(of: value)).lowercased()
+
             if typeName.contains("attachment") {
                 return typeName.contains("image") ? .image : .generic
             }

Sources/RDReaderView/EPUBTextRendering/Typesetter/RDEPUBCFIMarkerInjector.swift

@@ -0,0 +1,59 @@
+import Foundation
+
+struct RDEPUBCFIMarkerInjector: RDEPUBTypesettingStage {
+
+    func process(_ html: String, context: RDEPUBTypesettingInput) -> String {
+
+        guard let regex = try? NSRegularExpression(
+            pattern: #"<([A-Za-z][A-Za-z0-9:_-]*)([^>]*\s(?:id|xml:id)\s*=\s*['"]([^'"]+)['"][^>]*)>"#,
+            options: [.caseInsensitive]
+        ) else {
+            return html
+        }
+
+        let nsHTML = html as NSString
+
+        let matches = regex.matches(in: html, range: NSRange(location: 0, length: nsHTML.length))
+        guard !matches.isEmpty else { return html }
+
+        var rewritten = html
+        for match in matches.reversed() {
+
+            guard match.numberOfRanges > 3,
+                  let fullRange = Range(match.range(at: 0), in: rewritten),
+                  let tagNameRange = Range(match.range(at: 1), in: html),
+                  let attributesRange = Range(match.range(at: 2), in: html),
+                  let fragmentRange = Range(match.range(at: 3), in: html) else {
+                continue
+            }
+
+            let tagName = String(html[tagNameRange])
+            let attributes = String(html[attributesRange])
+            let fragmentID = String(html[fragmentRange])
+
+            guard attributes.range(of: "data-rd-cfi-marker", options: [.caseInsensitive]) == nil else {
+                continue
+            }
+
+            let marker = RDEPUBCFIGenerator.makeOffsetCFI(
+                href: context.href,
+                fileIndex: context.spineIndex ?? 0,
+                chapterOffset: 0,
+                fragmentID: fragmentID
+            ).rawValue
+
+            let replacement = "<\(tagName)\(attributes) data-rd-cfi-marker=\"\(Self.escapeAttribute(marker))\">"
+            rewritten.replaceSubrange(fullRange, with: replacement)
+        }
+
+        return rewritten
+    }
+
+    private static func escapeAttribute(_ value: String) -> String {
+        value
+            .replacingOccurrences(of: "&", with: "&amp;")
+            .replacingOccurrences(of: "\"", with: "&quot;")
+            .replacingOccurrences(of: "<", with: "&lt;")
+            .replacingOccurrences(of: ">", with: "&gt;")
+    }
+}

Sources/RDReaderView/EPUBTextRendering/Typesetter/RDEPUBFontNormalizer.swift

@@ -1,16 +1,18 @@
 import UIKit
+
 import CoreText
 
-/// 字体规范化器，负责注册 EPUB 嵌入字体并映射到用户设置字体。
 struct RDEPUBFontNormalizer {
-    /// 已注册字体资源，避免重复调用 CTFontManager。
+
     private static var registeredFontPaths = Set<String>()
 
+    @discardableResult
     func registerEmbeddedFonts(
         html: String,
         inlinedCSS: String,
         input: RDEPUBTypesettingInput
-    ) {
+    ) -> [RDEPUBFontRegistrationResult] {
+
         Self.registerEmbeddedFonts(
             in: inlinedCSS + "\n" + Self.inlineStyleCSS(in: html),
             chapterHref: input.href,
@@ -18,70 +20,119 @@ struct RDEPUBFontNormalizer {
         )
     }
 
-    // MARK: - 字体注册
-
-    /// 从 CSS 中解析 @font-face 规则，注册嵌入字体。
+    @discardableResult
     static func registerEmbeddedFonts(
         in css: String,
         chapterHref: String,
         resourceResolver: RDEPUBResourceResolver?
-    ) {
+    ) -> [RDEPUBFontRegistrationResult] {
+
         guard let resourceResolver,
+
               let faceRegex = try? NSRegularExpression(pattern: #"@font-face\s*\{([\s\S]*?)\}"#, options: [.caseInsensitive]),
+
               let urlRegex = try? NSRegularExpression(pattern: #"url\(([^)]+)\)"#, options: [.caseInsensitive]) else {
-            return
+            return []
         }
 
+        var results: [RDEPUBFontRegistrationResult] = []
         let nsCSS = css as NSString
+
         for faceMatch in faceRegex.matches(in: css, range: NSRange(location: 0, length: nsCSS.length)) {
             guard faceMatch.numberOfRanges > 1 else { continue }
+
             let block = nsCSS.substring(with: faceMatch.range(at: 1))
             let nsBlock = block as NSString
+
+            let family = declarationValue(named: "font-family", in: block)?
+                .trimmingCharacters(in: CharacterSet(charactersIn: "\"'"))
+
+            let weight = declarationValue(named: "font-weight", in: block).flatMap(Int.init)
+
+            let style = declarationValue(named: "font-style", in: block)
+
             for urlMatch in urlRegex.matches(in: block, range: NSRange(location: 0, length: nsBlock.length)) {
                 guard urlMatch.numberOfRanges > 1 else { continue }
+
                 let rawReference = nsBlock.substring(with: urlMatch.range(at: 1))
                     .trimmingCharacters(in: CharacterSet(charactersIn: "\"' \n\r\t"))
+
+                let descriptor = RDEPUBEmbeddedFontDescriptor(
+                    family: family,
+                    href: rawReference,
+                    format: nil,
+                    weight: weight,
+                    style: style
+                )
+
                 guard !rawReference.isEmpty,
                       !rawReference.hasPrefix("data:"),
-                      !rawReference.hasPrefix("http://"),
-                      !rawReference.hasPrefix("https://"),
+                      !rawReference.hasPrefix("http:"),
+                      !rawReference.hasPrefix("https:"),
+
                       let fileURL = resourceResolver.fileURL(forReference: rawReference, relativeToHref: chapterHref) else {
+
+                    results.append(
+                        RDEPUBFontRegistrationResult(
+                            descriptor: descriptor,
+                            fileURL: nil,
+                            didRegister: false,
+                            errorDescription: "Font URL could not be resolved"
+                        )
+                    )
                     continue
                 }
-                registerFontIfNeeded(at: fileURL)
+
+                let didRegister = registerFontIfNeeded(at: fileURL)
+                results.append(
+                    RDEPUBFontRegistrationResult(
+                        descriptor: descriptor,
+                        fileURL: fileURL,
+                        didRegister: didRegister,
+                        errorDescription: didRegister ? nil : "Font was already registered or registration failed"
+                    )
+                )
             }
         }
+        return results
     }
 
-    /// 若字体尚未注册，则通过 CTFontManager 注册。
-    /// - Parameter fileURL: 字体文件 URL
-    static func registerFontIfNeeded(at fileURL: URL) {
+    @discardableResult
+    static func registerFontIfNeeded(at fileURL: URL) -> Bool {
+
         let standardizedPath = fileURL.standardizedFileURL.path
-        guard !registeredFontPaths.contains(standardizedPath) else { return }
-        CTFontManagerRegisterFontsForURL(fileURL as CFURL, .process, nil)
-        registeredFontPaths.insert(standardizedPath)
+
+        guard !registeredFontPaths.contains(standardizedPath) else { return true }
+
+        let registered = CTFontManagerRegisterFontsForURL(fileURL as CFURL, .process, nil)
+        if registered {
+
+            registeredFontPaths.insert(standardizedPath)
+        }
+        return registered
     }
 
-    // MARK: - 字体标准化
-
-    /// 将 EPUB 原始字体映射到用户设置字体，保留粗体/斜体特征。
     static func normalizedFont(from sourceFont: UIFont?, baseFont: UIFont) -> UIFont {
         guard let sourceFont else {
             return baseFont
         }
+
         let traits = sourceFont.fontDescriptor.symbolicTraits.intersection([.traitBold, .traitItalic])
+
         if let descriptor = baseFont.fontDescriptor.withSymbolicTraits(traits) {
             return UIFont(descriptor: descriptor, size: baseFont.pointSize)
         }
+
         return baseFont
     }
 
-    /// 提取 HTML 中内联 <style> 块的 CSS 内容。
     static func inlineStyleCSS(in html: String) -> String {
+
         guard let regex = try? NSRegularExpression(pattern: #"<style\b[^>]*>([\s\S]*?)</style>"#, options: [.caseInsensitive]) else {
             return ""
         }
         let nsHTML = html as NSString
+
         return regex.matches(in: html, range: NSRange(location: 0, length: nsHTML.length))
             .compactMap { match in
                 guard match.numberOfRanges > 1 else { return nil }
@@ -89,4 +140,21 @@ struct RDEPUBFontNormalizer {
             }
             .joined(separator: "\n")
     }
+
+    private static func declarationValue(named name: String, in block: String) -> String? {
+
+        guard let regex = try? NSRegularExpression(
+            pattern: #"(?i)\b"# + NSRegularExpression.escapedPattern(for: name) + #"\s*:\s*([^;]+)"#
+        ) else {
+            return nil
+        }
+        let nsBlock = block as NSString
+
+        guard let match = regex.firstMatch(in: block, range: NSRange(location: 0, length: nsBlock.length)),
+              match.numberOfRanges > 1 else {
+            return nil
+        }
+
+        return nsBlock.substring(with: match.range(at: 1)).trimmingCharacters(in: .whitespacesAndNewlines)
+    }
 }

Sources/RDReaderView/EPUBTextRendering/Typesetter/RDEPUBFragmentMarkerInjector.swift

@@ -1,26 +1,16 @@
-/// RDEPUBFragmentMarkerInjector - Fragment 标记注入与偏移量提取
+
 import Foundation
 
-/// Fragment 标记注入器，负责在 HTML 中注入 fragment 锚点标记并从渲染结果中提取偏移量。
-///
-/// 工作流程：
-/// 1. `process` 阶段：将 HTML 中的 `id` 属性元素转为 `${id=xxx}` 文本标记
-/// 2. `extractOffsets` 阶段：从 NSAttributedString 中扫描标记，记录偏移量后删除标记
 struct RDEPUBFragmentMarkerInjector: RDEPUBTypesettingStage {
-    /// 将 HTML 中的 id 元素注入 fragment 文本标记，供后续偏移量提取使用。
+
     func process(_ html: String, context: RDEPUBTypesettingInput) -> String {
         Self.injectFragmentMarkers(into: html)
     }
 
-    /// 从渲染后的富文本中扫描 `${id=xxx}` 标记，提取 fragment ID 到字符偏移量的映射。
     func extractOffsets(from attributedString: NSMutableAttributedString) -> [String: Int] {
         Self.extractFragmentOffsets(from: attributedString)
     }
 
-    // MARK: - Fragment 标记注入
-
-    /// 将 HTML 中的 id 属性元素注入 fragment 标记。
-    /// `<tag id="xxx" ...>` → `${id=xxx}<tag id="xxx" ...>`
     static func injectFragmentMarkers(into html: String) -> String {
         guard let regex = try? NSRegularExpression(pattern: #"(<[^>]+\sid="([^"]+)"[^>]*>)"#, options: [.caseInsensitive]) else {
             return html
@@ -33,32 +23,43 @@ struct RDEPUBFragmentMarkerInjector: RDEPUBTypesettingStage {
         )
     }
 
-    // MARK: - Fragment 偏移量提取
+    
 
-    /// 从渲染后的富文本中提取 fragment 偏移量映射。
-    /// 扫描 `${id=xxx}` 标记，记录偏移量，然后删除标记文本。
+    
+    
     static func extractFragmentOffsets(from attributedString: NSMutableAttributedString) -> [String: Int] {
+        
         let markerPattern = #"\$\{id=([^}]+)\}"#
         guard let regex = try? NSRegularExpression(pattern: markerPattern, options: []) else {
             return [:]
         }
 
+        
         let mutableString = NSMutableString(string: attributedString.string)
+        
         var fragmentOffsets: [String: Int] = [:]
+        
         var searchRange = NSRange(location: 0, length: mutableString.length)
+        
         var offsetAdjustment = 0
 
+        
         while let match = regex.firstMatch(in: mutableString as String, options: [], range: searchRange) {
+            
             let fullMatch = mutableString.substring(with: match.range) as NSString
             let fragmentID = fullMatch
                 .replacingOccurrences(of: #"\$\{id="#, with: "", options: .regularExpression, range: NSRange(location: 0, length: fullMatch.length))
                 .replacingOccurrences(of: #"\}"#, with: "", options: .regularExpression)
 
             let adjustedLocation = max(0, match.range.location + offsetAdjustment)
+
             fragmentOffsets[fragmentID] = adjustedLocation
+
             attributedString.deleteCharacters(in: match.range)
             mutableString.deleteCharacters(in: match.range)
+
             offsetAdjustment -= match.range.length
+
             searchRange = NSRange(location: match.range.location, length: mutableString.length - match.range.location)
         }
 

Sources/RDReaderView/EPUBTextRendering/Typesetter/RDEPUBHTMLNormalizer.swift

@@ -1,25 +1,18 @@
 import Foundation
 
-/// HTML 规范化器，清理冗余字符并规范化附件 HTML 标记。
 struct RDEPUBHTMLNormalizer: RDEPUBTypesettingStage {
-    /// 执行 HTML 规范化处理。
-    /// - Parameters:
-    ///   - html: 原始 HTML
-    ///   - context: 排版上下文
-    /// - Returns: 规范化后的 HTML
+
     func process(_ html: String, context: RDEPUBTypesettingInput) -> String {
         Self.normalizeHTML(html)
     }
 
-    // MARK: - HTML 规范化入口
-
-    /// 清理冗余字符（CR、多余换行），规范化附件 HTML 标记。
     static func normalizeHTML(_ html: String) -> String {
         var cleanedHTML = html
+
         let replacements: [(pattern: String, template: String)] = [
-            (#"<hr\s+lang="zh-CN">分页符</hr>"#, ""),
-            (#"\r"#, "\n"),
-            (#"\n+"#, "\n")
+            (#"<hr\s+lang="zh-CN">分页符</hr>"#, ""),   
+            (#"\r"#, "\n"),                               
+            (#"\n+"#, "\n")                               
         ]
 
         for replacement in replacements {
@@ -37,9 +30,6 @@ struct RDEPUBHTMLNormalizer: RDEPUBTypesettingStage {
         return cleanedHTML
     }
 
-    // MARK: - 附件 HTML 标记规范化
-
-    /// 处理 bodyPic div、脚注 img、封面 h1+img 等特殊 HTML 结构。
     private static func normalizeAttachmentHTMLMarkers(in html: String) -> String {
         var normalized = html
 
@@ -51,10 +41,12 @@ struct RDEPUBHTMLNormalizer: RDEPUBTypesettingStage {
                 using: bodyPicContainerRegex,
                 in: normalized
             ) { tag in
+                
                 guard let imageTagRegex = try? NSRegularExpression(pattern: #"<img\b[^>]*>"#, options: [.caseInsensitive]) else {
                     return tag
                 }
 
+                
                 return replaceMatches(
                     using: imageTagRegex,
                     in: tag
@@ -75,6 +67,7 @@ struct RDEPUBHTMLNormalizer: RDEPUBTypesettingStage {
             }
         }
 
+        
         if let footnoteRegex = try? NSRegularExpression(
             pattern: #"<img\b([^>]*class\s*=\s*["'][^"']*\bqqreader-footnote\b[^"']*["'][^>]*)>"#,
             options: [.caseInsensitive]
@@ -83,6 +76,7 @@ struct RDEPUBHTMLNormalizer: RDEPUBTypesettingStage {
                 using: footnoteRegex,
                 in: normalized
             ) { tag in
+                
                 mergeHTMLAttributes(
                     into: tag,
                     requiredClass: nil,
@@ -96,6 +90,7 @@ struct RDEPUBHTMLNormalizer: RDEPUBTypesettingStage {
             }
         }
 
+        
         if let coverRegex = try? NSRegularExpression(
             pattern: #"<h1\b([^>]*class\s*=\s*["'][^"']*\bfrontCover\b[^"']*["'][^>]*)>\s*(<img\b[^>]*>)\s*</h1>"#,
             options: [.caseInsensitive]
@@ -104,6 +99,7 @@ struct RDEPUBHTMLNormalizer: RDEPUBTypesettingStage {
                 using: coverRegex,
                 in: normalized
             ) { tag in
+
                 guard let imageTagRegex = try? NSRegularExpression(pattern: #"<img\b[^>]*>"#, options: [.caseInsensitive]),
                       let imageMatch = imageTagRegex.firstMatch(
                         in: tag,
@@ -133,15 +129,13 @@ struct RDEPUBHTMLNormalizer: RDEPUBTypesettingStage {
         return normalized
     }
 
-    // MARK: - HTML 工具方法
-
-    /// 通用反向正则替换：遍历所有匹配，对每个匹配的原始文本调用 transform。
     static func replaceMatches(
         using regex: NSRegularExpression,
         in source: String,
         transform: (String) -> String
     ) -> String {
         let nsSource = source as NSString
+
         let matches = regex.matches(in: source, options: [], range: NSRange(location: 0, length: nsSource.length))
         guard !matches.isEmpty else { return source }
 
@@ -154,7 +148,6 @@ struct RDEPUBHTMLNormalizer: RDEPUBTypesettingStage {
         return rewritten
     }
 
-    /// 合并 HTML 标签的 class 和 style 属性。
     static func mergeHTMLAttributes(
         into tag: String,
         requiredClass: String?,
@@ -194,7 +187,6 @@ struct RDEPUBHTMLNormalizer: RDEPUBTypesettingStage {
         return rewritten
     }
 
-    /// 注入 `<base>` 标签以解析相对路径。
     static func injectBaseHref(into html: String, baseURL: URL?) -> String {
         guard let baseURL else {
             return html
@@ -213,7 +205,6 @@ struct RDEPUBHTMLNormalizer: RDEPUBTypesettingStage {
         return "<head>\n\(baseTag)\n</head>\n" + html
     }
 
-    /// 工具方法：从字符串范围构建 CGSize 描述。
     static func string(from size: CGSize) -> String {
         "{\(Int(round(size.width))), \(Int(round(size.height)))}"
     }

Sources/RDReaderView/EPUBTextRendering/Typesetter/RDEPUBRenderDiagnosticsCollector.swift

@@ -1,17 +1,16 @@
 import Foundation
 
-/// 渲染诊断收集器，扫描 HTML 中的资源引用并生成诊断信息。
 struct RDEPUBRenderDiagnosticsCollector {
-    /// 外部样式表链接正则
+
     private static let stylesheetLinkPattern = #"<link\b[^>]*rel\s*=\s*["'][^"']*stylesheet[^"']*["'][^>]*href\s*=\s*["']([^"']+)["'][^>]*>"#
-    /// 图片源地址正则
+    
     private static let imageSourcePattern = #"<img\b[^>]*src\s*=\s*["']([^"']+)["'][^>]*>"#
 
-    /// 收集 HTML 中图片资源的引用诊断。
-    /// - Parameters:
-    ///   - html: 待扫描的 HTML
-    ///   - input: 排版输入上下文
-    /// - Returns: 资源引用诊断列表
+    
+    
+    
+    
+    
     func collect(
         in html: String,
         input: RDEPUBTypesettingInput
@@ -24,9 +23,9 @@ struct RDEPUBRenderDiagnosticsCollector {
         )
     }
 
-    // MARK: - 图片诊断
+    
 
-    /// 扫描 HTML 中的 <img> 标签，构建资源引用诊断。
+    
     static func collectImageDiagnostics(
         in html: String,
         chapterHref: String,
@@ -50,9 +49,9 @@ struct RDEPUBRenderDiagnosticsCollector {
         }
     }
 
-    // MARK: - 外部样式表内联
+    
 
-    /// 查找 `<link rel=stylesheet>` 标签，内联 CSS 内容。
+    
     static func inlineLinkedStyleSheets(
         in html: String,
         chapterHref: String,
@@ -69,10 +68,14 @@ struct RDEPUBRenderDiagnosticsCollector {
             return (html, "", [])
         }
 
+        
         var rewrittenHTML = html
+        
         var inlinedCSSBlocks: [String] = []
+        
         var diagnostics: [RDEPUBTextResourceReferenceDiagnostic] = []
 
+        
         for match in matches.reversed() {
             guard match.numberOfRanges > 1 else { continue }
             let href = nsHTML.substring(with: match.range(at: 1))
@@ -103,9 +106,9 @@ struct RDEPUBRenderDiagnosticsCollector {
         return (rewrittenHTML, inlinedCSSBlocks.reversed().joined(separator: "\n\n"), diagnostics.reversed())
     }
 
-    // MARK: - CSS 资源 URL 重写
+    
 
-    /// 重写 CSS 中的相对 url() 引用，解析为绝对文件路径。
+    
     static func rewriteCSSResourceURLs(
         in css: String,
         styleSheetFileURL: URL
@@ -121,18 +124,25 @@ struct RDEPUBRenderDiagnosticsCollector {
         }
 
         var rewrittenCSS = css
+        
         for match in matches.reversed() {
             guard match.numberOfRanges > 1 else { continue }
+            
             let rawValue = nsCSS.substring(with: match.range(at: 1))
                 .trimmingCharacters(in: .whitespacesAndNewlines)
                 .trimmingCharacters(in: CharacterSet(charactersIn: "\"'"))
             guard !rawValue.isEmpty else { continue }
-            if rawValue.hasPrefix("data:") || rawValue.hasPrefix("http://") || rawValue.hasPrefix("https://") || rawValue.hasPrefix("file://") || rawValue.hasPrefix("#") {
+            
+            if rawValue.hasPrefix("data:")
+                || rawValue.hasPrefix("http:")
+                || rawValue.hasPrefix("https:") {
                 continue
             }
+
             guard let resolvedURL = URL(string: rawValue, relativeTo: styleSheetFileURL.deletingLastPathComponent())?.standardizedFileURL else {
                 continue
             }
+
             let replacement = "url(\"\(resolvedURL.absoluteString)\")"
             if let range = Range(match.range, in: rewrittenCSS) {
                 rewrittenCSS.replaceSubrange(range, with: replacement)
@@ -141,8 +151,6 @@ struct RDEPUBRenderDiagnosticsCollector {
         return rewrittenCSS
     }
 
-    // MARK: - 资源引用解析
-
     static func resolveReference(
         _ reference: String,
         kind: RDEPUBTextResourceReferenceKind,
@@ -150,11 +158,16 @@ struct RDEPUBRenderDiagnosticsCollector {
         baseURL: URL?,
         resourceResolver: RDEPUBResourceResolver?
     ) -> (normalizedHref: String?, resolvedFileURL: URL?, diagnostic: RDEPUBTextResourceReferenceDiagnostic) {
+
         let trimmedReference = reference.trimmingCharacters(in: .whitespacesAndNewlines)
+
         let normalizedHref = resourceResolver?.normalizedHref(trimmedReference, relativeToHref: chapterHref)
+
         let resolvedFileURL = resourceResolver?.fileURL(forReference: trimmedReference, relativeToHref: chapterHref)
             ?? URL(string: trimmedReference, relativeTo: baseURL)?.standardizedFileURL
+
         let existsOnDisk = resolvedFileURL.map { FileManager.default.fileExists(atPath: $0.path) } ?? false
+
         let diagnostic = RDEPUBTextResourceReferenceDiagnostic(
             kind: kind,
             chapterHref: chapterHref,

Sources/RDReaderView/EPUBTextRendering/Typesetter/RDEPUBSemanticMarkerInjector.swift

@@ -1,29 +1,19 @@
-/// RDEPUBSemanticMarkerInjector - 分页语义标记注入与应用
+
 import Foundation
 import UIKit
 
-/// 语义标记注入器，为 HTML 标签注入分页语义信息（块级类型、分页提示、附件放置方式等）。
-///
-/// 分两阶段工作：
-/// 1. HTML 阶段（`process`）：解析标签并注入 `${rd-sem-start/end}` 语义标记
-/// 2. 渲染后阶段（`apply`）：将标记解析为 NSAttributedString 属性
 struct RDEPUBSemanticMarkerInjector: RDEPUBTypesettingStage {
-    /// 语义标记正则（${rd-sem-start:...} / ${rd-sem-end:...}）
+
     private static let semanticMarkerPattern = #"\$\{rd-sem-(start|end):([^}]+)\}"#
 
-    /// 为 HTML 标签注入 `${rd-sem-start/end}` 语义标记，标记块级元素类型和分页提示。
     func process(_ html: String, context: RDEPUBTypesettingInput) -> String {
         Self.injectPaginationSemanticMarkers(into: html)
     }
 
-    /// 解析渲染后富文本中的语义标记，将其转为 NSAttributedString 属性并删除标记文本。
     func apply(to attributedString: NSMutableAttributedString) {
         Self.applyPaginationSemantics(in: attributedString)
     }
 
-    // MARK: - 语义标记注入（HTML 阶段）
-
-    /// 为 HTML 标签注入 ${rd-sem-start/end} 语义标记。
     static func injectPaginationSemanticMarkers(into html: String) -> String {
         guard let regex = try? NSRegularExpression(pattern: #"<[^>]+>"#, options: [.caseInsensitive]) else {
             return html
@@ -36,8 +26,11 @@ struct RDEPUBSemanticMarkerInjector: RDEPUBTypesettingStage {
         }
 
         var output = ""
+
         var cursor = 0
+
         var openTagStack: [(name: String, id: String)] = []
+
         var nextMarkerID = 0
 
         for match in matches {
@@ -47,9 +40,11 @@ struct RDEPUBSemanticMarkerInjector: RDEPUBTypesettingStage {
 
             let tag = nsHTML.substring(with: tagRange)
             let loweredTag = tag.lowercased()
+
             let tagName = htmlTagName(from: loweredTag)
 
             if loweredTag.hasPrefix("</"), let tagName {
+
                 if let index = openTagStack.lastIndex(where: { $0.name == tagName }) {
                     let markerID = openTagStack.remove(at: index).id
                     output += semanticEndMarker(id: markerID)
@@ -57,16 +52,20 @@ struct RDEPUBSemanticMarkerInjector: RDEPUBTypesettingStage {
                 output += tag
             } else if let tagName,
                       let semantics = paginationSemantics(forTagName: tagName, rawTag: tag) {
+
                 nextMarkerID += 1
                 let markerID = String(nextMarkerID)
                 let startMarker = semanticStartMarker(id: markerID, semantics: semantics)
                 if isVoidHTMLTag(tagName) || loweredTag.hasSuffix("/>") {
+
                     output += startMarker + tag + semanticEndMarker(id: markerID)
                 } else {
+
                     openTagStack.append((name: tagName, id: markerID))
                     output += tag + startMarker
                 }
             } else {
+
                 output += tag
             }
 
@@ -77,30 +76,34 @@ struct RDEPUBSemanticMarkerInjector: RDEPUBTypesettingStage {
         return output
     }
 
-    // MARK: - 语义标记应用（渲染后阶段）
-
-    /// 将 HTML 中注入的语义标记解析后写入 NSAttributedString 属性。
     static func applyPaginationSemantics(in attributedString: NSMutableAttributedString) {
         guard let regex = try? NSRegularExpression(pattern: semanticMarkerPattern, options: []) else {
             return
         }
 
         let mutableString = NSMutableString(string: attributedString.string)
+
         var searchRange = NSRange(location: 0, length: mutableString.length)
+
         var openRanges: [String: (location: Int, semantics: RDPaginationSemantics)] = [:]
 
         while let match = regex.firstMatch(in: mutableString as String, options: [], range: searchRange) {
+
             let kind = mutableString.substring(with: match.range(at: 1))
+
             let payload = mutableString.substring(with: match.range(at: 2))
+
             let markerLocation = match.range.location
 
             attributedString.deleteCharacters(in: match.range)
             mutableString.deleteCharacters(in: match.range)
 
             if kind == "start" {
+
                 let semantics = parseSemanticMarkerPayload(payload)
                 openRanges[semantics.id] = (markerLocation, semantics)
             } else {
+
                 let markerID = parseSemanticEndID(payload)
                 if let markerID, let opened = openRanges.removeValue(forKey: markerID) {
                     let length = max(markerLocation - opened.location, 0)
@@ -114,8 +117,6 @@ struct RDEPUBSemanticMarkerInjector: RDEPUBTypesettingStage {
         }
     }
 
-    // MARK: - 语义推断
-
     static func htmlTagName(from loweredTag: String) -> String? {
         let trimmed = loweredTag.trimmingCharacters(in: .whitespacesAndNewlines)
         guard trimmed.hasPrefix("<") else { return nil }
@@ -297,7 +298,6 @@ struct RDEPUBSemanticMarkerInjector: RDEPUBTypesettingStage {
         attributedString.addAttributes(attributes, range: range)
     }
 
-    /// 推断块级元素类型。
     static func normalizeBlockKind(for attributes: [NSAttributedString.Key: Any]) -> RDEPUBTextBlockKind? {
         if let rawValue = attributes[.rdPageBlockKind] as? String,
            let blockKind = RDEPUBTextBlockKind(rawValue: rawValue) {
@@ -306,7 +306,6 @@ struct RDEPUBSemanticMarkerInjector: RDEPUBTypesettingStage {
         return nil
     }
 
-    /// 推断语义提示列表。
     static func normalizeSemanticHints(for attributes: [NSAttributedString.Key: Any]) -> [RDEPUBTextSemanticHint]? {
         if let rawValue = attributes[.rdPageSemanticHints] as? String {
             let hints = rawValue
@@ -317,7 +316,6 @@ struct RDEPUBSemanticMarkerInjector: RDEPUBTypesettingStage {
         return nil
     }
 
-    /// 推断附件放置方式。
     static func normalizeAttachmentPlacement(for attributes: [NSAttributedString.Key: Any]) -> RDEPUBTextAttachmentPlacement? {
         if let rawValue = attributes[.rdPageAttachmentPlacement] as? String,
            let placement = RDEPUBTextAttachmentPlacement(rawValue: rawValue) {
@@ -329,9 +327,6 @@ struct RDEPUBSemanticMarkerInjector: RDEPUBTypesettingStage {
         return nil
     }
 
-    // MARK: - 内部类型
-
-    /// 单个 HTML 元素的分页语义信息，由标签名和属性推断而来。
     struct RDPaginationSemantics {
         var id: String
         var blockKind: RDEPUBTextBlockKind?

Sources/RDReaderView/EPUBTextRendering/Typesetter/RDEPUBStyleSheetComposer.swift

@@ -1,24 +1,20 @@
 import UIKit
 
-/// 样式表组合结果，包含合成后的 HTML、CSS 层列表及诊断信息。
 struct RDEPUBStyleSheetComposition {
-    /// 合成后的 HTML 文本
+
     var html: String
-    /// 五层 CSS 样式层（default/replace/dark/epub/user）
+
     var layers: [RDEPUBTextStyleSheetLayer]
-    /// 内联后的 CSS 内容
+
     var inlinedCSS: String
-    /// 资源引用诊断列表
+
     var diagnostics: [RDEPUBTextResourceReferenceDiagnostic]
+
+    var compatibilityReport: RDEPUBCSSCompatibilityReport
 }
 
-/// EPUB 样式表合成器，负责组装五层 CSS 并注入 HTML。
 struct RDEPUBStyleSheetComposer {
-    /// 将 CSS 层注入 HTML，返回合成结果。
-    /// - Parameters:
-    ///   - html: 原始 HTML
-    ///   - input: 排版输入上下文
-    /// - Returns: 包含合成 HTML、CSS 层和诊断信息的结果
+
     func compose(html: String, input: RDEPUBTypesettingInput) -> RDEPUBStyleSheetComposition {
         let stylesheetHrefReplacements = RDEPUBRenderDiagnosticsCollector.inlineLinkedStyleSheets(
             in: html,
@@ -26,9 +22,10 @@ struct RDEPUBStyleSheetComposer {
             baseURL: input.baseURL,
             resourceResolver: input.resourceResolver
         )
+        let compatibility = RDEPUBCSSCompatibilityLayer().sanitize(stylesheetHrefReplacements.inlinedCSS)
         let layers = Self.makeStyleSheetLayers(
             style: input.style,
-            epubCSS: stylesheetHrefReplacements.inlinedCSS,
+            epubCSS: compatibility.css,
             contentLanguageCode: input.contentLanguageCode,
             sourceHTML: input.rawHTML
         )
@@ -61,14 +58,12 @@ struct RDEPUBStyleSheetComposer {
         return RDEPUBStyleSheetComposition(
             html: composedHTML,
             layers: layers,
-            inlinedCSS: stylesheetHrefReplacements.inlinedCSS,
-            diagnostics: stylesheetHrefReplacements.diagnostics
+            inlinedCSS: compatibility.css,
+            diagnostics: stylesheetHrefReplacements.diagnostics,
+            compatibilityReport: compatibility.report
         )
     }
 
-    // MARK: - CSS 层组装
-
-    /// 构建五层 CSS 数组（default/replace/dark/epub/user）。
     static func makeStyleSheetLayers(
         style: RDEPUBTextRenderStyle,
         epubCSS: String,
@@ -93,17 +88,13 @@ struct RDEPUBStyleSheetComposer {
         return layers
     }
 
-    // MARK: - Style 注入
-
-    /// `<style>` 标签的注入位置。
     enum StyleInjectionPosition {
-        /// 注入到 `<head>` 标签之后
+
         case headStart
-        /// 注入到 `</head>` 标签之前
+
         case headEnd
     }
 
-    /// 向 HTML 注入 <style> 标签。
     static func injectStyleTag(
         into html: String,
         styleID: String,
@@ -133,8 +124,6 @@ struct RDEPUBStyleSheetComposer {
         return styleTag + "\n" + html
     }
 
-    // MARK: - 各层 CSS
-
     private static func defaultCSS() -> String {
         RDEPUBAssetRepository.string(for: .wxReadDefaultCSS)
     }
@@ -186,8 +175,6 @@ struct RDEPUBStyleSheetComposer {
         return luminance < 0.5
     }
 
-    // MARK: - 语言检测
-
     private static func prefersLatinLanguageCSS(
         languageCode: String?,
         sourceHTML: String

Sources/RDReaderView/EPUBTextRendering/Typesetter/RDEPUBTextRendererSupport.swift

@@ -5,25 +5,8 @@ import CoreText
 import DTCoreText
 #endif
 
-/// 渲染器支持 Facade：串联各 stage 完成 HTML 预处理，并保留后渲染归一化入口。
-///
-/// 预处理管线由各 stage 文件持有实现，本文件只作为公开入口协调调用。
-/// `RDEPUBDTCoreTextRenderer` 直接调用各 stage 的静态方法。
 enum RDEPUBTextRendererSupport {
 
-    // MARK: - 预处理管线入口
-
-    /// 核心预处理方法：将原始 HTML 转换为完整的章节渲染请求。
-    ///
-    /// 内部流程：
-    /// 1. HTMLNormalizer.normalizeHTML
-    /// 2. SemanticMarkerInjector.injectPaginationSemanticMarkers
-    /// 3. DiagnosticsCollector.inlineLinkedStyleSheets
-    /// 4. StyleSheetComposer.makeStyleSheetLayers + injectStyleTag
-    /// 5. FontNormalizer.registerEmbeddedFonts
-    /// 6. HTMLNormalizer.injectBaseHref
-    /// 7. FragmentMarkerInjector.injectFragmentMarkers
-    /// 8. DiagnosticsCollector.collectImageDiagnostics
     static func makeChapterRenderRequest(
         href: String,
         title: String,
@@ -35,27 +18,33 @@ enum RDEPUBTextRendererSupport {
         pageSize: CGSize? = nil,
         layoutConfig: RDEPUBTextLayoutConfig? = nil
     ) -> RDEPUBTextChapterRenderRequest {
+
         let normalizedHTML = RDEPUBSemanticMarkerInjector.injectPaginationSemanticMarkers(
             into: RDEPUBHTMLNormalizer.normalizeHTML(rawHTML)
         )
+
         let stylesheetHrefReplacements = RDEPUBRenderDiagnosticsCollector.inlineLinkedStyleSheets(
             in: normalizedHTML,
             chapterHref: href,
             baseURL: baseURL,
             resourceResolver: resourceResolver
         )
+
         let layers = RDEPUBStyleSheetComposer.makeStyleSheetLayers(
             style: style,
             epubCSS: stylesheetHrefReplacements.inlinedCSS,
             contentLanguageCode: contentLanguageCode,
             sourceHTML: rawHTML
         )
+
         RDEPUBFontNormalizer.registerEmbeddedFonts(
             in: stylesheetHrefReplacements.inlinedCSS + "\n" + RDEPUBFontNormalizer.inlineStyleCSS(in: normalizedHTML),
             chapterHref: href,
             resourceResolver: resourceResolver
         )
+
         let htmlWithBase = RDEPUBHTMLNormalizer.injectBaseHref(into: stylesheetHrefReplacements.html, baseURL: baseURL)
+
         let htmlWithDefaultLayers = RDEPUBStyleSheetComposer.injectStyleTag(
             into: htmlWithBase,
             styleID: "rd-native-default-replace-dark",
@@ -65,19 +54,23 @@ enum RDEPUBTextRendererSupport {
                 .joined(separator: "\n\n"),
             position: .headStart
         )
+
         let htmlWithEPUBLayer = RDEPUBStyleSheetComposer.injectStyleTag(
             into: htmlWithDefaultLayers,
             styleID: "rd-native-epub",
             css: layers.first(where: { $0.kind == .epub })?.css ?? "",
             position: .headEnd
         )
+
         let composedHTML = RDEPUBStyleSheetComposer.injectStyleTag(
             into: htmlWithEPUBLayer,
             styleID: "rd-native-user",
             css: layers.first(where: { $0.kind == .user })?.css ?? "",
             position: .headEnd
         )
+
         let markedHTML = RDEPUBFragmentMarkerInjector.injectFragmentMarkers(into: composedHTML)
+
         let resourceDiagnostics = stylesheetHrefReplacements.diagnostics + RDEPUBRenderDiagnosticsCollector.collectImageDiagnostics(
             in: markedHTML,
             chapterHref: href,
@@ -101,59 +94,70 @@ enum RDEPUBTextRendererSupport {
         )
     }
 
-    // MARK: - 后渲染归一化（由 RDEPUBDTCoreTextRenderer 调用）
-
-    /// 规范化阅读属性：统一字体、行距、颜色，并注入分页语义属性。
     static func normalizeReadingAttributes(
         in attributedString: NSMutableAttributedString,
         style: RDEPUBTextRenderStyle,
         layoutConfig: RDEPUBTextLayoutConfig = .default
     ) {
         let fullRange = NSRange(location: 0, length: attributedString.length)
+
         var blockIndex = 0
         let sourceText = attributedString.string as NSString
+
         attributedString.enumerateAttributes(in: fullRange) { attributes, range, _ in
+
             let sourceFont = attributes[.font] as? UIFont
             let normalizedFont = RDEPUBFontNormalizer.normalizedFont(from: sourceFont, baseFont: style.font)
+
             let paragraph = (attributes[.paragraphStyle] as? NSParagraphStyle)?.mutableCopy() as? NSMutableParagraphStyle ?? paragraphStyle(lineSpacing: style.lineSpacing)
             paragraph.lineSpacing = style.lineSpacing
             paragraph.paragraphSpacing = max(paragraph.paragraphSpacing, style.lineSpacing / 2)
+
             paragraph.hyphenationFactor = layoutConfig.hyphenation ? 1.0 : 0.0
 
             var updatedAttributes = attributes
             updatedAttributes[.font] = normalizedFont
             updatedAttributes[.paragraphStyle] = paragraph
+
             if let textColor = style.textColor {
                 updatedAttributes[.foregroundColor] = textColor
             }
+
             RDEPUBAttachmentNormalizer.normalizeAttachmentDisplayIfNeeded(in: &updatedAttributes, font: normalizedFont)
+
             let semanticBlockRange = (attributes[.rdPageBlockRange] as? String)
                 .flatMap(NSRangeFromString)
                 .flatMap { $0.length > 0 ? $0 : nil }
             let paragraphRange = sourceText.length > 0
                 ? sourceText.paragraphRange(for: NSRange(location: min(range.location, max(sourceText.length - 1, 0)), length: 0))
                 : range
+
             updatedAttributes[.rdPageBlockRange] = NSStringFromRange(semanticBlockRange ?? paragraphRange)
             updatedAttributes[.rdPageBlockIndex] = blockIndex
+
             if let attachmentKind = RDEPUBAttachmentNormalizer.attachmentKind(for: attributes) {
                 updatedAttributes[.rdPageAttachmentKind] = attachmentKind.rawValue
             }
+
             if let placement = RDEPUBSemanticMarkerInjector.normalizeAttachmentPlacement(for: attributes) {
                 updatedAttributes[.rdPageAttachmentPlacement] = placement.rawValue
             }
+
             if let blockKind = RDEPUBSemanticMarkerInjector.normalizeBlockKind(for: attributes) {
                 updatedAttributes[.rdPageBlockKind] = blockKind.rawValue
             }
+
             if let hints = RDEPUBSemanticMarkerInjector.normalizeSemanticHints(for: attributes), !hints.isEmpty {
                 updatedAttributes[.rdPageSemanticHints] = hints.map(\.rawValue).joined(separator: ",")
             }
+
             attributedString.setAttributes(updatedAttributes, range: range)
             blockIndex += 1
         }
     }
 
-    /// 回退渲染：当 DTCoreText 不可用时，将 HTML 源码当作纯文本处理。
     static func fallbackAttributedString(for html: String, style: RDEPUBTextRenderStyle) -> NSMutableAttributedString {
+
         let fallbackAttributes: [NSAttributedString.Key: Any] = [
             .font: style.font,
             .paragraphStyle: paragraphStyle(lineSpacing: style.lineSpacing),
@@ -162,7 +166,6 @@ enum RDEPUBTextRendererSupport {
         return NSMutableAttributedString(string: html, attributes: fallbackAttributes)
     }
 
-    /// 构建共享段落样式。
     static func paragraphStyle(lineSpacing: CGFloat) -> NSMutableParagraphStyle {
         let style = NSMutableParagraphStyle()
         style.lineSpacing = lineSpacing

Sources/RDReaderView/EPUBTextRendering/Typesetter/RDEPUBTypesettingPipeline.swift

@@ -1,69 +1,77 @@
 import UIKit
 
-/// 排版输入参数，包含章节 HTML、样式和布局配置。
 struct RDEPUBTypesettingInput {
-    /// 章节相对路径
+
     var href: String
-    /// 章节标题
+
+    var spineIndex: Int?
+
     var title: String
-    /// 原始 HTML 内容
+
     var rawHTML: String
-    /// HTML 基础 URL，用于解析相对路径
+
     var baseURL: URL?
-    /// 渲染样式
+
     var style: RDEPUBTextRenderStyle
-    /// 资源解析器
+
     var resourceResolver: RDEPUBResourceResolver?
-    /// 内容语言代码（如 zh-CN）
+
     var contentLanguageCode: String?
-    /// 页面尺寸
+
     var pageSize: CGSize?
-    /// 页面布局配置
+
     var layoutConfig: RDEPUBTextLayoutConfig?
 }
 
-/// 排版输出结果，包含渲染请求和诊断信息。
 struct RDEPUBTypesettingOutput {
-    /// 章节渲染请求
+
     var request: RDEPUBTextChapterRenderRequest
-    /// 资源引用诊断列表
+
     var diagnostics: [RDEPUBTextResourceReferenceDiagnostic]
+
+    var styleCompatibilityReport: RDEPUBCSSCompatibilityReport
 }
 
-/// 排版阶段协议，定义 HTML 处理管线中的单个步骤。
 protocol RDEPUBTypesettingStage {
-    /// 处理 HTML 并返回转换后的结果。
-    /// - Parameters:
-    ///   - html: 输入 HTML
-    ///   - context: 排版上下文
-    /// - Returns: 处理后的 HTML
+
     func process(_ html: String, context: RDEPUBTypesettingInput) -> String
 }
 
-/// 排版管线，依次执行 HTML 规范化、语义标记、样式合成、字体注册和诊断收集。
 struct RDEPUBTextTypesetterPipeline {
-    /// 从排版输入构建渲染请求。
-    /// - Parameter input: 排版输入参数
-    /// - Returns: 包含渲染请求和诊断信息的输出
+
     func makeRequest(from input: RDEPUBTypesettingInput) -> RDEPUBTypesettingOutput {
+
         let htmlNormalizer = RDEPUBHTMLNormalizer()
         let semanticMarkerInjector = RDEPUBSemanticMarkerInjector()
+        let cfiMarkerInjector = RDEPUBCFIMarkerInjector()
         let styleSheetComposer = RDEPUBStyleSheetComposer()
         let fontNormalizer = RDEPUBFontNormalizer()
         let fragmentMarkerInjector = RDEPUBFragmentMarkerInjector()
         let diagnosticsCollector = RDEPUBRenderDiagnosticsCollector()
 
-        let normalizedHTML = semanticMarkerInjector.process(
-            htmlNormalizer.process(input.rawHTML, context: input),
+        let normalizedHTML = cfiMarkerInjector.process(
+            semanticMarkerInjector.process(
+                htmlNormalizer.process(input.rawHTML, context: input),
+                context: input
+            ),
             context: input
         )
+
         let styleSheetComposition = styleSheetComposer.compose(html: normalizedHTML, input: input)
-        fontNormalizer.registerEmbeddedFonts(
+
+        let fontResults = fontNormalizer.registerEmbeddedFonts(
             html: normalizedHTML,
             inlinedCSS: styleSheetComposition.inlinedCSS,
             input: input
         )
+
+        let compatibilityReport = Self.mergedCompatibilityReport(
+            styleSheetComposition.compatibilityReport,
+            fontResults: fontResults
+        )
+
         let markedHTML = fragmentMarkerInjector.process(styleSheetComposition.html, context: input)
+
         let diagnostics = styleSheetComposition.diagnostics + diagnosticsCollector.collect(in: markedHTML, input: input)
 
         let context = RDEPUBTextChapterContext(
@@ -72,7 +80,8 @@ struct RDEPUBTextTypesetterPipeline {
             html: markedHTML,
             baseURL: input.baseURL,
             stylesheet: RDEPUBTextStyleSheetPackage(layers: styleSheetComposition.layers),
-            resourceDiagnostics: diagnostics
+            resourceDiagnostics: diagnostics,
+            styleCompatibilityReport: compatibilityReport
         )
         let request = RDEPUBTextChapterRenderRequest(
             context: context,
@@ -82,7 +91,27 @@ struct RDEPUBTextTypesetterPipeline {
         )
         return RDEPUBTypesettingOutput(
             request: request,
-            diagnostics: diagnostics
+            diagnostics: diagnostics,
+            styleCompatibilityReport: compatibilityReport
+        )
+    }
+
+    private static func mergedCompatibilityReport(
+        _ report: RDEPUBCSSCompatibilityReport,
+        fontResults: [RDEPUBFontRegistrationResult]
+    ) -> RDEPUBCSSCompatibilityReport {
+
+        let fontFailures = fontResults.compactMap { result -> String? in
+            guard result.didRegister == false else { return nil }
+            let family = result.descriptor.family ?? "unknown-family"
+            let href = result.descriptor.href
+            let reason = result.errorDescription ?? "Font registration failed"
+            return "\(family) <\(href)>: \(reason)"
+        }
+        return RDEPUBCSSCompatibilityReport(
+            unsupportedRules: report.unsupportedRules,
+            normalizedRules: report.normalizedRules,
+            fontFailures: report.fontFailures + fontFailures
         )
     }
 }