termcut 0.7.0 → 0.7.1

package/README.md

@@ -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: [Releases](https://github.com/AmanVarshney01/tcut/releases). MP4/GIF need `ffmpeg`; SVG/HTML don't. Linux renders pixels through Chrome/Chromium on the PATH.
 
 ## Use
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "termcut",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "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

@@ -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,25 @@ 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;
+  // 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;
+  };
+  const evaluate = (js: string, ms: number, label: string): Promise<unknown> => serial(() => within(view.evaluate(js), ms, label));
+  // 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 +73,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,13 +109,17 @@ 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)) {
+      const state = await evaluate("document.readyState", 3000, "goto").catch(() => "");
+      // Some backends leave view.url empty; then a complete document is the best signal we have.
+      const href = (view.url ?? "").replace(/\/$/, "");
+      if (state === "complete" && (href === "" || href.startsWith(target))) {
         currentUrl = url;
+        loaded = true;
         return;
       }
       if (performance.now() > deadline) {
@@ -110,18 +140,32 @@ 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;
+        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() > 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() {
       running = false;
       await sampler;
+      await sampleOnce(); // final state of the page
       try {
         view.close();
       } catch {

package/src/recorder.ts

@@ -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/view.ts

@@ -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

@@ -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++) {