termcut 0.5.1 → 0.6.1

package/README.md

@@ -51,6 +51,8 @@ defineVideo({ output: "demo.mp4", browser: { position: "overlay" } }, async (t)
 });
 ```
 
+Polish: `keys: true` shows key presses, `maxPause: "800ms"` cuts dead air, `t.zoom({ rows: [0, 5] })` magnifies output, `t.chapter("Install")` adds mp4 chapters, `preset: "x"` sizes it for X. `tcut diff a.cast b.cast` catches output changes in CI.
+
 Re-render any recording without re-running it — ~600 themes ([Ghostty's collection](https://github.com/mbadolato/iTerm2-Color-Schemes)), `tcut themes` lists them:
 
 ```sh

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "termcut",
-  "version": "0.5.1",
+  "version": "0.6.1",
   "description": "Script terminal sessions in TypeScript, render them to reproducible MP4/GIF/WebM/SVG/HTML with Bun.",
   "license": "MIT",
   "author": "Aman Varshney",

package/src/browser.ts

@@ -0,0 +1,135 @@
+import { WINDOW_BAR_HEIGHT, estimateCell } from "./config";
+import { toMs } from "./duration";
+import { WaitTimeoutError } from "./errors";
+import type { BrowserFrame, BrowserSession, ResolvedConfig } from "./types";
+
+export interface BrowserCapture extends BrowserSession {
+  /** Frames captured so far (only when the page's pixels changed). */
+  frames: BrowserFrame[];
+  /** Stop sampling and close the WebView. */
+  stop(): Promise<void>;
+}
+
+/** "better-t-stack.dev" → "https://better-t-stack.dev"; localhost defaults to http. */
+export function normalizeUrl(url: string): string {
+  if (/^[a-z][a-z0-9+.-]*:\/\//i.test(url) || /^(about|data|file|blob):/i.test(url)) return url;
+  return /^(localhost|127\.|0\.0\.0\.0|\[::1\])/.test(url) ? `http://${url}` : `https://${url}`;
+}
+
+const toRegExp = (pattern: RegExp | string): RegExp =>
+  typeof pattern === "string" ? new RegExp(pattern.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")) : pattern;
+
+/**
+ * A Bun.WebView sampled on the recording clock, shared by scripted and live recording. Only changed frames are
+ * kept; every WebView call is bounded by a timeout so a stuck page can never hang a recording.
+ */
+export function startBrowserCapture(config: ResolvedConfig, stamp: () => number, log: (m: string) => void = () => {}): BrowserCapture {
+  if (!config.browser) throw new Error("startBrowserCapture needs config.browser");
+  if (typeof Bun.WebView !== "function") throw new Error("The browser pane needs Bun.WebView (Bun >= 1.4).");
+  const bcfg = config.browser;
+
+  // Default pane size: match the terminal window (estimated from the font metrics) unless given.
+  const est = estimateCell(config.font);
+  const termFrameH = Math.round(config.rows * est.h + config.padding * 2 + (config.windowBar === "none" ? 0 : WINDOW_BAR_HEIGHT));
+  const termFrameW = Math.round(config.cols * est.w + config.padding * 2);
+  const stacked = bcfg.position === "top" || bcfg.position === "bottom";
+  const paneW = stacked ? termFrameW : bcfg.width;
+  const paneH = bcfg.height || (stacked || bcfg.position === "overlay" ? 480 : termFrameH);
+  const view = new Bun.WebView({ width: paneW, height: paneH });
+
+  const frames: BrowserFrame[] = [];
+  const within = <T,>(promise: Promise<T>, ms: number, label: string): Promise<T> =>
+    Promise.race([promise, Bun.sleep(ms).then(() => Promise.reject(new Error(`browser.${label} did not finish within ${ms}ms`)))]);
+
+  let currentUrl = bcfg.url ?? "about:blank";
+  let lastHash = "";
+  let running = true;
+  const sampler = (async () => {
+    while (running) {
+      try {
+        const png = (await within(view.screenshot({ encoding: "buffer" }), 5000, "screenshot")) as Uint8Array;
+        const hash = Bun.hash(png).toString(16);
+        if (hash !== lastHash) {
+          lastHash = hash;
+          frames.push({ time: stamp(), png });
+        }
+      } catch {
+        /* view busy or closed */
+      }
+      await Bun.sleep(1000 / bcfg.fps);
+    }
+  })();
+
+  /**
+   * Navigate and wait for the page to be there. Dev servers may still be starting (connection refused → retry)
+   * or take a long first load (Vite pre-bundling, then a reload), so success is judged by the document's
+   * readyState at the target URL rather than by the navigate() promise alone.
+   */
+  const goto = async (rawUrl: string): Promise<void> => {
+    const url = normalizeUrl(rawUrl);
+    const deadline = performance.now() + config.waitTimeout;
+    const target = url.replace(/\/$/, "");
+    let navigation: Promise<"ok" | "pending" | "failed"> | null = null;
+    for (;;) {
+      if (!running) return; // stop() closed the view mid-retry; abort quietly
+      try {
+        navigation ??= view.navigate(url).then(
+        () => "ok" as const,
+          (err: unknown) => (/pending/i.test(String(err)) ? ("pending" as const) : ("failed" as const)),
+        );
+      } catch {
+        return; // navigate threw synchronously: the view is closed
+      }
+      const outcome = await Promise.race([navigation, Bun.sleep(750).then(() => "tick" as const)]);
+      if (outcome === "ok") {
+        currentUrl = url;
+        return;
+      }
+      if (outcome === "failed") navigation = null;
+      if (!running) return;
+      const state = await within(view.evaluate("document.readyState"), 3000, "goto").catch(() => "");
+      if (state === "complete" && (view.url ?? "").replace(/\/$/, "").startsWith(target)) {
+        currentUrl = url;
+        return;
+      }
+      if (performance.now() > deadline) {
+        throw new WaitTimeoutError(`browser.goto(${url})`, config.waitTimeout, `current url: ${view.url ?? "(none)"}, readyState: ${state || "unknown"}`);
+      }
+      await Bun.sleep(250);
+    }
+  };
+
+  const capture: BrowserCapture = {
+    frames,
+    get url() {
+      return currentUrl;
+    },
+    goto,
+    async waitFor(pattern, waitOpts = {}) {
+      const regex = toRegExp(pattern);
+      const timeout = toMs(waitOpts.timeout, config.waitTimeout);
+      const deadline = performance.now() + timeout;
+      for (;;) {
+        const text = String((await within(view.evaluate("document.body ? document.body.innerText : ''"), 5000, "waitFor").catch(() => "")) ?? "");
+        if (regex.test(text)) return;
+        if (performance.now() > deadline) throw new WaitTimeoutError(`${regex} in the browser page`, timeout, text.slice(0, 2000));
+        await Bun.sleep(150);
+      }
+    },
+    click: (selector) => within(view.click(selector), 10000, "click"),
+    reload: () => within(view.reload(), 30000, "reload").catch((err) => (/pending/i.test(String(err)) ? undefined : Promise.reject(err))),
+    evaluate: (js) => within(view.evaluate(js), 10000, "evaluate"),
+    async stop() {
+      running = false;
+      await sampler;
+      try {
+        view.close();
+      } catch {
+        /* closed */
+      }
+    },
+  };
+
+  if (bcfg.url) void goto(bcfg.url).catch((err) => log(String(err)));
+  return capture;
+}

package/src/cast.ts

@@ -42,5 +42,7 @@ export const MARKER = {
   show: "show",
   screenshot: "screenshot:",
   focus: "focus:",
+  zoom: "zoom:",
+  chapter: "chapter:",
   end: "end",
 } as const;

package/src/cli.ts

@@ -7,12 +7,14 @@ import { resolveConfig } from "./config";
 import * as api from "./index";
 import { recordLive } from "./live";
 import { ensurePublicBucket, loadPublishConfig, publicUrlFor, publishFiles, savePublishConfig, type PublishConfig } from "./publish";
+import { diffCasts } from "./diff";
+import { presetNames, type PresetName } from "./presets";
 import { renderOutputs } from "./render";
 import { generateScript } from "./scriptgen";
 import { runScriptTests } from "./testing";
 import { findThemes, themeNames } from "./themes";
-import type { CoreName, ThemeName, VideoConfig, WindowBar } from "./types";
-import { Video, isVideo, renderCast } from "./video";
+import type { BrowserConfig, CoreName, ThemeName, VideoConfig, WindowBar } from "./types";
+import { Video, attachBrowserFrames, 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
@@ -34,6 +36,7 @@ Usage:
   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 diff <a.cast> <b.cast>         compare what two recordings show on screen (exit 1 if different)
   tcut publish <files...> [--open]    upload to your S3-compatible bucket and print share links
   tcut publish --setup                configure the bucket (RustFS, MinIO, R2, S3 …) — once
   tcut init [name] [--template t]     scaffold a new script (basic | tour | test)
@@ -51,6 +54,12 @@ Options (override the script's config):
       --cols <n> --rows <n>  terminal grid (rec: defaults to your terminal's size)
       --width <px> --height <px>  video size; the grid is derived and centred inside
       --loop-offset <n|N%> where GIF/WebP loops start
+      --max-pause <dur>    idle compression: cap gaps between events (e.g. 800ms)
+      --keys               show recent key presses as chips
+      --preset <name>      readme | x | youtube | square
+      --browser <url>      rec: record a browser window too (--browser-position right|left|top|bottom|overlay)
+      --at <seconds>       diff: compare the screen at this time instead of the end
+      --images <dir>       diff: also write a.png / b.png
       --cast <path>        where to read/write the .cast
       --record-only        stop after writing the cast
       --no-script          rec: don't write the editable <name>.video.ts next to the cast
@@ -89,6 +98,13 @@ const { values, positionals } = parseArgs({
     width: { type: "string" },
     height: { type: "string" },
     "loop-offset": { type: "string" },
+    "max-pause": { type: "string" },
+    keys: { type: "boolean" },
+    preset: { type: "string" },
+    browser: { type: "string" },
+    "browser-position": { type: "string" },
+    at: { type: "string" },
+    images: { type: "string" },
     cast: { type: "string" },
     "record-only": { type: "boolean" },
     "no-script": { type: "boolean" },
@@ -169,6 +185,17 @@ function overridesFromFlags(): Partial<VideoConfig> {
   if (values.width !== undefined) o.width = num("width");
   if (values.height !== undefined) o.height = num("height");
   if (values["loop-offset"] !== undefined) o.loopOffset = values["loop-offset"];
+  if (values["max-pause"] !== undefined) o.maxPause = values["max-pause"];
+  if (values.keys) o.keys = true;
+  if (values.preset) {
+    if (!presetNames.includes(values.preset as PresetName)) fail(`--preset must be one of ${presetNames.join(", ")}`);
+    o.preset = values.preset as PresetName;
+  }
+  if (values.browser) {
+    const position = values["browser-position"] as BrowserConfig["position"] | undefined;
+    if (position && !["right", "left", "top", "bottom", "overlay"].includes(position)) fail("--browser-position must be right, left, top, bottom or overlay");
+    o.browser = { url: values.browser, ...(position && { position }) };
+  }
   return o;
 }
 
@@ -388,7 +415,9 @@ async function main(): Promise<void> {
         rows: overrides.rows ?? (sized ? config.rows : undefined),
       });
       await mkdir(path.dirname(path.resolve(config.cast)), { recursive: true });
+      await attachBrowserFrames(recording, path.resolve(config.cast));
       await writeCast(config.cast, recording);
+      recording.source = path.resolve(config.cast);
       log("");
       ok(`wrote ${config.cast}`, `${recording.events.length} events, ${(recording.header.duration ?? 0).toFixed(1)}s`);
       if (!values["no-script"]) {
@@ -422,6 +451,20 @@ async function main(): Promise<void> {
       emit({ cast: rest[0], outputs: files, frames: result.frames, durationSeconds: result.durationSeconds });
       return;
     }
+    case "diff": {
+      if (rest.length < 2) fail("diff needs two .cast files");
+      const result = await diffCasts(rest[0]!, rest[1]!, { at: values.at !== undefined ? num("at") : undefined, images: values.images });
+      emit(result);
+      if (!json) {
+        if (result.equal) ok("screens match");
+        else {
+          for (const line of result.lines) log(line.startsWith("- ") ? red(line) : line.startsWith("+ ") ? green(line) : dim(line));
+          if (result.images) log(dim(`  images: ${result.images.a}  ${result.images.b}`));
+        }
+      }
+      process.exit(result.equal ? 0 : 1);
+    }
+    // eslint-disable-next-line no-fallthrough -- process.exit above never returns
     case "test": {
       if (rest.length === 0) fail("test needs at least one script file or directory");
       const summary = await runScriptTests(rest, json ? () => {} : (line) => console.log(line));

package/src/config.ts

@@ -1,5 +1,6 @@
 import path from "node:path";
 import { toMs } from "./duration";
+import { applyPreset } from "./presets";
 import { resolveTheme } from "./themes";
 import type { ResolvedConfig, VideoConfig } from "./types";
 
@@ -21,7 +22,8 @@ export function estimateCell(font: { size: number; lineHeight: number; letterSpa
 
 export const WINDOW_BAR_HEIGHT = 36;
 
-export function resolveConfig(config: VideoConfig): ResolvedConfig {
+export function resolveConfig(input: VideoConfig): ResolvedConfig {
+  const config = applyPreset(input);
   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");
 
@@ -60,6 +62,15 @@ export function resolveConfig(config: VideoConfig): ResolvedConfig {
     ...(config.width !== undefined && { width: config.width }),
     ...(config.height !== undefined && { height: config.height }),
     ...(config.loopOffset !== undefined && { loopOffset: config.loopOffset }),
+    ...(config.maxPause !== undefined && { maxPause: toMs(config.maxPause) / 1000 }),
+    ...(config.keys && {
+      keys: {
+        position: (config.keys === true ? undefined : config.keys.position) ?? "bottom",
+        ttl: toMs(config.keys === true ? undefined : config.keys.ttl, 1200),
+        merge: toMs(config.keys === true ? undefined : config.keys.merge, 350),
+        limit: (config.keys === true ? undefined : config.keys.limit) ?? 1,
+      },
+    }),
     fps: config.fps ?? 60,
     typingSpeed: toMs(config.typingSpeed, 50),
     typingJitter: Math.min(1, Math.max(0, config.typingJitter ?? 0)),

package/src/diff.ts

@@ -0,0 +1,91 @@
+import path from "node:path";
+import { readCast } from "./cast";
+import { applyOverrides, resolveConfig } from "./config";
+import { replayFrames, type GridFrame } from "./export/frames";
+import { renderOutputs } from "./render";
+import type { Recording, ResolvedConfig } from "./types";
+
+export interface DiffOptions {
+  /** Compare the screen at this time on the visible timeline (seconds). Default: the last frame. */
+  at?: number;
+  /** Write `a.png` / `b.png` of the compared frames into this directory. */
+  images?: string;
+}
+
+export interface DiffResult {
+  equal: boolean;
+  a: string[];
+  b: string[];
+  /** Unified-ish diff lines ("  same", "- only in a", "+ only in b"). */
+  lines: string[];
+  images?: { a: string; b: string };
+}
+
+function frameAt(frames: GridFrame[], at: number | undefined): GridFrame {
+  if (at === undefined) return frames[frames.length - 1]!;
+  let chosen = frames[0]!;
+  for (const f of frames) if (f.time <= at + 1e-9) chosen = f;
+  return chosen;
+}
+
+function rowsText(frame: GridFrame): string[] {
+  const out: string[] = [];
+  for (let y = 0; y < frame.rows; y++) {
+    const cells = frame.rows_.get(y);
+    out.push(cells ? cells.map((c) => c.text).join("").replace(/\s+$/, "") : "");
+  }
+  while (out.length && out[out.length - 1] === "") out.pop();
+  return out;
+}
+
+/** Simple LCS-based line diff — screens are small, so O(n·m) is fine. */
+function diffLines(a: string[], b: string[]): string[] {
+  const n = a.length;
+  const m = b.length;
+  const dp: number[][] = Array.from({ length: n + 1 }, () => new Array<number>(m + 1).fill(0));
+  for (let i = n - 1; i >= 0; i--) for (let j = m - 1; j >= 0; j--) dp[i]![j] = a[i] === b[j] ? dp[i + 1]![j + 1]! + 1 : Math.max(dp[i + 1]![j]!, dp[i]![j + 1]!);
+  const out: string[] = [];
+  let i = 0;
+  let j = 0;
+  while (i < n && j < m) {
+    if (a[i] === b[j]) {
+      out.push(`  ${a[i]}`);
+      i++;
+      j++;
+    } else if (dp[i + 1]![j]! >= dp[i]![j + 1]!) {
+      out.push(`- ${a[i]}`);
+      i++;
+    } else {
+      out.push(`+ ${b[j]}`);
+      j++;
+    }
+  }
+  while (i < n) out.push(`- ${a[i++]}`);
+  while (j < m) out.push(`+ ${b[j++]}`);
+  return out;
+}
+
+async function screenOf(rec: Recording, at: number | undefined): Promise<{ text: string[]; config: ResolvedConfig }> {
+  const base = rec.header.bunVideo ?? resolveConfig({ output: "x.svg", cols: rec.header.width, rows: rec.header.height });
+  const config = applyOverrides(base, {});
+  const replay = await replayFrames(rec, config);
+  return { text: rowsText(frameAt(replay.frames, at)), config };
+}
+
+/** Compare what two recordings show on screen (text, not pixels) at the end or at a given time. */
+export async function diffCasts(fileA: string, fileB: string, opts: DiffOptions = {}): Promise<DiffResult> {
+  const [recA, recB] = await Promise.all([readCast(fileA), readCast(fileB)]);
+  const [a, b] = await Promise.all([screenOf(recA, opts.at), screenOf(recB, opts.at)]);
+  const equal = a.text.length === b.text.length && a.text.every((line, i) => line === b.text[i]);
+  const result: DiffResult = { equal, a: a.text, b: b.text, lines: equal ? [] : diffLines(a.text, b.text) };
+  if (opts.images) {
+    const dir = path.resolve(opts.images);
+    const pa = path.join(dir, "a.png");
+    const pb = path.join(dir, "b.png");
+    const speedA = opts.at === undefined ? 1 : 1; // stills are the final frame; `at` applies to text only
+    await renderOutputs(recA, { ...a.config, output: [pa], playbackSpeed: speedA });
+    await renderOutputs(recB, { ...b.config, output: [pb], playbackSpeed: speedA });
+    result.images = { a: pa, b: pb };
+  }
+  return result;
+}

package/src/errors.ts

@@ -0,0 +1,15 @@
+import { formatMs } from "./duration";
+
+export class WaitTimeoutError extends Error {
+  constructor(what: string, timeoutMs: number, screen: string) {
+    super(`Timed out after ${formatMs(timeoutMs)} waiting for ${what}.\n\n--- screen ---\n${screen}\n--------------`);
+    this.name = "WaitTimeoutError";
+  }
+}
+
+export class ExpectationError extends Error {
+  constructor(what: string, screen: string) {
+    super(`Expected ${what} to match.\n\n--- screen ---\n${screen}\n--------------`);
+    this.name = "ExpectationError";
+  }
+}

package/src/index.ts

@@ -16,6 +16,11 @@ export { publishFiles, loadPublishConfig, savePublishConfig, ensurePublicBucket,
 export type { PublishConfig, Published, PublishOptions } from "./publish";
 export { readCast, writeCast, parseCast, serializeCast } from "./cast";
 export { buildTimeline } from "./timeline";
+export { presets, presetNames, applyPreset } from "./presets";
+export { diffCasts } from "./diff";
+export type { DiffOptions, DiffResult } from "./diff";
+export { keyLabels, keyChips } from "./keylabels";
+export { startBrowserCapture } from "./browser";
 export { resolveConfig } from "./config";
 export { WaitTimeoutError, ExpectationError } from "./recorder";
 export type * from "./types";

package/src/keylabels.ts

@@ -0,0 +1,81 @@
+import { tokenize } from "./scriptgen";
+
+const NAMED: Record<string, string> = {
+  "\r": "⏎",
+  "\n": "⏎",
+  "\t": "⇥",
+  "\x1b[Z": "⇧⇥",
+  "\x7f": "⌫",
+  "\x1b": "esc",
+  "\x1b[A": "↑",
+  "\x1b[B": "↓",
+  "\x1b[C": "→",
+  "\x1b[D": "←",
+  "\x1bOA": "↑",
+  "\x1bOB": "↓",
+  "\x1bOC": "→",
+  "\x1bOD": "←",
+  "\x1b[1;2A": "⇧↑",
+  "\x1b[1;2B": "⇧↓",
+  "\x1b[1;2C": "⇧→",
+  "\x1b[1;2D": "⇧←",
+  "\x1b[H": "home",
+  "\x1b[F": "end",
+  "\x1b[3~": "del",
+  "\x1b[5~": "pgup",
+  "\x1b[6~": "pgdn",
+};
+
+/** Human-readable labels for a raw input chunk: printable runs stay words, control sequences become symbols. */
+export function keyLabels(input: string): string[] {
+  const labels: string[] = [];
+  for (const token of tokenize(input)) {
+    if (token === " ") { labels.push(" "); continue; }
+    const named = NAMED[token];
+    if (named) {
+      labels.push(named);
+    } else if (token.length === 1 && token.charCodeAt(0) < 32) {
+      labels.push(`⌃${String.fromCharCode(token.charCodeAt(0) + 64)}`);
+    } else if (token.length === 2 && token[0] === "\x1b") {
+      labels.push(`⌥${token[1]}`);
+    } else if (token.startsWith("\x1b[<")) {
+      labels.push(/M$/.test(token) && /^\x1b\[<6[45]/.test(token) ? "wheel" : "mouse");
+    } else if (token.startsWith("\x1b")) {
+      labels.push("esc…");
+    } else {
+      labels.push(token);
+    }
+  }
+  return labels;
+}
+
+export interface KeyChip {
+  /** Time the chip appeared (visible timeline, seconds). */
+  at: number;
+  label: string;
+}
+
+/**
+ * Turn timed input events into chips. Printable keystrokes within `mergeWithin` seconds of each other are merged
+ * into one chip (so typing reads as words, not a flood of letters); named keys always get their own chip.
+ */
+export function keyChips(inputs: Array<{ vt: number; data: string }>, mergeWithin = 0.35): KeyChip[] {
+  const chips: KeyChip[] = [];
+  let lastPrintable: KeyChip | null = null;
+  let lastTime = -Infinity;
+  for (const { vt, data } of inputs) {
+    for (const label of keyLabels(data)) {
+      const printable = !/^[⏎⇥⌫␣↑↓→←⌃⌥⇧]|^(esc|home|end|del|pgup|pgdn|wheel|mouse)/.test(label);
+      if (printable && lastPrintable && vt - lastTime <= mergeWithin) {
+        lastPrintable.label += label;
+        lastPrintable.at = vt;
+      } else {
+        const chip = { at: vt, label };
+        chips.push(chip);
+        lastPrintable = printable ? chip : null;
+      }
+      lastTime = vt;
+    }
+  }
+  return chips;
+}

package/src/live.ts

@@ -1,3 +1,4 @@
+import { startBrowserCapture } from "./browser";
 import { MARKER } from "./cast";
 import { shellSetup } from "./recorder";
 import type { CastEvent, Recording, ResolvedConfig } from "./types";
@@ -37,6 +38,7 @@ export async function recordLive(config: ResolvedConfig, opts: LiveOptions = {})
     events.push([stamp(), type, data]);
   };
 
+  const browser = config.browser ? startBrowserCapture({ ...config, cols, rows }, stamp, log) : null;
   const setup = opts.command ? { cmd: opts.command, env: {} } : shellSetup(config);
   const env: Record<string, string> = {
     ...process.env,
@@ -98,6 +100,7 @@ export async function recordLive(config: ResolvedConfig, opts: LiveOptions = {})
     await Promise.race([exitedPromise, proc.exited]);
     push("m", MARKER.end);
   } finally {
+    await browser?.stop();
     (process as unknown as { off(event: string, fn: () => void): void }).off("SIGWINCH", onResize); // newer @types/bun drop the signal overload on off()
     if (stdin) {
       stdin.off("data", onData);
@@ -126,5 +129,6 @@ export async function recordLive(config: ResolvedConfig, opts: LiveOptions = {})
       bunVideo: { ...config, cols, rows },
     },
     events,
+    ...(browser && { browserFrames: browser.frames }),
   };
 }

package/src/presets.ts

@@ -0,0 +1,24 @@
+import type { VideoConfig } from "./types";
+
+export type PresetName = "readme" | "x" | "youtube" | "square";
+
+/** Opinionated bundles applied *under* whatever the config sets explicitly. */
+export const presets: Record<PresetName, Partial<VideoConfig>> = {
+  // Small, loops well, reads at README width.
+  readme: { cols: 80, rows: 20, fps: 30, font: { size: 18 }, padding: 20, margin: 0, borderRadius: 8, windowBar: "none", typingSpeed: "40ms" },
+  // 16:9 at the size X/Twitter serves without downscaling.
+  x: { width: 1280, height: 720, fps: 30, font: { size: 20 }, padding: 24, margin: 24, borderRadius: 12, windowBar: "colorful", typingSpeed: "35ms", typingJitter: 0.3 },
+  // Full HD, smooth.
+  youtube: { width: 1920, height: 1080, fps: 60, font: { size: 26 }, padding: 32, margin: 40, borderRadius: 14, windowBar: "colorful", typingSpeed: "35ms", typingJitter: 0.3 },
+  // 1:1 for feeds.
+  square: { width: 1080, height: 1080, fps: 30, font: { size: 22 }, padding: 24, margin: 32, borderRadius: 14, windowBar: "colorful", typingSpeed: "35ms" },
+};
+
+export const presetNames = Object.keys(presets) as PresetName[];
+
+export function applyPreset(config: VideoConfig): VideoConfig {
+  if (!config.preset) return config;
+  const base = presets[config.preset];
+  if (!base) throw new Error(`Unknown preset "${config.preset}". Available: ${presetNames.join(", ")}`);
+  return { ...base, ...config, font: { ...base.font, ...config.font } };
+}