fix(tiles): page a hollow tile's CLI transcript and report its clicks (#555 parity)

#555 made the primary pane page opencode's transcript with PageUp/PageDown
from the wheel, because opencode draws in place on the alternate screen and
leaves the browser's buffer with no scrollback. A TerminalTile (a grid tile,
the split's Pane B) left every wheel to xterm, so in an opencode tile the
wheel scrolled nothing, or only stale rows.

The tile now runs the primary pane's own gates aimed at itself (its terminal,
its session, never the active one): xterm's tracking mode, the Claude
forwarding gate, then the hollow-buffer test. A wheel that passes them is
consumed in the capture phase and turned into PageUp/PageDown through the
shared pageKeysForTravel math, coalesced per tile (40 ms, 512 bytes, the twin
of the primary pane's queue) and sent ephemeral on the tile's own socket.
Every other wheel stays with xterm as before, the shell history pull
included. The file names no CLI: the mode rules stay in terminal-ui.js, and
terminal-tile.js joins the frontend no-id-branching guard.

A plain port of the primary's baseY === 0 test would almost never fire in a
grid. A tile's first capture is taken at the PTY's previous size (usually the
taller primary pane's) and written into a shorter xterm, and its own
row-shrinking fits (zoom-out, divider drags, tile count changes) push more
rows above the screen. The tile counts those rows as its own overflow: all of
them after a load whose capture held a single screen (the server's
captureRows), plus whatever a local fit or a PTY geometry report pushes up,
reset by a clear and clamped to baseY. The paging gate gets baseY minus that
count. Output that scrolls real lines still counts as history, so the tile
stops paging there.

#555's other half, stripping opencode's mouse DECSETs so a drag selects text,
is server-side and already reached tile sockets. It also left the tile's
xterm unable to encode opencode's clicks, so the tile now installs the
primary pane's desktop click report (bubble phase, gated on the session's
cliMouseTracking, the tile's own link hover and selection). Both listeners,
the flush timer and the page-key state are torn down in destroy().

Still out of scope, as the fileoverview now says: touch paging (tiles have
no touch path) and SGR wheel forwarding to Claude's fullscreen renderer
(tile-grid-plan follow-up 4), so a fullscreen Claude tile keeps leaving the
wheel to xterm.

Tests: test/terminal-tile-scroll.test.ts drives a real tile in the vm
harness (session targeting, every no-page case, accumulation, the cap,
coalescing, byte parity with the primary pane, the overflow discount through
a load, a fit, a geometry report and a clear, the click report and destroy);
the discount cases fail with it removed. The fake xterm gains opt-in row
emulation. test/terminal-tile-scroll.browser.test.ts checks the same model
against a real xterm with trusted wheel events (browser suite, not the gate).

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

test/frontend-cli-no-id-branching.test.ts

@@ -3,7 +3,9 @@
  * (`session-ui.js`, `mobile-overview.js`), plus the files that draw a session
  * header's harness logo and model (`constants.js`, `terminal-split.js`,
  * `tile-grid.js`: the logo's `run-mode-dot <cliId>` class is the id as DATA),
- * mirroring
+ * and `terminal-tile.js`, whose wheel paging and click reports reach the
+ * primary pane's CLI rules through terminal-ui.js and must not grow a copy of
+ * them, mirroring
  * `test/cli-registry-no-id-branching.test.ts` for the backend registry.
  *
  * Deliberately scoped to ONLY these two files, not all of `src/web/public/`.
@@ -24,7 +26,14 @@ import { fileURLToPath } from 'node:url';
 import { STOCK_CLIS } from '../src/config/cli-registry/stock.js';
 
 const PUBLIC = fileURLToPath(new URL('../src/web/public/', import.meta.url));
-const SCANNED_FILES = ['session-ui.js', 'mobile-overview.js', 'constants.js', 'terminal-split.js', 'tile-grid.js'];
+const SCANNED_FILES = [
+  'session-ui.js',
+  'mobile-overview.js',
+  'constants.js',
+  'terminal-split.js',
+  'tile-grid.js',
+  'terminal-tile.js',
+];
 
 /**
  * Every currently-surviving branch, each with the COUNT of physical call
@@ -100,6 +109,20 @@ const ALLOWED_BRANCHES: Record<string, { count: number; reason: string }> = {
     reason: 'attach route: a shell session attaches through /shell, an agent through /interactive',
   },
 
+  // terminal-tile.js: the pane's two shell-only mechanisms, both mirrors of the
+  // primary pane's own shell checks (terminal-ui.js / app.js). Its wheel
+  // paging and click reports name no CLI: they ask terminal-ui.js's gates.
+  "terminal-tile.js::mode !== 'shell'": {
+    count: 2,
+    reason:
+      'Ctrl+Z reaches the PTY only in a shell (job control), and the scroll-to-top history pull is shell-only, ' +
+      'both as in the primary pane',
+  },
+  "terminal-tile.js::mode === 'shell'": {
+    count: 1,
+    reason: 'the load query: a shell loads the bounded tail= window instead of a full capture, as in the primary pane',
+  },
+
   // mobile-overview.js: shell is exempt from the isCliAvailable() gate the
   // same way the toolbar's #runModeMenu exempts it (shell needs no CLI).
   "mobile-overview.js::mode !== 'shell'": {
@@ -188,7 +211,7 @@ function actualCounts(): Map<string, number> {
 }
 
 describe('no NEW CLI-id branching in the scanned frontend files', () => {
-  it('scans both files (sanity)', () => {
+  it('scans every listed file (sanity)', () => {
     // If this drops to zero the scanner or the file list drifted and every
     // assertion below would pass vacuously.
     const scannedBytes = SCANNED_FILES.reduce((n, f) => n + readFileSync(PUBLIC + f, 'utf-8').length, 0);

test/mocks/terminal-tile-fakes.ts

@@ -61,15 +61,45 @@ export class FakeFit {
 /** An xterm that records writes, resizes and its handlers; `type()` feeds onData like a keystroke. */
 export class FakeTerminal {
   static last: FakeTerminal | null = null;
+  /**
+   * Opt-in, set by a test BEFORE the tile connects: the buffer's rows follow
+   * what is written, as in xterm. Every `\n` adds a line, `baseY` is the lines
+   * beyond the screen, a clear leaves one line, and a resize recomputes it
+   * (a row-shrinking fit pushes rows above the screen, a growing one pulls them
+   * back). The viewport follows the bottom. Off, `baseY` stays where a test
+   * puts it.
+   */
+  static emulateScroll = false;
   options: Record<string, unknown>;
   cols = 80;
   rows = 24;
   dataCb: ((data: string) => void) | null = null;
-  buffer = { active: { type: 'normal', viewportY: 0, length: 24 } };
+  buffer = { active: { type: 'normal', viewportY: 0, baseY: 0, length: 24 } };
+  /** xterm's own mouse-tracking mode (DECSET 1000 and friends); 'none' while no app asked for the mouse. */
+  modes = { mouseTrackingMode: 'none' };
+  /** Lines in the buffer while emulating (the cursor line counts). */
+  lineCount = 1;
+  emulate = FakeTerminal.emulateScroll;
+  /** Called after an emulated resize, so a test can stand in for a reflow. */
+  afterResize: ((cols: number, rows: number) => void) | null = null;
+  /** Where the screen sits and how big a cell renders, for the click-to-cell math. */
+  screenRect = { left: 10, top: 20 };
+  element = {
+    querySelector: (sel: string) =>
+      sel === '.xterm-screen' ? { getBoundingClientRect: () => ({ ...this.screenRect }) } : null,
+  };
+  _core = { _renderService: { dimensions: { css: { cell: { width: 8, height: 16 } } } } };
   constructor(options: Record<string, unknown>) {
     this.options = { ...options };
     FakeTerminal.last = this;
   }
+  /** Re-derives baseY (and a viewport following the bottom) from the emulated line count. */
+  settleRows() {
+    const active = this.buffer.active;
+    active.baseY = Math.max(0, this.lineCount - this.rows);
+    active.viewportY = active.baseY;
+    active.length = Math.max(this.lineCount, this.rows);
+  }
   loadAddon(addon: FakeFit) {
     addon.term = this;
   }
@@ -101,16 +131,28 @@ export class FakeTerminal {
     // An empty write puts nothing on screen; the replay queues one only to hear
     // (its callback) that everything before it has been parsed.
     if (data) this.writes.push(data);
+    if (data && this.emulate) {
+      this.lineCount += data.split('\n').length - 1;
+      this.settleRows();
+    }
     if (!this.holdParse) cb?.();
   }
   clear() {
     this.writes.push('<CLEAR>');
+    if (this.emulate) {
+      this.lineCount = 1;
+      this.settleRows();
+    }
   }
   resizes: Array<[number, number]> = [];
   resize(cols: number, rows: number) {
     this.resizes.push([cols, rows]);
     this.cols = cols;
     this.rows = rows;
+    if (this.emulate) {
+      this.settleRows();
+      this.afterResize?.(cols, rows);
+    }
   }
   scrollToLine() {}
   scrollToTop() {}

test/terminal-tile-scroll.browser.test.ts

@@ -0,0 +1,176 @@
+/**
+ * @fileoverview Real Chromium + real xterm coverage for a TerminalTile's
+ * hollow-buffer paging (#555 parity), the parts a fake xterm cannot prove:
+ *
+ *  - the capture-phase wheel listener on the tile's mount really keeps the
+ *    paged wheel away from xterm (its viewport does not move into the stale
+ *    rows above the screen), while a wheel the tile does not page still
+ *    reaches xterm and scrolls it, and
+ *  - real xterm puts a one-screen capture taken at a taller size above the
+ *    screen, and a row-shrinking fit pushes more rows up, which is what the
+ *    tile's overflow discount (`_localRows`) counts. Output that scrolls real
+ *    lines is history, and the tile stops paging.
+ *
+ * The wheel is a real one (`page.mouse.wheel()`), and the last step proves it
+ * reaches xterm: a wheel the tile does not page scrolls xterm's viewport, so
+ * "xterm did not scroll" on a paged wheel means something. What keeps xterm
+ * still there is the tile's preventDefault (xterm 6's scrollable element skips
+ * a wheel whose default was prevented); its stopPropagation, the primary
+ * pane's other half, keeps xterm's own handlers from seeing the event at all.
+ * Dropping both makes this test fail.
+ *
+ * The tile's load and socket are stubbed in the page (fetch answers its one
+ * capture, WebSocket never opens), so nothing here needs a PTY; the page keys
+ * are read from a spy on `app._sendInputEphemeral`. The gates themselves are
+ * the real ones in terminal-ui.js, asked for the tile's own session.
+ *
+ * Port: ephemeral (`new WebServer(0, …)`, read back from `boundPort`).
+ */
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { chromium, type Browser, type Page } from 'playwright';
+import { WebServer } from '../src/web/server.js';
+
+const PROBE_ID = 'tile-scroll-probe';
+
+type Snap = { rows: number; baseY: number; viewportY: number; localRows: number; sent: Array<[string, string]> };
+
+describe('TerminalTile wheel paging in a real browser', () => {
+  let server: WebServer;
+  let browser: Browser;
+  let page: Page;
+
+  beforeAll(async () => {
+    server = new WebServer(0, false, true);
+    await server.start();
+    browser = await chromium.launch({ headless: true });
+    page = await browser.newPage({ viewport: { width: 1280, height: 900 }, deviceScaleFactor: 1 });
+    await page.goto(`http://localhost:${server.boundPort}`, { waitUntil: 'domcontentloaded' });
+    await page.waitForFunction(() => (window as any).app?.terminal && (window as any).TerminalTile, null, {
+      timeout: 30000,
+    });
+  }, 90000);
+
+  afterAll(async () => {
+    if (browser) await browser.close();
+    if (server) await server.stop();
+  }, 60000);
+
+  /** The tile's state plus every page key sent so far. */
+  const snap = () =>
+    page.evaluate(() => {
+      const probe = (window as any).__tileProbe;
+      const term = probe.tile.terminal;
+      return {
+        rows: term.rows,
+        baseY: term.buffer.active.baseY,
+        viewportY: term.buffer.active.viewportY,
+        localRows: probe.tile._localRows(),
+        sent: probe.sent.slice(),
+      } as Snap;
+    });
+
+  /** A real wheel-up of a whole screen over the tile, then time for the 40 ms flush and a frame. */
+  async function wheelUp(rows: number) {
+    await page.mouse.move(200, 60);
+    await page.mouse.wheel(0, -rows * 25);
+    await page.waitForTimeout(150);
+  }
+
+  it('pages a hollow tile, keeps xterm still, survives a shrink, and stops once real lines scroll', async () => {
+    await page.evaluate(async (id) => {
+      const w = window as any;
+      const app = w.app;
+      const CAPTURE_ROWS = 40;
+      const capture = Array.from({ length: CAPTURE_ROWS }, (_, i) => `row ${i}`).join('\r\n');
+
+      // The tile's session, as the app knows it: opencode, which draws in place.
+      app.sessions.set(id, { id, mode: 'opencode' });
+      const sent: Array<[string, string]> = [];
+      const realEphemeral = app._sendInputEphemeral;
+      app._sendInputEphemeral = (sessionId: string, data: string) => sent.push([sessionId, data]);
+      const realFetch = w.fetch;
+      w.fetch = async (url: string, init?: unknown) =>
+        String(url).includes(`/api/sessions/${id}/terminal`)
+          ? new Response(JSON.stringify({ data: { terminalBuffer: capture, captureRows: CAPTURE_ROWS } }))
+          : realFetch(url, init);
+      const RealWebSocket = w.WebSocket;
+      w.WebSocket = class {
+        static OPEN = 1;
+        readyState = 0;
+        send() {}
+        close() {}
+      };
+
+      const mount = document.createElement('div');
+      mount.style.cssText = 'position:fixed;left:0;top:0;width:640px;height:300px;z-index:99999;background:#000';
+      document.body.appendChild(mount);
+      const tile = new w.TerminalTile(id, mount, { mode: 'opencode' });
+      try {
+        await tile.connect();
+      } finally {
+        w.fetch = realFetch;
+        w.WebSocket = RealWebSocket;
+      }
+      w.__tileProbe = { tile, mount, sent, realEphemeral };
+    }, PROBE_ID);
+
+    try {
+      // A 40-row capture in a shorter xterm: the extra rows sit above the
+      // screen, and the tile counts every one of them as its own overflow.
+      const afterLoad = await snap();
+      expect(afterLoad.rows).toBeLessThan(40);
+      expect(afterLoad.baseY).toBe(40 - afterLoad.rows);
+      expect(afterLoad.viewportY).toBe(afterLoad.baseY);
+      expect(afterLoad.localRows).toBe(0);
+
+      // The wheel is consumed and paged: xterm never saw it, so its viewport
+      // stayed at the bottom instead of scrolling into the stale rows.
+      await wheelUp(afterLoad.rows);
+      const afterWheel = await snap();
+      expect(afterWheel.viewportY).toBe(afterLoad.baseY);
+      expect(afterWheel.sent.length).toBeGreaterThanOrEqual(1);
+      expect(afterWheel.sent.every(([id]) => id === PROBE_ID)).toBe(true);
+      expect(afterWheel.sent.map(([, data]) => data).join('')).toMatch(/^(?:\x1b\[5~)+$/);
+
+      // A row-shrinking fit pushes more rows up; still not history, still paged.
+      await page.evaluate(() => {
+        const probe = (window as any).__tileProbe;
+        probe.mount.style.height = '200px';
+        probe.tile.localFit();
+      });
+      const afterShrink = await snap();
+      expect(afterShrink.rows).toBeLessThan(afterLoad.rows);
+      expect(afterShrink.baseY).toBeGreaterThan(afterLoad.baseY);
+      expect(afterShrink.localRows).toBe(0);
+      await wheelUp(afterShrink.rows);
+      const afterSecondWheel = await snap();
+      expect(afterSecondWheel.sent.length).toBeGreaterThan(afterWheel.sent.length);
+      expect(afterSecondWheel.viewportY).toBe(afterShrink.baseY);
+
+      // Output that scrolled real lines is history: the wheel goes back to
+      // xterm, which scrolls its own buffer, and no page key is sent.
+      await page.evaluate(
+        () =>
+          new Promise((resolve) =>
+            (window as any).__tileProbe.tile.terminal.write('real 1\r\nreal 2\r\nreal 3\r\n', resolve)
+          )
+      );
+      const afterOutput = await snap();
+      expect(afterOutput.localRows).toBe(3);
+      await wheelUp(afterOutput.rows);
+      const afterThirdWheel = await snap();
+      expect(afterThirdWheel.sent.length).toBe(afterSecondWheel.sent.length);
+      expect(afterThirdWheel.viewportY).toBeLessThan(afterOutput.baseY);
+    } finally {
+      await page.evaluate((id) => {
+        const w = window as any;
+        const probe = w.__tileProbe;
+        probe.tile.destroy();
+        probe.mount.remove();
+        w.app.sessions.delete(id);
+        w.app._sendInputEphemeral = probe.realEphemeral;
+        delete w.__tileProbe;
+      }, PROBE_ID);
+    }
+  });
+});

test/terminal-tile-scroll.test.ts

@@ -0,0 +1,573 @@
+/**
+ * @fileoverview A TerminalTile pages a hollow buffer's CLI transcript, and
+ * reports a plain click to a CLI whose mouse DECSETs the server strips, the way
+ * the primary pane does (#555), through the primary pane's own gates aimed at
+ * the TILE: its terminal, its session, never the active one.
+ *
+ * opencode draws in place on the alternate screen, so tmux keeps no history
+ * for it and the browser's buffer holds one screen. The primary pane turns the
+ * wheel into PageUp/PageDown there (`_maybePageCliTranscript`, terminal-ui.js);
+ * a tile left the wheel to xterm, which scrolled nothing. #555 also strips
+ * opencode's mouse DECSETs on the server, which reaches tile sockets too: a
+ * drag selects text again, but xterm's own encoder no longer reports a click,
+ * so the tile now hand-encodes it like the primary pane.
+ *
+ * A tile's buffer is rarely empty above the screen even so: its first capture
+ * is taken at the PTY's previous, taller size and written into a shorter
+ * xterm, and its own row-shrinking fits push more rows up. Those rows are not
+ * history, so the tile discounts them (`_localRows`); the overflow cases below
+ * fail without that discount.
+ *
+ * Real code under test: constants.js + app.js + terminal-ui.js +
+ * terminal-tile.js in one `vm` context, as in terminal-tile-input.test.ts.
+ * xterm, the fit addon and WebSocket are fakes (test/mocks/terminal-tile-fakes.ts),
+ * with the fake xterm's row emulation switched on.
+ *
+ * Port: none (no server, no browser).
+ */
+import { readFileSync } from 'node:fs';
+import { performance } from 'node:perf_hooks';
+import { resolve } from 'node:path';
+import vm from 'node:vm';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { FakeFit, FakeSocket, FakeTerminal } from './mocks/terminal-tile-fakes.js';
+
+const fetchMock = vi.fn();
+
+function loadContext() {
+  const read = (f: string) => readFileSync(resolve(import.meta.dirname, `../src/web/public/${f}`), 'utf8');
+  const windowStub: Record<string, unknown> = {
+    addEventListener: vi.fn(),
+    removeEventListener: vi.fn(),
+    CodemanBase: { base: '' },
+  };
+  const context = vm.createContext({
+    console: { ...console, log: vi.fn(), debug: vi.fn() },
+    performance,
+    setInterval: vi.fn(),
+    clearInterval: vi.fn(),
+    // Late-bound, so vi.useFakeTimers() (which swaps the globals) reaches code
+    // running inside this context.
+    setTimeout: (fn: () => void, ms?: number) => globalThis.setTimeout(fn, ms),
+    clearTimeout: (id: ReturnType<typeof setTimeout>) => globalThis.clearTimeout(id),
+    requestAnimationFrame: vi.fn(),
+    HTMLCanvasElement: class HTMLCanvasElement {},
+    WebSocket: FakeSocket,
+    Terminal: FakeTerminal,
+    FitAddon: { FitAddon: FakeFit },
+    fetch: (...args: unknown[]) => fetchMock(...args),
+    location: { protocol: 'http:', host: 'codeman.test' },
+    document: { addEventListener: vi.fn(), documentElement: { dataset: {} } },
+    localStorage: { length: 0, key: vi.fn(), getItem: vi.fn(), setItem: vi.fn(), removeItem: vi.fn() },
+    window: windowStub,
+    MobileDetection: {
+      isTouchDevice: () => false,
+      isHandheldDevice: () => false,
+      getDeviceType: () => 'desktop',
+    },
+  });
+  vm.runInContext(
+    `${read('constants.js')}\n${read('app.js')}\n${read('terminal-ui.js')}\n${read('terminal-tile.js')}\n` +
+      'globalThis.__CodemanApp = CodemanApp;',
+    context
+  );
+  return {
+    CodemanApp: (context as unknown as { __CodemanApp: { prototype: object } }).__CodemanApp,
+    windowStub,
+  };
+}
+
+const { CodemanApp, windowStub } = loadContext();
+
+type Session = { mode: string; cliVersion?: string; cliMouseTracking?: boolean };
+type App = Record<string, unknown> & {
+  sessions: Map<string, Session>;
+  activeSessionId: string | null;
+  _linkHovered?: boolean;
+  loadAppSettingsFromStorage: () => Record<string, unknown>;
+};
+
+function makeApp(sessions: Record<string, Session>, activeSessionId: string | null = 'other'): App {
+  const app = Object.create(CodemanApp.prototype) as App;
+  app._clientId = 'c-test';
+  app._wsTabNonce = 'nonce-1';
+  app._seqCounters = new Map();
+  app._pendingDeliveries = new Map();
+  app._postDraining = new Set();
+  app._extraInputSockets = new Map();
+  app._persistReliableState = vi.fn();
+  app._persistReliableNow = vi.fn();
+  app._updateConnectionIndicator = vi.fn();
+  app.markIdleAlertSeen = vi.fn();
+  app.showToast = vi.fn();
+  app.loadAppSettingsFromStorage = () => ({});
+  app._ws = null;
+  app._wsSessionId = null;
+  app._estimateReplayRows = (text: string) => text.split('\n').length;
+  app.sessions = new Map(Object.entries(sessions));
+  app.activeSessionId = activeSessionId;
+  return app;
+}
+
+/** The tile's mount element: records its listeners by type, with their options. */
+function makeMount() {
+  const listeners: Record<string, Array<{ fn: (ev: unknown) => void; opts: unknown }>> = {};
+  return {
+    listeners,
+    addEventListener: vi.fn((type: string, fn: (ev: unknown) => void, opts?: unknown) => {
+      (listeners[type] ||= []).push({ fn, opts });
+    }),
+    removeEventListener: vi.fn(),
+    fire(type: string, ev: unknown) {
+      for (const { fn } of listeners[type] || []) fn(ev);
+    },
+  };
+}
+
+type Tile = {
+  connect(): Promise<void>;
+  destroy(): void;
+  fit(opts?: { force?: boolean }): void;
+  ws: FakeSocket | null;
+  sessionId: string;
+  _linkHovered: boolean;
+  _scrollFlushTimer: unknown;
+  _onPtyGeometryReport(cols: number, rows: number): void;
+};
+const TerminalTile = windowStub.TerminalTile as new (id: string, mount: unknown, opts?: object) => Tile;
+
+const liveTiles: Tile[] = [];
+
+const lines = (n: number) => Array.from({ length: n }, (_, i) => `row ${i}`).join('\r\n');
+
+/** The capture a tile's first load receives. `captureRows` absent = the server could not say. */
+function serveCapture(terminalBuffer: string, captureRows?: number) {
+  fetchMock.mockImplementation(async () => ({
+    ok: true,
+    status: 200,
+    json: async () => ({ data: { terminalBuffer, ...(captureRows === undefined ? {} : { captureRows }) } }),
+  }));
+}
+
+async function connectTile(app: App, opts: { sessionId?: string; mode?: string } = {}) {
+  windowStub.app = app;
+  const mount = makeMount();
+  const tile = new TerminalTile(opts.sessionId ?? 's-tile', mount, { mode: opts.mode ?? 'opencode' });
+  liveTiles.push(tile);
+  await tile.connect();
+  const ws = FakeSocket.instances.at(-1)!;
+  ws.open();
+  return { tile, ws, term: FakeTerminal.last!, mount };
+}
+
+function wheel(deltaY: number, extra: Record<string, unknown> = {}) {
+  return {
+    deltaY,
+    deltaX: 0,
+    deltaMode: 0,
+    shiftKey: false,
+    preventDefault: vi.fn(),
+    stopPropagation: vi.fn(),
+    ...extra,
+  };
+}
+
+/** One wheel event worth `rowsOfTravel` lines (pixel mode: 25 px a line). */
+const wheelLines = (rowsOfTravel: number, extra: Record<string, unknown> = {}) => wheel(rowsOfTravel * 25, extra);
+
+const PAGE_UP = '\x1b[5~';
+const PAGE_DOWN = '\x1b[6~';
+
+/** Frames the tile's socket sent once the 40 ms coalescer has flushed. */
+function flushed(ws: FakeSocket) {
+  vi.advanceTimersByTime(40);
+  return ws.inputFrames();
+}
+
+beforeEach(() => {
+  vi.useFakeTimers();
+  FakeFit.proposed = { cols: 80, rows: 24 };
+  FakeSocket.instances = [];
+  FakeTerminal.emulateScroll = true;
+  fetchMock.mockReset();
+  serveCapture(lines(10), 24);
+});
+
+afterEach(() => {
+  for (const tile of liveTiles.splice(0)) tile.destroy();
+  FakeTerminal.emulateScroll = false;
+  vi.useRealTimers();
+});
+
+describe('a tile pages a hollow buffer through the primary pane gates', () => {
+  it('turns half a screen of wheel-up into one ephemeral PageUp on its own socket, and down into PageDown', async () => {
+    const { ws, term, mount } = await connectTile(makeApp({ 's-tile': { mode: 'opencode' } }));
+    expect(term.buffer.active.baseY).toBe(0);
+
+    const up = wheelLines(-term.rows / 2);
+    mount.fire('wheel', up);
+
+    expect(up.preventDefault).toHaveBeenCalled();
+    expect(up.stopPropagation).toHaveBeenCalled();
+    expect(ws.inputFrames()).toEqual([]); // coalesced, not sent per event
+    expect(flushed(ws)).toEqual([{ t: 'i', d: PAGE_UP }]); // no seq: never persisted
+
+    mount.fire('wheel', wheelLines(term.rows / 2));
+    expect(flushed(ws).at(-1)).toEqual({ t: 'i', d: PAGE_DOWN });
+  });
+
+  it("reads the TILE's session, not the active one", async () => {
+    // Active session is a shell; the tile shows opencode: the tile still pages.
+    const app = makeApp({ other: { mode: 'shell' }, 's-tile': { mode: 'opencode' } }, 'other');
+    const { ws, mount } = await connectTile(app);
+
+    mount.fire('wheel', wheelLines(-12));
+
+    expect(flushed(ws)).toEqual([{ t: 'i', d: PAGE_UP }]);
+  });
+
+  it.each(['shell', 'codex', 'antigravity'])(
+    'leaves a %s tile to xterm even while the active session is opencode',
+    async (mode) => {
+      const app = makeApp({ other: { mode: 'opencode' }, 's-tile': { mode } }, 'other');
+      const { ws, mount } = await connectTile(app, { mode });
+
+      const ev = wheelLines(-12);
+      mount.fire('wheel', ev);
+
+      expect(ev.preventDefault).not.toHaveBeenCalled();
+      expect(ev.stopPropagation).not.toHaveBeenCalled();
+      expect(flushed(ws)).toEqual([]);
+    }
+  );
+
+  it('still pulls history on a wheel-up at the top of a shell tile', async () => {
+    const { mount } = await connectTile(makeApp({ 's-tile': { mode: 'shell' } }), { mode: 'shell' });
+    expect(fetchMock).toHaveBeenCalledTimes(1); // the initial load
+
+    mount.fire('wheel', wheelLines(-3));
+    await vi.advanceTimersByTimeAsync(0);
+
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+    expect(String(fetchMock.mock.calls[1][0])).toContain('full=1&tail=');
+  });
+
+  it('never pages Shift, a tracking xterm, the alternate buffer, real history or a horizontal swipe', async () => {
+    const { ws, term, mount } = await connectTile(makeApp({ 's-tile': { mode: 'opencode' } }));
+    const fireAndCheck = (ev: ReturnType<typeof wheel>) => {
+      mount.fire('wheel', ev);
+      expect(ev.preventDefault).not.toHaveBeenCalled();
+      expect(ev.stopPropagation).not.toHaveBeenCalled();
+    };
+
+    fireAndCheck(wheelLines(-12, { shiftKey: true })); // the explicit "local scrollback" gesture
+
+    term.modes.mouseTrackingMode = 'any'; // xterm's own encoder forwards the wheel
+    fireAndCheck(wheelLines(-12));
+    term.modes.mouseTrackingMode = 'none';
+
+    term.buffer.active.type = 'alternate'; // xterm's alt-scroll owns it
+    fireAndCheck(wheelLines(-12));
+    term.buffer.active.type = 'normal';
+
+    fireAndCheck(wheel(0, { deltaX: 120 })); // pure horizontal: nothing to page
+
+    term.write(lines(40)); // real output scrolled real lines above the screen
+    expect(term.buffer.active.baseY).toBeGreaterThan(0);
+    fireAndCheck(wheelLines(-12));
+
+    expect(flushed(ws)).toEqual([]);
+  });
+});
+
+describe("the forwarding gate behaves as in the primary pane, for the tile's session", () => {
+  it('leaves a fullscreen Claude tile to xterm (tiles do not forward SGR wheel yet)', async () => {
+    const app = makeApp({ 's-tile': { mode: 'claude', cliVersion: '2.1.223', cliMouseTracking: true } });
+    const { ws, mount } = await connectTile(app, { mode: 'claude' });
+
+    const ev = wheelLines(-12);
+    mount.fire('wheel', ev);
+
+    expect(ev.preventDefault).not.toHaveBeenCalled();
+    expect(flushed(ws)).toEqual([]);
+  });
+
+  it('pages that same tile under the "Wheel scrolls local history" opt-out (the footgun rescue)', async () => {
+    const app = makeApp({ 's-tile': { mode: 'claude', cliVersion: '2.1.223', cliMouseTracking: true } });
+    app.loadAppSettingsFromStorage = () => ({ terminalWheelLocalScrollback: true });
+    const { ws, mount } = await connectTile(app, { mode: 'claude' });
+
+    mount.fire('wheel', wheelLines(-12));
+
+    expect(flushed(ws)).toEqual([{ t: 'i', d: PAGE_UP }]);
+  });
+
+  it('pages a Claude tile whose CLI version is unknown', async () => {
+    const { ws, mount } = await connectTile(makeApp({ 's-tile': { mode: 'claude', cliMouseTracking: true } }), {
+      mode: 'claude',
+    });
+
+    mount.fire('wheel', wheelLines(-12));
+
+    expect(flushed(ws)).toEqual([{ t: 'i', d: PAGE_UP }]);
+  });
+});
+
+describe('page-key travel, cap and coalescing', () => {
+  beforeEach(() => {
+    FakeFit.proposed = { cols: 80, rows: 36 };
+  });
+
+  it('accumulates sub-page travel: two wheels of 10 lines are one PageUp', async () => {
+    const { ws, mount } = await connectTile(makeApp({ 's-tile': { mode: 'opencode' } }));
+
+    mount.fire('wheel', wheelLines(-10));
+    expect(flushed(ws)).toEqual([]);
+    mount.fire('wheel', wheelLines(-10));
+
+    expect(flushed(ws)).toEqual([{ t: 'i', d: PAGE_UP }]);
+  });
+
+  it('caps one wheel at three PageUps, in one frame', async () => {
+    const { ws, mount } = await connectTile(makeApp({ 's-tile': { mode: 'opencode' } }));
+
+    mount.fire('wheel', wheelLines(-1000));
+
+    expect(flushed(ws)).toEqual([{ t: 'i', d: PAGE_UP.repeat(3) }]);
+  });
+
+  it('sends two pages queued within 40 ms as one frame', async () => {
+    const { ws, mount } = await connectTile(makeApp({ 's-tile': { mode: 'opencode' } }));
+
+    mount.fire('wheel', wheelLines(-18));
+    vi.advanceTimersByTime(20);
+    mount.fire('wheel', wheelLines(-18));
+
+    expect(flushed(ws)).toEqual([{ t: 'i', d: PAGE_UP.repeat(2) }]);
+  });
+
+  it('sends exactly the bytes the primary pane sends for the same wheel sequence', async () => {
+    const sequence = [-10, -10, -4, 30, -1000, 7, -18, 200].map((n) => wheelLines(n));
+    const { ws, mount } = await connectTile(makeApp({ 's-tile': { mode: 'opencode' } }));
+    for (const ev of sequence) mount.fire('wheel', ev);
+    const tileBytes = flushed(ws)
+      .map((f) => f.d)
+      .join('');
+
+    const primary = makeApp({ other: { mode: 'opencode' } }, 'other') as App & {
+      terminal: unknown;
+      _maybePageCliTranscript(ev: unknown, lines: number): boolean;
+      _wheelScrollLinesFloat(ev: unknown): number;
+      _flushWheelSgrQueue(): void;
+    };
+    const sent: string[] = [];
+    primary._sendInputEphemeral = (_id: string, data: string) => sent.push(data);
+    primary.terminal = {
+      rows: 36,
+      modes: { mouseTrackingMode: 'none' },
+      buffer: { active: { type: 'normal', baseY: 0, viewportY: 0 } },
+    };
+    for (const ev of sequence) primary._maybePageCliTranscript(ev, primary._wheelScrollLinesFloat(ev));
+    primary._flushWheelSgrQueue();
+
+    expect(tileBytes).not.toBe('');
+    expect(tileBytes).toBe(sent.join(''));
+  });
+});
+
+describe('rows the tile pushed above the screen itself are not history', () => {
+  it('pages after a one-screen capture taken at a taller size (the first load)', async () => {
+    serveCapture(lines(40), 40); // the PTY was 40 rows when it was captured
+    const { ws, term, mount } = await connectTile(makeApp({ 's-tile': { mode: 'opencode' } }));
+    expect(term.buffer.active.baseY).toBe(16); // 40 lines into a 24-row xterm
+
+    mount.fire('wheel', wheelLines(-12));
+
+    expect(flushed(ws)).toEqual([{ t: 'i', d: PAGE_UP }]);
+  });
+
+  it('does not page a capture that carried real history', async () => {
+    serveCapture(lines(60), 24);
+    const { ws, term, mount } = await connectTile(makeApp({ 's-tile': { mode: 'opencode' } }));
+    expect(term.buffer.active.baseY).toBeGreaterThan(0);
+
+    const ev = wheelLines(-12);
+    mount.fire('wheel', ev);
+
+    expect(ev.preventDefault).not.toHaveBeenCalled();
+    expect(flushed(ws)).toEqual([]);
+  });
+
+  it('falls back to the raw baseY when the server sent no captureRows', async () => {
+    serveCapture(lines(40));
+    const tall = await connectTile(makeApp({ 's-tile': { mode: 'opencode' } }));
+    expect(tall.term.buffer.active.baseY).toBe(16);
+    tall.mount.fire('wheel', wheelLines(-12));
+    expect(flushed(tall.ws)).toEqual([]);
+
+    serveCapture(lines(10));
+    const short = await connectTile(makeApp({ 's-tile': { mode: 'opencode' } }));
+    expect(short.term.buffer.active.baseY).toBe(0);
+    short.mount.fire('wheel', wheelLines(-12));
+    expect(flushed(short.ws)).toEqual([{ t: 'i', d: PAGE_UP }]);
+  });
+
+  it('keeps paging after a row-shrinking fit pushes more rows up', async () => {
+    serveCapture(lines(40), 40);
+    const { tile, ws, term, mount } = await connectTile(makeApp({ 's-tile': { mode: 'opencode' } }));
+
+    FakeFit.proposed = { cols: 80, rows: 20 }; // a zoom-out or a divider drag
+    tile.fit();
+    expect(term.buffer.active.baseY).toBe(20);
+
+    mount.fire('wheel', wheelLines(-10));
+    expect(flushed(ws)).toEqual([{ t: 'i', d: PAGE_UP }]);
+  });
+
+  it('stops paging once output scrolls real lines above the screen', async () => {
+    serveCapture(lines(40), 40);
+    const { ws, mount } = await connectTile(makeApp({ 's-tile': { mode: 'opencode' } }));
+
+    ws.receive({ t: 'o', d: 'a\r\nb\r\nc\r\n' }); // three real lines scrolled off
+
+    const ev = wheelLines(-12);
+    mount.fire('wheel', ev);
+    expect(ev.preventDefault).not.toHaveBeenCalled();
+    expect(flushed(ws)).toEqual([]);
+  });
+
+  it('forgets the overflow on a server clear, so later real history counts', async () => {
+    serveCapture(lines(40), 40);
+    const { ws, term, mount } = await connectTile(makeApp({ 's-tile': { mode: 'opencode' } }));
+
+    ws.receive({ t: 'c' });
+    expect(term.buffer.active.baseY).toBe(0);
+    ws.receive({ t: 'o', d: '\r\n'.repeat(term.rows + 1) }); // two real lines above the screen
+    expect(term.buffer.active.baseY).toBe(2);
+
+    const ev = wheelLines(-12);
+    mount.fire('wheel', ev);
+    expect(ev.preventDefault).not.toHaveBeenCalled();
+    expect(flushed(ws)).toEqual([]);
+  });
+
+  it('keeps paging when the PTY geometry report reflows the rows above the screen', async () => {
+    serveCapture(lines(40), 40);
+    const { tile, ws, term, mount } = await connectTile(makeApp({ 's-tile': { mode: 'opencode' } }));
+    // A narrower width wraps the overflow rows onto more rows, as xterm's reflow does.
+    term.afterResize = () => {
+      term.lineCount += 3;
+      term.settleRows();
+    };
+
+    tile._onPtyGeometryReport(60, 40);
+    expect(term.cols).toBe(60);
+    expect(term.buffer.active.baseY).toBe(19);
+
+    mount.fire('wheel', wheelLines(-12));
+    expect(flushed(ws)).toEqual([{ t: 'i', d: PAGE_UP }]);
+  });
+});
+
+describe('a tile reports a plain click to a CLI with mouse tracking on', () => {
+  const click = (overrides: Record<string, unknown> = {}) => ({
+    isTrusted: true,
+    button: 0,
+    detail: 1,
+    // 10 + 8 * 20 + 1, 20 + 16 * 5 + 1 inside the tile's own screen: column 21, row 6.
+    clientX: 171,
+    clientY: 101,
+    target: { closest: (sel: string) => (sel === '.xterm-screen' ? {} : null) },
+    ...overrides,
+  });
+  const TAP = '\x1b[<0;21;6M\x1b[<0;21;6m';
+
+  it("sends one seq-tagged SGR press+release on the tile's socket, from the tile's own geometry", async () => {
+    const app = makeApp({ other: { mode: 'shell' }, 's-tile': { mode: 'opencode', cliMouseTracking: true } });
+    const { ws, mount } = await connectTile(app);
+
+    mount.fire('click', click());
+
+    expect(ws.inputFrames().map((f) => [f.d, typeof f.seq])).toEqual([[TAP, 'number']]);
+  });
+
+  it('sends nothing without the flag, over a selection, over its own hovered link, or scrolled up', async () => {
+    const app = makeApp({ 's-tile': { mode: 'opencode' } });
+    const { tile, ws, term, mount } = await connectTile(app);
+
+    mount.fire('click', click()); // the CLI has no tracking mode on
+    app.sessions.set('s-tile', { mode: 'opencode', cliMouseTracking: true });
+
+    term.selection = 'picked';
+    mount.fire('click', click()); // a drag-selection just ended
+    term.selection = '';
+
+    tile._linkHovered = true;
+    mount.fire('click', click()); // the link provider opens this one
+    tile._linkHovered = false;
+
+    term.buffer.active.baseY = 10;
+    term.buffer.active.viewportY = 0;
+    mount.fire('click', click()); // would hit-test a different row
+    term.buffer.active.viewportY = 10;
+
+    expect(ws.inputFrames()).toEqual([]);
+
+    mount.fire('click', click()); // nothing in the way any more
+    expect(ws.inputFrames().map((f) => f.d)).toEqual([TAP]);
+  });
+
+  it("is not blocked by the primary pane's own link hover", async () => {
+    const app = makeApp({ 's-tile': { mode: 'opencode', cliMouseTracking: true } });
+    app._linkHovered = true;
+    const { ws, mount } = await connectTile(app);
+
+    mount.fire('click', click());
+
+    expect(ws.inputFrames().map((f) => f.d)).toEqual([TAP]);
+  });
+
+  it("follows the tile session's flag, never the active session's", async () => {
+    const reported = await connectTile(
+      makeApp({
+        other: { mode: 'claude', cliMouseTracking: false },
+        's-tile': { mode: 'opencode', cliMouseTracking: true },
+      })
+    );
+    reported.mount.fire('click', click());
+    expect(reported.ws.inputFrames().map((f) => f.d)).toEqual([TAP]);
+
+    const silent = await connectTile(
+      makeApp({
+        other: { mode: 'claude', cliMouseTracking: true },
+        's-tile': { mode: 'opencode', cliMouseTracking: false },
+      })
+    );
+    silent.mount.fire('click', click());
+    expect(silent.ws.inputFrames()).toEqual([]);
+  });
+});
+
+describe('destroy()', () => {
+  it('drops queued page keys and detaches both listeners it registered', async () => {
+    const { tile, ws, mount } = await connectTile(makeApp({ 's-tile': { mode: 'opencode' } }));
+    mount.fire('wheel', wheelLines(-12)); // queued, not yet flushed
+    const wheelFn = mount.listeners.wheel[0].fn;
+    const clickFn = mount.listeners.click[0].fn;
+
+    tile.destroy();
+    vi.advanceTimersByTime(100);
+
+    expect(ws.inputFrames()).toEqual([]);
+    expect(tile._scrollFlushTimer).toBeNull();
+    expect(mount.removeEventListener).toHaveBeenCalledWith('wheel', wheelFn, { capture: true });
+    expect(mount.removeEventListener).toHaveBeenCalledWith('click', clickFn);
+  });
+
+  it('registers the wheel listener non-passive in the capture phase and the click one in the bubble phase', async () => {
+    const { mount } = await connectTile(makeApp({ 's-tile': { mode: 'opencode' } }));
+
+    expect(mount.listeners.wheel.map((l) => l.opts)).toEqual([{ capture: true, passive: false }]);
+    expect(mount.listeners.click.map((l) => l.opts)).toEqual([undefined]);
+  });
+});

test/terminal-tile-unit.test.ts

@@ -65,6 +65,8 @@ type PaneUnderTest = {
   _onLiveOutput(data: string): void;
   _onLiveClear(): void;
   _installWheelListener(): void;
+  _installClickListener(): void;
+  _onClick: unknown;
   _writeDisconnectedMarker(): void;
   _onSocketClosed(): void;
 };
@@ -763,9 +765,13 @@ describe('TerminalTile scroll-to-top history pull', () => {
     // Capture phase: xterm's own wheel handler stopPropagation()s the events it
     // consumes, so a bubbling listener would never fire while the pane still has
     // scrollback to scroll, and the pull would work only from the exact top row.
+    // Not passive: the hollow-buffer paging route consumes its wheel right here
+    // (test/terminal-tile-scroll.test.ts). This stub window has neither the
+    // shared paging helpers nor the app's gates, so that route stays inert and
+    // every wheel below falls through to the pull, as before.
     const [type, listener, options] = mount.addEventListener.mock.calls[0];
     expect(type).toBe('wheel');
-    expect(options).toEqual({ capture: true, passive: true });
+    expect(options).toEqual({ capture: true, passive: false });
 
     listener({ deltaY: 120 }); // wheel down
     listener({ deltaY: 0 });
@@ -789,6 +795,22 @@ describe('TerminalTile scroll-to-top history pull', () => {
     expect(pane._onWheel).toBeNull();
   });
 
+  it('destroy() detaches exactly the click listener it registered', () => {
+    const mount = { addEventListener: vi.fn(), removeEventListener: vi.fn() };
+    const pane = makePane('opencode', mount);
+    pane._installWheelListener();
+    pane._installClickListener();
+    const [type, registered, options] = mount.addEventListener.mock.calls[1];
+    // Bubble phase, like the primary pane's click reporter (terminal-ui.js).
+    expect(type).toBe('click');
+    expect(options).toBeUndefined();
+
+    pane.destroy();
+
+    expect(mount.removeEventListener).toHaveBeenCalledWith('click', registered);
+    expect(pane._onClick).toBeNull();
+  });
+
   it('connect() installs the wheel listener (static guard)', () => {
     // connect() needs a whole xterm to run, so its wiring is pinned by source
     // rather than executed; the listener's behaviour is exercised above.
@@ -800,6 +822,7 @@ describe('TerminalTile scroll-to-top history pull', () => {
     expect(end).toBeGreaterThan(start);
     const connect = SOURCE.slice(start, end);
     expect(connect).toContain('this._installWheelListener();');
+    expect(connect).toContain('this._installClickListener();');
     expect(connect).toContain('this._onLiveClear();');
     expect(connect).not.toContain('this.terminal.clear();');
     // The tests below drive the close through _onSocketClosed() directly; the