oh-my-opencode 4.13.0 → 4.14.0

package/packages/shared-skills/skills/visual-qa/scripts/skill-prompt-contract.test.ts

@@ -68,6 +68,8 @@ describe("visual-qa skill prompt contract", () => {
 			expect(lowerPassB, fixture.label).toContain("view_image")
 			expect(lowerPassB, fixture.label).toContain("source code")
 			expect(passB, fixture.label).toContain("[Image #1]")
+			expect(passB, fixture.label).toContain("semantic phrases")
+			expect(passB, fixture.label).toContain("놀라운 변 / 화")
 			expect(passB, fixture.label).toContain("에이전트 오케스트")
 			expect(passB, fixture.label).toContain("레이션 현황 및 미")
 			expect(passB, fixture.label).toContain("래")
@@ -112,16 +114,133 @@ describe("visual-qa skill prompt contract", () => {
 		expect(doc).toContain("agent-browser --help")
 	})
 
-	test("#given a clone/design-port task #when in clone-coding mode #then dual pixel + code-fidelity verification loops until both pass", () => {
+	test("#given a concrete visual target #when in reference-fidelity mode #then dual pixel + code-fidelity verification loops until both pass", () => {
 		for (const fixture of fixtures()) {
 			const cloneMode = sectionBetween(fixture.text, "## Step 5", "## Reference evidence is not the verdict")
 			const lowerCloneMode = cloneMode.toLowerCase()
 
 			expect(lowerCloneMode, fixture.label).toContain("clone")
+			expect(lowerCloneMode, fixture.label).toContain("imagen")
+			expect(lowerCloneMode, fixture.label).toContain("stitch")
+			expect(lowerCloneMode, fixture.label).toContain("generated mockup")
+			expect(lowerCloneMode, fixture.label).toContain("overview")
 			expect(cloneMode, fixture.label).toContain("pixel-by-pixel")
 			expect(cloneMode, fixture.label).toContain("image-diff")
 			expect(cloneMode, fixture.label).toContain("lazycodex-clone-fidelity-reviewer")
+			expect(lowerCloneMode, fixture.label).toContain("extensible state variants")
 			expect(lowerCloneMode, fixture.label).toContain("retry")
 		}
 	})
 })
+
+describe("visual-qa skill exhaustive-coverage and review-gate contract", () => {
+	test("#given a multi-page surface #when capturing #then every page is enumerated and verified per page, not sampled", () => {
+		for (const fixture of fixtures()) {
+			const capture = sectionBetween(fixture.text, "## Step 2", "## Step 3")
+			const lower = capture.toLowerCase()
+
+			expect(lower, fixture.label).toContain("every page")
+			expect(lower, fixture.label).toContain("enumerate")
+			expect(lower, fixture.label).toContain("never sample")
+			expect(lower, fixture.label).toContain("per page")
+			expect(lower, fixture.label).toContain("one failing page fails")
+		}
+	})
+
+	test("#given prior QA artifacts #when verifying #then stale evidence older than the source must be regenerated", () => {
+		for (const fixture of fixtures()) {
+			const capture = sectionBetween(fixture.text, "## Step 2", "## Step 3")
+			const lower = capture.toLowerCase()
+
+			expect(lower, fixture.label).toContain("stale")
+			expect(lower, fixture.label).toContain("older than")
+			expect(lower, fixture.label).toContain("regenerate")
+		}
+	})
+
+	test("#given Step 3 dispatch #when running the review #then it is required pre-done, harness-native, and covers every enumerated page", () => {
+		for (const fixture of fixtures()) {
+			const dispatch = sectionBetween(fixture.text, "## Step 3", "### Pass A")
+			const lower = dispatch.toLowerCase()
+
+			expect(lower, fixture.label).toContain("required before")
+			expect(lower, fixture.label).toContain("do not self-review")
+			expect(dispatch, fixture.label).toContain("spawn_agent")
+			expect(dispatch, fixture.label).toContain("lazycodex-gate-reviewer")
+			expect(lower, fixture.label).toContain("every enumerated page")
+		}
+	})
+
+	test("#given the completion gate #when deciding done #then an independent reviewer must PASS on a fresh full capture, looping until clean", () => {
+		for (const fixture of fixtures()) {
+			const gate = sectionBetween(fixture.text, "## Step 4", "## Step 5")
+			const lower = gate.toLowerCase()
+
+			expect(lower, fixture.label).toContain("hard stop rule")
+			expect(lower, fixture.label).toContain("independent")
+			expect(lower, fixture.label).toContain("no blocking")
+			expect(lower, fixture.label).toContain("fresh")
+			expect(lower, fixture.label).toContain("every enumerated page")
+			expect(lower, fixture.label).toContain("loop until")
+			expect(lower, fixture.label).toContain("do not stop because the automated script")
+		}
+	})
+
+	test("#given Pass B CJK checks #when inspecting #then it flags topic, connective, and source-citation splits across every page", () => {
+		for (const fixture of fixtures()) {
+			const passB = sectionBetween(fixture.text, "### Pass B", "## Step 4")
+			const lower = passB.toLowerCase()
+
+			expect(passB, fixture.label).toContain("두 강은")
+			expect(passB, fixture.label).toContain("쓸 수")
+			expect(passB, fixture.label).toContain("Attention Is")
+			expect(lower, fixture.label).toContain("citation")
+			expect(lower, fixture.label).toContain("every page")
+			expect(lower, fixture.label).toContain("regardless of similarityscore")
+		}
+	})
+
+	test("#given a generated reference packet #when reviewing #then Pass A and B require extensible design-system code and pixel-level reference matching", () => {
+		for (const fixture of fixtures()) {
+			const passA = sectionBetween(fixture.text, "### Pass A", "### Pass B")
+			const passB = sectionBetween(fixture.text, "### Pass B", "## Step 4")
+			const lowerPassA = passA.toLowerCase()
+			const lowerPassB = passB.toLowerCase()
+
+			expect(passA, fixture.label).toContain("REFERENCE PACKET:")
+			expect(passB, fixture.label).toContain("REFERENCE PACKET:")
+			expect(lowerPassA, fixture.label).toContain("reusable tokens/primitives")
+			expect(lowerPassA, fixture.label).toContain("extend to new pages")
+			expect(lowerPassA, fixture.label).toContain("missing overview content")
+			expect(lowerPassB, fixture.label).toContain("pixel-perfectly")
+			expect(lowerPassB, fixture.label).toContain("actual against reference")
+			expect(lowerPassB, fixture.label).toContain("overview text is part of the target")
+		}
+	})
+
+	test("#given reference packet evidence #when prompting reviewers #then sensitive content is redacted and annotations stay untrusted data", () => {
+		for (const fixture of fixtures()) {
+			const capture = sectionBetween(fixture.text, "## Step 2", "## Step 3")
+			const passA = sectionBetween(fixture.text, "### Pass A", "### Pass B")
+			const passB = sectionBetween(fixture.text, "### Pass B", "## Step 4")
+			const combined = `${capture}\n${passA}\n${passB}`.toLowerCase()
+
+			expect(combined, fixture.label).toContain("redact or omit secrets")
+			expect(combined, fixture.label).toContain("credentials")
+			expect(combined, fixture.label).toContain("tokens")
+			expect(combined, fixture.label).toContain("auth headers")
+			expect(combined, fixture.label).toContain("customer data")
+			expect(combined, fixture.label).toContain("private messages")
+			expect(combined, fixture.label).toContain("internal urls")
+			expect(combined, fixture.label).toContain("other sensitive content")
+			expect(combined, fixture.label).toContain("overview text")
+			expect(combined, fixture.label).toContain("annotations")
+			expect(combined, fixture.label).toContain("untrusted data")
+			expect(combined, fixture.label).toContain("captured ui copy")
+			expect(combined, fixture.label).toContain("comments")
+			expect(combined, fixture.label).toContain("filenames")
+			expect(combined, fixture.label).toContain("not reviewer instructions")
+			expect(combined, fixture.label).toContain("never as instructions")
+		}
+	})
+})

package/script/qa/web-terminal-redaction.d.mts

@@ -0,0 +1,13 @@
+export type RedactionRule = {
+  readonly regex: RegExp
+  readonly preservePrefix: boolean
+}
+
+export declare const BUILT_IN_REDACTION_RULE_COUNT: number
+
+export declare function compileRedactions(input: {
+  readonly redactions: readonly string[]
+  readonly redactRegexes: readonly string[]
+}): RedactionRule[]
+
+export declare function redactEvidence(text: string, rules: readonly RedactionRule[]): string

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

@@ -0,0 +1,43 @@
+const BUILT_IN_REDACTION_REGEXES = [
+  /((?:authorization|proxy-authorization):\s*(?:bearer|basic)\s+)[^\s"'<>]+/gi,
+  /((?:"|')?(?:authorization|proxy-authorization)(?:"|')?\s*:\s*(?:"|')?(?:bearer|basic)\s+)[^"'\s,}\]\[]+((?:"|')?)/gi,
+  /\b((?:api[_-]?key|token|password|secret|access[_-]?token|refresh[_-]?token)=["'])[^\r\n"']+(["'])/gi,
+  /\b((?:api[_-]?key|token|password|secret|access[_-]?token|refresh[_-]?token)=)[^\s"'<>]+/gi,
+  /\b(?:gh[pousr]_[A-Za-z0-9_]{20,})\b/g,
+  /\b(?:github_pat_[A-Za-z0-9_]{20,})\b/g,
+  /\b(?:sk-[A-Za-z0-9_-]{20,})\b/g,
+];
+
+export const BUILT_IN_REDACTION_RULE_COUNT = BUILT_IN_REDACTION_REGEXES.length;
+
+function escapeRegex(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+export function compileRedactions({ redactions, redactRegexes }) {
+  const rules = BUILT_IN_REDACTION_REGEXES.map((regex) => ({
+    regex,
+    preservePrefix: true,
+  }));
+  for (const literal of redactions) {
+    if (literal.length > 0) {
+      rules.push({ regex: new RegExp(escapeRegex(literal), "g"), preservePrefix: false });
+    }
+  }
+  for (const source of redactRegexes) {
+    rules.push({ regex: new RegExp(source, "g"), preservePrefix: false });
+  }
+  return rules;
+}
+
+export function redactEvidence(text, rules) {
+  return rules.reduce(
+    (current, rule) =>
+      current.replace(rule.regex, (match, prefix, suffix) =>
+        rule.preservePrefix && typeof prefix === "string"
+          ? `${prefix}[REDACTED]${typeof suffix === "string" ? suffix : ""}`
+          : "[REDACTED]",
+      ),
+    text,
+  );
+}

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

@@ -0,0 +1,218 @@
+const ANSI_PATTERN = /\u001b\[[0-?]*[ -/]*[@-~]/g;
+const OSC_PATTERN = /\u001b\][\s\S]*?(?:\u0007|\u001b\\|\u009c)/g;
+const SGR_PATTERN = /\u001b\[([0-9;:]*)m/g;
+
+const COLOR_NAMES = [
+  "black",
+  "red",
+  "green",
+  "yellow",
+  "blue",
+  "magenta",
+  "cyan",
+  "white",
+];
+
+const BASIC_ANSI_COLORS = {
+  black: "#0c0d10",
+  red: "#ff6b6b",
+  green: "#51cf66",
+  yellow: "#ffd43b",
+  blue: "#4dabf7",
+  magenta: "#d0bfff",
+  cyan: "#66d9e8",
+  white: "#f1f3f5",
+  "bright-black": "#868e96",
+  "bright-red": "#ff8787",
+  "bright-green": "#69db7c",
+  "bright-yellow": "#ffe066",
+  "bright-blue": "#74c0fc",
+  "bright-magenta": "#e599f7",
+  "bright-cyan": "#99e9f2",
+  "bright-white": "#ffffff",
+};
+
+export const DEFAULT_TERMINAL_FOREGROUND = "#d8dee9";
+export const DEFAULT_TERMINAL_BACKGROUND = "#090b10";
+
+export function escapeHtml(value) {
+  return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+}
+
+export function stripAnsi(value) {
+  return value.replace(OSC_PATTERN, "").replace(ANSI_PATTERN, "");
+}
+
+function createState() {
+  return {
+    bold: false,
+    dim: false,
+    italic: false,
+    underline: false,
+    inverse: false,
+    strike: false,
+    fg: null,
+    bg: null,
+  };
+}
+
+function parseCodes(raw) {
+  if (raw === "") return { values: [0], separators: [null] };
+  const values = [];
+  const separators = [];
+  let separator = null;
+  for (const part of raw.split(/([;:])/)) {
+    if (part === ";" || part === ":") {
+      separator = part;
+      continue;
+    }
+    values.push(part === "" ? null : Number.parseInt(part, 10));
+    separators.push(separator);
+    separator = null;
+  }
+  return { values, separators };
+}
+
+function basicColor(code, base, brightBase, prefix) {
+  if (code >= base && code < base + COLOR_NAMES.length) return `${prefix}-${COLOR_NAMES[code - base]}`;
+  if (code >= brightBase && code < brightBase + COLOR_NAMES.length) {
+    return `${prefix}-bright-${COLOR_NAMES[code - brightBase]}`;
+  }
+  return null;
+}
+
+function rgbFrom256(index) {
+  if (index < 0 || index > 255) return null;
+  if (index < 16) {
+    const base = [
+      "#000000",
+      "#800000",
+      "#008000",
+      "#808000",
+      "#000080",
+      "#800080",
+      "#008080",
+      "#c0c0c0",
+      "#808080",
+      "#ff0000",
+      "#00ff00",
+      "#ffff00",
+      "#0000ff",
+      "#ff00ff",
+      "#00ffff",
+      "#ffffff",
+    ];
+    return base[index] ?? null;
+  }
+  if (index >= 232) {
+    const level = 8 + (index - 232) * 10;
+    return `rgb(${level}, ${level}, ${level})`;
+  }
+  const offset = index - 16;
+  const levels = [0, 95, 135, 175, 215, 255];
+  const r = levels[Math.floor(offset / 36) % 6] ?? 0;
+  const g = levels[Math.floor(offset / 6) % 6] ?? 0;
+  const b = levels[offset % 6] ?? 0;
+  return `rgb(${r}, ${g}, ${b})`;
+}
+
+function readExtendedColor(codes, separators, index) {
+  const mode = codes[index + 1];
+  if (mode === 5) return { color: rgbFrom256(codes[index + 2] ?? -1), next: index + 3 };
+  if (mode === 2) {
+    const offset = separators[index + 1] === ":" && codes[index + 5] !== undefined ? 3 : 2;
+    const [r, g, b] = [codes[index + offset], codes[index + offset + 1], codes[index + offset + 2]];
+    if ([r, g, b].every((value) => Number.isInteger(value) && value >= 0 && value <= 255)) {
+      return { color: `rgb(${r}, ${g}, ${b})`, next: index + offset + 3 };
+    }
+  }
+  return { color: null, next: index + 1 };
+}
+
+function applySgr(state, raw) {
+  const { values: codes, separators } = parseCodes(raw);
+  let nextState = { ...state };
+  for (let i = 0; i < codes.length; i += 1) {
+    const code = codes[i] ?? 0;
+    if (code === 0) nextState = createState();
+    else if (code === 1) nextState.bold = true;
+    else if (code === 2) nextState.dim = true;
+    else if (code === 3) nextState.italic = true;
+    else if (code === 4) nextState.underline = true;
+    else if (code === 7) nextState.inverse = true;
+    else if (code === 9) nextState.strike = true;
+    else if (code === 22) {
+      nextState.bold = false;
+      nextState.dim = false;
+    } else if (code === 23) nextState.italic = false;
+    else if (code === 24) nextState.underline = false;
+    else if (code === 27) nextState.inverse = false;
+    else if (code === 29) nextState.strike = false;
+    else if (code === 39) nextState.fg = null;
+    else if (code === 49) nextState.bg = null;
+    else if (code === 38 || code === 48) {
+      const extended = readExtendedColor(codes, separators, i);
+      if (code === 38) nextState.fg = extended.color;
+      else nextState.bg = extended.color;
+      i = extended.next - 1;
+    } else {
+      const fg = basicColor(code, 30, 90, "fg");
+      const bg = basicColor(code, 40, 100, "bg");
+      if (fg) nextState.fg = fg;
+      if (bg) nextState.bg = bg;
+    }
+  }
+  return nextState;
+}
+
+function spanAttributes(state) {
+  const classes = [];
+  const styles = [];
+  if (state.bold) classes.push("ansi-bold");
+  if (state.dim) classes.push("ansi-dim");
+  if (state.italic) classes.push("ansi-italic");
+  if (state.underline) classes.push("ansi-underline");
+  if (state.strike) classes.push("ansi-strike");
+  const effectiveFg = state.inverse ? state.bg || DEFAULT_TERMINAL_BACKGROUND : state.fg;
+  const effectiveBg = state.inverse ? state.fg || DEFAULT_TERMINAL_FOREGROUND : state.bg;
+  for (const [value, cssProperty, classPrefix] of [
+    [effectiveFg, "color", "fg-"],
+    [effectiveBg, "background-color", "bg-"],
+  ]) {
+    if (!value) continue;
+    const colorName = value.match(/^(?:fg|bg)-(.+)$/)?.[1];
+    if (colorName) classes.push(`ansi-${classPrefix}${colorName}`);
+    else styles.push(`${cssProperty}: ${value}`);
+  }
+  const attrs = [];
+  if (classes.length > 0) attrs.push(`class="${classes.join(" ")}"`);
+  if (styles.length > 0) attrs.push(`style="${styles.join("; ")}"`);
+  return attrs.join(" ");
+}
+
+function renderSegment(value, state) {
+  const escaped = escapeHtml(value);
+  const attrs = spanAttributes(state);
+  return attrs ? `<span ${attrs}>${escaped}</span>` : escaped;
+}
+
+export function renderAnsiToHtml(value) {
+  const cleanValue = value.replace(OSC_PATTERN, "");
+  let state = createState();
+  let cursor = 0;
+  let output = "";
+  for (const match of cleanValue.matchAll(SGR_PATTERN)) {
+    const index = match.index ?? 0;
+    if (index > cursor) output += renderSegment(cleanValue.slice(cursor, index), state);
+    state = applySgr(state, match[1] ?? "");
+    cursor = index + match[0].length;
+  }
+  if (cursor < cleanValue.length) output += renderSegment(cleanValue.slice(cursor), state);
+  return output.replace(ANSI_PATTERN, "");
+}
+
+export function ansiColorCss() {
+  return Object.entries(BASIC_ANSI_COLORS)
+    .map(([name, value]) => `.ansi-fg-${name} { color: ${value}; }\n.ansi-bg-${name} { background-color: ${value}; }`)
+    .join("\n");
+}

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

@@ -0,0 +1,264 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+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";
+
+const HELP = `web-terminal-visual-qa
+
+Render terminal/TUI evidence through a browser-capturable web page.
+
+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
+
+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.
+  --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.
+
+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.
+`;
+
+function parseArgs(argv) {
+  const args = {
+    cols: 140,
+    rows: 40,
+    dwellMs: 3000,
+    cwd: process.cwd(),
+    browser: true,
+    wrap: true,
+    redactions: [],
+    redactRegexes: [],
+  };
+  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;
+    }
+    const next = argv[i + 1];
+    if (!next) throw new Error(`missing value for ${arg}`);
+    i += 1;
+    if (arg === "--title") args.title = next;
+    else if (arg === "--from-file") args.fromFile = next;
+    else if (arg === "--command") args.command = next;
+    else if (arg === "--cwd") args.cwd = next;
+    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 === "--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 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");
+  if (args.fromFile && args.command) throw new Error("choose exactly one of --from-file or --command");
+  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" };
+}
+
+function shellQuote(value) {
+  return `'${value.replaceAll("'", "'\\''")}'`;
+}
+
+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);
+  const evidenceDir = resolve(args.evidenceDir);
+  mkdirSync(evidenceDir, { recursive: true });
+  const htmlPath = join(evidenceDir, "terminal.html");
+  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(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" };
+  const metadata = {
+    title: args.title,
+    connector: capture.connector,
+    browserCapture: browser.status,
+    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 },
+  };
+  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`);
+}
+
+try {
+  main();
+} catch (error) {
+  const message = error instanceof Error ? error.message : String(error);
+  process.stderr.write(`${message}\n`);
+  process.exit(1);
+}