feat: EPUB 阅读器搜索、选中注释、书签 chrome 状态及大量重构优化

- 新增 RDEPUBReaderSearchCoordinator 与 RDEPUBSelectionState 管理搜索和选中状态 - 新增 BookmarkChromeStateTests、NavigationBackwardTests、SelectionAnnotateTests 等 UI 测试 - 新增多个边界测试 epub 样本（损坏结构、空归档、缺失文件、流式外链验证） - 重构阅读器 chrome 状态管理，统一 tool bar 与 search bar 交互 - 优化大书分页缓存策略（RDEPUBChapterSummaryDiskCache、RDEPUBPageCountCache） - 移除废弃的 RDEPUBLocationConverter 和 RDEPUBPageBreakPolicy - 更新 epub-bridge.js 与 JS bridge 通信协议 - 全面更新现有 UI 测试以适配新的 helper 和状态管理
2026-06-13 22:48:56 +08:00
parent 27e9b85ddb
commit 6f75b083f7
83 changed files with 4824 additions and 1879 deletions
@@ -34,8 +34,28 @@ final class RDEPUBChapterSummaryDiskCache {

    func read(for key: RDEPUBChapterCacheKey) -> RDEPUBChapterSummary? {
        let fileURL = self.fileURL(for: key)
-        guard let data = try? Data(contentsOf: fileURL) else { return nil }
-        return try? JSONDecoder().decode(RDEPUBChapterSummary.self, from: data)
+        let data: Data
+        do {
+            data = try Data(contentsOf: fileURL)
+        } catch {
+            let nsError = error as NSError
+            if nsError.domain == NSCocoaErrorDomain && nsError.code == NSFileReadNoSuchFileError {
+                // 文件不存在属于正常缓存未命中，不报错
+            } else {
+                #if DEBUG
+                print("[RDEPUBChapterSummaryDiskCache] ⚠️ read IO error for \(fileURL.lastPathComponent): \(error.localizedDescription)")
+                #endif
+            }
+            return nil
+        }
+        do {
+            return try JSONDecoder().decode(RDEPUBChapterSummary.self, from: data)
+        } catch {
+            #if DEBUG
+            print("[RDEPUBChapterSummaryDiskCache] ⚠️ decode error for \(fileURL.lastPathComponent): \(error.localizedDescription)")
+            #endif
+            return nil
+        }
    }

    // MARK: - 批量读取：二次打开时直接从磁盘构建 BookPageMap
@@ -75,32 +95,78 @@ final class RDEPUBChapterSummaryDiskCache {
        return true
    }

-    /// 语义化别名：用于判断当前 renderSignature 下是否具备完整章节摘要集合。
-    func containsCompleteSet(keys: [RDEPUBChapterCacheKey]) -> Bool {
-        isCacheComplete(keys: keys)
-    }
-
    /// 清空所有缓存文件
    func removeAll() {
-        guard let files = try? fileManager.contentsOfDirectory(at: cacheDirectory, includingPropertiesForKeys: nil) else { return }
-        for fileURL in files where fileURL.pathExtension == "json" {
-            try? fileManager.removeItem(at: fileURL)
+        removeFiles(matching: { _ in true })
+    }
+
+    /// 清空指定书籍的所有缓存文件
+    func removeAll(forBookID bookID: String) {
+        let bookPrefix = Self.cacheNamespacePrefix(for: bookID)
+        removeFiles { $0.hasPrefix(bookPrefix + "__") }
+    }
+
+    /// 清空指定渲染签名下的所有缓存文件
+    func removeAll(forRenderSignature renderSignature: String) {
+        let renderPrefix = "__" + Self.cacheNamespacePrefix(for: renderSignature) + "__"
+        removeFiles { $0.contains(renderPrefix) }
+    }
+
+    /// 缓存统计信息
+    var cacheStatistics: (fileCount: Int, totalBytes: Int64) {
+        guard let files = try? fileManager.contentsOfDirectory(at: cacheDirectory, includingPropertiesForKeys: [.fileSizeKey]) else {
+            return (0, 0)
        }
+        var count = 0
+        var totalBytes: Int64 = 0
+        for fileURL in files where fileURL.pathExtension == "json" {
+            count += 1
+            if let size = try? fileURL.resourceValues(forKeys: [.fileSizeKey]).fileSize {
+                totalBytes += Int64(size)
+            }
+        }
+        return (count, totalBytes)
    }

    // MARK: - key -> 文件路径

    /// 使用确定性字符串拼接生成文件名，不依赖 Hashable.hashValue
    private func fileURL(for key: RDEPUBChapterCacheKey) -> URL {
+        let bookPrefix = Self.cacheNamespacePrefix(for: key.bookID)
+        let renderPrefix = Self.cacheNamespacePrefix(for: key.renderSignature)
        let rawKey = "\(key.bookID)_\(key.spineIndex)_\(key.renderSignature)_\(key.chapterContentHash)"
        let digest = rawKey.sha256Hex
-        return cacheDirectory.appendingPathComponent("\(digest).json")
+        return cacheDirectory.appendingPathComponent("\(bookPrefix)__\(renderPrefix)__\(digest).json")
    }

    private func writeImmediately(summary: RDEPUBChapterSummary, for key: RDEPUBChapterCacheKey) {
        let fileURL = self.fileURL(for: key)
-        let data = try? JSONEncoder().encode(summary)
-        try? data?.write(to: fileURL)
+        let tmpURL = fileURL.appendingPathExtension("tmp")
+        do {
+            let data = try JSONEncoder().encode(summary)
+            try data.write(to: tmpURL)
+            if fileManager.fileExists(atPath: fileURL.path) {
+                _ = try fileManager.replaceItemAt(fileURL, withItemAt: tmpURL)
+            } else {
+                try fileManager.moveItem(at: tmpURL, to: fileURL)
+            }
+        } catch {
+            #if DEBUG
+            print("[RDEPUBChapterSummaryDiskCache] ⚠️ write error for \(fileURL.lastPathComponent): \(error.localizedDescription)")
+            #endif
+            try? fileManager.removeItem(at: tmpURL)
+        }
+    }
+
+    private func removeFiles(matching predicate: (String) -> Bool) {
+        guard let files = try? fileManager.contentsOfDirectory(at: cacheDirectory, includingPropertiesForKeys: nil) else { return }
+        for fileURL in files where fileURL.pathExtension == "json" && predicate(fileURL.lastPathComponent) {
+            try? fileManager.removeItem(at: fileURL)
+        }
+    }
+
+    private static func cacheNamespacePrefix(for rawValue: String) -> String {
+        rawValue.sha256Hex.prefix(12).lowercased()
    }
 }

@@ -52,7 +52,9 @@ final class RDEPUBChapterWindowCoordinator {
                self.isSwitchingChapter = false
                self.buildSnapshotAroundCurrent(chapter: chapter)
            case .failure(let error):
+                #if DEBUG
                print("[EPUB][WindowCoord] loadChapter failed at spine=\(initialSpineIndex): \(error), trying next")
+                #endif
                // 自动跳过不可渲染的章节（封面/版权页等 linear=false 的 spine 项）
                let nextIndex = initialSpineIndex + 1
                if nextIndex < totalSpineCount {
@@ -76,7 +78,9 @@ final class RDEPUBChapterWindowCoordinator {

    private func buildSnapshotAroundCurrent(chapter: RDEPUBRuntimeChapter) {
        guard let current = store.currentSpineIndex else {
+            #if DEBUG
            print("[EPUB][WindowCoord] buildSnapshot: currentSpineIndex is nil, ABORT")
+            #endif
            return
        }
        let chapters = store.windowSpineIndices.compactMap { spineIndex -> RDEPUBRuntimeChapter? in
@@ -86,7 +90,9 @@ final class RDEPUBChapterWindowCoordinator {
            return store.chapterData(for: spineIndex)
        }
        let snapshot = RDEPUBChapterWindowSnapshot.from(chapters: chapters, anchorSpineIndex: current)
+        #if DEBUG
        print("[EPUB][WindowCoord] snapshot: chapters=\(snapshot.chapters.count) pages=\(snapshot.pageCount) anchorPage=\(snapshot.anchorPageOffset)")
+        #endif
        currentSnapshot = snapshot
        isApplyingSnapshot = true
        onSnapshotChanged?(snapshot)
@@ -240,14 +246,18 @@ final class RDEPUBChapterWindowCoordinator {

    private func handle(error: Error) {
        // 日志记录，不中断当前阅读状态
+        #if DEBUG
        print("[RDEPUBChapterWindowCoordinator] chapter load error: \(error)")
+        #endif
        // 确保 loading 指示器在加载失败时也被隐藏（避免永久白屏）
        DispatchQueue.main.async { [weak self] in
            guard let self else { return }
            self.context.hideLoading()
            // 如果有快照但没内容显示，显示错误提示
            if self.currentSnapshot == nil {
+                #if DEBUG
                print("[RDEPUBChapterWindowCoordinator] No snapshot after error, page will be blank")
+                #endif
            }
        }
    }
@@ -1,111 +0,0 @@
-import Foundation
-
-struct RDEPUBLocationConverter {
-
-    // MARK: - 主路径：先构建目标章，拿到真实长度后再精确转换
-
-    /// 旧版 RDEPUBLocation -> 新版 RDEPUBChapterLocation
-    /// 主迁移路径：要求先构建目标章，用真实 chapterLength 做精确转换
-    /// 仅在无法获取章节长度时才降级到粗估 fallback
-    static func convert(
-        legacy location: RDEPUBLocation,
-        parser: RDEPUBParser,
-        publication: RDEPUBPublication,
-        chapterLengthProvider: ((Int) -> Int?)? = nil
-    ) -> RDEPUBChapterLocation? {
-        // 1. 从 href 找到 spineIndex
-        guard let spineItem = publication.spine.first(where: {
-            $0.href == location.href || $0.href.contains(location.href)
-        }) else { return nil }
-
-        let spineIndex = publication.spine.firstIndex(of: spineItem) ?? 0
-
-        // 2. 优先用 fragmentID 定位（最精确，不受 progression 精度影响）
-        if let fragmentID = location.fragment {
-            return RDEPUBChapterLocation(
-                spineIndex: spineIndex,
-                chapterOffset: 0,  // fragmentID 由 chapterOffsetMap 精确解析
-                fragmentID: fragmentID,
-                progressionInChapter: location.progression
-            )
-        }
-
-        // 3. 有 chapterLength 时做精确转换
-        if let provider = chapterLengthProvider,
-           let chapterLength = provider(spineIndex), chapterLength > 0 {
-            return convert(
-                legacy: location,
-                spineIndex: spineIndex,
-                chapterLength: chapterLength
-            )
-        }
-
-        // 4. Fallback：无法获取章节长度时的粗估（仅作临时降级）
-        let estimatedOffset = Int(location.progression * 10000)
-        return RDEPUBChapterLocation(
-            spineIndex: spineIndex,
-            chapterOffset: estimatedOffset,
-            fragmentID: nil,
-            progressionInChapter: location.progression,
-            schemaVersion: 1  // 标记为降级结果，后续可被精确值覆盖
-        )
-    }
-
-    /// 精确转换：已知章节实际长度
-    static func convert(
-        legacy location: RDEPUBLocation,
-        spineIndex: Int,
-        chapterLength: Int
-    ) -> RDEPUBChapterLocation? {
-        let offset = Int(location.progression * Double(chapterLength))
-        return RDEPUBChapterLocation(
-            spineIndex: spineIndex,
-            chapterOffset: offset,
-            fragmentID: location.fragment,
-            progressionInChapter: location.progression,
-            schemaVersion: 2
-        )
-    }
-
-    /// 从已构建的 RDEPUBRuntimeChapter 做精确转换（推荐迁移路径）
-    static func convert(
-        legacy location: RDEPUBLocation,
-        chapter: RDEPUBRuntimeChapter
-    ) -> RDEPUBChapterLocation? {
-        // 优先用 fragmentID
-        if let fragmentID = location.fragment,
-           let fragmentOffset = chapter.chapterOffsetMap.chapterOffset(forFragmentID: fragmentID) {
-            return RDEPUBChapterLocation(
-                spineIndex: chapter.spineIndex,
-                chapterOffset: fragmentOffset,
-                fragmentID: fragmentID,
-                progressionInChapter: nil,
-                schemaVersion: 2
-            )
-        }
-
-        // 用 progression + 真实长度
-        let chapterLength = chapter.typesetAttributedString.length
-        return convert(
-            legacy: location,
-            spineIndex: chapter.spineIndex,
-            chapterLength: chapterLength
-        )
-    }
-
-    /// 新版 -> 旧版（兼容外部接口）
-    static func toLegacy(
-        chapterLocation: RDEPUBChapterLocation,
-        href: String,
-        chapterLength: Int
-    ) -> RDEPUBLocation {
-        let progression = chapterLength > 0
-            ? Double(chapterLocation.chapterOffset) / Double(chapterLength)
-            : 0
-        return RDEPUBLocation(
-            href: href,
-            progression: min(max(progression, 0), 1),
-            fragment: chapterLocation.fragmentID
-        )
-    }
-}
@@ -17,12 +17,6 @@ final class RDEPUBPageCountCache {
        }
    }

-    func entriesForSpineIndex(_ spineIndex: Int) -> [(RDEPUBChapterCacheKey, RDEPUBRuntimePageCount)] {
-        lock.lock()
-        defer { lock.unlock() }
-        return storage.filter { $0.value.spineIndex == spineIndex }.map { ($0.key, $0.value) }
-    }
-
    func remove(forSpineIndex spineIndex: Int) {
        lock.lock()
        defer { lock.unlock() }
@@ -32,14 +32,34 @@ final class RDEPUBReaderAnnotationCoordinator {

    /// 更新当前文本选区状态，并同步刷新底部工具栏的高亮按钮可用性。
    func updateCurrentSelection(_ selection: RDEPUBSelection?) {
+        if let selection, !selection.isEmpty {
+            applySelectionState(.selected(selection))
+        } else {
+            applySelectionState(.idle)
+        }
+    }
+
+    /// 统一选区状态变更入口。
+    /// 在 `.selected` 时：更新 context 选区、显示工具栏、刷新 chrome、通知 delegate。
+    /// 在 `.idle` 时：清空选区、刷新 chrome、通知 delegate。
+    func applySelectionState(_ state: RDEPUBSelectionState) {
        guard let controller else { return }
-        controller.currentSelection = selection?.isEmpty == false ? selection : nil
-        if controller.currentSelection != nil,
-           controller.readerView.isShowToolView == false {
-            controller.readerView.tapCenter()
+        context.selectionState = state
+        switch state {
+        case .idle:
+            controller.updateReaderChrome()
+            controller.delegate?.epubReader(controller, didChangeSelection: nil)
+        case .selecting:
+            break
+        case .selected(let selection):
+            if controller.readerView.isShowToolView == false {
+                controller.readerView.tapCenter()
+            }
+            controller.updateReaderChrome()
+            controller.delegate?.epubReader(controller, didChangeSelection: selection)
+        case .committingAction:
+            break
        }
-        controller.updateReaderChrome()
-        controller.delegate?.epubReader(controller, didChangeSelection: controller.currentSelection)
    }

    /// 基于当前选区添加高亮标记，自动去重并持久化。
@@ -139,11 +159,10 @@ final class RDEPUBReaderAnnotationCoordinator {
    /// 跳转到指定高亮所在位置。
    @discardableResult
    func go(toHighlightID id: String, animated: Bool = true) -> Bool {
-        guard let controller else { return false }
        guard let highlight = highlight(withID: id) else {
            return false
        }
-        return controller.restoreReadingLocation(highlight.location, animated: animated)
+        return navigate(to: highlight, animated: animated)
    }

    /// 清除所有高亮标记。
@@ -196,9 +215,8 @@ final class RDEPUBReaderAnnotationCoordinator {
            }
        )
        highlightsController.onSelectHighlight = { [weak self, weak highlightsController] highlight in
-            guard let controller = self?.controller else { return }
            highlightsController?.dismiss(animated: true) {
-                controller.go(to: highlight.location)
+                _ = self?.navigate(to: highlight, animated: true)
            }
        }
        highlightsController.onUpdateHighlight = { [weak self] highlight in
@@ -371,6 +389,17 @@ final class RDEPUBReaderAnnotationCoordinator {
        )
    }

+    @discardableResult
+    private func navigate(to highlight: RDEPUBHighlight, animated: Bool) -> Bool {
+        guard let controller else { return false }
+        let navigationTarget = scopedHighlight(highlight) ?? highlight
+        return controller.restoreReadingLocation(
+            navigationTarget.location,
+            animated: animated,
+            targetHighlightRangeInfo: navigationTarget.rangeInfo
+        )
+    }
+
    private func persistHighlightsAndRefreshContent() {
        guard let controller else { return }
        if let currentBookIdentifier = controller.currentBookIdentifier {
@@ -23,7 +23,9 @@ final class RDEPUBReaderAssemblyCoordinator {
        setupLoadingIndicator(controller.loadingIndicator, in: controller.view)
        setupErrorLabel(controller.errorLabel, in: controller.view)
        controller.delegate?.epubReader(controller, configureTopToolView: controller.topToolView)
+        #if DEBUG
        print("[ReadViewDemo] assembleInterface: dataSource=\(readerView.dataSource != nil ? "set" : "nil"), numberOfPages=\(readerView.numberOfPages())")
+        #endif
    }

    /// 外部纯文本图书启动时，加载已保存的书签、高亮和阅读位置，完成分页收尾。
@@ -41,9 +43,13 @@ final class RDEPUBReaderAssemblyCoordinator {
        }

        if let textBook = controller.textBook {
+            #if DEBUG
            print("[ReadViewDemo] finishExternalTextBook: applying textBook with \(textBook.pages.count) pages")
+            #endif
            runtime.applyTextBook(textBook, restoreLocation: restoreLocation)
+            #if DEBUG
            print("[ReadViewDemo] finishExternalTextBook: after applyTextBook, numberOfPages=\(context.readerView?.numberOfPages() ?? -1)")
+            #endif
        } else {
            runtime.finishPagination(restoreLocation: restoreLocation)
        }
@@ -70,7 +70,7 @@ final class RDEPUBReaderChromeCoordinator {
            canToggleBookmark: controller.currentBookIdentifier != nil,
            hasBookmarkAtCurrentLocation: hasBookmarkAtCurrentLocation(),
            canShowBookmarks: !controller.activeBookmarks.isEmpty,
-            canAddHighlight: controller.configuration.allowsHighlights && controller.currentSelection != nil,
+            canAddHighlight: controller.configuration.allowsHighlights && context.selectionState.hasSelection,
            canShowHighlights: controller.configuration.allowsHighlights && !controller.activeHighlights.isEmpty,
            showsTableOfContents: controller.configuration.showsTableOfContents,
            allowsHighlights: controller.configuration.allowsHighlights,
@@ -59,8 +59,19 @@ final class RDEPUBReaderContext {
    var lastMetadataParseWallClockMs: Int = 0
    /// 后台元数据解析使用的并发数。
    var lastMetadataParseConcurrency: Int = 0
-    /// 当前用户文本选区。
-    var currentSelection: RDEPUBSelection?
+    /// 当前用户文本选区（对外只读语义，底层由 selectionState 推导）。
+    var currentSelection: RDEPUBSelection? {
+        get { selectionState.selection }
+        set {
+            if let newValue, !newValue.isEmpty {
+                selectionState = .selected(newValue)
+            } else {
+                selectionState = .idle
+            }
+        }
+    }
+    /// 统一选区状态模型，收口所有选区相关状态变更。
+    var selectionState: RDEPUBSelectionState = .idle

    // MARK: - 控制器状态（从 controller 下沉）

@@ -16,7 +16,11 @@ final class RDEPUBReaderLocationCoordinator {

    /// 恢复到指定阅读位置，返回是否成功跳转。
    @discardableResult
-    func restoreReadingLocation(_ location: RDEPUBLocation, animated: Bool = false) -> Bool {
+    func restoreReadingLocation(
+        _ location: RDEPUBLocation,
+        animated: Bool = false,
+        targetHighlightRangeInfo: String? = nil
+    ) -> Bool {
        guard let controller = context.controller,
              let readerView = context.readerView else { return false }
        guard let targetPageNumber = controller.pageNumber(for: location) else {
@@ -32,13 +36,15 @@ final class RDEPUBReaderLocationCoordinator {
            _ = context.readingSession?.queueNavigation(
                to: location,
                relativeToSpineIndex: nil,
-                bookIdentifier: context.currentBookIdentifier
+                bookIdentifier: context.currentBookIdentifier,
+                targetHighlightRangeInfo: targetHighlightRangeInfo
            )
        } else if context.textBook == nil {
            _ = context.readingSession?.queueNavigation(
                to: location,
                relativeToSpineIndex: nil,
-                bookIdentifier: context.currentBookIdentifier
+                bookIdentifier: context.currentBookIdentifier,
+                targetHighlightRangeInfo: targetHighlightRangeInfo
            )
        } else {
            context.readingSession?.transition(to: .jumping)
@@ -33,10 +33,14 @@ final class RDEPUBReaderPaginationCoordinator {
        controller.showLoading()
        let token = UUID()
        context.paginationToken = token
+        #if DEBUG
        print("[EPUB][Pagination] profile=\(publication.readingProfile.rawValue) layout=\(publication.layout.rawValue) spine=\(publication.spine.count)")
+        #endif

        if publication.readingProfile == .textReflowable {
+            #if DEBUG
            print("[EPUB][Pagination] path=text-reflowable-on-demand")
+            #endif
            paginateTextPublication(
                parser: parser,
                publication: publication,
@@ -48,7 +52,9 @@ final class RDEPUBReaderPaginationCoordinator {
        }

        if publication.layout == .fixed {
+            #if DEBUG
            print("[EPUB][Pagination] path=fixed-layout")
+            #endif
            let snapshot = readingSession.makePaginationSnapshot(
                pageCounts: Array(repeating: 1, count: publication.spine.count),
                preferences: controller.currentPreferences(),
@@ -59,7 +65,9 @@ final class RDEPUBReaderPaginationCoordinator {
        }

        let paginator = context.makePaginator()
+        #if DEBUG
        print("[EPUB][Pagination] path=web-paginator")
+        #endif
        context.paginator = paginator
        paginator.calculate(
            parser: parser,
@@ -230,6 +230,12 @@ final class RDEPUBReaderRuntime {
        searchCoordinator.searchPrevious()
    }

+    /// 跳转到指定搜索匹配项
+    @discardableResult
+    func selectSearchMatch(at index: Int) -> Bool {
+        searchCoordinator.selectSearchMatch(at: index)
+    }
+
    /// 清除搜索状态
    func clearSearch() {
        searchCoordinator.clearSearch()
@@ -365,8 +371,16 @@ final class RDEPUBReaderRuntime {

    /// 恢复到指定阅读位置
    @discardableResult
-    func restoreReadingLocation(_ location: RDEPUBLocation, animated: Bool = false) -> Bool {
-        locationCoordinator.restoreReadingLocation(location, animated: animated)
+    func restoreReadingLocation(
+        _ location: RDEPUBLocation,
+        animated: Bool = false,
+        targetHighlightRangeInfo: String? = nil
+    ) -> Bool {
+        locationCoordinator.restoreReadingLocation(
+            location,
+            animated: animated,
+            targetHighlightRangeInfo: targetHighlightRangeInfo
+        )
    }

    /// 获取当前可见页面的阅读位置
@@ -51,6 +51,21 @@ final class RDEPUBReaderSearchCoordinator {
        advanceSearch(by: -1)
    }

+    /// 跳转到指定索引的搜索匹配项
+    @discardableResult
+    func selectSearchMatch(at index: Int) -> Bool {
+        guard let controller else { return false }
+        guard var searchState = controller.searchState,
+              searchState.matches.indices.contains(index) else {
+            return false
+        }
+
+        searchState.currentMatchIndex = index
+        controller.searchState = searchState
+        notifySearchStateChanged()
+        return navigateToCurrentSearchMatch(animated: true)
+    }
+
    /// 清除搜索状态并刷新当前可见内容
    func clearSearch() {
        guard let controller else { return }
@@ -109,12 +124,109 @@ final class RDEPUBReaderSearchCoordinator {
            }
            return RDEPUBTextSearchEngine.searchWithoutPublication(textBook: textBook, keyword: keyword)
        }
+        if controller.readerContext.bookPageMap != nil, controller.publication != nil {
+            return resolvedOnDemandSearchMatches(for: keyword)
+        }
        if let parser = controller.parser, let publication = controller.publication {
            return RDEPUBHTMLSearchEngine(parser: parser, publication: publication).search(keyword: keyword)
        }
        return []
    }

+    private func resolvedOnDemandSearchMatches(for keyword: String) -> [RDEPUBSearchMatch] {
+        guard let controller,
+              let publication = controller.publication else {
+            return []
+        }
+
+        let normalizedKeyword = keyword.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !normalizedKeyword.isEmpty else {
+            return []
+        }
+
+        let buildableSpineIndices = publication.spine.indices.filter { index in
+            let item = publication.spine[index]
+            return item.linear && (item.mediaType.contains("html") || item.mediaType.contains("xhtml"))
+        }
+
+        var matches: [RDEPUBSearchMatch] = []
+        for spineIndex in buildableSpineIndices {
+            guard let chapter = try? controller.runtime.chapterLoader.loadChapterSynchronouslyForMigration(
+                spineIndex: spineIndex,
+                store: controller.runtime.chapterRuntimeStore
+            ) else {
+                continue
+            }
+
+            let chapterData = makeChapterData(from: chapter, chapterIndex: chapter.pages.first?.chapterIndex ?? 0)
+            let source = chapter.typesetAttributedString.string as NSString
+            let fullLength = source.length
+            guard fullLength > 0 else { continue }
+
+            let normalizedHref = publication.resourceResolver.normalizedHref(chapter.href) ?? chapter.href
+            var localMatchIndex = 0
+            var searchRange = NSRange(location: 0, length: fullLength)
+
+            while searchRange.length > 0 {
+                let foundRange = source.range(of: normalizedKeyword, options: [.caseInsensitive], range: searchRange)
+                guard foundRange.location != NSNotFound else {
+                    break
+                }
+
+                let progressionDenominator = max(fullLength - 1, 1)
+                let progression = Double(foundRange.location) / Double(progressionDenominator)
+                matches.append(
+                    RDEPUBSearchMatch(
+                        href: normalizedHref,
+                        progression: progression,
+                        previewText: previewText(in: source, matchRange: foundRange),
+                        localMatchIndex: localMatchIndex,
+                        rangeLocation: foundRange.location,
+                        rangeLength: foundRange.length,
+                        rangeAnchor: chapterData.rangeAnchor(for: foundRange)
+                    )
+                )
+
+                localMatchIndex += 1
+                let nextLocation = foundRange.location + max(foundRange.length, 1)
+                if nextLocation >= fullLength {
+                    break
+                }
+                searchRange = NSRange(location: nextLocation, length: fullLength - nextLocation)
+            }
+        }
+
+        return matches
+    }
+
+    private func makeChapterData(
+        from runtimeChapter: RDEPUBRuntimeChapter,
+        chapterIndex: Int
+    ) -> RDEPUBChapterData {
+        let textChapter = RDEPUBTextChapter(
+            chapterIndex: chapterIndex,
+            spineIndex: runtimeChapter.spineIndex,
+            href: runtimeChapter.href,
+            title: runtimeChapter.title,
+            attributedContent: runtimeChapter.typesetAttributedString,
+            fragmentOffsets: runtimeChapter.chapterOffsetMap.fragmentOffsets,
+            pageBreakReasons: runtimeChapter.pages.map(\.metadata.breakReason),
+            pages: runtimeChapter.pages
+        )
+        return RDEPUBChapterData(
+            chapter: textChapter,
+            indexTable: RDEPUBTextIndexTable(chapters: [textChapter])
+        )
+    }
+
+    private func previewText(in text: NSString, matchRange: NSRange) -> String {
+        let previewRadius = 12
+        let start = max(matchRange.location - previewRadius, 0)
+        let end = min(matchRange.location + matchRange.length + previewRadius, text.length)
+        let range = NSRange(location: start, length: max(end - start, 0))
+        return text.substring(with: range).trimmingCharacters(in: .whitespacesAndNewlines)
+    }
+
    private func advanceSearch(by delta: Int) -> Bool {
        guard let controller else { return false }
        guard var searchState = controller.searchState, !searchState.matches.isEmpty else {
@@ -162,6 +274,14 @@ final class RDEPUBReaderSearchCoordinator {
    private func pageNumber(for searchMatch: RDEPUBSearchMatch) -> Int? {
        guard let controller else { return nil }
        if let chapterData = controller.textChapterData(forNormalizedHref: searchMatch.href) {
+            if let exactPageNumber = exactPageNumber(
+                for: searchMatch,
+                in: chapterData,
+                keyword: controller.searchState?.keyword
+            ) {
+                return exactPageNumber
+            }
+
            if let pageNumber = chapterData.pageNumber(for: searchMatch) {
                return pageNumber
            }
@@ -194,4 +314,39 @@ final class RDEPUBReaderSearchCoordinator {
            bookIdentifier: controller.currentBookIdentifier
        ).map { $0 + 1 }
    }
+
+    private func exactPageNumber(
+        for searchMatch: RDEPUBSearchMatch,
+        in chapterData: RDEPUBChapterData,
+        keyword: String?
+    ) -> Int? {
+        let normalizedKeyword = keyword?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        guard !normalizedKeyword.isEmpty else { return nil }
+
+        let source = chapterData.attributedContent.string as NSString
+        let fullLength = source.length
+        guard fullLength > 0 else { return nil }
+
+        var localMatchIndex = 0
+        var searchRange = NSRange(location: 0, length: fullLength)
+
+        while searchRange.length > 0 {
+            let foundRange = source.range(of: normalizedKeyword, options: [.caseInsensitive], range: searchRange)
+            guard foundRange.location != NSNotFound else { break }
+
+            if localMatchIndex == searchMatch.localMatchIndex,
+               let page = chapterData.page(containing: foundRange.location) {
+                return page.absolutePageIndex + 1
+            }
+
+            localMatchIndex += 1
+            let nextLocation = foundRange.location + max(foundRange.length, 1)
+            if nextLocation >= fullLength {
+                break
+            }
+            searchRange = NSRange(location: nextLocation, length: fullLength - nextLocation)
+        }
+
+        return nil
+    }
 }
@@ -0,0 +1,39 @@
+// RDEPUBSelectionState.swift
+// 统一选区状态模型
+// 收口选区相关状态的冗余表达，降低 view 层与 controller 层各持有一份选区状态
+// 所带来的维护成本和时序问题。
+
+import Foundation
+
+/// 统一选区状态枚举
+/// 替代原先散落在 view/controller/coordinator 的 `currentSelection != nil` 判断
+enum RDEPUBSelectionState: Equatable {
+    /// 无选区
+    case idle
+    /// 用户正在拖拽选区（长按手势已开始，尚未松手）
+    case selecting(anchor: Int)
+    /// 选区已完成（用户松手，有有效文本）
+    case selected(RDEPUBSelection)
+    /// 正在执行选区菜单动作（拷贝/高亮/批注），动作完成后回到 idle
+    case committingAction(RDEPUBSelection, action: RDEPUBAnnotationMenuAction)
+
+    /// 当前是否有有效选区（selecting / selected / committingAction 均视为有选区）
+    var hasSelection: Bool {
+        switch self {
+        case .idle:
+            return false
+        case .selecting, .selected, .committingAction:
+            return true
+        }
+    }
+
+    /// 当前选区数据（如有）
+    var selection: RDEPUBSelection? {
+        switch self {
+        case .idle, .selecting:
+            return nil
+        case .selected(let selection), .committingAction(let selection, _):
+            return selection
+        }
+    }
+}