Defer List scrolls on macOS 12 until content settles to avoid offset corruption

macOS 12's SwiftUI List corrupts its scroll offset when
ScrollViewProxy.scrollTo runs while the list content is still settling,
which resurfaced after following a planet (the article list is
wholesale-replaced while FollowPlanetView and the selection restore both
request scrolls). Since many senders post scroll notifications, gate the
receivers instead of individual senders: a shared ListScrollSettleGate
runs scrolls immediately on macOS 13+ and on macOS 12 defers them until
the list content has been stable for a moment, keeping only the latest
request.

Wired into all three List-backed scroll sites: the article list
(articlesVersion), the sidebar (planet id changes), and search results
(result id changes, which previously scrolled on every keystroke's
result replacement). ScrollView-based views (AI chat, avatar picker)
are unaffected by the List bug and left unchanged.

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

Author: livid

Planet/Helper/ViewUtils.swift

@@ -155,6 +155,61 @@ extension Color {
     }
 }
 
+/// macOS 12's SwiftUI List corrupts its scroll offset when
+/// ScrollViewProxy.scrollTo runs while the list content is still settling
+/// (initial layout, or a wholesale replacement such as switching to a freshly
+/// followed planet). On macOS 13+, `perform` runs the scroll action
+/// immediately; on macOS 12 it defers the action until the list content has
+/// been stable for `settleDelay`. Only the latest deferred action is kept.
+/// Call `noteContentChange` whenever the list content is replaced.
+@MainActor
+final class ListScrollSettleGate {
+    private var lastContentChange = Date()
+    private var deferredTask: Task<Void, Never>?
+    private let settleDelay: TimeInterval
+    private let maxWait: TimeInterval
+
+    init(settleDelay: TimeInterval = 0.6, maxWait: TimeInterval = 5) {
+        self.settleDelay = settleDelay
+        self.maxWait = maxWait
+    }
+
+    func noteContentChange() {
+        lastContentChange = Date()
+    }
+
+    func perform(_ action: @escaping () -> Void) {
+        if #available(macOS 13.0, *) {
+            action()
+            return
+        }
+        deferredTask?.cancel()
+        deferredTask = Task { @MainActor [weak self] in
+            let startedAt = Date()
+            while true {
+                guard let self, !Task.isCancelled else { return }
+                let remaining = self.settleDelay - Date().timeIntervalSince(self.lastContentChange)
+                if remaining <= 0 {
+                    break
+                }
+                // Content keeps churning; give up rather than risking a
+                // corrupted offset from scrolling mid-layout.
+                if Date().timeIntervalSince(startedAt) > self.maxWait {
+                    return
+                }
+                try? await Task.sleep(nanoseconds: UInt64(max(remaining, 0.05) * 1_000_000_000))
+            }
+            guard !Task.isCancelled else { return }
+            action()
+        }
+    }
+
+    func cancel() {
+        deferredTask?.cancel()
+        deferredTask = nil
+    }
+}
+
 enum ViewVisibility: CaseIterable {
     case visible  // view is fully visible
     case invisible  // view is hidden but takes up space

Planet/Search/SearchView.swift

@@ -17,6 +17,7 @@ struct SearchView: View {
 
     @AppStorage("searchText") private var storedSearchText: String = ""
     @State private var searchTask: Task<Void, Never>?
+    @State private var scrollSettleGate = ListScrollSettleGate()
 
     @Environment(\.dismiss) private var dismiss
     private let searchEmptyAnchorID = "search-results-empty-anchor"
@@ -58,12 +59,18 @@ struct SearchView: View {
             ScrollViewReader { proxy in
                 searchResultView()
                     .onChange(of: result.map(\.articleID)) { _ in
+                        scrollSettleGate.noteContentChange()
                         Task { @MainActor in
                             await Task.yield()
-                            if let firstID = result.first?.articleID {
-                                proxy.scrollTo(firstID, anchor: .top)
-                            } else {
-                                proxy.scrollTo(searchEmptyAnchorID, anchor: .top)
+                            // Resolve the target when the scroll runs: on
+                            // macOS 12 the deferred scroll can fire after the
+                            // results have changed again.
+                            scrollSettleGate.perform {
+                                if let firstID = result.first?.articleID {
+                                    proxy.scrollTo(firstID, anchor: .top)
+                                } else {
+                                    proxy.scrollTo(searchEmptyAnchorID, anchor: .top)
+                                }
                             }
                         }
                         if let focusedResult, !result.contains(focusedResult) {
@@ -72,8 +79,10 @@ struct SearchView: View {
                     }
                     .onChange(of: focusedResult?.articleID) { id in
                         if let id = id {
-                            withAnimation(.easeInOut(duration: 0.12)) {
-                                proxy.scrollTo(id, anchor: .center)
+                            scrollSettleGate.perform {
+                                withAnimation(.easeInOut(duration: 0.12)) {
+                                    proxy.scrollTo(id, anchor: .center)
+                                }
                             }
                         }
                     }
@@ -95,6 +104,7 @@ struct SearchView: View {
             searchTask = nil
             isSearching = false
             storedSearchText = searchText
+            scrollSettleGate.cancel()
         }
     }
 

Planet/Views/Articles/ArticleListView.swift

@@ -461,16 +461,19 @@ struct ArticleListView: View {
     @State var articles: [ArticleModel]? = []
     @State private var pendingScrollArticleID: UUID?
     @State private var pendingScrollTask: Task<Void, Never>?
+    @State private var scrollSettleGate = ListScrollSettleGate()
 
     let articleDropDelegate = ArticleListDropDelegate()
 
     private func scrollToArticle(_ articleID: UUID, proxy: ScrollViewProxy, animated: Bool) {
-        if animated {
-            withAnimation {
+        scrollSettleGate.perform {
+            if animated {
+                withAnimation {
+                    proxy.scrollTo(articleID, anchor: .center)
+                }
+            } else {
                 proxy.scrollTo(articleID, anchor: .center)
             }
-        } else {
-            proxy.scrollTo(articleID, anchor: .center)
         }
     }
 
@@ -559,13 +562,18 @@ struct ArticleListView: View {
                             }.id(article.id)
                         }
                         .onReceive(NotificationCenter.default.publisher(for: .scrollToTopArticleList)) { n in
-                            if let article = viewModel.articles.first {
-                                debugPrint("Scrolling to top of Article List: \(article)")
-                                pendingScrollTask?.cancel()
-                                pendingScrollTask = nil
-                                pendingScrollArticleID = nil
-                                withAnimation {
-                                    proxy.scrollTo(article.id, anchor: .top)
+                            pendingScrollTask?.cancel()
+                            pendingScrollTask = nil
+                            pendingScrollArticleID = nil
+                            // Resolve the first article when the scroll runs:
+                            // on macOS 12 the deferred scroll can fire after
+                            // the list content is replaced.
+                            scrollSettleGate.perform {
+                                if let article = viewModel.articles.first {
+                                    debugPrint("Scrolling to top of Article List: \(article)")
+                                    withAnimation {
+                                        proxy.scrollTo(article.id, anchor: .top)
+                                    }
                                 }
                             }
                         }
@@ -585,6 +593,7 @@ struct ArticleListView: View {
                             }
                         }
                         .onChange(of: viewModel.articlesVersion) { _ in
+                            scrollSettleGate.noteContentChange()
                             guard pendingScrollArticleID != nil else {
                                 return
                             }
@@ -679,6 +688,7 @@ struct ArticleListView: View {
             pendingScrollTask?.cancel()
             pendingScrollTask = nil
             pendingScrollArticleID = nil
+            scrollSettleGate.cancel()
         }
     }
 }

Planet/Views/Sidebar/PlanetSidebarView.swift

@@ -16,6 +16,7 @@ struct PlanetSidebarView: View {
     @StateObject var ipfsState = IPFSState.shared
     @AppStorage(String.settingsAIIsReady) private var settingsAIIsReady: Bool = false
     @State private var isOnDeviceAIAvailable: Bool = false
+    @State private var scrollSettleGate = ListScrollSettleGate()
 
     let timer1m = Timer.publish(every: 60, on: .current, in: .common).autoconnect()
     let timer3m = Timer.publish(every: 180, on: .current, in: .common).autoconnect()
@@ -107,9 +108,17 @@ struct PlanetSidebarView: View {
                 .listStyle(.sidebar)
                 .onReceive(NotificationCenter.default.publisher(for: .scrollToSidebarItem)) { n in
                     if let id = n.object as? String {
-                        sidebarProxy.scrollTo(id, anchor: .center)
+                        scrollSettleGate.perform {
+                            sidebarProxy.scrollTo(id, anchor: .center)
+                        }
                     }
                 }
+                .onChange(of: planetStore.myPlanets.map(\.id)) { _ in
+                    scrollSettleGate.noteContentChange()
+                }
+                .onChange(of: planetStore.followingPlanets.map(\.id)) { _ in
+                    scrollSettleGate.noteContentChange()
+                }
             }
 
             Divider()

Planet/versioning.xcconfig

@@ -1 +1 @@
-CURRENT_PROJECT_VERSION = 2833
+CURRENT_PROJECT_VERSION = 2834