termcut 0.6.4 → 0.7.0

package/src/edit.ts

@@ -0,0 +1,188 @@
+// Cast-level editing: cut, concatenate and select chapters. Everything works on the *visible* timeline (hides
+// collapsed, speed and idle compression applied), so the result renders identically in every output format and
+// never goes through ffmpeg — a cut cast is still a cast.
+import { mkdir } from "node:fs/promises";
+import path from "node:path";
+import { MARKER } from "./cast";
+import { buildTimeline } from "./timeline";
+import type { CastEvent, Recording, ResolvedConfig } from "./types";
+
+/** A window on the visible timeline, seconds. Either end may be open. */
+export interface ClipRange {
+  from?: number;
+  to?: number;
+}
+
+export interface ChapterRange {
+  title: string;
+  from: number;
+  to: number;
+}
+
+const round = (t: number): number => Number(t.toFixed(6));
+
+/** Config a flattened recording should be rendered with: the timing it was flattened on is now baked in. */
+export function flattenedConfig(config: ResolvedConfig): ResolvedConfig {
+  return { ...config, playbackSpeed: 1 };
+}
+
+/**
+ * The recording re-timed onto its visible timeline: hidden intervals removed, `playbackSpeed`, `maxPause` and
+ * timelapse segments applied, input events kept (the key overlay needs them). Rendering the result with
+ * `flattenedConfig(config)` produces the same video as rendering the original with `config`.
+ */
+export function flattenRecording(rec: Recording, config: ResolvedConfig): Recording {
+  const timeline = buildTimeline(rec.events, config.playbackSpeed, { keepInput: true, maxPause: config.maxPause });
+  const events: CastEvent[] = timeline.events.map((e) => [round(e.vt), e.type, e.data]);
+  return {
+    header: { ...rec.header, duration: round(timeline.duration), bunVideo: flattenedConfig(config) },
+    events,
+    ...(rec.source && { source: rec.source }),
+  };
+}
+
+/** Duration of a recording: its end marker, or the last event. */
+export function recordingDuration(rec: Recording): number {
+  const end = rec.events.find((e) => e[1] === "m" && e[2] === MARKER.end);
+  if (end) return end[0];
+  return rec.events.length ? rec.events[rec.events.length - 1]![0] : 0;
+}
+
+const isState = (e: CastEvent): boolean =>
+  e[1] === "o" || e[1] === "r" || e[1] === "b" || (e[1] === "m" && (e[2].startsWith(MARKER.zoom) || e[2].startsWith(MARKER.focus)));
+
+/**
+ * Keep `[from, to]` of the visible timeline. Everything before `from` that shapes the screen (output, resizes,
+ * the last zoom/focus/browser frame) is kept at t=0 so the first frame is right; markers such as chapters and
+ * screenshots before `from` are dropped. The result is flattened (see `flattenRecording`).
+ */
+export function cutRecording(rec: Recording, config: ResolvedConfig, range: ClipRange): Recording {
+  const flat = flattenRecording(rec, config);
+  const duration = recordingDuration(flat);
+  const from = Math.max(0, range.from ?? 0);
+  const to = Math.min(duration, range.to ?? duration);
+  if (!(to > from)) throw new Error(`Nothing to keep between ${from}s and ${to}s (the recording is ${duration.toFixed(2)}s long)`);
+
+  const preroll: CastEvent[] = [];
+  let lastZoom: CastEvent | undefined;
+  let lastFocus: CastEvent | undefined;
+  let lastBrowser: CastEvent | undefined;
+  const kept: CastEvent[] = [];
+  for (const e of flat.events) {
+    const [t, type, data] = e;
+    if (t < from - 1e-9) {
+      if (!isState(e)) continue;
+      if (type === "o" || type === "r") preroll.push([0, type, data]);
+      else if (type === "b") lastBrowser = [0, type, data];
+      else if (data.startsWith(MARKER.zoom)) lastZoom = [0, type, data];
+      else lastFocus = [0, type, data];
+      continue;
+    }
+    if (t > to + 1e-9) continue;
+    if (type === "m" && data === MARKER.end) continue;
+    kept.push([round(t - from), type, data]);
+  }
+  const events: CastEvent[] = [...preroll];
+  for (const e of [lastBrowser, lastFocus, lastZoom]) if (e) events.push(e);
+  events.push(...kept, [round(to - from), "m", MARKER.end]);
+  return { ...flat, header: { ...flat.header, duration: round(to - from) }, events };
+}
+
+/** Chapters on the visible timeline; each runs until the next chapter (or the end). */
+export function chapterRanges(rec: Recording, config: ResolvedConfig): ChapterRange[] {
+  const flat = flattenRecording(rec, config);
+  const duration = recordingDuration(flat);
+  const starts = flat.events.filter((e) => e[1] === "m" && e[2].startsWith(MARKER.chapter)).map((e) => ({ title: e[2].slice(MARKER.chapter.length), from: e[0] }));
+  return starts.map((c, i) => ({ ...c, to: starts[i + 1]?.from ?? duration }));
+}
+
+const slug = (s: string): string =>
+  s
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+
+/** File-name friendly chapter label: "02-zoom-in". */
+export function chapterSlug(index: number, title: string): string {
+  return `${String(index + 1).padStart(2, "0")}-${slug(title) || "chapter"}`;
+}
+
+/** Find chapters by title (case/punctuation-insensitive) or 1-based index; throws listing what exists. */
+export function findChapters(ranges: ChapterRange[], names: string[]): ChapterRange[] {
+  if (ranges.length === 0) throw new Error("This recording has no chapters (add `t.chapter(name)` calls to the script)");
+  return names.map((name) => {
+    const want = slug(name);
+    const index = Number(name);
+    const found = ranges.find((r) => slug(r.title) === want) ?? (Number.isInteger(index) && index >= 1 ? ranges[index - 1] : undefined);
+    if (!found) throw new Error(`Unknown chapter "${name}". Chapters: ${ranges.map((r, i) => `${i + 1}. ${r.title}`).join(", ")}`);
+    return found;
+  });
+}
+
+export interface ConcatOptions {
+  /** Still time between parts, seconds. Default 0. */
+  gap?: number;
+}
+
+/**
+ * Join recordings end to end. Each part is flattened; the terminal is reset (`ESC c`) at every seam so a part
+ * starts on a clean screen, and any zoom/focus from the previous part is cleared. Parts must share a grid size.
+ */
+export function concatRecordings(parts: Array<{ rec: Recording; config: ResolvedConfig }>, opts: ConcatOptions = {}): Recording {
+  if (parts.length === 0) throw new Error("concat needs at least one recording");
+  const flats = parts.map(({ rec, config }) => flattenRecording(rec, config));
+  const first = flats[0]!;
+  for (const f of flats) {
+    if (f.header.width !== first.header.width || f.header.height !== first.header.height) {
+      throw new Error(
+        `All recordings must have the same size to be joined: got ${flats.map((x) => `${x.header.width}x${x.header.height}`).join(", ")}. Re-record, or render each separately.`,
+      );
+    }
+  }
+  const gap = Math.max(0, opts.gap ?? 0);
+  const events: CastEvent[] = [];
+  let offset = 0;
+  flats.forEach((flat, i) => {
+    if (i > 0) {
+      events.push([round(offset), "o", "\x1bc"]);
+      events.push([round(offset), "m", `${MARKER.zoom}null`]);
+      if (flat.events.some((e) => e[1] === "b") || flats[i - 1]!.events.some((e) => e[1] === "b")) events.push([round(offset), "m", `${MARKER.focus}terminal`]);
+    }
+    for (const [t, type, data] of flat.events) {
+      if (type === "m" && data === MARKER.end) continue;
+      events.push([round(t + offset), type, data]);
+    }
+    offset += recordingDuration(flat) + (i < flats.length - 1 ? gap : 0);
+  });
+  events.push([round(offset), "m", MARKER.end]);
+  return { header: { ...first.header, duration: round(offset) }, events };
+}
+
+/** Keep only the named chapters, in the order given (non-adjacent chapters are joined). */
+export function selectChapters(rec: Recording, config: ResolvedConfig, names: string[]): Recording {
+  const ranges = findChapters(chapterRanges(rec, config), names);
+  const flat = flattenedConfig(config);
+  const parts = ranges.map((r) => ({ rec: cutRecording(rec, config, r), config: flat }));
+  return parts.length === 1 ? parts[0]!.rec : concatRecordings(parts);
+}
+
+/**
+ * Browser frames (`b` events) are paths relative to the cast they were recorded with. When a cut or joined cast
+ * is written somewhere else, copy the frames next to it (`<name>.browser/`) and point the events there.
+ */
+export async function rebaseBrowserFrames(rec: Recording, sourceCast: string | undefined, targetCast: string, prefix = ""): Promise<Recording> {
+  const frames = rec.events.filter((e) => e[1] === "b");
+  if (frames.length === 0) return rec;
+  const fromDir = sourceCast ? path.dirname(path.resolve(sourceCast)) : process.cwd();
+  const dirName = `${path.basename(targetCast).replace(/\.cast$/, "")}.browser`;
+  const dir = path.join(path.dirname(path.resolve(targetCast)), dirName);
+  await mkdir(dir, { recursive: true });
+  const moved = new Map<string, string>();
+  for (const [, , rel] of frames) {
+    if (moved.has(rel)) continue;
+    const name = `${prefix}${path.basename(rel)}`;
+    await Bun.write(path.join(dir, name), Bun.file(path.join(fromDir, rel)));
+    moved.set(rel, `${dirName}/${name}`);
+  }
+  return { ...rec, events: rec.events.map((e) => (e[1] === "b" ? [e[0], e[1], moved.get(e[2]) ?? e[2]] : e)) };
+}

package/src/export/frames.ts

@@ -36,6 +36,17 @@ export interface GridFrame {
   cursor: { row: number; col: number; visible: boolean };
 }
 
+/** Visible text of a frame: one string per row, trailing spaces and trailing blank rows removed. */
+export function frameText(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;
+}
+
 export interface GridReplay {
   frames: GridFrame[];
   duration: number;
@@ -76,7 +87,13 @@ function toGridCell(cell: CellData, theme: Theme): GridCell {
   return { text, width: cell.width === 2 ? 2 : 1, fg, bg, flags: cell.flags & ~FLAG.reverse };
 }
 
-function snapshot(core: TerminalCore, theme: Theme): { rows: Map<number, GridCell[]>; key: string } {
+interface ScreenSnapshot {
+  rows: Map<number, GridCell[]>;
+  /** Content fingerprint: identical screens share a key, so identical frames are deduplicated. */
+  key: string;
+}
+
+function snapshot(core: TerminalCore, theme: Theme): ScreenSnapshot {
   const rows = new Map<number, GridCell[]>();
   const keyParts: string[] = [];
   const cols = core.getCols();

package/src/export/html.ts

@@ -1,6 +1,6 @@
 import { mkdir } from "node:fs/promises";
 import path from "node:path";
-import { barHeight } from "../renderer/page";
+import { barHeight, embedImage, shadowCss, watermarkCss } from "../renderer/page";
 import { pageAssets } from "../renderer/bundle";
 import { buildTimeline } from "../timeline";
 import type { Recording, ResolvedConfig, Theme } from "../types";
@@ -29,6 +29,8 @@ export async function buildHtml(rec: Recording, config: ResolvedConfig): Promise
   const assets = await pageAssets();
   const { events, duration } = buildTimeline(rec.events, config.playbackSpeed);
   const { theme, font } = config;
+  const wm = config.watermark;
+  const watermark = wm ? `<div id="watermark">${wm.image ? `<img src="${(await embedImage(wm.image)).dataUri}" alt="">` : escapeHtml(wm.text ?? "")}</div>` : "";
   const data = {
     cols: rec.header.width,
     rows: rec.header.height,
@@ -54,7 +56,8 @@ export async function buildHtml(rec: Recording, config: ResolvedConfig): Promise
 <style>
 ${assets.css}
 html, body { margin: 0; background: ${config.marginFill}; min-height: 100vh; display: flex; align-items: center; justify-content: center; }
-#frame { display: inline-block; background: ${theme.background}; border-radius: ${config.borderRadius}px; padding: ${config.padding}px; margin: ${config.margin}px; box-shadow: 0 12px 40px rgba(0,0,0,.35); }
+#frame { position: relative; display: inline-block; background: ${theme.background}; border-radius: ${config.borderRadius}px; padding: ${config.padding}px; margin: ${config.margin}px; box-shadow: ${shadowCss(config) ?? "0 12px 40px rgba(0,0,0,.35)"}; }
+${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; }
@@ -68,6 +71,7 @@ html, body { margin: 0; background: ${config.marginFill}; min-height: 100vh; dis
 <body>
 <div id="frame">
   ${windowBar(config)}
+  ${watermark}
   <div id="term"></div>
   <div id="controls">
     <button id="play" title="Play / pause">▶</button>

package/src/export/svg.ts

@@ -1,5 +1,5 @@
 import { fitFrame } from "../loop";
-import { barHeight } from "../renderer/page";
+import { barHeight, embedImage } from "../renderer/page";
 import type { Recording, ResolvedConfig } from "../types";
 import { FLAG, replayFrames, type GridCell, type GridFrame } from "./frames";
 
@@ -128,6 +128,32 @@ function frameMarkup(frame: GridFrame, config: ResolvedConfig, g: Geometry): str
   return parts.join("");
 }
 
+/** Drop shadow as an SVG filter on the window rect (blur radius ≈ 2 × stdDeviation). */
+function shadowDefs(config: ResolvedConfig): string {
+  const s = config.shadow;
+  if (!s) return "";
+  return `<defs><filter id="shadow" x="-40%" y="-40%" width="180%" height="200%"><feDropShadow dx="${num(s.x)}" dy="${num(s.y)}" stdDeviation="${num(s.blur / 2)}" flood-color="${s.color}" flood-opacity="${num(s.opacity)}"/></filter></defs>`;
+}
+
+async function watermarkMarkup(config: ResolvedConfig, g: Geometry): Promise<string> {
+  const w = config.watermark;
+  if (!w) return "";
+  const m = w.margin;
+  const anchor = w.position === "center" ? "middle" : w.position.endsWith("left") ? "start" : "end";
+  const x = w.position === "center" ? g.width / 2 : w.position.endsWith("left") ? m : g.width - m;
+  if (w.image) {
+    const img = await embedImage(w.image);
+    const h = w.size;
+    const iw = img.height > 0 ? (img.width / img.height) * h : h;
+    const ix = anchor === "start" ? x : anchor === "end" ? x - iw : x - iw / 2;
+    const iy = w.position === "center" ? g.height / 2 - h / 2 : w.position.startsWith("top") ? m : g.height - m - h;
+    return `<image href="${img.dataUri}" x="${num(ix)}" y="${num(iy)}" width="${num(iw)}" height="${num(h)}" opacity="${num(w.opacity)}"/>`;
+  }
+  const y = w.position === "center" ? g.height / 2 : w.position.startsWith("top") ? m + w.size : g.height - m;
+  const baseline = w.position === "center" ? ' dominant-baseline="middle"' : "";
+  return `<text x="${num(x)}" y="${num(y)}" text-anchor="${anchor}"${baseline} font-family="-apple-system, Segoe UI, Helvetica, Arial, sans-serif" font-weight="500" font-size="${num(w.size)}" fill="${w.color}" opacity="${num(w.opacity)}">${esc(w.text ?? "")}</text>`;
+}
+
 export interface SvgResult {
   svg: string;
   frames: number;
@@ -160,13 +186,15 @@ export async function buildSvg(rec: Recording, config: ResolvedConfig): Promise<
 @keyframes tcut{${keyframes.join("")}}
 text{white-space:pre;dominant-baseline:auto}
 </style>
-<rect width="100%" height="100%" fill="${config.marginFill}"/>
-<rect x="${num(g.frameX)}" y="${num(g.frameY)}" width="${num(g.frameW)}" height="${num(g.frameH)}" rx="${config.borderRadius}" fill="${theme.background}"/>
+${config.marginFill === "transparent" ? "" : `<rect width="100%" height="100%" fill="${config.marginFill}"/>`}
+${shadowDefs(config)}
+<rect x="${num(g.frameX)}" y="${num(g.frameY)}" width="${num(g.frameW)}" height="${num(g.frameH)}" rx="${config.borderRadius}" fill="${theme.background}"${config.shadow ? ' filter="url(#shadow)"' : ""}/>
 ${windowBar(config, g)}
 <clipPath id="term"><rect x="${num(g.termX)}" y="${num(g.termY)}" width="${num(g.termW)}" height="${num(g.termH)}"/></clipPath>
 <g clip-path="url(#term)"><g transform="translate(${num(g.termX)} ${num(g.termY)})"><g class="strip" xml:space="preserve">
 ${frames}
 </g></g></g>
+${await watermarkMarkup(config, g)}
 </svg>
 `;
   return { svg, frames: n, duration: total };

package/src/index.ts

@@ -1,6 +1,10 @@
-export { defineVideo, Video, renderCast, isVideo } from "./video";
+export { defineVideo, Video, renderCast, castConfig, isVideo } from "./video";
 export type { RunOptions as VideoRunOptions, RunResult, VideoRecordOptions } from "./video";
-export { renderOutputs } from "./render";
+export { renderOutputs, renderSelection, writeTxt } from "./render";
+export { cutRecording, concatRecordings, selectChapters, chapterRanges, findChapters, flattenRecording, flattenedConfig, rebaseBrowserFrames, recordingDuration } from "./edit";
+export type { ClipRange, ChapterRange, ConcatOptions } from "./edit";
+export { decodePng, encodePng, matte } from "./renderer/png";
+export type { RgbaImage } from "./renderer/png";
 export { recordLive } from "./live";
 export type { LiveOptions } from "./live";
 export { buildSvg } from "./export/svg";

package/src/keylabels.ts

@@ -1,37 +1,37 @@
 import { tokenize } from "./scriptgen";
 
-const NAMED: Record<string, string> = {
-  "\r": "⏎",
-  "\n": "⏎",
-  "\t": "⇥",
-  "\x1b[Z": "⇧⇥",
-  "\x7f": "⌫",
-  "\x1b": "esc",
-  "\x1b[A": "↑",
-  "\x1b[B": "↓",
-  "\x1b[C": "→",
-  "\x1b[D": "←",
-  "\x1bOA": "↑",
-  "\x1bOB": "↓",
-  "\x1bOC": "→",
-  "\x1bOD": "←",
-  "\x1b[1;2A": "⇧↑",
-  "\x1b[1;2B": "⇧↓",
-  "\x1b[1;2C": "⇧→",
-  "\x1b[1;2D": "⇧←",
-  "\x1b[H": "home",
-  "\x1b[F": "end",
-  "\x1b[3~": "del",
-  "\x1b[5~": "pgup",
-  "\x1b[6~": "pgdn",
-};
+const NAMED = new Map<string, string>([
+  ["\r", "⏎"],
+  ["\n", "⏎"],
+  ["\t", "⇥"],
+  ["\x1b[Z", "⇧⇥"],
+  ["\x7f", "⌫"],
+  ["\x1b", "esc"],
+  ["\x1b[A", "↑"],
+  ["\x1b[B", "↓"],
+  ["\x1b[C", "→"],
+  ["\x1b[D", "←"],
+  ["\x1bOA", "↑"],
+  ["\x1bOB", "↓"],
+  ["\x1bOC", "→"],
+  ["\x1bOD", "←"],
+  ["\x1b[1;2A", "⇧↑"],
+  ["\x1b[1;2B", "⇧↓"],
+  ["\x1b[1;2C", "⇧→"],
+  ["\x1b[1;2D", "⇧←"],
+  ["\x1b[H", "home"],
+  ["\x1b[F", "end"],
+  ["\x1b[3~", "del"],
+  ["\x1b[5~", "pgup"],
+  ["\x1b[6~", "pgdn"],
+]);
 
 /** Human-readable labels for a raw input chunk: printable runs stay words, control sequences become symbols. */
 export function keyLabels(input: string): string[] {
   const labels: string[] = [];
   for (const token of tokenize(input)) {
     if (token === " ") { labels.push(" "); continue; }
-    const named = NAMED[token];
+    const named = NAMED.get(token);
     if (named) {
       labels.push(named);
     } else if (token.length === 1 && token.charCodeAt(0) < 32) {
@@ -39,7 +39,8 @@ export function keyLabels(input: string): string[] {
     } else if (token.length === 2 && token[0] === "\x1b") {
       labels.push(`⌥${token[1]}`);
     } else if (token.startsWith("\x1b[<")) {
-      labels.push(/M$/.test(token) && /^\x1b\[<6[45]/.test(token) ? "wheel" : "mouse");
+      const wheel = token.endsWith("M") && (token.startsWith("\x1b[<64") || token.startsWith("\x1b[<65"));
+      labels.push(wheel ? "wheel" : "mouse");
     } else if (token.startsWith("\x1b")) {
       labels.push("esc…");
     } else {

package/src/keys.ts

@@ -2,7 +2,7 @@ import type { KeyName } from "./types";
 
 const ESC = "\x1b";
 
-const keySequences: Record<KeyName, string> = {
+const keySequences = {
   enter: "\r",
   tab: "\t",
   backspace: "\x7f",
@@ -30,7 +30,7 @@ const keySequences: Record<KeyName, string> = {
   f10: `${ESC}[21~`,
   f11: `${ESC}[23~`,
   f12: `${ESC}[24~`,
-};
+} satisfies Record<KeyName, string>;
 
 export function keySequence(name: KeyName): string {
   const seq = keySequences[name];
@@ -51,27 +51,27 @@ 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: " ",
-};
+const shiftedNamed = new Map<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];
+  const named = shiftedNamed.get(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.`);
+  throw new Error(`Cannot send Shift+${key}. Known: ${[...shiftedNamed.keys()].join(", ")}, or a single character.`);
 }
 
 /** SGR mouse wheel event (button 64 = up, 65 = down) at a 1-based cell position. */

package/src/live.ts

@@ -3,6 +3,16 @@ import { MARKER } from "./cast";
 import { shellSetup } from "./recorder";
 import type { CastEvent, Recording, ResolvedConfig } from "./types";
 
+/** What live recording needs from a keystroke source: `process.stdin`, or any readable stream (a PassThrough in tests). */
+export interface LiveStdin {
+  isTTY?: boolean;
+  setRawMode?(mode: boolean): unknown;
+  resume(): unknown;
+  pause(): unknown;
+  on(event: "data", listener: (chunk: Buffer | string) => void): unknown;
+  off(event: "data", listener: (chunk: Buffer | string) => void): unknown;
+}
+
 export interface LiveOptions {
   /** Run this command instead of the configured clean shell. */
   command?: string[];
@@ -12,7 +22,7 @@ export interface LiveOptions {
   /** Where to mirror the session (default: this process's stdout). */
   stdout?: { write(data: Uint8Array | string): unknown };
   /** Keystroke source (default: this process's stdin, switched to raw mode when it is a TTY). */
-  stdin?: NodeJS.ReadStream | null;
+  stdin?: LiveStdin | null;
   log?: (message: string) => void;
 }
 
@@ -40,7 +50,7 @@ export async function recordLive(config: ResolvedConfig, opts: LiveOptions = {})
 
   const browser = config.browser ? startBrowserCapture({ ...config, cols, rows }, stamp, log) : null;
   const setup = opts.command ? { cmd: opts.command, env: {} } : shellSetup(config);
-  const env: Record<string, string> = {
+  const env = {
     ...process.env,
     TERM: "xterm-256color",
     COLORTERM: "truecolor",
@@ -74,11 +84,11 @@ export async function recordLive(config: ResolvedConfig, opts: LiveOptions = {})
   const terminal = proc.terminal;
   if (!terminal) throw new Error("Bun.spawn did not return a terminal. Is this Bun >= 1.4?");
 
-  const isTTY = Boolean(stdin && (stdin as NodeJS.ReadStream).isTTY);
+  const isTTY = Boolean(stdin?.isTTY);
   const onData = (chunk: Buffer | string): void => {
     if (exited || terminal.closed) return;
     terminal.write(chunk);
-    push("i", typeof chunk === "string" ? chunk : chunk.toString("utf8"));
+    push("i", chunk instanceof Uint8Array ? chunk.toString("utf8") : chunk);
   };
   const onResize = (): void => {
     const c = process.stdout.columns ?? cols;
@@ -89,7 +99,7 @@ export async function recordLive(config: ResolvedConfig, opts: LiveOptions = {})
   };
 
   if (stdin) {
-    if (isTTY) stdin.setRawMode(true);
+    if (isTTY) stdin.setRawMode?.(true);
     stdin.resume();
     stdin.on("data", onData);
   }
@@ -101,10 +111,11 @@ export async function recordLive(config: ResolvedConfig, opts: LiveOptions = {})
     push("m", MARKER.end);
   } finally {
     await browser?.stop();
-    (process as unknown as { off(event: string, fn: () => void): void }).off("SIGWINCH", onResize); // newer @types/bun drop the signal overload on off()
+    const emitter: NodeJS.EventEmitter = process; // @types/bun's process.off() lacks the signal overload; the generic emitter has it
+    emitter.off("SIGWINCH", onResize);
     if (stdin) {
       stdin.off("data", onData);
-      if (isTTY) stdin.setRawMode(false);
+      if (isTTY) stdin.setRawMode?.(false);
       stdin.pause();
     }
     try {

package/src/loop.ts

@@ -1,14 +1,9 @@
 /** 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);
-  }
+  const m = /^\s*(-?\d+(?:\.\d+)?)\s*(%?)\s*$/.exec(String(value));
+  if (!m) throw new Error(`Invalid loopOffset "${value}" (use a frame count or a percentage like "50%")`);
+  const frames = m[2] ? Math.round((Number(m[1]) / 100) * total) : Math.round(Number(m[1]));
   return ((frames % total) + total) % total;
 }
 
@@ -18,6 +13,16 @@ export function rotateFrames<T>(frames: T[], offset: number): T[] {
   return [...frames.slice(offset), ...frames.slice(0, offset)];
 }
 
+/** Where the terminal grid sits inside the frame, and the final (even-sized) video dimensions. */
+export interface FrameFit {
+  frameW: number;
+  frameH: number;
+  padX: number;
+  padY: number;
+  width: number;
+  height: number;
+}
+
 /** 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;
@@ -27,7 +32,7 @@ export function fitFrame(opts: {
   bar: number;
   width?: number;
   height?: number;
-}): { frameW: number; frameH: number; padX: number; padY: number; width: number; height: number } {
+}): FrameFit {
   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;

package/src/presets.ts

@@ -3,7 +3,7 @@ import type { VideoConfig } from "./types";
 export type PresetName = "readme" | "x" | "youtube" | "square";
 
 /** Opinionated bundles applied *under* whatever the config sets explicitly. */
-export const presets: Record<PresetName, Partial<VideoConfig>> = {
+export const presets = {
   // Small, loops well, reads at README width.
   readme: { cols: 80, rows: 20, fps: 30, font: { size: 18 }, padding: 20, margin: 0, borderRadius: 8, windowBar: "none", typingSpeed: "40ms" },
   // 16:9 at the size X/Twitter serves without downscaling.
@@ -12,7 +12,7 @@ export const presets: Record<PresetName, Partial<VideoConfig>> = {
   youtube: { width: 1920, height: 1080, fps: 60, font: { size: 26 }, padding: 32, margin: 40, borderRadius: 14, windowBar: "colorful", typingSpeed: "35ms", typingJitter: 0.3 },
   // 1:1 for feeds.
   square: { width: 1080, height: 1080, fps: 30, font: { size: 22 }, padding: 24, margin: 32, borderRadius: 14, windowBar: "colorful", typingSpeed: "35ms" },
-};
+} satisfies Record<PresetName, Partial<VideoConfig>>;
 
 export const presetNames = Object.keys(presets) as PresetName[];