feat: preserve scroll position on write

Change-Id: I3460285d7e278bbd0a3a02a056738ae734c8eb1a
Signed-off-by: Thomas Kosiewski <tk@coder.com>

Author: ThomasK33

lib/interfaces.ts

@@ -21,6 +21,7 @@ export interface ITerminalOptions {
 
   // Scrolling options
   smoothScrollDuration?: number; // Duration in ms for smooth scroll animation (default: 100, 0 = instant)
+  preserveScrollOnWrite?: boolean; // Preserve scrolled-up viewport on write (default: false)
 
   // Internal: Ghostty WASM instance (optional, for test isolation)
   // If not provided, uses the module-level instance from init()

lib/scrolling.test.ts

@@ -6,6 +6,7 @@
  */
 
 import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import type { ITerminalOptions } from './interfaces';
 import type { Terminal } from './terminal';
 import { createIsolatedTerminal } from './test-helpers';
 
@@ -680,3 +681,276 @@ describe('Custom Wheel Event Handler', () => {
     expect((term as any).viewportY).toBeGreaterThan(0);
   });
 });
+
+type ScrollTestOptions = Omit<ITerminalOptions, 'ghostty'>;
+
+async function createPreserveScrollTestTerminal(
+  options: ScrollTestOptions = {}
+): Promise<{ term: Terminal; container: HTMLDivElement }> {
+  const container = document.createElement('div');
+  document.body.appendChild(container);
+  const term = await createIsolatedTerminal({
+    cols: 20,
+    rows: 5,
+    scrollback: 100,
+    smoothScrollDuration: 0,
+    ...options,
+  });
+  term.open(container);
+  return { term, container };
+}
+
+function disposePreserveScrollTestTerminal(term: Terminal, container: HTMLDivElement): void {
+  term.dispose();
+  document.body.removeChild(container);
+}
+
+function writeNumberedLines(term: Terminal, count: number, start = 0): void {
+  for (let i = start; i < start + count; i++) {
+    term.write(`Line ${i.toString().padStart(3, '0')}\r\n`);
+  }
+}
+
+function cellsToText(cells: Array<{ codepoint: number }> | null | undefined): string {
+  if (!cells) return '';
+
+  return cells
+    .map((cell) => {
+      const codepoint = cell.codepoint;
+      if (codepoint <= 0 || codepoint > 0x10ffff) return '';
+      if (codepoint >= 0xd800 && codepoint <= 0xdfff) return '';
+      return String.fromCodePoint(codepoint);
+    })
+    .join('')
+    .trimEnd();
+}
+
+function getVisibleLineText(term: Terminal, row: number): string {
+  if (!term.wasmTerm) {
+    throw new Error('Terminal must be open before reading visible lines');
+  }
+
+  const viewportY = Math.max(0, Math.floor(term.getViewportY()));
+  const scrollbackLength = term.getScrollbackLength();
+
+  if (viewportY > 0 && row < viewportY) {
+    const scrollbackOffset = scrollbackLength - viewportY + row;
+    return cellsToText(term.getScrollbackLine(scrollbackOffset));
+  }
+
+  const screenRow = viewportY > 0 ? row - viewportY : row;
+  return cellsToText(term.wasmTerm.getLine(screenRow));
+}
+
+function clampViewportY(viewportY: number, scrollbackLength: number): number {
+  return Math.max(0, Math.min(viewportY, scrollbackLength));
+}
+
+function makeSignatureLine(
+  text: string
+): Array<{ codepoint: number; flags: number; width: number }> {
+  return Array.from({ length: 20 }, (_, index) => ({
+    codepoint: index < text.length ? text.codePointAt(index)! : 0,
+    flags: 0,
+    width: 1,
+  }));
+}
+
+describe('preserveScrollOnWrite', () => {
+  test('write() scrolls to bottom by default when viewport is scrolled up', async () => {
+    const { term, container } = await createPreserveScrollTestTerminal();
+
+    try {
+      expect(term.options.preserveScrollOnWrite).toBe(false);
+
+      writeNumberedLines(term, 12);
+      expect(term.getScrollbackLength()).toBeGreaterThanOrEqual(3);
+
+      term.scrollLines(-3);
+      expect(term.getViewportY()).toBe(3);
+
+      term.write('Line 012\r\n');
+
+      expect(term.getViewportY()).toBe(0);
+    } finally {
+      disposePreserveScrollTestTerminal(term, container);
+    }
+  });
+
+  test('write() preserves scrolled-up viewport on opt-in and emits onScroll', async () => {
+    const { term, container } = await createPreserveScrollTestTerminal({
+      preserveScrollOnWrite: true,
+    });
+
+    try {
+      writeNumberedLines(term, 12);
+      term.scrollLines(-3);
+
+      const beforeViewportY = term.getViewportY();
+      const beforeScrollbackLength = term.getScrollbackLength();
+      const beforeTopLine = getVisibleLineText(term, 0);
+      const scrollEvents: number[] = [];
+      const scrollDisposable = term.onScroll((value) => scrollEvents.push(value));
+
+      try {
+        term.write('Line 012\r\n');
+
+        const afterScrollbackLength = term.getScrollbackLength();
+        const expectedViewportY = clampViewportY(
+          beforeViewportY + (afterScrollbackLength - beforeScrollbackLength),
+          afterScrollbackLength
+        );
+
+        expect(afterScrollbackLength).toBeGreaterThan(beforeScrollbackLength);
+        expect(term.getViewportY()).toBe(expectedViewportY);
+        expect(getVisibleLineText(term, 0)).toBe(beforeTopLine);
+        expect(scrollEvents.at(-1)).toBe(Math.floor(term.getViewportY()));
+      } finally {
+        scrollDisposable.dispose();
+      }
+    } finally {
+      disposePreserveScrollTestTerminal(term, container);
+    }
+  });
+
+  test('write() scrolls to bottom instead of preserving when entering alternate screen', async () => {
+    const { term, container } = await createPreserveScrollTestTerminal({
+      preserveScrollOnWrite: true,
+    });
+
+    try {
+      writeNumberedLines(term, 12);
+      term.scrollLines(-3);
+      expect(term.getViewportY()).toBe(3);
+
+      term.write('\x1b[?1049h');
+
+      expect(term.wasmTerm?.isAlternateScreen()).toBe(true);
+      expect(term.getViewportY()).toBe(0);
+    } finally {
+      disposePreserveScrollTestTerminal(term, container);
+    }
+  });
+
+  test('write() preserves viewport when capped scrollback evicts old rows', async () => {
+    const { term, container } = await createPreserveScrollTestTerminal({
+      preserveScrollOnWrite: true,
+    });
+
+    const oldScrollback = ['old-0', 'old-1', 'old-2', 'old-3', 'old-4'].map(makeSignatureLine);
+    const newScrollback = ['old-1', 'old-2', 'old-3', 'old-4', 'new-5'].map(makeSignatureLine);
+    const originalWrite = term.wasmTerm!.write.bind(term.wasmTerm);
+    const originalGetScrollbackLength = term.getScrollbackLength.bind(term);
+    const originalGetScrollbackLine = term.getScrollbackLine.bind(term);
+    let afterWrite = false;
+
+    try {
+      term.viewportY = 3;
+      (term as any).targetViewportY = 3;
+      (term as any).getScrollbackLength = () => 5;
+      (term as any).getScrollbackLine = (offset: number) =>
+        (afterWrite ? newScrollback : oldScrollback)[offset] ?? null;
+      term.wasmTerm!.write = (() => {
+        afterWrite = true;
+      }) as typeof term.wasmTerm.write;
+
+      term.write('Line 005\r\n');
+
+      expect(term.getViewportY()).toBe(4);
+    } finally {
+      term.wasmTerm!.write = originalWrite;
+      (term as any).getScrollbackLength = originalGetScrollbackLength;
+      (term as any).getScrollbackLine = originalGetScrollbackLine;
+      disposePreserveScrollTestTerminal(term, container);
+    }
+  });
+
+  test('write() falls back to scrollback delta when preserved anchor disappears', async () => {
+    const { term, container } = await createPreserveScrollTestTerminal({
+      preserveScrollOnWrite: true,
+    });
+
+    const oldScrollback = ['old-0', 'old-1', 'old-2', 'old-3', 'old-4'].map(makeSignatureLine);
+    const newScrollback = ['new-0', 'new-1', 'new-2', 'new-3', 'new-4'].map(makeSignatureLine);
+    const originalWrite = term.wasmTerm!.write.bind(term.wasmTerm);
+    const originalGetScrollbackLength = term.getScrollbackLength.bind(term);
+    const originalGetScrollbackLine = term.getScrollbackLine.bind(term);
+    let afterWrite = false;
+
+    try {
+      term.viewportY = 3;
+      (term as any).targetViewportY = 3;
+      (term as any).getScrollbackLength = () => 5;
+      (term as any).getScrollbackLine = (offset: number) =>
+        (afterWrite ? newScrollback : oldScrollback)[offset] ?? null;
+      term.wasmTerm!.write = (() => {
+        afterWrite = true;
+      }) as typeof term.wasmTerm.write;
+
+      term.write('\x1bc');
+
+      expect(term.getViewportY()).toBe(3);
+    } finally {
+      term.wasmTerm!.write = originalWrite;
+      (term as any).getScrollbackLength = originalGetScrollbackLength;
+      (term as any).getScrollbackLine = originalGetScrollbackLine;
+      disposePreserveScrollTestTerminal(term, container);
+    }
+  });
+
+  test('write() does not move preserved viewport when scrollback does not grow', async () => {
+    const { term, container } = await createPreserveScrollTestTerminal({
+      preserveScrollOnWrite: true,
+    });
+
+    try {
+      writeNumberedLines(term, 12);
+      term.scrollLines(-3);
+
+      const beforeViewportY = term.getViewportY();
+      const beforeScrollbackLength = term.getScrollbackLength();
+      const scrollEvents: number[] = [];
+      const scrollDisposable = term.onScroll((value) => scrollEvents.push(value));
+
+      try {
+        term.write('x');
+
+        expect(term.getScrollbackLength()).toBe(beforeScrollbackLength);
+        expect(term.getViewportY()).toBe(beforeViewportY);
+        expect(scrollEvents).toEqual([]);
+      } finally {
+        scrollDisposable.dispose();
+      }
+    } finally {
+      disposePreserveScrollTestTerminal(term, container);
+    }
+  });
+
+  test('preserveScrollOnWrite can be enabled at runtime through terminal options', async () => {
+    const { term, container } = await createPreserveScrollTestTerminal();
+
+    try {
+      writeNumberedLines(term, 12);
+      term.scrollLines(-3);
+      term.write('Default mode\r\n');
+      expect(term.getViewportY()).toBe(0);
+
+      term.options.preserveScrollOnWrite = true;
+      term.scrollLines(-3);
+
+      const beforeViewportY = term.getViewportY();
+      const beforeScrollbackLength = term.getScrollbackLength();
+      term.write('Opt-in mode\r\n');
+
+      const afterScrollbackLength = term.getScrollbackLength();
+      expect(term.getViewportY()).toBe(
+        clampViewportY(
+          beforeViewportY + (afterScrollbackLength - beforeScrollbackLength),
+          afterScrollbackLength
+        )
+      );
+    } finally {
+      disposePreserveScrollTestTerminal(term, container);
+    }
+  });
+});