@aurigax-ai/ghostty-web 0.2.0 → 0.3.0

package/README.md

@@ -16,7 +16,8 @@ kept with its history. It does not track upstream. What changed:
   its host (OSC 7), notifications, clipboard writes and unknown sequences, and keep markers as
   tracked grid references.
 - **WebGL renderer.** `renderer: 'webgl'` (the default) draws with WebGL 2 from a glyph atlas,
-  rewriting only the rows that changed; without WebGL 2, or when its context is lost, the terminal
+  rewriting only the rows that changed and drawing only the cells and glyph pixels that show
+  something; without WebGL 2, or when its context is lost, the terminal
   draws with the canvas renderer instead (`renderer: 'canvas'` asks for it). Both draw box drawing
   and block elements from geometry, so they fill their cells.
 - **pnpm and Vitest** instead of Bun; no demo server, benchmark or release automation.

package/lib/addons/search.ts

@@ -0,0 +1,190 @@
+/**
+ * SearchAddon: find in the terminal's screen and scrollback, shaped like
+ * xterm.js's @xterm/addon-search (findNext, findPrevious, clearDecorations,
+ * onDidChangeResults). Matching is libghostty-vt's: case-insensitive for ASCII
+ * letters. "Next" moves toward older output, as in Ghostty, and the result
+ * index counts from the newest match.
+ */
+
+import { EventEmitter } from '../event-emitter';
+import type { SearchMatch, TerminalSearch } from '../ghostty';
+import type { IDisposable, IEvent, ITerminalAddon } from '../interfaces';
+import type { SearchHighlight } from '../renderer';
+import type { Terminal } from '../terminal';
+
+export interface ISearchDecorationOptions {
+  matchBackground?: string;
+  activeMatchBackground?: string;
+}
+
+export interface ISearchOptions {
+  /** Typing into the query: keep searching from the newest match. */
+  incremental?: boolean;
+  decorations?: ISearchDecorationOptions;
+}
+
+export interface ISearchResultChangeEvent {
+  /** Index of the selected match, newest first, or -1 when none is selected. */
+  resultIndex: number;
+  resultCount: number;
+}
+
+const DEFAULT_MATCH = '#5c6266';
+const DEFAULT_ACTIVE = '#538bb5';
+/** Matches beyond this many (newest first) are counted but not highlighted. */
+const HIGHLIGHT_LIMIT = 20_000;
+
+export class SearchAddon implements ITerminalAddon {
+  private terminal?: Terminal;
+  private search: TerminalSearch | null = null;
+  private searchedEngine: unknown = null;
+  private needle = '';
+  private decorations: ISearchDecorationOptions = {};
+  private frame: number | null = null;
+  private subscriptions: IDisposable[] = [];
+  private readonly resultsEmitter = new EventEmitter<ISearchResultChangeEvent>();
+
+  readonly onDidChangeResults: IEvent<ISearchResultChangeEvent> = this.resultsEmitter.event;
+
+  activate(terminal: Terminal): void {
+    this.terminal = terminal;
+    this.subscriptions = [
+      terminal.onWriteParsed(() => this.scheduleRefresh()),
+      terminal.onResize(() => this.scheduleRefresh()),
+      terminal.onScroll(() => this.paint()),
+    ];
+  }
+
+  findNext(term: string, options?: ISearchOptions): boolean {
+    return this.find(term, options, true);
+  }
+
+  findPrevious(term: string, options?: ISearchOptions): boolean {
+    return this.find(term, options, false);
+  }
+
+  /** Stops searching and removes every highlight. */
+  clearDecorations(): void {
+    this.cancelRefresh();
+    this.needle = '';
+    this.search?.setNeedle('');
+    this.terminal?.setSearchHighlights(null);
+  }
+
+  private engineSearch(): TerminalSearch | null {
+    const engine = this.terminal?.wasmTerm;
+    if (!engine) return null;
+    if (this.search && this.searchedEngine === engine) return this.search;
+    this.search?.free();
+    this.search = engine.createSearch();
+    this.searchedEngine = engine;
+    this.needle = '';
+    return this.search;
+  }
+
+  private find(term: string, options: ISearchOptions | undefined, older: boolean): boolean {
+    const search = this.engineSearch();
+    if (!search) return false;
+    if (options?.decorations) this.decorations = options.decorations;
+    if (!term) {
+      this.clearDecorations();
+      this.emitResults();
+      return false;
+    }
+    const changed = term !== this.needle;
+    if (changed) {
+      this.needle = term;
+      search.setNeedle(term);
+    }
+    search.run();
+    const found = search.select(changed ? true : older);
+    if (found) this.reveal(search.selected());
+    this.paint();
+    this.emitResults();
+    return found;
+  }
+
+  /** Scrolls so the match is in view, centered, unless it already is. */
+  private reveal(match: SearchMatch | null): void {
+    const terminal = this.terminal;
+    if (!terminal || !match) return;
+    const scrollback = terminal.getScrollbackLength();
+    const top = scrollback - Math.floor(terminal.getViewportY());
+    if (match.startY >= top && match.endY < top + terminal.rows) return;
+    terminal.scrollToLine(match.startY - Math.floor(terminal.rows / 2));
+  }
+
+  private scheduleRefresh(): void {
+    if (!this.needle || this.frame !== null) return;
+    this.frame = requestAnimationFrame(() => {
+      this.frame = null;
+      if (!this.needle || !this.search) return;
+      this.search.run();
+      this.paint();
+      this.emitResults();
+    });
+  }
+
+  private cancelRefresh(): void {
+    if (this.frame !== null) cancelAnimationFrame(this.frame);
+    this.frame = null;
+  }
+
+  /** Highlights the matches on the rows now in view. */
+  private paint(): void {
+    const terminal = this.terminal;
+    const search = this.search;
+    if (!terminal || !search || !this.needle) return;
+    const cols = terminal.cols;
+    const rows = terminal.rows;
+    const top = terminal.getScrollbackLength() - Math.floor(terminal.getViewportY());
+    const selected = search.selected();
+    const highlights: SearchHighlight[] = [];
+    const matches = search.matches();
+    for (let i = 0; i < matches.length && i < HIGHLIGHT_LIMIT; i++) {
+      const match = matches[i];
+      if (match.endY < top || match.startY >= top + rows) continue;
+      const active =
+        selected !== null &&
+        selected.startX === match.startX &&
+        selected.startY === match.startY &&
+        selected.endX === match.endX &&
+        selected.endY === match.endY;
+      for (let y = Math.max(match.startY, top); y <= Math.min(match.endY, top + rows - 1); y++) {
+        highlights.push({
+          row: y - top,
+          start: y === match.startY ? match.startX : 0,
+          end: y === match.endY ? match.endX : cols - 1,
+          active,
+        });
+      }
+    }
+    terminal.setSearchHighlights(highlights, {
+      match: this.decorations.matchBackground ?? DEFAULT_MATCH,
+      active: this.decorations.activeMatchBackground ?? DEFAULT_ACTIVE,
+    });
+  }
+
+  private emitResults(): void {
+    const search = this.search;
+    if (!search || !this.needle) {
+      this.resultsEmitter.fire({ resultIndex: -1, resultCount: 0 });
+      return;
+    }
+    this.resultsEmitter.fire({
+      resultIndex: search.selectedIndex() ?? -1,
+      resultCount: search.total(),
+    });
+  }
+
+  dispose(): void {
+    this.cancelRefresh();
+    for (const sub of this.subscriptions) sub.dispose();
+    this.subscriptions = [];
+    this.terminal?.setSearchHighlights(null);
+    this.search?.free();
+    this.search = null;
+    this.resultsEmitter.dispose();
+    this.terminal = undefined;
+  }
+}

package/lib/ghostty.ts

@@ -6,7 +6,14 @@
  * grid references and key encoder through `Abi`.
  */
 
-import { Abi, GHOSTTY_SUCCESS, GhosttyCallError, type VtExports } from './abi';
+import {
+  Abi,
+  GHOSTTY_NO_VALUE,
+  GHOSTTY_OUT_OF_SPACE,
+  GHOSTTY_SUCCESS,
+  GhosttyCallError,
+  type VtExports,
+} from './abi';
 import { EventEmitter } from './event-emitter';
 import type { IEvent } from './interfaces';
 import {
@@ -372,6 +379,176 @@ function allocScratch(abi: Abi, layout: CellLayout): ExtractScratch {
  * Scrollback, graphemes, hyperlinks and wrap flags are read through grid
  * references on demand.
  */
+/** A match in screen coordinates: columns, and rows counted from the top of the scrollback. */
+export interface SearchMatch {
+  startX: number;
+  startY: number;
+  endX: number;
+  endY: number;
+}
+
+/**
+ * A search of one terminal's screen and scrollback with libghostty-vt's
+ * search: case-insensitive for ASCII letters, kept in sync with the terminal
+ * by `run()` after writes. It never scrolls; the caller shows the selected
+ * match. "Next" moves toward older output (up), as in Ghostty.
+ */
+export class TerminalSearch {
+  private handle: number;
+
+  constructor(
+    private readonly abi: Abi,
+    private readonly terminal: number
+  ) {
+    this.handle = abi.newHandle('ghostty_search_new', (slot) =>
+      abi.call('ghostty_search_new', 0, slot, terminal)
+    );
+    abi.with(4, (ptr) => {
+      abi.view().setInt32(ptr, abi.enumValue('GhosttySearchScroll', 'NONE'), true);
+      abi.check('ghostty_search_set', this.handle, this.option('SELECT_SCROLL'), ptr);
+    });
+  }
+
+  private option(name: string): number {
+    return this.abi.enumValue('GhosttySearchOption', name);
+  }
+
+  private data(name: string): number {
+    return this.abi.enumValue('GhosttySearchData', name);
+  }
+
+  /** Starts a search for `text`, or stops searching when it is empty. */
+  setNeedle(text: string): void {
+    const abi = this.abi;
+    if (!text) {
+      abi.check('ghostty_search_set', this.handle, this.option('NEEDLE'), 0);
+      return;
+    }
+    const bytes = new TextEncoder().encode(text);
+    abi.withBytes(bytes, (ptr, len) =>
+      abi.with(abi.sizeOf('GhosttyString'), (str) => {
+        const view = abi.view();
+        view.setUint32(str + abi.offset('GhosttyString', 'ptr'), ptr, true);
+        view.setUint32(str + abi.offset('GhosttyString', 'len'), len, true);
+        abi.check('ghostty_search_set', this.handle, this.option('NEEDLE'), str);
+      })
+    );
+  }
+
+  /** Catches up with everything written to the terminal since the last run. */
+  run(): void {
+    this.abi.check('ghostty_search_run', this.handle);
+  }
+
+  /** Selects the next older (`older`) or newer match, wrapping; false when there are none. */
+  select(older: boolean): boolean {
+    const result = this.abi.call(
+      'ghostty_search_set',
+      this.handle,
+      this.option(older ? 'SELECT_NEXT' : 'SELECT_PREV'),
+      0
+    );
+    if (result === GHOSTTY_NO_VALUE) return false;
+    if (result !== GHOSTTY_SUCCESS) throw new GhosttyCallError('ghostty_search_set', result);
+    return true;
+  }
+
+  total(): number {
+    return this.readU32('TOTAL_MATCHES') ?? 0;
+  }
+
+  /** Index of the selected match, newest first (0 is the newest), or null. */
+  selectedIndex(): number | null {
+    return this.readU32('SELECTED_INDEX');
+  }
+
+  private readU32(name: string): number | null {
+    const abi = this.abi;
+    return abi.with(8, (ptr) => {
+      const result = abi.call('ghostty_search_get', this.handle, this.data(name), ptr);
+      if (result === GHOSTTY_NO_VALUE) return null;
+      if (result !== GHOSTTY_SUCCESS) throw new GhosttyCallError('ghostty_search_get', result);
+      return abi.view().getUint32(ptr, true);
+    });
+  }
+
+  selected(): SearchMatch | null {
+    const abi = this.abi;
+    return abi.withSized('GhosttySelection', (sel) => {
+      const result = abi.call('ghostty_search_get', this.handle, this.data('SELECTED_MATCH'), sel);
+      if (result === GHOSTTY_NO_VALUE) return null;
+      if (result !== GHOSTTY_SUCCESS) throw new GhosttyCallError('ghostty_search_get', result);
+      return this.toMatch(sel);
+    });
+  }
+
+  /** Every match, newest first, read right after `run()` and before the next write. */
+  matches(): SearchMatch[] {
+    const abi = this.abi;
+    const selSize = abi.sizeOf('GhosttySelection');
+    const bufSize = abi.sizeOf('GhosttySelectionBuffer');
+    const at = (buf: number, field: string) => buf + abi.offset('GhosttySelectionBuffer', field);
+    return abi.with(bufSize, (buf) => {
+      const query = abi.call('ghostty_search_get', this.handle, this.data('MATCHES'), buf);
+      if (query === GHOSTTY_SUCCESS) return [];
+      if (query !== GHOSTTY_OUT_OF_SPACE) {
+        if (query === GHOSTTY_NO_VALUE) return [];
+        throw new GhosttyCallError('ghostty_search_get', query);
+      }
+      const count = abi.view().getUint32(at(buf, 'len'), true);
+      return abi.with(count * selSize, (items) => {
+        for (let i = 0; i < count; i++) {
+          abi.view().setUint32(items + i * selSize, selSize, true);
+        }
+        const view = abi.view();
+        view.setUint32(at(buf, 'ptr'), items, true);
+        view.setUint32(at(buf, 'cap'), count, true);
+        abi.check('ghostty_search_get', this.handle, this.data('MATCHES'), buf);
+        const len = abi.view().getUint32(at(buf, 'len'), true);
+        const out: SearchMatch[] = [];
+        for (let i = 0; i < len; i++) {
+          const match = this.toMatch(items + i * selSize);
+          if (match) out.push(match);
+        }
+        return out;
+      });
+    });
+  }
+
+  private toMatch(sel: number): SearchMatch | null {
+    const abi = this.abi;
+    const start = this.screenPoint(sel + abi.offset('GhosttySelection', 'start'));
+    const end = this.screenPoint(sel + abi.offset('GhosttySelection', 'end'));
+    if (!start || !end) return null;
+    return { startX: start.x, startY: start.y, endX: end.x, endY: end.y };
+  }
+
+  private screenPoint(ref: number): { x: number; y: number } | null {
+    const abi = this.abi;
+    return abi.with(abi.sizeOf('GhosttyPointCoordinate'), (out) => {
+      const result = abi.call(
+        'ghostty_terminal_point_from_grid_ref',
+        this.terminal,
+        ref,
+        abi.enumValue('GhosttyPointTag', 'SCREEN'),
+        out
+      );
+      if (result !== GHOSTTY_SUCCESS) return null;
+      const view = abi.view();
+      return {
+        x: view.getUint16(out + abi.offset('GhosttyPointCoordinate', 'x'), true),
+        y: view.getUint32(out + abi.offset('GhosttyPointCoordinate', 'y'), true),
+      };
+    });
+  }
+
+  free(): void {
+    if (!this.handle) return;
+    this.abi.call('ghostty_search_free', this.handle);
+    this.handle = 0;
+  }
+}
+
 export class GhosttyTerminal {
   private handle: number;
   private renderState: number;
@@ -449,7 +626,7 @@ export class GhosttyTerminal {
     this.setOption('WRITE_PTY', writePty);
     this.installHooks();
     this.setModeDefault(GRAPHEME_CLUSTER_MODE, true);
-    if (config) this.applyConfig(config);
+    if (config) this.configure(config);
     this.initCellPool();
   }
 
@@ -460,6 +637,11 @@ export class GhosttyTerminal {
     return this._rows;
   }
 
+  /** A new search of this terminal; free it before or after the terminal. */
+  createSearch(): TerminalSearch {
+    return new TerminalSearch(this.abi, this.handle);
+  }
+
   /** The raw libghostty-vt terminal handle, for APIs this class does not wrap yet. */
   get rawHandle(): number {
     return this.handle;
@@ -811,7 +993,11 @@ export class GhosttyTerminal {
   // Private helpers
   // ==========================================================================
 
-  private applyConfig(config: GhosttyTerminalConfig): void {
+  /**
+   * Applies scrollback and color settings. Colors take effect on the whole
+   * screen at the next update; programs can still change them (OSC 4/10/11).
+   */
+  configure(config: GhosttyTerminalConfig): void {
     const abi = this.abi;
     if (config.scrollbackLimit !== undefined) {
       abi.with(4, (ptr) => {
@@ -820,7 +1006,7 @@ export class GhosttyTerminal {
       });
     }
     const setRgb = (option: string, color: number | undefined) => {
-      if (!color) return;
+      if (color === undefined) return;
       abi.with(4, (ptr) => {
         const view = abi.view();
         view.setUint8(ptr, (color >> 16) & 0xff);
@@ -832,7 +1018,7 @@ export class GhosttyTerminal {
     setRgb('COLOR_FOREGROUND', config.fgColor);
     setRgb('COLOR_BACKGROUND', config.bgColor);
     setRgb('COLOR_CURSOR', config.cursorColor);
-    if (config.palette?.some((c) => c)) {
+    if (config.palette?.some((c) => c !== undefined)) {
       const size = 256 * 3;
       abi.with(size, (ptr) => {
         abi.check(
@@ -843,7 +1029,7 @@ export class GhosttyTerminal {
         );
         const view = abi.view();
         config.palette!.slice(0, 16).forEach((color, i) => {
-          if (!color) return;
+          if (color === undefined) return;
           view.setUint8(ptr + i * 3, (color >> 16) & 0xff);
           view.setUint8(ptr + i * 3 + 1, (color >> 8) & 0xff);
           view.setUint8(ptr + i * 3 + 2, color & 0xff);
@@ -851,6 +1037,8 @@ export class GhosttyTerminal {
         this.setOption('COLOR_PALETTE', ptr);
       });
     }
+    this.changed = true;
+    this.dirty = DirtyState.FULL;
   }
 
   private installHooks(): void {
@@ -1028,6 +1216,36 @@ export class GhosttyTerminal {
         palette,
       };
     });
+    this.readTerminalColors();
+  }
+
+  /**
+   * The render state does not pick up default colors set with
+   * ghostty_terminal_set, so the effective colors (a program's OSC override,
+   * else the default) are read from the terminal itself.
+   */
+  private readTerminalColors(): 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
+      );
+    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);
+    });
   }
 
   private extractRows(all: boolean): void {

package/lib/glyph-ink.ts

@@ -0,0 +1,42 @@
+/**
+ * Finds the pixels a rasterized glyph actually covers, so the renderer draws
+ * a quad over the ink instead of over the whole padded atlas slot.
+ */
+
+const COLORED_SPREAD = 24;
+
+export interface GlyphInk {
+  left: number;
+  top: number;
+  width: number;
+  height: number;
+  colored: boolean;
+}
+
+/** Bounds of the non-transparent pixels in RGBA `data` (`w` × `h`), or null when none. */
+export function glyphInk(data: Uint8ClampedArray, w: number, h: number): GlyphInk | null {
+  let left = w;
+  let right = -1;
+  let top = h;
+  let bottom = -1;
+  let colored = false;
+  for (let y = 0; y < h; y++) {
+    const row = y * w * 4;
+    for (let x = 0; x < w; x++) {
+      const i = row + x * 4;
+      if (data[i + 3] === 0) continue;
+      if (x < left) left = x;
+      if (x > right) right = x;
+      if (y < top) top = y;
+      bottom = y;
+      if (!colored) {
+        const r = data[i];
+        const g = data[i + 1];
+        const b = data[i + 2];
+        colored = Math.max(r, g, b) - Math.min(r, g, b) > COLORED_SPREAD;
+      }
+    }
+  }
+  if (right < 0) return null;
+  return { left, top, width: right - left + 1, height: bottom - top + 1, colored };
+}

package/lib/index.ts

@@ -102,6 +102,12 @@ export type { SelectionCoordinates } from './selection-manager';
 
 // Addons
 export { FitAddon } from './addons/fit';
+export { SearchAddon } from './addons/search';
+export type {
+  ISearchDecorationOptions,
+  ISearchOptions,
+  ISearchResultChangeEvent,
+} from './addons/search';
 export type { ITerminalDimensions } from './addons/fit';
 
 // Link providers

package/lib/input-handler.ts

@@ -195,6 +195,13 @@ export class InputHandler {
   private wheelListener: ((e: WheelEvent) => void) | null = null;
   private isComposing = false;
   private isDisposed = false;
+  /**
+   * On macOS, whether Option acts as Meta (ESC prefix) instead of composing a
+   * character (Option+A types 'å'). Elsewhere Alt always acts as Meta.
+   */
+  macOptionIsMeta = false;
+  private readonly isMac =
+    typeof navigator !== 'undefined' && /Mac|iPhone|iPad/.test(navigator.platform ?? '');
   private mouseButtonsPressed = 0; // Track which buttons are pressed for motion reporting
   private lastKeyDownData: string | null = null;
   private lastKeyDownTime = 0;
@@ -233,6 +240,7 @@ export class InputHandler {
     mouseConfig?: MouseTrackingConfig
   ) {
     this.encoder = ghostty.createKeyEncoder();
+    this.encoder.setOption(KeyEncoderOption.ALT_ESC_PREFIX, true);
     this.container = container;
     this.inputElement = inputElement;
     this.onDataCallback = onData;
@@ -345,6 +353,18 @@ export class InputHandler {
     return mods;
   }
 
+  /** macOS Option without Ctrl or Cmd composes a character unless Option is Meta. */
+  private optionComposes(event: KeyboardEvent): boolean {
+    return (
+      this.isMac &&
+      !this.macOptionIsMeta &&
+      event.altKey &&
+      !event.ctrlKey &&
+      !event.metaKey &&
+      event.key.length === 1
+    );
+  }
+
   /**
    * Check if this is a printable character with no special modifiers
    * @param event - KeyboardEvent
@@ -407,6 +427,13 @@ export class InputHandler {
       return;
     }
 
+    if (this.optionComposes(event)) {
+      event.preventDefault();
+      this.onDataCallback(event.key);
+      this.recordKeyDownData(event.key);
+      return;
+    }
+
     // For printable characters without modifiers, send the character directly
     // This handles: a-z, A-Z (with shift), 0-9, punctuation, etc.
     if (this.isPrintableCharacter(event)) {
@@ -532,7 +559,9 @@ export class InputHandler {
       const utf8 =
         event.key.length === 1 && event.key.charCodeAt(0) < 128
           ? event.key.toLowerCase() // Use lowercase for consistency
-          : undefined;
+          : event.altKey
+            ? baseCharacter(event.code)
+            : undefined;
 
       const encoded = this.encoder.encode({
         action,
@@ -1114,3 +1143,15 @@ export class InputHandler {
     return !this.isDisposed;
   }
 }
+
+/**
+ * The character a letter or digit key types without modifiers, from its
+ * physical code: Alt as Meta sends ESC and this even when the layout makes
+ * Alt+key type something else (macOS Option+A types 'å').
+ */
+function baseCharacter(code: string): string | undefined {
+  const letter = /^Key([A-Z])$/.exec(code);
+  if (letter) return letter[1].toLowerCase();
+  const digit = /^Digit([0-9])$/.exec(code);
+  return digit ? digit[1] : undefined;
+}

package/lib/interfaces.ts

@@ -14,6 +14,14 @@ export interface ITerminalOptions {
   fontSize?: number; // Default: 15
   fontFamily?: string; // Default: 'monospace'
   allowTransparency?: boolean;
+  fontWeight?: FontWeight; // Default: 'normal'
+  fontWeightBold?: FontWeight; // Default: 'bold'
+  lineHeight?: number; // Multiplies the cell height. Default: 1
+  scrollSensitivity?: number; // Multiplies wheel scrolling. Default: 1
+  /** Foreground colors are adjusted to at least this contrast ratio with their background (1 to 21). Default: 1 */
+  minimumContrastRatio?: number;
+  /** On macOS, Option acts as Meta instead of composing characters. Default: false */
+  macOptionIsMeta?: boolean;
   /**
    * How the terminal draws, read when it opens. 'webgl' draws on the GPU and
    * falls back to 'canvas' when WebGL 2 is unavailable or its context is lost.
@@ -21,6 +29,12 @@ export interface ITerminalOptions {
    */
   renderer?: 'webgl' | 'canvas';
 
+  /**
+   * What clicking and hovering a web link does (plain URLs and OSC 8
+   * hyperlinks). Without one, Ctrl/Cmd+click opens the link in a new window.
+   */
+  linkHandler?: ILinkHandler | null;
+
   // Phase 1 additions
   convertEol?: boolean; // Convert \n to \r\n (default: false)
   disableStdin?: boolean; // Disable keyboard input (default: false)
@@ -33,6 +47,15 @@ export interface ITerminalOptions {
   ghostty?: Ghostty;
 }
 
+export type FontWeight = 'normal' | 'bold' | number;
+
+/** Handles web links the way xterm.js's `linkHandler` option does. Ranges are 0-based buffer cells. */
+export interface ILinkHandler {
+  activate(event: MouseEvent, text: string, range: IBufferRange): void;
+  hover?(event: MouseEvent, text: string, range: IBufferRange): void;
+  leave?(event: MouseEvent, text: string, range: IBufferRange): void;
+}
+
 export interface ITheme {
   foreground?: string;
   background?: string;