@aurigax-ai/ghostty-web 0.3.7 → 0.3.9

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,
@@ -230,8 +232,8 @@ 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;
+type PointSpace = typeof POINT_ACTIVE | typeof POINT_HISTORY | typeof POINT_SCREEN;
+type PointTag = PointSpace;
 
 const GRAPHEME_CAP = 16;
 const GRAPHEME_CLUSTER_MODE = 2027;
@@ -1035,6 +1037,61 @@ export class GhosttyTerminal {
     return out;
   }
 
+  /**
+   * The rows `from` to `to` (0 is the oldest scrollback row) of the screen that
+   * is showing, as text with its colours and styles as escape sequences. A
+   * wrapped line comes back as one line, lines end in CR LF, and empty rows at
+   * the end are dropped. One call into the engine, whatever the number of rows.
+   */
+  formatRows(from: number, to: number): string {
+    const abi = this.abi;
+    const optionsSize = abi.sizeOf('GhosttyFormatterTerminalOptions');
+    const selectionSize = abi.sizeOf('GhosttySelection');
+    const refSize = abi.sizeOf('GhosttyGridRef');
+    const lastCol = this._cols - 1;
+    return abi.with(optionsSize + selectionSize, (base) => {
+      const options = base;
+      const selection = base + optionsSize;
+      const O = (field: string) => options + abi.offset('GhosttyFormatterTerminalOptions', field);
+      const S = (field: string) => selection + abi.offset('GhosttySelection', field);
+      abi.view().setUint32(selection, selectionSize, true);
+      const place = (field: string, x: number, y: number) =>
+        this.gridRef(POINT_SCREEN, x, y, (ref) => {
+          abi.bytes().copyWithin(S(field), ref, ref + refSize);
+          return true;
+        });
+      if (!place('start', 0, from) || !place('end', lastCol, to)) return '';
+      const view = abi.view();
+      view.setUint32(O('size'), optionsSize, true);
+      view.setInt32(O('emit'), abi.enumValue('GhosttyFormatterFormat', 'VT'), true);
+      view.setUint8(O('unwrap'), 1);
+      view.setUint8(O('trim'), 1);
+      view.setUint32(O('extra'), abi.sizeOf('GhosttyFormatterTerminalExtra'), true);
+      view.setUint32(O('selection'), selection, true);
+      const slot = abi.call('ghostty_wasm_alloc_opaque');
+      try {
+        abi.check('ghostty_formatter_terminal_new', 0, slot, this.handle, options);
+        const formatter = abi.call('ghostty_wasm_take_opaque', slot);
+        try {
+          const written = abi.scratch(4);
+          const probe = abi.call('ghostty_formatter_format_buf', formatter, 0, 0, written);
+          if (probe === GHOSTTY_SUCCESS) return '';
+          if (probe !== GHOSTTY_OUT_OF_SPACE)
+            throw new GhosttyCallError('ghostty_formatter_format_buf', probe);
+          const need = abi.view().getUint32(written, true);
+          return abi.with(need, (buf) => {
+            abi.check('ghostty_formatter_format_buf', formatter, buf, need, written);
+            return abi.string(buf, abi.view().getUint32(written, true));
+          });
+        } finally {
+          abi.call('ghostty_formatter_free', formatter);
+        }
+      } finally {
+        abi.call('ghostty_wasm_free_opaque', slot);
+      }
+    });
+  }
+
   getGrapheme(row: number, col: number): number[] | null {
     return this.gridRef(POINT_ACTIVE, col, row, (ref) => this.graphemesAt(ref)) ?? null;
   }
@@ -1402,9 +1459,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 +1491,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 +1597,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,244 @@
+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());
+  }
+
+  /**
+   * The logical lines of the rows `from` to `to` (0 is the oldest scrollback
+   * row) of the screen that is showing, each with its colours and styles as
+   * escape sequences. A wrapped line is one line, so the count is the number
+   * of rows that do not continue the row before them, empty rows at the end
+   * included. Costs one call into the engine, not one per row or cell.
+   */
+  serialize(range: { from: number; to: number }): string[] {
+    const engine = this.wasmTerm;
+    if (!engine || range.to < range.from) return [];
+    const text = engine.formatRows(range.from, range.to);
+    const printed = text === '' ? [] : text.split('\r\n');
+    const scrollback = engine.isAlternateScreen() ? 0 : engine.getScrollbackLength();
+    const wrapped = (y: number): boolean =>
+      y < scrollback ? engine.isScrollbackRowWrapped(y) : engine.isRowWrapped(y - scrollback);
+    const starts = [range.from];
+    for (let y = range.from + 1; y <= range.to; y++) if (!wrapped(y)) starts.push(y);
+    const lines: string[] = [];
+    let at = 0;
+    for (const [i, start] of starts.entries()) {
+      const rows = (starts[i + 1] ?? range.to + 1) - start;
+      let blank = 0;
+      while (blank < rows - 1 && engine.formatRows(start + blank, start + blank) === '') blank++;
+      at += blank;
+      lines.push(' '.repeat(blank * this.cols) + (printed[at++] ?? ''));
+    }
+    return lines;
+  }
+
+  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/input-handler.ts

@@ -850,6 +850,7 @@ export class InputHandler {
   private handleMouseDown(event: MouseEvent): void {
     if (this.isDisposed) return;
     if (!this.mouseConfig?.hasMouseTracking()) return;
+    if (event.shiftKey) return;
 
     const cell = this.pixelToCell(event);
     if (!cell) return;
@@ -875,6 +876,7 @@ export class InputHandler {
   private handleMouseUp(event: MouseEvent): void {
     if (this.isDisposed) return;
     if (!this.mouseConfig?.hasMouseTracking()) return;
+    if (event.shiftKey) return;
 
     const cell = this.pixelToCell(event);
     if (!cell) return;
@@ -895,6 +897,7 @@ export class InputHandler {
   private handleMouseMove(event: MouseEvent): void {
     if (this.isDisposed) return;
     if (!this.mouseConfig?.hasMouseTracking()) return;
+    if (event.shiftKey) return;
 
     // Check if button motion mode or any-event tracking is enabled
     // Mode 1002 = button motion, Mode 1003 = any motion

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/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/package.json

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