Fix retained terminal scroll after activation (#28)

Co-authored-by: Agent Manager <agents@agent-manager.local>

server/mobile.test.mjs

@@ -123,6 +123,9 @@ try {
         super(url, protocols);
         if (String(url).includes('/ws?session=')) {
           const record = { url: String(url), sent: [], events: [] };
+          Object.defineProperty(record, 'sendRaw', {
+            value: (data) => this.send(data),
+          });
           window.__terminalSockets.push(record);
           this.addEventListener('open', () => record.events.push({ type: 'open' }));
           this.addEventListener('close', (event) => record.events.push({
@@ -236,6 +239,22 @@ try {
   await page.locator('.sidebar .row').filter({ hasText: 'mobile-terminal-second' }).first().click();
   await page.locator('.tile-terminal:not(.tile-cached) .xterm-screen').waitFor({ state: 'visible' });
   const secondOpened = await waitFor(() => page.evaluate(() => window.__terminalSockets.length === 2));
+
+  // Keep writing to the first session while its retained xterm is under
+  // display:none. xterm keeps the logical viewport at the live bottom, but a
+  // hidden DOM viewport cannot accept that pixel scrollTop. Re-activation must
+  // reconcile the two before the first wheel event uses the stale DOM value.
+  await page.evaluate(({ sessionId, input }) => {
+    const socket = window.__terminalSockets.find((item) => item.url.includes(`session=${sessionId}`));
+    socket?.sendRaw(JSON.stringify({ t: 'i', d: input }));
+  }, {
+    sessionId: id,
+    input: "printf '\\033[?1000l\\033[?1006l'; for i in $(seq 221 280); do printf 'MOBILE-HISTORY-%04d\\n' \"$i\"; done\r",
+  });
+  const hiddenOutputReady = await waitFor(async () => {
+    const body = await (await fetch(`${API}/api/agents/${id}/tail?lines=400`)).json();
+    return body.text?.includes('MOBILE-HISTORY-0280');
+  });
   await page.getByTitle('Back to list').click();
   await page.locator('.sidebar .row').filter({ hasText: 'mobile-terminal-e2e' }).first().click();
   await page.locator('.tile-terminal:not(.tile-cached) .xterm-screen').waitFor({ state: 'visible' });
@@ -254,6 +273,26 @@ try {
     secondOpened && retained.matching === 1 && !retained.closed
       && retained.terminals === 2 && retained.hidden === 1,
     JSON.stringify({ secondOpened, retained }));
+  const reactivatedScroll = await page.locator('.tile-terminal:not(.tile-cached) .xterm-viewport').evaluate((node) => ({
+    top: node.scrollTop,
+    max: node.scrollHeight - node.clientHeight,
+  }));
+  check('a retained terminal restores its DOM viewport before wheel input',
+    hiddenOutputReady && reactivatedScroll.max > 0
+      && Math.abs(reactivatedScroll.top - reactivatedScroll.max) <= 1,
+    JSON.stringify({ hiddenOutputReady, reactivatedScroll }));
+  await page.locator('.tile-terminal:not(.tile-cached) .xterm').dispatchEvent('wheel', {
+    deltaY: -96, deltaMode: 0,
+  });
+  await sleep(100);
+  const wheelTop = await page.locator('.tile-terminal:not(.tile-cached) .xterm-viewport').evaluate((node) => node.scrollTop);
+  check('the first upward wheel after re-activation scrolls into history',
+    wheelTop < reactivatedScroll.top - 1,
+    JSON.stringify({ before: reactivatedScroll.top, after: wheelTop }));
+  await page.locator('.tile-terminal:not(.tile-cached) .xterm-viewport').evaluate((node) => {
+    node.scrollTop = node.scrollHeight;
+  });
+  await sleep(100);
   const hiddenMessagesBeforeZoom = await page.evaluate((sessionId) => {
     const socket = window.__terminalSockets.find((item) => item.url.includes(`session=${sessionId}`));
     return socket?.sent?.length ?? -1;
@@ -529,13 +568,13 @@ try {
   const previewSaved = await waitFor(() => page.evaluate((sessionId) => {
     try {
       const saved = JSON.parse(localStorage.getItem(`am-terminal-preview:${sessionId}`) || 'null');
-      return saved?.rows?.some((line) => String(line).includes('MOBILE-HISTORY-0220'));
+      return saved?.rows?.some((line) => String(line).includes('MOBILE-HISTORY-0280'));
     } catch { return false; }
   }, id), 5_000);
   await page.evaluate(() => localStorage.setItem('__am_test_offline_sockets', '1'));
   await page.reload({ waitUntil: 'domcontentloaded' });
   await page.locator('.sidebar .row').filter({ hasText: 'mobile-terminal-e2e' }).first().click();
-  const previewVisible = await page.locator('.term-preview').filter({ hasText: 'MOBILE-HISTORY-0220' })
+  const previewVisible = await page.locator('.term-preview').filter({ hasText: 'MOBILE-HISTORY-0280' })
     .isVisible().catch(() => false);
   check('the last terminal view survives reload while the backend is unavailable',
     previewSaved && previewVisible, JSON.stringify({ previewSaved, previewVisible }));

web/src/App.tsx

@@ -718,6 +718,7 @@ export default function App() {
                 theme={theme}
                 zoom={zoom}
                 focused={shown && sessions.length > 1 && s.id === focusedId}
+                visible={shown && deckVisible}
                 active={shown && deckVisible && s.id === focusedId}
                 dragId={shown && canDrag ? `p:${s.id}` : undefined}
                 isMobile={isMobile}

web/src/components/TerminalPane.tsx

@@ -1,4 +1,4 @@
-import { useEffect, useRef, useState } from 'react';
+import { useEffect, useLayoutEffect, useRef, useState } from 'react';
 import { Terminal, type ITheme } from '@xterm/xterm';
 import { FitAddon } from '@xterm/addon-fit';
 import { ClipboardAddon, Base64 } from '@xterm/addon-clipboard';
@@ -177,12 +177,13 @@ if (typeof window !== 'undefined') {
 }
 
 export default function TerminalPane({
-  session, cli, theme, focused, active, zoom = 100, dragId, isMobile, onDragActive, onFocus, onRename, onClose,
+  session, cli, theme, focused, visible, active, zoom = 100, dragId, isMobile, onDragActive, onFocus, onRename, onClose,
 }: {
   session: Session;
   cli?: Cli;
   theme: 'light' | 'dark';
   focused?: boolean;
+  visible?: boolean;
   active?: boolean;
   zoom?: number;
   dragId?: string;          // set when the pane can be rearranged (group view)
@@ -196,6 +197,7 @@ export default function TerminalPane({
   const frameRef = useRef<HTMLDivElement>(null);
   const termRef = useRef<Terminal | null>(null);
   const resyncRef = useRef<() => void>(() => {});
+  const reconcileScrollRef = useRef<() => void>(() => {});
   const claimRef = useRef<() => void>(() => {});
   const reconnectRef = useRef<() => void>(() => {});
   const controllerRef = useRef(false);
@@ -576,6 +578,21 @@ export default function TerminalPane({
       resyncTimer = setTimeout(() => { resyncTimer = null; requestSize(); }, 80);
     };
     resyncRef.current = resync;
+    // xterm deliberately ignores DOM scroll events while its viewport is under
+    // display:none. Output can still advance its logical viewport in that
+    // state, leaving scrollTop behind; the next wheel then calculates a large
+    // jump from two contradictory positions. Move away and back through the
+    // public scroll API once the pane has layout again. This makes xterm rebuild
+    // its scroll area and reconcile scrollTop without changing where the user
+    // was reading.
+    reconcileScrollRef.current = () => {
+      const box = hostRef.current;
+      const buffer = term.buffer.active;
+      if (!box || box.clientWidth < 40 || box.clientHeight < 40 || buffer.baseY <= 0) return;
+      const step = buffer.viewportY > 0 ? -1 : 1;
+      term.scrollLines(step);
+      term.scrollLines(-step);
+    };
     const onReturn = () => resync();
     const onVisible = () => { if (!document.hidden) onReturn(); };
     // Typing means the user sees enough to interact — drop the boot cover.
@@ -723,6 +740,7 @@ export default function TerminalPane({
       term.dispose();
       termRef.current = null;
       resyncRef.current = () => {};
+      reconcileScrollRef.current = () => {};
       claimRef.current = () => {};
     };
   }, [session.id]);
@@ -749,6 +767,14 @@ export default function TerminalPane({
     if (active) resyncRef.current();
   }, [zoom, active]);
 
+  // A retained pane can receive output while display:none. Reconcile xterm's
+  // logical and DOM scroll positions as soon as any cached tile becomes visible,
+  // including non-focused panes in a group.
+  useLayoutEffect(() => {
+    if (!visible) return;
+    reconcileScrollRef.current();
+  }, [visible]);
+
   // Move keyboard focus into the terminal whenever this pane becomes the active
   // one (e.g. selected from the sidebar, or newly created).
   useEffect(() => {