barebrowse 0.14.0 → 0.17.0

package/src/firefox-page.js

@@ -0,0 +1,445 @@
+/**
+ * firefox-page.js — A barebrowse page object backed by WebDriver BiDi (Firefox).
+ *
+ * Mirrors the core of connect()'s CDP page surface — goto, snapshot, click,
+ * type, press, scroll, hover, readable, injectCookies, close — but every
+ * operation goes over BiDi instead of CDP. The tree that snapshot() feeds to
+ * prune.js/aria.js is reconstructed in-page by ax-snapshot.js (BiDi has no
+ * getFullAXTree), and refs resolve to elements through the data-bb-ref
+ * attribute those snapshots stamp on.
+ *
+ * Interactions use faithful BiDi input.performActions with an *element origin*
+ * (pointerMove auto-scrolls the element into view, then real pointerDown/Up
+ * fire) rather than a synthetic el.click(), so pages that need genuine mouse
+ * events behave. Refs are resolved to BiDi element sharedIds per context, so
+ * clicks land in the right frame.
+ */
+
+import { formatTree } from './aria.js';
+import { prune as pruneTree } from './prune.js';
+import { axSnapshotExpression, REF_ATTR } from './ax-snapshot.js';
+import { EXTRACT_EXPRESSION, finalizeReadable } from './readable.js';
+import { scopedCookiesForUrl } from './auth.js';
+import { assertNavigable, assertUploadAllowed } from './url-guard.js';
+import { dismissConsentFirefox } from './consent-firefox.js';
+import { waitForNetworkIdleBiDi } from './network-idle.js';
+
+/** BiDi/WebDriver normalized key values for named keys (U+E000 block). */
+const BIDI_KEYS = {
+  Enter: "\uE007", Tab: "\uE004", Escape: "\uE00C", Backspace: "\uE003",
+  Delete: "\uE017", ArrowUp: "\uE013", ArrowDown: "\uE015",
+  ArrowLeft: "\uE012", ArrowRight: "\uE014", Home: "\uE011", End: "\uE010",
+  PageUp: "\uE00E", PageDown: "\uE00F", Space: " ",
+};
+
+/**
+ * Build a Firefox/BiDi-backed page object.
+ * @param {object} bidi - BiDi client from createBiDi()
+ * @param {object} [opts]
+ * @param {'act'|'browse'|'navigate'|'full'|'read'} [opts.pruneMode='act'] - Default prune mode.
+ * @param {{allowLocalUrls?: boolean, blockPrivateNetwork?: boolean}} [opts.urlGuard] - Navigation safety policy, applied on every goto().
+ * @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().
+ * @returns {Promise<object>} page object
+ */
+export async function createFirefoxPage(bidi, opts = {}) {
+  const defaultPruneMode = opts.pruneMode || 'act';
+  const urlGuard = opts.urlGuard || {};
+  const uploadDir = opts.uploadDir || null;
+  const incognito = !!opts.incognito;
+  const consent = opts.consent !== false;
+  // 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', {});
+  let topContext = contexts[0].context;
+
+  // ref (string int) → owning browsing-context id, rebuilt every snapshot so a
+  // click after a snapshot routes to the frame the element actually lives in.
+  let refContexts = new Map();
+
+  /**
+   * Depth-first list of the ACTIVE tab's contexts (main frame + descendant
+   * frames). Scoped to `topContext` via getTree's `root` param — without it
+   * getTree returns every open tab flat, and after switchTab() to a non-first
+   * tab the positional iframe-splice in snapshot() grafts another tab's frame
+   * into the active tab (verified: INNER1 leaked into TAB2). Root-scoping keeps
+   * topContext at index 0 so the splice stays aligned and cross-tab-safe.
+   */
+  async function allContexts() {
+    const { contexts: tree } = await bidi.send('browsingContext.getTree', { root: topContext });
+    const flat = [];
+    (function walk(nodes) {
+      for (const n of nodes) { flat.push(n.context); walk(n.children || []); }
+    })(tree);
+    return flat;
+  }
+
+  /**
+   * Build the spliced AX tree for the active tab (main frame + child frames)
+   * and (re)populate refContexts so a subsequent click routes to the right
+   * frame. Returns the top context's root node, or null if it couldn't be
+   * snapshotted. Shared by snapshot() and the consent auto-dismiss so the
+   * iframe-splice logic lives in one place.
+   */
+  async function buildTree() {
+    const contextIds = await allContexts();
+    refContexts = new Map();
+
+    // Snapshot each context, assigning refs from a shared running counter so
+    // they're globally unique (matching CDP's flat integer refs).
+    let base = 0;
+    const treesByContext = new Map();
+    for (const ctx of contextIds) {
+      let raw;
+      try {
+        raw = await bidi.evaluate(ctx, axSnapshotExpression(base), false);
+      } catch { continue; } // frame navigated mid-snapshot — skip it
+      const { tree, count } = JSON.parse(raw);
+      for (let r = base + 1; r <= base + count; r++) refContexts.set(String(r), ctx);
+      base += count;
+      treesByContext.set(ctx, tree);
+    }
+
+    // Splice each child frame's tree under an <iframe> (role 'Iframe')
+    // placeholder in its parent, matched by document order — BiDi getTree
+    // lists children in frame order, and the AX walk emits Iframe nodes in
+    // the same order.
+    const iframeNodes = (tree) => {
+      const out = [];
+      (function walk(n) { if (n.role === 'Iframe') out.push(n); for (const c of n.children) walk(c); })(tree);
+      return out;
+    };
+    for (let i = 1; i < contextIds.length; i++) {
+      const childTree = treesByContext.get(contextIds[i]);
+      if (!childTree) continue;
+      // Attach to the next unfilled Iframe placeholder in the top tree.
+      const holders = iframeNodes(treesByContext.get(topContext) || { role: '', children: [] });
+      const holder = holders[i - 1];
+      if (holder) holder.children = [childTree];
+    }
+
+    return treesByContext.get(topContext) || null;
+  }
+
+  /** Resolve a ref to a BiDi element sharedId in its owning context. */
+  async function resolveRef(ref) {
+    const context = refContexts.get(String(ref));
+    if (!context) throw new Error(`Unknown ref: ${ref} (snapshot first, or it's stale)`);
+    const res = await bidi.send('script.evaluate', {
+      expression: `document.querySelector('[${REF_ATTR}="${ref}"]')`,
+      target: { context }, awaitPromise: false, resultOwnership: 'root',
+    });
+    if (res.type === 'exception' || !res.result || res.result.type !== 'node') {
+      throw new Error(`Could not resolve element for ref ${ref}`);
+    }
+    return { context, sharedId: res.result.sharedId };
+  }
+
+  async function pointerClick(ref) {
+    const { context, sharedId } = await resolveRef(ref);
+    await bidi.send('input.performActions', {
+      context,
+      actions: [{
+        type: 'pointer', id: 'mouse', parameters: { pointerType: 'mouse' },
+        actions: [
+          { type: 'pointerMove', x: 0, y: 0, origin: { type: 'element', element: { sharedId } } },
+          { type: 'pointerDown', button: 0 },
+          { type: 'pointerUp', button: 0 },
+        ],
+      }],
+    });
+  }
+
+  async function keyType(context, text) {
+    const actions = [];
+    for (const ch of text) { actions.push({ type: 'keyDown', value: ch }, { type: 'keyUp', value: ch }); }
+    await bidi.send('input.performActions', {
+      context, actions: [{ type: 'key', id: 'kbd', actions }],
+    });
+  }
+
+  /**
+   * Reject if `p` doesn't settle within `ms`. BiDi commands have no built-in
+   * timeout, so a navigate/reload/traverse whose `wait:'complete'` never fires
+   * (a page that never loads) would otherwise hang the call forever.
+   */
+  function withTimeout(p, ms, label) {
+    let timer;
+    const t = new Promise((_, rej) => { timer = setTimeout(() => rej(new Error(`${label} timed out after ${ms}ms`)), ms); });
+    return Promise.race([p, t]).finally(() => clearTimeout(timer));
+  }
+
+  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; },
+
+    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);
+      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) {
+        try {
+          const root = await buildTree();
+          if (root) await dismissConsentFirefox(root, (ref) => pointerClick(ref));
+        } catch { /* consent dismissal is best-effort */ }
+      }
+    },
+
+    async snapshot(pruneOpts) {
+      const root = await buildTree();
+      if (!root) return '';
+
+      const pageUrl = await bidi.evaluate(topContext, 'location.href', false).catch(() => '');
+      const raw = formatTree(root);
+      if (pruneOpts === false) return `url: ${pageUrl}\n` + raw;
+
+      const mode = pruneOpts?.mode || defaultPruneMode;
+      const pruned = pruneTree(root, { mode });
+      const out = pruned ? formatTree(pruned) : '';
+      const stats = `url: ${pageUrl}\n${raw.length.toLocaleString()} chars → ${out.length.toLocaleString()} chars`
+        + ` (${raw.length ? Math.round((1 - out.length / raw.length) * 100) : 0}% pruned)`;
+      return stats + '\n' + out;
+    },
+
+    async readable() {
+      const raw = await bidi.evaluate(topContext, `JSON.stringify(${EXTRACT_EXPRESSION})`, true);
+      return finalizeReadable(JSON.parse(raw));
+    },
+
+    async click(ref) { await pointerClick(ref); },
+
+    async type(ref, text, typeOpts = {}) {
+      const { context, sharedId } = await resolveRef(ref);
+      // Focus the field (and optionally clear it) in-page, then send real key
+      // events so input handlers fire.
+      await bidi.send('script.callFunction', {
+        functionDeclaration: `function(clear){ this.focus(); if(clear){ if('value' in this) this.value=''; else this.textContent=''; this.dispatchEvent(new Event('input',{bubbles:true})); } }`,
+        arguments: [{ type: 'boolean', value: !!typeOpts.clear }],
+        this: { sharedId },
+        target: { context }, awaitPromise: false,
+      });
+      await keyType(context, text);
+    },
+
+    async press(key) {
+      const value = BIDI_KEYS[key] || (key.length === 1 ? key : null);
+      if (!value) throw new Error(`Unknown key: "${key}". Valid: ${Object.keys(BIDI_KEYS).join(', ')}`);
+      await bidi.send('input.performActions', {
+        context: topContext,
+        actions: [{ type: 'key', id: 'kbd', actions: [{ type: 'keyDown', value }, { type: 'keyUp', value }] }],
+      });
+    },
+
+    async scroll(deltaY) {
+      await bidi.evaluate(topContext, `window.scrollBy(0, ${Number(deltaY)})`, false);
+    },
+
+    async hover(ref) {
+      const { context, sharedId } = await resolveRef(ref);
+      await bidi.send('input.performActions', {
+        context,
+        actions: [{
+          type: 'pointer', id: 'mouse', parameters: { pointerType: 'mouse' },
+          actions: [{ type: 'pointerMove', x: 0, y: 0, origin: { type: 'element', element: { sharedId } } }],
+        }],
+      });
+    },
+
+    /**
+     * Inject cookies from the user's real browser into this Firefox session,
+     * via BiDi storage.setCookie. Scoped to the URL host via the SHARED
+     * scopedCookiesForUrl (same as the CDP path) — never the whole jar.
+     */
+    async injectCookies(url, cookieOpts) {
+      if (incognito) return 0;
+      const cookies = scopedCookiesForUrl(url, { browser: cookieOpts?.browser });
+      let injected = 0;
+      for (const c of cookies) {
+        const cookie = {
+          name: c.name,
+          value: { type: 'string', value: String(c.value ?? '') },
+          domain: String(c.domain || '').replace(/^\./, ''),
+          path: c.path || '/',
+        };
+        if (c.secure) cookie.secure = true;
+        if (c.httpOnly) cookie.httpOnly = true;
+        if (c.sameSite) cookie.sameSite = String(c.sameSite).toLowerCase();
+        if (c.expires && c.expires > 0) cookie.expiry = Math.floor(c.expires);
+        try { await bidi.send('storage.setCookie', { cookie }); injected++; } catch { /* skip bad cookie */ }
+      }
+      return injected;
+    },
+
+    async select(ref, value) {
+      const { context, sharedId } = await resolveRef(ref);
+      // Native <select>: set value + fire change. Custom dropdown: open then
+      // click the matching option. Mirrors interact.js's two strategies.
+      const handled = await bidi.send('script.callFunction', {
+        functionDeclaration: `function(v){
+          if (this.tagName === 'SELECT') {
+            const opt = Array.from(this.options).find(o => o.value === v || o.textContent.trim() === v);
+            if (opt) { this.value = opt.value; this.dispatchEvent(new Event('change',{bubbles:true})); return true; }
+            return false;
+          }
+          this.click();
+          return false;
+        }`,
+        arguments: [{ type: 'string', value }],
+        this: { sharedId }, target: { context }, awaitPromise: false,
+      });
+      if (handled.type === 'success' && handled.result?.value === true) return;
+      // Custom dropdown fallback: click a matching option after it opens.
+      await new Promise((r) => setTimeout(r, 300));
+      await bidi.evaluate(context, `(() => {
+        for (const o of document.querySelectorAll('[role="option"],[role="menuitem"],li[role="option"]')) {
+          if (o.textContent.trim() === ${JSON.stringify(value)}) { o.click(); return true; }
+        }
+        return false;
+      })()`, false);
+    },
+
+    async drag(fromRef, toRef) {
+      const from = await resolveRef(fromRef);
+      const to = await resolveRef(toRef);
+      if (from.context !== to.context) {
+        throw new Error('drag() between elements in different frames is not supported');
+      }
+      await bidi.send('input.performActions', {
+        context: from.context,
+        actions: [{
+          type: 'pointer', id: 'mouse', parameters: { pointerType: 'mouse' },
+          actions: [
+            { type: 'pointerMove', x: 0, y: 0, origin: { type: 'element', element: { sharedId: from.sharedId } } },
+            { type: 'pointerDown', button: 0 },
+            { type: 'pointerMove', x: 0, y: 0, origin: { type: 'element', element: { sharedId: to.sharedId } } },
+            { type: 'pointerUp', button: 0 },
+          ],
+        }],
+      });
+    },
+
+    async upload(ref, files) {
+      // Same upload sandbox the CDP path enforces: every path must resolve
+      // (symlinks included) inside uploadDir when set.
+      assertUploadAllowed(files, uploadDir);
+      const { context, sharedId } = await resolveRef(ref);
+      await bidi.send('input.setFiles', { context, element: { sharedId }, files });
+    },
+
+    async goBack() { await traverse(-1); },
+    async goForward() { await traverse(1); },
+
+    async reload() {
+      // Note: Firefox BiDi does not yet support the ignoreCache argument, so
+      // (unlike the CDP path) reload() always does a normal reload.
+      await withTimeout(
+        bidi.send('browsingContext.reload', { context: topContext, wait: 'complete' }),
+        30000, 'reload');
+      refContexts = new Map();
+      await new Promise((r) => setTimeout(r, 300));
+    },
+
+    async screenshot(screenshotOpts = {}) {
+      const fmt = screenshotOpts.format || 'png';
+      const type = fmt === 'jpeg' ? 'image/jpeg' : fmt === 'webp' ? 'image/webp' : 'image/png';
+      const format = { type };
+      if (type !== 'image/png') format.quality = (screenshotOpts.quality || 80) / 100;
+      const { data } = await bidi.send('browsingContext.captureScreenshot', { context: topContext, format });
+      return data; // base64
+    },
+
+    async pdf(pdfOpts = {}) {
+      const { data } = await bidi.send('browsingContext.print', {
+        context: topContext,
+        background: true,
+        orientation: pdfOpts.landscape ? 'landscape' : 'portrait',
+      });
+      return data; // base64
+    },
+
+    async tabs() {
+      const { contexts: tree } = await bidi.send('browsingContext.getTree', {});
+      const out = [];
+      for (let i = 0; i < tree.length; i++) {
+        const title = await bidi.evaluate(tree[i].context, 'document.title', false).catch(() => '');
+        out.push({ index: i, url: tree[i].url, title, context: tree[i].context });
+      }
+      return out;
+    },
+
+    async switchTab(index) {
+      const { contexts: tree } = await bidi.send('browsingContext.getTree', {});
+      if (index < 0 || index >= tree.length) throw new Error(`Tab index ${index} out of range (0-${tree.length - 1})`);
+      topContext = tree[index].context;
+      refContexts = new Map(); // refs from the previous tab are invalid
+      await bidi.send('browsingContext.activate', { context: topContext }).catch(() => {});
+    },
+
+    async waitFor(waitOpts = {}) {
+      const timeout = waitOpts.timeout || 30000;
+      const deadline = Date.now() + timeout;
+      while (Date.now() < deadline) {
+        if (waitOpts.text) {
+          const t = await bidi.evaluate(topContext, 'document.body ? document.body.innerText : ""', false).catch(() => '');
+          if (t && t.includes(waitOpts.text)) return;
+        }
+        if (waitOpts.selector) {
+          const found = await bidi.evaluate(topContext, `!!document.querySelector(${JSON.stringify(waitOpts.selector)})`, false).catch(() => false);
+          if (found) return;
+        }
+        await new Promise((r) => setTimeout(r, 200));
+      }
+      throw new Error(`waitFor timed out after ${timeout}ms`);
+    },
+
+    /**
+     * Wait until the network has been idle for `idle` ms, over BiDi
+     * network.* events. Parity with the CDP page.waitForNetworkIdle (Phase 2).
+     */
+    async waitForNetworkIdle(idleOpts = {}) {
+      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)');
+    },
+    async waitForNavigation() {
+      throw new Error('waitForNavigation() is not supported on the Firefox/BiDi engine (CDP-only)');
+    },
+
+    async close() {
+      try { await bidi.send('browsingContext.close', { context: topContext }); } catch {}
+      bidi.close();
+    },
+  };
+
+  /** Walk session history by delta and settle (BiDi has no load-wait here). */
+  async function traverse(delta) {
+    await withTimeout(
+      bidi.send('browsingContext.traverseHistory', { context: topContext, delta }),
+      30000, 'history navigation');
+    refContexts = new Map();
+    await new Promise((r) => setTimeout(r, 500));
+  }
+
+  return page;
+}

package/src/firefox.js

@@ -0,0 +1,203 @@
+/**
+ * firefox.js — Find and launch Firefox with WebDriver BiDi enabled.
+ *
+ * The BiDi counterpart to chromium.js. Firefox deprecated CDP, so it's driven
+ * over the W3C BiDi protocol instead. `--remote-debugging-port` starts
+ * Firefox's remote agent, which prints its BiDi endpoint to stderr:
+ *   "WebDriver BiDi listening on ws://127.0.0.1:PORT"
+ * The direct-connection socket (no geckodriver / WebDriver-classic handshake)
+ * is that URL + "/session" — createBiDi() appends it. No new dependency:
+ * BiDi rides the same `ws` transport as CDP.
+ *
+ * Like chromium.js we launch a fresh temp profile (never the user's live
+ * profile — that would profile-lock their running Firefox) and reap the
+ * process + profile dir on parent crash.
+ */
+
+import { execFileSync, spawn } from 'node:child_process';
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+/** Block the current thread for `ms` (sync, for the 'exit' reaper). */
+function sleepSync(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+// Reap launched Firefoxes on parent crash — mirrors chromium.js.
+const activeBrowsers = new Set();
+let exitHandlersRegistered = false;
+
+function reapAllSync() {
+  const toReap = [...activeBrowsers];
+  activeBrowsers.clear();
+  for (const b of toReap) {
+    try { if (!b.process.killed) b.process.kill('SIGKILL'); } catch {}
+    try { process.kill(-b.process.pid, 'SIGKILL'); } catch {}
+  }
+  for (const b of toReap) {
+    for (let i = 0; i < 20; i++) {
+      try { process.kill(b.process.pid, 0); } catch { break; }
+      sleepSync(50);
+    }
+    if (b.ownedProfileDir) {
+      try { rmSync(b.ownedProfileDir, { recursive: true, force: true }); } catch {}
+    }
+  }
+}
+
+function registerExitHandlers() {
+  if (exitHandlersRegistered) return;
+  exitHandlersRegistered = true;
+  process.once('exit', reapAllSync);
+  for (const sig of ['SIGINT', 'SIGTERM', 'SIGHUP']) {
+    process.once(sig, () => { reapAllSync(); process.kill(process.pid, sig); });
+  }
+}
+
+const CANDIDATES = [
+  'firefox',
+  'firefox-esr',
+  'firefox-developer-edition',
+  'librewolf',
+  '/Applications/Firefox.app/Contents/MacOS/firefox',
+];
+
+/**
+ * Find the first available Firefox binary on the system.
+ * @returns {string} Path to the binary
+ * @throws {Error} If no Firefox is found
+ */
+export function findFirefox() {
+  for (const candidate of CANDIDATES) {
+    try {
+      if (candidate.startsWith('/')) {
+        execFileSync('test', ['-f', candidate]);
+        return candidate;
+      }
+      const path = execFileSync('which', [candidate], {
+        encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'],
+      }).trim();
+      if (path) return path;
+    } catch { /* try next */ }
+  }
+  throw new Error(
+    'No Firefox binary found. Install Firefox (>= 121 for stable BiDi).\n' +
+    'On Fedora: sudo dnf install firefox'
+  );
+}
+
+/**
+ * Launch Firefox with WebDriver BiDi enabled and return its session WS URL.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.binary] - Firefox binary (auto-detected if omitted)
+ * @param {number} [opts.port=0] - Remote-agent port (0 = OS-assigned)
+ * @param {boolean} [opts.headed=false] - Launch with a visible window
+ * @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
+ * @returns {Promise<{wsUrl: string, process: import('node:child_process').ChildProcess, port: number, ownedProfileDir: string}>}
+ */
+export async function launchFirefox(opts = {}) {
+  const binary = opts.binary || findFirefox();
+  const port = opts.port || 0;
+  const profileDir = mkdtempSync(join(tmpdir(), 'barebrowse-ff-'));
+
+  // Proxy + prompt-suppressing prefs go in user.js (read at profile load).
+  const prefs = [
+    'user_pref("browser.shell.checkDefaultBrowser", false);',
+    'user_pref("datareporting.policy.dataSubmissionEnabled", false);',
+    'user_pref("dom.webnotifications.enabled", false);',
+    'user_pref("permissions.default.desktop-notification", 1);',
+    'user_pref("media.navigator.permission.disabled", true);',
+    'user_pref("geo.prompt.testing", true);',
+    'user_pref("geo.prompt.testing.allow", true);',
+  ];
+  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.
+    const raw = String(opts.proxy);
+    const scheme = (raw.match(/^(\w+):\/\//)?.[1] || '').toLowerCase();
+    const [host, pport] = raw.replace(/^\w+:\/\//, '').split(':');
+    const isSocks = scheme.startsWith('socks');
+    const port = Number(pport) || (isSocks ? 1080 : 8080);
+    prefs.push('user_pref("network.proxy.type", 1);');
+    if (isSocks) {
+      prefs.push(
+        `user_pref("network.proxy.socks", "${host}");`,
+        `user_pref("network.proxy.socks_port", ${port});`,
+        `user_pref("network.proxy.socks_version", ${scheme === 'socks4' ? 4 : 5});`,
+        'user_pref("network.proxy.socks_remote_dns", true);',
+      );
+    } else {
+      prefs.push(
+        `user_pref("network.proxy.http", "${host}");`,
+        `user_pref("network.proxy.http_port", ${port});`,
+        `user_pref("network.proxy.ssl", "${host}");`,
+        `user_pref("network.proxy.ssl_port", ${port});`,
+        'user_pref("network.proxy.share_proxy_settings", true);',
+      );
+    }
+  }
+  writeFileSync(join(profileDir, 'user.js'), prefs.join('\n'));
+
+  const args = [
+    '--remote-debugging-port', String(port),
+    '--no-remote', '--new-instance',
+    '--profile', profileDir,
+  ];
+  if (!opts.headed) args.push('--headless');
+  if (opts.viewport) args.push('--width', String(opts.viewport.width), '--height', String(opts.viewport.height));
+  args.push('about:blank');
+
+  // detached:true → own process group, so cleanup can signal the whole tree.
+  const child = spawn(binary, args, { stdio: ['ignore', 'pipe', 'pipe'], detached: true });
+
+  // Firefox prints the BiDi endpoint to stderr. Wait for it (or die trying).
+  const wsUrl = await new Promise((resolve, reject) => {
+    let buf = '';
+    const timeout = setTimeout(() => reject(new Error(`Firefox BiDi did not start within 20s. stderr: ${buf}`)), 20000);
+    const scan = (chunk) => {
+      buf += chunk.toString();
+      const m = buf.match(/WebDriver BiDi listening on (ws:\/\/\S+)/);
+      if (m) { clearTimeout(timeout); resolve(m[1].replace(/\/?$/, '') + '/session'); }
+    };
+    child.stderr.on('data', scan);
+    child.stdout.on('data', scan);
+    child.on('error', (err) => { clearTimeout(timeout); reject(new Error(`Failed to launch Firefox: ${err.message}`)); });
+    child.on('exit', (code) => {
+      clearTimeout(timeout);
+      if (!buf.includes('WebDriver BiDi')) reject(new Error(`Firefox exited with code ${code}. stderr: ${buf}`));
+    });
+  });
+
+  const actualPort = parseInt(new URL(wsUrl.replace('/session', '')).port, 10);
+  const browser = { wsUrl, process: child, port: actualPort, ownedProfileDir: profileDir };
+
+  registerExitHandlers();
+  activeBrowsers.add(browser);
+  child.once('exit', () => activeBrowsers.delete(browser));
+
+  return browser;
+}
+
+/**
+ * Kill a launched Firefox and remove its temp profile dir.
+ * @param {{process: import('node:child_process').ChildProcess, ownedProfileDir?: string}} browser
+ */
+export async function cleanupFirefox(browser) {
+  if (!browser) return;
+  activeBrowsers.delete(browser);
+  const pid = browser.process.pid;
+  try { if (!browser.process.killed) browser.process.kill('SIGKILL'); } catch {}
+  if (pid != null) try { process.kill(-pid, 'SIGKILL'); } catch {}
+  // Wait for death so rmSync doesn't race Firefox's profile file handles.
+  for (let i = 0; pid != null && i < 40; i++) {
+    try { process.kill(pid, 0); } catch { break; }
+    await new Promise((r) => setTimeout(r, 50));
+  }
+  if (browser.ownedProfileDir) {
+    try { rmSync(browser.ownedProfileDir, { recursive: true, force: true }); } catch {}
+  }
+}