@cueloop/client 0.1.0-alpha.6 → 0.1.0-alpha.61

package/src/prototype-browser.ts

@@ -0,0 +1,289 @@
+/// <reference lib="dom" />
+/**
+ * Headless-Chromium backing for prototype review: render an HTML file to a PNG
+ * and resolve a click coordinate to a DOM element. puppeteer-core is imported
+ * lazily so plan/diff review and the test suite never load it.
+ */
+
+export interface PrototypeElement {
+  /** Stable CSS selector - the annotation anchor's authority. */
+  selector: string;
+  /** Short human label for the rail card (element text, else the selector). */
+  quote: string;
+  /** Element rectangle in CSS pixels within the captured viewport. */
+  box: ElementBox;
+}
+
+export interface ElementBox {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+export interface PrototypeViewport {
+  width: number;
+  height: number;
+}
+
+export interface PrototypeRenderer {
+  readonly viewport: PrototypeViewport;
+  screenshot(): Promise<Uint8Array>;
+  elementAt(cssX: number, cssY: number): Promise<PrototypeElement | null>;
+  /** Scroll the page by a pixel delta; returns whether the scroll position moved. */
+  scrollBy(deltaY: number): Promise<boolean>;
+  close(): Promise<void>;
+}
+
+export interface LaunchOptions {
+  filePath: string;
+  viewport: PrototypeViewport;
+  /** Capture density; 1 when the viewport already matches the region's pixels. */
+  deviceScaleFactor?: number;
+  /** Absolute path to a Chrome/Chromium binary; falls back to the channel. */
+  executablePath?: string;
+}
+
+/** Cell click -> CSS pixel inside the letterboxed image, or null when outside it. */
+export function imageCellToCss(
+  event: { x: number; y: number },
+  image: { x: number; y: number; width: number; height: number },
+  viewport: PrototypeViewport,
+): { x: number; y: number } | null {
+  const columnInImage = event.x - image.x;
+  const rowInImage = event.y - image.y;
+
+  if (
+    columnInImage < 0 ||
+    rowInImage < 0 ||
+    columnInImage >= image.width ||
+    rowInImage >= image.height
+  ) {
+    return null;
+  }
+
+  return {
+    x: ((columnInImage + 0.5) / image.width) * viewport.width,
+    y: ((rowInImage + 0.5) / image.height) * viewport.height,
+  };
+}
+
+/** CSS pixel rect -> the image cell it maps to, for anchoring overlays. */
+export function cssBoxToCell(
+  box: ElementBox,
+  image: { x: number; y: number; width: number; height: number },
+  viewport: PrototypeViewport,
+): { column: number; row: number; columns: number; rows: number } {
+  const scaleColumn = image.width / viewport.width;
+  const scaleRow = image.height / viewport.height;
+
+  return {
+    column: image.x + Math.floor(box.x * scaleColumn),
+    row: image.y + Math.floor(box.y * scaleRow),
+    columns: Math.max(1, Math.round(box.width * scaleColumn)),
+    rows: Math.max(1, Math.round(box.height * scaleRow)),
+  };
+}
+
+export type PrototypeRendererFactory = (options: LaunchOptions) => Promise<PrototypeRenderer>;
+
+let rendererFactory: PrototypeRendererFactory | null = null;
+
+/** Override the renderer factory so tests can inject a browserless fake. */
+export function setPrototypeRendererFactory(factory: PrototypeRendererFactory | null): void {
+  rendererFactory = factory;
+}
+
+/** The active factory - the injected fake in tests, else real headless Chromium. */
+export function prototypeRendererFactory(): PrototypeRendererFactory {
+  return rendererFactory ?? launchPrototypeRenderer;
+}
+
+type PuppeteerBrowser = Awaited<ReturnType<typeof import("puppeteer-core").default.launch>>;
+
+// One Chromium per process, kept warm and reused across prototype opens: the
+// launch is the dominant load cost, so each open only spawns a fresh page.
+let sharedBrowser: Promise<PuppeteerBrowser> | null = null;
+
+async function warmBrowser(executablePath: string | undefined): Promise<PuppeteerBrowser> {
+  // reuse the warm browser only while it is still connected; a crashed or
+  // disconnected Chromium is dropped so the next open relaunches instead of
+  // calling newPage on a dead process forever
+  const cached = sharedBrowser ? await sharedBrowser.catch(() => null) : null;
+
+  if (cached && cached.connected) return cached;
+  const puppeteer = (await import("puppeteer-core")).default;
+  const launched = puppeteer.launch({
+    executablePath: executablePath ?? chromeExecutable(),
+    headless: true,
+    args: ["--no-sandbox", "--hide-scrollbars", "--force-color-profile=srgb"],
+  });
+
+  sharedBrowser = launched;
+  const browser = await launched.catch((error) => {
+    if (sharedBrowser === launched) sharedBrowser = null;
+    throw error;
+  });
+
+  browser.once("disconnected", () => {
+    if (sharedBrowser === launched) sharedBrowser = null;
+  });
+
+  return browser;
+}
+
+export async function launchPrototypeRenderer(options: LaunchOptions): Promise<PrototypeRenderer> {
+  const { pathToFileURL } = await import("node:url");
+  const browser = await warmBrowser(options.executablePath);
+  // close only the page on teardown, never the shared browser, so the next open
+  // reuses the warm Chromium
+  const page = await browser.newPage();
+
+  try {
+    await page.setViewport({
+      width: options.viewport.width,
+      height: options.viewport.height,
+      deviceScaleFactor: options.deviceScaleFactor ?? 2,
+    });
+    // `load` waits for images and styles but skips networkidle0's fixed 500ms
+    // idle window, which a static local file would otherwise always pay
+    await page.goto(pathToFileURL(options.filePath).href, { waitUntil: "load" });
+    // Render the mockup on the terminal's own surface rather than on an opaque
+    // page: strip the root background so it never paints a square box, and the
+    // capture (taken with alpha, below) lets the active terminal theme show
+    // through around the mockup's own components - the prototype emerges into
+    // whatever theme is running instead of sitting in a grey card.
+    await page.evaluate(() => {
+      for (const element of [document.documentElement, document.body]) {
+        element?.style.setProperty("background", "transparent", "important");
+      }
+    });
+  } catch (error) {
+    await page.close().catch(() => undefined);
+    throw error;
+  }
+
+  return {
+    viewport: options.viewport,
+    async screenshot() {
+      // omitBackground keeps the alpha from the stripped page background, so the
+      // terminal composites the mockup over its own theme surface.
+      const buffer = await page.screenshot({
+        type: "png",
+        encoding: "binary",
+        omitBackground: true,
+      });
+
+      return new Uint8Array(buffer as Buffer);
+    },
+    async elementAt(cssX, cssY) {
+      return (await page.evaluate(elementAtScript, cssX, cssY)) as PrototypeElement | null;
+    },
+    async scrollBy(deltaY) {
+      return (await page.evaluate(scrollByScript, deltaY)) as boolean;
+    },
+    async close() {
+      await page.close().catch(() => undefined);
+    },
+  };
+}
+
+/** Serialized into the page (self-contained for puppeteer): resolve the click to a component element. */
+function elementAtScript(x: number, y: number): unknown {
+  const SEMANTIC = new Set([
+    "SECTION",
+    "ARTICLE",
+    "LI",
+    "NAV",
+    "HEADER",
+    "FOOTER",
+    "ASIDE",
+    "FORM",
+  ]);
+  const isNamed = (element: Element): boolean =>
+    element.classList.length > 0 || SEMANTIC.has(element.tagName);
+  // a card wraps several children: climb to the nearest named container holding
+  // more than one child, else the nearest named ancestor, else the clicked leaf
+  const componentRoot = (start: Element): Element => {
+    let namedFallback: Element | null = null;
+    let current: Element | null = start;
+
+    while (current && current !== document.body) {
+      if (isNamed(current)) {
+        if (current.childElementCount > 1) return current;
+        namedFallback = namedFallback ?? current;
+      }
+      current = current.parentElement;
+    }
+
+    return namedFallback ?? start;
+  };
+  const selectorFor = (start: Element): string => {
+    const parts: string[] = [];
+    let current: Element | null = start;
+
+    while (current && current.nodeType === 1 && current !== document.documentElement) {
+      let part = current.tagName.toLowerCase();
+
+      if (current.id) {
+        parts.unshift(part + "#" + CSS.escape(current.id));
+        break;
+      }
+      const parent: Element | null = current.parentElement;
+
+      if (parent) {
+        const twins = [...parent.children].filter((child) => child.tagName === current!.tagName);
+
+        if (twins.length > 1) part += ":nth-of-type(" + (twins.indexOf(current) + 1) + ")";
+      }
+      parts.unshift(part);
+      current = current.parentElement;
+    }
+
+    return parts.join(" > ");
+  };
+  const hit = document.elementFromPoint(x, y);
+
+  if (!(hit instanceof Element)) return null;
+  // A click on an interactive control anchors to that control - a button in a
+  // grid is the target, not the grid. Everything else climbs to its component.
+  const control = hit.closest(
+    "button, a, [role='button'], input, select, textarea, label, summary",
+  );
+  const node = control ?? componentRoot(hit);
+  const selector = selectorFor(node);
+
+  if (!selector) return null;
+  const text = (node.textContent || "").replace(/\s+/g, " ").trim();
+  const tag = node.tagName.toLowerCase();
+  const quote = text
+    ? text.slice(0, 80)
+    : node.id
+      ? tag + "#" + node.id
+      : node.classList.length
+        ? tag + "." + node.classList[0]
+        : tag;
+  const rect = node.getBoundingClientRect();
+
+  return { selector, quote, box: { x: rect.x, y: rect.y, width: rect.width, height: rect.height } };
+}
+
+function scrollByScript(deltaY: number): boolean {
+  const before = window.scrollY;
+
+  window.scrollBy(0, deltaY);
+
+  return window.scrollY !== before;
+}
+
+/** Standard Chrome install locations by platform; puppeteer-core ships no browser. */
+function chromeExecutable(): string {
+  if (process.platform === "darwin") {
+    return "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome";
+  }
+  if (process.platform === "win32") {
+    return "C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe";
+  }
+
+  return "/usr/bin/google-chrome";
+}

package/src/pty.test.ts

@@ -0,0 +1,81 @@
+import { describe, expect, test } from "bun:test";
+import { ptyAvailable, spawn } from "./pty";
+
+// The forkpty shim is a per-platform prebuilt; skip where none ships (e.g. CI
+// without the built dylib), exactly as the caller degrades to a herdr split.
+const ptyTest = ptyAvailable() ? test : test.skip;
+
+/** Run a child on a PTY, collect its output, and resolve with the exit code. */
+function runOnPty(file: string, args: string[]): Promise<{ output: string; exitCode: number }> {
+  return new Promise((resolve, reject) => {
+    const pty = spawn(file, args, { name: "xterm-256color", cols: 80, rows: 24 });
+    let output = "";
+    const timeout = setTimeout(() => reject(new Error("pty child never exited")), 5000);
+
+    pty.onData((chunk) => {
+      output += chunk;
+    });
+    pty.onExit(({ exitCode }) => {
+      clearTimeout(timeout);
+      resolve({ output, exitCode });
+    });
+  });
+}
+
+describe("pty", () => {
+  ptyTest("streams a child's output and reports its exit code", async () => {
+    // Act
+    const { output, exitCode } = await runOnPty("sh", ["-c", "printf 'PTY-OK'; exit 7"]);
+
+    // Assert
+    expect(output).toContain("PTY-OK");
+    expect(exitCode).toBe(7);
+  });
+
+  ptyTest("forwards written input to the child", async () => {
+    // Arrange - `cat` echoes stdin back through the tty until it closes
+    const pty = spawn("cat", [], { name: "xterm-256color", cols: 80, rows: 24 });
+    let output = "";
+
+    pty.onData((chunk) => {
+      output += chunk;
+    });
+
+    // Act
+    pty.write("ping\n");
+    await new Promise((resolve) => setTimeout(resolve, 200));
+    pty.kill();
+
+    // Assert - the tty echoes the written line back
+    expect(output).toContain("ping");
+  });
+
+  ptyTest("passes env through to the child", async () => {
+    // Act
+    const { output } = await runOnPty("sh", ["-c", "printf '%s' \"$CUELOOP_PTY_MARKER\""]);
+
+    // Assert - a child with no inherited marker prints nothing for it
+    expect(output).not.toContain("marker-value");
+
+    // Act - now inject the marker via env
+    const withEnv = await new Promise<string>((resolve, reject) => {
+      const pty = spawn("sh", ["-c", "printf '%s' \"$CUELOOP_PTY_MARKER\""], {
+        name: "xterm-256color",
+        env: { ...process.env, CUELOOP_PTY_MARKER: "marker-value" },
+      });
+      let collected = "";
+      const timeout = setTimeout(() => reject(new Error("no exit")), 5000);
+
+      pty.onData((chunk) => {
+        collected += chunk;
+      });
+      pty.onExit(() => {
+        clearTimeout(timeout);
+        resolve(collected);
+      });
+    });
+
+    // Assert
+    expect(withEnv).toContain("marker-value");
+  });
+});

package/src/pty.ts

@@ -0,0 +1,237 @@
+/**
+ * A pseudo-terminal for the embedded Agent-tab terminal, over cueloop's own
+ * forkpty(3) FFI shim (native/src/pty.zig). `spawn` returns a `Pty` with
+ * `onData`/`onExit` events and `write`/`resize`/`kill`; a poll loop drains the
+ * child's output and decodes it as streaming UTF-8. `ptyAvailable()` returns
+ * false when no prebuilt shim ships for this platform, so callers fall back to a
+ * herdr split, exactly like the Ghostty VT loader.
+ */
+
+import { dlopen, FFIType, ptr } from "bun:ffi";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+const DEFAULT_COLS = 80;
+const DEFAULT_ROWS = 24;
+/** How long the read loop sleeps when the child produced no output this tick. */
+const READ_IDLE_MS = 8;
+const READ_BUFFER_BYTES = 4096;
+/** cueloop_pty_read's sentinel: the child has exited and its output is drained. */
+const CHILD_EXITED = -2;
+
+export interface PtyForkOptions {
+  name?: string;
+  cols?: number;
+  rows?: number;
+  cwd?: string;
+  env?: Record<string, string>;
+}
+
+export interface ExitEvent {
+  exitCode: number;
+}
+
+export interface Disposable {
+  dispose(): void;
+}
+
+/** The pseudo-terminal surface the embedded terminal consumes. */
+export interface IPty {
+  readonly pid: number;
+  readonly cols: number;
+  readonly rows: number;
+  readonly onData: (listener: (data: string) => void) => Disposable;
+  readonly onExit: (listener: (event: ExitEvent) => void) => Disposable;
+  write(data: string): void;
+  resize(cols: number, rows: number): void;
+  kill(signal?: string): void;
+}
+
+const PTY_SYMBOLS = {
+  cueloop_pty_spawn: {
+    args: [FFIType.ptr, FFIType.cstring, FFIType.ptr, FFIType.i32, FFIType.i32],
+    returns: FFIType.i32,
+  },
+  cueloop_pty_write: { args: [FFIType.i32, FFIType.ptr, FFIType.i32], returns: FFIType.i32 },
+  cueloop_pty_read: { args: [FFIType.i32, FFIType.ptr, FFIType.i32], returns: FFIType.i32 },
+  cueloop_pty_resize: { args: [FFIType.i32, FFIType.i32, FFIType.i32], returns: FFIType.i32 },
+  cueloop_pty_kill: { args: [FFIType.i32], returns: FFIType.i32 },
+  cueloop_pty_get_pid: { args: [FFIType.i32], returns: FFIType.i32 },
+  cueloop_pty_get_exit_code: { args: [FFIType.i32], returns: FFIType.i32 },
+  cueloop_pty_close: { args: [FFIType.i32], returns: FFIType.void },
+} as const;
+
+type PtyLib = ReturnType<typeof dlopen<typeof PTY_SYMBOLS>>["symbols"];
+
+/** The prebuilt pty shim 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, `libcuelooppty.${suffix}`);
+
+  return existsSync(path) ? path : null;
+}
+
+/** One shared load of the pty shim; null when no dylib ships for the platform. */
+let ptyLib: PtyLib | null | undefined;
+
+function library(): PtyLib | null {
+  if (ptyLib !== undefined) return ptyLib;
+  const path = nativeLibraryPath();
+
+  if (!path) return (ptyLib = null);
+  try {
+    ptyLib = dlopen(path, PTY_SYMBOLS).symbols;
+  } catch (error) {
+    console.error(`cueloop: failed to load ${path}:`, error);
+    ptyLib = null;
+  }
+
+  return ptyLib;
+}
+
+/** True when this platform ships a prebuilt pty shim (embedding is possible). */
+export function ptyAvailable(): boolean {
+  return library() !== null;
+}
+
+class EventEmitter<T> {
+  private listeners: ((value: T) => void)[] = [];
+  readonly event = (listener: (value: T) => void): Disposable => {
+    this.listeners.push(listener);
+
+    return {
+      dispose: () => {
+        const index = this.listeners.indexOf(listener);
+
+        if (index !== -1) this.listeners.splice(index, 1);
+      },
+    };
+  };
+  fire(value: T): void {
+    for (const listener of this.listeners) listener(value);
+  }
+}
+
+/** Pack tokens into the C shim's "tok\0tok\0...\0\0" (double-NUL-terminated) form. */
+function packTokens(tokens: string[]): Buffer {
+  return Buffer.from(tokens.map((token) => `${token}\0`).join("") + "\0", "utf8");
+}
+
+class Pty implements IPty {
+  private handle: number;
+  private processId: number;
+  private columns: number;
+  private rowCount: number;
+  private closing = false;
+  private reading = false;
+  private readonly decoder = new TextDecoder("utf-8");
+  private readonly dataEvent = new EventEmitter<string>();
+  private readonly exitEvent = new EventEmitter<ExitEvent>();
+
+  constructor(
+    private readonly lib: PtyLib,
+    file: string,
+    args: string[],
+    options: PtyForkOptions,
+  ) {
+    this.columns = options.cols ?? DEFAULT_COLS;
+    this.rowCount = options.rows ?? DEFAULT_ROWS;
+    const cwd = options.cwd ?? process.cwd();
+    const env = options.env
+      ? Object.entries(options.env).map(([key, value]) => `${key}=${value}`)
+      : [];
+
+    const argvPacked = packTokens([file, ...args]);
+    const envPacked = packTokens(env);
+
+    this.handle = lib.cueloop_pty_spawn(
+      ptr(argvPacked),
+      Buffer.from(`${cwd}\0`, "utf8"),
+      ptr(envPacked),
+      this.columns,
+      this.rowCount,
+    );
+    if (this.handle < 0) throw new Error("PTY spawn failed");
+    this.processId = lib.cueloop_pty_get_pid(this.handle);
+    // Let the caller attach onData/onExit before the first bytes arrive.
+    queueMicrotask(() => void this.readLoop());
+  }
+
+  get pid(): number {
+    return this.processId;
+  }
+  get cols(): number {
+    return this.columns;
+  }
+  get rows(): number {
+    return this.rowCount;
+  }
+  get onData() {
+    return this.dataEvent.event;
+  }
+  get onExit() {
+    return this.exitEvent.event;
+  }
+
+  write(data: string): void {
+    if (this.closing) return;
+    const buffer = Buffer.from(data, "utf8");
+
+    this.lib.cueloop_pty_write(this.handle, ptr(buffer), buffer.length);
+  }
+
+  resize(cols: number, rows: number): void {
+    if (this.closing) return;
+    this.columns = cols;
+    this.rowCount = rows;
+    this.lib.cueloop_pty_resize(this.handle, cols, rows);
+  }
+
+  kill(): void {
+    if (this.closing) return;
+    this.closing = true;
+    this.lib.cueloop_pty_kill(this.handle);
+    this.lib.cueloop_pty_close(this.handle);
+    this.exitEvent.fire({ exitCode: 0 });
+  }
+
+  private async readLoop(): Promise<void> {
+    if (this.reading) return;
+    this.reading = true;
+    const buffer = Buffer.allocUnsafe(READ_BUFFER_BYTES);
+
+    while (!this.closing) {
+      const count = this.lib.cueloop_pty_read(this.handle, ptr(buffer), buffer.length);
+
+      if (count > 0) {
+        // Stream mode buffers a multibyte char split across reads (box-drawing etc.).
+        const text = this.decoder.decode(buffer.subarray(0, count), { stream: true });
+
+        if (text) this.dataEvent.fire(text);
+      } else if (count === CHILD_EXITED || count < 0) {
+        // Both the drained-exit sentinel and a hard read error end the session:
+        // flush the decoder, reap for the code, close, and fire the exit once.
+        const tail = this.decoder.decode();
+
+        if (tail) this.dataEvent.fire(tail);
+        const exitCode = this.lib.cueloop_pty_get_exit_code(this.handle);
+
+        this.lib.cueloop_pty_close(this.handle);
+        this.closing = true;
+        this.exitEvent.fire({ exitCode });
+      } else {
+        await new Promise((resolve) => setTimeout(resolve, READ_IDLE_MS));
+      }
+    }
+  }
+}
+
+/** Spawn `file` with `args` on a fresh PTY. Throws when no shim ships (gate on ptyAvailable). */
+export function spawn(file: string, args: string[], options: PtyForkOptions = {}): IPty {
+  const lib = library();
+
+  if (!lib) throw new Error("cueloop: no pty shim for this platform");
+
+  return new Pty(lib, file, args, options);
+}