@aurigax-ai/ghostty-web 0.3.1 → 0.3.3

package/README.md

@@ -66,7 +66,9 @@ in the output stream:
 | `modes.mouseTrackingMode` | `none`, `x10`, `vt200`, `drag` or `any`                                                                |
 
 The render loop runs only while something changes (output, input, scrolling, selection, cursor
-blink) and sleeps otherwise.
+blink) and sleeps otherwise. `setPaused(true)` stops drawing a terminal that is off screen while it
+keeps parsing output; `setPaused(false)` redraws it whole. `setPaused(true, { releaseRenderer: true })`
+also gives up its WebGL context until then, since browsers keep only a few.
 
 ## Use
 

package/lib/abi.ts

@@ -32,6 +32,9 @@ interface TypeLayout {
   values?: Record<string, number>;
 }
 
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+
 const I32 = 0x7f;
 const I64 = 0x7e;
 
@@ -95,13 +98,16 @@ export class GhosttyCallError extends Error {
 export class Abi {
   private readonly types: Record<string, TypeLayout>;
   private readonly freeSlots: number[] = [];
+  private scratchPtr = 0;
+  private scratchLen = 0;
+  private readonly input = { ptr: 0, len: 0, busy: false };
 
   constructor(readonly exports: VtExports) {
     const ptr = this.fn('ghostty_type_json')() as number;
     const bytes = new Uint8Array(exports.memory.buffer);
     let end = ptr;
     while (bytes[end] !== 0) end++;
-    this.types = JSON.parse(new TextDecoder().decode(bytes.subarray(ptr, end))).types;
+    this.types = JSON.parse(decoder.decode(bytes.subarray(ptr, end))).types;
   }
 
   fn(name: string): Fn {
@@ -188,6 +194,69 @@ export class Abi {
     });
   }
 
+  /**
+   * A zeroed buffer of at least `len` bytes, the same one on every call, for a
+   * read that is done with it before anything else calls scratch().
+   */
+  scratch(len: number): number {
+    if (len > this.scratchLen) {
+      if (this.scratchPtr) this.free(this.scratchPtr, this.scratchLen);
+      this.scratchPtr = 0;
+      this.scratchLen = 0;
+      const size = Math.max(len, 64);
+      this.scratchPtr = this.alloc(size);
+      this.scratchLen = size;
+    } else {
+      this.bytes().fill(0, this.scratchPtr, this.scratchPtr + len);
+    }
+    return this.scratchPtr;
+  }
+
+  /** scratch() holding a sized struct (its leading `size` field set), as GHOSTTY_INIT_SIZED does. */
+  scratchSized(type: string): number {
+    const size = this.sizeOf(type);
+    const ptr = this.scratch(size);
+    this.view().setUint32(ptr, size, true);
+    return ptr;
+  }
+
+  /**
+   * Runs `use` on text (as UTF-8) or bytes copied into a grow-only buffer kept
+   * between calls. A call from inside `use` (a terminal written to from one of
+   * the callbacks a write runs) gets a buffer of its own.
+   */
+  withInput<T>(data: string | Uint8Array, use: (ptr: number, len: number) => T): T {
+    if (this.input.busy) {
+      return this.withBytes(typeof data === 'string' ? encoder.encode(data) : data, use);
+    }
+    // UTF-8 takes at most 3 bytes per UTF-16 code unit.
+    const max = typeof data === 'string' ? data.length * 3 : data.length;
+    if (max === 0) return use(0, 0);
+    const input = this.input;
+    if (max > input.len) {
+      if (input.ptr) this.free(input.ptr, input.len);
+      input.ptr = 0;
+      input.len = 0;
+      const len = Math.max(max, 4096);
+      input.ptr = this.call('ghostty_wasm_alloc', len);
+      if (input.ptr === 0) throw new GhosttyCallError('ghostty_wasm_alloc', -1);
+      input.len = len;
+    }
+    const bytes = this.bytes();
+    let len = data.length;
+    if (typeof data === 'string') {
+      len = encoder.encodeInto(data, bytes.subarray(input.ptr, input.ptr + input.len)).written;
+    } else {
+      bytes.set(data, input.ptr);
+    }
+    input.busy = true;
+    try {
+      return use(input.ptr, len);
+    } finally {
+      input.busy = false;
+    }
+  }
+
   /** Runs a constructor that writes an opaque handle into an out slot and returns the handle. */
   newHandle(name: string, construct: (slot: number) => number): number {
     const slot = this.call('ghostty_wasm_alloc_opaque');
@@ -203,7 +272,7 @@ export class Abi {
 
   string(ptr: number, len: number): string {
     if (len === 0) return '';
-    return new TextDecoder().decode(this.bytes().slice(ptr, ptr + len));
+    return decoder.decode(this.bytes().subarray(ptr, ptr + len));
   }
 
   /** Registers a JavaScript callback in the function table and returns its index (the C function pointer). */

package/lib/ghostty.ts

@@ -229,7 +229,9 @@ export interface TrackedRow {
 
 const POINT_ACTIVE = 'ACTIVE';
 const POINT_HISTORY = 'HISTORY';
+const POINT_SCREEN = 'SCREEN';
 type PointSpace = typeof POINT_ACTIVE | typeof POINT_HISTORY;
+type PointTag = PointSpace | typeof POINT_SCREEN;
 
 const GRAPHEME_CAP = 16;
 const GRAPHEME_CLUSTER_MODE = 2027;
@@ -560,6 +562,8 @@ export class GhosttyTerminal {
   private readonly layout: CellLayout;
   private readonly scratch: ExtractScratch;
   private cellPool: GhosttyCell[] = [];
+  /** Each row of cellPool as an array of the same cell objects. */
+  private rowViews: GhosttyCell[][] = [];
   private rowDirty: boolean[] = [];
   private dirty: DirtyState = DirtyState.FULL;
   private changed = true;
@@ -569,8 +573,13 @@ export class GhosttyTerminal {
     cursor: null,
     palette: [],
   };
+  /** libghostty-vt changes the palette only with a full redraw, or through configure(). */
+  private paletteStale = true;
+  private cursor: RenderStateCursor | null = null;
   private responses: string[] = [];
   private callbacks: number[] = [];
+  /** A tracked row at the top of each screen, keyed by whether it is the alternate one. */
+  private screenTops = new Map<boolean, TrackedRow>();
 
   private readonly bellEmitter = new EventEmitter<void>();
   private readonly titleEmitter = new EventEmitter<string>();
@@ -658,8 +667,7 @@ export class GhosttyTerminal {
   // ==========================================================================
 
   write(data: string | Uint8Array): void {
-    const bytes = typeof data === 'string' ? new TextEncoder().encode(data) : data;
-    this.abi.withBytes(bytes, (ptr, len) =>
+    this.abi.withInput(data, (ptr, len) =>
       this.abi.call('ghostty_terminal_vt_write', this.handle, ptr, len)
     );
     this.changed = true;
@@ -681,6 +689,8 @@ export class GhosttyTerminal {
     abi.call('ghostty_render_state_row_iterator_free', this.rowIterator);
     abi.call('ghostty_render_state_free', this.renderState);
     abi.free(this.scratch.base, this.scratch.size);
+    for (const top of this.screenTops.values()) top.free();
+    this.screenTops.clear();
     abi.call('ghostty_terminal_free', this.handle);
     for (const index of this.callbacks) abi.removeCallback(index);
     this.callbacks = [];
@@ -713,43 +723,50 @@ export class GhosttyTerminal {
     abi.check('ghostty_render_state_update', this.renderState, this.handle);
     const dirty = this.readRenderU32('DIRTY') as DirtyState;
     if (dirty > this.dirty || this.dirty === DirtyState.NONE) this.dirty = dirty;
-    this.readColors();
+    this.cursor = null;
+    this.readColors(this.dirty === DirtyState.FULL || this.paletteStale);
+    this.paletteStale = false;
     this.extractRows(this.dirty === DirtyState.FULL);
     return this.dirty;
   }
 
+  /** The cursor as of the last update; the same object until the render state changes. */
   getCursor(): RenderStateCursor {
     this.update();
+    this.cursor ??= this.readCursor();
+    return this.cursor;
+  }
+
+  private readCursor(): RenderStateCursor {
     const abi = this.abi;
-    return abi.withSized('GhosttyRenderStateCursor', (ptr) => {
-      abi.check(
-        'ghostty_render_state_get',
-        this.renderState,
-        abi.enumValue('GhosttyRenderStateData', 'CURSOR'),
-        ptr
-      );
-      const view = abi.view();
-      const at = (f: string) => ptr + abi.offset('GhosttyRenderStateCursor', f);
-      const inViewport = view.getUint8(at('viewport_has_value')) !== 0;
-      const x = inViewport ? view.getUint16(at('viewport_x'), true) : -1;
-      const y = inViewport ? view.getUint16(at('viewport_y'), true) : -1;
-      const style = view.getInt32(at('visual_style'), true);
-      const styles = 'GhosttyRenderStateCursorVisualStyle';
-      return {
-        x,
-        y,
-        viewportX: x,
-        viewportY: y,
-        visible: inViewport && view.getUint8(at('visible')) !== 0,
-        blinking: view.getUint8(at('blinking')) !== 0,
-        style:
-          style === abi.enumValue(styles, 'BAR')
-            ? 'bar'
-            : style === abi.enumValue(styles, 'UNDERLINE')
-              ? 'underline'
-              : 'block',
-      };
-    });
+    const ptr = abi.scratchSized('GhosttyRenderStateCursor');
+    abi.check(
+      'ghostty_render_state_get',
+      this.renderState,
+      abi.enumValue('GhosttyRenderStateData', 'CURSOR'),
+      ptr
+    );
+    const view = abi.view();
+    const at = (f: string) => ptr + abi.offset('GhosttyRenderStateCursor', f);
+    const inViewport = view.getUint8(at('viewport_has_value')) !== 0;
+    const x = inViewport ? view.getUint16(at('viewport_x'), true) : -1;
+    const y = inViewport ? view.getUint16(at('viewport_y'), true) : -1;
+    const style = view.getInt32(at('visual_style'), true);
+    const styles = 'GhosttyRenderStateCursorVisualStyle';
+    return {
+      x,
+      y,
+      viewportX: x,
+      viewportY: y,
+      visible: inViewport && view.getUint8(at('visible')) !== 0,
+      blinking: view.getUint8(at('blinking')) !== 0,
+      style:
+        style === abi.enumValue(styles, 'BAR')
+          ? 'bar'
+          : style === abi.enumValue(styles, 'UNDERLINE')
+            ? 'underline'
+            : 'block',
+    };
   }
 
   /**
@@ -792,6 +809,17 @@ export class GhosttyTerminal {
     return this.cellPool.slice(start, start + this._cols).map((cell) => ({ ...cell }));
   }
 
+  /**
+   * A row's cells as the renderer reads them: the terminal's own cell objects,
+   * updated in place by later updates, so read them before the next one and
+   * never modify them. getLine() returns a copy to keep.
+   */
+  getLineView(y: number): readonly GhosttyCell[] | null {
+    if (y < 0 || y >= this._rows) return null;
+    this.update();
+    return this.rowViews[y];
+  }
+
   isDirty(): boolean {
     return this.update() !== DirtyState.NONE;
   }
@@ -833,13 +861,41 @@ export class GhosttyTerminal {
 
   /** Tracks the start of a row of the active area. */
   trackRow(activeY: number): TrackedRow | null {
+    return this.trackLineStart(POINT_ACTIVE, activeY);
+  }
+
+  /**
+   * Whether the terminal may have discarded rows since the last call, which is
+   * the only way a tracked row loses its line: libghostty-vt prunes scrollback
+   * from its first page and resets a screen whole, and either marks every
+   * tracked row on that page stale. A tracked row at the top of each screen
+   * goes stale with them. A screen is watched from the first call made while it
+   * is active.
+   */
+  rowsDiscarded(): boolean {
+    let discarded = false;
+    for (const [alternate, top] of this.screenTops) {
+      if (top.line() === 0) continue;
+      discarded = true;
+      top.free();
+      this.screenTops.delete(alternate);
+    }
+    const alternate = this.isAlternateScreen();
+    if (!this.screenTops.has(alternate)) {
+      const top = this.trackLineStart(POINT_SCREEN, 0);
+      if (top) this.screenTops.set(alternate, top);
+    }
+    return discarded;
+  }
+
+  private trackLineStart(tag: PointTag, y: number): TrackedRow | null {
     const abi = this.abi;
     const ref = abi.with(abi.sizeOf('GhosttyPoint'), (point) => {
       const view = abi.view();
-      view.setInt32(point, abi.enumValue('GhosttyPointTag', POINT_ACTIVE), true);
+      view.setInt32(point, abi.enumValue('GhosttyPointTag', tag), true);
       const coord = point + abi.offset('GhosttyPoint', 'value');
       view.setUint16(coord + abi.offset('GhosttyPointCoordinate', 'x'), 0, true);
-      view.setUint32(coord + abi.offset('GhosttyPointCoordinate', 'y'), activeY, true);
+      view.setUint32(coord + abi.offset('GhosttyPointCoordinate', 'y'), y, true);
       const slot = abi.call('ghostty_wasm_alloc_opaque');
       try {
         const result = abi.call('ghostty_terminal_grid_ref_track', this.handle, point, slot);
@@ -853,16 +909,11 @@ export class GhosttyTerminal {
     return {
       line: () => {
         if (freed) return null;
-        return abi.with(abi.sizeOf('GhosttyPointCoordinate'), (out) => {
-          const result = abi.call(
-            'ghostty_tracked_grid_ref_point',
-            ref,
-            abi.enumValue('GhosttyPointTag', 'SCREEN'),
-            out
-          );
-          if (result !== GHOSTTY_SUCCESS) return null;
-          return abi.view().getUint32(out + abi.offset('GhosttyPointCoordinate', 'y'), true);
-        });
+        const out = abi.scratch(abi.sizeOf('GhosttyPointCoordinate'));
+        const tag = abi.enumValue('GhosttyPointTag', POINT_SCREEN);
+        if (abi.call('ghostty_tracked_grid_ref_point', ref, tag, out) !== GHOSTTY_SUCCESS)
+          return null;
+        return abi.view().getUint32(out + abi.offset('GhosttyPointCoordinate', 'y'), true);
       },
       free: () => {
         if (freed) return;
@@ -1009,6 +1060,8 @@ export class GhosttyTerminal {
    */
   configure(config: GhosttyTerminalConfig): void {
     const abi = this.abi;
+    this.paletteStale = true;
+    this.changed = true;
     if (config.scrollbackLimit !== undefined) {
       this.setOption('SCROLLBACK_MAX_BYTES', 0);
       abi.with(4, (ptr) => {
@@ -1170,46 +1223,35 @@ export class GhosttyTerminal {
 
   private readTerminalU32(data: string): number {
     const abi = this.abi;
-    return abi.with(8, (out) => {
-      abi.check(
-        'ghostty_terminal_get',
-        this.handle,
-        abi.enumValue('GhosttyTerminalData', data),
-        out
-      );
-      return abi.view().getUint32(out, true);
-    });
+    const out = abi.scratch(8);
+    abi.check('ghostty_terminal_get', this.handle, abi.enumValue('GhosttyTerminalData', data), out);
+    return abi.view().getUint32(out, true);
   }
 
   private readTerminalU16(data: string): number {
     const abi = this.abi;
-    return abi.with(8, (out) => {
-      abi.check(
-        'ghostty_terminal_get',
-        this.handle,
-        abi.enumValue('GhosttyTerminalData', data),
-        out
-      );
-      return abi.view().getUint16(out, true);
-    });
+    const out = abi.scratch(8);
+    abi.check('ghostty_terminal_get', this.handle, abi.enumValue('GhosttyTerminalData', data), out);
+    return abi.view().getUint16(out, true);
   }
 
   private readRenderU32(data: string): number {
     const abi = this.abi;
-    return abi.with(8, (out) => {
-      abi.check(
-        'ghostty_render_state_get',
-        this.renderState,
-        abi.enumValue('GhosttyRenderStateData', data),
-        out
-      );
-      return abi.view().getUint32(out, true);
-    });
+    const out = abi.scratch(8);
+    abi.check(
+      'ghostty_render_state_get',
+      this.renderState,
+      abi.enumValue('GhosttyRenderStateData', data),
+      out
+    );
+    return abi.view().getUint32(out, true);
   }
 
-  private readColors(): void {
+  /** Reads the colors cells are drawn with; the 256-color palette only when `palette`. */
+  private readColors(palette: boolean): void {
     const abi = this.abi;
-    abi.withSized('GhosttyRenderStateColors', (ptr) => {
+    if (palette) {
+      const ptr = abi.scratchSized('GhosttyRenderStateColors');
       abi.check(
         'ghostty_render_state_get',
         this.renderState,
@@ -1218,16 +1260,16 @@ export class GhosttyTerminal {
       );
       const view = abi.view();
       const at = (f: string) => ptr + abi.offset('GhosttyRenderStateColors', f);
-      const palette: RGB[] = [];
-      for (let i = 0; i < 256; i++) palette.push(rgbAt(view, at('palette') + i * 3));
+      const colors: RGB[] = [];
+      for (let i = 0; i < 256; i++) colors.push(rgbAt(view, at('palette') + i * 3));
       this.colors = {
         background: rgbAt(view, at('background')),
         foreground: rgbAt(view, at('foreground')),
         cursor: view.getUint8(at('cursor_has_value')) ? rgbAt(view, at('cursor')) : null,
-        palette,
+        palette: colors,
       };
-    });
-    this.readTerminalColors();
+    }
+    this.readTerminalColors(palette);
   }
 
   /**
@@ -1235,28 +1277,27 @@ export class GhosttyTerminal {
    * ghostty_terminal_set, so the effective colors (a program's OSC override,
    * else the default) are read from the terminal itself.
    */
-  private readTerminalColors(): void {
+  private readTerminalColors(palette: boolean): void {
     const abi = this.abi;
     const data = (name: string) => abi.enumValue('GhosttyTerminalData', name);
-    const rgb = (name: string): RGB | null =>
-      abi.with(4, (ptr) =>
-        abi.call('ghostty_terminal_get', this.handle, data(name), ptr) === GHOSTTY_SUCCESS
-          ? rgbAt(abi.view(), ptr)
-          : null
-      );
+    const rgb = (name: string): RGB | null => {
+      const ptr = abi.scratch(4);
+      return abi.call('ghostty_terminal_get', this.handle, data(name), ptr) === GHOSTTY_SUCCESS
+        ? rgbAt(abi.view(), ptr)
+        : null;
+    };
     this.colors.background = rgb('COLOR_BACKGROUND') ?? this.colors.background;
     this.colors.foreground = rgb('COLOR_FOREGROUND') ?? this.colors.foreground;
     this.colors.cursor = rgb('COLOR_CURSOR') ?? this.colors.cursor;
-    abi.with(256 * 3, (ptr) => {
-      if (
-        abi.call('ghostty_terminal_get', this.handle, data('COLOR_PALETTE'), ptr) !==
-        GHOSTTY_SUCCESS
-      ) {
-        return;
-      }
-      const view = abi.view();
-      for (let i = 0; i < 256; i++) this.colors.palette[i] = rgbAt(view, ptr + i * 3);
-    });
+    if (!palette) return;
+    const ptr = abi.scratch(256 * 3);
+    if (
+      abi.call('ghostty_terminal_get', this.handle, data('COLOR_PALETTE'), ptr) !== GHOSTTY_SUCCESS
+    ) {
+      return;
+    }
+    const view = abi.view();
+    for (let i = 0; i < 256; i++) this.colors.palette[i] = rgbAt(view, ptr + i * 3);
   }
 
   private extractRows(all: boolean): void {
@@ -1476,6 +1517,10 @@ export class GhosttyTerminal {
     const total = this._cols * this._rows;
     while (this.cellPool.length < total) this.cellPool.push(GhosttyTerminal.emptyCell());
     this.cellPool.length = total;
+    this.rowViews = [];
+    for (let y = 0; y < this._rows; y++) {
+      this.rowViews.push(this.cellPool.slice(y * this._cols, (y + 1) * this._cols));
+    }
     this.rowDirty = new Array(this._rows).fill(true);
     this.dirty = DirtyState.FULL;
   }

package/lib/input-handler.ts

@@ -192,7 +192,6 @@ export class InputHandler {
   private mousedownListener: ((e: MouseEvent) => void) | null = null;
   private mouseupListener: ((e: MouseEvent) => void) | null = null;
   private mousemoveListener: ((e: MouseEvent) => void) | null = null;
-  private wheelListener: ((e: WheelEvent) => void) | null = null;
   private isComposing = false;
   private isDisposed = false;
   /**
@@ -319,9 +318,6 @@ export class InputHandler {
 
     this.mousemoveListener = this.handleMouseMove.bind(this);
     this.container.addEventListener('mousemove', this.mousemoveListener);
-
-    this.wheelListener = this.handleWheel.bind(this);
-    this.container.addEventListener('wheel', this.wheelListener, { passive: false });
   }
 
   /**
@@ -925,7 +921,7 @@ export class InputHandler {
   /**
    * Handle wheel event (scroll)
    */
-  private handleWheel(event: WheelEvent): void {
+  handleWheel(event: WheelEvent): void {
     if (this.isDisposed) return;
     if (!this.mouseConfig?.hasMouseTracking()) return;
 
@@ -1129,11 +1125,6 @@ export class InputHandler {
       this.mousemoveListener = null;
     }
 
-    if (this.wheelListener) {
-      this.container.removeEventListener('wheel', this.wheelListener);
-      this.wheelListener = null;
-    }
-
     this.isDisposed = true;
   }
 

package/lib/renderer.ts

@@ -17,6 +17,8 @@ import { CellFlags } from './types';
 // Interface for objects that can be rendered
 export interface IRenderable {
   getLine(y: number): GhosttyCell[] | null;
+  /** A row's cells without a copy, read before the buffer next changes; getLine() when absent. */
+  getLineView?(y: number): readonly GhosttyCell[] | null;
   getCursor(): { x: number; y: number; visible: boolean };
   getDimensions(): { cols: number; rows: number };
   isRowDirty(y: number): boolean;
@@ -247,6 +249,8 @@ export abstract class TerminalRenderer {
   protected lastCursorPosition: { x: number; y: number } = { x: 0, y: 0 };
   private lastViewportY = 0;
   private fullRedrawPending = false;
+  /** The cursor and scrollbar the last finished frame showed. */
+  private shownOverlay: FrameOverlay | null = null;
 
   /** The buffer of the frame being drawn, for grapheme lookups. */
   protected currentBuffer: IRenderable | null = null;
@@ -290,7 +294,7 @@ export abstract class TerminalRenderer {
   }
 
   /** Draws one viewport row. */
-  protected abstract drawLine(line: GhosttyCell[], y: number, cols: number): void;
+  protected abstract drawLine(line: readonly GhosttyCell[], y: number, cols: number): void;
   /** Whether the drawing surface no longer matches cols × rows. */
   protected abstract surfaceMismatch(cols: number, rows: number): boolean;
   /** Draws the cursor and scrollbar and presents the frame. */
@@ -334,14 +338,15 @@ export abstract class TerminalRenderer {
       this.cursorVisible !== this.lastCursorVisible || this.focused !== this.lastFocused;
     this.lastCursorVisible = this.cursorVisible;
     this.lastFocused = this.focused;
-    if (this.cursorInRows && (cursorMoved || blinked)) {
+    // Scrolled back the cursor is not shown, and its row is not on screen where it is in the buffer.
+    if (this.cursorInRows && viewportY === 0 && (cursorMoved || blinked)) {
       if (!forceAll && !buffer.isRowDirty(cursor.y)) {
-        const line = buffer.getLine(cursor.y);
+        const line = this.bufferLine(cursor.y);
         if (line) this.drawLine(line, cursor.y, dims.cols);
       }
       if (cursorMoved && this.lastCursorPosition.y !== cursor.y) {
         if (!forceAll && !buffer.isRowDirty(this.lastCursorPosition.y)) {
-          const line = buffer.getLine(this.lastCursorPosition.y);
+          const line = this.bufferLine(this.lastCursorPosition.y);
           if (line) this.drawLine(line, this.lastCursorPosition.y, dims.cols);
         }
       }
@@ -364,14 +369,19 @@ export abstract class TerminalRenderer {
       }
     }
 
-    const lineAt = (y: number): GhosttyCell[] | null => {
+    const lineAt = (y: number): readonly GhosttyCell[] | null => {
       if (viewportY > 0) {
         if (y < viewportY && scrollbackProvider) {
           return scrollbackProvider.getScrollbackLine(scrollbackLength - Math.floor(viewportY) + y);
         }
-        return buffer.getLine(y - Math.floor(viewportY));
+        return this.bufferLine(y - Math.floor(viewportY));
       }
-      return buffer.getLine(y);
+      return this.bufferLine(y);
+    };
+    // Scrolled back, viewport row y shows active row y - viewportY; rows above it show scrollback.
+    const rowDirty = (y: number): boolean => {
+      const active = y - Math.floor(viewportY);
+      return active >= 0 && buffer.isRowDirty(active);
     };
 
     const hyperlinkRows = new Set<number>();
@@ -401,12 +411,7 @@ export abstract class TerminalRenderer {
 
     const rowsToRender = new Set<number>();
     for (let y = 0; y < dims.rows; y++) {
-      const needsRender =
-        viewportY > 0 ||
-        forceAll ||
-        buffer.isRowDirty(y) ||
-        selectionRows.has(y) ||
-        hyperlinkRows.has(y);
+      const needsRender = forceAll || rowDirty(y) || selectionRows.has(y) || hyperlinkRows.has(y);
       if (needsRender) {
         rowsToRender.add(y);
         if (y > 0) rowsToRender.add(y - 1);
@@ -419,7 +424,7 @@ export abstract class TerminalRenderer {
       if (line) this.drawLine(line, y, dims.cols);
     }
 
-    this.finishFrame({
+    const overlay: FrameOverlay = {
       cursorX: cursor.x,
       cursorY: cursor.y,
       showCursor: viewportY === 0 && cursor.visible && this.cursorVisible,
@@ -429,11 +434,23 @@ export abstract class TerminalRenderer {
       cols: dims.cols,
       rows: dims.rows,
       scrollbarOpacity: scrollbackProvider ? scrollbarOpacity : 0,
-    });
+    };
+    // A frame with no row drawn and the same cursor and scrollbar has nothing to show.
+    if (rowsToRender.size > 0 || !sameOverlay(overlay, this.shownOverlay)) {
+      this.finishFrame(overlay);
+      this.shownOverlay = overlay;
+    }
     this.lastCursorPosition = { x: cursor.x, y: cursor.y };
     buffer.clearDirty();
   }
 
+  /** A row of the buffer being drawn, without a copy when the buffer offers one. */
+  protected bufferLine(y: number): readonly GhosttyCell[] | null {
+    const buffer = this.currentBuffer;
+    if (!buffer) return null;
+    return buffer.getLineView ? buffer.getLineView(y) : buffer.getLine(y);
+  }
+
   // ==========================================================================
   // Shared helpers
   // ==========================================================================
@@ -441,6 +458,7 @@ export abstract class TerminalRenderer {
   /** Makes the next frame redraw every row. */
   protected requestFullRedraw(): void {
     this.fullRedrawPending = true;
+    this.shownOverlay = null;
   }
 
   /** The text of a cell: its grapheme cluster when it has one, else its codepoint. */
@@ -625,7 +643,9 @@ export abstract class TerminalRenderer {
   }
 
   public setCursorStyle(style: CursorStyle): void {
+    if (style === this.cursorStyle) return;
     this.cursorStyle = style;
+    this.requestFullRedraw();
   }
 
   public setCursorBlink(enabled: boolean): void {
@@ -700,6 +720,21 @@ export function cssRgb(css: string): [number, number, number] {
   return [0, 0, 0];
 }
 
+function sameOverlay(a: FrameOverlay, b: FrameOverlay | null): boolean {
+  return (
+    b !== null &&
+    a.cursorX === b.cursorX &&
+    a.cursorY === b.cursorY &&
+    a.showCursor === b.showCursor &&
+    a.focused === b.focused &&
+    a.viewportY === b.viewportY &&
+    a.scrollbackLength === b.scrollbackLength &&
+    a.cols === b.cols &&
+    a.rows === b.rows &&
+    a.scrollbarOpacity === b.scrollbarOpacity
+  );
+}
+
 function sameRange(a: LinkRange | null, b: LinkRange | null): boolean {
   if (a === b) return true;
   if (!a || !b) return false;
@@ -774,7 +809,7 @@ export class CanvasRenderer extends TerminalRenderer {
    * of one color are one rect; runs of plain ASCII in one style are one
    * fillText, spaced to the cell grid with letterSpacing.
    */
-  protected drawLine(line: GhosttyCell[], y: number, cols: number): void {
+  protected drawLine(line: readonly GhosttyCell[], y: number, cols: number): void {
     const ctx = this.ctx;
     const cellW = this.metrics.width;
     const cellH = this.metrics.height;
@@ -1007,7 +1042,7 @@ export class CanvasRenderer extends TerminalRenderer {
       );
     } else if (this.cursorStyle === 'block') {
       this.ctx.fillRect(cursorX, cursorY, this.metrics.width, this.metrics.height);
-      const line = this.currentBuffer?.getLine(y);
+      const line = this.bufferLine(y);
       if (line?.[x]) {
         this.ctx.save();
         this.ctx.beginPath();

package/lib/terminal.ts

@@ -263,7 +263,7 @@ export class Terminal implements ITerminalCore {
         this.wasmTerm?.configure(this.themeConfig());
         if (this.renderer && this.wasmTerm) {
           this.renderer.setTheme(this.options.theme);
-          this.renderer.render(this.wasmTerm, true, this.viewportY, this, this.scrollbarOpacity);
+          this.draw(true, this.scrollbarOpacity);
         }
         break;
 
@@ -283,7 +283,7 @@ export class Terminal implements ITerminalCore {
       case 'minimumContrastRatio':
         if (this.renderer && this.wasmTerm) {
           this.renderer.setMinimumContrastRatio(this.options.minimumContrastRatio);
-          this.renderer.render(this.wasmTerm, true, this.viewportY, this, this.scrollbarOpacity);
+          this.draw(true, this.scrollbarOpacity);
         }
         break;
 
@@ -329,7 +329,7 @@ export class Terminal implements ITerminalCore {
     this.renderer.resize(this.cols, this.rows);
 
     // Force full re-render with new font
-    this.renderer.render(this.wasmTerm, true, this.viewportY, this);
+    this.draw(true);
   }
 
   /**
@@ -578,7 +578,7 @@ export class Terminal implements ITerminalCore {
       parent.addEventListener('wheel', this.handleWheel, { passive: false, capture: true });
 
       // Render initial blank screen (force full redraw)
-      this.renderer.render(this.wasmTerm, true, this.viewportY, this, this.scrollbarOpacity);
+      this.draw(true, this.scrollbarOpacity);
 
       // Start render loop
       this.startRenderLoop();
@@ -638,10 +638,16 @@ export class Terminal implements ITerminalCore {
 
   /** Replaces a WebGL renderer whose context was lost with a canvas renderer on the same canvas. */
   private fallBackToCanvas(): void {
-    if (!this.renderer || !this.canvas || !(this.renderer instanceof WebglRenderer)) return;
-    const hoveredLink = this.renderer.getHoveredHyperlinkId();
-    this.renderer.dispose();
-    const renderer = new CanvasRenderer(this.canvas, this.rendererOptions());
+    if (!this.canvas || !(this.renderer instanceof WebglRenderer)) return;
+    this.installRenderer(new CanvasRenderer(this.canvas, this.rendererOptions()));
+    this.wake();
+  }
+
+  /** Disposes the current renderer and draws with `renderer` from now on, in its state. */
+  private installRenderer(renderer: TerminalRenderer): void {
+    const old = this.renderer!;
+    const hoveredLink = old.getHoveredHyperlinkId();
+    old.dispose();
     renderer.onNeedsFrame = () => this.requestFrame();
     renderer.setHoveredHyperlinkId(hoveredLink);
     renderer.setFocused(this.focused);
@@ -652,10 +658,47 @@ export class Terminal implements ITerminalCore {
     }
     this.renderer = renderer;
     renderer.resize(this.cols, this.rows);
-    if (this.wasmTerm) {
-      renderer.render(this.wasmTerm, true, this.viewportY, this, this.scrollbarOpacity);
+    this.draw(true, this.scrollbarOpacity);
+  }
+
+  private paused = false;
+  private rendererReleased = false;
+
+  /**
+   * Pauses drawing, for a terminal that is not on screen. Writes still parse and
+   * the buffer, markers and events stay current, but no frame is drawn and
+   * onRender does not fire until resumed, which redraws the whole screen once.
+   * `releaseRenderer` also gives up a WebGL context until then (browsers keep
+   * only a few), at the cost of rebuilding the glyph atlas on resume.
+   */
+  setPaused(paused: boolean, options: { releaseRenderer?: boolean } = {}): void {
+    if (paused) {
+      this.paused = true;
+      this.cancelRenderLoop();
+      if (options.releaseRenderer && this.canvas && this.renderer instanceof WebglRenderer) {
+        // A canvas renderer that never draws keeps metrics and sizing until resume.
+        this.installRenderer(new CanvasRenderer(this.canvas, this.rendererOptions()));
+        this.rendererReleased = true;
+      }
+      return;
     }
-    this.wake();
+    if (!this.paused) return;
+    this.paused = false;
+    if (!this.isOpen || this.isDisposed) return;
+    if (this.rendererReleased) {
+      this.rendererReleased = false;
+      this.installRenderer(this.createRenderer());
+    } else {
+      this.draw(true, this.scrollbarOpacity);
+    }
+    this.renderEmitter.fire({ start: 0, end: this.rows - 1 });
+    this.requestFrame();
+  }
+
+  /** Draws a frame now unless paused; forceAll redraws every row. */
+  private draw(forceAll: boolean, scrollbarOpacity?: number): void {
+    if (this.paused || !this.renderer || !this.wasmTerm) return;
+    this.renderer.render(this.wasmTerm, forceAll, this.viewportY, this, scrollbarOpacity);
   }
 
   /**
@@ -706,9 +749,7 @@ export class Terminal implements ITerminalCore {
 
     if (this.awaitingEcho) {
       this.awaitingEcho = false;
-      if (this.renderer && this.wasmTerm) {
-        this.renderer.render(this.wasmTerm, false, this.viewportY, this, this.scrollbarOpacity);
-      }
+      this.draw(false, this.scrollbarOpacity);
     }
 
     // Render will happen on next animation frame
@@ -800,6 +841,7 @@ export class Terminal implements ITerminalCore {
 
       // Resize WASM terminal (may reallocate buffers, invalidating TypedArray views)
       this.wasmTerm!.resize(cols, rows);
+      this.refreshMarkers(false);
 
       // Resize renderer
       this.renderer!.resize(cols, rows);
@@ -808,7 +850,7 @@ export class Terminal implements ITerminalCore {
       this.resizeEmitter.fire({ cols, rows });
 
       // Force full render
-      this.renderer!.render(this.wasmTerm!, true, this.viewportY, this);
+      this.draw(true);
     } catch (e) {
       console.error('Terminal resize failed:', e);
     }
@@ -1271,12 +1313,12 @@ export class Terminal implements ITerminalCore {
    * Start the render loop
    */
   private startRenderLoop(): void {
-    if (this.animationFrameId) return;
+    if (this.animationFrameId || this.paused) return;
     const loop = () => {
       this.animationFrameId = undefined;
       if (this.isDisposed || !this.isOpen) return;
       const drew = this.wasmTerm!.update() !== DirtyState.NONE;
-      this.renderer!.render(this.wasmTerm!, false, this.viewportY, this, this.scrollbarOpacity);
+      this.draw(false, this.scrollbarOpacity);
       if (drew) this.renderEmitter.fire({ start: 0, end: this.rows - 1 });
       const cursor = this.wasmTerm!.getCursor();
       if (cursor.y !== this.lastCursorY) {
@@ -1667,6 +1709,11 @@ export class Terminal implements ITerminalCore {
       return;
     }
 
+    if (this.wasmTerm?.hasMouseTracking()) {
+      this.inputHandler?.handleWheel(e);
+      return;
+    }
+
     // Check if in alternate screen mode (vim, less, htop, etc.)
     const isAltScreen = this.wasmTerm?.isAlternateScreen() ?? false;
 
@@ -1675,7 +1722,8 @@ export class Terminal implements ITerminalCore {
       // Applications like vim handle scrolling internally
       // Standard: ~3 arrow presses per wheel "click"
       const direction = e.deltaY > 0 ? 'down' : 'up';
-      const count = Math.min(Math.abs(Math.round(e.deltaY / 33)), 5); // Cap at 5
+      const lines = e.deltaMode === WheelEvent.DOM_DELTA_LINE ? e.deltaY : e.deltaY / 33;
+      const count = Math.min(Math.abs(Math.round(lines)), 5); // Cap at 5
 
       for (let i = 0; i < count; i++) {
         if (direction === 'up') {
@@ -1889,9 +1937,7 @@ export class Terminal implements ITerminalCore {
       this.scrollbarOpacity = progress;
 
       // Trigger render to show updated opacity
-      if (this.renderer && this.wasmTerm) {
-        this.renderer.render(this.wasmTerm, false, this.viewportY, this, this.scrollbarOpacity);
-      }
+      this.draw(false, this.scrollbarOpacity);
 
       if (progress < 1) {
         requestAnimationFrame(animate);
@@ -1913,9 +1959,7 @@ export class Terminal implements ITerminalCore {
       this.scrollbarOpacity = startOpacity * (1 - progress);
 
       // Trigger render to show updated opacity
-      if (this.renderer && this.wasmTerm) {
-        this.renderer.render(this.wasmTerm, false, this.viewportY, this, this.scrollbarOpacity);
-      }
+      this.draw(false, this.scrollbarOpacity);
 
       if (progress < 1) {
         requestAnimationFrame(animate);
@@ -1923,9 +1967,7 @@ export class Terminal implements ITerminalCore {
         this.scrollbarVisible = false;
         this.scrollbarOpacity = 0;
         // Final render to clear scrollbar completely
-        if (this.renderer && this.wasmTerm) {
-          this.renderer.render(this.wasmTerm, false, this.viewportY, this, 0);
-        }
+        this.draw(false, 0);
       }
     };
     animate();
@@ -1973,6 +2015,8 @@ export class Terminal implements ITerminalCore {
     if (!this.wasmTerm) return undefined;
     const y = this.wasmTerm.cursorPosition().y + cursorYOffset;
     if (y < 0 || y >= this.rows) return undefined;
+    // Starts watching the active screen for discarded rows before the marker exists.
+    if (this.wasmTerm.rowsDiscarded()) this.refreshMarkers(true);
     const row = this.wasmTerm.trackRow(y);
     if (!row) return undefined;
     const marker = new Marker(row);
@@ -2065,8 +2109,10 @@ export class Terminal implements ITerminalCore {
     if (alternate !== this.lastAlternate) {
       this.lastAlternate = alternate;
       (this.buffer as BufferNamespace)._fireBufferChange(this.buffer.active);
+      this.refreshMarkers(true);
+    } else {
+      this.refreshMarkers(false);
     }
-    for (const marker of [...this.markers]) marker.refresh();
     this.writeParsedEmitter.fire();
     this.wake();
   }
@@ -2088,6 +2134,13 @@ export class Terminal implements ITerminalCore {
     this.scrollEmitter.fire(this.buffer.active.viewportY);
   }
 
+  /** Disposes the markers whose line is gone; only rows the engine discarded can be. */
+  private refreshMarkers(force: boolean): void {
+    if (this.markers.size === 0 || !this.wasmTerm) return;
+    if (!this.wasmTerm.rowsDiscarded() && !force) return;
+    for (const marker of [...this.markers]) marker.refresh();
+  }
+
   private disposeMarkers(): void {
     for (const marker of [...this.markers]) marker.dispose();
     this.markers.clear();

package/lib/webgl-renderer.ts

@@ -524,7 +524,7 @@ export class WebglRenderer extends TerminalRenderer {
   // Rows
   // ==========================================================================
 
-  protected drawLine(line: GhosttyCell[], y: number, cols: number): void {
+  protected drawLine(line: readonly GhosttyCell[], y: number, cols: number): void {
     if (y < 0 || y >= this.rows) return;
     const cells = this.cols * this.rows;
     const rects = this.rectWords;
@@ -721,7 +721,7 @@ export class WebglRenderer extends TerminalRenderer {
       colors[4] = theme.cursor;
       key = `${left},${top},${this.cursorStyle},${overlay.focused}`;
       if (overlay.focused && this.cursorStyle === 'block') {
-        const cell = this.currentBuffer?.getLine(overlay.cursorY)?.[overlay.cursorX];
+        const cell = this.bufferLine(overlay.cursorY)?.[overlay.cursorX];
         if (cell && !isBlank(cell) && !(cell.flags & CellFlags.INVISIBLE)) {
           const entry = this.glyphFor(cell, overlay.cursorX, overlay.cursorY);
           if (entry) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aurigax-ai/ghostty-web",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "description": "Ghostty's terminal engine (libghostty-vt) in the browser: WebAssembly build, an xterm.js-shaped API and WebGL and canvas renderers. A hard fork of coder/ghostty-web.",
   "type": "module",
   "main": "./lib/index.ts",