From fb91d80325bb2159286663ace7f45f8405a80a16 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Pascal=20Andr=C3=A9?= <pascalandr@gmail.com>
Date: Fri, 8 May 2026 14:37:41 +0200
Subject: [PATCH 1/4] fix(ui): stabilize virtual follow autoscroll

Keep DOM and Virtua timing in VirtualFollowList while moving pure follow and hold transitions into a colocated behavior module with focused tests. The integration restores hidden session scroll snapshots safely, gates streaming magnetization on active streaming and hold state, and preserves explicit latest/submit bottom jumps without reintroducing fast-down heuristics.

Use Virtua offsets for scroll snapshots and decide streaming rejoin from the item at the bottom of the viewport so long assistant messages can still magnetize near their tail without using stale top-of-viewport position. Remove the unused generic scroll cache hook now that message scroll restore is handled by the virtual follow integration.

Validation: node --test packages/ui/src/components/virtual-follow-behavior.test.ts, npm run typecheck --workspace @codenomad/ui, npm run build --workspace @codenomad/tauri-app, and manual release-exe testing.
---
 packages/ui/src/components/message-block.tsx  |   8 +
 .../ui/src/components/message-section.tsx     | 131 +++-
 .../src/components/session/session-view.tsx   | 172 ++++--
 .../virtual-follow-behavior.test.ts           | 248 ++++++++
 .../src/components/virtual-follow-behavior.ts | 307 +++++++++
 .../ui/src/components/virtual-follow-list.tsx | 583 +++++++++++++++---
 packages/ui/src/lib/hooks/use-scroll-cache.ts | 102 ---
 packages/ui/src/stores/message-v2/types.ts    |   4 +
 8 files changed, 1255 insertions(+), 300 deletions(-)
 create mode 100644 packages/ui/src/components/virtual-follow-behavior.test.ts
 create mode 100644 packages/ui/src/components/virtual-follow-behavior.ts
 delete mode 100644 packages/ui/src/lib/hooks/use-scroll-cache.ts

diff --git a/packages/ui/src/components/message-block.tsx b/packages/ui/src/components/message-block.tsx
index 04c15e7ac..4b5e97f18 100644
--- a/packages/ui/src/components/message-block.tsx
+++ b/packages/ui/src/components/message-block.tsx
@@ -1004,6 +1004,7 @@ export default function MessageBlock(props: MessageBlockProps) {
                     onDeleteMessagesUpTo={props.onDeleteMessagesUpTo}
                     selectedMessageIds={props.selectedMessageIds}
                     onToggleSelectedMessage={props.onToggleSelectedMessage}
+                    onContentRendered={props.onContentRendered}
                   />
                 </Match>
                 <Match when={item().type === "compaction"}>
@@ -1063,6 +1064,7 @@ interface StepCardProps {
   onDeleteMessagesUpTo?: (messageId: string) => void | Promise<void>
   selectedMessageIds?: () => Set<string>
   onToggleSelectedMessage?: (messageId: string, selected: boolean) => void
+  onContentRendered?: () => void
 }
 
 interface CompactionCardProps {
@@ -1245,6 +1247,12 @@ function StepCard(props: StepCardProps) {
 
   const finishStyle = () => (props.borderColor ? { "border-left-color": props.borderColor } : undefined)
 
+  createEffect(() => {
+    if (props.kind !== "finish") return
+    if (!usageStats()) return
+    props.onContentRendered?.()
+  })
+
   const canDeleteMessage = () =>
     Boolean(props.showDeleteMessage && props.instanceId && props.sessionId && props.messageId) && !deletingMessage()
 
diff --git a/packages/ui/src/components/message-section.tsx b/packages/ui/src/components/message-section.tsx
index f2cc7abbb..6a2e42551 100644
--- a/packages/ui/src/components/message-section.tsx
+++ b/packages/ui/src/components/message-section.tsx
@@ -4,12 +4,11 @@ import Kbd from "./kbd"
 import MessageBlock from "./message-block"
 import { getMessageAnchorId, getMessageIdFromAnchorId } from "./message-anchors"
 import MessageTimeline, { buildTimelineSegments, type TimelineSegment } from "./message-timeline"
-import VirtualFollowList, { type VirtualFollowListApi, type VirtualFollowListState } from "./virtual-follow-list"
+import VirtualFollowList, { type VirtualFollowListApi, type VirtualFollowListState, type VirtualFollowScrollSnapshot } from "./virtual-follow-list"
 import { useConfig } from "../stores/preferences"
 import { getSessionInfo } from "../stores/sessions"
 import { messageStoreBus } from "../stores/message-v2/bus"
 import { useI18n } from "../lib/i18n"
-import { useScrollCache } from "../lib/hooks/use-scroll-cache"
 import { copyToClipboard } from "../lib/clipboard"
 import { showToastNotification } from "../lib/notifications"
 import { showAlertDialog } from "../stores/alerts"
@@ -38,12 +37,13 @@ export interface MessageSectionProps {
   onRevert?: (messageId: string) => void
   onDeleteMessagesUpTo?: (messageId: string) => void | Promise<void>
   onFork?: (messageId?: string) => void
-  registerScrollToBottom?: (fn: () => void) => void
+  registerScrollToBottom?: (fn: (() => void) | null) => void
   showSidebarToggle?: boolean
   onSidebarToggle?: () => void
   forceCompactStatusLayout?: boolean
   onQuoteSelection?: (text: string, mode: "quote" | "code") => void
   isActive?: boolean
+  sessionStreamingActive?: boolean
 }
 
 export default function MessageSection(props: MessageSectionProps) {
@@ -82,12 +82,6 @@ export default function MessageSection(props: MessageSectionProps) {
     })
   })
 
-  const scrollCache = useScrollCache({
-    instanceId: props.instanceId,
-    sessionId: props.sessionId,
-    scope: MESSAGE_SCROLL_CACHE_SCOPE,
-  })
-
   const sessionRevision = createMemo(() => store().getSessionRevision(props.sessionId))
   const usageSnapshot = createMemo(() => store().getSessionUsage(props.sessionId))
   const sessionInfo = createMemo(() =>
@@ -661,39 +655,101 @@ export default function MessageSection(props: MessageSectionProps) {
   const initialAutoScroll = createMemo(() => initialScrollSnapshot()?.atBottom ?? true)
 
   const [didRestoreScroll, setDidRestoreScroll] = createSignal(false)
+  let lastGoodScrollSnapshot: VirtualFollowScrollSnapshot | undefined
+  let restoringScrollSnapshot = false
   createEffect(
     on(
       () => props.sessionId,
       () => {
         setDidRestoreScroll(false)
+        lastGoodScrollSnapshot = store().getScrollSnapshot(props.sessionId, MESSAGE_SCROLL_CACHE_SCOPE)
+      },
+    ),
+  )
+
+  createEffect(
+    on(
+      isActive,
+      (active, wasActive) => {
+        if (active) {
+          if (wasActive === false) {
+            setDidRestoreScroll(false)
+          }
+          return
+        }
+        persistMessageScrollSnapshot({ requireActive: false })
       },
     ),
   )
 
+  function canCaptureScrollSnapshot(options?: { requireActive?: boolean }) {
+    const element = streamElement()
+    if (!element) return false
+    if ((options?.requireActive ?? true) && !isActive()) return false
+    if (restoringScrollSnapshot) return false
+    if (!element.isConnected) return false
+    if (element.clientHeight <= 0) return false
+    if (typeof getComputedStyle === "function" && getComputedStyle(element).display === "none") return false
+    return true
+  }
+
+  function persistMessageScrollSnapshot(options?: { sessionId?: string; allowCapture?: boolean; requireActive?: boolean }) {
+    if (restoringScrollSnapshot) return
+
+    const sessionId = options?.sessionId ?? props.sessionId
+    const allowCapture = options?.allowCapture ?? true
+    const canCapture = canCaptureScrollSnapshot({ requireActive: options?.requireActive })
+    if (allowCapture && canCapture) {
+      const snapshot = listApi()?.captureScrollSnapshot()
+      if (snapshot) {
+        lastGoodScrollSnapshot = snapshot
+        store().setScrollSnapshot(sessionId, MESSAGE_SCROLL_CACHE_SCOPE, snapshot)
+        return
+      }
+    }
+
+    if (lastGoodScrollSnapshot) {
+      store().setScrollSnapshot(sessionId, MESSAGE_SCROLL_CACHE_SCOPE, lastGoodScrollSnapshot)
+      return
+    }
+
+    const element = streamElement()
+    if (!allowCapture || !canCapture) return
+    if (!element) return
+    const scrollTop = element.scrollTop
+    const maxScrollTop = Math.max(element.scrollHeight - element.clientHeight, 0)
+    const scrollRatio = maxScrollTop > 0 ? scrollTop / maxScrollTop : 0
+    const atBottom = element.scrollHeight - (element.scrollTop + element.clientHeight) <= 48
+    lastGoodScrollSnapshot = { scrollTop, scrollRatio, maxScrollTop, atBottom }
+    store().setScrollSnapshot(sessionId, MESSAGE_SCROLL_CACHE_SCOPE, lastGoodScrollSnapshot)
+  }
+
   // Persist scroll position when switching sessions. This effect's cleanup runs
   // when `props.sessionId` changes, before the next session is rendered.
   createEffect(() => {
     const sessionId = props.sessionId
     onCleanup(() => {
-      const element = streamElement()
-      if (!element) return
-      const scrollTop = element.scrollTop
-      const atBottom = element.scrollHeight - (element.scrollTop + element.clientHeight) <= 48
-      store().setScrollSnapshot(sessionId, MESSAGE_SCROLL_CACHE_SCOPE, { scrollTop, atBottom })
+      persistMessageScrollSnapshot({ sessionId, requireActive: false })
     })
   })
 
   const [quoteSelection, setQuoteSelection] = createSignal<{ text: string; top: number; left: number } | null>(null)
 
-  const lastVisibleMessageId = createMemo(() => {
-    const ids = visibleMessageIds()
-    return ids[ids.length - 1] ?? null
+  const streamingAssistantTextMessageId = createMemo(() => {
+    const ids = messageIds()
+    for (let index = ids.length - 1; index >= 0; index -= 1) {
+      const messageId = ids[index]
+      if (isStreamingAssistantTextMessage(messageId)) return messageId
+    }
+    return null
   })
 
+  const streamingActive = createMemo(() => Boolean(props.sessionStreamingActive) && streamingAssistantTextMessageId() !== null)
+
   const autoPinHoldTargetKey = createMemo(() => {
     if (!holdLongAssistantRepliesEnabled()) return null
-    const messageId = lastVisibleMessageId()
-    return isStreamingAssistantTextMessage(messageId) ? messageId : null
+    if (!streamingActive()) return null
+    return streamingAssistantTextMessageId()
   })
 
   function toggleHoldLongAssistantReplies() {
@@ -708,10 +764,8 @@ export default function MessageSection(props: MessageSectionProps) {
     if (record.status !== "streaming") return false
 
     const info = resolvedStore.getMessageInfo(messageId)
-    if (!info) return false
     const timeInfo = info?.time as { end?: number } | undefined
-    const isStreaming = timeInfo?.end === undefined || timeInfo.end === 0
-    if (!isStreaming) return false
+    if (typeof timeInfo?.end === "number" && timeInfo.end > 0) return false
 
     const { orderedParts } = buildRecordDisplayData(props.instanceId, record)
     return orderedParts.some((part) => {
@@ -725,7 +779,8 @@ export default function MessageSection(props: MessageSectionProps) {
     const api = listApi()
     if (!api) return
     if (props.registerScrollToBottom) {
-      props.registerScrollToBottom(() => api.scrollToBottom({ immediate: true }))
+      props.registerScrollToBottom(() => api.scrollToBottom({ immediate: true, suppressHold: true }))
+      onCleanup(() => props.registerScrollToBottom?.(null))
     }
   })
 
@@ -734,26 +789,38 @@ export default function MessageSection(props: MessageSectionProps) {
     const element = streamElement()
     const api = listApi()
     if (!element || !api) return
+    if (!isActive()) return
     if (props.loading) return
     if (visibleMessageIds().length === 0) return
     if (didRestoreScroll()) return
 
-    scrollCache.restore(element, {
+    const snapshot = store().getScrollSnapshot(props.sessionId, MESSAGE_SCROLL_CACHE_SCOPE)
+    if (!snapshot) {
+      api.setAutoScroll(true)
+      api.scrollToBottom({ immediate: true })
+      setDidRestoreScroll(true)
+      return
+    }
+
+    restoringScrollSnapshot = true
+    api.restoreScrollSnapshot(snapshot, {
       behavior: "auto",
       fallback: () => {
         api.setAutoScroll(true)
         api.scrollToBottom({ immediate: true })
       },
-      onApplied: (snapshot) => {
+      onApplied: () => {
         // Keep follow mode consistent with the restored state.
-        api.setAutoScroll(snapshot?.atBottom ?? true)
+        api.setAutoScroll(snapshot.atBottom)
+        restoringScrollSnapshot = false
+        lastGoodScrollSnapshot = snapshot
         setDidRestoreScroll(true)
       },
     })
   })
 
   onCleanup(() => {
-    scrollCache.persist(streamElement())
+    persistMessageScrollSnapshot({ requireActive: false })
   })
 
   function clearQuoteSelection() {
@@ -865,7 +932,6 @@ export default function MessageSection(props: MessageSectionProps) {
   }
  
   function handleContentRendered() {
-    if (props.loading) return
     listApi()?.notifyContentRendered()
   }
 
@@ -1241,11 +1307,11 @@ export default function MessageSection(props: MessageSectionProps) {
           items={visibleMessageIds}
           getKey={(messageId) => messageId}
           getAnchorId={getMessageAnchorId}
-          getKeyFromAnchorId={getMessageIdFromAnchorId}
           overscanPx={800}
           scrollSentinelMarginPx={SCROLL_SENTINEL_MARGIN_PX}
           suspendMeasurements={() => !isActive()}
-          loading={() => Boolean(props.loading)}
+          streamingActive={streamingActive}
+          autoPinHoldEnabled={holdLongAssistantRepliesEnabled}
           isActive={isActive}
           scrollToBottomOnActivate={() => false}
           initialScrollToBottom={() => false}
@@ -1260,7 +1326,7 @@ export default function MessageSection(props: MessageSectionProps) {
           }}
           onScroll={() => {
             clearQuoteSelection()
-            scrollCache.persist(streamElement())
+            persistMessageScrollSnapshot()
           }}
           onMouseUp={() => handleStreamMouseUp()}
           onClick={(e) => {
@@ -1295,6 +1361,7 @@ export default function MessageSection(props: MessageSectionProps) {
                 class="message-scroll-button"
                 data-active={holdLongAssistantRepliesEnabled() ? "true" : "false"}
                 onClick={toggleHoldLongAssistantReplies}
+                aria-pressed={holdLongAssistantRepliesEnabled()}
                 aria-label={
                   holdLongAssistantRepliesEnabled()
                     ? t("messageSection.scroll.disableHoldAriaLabel")
@@ -1324,7 +1391,7 @@ export default function MessageSection(props: MessageSectionProps) {
                 <button
                   type="button"
                   class="message-scroll-button"
-                  onClick={() => api.scrollToBottom()}
+                  onClick={() => api.scrollToBottom({ suppressHold: true })}
                   aria-label={t("messageSection.scroll.toLatestAriaLabel")}
                 >
                   <span class="message-scroll-icon" aria-hidden="true">
diff --git a/packages/ui/src/components/session/session-view.tsx b/packages/ui/src/components/session/session-view.tsx
index 0ce385cd8..f54226e68 100644
--- a/packages/ui/src/components/session/session-view.tsx
+++ b/packages/ui/src/components/session/session-view.tsx
@@ -1,4 +1,4 @@
-import { Show, createMemo, createEffect, on, onCleanup, type Component } from "solid-js"
+import { Show, createMemo, createEffect, createSignal, on, onCleanup, type Component } from "solid-js"
 import type { Session } from "../../types/session"
 import type { Attachment } from "../../types/attachment"
 import type { ClientPart } from "../../types/message"
@@ -9,7 +9,7 @@ import PromptAttachmentsBar from "../prompt-input/PromptAttachmentsBar"
 import { getAttachments, removeAttachment } from "../../stores/attachments"
 import { instances } from "../../stores/instances"
 import { loadMessages, sendMessage, forkSession, renameSession, isSessionMessagesLoading, markViewedSessionIdleSeen, setActiveParentSession, setActiveSession, runShellCommand, abortSession } from "../../stores/sessions"
-import { IDLE_STATUS_VISIBILITY_MS, isSessionBusy as getSessionBusyStatus } from "../../stores/session-status"
+import { IDLE_STATUS_VISIBILITY_MS, getSessionStatus, isSessionBusy as getSessionBusyStatus } from "../../stores/session-status"
 import { deleteMessage } from "../../stores/session-actions"
 import { showAlertDialog } from "../../stores/alerts"
 import { getLogger } from "../../lib/logger"
@@ -51,6 +51,11 @@ export const SessionView: Component<SessionViewProps> = (props) => {
     if (!currentSession) return false
     return getSessionBusyStatus(props.instanceId, currentSession.id)
   })
+  const sessionStreamingActive = createMemo(() => {
+    const currentSession = session()
+    if (!currentSession) return false
+    return getSessionStatus(props.instanceId, currentSession.id) === "working"
+  })
 
   const sessionNeedsInput = createMemo(() => {
     const currentSession = session()
@@ -68,6 +73,7 @@ export const SessionView: Component<SessionViewProps> = (props) => {
 
   let scrollToBottomHandle: (() => void) | undefined
   let rootRef: HTMLDivElement | undefined
+  const [pendingSubmitBottomScrollTargetCount, setPendingSubmitBottomScrollTargetCount] = createSignal<number | null>(null)
 
   function shouldScrollToBottomOnActivate() {
     const current = session()
@@ -76,11 +82,15 @@ export const SessionView: Component<SessionViewProps> = (props) => {
     return !snapshot || snapshot.atBottom
   }
 
-  function scheduleScrollToBottom() {
-    if (!scrollToBottomHandle) return
+  function scheduleScrollToBottom(options?: { force?: boolean }) {
+    if (!scrollToBottomHandle) return false
     requestAnimationFrame(() => {
-      requestAnimationFrame(() => scrollToBottomHandle?.())
+      requestAnimationFrame(() => {
+        if (!options?.force && !shouldScrollToBottomOnActivate()) return
+        scrollToBottomHandle?.()
+      })
     })
+    return true
   }
 
   function getSeenIdleSignature(currentSession: Session, keepUnseenSubagentIdleStatus: boolean): string {
@@ -189,6 +199,21 @@ export const SessionView: Component<SessionViewProps> = (props) => {
     }
   })
 
+  createEffect(
+    on(
+      () => messageStore().getSessionMessageIds(props.sessionId).length,
+      (messageCount) => {
+        const targetCount = pendingSubmitBottomScrollTargetCount()
+        if (targetCount === null) return
+        const didSchedule = scheduleScrollToBottom({ force: true })
+        if (didSchedule && messageCount >= targetCount) {
+          setPendingSubmitBottomScrollTargetCount(null)
+        }
+      },
+      { defer: true },
+    ),
+  )
+
   function registerPromptInputApi(api: PromptInputApi) {
     promptInputApi = api
     props.registerSessionPromptApi?.(props.sessionId, api)
@@ -220,8 +245,17 @@ export const SessionView: Component<SessionViewProps> = (props) => {
   }
  
   async function handleSendMessage(prompt: string, attachments: Attachment[]) {
-    scheduleScrollToBottom()
-    await sendMessage(props.instanceId, props.sessionId, prompt, attachments)
+    const messageCount = messageStore().getSessionMessageIds(props.sessionId).length
+    setPendingSubmitBottomScrollTargetCount(messageCount + 2)
+    scheduleScrollToBottom({ force: true })
+    try {
+      await sendMessage(props.instanceId, props.sessionId, prompt, attachments)
+      scheduleScrollToBottom({ force: true })
+      setPendingSubmitBottomScrollTargetCount(null)
+    } catch (error) {
+      setPendingSubmitBottomScrollTargetCount(null)
+      throw error
+    }
   }
 
   async function handleRunShell(command: string) {
@@ -276,13 +310,13 @@ export const SessionView: Component<SessionViewProps> = (props) => {
       )
 
       const restoredText = getUserMessageText(messageId)
-       if (restoredText) {
-         if (promptInputApi) {
-           promptInputApi.setPromptText(restoredText, { focus: true })
-         } else {
-           pendingPromptText = restoredText
-         }
-       }
+      if (restoredText) {
+        if (promptInputApi) {
+          promptInputApi.setPromptText(restoredText, { focus: true })
+        } else {
+          pendingPromptText = restoredText
+        }
+      }
     } catch (error) {
       log.error("Failed to revert message", error)
       showAlertDialog(t("sessionView.alerts.revertFailed.message"), {
@@ -360,8 +394,6 @@ export const SessionView: Component<SessionViewProps> = (props) => {
       })
     }
   }
-
-
   return (
     <Show
       when={session()}
@@ -377,58 +409,62 @@ export const SessionView: Component<SessionViewProps> = (props) => {
         return (
           <div ref={rootRef} class="session-view">
             <MessageSection
-               instanceId={props.instanceId}
-               sessionId={activeSession.id}
-                loading={messagesLoading()}
-                onRevert={handleRevert}
-                onDeleteMessagesUpTo={handleDeleteMessagesUpTo}
-                 onFork={handleFork}
-                 isActive={props.isActive}
-                 registerScrollToBottom={(fn) => {
-                   scrollToBottomHandle = fn
-                 }}
-
-
-
-
-               showSidebarToggle={props.showSidebarToggle}
-               onSidebarToggle={props.onSidebarToggle}
-               forceCompactStatusLayout={props.forceCompactStatusLayout}
-               onQuoteSelection={handleQuoteSelection}
-             />
-
-
-                <Show when={attachments().length > 0}>
-                  <PromptAttachmentsBar
-                    attachments={attachments()}
-                    onRemoveAttachment={(attachmentId) => {
-                      if (promptInputApi) {
-                        promptInputApi.removeAttachment(attachmentId)
-                        return
-                      }
-                      removeAttachment(props.instanceId, props.sessionId, attachmentId)
-                    }}
-                    onExpandTextAttachment={(attachmentId) => promptInputApi?.expandTextAttachment(attachmentId)}
-                  />
-                </Show>
-
-              <PromptInput
-                instanceId={props.instanceId}
-                instanceFolder={props.instanceFolder}
-                sessionId={activeSession.id}
-                isActive={props.isActive}
-                compactLayout={props.compactPromptLayout}
-                onSend={handleSendMessage}
-                onRunShell={handleRunShell}
-                escapeInDebounce={props.escapeInDebounce}
-                isSessionBusy={sessionBusy()}
-                disabled={sessionNeedsInput()}
-                onAbortSession={handleAbortSession}
-                registerPromptInputApi={registerPromptInputApi}
-                />
-            </div>
-          )
-        }}
+              instanceId={props.instanceId}
+              sessionId={activeSession.id}
+              loading={messagesLoading()}
+              sessionStreamingActive={sessionStreamingActive()}
+              onRevert={handleRevert}
+              onDeleteMessagesUpTo={handleDeleteMessagesUpTo}
+              onFork={handleFork}
+              isActive={props.isActive}
+              registerScrollToBottom={(fn) => {
+                scrollToBottomHandle = fn ?? undefined
+                if (!fn) return
+                const targetCount = pendingSubmitBottomScrollTargetCount()
+                if (targetCount === null) return
+                const didSchedule = scheduleScrollToBottom({ force: true })
+                const messageCount = messageStore().getSessionMessageIds(props.sessionId).length
+                if (didSchedule && messageCount >= targetCount) {
+                  setPendingSubmitBottomScrollTargetCount(null)
+                }
+              }}
+              showSidebarToggle={props.showSidebarToggle}
+              onSidebarToggle={props.onSidebarToggle}
+              forceCompactStatusLayout={props.forceCompactStatusLayout}
+              onQuoteSelection={handleQuoteSelection}
+            />
+
+            <Show when={attachments().length > 0}>
+              <PromptAttachmentsBar
+                attachments={attachments()}
+                onRemoveAttachment={(attachmentId) => {
+                  if (promptInputApi) {
+                    promptInputApi.removeAttachment(attachmentId)
+                    return
+                  }
+                  removeAttachment(props.instanceId, props.sessionId, attachmentId)
+                }}
+                onExpandTextAttachment={(attachmentId) => promptInputApi?.expandTextAttachment(attachmentId)}
+              />
+            </Show>
+
+            <PromptInput
+              instanceId={props.instanceId}
+              instanceFolder={props.instanceFolder}
+              sessionId={activeSession.id}
+              isActive={props.isActive}
+              compactLayout={props.compactPromptLayout}
+              onSend={handleSendMessage}
+              onRunShell={handleRunShell}
+              escapeInDebounce={props.escapeInDebounce}
+              isSessionBusy={sessionBusy()}
+              disabled={sessionNeedsInput()}
+              onAbortSession={handleAbortSession}
+              registerPromptInputApi={registerPromptInputApi}
+            />
+          </div>
+        )
+      }}
     </Show>
   )
 }
diff --git a/packages/ui/src/components/virtual-follow-behavior.test.ts b/packages/ui/src/components/virtual-follow-behavior.test.ts
new file mode 100644
index 000000000..1e20f0aa8
--- /dev/null
+++ b/packages/ui/src/components/virtual-follow-behavior.test.ts
@@ -0,0 +1,248 @@
+import assert from "node:assert/strict"
+import { describe, it } from "node:test"
+
+import {
+  VirtualScrollController,
+  isAtBottom,
+  isAutoFollowing,
+  transitionFollowMode,
+  type FollowMode,
+  type ScrollControllerMetrics,
+} from "./virtual-follow-behavior.ts"
+
+const userScroll = (direction: "up" | "down" | null, atBottom: boolean, canPinToBottom = false) =>
+  ({ type: "user-scroll", direction, atBottom, canPinToBottom }) as const
+
+function metrics(offset: number, scrollHeight = 3000, clientHeight = 600): ScrollControllerMetrics {
+  return {
+    offset,
+    scrollHeight,
+    clientHeight,
+    sentinelMarginPx: 48,
+  }
+}
+
+describe("virtual follow behavior", () => {
+  it("escapes follow on upward user scroll", () => {
+    const next = transitionFollowMode({ type: "following" }, userScroll("up", false))
+
+    assert.deepEqual(next.mode, { type: "escaped" })
+    assert.deepEqual(next.effect, { type: "none" })
+  })
+
+  it("does not rejoin follow when escaped user scrolls down above bottom without pin permission", () => {
+    const next = transitionFollowMode({ type: "escaped" }, userScroll("down", false))
+
+    assert.deepEqual(next.mode, { type: "escaped" })
+    assert.deepEqual(next.effect, { type: "none" })
+  })
+
+  it("rejoins follow and pins bottom when escaped user scrolls down with pin permission", () => {
+    const next = transitionFollowMode({ type: "escaped" }, userScroll("down", false, true))
+
+    assert.deepEqual(next.mode, { type: "following" })
+    assert.deepEqual(next.effect, { type: "scroll-bottom", immediate: true, suppressHold: false })
+  })
+
+  it("rejoins follow when escaped user scrolls to the bottom", () => {
+    const next = transitionFollowMode({ type: "escaped" }, userScroll("down", true))
+
+    assert.deepEqual(next.mode, { type: "following" })
+    assert.deepEqual(next.effect, { type: "none" })
+  })
+
+  it("releases hold when the user scrolls down above bottom", () => {
+    const next = transitionFollowMode({ type: "holding", key: "message-1" }, userScroll("down", false, true))
+
+    assert.deepEqual(next.mode, { type: "escaped" })
+    assert.deepEqual(next.effect, { type: "none" })
+  })
+
+  it("does not rejoin follow for directionless scroll above bottom", () => {
+    const next = transitionFollowMode({ type: "escaped" }, userScroll(null, false, true))
+
+    assert.deepEqual(next.mode, { type: "escaped" })
+    assert.deepEqual(next.effect, { type: "none" })
+  })
+
+  it("does not rejoin follow on upward scroll at bottom", () => {
+    const next = transitionFollowMode({ type: "escaped" }, userScroll("up", true, true))
+
+    assert.deepEqual(next.mode, { type: "escaped" })
+    assert.deepEqual(next.effect, { type: "none" })
+  })
+
+  it("releases hold for directionless user scroll away from bottom", () => {
+    const next = transitionFollowMode({ type: "holding", key: "message-1" }, userScroll(null, false, true))
+
+    assert.deepEqual(next.mode, { type: "escaped" })
+    assert.deepEqual(next.effect, { type: "none" })
+  })
+
+  it("pins content growth while following but not while escaped", () => {
+    const escaped = transitionFollowMode({ type: "escaped" }, { type: "content-grew", canPinToBottom: true })
+    const following = transitionFollowMode({ type: "following" }, { type: "content-grew", canPinToBottom: true })
+
+    assert.deepEqual(escaped.effect, { type: "none" })
+    assert.deepEqual(following.effect, { type: "scroll-bottom", immediate: true, suppressHold: false })
+  })
+
+  it("maintains hold alignment while held content grows", () => {
+    const next = transitionFollowMode({ type: "holding", key: "message-1" }, { type: "content-grew", canPinToBottom: true })
+
+    assert.deepEqual(next.mode, { type: "holding", key: "message-1" })
+    assert.deepEqual(next.effect, { type: "align-hold", key: "message-1" })
+  })
+
+  it("enters hold mode for a valid hold candidate", () => {
+    const next = transitionFollowMode({ type: "following" }, { type: "hold-candidate", key: "message-1", shouldHold: true })
+
+    assert.deepEqual(next.mode, { type: "holding", key: "message-1" })
+    assert.deepEqual(next.effect, { type: "align-hold", key: "message-1" })
+  })
+
+  it("explicit bottom jumps leave hold and suppress the next hold", () => {
+    const next = transitionFollowMode({ type: "holding", key: "message-1" }, { type: "jump-bottom", immediate: true, explicit: true })
+
+    assert.deepEqual(next.mode, { type: "following" })
+    assert.deepEqual(next.effect, { type: "scroll-bottom", immediate: true, suppressHold: true })
+  })
+
+  it("key jumps can opt into follow or escape mode", () => {
+    const follow = transitionFollowMode({ type: "escaped" }, { type: "jump-key", key: "a", block: "start", smooth: false, followAfter: true })
+    const escape = transitionFollowMode({ type: "following" }, { type: "jump-key", key: "b", block: "center", smooth: true, followAfter: false })
+
+    assert.deepEqual(follow.mode, { type: "following" })
+    assert.deepEqual(escape.mode, { type: "escaped" })
+  })
+
+  it("derives auto-follow from modes", () => {
+    const modes: Array<[FollowMode, boolean]> = [
+      [{ type: "following" }, true],
+      [{ type: "holding", key: "message-1" }, true],
+      [{ type: "escaped" }, false],
+    ]
+
+    for (const [mode, expected] of modes) {
+      assert.equal(isAutoFollowing(mode), expected)
+    }
+  })
+
+  it("pins content growth instead of escaping on transient upward render movement", () => {
+    const controller = new VirtualScrollController(true)
+    controller.recordProgrammaticOffset(2400, true)
+
+    const result = controller.contentRendered(metrics(2200), true)
+
+    assert.deepEqual(result.state.mode, { type: "following" })
+    assert.deepEqual(result.effect, { type: "scroll-bottom", immediate: true, suppressHold: false })
+  })
+
+  it("maintains hold alignment when held content renders", () => {
+    const controller = new VirtualScrollController(true)
+    controller.holdCandidate("message-1", true)
+
+    const result = controller.contentRendered(metrics(2200), true)
+
+    assert.deepEqual(result.state.mode, { type: "holding", key: "message-1" })
+    assert.deepEqual(result.effect, { type: "align-hold", key: "message-1" })
+  })
+
+  it("lets fresh user upward movement escape even during a programmatic window", () => {
+    const controller = new VirtualScrollController(true)
+    controller.recordProgrammaticOffset(2400, true)
+    controller.setUserIntent("up", 700)
+
+    const result = controller.observeViewport(metrics(2200), 100, true)
+
+    assert.deepEqual(result.state.mode, { type: "escaped" })
+  })
+
+  it("does not escape for owned programmatic upward movement", () => {
+    const controller = new VirtualScrollController(true)
+    controller.recordProgrammaticOffset(2400, true)
+
+    const result = controller.observeViewport(metrics(2200), 100, true)
+
+    assert.deepEqual(result.state.mode, { type: "following" })
+    assert.deepEqual(result.effect, { type: "none" })
+  })
+
+  it("does not resume follow on directionless scroll above bottom", () => {
+    const controller = new VirtualScrollController(false)
+    controller.recordProgrammaticOffset(2220, false)
+
+    const result = controller.observeViewport(metrics(2220), 100, false)
+
+    assert.deepEqual(result.state.mode, { type: "escaped" })
+    assert.deepEqual(result.effect, { type: "none" })
+  })
+
+  it("does not resume follow from pixel distance alone", () => {
+    const controller = new VirtualScrollController(false)
+    controller.recordProgrammaticOffset(2100, false)
+    controller.setUserIntent("down", 700)
+
+    const result = controller.observeViewport(metrics(2220), 100, false)
+
+    assert.deepEqual(result.state.mode, { type: "escaped" })
+    assert.deepEqual(result.effect, { type: "none" })
+  })
+
+  it("resumes follow only when downward movement reaches actual bottom", () => {
+    const controller = new VirtualScrollController(false)
+    controller.recordProgrammaticOffset(2300, false)
+    controller.setUserIntent("down", 700)
+
+    const result = controller.observeViewport(metrics(2400), 100, false)
+
+    assert.deepEqual(result.state.mode, { type: "following" })
+    assert.deepEqual(result.effect, { type: "none" })
+  })
+
+  it("still escapes follow on upward movement at bottom", () => {
+    const controller = new VirtualScrollController(true)
+    controller.recordProgrammaticOffset(1200, false)
+
+    const result = controller.observeViewport(metrics(1100), 100, false)
+
+    assert.deepEqual(result.state.mode, { type: "escaped" })
+    assert.deepEqual(result.effect, { type: "none" })
+  })
+
+  it("blocks content pinning while restoring", () => {
+    const controller = new VirtualScrollController(true)
+    controller.setRestoring(true)
+
+    const result = controller.contentRendered(metrics(2400), true)
+
+    assert.deepEqual(result.state.mode, { type: "following" })
+    assert.deepEqual(result.effect, { type: "none" })
+  })
+
+  it("does not pin content growth when the integration gate is closed", () => {
+    const controller = new VirtualScrollController(true)
+
+    const result = controller.contentRendered(metrics(2400), false)
+
+    assert.deepEqual(result.state.mode, { type: "following" })
+    assert.deepEqual(result.effect, { type: "none" })
+  })
+
+  it("blocks pre-pin upward reconciliation while restoring", () => {
+    const controller = new VirtualScrollController(true)
+    controller.recordProgrammaticOffset(2400, true)
+    controller.setRestoring(true)
+
+    const result = controller.beforeBottomPin(metrics(2200))
+
+    assert.deepEqual(result.state.mode, { type: "following" })
+    assert.deepEqual(result.effect, { type: "none" })
+  })
+
+  it("distinguishes close-to-bottom from at-bottom metrics", () => {
+    const closeButNotAtBottom = metrics(2351)
+
+    assert.equal(isAtBottom(closeButNotAtBottom), false)
+  })
+})
diff --git a/packages/ui/src/components/virtual-follow-behavior.ts b/packages/ui/src/components/virtual-follow-behavior.ts
new file mode 100644
index 000000000..e2e6e446b
--- /dev/null
+++ b/packages/ui/src/components/virtual-follow-behavior.ts
@@ -0,0 +1,307 @@
+export type FollowMode =
+  | { type: "following" }
+  | { type: "escaped" }
+  | { type: "holding"; key: string }
+
+export type FollowEffect =
+  | { type: "none" }
+  | { type: "scroll-top"; immediate: boolean }
+  | { type: "scroll-bottom"; immediate: boolean; suppressHold: boolean }
+  | { type: "scroll-key"; key: string; block: ScrollLogicalPosition; smooth: boolean }
+  | { type: "align-hold"; key: string }
+
+export type FollowEvent =
+  | { type: "user-scroll"; direction: "up" | "down" | null; atBottom: boolean; canPinToBottom: boolean }
+  | { type: "jump-top"; immediate: boolean }
+  | { type: "jump-bottom"; immediate: boolean; explicit: boolean }
+  | { type: "jump-key"; key: string; block: ScrollLogicalPosition; smooth: boolean; followAfter: boolean }
+  | { type: "content-grew"; canPinToBottom: boolean }
+  | { type: "hold-candidate"; key: string; shouldHold: boolean }
+  | { type: "hold-target-changed"; key: string | null; canPinToBottom: boolean }
+  | { type: "set-follow"; enabled: boolean }
+  | { type: "reset"; follow: boolean }
+
+export interface FollowTransition {
+  mode: FollowMode
+  effect: FollowEffect
+}
+
+export type ScrollDirection = "up" | "down" | null
+
+export interface ScrollControllerMetrics {
+  offset: number
+  scrollHeight: number
+  clientHeight: number
+  sentinelMarginPx: number
+}
+
+export interface ScrollControllerState {
+  mode: FollowMode
+  lastObservedOffset: number
+  lastObservedAtBottom: boolean
+  userIntentDirection: ScrollDirection
+  userIntentUntil: number
+  restoring: boolean
+}
+
+export interface ScrollControllerResult {
+  effect: FollowEffect
+  state: ScrollControllerState
+}
+
+export interface ScrollControllerSnapshot {
+  mode: FollowMode
+  lastObservedOffset: number
+  lastObservedAtBottom: boolean
+  userIntentDirection: ScrollDirection
+  userIntentUntil: number
+  restoring: boolean
+}
+
+const noFollowEffect: FollowEffect = { type: "none" }
+
+export function isAutoFollowing(mode: FollowMode) {
+  return mode.type === "following" || mode.type === "holding"
+}
+
+export function getHeldKey(mode: FollowMode) {
+  return mode.type === "holding" ? mode.key : null
+}
+
+export function transitionFollowMode(mode: FollowMode, event: FollowEvent): FollowTransition {
+  switch (event.type) {
+    case "user-scroll": {
+      if (event.direction === "up") {
+        return { mode: { type: "escaped" }, effect: noFollowEffect }
+      }
+      if (mode.type === "holding" && event.direction === null) {
+        return { mode: { type: "escaped" }, effect: noFollowEffect }
+      }
+      if (mode.type === "holding" && event.direction === "down") {
+        return { mode: { type: "escaped" }, effect: noFollowEffect }
+      }
+      if (mode.type === "escaped" && event.direction === "down" && event.canPinToBottom) {
+        return {
+          mode: { type: "following" },
+          effect: { type: "scroll-bottom", immediate: true, suppressHold: false },
+        }
+      }
+      if (event.atBottom && mode.type !== "holding") {
+        return { mode: { type: "following" }, effect: noFollowEffect }
+      }
+      return { mode, effect: noFollowEffect }
+    }
+
+    case "jump-top":
+      return { mode: { type: "escaped" }, effect: { type: "scroll-top", immediate: event.immediate } }
+
+    case "jump-bottom":
+      return {
+        mode: { type: "following" },
+        effect: { type: "scroll-bottom", immediate: event.immediate, suppressHold: event.explicit },
+      }
+
+    case "jump-key":
+      return {
+        mode: event.followAfter ? { type: "following" } : { type: "escaped" },
+        effect: { type: "scroll-key", key: event.key, block: event.block, smooth: event.smooth },
+      }
+
+    case "content-grew":
+      if (mode.type === "following" && event.canPinToBottom) {
+        return { mode, effect: { type: "scroll-bottom", immediate: true, suppressHold: false } }
+      }
+      if (mode.type === "holding" && event.canPinToBottom) {
+        return { mode, effect: { type: "align-hold", key: mode.key } }
+      }
+      return { mode, effect: noFollowEffect }
+
+    case "hold-candidate":
+      if (mode.type === "following" && event.shouldHold) {
+        return { mode: { type: "holding", key: event.key }, effect: { type: "align-hold", key: event.key } }
+      }
+      return { mode, effect: noFollowEffect }
+
+    case "hold-target-changed":
+      if (mode.type !== "holding" || event.key === mode.key) {
+        return { mode, effect: noFollowEffect }
+      }
+      return {
+        mode: { type: "following" },
+        effect: event.canPinToBottom ? { type: "scroll-bottom", immediate: false, suppressHold: false } : noFollowEffect,
+      }
+
+    case "set-follow":
+      return { mode: event.enabled ? { type: "following" } : { type: "escaped" }, effect: noFollowEffect }
+
+    case "reset":
+      return { mode: event.follow ? { type: "following" } : { type: "escaped" }, effect: noFollowEffect }
+  }
+}
+
+export function getDistanceFromBottom(metrics: ScrollControllerMetrics) {
+  return metrics.scrollHeight - (metrics.offset + metrics.clientHeight)
+}
+
+export function isAtBottom(metrics: ScrollControllerMetrics) {
+  return getDistanceFromBottom(metrics) <= metrics.sentinelMarginPx
+}
+
+export class VirtualScrollController {
+  private state: ScrollControllerState
+
+  constructor(initialFollow: boolean) {
+    this.state = {
+      mode: initialFollow ? { type: "following" } : { type: "escaped" },
+      lastObservedOffset: 0,
+      lastObservedAtBottom: false,
+      userIntentDirection: null,
+      userIntentUntil: 0,
+      restoring: false,
+    }
+  }
+
+  snapshot(): ScrollControllerSnapshot {
+    return { ...this.state, mode: { ...this.state.mode } }
+  }
+
+  isAutoFollowing() {
+    return isAutoFollowing(this.state.mode)
+  }
+
+  heldKey() {
+    return this.state.mode.type === "holding" ? this.state.mode.key : null
+  }
+
+  setUserIntent(direction: ScrollDirection, until: number) {
+    this.state.userIntentDirection = direction
+    this.state.userIntentUntil = until
+  }
+
+  clearExpiredUserIntent(now: number) {
+    if (now <= this.state.userIntentUntil) return false
+    this.state.userIntentDirection = null
+    return true
+  }
+
+  setRestoring(restoring: boolean) {
+    this.state.restoring = restoring
+  }
+
+  reset(follow: boolean): ScrollControllerResult {
+    const next = transitionFollowMode(this.state.mode, { type: "reset", follow })
+    this.state.mode = next.mode
+    this.state.lastObservedOffset = 0
+    this.state.lastObservedAtBottom = false
+    this.state.userIntentDirection = null
+    this.state.userIntentUntil = 0
+    this.state.restoring = false
+    return this.result(next.effect)
+  }
+
+  setFollow(enabled: boolean): ScrollControllerResult {
+    const next = transitionFollowMode(this.state.mode, { type: "set-follow", enabled })
+    this.state.mode = next.mode
+    return this.result(next.effect)
+  }
+
+  jumpTop(immediate: boolean): ScrollControllerResult {
+    const next = transitionFollowMode(this.state.mode, { type: "jump-top", immediate })
+    this.state.mode = next.mode
+    return this.result(next.effect)
+  }
+
+  jumpBottom(immediate: boolean, explicit: boolean): ScrollControllerResult {
+    const next = transitionFollowMode(this.state.mode, { type: "jump-bottom", immediate, explicit })
+    this.state.mode = next.mode
+    return this.result(next.effect)
+  }
+
+  jumpKey(key: string, block: ScrollLogicalPosition, smooth: boolean, followAfter: boolean): ScrollControllerResult {
+    const next = transitionFollowMode(this.state.mode, { type: "jump-key", key, block, smooth, followAfter })
+    this.state.mode = next.mode
+    return this.result(next.effect)
+  }
+
+  holdCandidate(key: string, shouldHold: boolean): ScrollControllerResult {
+    const next = transitionFollowMode(this.state.mode, { type: "hold-candidate", key, shouldHold })
+    this.state.mode = next.mode
+    return this.result(next.effect)
+  }
+
+  holdTargetChanged(key: string | null, canPinToBottom: boolean): ScrollControllerResult {
+    const next = transitionFollowMode(this.state.mode, { type: "hold-target-changed", key, canPinToBottom })
+    this.state.mode = next.mode
+    return this.result(next.effect)
+  }
+
+  observeViewport(metrics: ScrollControllerMetrics, now: number, programmatic: boolean, canPinToBottom = false): ScrollControllerResult {
+    const previousOffset = this.state.lastObservedOffset
+    const offset = metrics.offset
+    const scrolledUp = offset < previousOffset - 1
+    const scrolledDown = offset > previousOffset + 1
+    const atBottom = isAtBottom(metrics)
+
+    this.state.lastObservedOffset = offset
+    this.state.lastObservedAtBottom = this.isAutoFollowing() && atBottom
+    this.clearExpiredUserIntent(now)
+
+    const hasFreshIntent = now <= this.state.userIntentUntil
+    if (scrolledUp && this.isAutoFollowing() && !atBottom && this.heldKey() === null && (!programmatic || hasFreshIntent)) {
+      return this.setFollow(false)
+    }
+
+    const actualDirection: ScrollDirection = scrolledUp ? "up" : scrolledDown ? "down" : null
+    if (!hasFreshIntent && (!actualDirection || programmatic)) {
+      return this.result(noFollowEffect)
+    }
+
+    const direction = actualDirection ?? this.state.userIntentDirection
+    const canMagnetToBottom = hasFreshIntent && direction === "down" && canPinToBottom
+    const next = transitionFollowMode(this.state.mode, {
+      type: "user-scroll",
+      direction,
+      atBottom,
+      canPinToBottom: canMagnetToBottom,
+    })
+    this.state.mode = next.mode
+    this.state.lastObservedAtBottom = this.isAutoFollowing() && atBottom
+    return this.result(next.effect)
+  }
+
+  contentRendered(metrics: ScrollControllerMetrics, canPinToBottom: boolean): ScrollControllerResult {
+    if (this.state.restoring) return this.result(noFollowEffect)
+    if (!canPinToBottom || !this.isAutoFollowing()) {
+      const reconcile = this.reconcileUpwardDomMovement(metrics)
+      if (reconcile.effect.type !== "none") return reconcile
+    }
+
+    const next = transitionFollowMode(this.state.mode, { type: "content-grew", canPinToBottom })
+    this.state.mode = next.mode
+    return this.result(next.effect)
+  }
+
+  beforeBottomPin(metrics: ScrollControllerMetrics): ScrollControllerResult {
+    if (this.state.restoring) return this.result(noFollowEffect)
+    return this.reconcileUpwardDomMovement(metrics)
+  }
+
+  recordProgrammaticOffset(offset: number, atBottom: boolean) {
+    this.state.lastObservedOffset = offset
+    this.state.lastObservedAtBottom = this.isAutoFollowing() && atBottom
+  }
+
+  private reconcileUpwardDomMovement(metrics: ScrollControllerMetrics): ScrollControllerResult {
+    if (!this.isAutoFollowing()) return this.result(noFollowEffect)
+    if (this.heldKey() !== null) return this.result(noFollowEffect)
+    if (isAtBottom(metrics)) return this.result(noFollowEffect)
+    if (metrics.offset >= this.state.lastObservedOffset - 1) return this.result(noFollowEffect)
+    this.state.lastObservedOffset = metrics.offset
+    this.state.lastObservedAtBottom = false
+    return this.setFollow(false)
+  }
+
+  private result(effect: FollowEffect): ScrollControllerResult {
+    return { effect, state: this.snapshot() }
+  }
+}
diff --git a/packages/ui/src/components/virtual-follow-list.tsx b/packages/ui/src/components/virtual-follow-list.tsx
index 070e0b92a..1a44a3b77 100644
--- a/packages/ui/src/components/virtual-follow-list.tsx
+++ b/packages/ui/src/components/virtual-follow-list.tsx
@@ -1,14 +1,17 @@
-import { Show, createEffect, createMemo, createSignal, onCleanup, type Accessor, type JSX, on } from "solid-js"
+import { Show, createEffect, createMemo, createSignal, type Accessor, type JSX, on, onCleanup } from "solid-js"
 import { Virtualizer, type VirtualizerHandle } from "virtua/solid"
+import { getHeldKey, isAutoFollowing, isAtBottom, VirtualScrollController, type FollowEffect, type FollowEvent, type FollowMode, type ScrollControllerMetrics, type ScrollControllerResult } from "./virtual-follow-behavior.ts"
 
 const DEFAULT_SCROLL_SENTINEL_MARGIN_PX = 48
 const DEFAULT_HOLD_TARGET_TOP_THRESHOLD_PX = 8
+const DEFAULT_REJOIN_LAST_ITEM_COUNT = 2
 const USER_SCROLL_INTENT_WINDOW_MS = 600
 const SCROLL_INTENT_KEYS = new Set(["ArrowUp", "ArrowDown", "PageUp", "PageDown", "Home", "End", " ", "Spacebar"])
+const INTERACTIVE_KEY_TARGET_SELECTOR = "button, a, input, textarea, select, [contenteditable='true'], [role='button'], [role='textbox']"
 
 export interface VirtualFollowListApi {
   scrollToTop: (opts?: { immediate?: boolean }) => void
-  scrollToBottom: (opts?: { immediate?: boolean; suppressAutoAnchor?: boolean }) => void
+  scrollToBottom: (opts?: { immediate?: boolean; suppressAutoAnchor?: boolean; suppressHold?: boolean }) => void
   scrollToKey: (
     key: string,
     opts?: { behavior?: ScrollBehavior; block?: ScrollLogicalPosition; setAutoScroll?: boolean },
@@ -18,6 +21,23 @@ export interface VirtualFollowListApi {
   getAutoScroll: () => boolean
   getScrollElement: () => HTMLDivElement | undefined
   getShellElement: () => HTMLDivElement | undefined
+  captureScrollSnapshot: () => VirtualFollowScrollSnapshot | undefined
+  restoreScrollSnapshot: (snapshot: VirtualFollowScrollSnapshot, opts?: RestoreScrollSnapshotOptions) => void
+}
+
+export interface VirtualFollowScrollSnapshot {
+  scrollTop: number
+  scrollRatio?: number
+  maxScrollTop?: number
+  anchorKey?: string
+  anchorOffset?: number
+  atBottom: boolean
+}
+
+interface RestoreScrollSnapshotOptions {
+  behavior?: ScrollBehavior
+  fallback?: () => void
+  onApplied?: () => void
 }
 
 export interface VirtualFollowListState {
@@ -39,17 +59,11 @@ export interface VirtualFollowListProps<T> {
    */
   getAnchorId?: (key: string) => string
 
-  /**
-   * Decode an item key from an observed wrapper element id.
-   * Defaults to identity.
-   */
-  getKeyFromAnchorId?: (anchorId: string) => string
-
   overscanPx?: number
   scrollSentinelMarginPx?: number
   virtualizationEnabled?: Accessor<boolean>
   suspendMeasurements?: Accessor<boolean>
-  loading?: Accessor<boolean>
+  streamingActive?: Accessor<boolean>
   isActive?: Accessor<boolean>
 
   /**
@@ -91,6 +105,7 @@ export interface VirtualFollowListProps<T> {
    * rendered item grows taller than the viewport and reaches the top edge.
    */
   autoPinHoldTargetKey?: Accessor<string | null>
+  autoPinHoldEnabled?: Accessor<boolean>
 
   /**
    * Optional resolver for the specific element inside an item wrapper that
@@ -154,28 +169,31 @@ export default function VirtualFollowList<T>(props: VirtualFollowListProps<T>) {
   const initialScrollToBottom = () => (props.initialScrollToBottom ? props.initialScrollToBottom() : true)
   const initialAutoScroll = () => (props.initialAutoScroll ? props.initialAutoScroll() : true)
   const externalSuspendAutoPinToBottom = () => (props.suspendAutoPinToBottom ? props.suspendAutoPinToBottom() : false)
+  const streamingActive = () => props.streamingActive?.() ?? false
+  const autoPinHoldEnabled = () => props.autoPinHoldEnabled?.() ?? false
   const holdTargetKey = () => (props.autoPinHoldTargetKey ? props.autoPinHoldTargetKey() : null)
   const holdTargetTopThresholdPx = () => props.autoPinHoldTopThresholdPx ?? DEFAULT_HOLD_TARGET_TOP_THRESHOLD_PX
 
-  const [autoScroll, setAutoScroll] = createSignal(Boolean(initialAutoScroll()))
+  const scrollController = new VirtualScrollController(initialAutoScroll())
+  const [followMode, setFollowMode] = createSignal<FollowMode>(scrollController.snapshot().mode)
+  const autoScroll = createMemo(() => isAutoFollowing(followMode()))
   const [showScrollTopButton, setShowScrollTopButton] = createSignal(false)
   const [showScrollBottomButton, setShowScrollBottomButton] = createSignal(false)
   const [activeKey, setActiveKey] = createSignal<string | null>(null)
-  const [activeHoldTargetKey, setActiveHoldTargetKey] = createSignal<string | null>(null)
+  const activeHoldTargetKey = createMemo(() => getHeldKey(followMode()))
   const [didTriggerHoldForCurrentTarget, setDidTriggerHoldForCurrentTarget] = createSignal(false)
   const effectiveSuspendAutoPinToBottom = () => externalSuspendAutoPinToBottom() || activeHoldTargetKey() !== null
 
   const scrollButtonsCount = createMemo(() => (showScrollTopButton() ? 1 : 0) + (showScrollBottomButton() ? 1 : 0))
   const itemElements = new Map<string, HTMLDivElement>()
 
-  let userScrollIntentUntil = 0
-  let lastUserScrollIntentDirection: "up" | "down" | null = null
   let detachScrollIntentListeners: (() => void) | undefined
   let lastResetKey: string | number | undefined
   let suppressAutoScrollOnce = false
+  let suppressHoldUntilTargetChanges = false
   let pendingInitialScroll = true
-  let lastObservedScrollOffset = 0
-  let lastObservedPinnedAtBottom = false
+  let programmaticScrollUntil = 0
+  let pendingBottomRepinAfterHold = false
 
   const state: VirtualFollowListState = {
     autoScroll,
@@ -187,24 +205,98 @@ export default function VirtualFollowList<T>(props: VirtualFollowListProps<T>) {
 
   function markUserScrollIntent(direction?: "up" | "down" | null) {
     const now = performance.now()
-    userScrollIntentUntil = now + USER_SCROLL_INTENT_WINDOW_MS
-    if (direction) {
-      lastUserScrollIntentDirection = direction
-    }
+    scrollController.setUserIntent(direction ?? null, now + USER_SCROLL_INTENT_WINDOW_MS)
   }
 
-  function hasUserScrollIntent() {
-    return performance.now() <= userScrollIntentUntil
+  function markProgrammaticScroll() {
+    programmaticScrollUntil = performance.now() + 120
   }
 
-  function clearAutoPinHold(options?: { resumeBottom?: boolean }) {
-    if (activeHoldTargetKey() === null) return
-    setActiveHoldTargetKey(null)
-    if (options?.resumeBottom && autoScroll()) {
-      requestAnimationFrame(() => {
-        if (!autoScroll() || activeHoldTargetKey() !== null) return
-        scrollToBottom(false)
-      })
+  function hasProgrammaticScrollIntent() {
+    return performance.now() <= programmaticScrollUntil
+  }
+
+  function syncControllerResult(result: ScrollControllerResult) {
+    setFollowMode(result.state.mode)
+    applyFollowEffect(result.effect)
+  }
+
+  function escapeFollowIfDomMovedUp(element = scrollElement()) {
+    if (!element) return false
+    const result = scrollController.beforeBottomPin(getDomMetrics(element))
+    syncControllerResult(result)
+    return result.effect.type !== "none" || result.state.mode.type === "escaped"
+  }
+
+  function shouldHonorPrePinEscape() {
+    const snapshot = scrollController.snapshot()
+    return performance.now() <= snapshot.userIntentUntil && snapshot.userIntentDirection === "up"
+  }
+
+  function dispatchFollowEvent(event: FollowEvent) {
+    let result: ScrollControllerResult
+    switch (event.type) {
+      case "user-scroll": {
+        const metrics = getManualMetrics(event.atBottom)
+        result = scrollController.observeViewport(
+          metrics,
+          performance.now(),
+          hasProgrammaticScrollIntent(),
+          canRejoinFollowFromDownScroll(metrics),
+        )
+        break
+      }
+      case "jump-top":
+        result = scrollController.jumpTop(event.immediate)
+        break
+      case "jump-bottom":
+        result = scrollController.jumpBottom(event.immediate, event.explicit)
+        break
+      case "jump-key":
+        result = scrollController.jumpKey(event.key, event.block, event.smooth, event.followAfter)
+        break
+      case "content-grew": {
+        const element = scrollElement()
+        result = element
+          ? scrollController.contentRendered(getDomMetrics(element), event.canPinToBottom)
+          : scrollController.contentRendered(getManualMetrics(false), event.canPinToBottom)
+        break
+      }
+      case "hold-candidate":
+        result = scrollController.holdCandidate(event.key, event.shouldHold)
+        break
+      case "hold-target-changed":
+        result = scrollController.holdTargetChanged(event.key, event.canPinToBottom)
+        break
+      case "set-follow":
+        result = scrollController.setFollow(event.enabled)
+        break
+      case "reset":
+        result = scrollController.reset(event.follow)
+        break
+    }
+    syncControllerResult(result)
+  }
+
+  function applyFollowEffect(effect: FollowEffect) {
+    switch (effect.type) {
+      case "none":
+        return
+      case "scroll-top":
+        performScrollToTop(effect.immediate)
+        return
+      case "scroll-bottom":
+        if (effect.suppressHold) {
+          suppressHoldUntilTargetChanges = true
+        }
+        performScrollToBottom(effect.immediate)
+        return
+      case "scroll-key":
+        performScrollToKey(effect.key, { block: effect.block, smooth: effect.smooth })
+        return
+      case "align-hold":
+        alignHoldTarget(effect.key)
+        return
     }
   }
 
@@ -218,9 +310,13 @@ export default function VirtualFollowList<T>(props: VirtualFollowListProps<T>) {
       const dir: "up" | "down" | null = event.deltaY < 0 ? "up" : event.deltaY > 0 ? "down" : null
       markUserScrollIntent(dir)
     }
-    const handlePointerIntent = () => markUserScrollIntent(null)
+    const handlePointerIntent = (event: PointerEvent) => {
+      if ((event.target as HTMLElement | null)?.closest(INTERACTIVE_KEY_TARGET_SELECTOR)) return
+      markUserScrollIntent(null)
+    }
     const handleKeyIntent = (event: KeyboardEvent) => {
       if (!SCROLL_INTENT_KEYS.has(event.key)) return
+      if ((event.target as HTMLElement | null)?.closest(INTERACTIVE_KEY_TARGET_SELECTOR)) return
       const key = event.key
       const dir: "up" | "down" | null =
         key === "ArrowUp" || key === "PageUp" || key === "Home"
@@ -232,93 +328,335 @@ export default function VirtualFollowList<T>(props: VirtualFollowListProps<T>) {
                 ? "up"
                 : "down"
               : null
+      if (key === "End") {
+        event.preventDefault()
+        scrollToBottom(true)
+        return
+      }
       markUserScrollIntent(dir)
     }
     element.addEventListener("wheel", handleWheelIntent, { passive: true })
     element.addEventListener("pointerdown", handlePointerIntent)
-    element.addEventListener("touchstart", handlePointerIntent, { passive: true })
     element.addEventListener("keydown", handleKeyIntent)
     detachScrollIntentListeners = () => {
       element.removeEventListener("wheel", handleWheelIntent)
       element.removeEventListener("pointerdown", handlePointerIntent)
-      element.removeEventListener("touchstart", handlePointerIntent)
       element.removeEventListener("keydown", handleKeyIntent)
     }
   }
 
+  function getCurrentScrollOffset(_element: HTMLDivElement, handle: VirtualizerHandle) {
+    return handle.scrollOffset
+  }
+
+  function getCurrentScrollSize(_element: HTMLDivElement, handle: VirtualizerHandle) {
+    return handle.scrollSize
+  }
+
+  function getDomMetrics(element: HTMLDivElement, handle = virtuaHandle(), offset = handle?.scrollOffset ?? element.scrollTop): ScrollControllerMetrics {
+    const scrollHeight = handle ? getCurrentScrollSize(element, handle) : element.scrollHeight
+    return {
+      offset,
+      scrollHeight,
+      clientHeight: handle?.viewportSize ?? element.clientHeight,
+      sentinelMarginPx: props.scrollSentinelMarginPx ?? DEFAULT_SCROLL_SENTINEL_MARGIN_PX,
+    }
+  }
+
+  function scrollToOffset(offset: number, atBottom: boolean) {
+    const handle = virtuaHandle()
+    const element = scrollElement()
+    if (!element) return
+    const maxOffset = Math.max((handle?.scrollSize ?? element.scrollHeight) - (handle?.viewportSize ?? element.clientHeight), 0)
+    const nextOffset = Math.min(Math.max(offset, 0), maxOffset)
+    markProgrammaticScroll()
+    if (handle) {
+      handle.scrollTo(nextOffset)
+    } else {
+      element.scrollTop = nextOffset
+    }
+    scrollController.recordProgrammaticOffset(nextOffset, atBottom)
+  }
+
+  function getManualMetrics(atBottom: boolean): ScrollControllerMetrics {
+    const clientHeight = 1000
+    const sentinelMarginPx = props.scrollSentinelMarginPx ?? DEFAULT_SCROLL_SENTINEL_MARGIN_PX
+    const distance = atBottom ? 0 : clientHeight
+    return {
+      offset: 0,
+      scrollHeight: clientHeight + distance,
+      clientHeight,
+      sentinelMarginPx,
+    }
+  }
+
+  function canRejoinFollowFromDownScroll(metrics: ScrollControllerMetrics) {
+    if (!streamingActive()) return false
+    if (autoPinHoldEnabled()) return false
+    if (effectiveSuspendAutoPinToBottom()) return false
+    if (activeHoldTargetKey() !== null) return false
+    const items = props.items()
+    if (items.length === 0) return false
+    if (isAtBottom(metrics)) return true
+
+    const handle = virtuaHandle()
+    if (!handle) return false
+    const viewportEndIndex = handle.findItemIndex(metrics.offset + metrics.clientHeight - 1)
+    return viewportEndIndex >= Math.max(items.length - DEFAULT_REJOIN_LAST_ITEM_COUNT, 0)
+  }
+
+  function getSnapshotMetrics(element: HTMLDivElement, handle?: VirtualizerHandle) {
+    const scrollTop = handle?.scrollOffset ?? element.scrollTop
+    const scrollHeight = handle ? getCurrentScrollSize(element, handle) : element.scrollHeight
+    const clientHeight = handle?.viewportSize ?? element.clientHeight
+    const maxScrollTop = Math.max(scrollHeight - clientHeight, 0)
+    const atBottom = scrollHeight - (scrollTop + clientHeight) <= (props.scrollSentinelMarginPx ?? DEFAULT_SCROLL_SENTINEL_MARGIN_PX)
+    return {
+      scrollTop,
+      scrollRatio: maxScrollTop > 0 ? scrollTop / maxScrollTop : 0,
+      maxScrollTop,
+      atBottom,
+    }
+  }
+
+  function findTopVisibleAnchor(element: HTMLDivElement) {
+    const containerRect = element.getBoundingClientRect()
+    let closestAbove: { key: string; offset: number } | null = null
+    let closestBelow: { key: string; offset: number } | null = null
+
+    for (const [key, itemElement] of itemElements) {
+      const rect = itemElement.getBoundingClientRect()
+      if (rect.bottom <= containerRect.top || rect.top >= containerRect.bottom) continue
+
+      const offset = rect.top - containerRect.top
+      if (offset <= 0) {
+        if (!closestAbove || offset > closestAbove.offset) closestAbove = { key, offset }
+      } else if (!closestBelow || offset < closestBelow.offset) {
+        closestBelow = { key, offset }
+      }
+    }
+
+    return closestAbove ?? closestBelow
+  }
+
+  function captureScrollSnapshot(): VirtualFollowScrollSnapshot | undefined {
+    const element = scrollElement()
+    if (!element) return undefined
+
+    const snapshot: VirtualFollowScrollSnapshot = getSnapshotMetrics(element, virtuaHandle())
+    if (!snapshot.atBottom) {
+      const anchor = findTopVisibleAnchor(element)
+      if (anchor) {
+        snapshot.anchorKey = anchor.key
+        snapshot.anchorOffset = anchor.offset
+      }
+    }
+    return snapshot
+  }
+
+  function applyPixelSnapshot(snapshot: VirtualFollowScrollSnapshot, behavior: ScrollBehavior) {
+    const element = scrollElement()
+    if (!element) return
+
+    const handle = virtuaHandle()
+    const maxScrollTop = Math.max((handle?.scrollSize ?? element.scrollHeight) - (handle?.viewportSize ?? element.clientHeight), 0)
+    const scrollRatio = snapshot.scrollRatio
+    const canUseRatio =
+      !snapshot.atBottom &&
+      typeof scrollRatio === "number" &&
+      Number.isFinite(scrollRatio) &&
+      snapshot.maxScrollTop !== maxScrollTop
+    const nextTop = snapshot.atBottom
+      ? maxScrollTop
+      : canUseRatio
+        ? Math.min(Math.max(scrollRatio, 0), 1) * maxScrollTop
+        : Math.min(snapshot.scrollTop, maxScrollTop)
+
+    if (behavior === "smooth" && !virtuaHandle()) {
+      markProgrammaticScroll()
+      element.scrollTo({ top: nextTop, behavior })
+      scrollController.recordProgrammaticOffset(nextTop, snapshot.atBottom)
+      return
+    }
+    scrollToOffset(nextTop, snapshot.atBottom)
+  }
+
+  function applyAnchorSnapshot(snapshot: VirtualFollowScrollSnapshot) {
+    const element = scrollElement()
+    if (!element || !snapshot.anchorKey || typeof snapshot.anchorOffset !== "number") return false
+
+    const itemWrapper = itemElements.get(snapshot.anchorKey)
+    if (!itemWrapper) return false
+
+    const containerRect = element.getBoundingClientRect()
+    const itemRect = itemWrapper.getBoundingClientRect()
+    const currentOffset = itemRect.top - containerRect.top
+    const delta = currentOffset - snapshot.anchorOffset
+    if (Math.abs(delta) > 1) {
+      scrollToOffset((virtuaHandle()?.scrollOffset ?? element.scrollTop) + delta, false)
+    }
+    return true
+  }
+
+  function applyBottomSnapshot() {
+    const element = scrollElement()
+    if (!element) return
+    const handle = virtuaHandle()
+    const maxOffset = Math.max((handle?.scrollSize ?? element.scrollHeight) - (handle?.viewportSize ?? element.clientHeight), 0)
+    scrollToOffset(maxOffset, true)
+  }
+
+  function restoreScrollSnapshot(snapshot: VirtualFollowScrollSnapshot, opts?: RestoreScrollSnapshotOptions) {
+    const element = scrollElement()
+    if (!element) {
+      opts?.fallback?.()
+      opts?.onApplied?.()
+      return
+    }
+
+    const behavior = opts?.behavior ?? "auto"
+    scrollController.setRestoring(true)
+    const finishRestore = () => {
+      scrollController.setRestoring(false)
+      opts?.onApplied?.()
+    }
+    if (snapshot.atBottom) {
+      applyBottomSnapshot()
+      requestAnimationFrame(() => {
+        applyBottomSnapshot()
+        finishRestore()
+      })
+      return
+    }
+
+    if (snapshot.anchorKey) {
+      const index = props.items().findIndex((item, i) => props.getKey(item, i) === snapshot.anchorKey)
+      if (index !== -1) {
+        markProgrammaticScroll()
+        virtuaHandle()?.scrollToIndex(index, { align: "start", smooth: behavior === "smooth" })
+        retryAnchorRestore(snapshot, behavior, 6, finishRestore)
+        return
+      }
+    }
+
+    applyPixelSnapshot(snapshot, behavior)
+    requestAnimationFrame(finishRestore)
+  }
+
+  function retryAnchorRestore(snapshot: VirtualFollowScrollSnapshot, behavior: ScrollBehavior, remainingFrames: number, onApplied?: () => void) {
+    requestAnimationFrame(() => {
+      const applied = applyAnchorSnapshot(snapshot)
+      if (applied) {
+        requestAnimationFrame(() => {
+          applyAnchorSnapshot(snapshot)
+          onApplied?.()
+        })
+        return
+      }
+
+      if (remainingFrames > 0) {
+        retryAnchorRestore(snapshot, behavior, remainingFrames - 1, onApplied)
+        return
+      }
+
+      applyPixelSnapshot(snapshot, behavior)
+      requestAnimationFrame(() => onApplied?.())
+    })
+  }
+
   function updateScrollButtons() {
     const handle = virtuaHandle()
     const element = scrollElement()
     if (!handle || !element) return
 
-    const offset = handle.scrollOffset
-    const scrolledUp = offset < lastObservedScrollOffset - 1
-    const wasPinnedAtBottom = lastObservedPinnedAtBottom
-    const scrollHeight = handle.scrollSize
-    const clientHeight = element.clientHeight
-    const atBottom = scrollHeight - (offset + clientHeight) <= (props.scrollSentinelMarginPx ?? DEFAULT_SCROLL_SENTINEL_MARGIN_PX)
+    const offset = getCurrentScrollOffset(element, handle)
+    const now = performance.now()
+    const programmatic = hasProgrammaticScrollIntent()
+    const metrics = getDomMetrics(element, handle, offset)
+    const atBottom = isAtBottom(metrics)
     const atTop = offset <= (props.scrollSentinelMarginPx ?? DEFAULT_SCROLL_SENTINEL_MARGIN_PX)
-    lastObservedScrollOffset = offset
 
     const hasItems = props.items().length > 0
     setShowScrollBottomButton(hasItems && !atBottom)
     setShowScrollTopButton(hasItems && !atTop)
 
-    // Keyboard/PageUp scrolls can move the viewport without ever hitting our
-    // local key intent listeners (for example after dragging the native
-    // scrollbar). If follow mode stays enabled, the next render notification
-    // snaps the list straight back to bottom. A real upward viewport move away
-    // from bottom should always break follow unless a hold target is active.
-    if (wasPinnedAtBottom && scrolledUp && autoScroll() && !atBottom && activeHoldTargetKey() === null) {
-      setAutoScroll(false)
-      lastObservedPinnedAtBottom = false
-      return
+    const result = scrollController.observeViewport(metrics, now, programmatic, canRejoinFollowFromDownScroll(metrics))
+    if (result.state.mode.type !== followMode().type || result.effect.type !== "none") {
+      suppressHoldUntilTargetChanges = false
     }
+    syncControllerResult(result)
+  }
 
-    // Sync autoScroll state based on scroll position if it was a user scroll
-    if (hasUserScrollIntent()) {
-      clearAutoPinHold()
-      if (atBottom && !autoScroll()) {
-        setAutoScroll(true)
-      } else if (!atBottom && autoScroll()) {
-        setAutoScroll(false)
-      }
+  function performScrollToBottom(immediate = true) {
+    const handle = virtuaHandle()
+    const element = scrollElement()
+    if (!handle || props.items().length === 0) return
+    if (immediate && element) {
+      markProgrammaticScroll()
+      handle.scrollToIndex(props.items().length - 1, { align: "end", smooth: false })
+      pinDomBottomAfterLayout()
+      return
     }
+    markProgrammaticScroll()
+    handle.scrollToIndex(props.items().length - 1, { align: "end", smooth: !immediate })
+  }
+
+  function pinDomBottomAfterLayout(remainingFrames = 2) {
+    const element = scrollElement()
+    if (!element) return
+    if (!autoScroll() || effectiveSuspendAutoPinToBottom() || scrollController.snapshot().restoring) return
+    if (shouldHonorPrePinEscape() && escapeFollowIfDomMovedUp(element)) return
 
-    lastObservedPinnedAtBottom = autoScroll() && atBottom
+    const handle = virtuaHandle()
+    const maxOffset = Math.max((handle?.scrollSize ?? element.scrollHeight) - (handle?.viewportSize ?? element.clientHeight), 0)
+    scrollToOffset(maxOffset, true)
+    if (remainingFrames <= 0) return
+
+    requestAnimationFrame(() => {
+      if (!autoScroll() || effectiveSuspendAutoPinToBottom() || scrollController.snapshot().restoring) return
+      pinDomBottomAfterLayout(remainingFrames - 1)
+    })
   }
 
-  function scrollToBottom(immediate = true, options?: { suppressAutoAnchor?: boolean }) {
+  function performScrollToTop(immediate = true) {
     const handle = virtuaHandle()
+    const element = scrollElement()
     if (!handle) return
+    if (immediate && element) {
+      scrollToOffset(0, false)
+      return
+    }
+    markProgrammaticScroll()
+    handle.scrollToIndex(0, { align: "start", smooth: !immediate })
+  }
+
+  function performScrollToKey(key: string, opts: { block: ScrollLogicalPosition; smooth: boolean }) {
+    const index = props.items().findIndex((item, i) => props.getKey(item, i) === key)
+    if (index === -1) return
+    markProgrammaticScroll()
+    virtuaHandle()?.scrollToIndex(index, { align: opts.block, smooth: opts.smooth })
+  }
+
+  function scrollToBottom(immediate = true, options?: { suppressAutoAnchor?: boolean; suppressHold?: boolean }) {
     if (options?.suppressAutoAnchor ?? !immediate) {
       suppressAutoScrollOnce = true
     }
-    handle.scrollToIndex(props.items().length - 1, { align: "end", smooth: !immediate })
-    setAutoScroll(true)
+    dispatchFollowEvent({ type: "jump-bottom", immediate, explicit: options?.suppressHold ?? false })
   }
 
   function scrollToTop(immediate = true) {
-    const handle = virtuaHandle()
-    if (!handle) return
-    handle.scrollToIndex(0, { align: "start", smooth: !immediate })
-    setAutoScroll(false)
+    dispatchFollowEvent({ type: "jump-top", immediate })
   }
 
   function handleScroll() {
-    const isUserScroll = hasUserScrollIntent()
-    if (isUserScroll) {
-      if (lastUserScrollIntentDirection === "up" && autoScroll()) {
-        setAutoScroll(false)
-      }
-    }
     updateScrollButtons()
     props.onScroll?.()
 
     // Find active key (roughly the first visible item)
     const handle = virtuaHandle()
-    if (handle) {
-      const start = handle.findItemIndex(handle.scrollOffset)
+    const element = scrollElement()
+    if (handle && element) {
+      const start = handle.findItemIndex(getCurrentScrollOffset(element, handle))
       const items = props.items()
       if (items[start]) {
         const key = props.getKey(items[start], start)
@@ -342,6 +680,21 @@ export default function VirtualFollowList<T>(props: VirtualFollowListProps<T>) {
     return props.getAnchorId ? props.getAnchorId(key) : key
   }
 
+  function alignHoldTarget(key: string) {
+    const element = scrollElement()
+    if (!element) return
+    const itemWrapper = itemElements.get(key)
+    if (!itemWrapper) return
+    const target = props.resolveAutoPinHoldElement?.(itemWrapper, key) ?? itemWrapper
+    const containerRect = element.getBoundingClientRect()
+    const targetRect = target.getBoundingClientRect()
+    const relativeTop = targetRect.top - containerRect.top
+    const alignDelta = relativeTop - holdTargetTopThresholdPx()
+    if (Math.abs(alignDelta) > 1) {
+      scrollToOffset((virtuaHandle()?.scrollOffset ?? element.scrollTop) + alignDelta, false)
+    }
+  }
+
   function updateAutoPinHold() {
     const element = scrollElement()
     if (!element) return
@@ -351,16 +704,18 @@ export default function VirtualFollowList<T>(props: VirtualFollowListProps<T>) {
 
     if (heldKey !== null) {
       if (targetKey !== heldKey) {
-        clearAutoPinHold({ resumeBottom: true })
+        dispatchFollowEvent({ type: "hold-target-changed", key: targetKey, canPinToBottom: !externalSuspendAutoPinToBottom() })
       }
 
       return
     }
 
+    if (!streamingActive()) return
     if (!autoScroll()) return
     if (externalSuspendAutoPinToBottom()) return
     if (!targetKey) return
     if (didTriggerHoldForCurrentTarget()) return
+    if (suppressHoldUntilTargetChanges) return
 
     const itemWrapper = itemElements.get(targetKey)
     if (!itemWrapper) return
@@ -372,36 +727,47 @@ export default function VirtualFollowList<T>(props: VirtualFollowListProps<T>) {
     const exceedsViewport = targetRect.height > element.clientHeight
 
     if (exceedsViewport && relativeTop < 0) {
-      const alignDelta = relativeTop - holdTargetTopThresholdPx()
-      if (Math.abs(alignDelta) > 1) {
-        element.scrollTop = Math.max(0, element.scrollTop + alignDelta)
-      }
-      setActiveHoldTargetKey(targetKey)
+      dispatchFollowEvent({ type: "hold-candidate", key: targetKey, shouldHold: true })
       setDidTriggerHoldForCurrentTarget(true)
     }
   }
 
   const api: VirtualFollowListApi = {
     scrollToTop: (opts) => scrollToTop(opts?.immediate ?? true),
-    scrollToBottom: (opts) => scrollToBottom(opts?.immediate ?? true, { suppressAutoAnchor: opts?.suppressAutoAnchor }),
+    scrollToBottom: (opts) => scrollToBottom(opts?.immediate ?? true, { suppressAutoAnchor: opts?.suppressAutoAnchor, suppressHold: opts?.suppressHold }),
     scrollToKey: (key, opts) => {
       const index = props.items().findIndex((item, i) => props.getKey(item, i) === key)
       if (index === -1) return
       const nextAutoScroll = opts?.setAutoScroll ?? false
-      setAutoScroll(nextAutoScroll)
-      virtuaHandle()?.scrollToIndex(index, { align: opts?.block ?? "start", smooth: opts?.behavior === "smooth" })
+      dispatchFollowEvent({
+        type: "jump-key",
+        key,
+        block: opts?.block ?? "start",
+        smooth: opts?.behavior === "smooth",
+        followAfter: nextAutoScroll,
+      })
     },
     notifyContentRendered: () => {
+      if (shouldHonorPrePinEscape() && escapeFollowIfDomMovedUp()) {
+        updateScrollButtons()
+        return
+      }
       updateAutoPinHold()
-      if (activeHoldTargetKey() !== null) return
-      if (autoScroll() && !effectiveSuspendAutoPinToBottom()) {
-        scrollToBottom(true)
+      if (activeHoldTargetKey() !== null) {
+        if (autoScroll() && streamingActive()) pendingBottomRepinAfterHold = true
+        updateScrollButtons()
+        return
       }
+      const canPinToBottom = autoScroll() && !effectiveSuspendAutoPinToBottom()
+      dispatchFollowEvent({ type: "content-grew", canPinToBottom })
+      updateScrollButtons()
     },
-    setAutoScroll: (enabled) => setAutoScroll(Boolean(enabled)),
+    setAutoScroll: (enabled) => dispatchFollowEvent({ type: "set-follow", enabled: Boolean(enabled) }),
     getAutoScroll: () => autoScroll(),
     getScrollElement: () => scrollElement(),
     getShellElement: () => shellElement(),
+    captureScrollSnapshot,
+    restoreScrollSnapshot,
   }
 
   createEffect(() => props.registerApi?.(api))
@@ -409,33 +775,50 @@ export default function VirtualFollowList<T>(props: VirtualFollowListProps<T>) {
 
   createEffect(on(() => props.resetKey?.(), () => {
     itemElements.clear()
-    setActiveHoldTargetKey(null)
     setDidTriggerHoldForCurrentTarget(false)
-    lastObservedScrollOffset = 0
-    lastObservedPinnedAtBottom = false
+    suppressHoldUntilTargetChanges = false
+    pendingBottomRepinAfterHold = false
   }))
 
   createEffect(on(holdTargetKey, (nextTargetKey, prevTargetKey) => {
     if (nextTargetKey !== prevTargetKey && didTriggerHoldForCurrentTarget()) {
       setDidTriggerHoldForCurrentTarget(false)
     }
+    if (nextTargetKey !== prevTargetKey) {
+      suppressHoldUntilTargetChanges = false
+    }
     if (activeHoldTargetKey() === null) return
     if (nextTargetKey === activeHoldTargetKey()) return
-    clearAutoPinHold({ resumeBottom: true })
+    dispatchFollowEvent({ type: "hold-target-changed", key: nextTargetKey, canPinToBottom: !externalSuspendAutoPinToBottom() })
+    if (pendingBottomRepinAfterHold) {
+      pendingBottomRepinAfterHold = false
+      requestAnimationFrame(() => pinDomBottomAfterLayout())
+    }
   }, { defer: true }))
 
   // Handle autoScroll (Follow) on items change
   createEffect(on(() => props.items().length, (len, prevLen) => {
+    if (pendingInitialScroll && isActive() && len > 0) {
+      pendingInitialScroll = false
+      if (initialScrollToBottom()) {
+        dispatchFollowEvent({ type: "jump-bottom", immediate: true, explicit: false })
+      }
+      suppressAutoScrollOnce = false
+      return
+    }
     if (len > (prevLen ?? 0) && autoScroll() && !effectiveSuspendAutoPinToBottom() && !suppressAutoScrollOnce) {
-      requestAnimationFrame(() => scrollToBottom(true))
+      requestAnimationFrame(() => {
+        dispatchFollowEvent({ type: "content-grew", canPinToBottom: autoScroll() && !effectiveSuspendAutoPinToBottom() })
+      })
     }
     suppressAutoScrollOnce = false
   }, { defer: true }))
 
   // Handle followToken change
   createEffect(on(() => props.followToken?.(), () => {
-    if (autoScroll() && !effectiveSuspendAutoPinToBottom()) {
-      scrollToBottom(true)
+    const canPinToBottom = autoScroll() && !effectiveSuspendAutoPinToBottom()
+    if (canPinToBottom) {
+      dispatchFollowEvent({ type: "content-grew", canPinToBottom })
     }
   }, { defer: true }))
 
@@ -443,22 +826,26 @@ export default function VirtualFollowList<T>(props: VirtualFollowListProps<T>) {
   createEffect(on(() => props.resetKey?.(), (nextKey) => {
     if (nextKey === lastResetKey) return
     lastResetKey = nextKey
-    setAutoScroll(initialAutoScroll())
+    dispatchFollowEvent({ type: "reset", follow: Boolean(initialAutoScroll()) })
     pendingInitialScroll = true
   }))
 
   // Initial scroll and session activation
-  createEffect(() => {
-    const active = isActive()
+  createEffect(on(isActive, (active) => {
     if (!active) return
     if (pendingInitialScroll && props.items().length > 0) {
       pendingInitialScroll = false
       if (initialScrollToBottom()) {
-        scrollToBottom(true)
+        dispatchFollowEvent({ type: "jump-bottom", immediate: true, explicit: false })
       }
     } else if (autoScroll() && scrollToBottomOnActivate()) {
-      scrollToBottom(true)
+      dispatchFollowEvent({ type: "jump-bottom", immediate: true, explicit: false })
     }
+  }))
+
+  onCleanup(() => {
+    detachScrollIntentListeners?.()
+    detachScrollIntentListeners = undefined
   })
 
   return (
@@ -523,7 +910,7 @@ export default function VirtualFollowList<T>(props: VirtualFollowListProps<T>) {
             </button>
           </Show>
           <Show when={showScrollBottomButton()}>
-            <button type="button" class="message-scroll-button" onClick={() => scrollToBottom()} aria-label={props.scrollToBottomAriaLabel!()}>
+            <button type="button" class="message-scroll-button" onClick={() => scrollToBottom(true, { suppressHold: true })} aria-label={props.scrollToBottomAriaLabel!()}>
               <span class="message-scroll-icon" aria-hidden="true">
                 ↓
               </span>
diff --git a/packages/ui/src/lib/hooks/use-scroll-cache.ts b/packages/ui/src/lib/hooks/use-scroll-cache.ts
deleted file mode 100644
index 1bbe956c2..000000000
--- a/packages/ui/src/lib/hooks/use-scroll-cache.ts
+++ /dev/null
@@ -1,102 +0,0 @@
-import { type Accessor, createMemo } from "solid-js"
-import { messageStoreBus } from "../../stores/message-v2/bus"
-import type { ScrollSnapshot } from "../../stores/message-v2/types"
-
-interface UseScrollCacheParams {
-  instanceId: MaybeAccessor<string>
-  sessionId: MaybeAccessor<string>
-  scope: MaybeAccessor<string>
-}
-
-interface PersistScrollOptions {
-  atBottomOffset?: number
-}
-
-interface RestoreScrollOptions {
-  behavior?: ScrollBehavior
-  fallback?: () => void
-  onApplied?: (snapshot: ScrollSnapshot | undefined) => void
-}
-
-interface ScrollCacheHandle {
-  persist: (element: HTMLElement | null | undefined, options?: PersistScrollOptions) => ScrollSnapshot | undefined
-  restore: (element: HTMLElement | null | undefined, options?: RestoreScrollOptions) => void
-}
-
-const DEFAULT_BOTTOM_OFFSET = 48
-
-/**
- * Wraps the message-store scroll snapshot helpers so components can
- * persist/restore scroll positions without duplicating requestAnimationFrame
- * boilerplate.
- */
-export function useScrollCache(params: UseScrollCacheParams): ScrollCacheHandle {
-  const resolved = createMemo(() => ({
-    instanceId: resolveValue(params.instanceId),
-    sessionId: resolveValue(params.sessionId),
-    scope: resolveValue(params.scope),
-  }))
-
-  const store = createMemo(() => {
-    const { instanceId } = resolved()
-    return messageStoreBus.getOrCreate(instanceId)
-  })
-
-  function persist(element: HTMLElement | null | undefined, options?: PersistScrollOptions) {
-    if (!element) {
-      return undefined
-    }
-    const target = resolved()
-    if (!target.sessionId) {
-      return undefined
-    }
-    const snapshot: Omit<ScrollSnapshot, "updatedAt"> = {
-      scrollTop: element.scrollTop,
-      atBottom: isNearBottom(element, options?.atBottomOffset ?? DEFAULT_BOTTOM_OFFSET),
-    }
-    store().setScrollSnapshot(target.sessionId, target.scope, snapshot)
-    return { ...snapshot, updatedAt: Date.now() }
-  }
-
-  function restore(element: HTMLElement | null | undefined, options?: RestoreScrollOptions) {
-    const target = resolved()
-    if (!element || !target.sessionId) {
-      options?.fallback?.()
-      options?.onApplied?.(undefined)
-      return
-    }
-    const snapshot = store().getScrollSnapshot(target.sessionId, target.scope)
-    requestAnimationFrame(() => {
-      if (!element) {
-        options?.onApplied?.(snapshot)
-        return
-      }
-      if (!snapshot) {
-        options?.fallback?.()
-        options?.onApplied?.(undefined)
-        return
-      }
-      const maxScrollTop = Math.max(element.scrollHeight - element.clientHeight, 0)
-      const nextTop = snapshot.atBottom ? maxScrollTop : Math.min(snapshot.scrollTop, maxScrollTop)
-      const behavior = options?.behavior ?? "auto"
-      element.scrollTo({ top: nextTop, behavior })
-      options?.onApplied?.(snapshot)
-    })
-  }
-
-  return { persist, restore }
-}
-
-function isNearBottom(element: HTMLElement, offset: number) {
-  const { scrollTop, scrollHeight, clientHeight } = element
-  return scrollHeight - (scrollTop + clientHeight) <= offset
-}
-
-function resolveValue<T>(value: MaybeAccessor<T>): T {
-  if (typeof value === "function") {
-    return (value as Accessor<T>)()
-  }
-  return value
-}
-
-type MaybeAccessor<T> = T | Accessor<T>
diff --git a/packages/ui/src/stores/message-v2/types.ts b/packages/ui/src/stores/message-v2/types.ts
index 581a896e4..6208d475e 100644
--- a/packages/ui/src/stores/message-v2/types.ts
+++ b/packages/ui/src/stores/message-v2/types.ts
@@ -75,6 +75,10 @@ export interface InstanceQuestionState {
 
 export interface ScrollSnapshot {
   scrollTop: number
+  scrollRatio?: number
+  maxScrollTop?: number
+  anchorKey?: string
+  anchorOffset?: number
   atBottom: boolean
   updatedAt: number
 }

From ba05b8e087709448d06e8f9ca11042613f157d36 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Pascal=20Andr=C3=A9?= <pascalandr@gmail.com>
Date: Fri, 8 May 2026 15:05:31 +0200
Subject: [PATCH 2/4] fix(ui): harden virtual follow review issues

Keep last-good scroll snapshots keyed by session so cleanup during session switches cannot write another session's snapshot under the previous session id. Also allow streaming rejoin while the hold preference is enabled when no hold target is actively suspending bottom pinning.

Validation: node --test packages/ui/src/components/virtual-follow-behavior.test.ts and npm run typecheck --workspace @codenomad/ui.
---
 .../ui/src/components/message-section.tsx     | 25 +++++++++++++------
 .../ui/src/components/virtual-follow-list.tsx |  3 ---
 2 files changed, 18 insertions(+), 10 deletions(-)

diff --git a/packages/ui/src/components/message-section.tsx b/packages/ui/src/components/message-section.tsx
index 6a2e42551..15f2040b6 100644
--- a/packages/ui/src/components/message-section.tsx
+++ b/packages/ui/src/components/message-section.tsx
@@ -655,14 +655,24 @@ export default function MessageSection(props: MessageSectionProps) {
   const initialAutoScroll = createMemo(() => initialScrollSnapshot()?.atBottom ?? true)
 
   const [didRestoreScroll, setDidRestoreScroll] = createSignal(false)
-  let lastGoodScrollSnapshot: VirtualFollowScrollSnapshot | undefined
+  const lastGoodScrollSnapshots = new Map<string, VirtualFollowScrollSnapshot>()
   let restoringScrollSnapshot = false
+
+  function getLastGoodScrollSnapshot(sessionId: string) {
+    return lastGoodScrollSnapshots.get(sessionId) ?? store().getScrollSnapshot(sessionId, MESSAGE_SCROLL_CACHE_SCOPE)
+  }
+
+  function setLastGoodScrollSnapshot(sessionId: string, snapshot: VirtualFollowScrollSnapshot) {
+    lastGoodScrollSnapshots.set(sessionId, snapshot)
+  }
+
   createEffect(
     on(
       () => props.sessionId,
       () => {
         setDidRestoreScroll(false)
-        lastGoodScrollSnapshot = store().getScrollSnapshot(props.sessionId, MESSAGE_SCROLL_CACHE_SCOPE)
+        const snapshot = store().getScrollSnapshot(props.sessionId, MESSAGE_SCROLL_CACHE_SCOPE)
+        if (snapshot) setLastGoodScrollSnapshot(props.sessionId, snapshot)
       },
     ),
   )
@@ -702,12 +712,13 @@ export default function MessageSection(props: MessageSectionProps) {
     if (allowCapture && canCapture) {
       const snapshot = listApi()?.captureScrollSnapshot()
       if (snapshot) {
-        lastGoodScrollSnapshot = snapshot
+        setLastGoodScrollSnapshot(sessionId, snapshot)
         store().setScrollSnapshot(sessionId, MESSAGE_SCROLL_CACHE_SCOPE, snapshot)
         return
       }
     }
 
+    const lastGoodScrollSnapshot = getLastGoodScrollSnapshot(sessionId)
     if (lastGoodScrollSnapshot) {
       store().setScrollSnapshot(sessionId, MESSAGE_SCROLL_CACHE_SCOPE, lastGoodScrollSnapshot)
       return
@@ -720,8 +731,9 @@ export default function MessageSection(props: MessageSectionProps) {
     const maxScrollTop = Math.max(element.scrollHeight - element.clientHeight, 0)
     const scrollRatio = maxScrollTop > 0 ? scrollTop / maxScrollTop : 0
     const atBottom = element.scrollHeight - (element.scrollTop + element.clientHeight) <= 48
-    lastGoodScrollSnapshot = { scrollTop, scrollRatio, maxScrollTop, atBottom }
-    store().setScrollSnapshot(sessionId, MESSAGE_SCROLL_CACHE_SCOPE, lastGoodScrollSnapshot)
+    const snapshot = { scrollTop, scrollRatio, maxScrollTop, atBottom }
+    setLastGoodScrollSnapshot(sessionId, snapshot)
+    store().setScrollSnapshot(sessionId, MESSAGE_SCROLL_CACHE_SCOPE, snapshot)
   }
 
   // Persist scroll position when switching sessions. This effect's cleanup runs
@@ -813,7 +825,7 @@ export default function MessageSection(props: MessageSectionProps) {
         // Keep follow mode consistent with the restored state.
         api.setAutoScroll(snapshot.atBottom)
         restoringScrollSnapshot = false
-        lastGoodScrollSnapshot = snapshot
+        setLastGoodScrollSnapshot(props.sessionId, snapshot)
         setDidRestoreScroll(true)
       },
     })
@@ -1311,7 +1323,6 @@ export default function MessageSection(props: MessageSectionProps) {
           scrollSentinelMarginPx={SCROLL_SENTINEL_MARGIN_PX}
           suspendMeasurements={() => !isActive()}
           streamingActive={streamingActive}
-          autoPinHoldEnabled={holdLongAssistantRepliesEnabled}
           isActive={isActive}
           scrollToBottomOnActivate={() => false}
           initialScrollToBottom={() => false}
diff --git a/packages/ui/src/components/virtual-follow-list.tsx b/packages/ui/src/components/virtual-follow-list.tsx
index 1a44a3b77..147b1ed89 100644
--- a/packages/ui/src/components/virtual-follow-list.tsx
+++ b/packages/ui/src/components/virtual-follow-list.tsx
@@ -105,7 +105,6 @@ export interface VirtualFollowListProps<T> {
    * rendered item grows taller than the viewport and reaches the top edge.
    */
   autoPinHoldTargetKey?: Accessor<string | null>
-  autoPinHoldEnabled?: Accessor<boolean>
 
   /**
    * Optional resolver for the specific element inside an item wrapper that
@@ -170,7 +169,6 @@ export default function VirtualFollowList<T>(props: VirtualFollowListProps<T>) {
   const initialAutoScroll = () => (props.initialAutoScroll ? props.initialAutoScroll() : true)
   const externalSuspendAutoPinToBottom = () => (props.suspendAutoPinToBottom ? props.suspendAutoPinToBottom() : false)
   const streamingActive = () => props.streamingActive?.() ?? false
-  const autoPinHoldEnabled = () => props.autoPinHoldEnabled?.() ?? false
   const holdTargetKey = () => (props.autoPinHoldTargetKey ? props.autoPinHoldTargetKey() : null)
   const holdTargetTopThresholdPx = () => props.autoPinHoldTopThresholdPx ?? DEFAULT_HOLD_TARGET_TOP_THRESHOLD_PX
 
@@ -392,7 +390,6 @@ export default function VirtualFollowList<T>(props: VirtualFollowListProps<T>) {
 
   function canRejoinFollowFromDownScroll(metrics: ScrollControllerMetrics) {
     if (!streamingActive()) return false
-    if (autoPinHoldEnabled()) return false
     if (effectiveSuspendAutoPinToBottom()) return false
     if (activeHoldTargetKey() !== null) return false
     const items = props.items()

From e7ac50a44c602ff2443681f3b3ac92e00307fe6c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Pascal=20Andr=C3=A9?= <pascalandr@gmail.com>
Date: Sat, 16 May 2026 16:24:30 +0200
Subject: [PATCH 3/4] perf(ui): coalesce virtual follow content render
 notifications

Fast streaming renders can notify VirtualFollowList multiple times in the same animation frame, repeating follow reconciliation, Virtua metric reads, and bottom-pin checks. Coalescing notifyContentRendered behind a single RAF keeps the existing follow and hold behavior while capping duplicate same-frame work during rapid updates.

The change preserves the current notification path, falls back to immediate execution when requestAnimationFrame is unavailable, and cancels pending frames during cleanup so cached panes do not flush stale work after teardown.

Validation:\n- node --test packages/ui/src/components/virtual-follow-behavior.test.ts\n- npm run typecheck --workspace @codenomad/ui
---
 .../ui/src/components/virtual-follow-list.tsx | 40 ++++++++++++++-----
 1 file changed, 29 insertions(+), 11 deletions(-)

diff --git a/packages/ui/src/components/virtual-follow-list.tsx b/packages/ui/src/components/virtual-follow-list.tsx
index 147b1ed89..107a0c18c 100644
--- a/packages/ui/src/components/virtual-follow-list.tsx
+++ b/packages/ui/src/components/virtual-follow-list.tsx
@@ -192,6 +192,7 @@ export default function VirtualFollowList<T>(props: VirtualFollowListProps<T>) {
   let pendingInitialScroll = true
   let programmaticScrollUntil = 0
   let pendingBottomRepinAfterHold = false
+  let pendingContentRenderedFrame: number | null = null
 
   const state: VirtualFollowListState = {
     autoScroll,
@@ -729,6 +730,26 @@ export default function VirtualFollowList<T>(props: VirtualFollowListProps<T>) {
     }
   }
 
+  function flushContentRendered() {
+    pendingContentRenderedFrame = null
+
+    if (shouldHonorPrePinEscape() && escapeFollowIfDomMovedUp()) {
+      updateScrollButtons()
+      return
+    }
+
+    updateAutoPinHold()
+    if (activeHoldTargetKey() !== null) {
+      if (autoScroll() && streamingActive()) pendingBottomRepinAfterHold = true
+      updateScrollButtons()
+      return
+    }
+
+    const canPinToBottom = autoScroll() && !effectiveSuspendAutoPinToBottom()
+    dispatchFollowEvent({ type: "content-grew", canPinToBottom })
+    updateScrollButtons()
+  }
+
   const api: VirtualFollowListApi = {
     scrollToTop: (opts) => scrollToTop(opts?.immediate ?? true),
     scrollToBottom: (opts) => scrollToBottom(opts?.immediate ?? true, { suppressAutoAnchor: opts?.suppressAutoAnchor, suppressHold: opts?.suppressHold }),
@@ -745,19 +766,12 @@ export default function VirtualFollowList<T>(props: VirtualFollowListProps<T>) {
       })
     },
     notifyContentRendered: () => {
-      if (shouldHonorPrePinEscape() && escapeFollowIfDomMovedUp()) {
-        updateScrollButtons()
+      if (typeof requestAnimationFrame !== "function") {
+        flushContentRendered()
         return
       }
-      updateAutoPinHold()
-      if (activeHoldTargetKey() !== null) {
-        if (autoScroll() && streamingActive()) pendingBottomRepinAfterHold = true
-        updateScrollButtons()
-        return
-      }
-      const canPinToBottom = autoScroll() && !effectiveSuspendAutoPinToBottom()
-      dispatchFollowEvent({ type: "content-grew", canPinToBottom })
-      updateScrollButtons()
+      if (pendingContentRenderedFrame !== null) return
+      pendingContentRenderedFrame = requestAnimationFrame(() => flushContentRendered())
     },
     setAutoScroll: (enabled) => dispatchFollowEvent({ type: "set-follow", enabled: Boolean(enabled) }),
     getAutoScroll: () => autoScroll(),
@@ -841,6 +855,10 @@ export default function VirtualFollowList<T>(props: VirtualFollowListProps<T>) {
   }))
 
   onCleanup(() => {
+    if (pendingContentRenderedFrame !== null && typeof cancelAnimationFrame === "function") {
+      cancelAnimationFrame(pendingContentRenderedFrame)
+      pendingContentRenderedFrame = null
+    }
     detachScrollIntentListeners?.()
     detachScrollIntentListeners = undefined
   })

From 681755888f62788c319f3f0b1ca7bf00a2022c8e Mon Sep 17 00:00:00 2001
From: Omer Cohen <639682+omercnet@users.noreply.github.com>
Date: Sat, 16 May 2026 11:07:46 -0400
Subject: [PATCH 4/4] fix(mobile): tappable instance/project tab bar while
 session drawer is open (#459)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

## Summary

Fixes a mobile UX bug where, with the session list (left drawer) open on
phone layout, the still-visible instance/project tab bar at the top was
non-interactive. Tapping a tab did nothing — users had to close the
drawer first and then switch projects/instances.

After this change, tapping a tab in that bar switches the
instance/project **and** the drawer auto-closes in a single gesture,
matching user expectation.

## Root cause

On phone (`max-width: 767px`), `InstanceShell` renders the left session
sidebar via MUI's `Drawer variant="temporary"`. The drawer paper is
offset down to `floatingTopPx()` so the instance tab bar remains
visually visible above it. However, MUI's `Modal` Backdrop is `position:
fixed; inset: 0` and covers the entire viewport — including the area
over the tab bar. The backdrop is styled `backgroundColor: transparent`
(so it's invisible) but it still captures pointer events at `z-index:
60`. Taps over the tab bar hit the transparent backdrop → MUI calls
`onClose` (closing the drawer) but the tab's click handler never fires.

## Implementation

1. **`packages/ui/src/components/instance/instance-shell2.tsx`** —
Constrain the MUI Drawer Backdrop via `sx` overrides on both the left
(session list) and right drawers so the backdrop is bound to the drawer
paper's vertical range (`top: floatingTopPx(); height:
floatingHeight();`) instead of fullscreen. Taps over the tab bar now
reach the tab buttons.

2. **`packages/ui/src/styles/panels/tabs.css`** — Lift
`.tab-bar-instance` to `position: relative; z-index: 70` so it stacks
deterministically above the drawer (z-index 60) across browsers as
defense-in-depth.

3. **`packages/ui/src/components/instance/shell/useDrawerChrome.ts` +
`instance-shell2.tsx`** — Expose `closeFloatingDrawersIfAny` from
`useDrawerChrome` and call it from an `InstanceShell` effect that fires
when `props.isActiveInstance` flips `true → false`. This closes any open
floating drawer on the instance the user just switched away from, so its
previously-open state doesn't bleed back when the user returns to that
tab later.

Tablet (>=768px) and desktop (>=1280px) layouts use pinned drawers (no
temporary modal), so the backdrop constraint and z-index lift are inert
there. The fix applies symmetrically to the right drawer on phone.

## Verification

- `tsc --noEmit` clean.
- `vite build` clean.
- Manual mobile-emulation checklist in the task file
(`tasks/done/058-mobile-session-list-blocks-tab-switch.md`) and SUMMARY
in `evidences/058-mobile-session-list-blocks-tab-switch/`.

## Reviewer manual check (phone viewport <=767px)

- Open session list drawer. Tap a different instance tab → it activates
AND drawer closes.
- Tap "+" while drawer open → folder picker opens, drawer closes.
- Tap Settings / Notifications / Remote while drawer open → action
fires, drawer closes.
- Same checks against the right drawer.
- Tap area below tab bar but outside drawer paper → drawer still closes
(existing backdrop dismissal preserved).
- Resize to tablet and desktop widths → pinned drawers unaffected.
- No visual regression in light or dark theme.

---------

Co-authored-by: Ubuntu <omer@Omer.dn3uxh3znnmu5eefnjnut0i1af.tlvx.internal.cloudapp.net>
Co-authored-by: Shantur Rathore <i@shantur.com>
---
 .../components/instance/instance-shell2.tsx   | 56 +++++++++++++++++++
 .../instance/shell/useDrawerChrome.ts         |  2 +
 2 files changed, 58 insertions(+)

diff --git a/packages/ui/src/components/instance/instance-shell2.tsx b/packages/ui/src/components/instance/instance-shell2.tsx
index 42b98c65c..c2689fdb4 100644
--- a/packages/ui/src/components/instance/instance-shell2.tsx
+++ b/packages/ui/src/components/instance/instance-shell2.tsx
@@ -194,6 +194,7 @@ const InstanceShell2: Component<InstanceShellProps> = (props) => {
     unpinRight: unpinRightDrawer,
     closeLeft: closeLeftDrawer,
     closeRight: closeRightDrawer,
+    closeFloatingDrawersIfAny,
     leftAppBarButtonLabel,
     rightAppBarButtonLabel,
     leftAppBarButtonIcon,
@@ -202,6 +203,45 @@ const InstanceShell2: Component<InstanceShellProps> = (props) => {
     handleRightAppBarButtonClick,
   } = drawerChrome
 
+  // When the user switches away from this instance (e.g., taps a different
+  // instance/project tab while a floating drawer is open on phone), close any
+  // open floating drawers so the previous instance's drawer doesn't remain
+  // visually or interactively open when its tab regains focus later.
+  let wasActiveInstance = Boolean(props.isActiveInstance)
+  createEffect(() => {
+    const isActive = Boolean(props.isActiveInstance)
+    if (wasActiveInstance && !isActive) {
+      closeFloatingDrawersIfAny()
+    }
+    wasActiveInstance = isActive
+  })
+
+  onMount(() => {
+    if (typeof document === "undefined") return
+
+    const handleFloatingDrawerPointerDown = (event: PointerEvent) => {
+      if (!props.isActiveInstance) return
+
+      const hasFloatingDrawerOpen = (!leftPinned() && leftOpen()) || (!rightPinned() && rightOpen())
+      if (!hasFloatingDrawerOpen) return
+
+      const target = event.target
+      if (!(target instanceof Node)) return
+
+      const leftContent = leftDrawerContentEl()
+      const rightContent = rightDrawerContentEl()
+      const leftPaper = leftContent?.closest(".MuiDrawer-paper")
+      const rightPaper = rightContent?.closest(".MuiDrawer-paper")
+      if (leftPaper?.contains(target) || rightPaper?.contains(target)) return
+
+      if (!leftPinned() && leftOpen()) setLeftOpen(false)
+      if (!rightPinned() && rightOpen()) setRightOpen(false)
+    }
+
+    document.addEventListener("pointerdown", handleFloatingDrawerPointerDown, true)
+    onCleanup(() => document.removeEventListener("pointerdown", handleFloatingDrawerPointerDown, true))
+  })
+
   createEffect(() => {
     const instanceId = props.instance.id
     loadBackgroundProcesses(instanceId).catch((error) => {
@@ -607,7 +647,12 @@ const InstanceShell2: Component<InstanceShellProps> = (props) => {
         ModalProps={modalProps}
         sx={{
           zIndex: 60,
+          // The tab bar sits outside the floating drawer. Let its controls
+          // receive the gesture; click-away handling above still closes the
+          // drawer when the target is not inside the drawer content.
+          pointerEvents: "none",
           "& .MuiDrawer-paper": {
+            pointerEvents: "auto",
             width: isPhoneLayout() ? "100vw" : `${sessionSidebarWidth()}px`,
             boxSizing: "border-box",
             borderInlineEnd: isPhoneLayout() ? "none" : "1px solid var(--border-base)",
@@ -620,8 +665,13 @@ const InstanceShell2: Component<InstanceShellProps> = (props) => {
             height: floatingHeight(),
           },
 
+          // Keep backdrop dismissal for the area below the tab bar without
+          // covering the tab bar itself.
           "& .MuiBackdrop-root": {
+            pointerEvents: "auto",
             backgroundColor: "transparent",
+            top: floatingTopPx(),
+            height: floatingHeight(),
           },
         }}
       >
@@ -723,7 +773,10 @@ const InstanceShell2: Component<InstanceShellProps> = (props) => {
         ModalProps={modalProps}
         sx={{
           zIndex: 60,
+          // See the matching override on the left drawer for rationale.
+          pointerEvents: "none",
           "& .MuiDrawer-paper": {
+            pointerEvents: "auto",
             width: isPhoneLayout() ? "100vw" : `${rightDrawerWidth()}px`,
             boxSizing: "border-box",
             borderInlineStart: isPhoneLayout() ? "none" : "1px solid var(--border-base)",
@@ -736,7 +789,10 @@ const InstanceShell2: Component<InstanceShellProps> = (props) => {
             height: floatingHeight(),
           },
           "& .MuiBackdrop-root": {
+            pointerEvents: "auto",
             backgroundColor: "transparent",
+            top: floatingTopPx(),
+            height: floatingHeight(),
           },
         }}
       >
diff --git a/packages/ui/src/components/instance/shell/useDrawerChrome.ts b/packages/ui/src/components/instance/shell/useDrawerChrome.ts
index bccc84441..4b1238176 100644
--- a/packages/ui/src/components/instance/shell/useDrawerChrome.ts
+++ b/packages/ui/src/components/instance/shell/useDrawerChrome.ts
@@ -44,6 +44,7 @@ export interface DrawerChromeApi {
   unpinRight: () => void
   closeLeft: () => void
   closeRight: () => void
+  closeFloatingDrawersIfAny: () => boolean
   leftAppBarButtonLabel: Accessor<string>
   rightAppBarButtonLabel: Accessor<string>
   leftAppBarButtonIcon: Accessor<JSX.Element>
@@ -250,6 +251,7 @@ export function useDrawerChrome(options: UseDrawerChromeOptions): DrawerChromeAp
     unpinRight,
     closeLeft,
     closeRight,
+    closeFloatingDrawersIfAny,
     leftAppBarButtonLabel,
     rightAppBarButtonLabel,
     leftAppBarButtonIcon,