termcut 1.0.0 → 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.0",
+  "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/export/html.ts

@@ -1,4 +1,5 @@
 import { mkdir } from "node:fs/promises";
+import { PIN_CSS } from "../renderer/pin";
 import path from "node:path";
 import { barHeight, embedImage, shadowCss, watermarkCss } from "../renderer/page";
 import { pageAssets } from "../renderer/bundle";
@@ -62,7 +63,8 @@ ${watermarkCss(config)}
 #bar { height: ${barHeight(config)}px; margin-top: -${Math.min(config.padding, 12)}px; display: flex; align-items: center; justify-content: space-between; font: 13px -apple-system, "Segoe UI", Helvetica, Arial, sans-serif; color: ${theme.foreground}; }
 #bar .dots { display: flex; gap: 8px; } #bar .dot { width: 12px; height: 12px; border-radius: 50%; box-sizing: border-box; display: inline-block; }
 #bar .title { flex: 1; text-align: center; opacity: .7; } #bar.right .title { text-align: left; }
-#term.wterm { ${vars}; --term-font-family: ${font.family}; --term-font-size: ${font.size}px; --term-line-height: ${font.lineHeight}; --term-row-height: ${Math.ceil(font.size * font.lineHeight)}px; letter-spacing: ${font.letterSpacing}px; padding: 0; border-radius: 0; box-shadow: none; background: transparent; cursor: pointer; }
+#term.wterm { ${vars}; --term-font-family: ${font.family}; --term-font-size: ${font.size}px; --term-line-height: ${font.lineHeight}; --term-row-height: ${Math.ceil(font.size * font.lineHeight)}px; letter-spacing: ${font.letterSpacing}px; --vt-letter-spacing: ${font.letterSpacing}px; padding: 0; border-radius: 0; box-shadow: none; background: transparent; cursor: pointer; }
+${PIN_CSS}
 #controls { display: flex; gap: 12px; align-items: center; margin-top: 12px; font: 12px -apple-system, "Segoe UI", Helvetica, Arial, sans-serif; color: ${theme.foreground}; opacity: .85; }
 #controls button { background: transparent; color: inherit; border: 1px solid currentColor; border-radius: 6px; width: 34px; height: 26px; cursor: pointer; }
 #controls input[type=range] { flex: 1; accent-color: ${theme.cursor ?? theme.foreground}; }

package/src/export/svg.ts

@@ -108,20 +108,28 @@ function frameMarkup(frame: GridFrame, config: ResolvedConfig, g: Geometry): str
     // Text runs with identical style (and link); OSC 8 links become real <a> elements
     const spans: string[] = [];
     x = 0;
-    let run: { x: number; text: string; style: string; link: string | null } | null = null;
+    let run: { x: number; text: string; style: string; link: string | null; cols: number[]; single: boolean } | null = null;
     const flushRun = () => {
       if (!run || !run.text.trim()) return;
-      const span = `<tspan x="${num(run.x * g.cellW)}"${run.style}>${esc(run.text.replace(/\s+$/, ""))}</tspan>`;
+      const text = run.text.replace(/\s+$/, "");
+      // Fallback-font glyphs are not one cell wide; give every glyph its own x when the run has any non-ASCII
+      // and each cell is a single code point (an x list addresses code points, so clusters would misalign).
+      const pinned = run.single && /[^\x20-\x7e]/.test(text);
+      const xAttr = pinned ? run.cols.slice(0, [...text].length).map((c) => num(c * g.cellW)).join(" ") : num(run.x * g.cellW);
+      const span = `<tspan x="${xAttr}"${run.style}>${esc(text)}</tspan>`;
       spans.push(run.link ? `<a href="${esc(run.link)}">${span}</a>` : span);
     };
     for (const cell of cells) {
       const blank = cell.text === " " && !(cell.flags & (FLAG.underline | FLAG.strike));
       const style = blank ? "" : styleAttrs(cell, theme.foreground);
+      const single = [...cell.text].length === 1;
       if (run && ((run.style === style && run.link === cell.link) || (blank && run.text.length > 0 && run.link === null))) {
         run.text += cell.text;
+        run.cols.push(x);
+        run.single &&= single;
       } else {
         flushRun();
-        run = blank ? null : { x, text: cell.text, style, link: cell.link };
+        run = blank ? null : { x, text: cell.text, style, link: cell.link, cols: [x], single };
       }
       x += cell.width;
     }

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