chrome-relay 0.5.22 → 0.6.0

package/dist/cli.js

@@ -228,140 +228,6 @@ var init_navigate = __esm({
   }
 });
 
-// ../protocol/dist/args/hover.js
-function parseChromeHoverArgs(input) {
-  const obj = asObject(input, TOOL_NAMES.HOVER);
-  const target = parseTargetArgs(obj, TOOL_NAMES.HOVER);
-  const x = optNumber(obj, "x", TOOL_NAMES.HOVER);
-  const y = optNumber(obj, "y", TOOL_NAMES.HOVER);
-  if (x !== void 0 !== (y !== void 0)) {
-    throw new RelayError({
-      code: "invalid_arguments",
-      message: "chrome_hover: pass BOTH x and y, or neither (selector mode).",
-      tool: TOOL_NAMES.HOVER,
-      phase: "parse_arguments",
-      details: { received: { x: obj.x, y: obj.y } },
-      retryable: false
-    });
-  }
-  if (x !== void 0 && y !== void 0) {
-    return { ...target, kind: "coords", x, y };
-  }
-  const selector = optString(obj, "selector", TOOL_NAMES.HOVER);
-  if (selector) {
-    return { ...target, kind: "selector", selector };
-  }
-  throw new RelayError({
-    code: "invalid_arguments",
-    message: "chrome_hover requires either a selector or x AND y.",
-    tool: TOOL_NAMES.HOVER,
-    phase: "parse_arguments",
-    details: { received: { selector: obj.selector, x: obj.x, y: obj.y } },
-    retryable: false
-  });
-}
-var init_hover = __esm({
-  "../protocol/dist/args/hover.js"() {
-    "use strict";
-    init_dist();
-    init_shared();
-  }
-});
-
-// ../protocol/dist/args/network.js
-function parseFilter(obj) {
-  const out = {};
-  const filter = optString(obj, "filter");
-  if (filter)
-    out.filter = filter;
-  const method = optString(obj, "method");
-  if (method)
-    out.method = method;
-  const limit = optNumber(obj, "limit");
-  if (limit !== void 0)
-    out.limit = limit;
-  const status = obj.status;
-  if (status !== void 0 && status !== null) {
-    if (typeof status !== "string" || !VALID_STATUSES.includes(status)) {
-      throw new RelayError({
-        code: "invalid_arguments",
-        message: `chrome_network: invalid status ${JSON.stringify(status)}. Expected one of: ${VALID_STATUSES.join(", ")}.`,
-        tool: TOOL_NAMES.NETWORK,
-        phase: "parse_status",
-        details: { received: status, validChoices: VALID_STATUSES },
-        retryable: false
-      });
-    }
-    out.status = status;
-  }
-  return out;
-}
-function parseChromeNetworkArgs(input) {
-  const obj = asObject(input, TOOL_NAMES.NETWORK);
-  const target = parseTargetArgs(obj);
-  const rawAction = obj.action;
-  const action = typeof rawAction === "string" ? rawAction : "read";
-  if (action === "clear") {
-    return { ...target, action: "clear" };
-  }
-  if (action === "body") {
-    const requestId = optString(obj, "requestId");
-    if (!requestId) {
-      throw new RelayError({
-        code: "invalid_arguments",
-        message: "chrome_network body requires `requestId` (a non-empty string).",
-        tool: TOOL_NAMES.NETWORK,
-        phase: "parse_arguments",
-        details: { field: "requestId", received: obj.requestId },
-        retryable: false
-      });
-    }
-    const out = {
-      ...target,
-      action: "body",
-      requestId
-    };
-    const full = optBool(obj, "full");
-    if (full !== void 0)
-      out.full = full;
-    const head = optPositiveNumber(obj, "head", TOOL_NAMES.NETWORK);
-    if (head !== void 0)
-      out.head = head;
-    return out;
-  }
-  if (action === "har") {
-    const withBodies = optBool(obj, "withBodies");
-    const bestEffortBodies = optBool(obj, "bestEffortBodies");
-    return {
-      ...target,
-      action: "har",
-      ...withBodies !== void 0 ? { withBodies } : {},
-      ...bestEffortBodies !== void 0 ? { bestEffortBodies } : {},
-      ...parseFilter(obj)
-    };
-  }
-  if (action === "read") {
-    return { ...target, action: "read", ...parseFilter(obj) };
-  }
-  throw new RelayError({
-    code: "invalid_arguments",
-    message: `chrome_network: unknown action "${action}". Expected read | clear | har | body.`,
-    tool: TOOL_NAMES.NETWORK,
-    phase: "parse_action",
-    details: { received: action, validChoices: ["read", "clear", "har", "body"] },
-    retryable: false
-  });
-}
-var VALID_STATUSES;
-var init_network = __esm({
-  "../protocol/dist/args/network.js"() {
-    "use strict";
-    init_dist();
-    init_shared();
-    VALID_STATUSES = ["ok", "redirect", "client_error", "server_error", "failed"];
-  }
-});
-
 // ../protocol/dist/args/simple.js
 function parseGetWindowsAndTabsArgs(input) {
   if (input !== void 0 && input !== null)
@@ -381,6 +247,25 @@ function parseChromeReadPageArgs(input) {
     out.interactiveOnly = io;
   return out;
 }
+function rejectMixedAddressing(tool, obj, modes) {
+  const present = [];
+  if (modes.ref)
+    present.push("ref");
+  if (modes.selector)
+    present.push("selector");
+  if (modes.coords)
+    present.push("x/y");
+  if (present.length > 1) {
+    throw new RelayError({
+      code: "invalid_arguments",
+      message: `${tool}: ${present.join(" + ")} are mutually exclusive \u2014 pass exactly one addressing mode.`,
+      tool,
+      phase: "parse_arguments",
+      details: { received: present },
+      retryable: false
+    });
+  }
+}
 function parseChromeClickArgs(input) {
   const obj = asObject(input, TOOL_NAMES.CLICK);
   const target = parseTargetArgs(obj, TOOL_NAMES.CLICK);
@@ -396,19 +281,24 @@ function parseChromeClickArgs(input) {
       retryable: false
     });
   }
+  const ref = optString(obj, "ref", TOOL_NAMES.CLICK);
+  const selector = optString(obj, "selector", TOOL_NAMES.CLICK);
+  rejectMixedAddressing(TOOL_NAMES.CLICK, obj, { ref, selector, coords: x !== void 0 });
+  if (ref) {
+    return { ...target, kind: "ref", ref };
+  }
   if (x !== void 0 && y !== void 0) {
     return { ...target, kind: "coords", x, y };
   }
-  const selector = optString(obj, "selector", TOOL_NAMES.CLICK);
   if (selector) {
     return { ...target, kind: "selector", selector };
   }
   throw new RelayError({
     code: "invalid_arguments",
-    message: "chrome_click_element requires either a selector or x AND y.",
+    message: "chrome_click_element requires a @ref, a selector, or x AND y.",
     tool: TOOL_NAMES.CLICK,
     phase: "parse_arguments",
-    details: { received: { selector: obj.selector, x: obj.x, y: obj.y } },
+    details: { received: { ref: obj.ref, selector: obj.selector, x: obj.x, y: obj.y } },
     retryable: false
   });
 }
@@ -424,10 +314,18 @@ function parseChromeFillArgs(input) {
       retryable: false
     });
   }
+  const target = parseTargetArgs(obj);
+  const ref = optString(obj, "ref", TOOL_NAMES.FILL);
+  const selector = optString(obj, "selector", TOOL_NAMES.FILL);
+  rejectMixedAddressing(TOOL_NAMES.FILL, obj, { ref, selector });
+  if (ref) {
+    return { ...target, kind: "ref", ref, value: obj.value };
+  }
   return {
+    ...target,
+    kind: "selector",
     selector: requireString(obj, "selector", TOOL_NAMES.FILL),
-    value: obj.value,
-    ...parseTargetArgs(obj)
+    value: obj.value
   };
 }
 function parseChromeKeyboardArgs(input) {
@@ -444,8 +342,12 @@ function parseChromeTypeArgs(input) {
     ...parseTargetArgs(obj)
   };
   const selector = optString(obj, "selector");
+  const ref = optString(obj, "ref", TOOL_NAMES.TYPE);
+  rejectMixedAddressing(TOOL_NAMES.TYPE, obj, { ref, selector });
   if (selector)
     out.selector = selector;
+  if (ref)
+    out.ref = ref;
   return out;
 }
 function parseChromeEvaluateArgs(input) {
@@ -525,6 +427,23 @@ function parseChromeClickAxArgs(input) {
   }
   return { node, ...parseTargetArgs(obj) };
 }
+function parseChromeSnapshotArgs(input) {
+  const obj = asObject(input, TOOL_NAMES.SNAPSHOT);
+  const out = { ...parseTargetArgs(obj, TOOL_NAMES.SNAPSHOT) };
+  const io = optBool(obj, "interactiveOnly", TOOL_NAMES.SNAPSHOT);
+  if (io !== void 0)
+    out.interactiveOnly = io;
+  const depth = optPositiveNumber(obj, "depth", TOOL_NAMES.SNAPSHOT);
+  if (depth !== void 0)
+    out.depth = depth;
+  const scope = optString(obj, "scope", TOOL_NAMES.SNAPSHOT);
+  if (scope)
+    out.scope = scope;
+  const urls = optBool(obj, "urls", TOOL_NAMES.SNAPSHOT);
+  if (urls !== void 0)
+    out.urls = urls;
+  return out;
+}
 function parseChromeScreenshotArgs(input) {
   const obj = asObject(input, TOOL_NAMES.SCREENSHOT);
   const out = { ...parseTargetArgs(obj, TOOL_NAMES.SCREENSHOT) };
@@ -553,6 +472,146 @@ var init_simple = __esm({
   }
 });
 
+// ../protocol/dist/args/hover.js
+function parseChromeHoverArgs(input) {
+  const obj = asObject(input, TOOL_NAMES.HOVER);
+  const target = parseTargetArgs(obj, TOOL_NAMES.HOVER);
+  const x = optNumber(obj, "x", TOOL_NAMES.HOVER);
+  const y = optNumber(obj, "y", TOOL_NAMES.HOVER);
+  if (x !== void 0 !== (y !== void 0)) {
+    throw new RelayError({
+      code: "invalid_arguments",
+      message: "chrome_hover: pass BOTH x and y, or neither (selector mode).",
+      tool: TOOL_NAMES.HOVER,
+      phase: "parse_arguments",
+      details: { received: { x: obj.x, y: obj.y } },
+      retryable: false
+    });
+  }
+  const ref = optString(obj, "ref", TOOL_NAMES.HOVER);
+  const selector = optString(obj, "selector", TOOL_NAMES.HOVER);
+  rejectMixedAddressing(TOOL_NAMES.HOVER, obj, { ref, selector, coords: x !== void 0 });
+  if (ref) {
+    return { ...target, kind: "ref", ref };
+  }
+  if (x !== void 0 && y !== void 0) {
+    return { ...target, kind: "coords", x, y };
+  }
+  if (selector) {
+    return { ...target, kind: "selector", selector };
+  }
+  throw new RelayError({
+    code: "invalid_arguments",
+    message: "chrome_hover requires a @ref, a selector, or x AND y.",
+    tool: TOOL_NAMES.HOVER,
+    phase: "parse_arguments",
+    details: { received: { ref: obj.ref, selector: obj.selector, x: obj.x, y: obj.y } },
+    retryable: false
+  });
+}
+var init_hover = __esm({
+  "../protocol/dist/args/hover.js"() {
+    "use strict";
+    init_dist();
+    init_shared();
+    init_simple();
+  }
+});
+
+// ../protocol/dist/args/network.js
+function parseFilter(obj) {
+  const out = {};
+  const filter = optString(obj, "filter");
+  if (filter)
+    out.filter = filter;
+  const method = optString(obj, "method");
+  if (method)
+    out.method = method;
+  const limit = optNumber(obj, "limit");
+  if (limit !== void 0)
+    out.limit = limit;
+  const status = obj.status;
+  if (status !== void 0 && status !== null) {
+    if (typeof status !== "string" || !VALID_STATUSES.includes(status)) {
+      throw new RelayError({
+        code: "invalid_arguments",
+        message: `chrome_network: invalid status ${JSON.stringify(status)}. Expected one of: ${VALID_STATUSES.join(", ")}.`,
+        tool: TOOL_NAMES.NETWORK,
+        phase: "parse_status",
+        details: { received: status, validChoices: VALID_STATUSES },
+        retryable: false
+      });
+    }
+    out.status = status;
+  }
+  return out;
+}
+function parseChromeNetworkArgs(input) {
+  const obj = asObject(input, TOOL_NAMES.NETWORK);
+  const target = parseTargetArgs(obj);
+  const rawAction = obj.action;
+  const action = typeof rawAction === "string" ? rawAction : "read";
+  if (action === "clear") {
+    return { ...target, action: "clear" };
+  }
+  if (action === "body") {
+    const requestId = optString(obj, "requestId");
+    if (!requestId) {
+      throw new RelayError({
+        code: "invalid_arguments",
+        message: "chrome_network body requires `requestId` (a non-empty string).",
+        tool: TOOL_NAMES.NETWORK,
+        phase: "parse_arguments",
+        details: { field: "requestId", received: obj.requestId },
+        retryable: false
+      });
+    }
+    const out = {
+      ...target,
+      action: "body",
+      requestId
+    };
+    const full = optBool(obj, "full");
+    if (full !== void 0)
+      out.full = full;
+    const head = optPositiveNumber(obj, "head", TOOL_NAMES.NETWORK);
+    if (head !== void 0)
+      out.head = head;
+    return out;
+  }
+  if (action === "har") {
+    const withBodies = optBool(obj, "withBodies");
+    const bestEffortBodies = optBool(obj, "bestEffortBodies");
+    return {
+      ...target,
+      action: "har",
+      ...withBodies !== void 0 ? { withBodies } : {},
+      ...bestEffortBodies !== void 0 ? { bestEffortBodies } : {},
+      ...parseFilter(obj)
+    };
+  }
+  if (action === "read") {
+    return { ...target, action: "read", ...parseFilter(obj) };
+  }
+  throw new RelayError({
+    code: "invalid_arguments",
+    message: `chrome_network: unknown action "${action}". Expected read | clear | har | body.`,
+    tool: TOOL_NAMES.NETWORK,
+    phase: "parse_action",
+    details: { received: action, validChoices: ["read", "clear", "har", "body"] },
+    retryable: false
+  });
+}
+var VALID_STATUSES;
+var init_network = __esm({
+  "../protocol/dist/args/network.js"() {
+    "use strict";
+    init_dist();
+    init_shared();
+    VALID_STATUSES = ["ok", "redirect", "client_error", "server_error", "failed"];
+  }
+});
+
 // ../protocol/dist/args/multi.js
 function invalidAction(tool, received, expected) {
   throw new RelayError({
@@ -896,6 +955,8 @@ function parseToolArgs(name, input) {
       return parseChromeHoverArgs(input);
     case "chrome_screencast":
       return parseChromeScreencastArgs(input);
+    case "chrome_snapshot":
+      return parseChromeSnapshotArgs(input);
   }
   const exhaustive = name;
   return exhaustive;
@@ -936,6 +997,78 @@ var init_limits = __esm({
   }
 });
 
+// ../protocol/dist/snapshot.js
+function parseRefToken(input) {
+  const m = REF_TOKEN.exec(input.trim());
+  return m ? m[1] : null;
+}
+function formatRefToken(ref) {
+  return `@${ref}`;
+}
+function renderAttrs(node) {
+  const parts = [];
+  const attrs = node.attrs;
+  if (attrs) {
+    for (const key of ATTR_ORDER) {
+      if (key === "url")
+        continue;
+      const v = attrs[key];
+      if (v === void 0)
+        continue;
+      if (v === true)
+        parts.push(key);
+      else
+        parts.push(`${key}=${v}`);
+    }
+  }
+  if (node.ref)
+    parts.push(`ref=${node.ref}`);
+  if (attrs?.url)
+    parts.push(`url=${attrs.url}`);
+  return parts.length > 0 ? ` [${parts.join(", ")}]` : "";
+}
+function renderNode(node, depth, out) {
+  const indent = "  ".repeat(depth);
+  let line = `${indent}- ${node.role}`;
+  if (node.name)
+    line += ` ${JSON.stringify(node.name)}`;
+  line += renderAttrs(node);
+  if (node.value !== void 0 && node.value !== node.name) {
+    line += `: ${node.value}`;
+  }
+  out.push(line);
+  for (const child of node.children ?? []) {
+    renderNode(child, depth + 1, out);
+  }
+}
+function renderSnapshot(data) {
+  const nodes = data.nodes ?? [];
+  const out = [`Page: ${data.title ?? ""}`, `URL: ${data.url ?? ""}`, `Tab: ${data.tabId ?? "?"}`, ""];
+  for (const node of nodes)
+    renderNode(node, 0, out);
+  if (nodes.length === 0)
+    out.push("(empty snapshot \u2014 page may still be loading)");
+  return out.join("\n");
+}
+var REF_TOKEN, ATTR_ORDER;
+var init_snapshot = __esm({
+  "../protocol/dist/snapshot.js"() {
+    "use strict";
+    REF_TOKEN = /^@(e\d+)$/;
+    ATTR_ORDER = [
+      "level",
+      "checked",
+      "expanded",
+      "selected",
+      "disabled",
+      "required",
+      "readonly",
+      "pressed",
+      "url"
+    ];
+  }
+});
+
 // ../protocol/dist/index.js
 var dist_exports = {};
 __export(dist_exports, {
@@ -961,6 +1094,7 @@ __export(dist_exports, {
   TOOL_NAMES: () => TOOL_NAMES,
   asObject: () => asObject,
   coerceTabId: () => coerceTabId,
+  formatRefToken: () => formatRefToken,
   optBool: () => optBool,
   optNonNegativeNumber: () => optNonNegativeNumber,
   optNumber: () => optNumber,
@@ -982,13 +1116,17 @@ __export(dist_exports, {
   parseChromeScreencastArgs: () => parseChromeScreencastArgs,
   parseChromeScreenshotArgs: () => parseChromeScreenshotArgs,
   parseChromeSelfReloadArgs: () => parseChromeSelfReloadArgs,
+  parseChromeSnapshotArgs: () => parseChromeSnapshotArgs,
   parseChromeSwitchTabArgs: () => parseChromeSwitchTabArgs,
   parseChromeTypeArgs: () => parseChromeTypeArgs,
   parseChromeViewportArgs: () => parseChromeViewportArgs,
   parseChromeWorkspaceArgs: () => parseChromeWorkspaceArgs,
   parseGetWindowsAndTabsArgs: () => parseGetWindowsAndTabsArgs,
+  parseRefToken: () => parseRefToken,
   parseTargetArgs: () => parseTargetArgs,
   parseToolArgs: () => parseToolArgs,
+  rejectMixedAddressing: () => rejectMixedAddressing,
+  renderSnapshot: () => renderSnapshot,
   requireString: () => requireString,
   toBridgeError: () => toBridgeError
 });
@@ -1010,6 +1148,7 @@ var init_dist = __esm({
     "use strict";
     init_args();
     init_limits();
+    init_snapshot();
     NATIVE_HOST_NAME = "dev.chrome_relay.native_host";
     DEFAULT_HTTP_PORT = 12122;
     CHROME_WEB_STORE_EXTENSION_ID = "cpdiapbifblhlcpnmlmfpgfjlacebokb";
@@ -1066,7 +1205,11 @@ var init_dist = __esm({
       // 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"
+      SCREENCAST: "chrome_screencast",
+      // Unified page snapshot (adoption-spec Change 1) — AX tree + cursor-
+      // interactive sweep, one ref space, compact text rendered CLI-side.
+      // Supersedes chrome_read_page and chrome_ax, which now alias to it.
+      SNAPSHOT: "chrome_snapshot"
     };
     RelayError = class extends Error {
       code;
@@ -1101,7 +1244,7 @@ var init_dist = __esm({
 import { Command } from "commander";
 
 // src/index.ts
-var CHROME_RELAY_VERSION = true ? "0.5.22" : "0.0.0-dev";
+var CHROME_RELAY_VERSION = true ? "0.6.0" : "0.0.0-dev";
 
 // src/commands/shared.ts
 init_dist();
@@ -1281,6 +1424,55 @@ function getChromiumBrowserTargets() {
       { label: "Opera", installRoot: path.join(config, "opera"), manifestDir: path.join(config, "opera/NativeMessagingHosts") }
     ];
   }
+  if (process.platform === "win32") {
+    const local = process.env.LOCALAPPDATA || path.join(home, "AppData", "Local");
+    const roaming = process.env.APPDATA || path.join(home, "AppData", "Roaming");
+    const manifestBase = path.join(APP_DIR, "NativeMessagingHosts");
+    return [
+      {
+        label: "Google Chrome",
+        installRoot: path.join(local, "Google", "Chrome", "User Data"),
+        manifestDir: path.join(manifestBase, "Google Chrome"),
+        registryKey: `HKCU\\Software\\Google\\Chrome\\NativeMessagingHosts\\${NATIVE_HOST_NAME}`
+      },
+      {
+        label: "Google Chrome Canary",
+        installRoot: path.join(local, "Google", "Chrome SxS", "User Data"),
+        manifestDir: path.join(manifestBase, "Google Chrome Canary"),
+        registryKey: `HKCU\\Software\\Google\\Chrome SxS\\NativeMessagingHosts\\${NATIVE_HOST_NAME}`
+      },
+      {
+        label: "Chromium",
+        installRoot: path.join(local, "Chromium", "User Data"),
+        manifestDir: path.join(manifestBase, "Chromium"),
+        registryKey: `HKCU\\Software\\Chromium\\NativeMessagingHosts\\${NATIVE_HOST_NAME}`
+      },
+      {
+        label: "Microsoft Edge",
+        installRoot: path.join(local, "Microsoft", "Edge", "User Data"),
+        manifestDir: path.join(manifestBase, "Microsoft Edge"),
+        registryKey: `HKCU\\Software\\Microsoft\\Edge\\NativeMessagingHosts\\${NATIVE_HOST_NAME}`
+      },
+      {
+        label: "Brave",
+        installRoot: path.join(local, "BraveSoftware", "Brave-Browser", "User Data"),
+        manifestDir: path.join(manifestBase, "Brave"),
+        registryKey: `HKCU\\Software\\BraveSoftware\\Brave-Browser\\NativeMessagingHosts\\${NATIVE_HOST_NAME}`
+      },
+      {
+        label: "Vivaldi",
+        installRoot: path.join(local, "Vivaldi", "User Data"),
+        manifestDir: path.join(manifestBase, "Vivaldi"),
+        registryKey: `HKCU\\Software\\Vivaldi\\NativeMessagingHosts\\${NATIVE_HOST_NAME}`
+      },
+      {
+        label: "Opera",
+        installRoot: path.join(roaming, "Opera Software", "Opera Stable"),
+        manifestDir: path.join(manifestBase, "Opera"),
+        registryKey: `HKCU\\Software\\Opera Software\\NativeMessagingHosts\\${NATIVE_HOST_NAME}`
+      }
+    ];
+  }
   throw new Error(`Unsupported platform for install: ${process.platform}`);
 }
 async function pathExists(p) {
@@ -1306,6 +1498,14 @@ function getDistDir() {
 }
 async function writeWrapperScript(hostPath) {
   await mkdir(APP_DIR, { recursive: true });
+  if (process.platform === "win32") {
+    const wrapperPath2 = path.join(APP_DIR, "run-host.cmd");
+    const content2 = `@echo off\r
+"${process.execPath}" "${hostPath}"\r
+`;
+    await writeFile(wrapperPath2, content2, "utf8");
+    return wrapperPath2;
+  }
   const wrapperPath = path.join(APP_DIR, "run-host.sh");
   const content = `#!/bin/sh
 exec "${process.execPath}" "${hostPath}"
@@ -1314,6 +1514,31 @@ exec "${process.execPath}" "${hostPath}"
   await chmod(wrapperPath, 493);
   return wrapperPath;
 }
+function registerWindowsNativeHost(registryKey, manifestPath) {
+  const res = spawnSync("reg.exe", [
+    "ADD",
+    registryKey,
+    "/ve",
+    "/t",
+    "REG_SZ",
+    "/d",
+    manifestPath,
+    "/f"
+  ], { encoding: "utf8" });
+  if (res.status !== 0) {
+    const detail = (res.stderr || res.stdout || "").trim();
+    throw new Error(`failed to register ${registryKey}${detail ? `: ${detail}` : ""}`);
+  }
+}
+function readWindowsNativeHostRegistry(registryKey) {
+  const res = spawnSync("reg.exe", ["QUERY", registryKey, "/ve"], { encoding: "utf8" });
+  if (res.status !== 0 || !res.stdout) return null;
+  for (const line of res.stdout.split("\n")) {
+    const match = line.match(/REG_SZ\s+(.+?)\s*$/);
+    if (match?.[1]) return match[1].trim();
+  }
+  return null;
+}
 async function writeManifestsForBrowsers(wrapperPath, browsers) {
   const manifest = {
     name: NATIVE_HOST_NAME,
@@ -1329,7 +1554,11 @@ async function writeManifestsForBrowsers(wrapperPath, browsers) {
     await mkdir(target.manifestDir, { recursive: true });
     const manifestPath = path.join(target.manifestDir, `${NATIVE_HOST_NAME}.json`);
     await writeFile(manifestPath, body, "utf8");
-    written.push({ browser: target.label, manifestPath });
+    if (process.platform === "win32") {
+      if (!target.registryKey) throw new Error(`missing registry key for ${target.label}`);
+      registerWindowsNativeHost(target.registryKey, manifestPath);
+    }
+    written.push({ browser: target.label, manifestPath, registryKey: target.registryKey });
   }
   return written;
 }
@@ -1373,6 +1602,9 @@ async function runInstall() {
   console.log(`Manifests written:`);
   for (const m of writtenManifests) {
     console.log(`  \u2022 ${m.browser}: ${m.manifestPath}`);
+    if (m.registryKey) {
+      console.log(`    registry: ${m.registryKey}`);
+    }
   }
   console.log(`Local bridge port: ${DEFAULT_HTTP_PORT}`);
   console.log(`Allowed extension IDs: ${formatKnownExtensionIds()}`);
@@ -1382,7 +1614,7 @@ async function runInstall() {
 }
 async function runDoctor() {
   try {
-    const wrapperPath = path.join(APP_DIR, "run-host.sh");
+    const wrapperPath = path.join(APP_DIR, process.platform === "win32" ? "run-host.cmd" : "run-host.sh");
     await stat(wrapperPath);
     console.log(`Wrapper present: yes`);
     const installed = await getInstalledBrowsers();
@@ -1402,6 +1634,14 @@ async function runDoctor() {
         console.log(`  \u2022 ${target.label}: manifest MISSING (${manifestPath})`);
         continue;
       }
+      if (process.platform === "win32" && target.registryKey) {
+        const registered = readWindowsNativeHostRegistry(target.registryKey);
+        if (path.normalize(registered || "") !== path.normalize(manifestPath)) {
+          allHealthy = false;
+          console.log(`  \u2022 ${target.label}: registry MISSING/STALE (${target.registryKey})`);
+          continue;
+        }
+      }
       try {
         const manifest = JSON.parse(await readFile(manifestPath, "utf8"));
         const allowedOrigins = Array.isArray(manifest.allowed_origins) ? manifest.allowed_origins : [];
@@ -1441,6 +1681,21 @@ async function runDoctor() {
 
 // src/release-notes.ts
 var RELEASE_NOTES = {
+  "0.6.0": [
+    "Unified `snapshot` with actionable @refs. `chrome-relay snapshot -i` renders the page as compact text (~4-5x smaller than the old `read -i`; 14 KB on the HN front page) \u2014 accessibility tree merged with a cursor-interactive sweep that catches div-soup clickables (cursor:pointer, onclick, tabindex, contenteditable) the AX tree misses. Every element gets a browser-unique @eN ref.",
+    'Refs are actionable everywhere: `click @e12`, `fill @e14 "v"`, `hover @e3`, `type -s @e7`. A ref carries its tab \u2014 no --tab needed, a contradicting --tab is target_conflict, so an agent can never click into the page the user is reading. Resolution is backendNodeId fast-path with role+name+nth healing on same-page DOM churn (healed clicks report `healed: true`). Refs reach inside shadow DOM, where CSS selectors can\'t.',
+    "Refs die on real navigation, deliberately: Chromium reuses backendNodeId integers in the new document, so a stale ref could silently click an unrelated element. Dead refs return the new `error.code = stale_ref` with a re-snapshot hint. SPA route changes (pushState) keep refs alive.",
+    "BREAKING: `read` and `ax` output changed. They are now aliases for `chrome_snapshot` and return the unified snapshot format (compact text / SnapshotData JSON) \u2014 the old `{elements: [{selector, bounds, ...}]}` and CompactAxNode shapes are gone, deliberately: keeping them would mean keeping the deleted walkers in parallel. Both print a deprecation notice; alias removal lands next minor. `click-ax` still works on raw backendNodeIds (now visible in `snapshot --json` refs).",
+    "Ref clicks hit-test before dispatch: if an unrelated element (overlay, sticky header, modal) owns the click point, the click fails with the new `error.code = click_intercepted` naming the interceptor \u2014 instead of reporting success while the overlay ate the click. Same-lineage hits (inner text, wrapping label) pass; fill/type skip the check (writing to a covered input is legitimate).",
+    "`snapshot --scope <css>` now bounds the cursor-interactive sweep too \u2014 a scoped snapshot never returns actionable refs for elements outside the scope subtree.",
+    "Error hygiene: in-page failures (bad selector, malformed CSS, zero-size element, unfocusable element) now map to structured codes (element_not_found, invalid_arguments) instead of internal_error with a raw JS stack.",
+    "Snapshot flags: -i (ref-bearing only), -d <n> (depth cap), -s <css> (scope to subtree), -u (include hrefs), --json (structured envelope incl. the refs map with backendNodeIds)."
+  ],
+  "0.5.23": [
+    "Windows native-host install. `chrome-relay install` now supports `win32`: it writes a `run-host.cmd` wrapper, writes browser-specific native-messaging manifests under `~/.chrome-relay/NativeMessagingHosts`, and registers each manifest through HKCU registry keys.",
+    "Detected Windows browsers: Chrome, Chrome Canary, Chromium, Edge, Brave, Vivaldi, and Opera. Detection uses the browser profile directory; if none are detected, install falls back to Chrome so a later Chrome install can find the host after re-running install.",
+    "`chrome-relay doctor` now checks the Windows wrapper and registry entries, so stale or missing native-host registration points at the failing browser instead of only showing a generic extension connection failure."
+  ],
   "0.5.22": [
     "Multi-browser install. `chrome-relay install` now writes the native-messaging manifest into every detected Chromium-fork browser's NativeMessagingHosts dir, not just Google Chrome's. Detected: Chrome, Chrome Canary, Chromium, Edge, Brave, Vivaldi, Arc, Opera (macOS + Linux paths). Detection is parent-dir existence \u2014 we never speculatively create profile dirs for browsers that aren't installed.",
     "Why this matters: the extension installs fine via Chrome Web Store in any Chromium fork, but the bridge silently failed because the host manifest was only at Chrome's path. Arc + Brave users hit `connectNative()` errors with no obvious cause.",
@@ -1761,34 +2016,48 @@ Use "chrome-relay switch ${url}" to activate that tab, or "chrome-relay navigate
 }
 
 // src/commands/input.ts
+init_dist();
+function addressArg(value) {
+  const ref = parseRefToken(value);
+  return ref ? { ref } : { selector: value };
+}
 function registerInput(ctx) {
   const { program, withBase, run } = ctx;
   tabOpt(
-    program.command("click [selector]").description("Click an element. Pass a CSS selector OR --x and --y for a coordinate click.").option("--x <px>", "explicit x coordinate (CSS pixels); requires --y", (v) => Number(v)).option("--y <px>", "explicit y coordinate (CSS pixels); requires --x", (v) => Number(v)).addHelpText(
+    program.command("click [target]").description("Click an element. Pass a @ref from `snapshot`, a CSS selector, OR --x/--y coordinates.").option("--x <px>", "explicit x coordinate (CSS pixels); requires --y", (v) => Number(v)).option("--y <px>", "explicit y coordinate (CSS pixels); requires --x", (v) => Number(v)).addHelpText(
       "after",
       `
 
 Examples:
+  chrome-relay click @e12
   chrome-relay click 'button[aria-label="Save"]'
   chrome-relay click --tab 123 --x 1327 --y 771
 
-Pick selector mode when the element has a stable CSS query. Pick
-coordinate mode when the page wraps content in unmarked divs (Cloudflare
-dashboard, Vercel dashboard, etc.) and you got the rect from a prior
-\`chrome-relay js\` call or a screenshot. See docs/clicking-strategies.md.
+Prefer @refs from \`chrome-relay snapshot\` \u2014 they carry their own tab and
+survive DOM churn (backendNodeId + role/name heal). CSS selectors for
+elements you know statically. Coordinates for canvas/SVG chart internals
+where no DOM handle exists. See docs/clicking-strategies.md.
 `
     )
-  ).action(async (selector, opts) => {
+  ).action(async (target, opts) => {
     const extras = {};
-    if (selector) extras.selector = selector;
+    if (target) Object.assign(extras, addressArg(target));
     if (typeof opts.x === "number") extras.x = opts.x;
     if (typeof opts.y === "number") extras.y = opts.y;
     await run("chrome_click_element", withBase(opts, extras));
   });
   tabOpt(
-    program.command("fill <selector> <value>").description("Fill an input or textarea.")
-  ).action(async (selector, value, opts) => {
-    await run("chrome_fill_or_select", withBase(opts, { selector, value }));
+    program.command("fill <target> <value>").description("Fill an input or textarea. Target is a @ref from `snapshot` or a CSS selector.").addHelpText(
+      "after",
+      `
+
+Examples:
+  chrome-relay fill @e4 "kushal@example.com"
+  chrome-relay fill 'input[name="email"]' "kushal@example.com"
+`
+    )
+  ).action(async (target, value, opts) => {
+    await run("chrome_fill_or_select", withBase(opts, { ...addressArg(target), value }));
   });
   tabOpt(
     program.command("keys <keys>").description("Press a single key or chord via trusted CDP input (e.g. Enter, Cmd+K).").addHelpText(
@@ -1808,7 +2077,7 @@ For typing text into a field, use \`chrome-relay type\` instead.
     await run("chrome_keyboard", withBase(opts, { keys }));
   });
   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("type <text>").description("Insert text via trusted CDP input. Works in contenteditable / Draft.js / Lexical.").option("-s, --selector <target>", "focus this element first (@ref or CSS selector)").addHelpText(
       "after",
       `
 
@@ -1825,7 +2094,7 @@ When to pick which:
     )
   ).action(async (text, opts) => {
     const extras = { text };
-    if (opts.selector) extras.selector = opts.selector;
+    if (opts.selector) Object.assign(extras, addressArg(opts.selector));
     await run("chrome_type", withBase(opts, extras));
   });
   tabOpt(
@@ -1850,7 +2119,7 @@ Notes:
     await run("chrome_evaluate", withBase(opts, extras));
   });
   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(
+    program.command("hover [target]").description("Move the pointer over an element (@ref or CSS selector) 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",
       `
 
@@ -1862,9 +2131,9 @@ 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) => {
+  ).action(async (target, opts) => {
     const extras = {};
-    if (selector) extras.selector = selector;
+    if (target) Object.assign(extras, addressArg(target));
     if (typeof opts.x === "number") extras.x = opts.x;
     if (typeof opts.y === "number") extras.y = opts.y;
     await run("chrome_hover", withBase(opts, extras));
@@ -1872,9 +2141,56 @@ tooltip appearance, etc.) that a bare click would skip past too quickly.
 }
 
 // src/commands/capture.ts
+init_dist();
 import { writeFileSync } from "fs";
+function printSnapshot(result, asJson) {
+  if (asJson) {
+    process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+    return;
+  }
+  process.stdout.write(renderSnapshot(result) + "\n");
+}
+function exitWithError(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);
+}
 function registerCapture(ctx) {
   const { program, withBase, run } = ctx;
+  tabOpt(
+    program.command("snapshot").description("Page snapshot with actionable @refs \u2014 accessibility tree + cursor-interactive sweep, compact text.").option("-i, --interactive", "only ref-bearing elements (buttons, links, inputs, named content, clickables)").option("-d, --depth <n>", "truncate the tree at this depth", (v) => Number(v)).option("-s, --scope <css>", "restrict to the subtree of the first CSS match").option("-u, --urls", "include link hrefs as url= attrs").option("--json", "structured output: { title, url, tabId, nodes, refs }").addHelpText(
+      "after",
+      `
+
+Examples:
+  chrome-relay snapshot -i                 # see the page, get @refs
+  chrome-relay click @e12                  # act on a ref \u2014 no --tab needed
+  chrome-relay snapshot -i -s "#main"      # scope to a subtree
+  chrome-relay snapshot --json             # machine-readable envelope
+
+The core loop: snapshot -i \u2192 click/fill @eN \u2192 snapshot -i again after the
+page changes. Refs carry their own tab and heal across DOM churn
+(backendNodeId fast path + role/name re-find); a dead ref returns
+error.code = stale_ref, which means: re-run snapshot.
+`
+    )
+  ).action(async (opts) => {
+    const extras = {};
+    if (opts.interactive) extras.interactiveOnly = true;
+    if (typeof opts.depth === "number") extras.depth = opts.depth;
+    if (opts.scope) extras.scope = opts.scope;
+    if (opts.urls) extras.urls = true;
+    try {
+      const result = await callTool("chrome_snapshot", withBase(opts, extras));
+      printSnapshot(result, opts.json === true);
+    } catch (error) {
+      exitWithError(error);
+    }
+  });
   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",
@@ -1914,43 +2230,37 @@ full-tab screenshot when an agent only needs to see one component.
       }
       process.stdout.write(JSON.stringify(result, null, 2) + "\n");
     } catch (error) {
-      process.stderr.write(
-        (error instanceof Error ? error.message : String(error)) + "\n"
-      );
-      process.exit(1);
+      exitWithError(error);
     }
   });
   tabOpt(
-    program.command("read").description("Extract page structure and interactive elements.").option("-i, --interactive", "return only interactive elements")
+    program.command("read").description("[deprecated \u2014 use `snapshot`] Alias for the unified snapshot.").option("-i, --interactive", "only ref-bearing elements").option("--json", "structured output")
   ).action(async (opts) => {
+    process.stderr.write("[chrome-relay] deprecated: `read` is now an alias for `snapshot` (new output format). Use `chrome-relay snapshot`.\n");
     const extras = {};
     if (opts.interactive) extras.interactiveOnly = true;
-    await run("chrome_read_page", withBase(opts, extras));
+    try {
+      const result = await callTool("chrome_read_page", withBase(opts, extras));
+      printSnapshot(result, opts.json === true);
+    } catch (error) {
+      exitWithError(error);
+    }
   });
   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.
-`
-    )
+    program.command("ax").description("[deprecated \u2014 use `snapshot`] Alias for the unified snapshot.").option("-i, --interactive-only", "only ref-bearing elements").option("--root <role>", "(ignored \u2014 use `snapshot --scope <css>`)").option("--include-subframes", "(ignored \u2014 snapshot is top-frame only)").option("--json", "structured output")
   ).action(async (opts) => {
+    process.stderr.write("[chrome-relay] deprecated: `ax` is now an alias for `snapshot` (new output format, one ref space). Use `chrome-relay snapshot`.\n");
     const extras = {};
     if (opts.interactiveOnly) extras.interactiveOnly = true;
-    if (opts.root) extras.rootRole = opts.root;
-    if (opts.includeSubframes) extras.includeSubframes = true;
-    await run("chrome_ax", withBase(opts, extras));
+    try {
+      const result = await callTool("chrome_ax", withBase(opts, extras));
+      printSnapshot(result, opts.json === true);
+    } catch (error) {
+      exitWithError(error);
+    }
   });
   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(
+    program.command("click-ax").description("[deprecated \u2014 use `click @eN`] Click by raw backendDOMNodeId (from `snapshot --json` refs).").requiredOption("--node <id>", "backendDOMNodeId from `chrome-relay ax`", (v) => Number(v)).addHelpText(
       "after",
       `
 

package/dist/index.js

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

package/dist/native-host.js

@@ -56,7 +56,7 @@ function toBridgeError(unknownErr, fallbackTool) {
 }
 
 // src/index.ts
-var CHROME_RELAY_VERSION = true ? "0.5.22" : "0.0.0-dev";
+var CHROME_RELAY_VERSION = true ? "0.6.0" : "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.22",
+  "version": "0.6.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",