termcut 0.1.0 → 0.2.0

package/README.md

@@ -1,186 +1,176 @@
 # tcut
 
-[![CI](https://github.com/AmanVarshney01/tcut/actions/workflows/ci.yml/badge.svg)](https://github.com/AmanVarshney01/tcut/actions/workflows/ci.yml)
+**Turn a terminal session into a video.** Record it live or script it in TypeScript; render it to MP4, GIF, WebM, SVG, HTML or PNG — identical every time.
+
 [![npm](https://img.shields.io/npm/v/termcut)](https://www.npmjs.com/package/termcut)
+[![CI](https://github.com/AmanVarshney01/tcut/actions/workflows/ci.yml/badge.svg)](https://github.com/AmanVarshney01/tcut/actions/workflows/ci.yml)
 [![license](https://img.shields.io/github/license/AmanVarshney01/tcut)](LICENSE)
 
-Script terminal sessions in **TypeScript**, render them to **reproducible** MP4 / GIF / WebM / SVG / HTML / PNG.
+![tcut demo](https://raw.githubusercontent.com/AmanVarshney01/tcut/main/packages/tcut/docs/demo.gif)
+
+Website: **[tcut.amanv.dev](https://tcut.amanv.dev)**
+
+## Install
+
+```sh
+bun add -g termcut        # installs the `tcut` command (needs Bun ≥ 1.4)
+bunx termcut --help       # or run it without installing
+```
+
+No Bun? Grab a standalone binary from [Releases](https://github.com/AmanVarshney01/tcut/releases) (macOS, Linux, Windows):
+
+```sh
+curl -fsSL https://github.com/AmanVarshney01/tcut/releases/latest/download/tcut-0.2.0-darwin-arm64 -o tcut && chmod +x tcut
+```
+
+For `.mp4` / `.gif` / `.webm` you also need `ffmpeg` (`brew install ffmpeg`, `apt install ffmpeg`). SVG, HTML and PNG need nothing else.
 
-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.
+## Record a session
 
-![tcut demo](docs/demo.gif)
+### Live — just do it, tcut records it
+
+```sh
+tcut rec -o demo.gif
+```
 
-<sub>Made by tcut from [`examples/readme.ts`](examples/readme.ts). Same cast as SVG: [docs/demo.svg](docs/demo.svg).</sub>
+A clean shell opens in your terminal. Type whatever you want to show; when you `exit`, tcut renders `demo.gif`.
+Everything is captured — output, timing, colours, arrow keys in TUIs, window resizes.
+
+```sh
+tcut rec -o demo.mp4 -- bun create better-t-stack    # record just one command (you still drive it)
+tcut rec -o demo.svg -o demo.gif                    # several formats from one session
+```
+
+### Scripted — write it once, re-record forever
 
 ```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,
-  },
+  { output: ["demo.mp4", "demo.gif"], theme: "catppuccin-mocha", cols: 80, rows: 20 },
   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("bun --version");              // types it, presses Enter, waits for the prompt
     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.expect(/package\.json/);           // assert on the screen — the demo is also a test
     await t.sleep("1.5s");
   },
 );
 ```
 
-## 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
+tcut demo.video.ts            # record + render
+tcut init demo                # scaffold a script to start from
 ```
 
-**Standalone binary** — no Bun required; download from
-[Releases](https://github.com/AmanVarshney01/tcut/releases) (`tcut-<version>-<platform>`, checksums in `SHA256SUMS`):
+Scripts are plain TypeScript: loops, helpers, imports, whatever you need. All output in the video comes from the
+real programs; the script only provides the key presses a person would make.
 
-```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
-```
+## Render again, differently
 
-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**
+Recording and rendering are separate. Every recording is saved as a standard [asciicast](https://docs.asciinema.org/manual/asciicast/v2/) (`demo.cast`) and frames are computed on a virtual clock, so the same cast renders to the same pixels on any machine — and you can re-render without re-running anything:
 
 ```sh
-git clone https://github.com/AmanVarshney01/tcut && cd tcut && bun install
-bun src/cli.ts examples/demo.ts
+tcut render demo.cast --theme dracula -o demo.gif     # new theme
+tcut render demo.cast -o demo.svg -o demo.html        # animated SVG for a README, single-file HTML player
+tcut render demo.cast --font-size 24 --speed 1.5 -o demo.mp4
 ```
 
-## Requirements
+| Output | Needs | |
+|---|---|---|
+| `.mp4` `.webm` | ffmpeg | H.264 / VP9 |
+| `.gif` `.webp` | ffmpeg | animated, palette-optimised |
+| `.svg` | nothing | animated vector — crisp at any size, ~20 KB, renders on GitHub |
+| `.html` | nothing | self-contained player with play / pause / loop |
+| `.png` `.jpg` | — | the final frame (`t.screenshot()` for any moment) |
+| `frames/` | — | one PNG per frame |
 
-| To… | You need |
+## Examples
+
+| | |
 |---|---|
-| 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) |
+| **Driving an interactive TUI** — answers `bun create better-t-stack` with arrow keys, picks options by reading the screen. [`better-t-stack.ts`](packages/tcut/examples/better-t-stack.ts) | ![better-t-stack](https://raw.githubusercontent.com/AmanVarshney01/tcut/main/packages/tcut/docs/examples/better-t-stack.gif) |
+| **Recording AI agents** — `claude -p` explains a file, `codex exec` edits it. [`ai-agents.ts`](packages/tcut/examples/ai-agents.ts) | ![claude and codex](https://raw.githubusercontent.com/AmanVarshney01/tcut/main/packages/tcut/docs/examples/ai-agents.gif) |
+| **README media** — the GIF at the top of this page. [`readme.ts`](packages/tcut/examples/readme.ts) | |
 
-## How it works
+More in [`packages/tcut/examples/`](packages/tcut/examples).
 
-```
-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
+## Use scripts as tests
+
+```sh
+tcut test examples/
 ```
 
-- **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.
+Runs every script in fast mode (no typing delay, no sleeps), renders nothing, and exits non-zero if any
+`expect()` fails — so the demo in your README is also the integration test for your CLI.
 
 ## CLI
 
 ```
-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
+tcut <script.ts>                  record + render
+tcut rec [-- command…]            record a live session, then render
+tcut record <script.ts>           record only (.cast)
+tcut render <file.cast>           render a cast (tcut's or asciinema's)
+tcut test <paths…>                run scripts as tests
+tcut init [name] [--template basic|tour|test]
+tcut themes
+
+-o, --output <path>   repeatable: .mp4 .webm .gif .webp .svg .html .png .jpg or a directory/
+--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
 ```
 
-## Script API
+## Script reference
 
 `defineVideo(config, async (t) => { … })`
 
-| Config | Default | |
+**Config** (all optional except `output`)
+
+| | 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 |
+| `output` | — | string or array; extension picks the format |
+| `shell` | `"bash"` | `bash` · `zsh` · `fish` · `sh` · or a `string[]` command |
+| `prompt` | `"> "` | prompt of the clean shell; `run()` waits for it |
+| `cols` · `rows` · `fps` | 80 · 24 · 60 | |
+| `typingSpeed` · `typingJitter` · `seed` | `"50ms"` · 0 · 1 | jitter is seeded, so it's reproducible |
+| `theme` | `"catppuccin-mocha"` | a name or a full theme object |
+| `font` | JetBrains Mono 20 px | `{ family, size, lineHeight, letterSpacing }` |
+| `windowBar` · `title` · `padding` · `margin` · `marginFill` · `borderRadius` | `"none"` · `""` · 24 · 0 · bg · 0 | window chrome |
 | `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 |
+| `playbackSpeed` · `waitTimeout` · `endPause` | 1 · `"15s"` · `"1s"` | |
+| `cache` · `quantize` · `core` | true · false · `"ghostty"` | skip re-recording when unchanged · frame-grid timestamps · emulator |
 
-`t` (a `TerminalSession`):
+**`t`**
 
-- 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`
+- Type: `run(cmd)` · `type(text)` · `paste(text)` · `enter()` `tab()` `backspace()` `escape()` `space()` `up()` `down()` `left()` `right()` `home()` `end()` `pageUp()` `pageDown()` (all take a count) · `ctrl("c")` · `alt("b")` · `key("f5")` · `raw(bytes)`
+- Wait: `sleep("500ms")` · `wait(/re/, { scope: "line" | "screen" })` — default waits for the prompt
+- Assert: `expect(/re/)` — throws with a screen dump
+- Shape the video: `hide(async () => …)` cuts a section · `screenshot("x.png")` · `marker("name")` · `resize(cols, rows)` · `clear()`
+- Look: `screen()` · `line()` · `cursor()` · `cols` · `rows`
 
-Durations accept milliseconds or `"500ms" | "1.5s" | "2m"`.
+Durations accept `500`, `"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)`.
+## Requirements
 
-## Development
+| To… | You need |
+|---|---|
+| run tcut | Bun ≥ 1.4, or the standalone binary |
+| record (`rec`, scripts, `test`) | a shell — nothing else |
+| render `.svg` / `.html` | nothing else |
+| render `.png` / `frames/` | macOS: nothing (built-in WebKit) · Linux / Windows: Chrome, Chromium, Edge or Brave |
+| render `.mp4` / `.gif` / `.webm` | the above + ffmpeg |
+| render `.webp` | ffmpeg with libwebp (`brew install ffmpeg-full`; found automatically) |
 
-```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
-```
+Verified on macOS. Linux and Windows binaries are cross-compiled and not yet exercised in CI.
+
+## How it works, briefly
 
-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.
+`Bun.Terminal` runs your shell in a PTY. Output is timestamped into the cast and also fed to a headless
+[Ghostty](https://ghostty.org) terminal (via [wterm](https://github.com/vercel-labs/wterm)), which is how `run()` knows the prompt is back and
+`expect()` sees what you see. Rendering replays the cast into that terminal inside `Bun.WebView` one frame at a time and hands the
+frames to ffmpeg; SVG and HTML are built straight from the terminal grid. Inspired by [VHS](https://github.com/charmbracelet/vhs).
 
-Specs and tasks are tracked with [OpenSpec](https://github.com/Fission-AI/OpenSpec) under `openspec/`; the roadmap
-and measurements are in `PLAN.md`.
+Contributing: see [CONTRIBUTING.md](CONTRIBUTING.md). MIT.

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "termcut",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "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"

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)
@@ -276,6 +282,22 @@ 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;
+      const recording = await recordLive(config, { command, log });
+      await mkdir(path.dirname(path.resolve(config.cast)), { recursive: true });
+      await writeCast(config.cast, recording);
+      log(`\n✔ 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(`  ${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]);

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}x${rows} — exit the shell 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.