browserclaw 0.11.2 → 0.11.3

package/dist/index.cjs

@@ -1782,137 +1782,10 @@ 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();
@@ -1932,56 +1805,6 @@ 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 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);
-}
 function ensureContextState(context) {
   const existing = contextStates.get(context);
   if (existing) return existing;
@@ -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--) {
@@ -2119,77 +1934,353 @@ function ensurePageState(page) {
       observedPages.delete(page);
     });
   }
-  return state;
+  return state;
+}
+function setDialogHandlerOnPage(page, handler) {
+  const state = ensurePageState(page);
+  state.dialogHandler = handler;
+}
+function applyStealthToPage(page) {
+  page.evaluate(STEALTH_SCRIPT).catch((e) => {
+    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) {
+  if (observedContexts.has(context)) return;
+  observedContexts.add(context);
+  ensureContextState(context);
+  context.addInitScript(STEALTH_SCRIPT).catch((e) => {
+    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);
+    applyStealthToPage(page);
+  }
+  context.on("page", (page) => {
+    ensurePageState(page);
+    applyStealthToPage(page);
+  });
+}
+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;
+  roleRefsByTarget.set(roleRefsKey(opts.cdpUrl, targetId), {
+    refs: opts.refs,
+    ...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 === true) break;
+    roleRefsByTarget.delete(first.value);
+  }
+}
+function storeRoleRefsForTarget(opts) {
+  const state = ensurePageState(opts.page);
+  state.roleRefs = opts.refs;
+  state.roleRefsFrameSelector = opts.frameSelector;
+  state.roleRefsMode = opts.mode;
+  if (opts.targetId === void 0 || opts.targetId.trim() === "") return;
+  rememberRoleRefsForTarget({
+    cdpUrl: opts.cdpUrl,
+    targetId: opts.targetId,
+    refs: opts.refs,
+    frameSelector: opts.frameSelector,
+    mode: opts.mode
+  });
+}
+function restoreRoleRefsForTarget(opts) {
+  const targetId = opts.targetId?.trim() ?? "";
+  if (targetId === "") return;
+  const entry = roleRefsByTarget.get(roleRefsKey(opts.cdpUrl, targetId));
+  if (!entry) return;
+  const state = ensurePageState(opts.page);
+  if (state.roleRefs) return;
+  state.roleRefs = entry.refs;
+  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;
+  }
 }
-async function setDialogHandler(opts) {
-  const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
-  const state = ensurePageState(page);
-  state.dialogHandler = opts.handler;
+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?.();
+  }
 }
-function applyStealthToPage(page) {
-  page.evaluate(STEALTH_SCRIPT).catch((e) => {
-    if (process.env.DEBUG !== void 0 && process.env.DEBUG !== "")
-      console.warn("[browserclaw] stealth evaluate failed:", e instanceof Error ? e.message : String(e));
-  });
+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;
 }
-function observeContext(context) {
-  if (observedContexts.has(context)) return;
-  observedContexts.add(context);
-  ensureContextState(context);
-  context.addInitScript(STEALTH_SCRIPT).catch((e) => {
-    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);
-    applyStealthToPage(page);
+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";
   }
-  context.on("page", (page) => {
-    ensurePageState(page);
-    applyStealthToPage(page);
-  });
+};
+var blockedTargetsByCdpUrl = /* @__PURE__ */ new Set();
+var blockedPageRefsByCdpUrl = /* @__PURE__ */ new Map();
+function blockedTargetKey(cdpUrl, targetId) {
+  return `${normalizeCdpUrl(cdpUrl)}::${targetId}`;
 }
-function observeBrowser(browser) {
-  for (const context of browser.contexts()) observeContext(context);
+function isBlockedTarget(cdpUrl, targetId) {
+  const normalized = targetId?.trim() ?? "";
+  if (normalized === "") return false;
+  return blockedTargetsByCdpUrl.has(blockedTargetKey(cdpUrl, normalized));
 }
-function rememberRoleRefsForTarget(opts) {
-  const targetId = opts.targetId.trim();
-  if (targetId === "") return;
-  roleRefsByTarget.set(roleRefsKey(opts.cdpUrl, targetId), {
-    refs: opts.refs,
-    ...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 === true) break;
-    roleRefsByTarget.delete(first.value);
+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 storeRoleRefsForTarget(opts) {
-  const state = ensurePageState(opts.page);
-  state.roleRefs = opts.refs;
-  state.roleRefsFrameSelector = opts.frameSelector;
-  state.roleRefsMode = opts.mode;
-  if (opts.targetId === void 0 || opts.targetId.trim() === "") return;
-  rememberRoleRefsForTarget({
-    cdpUrl: opts.cdpUrl,
-    targetId: opts.targetId,
-    refs: opts.refs,
-    frameSelector: opts.frameSelector,
-    mode: opts.mode
-  });
+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 restoreRoleRefsForTarget(opts) {
-  const targetId = opts.targetId?.trim() ?? "";
-  if (targetId === "") return;
-  const entry = roleRefsByTarget.get(roleRefsKey(opts.cdpUrl, targetId));
-  if (!entry) return;
-  const state = ensurePageState(opts.page);
-  if (state.roleRefs) return;
-  state.roleRefs = entry.refs;
-  state.roleRefsFrameSelector = entry.frameSelector;
-  state.roleRefsMode = entry.mode;
+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);
@@ -2213,9 +2304,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 };
@@ -2479,87 +2568,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 +2598,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;
@@ -3299,7 +3314,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) {
@@ -5067,6 +5082,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();