fix(reader): use stable page IDs instead of indices for preloading (#654)

## Problem

When the DIVINA reader opens a book that belongs to a multi-segment
series, `preloadNextSegmentIfNeeded` may prepend the previous book's
pages to the `readerPages` array. This shifts all page indices, causing
background preload tasks that captured raw indices to load pages from
the wrong book. The cleanup pass then evicts the correctly-loaded
visible pages, leaving the UI stuck on a loading spinner — most
noticeable in dual-page and cover modes.

## Approach

Replace every external index-based preload path with stable
`ReaderPageID` lookups that resolve the index at call time, so stale
captures are impossible. Additionally, track the set of currently
visible page IDs in the scheduler so cleanup never evicts pages the user
is looking at.

For CoverPageView (pure SwiftUI → `PageScrollView` UIViewRepresentable),
images were loaded but the UI never refreshed because the image cache
lives outside `@Observable`. Fixed by having `PageScrollView`'s
Coordinator register a `pagePresentationInvalidationObserver` — the same
pattern the scroll reader already uses via
`NativePagedPagePresentationCoordinator`.

## Scope

- **ReaderPageLoadScheduler**: merge `preloadImageForPage(at:)` into
`preloadImage(for:)` as single entry point; simplify `preloadPages` from
task-group to sequential loop (tasks were serialising on MainActor
anyway); add `visiblePageIDs` protection in cleanup; remove dead
`setPreloadedImage(forPageIndex:)` overload
- **ReaderViewModel**: remove public `preloadImageForPage(at:)` wrapper
- **ScrollPageView (iOS/macOS)**: switch `preloadVisiblePages` from
index-based to pageID-based loading
- **CoverPageView**: make `preloadPresentationWindow` async with
`prioritizeVisiblePageLoads`; collapse redundant guard block
- **NativeImagePageViewController**: use `preloadImage(for:)` instead of
capturing stale index
- **PageScrollView (iOS/macOS)**: register presentation invalidation
observer for automatic UIKit refresh

Author: everpcpc

KMReader.xcodeproj/project.pbxproj

@@ -438,7 +438,7 @@
 				"CODE_SIGN_ENTITLEMENTS[sdk=macosx*]" = "KMReader/KMReader-macOS.entitlements";
 				CODE_SIGN_IDENTITY = "Apple Development";
 				CODE_SIGN_STYLE = Automatic;
-				CURRENT_PROJECT_VERSION = 362;
+				CURRENT_PROJECT_VERSION = 363;
 				DEVELOPMENT_TEAM = M777UHWZA4;
 				ENABLE_APP_SANDBOX = YES;
 				ENABLE_HARDENED_RUNTIME = YES;
@@ -496,7 +496,7 @@
 				"CODE_SIGN_ENTITLEMENTS[sdk=macosx*]" = "KMReader/KMReader-macOS.entitlements";
 				CODE_SIGN_IDENTITY = "Apple Distribution";
 				CODE_SIGN_STYLE = Manual;
-				CURRENT_PROJECT_VERSION = 362;
+				CURRENT_PROJECT_VERSION = 363;
 				DEVELOPMENT_TEAM = "";
 				"DEVELOPMENT_TEAM[sdk=appletvos*]" = M777UHWZA4;
 				"DEVELOPMENT_TEAM[sdk=iphoneos*]" = M777UHWZA4;
@@ -556,7 +556,7 @@
 				CODE_SIGN_ENTITLEMENTS = KMReaderWidgets/KMReaderWidgets.entitlements;
 				CODE_SIGN_IDENTITY = "Apple Development";
 				CODE_SIGN_STYLE = Automatic;
-				CURRENT_PROJECT_VERSION = 362;
+				CURRENT_PROJECT_VERSION = 363;
 				DEVELOPMENT_TEAM = M777UHWZA4;
 				GENERATE_INFOPLIST_FILE = YES;
 				INFOPLIST_FILE = KMReaderWidgets/Info.plist;
@@ -590,7 +590,7 @@
 				CODE_SIGN_IDENTITY = "Apple Distribution";
 				"CODE_SIGN_IDENTITY[sdk=iphoneos*]" = "iPhone Distribution";
 				CODE_SIGN_STYLE = Manual;
-				CURRENT_PROJECT_VERSION = 362;
+				CURRENT_PROJECT_VERSION = 363;
 				DEVELOPMENT_TEAM = "";
 				"DEVELOPMENT_TEAM[sdk=iphoneos*]" = M777UHWZA4;
 				GENERATE_INFOPLIST_FILE = YES;

KMReader/Features/Reader/Services/ReaderPageLoadScheduler.swift

@@ -42,6 +42,7 @@ final class ReaderPageLoadScheduler {
   private var preloadingImageTasks: [ReaderPageID: ImageLoadTaskRecord] = [:]
   private var lastPreloadRequestTime: Date?
   private var preloadTask: Task<Void, Never>?
+  private var visiblePageIDs: [ReaderPageID] = []
 
   init(
     preloadBefore: Int = ReaderConstants.preloadBefore,
@@ -97,6 +98,8 @@ final class ReaderPageLoadScheduler {
   }
 
   func prioritizeVisiblePageLoads(for pageIDs: [ReaderPageID]) {
+    visiblePageIDs = pageIDs
+
     let keepPageIDs = prioritizedPageIDs(around: pageIDs)
     guard !keepPageIDs.isEmpty else { return }
 
@@ -127,57 +130,31 @@ final class ReaderPageLoadScheduler {
     guard !pagesToPreload.isEmpty else { return }
 
     preloadTask?.cancel()
+    let pageIDsToPreload = pagesToPreload.map(\.pageID)
     preloadTask = Task { [weak self] in
       guard let self else { return }
 
-      let results = await withTaskGroup(of: (Int, ReaderPageID, PlatformImage?, URL?).self) {
-        group -> [(Int, ReaderPageID, PlatformImage?, URL?)] in
-        for (index, pageID) in pagesToPreload {
-          if Task.isCancelled { break }
-          if self.preloadedImage(for: pageID) != nil {
-            continue
-          }
-          group.addTask {
-            if Task.isCancelled { return (index, pageID, nil, nil) }
-            let (image, animatedSourceFileURL) = await self.preloadDecodedPageImage(pageIndex: index)
-            return (index, pageID, image, animatedSourceFileURL)
-          }
-        }
-
-        var collected: [(Int, ReaderPageID, PlatformImage?, URL?)] = []
-        for await result in group {
-          if !Task.isCancelled {
-            collected.append(result)
-          }
-        }
-        return collected
+      for pageID in pageIDsToPreload {
+        guard !Task.isCancelled else { return }
+        if self.preloadedImage(for: pageID) != nil { continue }
+        _ = await self.preloadImage(for: pageID)
       }
 
-      if Task.isCancelled { return }
-
-      for (pageIndex, pageID, image, animatedSourceFileURL) in results {
-        self.updateAnimatedPresentation(
-          knownAnimatedState: animatedSourceFileURL != nil,
-          sourceFileURL: animatedSourceFileURL,
-          for: pageID
-        )
-        if let image {
-          self.setPreloadedImage(image, forPageIndex: pageIndex)
-        }
+      if !Task.isCancelled {
+        self.cleanupDistantImagesAroundCurrentPage()
       }
-
-      self.cleanupDistantImagesAroundCurrentPage()
     }
   }
 
   func cleanupDistantImagesAroundCurrentPage() {
-    let keepPageIDs = Set(
+    var keepPageIDs = Set(
       pageWindowEntries(
         around: currentPageID,
         before: keepRangeBefore,
         after: keepRangeAfter
       ).map(\.pageID)
     )
+    keepPageIDs.formUnion(visiblePageIDs)
     guard !keepPageIDs.isEmpty else { return }
 
     let imageKeysToRemove = preloadedImagesByID.keys.filter { !keepPageIDs.contains($0) }
@@ -192,8 +169,6 @@ final class ReaderPageLoadScheduler {
     for key in animatedKeysToRemove {
       updateAnimatedPresentation(knownAnimatedState: nil, sourceFileURL: nil, for: key)
     }
-
-    logger.debug("🖼️ Memory Cache: \(preloadedImagesByID.count) images")
   }
 
   func isAnimatedPage(for pageID: ReaderPageID) -> Bool {
@@ -216,12 +191,15 @@ final class ReaderPageLoadScheduler {
     await prepareAnimatedPagePlaybackURL(pageIndex: pageIndex)
   }
 
-  func preloadImageForPage(at pageIndex: Int) async -> PlatformImage? {
-    guard let pageID = readerPageID(forPageIndex: pageIndex) else { return nil }
+  func preloadImage(for pageID: ReaderPageID) async -> PlatformImage? {
     if let cached = preloadedImagesByID[pageID] {
       return cached
     }
 
+    guard let pageIndex = pageIndex(for: pageID) else {
+      return nil
+    }
+
     if let existingTask = preloadingImageTasks[pageID] {
       return await existingTask.task.value
     }
@@ -249,13 +227,6 @@ final class ReaderPageLoadScheduler {
     return image
   }
 
-  func preloadImage(for pageID: ReaderPageID) async -> PlatformImage? {
-    guard let pageIndex = pageIndex(for: pageID) else {
-      return preloadedImagesByID[pageID]
-    }
-    return await preloadImageForPage(at: pageIndex)
-  }
-
   func clearPreloadedImages() {
     preloadTask?.cancel()
     preloadTask = nil
@@ -288,6 +259,7 @@ final class ReaderPageLoadScheduler {
     readerPages.removeAll()
     readerPageIndexByID.removeAll()
     currentPageID = nil
+    visiblePageIDs.removeAll()
   }
 
   private func pageIndex(for pageID: ReaderPageID) -> Int? {
@@ -331,11 +303,6 @@ final class ReaderPageLoadScheduler {
     return keepPageIDs
   }
 
-  private func setPreloadedImage(_ image: PlatformImage, forPageIndex pageIndex: Int) {
-    guard let pageID = readerPageID(forPageIndex: pageIndex) else { return }
-    setPreloadedImage(image, for: pageID)
-  }
-
   private func setPreloadedImage(_ image: PlatformImage, for pageID: ReaderPageID) {
     preloadedImagesByID[pageID] = image
     invalidatePresentation(.pages([pageID]))

KMReader/Features/Reader/ViewModels/ReaderViewModel.swift

@@ -823,10 +823,6 @@ class ReaderViewModel {
     await pageLoadScheduler.prepareAnimatedPagePlaybackURL(pageID: pageID)
   }
 
-  func preloadImageForPage(at pageIndex: Int) async -> PlatformImage? {
-    await pageLoadScheduler.preloadImageForPage(at: pageIndex)
-  }
-
   func preloadImage(for pageID: ReaderPageID) async -> PlatformImage? {
     await pageLoadScheduler.preloadImage(for: pageID)
   }

KMReader/Features/Reader/Views/CoverPageView.swift

@@ -653,53 +653,41 @@ struct CoverPageView: View {
     postTransitionTask = Task(priority: .utility) {
       guard !Task.isCancelled else { return }
 
-      let shouldSyncPosition = await MainActor.run { () -> Bool in
+      let shouldContinue = await MainActor.run { () -> Bool in
         guard token == transitionToken else { return false }
         guard currentItem == item else { return false }
         viewModel.updateCurrentPosition(viewItem: item)
         return true
       }
-      guard shouldSyncPosition else { return }
-
-      let shouldPreload = await MainActor.run { () -> Bool in
-        guard token == transitionToken else { return false }
-        guard currentItem == item else { return false }
-        preloadPresentationWindow(around: item)
-        return true
-      }
-      guard shouldPreload else { return }
+      guard shouldContinue else { return }
 
+      await preloadPresentationWindow(around: item)
       await viewModel.preloadPages()
     }
   }
 
-  private func preloadPresentationWindow(around item: ReaderViewItem) {
+  private func preloadPresentationWindow(around item: ReaderViewItem) async {
     let candidateItems = [
       item,
       viewModel.adjacentViewItem(from: item, offset: 1),
       viewModel.adjacentViewItem(from: item, offset: -1),
     ].compactMap { $0 }
 
-    var pageIndices: [Int] = []
+    var pageIDs: [ReaderPageID] = []
     var seenPageIDs: Set<ReaderPageID> = []
     for candidateItem in candidateItems {
       for pageID in candidateItem.pageIDs where seenPageIDs.insert(pageID).inserted {
-        if let pageIndex = viewModel.pageIndex(for: pageID) {
-          pageIndices.append(pageIndex)
-        }
+        pageIDs.append(pageID)
       }
     }
 
-    guard !pageIndices.isEmpty else { return }
+    guard !pageIDs.isEmpty else { return }
 
-    Task(priority: .userInitiated) {
-      await withTaskGroup(of: Void.self) { group in
-        for pageIndex in pageIndices {
-          group.addTask {
-            _ = await viewModel.preloadImageForPage(at: pageIndex)
-          }
-        }
-      }
+    viewModel.prioritizeVisiblePageLoads(for: item.pageIDs)
+
+    for pageID in pageIDs {
+      guard !Task.isCancelled else { return }
+      _ = await viewModel.preloadImage(for: pageID)
     }
   }
 

KMReader/Features/Reader/Views/NativeImagePageViewController.swift

@@ -189,13 +189,12 @@
     private func startLoadingImageIfNeeded() {
       guard loadTask == nil else { return }
       guard let viewModel else { return }
-      guard let requestedPageIndex = viewModel.pageIndex(for: pageID) else { return }
 
       let requestedPageID = pageID
 
       loadTask = Task { [weak self] in
         guard let self else { return }
-        let image = await viewModel.preloadImageForPage(at: requestedPageIndex)
+        let image = await viewModel.preloadImage(for: requestedPageID)
         guard !Task.isCancelled else { return }
         guard self.pageID == requestedPageID else { return }
 

KMReader/Features/Reader/Views/PageImage/PageScrollView_iOS.swift

@@ -85,6 +85,7 @@
       context.coordinator.parent = self
       context.coordinator.applyDisplayModeIfNeeded(in: scrollView)
       context.coordinator.setupNativeInteractions(on: scrollView)
+      context.coordinator.registerInvalidationObserver()
       return scrollView
     }
 
@@ -127,8 +128,21 @@
       weak var contentStack: UIStackView?
       var contentHeightConstraint: NSLayoutConstraint?
       private var pageViews: [NativePageItem] = []
+      private var invalidationObserverToken: UUID?
+
+      func registerInvalidationObserver() {
+        guard invalidationObserverToken == nil else { return }
+        invalidationObserverToken = parent.viewModel.addPagePresentationInvalidationObserver {
+          [weak self] _ in
+          self?.updatePages()
+        }
+      }
 
       func prepareForDismantle() {
+        if let token = invalidationObserverToken {
+          parent?.viewModel.removePagePresentationInvalidationObserver(token)
+          invalidationObserverToken = nil
+        }
         pageViews.forEach { view in
           view.prepareForDismantle()
           view.removeFromSuperview()

KMReader/Features/Reader/Views/PageImage/PageScrollView_macOS.swift

@@ -92,6 +92,7 @@
       context.coordinator.scrollView = scrollView
       context.coordinator.applyDisplayModeIfNeeded(in: scrollView)
       context.coordinator.setupNativeInteractions(on: scrollView)
+      context.coordinator.registerInvalidationObserver()
 
       return scrollView
     }
@@ -162,8 +163,21 @@
       weak var contentStack: NSStackView?
       var contentHeightConstraint: NSLayoutConstraint?
       private var pageViews: [NativePageItem] = []
+      private var invalidationObserverToken: UUID?
+
+      func registerInvalidationObserver() {
+        guard invalidationObserverToken == nil else { return }
+        invalidationObserverToken = parent.viewModel.addPagePresentationInvalidationObserver {
+          [weak self] _ in
+          self?.updatePages()
+        }
+      }
 
       func prepareForDismantle() {
+        if let token = invalidationObserverToken {
+          parent?.viewModel.removePagePresentationInvalidationObserver(token)
+          invalidationObserverToken = nil
+        }
         if let scrollView = scrollView {
           NotificationCenter.default.removeObserver(
             self, name: NSScrollView.didEndLiveScrollNotification, object: scrollView)

KMReader/Features/Reader/Views/ScrollPageView_iOS.swift

@@ -652,7 +652,7 @@
       private func preloadVisiblePages(for item: ReaderViewItem) {
         let visiblePageIDs = item.pageIDs
         if visiblePreloadItem == item,
-          visiblePageIDs.allSatisfy({
+          visiblePreloadTask != nil || visiblePageIDs.allSatisfy({
             parent.viewModel.preloadedImage(for: $0) != nil
               || parent.viewModel.hasPendingImageLoad(for: $0)
           })
@@ -662,9 +662,6 @@
 
         parent.viewModel.prioritizeVisiblePageLoads(for: visiblePageIDs)
 
-        let visiblePageIndices = visiblePageIDs.compactMap { parent.viewModel.pageIndex(for: $0) }
-        guard !visiblePageIndices.isEmpty else { return }
-
         visiblePreloadTask?.cancel()
         visiblePreloadItem = item
         let viewModel = parent.viewModel
@@ -675,9 +672,9 @@
             }
           }
 
-          for pageIndex in visiblePageIndices {
+          for pageID in visiblePageIDs {
             guard !Task.isCancelled else { return }
-            _ = await viewModel.preloadImageForPage(at: pageIndex)
+            _ = await viewModel.preloadImage(for: pageID)
           }
         }
       }

KMReader/Features/Reader/Views/ScrollPageView_macOS.swift

@@ -757,7 +757,7 @@
       private func preloadVisiblePages(for item: ReaderViewItem) {
         let visiblePageIDs = item.pageIDs
         if visiblePreloadItem == item,
-          visiblePageIDs.allSatisfy({
+          visiblePreloadTask != nil || visiblePageIDs.allSatisfy({
             parent.viewModel.preloadedImage(for: $0) != nil
               || parent.viewModel.hasPendingImageLoad(for: $0)
           })
@@ -767,9 +767,6 @@
 
         parent.viewModel.prioritizeVisiblePageLoads(for: visiblePageIDs)
 
-        let visiblePageIndices = visiblePageIDs.compactMap { parent.viewModel.pageIndex(for: $0) }
-        guard !visiblePageIndices.isEmpty else { return }
-
         visiblePreloadTask?.cancel()
         visiblePreloadItem = item
         let viewModel = parent.viewModel
@@ -780,9 +777,9 @@
             }
           }
 
-          for pageIndex in visiblePageIndices {
+          for pageID in visiblePageIDs {
             guard !Task.isCancelled else { return }
-            _ = await viewModel.preloadImageForPage(at: pageIndex)
+            _ = await viewModel.preloadImage(for: pageID)
           }
         }
       }