@cueloop/client 0.1.0-alpha.40 → 0.1.0-alpha.41

package/native/build.sh

@@ -0,0 +1,56 @@
+#!/bin/sh
+# Rebuild libcueloopvt.dylib: libghostty-vt (Ghostty's VT core) statically linked
+# behind the flat FFI shim in src/shim.c. Pinned to a Ghostty commit + Zig 0.16.0.
+# Output lands in native/<os>-<arch>/libcueloopvt.dylib. Requires curl, git, clang.
+set -eu
+
+GHOSTTY_COMMIT="5834a0e3df621802e9578e4562d88b0c2ad4ada8"
+ZIG_VERSION="0.16.0"
+
+here="$(cd "$(dirname "$0")" && pwd)"
+work="${TMPDIR:-/tmp}/cueloop-libghostty-build"
+mkdir -p "$work"
+cd "$work"
+
+# host triple for the prebuilt dir + zig download
+arch="$(uname -m)"; os="$(uname -s | tr '[:upper:]' '[:lower:]')"
+case "$os" in darwin) zig_os="macos"; dylib="libcueloopvt.dylib";; linux) zig_os="linux"; dylib="libcueloopvt.so";; *) echo "unsupported os $os" >&2; exit 1;; esac
+outdir="$here/${os}-${arch}"
+
+if [ ! -x "zig-$arch-$zig_os-$ZIG_VERSION/zig" ]; then
+  echo "== fetching zig $ZIG_VERSION =="
+  curl -sSL -o zig.tar.xz "https://ziglang.org/download/$ZIG_VERSION/zig-$arch-$zig_os-$ZIG_VERSION.tar.xz"
+  tar -xf zig.tar.xz
+fi
+zig="$work/zig-$arch-$zig_os-$ZIG_VERSION/zig"
+
+if [ ! -d ghostty ]; then
+  echo "== cloning ghostty @ $GHOSTTY_COMMIT =="
+  mkdir ghostty && cd ghostty && git init -q
+  git remote add origin https://github.com/ghostty-org/ghostty.git
+  git fetch -q --depth 1 origin "$GHOSTTY_COMMIT"
+  git checkout -q FETCH_HEAD
+  cd ..
+fi
+
+echo "== building libghostty-vt (ReleaseFast) =="
+cd ghostty
+# The final xcframework packaging step can fail while the .a we need is produced,
+# so tolerate a non-zero exit here but assert the static lib exists below.
+ZIG_GLOBAL_CACHE_DIR="$work/zig-gcache" ZIG_LOCAL_CACHE_DIR="$work/zig-lcache" \
+  "$zig" build -Demit-lib-vt -Doptimize=ReleaseFast --prefix "$work/vt-install" || true
+cd ..
+staticlib="$work/vt-install/lib/libghostty-vt.a"
+[ -f "$staticlib" ] || { echo "build failed: $staticlib not produced" >&2; exit 1; }
+
+echo "== linking shim -> $outdir/$dylib =="
+mkdir -p "$outdir"
+if [ "$os" = "darwin" ]; then
+  clang -O2 -dynamiclib -o "$outdir/$dylib" "$here/src/shim.c" \
+    -I"$work/vt-install/include" "$staticlib" \
+    -framework CoreFoundation -framework CoreText -framework CoreGraphics
+else
+  clang -O2 -shared -fPIC -o "$outdir/$dylib" "$here/src/shim.c" \
+    -I"$work/vt-install/include" "$staticlib" -lm -lpthread
+fi
+echo "== done: $outdir/$dylib =="

package/native/src/shim.c

@@ -0,0 +1,107 @@
+// Flat, FFI-trivial wrapper over libghostty-vt: hides the allocator vtable, the
+// by-value GhosttyPoint (which bun:ffi cannot pass), and the packed-cell decode,
+// exposing exactly what an OpenTUI paint loop needs - new/write/resize/cell/free.
+#include <stdint.h>
+#include <stddef.h>
+#include <stdbool.h>
+#include <string.h>
+#include "ghostty/vt/types.h"
+#include "ghostty/vt/allocator.h"
+#include "ghostty/vt/terminal.h"
+#include "ghostty/vt/point.h"
+#include "ghostty/vt/grid_ref.h"
+#include "ghostty/vt/screen.h"
+#include "ghostty/vt/style.h"
+#include "ghostty/vt/color.h"
+
+typedef struct {
+  uint32_t codepoint;    // 0 = blank
+  uint8_t fg_r, fg_g, fg_b, fg_kind;  // kind: 0 default, 1 palette (index in fg_r), 2 rgb
+  uint8_t bg_r, bg_g, bg_b, bg_kind;
+  uint8_t width;         // 0 (wide trailing), 1, 2
+  uint8_t flags;         // bit0 bold, 1 italic, 2 underline, 3 inverse, 4 faint, 5 strikethrough
+  uint16_t _pad;
+} CvtCell;
+
+void *cvt_new(uint16_t cols, uint16_t rows) {
+  GhosttyTerminal t = NULL;
+  // NULL allocator selects libghostty's default (libc malloc/free when linked).
+  if (ghostty_terminal_new(NULL, &t, cols, rows) != GHOSTTY_SUCCESS) return NULL;
+  return (void *)t;
+}
+
+void cvt_free(void *t) {
+  if (t) ghostty_terminal_free((GhosttyTerminal)t);
+}
+
+void cvt_write(void *t, const uint8_t *data, size_t len) {
+  ghostty_terminal_vt_write((GhosttyTerminal)t, data, len);
+}
+
+void cvt_resize(void *t, uint16_t cols, uint16_t rows) {
+  // cell pixel size is irrelevant to the character grid; pass a nominal 1x1.
+  ghostty_terminal_resize((GhosttyTerminal)t, cols, rows, 1, 1);
+}
+
+// Writes cursor state into out8: [0..1] col (u16), [2..3] row (u16), [4] visible (u8).
+void cvt_cursor(void *t, uint8_t *out8) {
+  uint16_t cx = 0, cy = 0;
+  bool vis = false;
+  ghostty_terminal_get((GhosttyTerminal)t, GHOSTTY_TERMINAL_DATA_CURSOR_X, &cx);
+  ghostty_terminal_get((GhosttyTerminal)t, GHOSTTY_TERMINAL_DATA_CURSOR_Y, &cy);
+  ghostty_terminal_get((GhosttyTerminal)t, GHOSTTY_TERMINAL_DATA_CURSOR_VISIBLE, &vis);
+  memcpy(out8, &cx, 2);
+  memcpy(out8 + 2, &cy, 2);
+  out8[4] = vis ? 1 : 0;
+}
+
+static void decode_color(const GhosttyStyleColor *c, uint8_t *r, uint8_t *g, uint8_t *b,
+                         uint8_t *kind) {
+  if (c->tag == GHOSTTY_STYLE_COLOR_RGB) {
+    *kind = 2;
+    *r = c->value.rgb.r;
+    *g = c->value.rgb.g;
+    *b = c->value.rgb.b;
+  } else if (c->tag == GHOSTTY_STYLE_COLOR_PALETTE) {
+    *kind = 1;
+    *r = (uint8_t)c->value.palette;  // palette index in r; JS maps 0-255 -> RGB
+    *g = 0;
+    *b = 0;
+  } else {
+    *kind = 0;
+  }
+}
+
+// Reads the viewport cell at (x, y). Returns 0 on success, -1 otherwise.
+int cvt_cell(void *t, uint16_t x, uint32_t y, CvtCell *out) {
+  memset(out, 0, sizeof(*out));
+  GhosttyPoint p;
+  p.tag = GHOSTTY_POINT_TAG_VIEWPORT;
+  p.value.coordinate.x = x;
+  p.value.coordinate.y = y;
+  GhosttyGridRef ref;
+  if (ghostty_terminal_grid_ref((GhosttyTerminal)t, p, &ref) != GHOSTTY_SUCCESS) return -1;
+  GhosttyCell cell;
+  if (ghostty_grid_ref_cell(&ref, &cell) != GHOSTTY_SUCCESS) return -1;
+  uint32_t cp = 0;
+  ghostty_cell_get(cell, GHOSTTY_CELL_DATA_CODEPOINT, &cp);
+  out->codepoint = cp;
+  uint32_t wide = 0;
+  ghostty_cell_get(cell, GHOSTTY_CELL_DATA_WIDE, &wide);
+  out->width = (uint8_t)wide;
+  GhosttyStyle st;
+  ghostty_style_default(&st);
+  if (ghostty_grid_ref_style(&ref, &st) == GHOSTTY_SUCCESS) {
+    decode_color(&st.fg_color, &out->fg_r, &out->fg_g, &out->fg_b, &out->fg_kind);
+    decode_color(&st.bg_color, &out->bg_r, &out->bg_g, &out->bg_b, &out->bg_kind);
+    uint8_t f = 0;
+    if (st.bold) f |= 1;
+    if (st.italic) f |= 2;
+    if (st.underline) f |= 4;
+    if (st.inverse) f |= 8;
+    if (st.faint) f |= 16;
+    if (st.strikethrough) f |= 32;
+    out->flags = f;
+  }
+  return 0;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cueloop/client",
-  "version": "0.1.0-alpha.40",
+  "version": "0.1.0-alpha.41",
   "description": "The cueloop review UI: projection renderer, keyboard grammar, review rail",
   "homepage": "https://github.com/mmurakaru/cueloop#readme",
   "bugs": {
@@ -14,6 +14,7 @@
   },
   "files": [
     "src",
+    "native",
     "README.md"
   ],
   "type": "module",
@@ -25,15 +26,16 @@
     "access": "public"
   },
   "dependencies": {
-    "@cueloop/daemon": "0.1.0-alpha.40",
-    "@cueloop/extension-api": "0.1.0-alpha.40",
-    "@cueloop/integration-obsidian": "0.1.0-alpha.40",
-    "@cueloop/schema": "0.1.0-alpha.40",
+    "@cueloop/daemon": "0.1.0-alpha.41",
+    "@cueloop/extension-api": "0.1.0-alpha.41",
+    "@cueloop/integration-obsidian": "0.1.0-alpha.41",
+    "@cueloop/schema": "0.1.0-alpha.41",
     "@opentui/core": "^0.5.2",
     "@opentui/keymap": "0.5.2",
     "@opentui/react": "^0.5.2",
     "@opentui/ssh": "0.5.2",
     "@pierre/diffs": "^1.3.5",
+    "bun-pty": "^0.4.10",
     "diff": "^8",
     "react": "^19.2.0"
   },

package/src/App.tsx

@@ -59,6 +59,7 @@ import { Breadcrumb, type BreadcrumbItem } from "./components/Breadcrumb";
 import { PlanSheet, type PlanSheetHandle } from "./components/PlanSheet";
 import { DiffSheet } from "./components/DiffSheet";
 import { annotationBlocking, type ReviewRailHandle } from "./components/ReviewRail";
+import type { AgentTerminalHandle } from "./components/agent-launcher";
 import { ReviewPanel } from "./components/ReviewPanel";
 import {
   REVIEW_COMPACT_WIDTH,
@@ -163,6 +164,8 @@ export function App({
   const [focusedAnnotationId, setFocusedAnnotationId] = useState<string | undefined>(undefined);
   const [selectedCurationId, setSelectedCurationId] = useState<string | undefined>(undefined);
   const [railTab, setRailTab] = useState<"review" | "agent">("review");
+  // A running in-tab agent terminal (embedded harness); while set, keys route to it.
+  const [agentTerminal, setAgentTerminal] = useState<AgentTerminalHandle | null>(null);
   // review panel layout: mode + expanded width are client view state, loaded
   // from and persisted to the user config so they survive a restart. The ref
   // mirrors the width so the drag-end persist reads the latest value.
@@ -584,6 +587,12 @@ export function App({
   };
 
   useKeyboard((key) => {
+    // A running in-tab agent terminal owns the keyboard: forward every key to it,
+    // with ctrl+] as the detach chord back to the review.
+    if (agentTerminal) {
+      if (key.ctrl && key.name === "]") return void agentTerminal.detach();
+      return void agentTerminal.write(key.sequence);
+    }
     if (menuDialog === "settings") return void handleSettingsKey(key.name);
     if (menuDialog) return void (key.name === "escape" && setMenuDialog(null));
     if (menuOpen) return void (key.name === "escape" && setMenuOpen(false));
@@ -1067,6 +1076,7 @@ export function App({
                   cwd: activeSession.artifact.meta.cwd ?? process.cwd(),
                   seedText,
                 }),
+              onAgentTerminal: setAgentTerminal,
             }}
           />
         </box>

package/src/components/ReviewRail.tsx

@@ -17,7 +17,7 @@ import { Button } from "./primitives/Button";
 import { Toolbar } from "./primitives/Toolbar";
 import { AnnotationCard, type AnnotationDraft } from "./AnnotationCard";
 import { ConfirmCard, type ConfirmCardProps } from "./ConfirmCard";
-import { AgentLauncher } from "./agent-launcher";
+import { AgentLauncher, type AgentTerminalHandle } from "./agent-launcher";
 import { Card } from "./primitives/Card";
 import { truncateToSingleLine } from "./truncate-text";
 import { resolveDisplayName } from "../attribution";
@@ -63,6 +63,8 @@ export interface ReviewRailProps {
   onSubmitRequest: () => void;
   /** Launch a bring-your-own harness in the rail (Agent tab); seedText is the plan-context briefing. */
   onLaunchHarness: (command: string, seedText?: string) => void;
+  /** In-tab agent terminal handle (embedded path); null when detached. Lets the app route keys to it. */
+  onAgentTerminal?: (handle: AgentTerminalHandle | null) => void;
   /** Rail column width; the app derives it from the persisted review layout. */
   width?: number;
   /**
@@ -97,6 +99,7 @@ export const ReviewRail = forwardRef<ReviewRailHandle, ReviewRailProps>(function
     onUndoCuration,
     onSubmitRequest,
     onLaunchHarness,
+    onAgentTerminal,
     width = 34,
     onCollapse,
     theme,
@@ -201,7 +204,12 @@ export const ReviewRail = forwardRef<ReviewRailHandle, ReviewRailProps>(function
       {railTab === "agent" ? (
         <box style={{ flexGrow: 1, flexDirection: "column", paddingLeft: 2 }}>
           <text> </text>
-          <AgentLauncher session={session} onLaunchHarness={onLaunchHarness} theme={theme} />
+          <AgentLauncher
+            session={session}
+            onLaunchHarness={onLaunchHarness}
+            onAgentTerminal={onAgentTerminal}
+            theme={theme}
+          />
         </box>
       ) : openAnnotations.length === 0 && curationItems.length === 0 ? (
         <box style={{ flexGrow: 1, alignItems: "center", justifyContent: "center" }}>

package/src/components/agent-launcher.tsx

@@ -5,11 +5,24 @@
  * without leaving the tab. A plan-context toggle seeds a briefing into the split.
  */
 
-import React, { useState } from "react";
+import React, { useEffect, useRef, useState } from "react";
 import type { ReviewSession } from "@cueloop/schema";
 import type { Theme } from "../theme";
 import { useComponentTheme } from "./theme-context";
 import { FRAME_BORDER_STYLE } from "./primitives/frame";
+import {
+  embeddedTerminalAvailable,
+  registerTerminalPane,
+  type TerminalPaneRenderable,
+} from "./terminal-pane";
+
+registerTerminalPane();
+
+/** A running in-tab agent terminal, handed to the app so it can route keys and detach. */
+export interface AgentTerminalHandle {
+  write: (data: string) => void;
+  detach: () => void;
+}
 
 /** One launchable harness: its rail command and the real logo, rendered as colored rows. */
 export interface HarnessLauncher {
@@ -62,26 +75,70 @@ function LogoMark({ harness }: { harness: HarnessLauncher }): React.ReactNode {
   );
 }
 
+/** Props for the Agent tab body: the session under review plus the launch callbacks. */
 export interface AgentLauncherProps {
   session: ReviewSession;
-  /** Launch a harness in the rail; seedText is the plan-context briefing when the toggle is on. */
+  /**
+   * Fallback launch when no embedded terminal ships for this platform: run the
+   * harness in a herdr split. seedText is the plan-context briefing.
+   */
   onLaunchHarness: (command: string, seedText?: string) => void;
+  /** Notifies the app of the in-tab terminal handle (or null when detached) so it can route keys. */
+  onAgentTerminal?: (handle: AgentTerminalHandle | null) => void;
   theme?: Theme;
 }
 
 /**
  * The Agent tab body: branded launcher cards plus a plan-context toggle. Replaces
- * the old dead agent/status/revision placeholder (now a dim footer line).
+ * the old dead agent/status/revision placeholder (now a dim footer line). When a
+ * prebuilt libghostty-vt ships for the platform, a picked harness runs embedded
+ * inside this tab; otherwise it falls back to a herdr split.
  */
 export function AgentLauncher({
   session,
   onLaunchHarness,
+  onAgentTerminal,
   theme,
 }: AgentLauncherProps): React.ReactNode {
   const tokens = useComponentTheme(theme);
   const [seedContext, setSeedContext] = useState(true);
-  const launch = (harness: HarnessLauncher): void =>
-    onLaunchHarness(harness.command, seedContext ? planHandoffBriefing(session.id) : undefined);
+  const [running, setRunning] = useState<{ harness: HarnessLauncher; seed?: string } | null>(null);
+  const paneRef = useRef<TerminalPaneRenderable | null>(null);
+
+  const launch = (harness: HarnessLauncher): void => {
+    const seed = seedContext ? planHandoffBriefing(session.id) : undefined;
+    if (embeddedTerminalAvailable()) setRunning({ harness, seed });
+    else onLaunchHarness(harness.command, seed);
+  };
+  const detach = (): void => setRunning(null);
+
+  useEffect(() => {
+    if (!running) return onAgentTerminal?.(null);
+    onAgentTerminal?.({ write: (data) => paneRef.current?.write(data), detach });
+    return () => onAgentTerminal?.(null);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [running]);
+
+  if (running) {
+    return (
+      <box style={{ flexDirection: "column", flexGrow: 1 }}>
+        <box style={{ flexDirection: "row" }} onMouseUp={detach}>
+          <text fg={running.harness.color}>{running.harness.name}</text>
+          <box style={{ flexGrow: 1 }} />
+          <text fg={tokens.textDim}>✕ detach (⌃])</text>
+        </box>
+        {React.createElement("terminalPane", {
+          ref: paneRef,
+          command: running.harness.command,
+          cwd: session.artifact.meta.cwd ?? process.cwd(),
+          seedText: running.seed,
+          onExit: detach,
+          style: { flexGrow: 1 },
+        })}
+      </box>
+    );
+  }
+
   return (
     <box style={{ flexDirection: "column", flexGrow: 1 }}>
       <text fg={tokens.text}>Ask an agent about this plan</text>

package/src/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 "../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(typeof embeddedTerminalAvailable()).toBe("boolean");
+    expect(TerminalPaneRenderable).toBeDefined();
+  });
+});

package/src/components/terminal-pane.ts

@@ -0,0 +1,174 @@
+/**
+ * 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 bun-pty (the child + tty) 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="cc" ... />` 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, type IPty } from "bun-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 (the platform dylib is present). */
+export function embeddedTerminalAvailable(): boolean {
+  return factory() !== null;
+}
+
+/** Props for `<terminalPane>`: the child to run plus its cwd/env and a plan-context seed. */
+export interface TerminalPaneOptions extends RenderableOptions {
+  /** The program to run, e.g. "cc" / "pi" / "codex" / a shell. */
+  command?: string;
+  args?: string[];
+  cwd?: string;
+  env?: Record<string, string>;
+  /** Text left unsubmitted in the child after it starts (plan-context seed). */
+  seedText?: string;
+  /** Fired when the child process exits. */
+  onExit?: (exitCode: number) => void;
+}
+
+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 ?? process.env) as Record<string, string>,
+    });
+    this.pty.onData((data) => {
+      // bun-pty 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);
+        // width 0 = the trailing half of a wide glyph already painted at x-1: skip it.
+        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);
+    }
+  }
+
+  protected destroySelf(): void {
+    this.pty?.kill();
+    this.vt?.free();
+    this.pty = null;
+    this.vt = null;
+    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/ghostty-terminal.test.ts

@@ -0,0 +1,45 @@
+/** 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 || typeof factory.create === "function").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, 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(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();
+  });
+});

package/src/ghostty-terminal.ts

@@ -0,0 +1,168 @@
+/**
+ * A live in-process terminal emulator backed by Ghostty's VT core (libghostty-vt)
+ * through a flat FFI shim (native/src/shim.c). 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 {
+  /** Unicode code point; 0 = blank. */
+  codepoint: number;
+  fg: GhosttyColor;
+  bg: GhosttyColor;
+  /** 0 = wide-char trailing cell (skip it), 1 = normal, 2 = double-width lead. */
+  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;
+}
+
+/**
+ * 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).
+ */
+export function loadGhosttyTerminals(): GhosttyTerminalFactory | null {
+  const path = nativeLibraryPath();
+  if (!path) return null;
+  try {
+    const lib = dlopen(path, CVT_SYMBOLS);
+    return 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);
+    return null;
+  }
+}
+
+/** 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,
+    };
+  }
+
+  /** 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" };
+}