browserclaw 0.11.2 → 0.11.4

package/dist/index.cjs

@@ -1319,7 +1319,10 @@ function normalizeCdpHttpBaseForJsonEndpoints(cdpUrl) {
     url.pathname = url.pathname.replace(/\/cdp$/, "");
     return url.toString().replace(/\/$/, "");
   } catch {
-    return cdpUrl.replace(/^ws:/, "http:").replace(/^wss:/, "https:").replace(/\/devtools\/browser\/.*$/, "").replace(/\/cdp$/, "").replace(/\/$/, "");
+    let normalized = cdpUrl.replace(/^ws:/, "http:").replace(/^wss:/, "https:");
+    const dtIdx = normalized.indexOf("/devtools/browser/");
+    if (dtIdx >= 0) normalized = normalized.slice(0, dtIdx);
+    return normalized.replace(/\/cdp$/, "").replace(/\/$/, "");
   }
 }
 function appendCdpPath(cdpUrl, cdpPath) {
@@ -1782,205 +1785,25 @@ var STEALTH_SCRIPT = `(function() {
   });
 })()`;
 
-// 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 CDP_SESSION_TIMEOUT_MS = 1e4;
-  const session = await Promise.race([
-    page.context().newCDPSession(page),
-    new Promise((_, reject) => {
-      setTimeout(() => {
-        reject(new Error("newCDPSession timed out after 10s"));
-      }, CDP_SESSION_TIMEOUT_MS);
-    })
-  ]);
-  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 ?? "";
-  return current.includes("localhost") && current.includes("127.0.0.1") && current.includes("[::1]");
-}
-function isLoopbackCdpUrl(url) {
-  try {
-    return isLoopbackHost(new URL(url).hostname);
-  } catch {
-    return false;
-  }
-}
-var NoProxyLeaseManager = class {
-  leaseCount = 0;
-  snapshot = null;
-  acquire(url) {
-    if (!isLoopbackCdpUrl(url) || !hasProxyEnvConfigured()) return null;
-    if (this.leaseCount === 0 && !noProxyAlreadyCoversLocalhost()) {
-      const noProxy = process.env.NO_PROXY;
-      const noProxyLower = process.env.no_proxy;
-      const current = noProxy ?? noProxyLower ?? "";
-      const applied = current ? `${current},${LOOPBACK_ENTRIES}` : LOOPBACK_ENTRIES;
-      process.env.NO_PROXY = applied;
-      process.env.no_proxy = applied;
-      this.snapshot = { noProxy, noProxyLower, applied };
-    }
-    this.leaseCount += 1;
-    let released = false;
-    return () => {
-      if (released) return;
-      released = true;
-      this.release();
-    };
-  }
-  release() {
-    if (this.leaseCount <= 0) return;
-    this.leaseCount -= 1;
-    if (this.leaseCount > 0 || !this.snapshot) return;
-    const { noProxy, noProxyLower, applied } = this.snapshot;
-    const currentNoProxy = process.env.NO_PROXY;
-    const currentNoProxyLower = process.env.no_proxy;
-    if (currentNoProxy === applied && (currentNoProxyLower === applied || currentNoProxyLower === void 0)) {
-      if (noProxy !== void 0) process.env.NO_PROXY = noProxy;
-      else delete process.env.NO_PROXY;
-      if (noProxyLower !== void 0) process.env.no_proxy = noProxyLower;
-      else delete process.env.no_proxy;
-    }
-    this.snapshot = null;
-  }
-};
-var noProxyLeaseManager = new NoProxyLeaseManager();
-async function withNoProxyForCdpUrl(url, fn) {
-  const release = noProxyLeaseManager.acquire(url);
-  try {
-    return await fn();
-  } finally {
-    release?.();
-  }
-}
-new http__default.default.Agent();
-new https__default.default.Agent();
-function getHeadersWithAuth(endpoint, baseHeaders = {}) {
-  const headers = { ...baseHeaders };
-  try {
-    const parsed = new URL(endpoint);
-    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 {
-  }
-  return headers;
-}
-var cachedByCdpUrl = /* @__PURE__ */ new Map();
-var connectingByCdpUrl = /* @__PURE__ */ new Map();
+// src/page-utils.ts
+var MAX_CONSOLE_MESSAGES = 500;
+var MAX_PAGE_ERRORS = 200;
+var MAX_NETWORK_REQUESTS = 500;
 var pageStates = /* @__PURE__ */ new WeakMap();
 var contextStates = /* @__PURE__ */ new WeakMap();
 var observedContexts = /* @__PURE__ */ new WeakSet();
 var observedPages = /* @__PURE__ */ new WeakSet();
-var nextUploadArmId = 0;
-var nextDialogArmId = 0;
-var nextDownloadArmId = 0;
-function bumpUploadArmId() {
-  nextUploadArmId += 1;
-  return nextUploadArmId;
-}
-function bumpDialogArmId() {
-  nextDialogArmId += 1;
-  return nextDialogArmId;
-}
-function bumpDownloadArmId() {
-  nextDownloadArmId += 1;
-  return nextDownloadArmId;
-}
-var BlockedBrowserTargetError = class extends Error {
-  constructor() {
-    super("Browser target is unavailable after SSRF policy blocked its navigation.");
-    this.name = "BlockedBrowserTargetError";
-  }
-};
-var blockedTargetsByCdpUrl = /* @__PURE__ */ new Set();
-var blockedPageRefsByCdpUrl = /* @__PURE__ */ new Map();
-function blockedTargetKey(cdpUrl, targetId) {
-  return `${normalizeCdpUrl(cdpUrl)}::${targetId}`;
+function bumpUploadArmId(state) {
+  state.nextArmIdUpload += 1;
+  return state.nextArmIdUpload;
 }
-function isBlockedTarget(cdpUrl, targetId) {
-  const normalized = targetId?.trim() ?? "";
-  if (normalized === "") return false;
-  return blockedTargetsByCdpUrl.has(blockedTargetKey(cdpUrl, normalized));
+function bumpDialogArmId(state) {
+  state.nextArmIdDialog += 1;
+  return state.nextArmIdDialog;
 }
-function markTargetBlocked(cdpUrl, targetId) {
-  const normalized = targetId?.trim() ?? "";
-  if (normalized === "") return;
-  blockedTargetsByCdpUrl.add(blockedTargetKey(cdpUrl, normalized));
-}
-function clearBlockedTarget(cdpUrl, targetId) {
-  const normalized = targetId?.trim() ?? "";
-  if (normalized === "") return;
-  blockedTargetsByCdpUrl.delete(blockedTargetKey(cdpUrl, normalized));
-}
-function hasBlockedTargetsForCdpUrl(cdpUrl) {
-  const prefix = `${normalizeCdpUrl(cdpUrl)}::`;
-  for (const key of blockedTargetsByCdpUrl) {
-    if (key.startsWith(prefix)) return true;
-  }
-  return false;
-}
-function blockedPageRefsForCdpUrl(cdpUrl) {
-  const normalized = normalizeCdpUrl(cdpUrl);
-  const existing = blockedPageRefsByCdpUrl.get(normalized);
-  if (existing) return existing;
-  const created = /* @__PURE__ */ new WeakSet();
-  blockedPageRefsByCdpUrl.set(normalized, created);
-  return created;
-}
-function isBlockedPageRef(cdpUrl, page) {
-  return blockedPageRefsByCdpUrl.get(normalizeCdpUrl(cdpUrl))?.has(page) ?? false;
-}
-function markPageRefBlocked(cdpUrl, page) {
-  blockedPageRefsForCdpUrl(cdpUrl).add(page);
-}
-function clearBlockedPageRef(cdpUrl, page) {
-  blockedPageRefsByCdpUrl.get(normalizeCdpUrl(cdpUrl))?.delete(page);
+function bumpDownloadArmId(state) {
+  state.nextArmIdDownload += 1;
+  return state.nextArmIdDownload;
 }
 function ensureContextState(context) {
   const existing = contextStates.get(context);
@@ -1989,16 +1812,8 @@ function ensureContextState(context) {
   contextStates.set(context, state);
   return state;
 }
-var roleRefsByTarget = /* @__PURE__ */ new Map();
-var MAX_ROLE_REFS_CACHE = 50;
-var MAX_CONSOLE_MESSAGES = 500;
-var MAX_PAGE_ERRORS = 200;
-var MAX_NETWORK_REQUESTS = 500;
-function normalizeCdpUrl(raw) {
-  return raw.replace(/\/$/, "");
-}
-function roleRefsKey(cdpUrl, targetId) {
-  return `${normalizeCdpUrl(cdpUrl)}::${targetId}`;
+function getPageState(page) {
+  return pageStates.get(page);
 }
 function findNetworkRequestById(state, id) {
   for (let i = state.requests.length - 1; i >= 0; i--) {
@@ -2018,7 +1833,10 @@ function ensurePageState(page) {
     nextRequestId: 0,
     armIdUpload: 0,
     armIdDialog: 0,
-    armIdDownload: 0
+    armIdDownload: 0,
+    nextArmIdUpload: 0,
+    nextArmIdDialog: 0,
+    nextArmIdDownload: 0
   };
   pageStates.set(page, state);
   if (!observedPages.has(page)) {
@@ -2121,10 +1939,9 @@ function ensurePageState(page) {
   }
   return state;
 }
-async function setDialogHandler(opts) {
-  const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
+function setDialogHandlerOnPage(page, handler) {
   const state = ensurePageState(page);
-  state.dialogHandler = opts.handler;
+  state.dialogHandler = handler;
 }
 function applyStealthToPage(page) {
   page.evaluate(STEALTH_SCRIPT).catch((e) => {
@@ -2152,6 +1969,47 @@ function observeContext(context) {
 function observeBrowser(browser) {
   for (const context of browser.contexts()) observeContext(context);
 }
+function toAIFriendlyError(error, selector) {
+  const message = error instanceof Error ? error.message : String(error);
+  if (message.includes("strict mode violation")) {
+    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.`
+    );
+  }
+  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.`
+    );
+  }
+  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.`
+    );
+  }
+  const timeoutMatch = /Timeout (\d+)ms exceeded/.exec(message);
+  if (timeoutMatch) {
+    return new Error(
+      `Element "${selector}" timed out after ${timeoutMatch[1]}ms \u2014 element may be hidden or not interactable. Run a new snapshot to see current page elements.`
+    );
+  }
+  const cleaned = message.replace(/locator\([^)]*\)\./g, "").replace(/waiting for locator\([^)]*\)/g, "").trim();
+  return new Error(cleaned || message);
+}
+function normalizeTimeoutMs(timeoutMs, fallback, maxMs = 12e4) {
+  return Math.max(500, Math.min(maxMs, timeoutMs ?? fallback));
+}
+
+// src/ref-resolver.ts
+var roleRefsByTarget = /* @__PURE__ */ new Map();
+var MAX_ROLE_REFS_CACHE = 50;
+function normalizeCdpUrl(raw) {
+  return raw.replace(/\/$/, "");
+}
+function roleRefsKey(cdpUrl, targetId) {
+  return `${normalizeCdpUrl(cdpUrl)}::${targetId}`;
+}
 function rememberRoleRefsForTarget(opts) {
   const targetId = opts.targetId.trim();
   if (targetId === "") return;
@@ -2191,6 +2049,232 @@ function restoreRoleRefsForTarget(opts) {
   state.roleRefsFrameSelector = entry.frameSelector;
   state.roleRefsMode = entry.mode;
 }
+function clearRoleRefsForCdpUrl(cdpUrl) {
+  const normalized = normalizeCdpUrl(cdpUrl);
+  for (const key of roleRefsByTarget.keys()) {
+    if (key.startsWith(normalized + "::")) roleRefsByTarget.delete(key);
+  }
+}
+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;
+}
+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 (/^e\d+$/.test(normalized)) {
+    const state = getPageState(page);
+    if (state?.roleRefsMode === "aria") {
+      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 !== void 0 && state.roleRefsFrameSelector !== "" ? page.frameLocator(state.roleRefsFrameSelector) : page;
+    const role = info.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}`);
+}
+
+// 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 CDP_SESSION_TIMEOUT_MS = 1e4;
+  const session = await Promise.race([
+    page.context().newCDPSession(page),
+    new Promise((_, reject) => {
+      setTimeout(() => {
+        reject(new Error("newCDPSession timed out after 10s"));
+      }, CDP_SESSION_TIMEOUT_MS);
+    })
+  ]);
+  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 ?? "";
+  return current.includes("localhost") && current.includes("127.0.0.1") && current.includes("[::1]");
+}
+function isLoopbackCdpUrl(url) {
+  try {
+    return isLoopbackHost(new URL(url).hostname);
+  } catch {
+    return false;
+  }
+}
+var envMutexPromise = Promise.resolve();
+async function withNoProxyForCdpUrl(url, fn) {
+  if (!isLoopbackCdpUrl(url) || !hasProxyEnvConfigured()) return fn();
+  const prev = envMutexPromise;
+  let release = () => {
+  };
+  envMutexPromise = new Promise((r) => {
+    release = r;
+  });
+  await prev;
+  if (noProxyAlreadyCoversLocalhost()) {
+    try {
+      return await fn();
+    } finally {
+      release();
+    }
+  }
+  const savedNoProxy = process.env.NO_PROXY;
+  const savedNoProxyLower = process.env.no_proxy;
+  const current = savedNoProxy ?? savedNoProxyLower ?? "";
+  const applied = current ? `${current},${LOOPBACK_ENTRIES}` : LOOPBACK_ENTRIES;
+  process.env.NO_PROXY = applied;
+  process.env.no_proxy = applied;
+  try {
+    return await fn();
+  } finally {
+    if (process.env.NO_PROXY === applied) {
+      if (savedNoProxy !== void 0) process.env.NO_PROXY = savedNoProxy;
+      else delete process.env.NO_PROXY;
+    }
+    if (process.env.no_proxy === applied) {
+      if (savedNoProxyLower !== void 0) process.env.no_proxy = savedNoProxyLower;
+      else delete process.env.no_proxy;
+    }
+    release();
+  }
+}
+new http__default.default.Agent();
+new https__default.default.Agent();
+function getHeadersWithAuth(endpoint, baseHeaders = {}) {
+  const headers = { ...baseHeaders };
+  try {
+    const parsed = new URL(endpoint);
+    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 {
+  }
+  return headers;
+}
+var cachedByCdpUrl = /* @__PURE__ */ new Map();
+var connectingByCdpUrl = /* @__PURE__ */ new Map();
+var BlockedBrowserTargetError = class extends Error {
+  constructor() {
+    super("Browser target is unavailable after SSRF policy blocked its navigation.");
+    this.name = "BlockedBrowserTargetError";
+  }
+};
+var blockedTargetsByCdpUrl = /* @__PURE__ */ new Set();
+var blockedPageRefsByCdpUrl = /* @__PURE__ */ new Map();
+function blockedTargetKey(cdpUrl, targetId) {
+  return `${normalizeCdpUrl(cdpUrl)}::${targetId}`;
+}
+function isBlockedTarget(cdpUrl, targetId) {
+  const normalized = targetId?.trim() ?? "";
+  if (normalized === "") return false;
+  return blockedTargetsByCdpUrl.has(blockedTargetKey(cdpUrl, normalized));
+}
+function markTargetBlocked(cdpUrl, targetId) {
+  const normalized = targetId?.trim() ?? "";
+  if (normalized === "") return;
+  blockedTargetsByCdpUrl.add(blockedTargetKey(cdpUrl, normalized));
+}
+function clearBlockedTarget(cdpUrl, targetId) {
+  const normalized = targetId?.trim() ?? "";
+  if (normalized === "") return;
+  blockedTargetsByCdpUrl.delete(blockedTargetKey(cdpUrl, normalized));
+}
+function hasBlockedTargetsForCdpUrl(cdpUrl) {
+  const prefix = `${normalizeCdpUrl(cdpUrl)}::`;
+  for (const key of blockedTargetsByCdpUrl) {
+    if (key.startsWith(prefix)) return true;
+  }
+  return false;
+}
+function blockedPageRefsForCdpUrl(cdpUrl) {
+  const normalized = normalizeCdpUrl(cdpUrl);
+  const existing = blockedPageRefsByCdpUrl.get(normalized);
+  if (existing) return existing;
+  const created = /* @__PURE__ */ new WeakSet();
+  blockedPageRefsByCdpUrl.set(normalized, created);
+  return created;
+}
+function isBlockedPageRef(cdpUrl, page) {
+  return blockedPageRefsByCdpUrl.get(normalizeCdpUrl(cdpUrl))?.has(page) ?? false;
+}
+function markPageRefBlocked(cdpUrl, page) {
+  blockedPageRefsForCdpUrl(cdpUrl).add(page);
+}
+function clearBlockedPageRef(cdpUrl, page) {
+  blockedPageRefsByCdpUrl.get(normalizeCdpUrl(cdpUrl))?.delete(page);
+}
+async function setDialogHandler(opts) {
+  const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
+  setDialogHandlerOnPage(page, opts.handler);
+}
 async function connectBrowser(cdpUrl, authToken) {
   const normalized = normalizeCdpUrl(cdpUrl);
   const existing_cached = cachedByCdpUrl.get(normalized);
@@ -2213,9 +2297,7 @@ async function connectBrowser(cdpUrl, authToken) {
         const onDisconnected = () => {
           if (cachedByCdpUrl.get(normalized)?.browser === browser) {
             cachedByCdpUrl.delete(normalized);
-            for (const key of roleRefsByTarget.keys()) {
-              if (key.startsWith(normalized + "::")) roleRefsByTarget.delete(key);
-            }
+            clearRoleRefsForCdpUrl(normalized);
           }
         };
         const connected = { browser, cdpUrl: normalized, onDisconnected };
@@ -2347,7 +2429,7 @@ async function tryTerminateExecutionViaCdp(cdpUrl, targetId) {
     };
   });
 }
-async function forceDisconnectPlaywrightForTarget(opts) {
+async function forceDisconnectPlaywrightConnection(opts) {
   const normalized = normalizeCdpUrl(opts.cdpUrl);
   const cur = cachedByCdpUrl.get(normalized);
   if (!cur) return;
@@ -2364,6 +2446,7 @@ async function forceDisconnectPlaywrightForTarget(opts) {
   cur.browser.close().catch(() => {
   });
 }
+var forceDisconnectPlaywrightForTarget = forceDisconnectPlaywrightConnection;
 function getAllPages(browser) {
   return browser.contexts().flatMap((c) => c.pages());
 }
@@ -2479,87 +2562,12 @@ async function resolvePageByTargetIdOrThrow(opts) {
   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 (/^e\d+$/.test(normalized)) {
-    const state = pageStates.get(page);
-    if (state?.roleRefsMode === "aria") {
-      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 !== void 0 && state.roleRefsFrameSelector !== "" ? page.frameLocator(state.roleRefsFrameSelector) : page;
-    const role = info.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}`);
-}
-function toAIFriendlyError(error, selector) {
-  const message = error instanceof Error ? error.message : String(error);
-  if (message.includes("strict mode violation")) {
-    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.`
-    );
-  }
-  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.`
-    );
-  }
-  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.`
-    );
-  }
-  const timeoutMatch = /Timeout (\d+)ms exceeded/.exec(message);
-  if (timeoutMatch) {
-    return new Error(
-      `Element "${selector}" timed out after ${timeoutMatch[1]}ms \u2014 element may be hidden or not interactable. Run a new snapshot to see current page elements.`
-    );
-  }
-  const cleaned = message.replace(/locator\([^)]*\)\./g, "").replace(/waiting for locator\([^)]*\)/g, "").trim();
-  return new Error(cleaned || message);
-}
-function normalizeTimeoutMs(timeoutMs, fallback, maxMs = 12e4) {
-  return Math.max(500, Math.min(maxMs, timeoutMs ?? fallback));
-}
 
 // src/actions/evaluate.ts
 async function evaluateInAllFramesViaPlaywright(opts) {
@@ -2584,7 +2592,8 @@ async function evaluateInAllFramesViaPlaywright(opts) {
         frameName: frame.name(),
         result
       });
-    } catch {
+    } catch (err) {
+      console.warn("[browserclaw] frame evaluate failed:", err instanceof Error ? err.message : String(err));
     }
   }
   return results;
@@ -2670,7 +2679,7 @@ async function evaluateViaPlaywright(opts) {
   }
   if (signal !== void 0) {
     const disconnect = () => {
-      forceDisconnectPlaywrightForTarget({
+      forceDisconnectPlaywrightConnection({
         cdpUrl: opts.cdpUrl,
         targetId: opts.targetId}).catch(() => {
       });
@@ -2737,7 +2746,6 @@ 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_KEYS2 = ["HTTP_PROXY", "HTTPS_PROXY", "ALL_PROXY", "http_proxy", "https_proxy", "all_proxy"];
 var BLOCKED_HOSTNAMES = /* @__PURE__ */ new Set(["localhost", "localhost.localdomain", "metadata.google.internal"]);
 function isAllowedNonNetworkNavigationUrl(parsed) {
   return SAFE_NON_NETWORK_URLS.has(parsed.href);
@@ -2745,13 +2753,6 @@ function isAllowedNonNetworkNavigationUrl(parsed) {
 function isPrivateNetworkAllowedByPolicy(policy) {
   return policy?.dangerouslyAllowPrivateNetwork === true || policy?.allowPrivateNetwork === true;
 }
-function hasProxyEnvConfigured2(env = process.env) {
-  for (const key of PROXY_ENV_KEYS2) {
-    const value = env[key];
-    if (typeof value === "string" && value.trim().length > 0) return true;
-  }
-  return false;
-}
 function normalizeHostname(hostname) {
   let h = hostname.trim().toLowerCase();
   if (h.startsWith("[") && h.endsWith("]")) h = h.slice(1, -1);
@@ -3062,7 +3063,7 @@ async function assertBrowserNavigationAllowed(opts) {
     if (isAllowedNonNetworkNavigationUrl(parsed)) return;
     throw new InvalidBrowserNavigationUrlError(`Navigation blocked: unsupported protocol "${parsed.protocol}"`);
   }
-  if (hasProxyEnvConfigured2() && !isPrivateNetworkAllowedByPolicy(opts.ssrfPolicy)) {
+  if (hasProxyEnvConfigured() && !isPrivateNetworkAllowedByPolicy(opts.ssrfPolicy)) {
     throw new InvalidBrowserNavigationUrlError(
       "Navigation blocked: strict browser SSRF policy cannot be enforced while env proxy variables are set"
     );
@@ -3299,7 +3300,7 @@ async function pressAndHoldViaCdp(opts) {
 async function clickByTextViaPlaywright(opts) {
   const page = await getRestoredPageForTarget(opts);
   const timeout = resolveInteractionTimeoutMs(opts.timeoutMs);
-  const locator = page.getByText(opts.text, { exact: opts.exact }).and(page.locator(":visible")).or(page.getByTitle(opts.text, { exact: opts.exact })).first();
+  const locator = page.getByText(opts.text, { exact: opts.exact }).or(page.getByTitle(opts.text, { exact: opts.exact })).and(page.locator(":visible")).first();
   try {
     await locator.click({ timeout, button: opts.button, modifiers: opts.modifiers });
   } catch (err) {
@@ -3517,7 +3518,7 @@ async function armDialogViaPlaywright(opts) {
   const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
   const state = ensurePageState(page);
   const timeout = normalizeTimeoutMs(opts.timeoutMs, 12e4);
-  state.armIdDialog = bumpDialogArmId();
+  state.armIdDialog = bumpDialogArmId(state);
   const armId = state.armIdDialog;
   page.waitForEvent("dialog", { timeout }).then(async (dialog) => {
     if (state.armIdDialog !== armId) return;
@@ -3535,7 +3536,7 @@ async function armFileUploadViaPlaywright(opts) {
   const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
   const state = ensurePageState(page);
   const timeout = normalizeTimeoutMs(opts.timeoutMs, 12e4);
-  state.armIdUpload = bumpUploadArmId();
+  state.armIdUpload = bumpUploadArmId(state);
   const armId = state.armIdUpload;
   page.waitForEvent("filechooser", { timeout }).then(async (fileChooser) => {
     if (state.armIdUpload !== armId) return;
@@ -3695,7 +3696,7 @@ async function navigateViaPlaywright(opts) {
     response = await navigate();
   } catch (err) {
     if (!isRetryableNavigateError(err)) throw err;
-    await forceDisconnectPlaywrightForTarget({
+    await forceDisconnectPlaywrightConnection({
       cdpUrl: opts.cdpUrl,
       targetId: opts.targetId}).catch(() => {
     });
@@ -3837,18 +3838,12 @@ async function resizeViewportViaPlaywright(opts) {
 
 // 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));
+    await page.waitForTimeout(resolveBoundedDelayMs(opts.timeMs, "wait timeMs", MAX_WAIT_TIME_MS));
   }
   if (opts.text !== void 0 && opts.text !== "") {
     await page.waitForFunction((text) => (document.body?.innerText ?? "").includes(text), opts.text, { timeout });
@@ -4105,7 +4100,7 @@ async function downloadViaPlaywright(opts) {
   const timeout = normalizeTimeoutMs(opts.timeoutMs, 12e4);
   const outPath = opts.path.trim();
   if (!outPath) throw new Error("path is required");
-  state.armIdDownload = bumpDownloadArmId();
+  state.armIdDownload = bumpDownloadArmId(state);
   const armId = state.armIdDownload;
   const waiter = createPageDownloadWaiter(page, timeout);
   try {
@@ -4125,7 +4120,7 @@ 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();
+  state.armIdDownload = bumpDownloadArmId(state);
   const armId = state.armIdDownload;
   const waiter = createPageDownloadWaiter(page, timeout);
   try {
@@ -5067,6 +5062,7 @@ function axValue(v) {
   return "";
 }
 function formatAriaNodes(nodes, limit) {
+  if (nodes.length === 0) return [];
   const byId = /* @__PURE__ */ new Map();
   for (const n of nodes) if (n.nodeId) byId.set(n.nodeId, n);
   const referenced = /* @__PURE__ */ new Set();
@@ -6575,6 +6571,7 @@ exports.createPinnedLookup = createPinnedLookup;
 exports.detectChallengeViaPlaywright = detectChallengeViaPlaywright;
 exports.ensureContextState = ensureContextState;
 exports.executeSingleAction = executeSingleAction;
+exports.forceDisconnectPlaywrightConnection = forceDisconnectPlaywrightConnection;
 exports.forceDisconnectPlaywrightForTarget = forceDisconnectPlaywrightForTarget;
 exports.getChromeWebSocketUrl = getChromeWebSocketUrl;
 exports.getRestoredPageForTarget = getRestoredPageForTarget;