termcut 0.1.0

package/src/renderer/player-entry.ts

@@ -0,0 +1,105 @@
+// Browser-side player for `.html` exports. Uses wterm's lite core (inline WASM) so the file is self-contained.
+import { WasmBridge } from "@wterm/core";
+import { WTerm } from "@wterm/dom";
+
+interface PlayerData {
+  cols: number;
+  rows: number;
+  duration: number;
+  speed: number;
+  events: Array<{ vt: number; type: "o" | "r"; data: string }>;
+}
+
+const dataEl = document.getElementById("tcut-cast");
+if (!dataEl) throw new Error("tcut player: missing cast data");
+const data = JSON.parse(dataEl.textContent || "{}") as PlayerData;
+
+const el = document.getElementById("term")!;
+const playBtn = document.getElementById("play") as HTMLButtonElement;
+const progress = document.getElementById("progress") as HTMLInputElement;
+const loopBox = document.getElementById("loop") as HTMLInputElement;
+const timeLabel = document.getElementById("time")!;
+
+const fmt = (s: number) => `${Math.floor(s / 60)}:${String(Math.floor(s % 60)).padStart(2, "0")}`;
+
+(async () => {
+  const core = await WasmBridge.load();
+  const term = new WTerm(el, { cols: data.cols, rows: data.rows, core, autoResize: false, cursorBlink: true, onData: () => {} });
+  await term.init();
+  el.classList.add("focused");
+
+  let pointer = 0;
+  let elapsed = 0; // seconds on the visible timeline
+  let playing = false;
+  let last = 0;
+  let raf = 0;
+
+  const reset = () => {
+    term.write("\x1bc");
+    term.resize(data.cols, data.rows);
+    pointer = 0;
+    elapsed = 0;
+  };
+
+  const applyUntil = (time: number) => {
+    while (pointer < data.events.length && data.events[pointer]!.vt <= time) {
+      const e = data.events[pointer++]!;
+      if (e.type === "o") term.write(e.data);
+      else if (e.type === "r") {
+        const [c, r] = e.data.split("x").map(Number);
+        if (c! > 0 && r! > 0) term.resize(c!, r!);
+      }
+    }
+  };
+
+  const updateUi = () => {
+    progress.value = String(Math.min(1000, Math.round((elapsed / data.duration) * 1000)));
+    timeLabel.textContent = `${fmt(elapsed)} / ${fmt(data.duration)}`;
+    playBtn.textContent = playing ? "❚❚" : "▶";
+  };
+
+  const tick = (now: number) => {
+    if (!playing) return;
+    elapsed += ((now - last) / 1000) * data.speed;
+    last = now;
+    applyUntil(elapsed);
+    if (elapsed >= data.duration) {
+      if (loopBox.checked) {
+        reset();
+      } else {
+        playing = false;
+        elapsed = data.duration;
+      }
+    }
+    updateUi();
+    if (playing) raf = requestAnimationFrame(tick);
+  };
+
+  const play = () => {
+    if (playing) return;
+    if (elapsed >= data.duration) reset();
+    playing = true;
+    last = performance.now();
+    raf = requestAnimationFrame(tick);
+    updateUi();
+  };
+  const pause = () => {
+    playing = false;
+    cancelAnimationFrame(raf);
+    updateUi();
+  };
+
+  playBtn.addEventListener("click", () => (playing ? pause() : play()));
+  progress.addEventListener("input", () => {
+    const target = (Number(progress.value) / 1000) * data.duration;
+    if (target < elapsed) reset();
+    elapsed = target;
+    applyUntil(elapsed);
+    updateUi();
+  });
+  el.addEventListener("click", () => (playing ? pause() : play()));
+
+  applyUntil(0);
+  updateUi();
+  play();
+})();

package/src/renderer/webview.ts

@@ -0,0 +1,140 @@
+import { mkdir } from "node:fs/promises";
+import path from "node:path";
+import { MARKER } from "../cast";
+import type { Recording, RenderProgress, ResolvedConfig } from "../types";
+import { buildTimeline, withReinjection, type TimedEvent } from "../timeline";
+import { pageAssets } from "./bundle";
+import { createSinks } from "./encoder";
+import { barHeight, renderHtml, themeOsc } from "./page";
+
+export interface RenderResult {
+  outputs: string[];
+  frames: number;
+  screenshots: string[];
+  durationSeconds: number;
+}
+
+export async function render(
+  rec: Recording,
+  config: ResolvedConfig,
+  onProgress?: (p: RenderProgress) => void,
+): Promise<RenderResult> {
+  if (typeof Bun.WebView !== "function") {
+    throw new Error("Bun.WebView is not available in this Bun version. tcut needs Bun >= 1.4.");
+  }
+
+  const assets = await pageAssets();
+  const html = renderHtml(config);
+  const osc = themeOsc(config.theme);
+  const batches = new Map<number, string>();
+  let batchId = 0;
+
+  const server = Bun.serve({
+    port: 0,
+    hostname: "127.0.0.1",
+    fetch(req) {
+      const { pathname } = new URL(req.url);
+      if (pathname === "/app.js") return new Response(assets.js, { headers: { "content-type": "text/javascript" } });
+      if (pathname === "/wterm.css") return new Response(assets.css, { headers: { "content-type": "text/css" } });
+      if (pathname === "/ghostty-vt.wasm") return new Response(Bun.file(assets.wasmPath), { headers: { "content-type": "application/wasm" } });
+      if (pathname === "/theme") return new Response(osc, { headers: { "content-type": "text/plain; charset=utf-8" } });
+      if (pathname.startsWith("/batch/")) {
+        const id = Number(pathname.slice("/batch/".length));
+        const body = batches.get(id);
+        batches.delete(id);
+        if (body === undefined) return new Response("[]", { status: 404, headers: { "content-type": "application/json" } });
+        return new Response(body, { headers: { "content-type": "application/json; charset=utf-8" } });
+      }
+      return new Response(html, { headers: { "content-type": "text/html; charset=utf-8" } });
+    },
+  });
+
+  const timeline = buildTimeline(rec.events, config.playbackSpeed);
+  const lite = config.core === "lite";
+  const events = lite ? timeline.events : withReinjection(timeline.events, osc);
+  const fps = config.fps;
+  const totalFrames = Math.max(1, Math.ceil(timeline.duration * fps) + 1);
+  const blinkPeriod = config.cursor.period / 1000;
+  const screenshots: string[] = [];
+
+  const view = new Bun.WebView({ width: 800, height: 600 });
+  try {
+    await view.navigate(`http://127.0.0.1:${server.port}/`);
+    for (let i = 0; i < 100; i++) {
+      if ((await view.evaluate("typeof window.__vt === 'object'")) === true) break;
+      await Bun.sleep(50);
+    }
+    const boot = {
+      cols: rec.header.width,
+      rows: rec.header.height,
+      foreground: config.theme.foreground,
+      background: config.theme.background,
+      wasmUrl: "/ghostty-vt.wasm",
+      core: config.core,
+    };
+    await view.evaluate(`window.__vt.boot(${JSON.stringify(boot)})`);
+    if (!lite) await view.evaluate("window.__vt.writeUrl('/theme')");
+
+    const cell = (await view.evaluate("window.__vt.measure()")) as { w: number; h: number };
+    if (!cell || !(cell.w > 0) || !(cell.h > 0)) throw new Error("Could not measure terminal cell size");
+
+    const termW = Math.ceil(rec.header.width * cell.w);
+    const termH = Math.ceil(rec.header.height * cell.h);
+    const frameW = termW + config.padding * 2;
+    const frameH = termH + config.padding * 2 + barHeight(config);
+    const even = (n: number) => (n % 2 === 0 ? n : n + 1);
+    const width = even(frameW + config.margin * 2);
+    const height = even(frameH + config.margin * 2);
+    await view.evaluate(`window.__vt.layout(${frameW}, ${frameH}, ${termW}, ${termH})`);
+    await view.resize(width, height);
+    await view.evaluate("new Promise(r => requestAnimationFrame(() => requestAnimationFrame(() => r(true))))");
+
+    const sinks = await createSinks(config.output, fps);
+    let pointer = 0;
+    let lastPng: Uint8Array | null = null;
+    let lastBlink: boolean | null = null;
+
+    for (let frame = 0; frame < totalFrames; frame++) {
+      const time = frame / fps;
+      const batch: TimedEvent[] = [];
+      while (pointer < events.length && events[pointer]!.vt <= time + 1e-9) {
+        batch.push(events[pointer]!);
+        pointer++;
+      }
+
+      const blinkOn = !config.cursor.blink || Math.floor((time / blinkPeriod) * 2) % 2 === 0;
+      const drawable = batch.filter((e) => e.type === "o" || e.type === "r");
+      const shots = batch.filter((e) => e.type === "m" && e.data.startsWith(MARKER.screenshot));
+      const dirty = lastPng === null || drawable.length > 0 || blinkOn !== lastBlink;
+
+      if (drawable.length > 0) {
+        const id = ++batchId;
+        batches.set(id, JSON.stringify(drawable.map(({ type, data }) => ({ type, data }))));
+        await view.evaluate(`window.__vt.applyUrl('/batch/${id}')`);
+      }
+      if (blinkOn !== lastBlink) {
+        await view.evaluate(`window.__vt.cursor(${blinkOn})`);
+        lastBlink = blinkOn;
+      }
+      if (dirty) {
+        lastPng = (await view.screenshot({ encoding: "buffer" })) as Uint8Array;
+      }
+
+      for (const shot of shots) {
+        const file = shot.data.slice(MARKER.screenshot.length);
+        await mkdir(path.dirname(path.resolve(file)), { recursive: true });
+        await Bun.write(file, lastPng!);
+        screenshots.push(file);
+      }
+
+      for (const sink of sinks) await sink.frame(lastPng!);
+      onProgress?.({ frame: frame + 1, total: totalFrames });
+    }
+
+    for (const sink of sinks) await sink.finish();
+    return { outputs: sinks.map((s) => s.target), frames: totalFrames, screenshots, durationSeconds: timeline.duration };
+  } finally {
+    view.close();
+    server.stop(true);
+  }
+}

package/src/screen.ts

@@ -0,0 +1,130 @@
+import { WasmBridge, type TerminalCore } from "@wterm/core";
+import { GhosttyCore } from "@wterm/ghostty";
+import { ghosttyWasmUrl } from "./renderer/bundle";
+import type { CoreName } from "./types";
+
+let logsSilenced = false;
+
+/** libghostty reports unimplemented modes via console.log (e.g. bash's `?1034h`); keep them out of CLI output. */
+function silenceGhosttyLogs(): void {
+  if (logsSilenced) return;
+  logsSilenced = true;
+  const original = console.log;
+  console.log = (...args: unknown[]) => {
+    if (args[0] === "[ghostty-vt]") return;
+    original(...args);
+  };
+}
+
+export interface ScreenOptions {
+  /** Called with terminal responses (e.g. Device Attributes replies) that must be written back to the PTY. */
+  onResponse?: (data: string) => void;
+  core?: CoreName;
+}
+
+export async function loadCore(core: CoreName = "ghostty"): Promise<TerminalCore> {
+  if (core === "lite") return WasmBridge.load();
+  silenceGhosttyLogs();
+  return GhosttyCore.load({ wasmPath: await ghosttyWasmUrl() });
+}
+
+/**
+ * Headless terminal model backed by libghostty (WASM). The recorder feeds every PTY chunk through it so
+ * `wait()` / `expect()` / `run()` look at the actual screen instead of a raw byte stream.
+ */
+export class Screen {
+  private listeners = new Set<() => void>();
+  onResponse: ((data: string) => void) | undefined;
+
+  private constructor(readonly core: TerminalCore) {}
+
+  static async create(cols: number, rows: number, opts: ScreenOptions = {}): Promise<Screen> {
+    const core = await loadCore(opts.core);
+    core.init(cols, rows);
+    const screen = new Screen(core);
+    screen.onResponse = opts.onResponse;
+    return screen;
+  }
+
+  write(data: string | Uint8Array): void {
+    if (typeof data === "string") this.core.writeString(data);
+    else this.core.writeRaw(data);
+    this.drainResponses();
+    for (const listener of this.listeners) listener();
+  }
+
+  private drainResponses(): void {
+    for (let i = 0; i < 64; i++) {
+      const response = this.core.getResponse();
+      if (response === null || response === undefined || response.length === 0) return;
+      this.onResponse?.(response);
+    }
+  }
+
+  /** Writes are synchronous; kept for API symmetry with async models. */
+  async settle(): Promise<void> {}
+
+  /** Resolves the next time a chunk is written. */
+  nextFlush(): Promise<void> {
+    return new Promise((resolve) => {
+      const listener = () => {
+        this.listeners.delete(listener);
+        resolve();
+      };
+      this.listeners.add(listener);
+    });
+  }
+
+  resize(cols: number, rows: number): void {
+    this.core.resize(cols, rows);
+  }
+
+  get cols(): number {
+    return this.core.getCols();
+  }
+
+  get rows(): number {
+    return this.core.getRows();
+  }
+
+  cursor(): { x: number; y: number } {
+    const c = this.core.getCursor();
+    return { x: c.col, y: c.row };
+  }
+
+  /** Absolute index of the cursor line, counting every line that ever scrolled off the top. */
+  absoluteCursorLine(): number {
+    const discarded = this.core.getScrollbackDiscardedCount?.() ?? 0;
+    return discarded + this.core.getScrollbackCount() + this.core.getCursor().row;
+  }
+
+  rowText(row: number): string {
+    let text = "";
+    const cols = this.core.getCols();
+    for (let col = 0; col < cols; col++) {
+      const cell = this.core.getCell(row, col);
+      if (cell.width === 0) continue; // wide-char continuation
+      if (cell.chars) text += cell.chars;
+      else text += cell.char === 0 ? " " : String.fromCodePoint(cell.char);
+    }
+    return text.replace(/\s+$/, "");
+  }
+
+  line(): string {
+    return this.rowText(this.core.getCursor().row);
+  }
+
+  screen(): string {
+    const rows: string[] = [];
+    for (let y = 0; y < this.core.getRows(); y++) rows.push(this.rowText(y));
+    return rows.join("\n");
+  }
+
+  usingAltScreen(): boolean {
+    return this.core.usingAltScreen();
+  }
+
+  dispose(): void {
+    this.listeners.clear();
+  }
+}

package/src/testing.ts

@@ -0,0 +1,69 @@
+import path from "node:path";
+import { record } from "./recorder";
+import { isVideo } from "./video";
+
+export interface TestResult {
+  file: string;
+  ok: boolean;
+  ms: number;
+  error?: string;
+}
+
+export interface TestSummary {
+  results: TestResult[];
+  passed: number;
+  failed: number;
+}
+
+const PATTERNS = ["**/*.video.ts", "**/*.tcut.ts"];
+
+/** Expand files and directories into script paths. Directories are searched for `*.video.ts` / `*.tcut.ts`. */
+export async function discoverScripts(inputs: string[]): Promise<string[]> {
+  const files = new Set<string>();
+  for (const input of inputs) {
+    const abs = path.resolve(input);
+    const stat = await Bun.file(abs).stat().catch(() => null);
+    if (stat?.isDirectory()) {
+      for (const pattern of PATTERNS) {
+        for await (const match of new Bun.Glob(pattern).scan({ cwd: abs, absolute: true })) {
+          if (!match.includes("/node_modules/")) files.add(match);
+        }
+      }
+    } else if (stat?.isFile()) {
+      files.add(abs);
+    } else {
+      throw new Error(`No such file or directory: ${input}`);
+    }
+  }
+  return [...files].sort();
+}
+
+/** Run each script's recording in fast mode (no sleeps, no typing delay), without rendering or writing casts. */
+export async function runScriptTests(inputs: string[], log: (line: string) => void = console.log): Promise<TestSummary> {
+  const files = await discoverScripts(inputs);
+  if (files.length === 0) throw new Error("No scripts found (looking for *.video.ts or *.tcut.ts)");
+  const results: TestResult[] = [];
+  log(`TAP version 14\n1..${files.length}`);
+  for (const [index, file] of files.entries()) {
+    const rel = path.relative(process.cwd(), file);
+    const started = performance.now();
+    let error: string | undefined;
+    try {
+      const mod = (await import(file)) as { default?: unknown };
+      if (!isVideo(mod.default)) throw new Error("default export is not a defineVideo() result");
+      await record(mod.default.config, mod.default.script, { fast: true });
+    } catch (err) {
+      error = err instanceof Error ? err.message : String(err);
+    }
+    const ms = Math.round(performance.now() - started);
+    results.push({ file: rel, ok: !error, ms, error });
+    if (error) {
+      log(`not ok ${index + 1} - ${rel} (${ms}ms)\n  ---\n${error.split("\n").map((l) => "  " + l).join("\n")}\n  ...`);
+    } else {
+      log(`ok ${index + 1} - ${rel} (${ms}ms)`);
+    }
+  }
+  const failed = results.filter((r) => !r.ok).length;
+  log(`\n# ${results.length - failed} passed, ${failed} failed`);
+  return { results, passed: results.length - failed, failed };
+}

package/src/themes.ts

@@ -0,0 +1,138 @@
+import type { Theme, ThemeName } from "./types";
+
+export const themes: Record<ThemeName, Theme> = {
+  "catppuccin-mocha": {
+    name: "catppuccin-mocha",
+    background: "#1e1e2e",
+    foreground: "#cdd6f4",
+    cursor: "#f5e0dc",
+    cursorAccent: "#1e1e2e",
+    selectionBackground: "#585b70",
+    black: "#45475a",
+    red: "#f38ba8",
+    green: "#a6e3a1",
+    yellow: "#f9e2af",
+    blue: "#89b4fa",
+    magenta: "#f5c2e7",
+    cyan: "#94e2d5",
+    white: "#bac2de",
+    brightBlack: "#585b70",
+    brightRed: "#f38ba8",
+    brightGreen: "#a6e3a1",
+    brightYellow: "#f9e2af",
+    brightBlue: "#89b4fa",
+    brightMagenta: "#f5c2e7",
+    brightCyan: "#94e2d5",
+    brightWhite: "#a6adc8",
+  },
+  dracula: {
+    name: "dracula",
+    background: "#282a36",
+    foreground: "#f8f8f2",
+    cursor: "#f8f8f2",
+    cursorAccent: "#282a36",
+    selectionBackground: "#44475a",
+    black: "#21222c",
+    red: "#ff5555",
+    green: "#50fa7b",
+    yellow: "#f1fa8c",
+    blue: "#bd93f9",
+    magenta: "#ff79c6",
+    cyan: "#8be9fd",
+    white: "#f8f8f2",
+    brightBlack: "#6272a4",
+    brightRed: "#ff6e6e",
+    brightGreen: "#69ff94",
+    brightYellow: "#ffffa5",
+    brightBlue: "#d6acff",
+    brightMagenta: "#ff92df",
+    brightCyan: "#a4ffff",
+    brightWhite: "#ffffff",
+  },
+  "github-dark": {
+    name: "github-dark",
+    background: "#0d1117",
+    foreground: "#c9d1d9",
+    cursor: "#c9d1d9",
+    cursorAccent: "#0d1117",
+    selectionBackground: "#264f78",
+    black: "#484f58",
+    red: "#ff7b72",
+    green: "#3fb950",
+    yellow: "#d29922",
+    blue: "#58a6ff",
+    magenta: "#bc8cff",
+    cyan: "#39c5cf",
+    white: "#b1bac4",
+    brightBlack: "#6e7681",
+    brightRed: "#ffa198",
+    brightGreen: "#56d364",
+    brightYellow: "#e3b341",
+    brightBlue: "#79c0ff",
+    brightMagenta: "#d2a8ff",
+    brightCyan: "#56d4dd",
+    brightWhite: "#f0f6fc",
+  },
+  "tokyo-night": {
+    name: "tokyo-night",
+    background: "#1a1b26",
+    foreground: "#c0caf5",
+    cursor: "#c0caf5",
+    cursorAccent: "#1a1b26",
+    selectionBackground: "#33467c",
+    black: "#15161e",
+    red: "#f7768e",
+    green: "#9ece6a",
+    yellow: "#e0af68",
+    blue: "#7aa2f7",
+    magenta: "#bb9af7",
+    cyan: "#7dcfff",
+    white: "#a9b1d6",
+    brightBlack: "#414868",
+    brightRed: "#f7768e",
+    brightGreen: "#9ece6a",
+    brightYellow: "#e0af68",
+    brightBlue: "#7aa2f7",
+    brightMagenta: "#bb9af7",
+    brightCyan: "#7dcfff",
+    brightWhite: "#c0caf5",
+  },
+  "one-dark": {
+    name: "one-dark",
+    background: "#282c34",
+    foreground: "#abb2bf",
+    cursor: "#528bff",
+    cursorAccent: "#282c34",
+    selectionBackground: "#3e4451",
+    black: "#282c34",
+    red: "#e06c75",
+    green: "#98c379",
+    yellow: "#e5c07b",
+    blue: "#61afef",
+    magenta: "#c678dd",
+    cyan: "#56b6c2",
+    white: "#abb2bf",
+    brightBlack: "#5c6370",
+    brightRed: "#e06c75",
+    brightGreen: "#98c379",
+    brightYellow: "#e5c07b",
+    brightBlue: "#61afef",
+    brightMagenta: "#c678dd",
+    brightCyan: "#56b6c2",
+    brightWhite: "#ffffff",
+  },
+};
+
+export const themeNames = Object.keys(themes) as ThemeName[];
+
+export function resolveTheme(theme: ThemeName | Theme | undefined): Theme {
+  if (!theme) return themes["catppuccin-mocha"];
+  if (typeof theme === "string") {
+    const found = themes[theme];
+    if (!found) {
+      throw new Error(`Unknown theme "${theme}". Available: ${themeNames.join(", ")}`);
+    }
+    return found;
+  }
+  return theme;
+}

package/src/timeline.ts

@@ -0,0 +1,58 @@
+import { MARKER } from "./cast";
+import type { CastEvent } from "./types";
+
+export interface TimedEvent {
+  /** Time on the visible (hide-collapsed, speed-adjusted) timeline, seconds. */
+  vt: number;
+  type: CastEvent[1];
+  data: string;
+}
+
+export interface Timeline {
+  events: TimedEvent[];
+  duration: number;
+}
+
+/**
+ * Collapse hidden intervals and apply playback speed. Hidden events keep their relative order but all land
+ * on the instant the hide started, so the first visible frame after `show` reflects their combined effect.
+ * Input (`i`) events are dropped: the PTY already echoed them.
+ */
+export function buildTimeline(events: CastEvent[], playbackSpeed: number): Timeline {
+  const out: TimedEvent[] = [];
+  let hiddenSince: number | null = null;
+  let removed = 0;
+  let duration = 0;
+
+  for (const [t, type, data] of events) {
+    if (type === "m" && data === MARKER.hide) {
+      if (hiddenSince === null) hiddenSince = t;
+      continue;
+    }
+    if (type === "m" && data === MARKER.show) {
+      if (hiddenSince !== null) {
+        removed += t - hiddenSince;
+        hiddenSince = null;
+      }
+      continue;
+    }
+    if (type === "i") continue;
+    const visible = hiddenSince === null ? t - removed : hiddenSince - removed;
+    const vt = visible / playbackSpeed;
+    out.push({ vt, type, data });
+    if (vt > duration) duration = vt;
+  }
+  return { events: out, duration };
+}
+
+const FULL_RESET = "\x1bc";
+
+/** Re-emit `inject` right after any full terminal reset (`ESC c`) so injected state (e.g. palette) survives `reset`. */
+export function withReinjection(events: TimedEvent[], inject: string): TimedEvent[] {
+  const out: TimedEvent[] = [];
+  for (const e of events) {
+    out.push(e);
+    if (e.type === "o" && e.data.includes(FULL_RESET)) out.push({ vt: e.vt, type: "o", data: inject });
+  }
+  return out;
+}