feat: 交互协调器拆分、附件提示、暗色图片适配、选区放大镜及文档清理

- 拆分 ContentDelegates/TextContentView 为独立协调器（InteractionCoordinator、LocationResolution、ExternalLinks、AttachmentTooltip）
- 新增 RDEPUBAttachmentTooltipView/OverlayView 附件气泡提示
- 新增 RDEPUBDarkImageAdjuster 暗色模式图片亮度适配
- 新增 RDEPUBSelectionLoupeView 选区放大镜
- 新增 MetadataParseWorker/CancellationController 元数据解析取消机制
- 重构 PresentationRuntime/PaginationCoordinator 精简职责
- 优化 ChapterLoader/WarmupOrchestrator 异步章节加载
- CFI 模块微调与 NoteModels 更新
- 清理冗余文档，更新架构/UML/业务逻辑文档

Co-Authored-By: Claude <noreply@anthropic.com>

Sources/RDReaderView/EPUBUI/ReaderController/ChapterRuntime/RDEPUBChapterLoader.swift

@@ -2,10 +2,21 @@ import Foundation
 
 final class RDEPUBChapterLoader {
 
-    private unowned let context: RDEPUBReaderContext
+    private typealias LoadCompletion = (Result<RDEPUBRuntimeChapter, Error>) -> Void
+
+    private struct PendingLoad {
+        var priority: LoadPriority
+        var completions: [LoadCompletion]
+    }
+
+    private weak var context: RDEPUBReaderContext?
 
     private var summaryDiskCache: RDEPUBChapterSummaryDiskCache?
 
+    private let pendingLoadsLock = NSLock()
+
+    private var pendingLoads: [Int: PendingLoad] = [:]
+
     var onDeferredCFIMapReady: ((Int) -> Void)?
 
     init(context: RDEPUBReaderContext) {
@@ -25,31 +36,70 @@ final class RDEPUBChapterLoader {
         case prefetch
     }
 
+    private enum LoadRegistrationResult {
+        case created
+        case joined(existingPriority: LoadPriority, effectivePriority: LoadPriority)
+    }
+
     func loadChapter(
         spineIndex: Int,
         store: RDEPUBChapterRuntimeStore,
         priority: LoadPriority = .navigation,
         completion: @escaping (Result<RDEPUBRuntimeChapter, Error>) -> Void
     ) {
+        RDEPUBBackgroundTrace.log("ChapterLoader", "request spine=\(spineIndex) priority=\(priority)")
 
         if let cached = store.chapterData(for: spineIndex) {
             RDEPUBBackgroundTrace.log("ChapterLoader", "cache hit spine=\(spineIndex) priority=\(priority)")
-            scheduleDeferredCFIMapBuildIfNeeded(
-                for: cached,
-                cacheKey: makeCacheKey(spineIndex: spineIndex),
-                store: store
-            )
+            if let context {
+                scheduleDeferredCFIMapBuildIfNeeded(
+                    for: cached,
+                    cacheKey: makeCacheKey(spineIndex: spineIndex, context: context),
+                    store: store
+                )
+            }
             DispatchQueue.main.async {
                 completion(.success(cached))
             }
             return
         }
 
-        store.markBuilding(true)
+        let completionOnMain: LoadCompletion = { result in
+            DispatchQueue.main.async {
+                completion(result)
+            }
+        }
 
-        store.chapterLoadQueue.async {
-            RDEPUBBackgroundTrace.log("ChapterLoader", "queue start spine=\(spineIndex) priority=\(priority)")
-            let cacheKey = self.makeCacheKey(spineIndex: spineIndex)
+        let registration = registerPendingLoad(
+            spineIndex: spineIndex,
+            priority: priority,
+            completion: completionOnMain
+        )
+
+        switch registration {
+        case .joined(let existingPriority, let effectivePriority):
+            RDEPUBBackgroundTrace.log(
+                "ChapterLoader",
+                "dedupe spine=\(spineIndex) existingPriority=\(existingPriority) requestedPriority=\(priority) effectivePriority=\(effectivePriority)"
+            )
+            return
+        case .created:
+            break
+        }
+
+        store.markBuilding(true)
+        _ = store.beginPendingChapterLoad(for: spineIndex)
+
+        store.chapterLoadQueue.async { [self] in
+            guard let context = self.context else {
+                store.endPendingChapterLoad(for: spineIndex)
+                store.markBuilding(false)
+                self.resolvePendingLoad(spineIndex: spineIndex, result: .failure(RDEPUBChapterLoadError.missingParser))
+                return
+            }
+            let queuePriority = self.pendingPriority(for: spineIndex) ?? priority
+            RDEPUBBackgroundTrace.log("ChapterLoader", "queue start spine=\(spineIndex) priority=\(queuePriority)")
+            let cacheKey = self.makeCacheKey(spineIndex: spineIndex, context: context)
 
             let precomputedPageRanges = store.pageCount(for: cacheKey)?.pageRanges
             let diskSummary: RDEPUBChapterSummary?
@@ -71,12 +121,13 @@ final class RDEPUBChapterLoader {
 
                 let chapter = try RDEPUBBackgroundTrace.measure(
                     "ChapterLoader",
-                    "buildChapter spine=\(spineIndex) priority=\(priority) cachedRanges=\(availablePageRanges?.count ?? 0)"
+                    "buildChapter spine=\(spineIndex) priority=\(queuePriority) cachedRanges=\(availablePageRanges?.count ?? 0)"
                 ) {
                     try self.buildChapter(
                         spineIndex: spineIndex,
                         availablePageRanges: availablePageRanges,
-                        diskSummary: diskSummary
+                        diskSummary: diskSummary,
+                        context: context
                     )
                 }
                 RDEPUBBackgroundTrace.log("ChapterLoader", "buildChapter OK: spine=\(spineIndex) pages=\(chapter.pages.count)")
@@ -96,42 +147,38 @@ final class RDEPUBChapterLoader {
                     store: store
                 )
 
-                switch priority {
+                let effectivePriority = self.pendingPriority(for: spineIndex) ?? queuePriority
+                store.endPendingChapterLoad(for: spineIndex)
+                switch effectivePriority {
                 case .navigation:
 
                     let nextTarget = store.consumeNavigationTarget()
                     if let target = nextTarget, target != spineIndex {
 
                         store.markBuilding(false)
-                        self.loadChapter(spineIndex: target, store: store, priority: .navigation, completion: completion)
+                        self.resolvePendingLoad(spineIndex: spineIndex, result: .success(chapter))
+                        self.loadChapter(spineIndex: target, store: store, priority: .navigation, completion: { _ in })
                         return
                     }
                     store.markBuilding(false)
-                    DispatchQueue.main.async {
-                        completion(.success(chapter))
-                    }
+                    self.resolvePendingLoad(spineIndex: spineIndex, result: .success(chapter))
 
                 case .preview:
                     store.markBuilding(false)
-                    DispatchQueue.main.async {
-                        completion(.success(chapter))
-                    }
+                    self.resolvePendingLoad(spineIndex: spineIndex, result: .success(chapter))
 
                 case .prefetch:
 
                     store.removePrefetchTarget(spineIndex)
                     store.markBuilding(false)
-                    DispatchQueue.main.async {
-                        completion(.success(chapter))
-                    }
+                    self.resolvePendingLoad(spineIndex: spineIndex, result: .success(chapter))
                 }
             } catch {
 
                 RDEPUBBackgroundTrace.log("ChapterLoader", "buildChapter FAILED: spine=\(spineIndex) error=\(error)")
+                store.endPendingChapterLoad(for: spineIndex)
                 store.markBuilding(false)
-                DispatchQueue.main.async {
-                    completion(.failure(error))
-                }
+                self.resolvePendingLoad(spineIndex: spineIndex, result: .failure(error))
             }
         }
     }
@@ -140,11 +187,15 @@ final class RDEPUBChapterLoader {
         spineIndex: Int,
         store: RDEPUBChapterRuntimeStore?
     ) throws -> RDEPUBRuntimeChapter {
+        guard let context else {
+            throw RDEPUBChapterLoadError.missingParser
+        }
+
         if let cached = store?.chapterData(for: spineIndex) {
             if let store {
                 scheduleDeferredCFIMapBuildIfNeeded(
                     for: cached,
-                    cacheKey: makeCacheKey(spineIndex: spineIndex),
+                    cacheKey: makeCacheKey(spineIndex: spineIndex, context: context),
                     store: store
                 )
             }
@@ -155,6 +206,26 @@ final class RDEPUBChapterLoader {
             throw RDEPUBChapterLoadError.missingParser
         }
 
+        if store.hasPendingChapterLoad(for: spineIndex) {
+            var result: Result<RDEPUBRuntimeChapter, Error>?
+            let semaphore = DispatchSemaphore(value: 0)
+            let registration = registerPendingLoad(
+                spineIndex: spineIndex,
+                priority: .navigation
+            ) { pendingResult in
+                result = pendingResult
+                semaphore.signal()
+            }
+            if case .joined(let existingPriority, let effectivePriority) = registration {
+                RDEPUBBackgroundTrace.log(
+                    "ChapterLoader",
+                    "sync join spine=\(spineIndex) existingPriority=\(existingPriority) effectivePriority=\(effectivePriority)"
+                )
+                semaphore.wait()
+                return try result!.get()
+            }
+        }
+
         store.assertNotOnChapterLoadQueue()
 
         var result: Result<RDEPUBRuntimeChapter, Error>?
@@ -167,7 +238,7 @@ final class RDEPUBChapterLoader {
                     "sync buildChapter spine=\(spineIndex)"
                 ) {
                     try autoreleasepool { () -> Result<RDEPUBRuntimeChapter, Error> in
-                        let cacheKey = self.makeCacheKey(spineIndex: spineIndex)
+                        let cacheKey = self.makeCacheKey(spineIndex: spineIndex, context: context)
                         let precomputedPageRanges = store.pageCount(for: cacheKey)?.pageRanges
                         let diskSummary: RDEPUBChapterSummary?
                         if precomputedPageRanges == nil {
@@ -178,7 +249,8 @@ final class RDEPUBChapterLoader {
                         let chapter = try self.buildChapter(
                             spineIndex: spineIndex,
                             availablePageRanges: precomputedPageRanges ?? diskSummary?.pageRanges.map(\.nsRange),
-                            diskSummary: diskSummary
+                            diskSummary: diskSummary,
+                            context: context
                         )
                         store.insertChapter(chapter)
                         let pageCount = RDEPUBRuntimePageCount(
@@ -206,10 +278,48 @@ final class RDEPUBChapterLoader {
         return try result!.get()
     }
 
+    private func registerPendingLoad(
+        spineIndex: Int,
+        priority: LoadPriority,
+        completion: @escaping LoadCompletion
+    ) -> LoadRegistrationResult {
+        pendingLoadsLock.lock()
+        defer { pendingLoadsLock.unlock() }
+
+        if var pending = pendingLoads[spineIndex] {
+            let existingPriority = pending.priority
+            pending.priority = LoadPriority.higherPriority(existingPriority, priority)
+            pending.completions.append(completion)
+            pendingLoads[spineIndex] = pending
+            return .joined(existingPriority: existingPriority, effectivePriority: pending.priority)
+        }
+
+        pendingLoads[spineIndex] = PendingLoad(priority: priority, completions: [completion])
+        return .created
+    }
+
+    private func pendingPriority(for spineIndex: Int) -> LoadPriority? {
+        pendingLoadsLock.lock()
+        let priority = pendingLoads[spineIndex]?.priority
+        pendingLoadsLock.unlock()
+        return priority
+    }
+
+    private func resolvePendingLoad(spineIndex: Int, result: Result<RDEPUBRuntimeChapter, Error>) {
+        pendingLoadsLock.lock()
+        let completions = pendingLoads.removeValue(forKey: spineIndex)?.completions ?? []
+        pendingLoadsLock.unlock()
+
+        guard !completions.isEmpty else { return }
+
+        completions.forEach { $0(result) }
+    }
+
     private func buildChapter(
         spineIndex: Int,
         availablePageRanges: [NSRange]?,
-        diskSummary: RDEPUBChapterSummary? = nil
+        diskSummary: RDEPUBChapterSummary? = nil,
+        context: RDEPUBReaderContext
     ) throws -> RDEPUBRuntimeChapter {
         guard let parser = context.parser,
               let publication = context.publication else {
@@ -231,7 +341,8 @@ final class RDEPUBChapterLoader {
                 pageSize: pageSize,
                 style: style,
                 layoutConfig: layoutConfig,
-                diskSummary: diskSummary
+                diskSummary: diskSummary,
+                context: context
             )
         }
 
@@ -251,7 +362,8 @@ final class RDEPUBChapterLoader {
             from: result.chapter,
             spineIndex: spineIndex,
             pageSize: pageSize,
-            layoutConfig: layoutConfig
+            layoutConfig: layoutConfig,
+            context: context
         )
     }
 
@@ -263,7 +375,8 @@ final class RDEPUBChapterLoader {
         pageSize: CGSize,
         style: RDEPUBTextRenderStyle,
         layoutConfig: RDEPUBTextLayoutConfig,
-        diskSummary: RDEPUBChapterSummary? = nil
+        diskSummary: RDEPUBChapterSummary? = nil,
+        context: RDEPUBReaderContext
     ) throws -> RDEPUBRuntimeChapter {
         let spineItem = publication.spine[spineIndex]
         let href = spineItem.href
@@ -465,7 +578,8 @@ final class RDEPUBChapterLoader {
         from chapter: RDEPUBTextChapter,
         spineIndex: Int,
         pageSize: CGSize,
-        layoutConfig: RDEPUBTextLayoutConfig
+        layoutConfig: RDEPUBTextLayoutConfig,
+        context: RDEPUBReaderContext
     ) throws -> RDEPUBRuntimeChapter {
         let layouter = RDEPUBTextLayouter(
             attributedString: chapter.attributedContent,
@@ -482,7 +596,7 @@ final class RDEPUBChapterLoader {
         )
 
         let pageRanges = chapter.pages.map { $0.contentRange }
-        let cacheKey = makeCacheKey(spineIndex: spineIndex)
+        let cacheKey = makeCacheKey(spineIndex: spineIndex, context: context)
         summaryDiskCache?.write(summary: makeSummary(for: chapter.pages, fragmentOffsets: chapter.fragmentOffsets, offsetMap: offsetMap, cacheKey: cacheKey), for: cacheKey)
 
         return RDEPUBRuntimeChapter(
@@ -498,7 +612,7 @@ final class RDEPUBChapterLoader {
         )
     }
 
-    private func makeCacheKey(spineIndex: Int) -> RDEPUBChapterCacheKey {
+    private func makeCacheKey(spineIndex: Int, context: RDEPUBReaderContext) -> RDEPUBChapterCacheKey {
         let style = context.currentTextRenderStyle()
         let layoutConfig = context.currentTextLayoutConfig(pageSize: context.currentTextPageSize())
 
@@ -513,7 +627,7 @@ final class RDEPUBChapterLoader {
             "\(RDEPUBChapterSummary.currentSchemaVersion)"
         ].joined(separator: "|")
 
-        let contentHash = contentHashForSpineIndex(spineIndex)
+        let contentHash = contentHashForSpineIndex(spineIndex, context: context)
 
         return RDEPUBChapterCacheKey(
             bookID: context.currentBookIdentifier ?? "",
@@ -540,7 +654,7 @@ final class RDEPUBChapterLoader {
 
         store.chapterLoadQueue.async {
             defer { store.endBuildingCFIMap(for: spineIndex) }
-            guard let rawHTML = self.context.parser?.htmlString(forRelativePath: href),
+            guard let rawHTML = self.context?.parser?.htmlString(forRelativePath: href),
                   let chapterText else {
                 return
             }
@@ -586,12 +700,12 @@ final class RDEPUBChapterLoader {
         )
     }
 
-    private func contentHashForSpineIndex(_ spineIndex: Int) -> String {
+    private func contentHashForSpineIndex(_ spineIndex: Int, context: RDEPUBReaderContext) -> String {
         guard let parser = context.parser,
               let publication = context.publication else { return "" }
         let href = publication.spine[spineIndex].href
         guard let html = parser.htmlString(forRelativePath: href) else { return "" }
-        return html.sha256Hex
+        return html.rd_sha256Hex
     }
 
     private func requireHTMLString(_ parser: RDEPUBParser, href: String) throws -> String {
@@ -638,13 +752,34 @@ final class RDEPUBChapterLoader {
             markers: markers,
             recoveryMetadata: RDEPUBCFIRecoveryMetadata(
                 domFingerprint: "",
-                normalizedTextChecksum: RDEPUBCFITextNodeMapBuilder.normalizedText(from: chapterText).sha256Hex,
+                normalizedTextChecksum: RDEPUBCFITextNodeMapBuilder.normalizedText(from: chapterText).rd_sha256Hex,
                 fragmentPathMap: domPaths
             )
         )
     }
 }
 
+private extension RDEPUBChapterLoader.LoadPriority {
+
+    static func higherPriority(_ lhs: Self, _ rhs: Self) -> Self {
+        if lhs.rank >= rhs.rank {
+            return lhs
+        }
+        return rhs
+    }
+
+    var rank: Int {
+        switch self {
+        case .prefetch:
+            return 0
+        case .preview:
+            return 1
+        case .navigation:
+            return 2
+        }
+    }
+}
+
 enum RDEPUBChapterLoadError: LocalizedError {
 
     case missingParser

Sources/RDReaderView/EPUBUI/ReaderController/ChapterRuntime/RDEPUBChapterRuntimeStore.swift

@@ -32,6 +32,10 @@ final class RDEPUBChapterRuntimeStore {
 
     private let cfiMapLock = NSLock()
 
+    private var pendingChapterLoadSpineIndices: Set<Int> = []
+
+    private let pendingChapterLoadLock = NSLock()
+
     init() {
 
         imageCache.countLimit = 50
@@ -146,6 +150,25 @@ final class RDEPUBChapterRuntimeStore {
         buildingLock.unlock()
     }
 
+    func beginPendingChapterLoad(for spineIndex: Int) -> Bool {
+        pendingChapterLoadLock.lock()
+        defer { pendingChapterLoadLock.unlock() }
+        return pendingChapterLoadSpineIndices.insert(spineIndex).inserted
+    }
+
+    func endPendingChapterLoad(for spineIndex: Int) {
+        pendingChapterLoadLock.lock()
+        pendingChapterLoadSpineIndices.remove(spineIndex)
+        pendingChapterLoadLock.unlock()
+    }
+
+    func hasPendingChapterLoad(for spineIndex: Int) -> Bool {
+        pendingChapterLoadLock.lock()
+        let hasPendingLoad = pendingChapterLoadSpineIndices.contains(spineIndex)
+        pendingChapterLoadLock.unlock()
+        return hasPendingLoad
+    }
+
     func beginBuildingCFIMap(for spineIndex: Int) -> Bool {
         cfiMapLock.lock()
         defer { cfiMapLock.unlock() }
@@ -166,5 +189,8 @@ final class RDEPUBChapterRuntimeStore {
         cfiMapLock.lock()
         buildingCFIMapSpineIndices.removeAll()
         cfiMapLock.unlock()
+        pendingChapterLoadLock.lock()
+        pendingChapterLoadSpineIndices.removeAll()
+        pendingChapterLoadLock.unlock()
     }
 }

Sources/RDReaderView/EPUBUI/ReaderController/ChapterRuntime/RDEPUBChapterSummaryDiskCache.swift

@@ -119,7 +119,7 @@ final class RDEPUBChapterSummaryDiskCache {
         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
+        let digest = rawKey.rd_sha256Hex
         return cacheDirectory.appendingPathComponent("\(bookPrefix)__\(renderPrefix)__\(digest).json")
     }
 
@@ -150,7 +150,7 @@ final class RDEPUBChapterSummaryDiskCache {
     }
 
     private static func cacheNamespacePrefix(for rawValue: String) -> String {
-        rawValue.sha256Hex.prefix(12).lowercased()
+        rawValue.rd_sha256Hex.prefix(12).lowercased()
     }
 }
 

Sources/RDReaderView/EPUBUI/ReaderController/ChapterRuntime/RDEPUBChapterWarmupOrchestrator.swift

@@ -24,6 +24,14 @@ final class RDEPUBChapterWarmupOrchestrator {
 
     private var isExtendingPartialBookPageMap = false
 
+    private let prepareRequestStateLock = NSLock()
+
+    private var pendingPreparePageNumbers: Set<Int> = []
+
+    private var recentPrepareTimestamps: [Int: CFAbsoluteTime] = [:]
+
+    private let prepareRequestDebounceInterval: CFTimeInterval = 0.15
+
     init(
         context: RDEPUBReaderContext,
         store: RDEPUBChapterRuntimeStore,
@@ -58,6 +66,16 @@ final class RDEPUBChapterWarmupOrchestrator {
         guard let spineIndex = bookPageMap.spineIndex(forAbsolutePage: absolutePageIndex) else {
             return false
         }
+        let chapterReady = store.chapterData(for: spineIndex) != nil
+
+        if let debouncedResult = debouncedPrepareResult(
+            pageNumber: pageNumber,
+            spineIndex: spineIndex,
+            chapterReady: chapterReady,
+            allowSynchronousLoad: allowSynchronousLoad
+        ) {
+            return debouncedResult
+        }
 
         store.setCurrentChapter(
             spineIndex: spineIndex,
@@ -70,7 +88,7 @@ final class RDEPUBChapterWarmupOrchestrator {
             "prepareOnDemandChapter page=\(pageNumber) absoluteIndex=\(absolutePageIndex) spine=\(spineIndex)"
         )
 
-        if store.chapterData(for: spineIndex) == nil {
+        if !chapterReady {
             guard allowSynchronousLoad else {
                 scheduleAsynchronousChapterPreparation(
                     spineIndex: spineIndex,
@@ -85,11 +103,13 @@ final class RDEPUBChapterWarmupOrchestrator {
                     store: store
                 )
             } catch {
+                clearPendingPreparePageNumber(pageNumber)
                 RDEPUBBackgroundTrace.log("Runtime", "prepareOnDemandChapter FAILED: spine=\(spineIndex) error=\(error)")
                 return false
             }
         }
 
+        markPrepareResolved(pageNumber)
         presentationRuntime.navigationStateMachine.transition(to: .presentingWindow)
         completion?(true)
         maybePrefetchUpcomingChapters(aroundAbsolutePageNumber: pageNumber, in: bookPageMap)
@@ -189,6 +209,7 @@ final class RDEPUBChapterWarmupOrchestrator {
                 appendLoadedForwardChaptersToCurrentPageMapIfPossible()
                 continue
             }
+            guard shouldSchedulePrefetch(for: spineIndex) else { continue }
 
             store.addPrefetchTarget(spineIndex)
             RDEPUBBackgroundTrace.log("Runtime", "initial open prefetch forward spine=\(spineIndex)")
@@ -226,9 +247,10 @@ final class RDEPUBChapterWarmupOrchestrator {
             return true
         }
 
-        if let pendingMap = context.pendingFullPageMap,
-           pendingMap.entry(forSpineIndex: targetSpineIndex) != nil {
-            presentationRuntime.applyPendingFullPageMapIfNeeded()
+        if context.pendingPageMapUpdates.contains(where: { update in
+            update.pageMap.entry(forSpineIndex: targetSpineIndex) != nil
+        }) {
+            presentationRuntime.commitPendingPageMapUpdateIfNeeded()
             if context.bookPageMap?.entry(forSpineIndex: targetSpineIndex) != nil {
                 if isDistantJump {
                     jumpSessionManager.createSession(
@@ -284,6 +306,10 @@ final class RDEPUBChapterWarmupOrchestrator {
         asynchronouslyPreparingSpineIndices.removeAll()
         isExtendingPartialBookPageMap = false
         asyncLoadStateLock.unlock()
+        prepareRequestStateLock.lock()
+        pendingPreparePageNumbers.removeAll()
+        recentPrepareTimestamps.removeAll()
+        prepareRequestStateLock.unlock()
     }
 
     private func applyAsyncPartialBookPageMapExtension(
@@ -337,7 +363,7 @@ final class RDEPUBChapterWarmupOrchestrator {
             "Runtime",
             "extendPartialBookPageMap applied chapters=\(newMap.totalChapters) pages=\(newMap.totalPages)"
         )
-        presentationRuntime.applyExtendedPartialPageMap(
+        presentationRuntime.queueExtendedPartialPageMap(
             newMap,
             currentPageNumber: currentPageNumber,
             currentLocation: currentLocation
@@ -349,7 +375,13 @@ final class RDEPUBChapterWarmupOrchestrator {
         triggerPageNumber: Int,
         completion: ((Bool) -> Void)?
     ) {
-        guard beginAsynchronousChapterPreparation(for: spineIndex) else { return }
+        guard beginAsynchronousChapterPreparation(for: spineIndex) else {
+            RDEPUBBackgroundTrace.log(
+                "Runtime",
+                "prepareOnDemandChapter async deduped spine=\(spineIndex) page=\(triggerPageNumber)"
+            )
+            return
+        }
         RDEPUBBackgroundTrace.log(
             "Runtime",
             "prepareOnDemandChapter async spine=\(spineIndex) page=\(triggerPageNumber)"
@@ -363,11 +395,13 @@ final class RDEPUBChapterWarmupOrchestrator {
             self.endAsynchronousChapterPreparation(for: spineIndex)
             switch result {
             case .success:
+                self.markPrepareResolved(triggerPageNumber)
                 self.presentationRuntime.navigationStateMachine.transition(to: .presentingWindow)
                 completion?(true)
                 self.appendLoadedForwardChaptersToCurrentPageMapIfPossible()
                 self.refreshVisibleContentIfNeeded(afterPreparing: spineIndex, triggerPageNumber: triggerPageNumber)
             case .failure(let error):
+                self.clearPendingPreparePageNumber(triggerPageNumber)
                 RDEPUBBackgroundTrace.log(
                     "Runtime",
                     "prepareOnDemandChapter async FAILED: spine=\(spineIndex) error=\(error)"
@@ -389,7 +423,7 @@ final class RDEPUBChapterWarmupOrchestrator {
         }
 
         for adjacentSpineIndex in store.windowSpineIndices where adjacentSpineIndex != spineIndex {
-            guard store.chapterData(for: adjacentSpineIndex) == nil else { continue }
+            guard shouldSchedulePrefetch(for: adjacentSpineIndex) else { continue }
             store.addPrefetchTarget(adjacentSpineIndex)
             RDEPUBBackgroundTrace.log(
                 "Runtime",
@@ -428,7 +462,7 @@ final class RDEPUBChapterWarmupOrchestrator {
 
         let targets = buildableIndices.dropFirst(currentPosition + 1).prefix(lookaheadChapterCount)
         for targetSpineIndex in targets {
-            guard store.chapterData(for: targetSpineIndex) == nil else { continue }
+            guard shouldSchedulePrefetch(for: targetSpineIndex) else { continue }
             store.addPrefetchTarget(targetSpineIndex)
             RDEPUBBackgroundTrace.log(
                 "Runtime",
@@ -441,7 +475,9 @@ final class RDEPUBChapterWarmupOrchestrator {
         }
     }
 
-    private func appendLoadedForwardChaptersToCurrentPageMapIfPossible() {
+    private func appendLoadedForwardChaptersToCurrentPageMapIfPossible(
+        minimumTrailingPages: Int = 2
+    ) {
         guard let publication = context.publication,
               let currentMap = context.bookPageMap,
               let readerView = context.readerView,
@@ -449,8 +485,13 @@ final class RDEPUBChapterWarmupOrchestrator {
             return
         }
 
+        let currentPageNumber = max(readerView.currentPage + 1, 1)
+        let trailingPages = currentMap.totalPages - currentPageNumber
+        guard trailingPages <= minimumTrailingPages else { return }
+
         let buildableIndices = buildableSpineIndices(in: publication)
         var appendedEntries: [RDEPUBBookPageMapEntry] = []
+        var projectedTotalPages = currentMap.totalPages
         for spineIndex in buildableIndices where spineIndex > lastKnownSpineIndex {
             guard let chapter = store.chapterData(for: spineIndex) else { break }
             appendedEntries.append(
@@ -463,6 +504,10 @@ final class RDEPUBChapterWarmupOrchestrator {
                     fragmentOffsets: chapter.chapterOffsetMap.fragmentOffsets
                 )
             )
+            projectedTotalPages += chapter.pages.count
+            if projectedTotalPages - currentPageNumber > minimumTrailingPages {
+                break
+            }
         }
 
         guard !appendedEntries.isEmpty else { return }
@@ -497,12 +542,68 @@ final class RDEPUBChapterWarmupOrchestrator {
 
         RDEPUBBackgroundTrace.log(
             "Runtime",
-            "appendLoadedForwardChapters chapters=\(newMap.totalChapters) pages=\(newMap.totalPages)"
+            "appendLoadedForwardChapters currentPage=\(currentPageNumber) trailingBefore=\(trailingPages) trailingAfter=\(newMap.totalPages - currentPageNumber) chapters=\(newMap.totalChapters) pages=\(newMap.totalPages)"
         )
 
-        context.bookPageMap = newMap
-        context.replaceActiveSnapshot(presentationRuntime.makeSnapshot(from: newMap))
-        readerView.reloadPageCountOnly()
+        presentationRuntime.queueForwardAppendedPageMap(newMap)
+    }
+
+    private func shouldSchedulePrefetch(for spineIndex: Int) -> Bool {
+        guard store.chapterData(for: spineIndex) == nil else { return false }
+        guard !store.hasPrefetchTarget(spineIndex) else { return false }
+        guard !store.hasPendingChapterLoad(for: spineIndex) else { return false }
+        return true
+    }
+
+    private func debouncedPrepareResult(
+        pageNumber: Int,
+        spineIndex: Int,
+        chapterReady: Bool,
+        allowSynchronousLoad: Bool
+    ) -> Bool? {
+        prepareRequestStateLock.lock()
+        defer { prepareRequestStateLock.unlock() }
+
+        let now = CFAbsoluteTimeGetCurrent()
+        recentPrepareTimestamps = recentPrepareTimestamps.filter { now - $0.value <= prepareRequestDebounceInterval }
+
+        if !allowSynchronousLoad && !chapterReady {
+            let inserted = pendingPreparePageNumbers.insert(pageNumber).inserted
+            if !inserted {
+                RDEPUBBackgroundTrace.log(
+                    "Runtime",
+                    "prepareOnDemandChapter page deduped page=\(pageNumber) spine=\(spineIndex) chapterReady=false"
+                )
+                return false
+            }
+            return nil
+        }
+
+        pendingPreparePageNumbers.remove(pageNumber)
+        if let lastTimestamp = recentPrepareTimestamps[pageNumber],
+           now - lastTimestamp <= prepareRequestDebounceInterval {
+            RDEPUBBackgroundTrace.log(
+                "Runtime",
+                "prepareOnDemandChapter page debounced page=\(pageNumber) spine=\(spineIndex) chapterReady=\(chapterReady)"
+            )
+            return chapterReady
+        }
+
+        recentPrepareTimestamps[pageNumber] = now
+        return nil
+    }
+
+    private func markPrepareResolved(_ pageNumber: Int) {
+        prepareRequestStateLock.lock()
+        pendingPreparePageNumbers.remove(pageNumber)
+        recentPrepareTimestamps[pageNumber] = CFAbsoluteTimeGetCurrent()
+        prepareRequestStateLock.unlock()
+    }
+
+    private func clearPendingPreparePageNumber(_ pageNumber: Int) {
+        prepareRequestStateLock.lock()
+        pendingPreparePageNumbers.remove(pageNumber)
+        prepareRequestStateLock.unlock()
     }
 
     private func refreshVisibleContentIfNeeded(afterPreparing spineIndex: Int, triggerPageNumber: Int) {
@@ -510,16 +611,41 @@ final class RDEPUBChapterWarmupOrchestrator {
               let bookPageMap = context.bookPageMap else {
             return
         }
+        if readerView.isPageCurlTransitioning {
+            RDEPUBBackgroundTrace.log(
+                "LoadingPage",
+                "defer refreshVisibleContent spine=\(spineIndex) triggerPage=\(triggerPageNumber) reason=pageCurlTransition"
+            )
+            DispatchQueue.main.asyncAfter(deadline: .now() + 0.1) { [weak self] in
+                self?.refreshVisibleContentIfNeeded(
+                    afterPreparing: spineIndex,
+                    triggerPageNumber: triggerPageNumber
+                )
+            }
+            return
+        }
         let visiblePageNumber = readerView.currentPage + 1
         if visiblePageNumber == triggerPageNumber {
+            RDEPUBBackgroundTrace.log(
+                "LoadingPage",
+                "refreshVisibleContent matchedTrigger spine=\(spineIndex) triggerPage=\(triggerPageNumber) visiblePage=\(visiblePageNumber)"
+            )
             refreshVisibleContentPreservingLocation()
             return
         }
         guard visiblePageNumber > 0,
               let visibleSpineIndex = bookPageMap.spineIndex(forAbsolutePage: visiblePageNumber - 1),
               visibleSpineIndex == spineIndex else {
+            RDEPUBBackgroundTrace.log(
+                "LoadingPage",
+                "skip refreshVisibleContent spine=\(spineIndex) triggerPage=\(triggerPageNumber) visiblePage=\(visiblePageNumber)"
+            )
             return
         }
+        RDEPUBBackgroundTrace.log(
+            "LoadingPage",
+            "refreshVisibleContent matchedVisibleSpine spine=\(spineIndex) triggerPage=\(triggerPageNumber) visiblePage=\(visiblePageNumber)"
+        )
         refreshVisibleContentPreservingLocation()
     }
 

Sources/RDReaderView/EPUBUI/ReaderController/ChapterRuntime/String+SHA256.swift

@@ -1,11 +0,0 @@
-import CryptoKit
-
-extension String {
-
-    var sha256Hex: String {
-
-        let digest = SHA256.hash(data: Data(self.utf8))
-
-        return digest.map { String(format: "%02x", $0) }.joined()
-    }
-}

Sources/RDReaderView/EPUBUI/ReaderController/RDEPUBMetadataParseCancellationController.swift

@@ -0,0 +1,44 @@
+import Foundation
+
+final class RDEPUBMetadataParseCancellationController {
+
+    let token: UUID
+
+    private let lock = NSLock()
+
+    private weak var queue: OperationQueue?
+
+    private var cancelled = false
+
+    init(token: UUID) {
+        self.token = token
+    }
+
+    func attach(queue: OperationQueue) {
+        let shouldCancelImmediately: Bool
+        lock.lock()
+        self.queue = queue
+        shouldCancelImmediately = cancelled
+        lock.unlock()
+
+        if shouldCancelImmediately {
+            queue.cancelAllOperations()
+        }
+    }
+
+    func cancel() {
+        let queueToCancel: OperationQueue?
+        lock.lock()
+        cancelled = true
+        queueToCancel = queue
+        lock.unlock()
+        queueToCancel?.cancelAllOperations()
+    }
+
+    var isCancelled: Bool {
+        lock.lock()
+        let value = cancelled
+        lock.unlock()
+        return value
+    }
+}

Sources/RDReaderView/EPUBUI/ReaderController/RDEPUBMetadataParseWorker.swift

@@ -0,0 +1,572 @@
+import Foundation
+
+final class RDEPUBMetadataParseWorker {
+
+    private static let maxRetryCount = 3
+    private static let retryDelays: [TimeInterval] = [0.5, 2.0, 8.0]
+
+    private final class ParseState {
+
+        var summariesBySpineIndex: [Int: RDEPUBChapterSummary]
+
+        var totalResolvedCount: Int
+
+        var lastAppliedCount: Int
+
+        init(
+            summariesBySpineIndex: [Int: RDEPUBChapterSummary],
+            totalResolvedCount: Int,
+            lastAppliedCount: Int
+        ) {
+            self.summariesBySpineIndex = summariesBySpineIndex
+            self.totalResolvedCount = totalResolvedCount
+            self.lastAppliedCount = lastAppliedCount
+        }
+    }
+
+    private let backgroundInteractionCooldown: CFAbsoluteTime = 0.8
+
+    unowned let context: RDEPUBReaderContext
+
+    let cancellationController: RDEPUBMetadataParseCancellationController
+
+    let pageMapRefreshInterval: Int
+
+    private let token: UUID
+
+    private let parser: RDEPUBParser
+
+    private let publication: RDEPUBPublication
+
+    private let pageSize: CGSize
+
+    private let layoutConfig: RDEPUBTextLayoutConfig
+
+    private let style: RDEPUBTextRenderStyle
+
+    private let renderSignature: String
+
+    private let allBuildableIndices: [Int]
+
+    private let summaryDiskCache: RDEPUBChapterSummaryDiskCache?
+
+    private let workerCount: Int
+
+    private let contentHashBySpineIndex: [Int: String]
+
+    private let catalog: [(key: RDEPUBChapterCacheKey, spineIndex: Int, href: String, title: String)]
+
+    init(
+        context: RDEPUBReaderContext,
+        cancellationController: RDEPUBMetadataParseCancellationController,
+        token: UUID,
+        parser: RDEPUBParser,
+        publication: RDEPUBPublication
+    ) {
+        self.context = context
+        self.cancellationController = cancellationController
+        self.token = token
+        self.parser = parser
+        self.publication = publication
+
+        let pageSize = context.currentTextPageSize()
+        self.pageSize = pageSize
+        self.layoutConfig = context.currentTextLayoutConfig(pageSize: pageSize)
+        self.style = context.currentTextRenderStyle()
+        self.renderSignature = context.currentRenderSignature()
+        self.allBuildableIndices = publication.spine.indices.filter { index in
+            guard publication.spine.indices.contains(index) else { return false }
+            let item = publication.spine[index]
+            return item.linear && (item.mediaType.contains("html") || item.mediaType.contains("xhtml"))
+        }
+        self.summaryDiskCache = context.runtime?.summaryDiskCache
+        self.workerCount = max(1, context.configuration.metadataParsingConcurrency)
+        self.pageMapRefreshInterval = RDEPUBReaderPaginationCoordinator.pageMapRefreshInterval
+
+        var hashes: [Int: String] = [:]
+        for spineIndex in allBuildableIndices {
+            guard let href = publication.spine.indices.contains(spineIndex)
+                ? publication.spine[spineIndex].href : nil,
+                let html = parser.htmlString(forRelativePath: href) else {
+                hashes[spineIndex] = ""
+                continue
+            }
+            hashes[spineIndex] = html.rd_sha256Hex
+        }
+        self.contentHashBySpineIndex = hashes
+
+        let ctx = context
+        let spine = publication.spine
+        let sig = renderSignature
+        self.catalog = allBuildableIndices.map { spineIndex in
+            let item = spine[spineIndex]
+            return (
+                key: ctx.chapterCacheKey(
+                    forSpineIndex: spineIndex,
+                    precomputedContentHash: hashes[spineIndex] ?? "",
+                    renderSignature: sig
+                ),
+                spineIndex: spineIndex,
+                href: item.href,
+                title: item.title
+            )
+        }
+    }
+
+    func start(token: UUID, restoreLocation: RDEPUBLocation?) {
+        let context = self.context
+        let cancellationController = self.cancellationController
+
+        DispatchQueue.global(qos: .utility).async { [weak self] in
+            guard let self else { return }
+            defer { self.context.runtime?.paginationCoordinator.finishMetadataParseCancellationController(cancellationController) }
+            guard context.controller != nil,
+                  !cancellationController.isCancelled,
+                  context.paginationToken == token else { return }
+
+            if let restoredPageMap = self.restoreBookPageMapIfPossible() {
+                RDEPUBBackgroundTrace.log(
+                    "MetadataParse",
+                    "full cache restore hit chapters=\(restoredPageMap.totalChapters) pages=\(restoredPageMap.totalPages)"
+                )
+                DispatchQueue.main.async {
+                    guard context.paginationToken == token,
+                          context.controller != nil,
+                          !cancellationController.isCancelled else { return }
+                    context.runtime?.refreshBookPageMapInPlace(restoredPageMap)
+                }
+                return
+            }
+
+            let prewarmStart = CFAbsoluteTimeGetCurrent()
+            let prewarmMs = Int((CFAbsoluteTimeGetCurrent() - prewarmStart) * 1000)
+            RDEPUBBackgroundTrace.log("MetadataParse", "prewarmHashMs=\(prewarmMs) chapters=\(self.allBuildableIndices.count)")
+
+            let restored = self.summaryDiskCache?.readAll(keys: self.catalog)
+            RDEPUBBackgroundTrace.log(
+                "MetadataParse",
+                "begin token=\(token.uuidString) buildableChapters=\(self.allBuildableIndices.count) concurrency=\(self.workerCount)"
+            )
+            let cachedSummaries = restored?.summaries ?? [:]
+            let cachedSpineIndices = Set(cachedSummaries.keys)
+            let resultLock = NSLock()
+            let parseState = ParseState(
+                summariesBySpineIndex: cachedSummaries,
+                totalResolvedCount: cachedSpineIndices.count,
+                lastAppliedCount: cachedSpineIndices.count
+            )
+
+            if !cachedSpineIndices.isEmpty {
+                RDEPUBBackgroundTrace.log(
+                    "MetadataParse",
+                    "resumeFromCache cachedChapters=\(cachedSpineIndices.count) total=\(self.allBuildableIndices.count)"
+                )
+                let cachedMap = self.buildPageMap(summaries: parseState.summariesBySpineIndex)
+                DispatchQueue.main.async {
+                    guard context.paginationToken == token,
+                          context.controller != nil else { return }
+                    context.runtime?.refreshBookPageMapInPlace(cachedMap)
+                }
+            }
+
+            let prioritizedSpineIndices: [Int]
+            if let priorityManager = context.runtime?.backgroundPriorityManager {
+                let currentSpineIndex = context.runtime?.locationCoordinator.currentVisibleLocation()
+                    .flatMap { context.normalizedSpineIndex(for: $0) }
+                prioritizedSpineIndices = priorityManager.makeMetadataPriorityOrder(
+                    allBuildableIndices: self.allBuildableIndices,
+                    currentSpineIndex: currentSpineIndex,
+                    cachedSpineIndices: cachedSpineIndices
+                )
+                RDEPUBBackgroundTrace.log(
+                    "MetadataParse",
+                    "prioritized hot=\(prioritizedSpineIndices.prefix(10).count) total=\(prioritizedSpineIndices.count)"
+                )
+            } else {
+                prioritizedSpineIndices = self.allBuildableIndices.filter { !cachedSpineIndices.contains($0) }
+            }
+
+            let uncachedSpineIndices = prioritizedSpineIndices
+
+            self.waitForReadingInteractionToSettle(cancellationController: cancellationController)
+            guard !cancellationController.isCancelled,
+                  context.controller != nil,
+                  context.paginationToken == token else {
+                RDEPUBBackgroundTrace.log("MetadataParse", "abort before queue start")
+                return
+            }
+
+            let wallClockStart = CFAbsoluteTimeGetCurrent()
+            var totalRenderMs: Double = 0
+            var totalWriteMs: Double = 0
+            var totalMergeMs: Double = 0
+            var completedChapters = 0
+            var failedChapters = 0
+            let timingLock = NSLock()
+
+            let queue = OperationQueue()
+            queue.name = "com.rdreader.metadata.parse"
+            queue.qualityOfService = .utility
+            queue.maxConcurrentOperationCount = self.workerCount
+            cancellationController.attach(queue: queue)
+
+            let refreshInterval = self.pageMapRefreshInterval
+
+            for (offset, spineIndex) in uncachedSpineIndices.enumerated() {
+                let operation = BlockOperation()
+                operation.addExecutionBlock { [weak operation] in
+                    guard context.controller != nil,
+                          context.paginationToken == token,
+                          !cancellationController.isCancelled,
+                          operation?.isCancelled != true else {
+                        return
+                    }
+                    do {
+                        RDEPUBBackgroundTrace.log("MetadataParse", "正在解析 spine=\(spineIndex) \(offset + 1)/\(uncachedSpineIndices.count)")
+
+                        let renderResult: RDEPUBChapterSummary? = try autoreleasepool { () -> RDEPUBChapterSummary? in
+                            guard context.controller != nil,
+                                  context.paginationToken == token,
+                                  !cancellationController.isCancelled,
+                                  operation?.isCancelled != true else {
+                                return nil
+                            }
+                            let chapterBuilder = context.makeTextBookBuilder(layoutConfig: self.layoutConfig)
+                            let renderStart = CFAbsoluteTimeGetCurrent()
+                            guard let result = try chapterBuilder.buildChapter(
+                                parser: self.parser,
+                                publication: self.publication,
+                                spineIndex: spineIndex,
+                                pageSize: self.pageSize,
+                                style: self.style
+                            ) else {
+                                return nil
+                            }
+                            guard context.controller != nil,
+                                  context.paginationToken == token,
+                                  !cancellationController.isCancelled,
+                                  operation?.isCancelled != true else {
+                                RDEPUBBackgroundTrace.log("MetadataParse", "drop rendered chapter due to cancellation spine=\(spineIndex)")
+                                return nil
+                            }
+                            let renderElapsed = (CFAbsoluteTimeGetCurrent() - renderStart) * 1000
+
+                            let chapter = result.chapter
+                            let precomputedHash = self.contentHashBySpineIndex[spineIndex] ?? ""
+                            let cacheKey = context.chapterCacheKey(
+                                forSpineIndex: spineIndex,
+                                precomputedContentHash: precomputedHash,
+                                renderSignature: self.renderSignature
+                            )
+                            let summary = RDEPUBChapterSummary(
+                                pageRanges: chapter.pages.map { .init(location: $0.contentRange.location, length: $0.contentRange.length) },
+                                pageCount: chapter.pages.count,
+                                fragmentOffsets: chapter.fragmentOffsets,
+                                cfiMap: chapter.cfiMap,
+                                renderSignature: cacheKey.renderSignature,
+                                schemaVersion: RDEPUBChapterSummary.currentSchemaVersion,
+                                chapterContentHash: cacheKey.chapterContentHash,
+                                pageMetadataList: chapter.pages.map { .from($0.metadata) }
+                            )
+                            guard context.controller != nil,
+                                  context.paginationToken == token,
+                                  !cancellationController.isCancelled,
+                                  operation?.isCancelled != true else {
+                                RDEPUBBackgroundTrace.log("MetadataParse", "skip disk write due to cancellation spine=\(spineIndex)")
+                                return nil
+                            }
+                            let writeStart = CFAbsoluteTimeGetCurrent()
+                            self.summaryDiskCache?.write(summary: summary, for: cacheKey)
+                            let writeElapsed = (CFAbsoluteTimeGetCurrent() - writeStart) * 1000
+
+                            timingLock.lock()
+                            totalRenderMs += renderElapsed
+                            totalWriteMs += writeElapsed
+                            completedChapters += 1
+                            timingLock.unlock()
+
+                            RDEPUBBackgroundTrace.log(
+                                "MetadataParse",
+                                "spine=\(spineIndex) renderMs=\(Int(renderElapsed)) writeMs=\(Int(writeElapsed))"
+                            )
+                            return summary
+                        }
+
+                        guard let renderResult else { return }
+                        guard context.controller != nil,
+                              context.paginationToken == token,
+                              !cancellationController.isCancelled,
+                              operation?.isCancelled != true else {
+                            return
+                        }
+
+                        var snapshot: [Int: RDEPUBChapterSummary]?
+                        resultLock.lock()
+                        parseState.summariesBySpineIndex[spineIndex] = renderResult
+                        parseState.totalResolvedCount += 1
+                        if parseState.totalResolvedCount - parseState.lastAppliedCount >= refreshInterval
+                            || parseState.totalResolvedCount == self.allBuildableIndices.count {
+                            parseState.lastAppliedCount = parseState.totalResolvedCount
+                            snapshot = parseState.summariesBySpineIndex
+                        }
+                        resultLock.unlock()
+
+                        if let snapshot {
+                            let mergeStart = CFAbsoluteTimeGetCurrent()
+                            let partialMap = self.buildPageMap(summaries: snapshot)
+                            let mergeElapsed = (CFAbsoluteTimeGetCurrent() - mergeStart) * 1000
+                            timingLock.lock()
+                            totalMergeMs += mergeElapsed
+                            timingLock.unlock()
+                            DispatchQueue.main.async {
+                                guard context.paginationToken == token,
+                                      context.controller != nil,
+                                      !cancellationController.isCancelled else { return }
+                                context.runtime?.refreshBookPageMapInPlace(partialMap)
+                            }
+                        }
+                    } catch {
+                        guard !cancellationController.isCancelled,
+                              context.paginationToken == token,
+                              context.controller != nil,
+                              operation?.isCancelled != true else {
+                            return
+                        }
+                        timingLock.lock()
+                        failedChapters += 1
+                        timingLock.unlock()
+                        RDEPUBBackgroundTrace.log("MetadataParse", "buildChapter FAILED: spine=\(spineIndex) error=\(error)")
+
+                        self.scheduleRetry(
+                            spineIndex: spineIndex,
+                            retryCount: 0,
+                            resultLock: resultLock,
+                            parseState: parseState,
+                            cancellationController: cancellationController
+                        )
+                    }
+                }
+                queue.addOperation(operation)
+            }
+            queue.waitUntilAllOperationsAreFinished()
+            if !cancellationController.isCancelled,
+               context.paginationToken == token,
+               context.controller != nil {
+                self.summaryDiskCache?.flushPendingWrites()
+            }
+
+            let wallClockMs = Int((CFAbsoluteTimeGetCurrent() - wallClockStart) * 1000)
+            timingLock.lock()
+            let renderTotal = Int(totalRenderMs)
+            let writeTotal = Int(totalWriteMs)
+            let mergeTotal = Int(totalMergeMs)
+            let rendered = completedChapters
+            let failed = failedChapters
+            timingLock.unlock()
+            let avgRenderMs = rendered > 0 ? renderTotal / rendered : 0
+            RDEPUBBackgroundTrace.log(
+                "MetadataParse",
+                "timing wallClockMs=\(wallClockMs) chapters=\(rendered) failed=\(failed) " +
+                "prewarmHashMs=\(prewarmMs) renderTotalMs=\(renderTotal) writeTotalMs=\(writeTotal) " +
+                "mergeTotalMs=\(mergeTotal) avgRenderMs=\(avgRenderMs) concurrency=\(self.workerCount)"
+            )
+            context.lastMetadataParseWallClockMs = wallClockMs
+            context.lastMetadataParseConcurrency = self.workerCount
+
+            guard context.controller != nil,
+                  context.paginationToken == token,
+                  !cancellationController.isCancelled else {
+                RDEPUBBackgroundTrace.log("MetadataParse", "abort: reader dismissed or token changed")
+                return
+            }
+
+            let finalMergeStart = CFAbsoluteTimeGetCurrent()
+            let pageMap = self.buildPageMap(summaries: parseState.summariesBySpineIndex)
+            let finalMergeMs = Int((CFAbsoluteTimeGetCurrent() - finalMergeStart) * 1000)
+            RDEPUBBackgroundTrace.log(
+                "MetadataParse",
+                "complete chapters=\(pageMap.totalChapters) pages=\(pageMap.totalPages) finalMergeMs=\(finalMergeMs)"
+            )
+
+            if let coverageStore = context.runtime?.backgroundCoverageStore {
+                let resolvedSpineIndices = Set(parseState.summariesBySpineIndex.keys)
+                let lowerSpine = resolvedSpineIndices.min() ?? 0
+                let upperSpine = resolvedSpineIndices.max() ?? 0
+                let estimatedBytes = 256 + pageMap.entries.count * 96 + resolvedSpineIndices.count * 16
+
+                let segment = RDEPUBBackgroundCoverageSegment(
+                    lowerSpineIndex: lowerSpine,
+                    upperSpineIndex: upperSpine,
+                    pageMap: pageMap,
+                    resolvedSpineIndices: resolvedSpineIndices,
+                    generatedAt: CFAbsoluteTimeGetCurrent(),
+                    renderSignature: self.renderSignature,
+                    estimatedMemoryBytes: estimatedBytes
+                )
+                coverageStore.addSegment(segment)
+            }
+
+            DispatchQueue.main.async {
+                guard context.paginationToken == token,
+                      context.controller != nil else { return }
+                context.runtime?.refreshBookPageMapInPlace(pageMap)
+            }
+        }
+    }
+
+    // MARK: - Private
+
+    private func waitForReadingInteractionToSettle(
+        cancellationController: RDEPUBMetadataParseCancellationController? = nil
+    ) {
+        while context.controller != nil,
+              cancellationController?.isCancelled != true,
+              context.secondsSinceLastUserNavigation() < backgroundInteractionCooldown {
+            Thread.sleep(forTimeInterval: 0.08)
+        }
+    }
+
+    private func scheduleRetry(
+        spineIndex: Int,
+        retryCount: Int,
+        resultLock: NSLock,
+        parseState: ParseState,
+        cancellationController: RDEPUBMetadataParseCancellationController
+    ) {
+        guard retryCount < Self.maxRetryCount else {
+            RDEPUBBackgroundTrace.log(
+                "MetadataParse",
+                "spine=\(spineIndex) max retries reached, marking as deferredFailure"
+            )
+            return
+        }
+
+        let delay = Self.retryDelays[min(retryCount, Self.retryDelays.count - 1)]
+        RDEPUBBackgroundTrace.log(
+            "MetadataParse",
+            "scheduling retry for spine=\(spineIndex) attempt=\(retryCount + 1) delay=\(delay)s"
+        )
+
+        DispatchQueue.global(qos: .utility).asyncAfter(deadline: .now() + delay) { [weak self] in
+            guard let self else { return }
+            let context = self.context
+            guard context.controller != nil,
+                  context.paginationToken == self.token,
+                  !cancellationController.isCancelled else {
+                return
+            }
+
+            do {
+                let chapterBuilder = context.makeTextBookBuilder(layoutConfig: self.layoutConfig)
+                guard let result = try chapterBuilder.buildChapter(
+                    parser: self.parser,
+                    publication: self.publication,
+                    spineIndex: spineIndex,
+                    pageSize: self.pageSize,
+                    style: self.style
+                ) else {
+                    return
+                }
+                guard context.controller != nil,
+                      context.paginationToken == self.token,
+                      !cancellationController.isCancelled else {
+                    RDEPUBBackgroundTrace.log("MetadataParse", "drop retry result due to cancellation spine=\(spineIndex)")
+                    return
+                }
+
+                let chapter = result.chapter
+                let precomputedHash = self.contentHashBySpineIndex[spineIndex] ?? ""
+                let cacheKey = context.chapterCacheKey(
+                    forSpineIndex: spineIndex,
+                    precomputedContentHash: precomputedHash,
+                    renderSignature: self.renderSignature
+                )
+                let summary = RDEPUBChapterSummary(
+                    pageRanges: chapter.pages.map { .init(location: $0.contentRange.location, length: $0.contentRange.length) },
+                    pageCount: chapter.pages.count,
+                    fragmentOffsets: chapter.fragmentOffsets,
+                    cfiMap: chapter.cfiMap,
+                    renderSignature: cacheKey.renderSignature,
+                    schemaVersion: RDEPUBChapterSummary.currentSchemaVersion,
+                    chapterContentHash: cacheKey.chapterContentHash,
+                    pageMetadataList: chapter.pages.map { .from($0.metadata) }
+                )
+                guard context.controller != nil,
+                      context.paginationToken == self.token,
+                      !cancellationController.isCancelled else {
+                    RDEPUBBackgroundTrace.log("MetadataParse", "skip retry disk write due to cancellation spine=\(spineIndex)")
+                    return
+                }
+                self.summaryDiskCache?.write(summary: summary, for: cacheKey)
+
+                resultLock.lock()
+                parseState.summariesBySpineIndex[spineIndex] = summary
+                parseState.totalResolvedCount += 1
+                let shouldRefresh =
+                    parseState.totalResolvedCount - parseState.lastAppliedCount >= self.pageMapRefreshInterval
+                    || parseState.totalResolvedCount == self.allBuildableIndices.count
+                if shouldRefresh {
+                    parseState.lastAppliedCount = parseState.totalResolvedCount
+                }
+                resultLock.unlock()
+
+                if shouldRefresh {
+                    let partialMap = self.buildPageMap(summaries: parseState.summariesBySpineIndex)
+                    DispatchQueue.main.async {
+                        guard context.paginationToken == self.token,
+                              context.controller != nil,
+                              !cancellationController.isCancelled else { return }
+                        context.runtime?.refreshBookPageMapInPlace(partialMap)
+                    }
+                }
+
+                RDEPUBBackgroundTrace.log(
+                    "MetadataParse",
+                    "retry succeeded for spine=\(spineIndex) attempt=\(retryCount + 1)"
+                )
+            } catch {
+                RDEPUBBackgroundTrace.log(
+                    "MetadataParse",
+                    "retry failed for spine=\(spineIndex) attempt=\(retryCount + 1) error=\(error)"
+                )
+
+                self.scheduleRetry(
+                    spineIndex: spineIndex,
+                    retryCount: retryCount + 1,
+                    resultLock: resultLock,
+                    parseState: parseState,
+                    cancellationController: cancellationController
+                )
+            }
+        }
+    }
+
+    private func restoreBookPageMapIfPossible() -> RDEPUBBookPageMap? {
+        guard let summaryDiskCache else { return nil }
+        guard summaryDiskCache.isCacheComplete(keys: catalog.map(\.key)) else {
+            return nil
+        }
+        let restored = summaryDiskCache.readAll(keys: catalog)
+        guard restored.summaries.count == catalog.count else {
+            return nil
+        }
+        return restored.mapBuilder.build()
+    }
+
+    private func buildPageMap(
+        summaries: [Int: RDEPUBChapterSummary]
+    ) -> RDEPUBBookPageMap {
+        var builder = RDEPUBBookPageMap.Builder()
+        for item in catalog {
+            guard let summary = summaries[item.spineIndex] else { continue }
+            builder.add(
+                spineIndex: item.spineIndex,
+                href: item.href,
+                title: item.title,
+                pageCount: summary.pageCount,
+                fragmentOffsets: summary.fragmentOffsets
+            )
+        }
+        return builder.build()
+    }
+}

Sources/RDReaderView/EPUBUI/ReaderController/RDEPUBPaginationState.swift

@@ -14,7 +14,7 @@ struct RDEPUBPaginationState {
 
     var activePageMap: RDEPUBBookPageMap?
 
-    var pendingFullPageMap: RDEPUBBookPageMap?
+    var pendingPageMapUpdates: [RDEPUBPendingPageMapUpdate] = []
 
     var chapterWindowSnapshot: RDEPUBChapterWindowSnapshot?
 

Sources/RDReaderView/EPUBUI/ReaderController/RDEPUBPresentationRuntime.swift

@@ -1,5 +1,17 @@
 import UIKit
 
+enum RDEPUBPendingPageMapUpdateKind {
+    case reconcileFullMap
+    case extendPartial(currentPageNumber: Int, currentLocation: RDEPUBLocation?)
+    case appendForward
+}
+
+struct RDEPUBPendingPageMapUpdate {
+    let pageMap: RDEPUBBookPageMap
+    let source: RDEPUBPaginationStateSource
+    let kind: RDEPUBPendingPageMapUpdateKind
+}
+
 final class RDEPUBPresentationRuntime {
 
     private unowned let context: RDEPUBReaderContext
@@ -34,77 +46,63 @@ final class RDEPUBPresentationRuntime {
         navigationStateMachine.transition(to: .presentingWindow)
         context.textBook = nil
         context.bookPageMap = bookPageMap
-        context.pendingFullPageMap = nil
+        context.pendingPageMapUpdates.removeAll()
         context.replaceActiveSnapshot(makeSnapshot(from: bookPageMap))
         paginationState.activePageMap = bookPageMap
-        paginationState.pendingFullPageMap = nil
+        paginationState.pendingPageMapUpdates.removeAll()
         paginationState.source = .initialPartial
         finishPagination(restoreLocation)
     }
 
     func refreshBookPageMapInPlace(_ bookPageMap: RDEPUBBookPageMap) {
-        if let pendingMap = context.pendingFullPageMap {
-            let shouldKeepExisting =
-                pendingMap.totalChapters > bookPageMap.totalChapters ||
-                (pendingMap.totalChapters == bookPageMap.totalChapters &&
-                    pendingMap.totalPages >= bookPageMap.totalPages)
-            if shouldKeepExisting {
-                return
-            }
-        }
-
         navigationStateMachine.transition(to: .reconcilingFullMap)
-        context.pendingFullPageMap = bookPageMap
-        paginationState.pendingFullPageMap = bookPageMap
+        enqueuePendingPageMapUpdate(
+            RDEPUBPendingPageMapUpdate(
+                pageMap: bookPageMap,
+                source: .pendingFullMap,
+                kind: .reconcileFullMap
+            )
+        )
     }
 
-    func applyPendingFullPageMapIfNeeded() {
-        guard let pendingMap = context.pendingFullPageMap,
-              let readerView = context.readerView,
+    func commitPendingPageMapUpdateIfNeeded() {
+        guard let readerView = context.readerView,
               let controller = context.controller else { return }
 
         guard !controller.isRepaginating else { return }
+        guard !readerView.isPageCurlTransitioning else {
+            RDEPUBBackgroundTrace.log("PageMapCommit", "defer commit reason=pageCurlTransition")
+            return
+        }
 
-        navigationStateMachine.transition(to: .reconcilingFullMap)
-        let decision = reconciliationCoordinator.evaluateTakeover(
-            candidatePageMap: pendingMap,
-            candidateSegment: nil,
-            currentWindow: context.bookPageMap,
-            jumpSession: jumpSessionManager.activeSession
-        )
-
-        switch decision {
-        case .keepCurrentWindow:
-            RDEPUBBackgroundTrace.log("Reconciliation", "decision: keepCurrentWindow")
-
-        case .fullReplace(let newPageMap):
-            RDEPUBBackgroundTrace.log("Reconciliation", "decision: fullReplace")
-            applyFullPageMapReplacement(newPageMap, readerView: readerView, controller: controller)
-
-        case .expandWindow, .segmentReplace:
-            RDEPUBBackgroundTrace.log("Reconciliation", "decision: unexpected segment decision")
+        let rankedUpdates = rankedPendingPageMapUpdates()
+        for (index, update) in rankedUpdates {
+            if commitPendingPageMapUpdate(
+                update,
+                at: index,
+                readerView: readerView,
+                controller: controller
+            ) {
+                return
+            }
         }
     }
 
-    func applyExtendedPartialPageMap(
+    func queueExtendedPartialPageMap(
         _ bookPageMap: RDEPUBBookPageMap,
         currentPageNumber: Int,
         currentLocation: RDEPUBLocation?
     ) {
-        guard let readerView = context.readerView else { return }
-
-        navigationStateMachine.transition(to: .presentingWindow)
-        context.bookPageMap = bookPageMap
-        context.replaceActiveSnapshot(makeSnapshot(from: bookPageMap))
-        paginationState.activePageMap = bookPageMap
-        paginationState.source = .asyncExtension
-
-        readerView.reloadPageCountOnly()
-        if let currentLocation,
-           locationCoordinator.restoreReadingLocation(currentLocation, animated: false) {
-            return
-        }
-        readerView.transitionToPage(pageNum: max(currentPageNumber - 1, 0), animated: false)
+        enqueuePendingPageMapUpdate(
+            RDEPUBPendingPageMapUpdate(
+                pageMap: bookPageMap,
+                source: .asyncExtension,
+                kind: .extendPartial(
+                    currentPageNumber: currentPageNumber,
+                    currentLocation: currentLocation
+                )
+            )
+        )
     }
 
     func applySettingsPreviewPageMap(_ bookPageMap: RDEPUBBookPageMap) {
@@ -115,6 +113,16 @@ final class RDEPUBPresentationRuntime {
         paginationState.source = .settingsPreview
     }
 
+    func queueForwardAppendedPageMap(_ bookPageMap: RDEPUBBookPageMap) {
+        enqueuePendingPageMapUpdate(
+            RDEPUBPendingPageMapUpdate(
+                pageMap: bookPageMap,
+                source: .asyncExtension,
+                kind: .appendForward
+            )
+        )
+    }
+
     func clear() {
         paginationState = RDEPUBPaginationState()
         navigationStateMachine.transition(to: .idle)
@@ -150,22 +158,17 @@ final class RDEPUBPresentationRuntime {
     ) {
         let currentLocation = locationCoordinator.currentVisibleLocation()
 
-        context.pendingFullPageMap = nil
         context.textBook = nil
-        context.bookPageMap = newPageMap
-        context.replaceActiveSnapshot(makeSnapshot(from: newPageMap))
-
-        paginationState.activePageMap = newPageMap
-        paginationState.pendingFullPageMap = nil
-        paginationState.source = .fullReplacement
-        navigationStateMachine.transition(to: .presentingWindow)
+        applyPageMapToLiveModel(newPageMap, source: .fullReplacement)
 
         if let currentLocation {
-            let newPageNumber = controller.pageNumber(for: currentLocation) ?? (readerView.currentPage + 1)
-            let newPage = max(0, newPageNumber - 1)
-            readerView.reloadPageCountOnly()
-            if newPage != readerView.currentPage {
-                readerView.transitionToPage(pageNum: newPage, animated: false)
+            if rebindVisibleLocation(currentLocation, readerView: readerView, controller: controller) == false {
+                let newPageNumber = controller.pageNumber(for: currentLocation) ?? (readerView.currentPage + 1)
+                let newPage = max(0, newPageNumber - 1)
+                rebindVisiblePage(
+                    to: newPage,
+                    readerView: readerView
+                )
             }
         } else {
             readerView.reloadPageCountOnly()
@@ -181,4 +184,184 @@ final class RDEPUBPresentationRuntime {
             }
         }
     }
+
+    private func enqueuePendingPageMapUpdate(_ update: RDEPUBPendingPageMapUpdate) {
+        var updates = context.pendingPageMapUpdates
+        if let existingIndex = updates.firstIndex(where: {
+            pendingPageMapUpdateKindMatches($0.kind, update.kind)
+        }) {
+            let existing = updates[existingIndex]
+            if shouldReplacePendingPageMapUpdate(existing, with: update) {
+                updates[existingIndex] = update
+            }
+        } else {
+            updates.append(update)
+        }
+        context.pendingPageMapUpdates = updates
+        paginationState.pendingPageMapUpdates = updates
+        commitPendingPageMapUpdateIfNeeded()
+    }
+
+    private func rankedPendingPageMapUpdates() -> [(Int, RDEPUBPendingPageMapUpdate)] {
+        context.pendingPageMapUpdates.enumerated().sorted { lhs, rhs in
+            pendingPriority(for: lhs.element.kind) > pendingPriority(for: rhs.element.kind)
+        }
+    }
+
+    private func commitPendingPageMapUpdate(
+        _ update: RDEPUBPendingPageMapUpdate,
+        at index: Int,
+        readerView: RDReaderView,
+        controller: RDEPUBReaderController
+    ) -> Bool {
+        switch update.kind {
+        case .reconcileFullMap:
+            navigationStateMachine.transition(to: .reconcilingFullMap)
+            let decision = reconciliationCoordinator.evaluateTakeover(
+                candidatePageMap: update.pageMap,
+                candidateSegment: nil,
+                currentWindow: context.bookPageMap,
+                jumpSession: jumpSessionManager.activeSession
+            )
+
+            switch decision {
+            case .keepCurrentWindow:
+                RDEPUBBackgroundTrace.log("Reconciliation", "decision: keepCurrentWindow")
+                return false
+
+            case .fullReplace(let newPageMap):
+                RDEPUBBackgroundTrace.log("Reconciliation", "decision: fullReplace")
+                removePendingPageMapUpdate(at: index)
+                applyFullPageMapReplacement(newPageMap, readerView: readerView, controller: controller)
+                return true
+
+            case .expandWindow, .segmentReplace:
+                RDEPUBBackgroundTrace.log("Reconciliation", "decision: unexpected segment decision")
+                removePendingPageMapUpdate(at: index)
+                return false
+            }
+
+        case .extendPartial(let currentPageNumber, let currentLocation):
+            removePendingPageMapUpdate(at: index)
+            applyPageMapToLiveModel(update.pageMap, source: update.source)
+            if let currentLocation,
+               rebindVisibleLocation(currentLocation, readerView: readerView, controller: controller) {
+                return true
+            }
+            rebindVisiblePage(
+                to: max(currentPageNumber - 1, 0),
+                readerView: readerView
+            )
+            return true
+
+        case .appendForward:
+            removePendingPageMapUpdate(at: index)
+            applyPageMapToLiveModel(update.pageMap, source: update.source)
+            readerView.reloadPageCountOnly()
+            return true
+        }
+    }
+
+    private func rebindVisiblePage(to pageIndex: Int, readerView: RDReaderView) {
+        if readerView.currentDisplayType == .pageCurl {
+            readerView.transitionToPage(pageNum: pageIndex, animated: false)
+        } else {
+            readerView.reloadPageCountOnly()
+            if pageIndex != readerView.currentPage {
+                readerView.transitionToPage(pageNum: pageIndex, animated: false)
+            }
+        }
+    }
+
+    private func rebindVisibleLocation(
+        _ location: RDEPUBLocation,
+        readerView: RDReaderView,
+        controller: RDEPUBReaderController
+    ) -> Bool {
+        guard let targetPageNumber = controller.pageNumber(for: location) else {
+            return false
+        }
+
+        if context.bookPageMap != nil,
+           context.runtime?.prepareOnDemandChapter(
+                forAbsolutePageNumber: targetPageNumber,
+                allowSynchronousLoad: true
+           ) == false {
+            return false
+        }
+
+        rebindVisiblePage(
+            to: max(targetPageNumber - 1, 0),
+            readerView: readerView
+        )
+        return true
+    }
+
+    private func applyPageMapToLiveModel(
+        _ pageMap: RDEPUBBookPageMap,
+        source: RDEPUBPaginationStateSource
+    ) {
+        navigationStateMachine.transition(to: .presentingWindow)
+        context.bookPageMap = pageMap
+        context.replaceActiveSnapshot(makeSnapshot(from: pageMap))
+        discardSupersededPendingPageMapUpdates(afterApplying: pageMap)
+        paginationState.activePageMap = pageMap
+        paginationState.source = source
+    }
+
+    private func removePendingPageMapUpdate(at index: Int) {
+        var updates = context.pendingPageMapUpdates
+        guard updates.indices.contains(index) else { return }
+        updates.remove(at: index)
+        context.pendingPageMapUpdates = updates
+        paginationState.pendingPageMapUpdates = updates
+    }
+
+    private func discardSupersededPendingPageMapUpdates(afterApplying liveMap: RDEPUBBookPageMap) {
+        let updates = context.pendingPageMapUpdates.filter { update in
+            update.pageMap.totalChapters > liveMap.totalChapters
+                || (
+                    update.pageMap.totalChapters == liveMap.totalChapters
+                        && update.pageMap.totalPages > liveMap.totalPages
+                )
+        }
+        context.pendingPageMapUpdates = updates
+        paginationState.pendingPageMapUpdates = updates
+    }
+
+    private func pendingPriority(for kind: RDEPUBPendingPageMapUpdateKind) -> Int {
+        switch kind {
+        case .extendPartial:
+            return 3
+        case .appendForward:
+            return 2
+        case .reconcileFullMap:
+            return 1
+        }
+    }
+
+    private func pendingPageMapUpdateKindMatches(
+        _ lhs: RDEPUBPendingPageMapUpdateKind,
+        _ rhs: RDEPUBPendingPageMapUpdateKind
+    ) -> Bool {
+        switch (lhs, rhs) {
+        case (.reconcileFullMap, .reconcileFullMap),
+             (.appendForward, .appendForward),
+             (.extendPartial, .extendPartial):
+            return true
+        default:
+            return false
+        }
+    }
+
+    private func shouldReplacePendingPageMapUpdate(
+        _ existing: RDEPUBPendingPageMapUpdate,
+        with candidate: RDEPUBPendingPageMapUpdate
+    ) -> Bool {
+        candidate.pageMap.totalChapters > existing.pageMap.totalChapters
+            || (
+                candidate.pageMap.totalChapters == existing.pageMap.totalChapters
+                    && candidate.pageMap.totalPages >= existing.pageMap.totalPages
+            )
+    }
 }

Sources/RDReaderView/EPUBUI/ReaderController/RDEPUBReaderContext.swift

@@ -83,9 +83,9 @@ final class RDEPUBReaderContext {
         set { state.searchState = newValue }
     }
 
-    var pendingFullPageMap: RDEPUBBookPageMap? {
-        get { state.pendingFullPageMap }
-        set { state.pendingFullPageMap = newValue }
+    var pendingPageMapUpdates: [RDEPUBPendingPageMapUpdate] {
+        get { state.pendingPageMapUpdates }
+        set { state.pendingPageMapUpdates = newValue }
     }
 
     var lastTextPaginationPageSize: CGSize? {
@@ -249,7 +249,7 @@ final class RDEPUBReaderContext {
            let publication,
            publication.spine.indices.contains(spineIndex) {
             let href = publication.spine[spineIndex].href
-            contentHash = parser.htmlString(forRelativePath: href)?.sha256Hex ?? ""
+            contentHash = parser.htmlString(forRelativePath: href)?.rd_sha256Hex ?? ""
         } else {
             contentHash = ""
         }

Sources/RDReaderView/EPUBUI/ReaderController/RDEPUBReaderPaginationCoordinator.swift

@@ -2,77 +2,13 @@ import Foundation
 
 final class RDEPUBReaderPaginationCoordinator {
 
-    private final class MetadataParseState {
-
-        var summariesBySpineIndex: [Int: RDEPUBChapterSummary]
-
-        var totalResolvedCount: Int
-
-        var lastAppliedCount: Int
-
-        init(
-            summariesBySpineIndex: [Int: RDEPUBChapterSummary],
-            totalResolvedCount: Int,
-            lastAppliedCount: Int
-        ) {
-            self.summariesBySpineIndex = summariesBySpineIndex
-            self.totalResolvedCount = totalResolvedCount
-            self.lastAppliedCount = lastAppliedCount
-        }
-    }
-
-    private final class MetadataParseCancellationController {
-
-        let token: UUID
-
-        private let lock = NSLock()
-
-        private weak var queue: OperationQueue?
-
-        private var cancelled = false
-
-        init(token: UUID) {
-            self.token = token
-        }
-
-        func attach(queue: OperationQueue) {
-            let shouldCancelImmediately: Bool
-            lock.lock()
-            self.queue = queue
-            shouldCancelImmediately = cancelled
-            lock.unlock()
-
-            if shouldCancelImmediately {
-                queue.cancelAllOperations()
-            }
-        }
-
-        func cancel() {
-            let queueToCancel: OperationQueue?
-            lock.lock()
-            cancelled = true
-            queueToCancel = queue
-            lock.unlock()
-            queueToCancel?.cancelAllOperations()
-        }
-
-        var isCancelled: Bool {
-            lock.lock()
-            let value = cancelled
-            lock.unlock()
-            return value
-        }
-    }
-
-    private let backgroundInteractionCooldown: CFAbsoluteTime = 0.8
-
     static var pageMapRefreshInterval: Int = 32
 
     private unowned let context: RDEPUBReaderContext
 
     private let metadataParseControlLock = NSLock()
 
-    private var activeMetadataParseCancellationController: MetadataParseCancellationController?
+    private var activeMetadataParseCancellationController: RDEPUBMetadataParseCancellationController?
 
     init(context: RDEPUBReaderContext) {
         self.context = context
@@ -148,7 +84,7 @@ final class RDEPUBReaderPaginationCoordinator {
         guard let controller = context.controller else { return }
         context.textBook = textBook
         context.bookPageMap = nil
-        context.pendingFullPageMap = nil
+        context.pendingPageMapUpdates.removeAll()
         let snapshot = controller.nativeTextSnapshot(from: textBook)
         context.replaceActiveSnapshot(snapshot)
 
@@ -167,7 +103,7 @@ final class RDEPUBReaderPaginationCoordinator {
         guard context.controller != nil else { return }
         context.textBook = nil
         context.bookPageMap = nil
-        context.pendingFullPageMap = nil
+        context.pendingPageMapUpdates.removeAll()
         context.replaceActiveSnapshot(snapshot)
 
         guard !snapshot.pages.isEmpty else {
@@ -206,8 +142,34 @@ final class RDEPUBReaderPaginationCoordinator {
 
     func refreshVisibleContentPreservingLocation() {
         guard let readerView = context.readerView else { return }
+        if readerView.isPageCurlTransitioning {
+            RDEPUBBackgroundTrace.log(
+                "LoadingPage",
+                "defer refreshVisibleContent currentPage=\(readerView.currentPage + 1) reason=pageCurlTransition"
+            )
+            DispatchQueue.main.asyncAfter(deadline: .now() + 0.1) { [weak self] in
+                self?.refreshVisibleContentPreservingLocation()
+            }
+            return
+        }
         let restoreLocation = context.currentVisibleLocation() ?? context.persistenceLocation()
-        readerView.reloadData()
+        RDEPUBBackgroundTrace.log(
+            "LoadingPage",
+            "refreshVisibleContentPreservingLocation currentPage=\(readerView.currentPage + 1) restoreHref=\(restoreLocation?.href ?? "nil") restoreCFI=\(restoreLocation?.cfi ?? "nil")"
+        )
+        if readerView.currentDisplayType == .pageCurl, readerView.currentPage >= 0 {
+            RDEPUBBackgroundTrace.log(
+                "LoadingPage",
+                "refreshVisibleContent using transitionToPage currentPage=\(readerView.currentPage + 1)"
+            )
+            readerView.transitionToPage(pageNum: readerView.currentPage, animated: false)
+        } else {
+            RDEPUBBackgroundTrace.log(
+                "LoadingPage",
+                "refreshVisibleContent using reloadData currentPage=\(readerView.currentPage + 1)"
+            )
+            readerView.reloadData()
+        }
         if let restoreLocation {
             _ = context.restoreReadingLocation(restoreLocation)
         }
@@ -275,6 +237,11 @@ final class RDEPUBReaderPaginationCoordinator {
                     "QuickOpen",
                     "ready anchorSpine=\(runtimeChapter.spineIndex) pages=\(runtimeChapter.pages.count)"
                 )
+                let initialChapters = self.loadInitialInteractiveRuntimeChapters(
+                    anchorChapter: runtimeChapter,
+                    publication: publication,
+                    runtime: runtime
+                )
 
                 DispatchQueue.main.async {
                     guard context.paginationToken == token,
@@ -284,13 +251,21 @@ final class RDEPUBReaderPaginationCoordinator {
                         totalSpineCount: publication.spine.count,
                         windowRadius: context.configuration.chapterWindowRadius
                     )
-                    let partialMap = self.makePartialPageMap(from: [runtimeChapter])
+                    let partialMap = self.makePartialPageMap(from: initialChapters)
                     runtime.applyBookPageMap(partialMap, restoreLocation: restoreLocation)
                     runtime.prefetchForwardChaptersAfterInitialOpen(
                         anchorSpineIndex: runtimeChapter.spineIndex,
                         totalSpineCount: publication.spine.count
                     )
-                    self.paginateMetadataOnly(token: token, restoreLocation: restoreLocation)
+                    let cancellationController = self.beginMetadataParseCancellationController(for: token)
+                    let worker = RDEPUBMetadataParseWorker(
+                        context: context,
+                        cancellationController: cancellationController,
+                        token: token,
+                        parser: parser,
+                        publication: publication
+                    )
+                    worker.start(token: token, restoreLocation: restoreLocation)
                 }
             } catch {
                 DispatchQueue.main.async {
@@ -321,6 +296,55 @@ final class RDEPUBReaderPaginationCoordinator {
         throw lastError ?? RDEPUBParserError.emptySpine
     }
 
+    private func loadInitialInteractiveRuntimeChapters(
+        anchorChapter: RDEPUBRuntimeChapter,
+        publication: RDEPUBPublication,
+        runtime: RDEPUBReaderRuntime
+    ) -> [RDEPUBRuntimeChapter] {
+        let minimumInteractivePageCount = 2
+        let maximumAdditionalChapters = 1
+
+        guard anchorChapter.pages.count < minimumInteractivePageCount else {
+            return [anchorChapter]
+        }
+
+        let buildableSpineIndices = publication.spine.indices.filter { isBuildableTextSpine(at: $0, in: publication) }
+        guard let anchorPosition = buildableSpineIndices.firstIndex(of: anchorChapter.spineIndex) else {
+            return [anchorChapter]
+        }
+
+        var selectedChapters: [RDEPUBRuntimeChapter] = [anchorChapter]
+
+        for offset in 1...maximumAdditionalChapters {
+            let candidatePositions = [anchorPosition + offset, anchorPosition - offset]
+            for candidatePosition in candidatePositions {
+                guard buildableSpineIndices.indices.contains(candidatePosition) else { continue }
+                let spineIndex = buildableSpineIndices[candidatePosition]
+                guard selectedChapters.contains(where: { $0.spineIndex == spineIndex }) == false else { continue }
+
+                do {
+                    let chapter = try runtime.chapterLoader.loadChapterSynchronouslyForMigration(
+                        spineIndex: spineIndex,
+                        store: runtime.chapterRuntimeStore
+                    )
+                    selectedChapters.append(chapter)
+                } catch {
+                    RDEPUBBackgroundTrace.log(
+                        "QuickOpen",
+                        "lookahead skip spine=\(spineIndex) reason=\(error)"
+                    )
+                }
+            }
+
+            let loadedPageCount = selectedChapters.reduce(0) { $0 + $1.pages.count }
+            if loadedPageCount >= minimumInteractivePageCount {
+                break
+            }
+        }
+
+        return selectedChapters
+    }
+
     private func makePartialPageMap(from chapters: [RDEPUBRuntimeChapter]) -> RDEPUBBookPageMap {
         var builder = RDEPUBBookPageMap.Builder()
         for chapter in chapters {
@@ -352,524 +376,12 @@ final class RDEPUBReaderPaginationCoordinator {
         publication.spine.indices.filter { isBuildableTextSpine(at: $0, in: publication) }
     }
 
-    private func waitForReadingInteractionToSettle(
-        using context: RDEPUBReaderContext,
-        cancellationController: MetadataParseCancellationController? = nil
-    ) {
-        while context.controller != nil,
-              cancellationController?.isCancelled != true,
-              context.secondsSinceLastUserNavigation() < backgroundInteractionCooldown {
-            Thread.sleep(forTimeInterval: 0.08)
-        }
-    }
-
     private func isBuildableTextSpine(at index: Int, in publication: RDEPUBPublication) -> Bool {
         guard publication.spine.indices.contains(index) else { return false }
         let item = publication.spine[index]
         return item.linear && (item.mediaType.contains("html") || item.mediaType.contains("xhtml"))
     }
 
-    private static let maxRetryCount = 3
-    private static let retryDelays: [TimeInterval] = [0.5, 2.0, 8.0]
-
-    func paginateMetadataOnly(token: UUID, restoreLocation: RDEPUBLocation?) {
-        let context = self.context
-        guard let parser = context.parser,
-              let publication = context.publication else { return }
-        let cancellationController = beginMetadataParseCancellationController(for: token)
-
-        let pageSize = context.currentTextPageSize()
-        let layoutConfig = context.currentTextLayoutConfig(pageSize: pageSize)
-        let style = context.currentTextRenderStyle()
-        let renderSignature = context.currentRenderSignature()
-        let allBuildableIndices = allBuildableSpineIndices(in: publication)
-        let summaryDiskCache = context.runtime?.summaryDiskCache
-        let workerCount = max(1, context.configuration.metadataParsingConcurrency)
-        let cpuCount = ProcessInfo.processInfo.activeProcessorCount
-        RDEPUBBackgroundTrace.log("MetadataParse", "config concurrency=\(workerCount) cpuCores=\(cpuCount)")
-
-        DispatchQueue.global(qos: .utility).async { [weak self] in
-            guard let self else { return }
-            defer { self.finishMetadataParseCancellationController(cancellationController) }
-            guard context.controller != nil,
-                  !cancellationController.isCancelled,
-                  context.paginationToken == token else { return }
-
-            if let restoredPageMap = self.restoreBookPageMapIfPossible(publication: publication) {
-                RDEPUBBackgroundTrace.log(
-                    "MetadataParse",
-                    "full cache restore hit chapters=\(restoredPageMap.totalChapters) pages=\(restoredPageMap.totalPages)"
-                )
-                DispatchQueue.main.async {
-                    guard context.paginationToken == token,
-                          context.controller != nil,
-                          !cancellationController.isCancelled else { return }
-                    context.runtime?.refreshBookPageMapInPlace(restoredPageMap)
-                }
-                return
-            }
-
-            let prewarmStart = CFAbsoluteTimeGetCurrent()
-            var contentHashBySpineIndex: [Int: String] = [:]
-            for spineIndex in allBuildableIndices {
-                guard !cancellationController.isCancelled,
-                      context.paginationToken == token,
-                      context.controller != nil else {
-                    RDEPUBBackgroundTrace.log("MetadataParse", "abort during content hash prewarm")
-                    return
-                }
-                guard let href = publication.spine.indices.contains(spineIndex)
-                    ? publication.spine[spineIndex].href : nil,
-                    let html = parser.htmlString(forRelativePath: href) else {
-                    contentHashBySpineIndex[spineIndex] = ""
-                    continue
-                }
-                contentHashBySpineIndex[spineIndex] = html.sha256Hex
-            }
-            let prewarmMs = Int((CFAbsoluteTimeGetCurrent() - prewarmStart) * 1000)
-            RDEPUBBackgroundTrace.log("MetadataParse", "prewarmHashMs=\(prewarmMs) chapters=\(allBuildableIndices.count)")
-
-            let catalog = allBuildableIndices.map { spineIndex in
-                let item = publication.spine[spineIndex]
-                return (
-                    key: context.chapterCacheKey(
-                        forSpineIndex: spineIndex,
-                        precomputedContentHash: contentHashBySpineIndex[spineIndex] ?? "",
-                        renderSignature: renderSignature
-                    ),
-                    spineIndex: spineIndex,
-                    href: item.href,
-                    title: item.title
-                )
-            }
-            let restored = summaryDiskCache?.readAll(keys: catalog)
-            RDEPUBBackgroundTrace.log(
-                "MetadataParse",
-                "begin token=\(token.uuidString) buildableChapters=\(allBuildableIndices.count) concurrency=\(workerCount)"
-            )
-            let cachedSummaries = restored?.summaries ?? [:]
-            let cachedSpineIndices = Set(cachedSummaries.keys)
-            let resultLock = NSLock()
-            let parseState = MetadataParseState(
-                summariesBySpineIndex: cachedSummaries,
-                totalResolvedCount: cachedSpineIndices.count,
-                lastAppliedCount: cachedSpineIndices.count
-            )
-
-            if !cachedSpineIndices.isEmpty {
-                RDEPUBBackgroundTrace.log(
-                    "MetadataParse",
-                    "resumeFromCache cachedChapters=\(cachedSpineIndices.count) total=\(allBuildableIndices.count)"
-                )
-                let cachedMap = self.buildPageMap(from: catalog, summaries: parseState.summariesBySpineIndex)
-                DispatchQueue.main.async {
-                    guard context.paginationToken == token,
-                          context.controller != nil else { return }
-                    context.runtime?.refreshBookPageMapInPlace(cachedMap)
-                }
-            }
-
-            let prioritizedSpineIndices: [Int]
-            if let priorityManager = context.runtime?.backgroundPriorityManager {
-                let currentSpineIndex = context.runtime?.locationCoordinator.currentVisibleLocation()
-                    .flatMap { context.normalizedSpineIndex(for: $0) }
-                prioritizedSpineIndices = priorityManager.makeMetadataPriorityOrder(
-                    allBuildableIndices: allBuildableIndices,
-                    currentSpineIndex: currentSpineIndex,
-                    cachedSpineIndices: cachedSpineIndices
-                )
-                RDEPUBBackgroundTrace.log(
-                    "MetadataParse",
-                    "prioritized hot=\(prioritizedSpineIndices.prefix(10).count) total=\(prioritizedSpineIndices.count)"
-                )
-            } else {
-                prioritizedSpineIndices = allBuildableIndices.filter { !cachedSpineIndices.contains($0) }
-            }
-
-            let uncachedSpineIndices = prioritizedSpineIndices
-
-            self.waitForReadingInteractionToSettle(
-                using: context,
-                cancellationController: cancellationController
-            )
-            guard !cancellationController.isCancelled,
-                  context.controller != nil,
-                  context.paginationToken == token else {
-                RDEPUBBackgroundTrace.log("MetadataParse", "abort before queue start")
-                return
-            }
-
-            let wallClockStart = CFAbsoluteTimeGetCurrent()
-            var totalRenderMs: Double = 0
-            var totalWriteMs: Double = 0
-            var totalMergeMs: Double = 0
-            var completedChapters = 0
-            var failedChapters = 0
-            let timingLock = NSLock()
-
-            let queue = OperationQueue()
-            queue.name = "com.rdreader.metadata.parse"
-            queue.qualityOfService = .utility
-            queue.maxConcurrentOperationCount = workerCount
-            cancellationController.attach(queue: queue)
-
-            let refreshInterval = RDEPUBReaderPaginationCoordinator.pageMapRefreshInterval
-
-            for (offset, spineIndex) in uncachedSpineIndices.enumerated() {
-                let operation = BlockOperation()
-                operation.addExecutionBlock { [weak operation] in
-                    guard context.controller != nil,
-                          context.paginationToken == token,
-                          !cancellationController.isCancelled,
-                          operation?.isCancelled != true else {
-                        return
-                    }
-                    do {
-                        RDEPUBBackgroundTrace.log("MetadataParse", "正在解析 spine=\(spineIndex) \(offset + 1)/\(uncachedSpineIndices.count)")
-
-                        let renderResult: RDEPUBChapterSummary? = try autoreleasepool { () -> RDEPUBChapterSummary? in
-                            guard context.controller != nil,
-                                  context.paginationToken == token,
-                                  !cancellationController.isCancelled,
-                                  operation?.isCancelled != true else {
-                                return nil
-                            }
-                            let chapterBuilder = context.makeTextBookBuilder(layoutConfig: layoutConfig)
-                            let renderStart = CFAbsoluteTimeGetCurrent()
-                            guard let result = try chapterBuilder.buildChapter(
-                                parser: parser,
-                                publication: publication,
-                                spineIndex: spineIndex,
-                                pageSize: pageSize,
-                                style: style
-                            ) else {
-                                return nil
-                            }
-                            guard context.controller != nil,
-                                  context.paginationToken == token,
-                                  !cancellationController.isCancelled,
-                                  operation?.isCancelled != true else {
-                                RDEPUBBackgroundTrace.log("MetadataParse", "drop rendered chapter due to cancellation spine=\(spineIndex)")
-                                return nil
-                            }
-                            let renderElapsed = (CFAbsoluteTimeGetCurrent() - renderStart) * 1000
-
-                            let chapter = result.chapter
-                            let precomputedHash = contentHashBySpineIndex[spineIndex] ?? ""
-                            let cacheKey = context.chapterCacheKey(
-                                forSpineIndex: spineIndex,
-                                precomputedContentHash: precomputedHash,
-                                renderSignature: renderSignature
-                            )
-                            let summary = RDEPUBChapterSummary(
-                                pageRanges: chapter.pages.map { .init(location: $0.contentRange.location, length: $0.contentRange.length) },
-                                pageCount: chapter.pages.count,
-                                fragmentOffsets: chapter.fragmentOffsets,
-                                cfiMap: chapter.cfiMap,
-                                renderSignature: cacheKey.renderSignature,
-                                schemaVersion: RDEPUBChapterSummary.currentSchemaVersion,
-                                chapterContentHash: cacheKey.chapterContentHash,
-                                pageMetadataList: chapter.pages.map { .from($0.metadata) }
-                            )
-                            guard context.controller != nil,
-                                  context.paginationToken == token,
-                                  !cancellationController.isCancelled,
-                                  operation?.isCancelled != true else {
-                                RDEPUBBackgroundTrace.log("MetadataParse", "skip disk write due to cancellation spine=\(spineIndex)")
-                                return nil
-                            }
-                            let writeStart = CFAbsoluteTimeGetCurrent()
-                            summaryDiskCache?.write(summary: summary, for: cacheKey)
-                            let writeElapsed = (CFAbsoluteTimeGetCurrent() - writeStart) * 1000
-
-                            timingLock.lock()
-                            totalRenderMs += renderElapsed
-                            totalWriteMs += writeElapsed
-                            completedChapters += 1
-                            timingLock.unlock()
-
-                            RDEPUBBackgroundTrace.log(
-                                "MetadataParse",
-                                "spine=\(spineIndex) renderMs=\(Int(renderElapsed)) writeMs=\(Int(writeElapsed))"
-                            )
-                            return summary
-                        }
-
-                        guard let renderResult else { return }
-                        guard context.controller != nil,
-                              context.paginationToken == token,
-                              !cancellationController.isCancelled,
-                              operation?.isCancelled != true else {
-                            return
-                        }
-
-                        var snapshot: [Int: RDEPUBChapterSummary]?
-                        resultLock.lock()
-                        parseState.summariesBySpineIndex[spineIndex] = renderResult
-                        parseState.totalResolvedCount += 1
-                        if parseState.totalResolvedCount - parseState.lastAppliedCount >= refreshInterval
-                            || parseState.totalResolvedCount == allBuildableIndices.count {
-                            parseState.lastAppliedCount = parseState.totalResolvedCount
-                            snapshot = parseState.summariesBySpineIndex
-                        }
-                        resultLock.unlock()
-
-                        if let snapshot {
-                            let mergeStart = CFAbsoluteTimeGetCurrent()
-                            let partialMap = self.buildPageMap(from: catalog, summaries: snapshot)
-                            let mergeElapsed = (CFAbsoluteTimeGetCurrent() - mergeStart) * 1000
-                            timingLock.lock()
-                            totalMergeMs += mergeElapsed
-                            timingLock.unlock()
-                            DispatchQueue.main.async {
-                                guard context.paginationToken == token,
-                                      context.controller != nil,
-                                      !cancellationController.isCancelled else { return }
-                                context.runtime?.refreshBookPageMapInPlace(partialMap)
-                            }
-                        }
-                    } catch {
-                        guard !cancellationController.isCancelled,
-                              context.paginationToken == token,
-                              context.controller != nil,
-                              operation?.isCancelled != true else {
-                            return
-                        }
-                        timingLock.lock()
-                        failedChapters += 1
-                        timingLock.unlock()
-                        RDEPUBBackgroundTrace.log("MetadataParse", "buildChapter FAILED: spine=\(spineIndex) error=\(error)")
-
-                        self.scheduleRetry(
-                            spineIndex: spineIndex,
-                            retryCount: 0,
-                            token: token,
-                            context: context,
-                            parser: parser,
-                            publication: publication,
-                            pageSize: pageSize,
-                            layoutConfig: layoutConfig,
-                            style: style,
-                            renderSignature: renderSignature,
-                            summaryDiskCache: summaryDiskCache,
-                            contentHashBySpineIndex: contentHashBySpineIndex,
-                            resultLock: resultLock,
-                            parseState: parseState,
-                            allBuildableIndices: allBuildableIndices,
-                            catalog: catalog,
-                            refreshInterval: refreshInterval,
-                            cancellationController: cancellationController
-                        )
-                    }
-                }
-                queue.addOperation(operation)
-            }
-            queue.waitUntilAllOperationsAreFinished()
-            if !cancellationController.isCancelled,
-               context.paginationToken == token,
-               context.controller != nil {
-                summaryDiskCache?.flushPendingWrites()
-            }
-
-            let wallClockMs = Int((CFAbsoluteTimeGetCurrent() - wallClockStart) * 1000)
-            timingLock.lock()
-            let renderTotal = Int(totalRenderMs)
-            let writeTotal = Int(totalWriteMs)
-            let mergeTotal = Int(totalMergeMs)
-            let rendered = completedChapters
-            let failed = failedChapters
-            timingLock.unlock()
-            let avgRenderMs = rendered > 0 ? renderTotal / rendered : 0
-            RDEPUBBackgroundTrace.log(
-                "MetadataParse",
-                "timing wallClockMs=\(wallClockMs) chapters=\(rendered) failed=\(failed) " +
-                "prewarmHashMs=\(prewarmMs) renderTotalMs=\(renderTotal) writeTotalMs=\(writeTotal) " +
-                "mergeTotalMs=\(mergeTotal) avgRenderMs=\(avgRenderMs) concurrency=\(workerCount)"
-            )
-            context.lastMetadataParseWallClockMs = wallClockMs
-            context.lastMetadataParseConcurrency = workerCount
-
-            guard context.controller != nil,
-                  context.paginationToken == token,
-                  !cancellationController.isCancelled else {
-                RDEPUBBackgroundTrace.log("MetadataParse", "abort: reader dismissed or token changed")
-                return
-            }
-
-            let finalMergeStart = CFAbsoluteTimeGetCurrent()
-            let pageMap = self.buildPageMap(from: catalog, summaries: parseState.summariesBySpineIndex)
-            let finalMergeMs = Int((CFAbsoluteTimeGetCurrent() - finalMergeStart) * 1000)
-            RDEPUBBackgroundTrace.log(
-                "MetadataParse",
-                "complete chapters=\(pageMap.totalChapters) pages=\(pageMap.totalPages) finalMergeMs=\(finalMergeMs)"
-            )
-
-            if let coverageStore = context.runtime?.backgroundCoverageStore {
-                let resolvedSpineIndices = Set(parseState.summariesBySpineIndex.keys)
-                let lowerSpine = resolvedSpineIndices.min() ?? 0
-                let upperSpine = resolvedSpineIndices.max() ?? 0
-                let estimatedBytes = 256 + pageMap.entries.count * 96 + resolvedSpineIndices.count * 16
-
-                let segment = RDEPUBBackgroundCoverageSegment(
-                    lowerSpineIndex: lowerSpine,
-                    upperSpineIndex: upperSpine,
-                    pageMap: pageMap,
-                    resolvedSpineIndices: resolvedSpineIndices,
-                    generatedAt: CFAbsoluteTimeGetCurrent(),
-                    renderSignature: renderSignature,
-                    estimatedMemoryBytes: estimatedBytes
-                )
-                coverageStore.addSegment(segment)
-            }
-
-            DispatchQueue.main.async {
-                guard context.paginationToken == token,
-                      context.controller != nil else { return }
-                context.runtime?.refreshBookPageMapInPlace(pageMap)
-            }
-        }
-    }
-
-    private func scheduleRetry(
-        spineIndex: Int,
-        retryCount: Int,
-        token: UUID,
-        context: RDEPUBReaderContext,
-        parser: RDEPUBParser,
-        publication: RDEPUBPublication,
-        pageSize: CGSize,
-        layoutConfig: RDEPUBTextLayoutConfig,
-        style: RDEPUBTextRenderStyle,
-        renderSignature: String,
-        summaryDiskCache: RDEPUBChapterSummaryDiskCache?,
-        contentHashBySpineIndex: [Int: String],
-        resultLock: NSLock,
-        parseState: MetadataParseState,
-        allBuildableIndices: [Int],
-        catalog: [(key: RDEPUBChapterCacheKey, spineIndex: Int, href: String, title: String)],
-        refreshInterval: Int,
-        cancellationController: MetadataParseCancellationController
-    ) {
-        guard retryCount < Self.maxRetryCount else {
-            RDEPUBBackgroundTrace.log(
-                "MetadataParse",
-                "spine=\(spineIndex) max retries reached, marking as deferredFailure"
-            )
-            return
-        }
-
-        let delay = Self.retryDelays[min(retryCount, Self.retryDelays.count - 1)]
-        RDEPUBBackgroundTrace.log(
-            "MetadataParse",
-            "scheduling retry for spine=\(spineIndex) attempt=\(retryCount + 1) delay=\(delay)s"
-        )
-
-        DispatchQueue.global(qos: .utility).asyncAfter(deadline: .now() + delay) { [weak self] in
-            guard let self else { return }
-            guard context.controller != nil,
-                  context.paginationToken == token,
-                  !cancellationController.isCancelled else {
-                return
-            }
-
-            do {
-                let chapterBuilder = context.makeTextBookBuilder(layoutConfig: layoutConfig)
-                guard let result = try chapterBuilder.buildChapter(
-                    parser: parser,
-                    publication: publication,
-                    spineIndex: spineIndex,
-                    pageSize: pageSize,
-                    style: style
-                ) else {
-                    return
-                }
-                guard context.controller != nil,
-                      context.paginationToken == token,
-                      !cancellationController.isCancelled else {
-                    RDEPUBBackgroundTrace.log("MetadataParse", "drop retry result due to cancellation spine=\(spineIndex)")
-                    return
-                }
-
-                let chapter = result.chapter
-                let precomputedHash = contentHashBySpineIndex[spineIndex] ?? ""
-                let cacheKey = context.chapterCacheKey(
-                    forSpineIndex: spineIndex,
-                    precomputedContentHash: precomputedHash,
-                    renderSignature: renderSignature
-                )
-                let summary = RDEPUBChapterSummary(
-                    pageRanges: chapter.pages.map { .init(location: $0.contentRange.location, length: $0.contentRange.length) },
-                    pageCount: chapter.pages.count,
-                    fragmentOffsets: chapter.fragmentOffsets,
-                    cfiMap: chapter.cfiMap,
-                    renderSignature: cacheKey.renderSignature,
-                    schemaVersion: RDEPUBChapterSummary.currentSchemaVersion,
-                    chapterContentHash: cacheKey.chapterContentHash,
-                    pageMetadataList: chapter.pages.map { .from($0.metadata) }
-                )
-                guard context.controller != nil,
-                      context.paginationToken == token,
-                      !cancellationController.isCancelled else {
-                    RDEPUBBackgroundTrace.log("MetadataParse", "skip retry disk write due to cancellation spine=\(spineIndex)")
-                    return
-                }
-                summaryDiskCache?.write(summary: summary, for: cacheKey)
-
-                resultLock.lock()
-                parseState.summariesBySpineIndex[spineIndex] = summary
-                parseState.totalResolvedCount += 1
-                let shouldRefresh =
-                    parseState.totalResolvedCount - parseState.lastAppliedCount >= refreshInterval
-                    || parseState.totalResolvedCount == allBuildableIndices.count
-                if shouldRefresh {
-                    parseState.lastAppliedCount = parseState.totalResolvedCount
-                }
-                resultLock.unlock()
-
-                if shouldRefresh {
-                    let partialMap = self.buildPageMap(from: catalog, summaries: parseState.summariesBySpineIndex)
-                    DispatchQueue.main.async {
-                        guard context.paginationToken == token,
-                              context.controller != nil,
-                              !cancellationController.isCancelled else { return }
-                        context.runtime?.refreshBookPageMapInPlace(partialMap)
-                    }
-                }
-
-                RDEPUBBackgroundTrace.log(
-                    "MetadataParse",
-                    "retry succeeded for spine=\(spineIndex) attempt=\(retryCount + 1)"
-                )
-            } catch {
-                RDEPUBBackgroundTrace.log(
-                    "MetadataParse",
-                    "retry failed for spine=\(spineIndex) attempt=\(retryCount + 1) error=\(error)"
-                )
-
-                self.scheduleRetry(
-                    spineIndex: spineIndex,
-                    retryCount: retryCount + 1,
-                    token: token,
-                    context: context,
-                    parser: parser,
-                    publication: publication,
-                    pageSize: pageSize,
-                    layoutConfig: layoutConfig,
-                    style: style,
-                    renderSignature: renderSignature,
-                    summaryDiskCache: summaryDiskCache,
-                    contentHashBySpineIndex: contentHashBySpineIndex,
-                    resultLock: resultLock,
-                    parseState: parseState,
-                    allBuildableIndices: allBuildableIndices,
-                    catalog: catalog,
-                    refreshInterval: refreshInterval,
-                    cancellationController: cancellationController
-                )
-            }
-        }
-    }
-
     func cancelActiveMetadataParseWork() {
         metadataParseControlLock.lock()
         let controller = activeMetadataParseCancellationController
@@ -878,17 +390,7 @@ final class RDEPUBReaderPaginationCoordinator {
         controller?.cancel()
     }
 
-    private func beginMetadataParseCancellationController(for token: UUID) -> MetadataParseCancellationController {
-        let controller = MetadataParseCancellationController(token: token)
-        metadataParseControlLock.lock()
-        let previous = activeMetadataParseCancellationController
-        activeMetadataParseCancellationController = controller
-        metadataParseControlLock.unlock()
-        previous?.cancel()
-        return controller
-    }
-
-    private func finishMetadataParseCancellationController(_ controller: MetadataParseCancellationController) {
+    func finishMetadataParseCancellationController(_ controller: RDEPUBMetadataParseCancellationController) {
         metadataParseControlLock.lock()
         if activeMetadataParseCancellationController === controller {
             activeMetadataParseCancellationController = nil
@@ -896,52 +398,13 @@ final class RDEPUBReaderPaginationCoordinator {
         metadataParseControlLock.unlock()
     }
 
-    private func restoreBookPageMapIfPossible(publication: RDEPUBPublication) -> RDEPUBBookPageMap? {
-        guard let summaryDiskCache = context.runtime?.summaryDiskCache,
-              let parser = context.parser else {
-            return nil
-        }
-        let renderSignature = context.currentRenderSignature()
-        let catalog = allBuildableSpineIndices(in: publication).map { spineIndex in
-            let item = publication.spine[spineIndex]
-            let href = item.href
-            let contentHash = parser.htmlString(forRelativePath: href)?.sha256Hex ?? ""
-            return (
-                key: context.chapterCacheKey(
-                    forSpineIndex: spineIndex,
-                    precomputedContentHash: contentHash,
-                    renderSignature: renderSignature
-                ),
-                spineIndex: spineIndex,
-                href: href,
-                title: item.title
-            )
-        }
-        guard summaryDiskCache.isCacheComplete(keys: catalog.map(\.key)) else {
-            return nil
-        }
-        let restored = summaryDiskCache.readAll(keys: catalog)
-        guard restored.summaries.count == catalog.count else {
-            return nil
-        }
-        return restored.mapBuilder.build()
-    }
-
-    private func buildPageMap(
-        from catalog: [(key: RDEPUBChapterCacheKey, spineIndex: Int, href: String, title: String)],
-        summaries: [Int: RDEPUBChapterSummary]
-    ) -> RDEPUBBookPageMap {
-        var builder = RDEPUBBookPageMap.Builder()
-        for item in catalog {
-            guard let summary = summaries[item.spineIndex] else { continue }
-            builder.add(
-                spineIndex: item.spineIndex,
-                href: item.href,
-                title: item.title,
-                pageCount: summary.pageCount,
-                fragmentOffsets: summary.fragmentOffsets
-            )
-        }
-        return builder.build()
+    private func beginMetadataParseCancellationController(for token: UUID) -> RDEPUBMetadataParseCancellationController {
+        let controller = RDEPUBMetadataParseCancellationController(token: token)
+        metadataParseControlLock.lock()
+        let previous = activeMetadataParseCancellationController
+        activeMetadataParseCancellationController = controller
+        metadataParseControlLock.unlock()
+        previous?.cancel()
+        return controller
     }
 }

Sources/RDReaderView/EPUBUI/ReaderController/RDEPUBReaderRuntime.swift

@@ -105,7 +105,7 @@ final class RDEPUBReaderRuntime {
         context.readingSession = nil
         context.textBook = nil
         context.bookPageMap = nil
-        context.pendingFullPageMap = nil
+        context.pendingPageMapUpdates.removeAll()
         context.activeBookmarks = []
         context.activeHighlights = []
         context.searchState = nil
@@ -349,7 +349,7 @@ final class RDEPUBReaderRuntime {
     }
 
     func applyPendingFullPageMapIfNeeded() {
-        presentationRuntime.applyPendingFullPageMapIfNeeded()
+        presentationRuntime.commitPendingPageMapUpdateIfNeeded()
     }
 
     func finishPagination(restoreLocation: RDEPUBLocation?) {
@@ -605,7 +605,7 @@ final class RDEPUBReaderRuntime {
         paginationCoordinator.cancelActiveMetadataParseWork()
         chapterRuntimeStore.invalidateAllForSettingsChange()
         context.bookPageMap = nil
-        context.pendingFullPageMap = nil
+        context.pendingPageMapUpdates.removeAll()
         jumpSessionManager.clearSession()
         backgroundPriorityManager.reset()
         backgroundCoverageStore.clearAll()

Sources/RDReaderView/EPUBUI/ReaderController/RDEPUBReaderServices.swift

@@ -45,7 +45,7 @@ final class RDEPUBReaderServices {
     func makeChapterSummaryDiskCache(bookIdentifier: String?) -> RDEPUBChapterSummaryDiskCache {
         let cachesDirectory = FileManager.default.urls(for: .cachesDirectory, in: .userDomainMask).first
             ?? FileManager.default.temporaryDirectory
-        let bookID = (bookIdentifier ?? "default").sha256Hex
+        let bookID = (bookIdentifier ?? "default").rd_sha256Hex
         let directory = cachesDirectory
             .appendingPathComponent("RDEPUBChapterSummaryCache", isDirectory: true)
             .appendingPathComponent(bookID, isDirectory: true)

Sources/RDReaderView/EPUBUI/ReaderController/RDEPUBReaderState.swift

@@ -24,7 +24,7 @@ final class RDEPUBReaderState {
 
     var searchState: RDEPUBSearchState?
 
-    var pendingFullPageMap: RDEPUBBookPageMap?
+    var pendingPageMapUpdates: [RDEPUBPendingPageMapUpdate] = []
 
     var lastTextPaginationPageSize: CGSize?