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

Sources/RDReaderView/EPUBUI/RDEPUBPageInteractionController.swift

@@ -0,0 +1,212 @@
+import UIKit
+
+#if canImport(DTCoreText)
+import DTCoreText
+#endif
+
+final class RDEPUBPageInteractionController {
+
+    var snapshot: RDEPUBPageLayoutSnapshot?
+    private var dtLayoutFrame: DTCoreTextLayoutFrame?
+
+#if canImport(DTCoreText)
+    func configure(layoutFrame: DTCoreTextLayoutFrame?, page: RDEPUBTextPage?) {
+        dtLayoutFrame = layoutFrame
+        if let layoutFrame, let page {
+            snapshot = RDEPUBPageLayoutSnapshot.build(from: layoutFrame, page: page)
+        } else {
+            snapshot = nil
+        }
+    }
+#endif
+
+    // MARK: - Hit Testing
+
+    func characterIndex(at point: CGPoint) -> Int? {
+        guard let snapshot else { return nil }
+
+        // Attachment rect priority (6pt inset for easier tapping)
+        for attachment in snapshot.attachments {
+            if attachment.frame.insetBy(dx: -6, dy: -6).contains(point) {
+                return attachment.stringRange.location
+            }
+        }
+
+        guard let line = nearestLine(to: point, in: snapshot.lines) else { return nil }
+
+#if canImport(DTCoreText)
+        guard let dtLine = dtLineContaining(range: line.stringRange) else { return nil }
+        let relativePoint = CGPoint(
+            x: point.x - line.baselineOrigin.x,
+            y: point.y - line.baselineOrigin.y
+        )
+        let idx = dtLine.stringIndex(forPosition: relativePoint)
+        guard idx != NSNotFound, idx >= 0 else { return nil }
+        return normalizedIndex(idx, lineRange: line.stringRange, pageRange: snapshot.pageContentRange)
+#else
+        return nil
+#endif
+    }
+
+    // MARK: - Selection Range
+
+    func selectionRange(from startPoint: CGPoint, to endPoint: CGPoint) -> NSRange? {
+        guard let start = characterIndex(at: startPoint),
+              let end = characterIndex(at: endPoint) else { return nil }
+        let lower = min(start, end)
+        let upper = max(start, end)
+        return NSRange(location: lower, length: max(upper - lower, 1))
+    }
+
+    // MARK: - Selection Rects
+
+    func selectionRects(for absoluteRange: NSRange) -> [CGRect] {
+        guard let snapshot else { return [] }
+        var rects: [CGRect] = []
+
+        for line in snapshot.lines {
+            let overlap = NSIntersectionRange(line.stringRange, absoluteRange)
+            guard overlap.length > 0 else { continue }
+
+#if canImport(DTCoreText)
+            guard let dtLine = dtLineContaining(range: line.stringRange) else { continue }
+            let startX = dtLine.offset(forStringIndex: overlap.location)
+            let endIdx = overlap.location + overlap.length
+            let endX = dtLine.offset(forStringIndex: endIdx)
+#else
+            let startX: CGFloat = 0
+            let endX: CGFloat = line.frame.width
+#endif
+
+            let rect = CGRect(
+                x: line.baselineOrigin.x + startX,
+                y: line.baselineOrigin.y - line.ascent,
+                width: max(endX - startX, 2),
+                height: line.ascent + line.descent
+            )
+            rects.append(rect)
+        }
+
+        return mergeAdjacentRects(rects)
+    }
+
+    func firstRect(for absoluteRange: NSRange) -> CGRect? {
+        selectionRects(for: absoluteRange).first
+    }
+
+    func lastRect(for absoluteRange: NSRange) -> CGRect? {
+        selectionRects(for: absoluteRange).last
+    }
+
+    func boundingRect(for absoluteRange: NSRange) -> CGRect? {
+        let rects = selectionRects(for: absoluteRange)
+        guard var rect = rects.first else { return nil }
+        for next in rects.dropFirst() {
+            rect = rect.union(next)
+        }
+        return rect
+    }
+
+    func menuAnchorRect(for absoluteRange: NSRange) -> CGRect? {
+        guard let first = firstRect(for: absoluteRange),
+              let last = lastRect(for: absoluteRange) else {
+            return boundingRect(for: absoluteRange)
+        }
+
+        let minX = min(first.minX, last.minX)
+        let maxX = max(first.maxX, last.maxX)
+        let minY = min(first.minY, last.minY)
+        let maxY = max(first.maxY, last.maxY)
+        return CGRect(x: minX, y: minY, width: max(maxX - minX, 2), height: max(maxY - minY, 2))
+    }
+
+    // MARK: - Caret Rect
+
+    func caretRect(at index: Int) -> CGRect? {
+        guard let snapshot else { return nil }
+        guard let line = snapshot.lines.first(where: { NSLocationInRange(index, $0.stringRange) }) else {
+            return nil
+        }
+
+#if canImport(DTCoreText)
+        guard let dtLine = dtLineContaining(range: line.stringRange) else { return nil }
+        let offsetX = dtLine.offset(forStringIndex: index)
+#else
+        let offsetX: CGFloat = 0
+#endif
+
+        return CGRect(
+            x: line.baselineOrigin.x + offsetX - 1,
+            y: line.baselineOrigin.y - line.ascent,
+            width: 2,
+            height: line.ascent + line.descent
+        )
+    }
+
+    // MARK: - Private Helpers
+
+    private func nearestLine(to point: CGPoint, in lines: [RDEPUBPageLine]) -> RDEPUBPageLine? {
+        var bestLine: RDEPUBPageLine?
+        var bestDistance: CGFloat = .greatestFiniteMagnitude
+
+        for line in lines {
+            let lineBottom = line.baselineOrigin.y + line.descent
+            let lineTop = line.baselineOrigin.y - line.ascent
+            if point.y >= lineTop && point.y <= lineBottom {
+                return line
+            }
+            let lineMidY = (lineTop + lineBottom) / 2
+            let distance = abs(point.y - lineMidY)
+
+            if distance < bestDistance {
+                bestDistance = distance
+                bestLine = line
+            }
+        }
+
+        return bestLine
+    }
+
+    private func normalizedIndex(_ idx: Int, lineRange: NSRange, pageRange: NSRange) -> Int {
+        var result = idx
+        if result < lineRange.location {
+            result = lineRange.location
+        }
+        let lineEnd = lineRange.location + lineRange.length
+        if result >= lineEnd {
+            result = max(lineEnd - 1, lineRange.location)
+        }
+        return result
+    }
+
+#if canImport(DTCoreText)
+    private func dtLineContaining(range: NSRange) -> DTCoreTextLayoutLine? {
+        guard let dtLayoutFrame else { return nil }
+        return dtLayoutFrame.lineContaining(UInt(range.location))
+    }
+#endif
+
+    private func mergeAdjacentRects(_ rects: [CGRect]) -> [CGRect] {
+        guard rects.count > 1 else { return rects }
+
+        let sorted = rects.sorted { a, b in
+            if abs(a.origin.y - b.origin.y) < 1 {
+                return a.origin.x < b.origin.x
+            }
+            return a.origin.y < b.origin.y
+        }
+
+        var merged: [CGRect] = [sorted[0]]
+        for rect in sorted.dropFirst() {
+            let last = merged[merged.count - 1]
+            if abs(rect.origin.y - last.origin.y) < 1,
+               rect.origin.x <= last.maxX + 2 {
+                merged[merged.count - 1] = last.union(rect)
+            } else {
+                merged.append(rect)
+            }
+        }
+
+        return merged
+    }
+}

Sources/RDReaderView/EPUBUI/RDEPUBPageLayoutSnapshot.swift

@@ -0,0 +1,146 @@
+import UIKit
+
+#if canImport(DTCoreText)
+import DTCoreText
+#endif
+
+struct RDEPUBPageLine {
+    let stringRange: NSRange
+    let frame: CGRect
+    let baselineOrigin: CGPoint
+    let ascent: CGFloat
+    let descent: CGFloat
+    let leading: CGFloat
+}
+
+struct RDEPUBPageRun {
+    let stringRange: NSRange
+    let frame: CGRect
+    let isAttachment: Bool
+}
+
+struct RDEPUBPageAttachment {
+    let stringRange: NSRange
+    let frame: CGRect
+    let displaySize: CGSize
+    let placement: RDEPUBTextAttachmentPlacement?
+    let kind: RDEPUBTextAttachmentKind?
+}
+
+struct RDEPUBPageLayoutSnapshot {
+    let page: RDEPUBTextPage
+    let lines: [RDEPUBPageLine]
+    let runs: [RDEPUBPageRun]
+    let attachments: [RDEPUBPageAttachment]
+    let pageContentRange: NSRange
+#if canImport(DTCoreText)
+    let layoutFrame: DTCoreTextLayoutFrame
+#endif
+
+    func line(containing absoluteIndex: Int) -> RDEPUBPageLine? {
+        lines.first { NSLocationInRange(absoluteIndex, $0.stringRange) }
+    }
+
+    func run(containing absoluteIndex: Int) -> RDEPUBPageRun? {
+        runs.first { NSLocationInRange(absoluteIndex, $0.stringRange) }
+    }
+
+    func runs(intersecting range: NSRange) -> [RDEPUBPageRun] {
+        runs.filter { NSIntersectionRange($0.stringRange, range).length > 0 }
+    }
+
+    func attachment(at point: CGPoint, hitSlop: CGFloat = 6) -> RDEPUBPageAttachment? {
+        attachments.first { $0.frame.insetBy(dx: -hitSlop, dy: -hitSlop).contains(point) }
+    }
+
+    func rects(containing point: CGPoint, in decorations: [RDEPUBTextOverlayDecoration]) -> [RDEPUBTextOverlayDecoration] {
+        decorations.filter { decoration in
+            decoration.rects.contains { $0.insetBy(dx: -4, dy: -4).contains(point) }
+        }
+    }
+
+#if canImport(DTCoreText)
+    static func build(
+        from layoutFrame: DTCoreTextLayoutFrame,
+        page: RDEPUBTextPage
+    ) -> RDEPUBPageLayoutSnapshot? {
+        guard let dtLines = layoutFrame.lines as? [DTCoreTextLayoutLine], !dtLines.isEmpty else {
+            return nil
+        }
+
+        var lines: [RDEPUBPageLine] = []
+        var runs: [RDEPUBPageRun] = []
+        var attachments: [RDEPUBPageAttachment] = []
+
+        for dtLine in dtLines {
+            let lineRange = dtLine.stringRange()
+            let line = RDEPUBPageLine(
+                stringRange: lineRange,
+                frame: dtLine.frame,
+                baselineOrigin: dtLine.baselineOrigin,
+                ascent: dtLine.ascent,
+                descent: dtLine.descent,
+                leading: dtLine.leading
+            )
+            lines.append(line)
+
+            if let glyphRuns = dtLine.glyphRuns as? [DTCoreTextGlyphRun] {
+                for run in glyphRuns {
+                    let runRange = run.stringRange()
+                    let isAttachment = run.attachment != nil
+                    runs.append(
+                        RDEPUBPageRun(
+                            stringRange: runRange,
+                            frame: run.frame,
+                            isAttachment: isAttachment
+                        )
+                    )
+
+                    guard isAttachment else { continue }
+                    let metadata = attachmentMetadata(
+                        for: runRange,
+                        on: page
+                    )
+                    attachments.append(
+                        RDEPUBPageAttachment(
+                            stringRange: runRange,
+                            frame: run.frame,
+                            displaySize: run.frame.size,
+                            placement: metadata.placement,
+                            kind: metadata.kind
+                        )
+                    )
+                }
+            }
+        }
+
+        let visibleRange = layoutFrame.visibleStringRange()
+
+        return RDEPUBPageLayoutSnapshot(
+            page: page,
+            lines: lines,
+            runs: runs,
+            attachments: attachments,
+            pageContentRange: visibleRange,
+            layoutFrame: layoutFrame
+        )
+    }
+
+    private static func attachmentMetadata(
+        for range: NSRange,
+        on page: RDEPUBTextPage
+    ) -> (placement: RDEPUBTextAttachmentPlacement?, kind: RDEPUBTextAttachmentKind?) {
+        guard let attachmentIndex = page.metadata.attachmentRanges.firstIndex(where: { NSIntersectionRange($0, range).length > 0 }) else {
+            return (nil, nil)
+        }
+
+        let placement = page.metadata.attachmentPlacements.indices.contains(attachmentIndex)
+            ? page.metadata.attachmentPlacements[attachmentIndex]
+            : nil
+        let kind = page.metadata.attachmentKinds.indices.contains(attachmentIndex)
+            ? page.metadata.attachmentKinds[attachmentIndex]
+            : nil
+        return (placement, kind)
+    }
+#endif
+}

Sources/RDReaderView/EPUBUI/RDEPUBReaderController.swift

@@ -58,6 +58,11 @@ public final class RDEPUBReaderController: UIViewController {
         currentVisibleLocation()
     }
 
+    public var currentPageNumber: Int? {
+        guard readerView.currentPage >= 0 else { return nil }
+        return readerView.currentPage + 1
+    }
+
     public private(set) var currentSelection: RDEPUBSelection?
 
     public var highlights: [RDEPUBHighlight] {
@@ -263,6 +268,27 @@ public final class RDEPUBReaderController: UIViewController {
         restoreReadingLocation(location)
     }
 
+    @discardableResult
+    public func go(toPageNumber pageNumber: Int, animated: Bool = false) -> Bool {
+        guard pageNumber > 0 else { return false }
+
+        if textBook != nil {
+            guard let location = resolvedTextLocation(forPageNumber: pageNumber) else {
+                return false
+            }
+            return restoreReadingLocation(location, animated: animated)
+        }
+
+        guard activePages.indices.contains(pageNumber - 1) else {
+            return false
+        }
+        readerView.transitionToPage(pageNum: pageNumber - 1, animated: animated)
+        if let location = currentVisibleLocation() {
+            persist(location: location)
+        }
+        return true
+    }
+
     public func clearSelection() {
         updateCurrentSelection(nil)
     }
@@ -489,12 +515,17 @@ public final class RDEPUBReaderController: UIViewController {
     }
 
     private func applyReaderViewConfiguration() {
+        let displayTypeDidChange = readerView.currentDisplayType != configuration.displayType
+        let preservedLocation = displayTypeDidChange ? currentVisibleLocation() : nil
         view.backgroundColor = configuration.theme.contentBackgroundColor
         readerView.landscapeDualPageEnabled = configuration.landscapeDualPageEnabled
         readerView.pageDirection = resolvedPageDirection()
         updateReaderChrome()
-        if readerView.currentDisplayType != configuration.displayType {
+        if displayTypeDidChange {
             readerView.switchReaderDisplayType(configuration.displayType)
+            if let preservedLocation {
+                _ = restoreReadingLocation(preservedLocation)
+            }
         }
     }
 
@@ -750,7 +781,8 @@ public final class RDEPUBReaderController: UIViewController {
             href: selection.location.href,
             progression: selection.location.progression,
             lastProgression: selection.location.lastProgression,
-            fragment: selection.location.fragment
+            fragment: selection.location.fragment,
+            rangeAnchor: selection.location.rangeAnchor
         )
         return RDEPUBSelection(
             bookIdentifier: currentBookIdentifier,
@@ -772,7 +804,8 @@ public final class RDEPUBReaderController: UIViewController {
             href: highlight.location.href,
             progression: highlight.location.progression,
             lastProgression: highlight.location.lastProgression,
-            fragment: highlight.location.fragment
+            fragment: highlight.location.fragment,
+            rangeAnchor: highlight.location.rangeAnchor
         )
         return RDEPUBHighlight(
             id: highlight.id,
@@ -1367,6 +1400,11 @@ extension RDEPUBReaderController {
             return false
         }
 
+        if let bookmarkAnchor = bookmark.location.rangeAnchor,
+           let locationAnchor = location.rangeAnchor {
+            return bookmarkAnchor == locationAnchor
+        }
+
         if let bookmarkFragment = bookmark.location.fragment,
            let locationFragment = location.fragment {
             return bookmarkFragment == locationFragment
@@ -1394,7 +1432,8 @@ extension RDEPUBReaderController {
                 href: location.href,
                 progression: location.progression,
                 lastProgression: location.lastProgression,
-                fragment: location.fragment
+                fragment: location.fragment,
+                rangeAnchor: location.rangeAnchor
             )
         }
 
@@ -1407,7 +1446,8 @@ extension RDEPUBReaderController {
             href: location.href,
             progression: location.progression,
             lastProgression: location.lastProgression,
-            fragment: location.fragment
+            fragment: location.fragment,
+            rangeAnchor: location.rangeAnchor
         )
     }
 
@@ -1499,21 +1539,32 @@ extension RDEPUBReaderController {
             href: searchMatch.href,
             progression: searchMatch.progression,
             lastProgression: searchMatch.progression,
-            fragment: nil
+            fragment: nil,
+            rangeAnchor: searchMatch.rangeAnchor
         )
         return restoreReadingLocation(location, animated: animated)
     }
 
     private func pageNumber(for searchMatch: RDEPUBSearchMatch) -> Int? {
-        if let textBook,
-           let publication,
-           let rangeLocation = searchMatch.rangeLocation,
-           let chapter = textBook.chapters.first(where: {
-               (publication.resourceResolver.normalizedHref($0.href) ?? $0.href) ==
-               (publication.resourceResolver.normalizedHref(searchMatch.href) ?? searchMatch.href)
-           }),
-           let page = chapter.pages.first(where: { rangeLocation >= $0.pageStartOffset && rangeLocation <= $0.pageEndOffset }) {
-            return page.absolutePageIndex + 1
+        if let chapterData = textChapterData(forNormalizedHref: searchMatch.href) {
+            let location = RDEPUBLocation(
+                bookIdentifier: currentBookIdentifier,
+                href: chapterData.href,
+                progression: searchMatch.progression,
+                lastProgression: searchMatch.progression,
+                fragment: nil,
+                rangeAnchor: searchMatch.rangeAnchor
+            )
+            if let pageNumber = chapterData.pageNumber(for: location) {
+                return pageNumber
+            }
+
+            if let rangeLocation = searchMatch.rangeLocation,
+               let page = chapterData.pages.first(where: {
+                   rangeLocation >= $0.pageStartOffset && rangeLocation <= $0.pageEndOffset
+               }) {
+                return page.absolutePageIndex + 1
+            }
         }
 
         let location = RDEPUBLocation(
@@ -1521,7 +1572,8 @@ extension RDEPUBReaderController {
             href: searchMatch.href,
             progression: searchMatch.progression,
             lastProgression: searchMatch.progression,
-            fragment: nil
+            fragment: nil,
+            rangeAnchor: searchMatch.rangeAnchor
         )
 
         if let textBook, let publication {
@@ -1554,9 +1606,12 @@ extension RDEPUBReaderController {
         }
 
         let currentMatch = searchState.currentMatch
+        let normalizedCurrentHref = currentMatch.map { publication.resourceResolver.normalizedHref($0.href) ?? $0.href }
         let resources = pageHrefs.map { href in
-            let matchCount = searchState.matches.filter { $0.href == href }.count
-            let activeLocalMatchIndex = currentMatch?.href == href ? currentMatch?.localMatchIndex : nil
+            let matchCount = searchState.matches.filter {
+                (publication.resourceResolver.normalizedHref($0.href) ?? $0.href) == href
+            }.count
+            let activeLocalMatchIndex = normalizedCurrentHref == href ? currentMatch?.localMatchIndex : nil
             return RDEPUBSearchPresentationResource(
                 href: href,
                 matchCount: matchCount,
@@ -1611,6 +1666,11 @@ extension RDEPUBReaderController: RDReaderDataSource, RDReaderDelegate {
     }
 
     private func textHighlights(for page: RDEPUBTextPage) -> [RDEPUBHighlight] {
+        if let textBook,
+           let chapterData = textBook.chapterData(for: page.href) {
+            return chapterData.highlights(on: page, from: activeHighlights)
+        }
+
         guard let publication else {
             return activeHighlights.filter { $0.location.href == page.href }
         }
@@ -1620,6 +1680,14 @@ extension RDEPUBReaderController: RDReaderDataSource, RDReaderDelegate {
         }
     }
 
+    private func textChapterData(forNormalizedHref href: String) -> RDEPUBChapterData? {
+        guard let textBook, let publication else { return nil }
+        let normalizedHref = publication.resourceResolver.normalizedHref(href) ?? href
+        return textBook.chapters.lazy
+            .first(where: { (publication.resourceResolver.normalizedHref($0.href) ?? $0.href) == normalizedHref })
+            .flatMap { textBook.chapterData(for: $0.href) }
+    }
+
     public func topToolView(readerView: RDReaderView) -> UIView? {
         topToolView
     }
@@ -1728,27 +1796,22 @@ extension RDEPUBReaderController: RDEPUBTextContentViewDelegate {
 
     private func normalizedTextSelection(_ selection: RDEPUBSelection) -> RDEPUBSelection? {
         guard let textBook,
-              let chapter = textBook.chapters.first(where: { $0.href == selection.location.href }) else {
+              let chapterData = textBook.chapterData(for: selection.location.href) else {
             return scopedSelection(selection, relativeToSpineIndex: nil)
         }
         guard let payload = RDEPUBTextOffsetRangeInfo.decode(from: selection.rangeInfo) else {
             return scopedSelection(selection, relativeToSpineIndex: nil)
         }
 
-        let contentLength = max(chapter.attributedContent.length, 1)
+        let contentLength = max(chapterData.attributedContent.length, 1)
         let lastInclusiveOffset = max(contentLength - 1, 1)
         let start = max(0, min(payload.start, lastInclusiveOffset))
         let endExclusive = max(start + 1, min(payload.end, contentLength))
-        let lastSelectedOffset = max(start, min(endExclusive - 1, lastInclusiveOffset))
+        let absoluteRange = NSRange(location: start, length: endExclusive - start)
+        let location = chapterData.location(for: absoluteRange, bookIdentifier: currentBookIdentifier)
         return RDEPUBSelection(
             bookIdentifier: currentBookIdentifier,
-            location: RDEPUBLocation(
-                bookIdentifier: currentBookIdentifier,
-                href: selection.location.href,
-                progression: Double(start) / Double(lastInclusiveOffset),
-                lastProgression: Double(lastSelectedOffset) / Double(lastInclusiveOffset),
-                fragment: nil
-            ),
+            location: location,
             text: selection.text,
             rangeInfo: selection.rangeInfo,
             createdAt: selection.createdAt
@@ -1757,6 +1820,13 @@ extension RDEPUBReaderController: RDEPUBTextContentViewDelegate {
 
     private func pageNumber(for location: RDEPUBLocation) -> Int? {
         if let textBook, let publication {
+            // Anchor-based lookup (character-level precision)
+            if let anchor = location.rangeAnchor?.start {
+                if let page = textBook.indexTable.pageNumber(for: anchor, in: textBook) {
+                    return page + 1
+                }
+            }
+
             let normalizedLocation = publication.resourceResolver.normalizedLocation(
                 location,
                 relativeToSpineIndex: nil,
@@ -1779,13 +1849,14 @@ extension RDEPUBReaderController: RDEPUBTextContentViewDelegate {
     private func resolvedTextLocation(forPageNumber pageNumber: Int) -> RDEPUBLocation? {
         guard let textBook,
               let publication,
-              let location = textBook.location(
-                forPageNumber: pageNumber,
-                bookIdentifier: currentBookIdentifier
-              ) else {
+              let page = textBook.page(at: pageNumber) else {
             return nil
         }
 
+        let location = textBook.chapterData(for: page.href)?.location(forPage: page, bookIdentifier: currentBookIdentifier)
+            ?? textBook.location(forPageNumber: pageNumber, bookIdentifier: currentBookIdentifier)
+        guard let location else { return nil }
+
         return publication.resourceResolver.normalizedLocation(
             location,
             relativeToSpineIndex: nil,

Sources/RDReaderView/EPUBUI/RDEPUBSelectionOverlayView.swift

@@ -17,8 +17,10 @@ struct RDEPUBTextOverlayDecoration {
 }
 
 final class RDEPUBSelectionOverlayView: UIView {
-    private var page: RDEPUBTextPage?
-    private var selectionRange: NSRange?
+    private(set) var page: RDEPUBTextPage?
+    private var snapshot: RDEPUBPageLayoutSnapshot?
+    private(set) var selectionRange: NSRange?
+    private var selectionRects: [CGRect] = []
     private var decorations: [RDEPUBTextOverlayDecoration] = []
     private let selectionVerticalAdjustment: CGFloat = -1
 
@@ -39,16 +41,28 @@ final class RDEPUBSelectionOverlayView: UIView {
         fatalError("init(coder:) has not been implemented")
     }
 
-    func configure(page: RDEPUBTextPage, selectionColor: UIColor) {
+    func configure(page: RDEPUBTextPage, selectionColor: UIColor, snapshot: RDEPUBPageLayoutSnapshot? = nil) {
         self.page = page
+        self.snapshot = snapshot
         self.selectionColor = selectionColor
         selectionRange = nil
         decorations = []
         setNeedsDisplay()
     }
 
+    func updateSnapshot(_ snapshot: RDEPUBPageLayoutSnapshot?) {
+        self.snapshot = snapshot
+    }
+
     func updateSelection(absoluteRange: NSRange?) {
         selectionRange = absoluteRange
+        selectionRects = []
+        setNeedsDisplay()
+    }
+
+    func updateSelection(absoluteRange: NSRange?, rects: [CGRect]) {
+        selectionRange = absoluteRange
+        selectionRects = rects
         setNeedsDisplay()
     }
 
@@ -62,6 +76,32 @@ final class RDEPUBSelectionOverlayView: UIView {
     }
 
     func absoluteRange(at point: CGPoint) -> NSRange? {
+        if let selectionRange,
+           selectionRects.contains(where: { $0.insetBy(dx: -4, dy: -4).contains(point) }) {
+            return selectionRange
+        }
+
+        if let snapshot,
+           let attachment = snapshot.attachment(at: point) {
+            return attachment.stringRange
+        }
+
+        if let snapshot {
+            let hitDecorations = snapshot.rects(containing: point, in: resolvedDecorations)
+            if let mostSpecific = hitDecorations.min(by: { lhs, rhs in
+                lhs.absoluteRange.length < rhs.absoluteRange.length
+            }) {
+                return mostSpecific.absoluteRange
+            }
+        }
+
+        for decoration in resolvedDecorations {
+            for rect in decoration.rects {
+                if rect.insetBy(dx: -4, dy: -4).contains(point) {
+                    return decoration.absoluteRange
+                }
+            }
+        }
         return nil
     }
 
@@ -110,21 +150,21 @@ final class RDEPUBSelectionOverlayView: UIView {
     }
 
     private var resolvedDecorations: [RDEPUBTextOverlayDecoration] {
-        guard let page else { return [] }
+        guard page != nil else { return [] }
 
-        let nonSelection = decorations.filter { !$0.rects.isEmpty }
-        guard let selectionRange else { return nonSelection }
+        var result = decorations.filter { !$0.rects.isEmpty }
 
-        let selectionRects:[CGRect] = []
-        guard !selectionRects.isEmpty else { return nonSelection }
-
-        return [
-            RDEPUBTextOverlayDecoration(
-                kind: .selection,
-                absoluteRange: selectionRange,
-                rects: selectionRects,
-                color: selectionColor
+        if let selectionRange, !selectionRects.isEmpty {
+            result.append(
+                RDEPUBTextOverlayDecoration(
+                    kind: .selection,
+                    absoluteRange: selectionRange,
+                    rects: selectionRects,
+                    color: selectionColor
+                )
             )
-        ]
+        }
+
+        return result
     }
 }

Sources/RDReaderView/EPUBUI/RDEPUBTextContentView.swift

@@ -77,6 +77,9 @@ final class RDEPUBTextContentView: UIView {
     private var contentInsets: UIEdgeInsets = .zero
     private var currentPage: RDEPUBTextPage?
     private var highlightedRanges: [RDEPUBHighlight] = []
+    private var currentSearchState: RDEPUBSearchState?
+    private var isSelectionFromInteraction = false
+    private var selectionMenuAnchorRect: CGRect?
     weak var delegate: RDEPUBTextContentViewDelegate?
 
 #if canImport(DTCoreText)
@@ -91,6 +94,20 @@ final class RDEPUBTextContentView: UIView {
     private var coreTextDisplayRange: NSRange?
 #endif
 
+    private let interactionController = RDEPUBPageInteractionController()
+
+    private let backgroundOverlayView: RDEPUBSelectionOverlayView = {
+        let view = RDEPUBSelectionOverlayView()
+        return view
+    }()
+
+    private let overlayView: RDEPUBSelectionOverlayView = {
+        let view = RDEPUBSelectionOverlayView()
+        return view
+    }()
+
+    private var selectionAnchorPoint: CGPoint?
+
     private let textView: RDEPUBSelectableTextView = {
         let view = RDEPUBSelectableTextView()
         view.isEditable = false
@@ -119,8 +136,10 @@ final class RDEPUBTextContentView: UIView {
         super.init(frame: frame)
         addSubview(coverImageView)
 #if canImport(DTCoreText)
+        addSubview(backgroundOverlayView)
         addSubview(coreTextContentView)
 #endif
+        addSubview(overlayView)
         addSubview(textView)
         addSubview(pageNumberLabel)
         textView.delegate = self
@@ -128,24 +147,46 @@ final class RDEPUBTextContentView: UIView {
             guard let self else { return }
             self.delegate?.textContentView(self, didRequestSelectionAction: action)
         }
-        UIMenuController.shared.menuItems = [
-            UIMenuItem(title: "拷贝", action: #selector(RDEPUBSelectableTextView.rd_copy(_:))),
-            UIMenuItem(title: "高亮", action: #selector(RDEPUBSelectableTextView.rd_highlight(_:))),
-            UIMenuItem(title: "批注", action: #selector(RDEPUBSelectableTextView.rd_annotate(_:)))
-        ]
+
+        let longPress = UILongPressGestureRecognizer(target: self, action: #selector(handleLongPress(_:)))
+        longPress.minimumPressDuration = 0.4
+        addGestureRecognizer(longPress)
+
+        let tap = UITapGestureRecognizer(target: self, action: #selector(handleTap(_:)))
+        tap.numberOfTapsRequired = 1
+        addGestureRecognizer(tap)
     }
 
     required init?(coder: NSCoder) {
         fatalError("init(coder:) has not been implemented")
     }
 
+    override var canBecomeFirstResponder: Bool { true }
+
+    override func canPerformAction(_ action: Selector, withSender sender: Any?) -> Bool {
+#if canImport(DTCoreText)
+        switch action {
+        case #selector(rd_copy(_:)),
+             #selector(rd_highlight(_:)),
+             #selector(rd_annotate(_:)):
+            return overlayView.selectionRange?.length ?? 0 > 0
+        default:
+            return false
+        }
+#else
+        return super.canPerformAction(action, withSender: sender)
+#endif
+    }
+
     override func layoutSubviews() {
         super.layoutSubviews()
 
 #if canImport(DTCoreText)
+        backgroundOverlayView.frame = bounds.inset(by: contentInsets)
         coreTextContentView.frame = bounds.inset(by: contentInsets)
         updateCoreTextLayoutFrameIfNeeded()
 #endif
+        overlayView.frame = bounds.inset(by: contentInsets)
         textView.frame = bounds.inset(by: contentInsets)
         coverImageView.frame = bounds.inset(by: contentInsets)
 
@@ -168,6 +209,7 @@ final class RDEPUBTextContentView: UIView {
     ) {
         currentPage = page
         highlightedRanges = highlights
+        currentSearchState = searchState
         contentInsets = configuration.reflowableContentInsets
         backgroundColor = configuration.theme.contentBackgroundColor
         pageNumberLabel.textColor = configuration.theme.contentTextColor
@@ -179,6 +221,8 @@ final class RDEPUBTextContentView: UIView {
             coreTextContentView.layoutFrame = nil
             coreTextDisplayContent = nil
             coreTextDisplayRange = nil
+            textView.isHidden = true
+            textView.isUserInteractionEnabled = false
 #endif
             textView.attributedText = nil
             textView.selectedRange = NSRange(location: 0, length: 0)
@@ -197,7 +241,6 @@ final class RDEPUBTextContentView: UIView {
             value: configuration.theme.contentTextColor,
             range: selectionRange
         )
-        normalizeInlineAttachments(in: selectionContent, basePointSize: configuration.fontSize)
 
 #if canImport(DTCoreText)
         let displayContent = NSMutableAttributedString(attributedString: page.chapterContent)
@@ -207,31 +250,152 @@ final class RDEPUBTextContentView: UIView {
             value: configuration.theme.contentTextColor,
             range: fullRange
         )
-        normalizeInlineAttachments(in: displayContent, basePointSize: configuration.fontSize)
-        applyHighlights(to: displayContent, page: page, contentBaseOffset: 0)
-        applySearchHighlights(to: displayContent, page: page, searchState: searchState, contentBaseOffset: 0)
         coreTextContentView.isHidden = false
         coreTextContentView.backgroundColor = .clear
         coreTextDisplayContent = displayContent
         coreTextDisplayRange = page.contentRange
+        textView.isHidden = true
+        textView.isUserInteractionEnabled = false
+        textView.attributedText = nil
         updateCoreTextLayoutFrameIfNeeded()
 #else
         applyHighlights(to: selectionContent, page: page, contentBaseOffset: page.pageStartOffset)
         applySearchHighlights(to: selectionContent, page: page, searchState: searchState, contentBaseOffset: page.pageStartOffset)
+        textView.isHidden = false
+        textView.isUserInteractionEnabled = true
 #endif
 
+#if !canImport(DTCoreText)
         textView.tintColor = configuration.theme.toolControlTextColor
         textView.attributedText = selectionProxyContent(from: selectionContent)
         textView.selectedRange = NSRange(location: 0, length: 0)
+#endif
+
+        overlayView.configure(page: page, selectionColor: overlayView.selectionColor, snapshot: interactionController.snapshot)
+#if canImport(DTCoreText)
+        backgroundOverlayView.configure(page: page, selectionColor: overlayView.selectionColor, snapshot: interactionController.snapshot)
+        let (bgDecorations, fgDecorations) = buildOverlayDecorations(page: page)
+        backgroundOverlayView.applyDecorations(bgDecorations)
+        overlayView.applyDecorations(fgDecorations)
+#endif
+
         delegate?.textContentView(self, didChangeSelection: nil)
         setNeedsLayout()
     }
 
     func clearSelection() {
         textView.selectedRange = NSRange(location: 0, length: 0)
+        overlayView.clearSelection()
+        backgroundOverlayView.clearSelection()
+        selectionAnchorPoint = nil
+        selectionMenuAnchorRect = nil
+        isSelectionFromInteraction = false
+        UIMenuController.shared.setMenuVisible(false, animated: true)
         delegate?.textContentView(self, didChangeSelection: nil)
     }
 
+    // MARK: - Gesture Handling
+
+    @objc private func handleLongPress(_ gesture: UILongPressGestureRecognizer) {
+        let point = gesture.location(in: overlayView)
+
+        switch gesture.state {
+        case .began:
+            selectionAnchorPoint = point
+            isSelectionFromInteraction = true
+            handleSelectionFromInteraction(point: point, anchorPoint: nil)
+
+        case .changed:
+            guard let anchor = selectionAnchorPoint else { return }
+            handleSelectionFromInteraction(point: point, anchorPoint: anchor)
+
+        case .ended:
+            isSelectionFromInteraction = false
+            showSelectionMenuIfNeeded()
+
+        default:
+            break
+        }
+    }
+
+    private func handleSelectionFromInteraction(point: CGPoint, anchorPoint: CGPoint?) {
+        guard let page = currentPage else { return }
+
+        let range: NSRange?
+        if let anchor = anchorPoint {
+            range = interactionController.selectionRange(from: anchor, to: point)
+        } else if let idx = interactionController.characterIndex(at: point) {
+            range = NSRange(location: idx, length: 1)
+        } else {
+            range = nil
+        }
+
+        guard let range else { return }
+        let rects = interactionController.selectionRects(for: range)
+        overlayView.updateSelection(absoluteRange: range, rects: rects)
+        selectionMenuAnchorRect = interactionController.menuAnchorRect(for: range)
+        notifySelectionChange(range: range, page: page)
+    }
+
+    @objc private func handleTap(_ gesture: UITapGestureRecognizer) {
+        clearSelection()
+    }
+
+    @objc private func rd_copy(_ sender: Any?) {
+        delegate?.textContentView(self, didRequestSelectionAction: .copy)
+    }
+
+    @objc private func rd_highlight(_ sender: Any?) {
+        delegate?.textContentView(self, didRequestSelectionAction: .highlight)
+    }
+
+    @objc private func rd_annotate(_ sender: Any?) {
+        delegate?.textContentView(self, didRequestSelectionAction: .annotate)
+    }
+
+    private func notifySelectionChange(range: NSRange, page: RDEPUBTextPage) {
+        let source = page.chapterContent.string as NSString
+        let selectedText = source.substring(with: range).trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !selectedText.isEmpty else {
+            delegate?.textContentView(self, didChangeSelection: nil)
+            return
+        }
+
+        let totalLength = max(page.content.length - 1, 1)
+        let relativeLocation = range.location - page.pageStartOffset
+        let selection = RDEPUBSelection(
+            location: RDEPUBLocation(
+                href: page.href,
+                progression: Double(max(relativeLocation, 0)) / Double(totalLength),
+                lastProgression: Double(max(relativeLocation + range.length - 1, 0)) / Double(totalLength),
+                fragment: nil
+            ),
+            text: selectedText,
+            rangeInfo: RDEPUBTextOffsetRangeInfo(href: page.href, start: range.location, end: range.location + range.length).jsonString()
+        )
+        delegate?.textContentView(self, didChangeSelection: selection)
+    }
+
+    private func showSelectionMenuIfNeeded() {
+#if canImport(DTCoreText)
+        guard overlayView.selectionRange?.length ?? 0 > 0,
+              let anchorRect = selectionMenuAnchorRect ?? overlayView.selectionRange.flatMap({ interactionController.menuAnchorRect(for: $0) }) else {
+            return
+        }
+
+        becomeFirstResponder()
+        let menuRect = overlayView.convert(anchorRect, to: self)
+        let menuController = UIMenuController.shared
+        menuController.menuItems = [
+            UIMenuItem(title: "拷贝", action: #selector(RDEPUBTextContentView.rd_copy(_:))),
+            UIMenuItem(title: "高亮", action: #selector(RDEPUBTextContentView.rd_highlight(_:))),
+            UIMenuItem(title: "批注", action: #selector(RDEPUBTextContentView.rd_annotate(_:)))
+        ]
+        menuController.setTargetRect(menuRect, in: self)
+        menuController.setMenuVisible(true, animated: true)
+#endif
+    }
+
     private func applyHighlights(to content: NSMutableAttributedString, page: RDEPUBTextPage) {
         applyHighlights(to: content, page: page, contentBaseOffset: page.pageStartOffset)
     }
@@ -317,6 +481,68 @@ final class RDEPUBTextContentView: UIView {
         return lowerBound..<max(upperBound, lowerBound)
     }
 
+#if canImport(DTCoreText)
+    private func buildOverlayDecorations(page: RDEPUBTextPage) -> (background: [RDEPUBTextOverlayDecoration], foreground: [RDEPUBTextOverlayDecoration]) {
+        var background: [RDEPUBTextOverlayDecoration] = []
+        var foreground: [RDEPUBTextOverlayDecoration] = []
+        let pageRange = absoluteOffsetRange(for: page)
+        let pageStart = pageRange.lowerBound
+        let pageEndExclusive = pageRange.upperBound
+
+        // Search results → background (behind text)
+        if let searchState = currentSearchState {
+            let normalColor = UIColor(red: 248 / 255, green: 225 / 255, blue: 108 / 255, alpha: 0.55)
+            let activeColor = UIColor(red: 255 / 255, green: 159 / 255, blue: 67 / 255, alpha: 0.75)
+
+            for match in searchState.matches where match.href == page.href {
+                guard let matchStart = match.rangeLocation else { continue }
+                let matchEnd = matchStart + match.rangeLength
+                let overlapStart = max(matchStart, pageStart)
+                let overlapEnd = min(matchEnd, pageEndExclusive)
+                guard overlapStart < overlapEnd else { continue }
+
+                let absoluteRange = NSRange(location: overlapStart, length: overlapEnd - overlapStart)
+                let rects = interactionController.selectionRects(for: absoluteRange)
+                guard !rects.isEmpty else { continue }
+
+                let isActive = match == searchState.currentMatch
+                let kind: RDEPUBTextOverlayDecoration.Kind = isActive ? .activeSearch : .search
+                let color = isActive ? activeColor : normalColor
+                background.append(RDEPUBTextOverlayDecoration(kind: kind, absoluteRange: absoluteRange, rects: rects, color: color))
+            }
+        }
+
+        // Highlights → background (filled) or foreground (underline)
+        for highlight in highlightedRanges where highlight.location.href == page.href {
+            guard let range = RDEPUBTextOffsetRangeInfo.decode(from: highlight.rangeInfo)?.nsRange else { continue }
+            let overlapStart = max(range.location, pageStart)
+            let overlapEnd = min(range.location + range.length, pageEndExclusive)
+            guard overlapStart < overlapEnd else { continue }
+
+            let absoluteRange = NSRange(location: overlapStart, length: overlapEnd - overlapStart)
+            let rects = interactionController.selectionRects(for: absoluteRange)
+            guard !rects.isEmpty else { continue }
+
+            let color = UIColor(hexString: highlight.color, alpha: 0.45)
+                ?? UIColor(red: 248 / 255, green: 225 / 255, blue: 108 / 255, alpha: 0.45)
+            let decoration = RDEPUBTextOverlayDecoration(
+                kind: highlight.style == .underline ? .underline : .highlight,
+                absoluteRange: absoluteRange,
+                rects: rects,
+                color: color
+            )
+
+            if decoration.kind == .underline {
+                foreground.append(decoration)
+            } else {
+                background.append(decoration)
+            }
+        }
+
+        return (background, foreground)
+    }
+#endif
+
     private func configureCoverIfNeeded(for page: RDEPUBTextPage) -> Bool {
         guard page.pageIndexInChapter == 0,
               page.href.lowercased().contains("cover"),
@@ -331,6 +557,8 @@ final class RDEPUBTextContentView: UIView {
         coreTextContentView.layoutFrame = nil
         coreTextDisplayContent = nil
         coreTextDisplayRange = nil
+        textView.isHidden = true
+        textView.isUserInteractionEnabled = false
 #endif
         textView.attributedText = nil
         return true
@@ -369,21 +597,6 @@ final class RDEPUBTextContentView: UIView {
         return nil
     }
 
-    private func normalizeInlineAttachments(in content: NSMutableAttributedString, basePointSize: CGFloat) {
-        guard content.length > 0 else { return }
-        content.enumerateAttribute(.attachment, in: NSRange(location: 0, length: content.length)) { value, range, _ in
-#if canImport(DTCoreText)
-            if let attachment = value as? DTTextAttachment {
-                RDEPUBTextRendererSupport.normalizeAttachmentLayoutForWXRead(
-                    attachment,
-                    fontPointSize: basePointSize
-                )
-                content.addAttribute(.attachment, value: attachment, range: range)
-            }
-#endif
-        }
-    }
-
     private func selectionProxyContent(from content: NSAttributedString) -> NSAttributedString {
         let proxy = NSMutableAttributedString(attributedString: content)
         let fullRange = NSRange(location: 0, length: proxy.length)
@@ -415,17 +628,24 @@ final class RDEPUBTextContentView: UIView {
         guard !coreTextContentView.isHidden,
               let displayContent = coreTextDisplayContent,
               let displayRange = coreTextDisplayRange,
+              let page = currentPage,
               coreTextContentView.bounds.width > 0,
               coreTextContentView.bounds.height > 0 else {
+            interactionController.configure(layoutFrame: nil, page: currentPage)
             return
         }
 
         guard let layouter = DTCoreTextLayouter(attributedString: displayContent) else {
             coreTextContentView.layoutFrame = nil
+            interactionController.configure(layoutFrame: nil, page: page)
             return
         }
         layouter.shouldCacheLayoutFrames = false
-        coreTextContentView.layoutFrame = layouter.layoutFrame(with: coreTextContentView.bounds, range: displayRange)
+        let layoutFrame = layouter.layoutFrame(with: coreTextContentView.bounds, range: displayRange)
+        coreTextContentView.layoutFrame = layoutFrame
+        interactionController.configure(layoutFrame: layoutFrame, page: page)
+        overlayView.updateSnapshot(interactionController.snapshot)
+        backgroundOverlayView.updateSnapshot(interactionController.snapshot)
     }
 #endif
 
@@ -433,6 +653,7 @@ final class RDEPUBTextContentView: UIView {
 
 extension RDEPUBTextContentView: UITextViewDelegate {
     func textViewDidChangeSelection(_ textView: UITextView) {
+        guard !isSelectionFromInteraction else { return }
         guard let page = currentPage else {
             delegate?.textContentView(self, didChangeSelection: nil)
             return