@cueloop/client 0.1.0-alpha.0 → 0.1.0-alpha.100

package/src/terminal/ansi-screen.ts

@@ -0,0 +1,72 @@
+/** Interpret an absolute-positioned ANSI byte stream (cursor moves plus printed text) into a grid of rows. */
+
+const CSI = "\x1b[";
+
+export function ansiScreenToLines(ansi: string, cols: number, rows: number): string[] {
+  const grid: string[][] = Array.from({ length: rows }, () =>
+    Array.from({ length: cols }, () => " "),
+  );
+  let row = 0;
+  let column = 0;
+  let index = 0;
+
+  const put = (character: string): void => {
+    if (row >= 0 && row < rows && column >= 0 && column < cols) grid[row]![column] = character;
+    column += 1;
+  };
+
+  while (index < ansi.length) {
+    const character = ansi[index]!;
+
+    if (character === "\x1b") {
+      index = consumeEscape(ansi, index, (nextRow, nextColumn) => {
+        if (nextRow === "clear") {
+          for (const line of grid) line.fill(" ");
+          row = 0;
+          column = 0;
+        } else {
+          row = nextRow;
+          column = nextColumn;
+        }
+      });
+      continue;
+    }
+    if (character === "\n") {
+      row += 1;
+      column = 0;
+    } else if (character === "\r") {
+      column = 0;
+    } else {
+      put(character);
+    }
+    index += 1;
+  }
+
+  return grid.map((line) => line.join("").replace(/\s+$/, ""));
+}
+
+type EscapeEffect = (row: number | "clear", column: number) => void;
+
+function consumeEscape(ansi: string, start: number, apply: EscapeEffect): number {
+  if (ansi[start + 1] === "]") {
+    const bell = ansi.indexOf("\x07", start);
+
+    return bell === -1 ? ansi.length : bell + 1;
+  }
+  if (ansi.slice(start, start + CSI.length) !== CSI) return start + 1;
+  let index = start + CSI.length;
+
+  while (index < ansi.length && !/[A-Za-z]/.test(ansi[index]!)) index += 1;
+  const final = ansi[index];
+  const parameters = ansi.slice(start + CSI.length, index);
+
+  if (final === "H" || final === "f") {
+    const [rowParameter = "1", columnParameter = "1"] = parameters.split(";");
+
+    apply(Math.max(0, Number(rowParameter) - 1), Math.max(0, Number(columnParameter) - 1));
+  } else if (final === "J" && parameters === "2") {
+    apply("clear", 0);
+  }
+
+  return index + 1;
+}

package/src/terminal/components/AnsiScreen.stories.tsx

@@ -0,0 +1,12 @@
+import React from "react";
+import type { Story, StoryMeta } from "../../stories/story";
+import { AnsiScreen } from "./AnsiScreen";
+
+export const meta: StoryMeta = { title: "Primitives/AnsiScreen" };
+
+const POSITIONED = "\x1b[2;4HHello from\x1b[4;6Hraw, positioned ANSI";
+
+export const Positioned: Story = {
+  render: () => <AnsiScreen ansi={POSITIONED} cols={40} rows={6} />,
+  size: { width: 44, height: 8 },
+};

package/src/terminal/components/AnsiScreen.tsx

@@ -0,0 +1,28 @@
+/** Paints a raw ANSI screen (cursor-positioned text) as a terminal would, for previewing SSH surfaces. */
+
+import React from "react";
+import type { Theme } from "../../appearance/theme";
+import { ansiScreenToLines } from "../ansi-screen";
+import { useComponentTheme } from "../../appearance/components/theme-context";
+
+export interface AnsiScreenProps {
+  ansi: string;
+  cols: number;
+  rows: number;
+  theme?: Theme;
+}
+
+export function AnsiScreen({ ansi, cols, rows, theme }: AnsiScreenProps): React.ReactNode {
+  const tokens = useComponentTheme(theme);
+  const lines = ansiScreenToLines(ansi, cols, rows);
+
+  return (
+    <box style={{ flexDirection: "column" }}>
+      {lines.map((line, index) => (
+        <text key={index} fg={tokens.text} selectable={false} style={{ wrapMode: "none" }}>
+          {line === "" ? " " : line}
+        </text>
+      ))}
+    </box>
+  );
+}

package/src/terminal/components/terminal-pane.test.tsx

@@ -0,0 +1,40 @@
+/** The embedded terminal renderable runs a real PTY child through Ghostty's VT and paints its screen; a live `printf` child must show up in the OpenTUI frame. Skipped where no prebuilt libghostty-vt ships for the platform. */
+
+import { describe, expect, test } from "bun:test";
+import React from "react";
+import { testRender } from "@opentui/react/test-utils";
+import { waitForText } from "../../testing/test-support";
+import {
+  embeddedTerminalAvailable,
+  registerTerminalPane,
+  TerminalPaneRenderable,
+} from "./terminal-pane";
+
+registerTerminalPane();
+
+describe("TerminalPaneRenderable", () => {
+  test.skipIf(!embeddedTerminalAvailable())(
+    "paints a live child process's output into the box",
+    async () => {
+      // Arrange / Act - a child that prints a known line
+      const setup = await testRender(
+        React.createElement("terminalPane", {
+          command: "/bin/sh",
+          args: ["-c", "printf 'HELLO-EMBED\\n'; sleep 5"],
+          style: { width: 40, height: 6 },
+        }),
+        { width: 40, height: 6 },
+      );
+
+      // Assert - the child's output reaches the painted frame via Ghostty
+      await waitForText(setup, "HELLO-EMBED");
+      setup.renderer.destroy();
+    },
+  );
+
+  test("exposes availability + the renderable class", () => {
+    // Assert - the module loads and reports platform support honestly
+    expect([true, false]).toContain(embeddedTerminalAvailable());
+    expect(TerminalPaneRenderable).toBeDefined();
+  });
+});

package/src/terminal/components/terminal-pane.ts

@@ -0,0 +1,196 @@
+/**
+ * An OpenTUI renderable that runs a real child process (a shell, cc, pi, codex)
+ * on a PTY and paints its live screen into the box - the terminal-in-the-rail
+ * primitive. It wires the forkpty shim (child + tty, ../pty) to a Ghostty VT emulator
+ * (ghostty-terminal.ts) and blits the emulator's cell grid every frame via
+ * OptimizedBuffer.setCell. Register once with `registerTerminalPane`, then use
+ * `<terminalPane command="claude" ... />` in the OpenTUI React tree.
+ */
+
+import { Renderable, RGBA, createTextAttributes, type RenderContext } from "@opentui/core";
+import type { OptimizedBuffer } from "@opentui/core";
+import type { RenderableOptions } from "@opentui/core";
+import { extend } from "@opentui/react";
+import { spawn, ptyAvailable, type IPty } from "../pty";
+import {
+  loadGhosttyTerminals,
+  type GhosttyColor,
+  type GhosttyTerminal,
+  type GhosttyTerminalFactory,
+} from "../ghostty-terminal";
+
+/** One shared VT library load; null when this platform ships no prebuilt dylib. */
+let ghosttyFactory: GhosttyTerminalFactory | null | undefined;
+
+function factory(): GhosttyTerminalFactory | null {
+  if (ghosttyFactory === undefined) ghosttyFactory = loadGhosttyTerminals();
+
+  return ghosttyFactory;
+}
+
+/** Whether the embedded terminal can run here: both native shims ship for this
+ *  platform (the Ghostty VT renderer and the forkpty PTY). */
+export function embeddedTerminalAvailable(): boolean {
+  return factory() !== null && ptyAvailable();
+}
+
+/** Props for `<terminalPane>`: the child to run plus its cwd/env and a plan-context seed. */
+export interface TerminalPaneOptions extends RenderableOptions {
+  command?: string;
+  args?: string[];
+  cwd?: string;
+  env?: Record<string, string>;
+  seedText?: string;
+  onExit?: (exitCode: number) => void;
+}
+
+function terminalEnvironment(env: NodeJS.ProcessEnv) {
+  return Object.fromEntries(
+    Object.entries(env).filter((entry): entry is [string, string] => entry[1] !== undefined),
+  );
+}
+
+const encoder = new TextEncoder();
+const DEFAULT_FG = RGBA.fromInts(208, 208, 208, 255);
+const TRANSPARENT = RGBA.fromValues(0, 0, 0, 0);
+/** Glyph color under the block cursor (dark ink on the light cursor block). */
+const CURSOR_INK = RGBA.fromInts(20, 20, 24, 255);
+
+/** Runs a PTY child and paints its Ghostty-rendered screen into this box. */
+export class TerminalPaneRenderable extends Renderable {
+  private pty: IPty | null = null;
+  private vt: GhosttyTerminal | null = null;
+  private cols = 0;
+  private rows = 0;
+  // The seed is held until the child's first output, so it lands in a ready
+  // prompt rather than racing the harness's startup (readline/TUI not up yet).
+  private pendingSeed: string | undefined;
+  private readonly opts: TerminalPaneOptions;
+
+  constructor(ctx: RenderContext, options: TerminalPaneOptions) {
+    super(ctx, options);
+    this.opts = options;
+    this.focusable = true;
+  }
+
+  /** Start the child + emulator once real layout dimensions are known. */
+  private start(cols: number, rows: number): void {
+    const terminals = factory();
+
+    if (!terminals) return;
+    const vt = terminals.create(cols, rows);
+
+    if (!vt) return; // no emulator, no visible screen - do not spawn a blind child
+    this.vt = vt;
+    this.cols = cols;
+    this.rows = rows;
+    this.pendingSeed = this.opts.seedText;
+    this.pty = spawn(this.opts.command ?? process.env.SHELL ?? "/bin/sh", this.opts.args ?? [], {
+      name: "xterm-256color",
+      cols,
+      rows,
+      cwd: this.opts.cwd ?? process.cwd(),
+      env: this.opts.env ?? terminalEnvironment(process.env),
+    });
+    this.pty.onData((data) => {
+      // the shim streams a UTF-8-decoded string (split multibyte is handled); a
+      // rare non-UTF-8 byte arrives as U+FFFD - acceptable for agent TUIs.
+      this.vt?.write(encoder.encode(data));
+      if (this.pendingSeed !== undefined) {
+        this.pty?.write(this.pendingSeed);
+        this.pendingSeed = undefined;
+      }
+      this.requestRender();
+    });
+    this.pty.onExit(({ exitCode }) => this.opts.onExit?.(exitCode));
+  }
+
+  /** Send raw bytes to the child (a key's escape sequence, or pasted text). */
+  write(data: string): void {
+    this.pty?.write(data);
+  }
+
+  protected onResize(width: number, height: number): void {
+    if (width <= 0 || height <= 0) return;
+    if (!this.pty) {
+      this.start(width, height);
+
+      return;
+    }
+    if (width === this.cols && height === this.rows) return;
+    this.cols = width;
+    this.rows = height;
+    this.vt?.resize(width, height);
+    this.pty.resize(width, height);
+  }
+
+  protected renderSelf(buffer: OptimizedBuffer): void {
+    if (!this.vt) return;
+    for (let y = 0; y < this.height; y++) {
+      for (let x = 0; x < this.width; x++) {
+        const cell = this.vt.readCell(x, y);
+
+        // Skip an empty normal-width cell; the buffer already starts blank.
+        if (cell && cell.width === 0 && cell.codepoint === 0) continue;
+        const char = cell && cell.codepoint ? String.fromCodePoint(cell.codepoint) : " ";
+        let fg = cell ? resolveColor(cell.fg, DEFAULT_FG) : DEFAULT_FG;
+        let bg = cell ? resolveColor(cell.bg, TRANSPARENT) : TRANSPARENT;
+
+        if (cell?.inverse) [fg, bg] = [bg, fg];
+        const attributes = cell
+          ? createTextAttributes({
+              bold: cell.bold,
+              italic: cell.italic,
+              underline: cell.underline,
+              dim: cell.faint,
+              strikethrough: cell.strikethrough,
+            })
+          : 0;
+
+        buffer.setCell(this.x + x, this.y + y, char, fg, bg, attributes);
+      }
+    }
+    // cursor is active-area coords; equal to viewport at the bottom (the live
+    // typing case). It can drift if the child scrolls the viewport back.
+    const cursor = this.vt.readCursor();
+
+    if (cursor.visible && cursor.x < this.width && cursor.y < this.height) {
+      const under = this.vt.readCell(cursor.x, cursor.y);
+      const char = under && under.codepoint ? String.fromCodePoint(under.codepoint) : " ";
+
+      // a block cursor: paint the cell with fg/bg swapped
+      buffer.setCell(this.x + cursor.x, this.y + cursor.y, char, CURSOR_INK, DEFAULT_FG, 0);
+    }
+  }
+
+  /** Kill the child and free the VT. Idempotent - the detach path calls this
+   *  directly because the React reconciler removes a child without destroying it. */
+  shutdown(): void {
+    this.pty?.kill();
+    this.vt?.free();
+    this.pty = null;
+    this.vt = null;
+  }
+
+  protected destroySelf(): void {
+    this.shutdown();
+    super.destroySelf();
+  }
+}
+
+/** Map a Ghostty cell color to an OpenTUI RGBA, using `fallback` for the terminal default. */
+function resolveColor(color: GhosttyColor, fallback: RGBA): RGBA {
+  if (color.kind === "rgb") return RGBA.fromInts(color.r, color.g, color.b, 255);
+  if (color.kind === "palette") return RGBA.fromIndex(color.index);
+
+  return fallback;
+}
+
+let registered = false;
+
+/** Register `<terminalPane>` with the OpenTUI React reconciler (idempotent). */
+export function registerTerminalPane(): void {
+  if (registered) return;
+  registered = true;
+  extend({ terminalPane: TerminalPaneRenderable });
+}

package/src/terminal/ghostty-terminal.test.ts

@@ -0,0 +1,85 @@
+/** The libghostty-vt FFI wrapper round-trips VT: fed bytes come back as decoded cells with colors and attributes. Skipped where no prebuilt dylib ships for the platform. */
+
+import { describe, expect, test } from "bun:test";
+import { loadGhosttyTerminals } from "./ghostty-terminal";
+
+const factory = loadGhosttyTerminals();
+
+describe("ghostty-terminal FFI", () => {
+  test("reports platform support without throwing", () => {
+    // Assert - null on unsupported platforms, a factory where a dylib ships
+    expect(factory === null || factory.create !== undefined).toBe(true);
+  });
+
+  test.skipIf(!factory)("writes VT bytes and reads back decoded cells", () => {
+    // Arrange
+    const term = factory!.create(80, 24)!;
+
+    expect(term).not.toBeNull();
+
+    // Act - plain text then bold + palette-green "GO"
+    term.write(new TextEncoder().encode("hi\x1b[1;32mGO\x1b[0m"));
+    const cells = [0, 1, 2, 3].map((x) => term.readCell(x, 0));
+
+    // Assert - glyphs decode, the row reads as text, and the green run is bold on ANSI palette index 2
+    expect(
+      cells.map((c) => (c?.codepoint ? String.fromCodePoint(c.codepoint) : " ")).join(""),
+    ).toBe("hiGO");
+    expect(term.rowText(0, 80)).toBe("hiGO");
+    expect(cells[2]!.bold).toBe(true);
+    expect(cells[2]!.fg).toEqual({ kind: "palette", index: 2 });
+    term.free();
+  });
+
+  test.skipIf(!factory)("tracks the cursor position as text is written", () => {
+    // Arrange
+    const term = factory!.create(80, 24)!;
+
+    // Act
+    term.write(new TextEncoder().encode("abc"));
+
+    // Assert - cursor advanced past the three glyphs on row 0
+    const cursor = term.readCursor();
+
+    expect(cursor.y).toBe(0);
+    expect(cursor.x).toBe(3);
+    term.free();
+  });
+
+  test.skipIf(!factory)(
+    "preserves the native screen contract across resize and styled text",
+    () => {
+      // Arrange
+      const term = factory!.create(8, 2)!;
+
+      // Act - resize first, then write RGB colors, every supported style, and a wide glyph
+      term.resize(6, 3);
+      term.write(
+        new TextEncoder().encode(
+          "\x1b[38;2;12;34;56;48;2;78;90;123;1;3;4;7;9mA\x1b[0m\x1b[2mF\x1b[0m\u754c",
+        ),
+      );
+
+      // Assert - the flat native ABI retains cell data and rejects coordinates outside the viewport
+      expect(term.readCell(0, 0)).toEqual({
+        codepoint: 0x41,
+        fg: { kind: "rgb", r: 12, g: 34, b: 56 },
+        bg: { kind: "rgb", r: 78, g: 90, b: 123 },
+        width: 0,
+        bold: true,
+        italic: true,
+        underline: true,
+        inverse: true,
+        faint: false,
+        strikethrough: true,
+      });
+      expect(term.readCell(1, 0)?.faint).toBe(true);
+      expect(term.readCell(2, 0)?.codepoint).toBe("\u754c".codePointAt(0));
+      expect(term.readCell(2, 0)?.width).toBe(1);
+      expect(term.readCell(3, 0)?.width).toBe(2);
+      expect(term.readCell(6, 0)).toBeNull();
+      expect(term.readCell(0, 3)).toBeNull();
+      term.free();
+    },
+  );
+});

package/src/terminal/ghostty-terminal.ts

@@ -0,0 +1,197 @@
+/**
+ * A live in-process terminal emulator backed by Ghostty's VT core (libghostty-vt)
+ * through a flat FFI shim (native/src/shim.zig). Feed it a child process's PTY
+ * output with `write`, then read the rendered screen cell-by-cell with `readCell`
+ * to paint it anywhere - this is what lets a real `cc`/shell render inside an
+ * OpenTUI box. Load with `loadGhosttyTerminals`, which returns null when no
+ * prebuilt dylib exists for this platform (callers fall back to a herdr split).
+ */
+
+import { dlopen, FFIType, ptr } from "bun:ffi";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+/** How a cell's color arrived from Ghostty: the terminal default, an ANSI palette index, or true RGB. */
+export type GhosttyColor =
+  | { kind: "default" }
+  | { kind: "palette"; index: number }
+  | { kind: "rgb"; r: number; g: number; b: number };
+
+/** The cursor's viewport position and whether it should be drawn. */
+export interface GhosttyCursor {
+  x: number;
+  y: number;
+  visible: boolean;
+}
+
+/** One decoded screen cell: its glyph, colors, cell width, and text decorations. */
+export interface GhosttyCell {
+  codepoint: number;
+  fg: GhosttyColor;
+  bg: GhosttyColor;
+  width: number;
+  bold: boolean;
+  italic: boolean;
+  underline: boolean;
+  inverse: boolean;
+  faint: boolean;
+  strikethrough: boolean;
+}
+
+const CVT_SYMBOLS = {
+  cvt_new: { args: [FFIType.u16, FFIType.u16], returns: FFIType.ptr },
+  cvt_free: { args: [FFIType.ptr], returns: FFIType.void },
+  cvt_write: { args: [FFIType.ptr, FFIType.ptr, FFIType.u64], returns: FFIType.void },
+  cvt_resize: { args: [FFIType.ptr, FFIType.u16, FFIType.u16], returns: FFIType.void },
+  cvt_cell: { args: [FFIType.ptr, FFIType.u16, FFIType.u32, FFIType.ptr], returns: FFIType.i32 },
+  cvt_cursor: { args: [FFIType.ptr, FFIType.ptr], returns: FFIType.void },
+} as const;
+
+type CvtLib = ReturnType<typeof dlopen<typeof CVT_SYMBOLS>>["symbols"];
+
+/** The prebuilt shim dylib for this platform, or null when none ships for it. */
+function nativeLibraryPath(): string | null {
+  const suffix = process.platform === "darwin" ? "dylib" : "so";
+  const dir = `${process.platform}-${process.arch}`;
+  const path = join(import.meta.dir, "..", "..", "native", dir, `libcueloopvt.${suffix}`);
+
+  return existsSync(path) ? path : null;
+}
+
+/** One shared load of the VT library; null when no dylib ships or it failed to load. */
+let ghosttyFactory: GhosttyTerminalFactory | null | undefined;
+
+/**
+ * Open the Ghostty VT library for this platform, or return null when the prebuilt
+ * dylib is missing (the caller degrades to a herdr split instead of embedding).
+ * The library is opened once per process; later calls return the same factory.
+ */
+export function loadGhosttyTerminals(): GhosttyTerminalFactory | null {
+  if (ghosttyFactory !== undefined) return ghosttyFactory;
+  const path = nativeLibraryPath();
+
+  if (!path) return (ghosttyFactory = null);
+  try {
+    const lib = dlopen(path, CVT_SYMBOLS);
+
+    ghosttyFactory = new GhosttyTerminalFactory(lib.symbols);
+  } catch (error) {
+    // The file exists but failed to load (bad arch, missing symbol) - a real
+    // fault, not the expected no-prebuilt case; surface it, then degrade.
+    console.error(`cueloop: failed to load ${path}:`, error);
+    ghosttyFactory = null;
+  }
+
+  return ghosttyFactory;
+}
+
+/** Creates `GhosttyTerminal`s that share one loaded copy of the VT library. */
+export class GhosttyTerminalFactory {
+  constructor(private readonly lib: CvtLib) {}
+  /** A fresh terminal sized to cols x rows, or null if allocation failed. */
+  create(cols: number, rows: number): GhosttyTerminal | null {
+    const handle = this.lib.cvt_new(cols, rows);
+
+    return handle ? new GhosttyTerminal(this.lib, handle) : null;
+  }
+}
+
+// The flat CvtCell struct the shim writes: u32 codepoint, fg rgba-ish (4 bytes),
+// bg (4 bytes), u8 width, u8 flags, u16 pad = 16 bytes.
+const CELL_STRUCT_BYTES = 16;
+const FLAG_BOLD = 1;
+const FLAG_ITALIC = 2;
+const FLAG_UNDERLINE = 4;
+const FLAG_INVERSE = 8;
+const FLAG_FAINT = 16;
+const FLAG_STRIKETHROUGH = 32;
+
+/** A live Ghostty terminal: feed PTY bytes, read the screen, resize, free. */
+export class GhosttyTerminal {
+  private readonly out = new Uint8Array(CELL_STRUCT_BYTES);
+  private readonly outView = new DataView(this.out.buffer);
+  private readonly cursorOut = new Uint8Array(8);
+  private freed = false;
+
+  constructor(
+    private readonly lib: CvtLib,
+    private readonly handle: NonNullable<ReturnType<CvtLib["cvt_new"]>>,
+  ) {}
+
+  /** Process a chunk of the child's PTY output into the screen state. */
+  write(bytes: Uint8Array): void {
+    if (this.freed || bytes.length === 0) return;
+    this.lib.cvt_write(this.handle, ptr(bytes), BigInt(bytes.length));
+  }
+
+  /** Resize the screen (and the child's tty, via the caller) to cols x rows. */
+  resize(cols: number, rows: number): void {
+    if (this.freed) return;
+    this.lib.cvt_resize(this.handle, cols, rows);
+  }
+
+  /** The rendered cell at viewport (x, y), or null when out of range. */
+  readCell(x: number, y: number): GhosttyCell | null {
+    if (this.freed) return null;
+    if (this.lib.cvt_cell(this.handle, x, y, ptr(this.out)) !== 0) return null;
+    const flags = this.out[13]!;
+
+    return {
+      codepoint: this.outView.getUint32(0, true),
+      fg: decodeColor(this.out[7]!, this.out[4]!, this.out[5]!, this.out[6]!),
+      bg: decodeColor(this.out[11]!, this.out[8]!, this.out[9]!, this.out[10]!),
+      width: this.out[12]!,
+      bold: (flags & FLAG_BOLD) !== 0,
+      italic: (flags & FLAG_ITALIC) !== 0,
+      underline: (flags & FLAG_UNDERLINE) !== 0,
+      inverse: (flags & FLAG_INVERSE) !== 0,
+      faint: (flags & FLAG_FAINT) !== 0,
+      strikethrough: (flags & FLAG_STRIKETHROUGH) !== 0,
+    };
+  }
+
+  /**
+   * Row `y` as text: blank cells read as spaces, the trailing half of a wide
+   * glyph is skipped, and trailing spaces are trimmed.
+   */
+  rowText(y: number, cols: number): string {
+    let line = "";
+
+    for (let x = 0; x < cols; x++) {
+      const cell = this.readCell(x, y);
+
+      if (cell === null || cell.width === 2) continue;
+      line += cell.codepoint === 0 ? " " : String.fromCodePoint(cell.codepoint);
+    }
+
+    return line.trimEnd();
+  }
+
+  /** The cursor's current viewport position and visibility. */
+  readCursor(): GhosttyCursor {
+    if (this.freed) return { x: 0, y: 0, visible: false };
+    this.lib.cvt_cursor(this.handle, ptr(this.cursorOut));
+    const view = new DataView(this.cursorOut.buffer);
+
+    return {
+      x: view.getUint16(0, true),
+      y: view.getUint16(2, true),
+      visible: this.cursorOut[4] === 1,
+    };
+  }
+
+  /** Release the terminal; further calls are no-ops. Call once on teardown. */
+  free(): void {
+    if (this.freed) return;
+    this.freed = true;
+    this.lib.cvt_free(this.handle);
+  }
+}
+
+/** Decode the shim's (kind, r, g, b) color triple; palette carries its index in r. */
+function decodeColor(kind: number, r: number, g: number, b: number): GhosttyColor {
+  if (kind === 2) return { kind: "rgb", r, g, b };
+  if (kind === 1) return { kind: "palette", index: r };
+
+  return { kind: "default" };
+}