@aurigax-ai/ghostty-web 0.0.0-stage → 0.2.0

package/lib/interfaces.ts

@@ -0,0 +1,224 @@
+/**
+ * xterm.js-compatible interfaces
+ */
+
+import type { Ghostty } from './ghostty';
+
+export interface ITerminalOptions {
+  cols?: number; // Default: 80
+  rows?: number; // Default: 24
+  cursorBlink?: boolean; // Default: false
+  cursorStyle?: 'block' | 'underline' | 'bar';
+  theme?: ITheme;
+  scrollback?: number; // Default: 10000
+  fontSize?: number; // Default: 15
+  fontFamily?: string; // Default: 'monospace'
+  allowTransparency?: 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.
+   * Default: 'webgl'.
+   */
+  renderer?: 'webgl' | 'canvas';
+
+  // Phase 1 additions
+  convertEol?: boolean; // Convert \n to \r\n (default: false)
+  disableStdin?: boolean; // Disable keyboard input (default: false)
+
+  // Scrolling options
+  smoothScrollDuration?: number; // Duration in ms for smooth scroll animation (default: 100, 0 = instant)
+
+  // Internal: Ghostty WASM instance (optional, for test isolation)
+  // If not provided, uses the module-level instance from init()
+  ghostty?: Ghostty;
+}
+
+export interface ITheme {
+  foreground?: string;
+  background?: string;
+  cursor?: string;
+  cursorAccent?: string;
+  selectionBackground?: string;
+  selectionForeground?: string;
+
+  // ANSI colors (0-15)
+  black?: string;
+  red?: string;
+  green?: string;
+  yellow?: string;
+  blue?: string;
+  magenta?: string;
+  cyan?: string;
+  white?: string;
+  brightBlack?: string;
+  brightRed?: string;
+  brightGreen?: string;
+  brightYellow?: string;
+  brightBlue?: string;
+  brightMagenta?: string;
+  brightCyan?: string;
+  brightWhite?: string;
+}
+
+export interface IDisposable {
+  dispose(): void;
+}
+
+export type IEvent<T> = (listener: (arg: T) => void) => IDisposable;
+
+export interface ITerminalAddon {
+  activate(terminal: ITerminalCore): void;
+  dispose(): void;
+}
+
+export interface ITerminalCore {
+  cols: number;
+  rows: number;
+  element?: HTMLElement;
+  textarea?: HTMLTextAreaElement;
+}
+
+/**
+ * Buffer range for selection coordinates
+ */
+export interface IBufferRange {
+  start: { x: number; y: number };
+  end: { x: number; y: number };
+}
+
+/**
+ * Keyboard event with key and DOM event
+ */
+export interface IKeyEvent {
+  key: string;
+  domEvent: KeyboardEvent;
+}
+
+/**
+ * Unicode version provider (xterm.js compatibility)
+ */
+export interface IUnicodeVersionProvider {
+  readonly activeVersion: string;
+}
+
+// ============================================================================
+// Buffer API Interfaces (xterm.js compatibility)
+// ============================================================================
+
+/**
+ * Top-level buffer API namespace
+ * Provides access to active, normal, and alternate screen buffers
+ */
+export interface IBufferNamespace {
+  /** The currently active buffer (normal or alternate) */
+  readonly active: IBuffer;
+  /** The normal buffer (primary screen) */
+  readonly normal: IBuffer;
+  /** The alternate buffer (used by full-screen apps like vim) */
+  readonly alternate: IBuffer;
+
+  /** Event fired when buffer changes (normal ↔ alternate) */
+  readonly onBufferChange: IEvent<IBuffer>;
+}
+
+/**
+ * A terminal buffer (normal or alternate screen)
+ */
+export interface IBuffer {
+  /** Buffer type: 'normal' or 'alternate' */
+  readonly type: 'normal' | 'alternate';
+  /** Cursor X position (0-indexed) */
+  readonly cursorX: number;
+  /** Cursor Y position (0-indexed, relative to viewport) */
+  readonly cursorY: number;
+  /** Viewport Y position (scroll offset, 0 = bottom of scrollback) */
+  readonly viewportY: number;
+  /** Base Y position (always 0 for normal buffer, may vary for alternate) */
+  readonly baseY: number;
+  /** Total buffer length (rows + scrollback for normal, just rows for alternate) */
+  readonly length: number;
+
+  /**
+   * Get a line from the buffer
+   * @param y Line index (0 = top of scrollback for normal buffer)
+   * @returns Line object or undefined if out of bounds
+   */
+  getLine(y: number): IBufferLine | undefined;
+
+  /**
+   * Get the null cell (used for empty/uninitialized cells)
+   */
+  getNullCell(): IBufferCell;
+}
+
+/**
+ * A single line in the buffer
+ */
+export interface IBufferLine {
+  /** Length of the line (in columns) */
+  readonly length: number;
+  /** Whether this line wraps to the next line */
+  readonly isWrapped: boolean;
+
+  /**
+   * Get a cell from this line
+   * @param x Column index (0-indexed)
+   * @returns Cell object or undefined if out of bounds
+   */
+  getCell(x: number): IBufferCell | undefined;
+
+  /**
+   * Translate the line to a string
+   * @param trimRight Whether to trim trailing whitespace (default: false)
+   * @param startColumn Start column (default: 0)
+   * @param endColumn End column (default: length)
+   * @returns String representation of the line
+   */
+  translateToString(trimRight?: boolean, startColumn?: number, endColumn?: number): string;
+}
+
+/**
+ * A single cell in the buffer
+ */
+export interface IBufferCell {
+  /** Character(s) in this cell (may be empty, single char, or emoji) */
+  getChars(): string;
+  /** Unicode codepoint (0 for null cell) */
+  getCode(): number;
+  /** Character width (1 = normal, 2 = wide/emoji, 0 = combining) */
+  getWidth(): number;
+
+  /** Foreground color index (for palette colors) or -1 for RGB */
+  getFgColorMode(): number;
+  /** Background color index (for palette colors) or -1 for RGB */
+  getBgColorMode(): number;
+  /** Foreground RGB color (or 0 for default) */
+  getFgColor(): number;
+  /** Background RGB color (or 0 for default) */
+  getBgColor(): number;
+
+  /** Whether cell has bold style */
+  isBold(): number;
+  /** Whether cell has italic style */
+  isItalic(): number;
+  /** Whether cell has underline style */
+  isUnderline(): number;
+  /** Whether cell has strikethrough style */
+  isStrikethrough(): number;
+  /** Whether cell has blink style */
+  isBlink(): number;
+  /** Whether cell has inverse video style */
+  isInverse(): number;
+  /** Whether cell has invisible style */
+  isInvisible(): number;
+  /** Whether cell has faint/dim style */
+  isFaint(): number;
+
+  // Link detection support
+  /** Get hyperlink ID for this cell (0 = no link) */
+  getHyperlinkId(): number;
+  /** Get the Unicode codepoint for this cell */
+  getCodepoint(): number;
+  /** Whether cell has dim/faint attribute (boolean version) */
+  isDim(): boolean;
+}

package/lib/link-detector.ts

@@ -0,0 +1,215 @@
+/**
+ * Link detection and caching system
+ *
+ * The LinkDetector coordinates between multiple link providers and caches
+ * results for performance. Links are cached by position range, and earlier
+ * providers (e.g. OSC8) take precedence over later ones (e.g. regex).
+ */
+
+import type { ILink, ILinkProvider } from './types';
+
+/**
+ * Manages link detection across multiple providers with intelligent caching
+ */
+export class LinkDetector {
+  private providers: ILinkProvider[] = [];
+
+  // Cache links by position range: `r${row}:${startX}-${endX}`
+  private linkCache = new Map<string, ILink>();
+
+  // Track which rows have been scanned to avoid redundant provider calls
+  private scannedRows = new Set<number>();
+
+  // Terminal instance for buffer access
+  constructor(private terminal: ITerminalForLinkDetector) {}
+
+  /**
+   * Register a link provider
+   */
+  registerProvider(provider: ILinkProvider): void {
+    this.providers.push(provider);
+    this.invalidateCache(); // New provider may detect different links
+  }
+
+  /**
+   * Get link at the specified buffer position
+   * @param col Column (0-based)
+   * @param row Absolute row in buffer (0-based)
+   * @returns Link at position, or undefined if none
+   */
+  async getLinkAt(col: number, row: number): Promise<ILink | undefined> {
+    const line = this.terminal.buffer.active.getLine(row);
+    if (!line || col < 0 || col >= line.length) {
+      return undefined;
+    }
+
+    const cell = line.getCell(col);
+    if (!cell) {
+      return undefined;
+    }
+
+    // Check if any cached link contains this position (fast path)
+    for (const link of this.linkCache.values()) {
+      if (this.isPositionInLink(col, row, link)) {
+        return link;
+      }
+    }
+
+    // Slow path: scan this row if not already scanned
+    if (!this.scannedRows.has(row)) {
+      await this.scanRow(row);
+    }
+
+    // Check cache again after scanning
+    for (const link of this.linkCache.values()) {
+      if (this.isPositionInLink(col, row, link)) {
+        return link;
+      }
+    }
+
+    return undefined;
+  }
+
+  /**
+   * Scan a row for links using all registered providers
+   */
+  private async scanRow(row: number): Promise<void> {
+    this.scannedRows.add(row);
+
+    const allLinks: ILink[] = [];
+
+    // Query all providers
+    for (const provider of this.providers) {
+      const links = await new Promise<ILink[] | undefined>((resolve) => {
+        provider.provideLinks(row, resolve);
+      });
+
+      if (links) {
+        allLinks.push(...links);
+      }
+    }
+
+    // Cache all discovered links
+    for (const link of allLinks) {
+      this.cacheLink(link);
+    }
+  }
+
+  /**
+   * Cache a link for fast lookup
+   *
+   * Note: We cache by position range, not hyperlink_id, because the WASM
+   * returns hyperlink_id as a boolean (0 or 1), not a unique identifier.
+   * The actual unique identifier is the URI which is retrieved separately.
+   */
+  private cacheLink(link: ILink): void {
+    // Cache by position range - this uniquely identifies links even when
+    // multiple OSC 8 links exist on the same line
+    const { start: s, end: e } = link.range;
+    const cacheKey = `r${s.y}:${s.x}-${e.x}`;
+    // Don't overwrite existing entries - earlier providers (OSC8) take
+    // precedence over later ones (regex) for the same range
+    if (!this.linkCache.has(cacheKey)) {
+      this.linkCache.set(cacheKey, link);
+    }
+  }
+
+  /**
+   * Check if a position is within a link's range
+   */
+  private isPositionInLink(col: number, row: number, link: ILink): boolean {
+    const { start, end } = link.range;
+
+    // Check if row is in range
+    if (row < start.y || row > end.y) {
+      return false;
+    }
+
+    // Single-line link
+    if (start.y === end.y) {
+      return col >= start.x && col <= end.x;
+    }
+
+    // Multi-line link
+    if (row === start.y) {
+      return col >= start.x; // First line: from start.x to end of line
+    } else if (row === end.y) {
+      return col <= end.x; // Last line: from start of line to end.x
+    } else {
+      return true; // Middle line: entire line is part of link
+    }
+  }
+
+  /**
+   * Invalidate cache when terminal content changes
+   * Should be called on terminal write, resize, or clear
+   */
+  invalidateCache(): void {
+    this.linkCache.clear();
+    this.scannedRows.clear();
+  }
+
+  /**
+   * Invalidate cache for specific rows
+   * Used when only part of the terminal changed
+   */
+  invalidateRows(startRow: number, endRow: number): void {
+    // Remove scanned markers
+    for (let row = startRow; row <= endRow; row++) {
+      this.scannedRows.delete(row);
+    }
+
+    // Remove cached links in this range
+    // This is conservative - we remove any link that touches these rows
+    const toDelete: string[] = [];
+    for (const [key, link] of this.linkCache.entries()) {
+      const { start, end } = link.range;
+      if (
+        (start.y >= startRow && start.y <= endRow) ||
+        (end.y >= startRow && end.y <= endRow) ||
+        (start.y < startRow && end.y > endRow)
+      ) {
+        toDelete.push(key);
+      }
+    }
+
+    for (const key of toDelete) {
+      this.linkCache.delete(key);
+    }
+  }
+
+  /**
+   * Dispose and cleanup
+   */
+  dispose(): void {
+    this.linkCache.clear();
+    this.scannedRows.clear();
+
+    // Dispose all providers
+    for (const provider of this.providers) {
+      provider.dispose?.();
+    }
+    this.providers = [];
+  }
+}
+
+/**
+ * Minimal terminal interface required by LinkDetector
+ * Keeps coupling low and testing easy
+ */
+export interface ITerminalForLinkDetector {
+  buffer: {
+    active: {
+      getLine(y: number):
+        | {
+            length: number;
+            getCell(x: number):
+              | {
+                  getHyperlinkId(): number;
+                }
+              | undefined;
+          }
+        | undefined;
+    };
+  };
+}

package/lib/marker.ts

@@ -0,0 +1,55 @@
+/**
+ * xterm.js-compatible marker on a buffer line, backed by a libghostty-vt
+ * tracked grid reference so it follows its line through scrolling, reflow and
+ * scrollback pruning.
+ */
+
+import { EventEmitter } from './event-emitter';
+import type { TrackedRow } from './ghostty';
+import type { IDisposable, IEvent } from './interfaces';
+
+export interface IMarker extends IDisposable {
+  readonly id: number;
+  readonly isDisposed: boolean;
+  /** The marker's absolute buffer line (scrollback first), or -1 once disposed. */
+  readonly line: number;
+  readonly onDispose: IEvent<void>;
+}
+
+let nextMarkerId = 1;
+
+export class Marker implements IMarker {
+  readonly id = nextMarkerId++;
+  private disposed = false;
+  private readonly disposeEmitter = new EventEmitter<void>();
+  readonly onDispose: IEvent<void> = this.disposeEmitter.event;
+
+  constructor(private readonly row: TrackedRow) {}
+
+  get isDisposed(): boolean {
+    return this.disposed;
+  }
+
+  get line(): number {
+    if (this.disposed) return -1;
+    const line = this.row.line();
+    if (line === null) {
+      this.dispose();
+      return -1;
+    }
+    return line;
+  }
+
+  /** Disposes the marker if its line no longer exists. */
+  refresh(): void {
+    if (!this.disposed && this.row.line() === null) this.dispose();
+  }
+
+  dispose(): void {
+    if (this.disposed) return;
+    this.disposed = true;
+    this.row.free();
+    this.disposeEmitter.fire();
+    this.disposeEmitter.dispose();
+  }
+}

package/lib/providers/osc8-link-provider.ts

@@ -0,0 +1,144 @@
+/**
+ * OSC 8 Hyperlink Provider
+ *
+ * Detects hyperlinks created with OSC 8 escape sequences.
+ * Supports multi-line links that wrap across lines.
+ *
+ * OSC 8 format: \x1b]8;;URL\x07TEXT\x1b]8;;\x07
+ *
+ * The Ghostty WASM automatically assigns hyperlink_id to cells,
+ * so we just need to scan for contiguous regions with the same ID.
+ */
+
+import type { IBufferRange, ILink, ILinkProvider } from '../types';
+
+/**
+ * OSC 8 Hyperlink Provider
+ *
+ * Detects OSC 8 hyperlinks by scanning for hyperlink_id in cells.
+ * Automatically handles multi-line links since Ghostty WASM preserves
+ * hyperlink_id across wrapped lines.
+ */
+export class OSC8LinkProvider implements ILinkProvider {
+  constructor(private terminal: ITerminalForOSC8Provider) {}
+
+  /**
+   * Provide all OSC 8 links on the given row
+   * Note: This may return links that span multiple rows
+   */
+  provideLinks(y: number, callback: (links: ILink[] | undefined) => void): void {
+    const links: ILink[] = [];
+    const visitedPositions = new Set<number>(); // Track which columns we've already processed
+
+    const line = this.terminal.buffer.active.getLine(y);
+    if (!line) {
+      callback(undefined);
+      return;
+    }
+
+    // Scan through this line looking for hyperlink_id
+    for (let x = 0; x < line.length; x++) {
+      // Skip already processed positions
+      if (visitedPositions.has(x)) continue;
+
+      const cell = line.getCell(x);
+      if (!cell) continue;
+
+      const hyperlinkId = cell.getHyperlinkId();
+
+      // Skip cells without links
+      if (hyperlinkId === 0) {
+        continue;
+      }
+
+      // Get the URI from WASM
+      // The y parameter is a buffer row - we need to determine if it's in
+      // scrollback or the active viewport and use the appropriate API
+      if (!this.terminal.wasmTerm) continue;
+      const scrollbackLength = this.terminal.wasmTerm.getScrollbackLength();
+      const viewportRow = y - scrollbackLength;
+
+      let uri: string | null;
+      if (viewportRow < 0) {
+        // Row is in scrollback - use scrollback API
+        // y is the buffer row (0 = oldest), scrollback offset is also 0 = oldest
+        uri = this.terminal.wasmTerm.getScrollbackHyperlinkUri(y, x);
+      } else {
+        // Row is in active viewport
+        uri = this.terminal.wasmTerm.getHyperlinkUri(viewportRow, x);
+      }
+
+      if (uri) {
+        // Find the end of this link by scanning forward until we hit a cell
+        // without a hyperlink or with a different URI
+        let endX = x;
+        for (let col = x + 1; col < line.length; col++) {
+          const nextCell = line.getCell(col);
+          if (!nextCell || nextCell.getHyperlinkId() === 0) break;
+
+          // Check if this cell has the same URI (use appropriate API for scrollback vs viewport)
+          const nextUri =
+            viewportRow < 0
+              ? this.terminal.wasmTerm!.getScrollbackHyperlinkUri(y, col)
+              : this.terminal.wasmTerm!.getHyperlinkUri(viewportRow, col);
+          if (nextUri !== uri) break;
+
+          endX = col;
+        }
+
+        // Mark all columns in this link as visited
+        for (let col = x; col <= endX; col++) {
+          visitedPositions.add(col);
+        }
+
+        const range: IBufferRange = {
+          start: { x, y },
+          end: { x: endX, y },
+        };
+
+        links.push({
+          text: uri,
+          range,
+          activate: (event) => {
+            // Open link if Ctrl/Cmd is pressed
+            if (event.ctrlKey || event.metaKey) {
+              window.open(uri, '_blank', 'noopener,noreferrer');
+            }
+          },
+        });
+      }
+    }
+
+    callback(links.length > 0 ? links : undefined);
+  }
+
+  dispose(): void {
+    // No resources to clean up
+  }
+}
+
+/**
+ * Minimal terminal interface required by OSC8LinkProvider
+ */
+export interface ITerminalForOSC8Provider {
+  buffer: {
+    active: {
+      length: number;
+      getLine(y: number):
+        | {
+            length: number;
+            getCell(x: number):
+              | {
+                  getHyperlinkId(): number;
+                }
+              | undefined;
+          }
+        | undefined;
+    };
+  };
+  wasmTerm?: {
+    getHyperlinkUri(row: number, col: number): string | null;
+    getScrollbackHyperlinkUri(offset: number, col: number): string | null;
+    getScrollbackLength(): number;
+  };
+}