npm - termcut - Versions diffs - 0.7.0 → 0.7.2 - Mend

termcut 0.7.0 → 0.7.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (10) hide show

package/README.md CHANGED Viewed

@@ -10,7 +10,7 @@ Turn a terminal session into a video. Record it live or script it in TypeScript;
 bun add -g termcut     # Bun ≥ 1.4 · installs the `tcut` command
 ```
-Standalone binaries: [Releases](https://github.com/AmanVarshney01/tcut/releases). MP4/GIF need `ffmpeg`; SVG/HTML don't.
+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.
 ## Use

package/package.json CHANGED Viewed

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

package/scripts/probe-webview.ts ADDED Viewed

@@ -0,0 +1,39 @@
+// Diagnostic: how does Bun.WebView behave on this machine? Prints backend, navigation, evaluate and screenshot
+// timings for a local page. `bun scripts/probe-webview.ts` (TCUT_DEBUG_CHROME=1 shows Chrome's stderr).
+import { createWebView, webViewBackend } from "../src/renderer/view";
+const t0 = performance.now();
+const at = () => `${((performance.now() - t0) / 1000).toFixed(3)}s`;
+const log = (m: string) => console.log(`${at()} ${m}`);
+const timed = async <T>(label: string, p: Promise<T>, ms = 8000): Promise<T | undefined> => {
+  try {
+    const v = await Promise.race([p, Bun.sleep(ms).then(() => Promise.reject(new Error(`timeout ${ms}ms`)))]);
+    log(`${label}: ok ${JSON.stringify(v)?.slice(0, 80) ?? ""}`);
+    return v;
+  } catch (cause) {
+    log(`${label}: FAILED ${cause instanceof Error ? cause.message : String(cause)}`);
+    return undefined;
+  }
+};
+const server = Bun.serve({ port: 0, hostname: "127.0.0.1", fetch: () => new Response("<html><body><h1 id=t>first</h1><button onclick=\"t.textContent='clicked'\">go</button></body></html>", { headers: { "content-type": "text/html" } }) });
+const url = `http://127.0.0.1:${server.port}/`;
+log(`platform ${process.platform} backend ${JSON.stringify(webViewBackend())}`);
+const view = createWebView({ width: 320, height: 240 });
+log(`view created; url=${JSON.stringify(view.url)} loading=${view.loading}`);
+const nav = view.navigate(url).then(() => "ok", (cause: unknown) => `rejected: ${cause instanceof Error ? cause.message : String(cause)}`);
+for (let i = 0; i < 6; i++) {
+  await Bun.sleep(250);
+  log(`tick ${i}: url=${JSON.stringify(view.url)} loading=${view.loading}`);
+}
+await timed("navigate", nav, 5000);
+await timed("evaluate readyState", view.evaluate("document.readyState"));
+await timed("evaluate innerText", view.evaluate("document.body ? document.body.innerText : ''"));
+const shot = await timed("screenshot", view.screenshot({ encoding: "buffer" }));
+log(`screenshot bytes: ${shot ? (shot as Uint8Array).length : "none"}`);
+await timed("click", view.click("button"), 5000);
+await timed("evaluate after click", view.evaluate("document.body.innerText"));
+await timed("screenshot 2", view.screenshot({ encoding: "buffer" }));
+log(`final url=${JSON.stringify(view.url)} loading=${view.loading}`);
+view.close();
+server.stop(true);

package/src/browser.ts CHANGED Viewed

@@ -1,4 +1,5 @@
 import { WINDOW_BAR_HEIGHT, estimateCell } from "./config";
+import { createWebView } from "./renderer/view";
 import { toMs } from "./duration";
 import { WaitTimeoutError } from "./errors";
 import type { BrowserFrame, BrowserSession, ResolvedConfig } from "./types";
@@ -25,7 +26,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 (!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.
@@ -35,7 +36,7 @@ export function startBrowserCapture(config: ResolvedConfig, stamp: () => number,
   const stacked = bcfg.position === "top" || bcfg.position === "bottom";
   const paneW = stacked ? termFrameW : bcfg.width;
   const paneH = bcfg.height || (stacked || bcfg.position === "overlay" ? 480 : termFrameH);
-  const view = new Bun.WebView({ width: paneW, height: paneH });
+  const view = createWebView({ width: paneW, height: paneH });
   const frames: BrowserFrame[] = [];
   const within = <T,>(promise: Promise<T>, ms: number, label: string): Promise<T> =>
@@ -44,8 +45,35 @@ export function startBrowserCapture(config: ResolvedConfig, stamp: () => number,
   let currentUrl = bcfg.url ?? "about:blank";
   let lastHash = "";
   let running = true;
-  const sampler = (async () => {
-    while (running) {
+  // 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;
+  const startedAt = performance.now();
+  const startupDeadline = (deadline: number): number => (loaded ? deadline : 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> => {
+    const next = chain.then(fn, fn);
+    chain = next.then(
+      () => undefined,
+      () => undefined,
+    );
+    return next;
+  };
+  // A page that answers an evaluate is a page worth sampling (view.loading is not reliable on every backend).
+  const evaluate = (js: string, ms: number, label: string): Promise<unknown> =>
+    serial(async () => {
+      const result = await within(view.evaluate(js), ms, label);
+      loaded = true;
+      return result;
+    });
+  // One screenshot at a time: the periodic sampler and the event-driven samples (after waitFor, at stop) share it.
+  let sampling: Promise<void> | null = null;
+  const sampleOnce = (): Promise<void> => {
+    if (!loaded) return Promise.resolve();
+    sampling ??= (async () => {
       try {
         const png = (await within(view.screenshot({ encoding: "buffer" }), 5000, "screenshot")) as Uint8Array;
         const hash = Bun.hash(png).toString(16);
@@ -55,8 +83,16 @@ export function startBrowserCapture(config: ResolvedConfig, stamp: () => number,
         }
       } catch {
         /* view busy or closed */
+      } finally {
+        sampling = null;
       }
-      await Bun.sleep(1000 / bcfg.fps);
+    })();
+    return sampling;
+  };
+  const sampler = (async () => {
+    while (running) {
+      await sampleOnce();
+      await Bun.sleep(loaded ? 1000 / bcfg.fps : 50);
     }
   })();
@@ -83,17 +119,21 @@ export function startBrowserCapture(config: ResolvedConfig, stamp: () => number,
       const outcome = await Promise.race([navigation, Bun.sleep(750).then(() => "tick" as const)]);
       if (outcome === "ok") {
         currentUrl = url;
+        loaded = true;
         return;
       }
       if (outcome === "failed") navigation = null;
       if (!running) return;
-      const state = await within(view.evaluate("document.readyState"), 3000, "goto").catch(() => "");
-      if (state === "complete" && (view.url ?? "").replace(/\/$/, "").startsWith(target)) {
+      // No evaluate() here: the view's own loading flag and URL say whether the page arrived (some backends keep
+      // the navigate() promise pending long after the page is up, and may leave view.url empty).
+      const href = (view.url ?? "").replace(/\/$/, "");
+      if (outcome === "tick" && (href.startsWith(target) || (!view.loading && href === ""))) {
         currentUrl = url;
+        loaded = true;
         return;
       }
-      if (performance.now() > deadline) {
-        throw new WaitTimeoutError(`browser.goto(${url})`, config.waitTimeout, `current url: ${view.url ?? "(none)"}, readyState: ${state || "unknown"}`);
+      if (performance.now() > startupDeadline(deadline)) {
+        throw new WaitTimeoutError(`browser.goto(${url})`, config.waitTimeout, `current url: ${view.url ?? "(none)"}, loading: ${view.loading}`);
       }
       await Bun.sleep(250);
     }
@@ -110,18 +150,35 @@ export function startBrowserCapture(config: ResolvedConfig, stamp: () => number,
       const timeout = toMs(waitOpts.timeout, config.waitTimeout);
       const deadline = performance.now() + timeout;
       for (;;) {
-        const text = String((await within(view.evaluate("document.body ? document.body.innerText : ''"), 5000, "waitFor").catch(() => "")) ?? "");
-        if (regex.test(text)) return;
-        if (performance.now() > deadline) throw new WaitTimeoutError(`${regex} in the browser page`, timeout, text.slice(0, 2000));
+        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
+          return;
+        }
+        if (performance.now() > startupDeadline(deadline)) throw new WaitTimeoutError(`${regex} in the browser page`, timeout, text.slice(0, 2000));
         await Bun.sleep(150);
       }
     },
-    click: (selector) => within(view.click(selector), 10000, "click"),
+    /** Real input emulation first; if the browser's actionability checks stall, a DOM click still drives the page. */
+    click: async (selector) => {
+      loaded = true;
+      try {
+        await within(view.click(selector), 3000, "click");
+      } catch {
+        const hit = await evaluate(`(() => { const el = document.querySelector(${JSON.stringify(selector)}); if (!el) return false; el.click(); return true; })()`, 5000, "click");
+        if (hit !== true) throw new Error(`browser.click: no element matches ${selector}`);
+      }
+    },
     reload: () => within(view.reload(), 30000, "reload").catch((err) => (/pending/i.test(String(err)) ? undefined : Promise.reject(err))),
-    evaluate: (js) => within(view.evaluate(js), 10000, "evaluate"),
+    evaluate: (js) => evaluate(js, 10000, "evaluate"),
     async stop() {
+      // A session shorter than the browser's start-up (cold Chrome on CI) should still show the page once.
+      if (frames.length === 0 && initialLoad) await Promise.race([initialLoad, Bun.sleep(Math.max(0, startupDeadline(0) - performance.now()))]);
+      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
       try {
         view.close();
       } catch {
@@ -130,6 +187,6 @@ export function startBrowserCapture(config: ResolvedConfig, stamp: () => number,
     },
   };
-  if (bcfg.url) void goto(bcfg.url).catch((err) => log(String(err)));
+  const initialLoad = bcfg.url ? goto(bcfg.url).catch((err) => log(String(err))) : null;
   return capture;
 }

package/src/recorder.ts CHANGED Viewed

@@ -78,6 +78,28 @@ export function shellSetup(config: ResolvedConfig): ShellSetup {
   }
 }
+let cachedLang: string | null = null;
+/**
+ * A UTF-8 locale the shell can actually switch to. A LANG naming a locale that is not installed (en_US.UTF-8 on a
+ * minimal Debian, say) silently drops bash into the C locale, where readline mangles multi-byte input such as emoji.
+ */
+export function defaultLang(): string {
+  if (cachedLang !== null) return cachedLang;
+  const current = process.env.LANG ?? "";
+  const available = new Set<string>();
+  try {
+    const proc = Bun.spawnSync(["locale", "-a"], { stdout: "pipe", stderr: "ignore" });
+    for (const line of proc.stdout.toString().split("\n")) available.add(line.trim().toLowerCase().replace("utf8", "utf-8"));
+  } catch {
+    /* no `locale` binary: keep the first candidate */
+  }
+  const has = (name: string) => available.size === 0 || available.has(name.toLowerCase());
+  const candidates = [current, "C.UTF-8", "en_US.UTF-8"].filter((c) => /utf-?8/i.test(c));
+  cachedLang = candidates.find(has) ?? candidates[candidates.length - 1] ?? "C.UTF-8";
+  return cachedLang;
+}
 /** 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 ?? (() => {});
@@ -111,7 +133,7 @@ export async function record(config: ResolvedConfig, script: Script, opts: Recor
     ...inheritedEnv,
     TERM: "xterm-256color",
     COLORTERM: "truecolor",
-    LANG: process.env.LANG ?? "en_US.UTF-8",
+    LANG: defaultLang(),
     ...setup.env,
     ...config.env,
   };

package/src/renderer/bundle.ts CHANGED Viewed

@@ -43,8 +43,8 @@ async function embeddedAssets(): Promise<PageAssets | null> {
   }
 }
-/** True inside a `bun build --compile` binary, where sources live on the virtual /$bunfs filesystem. */
-const isCompiled = import.meta.dir.startsWith("/$bunfs");
+/** True inside a `bun build --compile` binary (sources then live on a virtual filesystem: /$bunfs, or B:\~BUN on Windows). */
+const isCompiled = Bun.isStandaloneExecutable;
 /**
  * Prebuilt assets in the compiled binary; otherwise built at runtime with Bun.build so edits to the page entries

package/src/renderer/view.ts ADDED Viewed

@@ -0,0 +1,41 @@
+// One place that knows how to open a headless Bun.WebView on every platform.
+// macOS uses the system WebKit; everywhere else Bun drives Chrome/Chromium over the DevTools protocol.
+export interface ViewSize {
+  width: number;
+  height: number;
+}
+/** Chrome flags that make headless rendering work in containers and CI without changing what is drawn. */
+export function chromeArgs(): string[] {
+  const args = ["--force-device-scale-factor=1", "--hide-scrollbars", "--disable-dev-shm-usage"];
+  // Chrome refuses to start its sandbox as root (Docker, most CI runners); unprivileged users keep it.
+  if (process.getuid?.() === 0) args.push("--no-sandbox");
+  return args;
+}
+/** Which backend to use: WebKit on macOS unless TCUT_WEBVIEW=chrome, Chrome elsewhere. */
+export function webViewBackend(): Bun.WebView.Backend {
+  const forced = process.env.TCUT_WEBVIEW;
+  if (process.platform === "darwin" && forced !== "chrome") return "webkit";
+  return {
+    type: "chrome",
+    url: false, // always spawn our own headless Chrome; never attach to a user's running browser
+    argv: chromeArgs(),
+    stderr: process.env.TCUT_DEBUG_CHROME ? "inherit" : "ignore",
+    ...(process.env.BUN_CHROME_PATH && { path: process.env.BUN_CHROME_PATH }),
+  };
+}
+export function createWebView(size: ViewSize): Bun.WebView {
+  if (!Bun.WebView) throw new Error("Bun.WebView is not available in this Bun version. tcut needs Bun >= 1.4.");
+  try {
+    return new Bun.WebView({ ...size, backend: webViewBackend() });
+  } catch (cause) {
+    const hint =
+      process.platform === "darwin"
+        ? ""
+        : " Rendering pixels on Linux/Windows needs Chrome or Chromium on the PATH (or BUN_CHROME_PATH=/path/to/chrome); SVG, HTML and TXT output need no browser.";
+    throw new Error(`Could not start the headless browser: ${cause instanceof Error ? cause.message : String(cause)}.${hint}`, { cause });
+  }
+}

package/src/renderer/webview.ts CHANGED Viewed

@@ -10,6 +10,7 @@ import { createSinks, type Chapter } from "./encoder";
 import { chipBuilder } from "../keylabels";
 import { BROWSER_GAP, barHeight, opaqueFill, renderHtml, themeOsc } from "./page";
 import { decodePng, encodePng, luminance, matte, parseHex } from "./png";
+import { createWebView } from "./view";
 export interface RenderResult {
   outputs: string[];
@@ -60,10 +61,6 @@ export async function render(
   config: ResolvedConfig,
   onProgress?: (p: RenderProgress) => void,
 ): Promise<RenderResult> {
-  if (!Bun.WebView) {
-    throw new Error("Bun.WebView is not available in this Bun version. tcut needs Bun >= 1.4.");
-  }
   const assets = await pageAssets();
   const html = renderHtml(config);
   const osc = themeOsc(config.theme);
@@ -121,7 +118,7 @@ export async function render(
   const rgbA = parseHex(fillA);
   const rgbB = parseHex(fillB);
-  const view = new Bun.WebView({ width: 800, height: 600 });
+  const view = createWebView({ width: 800, height: 600 });
   try {
     await view.navigate(`http://127.0.0.1:${server.port}/`);
     for (let i = 0; i < 100; i++) {

package/src/scriptgen.ts CHANGED Viewed

@@ -1,4 +1,5 @@
 import path from "node:path";
+import { keySequence } from "./keys";
 import type { Recording } from "./types";
 export interface ScriptGenOptions {
@@ -20,7 +21,9 @@ type Op =
   | { kind: "key"; name: string; times: number }
   | { kind: "ctrl"; letter: string; times: number }
   | { kind: "alt"; key: string; times: number }
-  | { kind: "raw"; data: string }
+  | { kind: "fkey"; name: string; times: number }
+  | { kind: "shift"; key: string; times: number }
+  | { kind: "raw"; data: string; comment?: string }
   | { kind: "sleep"; ms: number };
 const NAMED = new Map<string, string>([
@@ -46,6 +49,35 @@ const NAMED = new Map<string, string>([
   ["\x1b[6~", "pageDown"],
 ]);
+/** F-keys by the bytes a terminal sends (`ESC O P` … `ESC [24~`), so they replay as `t.key("f5")`: one write, never ESC + key. */
+const FKEYS = new Map(Array.from({ length: 12 }, (_, i) => [keySequence(`f${i + 1}` as `f${1}`), `f${i + 1}`] as const));
+const MODIFIER_NAMES = new Map([
+  ["2", "shift"],
+  ["3", "alt"],
+  ["5", "ctrl"],
+  ["6", "ctrl+shift"],
+  ["7", "ctrl+alt"],
+]);
+const MODIFIED_KEYS = new Map([
+  ["A", "up"],
+  ["B", "down"],
+  ["C", "right"],
+  ["D", "left"],
+  ["H", "home"],
+  ["F", "end"],
+]);
+/** `ESC [1;3D` → { modifier: "alt", key: "left" } (xterm modifier encoding), or null. */
+function modifiedKey(token: string): { modifier: string; key: string } | null {
+  if (!token.startsWith("\x1b[1;")) return null;
+  const m = /^(\d)([A-DHF])$/.exec(token.slice(4));
+  if (!m) return null;
+  const modifier = MODIFIER_NAMES.get(m[1]!);
+  const key = MODIFIED_KEYS.get(m[2]!);
+  return modifier && key ? { modifier, key } : null;
+}
 /** Split a raw input chunk into individual key tokens (escape sequences, control chars, printable runs). */
 export function tokenize(input: string): string[] {
   const tokens: string[] = [];
@@ -160,8 +192,12 @@ export function eventsToOps(rec: Recording, opts: ScriptGenOptions): Op[] {
         pushKey({ kind: "ctrl", letter, times: 1 });
       } else if (token.length === 2 && token[0] === "\x1b") {
         pushKey({ kind: "alt", key: token[1]!, times: 1 });
+      } else if (FKEYS.has(token)) {
+        pushKey({ kind: "fkey", name: FKEYS.get(token)!, times: 1 });
       } else {
-        ops.push({ kind: "raw", data: token });
+        const mod = modifiedKey(token);
+        if (mod?.modifier === "shift") pushKey({ kind: "shift", key: mod.key, times: 1 });
+        else ops.push({ kind: "raw", data: token, ...(mod && { comment: `${mod.modifier}+${mod.key}` }) });
       }
     }
   }
@@ -186,8 +222,12 @@ function opToLine(op: Op): string {
       return op.times > 1 ? `await t.ctrl(${q(op.letter)}, ${op.times});` : `await t.ctrl(${q(op.letter)});`;
     case "alt":
       return op.times > 1 ? `await t.alt(${q(op.key)}, ${op.times});` : `await t.alt(${q(op.key)});`;
+    case "fkey":
+      return op.times > 1 ? `await t.key(${q(op.name)}, ${op.times});` : `await t.key(${q(op.name)});`;
+    case "shift":
+      return op.times > 1 ? `await t.shift(${q(op.key)}, ${op.times});` : `await t.shift(${q(op.key)});`;
     case "raw":
-      return `await t.raw(${q(op.data)});`;
+      return `await t.raw(${q(op.data)});${op.comment ? ` // ${op.comment}` : ""}`;
     case "sleep":
       return `await t.sleep(${formatMs(op.ms)});`;
   }

package/src/testing.ts CHANGED Viewed

@@ -45,7 +45,7 @@ export async function runScriptTests(inputs: string[], log: (line: string) => vo
   const results: TestResult[] = [];
   log(`TAP version 14\n1..${files.length}`);
   for (const [index, file] of files.entries()) {
-    const rel = path.relative(process.cwd(), file);
+    const rel = path.relative(process.cwd(), file).split(path.sep).join("/"); // stable TAP output on every platform
     const started = performance.now();
     let error: string | undefined;
     try {