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

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

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,