replicas-cli 0.2.354 → 0.2.356

package/dist/index.mjs

@@ -8010,13 +8010,12 @@ replicas computer info
 # 2) Launch a browser on the workspace display.
 replicas computer launch chrome https://news.ycombinator.com
 
-# 3) Observe the settled screen and browser tab state before clicking.
-replicas computer observe /tmp/state.png
-replicas computer browser --snapshot
+# 3) Capture the settled viewport and native accessibility tree together.
+replicas computer browser-state /tmp/state.png --full
 
-# 4) Drive the UI.
-replicas computer click 521 700                    # click coordinates from the screenshot
-replicas computer scroll down --amount 5
+# 4) Batch actions that use refs from the same state, then capture the semantic diff.
+replicas computer browser-batch '[{"action":"fill","ref":17,"value":"hello"},{"action":"click","ref":42}]'
+replicas computer browser-state /tmp/after-click.png
 
 # 5) (Optional) Record a screencap to share back.
 replicas computer record start /tmp/demo.mp4 --fps 60
@@ -8045,21 +8044,33 @@ Waits briefly for the screen to stop changing, saves a 1:1 screenshot, and print
 
 Use this instead of hand-written \`sleep && screenshot\` loops after clicks, navigation, typing, or page loads. By default it saves a 100px coordinate-grid screenshot and waits up to 3s for 600ms of visual stability. Pass \`--raw\` if you need an unannotated 1:1 screenshot.
 
-### \`replicas computer browser\`
-Prints JSON for Chrome tabs launched through Replicas, including page titles and URLs. Pass \`--snapshot\` to include visible page text and interactive controls with DOM viewport bounding boxes.
+### \`replicas computer browser-state <path> [--full] [--timeout MS] [--stable-ms MS]\`
+Waits for the selected Chrome page to settle, saves its viewport screenshot, and prints a compact native Chrome accessibility tree in the same coordinate space. Actionable nodes have DOM-backed refs such as \`[ref=42] button "Save"\`; the tree includes accessible roles, names, values, states, visible bounds, and iframe content.
+
+The first call returns a full tree. Later calls for the same target and document return semantic changes; navigation or reload forces a new full tree. Pass \`--full\` to reset the baseline. Refs are valid for the current document.
+
+### \`replicas computer browser [--snapshot]\`
+Lists Chrome tabs. \`--snapshot\` returns the compatibility accessibility snapshot. Use \`browser-state\` for the primary action/observe loop.
+
+### \`replicas computer browser-batch '<actions-json>'\`
+Runs up to 100 ordered browser actions through one Chrome session and stops at the first failure. Supported actions are \`click\`, \`fill\`, \`key\`, \`type\`, \`scroll\`, and \`wait\`. Prefer this when several actions use refs from the same \`browser-state\`; it avoids repeated process, tab-selection, and connection setup. Do not carry refs across navigation\u2014capture fresh state and start a new batch.
+
+### \`replicas computer browser-click --ref ID [--button left|middle|right] [--double]\`
+Scrolls the referenced node into view and sends trusted Chrome mouse input at its current visible bounds. Prefer refs from \`browser-state\`. \`browser-click <text> [--exact] [--index N]\` remains a fallback when no fresh ref is available.
 
-Use this alongside \`observe\` when testing web apps so you do not infer navigation, page state, or click targets from pixels alone. Snapshot coordinates are DOM viewport coordinates, not desktop click coordinates.
+### \`replicas computer browser-fill --ref ID <value>\`
+Focuses the referenced field, fills it with trusted Chrome input, and verifies the resulting value. Select controls use their semantic option value. \`browser-fill <field> <value> [--exact] [--index N]\` remains a text-matching fallback.
 
-### \`replicas computer browser-click <text> [--exact] [--index N]\`
-Clicks the first visible Chrome control whose text, label, placeholder, or href matches \`<text>\`. Use this for web buttons and links found via \`browser --snapshot\`; it is faster and less error-prone than converting DOM coordinates to desktop pixels.
+### \`replicas computer browser-scroll <up|down|left|right> [--ref ID] [--amount PX]\`
+Sends trusted wheel input at a referenced element or the center of the viewport.
 
-### \`replicas computer browser-fill <field> <value> [--exact] [--index N]\`
-Fills the first visible Chrome field whose label, placeholder, name, or text matches \`<field>\`, then dispatches input/change events. Use this for web forms instead of clicking a field and typing through the desktop.
+### \`replicas computer browser-key <combo>\` / \`browser-type <text>\`
+Sends trusted keyboard input to the focused element in the selected Chrome target. Prefer \`browser-fill\` when setting a known field value.
 
 ### \`replicas computer browser-wait <text> [--mode any|text|title|url|control] [--exact] [--timeout MS]\`
 Waits until the active Chrome page matches text in the title, URL, body text, or visible controls. Use this after \`browser-click\` / \`browser-fill\` when you need web app state to settle without screenshot polling.
 
-For \`browser-click\`, \`browser-fill\`, and \`browser-wait\`, pass \`--id <id>\`, \`--title <text>\`, \`--url <text>\`, or \`--page <n>\` when multiple Chrome tabs are open. Run \`replicas computer browser\` first to list tabs. Prefer \`--id\` when a click may change the page title or URL.
+For browser state and actions, pass \`--target-id <id>\`, \`--title <text>\`, \`--url <text>\`, or \`--page <n>\` when multiple Chrome tabs are open. Prefer \`--target-id\` because titles and URLs can change after an action. The matched tab is brought to the foreground before each action, so driving multiple tabs or recording the screen switches which tab is visible.
 
 ### \`replicas computer click <x> <y> [--button N] [--double] [--modifiers ctrl+shift]\`
 Move to (x, y) and click. Coordinates can be absolute pixels or percentages such as \`50%\` \`50%\`. Default is left-click (button 1); pass \`--button 3\` for right-click. \`--modifiers\` holds keys during the click (e.g. ctrl-click a link to open in a new tab).
@@ -8092,26 +8103,29 @@ Spawns an app on the workspace display. Built-in aliases:
 Anything else gets \`exec\`'d verbatim, so \`replicas computer launch xeyes\` works if xeyes is installed.
 When opening a known page, prefer passing the URL directly: \`replicas computer launch chrome http://localhost:3000/\`.
 
+Chrome launches do not return until the requested page is controllable. The output includes its page ID; carry that ID with \`--target-id\` into \`browser-state\` and browser actions so unrelated tabs cannot steal task context.
+
 ### \`replicas computer record start <path> [--fps N]\`
-Starts an ffmpeg screen recorder. Output is post-processed when stopped: action windows stay at normal speed, idle gaps accelerate, click moments get eased camera zoom, and a synthetic cursor animates between logged mouse positions. The raw capture is fragmented MP4 while active (still playable if the workspace dies mid-record). Default 60fps; drop to 30 if the workspace is CPU-constrained.
+Starts an ffmpeg screen recorder and returns only after ffmpeg has written the first bytes. Output is post-processed when stopped: action windows stay at normal speed, idle gaps accelerate, click moments get eased camera zoom, and a synthetic cursor animates between logged mouse positions. The raw capture is fragmented MP4 while active (still playable if the workspace dies mid-record). Default 60fps; drop to 30 if the workspace is CPU-constrained.
 
 Only one recording at a time. Re-running \`start\` while one is active fails - call \`stop\` first.
 
 ### \`replicas computer record stop\`
-SIGINTs ffmpeg, waits for it to finalize the MP4, prints the output path. Upload it with \`replicas media upload <path>\` to share it.
+SIGINTs ffmpeg, verifies that the process has finalized the MP4, then prints the output path. A finalization timeout preserves the recording state so \`stop\` can be retried safely. Upload it with \`replicas media upload <path>\` to share it.
 
 ## Patterns
 
-### Action / observe loop
-You are blind between tool calls. After any action that changes the screen, observe before deciding the next coordinate:
+### Browser action / state loop
+For Chrome, use the native accessibility state before interpreting pixels or guessing coordinates:
 
 \`\`\`bash
-replicas computer click 521 700
-replicas computer observe /tmp/after-click.png
-# read /tmp/after-click.png and the JSON output, decide next click
+replicas computer launch chrome https://example.com
+replicas computer browser-state /tmp/before.png --full --target-id <page-id>
+replicas computer browser-batch '[{"action":"fill","ref":17,"value":"hello"},{"action":"click","ref":23}]' --target-id <page-id>
+replicas computer browser-state /tmp/after.png --target-id <page-id>
 \`\`\`
 
-The JSON \`stable\`, \`frames\`, and \`changes\` fields tell you whether something changed while you were waiting. If \`stable\` is false, observe again or increase \`--timeout\` before acting on coordinates.
+Read the screenshot and tree as one state. Batch ordered actions whose refs all come from that state, then inspect the next semantic diff. A batch is fail-fast and validates each ref against the cached document. Split at navigation or whenever a later action depends on newly rendered refs. Fall back to \`observe\` plus desktop coordinates for canvas content, browser chrome, non-Chrome apps, or controls missing from the accessibility tree.
 
 ### Typing into an address bar
 \`\`\`bash
@@ -8120,10 +8134,9 @@ replicas computer observe /tmp/browser-open.png
 replicas computer key ctrl+l
 replicas computer type "https://example.com"
 replicas computer key Return
-replicas computer observe /tmp/loaded.png
-replicas computer browser --snapshot
-replicas computer browser-fill "Search" "replicas"
-replicas computer browser-click "More information" --title "Example"
+replicas computer browser-state /tmp/loaded.png --full
+replicas computer browser-fill --ref 17 "replicas"
+replicas computer browser-click --ref 23 --title "Example"
 replicas computer browser-wait "Example Domain" --mode title --title "Example"
 \`\`\`
 
@@ -9283,6 +9296,7 @@ In agent mode the CLI hides commands that don't make sense for in-workspace agen
 | \`replicas automation ...\` | Manage automations (cron + GitHub/GitLab event triggers) |
 | \`replicas preview ...\` | Register / list preview URLs (covered in \`PREVIEWS.md\`) |
 | \`replicas media ...\` | Upload screenshots, videos, audio (covered in \`MEDIA.md\`) |
+| \`replicas slack thread ...\` | Attach or switch Slack thread routing (covered in \`SLACK.md\`) |
 
 \`replicas <command> --help\` is always the source of truth for flags.
 
@@ -9516,6 +9530,30 @@ curl -s -X POST "https://slack.com/api/chat.postMessage" \\
 
 Omit \`thread_ts\` to post a new message to the channel. Include it to reply in a thread.
 
+#### Attach every new conversation
+
+Whenever you send a Slack message outside the thread that already routes to the current workspace, immediately attach the destination thread so future replies are delivered to this workspace:
+
+\`\`\`bash
+replicas slack thread attach --channel <channel-id> --thread-ts <thread-root-ts>
+\`\`\`
+
+- For a new top-level message or DM, use the \`channel\` and \`ts\` from the successful \`chat.postMessage\` response. That message's \`ts\` is the new thread root.
+- For a reply in another existing thread, use its root \`thread_ts\`, not the reply's \`ts\`.
+- Do not attach the originating thread again when it already routes to the current workspace.
+- Treat sending and attaching as one operation: check that both API calls succeed, and report an attachment failure instead of implying future replies will reach you.
+
+#### Switch a thread to an existing workspace
+
+When the user wants a Slack thread to continue in a particular existing workspace, resolve the target and switch the thread:
+
+\`\`\`bash
+replicas list
+replicas slack thread switch <workspace-id-or-name> --channel <channel-id> --thread-ts <thread-root-ts>
+\`\`\`
+
+The channel and thread flags default to \`SLACK_CHANNEL_ID\` and \`SLACK_THREAD_TS\` for a Slack-triggered workspace. Workspace-authenticated agents may target only their current workspace; switching to a different workspace requires running the command with user authentication outside agent mode. If that restriction applies, give the user the exact command to run rather than claiming the switch succeeded.
+
 ### Searching Messages
 
 \`\`\`bash
@@ -9654,7 +9692,7 @@ var HOOK_EXEC_MAX_BUFFER_BYTES = 10 * 1024 * 1024;
 var REPLICAS_CONFIG_FILENAMES = ["replicas.json", "replicas.yaml", "replicas.yml"];
 
 // ../shared/src/cli-version.ts
-var CLI_VERSION = "0.2.354";
+var CLI_VERSION = "0.2.356";
 
 // ../shared/src/version.ts
 function compareVersions(v1, v2) {
@@ -15010,7 +15048,7 @@ var sleep = (ms) => new Promise((resolve2) => setTimeout(resolve2, ms));
 
 // src/commands/computer/recording.ts
 import { spawn as spawn3 } from "child_process";
-import { appendFileSync, existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync as readFileSync2, rmSync as rmSync2, writeFileSync as writeFileSync2 } from "fs";
+import { appendFileSync, existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync as readFileSync2, rmSync as rmSync2, statSync, writeFileSync as writeFileSync2 } from "fs";
 import { dirname as dirname2 } from "path";
 
 // src/commands/computer/recording/render.ts
@@ -15491,6 +15529,18 @@ var RECORD_STARTED_AT_FILE = `${STATE_DIR}/recording-started-at.txt`;
 var RECORD_FPS_FILE = `${STATE_DIR}/recording-fps.txt`;
 var RECORD_DIMENSIONS_FILE = `${STATE_DIR}/recording-dimensions.json`;
 var RECORD_ACTIONS_FILE = `${STATE_DIR}/recording-actions.jsonl`;
+var RECORD_STATE_FILES = [
+  RECORD_PID_FILE,
+  RECORD_PATH_FILE,
+  RECORD_RAW_PATH_FILE,
+  RECORD_STARTED_AT_FILE,
+  RECORD_FPS_FILE,
+  RECORD_DIMENSIONS_FILE,
+  RECORD_ACTIONS_FILE
+];
+function clearRecordingState() {
+  for (const file of RECORD_STATE_FILES) rmSync2(file, { force: true });
+}
 function recordingStartedAt() {
   if (!existsSync2(RECORD_STARTED_AT_FILE)) return null;
   const startedAt = Number.parseInt(readFileSync2(RECORD_STARTED_AT_FILE, "utf8").trim(), 10);
@@ -15548,13 +15598,13 @@ async function computerRecordStartCommand(path6, options) {
   if (existsSync2(RECORD_PID_FILE)) {
     const pid = parseInt(readFileSync2(RECORD_PID_FILE, "utf8").trim(), 10);
     if (Number.isFinite(pid)) {
-      let alive = false;
+      let alive2 = false;
       try {
         process.kill(pid, 0);
-        alive = true;
+        alive2 = true;
       } catch {
       }
-      if (alive) fail(`recording already in progress (pid ${pid}). run \`replicas computer record stop\` first.`);
+      if (alive2) fail(`recording already in progress (pid ${pid}). run \`replicas computer record stop\` first.`);
     }
   }
   const target = resolvePath(path6);
@@ -15601,7 +15651,29 @@ async function computerRecordStartCommand(path6, options) {
   writeFileSync2(RECORD_STARTED_AT_FILE, String(Date.now()));
   writeFileSync2(RECORD_FPS_FILE, String(fps));
   writeFileSync2(RECORD_DIMENSIONS_FILE, JSON.stringify({ width, height }));
-  console.log(target);
+  const startedAt = Date.now();
+  while (Date.now() - startedAt < 5e3) {
+    try {
+      process.kill(child.pid, 0);
+      if (existsSync2(rawTarget) && statSync(rawTarget).size > 0) {
+        console.log(`${target} (recording ready in ${Date.now() - startedAt}ms)`);
+        return;
+      }
+    } catch {
+      break;
+    }
+    await sleep(100);
+  }
+  let alive = false;
+  try {
+    process.kill(child.pid, 0);
+    alive = true;
+  } catch {
+  }
+  if (alive) fail("ffmpeg is running but did not produce recording output within 5 seconds; run `replicas computer record stop` to finalize or retry");
+  clearRecordingState();
+  rmSync2(rawTarget, { force: true });
+  fail("ffmpeg exited before screen recording became ready");
 }
 async function computerRecordStopCommand() {
   if (!existsSync2(RECORD_PID_FILE) && !existsSync2(RECORD_PATH_FILE)) fail("no recording in progress");
@@ -15612,15 +15684,17 @@ async function computerRecordStopCommand() {
       process.kill(pid, "SIGINT");
     } catch {
     }
-    for (let i = 0; i < 30; i++) {
+    let alive = true;
+    for (let i = 0; i < 150; i++) {
       try {
         process.kill(pid, 0);
       } catch {
+        alive = false;
         break;
       }
-      await new Promise((r) => setTimeout(r, 200));
+      await sleep(200);
     }
-    rmSync2(RECORD_PID_FILE, { force: true });
+    if (alive) fail(`ffmpeg did not finalize recording within 30 seconds (pid ${pid})`);
   }
   if (existsSync2(RECORD_PATH_FILE)) {
     const target = readFileSync2(RECORD_PATH_FILE, "utf8").trim();
@@ -15633,13 +15707,8 @@ async function computerRecordStopCommand() {
       rmSync2(rawPath, { force: true });
     }
     console.log(target);
-    rmSync2(RECORD_PATH_FILE, { force: true });
-    rmSync2(RECORD_RAW_PATH_FILE, { force: true });
-    rmSync2(RECORD_STARTED_AT_FILE, { force: true });
-    rmSync2(RECORD_FPS_FILE, { force: true });
-    rmSync2(RECORD_DIMENSIONS_FILE, { force: true });
-    rmSync2(RECORD_ACTIONS_FILE, { force: true });
   }
+  clearRecordingState();
 }
 
 // src/commands/computer/index.ts
@@ -15978,8 +16047,8 @@ async function getChromePages() {
 async function selectChromePage(options = {}) {
   const pages = await getChromePages();
   let matches = pages;
-  if (options.id) {
-    matches = matches.filter((page2) => page2.id === options.id);
+  if (options.targetId) {
+    matches = matches.filter((page2) => page2.id === options.targetId);
   }
   if (options.title) {
     const needle = options.title.toLowerCase();
@@ -15998,121 +16067,528 @@ async function selectChromePage(options = {}) {
       `No matching debuggable Chrome page found (${matches.length} match${matches.length === 1 ? "" : "es"}, index ${index}). Use \`replicas computer browser\` to list pages.`
     );
   }
+  await sendChromeCommand(webSocketDebuggerUrl, "Page.bringToFront", {});
   return { ...page, webSocketDebuggerUrl };
 }
-function buildBrowserSnapshotExpression(textLimit, elementLimit) {
-  return `(() => {
-    const clip = (value, limit) => String(value || '').replace(/\\s+/g, ' ').trim().slice(0, limit);
-    const escape = (value) => globalThis.CSS && CSS.escape ? CSS.escape(value) : String(value).replace(/["\\\\]/g, '\\\\$&');
+var VISIBLE_JS = `
     const visible = (el) => {
       const rect = el.getBoundingClientRect();
       const style = getComputedStyle(el);
       return rect.width > 0 && rect.height > 0 && style.visibility !== 'hidden' && style.display !== 'none';
-    };
-    const labels = (el) => {
-      const values = [];
-      const id = el.getAttribute('id');
-      if (id) values.push(...Array.from(document.querySelectorAll('label[for="' + escape(id) + '"]')).map((label) => label.innerText));
-      const wrappingLabel = el.closest('label');
-      if (wrappingLabel) values.push(wrappingLabel.innerText);
-      values.push(el.innerText, el.value, el.getAttribute('aria-label'), el.getAttribute('title'), el.getAttribute('placeholder'), el.href, el.id, el.name, el.tagName);
-      return values.map((value) => clip(value, 160)).filter(Boolean);
-    };
-    const name = (el) => labels(el)[0] || clip(el.tagName, 160);
-    const selector = 'a,button,input,textarea,select,[role="button"],[role="link"],[role="textbox"],[contenteditable="true"]';
-    const controls = Array.from(document.querySelectorAll(selector))
-      .filter(visible)
-      .slice(0, ${elementLimit})
-      .map((el) => {
-        const rect = el.getBoundingClientRect();
-        return {
-          tag: el.tagName.toLowerCase(),
-          role: el.getAttribute('role') || null,
-          type: el.getAttribute('type') || null,
-          text: name(el),
-          href: el.href || null,
-          disabled: !!el.disabled || el.getAttribute('aria-disabled') === 'true',
-          rect: {
-            x: Math.round(rect.x),
-            y: Math.round(rect.y),
-            width: Math.round(rect.width),
-            height: Math.round(rect.height),
-            centerX: Math.round(rect.x + rect.width / 2),
-            centerY: Math.round(rect.y + rect.height / 2),
-          },
-        };
-      });
-    return {
-      title: document.title,
-      url: location.href,
-      text: clip(document.body ? document.body.innerText : '', ${textLimit}),
-      controls,
-    };
-  })()`;
+    };`;
+async function sendChromeSessionCommand(session, method, params) {
+  return chromeResult(await session.send({ method, params }), method);
 }
-async function evaluateChromeTarget(webSocketDebuggerUrl, expression) {
+async function withChromeSession(webSocketDebuggerUrl, callback) {
   return await new Promise((resolve2, reject) => {
     const ws = new WebSocket(webSocketDebuggerUrl);
+    const pending = /* @__PURE__ */ new Map();
+    let nextId = 1;
     let settled = false;
-    const finish = (callback) => {
+    const failSession = (error) => {
       if (settled) return;
       settled = true;
-      clearTimeout(timeout);
+      for (const request of pending.values()) {
+        clearTimeout(request.timeout);
+        request.reject(error);
+      }
+      pending.clear();
       ws.close();
-      callback();
+      reject(error);
     };
-    const timeout = setTimeout(() => {
-      finish(() => reject(new Error("Chrome DevTools evaluation timed out")));
-    }, 5e3);
-    ws.addEventListener("open", () => {
-      ws.send(JSON.stringify({
-        id: 1,
-        method: "Runtime.evaluate",
-        params: {
-          expression,
-          awaitPromise: true,
-          returnByValue: true
-        }
-      }));
+    const finishSession = (value) => {
+      if (settled) return;
+      settled = true;
+      for (const request of pending.values()) clearTimeout(request.timeout);
+      pending.clear();
+      ws.close();
+      resolve2(value);
+    };
+    const session = {
+      send: ({ method, params }) => new Promise((resolveCommand, rejectCommand) => {
+        const id = nextId++;
+        const timeout = setTimeout(() => {
+          pending.delete(id);
+          rejectCommand(new Error(`Chrome DevTools ${method} timed out`));
+        }, 1e4);
+        pending.set(id, { method, resolve: resolveCommand, reject: rejectCommand, timeout });
+        ws.send(JSON.stringify({ id, method, params }));
+      })
+    };
+    ws.addEventListener("open", async () => {
+      try {
+        finishSession(await callback(session));
+      } catch (error) {
+        failSession(error instanceof Error ? error : new Error(String(error)));
+      }
     });
     ws.addEventListener("message", (event) => {
       const data = typeof event.data === "string" ? event.data : Buffer.isBuffer(event.data) ? event.data.toString("utf8") : Buffer.from(event.data).toString("utf8");
-      let parsed;
+      let message;
       try {
-        parsed = JSON.parse(data);
+        message = JSON.parse(data);
       } catch (error) {
-        const reason = error instanceof Error ? error.message : String(error);
-        finish(() => reject(new Error(`Chrome DevTools returned invalid WebSocket JSON: ${reason}`)));
-        return;
-      }
-      if (typeof parsed !== "object" || parsed === null) {
-        finish(() => reject(new Error("Chrome DevTools returned an invalid WebSocket message")));
+        failSession(new Error(`Chrome DevTools returned invalid WebSocket JSON: ${error instanceof Error ? error.message : String(error)}`));
         return;
       }
-      const message = parsed;
-      if (message.id !== 1) return;
-      if (message.error) {
-        finish(() => reject(new Error(message.error?.message || "Chrome DevTools evaluation failed")));
-        return;
-      }
-      if (message.result?.exceptionDetails) {
-        finish(() => reject(new Error(message.result.exceptionDetails.text || "Chrome DevTools evaluation threw")));
-        return;
-      }
-      finish(() => resolve2(message.result?.result?.value ?? null));
+      if (!isRecord(message) || typeof message.id !== "number") return;
+      const request = pending.get(message.id);
+      if (!request) return;
+      clearTimeout(request.timeout);
+      pending.delete(message.id);
+      const detail = isRecord(message.error) && typeof message.error.message === "string" ? message.error.message : void 0;
+      request.resolve(message.error ? { error: { message: detail } } : { result: isRecord(message.result) ? message.result : {} });
     });
-    ws.addEventListener("error", () => {
-      finish(() => reject(new Error("Chrome DevTools WebSocket failed")));
+    ws.addEventListener("error", () => failSession(new Error("Chrome DevTools WebSocket failed")));
+    ws.addEventListener("close", () => {
+      if (!settled) failSession(new Error("Chrome DevTools WebSocket closed unexpectedly"));
     });
   });
 }
+async function sendChromeCommands(webSocketDebuggerUrl, commands) {
+  return await withChromeSession(webSocketDebuggerUrl, async (session) => await Promise.all(commands.map((command) => session.send(command))));
+}
+async function sendChromeCommand(webSocketDebuggerUrl, method, params) {
+  const response = (await sendChromeCommands(webSocketDebuggerUrl, [{ method, params }]))[0];
+  if (response.error) throw new Error(response.error.message || `Chrome DevTools ${method} failed`);
+  return response.result ?? {};
+}
+async function callFunctionOnChromeNodeInSession(session, backendNodeId, functionDeclaration, args = []) {
+  const resolved = await sendChromeSessionCommand(session, "DOM.resolveNode", { backendNodeId });
+  const objectId = isRecord(resolved.object) ? resolved.object.objectId : void 0;
+  if (typeof objectId !== "string") throw new Error(`Could not resolve browser element ref ${backendNodeId}`);
+  return await sendChromeSessionCommand(session, "Runtime.callFunctionOn", {
+    objectId,
+    functionDeclaration,
+    arguments: args.map((value) => ({ value })),
+    returnByValue: true
+  });
+}
+function chromeCallValue(response) {
+  return isRecord(response.result) ? response.result.value : void 0;
+}
+async function evaluateChromeTarget(webSocketDebuggerUrl, expression) {
+  return await withChromeSession(webSocketDebuggerUrl, async (session) => await evaluateChromeSession(session, expression));
+}
+async function evaluateChromeSession(session, expression) {
+  const response = await sendChromeSessionCommand(session, "Runtime.evaluate", {
+    expression,
+    awaitPromise: true,
+    returnByValue: true
+  });
+  const exception = response.exceptionDetails;
+  if (exception) {
+    const text = typeof exception === "object" && exception !== null && "text" in exception && typeof exception.text === "string" ? exception.text : "";
+    throw new Error(text || "Chrome DevTools evaluation threw");
+  }
+  const evaluated = response.result;
+  return typeof evaluated === "object" && evaluated !== null && "value" in evaluated ? evaluated.value ?? null : null;
+}
+function isRawAXNode(value) {
+  return isRecord(value);
+}
+function isDOMSnapshotDocument(value) {
+  return isRecord(value);
+}
+function chromeVisualViewport(layout) {
+  const viewport = isRecord(layout.cssVisualViewport) ? layout.cssVisualViewport : {};
+  return {
+    width: typeof viewport.clientWidth === "number" ? viewport.clientWidth : 0,
+    height: typeof viewport.clientHeight === "number" ? viewport.clientHeight : 0
+  };
+}
+function roundBrowserRect(rect) {
+  return {
+    x: Math.round(rect.x),
+    y: Math.round(rect.y),
+    width: Math.round(rect.width),
+    height: Math.round(rect.height),
+    centerX: Math.round(rect.centerX),
+    centerY: Math.round(rect.centerY)
+  };
+}
+function browserStateProperties(node) {
+  const properties = [];
+  for (const { name, value } of node.properties ?? []) {
+    const state = value?.value;
+    if (!name || !BROWSER_STATE_PROPERTIES.has(name) || typeof state !== "string" && typeof state !== "number" && typeof state !== "boolean") continue;
+    properties.push([name, name === "url" ? clippedText(state, 300) : state]);
+  }
+  return Object.fromEntries(properties);
+}
+function readBrowserStateCache(path6) {
+  let value;
+  try {
+    value = JSON.parse(readFileSync3(path6, "utf8"));
+  } catch {
+    return null;
+  }
+  if (!isRecord(value) || !Array.isArray(value.entries)) return null;
+  const entries = [];
+  for (const entry of value.entries) {
+    if (!isRecord(entry) || typeof entry.key !== "string" || typeof entry.semantic !== "string" || typeof entry.line !== "string") return null;
+    entries.push({ key: entry.key, semantic: entry.semantic, line: entry.line });
+  }
+  return {
+    url: typeof value.url === "string" ? value.url : void 0,
+    documentId: typeof value.documentId === "string" || value.documentId === null ? value.documentId : void 0,
+    entries
+  };
+}
+function chromeResult(response, method) {
+  if (response.error) throw new Error(response.error.message || `Chrome DevTools ${method} failed`);
+  return response.result ?? {};
+}
+function collectFrameIds(frameTree) {
+  const ids = [];
+  const visit = (value) => {
+    if (!isRecord(value)) return;
+    const frame = isRecord(value.frame) ? value.frame : {};
+    if (typeof frame.id === "string") ids.push(frame.id);
+    if (Array.isArray(value.childFrames)) value.childFrames.forEach(visit);
+  };
+  visit(frameTree);
+  return ids;
+}
+function browserDocumentId(frameTree) {
+  if (!isRecord(frameTree) || !isRecord(frameTree.frame)) return null;
+  const loaderId = frameTree.frame.loaderId;
+  return typeof loaderId === "string" ? loaderId : null;
+}
+function intersectRects(a, b) {
+  const x = Math.max(a.x, b.x);
+  const y = Math.max(a.y, b.y);
+  const right = Math.min(a.x + a.width, b.x + b.width);
+  const bottom = Math.min(a.y + a.height, b.y + b.height);
+  if (right <= x || bottom <= y) return null;
+  return {
+    x,
+    y,
+    width: right - x,
+    height: bottom - y,
+    centerX: x + (right - x) / 2,
+    centerY: y + (bottom - y) / 2
+  };
+}
+function browserContentQuadRects(quads, viewportRect) {
+  if (!Array.isArray(quads)) return [];
+  return quads.filter((quad) => Array.isArray(quad) && quad.length >= 8 && quad.every(Number.isFinite)).map((quad) => {
+    const xs = [quad[0], quad[2], quad[4], quad[6]];
+    const ys = [quad[1], quad[3], quad[5], quad[7]];
+    const x = Math.min(...xs);
+    const y = Math.min(...ys);
+    const width = Math.max(...xs) - x;
+    const height = Math.max(...ys) - y;
+    return { x, y, width, height, centerX: x + width / 2, centerY: y + height / 2 };
+  }).map((rect) => intersectRects(rect, viewportRect)).filter((rect) => !!rect).sort((a, b) => b.width * b.height - a.width * a.height);
+}
+function buildBrowserBounds(result, viewport, targetId) {
+  const strings = Array.isArray(result.strings) ? result.strings : [];
+  const documents = Array.isArray(result.documents) ? result.documents.filter(isDOMSnapshotDocument) : [];
+  const localRects = documents.map((document) => {
+    const rects = /* @__PURE__ */ new Map();
+    const nodeIndexes = document.layout?.nodeIndex ?? [];
+    const bounds = document.layout?.bounds ?? [];
+    const scrollX = document.scrollOffsetX ?? 0;
+    const scrollY = document.scrollOffsetY ?? 0;
+    nodeIndexes.forEach((nodeIndex, index) => {
+      const bound = bounds[index];
+      if (!Array.isArray(bound) || bound.length < 4 || !bound.every(Number.isFinite)) return;
+      const [rawX, rawY, width, height] = bound;
+      rects.set(nodeIndex, {
+        x: rawX - scrollX,
+        y: rawY - scrollY,
+        width,
+        height,
+        centerX: rawX - scrollX + width / 2,
+        centerY: rawY - scrollY + height / 2
+      });
+    });
+    return rects;
+  });
+  const parents = /* @__PURE__ */ new Map();
+  documents.forEach((document, documentIndex) => {
+    const sparse = document.nodes?.contentDocumentIndex;
+    sparse?.index?.forEach((nodeIndex, index) => {
+      const childDocumentIndex = sparse.value?.[index];
+      if (typeof childDocumentIndex === "number") parents.set(childDocumentIndex, { documentIndex, nodeIndex });
+    });
+  });
+  const targetDocumentIndex = documents.findIndex(
+    (document) => typeof document.frameId === "number" && strings[document.frameId] === targetId
+  );
+  const rootIndex = targetDocumentIndex >= 0 ? targetDocumentIndex : documents.findIndex((_, index) => !parents.has(index));
+  const viewportRect = {
+    x: 0,
+    y: 0,
+    width: viewport.width,
+    height: viewport.height,
+    centerX: viewport.width / 2,
+    centerY: viewport.height / 2
+  };
+  const origins = /* @__PURE__ */ new Map();
+  origins.set(rootIndex < 0 ? 0 : rootIndex, { x: 0, y: 0, clip: viewportRect });
+  for (let pass = 0; pass < documents.length; pass++) {
+    let changed = false;
+    for (const [childIndex, parent] of parents) {
+      if (origins.has(childIndex)) continue;
+      const parentOrigin = origins.get(parent.documentIndex);
+      const frameRect = localRects[parent.documentIndex]?.get(parent.nodeIndex);
+      if (!parentOrigin || !frameRect) continue;
+      const globalFrameRect = {
+        ...frameRect,
+        x: parentOrigin.x + frameRect.x,
+        y: parentOrigin.y + frameRect.y,
+        centerX: parentOrigin.x + frameRect.centerX,
+        centerY: parentOrigin.y + frameRect.centerY
+      };
+      const childDocument = documents[childIndex];
+      const insetX = Math.max(0, (globalFrameRect.width - (childDocument?.contentWidth ?? globalFrameRect.width)) / 2);
+      const insetY = Math.max(0, (globalFrameRect.height - (childDocument?.contentHeight ?? globalFrameRect.height)) / 2);
+      const contentRect = {
+        x: globalFrameRect.x + insetX,
+        y: globalFrameRect.y + insetY,
+        width: Math.max(0, globalFrameRect.width - insetX * 2),
+        height: Math.max(0, globalFrameRect.height - insetY * 2),
+        centerX: globalFrameRect.centerX,
+        centerY: globalFrameRect.centerY
+      };
+      const clip = intersectRects(parentOrigin.clip, contentRect);
+      if (!clip) continue;
+      origins.set(childIndex, { x: contentRect.x, y: contentRect.y, clip });
+      changed = true;
+    }
+    if (!changed) break;
+  }
+  const byBackendNodeId = /* @__PURE__ */ new Map();
+  documents.forEach((document, documentIndex) => {
+    const origin = origins.get(documentIndex);
+    if (!origin) return;
+    const backendNodeIds = document.nodes?.backendNodeId ?? [];
+    for (const [nodeIndex, local] of localRects[documentIndex] ?? []) {
+      const backendNodeId = backendNodeIds[nodeIndex];
+      if (!Number.isInteger(backendNodeId)) continue;
+      const rect = {
+        ...local,
+        x: origin.x + local.x,
+        y: origin.y + local.y,
+        centerX: origin.x + local.centerX,
+        centerY: origin.y + local.centerY
+      };
+      if (intersectRects(rect, origin.clip)) byBackendNodeId.set(backendNodeId, { rect, clip: origin.clip });
+    }
+  });
+  return byBackendNodeId;
+}
+var BROWSER_INTERACTIVE_ROLES = /* @__PURE__ */ new Set([
+  "button",
+  "checkbox",
+  "combobox",
+  "link",
+  "listbox",
+  "menuitem",
+  "menuitemcheckbox",
+  "menuitemradio",
+  "option",
+  "radio",
+  "scrollbar",
+  "searchbox",
+  "slider",
+  "spinbutton",
+  "switch",
+  "tab",
+  "textbox",
+  "treeitem"
+]);
+var BROWSER_STRUCTURAL_ROLES = /* @__PURE__ */ new Set([
+  "alert",
+  "cell",
+  "columnheader",
+  "dialog",
+  "figure",
+  "gridcell",
+  "heading",
+  "image",
+  "listitem",
+  "main",
+  "paragraph",
+  "region",
+  "row",
+  "rowheader",
+  "status",
+  "StaticText"
+]);
+var BROWSER_STATE_PROPERTIES = /* @__PURE__ */ new Set([
+  "autocomplete",
+  "checked",
+  "disabled",
+  "editable",
+  "expanded",
+  "focusable",
+  "focused",
+  "haspopup",
+  "invalid",
+  "level",
+  "multiselectable",
+  "orientation",
+  "pressed",
+  "readonly",
+  "protected",
+  "required",
+  "selected",
+  "url"
+]);
+function clippedText(value, limit = 240) {
+  return String(value ?? "").replace(/\s+/g, " ").trim().slice(0, limit);
+}
+function browserTargetOutput(page) {
+  return {
+    targetId: page.id ?? null,
+    title: (page.title ?? "").slice(0, 1e3),
+    url: (page.url ?? "").slice(0, 2e3)
+  };
+}
+function browserNodeActionable(role, states) {
+  return BROWSER_INTERACTIVE_ROLES.has(role) || states.editable === true || states.focusable === true && role !== "RootWebArea";
+}
+async function captureBrowserSnapshot(page, options) {
+  const initialCommands = [
+    { method: "Page.getFrameTree", params: {} },
+    { method: "Page.getLayoutMetrics", params: {} },
+    { method: "DOMSnapshot.captureSnapshot", params: { computedStyles: [], includeDOMRects: true, includePaintOrder: true } }
+  ];
+  const initial = await sendChromeCommands(page.webSocketDebuggerUrl, initialCommands);
+  const frameTree = chromeResult(initial[0], initialCommands[0].method).frameTree;
+  const layout = chromeResult(initial[1], initialCommands[1].method);
+  const domSnapshot = chromeResult(initial[2], initialCommands[2].method);
+  const viewport = chromeVisualViewport(layout);
+  const frameIds = collectFrameIds(frameTree);
+  if (frameIds.length === 0 && page.id) frameIds.push(page.id);
+  const axCommands = frameIds.map((frameId) => ({
+    method: "Accessibility.getFullAXTree",
+    params: { frameId }
+  }));
+  const axResults = await sendChromeCommands(page.webSocketDebuggerUrl, axCommands);
+  const nodes = [];
+  axResults.forEach((response, index) => {
+    if (response.error) return;
+    const responseNodes = response.result?.nodes;
+    if (!Array.isArray(responseNodes)) return;
+    for (const node of responseNodes) {
+      if (!isRawAXNode(node)) continue;
+      nodes.push({ ...node, sourceFrameId: frameIds[index] });
+    }
+  });
+  const bounds = buildBrowserBounds(domSnapshot, viewport, page.id);
+  const nodesByKey = new Map(nodes.map((node) => [`${node.sourceFrameId}:${node.nodeId}`, node]));
+  const propertyMap = browserStateProperties;
+  const roleOf = (node) => clippedText(node.role?.value, 80);
+  const nameOf = (node) => clippedText(node.name?.value);
+  const valueOf = (node) => {
+    if (propertyMap(node).protected === true) return null;
+    const value = node.value?.value;
+    if (typeof value === "number" || typeof value === "boolean") return value;
+    const text = clippedText(value);
+    if (/^[•●*]+$/.test(text)) return "[protected]";
+    return text || null;
+  };
+  const meaningful = nodes.filter((node) => !node.ignored && Number.isInteger(node.backendDOMNodeId)).map((node) => ({
+    node,
+    role: roleOf(node),
+    bound: typeof node.backendDOMNodeId === "number" ? bounds.get(node.backendDOMNodeId) : void 0
+  })).filter(({ node, role, bound }) => {
+    if (!bound || bound.rect.width <= 0 || bound.rect.height <= 0) return false;
+    if (role === "InlineTextBox" || role === "none" || role === "generic") return false;
+    if (BROWSER_INTERACTIVE_ROLES.has(role) || BROWSER_STRUCTURAL_ROLES.has(role)) return true;
+    return !!nameOf(node) || valueOf(node) !== null || propertyMap(node).focusable === true;
+  }).filter(({ node, role }) => {
+    if (role !== "StaticText") return true;
+    const parent = node.parentId ? nodesByKey.get(`${node.sourceFrameId}:${node.parentId}`) : void 0;
+    return !parent || nameOf(parent) !== nameOf(node);
+  }).sort((a, b) => a.bound.rect.y - b.bound.rect.y || a.bound.rect.x - b.bound.rect.x);
+  const elements = [];
+  const entries = [];
+  const meaningfulKeys = new Set(meaningful.map(({ node }) => `${node.sourceFrameId}:${node.nodeId}`));
+  const visibleText = [];
+  let visibleTextLength = 0;
+  let treeLength = 0;
+  const treeLimit = Math.min(5e4, Math.max(4e3, options.textLimit * 2));
+  for (const { node, role, bound } of meaningful) {
+    const name = nameOf(node);
+    const description = clippedText(node.description?.value) || null;
+    const value = valueOf(node);
+    const states = propertyMap(node);
+    const actionable = browserNodeActionable(role, states);
+    const ref = actionable && elements.length < options.elementLimit ? String(node.backendDOMNodeId) : null;
+    const visibleRect = role === "RootWebArea" && node.sourceFrameId === page.id ? { x: 0, y: 0, width: viewport.width, height: viewport.height, centerX: viewport.width / 2, centerY: viewport.height / 2 } : intersectRects(bound.rect, bound.clip) ?? bound.rect;
+    const rect = roundBrowserRect(visibleRect);
+    const actions = [
+      ...actionable ? ["click"] : [],
+      ...["textbox", "searchbox", "combobox", "spinbutton", "slider"].includes(role) || states.editable === true ? ["set_value"] : [],
+      "scroll"
+    ];
+    if (ref) {
+      elements.push({
+        ref,
+        role,
+        name: name || null,
+        description,
+        value,
+        states,
+        actions,
+        rect,
+        frameId: node.sourceFrameId
+      });
+    }
+    const stateText = Object.entries(states).filter(([key]) => key !== "url" && key !== "focusable").map(([key, state]) => `${key}=${JSON.stringify(state)}`);
+    const url = typeof states.url === "string" ? clippedText(states.url, 300) : "";
+    const semantic = [role, name && JSON.stringify(name), value !== null && `value=${JSON.stringify(value)}`, description && `description=${JSON.stringify(description)}`, url && `url=${JSON.stringify(url)}`, ...stateText].filter(Boolean).join(" ");
+    let depth = 0;
+    let parentId = node.parentId;
+    const visited = /* @__PURE__ */ new Set();
+    while (parentId && depth < 8) {
+      const parentKey = `${node.sourceFrameId}:${parentId}`;
+      if (visited.has(parentKey)) break;
+      visited.add(parentKey);
+      if (meaningfulKeys.has(parentKey)) depth++;
+      parentId = nodesByKey.get(parentKey)?.parentId;
+    }
+    const line = `${"  ".repeat(depth)}${ref ? `[ref=${ref}]` : "-"} ${semantic} (${rect.x},${rect.y} ${rect.width}x${rect.height})`;
+    if (treeLength + line.length + 1 <= treeLimit) {
+      const key = Number.isInteger(node.backendDOMNodeId) ? `dom:${node.sourceFrameId}:${node.backendDOMNodeId}` : `ax:${node.sourceFrameId}:${node.nodeId}`;
+      entries.push({ key, semantic, line });
+      treeLength += line.length + 1;
+    }
+    if (name && visibleTextLength < options.textLimit && (role === "StaticText" || role === "heading" || BROWSER_INTERACTIVE_ROLES.has(role))) {
+      const remaining = options.textLimit - visibleTextLength;
+      visibleText.push(name.slice(0, remaining));
+      visibleTextLength += Math.min(name.length, remaining) + 1;
+    }
+  }
+  const revision = createHash2("sha256").update(JSON.stringify([page.url, entries.map(({ key, semantic }) => [key, semantic])])).digest("hex").slice(0, 16);
+  const snapshot = {
+    title: (page.title ?? "").slice(0, 1e3),
+    url: (page.url ?? "").slice(0, 2e3),
+    documentId: browserDocumentId(frameTree),
+    revision,
+    viewport,
+    text: visibleText.join(" ").slice(0, options.textLimit),
+    tree: entries.map(({ line }) => line).join("\n"),
+    elements,
+    controls: elements,
+    nodeCount: entries.length,
+    elementCount: elements.length,
+    truncated: entries.length < meaningful.length || elements.length < meaningful.filter(({ node, role }) => browserNodeActionable(role, propertyMap(node))).length
+  };
+  return { snapshot, entries };
+}
 async function computerBrowserCommand(options = {}) {
   const textLimit = options.limit ? parseCoord(options.limit, "--limit") : 4e3;
   const elementLimit = options.elementLimit ? parseCoord(options.elementLimit, "--element-limit") : 80;
   if (textLimit < 0 || textLimit > 5e4) fail("--limit must be between 0 and 50000");
   if (elementLimit < 0 || elementLimit > 500) fail("--element-limit must be between 0 and 500");
-  const expression = buildBrowserSnapshotExpression(textLimit, elementLimit);
-  const pages = (await getChromePages()).map((target) => ({
+  const targets = options.targetId || options.page || options.title || options.url ? [await selectChromePage(options)] : await getChromePages();
+  const pages = targets.map((target) => ({
     target,
     page: {
       id: target.id ?? null,
@@ -16125,7 +16601,11 @@ async function computerBrowserCommand(options = {}) {
   for (const { target, page } of pages) {
     if (options.snapshot && target.webSocketDebuggerUrl) {
       try {
-        pageResults.push({ ...page, snapshot: await evaluateChromeTarget(target.webSocketDebuggerUrl, expression) });
+        const { snapshot } = await captureBrowserSnapshot(
+          { ...target, webSocketDebuggerUrl: target.webSocketDebuggerUrl },
+          { textLimit, elementLimit }
+        );
+        pageResults.push({ ...page, snapshot });
       } catch (error) {
         pageResults.push({ ...page, snapshotError: error instanceof Error ? error.message : "snapshot failed" });
       }
@@ -16139,6 +16619,188 @@ async function computerBrowserCommand(options = {}) {
     pages: pageResults
   }, null, 2));
 }
+function buildBrowserStabilityExpression() {
+  return `(() => {
+    const key = '__replicasComputerUseObserver';
+    if (!globalThis[key]) {
+      const state = { revision: 0 };
+      const observer = new MutationObserver(() => state.revision++);
+      globalThis[key] = { state, observer, observing: false };
+    }
+    if (document.documentElement && !globalThis[key].observing) {
+      globalThis[key].observer.observe(document.documentElement, {
+        subtree: true,
+        childList: true,
+        attributes: true,
+        characterData: true,
+      });
+      globalThis[key].observing = true;
+    }
+    const controls = Array.from(document.querySelectorAll('input,textarea,select,[contenteditable="true"],[role="checkbox"],[role="combobox"],[role="slider"],[role="switch"],[role="textbox"]')).slice(0, 200);
+    const active = document.activeElement;
+    const controlState = controls.map((element, index) => {
+      const value = 'value' in element
+        ? element instanceof HTMLInputElement && element.type === 'password'
+          ? String(element.value).length
+          : String(element.value)
+        : element.textContent;
+      return [
+        index,
+        element === active,
+        value,
+        'checked' in element ? element.checked : null,
+        'selectedIndex' in element ? element.selectedIndex : null,
+        'disabled' in element ? element.disabled : null,
+        element.getAttribute('aria-checked'),
+        element.getAttribute('aria-expanded'),
+        element.getAttribute('aria-selected'),
+      ].join('|');
+    }).join('\\u001f');
+    let controlRevision = 2166136261;
+    for (let index = 0; index < controlState.length; index++) {
+      controlRevision ^= controlState.charCodeAt(index);
+      controlRevision = Math.imul(controlRevision, 16777619);
+    }
+    return {
+      revision: globalThis[key].state.revision,
+      controlRevision: (controlRevision >>> 0).toString(16),
+      readyState: document.readyState,
+      busy: !!document.querySelector('[aria-busy="true"]'),
+      url: location.href.slice(0, 2000),
+      scrollX: Math.round(scrollX),
+      scrollY: Math.round(scrollY),
+      innerWidth,
+      innerHeight,
+      devicePixelRatio,
+    };
+  })()`;
+}
+async function waitForBrowserStability(page, options) {
+  const startedAt = Date.now();
+  let lastSignature = null;
+  let lastChangeAt = startedAt;
+  let samples = 0;
+  let changes = 0;
+  let state = null;
+  while (Date.now() - startedAt <= options.timeoutMs) {
+    try {
+      state = await evaluateChromeTarget(page.webSocketDebuggerUrl, buildBrowserStabilityExpression());
+      samples++;
+      const signature = JSON.stringify(state);
+      const now = Date.now();
+      if (lastSignature === null || signature !== lastSignature) {
+        if (lastSignature !== null) changes++;
+        lastSignature = signature;
+        lastChangeAt = now;
+      }
+      const ready = typeof state === "object" && state !== null && "readyState" in state && state.readyState !== "loading" && "busy" in state && state.busy !== true;
+      if (samples > 1 && ready && now - lastChangeAt >= options.stableMs) {
+        return { stable: true, elapsedMs: now - startedAt, samples, changes, state };
+      }
+    } catch {
+    }
+    await sleep(options.pollMs);
+  }
+  return { stable: false, elapsedMs: Date.now() - startedAt, samples, changes, state };
+}
+function browserStateCachePath(targetId) {
+  return `${STATE_DIR}/browser-state-${targetId.replace(/[^a-zA-Z0-9_-]/g, "_")}.json`;
+}
+function browserStateDiff(previous, current) {
+  const before = new Map(previous.map((entry) => [entry.key, entry]));
+  const after = new Map(current.map((entry) => [entry.key, entry]));
+  const lines = [];
+  let added = 0;
+  let changed = 0;
+  let removed = 0;
+  for (const entry of current) {
+    const old = before.get(entry.key);
+    if (!old) {
+      added++;
+      lines.push(`+ ${entry.line}`);
+    } else if (old.semantic !== entry.semantic) {
+      changed++;
+      lines.push(`~ ${old.line}
+  ${entry.line}`);
+    }
+  }
+  for (const entry of previous) {
+    if (after.has(entry.key)) continue;
+    removed++;
+    lines.push(`- ${entry.line}`);
+  }
+  return { tree: lines.join("\n") || "No accessibility changes.", added, changed, removed };
+}
+async function computerBrowserStateCommand(path6, options = {}) {
+  const textLimit = options.limit ? parseCoord(options.limit, "--limit") : 8e3;
+  const elementLimit = options.elementLimit ? parseCoord(options.elementLimit, "--element-limit") : 120;
+  const timeoutMs = options.timeout ? parseCoord(options.timeout, "--timeout") : 5e3;
+  const stableMs = options.stableMs ? parseCoord(options.stableMs, "--stable-ms") : 500;
+  const pollMs = options.pollMs ? parseCoord(options.pollMs, "--poll-ms") : 100;
+  if (textLimit < 0 || textLimit > 5e4) fail("--limit must be between 0 and 50000");
+  if (elementLimit < 0 || elementLimit > 500) fail("--element-limit must be between 0 and 500");
+  if (timeoutMs < 0) fail("--timeout must be >= 0");
+  if (stableMs < 0) fail("--stable-ms must be >= 0");
+  if (pollMs < 50 || pollMs > 2e3) fail("--poll-ms must be between 50 and 2000");
+  const page = await selectChromePage(options);
+  const stability = await waitForBrowserStability(page, { timeoutMs, stableMs, pollMs });
+  const target = resolvePath(path6);
+  mkdirSync3(dirname3(target), { recursive: true });
+  const [{ snapshot, entries }, screenshotResult] = await Promise.all([
+    captureBrowserSnapshot(page, { textLimit, elementLimit }),
+    sendChromeCommand(page.webSocketDebuggerUrl, "Page.captureScreenshot", {
+      format: "png",
+      fromSurface: true,
+      captureBeyondViewport: false
+    })
+  ]);
+  const data = screenshotResult.data;
+  if (typeof data !== "string") fail("Chrome did not return screenshot data");
+  writeFileSync3(target, Buffer.from(data, "base64"));
+  const screenshot = readPngDimensions(target);
+  const targetId = page.id ?? "unknown";
+  const cachePath = browserStateCachePath(targetId);
+  let mode = "full";
+  let tree = snapshot.tree;
+  let changes = { added: snapshot.nodeCount, changed: 0, removed: 0 };
+  if (!options.full && existsSync3(cachePath)) {
+    const cached = readBrowserStateCache(cachePath);
+    if (cached?.url === snapshot.url && cached.documentId === snapshot.documentId) {
+      mode = "diff";
+      const diff = browserStateDiff(cached.entries, entries);
+      tree = diff.tree;
+      changes = { added: diff.added, changed: diff.changed, removed: diff.removed };
+    }
+  }
+  mkdirSync3(STATE_DIR, { recursive: true });
+  writeFileSync3(cachePath, JSON.stringify({ url: snapshot.url, documentId: snapshot.documentId, entries }));
+  const stableState = isRecord(stability.state) ? stability.state : {};
+  const state = {
+    title: snapshot.title,
+    url: snapshot.url,
+    documentId: snapshot.documentId,
+    revision: snapshot.revision,
+    viewport: snapshot.viewport,
+    text: snapshot.text,
+    tree,
+    nodeCount: snapshot.nodeCount,
+    elementCount: snapshot.elementCount,
+    truncated: snapshot.truncated,
+    mode,
+    changes
+  };
+  console.log(JSON.stringify({
+    targetId,
+    screenshot: {
+      path: target,
+      width: screenshot.width,
+      height: screenshot.height,
+      devicePixelRatio: typeof stableState.devicePixelRatio === "number" ? stableState.devicePixelRatio : 1
+    },
+    stability,
+    state
+  }, null, 2));
+}
 var DESKTOP_POINT_JS = `
     const desktopPoint = (rect) => {
       const borderX = Math.max(0, (window.outerWidth - window.innerWidth) / 2);
@@ -16148,17 +16810,95 @@ var DESKTOP_POINT_JS = `
         y: Math.round(window.screenY + topChrome + rect.y + rect.height / 2),
       };
     };`;
+function parseBrowserRef(value) {
+  const ref = parseCoord(value.replace(/^ref=/, ""), "--ref");
+  if (ref <= 0) fail("--ref must be a positive backend DOM node ID from the latest browser state");
+  return ref;
+}
+function readBrowserRefCache(page) {
+  const targetId = page.id;
+  if (!targetId) fail("Chrome target has no stable ID. Capture fresh browser state and retry.");
+  const cachePath = browserStateCachePath(targetId);
+  if (!existsSync3(cachePath)) fail(`No browser state is cached for target ${targetId}. Run replicas computer browser-state <path> --target-id ${targetId} first.`);
+  const cached = readBrowserStateCache(cachePath);
+  if (!cached) fail(`Browser state for target ${targetId} is invalid. Capture fresh browser state and retry.`);
+  if (cached.url !== (page.url ?? "").slice(0, 2e3)) fail("Cached browser state belongs to a different URL. Capture fresh browser state and retry.");
+  return { targetId, cached };
+}
+function browserViewportRect(layout) {
+  const viewport = chromeVisualViewport(layout);
+  return {
+    x: 0,
+    y: 0,
+    width: viewport.width,
+    height: viewport.height,
+    centerX: viewport.width / 2,
+    centerY: viewport.height / 2
+  };
+}
+async function prepareBrowserElement(page, refValue) {
+  const backendNodeId = parseBrowserRef(refValue);
+  const { cached } = readBrowserRefCache(page);
+  return await withChromeSession(page.webSocketDebuggerUrl, async (session) => {
+    const layout = await sendChromeSessionCommand(session, "Page.getLayoutMetrics", {});
+    const rect = await prepareBrowserRefInSession(session, backendNodeId, cached, browserViewportRect(layout));
+    const axNodes = (await sendChromeSessionCommand(session, "Accessibility.getPartialAXTree", {
+      backendNodeId,
+      fetchRelatives: false
+    })).nodes;
+    const rawNode = Array.isArray(axNodes) && isRawAXNode(axNodes[0]) ? axNodes[0] : null;
+    const states = rawNode ? browserStateProperties(rawNode) : {};
+    const role = clippedText(rawNode?.role?.value, 80);
+    const element = rawNode ? {
+      ref: String(backendNodeId),
+      role,
+      name: clippedText(rawNode.name?.value) || null,
+      description: clippedText(rawNode.description?.value) || null,
+      value: typeof rawNode.value?.value === "string" ? clippedText(rawNode.value.value) : typeof rawNode.value?.value === "number" || typeof rawNode.value?.value === "boolean" ? rawNode.value.value : null,
+      states,
+      actions: [
+        "click",
+        ...["textbox", "searchbox", "combobox", "spinbutton", "slider"].includes(role) || states.editable === true ? ["set_value"] : [],
+        "scroll"
+      ]
+    } : null;
+    const desktopPoint = await evaluateChromeSession(session, `(() => {
+${DESKTOP_POINT_JS}
+    return desktopPoint({ x: ${rect.centerX}, y: ${rect.centerY}, width: 0, height: 0 });
+  })()`);
+    return {
+      ref: String(backendNodeId),
+      rect,
+      element,
+      desktopPoint: typeof desktopPoint === "object" && desktopPoint !== null && "x" in desktopPoint && typeof desktopPoint.x === "number" && "y" in desktopPoint && typeof desktopPoint.y === "number" ? { x: desktopPoint.x, y: desktopPoint.y } : null
+    };
+  });
+}
+async function prepareBrowserRefInSession(session, backendNodeId, cached, viewportRect) {
+  if (!cached.entries.some(({ line }) => line.trimStart().startsWith(`[ref=${backendNodeId}]`))) {
+    fail(`Browser element ref ${backendNodeId} is not in the latest state. Capture fresh browser state and retry.`);
+  }
+  const frameTree = (await sendChromeSessionCommand(session, "Page.getFrameTree", {})).frameTree;
+  if (cached.documentId !== browserDocumentId(frameTree)) {
+    fail(`Browser element ref ${backendNodeId} belongs to a previous document. Capture fresh browser state and retry.`);
+  }
+  try {
+    await sendChromeSessionCommand(session, "DOM.scrollIntoViewIfNeeded", { backendNodeId });
+  } catch (error) {
+    fail(`Browser element ref ${backendNodeId} is stale or cannot be scrolled into view: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  const quads = (await sendChromeSessionCommand(session, "DOM.getContentQuads", { backendNodeId })).quads;
+  const candidates = browserContentQuadRects(quads, viewportRect);
+  if (!candidates[0]) fail(`Browser element ref ${backendNodeId} has no visible content quad. Fetch fresh browser state and retry.`);
+  return roundBrowserRect(candidates[0]);
+}
 function buildBrowserClickExpression(query, options) {
   return `(() => {
     const query = ${JSON.stringify(query)};
     const exact = ${JSON.stringify(options.exact)};
     const index = ${options.index};
     const normalize = (value) => String(value || '').replace(/\\s+/g, ' ').trim();
-    const visible = (el) => {
-      const rect = el.getBoundingClientRect();
-      const style = getComputedStyle(el);
-      return rect.width > 0 && rect.height > 0 && style.visibility !== 'hidden' && style.display !== 'none';
-    };
+${VISIBLE_JS}
     const label = (el) => normalize(el.innerText || el.value || el.getAttribute('aria-label') || el.getAttribute('title') || el.getAttribute('placeholder') || el.href || el.id || el.name || el.tagName);
 ${DESKTOP_POINT_JS}
     const matches = (text) => {
@@ -16183,8 +16923,7 @@ ${DESKTOP_POINT_JS}
     const { el, text } = candidate;
     el.scrollIntoView({ block: 'center', inline: 'center' });
     const rect = el.getBoundingClientRect();
-    if (typeof el.focus === 'function') el.focus();
-    el.click();
+    if (typeof el.focus === 'function') el.focus({ preventScroll: true });
     return {
       clicked: true,
       query,
@@ -16207,6 +16946,15 @@ ${DESKTOP_POINT_JS}
     };
   })()`;
 }
+function browserActionRectCenter(result) {
+  if (typeof result !== "object" || result === null || !("rect" in result)) return null;
+  const rect = result.rect;
+  if (typeof rect !== "object" || rect === null) return null;
+  const x = "centerX" in rect ? rect.centerX : void 0;
+  const y = "centerY" in rect ? rect.centerY : void 0;
+  if (typeof x !== "number" || typeof y !== "number" || !Number.isFinite(x) || !Number.isFinite(y)) return null;
+  return { x, y };
+}
 function browserActionPoint(result) {
   if (typeof result !== "object" || result === null) return null;
   const action = "result" in result ? result.result : result;
@@ -16222,19 +16970,149 @@ function browserActionPoint(result) {
     y: clamp(Math.round(y), 0, dimensions.height)
   };
 }
+async function dispatchChromeClick(page, x, y, button, clicks) {
+  await withChromeSession(page.webSocketDebuggerUrl, async (session) => {
+    await dispatchChromeClickInSession(session, x, y, button, clicks);
+  });
+}
+async function dispatchChromeClickInSession(session, x, y, button, clicks) {
+  for (let clickCount = 1; clickCount <= clicks; clickCount++) {
+    await sendChromeSessionCommand(session, "Input.dispatchMouseEvent", {
+      type: "mousePressed",
+      x,
+      y,
+      button,
+      clickCount
+    });
+    await sendChromeSessionCommand(session, "Input.dispatchMouseEvent", {
+      type: "mouseReleased",
+      x,
+      y,
+      button,
+      clickCount
+    });
+  }
+}
+async function replaceChromeText(page, text) {
+  await withChromeSession(page.webSocketDebuggerUrl, async (session) => {
+    await replaceChromeTextInSession(session, text);
+  });
+}
+async function replaceChromeTextInSession(session, text) {
+  await sendChromeSessionCommand(session, "Input.dispatchKeyEvent", {
+    type: "rawKeyDown",
+    key: "a",
+    code: "KeyA",
+    windowsVirtualKeyCode: 65,
+    nativeVirtualKeyCode: 65,
+    modifiers: 2
+  });
+  await sendChromeSessionCommand(session, "Input.dispatchKeyEvent", {
+    type: "keyUp",
+    key: "a",
+    code: "KeyA",
+    windowsVirtualKeyCode: 65,
+    nativeVirtualKeyCode: 65,
+    modifiers: 2
+  });
+  await sendChromeSessionCommand(session, "Input.insertText", { text });
+}
+var BROWSER_DIRECT_VALUE_INPUT_TYPES = /* @__PURE__ */ new Set(["number", "range", "date", "datetime-local", "month", "week", "time", "color"]);
+function browserFillInvalid(actual, expected, fieldType, semanticSelection = false, selectionMatched = false) {
+  if (semanticSelection) return !selectionMatched;
+  if (["number", "range"].includes(fieldType)) {
+    const actualNumber = typeof actual === "number" ? actual : Number(actual);
+    const expectedNumber = Number(expected);
+    return !Number.isFinite(actualNumber) || !Number.isFinite(expectedNumber) || actualNumber !== expectedNumber;
+  }
+  if (fieldType === "color") return String(actual).toLowerCase() !== expected.toLowerCase();
+  return actual !== expected;
+}
+async function fillChromeNodeInSession(session, backendNodeId, value) {
+  await sendChromeSessionCommand(session, "DOM.focus", { backendNodeId });
+  const directResult = await callFunctionOnChromeNodeInSession(
+    session,
+    backendNodeId,
+    `function(value) {
+      const emit = () => {
+        this.dispatchEvent(new Event('input', { bubbles: true }));
+        this.dispatchEvent(new Event('change', { bubbles: true }));
+      };
+      if (this instanceof HTMLSelectElement) {
+        const option = Array.from(this.options).find((item) => item.value === value || item.text.trim() === value);
+        if (option) this.value = option.value;
+        else this.value = value;
+        emit();
+        return { handled: true, semanticSelection: true, matched: !!option, value: this.value };
+      }
+      if (this instanceof HTMLInputElement && ${JSON.stringify([...BROWSER_DIRECT_VALUE_INPUT_TYPES])}.includes(this.type.toLowerCase())) {
+        const setter = Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, 'value')?.set;
+        if (!setter) return { handled: false };
+        setter.call(this, value);
+        emit();
+        return { handled: true, semanticSelection: false, matched: true, value: this.value };
+      }
+      return { handled: false };
+    }`,
+    [value]
+  );
+  const directValue = chromeCallValue(directResult);
+  const directHandled = isRecord(directValue) && directValue.handled === true;
+  if (!directHandled) await replaceChromeTextInSession(session, value);
+  const verification = await callFunctionOnChromeNodeInSession(
+    session,
+    backendNodeId,
+    `function() {
+      const value = this instanceof HTMLSelectElement || 'value' in this ? this.value : this.textContent;
+      const type = this instanceof HTMLSelectElement
+        ? 'select'
+        : this instanceof HTMLInputElement
+          ? this.type.toLowerCase()
+          : this.isContentEditable
+            ? 'contenteditable'
+            : 'text';
+      return { value, valueLength: String(value ?? '').length, type };
+    }`
+  );
+  const actual = chromeCallValue(verification);
+  if (!isRecord(actual)) fail(`Chrome did not return a value for browser element ref ${backendNodeId}.`);
+  const fieldType = typeof actual.type === "string" ? actual.type : "";
+  const semanticSelection = isRecord(directValue) && directValue.semanticSelection === true;
+  const selectionMatched = isRecord(directValue) && directValue.matched === true;
+  if (browserFillInvalid(actual.value, value, fieldType, semanticSelection, selectionMatched)) {
+    fail(`Chrome reported that ref ${backendNodeId} contains ${JSON.stringify(actual.value)} after filling, expected ${JSON.stringify(value)}.`);
+  }
+  return { value: actual.value, valueLength: actual.valueLength, type: fieldType };
+}
 async function computerBrowserClickCommand(query, options = {}) {
   const page = await selectChromePage(options);
+  if (options.ref) {
+    const target = await prepareBrowserElement(page, options.ref);
+    const buttonNames = { "1": "left", "2": "middle", "3": "right", left: "left", middle: "middle", right: "right" };
+    const button = buttonNames[(options.button ?? "left").toLowerCase()];
+    if (!button) fail("--button must be one of left|middle|right|1|2|3");
+    const clicks = options.double ? 2 : 1;
+    await dispatchChromeClick(page, target.rect.centerX, target.rect.centerY, button, clicks);
+    if (target.desktopPoint) logRecordingAction({ type: "click", ...target.desktopPoint });
+    console.log(JSON.stringify({
+      ...browserTargetOutput(page),
+      result: { clicked: true, ref: target.ref, button, clickCount: clicks, rect: target.rect, element: target.element }
+    }, null, 2));
+    return;
+  }
+  if (!query) fail("Provide control text or --ref <id> from the latest browser state");
   const index = options.index ? parseCoord(options.index, "--index") : 0;
   if (index < 0) fail("--index must be >= 0");
   const result = await evaluateChromeTarget(
     page.webSocketDebuggerUrl,
     buildBrowserClickExpression(query, { exact: !!options.exact, index })
   );
+  const center = browserActionRectCenter(result);
+  if (center) await dispatchChromeClick(page, center.x, center.y, "left", 1);
   const point = browserActionPoint(result);
   if (point) logRecordingAction({ type: "click", ...point });
   console.log(JSON.stringify({
-    title: page.title ?? "",
-    url: page.url ?? "",
+    ...browserTargetOutput(page),
     result
   }, null, 2));
 }
@@ -16246,11 +17124,7 @@ function buildBrowserFillExpression(query, value, options) {
     const index = ${options.index};
     const normalize = (text) => String(text || '').replace(/\\s+/g, ' ').trim();
     const escape = (text) => globalThis.CSS && CSS.escape ? CSS.escape(text) : String(text).replace(/["\\\\]/g, '\\\\$&');
-    const visible = (el) => {
-      const rect = el.getBoundingClientRect();
-      const style = getComputedStyle(el);
-      return rect.width > 0 && rect.height > 0 && style.visibility !== 'hidden' && style.display !== 'none';
-    };
+${VISIBLE_JS}
     const matches = (text) => {
       const haystack = text.toLowerCase();
       const needle = query.toLowerCase();
@@ -16295,18 +17169,42 @@ ${DESKTOP_POINT_JS}
     }
     const { el, text } = candidate;
     el.scrollIntoView({ block: 'center', inline: 'center' });
-    if (typeof el.focus === 'function') el.focus();
+    if (typeof el.focus === 'function') el.focus({ preventScroll: true });
+    const fieldType = el.tagName.toLowerCase() === 'select' ? 'select' : String(el.getAttribute('type') || 'text').toLowerCase();
+    let nativeInputRequired = false;
+    let semanticSelection = false;
+    let selectionMatched = false;
     if (el.tagName.toLowerCase() === 'select') {
       const option = Array.from(el.options).find((item) => item.value === value || normalize(item.text) === value);
       if (option) el.value = option.value;
       else el.value = value;
+      semanticSelection = true;
+      selectionMatched = !!option;
+      el.dispatchEvent(new Event('input', { bubbles: true }));
+      el.dispatchEvent(new Event('change', { bubbles: true }));
+    } else if (el instanceof HTMLInputElement && ${JSON.stringify([...BROWSER_DIRECT_VALUE_INPUT_TYPES])}.includes(fieldType)) {
+      const setter = Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, 'value')?.set;
+      if (setter) {
+        setter.call(el, value);
+        el.dispatchEvent(new Event('input', { bubbles: true }));
+        el.dispatchEvent(new Event('change', { bubbles: true }));
+      } else {
+        nativeInputRequired = true;
+      }
     } else if (el.isContentEditable) {
-      el.textContent = value;
+      const selection = getSelection();
+      const range = document.createRange();
+      range.selectNodeContents(el);
+      selection.removeAllRanges();
+      selection.addRange(range);
+      nativeInputRequired = true;
+    } else if (typeof el.select === 'function') {
+      el.select();
+      nativeInputRequired = true;
     } else {
-      el.value = value;
+      el.setSelectionRange(0, String(el.value || '').length);
+      nativeInputRequired = true;
     }
-    el.dispatchEvent(new InputEvent('input', { bubbles: true, inputType: 'insertText', data: value }));
-    el.dispatchEvent(new Event('change', { bubbles: true }));
     const rect = el.getBoundingClientRect();
     return {
       filled: true,
@@ -16315,9 +17213,13 @@ ${DESKTOP_POINT_JS}
       index,
       tag: el.tagName.toLowerCase(),
       role: el.getAttribute('role') || null,
-      type: el.getAttribute('type') || null,
+      type: fieldType,
       text,
-      value: el.isContentEditable ? el.textContent : el.value,
+      actualValue: el.isContentEditable ? el.textContent : 'value' in el ? el.value : null,
+      valueLength: String(el.isContentEditable ? el.textContent : 'value' in el ? el.value : '').length,
+      nativeInputRequired,
+      semanticSelection,
+      selectionMatched,
       desktopPoint: desktopPoint(rect),
       rect: {
         x: Math.round(rect.x),
@@ -16332,6 +17234,18 @@ ${DESKTOP_POINT_JS}
 }
 async function computerBrowserFillCommand(query, value, options = {}) {
   const page = await selectChromePage(options);
+  if (options.ref) {
+    const target = await prepareBrowserElement(page, options.ref);
+    const backendNodeId = parseBrowserRef(options.ref);
+    const actual = await withChromeSession(page.webSocketDebuggerUrl, async (session) => await fillChromeNodeInSession(session, backendNodeId, value));
+    if (target.desktopPoint) logRecordingAction({ type: "type", ...target.desktopPoint });
+    console.log(JSON.stringify({
+      ...browserTargetOutput(page),
+      result: { filled: true, ref: target.ref, valueLength: actual.valueLength, rect: target.rect, element: target.element }
+    }, null, 2));
+    return;
+  }
+  if (!query) fail("Provide field text or --ref <id> from the latest browser state");
   const index = options.index ? parseCoord(options.index, "--index") : 0;
   if (index < 0) fail("--index must be >= 0");
   const result = await evaluateChromeTarget(
@@ -16339,10 +17253,28 @@ async function computerBrowserFillCommand(query, value, options = {}) {
     buildBrowserFillExpression(query, value, { exact: !!options.exact, index })
   );
   const point = browserActionPoint(result);
+  if (typeof result === "object" && result !== null && "nativeInputRequired" in result && result.nativeInputRequired === true) {
+    await replaceChromeText(page, value);
+    const actualValue = await evaluateChromeTarget(page.webSocketDebuggerUrl, `(() => {
+      const el = document.activeElement;
+      return el && el.isContentEditable ? el.textContent : el && 'value' in el ? el.value : null;
+    })()`);
+    const fieldType = "type" in result && typeof result.type === "string" ? result.type.toLowerCase() : "";
+    if (browserFillInvalid(actualValue, value, fieldType)) {
+      fail(`Chrome reported that ${JSON.stringify(query)} contains ${JSON.stringify(actualValue)} after filling, expected ${JSON.stringify(value)}.`);
+    }
+    if (isRecord(result)) {
+      Object.assign(result, { actualValue, valueLength: String(actualValue ?? "").length });
+    }
+  } else if (isRecord(result) && result.filled === true) {
+    const fieldType = typeof result.type === "string" ? result.type : "";
+    if (browserFillInvalid(result.actualValue, value, fieldType, result.semanticSelection === true, result.selectionMatched === true)) {
+      fail(`Chrome reported that ${JSON.stringify(query)} contains ${JSON.stringify(result.actualValue)} after filling, expected ${JSON.stringify(value)}.`);
+    }
+  }
   if (point) logRecordingAction({ type: "type", ...point });
   console.log(JSON.stringify({
-    title: page.title ?? "",
-    url: page.url ?? "",
+    ...browserTargetOutput(page),
     result
   }, null, 2));
 }
@@ -16352,11 +17284,7 @@ function buildBrowserWaitExpression(query, options) {
     const mode = ${JSON.stringify(options.mode)};
     const exact = ${JSON.stringify(options.exact)};
     const normalize = (text) => String(text || '').replace(/\\s+/g, ' ').trim();
-    const visible = (el) => {
-      const rect = el.getBoundingClientRect();
-      const style = getComputedStyle(el);
-      return rect.width > 0 && rect.height > 0 && style.visibility !== 'hidden' && style.display !== 'none';
-    };
+${VISIBLE_JS}
     const matches = (text) => {
       const haystack = normalize(text).toLowerCase();
       const needle = query.toLowerCase();
@@ -16411,6 +17339,241 @@ async function computerBrowserWaitCommand(query, options = {}) {
   console.log(JSON.stringify({ ok: false, elapsedMs: Date.now() - start, attempts, result: lastResult }, null, 2));
   process.exitCode = 1;
 }
+async function computerBrowserScrollCommand(direction, options = {}) {
+  const page = await selectChromePage(options);
+  const normalized = direction.toLowerCase();
+  if (!["up", "down", "left", "right"].includes(normalized)) fail("direction must be one of up|down|left|right");
+  const amount = options.amount ? parseCoord(options.amount, "--amount") : 600;
+  if (amount <= 0 || amount > 1e4) fail("--amount must be between 1 and 10000 CSS pixels");
+  const layout = await sendChromeCommand(page.webSocketDebuggerUrl, "Page.getLayoutMetrics", {});
+  const viewport = chromeVisualViewport(layout);
+  const target = options.ref ? await prepareBrowserElement(page, options.ref) : null;
+  const x = target?.rect.centerX ?? viewport.width / 2;
+  const y = target?.rect.centerY ?? viewport.height / 2;
+  const deltaX = normalized === "left" ? -amount : normalized === "right" ? amount : 0;
+  const deltaY = normalized === "up" ? -amount : normalized === "down" ? amount : 0;
+  await sendChromeCommand(page.webSocketDebuggerUrl, "Input.dispatchMouseEvent", {
+    type: "mouseWheel",
+    x,
+    y,
+    deltaX,
+    deltaY
+  });
+  logRecordingAction({ type: "scroll", ...target?.desktopPoint ?? {} });
+  console.log(JSON.stringify({
+    ...browserTargetOutput(page),
+    result: { scrolled: true, direction: normalized, amount, ref: target?.ref ?? null, x: Math.round(x), y: Math.round(y) }
+  }, null, 2));
+}
+function browserKeyDetails(combo) {
+  const tokens = combo.split("+").map((token) => token.trim()).filter(Boolean);
+  if (tokens.length === 0) fail("key combination cannot be empty");
+  let modifiers = 0;
+  for (const token of tokens.slice(0, -1)) {
+    const normalized2 = token.toLowerCase();
+    if (["alt", "option"].includes(normalized2)) modifiers |= 1;
+    else if (["ctrl", "control"].includes(normalized2)) modifiers |= 2;
+    else if (["meta", "cmd", "command", "super"].includes(normalized2)) modifiers |= 4;
+    else if (normalized2 === "shift") modifiers |= 8;
+    else fail(`Unsupported browser key modifier ${JSON.stringify(token)}`);
+  }
+  const requested = tokens[tokens.length - 1];
+  const aliases = {
+    enter: { key: "Enter", code: "Enter", windowsVirtualKeyCode: 13 },
+    return: { key: "Enter", code: "Enter", windowsVirtualKeyCode: 13 },
+    tab: { key: "Tab", code: "Tab", windowsVirtualKeyCode: 9 },
+    escape: { key: "Escape", code: "Escape", windowsVirtualKeyCode: 27 },
+    esc: { key: "Escape", code: "Escape", windowsVirtualKeyCode: 27 },
+    backspace: { key: "Backspace", code: "Backspace", windowsVirtualKeyCode: 8 },
+    delete: { key: "Delete", code: "Delete", windowsVirtualKeyCode: 46 },
+    space: { key: " ", code: "Space", windowsVirtualKeyCode: 32 },
+    up: { key: "ArrowUp", code: "ArrowUp", windowsVirtualKeyCode: 38 },
+    arrowup: { key: "ArrowUp", code: "ArrowUp", windowsVirtualKeyCode: 38 },
+    down: { key: "ArrowDown", code: "ArrowDown", windowsVirtualKeyCode: 40 },
+    arrowdown: { key: "ArrowDown", code: "ArrowDown", windowsVirtualKeyCode: 40 },
+    left: { key: "ArrowLeft", code: "ArrowLeft", windowsVirtualKeyCode: 37 },
+    arrowleft: { key: "ArrowLeft", code: "ArrowLeft", windowsVirtualKeyCode: 37 },
+    right: { key: "ArrowRight", code: "ArrowRight", windowsVirtualKeyCode: 39 },
+    arrowright: { key: "ArrowRight", code: "ArrowRight", windowsVirtualKeyCode: 39 },
+    home: { key: "Home", code: "Home", windowsVirtualKeyCode: 36 },
+    end: { key: "End", code: "End", windowsVirtualKeyCode: 35 },
+    pageup: { key: "PageUp", code: "PageUp", windowsVirtualKeyCode: 33 },
+    pagedown: { key: "PageDown", code: "PageDown", windowsVirtualKeyCode: 34 }
+  };
+  const normalized = requested.toLowerCase();
+  const alias = aliases[normalized];
+  if (alias) return { ...alias, modifiers, ...alias.key === " " && modifiers === 0 ? { text: " " } : {} };
+  if (/^[a-z]$/i.test(requested)) {
+    const upper = requested.toUpperCase();
+    const key = modifiers & 8 ? upper : requested.toLowerCase();
+    return { key, code: `Key${upper}`, windowsVirtualKeyCode: upper.charCodeAt(0), modifiers, ...modifiers === 0 ? { text: key } : {} };
+  }
+  if (/^[0-9]$/.test(requested)) {
+    return { key: requested, code: `Digit${requested}`, windowsVirtualKeyCode: requested.charCodeAt(0), modifiers, ...modifiers === 0 ? { text: requested } : {} };
+  }
+  fail(`Unsupported browser key ${JSON.stringify(requested)}`);
+}
+async function computerBrowserKeyCommand(combo, options = {}) {
+  const page = await selectChromePage(options);
+  const key = browserKeyDetails(combo);
+  await withChromeSession(page.webSocketDebuggerUrl, async (session) => {
+    await dispatchChromeKeyInSession(session, key);
+  });
+  logRecordingAction({ type: "key" });
+  console.log(JSON.stringify({ targetId: page.id ?? null, result: { pressed: combo } }, null, 2));
+}
+async function dispatchChromeKeyInSession(session, key) {
+  await sendChromeSessionCommand(session, "Input.dispatchKeyEvent", {
+    type: "keyDown",
+    ...key,
+    nativeVirtualKeyCode: key.windowsVirtualKeyCode
+  });
+  await sendChromeSessionCommand(session, "Input.dispatchKeyEvent", {
+    type: "keyUp",
+    key: key.key,
+    code: key.code,
+    modifiers: key.modifiers,
+    windowsVirtualKeyCode: key.windowsVirtualKeyCode,
+    nativeVirtualKeyCode: key.windowsVirtualKeyCode
+  });
+}
+async function computerBrowserTypeCommand(text, options = {}) {
+  const page = await selectChromePage(options);
+  await sendChromeCommand(page.webSocketDebuggerUrl, "Input.insertText", { text });
+  logRecordingAction({ type: "type" });
+  console.log(JSON.stringify({ targetId: page.id ?? null, result: { typed: true, length: text.length } }, null, 2));
+}
+function parseBrowserBatchActions(value) {
+  let input;
+  try {
+    input = JSON.parse(value);
+  } catch (error) {
+    fail(`Batch actions must be valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  if (!Array.isArray(input) || input.length === 0 || input.length > 100) {
+    fail("Batch actions must be a JSON array containing 1 to 100 actions");
+  }
+  return input.map((item, index) => {
+    if (!isRecord(item) || typeof item.action !== "string") fail(`Batch action ${index} must be an object with an action`);
+    if (item.action === "click") {
+      if (typeof item.ref !== "string" && typeof item.ref !== "number") fail(`Batch click ${index} requires ref`);
+      const buttons = { "1": "left", "2": "middle", "3": "right", left: "left", middle: "middle", right: "right" };
+      const requestedButton = item.button === void 0 ? "left" : String(item.button).toLowerCase();
+      const button = buttons[requestedButton];
+      if (!button) fail(`Batch click ${index} button must be left, middle, or right`);
+      return { action: "click", ref: String(item.ref), button, clicks: item.double === true ? 2 : 1 };
+    }
+    if (item.action === "fill") {
+      if (typeof item.ref !== "string" && typeof item.ref !== "number" || typeof item.value !== "string") {
+        fail(`Batch fill ${index} requires ref and string value`);
+      }
+      return { action: "fill", ref: String(item.ref), value: item.value };
+    }
+    if (item.action === "key") {
+      if (typeof item.combo !== "string") fail(`Batch key ${index} requires combo`);
+      return { action: "key", combo: item.combo };
+    }
+    if (item.action === "type") {
+      if (typeof item.text !== "string") fail(`Batch type ${index} requires text`);
+      return { action: "type", text: item.text };
+    }
+    if (item.action === "scroll") {
+      const directions = { up: "up", down: "down", left: "left", right: "right" };
+      const direction = typeof item.direction === "string" ? directions[item.direction] : void 0;
+      if (!direction) {
+        fail(`Batch scroll ${index} direction must be up, down, left, or right`);
+      }
+      const amount = item.amount === void 0 ? 600 : Number(item.amount);
+      if (!Number.isFinite(amount) || amount <= 0 || amount > 1e4) fail(`Batch scroll ${index} amount must be between 1 and 10000`);
+      if (item.ref !== void 0 && typeof item.ref !== "string" && typeof item.ref !== "number") fail(`Batch scroll ${index} ref is invalid`);
+      return {
+        action: "scroll",
+        direction,
+        amount,
+        ...item.ref === void 0 ? {} : { ref: String(item.ref) }
+      };
+    }
+    if (item.action === "wait") {
+      if (typeof item.text !== "string") fail(`Batch wait ${index} requires text`);
+      const mode = item.mode === void 0 ? "any" : String(item.mode);
+      if (!["any", "text", "title", "url", "control"].includes(mode)) fail(`Batch wait ${index} mode is invalid`);
+      const timeoutMs = item.timeoutMs === void 0 ? 1e4 : Number(item.timeoutMs);
+      const pollMs = item.pollMs === void 0 ? 250 : Number(item.pollMs);
+      if (!Number.isFinite(timeoutMs) || timeoutMs < 0) fail(`Batch wait ${index} timeoutMs must be >= 0`);
+      if (!Number.isFinite(pollMs) || pollMs < 50 || pollMs > 2e3) fail(`Batch wait ${index} pollMs must be between 50 and 2000`);
+      return { action: "wait", text: item.text, mode, exact: item.exact === true, timeoutMs, pollMs };
+    }
+    fail(`Batch action ${index} has unsupported action ${JSON.stringify(item.action)}`);
+  });
+}
+async function computerBrowserBatchCommand(actionsJson, options = {}) {
+  const actions = parseBrowserBatchActions(actionsJson);
+  const page = await selectChromePage(options);
+  const { targetId, cached } = readBrowserRefCache(page);
+  const startedAt = Date.now();
+  const completed = [];
+  try {
+    await withChromeSession(page.webSocketDebuggerUrl, async (session) => {
+      const layout = await sendChromeSessionCommand(session, "Page.getLayoutMetrics", {});
+      const viewportRect = browserViewportRect(layout);
+      for (const [index, action] of actions.entries()) {
+        const actionStartedAt = Date.now();
+        if (action.action === "click") {
+          const ref = parseBrowserRef(action.ref);
+          const rect = await prepareBrowserRefInSession(session, ref, cached, viewportRect);
+          await dispatchChromeClickInSession(session, rect.centerX, rect.centerY, action.button, action.clicks);
+          logRecordingAction({ type: "click" });
+          completed.push({ index, action: action.action, ref: String(ref), elapsedMs: Date.now() - actionStartedAt });
+        } else if (action.action === "fill") {
+          const ref = parseBrowserRef(action.ref);
+          await prepareBrowserRefInSession(session, ref, cached, viewportRect);
+          const result = await fillChromeNodeInSession(session, ref, action.value);
+          logRecordingAction({ type: "type" });
+          completed.push({ index, action: action.action, ref: String(ref), valueLength: result.valueLength, elapsedMs: Date.now() - actionStartedAt });
+        } else if (action.action === "key") {
+          await dispatchChromeKeyInSession(session, browserKeyDetails(action.combo));
+          logRecordingAction({ type: "key" });
+          completed.push({ index, action: action.action, elapsedMs: Date.now() - actionStartedAt });
+        } else if (action.action === "type") {
+          await sendChromeSessionCommand(session, "Input.insertText", { text: action.text });
+          logRecordingAction({ type: "type" });
+          completed.push({ index, action: action.action, length: action.text.length, elapsedMs: Date.now() - actionStartedAt });
+        } else if (action.action === "scroll") {
+          const ref = action.ref ? parseBrowserRef(action.ref) : null;
+          const rect = ref ? await prepareBrowserRefInSession(session, ref, cached, viewportRect) : viewportRect;
+          const deltaX = action.direction === "left" ? -action.amount : action.direction === "right" ? action.amount : 0;
+          const deltaY = action.direction === "up" ? -action.amount : action.direction === "down" ? action.amount : 0;
+          await sendChromeSessionCommand(session, "Input.dispatchMouseEvent", {
+            type: "mouseWheel",
+            x: rect.centerX,
+            y: rect.centerY,
+            deltaX,
+            deltaY
+          });
+          logRecordingAction({ type: "scroll" });
+          completed.push({ index, action: action.action, direction: action.direction, amount: action.amount, elapsedMs: Date.now() - actionStartedAt });
+        } else {
+          const expression = buildBrowserWaitExpression(action.text, { mode: action.mode, exact: action.exact });
+          let attempts = 0;
+          let result = null;
+          while (Date.now() - actionStartedAt <= action.timeoutMs) {
+            attempts++;
+            result = await evaluateChromeSession(session, expression);
+            if (isRecord(result) && result.matched === true) break;
+            await sleep(action.pollMs);
+          }
+          if (!isRecord(result) || result.matched !== true) fail(`Batch wait ${index} timed out after ${Date.now() - actionStartedAt}ms`);
+          completed.push({ index, action: action.action, attempts, elapsedMs: Date.now() - actionStartedAt });
+        }
+      }
+    });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.log(JSON.stringify({ ok: false, targetId, elapsedMs: Date.now() - startedAt, completed, failedIndex: completed.length, error: message }, null, 2));
+    throw error;
+  }
+  console.log(JSON.stringify({ ok: true, targetId, elapsedMs: Date.now() - startedAt, completed }, null, 2));
+}
 async function computerClickCommand(xStr, yStr, options) {
   const dimensions = getDisplayDimensions();
   const x = parseScreenCoord(xStr, "x", dimensions.width);
@@ -16533,12 +17696,55 @@ async function computerLaunchCommand(app, args) {
   const baseArgs = app === "chrome" && !existsSync3(CHROME_WRAPPER) ? LEGACY_CHROME_ALIAS : APP_ALIASES[app] ?? [app];
   const bin = baseArgs[0];
   const fullArgs = [...baseArgs.slice(1), ...args];
+  const expectsNewChromePage = args.some((arg) => !arg.startsWith("-"));
+  const existingChromePageIds = /* @__PURE__ */ new Set();
+  if (app === "chrome") {
+    try {
+      for (const page of await getChromePages()) {
+        if (page.id) existingChromePageIds.add(page.id);
+      }
+    } catch {
+    }
+  }
   const child = spawn4(bin, fullArgs, {
     env: withDisplay(),
     detached: true,
     stdio: "ignore"
   });
   child.unref();
+  if (app === "chrome") {
+    const startedAt = Date.now();
+    let pageCount = 0;
+    let readyPage = null;
+    while (Date.now() - startedAt < 15e3) {
+      let pages = [];
+      try {
+        pages = await getChromePages();
+      } catch {
+      }
+      pageCount = pages.length;
+      const candidates = expectsNewChromePage && existingChromePageIds.size > 0 ? pages.filter((page) => page.id && !existingChromePageIds.has(page.id)) : pages;
+      for (const page of candidates) {
+        if (!page.webSocketDebuggerUrl || !page.url || page.url === "about:blank") continue;
+        const readyState = await evaluateChromeTarget(page.webSocketDebuggerUrl, "document.readyState");
+        if (readyState === "interactive" || readyState === "complete") {
+          readyPage = page;
+          break;
+        }
+      }
+      if (readyPage) break;
+      try {
+        if (child.pid) process.kill(child.pid, 0);
+      } catch {
+        fail(`Chrome exited before its desktop control channel became ready.`);
+      }
+      await sleep(100);
+    }
+    if (!readyPage?.webSocketDebuggerUrl) fail(`Chrome launched but its requested page was not controllable after 15 seconds.`);
+    await sendChromeCommand(readyPage.webSocketDebuggerUrl, "Page.bringToFront", {});
+    console.log(`launched ${bin} (pid ${child.pid}, ready in ${Date.now() - startedAt}ms, page ${readyPage.id}, ${pageCount} open)`);
+    return;
+  }
   console.log(`launched ${bin} (pid ${child.pid})`);
 }
 
@@ -20965,10 +22171,20 @@ if (isAgentMode()) {
   computer.command("status").description("Show which desktop services are running and the active preview URL").action(wrap(() => computerStatusCommand()));
   computer.command("screenshot <path>").description("Capture the current desktop to a PNG file. Use --raw or --grid for agent click planning; omit both for a branded shareable image.").option("--raw", "Save a 1:1 desktop capture with no branding, padding, or rounded corners").option("--grid [px]", "Overlay a coordinate grid on a 1:1 desktop capture. Default 100px.").action(wrap((path6, options) => computerScreenshotCommand(path6, options)));
   computer.command("observe <path>").description("Wait briefly for the desktop to settle, save a 1:1 screenshot, and print JSON screen context for agents.").option("--raw", "Save a 1:1 desktop capture with no coordinate grid").option("--grid [px]", "Overlay a coordinate grid on the 1:1 desktop capture. Default 100px.").option("--timeout <ms>", "Maximum time to wait for visual stability. Default 3000.").option("--stable-ms <ms>", "Required unchanged time before the screen is considered stable. Default 600.").option("--poll-ms <ms>", "Screenshot polling interval while waiting. Default 200.").action(wrap((path6, options) => computerObserveCommand(path6, options)));
-  computer.command("browser").description("Print JSON for Chrome tabs launched through Replicas, including page titles and URLs.").option("--snapshot", "Include visible page text and interactive controls with bounding boxes").option("--limit <chars>", "Maximum body text characters per page snapshot. Default 4000.").option("--element-limit <n>", "Maximum controls per page snapshot. Default 80.").action(wrap((options) => computerBrowserCommand(options)));
-  computer.command("browser-click <text>").description("Click the first visible Chrome control whose text, label, placeholder, or href matches <text>.").option("--exact", "Require an exact text match instead of substring matching").option("--index <n>", "When multiple controls match, click the nth match. Default 0.").option("--id <id>", "Only target the Chrome page with this target id").option("--page <n>", "When multiple pages match, target the nth page. Default 0.").option("--title <text>", "Only target pages whose title contains text").option("--url <text>", "Only target pages whose URL contains text").action(wrap((text, options) => computerBrowserClickCommand(text, options)));
-  computer.command("browser-fill <field> <value>").description("Fill the first visible Chrome field whose label, placeholder, name, or text matches <field>.").option("--exact", "Require an exact field match instead of substring matching").option("--index <n>", "When multiple fields match, fill the nth match. Default 0.").option("--id <id>", "Only target the Chrome page with this target id").option("--page <n>", "When multiple pages match, target the nth page. Default 0.").option("--title <text>", "Only target pages whose title contains text").option("--url <text>", "Only target pages whose URL contains text").action(wrap((field, value, options) => computerBrowserFillCommand(field, value, options)));
-  computer.command("browser-wait <text>").description("Wait until Chrome page title, URL, body text, or controls match <text>.").option("--mode <mode>", "Where to match: any, text, title, url, or control. Default any.").option("--exact", "Require an exact match instead of substring matching").option("--timeout <ms>", "Maximum time to wait. Default 10000.").option("--poll-ms <ms>", "Polling interval. Default 250.").option("--id <id>", "Only target the Chrome page with this target id").option("--page <n>", "When multiple pages match, target the nth page. Default 0.").option("--title <text>", "Only target pages whose title contains text").option("--url <text>", "Only target pages whose URL contains text").action(wrap((text, options) => computerBrowserWaitCommand(text, options)));
+  computer.command("browser").description("Print JSON for Chrome tabs launched through Replicas, including page titles and URLs.").option("--snapshot", "Include visible page text and interactive controls with bounding boxes").option("--limit <chars>", "Maximum body text characters per page snapshot. Default 4000.").option("--element-limit <n>", "Maximum controls per page snapshot. Default 80.").option("--target-id <id>", "Only include the Chrome page with this target id").option("--page <n>", "When multiple pages match, include the nth page. Default 0.").option("--title <text>", "Only include pages whose title contains text").option("--url <text>", "Only include pages whose URL contains text").action(wrap((options) => computerBrowserCommand(options)));
+  computer.command("browser-state <path>").description("Wait for a Chrome page to settle, capture its viewport, and print a bounded accessibility state with actionable refs.").option("--full", "Return the full accessibility tree instead of a diff from the previous state").option("--limit <chars>", "Maximum visible text characters. Default 8000.").option("--element-limit <n>", "Maximum actionable elements. Default 120.").option("--timeout <ms>", "Maximum time to wait for state stability. Default 5000.").option("--stable-ms <ms>", "Required unchanged time before capture. Default 500.").option("--poll-ms <ms>", "State polling interval. Default 100.").option("--target-id <id>", "Target the Chrome page with this stable target id").option("--page <n>", "When multiple pages match, target the nth page. Default 0.").option("--title <text>", "Only target pages whose title contains text").option("--url <text>", "Only target pages whose URL contains text").action(wrap((path6, options) => computerBrowserStateCommand(path6, options)));
+  computer.command("browser-batch <actions>").description("Run an ordered, fail-fast JSON array of browser actions through one Chrome session.").option("--target-id <id>", "Target the Chrome page with this stable target id").option("--page <n>", "When multiple pages match, target the nth page. Default 0.").option("--title <text>", "Only target pages whose title contains text").option("--url <text>", "Only target pages whose URL contains text").action(wrap((actions, options) => computerBrowserBatchCommand(actions, options)));
+  computer.command("browser-click [text]").description("Click a Chrome element by ref from browser-state, or fall back to visible control text.").option("--ref <id>", "Click the backend DOM node ref from the latest browser state").option("--exact", "Require an exact text match instead of substring matching").option("--index <n>", "When multiple controls match, click the nth match. Default 0.").option("--button <button>", "Mouse button for ref clicks: left, middle, or right. Default left.").option("--double", "Double-click a ref target").option("--target-id <id>", "Only target the Chrome page with this target id").option("--page <n>", "When multiple pages match, target the nth page. Default 0.").option("--title <text>", "Only target pages whose title contains text").option("--url <text>", "Only target pages whose URL contains text").action(wrap((text, options) => computerBrowserClickCommand(text, options)));
+  computer.command("browser-fill [field] [value]").description("Fill a Chrome field by ref from browser-state, or fall back to visible field text.").option("--ref <id>", "Fill the backend DOM node ref from the latest browser state").option("--exact", "Require an exact field match instead of substring matching").option("--index <n>", "When multiple fields match, fill the nth match. Default 0.").option("--target-id <id>", "Only target the Chrome page with this target id").option("--page <n>", "When multiple pages match, target the nth page. Default 0.").option("--title <text>", "Only target pages whose title contains text").option("--url <text>", "Only target pages whose URL contains text").action(wrap((field, value, options) => {
+    const resolvedValue = value ?? (options.ref ? field : void 0);
+    const resolvedField = value === void 0 && options.ref ? void 0 : field;
+    if (resolvedValue === void 0) throw new Error("Provide <field> <value>, or --ref <id> <value>");
+    return computerBrowserFillCommand(resolvedField, resolvedValue, options);
+  }));
+  computer.command("browser-scroll <direction>").description("Send trusted wheel input to a Chrome element ref or the center of the target page.").option("--ref <id>", "Scroll from the backend DOM node ref from the latest browser state").option("--amount <px>", "Scroll distance in CSS pixels. Default 600.").option("--target-id <id>", "Target the Chrome page with this stable target id").option("--page <n>", "When multiple pages match, target the nth page. Default 0.").option("--title <text>", "Only target pages whose title contains text").option("--url <text>", "Only target pages whose URL contains text").action(wrap((direction, options) => computerBrowserScrollCommand(direction, options)));
+  computer.command("browser-key <combo>").description("Press a key or modifier chord in the target Chrome page with trusted browser input.").option("--target-id <id>", "Target the Chrome page with this stable target id").option("--page <n>", "When multiple pages match, target the nth page. Default 0.").option("--title <text>", "Only target pages whose title contains text").option("--url <text>", "Only target pages whose URL contains text").action(wrap((combo, options) => computerBrowserKeyCommand(combo, options)));
+  computer.command("browser-type <text>").description("Type literal text into the focused field in the target Chrome page with trusted browser input.").option("--target-id <id>", "Target the Chrome page with this stable target id").option("--page <n>", "When multiple pages match, target the nth page. Default 0.").option("--title <text>", "Only target pages whose title contains text").option("--url <text>", "Only target pages whose URL contains text").action(wrap((text, options) => computerBrowserTypeCommand(text, options)));
+  computer.command("browser-wait <text>").description("Wait until Chrome page title, URL, body text, or controls match <text>.").option("--mode <mode>", "Where to match: any, text, title, url, or control. Default any.").option("--exact", "Require an exact match instead of substring matching").option("--timeout <ms>", "Maximum time to wait. Default 10000.").option("--poll-ms <ms>", "Polling interval. Default 250.").option("--target-id <id>", "Only target the Chrome page with this target id").option("--page <n>", "When multiple pages match, target the nth page. Default 0.").option("--title <text>", "Only target pages whose title contains text").option("--url <text>", "Only target pages whose URL contains text").action(wrap((text, options) => computerBrowserWaitCommand(text, options)));
   computer.command("click <x> <y>").description("Move to (x, y) and click. Coordinates are pixels or percentages like 50% 50%.").option("-b, --button <n>", "Mouse button (1=left, 2=middle, 3=right). Default 1.").option("--double", "Double-click instead of single-click").option("--modifiers <mods>", "Hold modifier keys during the click, e.g. ctrl or ctrl+shift").action(wrap((x, y, options) => computerClickCommand(x, y, options)));
   computer.command("move <x> <y>").description("Move the mouse to (x, y) without clicking. Coordinates are pixels or percentages like 50% 50%.").action(wrap((x, y) => computerMoveCommand(x, y)));
   computer.command("type <text>").description("Type a literal string into the focused field. Use `key` for key combos like ctrl+l.").option("--delay <ms>", "Per-character delay in ms (default 12 \u2248 80 wpm)").action(wrap((text, options) => computerTypeCommand(text, options)));