browserclaw 0.5.8 → 0.7.0

package/dist/index.d.cts

@@ -1,8 +1,6 @@
-import * as playwright_core from 'playwright-core';
 import { BrowserContext, Page, CDPSession } from 'playwright-core';
-import * as node_dns from 'node:dns';
-import { lookup as lookup$1 } from 'node:dns';
-import { lookup } from 'node:dns/promises';
+import { lookup } from 'node:dns';
+import { lookup as lookup$1 } from 'node:dns/promises';
 
 /** A single action within a batch. */
 type BatchAction = {
@@ -58,11 +56,11 @@ type BatchAction = {
     timeoutMs?: number;
 } | {
     kind: 'fill';
-    fields: Array<{
+    fields: {
         ref: string;
         type?: string;
         value?: string | number | boolean;
-    }>;
+    }[];
     targetId?: string;
     timeoutMs?: number;
 } | {
@@ -547,11 +545,27 @@ interface HttpCredentials {
 interface ContextState {
     traceActive: boolean;
 }
+/** The kind of anti-bot challenge detected on a page. */
+type ChallengeKind = 'cloudflare-js' | 'cloudflare-block' | 'cloudflare-turnstile' | 'hcaptcha' | 'recaptcha' | 'blocked' | 'rate-limited';
+/** Information about a detected anti-bot challenge. */
+interface ChallengeInfo {
+    /** What type of challenge is present */
+    kind: ChallengeKind;
+    /** Human-readable description */
+    message: string;
+}
+/** Result of waiting for an anti-bot challenge to resolve. */
+interface ChallengeWaitResult {
+    /** Whether the challenge cleared within the timeout */
+    resolved: boolean;
+    /** The challenge still present (null if resolved) */
+    challenge: ChallengeInfo | null;
+}
 /** Result of DNS pinning resolution — hostname locked to resolved addresses. */
 interface PinnedHostname {
     hostname: string;
     addresses: string[];
-    lookup: typeof node_dns.lookup;
+    lookup: typeof lookup;
 }
 
 /**
@@ -925,7 +939,7 @@ declare class CrawlPage {
         type?: 'png' | 'jpeg';
     }): Promise<{
         buffer: Buffer;
-        labels: Array<{
+        labels: {
             ref: string;
             index: number;
             box: {
@@ -934,7 +948,7 @@ declare class CrawlPage {
                 width: number;
                 height: number;
             };
-        }>;
+        }[];
         skipped: string[];
     }>;
     /**
@@ -1022,7 +1036,7 @@ declare class CrawlPage {
      *
      * @returns Array of cookie objects
      */
-    cookies(): Promise<Awaited<ReturnType<playwright_core.BrowserContext['cookies']>>>;
+    cookies(): Promise<Awaited<ReturnType<BrowserContext['cookies']>>>;
     /**
      * Set a cookie in the browser context.
      *
@@ -1164,6 +1178,46 @@ declare class CrawlPage {
      * ```
      */
     setDevice(name: string): Promise<void>;
+    /**
+     * Detect whether the page is showing an anti-bot challenge
+     * (Cloudflare, hCaptcha, reCAPTCHA, access-denied, rate-limit, etc.).
+     *
+     * Returns `null` if no challenge is detected.
+     *
+     * @example
+     * ```ts
+     * const challenge = await page.detectChallenge();
+     * if (challenge) {
+     *   console.log(challenge.kind);    // 'cloudflare-js'
+     *   console.log(challenge.message); // 'Cloudflare JS challenge'
+     * }
+     * ```
+     */
+    detectChallenge(): Promise<ChallengeInfo | null>;
+    /**
+     * Wait for an anti-bot challenge to resolve on its own.
+     *
+     * Cloudflare JS challenges typically auto-resolve in ~5 seconds.
+     * CAPTCHA challenges will only resolve if solved in a visible browser window.
+     *
+     * @param opts.timeoutMs - Maximum wait time (default: `15000`)
+     * @param opts.pollMs - Poll interval (default: `500`)
+     * @returns Whether the challenge resolved, and the remaining challenge info if not
+     *
+     * @example
+     * ```ts
+     * await page.goto('https://example.com');
+     * const challenge = await page.detectChallenge();
+     * if (challenge?.kind === 'cloudflare-js') {
+     *   const { resolved } = await page.waitForChallenge({ timeoutMs: 20000 });
+     *   if (!resolved) throw new Error('Challenge did not resolve');
+     * }
+     * ```
+     */
+    waitForChallenge(opts?: {
+        timeoutMs?: number;
+        pollMs?: number;
+    }): Promise<ChallengeWaitResult>;
 }
 /**
  * Main entry point for browserclaw.
@@ -1296,7 +1350,7 @@ declare function isChromeReachable(cdpUrl: string, timeoutMs?: number, authToken
 declare function getChromeWebSocketUrl(cdpUrl: string, timeoutMs?: number, authToken?: string): Promise<string | null>;
 declare function isChromeCdpReady(cdpUrl: string, timeoutMs?: number, handshakeTimeoutMs?: number): Promise<boolean>;
 
-type LookupFn = typeof lookup;
+type LookupFn = typeof lookup$1;
 /**
  * Thrown when a navigation URL is blocked by SSRF policy.
  * Callers can catch this specifically to distinguish navigation blocks
@@ -1306,14 +1360,14 @@ declare class InvalidBrowserNavigationUrlError extends Error {
     constructor(message: string);
 }
 /** Options for browser navigation SSRF policy. */
-type BrowserNavigationPolicyOptions = {
+interface BrowserNavigationPolicyOptions {
     ssrfPolicy?: SsrfPolicy;
-};
+}
 /** Playwright-compatible request interface for redirect chain inspection. */
-type BrowserNavigationRequestLike = {
+interface BrowserNavigationRequestLike {
     url(): string;
     redirectedFrom(): BrowserNavigationRequestLike | null;
-};
+}
 /** Build a BrowserNavigationPolicyOptions from an SsrfPolicy. */
 declare function withBrowserNavigationPolicy(ssrfPolicy?: SsrfPolicy): BrowserNavigationPolicyOptions;
 /**
@@ -1323,8 +1377,8 @@ declare function withBrowserNavigationPolicy(ssrfPolicy?: SsrfPolicy): BrowserNa
 declare function createPinnedLookup(params: {
     hostname: string;
     addresses: string[];
-    fallback?: typeof lookup$1;
-}): typeof lookup$1;
+    fallback?: typeof lookup;
+}): typeof lookup;
 /**
  * Resolve DNS for a hostname and validate resolved addresses against SSRF policy.
  * Returns a PinnedHostname with pre-resolved addresses and a pinned lookup function.
@@ -1401,14 +1455,12 @@ declare class BrowserTabNotFoundError extends Error {
 declare function withPlaywrightPageCdpSession<T>(page: Page, fn: (session: CDPSession) => Promise<T>): Promise<T>;
 /**
  * Run a function with a page-scoped CDP client.
- * For extension relay endpoints, routes through the raw CDP websocket.
- * Otherwise, uses a Playwright CDP session.
  */
 declare function withPageScopedCdpClient<T>(opts: {
     cdpUrl: string;
     page: Page;
     targetId?: string;
-    fn: (send: (method: string, params?: Record<string, unknown>) => Promise<any>) => Promise<T>;
+    fn: (send: (method: string, params?: Record<string, unknown>) => Promise<unknown>) => Promise<T>;
 }): Promise<T>;
 declare function ensureContextState(context: BrowserContext): ContextState;
 /**
@@ -1458,4 +1510,42 @@ declare function getRestoredPageForTarget(opts: {
     targetId?: string;
 }): Promise<Page>;
 
-export { type AriaNode, type AriaSnapshotResult, type BatchAction, type BatchActionResult, BrowserClaw, type BrowserNavigationPolicyOptions, type BrowserNavigationRequestLike, type BrowserTab, BrowserTabNotFoundError, type ChromeExecutable, type ChromeKind, type ClickOptions, type ColorScheme, type ConnectOptions, type ConsoleMessage, type ContextState, type CookieData, CrawlPage, type DialogOptions, type DownloadResult, type FormField, type FrameEvalResult, type GeolocationOptions, type HttpCredentials, InvalidBrowserNavigationUrlError, type LaunchOptions, type LookupFn, type NetworkRequest, type PageError, type PinnedHostname, type ResponseBodyResult, type RoleRefInfo, type RoleRefs, type ScreenshotOptions, type SnapshotOptions, type SnapshotResult, type SnapshotStats, type SsrfPolicy, type StorageKind, type TraceStartOptions, type TypeOptions, type UntrustedContentMeta, type WaitOptions, assertBrowserNavigationAllowed, assertBrowserNavigationRedirectChainAllowed, assertBrowserNavigationResultAllowed, assertSafeUploadPaths, batchViaPlaywright, createPinnedLookup, ensureContextState, executeSingleAction, forceDisconnectPlaywrightForTarget, getChromeWebSocketUrl, getRestoredPageForTarget, isChromeCdpReady, isChromeReachable, normalizeCdpHttpBaseForJsonEndpoints, parseRoleRef, requireRef, requireRefOrSelector, requiresInspectableBrowserNavigationRedirects, resolveBoundedDelayMs, resolveInteractionTimeoutMs, resolvePageByTargetIdOrThrow, resolvePinnedHostnameWithPolicy, resolveStrictExistingUploadPaths, sanitizeUntrustedFileName, withBrowserNavigationPolicy, withPageScopedCdpClient, withPlaywrightPageCdpSession, writeViaSiblingTempPath };
+/**
+ * Comprehensive browser stealth evasions.
+ *
+ * Injected via `addInitScript()` (runs before any page JS) and via
+ * `page.evaluate()` for already-loaded pages. Each patch is wrapped
+ * in try/catch so a single failure never breaks the rest.
+ *
+ * Covers: navigator.webdriver, plugins, languages, window.chrome,
+ * Permissions API, WebGL fingerprint, Notification.permission,
+ * navigator.connection, console toString, headless-mode quirks,
+ * hardwareConcurrency, and deviceMemory.
+ */
+declare const STEALTH_SCRIPT = "(function() {\n  'use strict';\n  function p(fn) { try { fn(); } catch(_) {} }\n\n  // \u2500\u2500 1. navigator.webdriver \u2192 undefined \u2500\u2500\n  p(function() {\n    Object.defineProperty(navigator, 'webdriver', { get: function() { return undefined; }, configurable: true });\n  });\n\n  // \u2500\u2500 2. navigator.plugins + mimeTypes (only if empty \u2014 Chrome 92+ populates them natively) \u2500\u2500\n  p(function() {\n    if (navigator.plugins && navigator.plugins.length > 0) return;\n\n    function FakePlugin(name, fn, desc, mimes) {\n      this.name = name; this.filename = fn; this.description = desc; this.length = mimes.length;\n      for (var i = 0; i < mimes.length; i++) { this[i] = mimes[i]; mimes[i].enabledPlugin = this; }\n    }\n    FakePlugin.prototype.item = function(i) { return this[i] || null; };\n    FakePlugin.prototype.namedItem = function(n) {\n      for (var i = 0; i < this.length; i++) if (this[i].type === n) return this[i];\n      return null;\n    };\n\n    function M(type, suf, desc) { this.type = type; this.suffixes = suf; this.description = desc; }\n\n    var m1 = new M('application/pdf', 'pdf', 'Portable Document Format');\n    var m2 = new M('application/x-google-chrome-pdf', 'pdf', 'Portable Document Format');\n    var m3 = new M('application/x-nacl', '', 'Native Client Executable');\n    var m4 = new M('application/x-pnacl', '', 'Portable Native Client Executable');\n\n    var plugins = [\n      new FakePlugin('Chrome PDF Plugin', 'internal-pdf-viewer', 'Portable Document Format', [m1]),\n      new FakePlugin('Chrome PDF Viewer', 'mhjfbmdgcfjbbpaeojofohoefgiehjai', '', [m2]),\n      new FakePlugin('Native Client', 'internal-nacl-plugin', '', [m3, m4]),\n    ];\n\n    function makeIterable(arr, items) {\n      arr.length = items.length;\n      for (var i = 0; i < items.length; i++) arr[i] = items[i];\n      arr[Symbol.iterator] = function() {\n        var idx = 0;\n        return { next: function() {\n          return idx < items.length ? { value: items[idx++], done: false } : { done: true };\n        }};\n      };\n    }\n\n    var pa = { item: function(i) { return plugins[i] || null; },\n      namedItem: function(n) { for (var i = 0; i < plugins.length; i++) if (plugins[i].name === n) return plugins[i]; return null; },\n      refresh: function() {} };\n    makeIterable(pa, plugins);\n    Object.defineProperty(navigator, 'plugins', { get: function() { return pa; } });\n\n    var allMimes = [m1, m2, m3, m4];\n    var ma = { item: function(i) { return allMimes[i] || null; },\n      namedItem: function(n) { for (var i = 0; i < allMimes.length; i++) if (allMimes[i].type === n) return allMimes[i]; return null; } };\n    makeIterable(ma, allMimes);\n    Object.defineProperty(navigator, 'mimeTypes', { get: function() { return ma; } });\n  });\n\n  // \u2500\u2500 3. navigator.languages (cached + frozen so identity check passes) \u2500\u2500\n  p(function() {\n    if (!navigator.languages || navigator.languages.length === 0) {\n      var langs = Object.freeze(['en-US', 'en']);\n      Object.defineProperty(navigator, 'languages', { get: function() { return langs; } });\n    }\n  });\n\n  // \u2500\u2500 4. window.chrome \u2500\u2500\n  p(function() {\n    if (window.chrome && window.chrome.runtime && window.chrome.runtime.connect) return;\n\n    var chrome = window.chrome || {};\n    var noop = function() {};\n    var evtStub = { addListener: noop, removeListener: noop, hasListeners: function() { return false; } };\n    chrome.runtime = chrome.runtime || {};\n    chrome.runtime.onMessage = chrome.runtime.onMessage || evtStub;\n    chrome.runtime.onConnect = chrome.runtime.onConnect || evtStub;\n    chrome.runtime.sendMessage = chrome.runtime.sendMessage || noop;\n    chrome.runtime.connect = chrome.runtime.connect || function() {\n      return { onMessage: { addListener: noop }, postMessage: noop, disconnect: noop };\n    };\n    if (chrome.runtime.id === undefined) chrome.runtime.id = undefined;\n    if (!chrome.loadTimes) chrome.loadTimes = function() { return {}; };\n    if (!chrome.csi) chrome.csi = function() { return {}; };\n    if (!chrome.app) {\n      chrome.app = {\n        isInstalled: false,\n        InstallState: { INSTALLED: 'installed', NOT_INSTALLED: 'not_installed', DISABLED: 'disabled' },\n        RunningState: { CANNOT_RUN: 'cannot_run', READY_TO_RUN: 'ready_to_run', RUNNING: 'running' },\n        getDetails: function() { return null; },\n        getIsInstalled: function() { return false; },\n        runningState: function() { return 'cannot_run'; },\n      };\n    }\n\n    if (!window.chrome) {\n      Object.defineProperty(window, 'chrome', { value: chrome, writable: false, enumerable: true, configurable: false });\n    }\n  });\n\n  // \u2500\u2500 5. Permissions API consistency \u2500\u2500\n  p(function() {\n    var orig = navigator.permissions.query.bind(navigator.permissions);\n    function q(params) {\n      if (params.name === 'notifications') {\n        return Promise.resolve({\n          state: typeof Notification !== 'undefined' ? Notification.permission : 'prompt',\n          name: 'notifications', onchange: null,\n          addEventListener: function(){}, removeEventListener: function(){}, dispatchEvent: function(){ return true; },\n        });\n      }\n      return orig(params);\n    }\n    q.toString = function() { return 'function query() { [native code] }'; };\n    navigator.permissions.query = q;\n  });\n\n  // \u2500\u2500 6. WebGL vendor / renderer \u2500\u2500\n  p(function() {\n    var h = {\n      apply: function(target, self, args) {\n        var param = args[0];\n        if (param === 0x9245) return 'Intel Inc.';\n        if (param === 0x9246) return 'Intel Iris OpenGL Engine';\n        return Reflect.apply(target, self, args);\n      }\n    };\n    if (typeof WebGLRenderingContext !== 'undefined')\n      WebGLRenderingContext.prototype.getParameter = new Proxy(WebGLRenderingContext.prototype.getParameter, h);\n    if (typeof WebGL2RenderingContext !== 'undefined')\n      WebGL2RenderingContext.prototype.getParameter = new Proxy(WebGL2RenderingContext.prototype.getParameter, h);\n  });\n\n  // \u2500\u2500 7. Notification.permission \u2500\u2500\n  p(function() {\n    if (typeof Notification !== 'undefined' && Notification.permission === 'denied') {\n      Object.defineProperty(Notification, 'permission', { get: function() { return 'default'; }, configurable: true });\n    }\n  });\n\n  // \u2500\u2500 8. navigator.connection (cached so identity check passes) \u2500\u2500\n  p(function() {\n    if (navigator.connection) return;\n    var conn = {\n      effectiveType: '4g', rtt: 50, downlink: 10, saveData: false, onchange: null,\n      addEventListener: function(){}, removeEventListener: function(){}, dispatchEvent: function(){ return true; },\n    };\n    Object.defineProperty(navigator, 'connection', { get: function() { return conn; } });\n  });\n\n  // \u2500\u2500 9. Iframe contentWindow.chrome \u2500\u2500\n  // Handled by patch 4 \u2014 chrome object is now on window, propagates to iframes on same origin.\n\n  // \u2500\u2500 10. console method toString \u2500\u2500\n  p(function() {\n    ['log','info','warn','error','debug','table','trace'].forEach(function(n) {\n      if (console[n]) {\n        console[n].toString = function() { return 'function ' + n + '() { [native code] }'; };\n      }\n    });\n  });\n\n  // \u2500\u2500 11. Headless-mode window / screen fixes \u2500\u2500\n  p(function() {\n    if (window.outerWidth === 0)\n      Object.defineProperty(window, 'outerWidth', { get: function() { return window.innerWidth || 1920; } });\n    if (window.outerHeight === 0)\n      Object.defineProperty(window, 'outerHeight', { get: function() { return (window.innerHeight || 1080) + 85; } });\n  });\n\n  p(function() {\n    if (screen.colorDepth === 0) {\n      Object.defineProperty(screen, 'colorDepth', { get: function() { return 24; } });\n      Object.defineProperty(screen, 'pixelDepth', { get: function() { return 24; } });\n    }\n  });\n\n  // \u2500\u2500 12. navigator.hardwareConcurrency \u2500\u2500\n  p(function() {\n    if (!navigator.hardwareConcurrency)\n      Object.defineProperty(navigator, 'hardwareConcurrency', { get: function() { return 4; } });\n  });\n\n  // \u2500\u2500 13. navigator.deviceMemory \u2500\u2500\n  p(function() {\n    if (!navigator.deviceMemory)\n      Object.defineProperty(navigator, 'deviceMemory', { get: function() { return 8; } });\n  });\n})()";
+
+/**
+ * Detect whether the current page is showing an anti-bot challenge.
+ * Returns `null` if no challenge is detected.
+ */
+declare function detectChallengeViaPlaywright(opts: {
+    cdpUrl: string;
+    targetId?: string;
+}): Promise<ChallengeInfo | null>;
+/**
+ * Wait for an anti-bot challenge to resolve on its own (e.g. Cloudflare JS challenge).
+ *
+ * Returns `{ resolved: true }` if the challenge cleared within the timeout,
+ * or `{ resolved: false, challenge }` with the still-present challenge info.
+ *
+ * For challenges that require human interaction (CAPTCHA), this will time out
+ * unless the user solves the challenge in the visible browser window.
+ */
+declare function waitForChallengeViaPlaywright(opts: {
+    cdpUrl: string;
+    targetId?: string;
+    timeoutMs?: number;
+    pollMs?: number;
+}): Promise<ChallengeWaitResult>;
+
+export { type AriaNode, type AriaSnapshotResult, type BatchAction, type BatchActionResult, BrowserClaw, type BrowserNavigationPolicyOptions, type BrowserNavigationRequestLike, type BrowserTab, BrowserTabNotFoundError, type ChallengeInfo, type ChallengeKind, type ChallengeWaitResult, type ChromeExecutable, type ChromeKind, type ClickOptions, type ColorScheme, type ConnectOptions, type ConsoleMessage, type ContextState, type CookieData, CrawlPage, type DialogOptions, type DownloadResult, type FormField, type FrameEvalResult, type GeolocationOptions, type HttpCredentials, InvalidBrowserNavigationUrlError, type LaunchOptions, type LookupFn, type NetworkRequest, type PageError, type PinnedHostname, type ResponseBodyResult, type RoleRefInfo, type RoleRefs, STEALTH_SCRIPT, type ScreenshotOptions, type SnapshotOptions, type SnapshotResult, type SnapshotStats, type SsrfPolicy, type StorageKind, type TraceStartOptions, type TypeOptions, type UntrustedContentMeta, type WaitOptions, 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, waitForChallengeViaPlaywright, withBrowserNavigationPolicy, withPageScopedCdpClient, withPlaywrightPageCdpSession, writeViaSiblingTempPath };

package/dist/index.d.ts

@@ -1,8 +1,6 @@
-import * as playwright_core from 'playwright-core';
 import { BrowserContext, Page, CDPSession } from 'playwright-core';
-import * as node_dns from 'node:dns';
-import { lookup as lookup$1 } from 'node:dns';
-import { lookup } from 'node:dns/promises';
+import { lookup } from 'node:dns';
+import { lookup as lookup$1 } from 'node:dns/promises';
 
 /** A single action within a batch. */
 type BatchAction = {
@@ -58,11 +56,11 @@ type BatchAction = {
     timeoutMs?: number;
 } | {
     kind: 'fill';
-    fields: Array<{
+    fields: {
         ref: string;
         type?: string;
         value?: string | number | boolean;
-    }>;
+    }[];
     targetId?: string;
     timeoutMs?: number;
 } | {
@@ -547,11 +545,27 @@ interface HttpCredentials {
 interface ContextState {
     traceActive: boolean;
 }
+/** The kind of anti-bot challenge detected on a page. */
+type ChallengeKind = 'cloudflare-js' | 'cloudflare-block' | 'cloudflare-turnstile' | 'hcaptcha' | 'recaptcha' | 'blocked' | 'rate-limited';
+/** Information about a detected anti-bot challenge. */
+interface ChallengeInfo {
+    /** What type of challenge is present */
+    kind: ChallengeKind;
+    /** Human-readable description */
+    message: string;
+}
+/** Result of waiting for an anti-bot challenge to resolve. */
+interface ChallengeWaitResult {
+    /** Whether the challenge cleared within the timeout */
+    resolved: boolean;
+    /** The challenge still present (null if resolved) */
+    challenge: ChallengeInfo | null;
+}
 /** Result of DNS pinning resolution — hostname locked to resolved addresses. */
 interface PinnedHostname {
     hostname: string;
     addresses: string[];
-    lookup: typeof node_dns.lookup;
+    lookup: typeof lookup;
 }
 
 /**
@@ -925,7 +939,7 @@ declare class CrawlPage {
         type?: 'png' | 'jpeg';
     }): Promise<{
         buffer: Buffer;
-        labels: Array<{
+        labels: {
             ref: string;
             index: number;
             box: {
@@ -934,7 +948,7 @@ declare class CrawlPage {
                 width: number;
                 height: number;
             };
-        }>;
+        }[];
         skipped: string[];
     }>;
     /**
@@ -1022,7 +1036,7 @@ declare class CrawlPage {
      *
      * @returns Array of cookie objects
      */
-    cookies(): Promise<Awaited<ReturnType<playwright_core.BrowserContext['cookies']>>>;
+    cookies(): Promise<Awaited<ReturnType<BrowserContext['cookies']>>>;
     /**
      * Set a cookie in the browser context.
      *
@@ -1164,6 +1178,46 @@ declare class CrawlPage {
      * ```
      */
     setDevice(name: string): Promise<void>;
+    /**
+     * Detect whether the page is showing an anti-bot challenge
+     * (Cloudflare, hCaptcha, reCAPTCHA, access-denied, rate-limit, etc.).
+     *
+     * Returns `null` if no challenge is detected.
+     *
+     * @example
+     * ```ts
+     * const challenge = await page.detectChallenge();
+     * if (challenge) {
+     *   console.log(challenge.kind);    // 'cloudflare-js'
+     *   console.log(challenge.message); // 'Cloudflare JS challenge'
+     * }
+     * ```
+     */
+    detectChallenge(): Promise<ChallengeInfo | null>;
+    /**
+     * Wait for an anti-bot challenge to resolve on its own.
+     *
+     * Cloudflare JS challenges typically auto-resolve in ~5 seconds.
+     * CAPTCHA challenges will only resolve if solved in a visible browser window.
+     *
+     * @param opts.timeoutMs - Maximum wait time (default: `15000`)
+     * @param opts.pollMs - Poll interval (default: `500`)
+     * @returns Whether the challenge resolved, and the remaining challenge info if not
+     *
+     * @example
+     * ```ts
+     * await page.goto('https://example.com');
+     * const challenge = await page.detectChallenge();
+     * if (challenge?.kind === 'cloudflare-js') {
+     *   const { resolved } = await page.waitForChallenge({ timeoutMs: 20000 });
+     *   if (!resolved) throw new Error('Challenge did not resolve');
+     * }
+     * ```
+     */
+    waitForChallenge(opts?: {
+        timeoutMs?: number;
+        pollMs?: number;
+    }): Promise<ChallengeWaitResult>;
 }
 /**
  * Main entry point for browserclaw.
@@ -1296,7 +1350,7 @@ declare function isChromeReachable(cdpUrl: string, timeoutMs?: number, authToken
 declare function getChromeWebSocketUrl(cdpUrl: string, timeoutMs?: number, authToken?: string): Promise<string | null>;
 declare function isChromeCdpReady(cdpUrl: string, timeoutMs?: number, handshakeTimeoutMs?: number): Promise<boolean>;
 
-type LookupFn = typeof lookup;
+type LookupFn = typeof lookup$1;
 /**
  * Thrown when a navigation URL is blocked by SSRF policy.
  * Callers can catch this specifically to distinguish navigation blocks
@@ -1306,14 +1360,14 @@ declare class InvalidBrowserNavigationUrlError extends Error {
     constructor(message: string);
 }
 /** Options for browser navigation SSRF policy. */
-type BrowserNavigationPolicyOptions = {
+interface BrowserNavigationPolicyOptions {
     ssrfPolicy?: SsrfPolicy;
-};
+}
 /** Playwright-compatible request interface for redirect chain inspection. */
-type BrowserNavigationRequestLike = {
+interface BrowserNavigationRequestLike {
     url(): string;
     redirectedFrom(): BrowserNavigationRequestLike | null;
-};
+}
 /** Build a BrowserNavigationPolicyOptions from an SsrfPolicy. */
 declare function withBrowserNavigationPolicy(ssrfPolicy?: SsrfPolicy): BrowserNavigationPolicyOptions;
 /**
@@ -1323,8 +1377,8 @@ declare function withBrowserNavigationPolicy(ssrfPolicy?: SsrfPolicy): BrowserNa
 declare function createPinnedLookup(params: {
     hostname: string;
     addresses: string[];
-    fallback?: typeof lookup$1;
-}): typeof lookup$1;
+    fallback?: typeof lookup;
+}): typeof lookup;
 /**
  * Resolve DNS for a hostname and validate resolved addresses against SSRF policy.
  * Returns a PinnedHostname with pre-resolved addresses and a pinned lookup function.
@@ -1401,14 +1455,12 @@ declare class BrowserTabNotFoundError extends Error {
 declare function withPlaywrightPageCdpSession<T>(page: Page, fn: (session: CDPSession) => Promise<T>): Promise<T>;
 /**
  * Run a function with a page-scoped CDP client.
- * For extension relay endpoints, routes through the raw CDP websocket.
- * Otherwise, uses a Playwright CDP session.
  */
 declare function withPageScopedCdpClient<T>(opts: {
     cdpUrl: string;
     page: Page;
     targetId?: string;
-    fn: (send: (method: string, params?: Record<string, unknown>) => Promise<any>) => Promise<T>;
+    fn: (send: (method: string, params?: Record<string, unknown>) => Promise<unknown>) => Promise<T>;
 }): Promise<T>;
 declare function ensureContextState(context: BrowserContext): ContextState;
 /**
@@ -1458,4 +1510,42 @@ declare function getRestoredPageForTarget(opts: {
     targetId?: string;
 }): Promise<Page>;
 
-export { type AriaNode, type AriaSnapshotResult, type BatchAction, type BatchActionResult, BrowserClaw, type BrowserNavigationPolicyOptions, type BrowserNavigationRequestLike, type BrowserTab, BrowserTabNotFoundError, type ChromeExecutable, type ChromeKind, type ClickOptions, type ColorScheme, type ConnectOptions, type ConsoleMessage, type ContextState, type CookieData, CrawlPage, type DialogOptions, type DownloadResult, type FormField, type FrameEvalResult, type GeolocationOptions, type HttpCredentials, InvalidBrowserNavigationUrlError, type LaunchOptions, type LookupFn, type NetworkRequest, type PageError, type PinnedHostname, type ResponseBodyResult, type RoleRefInfo, type RoleRefs, type ScreenshotOptions, type SnapshotOptions, type SnapshotResult, type SnapshotStats, type SsrfPolicy, type StorageKind, type TraceStartOptions, type TypeOptions, type UntrustedContentMeta, type WaitOptions, assertBrowserNavigationAllowed, assertBrowserNavigationRedirectChainAllowed, assertBrowserNavigationResultAllowed, assertSafeUploadPaths, batchViaPlaywright, createPinnedLookup, ensureContextState, executeSingleAction, forceDisconnectPlaywrightForTarget, getChromeWebSocketUrl, getRestoredPageForTarget, isChromeCdpReady, isChromeReachable, normalizeCdpHttpBaseForJsonEndpoints, parseRoleRef, requireRef, requireRefOrSelector, requiresInspectableBrowserNavigationRedirects, resolveBoundedDelayMs, resolveInteractionTimeoutMs, resolvePageByTargetIdOrThrow, resolvePinnedHostnameWithPolicy, resolveStrictExistingUploadPaths, sanitizeUntrustedFileName, withBrowserNavigationPolicy, withPageScopedCdpClient, withPlaywrightPageCdpSession, writeViaSiblingTempPath };
+/**
+ * Comprehensive browser stealth evasions.
+ *
+ * Injected via `addInitScript()` (runs before any page JS) and via
+ * `page.evaluate()` for already-loaded pages. Each patch is wrapped
+ * in try/catch so a single failure never breaks the rest.
+ *
+ * Covers: navigator.webdriver, plugins, languages, window.chrome,
+ * Permissions API, WebGL fingerprint, Notification.permission,
+ * navigator.connection, console toString, headless-mode quirks,
+ * hardwareConcurrency, and deviceMemory.
+ */
+declare const STEALTH_SCRIPT = "(function() {\n  'use strict';\n  function p(fn) { try { fn(); } catch(_) {} }\n\n  // \u2500\u2500 1. navigator.webdriver \u2192 undefined \u2500\u2500\n  p(function() {\n    Object.defineProperty(navigator, 'webdriver', { get: function() { return undefined; }, configurable: true });\n  });\n\n  // \u2500\u2500 2. navigator.plugins + mimeTypes (only if empty \u2014 Chrome 92+ populates them natively) \u2500\u2500\n  p(function() {\n    if (navigator.plugins && navigator.plugins.length > 0) return;\n\n    function FakePlugin(name, fn, desc, mimes) {\n      this.name = name; this.filename = fn; this.description = desc; this.length = mimes.length;\n      for (var i = 0; i < mimes.length; i++) { this[i] = mimes[i]; mimes[i].enabledPlugin = this; }\n    }\n    FakePlugin.prototype.item = function(i) { return this[i] || null; };\n    FakePlugin.prototype.namedItem = function(n) {\n      for (var i = 0; i < this.length; i++) if (this[i].type === n) return this[i];\n      return null;\n    };\n\n    function M(type, suf, desc) { this.type = type; this.suffixes = suf; this.description = desc; }\n\n    var m1 = new M('application/pdf', 'pdf', 'Portable Document Format');\n    var m2 = new M('application/x-google-chrome-pdf', 'pdf', 'Portable Document Format');\n    var m3 = new M('application/x-nacl', '', 'Native Client Executable');\n    var m4 = new M('application/x-pnacl', '', 'Portable Native Client Executable');\n\n    var plugins = [\n      new FakePlugin('Chrome PDF Plugin', 'internal-pdf-viewer', 'Portable Document Format', [m1]),\n      new FakePlugin('Chrome PDF Viewer', 'mhjfbmdgcfjbbpaeojofohoefgiehjai', '', [m2]),\n      new FakePlugin('Native Client', 'internal-nacl-plugin', '', [m3, m4]),\n    ];\n\n    function makeIterable(arr, items) {\n      arr.length = items.length;\n      for (var i = 0; i < items.length; i++) arr[i] = items[i];\n      arr[Symbol.iterator] = function() {\n        var idx = 0;\n        return { next: function() {\n          return idx < items.length ? { value: items[idx++], done: false } : { done: true };\n        }};\n      };\n    }\n\n    var pa = { item: function(i) { return plugins[i] || null; },\n      namedItem: function(n) { for (var i = 0; i < plugins.length; i++) if (plugins[i].name === n) return plugins[i]; return null; },\n      refresh: function() {} };\n    makeIterable(pa, plugins);\n    Object.defineProperty(navigator, 'plugins', { get: function() { return pa; } });\n\n    var allMimes = [m1, m2, m3, m4];\n    var ma = { item: function(i) { return allMimes[i] || null; },\n      namedItem: function(n) { for (var i = 0; i < allMimes.length; i++) if (allMimes[i].type === n) return allMimes[i]; return null; } };\n    makeIterable(ma, allMimes);\n    Object.defineProperty(navigator, 'mimeTypes', { get: function() { return ma; } });\n  });\n\n  // \u2500\u2500 3. navigator.languages (cached + frozen so identity check passes) \u2500\u2500\n  p(function() {\n    if (!navigator.languages || navigator.languages.length === 0) {\n      var langs = Object.freeze(['en-US', 'en']);\n      Object.defineProperty(navigator, 'languages', { get: function() { return langs; } });\n    }\n  });\n\n  // \u2500\u2500 4. window.chrome \u2500\u2500\n  p(function() {\n    if (window.chrome && window.chrome.runtime && window.chrome.runtime.connect) return;\n\n    var chrome = window.chrome || {};\n    var noop = function() {};\n    var evtStub = { addListener: noop, removeListener: noop, hasListeners: function() { return false; } };\n    chrome.runtime = chrome.runtime || {};\n    chrome.runtime.onMessage = chrome.runtime.onMessage || evtStub;\n    chrome.runtime.onConnect = chrome.runtime.onConnect || evtStub;\n    chrome.runtime.sendMessage = chrome.runtime.sendMessage || noop;\n    chrome.runtime.connect = chrome.runtime.connect || function() {\n      return { onMessage: { addListener: noop }, postMessage: noop, disconnect: noop };\n    };\n    if (chrome.runtime.id === undefined) chrome.runtime.id = undefined;\n    if (!chrome.loadTimes) chrome.loadTimes = function() { return {}; };\n    if (!chrome.csi) chrome.csi = function() { return {}; };\n    if (!chrome.app) {\n      chrome.app = {\n        isInstalled: false,\n        InstallState: { INSTALLED: 'installed', NOT_INSTALLED: 'not_installed', DISABLED: 'disabled' },\n        RunningState: { CANNOT_RUN: 'cannot_run', READY_TO_RUN: 'ready_to_run', RUNNING: 'running' },\n        getDetails: function() { return null; },\n        getIsInstalled: function() { return false; },\n        runningState: function() { return 'cannot_run'; },\n      };\n    }\n\n    if (!window.chrome) {\n      Object.defineProperty(window, 'chrome', { value: chrome, writable: false, enumerable: true, configurable: false });\n    }\n  });\n\n  // \u2500\u2500 5. Permissions API consistency \u2500\u2500\n  p(function() {\n    var orig = navigator.permissions.query.bind(navigator.permissions);\n    function q(params) {\n      if (params.name === 'notifications') {\n        return Promise.resolve({\n          state: typeof Notification !== 'undefined' ? Notification.permission : 'prompt',\n          name: 'notifications', onchange: null,\n          addEventListener: function(){}, removeEventListener: function(){}, dispatchEvent: function(){ return true; },\n        });\n      }\n      return orig(params);\n    }\n    q.toString = function() { return 'function query() { [native code] }'; };\n    navigator.permissions.query = q;\n  });\n\n  // \u2500\u2500 6. WebGL vendor / renderer \u2500\u2500\n  p(function() {\n    var h = {\n      apply: function(target, self, args) {\n        var param = args[0];\n        if (param === 0x9245) return 'Intel Inc.';\n        if (param === 0x9246) return 'Intel Iris OpenGL Engine';\n        return Reflect.apply(target, self, args);\n      }\n    };\n    if (typeof WebGLRenderingContext !== 'undefined')\n      WebGLRenderingContext.prototype.getParameter = new Proxy(WebGLRenderingContext.prototype.getParameter, h);\n    if (typeof WebGL2RenderingContext !== 'undefined')\n      WebGL2RenderingContext.prototype.getParameter = new Proxy(WebGL2RenderingContext.prototype.getParameter, h);\n  });\n\n  // \u2500\u2500 7. Notification.permission \u2500\u2500\n  p(function() {\n    if (typeof Notification !== 'undefined' && Notification.permission === 'denied') {\n      Object.defineProperty(Notification, 'permission', { get: function() { return 'default'; }, configurable: true });\n    }\n  });\n\n  // \u2500\u2500 8. navigator.connection (cached so identity check passes) \u2500\u2500\n  p(function() {\n    if (navigator.connection) return;\n    var conn = {\n      effectiveType: '4g', rtt: 50, downlink: 10, saveData: false, onchange: null,\n      addEventListener: function(){}, removeEventListener: function(){}, dispatchEvent: function(){ return true; },\n    };\n    Object.defineProperty(navigator, 'connection', { get: function() { return conn; } });\n  });\n\n  // \u2500\u2500 9. Iframe contentWindow.chrome \u2500\u2500\n  // Handled by patch 4 \u2014 chrome object is now on window, propagates to iframes on same origin.\n\n  // \u2500\u2500 10. console method toString \u2500\u2500\n  p(function() {\n    ['log','info','warn','error','debug','table','trace'].forEach(function(n) {\n      if (console[n]) {\n        console[n].toString = function() { return 'function ' + n + '() { [native code] }'; };\n      }\n    });\n  });\n\n  // \u2500\u2500 11. Headless-mode window / screen fixes \u2500\u2500\n  p(function() {\n    if (window.outerWidth === 0)\n      Object.defineProperty(window, 'outerWidth', { get: function() { return window.innerWidth || 1920; } });\n    if (window.outerHeight === 0)\n      Object.defineProperty(window, 'outerHeight', { get: function() { return (window.innerHeight || 1080) + 85; } });\n  });\n\n  p(function() {\n    if (screen.colorDepth === 0) {\n      Object.defineProperty(screen, 'colorDepth', { get: function() { return 24; } });\n      Object.defineProperty(screen, 'pixelDepth', { get: function() { return 24; } });\n    }\n  });\n\n  // \u2500\u2500 12. navigator.hardwareConcurrency \u2500\u2500\n  p(function() {\n    if (!navigator.hardwareConcurrency)\n      Object.defineProperty(navigator, 'hardwareConcurrency', { get: function() { return 4; } });\n  });\n\n  // \u2500\u2500 13. navigator.deviceMemory \u2500\u2500\n  p(function() {\n    if (!navigator.deviceMemory)\n      Object.defineProperty(navigator, 'deviceMemory', { get: function() { return 8; } });\n  });\n})()";
+
+/**
+ * Detect whether the current page is showing an anti-bot challenge.
+ * Returns `null` if no challenge is detected.
+ */
+declare function detectChallengeViaPlaywright(opts: {
+    cdpUrl: string;
+    targetId?: string;
+}): Promise<ChallengeInfo | null>;
+/**
+ * Wait for an anti-bot challenge to resolve on its own (e.g. Cloudflare JS challenge).
+ *
+ * Returns `{ resolved: true }` if the challenge cleared within the timeout,
+ * or `{ resolved: false, challenge }` with the still-present challenge info.
+ *
+ * For challenges that require human interaction (CAPTCHA), this will time out
+ * unless the user solves the challenge in the visible browser window.
+ */
+declare function waitForChallengeViaPlaywright(opts: {
+    cdpUrl: string;
+    targetId?: string;
+    timeoutMs?: number;
+    pollMs?: number;
+}): Promise<ChallengeWaitResult>;
+
+export { type AriaNode, type AriaSnapshotResult, type BatchAction, type BatchActionResult, BrowserClaw, type BrowserNavigationPolicyOptions, type BrowserNavigationRequestLike, type BrowserTab, BrowserTabNotFoundError, type ChallengeInfo, type ChallengeKind, type ChallengeWaitResult, type ChromeExecutable, type ChromeKind, type ClickOptions, type ColorScheme, type ConnectOptions, type ConsoleMessage, type ContextState, type CookieData, CrawlPage, type DialogOptions, type DownloadResult, type FormField, type FrameEvalResult, type GeolocationOptions, type HttpCredentials, InvalidBrowserNavigationUrlError, type LaunchOptions, type LookupFn, type NetworkRequest, type PageError, type PinnedHostname, type ResponseBodyResult, type RoleRefInfo, type RoleRefs, STEALTH_SCRIPT, type ScreenshotOptions, type SnapshotOptions, type SnapshotResult, type SnapshotStats, type SsrfPolicy, type StorageKind, type TraceStartOptions, type TypeOptions, type UntrustedContentMeta, type WaitOptions, 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, waitForChallengeViaPlaywright, withBrowserNavigationPolicy, withPageScopedCdpClient, withPlaywrightPageCdpSession, writeViaSiblingTempPath };