chrome-relay 0.5.22 → 0.7.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,26 @@ 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;
+  const diff = optBool(obj, "diff", TOOL_NAMES.SNAPSHOT);
+  if (diff !== void 0)
+    out.diff = diff;
+  return out;
+}
 function parseChromeScreenshotArgs(input) {
   const obj = asObject(input, TOOL_NAMES.SCREENSHOT);
   const out = { ...parseTargetArgs(obj, TOOL_NAMES.SCREENSHOT) };
@@ -545,11 +467,151 @@ function parseChromeScreenshotArgs(input) {
     out.maxEdge = me;
   return out;
 }
-var init_simple = __esm({
-  "../protocol/dist/args/simple.js"() {
+var init_simple = __esm({
+  "../protocol/dist/args/simple.js"() {
+    "use strict";
+    init_dist();
+    init_shared();
+  }
+});
+
+// ../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"];
   }
 });
 
@@ -851,6 +913,170 @@ var init_multi = __esm({
   }
 });
 
+// ../protocol/dist/limits.js
+var DEFAULT_TOOL_CALL_TIMEOUT_MS, DEFAULT_PING_TIMEOUT_MS, DEFAULT_READY_TIMEOUT_MS, DEFAULT_EVAL_TIMEOUT_MS, DEFAULT_BODY_PREVIEW_BYTES, DEFAULT_WAIT_TIMEOUT_MS, MAX_WAIT_TIMEOUT_MS, WAIT_POLL_INTERVAL_MS, NETWORKIDLE_QUIET_MS, MAX_BATCH_COMMANDS, MAX_BATCH_BYTES, NETWORK_BUFFER_MAX_ENTRIES, NETWORK_BUFFER_MAX_BYTES, CONSOLE_BUFFER_MAX_ENTRIES, CONSOLE_BUFFER_MAX_BYTES, CONSOLE_ENTRY_TEXT_MAX_CHARS, CONSOLE_ENTRY_STACK_MAX_CHARS;
+var init_limits = __esm({
+  "../protocol/dist/limits.js"() {
+    "use strict";
+    DEFAULT_TOOL_CALL_TIMEOUT_MS = 3e4;
+    DEFAULT_PING_TIMEOUT_MS = 2e3;
+    DEFAULT_READY_TIMEOUT_MS = 15e3;
+    DEFAULT_EVAL_TIMEOUT_MS = 15e3;
+    DEFAULT_BODY_PREVIEW_BYTES = 8 * 1024;
+    DEFAULT_WAIT_TIMEOUT_MS = 1e4;
+    MAX_WAIT_TIMEOUT_MS = 25e3;
+    WAIT_POLL_INTERVAL_MS = 100;
+    NETWORKIDLE_QUIET_MS = 500;
+    MAX_BATCH_COMMANDS = 50;
+    MAX_BATCH_BYTES = 9e5;
+    NETWORK_BUFFER_MAX_ENTRIES = 200;
+    NETWORK_BUFFER_MAX_BYTES = 512 * 1024;
+    CONSOLE_BUFFER_MAX_ENTRIES = 200;
+    CONSOLE_BUFFER_MAX_BYTES = 256 * 1024;
+    CONSOLE_ENTRY_TEXT_MAX_CHARS = 1e3;
+    CONSOLE_ENTRY_STACK_MAX_CHARS = 1e3;
+  }
+});
+
+// ../protocol/dist/args/loop.js
+function parseChromeWaitArgs(input) {
+  const obj = asObject(input, TOOL_NAMES.WAIT);
+  const target = parseTargetArgs(obj, TOOL_NAMES.WAIT);
+  const candidates = [];
+  const selector = optString(obj, "selector", TOOL_NAMES.WAIT);
+  if (selector)
+    candidates.push({ kind: "selector", selector });
+  const ref = optString(obj, "ref", TOOL_NAMES.WAIT);
+  if (ref)
+    candidates.push({ kind: "ref", ref });
+  const text = optString(obj, "text", TOOL_NAMES.WAIT);
+  if (text)
+    candidates.push({ kind: "text", text });
+  const urlGlob = optString(obj, "urlGlob", TOOL_NAMES.WAIT);
+  if (urlGlob)
+    candidates.push({ kind: "url", urlGlob });
+  const load = optString(obj, "load", TOOL_NAMES.WAIT);
+  if (load) {
+    if (!LOAD_STATES.has(load)) {
+      throw new RelayError({
+        code: "invalid_arguments",
+        message: `${TOOL_NAMES.WAIT}: \`load\` must be one of load | domcontentloaded | networkidle (got ${load}).`,
+        tool: TOOL_NAMES.WAIT,
+        phase: "parse_arguments",
+        details: { received: load },
+        retryable: false
+      });
+    }
+    candidates.push({ kind: "load", state: load });
+  }
+  const fn = optString(obj, "fn", TOOL_NAMES.WAIT);
+  if (fn)
+    candidates.push({ kind: "fn", fn });
+  if (candidates.length !== 1) {
+    throw new RelayError({
+      code: "invalid_arguments",
+      message: `${TOOL_NAMES.WAIT}: pass exactly one condition (selector | ref | text | urlGlob | load | fn); got ${candidates.length}.`,
+      tool: TOOL_NAMES.WAIT,
+      phase: "parse_arguments",
+      details: { received: candidates.map((c) => c.kind) },
+      retryable: false
+    });
+  }
+  const timeoutRaw = optPositiveNumber(obj, "timeoutMs", TOOL_NAMES.WAIT) ?? DEFAULT_WAIT_TIMEOUT_MS;
+  return {
+    ...target,
+    condition: candidates[0],
+    timeoutMs: Math.min(timeoutRaw, MAX_WAIT_TIMEOUT_MS)
+  };
+}
+function parseChromeBatchArgs(input) {
+  const obj = asObject(input, TOOL_NAMES.BATCH);
+  if (!Array.isArray(obj.commands) || obj.commands.length === 0) {
+    throw new RelayError({
+      code: "invalid_arguments",
+      message: `${TOOL_NAMES.BATCH}: \`commands\` must be a non-empty array of { name, args? }.`,
+      tool: TOOL_NAMES.BATCH,
+      phase: "parse_arguments",
+      details: { received: obj.commands },
+      retryable: false
+    });
+  }
+  if (obj.commands.length > MAX_BATCH_COMMANDS) {
+    throw new RelayError({
+      code: "invalid_arguments",
+      message: `${TOOL_NAMES.BATCH}: at most ${MAX_BATCH_COMMANDS} commands per batch (got ${obj.commands.length}).`,
+      tool: TOOL_NAMES.BATCH,
+      phase: "parse_arguments",
+      details: { received: obj.commands.length },
+      retryable: false
+    });
+  }
+  const commands = obj.commands.map((c, i) => {
+    const cmd = asObject(c, TOOL_NAMES.BATCH);
+    const name = requireString(cmd, "name", TOOL_NAMES.BATCH);
+    if (name === TOOL_NAMES.BATCH) {
+      throw new RelayError({
+        code: "invalid_arguments",
+        message: `${TOOL_NAMES.BATCH}: command ${i} nests a batch inside a batch \u2014 not supported.`,
+        tool: TOOL_NAMES.BATCH,
+        phase: "parse_arguments",
+        details: { index: i },
+        retryable: false
+      });
+    }
+    return { name, args: cmd.args ?? {} };
+  });
+  return { commands, bail: optBool(obj, "bail", TOOL_NAMES.BATCH) ?? true };
+}
+function parseChromeGetArgs(input) {
+  const obj = asObject(input, TOOL_NAMES.GET);
+  const target = parseTargetArgs(obj, TOOL_NAMES.GET);
+  const what = requireString(obj, "what", TOOL_NAMES.GET);
+  if (!GET_WHATS.has(what)) {
+    throw new RelayError({
+      code: "invalid_arguments",
+      message: `${TOOL_NAMES.GET}: \`what\` must be one of text | value | attr | count | title | url (got ${what}).`,
+      tool: TOOL_NAMES.GET,
+      phase: "parse_arguments",
+      details: { received: what },
+      retryable: false
+    });
+  }
+  if (what === "title" || what === "url") {
+    return { ...target, what };
+  }
+  if (what === "count") {
+    return { ...target, what, selector: requireString(obj, "selector", TOOL_NAMES.GET) };
+  }
+  const selector = optString(obj, "selector", TOOL_NAMES.GET);
+  const ref = optString(obj, "ref", TOOL_NAMES.GET);
+  if ((selector ? 1 : 0) + (ref ? 1 : 0) !== 1) {
+    throw new RelayError({
+      code: "invalid_arguments",
+      message: `${TOOL_NAMES.GET} ${what}: pass exactly one of \`selector\` or \`ref\`.`,
+      tool: TOOL_NAMES.GET,
+      phase: "parse_arguments",
+      details: { received: { selector, ref } },
+      retryable: false
+    });
+  }
+  if (what === "attr") {
+    return { ...target, what, attrName: requireString(obj, "attrName", TOOL_NAMES.GET), selector, ref };
+  }
+  return { ...target, what, selector, ref };
+}
+var LOAD_STATES, GET_WHATS;
+var init_loop = __esm({
+  "../protocol/dist/args/loop.js"() {
+    "use strict";
+    init_limits();
+    init_dist();
+    init_shared();
+    LOAD_STATES = /* @__PURE__ */ new Set(["load", "domcontentloaded", "networkidle"]);
+    GET_WHATS = /* @__PURE__ */ new Set(["text", "value", "attr", "count", "title", "url"]);
+  }
+});
+
 // ../protocol/dist/args/index.js
 function parseToolArgs(name, input) {
   switch (name) {
@@ -896,6 +1122,14 @@ function parseToolArgs(name, input) {
       return parseChromeHoverArgs(input);
     case "chrome_screencast":
       return parseChromeScreencastArgs(input);
+    case "chrome_snapshot":
+      return parseChromeSnapshotArgs(input);
+    case "chrome_wait":
+      return parseChromeWaitArgs(input);
+    case "chrome_batch":
+      return parseChromeBatchArgs(input);
+    case "chrome_get":
+      return parseChromeGetArgs(input);
   }
   const exhaustive = name;
   return exhaustive;
@@ -909,30 +1143,85 @@ var init_args = __esm({
     init_network();
     init_simple();
     init_multi();
+    init_loop();
     init_navigate();
     init_hover();
     init_network();
     init_simple();
+    init_loop();
     init_multi();
   }
 });
 
-// ../protocol/dist/limits.js
-var DEFAULT_TOOL_CALL_TIMEOUT_MS, DEFAULT_PING_TIMEOUT_MS, DEFAULT_READY_TIMEOUT_MS, DEFAULT_EVAL_TIMEOUT_MS, DEFAULT_BODY_PREVIEW_BYTES, NETWORK_BUFFER_MAX_ENTRIES, NETWORK_BUFFER_MAX_BYTES, CONSOLE_BUFFER_MAX_ENTRIES, CONSOLE_BUFFER_MAX_BYTES, CONSOLE_ENTRY_TEXT_MAX_CHARS, CONSOLE_ENTRY_STACK_MAX_CHARS;
-var init_limits = __esm({
-  "../protocol/dist/limits.js"() {
+// ../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";
-    DEFAULT_TOOL_CALL_TIMEOUT_MS = 3e4;
-    DEFAULT_PING_TIMEOUT_MS = 2e3;
-    DEFAULT_READY_TIMEOUT_MS = 15e3;
-    DEFAULT_EVAL_TIMEOUT_MS = 15e3;
-    DEFAULT_BODY_PREVIEW_BYTES = 8 * 1024;
-    NETWORK_BUFFER_MAX_ENTRIES = 200;
-    NETWORK_BUFFER_MAX_BYTES = 512 * 1024;
-    CONSOLE_BUFFER_MAX_ENTRIES = 200;
-    CONSOLE_BUFFER_MAX_BYTES = 256 * 1024;
-    CONSOLE_ENTRY_TEXT_MAX_CHARS = 1e3;
-    CONSOLE_ENTRY_STACK_MAX_CHARS = 1e3;
+    REF_TOKEN = /^@(e\d+)$/;
+    ATTR_ORDER = [
+      "level",
+      "checked",
+      "expanded",
+      "selected",
+      "disabled",
+      "required",
+      "readonly",
+      "pressed",
+      "url"
+    ];
   }
 });
 
@@ -952,27 +1241,36 @@ __export(dist_exports, {
   DEFAULT_PING_TIMEOUT_MS: () => DEFAULT_PING_TIMEOUT_MS,
   DEFAULT_READY_TIMEOUT_MS: () => DEFAULT_READY_TIMEOUT_MS,
   DEFAULT_TOOL_CALL_TIMEOUT_MS: () => DEFAULT_TOOL_CALL_TIMEOUT_MS,
+  DEFAULT_WAIT_TIMEOUT_MS: () => DEFAULT_WAIT_TIMEOUT_MS,
   LEGACY_DEV_EXTENSION_ID: () => LEGACY_DEV_EXTENSION_ID,
   LOCAL_UNPACKED_EXTENSION_ID: () => LOCAL_UNPACKED_EXTENSION_ID,
+  MAX_BATCH_BYTES: () => MAX_BATCH_BYTES,
+  MAX_BATCH_COMMANDS: () => MAX_BATCH_COMMANDS,
+  MAX_WAIT_TIMEOUT_MS: () => MAX_WAIT_TIMEOUT_MS,
   NATIVE_HOST_NAME: () => NATIVE_HOST_NAME,
+  NETWORKIDLE_QUIET_MS: () => NETWORKIDLE_QUIET_MS,
   NETWORK_BUFFER_MAX_BYTES: () => NETWORK_BUFFER_MAX_BYTES,
   NETWORK_BUFFER_MAX_ENTRIES: () => NETWORK_BUFFER_MAX_ENTRIES,
   RelayError: () => RelayError,
   TOOL_NAMES: () => TOOL_NAMES,
+  WAIT_POLL_INTERVAL_MS: () => WAIT_POLL_INTERVAL_MS,
   asObject: () => asObject,
   coerceTabId: () => coerceTabId,
+  formatRefToken: () => formatRefToken,
   optBool: () => optBool,
   optNonNegativeNumber: () => optNonNegativeNumber,
   optNumber: () => optNumber,
   optPositiveNumber: () => optPositiveNumber,
   optString: () => optString,
   parseChromeAxArgs: () => parseChromeAxArgs,
+  parseChromeBatchArgs: () => parseChromeBatchArgs,
   parseChromeClickArgs: () => parseChromeClickArgs,
   parseChromeClickAxArgs: () => parseChromeClickAxArgs,
   parseChromeCloseTabsArgs: () => parseChromeCloseTabsArgs,
   parseChromeConsoleArgs: () => parseChromeConsoleArgs,
   parseChromeEvaluateArgs: () => parseChromeEvaluateArgs,
   parseChromeFillArgs: () => parseChromeFillArgs,
+  parseChromeGetArgs: () => parseChromeGetArgs,
   parseChromeGroupArgs: () => parseChromeGroupArgs,
   parseChromeHoverArgs: () => parseChromeHoverArgs,
   parseChromeKeyboardArgs: () => parseChromeKeyboardArgs,
@@ -982,13 +1280,18 @@ __export(dist_exports, {
   parseChromeScreencastArgs: () => parseChromeScreencastArgs,
   parseChromeScreenshotArgs: () => parseChromeScreenshotArgs,
   parseChromeSelfReloadArgs: () => parseChromeSelfReloadArgs,
+  parseChromeSnapshotArgs: () => parseChromeSnapshotArgs,
   parseChromeSwitchTabArgs: () => parseChromeSwitchTabArgs,
   parseChromeTypeArgs: () => parseChromeTypeArgs,
   parseChromeViewportArgs: () => parseChromeViewportArgs,
+  parseChromeWaitArgs: () => parseChromeWaitArgs,
   parseChromeWorkspaceArgs: () => parseChromeWorkspaceArgs,
   parseGetWindowsAndTabsArgs: () => parseGetWindowsAndTabsArgs,
+  parseRefToken: () => parseRefToken,
   parseTargetArgs: () => parseTargetArgs,
   parseToolArgs: () => parseToolArgs,
+  rejectMixedAddressing: () => rejectMixedAddressing,
+  renderSnapshot: () => renderSnapshot,
   requireString: () => requireString,
   toBridgeError: () => toBridgeError
 });
@@ -1010,6 +1313,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 +1370,21 @@ 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",
+      // Adoption-spec Change 3 — block until a condition holds (selector/@ref
+      // visible, text present, URL glob, load state, JS truthy).
+      WAIT: "chrome_wait",
+      // Adoption-spec Change 5 — run N tool calls in one round-trip,
+      // sequentially, bail-on-error by default. Amortizes CLI startup + the
+      // HTTP/native-messaging hop.
+      BATCH: "chrome_batch",
+      // Adoption-spec Change 6 — one value (text/value/attr/count/title/url)
+      // without paying for a full snapshot.
+      GET: "chrome_get"
     };
     RelayError = class extends Error {
       code;
@@ -1101,7 +1419,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.7.0" : "0.0.0-dev";
 
 // src/commands/shared.ts
 init_dist();
@@ -1281,6 +1599,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 +1673,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 +1689,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 +1729,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 +1777,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 +1789,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 +1809,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 +1856,30 @@ async function runDoctor() {
 
 // src/release-notes.ts
 var RELEASE_NOTES = {
+  "0.7.0": [
+    "`wait` \u2014 block until a condition holds: `wait <css|@ref>` (exists and visible), `wait --text <s>`, `wait --url <glob>`, `wait --load load|domcontentloaded|networkidle`, `wait --fn <js>`, or `wait <ms>` for a plain sleep. One condition per call; default 10s, capped 25s (under the transport timeout, so waits always resolve in their own round-trip). Timeout errors include the page's current state so no follow-up probe is needed.",
+    "`snapshot --diff` \u2014 print only what changed since this tab's previous snapshot (unified hunks + an additions/removals count; ~100 tokens instead of a full re-read). The full snapshot is still taken and the ref map still refreshes \u2014 refs in the diff are current and clickable.",
+    "`get text|value|attr|count|title|url <target>` \u2014 one value, plain on stdout, no snapshot. Targets are @refs or CSS selectors; built for $(...) substitution.",
+    "`batch` \u2014 run up to 50 tool calls in ONE round-trip (one HTTP POST, one native-messaging message, sequential in the extension). Bail-on-error by default, `--no-bail` to continue; per-command result envelopes; nested batches rejected.",
+    "`skills get core` \u2014 the agent playbook is now inlined in the binary, always version-matched. `chrome-relay skills` lists; the same guide is hosted at https://chrome-relay.kushalsm.com/skill.md.",
+    "Top-level --help rewritten around the snapshot -> @ref loop (the old read -> selector flow was stale). Example URLs across help/docs now point at real pages.",
+    "Extension + CLI must both be 0.7.0 for wait/get/batch/--diff \u2014 an older extension returns unsupported_tool (update at chrome://extensions)."
+  ],
+  "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.",
@@ -1724,10 +2163,10 @@ function registerNavigation(ctx) {
       `
 
 Examples:
-  chrome-relay navigate "https://example.com"                    # navigate current tab
-  chrome-relay navigate --tab 123 "https://example.com"          # navigate an existing tab
-  chrome-relay navigate "https://example.com" --new              # open in a new background tab
-  chrome-relay navigate "https://example.com" --new --active     # open new tab AND show it to the user
+  chrome-relay navigate "https://chrome-relay.kushalsm.com"                    # navigate current tab
+  chrome-relay navigate --tab 123 "https://chrome-relay.kushalsm.com"          # navigate an existing tab
+  chrome-relay navigate "https://chrome-relay.kushalsm.com" --new              # open in a new background tab
+  chrome-relay navigate "https://chrome-relay.kushalsm.com" --new --active     # open new tab AND show it to the user
 
 By default chrome-relay never steals focus \u2014 navigated tabs (new or
 existing) stay in whatever state they're in. Pass --active when you
@@ -1738,7 +2177,7 @@ actually want the user looking at the page.
     if (/^\d+$/.test(url)) {
       process.stderr.write(
         `navigate expects a URL, but "${url}" looks like a tab ID.
-Use "chrome-relay switch ${url}" to activate that tab, or "chrome-relay navigate --tab ${url} https://example.com" to navigate it.
+Use "chrome-relay switch ${url}" to activate that tab, or "chrome-relay navigate --tab ${url} https://chrome-relay.kushalsm.com" to navigate it.
 `
       );
       process.exit(1);
@@ -1761,34 +2200,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@kushalsm.com"
+  chrome-relay fill 'input[name="email"]' "kushal@kushalsm.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 +2261,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 +2278,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 +2303,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 +2315,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 +2325,88 @@ tooltip appearance, etc.) that a bare click would skip past too quickly.
 }
 
 // src/commands/capture.ts
+init_dist();
 import { writeFileSync } from "fs";
+import { structuredPatch } from "diff";
+function printSnapshotDiff(current, prevText) {
+  if (prevText === null) {
+    process.stderr.write("[chrome-relay] no previous snapshot for this tab \u2014 showing full output.\n");
+    process.stdout.write(current + "\n");
+    return;
+  }
+  if (prevText === current) {
+    process.stdout.write("no changes since last snapshot\n");
+    return;
+  }
+  const patch = structuredPatch("prev", "current", prevText, current, "", "", { context: 3 });
+  let added = 0;
+  let removed = 0;
+  for (const hunk of patch.hunks) {
+    process.stdout.write(`@@ -${hunk.oldStart},${hunk.oldLines} +${hunk.newStart},${hunk.newLines} @@
+`);
+    for (const line of hunk.lines) {
+      if (line.startsWith("+")) added++;
+      else if (line.startsWith("-")) removed++;
+      process.stdout.write(line + "\n");
+    }
+  }
+  process.stdout.write(`${added} addition${added === 1 ? "" : "s"}, ${removed} removal${removed === 1 ? "" : "s"}
+`);
+}
+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("--diff", "print only what changed since the previous snapshot of this tab (~100 tokens instead of a re-read)").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;
+    if (opts.diff) extras.diff = true;
+    try {
+      const result = await callTool("chrome_snapshot", withBase(opts, extras));
+      if (opts.diff && !opts.json) {
+        const data = result;
+        printSnapshotDiff(renderSnapshot(data), data.prevText ?? null);
+        return;
+      }
+      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 +2446,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",
       `
 
@@ -2258,7 +2784,7 @@ Notes:
 
 Examples:
   chrome-relay network --tab 123                              # last ${NETWORK_BUFFER_MAX_ENTRIES} requests
-  chrome-relay network --tab 123 --filter api.example.com      # url substring
+  chrome-relay network --tab 123 --filter api.kushalsm.com      # url substring
   chrome-relay network --tab 123 --status failed
   chrome-relay network --tab 123 --method POST
   chrome-relay network body <requestId> --tab 123              # lazy body fetch
@@ -2338,27 +2864,231 @@ Notes:
   });
 }
 
+// src/commands/loop.ts
+init_dist();
+import { readFileSync } from "fs";
+function coreSkillText() {
+  if (true) return '# Chrome Relay\n\nDrives the user\'s real Chrome through a Chrome extension + local native host. Prefer it when logged-in browser state (auth cookies, sessions, installed extensions) matters.\n\n## Setup\n\n1. [Chrome extension](https://chromewebstore.google.com/detail/chrome-relay/cpdiapbifblhlcpnmlmfpgfjlacebokb)\n2. CLI:\n   ```sh\n   pnpm add -g chrome-relay\n   chrome-relay install\n   chrome-relay doctor\n   ```\n\nVerify CLI \u2265 0.7.0 \u2014 wait/get/batch/`snapshot --diff` landed there (0.6.0 brought the snapshot/@ref loop; \u2265 0.5.20 fixed a silent click bug on Radix/React-Aria UIs):\n```sh\nchrome-relay --version\n```\n\n## The core loop\n\n```sh\nchrome-relay tabs                             # find or create a tab\nchrome-relay navigate "https://kushalsm.com" --new   # background tab by default\nchrome-relay snapshot --tab 1234 -i           # see the page: actionable elements get @refs\nchrome-relay click @e12                       # act on refs \u2014 no --tab, no selector\nchrome-relay fill @e14 "hello"\nchrome-relay wait --text "Saved" --tab 1234   # block until the page reacts\nchrome-relay snapshot --tab 1234 --diff       # print only what changed (~100 tokens)\n```\n\nSnapshot output is compact indented text (~1\u201315 KB for most pages) \u2014 read it directly, no jq needed:\n\n```\n- link "Hacker News" [ref=e4]\n- textbox "Search" [ref=e41]: current value\n- checkbox "Remember me" [checked, ref=e42]\n- clickable "Open card" [ref=e88]        \u2190 cursor-pointer div the AX tree missed\n```\n\n**Refs carry their own tab.** `click @e12` acts on the tab that produced e12, never the active tab \u2014 safe while the user keeps browsing. A contradicting `--tab` errors with `target_conflict`.\n\n**Ref lifetime.** Refs survive same-page DOM churn (cached backendNodeId, healed by role+name re-find when nodes are replaced) but die on real navigation. A dead ref returns `error.code = stale_ref` \u2192 re-run `snapshot`.\n\n**Interception.** Ref clicks hit-test the point first: if an overlay / sticky header / modal owns it, you get `error.code = click_intercepted` naming the interceptor \u2014 dismiss it or scroll, then retry. The click was NOT delivered. `fill`/`type` skip this check (covered inputs are still writable).\n\n## Tool surface\n\n| Command | What it does |\n|---|---|\n| `tabs` | List windows + tabs with their `tabId`s |\n| `navigate <url>` | Open in current tab. `--new` opens in a **background** tab (default). `--active` brings it to foreground. `--tab <id>` retargets an existing tab. |\n| `snapshot --tab <id> -i` | Page snapshot with actionable `@refs` \u2014 accessibility tree + cursor-interactive sweep, one ref space, compact text. `-d N` depth cap, `-s <css>` scope to subtree, `-u` include hrefs, `--diff` print only changes since the last snapshot, `--json` structured envelope with the refs map. |\n| `wait <css\\|@ref>` / `wait --text` / `--url <glob>` / `--load networkidle` / `--fn <js>` | Block until a condition holds (one per call, default 10s, max 25s). `wait 1500` just sleeps. On timeout the error includes current page state. |\n| `get text\\|value\\|attr\\|count\\|title\\|url <target>` | One value, plain to stdout \u2014 no full snapshot. `get text @e12`, `get attr @e7 href`, `get count ".row"`. |\n| `batch \'[{"name":"chrome_...","args":{...}}, ...]\'` | N tool calls in ONE round-trip, sequential, bail-on-error by default. Use wire tool names. |\n| `skills get core` | Print this playbook, version-matched to the installed binary. |\n| `click <@ref \\| selector> --tab <id>` | Trusted hover + press + release at element center (`pointerType: "mouse"`). Refs need no `--tab`. |\n| `click --x N --y N --tab <id>` | Coordinate-mode click \u2014 for canvas/SVG chart internals with no DOM handle. |\n| `hover <@ref \\| selector \\| --x --y>` | Pointer move only \u2014 fires `:hover` styles. |\n| `fill <@ref \\| selector> <value>` | Atomic value write into `<input>`/`<textarea>`/`<select>`. Bypasses React\'s value tracker. Refs reach inside shadow DOM (selectors can\'t). |\n| `type <text> [-s <@ref \\| selector>]` | CDP `Input.insertText`. Use for contenteditable / Draft.js / Lexical / ProseMirror. **Appends** at caret; clear the input first if it had a value. |\n| `keys <chord> --tab <id>` | Single key or chord: `Enter`, `Tab`, `Escape`, `Cmd+K`, `Shift+ArrowDown`. |\n| `js <code> --tab <id>` | `Runtime.evaluate` in MAIN world. Use `return` for the value. Top-level `await` works. |\n| `screenshot --tab <id> -o <path>` | PNG. `--full` captures beyond viewport. `--max-edge N` resizes. |\n| `screencast --tab <id> -o <path>` | Record a tab via CDP (paint-driven). Requires an active tab. |\n| `network --tab <id>` | HTTP request/response ring buffer, last 200 per tab. `network read --request-id <id>` for bodies. |\n| `console --tab <id>` | `console.log/warn/error` + page exceptions, last 200. |\n| `viewport` | Emulate device viewport, DPR, mobile flag, touch, UA. |\n| `workspace` / `group` | Manage named windows / tab-groups so multiple agents can drive separate windows. |\n| `switch <tabId>` / `close <tabIds...>` | Activate or close tabs |\n| `self-reload` | Restart the extension\'s service worker after a rebuild |\n| `release-notes --since <ver>` / `update` | Queryable changelog; agent-readable JSON. |\n| `call <tool> [json]` | Raw pass-through for any internal tool. |\n| `read` / `ax` / `click-ax` | **Deprecated** \u2014 aliases for `snapshot` / `click @ref`. Will be removed; don\'t use in new work. |\n\n## Picking the right text tool\n\n| Target element | Tool |\n|---|---|\n| `<input>`, `<textarea>`, `<select>` (including React-controlled, shadow DOM) | `fill @ref` |\n| `[contenteditable]`, `role="textbox"`, Draft.js / Lexical / ProseMirror, X compose, LinkedIn DM, new Reddit composer | `type` |\n| Submit, navigate menus, modifier shortcuts | `keys` |\n| Combobox / autocomplete option selection | `type` into filter \u2192 `keys ArrowDown` \u2192 `keys Enter` ([why](references/patterns.md)) |\n| Framework-internal pokes, scraping, custom widgets | `js` |\n\n## Element addressing \u2014 the fallback ladder\n\n1. **`@ref` from `snapshot -i`** \u2014 default. Covers buttons/links/inputs, named content, cursor-pointer div-soup (the sweep), and shadow DOM.\n2. **CSS selector** \u2014 when you know the selector statically and don\'t need a snapshot.\n3. **`js` probe \u2192 coordinate click** \u2014 canvas internals and SVG chart segments (anonymous `<path>` elements have no DOM handle anywhere):\n   ```sh\n   chrome-relay js --tab 1234 "const r = document.querySelector(\'svg path\').getBoundingClientRect(); return {x: r.x + r.width/2, y: r.y + r.height/2}"\n   chrome-relay click --tab 1234 --x 312 --y 218\n   ```\n\n## Don\'t poll \u2014 wait\n\nA snapshot after every action wastes turns. The cheap loop on a changing page:\n\n```sh\nchrome-relay click @e12\nchrome-relay wait --text "Saved" --tab 1234     # or wait <selector> / --url / --load\nchrome-relay snapshot --tab 1234 --diff         # only the changes, refs included\n```\n\n## Top gotchas\n\n1. **`type` appends** \u2014 it inserts at the caret. If the input had a value (autosaved draft, default text), clear it first via `js` or `keys` (Cmd+A then Backspace).\n2. **Refs die on navigation** \u2014 `stale_ref` means the page changed under you; re-snapshot. Don\'t retry the same ref.\n3. **Coords go stale fast** \u2014 read `getBoundingClientRect`, scroll/reflow, then click \u2192 you hit the wrong element. For autocomplete popups especially, use keyboard nav, not coord clicks.\n4. **Click "succeeded" but nothing happened** \u2014 first diagnostic: `document.elementFromPoint(x, y)`. If it returns a wrapper or form background, your coords are wrong. If it returns the right element but state didn\'t change, you\'re likely on chrome-relay <0.5.20 \u2014 upgrade.\n\nMore recipes: [references/patterns.md](references/patterns.md)\nFailure modes: [references/troubleshooting.md](references/troubleshooting.md)\n\n## Operational guidance\n\n- **Don\'t give up early.** A failing click is information, not a stop signal. Attach a document-level listener with `capture:true` and watch what fires:\n  ```sh\n  chrome-relay js --tab 1234 "\n    [\'pointerdown\',\'mousedown\',\'click\'].forEach(t =>\n      document.addEventListener(t, e => console.log(t, e.target.tagName, e.target.className), {capture:true})\n    );\n    return \'listening\'\n  "\n  # do the action, then:\n  chrome-relay console --tab 1234\n  ```\n- **Don\'t echo secrets.** When extracting tokens / API keys via `js`, write the result directly to a file. Never `echo $TOKEN` or interpolate into shell strings \u2014 it ends up in scrollback, logs, and tool transcripts.\n- **Capture before irreversible actions** (form submit, send message, account change). Save the screenshot path.\n\n## Guardrails\n\n- Errors are structured: branch on `relayError.code` (`stale_ref`, `click_intercepted`, `element_not_found`, `target_conflict`, `timeout`), not on message text.\n- If a flag is unclear, `chrome-relay <command> --help` is authoritative \u2014 these docs lag.';
+  try {
+    return readFileSync(new URL("../../../../skills/chrome-relay/SKILL.md", import.meta.url), "utf8").replace(/^---\n[\s\S]*?\n---\n/, "").replace(/<!--[\s\S]*?-->\n*/, "").trim();
+  } catch {
+    return "core skill unavailable in this build \u2014 see https://chrome-relay.kushalsm.com/skill.md";
+  }
+}
+function exitWithError2(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 registerLoop(ctx) {
+  const { program, withBase, run } = ctx;
+  tabOpt(
+    program.command("wait [target]").description("Block until a condition holds: a selector/@ref is visible, text appears, the URL matches, the page loads, or a JS expression is truthy. Pass a number to just sleep.").option("--text <s>", "body text contains <s>").option("--url <glob>", "URL matches glob (** crosses /, * doesn't)").option("--load <state>", "load | domcontentloaded | networkidle").option("--fn <js>", "JS expression in the page; waits until truthy").option("--timeout <ms>", "max wait (default 10000, capped 25000)", (v) => Number(v)).addHelpText(
+      "after",
+      `
+
+Examples:
+  chrome-relay wait @e12                       # ref resolves and has a box
+  chrome-relay wait ".results" --tab 42        # selector exists and visible
+  chrome-relay wait --text "Welcome" --tab 42
+  chrome-relay wait --url "**/dashboard" --tab 42
+  chrome-relay wait --load networkidle --tab 42
+  chrome-relay wait --fn "window.__APP_READY === true" --tab 42
+  chrome-relay wait 1500                       # plain sleep, no tab needed
+
+Exactly one condition per call. On timeout the error includes the page's
+current state (url, readyState, whether the selector exists) so you don't
+need a follow-up probe.
+`
+    )
+  ).action(async (target, opts) => {
+    if (target && /^\d+$/.test(target)) {
+      const ms = Number(target);
+      await new Promise((r) => setTimeout(r, ms));
+      process.stdout.write(JSON.stringify({ satisfied: true, sleptMs: ms }) + "\n");
+      return;
+    }
+    const extras = {};
+    if (target) {
+      const ref = parseRefToken(target);
+      if (ref) extras.ref = ref;
+      else extras.selector = target;
+    }
+    if (opts.text) extras.text = opts.text;
+    if (opts.url) extras.urlGlob = opts.url;
+    if (opts.load) extras.load = opts.load;
+    if (opts.fn) extras.fn = opts.fn;
+    if (typeof opts.timeout === "number") extras.timeoutMs = opts.timeout;
+    await run(TOOL_NAMES.WAIT, withBase(opts, extras));
+  });
+  const get = program.command("get").description("One value, plain to stdout \u2014 no full snapshot.").addHelpText(
+    "after",
+    `
+
+Examples:
+  chrome-relay get text @e12
+  chrome-relay get value 'input[name="email"]' --tab 42
+  chrome-relay get attr @e7 href
+  chrome-relay get count ".result" --tab 42
+  chrome-relay get title --tab 42
+  chrome-relay get url --tab 42
+`
+  );
+  const printValue = async (args) => {
+    try {
+      const result = await callTool(TOOL_NAMES.GET, args);
+      const v = result.value;
+      process.stdout.write((v === null || v === void 0 ? "" : String(v)) + "\n");
+    } catch (error) {
+      exitWithError2(error);
+    }
+  };
+  const addressArgs = (target) => {
+    const ref = parseRefToken(target);
+    return ref ? { ref } : { selector: target };
+  };
+  for (const what of ["text", "value"]) {
+    tabOpt(
+      get.command(`${what} <target>`).description(`${what === "text" ? "Visible text" : "Input value"} of a @ref or CSS selector.`)
+    ).action(async (target, opts) => {
+      await printValue(withBase(opts, { what, ...addressArgs(target) }));
+    });
+  }
+  tabOpt(
+    get.command("attr <target> <name>").description("Attribute value of a @ref or CSS selector.")
+  ).action(async (target, name, opts) => {
+    await printValue(withBase(opts, { what: "attr", attrName: name, ...addressArgs(target) }));
+  });
+  tabOpt(get.command("count <selector>").description("Number of elements matching a CSS selector.")).action(
+    async (selector, opts) => {
+      await printValue(withBase(opts, { what: "count", selector }));
+    }
+  );
+  tabOpt(get.command("title").description("Page title.")).action(async (opts) => {
+    await printValue(withBase(opts, { what: "title" }));
+  });
+  tabOpt(get.command("url").description("Page URL.")).action(async (opts) => {
+    await printValue(withBase(opts, { what: "url" }));
+  });
+  program.command("batch [json]").description("Run multiple tool calls in ONE round-trip, sequentially. JSON array of {name, args}, inline or via --stdin.").option("--stdin", "read the JSON array from stdin").option("--no-bail", "keep going after a failed command (default stops at first error)").addHelpText(
+    "after",
+    `
+
+Examples:
+  chrome-relay batch '[
+    {"name":"chrome_navigate","args":{"url":"https://chrome-relay.kushalsm.com","newTab":true}},
+    {"name":"chrome_wait","args":{"load":"load"}},
+    {"name":"chrome_snapshot","args":{"interactiveOnly":true}}
+  ]'
+  cat commands.json | chrome-relay batch --stdin
+
+One HTTP POST, one native-messaging message, sequential execution in the
+extension. Tool names are the wire names (chrome_navigate, chrome_snapshot,
+chrome_click_element, ... \u2014 see \`chrome-relay call --help\`). Amortizes CLI
+startup across N actions. Nested batches are rejected.
+`
+  ).action(async (json, opts) => {
+    try {
+      let raw = json;
+      if (opts.stdin) {
+        raw = readFileSync(0, "utf8");
+      }
+      if (!raw) {
+        throw new RelayError({
+          code: "invalid_arguments",
+          message: "chrome-relay batch: pass a JSON array inline or via --stdin.",
+          tool: TOOL_NAMES.BATCH,
+          phase: "parse_arguments",
+          retryable: false
+        });
+      }
+      if (Buffer.byteLength(raw, "utf8") > MAX_BATCH_BYTES) {
+        throw new RelayError({
+          code: "invalid_arguments",
+          message: `chrome-relay batch: input exceeds ${MAX_BATCH_BYTES} bytes (native-messaging frame safety). Split the batch.`,
+          tool: TOOL_NAMES.BATCH,
+          phase: "parse_arguments",
+          retryable: false
+        });
+      }
+      let commands;
+      try {
+        commands = JSON.parse(raw);
+      } catch (e) {
+        throw new RelayError({
+          code: "invalid_arguments",
+          message: `chrome-relay batch: input is not valid JSON (${e instanceof Error ? e.message : e}).`,
+          tool: TOOL_NAMES.BATCH,
+          phase: "parse_arguments",
+          retryable: false
+        });
+      }
+      const result = await callTool(TOOL_NAMES.BATCH, { commands, bail: opts.bail !== false });
+      process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+      const failed = result.results?.some((r) => !r.ok);
+      if (failed) process.exit(1);
+    } catch (error) {
+      exitWithError2(error);
+    }
+  });
+  const skills = program.command("skills [verb] [name]").description("Agent playbooks shipped inside the CLI \u2014 always version-matched to the binary.").addHelpText(
+    "after",
+    `
+
+Examples:
+  chrome-relay skills            # list available skills
+  chrome-relay skills get core   # print the core usage guide
+
+The same guide is hosted at https://chrome-relay.kushalsm.com/skill.md \u2014
+the binary copy is authoritative for the version you have installed.
+`
+  );
+  skills.action(async (verb, name) => {
+    if (!verb || verb === "list") {
+      process.stdout.write("core \u2014 the Chrome Relay agent playbook (snapshot/@ref loop, text-tool table, gotchas)\n");
+      return;
+    }
+    if (verb === "get" && (name === "core" || name === void 0)) {
+      process.stdout.write(coreSkillText() + "\n");
+      return;
+    }
+    process.stderr.write(`Unknown skill command: ${verb}${name ? ` ${name}` : ""}. Try \`chrome-relay skills\` or \`chrome-relay skills get core\`.
+`);
+    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(
+  program.name("chrome-relay").description("Your agent drives the Chrome you're signed into \u2014 reads pages, clicks buttons, fills forms from any shell.").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:
+The core loop:
   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 navigate "https://chrome-relay.kushalsm.com" --new      # background tab
+  chrome-relay snapshot --tab <tabId> -i                 # actionable elements get @refs
+  chrome-relay click @e12                                # act on a ref \u2014 no --tab needed
+  chrome-relay fill @e14 "value"
+  chrome-relay snapshot --tab <tabId> -i                 # re-look after the page changes
+
+Also:
+  chrome-relay wait --tab <tabId> --text "Welcome"       # selector/@ref/text/url/load/fn
+  chrome-relay get text @e12                             # one value, no full snapshot
   chrome-relay keys --tab <tabId> Enter
   chrome-relay js --tab <tabId> "return document.title"
   chrome-relay screenshot --tab <tabId> -o evidence.png
+  chrome-relay skills get core                           # the agent playbook, version-matched
 
 Notes:
-  navigate takes a URL. Use --tab to target an existing tab.
-  Tools attach via CDP and run on backgrounded tabs without stealing focus.
+  Refs come from snapshot and carry their own tab. Tools attach via CDP and
+  run on backgrounded tabs without stealing focus. Errors are structured \u2014
+  branch on relayError.code (stale_ref means: re-run snapshot).
 `
   );
   const baseArgs = makeBaseArgs(program);
@@ -2373,6 +3103,7 @@ Notes:
   registerInput(ctx);
   registerCapture(ctx);
   registerSessions(ctx);
+  registerLoop(ctx);
   return program;
 }