termcut 1.0.1 → 1.0.2

package/README.md

@@ -1,38 +1,45 @@
 # tcut
 
-Turn a terminal session into a video. Record it live or script it in TypeScript; render to MP4, GIF, SVG, HTML — identical every time.
+Terminal videos, written in TypeScript. Record a session live or script it, then render it to MP4, GIF, WebM, SVG or HTML — the same recording gives the same pixels every time.
 
 ![tcut demo](https://raw.githubusercontent.com/AmanVarshney01/tcut/main/packages/tcut/docs/demo.gif)
 
+[tcut.amanv.dev](https://tcut.amanv.dev) · [Reference](https://github.com/AmanVarshney01/tcut/blob/main/packages/tcut/docs/REFERENCE.md) · [Examples](https://github.com/AmanVarshney01/tcut/tree/main/packages/tcut/examples) · [llms.txt](https://tcut.amanv.dev/llms.txt)
+
 ## Install
 
 ```sh
-bun add -g termcut     # Bun ≥ 1.4 · installs the `tcut` command
+bun add -g termcut        # Bun ≥ 1.4 · installs the `tcut` command
 ```
 
-Standalone binaries for macOS, Linux and Windows (all tested in CI): [Releases](https://github.com/AmanVarshney01/tcut/releases). MP4/GIF need `ffmpeg`; SVG/HTML don't. Linux and Windows render pixels through Chrome/Chromium.
+Or a standalone binary for macOS, Linux or Windows from [Releases](https://github.com/AmanVarshney01/tcut/releases) — all three are tested in CI.
+
+- MP4, GIF, WebM, WebP need `ffmpeg` on the PATH. SVG, HTML and text outputs need nothing.
+- Linux and Windows render pixels through Chrome or Chromium (`BUN_CHROME_PATH` to point at one).
 
-## Use
+## Record
 
-Record what you do:
+**Live.** Your shell opens — your prompt, config and aliases; type; `exit`. You get the video, the exact recording (`demo.cast`) and an editable script of what you typed (`demo.video.ts`). `--clean` opens a plain shell with a `>` prompt instead.
 
 ```sh
-tcut rec -o demo.gif                    # opens a shell, records until you `exit`
-tcut rec -o demo.mp4 -- npm create vite # or just one command
+tcut rec -o demo.gif
+tcut rec -o demo.mp4 -- npm create vite     # one command, ends when it exits
 ```
 
-You get `demo.gif`, the exact recording (`demo.cast`) and an editable script (`demo.video.ts`) of what you typed.
+`-- command` runs through that same shell, so `tcut rec -- ls` records what *your* `ls` shows — aliases, functions and colours included. `--raw` runs the binary directly.
 
-Or script it:
+**Scripted.** Plain TypeScript, so loops, helpers and imports work, and the script lives in the repo next to the code it shows.
 
 ```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");
+export default defineVideo({ output: ["demo.mp4", "demo.gif"] }, async (t) => {
+  await t.run("bun --version");       // types it, presses Enter, waits for the prompt
+  await t.run("ls -la");
+  await t.expect(/package\.json/);    // asserts on the screen — the demo is a test
+  await t.snapshot("files.png");      // a still of this exact moment
+  await t.sleep("1.5s");
 });
 ```
 
@@ -40,57 +47,107 @@ export default defineVideo({ output: "demo.gif" }, async (t) => {
 tcut demo.video.ts
 ```
 
-Record a real browser next to (or over) the terminal, for dev-server demos:
+What a script can do, one line each:
 
-```ts
-defineVideo({ output: "demo.mp4", browser: { position: "overlay" } }, async (t) => {
-  await t.run("bun run dev </dev/null >/tmp/dev.log 2>&1 &");
-  await t.browser.goto("http://localhost:5173");
-  await t.run("sed -i '' 's/Hello/Hi/' src/App.tsx");   // HMR updates the page
-  await t.focus("browser");
-});
-```
-
-Polish: `shadow: true`, `watermark: "© you"`, `marginFill: "transparent"` (real alpha in PNG/WebP/GIF/WebM/SVG), `title: "auto"` follows the title the program sets, `keys: true` shows key presses, `maxPause: "800ms"` cuts dead air, `t.timelapse(fn, { speed: 8 })` fast-forwards an install, `t.zoom({ rows: [0, 5] })` magnifies output, `t.chapter("Install")` adds mp4 chapters, `t.snapshot("hero.png")` (or `.svg`) saves a still of that exact moment on every render, `preset: "x"` sizes it for X.
+| | |
+|---|---|
+| `run(cmd)` | waits for your prompt to come back, not for a timer |
+| `wait(/re/)` · `expect(/re/)` | observe or assert the screen — including lines that already scrolled away (`{ scope: "scrollback" }`) |
+| `type` · `enter` · arrows · `ctrl("c")` · `key("f5")` | keys, sent the way the running program asked for them |
+| `hide(fn)` | runs setup off-camera; the state stays |
+| `snapshot("x.png" \| "x.svg")` | a pixel or vector still of that exact moment, written on every render |
+| `chapter(name)` | mp4 chapters, and cut points for `--chapters` / `--split-chapters` |
+| `print(markdown)` · `title(text)` | captions rendered into the terminal, nothing typed |
+| `zoom({ rows, cols })` | magnifies a region; `keys: true` shows what was pressed |
+| `timelapse(fn, { speed })` | fast-forwards an install or a build, not just the silence |
+| `browser` | a real browser window beside or over the terminal (below) |
 
-Faithful to the terminal: arrows switch to the form vim/less asked for, `t.paste()` uses bracketed paste (no autoindent stair-steps), synchronized-output repaints never show torn frames, and OSC 8 hyperlinks — including Markdown links in `t.print()` captions — stay clickable in SVG and HTML output.
+The full surface is in the [reference](https://github.com/AmanVarshney01/tcut/blob/main/packages/tcut/docs/REFERENCE.md).
 
-Test and inspect: `tcut diff a.cast b.cast` catches output changes in CI, `t.expect(/…/, { scope: "scrollback" })` checks output that scrolled away (`-o demo.log` writes the whole transcript), and `tcut doctor demo.cast` tells you what a recording used — and what can't be rendered (inline images).
+## Render again
 
-Cut and join without re-recording — on the cast, so every format works:
+Recording and rendering are separate. A recording is an asciicast; frames are computed on a virtual clock. So a new theme, size or format never re-runs a shell — and cuts, joins and chapter splits happen on the recording, which is why they work for SVG as well as MP4.
 
 ```sh
-tcut render demo.cast --from 2s --to 10s -o clip.gif     # a window of the video
-tcut render demo.cast --split-chapters -o demo.mp4       # one file per t.chapter()
+tcut render demo.cast --theme "Gruvbox Dark" -o demo.svg -o demo.html
+tcut render demo.cast --width 1280 --height 720 --speed 1.5 -o demo.mp4
+tcut render demo.cast --from 2s --to 10s --shadow --watermark "@you" -o clip.gif
+tcut render demo.cast --split-chapters --margin-fill transparent -o demo.webm
 tcut concat intro.cast demo.cast --gap 500ms -o launch.mp4
+tcut themes                                   # ~600 themes, Ghostty's collection
 ```
 
-Re-render any recording without re-running it — ~600 themes ([Ghostty's collection](https://github.com/mbadolato/iTerm2-Color-Schemes)), `tcut themes` lists them:
+Outputs by extension: `.mp4` `.gif` `.webm` `.webp` · `.svg` (animated, real text) · `.html` (single-file player) · `.png` `.jpg` (final frame) · `.txt` (final screen) · `.log` (full transcript) · `dir/` (PNG frames).
+
+## Faithful to the terminal
+
+The emulator is Ghostty's core, so what tcut sees is what your terminal would show — and what it records is what the program actually received.
+
+- Arrow keys and pastes arrive exactly as the running program asked: application cursor mode, bracketed paste.
+- Links printed with OSC 8 — including Markdown links in `print()` captions — stay clickable in SVG and HTML.
+- Frames are never torn: synchronized-output blocks are captured whole.
+- Symbols the font lacks (progress blocks, Nerd Font icons) stay on their cell, so status bars never drift.
+- `tcut doctor demo.cast` explains what a recording used, and what cannot be rendered (inline images).
+
+## Test it
 
 ```sh
-tcut render demo.cast --theme "Gruvbox Dark" -o demo.svg
+tcut test demo.video.ts        # runs the script with no delays — just the assertions
+tcut diff a.cast b.cast        # catches output changes between two recordings
 ```
 
-Share it:
+`expect()` makes a demo a test. `tcut test` runs it fast, and exits non-zero when the screen does not match — so the same script that renders your README video can guard it in CI.
+
+## A browser next to the terminal
+
+For dev-server demos: the page is recorded on the same clock and composited beside or over the terminal.
+
+```ts
+defineVideo({ output: "demo.mp4", browser: { position: "overlay" } }, async (t) => {
+  await t.run("bun run dev </dev/null >/tmp/dev.log 2>&1 &");
+  await t.browser.goto("http://localhost:5173");
+  await t.run("sed -i '' 's/Hello/Hi/' src/App.tsx");   // HMR updates the page
+  await t.focus("browser");
+});
+```
+
+## Share it
 
 ```sh
-tcut publish --setup        # once: your S3-compatible bucket (RustFS, MinIO, R2, S3)
+tcut publish --setup        # once: your own S3-compatible bucket (RustFS, MinIO, R2, S3)
 tcut publish demo.gif       # → https://…/3f9a1c2b7d4e/demo.gif
 ```
 
-## Agents
+There is no hosted service; you bring the bucket.
+
+## For agents
 
 ```sh
-npx skills add AmanVarshney01/tcut   # tcut + tcut-remotion skills for Claude Code, Cursor, etc.
+npx skills add AmanVarshney01/tcut   # skills for Claude Code, Cursor, Codex, …
 ```
 
-Two skills: `tcut` (record terminal videos) and `tcut-remotion` (compose tcut footage into launch videos with [Remotion](https://remotion.dev)). Plus [llms.txt](https://tcut.amanv.dev/llms.txt) and `--json` everywhere.
+Two skills: `tcut` (record terminal videos) and `tcut-remotion` (compose tcut footage into a launch video with [Remotion](https://remotion.dev)). Every command has `--json`, exit codes and no prompts; [llms.txt](https://tcut.amanv.dev/llms.txt) is the condensed guide.
+
+## Compared with VHS
+
+[VHS](https://github.com/charmbracelet/vhs) is the reference point and the inspiration. Where tcut differs:
+
+- **Scripts are TypeScript** — loops, imports, shared scenes, autocomplete — instead of a `.tape` DSL.
+- **Waits on the screen** — `run()` returns when your prompt is back; VHS sleeps for a guessed duration.
+- **Rendering never re-runs the shell** — a new theme, size or format is computed from the recording. VHS screenshots Chrome live, so output depends on machine speed.
+- **Demos are tests** — `expect()` asserts on the screen; `tcut test` runs them in CI.
+- **Same emulator as your terminal** — Ghostty's core in WASM, its themes, plus SVG and HTML outputs that need no ffmpeg or browser.
+
+## How it works
+
+1. **Record.** `Bun.Terminal` runs your shell in a PTY. Every byte is timestamped into a `.cast`.
+2. **Watch.** The same bytes feed a headless [Ghostty](https://ghostty.org) (via [wterm](https://github.com/vercel-labs/wterm)). That is how `run()` knows the prompt is back and `expect()` sees what you see.
+3. **Render.** The cast replays into the same terminal inside `Bun.WebView`, one frame per tick, straight to ffmpeg. SVG and HTML are built from the terminal grid, no browser involved.
 
 ## More
 
-- [Examples](https://github.com/AmanVarshney01/tcut/tree/main/packages/tcut/examples) — driving an interactive TUI, recording Claude Code / Codex
+- [Examples](https://github.com/AmanVarshney01/tcut/tree/main/packages/tcut/examples) — driving an interactive TUI, recording Claude Code and Codex
 - [Reference](https://github.com/AmanVarshney01/tcut/blob/main/packages/tcut/docs/REFERENCE.md) — every CLI flag and script option
-- [llms.txt](https://tcut.amanv.dev/llms.txt) — the same, condensed for coding agents (`--json` gives machine-readable results)
 - [tcut.amanv.dev](https://tcut.amanv.dev)
 
 MIT

package/package.json

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

package/src/cli.ts

@@ -6,6 +6,7 @@ import { readCast, writeCast } from "./cast";
 import { applyOverrides, resolveConfig } from "./config";
 import * as api from "./index";
 import { recordLive } from "./live";
+import { throughShell, userShell } from "./usershell";
 import { ensurePublicBucket, loadPublishConfig, publicUrlFor, publishFiles, savePublishConfig, type PublishConfig, type Published } from "./publish";
 import { diffCasts, type DiffResult } from "./diff";
 import { diagnoseCast, formatDoctorReport, type DoctorReport } from "./doctor";
@@ -70,6 +71,8 @@ Options (override the script's config):
       --gap <dur>          concat: still time between parts
       --preset <name>      readme | x | youtube | square
       --browser <url>      rec: record a browser window too (--browser-position right|left|top|bottom|overlay)
+      --raw                rec: run the command directly instead of through your shell (no aliases/functions)
+      --clean              rec: open tcut's clean shell (plain > prompt, no personal config) instead of yours
       --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
@@ -130,6 +133,8 @@ const { values, positionals } = parseArgs({
     cast: { type: "string" },
     "record-only": { type: "boolean" },
     "no-script": { type: "boolean" },
+    raw: { type: "boolean" },
+    clean: { type: "boolean" },
     force: { type: "boolean" },
     setup: { type: "boolean" },
     open: { type: "boolean" },
@@ -471,11 +476,26 @@ async function main(): Promise<void> {
       const rawOutputs = overrides.output ?? ["rec.mp4"];
       const outputs = Array.isArray(rawOutputs) ? rawOutputs : [rawOutputs];
       const config = resolveConfig({ ...overrides, output: outputs, cast: overrides.cast });
-      const command = rest.length > 0 ? rest : undefined;
+      // The shell tcut was typed into: `-- cmd` runs through it (aliases, functions, colours) unless --raw;
+      // with no command it IS the session — your prompt and config — unless --clean or an explicit --shell.
+      const clean = Boolean(values.clean) || overrides.shell !== undefined;
+      const shell = (rest.length > 0 ? !values.raw : !clean) ? userShell() : null;
+      let command: string[] | undefined;
+      let interactive = false;
+      if (rest.length > 0) {
+        command = shell ? throughShell(rest, shell) : rest;
+        if (shell) log(dim(`  via ${shell.name} — your aliases and functions apply (--raw to run the binary directly)`));
+      } else if (shell) {
+        command = [shell.path, "-il"];
+        interactive = true;
+        log(dim(`  your ${shell.name}, with its config (--clean for a plain shell with a > prompt)`));
+      }
       // Size: --cols/--rows if given, else derived from --width/--height, else the terminal tcut runs in.
       const sized = overrides.width !== undefined || overrides.height !== undefined;
       const recording = await recordLive(config, {
         command,
+        interactive,
+        describe: rest.length > 0 ? rest.join(" ") : shell ? `your ${shell.name}` : undefined,
         log,
         cols: overrides.cols ?? (sized ? config.cols : undefined),
         rows: overrides.rows ?? (sized ? config.rows : undefined),

package/src/live.ts

@@ -24,6 +24,10 @@ export interface LiveOptions {
   /** Keystroke source (default: this process's stdin, switched to raw mode when it is a TTY). */
   stdin?: LiveStdin | null;
   log?: (message: string) => void;
+  /** How to name the command in status lines (defaults to the argv). */
+  describe?: string;
+  /** The command is a shell the user types into (ends on `exit`), not a program that runs and exits. */
+  interactive?: boolean;
 }
 
 /**
@@ -104,11 +108,13 @@ export async function recordLive(config: ResolvedConfig, opts: LiveOptions = {})
     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"}`);
+  log(`recording ${opts.describe ?? setup.cmd.join(" ")} at ${cols}×${rows} — ${opts.command && !opts.interactive ? "ends when the command exits" : "type exit to stop"}`);
 
   try {
     await Promise.race([exitedPromise, proc.exited]);
-    push("m", MARKER.end);
+    // Hold the final screen for `endPause`, like a scripted recording does — otherwise a command that exits in
+    // 20 ms (`tcut rec -- ls`) becomes a three-frame video. The timeline is virtual: stamp it, don't sleep.
+    events.push([Number((stamp() + config.endPause / 1000).toFixed(6)), "m", MARKER.end]);
   } finally {
     await browser?.stop();
     const emitter: NodeJS.EventEmitter = process; // @types/bun's process.off() lacks the signal overload; the generic emitter has it

package/src/scriptgen.ts

@@ -128,6 +128,25 @@ function formatMs(ms: number): string {
 
 const q = (s: string) => JSON.stringify(s);
 
+/**
+ * Answers the terminal sent to the program's queries (device attributes, kitty keyboard, colours via OSC,
+ * XTGETTCAP via DCS, cursor position). They arrive on stdin and get recorded as input, but they are not
+ * keystrokes: when a script replays, tcut answers the queries itself.
+ */
+const ESC = String.fromCharCode(0x1b);
+const BEL = String.fromCharCode(0x07);
+const TERMINAL_REPLIES = new RegExp(
+  [
+    `${ESC}\\[\\?[\\d;]*[cu]`, // primary DA, kitty keyboard flags
+    `${ESC}\\[>[\\d;]*c`, // secondary DA
+    `${ESC}\\][\\d;]*[^${BEL}${ESC}]*(?:${BEL}|${ESC}\\\\)`, // OSC (colour queries)
+    `${ESC}P[^${ESC}]*${ESC}\\\\`, // DCS (XTGETTCAP)
+    `${ESC}\\[\\d+;\\d+R`, // cursor position report
+  ].join("|"),
+  "g",
+);
+export const stripTerminalReplies = (input: string): string => input.replace(TERMINAL_REPLIES, "");
+
 /** Turn the `i` (input) events of a recording into a list of script operations. */
 export function eventsToOps(rec: Recording, opts: ScriptGenOptions): Op[] {
   const threshold = opts.pauseThresholdMs ?? 400;
@@ -163,7 +182,7 @@ export function eventsToOps(rec: Recording, opts: ScriptGenOptions): Op[] {
     }
     lastTime = time;
 
-    for (const token of tokenize(data)) {
+    for (const token of tokenize(stripTerminalReplies(data))) {
       if (token.length > 1 && token[0]! >= " ") {
         pendingText += token;
         continue;
@@ -251,7 +270,7 @@ export function generateScript(rec: Recording, opts: ScriptGenOptions): string {
   const body = ops.length ? ops.map((op) => `    ${opToLine(op)}`).join("\n") : "    // (no input was recorded)";
   const castNote = opts.castPath ? ` The exact recording is in ${path.basename(opts.castPath)}.` : "";
   const modeNote = opts.command
-    ? "It runs the same command and replays your keys; waits are the pauses you took, so adjust them if the program is slower elsewhere."
+    ? "It opens the same program and replays your keys; waits are the pauses you took, so adjust them if it is slower elsewhere."
     : "Typed commands became run(), which waits for the prompt instead of guessing.";
 
   return `import { defineVideo } from "tcut";

package/src/usershell.ts

@@ -0,0 +1,69 @@
+import path from "node:path";
+
+// `tcut rec -- ls` should record what the user sees when they type `ls`: their shell's alias, function or
+// abbreviation, with their colour settings. Running the bare binary gives none of that ("Executable not
+// found" for an alias, plain output for a coloured one). So the command goes through the shell tcut was
+// launched from, interactively, the way the user's own terminal runs it.
+
+export interface UserShell {
+  path: string;
+  /** bash | zsh | fish — the shells whose `-ic <command>` form loads the interactive config. */
+  name: string;
+}
+
+const INTERACTIVE_SHELLS = new Set(["bash", "zsh", "fish"]);
+
+/** The process that launched tcut, by executable name (macOS/Linux `ps`). Null when that cannot be read. */
+function parentCommand(): string | null {
+  try {
+    const r = Bun.spawnSync(["ps", "-o", "comm=", "-p", String(process.ppid)]);
+    const comm = r.stdout.toString().trim().replace(/^-/, ""); // login shells report as "-fish"
+    return comm || null;
+  } catch {
+    return null;
+  }
+}
+
+/** The shell the user typed tcut into, falling back to $SHELL. Null on Windows or when neither is a known shell. */
+export function userShell(): UserShell | null {
+  if (process.platform === "win32") return null;
+  const candidates = [parentCommand(), process.env.SHELL].filter((c): c is string => Boolean(c));
+  for (const candidate of candidates) {
+    const name = path.basename(candidate);
+    if (!INTERACTIVE_SHELLS.has(name)) continue;
+    const resolved = candidate.includes("/") ? candidate : Bun.which(candidate);
+    if (resolved) return { path: resolved, name };
+  }
+  return null;
+}
+
+/** Join argv into one command line; single quotes are understood the same way by bash, zsh and fish. */
+export function shellQuote(args: string[]): string {
+  return args.map((a) => (/^[A-Za-z0-9_@%+=:,./-]+$/.test(a) ? a : `'${a.replace(/'/g, `'\\''`)}'`)).join(" ");
+}
+
+/** fish abbreviations expand only at the prompt, not in `fish -c`; expand a leading one ourselves. */
+export function fishAbbreviation(shell: UserShell, word: string): string | null {
+  if (shell.name !== "fish") return null;
+  try {
+    const r = Bun.spawnSync([shell.path, "-c", "abbr --show"]);
+    for (const line of r.stdout.toString().split("\n")) {
+      // `abbr -a -- lzg lazygit` (options may precede `--`; the expansion may be quoted)
+      const m = /^abbr .*-- (\S+) (.+)$/.exec(line.trim());
+      if (!m || m[1] !== word) continue;
+      const expansion = m[2]!;
+      return expansion.startsWith("'") && expansion.endsWith("'") ? expansion.slice(1, -1).replace(/\\'/g, "'") : expansion;
+    }
+  } catch {
+    /* no abbreviations available */
+  }
+  return null;
+}
+
+/** `args` as the user's shell would run them when typed: interactive, so aliases, functions and abbreviations apply. */
+export function throughShell(args: string[], shell: UserShell): string[] {
+  const [first, ...rest] = args;
+  const expanded = first ? fishAbbreviation(shell, first) : null;
+  const line = expanded ? `${expanded} ${shellQuote(rest)}`.trim() : shellQuote(args);
+  return [shell.path, "-ic", line];
+}