chrome-relay 0.5.8 → 0.5.10

package/dist/cli.js

@@ -1,57 +1,264 @@
 #!/usr/bin/env node
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+// ../protocol/dist/index.js
+var dist_exports = {};
+__export(dist_exports, {
+  CHROME_WEB_STORE_EXTENSION_ID: () => CHROME_WEB_STORE_EXTENSION_ID,
+  DEFAULT_EXTENSION_ID: () => DEFAULT_EXTENSION_ID,
+  DEFAULT_EXTENSION_IDS: () => DEFAULT_EXTENSION_IDS,
+  DEFAULT_HTTP_PORT: () => DEFAULT_HTTP_PORT,
+  LEGACY_DEV_EXTENSION_ID: () => LEGACY_DEV_EXTENSION_ID,
+  LOCAL_UNPACKED_EXTENSION_ID: () => LOCAL_UNPACKED_EXTENSION_ID,
+  NATIVE_HOST_NAME: () => NATIVE_HOST_NAME,
+  RelayError: () => RelayError,
+  TOOL_NAMES: () => TOOL_NAMES,
+  toBridgeError: () => toBridgeError
+});
+function toBridgeError(unknownErr, fallbackTool) {
+  if (unknownErr instanceof RelayError) {
+    const e = unknownErr.toBridgeError();
+    return fallbackTool && !e.tool ? { ...e, tool: fallbackTool } : e;
+  }
+  const message = unknownErr instanceof Error ? unknownErr.message : String(unknownErr);
+  return {
+    code: "internal_error",
+    message,
+    ...fallbackTool ? { tool: fallbackTool } : {}
+  };
+}
+var NATIVE_HOST_NAME, DEFAULT_HTTP_PORT, CHROME_WEB_STORE_EXTENSION_ID, LEGACY_DEV_EXTENSION_ID, LOCAL_UNPACKED_EXTENSION_ID, DEFAULT_EXTENSION_ID, DEFAULT_EXTENSION_IDS, TOOL_NAMES, RelayError;
+var init_dist = __esm({
+  "../protocol/dist/index.js"() {
+    "use strict";
+    NATIVE_HOST_NAME = "dev.chrome_relay.native_host";
+    DEFAULT_HTTP_PORT = 12122;
+    CHROME_WEB_STORE_EXTENSION_ID = "cpdiapbifblhlcpnmlmfpgfjlacebokb";
+    LEGACY_DEV_EXTENSION_ID = "cdmmkpadhnpcfjljhgpdnnljhjafmhop";
+    LOCAL_UNPACKED_EXTENSION_ID = "cleiodnaklknhhfopegimjelfibjmbkc";
+    DEFAULT_EXTENSION_ID = CHROME_WEB_STORE_EXTENSION_ID;
+    DEFAULT_EXTENSION_IDS = [
+      CHROME_WEB_STORE_EXTENSION_ID,
+      LEGACY_DEV_EXTENSION_ID,
+      LOCAL_UNPACKED_EXTENSION_ID
+    ];
+    TOOL_NAMES = {
+      GET_WINDOWS_AND_TABS: "get_windows_and_tabs",
+      NAVIGATE: "chrome_navigate",
+      SWITCH_TAB: "chrome_switch_tab",
+      CLOSE_TABS: "chrome_close_tabs",
+      SCREENSHOT: "chrome_screenshot",
+      READ_PAGE: "chrome_read_page",
+      CLICK: "chrome_click_element",
+      FILL: "chrome_fill_or_select",
+      KEYBOARD: "chrome_keyboard",
+      TYPE: "chrome_type",
+      EVALUATE: "chrome_evaluate",
+      // §2.2 — viewport emulation (set/preset/clear share one tool, action via args.action)
+      VIEWPORT: "chrome_viewport",
+      // chrome_self_reload — calls chrome.runtime.reload() inside the extension.
+      // Lets the dev loop refresh the extension without manually clicking reload
+      // on chrome://extensions (Chrome blocks CDP attach on chrome:// pages).
+      SELF_RELOAD: "chrome_self_reload",
+      // §2.7c — console capture. Ring-buffer per tab; actions read/clear via args.
+      CONSOLE: "chrome_console",
+      // Workspaces — named Chrome windows for parallel agent work. Single tool
+      // with action: create | list | close. Every existing tool also accepts an
+      // optional workspaceName arg that routes ops into that workspace's window.
+      // (Was "chrome_group" pre-0.4.0; renamed because "group" collides with
+      // Chrome's own tab-group UI primitive, which is now exposed separately.)
+      WORKSPACE: "chrome_workspace",
+      // Tab groups — Chrome's native colored, collapsible folder of tabs inside
+      // a single window. Single tool with action: create | list | close | add | remove.
+      // Every existing tool also accepts an optional groupName arg that routes
+      // ops to a tab inside that tab-group.
+      GROUP: "chrome_group",
+      // §2.4 — accessibility tree. ~30× smaller than DOM serialization, more
+      // semantic. click_ax pairs with it: targets by backendDOMNodeId, no CSS.
+      AX: "chrome_ax",
+      CLICK_AX: "chrome_click_ax",
+      // §2.7a — network capture. Ring-buffer per tab; actions read/clear/har/body.
+      NETWORK: "chrome_network",
+      // Hover — dispatches mouseMoved at element center (or x,y) so :hover/
+      // :focus-within styles fire before a click or screencast frame is read.
+      HOVER: "chrome_hover",
+      // Screencast — wraps CDP Page.startScreencast / stopScreencast. SW buffers
+      // base64 JPEG frames per tab between start and stop. Paint-driven (catches
+      // CSS transitions, fade-ins, focus-ring motion) — at the cost of requiring
+      // the tab to be ACTIVE (Chrome doesn't paint backgrounded tabs). See
+      // docs/recording.md for the active-tab matrix.
+      SCREENCAST: "chrome_screencast"
+    };
+    RelayError = class extends Error {
+      code;
+      tool;
+      phase;
+      details;
+      retryable;
+      constructor(spec) {
+        super(spec.message);
+        this.name = "RelayError";
+        this.code = spec.code;
+        this.tool = spec.tool;
+        this.phase = spec.phase;
+        this.details = spec.details;
+        this.retryable = spec.retryable;
+      }
+      toBridgeError() {
+        return {
+          code: this.code,
+          message: this.message,
+          ...this.tool ? { tool: this.tool } : {},
+          ...this.phase ? { phase: this.phase } : {},
+          ...this.details ? { details: this.details } : {},
+          ...this.retryable !== void 0 ? { retryable: this.retryable } : {}
+        };
+      }
+    };
+  }
+});
 
 // src/program.ts
 import { Command } from "commander";
-import { writeFileSync } from "fs";
 
 // src/index.ts
-var CHROME_RELAY_VERSION = true ? "0.5.8" : "0.0.0-dev";
+var CHROME_RELAY_VERSION = true ? "0.5.10" : "0.0.0-dev";
 
-// src/install/install.ts
-import os from "os";
-import path from "path";
-import { chmod, mkdir, readFile, stat, writeFile } from "fs/promises";
-import { fileURLToPath } from "url";
+// src/commands/shared.ts
+init_dist();
 
-// ../protocol/dist/index.js
-var NATIVE_HOST_NAME = "dev.chrome_relay.native_host";
-var DEFAULT_HTTP_PORT = 12122;
-var CHROME_WEB_STORE_EXTENSION_ID = "cpdiapbifblhlcpnmlmfpgfjlacebokb";
-var LEGACY_DEV_EXTENSION_ID = "cdmmkpadhnpcfjljhgpdnnljhjafmhop";
-var LOCAL_UNPACKED_EXTENSION_ID = "cleiodnaklknhhfopegimjelfibjmbkc";
-var DEFAULT_EXTENSION_IDS = [
-  CHROME_WEB_STORE_EXTENSION_ID,
-  LEGACY_DEV_EXTENSION_ID,
-  LOCAL_UNPACKED_EXTENSION_ID
-];
-var RelayError = class extends Error {
-  code;
-  tool;
-  phase;
-  details;
-  retryable;
-  constructor(spec) {
-    super(spec.message);
-    this.name = "RelayError";
-    this.code = spec.code;
-    this.tool = spec.tool;
-    this.phase = spec.phase;
-    this.details = spec.details;
-    this.retryable = spec.retryable;
+// src/client/call.ts
+init_dist();
+var noticePrinted = false;
+function emitNoticeOnce(notice) {
+  if (noticePrinted) return;
+  noticePrinted = true;
+  process.stderr.write(`[chrome-relay] ${notice}
+`);
+}
+async function callToolWithMeta(name, args) {
+  const response = await fetch(`http://127.0.0.1:${DEFAULT_HTTP_PORT}/call`, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({
+      name,
+      args
+    })
+  });
+  const payload = await response.json().catch(() => null);
+  const noticeString = payload?.notice ?? payload?.notices?.[0]?.message;
+  if (!response.ok) {
+    if (noticeString) emitNoticeOnce(noticeString);
+    throw rebuildError(payload, `Bridge request failed with ${response.status}`);
   }
-  toBridgeError() {
-    return {
-      code: this.code,
-      message: this.message,
-      ...this.tool ? { tool: this.tool } : {},
-      ...this.phase ? { phase: this.phase } : {},
-      ...this.details ? { details: this.details } : {},
-      ...this.retryable !== void 0 ? { retryable: this.retryable } : {}
-    };
+  if (!payload?.ok) {
+    if (noticeString) emitNoticeOnce(noticeString);
+    throw rebuildError(payload, "Bridge call failed.");
   }
-};
+  if (noticeString) emitNoticeOnce(noticeString);
+  return { data: payload.data, notice: payload.notice, notices: payload.notices };
+}
+function rebuildError(payload, fallbackMessage) {
+  if (payload?.errorDetails) {
+    return new RelayError(payload.errorDetails);
+  }
+  return new Error(payload?.error || fallbackMessage);
+}
+async function callTool(name, args) {
+  const { data } = await callToolWithMeta(name, args);
+  return data;
+}
+
+// src/commands/shared.ts
+function tabOpt(cmd) {
+  return cmd.option("-t, --tab <id>", "target tab ID", (v) => Number(v)).option("--workspace <name>", "target the active tab in a named workspace window (see `chrome-relay workspace`)").option("--group <name>", "target the active tab in a named tab-group (see `chrome-relay group`)");
+}
+function makeBaseArgs(program) {
+  return function baseArgs(opts) {
+    const parentOpts = program.opts();
+    rejectIntraScopeConflict("subcommand", {
+      tab: opts.tab,
+      workspace: opts.workspace,
+      group: opts.group
+    });
+    rejectIntraScopeConflict("program-level", {
+      workspace: parentOpts.workspace,
+      group: parentOpts.group
+    });
+    if (opts.workspace && parentOpts.workspace && opts.workspace !== parentOpts.workspace) {
+      emitTargetOverride("workspace", parentOpts.workspace, opts.workspace);
+    }
+    if (opts.group && parentOpts.group && opts.group !== parentOpts.group) {
+      emitTargetOverride("group", parentOpts.group, opts.group);
+    }
+    if (opts.tab !== void 0 && (parentOpts.workspace || parentOpts.group)) {
+      const prior = parentOpts.workspace ? `workspace=${parentOpts.workspace}` : `group=${parentOpts.group}`;
+      emitTargetOverride("tab", prior, String(opts.tab));
+    }
+    const args = {};
+    if (opts.tab !== void 0) args.tabId = opts.tab;
+    const effectiveWorkspace = opts.workspace ?? parentOpts.workspace;
+    const effectiveGroup = opts.group ?? parentOpts.group;
+    if (opts.tab === void 0 && effectiveWorkspace) args.workspaceName = effectiveWorkspace;
+    if (opts.tab === void 0 && effectiveGroup) args.groupName = effectiveGroup;
+    return args;
+  };
+}
+function rejectIntraScopeConflict(scope, fields) {
+  const present = [];
+  if (fields.tab !== void 0) present.push("--tab");
+  if (fields.workspace) present.push("--workspace");
+  if (fields.group) present.push("--group");
+  if (present.length > 1) {
+    process.stderr.write(
+      `[chrome-relay] target_conflict: ${scope} flags ${present.join(" + ")} are mutually exclusive. Pass exactly one of --tab, --workspace, or --group on the same ${scope}.
+`
+    );
+    process.exit(2);
+  }
+}
+function emitTargetOverride(kind, from, to) {
+  process.stderr.write(
+    `[chrome-relay] target_overridden: ${kind} ${from} \u2192 ${to} (subcommand-level overrides program-level)
+`
+  );
+}
+async function runToolImpl(name, args) {
+  try {
+    const result = await callTool(name, args);
+    if (typeof result === "string") {
+      process.stdout.write(result + "\n");
+    } else {
+      process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+    }
+  } catch (error) {
+    if (error instanceof RelayError) {
+      process.stderr.write(error.message + "\n");
+      process.stderr.write(JSON.stringify({ relayError: error.toBridgeError() }, null, 2) + "\n");
+    } else {
+      process.stderr.write(
+        (error instanceof Error ? error.message : String(error)) + "\n"
+      );
+    }
+    process.exit(1);
+  }
+}
+var runTool = runToolImpl;
 
 // src/install/install.ts
+init_dist();
+import os from "os";
+import path from "path";
+import { chmod, mkdir, readFile, stat, writeFile } from "fs/promises";
+import { fileURLToPath } from "url";
 var APP_DIR = path.join(os.homedir(), ".chrome-relay");
 var KNOWN_EXTENSION_IDS = [
   ["Chrome Web Store", CHROME_WEB_STORE_EXTENSION_ID],
@@ -155,49 +362,21 @@ async function runDoctor() {
   }
 }
 
-// src/client/call.ts
-var noticePrinted = false;
-function emitNoticeOnce(notice) {
-  if (noticePrinted) return;
-  noticePrinted = true;
-  process.stderr.write(`[chrome-relay] ${notice}
-`);
-}
-async function callToolWithMeta(name, args) {
-  const response = await fetch(`http://127.0.0.1:${DEFAULT_HTTP_PORT}/call`, {
-    method: "POST",
-    headers: { "content-type": "application/json" },
-    body: JSON.stringify({
-      name,
-      args
-    })
-  });
-  const payload = await response.json().catch(() => null);
-  const noticeString = payload?.notice ?? payload?.notices?.[0]?.message;
-  if (!response.ok) {
-    if (noticeString) emitNoticeOnce(noticeString);
-    throw rebuildError(payload, `Bridge request failed with ${response.status}`);
-  }
-  if (!payload?.ok) {
-    if (noticeString) emitNoticeOnce(noticeString);
-    throw rebuildError(payload, "Bridge call failed.");
-  }
-  if (noticeString) emitNoticeOnce(noticeString);
-  return { data: payload.data, notice: payload.notice, notices: payload.notices };
-}
-function rebuildError(payload, fallbackMessage) {
-  if (payload?.errorDetails) {
-    return new RelayError(payload.errorDetails);
-  }
-  return new Error(payload?.error || fallbackMessage);
-}
-async function callTool(name, args) {
-  const { data } = await callToolWithMeta(name, args);
-  return data;
-}
-
 // src/release-notes.ts
 var RELEASE_NOTES = {
+  "0.5.10": [
+    "Direct /call target conflict enforcement. Third-party callers posting to /call with multiple loose target fields (tabId + workspaceName, etc.) now throw `target_conflict` instead of silently applying precedence. Matches the CLI rule the CLI itself enforced since 0.5.4.",
+    "All useful plain Error throws in extension handlers converted to RelayError(invalid_arguments). Affected tools: chrome_click_element, chrome_fill_or_select, chrome_keyboard, chrome_type, chrome_evaluate, chrome_switch_tab, chrome_close_tabs, chrome_viewport (preset name + width/height), chrome_workspace (create/close), chrome_group (create/close/add/remove), chrome_network (body without --request-id), chrome_hover (no selector or x,y), chrome_click_ax (no --node), and bbox parser. Agents can now branch on `errorDetails.code === 'invalid_arguments'` for all of these.",
+    "chrome_hover with a selector that doesn't match now throws RelayError(`element_not_found`) (was plain Error).",
+    "BEHAVIOR CHANGE \u2014 `chrome-relay screencast stop --gif/--mp4` is no longer best-effort when ffmpeg is missing. Old behavior printed 'skipping' and exited 0 (agent saw success but no GIF existed). New behavior throws `external_dependency_missing` with exit 1. Pass `--allow-missing-ffmpeg` to restore the legacy skip-with-warning behavior.",
+    "Tests: +17 in handler-strict.test.ts covering the conflict + 13 missing-arg paths. Total now 372."
+  ],
+  "0.5.9": [
+    "Internal refactor (code-quality-hardening PR 7): program.ts and tools.ts split into per-domain modules. Pure code motion, no behavior change.",
+    "CLI: packages/cli/src/program.ts shrank from 1041 \u2192 75 lines. Per-domain modules now live in packages/cli/src/commands/{install-update,navigation,input,capture,sessions}.ts.",
+    "Extension: apps/extension/src/browser/tools.ts shrank from 891 \u2192 34 lines. Per-domain handler modules live in apps/extension/src/browser/handlers/{target,navigation,input,capture,sessions}.ts.",
+    "All 355 tests still pass without modification \u2014 the dispatcher contract (runTool name dispatch) is unchanged."
+  ],
   "0.5.8": [
     "Internal refactor (code-quality-hardening PR 6, first cut): shared CLI helpers moved out of program.ts into packages/cli/src/commands/shared.ts.",
     "tabOpt(), makeBaseArgs(program), and runTool() are now importable from `./commands/shared.js`. program.ts dropped ~100 lines.",
@@ -273,104 +452,8 @@ function listReleaseNotesSince(since) {
   return Object.keys(RELEASE_NOTES).filter((v) => compareSemver(v, since) > 0).sort((a, b) => compareSemver(a, b)).map((version) => ({ version, bullets: RELEASE_NOTES[version] }));
 }
 
-// src/commands/shared.ts
-function tabOpt(cmd) {
-  return cmd.option("-t, --tab <id>", "target tab ID", (v) => Number(v)).option("--workspace <name>", "target the active tab in a named workspace window (see `chrome-relay workspace`)").option("--group <name>", "target the active tab in a named tab-group (see `chrome-relay group`)");
-}
-function makeBaseArgs(program) {
-  return function baseArgs(opts) {
-    const parentOpts = program.opts();
-    rejectIntraScopeConflict("subcommand", {
-      tab: opts.tab,
-      workspace: opts.workspace,
-      group: opts.group
-    });
-    rejectIntraScopeConflict("program-level", {
-      workspace: parentOpts.workspace,
-      group: parentOpts.group
-    });
-    if (opts.workspace && parentOpts.workspace && opts.workspace !== parentOpts.workspace) {
-      emitTargetOverride("workspace", parentOpts.workspace, opts.workspace);
-    }
-    if (opts.group && parentOpts.group && opts.group !== parentOpts.group) {
-      emitTargetOverride("group", parentOpts.group, opts.group);
-    }
-    if (opts.tab !== void 0 && (parentOpts.workspace || parentOpts.group)) {
-      const prior = parentOpts.workspace ? `workspace=${parentOpts.workspace}` : `group=${parentOpts.group}`;
-      emitTargetOverride("tab", prior, String(opts.tab));
-    }
-    const args = {};
-    if (opts.tab !== void 0) args.tabId = opts.tab;
-    const effectiveWorkspace = opts.workspace ?? parentOpts.workspace;
-    const effectiveGroup = opts.group ?? parentOpts.group;
-    if (opts.tab === void 0 && effectiveWorkspace) args.workspaceName = effectiveWorkspace;
-    if (opts.tab === void 0 && effectiveGroup) args.groupName = effectiveGroup;
-    return args;
-  };
-}
-function rejectIntraScopeConflict(scope, fields) {
-  const present = [];
-  if (fields.tab !== void 0) present.push("--tab");
-  if (fields.workspace) present.push("--workspace");
-  if (fields.group) present.push("--group");
-  if (present.length > 1) {
-    process.stderr.write(
-      `[chrome-relay] target_conflict: ${scope} flags ${present.join(" + ")} are mutually exclusive. Pass exactly one of --tab, --workspace, or --group on the same ${scope}.
-`
-    );
-    process.exit(2);
-  }
-}
-function emitTargetOverride(kind, from, to) {
-  process.stderr.write(
-    `[chrome-relay] target_overridden: ${kind} ${from} \u2192 ${to} (subcommand-level overrides program-level)
-`
-  );
-}
-async function runTool(name, args) {
-  try {
-    const result = await callTool(name, args);
-    if (typeof result === "string") {
-      process.stdout.write(result + "\n");
-    } else {
-      process.stdout.write(JSON.stringify(result, null, 2) + "\n");
-    }
-  } catch (error) {
-    if (error instanceof RelayError) {
-      process.stderr.write(error.message + "\n");
-      process.stderr.write(JSON.stringify({ relayError: error.toBridgeError() }, null, 2) + "\n");
-    } else {
-      process.stderr.write(
-        (error instanceof Error ? error.message : String(error)) + "\n"
-      );
-    }
-    process.exit(1);
-  }
-}
-
-// src/program.ts
-function buildProgram() {
-  const program = new Command();
-  program.name("chrome-relay").description("Connect your local Chrome browser to coding agents through a local bridge.").version(CHROME_RELAY_VERSION).showHelpAfterError().option("--workspace <name>", "target the active tab in a named workspace window (works at top level too)").option("--group <name>", "target the active tab in a named tab-group (works at top level too)").enablePositionalOptions().addHelpText(
-    "after",
-    `
-
-Common agent flow:
-  chrome-relay tabs
-  chrome-relay navigate --tab <tabId> "https://example.com"
-  chrome-relay read --tab <tabId> -i
-  chrome-relay click --tab <tabId> "<selector>"
-  chrome-relay fill --tab <tabId> "<selector>" "value"
-  chrome-relay type --tab <tabId> -s "<selector>" "text into rich editor"
-  chrome-relay keys --tab <tabId> Enter
-  chrome-relay js --tab <tabId> "return document.title"
-  chrome-relay screenshot --tab <tabId> -o evidence.png
-
-Notes:
-  navigate takes a URL. Use --tab to target an existing tab.
-  Tools attach via CDP and run on backgrounded tabs without stealing focus.
-`
-  );
+// src/commands/install-update.ts
+function registerInstallUpdate(program) {
   program.command("install").description("Install and register the local Chrome Relay host.").action(async () => {
     await runInstall();
   });
@@ -459,8 +542,11 @@ Notes:
       changes
     }, null, 2) + "\n");
   });
-  const run = runTool;
-  const baseArgs = makeBaseArgs(program);
+}
+
+// src/commands/navigation.ts
+function registerNavigation(ctx) {
+  const { program, baseArgs, run } = ctx;
   program.command("tabs [verb]").description("List open Chrome windows and tabs. (verb 'list' is accepted as alias)").action(async (verb) => {
     if (verb && verb !== "list") {
       process.stderr.write(`unknown tabs verb: ${verb}. Use 'tabs' or 'tabs list'.
@@ -495,6 +581,127 @@ Use "chrome-relay switch ${url}" to activate that tab, or "chrome-relay navigate
     if (opts.inactive) args.active = false;
     await run("chrome_navigate", args);
   });
+  program.command("switch <tabId>").description("Activate a tab by ID.").action(async (tabId) => {
+    await run("chrome_switch_tab", { tabId: Number(tabId) });
+  });
+  program.command("close <tabIds...>").description("Close one or more tabs by ID.").action(async (tabIds) => {
+    await run("chrome_close_tabs", { tabIds: tabIds.map(Number) });
+  });
+  program.command("call <tool> [json]").description("Call any Chrome Relay tool with raw JSON args.").action(async (tool, json) => {
+    const args = json ? JSON.parse(json) : {};
+    await run(tool, args);
+  });
+}
+
+// src/commands/input.ts
+function registerInput(ctx) {
+  const { program, baseArgs, run } = ctx;
+  tabOpt(
+    program.command("click <selector>").description("Click an element by CSS selector.")
+  ).action(async (selector, opts) => {
+    const args = { selector };
+    Object.assign(args, baseArgs(opts));
+    await run("chrome_click_element", args);
+  });
+  tabOpt(
+    program.command("fill <selector> <value>").description("Fill an input or textarea.")
+  ).action(async (selector, value, opts) => {
+    const args = { selector, value };
+    Object.assign(args, baseArgs(opts));
+    await run("chrome_fill_or_select", args);
+  });
+  tabOpt(
+    program.command("keys <keys>").description("Press a single key or chord via trusted CDP input (e.g. Enter, Cmd+K).").addHelpText(
+      "after",
+      `
+
+Examples:
+  chrome-relay keys Enter
+  chrome-relay keys Tab
+  chrome-relay keys Cmd+K
+  chrome-relay keys Shift+ArrowDown
+
+For typing text into a field, use \`chrome-relay type\` instead.
+`
+    )
+  ).action(async (keys, opts) => {
+    const args = { keys };
+    Object.assign(args, baseArgs(opts));
+    await run("chrome_keyboard", args);
+  });
+  tabOpt(
+    program.command("type <text>").description("Insert text via trusted CDP input. Works in contenteditable / Draft.js / Lexical.").option("-s, --selector <selector>", "focus this element first").addHelpText(
+      "after",
+      `
+
+Examples:
+  chrome-relay type --selector "[data-testid=tweetTextarea_0]" "hello world"
+  chrome-relay type "appended into already-focused element"
+
+When to pick which:
+  fill   \u2014 plain <input>, <textarea>, <select>, React-controlled inputs (atomic write).
+  type   \u2014 contenteditable, Draft.js, Lexical, ProseMirror (trusted text commit).
+  keys   \u2014 Enter, Tab, Esc, arrows, modifier chords (single key press).
+  js     \u2014 anything else.
+`
+    )
+  ).action(async (text, opts) => {
+    const args = { text };
+    Object.assign(args, baseArgs(opts));
+    if (opts.selector) args.selector = opts.selector;
+    await run("chrome_type", args);
+  });
+  tabOpt(
+    program.command("js <code>").description("Evaluate JavaScript in the page MAIN world. Use `return` for the value.").option("--timeout-ms <ms>", "execution timeout in milliseconds (default 15000)", (v) => Number(v)).addHelpText(
+      "after",
+      `
+
+Examples:
+  chrome-relay js "return document.title"
+  chrome-relay js "return await fetch('/api/me').then(r => r.json())"
+  chrome-relay js --tab 12345 "return document.querySelectorAll('article').length"
+
+Notes:
+  Code is wrapped in an async IIFE. Top-level await works. Use \`return\` to send a value back.
+  Returned value is JSON-serialized. DOM nodes and functions become {}.
+  Runs in MAIN world: page globals, framework internals, and shadow roots are reachable.
+`
+    )
+  ).action(async (code, opts) => {
+    const args = { code };
+    Object.assign(args, baseArgs(opts));
+    if (typeof opts.timeoutMs === "number") args.timeoutMs = opts.timeoutMs;
+    await run("chrome_evaluate", args);
+  });
+  tabOpt(
+    program.command("hover [selector]").description("Move the pointer over an element or coordinates. Fires :hover styles.").option("--x <px>", "explicit x coordinate (CSS pixels)", (v) => Number(v)).option("--y <px>", "explicit y coordinate (CSS pixels)", (v) => Number(v)).addHelpText(
+      "after",
+      `
+
+Examples:
+  chrome-relay hover --tab 123 'button[title="Install runner"]'
+  chrome-relay hover --tab 123 --x 1327 --y 771
+
+Use before screencast to capture hover-driven micro-states (button glow,
+tooltip appearance, etc.) that a bare click would skip past too quickly.
+`
+    )
+  ).action(async (selector, opts) => {
+    const args = {};
+    Object.assign(args, baseArgs(opts));
+    if (selector) args.selector = selector;
+    if (typeof opts.x === "number" && typeof opts.y === "number") {
+      args.x = opts.x;
+      args.y = opts.y;
+    }
+    await run("chrome_hover", args);
+  });
+}
+
+// src/commands/capture.ts
+import { writeFileSync } from "fs";
+function registerCapture(ctx) {
+  const { program, baseArgs, run } = ctx;
   tabOpt(
     program.command("screenshot").description("Capture a screenshot of any tab without activating it.").option("--full", "capture beyond the viewport (full page)").option("--bbox <rect>", "capture a region: 'x,y,width,height' (pixels)").option("--selector <css>", "capture the bounding box of a CSS selector").option("--padding <px>", "pixels of padding around --selector region", (v) => Number(v)).option("--max-edge <px>", "downscale so longer edge \u2264 this many pixels (no default; opt-in)", (v) => Number(v)).option("-o, --out <path>", "save image to path (base64 PNG decoded)").addHelpText(
       "after",
@@ -549,92 +756,217 @@ full-tab screenshot when an agent only needs to see one component.
     await run("chrome_read_page", args);
   });
   tabOpt(
-    program.command("click <selector>").description("Click an element by CSS selector.")
-  ).action(async (selector, opts) => {
-    const args = { selector };
-    Object.assign(args, baseArgs(opts));
-    await run("chrome_click_element", args);
-  });
-  tabOpt(
-    program.command("fill <selector> <value>").description("Fill an input or textarea.")
-  ).action(async (selector, value, opts) => {
-    const args = { selector, value };
-    Object.assign(args, baseArgs(opts));
-    await run("chrome_fill_or_select", args);
-  });
-  tabOpt(
-    program.command("keys <keys>").description("Press a single key or chord via trusted CDP input (e.g. Enter, Cmd+K).").addHelpText(
+    program.command("ax").description("Extract the accessibility tree \u2014 ~30\xD7 smaller than `read` and more semantic.").option("-i, --interactive-only", "filter to actionable roles (button, link, textbox, ...)").option("--root <role>", "start from the first node matching this role (e.g. 'main')").option("--include-subframes", "walk subframes too (default: top frame only)").addHelpText(
       "after",
       `
 
 Examples:
-  chrome-relay keys Enter
-  chrome-relay keys Tab
-  chrome-relay keys Cmd+K
-  chrome-relay keys Shift+ArrowDown
+  chrome-relay ax --tab 123
+  chrome-relay ax --tab 123 --interactive-only
+  chrome-relay ax --tab 123 --root main --interactive-only
 
-For typing text into a field, use \`chrome-relay type\` instead.
+Notes:
+  Each node carries an "id" \u2014 that's the backendDOMNodeId. Pass it to
+  \`chrome-relay click-ax --node <id>\` to click without a CSS selector.
 `
     )
-  ).action(async (keys, opts) => {
-    const args = { keys };
-    Object.assign(args, baseArgs(opts));
-    await run("chrome_keyboard", args);
+  ).action(async (opts) => {
+    const args = baseArgs(opts);
+    if (opts.interactiveOnly) args.interactiveOnly = true;
+    if (opts.root) args.rootRole = opts.root;
+    if (opts.includeSubframes) args.includeSubframes = true;
+    await run("chrome_ax", args);
   });
   tabOpt(
-    program.command("type <text>").description("Insert text via trusted CDP input. Works in contenteditable / Draft.js / Lexical.").option("-s, --selector <selector>", "focus this element first").addHelpText(
+    program.command("click-ax").description("Click an element by its backendDOMNodeId from a previous `ax` call.").requiredOption("--node <id>", "backendDOMNodeId from `chrome-relay ax`", (v) => Number(v)).addHelpText(
       "after",
       `
 
 Examples:
-  chrome-relay type --selector "[data-testid=tweetTextarea_0]" "hello world"
-  chrome-relay type "appended into already-focused element"
+  chrome-relay click-ax --tab 123 --node 456
 
-When to pick which:
-  fill   \u2014 plain <input>, <textarea>, <select>, React-controlled inputs (atomic write).
-  type   \u2014 contenteditable, Draft.js, Lexical, ProseMirror (trusted text commit).
-  keys   \u2014 Enter, Tab, Esc, arrows, modifier chords (single key press).
-  js     \u2014 anything else.
+Notes:
+  Throws explicitly if the node id is stale (page mutated since you called
+  \`ax\`). Re-run \`ax\` and pass the fresh id.
 `
     )
-  ).action(async (text, opts) => {
-    const args = { text };
+  ).action(async (opts) => {
+    const args = baseArgs(opts);
+    args.node = opts.node;
+    await run("chrome_click_ax", args);
+  });
+  const screencast = program.command("screencast").description("Record a tab via CDP (paint-driven). Requires an active tab.").addHelpText(
+    "after",
+    `
+
+Examples:
+  chrome-relay screencast start --tab 123 --quality 80 --max-width 900
+  # ... drive the interaction (hover, click, etc.) ...
+  chrome-relay screencast stop --tab 123 --out /tmp/recording
+
+  # The --out path becomes a directory of frame_NNNN.jpg files. If ffmpeg
+  # is on PATH and --gif is also passed, an animated GIF is written next to
+  # the frames at /tmp/recording.gif.
+
+Notes:
+  Frames buffer in the extension service worker. A 10-second capture at
+  default settings (jpeg q=60, ~15fps, full viewport) lands ~2-3 MB.
+  Pass --max-width to downscale and lighten the buffer.
+  Each frame is base64 JPEG; the CLI decodes them when --out is given.
+`
+  );
+  tabOpt(
+    screencast.command("start").description("Begin screencast capture on a tab.").option("--format <fmt>", "jpeg | png (default jpeg)").option("--quality <n>", "jpeg quality 0-100 (default 80)", (v) => Number(v)).option("--max-width <px>", "downscale; aspect preserved", (v) => Number(v)).option("--max-height <px>", "downscale; aspect preserved", (v) => Number(v)).option("--every-nth <n>", "throttle: keep 1 in N frames (default 1)", (v) => Number(v))
+  ).action(async (opts) => {
+    const args = { action: "start" };
     Object.assign(args, baseArgs(opts));
-    if (opts.selector) args.selector = opts.selector;
-    await run("chrome_type", args);
+    if (opts.format) args.format = opts.format;
+    if (typeof opts.quality === "number") args.quality = opts.quality;
+    if (typeof opts.maxWidth === "number") args.maxWidth = opts.maxWidth;
+    if (typeof opts.maxHeight === "number") args.maxHeight = opts.maxHeight;
+    if (typeof opts.everyNth === "number") args.everyNthFrame = opts.everyNth;
+    await run("chrome_screencast", args);
+  });
+  tabOpt(
+    screencast.command("stop").description("Stop the screencast and emit frames (or write to disk).").option("-o, --out <dir>", "write frames as JPEGs into this directory (created if missing)").option("--gif", "after writing frames, ffmpeg them into <dir>.gif (requires ffmpeg on PATH)").option("--mp4", "after writing frames, ffmpeg them into <dir>.mp4 (requires ffmpeg on PATH)").option("--fps <n>", "assumed framerate when invoking ffmpeg (default 15)", (v) => Number(v)).option("--no-dedupe", "keep raw frames; default collapses consecutive identical frames via SHA-256").option("--allow-missing-ffmpeg", "with --gif/--mp4: skip ffmpeg step (and emit a warning) if ffmpeg isn't on PATH, instead of failing with external_dependency_missing")
+  ).action(async (opts) => {
+    const args = { action: "stop" };
+    Object.assign(args, baseArgs(opts));
+    try {
+      const result = await callTool("chrome_screencast", args);
+      if (!opts.out) {
+        const { frames, ...summary } = result;
+        process.stdout.write(JSON.stringify({ ...summary, framesOmitted: frames.length, hint: "pass --out <dir> to save" }, null, 2) + "\n");
+        return;
+      }
+      const { mkdirSync, writeFileSync: wf, renameSync, unlinkSync } = await import("fs");
+      const path2 = await import("path");
+      const { createHash } = await import("crypto");
+      mkdirSync(opts.out, { recursive: true });
+      result.frames.forEach((f, i) => {
+        const name = `frame_${String(i + 1).padStart(4, "0")}.jpg`;
+        wf(path2.join(opts.out, name), Buffer.from(f.data, "base64"));
+      });
+      process.stdout.write(`Wrote ${result.frames.length} frames to ${opts.out}
+`);
+      const dedupeOn = opts.dedupe !== false;
+      if (dedupeOn && result.frames.length > 1) {
+        const hashes = result.frames.map(
+          (f) => createHash("sha256").update(Buffer.from(f.data, "base64")).digest("hex")
+        );
+        const kept = [];
+        let prev = "";
+        hashes.forEach((h, i) => {
+          if (h !== prev) kept.push(i);
+          prev = h;
+        });
+        const dropped = result.frames.length - kept.length;
+        if (dropped > 0) {
+          for (let i = 0; i < result.frames.length; i++) {
+            const src = path2.join(opts.out, `frame_${String(i + 1).padStart(4, "0")}.jpg`);
+            try {
+              unlinkSync(src);
+            } catch {
+            }
+          }
+          kept.forEach((srcIdx, newIdx) => {
+            const tmp = path2.join(opts.out, `tmp_${String(newIdx + 1).padStart(4, "0")}.jpg`);
+            wf(tmp, Buffer.from(result.frames[srcIdx].data, "base64"));
+          });
+          kept.forEach((_, newIdx) => {
+            const tmp = path2.join(opts.out, `tmp_${String(newIdx + 1).padStart(4, "0")}.jpg`);
+            const final = path2.join(opts.out, `frame_${String(newIdx + 1).padStart(4, "0")}.jpg`);
+            renameSync(tmp, final);
+          });
+          process.stdout.write(`Deduped: dropped ${dropped} identical frames, ${kept.length} remain.
+`);
+        } else {
+          process.stdout.write(`Deduped: no consecutive duplicates found.
+`);
+        }
+      }
+      if (opts.gif || opts.mp4) {
+        const fps = typeof opts.fps === "number" ? opts.fps : 15;
+        const { spawnSync } = await import("child_process");
+        const which = spawnSync("which", ["ffmpeg"]);
+        if (which.status !== 0) {
+          if (opts.allowMissingFfmpeg) {
+            process.stderr.write("[chrome-relay] ffmpeg not on PATH \u2014 skipping --gif/--mp4 (allow-missing-ffmpeg).\n");
+            return;
+          }
+          const { RelayError: RelayError2 } = await Promise.resolve().then(() => (init_dist(), dist_exports));
+          const err = new RelayError2({
+            code: "external_dependency_missing",
+            message: "chrome-relay screencast stop --gif/--mp4 requires ffmpeg on PATH. Install ffmpeg (brew install ffmpeg) or pass --allow-missing-ffmpeg to skip the stitch step with a warning.",
+            tool: "chrome_screencast",
+            phase: "ffmpeg_stitch",
+            details: { dependency: "ffmpeg", outputs: { gif: !!opts.gif, mp4: !!opts.mp4 } },
+            retryable: false
+          });
+          process.stderr.write(err.message + "\n");
+          process.stderr.write(JSON.stringify({ relayError: err.toBridgeError() }, null, 2) + "\n");
+          process.exit(1);
+        }
+        if (opts.gif) {
+          const gifOut = `${opts.out.replace(/\/$/, "")}.gif`;
+          const r = spawnSync("ffmpeg", [
+            "-y",
+            "-framerate",
+            String(fps),
+            "-i",
+            path2.join(opts.out, "frame_%04d.jpg"),
+            "-vf",
+            `fps=${fps},split[s0][s1];[s0]palettegen[p];[s1][p]paletteuse`,
+            "-loop",
+            "0",
+            gifOut
+          ], { stdio: "inherit" });
+          if (r.status === 0) process.stdout.write(`Wrote ${gifOut}
+`);
+        }
+        if (opts.mp4) {
+          const mp4Out = `${opts.out.replace(/\/$/, "")}.mp4`;
+          const r = spawnSync("ffmpeg", [
+            "-y",
+            "-framerate",
+            String(fps),
+            "-i",
+            path2.join(opts.out, "frame_%04d.jpg"),
+            "-c:v",
+            "libx264",
+            "-pix_fmt",
+            "yuv420p",
+            "-crf",
+            "20",
+            mp4Out
+          ], { stdio: "inherit" });
+          if (r.status === 0) process.stdout.write(`Wrote ${mp4Out}
+`);
+        }
+      }
+    } catch (error) {
+      process.stderr.write(
+        (error instanceof Error ? error.message : String(error)) + "\n"
+      );
+      process.exit(1);
+    }
   });
-  tabOpt(
-    program.command("js <code>").description("Evaluate JavaScript in the page MAIN world. Use `return` for the value.").option("--timeout-ms <ms>", "execution timeout in milliseconds (default 15000)", (v) => Number(v)).addHelpText(
-      "after",
-      `
-
-Examples:
-  chrome-relay js "return document.title"
-  chrome-relay js "return await fetch('/api/me').then(r => r.json())"
-  chrome-relay js --tab 12345 "return document.querySelectorAll('article').length"
+}
 
-Notes:
-  Code is wrapped in an async IIFE. Top-level await works. Use \`return\` to send a value back.
-  Returned value is JSON-serialized. DOM nodes and functions become {}.
-  Runs in MAIN world: page globals, framework internals, and shadow roots are reachable.
-`
-    )
-  ).action(async (code, opts) => {
-    const args = { code };
-    Object.assign(args, baseArgs(opts));
-    if (typeof opts.timeoutMs === "number") args.timeoutMs = opts.timeoutMs;
-    await run("chrome_evaluate", args);
-  });
-  program.command("switch <tabId>").description("Activate a tab by ID.").action(async (tabId) => {
-    await run("chrome_switch_tab", { tabId: Number(tabId) });
-  });
-  program.command("close <tabIds...>").description("Close one or more tabs by ID.").action(async (tabIds) => {
-    await run("chrome_close_tabs", { tabIds: tabIds.map(Number) });
-  });
-  program.command("call <tool> [json]").description("Call any Chrome Relay tool with raw JSON args.").action(async (tool, json) => {
-    const args = json ? JSON.parse(json) : {};
-    await run(tool, args);
-  });
+// src/commands/sessions.ts
+function netFilterOpts(cmd) {
+  return cmd.option("--filter <substr>", "url substring filter").option("--status <bucket>", "ok | redirect | client_error | server_error | failed").option("--method <verb>", "exact method, e.g. POST").option("--limit <n>", "cap response length", (v) => Number(v));
+}
+function netFilterArgs(opts) {
+  const a = {};
+  if (opts.filter) a.filter = opts.filter;
+  if (opts.status) a.status = opts.status;
+  if (opts.method) a.method = opts.method;
+  if (typeof opts.limit === "number") a.limit = opts.limit;
+  return a;
+}
+function registerSessions(ctx) {
+  const { program, baseArgs, run } = ctx;
   const viewport = program.command("viewport").description("Emulate device viewport, DPR, mobile flag, touch, and user agent.").addHelpText(
     "after",
     `
@@ -683,46 +1015,6 @@ Notes:
   program.command("self-reload").description("Restart the chrome-relay extension's service worker (picks up newly built code).").action(async () => {
     await run("chrome_self_reload", {});
   });
-  tabOpt(
-    program.command("ax").description("Extract the accessibility tree \u2014 ~30\xD7 smaller than `read` and more semantic.").option("-i, --interactive-only", "filter to actionable roles (button, link, textbox, ...)").option("--root <role>", "start from the first node matching this role (e.g. 'main')").option("--include-subframes", "walk subframes too (default: top frame only)").addHelpText(
-      "after",
-      `
-
-Examples:
-  chrome-relay ax --tab 123
-  chrome-relay ax --tab 123 --interactive-only
-  chrome-relay ax --tab 123 --root main --interactive-only
-
-Notes:
-  Each node carries an "id" \u2014 that's the backendDOMNodeId. Pass it to
-  \`chrome-relay click-ax --node <id>\` to click without a CSS selector.
-`
-    )
-  ).action(async (opts) => {
-    const args = baseArgs(opts);
-    if (opts.interactiveOnly) args.interactiveOnly = true;
-    if (opts.root) args.rootRole = opts.root;
-    if (opts.includeSubframes) args.includeSubframes = true;
-    await run("chrome_ax", args);
-  });
-  tabOpt(
-    program.command("click-ax").description("Click an element by its backendDOMNodeId from a previous `ax` call.").requiredOption("--node <id>", "backendDOMNodeId from `chrome-relay ax`", (v) => Number(v)).addHelpText(
-      "after",
-      `
-
-Examples:
-  chrome-relay click-ax --tab 123 --node 456
-
-Notes:
-  Throws explicitly if the node id is stale (page mutated since you called
-  \`ax\`). Re-run \`ax\` and pass the fresh id.
-`
-    )
-  ).action(async (opts) => {
-    const args = baseArgs(opts);
-    args.node = opts.node;
-    await run("chrome_click_ax", args);
-  });
   const workspace = program.command("workspace").description("Manage named Chrome windows so multiple agents can drive separate windows.").addHelpText(
     "after",
     `
@@ -796,17 +1088,6 @@ Notes:
     const tabIds = String(opts.tabs).split(",").map((s) => Number(s.trim())).filter(Number.isFinite);
     await run("chrome_group", { action: "remove", tabIds });
   });
-  function netFilterOpts(cmd) {
-    return cmd.option("--filter <substr>", "url substring filter").option("--status <bucket>", "ok | redirect | client_error | server_error | failed").option("--method <verb>", "exact method, e.g. POST").option("--limit <n>", "cap response length", (v) => Number(v));
-  }
-  function netFilterArgs(opts) {
-    const a = {};
-    if (opts.filter) a.filter = opts.filter;
-    if (opts.status) a.status = opts.status;
-    if (opts.method) a.method = opts.method;
-    if (typeof opts.limit === "number") a.limit = opts.limit;
-    return a;
-  }
   const network = tabOpt(netFilterOpts(
     program.command("network").description("Capture HTTP request/response metadata. Ring buffer, last 200 per tab.")
   )).addHelpText(
@@ -896,171 +1177,41 @@ Notes:
     if (typeof opts.limit === "number") args.limit = opts.limit;
     await run("chrome_console", args);
   });
-  tabOpt(
-    program.command("hover [selector]").description("Move the pointer over an element or coordinates. Fires :hover styles.").option("--x <px>", "explicit x coordinate (CSS pixels)", (v) => Number(v)).option("--y <px>", "explicit y coordinate (CSS pixels)", (v) => Number(v)).addHelpText(
-      "after",
-      `
-
-Examples:
-  chrome-relay hover --tab 123 'button[title="Install runner"]'
-  chrome-relay hover --tab 123 --x 1327 --y 771
+}
 
-Use before screencast to capture hover-driven micro-states (button glow,
-tooltip appearance, etc.) that a bare click would skip past too quickly.
-`
-    )
-  ).action(async (selector, opts) => {
-    const args = {};
-    Object.assign(args, baseArgs(opts));
-    if (selector) args.selector = selector;
-    if (typeof opts.x === "number" && typeof opts.y === "number") {
-      args.x = opts.x;
-      args.y = opts.y;
-    }
-    await run("chrome_hover", args);
-  });
-  const screencast = program.command("screencast").description("Record a tab via CDP (paint-driven). Requires an active tab.").addHelpText(
+// src/program.ts
+function buildProgram() {
+  const program = new Command();
+  program.name("chrome-relay").description("Connect your local Chrome browser to coding agents through a local bridge.").version(CHROME_RELAY_VERSION).showHelpAfterError().option("--workspace <name>", "target the active tab in a named workspace window (works at top level too)").option("--group <name>", "target the active tab in a named tab-group (works at top level too)").enablePositionalOptions().addHelpText(
     "after",
     `
 
-Examples:
-  chrome-relay screencast start --tab 123 --quality 80 --max-width 900
-  # ... drive the interaction (hover, click, etc.) ...
-  chrome-relay screencast stop --tab 123 --out /tmp/recording
-
-  # The --out path becomes a directory of frame_NNNN.jpg files. If ffmpeg
-  # is on PATH and --gif is also passed, an animated GIF is written next to
-  # the frames at /tmp/recording.gif.
+Common agent flow:
+  chrome-relay tabs
+  chrome-relay navigate --tab <tabId> "https://example.com"
+  chrome-relay read --tab <tabId> -i
+  chrome-relay click --tab <tabId> "<selector>"
+  chrome-relay fill --tab <tabId> "<selector>" "value"
+  chrome-relay type --tab <tabId> -s "<selector>" "text into rich editor"
+  chrome-relay keys --tab <tabId> Enter
+  chrome-relay js --tab <tabId> "return document.title"
+  chrome-relay screenshot --tab <tabId> -o evidence.png
 
 Notes:
-  Frames buffer in the extension service worker. A 10-second capture at
-  default settings (jpeg q=60, ~15fps, full viewport) lands ~2-3 MB.
-  Pass --max-width to downscale and lighten the buffer.
-  Each frame is base64 JPEG; the CLI decodes them when --out is given.
+  navigate takes a URL. Use --tab to target an existing tab.
+  Tools attach via CDP and run on backgrounded tabs without stealing focus.
 `
   );
-  tabOpt(
-    screencast.command("start").description("Begin screencast capture on a tab.").option("--format <fmt>", "jpeg | png (default jpeg)").option("--quality <n>", "jpeg quality 0-100 (default 80)", (v) => Number(v)).option("--max-width <px>", "downscale; aspect preserved", (v) => Number(v)).option("--max-height <px>", "downscale; aspect preserved", (v) => Number(v)).option("--every-nth <n>", "throttle: keep 1 in N frames (default 1)", (v) => Number(v))
-  ).action(async (opts) => {
-    const args = { action: "start" };
-    Object.assign(args, baseArgs(opts));
-    if (opts.format) args.format = opts.format;
-    if (typeof opts.quality === "number") args.quality = opts.quality;
-    if (typeof opts.maxWidth === "number") args.maxWidth = opts.maxWidth;
-    if (typeof opts.maxHeight === "number") args.maxHeight = opts.maxHeight;
-    if (typeof opts.everyNth === "number") args.everyNthFrame = opts.everyNth;
-    await run("chrome_screencast", args);
-  });
-  tabOpt(
-    screencast.command("stop").description("Stop the screencast and emit frames (or write to disk).").option("-o, --out <dir>", "write frames as JPEGs into this directory (created if missing)").option("--gif", "after writing frames, ffmpeg them into <dir>.gif").option("--mp4", "after writing frames, ffmpeg them into <dir>.mp4").option("--fps <n>", "assumed framerate when invoking ffmpeg (default 15)", (v) => Number(v)).option("--no-dedupe", "keep raw frames; default collapses consecutive identical frames via SHA-256")
-  ).action(async (opts) => {
-    const args = { action: "stop" };
-    Object.assign(args, baseArgs(opts));
-    try {
-      const result = await callTool("chrome_screencast", args);
-      if (!opts.out) {
-        const { frames, ...summary } = result;
-        process.stdout.write(JSON.stringify({ ...summary, framesOmitted: frames.length, hint: "pass --out <dir> to save" }, null, 2) + "\n");
-        return;
-      }
-      const { mkdirSync, writeFileSync: writeFileSync2, renameSync, unlinkSync } = await import("fs");
-      const path2 = await import("path");
-      const { createHash } = await import("crypto");
-      mkdirSync(opts.out, { recursive: true });
-      result.frames.forEach((f, i) => {
-        const name = `frame_${String(i + 1).padStart(4, "0")}.jpg`;
-        writeFileSync2(path2.join(opts.out, name), Buffer.from(f.data, "base64"));
-      });
-      process.stdout.write(`Wrote ${result.frames.length} frames to ${opts.out}
-`);
-      const dedupeOn = opts.dedupe !== false;
-      if (dedupeOn && result.frames.length > 1) {
-        const hashes = result.frames.map(
-          (f) => createHash("sha256").update(Buffer.from(f.data, "base64")).digest("hex")
-        );
-        const kept = [];
-        let prev = "";
-        hashes.forEach((h, i) => {
-          if (h !== prev) kept.push(i);
-          prev = h;
-        });
-        const dropped = result.frames.length - kept.length;
-        if (dropped > 0) {
-          for (let i = 0; i < result.frames.length; i++) {
-            const src = path2.join(opts.out, `frame_${String(i + 1).padStart(4, "0")}.jpg`);
-            try {
-              unlinkSync(src);
-            } catch {
-            }
-          }
-          kept.forEach((srcIdx, newIdx) => {
-            const tmp = path2.join(opts.out, `tmp_${String(newIdx + 1).padStart(4, "0")}.jpg`);
-            writeFileSync2(tmp, Buffer.from(result.frames[srcIdx].data, "base64"));
-          });
-          kept.forEach((_, newIdx) => {
-            const tmp = path2.join(opts.out, `tmp_${String(newIdx + 1).padStart(4, "0")}.jpg`);
-            const final = path2.join(opts.out, `frame_${String(newIdx + 1).padStart(4, "0")}.jpg`);
-            renameSync(tmp, final);
-          });
-          process.stdout.write(`Deduped: dropped ${dropped} identical frames, ${kept.length} remain.
-`);
-        } else {
-          process.stdout.write(`Deduped: no consecutive duplicates found.
-`);
-        }
-      }
-      if (opts.gif || opts.mp4) {
-        const fps = typeof opts.fps === "number" ? opts.fps : 15;
-        const { spawnSync } = await import("child_process");
-        const which = spawnSync("which", ["ffmpeg"]);
-        if (which.status !== 0) {
-          process.stderr.write("[chrome-relay] ffmpeg not on PATH \u2014 skipping --gif/--mp4.\n");
-          return;
-        }
-        if (opts.gif) {
-          const gifOut = `${opts.out.replace(/\/$/, "")}.gif`;
-          const r = spawnSync("ffmpeg", [
-            "-y",
-            "-framerate",
-            String(fps),
-            "-i",
-            path2.join(opts.out, "frame_%04d.jpg"),
-            "-vf",
-            `fps=${fps},split[s0][s1];[s0]palettegen[p];[s1][p]paletteuse`,
-            "-loop",
-            "0",
-            gifOut
-          ], { stdio: "inherit" });
-          if (r.status === 0) process.stdout.write(`Wrote ${gifOut}
-`);
-        }
-        if (opts.mp4) {
-          const mp4Out = `${opts.out.replace(/\/$/, "")}.mp4`;
-          const r = spawnSync("ffmpeg", [
-            "-y",
-            "-framerate",
-            String(fps),
-            "-i",
-            path2.join(opts.out, "frame_%04d.jpg"),
-            "-c:v",
-            "libx264",
-            "-pix_fmt",
-            "yuv420p",
-            "-crf",
-            "20",
-            mp4Out
-          ], { stdio: "inherit" });
-          if (r.status === 0) process.stdout.write(`Wrote ${mp4Out}
-`);
-        }
-      }
-    } catch (error) {
-      process.stderr.write(
-        (error instanceof Error ? error.message : String(error)) + "\n"
-      );
-      process.exit(1);
-    }
-  });
+  const ctx = {
+    program,
+    baseArgs: makeBaseArgs(program),
+    run: runTool
+  };
+  registerInstallUpdate(program);
+  registerNavigation(ctx);
+  registerInput(ctx);
+  registerCapture(ctx);
+  registerSessions(ctx);
   return program;
 }
 

package/dist/index.js

@@ -1,5 +1,5 @@
 // src/index.ts
-var CHROME_RELAY_VERSION = true ? "0.5.8" : "0.0.0-dev";
+var CHROME_RELAY_VERSION = true ? "0.5.10" : "0.0.0-dev";
 export {
   CHROME_RELAY_VERSION
 };

package/dist/native-host.js

@@ -48,7 +48,7 @@ function toBridgeError(unknownErr, fallbackTool) {
 }
 
 // src/index.ts
-var CHROME_RELAY_VERSION = true ? "0.5.8" : "0.0.0-dev";
+var CHROME_RELAY_VERSION = true ? "0.5.10" : "0.0.0-dev";
 
 // src/release-notes.ts
 function compareSemver(a, b) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chrome-relay",
-  "version": "0.5.8",
+  "version": "0.5.10",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",