@aurigax-ai/ghostty-web 0.3.6 → 0.3.8

package/README.md

@@ -70,6 +70,23 @@ blink) and sleeps otherwise. `setPaused(true)` stops drawing a terminal that is
 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.
 
+## Headless terminal
+
+`HeadlessTerminal` parses bytes with no DOM, canvas or renderer, for a server or worker that keeps a screen and scrollback.
+
+```ts
+import { Ghostty, HeadlessTerminal } from '@aurigax-ai/ghostty-web';
+
+const ghostty = await Ghostty.fromBytes(wasmBytes);
+const term = new HeadlessTerminal({ ghostty, cols: 120, rows: 40, scrollback: 2000 });
+term.parser.registerOscHandler(133, (data) => false);
+term.parser.registerCsiHandler({ final: 'J' }, (params) => {});
+term.write('hello\r\n', () => {});
+term.buffer.normal.getLine(0)?.translateToString(true);
+```
+
+It has `buffer`, `registerMarker`, `onScroll`, `onWriteParsed`, `modes.bracketedPasteMode`, `resize` and `dispose`, with the xterm.js names. OSC handlers get the payload after the number (7, 133 and any other number). CSI handlers only observe a sequence, just before the terminal applies it. `scrollback` frees whole pages, so a screen can hold fewer lines than the limit (about half at 80 columns) and a narrow one more.
+
 ## Use
 
 ```ts

package/lib/buffer.ts

@@ -17,11 +17,36 @@
 
 import { EventEmitter } from './event-emitter';
 import type { GhosttyTerminal } from './ghostty';
-import { CellFlags } from './ghostty';
+import { CellFlags, ColorKind } from './ghostty';
 import type { IBuffer, IBufferCell, IBufferLine, IBufferNamespace, IEvent } from './interfaces';
-import type { Terminal } from './terminal';
 import type { GhosttyCell } from './types';
 
+function nullCellData(): GhosttyCell {
+  return {
+    codepoint: 0,
+    fg_r: 204,
+    fg_g: 204,
+    fg_b: 204,
+    bg_r: 0,
+    bg_g: 0,
+    bg_b: 0,
+    flags: 0,
+    width: 1,
+    hyperlink_id: 0,
+    grapheme_len: 0,
+    fg_kind: ColorKind.DEFAULT,
+    bg_kind: ColorKind.DEFAULT,
+    fg_index: 0,
+    bg_index: 0,
+  };
+}
+
+/** What a buffer reads from its terminal: the wasm engine and how far the viewport is scrolled back. */
+export interface BufferHost {
+  readonly wasmTerm?: GhosttyTerminal;
+  readonly viewportY: number;
+}
+
 // ============================================================================
 // BufferNamespace - Top-level buffer API
 // ============================================================================
@@ -31,20 +56,20 @@ import type { GhosttyCell } from './types';
  * Provides access to active, normal, and alternate screen buffers
  */
 export class BufferNamespace implements IBufferNamespace {
-  private terminal: Terminal;
+  private terminal: BufferHost;
   private bufferChangeEmitter = new EventEmitter<IBuffer>();
 
   // Lazy-initialized buffer wrappers (stateless, so we can cache them)
   private _normalBuffer?: Buffer;
   private _alternateBuffer?: Buffer;
 
-  constructor(terminal: Terminal) {
+  constructor(terminal: BufferHost) {
     this.terminal = terminal;
   }
 
   get active(): IBuffer {
     // Query WASM to determine which buffer is active
-    const wasmTerm = (this.terminal as any).wasmTerm as GhosttyTerminal | undefined;
+    const wasmTerm = this.terminal.wasmTerm;
     if (!wasmTerm) {
       return this.normal; // Default to normal if not initialized
     }
@@ -87,29 +112,16 @@ export class BufferNamespace implements IBufferNamespace {
  * A terminal buffer (normal or alternate screen)
  */
 export class Buffer implements IBuffer {
-  private terminal: Terminal;
+  private terminal: BufferHost;
   private bufferType: 'normal' | 'alternate';
   private nullCell: BufferCell;
 
-  constructor(terminal: Terminal, type: 'normal' | 'alternate') {
+  constructor(terminal: BufferHost, type: 'normal' | 'alternate') {
     this.terminal = terminal;
     this.bufferType = type;
 
     // Create a null cell (codepoint=0, default colors, no flags)
-    const nullCellData: GhosttyCell = {
-      codepoint: 0,
-      fg_r: 204,
-      fg_g: 204,
-      fg_b: 204,
-      bg_r: 0,
-      bg_g: 0,
-      bg_b: 0,
-      flags: 0,
-      width: 1,
-      hyperlink_id: 0,
-      grapheme_len: 0,
-    };
-    this.nullCell = new BufferCell(nullCellData, 0);
+    this.nullCell = new BufferCell(nullCellData(), 0);
   }
 
   get type(): 'normal' | 'alternate' {
@@ -132,7 +144,7 @@ export class Buffer implements IBuffer {
   /** The absolute line at the top of the viewport (baseY when scrolled to the bottom). */
   get viewportY(): number {
     if (this.bufferType === 'alternate') return 0;
-    const scrolledBack = Math.round((this.terminal as any).viewportY ?? 0);
+    const scrolledBack = Math.round(this.terminal.viewportY);
     return Math.max(0, this.baseY - scrolledBack);
   }
 
@@ -172,6 +184,7 @@ export class Buffer implements IBuffer {
     let cells: GhosttyCell[] | null;
     let lineNumber: number;
     let isWrapped: boolean;
+    let graphemes: (x: number) => string;
 
     if (this.bufferType === 'normal' && y < scrollbackLength) {
       // Accessing scrollback
@@ -181,18 +194,20 @@ export class Buffer implements IBuffer {
       const scrollbackOffset = y;
       cells = wasmTerm.getScrollbackLine(scrollbackOffset);
       isWrapped = wasmTerm.isScrollbackRowWrapped(scrollbackOffset);
+      graphemes = (x) => wasmTerm.getScrollbackGraphemeString(scrollbackOffset, x);
     } else {
       // Accessing visible screen
       lineNumber = this.bufferType === 'normal' ? y - scrollbackLength : y;
       cells = wasmTerm.getLine(lineNumber);
       isWrapped = wasmTerm.isRowWrapped(lineNumber);
+      graphemes = (x) => wasmTerm.getGraphemeString(lineNumber, x);
     }
 
     if (!cells) {
       return undefined;
     }
 
-    return new BufferLine(cells, isWrapped, wasmTerm.cols);
+    return new BufferLine(cells, isWrapped, wasmTerm.cols, graphemes);
   }
 
   getNullCell(): IBufferCell {
@@ -200,7 +215,7 @@ export class Buffer implements IBuffer {
   }
 
   private getWasmTerm(): GhosttyTerminal | undefined {
-    return (this.terminal as any).wasmTerm as GhosttyTerminal | undefined;
+    return this.terminal.wasmTerm;
   }
 }
 
@@ -216,7 +231,12 @@ export class BufferLine implements IBufferLine {
   private _isWrapped: boolean;
   private _length: number;
 
-  constructor(cells: GhosttyCell[], isWrapped: boolean, length: number) {
+  constructor(
+    cells: GhosttyCell[],
+    isWrapped: boolean,
+    length: number,
+    private readonly graphemes?: (x: number) => string
+  ) {
     this.cells = cells;
     this._isWrapped = isWrapped;
     this._length = length;
@@ -237,25 +257,11 @@ export class BufferLine implements IBufferLine {
 
     if (x >= this.cells.length) {
       // Cell beyond what was returned (empty/null cell)
-      return new BufferCell(
-        {
-          codepoint: 0,
-          fg_r: 204,
-          fg_g: 204,
-          fg_b: 204,
-          bg_r: 0,
-          bg_g: 0,
-          bg_b: 0,
-          flags: 0,
-          width: 1,
-          hyperlink_id: 0,
-          grapheme_len: 0,
-        },
-        x
-      );
+      return new BufferCell(nullCellData(), x);
     }
 
-    return new BufferCell(this.cells[x], x);
+    const cell = this.cells[x];
+    return new BufferCell(cell, x, cell.grapheme_len > 0 ? this.graphemes?.(x) : undefined);
   }
 
   translateToString(trimRight = false, startColumn = 0, endColumn = this._length): string {
@@ -266,10 +272,7 @@ export class BufferLine implements IBufferLine {
     let result = '';
     for (let x = start; x < end; x++) {
       const cell = this.getCell(x);
-      if (cell) {
-        const chars = cell.getChars();
-        result += chars;
-      }
+      if (cell && cell.getWidth() !== 0) result += cell.getChars() || ' ';
     }
 
     if (trimRight) {
@@ -290,11 +293,16 @@ export class BufferLine implements IBufferLine {
 export class BufferCell implements IBufferCell {
   private cell: GhosttyCell;
 
-  constructor(cell: GhosttyCell, _x: number) {
+  constructor(
+    cell: GhosttyCell,
+    _x: number,
+    private readonly grapheme?: string
+  ) {
     this.cell = cell;
   }
 
   getChars(): string {
+    if (this.grapheme) return this.grapheme;
     const codepoint = this.cell.codepoint;
 
     // Return empty string for null character or invalid codepoints
@@ -320,6 +328,22 @@ export class BufferCell implements IBufferCell {
     return this.cell.width;
   }
 
+  getFgKind(): ColorKind {
+    return this.cell.fg_kind;
+  }
+
+  getBgKind(): ColorKind {
+    return this.cell.bg_kind;
+  }
+
+  getFgPaletteIndex(): number {
+    return this.cell.fg_index;
+  }
+
+  getBgPaletteIndex(): number {
+    return this.cell.bg_index;
+  }
+
   getFgColorMode(): number {
     // Return -1 for RGB (we always use RGB in our WASM implementation)
     // xterm.js uses different values:

package/lib/csi-observer.ts

@@ -0,0 +1,123 @@
+export type CsiParams = (number | number[])[];
+
+export interface CsiIdentifier {
+  prefix?: string;
+  intermediates?: string;
+  final: string;
+}
+
+export type CsiHandler = (params: CsiParams) => void;
+
+type State = 'ground' | 'escape' | 'csi' | 'string' | 'string-escape';
+
+const ESC = 0x1b;
+const BEL = 0x07;
+const CSI_INTRODUCER = 0x5b;
+const STRING_INTRODUCERS = new Set([0x5d, 0x50, 0x5f, 0x5e, 0x58]);
+const MAX_SEQUENCE = 256;
+
+/**
+ * Watches a byte stream for CSI sequences without parsing the terminal state.
+ * It follows the stream across chunks and skips OSC, DCS, APC, PM and SOS
+ * strings, so text inside them never counts as a sequence.
+ */
+export class CsiObserver {
+  private state: State = 'ground';
+  private body = '';
+  private readonly handlers = new Map<string, Set<CsiHandler>>();
+
+  get active(): boolean {
+    return this.handlers.size > 0;
+  }
+
+  register(id: CsiIdentifier, handler: CsiHandler): { dispose(): void } {
+    const key = keyOf(id.prefix ?? '', id.intermediates ?? '', id.final);
+    const set = this.handlers.get(key) ?? new Set<CsiHandler>();
+    set.add(handler);
+    this.handlers.set(key, set);
+    return {
+      dispose: () => {
+        set.delete(handler);
+        if (set.size === 0) this.handlers.delete(key);
+      },
+    };
+  }
+
+  /**
+   * Advances over the byte at `index`. When it ends a sequence with handlers,
+   * `before(index)` runs first, so the caller can hand the terminal everything
+   * before that byte, and the handlers then see the state the sequence found.
+   */
+  step(byte: number, index: number, before: (index: number) => void): void {
+    switch (this.state) {
+      case 'ground':
+        if (byte === ESC) this.state = 'escape';
+        return;
+      case 'escape':
+        if (byte === CSI_INTRODUCER) {
+          this.state = 'csi';
+          this.body = '';
+        } else if (STRING_INTRODUCERS.has(byte)) {
+          this.state = 'string';
+        } else {
+          this.state = byte === ESC ? 'escape' : 'ground';
+        }
+        return;
+      case 'string':
+        if (byte === BEL) this.state = 'ground';
+        else if (byte === ESC) this.state = 'string-escape';
+        return;
+      case 'string-escape':
+        this.state = byte === 0x5c ? 'ground' : byte === ESC ? 'string-escape' : 'string';
+        return;
+      case 'csi':
+        this.csiByte(byte, index, before);
+    }
+  }
+
+  private csiByte(byte: number, index: number, before: (index: number) => void): void {
+    if (byte >= 0x40 && byte <= 0x7e) {
+      this.state = 'ground';
+      this.dispatch(this.body, String.fromCharCode(byte), index, before);
+      return;
+    }
+    if (byte === ESC) {
+      this.state = 'escape';
+      return;
+    }
+    if (byte < 0x20 || byte > 0x3f) {
+      if (byte >= 0x20 && byte <= 0x2f) this.body += String.fromCharCode(byte);
+      else if (byte === 0x18 || byte === 0x1a) this.state = 'ground';
+      return;
+    }
+    this.body += String.fromCharCode(byte);
+    if (this.body.length > MAX_SEQUENCE) this.state = 'ground';
+  }
+
+  private dispatch(
+    body: string,
+    final: string,
+    index: number,
+    before: (index: number) => void
+  ): void {
+    const match = /^([<=>?]?)([0-9;:]*)([ -/]*)$/.exec(body);
+    if (!match) return;
+    const handlers = this.handlers.get(keyOf(match[1], match[3], final));
+    if (!handlers) return;
+    before(index);
+    const params = parseParams(match[2]);
+    for (const handler of [...handlers]) handler(params);
+  }
+}
+
+function keyOf(prefix: string, intermediates: string, final: string): string {
+  return `${prefix}|${intermediates}|${final}`;
+}
+
+function parseParams(text: string): CsiParams {
+  if (text === '') return [];
+  return text.split(';').map((part) => {
+    if (!part.includes(':')) return part === '' ? 0 : Number(part);
+    return part.split(':').map((sub) => (sub === '' ? 0 : Number(sub)));
+  });
+}

package/lib/ghostty.ts

@@ -18,6 +18,7 @@ import { EventEmitter } from './event-emitter';
 import type { IEvent } from './interfaces';
 import {
   CellFlags,
+  ColorKind,
   type Cursor,
   DirtyState,
   type GhosttyCell,
@@ -33,6 +34,7 @@ import {
 // Re-export types for convenience
 export {
   CellFlags,
+  ColorKind,
   type Cursor,
   DirtyState,
   type GhosttyCell,
@@ -1402,9 +1404,27 @@ export class GhosttyTerminal {
     let fg = this.colors.foreground;
     let bg = this.colors.background;
     let flags = 0;
+    let fgKind = ColorKind.DEFAULT;
+    let bgKind = ColorKind.DEFAULT;
+    let fgIndex = 0;
+    let bgIndex = 0;
     if (styleId !== 0) {
       fg = this.styleColor(view, stylePtr + L.fgColor) ?? fg;
       bg = this.styleColor(view, stylePtr + L.bgColor) ?? bg;
+      const fgTag = view.getInt32(stylePtr + L.fgColor + L.colorTag, true);
+      const bgTag = view.getInt32(stylePtr + L.bgColor + L.colorTag, true);
+      if (fgTag === L.colorPalette) {
+        fgKind = ColorKind.PALETTE;
+        fgIndex = view.getUint8(stylePtr + L.fgColor + L.colorValue);
+      } else if (fgTag === L.colorRgb) {
+        fgKind = ColorKind.RGB;
+      }
+      if (bgTag === L.colorPalette) {
+        bgKind = ColorKind.PALETTE;
+        bgIndex = view.getUint8(stylePtr + L.bgColor + L.colorValue);
+      } else if (bgTag === L.colorRgb) {
+        bgKind = ColorKind.RGB;
+      }
       if (view.getUint8(stylePtr + L.bold)) flags |= CellFlags.BOLD;
       if (view.getUint8(stylePtr + L.italic)) flags |= CellFlags.ITALIC;
       if (view.getInt32(stylePtr + L.underline, true) !== 0) flags |= CellFlags.UNDERLINE;
@@ -1416,9 +1436,16 @@ export class GhosttyTerminal {
     }
     if (tag === L.tagBgPalette) {
       bg = this.colors.palette[contentBits & 0xff] ?? bg;
+      bgKind = ColorKind.PALETTE;
+      bgIndex = contentBits & 0xff;
     } else if (tag === L.tagBgRgb) {
       bg = { r: contentBits & 0xff, g: (contentBits >> 8) & 0xff, b: (contentBits >> 16) & 0xff };
+      bgKind = ColorKind.RGB;
     }
+    cell.fg_kind = fgKind;
+    cell.bg_kind = bgKind;
+    cell.fg_index = fgIndex;
+    cell.bg_index = bgIndex;
     cell.fg_r = fg.r;
     cell.fg_g = fg.g;
     cell.fg_b = fg.b;
@@ -1515,6 +1542,10 @@ export class GhosttyTerminal {
       width: 1,
       hyperlink_id: 0,
       grapheme_len: 0,
+      fg_kind: ColorKind.DEFAULT,
+      bg_kind: ColorKind.DEFAULT,
+      fg_index: 0,
+      bg_index: 0,
     };
   }
 

package/lib/headless.ts

@@ -0,0 +1,215 @@
+import { BufferNamespace } from './buffer';
+import { type CsiHandler, type CsiIdentifier, CsiObserver } from './csi-observer';
+import { EventEmitter } from './event-emitter';
+import type { Ghostty, GhosttyTerminal, MouseTrackingMode, SemanticPromptEvent } from './ghostty';
+import type { IBufferNamespace, IDisposable, IEvent } from './interfaces';
+import { type IMarker, Marker } from './marker';
+
+export interface HeadlessTerminalOptions {
+  ghostty: Ghostty;
+  cols?: number;
+  rows?: number;
+  /**
+   * Lines kept above the screen. Ghostty frees whole pages, never single rows,
+   * so at 80 columns it can hold about half of this, and a
+   * narrow screen, whose page holds more rows, can hold more than this.
+   */
+  scrollback?: number;
+}
+
+export type OscHandler = (data: string) => boolean | Promise<boolean>;
+
+export interface HeadlessParser {
+  /** Runs `handler` with the OSC payload after its number; its result is ignored. */
+  registerOscHandler(ident: number, handler: OscHandler): IDisposable;
+  /** Observes a CSI sequence just before the terminal applies it; its result is ignored. */
+  registerCsiHandler(id: CsiIdentifier, handler: CsiHandler): IDisposable;
+}
+
+const PROMPT_MARKS: Record<SemanticPromptEvent['kind'], string> = {
+  'prompt-start': 'A',
+  'input-start': 'B',
+  'output-start': 'C',
+  'command-end': 'D',
+};
+
+const LINE_FEED = 0x0a;
+const LINES_PER_SLICE = 128;
+
+function unknownOsc(content: string): { ident: number; data: string } | null {
+  const sep = content.indexOf(';');
+  const ident = Number(sep === -1 ? content : content.slice(0, sep));
+  if (!Number.isInteger(ident) || ident < 0) return null;
+  return { ident, data: sep === -1 ? '' : content.slice(sep + 1) };
+}
+
+/**
+ * A terminal with no DOM, canvas or renderer: it parses bytes and keeps the
+ * screen, scrollback, markers and OSC/CSI hooks, with the xterm.js names that
+ * `Terminal` uses. Writes are synchronous; the write callback runs in a
+ * microtask. Replies the terminal would send to the program are dropped.
+ */
+export class HeadlessTerminal implements IDisposable {
+  readonly buffer: IBufferNamespace;
+  readonly parser: HeadlessParser;
+  readonly onScroll: IEvent<number>;
+  readonly onWriteParsed: IEvent<void>;
+  readonly onTitleChange: IEvent<string>;
+
+  cols: number;
+  rows: number;
+  wasmTerm: GhosttyTerminal | undefined;
+  readonly viewportY = 0;
+
+  private readonly scrollEmitter = new EventEmitter<number>();
+  private readonly writeParsedEmitter = new EventEmitter<void>();
+  private readonly titleEmitter = new EventEmitter<string>();
+  private readonly oscRoutes = new Map<number, Set<OscHandler>>();
+  private readonly csi = new CsiObserver();
+  private readonly markers = new Set<Marker>();
+  private readonly subscriptions: IDisposable[];
+  private readonly encoder = new TextEncoder();
+  private lastAlternate = false;
+  private lastBase = 0;
+  private disposed = false;
+
+  constructor(options: HeadlessTerminalOptions) {
+    this.cols = options.cols ?? 80;
+    this.rows = options.rows ?? 24;
+    const engine = options.ghostty.createTerminal(this.cols, this.rows, {
+      scrollbackLimit: options.scrollback ?? 10000,
+    });
+    this.wasmTerm = engine;
+    this.buffer = new BufferNamespace(this);
+    this.onScroll = this.scrollEmitter.event;
+    this.onWriteParsed = this.writeParsedEmitter.event;
+    this.onTitleChange = this.titleEmitter.event;
+    this.parser = {
+      registerOscHandler: (ident, handler) => this.addOsc(ident, handler),
+      registerCsiHandler: (id, handler) => this.csi.register(id, handler),
+    };
+    this.subscriptions = [
+      engine.onSemanticPrompt((event) => {
+        const mark = PROMPT_MARKS[event.kind];
+        const data =
+          event.kind === 'command-end' && event.exitCode !== undefined
+            ? `${mark};${event.exitCode}`
+            : mark;
+        this.fireOsc(133, data);
+      }),
+      engine.onPwdChange((pwd) => this.fireOsc(7, pwd)),
+      engine.onTitleChange((title) => this.titleEmitter.fire(title)),
+      engine.onUnknownOsc((content) => {
+        const parsed = unknownOsc(content);
+        if (parsed) this.fireOsc(parsed.ident, parsed.data);
+      }),
+    ];
+    this.lastAlternate = engine.isAlternateScreen();
+  }
+
+  get modes(): { bracketedPasteMode: boolean; mouseTrackingMode: MouseTrackingMode } {
+    return {
+      bracketedPasteMode: this.wasmTerm?.hasBracketedPaste() ?? false,
+      mouseTrackingMode: this.wasmTerm?.mouseTrackingMode() ?? 'none',
+    };
+  }
+
+  write(data: string | Uint8Array, callback?: () => void): void {
+    const engine = this.wasmTerm;
+    if (!engine || this.disposed) {
+      if (callback) queueMicrotask(callback);
+      return;
+    }
+    const bytes = typeof data === 'string' ? this.encoder.encode(data) : data;
+    let written = 0;
+    let lines = 0;
+    const flushTo = (end: number): void => {
+      if (end <= written) return;
+      engine.write(bytes.subarray(written, end));
+      written = end;
+      this.afterChunk();
+    };
+    const watching = this.csi.active;
+    for (let i = 0; i < bytes.length; i++) {
+      const byte = bytes[i];
+      if (watching) this.csi.step(byte, i, flushTo);
+      if (byte === LINE_FEED && ++lines % LINES_PER_SLICE === 0) flushTo(i + 1);
+      if (this.disposed) return;
+    }
+    flushTo(bytes.length);
+    this.writeParsedEmitter.fire();
+    if (callback) queueMicrotask(callback);
+  }
+
+  resize(cols: number, rows: number): void {
+    const engine = this.wasmTerm;
+    if (!engine || (cols === this.cols && rows === this.rows)) return;
+    this.cols = cols;
+    this.rows = rows;
+    engine.resize(cols, rows);
+    this.refreshMarkers(engine.rowsDiscarded());
+  }
+
+  registerMarker(cursorYOffset = 0): IMarker | undefined {
+    const engine = this.wasmTerm;
+    if (!engine) return undefined;
+    const y = engine.cursorPosition().y + cursorYOffset;
+    if (y < 0 || y >= this.rows) return undefined;
+    if (engine.rowsDiscarded()) this.refreshMarkers(true);
+    const row = engine.trackRow(y);
+    if (!row) return undefined;
+    const marker = new Marker(row);
+    this.markers.add(marker);
+    marker.onDispose(() => this.markers.delete(marker));
+    return marker;
+  }
+
+  dispose(): void {
+    if (this.disposed) return;
+    this.disposed = true;
+    for (const sub of this.subscriptions) sub.dispose();
+    for (const marker of [...this.markers]) marker.dispose();
+    this.markers.clear();
+    this.oscRoutes.clear();
+    this.scrollEmitter.dispose();
+    this.writeParsedEmitter.dispose();
+    this.titleEmitter.dispose();
+    this.wasmTerm?.free();
+    this.wasmTerm = undefined;
+  }
+
+  private addOsc(ident: number, handler: OscHandler): IDisposable {
+    const set = this.oscRoutes.get(ident) ?? new Set<OscHandler>();
+    set.add(handler);
+    this.oscRoutes.set(ident, set);
+    return { dispose: () => set.delete(handler) };
+  }
+
+  private fireOsc(ident: number, data: string): void {
+    for (const handler of [...(this.oscRoutes.get(ident) ?? [])]) void handler(data);
+  }
+
+  private afterChunk(): void {
+    const engine = this.wasmTerm;
+    if (!engine) return;
+    while (engine.hasResponse()) engine.readResponse();
+    const alternate = engine.isAlternateScreen();
+    const switched = alternate !== this.lastAlternate;
+    this.lastAlternate = alternate;
+    if (switched) {
+      (this.buffer as BufferNamespace)._fireBufferChange(this.buffer.active);
+    }
+    const discarded = engine.rowsDiscarded();
+    this.refreshMarkers(switched || discarded);
+    const base = engine.getScrollbackLength();
+    if (!alternate && (base !== this.lastBase || discarded)) {
+      this.lastBase = base;
+      this.scrollEmitter.fire(base);
+    }
+  }
+
+  private refreshMarkers(needed: boolean): void {
+    if (!needed) return;
+    for (const marker of [...this.markers]) marker.refresh();
+  }
+}

package/lib/index.ts

@@ -56,6 +56,9 @@ export function getGhostty(): Ghostty {
 
 // Main Terminal class
 export { Terminal } from './terminal';
+export { HeadlessTerminal } from './headless';
+export type { HeadlessParser, HeadlessTerminalOptions, OscHandler } from './headless';
+export type { CsiHandler, CsiIdentifier, CsiParams } from './csi-observer';
 
 // xterm.js-compatible interfaces
 export type {
@@ -65,6 +68,10 @@ export type {
   ITerminalCore,
   IDisposable,
   IEvent,
+  IBuffer,
+  IBufferCell,
+  IBufferLine,
+  IBufferNamespace,
   IBufferRange,
   IKeyEvent,
   IUnicodeVersionProvider,
@@ -88,7 +95,7 @@ export type {
 } from './ghostty';
 export type { IMarker } from './marker';
 export { Abi, GhosttyCallError } from './abi';
-export { Key, KeyAction, Mods } from './types';
+export { ColorKind, Key, KeyAction, Mods } from './types';
 export type { KeyEvent, GhosttyCell, RGB, Cursor, TerminalHandle } from './types';
 
 // Low-level components (for custom integrations)

package/lib/interfaces.ts

@@ -3,6 +3,7 @@
  */
 
 import type { Ghostty } from './ghostty';
+import type { ColorKind } from './types';
 
 export interface ITerminalOptions {
   cols?: number; // Default: 80
@@ -222,6 +223,15 @@ export interface IBufferCell {
   /** Background RGB color (or 0 for default) */
   getBgColor(): number;
 
+  /** How the foreground was set: default, a palette entry or RGB */
+  getFgKind(): ColorKind;
+  /** How the background was set: default, a palette entry or RGB */
+  getBgKind(): ColorKind;
+  /** The foreground palette entry, when getFgKind() is PALETTE */
+  getFgPaletteIndex(): number;
+  /** The background palette entry, when getBgKind() is PALETTE */
+  getBgPaletteIndex(): number;
+
   /** Whether cell has bold style */
   isBold(): number;
   /** Whether cell has italic style */

package/lib/renderer.ts

@@ -268,8 +268,6 @@ export abstract class TerminalRenderer {
   private readonly highlightRows = new Set<number>();
   protected highlightColors: SearchHighlightColors = { match: '#5c6266', active: '#538bb5' };
 
-  protected hoveredHyperlinkId = 0;
-  private previousHoveredHyperlinkId = 0;
   protected hoveredLinkRange: LinkRange | null = null;
   private previousHoveredLinkRange: LinkRange | null = null;
 
@@ -385,22 +383,6 @@ export abstract class TerminalRenderer {
     };
 
     const hyperlinkRows = new Set<number>();
-    if (this.hoveredHyperlinkId !== this.previousHoveredHyperlinkId) {
-      for (let y = 0; y < dims.rows; y++) {
-        const line = lineAt(y);
-        if (!line) continue;
-        for (const cell of line) {
-          if (
-            cell.hyperlink_id === this.hoveredHyperlinkId ||
-            cell.hyperlink_id === this.previousHoveredHyperlinkId
-          ) {
-            hyperlinkRows.add(y);
-            break;
-          }
-        }
-      }
-      this.previousHoveredHyperlinkId = this.hoveredHyperlinkId;
-    }
     if (!sameRange(this.hoveredLinkRange, this.previousHoveredLinkRange)) {
       for (const range of [this.previousHoveredLinkRange, this.hoveredLinkRange]) {
         if (!range) continue;
@@ -511,9 +493,8 @@ export abstract class TerminalRenderer {
   /** Called when the search highlight colors change. */
   protected searchColorsChanged(): void {}
 
-  /** Whether the cell has a hovered link under it (OSC 8 id or a detected URL range). */
-  protected linkHovered(cell: GhosttyCell, x: number, y: number): boolean {
-    if (cell.hyperlink_id > 0 && cell.hyperlink_id === this.hoveredHyperlinkId) return true;
+  /** Whether the cell has a hovered link under it (OSC 8 or detected URL range). */
+  protected linkHovered(x: number, y: number): boolean {
     const range = this.hoveredLinkRange;
     if (!range) return false;
     return (
@@ -676,14 +657,6 @@ export abstract class TerminalRenderer {
     this.selectionManager = manager;
   }
 
-  public setHoveredHyperlinkId(hyperlinkId: number): void {
-    this.hoveredHyperlinkId = hyperlinkId;
-  }
-
-  public getHoveredHyperlinkId(): number {
-    return this.hoveredHyperlinkId;
-  }
-
   /** Set the hovered range of a detected URL, or null to clear it. */
   public setHoveredLinkRange(range: LinkRange | null): void {
     this.hoveredLinkRange = range;
@@ -1006,7 +979,7 @@ export class CanvasRenderer extends TerminalRenderer {
   private renderDecorations(cell: GhosttyCell, x: number, y: number, color: string): void {
     const underline = cell.flags & CellFlags.UNDERLINE;
     const strike = cell.flags & CellFlags.STRIKETHROUGH;
-    const link = (cell.hyperlink_id > 0 || this.hoveredLinkRange) && this.linkHovered(cell, x, y);
+    const link = this.hoveredLinkRange && this.linkHovered(x, y);
     if (!underline && !strike && !link) return;
     const cellX = x * this.metrics.width;
     const cellY = y * this.metrics.height;

package/lib/terminal.ts

@@ -660,10 +660,8 @@ export class Terminal implements ITerminalCore {
   /** 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);
     renderer.setSearchHighlights(this.searchHighlights.list, this.searchHighlights.colors);
     if (this.selectionManager) {
@@ -1545,47 +1543,7 @@ export class Terminal implements ITerminalCore {
     const x = Math.floor((e.clientX - rect.left) / this.renderer.charWidth);
     const y = Math.floor((e.clientY - rect.top) / this.renderer.charHeight);
 
-    // Get hyperlink_id directly from the cell at this position
-    // Must account for viewportY (scrollback position)
-    const viewportRow = y; // Row in the viewport (0 to rows-1)
-    let hyperlinkId = 0;
-
-    // When scrolled, fetch from scrollback or screen based on position
-    // NOTE: viewportY may be fractional during smooth scrolling. The renderer
-    // uses Math.floor(viewportY) when mapping viewport rows to scrollback vs
-    // screen; we mirror that logic here so link hit-testing matches what the
-    // user sees on screen.
-    let line: GhosttyCell[] | null = null;
-    const rawViewportY = this.getViewportY();
-    const viewportY = Math.max(0, Math.floor(rawViewportY));
-    if (viewportY > 0) {
-      const scrollbackLength = this.wasmTerm.getScrollbackLength();
-      if (viewportRow < viewportY) {
-        // Mouse is over scrollback content
-        const scrollbackOffset = scrollbackLength - viewportY + viewportRow;
-        line = this.wasmTerm.getScrollbackLine(scrollbackOffset);
-      } else {
-        // Mouse is over screen content (bottom part of viewport)
-        const screenRow = viewportRow - viewportY;
-        line = this.wasmTerm.getLine(screenRow);
-      }
-    } else {
-      // At bottom - just use screen buffer
-      line = this.wasmTerm.getLine(viewportRow);
-    }
-
-    if (line && x >= 0 && x < line.length) {
-      hyperlinkId = line[x].hyperlink_id;
-    }
-
-    // Update renderer for underline rendering
-    const previousHyperlinkId = (this.renderer as any).hoveredHyperlinkId || 0;
-    if (hyperlinkId !== previousHyperlinkId) {
-      this.renderer.setHoveredHyperlinkId(hyperlinkId);
-
-      // The 60fps render loop will pick up the change automatically
-      // No need to force a render - this keeps performance smooth
-    }
+    const viewportRow = y;
 
     // Check if there's a link at this position (for click handling and cursor)
     // Buffer API expects absolute buffer coordinates (including scrollback)
@@ -1678,12 +1636,6 @@ export class Terminal implements ITerminalCore {
     this.wake();
     // Clear hyperlink underline
     if (this.renderer && this.wasmTerm) {
-      const previousHyperlinkId = (this.renderer as any).hoveredHyperlinkId || 0;
-      if (previousHyperlinkId > 0) {
-        this.renderer.setHoveredHyperlinkId(0);
-
-        // The 60fps render loop will pick up the change automatically
-      }
       // Clear regex link underline
       this.renderer.setHoveredLinkRange(null);
     }

package/lib/types.ts

@@ -418,6 +418,16 @@ export interface GhosttyCell {
   width: number; // u8 (character width: 1=normal, 2=wide, etc.)
   hyperlink_id: number; // u16 (0 = no link, >0 = hyperlink ID in set)
   grapheme_len: number; // u8 (number of extra codepoints beyond first)
+  fg_kind: ColorKind; // how the foreground was set: default, a palette entry or RGB
+  bg_kind: ColorKind;
+  fg_index: number; // palette entry when fg_kind is PALETTE
+  bg_index: number;
+}
+
+export enum ColorKind {
+  DEFAULT = 0,
+  PALETTE = 1,
+  RGB = 2,
 }
 
 /**

package/lib/webgl-renderer.ts

@@ -610,7 +610,7 @@ export class WebglRenderer extends TerminalRenderer {
         }
       }
 
-      const link = (cell.hyperlink_id > 0 || this.hoveredLinkRange) && this.linkHovered(cell, x, y);
+      const link = this.hoveredLinkRange && this.linkHovered(x, y);
       if (link || cell.flags & CellFlags.UNDERLINE) {
         rects[deco1] = left;
         rects[deco1 + 1] = underlineY;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aurigax-ai/ghostty-web",
-  "version": "0.3.6",
+  "version": "0.3.8",
   "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",