browserclaw 0.10.6 → 0.11.1

package/dist/index.js

@@ -37,9 +37,9 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
   mod
 ));
 
-// ../../../node_modules/ipaddr.js/lib/ipaddr.js
+// node_modules/ipaddr.js/lib/ipaddr.js
 var require_ipaddr = __commonJS({
-  "../../../node_modules/ipaddr.js/lib/ipaddr.js"(exports$1, module) {
+  "node_modules/ipaddr.js/lib/ipaddr.js"(exports$1, module) {
     (function(root) {
       const ipv4Part = "(0?\\d+|0x[a-f0-9]+)";
       const ipv4Regexes = {
@@ -835,6 +835,10 @@ var CHROMIUM_BUNDLE_IDS = /* @__PURE__ */ new Set([
   "com.microsoft.EdgeBeta",
   "com.microsoft.EdgeDev",
   "com.microsoft.EdgeCanary",
+  "com.microsoft.edgemac",
+  "com.microsoft.edgemac.beta",
+  "com.microsoft.edgemac.dev",
+  "com.microsoft.edgemac.canary",
   "org.chromium.Chromium",
   "com.vivaldi.Vivaldi",
   "com.operasoftware.Opera",
@@ -903,12 +907,12 @@ function fileExists(filePath) {
     return false;
   }
 }
-function execText(command, args, timeoutMs = 1200) {
+function execText(command, args, timeoutMs = 1200, maxBuffer = 1024 * 1024) {
   try {
     const output = execFileSync(command, args, {
       timeout: timeoutMs,
       encoding: "utf8",
-      maxBuffer: 1024 * 1024
+      maxBuffer
     });
     return output.trim() || null;
   } catch {
@@ -944,7 +948,12 @@ function detectDefaultBrowserBundleIdMac() {
     "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);
+  const handlersRaw = execText(
+    "/usr/bin/plutil",
+    ["-extract", "LSHandlers", "json", "-o", "-", "--", plistPath],
+    2e3,
+    5 * 1024 * 1024
+  );
   if (handlersRaw === null) return null;
   let handlers;
   try {
@@ -996,6 +1005,34 @@ function findChromeMac() {
     }
   ]);
 }
+function splitExecLine(line) {
+  const tokens = [];
+  let current = "";
+  let inQuotes = false;
+  let quoteChar = "";
+  for (const ch of line) {
+    if ((ch === '"' || ch === "'") && (!inQuotes || ch === quoteChar)) {
+      if (inQuotes) {
+        inQuotes = false;
+        quoteChar = "";
+      } else {
+        inQuotes = true;
+        quoteChar = ch;
+      }
+      continue;
+    }
+    if (!inQuotes && /\s/.test(ch)) {
+      if (current) {
+        tokens.push(current);
+        current = "";
+      }
+      continue;
+    }
+    current += ch;
+  }
+  if (current) tokens.push(current);
+  return tokens;
+}
 function detectDefaultChromiumLinux() {
   const desktopId = execText("xdg-settings", ["get", "default-web-browser"]) ?? execText("xdg-mime", ["query", "default", "x-scheme-handler/http"]);
   if (desktopId === null) return null;
@@ -1027,10 +1064,10 @@ function detectDefaultChromiumLinux() {
   } catch {
   }
   if (execLine === null) return null;
-  const tokens = execLine.split(/\s+/);
+  const tokens = splitExecLine(execLine);
   let command = null;
   for (const token of tokens) {
-    if (!token || token === "env" || token.includes("=") && !token.startsWith("/")) continue;
+    if (!token || token === "env" || token.includes("=") && !token.startsWith("/") && !token.includes("\\")) continue;
     command = token.replace(/^["']|["']$/g, "");
     break;
   }
@@ -1087,6 +1124,49 @@ function findChromeWindows() {
   candidates.push({ kind: "edge", path: j(programFilesX86, "Microsoft", "Edge", "Application", "msedge.exe") });
   return findFirstExe(candidates);
 }
+function readWindowsProgId() {
+  const output = execText("reg", [
+    "query",
+    "HKCU\\Software\\Microsoft\\Windows\\Shell\\Associations\\UrlAssociations\\http\\UserChoice",
+    "/v",
+    "ProgId"
+  ]);
+  if (output === null) return null;
+  return /ProgId\s+REG_\w+\s+(.+)$/im.exec(output)?.[1]?.trim() ?? null;
+}
+function readWindowsCommandForProgId(progId) {
+  const output = execText("reg", [
+    "query",
+    progId === "http" ? "HKCR\\http\\shell\\open\\command" : `HKCR\\${progId}\\shell\\open\\command`,
+    "/ve"
+  ]);
+  if (output === null) return null;
+  return /REG_\w+\s+(.+)$/im.exec(output)?.[1]?.trim() ?? null;
+}
+function expandWindowsEnvVars(value) {
+  return value.replace(/%([^%]+)%/g, (_match, name) => {
+    const key = name.trim();
+    return key !== "" ? process.env[key] ?? `%${key}%` : _match;
+  });
+}
+function extractWindowsExecutablePath(command) {
+  const quoted = /"([^"]+\.exe)"/i.exec(command);
+  if (quoted?.[1] !== void 0) return quoted[1];
+  const unquoted = /([^\s]+\.exe)/i.exec(command);
+  if (unquoted?.[1] !== void 0) return unquoted[1];
+  return null;
+}
+function detectDefaultChromiumWindows() {
+  const progId = readWindowsProgId();
+  const command = (progId !== null ? readWindowsCommandForProgId(progId) : null) ?? readWindowsCommandForProgId("http");
+  if (command === null) return null;
+  const exePath = extractWindowsExecutablePath(expandWindowsEnvVars(command));
+  if (exePath === null) return null;
+  if (!fileExists(exePath)) return null;
+  const exeName = path.win32.basename(exePath).toLowerCase();
+  if (!CHROMIUM_EXE_NAMES.has(exeName)) return null;
+  return { kind: inferKindFromExeName(exeName), path: exePath };
+}
 function resolveBrowserExecutable(opts) {
   if (opts?.executablePath !== void 0 && opts.executablePath !== "") {
     if (!fileExists(opts.executablePath)) throw new Error(`executablePath not found: ${opts.executablePath}`);
@@ -1095,7 +1175,7 @@ function resolveBrowserExecutable(opts) {
   const platform = process.platform;
   if (platform === "darwin") return detectDefaultChromiumMac() ?? findChromeMac();
   if (platform === "linux") return detectDefaultChromiumLinux() ?? findChromeLinux();
-  if (platform === "win32") return findChromeWindows();
+  if (platform === "win32") return detectDefaultChromiumWindows() ?? findChromeWindows();
   return null;
 }
 async function ensurePortAvailable(port) {
@@ -1185,7 +1265,8 @@ function isWebSocketUrl(url) {
   }
 }
 function isLoopbackHost(hostname) {
-  return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "::1" || hostname === "[::1]";
+  const h = hostname.replace(/\.+$/, "");
+  return h === "localhost" || h === "127.0.0.1" || h === "::1" || h === "[::1]";
 }
 var PROXY_ENV_KEYS = ["HTTP_PROXY", "HTTPS_PROXY", "ALL_PROXY", "http_proxy", "https_proxy", "all_proxy"];
 function hasProxyEnvConfigured(env = process.env) {
@@ -1377,6 +1458,7 @@ async function launchChrome(opts = {}) {
   const spawnChrome = () => {
     const args = [
       `--remote-debugging-port=${String(cdpPort)}`,
+      "--remote-debugging-address=127.0.0.1",
       `--user-data-dir=${userDataDir}`,
       "--no-first-run",
       "--no-default-browser-check",
@@ -1395,6 +1477,9 @@ async function launchChrome(opts = {}) {
     if (opts.noSandbox === true) {
       args.push("--no-sandbox", "--disable-setuid-sandbox");
     }
+    if (opts.ignoreHTTPSErrors === true) {
+      args.push("--ignore-certificate-errors");
+    }
     if (process.platform === "linux") args.push("--disable-dev-shm-usage");
     const extraArgs = Array.isArray(opts.chromeArgs) ? opts.chromeArgs.filter((a) => typeof a === "string" && a.trim().length > 0) : [];
     if (extraArgs.length) args.push(...extraArgs);
@@ -1715,7 +1800,15 @@ function appendCdpPath2(cdpUrl, cdpPath) {
   }
 }
 async function withPlaywrightPageCdpSession(page, fn) {
-  const session = await page.context().newCDPSession(page);
+  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 {
@@ -1825,6 +1918,56 @@ 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;
@@ -2265,11 +2408,43 @@ async function findPageByTargetId(browser, targetId, cdpUrl) {
   if (!resolvedViaCdp && pages.length === 1) return pages[0] ?? null;
   return null;
 }
+async function partitionAccessiblePages(opts) {
+  const accessible = [];
+  let blockedCount = 0;
+  for (const page of opts.pages) {
+    if (isBlockedPageRef(opts.cdpUrl, page)) {
+      blockedCount += 1;
+      continue;
+    }
+    const targetId = await pageTargetId(page).catch(() => null);
+    if (targetId === null || targetId === "") {
+      if (hasBlockedTargetsForCdpUrl(opts.cdpUrl)) {
+        blockedCount += 1;
+        continue;
+      }
+      accessible.push(page);
+      continue;
+    }
+    if (isBlockedTarget(opts.cdpUrl, targetId)) {
+      blockedCount += 1;
+      continue;
+    }
+    accessible.push(page);
+  }
+  return { accessible, blockedCount };
+}
 async function getPageForTargetId(opts) {
+  if (opts.targetId !== void 0 && opts.targetId !== "" && isBlockedTarget(opts.cdpUrl, opts.targetId))
+    throw new BlockedBrowserTargetError();
   const { browser } = await connectBrowser(opts.cdpUrl);
   const pages = getAllPages(browser);
   if (!pages.length) throw new Error("No pages available in the connected browser.");
-  const first = pages[0];
+  const { accessible, blockedCount } = await partitionAccessiblePages({ cdpUrl: opts.cdpUrl, pages });
+  if (!accessible.length) {
+    if (blockedCount > 0) throw new BlockedBrowserTargetError();
+    throw new Error("No pages available in the connected browser.");
+  }
+  const first = accessible[0];
   if (opts.targetId === void 0 || opts.targetId === "") return first;
   const found = await findPageByTargetId(browser, opts.targetId, opts.cdpUrl);
   if (!found) {
@@ -2278,6 +2453,10 @@ async function getPageForTargetId(opts) {
       `Tab not found (targetId: ${opts.targetId}). Call browser.tabs() to list open tabs.`
     );
   }
+  if (isBlockedPageRef(opts.cdpUrl, found)) throw new BlockedBrowserTargetError();
+  const foundTargetId = await pageTargetId(found).catch(() => null);
+  if (foundTargetId !== null && foundTargetId !== "" && isBlockedTarget(opts.cdpUrl, foundTargetId))
+    throw new BlockedBrowserTargetError();
   return found;
 }
 async function resolvePageByTargetIdOrThrow(opts) {
@@ -2355,7 +2534,14 @@ function toAIFriendlyError(error, selector) {
       `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);
+  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));
@@ -3053,7 +3239,19 @@ function requiresInspectableBrowserNavigationRedirects(ssrfPolicy) {
 
 // src/actions/interaction.ts
 var MAX_CLICK_DELAY_MS = 5e3;
-var CHECKABLE_ROLES = /* @__PURE__ */ new Set(["menuitemcheckbox", "menuitemradio", "checkbox", "switch"]);
+var DEFAULT_SCROLL_TIMEOUT_MS = 2e4;
+var CHECKABLE_ROLES = /* @__PURE__ */ new Set(["menuitemcheckbox", "menuitemradio", "checkbox", "radio", "switch"]);
+async function setCheckedViaEvaluate(locator, checked) {
+  await locator.evaluate((el, desired) => {
+    const input = el;
+    const desc = Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, "checked");
+    if (desc?.set) desc.set.call(input, desired);
+    else input.checked = desired;
+    input.dispatchEvent(new Event("input", { bubbles: true }));
+    input.dispatchEvent(new Event("change", { bubbles: true }));
+    input.click();
+  }, checked);
+}
 function resolveLocator(page, resolved) {
   if (resolved.ref !== void 0 && resolved.ref !== "") return refLocator(page, resolved.ref);
   const sel = resolved.selector ?? "";
@@ -3067,11 +3265,29 @@ async function mouseClickViaPlaywright(opts) {
     delay: opts.delayMs
   });
 }
+async function pressAndHoldViaCdp(opts) {
+  const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
+  ensurePageState(page);
+  const { x, y } = opts;
+  await withPageScopedCdpClient({
+    cdpUrl: opts.cdpUrl,
+    page,
+    targetId: opts.targetId,
+    fn: async (send) => {
+      await send("Input.dispatchMouseEvent", { type: "mouseMoved", x, y, button: "none" });
+      if (opts.delay !== void 0 && opts.delay !== 0) await new Promise((r) => setTimeout(r, opts.delay));
+      await send("Input.dispatchMouseEvent", { type: "mousePressed", x, y, button: "left", clickCount: 1 });
+      if (opts.holdMs !== void 0 && opts.holdMs !== 0) await new Promise((r) => setTimeout(r, opts.holdMs));
+      await send("Input.dispatchMouseEvent", { type: "mouseReleased", x, y, button: "left", clickCount: 1 });
+    }
+  });
+}
 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();
   try {
-    await page.getByText(opts.text, { exact: opts.exact }).click({ timeout, button: opts.button, modifiers: opts.modifiers });
+    await locator.click({ timeout, button: opts.button, modifiers: opts.modifiers });
   } catch (err) {
     throw toAIFriendlyError(err, `text="${opts.text}"`);
   }
@@ -3079,13 +3295,12 @@ async function clickByTextViaPlaywright(opts) {
 async function clickByRoleViaPlaywright(opts) {
   const page = await getRestoredPageForTarget(opts);
   const timeout = resolveInteractionTimeoutMs(opts.timeoutMs);
+  const label = `role=${opts.role}${opts.name !== void 0 && opts.name !== "" ? ` name="${opts.name}"` : ""}`;
+  const locator = page.getByRole(opts.role, { name: opts.name }).nth(opts.index ?? 0);
   try {
-    await page.getByRole(opts.role, { name: opts.name }).click({ timeout, button: opts.button, modifiers: opts.modifiers });
+    await locator.click({ timeout, button: opts.button, modifiers: opts.modifiers });
   } catch (err) {
-    throw toAIFriendlyError(
-      err,
-      `role=${opts.role}${opts.name !== void 0 && opts.name !== "" ? ` name="${opts.name}"` : ""}`
-    );
+    throw toAIFriendlyError(err, label);
   }
 }
 async function clickViaPlaywright(opts) {
@@ -3106,7 +3321,7 @@ async function clickViaPlaywright(opts) {
   try {
     const delayMs = resolveBoundedDelayMs(opts.delayMs, "click delayMs", MAX_CLICK_DELAY_MS);
     if (delayMs > 0) {
-      await locator.hover({ timeout });
+      await locator.hover({ timeout, force: opts.force });
       await new Promise((resolve2) => setTimeout(resolve2, delayMs));
     }
     let ariaCheckedBefore;
@@ -3114,9 +3329,9 @@ async function clickViaPlaywright(opts) {
       ariaCheckedBefore = await locator.getAttribute("aria-checked", { timeout }).catch(() => void 0);
     }
     if (opts.doubleClick === true) {
-      await locator.dblclick({ timeout, button: opts.button, modifiers: opts.modifiers });
+      await locator.dblclick({ timeout, button: opts.button, modifiers: opts.modifiers, force: opts.force });
     } else {
-      await locator.click({ timeout, button: opts.button, modifiers: opts.modifiers });
+      await locator.click({ timeout, button: opts.button, modifiers: opts.modifiers, force: opts.force });
     }
     if (checkableRole && opts.doubleClick !== true && ariaCheckedBefore !== void 0) {
       const POLL_INTERVAL_MS = 50;
@@ -3210,9 +3425,13 @@ async function fillFormViaPlaywright(opts) {
     if (type === "checkbox" || type === "radio") {
       const checked = rawValue === true || rawValue === 1 || rawValue === "1" || rawValue === "true";
       try {
-        await locator.setChecked(checked, { timeout });
-      } catch (err) {
-        throw toAIFriendlyError(err, ref);
+        await locator.setChecked(checked, { timeout, force: true });
+      } catch {
+        try {
+          await setCheckedViaEvaluate(locator, checked);
+        } catch (err) {
+          throw toAIFriendlyError(err, ref);
+        }
       }
       continue;
     }
@@ -3229,7 +3448,13 @@ async function scrollIntoViewViaPlaywright(opts) {
   const label = resolved.ref ?? resolved.selector ?? "";
   const locator = resolveLocator(page, resolved);
   try {
-    await locator.scrollIntoViewIfNeeded({ timeout: normalizeTimeoutMs(opts.timeoutMs, 2e4) });
+    await locator.waitFor({
+      state: "attached",
+      timeout: normalizeTimeoutMs(opts.timeoutMs, DEFAULT_SCROLL_TIMEOUT_MS)
+    });
+    await locator.evaluate((el) => {
+      el.scrollIntoView({ block: "center", behavior: "instant" });
+    });
   } catch (err) {
     throw toAIFriendlyError(err, label);
   }
@@ -3359,6 +3584,82 @@ function isRetryableNavigateError(err) {
   const msg = typeof err === "string" ? err.toLowerCase() : err instanceof Error ? err.message.toLowerCase() : "";
   return msg.includes("frame has been detached") || msg.includes("target page, context or browser has been closed");
 }
+function isPolicyDenyNavigationError(err) {
+  return err instanceof InvalidBrowserNavigationUrlError;
+}
+function isTopLevelNavigationRequest(page, request) {
+  if (!request.isNavigationRequest()) return false;
+  try {
+    return request.frame() === page.mainFrame();
+  } catch {
+    return true;
+  }
+}
+async function closeBlockedNavigationTarget(opts) {
+  markPageRefBlocked(opts.cdpUrl, opts.page);
+  const resolvedTargetId = await pageTargetId(opts.page).catch(() => null);
+  const fallbackTargetId = opts.targetId?.trim() ?? "";
+  const targetIdToBlock = resolvedTargetId ?? fallbackTargetId;
+  if (targetIdToBlock) markTargetBlocked(opts.cdpUrl, targetIdToBlock);
+  await opts.page.close().catch((e) => {
+    console.warn("[browserclaw] failed to close blocked page", e);
+  });
+}
+async function assertPageNavigationCompletedSafely(opts) {
+  const navigationPolicy = withBrowserNavigationPolicy(opts.ssrfPolicy);
+  try {
+    await assertBrowserNavigationRedirectChainAllowed({ request: opts.response?.request(), ...navigationPolicy });
+    await assertBrowserNavigationResultAllowed({ url: opts.page.url(), ...navigationPolicy });
+  } catch (err) {
+    if (isPolicyDenyNavigationError(err))
+      await closeBlockedNavigationTarget({ cdpUrl: opts.cdpUrl, page: opts.page, targetId: opts.targetId });
+    throw err;
+  }
+}
+async function gotoPageWithNavigationGuard(opts) {
+  const navigationPolicy = withBrowserNavigationPolicy(opts.ssrfPolicy);
+  const state = { blocked: null };
+  const handler = async (route, request) => {
+    if (state.blocked !== null) {
+      await route.abort().catch((e) => {
+        console.warn("[browserclaw] route abort failed", e);
+      });
+      return;
+    }
+    if (!isTopLevelNavigationRequest(opts.page, request)) {
+      await route.continue();
+      return;
+    }
+    try {
+      await assertBrowserNavigationAllowed({ url: request.url(), ...navigationPolicy });
+    } catch (err) {
+      if (isPolicyDenyNavigationError(err)) {
+        state.blocked = err;
+        await route.abort().catch((e) => {
+          console.warn("[browserclaw] route abort failed", e);
+        });
+        return;
+      }
+      throw err;
+    }
+    await route.continue();
+  };
+  await opts.page.route("**", handler);
+  try {
+    const response = await opts.page.goto(opts.url, { timeout: opts.timeoutMs });
+    if (state.blocked !== null) throw state.blocked;
+    return response;
+  } catch (err) {
+    if (state.blocked !== null) throw state.blocked;
+    throw err;
+  } finally {
+    await opts.page.unroute("**", handler).catch((e) => {
+      console.warn("[browserclaw] route unroute failed", e);
+    });
+    if (state.blocked !== null)
+      await closeBlockedNavigationTarget({ cdpUrl: opts.cdpUrl, page: opts.page, targetId: opts.targetId });
+  }
+}
 async function navigateViaPlaywright(opts) {
   const url = opts.url.trim();
   if (!url) throw new Error("url is required");
@@ -3367,7 +3668,14 @@ async function navigateViaPlaywright(opts) {
   const timeout = Math.max(1e3, Math.min(12e4, opts.timeoutMs ?? 2e4));
   let page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
   ensurePageState(page);
-  const navigate = async () => await page.goto(url, { timeout });
+  const navigate = async () => await gotoPageWithNavigationGuard({
+    cdpUrl: opts.cdpUrl,
+    page,
+    url,
+    timeoutMs: timeout,
+    ssrfPolicy: policy,
+    targetId: opts.targetId
+  });
   let response;
   try {
     response = await navigate();
@@ -3381,21 +3689,23 @@ async function navigateViaPlaywright(opts) {
     ensurePageState(page);
     response = await navigate();
   }
-  await assertBrowserNavigationRedirectChainAllowed({
-    request: response?.request(),
-    ...withBrowserNavigationPolicy(policy)
+  await assertPageNavigationCompletedSafely({
+    cdpUrl: opts.cdpUrl,
+    page,
+    response,
+    ssrfPolicy: policy,
+    targetId: opts.targetId
   });
-  const finalUrl = page.url();
-  await assertBrowserNavigationResultAllowed({ url: finalUrl, ...withBrowserNavigationPolicy(policy) });
-  return { url: finalUrl };
+  return { url: page.url() };
 }
 async function listPagesViaPlaywright(opts) {
   const { browser } = await connectBrowser(opts.cdpUrl);
   const pages = getAllPages(browser);
   const results = [];
   for (const page of pages) {
+    if (isBlockedPageRef(opts.cdpUrl, page)) continue;
     const tid = await pageTargetId(page).catch(() => null);
-    if (tid !== null && tid !== "")
+    if (tid !== null && tid !== "" && !isBlockedTarget(opts.cdpUrl, tid))
       results.push({
         targetId: tid,
         title: await page.title().catch(() => ""),
@@ -3411,18 +3721,35 @@ async function createPageViaPlaywright(opts) {
   ensureContextState(context);
   const page = await context.newPage();
   ensurePageState(page);
+  clearBlockedPageRef(opts.cdpUrl, page);
+  const createdTargetId = await pageTargetId(page).catch(() => null);
+  clearBlockedTarget(opts.cdpUrl, createdTargetId ?? void 0);
   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);
-    await assertBrowserNavigationAllowed({ url: targetUrl, ...navigationPolicy });
-    await assertBrowserNavigationRedirectChainAllowed({
-      request: (await page.goto(targetUrl, { timeout: 3e4 }).catch(() => null))?.request(),
-      ...navigationPolicy
+    await assertBrowserNavigationAllowed({ url: targetUrl, ...withBrowserNavigationPolicy(policy) });
+    let response = null;
+    try {
+      response = await gotoPageWithNavigationGuard({
+        cdpUrl: opts.cdpUrl,
+        page,
+        url: targetUrl,
+        timeoutMs: 3e4,
+        ssrfPolicy: policy,
+        targetId: createdTargetId ?? void 0
+      });
+    } catch (err) {
+      if (isPolicyDenyNavigationError(err) || err instanceof BlockedBrowserTargetError) throw err;
+    }
+    await assertPageNavigationCompletedSafely({
+      cdpUrl: opts.cdpUrl,
+      page,
+      response,
+      ssrfPolicy: policy,
+      targetId: createdTargetId ?? void 0
     });
-    await assertBrowserNavigationResultAllowed({ url: page.url(), ...navigationPolicy });
   }
-  const tid = await pageTargetId(page).catch(() => null);
+  const tid = createdTargetId ?? await pageTargetId(page).catch(() => null);
   if (tid === null || tid === "") throw new Error("Failed to get targetId for new page");
   return {
     targetId: tid,
@@ -3437,7 +3764,12 @@ async function closePageViaPlaywright(opts) {
   await page.close();
 }
 async function closePageByTargetIdViaPlaywright(opts) {
-  await (await resolvePageByTargetIdOrThrow(opts)).close();
+  try {
+    await (await resolvePageByTargetIdOrThrow(opts)).close();
+  } catch (err) {
+    if (err instanceof BrowserTabNotFoundError) return;
+    throw err;
+  }
 }
 async function focusPageByTargetIdViaPlaywright(opts) {
   const page = await resolvePageByTargetIdOrThrow(opts);
@@ -3459,6 +3791,27 @@ async function focusPageByTargetIdViaPlaywright(opts) {
     }
   }
 }
+async function waitForTabViaPlaywright(opts) {
+  if (opts.urlContains === void 0 && opts.titleContains === void 0)
+    throw new Error("urlContains or titleContains is required");
+  const timeout = Math.max(1e3, Math.min(12e4, opts.timeoutMs ?? 3e4));
+  const start = Date.now();
+  const POLL_INTERVAL_MS = 250;
+  while (Date.now() - start < timeout) {
+    const tabs = await listPagesViaPlaywright({ cdpUrl: opts.cdpUrl });
+    const match = tabs.find((t) => {
+      if (opts.urlContains !== void 0 && !t.url.includes(opts.urlContains)) return false;
+      if (opts.titleContains !== void 0 && !t.title.includes(opts.titleContains)) return false;
+      return true;
+    });
+    if (match) return match;
+    await new Promise((resolve2) => setTimeout(resolve2, POLL_INTERVAL_MS));
+  }
+  const criteria = [];
+  if (opts.urlContains !== void 0) criteria.push(`url contains "${opts.urlContains}"`);
+  if (opts.titleContains !== void 0) criteria.push(`title contains "${opts.titleContains}"`);
+  throw new Error(`Timed out waiting for tab: ${criteria.join(", ")}`);
+}
 async function resizeViewportViaPlaywright(opts) {
   const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
   ensurePageState(page);
@@ -3500,9 +3853,13 @@ async function waitForViaPlaywright(opts) {
   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 });
+  if (opts.fn !== void 0) {
+    if (typeof opts.fn === "function") {
+      await page.waitForFunction(opts.fn, opts.arg, { timeout });
+    } else {
+      const fn = opts.fn.trim();
+      if (fn !== "") await page.waitForFunction(fn, opts.arg, { timeout });
+    }
   }
 }
 
@@ -3614,6 +3971,7 @@ async function executeSingleAction(action, cdpUrl, targetId, evaluateEnabled, de
         url: action.url,
         loadState: action.loadState,
         fn: action.fn,
+        arg: action.arg,
         timeoutMs: action.timeoutMs
       });
       break;
@@ -4089,6 +4447,40 @@ async function responseBodyViaPlaywright(opts) {
     truncated
   };
 }
+async function waitForRequestViaPlaywright(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 upperMethod = opts.method !== void 0 ? opts.method.toUpperCase() : void 0;
+  const response = await page.waitForResponse(
+    (resp) => matchUrlPattern(pattern, resp.url()) && (upperMethod === void 0 || resp.request().method() === upperMethod),
+    { timeout }
+  );
+  const request = response.request();
+  let responseBody;
+  let truncated = false;
+  try {
+    responseBody = await response.text();
+    const maxChars = typeof opts.maxChars === "number" && Number.isFinite(opts.maxChars) ? Math.max(1, Math.min(5e6, Math.floor(opts.maxChars))) : 2e5;
+    if (responseBody.length > maxChars) {
+      responseBody = responseBody.slice(0, maxChars);
+      truncated = true;
+    }
+  } catch (err) {
+    console.warn("[browserclaw] response body unavailable:", err instanceof Error ? err.message : String(err));
+  }
+  return {
+    url: response.url(),
+    method: request.method(),
+    postData: request.postData() ?? void 0,
+    status: response.status(),
+    ok: response.ok(),
+    responseBody,
+    truncated
+  };
+}
 
 // src/capture/screenshot.ts
 async function takeScreenshotViaPlaywright(opts) {
@@ -4212,6 +4604,13 @@ async function traceStopViaPlaywright(opts) {
 }
 
 // src/snapshot/ref-map.ts
+function parseStateFromSuffix(suffix) {
+  const state = {};
+  if (/\[disabled\]/i.test(suffix)) state.disabled = true;
+  if (/\[checked\s*=\s*"?mixed"?\]/i.test(suffix)) state.checked = "mixed";
+  else if (/\[checked\]/i.test(suffix)) state.checked = true;
+  return state;
+}
 var INTERACTIVE_ROLES = /* @__PURE__ */ new Set([
   "button",
   "link",
@@ -4370,7 +4769,8 @@ function buildRoleSnapshotFromAriaSnapshot(ariaSnapshot, options = {}) {
       const ref = nextRef();
       const nth = tracker.getNextIndex(role, name);
       tracker.trackRef(role, name, ref);
-      refs[ref] = { role, name, nth };
+      const state = parseStateFromSuffix(suffix);
+      refs[ref] = { role, name, nth, ...state };
       let enhanced = `${prefix}${roleRaw}`;
       if (name !== void 0 && name !== "") enhanced += ` "${name}"`;
       enhanced += ` [ref=${ref}]`;
@@ -4407,7 +4807,8 @@ function buildRoleSnapshotFromAriaSnapshot(ariaSnapshot, options = {}) {
     const ref = nextRef();
     const nth = tracker.getNextIndex(role, name);
     tracker.trackRef(role, name, ref);
-    refs[ref] = { role, name, nth };
+    const state = parseStateFromSuffix(suffix);
+    refs[ref] = { role, name, nth, ...state };
     let enhanced = `${prefix}${roleRaw}`;
     if (name !== "") enhanced += ` "${name}"`;
     enhanced += ` [ref=${ref}]`;
@@ -4445,12 +4846,13 @@ function buildRoleSnapshotFromAiSnapshot(aiSnapshot, options = {}) {
       if (!INTERACTIVE_ROLES.has(role)) continue;
       const ref = parseAiSnapshotRef(suffix);
       const prefix = /^(\s*-\s*)/.exec(line)?.[1] ?? "";
+      const state = parseStateFromSuffix(suffix);
       if (ref !== null) {
-        refs[ref] = { role, ...name !== void 0 && name !== "" ? { name } : {} };
+        refs[ref] = { role, ...name !== void 0 && name !== "" ? { name } : {}, ...state };
         out2.push(`${prefix}${roleRaw}${name !== void 0 && name !== "" ? ` "${name}"` : ""}${suffix}`);
       } else {
         const generatedRef = nextInteractiveRef();
-        refs[generatedRef] = { role, ...name !== void 0 && name !== "" ? { name } : {} };
+        refs[generatedRef] = { role, ...name !== void 0 && name !== "" ? { name } : {}, ...state };
         let enhanced = `${prefix}${roleRaw}`;
         if (name !== void 0 && name !== "") enhanced += ` "${name}"`;
         enhanced += ` [ref=${generatedRef}]`;
@@ -4488,12 +4890,13 @@ function buildRoleSnapshotFromAiSnapshot(aiSnapshot, options = {}) {
     const isStructural = STRUCTURAL_ROLES.has(role);
     if (options.compact === true && isStructural && name === "") continue;
     const ref = parseAiSnapshotRef(suffix);
+    const state = parseStateFromSuffix(suffix);
     if (ref !== null) {
-      refs[ref] = { role, ...name !== "" ? { name } : {} };
+      refs[ref] = { role, ...name !== "" ? { name } : {}, ...state };
       out.push(line);
     } else if (INTERACTIVE_ROLES.has(role)) {
       const generatedRef = nextGeneratedRef();
-      refs[generatedRef] = { role, ...name !== "" ? { name } : {} };
+      refs[generatedRef] = { role, ...name !== "" ? { name } : {}, ...state };
       let enhanced = `${prefix}${roleRaw}`;
       if (name !== "") enhanced += ` "${name}"`;
       enhanced += ` [ref=${generatedRef}]`;
@@ -4859,7 +5262,8 @@ var CrawlPage = class {
       button: opts?.button,
       modifiers: opts?.modifiers,
       delayMs: opts?.delayMs,
-      timeoutMs: opts?.timeoutMs
+      timeoutMs: opts?.timeoutMs,
+      force: opts?.force
     });
   }
   /**
@@ -4885,7 +5289,8 @@ var CrawlPage = class {
       button: opts?.button,
       modifiers: opts?.modifiers,
       delayMs: opts?.delayMs,
-      timeoutMs: opts?.timeoutMs
+      timeoutMs: opts?.timeoutMs,
+      force: opts?.force
     });
   }
   /**
@@ -4915,6 +5320,32 @@ var CrawlPage = class {
       delayMs: opts?.delayMs
     });
   }
+  /**
+   * Press and hold at page coordinates using raw CDP events.
+   *
+   * Bypasses Playwright's automation layer by dispatching CDP
+   * `Input.dispatchMouseEvent` directly — useful for anti-bot challenges
+   * that detect automated clicks.
+   *
+   * @param x - X coordinate in CSS pixels
+   * @param y - Y coordinate in CSS pixels
+   * @param opts - Options (delay: ms before press, holdMs: hold duration)
+   *
+   * @example
+   * ```ts
+   * await page.pressAndHold(400, 300, { delay: 150, holdMs: 5000 });
+   * ```
+   */
+  async pressAndHold(x, y, opts) {
+    return pressAndHoldViaCdp({
+      cdpUrl: this.cdpUrl,
+      targetId: this.targetId,
+      x,
+      y,
+      delay: opts?.delay,
+      holdMs: opts?.holdMs
+    });
+  }
   /**
    * Click an element by its visible text content (no snapshot/ref needed).
    *
@@ -4962,6 +5393,7 @@ var CrawlPage = class {
       targetId: this.targetId,
       role,
       name,
+      index: opts?.index,
       button: opts?.button,
       modifiers: opts?.modifiers,
       timeoutMs: opts?.timeoutMs
@@ -5485,6 +5917,35 @@ var CrawlPage = class {
       maxChars: opts?.maxChars
     });
   }
+  /**
+   * Wait for a network request matching a URL pattern and return request + response details.
+   *
+   * Unlike `networkRequests()` which only captures metadata, this method captures
+   * the full request body (POST data) and response body.
+   *
+   * @param url - URL string or pattern to match (supports `*` wildcards and substring matching)
+   * @param opts - Options (method filter, timeoutMs, maxChars for response body)
+   * @returns Request method, postData, response status, and response body
+   *
+   * @example
+   * ```ts
+   * const reqPromise = page.waitForRequest('/api/submit', { method: 'POST' });
+   * await page.click('e5'); // submit a form
+   * const req = await reqPromise;
+   * console.log(req.postData); // form body
+   * console.log(req.status, req.responseBody); // response
+   * ```
+   */
+  async waitForRequest(url, opts) {
+    return waitForRequestViaPlaywright({
+      cdpUrl: this.cdpUrl,
+      targetId: this.targetId,
+      url,
+      method: opts?.method,
+      timeoutMs: opts?.timeoutMs,
+      maxChars: opts?.maxChars
+    });
+  }
   /**
    * Get console messages captured from the page.
    *
@@ -5915,14 +6376,15 @@ var BrowserClaw = class _BrowserClaw {
    *
    * @example
    * ```ts
-   * // Default: visible Chrome window
-   * const browser = await BrowserClaw.launch();
+   * // Launch and navigate to a URL
+   * const browser = await BrowserClaw.launch({ url: 'https://example.com' });
    *
    * // Headless mode
-   * const browser = await BrowserClaw.launch({ headless: true });
+   * const browser = await BrowserClaw.launch({ url: 'https://example.com', headless: true });
    *
    * // Specific browser
    * const browser = await BrowserClaw.launch({
+   *   url: 'https://example.com',
    *   executablePath: '/usr/bin/google-chrome',
    * });
    * ```
@@ -5931,7 +6393,12 @@ var BrowserClaw = class _BrowserClaw {
     const chrome = await launchChrome(opts);
     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, opts.recordVideo);
+    const browser = new _BrowserClaw(cdpUrl, chrome, ssrfPolicy, opts.recordVideo);
+    if (opts.url !== void 0 && opts.url !== "") {
+      const page = await browser.currentPage();
+      await page.goto(opts.url);
+    }
+    return browser;
   }
   /**
    * Connect to an already-running Chrome instance via its CDP endpoint.
@@ -6007,6 +6474,31 @@ var BrowserClaw = class _BrowserClaw {
   async tabs() {
     return listPagesViaPlaywright({ cdpUrl: this.cdpUrl });
   }
+  /**
+   * Wait for a tab matching the given criteria and return a page handle.
+   *
+   * Polls open tabs until one matches, then focuses it and returns a CrawlPage.
+   *
+   * @param opts - Match criteria (urlContains, titleContains) and timeout
+   * @returns A CrawlPage for the matched tab
+   *
+   * @example
+   * ```ts
+   * await page.click('e5'); // opens a new tab
+   * const appPage = await browser.waitForTab({ urlContains: 'app-web' });
+   * const { snapshot } = await appPage.snapshot();
+   * ```
+   */
+  async waitForTab(opts) {
+    const tab = await waitForTabViaPlaywright({
+      cdpUrl: this.cdpUrl,
+      urlContains: opts.urlContains,
+      titleContains: opts.titleContains,
+      timeoutMs: opts.timeoutMs
+    });
+    await focusPageByTargetIdViaPlaywright({ cdpUrl: this.cdpUrl, targetId: tab.targetId });
+    return new CrawlPage(this.cdpUrl, tab.targetId, this.ssrfPolicy);
+  }
   /**
    * Bring a tab to the foreground.
    *
@@ -6055,6 +6547,6 @@ var BrowserClaw = class _BrowserClaw {
   }
 };
 
-export { BrowserClaw, BrowserTabNotFoundError, CrawlPage, InvalidBrowserNavigationUrlError, STEALTH_SCRIPT, assertBrowserNavigationAllowed, assertBrowserNavigationRedirectChainAllowed, assertBrowserNavigationResultAllowed, assertSafeUploadPaths, batchViaPlaywright, createPinnedLookup, detectChallengeViaPlaywright, ensureContextState, executeSingleAction, forceDisconnectPlaywrightForTarget, getChromeWebSocketUrl, getRestoredPageForTarget, isChromeCdpReady, isChromeReachable, normalizeCdpHttpBaseForJsonEndpoints, parseRoleRef, requireRef, requireRefOrSelector, requiresInspectableBrowserNavigationRedirects, resolveBoundedDelayMs, resolveInteractionTimeoutMs, resolvePageByTargetIdOrThrow, resolvePinnedHostnameWithPolicy, resolveStrictExistingUploadPaths, sanitizeUntrustedFileName, setDialogHandler, waitForChallengeViaPlaywright, withBrowserNavigationPolicy, withPageScopedCdpClient, withPlaywrightPageCdpSession, writeViaSiblingTempPath };
+export { BrowserClaw, BrowserTabNotFoundError, CrawlPage, InvalidBrowserNavigationUrlError, STEALTH_SCRIPT, assertBrowserNavigationAllowed, assertBrowserNavigationRedirectChainAllowed, assertBrowserNavigationResultAllowed, assertSafeUploadPaths, batchViaPlaywright, createPinnedLookup, detectChallengeViaPlaywright, ensureContextState, executeSingleAction, forceDisconnectPlaywrightForTarget, getChromeWebSocketUrl, getRestoredPageForTarget, isChromeCdpReady, isChromeReachable, normalizeCdpHttpBaseForJsonEndpoints, parseRoleRef, pressAndHoldViaCdp, requireRef, requireRefOrSelector, requiresInspectableBrowserNavigationRedirects, resolveBoundedDelayMs, resolveInteractionTimeoutMs, resolvePageByTargetIdOrThrow, resolvePinnedHostnameWithPolicy, resolveStrictExistingUploadPaths, sanitizeUntrustedFileName, setDialogHandler, waitForChallengeViaPlaywright, withBrowserNavigationPolicy, withPageScopedCdpClient, withPlaywrightPageCdpSession, writeViaSiblingTempPath };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map