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

package/GHOSTTY_COMMIT

@@ -0,0 +1 @@
+c3203ea4b169a18eb2ccfe92847e426d8afea858

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 Coder
+Copyright (c) 2026 AurigaX
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,95 @@
-# Temporary Holding Version
+# ghostty-web (AurigaX)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[Ghostty](https://github.com/ghostty-org/ghostty)'s terminal engine in the browser, with an
+[xterm.js](https://github.com/xtermjs/xterm.js)-shaped API and WebGL and canvas renderers. It is the engine
+behind the Ghostty terminal in Ostia.
+
+This is a hard fork of [coder/ghostty-web](https://github.com/coder/ghostty-web) (MIT, © Coder),
+kept with its history. It does not track upstream. What changed:
+
+- **Official, unpatched libghostty-vt.** ghostty-web built Ghostty with a patch that added its own
+  C functions. This fork builds Ghostty's published libghostty-vt API at a pinned commit
+  (`GHOSTTY_COMMIT`) and talks to it through `lib/abi.ts`, which reads struct layouts from
+  `ghostty_type_json()` so a field that moves fails loudly instead of reading garbage.
+- **Host hooks.** JavaScript callbacks reach libghostty-vt through its growable function table
+  (`Abi.addCallback`), so the host can receive prompt marks (OSC 133), the working directory with
+  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
+  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.
+
+## Install
+
+```sh
+pnpm add @aurigax-ai/ghostty-web
+```
+
+The package ships its TypeScript source and `ghostty-vt.wasm`; bundle it with Vite or similar.
+
+## Build
+
+Needs [Zig](https://ziglang.org) 0.16.0 and pnpm. Use the official Zig tarball (as CI does): a
+distribution's Zig built against its own LLVM produces a different, equally valid `ghostty-vt.wasm`,
+and CI checks that the committed file matches the official build. Point `ZIG` at it if it is not the
+`zig` on your PATH: `ZIG=/path/to/zig pnpm build:wasm`.
+
+```sh
+pnpm install
+pnpm build:wasm   # clones Ghostty at GHOSTTY_COMMIT into vendor/ and builds ghostty-vt.wasm
+pnpm test
+pnpm build        # dist/ with the library and the WASM
+```
+
+libghostty-vt's API is not stable yet, so `GHOSTTY_COMMIT` is raised on purpose, with the tests as
+the guard. The built `ghostty-vt.wasm` is committed so the package installs without Zig; the build
+is reproducible and CI fails if the committed file differs from a fresh build of the pinned commit.
+The package exports its TypeScript source (`lib/index.ts`), for bundlers such as Vite.
+
+## Host hooks
+
+Besides the xterm.js-shaped API, `Terminal` exposes what libghostty-vt reports, at its exact place
+in the output stream:
+
+| Hook                      | What it reports                                                                                        |
+| ------------------------- | ------------------------------------------------------------------------------------------------------ |
+| `onSemanticPrompt`        | OSC 133 prompt marks (`prompt-start`, `input-start`, `output-start`, `command-end` with the exit code) |
+| `onPwdChange`             | OSC 7 as sent: the raw `file://host/path` URI                                                          |
+| `onDesktopNotification`   | OSC 9 and OSC 777 notifications                                                                        |
+| `onUnknownOsc`            | OSCs Ghostty does not implement, e.g. `633;E;…`                                                        |
+| `onBell`, `onTitleChange` | Ghostty's own bell and title                                                                           |
+| `clipboardWriteHandler`   | Decides OSC 52 writes (denied unless it returns true); reads are never answered                        |
+| `registerMarker(offset)`  | An xterm.js-style marker that follows its line through scrolling and reflow                            |
+| `modes.mouseTrackingMode` | `none`, `x10`, `vt200`, `drag` or `any`                                                                |
+
+The render loop runs only while something changes (output, input, scrolling, selection, cursor
+blink) and sleeps otherwise.
+
+## Use
+
+```ts
+import { Ghostty, Terminal, FitAddon } from '@aurigax-ai/ghostty-web';
+
+const ghostty = await Ghostty.fromBytes(wasmBytes);
+const term = new Terminal({ ghostty, fontSize: 14 });
+const fit = new FitAddon();
+term.loadAddon(fit);
+term.open(element);
+fit.fit();
+term.onData((data) => pty.write(data));
+pty.onData((data) => term.write(data));
+```
+
+## Release
+
+Raise `version` in `package.json`, commit, and push a matching `v<version>` tag. `release.yml`
+rebuilds the WASM, checks it matches the committed file, runs the tests and publishes to npm with
+trusted publishing (no token). A version with a `-` (e.g. `0.2.0-rc.1`) is published under the
+`next` tag.
+
+## License
+
+MIT. See [LICENSE](./LICENSE). Ghostty is MIT licensed by Mitchell Hashimoto and the Ghostty
+contributors.

package/lib/abi.ts

@@ -0,0 +1,227 @@
+/**
+ * Low-level access to the official libghostty-vt WebAssembly ABI.
+ *
+ * Struct layouts are read from `ghostty_type_json()` at load time instead of
+ * being hard-coded, so a Ghostty upgrade that moves a field fails loudly in
+ * `Abi.offset` rather than reading garbage.
+ */
+
+export const GHOSTTY_SUCCESS = 0;
+export const GHOSTTY_INVALID_VALUE = -2;
+export const GHOSTTY_OUT_OF_SPACE = -3;
+export const GHOSTTY_NO_VALUE = -4;
+
+type Fn = (...args: any[]) => any;
+
+export interface VtExports {
+  memory: WebAssembly.Memory;
+  __indirect_function_table: WebAssembly.Table;
+  [name: string]: Fn | WebAssembly.Memory | WebAssembly.Table;
+}
+
+interface FieldLayout {
+  offset: number;
+  size: number;
+}
+
+interface TypeLayout {
+  kind: string;
+  size: number;
+  fields?: Record<string, FieldLayout>;
+  bits?: Record<string, { lsb: number; width: number }>;
+  values?: Record<string, number>;
+}
+
+const I32 = 0x7f;
+const I64 = 0x7e;
+
+function leb(n: number): number[] {
+  const out: number[] = [];
+  let v = n;
+  do {
+    let byte = v & 0x7f;
+    v >>>= 7;
+    if (v !== 0) byte |= 0x80;
+    out.push(byte);
+  } while (v !== 0);
+  return out;
+}
+
+function section(id: number, body: number[]): number[] {
+  return [id, ...leb(body.length), ...body];
+}
+
+/**
+ * The bytes of a tiny module that imports one host function and re-exports it,
+ * which turns a JavaScript function into a WebAssembly function that can be
+ * placed in libghostty-vt's (growable) function table.
+ */
+export function trampolineBytes(
+  params: ('i32' | 'i64')[],
+  result: 'i32' | null
+): Uint8Array<ArrayBuffer> {
+  const name = [1, 0x66];
+  const type = [
+    1,
+    0x60,
+    params.length,
+    ...params.map((p) => (p === 'i64' ? I64 : I32)),
+    ...(result ? [1, I32] : [0]),
+  ];
+  return new Uint8Array([
+    0x00,
+    0x61,
+    0x73,
+    0x6d,
+    0x01,
+    0x00,
+    0x00,
+    0x00,
+    ...section(1, type),
+    ...section(2, [1, 1, 0x65, ...name, 0x00, 0]),
+    ...section(7, [1, ...name, 0x00, 0]),
+  ]);
+}
+
+export class GhosttyCallError extends Error {
+  constructor(
+    readonly call: string,
+    readonly result: number
+  ) {
+    super(`${call} failed with result ${result}`);
+  }
+}
+
+export class Abi {
+  private readonly types: Record<string, TypeLayout>;
+  private readonly freeSlots: number[] = [];
+
+  constructor(readonly exports: VtExports) {
+    const ptr = this.fn('ghostty_type_json')() as number;
+    const bytes = new Uint8Array(exports.memory.buffer);
+    let end = ptr;
+    while (bytes[end] !== 0) end++;
+    this.types = JSON.parse(new TextDecoder().decode(bytes.subarray(ptr, end))).types;
+  }
+
+  fn(name: string): Fn {
+    const f = this.exports[name];
+    if (typeof f !== 'function') throw new Error(`libghostty-vt has no export ${name}`);
+    return f as Fn;
+  }
+
+  call(name: string, ...args: unknown[]): number {
+    return this.fn(name)(...args) as number;
+  }
+
+  check(name: string, ...args: unknown[]): void {
+    const result = this.call(name, ...args);
+    if (result !== GHOSTTY_SUCCESS) throw new GhosttyCallError(name, result);
+  }
+
+  sizeOf(type: string): number {
+    const layout = this.types[type];
+    if (!layout) throw new Error(`libghostty-vt has no type ${type}`);
+    return layout.size;
+  }
+
+  offset(type: string, field: string): number {
+    const f = this.types[type]?.fields?.[field];
+    if (!f) throw new Error(`libghostty-vt type ${type} has no field ${field}`);
+    return f.offset;
+  }
+
+  bits(type: string, field: string): { lsb: number; width: number } {
+    const b = this.types[type]?.bits?.[field];
+    if (!b) throw new Error(`libghostty-vt type ${type} has no bit field ${field}`);
+    return b;
+  }
+
+  enumValue(type: string, key: string): number {
+    const v = this.types[type]?.values?.[key];
+    if (v === undefined) throw new Error(`libghostty-vt enum ${type} has no value ${key}`);
+    return v;
+  }
+
+  bytes(): Uint8Array {
+    return new Uint8Array(this.exports.memory.buffer);
+  }
+
+  view(): DataView {
+    return new DataView(this.exports.memory.buffer);
+  }
+
+  alloc(len: number): number {
+    const ptr = this.call('ghostty_wasm_alloc', len);
+    if (ptr === 0) throw new GhosttyCallError('ghostty_wasm_alloc', -1);
+    this.bytes().fill(0, ptr, ptr + len);
+    return ptr;
+  }
+
+  free(ptr: number, len: number): void {
+    this.call('ghostty_wasm_free', ptr, len);
+  }
+
+  with<T>(len: number, use: (ptr: number) => T): T {
+    const ptr = this.alloc(len);
+    try {
+      return use(ptr);
+    } finally {
+      this.free(ptr, len);
+    }
+  }
+
+  /** Allocates a sized struct (its leading `size` field set), as GHOSTTY_INIT_SIZED does. */
+  withSized<T>(type: string, use: (ptr: number) => T): T {
+    const size = this.sizeOf(type);
+    return this.with(size, (ptr) => {
+      this.view().setUint32(ptr, size, true);
+      return use(ptr);
+    });
+  }
+
+  withBytes<T>(data: Uint8Array, use: (ptr: number, len: number) => T): T {
+    if (data.length === 0) return use(0, 0);
+    return this.with(data.length, (ptr) => {
+      this.bytes().set(data, ptr);
+      return use(ptr, data.length);
+    });
+  }
+
+  /** Runs a constructor that writes an opaque handle into an out slot and returns the handle. */
+  newHandle(name: string, construct: (slot: number) => number): number {
+    const slot = this.call('ghostty_wasm_alloc_opaque');
+    if (slot === 0) throw new GhosttyCallError('ghostty_wasm_alloc_opaque', -1);
+    try {
+      const result = construct(slot);
+      if (result !== GHOSTTY_SUCCESS) throw new GhosttyCallError(name, result);
+      return this.call('ghostty_wasm_take_opaque', slot);
+    } finally {
+      this.call('ghostty_wasm_free_opaque', slot);
+    }
+  }
+
+  string(ptr: number, len: number): string {
+    if (len === 0) return '';
+    return new TextDecoder().decode(this.bytes().slice(ptr, ptr + len));
+  }
+
+  /** Registers a JavaScript callback in the function table and returns its index (the C function pointer). */
+  addCallback(
+    params: ('i32' | 'i64')[],
+    result: 'i32' | null,
+    fn: (...args: any[]) => unknown
+  ): number {
+    const module = new WebAssembly.Module(trampolineBytes(params, result));
+    const instance = new WebAssembly.Instance(module, { e: { f: fn } });
+    const table = this.exports.__indirect_function_table;
+    const index = this.freeSlots.pop() ?? table.grow(1);
+    table.set(index, instance.exports.f as any);
+    return index;
+  }
+
+  removeCallback(index: number): void {
+    this.exports.__indirect_function_table.set(index, null);
+    this.freeSlots.push(index);
+  }
+}

package/lib/addons/fit.ts

@@ -0,0 +1,242 @@
+/**
+ * FitAddon - Auto-resize terminal to fit container
+ *
+ * Provides automatic terminal resizing to fit its container element.
+ * Compatible with xterm.js FitAddon API.
+ *
+ * Usage:
+ * ```typescript
+ * const fitAddon = new FitAddon();
+ * term.loadAddon(fitAddon);
+ * fitAddon.fit();              // Manual fit
+ * fitAddon.observeResize();    // Auto-fit on resize
+ * ```
+ */
+
+import type { ITerminalAddon, ITerminalCore } from '../interfaces';
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+const MINIMUM_COLS = 2;
+const MINIMUM_ROWS = 1;
+const DEFAULT_SCROLLBAR_WIDTH = 15; // Reserve space for future scrollback scrollbar
+const RESIZE_DEBOUNCE_MS = 100; // Debounce time for ResizeObserver
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface ITerminalDimensions {
+  cols: number;
+  rows: number;
+}
+
+// ============================================================================
+// FitAddon Class
+// ============================================================================
+
+export class FitAddon implements ITerminalAddon {
+  private _terminal?: ITerminalCore;
+  private _resizeObserver?: ResizeObserver;
+  private _resizeDebounceTimer?: ReturnType<typeof setTimeout>;
+  private _lastCols?: number;
+  private _lastRows?: number;
+  private _isResizing: boolean = false;
+
+  /**
+   * Activate the addon (called by Terminal.loadAddon)
+   */
+  public activate(terminal: ITerminalCore): void {
+    this._terminal = terminal;
+  }
+
+  /**
+   * Dispose the addon and clean up resources
+   */
+  public dispose(): void {
+    // Disconnect ResizeObserver
+    if (this._resizeObserver) {
+      this._resizeObserver.disconnect();
+      this._resizeObserver = undefined;
+    }
+
+    // Clear pending debounce timer
+    if (this._resizeDebounceTimer) {
+      clearTimeout(this._resizeDebounceTimer);
+      this._resizeDebounceTimer = undefined;
+    }
+
+    // Clear stored dimensions
+    this._lastCols = undefined;
+    this._lastRows = undefined;
+
+    this._terminal = undefined;
+  }
+
+  /**
+   * Fit the terminal to its container
+   *
+   * Calculates optimal dimensions and resizes the terminal.
+   * Does nothing if dimensions cannot be calculated or haven't changed.
+   */
+  public fit(): void {
+    // Prevent re-entrant calls during resize
+    if (this._isResizing) {
+      return;
+    }
+
+    const dims = this.proposeDimensions();
+    if (!dims || !this._terminal) {
+      return;
+    }
+
+    // Access terminal to check current dimensions
+    const terminal = this._terminal as any;
+    const currentCols = terminal.cols;
+    const currentRows = terminal.rows;
+
+    // Check if dimensions actually changed (prevent feedback loops)
+    // Compare against BOTH proposed dimensions AND current terminal dimensions
+    if (
+      (dims.cols === this._lastCols && dims.rows === this._lastRows) ||
+      (dims.cols === currentCols && dims.rows === currentRows)
+    ) {
+      return;
+    }
+
+    // Store dimensions before resize
+    this._lastCols = dims.cols;
+    this._lastRows = dims.rows;
+
+    // Set flag to prevent re-entrant calls
+    this._isResizing = true;
+
+    try {
+      // Resize terminal
+      if (terminal.resize && typeof terminal.resize === 'function') {
+        terminal.resize(dims.cols, dims.rows);
+      }
+    } finally {
+      // Clear flag after a short delay to allow DOM to settle
+      setTimeout(() => {
+        this._isResizing = false;
+      }, 50);
+    }
+  }
+
+  /**
+   * Propose dimensions to fit the terminal to its container
+   *
+   * Calculates cols and rows based on:
+   * - Terminal container element dimensions (clientWidth/Height)
+   * - Terminal element padding
+   * - Font metrics (character cell size)
+   * - Scrollbar width reservation
+   *
+   * @returns Proposed dimensions or undefined if cannot calculate
+   */
+  public proposeDimensions(): ITerminalDimensions | undefined {
+    // Need terminal and its DOM element
+    if (!this._terminal?.element) {
+      return undefined;
+    }
+
+    // Access terminal internals to get renderer
+    const terminal = this._terminal as any;
+    const renderer = terminal.renderer;
+
+    if (!renderer || typeof renderer.getMetrics !== 'function') {
+      return undefined;
+    }
+
+    // Get font metrics from renderer
+    const metrics = renderer.getMetrics();
+    if (!metrics || metrics.width === 0 || metrics.height === 0) {
+      return undefined;
+    }
+
+    // Get terminal element (container) dimensions
+    // Use clientWidth/clientHeight to get the INSIDE dimensions (excluding padding)
+    const terminalElement = this._terminal.element;
+
+    // Check if we have clientWidth/clientHeight (DOM element required)
+    if (typeof terminalElement.clientWidth === 'undefined') {
+      return undefined;
+    }
+
+    const elementStyle = window.getComputedStyle(terminalElement);
+
+    // Get the actual content area (inside padding)
+    const paddingTop = Number.parseInt(elementStyle.getPropertyValue('padding-top')) || 0;
+    const paddingBottom = Number.parseInt(elementStyle.getPropertyValue('padding-bottom')) || 0;
+    const paddingLeft = Number.parseInt(elementStyle.getPropertyValue('padding-left')) || 0;
+    const paddingRight = Number.parseInt(elementStyle.getPropertyValue('padding-right')) || 0;
+
+    // Use clientWidth/clientHeight which gives us the inside dimensions
+    // This is stable and doesn't grow with content
+    const containerWidth = terminalElement.clientWidth;
+    const containerHeight = terminalElement.clientHeight;
+
+    // Check for invalid dimensions
+    if (containerWidth === 0 || containerHeight === 0) {
+      return undefined;
+    }
+
+    // Calculate available space (subtract padding since clientWidth includes padding)
+    const availableWidth = containerWidth - paddingLeft - paddingRight - DEFAULT_SCROLLBAR_WIDTH;
+    const availableHeight = containerHeight - paddingTop - paddingBottom;
+
+    // Calculate dimensions (enforce minimums)
+    const cols = Math.max(MINIMUM_COLS, Math.floor(availableWidth / metrics.width));
+    const rows = Math.max(MINIMUM_ROWS, Math.floor(availableHeight / metrics.height));
+
+    return { cols, rows };
+  }
+
+  /**
+   * Observe the terminal's container for resize events
+   *
+   * Sets up a ResizeObserver to automatically call fit() when the
+   * container size changes. Resize events are debounced to avoid
+   * excessive calls during window drag operations.
+   *
+   * Call dispose() to stop observing.
+   */
+  public observeResize(): void {
+    if (!this._terminal?.element) {
+      return;
+    }
+
+    // Already observing
+    if (this._resizeObserver) {
+      return;
+    }
+
+    // Create ResizeObserver that watches for external size changes
+    this._resizeObserver = new ResizeObserver((entries) => {
+      // Ignore resize events while we're actively resizing
+      if (this._isResizing) {
+        return;
+      }
+
+      // Only trigger if the observed element's content rect changed
+      const entry = entries[0];
+      if (!entry) return;
+
+      // Debounce resize events
+      if (this._resizeDebounceTimer) {
+        clearTimeout(this._resizeDebounceTimer);
+      }
+
+      this._resizeDebounceTimer = setTimeout(() => {
+        this.fit();
+      }, RESIZE_DEBOUNCE_MS);
+    });
+
+    // Observe the terminal element itself (the container we want to fit into)
+    // This gives us stable resize events when the CONTAINER changes, not when our canvas changes
+    this._resizeObserver.observe(this._terminal.element);
+  }
+}