barebrowse 0.14.0 → 0.17.0

package/src/index.js

@@ -9,13 +9,17 @@
  */
 
 import { launch, attach, cleanupBrowser } from './chromium.js';
+import { launchFirefox, cleanupFirefox } from './firefox.js';
 import { createCDP } from './cdp.js';
+import { createBiDi } from './bidi.js';
+import { createFirefoxPage } from './firefox-page.js';
 import { formatTree } from './aria.js';
 import { authenticate } from './auth.js';
 import { prune as pruneTree } from './prune.js';
 import { click as cdpClick, type as cdpType, scroll as cdpScroll, press as cdpPress, hover as cdpHover, select as cdpSelect, drag as cdpDrag, upload as cdpUpload } from './interact.js';
 import { dismissConsent } from './consent.js';
 import { applyStealth } from './stealth.js';
+import { applyFirefoxStealth } from './stealth-firefox.js';
 import { DEFAULT_BLOCKLIST } from './blocklist.js';
 import { waitForNetworkIdle } from './network-idle.js';
 import { readable as extractReadable } from './readable.js';
@@ -31,6 +35,8 @@ import { chmodSync } from 'node:fs';
  * @param {object} [opts]
  * @param {'headless'|'headed'|'hybrid'} [opts.mode='headless'] - Browser mode
  * @param {boolean} [opts.cookies=true] - Inject user's cookies (Phase 2)
+ * @param {boolean} [opts.incognito=false] - Clean, unauthenticated session:
+ *   skip cookie/auth injection entirely (equivalent to cookies:false here).
  * @param {boolean} [opts.prune=true] - Apply ARIA pruning (Phase 2)
  * @param {number} [opts.timeout=30000] - Navigation timeout in ms
  * @param {boolean} [opts.blockAds=true] - Block ~120 common ad/tracker
@@ -54,6 +60,8 @@ import { chmodSync } from 'node:fs';
 export async function browse(url, opts = {}) {
   const mode = opts.mode || 'headless';
   const timeout = opts.timeout || 30000;
+  // Skip all auth injection when incognito (or the legacy cookies:false).
+  const noAuth = !!opts.incognito || opts.cookies === false;
 
   // Reject local-resource schemes (and optionally private hosts) before we
   // spend a browser launch on a URL we won't navigate to.
@@ -84,7 +92,7 @@ export async function browse(url, opts = {}) {
     await suppressPermissions(cdp);
 
     // Step 3: Cookie injection — extract from user's browser, inject via CDP
-    if (opts.cookies !== false) {
+    if (!noAuth) {
       try {
         await authenticate(page.session, url, { browser: opts.browser });
       } catch {
@@ -114,7 +122,7 @@ export async function browse(url, opts = {}) {
         cdp = await createCDP(browser.wsUrl);
         page = await createPage(cdp, false, pageOpts);
         await suppressPermissions(cdp);
-        if (opts.cookies !== false) {
+        if (!noAuth) {
           try { await authenticate(page.session, url, { browser: opts.browser }); } catch {}
         }
         await navigate(page, url, timeout);
@@ -188,12 +196,32 @@ export async function browse(url, opts = {}) {
  * @param {boolean} [opts.consent=true] - Auto-dismiss cookie consent dialogs.
  * @param {string} [opts.storageState] - Path to a storage-state JSON file
  *   (cookies + localStorage) to load before navigation.
+ * @param {boolean} [opts.incognito=false] - Clean, unauthenticated session:
+ *   skip storageState loading and make injectCookies() a no-op, so no auth
+ *   ever enters the session even if a caller injects unconditionally.
  * @param {'act'|'browse'|'navigate'|'full'|'read'} [opts.pruneMode='act'] - Pruning mode.
+ * @param {'chromium'|'firefox'} [opts.engine='chromium'] - Browser engine.
+ *   'firefox' drives over WebDriver BiDi (a separate transport / page object);
+ *   'chromium' (default) uses CDP.
  * @returns {Promise<object>} Page handle with goto, snapshot, close
  */
 export async function connect(opts = {}) {
+  // Firefox is driven over WebDriver BiDi (CDP is deprecated there) — a
+  // separate transport with its own page object. It reuses prune.js/aria.js/
+  // readable.js but none of the CDP page machinery below, so branch early.
+  if (opts.engine === 'firefox') {
+    return connectFirefox(opts);
+  }
+
   const mode = opts.mode || 'headless';
   const attachMode = !!opts.port;
+  // Incognito: run a clean, unauthenticated session. Skips storageState loading
+  // and neuters injectCookies() so no auth ever enters the session — even when
+  // a caller (MCP goto, daemon) calls injectCookies() unconditionally. The
+  // temp profile is already throwaway; this gates the OTHER auth source: the
+  // user's real browser cookies. Not Chrome's --incognito flag (redundant with
+  // the temp profile and would break the cookie-injection path when off).
+  const incognito = !!opts.incognito;
   let browser = null;
   let cdp;
   // Forward caller-supplied launch knobs into every launch() below,
@@ -243,8 +271,9 @@ export async function connect(opts = {}) {
     await suppressPermissions(cdp);
   }
 
-  // Load storage state (cookies + localStorage) from file
-  if (opts.storageState) {
+  // Load storage state (cookies + localStorage) from file.
+  // Skipped under incognito — storageState is an auth source too.
+  if (opts.storageState && !incognito) {
     try {
       const { readFileSync } = await import('node:fs');
       const state = JSON.parse(readFileSync(opts.storageState, 'utf8'));
@@ -439,7 +468,10 @@ export async function connect(opts = {}) {
     },
 
     async injectCookies(url, cookieOpts) {
-      await authenticate(page.session, url, { browser: cookieOpts?.browser });
+      // No-op under incognito: callers (MCP goto, daemon) inject unconditionally,
+      // so the gate has to live here, not just at the call site.
+      if (incognito) return 0;
+      return authenticate(page.session, url, { browser: cookieOpts?.browser });
     },
 
     async snapshot(pruneOpts) {
@@ -655,7 +687,8 @@ export async function connect(opts = {}) {
         },
         get botBlocked() { return tabBotBlocked; },
         async injectCookies(url, cookieOpts) {
-          await authenticate(tab.session, url, { browser: cookieOpts?.browser });
+          if (incognito) return 0;
+          return authenticate(tab.session, url, { browser: cookieOpts?.browser });
         },
         waitForNetworkIdle(idleOpts = {}) {
           return waitForNetworkIdle(tab.session, idleOpts);
@@ -708,6 +741,55 @@ async function suppressPermissions(cdp) {
   }
 }
 
+/**
+ * Firefox path for connect(): launch Firefox, open a BiDi session, and return
+ * a BiDi-backed page object. Separate from the CDP path because the transport,
+ * 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 })
+ * @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 page = await createFirefoxPage(bidi, {
+    pruneMode: opts.pruneMode,
+    urlGuard: { allowLocalUrls: opts.allowLocalUrls, blockPrivateNetwork: opts.blockPrivateNetwork },
+    uploadDir: opts.uploadDir || null,
+    incognito: !!opts.incognito,
+    consent: opts.consent,
+  });
+  const closePage = page.close.bind(page);
+  page.close = async () => {
+    await closePage();
+    await cleanupFirefox(browser);
+  };
+  return page;
+}
+
 /**
  * Create a new page target and return a session-scoped handle.
  * @param {object} cdp - CDP client

package/src/network-idle.js

@@ -2,24 +2,27 @@
  * network-idle.js — wait until the page's network has been idle for N ms.
  *
  * Tracks in-flight requests by requestId in a Set, so an orphan
- * loadingFinished/Failed (event for a request whose requestWillBeSent
- * arrived before our listener attached) is a harmless no-op instead of
- * driving a counter negative and resolving prematurely.
+ * finish/fail event (for a request whose start event arrived before our
+ * listener attached) is a harmless no-op instead of driving a counter
+ * negative and resolving prematurely.
+ *
+ * Two engines, one core: `waitForNetworkIdle` wires the CDP `Network.*`
+ * events, `waitForNetworkIdleBiDi` wires the WebDriver BiDi `network.*`
+ * events. Both feed the same orphan-resilient idle waiter (`idleWaiter`).
  */
 
 /**
- * @param {object} session - CDP session-scoped handle with .on() returning unsub
- * @param {object} [opts]
- * @param {number} [opts.timeout=30000] - Max wait time before reject
- * @param {number} [opts.idle=500] - Required idle duration before resolve
+ * Shared idle-detection loop. `attach` registers the engine-specific event
+ * listeners, calling onStart(id) when a request begins and onEnd(id) when it
+ * finishes/fails, and pushing each listener's unsub fn into `unsubs`.
+ * @param {object} cfg
+ * @param {number} cfg.timeout - Max wait before reject
+ * @param {number} cfg.idle - Required quiet duration before resolve
+ * @param {(hooks: {onStart: (id:any)=>void, onEnd: (id:any)=>void, unsubs: Array<()=>void>}) => void} cfg.attach
  * @returns {Promise<void>}
  */
-export function waitForNetworkIdle(session, opts = {}) {
-  const timeout = opts.timeout || 30000;
-  const idle = opts.idle || 500;
-
-  /** @type {Promise<void>} */
-  const settled = new Promise((resolve, reject) => {
+function idleWaiter({ timeout, idle, attach }) {
+  return new Promise((resolve, reject) => {
     const pending = new Set();
     let timer = null;
     const unsubs = [];
@@ -38,20 +41,12 @@ export function waitForNetworkIdle(session, opts = {}) {
       }
     };
 
-    unsubs.push(session.on('Network.requestWillBeSent', (p) => {
-      pending.add(p.requestId);
-      clearTimeout(timer);
-    }));
-    unsubs.push(session.on('Network.loadingFinished', (p) => {
-      // delete() on a Set is a no-op for unknown keys — orphan events from
-      // requests started before we attached the listener can't push us negative.
-      pending.delete(p.requestId);
-      check();
-    }));
-    unsubs.push(session.on('Network.loadingFailed', (p) => {
-      pending.delete(p.requestId);
-      check();
-    }));
+    const onStart = (id) => { pending.add(id); clearTimeout(timer); };
+    // delete() on a Set is a no-op for unknown keys — orphan finish/fail
+    // events from requests started before we attached can't push us negative.
+    const onEnd = (id) => { pending.delete(id); check(); };
+
+    attach({ onStart, onEnd, unsubs });
 
     const deadlineTimer = setTimeout(() => {
       for (const unsub of unsubs) unsub();
@@ -61,5 +56,48 @@ export function waitForNetworkIdle(session, opts = {}) {
     // Start check immediately (might already be idle)
     check();
   });
-  return settled;
+}
+
+/**
+ * CDP: wait for network idle over `Network.*` events.
+ * @param {object} session - CDP session-scoped handle with .on() returning unsub
+ * @param {object} [opts]
+ * @param {number} [opts.timeout=30000] - Max wait time before reject
+ * @param {number} [opts.idle=500] - Required idle duration before resolve
+ * @returns {Promise<void>}
+ */
+export function waitForNetworkIdle(session, opts = {}) {
+  return idleWaiter({
+    timeout: opts.timeout || 30000,
+    idle: opts.idle || 500,
+    attach: ({ onStart, onEnd, unsubs }) => {
+      unsubs.push(session.on('Network.requestWillBeSent', (p) => onStart(p.requestId)));
+      unsubs.push(session.on('Network.loadingFinished', (p) => onEnd(p.requestId)));
+      unsubs.push(session.on('Network.loadingFailed', (p) => onEnd(p.requestId)));
+    },
+  });
+}
+
+/**
+ * Firefox/BiDi: wait for network idle over `network.*` events. Subscribes the
+ * events first (idempotent — safe even if the daemon already subscribed for
+ * log capture), then runs the same orphan-resilient idle loop. The in-flight
+ * key is `params.request.request` (the BiDi request id).
+ * @param {object} bidi - BiDi client with async .subscribe() and .on() returning unsub
+ * @param {object} [opts]
+ * @param {number} [opts.timeout=30000] - Max wait time before reject
+ * @param {number} [opts.idle=500] - Required idle duration before resolve
+ * @returns {Promise<void>}
+ */
+export async function waitForNetworkIdleBiDi(bidi, opts = {}) {
+  await bidi.subscribe(['network.beforeRequestSent', 'network.responseCompleted', 'network.fetchError']);
+  return idleWaiter({
+    timeout: opts.timeout || 30000,
+    idle: opts.idle || 500,
+    attach: ({ onStart, onEnd, unsubs }) => {
+      unsubs.push(bidi.on('network.beforeRequestSent', (p) => onStart(p.request.request)));
+      unsubs.push(bidi.on('network.responseCompleted', (p) => onEnd(p.request.request)));
+      unsubs.push(bidi.on('network.fetchError', (p) => onEnd(p.request.request)));
+    },
+  });
 }

package/src/readable.js

@@ -72,21 +72,21 @@ export function formatReadable(r) {
 }
 
 /**
- * Extract the main article from the current page.
- * @param {object} session - CDP session-scoped handle (.send()).
- * @returns {Promise<object>} One of:
- *   { ok: false, hint }                              — no article content found
- *   { ok: true, title, byline, text, length,
- *     confidence: 'high'|'low', readerable, hint? }  — extracted article
+ * The in-page extraction expression (Readability injected + run). Exported so
+ * non-CDP transports (BiDi/Firefox) can evaluate the same source and feed the
+ * raw result through finalizeReadable() — keeping every engine's output
+ * identical.
  */
-export async function readable(session) {
-  const { result } = await session.send('Runtime.evaluate', {
-    expression: EXTRACT_EXPRESSION,
-    returnByValue: true,
-    awaitPromise: true,
-  });
-  const r = result.value || {};
+export { EXTRACT_EXPRESSION };
 
+/**
+ * Turn the raw in-page extraction result into the public readable() shape,
+ * applying the advisory confidence rule. Transport-agnostic.
+ * @param {object} r - raw result from EXTRACT_EXPRESSION
+ * @returns {object} public readable() result
+ */
+export function finalizeReadable(r) {
+  r = r || {};
   if (!r.ok) {
     return {
       ok: false,
@@ -95,22 +95,34 @@ export async function readable(session) {
         : 'no article content found on this page; use snapshot() instead',
     };
   }
-
   // Advisory confidence: high only when the reader-view heuristic agrees AND
   // there is a substantial amount of text. Low is not an error — the text is
   // still returned; it just means "verify, or prefer snapshot()".
   const confidence = r.readerable && r.length >= MIN_ARTICLE_CHARS ? 'high' : 'low';
   const out = {
     ok: true,
-    title: r.title,
-    byline: r.byline,
-    text: r.text,
-    length: r.length,
-    readerable: r.readerable,
-    confidence,
+    title: r.title, byline: r.byline, text: r.text, length: r.length,
+    readerable: r.readerable, confidence,
   };
   if (confidence === 'low') {
     out.hint = 'low article confidence — this may not be an article; consider snapshot()';
   }
   return out;
 }
+
+/**
+ * Extract the main article from the current page.
+ * @param {object} session - CDP session-scoped handle (.send()).
+ * @returns {Promise<object>} One of:
+ *   { ok: false, hint }                              — no article content found
+ *   { ok: true, title, byline, text, length,
+ *     confidence: 'high'|'low', readerable, hint? }  — extracted article
+ */
+export async function readable(session) {
+  const { result } = await session.send('Runtime.evaluate', {
+    expression: EXTRACT_EXPRESSION,
+    returnByValue: true,
+    awaitPromise: true,
+  });
+  return finalizeReadable(result.value || {});
+}

package/src/stealth-firefox.js

@@ -0,0 +1,42 @@
+/**
+ * stealth-firefox.js — Anti-detection patches for headless Firefox (BiDi).
+ *
+ * Deliberately MUCH smaller than the Chromium stealth.js. That isn't laziness —
+ * it's what a POC measured stock Firefox-under-BiDi to actually expose:
+ *
+ *   navigator.webdriver  → true   (the tell — we hide it)
+ *   window.chrome        → absent (correct; ADDING it would be a spoof tell)
+ *   navigator.plugins    → 5      (realistic PDF set; already normal)
+ *   languages / hardwareConcurrency → normal (en-US,en / 8)
+ *   User-Agent           → real Firefox, NO "Headless" marker (no rewrite needed)
+ *   WebGL vendor/renderer → the REAL GPU, not SwiftShader (spoofing would
+ *                           replace a real value with a fake one)
+ *
+ * So porting Chromium's STEALTH_SCRIPT verbatim would have made Firefox look
+ * like a spoofed browser (window.chrome + Chrome plugins on Firefox = obvious
+ * tell) — a worse fingerprint than the one removed. The only genuinely
+ * engine-agnostic pieces are webdriver-hiding and canvas noise, both reused
+ * verbatim from stealth.js so their fixes stay single-sourced.
+ *
+ * BiDi's script.addPreloadScript is the equivalent of CDP's
+ * Page.addScriptToEvaluateOnNewDocument — the POC confirmed it runs BEFORE any
+ * page script (navigator.webdriver read at parse time already saw `undefined`).
+ */
+
+import { WEBDRIVER_PATCH, CANVAS_NOISE_PATCH } from './stealth.js';
+
+const FIREFOX_STEALTH_SCRIPT = `${WEBDRIVER_PATCH}\n${CANVAS_NOISE_PATCH}`;
+
+/**
+ * Register the Firefox stealth patches so they run before any page script.
+ * Must be called before the first navigation. addPreloadScript is global
+ * (applies to every browsing context / navigation), so a single registration
+ * covers the whole session.
+ *
+ * @param {object} bidi - BiDi client from createBiDi()
+ */
+export async function applyFirefoxStealth(bidi) {
+  await bidi.send('script.addPreloadScript', {
+    functionDeclaration: `() => { ${FIREFOX_STEALTH_SCRIPT} }`,
+  });
+}

package/src/stealth.js

@@ -5,9 +5,114 @@
  * any page scripts (unlike Runtime.evaluate which runs after).
  */
 
+/**
+ * navigator.webdriver hiding — the one automation tell shared by every engine
+ * (Chromium headless AND Firefox-under-BiDi both report `true`). Split out so
+ * the Firefox stealth path (stealth-firefox.js) reuses the exact same patch
+ * instead of duplicating it. Measured baseline on both engines: `true`.
+ *
+ * A naive `Object.defineProperty(navigator, 'webdriver', …)` hides the *value*
+ * but leaves an advanced tell: it creates an OWN property on the instance, so
+ * `navigator.hasOwnProperty('webdriver')` becomes `true` where a real browser
+ * (property lives on Navigator.prototype) reports `false` — sophisticated
+ * anti-bot checks (e.g. sannysoft's "WebDriver New") catch that inconsistency.
+ * So we DELETE the getter off the prototype instead: then `navigator.webdriver`
+ * is `undefined` AND `'webdriver' in navigator` AND `hasOwnProperty` are both
+ * `false`, matching a stock browser. POC-verified on Chromium and Firefox
+ * (own/in both false, prototype descriptor gone). The defineProperty fallback
+ * only fires if the descriptor is somehow non-configurable (delete a no-op).
+ */
+export const WEBDRIVER_PATCH = `
+  try {
+    const proto = Object.getPrototypeOf(navigator);
+    const desc = proto && Object.getOwnPropertyDescriptor(proto, 'webdriver');
+    if (desc && desc.configurable) delete proto.webdriver;
+    if (navigator.webdriver) {
+      Object.defineProperty(navigator, 'webdriver', { get: () => undefined, configurable: true });
+    }
+  } catch {}
+`;
+
+/**
+ * Canvas-fingerprint noise — browser-agnostic (standard Canvas2D API), so both
+ * the Chromium and Firefox stealth scripts compose it. This block carries the
+ * subtle double-XOR-cancellation fixes (see git history / project memory); keep
+ * it SINGLE-SOURCED here so a fix never has to be made in two places.
+ */
+export const CANVAS_NOISE_PATCH = `
+  // Canvas fingerprinting — sites render standard text/shapes, then read
+  // pixels via toDataURL or getImageData. The output is stable per machine
+  // (GPU, font rasterizer, anti-aliasing) but unique across machines, which
+  // makes it the second-most-common fingerprint after WebGL. Defense: nudge
+  // a few RGB channels by ±1 per session so the hash changes each visit
+  // while the canvas still looks identical to the human eye. The per-tab
+  // seed keeps reads stable within a session so legitimate canvas use
+  // (image processing, games) doesn't flicker.
+  // crypto.getRandomValues is guaranteed unique per browsing context; using
+  // Math.random alone can collide when two fresh V8 contexts start within
+  // microseconds of each other (real-world: parallel tests, real-world hit:
+  // we observed it). performance.now adds a wall-clock anchor as a belt-and-
+  // braces guard against contexts where crypto is somehow stubbed.
+  const _seedBuf = new Uint32Array(1);
+  crypto.getRandomValues(_seedBuf);
+  const CANVAS_SEED = (_seedBuf[0] ^ ((performance.now() * 1e6) | 0)) >>> 0;
+  function shiftPixels(data) {
+    // Touch ~1 byte per 64-byte stride. The bit we XOR with is taken from a
+    // position-dependent SLICE of a seed-mixed hash, not its low bit — a
+    // naive 'mix & 1' collapses to only two possible outputs per seed
+    // parity because every stride index is even (the position multiplier
+    // is odd, so the low bit only depends on seed parity). Indexing the
+    // hash by (i/64) mod 32 makes every stride position sample a different
+    // bit, so two distinct seeds produce different mask patterns.
+    for (let i = 0; i < data.length; i += 64) {
+      const h = ((CANVAS_SEED * 2654435761) ^ (i * 1597334677)) >>> 0;
+      const bit = (h >>> ((i >>> 6) & 31)) & 1;
+      data[i] = (data[i] ^ bit) & 0xff;
+    }
+    return data;
+  }
+  // Capture originals BEFORE replacing — toDataURL must read pixels via the
+  // native getImageData (not the patched one), otherwise the patch double-
+  // applies and the second XOR cancels the first, leaving output unchanged.
+  const origGetImageData = CanvasRenderingContext2D.prototype.getImageData;
+  const origToDataURL = HTMLCanvasElement.prototype.toDataURL;
+  HTMLCanvasElement.prototype.toDataURL = function() {
+    const ctx = this.getContext('2d');
+    if (ctx && this.width > 0 && this.height > 0) {
+      try {
+        const img = origGetImageData.call(ctx, 0, 0, this.width, this.height);
+        // Snapshot the original bytes so we can restore them after encoding.
+        // Without this, repeated toDataURL() alternates noisy/clean: call 1
+        // XORs the canvas in place, call 2 reads the noisy canvas and XORs
+        // again (self-inverse), call 3 again, etc. Same XOR-cancellation
+        // class as the earlier double-apply bug, just through canvas state
+        // rather than method composition. The restore also keeps the
+        // bitmap idempotent for any downstream legitimate canvas reads.
+        const original = new Uint8ClampedArray(img.data);
+        shiftPixels(img.data);
+        ctx.putImageData(img, 0, 0);
+        const result = origToDataURL.apply(this, arguments);
+        img.data.set(original);
+        ctx.putImageData(img, 0, 0);
+        return result;
+      } catch {
+        // Tainted canvas (cross-origin image) — can't read; skip the nudge
+        // and fall through to the original call so the page sees the
+        // expected SecurityError instead of silent corruption.
+      }
+    }
+    return origToDataURL.apply(this, arguments);
+  };
+  CanvasRenderingContext2D.prototype.getImageData = function() {
+    const img = origGetImageData.apply(this, arguments);
+    shiftPixels(img.data);
+    return img;
+  };
+`;
+
 const STEALTH_SCRIPT = `
   // Hide webdriver flag
-  Object.defineProperty(navigator, 'webdriver', { get: () => undefined });
+  ${WEBDRIVER_PATCH}
 
   // Fake plugins (headless has 0)
   Object.defineProperty(navigator, 'plugins', {
@@ -93,74 +198,7 @@ const STEALTH_SCRIPT = `
     };
   }
 
-  // Canvas fingerprinting — sites render standard text/shapes, then read
-  // pixels via toDataURL or getImageData. The output is stable per machine
-  // (GPU, font rasterizer, anti-aliasing) but unique across machines, which
-  // makes it the second-most-common fingerprint after WebGL. Defense: nudge
-  // a few RGB channels by ±1 per session so the hash changes each visit
-  // while the canvas still looks identical to the human eye. The per-tab
-  // seed keeps reads stable within a session so legitimate canvas use
-  // (image processing, games) doesn't flicker.
-  // crypto.getRandomValues is guaranteed unique per browsing context; using
-  // Math.random alone can collide when two fresh V8 contexts start within
-  // microseconds of each other (real-world: parallel tests, real-world hit:
-  // we observed it). performance.now adds a wall-clock anchor as a belt-and-
-  // braces guard against contexts where crypto is somehow stubbed.
-  const _seedBuf = new Uint32Array(1);
-  crypto.getRandomValues(_seedBuf);
-  const CANVAS_SEED = (_seedBuf[0] ^ ((performance.now() * 1e6) | 0)) >>> 0;
-  function shiftPixels(data) {
-    // Touch ~1 byte per 64-byte stride. The bit we XOR with is taken from a
-    // position-dependent SLICE of a seed-mixed hash, not its low bit — a
-    // naive 'mix & 1' collapses to only two possible outputs per seed
-    // parity because every stride index is even (the position multiplier
-    // is odd, so the low bit only depends on seed parity). Indexing the
-    // hash by (i/64) mod 32 makes every stride position sample a different
-    // bit, so two distinct seeds produce different mask patterns.
-    for (let i = 0; i < data.length; i += 64) {
-      const h = ((CANVAS_SEED * 2654435761) ^ (i * 1597334677)) >>> 0;
-      const bit = (h >>> ((i >>> 6) & 31)) & 1;
-      data[i] = (data[i] ^ bit) & 0xff;
-    }
-    return data;
-  }
-  // Capture originals BEFORE replacing — toDataURL must read pixels via the
-  // native getImageData (not the patched one), otherwise the patch double-
-  // applies and the second XOR cancels the first, leaving output unchanged.
-  const origGetImageData = CanvasRenderingContext2D.prototype.getImageData;
-  const origToDataURL = HTMLCanvasElement.prototype.toDataURL;
-  HTMLCanvasElement.prototype.toDataURL = function() {
-    const ctx = this.getContext('2d');
-    if (ctx && this.width > 0 && this.height > 0) {
-      try {
-        const img = origGetImageData.call(ctx, 0, 0, this.width, this.height);
-        // Snapshot the original bytes so we can restore them after encoding.
-        // Without this, repeated toDataURL() alternates noisy/clean: call 1
-        // XORs the canvas in place, call 2 reads the noisy canvas and XORs
-        // again (self-inverse), call 3 again, etc. Same XOR-cancellation
-        // class as the earlier double-apply bug, just through canvas state
-        // rather than method composition. The restore also keeps the
-        // bitmap idempotent for any downstream legitimate canvas reads.
-        const original = new Uint8ClampedArray(img.data);
-        shiftPixels(img.data);
-        ctx.putImageData(img, 0, 0);
-        const result = origToDataURL.apply(this, arguments);
-        img.data.set(original);
-        ctx.putImageData(img, 0, 0);
-        return result;
-      } catch {
-        // Tainted canvas (cross-origin image) — can't read; skip the nudge
-        // and fall through to the original call so the page sees the
-        // expected SecurityError instead of silent corruption.
-      }
-    }
-    return origToDataURL.apply(this, arguments);
-  };
-  CanvasRenderingContext2D.prototype.getImageData = function() {
-    const img = origGetImageData.apply(this, arguments);
-    shiftPixels(img.data);
-    return img;
-  };
+  ${CANVAS_NOISE_PATCH}
 `;
 
 /**

package/types/auth.d.ts

@@ -25,9 +25,26 @@ export function injectCookies(session: object, cookies: Array<object>): Promise<
  * @returns {boolean}
  */
 export function cookieDomainMatch(host: string, cookieDomain: string): boolean;
+/**
+ * Select the user's cookies that are in-scope for `url`. Shared by BOTH engines
+ * (CDP `authenticate` and Firefox/BiDi `injectCookies`) so they can't drift on
+ * scoping — a divergence here re-opens loading the entire cookie jar into an
+ * agent session. Returns the filtered cookie array; never injects.
+ *
+ * Coarse SQL pre-filter strips to a registrable-ish domain so the LIKE query
+ * returns a superset (incl. parent-domain cookies). slice(-2) is a cheap
+ * heuristic — it over-selects for multi-part eTLDs (co.uk) and as a substring
+ * match, so the precise RFC-6265 domain-match is what actually decides which
+ * cookies pass. Without it, browsing apple.com would match apple.com.evil.org
+ * and every *.co.uk site (verified).
+ * @param {string} url - URL whose host the cookies must match
+ * @param {object} [opts] - passed to extractCookies (e.g. { browser })
+ * @returns {Array<object>} cookies whose domain matches the URL host
+ */
+export function scopedCookiesForUrl(url: string, opts?: object): Array<object>;
 /**
  * Extract cookies for a URL and inject them into a CDP session.
- * Convenience function combining extractCookies + injectCookies.
+ * Convenience function combining scopedCookiesForUrl + injectCookies.
  * @param {object} session - CDP session handle
  * @param {string} url - URL to extract cookies for
  * @param {object} [opts] - Options passed to extractCookies

package/types/ax-snapshot.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Build the script.evaluate expression that reconstructs the AX tree in a
+ * context, assigning refs from `base`.
+ * @param {number} base - Starting ref offset (exclusive; first ref is base+1)
+ * @returns {string} JS expression returning JSON { tree, count }
+ */
+export function axSnapshotExpression(base: number): string;
+/**
+ * ax-snapshot.js — Reconstruct a CDP-shaped accessibility tree in-page.
+ *
+ * CDP hands you Accessibility.getFullAXTree; BiDi has no equivalent, so on
+ * Firefox we rebuild an equivalent tree inside the page via script.evaluate.
+ * The output tree uses the SAME node shape and role vocabulary as
+ * buildTree()'s CDP output, so prune.js and aria.js consume it unchanged:
+ *
+ *   { nodeId, role, name, properties, children, ignored }
+ *
+ * where `role` is CDP/ARIA vocabulary ('RootWebArea', 'StaticText', 'heading',
+ * 'link', 'button', 'img', 'paragraph', 'list', 'navigation', …), NOT tag
+ * names. The three things getFullAXTree gave us for free and we reimplement:
+ *   1. implicit ARIA role mapping (HTML element → role)
+ *   2. accessible-name computation (aria-labelledby → aria-label → native
+ *      label/alt/legend/title → text content) — the POC proved textContent
+ *      alone is NOT enough (img alt, <label>, aria-labelledby all missed).
+ *   3. hidden-subtree filtering (aria-hidden, display:none, visibility:hidden,
+ *      the hidden attribute).
+ *
+ * Each kept element is tagged with a data-bb-ref attribute carrying its ref,
+ * so firefox-page.js (resolveRef) can resolve a ref back to its element via
+ * querySelector.
+ * Refs are assigned from a caller-supplied `base` so they stay globally unique
+ * across browsing contexts (iframes), matching CDP's flat integer refs.
+ */
+/** Attribute used to tag elements for ref → element resolution. */
+export const REF_ATTR: "data-bb-ref";