browserclaw 0.5.7 → 0.6.0

package/dist/index.cjs

@@ -1,26 +1,26 @@
 'use strict';
 
-var os = require('os');
-var path = require('path');
-var fs = require('fs');
-var net = require('net');
-var child_process = require('child_process');
-var playwrightCore = require('playwright-core');
 var http = require('http');
 var https = require('https');
-var promises = require('dns/promises');
+var playwrightCore = require('playwright-core');
+var child_process = require('child_process');
+var fs = require('fs');
+var net = require('net');
+var os = require('os');
+var path = require('path');
+var crypto = require('crypto');
 var dns = require('dns');
+var promises = require('dns/promises');
 var promises$1 = require('fs/promises');
-var crypto = require('crypto');
 
 function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
 
-var os__default = /*#__PURE__*/_interopDefault(os);
-var path__default = /*#__PURE__*/_interopDefault(path);
-var fs__default = /*#__PURE__*/_interopDefault(fs);
-var net__default = /*#__PURE__*/_interopDefault(net);
 var http__default = /*#__PURE__*/_interopDefault(http);
 var https__default = /*#__PURE__*/_interopDefault(https);
+var fs__default = /*#__PURE__*/_interopDefault(fs);
+var net__default = /*#__PURE__*/_interopDefault(net);
+var os__default = /*#__PURE__*/_interopDefault(os);
+var path__default = /*#__PURE__*/_interopDefault(path);
 
 var __create = Object.create;
 var __defProp = Object.defineProperty;
@@ -921,7 +921,7 @@ function execText(command, args, timeoutMs = 1200) {
       encoding: "utf8",
       maxBuffer: 1024 * 1024
     });
-    return String(output ?? "").trim() || null;
+    return output.trim() || null;
   } catch {
     return null;
   }
@@ -932,7 +932,8 @@ function inferKindFromIdentifier(identifier) {
   if (id.includes("edge")) return "edge";
   if (id.includes("chromium")) return "chromium";
   if (id.includes("canary")) return "canary";
-  if (id.includes("opera") || id.includes("vivaldi") || id.includes("yandex") || id.includes("thebrowser")) return "chromium";
+  if (id.includes("opera") || id.includes("vivaldi") || id.includes("yandex") || id.includes("thebrowser"))
+    return "chromium";
   return "chrome";
 }
 function inferKindFromExeName(name) {
@@ -949,24 +950,29 @@ function findFirstExe(candidates) {
   return null;
 }
 function detectDefaultBrowserBundleIdMac() {
-  const plistPath = path__default.default.join(os__default.default.homedir(), "Library/Preferences/com.apple.LaunchServices/com.apple.launchservices.secure.plist");
+  const plistPath = path__default.default.join(
+    os__default.default.homedir(),
+    "Library/Preferences/com.apple.LaunchServices/com.apple.launchservices.secure.plist"
+  );
   if (!fileExists(plistPath)) return null;
   const handlersRaw = execText("/usr/bin/plutil", ["-extract", "LSHandlers", "json", "-o", "-", "--", plistPath], 2e3);
-  if (!handlersRaw) return null;
+  if (handlersRaw === null) return null;
   let handlers;
   try {
-    handlers = JSON.parse(handlersRaw);
+    const parsed = JSON.parse(handlersRaw);
+    if (!Array.isArray(parsed)) return null;
+    handlers = parsed;
   } catch {
     return null;
   }
-  if (!Array.isArray(handlers)) return null;
   const resolveScheme = (scheme) => {
     let candidate = null;
     for (const entry of handlers) {
-      if (!entry || typeof entry !== "object") continue;
-      if (entry.LSHandlerURLScheme !== scheme) continue;
-      const role = typeof entry.LSHandlerRoleAll === "string" && entry.LSHandlerRoleAll || typeof entry.LSHandlerRoleViewer === "string" && entry.LSHandlerRoleViewer || null;
-      if (role) candidate = role;
+      if (entry === null || entry === void 0 || typeof entry !== "object") continue;
+      const rec = entry;
+      if (rec.LSHandlerURLScheme !== scheme) continue;
+      const role = (typeof rec.LSHandlerRoleAll === "string" ? rec.LSHandlerRoleAll : null) ?? (typeof rec.LSHandlerRoleViewer === "string" ? rec.LSHandlerRoleViewer : null) ?? null;
+      if (role !== null) candidate = role;
     }
     return candidate;
   };
@@ -974,12 +980,12 @@ function detectDefaultBrowserBundleIdMac() {
 }
 function detectDefaultChromiumMac() {
   const bundleId = detectDefaultBrowserBundleIdMac();
-  if (!bundleId || !CHROMIUM_BUNDLE_IDS.has(bundleId)) return null;
+  if (bundleId === null || !CHROMIUM_BUNDLE_IDS.has(bundleId)) return null;
   const appPathRaw = execText("/usr/bin/osascript", ["-e", `POSIX path of (path to application id "${bundleId}")`]);
-  if (!appPathRaw) return null;
+  if (appPathRaw === null) return null;
   const appPath = appPathRaw.trim().replace(/\/$/, "");
   const exeName = execText("/usr/bin/defaults", ["read", path__default.default.join(appPath, "Contents", "Info"), "CFBundleExecutable"]);
-  if (!exeName) return null;
+  if (exeName === null) return null;
   const exePath = path__default.default.join(appPath, "Contents", "MacOS", exeName.trim());
   if (!fileExists(exePath)) return null;
   return { kind: inferKindFromIdentifier(bundleId), path: exePath };
@@ -995,12 +1001,15 @@ function findChromeMac() {
     { kind: "chromium", path: "/Applications/Chromium.app/Contents/MacOS/Chromium" },
     { kind: "chromium", path: path__default.default.join(os__default.default.homedir(), "Applications/Chromium.app/Contents/MacOS/Chromium") },
     { kind: "canary", path: "/Applications/Google Chrome Canary.app/Contents/MacOS/Google Chrome Canary" },
-    { kind: "canary", path: path__default.default.join(os__default.default.homedir(), "Applications/Google Chrome Canary.app/Contents/MacOS/Google Chrome Canary") }
+    {
+      kind: "canary",
+      path: path__default.default.join(os__default.default.homedir(), "Applications/Google Chrome Canary.app/Contents/MacOS/Google Chrome Canary")
+    }
   ]);
 }
 function detectDefaultChromiumLinux() {
-  const desktopId = execText("xdg-settings", ["get", "default-web-browser"]) || execText("xdg-mime", ["query", "default", "x-scheme-handler/http"]);
-  if (!desktopId) return null;
+  const desktopId = execText("xdg-settings", ["get", "default-web-browser"]) ?? execText("xdg-mime", ["query", "default", "x-scheme-handler/http"]);
+  if (desktopId === null) return null;
   const trimmed = desktopId.trim();
   if (!CHROMIUM_DESKTOP_IDS.has(trimmed)) return null;
   const searchDirs = [
@@ -1017,17 +1026,18 @@ function detectDefaultChromiumLinux() {
       break;
     }
   }
-  if (!desktopPath) return null;
+  if (desktopPath === null) return null;
   let execLine = null;
   try {
     const lines = fs__default.default.readFileSync(desktopPath, "utf8").split(/\r?\n/);
-    for (const line of lines) if (line.startsWith("Exec=")) {
-      execLine = line.slice(5).trim();
-      break;
-    }
+    for (const line of lines)
+      if (line.startsWith("Exec=")) {
+        execLine = line.slice(5).trim();
+        break;
+      }
   } catch {
   }
-  if (!execLine) return null;
+  if (execLine === null) return null;
   const tokens = execLine.split(/\s+/);
   let command = null;
   for (const token of tokens) {
@@ -1035,9 +1045,9 @@ function detectDefaultChromiumLinux() {
     command = token.replace(/^["']|["']$/g, "");
     break;
   }
-  if (!command) return null;
+  if (command === null) return null;
   const resolved = command.startsWith("/") ? command : execText("which", [command], 800)?.trim() ?? null;
-  if (!resolved) return null;
+  if (resolved === null || resolved === "") return null;
   const exeName = path__default.default.posix.basename(resolved).toLowerCase();
   if (!CHROMIUM_EXE_NAMES.has(exeName)) return null;
   return { kind: inferKindFromExeName(exeName), path: resolved };
@@ -1066,21 +1076,30 @@ function findChromeWindows() {
   const candidates = [];
   if (localAppData) {
     candidates.push({ kind: "chrome", path: j(localAppData, "Google", "Chrome", "Application", "chrome.exe") });
-    candidates.push({ kind: "brave", path: j(localAppData, "BraveSoftware", "Brave-Browser", "Application", "brave.exe") });
+    candidates.push({
+      kind: "brave",
+      path: j(localAppData, "BraveSoftware", "Brave-Browser", "Application", "brave.exe")
+    });
     candidates.push({ kind: "edge", path: j(localAppData, "Microsoft", "Edge", "Application", "msedge.exe") });
     candidates.push({ kind: "chromium", path: j(localAppData, "Chromium", "Application", "chrome.exe") });
     candidates.push({ kind: "canary", path: j(localAppData, "Google", "Chrome SxS", "Application", "chrome.exe") });
   }
   candidates.push({ kind: "chrome", path: j(programFiles, "Google", "Chrome", "Application", "chrome.exe") });
   candidates.push({ kind: "chrome", path: j(programFilesX86, "Google", "Chrome", "Application", "chrome.exe") });
-  candidates.push({ kind: "brave", path: j(programFiles, "BraveSoftware", "Brave-Browser", "Application", "brave.exe") });
-  candidates.push({ kind: "brave", path: j(programFilesX86, "BraveSoftware", "Brave-Browser", "Application", "brave.exe") });
+  candidates.push({
+    kind: "brave",
+    path: j(programFiles, "BraveSoftware", "Brave-Browser", "Application", "brave.exe")
+  });
+  candidates.push({
+    kind: "brave",
+    path: j(programFilesX86, "BraveSoftware", "Brave-Browser", "Application", "brave.exe")
+  });
   candidates.push({ kind: "edge", path: j(programFiles, "Microsoft", "Edge", "Application", "msedge.exe") });
   candidates.push({ kind: "edge", path: j(programFilesX86, "Microsoft", "Edge", "Application", "msedge.exe") });
   return findFirstExe(candidates);
 }
 function resolveBrowserExecutable(opts) {
-  if (opts?.executablePath) {
+  if (opts?.executablePath !== void 0 && opts.executablePath !== "") {
     if (!fileExists(opts.executablePath)) throw new Error(`executablePath not found: ${opts.executablePath}`);
     return { kind: "custom", path: opts.executablePath };
   }
@@ -1093,10 +1112,12 @@ function resolveBrowserExecutable(opts) {
 async function ensurePortAvailable(port) {
   await new Promise((resolve2, reject) => {
     const tester = net__default.default.createServer().once("error", (err) => {
-      if (err.code === "EADDRINUSE") reject(new Error(`Port ${port} is already in use`));
+      if (err.code === "EADDRINUSE") reject(new Error(`Port ${String(port)} is already in use`));
       else reject(err);
     }).once("listening", () => {
-      tester.close(() => resolve2());
+      tester.close(() => {
+        resolve2();
+      });
     }).listen(port);
   });
 }
@@ -1178,7 +1199,7 @@ function isLoopbackHost(hostname) {
   return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "::1" || hostname === "[::1]";
 }
 function hasProxyEnvConfigured() {
-  return !!(process.env.HTTP_PROXY || process.env.HTTPS_PROXY || process.env.http_proxy || process.env.https_proxy);
+  return (process.env.HTTP_PROXY ?? process.env.HTTPS_PROXY ?? process.env.http_proxy ?? process.env.https_proxy ?? "") !== "";
 }
 function normalizeCdpWsUrl(wsUrl, cdpUrl) {
   const ws = new URL(wsUrl);
@@ -1230,7 +1251,12 @@ async function canOpenWebSocket(url, timeoutMs) {
       }
       resolve2(value);
     };
-    const timer = setTimeout(() => finish(false), Math.max(50, timeoutMs + 25));
+    const timer = setTimeout(
+      () => {
+        finish(false);
+      },
+      Math.max(50, timeoutMs + 25)
+    );
     let ws;
     try {
       ws = new WebSocket(url);
@@ -1238,21 +1264,27 @@ async function canOpenWebSocket(url, timeoutMs) {
       finish(false);
       return;
     }
-    ws.onopen = () => finish(true);
-    ws.onerror = () => finish(false);
+    ws.onopen = () => {
+      finish(true);
+    };
+    ws.onerror = () => {
+      finish(false);
+    };
   });
 }
 async function fetchChromeVersion(cdpUrl, timeoutMs = 500, authToken) {
   const ctrl = new AbortController();
-  const t = setTimeout(() => ctrl.abort(), timeoutMs);
+  const t = setTimeout(() => {
+    ctrl.abort();
+  }, timeoutMs);
   try {
     const httpBase = isWebSocketUrl(cdpUrl) ? normalizeCdpHttpBaseForJsonEndpoints(cdpUrl) : cdpUrl;
     const headers = {};
-    if (authToken) headers["Authorization"] = `Bearer ${authToken}`;
+    if (authToken !== void 0 && authToken !== "") headers.Authorization = `Bearer ${authToken}`;
     const res = await fetch(appendCdpPath(httpBase, "/json/version"), { signal: ctrl.signal, headers });
     if (!res.ok) return null;
     const data = await res.json();
-    if (!data || typeof data !== "object") return null;
+    if (data === null || data === void 0 || typeof data !== "object") return null;
     return data;
   } catch {
     return null;
@@ -1268,13 +1300,14 @@ async function isChromeReachable(cdpUrl, timeoutMs = 500, authToken) {
 async function getChromeWebSocketUrl(cdpUrl, timeoutMs = 500, authToken) {
   if (isWebSocketUrl(cdpUrl)) return cdpUrl;
   const version = await fetchChromeVersion(cdpUrl, timeoutMs, authToken);
-  const wsUrl = String(version?.webSocketDebuggerUrl ?? "").trim();
-  if (!wsUrl) return null;
+  const rawWsUrl = version?.webSocketDebuggerUrl;
+  const wsUrl = typeof rawWsUrl === "string" ? rawWsUrl.trim() : "";
+  if (wsUrl === "") return null;
   return normalizeCdpWsUrl(wsUrl, cdpUrl);
 }
 async function isChromeCdpReady(cdpUrl, timeoutMs = 500, handshakeTimeoutMs = 800) {
   const wsUrl = await getChromeWebSocketUrl(cdpUrl, timeoutMs);
-  if (!wsUrl) return false;
+  if (wsUrl === null) return false;
   return await canRunCdpHealthCommand(wsUrl, handshakeTimeoutMs);
 }
 async function canRunCdpHealthCommand(wsUrl, timeoutMs = 800) {
@@ -1290,7 +1323,12 @@ async function canRunCdpHealthCommand(wsUrl, timeoutMs = 800) {
       }
       resolve2(value);
     };
-    const timer = setTimeout(() => finish(false), Math.max(50, timeoutMs + 25));
+    const timer = setTimeout(
+      () => {
+        finish(false);
+      },
+      Math.max(50, timeoutMs + 25)
+    );
     let ws;
     try {
       ws = new WebSocket(wsUrl);
@@ -1308,26 +1346,33 @@ async function canRunCdpHealthCommand(wsUrl, timeoutMs = 800) {
     ws.onmessage = (event) => {
       try {
         const parsed = JSON.parse(String(event.data));
-        if (parsed?.id !== 1) return;
-        finish(Boolean(parsed.result && typeof parsed.result === "object"));
+        if (typeof parsed !== "object" || parsed === null) return;
+        const msg = parsed;
+        if (msg.id !== 1) return;
+        finish(typeof msg.result === "object" && msg.result !== null);
       } catch {
       }
     };
-    ws.onerror = () => finish(false);
-    ws.onclose = () => finish(false);
+    ws.onerror = () => {
+      finish(false);
+    };
+    ws.onclose = () => {
+      finish(false);
+    };
   });
 }
 async function launchChrome(opts = {}) {
   const cdpPort = opts.cdpPort ?? DEFAULT_CDP_PORT;
   await ensurePortAvailable(cdpPort);
   const exe = resolveBrowserExecutable({ executablePath: opts.executablePath });
-  if (!exe) throw new Error("No supported browser found (Chrome/Brave/Edge/Chromium). Install one or provide executablePath.");
+  if (!exe)
+    throw new Error("No supported browser found (Chrome/Brave/Edge/Chromium). Install one or provide executablePath.");
   const profileName = opts.profileName ?? DEFAULT_PROFILE_NAME;
   const userDataDir = opts.userDataDir ?? resolveUserDataDir(profileName);
   fs__default.default.mkdirSync(userDataDir, { recursive: true });
   const spawnChrome = () => {
     const args = [
-      `--remote-debugging-port=${cdpPort}`,
+      `--remote-debugging-port=${String(cdpPort)}`,
       `--user-data-dir=${userDataDir}`,
       "--no-first-run",
       "--no-default-browser-check",
@@ -1340,10 +1385,10 @@ async function launchChrome(opts = {}) {
       "--hide-crash-restore-bubble",
       "--password-store=basic"
     ];
-    if (opts.headless) {
+    if (opts.headless === true) {
       args.push("--headless=new", "--disable-gpu");
     }
-    if (opts.noSandbox) {
+    if (opts.noSandbox === true) {
       args.push("--no-sandbox", "--disable-setuid-sandbox");
     }
     if (process.platform === "linux") args.push("--disable-dev-shm-usage");
@@ -1390,12 +1435,12 @@ async function launchChrome(opts = {}) {
   } catch {
   }
   const proc = spawnChrome();
-  const cdpUrl = `http://127.0.0.1:${cdpPort}`;
+  const cdpUrl = `http://127.0.0.1:${String(cdpPort)}`;
   const stderrChunks = [];
   const onStderr = (chunk) => {
     stderrChunks.push(chunk);
   };
-  proc.stderr?.on("data", onStderr);
+  proc.stderr.on("data", onStderr);
   const readyDeadline = Date.now() + 15e3;
   while (Date.now() < readyDeadline) {
     if (await isChromeReachable(cdpUrl, 500)) break;
@@ -1406,14 +1451,14 @@ async function launchChrome(opts = {}) {
     const stderrHint = stderrOutput ? `
 Chrome stderr:
 ${stderrOutput.slice(0, 2e3)}` : "";
-    const sandboxHint = process.platform === "linux" && !opts.noSandbox ? "\nHint: If running in a container or as root, try setting noSandbox: true." : "";
+    const sandboxHint = process.platform === "linux" && opts.noSandbox !== true ? "\nHint: If running in a container or as root, try setting noSandbox: true." : "";
     try {
       proc.kill("SIGKILL");
     } catch {
     }
-    throw new Error(`Failed to start Chrome CDP on port ${cdpPort}.${sandboxHint}${stderrHint}`);
+    throw new Error(`Failed to start Chrome CDP on port ${String(cdpPort)}.${sandboxHint}${stderrHint}`);
   }
-  proc.stderr?.off("data", onStderr);
+  proc.stderr.off("data", onStderr);
   stderrChunks.length = 0;
   return {
     pid: proc.pid ?? -1,
@@ -1426,14 +1471,14 @@ ${stderrOutput.slice(0, 2e3)}` : "";
 }
 async function stopChrome(running, timeoutMs = 2500) {
   const proc = running.proc;
-  if (proc.exitCode != null) return;
+  if (proc.exitCode !== null) return;
   try {
     proc.kill("SIGTERM");
   } catch {
   }
   const start = Date.now();
   while (Date.now() - start < timeoutMs) {
-    if (proc.exitCode != null) return;
+    if (proc.exitCode !== null) return;
     await new Promise((r) => setTimeout(r, 100));
   }
   try {
@@ -1441,9 +1486,55 @@ async function stopChrome(running, timeoutMs = 2500) {
   } catch {
   }
 }
+
+// src/connection.ts
+var BrowserTabNotFoundError = class extends Error {
+  constructor(message = "Tab not found") {
+    super(message);
+    this.name = "BrowserTabNotFoundError";
+  }
+};
+async function fetchJsonForCdp(url, timeoutMs) {
+  const ctrl = new AbortController();
+  const t = setTimeout(() => {
+    ctrl.abort();
+  }, timeoutMs);
+  try {
+    const res = await fetch(url, { signal: ctrl.signal });
+    if (!res.ok) return null;
+    return await res.json();
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(t);
+  }
+}
+function appendCdpPath2(cdpUrl, cdpPath) {
+  try {
+    const url = new URL(cdpUrl);
+    url.pathname = `${url.pathname.replace(/\/$/, "")}${cdpPath.startsWith("/") ? cdpPath : `/${cdpPath}`}`;
+    return url.toString();
+  } catch {
+    return `${cdpUrl.replace(/\/$/, "")}${cdpPath}`;
+  }
+}
+async function withPlaywrightPageCdpSession(page, fn) {
+  const session = await page.context().newCDPSession(page);
+  try {
+    return await fn(session);
+  } finally {
+    await session.detach().catch(() => {
+    });
+  }
+}
+async function withPageScopedCdpClient(opts) {
+  return await withPlaywrightPageCdpSession(opts.page, async (session) => {
+    return await opts.fn((method, params) => session.send(method, params));
+  });
+}
 var LOOPBACK_ENTRIES = "localhost,127.0.0.1,[::1]";
 function noProxyAlreadyCoversLocalhost() {
-  const current = process.env.NO_PROXY || process.env.no_proxy || "";
+  const current = process.env.NO_PROXY ?? process.env.no_proxy ?? "";
   return current.includes("localhost") && current.includes("127.0.0.1") && current.includes("[::1]");
 }
 function isLoopbackCdpUrl(url) {
@@ -1461,7 +1552,7 @@ var NoProxyLeaseManager = class {
     if (this.leaseCount === 0 && !noProxyAlreadyCoversLocalhost()) {
       const noProxy = process.env.NO_PROXY;
       const noProxyLower = process.env.no_proxy;
-      const current = noProxy || noProxyLower || "";
+      const current = noProxy ?? noProxyLower ?? "";
       const applied = current ? `${current},${LOOPBACK_ENTRIES}` : LOOPBACK_ENTRIES;
       process.env.NO_PROXY = applied;
       process.env.no_proxy = applied;
@@ -1506,9 +1597,12 @@ function getHeadersWithAuth(endpoint, baseHeaders = {}) {
   const headers = { ...baseHeaders };
   try {
     const parsed = new URL(endpoint);
-    if (parsed.username && parsed.password) {
-      const credentials = Buffer.from(`${decodeURIComponent(parsed.username)}:${decodeURIComponent(parsed.password)}`).toString("base64");
-      headers["Authorization"] = `Basic ${credentials}`;
+    if (Object.keys(headers).some((k) => k.toLowerCase() === "authorization")) return headers;
+    if (parsed.username || parsed.password) {
+      const credentials = Buffer.from(
+        `${decodeURIComponent(parsed.username)}:${decodeURIComponent(parsed.password)}`
+      ).toString("base64");
+      headers.Authorization = `Basic ${credentials}`;
     }
   } catch {
   }
@@ -1556,7 +1650,7 @@ function roleRefsKey(cdpUrl, targetId) {
 function findNetworkRequestById(state, id) {
   for (let i = state.requests.length - 1; i >= 0; i--) {
     const candidate = state.requests[i];
-    if (candidate && candidate.id === id) return candidate;
+    if (candidate.id === id) return candidate;
   }
   return void 0;
 }
@@ -1587,16 +1681,16 @@ function ensurePageState(page) {
     });
     page.on("pageerror", (err) => {
       state.errors.push({
-        message: err?.message ? String(err.message) : String(err),
-        name: err?.name ? String(err.name) : void 0,
-        stack: err?.stack ? String(err.stack) : void 0,
+        message: err.message !== "" ? err.message : String(err),
+        name: err.name !== "" ? err.name : void 0,
+        stack: err.stack !== void 0 && err.stack !== "" ? err.stack : void 0,
         timestamp: (/* @__PURE__ */ new Date()).toISOString()
       });
       if (state.errors.length > MAX_PAGE_ERRORS) state.errors.shift();
     });
     page.on("request", (req) => {
       state.nextRequestId += 1;
-      const id = `r${state.nextRequestId}`;
+      const id = `r${String(state.nextRequestId)}`;
       state.requestIds.set(req, id);
       state.requests.push({
         id,
@@ -1610,7 +1704,7 @@ function ensurePageState(page) {
     page.on("response", (resp) => {
       const req = resp.request();
       const id = state.requestIds.get(req);
-      if (!id) return;
+      if (id === void 0) return;
       const rec = findNetworkRequestById(state, id);
       if (rec) {
         rec.status = resp.status();
@@ -1619,7 +1713,7 @@ function ensurePageState(page) {
     });
     page.on("requestfailed", (req) => {
       const id = state.requestIds.get(req);
-      if (!id) return;
+      if (id === void 0) return;
       const rec = findNetworkRequestById(state, id);
       if (rec) {
         rec.failureText = req.failure()?.errorText;
@@ -1636,7 +1730,8 @@ function ensurePageState(page) {
 var STEALTH_SCRIPT = `Object.defineProperty(navigator, 'webdriver', { get: () => undefined })`;
 function applyStealthToPage(page) {
   page.evaluate(STEALTH_SCRIPT).catch((e) => {
-    if (process.env.DEBUG) console.warn("[browserclaw] stealth evaluate failed:", e.message);
+    if (process.env.DEBUG !== void 0 && process.env.DEBUG !== "")
+      console.warn("[browserclaw] stealth evaluate failed:", e instanceof Error ? e.message : String(e));
   });
 }
 function observeContext(context) {
@@ -1644,7 +1739,8 @@ function observeContext(context) {
   observedContexts.add(context);
   ensureContextState(context);
   context.addInitScript(STEALTH_SCRIPT).catch((e) => {
-    if (process.env.DEBUG) console.warn("[browserclaw] stealth initScript failed:", e.message);
+    if (process.env.DEBUG !== void 0 && process.env.DEBUG !== "")
+      console.warn("[browserclaw] stealth initScript failed:", e instanceof Error ? e.message : String(e));
   });
   for (const page of context.pages()) {
     ensurePageState(page);
@@ -1660,15 +1756,15 @@ function observeBrowser(browser) {
 }
 function rememberRoleRefsForTarget(opts) {
   const targetId = opts.targetId.trim();
-  if (!targetId) return;
+  if (targetId === "") return;
   roleRefsByTarget.set(roleRefsKey(opts.cdpUrl, targetId), {
     refs: opts.refs,
-    ...opts.frameSelector ? { frameSelector: opts.frameSelector } : {},
-    ...opts.mode ? { mode: opts.mode } : {}
+    ...opts.frameSelector !== void 0 && opts.frameSelector !== "" ? { frameSelector: opts.frameSelector } : {},
+    ...opts.mode !== void 0 ? { mode: opts.mode } : {}
   });
   while (roleRefsByTarget.size > MAX_ROLE_REFS_CACHE) {
     const first = roleRefsByTarget.keys().next();
-    if (first.done) break;
+    if (first.done === true) break;
     roleRefsByTarget.delete(first.value);
   }
 }
@@ -1677,7 +1773,7 @@ function storeRoleRefsForTarget(opts) {
   state.roleRefs = opts.refs;
   state.roleRefsFrameSelector = opts.frameSelector;
   state.roleRefsMode = opts.mode;
-  if (!opts.targetId?.trim()) return;
+  if (opts.targetId === void 0 || opts.targetId.trim() === "") return;
   rememberRoleRefsForTarget({
     cdpUrl: opts.cdpUrl,
     targetId: opts.targetId,
@@ -1687,8 +1783,8 @@ function storeRoleRefsForTarget(opts) {
   });
 }
 function restoreRoleRefsForTarget(opts) {
-  const targetId = opts.targetId?.trim() || "";
-  if (!targetId) return;
+  const targetId = opts.targetId?.trim() ?? "";
+  if (targetId === "") return;
   const entry = roleRefsByTarget.get(roleRefsKey(opts.cdpUrl, targetId));
   if (!entry) return;
   const state = ensurePageState(opts.page);
@@ -1710,12 +1806,18 @@ async function connectBrowser(cdpUrl, authToken) {
         const timeout = 5e3 + attempt * 2e3;
         const endpoint = await getChromeWebSocketUrl(normalized, timeout, authToken).catch(() => null) ?? normalized;
         const headers = getHeadersWithAuth(endpoint);
-        if (authToken && !headers["Authorization"]) headers["Authorization"] = `Bearer ${authToken}`;
-        const browser = await withNoProxyForCdpUrl(endpoint, () => playwrightCore.chromium.connectOverCDP(endpoint, { timeout, headers }));
+        if (authToken !== void 0 && authToken !== "" && !headers.Authorization)
+          headers.Authorization = `Bearer ${authToken}`;
+        const browser = await withNoProxyForCdpUrl(
+          endpoint,
+          () => playwrightCore.chromium.connectOverCDP(endpoint, { timeout, headers })
+        );
         const onDisconnected = () => {
-          if (cachedByCdpUrl.get(normalized)?.browser === browser) cachedByCdpUrl.delete(normalized);
-          for (const key of roleRefsByTarget.keys()) {
-            if (key.startsWith(normalized + "::")) roleRefsByTarget.delete(key);
+          if (cachedByCdpUrl.get(normalized)?.browser === browser) {
+            cachedByCdpUrl.delete(normalized);
+            for (const key of roleRefsByTarget.keys()) {
+              if (key.startsWith(normalized + "::")) roleRefsByTarget.delete(key);
+            }
           }
         };
         const connected = { browser, cdpUrl: normalized, onDisconnected };
@@ -1763,7 +1865,9 @@ function cdpSocketNeedsAttach(wsUrl) {
 async function tryTerminateExecutionViaCdp(cdpUrl, targetId) {
   const httpBase = normalizeCdpHttpBaseForJsonEndpoints(cdpUrl);
   const ctrl = new AbortController();
-  const t = setTimeout(() => ctrl.abort(), 2e3);
+  const t = setTimeout(() => {
+    ctrl.abort();
+  }, 2e3);
   let targets;
   try {
     const res = await fetch(`${httpBase}/json/list`, { signal: ctrl.signal });
@@ -1775,9 +1879,12 @@ async function tryTerminateExecutionViaCdp(cdpUrl, targetId) {
     clearTimeout(t);
   }
   if (!Array.isArray(targets)) return;
-  const target = targets.find((entry) => String(entry?.id ?? "").trim() === targetId);
-  const wsUrlRaw = String(target?.webSocketDebuggerUrl ?? "").trim();
-  if (!wsUrlRaw) return;
+  const target = targets.find((entry) => {
+    const e = entry;
+    return (e.id ?? "").trim() === targetId;
+  });
+  const wsUrlRaw = (target?.webSocketDebuggerUrl ?? "").trim();
+  if (wsUrlRaw === "") return;
   const wsUrl = normalizeCdpWsUrl(wsUrlRaw, httpBase);
   const needsAttach = cdpSocketNeedsAttach(wsUrl);
   await new Promise((resolve2) => {
@@ -1813,10 +1920,18 @@ async function tryTerminateExecutionViaCdp(cdpUrl, targetId) {
       if (!needsAttach) return;
       try {
         const msg = JSON.parse(String(event.data));
-        if (msg.id && msg.result?.sessionId) {
-          ws.send(JSON.stringify({ id: nextId++, sessionId: msg.result.sessionId, method: "Runtime.terminateExecution" }));
+        const result = msg.result;
+        if (msg.id !== void 0 && result?.sessionId !== void 0) {
+          const sessionId = result.sessionId;
+          ws.send(JSON.stringify({ id: nextId++, sessionId, method: "Runtime.terminateExecution" }));
           try {
-            ws.send(JSON.stringify({ id: nextId++, method: "Target.detachFromTarget", params: { sessionId: msg.result.sessionId } }));
+            ws.send(
+              JSON.stringify({
+                id: nextId++,
+                method: "Target.detachFromTarget",
+                params: { sessionId }
+              })
+            );
           } catch {
           }
           setTimeout(finish, 300);
@@ -1824,8 +1939,12 @@ async function tryTerminateExecutionViaCdp(cdpUrl, targetId) {
       } catch {
       }
     };
-    ws.onerror = () => finish();
-    ws.onclose = () => finish();
+    ws.onerror = () => {
+      finish();
+    };
+    ws.onclose = () => {
+      finish();
+    };
   });
 }
 async function forceDisconnectPlaywrightForTarget(opts) {
@@ -1837,15 +1956,15 @@ async function forceDisconnectPlaywrightForTarget(opts) {
   if (cur.onDisconnected && typeof cur.browser.off === "function") {
     cur.browser.off("disconnected", cur.onDisconnected);
   }
-  const targetId = opts.targetId?.trim() || "";
-  if (targetId) {
+  const targetId = opts.targetId?.trim() ?? "";
+  if (targetId !== "") {
     await tryTerminateExecutionViaCdp(normalized, targetId).catch(() => {
     });
   }
   cur.browser.close().catch(() => {
   });
 }
-async function getAllPages(browser) {
+function getAllPages(browser) {
   return browser.contexts().flatMap((c) => c.pages());
 }
 async function pageTargetId(page) {
@@ -1853,14 +1972,36 @@ async function pageTargetId(page) {
   try {
     const info = await session.send("Target.getTargetInfo");
     const targetInfo = info.targetInfo;
-    return String(targetInfo?.targetId ?? "").trim() || null;
+    return (targetInfo?.targetId ?? "").trim() || null;
   } finally {
     await session.detach().catch(() => {
     });
   }
 }
+function matchPageByTargetList(pages, targets, targetId) {
+  const target = targets.find((entry) => entry.id === targetId);
+  if (!target) return null;
+  const urlMatch = pages.filter((page) => page.url() === target.url);
+  if (urlMatch.length === 1) return urlMatch[0] ?? null;
+  if (urlMatch.length > 1) {
+    const sameUrlTargets = targets.filter((entry) => entry.url === target.url);
+    if (sameUrlTargets.length === urlMatch.length) {
+      const idx = sameUrlTargets.findIndex((entry) => entry.id === targetId);
+      if (idx >= 0 && idx < urlMatch.length) return urlMatch[idx] ?? null;
+    }
+  }
+  return null;
+}
+async function findPageByTargetIdViaTargetList(pages, targetId, cdpUrl) {
+  const targets = await fetchJsonForCdp(
+    appendCdpPath2(normalizeCdpHttpBaseForJsonEndpoints(cdpUrl), "/json/list"),
+    2e3
+  );
+  if (!Array.isArray(targets)) return null;
+  return matchPageByTargetList(pages, targets, targetId);
+}
 async function findPageByTargetId(browser, targetId, cdpUrl) {
-  const pages = await getAllPages(browser);
+  const pages = getAllPages(browser);
   let resolvedViaCdp = false;
   for (const page of pages) {
     let tid = null;
@@ -1870,66 +2011,84 @@ async function findPageByTargetId(browser, targetId, cdpUrl) {
     } catch {
       tid = null;
     }
-    if (tid && tid === targetId) return page;
+    if (tid !== null && tid !== "" && tid === targetId) return page;
   }
-  if (cdpUrl) {
+  if (cdpUrl !== void 0 && cdpUrl !== "") {
     try {
-      const listUrl = `${normalizeCdpHttpBaseForJsonEndpoints(cdpUrl)}/json/list`;
-      const headers = {};
-      const ctrl = new AbortController();
-      const t = setTimeout(() => ctrl.abort(), 2e3);
-      try {
-        const response = await fetch(listUrl, { headers, signal: ctrl.signal });
-        if (response.ok) {
-          const targets = await response.json();
-          const target = targets.find((entry) => entry.id === targetId);
-          if (target) {
-            const urlMatch = pages.filter((p) => p.url() === target.url);
-            if (urlMatch.length === 1) return urlMatch[0];
-            if (urlMatch.length > 1) {
-              const sameUrlTargets = targets.filter((entry) => entry.url === target.url);
-              if (sameUrlTargets.length === urlMatch.length) {
-                const idx = sameUrlTargets.findIndex((entry) => entry.id === targetId);
-                if (idx >= 0 && idx < urlMatch.length) return urlMatch[idx];
-              }
-            }
-          }
-        }
-      } finally {
-        clearTimeout(t);
-      }
+      return await findPageByTargetIdViaTargetList(pages, targetId, cdpUrl);
     } catch {
     }
   }
-  if (!resolvedViaCdp && pages.length === 1) return pages[0];
+  if (!resolvedViaCdp && pages.length === 1) return pages[0] ?? null;
   return null;
 }
 async function getPageForTargetId(opts) {
   const { browser } = await connectBrowser(opts.cdpUrl);
-  const pages = await getAllPages(browser);
+  const pages = getAllPages(browser);
   if (!pages.length) throw new Error("No pages available in the connected browser.");
   const first = pages[0];
-  if (!opts.targetId) return first;
+  if (opts.targetId === void 0 || opts.targetId === "") return first;
   const found = await findPageByTargetId(browser, opts.targetId, opts.cdpUrl);
   if (!found) {
     if (pages.length === 1) return first;
-    throw new Error(`Tab not found (targetId: ${opts.targetId}). Call browser.tabs() to list open tabs.`);
+    throw new BrowserTabNotFoundError(
+      `Tab not found (targetId: ${opts.targetId}). Call browser.tabs() to list open tabs.`
+    );
   }
   return found;
 }
+async function resolvePageByTargetIdOrThrow(opts) {
+  const { browser } = await connectBrowser(opts.cdpUrl);
+  const page = await findPageByTargetId(browser, opts.targetId, opts.cdpUrl);
+  if (!page) throw new BrowserTabNotFoundError();
+  return page;
+}
+function parseRoleRef(raw) {
+  const trimmed = raw.trim();
+  if (!trimmed) return null;
+  const normalized = trimmed.startsWith("@") ? trimmed.slice(1) : trimmed.startsWith("ref=") ? trimmed.slice(4) : trimmed;
+  return /^e\d+$/.test(normalized) ? normalized : null;
+}
+function requireRef(value) {
+  const raw = typeof value === "string" ? value.trim() : "";
+  const ref = (raw ? parseRoleRef(raw) : null) ?? (raw.startsWith("@") ? raw.slice(1) : raw);
+  if (!ref) throw new Error("ref is required");
+  return ref;
+}
+function requireRefOrSelector(ref, selector) {
+  const trimmedRef = typeof ref === "string" ? ref.trim() : "";
+  const trimmedSelector = typeof selector === "string" ? selector.trim() : "";
+  if (!trimmedRef && !trimmedSelector) throw new Error("ref or selector is required");
+  return { ref: trimmedRef || void 0, selector: trimmedSelector || void 0 };
+}
+function resolveInteractionTimeoutMs(timeoutMs) {
+  return Math.max(500, Math.min(6e4, Math.floor(timeoutMs ?? 8e3)));
+}
+function resolveBoundedDelayMs(value, label, maxMs) {
+  const normalized = Math.floor(value ?? 0);
+  if (!Number.isFinite(normalized) || normalized < 0) throw new Error(`${label} must be >= 0`);
+  if (normalized > maxMs) throw new Error(`${label} exceeds maximum of ${String(maxMs)}ms`);
+  return normalized;
+}
+async function getRestoredPageForTarget(opts) {
+  const page = await getPageForTargetId(opts);
+  ensurePageState(page);
+  restoreRoleRefsForTarget({ cdpUrl: opts.cdpUrl, targetId: opts.targetId, page });
+  return page;
+}
 function refLocator(page, ref) {
   const normalized = ref.startsWith("@") ? ref.slice(1) : ref.startsWith("ref=") ? ref.slice(4) : ref;
-  if (!normalized.trim()) throw new Error("ref is required");
+  if (normalized.trim() === "") throw new Error("ref is required");
   if (/^e\d+$/.test(normalized)) {
     const state = pageStates.get(page);
     if (state?.roleRefsMode === "aria") {
-      return (state.roleRefsFrameSelector ? page.frameLocator(state.roleRefsFrameSelector) : page).locator(`aria-ref=${normalized}`);
+      return (state.roleRefsFrameSelector !== void 0 && state.roleRefsFrameSelector !== "" ? page.frameLocator(state.roleRefsFrameSelector) : page).locator(`aria-ref=${normalized}`);
     }
     const info = state?.roleRefs?.[normalized];
     if (!info) throw new Error(`Unknown ref "${normalized}". Run a new snapshot and use a ref from that snapshot.`);
-    const locAny = state?.roleRefsFrameSelector ? page.frameLocator(state.roleRefsFrameSelector) : page;
+    const locAny = state.roleRefsFrameSelector !== void 0 && state.roleRefsFrameSelector !== "" ? page.frameLocator(state.roleRefsFrameSelector) : page;
     const role = info.role;
-    const locator = info.name ? locAny.getByRole(role, { name: info.name, exact: true }) : locAny.getByRole(role);
+    const locator = info.name !== void 0 && info.name !== "" ? locAny.getByRole(role, { name: info.name, exact: true }) : locAny.getByRole(role);
     return info.nth !== void 0 ? locator.nth(info.nth) : locator;
   }
   return page.locator(`aria-ref=${normalized}`);
@@ -1937,15 +2096,21 @@ function refLocator(page, ref) {
 function toAIFriendlyError(error, selector) {
   const message = error instanceof Error ? error.message : String(error);
   if (message.includes("strict mode violation")) {
-    const countMatch = message.match(/resolved to (\d+) elements/);
+    const countMatch = /resolved to (\d+) elements/.exec(message);
     const count = countMatch ? countMatch[1] : "multiple";
-    return new Error(`Selector "${selector}" matched ${count} elements. Run a new snapshot to get updated refs, or use a different ref.`);
+    return new Error(
+      `Selector "${selector}" matched ${count} elements. Run a new snapshot to get updated refs, or use a different ref.`
+    );
   }
   if ((message.includes("Timeout") || message.includes("waiting for")) && (message.includes("to be visible") || message.includes("not visible"))) {
-    return new Error(`Element "${selector}" not found or not visible. Run a new snapshot to see current page elements.`);
+    return new Error(
+      `Element "${selector}" not found or not visible. Run a new snapshot to see current page elements.`
+    );
   }
   if (message.includes("intercepts pointer events") || message.includes("not visible") || message.includes("not receive pointer events")) {
-    return new Error(`Element "${selector}" is not interactable (hidden or covered). Try scrolling it into view, closing overlays, or re-snapshotting.`);
+    return new Error(
+      `Element "${selector}" is not interactable (hidden or covered). Try scrolling it into view, closing overlays, or re-snapshotting.`
+    );
   }
   return error instanceof Error ? error : new Error(message);
 }
@@ -1953,438 +2118,151 @@ function normalizeTimeoutMs(timeoutMs, fallback, maxMs = 12e4) {
   return Math.max(500, Math.min(maxMs, timeoutMs ?? fallback));
 }
 
-// src/snapshot/ref-map.ts
-var INTERACTIVE_ROLES = /* @__PURE__ */ new Set([
-  "button",
-  "link",
-  "textbox",
-  "checkbox",
-  "radio",
-  "combobox",
-  "listbox",
-  "menuitem",
-  "menuitemcheckbox",
-  "menuitemradio",
-  "option",
-  "searchbox",
-  "slider",
-  "spinbutton",
-  "switch",
-  "tab",
-  "treeitem"
-]);
-var CONTENT_ROLES = /* @__PURE__ */ new Set([
-  "heading",
-  "cell",
-  "gridcell",
-  "columnheader",
-  "rowheader",
-  "listitem",
-  "article",
-  "region",
-  "main",
-  "navigation"
-]);
-var STRUCTURAL_ROLES = /* @__PURE__ */ new Set([
-  "generic",
-  "group",
-  "list",
-  "table",
-  "row",
-  "rowgroup",
-  "grid",
-  "treegrid",
-  "menu",
-  "menubar",
-  "toolbar",
-  "tablist",
-  "tree",
-  "directory",
-  "document",
-  "application",
-  "presentation",
-  "none"
-]);
-function getIndentLevel(line) {
-  const match = line.match(/^(\s*)/);
-  return match ? Math.floor(match[1].length / 2) : 0;
-}
-function matchInteractiveSnapshotLine(line, options) {
-  const depth = getIndentLevel(line);
-  if (options.maxDepth !== void 0 && depth > options.maxDepth) {
-    return null;
-  }
-  const match = line.match(/^(\s*-\s*)(\w+)(?:\s+"([^"]*)")?(.*)$/);
-  if (!match) {
-    return null;
-  }
-  const [, , roleRaw, name, suffix] = match;
-  if (roleRaw.startsWith("/")) {
-    return null;
-  }
-  const role = roleRaw.toLowerCase();
-  return {
-    roleRaw,
-    role,
-    ...name ? { name } : {},
-    suffix
-  };
-}
-function createRoleNameTracker() {
-  const counts = /* @__PURE__ */ new Map();
-  const refsByKey = /* @__PURE__ */ new Map();
-  return {
-    counts,
-    refsByKey,
-    getKey(role, name) {
-      return `${role}:${name ?? ""}`;
-    },
-    getNextIndex(role, name) {
-      const key = this.getKey(role, name);
-      const current = counts.get(key) ?? 0;
-      counts.set(key, current + 1);
-      return current;
-    },
-    trackRef(role, name, ref) {
-      const key = this.getKey(role, name);
-      const list = refsByKey.get(key) ?? [];
-      list.push(ref);
-      refsByKey.set(key, list);
-    },
-    getDuplicateKeys() {
-      const out = /* @__PURE__ */ new Set();
-      for (const [key, refs] of refsByKey) if (refs.length > 1) out.add(key);
-      return out;
+// src/actions/evaluate.ts
+async function evaluateInAllFramesViaPlaywright(opts) {
+  const fnText = opts.fn.trim();
+  if (!fnText) throw new Error("function is required");
+  const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
+  const frames = page.frames();
+  const results = [];
+  for (const frame of frames) {
+    try {
+      const result = await frame.evaluate((fnBody) => {
+        "use strict";
+        try {
+          const candidate = (0, eval)("(" + fnBody + ")");
+          return typeof candidate === "function" ? candidate() : candidate;
+        } catch (err) {
+          throw new Error("Invalid evaluate function: " + (err instanceof Error ? err.message : String(err)));
+        }
+      }, fnText);
+      results.push({
+        frameUrl: frame.url(),
+        frameName: frame.name(),
+        result
+      });
+    } catch {
     }
-  };
+  }
+  return results;
 }
-function removeNthFromNonDuplicates(refs, tracker) {
-  const duplicates = tracker.getDuplicateKeys();
-  for (const [ref, data] of Object.entries(refs)) {
-    const key = tracker.getKey(data.role, data.name);
-    if (!duplicates.has(key)) delete refs[ref]?.nth;
+async function awaitEvalWithAbort(evalPromise, abortPromise) {
+  if (!abortPromise) return await evalPromise;
+  try {
+    return await Promise.race([evalPromise, abortPromise]);
+  } catch (err) {
+    evalPromise.catch(() => {
+    });
+    throw err;
   }
 }
-function compactTree(tree) {
-  const lines = tree.split("\n");
-  const result = [];
-  for (let i = 0; i < lines.length; i++) {
-    const line = lines[i];
-    if (line.includes("[ref=")) {
-      result.push(line);
-      continue;
-    }
-    if (line.includes(":") && !line.trimEnd().endsWith(":")) {
-      result.push(line);
-      continue;
-    }
-    const currentIndent = getIndentLevel(line);
-    let hasRelevantChildren = false;
-    for (let j = i + 1; j < lines.length; j++) {
-      if (getIndentLevel(lines[j]) <= currentIndent) break;
-      if (lines[j]?.includes("[ref=")) {
-        hasRelevantChildren = true;
-        break;
-      }
-    }
-    if (hasRelevantChildren) result.push(line);
-  }
-  return result.join("\n");
-}
-function buildRoleSnapshotFromAriaSnapshot(ariaSnapshot, options = {}) {
-  const lines = ariaSnapshot.split("\n");
-  const refs = {};
-  const tracker = createRoleNameTracker();
-  let counter = 0;
-  const nextRef = () => {
-    counter++;
-    return `e${counter}`;
-  };
-  if (options.interactive) {
-    const result2 = [];
-    for (const line of lines) {
-      const parsed = matchInteractiveSnapshotLine(line, options);
-      if (!parsed) continue;
-      const { roleRaw, role, name, suffix } = parsed;
-      if (!INTERACTIVE_ROLES.has(role)) continue;
-      const prefix = line.match(/^(\s*-\s*)/)?.[1] ?? "";
-      const ref = nextRef();
-      const nth = tracker.getNextIndex(role, name);
-      tracker.trackRef(role, name, ref);
-      refs[ref] = { role, name, nth };
-      let enhanced = `${prefix}${roleRaw}`;
-      if (name) enhanced += ` "${name}"`;
-      enhanced += ` [ref=${ref}]`;
-      if (nth > 0) enhanced += ` [nth=${nth}]`;
-      if (suffix.includes("[")) enhanced += suffix;
-      result2.push(enhanced);
-    }
-    removeNthFromNonDuplicates(refs, tracker);
-    return { snapshot: result2.join("\n") || "(no interactive elements)", refs };
-  }
-  const result = [];
-  for (const line of lines) {
-    const depth = getIndentLevel(line);
-    if (options.maxDepth !== void 0 && depth > options.maxDepth) continue;
-    const match = line.match(/^(\s*-\s*)(\w+)(?:\s+"([^"]*)")?(.*)$/);
-    if (!match) {
-      result.push(line);
-      continue;
-    }
-    const [, prefix, roleRaw, name, suffix] = match;
-    if (roleRaw.startsWith("/")) {
-      result.push(line);
-      continue;
-    }
-    const role = roleRaw.toLowerCase();
-    const isInteractive = INTERACTIVE_ROLES.has(role);
-    const isContent = CONTENT_ROLES.has(role);
-    const isStructural = STRUCTURAL_ROLES.has(role);
-    if (options.compact && isStructural && !name) continue;
-    if (!(isInteractive || isContent && name)) {
-      result.push(line);
-      continue;
-    }
-    const ref = nextRef();
-    const nth = tracker.getNextIndex(role, name);
-    tracker.trackRef(role, name, ref);
-    refs[ref] = { role, name, nth };
-    let enhanced = `${prefix}${roleRaw}`;
-    if (name) enhanced += ` "${name}"`;
-    enhanced += ` [ref=${ref}]`;
-    if (nth > 0) enhanced += ` [nth=${nth}]`;
-    if (suffix) enhanced += suffix;
-    result.push(enhanced);
-  }
-  removeNthFromNonDuplicates(refs, tracker);
-  const tree = result.join("\n") || "(empty)";
-  return { snapshot: options.compact ? compactTree(tree) : tree, refs };
-}
-function buildRoleSnapshotFromAiSnapshot(aiSnapshot, options = {}) {
-  const lines = String(aiSnapshot ?? "").split("\n");
-  const refs = {};
-  function parseAiSnapshotRef(suffix) {
-    const match = suffix.match(/\[ref=(e\d+)\]/i);
-    return match ? match[1] : null;
-  }
-  if (options.interactive) {
-    const out2 = [];
-    for (const line of lines) {
-      const parsed = matchInteractiveSnapshotLine(line, options);
-      if (!parsed) continue;
-      const { roleRaw, role, name, suffix } = parsed;
-      if (!INTERACTIVE_ROLES.has(role)) continue;
-      const ref = parseAiSnapshotRef(suffix);
-      if (!ref) continue;
-      const prefix = line.match(/^(\s*-\s*)/)?.[1] ?? "";
-      refs[ref] = { role, ...name ? { name } : {} };
-      out2.push(`${prefix}${roleRaw}${name ? ` "${name}"` : ""}${suffix}`);
+var BROWSER_EVALUATOR = new Function(
+  "args",
+  `
+  "use strict";
+  var fnBody = args.fnBody, timeoutMs = args.timeoutMs;
+  try {
+    var candidate = eval("(" + fnBody + ")");
+    var result = typeof candidate === "function" ? candidate() : candidate;
+    if (result && typeof result.then === "function") {
+      return Promise.race([
+        result,
+        new Promise(function(_, reject) {
+          setTimeout(function() { reject(new Error("evaluate timed out after " + timeoutMs + "ms")); }, timeoutMs);
+        })
+      ]);
     }
-    return { snapshot: out2.join("\n") || "(no interactive elements)", refs };
+    return result;
+  } catch (err) {
+    throw new Error("Invalid evaluate function: " + (err && err.message ? err.message : String(err)));
   }
-  const out = [];
-  for (const line of lines) {
-    const depth = getIndentLevel(line);
-    if (options.maxDepth !== void 0 && depth > options.maxDepth) continue;
-    const match = line.match(/^(\s*-\s*)(\w+)(?:\s+"([^"]*)")?(.*)$/);
-    if (!match) {
-      out.push(line);
-      continue;
-    }
-    const [, , roleRaw, name, suffix] = match;
-    if (roleRaw.startsWith("/")) {
-      out.push(line);
-      continue;
+`
+);
+var ELEMENT_EVALUATOR = new Function(
+  "el",
+  "args",
+  `
+  "use strict";
+  var fnBody = args.fnBody, timeoutMs = args.timeoutMs;
+  try {
+    var candidate = eval("(" + fnBody + ")");
+    var result = typeof candidate === "function" ? candidate(el) : candidate;
+    if (result && typeof result.then === "function") {
+      return Promise.race([
+        result,
+        new Promise(function(_, reject) {
+          setTimeout(function() { reject(new Error("evaluate timed out after " + timeoutMs + "ms")); }, timeoutMs);
+        })
+      ]);
     }
-    const role = roleRaw.toLowerCase();
-    const isStructural = STRUCTURAL_ROLES.has(role);
-    if (options.compact && isStructural && !name) continue;
-    const ref = parseAiSnapshotRef(suffix);
-    if (ref) refs[ref] = { role, ...name ? { name } : {} };
-    out.push(line);
-  }
-  const tree = out.join("\n") || "(empty)";
-  return { snapshot: options.compact ? compactTree(tree) : tree, refs };
-}
-function getRoleSnapshotStats(snapshot, refs) {
-  const interactive = Object.values(refs).filter((r) => INTERACTIVE_ROLES.has(r.role)).length;
-  return {
-    lines: snapshot.split("\n").length,
-    chars: snapshot.length,
-    refs: Object.keys(refs).length,
-    interactive
-  };
-}
-
-// src/snapshot/ai-snapshot.ts
-async function snapshotAi(opts) {
-  const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
-  ensurePageState(page);
-  const maybe = page;
-  if (!maybe._snapshotForAI) {
-    throw new Error("Playwright _snapshotForAI is not available. Upgrade playwright-core to >= 1.50.");
-  }
-  const sourceUrl = page.url();
-  const result = await maybe._snapshotForAI({
-    timeout: normalizeTimeoutMs(opts.timeoutMs, 5e3, 6e4),
-    track: "response"
-  });
-  let snapshot = String(result?.full ?? "");
-  const maxChars = opts.maxChars;
-  const limit = typeof maxChars === "number" && Number.isFinite(maxChars) && maxChars > 0 ? Math.floor(maxChars) : void 0;
-  if (limit && snapshot.length > limit) {
-    const lastNewline = snapshot.lastIndexOf("\n", limit);
-    const cutoff = lastNewline > 0 ? lastNewline : limit;
-    snapshot = `${snapshot.slice(0, cutoff)}
-
-[...TRUNCATED - page too large]`;
+    return result;
+  } catch (err) {
+    throw new Error("Invalid evaluate function: " + (err && err.message ? err.message : String(err)));
   }
-  const built = buildRoleSnapshotFromAiSnapshot(snapshot, opts.options);
-  storeRoleRefsForTarget({
-    page,
-    cdpUrl: opts.cdpUrl,
-    targetId: opts.targetId,
-    refs: built.refs,
-    mode: "aria"
-  });
-  return {
-    snapshot: built.snapshot,
-    refs: built.refs,
-    stats: getRoleSnapshotStats(built.snapshot, built.refs),
-    untrusted: true,
-    contentMeta: {
-      sourceUrl,
-      contentType: "browser-snapshot",
-      capturedAt: (/* @__PURE__ */ new Date()).toISOString()
-    }
-  };
-}
-
-// src/snapshot/aria-snapshot.ts
-async function snapshotRole(opts) {
+`
+);
+async function evaluateViaPlaywright(opts) {
+  const fnText = opts.fn.trim();
+  if (!fnText) throw new Error("function is required");
   const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
   ensurePageState(page);
-  const sourceUrl = page.url();
-  if (opts.refsMode === "aria") {
-    if (opts.selector?.trim() || opts.frameSelector?.trim()) {
-      throw new Error("refs=aria does not support selector/frame snapshots yet.");
-    }
-    const maybe = page;
-    if (!maybe._snapshotForAI) {
-      throw new Error("refs=aria requires Playwright _snapshotForAI support.");
-    }
-    const result = await maybe._snapshotForAI({ timeout: 5e3, track: "response" });
-    const built2 = buildRoleSnapshotFromAiSnapshot(String(result?.full ?? ""), opts.options);
-    storeRoleRefsForTarget({
-      page,
-      cdpUrl: opts.cdpUrl,
-      targetId: opts.targetId,
-      refs: built2.refs,
-      mode: "aria"
+  restoreRoleRefsForTarget({ cdpUrl: opts.cdpUrl, targetId: opts.targetId, page });
+  const outerTimeout = normalizeTimeoutMs(opts.timeoutMs, 2e4);
+  let evaluateTimeout = Math.max(1e3, Math.min(12e4, outerTimeout - 500));
+  evaluateTimeout = Math.min(evaluateTimeout, outerTimeout);
+  const signal = opts.signal;
+  let abortListener;
+  let abortReject;
+  let abortPromise;
+  if (signal !== void 0) {
+    abortPromise = new Promise((_, reject) => {
+      abortReject = reject;
+    });
+    abortPromise.catch(() => {
     });
-    return {
-      snapshot: built2.snapshot,
-      refs: built2.refs,
-      stats: getRoleSnapshotStats(built2.snapshot, built2.refs),
-      untrusted: true,
-      contentMeta: {
-        sourceUrl,
-        contentType: "browser-snapshot",
-        capturedAt: (/* @__PURE__ */ new Date()).toISOString()
-      }
-    };
   }
-  const frameSelector = opts.frameSelector?.trim() || "";
-  const selector = opts.selector?.trim() || "";
-  const locator = frameSelector ? selector ? page.frameLocator(frameSelector).locator(selector) : page.frameLocator(frameSelector).locator(":root") : selector ? page.locator(selector) : page.locator(":root");
-  const ariaSnapshot = await locator.ariaSnapshot({ timeout: normalizeTimeoutMs(opts.timeoutMs, 5e3) });
-  const built = buildRoleSnapshotFromAriaSnapshot(String(ariaSnapshot ?? ""), opts.options);
-  storeRoleRefsForTarget({
-    page,
-    cdpUrl: opts.cdpUrl,
-    targetId: opts.targetId,
-    refs: built.refs,
-    frameSelector: frameSelector || void 0,
-    mode: "role"
-  });
-  return {
-    snapshot: built.snapshot,
-    refs: built.refs,
-    stats: getRoleSnapshotStats(built.snapshot, built.refs),
-    untrusted: true,
-    contentMeta: {
-      sourceUrl,
-      contentType: "browser-snapshot",
-      capturedAt: (/* @__PURE__ */ new Date()).toISOString()
+  if (signal !== void 0) {
+    const disconnect = () => {
+      forceDisconnectPlaywrightForTarget({
+        cdpUrl: opts.cdpUrl,
+        targetId: opts.targetId}).catch(() => {
+      });
+    };
+    if (signal.aborted) {
+      disconnect();
+      throw signal.reason ?? new Error("aborted");
     }
-  };
-}
-async function snapshotAria(opts) {
-  const limit = Math.max(1, Math.min(2e3, Math.floor(opts.limit ?? 500)));
-  const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
-  ensurePageState(page);
-  const sourceUrl = page.url();
-  const session = await page.context().newCDPSession(page);
-  try {
-    await session.send("Accessibility.enable").catch(() => {
-    });
-    const res = await session.send("Accessibility.getFullAXTree");
-    return {
-      nodes: formatAriaNodes(Array.isArray(res?.nodes) ? res.nodes : [], limit),
-      untrusted: true,
-      contentMeta: {
-        sourceUrl,
-        contentType: "browser-aria-tree",
-        capturedAt: (/* @__PURE__ */ new Date()).toISOString()
-      }
+    abortListener = () => {
+      disconnect();
+      abortReject?.(signal.reason ?? new Error("aborted"));
     };
-  } finally {
-    await session.detach().catch(() => {
-    });
+    signal.addEventListener("abort", abortListener, { once: true });
+    if (signal.aborted) {
+      abortListener();
+      throw signal.reason ?? new Error("aborted");
+    }
   }
-}
-function axValue(v) {
-  if (!v || typeof v !== "object") return "";
-  const value = v.value;
-  if (typeof value === "string") return value;
-  if (typeof value === "number" || typeof value === "boolean") return String(value);
-  return "";
-}
-function formatAriaNodes(nodes, limit) {
-  const byId = /* @__PURE__ */ new Map();
-  for (const n of nodes) if (n.nodeId) byId.set(n.nodeId, n);
-  const referenced = /* @__PURE__ */ new Set();
-  for (const n of nodes) for (const c of n.childIds ?? []) referenced.add(c);
-  const root = nodes.find((n) => n.nodeId && !referenced.has(n.nodeId)) ?? nodes[0];
-  if (!root?.nodeId) return [];
-  const out = [];
-  const stack = [{ id: root.nodeId, depth: 0 }];
-  while (stack.length && out.length < limit) {
-    const popped = stack.pop();
-    if (!popped) break;
-    const { id, depth } = popped;
-    const n = byId.get(id);
-    if (!n) continue;
-    const role = axValue(n.role);
-    const name = axValue(n.name);
-    const value = axValue(n.value);
-    const description = axValue(n.description);
-    const ref = `ax${out.length + 1}`;
-    out.push({
-      ref,
-      role: role || "unknown",
-      name: name || "",
-      ...value ? { value } : {},
-      ...description ? { description } : {},
-      ...typeof n.backendDOMNodeId === "number" ? { backendDOMNodeId: n.backendDOMNodeId } : {},
-      depth
-    });
-    const children = (n.childIds ?? []).filter((c) => byId.has(c));
-    for (let i = children.length - 1; i >= 0; i--) {
-      if (children[i]) stack.push({ id: children[i], depth: depth + 1 });
+  try {
+    if (opts.ref !== void 0 && opts.ref !== "") {
+      const locator = refLocator(page, opts.ref);
+      return await awaitEvalWithAbort(
+        locator.evaluate(ELEMENT_EVALUATOR, {
+          fnBody: fnText,
+          timeoutMs: evaluateTimeout
+        }),
+        abortPromise
+      );
     }
+    return await awaitEvalWithAbort(
+      page.evaluate(BROWSER_EVALUATOR, {
+        fnBody: fnText,
+        timeoutMs: evaluateTimeout
+      }),
+      abortPromise
+    );
+  } finally {
+    if (signal && abortListener) signal.removeEventListener("abort", abortListener);
   }
-  return out;
 }
 
 // src/security.ts
@@ -2401,11 +2279,7 @@ function withBrowserNavigationPolicy(ssrfPolicy) {
 var NETWORK_NAVIGATION_PROTOCOLS = /* @__PURE__ */ new Set(["http:", "https:"]);
 var SAFE_NON_NETWORK_URLS = /* @__PURE__ */ new Set(["about:blank"]);
 var PROXY_ENV_KEYS = ["HTTP_PROXY", "HTTPS_PROXY", "ALL_PROXY", "http_proxy", "https_proxy", "all_proxy"];
-var BLOCKED_HOSTNAMES = /* @__PURE__ */ new Set([
-  "localhost",
-  "localhost.localdomain",
-  "metadata.google.internal"
-]);
+var BLOCKED_HOSTNAMES = /* @__PURE__ */ new Set(["localhost", "localhost.localdomain", "metadata.google.internal"]);
 function isAllowedNonNetworkNavigationUrl(parsed) {
   return SAFE_NON_NETWORK_URLS.has(parsed.href);
 }
@@ -2420,7 +2294,7 @@ function hasProxyEnvConfigured2(env = process.env) {
   return false;
 }
 function normalizeHostname(hostname) {
-  let h = String(hostname ?? "").trim().toLowerCase();
+  let h = hostname.trim().toLowerCase();
   if (h.startsWith("[") && h.endsWith("]")) h = h.slice(1, -1);
   if (h.endsWith(".")) h = h.slice(0, -1);
   return h;
@@ -2439,13 +2313,7 @@ var BLOCKED_IPV4_RANGES = /* @__PURE__ */ new Set([
   "private",
   "reserved"
 ]);
-var BLOCKED_IPV6_RANGES = /* @__PURE__ */ new Set([
-  "unspecified",
-  "loopback",
-  "linkLocal",
-  "uniqueLocal",
-  "multicast"
-]);
+var BLOCKED_IPV6_RANGES = /* @__PURE__ */ new Set(["unspecified", "loopback", "linkLocal", "uniqueLocal", "multicast"]);
 var RFC2544_BENCHMARK_PREFIX = [ipaddr.IPv4.parse("198.18.0.0"), 15];
 var EMBEDDED_IPV4_SENTINEL_RULES = [
   // IPv4-compatible (::a.b.c.d)
@@ -2494,12 +2362,12 @@ function parseIpv6WithEmbeddedIpv4(raw) {
 }
 function normalizeIpParseInput(raw) {
   const trimmed = raw?.trim();
-  if (!trimmed) return;
+  if (trimmed === void 0 || trimmed === "") return;
   return stripIpv6Brackets(trimmed);
 }
 function parseCanonicalIpAddress(raw) {
   const normalized = normalizeIpParseInput(raw);
-  if (!normalized) return;
+  if (normalized === void 0) return;
   if (ipaddr.IPv4.isValid(normalized)) {
     if (!ipaddr.IPv4.isValidFourPartDecimal(normalized)) return;
     return ipaddr.IPv4.parse(normalized);
@@ -2509,20 +2377,20 @@ function parseCanonicalIpAddress(raw) {
 }
 function parseLooseIpAddress(raw) {
   const normalized = normalizeIpParseInput(raw);
-  if (!normalized) return;
+  if (normalized === void 0) return;
   if (ipaddr.isValid(normalized)) return ipaddr.parse(normalized);
   return parseIpv6WithEmbeddedIpv4(normalized);
 }
 function isCanonicalDottedDecimalIPv4(raw) {
-  const trimmed = raw?.trim();
-  if (!trimmed) return false;
+  const trimmed = raw.trim();
+  if (trimmed === "") return false;
   const normalized = stripIpv6Brackets(trimmed);
   if (!normalized) return false;
   return ipaddr.IPv4.isValidFourPartDecimal(normalized);
 }
 function isLegacyIpv4Literal(raw) {
-  const trimmed = raw?.trim();
-  if (!trimmed) return false;
+  const trimmed = raw.trim();
+  if (trimmed === "") return false;
   const normalized = stripIpv6Brackets(trimmed);
   if (!normalized || normalized.includes(":")) return false;
   if (isCanonicalDottedDecimalIPv4(normalized)) return false;
@@ -2548,12 +2416,7 @@ function isBlockedSpecialUseIpv6Address(address) {
   return (address.parts[0] & 65472) === 65216;
 }
 function decodeIpv4FromHextets(high, low) {
-  const octets = [
-    high >>> 8 & 255,
-    high & 255,
-    low >>> 8 & 255,
-    low & 255
-  ];
+  const octets = [high >>> 8 & 255, high & 255, low >>> 8 & 255, low & 255];
   return ipaddr.IPv4.parse(octets.join("."));
 }
 function extractEmbeddedIpv4FromIpv6(address) {
@@ -2600,9 +2463,7 @@ function normalizeHostnameSet(values) {
 function normalizeHostnameAllowlist(values) {
   if (!values || values.length === 0) return [];
   return Array.from(
-    new Set(
-      values.map((v) => normalizeHostname(v)).filter((v) => v !== "*" && v !== "*." && v.length > 0)
-    )
+    new Set(values.map((v) => normalizeHostname(v)).filter((v) => v !== "*" && v !== "*." && v.length > 0))
   );
 }
 function isHostnameAllowedByPattern(hostname, pattern) {
@@ -2637,19 +2498,25 @@ function createPinnedLookup(params) {
     family: address.includes(":") ? 6 : 4
   }));
   let index = 0;
-  return ((host, options, callback) => {
-    const cb = typeof options === "function" ? options : callback;
-    if (!cb) return;
-    const normalized = normalizeHostname(host);
-    if (!normalized || normalized !== normalizedHost) {
-      if (typeof options === "function" || options === void 0) return fallback(host, cb);
-      return fallback(host, options, cb);
+  return ((_host, ...rest) => {
+    const second = rest[0];
+    const third = rest[1];
+    const cb = typeof second === "function" ? second : typeof third === "function" ? third : void 0;
+    if (cb === void 0) return;
+    const normalized = normalizeHostname(_host);
+    if (normalized === "" || normalized !== normalizedHost) {
+      if (typeof second === "function" || second === void 0) {
+        fallback(_host, cb);
+        return;
+      }
+      fallback(_host, second, cb);
+      return;
     }
-    const opts = typeof options === "object" && options !== null ? options : {};
-    const requestedFamily = typeof options === "number" ? options : typeof opts.family === "number" ? opts.family : 0;
+    const opts = typeof second === "object" ? second : {};
+    const requestedFamily = typeof second === "number" ? second : typeof opts.family === "number" ? opts.family : 0;
     const candidates = requestedFamily === 4 || requestedFamily === 6 ? records.filter((entry) => entry.family === requestedFamily) : records;
     const usable = candidates.length > 0 ? candidates : records;
-    if (opts.all) {
+    if (opts.all === true) {
       cb(null, usable);
       return;
     }
@@ -2667,9 +2534,7 @@ async function resolvePinnedHostnameWithPolicy(hostname, params = {}) {
   const isExplicitlyAllowed = allowedHostnames.has(normalized);
   const skipPrivateNetworkChecks = allowPrivateNetwork || isExplicitlyAllowed;
   if (!matchesHostnameAllowlist(normalized, hostnameAllowlist)) {
-    throw new InvalidBrowserNavigationUrlError(
-      `Navigation blocked: hostname "${hostname}" is not in the allowlist.`
-    );
+    throw new InvalidBrowserNavigationUrlError(`Navigation blocked: hostname "${hostname}" is not in the allowlist.`);
   }
   if (!skipPrivateNetworkChecks) {
     if (isBlockedHostnameOrIp(normalized, params.policy)) {
@@ -2687,7 +2552,7 @@ async function resolvePinnedHostnameWithPolicy(hostname, params = {}) {
       `Navigation to internal/loopback address blocked: unable to resolve "${hostname}". ssrfPolicy.dangerouslyAllowPrivateNetwork is false (strict mode).`
     );
   }
-  if (!results || results.length === 0) {
+  if (results.length === 0) {
     throw new InvalidBrowserNavigationUrlError(
       `Navigation to internal/loopback address blocked: unable to resolve "${hostname}". ssrfPolicy.dangerouslyAllowPrivateNetwork is false (strict mode).`
     );
@@ -2714,8 +2579,8 @@ async function resolvePinnedHostnameWithPolicy(hostname, params = {}) {
   };
 }
 async function assertBrowserNavigationAllowed(opts) {
-  const rawUrl = String(opts.url ?? "").trim();
-  if (!rawUrl) throw new InvalidBrowserNavigationUrlError("url is required");
+  const rawUrl = opts.url.trim();
+  if (rawUrl === "") throw new InvalidBrowserNavigationUrlError("url is required");
   let parsed;
   try {
     parsed = new URL(rawUrl);
@@ -2744,7 +2609,7 @@ async function assertSafeOutputPath(path2, allowedRoots) {
   if (normalized.includes("..")) {
     throw new Error(`Unsafe output path: directory traversal detected in "${path2}".`);
   }
-  if (allowedRoots?.length) {
+  if (allowedRoots !== void 0 && allowedRoots.length > 0) {
     const resolved = path.resolve(normalized);
     let parentReal;
     try {
@@ -2793,9 +2658,17 @@ async function assertSafeUploadPaths(paths) {
     }
   }
 }
+async function resolveStrictExistingUploadPaths(params) {
+  try {
+    await assertSafeUploadPaths(params.requestedPaths);
+    return { ok: true, paths: params.requestedPaths };
+  } catch (err) {
+    return { ok: false, error: err instanceof Error ? err.message : String(err) };
+  }
+}
 function sanitizeUntrustedFileName(fileName, fallbackName) {
-  const trimmed = String(fileName ?? "").trim();
-  if (!trimmed) return fallbackName;
+  const trimmed = fileName.trim();
+  if (trimmed === "") return fallbackName;
   let base = path.posix.basename(trimmed);
   base = path.win32.basename(base);
   let cleaned = "";
@@ -2829,16 +2702,17 @@ async function writeViaSiblingTempPath(params) {
     await promises$1.rename(tempPath, targetPath);
     renameSucceeded = true;
   } finally {
-    if (!renameSucceeded) await promises$1.rm(tempPath, { force: true }).catch(() => {
-    });
+    if (!renameSucceeded)
+      await promises$1.rm(tempPath, { force: true }).catch(() => {
+      });
   }
 }
 function isAbsolute(p) {
   return p.startsWith("/") || /^[a-zA-Z]:/.test(p);
 }
 async function assertBrowserNavigationResultAllowed(opts) {
-  const rawUrl = String(opts.url ?? "").trim();
-  if (!rawUrl) return;
+  const rawUrl = opts.url.trim();
+  if (rawUrl === "") return;
   let parsed;
   try {
     parsed = new URL(rawUrl);
@@ -2866,47 +2740,61 @@ function requiresInspectableBrowserNavigationRedirects(ssrfPolicy) {
 
 // src/actions/interaction.ts
 var MAX_CLICK_DELAY_MS = 5e3;
-function resolveBoundedDelayMs(value, label, maxMs) {
-  const normalized = Math.floor(value ?? 0);
-  if (!Number.isFinite(normalized) || normalized < 0) throw new Error(`${label} must be >= 0`);
-  if (normalized > maxMs) throw new Error(`${label} exceeds maximum of ${maxMs}ms`);
-  return normalized;
-}
-function resolveInteractionTimeoutMs(timeoutMs) {
-  return Math.max(500, Math.min(6e4, Math.floor(timeoutMs ?? 8e3)));
-}
-function requireRefOrSelector(ref, selector) {
-  const trimmedRef = typeof ref === "string" ? ref.trim() : "";
-  const trimmedSelector = typeof selector === "string" ? selector.trim() : "";
-  if (!trimmedRef && !trimmedSelector) throw new Error("ref or selector is required");
-  return { ref: trimmedRef || void 0, selector: trimmedSelector || void 0 };
-}
+var CHECKABLE_ROLES = /* @__PURE__ */ new Set(["menuitemcheckbox", "menuitemradio", "checkbox", "switch"]);
 function resolveLocator(page, resolved) {
-  return resolved.ref ? refLocator(page, resolved.ref) : page.locator(resolved.selector);
-}
-async function getRestoredPageForTarget(opts) {
-  const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
-  ensurePageState(page);
-  restoreRoleRefsForTarget({ cdpUrl: opts.cdpUrl, targetId: opts.targetId, page });
-  return page;
+  if (resolved.ref !== void 0 && resolved.ref !== "") return refLocator(page, resolved.ref);
+  const sel = resolved.selector ?? "";
+  return page.locator(sel);
 }
 async function clickViaPlaywright(opts) {
   const resolved = requireRefOrSelector(opts.ref, opts.selector);
   const page = await getRestoredPageForTarget(opts);
-  const label = resolved.ref ?? resolved.selector;
+  const label = resolved.ref ?? resolved.selector ?? "";
   const locator = resolveLocator(page, resolved);
   const timeout = resolveInteractionTimeoutMs(opts.timeoutMs);
+  let checkableRole = false;
+  if (resolved.ref !== void 0 && resolved.ref !== "") {
+    const refId = parseRoleRef(resolved.ref);
+    if (refId !== null) {
+      const state = ensurePageState(page);
+      const info = state.roleRefs?.[refId];
+      if (info && CHECKABLE_ROLES.has(info.role)) checkableRole = true;
+    }
+  }
   try {
     const delayMs = resolveBoundedDelayMs(opts.delayMs, "click delayMs", MAX_CLICK_DELAY_MS);
     if (delayMs > 0) {
       await locator.hover({ timeout });
       await new Promise((resolve2) => setTimeout(resolve2, delayMs));
     }
-    if (opts.doubleClick) {
+    let ariaCheckedBefore;
+    if (checkableRole && opts.doubleClick !== true) {
+      ariaCheckedBefore = await locator.getAttribute("aria-checked", { timeout }).catch(() => void 0);
+    }
+    if (opts.doubleClick === true) {
       await locator.dblclick({ timeout, button: opts.button, modifiers: opts.modifiers });
     } else {
       await locator.click({ timeout, button: opts.button, modifiers: opts.modifiers });
     }
+    if (checkableRole && opts.doubleClick !== true && ariaCheckedBefore !== void 0) {
+      const POLL_INTERVAL_MS = 50;
+      const POLL_TIMEOUT_MS = 500;
+      let changed = false;
+      for (let elapsed = 0; elapsed < POLL_TIMEOUT_MS; elapsed += POLL_INTERVAL_MS) {
+        const current = await locator.getAttribute("aria-checked", { timeout }).catch(() => void 0);
+        if (current === void 0 || current !== ariaCheckedBefore) {
+          changed = true;
+          break;
+        }
+        await new Promise((resolve2) => setTimeout(resolve2, POLL_INTERVAL_MS));
+      }
+      if (!changed) {
+        await locator.evaluate((el) => {
+          el.click();
+        }).catch(() => {
+        });
+      }
+    }
   } catch (err) {
     throw toAIFriendlyError(err, label);
   }
@@ -2914,7 +2802,7 @@ async function clickViaPlaywright(opts) {
 async function hoverViaPlaywright(opts) {
   const resolved = requireRefOrSelector(opts.ref, opts.selector);
   const page = await getRestoredPageForTarget(opts);
-  const label = resolved.ref ?? resolved.selector;
+  const label = resolved.ref ?? resolved.selector ?? "";
   const locator = resolveLocator(page, resolved);
   try {
     await locator.hover({ timeout: resolveInteractionTimeoutMs(opts.timeoutMs) });
@@ -2924,28 +2812,28 @@ async function hoverViaPlaywright(opts) {
 }
 async function typeViaPlaywright(opts) {
   const resolved = requireRefOrSelector(opts.ref, opts.selector);
-  const text = String(opts.text ?? "");
+  const text = opts.text;
   const page = await getRestoredPageForTarget(opts);
-  const label = resolved.ref ?? resolved.selector;
+  const label = resolved.ref ?? resolved.selector ?? "";
   const locator = resolveLocator(page, resolved);
   const timeout = resolveInteractionTimeoutMs(opts.timeoutMs);
   try {
-    if (opts.slowly) {
+    if (opts.slowly === true) {
       await locator.click({ timeout });
       await locator.pressSequentially(text, { timeout, delay: 75 });
     } else {
       await locator.fill(text, { timeout });
     }
-    if (opts.submit) await locator.press("Enter", { timeout });
+    if (opts.submit === true) await locator.press("Enter", { timeout });
   } catch (err) {
     throw toAIFriendlyError(err, label);
   }
 }
 async function selectOptionViaPlaywright(opts) {
   const resolved = requireRefOrSelector(opts.ref, opts.selector);
-  if (!opts.values?.length) throw new Error("values are required");
+  if (opts.values.length === 0) throw new Error("values are required");
   const page = await getRestoredPageForTarget(opts);
-  const label = resolved.ref ?? resolved.selector;
+  const label = resolved.ref ?? resolved.selector ?? "";
   const locator = resolveLocator(page, resolved);
   try {
     await locator.selectOption(opts.values, { timeout: resolveInteractionTimeoutMs(opts.timeoutMs) });
@@ -2959,8 +2847,8 @@ async function dragViaPlaywright(opts) {
   const page = await getRestoredPageForTarget(opts);
   const startLocator = resolveLocator(page, resolvedStart);
   const endLocator = resolveLocator(page, resolvedEnd);
-  const startLabel = resolvedStart.ref ?? resolvedStart.selector;
-  const endLabel = resolvedEnd.ref ?? resolvedEnd.selector;
+  const startLabel = resolvedStart.ref ?? resolvedStart.selector ?? "";
+  const endLabel = resolvedEnd.ref ?? resolvedEnd.selector ?? "";
   try {
     await startLocator.dragTo(endLocator, { timeout: resolveInteractionTimeoutMs(opts.timeoutMs) });
   } catch (err) {
@@ -2996,7 +2884,7 @@ async function fillFormViaPlaywright(opts) {
 async function scrollIntoViewViaPlaywright(opts) {
   const resolved = requireRefOrSelector(opts.ref, opts.selector);
   const page = await getRestoredPageForTarget(opts);
-  const label = resolved.ref ?? resolved.selector;
+  const label = resolved.ref ?? resolved.selector ?? "";
   const locator = resolveLocator(page, resolved);
   try {
     await locator.scrollIntoViewIfNeeded({ timeout: normalizeTimeoutMs(opts.timeoutMs, 2e4) });
@@ -3006,10 +2894,11 @@ async function scrollIntoViewViaPlaywright(opts) {
 }
 async function highlightViaPlaywright(opts) {
   const page = await getRestoredPageForTarget(opts);
+  const ref = requireRef(opts.ref);
   try {
-    await refLocator(page, opts.ref).highlight();
+    await refLocator(page, ref).highlight();
   } catch (err) {
-    throw toAIFriendlyError(err, opts.ref);
+    throw toAIFriendlyError(err, ref);
   }
 }
 async function setInputFilesViaPlaywright(opts) {
@@ -3020,9 +2909,14 @@ async function setInputFilesViaPlaywright(opts) {
   if (inputRef && element) throw new Error("ref and element are mutually exclusive");
   if (!inputRef && !element) throw new Error("Either ref or element is required for setInputFiles");
   const locator = inputRef ? refLocator(page, inputRef) : page.locator(element).first();
-  await assertSafeUploadPaths(opts.paths);
+  const uploadPathsResult = await resolveStrictExistingUploadPaths({
+    requestedPaths: opts.paths,
+    scopeLabel: "uploads directory"
+  });
+  if (!uploadPathsResult.ok) throw new Error(uploadPathsResult.error);
+  const resolvedPaths = uploadPathsResult.paths;
   try {
-    await locator.setInputFiles(opts.paths);
+    await locator.setInputFiles(resolvedPaths);
   } catch (err) {
     throw toAIFriendlyError(err, inputRef || element);
   }
@@ -3058,26 +2952,28 @@ async function armFileUploadViaPlaywright(opts) {
   const armId = state.armIdUpload;
   page.waitForEvent("filechooser", { timeout }).then(async (fileChooser) => {
     if (state.armIdUpload !== armId) return;
-    if (!opts.paths?.length) {
+    if (opts.paths === void 0 || opts.paths.length === 0) {
       try {
         await page.keyboard.press("Escape");
       } catch {
       }
       return;
     }
-    try {
-      await assertSafeUploadPaths(opts.paths);
-    } catch {
+    const uploadPathsResult = await resolveStrictExistingUploadPaths({
+      requestedPaths: opts.paths,
+      scopeLabel: "uploads directory"
+    });
+    if (!uploadPathsResult.ok) {
       try {
         await page.keyboard.press("Escape");
       } catch {
       }
       return;
     }
-    await fileChooser.setFiles(opts.paths);
+    await fileChooser.setFiles(uploadPathsResult.paths);
     try {
       const input = typeof fileChooser.element === "function" ? await Promise.resolve(fileChooser.element()) : null;
-      if (input) {
+      if (input !== null) {
         await input.evaluate((el) => {
           el.dispatchEvent(new Event("input", { bubbles: true }));
           el.dispatchEvent(new Event("change", { bubbles: true }));
@@ -3091,7 +2987,7 @@ async function armFileUploadViaPlaywright(opts) {
 
 // src/actions/keyboard.ts
 async function pressKeyViaPlaywright(opts) {
-  const key = String(opts.key ?? "").trim();
+  const key = opts.key.trim();
   if (!key) throw new Error("key is required");
   const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
   ensurePageState(page);
@@ -3104,9 +3000,9 @@ function isRetryableNavigateError(err) {
   return msg.includes("frame has been detached") || msg.includes("target page, context or browser has been closed");
 }
 async function navigateViaPlaywright(opts) {
-  const url = String(opts.url ?? "").trim();
+  const url = opts.url.trim();
   if (!url) throw new Error("url is required");
-  const policy = opts.allowInternal ? { ...opts.ssrfPolicy, dangerouslyAllowPrivateNetwork: true } : opts.ssrfPolicy;
+  const policy = opts.allowInternal === true ? { ...opts.ssrfPolicy, dangerouslyAllowPrivateNetwork: true } : opts.ssrfPolicy;
   await assertBrowserNavigationAllowed({ url, ...withBrowserNavigationPolicy(policy) });
   const timeout = Math.max(1e3, Math.min(12e4, opts.timeoutMs ?? 2e4));
   let page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
@@ -3125,45 +3021,49 @@ async function navigateViaPlaywright(opts) {
     ensurePageState(page);
     response = await navigate();
   }
-  await assertBrowserNavigationRedirectChainAllowed({ request: response?.request(), ...withBrowserNavigationPolicy(policy) });
+  await assertBrowserNavigationRedirectChainAllowed({
+    request: response?.request(),
+    ...withBrowserNavigationPolicy(policy)
+  });
   const finalUrl = page.url();
   await assertBrowserNavigationResultAllowed({ url: finalUrl, ...withBrowserNavigationPolicy(policy) });
   return { url: finalUrl };
 }
 async function listPagesViaPlaywright(opts) {
   const { browser } = await connectBrowser(opts.cdpUrl);
-  const pages = await getAllPages(browser);
+  const pages = getAllPages(browser);
   const results = [];
   for (const page of pages) {
     const tid = await pageTargetId(page).catch(() => null);
-    if (tid) results.push({
-      targetId: tid,
-      title: await page.title().catch(() => ""),
-      url: page.url(),
-      type: "page"
-    });
+    if (tid !== null && tid !== "")
+      results.push({
+        targetId: tid,
+        title: await page.title().catch(() => ""),
+        url: page.url(),
+        type: "page"
+      });
   }
   return results;
 }
 async function createPageViaPlaywright(opts) {
-  const targetUrl = (opts.url ?? "").trim() || "about:blank";
-  const policy = opts.allowInternal ? { ...opts.ssrfPolicy, dangerouslyAllowPrivateNetwork: true } : opts.ssrfPolicy;
-  if (targetUrl !== "about:blank") {
-    await assertBrowserNavigationAllowed({ url: targetUrl, ssrfPolicy: policy });
-  }
   const { browser } = await connectBrowser(opts.cdpUrl);
   const context = browser.contexts()[0] ?? await browser.newContext();
   ensureContextState(context);
   const page = await context.newPage();
   ensurePageState(page);
+  const targetUrl = (opts.url ?? "").trim() || "about:blank";
+  const policy = opts.allowInternal === true ? { ...opts.ssrfPolicy, dangerouslyAllowPrivateNetwork: true } : opts.ssrfPolicy;
   if (targetUrl !== "about:blank") {
     const navigationPolicy = withBrowserNavigationPolicy(policy);
-    const response = await page.goto(targetUrl, { timeout: 3e4 }).catch(() => null);
-    await assertBrowserNavigationRedirectChainAllowed({ request: response?.request(), ...navigationPolicy });
-    await assertBrowserNavigationResultAllowed({ url: page.url(), ssrfPolicy: policy });
+    await assertBrowserNavigationAllowed({ url: targetUrl, ...navigationPolicy });
+    await assertBrowserNavigationRedirectChainAllowed({
+      request: (await page.goto(targetUrl, { timeout: 3e4 }).catch(() => null))?.request(),
+      ...navigationPolicy
+    });
+    await assertBrowserNavigationResultAllowed({ url: page.url(), ...navigationPolicy });
   }
   const tid = await pageTargetId(page).catch(() => null);
-  if (!tid) throw new Error("Failed to get targetId for new page");
+  if (tid === null || tid === "") throw new Error("Failed to get targetId for new page");
   return {
     targetId: tid,
     title: await page.title().catch(() => ""),
@@ -3171,213 +3071,240 @@ async function createPageViaPlaywright(opts) {
     type: "page"
   };
 }
-async function closePageByTargetIdViaPlaywright(opts) {
-  const { browser } = await connectBrowser(opts.cdpUrl);
-  const page = await findPageByTargetId(browser, opts.targetId, opts.cdpUrl);
-  if (!page) throw new Error(`Tab not found (targetId: ${opts.targetId}). Use browser.tabs() to list open tabs.`);
-  await page.close();
-}
-async function focusPageByTargetIdViaPlaywright(opts) {
-  const { browser } = await connectBrowser(opts.cdpUrl);
-  const page = await findPageByTargetId(browser, opts.targetId, opts.cdpUrl);
-  if (!page) throw new Error(`Tab not found (targetId: ${opts.targetId}). Use browser.tabs() to list open tabs.`);
-  try {
-    await page.bringToFront();
-  } catch (err) {
-    const session = await page.context().newCDPSession(page);
-    try {
-      await session.send("Page.bringToFront");
-    } catch {
-      throw err;
-    } finally {
-      await session.detach().catch(() => {
-      });
-    }
-  }
-}
-async function resizeViewportViaPlaywright(opts) {
-  const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
-  ensurePageState(page);
-  await page.setViewportSize({
-    width: Math.max(1, Math.floor(opts.width)),
-    height: Math.max(1, Math.floor(opts.height))
-  });
-}
-
-// src/actions/wait.ts
-var MAX_WAIT_TIME_MS = 3e4;
-function resolveBoundedDelayMs2(value, label, maxMs) {
-  const normalized = Math.floor(value ?? 0);
-  if (!Number.isFinite(normalized) || normalized < 0) throw new Error(`${label} must be >= 0`);
-  if (normalized > maxMs) throw new Error(`${label} exceeds maximum of ${maxMs}ms`);
-  return normalized;
-}
-async function waitForViaPlaywright(opts) {
+async function closePageViaPlaywright(opts) {
   const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
   ensurePageState(page);
-  const timeout = normalizeTimeoutMs(opts.timeoutMs, 2e4);
-  if (typeof opts.timeMs === "number" && Number.isFinite(opts.timeMs)) {
-    await page.waitForTimeout(resolveBoundedDelayMs2(opts.timeMs, "wait timeMs", MAX_WAIT_TIME_MS));
-  }
-  if (opts.text) {
-    await page.getByText(opts.text).first().waitFor({ state: "visible", timeout });
-  }
-  if (opts.textGone) {
-    await page.getByText(opts.textGone).first().waitFor({ state: "hidden", timeout });
-  }
-  if (opts.selector) {
-    const selector = String(opts.selector).trim();
-    if (selector) await page.locator(selector).first().waitFor({ state: "visible", timeout });
-  }
-  if (opts.url) {
-    const url = String(opts.url).trim();
-    if (url) await page.waitForURL(url, { timeout });
-  }
-  if (opts.loadState) {
-    await page.waitForLoadState(opts.loadState, { timeout });
-  }
-  if (opts.fn) {
-    const fn = String(opts.fn).trim();
-    if (fn) await page.waitForFunction(fn, void 0, { timeout });
-  }
-}
-
-// src/actions/evaluate.ts
-async function evaluateInAllFramesViaPlaywright(opts) {
-  const fnText = String(opts.fn ?? "").trim();
-  if (!fnText) throw new Error("function is required");
-  const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
-  const frames = page.frames();
-  const results = [];
-  for (const frame of frames) {
-    try {
-      const result = await frame.evaluate(
-        // eslint-disable-next-line no-eval
-        (fnBody) => {
-          "use strict";
-          try {
-            const candidate = (0, eval)("(" + fnBody + ")");
-            return typeof candidate === "function" ? candidate() : candidate;
-          } catch (err) {
-            throw new Error("Invalid evaluate function: " + (err instanceof Error ? err.message : String(err)));
-          }
-        },
-        fnText
-      );
-      results.push({
-        frameUrl: frame.url(),
-        frameName: frame.name(),
-        result
-      });
-    } catch {
-    }
-  }
-  return results;
+  await page.close();
 }
-async function awaitEvalWithAbort(evalPromise, abortPromise) {
-  if (!abortPromise) return await evalPromise;
-  try {
-    return await Promise.race([evalPromise, abortPromise]);
-  } catch (err) {
-    evalPromise.catch(() => {
-    });
-    throw err;
-  }
+async function closePageByTargetIdViaPlaywright(opts) {
+  await (await resolvePageByTargetIdOrThrow(opts)).close();
 }
-var BROWSER_EVALUATOR = new Function("args", `
-  "use strict";
-  var fnBody = args.fnBody, timeoutMs = args.timeoutMs;
-  try {
-    var candidate = eval("(" + fnBody + ")");
-    var result = typeof candidate === "function" ? candidate() : candidate;
-    if (result && typeof result.then === "function") {
-      return Promise.race([
-        result,
-        new Promise(function(_, reject) {
-          setTimeout(function() { reject(new Error("evaluate timed out after " + timeoutMs + "ms")); }, timeoutMs);
-        })
-      ]);
-    }
-    return result;
-  } catch (err) {
-    throw new Error("Invalid evaluate function: " + (err && err.message ? err.message : String(err)));
-  }
-`);
-var ELEMENT_EVALUATOR = new Function("el", "args", `
-  "use strict";
-  var fnBody = args.fnBody, timeoutMs = args.timeoutMs;
+async function focusPageByTargetIdViaPlaywright(opts) {
+  const page = await resolvePageByTargetIdOrThrow(opts);
   try {
-    var candidate = eval("(" + fnBody + ")");
-    var result = typeof candidate === "function" ? candidate(el) : candidate;
-    if (result && typeof result.then === "function") {
-      return Promise.race([
-        result,
-        new Promise(function(_, reject) {
-          setTimeout(function() { reject(new Error("evaluate timed out after " + timeoutMs + "ms")); }, timeoutMs);
-        })
-      ]);
-    }
-    return result;
+    await page.bringToFront();
   } catch (err) {
-    throw new Error("Invalid evaluate function: " + (err && err.message ? err.message : String(err)));
+    try {
+      await withPageScopedCdpClient({
+        cdpUrl: opts.cdpUrl,
+        page,
+        targetId: opts.targetId,
+        fn: async (send) => {
+          await send("Page.bringToFront");
+        }
+      });
+      return;
+    } catch {
+      throw err;
+    }
   }
-`);
-async function evaluateViaPlaywright(opts) {
-  const fnText = String(opts.fn ?? "").trim();
-  if (!fnText) throw new Error("function is required");
+}
+async function resizeViewportViaPlaywright(opts) {
   const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
   ensurePageState(page);
-  restoreRoleRefsForTarget({ cdpUrl: opts.cdpUrl, targetId: opts.targetId, page });
-  const outerTimeout = normalizeTimeoutMs(opts.timeoutMs, 2e4);
-  let evaluateTimeout = Math.max(1e3, Math.min(12e4, outerTimeout - 500));
-  evaluateTimeout = Math.min(evaluateTimeout, outerTimeout);
-  const signal = opts.signal;
-  let abortListener;
-  let abortReject;
-  let abortPromise;
-  if (signal) {
-    abortPromise = new Promise((_, reject) => {
-      abortReject = reject;
-    });
-    abortPromise.catch(() => {
-    });
+  await page.setViewportSize({
+    width: Math.max(1, Math.floor(opts.width)),
+    height: Math.max(1, Math.floor(opts.height))
+  });
+}
+
+// src/actions/wait.ts
+var MAX_WAIT_TIME_MS = 3e4;
+function resolveBoundedDelayMs2(value, label, maxMs) {
+  const normalized = Math.floor(value ?? 0);
+  if (!Number.isFinite(normalized) || normalized < 0) throw new Error(`${label} must be >= 0`);
+  if (normalized > maxMs) throw new Error(`${label} exceeds maximum of ${String(maxMs)}ms`);
+  return normalized;
+}
+async function waitForViaPlaywright(opts) {
+  const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
+  ensurePageState(page);
+  const timeout = normalizeTimeoutMs(opts.timeoutMs, 2e4);
+  if (typeof opts.timeMs === "number" && Number.isFinite(opts.timeMs)) {
+    await page.waitForTimeout(resolveBoundedDelayMs2(opts.timeMs, "wait timeMs", MAX_WAIT_TIME_MS));
   }
-  if (signal) {
-    const disconnect = () => {
-      forceDisconnectPlaywrightForTarget({
-        cdpUrl: opts.cdpUrl,
-        targetId: opts.targetId}).catch(() => {
+  if (opts.text !== void 0 && opts.text !== "") {
+    await page.getByText(opts.text).first().waitFor({ state: "visible", timeout });
+  }
+  if (opts.textGone !== void 0 && opts.textGone !== "") {
+    await page.getByText(opts.textGone).first().waitFor({ state: "hidden", timeout });
+  }
+  if (opts.selector !== void 0 && opts.selector !== "") {
+    const selector = opts.selector.trim();
+    if (selector !== "") await page.locator(selector).first().waitFor({ state: "visible", timeout });
+  }
+  if (opts.url !== void 0 && opts.url !== "") {
+    const url = opts.url.trim();
+    if (url !== "") await page.waitForURL(url, { timeout });
+  }
+  if (opts.loadState !== void 0) {
+    await page.waitForLoadState(opts.loadState, { timeout });
+  }
+  if (opts.fn !== void 0 && opts.fn !== "") {
+    const fn = opts.fn.trim();
+    if (fn !== "") await page.waitForFunction(fn, void 0, { timeout });
+  }
+}
+
+// src/actions/batch.ts
+var MAX_BATCH_DEPTH = 5;
+var MAX_BATCH_ACTIONS = 100;
+async function executeSingleAction(action, cdpUrl, targetId, evaluateEnabled, depth = 0) {
+  if (depth > MAX_BATCH_DEPTH) throw new Error(`Batch nesting depth exceeds maximum of ${String(MAX_BATCH_DEPTH)}`);
+  const effectiveTargetId = action.targetId ?? targetId;
+  switch (action.kind) {
+    case "click":
+      await clickViaPlaywright({
+        cdpUrl,
+        targetId: effectiveTargetId,
+        ref: action.ref,
+        selector: action.selector,
+        doubleClick: action.doubleClick,
+        button: action.button,
+        modifiers: action.modifiers,
+        delayMs: action.delayMs,
+        timeoutMs: action.timeoutMs
       });
-    };
-    if (signal.aborted) {
-      disconnect();
-      throw signal.reason ?? new Error("aborted");
-    }
-    abortListener = () => {
-      disconnect();
-      abortReject?.(signal.reason ?? new Error("aborted"));
-    };
-    signal.addEventListener("abort", abortListener, { once: true });
-    if (signal.aborted) {
-      abortListener();
-      throw signal.reason ?? new Error("aborted");
-    }
+      break;
+    case "type":
+      await typeViaPlaywright({
+        cdpUrl,
+        targetId: effectiveTargetId,
+        ref: action.ref,
+        selector: action.selector,
+        text: action.text,
+        submit: action.submit,
+        slowly: action.slowly,
+        timeoutMs: action.timeoutMs
+      });
+      break;
+    case "press":
+      await pressKeyViaPlaywright({
+        cdpUrl,
+        targetId: effectiveTargetId,
+        key: action.key,
+        delayMs: action.delayMs
+      });
+      break;
+    case "hover":
+      await hoverViaPlaywright({
+        cdpUrl,
+        targetId: effectiveTargetId,
+        ref: action.ref,
+        selector: action.selector,
+        timeoutMs: action.timeoutMs
+      });
+      break;
+    case "scrollIntoView":
+      await scrollIntoViewViaPlaywright({
+        cdpUrl,
+        targetId: effectiveTargetId,
+        ref: action.ref,
+        selector: action.selector,
+        timeoutMs: action.timeoutMs
+      });
+      break;
+    case "drag":
+      await dragViaPlaywright({
+        cdpUrl,
+        targetId: effectiveTargetId,
+        startRef: action.startRef,
+        startSelector: action.startSelector,
+        endRef: action.endRef,
+        endSelector: action.endSelector,
+        timeoutMs: action.timeoutMs
+      });
+      break;
+    case "select":
+      await selectOptionViaPlaywright({
+        cdpUrl,
+        targetId: effectiveTargetId,
+        ref: action.ref,
+        selector: action.selector,
+        values: action.values,
+        timeoutMs: action.timeoutMs
+      });
+      break;
+    case "fill":
+      await fillFormViaPlaywright({
+        cdpUrl,
+        targetId: effectiveTargetId,
+        fields: action.fields,
+        timeoutMs: action.timeoutMs
+      });
+      break;
+    case "resize":
+      await resizeViewportViaPlaywright({
+        cdpUrl,
+        targetId: effectiveTargetId,
+        width: action.width,
+        height: action.height
+      });
+      break;
+    case "wait":
+      if (action.fn !== void 0 && action.fn !== "" && !evaluateEnabled)
+        throw new Error("wait --fn is disabled by config (browser.evaluateEnabled=false)");
+      await waitForViaPlaywright({
+        cdpUrl,
+        targetId: effectiveTargetId,
+        timeMs: action.timeMs,
+        text: action.text,
+        textGone: action.textGone,
+        selector: action.selector,
+        url: action.url,
+        loadState: action.loadState,
+        fn: action.fn,
+        timeoutMs: action.timeoutMs
+      });
+      break;
+    case "evaluate":
+      if (!evaluateEnabled) throw new Error("act:evaluate is disabled by config (browser.evaluateEnabled=false)");
+      await evaluateViaPlaywright({
+        cdpUrl,
+        targetId: effectiveTargetId,
+        fn: action.fn,
+        ref: action.ref,
+        timeoutMs: action.timeoutMs
+      });
+      break;
+    case "close":
+      await closePageViaPlaywright({
+        cdpUrl,
+        targetId: effectiveTargetId
+      });
+      break;
+    case "batch":
+      await batchViaPlaywright({
+        cdpUrl,
+        targetId: effectiveTargetId,
+        actions: action.actions,
+        stopOnError: action.stopOnError,
+        evaluateEnabled,
+        depth: depth + 1
+      });
+      break;
+    default:
+      throw new Error(`Unsupported batch action kind: ${String(action.kind)}`);
   }
-  try {
-    if (opts.ref) {
-      const locator = refLocator(page, opts.ref);
-      return await awaitEvalWithAbort(
-        locator.evaluate(ELEMENT_EVALUATOR, { fnBody: fnText, timeoutMs: evaluateTimeout }),
-        abortPromise
-      );
+}
+async function batchViaPlaywright(opts) {
+  const depth = opts.depth ?? 0;
+  if (depth > MAX_BATCH_DEPTH) throw new Error(`Batch nesting depth exceeds maximum of ${String(MAX_BATCH_DEPTH)}`);
+  if (opts.actions.length > MAX_BATCH_ACTIONS)
+    throw new Error(`Batch exceeds maximum of ${String(MAX_BATCH_ACTIONS)} actions`);
+  const results = [];
+  const evaluateEnabled = opts.evaluateEnabled !== false;
+  for (const action of opts.actions) {
+    try {
+      await executeSingleAction(action, opts.cdpUrl, opts.targetId, evaluateEnabled, depth);
+      results.push({ ok: true });
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      results.push({ ok: false, error: message });
+      if (opts.stopOnError !== false) break;
     }
-    return await awaitEvalWithAbort(
-      page.evaluate(BROWSER_EVALUATOR, { fnBody: fnText, timeoutMs: evaluateTimeout }),
-      abortPromise
-    );
-  } finally {
-    if (signal && abortListener) signal.removeEventListener("abort", abortListener);
   }
+  return { results };
 }
 function createPageDownloadWaiter(page, timeoutMs) {
   let done = false;
@@ -3412,379 +3339,856 @@ function createPageDownloadWaiter(page, timeoutMs) {
       done = true;
       cleanup();
     }
-  };
+  };
+}
+async function saveDownloadPayload(download, outPath) {
+  await writeViaSiblingTempPath({
+    rootDir: path.dirname(outPath),
+    targetPath: outPath,
+    writeTemp: async (tempPath) => {
+      await download.saveAs(tempPath);
+    }
+  });
+  return {
+    url: download.url(),
+    suggestedFilename: download.suggestedFilename(),
+    path: outPath
+  };
+}
+async function awaitDownloadPayload(params) {
+  try {
+    const download = await params.waiter.promise;
+    if (params.state.armIdDownload !== params.armId) throw new Error("Download was superseded by another waiter");
+    return await saveDownloadPayload(download, params.outPath);
+  } catch (err) {
+    params.waiter.cancel();
+    throw err;
+  }
+}
+async function downloadViaPlaywright(opts) {
+  await assertSafeOutputPath(opts.path, opts.allowedOutputRoots);
+  const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
+  const state = ensurePageState(page);
+  restoreRoleRefsForTarget({ cdpUrl: opts.cdpUrl, targetId: opts.targetId, page });
+  const timeout = normalizeTimeoutMs(opts.timeoutMs, 12e4);
+  const outPath = opts.path.trim();
+  if (!outPath) throw new Error("path is required");
+  state.armIdDownload = bumpDownloadArmId();
+  const armId = state.armIdDownload;
+  const waiter = createPageDownloadWaiter(page, timeout);
+  try {
+    const locator = refLocator(page, opts.ref);
+    try {
+      await locator.click({ timeout });
+    } catch (err) {
+      throw toAIFriendlyError(err, opts.ref);
+    }
+    return await awaitDownloadPayload({ waiter, state, armId, outPath });
+  } catch (err) {
+    waiter.cancel();
+    throw err;
+  }
+}
+async function waitForDownloadViaPlaywright(opts) {
+  const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
+  const state = ensurePageState(page);
+  const timeout = normalizeTimeoutMs(opts.timeoutMs, 12e4);
+  state.armIdDownload = bumpDownloadArmId();
+  const armId = state.armIdDownload;
+  const waiter = createPageDownloadWaiter(page, timeout);
+  try {
+    const download = await waiter.promise;
+    if (state.armIdDownload !== armId) throw new Error("Download was superseded by another waiter");
+    const savePath = opts.path ?? download.suggestedFilename();
+    await assertSafeOutputPath(savePath, opts.allowedOutputRoots);
+    return await saveDownloadPayload(download, savePath);
+  } catch (err) {
+    waiter.cancel();
+    throw err;
+  }
+}
+async function emulateMediaViaPlaywright(opts) {
+  const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
+  ensurePageState(page);
+  await page.emulateMedia({ colorScheme: opts.colorScheme });
+}
+async function setDeviceViaPlaywright(opts) {
+  const name = opts.name.trim();
+  if (!name) throw new Error("device name is required");
+  const device = playwrightCore.devices[name];
+  if (device === void 0) {
+    throw new Error(`Unknown device "${name}".`);
+  }
+  const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
+  ensurePageState(page);
+  if (device.viewport !== null) {
+    await page.setViewportSize({
+      width: device.viewport.width,
+      height: device.viewport.height
+    });
+  }
+  await withPageScopedCdpClient({
+    cdpUrl: opts.cdpUrl,
+    page,
+    targetId: opts.targetId,
+    fn: async (send) => {
+      const locale = device.locale;
+      if (device.userAgent !== "" || locale !== void 0 && locale !== "") {
+        await send("Emulation.setUserAgentOverride", {
+          userAgent: device.userAgent,
+          acceptLanguage: locale
+        });
+      }
+      if (device.viewport !== null) {
+        await send("Emulation.setDeviceMetricsOverride", {
+          mobile: device.isMobile,
+          width: device.viewport.width,
+          height: device.viewport.height,
+          deviceScaleFactor: device.deviceScaleFactor,
+          screenWidth: device.viewport.width,
+          screenHeight: device.viewport.height
+        });
+      }
+      if (device.hasTouch) {
+        await send("Emulation.setTouchEmulationEnabled", { enabled: true });
+      }
+    }
+  });
+}
+async function setExtraHTTPHeadersViaPlaywright(opts) {
+  const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
+  ensurePageState(page);
+  await page.context().setExtraHTTPHeaders(opts.headers);
+}
+async function setGeolocationViaPlaywright(opts) {
+  const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
+  ensurePageState(page);
+  const context = page.context();
+  if (opts.clear === true) {
+    await context.setGeolocation(null);
+    await context.clearPermissions().catch(() => {
+    });
+    return;
+  }
+  if (typeof opts.latitude !== "number" || typeof opts.longitude !== "number") {
+    throw new Error("latitude and longitude are required (or set clear=true)");
+  }
+  await context.setGeolocation({
+    latitude: opts.latitude,
+    longitude: opts.longitude,
+    accuracy: typeof opts.accuracy === "number" ? opts.accuracy : void 0
+  });
+  const origin = (opts.origin !== void 0 && opts.origin !== "" ? opts.origin.trim() : "") || (() => {
+    try {
+      return new URL(page.url()).origin;
+    } catch {
+      return "";
+    }
+  })();
+  if (origin !== "")
+    await context.grantPermissions(["geolocation"], { origin }).catch(() => {
+    });
+}
+async function setHttpCredentialsViaPlaywright(opts) {
+  const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
+  ensurePageState(page);
+  if (opts.clear === true) {
+    await page.context().setHTTPCredentials(null);
+    return;
+  }
+  const username = opts.username ?? "";
+  const password = opts.password ?? "";
+  if (!username) throw new Error("username is required (or set clear=true)");
+  await page.context().setHTTPCredentials({ username, password });
+}
+async function setLocaleViaPlaywright(opts) {
+  const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
+  ensurePageState(page);
+  const locale = opts.locale.trim();
+  if (!locale) throw new Error("locale is required");
+  await withPageScopedCdpClient({
+    cdpUrl: opts.cdpUrl,
+    page,
+    targetId: opts.targetId,
+    fn: async (send) => {
+      try {
+        await send("Emulation.setLocaleOverride", { locale });
+      } catch (err) {
+        if (String(err).includes("Another locale override is already in effect")) return;
+        throw err;
+      }
+    }
+  });
 }
-async function saveDownloadPayload(download, outPath) {
-  await writeViaSiblingTempPath({
-    rootDir: path.dirname(outPath),
-    targetPath: outPath,
-    writeTemp: async (tempPath) => {
-      await download.saveAs(tempPath);
+async function setOfflineViaPlaywright(opts) {
+  const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
+  ensurePageState(page);
+  await page.context().setOffline(opts.offline);
+}
+async function setTimezoneViaPlaywright(opts) {
+  const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
+  ensurePageState(page);
+  const timezoneId = opts.timezoneId.trim();
+  if (!timezoneId) throw new Error("timezoneId is required");
+  await withPageScopedCdpClient({
+    cdpUrl: opts.cdpUrl,
+    page,
+    targetId: opts.targetId,
+    fn: async (send) => {
+      try {
+        await send("Emulation.setTimezoneOverride", { timezoneId });
+      } catch (err) {
+        const msg = String(err);
+        if (msg.includes("Timezone override is already in effect")) return;
+        if (msg.includes("Invalid timezone")) throw new Error(`Invalid timezone ID: ${timezoneId}`, { cause: err });
+        throw err;
+      }
     }
   });
+}
+
+// src/capture/activity.ts
+function consolePriority(level) {
+  switch (level) {
+    case "error":
+      return 3;
+    case "warning":
+    case "warn":
+      return 2;
+    case "info":
+    case "log":
+      return 1;
+    case "debug":
+      return 0;
+    default:
+      return 1;
+  }
+}
+async function getConsoleMessagesViaPlaywright(opts) {
+  const state = ensurePageState(await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId }));
+  const messages = opts.level !== void 0 && opts.level !== "" ? state.console.filter((msg) => consolePriority(msg.type) >= consolePriority(opts.level ?? "")) : [...state.console];
+  if (opts.clear === true) state.console = [];
+  return messages;
+}
+async function getPageErrorsViaPlaywright(opts) {
+  const state = ensurePageState(await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId }));
+  const errors = [...state.errors];
+  if (opts.clear === true) state.errors = [];
+  return { errors };
+}
+async function getNetworkRequestsViaPlaywright(opts) {
+  const state = ensurePageState(await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId }));
+  const raw = [...state.requests];
+  const filter = typeof opts.filter === "string" ? opts.filter.trim() : "";
+  const requests = filter ? raw.filter((r) => r.url.includes(filter)) : raw;
+  if (opts.clear === true) {
+    state.requests = [];
+    state.requestIds = /* @__PURE__ */ new WeakMap();
+  }
+  return { requests };
+}
+
+// src/capture/pdf.ts
+async function pdfViaPlaywright(opts) {
+  const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
+  ensurePageState(page);
+  return { buffer: await page.pdf({ printBackground: true }) };
+}
+
+// src/capture/response.ts
+function matchUrlPattern(pattern, url) {
+  if (!pattern || !url) return false;
+  if (pattern === url) return true;
+  if (pattern.includes("*")) {
+    const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*");
+    try {
+      return new RegExp(`^${escaped}$`).test(url);
+    } catch {
+      return false;
+    }
+  }
+  return url.includes(pattern);
+}
+async function responseBodyViaPlaywright(opts) {
+  const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
+  ensurePageState(page);
+  const timeout = normalizeTimeoutMs(opts.timeoutMs, 3e4, 12e4);
+  const pattern = opts.url.trim();
+  if (!pattern) throw new Error("url is required");
+  const response = await page.waitForResponse((resp) => matchUrlPattern(pattern, resp.url()), { timeout });
+  let body = await response.text();
+  let truncated = false;
+  const maxChars = typeof opts.maxChars === "number" && Number.isFinite(opts.maxChars) ? Math.max(1, Math.min(5e6, Math.floor(opts.maxChars))) : 2e5;
+  if (body.length > maxChars) {
+    body = body.slice(0, maxChars);
+    truncated = true;
+  }
+  const headers = {};
+  const allHeaders = response.headers();
+  for (const [key, value] of Object.entries(allHeaders)) {
+    headers[key] = value;
+  }
   return {
-    url: download.url(),
-    suggestedFilename: download.suggestedFilename(),
-    path: outPath
+    url: response.url(),
+    status: response.status(),
+    headers,
+    body,
+    truncated
   };
 }
-async function awaitDownloadPayload(params) {
-  try {
-    const download = await params.waiter.promise;
-    if (params.state.armIdDownload !== params.armId) throw new Error("Download was superseded by another waiter");
-    return await saveDownloadPayload(download, params.outPath);
-  } catch (err) {
-    params.waiter.cancel();
-    throw err;
+
+// src/capture/screenshot.ts
+async function takeScreenshotViaPlaywright(opts) {
+  const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
+  ensurePageState(page);
+  restoreRoleRefsForTarget({ cdpUrl: opts.cdpUrl, targetId: opts.targetId, page });
+  const type = opts.type ?? "png";
+  if (opts.ref !== void 0 && opts.ref !== "") {
+    if (opts.fullPage === true) throw new Error("fullPage is not supported for element screenshots");
+    return { buffer: await refLocator(page, opts.ref).screenshot({ type }) };
   }
+  if (opts.element !== void 0 && opts.element !== "") {
+    if (opts.fullPage === true) throw new Error("fullPage is not supported for element screenshots");
+    return { buffer: await page.locator(opts.element).first().screenshot({ type }) };
+  }
+  return { buffer: await page.screenshot({ type, fullPage: Boolean(opts.fullPage) }) };
 }
-async function downloadViaPlaywright(opts) {
-  await assertSafeOutputPath(opts.path, opts.allowedOutputRoots);
+async function screenshotWithLabelsViaPlaywright(opts) {
   const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
-  const state = ensurePageState(page);
+  ensurePageState(page);
   restoreRoleRefsForTarget({ cdpUrl: opts.cdpUrl, targetId: opts.targetId, page });
-  const timeout = normalizeTimeoutMs(opts.timeoutMs, 12e4);
-  const outPath = String(opts.path ?? "").trim();
-  if (!outPath) throw new Error("path is required");
-  state.armIdDownload = bumpDownloadArmId();
-  const armId = state.armIdDownload;
-  const waiter = createPageDownloadWaiter(page, timeout);
-  try {
-    const locator = refLocator(page, opts.ref);
+  const maxLabels = typeof opts.maxLabels === "number" && Number.isFinite(opts.maxLabels) ? Math.max(1, Math.floor(opts.maxLabels)) : 150;
+  const type = opts.type ?? "png";
+  const refs = opts.refs.slice(0, maxLabels);
+  const skipped = opts.refs.slice(maxLabels);
+  const viewport = await page.evaluate(() => ({
+    width: window.innerWidth || 0,
+    height: window.innerHeight || 0
+  }));
+  const labels = [];
+  for (let i = 0; i < refs.length; i++) {
+    const ref = refs[i];
     try {
-      await locator.click({ timeout });
-    } catch (err) {
-      throw toAIFriendlyError(err, opts.ref);
+      const locator = refLocator(page, ref);
+      const box = await locator.boundingBox({ timeout: 2e3 });
+      if (!box) {
+        skipped.push(ref);
+        continue;
+      }
+      const x1 = box.x + box.width;
+      const y1 = box.y + box.height;
+      if (x1 < 0 || box.x > viewport.width || y1 < 0 || box.y > viewport.height) {
+        skipped.push(ref);
+        continue;
+      }
+      labels.push({ ref, index: i + 1, box });
+    } catch {
+      skipped.push(ref);
     }
-    return await awaitDownloadPayload({ waiter, state, armId, outPath });
-  } catch (err) {
-    waiter.cancel();
-    throw err;
+  }
+  try {
+    if (labels.length > 0) {
+      await page.evaluate(
+        (labelData) => {
+          document.querySelectorAll("[data-browserclaw-labels]").forEach((el) => {
+            el.remove();
+          });
+          const container = document.createElement("div");
+          container.setAttribute("data-browserclaw-labels", "1");
+          container.style.cssText = "position:fixed;top:0;left:0;width:100%;height:100%;pointer-events:none;z-index:2147483647;";
+          for (const { index, box } of labelData) {
+            const border = document.createElement("div");
+            border.style.cssText = `position:absolute;left:${String(box.x)}px;top:${String(box.y)}px;width:${String(box.width)}px;height:${String(box.height)}px;border:2px solid #FF4500;box-sizing:border-box;`;
+            container.appendChild(border);
+            const badge = document.createElement("div");
+            badge.textContent = String(index);
+            badge.style.cssText = `position:absolute;left:${String(box.x)}px;top:${String(Math.max(0, box.y - 18))}px;background:#FF4500;color:#fff;font:bold 12px/16px monospace;padding:0 4px;border-radius:2px;`;
+            container.appendChild(badge);
+          }
+          document.documentElement.appendChild(container);
+        },
+        labels.map((l) => ({ index: l.index, box: l.box }))
+      );
+    }
+    return {
+      buffer: await page.screenshot({ type }),
+      labels,
+      skipped
+    };
+  } finally {
+    await page.evaluate(() => {
+      document.querySelectorAll("[data-browserclaw-labels]").forEach((el) => {
+        el.remove();
+      });
+    }).catch(() => {
+    });
   }
 }
-async function waitForDownloadViaPlaywright(opts) {
+async function traceStartViaPlaywright(opts) {
   const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
-  const state = ensurePageState(page);
-  const timeout = normalizeTimeoutMs(opts.timeoutMs, 12e4);
-  state.armIdDownload = bumpDownloadArmId();
-  const armId = state.armIdDownload;
-  const waiter = createPageDownloadWaiter(page, timeout);
-  try {
-    const download = await waiter.promise;
-    if (state.armIdDownload !== armId) throw new Error("Download was superseded by another waiter");
-    const savePath = opts.path ?? download.suggestedFilename();
-    await assertSafeOutputPath(savePath, opts.allowedOutputRoots);
-    return await saveDownloadPayload(download, savePath);
-  } catch (err) {
-    waiter.cancel();
-    throw err;
+  ensurePageState(page);
+  const context = page.context();
+  const ctxState = ensureContextState(context);
+  if (ctxState.traceActive) {
+    throw new Error("Trace already running. Stop the current trace before starting a new one.");
   }
+  await context.tracing.start({
+    screenshots: opts.screenshots ?? true,
+    snapshots: opts.snapshots ?? true,
+    sources: opts.sources ?? false
+  });
+  ctxState.traceActive = true;
 }
-async function emulateMediaViaPlaywright(opts) {
+async function traceStopViaPlaywright(opts) {
+  await assertSafeOutputPath(opts.path, opts.allowedOutputRoots);
   const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
   ensurePageState(page);
-  await page.emulateMedia({ colorScheme: opts.colorScheme });
+  const context = page.context();
+  const ctxState = ensureContextState(context);
+  if (!ctxState.traceActive) {
+    throw new Error("No active trace. Start a trace before stopping it.");
+  }
+  await writeViaSiblingTempPath({
+    rootDir: path.dirname(opts.path),
+    targetPath: opts.path,
+    writeTemp: async (tempPath) => {
+      await context.tracing.stop({ path: tempPath });
+    }
+  });
+  ctxState.traceActive = false;
+}
+
+// src/snapshot/ref-map.ts
+var INTERACTIVE_ROLES = /* @__PURE__ */ new Set([
+  "button",
+  "link",
+  "textbox",
+  "checkbox",
+  "radio",
+  "combobox",
+  "listbox",
+  "menuitem",
+  "menuitemcheckbox",
+  "menuitemradio",
+  "option",
+  "searchbox",
+  "slider",
+  "spinbutton",
+  "switch",
+  "tab",
+  "treeitem"
+]);
+var CONTENT_ROLES = /* @__PURE__ */ new Set([
+  "heading",
+  "cell",
+  "gridcell",
+  "columnheader",
+  "rowheader",
+  "listitem",
+  "article",
+  "region",
+  "main",
+  "navigation"
+]);
+var STRUCTURAL_ROLES = /* @__PURE__ */ new Set([
+  "generic",
+  "group",
+  "list",
+  "table",
+  "row",
+  "rowgroup",
+  "grid",
+  "treegrid",
+  "menu",
+  "menubar",
+  "toolbar",
+  "tablist",
+  "tree",
+  "directory",
+  "document",
+  "application",
+  "presentation",
+  "none"
+]);
+function getIndentLevel(line) {
+  const match = /^(\s*)/.exec(line);
+  return match ? Math.floor(match[1].length / 2) : 0;
 }
-async function setDeviceViaPlaywright(opts) {
-  const name = String(opts.name ?? "").trim();
-  if (!name) throw new Error("device name is required");
-  const device = playwrightCore.devices[name];
-  if (!device) {
-    throw new Error(`Unknown device "${name}".`);
+function matchInteractiveSnapshotLine(line, options) {
+  const depth = getIndentLevel(line);
+  if (options.maxDepth !== void 0 && depth > options.maxDepth) {
+    return null;
   }
-  const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
-  ensurePageState(page);
-  if (device.viewport) {
-    await page.setViewportSize({
-      width: device.viewport.width,
-      height: device.viewport.height
-    });
+  const match = /^(\s*-\s*)(\w+)(?:\s+"([^"]*)")?(.*)$/.exec(line);
+  if (!match) {
+    return null;
   }
-  const session = await page.context().newCDPSession(page);
-  try {
-    const locale = device.locale;
-    if (device.userAgent || locale) {
-      await session.send("Emulation.setUserAgentOverride", {
-        userAgent: device.userAgent ?? "",
-        acceptLanguage: locale ?? void 0
-      });
-    }
-    if (device.viewport) {
-      await session.send("Emulation.setDeviceMetricsOverride", {
-        mobile: Boolean(device.isMobile),
-        width: device.viewport.width,
-        height: device.viewport.height,
-        deviceScaleFactor: device.deviceScaleFactor ?? 1,
-        screenWidth: device.viewport.width,
-        screenHeight: device.viewport.height
-      });
-    }
-    if (device.hasTouch) {
-      await session.send("Emulation.setTouchEmulationEnabled", { enabled: true });
-    }
-  } finally {
-    await session.detach().catch(() => {
-    });
+  const [, , roleRaw, name, suffix] = match;
+  if (roleRaw.startsWith("/")) {
+    return null;
   }
+  const role = roleRaw.toLowerCase();
+  return {
+    roleRaw,
+    role,
+    ...name ? { name } : {},
+    suffix
+  };
 }
-async function setExtraHTTPHeadersViaPlaywright(opts) {
-  const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
-  ensurePageState(page);
-  await page.context().setExtraHTTPHeaders(opts.headers);
-}
-async function setGeolocationViaPlaywright(opts) {
-  const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
-  ensurePageState(page);
-  const context = page.context();
-  if (opts.clear) {
-    await context.setGeolocation(null);
-    await context.clearPermissions().catch(() => {
-    });
-    return;
-  }
-  if (typeof opts.latitude !== "number" || typeof opts.longitude !== "number") {
-    throw new Error("latitude and longitude are required (or set clear=true)");
-  }
-  await context.setGeolocation({
-    latitude: opts.latitude,
-    longitude: opts.longitude,
-    accuracy: typeof opts.accuracy === "number" ? opts.accuracy : void 0
-  });
-  const origin = opts.origin?.trim() || (() => {
-    try {
-      return new URL(page.url()).origin;
-    } catch {
-      return "";
+function createRoleNameTracker() {
+  const counts = /* @__PURE__ */ new Map();
+  const refsByKey = /* @__PURE__ */ new Map();
+  return {
+    counts,
+    refsByKey,
+    getKey(role, name) {
+      return `${role}:${name ?? ""}`;
+    },
+    getNextIndex(role, name) {
+      const key = this.getKey(role, name);
+      const current = counts.get(key) ?? 0;
+      counts.set(key, current + 1);
+      return current;
+    },
+    trackRef(role, name, ref) {
+      const key = this.getKey(role, name);
+      const list = refsByKey.get(key) ?? [];
+      list.push(ref);
+      refsByKey.set(key, list);
+    },
+    getDuplicateKeys() {
+      const out = /* @__PURE__ */ new Set();
+      for (const [key, refs] of refsByKey) if (refs.length > 1) out.add(key);
+      return out;
     }
-  })();
-  if (origin) await context.grantPermissions(["geolocation"], { origin }).catch(() => {
-  });
+  };
 }
-async function setHttpCredentialsViaPlaywright(opts) {
-  const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
-  ensurePageState(page);
-  if (opts.clear) {
-    await page.context().setHTTPCredentials(null);
-    return;
+function removeNthFromNonDuplicates(refs, tracker) {
+  const duplicates = tracker.getDuplicateKeys();
+  for (const [ref, data] of Object.entries(refs)) {
+    const key = tracker.getKey(data.role, data.name);
+    if (!duplicates.has(key)) delete refs[ref].nth;
   }
-  const username = String(opts.username ?? "");
-  const password = String(opts.password ?? "");
-  if (!username) throw new Error("username is required (or set clear=true)");
-  await page.context().setHTTPCredentials({ username, password });
 }
-async function setLocaleViaPlaywright(opts) {
-  const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
-  ensurePageState(page);
-  const locale = String(opts.locale ?? "").trim();
-  if (!locale) throw new Error("locale is required");
-  const session = await page.context().newCDPSession(page);
-  try {
-    try {
-      await session.send("Emulation.setLocaleOverride", { locale });
-    } catch (err) {
-      if (String(err).includes("Another locale override is already in effect")) return;
-      throw err;
+function compactTree(tree) {
+  const lines = tree.split("\n");
+  const result = [];
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (line.includes("[ref=")) {
+      result.push(line);
+      continue;
     }
-  } finally {
-    await session.detach().catch(() => {
-    });
-  }
-}
-async function setOfflineViaPlaywright(opts) {
-  const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
-  ensurePageState(page);
-  await page.context().setOffline(Boolean(opts.offline));
-}
-async function setTimezoneViaPlaywright(opts) {
-  const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
-  ensurePageState(page);
-  const timezoneId = String(opts.timezoneId ?? "").trim();
-  if (!timezoneId) throw new Error("timezoneId is required");
-  const session = await page.context().newCDPSession(page);
-  try {
-    try {
-      await session.send("Emulation.setTimezoneOverride", { timezoneId });
-    } catch (err) {
-      const msg = String(err);
-      if (msg.includes("Timezone override is already in effect")) return;
-      if (msg.includes("Invalid timezone")) throw new Error(`Invalid timezone ID: ${timezoneId}`, { cause: err });
-      throw err;
+    if (line.includes(":") && !line.trimEnd().endsWith(":")) {
+      result.push(line);
+      continue;
     }
-  } finally {
-    await session.detach().catch(() => {
-    });
+    const currentIndent = getIndentLevel(line);
+    let hasRelevantChildren = false;
+    for (let j = i + 1; j < lines.length; j++) {
+      if (getIndentLevel(lines[j]) <= currentIndent) break;
+      if (lines[j]?.includes("[ref=")) {
+        hasRelevantChildren = true;
+        break;
+      }
+    }
+    if (hasRelevantChildren) result.push(line);
   }
+  return result.join("\n");
 }
-
-// src/capture/screenshot.ts
-async function takeScreenshotViaPlaywright(opts) {
-  const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
-  ensurePageState(page);
-  restoreRoleRefsForTarget({ cdpUrl: opts.cdpUrl, targetId: opts.targetId, page });
-  const type = opts.type ?? "png";
-  if (opts.ref) {
-    if (opts.fullPage) throw new Error("fullPage is not supported for element screenshots");
-    return { buffer: await refLocator(page, opts.ref).screenshot({ type }) };
+function buildRoleSnapshotFromAriaSnapshot(ariaSnapshot, options = {}) {
+  const lines = ariaSnapshot.split("\n");
+  const refs = {};
+  const tracker = createRoleNameTracker();
+  let counter = 0;
+  const nextRef = () => {
+    counter++;
+    return `e${String(counter)}`;
+  };
+  if (options.interactive === true) {
+    const result2 = [];
+    for (const line of lines) {
+      const parsed = matchInteractiveSnapshotLine(line, options);
+      if (!parsed) continue;
+      const { roleRaw, role, name, suffix } = parsed;
+      if (!INTERACTIVE_ROLES.has(role)) continue;
+      const prefix = /^(\s*-\s*)/.exec(line)?.[1] ?? "";
+      const ref = nextRef();
+      const nth = tracker.getNextIndex(role, name);
+      tracker.trackRef(role, name, ref);
+      refs[ref] = { role, name, nth };
+      let enhanced = `${prefix}${roleRaw}`;
+      if (name !== void 0 && name !== "") enhanced += ` "${name}"`;
+      enhanced += ` [ref=${ref}]`;
+      if (nth > 0) enhanced += ` [nth=${String(nth)}]`;
+      if (suffix.includes("[")) enhanced += suffix;
+      result2.push(enhanced);
+    }
+    removeNthFromNonDuplicates(refs, tracker);
+    return { snapshot: result2.join("\n") || "(no interactive elements)", refs };
   }
-  if (opts.element) {
-    if (opts.fullPage) throw new Error("fullPage is not supported for element screenshots");
-    return { buffer: await page.locator(opts.element).first().screenshot({ type }) };
+  const result = [];
+  for (const line of lines) {
+    const depth = getIndentLevel(line);
+    if (options.maxDepth !== void 0 && depth > options.maxDepth) continue;
+    const match = /^(\s*-\s*)(\w+)(?:\s+"([^"]*)")?(.*)$/.exec(line);
+    if (!match) {
+      result.push(line);
+      continue;
+    }
+    const [, prefix, roleRaw, name, suffix] = match;
+    if (roleRaw.startsWith("/")) {
+      result.push(line);
+      continue;
+    }
+    const role = roleRaw.toLowerCase();
+    const isInteractive = INTERACTIVE_ROLES.has(role);
+    const isContent = CONTENT_ROLES.has(role);
+    const isStructural = STRUCTURAL_ROLES.has(role);
+    if (options.compact === true && isStructural && name === "") continue;
+    if (!(isInteractive || isContent && name !== "")) {
+      result.push(line);
+      continue;
+    }
+    const ref = nextRef();
+    const nth = tracker.getNextIndex(role, name);
+    tracker.trackRef(role, name, ref);
+    refs[ref] = { role, name, nth };
+    let enhanced = `${prefix}${roleRaw}`;
+    if (name !== "") enhanced += ` "${name}"`;
+    enhanced += ` [ref=${ref}]`;
+    if (nth > 0) enhanced += ` [nth=${String(nth)}]`;
+    if (suffix !== "") enhanced += suffix;
+    result.push(enhanced);
   }
-  return { buffer: await page.screenshot({ type, fullPage: Boolean(opts.fullPage) }) };
+  removeNthFromNonDuplicates(refs, tracker);
+  const tree = result.join("\n") || "(empty)";
+  return { snapshot: options.compact === true ? compactTree(tree) : tree, refs };
 }
-async function screenshotWithLabelsViaPlaywright(opts) {
-  const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
-  ensurePageState(page);
-  restoreRoleRefsForTarget({ cdpUrl: opts.cdpUrl, targetId: opts.targetId, page });
-  const maxLabels = opts.maxLabels ?? 50;
-  const type = opts.type ?? "png";
-  const refs = opts.refs.slice(0, maxLabels);
-  const skipped = opts.refs.slice(maxLabels);
-  const labels = [];
-  for (let i = 0; i < refs.length; i++) {
-    const ref = refs[i];
-    try {
-      const locator = refLocator(page, ref);
-      const box = await locator.boundingBox({ timeout: 2e3 });
-      if (box) {
-        labels.push({ ref, index: i + 1, box });
-      } else {
-        skipped.push(ref);
-      }
-    } catch {
-      skipped.push(ref);
+function buildRoleSnapshotFromAiSnapshot(aiSnapshot, options = {}) {
+  const lines = aiSnapshot.split("\n");
+  const refs = {};
+  function parseAiSnapshotRef(suffix) {
+    const match = /\[ref=(e\d+)\]/i.exec(suffix);
+    return match ? match[1] : null;
+  }
+  if (options.interactive === true) {
+    const out2 = [];
+    for (const line of lines) {
+      const parsed = matchInteractiveSnapshotLine(line, options);
+      if (!parsed) continue;
+      const { roleRaw, role, name, suffix } = parsed;
+      if (!INTERACTIVE_ROLES.has(role)) continue;
+      const ref = parseAiSnapshotRef(suffix);
+      if (ref === null) continue;
+      const prefix = /^(\s*-\s*)/.exec(line)?.[1] ?? "";
+      refs[ref] = { role, ...name !== void 0 && name !== "" ? { name } : {} };
+      out2.push(`${prefix}${roleRaw}${name !== void 0 && name !== "" ? ` "${name}"` : ""}${suffix}`);
     }
+    return { snapshot: out2.join("\n") || "(no interactive elements)", refs };
   }
-  await page.evaluate((labelData) => {
-    const container = document.createElement("div");
-    container.id = "__browserclaw_labels__";
-    container.style.cssText = "position:fixed;top:0;left:0;width:100%;height:100%;pointer-events:none;z-index:2147483647;";
-    for (const { index, box } of labelData) {
-      const border = document.createElement("div");
-      border.style.cssText = `position:absolute;left:${box.x}px;top:${box.y}px;width:${box.width}px;height:${box.height}px;border:2px solid #FF4500;box-sizing:border-box;`;
-      container.appendChild(border);
-      const badge = document.createElement("div");
-      badge.textContent = String(index);
-      badge.style.cssText = `position:absolute;left:${box.x}px;top:${Math.max(0, box.y - 18)}px;background:#FF4500;color:#fff;font:bold 12px/16px monospace;padding:0 4px;border-radius:2px;`;
-      container.appendChild(badge);
+  const out = [];
+  for (const line of lines) {
+    const depth = getIndentLevel(line);
+    if (options.maxDepth !== void 0 && depth > options.maxDepth) continue;
+    const match = /^(\s*-\s*)(\w+)(?:\s+"([^"]*)")?(.*)$/.exec(line);
+    if (!match) {
+      out.push(line);
+      continue;
     }
-    document.body.appendChild(container);
-  }, labels.map((l) => ({ index: l.index, box: l.box })));
-  const buffer = await page.screenshot({ type });
-  await page.evaluate(() => {
-    const el = document.getElementById("__browserclaw_labels__");
-    if (el) el.remove();
-  }).catch(() => {
-  });
-  return { buffer, labels, skipped };
+    const [, , roleRaw, name, suffix] = match;
+    if (roleRaw.startsWith("/")) {
+      out.push(line);
+      continue;
+    }
+    const role = roleRaw.toLowerCase();
+    const isStructural = STRUCTURAL_ROLES.has(role);
+    if (options.compact === true && isStructural && name === "") continue;
+    const ref = parseAiSnapshotRef(suffix);
+    if (ref !== null) refs[ref] = { role, ...name !== "" ? { name } : {} };
+    out.push(line);
+  }
+  const tree = out.join("\n") || "(empty)";
+  return { snapshot: options.compact === true ? compactTree(tree) : tree, refs };
 }
-
-// src/capture/pdf.ts
-async function pdfViaPlaywright(opts) {
-  const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
-  ensurePageState(page);
-  return { buffer: await page.pdf({ printBackground: true }) };
+function getRoleSnapshotStats(snapshot, refs) {
+  const interactive = Object.values(refs).filter((r) => INTERACTIVE_ROLES.has(r.role)).length;
+  return {
+    lines: snapshot.split("\n").length,
+    chars: snapshot.length,
+    refs: Object.keys(refs).length,
+    interactive
+  };
 }
-async function traceStartViaPlaywright(opts) {
+
+// src/snapshot/ai-snapshot.ts
+async function snapshotAi(opts) {
   const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
   ensurePageState(page);
-  const context = page.context();
-  const ctxState = ensureContextState(context);
-  if (ctxState.traceActive) {
-    throw new Error("Trace already running. Stop the current trace before starting a new one.");
+  const maybe = page;
+  if (!maybe._snapshotForAI) {
+    throw new Error("Playwright _snapshotForAI is not available. Upgrade playwright-core to >= 1.50.");
   }
-  await context.tracing.start({
-    screenshots: opts.screenshots ?? true,
-    snapshots: opts.snapshots ?? true,
-    sources: opts.sources ?? false
+  const sourceUrl = page.url();
+  const result = await maybe._snapshotForAI({
+    timeout: normalizeTimeoutMs(opts.timeoutMs, 5e3, 6e4),
+    track: "response"
   });
-  ctxState.traceActive = true;
-}
-async function traceStopViaPlaywright(opts) {
-  await assertSafeOutputPath(opts.path, opts.allowedOutputRoots);
-  const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
-  ensurePageState(page);
-  const context = page.context();
-  const ctxState = ensureContextState(context);
-  if (!ctxState.traceActive) {
-    throw new Error("No active trace. Start a trace before stopping it.");
+  let snapshot = String(result.full);
+  const maxChars = opts.maxChars;
+  const limit = typeof maxChars === "number" && Number.isFinite(maxChars) && maxChars > 0 ? Math.floor(maxChars) : void 0;
+  let truncated = false;
+  if (limit !== void 0 && snapshot.length > limit) {
+    const lastNewline = snapshot.lastIndexOf("\n", limit);
+    const cutoff = lastNewline > 0 ? lastNewline : limit;
+    snapshot = `${snapshot.slice(0, cutoff)}
+
+[...TRUNCATED - page too large]`;
+    truncated = true;
   }
-  await writeViaSiblingTempPath({
-    rootDir: path.dirname(opts.path),
-    targetPath: opts.path,
-    writeTemp: async (tempPath) => {
-      await context.tracing.stop({ path: tempPath });
-    }
+  const built = buildRoleSnapshotFromAiSnapshot(snapshot, opts.options);
+  storeRoleRefsForTarget({
+    page,
+    cdpUrl: opts.cdpUrl,
+    targetId: opts.targetId,
+    refs: built.refs,
+    mode: "aria"
   });
-  ctxState.traceActive = false;
+  return {
+    snapshot: built.snapshot,
+    refs: built.refs,
+    stats: getRoleSnapshotStats(built.snapshot, built.refs),
+    ...truncated ? { truncated } : {},
+    untrusted: true,
+    contentMeta: {
+      sourceUrl,
+      contentType: "browser-snapshot",
+      capturedAt: (/* @__PURE__ */ new Date()).toISOString()
+    }
+  };
 }
 
-// src/capture/response.ts
-async function responseBodyViaPlaywright(opts) {
+// src/snapshot/aria-snapshot.ts
+async function snapshotRole(opts) {
   const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
   ensurePageState(page);
-  const timeout = normalizeTimeoutMs(opts.timeoutMs, 3e4, 12e4);
-  const response = await page.waitForResponse(opts.url, { timeout });
-  let body = await response.text();
-  let truncated = false;
-  const maxChars = typeof opts.maxChars === "number" && Number.isFinite(opts.maxChars) ? Math.max(1, Math.min(5e6, Math.floor(opts.maxChars))) : void 0;
-  if (maxChars !== void 0 && body.length > maxChars) {
-    body = body.slice(0, maxChars);
-    truncated = true;
-  }
-  const headers = {};
-  const allHeaders = response.headers();
-  for (const [key, value] of Object.entries(allHeaders)) {
-    headers[key] = value;
+  const sourceUrl = page.url();
+  if (opts.refsMode === "aria") {
+    if (opts.selector !== void 0 && opts.selector.trim() !== "" || opts.frameSelector !== void 0 && opts.frameSelector.trim() !== "") {
+      throw new Error("refs=aria does not support selector/frame snapshots yet.");
+    }
+    const maybe = page;
+    if (!maybe._snapshotForAI) {
+      throw new Error("refs=aria requires Playwright _snapshotForAI support.");
+    }
+    const result = await maybe._snapshotForAI({ timeout: 5e3, track: "response" });
+    const built2 = buildRoleSnapshotFromAiSnapshot(String(result.full), opts.options);
+    storeRoleRefsForTarget({
+      page,
+      cdpUrl: opts.cdpUrl,
+      targetId: opts.targetId,
+      refs: built2.refs,
+      mode: "aria"
+    });
+    return {
+      snapshot: built2.snapshot,
+      refs: built2.refs,
+      stats: getRoleSnapshotStats(built2.snapshot, built2.refs),
+      untrusted: true,
+      contentMeta: {
+        sourceUrl,
+        contentType: "browser-snapshot",
+        capturedAt: (/* @__PURE__ */ new Date()).toISOString()
+      }
+    };
   }
+  const frameSelector = opts.frameSelector?.trim() ?? "";
+  const selector = opts.selector?.trim() ?? "";
+  const locator = frameSelector ? selector ? page.frameLocator(frameSelector).locator(selector) : page.frameLocator(frameSelector).locator(":root") : selector ? page.locator(selector) : page.locator(":root");
+  const ariaSnapshot = await locator.ariaSnapshot({ timeout: normalizeTimeoutMs(opts.timeoutMs, 5e3) });
+  const built = buildRoleSnapshotFromAriaSnapshot(ariaSnapshot, opts.options);
+  storeRoleRefsForTarget({
+    page,
+    cdpUrl: opts.cdpUrl,
+    targetId: opts.targetId,
+    refs: built.refs,
+    frameSelector: frameSelector !== "" ? frameSelector : void 0,
+    mode: "role"
+  });
   return {
-    url: response.url(),
-    status: response.status(),
-    headers,
-    body,
-    truncated
+    snapshot: built.snapshot,
+    refs: built.refs,
+    stats: getRoleSnapshotStats(built.snapshot, built.refs),
+    untrusted: true,
+    contentMeta: {
+      sourceUrl,
+      contentType: "browser-snapshot",
+      capturedAt: (/* @__PURE__ */ new Date()).toISOString()
+    }
   };
 }
-
-// src/capture/activity.ts
-function consolePriority(level) {
-  switch (level) {
-    case "error":
-      return 3;
-    case "warning":
-    case "warn":
-      return 2;
-    case "info":
-    case "log":
-      return 1;
-    case "debug":
-      return 0;
-    default:
-      return 1;
-  }
-}
-async function getConsoleMessagesViaPlaywright(opts) {
-  const state = ensurePageState(await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId }));
-  const messages = opts.level ? state.console.filter((msg) => consolePriority(msg.type) >= consolePriority(opts.level)) : [...state.console];
-  if (opts.clear) state.console = [];
-  return messages;
+async function snapshotAria(opts) {
+  const limit = Math.max(1, Math.min(2e3, Math.floor(opts.limit ?? 500)));
+  const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
+  ensurePageState(page);
+  const sourceUrl = page.url();
+  const res = await withPlaywrightPageCdpSession(page, async (session) => {
+    await session.send("Accessibility.enable").catch(() => {
+    });
+    return await session.send("Accessibility.getFullAXTree");
+  });
+  return {
+    nodes: formatAriaNodes(Array.isArray(res.nodes) ? res.nodes : [], limit),
+    untrusted: true,
+    contentMeta: {
+      sourceUrl,
+      contentType: "browser-aria-tree",
+      capturedAt: (/* @__PURE__ */ new Date()).toISOString()
+    }
+  };
 }
-async function getPageErrorsViaPlaywright(opts) {
-  const state = ensurePageState(await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId }));
-  const errors = [...state.errors];
-  if (opts.clear) state.errors = [];
-  return { errors };
+function axValue(v) {
+  if (!v || typeof v !== "object") return "";
+  const value = v.value;
+  if (typeof value === "string") return value;
+  if (typeof value === "number" || typeof value === "boolean") return String(value);
+  return "";
 }
-async function getNetworkRequestsViaPlaywright(opts) {
-  const state = ensurePageState(await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId }));
-  const raw = [...state.requests];
-  const filter = typeof opts.filter === "string" ? opts.filter.trim() : "";
-  const requests = filter ? raw.filter((r) => r.url.includes(filter)) : raw;
-  if (opts.clear) {
-    state.requests = [];
-    state.requestIds = /* @__PURE__ */ new WeakMap();
+function formatAriaNodes(nodes, limit) {
+  const byId = /* @__PURE__ */ new Map();
+  for (const n of nodes) if (n.nodeId) byId.set(n.nodeId, n);
+  const referenced = /* @__PURE__ */ new Set();
+  for (const n of nodes) for (const c of n.childIds ?? []) referenced.add(c);
+  const root = nodes.find((n) => n.nodeId !== "" && !referenced.has(n.nodeId)) ?? nodes[0];
+  if (root.nodeId === "") return [];
+  const out = [];
+  const stack = [{ id: root.nodeId, depth: 0 }];
+  while (stack.length && out.length < limit) {
+    const popped = stack.pop();
+    if (!popped) break;
+    const { id, depth } = popped;
+    const n = byId.get(id);
+    if (!n) continue;
+    const role = axValue(n.role);
+    const name = axValue(n.name);
+    const value = axValue(n.value);
+    const description = axValue(n.description);
+    const ref = `ax${String(out.length + 1)}`;
+    out.push({
+      ref,
+      role: role || "unknown",
+      name: name || "",
+      ...value ? { value } : {},
+      ...description ? { description } : {},
+      ...typeof n.backendDOMNodeId === "number" ? { backendDOMNodeId: n.backendDOMNodeId } : {},
+      depth
+    });
+    const children = (n.childIds ?? []).filter((c) => byId.has(c));
+    for (let i = children.length - 1; i >= 0; i--) {
+      if (children[i]) stack.push({ id: children[i], depth: depth + 1 });
+    }
   }
-  return { requests };
+  return out;
 }
 
 // src/storage/index.ts
@@ -3797,9 +4201,9 @@ async function cookiesSetViaPlaywright(opts) {
   const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
   ensurePageState(page);
   const cookie = opts.cookie;
-  if (!cookie.name || cookie.value === void 0) throw new Error("cookie name and value are required");
-  const hasUrl = typeof cookie.url === "string" && cookie.url.trim();
-  const hasDomainPath = typeof cookie.domain === "string" && cookie.domain.trim() && typeof cookie.path === "string" && cookie.path.trim();
+  if (cookie.name === "") throw new Error("cookie name and value are required");
+  const hasUrl = typeof cookie.url === "string" && cookie.url.trim() !== "";
+  const hasDomainPath = typeof cookie.domain === "string" && cookie.domain.trim() !== "" && typeof cookie.path === "string" && cookie.path.trim() !== "";
   if (!hasUrl && !hasDomainPath) throw new Error("cookie requires url, or domain+path");
   await page.context().addCookies([cookie]);
 }
@@ -3815,33 +4219,33 @@ async function storageGetViaPlaywright(opts) {
     values: await page.evaluate(
       ({ kind, key }) => {
         const store = kind === "session" ? window.sessionStorage : window.localStorage;
-        if (key) {
+        if (key !== void 0 && key !== "") {
           const value = store.getItem(key);
           return value === null ? {} : { [key]: value };
         }
         const out = {};
         for (let i = 0; i < store.length; i++) {
           const k = store.key(i);
-          if (!k) continue;
+          if (k === null || k === "") continue;
           const v = store.getItem(k);
           if (v !== null) out[k] = v;
         }
         return out;
       },
       { kind: opts.kind, key: opts.key }
-    ) ?? {}
+    )
   };
 }
 async function storageSetViaPlaywright(opts) {
-  const key = String(opts.key ?? "");
-  if (!key) throw new Error("key is required");
+  const key = opts.key;
+  if (key === "") throw new Error("key is required");
   const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
   ensurePageState(page);
   await page.evaluate(
     ({ kind, key: k, value }) => {
       (kind === "session" ? window.sessionStorage : window.localStorage).setItem(k, value);
     },
-    { kind: opts.kind, key, value: String(opts.value ?? "") }
+    { kind: opts.kind, key, value: opts.value }
   );
 }
 async function storageClearViaPlaywright(opts) {
@@ -3908,8 +4312,10 @@ var CrawlPage = class {
         }
       });
     }
-    if (opts?.selector || opts?.frameSelector) {
-      throw new Error('selector and frameSelector are only supported in role mode. Use { mode: "role" } or omit these options.');
+    if (opts?.selector !== void 0 && opts.selector !== "" || opts?.frameSelector !== void 0 && opts.frameSelector !== "") {
+      throw new Error(
+        'selector and frameSelector are only supported in role mode. Use { mode: "role" } or omit these options.'
+      );
     }
     return snapshotAi({
       cdpUrl: this.cdpUrl,
@@ -4148,6 +4554,22 @@ var CrawlPage = class {
       timeoutMs: opts?.timeoutMs
     });
   }
+  /**
+   * Execute multiple browser actions in sequence.
+   *
+   * @param actions - Array of actions to execute
+   * @param opts - Options (stopOnError: stop on first failure, default true)
+   * @returns Array of per-action results
+   */
+  async batch(actions, opts) {
+    return batchViaPlaywright({
+      cdpUrl: this.cdpUrl,
+      targetId: this.targetId,
+      actions,
+      stopOnError: opts?.stopOnError,
+      evaluateEnabled: opts?.evaluateEnabled
+    });
+  }
   // ── Keyboard ─────────────────────────────────────────────────
   /**
    * Press a keyboard key or key combination.
@@ -4764,8 +5186,8 @@ var BrowserClaw = class _BrowserClaw {
    */
   static async launch(opts = {}) {
     const chrome = await launchChrome(opts);
-    const cdpUrl = `http://127.0.0.1:${chrome.cdpPort}`;
-    const ssrfPolicy = opts.allowInternal ? { ...opts.ssrfPolicy, dangerouslyAllowPrivateNetwork: true } : opts.ssrfPolicy;
+    const cdpUrl = `http://127.0.0.1:${String(chrome.cdpPort)}`;
+    const ssrfPolicy = opts.allowInternal === true ? { ...opts.ssrfPolicy, dangerouslyAllowPrivateNetwork: true } : opts.ssrfPolicy;
     return new _BrowserClaw(cdpUrl, chrome, ssrfPolicy);
   }
   /**
@@ -4787,7 +5209,7 @@ var BrowserClaw = class _BrowserClaw {
       throw new Error(`Cannot connect to Chrome at ${cdpUrl}. Is Chrome running with --remote-debugging-port?`);
     }
     await connectBrowser(cdpUrl, opts?.authToken);
-    const ssrfPolicy = opts?.allowInternal ? { ...opts.ssrfPolicy, dangerouslyAllowPrivateNetwork: true } : opts?.ssrfPolicy;
+    const ssrfPolicy = opts?.allowInternal === true ? { ...opts.ssrfPolicy, dangerouslyAllowPrivateNetwork: true } : opts?.ssrfPolicy;
     return new _BrowserClaw(cdpUrl, null, ssrfPolicy);
   }
   /**
@@ -4813,10 +5235,10 @@ var BrowserClaw = class _BrowserClaw {
    */
   async currentPage() {
     const { browser } = await connectBrowser(this.cdpUrl);
-    const pages = await getAllPages(browser);
+    const pages = getAllPages(browser);
     if (!pages.length) throw new Error("No pages available. Use browser.open(url) to create a tab.");
     const tid = await pageTargetId(pages[0]).catch(() => null);
-    if (!tid) throw new Error("Failed to get targetId for the current page.");
+    if (tid === null || tid === "") throw new Error("Failed to get targetId for the current page.");
     return new CrawlPage(this.cdpUrl, tid, this.ssrfPolicy);
   }
   /**
@@ -4875,22 +5297,36 @@ var BrowserClaw = class _BrowserClaw {
 };
 
 exports.BrowserClaw = BrowserClaw;
+exports.BrowserTabNotFoundError = BrowserTabNotFoundError;
 exports.CrawlPage = CrawlPage;
 exports.InvalidBrowserNavigationUrlError = InvalidBrowserNavigationUrlError;
 exports.assertBrowserNavigationAllowed = assertBrowserNavigationAllowed;
 exports.assertBrowserNavigationRedirectChainAllowed = assertBrowserNavigationRedirectChainAllowed;
 exports.assertBrowserNavigationResultAllowed = assertBrowserNavigationResultAllowed;
+exports.assertSafeUploadPaths = assertSafeUploadPaths;
+exports.batchViaPlaywright = batchViaPlaywright;
 exports.createPinnedLookup = createPinnedLookup;
 exports.ensureContextState = ensureContextState;
+exports.executeSingleAction = executeSingleAction;
 exports.forceDisconnectPlaywrightForTarget = forceDisconnectPlaywrightForTarget;
 exports.getChromeWebSocketUrl = getChromeWebSocketUrl;
+exports.getRestoredPageForTarget = getRestoredPageForTarget;
 exports.isChromeCdpReady = isChromeCdpReady;
 exports.isChromeReachable = isChromeReachable;
 exports.normalizeCdpHttpBaseForJsonEndpoints = normalizeCdpHttpBaseForJsonEndpoints;
+exports.parseRoleRef = parseRoleRef;
+exports.requireRef = requireRef;
+exports.requireRefOrSelector = requireRefOrSelector;
 exports.requiresInspectableBrowserNavigationRedirects = requiresInspectableBrowserNavigationRedirects;
+exports.resolveBoundedDelayMs = resolveBoundedDelayMs;
+exports.resolveInteractionTimeoutMs = resolveInteractionTimeoutMs;
+exports.resolvePageByTargetIdOrThrow = resolvePageByTargetIdOrThrow;
 exports.resolvePinnedHostnameWithPolicy = resolvePinnedHostnameWithPolicy;
+exports.resolveStrictExistingUploadPaths = resolveStrictExistingUploadPaths;
 exports.sanitizeUntrustedFileName = sanitizeUntrustedFileName;
 exports.withBrowserNavigationPolicy = withBrowserNavigationPolicy;
+exports.withPageScopedCdpClient = withPageScopedCdpClient;
+exports.withPlaywrightPageCdpSession = withPlaywrightPageCdpSession;
 exports.writeViaSiblingTempPath = writeViaSiblingTempPath;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map