termcut 0.1.0

package/src/cli.ts

@@ -0,0 +1,312 @@
+#!/usr/bin/env bun
+import path from "node:path";
+import { parseArgs } from "node:util";
+import * as api from "./index";
+import { runScriptTests } from "./testing";
+import { themeNames } from "./themes";
+import type { CoreName, ThemeName, VideoConfig, WindowBar } from "./types";
+import { Video, isVideo, renderCast } from "./video";
+
+// Let user scripts `import { defineVideo } from "tcut"` (or "termcut", the npm package name) regardless of
+// where they live or whether this is the compiled binary (no node_modules there): resolve the bare specifier
+// to this very module graph.
+Bun.plugin({
+  name: "tcut-self",
+  setup(build) {
+    for (const specifier of ["tcut", "termcut"]) {
+      build.module(specifier, () => ({ exports: { ...api }, loader: "object" }));
+    }
+  },
+});
+
+const HELP = `tcut — script terminal sessions in TypeScript, render them to video.
+
+Usage:
+  tcut <script.ts> [options]          record + render
+  tcut record <script.ts> [options]   record only (writes the .cast)
+  tcut render <file.cast> [options]   render an existing .cast (tcut or asciinema)
+  tcut test <path...>                 run scripts in fast mode as tests (no video)
+  tcut init [name] [--template t]     scaffold a new script (basic | tour | test)
+  tcut themes                         list built-in themes
+
+Options (override the script's config):
+  -o, --output <path>      .mp4 .webm .gif .webp .svg .html .png .jpg or dir/ for PNG frames — repeatable
+      --theme <name>       ${themeNames.join(" | ")}
+      --font <family>      --font-size <px>  --line-height <x>  --letter-spacing <px>
+      --fps <n>            --speed <x>       playback speed multiplier
+      --padding <px>       --margin <px>     --margin-fill <css-color>   --radius <px>
+      --window-bar <type>  none | colorful | colorfulRight | rings | ringsRight
+      --title <text>       --no-blink
+      --core <name>        ghostty | lite
+      --cast <path>        where to read/write the .cast
+      --record-only        stop after writing the cast
+      --force              ignore the cast cache and re-record
+      --template <name>    for init: basic | tour | test
+  -q, --quiet
+  -h, --help
+`;
+
+const { values, positionals } = parseArgs({
+  args: Bun.argv.slice(2),
+  allowPositionals: true,
+  options: {
+    output: { type: "string", short: "o", multiple: true },
+    theme: { type: "string" },
+    font: { type: "string" },
+    "font-size": { type: "string" },
+    "line-height": { type: "string" },
+    "letter-spacing": { type: "string" },
+    fps: { type: "string" },
+    speed: { type: "string" },
+    padding: { type: "string" },
+    margin: { type: "string" },
+    "margin-fill": { type: "string" },
+    radius: { type: "string" },
+    "window-bar": { type: "string" },
+    title: { type: "string" },
+    "no-blink": { type: "boolean" },
+    core: { type: "string" },
+    cast: { type: "string" },
+    "record-only": { type: "boolean" },
+    force: { type: "boolean" },
+    template: { type: "string" },
+    quiet: { type: "boolean", short: "q" },
+    help: { type: "boolean", short: "h" },
+  },
+});
+
+const quiet = values.quiet === true;
+const log = (msg: string) => {
+  if (!quiet) console.error(msg);
+};
+
+function fail(message: string): never {
+  console.error(`error: ${message}`);
+  process.exit(1);
+}
+
+function num(name: keyof typeof values): number | undefined {
+  const raw = values[name];
+  if (raw === undefined) return undefined;
+  const n = Number(raw);
+  if (!Number.isFinite(n)) fail(`--${String(name)} expects a number, got "${String(raw)}"`);
+  return n;
+}
+
+function overridesFromFlags(): Partial<VideoConfig> {
+  const o: Partial<VideoConfig> = {};
+  if (values.output?.length) o.output = values.output;
+  if (values.theme) o.theme = values.theme as ThemeName;
+  const font: NonNullable<VideoConfig["font"]> = {};
+  if (values.font) font.family = values.font;
+  if (values["font-size"] !== undefined) font.size = num("font-size");
+  if (values["line-height"] !== undefined) font.lineHeight = num("line-height");
+  if (values["letter-spacing"] !== undefined) font.letterSpacing = num("letter-spacing");
+  if (Object.keys(font).length) o.font = font;
+  if (values.fps !== undefined) o.fps = num("fps");
+  if (values.speed !== undefined) o.playbackSpeed = num("speed");
+  if (values.padding !== undefined) o.padding = num("padding");
+  if (values.margin !== undefined) o.margin = num("margin");
+  if (values["margin-fill"]) o.marginFill = values["margin-fill"];
+  if (values.radius !== undefined) o.borderRadius = num("radius");
+  if (values["window-bar"]) o.windowBar = values["window-bar"] as WindowBar;
+  if (values.title !== undefined) o.title = values.title;
+  if (values["no-blink"]) o.cursor = { blink: false };
+  if (values.core) {
+    if (values.core !== "ghostty" && values.core !== "lite") fail("--core must be ghostty or lite");
+    o.core = values.core as CoreName;
+  }
+  if (values.cast) o.cast = values.cast;
+  return o;
+}
+
+async function loadVideo(file: string): Promise<Video> {
+  const abs = path.resolve(file);
+  if (!(await Bun.file(abs).exists())) fail(`Script not found: ${file}`);
+  const mod = (await import(abs)) as { default?: unknown };
+  if (!isVideo(mod.default)) {
+    fail(`${file} must \`export default defineVideo({...}, async (t) => {...})\``);
+  }
+  const video = mod.default;
+  video.source = abs;
+  const overrides = overridesFromFlags();
+  if (Object.keys(overrides).length === 0) return video;
+  const merged = new Video(
+    {
+      ...video.config,
+      promptPattern: new RegExp(video.config.promptPattern),
+      ...overrides,
+      font: { ...video.config.font, ...overrides.font },
+      cursor: { ...video.config.cursor, ...overrides.cursor },
+    },
+    video.script,
+  );
+  merged.source = abs;
+  return merged;
+}
+
+function progressReporter(): (p: { frame: number; total: number }) => void {
+  if (quiet || !process.stderr.isTTY) return () => {};
+  let last = -1;
+  return ({ frame, total }) => {
+    const pct = Math.floor((frame / total) * 100);
+    if (pct === last && frame !== total) return;
+    last = pct;
+    process.stderr.write(`\r  rendering ${frame}/${total} frames (${pct}%)`);
+    if (frame === total) process.stderr.write("\n");
+  };
+}
+
+async function fileSize(file: string): Promise<string> {
+  const f = Bun.file(file);
+  if (!(await f.exists())) return "";
+  const bytes = f.size;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(0)} KB`;
+  return `${(bytes / 1024 / 1024).toFixed(1)} MB`;
+}
+
+async function reportOutputs(outputs: string[], screenshots: string[]): Promise<void> {
+  for (const out of outputs) log(`✔ wrote ${out} ${await fileSize(out)}`);
+  for (const shot of screenshots) log(`✔ screenshot ${shot}`);
+}
+
+const TEMPLATES: Record<string, (name: string) => string> = {
+  basic: (name) => `import { defineVideo } from "tcut";
+
+export default defineVideo(
+  {
+    output: "${name}.mp4",
+    theme: "catppuccin-mocha",
+    cols: 80,
+    rows: 24,
+    typingSpeed: "40ms",
+  },
+  async (t) => {
+    await t.run("echo 'Hello from tcut!'");
+    await t.sleep("1s");
+    await t.type("ls -la");
+    await t.sleep("500ms");
+    await t.enter();
+    await t.wait();
+    await t.sleep("2s");
+  },
+);
+`,
+  tour: (name) => `import { defineVideo } from "tcut";
+
+export default defineVideo(
+  {
+    output: ["${name}.mp4", "${name}.gif", "${name}.svg"],
+    theme: "tokyo-night",
+    cols: 90,
+    rows: 24,
+    typingSpeed: "35ms",
+    typingJitter: 0.3,
+    windowBar: "colorful",
+    title: "${name}",
+    margin: 32,
+    borderRadius: 12,
+  },
+  async (t) => {
+    // Setup that happens but is cut from the video.
+    await t.hide(async () => {
+      await t.run("cd $(mktemp -d) && printf 'alpha\\\\nbeta\\\\n' > notes.txt");
+      await t.clear();
+    });
+
+    await t.run("ls -la");
+    await t.expect(/notes\\.txt/);          // assertion: the script is also a test
+    await t.sleep("800ms");
+
+    await t.type("cat notes.txt");
+    await t.sleep("400ms");
+    await t.enter();
+    await t.wait();                         // prompt is back
+    await t.screenshot("${name}-notes.png");
+    await t.sleep("1.5s");
+  },
+);
+`,
+  test: (name) => `import { defineVideo } from "tcut";
+
+// Run with: tcut test ${name}.tcut.ts   (fast mode: no sleeps, no typing delay)
+export default defineVideo(
+  {
+    output: "${name}.mp4",
+    shell: "bash",
+  },
+  async (t) => {
+    await t.run("echo $((6 * 7))");
+    await t.expect(/^42$/m);
+
+    await t.run("printf 'a\\\\nb\\\\n' | wc -l");
+    await t.expect(/2/);
+
+    await t.run("true && echo ok");
+    await t.expect(/ok/);
+  },
+);
+`,
+};
+
+async function main(): Promise<void> {
+  if (values.help || positionals.length === 0) {
+    console.log(HELP);
+    return;
+  }
+
+  const [first, ...rest] = positionals;
+  const started = performance.now();
+  const elapsed = () => `${((performance.now() - started) / 1000).toFixed(1)}s`;
+
+  switch (first) {
+    case "themes": {
+      for (const name of themeNames) console.log(name);
+      return;
+    }
+    case "init": {
+      const name = rest[0] ?? "demo";
+      const template = values.template ?? "basic";
+      const make = TEMPLATES[template];
+      if (!make) fail(`Unknown template "${template}". Available: ${Object.keys(TEMPLATES).join(", ")}`);
+      const base = name.replace(/\.(video|tcut)\.ts$|\.ts$/, "");
+      const file = name.endsWith(".ts") ? name : template === "test" ? `${base}.tcut.ts` : `${base}.video.ts`;
+      if (await Bun.file(file).exists()) fail(`${file} already exists`);
+      await Bun.write(file, make(path.basename(base)));
+      console.log(`created ${file}\n\nrun it with:\n  ${template === "test" ? `tcut test ${file}` : `tcut ${file}`}`);
+      return;
+    }
+    case "record": {
+      if (!rest[0]) fail("record needs a script file");
+      const video = await loadVideo(rest[0]);
+      const rec = await video.record({ log, force: values.force });
+      log(`✔ ${rec.cached ? "reused" : "wrote"} ${video.config.cast} (${rec.events.length} events, ${(rec.header.duration ?? 0).toFixed(1)}s) in ${elapsed()}`);
+      return;
+    }
+    case "render": {
+      if (!rest[0]) fail("render needs a .cast file");
+      const result = await renderCast(rest[0], overridesFromFlags(), progressReporter());
+      await reportOutputs(result.outputs, result.screenshots);
+      log(`  ${result.frames} frames, ${result.durationSeconds.toFixed(1)}s of video in ${elapsed()}`);
+      return;
+    }
+    case "test": {
+      if (rest.length === 0) fail("test needs at least one script file or directory");
+      const summary = await runScriptTests(rest, (line) => console.log(line));
+      process.exit(summary.failed > 0 ? 1 : 0);
+    }
+    // eslint-disable-next-line no-fallthrough -- process.exit above never returns
+    default: {
+      const video = await loadVideo(first!);
+      const result = await video.run({ log, force: values.force, recordOnly: values["record-only"], onProgress: progressReporter() });
+      log(`✔ ${result.cached ? "reused" : "wrote"} ${result.cast}`);
+      await reportOutputs(result.outputs, result.screenshots);
+      if (!values["record-only"]) log(`  ${result.frames} frames, ${result.durationSeconds.toFixed(1)}s of video in ${elapsed()}`);
+    }
+  }
+}
+
+main().catch((err: unknown) => {
+  console.error(`\nerror: ${err instanceof Error ? err.message : String(err)}`);
+  process.exit(1);
+});

package/src/config.ts

@@ -0,0 +1,84 @@
+import path from "node:path";
+import { toMs } from "./duration";
+import { resolveTheme } from "./themes";
+import type { ResolvedConfig, VideoConfig } from "./types";
+
+export const DEFAULT_FONT_FAMILY =
+  '"JetBrains Mono", "JetBrainsMono Nerd Font Mono", "Fira Code", Menlo, Consolas, "DejaVu Sans Mono", monospace';
+
+function escapeRegExp(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+export function defaultPromptPattern(prompt: string): RegExp {
+  return new RegExp(`${escapeRegExp(prompt.trimEnd())}\\s*$`);
+}
+
+export function resolveConfig(config: VideoConfig): ResolvedConfig {
+  const outputs = Array.isArray(config.output) ? config.output : [config.output];
+  if (outputs.length === 0) throw new Error("config.output must name at least one output");
+
+  const prompt = config.prompt ?? "> ";
+  const theme = resolveTheme(config.theme);
+  const first = outputs[0]!;
+  const castDefault = first.endsWith("/")
+    ? path.join(first, "session.cast")
+    : first.replace(/\.[^./]+$/, "") + ".cast";
+
+  return {
+    output: outputs,
+    cast: config.cast ?? castDefault,
+    shell: config.shell ?? "bash",
+    prompt,
+    promptPattern: (config.promptPattern ?? defaultPromptPattern(prompt)).source,
+    cwd: config.cwd ?? process.cwd(),
+    env: config.env ?? {},
+    cols: config.cols ?? 80,
+    rows: config.rows ?? 24,
+    fps: config.fps ?? 60,
+    typingSpeed: toMs(config.typingSpeed, 50),
+    typingJitter: Math.min(1, Math.max(0, config.typingJitter ?? 0)),
+    seed: config.seed ?? 1,
+    playbackSpeed: config.playbackSpeed ?? 1,
+    waitTimeout: toMs(config.waitTimeout, 15_000),
+    endPause: toMs(config.endPause, 1000),
+    quantize: config.quantize ?? false,
+    core: config.core ?? "ghostty",
+    cache: config.cache ?? true,
+    font: {
+      family: config.font?.family ?? DEFAULT_FONT_FAMILY,
+      size: config.font?.size ?? 20,
+      lineHeight: config.font?.lineHeight ?? 1.2,
+      letterSpacing: config.font?.letterSpacing ?? 0,
+    },
+    theme,
+    cursor: {
+      blink: config.cursor?.blink ?? true,
+      period: config.cursor?.period ?? 1000,
+    },
+    padding: config.padding ?? 24,
+    margin: config.margin ?? 0,
+    marginFill: config.marginFill ?? theme.background,
+    borderRadius: config.borderRadius ?? 0,
+    windowBar: config.windowBar ?? "none",
+    title: config.title ?? "",
+  };
+}
+
+/** Apply partial user overrides on top of an already-resolved config (used by `render --theme …`). */
+export function applyOverrides(base: ResolvedConfig, overrides: Partial<VideoConfig> | undefined): ResolvedConfig {
+  if (!overrides) return base;
+  const merged: VideoConfig = {
+    ...base,
+    promptPattern: new RegExp(base.promptPattern),
+    ...overrides,
+    font: { ...base.font, ...overrides.font },
+    cursor: { ...base.cursor, ...overrides.cursor },
+    output: overrides.output ?? base.output,
+  };
+  // marginFill should follow a new theme unless explicitly set
+  if (overrides.theme && !overrides.marginFill) delete (merged as Partial<VideoConfig>).marginFill;
+  const resolved = resolveConfig(merged);
+  if (!overrides.cast) resolved.cast = base.cast;
+  return resolved;
+}

package/src/duration.ts

@@ -0,0 +1,21 @@
+import type { Duration } from "./types";
+
+const units: Record<string, number> = { ms: 1, s: 1000, m: 60_000 };
+
+/** "500ms" → 500, "1.5s" → 1500, "2m" → 120000, 250 → 250. Bare numbers are milliseconds. */
+export function toMs(value: Duration | undefined, fallback = 0): number {
+  if (value === undefined) return fallback;
+  if (typeof value === "number") {
+    if (!Number.isFinite(value) || value < 0) throw new Error(`Invalid duration ${value}`);
+    return value;
+  }
+  const match = /^\s*(\d+(?:\.\d+)?)\s*(ms|s|m)?\s*$/.exec(value);
+  if (!match) throw new Error(`Invalid duration "${value}" (use e.g. 500, "500ms", "1.5s", "2m")`);
+  const unit = match[2] ?? "ms";
+  return Number(match[1]) * units[unit]!;
+}
+
+export function formatMs(ms: number): string {
+  if (ms < 1000) return `${Math.round(ms)}ms`;
+  return `${(ms / 1000).toFixed(ms % 1000 === 0 ? 0 : 1)}s`;
+}

package/src/export/frames.ts

@@ -0,0 +1,142 @@
+import type { CellData, TerminalCore } from "@wterm/core";
+import { themeOsc } from "../renderer/page";
+import { loadCore } from "../screen";
+import { buildTimeline, withReinjection } from "../timeline";
+import type { Recording, ResolvedConfig, Theme } from "../types";
+
+export const FLAG = {
+  bold: 0x01,
+  dim: 0x02,
+  italic: 0x04,
+  underline: 0x08,
+  reverse: 0x20,
+  invisible: 0x40,
+  strike: 0x80,
+} as const;
+
+export interface GridCell {
+  text: string;
+  /** 1 = normal, 2 = wide (next cell is a continuation and is omitted). */
+  width: 1 | 2;
+  /** Resolved CSS hex colour, or null for the theme default. */
+  fg: string | null;
+  bg: string | null;
+  flags: number;
+}
+
+export interface GridFrame {
+  /** Start time on the visible timeline, seconds. */
+  time: number;
+  /** How long this frame is shown, seconds. */
+  hold: number;
+  cols: number;
+  rows: number;
+  /** Sparse rows: index → cells (rows that are entirely blank/default are omitted). */
+  rows_: Map<number, GridCell[]>;
+  cursor: { row: number; col: number; visible: boolean };
+}
+
+export interface GridReplay {
+  frames: GridFrame[];
+  duration: number;
+  cols: number;
+  rows: number;
+}
+
+const ANSI: (keyof Theme)[] = [
+  "black", "red", "green", "yellow", "blue", "magenta", "cyan", "white",
+  "brightBlack", "brightRed", "brightGreen", "brightYellow", "brightBlue", "brightMagenta", "brightCyan", "brightWhite",
+];
+
+const hex = (n: number) => `#${(n & 0xffffff).toString(16).padStart(6, "0")}`;
+
+/** Resolve a wterm colour (palette index 0–255, 256 = default, or packed RGB) to CSS. */
+export function resolveColor(index: number, rgb: number | undefined, theme: Theme): string | null {
+  if (rgb !== undefined) return hex(rgb);
+  if (index === 256) return null;
+  if (index < 16) return theme[ANSI[index]!] as string;
+  if (index < 232) {
+    const n = index - 16;
+    const r = Math.floor(n / 36) * 51;
+    const g = (Math.floor(n / 6) % 6) * 51;
+    const b = (n % 6) * 51;
+    return hex((r << 16) | (g << 8) | b);
+  }
+  const level = (index - 232) * 10 + 8;
+  return hex((level << 16) | (level << 8) | level);
+}
+
+function toGridCell(cell: CellData, theme: Theme): GridCell {
+  let fg = resolveColor(cell.fg, cell.fgRgb, theme);
+  let bg = resolveColor(cell.bg, cell.bgRgb, theme);
+  if (cell.flags & FLAG.reverse) {
+    [fg, bg] = [bg ?? theme.background, fg ?? theme.foreground];
+  }
+  const text = cell.chars ?? (cell.char === 0 ? " " : String.fromCodePoint(cell.char));
+  return { text, width: cell.width === 2 ? 2 : 1, fg, bg, flags: cell.flags & ~FLAG.reverse };
+}
+
+function snapshot(core: TerminalCore, theme: Theme): { rows: Map<number, GridCell[]>; key: string } {
+  const rows = new Map<number, GridCell[]>();
+  const keyParts: string[] = [];
+  const cols = core.getCols();
+  for (let y = 0; y < core.getRows(); y++) {
+    const cells: GridCell[] = [];
+    let meaningful = false;
+    for (let x = 0; x < cols; x++) {
+      const raw = core.getCell(y, x);
+      if (raw.width === 0) continue;
+      const cell = toGridCell(raw, theme);
+      if (cell.text !== " " || cell.bg !== null || cell.flags & (FLAG.underline | FLAG.strike)) meaningful = true;
+      cells.push(cell);
+    }
+    if (meaningful) {
+      rows.set(y, cells);
+      keyParts.push(`${y}:${cells.map((c) => `${c.text}${c.fg ?? ""}${c.bg ?? ""}${c.flags}`).join("")}`);
+    }
+  }
+  return { rows, key: keyParts.join("\n") };
+}
+
+/**
+ * Replay the visible timeline into a headless core and return de-duplicated grid snapshots with hold durations.
+ * This is the shared source for vector/text exporters (SVG, and anything else that doesn't need pixels).
+ */
+export async function replayFrames(rec: Recording, config: ResolvedConfig): Promise<GridReplay> {
+  const core = await loadCore(config.core);
+  core.init(rec.header.width, rec.header.height);
+
+  const timeline = buildTimeline(rec.events, config.playbackSpeed);
+  const osc = themeOsc(config.theme);
+  const events = config.core === "lite" ? timeline.events : withReinjection(timeline.events, osc);
+  if (config.core !== "lite") core.writeString(osc);
+
+  const fps = config.fps;
+  const totalFrames = Math.max(1, Math.ceil(timeline.duration * fps) + 1);
+  const frames: GridFrame[] = [];
+  let pointer = 0;
+  let lastKey: string | null = null;
+
+  for (let i = 0; i < totalFrames; i++) {
+    const time = i / fps;
+    while (pointer < events.length && events[pointer]!.vt <= time + 1e-9) {
+      const e = events[pointer++]!;
+      if (e.type === "o") core.writeString(e.data);
+      else if (e.type === "r") {
+        const [c, r] = e.data.split("x").map(Number);
+        if (c! > 0 && r! > 0) core.resize(c!, r!);
+      }
+    }
+    const cursor = core.getCursor();
+    const { rows, key } = snapshot(core, config.theme);
+    const fullKey = `${key}|${cursor.row},${cursor.col},${cursor.visible}|${core.getCols()}x${core.getRows()}`;
+    if (fullKey === lastKey && frames.length > 0) {
+      frames[frames.length - 1]!.hold += 1 / fps;
+      continue;
+    }
+    lastKey = fullKey;
+    frames.push({ time, hold: 1 / fps, cols: core.getCols(), rows: core.getRows(), rows_: rows, cursor });
+  }
+
+  return { frames, duration: totalFrames / fps, cols: rec.header.width, rows: rec.header.height };
+}

package/src/export/html.ts

@@ -0,0 +1,88 @@
+import { mkdir } from "node:fs/promises";
+import path from "node:path";
+import { barHeight } from "../renderer/page";
+import { pageAssets } from "../renderer/bundle";
+import { buildTimeline } from "../timeline";
+import type { Recording, ResolvedConfig, Theme } from "../types";
+
+const ANSI_ORDER: (keyof Theme)[] = [
+  "black", "red", "green", "yellow", "blue", "magenta", "cyan", "white",
+  "brightBlack", "brightRed", "brightGreen", "brightYellow", "brightBlue", "brightMagenta", "brightCyan", "brightWhite",
+];
+
+function escapeHtml(s: string): string {
+  return s.replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]!);
+}
+
+function windowBar(config: ResolvedConfig): string {
+  if (config.windowBar === "none") return "";
+  const rings = config.windowBar.startsWith("rings");
+  const right = config.windowBar.endsWith("Right");
+  const dot = (c: string) => `<span class="dot" style="${rings ? `border:2px solid ${c}` : `background:${c}`}"></span>`;
+  const dots = `<div class="dots">${dot("#ff5f57")}${dot("#febc2e")}${dot("#28c840")}</div>`;
+  const title = `<div class="title">${escapeHtml(config.title)}</div>`;
+  return `<div id="bar" class="${right ? "right" : ""}">${right ? title + dots : dots + title}</div>`;
+}
+
+/** Single-file HTML player: cast + theme + lite core + controls. Works from file://. */
+export async function buildHtml(rec: Recording, config: ResolvedConfig): Promise<string> {
+  const assets = await pageAssets();
+  const { events, duration } = buildTimeline(rec.events, config.playbackSpeed);
+  const { theme, font } = config;
+  const data = {
+    cols: rec.header.width,
+    rows: rec.header.height,
+    duration,
+    speed: 1,
+    events: events.filter((e) => e.type === "o" || e.type === "r").map(({ vt, type, data }) => ({ vt, type, data })),
+  };
+  // "</script>" inside the JSON would terminate the data block; escape it.
+  const json = JSON.stringify(data).replace(/<\//g, "<\\/");
+  const vars = [
+    `--term-fg:${theme.foreground}`,
+    `--term-bg:${theme.background}`,
+    `--term-cursor:${theme.cursor ?? theme.foreground}`,
+    ...ANSI_ORDER.map((k, i) => `--term-color-${i}:${theme[k]}`),
+  ].join(";");
+
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${escapeHtml(config.title || "tcut recording")}</title>
+<style>
+${assets.css}
+html, body { margin: 0; background: ${config.marginFill}; min-height: 100vh; display: flex; align-items: center; justify-content: center; }
+#frame { display: inline-block; background: ${theme.background}; border-radius: ${config.borderRadius}px; padding: ${config.padding}px; margin: ${config.margin}px; box-shadow: 0 12px 40px rgba(0,0,0,.35); }
+#bar { height: ${barHeight(config)}px; margin-top: -${Math.min(config.padding, 12)}px; display: flex; align-items: center; justify-content: space-between; font: 13px -apple-system, "Segoe UI", Helvetica, Arial, sans-serif; color: ${theme.foreground}; }
+#bar .dots { display: flex; gap: 8px; } #bar .dot { width: 12px; height: 12px; border-radius: 50%; box-sizing: border-box; display: inline-block; }
+#bar .title { flex: 1; text-align: center; opacity: .7; } #bar.right .title { text-align: left; }
+#term.wterm { ${vars}; --term-font-family: ${font.family}; --term-font-size: ${font.size}px; --term-line-height: ${font.lineHeight}; --term-row-height: ${Math.ceil(font.size * font.lineHeight)}px; letter-spacing: ${font.letterSpacing}px; padding: 0; border-radius: 0; box-shadow: none; background: transparent; cursor: pointer; }
+#controls { display: flex; gap: 12px; align-items: center; margin-top: 12px; font: 12px -apple-system, "Segoe UI", Helvetica, Arial, sans-serif; color: ${theme.foreground}; opacity: .85; }
+#controls button { background: transparent; color: inherit; border: 1px solid currentColor; border-radius: 6px; width: 34px; height: 26px; cursor: pointer; }
+#controls input[type=range] { flex: 1; accent-color: ${theme.cursor ?? theme.foreground}; }
+#controls label { display: flex; gap: 4px; align-items: center; }
+</style>
+</head>
+<body>
+<div id="frame">
+  ${windowBar(config)}
+  <div id="term"></div>
+  <div id="controls">
+    <button id="play" title="Play / pause">▶</button>
+    <input id="progress" type="range" min="0" max="1000" value="0">
+    <span id="time">0:00</span>
+    <label><input id="loop" type="checkbox" checked> loop</label>
+  </div>
+</div>
+<script type="application/json" id="tcut-cast">${json}</script>
+<script type="module">${assets.playerJs}</script>
+</body>
+</html>`;
+}
+
+export async function writeHtml(rec: Recording, config: ResolvedConfig, file: string): Promise<void> {
+  await mkdir(path.dirname(path.resolve(file)), { recursive: true });
+  await Bun.write(file, await buildHtml(rec, config));
+}