termcut 0.6.3 → 0.7.0

package/README.md

@@ -51,7 +51,15 @@ defineVideo({ output: "demo.mp4", browser: { position: "overlay" } }, async (t)
 });
 ```
 
-Polish: `keys: true` shows key presses, `maxPause: "800ms"` cuts dead air, `t.zoom({ rows: [0, 5] })` magnifies output, `t.chapter("Install")` adds mp4 chapters, `preset: "x"` sizes it for X. `tcut diff a.cast b.cast` catches output changes in CI.
+Polish: `shadow: true`, `watermark: "© you"`, `marginFill: "transparent"` (real alpha in PNG/WebP/GIF/WebM/SVG), `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, `preset: "x"` sizes it for X. `tcut diff a.cast b.cast` catches output changes in CI.
+
+Cut and join without re-recording — on the cast, so every format works:
+
+```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 concat intro.cast demo.cast --gap 500ms -o launch.mp4
+```
 
 Re-render any recording without re-running it — ~600 themes ([Ghostty's collection](https://github.com/mbadolato/iTerm2-Color-Schemes)), `tcut themes` lists them:
 
@@ -66,6 +74,14 @@ tcut publish --setup        # once: your S3-compatible bucket (RustFS, MinIO, R2
 tcut publish demo.gif       # → https://…/3f9a1c2b7d4e/demo.gif
 ```
 
+## Agents
+
+```sh
+npx skills add AmanVarshney01/tcut   # tcut + tcut-remotion skills for Claude Code, Cursor, etc.
+```
+
+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.
+
 ## More
 
 - [Examples](https://github.com/AmanVarshney01/tcut/tree/main/packages/tcut/examples) — driving an interactive TUI, recording Claude Code / Codex

package/package.json

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

package/scripts/build-themes.ts

@@ -47,15 +47,19 @@ function parse(name: string, text: string): Record<string, string> | null {
   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 entries: [string, string][] = [
+    ["name", name],
+    ["background", background],
+    ["foreground", foreground],
+  ];
   const cursor = hex(props["cursor-color"] ?? "");
-  if (cursor) theme.cursor = cursor;
+  if (cursor) entries.push(["cursor", cursor]);
   const cursorText = hex(props["cursor-text"] ?? "");
-  if (cursorText) theme.cursorAccent = cursorText;
+  if (cursorText) entries.push(["cursorAccent", cursorText]);
   const selection = hex(props["selection-background"] ?? "");
-  if (selection) theme.selectionBackground = selection;
-  KEYS.forEach((k, i) => (theme[k] = palette[i]!));
-  return theme;
+  if (selection) entries.push(["selectionBackground", selection]);
+  KEYS.forEach((k, i) => entries.push([k, palette[i]!]));
+  return Object.fromEntries(entries);
 }
 
 const tmp = await mkdtemp(path.join(tmpdir(), "tcut-themes-"));

package/src/browser.ts

@@ -17,7 +17,7 @@ export function normalizeUrl(url: string): string {
 }
 
 const toRegExp = (pattern: RegExp | string): RegExp =>
-  typeof pattern === "string" ? new RegExp(pattern.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")) : pattern;
+  pattern instanceof RegExp ? pattern : new RegExp(pattern.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"));
 
 /**
  * A Bun.WebView sampled on the recording clock, shared by scripted and live recording. Only changed frames are
@@ -25,7 +25,7 @@ const toRegExp = (pattern: RegExp | string): RegExp =>
  */
 export function startBrowserCapture(config: ResolvedConfig, stamp: () => number, log: (m: string) => void = () => {}): BrowserCapture {
   if (!config.browser) throw new Error("startBrowserCapture needs config.browser");
-  if (typeof Bun.WebView !== "function") throw new Error("The browser pane needs Bun.WebView (Bun >= 1.4).");
+  if (!Bun.WebView) throw new Error("The browser pane needs Bun.WebView (Bun >= 1.4).");
   const bcfg = config.browser;
 
   // Default pane size: match the terminal window (estimated from the font metrics) unless given.
@@ -75,7 +75,7 @@ export function startBrowserCapture(config: ResolvedConfig, stamp: () => number,
       try {
         navigation ??= view.navigate(url).then(
         () => "ok" as const,
-          (err: unknown) => (/pending/i.test(String(err)) ? ("pending" as const) : ("failed" as const)),
+          (cause: unknown) => (/pending/i.test(String(cause)) ? ("pending" as const) : ("failed" as const)),
         );
       } catch {
         return; // navigate threw synchronously: the view is closed

package/src/cast.ts

@@ -44,5 +44,7 @@ export const MARKER = {
   focus: "focus:",
   zoom: "zoom:",
   chapter: "chapter:",
+  /** Render-clock speed for the events that follow (`speed:8`); `speed:1` restores real time. */
+  speed: "speed:",
   end: "end",
 } as const;

package/src/cli.ts

@@ -2,19 +2,21 @@
 import { mkdir } from "node:fs/promises";
 import path from "node:path";
 import { parseArgs } from "node:util";
-import { writeCast } from "./cast";
-import { resolveConfig } from "./config";
+import { readCast, writeCast } from "./cast";
+import { applyOverrides, resolveConfig } from "./config";
 import * as api from "./index";
 import { recordLive } from "./live";
-import { ensurePublicBucket, loadPublishConfig, publicUrlFor, publishFiles, savePublishConfig, type PublishConfig } from "./publish";
-import { diffCasts } from "./diff";
+import { ensurePublicBucket, loadPublishConfig, publicUrlFor, publishFiles, savePublishConfig, type PublishConfig, type Published } from "./publish";
+import { diffCasts, type DiffResult } from "./diff";
+import { toMs } from "./duration";
+import { concatRecordings, cutRecording, flattenedConfig, rebaseBrowserFrames, recordingDuration, selectChapters } from "./edit";
 import { presetNames, type PresetName } from "./presets";
 import { renderOutputs } from "./render";
 import { generateScript } from "./scriptgen";
-import { runScriptTests } from "./testing";
+import { runScriptTests, type TestSummary } from "./testing";
 import { findThemes, themeNames } from "./themes";
-import type { BrowserConfig, CoreName, ThemeName, VideoConfig, WindowBar } from "./types";
-import { Video, attachBrowserFrames, isVideo, renderCast } from "./video";
+import type { BrowserConfig, ClipSelection, CoreName, ThemeName, VideoConfig, WindowBar } from "./types";
+import { Video, attachBrowserFrames, castConfig, isVideo, renderCast } from "./video";
 
 // Let user scripts `import { defineVideo } from "tcut"` (or "termcut", the npm package name) regardless of
 // where they live or whether this is the compiled binary (no node_modules there): resolve the bare specifier
@@ -37,6 +39,8 @@ Usage:
   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 diff <a.cast> <b.cast>         compare what two recordings show on screen (exit 1 if different)
+  tcut cut <file.cast> --from 2s --to 10s [--cast out.cast] [-o …]   keep part of a recording (by time or --chapters)
+  tcut concat <a.cast> <b.cast…> [--gap 500ms] [--cast out.cast] [-o …]   join recordings end to end
   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)
@@ -56,6 +60,12 @@ Options (override the script's config):
       --loop-offset <n|N%> where GIF/WebP loops start
       --max-pause <dur>    idle compression: cap gaps between events (e.g. 800ms)
       --keys               show recent key presses as chips
+      --shadow             drop shadow under the window (margin defaults to 40)
+      --watermark <text>   text in the bottom-right corner; --watermark-image <file> for a logo
+      --from <t> --to <t>  render/cut only this part of the visible timeline (seconds, or "1.5s", "2m")
+      --chapters <a,b>     render/cut only these chapters (titles or numbers), joined in that order
+      --split-chapters     one output per chapter: demo.mp4 → demo-01-install.mp4 …
+      --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)
       --at <seconds>       diff: compare the screen at this time instead of the end
@@ -71,6 +81,8 @@ Options (override the script's config):
       --json               machine-readable result (or { "error" }) on stdout, nothing else
   -q, --quiet
   -h, --help
+
+Agents: npx skills add AmanVarshney01/tcut   ·   docs: https://tcut.amanv.dev/llms.txt
 `;
 
 const { values, positionals } = parseArgs({
@@ -103,6 +115,14 @@ const { values, positionals } = parseArgs({
     preset: { type: "string" },
     browser: { type: "string" },
     "browser-position": { type: "string" },
+    shadow: { type: "boolean" },
+    watermark: { type: "string" },
+    "watermark-image": { type: "string" },
+    from: { type: "string" },
+    to: { type: "string" },
+    chapters: { type: "string" },
+    "split-chapters": { type: "boolean" },
+    gap: { type: "string" },
     at: { type: "string" },
     images: { type: "string" },
     cast: { type: "string" },
@@ -127,8 +147,25 @@ const { values, positionals } = parseArgs({
 
 const json = values.json === true;
 const quiet = values.quiet === true || json;
+interface OutputFile {
+  path: string;
+  bytes: number;
+}
+
+/** Every shape `--json` can print (one document on stdout; failures print `{ error, type }` instead). */
+type CliReport =
+  | { published: Published[] }
+  | { cast: string; script: string | null; events: number; durationSeconds: number }
+  | { cast: string; script: string | null; outputs: OutputFile[]; frames: number; durationSeconds: number }
+  | { cast: string; cached: boolean; events: number; durationSeconds: number }
+  | { cast: string; outputs: OutputFile[]; frames: number; durationSeconds: number }
+  | { cast: string; cached: boolean; outputs: OutputFile[]; frames: number; durationSeconds: number }
+  | { cast: string; events: number; durationSeconds: number; outputs: OutputFile[] }
+  | DiffResult
+  | TestSummary;
+
 /** With --json, the only thing on stdout is one JSON document (results or { error }). */
-const emit = (data: unknown) => {
+const emit = (data: CliReport) => {
   if (json) process.stdout.write(JSON.stringify(data, null, 2) + "\n");
 };
 const useColor = process.stdout.isTTY === true && !process.env.NO_COLOR;
@@ -187,6 +224,10 @@ function overridesFromFlags(): Partial<VideoConfig> {
   if (values["loop-offset"] !== undefined) o.loopOffset = values["loop-offset"];
   if (values["max-pause"] !== undefined) o.maxPause = values["max-pause"];
   if (values.keys) o.keys = true;
+  if (values.shadow) o.shadow = true;
+  if (values.watermark || values["watermark-image"]) {
+    o.watermark = { ...(values.watermark && { text: values.watermark }), ...(values["watermark-image"] && { image: values["watermark-image"] }) };
+  }
   if (values.preset) {
     if (!presetNames.includes(values.preset as PresetName)) fail(`--preset must be one of ${presetNames.join(", ")}`);
     o.preset = values.preset as PresetName;
@@ -199,6 +240,28 @@ function overridesFromFlags(): Partial<VideoConfig> {
   return o;
 }
 
+/** `--from 2` and `--at 2` are seconds; `--from 1.5s` / `"2m"` go through the duration parser. */
+function seconds(flag: "from" | "to" | "gap"): number | undefined {
+  const raw = values[flag];
+  if (raw === undefined) return undefined;
+  return /^\s*\d+(\.\d+)?\s*$/.test(raw) ? Number(raw) : toMs(raw) / 1000;
+}
+
+function clipFromFlags(): ClipSelection | undefined {
+  const clip: ClipSelection = {};
+  const from = seconds("from");
+  const to = seconds("to");
+  if (from !== undefined) clip.from = from;
+  if (to !== undefined) clip.to = to;
+  if (values.chapters) clip.chapters = values.chapters.split(",").map((s) => s.trim()).filter(Boolean);
+  if (values["split-chapters"]) clip.splitChapters = true;
+  return Object.keys(clip).length ? clip : undefined;
+}
+
+function reportNotes(notes: string[] | undefined): void {
+  for (const note of notes ?? []) log(dim(`  note: ${note}`));
+}
+
 async function loadVideo(file: string): Promise<Video> {
   const abs = path.resolve(file);
   if (!(await Bun.file(abs).exists())) fail(`Script not found: ${file}`);
@@ -246,14 +309,14 @@ async function fileSize(file: string): Promise<string> {
 
 const ok = (what: string, detail = "") => log(`${green("✔")} ${what}${detail ? ` ${dim(detail)}` : ""}`);
 
-async function reportOutputs(outputs: string[], screenshots: string[]): Promise<Array<{ path: string; bytes: number }>> {
+async function reportOutputs(outputs: string[], screenshots: string[]): Promise<OutputFile[]> {
   for (const out of outputs) ok(`wrote ${out}`, await fileSize(out));
   for (const shot of screenshots) ok(`screenshot ${shot}`);
   return Promise.all([...outputs, ...screenshots].map(async (p) => ({ path: p, bytes: (await Bun.file(p).exists()) ? Bun.file(p).size : 0 })));
 }
 
-const TEMPLATES: Record<string, (name: string) => string> = {
-  basic: (name) => `import { defineVideo } from "tcut";
+const TEMPLATES = new Map<string, (name: string) => string>([
+  ["basic", (name) => `import { defineVideo } from "tcut";
 
 export default defineVideo(
   {
@@ -273,8 +336,8 @@ export default defineVideo(
     await t.sleep("2s");
   },
 );
-`,
-  tour: (name) => `import { defineVideo } from "tcut";
+`],
+  ["tour", (name) => `import { defineVideo } from "tcut";
 
 export default defineVideo(
   {
@@ -308,8 +371,8 @@ export default defineVideo(
     await t.sleep("1.5s");
   },
 );
-`,
-  test: (name) => `import { defineVideo } from "tcut";
+`],
+  ["test", (name) => `import { defineVideo } from "tcut";
 
 // Run with: tcut test ${name}.tcut.ts   (fast mode: no sleeps, no typing delay)
 export default defineVideo(
@@ -328,8 +391,8 @@ export default defineVideo(
     await t.expect(/ok/);
   },
 );
-`,
-};
+`],
+]);
 
 async function main(): Promise<void> {
   if (values.help || positionals.length === 0) {
@@ -351,7 +414,7 @@ async function main(): Promise<void> {
     }
     case "publish": {
       if (values.setup) {
-        const ask = async (label: string, flag: string | undefined, fallback: string, secret = false): Promise<string> => {
+        const ask = async (label: string, flag: string | undefined, fallback: string): Promise<string> => {
           if (flag) return flag;
           if (!process.stdin.isTTY) return fallback;
           const answer = prompt(`${label}${fallback ? ` [${fallback}]` : ""}:`) ?? "";
@@ -362,9 +425,9 @@ async function main(): Promise<void> {
           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),
+          secretAccessKey: await ask("Secret key", values["secret-key"], existing?.secretAccessKey ?? ""),
           region: values.region ?? existing?.region ?? "us-east-1",
-          ...(values["public-url"] || existing?.publicUrl ? { publicUrl: values["public-url"] ?? existing?.publicUrl } : {}),
+          publicUrl: values["public-url"] || existing?.publicUrl || undefined,
         };
         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);
@@ -390,8 +453,8 @@ async function main(): Promise<void> {
     case "init": {
       const name = rest[0] ?? "demo";
       const template = values.template ?? "basic";
-      const make = TEMPLATES[template];
-      if (!make) fail(`Unknown template "${template}". Available: ${Object.keys(TEMPLATES).join(", ")}`);
+      const make = TEMPLATES.get(template);
+      if (!make) fail(`Unknown template "${template}". Available: ${[...TEMPLATES.keys()].join(", ")}`);
       const base = name.replace(/\.(video|tcut)\.ts$|\.ts$/, "");
       const file = name.endsWith(".ts") ? name : template === "test" ? `${base}.tcut.ts` : `${base}.video.ts`;
       if (await Bun.file(file).exists()) fail(`${file} already exists`);
@@ -445,12 +508,58 @@ async function main(): Promise<void> {
     }
     case "render": {
       if (!rest[0]) fail("render needs a .cast file");
-      const result = await renderCast(rest[0], overridesFromFlags(), progressReporter());
+      const result = await renderCast(rest[0], overridesFromFlags(), progressReporter(), clipFromFlags());
       const files = await reportOutputs(result.outputs, result.screenshots);
+      reportNotes(result.notes);
       log(dim(`  ${result.frames} frames, ${result.durationSeconds.toFixed(1)}s of video in ${elapsed()}`));
       emit({ cast: rest[0], outputs: files, frames: result.frames, durationSeconds: result.durationSeconds });
       return;
     }
+    case "cut":
+    case "concat": {
+      const joining = first === "concat";
+      if (joining ? rest.length < 2 : !rest[0]) fail(joining ? "concat needs two or more .cast files" : "cut needs a .cast file");
+      const clip = clipFromFlags();
+      if (!joining && !clip) fail("cut needs --from/--to and/or --chapters");
+      const castOut = values.cast ?? (joining ? path.join(path.dirname(rest[0]!), "concat.cast") : rest[0]!.replace(/\.cast$/, "") + "-cut.cast");
+      const overrides = overridesFromFlags();
+      delete overrides.cast;
+      const parts: Array<{ rec: Awaited<ReturnType<typeof readCast>>; config: ReturnType<typeof castConfig> }> = [];
+      for (const [i, file] of rest.entries()) {
+        const rec = await readCast(file);
+        const config = applyOverrides(castConfig(rec, file, values.output), overrides);
+        parts.push({ rec: await rebaseBrowserFrames(rec, file, castOut, joining ? `${i}-` : ""), config });
+      }
+      let out: Awaited<ReturnType<typeof readCast>>;
+      if (joining) {
+        out = concatRecordings(parts, { gap: seconds("gap") ?? 0 });
+      } else {
+        const { rec, config } = parts[0]!;
+        let part = rec;
+        let partConfig = config;
+        if (clip?.chapters) {
+          part = selectChapters(rec, config, clip.chapters);
+          partConfig = flattenedConfig(config);
+        }
+        out = clip && (clip.from !== undefined || clip.to !== undefined) ? cutRecording(part, partConfig, clip) : part;
+      }
+      const renderConfig = { ...flattenedConfig(parts[0]!.config), cast: castOut, output: values.output?.length ? values.output : parts[0]!.config.output };
+      out.header.bunVideo = renderConfig;
+      await mkdir(path.dirname(path.resolve(castOut)), { recursive: true });
+      await writeCast(castOut, out);
+      out.source = path.resolve(castOut);
+      const durationSeconds = recordingDuration(out);
+      ok(`wrote ${castOut}`, `${out.events.length} events, ${durationSeconds.toFixed(1)}s`);
+      let files: OutputFile[] = [];
+      if (values.output?.length) {
+        const result = await renderOutputs(out, renderConfig, progressReporter());
+        files = await reportOutputs(result.outputs, result.screenshots);
+        reportNotes(result.notes);
+        log(dim(`  ${result.frames} frames, ${result.durationSeconds.toFixed(1)}s of video in ${elapsed()}`));
+      }
+      emit({ cast: castOut, events: out.events.length, durationSeconds, outputs: files });
+      return;
+    }
     case "diff": {
       if (rest.length < 2) fail("diff needs two .cast files");
       const result = await diffCasts(rest[0]!, rest[1]!, { at: values.at !== undefined ? num("at") : undefined, images: values.images });
@@ -474,7 +583,8 @@ async function main(): Promise<void> {
     // eslint-disable-next-line no-fallthrough -- process.exit above never returns
     default: {
       const video = await loadVideo(first!);
-      const result = await video.run({ log, force: values.force, recordOnly: values["record-only"], onProgress: progressReporter() });
+      const result = await video.run({ log, force: values.force, recordOnly: values["record-only"], onProgress: progressReporter(), clip: clipFromFlags() });
+      reportNotes(result.notes);
       ok(`${result.cached ? "reused" : "wrote"} ${result.cast}`);
       const files = await reportOutputs(result.outputs, result.screenshots);
       if (!values["record-only"]) log(dim(`  ${result.frames} frames, ${result.durationSeconds.toFixed(1)}s of video in ${elapsed()}`));
@@ -483,9 +593,9 @@ async function main(): Promise<void> {
   }
 }
 
-main().catch((err: unknown) => {
-  const message = err instanceof Error ? err.message : String(err);
-  if (json) process.stdout.write(JSON.stringify({ error: message, type: err instanceof Error ? err.name : "Error" }) + "\n");
+main().catch((cause: unknown) => {
+  const message = cause instanceof Error ? cause.message : String(cause);
+  if (json) process.stdout.write(JSON.stringify({ error: message, type: cause instanceof Error ? cause.name : "Error" }) + "\n");
   else console.error(`\n${red("error:")} ${message}`);
   process.exit(1);
 });

package/src/config.ts

@@ -15,8 +15,14 @@ export function defaultPromptPattern(prompt: string): RegExp {
   return new RegExp(`${escapeRegExp(prompt.trimEnd())}\\s*$`);
 }
 
+/** Size of one terminal cell in CSS pixels. */
+export interface CellSize {
+  w: number;
+  h: number;
+}
+
 /** 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 } {
+export function estimateCell(font: { size: number; lineHeight: number; letterSpacing: number }): CellSize {
   return { w: Math.round(font.size * 0.6 * 100) / 100 + font.letterSpacing, h: Math.ceil(font.size * font.lineHeight) };
 }
 
@@ -37,7 +43,30 @@ export function resolveConfig(input: VideoConfig): ResolvedConfig {
     letterSpacing: config.font?.letterSpacing ?? 0,
   };
   const padding = config.padding ?? 24;
-  const margin = config.margin ?? 0;
+  const shadow = config.shadow
+    ? {
+        x: (config.shadow === true ? undefined : config.shadow.x) ?? 0,
+        y: (config.shadow === true ? undefined : config.shadow.y) ?? 18,
+        blur: (config.shadow === true ? undefined : config.shadow.blur) ?? 50,
+        color: (config.shadow === true ? undefined : config.shadow.color) ?? "#000000",
+        opacity: (config.shadow === true ? undefined : config.shadow.opacity) ?? 0.45,
+      }
+    : undefined;
+  // A shadow needs room around the window; give it some unless the margin was set explicitly.
+  const margin = config.margin ?? (shadow ? 40 : 0);
+  const wm = config.watermark === undefined ? undefined : config.watermark instanceof Object ? config.watermark : { text: config.watermark };
+  const watermark = wm
+    ? {
+        ...(wm.text !== undefined && { text: wm.text }),
+        ...(wm.image !== undefined && { image: wm.image }),
+        position: wm.position ?? "bottom-right",
+        opacity: wm.opacity ?? 0.6,
+        size: wm.size ?? (wm.image ? 28 : 14),
+        color: wm.color ?? theme.foreground,
+        margin: wm.margin ?? 16,
+      }
+    : undefined;
+  if (watermark && !watermark.text && !watermark.image) throw new Error("watermark needs `text` or `image`");
   const bar = (config.windowBar ?? "none") === "none" ? 0 : WINDOW_BAR_HEIGHT;
   const cell = estimateCell(font);
   let cols = config.cols;
@@ -105,6 +134,8 @@ export function resolveConfig(input: VideoConfig): ResolvedConfig {
     padding,
     margin,
     marginFill: config.marginFill ?? theme.background,
+    ...(shadow && { shadow }),
+    ...(watermark && { watermark }),
     borderRadius: config.borderRadius ?? 0,
     windowBar: config.windowBar ?? "none",
     title: config.title ?? "",
@@ -117,6 +148,8 @@ export function applyOverrides(base: ResolvedConfig, overrides: Partial<VideoCon
   const merged: VideoConfig = {
     ...base,
     promptPattern: new RegExp(base.promptPattern),
+    // ResolvedConfig keeps maxPause in seconds; VideoConfig reads bare numbers as milliseconds.
+    maxPause: base.maxPause === undefined ? undefined : base.maxPause * 1000,
     ...overrides,
     font: { ...base.font, ...overrides.font },
     cursor: { ...base.cursor, ...overrides.cursor },

package/src/diff.ts

@@ -1,7 +1,7 @@
 import path from "node:path";
 import { readCast } from "./cast";
 import { applyOverrides, resolveConfig } from "./config";
-import { replayFrames, type GridFrame } from "./export/frames";
+import { frameText, replayFrames, type GridFrame } from "./export/frames";
 import { renderOutputs } from "./render";
 import type { Recording, ResolvedConfig } from "./types";
 
@@ -28,21 +28,11 @@ function frameAt(frames: GridFrame[], at: number | undefined): GridFrame {
   return chosen;
 }
 
-function rowsText(frame: GridFrame): string[] {
-  const out: string[] = [];
-  for (let y = 0; y < frame.rows; y++) {
-    const cells = frame.rows_.get(y);
-    out.push(cells ? cells.map((c) => c.text).join("").replace(/\s+$/, "") : "");
-  }
-  while (out.length && out[out.length - 1] === "") out.pop();
-  return out;
-}
-
 /** Simple LCS-based line diff — screens are small, so O(n·m) is fine. */
 function diffLines(a: string[], b: string[]): string[] {
   const n = a.length;
   const m = b.length;
-  const dp: number[][] = Array.from({ length: n + 1 }, () => new Array<number>(m + 1).fill(0));
+  const dp: number[][] = Array.from({ length: n + 1 }, () => Array.from({ length: m + 1 }, () => 0));
   for (let i = n - 1; i >= 0; i--) for (let j = m - 1; j >= 0; j--) dp[i]![j] = a[i] === b[j] ? dp[i + 1]![j + 1]! + 1 : Math.max(dp[i + 1]![j]!, dp[i]![j + 1]!);
   const out: string[] = [];
   let i = 0;
@@ -69,7 +59,7 @@ async function screenOf(rec: Recording, at: number | undefined): Promise<{ text:
   const base = rec.header.bunVideo ?? resolveConfig({ output: "x.svg", cols: rec.header.width, rows: rec.header.height });
   const config = applyOverrides(base, {});
   const replay = await replayFrames(rec, config);
-  return { text: rowsText(frameAt(replay.frames, at)), config };
+  return { text: frameText(frameAt(replay.frames, at)), config };
 }
 
 /** Compare what two recordings show on screen (text, not pixels) at the end or at a given time. */

package/src/duration.ts

@@ -1,18 +1,14 @@
 import type { Duration } from "./types";
 
-const units: Record<string, number> = { ms: 1, s: 1000, m: 60_000 };
+const unitMs = (unit: string | undefined): number => (unit === "s" ? 1000 : unit === "m" ? 60_000 : 1);
 
 /** "500ms" → 500, "1.5s" → 1500, "2m" → 120000, 250 → 250. Bare numbers are milliseconds. */
 export function toMs(value: Duration | undefined, fallback = 0): number {
   if (value === undefined) return fallback;
-  if (typeof value === "number") {
-    if (!Number.isFinite(value) || value < 0) throw new Error(`Invalid duration ${value}`);
-    return value;
-  }
-  const match = /^\s*(\d+(?:\.\d+)?)\s*(ms|s|m)?\s*$/.exec(value);
+  // Numbers and strings share one grammar: a non-negative decimal with an optional unit.
+  const match = /^\s*(\d+(?:\.\d+)?)\s*(ms|s|m)?\s*$/.exec(String(value));
   if (!match) throw new Error(`Invalid duration "${value}" (use e.g. 500, "500ms", "1.5s", "2m")`);
-  const unit = match[2] ?? "ms";
-  return Number(match[1]) * units[unit]!;
+  return Number(match[1]) * unitMs(match[2]);
 }
 
 export function formatMs(ms: number): string {