termcut 0.7.2 → 0.7.3

package/package.json

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

package/src/browser.ts

@@ -48,10 +48,18 @@ export function startBrowserCapture(config: ResolvedConfig, stamp: () => number,
   // Sampling starts once a page has loaded: headless Chrome never resolves a screenshot of the initial blank
   // view, and a hung screenshot blocks every later command on that view.
   let loaded = false;
-  /** Extra time allowed while the browser has never answered: a cold Chrome on a CI runner can take ~20 s to come up. */
-  const STARTUP_GRACE = 20_000;
+  /** Extra time allowed while the browser has never answered: a cold Chrome on a fresh Windows runner can take 20–40 s. */
+  const STARTUP_GRACE = 45_000;
   const startedAt = performance.now();
-  const startupDeadline = (deadline: number): number => (loaded ? deadline : Math.max(deadline, startedAt + STARTUP_GRACE));
+  let startupNoted = false;
+  const startupDeadline = (deadline: number): number => {
+    if (loaded) return deadline;
+    if (!startupNoted && performance.now() > startedAt + 5000) {
+      startupNoted = true;
+      log("waiting for the browser to start…");
+    }
+    return Math.max(deadline, startedAt + STARTUP_GRACE);
+  };
   // A view runs one evaluate() at a time; goto's probes, waitFor and the script's own evaluate calls take turns.
   let chain: Promise<unknown> = Promise.resolve();
   const serial = <T,>(fn: () => Promise<T>): Promise<T> => {
@@ -89,6 +97,11 @@ export function startBrowserCapture(config: ResolvedConfig, stamp: () => number,
     })();
     return sampling;
   };
+  /** A sample taken after this moment: waits out any in-flight screenshot (seconds on a cold Chrome), then takes a fresh one. */
+  const sampleNow = async (): Promise<void> => {
+    if (sampling) await sampling;
+    await sampleOnce();
+  };
   const sampler = (async () => {
     while (running) {
       await sampleOnce();
@@ -153,7 +166,7 @@ export function startBrowserCapture(config: ResolvedConfig, stamp: () => number,
         const text = String((await evaluate("document.body ? document.body.innerText : ''", 5000, "waitFor").catch(() => "")) ?? "");
         if (regex.test(text)) {
           loaded = true; // a page that answers is a page worth sampling, even if navigate() has not settled yet
-          await sampleOnce(); // the frame the script waited for, captured the moment it appeared
+          await sampleNow(); // the frame the script waited for, captured the moment it appeared
           return;
         }
         if (performance.now() > startupDeadline(deadline)) throw new WaitTimeoutError(`${regex} in the browser page`, timeout, text.slice(0, 2000));
@@ -178,7 +191,7 @@ export function startBrowserCapture(config: ResolvedConfig, stamp: () => number,
       if (!loaded && bcfg.url) await evaluate("document.readyState", 2000, "probe").catch(() => undefined); // marks loaded if the page answers
       running = false;
       await sampler;
-      await sampleOnce(); // final state of the page
+      await sampleNow(); // final state of the page
       try {
         view.close();
       } catch {

package/src/cli.ts

@@ -15,7 +15,7 @@ import { renderOutputs } from "./render";
 import { generateScript } from "./scriptgen";
 import { runScriptTests, type TestSummary } from "./testing";
 import { findThemes, themeNames } from "./themes";
-import type { BrowserConfig, ClipSelection, CoreName, ThemeName, VideoConfig, WindowBar } from "./types";
+import type { BrowserConfig, ClipSelection, CoreName, Recording, ResolvedConfig, 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
@@ -524,13 +524,13 @@ async function main(): Promise<void> {
       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> }> = [];
+      const parts: Array<{ rec: Recording; config: ResolvedConfig }> = [];
       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>>;
+      let out: Recording;
       if (joining) {
         out = concatRecordings(parts, { gap: seconds("gap") ?? 0 });
       } else {

package/src/config.ts

@@ -114,6 +114,7 @@ export function resolveConfig(input: VideoConfig): ResolvedConfig {
     quantize: config.quantize ?? false,
     core: config.core ?? "ghostty",
     cache: config.cache ?? true,
+    requires: config.requires ?? [],
     font,
     theme,
     cursor: {

package/src/errors.ts

@@ -7,6 +7,16 @@ export class WaitTimeoutError extends Error {
   }
 }
 
+/** A program named in `requires` is not on the PATH — raised before the shell is even started. */
+export class MissingRequirementError extends Error {
+  constructor(readonly missing: string[]) {
+    super(
+      `${missing.length === 1 ? `\`${missing[0]}\` is` : `${missing.map((m) => `\`${m}\``).join(", ")} are`} not on the PATH. Install ${missing.length === 1 ? "it" : "them"}, or remove ${missing.length === 1 ? "it" : "them"} from \`requires\`.`,
+    );
+    this.name = "MissingRequirementError";
+  }
+}
+
 export class ExpectationError extends Error {
   constructor(what: string, screen: string) {
     super(`Expected ${what} to match.\n\n--- screen ---\n${screen}\n--------------`);

package/src/index.ts

@@ -26,5 +26,5 @@ export type { DiffOptions, DiffResult } from "./diff";
 export { keyLabels, keyChips } from "./keylabels";
 export { startBrowserCapture } from "./browser";
 export { resolveConfig } from "./config";
-export { WaitTimeoutError, ExpectationError } from "./recorder";
+export { WaitTimeoutError, ExpectationError, MissingRequirementError } from "./recorder";
 export type * from "./types";

package/src/recorder.ts

@@ -2,7 +2,7 @@ import { MarkdownRenderer } from "@wterm/markdown";
 import { startBrowserCapture, type BrowserCapture } from "./browser";
 import { MARKER } from "./cast";
 import { toMs } from "./duration";
-import { ExpectationError, WaitTimeoutError } from "./errors";
+import { ExpectationError, MissingRequirementError, WaitTimeoutError } from "./errors";
 import { altSequence, ctrlSequence, keySequence, shiftSequence, wheelSequence } from "./keys";
 import { Screen } from "./screen";
 import type {
@@ -20,7 +20,7 @@ import type {
   WaitOptions,
 } from "./types";
 
-export { WaitTimeoutError, ExpectationError } from "./errors";
+export { WaitTimeoutError, ExpectationError, MissingRequirementError } from "./errors";
 
 /** Deterministic PRNG (mulberry32) so typing jitter is reproducible. */
 function mulberry32(seed: number): () => number {
@@ -103,6 +103,8 @@ export function defaultLang(): string {
 /** Drives a Bun.Terminal PTY according to a script and produces an asciicast recording. */
 export async function record(config: ResolvedConfig, script: Script, opts: RecordOptions = {}): Promise<Recording> {
   const log = opts.log ?? (() => {});
+  const missing = config.requires.filter((name) => Bun.which(name) === null);
+  if (missing.length > 0) throw new MissingRequirementError(missing);
   const events: CastEvent[] = [];
   const screen = await Screen.create(config.cols, config.rows, { core: config.core });
   const fast = opts.fast === true;

package/src/renderer/png.ts

@@ -1,7 +1,7 @@
 // A minimal PNG codec for the renderer. Bun.WebView screenshots come in as opaque PNGs and Bun.Image has no raw
 // pixel access, so transparent output needs its own decode → matte → encode step. 8-bit RGB/RGBA, non-interlaced.
-// node:zlib rather than Bun.inflateSync/deflateSync: PNG needs zlib-framed streams and Bun's defaults are raw deflate.
-import { deflateSync, inflateSync } from "node:zlib";
+// PNG streams are zlib-framed; Bun's inflateSync reads that with windowBits 15, and deflateSync's raw output gets the
+// two-byte header and Adler-32 trailer added here (Bun only — no node:zlib).
 
 /** Straight (non-premultiplied) RGBA pixels, row-major. */
 export interface RgbaImage {
@@ -16,8 +16,31 @@ const SIGNATURE = [137, 80, 78, 71, 13, 10, 26, 10];
 
 const readU32 = (b: Uint8Array, o: number): number => ((b[o]! << 24) | (b[o + 1]! << 16) | (b[o + 2]! << 8) | b[o + 3]!) >>> 0;
 
-function concat(parts: Uint8Array[]): Uint8Array {
-  const out = new Uint8Array(parts.reduce((n, p) => n + p.length, 0));
+function adler32(bytes: Uint8Array): number {
+  let a = 1;
+  let b = 0;
+  for (let i = 0; i < bytes.length; i++) {
+    a = (a + bytes[i]!) % 65521;
+    b = (b + a) % 65521;
+  }
+  return ((b << 16) | a) >>> 0;
+}
+
+/** Raw DEFLATE from Bun.deflateSync wrapped as a zlib stream (RFC 1950): CMF/FLG header + data + Adler-32. */
+function zlibDeflate(raw: Uint8Array<ArrayBuffer>, level: 1 | 6 = 1): Uint8Array {
+  const body = Bun.deflateSync(raw, { level });
+  const out = new Uint8Array(2 + body.length + 4);
+  out[0] = 0x78;
+  out[1] = level === 1 ? 0x01 : 0x9c;
+  out.set(body, 2);
+  new DataView(out.buffer).setUint32(2 + body.length, adler32(raw));
+  return out;
+}
+
+const zlibInflate = (data: Uint8Array<ArrayBuffer>): Uint8Array => Bun.inflateSync(data, { windowBits: 15 });
+
+function concat(parts: Uint8Array[]): Uint8Array<ArrayBuffer> {
+  const out = new Uint8Array(new ArrayBuffer(parts.reduce((n, p) => n + p.length, 0)));
   let o = 0;
   for (const p of parts) {
     out.set(p, o);
@@ -83,7 +106,7 @@ export function decodePng(png: Uint8Array): RgbaImage {
   }
   const bpp = colorType === 6 ? 4 : 3;
   const stride = width * bpp;
-  const raw = inflateSync(concat(idat));
+  const raw = zlibInflate(concat(idat));
   const out = new Uint8Array(width * height * 4);
   let prev = new Uint8Array(stride);
   let row = new Uint8Array(stride);
@@ -133,7 +156,7 @@ function chunk(type: string, data: Uint8Array): Uint8Array {
 /** Encode straight RGBA as an 8-bit PNG (filter 0; speed matters more than size — ffmpeg re-encodes anyway). */
 export function encodePng(img: RgbaImage): Uint8Array {
   const stride = img.width * 4;
-  const raw = new Uint8Array((stride + 1) * img.height);
+  const raw = new Uint8Array(new ArrayBuffer((stride + 1) * img.height));
   for (let y = 0; y < img.height; y++) {
     raw[y * (stride + 1)] = 0;
     raw.set(img.data.subarray(y * stride, (y + 1) * stride), y * (stride + 1) + 1);
@@ -144,7 +167,7 @@ export function encodePng(img: RgbaImage): Uint8Array {
   v.setUint32(4, img.height);
   ihdr[8] = 8; // bit depth
   ihdr[9] = 6; // RGBA
-  return concat([new Uint8Array(SIGNATURE), chunk("IHDR", ihdr), chunk("IDAT", deflateSync(raw, { level: 1 })), chunk("IEND", new Uint8Array(0))]);
+  return concat([new Uint8Array(SIGNATURE), chunk("IHDR", ihdr), chunk("IDAT", zlibDeflate(raw)), chunk("IEND", new Uint8Array(0))]);
 }
 
 export function parseHex(color: string): Rgb {

package/src/types.ts

@@ -205,6 +205,8 @@ export interface VideoConfig {
   core?: CoreName;
   /** Reuse the existing cast when the script and record config are unchanged. Default true. */
   cache?: boolean;
+  /** Programs the script needs on the PATH (`["bun", "eza"]`). Checked before the shell starts; missing ones fail fast with a clear message. */
+  requires?: string[];
 
   font?: FontConfig;
   theme?: ThemeName | Theme;
@@ -257,6 +259,7 @@ export interface ResolvedConfig {
   quantize: boolean;
   core: CoreName;
   cache: boolean;
+  requires: string[];
   font: Required<FontConfig>;
   theme: Theme;
   cursor: Required<CursorConfig>;