barebrowse 0.17.0 → 0.19.1

package/src/firefox-page.js

@@ -23,6 +23,8 @@ import { scopedCookiesForUrl } from './auth.js';
 import { assertNavigable, assertUploadAllowed } from './url-guard.js';
 import { dismissConsentFirefox } from './consent-firefox.js';
 import { waitForNetworkIdleBiDi } from './network-idle.js';
+import { decideDialog, dialogLogEntry } from './dialog.js';
+import { isChallengePage, countNodes } from './challenge.js';
 
 /** BiDi/WebDriver normalized key values for named keys (U+E000 block). */
 const BIDI_KEYS = {
@@ -41,6 +43,9 @@ const BIDI_KEYS = {
  * @param {string} [opts.uploadDir] - When set, upload() rejects files outside this dir.
  * @param {boolean} [opts.incognito=false] - Clean session: injectCookies() is a no-op.
  * @param {boolean} [opts.consent=true] - Auto-dismiss cookie consent dialogs after goto().
+ * @param {boolean} [opts.hybrid=false] - Relaunch headed on a bot-challenge page and retry.
+ * @param {boolean} [opts.headed=false] - Whether the browser was launched headed (skips hybrid fallback).
+ * @param {?function(): Promise<{bidi: object, topContext: string}>} [opts.relaunchHeaded] - Hybrid relaunch hook (from connectFirefox).
  * @returns {Promise<object>} page object
  */
 export async function createFirefoxPage(bidi, opts = {}) {
@@ -49,6 +54,17 @@ export async function createFirefoxPage(bidi, opts = {}) {
   const uploadDir = opts.uploadDir || null;
   const incognito = !!opts.incognito;
   const consent = opts.consent !== false;
+  // Hybrid mode: on a bot-challenge page, relaunch headed and retry. The
+  // relaunch tears down this Firefox+BiDi and returns a fresh one, so the
+  // browser lifecycle is owned by connectFirefox, which supplies relaunchHeaded.
+  const hybrid = !!opts.hybrid;
+  const relaunchHeaded = opts.relaunchHeaded || null;
+  let currentlyHeaded = !!opts.headed; // already headed → no fallback needed
+  let botBlocked = false;
+  // Last injectCookies(url, opts) args, so a hybrid relaunch (a brand-new
+  // Firefox profile) can re-inject them — otherwise the headed retry loads
+  // unauthenticated, defeating hybrid on an auth-gated challenge page.
+  let lastInject = null;
   // The active browsing context. Starts at the initial tab; switchTab() points
   // it at another top-level context, so it's mutable and read via a getter.
   const { contexts } = await bidi.send('browsingContext.getTree', {});
@@ -170,29 +186,143 @@ export async function createFirefoxPage(bidi, opts = {}) {
     return Promise.race([p, t]).finally(() => clearTimeout(timer));
   }
 
+  // Download tracking, parity with the CDP `page.downloads` array. Firefox
+  // downloads land in `downloadDir` (a throwaway dir the caller sets via launch
+  // prefs — see connectFirefox / firefox.js), so `savedPath` is a real path the
+  // caller can read. BiDi emits browsingContext.downloadWillBegin (start) +
+  // downloadEnd (finish, with the actual filepath + status) — measured against
+  // real Firefox. Records mirror the CDP shape:
+  // { url, suggestedFilename, savedPath, state, totalBytes, receivedBytes }.
+  const downloads = [];
+  async function setupDownloads() {
+    await bidi.subscribe(['browsingContext.downloadWillBegin', 'browsingContext.downloadEnd']);
+    bidi.on('browsingContext.downloadWillBegin', (e) => {
+      downloads.push({
+        url: e.url,
+        suggestedFilename: e.suggestedFilename || '',
+        savedPath: null,
+        state: 'inProgress',
+        totalBytes: 0,
+        receivedBytes: 0,
+      });
+    });
+    bidi.on('browsingContext.downloadEnd', (e) => {
+      // Correlate to the most recent still-in-progress record for this URL.
+      const d = [...downloads].reverse().find((x) => x.url === e.url && x.state === 'inProgress');
+      if (!d) return;
+      // BiDi status is 'complete' | 'canceled'; normalize 'complete' to CDP's
+      // 'completed' so callers can branch on one vocabulary across engines.
+      d.state = e.status === 'complete' ? 'completed' : e.status || 'completed';
+      d.savedPath = e.filepath || null;
+    });
+  }
+
+  // JS dialog handling (alert/confirm/prompt/beforeunload), parity with the
+  // CDP path in index.js. The BiDi session is created with
+  // unhandledPromptBehavior:'ignore' (see bidi.js) so prompts stay open until
+  // we respond; setupDialogs() must run before the first navigation or an
+  // 'ignore' prompt would hang the page. Default: accept everything except
+  // beforeunload (dismiss = stay), mirroring the CDP default. A caller can
+  // override per-dialog via page.onDialog(handler).
+  const dialogLog = [];
+  let onDialogHandler = null;
+  async function setupDialogs() {
+    await bidi.subscribe(['browsingContext.userPromptOpened']);
+    bidi.on('browsingContext.userPromptOpened', async (e) => {
+      dialogLog.push(dialogLogEntry(e.type, e.message));
+      // Shared decision core with the CDP path (dialog.js). BiDi's userText is
+      // the CDP promptText; its defaultValue is the CDP defaultPrompt.
+      const { accept, promptText } = await decideDialog(
+        { type: e.type, message: e.message, defaultPrompt: e.defaultValue },
+        onDialogHandler,
+      );
+      try {
+        await bidi.send('browsingContext.handleUserPrompt', {
+          context: e.context, accept, userText: promptText,
+        });
+      } catch {
+        // Prompt already gone (closed by page JS / navigation). Nothing to do.
+      }
+    });
+  }
+
+  /**
+   * Wire all event subscriptions (dialogs, downloads, load) on the CURRENT
+   * bidi connection. Run once at construction, and again after a hybrid
+   * relaunch swaps in a fresh connection. Dialogs must be wired before any
+   * navigation (the 'ignore' capability would otherwise hang a prompt).
+   */
+  async function setupSubscriptions() {
+    await setupDialogs();
+    await setupDownloads();
+    await bidi.subscribe(['browsingContext.load']);
+  }
+
+  /**
+   * Post-navigation routine shared by goto() and the hybrid retry: settle for
+   * dynamic content, auto-dismiss consent (best-effort), then report whether
+   * the resulting page looks like a bot challenge.
+   */
+  async function afterNavigate() {
+    await new Promise((r) => setTimeout(r, 500));
+    // Build the tree ONCE and use it for both consent dismissal and challenge
+    // detection. A challenge page (Cloudflare/hCaptcha) never carries a consent
+    // banner, so dismissing consent can't flip the challenge verdict — reusing
+    // the pre-dismiss tree avoids a second full AX reconstruction per goto.
+    let root = null;
+    try { root = await buildTree(); } catch { /* null → treated as challenge */ }
+    if (consent && root) {
+      try { await dismissConsentFirefox(root, (ref) => pointerClick(ref)); }
+      catch { /* consent dismissal is best-effort */ }
+    }
+    return isChallengePage(root, countNodes(root));
+  }
+
   const page = {
     /** The BiDi escape hatch, analogous to connect()'s page.cdp. */
     get bidi() { return bidi; },
     /** The active browsing-context id (getter so it tracks switchTab). */
     get context() { return topContext; },
+    /** Whether the last goto() landed on a bot-challenge page (parity w/ CDP). */
+    get botBlocked() { return botBlocked; },
 
     async goto(url, timeout = 30000) {
       // Same navigation guard the CDP path enforces — block file:/chrome:/
       // view-source: and (optionally) private-network hosts before navigating.
       assertNavigable(url, urlGuard);
+      refContexts = new Map(); // refs from the previous page are now stale
       await withTimeout(
         bidi.send('browsingContext.navigate', { context: topContext, url, wait: 'complete' }),
         timeout, `goto(${url})`);
-      // Brief settle for dynamic/SPA content, matching the CDP path.
-      await new Promise((r) => setTimeout(r, 500));
-      // Auto-dismiss cookie consent, mirroring the CDP path (index.js runs
-      // dismissConsent right after navigate). Best-effort: a failure here must
-      // never fail the navigation.
-      if (consent) {
+      // Settle + consent + challenge detection (mirrors the CDP path).
+      botBlocked = await afterNavigate();
+
+      // Hybrid fallback: on a bot-challenge page, relaunch headed once and
+      // retry — a real display often clears an interstitial headless can't.
+      // Only when hybrid mode and we're still headless. relaunchHeaded (from
+      // connectFirefox) tears down this Firefox+BiDi and returns a fresh one.
+      if (botBlocked && hybrid && !currentlyHeaded && relaunchHeaded) {
         try {
-          const root = await buildTree();
-          if (root) await dismissConsentFirefox(root, (ref) => pointerClick(ref));
-        } catch { /* consent dismissal is best-effort */ }
+          const relaunched = await relaunchHeaded();
+          bidi = relaunched.bidi;          // rebind the closure — all inner fns follow
+          topContext = relaunched.topContext;
+          currentlyHeaded = true;
+          refContexts = new Map();
+          await setupSubscriptions();      // re-wire dialogs/downloads/load on the new bidi
+          // Re-inject cookies into the fresh profile BEFORE navigating, so the
+          // headed retry is authenticated (the relaunch is a new Firefox profile
+          // — the pre-relaunch session's cookies are gone).
+          if (lastInject) {
+            try { await page.injectCookies(lastInject.url, lastInject.cookieOpts); } catch { /* best-effort */ }
+          }
+          await withTimeout(
+            bidi.send('browsingContext.navigate', { context: topContext, url, wait: 'complete' }),
+            timeout, `goto(${url})`);
+          botBlocked = await afterNavigate();
+        } catch {
+          // Headed relaunch failed (no display?) — keep the headless result;
+          // botBlocked stays true so the caller can see it didn't clear.
+        }
       }
     },
 
@@ -263,6 +393,7 @@ export async function createFirefoxPage(bidi, opts = {}) {
      */
     async injectCookies(url, cookieOpts) {
       if (incognito) return 0;
+      lastInject = { url, cookieOpts }; // remember for a hybrid re-inject
       const cookies = scopedCookiesForUrl(url, { browser: cookieOpts?.browser });
       let injected = 0;
       for (const c of cookies) {
@@ -411,19 +542,72 @@ export async function createFirefoxPage(bidi, opts = {}) {
       return waitForNetworkIdleBiDi(bidi, idleOpts);
     },
 
-    // --- CDP-only surfaces, stubbed for daemon parity ---------------------
-    // The daemon (src/daemon.js) dispatches these unconditionally. On the
-    // Firefox/BiDi engine download tracking and dialog capture aren't wired
-    // (Phase 3/4), so the two logs are genuinely empty; the two actions are
-    // CDP-only and fail with a clear, intentional message instead of an
-    // incidental TypeError. Documented as a known gap in CHANGELOG.
-    get downloads() { return []; },
-    get dialogLog() { return []; },
-    async saveState() {
-      throw new Error('saveState() is not supported on the Firefox/BiDi engine (CDP-only)');
+    /** Downloads that began in this session (Phase 4 — see setupDownloads). */
+    get downloads() { return downloads; },
+
+    dialogLog,
+
+    /**
+     * Install a custom JS dialog handler, mirroring connect()'s page.onDialog.
+     * Called with `{ type, message, defaultPrompt }`; may return (sync or async)
+     * `{ accept: bool, promptText: string }` to override the auto-accept
+     * default. Pass null to restore default behavior.
+     */
+    onDialog(handler) {
+      onDialogHandler = handler;
     },
-    async waitForNavigation() {
-      throw new Error('waitForNavigation() is not supported on the Firefox/BiDi engine (CDP-only)');
+
+    /**
+     * Persist cookies + localStorage to a JSON file (parity with the CDP
+     * saveState). Cookies come from BiDi storage.getCookies (whose value is a
+     * `{type,value}` object) and are flattened to the CDP-symmetric shape so the
+     * file format matches across engines. Written 0600 — it holds session
+     * tokens, so a multi-user host must not be able to read another user's.
+     */
+    async saveState(filePath) {
+      const { cookies } = await bidi.send('storage.getCookies', {});
+      const flat = cookies.map((c) => {
+        const out = {
+          name: c.name,
+          value: c.value && typeof c.value === 'object' ? c.value.value : c.value,
+          domain: c.domain,
+          path: c.path,
+          secure: !!c.secure,
+          httpOnly: !!c.httpOnly,
+        };
+        if (c.sameSite && c.sameSite !== 'default') out.sameSite = c.sameSite;
+        if (c.expiry && c.expiry > 0) out.expires = c.expiry;
+        return out;
+      });
+      const lsRaw = await bidi
+        .evaluate(topContext, 'JSON.stringify(Object.fromEntries(Object.entries(localStorage)))', false)
+        .catch(() => '{}'); // opaque-origin pages (about:blank) throw — treat as empty
+      const state = { cookies: flat, localStorage: JSON.parse(lsRaw || '{}') };
+      const { writeFileSync, chmodSync } = await import('node:fs');
+      writeFileSync(filePath, JSON.stringify(state, null, 2), { mode: 0o600 });
+      try { chmodSync(filePath, 0o600); } catch { /* best effort if pre-existing */ }
+    },
+
+    /**
+     * Resolve when the active tab fires its next load event (parity with the
+     * CDP waitForNavigation → Page.loadEventFired). Scoped to topContext so a
+     * subframe load can't resolve it early. Falls back to a short settle delay
+     * for SPA navigations that fire no load event.
+     */
+    async waitForNavigation(timeout = 30000) {
+      try {
+        await /** @type {Promise<void>} */ (new Promise((resolve, reject) => {
+          const timer = setTimeout(() => { unsub(); reject(new Error('waitForNavigation timed out')); }, timeout);
+          const unsub = bidi.on('browsingContext.load', (e) => {
+            if (e.context !== topContext) return;
+            clearTimeout(timer); unsub(); resolve();
+          });
+        }));
+        refContexts = new Map(); // the DOM changed — old refs are stale
+      } catch {
+        // No load event (SPA pushState/replaceState) — settle for DOM updates.
+        await new Promise((r) => setTimeout(r, 500));
+      }
     },
 
     async close() {
@@ -441,5 +625,9 @@ export async function createFirefoxPage(bidi, opts = {}) {
     await new Promise((r) => setTimeout(r, 500));
   }
 
+  // Wire event subscriptions before returning — dialogs must precede any
+  // navigation so an 'ignore' prompt (see bidi.js capability) is never hung.
+  await setupSubscriptions();
+
   return page;
 }

package/src/firefox.js

@@ -97,6 +97,7 @@ export function findFirefox() {
  * @param {string} [opts.proxy] - Proxy 'host:port' or 'scheme://host:port'
  *   (http/https → HTTP+SSL proxy; socks/socks5/socks4 → SOCKS), via prefs
  * @param {{width:number,height:number}} [opts.viewport] - Initial window size
+ * @param {string} [opts.downloadDir] - Route downloads here (throwaway dir), no prompt
  * @returns {Promise<{wsUrl: string, process: import('node:child_process').ChildProcess, port: number, ownedProfileDir: string}>}
  */
 export async function launchFirefox(opts = {}) {
@@ -114,6 +115,20 @@ export async function launchFirefox(opts = {}) {
     'user_pref("geo.prompt.testing", true);',
     'user_pref("geo.prompt.testing.allow", true);',
   ];
+  if (opts.downloadDir) {
+    // Route downloads to a caller-owned throwaway dir (parity with CDP's
+    // Browser.setDownloadBehavior) and never prompt — folderList:2 = custom dir.
+    // JSON.stringify emits a fully-escaped JS string literal (quotes, backslashes
+    // AND newlines/control chars), so a path can't inject extra user_pref lines.
+    const dir = JSON.stringify(String(opts.downloadDir));
+    prefs.push(
+      'user_pref("browser.download.folderList", 2);',
+      `user_pref("browser.download.dir", ${dir});`,
+      'user_pref("browser.download.useDownloadDir", true);',
+      'user_pref("browser.download.manager.showWhenStarting", false);',
+      'user_pref("browser.download.always_ask_before_handling_new_types", false);',
+    );
+  }
   if (opts.proxy) {
     // Honor the scheme: a socks:// proxy must be wired as SOCKS, not HTTP —
     // otherwise SOCKS traffic is silently sent to an HTTP proxy and fails.

package/src/index.js

@@ -20,8 +20,11 @@ import { click as cdpClick, type as cdpType, scroll as cdpScroll, press as cdpPr
 import { dismissConsent } from './consent.js';
 import { applyStealth } from './stealth.js';
 import { applyFirefoxStealth } from './stealth-firefox.js';
-import { DEFAULT_BLOCKLIST } from './blocklist.js';
+import { applyFirefoxBlocklist } from './blocklist-firefox.js';
+import { resolveBlocklistPatterns } from './blocklist.js';
 import { waitForNetworkIdle } from './network-idle.js';
+import { decideDialog, dialogLogEntry } from './dialog.js';
+import { isChallengePage } from './challenge.js';
 import { readable as extractReadable } from './readable.js';
 import { assertNavigable, assertUploadAllowed } from './url-guard.js';
 import { join as pathJoin } from 'node:path';
@@ -351,29 +354,11 @@ export async function connect(opts = {}) {
   let onDialogHandler = null;
   function setupDialogHandler(session) {
     session.on('Page.javascriptDialogOpening', async (params) => {
-      dialogLog.push({
-        type: params.type,
-        message: params.message,
-        timestamp: new Date().toISOString(),
-      });
-      let accept = params.type !== 'beforeunload';
-      let promptText = params.defaultPrompt || '';
-      if (onDialogHandler) {
-        try {
-          const decision = await onDialogHandler({
-            type: params.type,
-            message: params.message,
-            defaultPrompt: params.defaultPrompt || '',
-          });
-          if (decision && typeof decision === 'object') {
-            if (typeof decision.accept === 'boolean') accept = decision.accept;
-            if (typeof decision.promptText === 'string') promptText = decision.promptText;
-          }
-        } catch {
-          // Handler threw — fall back to defaults so the page doesn't hang
-          // waiting for a never-arriving handleJavaScriptDialog reply.
-        }
-      }
+      dialogLog.push(dialogLogEntry(params.type, params.message));
+      const { accept, promptText } = await decideDialog(
+        { type: params.type, message: params.message, defaultPrompt: params.defaultPrompt },
+        onDialogHandler,
+      );
       await session.send('Page.handleJavaScriptDialog', { accept, promptText });
     });
   }
@@ -747,45 +732,89 @@ async function suppressPermissions(cdp) {
  * ref model, and AX-tree source all differ (see firefox-page.js). close() is
  * wrapped to also reap the Firefox process + temp profile.
  *
- * Chromium-only options NOT applied on this path: `blockAds`/`blockUrls` and
- * `hybrid` mode. `saveState`, `waitForNavigation`, and download/dialog capture
- * are CDP-only too (the page object stubs them — see firefox-page.js).
- * `waitForNetworkIdle` and daemon console/network capture DO apply as of Phase
- * 2 (over BiDi `network.*` and `log.entryAdded` events). `consent`
- * (auto-dismiss) and
- * stealth patches DO apply here as of v0.16.0 (stealth headless-only, via BiDi
- * preload script — see stealth-firefox.js / consent-firefox.js), alongside the
- * navigation guard
- * (`allowLocalUrls`/`blockPrivateNetwork`), `uploadDir` sandbox, `incognito`,
- * `proxy`, `viewport`, and `pruneMode`.
- * @param {object} opts - connect() options ({ mode, proxy, binary, viewport, pruneMode, urlGuard, uploadDir, incognito })
+ * As of Phase 4, the Firefox path reaches practical parity with the CDP path:
+ * `hybrid` mode (relaunch headed on a bot-challenge page), `saveState`
+ * (`storage.getCookies` + localStorage), `waitForNavigation`
+ * (`browsingContext.load`), and download capture (`page.downloads` via
+ * `browsingContext.downloadWillBegin`/`downloadEnd`) all work here now.
+ * `blockAds`/`blockUrls` + JS dialog handling arrived in Phase 3; console/
+ * network capture + `waitForNetworkIdle` in Phase 2; stealth + consent in
+ * v0.16.0. Still Firefox-limited: `reload({ignoreCache})` (upstream BiDi gap).
+ * The navigation guard (`allowLocalUrls`/`blockPrivateNetwork`), `uploadDir`
+ * sandbox, `incognito`, `proxy`, `viewport`, and `pruneMode` all apply.
+ * @param {object} opts - connect() options ({ mode, proxy, binary, viewport, pruneMode, urlGuard, uploadDir, incognito, downloadPath, blockAds, blockUrls })
  * @returns {Promise<object>} Firefox page object
  */
 async function connectFirefox(opts) {
-  const browser = await launchFirefox({
-    headed: opts.mode === 'headed',
-    proxy: opts.proxy,
-    binary: opts.binary,
-    viewport: opts.viewport,
-  });
-  const bidi = await createBiDi(browser.wsUrl);
-  // Stealth patches (headless only, mirroring the CDP path's `mode !== 'headed'`
-  // gate). Registered before the first navigation via script.addPreloadScript.
-  // Firefox needs a much smaller script than Chromium — see stealth-firefox.js.
-  if (opts.mode !== 'headed') {
-    await applyFirefoxStealth(bidi);
+  const hybrid = opts.mode === 'hybrid';
+  const blockOpts = {
+    blockAds: opts.blockAds !== undefined ? opts.blockAds : true,
+    blockUrls: opts.blockUrls,
+  };
+
+  // Downloads land in a throwaway dir (parity with CDP's setDownloadBehavior).
+  // A caller-supplied opts.downloadPath is honored and left alone; otherwise we
+  // own + reap a temp dir on close.
+  let ownedDownloadDir = null;
+  let downloadDir = opts.downloadPath || null;
+  if (!downloadDir) {
+    const { mkdtempSync } = await import('node:fs');
+    const { tmpdir } = await import('node:os');
+    ownedDownloadDir = mkdtempSync(pathJoin(tmpdir(), 'barebrowse-ff-dl-'));
+    downloadDir = ownedDownloadDir;
+  }
+
+  // Launch Firefox, open a BiDi session, and apply stealth (headless-only,
+  // mirroring the CDP `mode !== 'headed'` gate) + ad/tracker blocking. Shared
+  // by the initial launch and the hybrid headed relaunch so both are wired
+  // identically. Blocking defaults on — Firefox is always a throwaway profile,
+  // never attach mode — and must be live before the first navigation.
+  async function launchAndSetup(headed) {
+    const browser = await launchFirefox({
+      headed, proxy: opts.proxy, binary: opts.binary, viewport: opts.viewport, downloadDir,
+    });
+    const bidi = await createBiDi(browser.wsUrl);
+    if (!headed) await applyFirefoxStealth(bidi);
+    await applyFirefoxBlocklist(bidi, blockOpts);
+    const { contexts } = await bidi.send('browsingContext.getTree', {});
+    return { browser, bidi, topContext: contexts[0].context };
   }
+
+  let { browser, bidi } = await launchAndSetup(opts.mode === 'headed');
+
+  // Hybrid relaunch: launch a headed Firefox FIRST (so a failure leaves the
+  // current session intact), then tear down the old headless one and hand the
+  // fresh bidi/topContext back to the page, which rebinds to it.
+  async function relaunchHeaded() {
+    const next = await launchAndSetup(true);
+    const old = browser;
+    browser = next.browser;
+    try { bidi.close(); } catch {}
+    try { await cleanupFirefox(old); } catch {}
+    bidi = next.bidi;
+    return { bidi: next.bidi, topContext: next.topContext };
+  }
+
   const page = await createFirefoxPage(bidi, {
     pruneMode: opts.pruneMode,
     urlGuard: { allowLocalUrls: opts.allowLocalUrls, blockPrivateNetwork: opts.blockPrivateNetwork },
     uploadDir: opts.uploadDir || null,
     incognito: !!opts.incognito,
     consent: opts.consent,
+    hybrid,
+    headed: opts.mode === 'headed',
+    relaunchHeaded: hybrid ? relaunchHeaded : null,
   });
   const closePage = page.close.bind(page);
   page.close = async () => {
     await closePage();
-    await cleanupFirefox(browser);
+    await cleanupFirefox(browser); // `browser` tracks the relaunched one if hybrid fired
+    if (ownedDownloadDir) {
+      try {
+        const { rmSync } = await import('node:fs');
+        rmSync(ownedDownloadDir, { recursive: true, force: true });
+      } catch { /* best-effort reap */ }
+    }
   };
   return page;
 }
@@ -911,10 +940,7 @@ let blocklistWarned = false;
  * API surface.
  */
 export async function applyBlocklist(session, pageOpts) {
-  if (pageOpts.blockAds === false && !pageOpts.blockUrls) return;
-  const patterns = pageOpts.blockAds === false
-    ? (pageOpts.blockUrls || [])
-    : [...DEFAULT_BLOCKLIST, ...(pageOpts.blockUrls || [])];
+  const patterns = resolveBlocklistPatterns(pageOpts);
   if (!patterns.length) return;
   try {
     await session.send('Network.setBlockedURLs', { urls: patterns });
@@ -1096,66 +1122,8 @@ function extractProps(props) {
   return result;
 }
 
-/**
- * Detect if a page is a bot-challenge page (Cloudflare, hCaptcha, etc.).
- *
- * Pre-H9 this was over-aggressive: `nodeCount < 50` alone fired on any
- * legitimate small page (404s, simple landings, error pages), and generic
- * phrases like "access denied" / "unknown error" / "permission denied"
- * triggered on real HTTP 4xx/5xx pages, kicking hybrid mode into a costly
- * headed fallback for nothing.
- *
- * H9 split: STRONG_PHRASES are essentially-unambiguous challenge UI and
- * fire regardless of page size; WEAK_PHRASES only fire when the page is
- * ALSO tiny (so a legitimate-looking error page with "access denied" in
- * its body doesn't trip the fallback).
- *
- * @param {object} tree - Nested ARIA tree (from buildTree)
- * @param {number} [nodeCount] - Raw CDP node count (from Accessibility.getFullAXTree)
- */
-export function isChallengePage(tree, nodeCount) {
-  if (!tree) return true; // truly empty AX tree — something went wrong fetching the page
-
-  const text = flattenTreeText(tree);
-  const lower = text.toLowerCase();
-
-  // Strong phrases — distinctive enough to identify the challenge product
-  // by name. Fire on their own regardless of node count.
-  const STRONG_PHRASES = [
-    'just a moment',                            // Cloudflare interstitial
-    'checking if the site connection is secure', // Cloudflare
-    'checking your browser',                     // Various JS challenges
-    'verify you are human',                      // hCaptcha / reCAPTCHA
-    'prove your humanity',
-    'attention required',                        // Cloudflare block page
-    'enable javascript and cookies to continue', // Cloudflare
-    'please complete the security check',        // Cloudflare/Akamai
-  ];
-  if (STRONG_PHRASES.some((p) => lower.includes(p))) return true;
-
-  // Weak phrases — show up on real challenge pages but ALSO on legitimate
-  // small error pages. Only count when the page is itself tiny (low node
-  // count or near-empty text), which is the corroborating signal that
-  // separates a real error UI from a challenge skeleton.
-  const WEAK_PHRASES = [
-    'please wait',
-    'request blocked',
-    'access denied',
-    'permission denied',
-    'unknown error',
-    'file a ticket',
-  ];
-  const tinyPage = (nodeCount !== undefined && nodeCount < 30) || text.trim().length < 50;
-  if (tinyPage && WEAK_PHRASES.some((p) => lower.includes(p))) return true;
-
-  return false;
-}
-
-function flattenTreeText(node) {
-  if (!node) return '';
-  let text = node.name || '';
-  for (const child of node.children || []) {
-    text += ' ' + flattenTreeText(child);
-  }
-  return text;
-}
+// isChallengePage (the hybrid-fallback gate) now lives in challenge.js so both
+// the CDP path here and the BiDi path (firefox-page.js) share it without a
+// circular import. Re-exported (from the local import above) so existing
+// importers of `src/index.js` and the public API keep working unchanged.
+export { isChallengePage };

package/types/blocklist-firefox.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Install ad/tracker blocking on a BiDi session. Idempotent per session is the
+ * caller's concern; call once at connect time before the first navigation.
+ *
+ * @param {object} bidi - BiDi client (send, subscribe, on).
+ * @param {object} pageOpts
+ * @param {boolean} [pageOpts.blockAds] - false disables the default list.
+ * @param {string[]} [pageOpts.blockUrls] - extra CDP-format globs; extend the
+ *   default unless blockAds is false, in which case they're the whole list.
+ * @returns {Promise<void>}
+ */
+export function applyFirefoxBlocklist(bidi: object, pageOpts?: {
+    blockAds?: boolean | undefined;
+    blockUrls?: string[] | undefined;
+}): Promise<void>;

package/types/blocklist.d.ts

@@ -1,3 +1,37 @@
+/**
+ * Resolve the effective blocklist from a page's blockAds/blockUrls options.
+ * Single-sourced across engines (CDP applyBlocklist + BiDi applyFirefoxBlocklist)
+ * so the merge/extend rule can't drift between them:
+ *   - blockAds !== false → DEFAULT_BLOCKLIST plus any blockUrls (extend);
+ *   - blockAds === false → only blockUrls (the default list is dropped);
+ *   - neither → empty (blocking disabled).
+ *
+ * @param {object} [pageOpts]
+ * @param {boolean} [pageOpts.blockAds] - false drops the default list.
+ * @param {string[]} [pageOpts.blockUrls] - extra CDP-format globs.
+ * @returns {string[]} the patterns to block (possibly empty).
+ */
+export function resolveBlocklistPatterns(pageOpts?: {
+    blockAds?: boolean | undefined;
+    blockUrls?: string[] | undefined;
+}): string[];
+/**
+ * Compile CDP-format glob patterns into a single URL-matching predicate.
+ *
+ * CDP blocks natively via Network.setBlockedURLs, which does the glob matching
+ * browser-side. WebDriver BiDi has no glob-capable equivalent — network.
+ * addIntercept's urlPatterns reject '*' outright ("forbidden character *") and
+ * can't express subdomain wildcards like *.doubleclick.net. So the Firefox
+ * path intercepts *all* requests and matches each URL here, in-process, against
+ * the same patterns — keeping the blocklist single-sourced across engines.
+ *
+ * Matches CDP's glob semantics: '*' = any run of characters, '?' = exactly
+ * one character, whole-URL (anchored) match; every other character is literal.
+ *
+ * @param {string[]} patterns - CDP-format globs (e.g. DEFAULT_BLOCKLIST).
+ * @returns {(url: string) => boolean} true when `url` matches any pattern.
+ */
+export function makeBlockMatcher(patterns: string[]): (url: string) => boolean;
 /**
  * blocklist.js — Ad/tracker URL patterns for CDP Network.setBlockedURLs.
  *

package/types/challenge.d.ts

@@ -0,0 +1,25 @@
+/**
+ * challenge.js — Bot-challenge / interstitial detection for the hybrid fallback.
+ *
+ * Extracted from index.js so both engines can share it without a circular
+ * import (index.js drives CDP; firefox-page.js drives BiDi, and both need to
+ * decide "is this a Cloudflare/hCaptcha wall we should retry headed?"). Pure —
+ * operates on the nested ARIA tree that buildTree() / ariaTree() produce, which
+ * is identical in shape across engines.
+ */
+/**
+ * Heuristic: does this ARIA tree look like a bot-challenge / block interstitial
+ * (Cloudflare "Just a moment", hCaptcha, Akamai) rather than real content?
+ *
+ * H9 split: STRONG_PHRASES are essentially-unambiguous challenge UI and fire
+ * regardless of page size; WEAK_PHRASES only fire when the page is ALSO tiny
+ * (so a legitimate-looking error page with "access denied" in its body doesn't
+ * trip the fallback).
+ *
+ * @param {object} tree - Nested ARIA tree (from buildTree / ariaTree)
+ * @param {number} [nodeCount] - Node count (CDP: getFullAXTree; BiDi: tree walk)
+ * @returns {boolean}
+ */
+export function isChallengePage(tree: object, nodeCount?: number): boolean;
+/** Count every node in a nested ARIA tree (shared node-count for the tinyPage test). */
+export function countNodes(node: any): number;