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
@@ -0,0 +1,148 @@
+import UIKit
+
+public final class RDEPUBChapterData {
+    public let chapter: RDEPUBTextChapter
+    public let indexTable: RDEPUBTextIndexTable
+
+    public init(chapter: RDEPUBTextChapter, indexTable: RDEPUBTextIndexTable) {
+        self.chapter = chapter
+        self.indexTable = indexTable
+    }
+
+    public var chapterIndex: Int { chapter.chapterIndex }
+    public var spineIndex: Int { chapter.spineIndex }
+    public var href: String { chapter.href }
+    public var title: String { chapter.title }
+    public var attributedContent: NSAttributedString { chapter.attributedContent }
+    public var pages: [RDEPUBTextPage] { chapter.pages }
+    public var fragmentOffsets: [String: Int] { chapter.fragmentOffsets }
+
+    public func page(containing absoluteOffset: Int) -> RDEPUBTextPage? {
+        chapter.pages.first { NSLocationInRange(absoluteOffset, $0.contentRange) }
+    }
+
+    public func pageNumber(containing absoluteOffset: Int) -> Int? {
+        page(containing: absoluteOffset)?.absolutePageIndex
+    }
+
+    public func page(atAbsolutePageIndex absolutePageIndex: Int) -> RDEPUBTextPage? {
+        chapter.pages.first { $0.absolutePageIndex == absolutePageIndex }
+    }
+
+    public func anchor(forAbsoluteIndex index: Int) -> RDEPUBTextAnchor {
+        indexTable.anchor(forAbsoluteIndex: index, in: chapter)
+    }
+
+    public func rangeAnchor(for absoluteRange: NSRange) -> RDEPUBTextRangeAnchor {
+        let start = anchor(forAbsoluteIndex: absoluteRange.location)
+        let end = anchor(forAbsoluteIndex: absoluteRange.location + absoluteRange.length)
+        return RDEPUBTextRangeAnchor(start: start, end: end)
+    }
+
+    public func selection(from absoluteRange: NSRange, bookIdentifier: String?) -> RDEPUBSelection? {
+        guard page(containing: absoluteRange.location) != nil else { return nil }
+        let location = self.location(for: absoluteRange, bookIdentifier: bookIdentifier)
+        let text = chapter.attributedContent.attributedSubstring(from: absoluteRange).string
+        let rangeInfo = RDEPUBTextOffsetRangeInfo(
+            href: chapter.href,
+            start: absoluteRange.location,
+            end: absoluteRange.location + absoluteRange.length
+        ).jsonString()
+        return RDEPUBSelection(
+            bookIdentifier: bookIdentifier,
+            location: location,
+            text: text,
+            rangeInfo: rangeInfo
+        )
+    }
+
+    public func location(for absoluteRange: NSRange, bookIdentifier: String?) -> RDEPUBLocation {
+        indexTable.location(
+            for: rangeAnchor(for: absoluteRange),
+            in: chapter,
+            bookIdentifier: bookIdentifier
+        )
+    }
+
+    public func location(forPage page: RDEPUBTextPage, bookIdentifier: String?) -> RDEPUBLocation {
+        location(for: page.contentRange, bookIdentifier: bookIdentifier)
+    }
+
+    public func absoluteRange(for location: RDEPUBLocation) -> NSRange? {
+        if let rangeAnchor = location.rangeAnchor {
+            return indexTable.absoluteRange(for: rangeAnchor)
+        }
+
+        if let fragment = location.fragment,
+           let offset = fragmentOffsets[fragment] {
+            return NSRange(location: offset, length: 1)
+        }
+
+        let lastOffset = max(attributedContent.length - 1, 0)
+        let offset = min(lastOffset, max(0, Int(round(Double(lastOffset) * location.navigationProgression))))
+        return NSRange(location: offset, length: 1)
+    }
+
+    public func absoluteRange(for highlight: RDEPUBHighlight) -> NSRange? {
+        if let rangeAnchor = highlight.location.rangeAnchor {
+            return indexTable.absoluteRange(for: rangeAnchor)
+        }
+        return RDEPUBTextOffsetRangeInfo.decode(from: highlight.rangeInfo)?.nsRange
+    }
+
+    public func absoluteRange(for searchMatch: RDEPUBSearchMatch) -> NSRange? {
+        if let rangeAnchor = searchMatch.rangeAnchor {
+            return indexTable.absoluteRange(for: rangeAnchor)
+        }
+        if let location = searchMatch.rangeLocation {
+            return NSRange(location: location, length: searchMatch.rangeLength)
+        }
+        return nil
+    }
+
+    public func highlights(on page: RDEPUBTextPage, from allHighlights: [RDEPUBHighlight]) -> [RDEPUBHighlight] {
+        let pageRange = absoluteOffsetRange(for: page)
+        return allHighlights.filter { highlight in
+            guard highlight.location.href == chapter.href else { return false }
+            if let anchor = highlight.location.rangeAnchor?.start {
+                return pageRange.contains(absoluteOffset(for: anchor))
+            }
+            guard let range = RDEPUBTextOffsetRangeInfo.decode(from: highlight.rangeInfo)?.nsRange else {
+                return false
+            }
+            return NSIntersectionRange(range, page.contentRange).length > 0
+        }
+    }
+
+    public func searchMatches(on page: RDEPUBTextPage, from matches: [RDEPUBSearchMatch]) -> [RDEPUBSearchMatch] {
+        let pageRange = absoluteOffsetRange(for: page)
+        return matches.filter { match in
+            guard match.href == chapter.href else { return false }
+            if let range = absoluteRange(for: match) {
+                return NSIntersectionRange(range, page.contentRange).length > 0
+            }
+            return false
+        }
+    }
+
+    public func pageNumber(for location: RDEPUBLocation) -> Int? {
+        if let range = absoluteRange(for: location) {
+            return pageNumber(containing: range.location).map { $0 + 1 }
+        }
+        return nil
+    }
+
+    private func absoluteOffsetRange(for page: RDEPUBTextPage) -> Range<Int> {
+        let lowerBound = page.pageStartOffset
+        let upperBound = page.pageEndOffset + 1
+        return lowerBound..<max(upperBound, lowerBound)
+    }
+
+    private func absoluteOffset(for anchor: RDEPUBTextAnchor) -> Int {
+        indexTable.absoluteIndex(
+            fileIndex: anchor.fileIndex,
+            row: anchor.row,
+            column: anchor.column
+        ) ?? anchor.chapterOffset
+    }
+}
@@ -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,
@@ -50,9 +50,15 @@ struct RDEPUBTextLayouter {
            let proposedRange = NSRange(location: location, length: visibleRange.length)

            // Line-level avoidPageBreakInside (WXRead approach: scan CTFrame lines backward)
-            let lineAdjusted = trimmedRangeForAvoidPageBreakInside(from: frame, proposed: proposedRange)
+            let avoidAdjusted = trimmedRangeForAvoidPageBreakInside(from: frame, proposed: proposedRange)
+            let lineAdjusted = trimmedRangeForKeepWithNext(from: frame, proposed: avoidAdjusted)
+            let lineRanges = lineRanges(from: frame)

-            let adjusted = adjustedRange(from: lineAdjusted, totalLength: attributedString.length)
+            let adjusted = adjustedRange(
+                from: lineAdjusted,
+                totalLength: attributedString.length,
+                lineRanges: lineRanges
+            )
            let trailingFragmentID = nearestTrailingFragmentID(
                endingAt: adjusted.range.location + adjusted.range.length,
                fragmentOffsets: fragmentOffsets
@@ -106,8 +112,14 @@ struct RDEPUBTextLayouter {
            }

            let proposedRange = NSRange(location: location, length: visibleRange.length)
-            let lineAdjusted = trimmedRangeForAvoidPageBreakInside(from: layoutFrame, proposed: proposedRange)
-            let adjusted = adjustedRange(from: lineAdjusted, totalLength: attributedString.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 trailingFragmentID = nearestTrailingFragmentID(
                endingAt: adjusted.range.location + adjusted.range.length,
                fragmentOffsets: fragmentOffsets
@@ -142,7 +154,8 @@ struct RDEPUBTextLayouter {

    private func adjustedRange(
        from proposedRange: NSRange,
-        totalLength: Int
+        totalLength: Int,
+        lineRanges: [NSRange]
    ) -> (
        range: NSRange,
        breakReason: RDEPUBTextPageBreakReason,
@@ -217,6 +230,34 @@ struct RDEPUBTextLayouter {
            )
        }

+        if let pageRelateBoundary = preferredPageRelateBoundary(
+            after: proposedRange,
+            minimumEnd: minimumEnd,
+            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
+                )
+            )
+        }
+
        if let attachmentBoundary = preferredAttachmentBoundary(
            in: proposedRange,
            minimumEnd: minimumEnd
@@ -300,15 +341,49 @@ struct RDEPUBTextLayouter {
        var boundary: Int?
        attributedString.enumerateAttribute(.rdPageAttachmentKind, in: range) { value, attributeRange, stop in
            guard value != nil else { return }
-            let paragraphRange = paragraphRange(containing: attributeRange.location)
-            if paragraphRange.location > range.location, paragraphRange.location >= minimumEnd {
-                boundary = paragraphRange.location
+
+            let location = attributeRange.location
+            let placement = attachmentPlacement(at: location)
+            let blockKind = blockKind(at: location)
+
+            // Mirror WXRead more closely: only block-level attachments should
+            // push the entire block to the next page. Inline footnote icons and
+            // other inline attachments must not cause a whole paragraph to move.
+            let isBlockLevelAttachment = blockKind == .attachment || placement == .centered
+            guard isBlockLevelAttachment else { return }
+
+            let boundaryRange = blockRange(at: location) ?? paragraphRange(containing: location)
+            if boundaryRange.location > range.location, boundaryRange.location >= minimumEnd {
+                boundary = boundaryRange.location
                stop.pointee = true
            }
        }
        return boundary
    }

+    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
+    }
+
    private func blockRange(at location: Int) -> NSRange? {
        guard location >= 0, location < attributedString.length else { return nil }
        let attributes = attributedString.attributes(at: location, effectiveRange: nil)
@@ -318,6 +393,20 @@ struct RDEPUBTextLayouter {
        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) }
@@ -334,6 +423,15 @@ struct RDEPUBTextLayouter {
        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] {
        var kinds: [RDEPUBTextAttachmentKind] = []
        attributedString.enumerateAttribute(.rdPageAttachmentKind, in: range) { value, _, _ in
@@ -451,6 +549,18 @@ struct RDEPUBTextLayouter {
        return NSRange(location: proposed.location, length: adjustedLength)
    }

+    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)
+    }
+
 #if canImport(DTCoreText)
    private func trimmedRangeForAvoidPageBreakInside(
        from layoutFrame: DTCoreTextLayoutFrame,
@@ -492,8 +602,52 @@ struct RDEPUBTextLayouter {

        return NSRange(location: proposed.location, length: adjustedLength)
    }
+
+    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

+    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)
+    }
+
    /// Checks if a line's string range intersects with an avoidPageBreakInside block.
    private func lineIsInAvoidPageBreakInsideBlock(_ lineRange: NSRange) -> Bool {
        var found = false
@@ -511,6 +665,39 @@ struct RDEPUBTextLayouter {
        return found
    }

+    private func lineIsInKeepWithNextBlock(_ lineRange: NSRange) -> Bool {
+        var found = false
+        let probeRange = NSRange(location: lineRange.location, length: max(lineRange.length, 1))
+        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
+    }
+
+    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)
+        }
+    }
+
+#if canImport(DTCoreText)
+    private func lineRanges(from layoutFrame: DTCoreTextLayoutFrame) -> [NSRange] {
+        guard let lines = layoutFrame.lines as? [DTCoreTextLayoutLine] else {
+            return []
+        }
+        return lines.map { $0.stringRange() }
+    }
+#endif
+
    private func diagnostics(
        reason: RDEPUBTextPageBreakReason,
        range: NSRange,
@@ -22,6 +22,7 @@ public enum RDEPUBTextBlockKind: String, Codable, Equatable, CaseIterable {

 public enum RDEPUBTextSemanticHint: String, Codable, Equatable, CaseIterable {
    case avoidPageBreakInside
+    case keepWithNext
    case pageBreakBefore
    case pageBreakAfter
    case pageRelate
@@ -812,6 +812,8 @@ enum RDEPUBTextRendererSupport {
            return .attachment
        }
        switch tagName {
+        case "h1", "h2", "h3", "h4", "h5", "h6":
+            return .generic
        case "blockquote":
            return .blockquote
        case "ul", "ol", "li":
@@ -849,6 +851,16 @@ enum RDEPUBTextRendererSupport {
            ["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") {
@@ -17,6 +17,7 @@ final class RDEPUBTextSearchEngine: RDEPUBSearchEngine {

        var matches: [RDEPUBSearchMatch] = []
        for chapter in textBook.chapters {
+            guard let chapterData = textBook.chapterData(for: chapter.href) else { continue }
            let source = chapter.attributedContent.string as NSString
            let fullLength = source.length
            guard fullLength > 0 else {
@@ -42,7 +43,8 @@ final class RDEPUBTextSearchEngine: RDEPUBSearchEngine {
                        previewText: previewText(in: source, matchRange: foundRange),
                        localMatchIndex: localMatchIndex,
                        rangeLocation: foundRange.location,
-                        rangeLength: foundRange.length
+                        rangeLength: foundRange.length,
+                        rangeAnchor: chapterData.rangeAnchor(for: foundRange)
                    )
                )