browserclaw 0.5.0 → 0.5.2

package/dist/index.d.cts

@@ -227,6 +227,8 @@ interface ClickOptions {
     button?: 'left' | 'right' | 'middle';
     /** Modifier keys to hold during click */
     modifiers?: ('Alt' | 'Control' | 'ControlOrMeta' | 'Meta' | 'Shift')[];
+    /** Delay in ms between hover and click (hovers first, waits, then clicks). Max: `5000` */
+    delayMs?: number;
     /** Timeout in milliseconds. Default: `8000` */
     timeoutMs?: number;
 }
@@ -1238,8 +1240,8 @@ declare function requiresInspectableBrowserNavigationRedirects(ssrfPolicy?: Ssrf
 declare function ensureContextState(context: BrowserContext): ContextState;
 /**
  * Force-disconnect a Playwright browser connection for a given CDP target.
- * Clears the connection cache, sends Runtime.terminateExecution via CDP
- * session to kill stuck evals, and closes the browser.
+ * Clears the connection cache, sends Runtime.terminateExecution via raw CDP
+ * websocket to kill stuck evals (bypassing Playwright), and closes the browser.
  */
 declare function forceDisconnectPlaywrightForTarget(opts: {
     cdpUrl: string;

package/dist/index.d.ts

@@ -227,6 +227,8 @@ interface ClickOptions {
     button?: 'left' | 'right' | 'middle';
     /** Modifier keys to hold during click */
     modifiers?: ('Alt' | 'Control' | 'ControlOrMeta' | 'Meta' | 'Shift')[];
+    /** Delay in ms between hover and click (hovers first, waits, then clicks). Max: `5000` */
+    delayMs?: number;
     /** Timeout in milliseconds. Default: `8000` */
     timeoutMs?: number;
 }
@@ -1238,8 +1240,8 @@ declare function requiresInspectableBrowserNavigationRedirects(ssrfPolicy?: Ssrf
 declare function ensureContextState(context: BrowserContext): ContextState;
 /**
  * Force-disconnect a Playwright browser connection for a given CDP target.
- * Clears the connection cache, sends Runtime.terminateExecution via CDP
- * session to kill stuck evals, and closes the browser.
+ * Clears the connection cache, sends Runtime.terminateExecution via raw CDP
+ * websocket to kill stuck evals (bypassing Playwright), and closes the browser.
  */
 declare function forceDisconnectPlaywrightForTarget(opts: {
     cdpUrl: string;

package/dist/index.js

@@ -813,6 +813,7 @@ async function connectBrowser(cdpUrl, authToken) {
         return connected;
       } catch (err) {
         lastErr = err;
+        if ((err instanceof Error ? err.message : String(err)).includes("rate limit")) break;
         await new Promise((r) => setTimeout(r, 250 + attempt * 250));
       }
     }
@@ -838,6 +839,55 @@ async function disconnectBrowser() {
   if (cur) await cur.browser.close().catch(() => {
   });
 }
+async function tryTerminateExecutionViaCdp(cdpUrl, targetId) {
+  const httpBase = normalizeCdpHttpBaseForJsonEndpoints(cdpUrl);
+  const ctrl = new AbortController();
+  const t = setTimeout(() => ctrl.abort(), 2e3);
+  let targets;
+  try {
+    const res = await fetch(`${httpBase}/json/list`, { signal: ctrl.signal });
+    if (!res.ok) return;
+    targets = await res.json();
+  } catch {
+    return;
+  } finally {
+    clearTimeout(t);
+  }
+  if (!Array.isArray(targets)) return;
+  const target = targets.find((entry) => String(entry?.id ?? "").trim() === targetId);
+  const wsUrl = String(target?.webSocketDebuggerUrl ?? "").trim();
+  if (!wsUrl) return;
+  await new Promise((resolve2) => {
+    let done = false;
+    const finish = () => {
+      if (done) return;
+      done = true;
+      clearTimeout(timer);
+      try {
+        ws.close();
+      } catch {
+      }
+      resolve2();
+    };
+    const timer = setTimeout(finish, 2e3);
+    let ws;
+    try {
+      ws = new WebSocket(wsUrl);
+    } catch {
+      finish();
+      return;
+    }
+    ws.onopen = () => {
+      try {
+        ws.send(JSON.stringify({ id: 1, method: "Runtime.terminateExecution" }));
+      } catch {
+      }
+      setTimeout(finish, 300);
+    };
+    ws.onerror = () => finish();
+    ws.onclose = () => finish();
+  });
+}
 async function forceDisconnectPlaywrightForTarget(opts) {
   const normalized = normalizeCdpUrl(opts.cdpUrl);
   const cur = cached;
@@ -846,23 +896,8 @@ async function forceDisconnectPlaywrightForTarget(opts) {
   connectingByUrl.delete(normalized);
   const targetId = opts.targetId?.trim() || "";
   if (targetId) {
-    try {
-      const pages = await getAllPages(cur.browser);
-      for (const page of pages) {
-        const tid = await pageTargetId(page).catch(() => null);
-        if (tid === targetId) {
-          const session = await page.context().newCDPSession(page);
-          try {
-            await session.send("Runtime.terminateExecution");
-          } finally {
-            await session.detach().catch(() => {
-            });
-          }
-          break;
-        }
-      }
-    } catch {
-    }
+    await tryTerminateExecutionViaCdp(normalized, targetId).catch(() => {
+    });
   }
   cur.browser.close().catch(() => {
   });
@@ -1284,6 +1319,35 @@ async function snapshotRole(opts) {
   const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
   ensurePageState(page);
   const sourceUrl = page.url();
+  if (opts.refsMode === "aria") {
+    if (opts.selector?.trim() || opts.frameSelector?.trim()) {
+      throw new Error("refs=aria does not support selector/frame snapshots yet.");
+    }
+    const maybe = page;
+    if (!maybe._snapshotForAI) {
+      throw new Error("refs=aria requires Playwright _snapshotForAI support.");
+    }
+    const result = await maybe._snapshotForAI({ timeout: 5e3, track: "response" });
+    const built2 = buildRoleSnapshotFromAiSnapshot(String(result?.full ?? ""), opts.options);
+    storeRoleRefsForTarget({
+      page,
+      cdpUrl: opts.cdpUrl,
+      targetId: opts.targetId,
+      refs: built2.refs,
+      mode: "aria"
+    });
+    return {
+      snapshot: built2.snapshot,
+      refs: built2.refs,
+      stats: getRoleSnapshotStats(built2.snapshot, built2.refs),
+      untrusted: true,
+      contentMeta: {
+        sourceUrl,
+        contentType: "browser-snapshot",
+        capturedAt: (/* @__PURE__ */ new Date()).toISOString()
+      }
+    };
+  }
   const frameSelector = opts.frameSelector?.trim() || "";
   const selector = opts.selector?.trim() || "";
   const locator = frameSelector ? selector ? page.frameLocator(frameSelector).locator(selector) : page.frameLocator(frameSelector).locator(":root") : selector ? page.locator(selector) : page.locator(":root");
@@ -1295,7 +1359,7 @@ async function snapshotRole(opts) {
     targetId: opts.targetId,
     refs: built.refs,
     frameSelector: frameSelector || void 0,
-    mode: opts.refsMode ?? "role"
+    mode: "role"
   });
   return {
     snapshot: built.snapshot,
@@ -1383,7 +1447,7 @@ var InvalidBrowserNavigationUrlError = class extends Error {
   }
 };
 function withBrowserNavigationPolicy(ssrfPolicy) {
-  return { ssrfPolicy };
+  return ssrfPolicy ? { ssrfPolicy } : {};
 }
 var NETWORK_NAVIGATION_PROTOCOLS = /* @__PURE__ */ new Set(["http:", "https:"]);
 var SAFE_NON_NETWORK_URLS = /* @__PURE__ */ new Set(["about:blank"]);
@@ -1496,6 +1560,30 @@ function extractEmbeddedIpv4FromIpv6(v6, opts) {
       return true;
     }
   }
+  if (parts[0] === 0 && parts[1] === 0 && parts[2] === 0 && parts[3] === 0 && parts[4] === 65535 && parts[5] === 0) {
+    const ip4str = `${parts[6] >> 8 & 255}.${parts[6] & 255}.${parts[7] >> 8 & 255}.${parts[7] & 255}`;
+    try {
+      return isBlockedSpecialUseIpv4Address(ipaddr.IPv4.parse(ip4str), opts);
+    } catch {
+      return true;
+    }
+  }
+  if (parts[0] === 0 && parts[1] === 0 && parts[2] === 0 && parts[3] === 0 && parts[4] === 0 && parts[5] === 0) {
+    const ip4str = `${parts[6] >> 8 & 255}.${parts[6] & 255}.${parts[7] >> 8 & 255}.${parts[7] & 255}`;
+    try {
+      return isBlockedSpecialUseIpv4Address(ipaddr.IPv4.parse(ip4str), opts);
+    } catch {
+      return true;
+    }
+  }
+  if ((parts[4] & 65023) === 0 && parts[5] === 24318) {
+    const ip4str = `${parts[6] >> 8 & 255}.${parts[6] & 255}.${parts[7] >> 8 & 255}.${parts[7] & 255}`;
+    try {
+      return isBlockedSpecialUseIpv4Address(ipaddr.IPv4.parse(ip4str), opts);
+    } catch {
+      return true;
+    }
+  }
   return null;
 }
 function isPrivateIpAddress(address, opts) {
@@ -1518,6 +1606,30 @@ function isPrivateIpAddress(address, opts) {
   if (normalized.includes(":")) return true;
   return false;
 }
+function normalizeHostnameSet(values) {
+  if (!values || values.length === 0) return /* @__PURE__ */ new Set();
+  return new Set(values.map((v) => normalizeHostname(v)).filter(Boolean));
+}
+function normalizeHostnameAllowlist(values) {
+  if (!values || values.length === 0) return [];
+  return Array.from(
+    new Set(
+      values.map((v) => normalizeHostname(v)).filter((v) => v !== "*" && v !== "*." && v.length > 0)
+    )
+  );
+}
+function isHostnameAllowedByPattern(hostname, pattern) {
+  if (pattern.startsWith("*.")) {
+    const suffix = pattern.slice(2);
+    if (!suffix || hostname === suffix) return false;
+    return hostname.endsWith(`.${suffix}`);
+  }
+  return hostname === pattern;
+}
+function matchesHostnameAllowlist(hostname, allowlist) {
+  if (allowlist.length === 0) return true;
+  return allowlist.some((pattern) => isHostnameAllowedByPattern(hostname, pattern));
+}
 function dedupeAndPreferIpv4(results) {
   const seen = /* @__PURE__ */ new Set();
   const ipv4 = [];
@@ -1563,12 +1675,15 @@ async function resolvePinnedHostnameWithPolicy(hostname, params = {}) {
   const normalized = normalizeHostname(hostname);
   if (!normalized) throw new InvalidBrowserNavigationUrlError(`Invalid hostname: "${hostname}"`);
   const allowPrivateNetwork = isPrivateNetworkAllowedByPolicy(params.policy);
-  const allowedHostnames = [
-    ...params.policy?.allowedHostnames ?? [],
-    ...params.policy?.hostnameAllowlist ?? []
-  ].map((h) => normalizeHostname(h));
-  const isExplicitlyAllowed = allowedHostnames.some((h) => h === normalized);
+  const allowedHostnames = normalizeHostnameSet(params.policy?.allowedHostnames);
+  const hostnameAllowlist = normalizeHostnameAllowlist(params.policy?.hostnameAllowlist);
+  const isExplicitlyAllowed = allowedHostnames.has(normalized);
   const skipPrivateNetworkChecks = allowPrivateNetwork || isExplicitlyAllowed;
+  if (!matchesHostnameAllowlist(normalized, hostnameAllowlist)) {
+    throw new InvalidBrowserNavigationUrlError(
+      `Navigation blocked: hostname "${hostname}" is not in the allowlist.`
+    );
+  }
   if (!skipPrivateNetworkChecks) {
     if (isBlockedHostnameNormalized(normalized)) {
       throw new InvalidBrowserNavigationUrlError(
@@ -1635,11 +1750,9 @@ async function assertBrowserNavigationAllowed(opts) {
       "Navigation blocked: strict browser SSRF policy cannot be enforced while env proxy variables are set"
     );
   }
-  const policy = opts.ssrfPolicy;
-  if (policy?.dangerouslyAllowPrivateNetwork ?? policy?.allowPrivateNetwork ?? true) return;
   await resolvePinnedHostnameWithPolicy(parsed.hostname, {
     lookupFn: opts.lookupFn,
-    policy
+    policy: opts.ssrfPolicy
   });
 }
 async function assertSafeOutputPath(path2, allowedRoots) {
@@ -1771,6 +1884,13 @@ function requiresInspectableBrowserNavigationRedirects(ssrfPolicy) {
 }
 
 // src/actions/interaction.ts
+var MAX_CLICK_DELAY_MS = 5e3;
+function resolveBoundedDelayMs(value, label, maxMs) {
+  const normalized = Math.floor(value ?? 0);
+  if (!Number.isFinite(normalized) || normalized < 0) throw new Error(`${label} must be >= 0`);
+  if (normalized > maxMs) throw new Error(`${label} exceeds maximum of ${maxMs}ms`);
+  return normalized;
+}
 async function clickViaPlaywright(opts) {
   const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
   ensurePageState(page);
@@ -1778,6 +1898,11 @@ async function clickViaPlaywright(opts) {
   const locator = refLocator(page, opts.ref);
   const timeout = normalizeTimeoutMs(opts.timeoutMs, 8e3, 6e4);
   try {
+    const delayMs = resolveBoundedDelayMs(opts.delayMs, "click delayMs", MAX_CLICK_DELAY_MS);
+    if (delayMs > 0) {
+      await locator.hover({ timeout });
+      await new Promise((resolve2) => setTimeout(resolve2, delayMs));
+    }
     if (opts.doubleClick) {
       await locator.dblclick({ timeout, button: opts.button, modifiers: opts.modifiers });
     } else {
@@ -2088,12 +2213,14 @@ async function resizeViewportViaPlaywright(opts) {
 }
 
 // src/actions/wait.ts
+var MAX_WAIT_TIME_MS = 3e4;
 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(Math.max(0, opts.timeMs));
+    const bounded = Math.max(0, Math.min(MAX_WAIT_TIME_MS, Math.floor(opts.timeMs)));
+    await page.waitForTimeout(bounded);
   }
   if (opts.text) {
     await page.getByText(opts.text).first().waitFor({ state: "visible", timeout });
@@ -2782,6 +2909,7 @@ var CrawlPage = class {
       doubleClick: opts?.doubleClick,
       button: opts?.button,
       modifiers: opts?.modifiers,
+      delayMs: opts?.delayMs,
       timeoutMs: opts?.timeoutMs
     });
   }