oh-my-opencode 4.16.0 → 4.16.1

package/script/qa/web-terminal-visual-qa.mjs

@@ -1,84 +1,64 @@
 #!/usr/bin/env node
-import { spawnSync } from "node:child_process";
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
+// Render terminal/TUI evidence through a REAL xterm.js terminal in a browser.
+//
+// A command runs in a real pty (node-pty), streams into xterm.js inside headless
+// Chrome, is driven with scripted keystrokes THROUGH the browser terminal, and is
+// screenshotted true-color. This replaces the old tmux capture-pane + hand-rolled
+// ANSI-to-HTML path, which degraded color and never rendered a real terminal.
+
+import { createRequire } from "node:module";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { basename, join, resolve } from "node:path";
-import { pathToFileURL } from "node:url";
-import {
-  DEFAULT_TERMINAL_BACKGROUND,
-  DEFAULT_TERMINAL_FOREGROUND,
-  ansiColorCss,
-  escapeHtml,
-  renderAnsiToHtml,
-  stripAnsi,
-} from "./web-terminal-renderer.mjs";
-import {
-  BUILT_IN_REDACTION_RULE_COUNT,
-  compileRedactions,
-  redactEvidence,
-} from "./web-terminal-redaction.mjs";
+import { captureLive } from "./xterm-live-terminal.mjs";
+import { BUILT_IN_REDACTION_RULE_COUNT, compileRedactions, redactEvidence } from "./web-terminal-redaction.mjs";
+import { stripAnsi } from "./strip-ansi.mjs";
+
+const require = createRequire(import.meta.url);
 
 const HELP = `web-terminal-visual-qa
 
-Render terminal/TUI evidence through a browser-capturable web page.
+Render terminal/TUI evidence through a REAL xterm.js terminal captured in a browser (true color, no tmux).
 
 Usage:
-  node script/qa/web-terminal-visual-qa.mjs --title "Codex TUI" --from-file pane.txt --evidence-dir .omo/evidence/run
-  node script/qa/web-terminal-visual-qa.mjs --title "OpenCode TUI" --command "opencode --help" --evidence-dir .omo/evidence/run
+  node script/qa/web-terminal-visual-qa.mjs --title "Codex TUI" --command "codex --help" --evidence-dir .omo/evidence/run
+  node script/qa/web-terminal-visual-qa.mjs --title "TUI" --command "my-tui" --input "{Down}" --input "{Down}" --input "{Enter}" --evidence-dir .omo/evidence/run
+  node script/qa/web-terminal-visual-qa.mjs --title "Replay" --from-file pane.ansi --evidence-dir .omo/evidence/run
+  node script/qa/web-terminal-visual-qa.mjs --self-test
 
 Inputs:
-  --from-file <path>     Replay an existing terminal/tmux transcript.
-  --command <command>    Run a command through a tmux-backed PTY connector, capture the pane, then clean up.
-  --cwd <path>           Working directory for --command. Defaults to current directory.
-  --cols <n>             Terminal columns for tmux connector. Default: 140.
-  --rows <n>             Terminal rows for tmux connector. Default: 40.
-  --dwell-ms <n>         Milliseconds to let --command render before capture. Default: 3000.
-  --wrap                 Wrap long terminal lines in HTML/PNG evidence. Default.
-  --no-wrap              Preserve long lines with horizontal scrolling.
-  --evidence-dir <path>  Directory for terminal.txt, terminal-ansi.txt, terminal.html, terminal.png, metadata.json.
-  --chrome-bin <path>    Chrome/Chromium executable for PNG capture.
+  --command <command>    Run in a real node-pty and render live in xterm.js. The color path is xterm.js - NEVER tmux.
+  --from-file <path>     Render an existing raw terminal byte stream through xterm.js (replay; no interaction).
+  --input <token>        Scripted interaction, repeatable, applied in order THROUGH the browser terminal.
+                         Literal text is typed; {Enter} {Tab} {Escape} {ArrowDown} {Ctrl+C} etc. are pressed as keys.
+  --cwd <path>           Working directory for --command. Default: current directory.
+  --cols <n> / --rows <n>  Terminal geometry. Default: 120 x 32.
+  --dwell-ms <n>         Milliseconds to let the TUI settle after input before capture. Default: 1500.
+  --key-delay-ms <n>     Pause between --input tokens. Default: 120.
+  --evidence-dir <path>  Directory for terminal.png, terminal.txt, terminal-ansi.txt, metadata.json.
+  --chrome-bin <path>    Chrome/Chromium executable (else auto-detect or CHROME_BIN).
   --source-label <text>  Safe label for --command metadata. The raw command is never written to metadata.
-  --redact <literal>     Literal secret value to redact before writing evidence. Repeatable.
-  --redact-regex <expr>  JavaScript regex source to redact before writing evidence. Repeatable.
-  --no-browser           Skip PNG capture, but still write HTML/text/metadata.
-
-Connector notes:
-  --command uses tmux as the tmux-backed PTY connector on macOS/Linux and on Windows environments that provide tmux.
-  Windows-native ConPTY live mode should plug into this same metadata contract later; until then use --from-file or Git Bash/tmux.
+  --redact <literal>     Literal secret to mask in ALL evidence, PNG included. Repeatable.
+  --redact-regex <expr>  JS regex source to mask in ALL evidence, PNG included. Repeatable.
+  --no-browser           Skip xterm.js/Chrome; capture the raw pty stream only (no PNG). For chrome-less CI.
 
 Secret handling:
-  Terminal evidence is redacted before terminal.txt, terminal-ansi.txt, terminal.html, and terminal.png are written.
-  Built-in rules cover common Authorization headers, token/password/key assignments, and GitHub/OpenAI-style tokens.
-  Add --redact for exact local values and --redact-regex for project-specific patterns.
-  The raw --command string is treated as secret-bearing process data and is never stored in metadata.json.
+  Text evidence and the screenshot are redacted before anything is written. When a redaction rule matches, the
+  masked stream is re-rendered so the PNG never shows the secret. The raw --command string is never stored.
 `;
 
+function parsePositiveInt(name, value) {
+  const parsed = Number.parseInt(value, 10);
+  if (!Number.isFinite(parsed) || parsed <= 0) throw new Error(`${name} must be a positive integer`);
+  return parsed;
+}
+
 function parseArgs(argv) {
-  const args = {
-    cols: 140,
-    rows: 40,
-    dwellMs: 3000,
-    cwd: process.cwd(),
-    browser: true,
-    wrap: true,
-    redactions: [],
-    redactRegexes: [],
-  };
+  const args = { cols: 120, rows: 32, dwellMs: 1500, keyDelayMs: 120, cwd: process.cwd(), browser: true, redactions: [], redactRegexes: [], inputs: [] };
   for (let i = 0; i < argv.length; i += 1) {
     const arg = argv[i];
     if (arg === "--help" || arg === "-h") return { ...args, help: true };
-    if (arg === "--no-browser") {
-      args.browser = false;
-      continue;
-    }
-    if (arg === "--wrap") {
-      args.wrap = true;
-      continue;
-    }
-    if (arg === "--no-wrap") {
-      args.wrap = false;
-      continue;
-    }
+    if (arg === "--self-test") return { ...args, selfTest: true };
+    if (arg === "--no-browser") { args.browser = false; continue; }
     const next = argv[i + 1];
     if (!next) throw new Error(`missing value for ${arg}`);
     i += 1;
@@ -89,22 +69,18 @@ function parseArgs(argv) {
     else if (arg === "--evidence-dir") args.evidenceDir = next;
     else if (arg === "--chrome-bin") args.chromeBin = next;
     else if (arg === "--source-label") args.sourceLabel = next;
+    else if (arg === "--input") args.inputs.push(next);
     else if (arg === "--redact") args.redactions.push(next);
     else if (arg === "--redact-regex") args.redactRegexes.push(next);
     else if (arg === "--cols") args.cols = parsePositiveInt(arg, next);
     else if (arg === "--rows") args.rows = parsePositiveInt(arg, next);
     else if (arg === "--dwell-ms") args.dwellMs = parsePositiveInt(arg, next);
+    else if (arg === "--key-delay-ms") args.keyDelayMs = parsePositiveInt(arg, next);
     else throw new Error(`unknown argument: ${arg}`);
   }
   return args;
 }
 
-function parsePositiveInt(name, value) {
-  const parsed = Number.parseInt(value, 10);
-  if (!Number.isFinite(parsed) || parsed <= 0) throw new Error(`${name} must be a positive integer`);
-  return parsed;
-}
-
 function requireArgs(args) {
   if (!args.evidenceDir) throw new Error("--evidence-dir is required");
   if (!args.title) throw new Error("--title is required");
@@ -112,153 +88,94 @@ function requireArgs(args) {
   if (!args.fromFile && !args.command) throw new Error("choose --from-file or --command");
 }
 
-function terminalWidthCh(cols) {
-  return Math.max(80, Math.min(cols, 160));
-}
-
-function screenshotSize({ cols, rows }) {
-  return {
-    width: Math.max(900, Math.min(1440, Math.round(cols * 8.2 + 120))),
-    height: Math.max(520, Math.min(1200, Math.round(rows * 18 + 120))),
-  };
-}
-
 function sourceMetadata(args) {
   if (args.fromFile) return { kind: "file-replay", path: resolve(args.fromFile) };
   return { kind: "command", label: args.sourceLabel || "redacted command" };
 }
 
-function writeHtml({ title, ansi, outPath, cols, wrap }) {
-  const whiteSpace = wrap ? "pre-wrap" : "pre";
-  const overflowWrap = wrap ? "anywhere" : "normal";
-  const terminalWidth = terminalWidthCh(cols);
-  const html = `<!doctype html>
-<html lang="en">
-<head>
-<meta charset="utf-8">
-<meta name="viewport" content="width=device-width, initial-scale=1">
-<title>${escapeHtml(title)}</title>
-<style>
-:root { color-scheme: dark; }
-body { margin: 0; background: #101217; color: ${DEFAULT_TERMINAL_FOREGROUND}; font: 13px/1.35 "SFMono-Regular", "Cascadia Mono", "JetBrains Mono", "Menlo", "Consolas", "Liberation Mono", ui-monospace, monospace; }
-main { min-height: 100vh; box-sizing: border-box; padding: 20px; }
-.terminal { width: min(100%, ${terminalWidth}ch); max-width: calc(100vw - 40px); border: 1px solid #3b4452; background: ${DEFAULT_TERMINAL_BACKGROUND}; box-shadow: 0 20px 80px rgb(0 0 0 / 40%); }
-.bar { display: flex; gap: 8px; align-items: center; padding: 8px 12px; border-bottom: 1px solid #303846; color: #aab7c4; background: #171b22; font-size: 12px; }
-.dot { width: 10px; height: 10px; border-radius: 999px; background: #6b7280; }
-pre { margin: 0; padding: 14px 16px; white-space: ${whiteSpace}; overflow-wrap: ${overflowWrap}; tab-size: 8; overflow: auto; }
-.ansi-bold { font-weight: 700; }
-.ansi-dim { opacity: 0.72; }
-.ansi-italic { font-style: italic; }
-.ansi-underline { text-decoration: underline; }
-.ansi-strike { text-decoration: line-through; }
-${ansiColorCss()}
-</style>
-</head>
-<body><main><section class="terminal"><div class="bar"><span class="dot"></span><strong>${escapeHtml(title)}</strong></div><pre>${renderAnsiToHtml(ansi)}</pre></section></main></body>
-</html>
-`;
-  writeFileSync(outPath, html, "utf8");
-}
-
-function captureFromFile(path) {
-  const ansi = readFileSync(path, "utf8");
-  return { ansi, cleanup: "cleanup: file replay; no live process", connector: "file-replay" };
+// Chrome-less path: run the command in a real pty and keep the raw stream only.
+async function captureRawPty(args) {
+  const { chmodSync, existsSync: exists } = await import("node:fs");
+  const { dirname, join: pjoin } = await import("node:path");
+  try {
+    const ptyRoot = dirname(require.resolve("node-pty"));
+    const helper = pjoin(ptyRoot, `../prebuilds/${process.platform}-${process.arch}/spawn-helper`);
+    if (exists(helper)) chmodSync(helper, 0o755);
+  } catch {}
+  const pty = require("node-pty");
+  const proc = pty.spawn(process.env.SHELL || "bash", ["-lc", args.command], {
+    name: "xterm-256color", cols: args.cols, rows: args.rows, cwd: args.cwd,
+    env: { ...process.env, TERM: "xterm-256color", COLORTERM: "truecolor" },
+  });
+  let raw = "";
+  proc.onData((d) => { raw += d; });
+  await new Promise((r) => setTimeout(r, args.dwellMs + 400));
+  try { proc.kill(); } catch {}
+  return { pngBuffer: null, screenText: stripAnsi(raw), rawStream: raw, connector: "node-pty-raw", cleanup: `pty pid ${proc.pid} killed` };
 }
 
-function shellQuote(value) {
-  return `'${value.replaceAll("'", "'\\''")}'`;
+function captureFileRaw(content) {
+  return { pngBuffer: null, screenText: stripAnsi(content), rawStream: content, connector: "file-raw", cleanup: "file replay; no process" };
 }
 
-function runTmuxCommand(args) {
-  const tmux = spawnSync("tmux", ["-V"], { encoding: "utf8" });
-  if (tmux.status !== 0) throw new Error("--command requires tmux on PATH; use --from-file on hosts without tmux");
-  const session = `omo_webterm_${process.pid}_${Date.now()}`;
-  const wrapped = `${args.command}; printf '\\n[web-terminal-visual-qa exit:%s]\\n' "$?"; sleep 600`;
-  const launch = spawnSync("tmux", ["new-session", "-d", "-s", session, "-x", String(args.cols), "-y", String(args.rows), "-c", resolve(args.cwd), "sh", "-lc", wrapped], { encoding: "utf8" });
-  if (launch.status !== 0) throw new Error(`tmux launch failed: ${launch.stderr || launch.stdout}`);
-  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, args.dwellMs);
-  const plain = spawnSync("tmux", ["capture-pane", "-p", "-S", "-", "-t", session], { encoding: "utf8" });
-  const ansi = spawnSync("tmux", ["capture-pane", "-e", "-p", "-S", "-", "-t", session], { encoding: "utf8" });
-  spawnSync("tmux", ["kill-session", "-t", session], { encoding: "utf8" });
-  const plainCapture = plain.status === 0 ? plain.stdout : "";
-  const ansiCapture = ansi.status === 0 ? ansi.stdout : "";
-  const captured = ansiCapture || plainCapture;
-  if (!captured || stripAnsi(captured).trim().length === 0) {
-    const detail = [plain.stderr || plain.stdout, ansi.stderr || ansi.stdout].filter(Boolean).join("; ");
-    throw new Error(`tmux capture was empty${detail ? `: ${detail}` : ""}`);
-  }
-  return {
-    ansi: captured,
-    cleanup: `cleanup: tmux kill-session -t ${shellQuote(session)}`,
-    connector: "tmux-backed-pty",
-  };
-}
-
-function chromeCandidates(explicit) {
-  const candidates = [explicit, process.env.CHROME_BIN, process.env.GOOGLE_CHROME_BIN];
-  if (process.platform === "darwin") candidates.push("/Applications/Google Chrome.app/Contents/MacOS/Google Chrome", "/Applications/Chromium.app/Contents/MacOS/Chromium");
-  if (process.platform === "linux") candidates.push("google-chrome", "google-chrome-stable", "chromium", "chromium-browser");
-  if (process.platform === "win32") {
-    candidates.push(join(process.env.PROGRAMFILES || "C:\\Program Files", "Google\\Chrome\\Application\\chrome.exe"));
-    candidates.push(join(process.env["PROGRAMFILES(X86)"] || "C:\\Program Files (x86)", "Google\\Chrome\\Application\\chrome.exe"));
-  }
-  return candidates.filter((candidate) => candidate && (candidate.includes("/") || candidate.includes("\\") ? existsSync(candidate) : true));
-}
-
-function capturePng(args) {
-  for (const chrome of chromeCandidates(args.chromeBin)) {
-    const result = spawnSync(chrome, ["--headless=new", "--disable-gpu", `--window-size=${args.width},${args.height}`, `--screenshot=${args.pngPath}`, pathToFileURL(args.htmlPath).href], { encoding: "utf8" });
-    if (result.status === 0 && existsSync(args.pngPath)) return { status: "captured", chrome };
-  }
-  throw new Error("PNG capture failed: set --chrome-bin or --no-browser");
-}
-
-function main() {
-  const args = parseArgs(process.argv.slice(2));
-  if (args.help) {
-    process.stdout.write(HELP);
-    return;
-  }
-  requireArgs(args);
+async function run(args) {
   const evidenceDir = resolve(args.evidenceDir);
   mkdirSync(evidenceDir, { recursive: true });
-  const htmlPath = join(evidenceDir, "terminal.html");
+  const rules = compileRedactions(args);
+  const redactStream = (s) => redactEvidence(s, rules);
+  const fromFile = args.fromFile ? readFileSync(args.fromFile, "utf8") : undefined;
+
+  let cap;
+  if (args.browser) cap = await captureLive({ ...args, fromFile, redactStream });
+  else if (fromFile !== undefined) cap = captureFileRaw(fromFile);
+  else cap = await captureRawPty(args);
+
+  const safeText = redactStream(cap.screenText);
+  const safeAnsi = redactStream(cap.rawStream);
   const textPath = join(evidenceDir, "terminal.txt");
   const ansiPath = join(evidenceDir, "terminal-ansi.txt");
   const pngPath = join(evidenceDir, "terminal.png");
   const metadataPath = join(evidenceDir, "metadata.json");
-  const capture = args.fromFile ? captureFromFile(args.fromFile) : runTmuxCommand(args);
-  const redactionRules = compileRedactions(args);
-  const safeAnsi = redactEvidence(capture.ansi, redactionRules);
-  const text = stripAnsi(safeAnsi);
-  writeFileSync(textPath, text, "utf8");
+  writeFileSync(textPath, safeText.endsWith("\n") ? safeText : `${safeText}\n`, "utf8");
   writeFileSync(ansiPath, safeAnsi, "utf8");
-  writeHtml({ title: args.title, ansi: safeAnsi, outPath: htmlPath, cols: args.cols, wrap: args.wrap });
-  const size = screenshotSize({ cols: args.cols, rows: args.rows });
-  const browser = args.browser ? capturePng({ chromeBin: args.chromeBin, htmlPath, pngPath, ...size }) : { status: "skipped" };
+  if (cap.pngBuffer) writeFileSync(pngPath, cap.pngBuffer);
+
   const metadata = {
     title: args.title,
-    connector: capture.connector,
-    browserCapture: browser.status,
+    connector: cap.connector,
+    colorPath: "xterm.js (true color; not tmux)",
+    browserCapture: cap.pngBuffer ? "captured" : "skipped",
     source: sourceMetadata(args),
-    redaction: {
-      builtInRules: BUILT_IN_REDACTION_RULE_COUNT,
-      literalRules: args.redactions.length,
-      regexRules: args.redactRegexes.length,
-    },
-    wrap: args.wrap ? "on" : "off",
-    dimensions: { cols: args.cols, rows: args.rows, screenshotWidth: size.width, screenshotHeight: size.height },
-    cleanup: capture.cleanup,
-    files: { html: htmlPath, text: textPath, ansi: ansiPath, png: browser.status === "captured" ? pngPath : null, metadata: metadataPath },
+    interaction: args.inputs,
+    redaction: { builtInRules: BUILT_IN_REDACTION_RULE_COUNT, literalRules: args.redactions.length, regexRules: args.redactRegexes.length },
+    dimensions: { cols: args.cols, rows: args.rows },
+    cleanup: cap.cleanup,
+    files: { png: cap.pngBuffer ? pngPath : null, text: textPath, ansi: ansiPath, metadata: metadataPath },
   };
   writeFileSync(metadataPath, `${JSON.stringify(metadata, null, 2)}\n`, "utf8");
-  process.stdout.write(`web terminal visual QA evidence (${basename(evidenceDir)}):\n${JSON.stringify(metadata.files, null, 2)}\n${capture.cleanup}\n`);
+  process.stdout.write(`web terminal visual QA evidence (${basename(evidenceDir)}):\n${JSON.stringify(metadata.files, null, 2)}\ncleanup: ${cap.cleanup}\n`);
 }
 
-try {
-  main();
-} catch (error) {
-  const message = error instanceof Error ? error.message : String(error);
-  process.stderr.write(`${message}\n`);
-  process.exit(1);
+async function selfTest() {
+  // Asset resolution + real pty capture, without requiring Chrome (chrome-less CI safe).
+  for (const spec of ["@xterm/xterm/lib/xterm.js", "@xterm/xterm/css/xterm.css", "@xterm/addon-unicode11/lib/addon-unicode11.js"]) {
+    if (readFileSync(require.resolve(spec), "utf8").length < 100) throw new Error(`asset too small: ${spec}`);
+  }
+  const cap = await captureRawPty({ command: "printf '\\033[31mRED\\033[0m \\033[32mGREEN\\033[0m 한글ABC'", cwd: process.cwd(), cols: 40, rows: 8, dwellMs: 300 });
+  if (!/RED/.test(cap.rawStream) || !cap.rawStream.includes("")) throw new Error("pty did not emit expected ANSI");
+  if (!cap.rawStream.includes("한글")) throw new Error("pty dropped CJK bytes");
+  process.stdout.write("self-test PASS: xterm assets resolve; node-pty emits true-color ANSI + CJK\n");
 }
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help) { process.stdout.write(HELP); return; }
+  if (args.selfTest) { await selfTest(); return; }
+  requireArgs(args);
+  await run(args);
+}
+
+main().catch((error) => {
+  process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+  process.exit(1);
+});

package/script/qa/xterm-live-terminal.mjs

@@ -0,0 +1,180 @@
+// Live xterm.js + node-pty terminal capture core.
+//
+// Spawns a command in a REAL pty (node-pty), bridges it to a REAL xterm.js
+// terminal running in a headless Chrome page (puppeteer-core drives the system
+// Chrome), drives scripted interaction THROUGH the browser terminal, then
+// screenshots the xterm.js render. The screenshot is true-color because
+// xterm.js interprets the raw pty byte stream itself - no tmux capture-pane,
+// no hand-rolled ANSI-to-HTML, no color degradation.
+
+import { createRequire } from "node:module";
+import { chmodSync, existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+const require = createRequire(import.meta.url);
+
+function resolveAsset(spec) {
+  const path = require.resolve(spec);
+  return readFileSync(path, "utf8");
+}
+
+// node-pty ships a `spawn-helper` on macOS/Linux that MUST be executable.
+// `bun install` (unlike npm) does not run node-pty's chmod postinstall, so the
+// committed harness heals the exec bit itself before the first spawn.
+function healSpawnHelper() {
+  let ptyRoot;
+  try {
+    ptyRoot = dirname(require.resolve("node-pty"));
+  } catch {
+    return;
+  }
+  const candidates = [
+    join(ptyRoot, `../prebuilds/${process.platform}-${process.arch}/spawn-helper`),
+    join(ptyRoot, "../build/Release/spawn-helper"),
+  ];
+  for (const helper of candidates) {
+    if (existsSync(helper)) {
+      try {
+        chmodSync(helper, 0o755);
+      } catch {
+        // best effort - a read-only store still works when the bit is already set
+      }
+    }
+  }
+}
+
+function buildPageHtml({ xtermJs, xtermCss, unicodeJs, cols, rows, fontSize }) {
+  return `<!doctype html><html><head><meta charset="utf-8"><style>
+${xtermCss}
+html,body{margin:0;padding:0;background:#0b0e14}
+#t{padding:8px}
+</style></head><body><div id="t"></div>
+<script>${xtermJs}</script>
+<script>${unicodeJs}</script>
+<script>
+  const term = new Terminal({
+    cols: ${cols}, rows: ${rows}, fontSize: ${fontSize},
+    fontFamily: 'Menlo, "DejaVu Sans Mono", "Noto Sans Mono CJK KR", monospace',
+    allowProposedApi: true, convertEol: false, scrollback: 0,
+    theme: { background: '#0b0e14', foreground: '#d7dae0' },
+  });
+  try { const u = new Unicode11Addon.Unicode11Addon(); term.loadAddon(u); term.unicode.activeVersion = '11'; } catch (e) {}
+  term.open(document.getElementById('t'));
+  window.__writeToTerm = (d) => term.write(d);
+  window.__screenText = () => {
+    const b = term.buffer.active; const lines = [];
+    for (let i = 0; i < b.length; i++) { const ln = b.getLine(i); lines.push(ln ? ln.translateToString(true) : ''); }
+    return lines.join('\\n').replace(/\\n+$/, '\\n');
+  };
+  window.__resetAndWrite = (d) => { term.reset(); term.write(d); };
+  term.focus();
+  term.onData((d) => { if (window.__ptyInput) window.__ptyInput(d); });
+</script></body></html>`;
+}
+
+const NAMED_KEYS = new Set([
+  "Enter", "Tab", "Escape", "Backspace", "Delete", "Space",
+  "ArrowUp", "ArrowDown", "ArrowLeft", "ArrowRight", "Home", "End", "PageUp", "PageDown",
+]);
+
+// An `input` token wrapped in {Braces} is pressed as a named key; anything else
+// is typed literally. Both flow through the browser terminal (xterm onData ->
+// pty), so the interaction is genuinely driven in the web terminal.
+async function driveInput(page, inputs, keyDelayMs) {
+  for (const raw of inputs) {
+    const match = /^\{(.+)\}$/.exec(raw);
+    if (match && NAMED_KEYS.has(match[1])) {
+      await page.keyboard.press(match[1] === "Space" ? " " : match[1], { delay: 15 });
+    } else if (match && /^Ctrl\+(.)$/i.test(match[1])) {
+      const key = /^Ctrl\+(.)$/i.exec(match[1])[1];
+      await page.keyboard.down("Control");
+      await page.keyboard.press(key);
+      await page.keyboard.up("Control");
+    } else {
+      await page.keyboard.type(raw, { delay: 10 });
+    }
+    if (keyDelayMs > 0) await new Promise((r) => setTimeout(r, keyDelayMs));
+  }
+}
+
+function chromeCandidates(explicit) {
+  const c = [explicit, process.env.CHROME_BIN, process.env.GOOGLE_CHROME_BIN];
+  if (process.platform === "darwin")
+    c.push("/Applications/Google Chrome.app/Contents/MacOS/Google Chrome", "/Applications/Chromium.app/Contents/MacOS/Chromium");
+  if (process.platform === "linux") c.push("/usr/bin/google-chrome", "/usr/bin/chromium", "/usr/bin/chromium-browser");
+  if (process.platform === "win32") {
+    c.push(join(process.env.PROGRAMFILES || "C:\\Program Files", "Google\\Chrome\\Application\\chrome.exe"));
+    c.push(join(process.env["PROGRAMFILES(X86)"] || "C:\\Program Files (x86)", "Google\\Chrome\\Application\\chrome.exe"));
+  }
+  return c.filter((x) => x && (x.includes("/") || x.includes("\\") ? existsSync(x) : true));
+}
+
+async function captureLive({ command, cwd, cols, rows, inputs, dwellMs, keyDelayMs, chromeBin, fromFile, redactStream }) {
+  healSpawnHelper();
+  const puppeteer = (await import("puppeteer-core")).default;
+  const executablePath = chromeCandidates(chromeBin)[0];
+  if (!executablePath) throw new Error("no Chrome/Chromium found; set --chrome-bin or CHROME_BIN");
+
+  const html = buildPageHtml({
+    xtermJs: resolveAsset("@xterm/xterm/lib/xterm.js"),
+    xtermCss: resolveAsset("@xterm/xterm/css/xterm.css"),
+    unicodeJs: resolveAsset("@xterm/addon-unicode11/lib/addon-unicode11.js"),
+    cols, rows, fontSize: 15,
+  });
+
+  const browser = await puppeteer.launch({
+    executablePath, headless: "new",
+    args: ["--no-sandbox", "--disable-gpu", "--hide-scrollbars", "--force-color-profile=srgb"],
+    defaultViewport: { width: cols * 10 + 40, height: rows * 20 + 40, deviceScaleFactor: 2 },
+  });
+
+  let rawStream = "";
+  let ptyProc;
+  const cleanupParts = [];
+  try {
+    const page = await browser.newPage();
+    await page.setContent(html, { waitUntil: "load" });
+    await page.evaluate(() => document.fonts && document.fonts.ready);
+
+    if (fromFile) {
+      rawStream = fromFile;
+      const shown = redactStream ? redactStream(rawStream) : rawStream;
+      await page.evaluate((d) => window.__writeToTerm(d), shown);
+      cleanupParts.push("no pty (replay)");
+    } else {
+      const pty = require("node-pty");
+      ptyProc = pty.spawn(process.env.SHELL || "bash", ["-lc", command], {
+        name: "xterm-256color", cols, rows, cwd: cwd || process.cwd(),
+        env: { ...process.env, TERM: "xterm-256color", COLORTERM: "truecolor" },
+      });
+      await page.exposeFunction("__ptyInput", (d) => { try { ptyProc.write(d); } catch {} });
+      ptyProc.onData((d) => {
+        rawStream += d;
+        page.evaluate((chunk) => window.__writeToTerm(chunk), d).catch(() => {});
+      });
+      await new Promise((r) => setTimeout(r, 400));
+      await page.focus("#t");
+      if (inputs.length) await driveInput(page, inputs, keyDelayMs);
+      await new Promise((r) => setTimeout(r, dwellMs));
+      cleanupParts.push(`pty pid ${ptyProc.pid} killed`);
+    }
+
+    // When redactions are configured, re-render the masked stream so the PNG
+    // never shows a secret that the interaction surfaced on screen.
+    if (redactStream && !fromFile) {
+      const masked = redactStream(rawStream);
+      if (masked !== rawStream) await page.evaluate((d) => window.__resetAndWrite(d), masked);
+    }
+    await page.evaluate(() => new Promise((r) => requestAnimationFrame(() => requestAnimationFrame(r))));
+
+    const screenText = await page.evaluate(() => window.__screenText());
+    const el = (await page.$(".xterm")) || page;
+    const pngBuffer = await el.screenshot({ type: "png" });
+    return { pngBuffer, screenText, rawStream, connector: fromFile ? "xterm-replay" : "xterm-node-pty", cleanup: cleanupParts.join("; ") };
+  } finally {
+    try { ptyProc && ptyProc.kill(); } catch {}
+    await browser.close();
+  }
+}
+
+export { captureLive };