Fix compact composer controls and native scrolling (#2361)

* fix(app): refine compact composer controls and native scrolling Consolidate responsive agent controls and model browsing inside the compact sheet. Preserve manual native scrolling by suspending sticky bottom maintenance while the user owns the viewport. * fix(app): suppress recoverable resume refresh errors Resume revalidation can race host reconnection and reject while the host is offline. Treat the refresh as deferred so development LogBox does not surface a recoverable disconnect. * fix(app): stabilize compact model sheet loading Let the model list consume the sheet space above persistent controls as the sheet expands. Keep unresolved defaults in a loading state so Select model only represents a genuinely empty selection. * fix(app): preserve route anchors during native scroll * fix(app): preserve native scroll intent and sheet dismissal * fix(app): keep compact sheet styles composable
2026-07-24 00:24:10 +08:00
parent 8cf70d10bf
commit 8e063f0dfc
34 changed files with 3252 additions and 1806 deletions
@@ -1,4 +1,4 @@
-import { describe, expect, it, vi } from "vitest";
+import { describe, expect, it } from "vitest";
 import {
  __private__,
  deriveBottomAnchorBlockedReason,
@@ -126,10 +126,15 @@ function createDriverHarness(input?: {
    measurementState,
    nearBottom: input?.isNearBottom ?? true,
  };
-  const scrollToBottom = vi.fn(() => {
+  const scrollAttempts: boolean[] = [];
+  let scrollToBottomBehavior = () => {
    context.nearBottom = true;
    context.measurementState.offsetY = 720;
-  });
+  };
+  const scrollToBottom = (animated: boolean) => {
+    scrollAttempts.push(animated);
+    scrollToBottomBehavior();
+  };
  const modeChanges: BottomAnchorMode[] = [];
  const driver = __private__.createBottomAnchorControllerDriver({
    getAgentId: () => context.agentId,
@@ -150,7 +155,10 @@ function createDriverHarness(input?: {
    context,
    driver,
    scheduler,
-    scrollToBottom,
+    scrollAttempts,
+    setScrollToBottomBehavior(next: () => void) {
+      scrollToBottomBehavior = next;
+    },
    modeChanges,
  };
 }
@@ -210,7 +218,7 @@ describe("bottom anchor controller driver", () => {
    });
    harness.scheduler.flushAll();

-    expect(harness.scrollToBottom).not.toHaveBeenCalled();
+    expect(harness.scrollAttempts).toHaveLength(0);
    expect(harness.driver.getSnapshot()).toMatchObject({
      mode: "sticky-bottom",
      blockedReason: "waiting_for_history_readiness",
@@ -229,7 +237,7 @@ describe("bottom anchor controller driver", () => {
    harness.driver.reevaluate();
    harness.scheduler.flushAll();

-    expect(harness.scrollToBottom).toHaveBeenCalledTimes(1);
+    expect(harness.scrollAttempts).toHaveLength(1);
    expect(harness.driver.getSnapshot()).toMatchObject({
      blockedReason: null,
      pendingRequest: null,
@@ -237,6 +245,97 @@ describe("bottom anchor controller driver", () => {
    });
  });

+  it("preserves a blocked route anchor while a user scroll ends at the bottom", () => {
+    const harness = createDriverHarness({ authoritativeReady: false });
+
+    harness.driver.applyRouteRequest({
+      agentId: "agent-1",
+      reason: "initial-entry",
+      requestKey: "route:agent-1:initial-entry",
+    });
+    harness.scheduler.flushAll();
+
+    harness.driver.beginUserScroll();
+    harness.context.authoritativeReady = true;
+    harness.driver.notifyAuthoritativeHistoryMaybeChanged();
+    harness.driver.reevaluate();
+    harness.scheduler.flushAll();
+
+    expect(harness.scrollAttempts).toHaveLength(0);
+
+    harness.driver.endUserScroll({ isNearBottom: true });
+    harness.scheduler.flushAll();
+
+    expect(harness.scrollAttempts).toHaveLength(1);
+    expect(harness.driver.getSnapshot()).toMatchObject({
+      mode: "sticky-bottom",
+      blockedReason: null,
+      pendingRequest: null,
+      pendingVerification: null,
+    });
+  });
+
+  it("preserves a blocked route anchor when layout moves after drag release", () => {
+    const harness = createDriverHarness({ authoritativeReady: false });
+
+    harness.driver.applyRouteRequest({
+      agentId: "agent-1",
+      reason: "resume",
+      requestKey: "route:agent-1:resume",
+    });
+    harness.scheduler.flushAll();
+
+    harness.driver.beginUserScroll();
+    harness.context.nearBottom = false;
+    harness.driver.handleScrollNearBottomChange({
+      nextIsNearBottom: false,
+      scrollDelta: 0,
+    });
+    harness.context.authoritativeReady = true;
+    harness.driver.notifyAuthoritativeHistoryMaybeChanged();
+    harness.driver.endUserScroll({ isNearBottom: true });
+    harness.scheduler.flushAll();
+
+    expect(harness.scrollAttempts).toHaveLength(1);
+    expect(harness.driver.getSnapshot()).toMatchObject({
+      mode: "sticky-bottom",
+      blockedReason: null,
+      pendingRequest: null,
+      pendingVerification: null,
+    });
+  });
+
+  it("lets a user scroll away supersede a blocked route anchor", () => {
+    const harness = createDriverHarness({ authoritativeReady: false });
+
+    harness.driver.applyRouteRequest({
+      agentId: "agent-1",
+      reason: "resume",
+      requestKey: "route:agent-1:resume",
+    });
+    harness.scheduler.flushAll();
+
+    harness.driver.beginUserScroll();
+    harness.context.nearBottom = false;
+    harness.driver.handleScrollNearBottomChange({
+      nextIsNearBottom: false,
+      scrollDelta: 48,
+    });
+    harness.driver.endUserScroll({ isNearBottom: false });
+    harness.context.authoritativeReady = true;
+    harness.driver.notifyAuthoritativeHistoryMaybeChanged();
+    harness.driver.reevaluate();
+    harness.scheduler.flushAll();
+
+    expect(harness.scrollAttempts).toHaveLength(0);
+    expect(harness.driver.getSnapshot()).toMatchObject({
+      mode: "detached",
+      blockedReason: null,
+      pendingRequest: null,
+      pendingVerification: null,
+    });
+  });
+
  it("suppresses sticky maintenance while detached", () => {
    const harness = createDriverHarness();

@@ -254,7 +353,74 @@ describe("bottom anchor controller driver", () => {
    harness.scheduler.flushAll();

    expect(harness.driver.getSnapshot().mode).toBe("detached");
-    expect(harness.scrollToBottom).not.toHaveBeenCalled();
+    expect(harness.scrollAttempts).toHaveLength(0);
+  });
+
+  it("pauses sticky maintenance while a user scroll owns the viewport", () => {
+    const harness = createDriverHarness({
+      transportBehavior: {
+        verificationDelayFrames: 2,
+        verificationRetryMode: "recheck",
+      },
+    });
+
+    harness.driver.prepareForStickyContentChange();
+    harness.driver.beginUserScroll();
+    harness.driver.handleContentSizeChange({
+      previousContentHeight: 1200,
+      contentHeight: 1400,
+    });
+    harness.context.nearBottom = false;
+    harness.driver.handleScrollNearBottomChange({
+      nextIsNearBottom: false,
+      scrollDelta: 1,
+    });
+    harness.scheduler.flushAll();
+
+    expect(harness.scrollAttempts).toHaveLength(1);
+    expect(harness.driver.getSnapshot()).toMatchObject({
+      mode: "sticky-bottom",
+      pendingRequest: null,
+      pendingVerification: null,
+    });
+
+    harness.driver.endUserScroll({ isNearBottom: false });
+
+    expect(harness.driver.getSnapshot().mode).toBe("detached");
+  });
+
+  it("restores sticky maintenance when a user scroll returns to the bottom", () => {
+    const harness = createDriverHarness({
+      transportBehavior: {
+        verificationDelayFrames: 2,
+        verificationRetryMode: "recheck",
+      },
+    });
+
+    harness.driver.beginUserScroll();
+    harness.context.nearBottom = false;
+    harness.driver.handleScrollNearBottomChange({
+      nextIsNearBottom: false,
+      scrollDelta: 48,
+    });
+    harness.driver.handleContentSizeChange({
+      previousContentHeight: 1200,
+      contentHeight: 1400,
+    });
+    harness.context.nearBottom = true;
+    harness.driver.handleScrollNearBottomChange({
+      nextIsNearBottom: true,
+      scrollDelta: -48,
+    });
+    harness.driver.endUserScroll({ isNearBottom: true });
+    harness.scheduler.flushAll();
+
+    expect(harness.driver.getSnapshot()).toMatchObject({
+      mode: "sticky-bottom",
+      pendingRequest: null,
+      pendingVerification: null,
+    });
+    expect(harness.scrollAttempts).toHaveLength(1);
  });

  it("switches back to sticky-bottom for explicit jump-to-bottom", () => {
@@ -271,7 +437,7 @@ describe("bottom anchor controller driver", () => {

    expect(harness.modeChanges).toContain("detached");
    expect(harness.modeChanges).toContain("sticky-bottom");
-    expect(harness.scrollToBottom).toHaveBeenCalledTimes(1);
+    expect(harness.scrollAttempts).toHaveLength(1);
    expect(harness.driver.getSnapshot().mode).toBe("sticky-bottom");
  });

@@ -292,7 +458,7 @@ describe("bottom anchor controller driver", () => {
    });
    harness.scheduler.flushAll();

-    expect(harness.scrollToBottom).toHaveBeenCalledTimes(2);
+    expect(harness.scrollAttempts).toHaveLength(2);
  });

  it("keeps a pending request blocked when stale container measurements arrive", () => {
@@ -313,7 +479,7 @@ describe("bottom anchor controller driver", () => {
    });
    harness.scheduler.flushAll();

-    expect(harness.scrollToBottom).not.toHaveBeenCalled();
+    expect(harness.scrollAttempts).toHaveLength(0);
    expect(harness.driver.getSnapshot()).toMatchObject({
      blockedReason: "waiting_for_measurable_viewport",
      pendingRequest: {
@@ -326,7 +492,7 @@ describe("bottom anchor controller driver", () => {
    harness.driver.reevaluate();
    harness.scheduler.flushAll();

-    expect(harness.scrollToBottom).toHaveBeenCalledTimes(1);
+    expect(harness.scrollAttempts).toHaveLength(1);
    expect(harness.driver.getSnapshot().pendingRequest).toBeNull();
  });

@@ -338,7 +504,7 @@ describe("bottom anchor controller driver", () => {
      },
      isNearBottom: false,
    });
-    harness.scrollToBottom.mockImplementation(() => {
+    harness.setScrollToBottomBehavior(() => {
      harness.context.measurementState.offsetY = 0;
    });

@@ -348,16 +514,16 @@ describe("bottom anchor controller driver", () => {
    });

    harness.scheduler.flushFrame();
-    expect(harness.scrollToBottom).toHaveBeenCalledTimes(1);
+    expect(harness.scrollAttempts).toHaveLength(1);

    harness.scheduler.flushFrame();
    harness.scheduler.flushFrame();
-    expect(harness.scrollToBottom).toHaveBeenCalledTimes(1);
+    expect(harness.scrollAttempts).toHaveLength(1);

    harness.context.nearBottom = true;
    harness.scheduler.flushAll();

-    expect(harness.scrollToBottom).toHaveBeenCalledTimes(1);
+    expect(harness.scrollAttempts).toHaveLength(1);
    expect(harness.driver.getSnapshot().pendingRequest).toBeNull();
  });

@@ -375,7 +541,7 @@ describe("bottom anchor controller driver", () => {
      isNearBottom: false,
    });

-    harness.scrollToBottom.mockImplementation(() => {
+    harness.setScrollToBottomBehavior(() => {
      harness.context.measurementState.offsetY = 13476;
    });

@@ -386,7 +552,7 @@ describe("bottom anchor controller driver", () => {
    });

    harness.scheduler.flushFrame();
-    expect(harness.scrollToBottom).toHaveBeenCalledTimes(1);
+    expect(harness.scrollAttempts).toHaveLength(1);

    harness.context.measurementState.contentHeight = 14804;
    harness.context.nearBottom = false;
@@ -409,7 +575,7 @@ describe("bottom anchor controller driver", () => {

    harness.scheduler.flushFrame();

-    expect(harness.scrollToBottom).toHaveBeenCalledTimes(2);
+    expect(harness.scrollAttempts).toHaveLength(2);
    expect(harness.driver.getSnapshot()).toMatchObject({
      blockedReason: "waiting_for_post_layout_verification",
      pendingRequest: {
@@ -435,7 +601,7 @@ describe("bottom anchor controller driver", () => {
      isNearBottom: false,
    });

-    harness.scrollToBottom.mockImplementation(() => {
+    harness.setScrollToBottomBehavior(() => {
      harness.context.measurementState.offsetY = Math.max(
        0,
        harness.context.measurementState.contentHeight -
@@ -471,7 +637,7 @@ describe("bottom anchor controller driver", () => {
    harness.scheduler.flushFrame();
    harness.scheduler.flushFrame();

-    expect(harness.scrollToBottom).toHaveBeenCalledTimes(2);
+    expect(harness.scrollAttempts).toHaveLength(2);
    expect(harness.driver.getSnapshot().pendingRequest).toMatchObject({
      reason: "resume",
    });
@@ -480,7 +646,7 @@ describe("bottom anchor controller driver", () => {
  it("keeps sticky-bottom during viewport growth until bottom is re-verified", () => {
    const harness = createDriverHarness();
    harness.context.nearBottom = false;
-    harness.scrollToBottom.mockImplementation(() => {
+    harness.setScrollToBottomBehavior(() => {
      harness.context.measurementState.offsetY = 720;
    });

@@ -492,7 +658,7 @@ describe("bottom anchor controller driver", () => {
    });
    harness.scheduler.flushAll();

-    expect(harness.scrollToBottom).toHaveBeenCalledTimes(4);
+    expect(harness.scrollAttempts).toHaveLength(4);
    expect(harness.driver.getSnapshot()).toMatchObject({
      mode: "sticky-bottom",
      pendingRequest: null,
@@ -523,7 +689,7 @@ describe("bottom anchor controller driver", () => {
  it("keeps sticky-bottom during streaming growth until bottom is re-verified", () => {
    const harness = createDriverHarness();
    harness.context.nearBottom = false;
-    harness.scrollToBottom.mockImplementation(() => {
+    harness.setScrollToBottomBehavior(() => {
      harness.context.measurementState.offsetY = 900;
    });

@@ -533,7 +699,7 @@ describe("bottom anchor controller driver", () => {
    });
    harness.scheduler.flushAll();

-    expect(harness.scrollToBottom).toHaveBeenCalledTimes(4);
+    expect(harness.scrollAttempts).toHaveLength(4);
    expect(harness.driver.getSnapshot()).toMatchObject({
      mode: "sticky-bottom",
      pendingRequest: null,
@@ -577,7 +743,7 @@ describe("bottom anchor controller driver", () => {
        contentMeasuredForKey: null,
      }),
    });
-    harness.scrollToBottom.mockImplementation(() => {
+    harness.setScrollToBottomBehavior(() => {
      harness.context.measurementState.offsetY = 0;
    });

@@ -588,7 +754,7 @@ describe("bottom anchor controller driver", () => {
      contentHeight: 1348,
    });

-    expect(harness.scrollToBottom).toHaveBeenCalledTimes(1);
+    expect(harness.scrollAttempts).toHaveLength(1);
    expect(harness.driver.getSnapshot()).toMatchObject({
      mode: "sticky-bottom",
      pendingVerification: {
@@ -625,14 +791,14 @@ describe("bottom anchor controller driver", () => {
        contentMeasuredForKey: "native-virtualized",
      }),
    });
-    harness.scrollToBottom.mockImplementation(() => {
+    harness.setScrollToBottomBehavior(() => {
      harness.context.measurementState.offsetY = 0;
      harness.context.nearBottom = true;
    });

    harness.driver.prepareForStickyContentChange();

-    expect(harness.scrollToBottom).toHaveBeenCalledTimes(1);
+    expect(harness.scrollAttempts).toHaveLength(1);
    expect(harness.driver.getSnapshot()).toMatchObject({
      mode: "sticky-bottom",
      pendingVerification: {
@@ -68,6 +68,8 @@ interface BottomAnchorControllerDriver {
  resetForAgent: () => void;
  applyRouteRequest: (request: BottomAnchorRouteRequest | null) => void;
  requestLocalAnchor: (request: BottomAnchorLocalRequest) => void;
+  beginUserScroll: () => void;
+  endUserScroll: (params: { isNearBottom: boolean }) => void;
  detachByUser: () => void;
  handleViewportMetricsChange: (params: {
    previousViewportWidth: number;
@@ -243,6 +245,7 @@ function createBottomAnchorControllerDriver(
  let lastRouteRequestKey: string | null = null;
  let stickyMeasurementRevision = 0;
  let lastVerifiedStickyMeasurementRevision = 0;
+  let isUserScrollActive = false;

  const setBlockedReason = (nextBlockedReason: BottomAnchorBlockedReason | null) => {
    if (blockedReason === nextBlockedReason) {
@@ -411,10 +414,14 @@ function createBottomAnchorControllerDriver(
      | "viewport_change"
      | "content_size_change"
      | "scroll_near_bottom_change"
+      | "user_scroll_end"
      | "history_readiness_change"
      | "manual_reevaluate"
      | "retry_scroll",
  ) => {
+    if (isUserScrollActive) {
+      return;
+    }
    if (attemptHandle) {
      return;
    }
@@ -481,6 +488,7 @@ function createBottomAnchorControllerDriver(
      cancelPendingAttempt();
      stickyMeasurementRevision = 0;
      lastVerifiedStickyMeasurementRevision = 0;
+      isUserScrollActive = false;
      mode = "sticky-bottom";
      input.onModeChange("sticky-bottom");
    },
@@ -497,6 +505,38 @@ function createBottomAnchorControllerDriver(
    requestLocalAnchor(request) {
      createRequest(request);
    },
+    beginUserScroll() {
+      isUserScrollActive = true;
+      cancelPendingAttempt();
+    },
+    endUserScroll(params) {
+      isUserScrollActive = false;
+      if (params.isNearBottom) {
+        if (mode === "detached") {
+          setModeInternal("sticky-bottom");
+          pendingVerification = { requestId: null, retries: 0 };
+          evaluate(false, "user_scroll_end");
+          return;
+        }
+        if (pendingRequest) {
+          evaluate(false, "user_scroll_end");
+          return;
+        }
+        if (
+          !input.isNearBottom() ||
+          stickyMeasurementRevision !== lastVerifiedStickyMeasurementRevision
+        ) {
+          pendingVerification = { requestId: null, retries: 0 };
+          evaluate(false, "user_scroll_end");
+          return;
+        }
+        markStickyMeasurementVerified();
+        return;
+      }
+      if (mode === "sticky-bottom") {
+        this.detachByUser();
+      }
+    },
    detachByUser() {
      if (mode === "detached") {
        return;
@@ -511,6 +551,9 @@ function createBottomAnchorControllerDriver(
      ) {
        markStickyMeasurementChanged();
      }
+      if (isUserScrollActive) {
+        return;
+      }
      const shouldRestick = __private__.shouldRestickOnViewportChange({
        mode,
        previousViewportWidth: params.previousViewportWidth,
@@ -529,6 +572,9 @@ function createBottomAnchorControllerDriver(
      if (params.previousContentHeight !== params.contentHeight) {
        markStickyMeasurementChanged();
      }
+      if (isUserScrollActive) {
+        return;
+      }
      const shouldRestick = __private__.shouldRestickOnContentChange({
        mode,
        previousContentHeight: params.previousContentHeight,
@@ -558,6 +604,9 @@ function createBottomAnchorControllerDriver(
        return;
      }
      markStickyMeasurementChanged();
+      if (isUserScrollActive) {
+        return;
+      }
      if (!pendingRequest) {
        pendingVerification = { requestId: null, retries: 0 };
        if (attemptHandle) {
@@ -571,6 +620,9 @@ function createBottomAnchorControllerDriver(
    },
    handleScrollNearBottomChange(params) {
      const { nextIsNearBottom, scrollDelta } = params;
+      if (isUserScrollActive) {
+        return;
+      }
      if (
        nextIsNearBottom &&
        mode === "sticky-bottom" &&
@@ -737,6 +789,12 @@ export function useBottomAnchorController(input: {
    requestLocalAnchor(request: BottomAnchorLocalRequest) {
      driverRef.current?.requestLocalAnchor(request);
    },
+    beginUserScroll() {
+      driverRef.current?.beginUserScroll();
+    },
+    endUserScroll(params: { isNearBottom: boolean }) {
+      driverRef.current?.endUserScroll(params);
+    },
    detachByUser() {
      driverRef.current?.detachByUser();
    },
@@ -89,6 +89,8 @@ function NativeStreamViewport(props: StreamRenderInput & { strategy: StreamStrat
    contentMeasuredForKey: null as string | null,
  });
  const scrollOffsetYRef = useRef(0);
+  const isUserScrollActiveRef = useRef(false);
+  const userScrollEndFrameIdRef = useRef<number | null>(null);
  const programmaticScrollEventBudgetRef = useRef(0);
  const [isNativeViewportSettling, setIsNativeViewportSettling] = useState(false);
  const nativeViewportSettlingFrameIdRef = useRef<number | null>(null);
@@ -129,6 +131,13 @@ function NativeStreamViewport(props: StreamRenderInput & { strategy: StreamStrat
    }
  }, []);

+  const clearPendingUserScrollEnd = useCallback(() => {
+    if (userScrollEndFrameIdRef.current !== null) {
+      cancelAnimationFrame(userScrollEndFrameIdRef.current);
+      userScrollEndFrameIdRef.current = null;
+    }
+  }, []);
+
  const markNativeViewportSettling = useCallback(() => {
    clearNativeViewportSettling();
    setIsNativeViewportSettling(true);
@@ -208,6 +217,8 @@ function NativeStreamViewport(props: StreamRenderInput & { strategy: StreamStrat
      contentMeasuredForKey: null,
    };
    scrollOffsetYRef.current = 0;
+    isUserScrollActiveRef.current = false;
+    clearPendingUserScrollEnd();
    clearNativeViewportSettling();
    setIsNativeViewportSettling(false);
    historyStartReadyRef.current = false;
@@ -216,8 +227,9 @@ function NativeStreamViewport(props: StreamRenderInput & { strategy: StreamStrat
    });
    return () => {
      cancelAnimationFrame(frame);
+      clearPendingUserScrollEnd();
    };
-  }, [agentId, clearNativeViewportSettling]);
+  }, [agentId, clearNativeViewportSettling, clearPendingUserScrollEnd]);

  useEffect(() => {
    const keyboardEvents = [
@@ -266,6 +278,19 @@ function NativeStreamViewport(props: StreamRenderInput & { strategy: StreamStrat
    };
  }, [agentId, bottomAnchorController, markNativeViewportSettling, viewportRef]);

+  const isScrollEventNearBottom = useStableEvent(
+    (event: NativeSyntheticEvent<NativeScrollEvent>) => {
+      const { contentOffset, contentSize, layoutMeasurement } = event.nativeEvent;
+      return isNearBottomForStreamRenderStrategy({
+        strategy,
+        offsetY: contentOffset.y,
+        threshold: 32,
+        contentHeight: contentSize.height,
+        viewportHeight: layoutMeasurement.height,
+      });
+    },
+  );
+
  const handleScroll = useStableEvent((event: NativeSyntheticEvent<NativeScrollEvent>) => {
    const { contentOffset, contentSize, layoutMeasurement } = event.nativeEvent;
    const previousOffsetY = scrollOffsetYRef.current;
@@ -280,13 +305,7 @@ function NativeStreamViewport(props: StreamRenderInput & { strategy: StreamStrat
      contentMeasuredForKey: "native-virtualized",
    };

-    const nearBottom = isNearBottomForStreamRenderStrategy({
-      strategy,
-      offsetY: contentOffset.y,
-      threshold: 32,
-      contentHeight: streamViewportMetricsRef.current.contentHeight,
-      viewportHeight: streamViewportMetricsRef.current.viewportHeight,
-    });
+    const nearBottom = isScrollEventNearBottom(event);
    onNearBottomChange(nearBottom);

    const distanceFromOldestEdge =
@@ -301,7 +320,11 @@ function NativeStreamViewport(props: StreamRenderInput & { strategy: StreamStrat
      onNearHistoryStart();
    }

-    if (programmaticScrollEventBudgetRef.current > 0 && contentOffset.y <= 8) {
+    if (
+      !isUserScrollActiveRef.current &&
+      programmaticScrollEventBudgetRef.current > 0 &&
+      contentOffset.y <= 8
+    ) {
      programmaticScrollEventBudgetRef.current -= 1;
    } else {
      programmaticScrollEventBudgetRef.current = 0;
@@ -312,6 +335,37 @@ function NativeStreamViewport(props: StreamRenderInput & { strategy: StreamStrat
    }
  });

+  const handleScrollBeginDrag = useStableEvent(() => {
+    clearPendingUserScrollEnd();
+    isUserScrollActiveRef.current = true;
+    bottomAnchorController.beginUserScroll();
+  });
+
+  // Defer drag end so momentum can take ownership, but capture the terminal
+  // gesture position now because layout may move the viewport in the meantime.
+  const handleScrollEndDrag = useStableEvent((event: NativeSyntheticEvent<NativeScrollEvent>) => {
+    const isNearBottom = isScrollEventNearBottom(event);
+    clearPendingUserScrollEnd();
+    userScrollEndFrameIdRef.current = requestAnimationFrame(() => {
+      userScrollEndFrameIdRef.current = null;
+      isUserScrollActiveRef.current = false;
+      bottomAnchorController.endUserScroll({ isNearBottom });
+    });
+  });
+
+  const handleMomentumScrollBegin = useStableEvent(() => {
+    clearPendingUserScrollEnd();
+  });
+
+  const handleMomentumScrollEnd = useStableEvent(
+    (event: NativeSyntheticEvent<NativeScrollEvent>) => {
+      const isNearBottom = isScrollEventNearBottom(event);
+      clearPendingUserScrollEnd();
+      isUserScrollActiveRef.current = false;
+      bottomAnchorController.endUserScroll({ isNearBottom });
+    },
+  );
+
  const handleListLayout = useStableEvent((event: LayoutChangeEvent) => {
    const previousViewportWidth = streamViewportMetricsRef.current.viewportWidth;
    const previousViewportHeight = streamViewportMetricsRef.current.viewportHeight;
@@ -419,6 +473,10 @@ function NativeStreamViewport(props: StreamRenderInput & { strategy: StreamStrat
      style={listStyle}
      onLayout={handleListLayout}
      onScroll={handleScroll}
+      onScrollBeginDrag={handleScrollBeginDrag}
+      onScrollEndDrag={handleScrollEndDrag}
+      onMomentumScrollBegin={handleMomentumScrollBegin}
+      onMomentumScrollEnd={handleMomentumScrollEnd}
      scrollEventThrottle={16}
      onContentSizeChange={handleContentSizeChange}
      maintainVisibleContentPosition={maintainVisibleContentPosition}