fix: remove flaky terminal scroll affordance

The scroll-to-bottom button was unreliable in practice and distracted from the terminal experience.

Keep the underlying auto-scroll pause behavior and harden shared scroll state detection across the terminal stack.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: faiyaz26

frontend/src/components/TerminalView.tsx

@@ -1,4 +1,4 @@
-import { onCleanup, onMount, createEffect, createSignal, Show, untrack } from 'solid-js';
+import { onCleanup, onMount, createSignal, Show } from 'solid-js';
 import { useTerminalPool } from '../hooks/useTerminalPool';
 import { TerminalInstance } from './terminal/TerminalInstance';
 import type { TerminalHandle } from '../types/terminal';
@@ -124,14 +124,6 @@ export function TerminalView(props: TerminalViewProps) {
     setShowNotificationPrompt(false);
   };
 
-  const scrollToBottom = () => {
-    const h = handle();
-    if (h) {
-      h.terminal.scrollToBottom();
-      h.autoScroll = true;
-    }
-  };
-
   return (
     <div class="relative w-full h-full group">
       <Show
@@ -158,19 +150,6 @@ export function TerminalView(props: TerminalViewProps) {
         {(h) => <TerminalInstance handle={h()} />}
       </Show>
 
-      <Show when={handle() && !handle()!.autoScroll}>
-        <button
-          onClick={scrollToBottom}
-          data-testid="scroll-to-bottom-button"
-          class="absolute bottom-10 right-10 px-4 py-2 bg-zed-accent-blue text-white rounded-full shadow-xl flex items-center gap-2 text-sm font-semibold hover:bg-zed-accent-blue-hover transition-all animate-bounce-in z-20 cursor-pointer"
-        >
-          <svg class="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24" stroke-width="3">
-            <path stroke-linecap="round" stroke-linejoin="round" d="M19 13l-7 7-7-7m14-8l-7 7-7-7" />
-          </svg>
-          Scroll to Bottom
-        </button>
-      </Show>
-
       <Show when={showNotificationPrompt()}>
         <div class="absolute top-3 left-3 right-3 flex items-center gap-3 px-4 py-3 rounded-lg bg-zed-bg-overlay border border-zed-border-default shadow-lg animate-slide-down z-10">
           <svg class="w-4 h-4 text-zed-accent-blue shrink-0" fill="none" viewBox="0 0 24 24" stroke="currentColor">

frontend/src/components/__tests__/TerminalView.test.tsx

@@ -25,7 +25,8 @@ vi.stubGlobal('ResizeObserver', class {
 });
 
 // Mock terminal and fit addon
-let scrollCallback: (() => void) | null = null;
+let scrollCallback: ((viewportY: number) => void) | null = null;
+let wheelCallback: ((event: WheelEvent) => boolean) | null = null;
 const mockTerminalInstance = {
   open: vi.fn(),
   focus: vi.fn(),
@@ -37,6 +38,9 @@ const mockTerminalInstance = {
   onData: vi.fn(() => ({ dispose: vi.fn() })),
   onTitleChange: vi.fn(() => ({ dispose: vi.fn() })),
   attachCustomKeyEventHandler: vi.fn(),
+  attachCustomWheelEventHandler: vi.fn((cb) => {
+    wheelCallback = cb;
+  }),
   loadAddon: vi.fn(),
   write: vi.fn(),
   scrollToBottom: vi.fn(),
@@ -95,6 +99,8 @@ vi.mock('../../lib/terminal-utils', () => ({
   createFitAddon: () => ({ fit: vi.fn() }),
   loadAddons: vi.fn(),
   attachKeyHandlers: vi.fn(),
+  isTerminalViewportAtBottom: (terminal: any, viewportY = terminal.buffer.active.viewportY) =>
+    viewportY >= terminal.buffer.active.baseY,
   updateTerminalTheme: vi.fn(),
 }));
 
@@ -107,6 +113,7 @@ describe('TerminalView Scrolling', () => {
   beforeEach(() => {
     vi.clearAllMocks();
     scrollCallback = null;
+    wheelCallback = null;
     mockTerminalInstance.buffer.active.viewportY = 0;
     mockTerminalInstance.buffer.active.baseY = 0;
     mockTerminalInstance.buffer.active.length = 24;
@@ -131,27 +138,55 @@ describe('TerminalView Scrolling', () => {
     setMockHandle = s;
   });
 
-  it('shows "Scroll to Bottom" button when user scrolls up', async () => {
-    // Start with autoScroll false so button can show
-    const current = { ...mockHandle() };
-    current.autoScroll = false;
-    setMockHandle(current);
-    
+  it('keeps the scroll-to-bottom button hidden when the terminal is manually scrolled up', async () => {
     render(() => <TerminalView laneId="lane-1" />);
 
-    // Wait for handle to be set
     await waitFor(() => expect(mockTerminalPool.acquire).toHaveBeenCalled());
+    await waitFor(() => expect(scrollCallback).not.toBeNull());
+
+    expect(screen.queryByTestId('scroll-to-bottom-button')).not.toBeInTheDocument();
 
     // Simulate user scrolling up
-    mockTerminalInstance.buffer.active.baseY = 76; 
+    mockTerminalInstance.buffer.active.baseY = 76;
     mockTerminalInstance.buffer.active.viewportY = 0;
     mockTerminalInstance.buffer.active.length = 100;
-    
-    // Trigger the scroll callback
-    if (scrollCallback) scrollCallback();
 
-    // The button should now be visible
-    const button = await screen.findByTestId('scroll-to-bottom-button');
-    expect(button).toBeDefined();
+    scrollCallback?.(0);
+
+    expect(mockHandle().autoScroll).toBe(false);
+    expect(screen.queryByTestId('scroll-to-bottom-button')).not.toBeInTheDocument();
+  });
+
+  it('still disables auto-scroll from xterm scroll events before buffer viewport state catches up', async () => {
+    render(() => <TerminalView laneId="lane-1" />);
+
+    await waitFor(() => expect(mockTerminalPool.acquire).toHaveBeenCalled());
+    await waitFor(() => expect(scrollCallback).not.toBeNull());
+
+    mockTerminalInstance.buffer.active.baseY = 76;
+    mockTerminalInstance.buffer.active.viewportY = 76;
+    mockTerminalInstance.buffer.active.length = 100;
+
+    scrollCallback?.(0);
+
+    expect(mockHandle().autoScroll).toBe(false);
+    expect(screen.queryByTestId('scroll-to-bottom-button')).not.toBeInTheDocument();
+  });
+
+  it('pauses auto-scroll as soon as the user wheels upward', async () => {
+    render(() => <TerminalView laneId="lane-1" />);
+
+    await waitFor(() => expect(mockTerminalPool.acquire).toHaveBeenCalled());
+    await waitFor(() => expect(wheelCallback).not.toBeNull());
+
+    expect(screen.queryByTestId('scroll-to-bottom-button')).not.toBeInTheDocument();
+
+    const shouldContinue = wheelCallback?.({
+      deltaY: -1,
+    } as WheelEvent);
+
+    expect(shouldContinue).toBe(true);
+    expect(mockHandle().autoScroll).toBe(false);
+    expect(screen.queryByTestId('scroll-to-bottom-button')).not.toBeInTheDocument();
   });
 });

frontend/src/components/terminal/TerminalInstance.tsx

@@ -7,6 +7,7 @@
 import { onMount, onCleanup, createEffect } from 'solid-js';
 import { 
   SharedTerminalInstance, 
+  isTerminalViewportAtBottom,
   updateTerminalTheme, 
   themeManager 
 } from '@codelane/shared';
@@ -40,12 +41,28 @@ export function TerminalInstance(props: TerminalInstanceProps) {
     if (!props.handle) return;
     const { terminal } = props.handle;
 
+    const setAutoScroll = (autoScroll: boolean) => {
+      props.handle.autoScroll = autoScroll;
+    };
+
     // Sticky scroll detection
-    const updateAutoScroll = () => {
-      const buffer = terminal.buffer.active;
-      props.handle.autoScroll = buffer.baseY + terminal.rows >= buffer.length;
+    const updateAutoScroll = (viewportY = terminal.buffer.active.viewportY) => {
+      const autoScroll = isTerminalViewportAtBottom(terminal, viewportY);
+      setAutoScroll(autoScroll);
     };
-    terminal.onScroll(updateAutoScroll);
+
+    // Pause follow-mode as soon as the user starts scrolling up so live output
+    // cannot race the viewport back to the bottom before xterm emits onScroll.
+    terminal.attachCustomWheelEventHandler((event) => {
+      if (event.deltaY < 0 && props.handle.autoScroll) {
+        setAutoScroll(false);
+      }
+      return true;
+    });
+
+    const scrollDisposable = terminal.onScroll((viewportY) => updateAutoScroll(viewportY));
+    updateAutoScroll();
+    onCleanup(() => scrollDisposable.dispose());
   });
 
   return (

frontend/src/services/TerminalPool.ts

@@ -10,7 +10,7 @@
 
 import { spawn, type PtyHandle } from './PortablePty';
 import { getLaneAgentConfig, checkCommandExists } from '../lib/settings-api';
-import { createTerminal, createFitAddon, attachKeyHandlers } from '../lib/terminal-utils';
+import { createTerminal, createFitAddon, attachKeyHandlers, isTerminalViewportAtBottom } from '../lib/terminal-utils';
 import { agentStatusManager } from './AgentStatusManager';
 import type { DetectableAgentType } from '../types/agentStatus';
 import type {
@@ -232,8 +232,7 @@ class TerminalPool {
     await pty.onData((data) => {
       // Check if we're at the bottom BEFORE writing. If the user has scrolled up,
       // we should respect that and not force a scroll to bottom.
-      const buffer = terminal.buffer.active;
-      const isAtBottom = buffer.baseY + terminal.rows >= buffer.length;
+      const isAtBottom = isTerminalViewportAtBottom(terminal);
 
       terminal.write(data);
 

frontend/src/services/__tests__/TerminalPool.test.ts

@@ -68,7 +68,7 @@ function createMockTerminal() {
       focus,
       element: null,
       buffer: {
-        active: { baseY: 0, length: 24 },
+        active: { baseY: 0, viewportY: 0, length: 24 },
       },
       hasSelection: () => false,
       options: {},
@@ -88,6 +88,8 @@ vi.mock('../../lib/terminal-utils', () => ({
   },
   createFitAddon: () => ({ fit: vi.fn() }),
   attachKeyHandlers: vi.fn(() => () => {}),
+  isTerminalViewportAtBottom: (terminal: any, viewportY = terminal.buffer.active.viewportY) =>
+    viewportY >= terminal.buffer.active.baseY,
   loadAddons: vi.fn(),
   updateTerminalTheme: vi.fn(),
 }));
@@ -188,10 +190,11 @@ describe('TerminalPool', () => {
 
       expect(handle.autoScroll).toBe(true);
 
-      // Simulate user being scrolled up (baseY is 0, length is 100)
-      terminal.buffer.active.baseY = 0;
+      // Simulate user being scrolled up. `baseY` marks the viewport position when
+      // fully scrolled down, while `viewportY` is where the user currently is.
+      terminal.buffer.active.baseY = 76;
+      terminal.buffer.active.viewportY = 0;
       terminal.buffer.active.length = 100;
-      // 0 + 24 < 100, so we're scrolled up
 
       // Simulate PTY output
       const data = new TextEncoder().encode('new output');
@@ -203,19 +206,18 @@ describe('TerminalPool', () => {
   });
 
   describe('scroll position detection', () => {
-    it('detects at-bottom when baseY + rows >= length', () => {
-      // This tests the logic: buffer.baseY + terminal.rows >= buffer.length
+    it('detects at-bottom when viewportY reaches baseY', () => {
       const cases = [
-        { baseY: 0, rows: 24, length: 24, expected: true },   // exactly at bottom
-        { baseY: 10, rows: 24, length: 34, expected: true },   // scrollback, at bottom
-        { baseY: 10, rows: 24, length: 35, expected: false },  // 1 line scrolled up
-        { baseY: 0, rows: 24, length: 50, expected: false },   // scrolled to top
-        { baseY: 100, rows: 24, length: 124, expected: true }, // large buffer, at bottom
-        { baseY: 100, rows: 24, length: 125, expected: false }, // large buffer, 1 line up
+        { baseY: 0, viewportY: 0, expected: true },     // no scrollback
+        { baseY: 10, viewportY: 10, expected: true },   // scrolled to bottom
+        { baseY: 10, viewportY: 9, expected: false },   // 1 line above bottom
+        { baseY: 76, viewportY: 0, expected: false },   // top of long scrollback
+        { baseY: 100, viewportY: 100, expected: true }, // large buffer, at bottom
+        { baseY: 100, viewportY: 50, expected: false }, // large buffer, midway up
       ];
 
-      for (const { baseY, rows, length, expected } of cases) {
-        const isAtBottom = baseY + rows >= length;
+      for (const { baseY, viewportY, expected } of cases) {
+        const isAtBottom = viewportY >= baseY;
         expect(isAtBottom).toBe(expected);
       }
     });

packages/shared/src/components/SharedTerminalInstance.tsx

@@ -5,7 +5,12 @@
  */
 
 import { onMount, onCleanup } from 'solid-js';
-import { loadAddons, attachKeyHandlers, type TerminalHandlers } from '../terminal/terminal-utils';
+import {
+  loadAddons,
+  attachKeyHandlers,
+  isTerminalViewportAtBottom,
+  type TerminalHandlers,
+} from '../terminal/terminal-utils';
 import type { Terminal } from '@xterm/xterm';
 import type { FitAddon } from '@xterm/addon-fit';
 
@@ -60,8 +65,7 @@ export function SharedTerminalInstance(props: SharedTerminalInstanceProps) {
         const r = containerRef.getBoundingClientRect();
         if (r.width < 1 || r.height < 1) return;
 
-        const buffer = terminal.buffer.active;
-        const isAtBottom = buffer.baseY + terminal.rows >= buffer.length;
+        const isAtBottom = isTerminalViewportAtBottom(terminal);
 
         fitAddon.fit();
         props.onResizePty(terminal.cols, terminal.rows);
@@ -77,7 +81,6 @@ export function SharedTerminalInstance(props: SharedTerminalInstanceProps) {
       // Initial resize
       setTimeout(() => {
         safeFitAndResize();
-        terminal.scrollToBottom();
       }, 100);
 
       // Handle resize events

packages/shared/src/terminal/terminal-utils.ts

@@ -15,6 +15,14 @@ export interface TerminalHandlers {
   onWriteClipboard?: (text: string) => Promise<void>;
 }
 
+export function isTerminalViewportAtBottom(
+  terminal: Pick<Terminal, 'buffer'>,
+  viewportY = terminal.buffer.active.viewportY
+): boolean {
+  const buffer = terminal.buffer.active;
+  return viewportY >= buffer.baseY;
+}
+
 /**
  * Creates a pre-configured xterm.js Terminal instance with current theme
  */