browserclaw 0.6.0 → 0.7.1

package/dist/index.d.cts

@@ -545,6 +545,22 @@ 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;
@@ -1162,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.
@@ -1454,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

@@ -545,6 +545,22 @@ 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;
@@ -1162,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.
@@ -1454,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.js

@@ -1284,7 +1284,7 @@ async function fetchChromeVersion(cdpUrl, timeoutMs = 500, authToken) {
 async function isChromeReachable(cdpUrl, timeoutMs = 500, authToken) {
   if (isWebSocketUrl(cdpUrl)) return await canOpenWebSocket(cdpUrl, timeoutMs);
   const version = await fetchChromeVersion(cdpUrl, timeoutMs, authToken);
-  return Boolean(version);
+  return version !== null;
 }
 async function getChromeWebSocketUrl(cdpUrl, timeoutMs = 500, authToken) {
   if (isWebSocketUrl(cdpUrl)) return cdpUrl;
@@ -1476,6 +1476,198 @@ async function stopChrome(running, timeoutMs = 2500) {
   }
 }
 
+// src/stealth.ts
+var STEALTH_SCRIPT = `(function() {
+  'use strict';
+  function p(fn) { try { fn(); } catch(_) {} }
+
+  // \u2500\u2500 1. navigator.webdriver \u2192 undefined \u2500\u2500
+  p(function() {
+    Object.defineProperty(navigator, 'webdriver', { get: function() { return undefined; }, configurable: true });
+  });
+
+  // \u2500\u2500 2. navigator.plugins + mimeTypes (only if empty \u2014 Chrome 92+ populates them natively) \u2500\u2500
+  p(function() {
+    if (navigator.plugins && navigator.plugins.length > 0) return;
+
+    function FakePlugin(name, fn, desc, mimes) {
+      this.name = name; this.filename = fn; this.description = desc; this.length = mimes.length;
+      for (var i = 0; i < mimes.length; i++) { this[i] = mimes[i]; mimes[i].enabledPlugin = this; }
+    }
+    FakePlugin.prototype.item = function(i) { return this[i] || null; };
+    FakePlugin.prototype.namedItem = function(n) {
+      for (var i = 0; i < this.length; i++) if (this[i].type === n) return this[i];
+      return null;
+    };
+
+    function M(type, suf, desc) { this.type = type; this.suffixes = suf; this.description = desc; }
+
+    var m1 = new M('application/pdf', 'pdf', 'Portable Document Format');
+    var m2 = new M('application/x-google-chrome-pdf', 'pdf', 'Portable Document Format');
+    var m3 = new M('application/x-nacl', '', 'Native Client Executable');
+    var m4 = new M('application/x-pnacl', '', 'Portable Native Client Executable');
+
+    var plugins = [
+      new FakePlugin('Chrome PDF Plugin', 'internal-pdf-viewer', 'Portable Document Format', [m1]),
+      new FakePlugin('Chrome PDF Viewer', 'mhjfbmdgcfjbbpaeojofohoefgiehjai', '', [m2]),
+      new FakePlugin('Native Client', 'internal-nacl-plugin', '', [m3, m4]),
+    ];
+
+    function makeIterable(arr, items) {
+      arr.length = items.length;
+      for (var i = 0; i < items.length; i++) arr[i] = items[i];
+      arr[Symbol.iterator] = function() {
+        var idx = 0;
+        return { next: function() {
+          return idx < items.length ? { value: items[idx++], done: false } : { done: true };
+        }};
+      };
+    }
+
+    var pa = { item: function(i) { return plugins[i] || null; },
+      namedItem: function(n) { for (var i = 0; i < plugins.length; i++) if (plugins[i].name === n) return plugins[i]; return null; },
+      refresh: function() {} };
+    makeIterable(pa, plugins);
+    Object.defineProperty(navigator, 'plugins', { get: function() { return pa; } });
+
+    var allMimes = [m1, m2, m3, m4];
+    var ma = { item: function(i) { return allMimes[i] || null; },
+      namedItem: function(n) { for (var i = 0; i < allMimes.length; i++) if (allMimes[i].type === n) return allMimes[i]; return null; } };
+    makeIterable(ma, allMimes);
+    Object.defineProperty(navigator, 'mimeTypes', { get: function() { return ma; } });
+  });
+
+  // \u2500\u2500 3. navigator.languages (cached + frozen so identity check passes) \u2500\u2500
+  p(function() {
+    if (!navigator.languages || navigator.languages.length === 0) {
+      var langs = Object.freeze(['en-US', 'en']);
+      Object.defineProperty(navigator, 'languages', { get: function() { return langs; } });
+    }
+  });
+
+  // \u2500\u2500 4. window.chrome \u2500\u2500
+  p(function() {
+    if (window.chrome && window.chrome.runtime && window.chrome.runtime.connect) return;
+
+    var chrome = window.chrome || {};
+    var noop = function() {};
+    var evtStub = { addListener: noop, removeListener: noop, hasListeners: function() { return false; } };
+    chrome.runtime = chrome.runtime || {};
+    chrome.runtime.onMessage = chrome.runtime.onMessage || evtStub;
+    chrome.runtime.onConnect = chrome.runtime.onConnect || evtStub;
+    chrome.runtime.sendMessage = chrome.runtime.sendMessage || noop;
+    chrome.runtime.connect = chrome.runtime.connect || function() {
+      return { onMessage: { addListener: noop }, postMessage: noop, disconnect: noop };
+    };
+    if (chrome.runtime.id === undefined) chrome.runtime.id = undefined;
+    if (!chrome.loadTimes) chrome.loadTimes = function() { return {}; };
+    if (!chrome.csi) chrome.csi = function() { return {}; };
+    if (!chrome.app) {
+      chrome.app = {
+        isInstalled: false,
+        InstallState: { INSTALLED: 'installed', NOT_INSTALLED: 'not_installed', DISABLED: 'disabled' },
+        RunningState: { CANNOT_RUN: 'cannot_run', READY_TO_RUN: 'ready_to_run', RUNNING: 'running' },
+        getDetails: function() { return null; },
+        getIsInstalled: function() { return false; },
+        runningState: function() { return 'cannot_run'; },
+      };
+    }
+
+    if (!window.chrome) {
+      Object.defineProperty(window, 'chrome', { value: chrome, writable: false, enumerable: true, configurable: false });
+    }
+  });
+
+  // \u2500\u2500 5. Permissions API consistency \u2500\u2500
+  p(function() {
+    var orig = navigator.permissions.query.bind(navigator.permissions);
+    function q(params) {
+      if (params.name === 'notifications') {
+        return Promise.resolve({
+          state: typeof Notification !== 'undefined' ? Notification.permission : 'prompt',
+          name: 'notifications', onchange: null,
+          addEventListener: function(){}, removeEventListener: function(){}, dispatchEvent: function(){ return true; },
+        });
+      }
+      return orig(params);
+    }
+    q.toString = function() { return 'function query() { [native code] }'; };
+    navigator.permissions.query = q;
+  });
+
+  // \u2500\u2500 6. WebGL vendor / renderer \u2500\u2500
+  p(function() {
+    var h = {
+      apply: function(target, self, args) {
+        var param = args[0];
+        if (param === 0x9245) return 'Intel Inc.';
+        if (param === 0x9246) return 'Intel Iris OpenGL Engine';
+        return Reflect.apply(target, self, args);
+      }
+    };
+    if (typeof WebGLRenderingContext !== 'undefined')
+      WebGLRenderingContext.prototype.getParameter = new Proxy(WebGLRenderingContext.prototype.getParameter, h);
+    if (typeof WebGL2RenderingContext !== 'undefined')
+      WebGL2RenderingContext.prototype.getParameter = new Proxy(WebGL2RenderingContext.prototype.getParameter, h);
+  });
+
+  // \u2500\u2500 7. Notification.permission \u2500\u2500
+  p(function() {
+    if (typeof Notification !== 'undefined' && Notification.permission === 'denied') {
+      Object.defineProperty(Notification, 'permission', { get: function() { return 'default'; }, configurable: true });
+    }
+  });
+
+  // \u2500\u2500 8. navigator.connection (cached so identity check passes) \u2500\u2500
+  p(function() {
+    if (navigator.connection) return;
+    var conn = {
+      effectiveType: '4g', rtt: 50, downlink: 10, saveData: false, onchange: null,
+      addEventListener: function(){}, removeEventListener: function(){}, dispatchEvent: function(){ return true; },
+    };
+    Object.defineProperty(navigator, 'connection', { get: function() { return conn; } });
+  });
+
+  // \u2500\u2500 9. Iframe contentWindow.chrome \u2500\u2500
+  // Handled by patch 4 \u2014 chrome object is now on window, propagates to iframes on same origin.
+
+  // \u2500\u2500 10. console method toString \u2500\u2500
+  p(function() {
+    ['log','info','warn','error','debug','table','trace'].forEach(function(n) {
+      if (console[n]) {
+        console[n].toString = function() { return 'function ' + n + '() { [native code] }'; };
+      }
+    });
+  });
+
+  // \u2500\u2500 11. Headless-mode window / screen fixes \u2500\u2500
+  p(function() {
+    if (window.outerWidth === 0)
+      Object.defineProperty(window, 'outerWidth', { get: function() { return window.innerWidth || 1920; } });
+    if (window.outerHeight === 0)
+      Object.defineProperty(window, 'outerHeight', { get: function() { return (window.innerHeight || 1080) + 85; } });
+  });
+
+  p(function() {
+    if (screen.colorDepth === 0) {
+      Object.defineProperty(screen, 'colorDepth', { get: function() { return 24; } });
+      Object.defineProperty(screen, 'pixelDepth', { get: function() { return 24; } });
+    }
+  });
+
+  // \u2500\u2500 12. navigator.hardwareConcurrency \u2500\u2500
+  p(function() {
+    if (!navigator.hardwareConcurrency)
+      Object.defineProperty(navigator, 'hardwareConcurrency', { get: function() { return 4; } });
+  });
+
+  // \u2500\u2500 13. navigator.deviceMemory \u2500\u2500
+  p(function() {
+    if (!navigator.deviceMemory)
+      Object.defineProperty(navigator, 'deviceMemory', { get: function() { return 8; } });
+  });
+})()`;
+
 // src/connection.ts
 var BrowserTabNotFoundError = class extends Error {
   constructor(message = "Tab not found") {
@@ -1716,7 +1908,6 @@ function ensurePageState(page) {
   }
   return state;
 }
-var STEALTH_SCRIPT = `Object.defineProperty(navigator, 'webdriver', { get: () => undefined })`;
 function applyStealthToPage(page) {
   page.evaluate(STEALTH_SCRIPT).catch((e) => {
     if (process.env.DEBUG !== void 0 && process.env.DEBUG !== "")
@@ -1838,6 +2029,8 @@ async function disconnectBrowser() {
     }
   }
   for (const cur of cachedByCdpUrl.values()) {
+    if (cur.onDisconnected && typeof cur.browser.off === "function")
+      cur.browser.off("disconnected", cur.onDisconnected);
     await cur.browser.close().catch(() => {
     });
   }
@@ -3536,6 +3729,99 @@ async function setTimezoneViaPlaywright(opts) {
   });
 }
 
+// src/anti-bot.ts
+var DETECT_CHALLENGE_SCRIPT = `(function() {
+  var title = (document.title || '').toLowerCase();
+
+  // Cloudflare JS challenge
+  if (title === 'just a moment...'
+      || document.querySelector('#challenge-running, #cf-please-wait, #challenge-form')
+      || title.indexOf('checking your browser') !== -1) {
+    return { kind: 'cloudflare-js', message: 'Cloudflare JS challenge' };
+  }
+
+  // Cloudflare block page (needs body text \u2014 read lazily)
+  var body = null;
+  function getBody() { if (body === null) body = (document.body && document.body.textContent) || ''; return body; }
+
+  if (title.indexOf('attention required') !== -1
+      || (document.querySelector('.cf-error-details') && getBody().indexOf('blocked') !== -1)) {
+    return { kind: 'cloudflare-block', message: 'Cloudflare block page' };
+  }
+
+  // Cloudflare Turnstile
+  if (document.querySelector('.cf-turnstile, iframe[src*="challenges.cloudflare.com"]')) {
+    return { kind: 'cloudflare-turnstile', message: 'Cloudflare Turnstile challenge' };
+  }
+
+  // hCaptcha
+  if (document.querySelector('.h-captcha, iframe[src*="hcaptcha.com"]')) {
+    return { kind: 'hcaptcha', message: 'hCaptcha challenge' };
+  }
+
+  // reCAPTCHA
+  if (document.querySelector('.g-recaptcha, iframe[src*="google.com/recaptcha"]')) {
+    return { kind: 'recaptcha', message: 'reCAPTCHA challenge' };
+  }
+
+  // Generic access-denied / rate-limit pages (only read body for short pages)
+  var b = getBody();
+  if (b.length < 5000) {
+    if (/access denied|403 forbidden/i.test(title) || /access denied/i.test(b)) {
+      return { kind: 'blocked', message: 'Access denied' };
+    }
+    if (/\\b429\\b/i.test(title) || /too many requests|rate limit/i.test(b)) {
+      return { kind: 'rate-limited', message: 'Rate limited' };
+    }
+  }
+
+  return null;
+})()`;
+function parseChallengeResult(raw) {
+  if (raw !== null && typeof raw === "object" && "kind" in raw) {
+    return raw;
+  }
+  return null;
+}
+async function detectChallengeViaPlaywright(opts) {
+  const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
+  ensurePageState(page);
+  return parseChallengeResult(await page.evaluate(DETECT_CHALLENGE_SCRIPT));
+}
+async function waitForChallengeViaPlaywright(opts) {
+  const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
+  ensurePageState(page);
+  const timeout = normalizeTimeoutMs(opts.timeoutMs, 15e3);
+  const poll = Math.max(250, Math.min(5e3, opts.pollMs ?? 500));
+  const detect = async () => parseChallengeResult(await page.evaluate(DETECT_CHALLENGE_SCRIPT));
+  const initial = await detect();
+  if (initial === null) return { resolved: true, challenge: null };
+  if (initial.kind === "cloudflare-js") {
+    try {
+      await page.waitForFunction(
+        "document.title.toLowerCase() !== 'just a moment...' && !document.querySelector('#challenge-running')",
+        void 0,
+        { timeout }
+      );
+      await page.waitForLoadState("domcontentloaded", { timeout: 5e3 }).catch(() => {
+      });
+      const after = await detect();
+      return { resolved: after === null, challenge: after };
+    } catch {
+      const after = await detect();
+      return { resolved: after === null, challenge: after };
+    }
+  }
+  const deadline = Date.now() + timeout;
+  while (Date.now() < deadline) {
+    await page.waitForTimeout(poll);
+    const current = await detect();
+    if (current === null) return { resolved: true, challenge: null };
+  }
+  const final = await detect();
+  return { resolved: final === null, challenge: final };
+}
+
 // src/capture/activity.ts
 function consolePriority(level) {
   switch (level) {
@@ -5140,6 +5426,53 @@ var CrawlPage = class {
       name
     });
   }
+  // ── Anti-Bot ──────────────────────────────────────────────────
+  /**
+   * 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'
+   * }
+   * ```
+   */
+  async detectChallenge() {
+    return detectChallengeViaPlaywright({ cdpUrl: this.cdpUrl, targetId: this.targetId });
+  }
+  /**
+   * 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');
+   * }
+   * ```
+   */
+  async waitForChallenge(opts) {
+    return waitForChallengeViaPlaywright({
+      cdpUrl: this.cdpUrl,
+      targetId: this.targetId,
+      timeoutMs: opts?.timeoutMs,
+      pollMs: opts?.pollMs
+    });
+  }
 };
 var BrowserClaw = class _BrowserClaw {
   cdpUrl;
@@ -5285,6 +5618,6 @@ var BrowserClaw = class _BrowserClaw {
   }
 };
 
-export { BrowserClaw, BrowserTabNotFoundError, CrawlPage, InvalidBrowserNavigationUrlError, 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 };
+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, waitForChallengeViaPlaywright, withBrowserNavigationPolicy, withPageScopedCdpClient, withPlaywrightPageCdpSession, writeViaSiblingTempPath };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map