barebrowse 0.18.0 → 0.19.1

package/CHANGELOG.md

@@ -1,5 +1,63 @@
 # Changelog
 
+## [0.19.1] - 2026-07-11
+
+### Changed
+
+- **MCP: Firefox sessions now default to `hybrid`** (was `headless`), matching the
+  Chromium default — Phase 4 gave Firefox the same headless→headed challenge
+  fallback, so there's no reason to hold it back. A failed headed relaunch (no
+  display) falls back to the headless result. Override with `BAREBROWSE_MODE`;
+  the Chromium path now honors `BAREBROWSE_MODE` too (was hardcoded `hybrid`).
+
+### Docs
+
+- **README** refocused on primitives and value — Firefox stated as a capability
+  set rather than a version-by-version log; stale counts/versions and a redundant
+  section removed.
+- **Single PRD** — the Firefox parity plan is merged into `docs/01-product/prd.md`
+  as a "Firefox Parity" section (capability matrix + goal/non-goals + forward
+  plan); the standalone `firefox-parity-plan.md` is removed.
+- Fixed stale "hybrid is chromium-only" strings in the CLI help and MCP comments.
+
+## [0.19.0] - 2026-07-11
+
+### Added
+
+- **Firefox/BiDi resilience + remaining methods (parity plan Phase 4).** The
+  Firefox engine reaches practical parity with the Chromium/CDP engine — four
+  CDP-only surfaces now work the same over WebDriver BiDi:
+  - **Hybrid mode** (`mode: 'hybrid'`). On a bot-challenge page (Cloudflare "Just
+    a moment", hCaptcha, etc.) the Firefox engine now relaunches **headed** and
+    retries, exactly like the CDP path — a real display often clears an
+    interstitial headless can't. The relaunch tears down the headless
+    Firefox+BiDi and hands a fresh connection back to the page, which rebinds to
+    it; a failed relaunch (no display) keeps the headless result. Cookies
+    injected before the challenge are **re-injected into the fresh headed
+    profile** so the retry stays authenticated. The challenge heuristic
+    (`isChallengePage`) is now shared by both engines (`challenge.js`).
+  - **`page.saveState(file)`** — persists cookies (`storage.getCookies`) +
+    localStorage (`script.evaluate`) to a `0600` JSON file, flattened to the
+    same shape the CDP path writes (was a throwing stub).
+  - **`page.waitForNavigation()`** — resolves on the next top-context
+    `browsingContext.load` event, with an SPA settle fallback (was a stub).
+  - **`page.downloads`** — real download tracking via
+    `browsingContext.downloadWillBegin`/`downloadEnd`. Downloads land in a
+    throwaway dir (Firefox `browser.download.*` prefs, parity with CDP's
+    `setDownloadBehavior`) and each record carries `{url, suggestedFilename,
+    savedPath, state}` with BiDi's `complete` normalized to CDP's `completed`
+    (was always empty).
+
+  BiDi mechanics were POC-measured against real Firefox before wiring (cookie/
+  localStorage shapes on real vs opaque origins; the `load` event sequence; that
+  Firefox emits `downloadWillBegin`/`downloadEnd` and honors the download-dir
+  prefs). The shared JS-dialog decision core was also extracted to `dialog.js`
+  (both engines — Phase-3 review finding #5). Guarded by
+  `test/unit/firefox-hybrid.test.js` (5, fake-BiDi orchestration) and Firefox
+  integration tests (saveState, waitForNavigation ×2, downloads).
+  Still Firefox-limited: `reload({ignoreCache})` (upstream BiDi gap, no local
+  fix).
+
 ## [0.18.0] - 2026-07-11
 
 ### Added

package/README.md

@@ -96,15 +96,15 @@ Or manually add to your config (`claude_desktop_config.json`, `.cursor/mcp.json`
 }
 ```
 
-19 tools: `browse`, `goto`, `snapshot`, `readable`, `click`, `type`, `press`, `scroll`, `hover`, `select`, `back`, `forward`, `reload`, `drag`, `upload`, `pdf`, `screenshot`, `wait_for`, `tabs`. Plus `assess` (privacy scan) if [wearehere](https://github.com/hamr0/wearehere) is installed. Plus opt-in `eval` (`BAREBROWSE_MCP_EVAL=1`) — runs JS in the authenticated session, off by default because it can read cookies/localStorage. Session runs in hybrid mode with automatic cookie injection. Per-tool timeouts (goto/reload/wait_for 60s, back/forward 30s, interactive ops 15s, pdf/screenshot/upload 45s) with auto-retry on transient failures (idempotent only — mutating tools fail loudly to avoid double-submits).
+MCP tools: `browse`, `goto`, `snapshot`, `readable`, `click`, `type`, `press`, `scroll`, `hover`, `select`, `back`, `forward`, `reload`, `drag`, `upload`, `pdf`, `screenshot`, `wait_for`, `tabs`. Plus `assess` (privacy scan) if [wearehere](https://github.com/hamr0/wearehere) is installed. Plus opt-in `eval` (`BAREBROWSE_MCP_EVAL=1`) — runs JS in the authenticated session, off by default because it can read cookies/localStorage. Session runs in hybrid mode with automatic cookie injection. Per-tool timeouts (goto/reload/wait_for 60s, back/forward 30s, interactive ops 15s, pdf/screenshot/upload 45s) with auto-retry on transient failures (idempotent only — mutating tools fail loudly to avoid double-submits).
 
-`browse` and `snapshot` accept `pruneMode: 'act'|'read'` (v0.9.1). `act` (default) keeps interactive elements — best for clicking/filling. `read` keeps paragraphs, headings, and long text — best for articles, docs, and content extraction. If act-mode collapses a content-heavy page near-totally, the snapshot includes a `hint: …` line suggesting `pruneMode='read'` so the agent doesn't bail to a separate HTTP fetch.
+`browse` and `snapshot` accept `pruneMode: 'act'|'read'`. `act` (default) keeps interactive elements — best for clicking/filling. `read` keeps paragraphs, headings, and long text — best for articles, docs, and content extraction. If act-mode collapses a content-heavy page near-totally, the snapshot includes a `hint: …` line suggesting `pruneMode='read'` so the agent doesn't bail to a separate HTTP fetch.
 
 Troubleshooting MCP setup: `npx barebrowse doctor` scans every known config location and flags scope conflicts. `npx barebrowse install --force` overwrites an existing entry pointing at a different endpoint.
 
 ### 3. Library -- for agentic automation
 
-Import barebrowse in your agent code. One-shot reads, interactive sessions, full observe-think-act loops. Works with any LLM orchestration library. Ships with a ready-made adapter for [bareagent](https://www.npmjs.com/package/bare-agent) (18 tools, auto-snapshot after every action).
+Import barebrowse in your agent code. One-shot reads, interactive sessions, full observe-think-act loops. Works with any LLM orchestration library. Ships with a ready-made adapter for [bareagent](https://www.npmjs.com/package/bare-agent) (auto-snapshot after every action).
 
 For code examples, API reference, and wiring instructions, see **[barebrowse.context.md](barebrowse.context.md)** -- the full integration guide.
 
@@ -112,10 +112,12 @@ For code examples, API reference, and wiring instructions, see **[barebrowse.con
 
 | Mode | What happens | Best for |
 |------|-------------|----------|
-| **Headless** (default) | Launches a fresh Chromium, no UI | Fast automation, scraping, reading pages |
-| **Headed** | Auto-launches a visible Chromium window | Bot-detected sites, visual debugging, CAPTCHAs |
+| **Headless** (default) | Launches a fresh browser, no UI | Fast automation, scraping, reading pages |
+| **Headed** | Auto-launches a visible browser window | Bot-detected sites, visual debugging, CAPTCHAs |
 | **Hybrid** | Tries headless first, auto-launches headed if blocked | General-purpose agent browsing |
 
+All three work on both engines (Chromium/CDP and Firefox/BiDi).
+
 ### Attach to your already-running browser
 
 Start Chromium yourself with a debug port, then drive your real logged-in session:
@@ -135,23 +137,22 @@ await page.close(); // closes only the tab barebrowse opened — your browser ke
 ### Firefox (WebDriver BiDi)
 
 CDP is deprecated in Firefox, so barebrowse drives it over the W3C WebDriver
-BiDi protocol instead — a second transport over the same `ws` dependency, no
-extra download. Same `page.*` API (the ARIA snapshot is reconstructed in-page
-since BiDi has no `getFullAXTree`):
+BiDi protocol — a second transport over the same `ws` dependency, no extra
+download. Same `page.*` API (the ARIA snapshot is reconstructed in-page since
+BiDi has no `getFullAXTree`):
 
 ```js
-const page = await connect({ engine: 'firefox' }); // headless by default
+const page = await connect({ engine: 'firefox' });
 ```
 
-From the CLI: `barebrowse open <url> --engine firefox`. From MCP: set
-`BAREBROWSE_ENGINE=firefox`. Firefox cookies (plaintext) reuse into the same
-engine. Consent auto-dismiss and headless stealth (v0.16.0), the daemon's
-console/network capture and `waitForNetworkIdle` (v0.17.0), and ad/tracker
-blocking plus JS dialog handling (`dialogLog`/`onDialog`, v0.18.0) all work on
-Firefox too. Chromium (CDP) remains the default; only `hybrid` mode is still
-Chromium-only.
+CLI: `barebrowse open <url> --engine firefox`. MCP: `BAREBROWSE_ENGINE=firefox`.
+Firefox cookies (plaintext) reuse into the same engine.
 
-No clone profile, no fresh cookies — the agent sees what you see.
+Firefox is at practical parity with Chromium: stealth, consent auto-dismiss,
+ad/tracker blocking, JS dialogs, console/network capture, hybrid fallback,
+`saveState`, `waitForNavigation`, and download tracking all work the same way.
+Chromium (CDP) stays the default; the only remaining gap is
+`reload({ignoreCache})` (upstream BiDi limitation).
 
 ### Incognito (clean session)
 
@@ -170,9 +171,9 @@ From the CLI: `barebrowse open <url> --incognito`. From MCP: set
 
 ## What it handles automatically
 
-Cookie consent walls (29 languages, with real mouse click fallback for stubborn CMPs), login walls (cookie extraction from your browsers), bot detection (ARIA node count heuristic + stealth patches + automatic headed fallback — snapshot shows `[BOT CHALLENGE DETECTED]` warning when blocked), permission prompts, SPA navigation, JS dialogs, off-screen elements, pre-filled inputs, ARIA noise, and profile locking. The agent doesn't think about any of it.
+Cookie consent walls (29 languages, with real mouse click fallback for stubborn CMPs), login walls (cookie extraction from your browsers), bot detection (challenge-phrase + node-count heuristic + stealth patches + automatic headed fallback — snapshot shows `[BOT CHALLENGE DETECTED]` warning when blocked), permission prompts, SPA navigation, JS dialogs, off-screen elements, pre-filled inputs, ARIA noise, and profile locking. The agent doesn't think about any of it.
 
-## Safe by default (v0.11.0)
+## Safe by default
 
 barebrowse hands an autonomous — and therefore prompt-injectable — agent an *authenticated* browser, so the defaults are calibrated for that threat:
 
@@ -223,8 +224,8 @@ Everything the agent can do through barebrowse:
 | **Wait for network idle** | Resolve when no pending requests for 500ms |
 | **Dialog handling** | Auto-dismiss JS alert/confirm/prompt dialogs |
 | **Save state** | Export cookies + localStorage to JSON |
-| **Inject cookies** | Extract from Firefox/Chromium and inject via CDP |
-| **Raw CDP** | Escape hatch for any Chrome DevTools Protocol command |
+| **Inject cookies** | Extract from Firefox/Chromium and inject into the session (CDP or BiDi) |
+| **Raw CDP / BiDi** | Escape hatch: `page.cdp` (Chromium) or `page.bidi` (Firefox) for any low-level command |
 
 ## Tested against
 
@@ -232,10 +233,6 @@ Everything the agent can do through barebrowse:
 
 Google, YouTube, BBC, Wikipedia, GitHub, DuckDuckGo, Hacker News, Amazon DE, The Guardian, Spiegel, Le Monde, El Pais, Corriere, NOS, Bild, Nu.nl, Booking, NYT, Stack Overflow, CNN, Reddit
 
-## Context file
-
-**[barebrowse.context.md](barebrowse.context.md)** is the full integration guide. Feed it to an AI assistant or read it yourself -- it covers the complete API, snapshot format, interaction loop, auth options, bareagent wiring, MCP setup, and gotchas. Everything you need to wire barebrowse into a project.
-
 ## How it works
 
 ```
@@ -247,12 +244,15 @@ URL -> find/launch browser (chromium.js)
     -> navigate to URL, wait for load
     -> detect + dismiss cookie consent dialogs (consent.js)
     -> get full ARIA accessibility tree (aria.js)
-    -> 9-step pruning pipeline from mcprune (prune.js)
+    -> pruning pipeline from mcprune (prune.js)
     -> dispatch real input events: click/type/scroll (interact.js)
     -> agent-ready snapshot with [ref=N] markers
 ```
 
-14 modules, ~3,000 lines, two small dependencies (`ws`, `@mozilla/readability`).
+Firefox follows the same flow over WebDriver BiDi (`bidi.js`), with the AX tree
+reconstructed in-page (`ax-snapshot.js`) and pruning/formatting shared verbatim.
+
+A small set of focused modules, two small dependencies (`ws`, `@mozilla/readability`).
 
 ## Requirements
 

package/barebrowse.context.md

@@ -95,7 +95,7 @@ const snapshot = await browse('https://example.com', {
 | `close()` | -- | void | Close page, disconnect CDP, kill browser (if headless) |
 
 **connect() options** (in addition to mode/port/consent):
-- `engine: 'chromium'|'firefox'` — Browser engine. Default `chromium` (CDP). `firefox` drives Firefox over WebDriver BiDi (CDP is deprecated there) — a separate transport with the same `page.*` API; the ARIA snapshot is reconstructed in-page since BiDi has no `getFullAXTree`. Consent auto-dismiss and stealth (headless anti-detection) work on Firefox as of v0.16.0; the CLI daemon's console/network capture and `waitForNetworkIdle` work as of v0.17.0; ad/tracker blocking (`blockAds`/`blockUrls`) and JS dialog handling (`dialogLog`/`onDialog`) work as of Phase 3. Still Chromium-only: `hybrid` mode. `reload()` ignores `ignoreCache` on Firefox (BiDi limitation).
+- `engine: 'chromium'|'firefox'` — Browser engine. Default `chromium` (CDP). `firefox` drives Firefox over WebDriver BiDi (CDP is deprecated there) — a separate transport with the same `page.*` API; the ARIA snapshot is reconstructed in-page since BiDi has no `getFullAXTree`. Consent auto-dismiss and stealth (headless anti-detection) work on Firefox as of v0.16.0; the CLI daemon's console/network capture and `waitForNetworkIdle` work as of v0.17.0; ad/tracker blocking (`blockAds`/`blockUrls`) and JS dialog handling (`dialogLog`/`onDialog`) work as of Phase 3; `hybrid` mode, `saveState`, `waitForNavigation`, and download tracking (`page.downloads`) work as of Phase 4. The only remaining Firefox gap is `reload()` ignoring `ignoreCache` (upstream BiDi limitation).
 - `port: 9222` — Attach to a Chromium already running with `--remote-debugging-port=N` instead of spawning one. The browser keeps running on `close()`. Stealth + permission denial + download capture are skipped to avoid mutating the user's running browser.
 - `proxy: 'http://...'` — HTTP/SOCKS proxy for browser
 - `viewport: '1280x720'` — Set viewport dimensions

package/cli.js

@@ -487,7 +487,7 @@ Session:
     --engine=chromium|firefox       Browser engine (default: chromium/CDP;
                                     firefox drives over WebDriver BiDi)
     --mode=headless|headed|hybrid   Browser mode (default: headless;
-                                    hybrid is chromium-only)
+                                    hybrid works on both engines)
     --port=N                        CDP port for headed mode
     --no-cookies                    Skip cookie injection
     --incognito                     Clean, unauthenticated session (skip all auth injection)

package/mcp-server.js

@@ -123,15 +123,17 @@ async function getPage() {
   if (_pageConnecting) return _pageConnecting;
   // Engine selection is a launch-time setting (the browser persists across
   // tool calls), so it's an env var, not a per-request flag. Firefox is driven
-  // over WebDriver BiDi and has no hybrid fallback — default it to headless
-  // (override with BAREBROWSE_MODE=headed).
+  // over WebDriver BiDi and, as of parity Phase 4, has the same hybrid fallback
+  // as Chromium (relaunch headed on a bot-challenge page) — so it defaults to
+  // hybrid too, matching the Chromium default (override with BAREBROWSE_MODE).
+  // A failed headed relaunch (no display) falls back to the headless result.
   // Incognito is a launch-time setting like engine/mode: the session persists
   // across tool calls, so it's an env var (BAREBROWSE_INCOGNITO=1), not a
   // per-request flag. Skips all auth injection for a clean, logged-out session.
   const incognito = process.env.BAREBROWSE_INCOGNITO === '1';
   const connectOpts = process.env.BAREBROWSE_ENGINE === 'firefox'
-    ? { engine: 'firefox', mode: process.env.BAREBROWSE_MODE || 'headless', incognito }
-    : { mode: 'hybrid', incognito };
+    ? { engine: 'firefox', mode: process.env.BAREBROWSE_MODE || 'hybrid', incognito }
+    : { mode: process.env.BAREBROWSE_MODE || 'hybrid', incognito };
   _pageConnecting = connect(connectOpts);
   try {
     _page = await _pageConnecting;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "barebrowse",
-  "version": "0.18.0",
+  "version": "0.19.1",
   "description": "Authenticated web browsing for autonomous agents via CDP. URL in, pruned ARIA snapshot out.",
   "repository": {
     "type": "git",

package/src/challenge.js

@@ -0,0 +1,77 @@
+/**
+ * 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, 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;
+}
+
+/** Count every node in a nested ARIA tree (shared node-count for the tinyPage test). */
+export function countNodes(node) {
+  if (!node) return 0;
+  let n = 1;
+  for (const c of node.children || []) n += countNodes(c);
+  return n;
+}
+
+function flattenTreeText(node) {
+  if (!node) return '';
+  let text = node.name || '';
+  for (const child of node.children || []) {
+    text += ' ' + flattenTreeText(child);
+  }
+  return text;
+}

package/src/dialog.js

@@ -0,0 +1,52 @@
+/**
+ * dialog.js — Shared JS-dialog decision core for both engines.
+ *
+ * A JS dialog (alert/confirm/prompt/beforeunload) surfaces differently per
+ * protocol — CDP's `Page.javascriptDialogOpening` vs BiDi's
+ * `browsingContext.userPromptOpened` — but the *decision* (accept? what prompt
+ * text?) and the log entry are identical. This module single-sources both so
+ * the CDP path (index.js) and the BiDi path (firefox-page.js) can't drift
+ * (code-review Phase-3 finding #5).
+ */
+
+/**
+ * Build a dialogLog entry from a normalized dialog descriptor.
+ * @param {string} type - 'alert' | 'confirm' | 'prompt' | 'beforeunload'
+ * @param {string} [message]
+ * @returns {{type: string, message: string, timestamp: string}}
+ */
+export function dialogLogEntry(type, message) {
+  return { type, message: message || '', timestamp: new Date().toISOString() };
+}
+
+/**
+ * Decide how to answer a JS dialog. Default policy (both engines): accept
+ * everything except `beforeunload` (dismiss = stay on page); a `prompt`
+ * returns its default text. A caller-installed handler may override via
+ * `{ accept, promptText }`; if the handler throws we keep the defaults so the
+ * page never hangs waiting for a reply that never arrives.
+ *
+ * @param {{type: string, message?: string, defaultPrompt?: string}} dialog
+ * @param {?(function({type,message,defaultPrompt}): (object|Promise<object>))} handler
+ * @returns {Promise<{accept: boolean, promptText: string}>}
+ */
+export async function decideDialog({ type, message, defaultPrompt }, handler) {
+  let accept = type !== 'beforeunload';
+  let promptText = defaultPrompt || '';
+  if (handler) {
+    try {
+      const decision = await handler({
+        type,
+        message: message || '',
+        defaultPrompt: 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 — keep defaults so the page doesn't hang.
+    }
+  }
+  return { accept, promptText };
+}

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,6 +186,37 @@ 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
@@ -182,32 +229,16 @@ export async function createFirefoxPage(bidi, opts = {}) {
   async function setupDialogs() {
     await bidi.subscribe(['browsingContext.userPromptOpened']);
     bidi.on('browsingContext.userPromptOpened', async (e) => {
-      dialogLog.push({
-        type: e.type,
-        message: e.message || '',
-        timestamp: new Date().toISOString(),
-      });
-      let accept = e.type !== 'beforeunload';
-      let userText = e.defaultValue || '';
-      if (onDialogHandler) {
-        try {
-          const decision = await onDialogHandler({
-            type: e.type,
-            message: e.message || '',
-            defaultPrompt: e.defaultValue || '',
-          });
-          if (decision && typeof decision === 'object') {
-            if (typeof decision.accept === 'boolean') accept = decision.accept;
-            if (typeof decision.promptText === 'string') userText = decision.promptText;
-          }
-        } catch {
-          // Handler threw — fall back to defaults so the prompt is still
-          // answered and the page doesn't hang on an 'ignore' dialog.
-        }
-      }
+      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,
+          context: e.context, accept, userText: promptText,
         });
       } catch {
         // Prompt already gone (closed by page JS / navigation). Nothing to do.
@@ -215,29 +246,83 @@ export async function createFirefoxPage(bidi, opts = {}) {
     });
   }
 
+  /**
+   * 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.
+        }
       }
     },
 
@@ -308,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) {
@@ -456,14 +542,8 @@ 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 isn't wired (Phase 4), so downloads
-    // is genuinely empty; saveState/waitForNavigation are CDP-only and fail with
-    // a clear, intentional message instead of an incidental TypeError.
-    // (dialogLog + onDialog ARE wired — Phase 3, see setupDialogs above.)
-    // Documented as a known gap in CHANGELOG.
-    get downloads() { return []; },
+    /** Downloads that began in this session (Phase 4 — see setupDownloads). */
+    get downloads() { return downloads; },
 
     dialogLog,
 
@@ -477,11 +557,57 @@ export async function createFirefoxPage(bidi, opts = {}) {
       onDialogHandler = handler;
     },
 
-    async saveState() {
-      throw new Error('saveState() 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 */ }
     },
-    async waitForNavigation() {
-      throw new Error('waitForNavigation() is not supported on the Firefox/BiDi engine (CDP-only)');
+
+    /**
+     * 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() {
@@ -499,9 +625,9 @@ export async function createFirefoxPage(bidi, opts = {}) {
     await new Promise((r) => setTimeout(r, 500));
   }
 
-  // Wire the dialog handler before returning — must precede any navigation so
-  // an 'ignore' prompt (see bidi.js capability) is never left hanging.
-  await setupDialogs();
+  // 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

@@ -23,6 +23,8 @@ import { applyFirefoxStealth } from './stealth-firefox.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';
@@ -352,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 });
     });
   }
@@ -748,56 +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: `hybrid` mode. `saveState`,
- * `waitForNavigation`, and download capture are CDP-only too (the page object
- * stubs them — see firefox-page.js). `blockAds`/`blockUrls` and JS dialog
- * handling (`dialogLog`/`onDialog`) DO apply as of Phase 3 (ad-block via a
- * catch-all `network.addIntercept` + in-process glob match; dialogs via
- * `browsingContext.userPromptOpened` → `handleUserPrompt`).
- * `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);
-  }
-  // Ad/tracker blocking (parity with the CDP applyBlocklist). Firefox is always
-  // a launched, throwaway profile (never attach mode), so the default is on —
-  // unlike the CDP path, which defaults off in attach mode. Must run before the
-  // first navigation so the catch-all intercept is live when the page loads.
-  await applyFirefoxBlocklist(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;
 }
@@ -1105,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/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;

package/types/dialog.d.ts

@@ -0,0 +1,44 @@
+/**
+ * dialog.js — Shared JS-dialog decision core for both engines.
+ *
+ * A JS dialog (alert/confirm/prompt/beforeunload) surfaces differently per
+ * protocol — CDP's `Page.javascriptDialogOpening` vs BiDi's
+ * `browsingContext.userPromptOpened` — but the *decision* (accept? what prompt
+ * text?) and the log entry are identical. This module single-sources both so
+ * the CDP path (index.js) and the BiDi path (firefox-page.js) can't drift
+ * (code-review Phase-3 finding #5).
+ */
+/**
+ * Build a dialogLog entry from a normalized dialog descriptor.
+ * @param {string} type - 'alert' | 'confirm' | 'prompt' | 'beforeunload'
+ * @param {string} [message]
+ * @returns {{type: string, message: string, timestamp: string}}
+ */
+export function dialogLogEntry(type: string, message?: string): {
+    type: string;
+    message: string;
+    timestamp: string;
+};
+/**
+ * Decide how to answer a JS dialog. Default policy (both engines): accept
+ * everything except `beforeunload` (dismiss = stay on page); a `prompt`
+ * returns its default text. A caller-installed handler may override via
+ * `{ accept, promptText }`; if the handler throws we keep the defaults so the
+ * page never hangs waiting for a reply that never arrives.
+ *
+ * @param {{type: string, message?: string, defaultPrompt?: string}} dialog
+ * @param {?(function({type,message,defaultPrompt}): (object|Promise<object>))} handler
+ * @returns {Promise<{accept: boolean, promptText: string}>}
+ */
+export function decideDialog({ type, message, defaultPrompt }: {
+    type: string;
+    message?: string;
+    defaultPrompt?: string;
+}, handler: ((arg0: {
+    type: any;
+    message: any;
+    defaultPrompt: any;
+}) => (object | Promise<object>)) | null): Promise<{
+    accept: boolean;
+    promptText: string;
+}>;

package/types/firefox-page.d.ts

@@ -7,6 +7,9 @@
  * @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 function createFirefoxPage(bidi: object, opts?: {
@@ -18,4 +21,10 @@ export function createFirefoxPage(bidi: object, opts?: {
     uploadDir?: string | undefined;
     incognito?: boolean | undefined;
     consent?: boolean | undefined;
+    hybrid?: boolean | undefined;
+    headed?: boolean | undefined;
+    relaunchHeaded?: (() => Promise<{
+        bidi: object;
+        topContext: string;
+    }>) | null | undefined;
 }): Promise<object>;

package/types/firefox.d.ts

@@ -14,6 +14,7 @@ export function findFirefox(): string;
  * @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 function launchFirefox(opts?: {
@@ -25,6 +26,7 @@ export function launchFirefox(opts?: {
         width: number;
         height: number;
     } | undefined;
+    downloadDir?: string | undefined;
 }): Promise<{
     wsUrl: string;
     process: import("node:child_process").ChildProcess;

package/types/index.d.ts

@@ -129,21 +129,5 @@ export function connect(opts?: {
 export function applyBlocklist(session: any, pageOpts: any): Promise<void>;
 /** Test-only: reset the warn-once flag. Not part of the public API. */
 export function _resetBlocklistWarning(): void;
-/**
- * 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: object, nodeCount?: number): boolean;
+export { isChallengePage };
+import { isChallengePage } from './challenge.js';