Fix terminal scroll glitch and add auto-follow toggle button

Prevent viewport jumping during Claude output by only re-enabling
auto-follow on user-initiated scrolls (wheel events within 300ms),
not on write-triggered xterm scroll events. Add a "Following/Paused"
toggle button in the top-right corner of the terminal.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

app/src/components/terminal/TerminalView.tsx

@@ -35,7 +35,12 @@ export default function TerminalView({ sessionId, active }: Props) {
   const [detectedUrl, setDetectedUrl] = useState<string | null>(null);
   const [imagePasteMsg, setImagePasteMsg] = useState<string | null>(null);
   const [isAtBottom, setIsAtBottom] = useState(true);
+  const [isAutoFollow, setIsAutoFollow] = useState(true);
   const isAtBottomRef = useRef(true);
+  // Tracks user intent to follow output — only set to false by explicit user
+  // actions (mouse wheel up), not by xterm scroll events during writes.
+  const autoFollowRef = useRef(true);
+  const lastUserScrollTimeRef = useRef(0);
 
   useEffect(() => {
     if (!containerRef.current) return;
@@ -132,19 +137,42 @@ export default function TerminalView({ sessionId, active }: Props) {
       sendInput(sessionId, data);
     });
 
+    // Detect user-initiated scroll-up (mouse wheel) to pause auto-follow.
+    // Captured during capture phase so it fires before xterm's own handler.
+    const handleWheel = (e: WheelEvent) => {
+      lastUserScrollTimeRef.current = Date.now();
+      if (e.deltaY < 0) {
+        autoFollowRef.current = false;
+        setIsAutoFollow(false);
+      }
+    };
+    containerRef.current.addEventListener("wheel", handleWheel, { capture: true, passive: true });
+
     // Track scroll position to show "Jump to Current" button.
     // Debounce state updates via rAF to avoid excessive re-renders during rapid output.
     let scrollStateRafId: number | null = null;
     const scrollDisposable = term.onScroll(() => {
       const buf = term.buffer.active;
       const atBottom = buf.viewportY >= buf.baseY;
+      const prevAtBottom = isAtBottomRef.current;
       isAtBottomRef.current = atBottom;
+
+      // Re-enable auto-follow only when USER scrolls to bottom (not write-triggered)
+      const isUserScroll = (Date.now() - lastUserScrollTimeRef.current) < 300;
+      if (atBottom && isUserScroll && !autoFollowRef.current) {
+        autoFollowRef.current = true;
+        setIsAutoFollow(true);
+      }
+
+      // Only update React state when value changes
+      if (atBottom !== prevAtBottom) {
         if (scrollStateRafId === null) {
           scrollStateRafId = requestAnimationFrame(() => {
             scrollStateRafId = null;
             setIsAtBottom(isAtBottomRef.current);
           });
         }
+      }
     });
 
     // Track text selection to show copy hint in status bar
@@ -198,11 +226,12 @@ export default function TerminalView({ sessionId, active }: Props) {
     const outputPromise = onOutput(sessionId, (data) => {
       if (aborted) return;
       term.write(data, () => {
-        // Keep viewport pinned to bottom when user hasn't scrolled up.
+        if (autoFollowRef.current) {
-        // Check ref at callback time (not capture time) so that a user
-        // scroll-up between the write() call and callback is respected.
-        if (isAtBottomRef.current) {
           term.scrollToBottom();
+          if (!isAtBottomRef.current) {
+            isAtBottomRef.current = true;
+            setIsAtBottom(true);
+          }
         }
       });
       detector.feed(data);
@@ -246,11 +275,9 @@ export default function TerminalView({ sessionId, active }: Props) {
       resizeRafId = requestAnimationFrame(() => {
         resizeRafId = null;
         if (!containerRef.current || containerRef.current.offsetWidth === 0) return;
-        const wasAtBottom = isAtBottomRef.current;
         fitAddon.fit();
         resize(sessionId, term.cols, term.rows);
-        // Maintain scroll position after resize reflow
+        if (autoFollowRef.current) {
-        if (wasAtBottom) {
           term.scrollToBottom();
         }
       });
@@ -268,6 +295,7 @@ export default function TerminalView({ sessionId, active }: Props) {
       scrollDisposable.dispose();
       selectionDisposable.dispose();
       setTerminalHasSelection(false);
+      containerRef.current?.removeEventListener("wheel", handleWheel, { capture: true });
       containerRef.current?.removeEventListener("paste", handlePaste, { capture: true });
       outputPromise.then((fn) => fn?.());
       exitPromise.then((fn) => fn?.());
@@ -303,6 +331,9 @@ export default function TerminalView({ sessionId, active }: Props) {
         }
       }
       fitRef.current?.fit();
+      if (autoFollowRef.current) {
+        term.scrollToBottom();
+      }
       term.focus();
     } else {
       // Release WebGL context for inactive terminals
@@ -339,7 +370,8 @@ export default function TerminalView({ sessionId, active }: Props) {
   const handleScrollToBottom = useCallback(() => {
     const term = termRef.current;
     if (term) {
-      // Re-fit first to fix viewport desync (same thing a resize does)
+      autoFollowRef.current = true;
+      setIsAutoFollow(true);
       fitRef.current?.fit();
       term.scrollToBottom();
       isAtBottomRef.current = true;
@@ -347,6 +379,21 @@ export default function TerminalView({ sessionId, active }: Props) {
     }
   }, []);
 
+  const handleToggleAutoFollow = useCallback(() => {
+    const next = !autoFollowRef.current;
+    autoFollowRef.current = next;
+    setIsAutoFollow(next);
+    if (next) {
+      const term = termRef.current;
+      if (term) {
+        fitRef.current?.fit();
+        term.scrollToBottom();
+        isAtBottomRef.current = true;
+        setIsAtBottom(true);
+      }
+    }
+  }, []);
+
   return (
     <div
       ref={terminalContainerRef}
@@ -367,6 +414,19 @@ export default function TerminalView({ sessionId, active }: Props) {
           {imagePasteMsg}
         </div>
       )}
+      {/* Auto-follow toggle - top right */}
+      <button
+        onClick={handleToggleAutoFollow}
+        className={`absolute top-2 right-4 z-50 px-2 py-1 rounded text-[10px] font-medium border shadow-sm transition-colors cursor-pointer ${
+          isAutoFollow
+            ? "bg-[#1a2332] text-[#3fb950] border-[#238636] hover:bg-[#1f2d3d]"
+            : "bg-[#1f2937] text-[#8b949e] border-[#30363d] hover:bg-[#2d3748]"
+        }`}
+        title={isAutoFollow ? "Auto-scrolling to latest output (click to pause)" : "Auto-scroll paused (click to resume)"}
+      >
+        {isAutoFollow ? "▼ Following" : "▽ Paused"}
+      </button>
+      {/* Jump to Current - bottom right, when scrolled up */}
       {!isAtBottom && (
         <button
           onClick={handleScrollToBottom}