refactor: split reader architecture and chrome handling

Sources/RDReaderView/EPUBTextRendering/BuildPipeline/RDEPUBBuildDiagnosticsReporter.swift

@@ -0,0 +1,57 @@
+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") })
+
+        var parts = [
+            title,
+            "章节 \(diagnostics.count)",
+            blockKinds.isEmpty ? nil : "block kinds [\(blockKinds.map(\.rawValue).joined(separator: ","))]",
+            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)
+        }
+        return parts.joined(separator: " · ")
+    }
+
+    func chapterDiagnostic(
+        href: String,
+        title: String,
+        pages: [RDEPUBTextPage]
+    ) -> RDEPUBTextChapterPaginationDiagnostic {
+        RDEPUBTextChapterPaginationDiagnostic(
+            href: href,
+            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))
+        )
+    }
+
+    private func uniqueValues<T: Equatable>(from values: [T]) -> [T] {
+        values.reduce(into: [T]()) { result, value in
+            if !result.contains(value) {
+                result.append(value)
+            }
+        }
+    }
+}

Sources/RDReaderView/EPUBTextRendering/BuildPipeline/RDEPUBChapterTailNormalizer.swift

@@ -0,0 +1,153 @@
+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
+
+        var compacted: [RDEPUBTextLayoutFrame] = []
+        compacted.reserveCapacity(normalized.count)
+        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 {
+                    print("[EPUB][Pagination] href=\(href) dropped leading/intermediate whitespace frame \(NSStringFromRange(frame.contentRange))")
+                }
+                continue
+            }
+            compacted.append(frame)
+        }
+        normalized = compacted
+
+        while let lastFrame = normalized.last,
+              shouldDropWhitespaceOnlyFrame(lastFrame, in: content) {
+            normalized.removeLast()
+            let note = "normalized: dropped whitespace-only trailing page \(NSStringFromRange(lastFrame.contentRange))"
+            if var previousFrame = normalized.popLast() {
+                previousFrame.diagnostics.append(note)
+                normalized.append(previousFrame)
+            } else {
+                print("[EPUB][Pagination] href=\(href) dropped trailing frame \(NSStringFromRange(lastFrame.contentRange))")
+            }
+        }
+
+        guard normalized.count > 1,
+              let lastFrame = normalized.last,
+              let previousFrame = normalized.dropLast().last,
+              shouldMergeShortTrailingFrame(lastFrame, previousFrame: previousFrame, in: content) else {
+            return normalized
+        }
+
+        let mergedFrame = mergeTrailingFrame(previousFrame, with: lastFrame)
+        normalized.removeLast(2)
+        normalized.append(mergedFrame)
+        return normalized
+    }
+
+    private func shouldDropWhitespaceOnlyFrame(
+        _ frame: RDEPUBTextLayoutFrame,
+        in content: NSAttributedString
+    ) -> Bool {
+        guard frame.contentRange.length > 0,
+              attachmentCount(in: content, range: frame.contentRange) == 0 else {
+            return false
+        }
+        return visibleCharacterCount(in: content, range: frame.contentRange) == 0
+    }
+
+    private func shouldMergeShortTrailingFrame(
+        _ trailingFrame: RDEPUBTextLayoutFrame,
+        previousFrame: RDEPUBTextLayoutFrame,
+        in content: NSAttributedString
+    ) -> Bool {
+        guard trailingFrame.contentRange.length > 0,
+              NSMaxRange(previousFrame.contentRange) == trailingFrame.contentRange.location else {
+            return false
+        }
+
+        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 {
+            return false
+        }
+
+        let previousVisibleCount = visibleCharacterCount(in: content, range: previousFrame.contentRange)
+        return previousVisibleCount >= max(visibleCount * 8, 12)
+    }
+
+    private func mergeTrailingFrame(
+        _ previousFrame: RDEPUBTextLayoutFrame,
+        with trailingFrame: RDEPUBTextLayoutFrame
+    ) -> RDEPUBTextLayoutFrame {
+        let mergedRange = NSRange(
+            location: previousFrame.contentRange.location,
+            length: NSMaxRange(trailingFrame.contentRange) - previousFrame.contentRange.location
+        )
+
+        return RDEPUBTextLayoutFrame(
+            contentRange: mergedRange,
+            breakReason: trailingFrame.breakReason,
+            blockRange: trailingFrame.blockRange ?? previousFrame.blockRange,
+            attachmentRanges: uniqueRanges(from: previousFrame.attachmentRanges + trailingFrame.attachmentRanges),
+            attachmentKinds: uniqueValues(from: previousFrame.attachmentKinds + trailingFrame.attachmentKinds),
+            blockKinds: uniqueValues(from: previousFrame.blockKinds + trailingFrame.blockKinds),
+            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"]
+        )
+    }
+
+    private func visibleCharacterCount(
+        in content: NSAttributedString,
+        range: NSRange
+    ) -> 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)
+        }
+        return filteredScalars.count
+    }
+
+    private func attachmentCount(in content: NSAttributedString, range: NSRange) -> Int {
+        guard content.length > 0, range.length > 0 else { return 0 }
+        var count = 0
+        content.enumerateAttribute(.attachment, in: range) { value, _, _ in
+            if value != nil {
+                count += 1
+            }
+        }
+        return count
+    }
+
+    private func uniqueValues<T: Equatable>(from values: [T]) -> [T] {
+        values.reduce(into: [T]()) { result, value in
+            if !result.contains(value) {
+                result.append(value)
+            }
+        }
+    }
+
+    private func uniqueRanges(from ranges: [NSRange]) -> [NSRange] {
+        ranges.reduce(into: [NSRange]()) { result, value in
+            if !result.contains(value) {
+                result.append(value)
+            }
+        }
+    }
+}

Sources/RDReaderView/EPUBTextRendering/BuildPipeline/RDEPUBPaginationCacheCoordinator.swift

@@ -0,0 +1,45 @@
+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) {
+        self.cache = cache
+        self.layoutConfig = layoutConfig
+    }
+
+    func cacheKey(
+        bookID: String,
+        pageSize: CGSize,
+        style: RDEPUBTextRenderStyle
+    ) -> String? {
+        guard let cache else { return nil }
+        return cache.cacheKey(
+            bookID: bookID,
+            fontSize: style.font.pointSize,
+            lineHeightMultiple: style.lineSpacing,
+            contentInsets: layoutConfig.edgeInsets,
+            pageSize: pageSize,
+            layoutConfigSignature: layoutConfig.cacheSignature
+        )
+    }
+
+    func load(key: String?) -> [String: RDEPUBTextChapterPaginationCache]? {
+        key.flatMap { cache?.load(key: $0) }
+    }
+
+    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)))
+            )
+        }
+        cache?.save(paginationCache, key: key)
+    }
+}

Sources/RDReaderView/EPUBTextRendering/BuildPipeline/RDEPUBTextBookBuilder.swift

@@ -0,0 +1,395 @@
+import UIKit
+public final class RDEPUBTextBookBuilder {
+    private let renderer: RDEPUBTextRenderer
+    private let cache: RDEPUBTextBookCache?
+    private let layoutConfig: RDEPUBTextLayoutConfig
+    private let sampler: RDEPUBTextPerformanceSampler
+    private let renderPipeline: RDEPUBChapterRenderPipeline
+    private let paginationPipeline: RDEPUBChapterPaginationPipeline
+    private let tailNormalizer: RDEPUBChapterTailNormalizer
+    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)
+
+    public init(
+        renderer: RDEPUBTextRenderer,
+        cache: RDEPUBTextBookCache? = nil,
+        layoutConfig: RDEPUBTextLayoutConfig = .default
+    ) {
+        self.renderer = renderer
+        self.cache = cache
+        self.layoutConfig = layoutConfig
+        self.sampler = RDEPUBTextPerformanceSampler()
+        self.renderPipeline = RDEPUBChapterRenderPipeline(renderer: renderer)
+        self.paginationPipeline = RDEPUBChapterPaginationPipeline()
+        self.tailNormalizer = RDEPUBChapterTailNormalizer()
+        self.cacheCoordinator = RDEPUBPaginationCacheCoordinator(cache: cache, layoutConfig: layoutConfig)
+        self.diagnosticsReporter = RDEPUBBuildDiagnosticsReporter()
+    }
+
+    /// 默认构造器，使用 DTCoreText 渲染器
+    public convenience init() {
+        self.init(renderer: RDEPUBDTCoreTextRenderer())
+    }
+
+    private var isPaginationDebugEnabled: Bool {
+        ProcessInfo.processInfo.arguments.contains("--demo-pagination-debug")
+    }
+
+    /// 生成最近一次构建的语义摘要，用于 Phase 7 质量检测日志
+    public func phase7SemanticSummary(title: String? = nil) -> String? {
+        diagnosticsReporter.phase7SemanticSummary(
+            title: title,
+            diagnostics: lastBuildPaginationDiagnostics
+        )
+    }
+
+    /// 核心构建方法：从 EPUB publication 构建分页书籍。
+    ///
+    /// 流程：
+    /// 1. 生成缓存键，尝试加载分页缓存
+    /// 2. 遍历 spine 中的线性 HTML 章节
+    /// 3. 渲染每章 HTML → NSAttributedString
+    /// 4. 跳过空白的封面/扉页章节
+    /// 5. 分页：缓存命中则使用缓存的页范围，否则调用 CoreText 分页引擎
+    /// 6. 尾页规范化：丢弃纯空白尾页、合并过短尾页
+    /// 7. 构建 RDEPUBTextBook 并保存分页缓存
+    public func build(
+        parser: RDEPUBParser,
+        publication: RDEPUBPublication,
+        pageSize: CGSize,
+        style: RDEPUBTextRenderStyle
+    ) throws -> RDEPUBTextBook {
+        if isPaginationDebugEnabled {
+            print("[PaginationDebug] build pageSize=\(NSCoder.string(for: pageSize)) layoutInsets=\(NSCoder.string(for: layoutConfig.edgeInsets))")
+        }
+        var chapters: [RDEPUBTextChapter] = []
+        var flatPages: [RDEPUBTextPage] = []
+        lastBuildResourceDiagnostics = []
+        lastBuildPaginationDiagnostics = []
+        lastBuildPerformanceSamples = []
+        lastBuildCacheStats = (0, 0)
+        sampler.reset()
+
+        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)
+
+        for (spineIndex, item) in publication.spine.enumerated() where item.linear {
+            guard item.mediaType.contains("html") || item.mediaType.contains("xhtml"),
+                  let rawHTML = parser.htmlString(forRelativePath: item.href) else {
+                continue
+            }
+
+            // 从目录表中解析章节标题
+            let chapterTitle = resolvedChapterTitle(for: item, toc: publication.tableOfContents)
+            let request = RDEPUBTextTypesetterPipeline().makeRequest(
+                from: RDEPUBTypesettingInput(
+                    href: item.href,
+                    title: chapterTitle,
+                    rawHTML: rawHTML,
+                    baseURL: parser.fileURL(forRelativePath: item.href)?.deletingLastPathComponent(),
+                    style: style,
+                    resourceResolver: publication.resourceResolver,
+                    contentLanguageCode: publication.metadata.language,
+                    pageSize: pageSize,
+                    layoutConfig: layoutConfig
+                )
+            ).request
+
+            // 渲染 HTML → NSAttributedString
+            let renderStart = CFAbsoluteTimeGetCurrent()
+            let rendered = try renderPipeline.render(request)
+            let renderDuration = CFAbsoluteTimeGetCurrent() - renderStart
+
+            lastBuildResourceDiagnostics.append(contentsOf: rendered.resourceDiagnostics)
+
+            let plainText = rendered.attributedString.string.trimmingCharacters(in: .whitespacesAndNewlines)
+            if item.href.lowercased().contains("cover") {
+                print("[EPUB][Cover] rendered href=\(item.href) textLength=\(plainText.count) attrLength=\(rendered.attributedString.length) attachments=\(attachmentCount(in: rendered.attributedString))")
+            }
+            // 跳过空白的封面/扉页章节
+            if shouldSkipChapter(item: item, content: rendered.attributedString, text: plainText) {
+                if item.href.lowercased().contains("cover") {
+                    print("[EPUB][Cover] skipped href=\(item.href)")
+                }
+                continue
+            }
+
+            let chapterIndex = chapters.count
+            let content = NSMutableAttributedString(attributedString: rendered.attributedString)
+
+            // 分页：封面图片章节走特殊路径，缓存命中则跳过分页引擎
+            let paginateStart = CFAbsoluteTimeGetCurrent()
+            let layoutFrames: [RDEPUBTextLayoutFrame]
+            let isCacheHit: Bool
+            if isAttachmentOnlyCoverChapter(item: item, content: content, plainText: plainText) {
+                // 纯图片封面：整个内容作为一页
+                layoutFrames = [
+                    RDEPUBTextLayoutFrame(
+                        contentRange: NSRange(location: 0, length: content.length),
+                        breakReason: .chapterEnd,
+                        blockRange: nil,
+                        attachmentRanges: attachmentRanges(in: content),
+                        attachmentKinds: [],
+                        blockKinds: [],
+                        semanticHints: [],
+                        attachmentPlacements: [],
+                        trailingFragmentID: nil,
+                        diagnostics: [
+                            "page break: chapterEnd",
+                            "cover fallback: single attachment page",
+                            "page range: \(NSStringFromRange(NSRange(location: 0, length: content.length)))"
+                        ]
+                    )
+                ]
+                isCacheHit = false
+            } else if let cached = cachedPagination?[item.href] {
+                // 缓存命中：直接使用缓存的页范围，跳过 CoreText 分页
+                layoutFrames = cached.pageRanges.enumerated().map { idx, range in
+                    let breakReason = idx < cached.breakReasons.count ? cached.breakReasons[idx] : .frameLimit
+                    return RDEPUBTextLayoutFrame(
+                        contentRange: range,
+                        breakReason: breakReason,
+                        blockRange: nil,
+                        attachmentRanges: [],
+                        attachmentKinds: [],
+                        blockKinds: [],
+                        semanticHints: cached.semanticHints,
+                        attachmentPlacements: [],
+                        trailingFragmentID: nil,
+                        diagnostics: ["page break: \(breakReason.rawValue)", "page range: \(NSStringFromRange(range))", "source: cache hit"]
+                    )
+                }
+                isCacheHit = true
+            } else {
+                // 缓存未命中：调用 CoreText 分页引擎
+                layoutFrames = content.length > 0
+                    ? paginationPipeline.frames(
+                        for: content,
+                        pageSize: pageSize,
+                        config: layoutConfig,
+                        fragmentOffsets: rendered.fragmentOffsets
+                    )
+                    : []
+                isCacheHit = false
+            }
+            let paginateDuration = CFAbsoluteTimeGetCurrent() - paginateStart
+
+            // 尾页规范化：丢弃纯空白尾页、合并过短尾页
+            let normalizedFrames = tailNormalizer.normalize(
+                layoutFrames,
+                content: content,
+                href: item.href
+            )
+            let effectiveFrames = normalizedFrames.isEmpty && content.length > 0
+                ? [
+                    RDEPUBTextLayoutFrame(
+                        contentRange: NSRange(location: 0, length: content.length),
+                        breakReason: .chapterEnd,
+                        blockRange: nil,
+                        attachmentRanges: [],
+                        attachmentKinds: [],
+                        blockKinds: [],
+                        semanticHints: [],
+                        attachmentPlacements: [],
+                        trailingFragmentID: nil,
+                        diagnostics: [
+                            "page break: chapterEnd",
+                            "page range: \(NSStringFromRange(NSRange(location: 0, length: content.length)))"
+                        ]
+                    )
+                ]
+                : normalizedFrames
+            if item.href.lowercased().contains("cover") {
+                print("[EPUB][Cover] paginated href=\(item.href) pages=\(effectiveFrames.count) firstRange=\(effectiveFrames.first.map { NSStringFromRange($0.contentRange) } ?? "none")")
+            }
+
+            // 记录性能采样
+            sampler.record(RDEPUBTextPerformanceSample(
+                chapterHref: item.href,
+                renderDuration: renderDuration,
+                paginateDuration: paginateDuration,
+                pageCount: effectiveFrames.count,
+                attributedStringLength: content.length,
+                cacheHit: isCacheHit
+            ))
+            if isCacheHit {
+                lastBuildCacheStats.hits += 1
+            } else {
+                lastBuildCacheStats.misses += 1
+            }
+
+            // 构建页面和章节模型
+            let chapterAttributedContent = content.copy() as! NSAttributedString
+            let pages = effectiveFrames.enumerated().map { localPageIndex, frame in
+                let range = frame.contentRange
+                return RDEPUBTextPage(
+                    absolutePageIndex: flatPages.count + localPageIndex,
+                    chapterIndex: chapterIndex,
+                    spineIndex: spineIndex,
+                    href: item.href,
+                    chapterTitle: chapterTitle,
+                    pageIndexInChapter: localPageIndex,
+                    totalPagesInChapter: effectiveFrames.count,
+                    chapterContent: chapterAttributedContent,
+                    content: content.attributedSubstring(from: range),
+                    contentRange: range,
+                    pageStartOffset: range.location,
+                    pageEndOffset: range.location + max(range.length - 1, 0),
+                    metadata: frame.metadata
+                )
+            }
+
+            if isPaginationDebugEnabled,
+               item.href.contains("Chapter_3.xhtml") {
+                print("[PaginationDebug] href=\(item.href) pages=\(pages.count)")
+                for page in pages {
+                    let preview = debugPreview(for: page.content, limit: 36)
+                    print("[PaginationDebug] absPage=\(page.absolutePageIndex + 1) localPage=\(page.pageIndexInChapter + 1) range=\(NSStringFromRange(page.contentRange)) break=\(page.metadata.breakReason.rawValue) preview=\(preview)")
+                    for note in page.metadata.diagnostics.prefix(4) {
+                        print("[PaginationDebug] note=\(note)")
+                    }
+                }
+            }
+
+            chapters.append(
+                RDEPUBTextChapter(
+                    chapterIndex: chapterIndex,
+                    spineIndex: spineIndex,
+                    href: item.href,
+                    title: chapterTitle,
+                    attributedContent: chapterAttributedContent,
+                    fragmentOffsets: rendered.fragmentOffsets,
+                    pageBreakReasons: pages.map(\.metadata.breakReason),
+                    pages: pages
+                )
+            )
+            lastBuildPaginationDiagnostics.append(
+                diagnosticsReporter.chapterDiagnostic(
+                    href: item.href,
+                    title: chapterTitle,
+                    pages: pages
+                )
+            )
+            flatPages.append(contentsOf: pages)
+        }
+
+        let book = RDEPUBTextBook(chapters: chapters, pages: flatPages)
+
+        sampler.totalBuildDuration = CFAbsoluteTimeGetCurrent() - buildStart
+
+        // 保存分页缓存（只缓存页范围和分页原因，不缓存富文本）
+        cacheCoordinator.save(chapters: chapters, key: cacheKey)
+
+        print(sampler.summary())
+        lastBuildPerformanceSamples = sampler.samples
+
+        return book
+    }
+
+    // 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
+        })?.title.trimmingCharacters(in: .whitespacesAndNewlines), !title.isEmpty {
+            return title
+        }
+        let trimmedTitle = item.title.trimmingCharacters(in: .whitespacesAndNewlines)
+        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
+        if content.length > 0 {
+            content.enumerateAttribute(.attachment, in: NSRange(location: 0, length: content.length)) { value, _, stop in
+                guard value != nil else { return }
+                hasAttachment = true
+                stop.pointee = true
+            }
+        }
+        if text.isEmpty && !hasAttachment && (lowercasedHref.contains("cover") || lowercasedHref.contains("title")) {
+            return true
+        }
+        return false
+    }
+
+    // MARK: - 附件统计
+
+    /// 统计富文本中的附件数量
+    private func attachmentCount(in content: NSAttributedString) -> Int {
+        guard content.length > 0 else { return 0 }
+        var count = 0
+        content.enumerateAttribute(.attachment, in: NSRange(location: 0, length: content.length)) { value, _, _ in
+            if value != nil {
+                count += 1
+            }
+        }
+        return count
+    }
+
+    /// 获取富文本中所有附件的 NSRange 列表
+    private func attachmentRanges(in content: NSAttributedString) -> [NSRange] {
+        guard content.length > 0 else { return [] }
+        var ranges: [NSRange] = []
+        content.enumerateAttribute(.attachment, in: NSRange(location: 0, length: content.length)) { value, range, _ in
+            if value != nil {
+                ranges.append(range)
+            }
+        }
+        return ranges
+    }
+
+    // MARK: - 封面章节检测
+
+    /// 判断是否为纯图片封面章节（href 包含 cover 且有附件但几乎无文本）
+    private func isAttachmentOnlyCoverChapter(
+        item: RDEPUBSpineItem,
+        content: NSAttributedString,
+        plainText: String
+    ) -> Bool {
+        let lowercasedHref = item.href.lowercased()
+        guard lowercasedHref.contains("cover") else { return false }
+        let trimmed = plainText.trimmingCharacters(in: .whitespacesAndNewlines)
+        return attachmentCount(in: content) > 0 && trimmed.count <= 1
+    }
+
+    private func debugPreview(for content: NSAttributedString, limit: Int) -> String {
+        let collapsed = content.string
+            .replacingOccurrences(of: "\n", with: " ")
+            .replacingOccurrences(of: "\r", with: " ")
+            .replacingOccurrences(of: "\t", with: " ")
+            .trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !collapsed.isEmpty else { return "<empty>" }
+        if collapsed.count <= limit {
+            return collapsed
+        }
+        let head = collapsed.prefix(limit)
+        return "\(head)…"
+    }
+
+}

Sources/RDReaderView/EPUBTextRendering/BuildPipeline/RDEPUBTextBookModels.swift

@@ -0,0 +1,193 @@
+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: - 页面数据模型
+
+/// 分页后的单页数据，包含全书绝对页码、所属章节、内容范围等。
+///
+/// 每个 `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 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)
+    }
+
+    public init(chapters: [RDEPUBTextChapter], pages: [RDEPUBTextPage]) {
+        self.chapters = chapters
+        self.pages = pages
+        self.indexTable = RDEPUBTextIndexTable(chapters: chapters)
+    }
+
+    public static func == (lhs: RDEPUBTextBook, rhs: RDEPUBTextBook) -> Bool {
+        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,
+        bookIdentifier: String?
+    ) -> RDEPUBChapterData? {
+        guard let normalizedLocation = resolver.normalizedLocation(location, bookIdentifier: bookIdentifier) else {
+            return nil
+        }
+        return chapterData(for: normalizedLocation.href)
+    }
+
+    /// 全书章节信息快照；对标 WXRead 由章节模型直接提供章节元数据。
+    public var chapterInfos: [EPUBChapterInfo] {
+        chapters.map { chapter in
+            EPUBChapterInfo(
+                spineIndex: chapter.spineIndex,
+                title: chapter.title,
+                pageCount: chapter.pages.count
+            )
+        }
+    }
+
+    /// 按页码（从 1 开始）获取对应页面
+    public func page(at pageNumber: Int) -> RDEPUBTextPage? {
+        guard pageNumber > 0, pages.indices.contains(pageNumber - 1) else {
+            return nil
+        }
+        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 {
+            return nil
+        }
+
+        if let anchor = normalizedLocation.rangeAnchor?.start,
+           let page = positionConverter.pageNumber(for: anchor) {
+            return page
+        }
+
+        if let anchor = indexTable.anchor(for: normalizedLocation),
+           let page = positionConverter.pageNumber(for: anchor) {
+            return page
+        }
+
+        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 {
+            return nil
+        }
+        return chapterData.location(forPage: page, bookIdentifier: bookIdentifier)
+    }
+}
+
+// MARK: - 分页书籍构建器
+
+/// 从 EPUB publication 构建分页书籍模型的核心构建器。
+///
+/// 渲染链路：遍历 spine → 渲染每章 HTML → 分页 → 合并/规范化尾页 → 构建 RDEPUBTextBook
+///
+/// 特性：
+/// - 支持分页缓存（WXRead 模式：只缓存页范围，不缓存富文本）
+/// - 性能采样（记录每章渲染/分页耗时）
+/// - 尾页规范化（丢弃纯空白尾页、合并过短尾页）

Sources/RDReaderView/EPUBTextRendering/BuildPipeline/RDEPUBTextBuildPipelineInterfaces.swift

@@ -0,0 +1,46 @@
+import UIKit
+
+protocol RDEPUBTextBookBuilding {
+    func build(
+        parser: RDEPUBParser,
+        publication: RDEPUBPublication,
+        pageSize: CGSize,
+        style: RDEPUBTextRenderStyle
+    ) throws -> RDEPUBTextBook
+}
+
+struct RDEPUBChapterRenderPipeline {
+    private let renderer: RDEPUBTextRenderer
+
+    init(renderer: RDEPUBTextRenderer) {
+        self.renderer = renderer
+    }
+
+    func render(_ request: RDEPUBTextChapterRenderRequest) throws -> RDEPUBRenderedChapterContent {
+        try renderer.renderChapter(request: request)
+    }
+}
+
+struct RDEPUBChapterPaginationPipeline {
+    private let frameFactory: RDEPUBPageFrameBuilding
+
+    init(frameFactory: RDEPUBPageFrameBuilding = RDEPUBCoreTextPageFrameFactory()) {
+        self.frameFactory = frameFactory
+    }
+
+    func frames(
+        for content: NSAttributedString,
+        pageSize: CGSize,
+        config: RDEPUBTextLayoutConfig,
+        fragmentOffsets: [String: Int]
+    ) -> [RDEPUBTextLayoutFrame] {
+        frameFactory.makeFrames(
+            attributedString: content,
+            pageSize: pageSize,
+            config: config,
+            fragmentOffsets: fragmentOffsets
+        )
+    }
+}
+
+extension RDEPUBTextBookBuilder: RDEPUBTextBookBuilding {}

Sources/RDReaderView/EPUBTextRendering/Pagination/RDEPUBChapterPageCounter.swift

@@ -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))
+    }
+}

Sources/RDReaderView/EPUBTextRendering/Pagination/RDEPUBCoreTextPageFrameFactory.swift

@@ -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
+    }
+}

Sources/RDReaderView/EPUBTextRendering/Pagination/RDEPUBPageBreakPolicy.swift

@@ -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))
+    }
+}

Sources/RDReaderView/EPUBTextRendering/Pagination/RDEPUBTextLayouter.swift

@@ -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)
+    }
+}

Sources/RDReaderView/EPUBTextRendering/Pagination/RDEPUBTextPaginationInterfaces.swift

@@ -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]
+}

Sources/RDReaderView/EPUBTextRendering/Pagination/RDEPUBTextPaginationSupport.swift

@@ -18,8 +18,9 @@ extension NSAttributedString {
         fragmentOffsets: [String: Int] = [:],
         config: RDEPUBTextLayoutConfig = .default
     ) -> [RDEPUBTextLayoutFrame] {
-        RDEPUBTextLayouter(attributedString: self, pageSize: size, config: config)
-            .layoutFrames(fragmentOffsets: fragmentOffsets)
+        let factory = RDEPUBCoreTextPageFrameFactory(attributedString: self, pageSize: size, config: config)
+        let counter = RDEPUBChapterPageCounter(factory: factory)
+        return counter.layoutFrames(fragmentOffsets: fragmentOffsets)
     }
 
     /// 简化版分页：只返回每页的 NSRange 列表（不含语义元数据）

Sources/RDReaderView/EPUBTextRendering/RDEPUBDTCoreTextRenderer.swift

@@ -25,13 +25,6 @@ public struct RDEPUBDTCoreTextRenderer: RDEPUBTextRenderer {
     }
 
     /// 渲染单个章节：HTML → NSAttributedString，同时提取 fragment 和语义标记。
-    ///
-    /// 渲染流程：
-    /// 1. 将 HTML 字符串编码为 Data
-    /// 2. 通过 DTCoreText 解析为富文本（失败则回退到纯文本）
-    /// 3. 注入分页语义标记（${rd-sem-start/end} → 属性字典）
-    /// 4. 提取 fragment 偏移量映射表
-    /// 5. 规范化阅读属性（字体、行距、颜色统一）
     public func renderChapter(
         request: RDEPUBTextChapterRenderRequest
     ) throws -> RDEPUBRenderedChapterContent {
@@ -46,8 +39,8 @@ public struct RDEPUBDTCoreTextRenderer: RDEPUBTextRenderer {
         }
 
         let attributedString = NSMutableAttributedString(attributedString: rendered)
-        RDEPUBTextRendererSupport.applyPaginationSemantics(in: attributedString)
-        let fragmentOffsets = RDEPUBTextRendererSupport.extractFragmentOffsets(from: attributedString)
+        RDEPUBSemanticMarkerInjector.applyPaginationSemantics(in: attributedString)
+        let fragmentOffsets = RDEPUBFragmentMarkerInjector.extractFragmentOffsets(from: attributedString)
         RDEPUBTextRendererSupport.normalizeReadingAttributes(in: attributedString, style: request.style)
         return RDEPUBRenderedChapterContent(
             attributedString: attributedString,
@@ -65,22 +58,24 @@ public struct RDEPUBDTCoreTextRenderer: RDEPUBTextRenderer {
         baseURL: URL?,
         style: RDEPUBTextRenderStyle
     ) throws -> RDEPUBRenderedChapterContent {
-        let request = RDEPUBTextRendererSupport.makeChapterRenderRequest(
-            href: "",
-            title: "",
-            rawHTML: html,
-            baseURL: baseURL,
-            style: style,
-            resourceResolver: nil
-        )
+        let request = RDEPUBTextTypesetterPipeline().makeRequest(
+            from: RDEPUBTypesettingInput(
+                href: "",
+                title: "",
+                rawHTML: html,
+                baseURL: baseURL,
+                style: style,
+                resourceResolver: nil
+            )
+        ).request
         return try renderChapter(request: request)
     }
 
     /// 回退渲染：当 DTCoreText 不可用时，将 HTML 源码当作纯文本处理
     private func fallbackRenderedContent(request: RDEPUBTextChapterRenderRequest) -> RDEPUBRenderedChapterContent {
         let attributedString = RDEPUBTextRendererSupport.fallbackAttributedString(for: request.context.html, style: request.style)
-        RDEPUBTextRendererSupport.applyPaginationSemantics(in: attributedString)
-        let fragmentOffsets = RDEPUBTextRendererSupport.extractFragmentOffsets(from: attributedString)
+        RDEPUBSemanticMarkerInjector.applyPaginationSemantics(in: attributedString)
+        let fragmentOffsets = RDEPUBFragmentMarkerInjector.extractFragmentOffsets(from: attributedString)
         RDEPUBTextRendererSupport.normalizeReadingAttributes(in: attributedString, style: request.style)
         return RDEPUBRenderedChapterContent(
             attributedString: attributedString,
@@ -91,9 +86,6 @@ public struct RDEPUBDTCoreTextRenderer: RDEPUBTextRenderer {
 
 #if canImport(DTCoreText)
     /// 使用 DTCoreText 将 HTML Data 解析为富文本。
-    ///
-    /// 通过 `willFlushCallback` 回调，在每个 DOM 元素最终写入富文本前，
-    /// 对图片附件做尺寸规范化、判断是否为脚注/封面等特殊元素。
     private func makeAttributedString(from data: Data, request: RDEPUBTextChapterRenderRequest) -> NSAttributedString? {
         let builder = DTHTMLAttributedStringBuilder(
             html: data,
@@ -102,7 +94,7 @@ public struct RDEPUBDTCoreTextRenderer: RDEPUBTextRenderer {
         )
         builder?.willFlushCallback = { element in
             guard let element else { return }
-            RDEPUBTextRendererSupport.prepareHTMLElementForReaderRendering(
+            RDEPUBAttachmentNormalizer.prepareHTMLElementForReaderRendering(
                 element,
                 style: request.style,
                 maxImageSize: resolvedMaxImageSize(for: request)
@@ -112,9 +104,6 @@ public struct RDEPUBDTCoreTextRenderer: RDEPUBTextRenderer {
     }
 
     /// 构建 DTCoreText 的解析选项字典，包括字体、行高、图片尺寸限制等。
-    ///
-    /// - 注意：行高倍率计算公式为 `(字体行高 + 行间距) / 字体行高`，
-    ///   确保最终行距与用户设置的 style.lineSpacing 一致。
     private func dtOptions(request: RDEPUBTextChapterRenderRequest) -> [AnyHashable: Any] {
         let style = request.style
         let maxImageSize = resolvedMaxImageSize(for: request)
@@ -139,16 +128,12 @@ public struct RDEPUBDTCoreTextRenderer: RDEPUBTextRenderer {
     }
 
     private func resolvedMaxImageSize(for request: RDEPUBTextChapterRenderRequest) -> CGSize {
-        if let pageSize = request.pageSize {
-            let layoutConfig = request.layoutConfig ?? .default
-            let contentRect = layoutConfig.contentRect(fallback: pageSize)
-            let maxWidth = max(round(contentRect.width), 1)
-            let maxHeight = max(round(contentRect.height * layoutConfig.imageMaxHeightRatio), 1)
-            return CGSize(width: maxWidth, height: maxHeight)
-        }
-
-        let screenBounds = UIScreen.main.bounds.insetBy(dx: 20, dy: 28)
-        return CGSize(width: max(round(screenBounds.width), 1), height: max(round(screenBounds.height * 0.85), 1))
+        let layoutConfig = request.layoutConfig ?? .default
+        let fallbackPageSize = request.pageSize ?? layoutConfig.fallbackViewportSize
+        let contentRect = layoutConfig.contentRect(fallback: fallbackPageSize)
+        let maxWidth = max(round(contentRect.width), 1)
+        let maxHeight = max(round(contentRect.height * layoutConfig.imageMaxHeightRatio), 1)
+        return CGSize(width: maxWidth, height: maxHeight)
     }
 #endif
 }

Sources/RDReaderView/EPUBTextRendering/RDEPUBTextBookBuilder.swift

@@ -1,798 +0,0 @@
-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: - 页面数据模型
-
-/// 分页后的单页数据，包含全书绝对页码、所属章节、内容范围等。
-///
-/// 每个 `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 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)
-    }
-
-    public init(chapters: [RDEPUBTextChapter], pages: [RDEPUBTextPage]) {
-        self.chapters = chapters
-        self.pages = pages
-        self.indexTable = RDEPUBTextIndexTable(chapters: chapters)
-    }
-
-    public static func == (lhs: RDEPUBTextBook, rhs: RDEPUBTextBook) -> Bool {
-        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,
-        bookIdentifier: String?
-    ) -> RDEPUBChapterData? {
-        guard let normalizedLocation = resolver.normalizedLocation(location, bookIdentifier: bookIdentifier) else {
-            return nil
-        }
-        return chapterData(for: normalizedLocation.href)
-    }
-
-    /// 全书章节信息快照；对标 WXRead 由章节模型直接提供章节元数据。
-    public var chapterInfos: [EPUBChapterInfo] {
-        chapters.map { chapter in
-            EPUBChapterInfo(
-                spineIndex: chapter.spineIndex,
-                title: chapter.title,
-                pageCount: chapter.pages.count
-            )
-        }
-    }
-
-    /// 按页码（从 1 开始）获取对应页面
-    public func page(at pageNumber: Int) -> RDEPUBTextPage? {
-        guard pageNumber > 0, pages.indices.contains(pageNumber - 1) else {
-            return nil
-        }
-        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 {
-            return nil
-        }
-
-        if let anchor = normalizedLocation.rangeAnchor?.start,
-           let page = positionConverter.pageNumber(for: anchor) {
-            return page
-        }
-
-        if let anchor = indexTable.anchor(for: normalizedLocation),
-           let page = positionConverter.pageNumber(for: anchor) {
-            return page
-        }
-
-        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 {
-            return nil
-        }
-        return chapterData.location(forPage: page, bookIdentifier: bookIdentifier)
-    }
-}
-
-// MARK: - 分页书籍构建器
-
-/// 从 EPUB publication 构建分页书籍模型的核心构建器。
-///
-/// 渲染链路：遍历 spine → 渲染每章 HTML → 分页 → 合并/规范化尾页 → 构建 RDEPUBTextBook
-///
-/// 特性：
-/// - 支持分页缓存（WXRead 模式：只缓存页范围，不缓存富文本）
-/// - 性能采样（记录每章渲染/分页耗时）
-/// - 尾页规范化（丢弃纯空白尾页、合并过短尾页）
-/// - 封面章节特殊处理
-public final class RDEPUBTextBookBuilder {
-    private let renderer: RDEPUBTextRenderer
-    private let cache: RDEPUBTextBookCache?
-    private let layoutConfig: RDEPUBTextLayoutConfig
-    private let sampler: RDEPUBTextPerformanceSampler
-
-    /// 最后一次构建的资源引用诊断（样式表、图片等）
-    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)
-
-    public init(
-        renderer: RDEPUBTextRenderer,
-        cache: RDEPUBTextBookCache? = nil,
-        layoutConfig: RDEPUBTextLayoutConfig = .default
-    ) {
-        self.renderer = renderer
-        self.cache = cache
-        self.layoutConfig = layoutConfig
-        self.sampler = RDEPUBTextPerformanceSampler()
-    }
-
-    /// 默认构造器，使用 DTCoreText 渲染器
-    public convenience init() {
-        self.init(renderer: RDEPUBDTCoreTextRenderer())
-    }
-
-    private var isPaginationDebugEnabled: Bool {
-        ProcessInfo.processInfo.arguments.contains("--demo-pagination-debug")
-    }
-
-    /// 生成最近一次构建的语义摘要，用于 Phase 7 质量检测日志
-    public func phase7SemanticSummary(title: String? = nil) -> String? {
-        guard !lastBuildPaginationDiagnostics.isEmpty else { return nil }
-
-        let blockKinds = uniqueValues(from: lastBuildPaginationDiagnostics.flatMap(\.blockKinds))
-        let semanticHints = uniqueValues(from: lastBuildPaginationDiagnostics.flatMap(\.semanticHints))
-        let attachmentPlacements = uniqueValues(from: lastBuildPaginationDiagnostics.flatMap(\.attachmentPlacements))
-        let note = lastBuildPaginationDiagnostics
-            .flatMap(\.sampleNotes)
-            .first(where: { $0.contains("semantic") || $0.contains("attachment") || $0.contains("block kinds") })
-
-        var parts = [
-            title,
-            "章节 \(lastBuildPaginationDiagnostics.count)",
-            blockKinds.isEmpty ? nil : "block kinds [\(blockKinds.map(\.rawValue).joined(separator: ","))]",
-            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)
-        }
-        return parts.joined(separator: " · ")
-    }
-
-    /// 核心构建方法：从 EPUB publication 构建分页书籍。
-    ///
-    /// 流程：
-    /// 1. 生成缓存键，尝试加载分页缓存
-    /// 2. 遍历 spine 中的线性 HTML 章节
-    /// 3. 渲染每章 HTML → NSAttributedString
-    /// 4. 跳过空白的封面/扉页章节
-    /// 5. 分页：缓存命中则使用缓存的页范围，否则调用 CoreText 分页引擎
-    /// 6. 尾页规范化：丢弃纯空白尾页、合并过短尾页
-    /// 7. 构建 RDEPUBTextBook 并保存分页缓存
-    public func build(
-        parser: RDEPUBParser,
-        publication: RDEPUBPublication,
-        pageSize: CGSize,
-        style: RDEPUBTextRenderStyle
-    ) throws -> RDEPUBTextBook {
-        if isPaginationDebugEnabled {
-            print("[PaginationDebug] build pageSize=\(NSCoder.string(for: pageSize)) layoutInsets=\(NSCoder.string(for: layoutConfig.edgeInsets))")
-        }
-        var chapters: [RDEPUBTextChapter] = []
-        var flatPages: [RDEPUBTextPage] = []
-        lastBuildResourceDiagnostics = []
-        lastBuildPaginationDiagnostics = []
-        lastBuildPerformanceSamples = []
-        lastBuildCacheStats = (0, 0)
-        sampler.reset()
-
-        let buildStart = CFAbsoluteTimeGetCurrent()
-
-        // 缓存查询 — WXRead 模式：只加载每章的页范围，不缓存富文本
-        let bookID = publication.metadata.identifier ?? publication.metadata.title
-        let cacheKey = makeCacheKey(bookID: bookID, pageSize: pageSize, style: style)
-        let cachedPagination = cacheKey.flatMap { cache?.load(key: $0) }
-
-        for (spineIndex, item) in publication.spine.enumerated() where item.linear {
-            guard item.mediaType.contains("html") || item.mediaType.contains("xhtml"),
-                  let rawHTML = parser.htmlString(forRelativePath: item.href) else {
-                continue
-            }
-
-            // 从目录表中解析章节标题
-            let chapterTitle = resolvedChapterTitle(for: item, toc: publication.tableOfContents)
-            let request = RDEPUBTextRendererSupport.makeChapterRenderRequest(
-                href: item.href,
-                title: chapterTitle,
-                rawHTML: rawHTML,
-                baseURL: parser.fileURL(forRelativePath: item.href)?.deletingLastPathComponent(),
-                style: style,
-                resourceResolver: publication.resourceResolver,
-                contentLanguageCode: publication.metadata.language,
-                pageSize: pageSize,
-                layoutConfig: layoutConfig
-            )
-
-            // 渲染 HTML → NSAttributedString
-            let renderStart = CFAbsoluteTimeGetCurrent()
-            let rendered = try renderer.renderChapter(request: request)
-            let renderDuration = CFAbsoluteTimeGetCurrent() - renderStart
-
-            lastBuildResourceDiagnostics.append(contentsOf: rendered.resourceDiagnostics)
-
-            let plainText = rendered.attributedString.string.trimmingCharacters(in: .whitespacesAndNewlines)
-            if item.href.lowercased().contains("cover") {
-                print("[EPUB][Cover] rendered href=\(item.href) textLength=\(plainText.count) attrLength=\(rendered.attributedString.length) attachments=\(attachmentCount(in: rendered.attributedString))")
-            }
-            // 跳过空白的封面/扉页章节
-            if shouldSkipChapter(item: item, content: rendered.attributedString, text: plainText) {
-                if item.href.lowercased().contains("cover") {
-                    print("[EPUB][Cover] skipped href=\(item.href)")
-                }
-                continue
-            }
-
-            let chapterIndex = chapters.count
-            let content = NSMutableAttributedString(attributedString: rendered.attributedString)
-
-            // 分页：封面图片章节走特殊路径，缓存命中则跳过分页引擎
-            let paginateStart = CFAbsoluteTimeGetCurrent()
-            let layoutFrames: [RDEPUBTextLayoutFrame]
-            let isCacheHit: Bool
-            if isAttachmentOnlyCoverChapter(item: item, content: content, plainText: plainText) {
-                // 纯图片封面：整个内容作为一页
-                layoutFrames = [
-                    RDEPUBTextLayoutFrame(
-                        contentRange: NSRange(location: 0, length: content.length),
-                        breakReason: .chapterEnd,
-                        blockRange: nil,
-                        attachmentRanges: attachmentRanges(in: content),
-                        attachmentKinds: [],
-                        blockKinds: [],
-                        semanticHints: [],
-                        attachmentPlacements: [],
-                        trailingFragmentID: nil,
-                        diagnostics: [
-                            "page break: chapterEnd",
-                            "cover fallback: single attachment page",
-                            "page range: \(NSStringFromRange(NSRange(location: 0, length: content.length)))"
-                        ]
-                    )
-                ]
-                isCacheHit = false
-            } else if let cached = cachedPagination?[item.href] {
-                // 缓存命中：直接使用缓存的页范围，跳过 CoreText 分页
-                layoutFrames = cached.pageRanges.enumerated().map { idx, range in
-                    let breakReason = idx < cached.breakReasons.count ? cached.breakReasons[idx] : .frameLimit
-                    return RDEPUBTextLayoutFrame(
-                        contentRange: range,
-                        breakReason: breakReason,
-                        blockRange: nil,
-                        attachmentRanges: [],
-                        attachmentKinds: [],
-                        blockKinds: [],
-                        semanticHints: cached.semanticHints,
-                        attachmentPlacements: [],
-                        trailingFragmentID: nil,
-                        diagnostics: ["page break: \(breakReason.rawValue)", "page range: \(NSStringFromRange(range))", "source: cache hit"]
-                    )
-                }
-                isCacheHit = true
-            } else {
-                // 缓存未命中：调用 CoreText 分页引擎
-                layoutFrames = content.length > 0
-                    ? content.rd_paginatedFrames(size: pageSize, fragmentOffsets: rendered.fragmentOffsets, config: layoutConfig)
-                    : []
-                isCacheHit = false
-            }
-            let paginateDuration = CFAbsoluteTimeGetCurrent() - paginateStart
-
-            // 尾页规范化：丢弃纯空白尾页、合并过短尾页
-            let normalizedFrames = normalizeTrailingFrames(
-                layoutFrames,
-                content: content,
-                href: item.href
-            )
-            let effectiveFrames = normalizedFrames.isEmpty && content.length > 0
-                ? [
-                    RDEPUBTextLayoutFrame(
-                        contentRange: NSRange(location: 0, length: content.length),
-                        breakReason: .chapterEnd,
-                        blockRange: nil,
-                        attachmentRanges: [],
-                        attachmentKinds: [],
-                        blockKinds: [],
-                        semanticHints: [],
-                        attachmentPlacements: [],
-                        trailingFragmentID: nil,
-                        diagnostics: [
-                            "page break: chapterEnd",
-                            "page range: \(NSStringFromRange(NSRange(location: 0, length: content.length)))"
-                        ]
-                    )
-                ]
-                : normalizedFrames
-            if item.href.lowercased().contains("cover") {
-                print("[EPUB][Cover] paginated href=\(item.href) pages=\(effectiveFrames.count) firstRange=\(effectiveFrames.first.map { NSStringFromRange($0.contentRange) } ?? "none")")
-            }
-
-            // 记录性能采样
-            sampler.record(RDEPUBTextPerformanceSample(
-                chapterHref: item.href,
-                renderDuration: renderDuration,
-                paginateDuration: paginateDuration,
-                pageCount: effectiveFrames.count,
-                attributedStringLength: content.length,
-                cacheHit: isCacheHit
-            ))
-            if isCacheHit {
-                lastBuildCacheStats.hits += 1
-            } else {
-                lastBuildCacheStats.misses += 1
-            }
-
-            // 构建页面和章节模型
-            let chapterAttributedContent = content.copy() as! NSAttributedString
-            let pages = effectiveFrames.enumerated().map { localPageIndex, frame in
-                let range = frame.contentRange
-                return RDEPUBTextPage(
-                    absolutePageIndex: flatPages.count + localPageIndex,
-                    chapterIndex: chapterIndex,
-                    spineIndex: spineIndex,
-                    href: item.href,
-                    chapterTitle: chapterTitle,
-                    pageIndexInChapter: localPageIndex,
-                    totalPagesInChapter: effectiveFrames.count,
-                    chapterContent: chapterAttributedContent,
-                    content: content.attributedSubstring(from: range),
-                    contentRange: range,
-                    pageStartOffset: range.location,
-                    pageEndOffset: range.location + max(range.length - 1, 0),
-                    metadata: frame.metadata
-                )
-            }
-
-            if isPaginationDebugEnabled,
-               item.href.contains("Chapter_3.xhtml") {
-                print("[PaginationDebug] href=\(item.href) pages=\(pages.count)")
-                for page in pages {
-                    let preview = debugPreview(for: page.content, limit: 36)
-                    print("[PaginationDebug] absPage=\(page.absolutePageIndex + 1) localPage=\(page.pageIndexInChapter + 1) range=\(NSStringFromRange(page.contentRange)) break=\(page.metadata.breakReason.rawValue) preview=\(preview)")
-                    for note in page.metadata.diagnostics.prefix(4) {
-                        print("[PaginationDebug] note=\(note)")
-                    }
-                }
-            }
-
-            chapters.append(
-                RDEPUBTextChapter(
-                    chapterIndex: chapterIndex,
-                    spineIndex: spineIndex,
-                    href: item.href,
-                    title: chapterTitle,
-                    attributedContent: chapterAttributedContent,
-                    fragmentOffsets: rendered.fragmentOffsets,
-                    pageBreakReasons: pages.map(\.metadata.breakReason),
-                    pages: pages
-                )
-            )
-            lastBuildPaginationDiagnostics.append(
-                RDEPUBTextChapterPaginationDiagnostic(
-                    href: item.href,
-                    title: chapterTitle,
-                    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)
-                    )
-                )
-            )
-            flatPages.append(contentsOf: pages)
-        }
-
-        let book = RDEPUBTextBook(chapters: chapters, pages: flatPages)
-
-        sampler.totalBuildDuration = CFAbsoluteTimeGetCurrent() - buildStart
-
-        // 保存分页缓存（只缓存页范围和分页原因，不缓存富文本）
-        if let cacheKey {
-            let paginationCache = chapters.map { chapter in
-                let pageRanges = chapter.pages.map(\.contentRange)
-                let breakReasons = chapter.pages.map(\.metadata.breakReason)
-                let semanticHints = Array(Set(chapter.pages.flatMap(\.metadata.semanticHints)))
-                return RDEPUBTextChapterPaginationCache(
-                    href: chapter.href,
-                    pageRanges: pageRanges,
-                    breakReasons: breakReasons,
-                    semanticHints: semanticHints
-                )
-            }
-            cache?.save(paginationCache, key: cacheKey)
-        }
-
-        print(sampler.summary())
-        lastBuildPerformanceSamples = sampler.samples
-
-        return book
-    }
-
-    // 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
-        })?.title.trimmingCharacters(in: .whitespacesAndNewlines), !title.isEmpty {
-            return title
-        }
-        let trimmedTitle = item.title.trimmingCharacters(in: .whitespacesAndNewlines)
-        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
-        if content.length > 0 {
-            content.enumerateAttribute(.attachment, in: NSRange(location: 0, length: content.length)) { value, _, stop in
-                guard value != nil else { return }
-                hasAttachment = true
-                stop.pointee = true
-            }
-        }
-        if text.isEmpty && !hasAttachment && (lowercasedHref.contains("cover") || lowercasedHref.contains("title")) {
-            return true
-        }
-        return false
-    }
-
-    // MARK: - 附件统计
-
-    /// 统计富文本中的附件数量
-    private func attachmentCount(in content: NSAttributedString) -> Int {
-        guard content.length > 0 else { return 0 }
-        var count = 0
-        content.enumerateAttribute(.attachment, in: NSRange(location: 0, length: content.length)) { value, _, _ in
-            if value != nil {
-                count += 1
-            }
-        }
-        return count
-    }
-
-    /// 获取富文本中所有附件的 NSRange 列表
-    private func attachmentRanges(in content: NSAttributedString) -> [NSRange] {
-        guard content.length > 0 else { return [] }
-        var ranges: [NSRange] = []
-        content.enumerateAttribute(.attachment, in: NSRange(location: 0, length: content.length)) { value, range, _ in
-            if value != nil {
-                ranges.append(range)
-            }
-        }
-        return ranges
-    }
-
-    // MARK: - 封面章节检测
-
-    /// 判断是否为纯图片封面章节（href 包含 cover 且有附件但几乎无文本）
-    private func isAttachmentOnlyCoverChapter(
-        item: RDEPUBSpineItem,
-        content: NSAttributedString,
-        plainText: String
-    ) -> Bool {
-        let lowercasedHref = item.href.lowercased()
-        guard lowercasedHref.contains("cover") else { return false }
-        let trimmed = plainText.trimmingCharacters(in: .whitespacesAndNewlines)
-        return attachmentCount(in: content) > 0 && trimmed.count <= 1
-    }
-
-    private func debugPreview(for content: NSAttributedString, limit: Int) -> String {
-        let collapsed = content.string
-            .replacingOccurrences(of: "\n", with: " ")
-            .replacingOccurrences(of: "\r", with: " ")
-            .replacingOccurrences(of: "\t", with: " ")
-            .trimmingCharacters(in: .whitespacesAndNewlines)
-        guard !collapsed.isEmpty else { return "<empty>" }
-        if collapsed.count <= limit {
-            return collapsed
-        }
-        let head = collapsed.prefix(limit)
-        return "\(head)…"
-    }
-
-    // MARK: - 尾页规范化
-
-    /// 规范化分页结果：
-    /// 1. 移除章节中间误产生的纯空白页
-    /// 2. 丢弃纯空白的尾页
-    /// 3. 将过短的尾页（≤2 字符）合并到前一页
-    private func normalizeTrailingFrames(
-        _ frames: [RDEPUBTextLayoutFrame],
-        content: NSAttributedString,
-        href: String
-    ) -> [RDEPUBTextLayoutFrame] {
-        guard frames.count > 1 else { return frames }
-
-        var normalized = frames
-
-        // 先移除章节中间的纯空白页。这类页通常只包含换行/占位空白，
-        // 会把相邻正文页硬生生拆开，直接表现为“上一页底部空很多”。
-        var compacted: [RDEPUBTextLayoutFrame] = []
-        compacted.reserveCapacity(normalized.count)
-        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 {
-                    print("[EPUB][Pagination] href=\(href) dropped leading/intermediate whitespace frame \(NSStringFromRange(frame.contentRange))")
-                }
-                continue
-            }
-            compacted.append(frame)
-        }
-        normalized = compacted
-
-        // 丢弃纯空白的尾页
-        while let lastFrame = normalized.last,
-              shouldDropWhitespaceOnlyFrame(lastFrame, in: content) {
-            normalized.removeLast()
-            let note = "normalized: dropped whitespace-only trailing page \(NSStringFromRange(lastFrame.contentRange))"
-            if var previousFrame = normalized.popLast() {
-                previousFrame.diagnostics.append(note)
-                normalized.append(previousFrame)
-            } else {
-                print("[EPUB][Pagination] href=\(href) dropped trailing frame \(NSStringFromRange(lastFrame.contentRange))")
-            }
-        }
-
-        // 将过短的尾页合并到前一页
-        guard normalized.count > 1,
-              let lastFrame = normalized.last,
-              let previousFrame = normalized.dropLast().last,
-              shouldMergeShortTrailingFrame(lastFrame, previousFrame: previousFrame, in: content) else {
-            return normalized
-        }
-
-        let mergedFrame = mergeTrailingFrame(previousFrame, with: lastFrame)
-        normalized.removeLast(2)
-        normalized.append(mergedFrame)
-        return normalized
-    }
-
-    /// 判断尾页是否为纯空白（无可显示字符且无附件）
-    private func shouldDropWhitespaceOnlyFrame(
-        _ frame: RDEPUBTextLayoutFrame,
-        in content: NSAttributedString
-    ) -> Bool {
-        guard frame.contentRange.length > 0,
-              attachmentCount(in: content, range: frame.contentRange) == 0 else {
-            return false
-        }
-        return visibleCharacterCount(in: content, range: frame.contentRange) == 0
-    }
-
-    /// 判断尾页是否过短需要合并到前一页。
-    /// 条件：尾页 ≤ 2 个可见字符，且前一页的字符数是尾页的 8 倍以上（至少 12 个字符）
-    private func shouldMergeShortTrailingFrame(
-        _ trailingFrame: RDEPUBTextLayoutFrame,
-        previousFrame: RDEPUBTextLayoutFrame,
-        in content: NSAttributedString
-    ) -> Bool {
-        guard trailingFrame.contentRange.length > 0,
-              NSMaxRange(previousFrame.contentRange) == trailingFrame.contentRange.location else {
-            return false
-        }
-
-        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 {
-            return false
-        }
-
-        let previousVisibleCount = visibleCharacterCount(in: content, range: previousFrame.contentRange)
-        return previousVisibleCount >= max(visibleCount * 8, 12)
-    }
-
-    /// 将尾页合并到前一页，保留尾页的分页原因
-    private func mergeTrailingFrame(
-        _ previousFrame: RDEPUBTextLayoutFrame,
-        with trailingFrame: RDEPUBTextLayoutFrame
-    ) -> RDEPUBTextLayoutFrame {
-        let mergedRange = NSRange(
-            location: previousFrame.contentRange.location,
-            length: NSMaxRange(trailingFrame.contentRange) - previousFrame.contentRange.location
-        )
-
-        return RDEPUBTextLayoutFrame(
-            contentRange: mergedRange,
-            breakReason: trailingFrame.breakReason,
-            blockRange: trailingFrame.blockRange ?? previousFrame.blockRange,
-            attachmentRanges: uniqueRanges(from: previousFrame.attachmentRanges + trailingFrame.attachmentRanges),
-            attachmentKinds: uniqueValues(from: previousFrame.attachmentKinds + trailingFrame.attachmentKinds),
-            blockKinds: uniqueValues(from: previousFrame.blockKinds + trailingFrame.blockKinds),
-            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"]
-        )
-    }
-
-    /// 统计指定范围内可见字符数（排除空白和控制字符）
-    private func visibleCharacterCount(
-        in content: NSAttributedString,
-        range: NSRange
-    ) -> 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)
-        }
-        return filteredScalars.count
-    }
-
-    // MARK: - 集合工具方法
-
-    /// 数组去重（保持顺序）
-    private func uniqueValues<T: Equatable>(from values: [T]) -> [T] {
-        values.reduce(into: [T]()) { result, value in
-            if !result.contains(value) {
-                result.append(value)
-            }
-        }
-    }
-
-    /// NSRange 数组去重（保持顺序）
-    private func uniqueRanges(from ranges: [NSRange]) -> [NSRange] {
-        ranges.reduce(into: [NSRange]()) { result, value in
-            if !result.contains(value) {
-                result.append(value)
-            }
-        }
-    }
-
-    /// 统计指定范围内附件数量
-    private func attachmentCount(in content: NSAttributedString, range: NSRange) -> Int {
-        guard content.length > 0, range.length > 0 else { return 0 }
-        var count = 0
-        content.enumerateAttribute(.attachment, in: range) { value, _, _ in
-            if value != nil {
-                count += 1
-            }
-        }
-        return count
-    }
-
-    // MARK: - 缓存键生成
-
-    /// 生成缓存键：基于书籍 ID、字号、行距、页面尺寸等参数的 SHA256 哈希
-    private func makeCacheKey(
-        bookID: String,
-        pageSize: CGSize,
-        style: RDEPUBTextRenderStyle
-    ) -> String? {
-        guard let cache else { return nil }
-        return cache.cacheKey(
-            bookID: bookID,
-            fontSize: style.font.pointSize,
-            lineHeightMultiple: style.lineSpacing,
-            contentInsets: layoutConfig.edgeInsets,
-            pageSize: pageSize,
-            layoutConfigSignature: layoutConfig.cacheSignature
-        )
-    }
-}

Sources/RDReaderView/EPUBTextRendering/RDEPUBTextLayouter.swift

@@ -1,946 +0,0 @@
-import CoreText
-import UIKit
-
-#if canImport(DTCoreText)
-import DTCoreText
-#endif
-
-/// CoreText 分页引擎：将富文本按页面尺寸拆分为多帧（每帧对应一页）。
-///
-/// 分页策略优先级（从高到低）：
-/// 1. avoidPageBreakInside — 不在保护块内分页（对标 WXRead 的行级回退扫描）
-/// 2. keepWithNext — 标题等元素需与下一段同页
-/// 3. 语义边界 — pageBreakBefore/After 等显式分页标记
-/// 4. pageRelate — 微信读书式的跨页关联元素
-/// 5. 附件边界 — 块级附件应整体移到下一页
-/// 6. 帧限制 — 默认按 CoreText 可视范围分页
-///
-/// 支持两条渲染路径：
-/// - DTCoreText 路径（首选）：DTCoreTextLayouter → DTCoreTextLayoutFrame
-/// - CoreText 回退路径：CTFramesetterCreateFrame
-struct RDEPUBTextLayouter {
-    /// 待分页的富文本
-    private let attributedString: NSAttributedString
-    /// 页面尺寸（决定每帧能容纳多少内容）
-    private let pageSize: CGSize
-    /// CoreText 帧设置器
-    private let framesetter: CTFramesetter
-    /// 页面矩形路径（用于 CTFrame 排版）
-    private let path: CGPath
-    /// DTCoreText 路径可直接消费的单矩形布局区域
-    private let dtLayoutRect: CGRect
-    /// 布局配置（avoidPageBreakInside、孤行控制等）
-    private let config: RDEPUBTextLayoutConfig
-
-    init(attributedString: NSAttributedString, pageSize: CGSize, config: RDEPUBTextLayoutConfig = .default) {
-        self.attributedString = attributedString
-        self.pageSize = pageSize
-        self.config = config
-        self.framesetter = CTFramesetterCreateWithAttributedString(attributedString)
-        self.dtLayoutRect = config.contentRect(fallback: pageSize)
-        self.path = Self.makeLayoutPath(pageSize: pageSize, config: config)
-    }
-
-    /// 执行分页，返回布局帧列表（每帧对应一页）。
-    /// 根据编译环境选择 DTCoreText 或 CoreText 路径。
-    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 分页路径（回退方案）
-
-    /// 使用原生 CoreText API 进行分页。
-    ///
-    /// 流程：CTFramesetterCreateFrame → 获取可视范围 → 语义边界调整 → 记录帧
-    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()
-            // 对齐 WXRead WRChapterPageCount：
-            // CoreText 分页路径使用 bottom inset 作为 y 原点，而不是 UIKit 语义的 top inset。
-            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
-            }
-
-            // 行级 avoidPageBreakInside 处理（WXRead 方案：从最后一行向前扫描）
-            let avoidAdjusted = trimmedRangeForAvoidPageBreakInside(from: frame, proposed: proposedRange)
-            let lineRanges = lineRanges(from: frame)
-
-            let adjusted = adjustedRange(
-                from: avoidAdjusted,
-                totalLength: attributedString.length,
-                lineRanges: lineRanges
-            )
-            let trailingFragmentID = 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)
-    /// 使用 DTCoreTextLayouter 进行分页，提供更精确的行级语义处理。
-    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 = trimmedRangeForAvoidPageBreakInside(from: layoutFrame, proposed: proposedRange)
-            let lineAdjusted = trimmedRangeForKeepWithNext(from: layoutFrame, proposed: avoidAdjusted)
-            let lineRanges = lineRanges(from: layoutFrame)
-            let adjusted = adjustedRange(
-                from: lineAdjusted,
-                totalLength: attributedString.length,
-                lineRanges: lineRanges
-            )
-            let verifiedRange: NSRange
-            if adjusted.breakReason == .attachmentBoundary {
-                verifiedRange = verifiedDisplayRange(for: adjusted.range)
-            } else {
-                verifiedRange = adjusted.range
-            }
-            let trailingFragmentID = 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: blockRange(at: max(verifiedRange.location, verifiedRange.location + verifiedRange.length - 1)),
-                    attachmentRanges: attachmentRanges(in: verifiedRange),
-                    attachmentKinds: attachmentKinds(in: verifiedRange),
-                    blockKinds: blockKinds(in: verifiedRange),
-                    semanticHints: semanticHints(in: verifiedRange),
-                    attachmentPlacements: 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 = clampedRange(range),
-              clampedRange.length > 0,
-              !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
-
-    private 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: - 语义边界调整
-
-    /// 对 CoreText 提出的分页范围进行语义边界调整。
-    ///
-    /// 调整优先级：
-    /// 1. 若已达章节末尾，直接返回 chapterEnd
-    /// 2. 优先在语义边界（pageBreakBefore/After）分页
-    /// 3. 其次在 pageRelate 跨页关联点分页
-    /// 4. 再次在附件边界分页（块级附件需整体移动）
-    /// 5. 以上都不满足时，使用原始帧限制分页
-    ///
-    /// 最小分页长度约束：不低于原始范围的 55%，避免单页内容过少。
-    private func adjustedRange(
-        from proposedRange: NSRange,
-        totalLength: Int,
-        lineRanges: [NSRange]
-    ) -> (
-        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 = blockKinds(in: proposedRange)
-        let proposedSemanticHints = semanticHints(in: proposedRange)
-        let proposedAttachmentPlacements = attachmentPlacements(in: proposedRange)
-        guard pageEnd < totalLength else {
-            return (
-                range: proposedRange,
-                breakReason: .chapterEnd,
-                blockRange: blockRange(at: max(proposedRange.location, pageEnd - 1)),
-                attachmentRanges: attachmentRanges(in: proposedRange),
-                attachmentKinds: attachmentKinds(in: proposedRange),
-                blockKinds: proposedBlockKinds,
-                semanticHints: proposedSemanticHints,
-                attachmentPlacements: proposedAttachmentPlacements,
-                diagnostics: diagnostics(
-                    reason: .chapterEnd,
-                    range: proposedRange,
-                    attachmentRanges: attachmentRanges(in: proposedRange),
-                    blockRange: blockRange(at: max(proposedRange.location, pageEnd - 1)),
-                    blockKinds: proposedBlockKinds,
-                    semanticHints: proposedSemanticHints,
-                    attachmentPlacements: proposedAttachmentPlacements
-                )
-            )
-        }
-
-        let currentBlockRange = blockRange(at: max(proposedRange.location, pageEnd - 1))
-        let currentAttachmentRanges = attachmentRanges(in: proposedRange)
-        let currentAttachmentKinds = attachmentKinds(in: proposedRange)
-        let currentBlockKinds = proposedBlockKinds
-        let currentSemanticHints = proposedSemanticHints
-        let currentAttachmentPlacements = proposedAttachmentPlacements
-
-        // 对齐 WXRead：默认按 CTFrame 已经容纳的行数分页，仅保留 pageRelate 这种
-        // 微信读书特有的跨页关联规则；其他 keepWithNext/attachmentBoundary/通用语义边界
-        // 先不参与截断，避免提前裁短页尾内容。
-        if let pageRelateBoundary = preferredPageRelateBoundary(
-            after: proposedRange,
-            minimumEnd: proposedRange.location + 1,
-            lineRanges: lineRanges
-        ) {
-            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: diagnostics(
-                    reason: .semanticBoundary,
-                    range: adjustedRange,
-                    attachmentRanges: currentAttachmentRanges,
-                    blockRange: currentBlockRange,
-                    blockKinds: currentBlockKinds,
-                    semanticHints: currentSemanticHints,
-                    attachmentPlacements: currentAttachmentPlacements,
-                    trigger: RDEPUBTextSemanticHint.pageRelate.rawValue
-                )
-            )
-        }
-
-        // 4. 帧限制（默认分页）
-        return (
-            range: proposedRange,
-            breakReason: .frameLimit,
-            blockRange: currentBlockRange,
-            attachmentRanges: currentAttachmentRanges,
-            attachmentKinds: currentAttachmentKinds,
-            blockKinds: currentBlockKinds,
-            semanticHints: currentSemanticHints,
-            attachmentPlacements: currentAttachmentPlacements,
-            diagnostics: diagnostics(
-                reason: .frameLimit,
-                range: proposedRange,
-                attachmentRanges: currentAttachmentRanges,
-                blockRange: currentBlockRange,
-                blockKinds: currentBlockKinds,
-                semanticHints: currentSemanticHints,
-                attachmentPlacements: currentAttachmentPlacements
-            )
-        )
-    }
-
-    // MARK: - 语义边界查找
-
-    /// 在指定范围内查找最优的语义分页点（pageBreakBefore / pageBreakAfter）。
-    ///
-    /// 只有当边界位置超过 minimumEnd（最小分页长度约束）时才有效。
-    private func preferredSemanticBoundary(
-        in range: NSRange,
-        minimumEnd: Int
-    ) -> (location: Int, trigger: String)? {
-        guard let safeRange = 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
-    }
-
-    /// 查找附件边界：只有块级附件（.attachment 或 .centered）才触发分页，
-    /// 行内脚注图标等不应导致整段移动。
-    private func preferredAttachmentBoundary(in range: NSRange, minimumEnd: Int) -> Int? {
-        guard let safeRange = 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 = attachmentPlacement(at: location)
-            let blockKind = blockKind(at: location)
-
-            // 对标 WXRead：只有块级附件才应将整个块推到下一页。
-            // 行内脚注图标等行内附件不应导致整段移动。
-            // 只有真正的块级附件才需要整块挪页。
-            // 行内/基线对齐的附件（例如脚注 note.png）不能触发附件边界分页。
-            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 = blockRange(at: location) ?? paragraphRange(containing: location)
-            if boundaryRange.location > safeRange.location, boundaryRange.location >= minimumEnd {
-                boundary = boundaryRange.location
-                stop.pointee = true
-            }
-        }
-        return boundary
-    }
-
-    /// 查找 pageRelate 跨页关联边界：当下一页起始是一个 pageRelate 块且
-    /// 该块恰好是当前页最后一行时，将最后一行移到下一页。
-    private func preferredPageRelateBoundary(
-        after range: NSRange,
-        minimumEnd: Int,
-        lineRanges: [NSRange]
-    ) -> Int? {
-        let pageStartOfNext = range.location + range.length
-        guard pageStartOfNext > range.location,
-              pageStartOfNext < attributedString.length,
-              lineRanges.count >= 2,
-              semanticHints(at: pageStartOfNext).contains(.pageRelate) else {
-            return nil
-        }
-
-        let boundaryBlockStart = blockRange(at: pageStartOfNext)?.location ?? 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 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
-    }
-
-    /// 获取指定位置的块级元素类型
-    private 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)
-    }
-
-    /// 获取指定位置的附件布局方式
-    private 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)
-    }
-
-    /// 获取包含指定位置的段落范围
-    private 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))
-    }
-
-    /// 获取指定范围内的所有附件字符范围
-    private 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
-    }
-
-    /// 获取指定位置的语义提示列表
-    private 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)) }
-    }
-
-    /// 获取指定范围内的附件类型列表（去重）
-    private 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
-    }
-
-    /// 获取指定范围内的块级元素类型列表（去重）
-    private 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
-    }
-
-    /// 获取指定范围内的语义提示列表（去重）
-    private 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
-    }
-
-    /// 获取指定范围内的附件布局方式列表（去重）
-    private 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 的合法边界内，避免属性枚举与子串提取越界。
-    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))
-    }
-
-    private func clampedProbeRange(for lineRange: NSRange) -> NSRange? {
-        clampedRange(NSRange(location: lineRange.location, length: max(lineRange.length, 1)))
-    }
-
-    /// 查找指定位置之前最近的 fragment ID（用于阅读位置恢复）
-    private func nearestTrailingFragmentID(
-        endingAt location: Int,
-        fragmentOffsets: [String: Int]
-    ) -> String? {
-        fragmentOffsets
-            .filter { $0.value <= location }
-            .max { lhs, rhs in lhs.value < rhs.value }?
-            .key
-    }
-
-    // MARK: - 行级 avoidPageBreakInside（WXRead 方案）
-
-    /// 从 CTFrame 最后一行向前扫描，移除落在 avoidPageBreakInside 保护块内的尾部行。
-    /// 对标 WXRead 的 WRCoreTextLayoutFrame.avoidPageBreakInsideByRemovingLastLinesIfNeeded。
-    /// 最多移除 3 行（kMaxLinesToRemove），避免因保护块过大导致整页内容被清空。
-    private 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 }
-
-        var origins = [CGPoint](repeating: .zero, count: lines.count)
-        CTFrameGetLineOrigins(frame, CFRangeMake(0, 0), &origins)
-
-        // 从最后一行向前扫描，统计落在保护块内的连续尾部行数
-        // kMaxLinesToRemove = 3（与 WXRead 一致）
-        let kMaxLinesToRemove = 3
-        var linesToRemove = 0
-
-        for i in stride(from: lines.count - 1, through: 0, by: -1) {
-            let lineRange = CTLineGetStringRange(lines[i])
-            let lineNSRange = NSRange(location: lineRange.location, length: lineRange.length)
-
-            if lineIsInAvoidPageBreakInsideBlock(lineNSRange) {
-                linesToRemove += 1
-                if linesToRemove >= kMaxLinesToRemove {
-                    // 不超过 kMaxLinesToRemove 行，停在这里
-                    linesToRemove = kMaxLinesToRemove
-                    break
-                }
-            } else {
-                break
-            }
-        }
-
-        guard linesToRemove > 0 else { return proposed }
-
-        let validLineCount = lines.count - linesToRemove
-        guard validLineCount > 0 else {
-            // 所有行都在保护块内，回退到原始范围
-            return proposed
-        }
-
-        let lastValidLine = lines[validLineCount - 1]
-        let lastLineRange = CTLineGetStringRange(lastValidLine)
-        let endLocation = lastLineRange.location + lastLineRange.length
-        let adjustedLength = endLocation - proposed.location
-
-        guard adjustedLength > 0 else { return proposed }
-
-        return NSRange(location: proposed.location, length: adjustedLength)
-    }
-
-    /// CoreText 路径的 keepWithNext 处理：从最后行向前扫描
-    private 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)
-    }
-
-    // MARK: - DTCoreText 行级处理
-
-#if canImport(DTCoreText)
-    /// DTCoreText 路径的 avoidPageBreakInside 处理
-    private 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 kMaxLinesToRemove = 3
-        var linesToRemove = 0
-
-        for line in lines.reversed() {
-            let lineRange = line.stringRange()
-            if lineIsInAvoidPageBreakInsideBlock(lineRange) {
-                linesToRemove += 1
-                if linesToRemove >= kMaxLinesToRemove {
-                    linesToRemove = kMaxLinesToRemove
-                    break
-                }
-            } else {
-                break
-            }
-        }
-
-        guard linesToRemove > 0 else { return proposed }
-
-        let validLineCount = lines.count - linesToRemove
-        guard validLineCount > 0 else { return proposed }
-
-        let lastValidLine = lines[validLineCount - 1]
-        let lastLineRange = lastValidLine.stringRange()
-        let endLocation = lastLineRange.location + lastLineRange.length
-        let adjustedLength = endLocation - proposed.location
-
-        guard adjustedLength > 0 else { return proposed }
-
-        return NSRange(location: proposed.location, length: adjustedLength)
-    }
-
-    /// DTCoreText 路径的 keepWithNext 处理
-    private 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
-
-    /// 从最后行向前扫描，移除落在 keepWithNext 保护块内的尾部行。
-    /// 最多移除 3 行。
-    private 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 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)
-    }
-
-    /// 检查某行是否落在 avoidPageBreakInside 保护块内
-    private 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
-    }
-
-    /// 只有真正的块级内容才应触发 avoidPageBreakInside。
-    /// 像脚注 note.png 这类行内图片会被标记为 `img`，但不该把整行推到下一页。
-    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
-    }
-
-    /// 检查某行是否落在 keepWithNext 保护块内
-    private 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
-    }
-
-    /// 获取 CTFrame 中所有行的字符范围
-    private 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)
-        }
-    }
-
-    /// 逐句对齐 WXRead `WRChapterPageCount.recalculatePageRangesForAttributedString` 的分页循环：
-    /// 1. 取出 CTFrame 当前页的所有行
-    /// 2. 读取每行 origin
-    /// 3. 用 `lineY - ascent > usableHeight` 判断是否越过可用高度
-    /// 4. 累计能容纳行的字符数得到本页范围
-    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))
-    }
-
-#if canImport(DTCoreText)
-    /// 获取 DTCoreTextLayoutFrame 中所有行的字符范围
-    private func lineRanges(from layoutFrame: DTCoreTextLayoutFrame) -> [NSRange] {
-        guard let lines = layoutFrame.lines as? [DTCoreTextLayoutLine] else {
-            return []
-        }
-        return lines.map { $0.stringRange() }
-    }
-#endif
-
-    // MARK: - 诊断日志
-
-    /// 生成分页诊断日志，记录分页原因、范围和语义信息
-    private 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
-    }
-}

Sources/RDReaderView/EPUBTextRendering/RDEPUBTextRenderer.swift

@@ -100,6 +100,8 @@ public struct RDEPUBTextLayoutConfig: Equatable {
     public var hyphenation: Bool
     /// 图片最大高度占页面高度的比例
     public var imageMaxHeightRatio: CGFloat
+    /// 当调用方暂时拿不到 pageSize 时，用于估算附件尺寸的兜底 viewport。
+    public var fallbackViewportSize: CGSize
 
     public init(
         frameWidth: CGFloat = 0,
@@ -111,7 +113,8 @@ public struct RDEPUBTextLayoutConfig: Equatable {
         avoidWidows: Bool = true,
         avoidPageBreakInsideEnabled: Bool = true,
         hyphenation: Bool = true,
-        imageMaxHeightRatio: CGFloat = 0.85
+        imageMaxHeightRatio: CGFloat = 0.85,
+        fallbackViewportSize: CGSize = CGSize(width: 375, height: 667)
     ) {
         self.frameWidth = frameWidth
         self.frameHeight = frameHeight
@@ -123,6 +126,7 @@ public struct RDEPUBTextLayoutConfig: Equatable {
         self.avoidPageBreakInsideEnabled = avoidPageBreakInsideEnabled
         self.hyphenation = hyphenation
         self.imageMaxHeightRatio = imageMaxHeightRatio
+        self.fallbackViewportSize = fallbackViewportSize
     }
 
     /// 默认配置
@@ -172,7 +176,9 @@ public struct RDEPUBTextLayoutConfig: Equatable {
             avoidWidows ? "1" : "0",
             avoidPageBreakInsideEnabled ? "1" : "0",
             hyphenation ? "1" : "0",
-            String(format: "%.3f", imageMaxHeightRatio)
+            String(format: "%.3f", imageMaxHeightRatio),
+            String(format: "%.3f", fallbackViewportSize.width),
+            String(format: "%.3f", fallbackViewportSize.height)
         ].joined(separator: "|")
     }
 }

Sources/RDReaderView/EPUBTextRendering/RDPlainTextBookBuilder.swift

@@ -43,7 +43,20 @@ public final class RDPlainTextBookBuilder {
 
         for (index, spec) in chapterSpecs.enumerated() {
             let html = wrapTextAsHTML(spec.content)
-            let rendered = try renderer.renderChapter(html: html, baseURL: nil, style: style)
+            let request = RDEPUBTextChapterRenderRequest(
+                context: RDEPUBTextChapterContext(
+                    href: "chapter_\(index).xhtml",
+                    title: spec.title ?? "第 \(index + 1) 章",
+                    html: html,
+                    baseURL: nil,
+                    stylesheet: RDEPUBTextStyleSheetPackage(layers: []),
+                    resourceDiagnostics: []
+                ),
+                style: style,
+                pageSize: pageSize,
+                layoutConfig: layoutConfig
+            )
+            let rendered = try renderer.renderChapter(request: request)
 
             let content = NSMutableAttributedString(attributedString: rendered.attributedString)
             let layoutFrames = content.length > 0 ? content.rd_paginatedFrames(size: pageSize, config: layoutConfig) : []

Sources/RDReaderView/EPUBTextRendering/Typesetter/RDEPUBAttachmentNormalizer.swift

@@ -0,0 +1,187 @@
+import UIKit
+
+#if canImport(DTCoreText)
+import DTCoreText
+#endif
+
+struct RDEPUBAttachmentNormalizer {
+    /// 脚注附件日志已输出标记（避免重复日志）
+    private static var didLogFootnoteAttachment = false
+    /// 封面附件日志已输出标记（避免重复日志）
+    private static var didLogCoverAttachment = false
+
+#if canImport(DTCoreText)
+    func normalize(
+        _ attachment: DTTextAttachment,
+        fontPointSize: CGFloat,
+        maxImageSize: CGSize
+    ) {
+        Self.normalizeAttachmentLayoutForWXRead(
+            attachment,
+            fontPointSize: fontPointSize,
+            maxImageSize: maxImageSize
+        )
+    }
+#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 {
+                didLogFootnoteAttachment = true
+                print("[EPUB][Attachment] footnote original=\(RDEPUBHTMLNormalizer.string(from: originalSize)) display=\(RDEPUBHTMLNormalizer.string(from: attachment.displaySize)) font=\(pointSize)")
+            }
+            return
+        }
+
+        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 {
+                didLogCoverAttachment = true
+                print("[EPUB][Attachment] cover original=\(RDEPUBHTMLNormalizer.string(from: originalSize)) display=\(RDEPUBHTMLNormalizer.string(from: attachment.displaySize))")
+            }
+            return
+        }
+
+        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)
+        }
+
+        if let maxImageSize,
+           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),
+                height: round(resolvedSize.height * scale)
+            )
+        }
+
+        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) {
+            element.displayStyle = .block
+        }
+    }
+
+    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)
+        )
+    }
+#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
+            return
+        }
+#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
+            }
+            return .generic
+        }
+
+        for value in attributes.values {
+            let typeName = String(describing: type(of: value)).lowercased()
+            if typeName.contains("attachment") {
+                return typeName.contains("image") ? .image : .generic
+            }
+        }
+
+        return nil
+    }
+}

Sources/RDReaderView/EPUBTextRendering/Typesetter/RDEPUBFontNormalizer.swift

@@ -0,0 +1,89 @@
+import UIKit
+import CoreText
+
+struct RDEPUBFontNormalizer {
+    /// 已注册字体资源，避免重复调用 CTFontManager。
+    private static var registeredFontPaths = Set<String>()
+
+    func registerEmbeddedFonts(
+        html: String,
+        inlinedCSS: String,
+        input: RDEPUBTypesettingInput
+    ) {
+        Self.registerEmbeddedFonts(
+            in: inlinedCSS + "\n" + Self.inlineStyleCSS(in: html),
+            chapterHref: input.href,
+            resourceResolver: input.resourceResolver
+        )
+    }
+
+    // MARK: - 字体注册
+
+    /// 从 CSS 中解析 @font-face 规则，注册嵌入字体。
+    static func registerEmbeddedFonts(
+        in css: String,
+        chapterHref: String,
+        resourceResolver: RDEPUBResourceResolver?
+    ) {
+        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
+        }
+
+        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
+            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"))
+                guard !rawReference.isEmpty,
+                      !rawReference.hasPrefix("data:"),
+                      !rawReference.hasPrefix("http://"),
+                      !rawReference.hasPrefix("https://"),
+                      let fileURL = resourceResolver.fileURL(forReference: rawReference, relativeToHref: chapterHref) else {
+                    continue
+                }
+                registerFontIfNeeded(at: fileURL)
+            }
+        }
+    }
+
+    static func registerFontIfNeeded(at fileURL: URL) {
+        let standardizedPath = fileURL.standardizedFileURL.path
+        guard !registeredFontPaths.contains(standardizedPath) else { return }
+        CTFontManagerRegisterFontsForURL(fileURL as CFURL, .process, nil)
+        registeredFontPaths.insert(standardizedPath)
+    }
+
+    // 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 }
+                return nsHTML.substring(with: match.range(at: 1))
+            }
+            .joined(separator: "\n")
+    }
+}

Sources/RDReaderView/EPUBTextRendering/Typesetter/RDEPUBFragmentMarkerInjector.swift

@@ -0,0 +1,59 @@
+import Foundation
+
+struct RDEPUBFragmentMarkerInjector: RDEPUBTypesettingStage {
+    func process(_ html: String, context: RDEPUBTypesettingInput) -> String {
+        Self.injectFragmentMarkers(into: html)
+    }
+
+    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
+        }
+        return regex.stringByReplacingMatches(
+            in: html,
+            options: [],
+            range: NSRange(location: 0, length: html.utf16.count),
+            withTemplate: "${id=$2}$1"
+        )
+    }
+
+    // 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)
+        }
+
+        return fragmentOffsets
+    }
+}

Sources/RDReaderView/EPUBTextRendering/Typesetter/RDEPUBHTMLNormalizer.swift

@@ -0,0 +1,214 @@
+import Foundation
+
+struct RDEPUBHTMLNormalizer: RDEPUBTypesettingStage {
+    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")
+        ]
+
+        for replacement in replacements {
+            if let regex = try? NSRegularExpression(pattern: replacement.pattern, options: [.caseInsensitive]) {
+                cleanedHTML = regex.stringByReplacingMatches(
+                    in: cleanedHTML,
+                    options: [],
+                    range: NSRange(location: 0, length: cleanedHTML.utf16.count),
+                    withTemplate: replacement.template
+                )
+            }
+        }
+
+        cleanedHTML = normalizeAttachmentHTMLMarkers(in: cleanedHTML)
+        return cleanedHTML
+    }
+
+    // MARK: - 附件 HTML 标记规范化
+
+    /// 处理 bodyPic div、脚注 img、封面 h1+img 等特殊 HTML 结构。
+    private static func normalizeAttachmentHTMLMarkers(in html: String) -> String {
+        var normalized = html
+
+        if let bodyPicContainerRegex = try? NSRegularExpression(
+            pattern: #"<div\b([^>]*class\s*=\s*["'][^"']*\b(?:qrbodyPic|bodyPic)\b[^"']*["'][^>]*)>([\s\S]*?)</div>"#,
+            options: [.caseInsensitive]
+        ) {
+            normalized = replaceMatches(
+                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
+                ) { imageTag in
+                    mergeHTMLAttributes(
+                        into: imageTag,
+                        requiredClass: "bodyPic",
+                        styleFragments: [
+                            "wr-vertical-center-style:2",
+                            "max-width:100%",
+                            "height:auto",
+                            "display:block",
+                            "margin-left:auto",
+                            "margin-right:auto"
+                        ]
+                    )
+                }
+            }
+        }
+
+        if let footnoteRegex = try? NSRegularExpression(
+            pattern: #"<img\b([^>]*class\s*=\s*["'][^"']*\bqqreader-footnote\b[^"']*["'][^>]*)>"#,
+            options: [.caseInsensitive]
+        ) {
+            normalized = replaceMatches(
+                using: footnoteRegex,
+                in: normalized
+            ) { tag in
+                mergeHTMLAttributes(
+                    into: tag,
+                    requiredClass: nil,
+                    styleFragments: [
+                        "width:1em",
+                        "height:1em",
+                        "vertical-align:middle",
+                        "display:inline-block"
+                    ]
+                )
+            }
+        }
+
+        if let coverRegex = try? NSRegularExpression(
+            pattern: #"<h1\b([^>]*class\s*=\s*["'][^"']*\bfrontCover\b[^"']*["'][^>]*)>\s*(<img\b[^>]*>)\s*</h1>"#,
+            options: [.caseInsensitive]
+        ) {
+            normalized = replaceMatches(
+                using: coverRegex,
+                in: normalized
+            ) { tag in
+                guard let imageTagRegex = try? NSRegularExpression(pattern: #"<img\b[^>]*>"#, options: [.caseInsensitive]),
+                      let imageMatch = imageTagRegex.firstMatch(
+                        in: tag,
+                        options: [],
+                        range: NSRange(location: 0, length: (tag as NSString).length)
+                      ),
+                      let imageRange = Range(imageMatch.range, in: tag) else {
+                    return tag
+                }
+
+                let imageTag = String(tag[imageRange])
+                let normalizedImageTag = mergeHTMLAttributes(
+                    into: imageTag,
+                    requiredClass: "rd-front-cover-image",
+                    styleFragments: [
+                        "display:block",
+                        "width:100%",
+                        "height:auto",
+                        "margin-left:auto",
+                        "margin-right:auto"
+                    ]
+                )
+                return tag.replacingCharacters(in: imageRange, with: normalizedImageTag)
+            }
+        }
+
+        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 }
+
+        var rewritten = source
+        for match in matches.reversed() {
+            guard let range = Range(match.range, in: rewritten) else { continue }
+            let original = String(rewritten[range])
+            rewritten.replaceSubrange(range, with: transform(original))
+        }
+        return rewritten
+    }
+
+    /// 合并 HTML 标签的 class 和 style 属性。
+    static func mergeHTMLAttributes(
+        into tag: String,
+        requiredClass: String?,
+        styleFragments: [String]
+    ) -> String {
+        var rewritten = tag
+        if let requiredClass {
+            if let classRegex = try? NSRegularExpression(pattern: #"class\s*=\s*["']([^"']*)["']"#, options: [.caseInsensitive]),
+               let match = classRegex.firstMatch(in: rewritten, options: [], range: NSRange(location: 0, length: (rewritten as NSString).length)),
+               match.numberOfRanges > 1 {
+                let existingClasses = (rewritten as NSString).substring(with: match.range(at: 1))
+                if !existingClasses.localizedCaseInsensitiveContains(requiredClass) {
+                    let replacement = #"class="\#(existingClasses) \#(requiredClass)""#
+                    if let range = Range(match.range, in: rewritten) {
+                        rewritten.replaceSubrange(range, with: replacement)
+                    }
+                }
+            } else if let closing = rewritten.lastIndex(of: ">") {
+                rewritten.insert(contentsOf: #" class="\#(requiredClass)""#, at: closing)
+            }
+        }
+
+        let styleValue = styleFragments.joined(separator: ";") + ";"
+        if let styleRegex = try? NSRegularExpression(pattern: #"style\s*=\s*["']([^"']*)["']"#, options: [.caseInsensitive]),
+           let match = styleRegex.firstMatch(in: rewritten, options: [], range: NSRange(location: 0, length: (rewritten as NSString).length)),
+           match.numberOfRanges > 1 {
+            let existing = (rewritten as NSString).substring(with: match.range(at: 1)).trimmingCharacters(in: .whitespacesAndNewlines)
+            let merged = existing.isEmpty ? styleValue : existing + (existing.hasSuffix(";") ? "" : ";") + styleValue
+            let replacement = #"style="\#(merged)""#
+            if let range = Range(match.range, in: rewritten) {
+                rewritten.replaceSubrange(range, with: replacement)
+            }
+        } else if let closing = rewritten.lastIndex(of: ">") {
+            rewritten.insert(contentsOf: #" style="\#(styleValue)""#, at: closing)
+        }
+
+        return rewritten
+    }
+
+    /// 注入 `<base>` 标签以解析相对路径。
+    static func injectBaseHref(into html: String, baseURL: URL?) -> String {
+        guard let baseURL else {
+            return html
+        }
+        let baseTag = "<base href=\"\(baseURL.absoluteString)\">"
+        if html.range(of: "<base ", options: [.caseInsensitive]) != nil {
+            return html
+        }
+        if html.range(of: "<head>", options: [.caseInsensitive]) != nil {
+            return html.replacingOccurrences(of: "<head>", with: "<head>\n\(baseTag)", options: [.caseInsensitive])
+        }
+        if let htmlTagRange = html.range(of: "<html", options: [.caseInsensitive]),
+           let htmlRange = html.range(of: ">", range: htmlTagRange.lowerBound..<html.endIndex) {
+            return html.replacingCharacters(in: htmlRange.upperBound..<htmlRange.upperBound, with: "\n<head>\n\(baseTag)\n</head>")
+        }
+        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

@@ -0,0 +1,162 @@
+import Foundation
+
+struct RDEPUBRenderDiagnosticsCollector {
+    /// 外部样式表链接正则
+    private static let stylesheetLinkPattern = #"<link\b[^>]*rel\s*=\s*["'][^"']*stylesheet[^"']*["'][^>]*href\s*=\s*["']([^"']+)["'][^>]*>"#
+    /// 图片源地址正则
+    private static let imageSourcePattern = #"<img\b[^>]*src\s*=\s*["']([^"']+)["'][^>]*>"#
+
+    func collect(
+        in html: String,
+        input: RDEPUBTypesettingInput
+    ) -> [RDEPUBTextResourceReferenceDiagnostic] {
+        Self.collectImageDiagnostics(
+            in: html,
+            chapterHref: input.href,
+            baseURL: input.baseURL,
+            resourceResolver: input.resourceResolver
+        )
+    }
+
+    // MARK: - 图片诊断
+
+    /// 扫描 HTML 中的 <img> 标签，构建资源引用诊断。
+    static func collectImageDiagnostics(
+        in html: String,
+        chapterHref: String,
+        baseURL: URL?,
+        resourceResolver: RDEPUBResourceResolver?
+    ) -> [RDEPUBTextResourceReferenceDiagnostic] {
+        guard let regex = try? NSRegularExpression(pattern: imageSourcePattern, options: [.caseInsensitive]) else {
+            return []
+        }
+        let nsHTML = html as NSString
+        return regex.matches(in: html, options: [], range: NSRange(location: 0, length: nsHTML.length)).compactMap { match in
+            guard match.numberOfRanges > 1 else { return nil }
+            let href = nsHTML.substring(with: match.range(at: 1))
+            return resolveReference(
+                href,
+                kind: .image,
+                chapterHref: chapterHref,
+                baseURL: baseURL,
+                resourceResolver: resourceResolver
+            ).diagnostic
+        }
+    }
+
+    // MARK: - 外部样式表内联
+
+    /// 查找 `<link rel=stylesheet>` 标签，内联 CSS 内容。
+    static func inlineLinkedStyleSheets(
+        in html: String,
+        chapterHref: String,
+        baseURL: URL?,
+        resourceResolver: RDEPUBResourceResolver?
+    ) -> (html: String, inlinedCSS: String, diagnostics: [RDEPUBTextResourceReferenceDiagnostic]) {
+        guard let regex = try? NSRegularExpression(pattern: stylesheetLinkPattern, options: [.caseInsensitive]) else {
+            return (html, "", [])
+        }
+
+        let nsHTML = html as NSString
+        let matches = regex.matches(in: html, options: [], range: NSRange(location: 0, length: nsHTML.length))
+        guard !matches.isEmpty else {
+            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))
+            let resolution = resolveReference(
+                href,
+                kind: .stylesheet,
+                chapterHref: chapterHref,
+                baseURL: baseURL,
+                resourceResolver: resourceResolver
+            )
+            diagnostics.append(resolution.diagnostic)
+
+            if let fileURL = resolution.resolvedFileURL,
+               let css = try? String(contentsOf: fileURL),
+               resolution.diagnostic.existsOnDisk {
+                let cssWithResolvedURLs = rewriteCSSResourceURLs(
+                    in: css,
+                    styleSheetFileURL: fileURL
+                )
+                inlinedCSSBlocks.append(cssWithResolvedURLs)
+            }
+
+            if let range = Range(match.range, in: rewrittenHTML) {
+                rewrittenHTML.replaceSubrange(range, with: "")
+            }
+        }
+
+        return (rewrittenHTML, inlinedCSSBlocks.reversed().joined(separator: "\n\n"), diagnostics.reversed())
+    }
+
+    // MARK: - CSS 资源 URL 重写
+
+    /// 重写 CSS 中的相对 url() 引用，解析为绝对文件路径。
+    static func rewriteCSSResourceURLs(
+        in css: String,
+        styleSheetFileURL: URL
+    ) -> String {
+        guard let regex = try? NSRegularExpression(pattern: #"url\(([^)]+)\)"#, options: [.caseInsensitive]) else {
+            return css
+        }
+
+        let nsCSS = css as NSString
+        let matches = regex.matches(in: css, options: [], range: NSRange(location: 0, length: nsCSS.length))
+        guard !matches.isEmpty else {
+            return css
+        }
+
+        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("#") {
+                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)
+            }
+        }
+        return rewrittenCSS
+    }
+
+    // MARK: - 资源引用解析
+
+    static func resolveReference(
+        _ reference: String,
+        kind: RDEPUBTextResourceReferenceKind,
+        chapterHref: String,
+        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,
+            originalReference: trimmedReference,
+            normalizedHref: normalizedHref,
+            resolvedFileURL: resolvedFileURL,
+            existsOnDisk: existsOnDisk
+        )
+        return (normalizedHref, resolvedFileURL, diagnostic)
+    }
+}

Sources/RDReaderView/EPUBTextRendering/Typesetter/RDEPUBSemanticMarkerInjector.swift

@@ -0,0 +1,332 @@
+import Foundation
+import UIKit
+
+struct RDEPUBSemanticMarkerInjector: RDEPUBTypesettingStage {
+    /// 语义标记正则（${rd-sem-start:...} / ${rd-sem-end:...}）
+    private static let semanticMarkerPattern = #"\$\{rd-sem-(start|end):([^}]+)\}"#
+
+    func process(_ html: String, context: RDEPUBTypesettingInput) -> String {
+        Self.injectPaginationSemanticMarkers(into: html)
+    }
+
+    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
+        }
+
+        let nsHTML = html as NSString
+        let matches = regex.matches(in: html, options: [], range: NSRange(location: 0, length: nsHTML.length))
+        guard !matches.isEmpty else {
+            return html
+        }
+
+        var output = ""
+        var cursor = 0
+        var openTagStack: [(name: String, id: String)] = []
+        var nextMarkerID = 0
+
+        for match in matches {
+            let tagRange = match.range
+            guard tagRange.location >= cursor else { continue }
+            output += nsHTML.substring(with: NSRange(location: cursor, length: tagRange.location - cursor))
+
+            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)
+                }
+                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
+            }
+
+            cursor = tagRange.location + tagRange.length
+        }
+
+        output += nsHTML.substring(from: cursor)
+        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)
+                    if length > 0 {
+                        apply(semantics: opened.semantics, to: NSRange(location: opened.location, length: length), in: attributedString)
+                    }
+                }
+            }
+
+            searchRange = NSRange(location: markerLocation, length: mutableString.length - markerLocation)
+        }
+    }
+
+    // MARK: - 语义推断
+
+    static func htmlTagName(from loweredTag: String) -> String? {
+        let trimmed = loweredTag.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard trimmed.hasPrefix("<") else { return nil }
+        let body = trimmed.dropFirst().drop(while: { $0 == "/" || $0 == "!" || $0 == "?" })
+        let name = body.prefix { $0.isLetter || $0.isNumber }
+        return name.isEmpty ? nil : String(name)
+    }
+
+    private static func paginationSemantics(forTagName tagName: String, rawTag: String) -> RDPaginationSemantics? {
+        let loweredTag = rawTag.lowercased()
+        let blockKind = inferredBlockKind(forTagName: tagName, rawTag: loweredTag)
+        let hints = inferredHints(forTagName: tagName, rawTag: loweredTag)
+        let placement = inferredAttachmentPlacement(forTagName: tagName, rawTag: loweredTag)
+
+        guard blockKind != nil || !hints.isEmpty || placement != nil else {
+            return nil
+        }
+
+        return RDPaginationSemantics(
+            id: "",
+            blockKind: blockKind,
+            hints: hints,
+            attachmentPlacement: placement
+        )
+    }
+
+    private static func inferredBlockKind(forTagName tagName: String, rawTag: String) -> RDEPUBTextBlockKind? {
+        if rawTag.contains("bodypic") || tagName == "img" || tagName == "figure" {
+            return .attachment
+        }
+        switch tagName {
+        case "h1", "h2", "h3", "h4", "h5", "h6":
+            return .generic
+        case "blockquote":
+            return .blockquote
+        case "ul", "ol", "li":
+            return .list
+        case "table", "thead", "tbody", "tfoot", "tr", "td", "th":
+            return .table
+        case "pre", "code":
+            return .code
+        case "p":
+            return .paragraph
+        case "div":
+            if rawTag.contains("code") || rawTag.contains("highlight") {
+                return .code
+            }
+            if rawTag.contains("quote") || rawTag.contains("blockquote") {
+                return .blockquote
+            }
+            if rawTag.contains("table") {
+                return .table
+            }
+            if rawTag.contains("list") {
+                return .list
+            }
+            return .generic
+        default:
+            return nil
+        }
+    }
+
+    private static func inferredHints(forTagName tagName: String, rawTag: String) -> [RDEPUBTextSemanticHint] {
+        var hints: [RDEPUBTextSemanticHint] = []
+        if rawTag.contains("avoidpagebreakinside") ||
+            rawTag.contains("break-inside: avoid") ||
+            rawTag.contains("page-break-inside: avoid") ||
+            ["blockquote", "pre", "code", "table", "ul", "ol", "figure", "img"].contains(tagName) {
+            hints.append(.avoidPageBreakInside)
+        }
+        if ["h1", "h2", "h3", "h4", "h5", "h6"].contains(tagName) ||
+            rawTag.contains("subhead") ||
+            rawTag.contains("firsttitle") ||
+            rawTag.contains("secondtitle") ||
+            rawTag.contains("thirdtitle") ||
+            rawTag.contains("fourthtitle") ||
+            rawTag.contains("fifthtitle") ||
+            rawTag.contains("sixthtitle") {
+            hints.append(.keepWithNext)
+        }
+        if rawTag.contains("pagebreakbefore") ||
+            rawTag.contains("page-break-before: always") ||
+            rawTag.contains("break-before: page") {
+            hints.append(.pageBreakBefore)
+        }
+        if rawTag.contains("pagebreakafter") ||
+            rawTag.contains("page-break-after: always") ||
+            rawTag.contains("break-after: page") {
+            hints.append(.pageBreakAfter)
+        }
+        if rawTag.contains("pageRelate".lowercased()) || rawTag.contains("weread-page-relate") {
+            hints.append(.pageRelate)
+        }
+        return hints
+            .reduce(into: [RDEPUBTextSemanticHint]()) { result, hint in
+                if !result.contains(hint) {
+                    result.append(hint)
+                }
+            }
+            .sorted { $0.rawValue < $1.rawValue }
+    }
+
+    private static func inferredAttachmentPlacement(forTagName tagName: String, rawTag: String) -> RDEPUBTextAttachmentPlacement? {
+        guard tagName == "img" || rawTag.contains("bodypic") || rawTag.contains("wr-vertical-center") else {
+            return nil
+        }
+        if rawTag.contains("wr-vertical-center-style: 2") || rawTag.contains("bodypic") {
+            return .centered
+        }
+        if rawTag.contains("wr-vertical-center-style: 1") || rawTag.contains("wr-vertical-center") {
+            return .baseline
+        }
+        return .inline
+    }
+
+    private static func isVoidHTMLTag(_ tagName: String) -> Bool {
+        ["img", "br", "hr", "input", "meta", "link"].contains(tagName)
+    }
+
+    private static func semanticStartMarker(id: String, semantics: RDPaginationSemantics) -> String {
+        var segments = ["id=\(id)"]
+        if let blockKind = semantics.blockKind {
+            segments.append("block=\(blockKind.rawValue)")
+        }
+        if !semantics.hints.isEmpty {
+            segments.append("hints=\(semantics.hints.map(\.rawValue).joined(separator: ","))")
+        }
+        if let placement = semantics.attachmentPlacement {
+            segments.append("placement=\(placement.rawValue)")
+        }
+        return "${rd-sem-start:\(segments.joined(separator: ";"))}"
+    }
+
+    private static func semanticEndMarker(id: String) -> String {
+        "${rd-sem-end:id=\(id)}"
+    }
+
+    private static func parseSemanticMarkerPayload(_ payload: String) -> RDPaginationSemantics {
+        var values: [String: String] = [:]
+        payload.split(separator: ";").forEach { entry in
+            let parts = entry.split(separator: "=", maxSplits: 1)
+            guard parts.count == 2 else { return }
+            values[String(parts[0])] = String(parts[1])
+        }
+        let blockKind = values["block"].flatMap(RDEPUBTextBlockKind.init(rawValue:))
+        let hints = values["hints"]?
+            .split(separator: ",")
+            .compactMap { RDEPUBTextSemanticHint(rawValue: String($0)) } ?? []
+        let placement = values["placement"].flatMap(RDEPUBTextAttachmentPlacement.init(rawValue:))
+        return RDPaginationSemantics(
+            id: values["id"] ?? UUID().uuidString,
+            blockKind: blockKind,
+            hints: hints,
+            attachmentPlacement: placement
+        )
+    }
+
+    private static func parseSemanticEndID(_ payload: String) -> String? {
+        payload.split(separator: ";").first { $0.hasPrefix("id=") }.map { String($0.dropFirst(3)) }
+    }
+
+    private static func apply(
+        semantics: RDPaginationSemantics,
+        to range: NSRange,
+        in attributedString: NSMutableAttributedString
+    ) {
+        var attributes: [NSAttributedString.Key: Any] = [:]
+        attributes[.rdPageBlockRange] = NSStringFromRange(range)
+        if let blockKind = semantics.blockKind {
+            attributes[.rdPageBlockKind] = blockKind.rawValue
+        }
+        if !semantics.hints.isEmpty {
+            attributes[.rdPageSemanticHints] = semantics.hints.map(\.rawValue).joined(separator: ",")
+        }
+        if let placement = semantics.attachmentPlacement {
+            attributes[.rdPageAttachmentPlacement] = placement.rawValue
+        }
+        guard !attributes.isEmpty else { return }
+        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) {
+            return blockKind
+        }
+        return nil
+    }
+
+    /// 推断语义提示列表。
+    static func normalizeSemanticHints(for attributes: [NSAttributedString.Key: Any]) -> [RDEPUBTextSemanticHint]? {
+        if let rawValue = attributes[.rdPageSemanticHints] as? String {
+            let hints = rawValue
+                .split(separator: ",")
+                .compactMap { RDEPUBTextSemanticHint(rawValue: String($0)) }
+            return hints.isEmpty ? nil : hints
+        }
+        return nil
+    }
+
+    /// 推断附件放置方式。
+    static func normalizeAttachmentPlacement(for attributes: [NSAttributedString.Key: Any]) -> RDEPUBTextAttachmentPlacement? {
+        if let rawValue = attributes[.rdPageAttachmentPlacement] as? String,
+           let placement = RDEPUBTextAttachmentPlacement(rawValue: rawValue) {
+            return placement
+        }
+        if let attachmentKind = RDEPUBAttachmentNormalizer.attachmentKind(for: attributes), attachmentKind == .image {
+            return .inline
+        }
+        return nil
+    }
+
+    // MARK: - 内部类型
+
+    struct RDPaginationSemantics {
+        var id: String
+        var blockKind: RDEPUBTextBlockKind?
+        var hints: [RDEPUBTextSemanticHint]
+        var attachmentPlacement: RDEPUBTextAttachmentPlacement?
+    }
+}

Sources/RDReaderView/EPUBTextRendering/Typesetter/RDEPUBStyleSheetComposer.swift

@@ -0,0 +1,288 @@
+import UIKit
+
+struct RDEPUBStyleSheetComposition {
+    var html: String
+    var layers: [RDEPUBTextStyleSheetLayer]
+    var inlinedCSS: String
+    var diagnostics: [RDEPUBTextResourceReferenceDiagnostic]
+}
+
+struct RDEPUBStyleSheetComposer {
+    func compose(html: String, input: RDEPUBTypesettingInput) -> RDEPUBStyleSheetComposition {
+        let stylesheetHrefReplacements = RDEPUBRenderDiagnosticsCollector.inlineLinkedStyleSheets(
+            in: html,
+            chapterHref: input.href,
+            baseURL: input.baseURL,
+            resourceResolver: input.resourceResolver
+        )
+        let layers = Self.makeStyleSheetLayers(
+            style: input.style,
+            epubCSS: stylesheetHrefReplacements.inlinedCSS,
+            contentLanguageCode: input.contentLanguageCode,
+            sourceHTML: input.rawHTML
+        )
+        let htmlWithBase = RDEPUBHTMLNormalizer.injectBaseHref(
+            into: stylesheetHrefReplacements.html,
+            baseURL: input.baseURL
+        )
+        let htmlWithDefaultLayers = Self.injectStyleTag(
+            into: htmlWithBase,
+            styleID: "rd-native-default-replace-dark",
+            css: layers
+                .filter { $0.kind != .user && $0.kind != .epub }
+                .map(\.css)
+                .joined(separator: "\n\n"),
+            position: .headStart
+        )
+        let htmlWithEPUBLayer = Self.injectStyleTag(
+            into: htmlWithDefaultLayers,
+            styleID: "rd-native-epub",
+            css: layers.first(where: { $0.kind == .epub })?.css ?? "",
+            position: .headEnd
+        )
+        let composedHTML = Self.injectStyleTag(
+            into: htmlWithEPUBLayer,
+            styleID: "rd-native-user",
+            css: layers.first(where: { $0.kind == .user })?.css ?? "",
+            position: .headEnd
+        )
+
+        return RDEPUBStyleSheetComposition(
+            html: composedHTML,
+            layers: layers,
+            inlinedCSS: stylesheetHrefReplacements.inlinedCSS,
+            diagnostics: stylesheetHrefReplacements.diagnostics
+        )
+    }
+
+    // MARK: - CSS 层组装
+
+    /// 构建五层 CSS 数组（default/replace/dark/epub/user）。
+    static func makeStyleSheetLayers(
+        style: RDEPUBTextRenderStyle,
+        epubCSS: String,
+        contentLanguageCode: String?,
+        sourceHTML: String
+    ) -> [RDEPUBTextStyleSheetLayer] {
+        let useLatinReplace = prefersLatinLanguageCSS(
+            languageCode: contentLanguageCode,
+            sourceHTML: sourceHTML
+        )
+        var layers: [RDEPUBTextStyleSheetLayer] = [
+            .init(kind: .default, css: defaultCSS()),
+            .init(kind: .replace, css: replaceCSS(useLatinVariant: useLatinReplace))
+        ]
+        if isDarkTheme(style: style) {
+            layers.append(.init(kind: .dark, css: darkCSS(style: style)))
+        }
+        if !epubCSS.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty {
+            layers.append(.init(kind: .epub, css: epubCSS))
+        }
+        layers.append(.init(kind: .user, css: userCSS(style: style)))
+        return layers
+    }
+
+    // MARK: - Style 注入
+
+    enum StyleInjectionPosition {
+        case headStart
+        case headEnd
+    }
+
+    /// 向 HTML 注入 <style> 标签。
+    static func injectStyleTag(
+        into html: String,
+        styleID: String,
+        css: String,
+        position: StyleInjectionPosition
+    ) -> String {
+        let trimmedCSS = css.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !trimmedCSS.isEmpty else {
+            return html
+        }
+
+        let styleTag = "<style id=\"\(styleID)\">\n\(trimmedCSS)\n</style>"
+        switch position {
+        case .headStart:
+            if html.range(of: "<head>", options: [.caseInsensitive]) != nil {
+                return html.replacingOccurrences(of: "<head>", with: "<head>\n\(styleTag)", options: [.caseInsensitive])
+            }
+        case .headEnd:
+            if html.range(of: "</head>", options: [.caseInsensitive]) != nil {
+                return html.replacingOccurrences(of: "</head>", with: "\(styleTag)\n</head>", options: [.caseInsensitive])
+            }
+        }
+
+        if html.range(of: "<body", options: [.caseInsensitive]) != nil {
+            return html.replacingOccurrences(of: "<body", with: "\(styleTag)\n<body", options: [.caseInsensitive])
+        }
+        return styleTag + "\n" + html
+    }
+
+    // MARK: - 各层 CSS
+
+    private static func defaultCSS() -> String {
+        RDEPUBAssetRepository.string(for: .wxReadDefaultCSS)
+    }
+
+    private static func replaceCSS(useLatinVariant: Bool) -> String {
+        let asset: RDEPUBAsset = useLatinVariant ? .wxReadLatinReplaceCSS : .wxReadReplaceCSS
+        return RDEPUBAssetRepository.string(for: asset)
+    }
+
+    private static func darkCSS(style: RDEPUBTextRenderStyle) -> String {
+        let background = style.backgroundColor?.ss_cssString ?? "rgba(0, 0, 0, 1.000)"
+        let text = style.textColor?.ss_cssString ?? "rgba(255, 255, 255, 1.000)"
+        return RDEPUBAssetRepository.string(for: .wxReadDarkCSS) + "\n\n" + """
+        html, body {
+          background: \(background) !important;
+          color: \(text) !important;
+        }
+        a {
+          color: \(text) !important;
+        }
+        """
+    }
+
+    private static func userCSS(style: RDEPUBTextRenderStyle) -> String {
+        let lineHeight = max((style.font.lineHeight + style.lineSpacing) / max(style.font.lineHeight, 1), 1)
+        let text = style.textColor.map { "color: \($0.ss_cssString) !important;" } ?? ""
+        let background = style.backgroundColor.map { "background: \($0.ss_cssString) !important;" } ?? ""
+        return """
+        html, body {
+          font-family: "\(style.font.familyName)" !important;
+          font-size: \(String(format: "%.3f", style.font.pointSize))px !important;
+          line-height: \(String(format: "%.3f", lineHeight)) !important;
+          \(text)
+          \(background)
+        }
+        """
+    }
+
+    private static func isDarkTheme(style: RDEPUBTextRenderStyle) -> Bool {
+        guard let backgroundColor = style.backgroundColor else {
+            return false
+        }
+        var red: CGFloat = 0
+        var green: CGFloat = 0
+        var blue: CGFloat = 0
+        var alpha: CGFloat = 0
+        backgroundColor.getRed(&red, green: &green, blue: &blue, alpha: &alpha)
+        let luminance = (0.299 * red) + (0.587 * green) + (0.114 * blue)
+        return luminance < 0.5
+    }
+
+    // MARK: - 语言检测
+
+    private static func prefersLatinLanguageCSS(
+        languageCode: String?,
+        sourceHTML: String
+    ) -> Bool {
+        let candidateCodes = inferredLanguageCodes(
+            explicitLanguageCode: languageCode,
+            sourceHTML: sourceHTML
+        )
+
+        if candidateCodes.contains(where: isExplicitLatinLanguageCode) {
+            return true
+        }
+        if candidateCodes.contains(where: isExplicitCJKLanguageCode) {
+            return false
+        }
+
+        let textSample = plainTextSample(from: sourceHTML)
+        guard !textSample.isEmpty else { return false }
+
+        var alphabeticCount = 0
+        var latinCount = 0
+        for scalar in textSample.unicodeScalars {
+            guard CharacterSet.letters.contains(scalar) else { continue }
+            alphabeticCount += 1
+            if isLatinScalar(scalar) {
+                latinCount += 1
+            }
+        }
+
+        guard alphabeticCount >= 80 else { return false }
+        return (Double(latinCount) / Double(alphabeticCount)) >= 0.6
+    }
+
+    private static func inferredLanguageCodes(
+        explicitLanguageCode: String?,
+        sourceHTML: String
+    ) -> [String] {
+        var codes: [String] = []
+        if let explicitLanguageCode {
+            let normalized = explicitLanguageCode.trimmingCharacters(in: .whitespacesAndNewlines).lowercased()
+            if !normalized.isEmpty {
+                codes.append(normalized)
+            }
+        }
+
+        if let regex = try? NSRegularExpression(
+            pattern: #"\b(?:xml:lang|lang)\s*=\s*["']([^"']+)["']"#,
+            options: [.caseInsensitive]
+        ) {
+            let nsHTML = sourceHTML as NSString
+            let range = NSRange(location: 0, length: min(nsHTML.length, 8_000))
+            for match in regex.matches(in: sourceHTML, options: [], range: range) {
+                guard match.numberOfRanges > 1 else { continue }
+                let code = nsHTML.substring(with: match.range(at: 1))
+                    .trimmingCharacters(in: .whitespacesAndNewlines)
+                    .lowercased()
+                if !code.isEmpty {
+                    codes.append(code)
+                }
+            }
+        }
+
+        return Array(NSOrderedSet(array: codes)) as? [String] ?? codes
+    }
+
+    private static func isExplicitLatinLanguageCode(_ code: String) -> Bool {
+        let normalized = code.lowercased()
+        if normalized.contains("latn") {
+            return true
+        }
+
+        let prefix = normalized.split(separator: "-").first.map(String.init) ?? normalized
+        let latinPrefixes: Set<String> = [
+            "en", "fr", "de", "es", "it", "pt", "nl", "sv", "da", "no", "fi",
+            "is", "ga", "cy", "pl", "cs", "sk", "sl", "hr", "hu", "ro", "tr",
+            "vi", "id", "ms", "tl", "sw", "af", "sq", "et", "lv", "lt"
+        ]
+        return latinPrefixes.contains(prefix)
+    }
+
+    private static func isExplicitCJKLanguageCode(_ code: String) -> Bool {
+        let prefix = code.lowercased().split(separator: "-").first.map(String.init) ?? code.lowercased()
+        return ["zh", "ja", "ko"].contains(prefix)
+    }
+
+    private static func plainTextSample(from html: String) -> String {
+        let maxLength = min(html.count, 20_000)
+        let sample = String(html.prefix(maxLength))
+        let withoutTags = sample.replacingOccurrences(
+            of: #"<[^>]+>"#,
+            with: " ",
+            options: .regularExpression
+        )
+        return withoutTags.replacingOccurrences(
+            of: #"&[A-Za-z0-9#]+;"#,
+            with: " ",
+            options: .regularExpression
+        )
+    }
+
+    private static func isLatinScalar(_ scalar: UnicodeScalar) -> Bool {
+        switch scalar.value {
+        case 0x0041...0x007A,
+             0x00C0...0x00FF,
+             0x0100...0x024F,
+             0x1E00...0x1EFF:
+            return true
+        default:
+            return false
+        }
+    }
+}

Sources/RDReaderView/EPUBTextRendering/Typesetter/RDEPUBTextRendererSupport.swift

@@ -0,0 +1,167 @@
+import UIKit
+import CoreText
+
+#if canImport(DTCoreText)
+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,
+        rawHTML: String,
+        baseURL: URL?,
+        style: RDEPUBTextRenderStyle,
+        resourceResolver: RDEPUBResourceResolver?,
+        contentLanguageCode: String? = nil,
+        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",
+            css: layers
+                .filter { $0.kind != .user && $0.kind != .epub }
+                .map(\.css)
+                .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,
+            baseURL: baseURL,
+            resourceResolver: resourceResolver
+        )
+
+        let context = RDEPUBTextChapterContext(
+            href: href,
+            title: title,
+            html: markedHTML,
+            baseURL: baseURL,
+            stylesheet: RDEPUBTextStyleSheetPackage(layers: layers),
+            resourceDiagnostics: resourceDiagnostics
+        )
+        return RDEPUBTextChapterRenderRequest(
+            context: context,
+            style: style,
+            pageSize: pageSize,
+            layoutConfig: layoutConfig
+        )
+    }
+
+    // MARK: - 后渲染归一化（由 RDEPUBDTCoreTextRenderer 调用）
+
+    /// 规范化阅读属性：统一字体、行距、颜色，并注入分页语义属性。
+    static func normalizeReadingAttributes(in attributedString: NSMutableAttributedString, style: RDEPUBTextRenderStyle) {
+        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)
+
+            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),
+            .foregroundColor: style.textColor ?? UIColor.black
+        ]
+        return NSMutableAttributedString(string: html, attributes: fallbackAttributes)
+    }
+
+    /// 构建共享段落样式。
+    static func paragraphStyle(lineSpacing: CGFloat) -> NSMutableParagraphStyle {
+        let style = NSMutableParagraphStyle()
+        style.lineSpacing = lineSpacing
+        style.paragraphSpacing = max(6, lineSpacing / 2)
+        return style
+    }
+}

Sources/RDReaderView/EPUBTextRendering/Typesetter/RDEPUBTypesettingPipeline.swift

@@ -0,0 +1,65 @@
+import UIKit
+
+struct RDEPUBTypesettingInput {
+    var href: String
+    var title: String
+    var rawHTML: String
+    var baseURL: URL?
+    var style: RDEPUBTextRenderStyle
+    var resourceResolver: RDEPUBResourceResolver?
+    var contentLanguageCode: String?
+    var pageSize: CGSize?
+    var layoutConfig: RDEPUBTextLayoutConfig?
+}
+
+struct RDEPUBTypesettingOutput {
+    var request: RDEPUBTextChapterRenderRequest
+    var diagnostics: [RDEPUBTextResourceReferenceDiagnostic]
+}
+
+protocol RDEPUBTypesettingStage {
+    func process(_ html: String, context: RDEPUBTypesettingInput) -> String
+}
+
+struct RDEPUBTextTypesetterPipeline {
+    func makeRequest(from input: RDEPUBTypesettingInput) -> RDEPUBTypesettingOutput {
+        let htmlNormalizer = RDEPUBHTMLNormalizer()
+        let semanticMarkerInjector = RDEPUBSemanticMarkerInjector()
+        let styleSheetComposer = RDEPUBStyleSheetComposer()
+        let fontNormalizer = RDEPUBFontNormalizer()
+        let fragmentMarkerInjector = RDEPUBFragmentMarkerInjector()
+        let diagnosticsCollector = RDEPUBRenderDiagnosticsCollector()
+
+        let normalizedHTML = semanticMarkerInjector.process(
+            htmlNormalizer.process(input.rawHTML, context: input),
+            context: input
+        )
+        let styleSheetComposition = styleSheetComposer.compose(html: normalizedHTML, input: input)
+        fontNormalizer.registerEmbeddedFonts(
+            html: normalizedHTML,
+            inlinedCSS: styleSheetComposition.inlinedCSS,
+            input: input
+        )
+        let markedHTML = fragmentMarkerInjector.process(styleSheetComposition.html, context: input)
+        let diagnostics = styleSheetComposition.diagnostics + diagnosticsCollector.collect(in: markedHTML, input: input)
+
+        let context = RDEPUBTextChapterContext(
+            href: input.href,
+            title: input.title,
+            html: markedHTML,
+            baseURL: input.baseURL,
+            stylesheet: RDEPUBTextStyleSheetPackage(layers: styleSheetComposition.layers),
+            resourceDiagnostics: diagnostics
+        )
+        let request = RDEPUBTextChapterRenderRequest(
+            context: context,
+            style: input.style,
+            pageSize: input.pageSize,
+            layoutConfig: input.layoutConfig
+        )
+        return RDEPUBTypesettingOutput(
+            request: request,
+            diagnostics: diagnostics
+        )
+    }
+}