feat(wxread): align pagination, rendering, and docs

2026-05-24 15:36:01 +08:00
parent a318c0e3d0
commit 2a94921e88
103 changed files with 6124 additions and 4623 deletions
@@ -40,13 +40,29 @@ public struct RDEPUBTextChapter: Equatable {
    public var pages: [RDEPUBTextPage]
 }

-public struct RDEPUBTextBook: Equatable {
+public struct RDEPUBTextBook {
    public var chapters: [RDEPUBTextChapter]
    public var pages: [RDEPUBTextPage]
+    public let indexTable: RDEPUBTextIndexTable

    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
+    }
+
+    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)
+    }
+
+    public func chapterData(atChapterIndex index: Int) -> RDEPUBChapterData? {
+        guard chapters.indices.contains(index) else { return nil }
+        return RDEPUBChapterData(chapter: chapters[index], indexTable: indexTable)
    }

    public func page(at pageNumber: Int) -> RDEPUBTextPage? {
@@ -62,6 +78,11 @@ public struct RDEPUBTextBook: Equatable {
            return nil
        }

+        if let anchor = normalizedLocation.rangeAnchor?.start,
+           let page = indexTable.pageNumber(for: anchor, in: self) {
+            return page + 1
+        }
+
        let targetOffset: Int
        if let fragment = normalizedLocation.fragment, let fragmentOffset = chapter.fragmentOffsets[fragment] {
            targetOffset = fragmentOffset
@@ -84,12 +105,18 @@ public struct RDEPUBTextBook: Equatable {
        }

        let totalLength = max(chapter.attributedContent.length - 1, 1)
+
+        let startAnchor = indexTable.anchor(forAbsoluteIndex: page.pageStartOffset, in: chapter)
+        let endAnchor = indexTable.anchor(forAbsoluteIndex: page.pageEndOffset, in: chapter)
+        let rangeAnchor = RDEPUBTextRangeAnchor(start: startAnchor, end: endAnchor)
+
        return RDEPUBLocation(
            bookIdentifier: bookIdentifier,
            href: page.href,
            progression: Double(page.pageStartOffset) / Double(totalLength),
            lastProgression: Double(page.pageEndOffset) / Double(totalLength),
-            fragment: nil
+            fragment: nil,
+            rangeAnchor: rangeAnchor
        )
    }
 }
@@ -243,7 +270,12 @@ public final class RDEPUBTextBookBuilder {
            }
            let paginateDuration = CFAbsoluteTimeGetCurrent() - paginateStart

-            let effectiveFrames = layoutFrames.isEmpty && content.length > 0
+            let normalizedFrames = normalizeTrailingFrames(
+                layoutFrames,
+                content: content,
+                href: item.href
+            )
+            let effectiveFrames = normalizedFrames.isEmpty && content.length > 0
                ? [
                    RDEPUBTextLayoutFrame(
                        contentRange: NSRange(location: 0, length: content.length),
@@ -261,7 +293,7 @@ public final class RDEPUBTextBookBuilder {
                        ]
                    )
                ]
-                : layoutFrames
+                : 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")")
            }
@@ -423,6 +455,111 @@ public final class RDEPUBTextBookBuilder {
        return attachmentCount(in: content) > 0 && trimmed.count <= 1
    }

+    private func normalizeTrailingFrames(
+        _ frames: [RDEPUBTextLayoutFrame],
+        content: NSAttributedString,
+        href: String
+    ) -> [RDEPUBTextLayoutFrame] {
+        guard frames.count > 1 else { return frames }
+
+        var normalized = frames
+
+        while let lastFrame = normalized.last,
+              shouldDropWhitespaceOnlyTrailingFrame(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 shouldDropWhitespaceOnlyTrailingFrame(
+        _ 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 uniqueValues<T: Equatable>(from values: [T]) -> [T] {
        values.reduce(into: [T]()) { result, value in
            if !result.contains(value) {
@@ -431,6 +568,25 @@ public final class RDEPUBTextBookBuilder {
        }
    }

+    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
+    }
+
    private func makeCacheKey(
        bookID: String,
        pageSize: CGSize,