refactor: split reader architecture and chrome handling

2026-05-31 21:47:54 +08:00
parent ea21c6a831
commit 44202357c0
80 changed files with 10635 additions and 8522 deletions
@@ -0,0 +1,270 @@
+import CoreText
+import UIKit
+
+#if canImport(DTCoreText)
+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
+
+    /// CoreText 帧设置器
+    private let framesetter: CTFramesetter
+    /// DTCoreText 路径可直接消费的单矩形布局区域
+    private let dtLayoutRect: CGRect
+
+    init(factory: RDEPUBCoreTextPageFrameFactory) {
+        self.factory = factory
+        self.attributedString = factory.attributedString
+        self.pageSize = factory.pageSize
+        self.config = factory.config
+        self.pageBreakPolicy = RDEPUBPageBreakPolicy(attributedString: factory.attributedString)
+        self.framesetter = CTFramesetterCreateWithAttributedString(factory.attributedString)
+        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 []
+        }
+
+#if canImport(DTCoreText)
+        return layoutFramesUsingDTCoreText(fragmentOffsets: fragmentOffsets)
+#else
+        return layoutFramesUsingCoreText(fragmentOffsets: fragmentOffsets)
+#endif
+    }
+
+    // MARK: - CoreText 分页路径（回退方案）
+
+    private func layoutFramesUsingCoreText(fragmentOffsets: [String: Int]) -> [RDEPUBTextLayoutFrame] {
+        guard attributedString.length > 0, pageSize.width > 0, pageSize.height > 0 else {
+            return []
+        }
+
+        var frames: [RDEPUBTextLayoutFrame] = []
+        var location = 0
+        let resolvedSize = config.resolvedFrameSize(fallback: pageSize)
+        let usableWidth = resolvedSize.width - config.edgeInsets.left - config.edgeInsets.right
+        let usableHeight = resolvedSize.height - config.edgeInsets.top - config.edgeInsets.bottom
+
+        guard usableWidth > 0, usableHeight > 0 else {
+            return []
+        }
+
+        while location < attributedString.length {
+            let framePath = CGMutablePath()
+            let pageRect = CGRect(
+                x: config.edgeInsets.left,
+                y: config.edgeInsets.bottom,
+                width: usableWidth,
+                height: usableHeight
+            )
+            framePath.addRect(pageRect)
+            let frame = CTFramesetterCreateFrame(framesetter, CFRangeMake(location, 0), framePath, nil)
+            let proposedRange = proposedRangeUsingWXReadPageCount(
+                from: frame,
+                start: location,
+                usableHeight: usableHeight,
+                totalLength: attributedString.length
+            )
+            guard proposedRange.length > 0 else {
+                break
+            }
+
+            let avoidAdjusted = factory.trimmedRangeForAvoidPageBreakInside(from: frame, proposed: proposedRange)
+            let lineRanges = RDEPUBCoreTextPageFrameFactory.lineRanges(from: frame)
+
+            let adjusted = pageBreakPolicy.adjustedRange(
+                from: avoidAdjusted,
+                totalLength: attributedString.length,
+                lineRanges: lineRanges,
+                factory: factory
+            )
+            let trailingFragmentID = factory.nearestTrailingFragmentID(
+                endingAt: adjusted.range.location + adjusted.range.length,
+                fragmentOffsets: fragmentOffsets
+            )
+            frames.append(
+                RDEPUBTextLayoutFrame(
+                    contentRange: adjusted.range,
+                    breakReason: adjusted.breakReason,
+                    blockRange: adjusted.blockRange,
+                    attachmentRanges: adjusted.attachmentRanges,
+                    attachmentKinds: adjusted.attachmentKinds,
+                    blockKinds: adjusted.blockKinds,
+                    semanticHints: adjusted.semanticHints,
+                    attachmentPlacements: adjusted.attachmentPlacements,
+                    trailingFragmentID: trailingFragmentID,
+                    diagnostics: adjusted.diagnostics
+                )
+            )
+
+            let nextLocation = adjusted.range.location + adjusted.range.length
+            guard nextLocation > location else {
+                location += max(proposedRange.length, 1)
+                continue
+            }
+            location = nextLocation
+        }
+
+        return frames
+    }
+
+    // MARK: - DTCoreText 分页路径（首选方案）
+
+#if canImport(DTCoreText)
+    private func layoutFramesUsingDTCoreText(fragmentOffsets: [String: Int]) -> [RDEPUBTextLayoutFrame] {
+        guard config.numberOfColumns == 1 else {
+            return layoutFramesUsingCoreText(fragmentOffsets: fragmentOffsets)
+        }
+
+        guard let layouter = DTCoreTextLayouter(attributedString: attributedString) else {
+            return layoutFramesUsingCoreText(fragmentOffsets: fragmentOffsets)
+        }
+
+        layouter.shouldCacheLayoutFrames = false
+
+        var frames: [RDEPUBTextLayoutFrame] = []
+        var location = 0
+        let pageRect = dtLayoutRect
+
+        while location < attributedString.length {
+            guard let layoutFrame = layouter.layoutFrame(with: pageRect, range: NSRange(location: location, length: 0)) else {
+                break
+            }
+
+            let visibleRange = layoutFrame.visibleStringRange()
+            guard visibleRange.length > 0 else {
+                break
+            }
+
+            let proposedRange = NSRange(location: location, length: visibleRange.length)
+            let avoidAdjusted = factory.trimmedRangeForAvoidPageBreakInside(from: layoutFrame, proposed: proposedRange)
+            let lineAdjusted = factory.trimmedRangeForKeepWithNext(from: layoutFrame, proposed: avoidAdjusted)
+            let lineRanges = RDEPUBCoreTextPageFrameFactory.lineRanges(from: layoutFrame)
+            let adjusted = pageBreakPolicy.adjustedRange(
+                from: lineAdjusted,
+                totalLength: attributedString.length,
+                lineRanges: lineRanges,
+                factory: factory
+            )
+            let verifiedRange: NSRange
+            if adjusted.breakReason == .attachmentBoundary {
+                verifiedRange = verifiedDisplayRange(for: adjusted.range)
+            } else {
+                verifiedRange = adjusted.range
+            }
+            let trailingFragmentID = factory.nearestTrailingFragmentID(
+                endingAt: verifiedRange.location + verifiedRange.length,
+                fragmentOffsets: fragmentOffsets
+            )
+            let diagnostics = verifiedRange == adjusted.range
+                ? adjusted.diagnostics
+                : adjusted.diagnostics + ["verified-display-range \(NSStringFromRange(adjusted.range)) -> \(NSStringFromRange(verifiedRange))"]
+
+            frames.append(
+                RDEPUBTextLayoutFrame(
+                    contentRange: verifiedRange,
+                    breakReason: adjusted.breakReason,
+                    blockRange: factory.blockRange(at: max(verifiedRange.location, verifiedRange.location + verifiedRange.length - 1)),
+                    attachmentRanges: factory.attachmentRanges(in: verifiedRange),
+                    attachmentKinds: factory.attachmentKinds(in: verifiedRange),
+                    blockKinds: factory.blockKinds(in: verifiedRange),
+                    semanticHints: factory.semanticHints(in: verifiedRange),
+                    attachmentPlacements: factory.attachmentPlacements(in: verifiedRange),
+                    trailingFragmentID: trailingFragmentID,
+                    diagnostics: diagnostics
+                )
+            )
+
+            let nextLocation = verifiedRange.location + verifiedRange.length
+            guard nextLocation > location else {
+                location += max(visibleRange.length, 1)
+                continue
+            }
+            location = nextLocation
+        }
+
+        return frames
+    }
+
+    private func verifiedDisplayRange(for range: NSRange) -> NSRange {
+        guard let clampedRange = factory.clampedRange(range),
+              clampedRange.length > 0,
+              !factory.attachmentRanges(in: clampedRange).isEmpty else {
+            return range
+        }
+
+        let pageContent = attributedString.attributedSubstring(from: clampedRange)
+        guard let layouter = DTCoreTextLayouter(attributedString: pageContent) else {
+            return clampedRange
+        }
+
+        layouter.shouldCacheLayoutFrames = false
+        guard let layoutFrame = layouter.layoutFrame(with: dtLayoutRect, range: NSRange(location: 0, length: 0)) else {
+            return clampedRange
+        }
+
+        let visibleRange = layoutFrame.visibleStringRange()
+        guard visibleRange.length > 0, visibleRange.length < clampedRange.length else {
+            return clampedRange
+        }
+
+        return NSRange(location: clampedRange.location, length: visibleRange.length)
+    }
+#endif
+
+    // MARK: - WXRead 分页对齐
+
+    /// 逐句对齐 WXRead `WRChapterPageCount.recalculatePageRangesForAttributedString` 的分页循环。
+    private func proposedRangeUsingWXReadPageCount(
+        from frame: CTFrame,
+        start location: Int,
+        usableHeight: CGFloat,
+        totalLength: Int
+    ) -> NSRange {
+        let lines = CTFrameGetLines(frame) as! [CTLine]
+        guard !lines.isEmpty else {
+            return NSRange(location: location, length: 0)
+        }
+
+        var origins = [CGPoint](repeating: .zero, count: lines.count)
+        CTFrameGetLineOrigins(frame, CFRangeMake(0, 0), &origins)
+
+        var pageCharCount = 0
+        for (index, line) in lines.enumerated() {
+            let lineRange = CTLineGetStringRange(line)
+            let lineY = origins[index].y
+            var ascent: CGFloat = 0
+            var descent: CGFloat = 0
+            CTLineGetTypographicBounds(line, &ascent, &descent, nil)
+
+            if lineY - ascent > usableHeight {
+                break
+            }
+
+            pageCharCount += lineRange.length
+        }
+
+        if pageCharCount == 0 {
+            pageCharCount = 1
+        }
+
+        return NSRange(location: location, length: min(pageCharCount, totalLength - location))
+    }
+}
@@ -0,0 +1,389 @@
+import CoreText
+import UIKit
+
+#if canImport(DTCoreText)
+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) {
+        self.attributedString = attributedString
+        self.pageSize = pageSize
+        self.config = config
+        self.pageBreakPolicy = RDEPUBPageBreakPolicy(attributedString: attributedString)
+    }
+
+    /// 协议要求的便捷初始化（使用默认配置）
+    init() {
+        self.init(attributedString: NSAttributedString(), pageSize: .zero, config: .default)
+    }
+
+    // MARK: - RDEPUBPageFrameBuilding 协议
+
+    func makeFrames(
+        attributedString: NSAttributedString,
+        pageSize: CGSize,
+        config: RDEPUBTextLayoutConfig,
+        fragmentOffsets: [String: Int]
+    ) -> [RDEPUBTextLayoutFrame] {
+        let factory = RDEPUBCoreTextPageFrameFactory(attributedString: attributedString, pageSize: pageSize, config: config)
+        let counter = RDEPUBChapterPageCounter(factory: factory)
+        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 {
+            return CGPath(rect: columnRects.first ?? CGRect(origin: .zero, size: pageSize), transform: nil)
+        }
+
+        let path = CGMutablePath()
+        for rect in columnRects {
+            path.addRect(rect)
+        }
+        return path
+    }
+
+    // MARK: - 行级裁剪
+
+    /// 从 CTFrame 最后一行向前扫描，移除落在 avoidPageBreakInside 保护块内的尾部行。
+    func trimmedRangeForAvoidPageBreakInside(
+        from frame: CTFrame,
+        proposed: NSRange
+    ) -> NSRange {
+        guard config.avoidPageBreakInsideEnabled else { return proposed }
+
+        let lines = CTFrameGetLines(frame) as! [CTLine]
+        guard !lines.isEmpty else { return proposed }
+
+        let lineRanges = lines.map {
+            let range = CTLineGetStringRange($0)
+            return NSRange(location: range.location, length: range.length)
+        }
+        return trimmedRangeForAvoidPageBreakInside(proposed: proposed, lineRanges: lineRanges)
+    }
+
+    /// CoreText 路径的 keepWithNext 处理：从最后行向前扫描
+    func trimmedRangeForKeepWithNext(
+        from frame: CTFrame,
+        proposed: NSRange
+    ) -> NSRange {
+        let lines = CTFrameGetLines(frame) as! [CTLine]
+        let lineRanges = lines.map {
+            let range = CTLineGetStringRange($0)
+            return NSRange(location: range.location, length: range.length)
+        }
+        return trimmedRangeForKeepWithNext(proposed: proposed, lineRanges: lineRanges)
+    }
+
+#if canImport(DTCoreText)
+    /// DTCoreText 路径的 avoidPageBreakInside 处理
+    func trimmedRangeForAvoidPageBreakInside(
+        from layoutFrame: DTCoreTextLayoutFrame,
+        proposed: NSRange
+    ) -> NSRange {
+        guard config.avoidPageBreakInsideEnabled else { return proposed }
+
+        guard let lines = layoutFrame.lines as? [DTCoreTextLayoutLine], !lines.isEmpty else {
+            return proposed
+        }
+        let lineRanges = lines.map { $0.stringRange() }
+        return trimmedRangeForAvoidPageBreakInside(proposed: proposed, lineRanges: lineRanges)
+    }
+
+    /// DTCoreText 路径的 keepWithNext 处理
+    func trimmedRangeForKeepWithNext(
+        from layoutFrame: DTCoreTextLayoutFrame,
+        proposed: NSRange
+    ) -> NSRange {
+        guard let lines = layoutFrame.lines as? [DTCoreTextLayoutLine], !lines.isEmpty else {
+            return proposed
+        }
+        let lineRanges = lines.map { $0.stringRange() }
+        return trimmedRangeForKeepWithNext(proposed: proposed, lineRanges: lineRanges)
+    }
+#endif
+
+    /// 从最后行向前扫描，移除落在 avoidPageBreakInside 保护块内的尾部行（通用路径）。
+    func trimmedRangeForAvoidPageBreakInside(
+        proposed: NSRange,
+        lineRanges: [NSRange]
+    ) -> NSRange {
+        guard config.avoidPageBreakInsideEnabled, !lineRanges.isEmpty else { return proposed }
+
+        let kMaxLinesToRemove = 3
+        var linesToRemove = 0
+
+        for lineRange in lineRanges.reversed() {
+            if pageBreakPolicy.lineIsInAvoidPageBreakInsideBlock(lineRange) {
+                linesToRemove += 1
+                if linesToRemove >= kMaxLinesToRemove {
+                    linesToRemove = kMaxLinesToRemove
+                    break
+                }
+            } else {
+                break
+            }
+        }
+
+        guard linesToRemove > 0 else { return proposed }
+
+        let validLineCount = lineRanges.count - linesToRemove
+        guard validLineCount > 0 else { return proposed }
+
+        let lastValidLine = lineRanges[validLineCount - 1]
+        let endLocation = lastValidLine.location + lastValidLine.length
+        let adjustedLength = endLocation - proposed.location
+        guard adjustedLength > 0 else { return proposed }
+        return NSRange(location: proposed.location, length: adjustedLength)
+    }
+
+    /// 从最后行向前扫描，移除落在 keepWithNext 保护块内的尾部行。
+    func trimmedRangeForKeepWithNext(
+        proposed: NSRange,
+        lineRanges: [NSRange]
+    ) -> NSRange {
+        guard !lineRanges.isEmpty else { return proposed }
+
+        let kMaxLinesToRemove = 3
+        var linesToRemove = 0
+
+        for lineRange in lineRanges.reversed() {
+            if pageBreakPolicy.lineIsInKeepWithNextBlock(lineRange) {
+                linesToRemove += 1
+                if linesToRemove >= kMaxLinesToRemove {
+                    linesToRemove = kMaxLinesToRemove
+                    break
+                }
+            } else {
+                break
+            }
+        }
+
+        guard linesToRemove > 0 else { return proposed }
+
+        let validLineCount = lineRanges.count - linesToRemove
+        guard validLineCount > 0 else { return proposed }
+
+        let lastValidLine = lineRanges[validLineCount - 1]
+        let endLocation = lastValidLine.location + lastValidLine.length
+        let adjustedLength = endLocation - proposed.location
+        guard adjustedLength > 0 else { return proposed }
+        return NSRange(location: proposed.location, length: adjustedLength)
+    }
+
+    // MARK: - 行信息提取
+
+    /// 获取 CTFrame 中所有行的字符范围
+    static func lineRanges(from frame: CTFrame) -> [NSRange] {
+        let lines = CTFrameGetLines(frame) as! [CTLine]
+        return lines.map {
+            let lineRange = CTLineGetStringRange($0)
+            return NSRange(location: lineRange.location, length: lineRange.length)
+        }
+    }
+
+#if canImport(DTCoreText)
+    /// 获取 DTCoreTextLayoutFrame 中所有行的字符范围
+    static func lineRanges(from layoutFrame: DTCoreTextLayoutFrame) -> [NSRange] {
+        guard let lines = layoutFrame.lines as? [DTCoreTextLayoutLine] else {
+            return []
+        }
+        return lines.map { $0.stringRange() }
+    }
+#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)
+        if let encodedRange = attributes[.rdPageBlockRange] as? String {
+            return NSRangeFromString(encodedRange)
+        }
+        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)
+        guard let rawValue = attributes[.rdPageBlockKind] as? String else { return nil }
+        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)
+        guard let rawValue = attributes[.rdPageAttachmentPlacement] as? String else { return nil }
+        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) }
+        let safeLocation = min(max(location, 0), max(source.length - 1, 0))
+        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 []
+        }
+        var results: [NSRange] = []
+        attributedString.enumerateAttribute(.rdPageAttachmentKind, in: safeRange) { value, attributeRange, _ in
+            guard value != nil else { return }
+            results.append(attributeRange)
+        }
+        return results
+    }
+
+    /// 获取指定位置的语义提示列表
+    func semanticHints(at location: Int) -> [RDEPUBTextSemanticHint] {
+        guard location >= 0, location < attributedString.length else { return [] }
+        let attributes = attributedString.attributes(at: location, effectiveRange: nil)
+        guard let rawValue = attributes[.rdPageSemanticHints] as? String else { return [] }
+        return rawValue
+            .split(separator: ",")
+            .compactMap { RDEPUBTextSemanticHint(rawValue: String($0)) }
+    }
+
+    /// 获取指定范围内的附件类型列表（去重）
+    func attachmentKinds(in range: NSRange) -> [RDEPUBTextAttachmentKind] {
+        guard let safeRange = clampedRange(range), safeRange.length > 0 else {
+            return []
+        }
+        var kinds: [RDEPUBTextAttachmentKind] = []
+        attributedString.enumerateAttribute(.rdPageAttachmentKind, in: safeRange) { value, _, _ in
+            guard let rawValue = value as? String,
+                  let kind = RDEPUBTextAttachmentKind(rawValue: rawValue),
+                  !kinds.contains(kind) else {
+                return
+            }
+            kinds.append(kind)
+        }
+        return kinds
+    }
+
+    /// 获取指定范围内的块级元素类型列表（去重）
+    func blockKinds(in range: NSRange) -> [RDEPUBTextBlockKind] {
+        guard let safeRange = clampedRange(range), safeRange.length > 0 else {
+            return []
+        }
+        var kinds: [RDEPUBTextBlockKind] = []
+        attributedString.enumerateAttribute(.rdPageBlockKind, in: safeRange) { value, _, _ in
+            guard let rawValue = value as? String,
+                  let kind = RDEPUBTextBlockKind(rawValue: rawValue),
+                  !kinds.contains(kind) else {
+                return
+            }
+            kinds.append(kind)
+        }
+        return kinds
+    }
+
+    /// 获取指定范围内的语义提示列表（去重）
+    func semanticHints(in range: NSRange) -> [RDEPUBTextSemanticHint] {
+        guard let safeRange = clampedRange(range), safeRange.length > 0 else {
+            return []
+        }
+        var hints: [RDEPUBTextSemanticHint] = []
+        attributedString.enumerateAttribute(.rdPageSemanticHints, in: safeRange) { value, _, _ in
+            guard let rawValue = value as? String else { return }
+            for hint in rawValue.split(separator: ",").compactMap({ RDEPUBTextSemanticHint(rawValue: String($0)) }) where !hints.contains(hint) {
+                hints.append(hint)
+            }
+        }
+        return hints
+    }
+
+    /// 获取指定范围内的附件布局方式列表（去重）
+    func attachmentPlacements(in range: NSRange) -> [RDEPUBTextAttachmentPlacement] {
+        guard let safeRange = clampedRange(range), safeRange.length > 0 else {
+            return []
+        }
+        var placements: [RDEPUBTextAttachmentPlacement] = []
+        attributedString.enumerateAttribute(.rdPageAttachmentPlacement, in: safeRange) { value, _, _ in
+            guard let rawValue = value as? String,
+                  let placement = RDEPUBTextAttachmentPlacement(rawValue: rawValue),
+                  !placements.contains(placement) else {
+                return
+            }
+            placements.append(placement)
+        }
+        return placements
+    }
+
+    /// 将范围裁剪到 attributedString 的合法边界内。
+    func clampedRange(_ range: NSRange) -> NSRange? {
+        guard range.location >= 0, range.length >= 0 else { return nil }
+        guard attributedString.length > 0 else {
+            return range.location == 0 ? NSRange(location: 0, length: 0) : nil
+        }
+        guard range.location < attributedString.length else { return nil }
+
+        let maxLength = attributedString.length - range.location
+        return NSRange(location: range.location, length: min(range.length, maxLength))
+    }
+
+    /// 查找指定位置之前最近的 fragment ID（用于阅读位置恢复）
+    func nearestTrailingFragmentID(
+        endingAt location: Int,
+        fragmentOffsets: [String: Int]
+    ) -> String? {
+        fragmentOffsets
+            .filter { $0.value <= location }
+            .max { lhs, rhs in lhs.value < rhs.value }?
+            .key
+    }
+
+    // MARK: - 诊断日志
+
+    /// 生成分页诊断日志
+    func diagnostics(
+        reason: RDEPUBTextPageBreakReason,
+        range: NSRange,
+        attachmentRanges: [NSRange],
+        blockRange: NSRange?,
+        blockKinds: [RDEPUBTextBlockKind],
+        semanticHints: [RDEPUBTextSemanticHint],
+        attachmentPlacements: [RDEPUBTextAttachmentPlacement],
+        trigger: String? = nil
+    ) -> [String] {
+        var items = ["page break: \(reason.rawValue)", "page range: \(NSStringFromRange(range))"]
+        if let blockRange {
+            items.append("block range: \(NSStringFromRange(blockRange))")
+        }
+        if !attachmentRanges.isEmpty {
+            items.append("attachment ranges: \(attachmentRanges.map(NSStringFromRange).joined(separator: ","))")
+        }
+        if !blockKinds.isEmpty {
+            items.append("block kinds: \(blockKinds.map(\.rawValue).joined(separator: ","))")
+        }
+        if !semanticHints.isEmpty {
+            items.append("semantic hints: \(semanticHints.map(\.rawValue).joined(separator: ","))")
+        }
+        if !attachmentPlacements.isEmpty {
+            items.append("attachment placements: \(attachmentPlacements.map(\.rawValue).joined(separator: ","))")
+        }
+        if let trigger, !trigger.isEmpty {
+            items.append("semantic trigger: \(trigger)")
+        }
+        return items
+    }
+}
@@ -0,0 +1,308 @@
+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
+        }
+        var found = false
+        attributedString.enumerateAttributes(in: probeRange) { attributes, _, stop in
+            guard shouldTreatAvoidHintAsBlockProtection(attributes) else {
+                return
+            }
+            guard let rawValue = attributes[.rdPageSemanticHints] as? String else { return }
+            let hints = rawValue
+                .split(separator: ",")
+                .compactMap { RDEPUBTextSemanticHint(rawValue: String($0)) }
+            if hints.contains(.avoidPageBreakInside) {
+                found = true
+                stop.pointee = true
+            }
+        }
+        return found
+    }
+
+    /// 检查指定行范围是否落在 keepWithNext 保护块内。
+    func lineIsInKeepWithNextBlock(_ lineRange: NSRange) -> Bool {
+        guard let probeRange = clampedProbeRange(for: lineRange) else {
+            return false
+        }
+        var found = false
+        attributedString.enumerateAttribute(.rdPageSemanticHints, in: probeRange) { value, _, stop in
+            guard let rawValue = value as? String else { return }
+            let hints = rawValue
+                .split(separator: ",")
+                .compactMap { RDEPUBTextSemanticHint(rawValue: String($0)) }
+            if hints.contains(.keepWithNext) {
+                found = true
+                stop.pointee = true
+            }
+        }
+        return found
+    }
+
+    // MARK: - 范围调整调度器
+
+    /// 对 CoreText/DTCoreText 提出的分页范围进行语义边界调整。
+    ///
+    /// 调整优先级：
+    /// 1. 若已达章节末尾，直接返回 chapterEnd
+    /// 2. pageRelate 跨页关联边界
+    /// 3. 以上都不满足时，使用原始帧限制分页
+    func adjustedRange(
+        from proposedRange: NSRange,
+        totalLength: Int,
+        lineRanges: [NSRange],
+        factory: RDEPUBCoreTextPageFrameFactory
+    ) -> (
+        range: NSRange,
+        breakReason: RDEPUBTextPageBreakReason,
+        blockRange: NSRange?,
+        attachmentRanges: [NSRange],
+        attachmentKinds: [RDEPUBTextAttachmentKind],
+        blockKinds: [RDEPUBTextBlockKind],
+        semanticHints: [RDEPUBTextSemanticHint],
+        attachmentPlacements: [RDEPUBTextAttachmentPlacement],
+        diagnostics: [String]
+    ) {
+        let pageEnd = proposedRange.location + proposedRange.length
+        let proposedBlockKinds = factory.blockKinds(in: proposedRange)
+        let proposedSemanticHints = factory.semanticHints(in: proposedRange)
+        let proposedAttachmentPlacements = factory.attachmentPlacements(in: proposedRange)
+        guard pageEnd < totalLength else {
+            return (
+                range: proposedRange,
+                breakReason: .chapterEnd,
+                blockRange: factory.blockRange(at: max(proposedRange.location, pageEnd - 1)),
+                attachmentRanges: factory.attachmentRanges(in: proposedRange),
+                attachmentKinds: factory.attachmentKinds(in: proposedRange),
+                blockKinds: proposedBlockKinds,
+                semanticHints: proposedSemanticHints,
+                attachmentPlacements: proposedAttachmentPlacements,
+                diagnostics: factory.diagnostics(
+                    reason: .chapterEnd,
+                    range: proposedRange,
+                    attachmentRanges: factory.attachmentRanges(in: proposedRange),
+                    blockRange: factory.blockRange(at: max(proposedRange.location, pageEnd - 1)),
+                    blockKinds: proposedBlockKinds,
+                    semanticHints: proposedSemanticHints,
+                    attachmentPlacements: proposedAttachmentPlacements
+                )
+            )
+        }
+
+        let currentBlockRange = factory.blockRange(at: max(proposedRange.location, pageEnd - 1))
+        let currentAttachmentRanges = factory.attachmentRanges(in: proposedRange)
+        let currentAttachmentKinds = factory.attachmentKinds(in: proposedRange)
+        let currentBlockKinds = proposedBlockKinds
+        let currentSemanticHints = proposedSemanticHints
+        let currentAttachmentPlacements = proposedAttachmentPlacements
+
+        // 对齐 WXRead：默认按 CTFrame 已经容纳的行数分页，仅保留 pageRelate 这种
+        // 微信读书特有的跨页关联规则。
+        if let pageRelateBoundary = preferredPageRelateBoundary(
+            after: proposedRange,
+            minimumEnd: proposedRange.location + 1,
+            lineRanges: lineRanges,
+            factory: factory
+        ) {
+            let adjustedRange = NSRange(location: proposedRange.location, length: pageRelateBoundary - proposedRange.location)
+            return (
+                range: adjustedRange,
+                breakReason: .semanticBoundary,
+                blockRange: currentBlockRange,
+                attachmentRanges: currentAttachmentRanges,
+                attachmentKinds: currentAttachmentKinds,
+                blockKinds: currentBlockKinds,
+                semanticHints: currentSemanticHints,
+                attachmentPlacements: currentAttachmentPlacements,
+                diagnostics: factory.diagnostics(
+                    reason: .semanticBoundary,
+                    range: adjustedRange,
+                    attachmentRanges: currentAttachmentRanges,
+                    blockRange: currentBlockRange,
+                    blockKinds: currentBlockKinds,
+                    semanticHints: currentSemanticHints,
+                    attachmentPlacements: currentAttachmentPlacements,
+                    trigger: RDEPUBTextSemanticHint.pageRelate.rawValue
+                )
+            )
+        }
+
+        // 帧限制（默认分页）
+        return (
+            range: proposedRange,
+            breakReason: .frameLimit,
+            blockRange: currentBlockRange,
+            attachmentRanges: currentAttachmentRanges,
+            attachmentKinds: currentAttachmentKinds,
+            blockKinds: currentBlockKinds,
+            semanticHints: currentSemanticHints,
+            attachmentPlacements: currentAttachmentPlacements,
+            diagnostics: factory.diagnostics(
+                reason: .frameLimit,
+                range: proposedRange,
+                attachmentRanges: currentAttachmentRanges,
+                blockRange: currentBlockRange,
+                blockKinds: currentBlockKinds,
+                semanticHints: currentSemanticHints,
+                attachmentPlacements: currentAttachmentPlacements
+            )
+        )
+    }
+
+    // MARK: - 语义边界查找
+
+    /// 在指定范围内查找最优的语义分页点（pageBreakBefore / pageBreakAfter）。
+    func preferredSemanticBoundary(
+        in range: NSRange,
+        minimumEnd: Int,
+        factory: RDEPUBCoreTextPageFrameFactory
+    ) -> (location: Int, trigger: String)? {
+        guard let safeRange = factory.clampedRange(range), safeRange.length > 0 else {
+            return nil
+        }
+        var boundary: (location: Int, trigger: String)?
+        attributedString.enumerateAttribute(.rdPageSemanticHints, in: safeRange) { value, attributeRange, stop in
+            guard let rawValue = value as? String else { return }
+            let hints = rawValue
+                .split(separator: ",")
+                .compactMap { RDEPUBTextSemanticHint(rawValue: String($0)) }
+            guard !hints.isEmpty else { return }
+
+            if hints.contains(.pageBreakBefore),
+               attributeRange.location > safeRange.location,
+               attributeRange.location >= minimumEnd {
+                boundary = (attributeRange.location, RDEPUBTextSemanticHint.pageBreakBefore.rawValue)
+                stop.pointee = true
+                return
+            }
+
+            let attributeEnd = attributeRange.location + attributeRange.length
+            if hints.contains(.pageBreakAfter),
+               attributeEnd > minimumEnd,
+               attributeEnd < safeRange.location + safeRange.length {
+                boundary = (attributeEnd, RDEPUBTextSemanticHint.pageBreakAfter.rawValue)
+                stop.pointee = true
+                return
+            }
+        }
+        return boundary
+    }
+
+    /// 查找附件边界：只有块级附件才触发分页。
+    func preferredAttachmentBoundary(
+        in range: NSRange,
+        minimumEnd: Int,
+        factory: RDEPUBCoreTextPageFrameFactory
+    ) -> Int? {
+        guard let safeRange = factory.clampedRange(range), safeRange.length > 0 else {
+            return nil
+        }
+        var boundary: Int?
+        attributedString.enumerateAttribute(.rdPageAttachmentKind, in: safeRange) { value, attributeRange, stop in
+            guard value != nil else { return }
+
+            let location = attributeRange.location
+            let placement = factory.attachmentPlacement(at: location)
+            let blockKind = factory.blockKind(at: location)
+
+            let isBlockLevelAttachment: Bool
+            switch placement {
+            case .centered:
+                isBlockLevelAttachment = true
+            case .inline, .baseline:
+                isBlockLevelAttachment = false
+            case nil:
+                isBlockLevelAttachment = blockKind == .attachment
+            }
+            guard isBlockLevelAttachment else { return }
+
+            let boundaryRange = factory.blockRange(at: location) ?? factory.paragraphRange(containing: location)
+            if boundaryRange.location > safeRange.location, boundaryRange.location >= minimumEnd {
+                boundary = boundaryRange.location
+                stop.pointee = true
+            }
+        }
+        return boundary
+    }
+
+    /// 查找 pageRelate 跨页关联边界。
+    func preferredPageRelateBoundary(
+        after range: NSRange,
+        minimumEnd: Int,
+        lineRanges: [NSRange],
+        factory: RDEPUBCoreTextPageFrameFactory
+    ) -> Int? {
+        let pageStartOfNext = range.location + range.length
+        guard pageStartOfNext > range.location,
+              pageStartOfNext < attributedString.length,
+              lineRanges.count >= 2,
+              factory.semanticHints(at: pageStartOfNext).contains(.pageRelate) else {
+            return nil
+        }
+
+        let boundaryBlockStart = factory.blockRange(at: pageStartOfNext)?.location
+            ?? factory.paragraphRange(containing: pageStartOfNext).location
+        guard boundaryBlockStart == pageStartOfNext else { return nil }
+
+        let lastLineStart = lineRanges[lineRanges.count - 1].location
+        guard lastLineStart > range.location, lastLineStart >= minimumEnd else {
+            return nil
+        }
+        return lastLineStart
+    }
+
+    // MARK: - 内部工具
+
+    private func shouldTreatAvoidHintAsBlockProtection(_ attributes: [NSAttributedString.Key: Any]) -> Bool {
+        guard let rawValue = attributes[.rdPageSemanticHints] as? String else {
+            return false
+        }
+        let hints = rawValue
+            .split(separator: ",")
+            .compactMap { RDEPUBTextSemanticHint(rawValue: String($0)) }
+        guard hints.contains(.avoidPageBreakInside) else {
+            return false
+        }
+
+        let placement = (attributes[.rdPageAttachmentPlacement] as? String)
+            .flatMap(RDEPUBTextAttachmentPlacement.init(rawValue:))
+        let blockKind = (attributes[.rdPageBlockKind] as? String)
+            .flatMap(RDEPUBTextBlockKind.init(rawValue:))
+
+        if blockKind == .attachment, placement != .centered {
+            return false
+        }
+
+        return true
+    }
+
+    private func clampedProbeRange(for lineRange: NSRange) -> NSRange? {
+        clampedRange(NSRange(location: lineRange.location, length: max(lineRange.length, 1)))
+    }
+
+    private func clampedRange(_ range: NSRange) -> NSRange? {
+        guard range.location >= 0, range.length >= 0 else { return nil }
+        guard attributedString.length > 0 else {
+            return range.location == 0 ? NSRange(location: 0, length: 0) : nil
+        }
+        guard range.location < attributedString.length else { return nil }
+
+        let maxLength = attributedString.length - range.location
+        return NSRange(location: range.location, length: min(range.length, maxLength))
+    }
+}
@@ -0,0 +1,44 @@
+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,
+            blockRange: blockRange,
+            attachmentRanges: attachmentRanges,
+            attachmentKinds: attachmentKinds,
+            blockKinds: blockKinds,
+            semanticHints: semanticHints,
+            attachmentPlacements: attachmentPlacements,
+            trailingFragmentID: trailingFragmentID,
+            diagnostics: diagnostics
+        )
+    }
+}
@@ -0,0 +1,26 @@
+import CoreText
+import UIKit
+
+#if canImport(DTCoreText)
+import DTCoreText
+#endif
+
+/// CoreText 分页引擎 Facade：将富文本按页面尺寸拆分为多帧（每帧对应一页）。
+///
+/// 内部委托给三个组件：
+/// - RDEPUBCoreTextPageFrameFactory — 帧创建、属性查询、诊断
+/// - RDEPUBPageBreakPolicy — 分页规则（语义保护、keepWithNext）
+/// - RDEPUBChapterPageCounter — 顶层分页循环编排
+struct RDEPUBTextLayouter {
+    private let counter: RDEPUBChapterPageCounter
+
+    init(attributedString: NSAttributedString, pageSize: CGSize, config: RDEPUBTextLayoutConfig = .default) {
+        let factory = RDEPUBCoreTextPageFrameFactory(attributedString: attributedString, pageSize: pageSize, config: config)
+        self.counter = RDEPUBChapterPageCounter(factory: factory)
+    }
+
+    /// 执行分页，返回布局帧列表（每帧对应一页）。
+    func layoutFrames(fragmentOffsets: [String: Int] = [:]) -> [RDEPUBTextLayoutFrame] {
+        counter.layoutFrames(fragmentOffsets: fragmentOffsets)
+    }
+}
@@ -0,0 +1,28 @@
+import Foundation
+import UIKit
+
+// MARK: - 分页接口定义
+
+struct RDEPUBPageBreakDecision {
+    var range: NSRange
+    var reason: RDEPUBTextPageBreakReason
+    var diagnostics: [String]
+}
+
+protocol RDEPUBChapterPageCounting {
+    func pageRanges(
+        for attributedString: NSAttributedString,
+        pageSize: CGSize,
+        config: RDEPUBTextLayoutConfig,
+        fragmentOffsets: [String: Int]
+    ) -> [RDEPUBPageBreakDecision]
+}
+
+protocol RDEPUBPageFrameBuilding {
+    func makeFrames(
+        attributedString: NSAttributedString,
+        pageSize: CGSize,
+        config: RDEPUBTextLayoutConfig,
+        fragmentOffsets: [String: Int]
+    ) -> [RDEPUBTextLayoutFrame]
+}
@@ -0,0 +1,45 @@
+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] = [:],
+        config: RDEPUBTextLayoutConfig = .default
+    ) -> [RDEPUBTextLayoutFrame] {
+        let factory = RDEPUBCoreTextPageFrameFactory(attributedString: self, pageSize: size, config: config)
+        let counter = RDEPUBChapterPageCounter(factory: factory)
+        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
+        var blue: CGFloat = 0
+        var alpha: CGFloat = 0
+        getRed(&red, green: &green, blue: &blue, alpha: &alpha)
+        return String(format: "rgba(%d, %d, %d, %.3f)", Int(red * 255), Int(green * 255), Int(blue * 255), alpha)
+    }
+}