Merge pull request #395 from irisitymichaelgrundberg/fix/full-history-replay-row-alignment

fix(terminal): keep row alignment in the full-history pane replay

test/routes/session-routes.test.ts

@@ -851,6 +851,85 @@ describe('session-routes', () => {
       );
     });
 
+    it('full reload (?full=1) keeps every leading row so the restored cursor lands on the right line', async () => {
+      // The capture ends with an absolute cursor move, so its rows and the pane's
+      // rows must line up one for one. Three transforms used to run over it and
+      // each could delete a leading line: redraw-bloat stripping, the trim that
+      // cuts everything above the Claude banner, and a leading-whitespace strip.
+      // Any one of them shifted the frame up and left the caret a row off.
+      harness.ctx._session.mode = 'claude';
+      harness.ctx._session.terminalBuffer = '';
+      // A blank first row, then the banner — the shape a real pane has.
+      const rendered = ['', '\x1b[1mClaude Code v2.1.266', 'conversation', '\u276f ', '\x1b[4;3H'].join('\r\n');
+      (harness.ctx.mux as { captureActivePaneBuffer?: unknown }).captureActivePaneBuffer = vi.fn(
+        (_name: string, opts?: { fullHistory?: boolean }) => (opts?.fullHistory ? rendered : 'visible frame')
+      );
+
+      const res = await harness.app.inject({
+        method: 'GET',
+        url: `/api/sessions/${harness.ctx._sessionId}/terminal?full=1`,
+      });
+
+      expect(res.statusCode).toBe(200);
+      const body = JSON.parse(res.body);
+      expect(body.data.source).toBe('mux-full-history');
+      // The blank first row survives, so row N of the reply is row N of the pane.
+      expect(body.data.terminalBuffer.startsWith('\r\n')).toBe(true);
+      expect(body.data.terminalBuffer.split('\r\n')).toHaveLength(rendered.split('\r\n').length);
+    });
+
+    it('full reload (?full=1) still strips the byte history when no capture came back', async () => {
+      // The row-preserving skips exist for a rendered pane. When the capture is
+      // unavailable the reply IS the byte stream — successive Ink frames, no row
+      // alignment to protect — so keying the skips on the query parameter rather
+      // than on the capture returned it unstripped, which is the whole reason
+      // stripInkRedrawBloat exists. A session with no mux takes this path on
+      // every first selection, not just during an outage.
+      harness.ctx._session.mode = 'claude';
+      // A VPA cluster the stripper will collapse: >= 10 sequences, spanning the
+      // 32KB minimum, with real content after it.
+      const frame = '\x1b[12d' + 'spinner frame '.repeat(240);
+      harness.ctx._session.terminalBuffer = frame.repeat(20) + 'REAL CONTENT AFTER THE BLOAT';
+      (harness.ctx.mux as { captureActivePaneBuffer?: unknown }).captureActivePaneBuffer = vi.fn(() => null);
+
+      const res = await harness.app.inject({
+        method: 'GET',
+        url: `/api/sessions/${harness.ctx._sessionId}/terminal?full=1`,
+      });
+
+      expect(res.statusCode).toBe(200);
+      const body = JSON.parse(res.body);
+      expect(body.data.source).toBe('history');
+      expect(body.data.terminalBuffer).toContain('REAL CONTENT AFTER THE BLOAT');
+      // Stripped, not passed through whole.
+      expect(body.data.terminalBuffer.length).toBeLessThan(harness.ctx._session.terminalBuffer.length);
+    });
+
+    it('full reload (?full=1) keeps the byte history when the capture is empty', async () => {
+      // Pins the contract the capture side relies on: an empty capture means
+      // "nothing to replay" and the byte history survives. capturePaneBuffer
+      // returns '' for an all-blank pane precisely to reach this branch, since
+      // retaining trailing blank rows and appending a cursor move would
+      // otherwise make a blank screen non-empty and replace the history with it.
+      // (The blank-pane decision itself is unit-tested on hasVisibleContent —
+      // capturePaneBuffer short-circuits under IS_TEST_MODE and cannot run here.)
+      harness.ctx._session.mode = 'claude';
+      harness.ctx._session.terminalBuffer = 'a real conversation worth keeping';
+      (harness.ctx.mux as { captureActivePaneBuffer?: unknown }).captureActivePaneBuffer = vi.fn(
+        (_name: string, opts?: { fullHistory?: boolean }) => (opts?.fullHistory ? '' : 'visible frame')
+      );
+
+      const res = await harness.app.inject({
+        method: 'GET',
+        url: `/api/sessions/${harness.ctx._sessionId}/terminal?full=1`,
+      });
+
+      expect(res.statusCode).toBe(200);
+      const body = JSON.parse(res.body);
+      expect(body.data.source).toBe('history');
+      expect(body.data.terminalBuffer).toContain('a real conversation worth keeping');
+    });
+
     it('full reload (?full=1) falls back to the byte history when the capture is unavailable', async () => {
       harness.ctx._session.mode = 'claude';
       harness.ctx._session.terminalBuffer = 'byte history survives';

test/tmux-capture-full-history.test.ts

@@ -11,11 +11,15 @@
 import { readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { describe, expect, it } from 'vitest';
+import { formatCursorRestore, hasVisibleContent } from '../src/tmux-manager.js';
 
 describe('tmux full-history pane capture (COD-47)', () => {
   const source = readFileSync(resolve(import.meta.dirname, '../src/tmux-manager.ts'), 'utf8');
   const methodStart = source.indexOf('capturePaneBuffer(muxName: string');
-  const methodBody = source.slice(methodStart, methodStart + 4000);
+  // Bounded at the next method so `methodBody` really is one method: the
+  // ordering assertions below would otherwise be satisfiable by a neighbour.
+  const methodEnd = source.indexOf('captureActivePaneBuffer(muxName: string', methodStart);
+  const methodBody = source.slice(methodStart, methodEnd);
 
   it('capturePaneBuffer accepts pane-capture options with a fullHistory flag', () => {
     expect(methodStart).toBeGreaterThan(-1);
@@ -42,13 +46,37 @@ describe('tmux full-history pane capture (COD-47)', () => {
   });
 
   it('returns full-history capture as raw scrollback (skips the single-screen repaint)', () => {
-    // When fullHistory, return the raw buffer BEFORE the formatPaneSnapshot
-    // repaint (which is single-screen and would clip a multi-screen history).
-    const earlyReturn = methodBody.indexOf('return normalizeScrollbackEol(buffer);');
+    // The fullHistory branch returns before the formatPaneSnapshot repaint,
+    // which is single-screen and would clip a multi-screen history.
+    const branch = methodBody.indexOf('if (fullHistory) {\n        // Without geometry');
     const snapshot = methodBody.indexOf('formatPaneSnapshot(');
-    expect(earlyReturn).toBeGreaterThan(-1);
+    expect(branch).toBeGreaterThan(-1);
     expect(snapshot).toBeGreaterThan(-1);
-    expect(earlyReturn).toBeLessThan(snapshot);
+    expect(branch).toBeLessThan(snapshot);
+    // …and what it returns is normalized linear scrollback, not a repaint.
+    expect(methodBody.slice(branch, snapshot)).toContain('normalizeScrollbackEol(');
+  });
+
+  it('appends the pane cursor to the full-history capture', () => {
+    // A linear replay leaves the caret wherever the last character landed — the
+    // status line, for an agent CLI — and every cursor-relative update the CLI
+    // sends afterwards is then measured from the wrong row.
+    const restore = methodBody.indexOf('formatCursorRestore(geometry)');
+    const snapshot = methodBody.indexOf('formatPaneSnapshot(');
+    expect(restore).toBeGreaterThan(-1);
+    expect(restore).toBeLessThan(snapshot);
+  });
+
+  it('keeps the trailing rows only when a cursor move will follow', () => {
+    // Trailing blank rows are the bottom of the screen and the cursor move counts
+    // up from them, so the two decisions travel together: no geometry, no move,
+    // and the old trim applies instead.
+    expect(methodBody).toContain("rawCapture.replace(/\\n$/, '')");
+    expect(methodBody).toContain("if (!geometry) return normalizeScrollbackEol(rawCapture.replace(/\\n+$/g, ''))");
+  });
+
+  it('defers to the byte history when the pane holds nothing visible', () => {
+    expect(methodBody).toContain("if (!hasVisibleContent(trimmed)) return ''");
   });
 
   it('captureActivePaneBuffer forwards the capture options', () => {
@@ -59,3 +87,37 @@ describe('tmux full-history pane capture (COD-47)', () => {
     expect(body).toContain('this.capturePaneBuffer(muxName, target, opts)');
   });
 });
+
+describe('full-history cursor restore', () => {
+  it('counts up from the last replayed row rather than down from the top', () => {
+    // Relative, not `CUP`: absolute row addressing is only correct while the
+    // browser's row count equals the pane's, and resizeWindow does not wait for
+    // tmux, so a capture can be taken before a requested resize has applied.
+    expect(formatCursorRestore({ cols: 80, rows: 24, cursorX: 2, cursorY: 20 })).toBe('\x1b[3A\r\x1b[2C');
+  });
+
+  it('emits no row move when the caret is already on the last row', () => {
+    expect(formatCursorRestore({ cols: 80, rows: 24, cursorX: 5, cursorY: 23 })).toBe('\r\x1b[5C');
+  });
+
+  it('emits no column move for column zero', () => {
+    expect(formatCursorRestore({ cols: 80, rows: 10, cursorX: 0, cursorY: 0 })).toBe('\x1b[9A\r');
+  });
+});
+
+describe('hasVisibleContent', () => {
+  it('is false for a pane of blank rows', () => {
+    expect(hasVisibleContent('\n'.repeat(23))).toBe(false);
+  });
+
+  it('is false for blank rows carrying only SGR attributes', () => {
+    // `capture-pane -e` styles every row, so an all-blank pane is not an empty
+    // string. Treating it as content would replace the byte history with a
+    // blank screen.
+    expect(hasVisibleContent('\x1b[m   \x1b[0m\n\x1b[m   \x1b[0m')).toBe(false);
+  });
+
+  it('is true as soon as one row carries a character', () => {
+    expect(hasVisibleContent('\x1b[m   \x1b[0m\n\x1b[m x \x1b[0m')).toBe(true);
+  });
+});