termcut 0.2.0 → 0.2.2

package/README.md

@@ -1,176 +1,53 @@
 # tcut
 
-**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)
+Turn a terminal session into a video. Record it live or script it in TypeScript; render to MP4, GIF, SVG, HTML — identical every time.
 
 ![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
+bun add -g termcut     # Bun ≥ 1.4 · installs the `tcut` command
 ```
 
-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
-```
+Standalone binaries: [Releases](https://github.com/AmanVarshney01/tcut/releases). MP4/GIF need `ffmpeg`; SVG/HTML don't.
 
-For `.mp4` / `.gif` / `.webm` you also need `ffmpeg` (`brew install ffmpeg`, `apt install ffmpeg`). SVG, HTML and PNG need nothing else.
-
-## Record a session
-
-### Live — just do it, tcut records it
-
-```sh
-tcut rec -o demo.gif
-```
+## Use
 
-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.
+Record what you do:
 
 ```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
+tcut rec -o demo.gif                    # opens a shell, records until you `exit`
+tcut rec -o demo.mp4 -- npm create vite # or just one command
 ```
 
-### Scripted — write it once, re-record forever
+Or script it:
 
 ```ts
 // demo.video.ts
 import { defineVideo } from "tcut";
 
-export default defineVideo(
-  { output: ["demo.mp4", "demo.gif"], theme: "catppuccin-mocha", cols: 80, rows: 20 },
-  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/);           // assert on the screen — the demo is also a test
-    await t.sleep("1.5s");
-  },
-);
+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");
+});
 ```
 
 ```sh
-tcut demo.video.ts            # record + render
-tcut init demo                # scaffold a script to start from
+tcut demo.video.ts
 ```
 
-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.
-
-## Render again, differently
-
-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:
+Re-render any recording without re-running it:
 
 ```sh
-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
+tcut render demo.cast --theme dracula -o demo.svg
 ```
 
-| 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 |
-
-## Examples
-
-| | |
-|---|---|
-| **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) | |
-
-More in [`packages/tcut/examples/`](packages/tcut/examples).
-
-## Use scripts as tests
-
-```sh
-tcut test examples/
-```
-
-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>                  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 reference
-
-`defineVideo(config, async (t) => { … })`
-
-**Config** (all optional except `output`)
-
-| | default | |
-|---|---|---|
-| `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 }` | |
-| `playbackSpeed` · `waitTimeout` · `endPause` | 1 · `"15s"` · `"1s"` | |
-| `cache` · `quantize` · `core` | true · false · `"ghostty"` | skip re-recording when unchanged · frame-grid timestamps · emulator |
-
-**`t`**
-
-- 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 `500`, `"500ms"`, `"1.5s"`, `"2m"`.
-
-## Requirements
-
-| 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) |
-
-Verified on macOS. Linux and Windows binaries are cross-compiled and not yet exercised in CI.
-
-## How it works, briefly
+## More
 
-`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).
+- [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)
 
-Contributing: see [CONTRIBUTING.md](CONTRIBUTING.md). MIT.
+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,6 +1,6 @@
 {
   "name": "termcut",
-  "version": "0.2.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",
@@ -33,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

@@ -44,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
@@ -72,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" },
@@ -82,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);
 }
 
@@ -123,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;
 }
 
@@ -152,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");
   };
 }
 
@@ -171,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> = {
@@ -288,28 +302,30 @@ async function main(): Promise<void> {
       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 });
+      // 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(`\n✔ wrote ${config.cast} (${recording.events.length} events, ${(recording.header.duration ?? 0).toFixed(1)}s)`);
+      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(`  ${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 "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": {
@@ -321,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/live.ts

@@ -92,7 +92,7 @@ export async function recordLive(config: ResolvedConfig, opts: LiveOptions = {})
     stdin.on("data", onData);
   }
   process.on("SIGWINCH", onResize);
-  log(`recording ${setup.cmd.join(" ")} at ${cols}x${rows} — exit the shell to stop`);
+  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]);