termcut 0.1.0 → 0.2.2

package/README.md

@@ -1,186 +1,53 @@
 # tcut
 
-[![CI](https://github.com/AmanVarshney01/tcut/actions/workflows/ci.yml/badge.svg)](https://github.com/AmanVarshney01/tcut/actions/workflows/ci.yml)
-[![npm](https://img.shields.io/npm/v/termcut)](https://www.npmjs.com/package/termcut)
-[![license](https://img.shields.io/github/license/AmanVarshney01/tcut)](LICENSE)
+Turn a terminal session into a video. Record it live or script it in TypeScript; render to MP4, GIF, SVG, HTML — identical every time.
 
-Script terminal sessions in **TypeScript**, render them to **reproducible** MP4 / GIF / WebM / SVG / HTML / PNG.
-
-Built on Bun 1.4 — `Bun.Terminal` for the PTY, `Bun.WebView` for pixels, `Bun.build` for the renderer,
-`Bun.Image` for stills, `bun build --compile` for a single binary — plus [wterm](https://github.com/vercel-labs/wterm)'s
-libghostty WASM core as the terminal emulator. Inspired by [VHS](https://github.com/charmbracelet/vhs); scripts are
-code, and recording is separate from rendering.
-
-![tcut demo](docs/demo.gif)
-
-<sub>Made by tcut from [`examples/readme.ts`](examples/readme.ts). Same cast as SVG: [docs/demo.svg](docs/demo.svg).</sub>
-
-```ts
-// demo.video.ts
-import { defineVideo } from "tcut";
-
-export default defineVideo(
-  {
-    output: ["out/demo.mp4", "out/demo.gif", "out/demo.svg"],
-    theme: "catppuccin-mocha",
-    cols: 80, rows: 20,
-    typingSpeed: "40ms", typingJitter: 0.4,      // jitter is seeded → reproducible
-    windowBar: "colorful", title: "tcut", margin: 32, borderRadius: 12,
-  },
-  async (t) => {
-    await t.hide(() => t.run("cd /tmp && mkdir -p demo && cd demo"));  // happens, but is cut from the video
-
-    await t.run("echo 'Hello 👋'");       // type + Enter + wait for the prompt to come back
-    await t.run("ls -la");
-    await t.expect(/total \d+/);          // assertion — the script doubles as an integration test
-    await t.screenshot("out/ls.png");
-    await t.sleep("1.5s");
-  },
-);
-```
+![tcut demo](https://raw.githubusercontent.com/AmanVarshney01/tcut/main/packages/tcut/docs/demo.gif)
 
 ## Install
 
-**With Bun (recommended)** — Bun ≥ 1.4. The npm package is **`termcut`** (npm's typosquat filter blocks the
-4-letter name); the command it installs is `tcut`:
-
 ```sh
-bun add -g termcut        # then: tcut demo.video.ts
-bunx termcut init demo    # or run it without installing
+bun add -g termcut     # Bun ≥ 1.4 · installs the `tcut` command
 ```
 
-**Standalone binary** — no Bun required; download from
-[Releases](https://github.com/AmanVarshney01/tcut/releases) (`tcut-<version>-<platform>`, checksums in `SHA256SUMS`):
+Standalone binaries: [Releases](https://github.com/AmanVarshney01/tcut/releases). MP4/GIF need `ffmpeg`; SVG/HTML don't.
 
-```sh
-curl -fsSL https://github.com/AmanVarshney01/tcut/releases/latest/download/tcut-0.1.0-darwin-arm64 -o tcut
-chmod +x tcut && ./tcut init demo
-```
+## Use
 
-Scripts `import { defineVideo } from "tcut"` — the CLI (binary or global install) resolves that import itself,
-so no `node_modules` is needed next to your script. If you add `termcut` to a project, `import … from "termcut"`
-also works and gives your editor the types.
-
-**From source**
+Record what you do:
 
 ```sh
-git clone https://github.com/AmanVarshney01/tcut && cd tcut && bun install
-bun src/cli.ts examples/demo.ts
-```
-
-## Requirements
-
-| To… | You need |
-|---|---|
-| run tcut | **Bun ≥ 1.4** (`bun add -g termcut`), or the standalone binary (Bun is embedded) |
-| record / `tcut test` | a shell — `bash` (default), `zsh`, `fish` or `sh` — plus whatever CLI tools your script runs. No browser, no ffmpeg |
-| render `.svg` / `.html` | nothing else — pure Bun |
-| render `.png` / `.jpg` / `frames/` | a WebView: **macOS → nothing** (system WebKit). **Linux / Windows → Chrome, Chromium, Edge or Brave** installed (Windows ships Edge) |
-| render `.mp4` / `.gif` / `.webm` | the WebView above **+ ffmpeg** — `brew install ffmpeg` · `apt install ffmpeg` · `winget install ffmpeg` |
-| render `.webp` | an ffmpeg with libwebp — Homebrew: `brew install ffmpeg-full` (tcut finds it automatically; see below) |
-| your chosen font | `font.family` must be installed (default stack: JetBrains Mono → Menlo → monospace). SVG output uses the *viewer's* fonts |
-
-Notes
-- tcut looks for ffmpeg in this order: `$TCUT_FFMPEG`, `ffmpeg` on PATH, Homebrew's keg-only `ffmpeg-full`. It picks the first one that has the encoder a given output needs.
-- Verified on macOS (Apple Silicon, CI on GitHub's macOS runners). Linux and Windows binaries are cross-compiled but not yet exercised in CI; recording should work everywhere, rendering depends on the WebView backend above.
-- Rendering throughput is ~30 output frames/s; idle stretches are free (unchanged frames are reused). A 60 fps, 10 s clip renders in a few seconds.
-
-## Why not VHS?
-
-| | VHS | tcut |
-|---|---|---|
-| Script format | `.tape` DSL | TypeScript: loops, imports, shared scenes, assertions |
-| Wait for output | `Wait` regex on raw bytes | `wait()` / `expect()` / `run()` read the **rendered screen** (headless Ghostty) |
-| Determinism | live screenshots, machine-speed dependent | record once to `.cast`, render on a virtual clock → identical frames anywhere |
-| Re-theme | re-run everything | `tcut render demo.cast --theme dracula` — no shell is spawned |
-| Outputs | mp4 / gif / webm / png frames | + **animated SVG**, **single-file HTML player**, PNG/JPG stills — SVG/HTML need no ffmpeg or browser |
-| As tests | — | `tcut test` runs scripts in fast mode, exit code reflects `expect()` |
-| Stack | ttyd + Chrome + ffmpeg | Bun + wterm (JS/WASM) + ffmpeg (only for video containers) |
-
-## How it works
-
-```
-script.ts ─▶ record (Bun.Terminal PTY) ─▶ demo.cast ─▶ render (virtual clock) ─▶ mp4 / gif / webm / png
-             clean shell; every chunk      asciicast v2   ├─ Bun.WebView + @wterm/dom → ffmpeg
-             also feeds a headless                        ├─ headless grid → animated SVG
-             Ghostty core for wait/expect                 └─ cast + lite core → self-contained HTML
+tcut rec -o demo.gif                    # opens a shell, records until you `exit`
+tcut rec -o demo.mp4 -- npm create vite # or just one command
 ```
 
-- **Record** drives a clean shell (no rc files, fixed prompt, `TERM=xterm-256color`) in a PTY. Output is
-  timestamped into an asciicast v2 file *and* parsed by a headless Ghostty terminal, so `run()` knows when the
-  prompt is back and `expect()` sees what a human would see. Terminal queries (e.g. from vim) are answered.
-- **Render** replays the cast: frame *N* is the screen at *N / fps*. Hidden sections are cut, playback speed is
-  applied, cursor blink is driven by the render clock. Unchanged frames are reused, so idle time is free.
-- **Cache**: re-running an unchanged script reuses the cast (`--force` to re-record). `quantize: true` snaps
-  timestamps to the frame grid for byte-stable casts.
+Or script it:
 
-## CLI
+```ts
+// demo.video.ts
+import { defineVideo } from "tcut";
 
+export default defineVideo({ output: "demo.gif" }, async (t) => {
+  await t.run("bun --version");     // type, Enter, wait for the prompt
+  await t.expect(/1\.\d+/);         // assert on the screen
+  await t.sleep("1s");
+});
 ```
-tcut <script.ts> [options]          record + render
-tcut record <script.ts>             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 script: basic | tour | test
-tcut themes                         list built-in themes
-
--o, --output <path>   .mp4 .webm .gif .webp .svg .html .png .jpg or a directory/ for PNG frames (repeatable)
-    --theme <name>    catppuccin-mocha | dracula | github-dark | tokyo-night | one-dark
-    --font <family>   --font-size <px>  --line-height <x>  --letter-spacing <px>
-    --fps <n>         --speed <x>
-    --padding <px>    --margin <px>     --margin-fill <color>  --radius <px>
-    --window-bar <none|colorful|colorfulRight|rings|ringsRight>   --title <text>   --no-blink
-    --core <ghostty|lite>   --cast <path>   --record-only   --force   -q, --quiet
-```
-
-## Script API
-
-`defineVideo(config, async (t) => { … })`
 
-| Config | Default | |
-|---|---|---|
-| `output` | — | string or string[]; extension selects the format |
-| `shell` | `"bash"` | `"bash" \| "zsh" \| "fish" \| "sh"` or a full `string[]` command |
-| `prompt` / `promptPattern` | `"> "` | prompt for the clean shell; regex used by `run()` / `wait()` |
-| `cols` / `rows` / `fps` | 80 / 24 / 60 | |
-| `typingSpeed` / `typingJitter` / `seed` | `"50ms"` / 0 / 1 | |
-| `playbackSpeed` | 1 | applied at render time |
-| `waitTimeout` / `endPause` | `"15s"` / `"1s"` | |
-| `quantize` / `cache` / `core` | false / true / `"ghostty"` | `core: "lite"` = wterm's Zig core (faster, no query replies) |
-| `font` | JetBrains Mono 20px, lh 1.2 | `{ family, size, lineHeight, letterSpacing }` |
-| `theme` | `"catppuccin-mocha"` | name or a full `Theme` object |
-| `cursor` | `{ blink: true, period: 1000 }` | |
-| `padding` / `margin` / `marginFill` / `borderRadius` / `windowBar` / `title` | 24 / 0 / bg / 0 / `"none"` / `""` | window chrome |
-| `cast` | next to the first output | where the recording is saved |
-
-`t` (a `TerminalSession`):
-
-- Input: `type(text, {speed})`, `run(cmd, {wait, timeout})`, `paste(text)`, `enter() tab() backspace() delete()
-  escape() space() up() down() left() right() home() end() pageUp() pageDown()` (repeat count), `ctrl("c")`,
-  `alt("b")`, `key("f5")`, `raw(bytes)`
-- Timing: `sleep("500ms")`, `wait(/re/, { scope: "line" | "screen", timeout })`
-- Assertions: `expect(/re/, { scope })` — throws `ExpectationError` with a screen dump
-- Structure: `hide(async () => …)`, `screenshot(path)`, `marker(name)`, `resize(cols, rows)`, `clear()`
-- Introspection: `screen()`, `line()`, `cursor()`, `cols`, `rows`, `config`
-
-Durations accept milliseconds or `"500ms" | "1.5s" | "2m"`.
-
-Programmatic use: `const v = defineVideo(...); await v.record(); await v.render(undefined, { overrides: { theme: "dracula" } })`,
-`renderCast(file, { output })`, `buildSvg(rec, config)`, `runScriptTests(paths)`.
+```sh
+tcut demo.video.ts
+```
 
-## Development
+Re-render any recording without re-running it:
 
 ```sh
-bun test                          # recorder, renderer, exporters, CLI (spawns real shells + WebView)
-bun run typecheck
-bun src/cli.ts examples/demo.ts
-bun run build                     # dist/tcut single binary with embedded renderer assets
-bun run build:all                 # cross-compile all platforms into dist/ + SHA256SUMS
+tcut render demo.cast --theme dracula -o demo.svg
 ```
 
-Releasing: bump `version` in `package.json`, commit, `git tag v<version> && git push --tags`. The release
-workflow builds the binaries, publishes the GitHub Release and, when an `NPM_TOKEN` secret is configured,
-publishes to npm.
+## More
+
+- [Examples](https://github.com/AmanVarshney01/tcut/tree/main/packages/tcut/examples) — driving an interactive TUI, recording Claude Code / Codex
+- [Reference](https://github.com/AmanVarshney01/tcut/blob/main/packages/tcut/docs/REFERENCE.md) — every CLI flag and script option
+- [tcut.amanv.dev](https://tcut.amanv.dev)
 
-Specs and tasks are tracked with [OpenSpec](https://github.com/Fission-AI/OpenSpec) under `openspec/`; the roadmap
-and measurements are in `PLAN.md`.
+MIT

package/bin/tcut.mjs

@@ -0,0 +1,3 @@
+#!/usr/bin/env bun
+// npm only accepts .js/.mjs bins; Bun imports the TypeScript CLI directly from here.
+import "../src/cli.ts";

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "termcut",
-  "version": "0.1.0",
+  "version": "0.2.2",
   "description": "Script terminal sessions in TypeScript, render them to reproducible MP4/GIF/WebM/SVG/HTML with Bun.",
   "license": "MIT",
   "author": "Aman Varshney",
   "homepage": "https://github.com/AmanVarshney01/tcut#readme",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/AmanVarshney01/tcut.git"
+    "url": "git+https://github.com/AmanVarshney01/tcut.git",
+    "directory": "packages/tcut"
   },
   "bugs": {
     "url": "https://github.com/AmanVarshney01/tcut/issues"
@@ -32,9 +33,10 @@
     ".": "./src/index.ts"
   },
   "bin": {
-    "tcut": "./src/cli.ts"
+    "tcut": "./bin/tcut.mjs"
   },
   "files": [
+    "bin",
     "src",
     "scripts",
     "README.md",

package/src/cli.ts

@@ -1,7 +1,12 @@
 #!/usr/bin/env bun
+import { mkdir } from "node:fs/promises";
 import path from "node:path";
 import { parseArgs } from "node:util";
+import { writeCast } from "./cast";
+import { resolveConfig } from "./config";
 import * as api from "./index";
+import { recordLive } from "./live";
+import { renderOutputs } from "./render";
 import { runScriptTests } from "./testing";
 import { themeNames } from "./themes";
 import type { CoreName, ThemeName, VideoConfig, WindowBar } from "./types";
@@ -23,6 +28,7 @@ const HELP = `tcut — script terminal sessions in TypeScript, render them to vi
 
 Usage:
   tcut <script.ts> [options]          record + render
+  tcut rec [options] [-- command…]    record a LIVE session you drive yourself (no script), then 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)
@@ -38,6 +44,7 @@ Options (override the script's config):
       --window-bar <type>  none | colorful | colorfulRight | rings | ringsRight
       --title <text>       --no-blink
       --core <name>        ghostty | lite
+      --cols <n> --rows <n>  terminal size (rec: defaults to your terminal's size)
       --cast <path>        where to read/write the .cast
       --record-only        stop after writing the cast
       --force              ignore the cast cache and re-record
@@ -66,6 +73,8 @@ const { values, positionals } = parseArgs({
     title: { type: "string" },
     "no-blink": { type: "boolean" },
     core: { type: "string" },
+    cols: { type: "string" },
+    rows: { type: "string" },
     cast: { type: "string" },
     "record-only": { type: "boolean" },
     force: { type: "boolean" },
@@ -76,12 +85,19 @@ const { values, positionals } = parseArgs({
 });
 
 const quiet = values.quiet === true;
+const useColor = process.stdout.isTTY === true && !process.env.NO_COLOR;
+const paint = (code: string) => (s: string) => (useColor ? `\x1b[${code}m${s}\x1b[0m` : s);
+const green = paint("32");
+const dim = paint("2");
+const red = paint("31");
+
+// Status goes to stdout (plain informational output); only real errors go to stderr.
 const log = (msg: string) => {
-  if (!quiet) console.error(msg);
+  if (!quiet) process.stdout.write(`${msg}\n`);
 };
 
 function fail(message: string): never {
-  console.error(`error: ${message}`);
+  console.error(`${red("error:")} ${message}`);
   process.exit(1);
 }
 
@@ -117,6 +133,8 @@ function overridesFromFlags(): Partial<VideoConfig> {
     o.core = values.core as CoreName;
   }
   if (values.cast) o.cast = values.cast;
+  if (values.cols !== undefined) o.cols = num("cols");
+  if (values.rows !== undefined) o.rows = num("rows");
   return o;
 }
 
@@ -146,14 +164,14 @@ async function loadVideo(file: string): Promise<Video> {
 }
 
 function progressReporter(): (p: { frame: number; total: number }) => void {
-  if (quiet || !process.stderr.isTTY) return () => {};
+  if (quiet || !process.stdout.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");
+    process.stdout.write(`\r${dim(`  rendering ${frame}/${total} frames (${pct}%)`)}`);
+    if (frame === total) process.stdout.write("\n");
   };
 }
 
@@ -165,9 +183,11 @@ async function fileSize(file: string): Promise<string> {
   return `${(bytes / 1024 / 1024).toFixed(1)} MB`;
 }
 
+const ok = (what: string, detail = "") => log(`${green("✔")} ${what}${detail ? ` ${dim(detail)}` : ""}`);
+
 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}`);
+  for (const out of outputs) ok(`wrote ${out}`, await fileSize(out));
+  for (const shot of screenshots) ok(`screenshot ${shot}`);
 }
 
 const TEMPLATES: Record<string, (name: string) => string> = {
@@ -276,18 +296,36 @@ async function main(): Promise<void> {
       console.log(`created ${file}\n\nrun it with:\n  ${template === "test" ? `tcut test ${file}` : `tcut ${file}`}`);
       return;
     }
+    case "rec": {
+      // Live mode: the user (or a pipe) drives the PTY; everything after `--` is the command to run.
+      const overrides = overridesFromFlags();
+      const outputs = overrides.output ?? ["rec.mp4"];
+      const config = resolveConfig({ ...overrides, output: outputs, cast: overrides.cast });
+      const command = rest.length > 0 ? rest : undefined;
+      // Size: --cols/--rows if given, else the terminal tcut runs in.
+      const recording = await recordLive(config, { command, log, cols: overrides.cols, rows: overrides.rows });
+      await mkdir(path.dirname(path.resolve(config.cast)), { recursive: true });
+      await writeCast(config.cast, recording);
+      log("");
+      ok(`wrote ${config.cast}`, `${recording.events.length} events, ${(recording.header.duration ?? 0).toFixed(1)}s`);
+      if (values["record-only"]) return;
+      const result = await renderOutputs(recording, config, progressReporter());
+      await reportOutputs(result.outputs, result.screenshots);
+      log(dim(`  ${result.frames} frames, ${result.durationSeconds.toFixed(1)}s of video in ${elapsed()}`));
+      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()}`);
+      ok(`${rec.cached ? "reused" : "wrote"} ${video.config.cast}`, `${rec.events.length} events, ${(rec.header.duration ?? 0).toFixed(1)}s, ${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()}`);
+      log(dim(`  ${result.frames} frames, ${result.durationSeconds.toFixed(1)}s of video in ${elapsed()}`));
       return;
     }
     case "test": {
@@ -299,9 +337,9 @@ async function main(): Promise<void> {
     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}`);
+      ok(`${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()}`);
+      if (!values["record-only"]) log(dim(`  ${result.frames} frames, ${result.durationSeconds.toFixed(1)}s of video in ${elapsed()}`));
     }
   }
 }

package/src/index.ts

@@ -1,6 +1,8 @@
 export { defineVideo, Video, renderCast, isVideo } from "./video";
 export type { RunOptions as VideoRunOptions, RunResult, VideoRecordOptions } from "./video";
 export { renderOutputs } from "./render";
+export { recordLive } from "./live";
+export type { LiveOptions } from "./live";
 export { buildSvg } from "./export/svg";
 export { buildHtml } from "./export/html";
 export { replayFrames } from "./export/frames";

package/src/live.ts

@@ -0,0 +1,130 @@
+import { MARKER } from "./cast";
+import { shellSetup } from "./recorder";
+import type { CastEvent, Recording, ResolvedConfig } from "./types";
+
+export interface LiveOptions {
+  /** Run this command instead of the configured clean shell. */
+  command?: string[];
+  /** Terminal size; defaults to the size of the terminal tcut is running in, then the config. */
+  cols?: number;
+  rows?: number;
+  /** Where to mirror the session (default: this process's stdout). */
+  stdout?: { write(data: Uint8Array | string): unknown };
+  /** Keystroke source (default: this process's stdin, switched to raw mode when it is a TTY). */
+  stdin?: NodeJS.ReadStream | null;
+  log?: (message: string) => void;
+}
+
+/**
+ * Record a *live* session: the user (or a pipe) drives the PTY, tcut mirrors it to the terminal and captures
+ * every byte with timestamps. No script, no waits — whatever happened is what gets rendered.
+ */
+export async function recordLive(config: ResolvedConfig, opts: LiveOptions = {}): Promise<Recording> {
+  const log = opts.log ?? (() => {});
+  const stdin = opts.stdin === undefined ? process.stdin : opts.stdin;
+  const stdout = opts.stdout ?? { write: (d: Uint8Array | string) => process.stdout.write(d) };
+  const cols = opts.cols ?? process.stdout.columns ?? config.cols;
+  const rows = opts.rows ?? process.stdout.rows ?? config.rows;
+  const decoder = new TextDecoder("utf-8");
+  const events: CastEvent[] = [];
+  const startedAt = performance.now();
+
+  const stamp = (): number => {
+    const t = (performance.now() - startedAt) / 1000;
+    return config.quantize ? Math.ceil(t * config.fps - 1e-6) / config.fps : Number(t.toFixed(6));
+  };
+  const push = (type: CastEvent[1], data: string): void => {
+    events.push([stamp(), type, data]);
+  };
+
+  const setup = opts.command ? { cmd: opts.command, env: {} } : shellSetup(config);
+  const env: Record<string, string> = {
+    ...process.env,
+    TERM: "xterm-256color",
+    COLORTERM: "truecolor",
+    ...setup.env,
+    ...config.env,
+  };
+
+  let exited = false;
+  let resolveExit!: () => void;
+  const exitedPromise = new Promise<void>((r) => (resolveExit = r));
+
+  const proc = Bun.spawn(setup.cmd, {
+    cwd: config.cwd,
+    env,
+    terminal: {
+      cols,
+      rows,
+      name: "xterm-256color",
+      data(_terminal, chunk) {
+        const text = decoder.decode(chunk, { stream: true });
+        if (!text) return;
+        stdout.write(chunk);
+        push("o", text);
+      },
+      exit() {
+        exited = true;
+        resolveExit();
+      },
+    },
+  });
+  const terminal = proc.terminal;
+  if (!terminal) throw new Error("Bun.spawn did not return a terminal. Is this Bun >= 1.4?");
+
+  const isTTY = Boolean(stdin && (stdin as NodeJS.ReadStream).isTTY);
+  const onData = (chunk: Buffer | string): void => {
+    if (exited || terminal.closed) return;
+    terminal.write(chunk);
+    push("i", typeof chunk === "string" ? chunk : chunk.toString("utf8"));
+  };
+  const onResize = (): void => {
+    const c = process.stdout.columns ?? cols;
+    const r = process.stdout.rows ?? rows;
+    if (exited || terminal.closed) return;
+    terminal.resize(c, r);
+    push("r", `${c}x${r}`);
+  };
+
+  if (stdin) {
+    if (isTTY) stdin.setRawMode(true);
+    stdin.resume();
+    stdin.on("data", onData);
+  }
+  process.on("SIGWINCH", onResize);
+  log(`recording ${setup.cmd.join(" ")} at ${cols}×${rows} — ${opts.command ? "ends when the command exits" : "type exit to stop"}`);
+
+  try {
+    await Promise.race([exitedPromise, proc.exited]);
+    push("m", MARKER.end);
+  } finally {
+    process.off("SIGWINCH", onResize);
+    if (stdin) {
+      stdin.off("data", onData);
+      if (isTTY) stdin.setRawMode(false);
+      stdin.pause();
+    }
+    try {
+      terminal.close();
+    } catch {
+      /* already closed */
+    }
+    if (!exited) proc.kill();
+    await proc.exited.catch(() => undefined);
+  }
+
+  const duration = events.length > 0 ? events[events.length - 1]![0] : 0;
+  return {
+    header: {
+      version: 2,
+      width: cols,
+      height: rows,
+      timestamp: Math.floor(Date.now() / 1000),
+      duration,
+      title: config.title || undefined,
+      env: { TERM: "xterm-256color", SHELL: setup.cmd[0]! },
+      bunVideo: { ...config, cols, rows },
+    },
+    events,
+  };
+}

package/src/recorder.ts

@@ -42,12 +42,13 @@ function mulberry32(seed: number): () => number {
   };
 }
 
-interface ShellSetup {
+export interface ShellSetup {
   cmd: string[];
   env: Record<string, string>;
 }
 
-function shellSetup(config: ResolvedConfig): ShellSetup {
+/** Command + environment for a clean, rc-free shell with the configured prompt. */
+export function shellSetup(config: ResolvedConfig): ShellSetup {
   const { shell, prompt } = config;
   if (Array.isArray(shell)) return { cmd: shell, env: {} };
   switch (shell) {

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2026 Aman Varshney
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.