termcut 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+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.

package/README.md

@@ -0,0 +1,186 @@
+# 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)
+
+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");
+  },
+);
+```
+
+## 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
+```
+
+**Standalone binary** — no Bun required; download from
+[Releases](https://github.com/AmanVarshney01/tcut/releases) (`tcut-<version>-<platform>`, checksums in `SHA256SUMS`):
+
+```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
+```
+
+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**
+
+```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
+```
+
+- **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.
+
+## 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
+```
+
+## 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)`.
+
+## Development
+
+```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
+```
+
+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.
+
+Specs and tasks are tracked with [OpenSpec](https://github.com/Fission-AI/OpenSpec) under `openspec/`; the roadmap
+and measurements are in `PLAN.md`.

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "termcut",
+  "version": "0.1.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"
+  },
+  "bugs": {
+    "url": "https://github.com/AmanVarshney01/tcut/issues"
+  },
+  "keywords": [
+    "terminal",
+    "recording",
+    "gif",
+    "mp4",
+    "svg",
+    "asciicast",
+    "asciinema",
+    "vhs",
+    "pty",
+    "demo",
+    "screencast",
+    "bun"
+  ],
+  "type": "module",
+  "module": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "bin": {
+    "tcut": "./src/cli.ts"
+  },
+  "files": [
+    "src",
+    "scripts",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "bun": ">=1.4.0"
+  },
+  "scripts": {
+    "demo": "bun src/cli.ts examples/demo.ts",
+    "typecheck": "bunx tsc --noEmit",
+    "test": "bun test",
+    "build:assets": "bun scripts/build-assets.ts",
+    "build": "bun run build:assets && bun build --compile --minify src/cli.ts --outfile dist/tcut",
+    "build:all": "bun run build:assets && bun scripts/build-binaries.ts"
+  },
+  "dependencies": {
+    "@wterm/core": "^0.3.4",
+    "@wterm/dom": "^0.3.4",
+    "@wterm/ghostty": "^0.3.4"
+  },
+  "devDependencies": {
+    "@types/bun": "latest"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  }
+}

package/scripts/build-assets.ts

@@ -0,0 +1,45 @@
+// Builds the browser bundles and copies static assets into src/renderer/generated/ so that
+// `bun build --compile` can embed them. Run via `bun run build:assets`.
+import { mkdir } from "node:fs/promises";
+import path from "node:path";
+
+const root = path.resolve(import.meta.dir, "..");
+const rendererDir = path.join(root, "src", "renderer");
+const outDir = path.join(rendererDir, "generated");
+
+function packageRoot(specifier: string): string {
+  const entry = Bun.resolveSync(specifier, root);
+  let dir = path.dirname(entry);
+  for (let i = 0; i < 5; i++) {
+    if (path.basename(path.dirname(dir)) === "@wterm") return dir;
+    dir = path.dirname(dir);
+  }
+  throw new Error(`Could not locate package root for ${specifier}`);
+}
+
+await mkdir(outDir, { recursive: true });
+
+for (const [entry, out] of [
+  ["page-entry.ts", "page.js"],
+  ["player-entry.ts", "player.js"],
+] as const) {
+  const result = await Bun.build({
+    entrypoints: [path.join(rendererDir, entry)],
+    target: "browser",
+    format: "esm",
+    minify: true,
+  });
+  if (!result.success) {
+    console.error(result.logs.map((l) => l.message).join("\n"));
+    process.exit(1);
+  }
+  await Bun.write(path.join(outDir, out), await result.outputs[0]!.text());
+}
+
+await Bun.write(path.join(outDir, "terminal.css"), Bun.file(path.join(packageRoot("@wterm/dom"), "src", "terminal.css")));
+await Bun.write(path.join(outDir, "ghostty-vt.wasm"), Bun.file(path.join(packageRoot("@wterm/ghostty"), "wasm", "ghostty-vt.wasm")));
+
+const sizes = await Promise.all(
+  ["page.js", "player.js", "terminal.css", "ghostty-vt.wasm"].map(async (f) => `${f} ${(Bun.file(path.join(outDir, f)).size / 1024).toFixed(0)} KB`),
+);
+console.log(`built src/renderer/generated/: ${sizes.join(", ")}`);

package/scripts/build-binaries.ts

@@ -0,0 +1,41 @@
+// Cross-compile standalone binaries for every supported platform into dist/ and write SHA-256 checksums.
+// Run `bun run build:assets` first (done by `bun run build:all`).
+import { mkdir } from "node:fs/promises";
+import path from "node:path";
+
+const root = path.resolve(import.meta.dir, "..");
+const dist = path.join(root, "dist");
+const version = (await Bun.file(path.join(root, "package.json")).json()).version as string;
+
+const targets = [
+  "bun-darwin-arm64",
+  "bun-darwin-x64",
+  "bun-linux-x64",
+  "bun-linux-arm64",
+  "bun-windows-x64",
+] as const;
+
+await mkdir(dist, { recursive: true });
+const checksums: string[] = [];
+
+for (const target of targets) {
+  const platform = target.replace(/^bun-/, "");
+  const ext = target.includes("windows") ? ".exe" : "";
+  const outfile = path.join(dist, `tcut-${version}-${platform}${ext}`);
+  const proc = Bun.spawn(
+    ["bun", "build", "--compile", "--minify", `--target=${target}`, path.join(root, "src", "cli.ts"), "--outfile", outfile],
+    { cwd: root, stdout: "ignore", stderr: "pipe" },
+  );
+  const code = await proc.exited;
+  if (code !== 0) {
+    console.error(await new Response(proc.stderr).text());
+    process.exit(code);
+  }
+  const bytes = await Bun.file(outfile).arrayBuffer();
+  const hash = new Bun.CryptoHasher("sha256").update(bytes).digest("hex");
+  checksums.push(`${hash}  ${path.basename(outfile)}`);
+  console.log(`${path.basename(outfile)}  ${(bytes.byteLength / 1024 / 1024).toFixed(1)} MB`);
+}
+
+await Bun.write(path.join(dist, "SHA256SUMS"), checksums.join("\n") + "\n");
+console.log("wrote dist/SHA256SUMS");

package/src/cast.ts

@@ -0,0 +1,40 @@
+import path from "node:path";
+import type { CastEvent, CastHeader, Recording } from "./types";
+
+/** Serialise to asciicast v2 (newline-delimited JSON). Playable with `asciinema play`. */
+export function serializeCast(rec: Recording): string {
+  const lines = [JSON.stringify(rec.header)];
+  for (const event of rec.events) lines.push(JSON.stringify(event));
+  return lines.join("\n") + "\n";
+}
+
+export function parseCast(text: string): Recording {
+  const lines = text.split("\n").filter((l) => l.trim().length > 0);
+  if (lines.length === 0) throw new Error("Empty cast file");
+  const header = JSON.parse(lines[0]!) as CastHeader;
+  if (header.version !== 2) throw new Error(`Unsupported cast version ${String(header.version)} (expected 2)`);
+  const events: CastEvent[] = [];
+  for (let i = 1; i < lines.length; i++) {
+    const parsed = JSON.parse(lines[i]!) as unknown;
+    if (!Array.isArray(parsed) || parsed.length < 3) throw new Error(`Malformed cast event on line ${i + 1}`);
+    events.push([Number(parsed[0]), parsed[1] as CastEvent[1], String(parsed[2])]);
+  }
+  return { header, events };
+}
+
+export async function writeCast(file: string, rec: Recording): Promise<void> {
+  await Bun.write(file, serializeCast(rec));
+}
+
+export async function readCast(file: string): Promise<Recording> {
+  const f = Bun.file(path.resolve(file));
+  if (!(await f.exists())) throw new Error(`Cast file not found: ${file}`);
+  return parseCast(await f.text());
+}
+
+export const MARKER = {
+  hide: "hide",
+  show: "show",
+  screenshot: "screenshot:",
+  end: "end",
+} as const;