fix(message-list): keep bottom anchor sticky through tall-card layout settle

A tall card (Edit diff, Bash output) that lays out in one frame grows the
content height while the throttled/async scroll-to-bottom is still pending,
leaving distanceFromBottom huge. A non-user-driven stable geometry frame in
that window would recompute isNearBottom to false even though the user never
scrolled, causing the pending auto-scroll to bail and stranding the view above
the bottom.

Gate the un-stick recompute in MessageListScrollAnchor.apply on a new
isUserDriven flag so only a genuine user scroll releases the anchor; layout
settles keep it sticky. Preserves the "only follow the bottom while at the
bottom" semantics.

Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>

Author: sirily11

Packages/Sources/MessageList/MessageList.swift

@@ -277,7 +277,8 @@ public struct MessageList<Message: MessageListItem, RowContent: View>: View {
     private func handleScrollMetrics(_ metrics: MessageListScrollMetrics, proxy: ScrollViewProxy) {
         let decision = anchor.apply(
             contentHeight: metrics.contentHeight,
-            visibleMaxY: metrics.visibleMaxY
+            visibleMaxY: metrics.visibleMaxY,
+            isUserDriven: isUserDrivenScroll
         )
         updateIsAtBottomBinding(anchor.isNearBottom)
 

Packages/Sources/MessageList/MessageListScrollAnchor.swift

@@ -18,8 +18,14 @@ nonisolated struct MessageListScrollAnchor: Equatable {
         self.hasReceivedFirstUpdate = false
     }
 
+    /// Apply a new scroll geometry sample.
+    ///
+    /// `isUserDriven` reports whether the change is driven by the user's finger /
+    /// trackpad (or post-flick glide) rather than by layout or a programmatic
+    /// scroll. It gates the only branch that can *un-stick* the anchor — see
+    /// below for why that matters.
     @discardableResult
-    mutating func apply(contentHeight: CGFloat, visibleMaxY: CGFloat) -> Decision {
+    mutating func apply(contentHeight: CGFloat, visibleMaxY: CGFloat, isUserDriven: Bool) -> Decision {
         let distanceFromBottom = max(0, contentHeight - visibleMaxY)
         let nowNearBottom = distanceFromBottom < threshold
 
@@ -39,6 +45,17 @@ nonisolated struct MessageListScrollAnchor: Equatable {
             return previouslyNearBottom ? .scrollToBottom : .none
         }
 
+        // Content stable (or shrunk). Recomputing `isNearBottom` from the raw
+        // distance is the ONLY path that can un-stick the anchor, so it must
+        // only run for a genuine user scroll. A tall card (Edit diff, Bash
+        // output, etc.) that lays out in one frame leaves `distanceFromBottom`
+        // huge until the throttled/async scroll-to-bottom executes; a layout
+        // settle that lands in that window would otherwise recompute
+        // `isNearBottom` to false even though the user never scrolled — which
+        // then makes the pending auto-scroll bail and strands the view above
+        // the bottom. Gating on `isUserDriven` keeps the anchor sticky through
+        // that settle while still letting a deliberate scroll up release it.
+        guard isUserDriven else { return .none }
         isNearBottom = nowNearBottom
         return .none
     }

Packages/Tests/MessageListTests/MessageListScrollAnchorTests.swift

@@ -7,9 +7,9 @@ struct MessageListScrollAnchorTests {
     @Test("Content growth while anchored requests bottom scroll")
     func contentGrowthWhileAnchoredRequestsBottomScroll() {
         var anchor = MessageListScrollAnchor(threshold: 120)
-        _ = anchor.apply(contentHeight: 1000, visibleMaxY: 1000)
+        _ = anchor.apply(contentHeight: 1000, visibleMaxY: 1000, isUserDriven: false)
 
-        let decision = anchor.apply(contentHeight: 1400, visibleMaxY: 1000)
+        let decision = anchor.apply(contentHeight: 1400, visibleMaxY: 1000, isUserDriven: false)
 
         #expect(decision == .scrollToBottom)
         #expect(anchor.isNearBottom)
@@ -18,10 +18,11 @@ struct MessageListScrollAnchorTests {
     @Test("Content growth while scrolled up does not re-anchor")
     func contentGrowthWhileScrolledUpDoesNotReanchor() {
         var anchor = MessageListScrollAnchor(threshold: 120)
-        _ = anchor.apply(contentHeight: 1000, visibleMaxY: 1000)
-        _ = anchor.apply(contentHeight: 1000, visibleMaxY: 600)
+        _ = anchor.apply(contentHeight: 1000, visibleMaxY: 1000, isUserDriven: false)
+        // User scrolls up — a user-driven stable frame un-sticks the anchor.
+        _ = anchor.apply(contentHeight: 1000, visibleMaxY: 600, isUserDriven: true)
 
-        let decision = anchor.apply(contentHeight: 1400, visibleMaxY: 600)
+        let decision = anchor.apply(contentHeight: 1400, visibleMaxY: 600, isUserDriven: false)
 
         #expect(decision == .none)
         #expect(!anchor.isNearBottom)
@@ -30,12 +31,48 @@ struct MessageListScrollAnchorTests {
     @Test("Reset restores bottom anchoring")
     func resetRestoresBottomAnchoring() {
         var anchor = MessageListScrollAnchor(threshold: 120)
-        _ = anchor.apply(contentHeight: 1000, visibleMaxY: 1000)
-        _ = anchor.apply(contentHeight: 1000, visibleMaxY: 500)
+        _ = anchor.apply(contentHeight: 1000, visibleMaxY: 1000, isUserDriven: false)
+        _ = anchor.apply(contentHeight: 1000, visibleMaxY: 500, isUserDriven: true)
         #expect(!anchor.isNearBottom)
 
         anchor.resetToBottom()
 
         #expect(anchor.isNearBottom)
     }
+
+    @Test("Tall card layout settle does not un-stick the anchor")
+    func tallCardLayoutSettleKeepsAnchorSticky() {
+        var anchor = MessageListScrollAnchor(threshold: 120)
+        // User is following the bottom.
+        _ = anchor.apply(contentHeight: 1000, visibleMaxY: 1000, isUserDriven: false)
+
+        // A tall Edit card lays out in one frame: content grows but the visible
+        // rect hasn't been re-anchored yet, so distance is huge. Still sticky;
+        // schedules a scroll-to-bottom.
+        let growth = anchor.apply(contentHeight: 1800, visibleMaxY: 1000, isUserDriven: false)
+        #expect(growth == .scrollToBottom)
+        #expect(anchor.isNearBottom)
+
+        // Before the (async/throttled) scroll executes, a *non*-user-driven
+        // stable frame arrives while distance is still huge. This must NOT
+        // un-stick the anchor — otherwise the pending auto-scroll bails and the
+        // view is stranded above the bottom.
+        let settle = anchor.apply(contentHeight: 1800, visibleMaxY: 1000, isUserDriven: false)
+        #expect(settle == .none)
+        #expect(anchor.isNearBottom)
+    }
+
+    @Test("User scroll up still releases the anchor after a tall card")
+    func userScrollUpReleasesAnchorAfterTallCard() {
+        var anchor = MessageListScrollAnchor(threshold: 120)
+        _ = anchor.apply(contentHeight: 1000, visibleMaxY: 1000, isUserDriven: false)
+        _ = anchor.apply(contentHeight: 1800, visibleMaxY: 1000, isUserDriven: false)
+        // Layout settles to the bottom (visible rect now catches up).
+        _ = anchor.apply(contentHeight: 1800, visibleMaxY: 1800, isUserDriven: false)
+        #expect(anchor.isNearBottom)
+
+        // User deliberately scrolls up.
+        _ = anchor.apply(contentHeight: 1800, visibleMaxY: 1200, isUserDriven: true)
+        #expect(!anchor.isNearBottom)
+    }
 }