termcut 0.2.2 → 0.4.0

package/README.md

@@ -21,6 +21,8 @@ tcut rec -o demo.gif                    # opens a shell, records until you `exit
 tcut rec -o demo.mp4 -- npm create vite # or just one command
 ```
 
+You get `demo.gif`, the exact recording (`demo.cast`) and an editable script (`demo.video.ts`) of what you typed.
+
 Or script it:
 
 ```ts
@@ -38,10 +40,17 @@ export default defineVideo({ output: "demo.gif" }, async (t) => {
 tcut demo.video.ts
 ```
 
-Re-render any recording without re-running it:
+Re-render any recording without re-running it — ~600 themes ([Ghostty's collection](https://github.com/mbadolato/iTerm2-Color-Schemes)), `tcut themes` lists them:
+
+```sh
+tcut render demo.cast --theme "Gruvbox Dark" -o demo.svg
+```
+
+Share it:
 
 ```sh
-tcut render demo.cast --theme dracula -o demo.svg
+tcut publish --setup        # once: your S3-compatible bucket (RustFS, MinIO, R2, S3)
+tcut publish demo.gif       # → https://…/3f9a1c2b7d4e/demo.gif
 ```
 
 ## More

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "termcut",
-  "version": "0.2.2",
+  "version": "0.4.0",
   "description": "Script terminal sessions in TypeScript, render them to reproducible MP4/GIF/WebM/SVG/HTML with Bun.",
   "license": "MIT",
   "author": "Aman Varshney",
@@ -33,7 +33,7 @@
     ".": "./src/index.ts"
   },
   "bin": {
-    "tcut": "./bin/tcut.mjs"
+    "tcut": "bin/tcut.mjs"
   },
   "files": [
     "bin",

package/scripts/build-themes.ts

@@ -0,0 +1,86 @@
+// Generates src/themes.generated.json from the Ghostty-format themes in mbadolato/iTerm2-Color-Schemes (MIT) —
+// the same collection Ghostty bundles. Run: `bun scripts/build-themes.ts` (network). Output is committed.
+import path from "node:path";
+import { mkdtemp, readdir, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+
+const SOURCE = "https://github.com/mbadolato/iTerm2-Color-Schemes/archive/refs/heads/master.tar.gz";
+const out = path.resolve(import.meta.dir, "..", "src", "themes.generated.json");
+
+const KEYS = [
+  "black", "red", "green", "yellow", "blue", "magenta", "cyan", "white",
+  "brightBlack", "brightRed", "brightGreen", "brightYellow", "brightBlue", "brightMagenta", "brightCyan", "brightWhite",
+] as const;
+
+const slug = (name: string) =>
+  name
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+
+const hex = (v: string) => {
+  const h = v.trim().replace(/^#/, "");
+  return /^[0-9a-f]{6}$/i.test(h) ? `#${h.toLowerCase()}` : null;
+};
+
+function parse(name: string, text: string): Record<string, string> | null {
+  const palette: Record<number, string> = {};
+  const props: Record<string, string> = {};
+  for (const raw of text.split("\n")) {
+    const line = raw.trim();
+    if (!line || line.startsWith("#")) continue;
+    const eq = line.indexOf("=");
+    if (eq < 0) continue;
+    const key = line.slice(0, eq).trim();
+    const value = line.slice(eq + 1).trim();
+    if (key === "palette") {
+      const m = /^(\d+)\s*=\s*(.+)$/.exec(value);
+      if (m) {
+        const c = hex(m[2]!);
+        if (c) palette[Number(m[1])] = c;
+      }
+    } else {
+      props[key] = value;
+    }
+  }
+  const background = hex(props.background ?? "");
+  const foreground = hex(props.foreground ?? "");
+  if (!background || !foreground) return null;
+  for (let i = 0; i < 16; i++) if (!palette[i]) return null;
+  const theme: Record<string, string> = { name, background, foreground };
+  const cursor = hex(props["cursor-color"] ?? "");
+  if (cursor) theme.cursor = cursor;
+  const cursorText = hex(props["cursor-text"] ?? "");
+  if (cursorText) theme.cursorAccent = cursorText;
+  const selection = hex(props["selection-background"] ?? "");
+  if (selection) theme.selectionBackground = selection;
+  KEYS.forEach((k, i) => (theme[k] = palette[i]!));
+  return theme;
+}
+
+const tmp = await mkdtemp(path.join(tmpdir(), "tcut-themes-"));
+const tgz = path.join(tmp, "schemes.tgz");
+const res = await fetch(SOURCE);
+if (!res.ok) throw new Error(`download failed: ${res.status}`);
+await Bun.write(tgz, await res.arrayBuffer());
+const untar = Bun.spawn(["tar", "-xzf", tgz, "-C", tmp], { stdout: "ignore", stderr: "pipe" });
+if ((await untar.exited) !== 0) throw new Error(await new Response(untar.stderr).text());
+const root = (await readdir(tmp)).find((d) => d.startsWith("iTerm2-Color-Schemes"));
+if (!root) throw new Error("unexpected archive layout");
+const dir = path.join(tmp, root, "ghostty");
+
+const themes: Record<string, Record<string, string>> = {};
+let skipped = 0;
+for (const file of (await readdir(dir)).sort()) {
+  const text = await Bun.file(path.join(dir, file)).text();
+  const theme = parse(file, text);
+  if (!theme) {
+    skipped++;
+    continue;
+  }
+  themes[slug(file)] = theme;
+}
+await rm(tmp, { recursive: true, force: true });
+
+await Bun.write(out, JSON.stringify(themes) + "\n");
+console.log(`wrote ${path.relative(process.cwd(), out)}: ${Object.keys(themes).length} themes (${skipped} skipped), ${(Bun.file(out).size / 1024).toFixed(0)} KB`);

package/src/cli.ts

@@ -6,9 +6,11 @@ import { writeCast } from "./cast";
 import { resolveConfig } from "./config";
 import * as api from "./index";
 import { recordLive } from "./live";
+import { ensurePublicBucket, loadPublishConfig, publicUrlFor, publishFiles, savePublishConfig, type PublishConfig } from "./publish";
 import { renderOutputs } from "./render";
+import { generateScript } from "./scriptgen";
 import { runScriptTests } from "./testing";
-import { themeNames } from "./themes";
+import { findThemes, themeNames } from "./themes";
 import type { CoreName, ThemeName, VideoConfig, WindowBar } from "./types";
 import { Video, isVideo, renderCast } from "./video";
 
@@ -32,8 +34,10 @@ Usage:
   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)
+  tcut publish <files...> [--open]    upload to your S3-compatible bucket and print share links
+  tcut publish --setup                configure the bucket (RustFS, MinIO, R2, S3 …) — once
   tcut init [name] [--template t]     scaffold a new script (basic | tour | test)
-  tcut themes                         list built-in themes
+  tcut themes [query]                 list the ~600 bundled themes (Ghostty collection)
 
 Options (override the script's config):
   -o, --output <path>      .mp4 .webm .gif .webp .svg .html .png .jpg or dir/ for PNG frames — repeatable
@@ -44,10 +48,16 @@ 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)
+      --cols <n> --rows <n>  terminal grid (rec: defaults to your terminal's size)
+      --width <px> --height <px>  video size; the grid is derived and centred inside
+      --loop-offset <n|N%> where GIF/WebP loops start
       --cast <path>        where to read/write the .cast
       --record-only        stop after writing the cast
+      --no-script          rec: don't write the editable <name>.video.ts next to the cast
       --force              ignore the cast cache and re-record
+      --open               publish: open the first link in the browser
+      --name <file>        publish: object name (default: the file's basename)
+      --endpoint --bucket --access-key --secret-key --public-url --region   publish --setup values
       --template <name>    for init: basic | tour | test
   -q, --quiet
   -h, --help
@@ -75,9 +85,22 @@ const { values, positionals } = parseArgs({
     core: { type: "string" },
     cols: { type: "string" },
     rows: { type: "string" },
+    width: { type: "string" },
+    height: { type: "string" },
+    "loop-offset": { type: "string" },
     cast: { type: "string" },
     "record-only": { type: "boolean" },
+    "no-script": { type: "boolean" },
     force: { type: "boolean" },
+    setup: { type: "boolean" },
+    open: { type: "boolean" },
+    name: { type: "string" },
+    endpoint: { type: "string" },
+    bucket: { type: "string" },
+    "access-key": { type: "string" },
+    "secret-key": { type: "string" },
+    "public-url": { type: "string" },
+    region: { type: "string" },
     template: { type: "string" },
     quiet: { type: "boolean", short: "q" },
     help: { type: "boolean", short: "h" },
@@ -135,6 +158,9 @@ function overridesFromFlags(): Partial<VideoConfig> {
   if (values.cast) o.cast = values.cast;
   if (values.cols !== undefined) o.cols = num("cols");
   if (values.rows !== undefined) o.rows = num("rows");
+  if (values.width !== undefined) o.width = num("width");
+  if (values.height !== undefined) o.height = num("height");
+  if (values["loop-offset"] !== undefined) o.loopOffset = values["loop-offset"];
   return o;
 }
 
@@ -281,7 +307,47 @@ async function main(): Promise<void> {
 
   switch (first) {
     case "themes": {
-      for (const name of themeNames) console.log(name);
+      const names = rest[0] ? findThemes(rest[0]) : themeNames;
+      if (names.length === 0) fail(`No theme matches "${rest[0]}"`);
+      for (const name of names) console.log(name);
+      if (!rest[0]) log(dim(`${names.length} themes · use any name with --theme, e.g. --theme "Gruvbox Dark"`));
+      return;
+    }
+    case "publish": {
+      if (values.setup) {
+        const ask = async (label: string, flag: string | undefined, fallback: string, secret = false): Promise<string> => {
+          if (flag) return flag;
+          if (!process.stdin.isTTY) return fallback;
+          const answer = prompt(`${label}${fallback ? ` [${fallback}]` : ""}:`) ?? "";
+          return answer.trim() || fallback;
+        };
+        const existing = await loadPublishConfig().catch(() => null);
+        const cfg: PublishConfig = {
+          endpoint: await ask("S3 endpoint", values.endpoint, existing?.endpoint ?? "https://s3.amanv.cloud"),
+          bucket: await ask("Bucket", values.bucket, existing?.bucket ?? "tcut"),
+          accessKeyId: await ask("Access key", values["access-key"], existing?.accessKeyId ?? ""),
+          secretAccessKey: await ask("Secret key", values["secret-key"], existing?.secretAccessKey ?? "", true),
+          region: values.region ?? existing?.region ?? "us-east-1",
+          ...(values["public-url"] || existing?.publicUrl ? { publicUrl: values["public-url"] ?? existing?.publicUrl } : {}),
+        };
+        if (!cfg.accessKeyId || !cfg.secretAccessKey) fail("publish --setup needs --access-key and --secret-key (or run it in a terminal to be prompted)");
+        const result = await ensurePublicBucket(cfg, log);
+        const file = await savePublishConfig(cfg);
+        ok(`saved ${file}`, "mode 600");
+        ok(`bucket ${cfg.bucket} on ${cfg.endpoint}`, result.bucketCreated ? "created" : "exists");
+        if (result.publicReadOk) ok("public read verified", `links will look like ${publicUrlFor(cfg, "x").replace(/\/x$/, "/<hash>/demo.gif")}`);
+        else log(`${red("✘")} anonymous read failed — set a public-read policy on the bucket or pass --public-url for a CDN/proxy in front of it`);
+        return;
+      }
+      if (rest.length === 0) fail("publish needs at least one file (or --setup)");
+      const cfg = await loadPublishConfig();
+      if (!cfg) fail("publish is not configured yet — run `tcut publish --setup` (or set TCUT_S3_ENDPOINT/BUCKET/ACCESS_KEY/SECRET_KEY)");
+      const published = await publishFiles(rest, cfg, { name: values.name, log });
+      for (const p of published) ok(p.url, dim(path.basename(p.file)));
+      if (values.open && published[0]) {
+        const opener = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
+        Bun.spawn([opener, published[published.length - 1]!.url], { stdout: "ignore", stderr: "ignore" });
+      }
       return;
     }
     case "init": {
@@ -299,15 +365,27 @@ async function main(): Promise<void> {
     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 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;
-      // Size: --cols/--rows if given, else the terminal tcut runs in.
-      const recording = await recordLive(config, { command, log, cols: overrides.cols, rows: overrides.rows });
+      // 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,
+        log,
+        cols: overrides.cols ?? (sized ? config.cols : undefined),
+        rows: overrides.rows ?? (sized ? config.rows : undefined),
+      });
       await mkdir(path.dirname(path.resolve(config.cast)), { recursive: true });
       await writeCast(config.cast, recording);
       log("");
       ok(`wrote ${config.cast}`, `${recording.events.length} events, ${(recording.header.duration ?? 0).toFixed(1)}s`);
+      if (!values["no-script"]) {
+        const scriptPath = config.cast.replace(/\.cast$/, "") + ".video.ts";
+        await Bun.write(scriptPath, generateScript(recording, { output: outputs, cleanShell: !command, command, castPath: config.cast }));
+        ok(`wrote ${scriptPath}`, "editable script — tweak it, then `tcut " + scriptPath + "`");
+      }
       if (values["record-only"]) return;
       const result = await renderOutputs(recording, config, progressReporter());
       await reportOutputs(result.outputs, result.screenshots);

package/src/config.ts

@@ -14,12 +14,34 @@ export function defaultPromptPattern(prompt: string): RegExp {
   return new RegExp(`${escapeRegExp(prompt.trimEnd())}\\s*$`);
 }
 
+/** Approximate cell size before anything is measured (JetBrains Mono / Menlo are ~0.6em wide). */
+export function estimateCell(font: { size: number; lineHeight: number; letterSpacing: number }): { w: number; h: number } {
+  return { w: Math.round(font.size * 0.6 * 100) / 100 + font.letterSpacing, h: Math.ceil(font.size * font.lineHeight) };
+}
+
+export const WINDOW_BAR_HEIGHT = 36;
+
 export function resolveConfig(config: VideoConfig): ResolvedConfig {
   const outputs = Array.isArray(config.output) ? config.output : [config.output];
   if (outputs.length === 0) throw new Error("config.output must name at least one output");
 
   const prompt = config.prompt ?? "> ";
   const theme = resolveTheme(config.theme);
+
+  const font = {
+    family: config.font?.family ?? DEFAULT_FONT_FAMILY,
+    size: config.font?.size ?? 20,
+    lineHeight: config.font?.lineHeight ?? 1.2,
+    letterSpacing: config.font?.letterSpacing ?? 0,
+  };
+  const padding = config.padding ?? 24;
+  const margin = config.margin ?? 0;
+  const bar = (config.windowBar ?? "none") === "none" ? 0 : WINDOW_BAR_HEIGHT;
+  const cell = estimateCell(font);
+  let cols = config.cols;
+  let rows = config.rows;
+  if (config.width !== undefined && cols === undefined) cols = Math.max(10, Math.floor((config.width - 2 * margin - 2 * padding) / cell.w));
+  if (config.height !== undefined && rows === undefined) rows = Math.max(3, Math.floor((config.height - 2 * margin - 2 * padding - bar) / cell.h));
   const first = outputs[0]!;
   const castDefault = first.endsWith("/")
     ? path.join(first, "session.cast")
@@ -33,8 +55,11 @@ export function resolveConfig(config: VideoConfig): ResolvedConfig {
     promptPattern: (config.promptPattern ?? defaultPromptPattern(prompt)).source,
     cwd: config.cwd ?? process.cwd(),
     env: config.env ?? {},
-    cols: config.cols ?? 80,
-    rows: config.rows ?? 24,
+    cols: cols ?? 80,
+    rows: rows ?? 24,
+    ...(config.width !== undefined && { width: config.width }),
+    ...(config.height !== undefined && { height: config.height }),
+    ...(config.loopOffset !== undefined && { loopOffset: config.loopOffset }),
     fps: config.fps ?? 60,
     typingSpeed: toMs(config.typingSpeed, 50),
     typingJitter: Math.min(1, Math.max(0, config.typingJitter ?? 0)),
@@ -45,19 +70,14 @@ export function resolveConfig(config: VideoConfig): ResolvedConfig {
     quantize: config.quantize ?? false,
     core: config.core ?? "ghostty",
     cache: config.cache ?? true,
-    font: {
-      family: config.font?.family ?? DEFAULT_FONT_FAMILY,
-      size: config.font?.size ?? 20,
-      lineHeight: config.font?.lineHeight ?? 1.2,
-      letterSpacing: config.font?.letterSpacing ?? 0,
-    },
+    font,
     theme,
     cursor: {
       blink: config.cursor?.blink ?? true,
       period: config.cursor?.period ?? 1000,
     },
-    padding: config.padding ?? 24,
-    margin: config.margin ?? 0,
+    padding,
+    margin,
     marginFill: config.marginFill ?? theme.background,
     borderRadius: config.borderRadius ?? 0,
     windowBar: config.windowBar ?? "none",

package/src/export/svg.ts

@@ -1,3 +1,4 @@
+import { fitFrame } from "../loop";
 import { barHeight } from "../renderer/page";
 import type { Recording, ResolvedConfig } from "../types";
 import { FLAG, replayFrames, type GridCell, type GridFrame } from "./frames";
@@ -28,8 +29,15 @@ export function svgGeometry(config: ResolvedConfig, cols: number, rows: number):
   const termW = cols * cellW;
   const termH = rows * cellH;
   const bar = barHeight(config);
-  const frameW = termW + config.padding * 2;
-  const frameH = termH + config.padding * 2 + bar;
+  const fit = fitFrame({
+    termW: Math.ceil(termW),
+    termH,
+    padding: config.padding,
+    margin: config.margin,
+    bar,
+    width: config.width,
+    height: config.height,
+  });
   return {
     cellW,
     cellH,
@@ -37,12 +45,12 @@ export function svgGeometry(config: ResolvedConfig, cols: number, rows: number):
     termH,
     frameX: config.margin,
     frameY: config.margin,
-    frameW,
-    frameH,
-    termX: config.margin + config.padding,
-    termY: config.margin + config.padding + bar,
-    width: Math.ceil(frameW + config.margin * 2),
-    height: Math.ceil(frameH + config.margin * 2),
+    frameW: fit.frameW,
+    frameH: fit.frameH,
+    termX: config.margin + fit.padX,
+    termY: config.margin + fit.padY + bar,
+    width: fit.width,
+    height: fit.height,
   };
 }
 

package/src/index.ts

@@ -9,7 +9,11 @@ export { replayFrames } from "./export/frames";
 export type { GridFrame, GridCell, GridReplay } from "./export/frames";
 export { runScriptTests, discoverScripts } from "./testing";
 export type { TestResult, TestSummary } from "./testing";
-export { themes, themeNames, resolveTheme } from "./themes";
+export { themes, themeNames, resolveTheme, findThemes, themeSlug, builtinThemes } from "./themes";
+export { generateScript, eventsToOps, tokenize } from "./scriptgen";
+export type { ScriptGenOptions } from "./scriptgen";
+export { publishFiles, loadPublishConfig, savePublishConfig, ensurePublicBucket, publicUrlFor, keyFor } from "./publish";
+export type { PublishConfig, Published, PublishOptions } from "./publish";
 export { readCast, writeCast, parseCast, serializeCast } from "./cast";
 export { buildTimeline } from "./timeline";
 export { resolveConfig } from "./config";

package/src/keys.ts

@@ -51,6 +51,34 @@ export function ctrlSequence(key: string): string {
   throw new Error(`Cannot send Ctrl+${key}`);
 }
 
+const shiftedNamed: Record<string, string> = {
+  tab: `${ESC}[Z`,
+  up: `${ESC}[1;2A`,
+  down: `${ESC}[1;2B`,
+  right: `${ESC}[1;2C`,
+  left: `${ESC}[1;2D`,
+  home: `${ESC}[1;2H`,
+  end: `${ESC}[1;2F`,
+  delete: `${ESC}[3;2~`,
+  pageUp: `${ESC}[5;2~`,
+  pageDown: `${ESC}[6;2~`,
+  enter: "\r",
+  space: " ",
+};
+
+/** Shift+<key>: back-tab, shifted navigation keys (xterm modifier 2), or an uppercased character. */
+export function shiftSequence(key: string): string {
+  const named = shiftedNamed[key];
+  if (named) return named;
+  if (key.length === 1) return key.toUpperCase();
+  throw new Error(`Cannot send Shift+${key}. Known: ${Object.keys(shiftedNamed).join(", ")}, or a single character.`);
+}
+
+/** SGR mouse wheel event (button 64 = up, 65 = down) at a 1-based cell position. */
+export function wheelSequence(direction: "up" | "down", col: number, row: number): string {
+  return `${ESC}[<${direction === "up" ? 64 : 65};${col};${row}M`;
+}
+
 /** Alt/Meta+<key> → ESC-prefixed key. */
 export function altSequence(key: string): string {
   const isNamed = key in keySequences;

package/src/loop.ts

@@ -0,0 +1,45 @@
+/** Resolve a `loopOffset` (frame count or "N%") to a frame index in `[0, total)`. */
+export function loopOffsetFrames(total: number, value: number | string | undefined): number {
+  if (!value || total <= 1) return 0;
+  let frames: number;
+  if (typeof value === "string") {
+    const m = /^\s*(\d+(?:\.\d+)?)\s*(%?)\s*$/.exec(value);
+    if (!m) throw new Error(`Invalid loopOffset "${value}" (use a frame count or a percentage like "50%")`);
+    frames = m[2] ? Math.round((Number(m[1]) / 100) * total) : Math.round(Number(m[1]));
+  } else {
+    frames = Math.round(value);
+  }
+  return ((frames % total) + total) % total;
+}
+
+/** Start the sequence at `offset`, appending the frames before it at the end. */
+export function rotateFrames<T>(frames: T[], offset: number): T[] {
+  if (offset <= 0 || offset >= frames.length) return frames;
+  return [...frames.slice(offset), ...frames.slice(0, offset)];
+}
+
+/** Place the terminal grid inside a frame of the requested size (or wrap it tightly when no size is requested). */
+export function fitFrame(opts: {
+  termW: number;
+  termH: number;
+  padding: number;
+  margin: number;
+  bar: number;
+  width?: number;
+  height?: number;
+}): { frameW: number; frameH: number; padX: number; padY: number; width: number; height: number } {
+  const even = (n: number) => (n % 2 === 0 ? n : n + 1);
+  let frameW = opts.termW + opts.padding * 2;
+  let frameH = opts.termH + opts.padding * 2 + opts.bar;
+  let padX = opts.padding;
+  let padY = opts.padding;
+  if (opts.width !== undefined || opts.height !== undefined) {
+    const targetW = (opts.width ?? frameW + opts.margin * 2) - opts.margin * 2;
+    const targetH = (opts.height ?? frameH + opts.margin * 2) - opts.margin * 2;
+    frameW = Math.max(opts.termW, targetW);
+    frameH = Math.max(opts.termH + opts.bar, targetH);
+    padX = Math.floor((frameW - opts.termW) / 2);
+    padY = Math.floor((frameH - opts.bar - opts.termH) / 2);
+  }
+  return { frameW, frameH, padX, padY, width: even(frameW + opts.margin * 2), height: even(frameH + opts.margin * 2) };
+}