improvement(mothership): net-zero settle — equal tail regions, drained floor, one growth signal

Author: TheodoreSpeaks

apps/sim/app/workspace/[workspaceId]/home/components/message-content/message-content.tsx

@@ -30,6 +30,13 @@ import { deriveMessagePhase, isToolDone, type MessagePhase } from './utils'
 const FILE_SUBAGENT_ID = 'file'
 /** Quiet period before the shimmer takes the slot back from streamed output. */
 const STREAM_IDLE_DELAY_MS = 1_500
+/**
+ * The one vertical extent (10px gap + 36px row) every tail-region occupant —
+ * shimmer slot, actions row, stopped row — must share. The settle swap is only
+ * jump-free because these are equal; changing one side without the others
+ * reintroduces a scroll clamp at end of turn.
+ */
+const TAIL_REGION_CLASSES = 'mt-[10px] flex h-[36px] items-center'
 
 interface TextSegment {
   type: 'text'
@@ -956,8 +963,8 @@ function MessageContentInner({
         // Fixed-height placeholder for the NEXT piece of output: the shimmer
         // and arriving output trade places via opacity only, so mid-turn swaps
         // can't move layout. A sibling of the space-y stack (not a child), so
-        // it carries no stray sibling margin — pt-[10px] is its own gap.
-        <div aria-hidden={!showShimmer} className='pt-[10px]'>
+        // it carries no stray sibling margin.
+        <div aria-hidden={!showShimmer} className={TAIL_REGION_CLASSES}>
           <div
             className={cn(
               'transition-opacity duration-200 ease-out',
@@ -968,17 +975,17 @@ function MessageContentInner({
           </div>
         </div>
       ) : (
-        // Stopped row and actions take the slot's place in the SAME render — a
-        // single small reflow instead of a collapse the buttons would ride
-        // upward or a late mount the chase would visibly scroll to.
+        // Stopped row and actions take the slot's place in the SAME render and
+        // at the SAME extent (TAIL_REGION_CLASSES), so the swap is height-
+        // neutral by construction — no reflow for the pinned scroller to absorb.
         <>
           {lastSegment?.type === 'stopped' && (
-            <div className='flex items-center gap-[8px] pt-[10px]'>
+            <div className={cn(TAIL_REGION_CLASSES, 'gap-[8px]')}>
               <CircleStop className='size-[16px] flex-shrink-0 text-[var(--text-icon)]' />
               <span className='text-[14px] text-[var(--text-body)]'>Stopped by user</span>
             </div>
           )}
-          {actions && <div className='mt-[10px]'>{actions}</div>}
+          {actions && <div className={TAIL_REGION_CLASSES}>{actions}</div>}
         </>
       )}
     </div>

apps/sim/app/workspace/[workspaceId]/home/components/mothership-chat/mothership-chat.tsx

@@ -12,6 +12,7 @@ import {
 } from 'react'
 import { cn } from '@sim/emcn'
 import { defaultRangeExtractor, type Range, useVirtualizer } from '@tanstack/react-virtual'
+import { SMOOTH_CHASE_RATE } from '@/lib/core/utils/smooth-bottom-chase'
 import { MessageActions } from '@/app/workspace/[workspaceId]/components'
 import { ChatMessageAttachments } from '@/app/workspace/[workspaceId]/home/components/chat-message-attachments'
 import { ChatSurfaceProvider } from '@/app/workspace/[workspaceId]/home/components/chat-surface-context'
@@ -109,7 +110,7 @@ const UNSCROLLED = Symbol('unscrolled')
 const LAYOUT_STYLES = {
   'mothership-view': {
     scrollContainer:
-      'min-h-0 flex-1 overflow-y-auto overflow-x-hidden px-6 pt-4 pb-2 [scrollbar-gutter:stable_both-edges]',
+      'min-h-0 flex-1 overflow-y-auto overflow-x-hidden px-6 pt-4 pb-2 [overflow-anchor:none] [scrollbar-gutter:stable_both-edges]',
     sizer: 'relative mx-auto w-full max-w-[48rem]',
     rowGap: 'pb-6',
     userRow: 'flex flex-col items-end gap-[6px] pt-3',
@@ -120,7 +121,8 @@ const LAYOUT_STYLES = {
     footerInner: 'mx-auto max-w-[48rem]',
   },
   'copilot-view': {
-    scrollContainer: 'min-h-0 flex-1 overflow-y-auto overflow-x-hidden px-3 pt-2 pb-4',
+    scrollContainer:
+      'min-h-0 flex-1 overflow-y-auto overflow-x-hidden px-3 pt-2 pb-4 [overflow-anchor:none]',
     sizer: 'relative w-full',
     rowGap: 'pb-4',
     userRow: 'flex flex-col items-end gap-[6px] pt-2',
@@ -315,6 +317,7 @@ export function MothershipChat({
   const sizerRef = useRef<HTMLDivElement | null>(null)
   const scrollerPaddingRef = useRef<{ top: number; bottom: number } | null>(null)
   const sizerFloorAppliedRef = useRef(0)
+  const floorDrainRafRef = useRef(0)
 
   /**
    * Sizer floor while streaming: `scrollHeight` must never dip below the
@@ -331,17 +334,44 @@ export function MothershipChat({
    * Active on the same signal as auto-scroll: the reveal keeps re-parsing
    * markdown (and shrinking) after the network stream closes, so the floor
    * must hold through `lastRowAnimating` too.
+   *
+   * Release is DRAINED, not cliffed: while active the floor forbids
+   * scrollHeight from dropping, so permanent shrinks over the turn accrue as
+   * phantom space (debt). Clearing min-height in one commit released that
+   * whole debt as a single clamp — the end-of-turn downward jump. Instead the
+   * floor glides down to the natural size at the chase's rate; the browser's
+   * clamp follows a few px per frame, which reads as the same eased settle as
+   * the rest of the stream. Instant-clears when the debt is sub-pixel or the
+   * user isn't pinned (shrinking below-viewport space is invisible then).
    */
   const floorActive = isStreamActive || lastRowAnimating
   useLayoutEffect(() => {
     const sizer = sizerRef.current
     const el = scrollElementRef.current
     if (!sizer || !el) return
     if (!floorActive) {
-      sizerFloorAppliedRef.current = 0
-      sizer.style.minHeight = ''
+      if (sizerFloorAppliedRef.current === 0) return
+      scrollerPaddingRef.current = null
+      const pinned = el.scrollHeight - el.scrollTop - el.clientHeight <= 2
+      cancelAnimationFrame(floorDrainRafRef.current)
+      const drain = () => {
+        const target = virtualizer.getTotalSize()
+        const current = sizerFloorAppliedRef.current
+        if (current === 0) return
+        const next = Math.floor(current - Math.max(1, (current - target) * SMOOTH_CHASE_RATE))
+        if (!pinned || next - target <= 1) {
+          sizerFloorAppliedRef.current = 0
+          sizer.style.minHeight = ''
+          return
+        }
+        sizerFloorAppliedRef.current = next
+        sizer.style.minHeight = `${next}px`
+        floorDrainRafRef.current = requestAnimationFrame(drain)
+      }
+      drain()
       return
     }
+    cancelAnimationFrame(floorDrainRafRef.current)
     if (!scrollerPaddingRef.current) {
       const style = getComputedStyle(el)
       scrollerPaddingRef.current = {

apps/sim/hooks/use-auto-scroll.ts

@@ -25,22 +25,6 @@ const USER_GESTURE_WINDOW = 250
  * in the listener) is the other upward shortcut; plain `Space` pages down.
  */
 const SCROLL_UP_KEYS = new Set(['ArrowUp', 'PageUp', 'Home'])
-/** How long to keep chasing the bottom while a CSS height animation plays. */
-const ANIMATION_FOLLOW_WINDOW = 500
-/**
- * How long to keep chasing the bottom after streaming stops. End-of-turn content
- * mounts just after `isStreaming` flips false — the suggested-follow-up options,
- * the actions row (swapped into the thinking slot's place), and the
- * virtualizer's re-measure of the grown row — so a single final scroll fires
- * before it lays out and leaves it clipped behind the input. Following for a
- * short window pulls it into view.
- */
-const POST_STREAM_SETTLE_WINDOW = 300
-
-interface UseAutoScrollOptions {
-  scrollOnMount?: boolean
-}
-
 /**
  * Manages sticky auto-scroll for a streaming chat container.
  *
@@ -50,23 +34,18 @@ interface UseAutoScrollOptions {
  * of the bottom to re-engage. Each streaming start re-seeds stickiness from the
  * current scroll position, so a user who scrolled up beforehand stays put.
  *
- * Returns `ref` (callback ref for the scroll container), `scrollToBottom` for
- * imperative use after layout-changing events like panel expansion, and
- * `detach` for programmatic freezes (a user stop) — it parks every chase path
- * exactly like a user scroll-away, until the user scrolls back to the bottom
- * or the next stream re-seeds stickiness.
+ * Returns `ref` (callback ref for the scroll container) and `detach` for
+ * programmatic freezes (a user stop) — it parks every chase path exactly like
+ * a user scroll-away, until the user scrolls back to the bottom or the next
+ * stream re-seeds stickiness.
  */
-export function useAutoScroll(
-  isStreaming: boolean,
-  { scrollOnMount = false }: UseAutoScrollOptions = {}
-) {
+export function useAutoScroll(isStreaming: boolean) {
   const containerRef = useRef<HTMLDivElement>(null)
   const stickyRef = useRef(true)
   const userDetachedRef = useRef(false)
   const prevScrollTopRef = useRef(0)
   const prevScrollHeightRef = useRef(0)
   const touchStartYRef = useRef(0)
-  const scrollOnMountRef = useRef(scrollOnMount)
   /**
    * Whether the user is actively dragging the scrollbar — a pointer press on the
    * container itself rather than its content. Reset on teardown so a pointer held
@@ -80,20 +59,13 @@ export function useAutoScroll(
    */
   const lastUserGestureAtRef = useRef(Number.NEGATIVE_INFINITY)
 
-  const scrollToBottom = useCallback(() => {
-    const el = containerRef.current
-    if (!el) return
-    el.scrollTop = el.scrollHeight
-  }, [])
-
   const detach = useCallback(() => {
     stickyRef.current = false
     userDetachedRef.current = true
   }, [])
 
   const callbackRef = useCallback((el: HTMLDivElement | null) => {
     containerRef.current = el
-    if (el && scrollOnMountRef.current) el.scrollTop = el.scrollHeight
   }, [])
 
   useEffect(() => {
@@ -198,42 +170,38 @@ export function useAutoScroll(
       prevScrollHeightRef.current = scrollHeight
     }
 
-    const onMutation = () => {
+    /**
+     * The single growth signal: the transcript sizer's height. Every source of
+     * scrollHeight growth flows through it — virtualizer re-measures per
+     * streamed token, CSS height animations (each frame re-measures the row),
+     * the sizer min-height floor — so one ResizeObserver replaces a subtree
+     * MutationObserver plus an `animationstart` deadline machine, and there is
+     * exactly one reason the chase ever runs.
+     */
+    const sizer = el.firstElementChild
+    const onSizerResize = () => {
       prevScrollHeightRef.current = el.scrollHeight
       if (!stickyRef.current) return
       chase.kick()
     }
 
-    /**
-     * CSS-driven height animations (e.g. Radix Collapsible expanding mid-stream)
-     * grow scrollHeight without triggering MutationObserver, so auto-scroll stops
-     * following. Keep the one chase loop alive for a short window so the
-     * container stays pinned while the animation runs. `animationstart` fires
-     * for every child animation in the transcript (segment fade-ins, loader
-     * keyframes, label crossfades) — kickUntil coalesces them into a single
-     * extended deadline on the single loop; anything more snaps the glide.
-     */
-    const onAnimationStart = () => chase.kickUntil(ANIMATION_FOLLOW_WINDOW)
-
     el.addEventListener('wheel', onWheel, { passive: true })
     el.addEventListener('touchstart', onTouchStart, { passive: true })
     el.addEventListener('touchmove', onTouchMove, { passive: true })
     el.addEventListener('scroll', onScroll, { passive: true })
-    el.addEventListener('animationstart', onAnimationStart)
     el.addEventListener('pointerdown', onPointerDown, { passive: true })
     el.addEventListener('keydown', onKeyDown, { passive: true })
     window.addEventListener('pointerup', onPointerUp, { passive: true })
     window.addEventListener('pointercancel', onPointerUp, { passive: true })
 
-    const observer = new MutationObserver(onMutation)
-    observer.observe(el, { childList: true, subtree: true, characterData: true })
+    const observer = new ResizeObserver(onSizerResize)
+    if (sizer) observer.observe(sizer)
 
     return () => {
       el.removeEventListener('wheel', onWheel)
       el.removeEventListener('touchstart', onTouchStart)
       el.removeEventListener('touchmove', onTouchMove)
       el.removeEventListener('scroll', onScroll)
-      el.removeEventListener('animationstart', onAnimationStart)
       el.removeEventListener('pointerdown', onPointerDown)
       el.removeEventListener('keydown', onKeyDown)
       window.removeEventListener('pointerup', onPointerUp)
@@ -242,13 +210,13 @@ export function useAutoScroll(
       chase.cancel()
       pointerDownRef.current = false
       lastUserGestureAtRef.current = Number.NEGATIVE_INFINITY
-      // End-of-turn content mounts just after teardown; follow it briefly. The
-      // chase's own upward-move interrupt still protects a real user scroll
-      // even with the gesture listeners gone, and the per-frame sticky check
-      // makes this a no-op after a detach().
-      chase.kickUntil(POST_STREAM_SETTLE_WINDOW)
+      // Teardown can land mid-glide (options mounted late in the reveal, gap
+      // not yet closed) — canceling there strands the follow-ups behind the
+      // input. One plain kick runs the loop to rest and parks; a stopped turn
+      // stays frozen because the detached sticky check parks it on frame one.
+      chase.kick()
     }
-  }, [isStreaming, scrollToBottom])
+  }, [isStreaming])
 
-  return { ref: callbackRef, scrollToBottom, detach }
+  return { ref: callbackRef, detach }
 }

apps/sim/lib/core/utils/smooth-bottom-chase.ts

@@ -26,14 +26,6 @@ export interface SmoothBottomChaseHandle {
   isActive: () => boolean
   /** Start the loop if parked. Call after content growth. */
   kick: () => void
-  /**
-   * Keep the loop alive for `durationMs` even while the gap is at rest,
-   * re-checking every frame. Covers growth that arrives over several frames
-   * with no observable trigger — a CSS height animation, or a virtualizer
-   * re-measure settling after streaming stops. Repeat calls extend the
-   * deadline; there is never more than one loop.
-   */
-  kickUntil: (durationMs: number) => void
   cancel: () => void
 }
 
@@ -55,15 +47,11 @@ export function createSmoothBottomChase(
 ): SmoothBottomChaseHandle {
   let raf: number | null = null
   let lastTop: number | null = null
-  let deadline = 0
 
   const park = () => {
     if (raf !== null) cancelAnimationFrame(raf)
     raf = null
     lastTop = null
-    // A stale deadline must not leak into a later plain kick() — kick alone
-    // parks at rest, only a live kickUntil window idles through it.
-    deadline = 0
   }
 
   const step = () => {
@@ -83,14 +71,7 @@ export function createSmoothBottomChase(
     }
     const gap = target.getBottomTop() - top
     if (gap <= CHASE_REST_GAP) {
-      // Within a kickUntil deadline the loop idles at rest instead of parking,
-      // so growth in the deadline window is chased without a fresh trigger.
-      if (performance.now() >= deadline) {
-        park()
-        return
-      }
-      lastTop = top
-      raf = requestAnimationFrame(step)
+      park()
       return
     }
     target.setTop(top + Math.max(1, gap * SMOOTH_CHASE_RATE))
@@ -105,8 +86,7 @@ export function createSmoothBottomChase(
    * Seed the upward-move interrupt baseline at (re)start so a user scroll-up
    * between the kick and the first frame parks the loop immediately — without
    * it the first step has no baseline and writes one downward frame against
-   * the user (relevant on the teardown kickUntil, where the gesture listeners
-   * are already gone).
+   * the user.
    */
   const start = () => {
     if (raf !== null) return
@@ -117,10 +97,6 @@ export function createSmoothBottomChase(
   return {
     isActive: () => raf !== null,
     kick: start,
-    kickUntil: (durationMs: number) => {
-      deadline = Math.max(deadline, performance.now() + durationMs)
-      start()
-    },
     cancel: park,
   }
 }