barebrowse 0.14.0 → 0.15.0

package/CHANGELOG.md

@@ -1,5 +1,52 @@
 # Changelog
 
+## [0.15.0] - 2026-07-10
+
+### Added
+
+- **Firefox support via WebDriver BiDi (`connect({ engine: 'firefox' })`).** CDP
+  is deprecated in Firefox, so Firefox is driven over the W3C-standard BiDi
+  protocol — a second transport (`src/bidi.js`) over the *same* `ws` dependency,
+  with no geckodriver and no new package. Selectable from the CLI
+  (`barebrowse open <url> --engine firefox`) and MCP (`BAREBROWSE_ENGINE=firefox`).
+  - New modules: `bidi.js` (BiDi JSON-RPC transport), `firefox.js` (launch/find/
+    reap), `ax-snapshot.js` (reconstructs a CDP-vocabulary ARIA tree in-page —
+    BiDi has no `getFullAXTree` — with implicit roles, accessible-name
+    computation, `aria-hidden`/visibility filtering, and shadow-DOM/`<slot>`
+    traversal), `firefox-page.js` (the BiDi-backed page object).
+  - `prune.js`, `aria.js`, and `readable.js` are reused unchanged across engines
+    (readable.js refactored to share `EXTRACT_EXPRESSION` + `finalizeReadable`).
+  - Covers `goto`, `snapshot`, `click`, `type`, `press`, `scroll`, `hover`,
+    `select`, `drag`, `upload`, `goBack`/`goForward`, `reload`, `screenshot`,
+    `pdf`, `tabs`/`switchTab`, `waitFor`, `readable`, `injectCookies`, `close`.
+    The navigation guard and upload sandbox are enforced on the Firefox path for
+    parity with CDP.
+  - Fidelity validated against real CDP snapshots; iframes (incl. nested +
+    multi-tab), shadow DOM, CSP, and SPA timing covered in
+    `test/integration/firefox.test.js` (15 tests).
+
+- **Incognito mode — a clean, unauthenticated session (`incognito: true`).**
+  Skips ALL auth injection: no cookie extraction/injection and no
+  `storageState` loading, so the agent browses logged-out even though the
+  default throwaway profile is unchanged. The gate lives at the page-object
+  level, so it holds even when a caller (MCP `goto`, the daemon) injects
+  unconditionally. Available on `browse()`, `connect()`, both engines, MCP
+  (`browse` tool arg + `BAREBROWSE_INCOGNITO=1`), and CLI (`--incognito`).
+  Cookie injection is scoped to the target host on **both** engines via a
+  shared `scopedCookiesForUrl` (the Firefox path no longer loads the whole
+  cookie jar).
+
+### Known gaps (Firefox engine)
+
+- Consent auto-dismiss, stealth patches, and `hybrid` mode remain Chromium-only.
+- `reload()` cannot honour `ignoreCache` (Firefox BiDi does not support it yet).
+- The CLI daemon's console/network log capture is CDP-only, so those logs are
+  empty for a Firefox session. `saveState`, `waitForNavigation`, and
+  `waitForNetworkIdle` are CDP-only too — on Firefox they throw a clear
+  "not supported on the Firefox/BiDi engine" error, and download/dialog logs
+  read empty. Accessible-name computation is a high-value subset of the full
+  W3C accname spec.
+
 ## [0.14.0] - 2026-06-15
 
 ### Documentation

package/README.md

@@ -132,6 +132,21 @@ const snap = await page.snapshot();
 await page.close(); // closes only the tab barebrowse opened — your browser keeps running
 ```
 
+### 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`):
+
+```js
+const page = await connect({ engine: 'firefox' }); // headless by default
+```
+
+From the CLI: `barebrowse open <url> --engine firefox`. From MCP: set
+`BAREBROWSE_ENGINE=firefox`. Firefox cookies (plaintext) reuse into the same
+engine. Chromium (CDP) remains the default; `hybrid` mode is Chromium-only.
+
 No clone profile, no fresh cookies — the agent sees what you see.
 
 ## What it handles automatically
@@ -223,7 +238,7 @@ URL -> find/launch browser (chromium.js)
 ## Requirements
 
 - Node.js >= 22 (built-in WebSocket, built-in SQLite)
-- Any Chromium-based browser installed (Chrome, Chromium, Brave, Edge, Vivaldi)
+- Any Chromium-based browser installed (Chrome, Chromium, Brave, Edge, Vivaldi) — or Firefox (>= 121) for the `engine: 'firefox'` BiDi path
 - Linux tested (Fedora/KDE). macOS/Windows cookie paths exist but untested.
 
 ## The bare ecosystem

package/barebrowse.context.md

@@ -46,6 +46,7 @@ const snapshot = await browse('https://example.com');
 const snapshot = await browse('https://example.com', {
   mode: 'headless',      // 'headless' | 'headed' | 'hybrid'
   cookies: true,         // inject user's browser cookies
+  incognito: false,      // clean, unauthenticated session: skip ALL auth injection
   browser: 'firefox',    // cookie source: 'firefox' | 'chromium' (auto-detected)
   prune: true,           // apply ARIA pruning (47-95% token reduction)
   pruneMode: 'act',      // 'act' (interactive elements) | 'read' (all content)
@@ -94,10 +95,12 @@ 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`. Chromium-only: `hybrid` mode, consent auto-dismiss, stealth, and the CLI daemon's console/network capture. `reload()` ignores `ignoreCache` on Firefox (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
 - `storageState: 'file.json'` — Load cookies/localStorage from saved state
+- `incognito: true|false` — Default `false`. When `true`, run a clean, unauthenticated session: skips `storageState` loading AND makes `injectCookies()` a no-op, so no auth ever enters the session even though callers (MCP `goto`, daemon) inject unconditionally. The temp profile is already throwaway; this gates the *other* auth source — the user's real browser cookies. Not Chrome's `--incognito` flag. Surfaced everywhere: library, MCP (`browse` tool param + `BAREBROWSE_INCOGNITO=1` env for the session), CLI (`--incognito`), bareagent (via `connect` opts).
 - `downloadPath: '/abs/dir'` — Where downloads land. Default: per-session `mkdtemp` under `/tmp/barebrowse-dl-*` that gets removed on `close()`. Caller-supplied paths are not cleaned up — caller owns the lifecycle.
 - `blockAds: true|false` — CDP-level URL blocking of 128 common ad/tracker patterns (Google ads/analytics, FB/Amazon/MS/Adobe ad+analytics, Segment/Amplitude/Mixpanel/Heap/PostHog, Hotjar/FullStory/LogRocket, Criteo/Taboola/Outbrain, the consumer-pixel cluster, AppNexus/Rubicon/PubMatic supply, marketing automation; v0.10.1 added AppsFlyer/Branch/Adjust, Cloudflare Web Analytics, Matomo Cloud). Default `true` for launched browsers, `false` in attach mode (would affect any tab in the user's running browser). Explicit `true` in attach mode is honored and follows the session across `switchTab()` (regression-tested). Shrinks ARIA snapshots and speeds page loads. On legacy Chromium lacking `Network.setBlockedURLs` a one-time `console.warn` surfaces the fallback.
 - `blockUrls: ['*://foo.com/*', ...]` — Extra glob patterns (CDP `Network.setBlockedURLs` format) to block in addition to the default. Merged with the default unless `blockAds: false`.

package/cli.js

@@ -108,9 +108,11 @@ async function cmdOpen() {
 
   const url = args[1] && !args[1].startsWith('--') ? args[1] : undefined;
   const opts = {
+    engine: parseFlag('--engine'),
     mode: parseFlag('--mode') || 'headless',
     port: parseFlag('--port'),
     cookies: !hasFlag('--no-cookies'),
+    incognito: hasFlag('--incognito') || undefined,
     browser: parseFlag('--browser'),
     timeout: parseFlag('--timeout'),
     pruneMode: parseFlag('--prune-mode') || 'act',
@@ -201,7 +203,7 @@ async function oneShot() {
   const url = args[1];
   const mode = args[2] || 'headless';
   try {
-    const snapshot = await browse(url, { mode });
+    const snapshot = await browse(url, { mode, incognito: hasFlag('--incognito') || undefined });
     process.stdout.write(snapshot + '\n');
     process.exit(0);
   } catch (err) {
@@ -213,9 +215,11 @@ async function oneShot() {
 async function runDaemonInternal() {
   const { runDaemon } = await import('./src/daemon.js');
   const opts = {
+    engine: parseFlag('--engine'),
     mode: parseFlag('--mode') || 'headless',
     port: parseFlag('--port'),
     cookies: !hasFlag('--no-cookies'),
+    incognito: hasFlag('--incognito') || undefined,
     browser: parseFlag('--browser'),
     timeout: parseFlag('--timeout'),
     pruneMode: parseFlag('--prune-mode') || 'act',
@@ -480,9 +484,13 @@ Session:
   barebrowse status                 Check session status
 
   Open flags:
-    --mode=headless|headed|hybrid   Browser mode (default: headless)
+    --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)
     --port=N                        CDP port for headed mode
     --no-cookies                    Skip cookie injection
+    --incognito                     Clean, unauthenticated session (skip all auth injection)
     --browser=firefox|chromium      Cookie source browser
     --timeout=N                     Navigation timeout in ms
     --prune-mode=act|read           Default pruning mode

package/mcp-server.js

@@ -121,7 +121,18 @@ let _pageConnecting = null;
 async function getPage() {
   if (_page) return _page;
   if (_pageConnecting) return _pageConnecting;
-  _pageConnecting = connect({ mode: 'hybrid' });
+  // 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).
+  // 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 };
+  _pageConnecting = connect(connectOpts);
   try {
     _page = await _pageConnecting;
     return _page;
@@ -156,6 +167,7 @@ export const TOOLS = [
         url: { type: 'string', description: 'URL to browse' },
         mode: { type: 'string', enum: ['headless', 'headed', 'hybrid'], description: 'Browser mode (default: headless)' },
         pruneMode: { type: 'string', enum: ['act', 'read'], description: 'Pruning mode. "act" (default) keeps interactive elements and short labels — best for clicking/filling. "read" keeps paragraphs, headings, and long text — best for articles, docs, and content extraction. If the page is content-heavy and act-mode returns mostly empty, retry with "read".' },
+        incognito: { type: 'boolean', description: 'Clean, unauthenticated session: skip cookie injection so the page loads logged-out (default: false).' },
         maxChars: { type: 'number', description: 'Max chars to return inline. Larger snapshots are saved to .barebrowse/ and a file path is returned instead. Default: 30000.' },
       },
       required: ['url'],
@@ -391,7 +403,7 @@ async function handleToolCall(name, args) {
     case 'browse': {
       let timer;
       const text = await Promise.race([
-        browse(args.url, { mode: args.mode, pruneMode: args.pruneMode }),
+        browse(args.url, { mode: args.mode, pruneMode: args.pruneMode, incognito: args.incognito }),
         new Promise((_, rej) => { timer = setTimeout(() => rej(new Error('browse timed out after 60s')), 60000); }),
       ]);
       clearTimeout(timer);

package/package.json

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

package/src/auth.js

@@ -288,25 +288,39 @@ export function cookieDomainMatch(host, cookieDomain) {
 }
 
 /**
- * Extract cookies for a URL and inject them into a CDP session.
- * Convenience function combining extractCookies + injectCookies.
- * @param {object} session - CDP session handle
- * @param {string} url - URL to extract cookies for
- * @param {object} [opts] - Options passed to extractCookies
+ * 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 async function authenticate(session, url, opts = {}) {
+export function scopedCookiesForUrl(url, opts = {}) {
   const fullHost = new URL(url).hostname.toLowerCase();
-  // Coarse SQL pre-filter: strip 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 below is what actually decides
-  // which cookies get injected. Without it, browsing apple.com would inject
-  // cookies for apple.com.evil.org and every *.co.uk site (verified).
   const noWww = fullHost.replace(/^www\./, '');
   const parts = noWww.split('.');
   const coarseDomain = parts.length > 2 ? parts.slice(-2).join('.') : noWww;
   const candidates = extractCookies({ ...opts, domain: coarseDomain });
-  const cookies = candidates.filter((c) => cookieDomainMatch(fullHost, c.domain));
+  return candidates.filter((c) => cookieDomainMatch(fullHost, c.domain));
+}
+
+/**
+ * Extract cookies for a URL and inject them into a CDP session.
+ * 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
+ */
+export async function authenticate(session, url, opts = {}) {
+  const cookies = scopedCookiesForUrl(url, opts);
   if (cookies.length > 0) {
     await injectCookies(session, cookies);
   }

package/src/ax-snapshot.js

@@ -0,0 +1,287 @@
+// @ts-nocheck — AX_FN below is browser-context code (document, getComputedStyle,
+// CSS, real regex literals) serialized via .toString() and run inside Firefox,
+// never in Node. tsc's Node lib (no DOM) can't meaningfully check it, and the
+// readable.js string convention would corrupt its regex backslashes, so the
+// file opts out of type-checking. The Node-side exports are trivial.
+/**
+ * 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';
+
+/**
+ * The in-page reconstruction function, as source text. Evaluated in a browsing
+ * context with a `base` ref offset; returns JSON { tree, count }. Written as a
+ * single self-contained function (no closures over module scope) because it
+ * runs in the page, not in Node.
+ */
+const AX_FN = function reconstructAX(base, REF_ATTR) {
+  let ref = base;
+
+  // Roles whose accessible name comes from descendant text (so we must NOT
+  // also emit child StaticText nodes — CDP folds the text into the name).
+  const NAME_FROM_CONTENT = new Set([
+    'button', 'link', 'heading', 'cell', 'columnheader', 'rowheader',
+    'tab', 'menuitem', 'option', 'treeitem', 'switch', 'checkbox', 'radio',
+  ]);
+
+  // HTML tag → implicit ARIA role (the common, high-value subset).
+  const TAG_ROLE = {
+    A: (el) => (el.hasAttribute('href') ? 'link' : 'generic'),
+    BUTTON: () => 'button',
+    NAV: () => 'navigation', MAIN: () => 'main', ASIDE: () => 'complementary',
+    HEADER: (el) => (isTopLevelLandmark(el) ? 'banner' : 'generic'),
+    FOOTER: (el) => (isTopLevelLandmark(el) ? 'contentinfo' : 'generic'),
+    FORM: () => 'form', SEARCH: () => 'search',
+    SECTION: (el) => (accName(el) ? 'region' : 'generic'),
+    ARTICLE: () => 'article',
+    H1: () => 'heading', H2: () => 'heading', H3: () => 'heading',
+    H4: () => 'heading', H5: () => 'heading', H6: () => 'heading',
+    P: () => 'paragraph',
+    UL: () => 'list', OL: () => 'list', LI: () => 'listitem',
+    DL: () => 'list', DT: () => 'term', DD: () => 'definition',
+    IMG: (el) => (el.getAttribute('alt') === '' ? 'none' : 'image'),
+    FIGURE: () => 'figure', FIGCAPTION: () => 'Figcaption',
+    TABLE: () => 'table', TR: () => 'row', TD: () => 'cell',
+    TH: (el) => (el.getAttribute('scope') === 'row' ? 'rowheader' : 'columnheader'),
+    THEAD: () => 'rowgroup', TBODY: () => 'rowgroup', TFOOT: () => 'rowgroup',
+    SELECT: (el) => (el.multiple ? 'listbox' : 'combobox'),
+    TEXTAREA: () => 'textbox',
+    OPTION: () => 'option',
+    LABEL: () => 'LabelText', SPAN: () => 'generic', DIV: () => 'generic',
+    STRONG: () => 'strong', EM: () => 'emphasis', B: () => 'strong', I: () => 'emphasis',
+    BLOCKQUOTE: () => 'blockquote', CODE: () => 'code', PRE: () => 'generic',
+    HR: () => 'separator',
+    IFRAME: () => 'Iframe', FRAME: () => 'Iframe',
+    INPUT: (el) => {
+      const t = (el.getAttribute('type') || 'text').toLowerCase();
+      return ({
+        button: 'button', submit: 'button', reset: 'button', image: 'button',
+        checkbox: 'checkbox', radio: 'radio', range: 'slider',
+        search: 'searchbox', email: 'textbox', tel: 'textbox', url: 'textbox',
+        text: 'textbox', password: 'textbox', number: 'spinbutton',
+        hidden: 'none',
+      })[t] || 'textbox';
+    },
+  };
+
+  function isTopLevelLandmark(el) {
+    // <header>/<footer> are landmarks only when not scoped inside article/section/main/aside.
+    for (let p = el.parentElement; p; p = p.parentElement) {
+      if (/^(ARTICLE|SECTION|MAIN|ASIDE|NAV)$/.test(p.tagName)) return false;
+    }
+    return true;
+  }
+
+  function roleOf(el) {
+    const explicit = el.getAttribute('role');
+    if (explicit) return explicit.trim().split(/\s+/)[0];
+    const fn = TAG_ROLE[el.tagName];
+    return fn ? fn(el) : 'generic';
+  }
+
+  function isHidden(el) {
+    if (el.getAttribute('aria-hidden') === 'true') return true;
+    if (el.hasAttribute('hidden')) return true;
+    const s = getComputedStyle(el);
+    if (s.display === 'none' || s.visibility === 'hidden' || s.visibility === 'collapse') return true;
+    return false;
+  }
+
+  // Accessible-name computation (compact subset of the accname spec, covering
+  // the cases the POC proved textContent misses).
+  function accName(el, depth) {
+    depth = depth || 0;
+    // 1. aria-labelledby (resolve id refs → their text)
+    const lb = el.getAttribute && el.getAttribute('aria-labelledby');
+    if (lb && depth < 2) {
+      const txt = lb.split(/\s+/).map((id) => {
+        const t = document.getElementById(id);
+        return t ? accName(t, depth + 1) || t.textContent.trim() : '';
+      }).filter(Boolean).join(' ').trim();
+      if (txt) return txt;
+    }
+    // 2. aria-label
+    const al = el.getAttribute && el.getAttribute('aria-label');
+    if (al && al.trim()) return al.trim();
+    const tag = el.tagName;
+    // 3. native naming
+    if (tag === 'IMG' || tag === 'AREA') {
+      const alt = el.getAttribute('alt');
+      if (alt) return alt.trim();
+    }
+    if (tag === 'INPUT' || tag === 'TEXTAREA' || tag === 'SELECT') {
+      // associated <label> (for= or wrapping ancestor)
+      if (el.id) {
+        const lab = document.querySelector('label[for="' + CSS.escape(el.id) + '"]');
+        if (lab) return lab.textContent.trim();
+      }
+      const wrap = el.closest && el.closest('label');
+      if (wrap) return wrap.textContent.trim();
+      const ph = el.getAttribute('placeholder');
+      if (ph && ph.trim()) return ph.trim();
+    }
+    if (tag === 'FIELDSET') {
+      const lg = el.querySelector && el.querySelector('legend');
+      if (lg) return lg.textContent.trim();
+    }
+    if (tag === 'TABLE') {
+      const cap = el.querySelector && el.querySelector('caption');
+      if (cap) return cap.textContent.trim();
+    }
+    // 4. title attribute
+    const title = el.getAttribute && el.getAttribute('title');
+    if (title && title.trim()) return title.trim();
+    return '';
+  }
+
+  function props(el, role) {
+    const p = {};
+    if (role === 'checkbox' || role === 'radio' || role === 'switch') p.checked = !!el.checked;
+    if (el.disabled || el.getAttribute('aria-disabled') === 'true') p.disabled = true;
+    const exp = el.getAttribute('aria-expanded');
+    if (exp !== null) p.expanded = exp === 'true';
+    if (role === 'heading') p.level = Number(el.getAttribute('aria-level')) || Number(el.tagName[1]) || 2;
+    if (el.getAttribute('aria-selected') === 'true') p.selected = true;
+    if (el.required || el.getAttribute('aria-required') === 'true') p.required = true;
+    if ((role === 'textbox' || role === 'searchbox' || role === 'combobox' || role === 'spinbutton') && el.value) {
+      p.value = el.value;
+    }
+    return p;
+  }
+
+  function makeNode(role, name, properties) {
+    return { nodeId: String(++ref), role, name: name || '', properties: properties || {}, children: [], ignored: false };
+  }
+
+  // Walk a DOM element → AX node (or null if hidden/irrelevant). Text runs
+  // become StaticText children unless the parent names from content.
+  function walk(el) {
+    if (isHidden(el)) return null;
+    let role = roleOf(el);
+    if (role === 'none') return collapseChildren(el); // presentational: keep kids
+
+    // Accessible name: explicit sources first, then fall back to descendant
+    // text for roles that name from content (button/link/heading/…), matching
+    // CDP — otherwise those nodes come back nameless.
+    let name = accName(el);
+    if (!name && NAME_FROM_CONTENT.has(role)) {
+      name = el.textContent.replace(/\s+/g, ' ').trim();
+    }
+    const node = makeNode(role, name, props(el, role));
+    el.setAttribute(REF_ATTR, node.nodeId);
+
+    // A collapsed native <select> exposes its current value via props/name;
+    // don't expand its <option> list into the tree (a 200-item country select
+    // would otherwise flood every snapshot). A multi/size listbox keeps them.
+    if (el.tagName === 'SELECT' && !el.multiple) return node;
+
+    if (!NAME_FROM_CONTENT.has(role)) {
+      for (const child of kidsOf(el)) {
+        if (child.nodeType === 3) {
+          const t = child.textContent.replace(/\s+/g, ' ').trim();
+          if (t) node.children.push(makeNode('StaticText', t, {}));
+        } else if (child.nodeType === 1) {
+          const c = walk(child);
+          if (c) Array.isArray(c) ? node.children.push(...c) : node.children.push(c);
+        }
+      }
+    } else {
+      // name-from-content: still recurse into element children for nested
+      // interactives (e.g. a link inside a heading), but drop bare text.
+      for (const child of kidsOf(el)) {
+        if (child.nodeType !== 1) continue;
+        const c = walk(child);
+        if (c) Array.isArray(c) ? node.children.push(...c) : node.children.push(c);
+      }
+    }
+    return node;
+  }
+
+  // Effective children to traverse: shadow-root content when the element hosts
+  // an open shadow tree (that is what actually renders — CDP's AX tree includes
+  // it), assigned light nodes for a <slot>, else plain light-DOM childNodes.
+  function kidsOf(el) {
+    if (el.tagName === 'SLOT') {
+      const assigned = el.assignedNodes ? el.assignedNodes({ flatten: true }) : [];
+      return assigned.length ? assigned : [...el.childNodes];
+    }
+    if (el.shadowRoot) return [...el.shadowRoot.childNodes];
+    return [...el.childNodes];
+  }
+
+  // Presentational element (role=none/presentation): emit its children only.
+  function collapseChildren(el) {
+    const out = [];
+    for (const child of kidsOf(el)) {
+      if (child.nodeType === 3) {
+        const t = child.textContent.replace(/\s+/g, ' ').trim();
+        if (t) out.push(makeNode('StaticText', t, {}));
+      } else if (child.nodeType === 1 && !isHidden(child)) {
+        const c = walk(child);
+        if (c) Array.isArray(c) ? out.push(...c) : out.push(c);
+      }
+    }
+    return out;
+  }
+
+  // Clear stale refs from a prior snapshot so resolution never hits a ghost.
+  for (const old of document.querySelectorAll('[' + REF_ATTR + ']')) old.removeAttribute(REF_ATTR);
+
+  // Wrap body content in an ignored 'none' node, mirroring the html/body
+  // wrappers CDP's getFullAXTree emits. prune.js's region extraction only
+  // inspects RootWebArea's DIRECT children for landmarks, so without this
+  // wrapper a top-level <form>/<nav> (no <main>) would be treated as a
+  // directly-extractable region and dropped in act mode — a divergence from
+  // CDP, where the same landmark is buried under body and flows through.
+  const root = makeNode('RootWebArea', document.title || '', {});
+  const body = makeNode('none', '', {});
+  body.ignored = true;
+  // childNodes (not .children) so bare text directly under <body> is kept as
+  // StaticText, matching walk()/CDP; .children would silently drop it.
+  for (const child of document.body ? document.body.childNodes : []) {
+    if (child.nodeType === 3) {
+      const t = child.textContent.replace(/\s+/g, ' ').trim();
+      if (t) body.children.push(makeNode('StaticText', t, {}));
+    } else if (child.nodeType === 1) {
+      const c = walk(child);
+      if (c) Array.isArray(c) ? body.children.push(...c) : body.children.push(c);
+    }
+  }
+  root.children.push(body);
+  return JSON.stringify({ tree: root, count: ref - base });
+};
+
+/**
+ * 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) {
+  return `(${AX_FN.toString()})(${Number(base)}, ${JSON.stringify(REF_ATTR)})`;
+}