haltija 1.1.21 → 1.2.3

package/dist/hj.js

@@ -0,0 +1,1600 @@
+#!/usr/bin/env bun
+import { createRequire } from "node:module";
+var __require = /* @__PURE__ */ createRequire(import.meta.url);
+
+// bin/cli-subcommand.mjs
+import { spawn } from "child_process";
+import { existsSync, readFileSync, readdirSync, statSync } from "fs";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+
+// bin/format-tree.mjs
+var MAX_TEXT_LEN = 80;
+function formatTree(node, indent = 0) {
+  if (!node)
+    return "";
+  const lines = [];
+  formatNode(node, indent, lines);
+  lines.push("---");
+  lines.push("hj tree --json");
+  return lines.join(`
+`);
+}
+function formatNode(node, indent, lines) {
+  if (!node)
+    return;
+  if (node.tag === "haltija-dev")
+    return;
+  const prefix = " ".repeat(indent);
+  const hasChildren = node.children && node.children.length > 0 || node.shadowChildren && node.shadowChildren.length > 0;
+  const line = buildLine(node);
+  if (hasChildren) {
+    lines.push(`${prefix}( ${line}`);
+    if (node.children) {
+      for (const child of node.children) {
+        formatNode(child, indent + 2, lines);
+      }
+    }
+    if (node.shadowChildren) {
+      for (const child of node.shadowChildren) {
+        if (child.classes && child.classes.includes("widget"))
+          continue;
+        formatNode(child, indent + 2, lines);
+      }
+    }
+    lines.push(`${prefix})`);
+  } else {
+    lines.push(`${prefix}${line}`);
+  }
+}
+function buildLine(node) {
+  const parts = [];
+  parts.push(node.ref || "?");
+  let tagPart = node.tag || "?";
+  if (node.id)
+    tagPart += `#${node.id}`;
+  if (node.classes && node.classes.length) {
+    tagPart += "." + node.classes.join(".");
+  }
+  parts.push(tagPart);
+  if (node.attrs) {
+    for (const [key, val] of Object.entries(node.attrs)) {
+      if (val === "" || val === "true") {
+        parts.push(key);
+      } else if (/\s/.test(val) || val.length > 40) {
+        parts.push(`${key}="${truncate(val, 40)}"`);
+      } else {
+        parts.push(`${key}=${val}`);
+      }
+    }
+  }
+  if (node.value !== undefined && node.value !== "") {
+    parts.push(`value="${truncate(node.value, 30)}"`);
+  }
+  if (node.checked !== undefined) {
+    parts.push(node.checked ? "checked" : "unchecked");
+  }
+  const flags = formatFlags(node.flags);
+  if (flags)
+    parts.push(flags);
+  if (node.text) {
+    parts.push(`"${truncate(node.text, MAX_TEXT_LEN)}"`);
+  }
+  if (node.truncated && node.childCount) {
+    parts.push(`(${node.childCount} children)`);
+  }
+  return parts.join(" ");
+}
+function formatFlags(flags) {
+  if (!flags)
+    return "";
+  const parts = [];
+  if (flags.interactive)
+    parts.push("interactive");
+  if (flags.disabled)
+    parts.push("disabled");
+  if (flags.required)
+    parts.push("required");
+  if (flags.readOnly)
+    parts.push("readonly");
+  if (flags.focused)
+    parts.push("focused");
+  if (flags.hidden && flags.hiddenReason) {
+    parts.push(`hidden:${flags.hiddenReason}`);
+  } else if (flags.hidden) {
+    parts.push("hidden");
+  }
+  if (flags.offScreen && !flags.hidden)
+    parts.push("offscreen");
+  if (flags.customElement)
+    parts.push("custom");
+  if (flags.hasAria)
+    parts.push("aria");
+  return parts.join(" ");
+}
+function truncate(str, max) {
+  if (!str)
+    return "";
+  if (str.length <= max)
+    return str;
+  return str.slice(0, max - 1) + "…";
+}
+
+// bin/format-events.mjs
+function formatEvents(response) {
+  const events = response?.events || response;
+  if (!events || !Array.isArray(events) || events.length === 0) {
+    return `(no events)
+---
+hj events --json`;
+  }
+  const lines = events.map((ev) => {
+    const parts = [];
+    parts.push(String(ev.timestamp));
+    parts.push(ev.type);
+    const target = formatTarget(ev.target);
+    if (target)
+      parts.push(target);
+    const summary = extractPayloadSummary(ev);
+    if (summary)
+      parts.push(summary);
+    return parts.join(" ");
+  });
+  const sinceTs = events[0].timestamp;
+  lines.push("---");
+  lines.push(`hj events --json --since=${sinceTs}`);
+  return lines.join(`
+`);
+}
+function formatTarget(target) {
+  if (!target)
+    return "";
+  let result = target.tag || "";
+  if (target.id) {
+    result += `#${target.id}`;
+  } else if (target.selector) {
+    return target.selector;
+  }
+  return result || "";
+}
+function extractPayloadSummary(ev) {
+  const { type, payload, target } = ev;
+  if (!payload && !target)
+    return "";
+  if (type === "input:typed") {
+    return quote(payload?.text || payload?.finalValue || "");
+  }
+  if (type === "interaction:click") {
+    return quote(payload?.text || target?.text || "");
+  }
+  if (type === "interaction:submit") {
+    return payload?.formAction || payload?.formId || "";
+  }
+  if (type?.startsWith("navigation:")) {
+    return payload?.to || payload?.url || "";
+  }
+  if (type?.startsWith("console:")) {
+    return quote(truncate2(payload?.message || "", 120));
+  }
+  if (type === "scroll:stop") {
+    return `${payload?.direction || ""} ${payload?.distance || 0}px`;
+  }
+  if (type === "hover:dwell") {
+    return `${payload?.duration || 0}ms`;
+  }
+  if (type === "mutation:change") {
+    const what = payload?.changeType || "";
+    const el = payload?.element || "";
+    return `${what} ${el}`.trim();
+  }
+  if (type === "focus:focus" || type === "focus:blur") {
+    return target?.text || target?.selector || "";
+  }
+  if (payload) {
+    for (const val of Object.values(payload)) {
+      if (typeof val === "string" && val.length > 0 && val.length < 200) {
+        return quote(truncate2(val, 80));
+      }
+    }
+  }
+  return "";
+}
+function quote(s) {
+  if (!s)
+    return "";
+  return `"${s}"`;
+}
+function truncate2(str, max) {
+  if (!str || str.length <= max)
+    return str;
+  return str.slice(0, max - 1) + "…";
+}
+
+// bin/format-test.mjs
+function formatTestResult(result) {
+  if (!result)
+    return `(no result)
+---
+hj test-run --json`;
+  const lines = [];
+  const status = result.passed ? "ok" : "FAIL";
+  const name = result.test || "unnamed";
+  const duration = result.duration ? `${result.duration}ms` : "";
+  const counts = result.summary ? `${result.summary.passed}/${result.summary.total}` : "";
+  lines.push([status, name, duration, counts].filter(Boolean).join(" "));
+  if (result.steps) {
+    for (const step of result.steps) {
+      const stepStatus = step.passed ? "ok" : step.error === "skipped" ? "skip" : "FAIL";
+      const desc = formatStepDescription(step);
+      const dur = step.duration ? `${step.duration}ms` : "";
+      const err = !step.passed && step.error && step.error !== "skipped" ? step.error : "";
+      lines.push(`  ${step.index + 1} ${[stepStatus, desc, dur, err].filter(Boolean).join(" ")}`);
+      if (!step.passed && step.context) {
+        const detail = formatFailureContext(step.context);
+        if (detail)
+          lines.push(`    > ${detail}`);
+      }
+    }
+  }
+  if (result.patience) {
+    const p = result.patience;
+    lines.push(`  patience ${p.remaining}/${p.allowed} remaining streak=${p.consecutiveFailures}/${p.streak} timeout=${p.finalTimeoutMs}ms`);
+  }
+  lines.push("---");
+  lines.push("hj test-run --json");
+  return lines.join(`
+`);
+}
+function formatSuiteResult(result) {
+  if (!result)
+    return `(no result)
+---
+hj test-run --json`;
+  const lines = [];
+  const status = result.summary?.failed === 0 ? "ok" : "FAIL";
+  const duration = result.duration ? `${result.duration}ms` : "";
+  const counts = result.summary ? `${result.summary.passed}/${result.summary.total} tests` : "";
+  lines.push([status, "suite", duration, counts].filter(Boolean).join(" "));
+  if (result.results) {
+    for (const testResult of result.results) {
+      const tStatus = testResult.passed ? "ok" : "FAIL";
+      const name = testResult.test || "unnamed";
+      const dur = testResult.duration ? `${testResult.duration}ms` : "";
+      const tCounts = testResult.summary ? `${testResult.summary.passed}/${testResult.summary.total}` : "";
+      lines.push(`  ${[tStatus, name, dur, tCounts].filter(Boolean).join(" ")}`);
+      if (!testResult.passed && testResult.steps) {
+        const failed = testResult.steps.find((s) => !s.passed);
+        if (failed) {
+          const desc = formatStepDescription(failed);
+          const err = failed.error || "";
+          lines.push(`    step ${failed.index + 1}: ${[desc, err].filter(Boolean).join(" ")}`);
+          if (failed.context) {
+            const detail = formatFailureContext(failed.context);
+            if (detail)
+              lines.push(`    > ${detail}`);
+          }
+        }
+      }
+    }
+  }
+  lines.push("---");
+  lines.push("hj test-run --json");
+  return lines.join(`
+`);
+}
+function formatStepDescription(step) {
+  const s = step.step || step;
+  const action = s.action || step.description || "";
+  switch (action) {
+    case "navigate":
+      return `navigate ${s.url || ""}`;
+    case "click":
+      return `click ${s.selector || s.ref || ""}`;
+    case "type":
+      return `type ${s.selector || s.ref || ""} "${truncate3(s.text || "", 30)}"`;
+    case "key":
+      return `key ${s.key || ""}`;
+    case "wait":
+      return `wait ${s.selector || s.url || (s.forWindow ? "new window" : "") || (s.duration != null ? s.duration + "ms" : "") || ""}`;
+    case "assert": {
+      const a = s.assertion || {};
+      const sel = a.selector || "";
+      const val = a.text || a.value || a.pattern || "";
+      return `assert ${a.type || ""} ${sel} ${val ? '"' + truncate3(val, 30) + '"' : ""}`.trim();
+    }
+    case "check":
+      return `check ${s.selector || ""}`;
+    case "eval":
+      return `eval ${truncate3(s.code || "", 40)}`;
+    case "verify":
+      return `verify ${truncate3(s.eval || "", 40)}`;
+    case "tabs-open":
+      return `tabs-open ${s.url || ""}`;
+    case "tabs-close":
+      return `tabs-close ${s.window || ""}`;
+    case "tabs-focus":
+      return `tabs-focus ${s.window || ""}`;
+    default:
+      return step.description || action || "unknown";
+  }
+}
+function formatFailureContext(context) {
+  const parts = [];
+  if (context.reason) {
+    parts.push(context.reason);
+  }
+  if (context.buttonsOnPage?.length) {
+    parts.push(`page shows: [${context.buttonsOnPage.join(", ")}]`);
+  }
+  if (context.actual !== undefined && context.expected !== undefined) {
+    parts.push(`expected "${context.expected}" got "${context.actual}"`);
+  }
+  if (context.suggestion) {
+    parts.push(context.suggestion);
+  }
+  return parts.join(", ");
+}
+function truncate3(str, max) {
+  if (!str || str.length <= max)
+    return str;
+  return str.slice(0, max - 1) + "…";
+}
+
+// bin/test-data.mjs
+function xorshift32(state) {
+  let s = state | 0;
+  s ^= s << 13;
+  s ^= s >>> 17;
+  s ^= s << 5;
+  return [s >>> 0, s >>> 0];
+}
+
+class SeededRandom {
+  constructor(seed) {
+    this.state = (seed === 0 ? 1 : seed) >>> 0;
+  }
+  next() {
+    const [value, newState] = xorshift32(this.state);
+    this.state = newState;
+    return value / 4294967296;
+  }
+  int(min, max) {
+    return min + Math.floor(this.next() * (max - min + 1));
+  }
+  pick(arr) {
+    return arr[this.int(0, arr.length - 1)];
+  }
+  hex(len) {
+    let s = "";
+    for (let i = 0;i < len; i++)
+      s += this.int(0, 15).toString(16);
+    return s;
+  }
+}
+var FIRST_NAMES = [
+  "Tessia",
+  "Testopher",
+  "Testina",
+  "Qadir",
+  "Qaleen",
+  "Checkov",
+  "Validia",
+  "Assertia",
+  "Debugson",
+  "Mockwell",
+  "Fixturia",
+  "Stubson",
+  "Spectra",
+  "Suitewell",
+  "Runley",
+  "Passandra",
+  "Failsworth",
+  "Edgeworth",
+  "Boundara",
+  "Flaxton"
+];
+var WORDS = [
+  "quick",
+  "brown",
+  "fox",
+  "lazy",
+  "dog",
+  "test",
+  "data",
+  "jumps",
+  "over",
+  "fence",
+  "under",
+  "bridge",
+  "through",
+  "forest",
+  "around",
+  "mountain",
+  "beside",
+  "river",
+  "across",
+  "valley",
+  "between",
+  "clouds",
+  "above",
+  "ocean",
+  "below"
+];
+var COMPANIES = [
+  "Haltija Test Corp",
+  "QA Industries",
+  "Assertion Labs",
+  "Testify Inc",
+  "Validate Co",
+  "Fixture Holdings",
+  "Mock & Sons",
+  "Spec Systems",
+  "Check Group",
+  "Edge Corp"
+];
+var STREETS = [
+  "Test Avenue",
+  "QA Boulevard",
+  "Assertion Lane",
+  "Validate Street",
+  "Debug Drive",
+  "Fixture Road",
+  "Mock Court",
+  "Spec Way",
+  "Check Circle",
+  "Edge Parkway",
+  "Suite Plaza",
+  "Run Terrace"
+];
+var CITIES = [
+  "Testville",
+  "QA City",
+  "Assertonia",
+  "Validateburg",
+  "Debugton",
+  "Mockford",
+  "Specburgh",
+  "Fixtureopolis"
+];
+var EVIL_XSS = [
+  `<script>alert('xss')</script>`,
+  `"><img src=x onerror=alert('xss')>`,
+  `'><svg/onload=alert('xss')>`,
+  `javascript:alert('xss')`,
+  `<img src="x" onerror="alert(document.cookie)">`,
+  `<div onmouseover="alert('xss')">hover me</div>`,
+  `<script>alert('xss')</script>`,
+  `<iframe src="javascript:alert('xss')"></iframe>`,
+  `<body onload=alert('xss')>`,
+  `<input onfocus=alert('xss') autofocus>`
+];
+var EVIL_SQL = [
+  `'; DROP TABLE users; --`,
+  `1 OR 1=1`,
+  `' UNION SELECT * FROM users --`,
+  `1; UPDATE users SET role='admin' WHERE 1=1; --`,
+  `' OR '1'='1`,
+  `'; EXEC xp_cmdshell('whoami'); --`,
+  `1' AND (SELECT COUNT(*) FROM users) > 0 --`,
+  `admin'--`,
+  `' OR 1=1 LIMIT 1 --`,
+  `'; INSERT INTO log VALUES('pwned'); --`
+];
+var EVIL_UNICODE = [
+  "​‌‍\uFEFF",
+  "‮Reverse",
+  "АВС",
+  "À́̂̃̄",
+  "���",
+  "\u2028\u2029",
+  "\x00\x01\x02",
+  "\uD800",
+  "a͏a",
+  "‏‎"
+];
+var EVIL_EMOJI = [
+  "\uD83D\uDC68‍\uD83D\uDC69‍\uD83D\uDC67‍\uD83D\uDC66",
+  "\uD83D\uDC4B\uD83C\uDFFD",
+  "\uD83C\uDDFA\uD83C\uDDF8",
+  "\uD83D\uDC68‍\uD83D\uDCBB",
+  "\uD83C\uDFF3️‍\uD83C\uDF08",
+  "\uD83E\uDDD1‍\uD83E\uDDD1‍\uD83E\uDDD2",
+  "\uD83D\uDE00\uD83D\uDE01\uD83D\uDE02\uD83D\uDE03\uD83D\uDE04",
+  "#️⃣",
+  "\uD83E\uDEE0",
+  "\uD83D\uDE00\uD83D\uDE01\uD83D\uDE02\uD83E\uDD23\uD83D\uDE03\uD83D\uDE04\uD83D\uDE05\uD83D\uDE06\uD83D\uDE07\uD83E\uDD70"
+];
+var EVIL_WHITESPACE = [
+  ` 	
+\r\v\f`,
+  "      ",
+  "      ",
+  "　",
+  `\r
+\r
+
+\r`,
+  "\t\t\t\t\t\t\t\t",
+  "     ",
+  "  ",
+  "   ​   ",
+  "᠎⁠"
+];
+var EVIL_NULL = [
+  "null",
+  "undefined",
+  "NaN",
+  "Infinity",
+  "-Infinity",
+  "true",
+  "false",
+  "0",
+  "-0",
+  "",
+  "None",
+  "nil",
+  "NULL",
+  "void",
+  "[object Object]"
+];
+var EVIL_PATH = [
+  "../../etc/passwd",
+  "C:\\windows\\system32\\config\\sam",
+  "/dev/null",
+  "..\\..\\..\\windows\\system32",
+  "file:///etc/passwd",
+  "\\\\server\\share\\file",
+  "/proc/self/environ",
+  "CON",
+  "PRN",
+  "AUX",
+  "NUL"
+];
+var EVIL_FORMAT = [
+  "%s%s%s%s%s%s%s%s%s%s",
+  "${7*7}",
+  '{{constructor.constructor("return this")()}}',
+  "#{7*7}",
+  "<%= 7*7 %>",
+  "{{7*7}}",
+  "${toString}",
+  "$(whoami)",
+  "`whoami`",
+  "{${<%[%'\"}}%\\."
+];
+var ALIASES = {
+  "NAME.FIRST": "PERSON.FIRST",
+  "NAME.LAST": "PERSON.LAST",
+  "NAME.FULL": "PERSON.FULL",
+  NAME: "PERSON.FULL",
+  "TEXT.SENTENCE": "TEXT",
+  WORD: "TEXT.SHORT",
+  INT: "NUMBER",
+  "ADDRESS.POSTAL": "ADDRESS.ZIP"
+};
+function createTestDataGenerator(seed) {
+  const actualSeed = seed ?? (Date.now() ^ Math.random() * 4294967296) >>> 0;
+  const rng = new SeededRandom(actualSeed);
+  const tag = rng.hex(4);
+  const cache = new Map;
+  function canonicalize(type) {
+    const upper = type.toUpperCase();
+    return ALIASES[upper] ?? upper;
+  }
+  function generate(type) {
+    const key = canonicalize(type);
+    if (cache.has(key))
+      return cache.get(key);
+    const value = generateFresh(key);
+    cache.set(key, value);
+    return value;
+  }
+  function generateFresh(upper) {
+    if (upper === "PERSON.FIRST")
+      return rng.pick(FIRST_NAMES);
+    if (upper === "PERSON.LAST")
+      return `Haltija-${tag}`;
+    if (upper === "PERSON.FULL")
+      return `${generate("PERSON.FIRST")} ${generate("PERSON.LAST")}`;
+    if (upper === "EMAIL")
+      return `${generate("PERSON.FIRST").toLowerCase()}.${tag}@haltija-test.example`;
+    if (upper === "PHONE")
+      return `+1-555-0${rng.int(100, 199)}`;
+    if (upper === "USERNAME")
+      return `test_${generate("PERSON.FIRST").toLowerCase()}_${tag}`;
+    if (upper === "PASSWORD")
+      return `Test!Pass#${tag}${rng.hex(2)}`;
+    if (upper === "TEXT") {
+      const len = rng.int(5, 10);
+      const words = Array.from({ length: len }, () => rng.pick(WORDS));
+      words[0] = words[0][0].toUpperCase() + words[0].slice(1);
+      return words.join(" ") + ".";
+    }
+    if (upper === "TEXT.SHORT")
+      return rng.pick(WORDS);
+    if (upper === "TEXT.PARAGRAPH") {
+      return Array.from({ length: rng.int(3, 6) }, () => generateFresh("TEXT")).join(" ");
+    }
+    if (upper === "NUMBER")
+      return String(rng.int(1, 9999));
+    const rangeMatch = upper.match(/^NUMBER\.RANGE\((\d+),\s*(\d+)\)$/);
+    if (rangeMatch)
+      return String(rng.int(parseInt(rangeMatch[1]), parseInt(rangeMatch[2])));
+    if (upper === "UUID")
+      return `hj-${rng.hex(8)}-${rng.hex(4)}-${rng.hex(4)}-${rng.hex(4)}-${rng.hex(12)}`;
+    if (upper === "DATE") {
+      const y = rng.int(2024, 2026), m = rng.int(1, 12), d = rng.int(1, 28);
+      return `${y}-${String(m).padStart(2, "0")}-${String(d).padStart(2, "0")}`;
+    }
+    if (upper === "DATE.FUTURE")
+      return new Date(Date.now() + rng.int(1, 365) * 86400000).toISOString().slice(0, 10);
+    if (upper === "DATE.PAST")
+      return new Date(Date.now() - rng.int(1, 365) * 86400000).toISOString().slice(0, 10);
+    if (upper === "URL")
+      return `https://haltija-test.example/${tag}`;
+    if (upper === "COMPANY")
+      return `${rng.pick(COMPANIES)} ${tag}`;
+    if (upper === "ADDRESS.STREET")
+      return `${rng.int(1, 9999)} ${rng.pick(STREETS)}`;
+    if (upper === "ADDRESS.CITY")
+      return rng.pick(CITIES);
+    if (upper === "ADDRESS.ZIP")
+      return `555${String(rng.int(0, 99)).padStart(2, "0")}`;
+    if (upper === "ADDRESS.FULL")
+      return `${generateFresh("ADDRESS.STREET")}, ${generateFresh("ADDRESS.CITY")} ${generateFresh("ADDRESS.ZIP")}`;
+    if (upper === "EVIL.XSS")
+      return rng.pick(EVIL_XSS);
+    if (upper === "EVIL.SQL")
+      return rng.pick(EVIL_SQL);
+    if (upper === "EVIL.UNICODE")
+      return rng.pick(EVIL_UNICODE);
+    if (upper === "EVIL.EMOJI")
+      return rng.pick(EVIL_EMOJI);
+    if (upper === "EVIL.WHITESPACE")
+      return rng.pick(EVIL_WHITESPACE);
+    if (upper === "EVIL.LONG")
+      return "A".repeat(1e4);
+    if (upper === "EVIL.EMPTY")
+      return "";
+    if (upper === "EVIL.NULL")
+      return rng.pick(EVIL_NULL);
+    if (upper === "EVIL.PATH")
+      return rng.pick(EVIL_PATH);
+    if (upper === "EVIL.FORMAT")
+      return rng.pick(EVIL_FORMAT);
+    if (upper === "EVIL") {
+      const cats = ["XSS", "SQL", "UNICODE", "EMOJI", "WHITESPACE", "NULL", "PATH", "FORMAT"];
+      return generateFresh(`EVIL.${rng.pick(cats)}`);
+    }
+    return `[unknown:${upper}]`;
+  }
+  return { generate, seed: actualSeed };
+}
+function substituteGeneratedVars(text, seed) {
+  const gen = createTestDataGenerator(seed);
+  const generated = {};
+  const result = text.replace(/\$\{GEN\.([^}]+)\}/g, (_match, type) => {
+    const value = gen.generate(type.trim());
+    generated[`GEN.${type.trim()}`] = value;
+    return value;
+  });
+  return { result, seed: gen.seed, generated };
+}
+
+// bin/cli-subcommand.mjs
+var __dirname2 = dirname(fileURLToPath(import.meta.url));
+var hintsPath = join(__dirname2, "hints.json");
+var COMMAND_HINTS = existsSync(hintsPath) ? JSON.parse(readFileSync(hintsPath, "utf-8")) : {};
+var GET_ENDPOINTS = new Set([
+  "location",
+  "events",
+  "console",
+  "windows",
+  "recordings",
+  "status",
+  "version",
+  "docs",
+  "api",
+  "stats"
+]);
+var COMPOUND_PATHS = {
+  styles: "/inspect",
+  "mutations-watch": "/mutations/watch",
+  "mutations-unwatch": "/mutations/unwatch",
+  "mutations-status": "/mutations/status",
+  "events-watch": "/events/watch",
+  "events-unwatch": "/events/unwatch",
+  "events-stats": "/events/stats",
+  "select-start": "/select/start",
+  "select-cancel": "/select/cancel",
+  "select-status": "/select/status",
+  "select-result": "/select/result",
+  "select-clear": "/select/clear",
+  "tabs-open": "/tabs/open",
+  "tabs-close": "/tabs/close",
+  "tabs-focus": "/tabs/focus",
+  "video-start": "/video/start",
+  "video-stop": "/video/stop",
+  "video-status": "/video/status",
+  "recording-start": "/recording/start",
+  "recording-stop": "/recording/stop",
+  "recording-generate": "/recording/generate",
+  "test-run": "/test/run",
+  "test-suite": "/test/suite",
+  "test-validate": "/test/validate",
+  "send-message": "/send/message",
+  "send-selection": "/send/selection",
+  "send-recording": "/send/recording"
+};
+var GET_COMPOUND = new Set([
+  "mutations-status",
+  "events-stats",
+  "select-status",
+  "select-result",
+  "video-status"
+]);
+var ARG_MAPS = {
+  click: (args) => parseClickArgs(args),
+  type: (args) => ({ ...parseTargetArgs(args.slice(0, 1)), text: args.slice(1).join(" ") }),
+  key: (args) => ({ key: args[0], ...parseModifiers(args.slice(1)) }),
+  drag: (args) => ({ ...parseTargetArgs(args.slice(0, 1)), deltaX: num(args[1]), deltaY: num(args[2]) }),
+  scroll: (args) => parseScrollArgs(args),
+  navigate: (args) => ({ url: args[0] }),
+  eval: (args) => ({ code: args.join(" ") }),
+  query: (args) => ({ selector: args[0] }),
+  inspect: (args) => parseInspectArgs(args),
+  inspectAll: (args) => parseInspectArgs(args),
+  styles: (args) => ({ ...parseTargetArgs(args), matchedRules: true }),
+  tree: (args) => parseTreeArgs(args),
+  highlight: (args) => ({ ...parseTargetArgs(args.slice(0, 1)), label: args[1] }),
+  unhighlight: () => ({}),
+  find: (args) => ({ text: args.join(" ") }),
+  wait: (args) => parseWaitArgs(args),
+  call: (args) => ({ ...parseTargetArgs(args.slice(0, 1)), method: args[1], args: args.slice(2).map(tryParseJSON) }),
+  fetch: (args) => ({ url: args[0], prompt: args.slice(1).join(" ") || undefined }),
+  screenshot: (args) => {
+    const dataUrl = args.includes("--data-url");
+    const filtered = args.filter((a) => a !== "--data-url");
+    return { ...parseTargetArgs(filtered), file: !dataUrl };
+  },
+  snapshot: (args) => ({ context: args.join(" ") || undefined }),
+  select: (args) => ({ action: args[0] }),
+  "select-start": () => ({}),
+  "select-cancel": () => ({}),
+  "select-clear": () => ({}),
+  refresh: (args) => args.includes("--soft") ? { soft: true } : {},
+  "tabs-open": (args) => ({ url: args[0] }),
+  "tabs-close": (args) => ({ window: args[0] }),
+  "tabs-focus": (args) => ({ window: args[0] }),
+  "video-start": (args) => {
+    const body = {};
+    for (let i = 0;i < args.length; i++) {
+      if (args[i] === "--maxDuration" || args[i] === "--max-duration")
+        body.maxDuration = num(args[++i]);
+    }
+    return body;
+  },
+  "video-stop": () => ({}),
+  "events-watch": (args) => ({ preset: args[0] || "interactive" }),
+  "mutations-watch": (args) => ({ preset: args[0] || "smart" }),
+  form: (args) => parseTargetArgs(args),
+  "test-run": (args) => {
+    if (!args.length) {
+      console.error("Usage: hj test-run <file.json> [--vars JSON] [--seed N] [--timeoutMs N] [--allow-failures N]");
+      process.exit(1);
+    }
+    const { files, options, vars } = parseTestArgs(args);
+    if (!files.length) {
+      console.error("Usage: hj test-run <file.json>");
+      process.exit(1);
+    }
+    const { seed, ...restOptions } = options;
+    return { ...readTestFile(files[0], vars, seed), ...restOptions };
+  },
+  "test-validate": (args) => {
+    if (!args.length) {
+      console.error("Usage: hj test-validate <file.json> [--vars JSON]");
+      process.exit(1);
+    }
+    const { files, vars, options } = parseTestArgs(args);
+    if (!files.length) {
+      console.error("Usage: hj test-validate <file.json>");
+      process.exit(1);
+    }
+    return readTestFile(files[0], vars, options.seed);
+  },
+  "test-suite": (args) => {
+    if (!args.length) {
+      console.error("Usage: hj test-suite <dir|file...> [--vars JSON] [--seed N] [--timeoutMs N] [--allow-failures N]");
+      process.exit(1);
+    }
+    const { files: rawFiles, options, vars } = parseTestArgs(args);
+    const files = expandTestFiles(rawFiles);
+    if (!files.length) {
+      console.error("Error: No test files found");
+      process.exit(1);
+    }
+    const { seed, ...restOptions } = options;
+    const tests = files.map((f) => readTestFile(f, vars, seed).test);
+    return { tests, ...restOptions };
+  },
+  "send-message": (args) => {
+    const noSubmit = args.includes("--no-submit");
+    const filtered = args.filter((a) => a !== "--no-submit");
+    return { agent: filtered[0], message: filtered.slice(1).join(" "), submit: !noSubmit };
+  },
+  "send-selection": (args) => {
+    const noSubmit = args.includes("--no-submit");
+    const filtered = args.filter((a) => a !== "--no-submit");
+    return { agent: filtered[0], submit: !noSubmit };
+  },
+  "send-recording": (args) => {
+    const noSubmit = args.includes("--no-submit");
+    const filtered = args.filter((a) => a !== "--no-submit");
+    return { agent: filtered[0], description: filtered.slice(1).join(" ") || undefined, submit: !noSubmit };
+  },
+  recording: (args) => {
+    const action = args[0] || "status";
+    if (action === "replay") {
+      return { action, id: args[1] };
+    }
+    if (action === "generate" || action === "start") {
+      return { action, name: args.slice(1).join(" ") || undefined };
+    }
+    return { action };
+  }
+};
+function parseTargetArgs(args) {
+  if (!args.length || !args[0])
+    return {};
+  const target = args[0];
+  if (/^@?\d+$/.test(target))
+    return { ref: target.replace("@", "") };
+  return { selector: target };
+}
+function parseTreeArgs(args) {
+  const body = {};
+  for (let i = 0;i < args.length; i++) {
+    const a = args[i];
+    if (a === "--depth" || a === "-d") {
+      body.depth = num(args[++i]);
+      continue;
+    }
+    if (a === "--selector" || a === "-s") {
+      body.selector = args[++i];
+      continue;
+    }
+    if (a === "--compact" || a === "-c") {
+      body.compact = true;
+      continue;
+    }
+    if (a === "--visible") {
+      body.visibleOnly = true;
+      continue;
+    }
+    if (a === "--text") {
+      body.includeText = true;
+      continue;
+    }
+    if (a === "--no-text") {
+      body.includeText = false;
+      continue;
+    }
+    if (a === "--shadow") {
+      body.pierceShadow = true;
+      continue;
+    }
+    if (a === "--frames") {
+      body.pierceFrames = true;
+      continue;
+    }
+    if (a === "--no-frames") {
+      body.pierceFrames = false;
+      continue;
+    }
+    if (!a.startsWith("-")) {
+      body.selector = a;
+      continue;
+    }
+  }
+  return Object.keys(body).length ? body : undefined;
+}
+function parseScrollArgs(args) {
+  if (!args.length)
+    return {};
+  const first = args[0];
+  if (first.startsWith(".") || first.startsWith("#") || first.startsWith("[")) {
+    return { selector: first };
+  }
+  if (args.length >= 2 && !isNaN(args[0]) && !isNaN(args[1])) {
+    return { deltaX: num(args[0]), deltaY: num(args[1]) };
+  }
+  if (!isNaN(first))
+    return { deltaY: num(first) };
+  return parseTargetArgs(args);
+}
+function parseWaitArgs(args) {
+  if (!args.length)
+    return { ms: 1000 };
+  const first = args[0];
+  if (!isNaN(first))
+    return { ms: num(first) };
+  return { ...parseTargetArgs([first]), timeout: args[1] ? num(args[1]) : undefined };
+}
+function parseClickArgs(args) {
+  const body = {};
+  const positional = [];
+  for (let i = 0;i < args.length; i++) {
+    const a = args[i];
+    if (a === "--diff") {
+      body.diff = true;
+      continue;
+    }
+    if (a === "--delay" && args[i + 1]) {
+      body.diffDelay = num(args[++i]);
+      continue;
+    }
+    if (!a.startsWith("-")) {
+      positional.push(a);
+      continue;
+    }
+  }
+  if (positional.length) {
+    const target = positional[0];
+    if (/^@?\d+$/.test(target)) {
+      body.ref = target.replace("@", "");
+    } else {
+      body.selector = target;
+    }
+  }
+  return Object.keys(body).length ? body : {};
+}
+function parseInspectArgs(args) {
+  const body = {};
+  const positional = [];
+  for (let i = 0;i < args.length; i++) {
+    const a = args[i];
+    if (a === "--full-styles" || a === "--styles") {
+      body.fullStyles = true;
+      continue;
+    }
+    if (a === "--matched-rules" || a === "--rules") {
+      body.matchedRules = true;
+      continue;
+    }
+    if (a === "--ancestors") {
+      body.ancestors = true;
+      continue;
+    }
+    if (!a.startsWith("-")) {
+      positional.push(a);
+      continue;
+    }
+  }
+  if (positional.length) {
+    const target = positional[0];
+    if (/^@?\d+$/.test(target)) {
+      body.ref = target.replace("@", "");
+    } else {
+      body.selector = target;
+    }
+  }
+  return Object.keys(body).length ? body : undefined;
+}
+function parseModifiers(args) {
+  const mods = {};
+  for (const a of args) {
+    if (a === "--ctrl" || a === "-c")
+      mods.ctrl = true;
+    if (a === "--shift" || a === "-s")
+      mods.shift = true;
+    if (a === "--alt" || a === "-a")
+      mods.alt = true;
+    if (a === "--meta" || a === "-m")
+      mods.meta = true;
+  }
+  return Object.keys(mods).length ? mods : {};
+}
+function substituteVars(text, vars = {}, seed) {
+  let genInfo = null;
+  if (/\$\{GEN\./i.test(text)) {
+    genInfo = substituteGeneratedVars(text, seed);
+    text = genInfo.result;
+  }
+  const result = text.replace(/\$\{([^}]+)\}/g, (match, varName) => {
+    const trimmed = varName.trim();
+    if (trimmed in vars)
+      return vars[trimmed];
+    if (trimmed in process.env)
+      return process.env[trimmed];
+    return match;
+  });
+  return { text: result, genInfo };
+}
+function readTestFile(filePath, vars = {}, seed) {
+  if (!existsSync(filePath)) {
+    console.error(`Error: File not found: ${filePath}`);
+    process.exit(1);
+  }
+  try {
+    const content = readFileSync(filePath, "utf-8");
+    const { text: processed, genInfo } = substituteVars(content, vars, seed);
+    if (genInfo && Object.keys(genInfo.generated).length > 0) {
+      const dim = (s) => `\x1B[2m${s}\x1B[0m`;
+      console.error(dim(`[test-data] seed: ${genInfo.seed}`));
+      for (const [key, value] of Object.entries(genInfo.generated)) {
+        const display = value.length > 60 ? value.slice(0, 57) + "..." : value;
+        console.error(dim(`  ${key} = ${JSON.stringify(display)}`));
+      }
+    }
+    const parsed = JSON.parse(processed);
+    return { test: parsed };
+  } catch (err) {
+    console.error(`Error: Failed to parse ${filePath}: ${err.message}`);
+    process.exit(1);
+  }
+}
+function parseTestArgs(args) {
+  const files = [];
+  const options = {};
+  let vars = {};
+  let i = 0;
+  while (i < args.length) {
+    const arg = args[i];
+    if (arg === "--timeoutMs" && args[i + 1]) {
+      options.timeout = parseInt(args[i + 1], 10);
+      i += 2;
+    } else if (arg === "--allow-failures" && args[i + 1]) {
+      options.patience = parseInt(args[i + 1], 10);
+      i += 2;
+    } else if (arg === "--allow-failures-streak" && args[i + 1]) {
+      options.patienceStreak = parseInt(args[i + 1], 10);
+      i += 2;
+    } else if (arg === "--step-delay" && args[i + 1]) {
+      options.stepDelay = parseInt(args[i + 1], 10);
+      i += 2;
+    } else if (arg === "--seed" && args[i + 1]) {
+      options.seed = parseInt(args[i + 1], 10);
+      i += 2;
+    } else if (arg === "--vars" && args[i + 1]) {
+      try {
+        vars = { ...vars, ...JSON.parse(args[i + 1]) };
+      } catch (err) {
+        console.error(`Error: Invalid JSON for --vars: ${args[i + 1]}`);
+        process.exit(1);
+      }
+      i += 2;
+    } else if (arg.startsWith("--")) {
+      i++;
+    } else {
+      files.push(arg);
+      i++;
+    }
+  }
+  return { files, options, vars };
+}
+function expandTestFiles(args) {
+  const files = [];
+  for (const arg of args) {
+    if (!existsSync(arg)) {
+      console.error(`Error: Not found: ${arg}`);
+      process.exit(1);
+    }
+    const stat = statSync(arg);
+    if (stat.isDirectory()) {
+      const jsonFiles = readdirSync(arg).filter((f) => f.endsWith(".json")).sort().map((f) => join(arg, f));
+      files.push(...jsonFiles);
+    } else {
+      files.push(arg);
+    }
+  }
+  return files;
+}
+function num(s) {
+  return s != null ? Number(s) : undefined;
+}
+function tryParseJSON(s) {
+  try {
+    return JSON.parse(s);
+  } catch {
+    return s;
+  }
+}
+function clean(obj) {
+  if (!obj)
+    return;
+  const result = {};
+  for (const [k, v] of Object.entries(obj)) {
+    if (v !== undefined)
+      result[k] = v;
+  }
+  return Object.keys(result).length ? result : undefined;
+}
+async function isServerRunning(port) {
+  try {
+    const resp = await fetch(`http://localhost:${port}/status`, {
+      signal: AbortSignal.timeout(1000)
+    });
+    return resp.ok;
+  } catch {
+    return false;
+  }
+}
+function resolveServerPath() {
+  const arch = process.arch === "arm64" ? "arm64" : "x64";
+  const execDir = dirname(process.execPath);
+  const bundledServerPath = join(execDir, `haltija-server-${arch}`);
+  const devServerPath = join(__dirname2, "../dist/server.js");
+  if (existsSync(bundledServerPath)) {
+    return { type: "bundled", path: bundledServerPath };
+  } else if (existsSync(devServerPath)) {
+    return { type: "dev", path: devServerPath };
+  }
+  return null;
+}
+async function startServerInBackground(port) {
+  const resolved = resolveServerPath();
+  if (!resolved) {
+    console.error("Error: Server not found. Run `bun run build` first.");
+    process.exit(1);
+  }
+  let command, cmdArgs;
+  if (resolved.type === "bundled") {
+    command = resolved.path;
+    cmdArgs = [];
+  } else {
+    command = "bun";
+    cmdArgs = ["run", resolved.path];
+    try {
+      const { execSync } = await import("child_process");
+      execSync("bun --version", { stdio: "ignore" });
+    } catch {
+      command = "node";
+      cmdArgs = [resolved.path];
+    }
+  }
+  const child = spawn(command, cmdArgs, {
+    env: { ...process.env, DEV_CHANNEL_PORT: String(port) },
+    stdio: "ignore",
+    detached: true
+  });
+  child.unref();
+  const maxWait = 5000;
+  const start = Date.now();
+  while (Date.now() - start < maxWait) {
+    if (await isServerRunning(port))
+      return true;
+    await new Promise((r) => setTimeout(r, 200));
+  }
+  return false;
+}
+async function runSubcommand(subcommand, subArgs, port = "8700") {
+  const baseUrl = `http://localhost:${port}`;
+  const jsonOutput = subArgs.includes("--json");
+  let filteredArgs = subArgs.filter((a) => a !== "--json");
+  let targetWindowId = undefined;
+  const windowIdx = filteredArgs.indexOf("--window");
+  if (windowIdx !== -1) {
+    targetWindowId = filteredArgs[windowIdx + 1];
+    filteredArgs = [...filteredArgs.slice(0, windowIdx), ...filteredArgs.slice(windowIdx + 2)];
+  }
+  if (!await isServerRunning(port)) {
+    process.stderr.write("\x1B[2mStarting Haltija server...\x1B[0m");
+    const started = await startServerInBackground(port);
+    if (started) {
+      process.stderr.write(`\x1B[2m done\x1B[0m
+`);
+    } else {
+      process.stderr.write(`
+`);
+      console.error("Error: Could not start server. Run `haltija --server` in another terminal.");
+      process.exit(1);
+    }
+  }
+  if (subcommand === "send") {
+    const firstArg = filteredArgs[0]?.toLocaleLowerCase();
+    if (firstArg === "selection") {
+      subcommand = "send-selection";
+      filteredArgs.shift();
+    } else if (firstArg === "recording") {
+      subcommand = "send-recording";
+      filteredArgs.shift();
+    } else {
+      subcommand = "send-message";
+    }
+  }
+  const path = COMPOUND_PATHS[subcommand] || `/${subcommand}`;
+  const isGet = GET_ENDPOINTS.has(subcommand) || GET_COMPOUND.has(subcommand);
+  let body = undefined;
+  if (!isGet) {
+    const mapper = ARG_MAPS[subcommand];
+    if (mapper) {
+      body = clean(mapper(filteredArgs));
+    } else if (filteredArgs.length) {
+      const joined = filteredArgs.join(" ");
+      try {
+        body = JSON.parse(joined);
+      } catch {
+        body = parseTargetArgs(filteredArgs);
+      }
+    }
+  }
+  if (targetWindowId) {
+    if (isGet) {
+      const url2 = new URL(path, baseUrl);
+      url2.searchParams.set("window", targetWindowId);
+      return doRequest(url2.toString(), "GET", undefined, { subcommand, jsonOutput });
+    } else {
+      if (!body)
+        body = {};
+      body.window = targetWindowId;
+    }
+  }
+  const url = `${baseUrl}${path}`;
+  return doRequest(url, isGet ? "GET" : "POST", body, { subcommand, jsonOutput });
+}
+async function doRequest(url, method, body, context = {}) {
+  const { subcommand, jsonOutput } = context;
+  try {
+    const opts = { method };
+    if (body) {
+      opts.headers = { "Content-Type": "application/json" };
+      opts.body = JSON.stringify(body);
+    }
+    const resp = await fetch(url, opts);
+    const contentType = resp.headers.get("content-type") || "";
+    if (contentType.includes("application/json")) {
+      const json = await resp.json();
+      if (!jsonOutput && subcommand === "tree" && json.success && json.data) {
+        console.log(formatTree(json.data));
+      } else if (!jsonOutput && subcommand === "events" && (json.events || Array.isArray(json))) {
+        console.log(formatEvents(json));
+      } else if (!jsonOutput && subcommand === "test-run" && json.test) {
+        console.log(formatTestResult(json));
+      } else if (!jsonOutput && subcommand === "test-suite" && json.results) {
+        console.log(formatSuiteResult(json));
+      } else if (!jsonOutput && subcommand === "screenshot" && json.data?.path) {
+        const bold = (s) => `\x1B[1m${s}\x1B[0m`;
+        const dim = (s) => `\x1B[2m${s}\x1B[0m`;
+        console.log(bold(json.data.path));
+        const meta = [json.data.width && json.data.height ? `${json.data.width}×${json.data.height}` : null, json.data.format, json.data.source].filter(Boolean).join(", ");
+        if (meta)
+          console.log(dim(meta));
+      } else if (!jsonOutput && subcommand === "video-stop" && json.data?.path) {
+        const bold = (s) => `\x1B[1m${s}\x1B[0m`;
+        const dim = (s) => `\x1B[2m${s}\x1B[0m`;
+        console.log(bold(json.data.path));
+        const meta = [json.data.duration ? `${json.data.duration.toFixed(1)}s` : null, json.data.size ? `${(json.data.size / 1024).toFixed(0)}KB` : null, json.data.format].filter(Boolean).join(", ");
+        if (meta)
+          console.log(dim(meta));
+      } else {
+        console.log(JSON.stringify(json, null, 2));
+      }
+    } else {
+      const text = await resp.text();
+      console.log(text);
+    }
+    if (resp.ok && !jsonOutput) {
+      const hint = COMMAND_HINTS[subcommand];
+      if (hint) {
+        const dim = (s) => `\x1B[2m${s}\x1B[0m`;
+        console.log(dim(`
+hj ${subcommand} : ${hint}`));
+      }
+    }
+    if (!resp.ok) {
+      process.exit(1);
+    }
+  } catch (err) {
+    if (err.cause?.code === "ECONNREFUSED") {
+      console.error("Error: Cannot connect to Haltija server.");
+      console.error("Start the server with: haltija --server");
+    } else {
+      console.error(`Error: ${err.message}`);
+    }
+    process.exit(1);
+  }
+}
+var KNOWN_COMMANDS = new Set([
+  "tree",
+  "query",
+  "inspect",
+  "inspectAll",
+  "styles",
+  "find",
+  "click",
+  "type",
+  "key",
+  "drag",
+  "scroll",
+  "call",
+  "navigate",
+  "refresh",
+  "location",
+  "events",
+  "events-watch",
+  "events-unwatch",
+  "console",
+  "mutations-watch",
+  "mutations-unwatch",
+  "mutations-status",
+  "eval",
+  "fetch",
+  "screenshot",
+  "snapshot",
+  "highlight",
+  "unhighlight",
+  "select-start",
+  "select-result",
+  "select-cancel",
+  "select-clear",
+  "windows",
+  "tabs-open",
+  "tabs-close",
+  "tabs-focus",
+  "video-start",
+  "video-stop",
+  "video-status",
+  "recording",
+  "recording-start",
+  "recording-stop",
+  "recording-generate",
+  "recordings",
+  "test-run",
+  "test-validate",
+  "test-suite",
+  "send",
+  "send-message",
+  "send-selection",
+  "send-recording",
+  "status",
+  "version",
+  "docs",
+  "api",
+  "stats"
+]);
+var COMMAND_ALIASES = {
+  open: "navigate",
+  goto: "navigate",
+  go: "navigate",
+  url: "navigate",
+  load: "navigate",
+  get: "tree",
+  dom: "tree",
+  page: "tree",
+  input: "type",
+  write: "type",
+  enter: "key",
+  press: "key",
+  run: "eval",
+  js: "eval",
+  exec: "eval",
+  shot: "screenshot",
+  capture: "screenshot",
+  ls: "tree",
+  list: "tree",
+  show: "tree",
+  help: "--help"
+};
+function isSubcommand(arg) {
+  if (!arg || arg.startsWith("-"))
+    return false;
+  if (/^\d+$/.test(arg))
+    return false;
+  return KNOWN_COMMANDS.has(arg);
+}
+function getSuggestion(cmd) {
+  if (COMMAND_ALIASES[cmd]) {
+    return COMMAND_ALIASES[cmd];
+  }
+  for (const known of KNOWN_COMMANDS) {
+    if (known.startsWith(cmd) || cmd.startsWith(known.slice(0, 3))) {
+      return known;
+    }
+  }
+  return null;
+}
+function listSubcommands() {
+  return `
+Subcommands (replace curl with simple commands):
+  ${bold("Inspect")}
+    tree [selector] [-d depth]     DOM tree with ref IDs
+    query <selector>               Find elements matching selector
+    inspect <@ref|selector>        Detailed element info
+    inspectAll <selector>          Deep inspect all matches
+    find <text>                    Find elements by text content
+
+  ${bold("Interact")}
+    click <@ref|selector|"text">   Click an element
+    type <@ref|selector> <text>    Type text into element
+    key <key> [--ctrl --shift]     Press a key
+    drag <@ref|selector> <dx> <dy> Drag element
+    scroll [selector|dy]           Scroll page or element
+    call <@ref|selector> <method>  Call element method/get property
+
+  ${bold("Navigate")}
+    navigate <url>                 Go to URL
+    refresh [--soft]               Reload page (hard by default)
+    location                       Current URL and title
+
+  ${bold("Observe")}
+    events                         Get semantic events
+    events-watch [preset]          Start watching events
+    events-unwatch                 Stop watching events
+    console                        Get console output
+    mutations-watch [preset]       Start watching DOM changes
+    mutations-unwatch              Stop watching
+    mutations-status               Check mutation watcher
+
+  ${bold("Evaluate")}
+    eval <code>                    Run JavaScript in browser
+    fetch <url> [prompt]           Fetch and process URL
+
+  ${bold("Capture")}
+    screenshot [@ref|selector]     Take screenshot (saves to /tmp)
+    snapshot [context]             Full page state capture
+    highlight <@ref|selector>      Highlight element
+    unhighlight                    Remove highlights
+    video-start [--maxDuration s]  Start video recording
+    video-stop                     Stop recording, get file path
+    video-status                   Check recording state
+
+  ${bold("Selection")}
+    select-start                   Begin region selection
+    select-result                  Get selection result
+    select-cancel                  Cancel selection
+    select-clear                   Clear selection
+
+  ${bold("Windows")}
+    windows                        List browser windows
+    tabs-open <url>                Open new tab
+    tabs-close <windowId>          Close tab
+    tabs-focus <windowId>          Focus tab
+
+  ${bold("Recording")}
+    recording start [name]         Start recording (survives page navigations)
+    recording stop                 Stop recording and save
+    recording list                 List saved recordings
+    recording replay <id|index>    Replay a saved recording
+    recording generate [name]      Generate test from last recording
+
+  ${bold("Send to Agent")}
+    send <agent> <message>         Send message to agent (auto-submits)
+    send selection [agent]         Send browser selection to agent
+    send recording [agent]         Send last recording to agent
+    --no-submit                    Paste only, don't auto-submit
+
+  ${bold("Testing")}
+    test-run <json> [options]      Run a test
+    test-suite <dir|files...>      Run all tests in dir (alphabetical)
+    test-validate <json>           Validate test format
+    
+    Test options:
+      --vars <json>                Template variables: '{"APP_URL": "http://localhost:5050"}'
+                                   Replaces \${VAR_NAME} in test files. Falls back to env vars.
+      --timeoutMs <ms>             Step timeout (default 5000)
+      --allow-failures <n>         Total failures before giving up (0=stop on first)
+      --allow-failures-streak <n>  Consecutive failures to bail (default 2)
+      --step-delay <ms>            Delay between steps (default 100)
+
+  ${bold("Info")}
+    status                         Server status
+    version                        Server version
+    docs                           API documentation
+    api                            Full API reference
+    stats                          Usage statistics
+
+  ${bold("Options")}
+    --window <id>                  Target specific window
+    --port <n>                     Server port (default: 8700)
+
+  ${bold("Examples")}
+    hj tree                        # See the page
+    hj tree -d 5                   # Deeper tree
+    hj click 42                    # Click by ref
+    hj click "#submit"             # Click by selector
+    hj type 10 Hello world         # Type text
+    hj key Enter                   # Press Enter
+    hj key a --ctrl                # Ctrl+A
+    hj eval document.title         # Get page title
+    hj navigate https://example.com
+    hj events                      # See what happened
+    hj send claude "check this"    # Message an agent
+    hj send selection              # Send selection to agent
+`;
+}
+function bold(s) {
+  return `\x1B[1m${s}\x1B[0m`;
+}
+
+// bin/hj.mjs
+var args = process.argv.slice(2);
+if (!args.length || args.includes("--help") || args.includes("-h")) {
+  const bold2 = (s) => `\x1B[1m${s}\x1B[0m`;
+  const dim = (s) => `\x1B[2m${s}\x1B[0m`;
+  console.log(`
+${bold2("hj")} - Haltija command-line interface
+
+Usage: hj <command> [args...]
+${listSubcommands()}
+Run ${dim("hj --help")} for this help.
+Run ${dim("haltija --help")} for server/app options.
+`);
+  process.exit(0);
+}
+var port = process.env.DEV_CHANNEL_PORT || "8700";
+var portIdx = args.indexOf("--port");
+if (portIdx !== -1 && args[portIdx + 1]) {
+  port = args[portIdx + 1];
+  args.splice(portIdx, 2);
+}
+var subcommand = args[0];
+var subArgs = args.slice(1).filter((a) => a !== "--window" || true);
+if (!isSubcommand(subcommand)) {
+  const suggestion = getSuggestion(subcommand);
+  if (suggestion === "--help") {
+    const topic = args[1];
+    if (topic) {
+      filterHelp(topic);
+    } else {
+      console.log(listSubcommands());
+    }
+    process.exit(0);
+  }
+  let msg = `Unknown command: '${subcommand}'`;
+  if (suggestion) {
+    msg += ` — did you mean '${suggestion}'?`;
+  }
+  console.error(msg);
+  console.error(`
+Examples: hj tree, hj navigate <url>, hj click @42`);
+  console.error(`Run 'hj' for docs.`);
+  process.exit(1);
+} else {
+  runSubcommand(subcommand, subArgs, port);
+}
+function filterHelp(topic) {
+  const bold2 = (s) => `\x1B[1m${s}\x1B[0m`;
+  const dim = (s) => `\x1B[2m${s}\x1B[0m`;
+  const needle = topic.toLowerCase();
+  const helpText = listSubcommands();
+  const lines = helpText.split(`
+`);
+  const matches = [];
+  let currentCategory = "";
+  for (const line of lines) {
+    if (line.match(/^\s{2}\x1b\[1m/)) {
+      currentCategory = line;
+      continue;
+    }
+    const stripped = line.replace(/\x1b\[[0-9;]*m/g, "").toLowerCase();
+    if (stripped.trim() && stripped.includes(needle)) {
+      matches.push({ category: currentCategory, line });
+    }
+  }
+  if (matches.length === 0) {
+    console.log(`No commands matching '${topic}'.`);
+    console.log(`Run ${dim("hj help")} to see all commands.`);
+    return;
+  }
+  console.log(`
+Commands matching '${bold2(topic)}':
+`);
+  let lastCategory = "";
+  for (const m of matches) {
+    if (m.category && m.category !== lastCategory) {
+      console.log(m.category);
+      lastCategory = m.category;
+    }
+    console.log(m.line);
+  }
+  const hintMatches = Object.entries(COMMAND_HINTS).filter(([cmd, hint]) => cmd.toLowerCase().includes(needle) || hint.toLowerCase().includes(needle));
+  if (hintMatches.length > 0) {
+    console.log(`
+  ${bold2("Hints")}`);
+    for (const [cmd, hint] of hintMatches) {
+      console.log(`    ${bold2(cmd.padEnd(28))} ${dim(hint)}`);
+    }
+  }
+  console.log("");
+}