From a90a69bd220e0cdd285c7c12b749feb6ba9da571 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 8 Oct 2026 01:56:54 +0000
Subject: [PATCH] feat(snapshot): read Chrome's native accessibility tree with
 source:"native"

browser_snapshot gains an opt-in `source: "native"`. Instead of the DOM
walker it reads the tree Chrome itself computes (CDP
Accessibility.getFullAXTree): exact roles, accessible names (aria-labelledby,
<label>, native widget semantics), states (checked, expanded, invalid,
heading level) and aria-hidden/inert exclusion. The default stays
source:"dom" and never touches the debugger.

The output has the same shape as the DOM snapshot and its refs work with
every ref tool. Each AX node is bound to its real element in the existing
page-side ref registry by a structural path (resolved through the main world,
walked in the isolated world, tag-verified), so closed shadow roots and
same-origin iframes work, same-named siblings stay distinct, and the
smart-selector fallback and isNew behave as before. No page mutation.

- per-frame AX trees grafted under their Iframe node; ids namespaced
- bridge batched per frame (Chrome rejects mixing JS contexts in one call)
- scoping by selector or ref (resolved in the page, located in a pierced
  DOM.getDocument dump with the same path grammar)
- browser-internal controls with no element (a date input's sub-fields) are
  omitted from the compact tree and counted in unreachableNodes
- if the debugger cannot attach, the DOM tree is returned with
  nativeUnavailable explaining why

Verified in headless Chromium with the real extension, and through the real
MCP client and daemon. Unit and integration tests added.

Co-Authored-By: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0197iXdHWDwMNUNW9NP9nTP5
---
 .cursor/rules/project.mdc                     |   4 +
 README.md                                     |  24 +-
 agent-config/AGENTS.md                        |   2 +-
 .../cursor/rules/browser-controller.mdc       |   2 +-
 .../skills/browser-automation/SKILL.md        |   2 +
 extension/handlers/ax-snapshot.js             | 235 +++++++++++
 extension/handlers/inspection.js              |  15 +-
 extension/lib/ax-native.js                    | 368 ++++++++++++++++++
 extension/lib/state.js                        |   4 +
 llms.txt                                      |   2 +-
 mcp-server/src/tools/meta.ts                  |   2 +-
 mcp-server/src/tools/snapshot.ts              |   6 +-
 tests/ax-native.test.ts                       | 350 +++++++++++++++++
 tests/extension-ax-snapshot.test.ts           | 326 ++++++++++++++++
 tests/helpers/fake-dom.ts                     |  11 +-
 tests/tools/snapshot.test.ts                  |  42 ++
 16 files changed, 1386 insertions(+), 9 deletions(-)
 create mode 100644 extension/handlers/ax-snapshot.js
 create mode 100644 extension/lib/ax-native.js
 create mode 100644 tests/ax-native.test.ts
 create mode 100644 tests/extension-ax-snapshot.test.ts
 create mode 100644 tests/tools/snapshot.test.ts

diff --git a/.cursor/rules/project.mdc b/.cursor/rules/project.mdc
index 923df13..14a093c 100644
--- a/.cursor/rules/project.mdc
+++ b/.cursor/rules/project.mdc
@@ -30,6 +30,10 @@ Agent ─stdio─ thin MCP client (index.ts) ─IPC─► daemon (daemon.ts, own
 - `autoReSnapshot`: on ref failure (virtualized feed), snapshot the tab and embed `freshRefs` in the response so the agent retries in one step. Do NOT auto-retry the click (non-idempotent). `browser_scroll` returns `refsMayBeStale: true` as a hint.
 - `isNew`: each snapshot tracks `role|name` fingerprints per tab; elements appearing since the last snapshot are tagged `isNew: true` so the agent can focus on what changed (big token saver after an overlay/dropdown opens). State lives in `lastSnapshotFingerprints` Map, cleared on tab close.
 
+## Native accessibility tree (`browser_snapshot source:"native"`)
+
+`handlers/ax-snapshot.js` + pure `lib/ax-native.js`. CDP `Accessibility.getFullAXTree` per frame (main + same-process child frames, grafted under their `Iframe` node) → same tree shape as the DOM snapshot. Refs are bound into the SAME page registry (`__bcDom.registry`) by structural path: main world `DOM.resolveNode` + `Runtime.callFunctionOn(pathOfTarget)` → isolated world walks the path (`-1` = enter shadow root, `-2` = enter iframe document, else element-child index), verifies the tag, registers, stores the smart-selector fallback. No DOM mutation. Gotchas: batch `callFunctionOn` PER FRAME (Chrome rejects mixed JS contexts); AX ids repeat across frames (namespaced on merge); user-agent shadow nodes (e.g. a date input's sub-fields) are unreachable: no ref, and omitted from the compact tree (`unreachableNodes`); scoping resolves in the page, then finds the node in a `DOM.getDocument({pierce:true})` dump with the same path grammar. CDP failure → DOM snapshot + `nativeUnavailable`. Default `source:"dom"` never touches the debugger.
+
 ## Concurrency (extension/lib/tab-concurrency.js — pure, unit-tested)
 
 - `TabMutexMap`: same-tab serializes, cross-tab parallelizes.
diff --git a/README.md b/README.md
index d94f647..b1e4913 100644
--- a/README.md
+++ b/README.md
@@ -45,6 +45,7 @@ It already has your browser open right there. It just can't see it.
 - **Batches.** `browser_batch` runs a list of tool calls in one round-trip and stops at the first failure — a click → type → Tab → wait → read sequence is one call instead of five.
 - **Console-style JavaScript.** `browser_evaluate` accepts code as you'd type it in DevTools: top-level `await`, several statements, the last expression's value is returned, DOM nodes come back as readable descriptions — and page CSP doesn't block it.
 - **Refs that stay right.** Snapshot/find refs resolve through one shared page runtime: the registered element first, then the first *visible* selector match (across open and closed shadow roots and same-origin iframes), then a verified fallback that only re-binds when role, tag and name identify one element — an ambiguous match is reported as gone instead of clicked. Hidden duplicates are skipped.
+- **Native Chrome accessibility tree.** `browser_snapshot { source: "native" }` reads the tree Chrome itself computes (CDP `Accessibility.getFullAXTree`): exact roles, accessible names (`aria-labelledby`, `<label>`, native widget semantics), states (`checked`, `expanded`, `invalid`, heading `level`…) and `aria-hidden`/`inert` exclusion — what a screen reader sees. Its refs work with every ref tool, including inside closed shadow roots and same-origin iframes. Opt-in; the default `source: "dom"` needs no debugger.
 - **Shadow DOM everywhere.** `snapshot`, `text`, `find`, `click_text`, `wait` and every locator see web components (open and closed roots, slots), so sites like caniuse read like any other page.
 - **Frozen tabs don't freeze the agent.** Every page call has an 8 s budget; a tab that stops answering is reported as `TAB_WEDGED` in seconds, later calls fail fast after a 1.5 s probe, and `browser_navigate` / `browser_tabs reload` replace the frozen tab in place (the result carries the new `tabId`).
 - **Coordinates when you need them.** Click, hover and wheel-scroll at `x`/`y`, triple-click, ctrl/shift-click, key sequences with `repeat`, and zoomed `region` screenshots that tell you how image pixels map to those coordinates.
@@ -246,6 +247,27 @@ The model is **tab-first**: the agent always says _which_ tab to act on. It neve
    If a ref is stale but the element still exists, it's found automatically via a robust selector + text/role scan (response carries `via: "fallback"`). If the element was scrolled away entirely (virtualized feeds), the response carries **`freshRefs: [...]`** with a fresh snapshot inline — retry with one of those new refs in the same step, no separate snapshot needed.
 4. **Verify** — snapshot or read text again after the action.
 
+### Native accessibility tree
+
+`browser_snapshot` has two sources. Both return the same shape (`ref`, `role`, `name`, `value`, state flags, `href`, `children`) and their refs are interchangeable with every ref tool.
+
+| | `source: "dom"` (default) | `source: "native"` |
+|---|---|---|
+| Built from | A walk of the DOM with ARIA rules re-implemented in the extension | Chrome's accessibility engine, via CDP `Accessibility.getFullAXTree` |
+| Roles / names / states | Approximation (explicit `role`, tag map, `aria-label`, `<label>`, text) | Exactly what assistive technology gets: name computation, native widget roles, `checked` / `expanded` / `invalid` / heading `level`, `aria-hidden` and `inert` honoured |
+| Debugger | Not used (no banner) | Attached (yellow "being debugged" banner, same as trusted input) |
+| Cost | ~tens of ms on typical pages | Same, plus Chrome's tree computation: roughly 2 s per 40k accessibility nodes on a very large page |
+| Custom clickable `<div tabindex>` | Listed | Listed only when it has an accessible name (Chrome calls it `generic`) |
+| If unavailable | — | Falls back to the DOM tree and adds `nativeUnavailable: "<reason>"` |
+
+```
+browser_snapshot { tabId: 15, source: "native" }
+→ { source: "native", tree: [ { ref: "s4k2-3", role: "textbox", name: "Search query", value: "abc", required: true }, … ] }
+browser_snapshot { tabId: 15, source: "native", selector: "form", compact: false }   // scoped, full tree incl. text
+```
+
+How refs are bound: every accessibility node carries a `backendDOMNodeId`; the extension resolves it to its element (closed shadow roots and same-origin iframes included) and registers it in the same page-side ref registry the DOM snapshot uses — no attribute or other mutation of the page. Because of that, `click` / `type` / `hover` / `select` / `scroll` / `drag` / `fill_form` act on the exact element (two buttons both named "Save" stay distinct) and keep the stale-ref fallback and `isNew` behaviour. Limits: at most 1500 refs per snapshot (`refLimited: true` when hit); cross-origin (out-of-process) iframes are reported in `skippedFrames`; controls with no page element to act on — Chrome-internal parts such as the sub-fields and picker button inside a date input, or an element that vanished mid-snapshot — are left out of the compact tree and listed without a `ref` in the full tree, counted in `unreachableNodes`.
+
 ### Safe Observe → Act workflow
 
 For automation that must fail safely when a page changes, use the Browser Controller 2.0 agent API. `browser_observe` captures one compact semantic state in a single page execution and returns session-, tab-, document-, and snapshot-owned refs:
@@ -341,7 +363,7 @@ See [`agent-config/`](agent-config/) for manual installation or to customize the
 | Tool | What it does |
 |------|-------------|
 | `browser_observe` | Compact atomic semantic observation with snapshot/document identity, geometry, state, and dynamic allowed actions |
-| `browser_snapshot` | Accessibility tree with element refs. Compact mode (default) returns only interactive elements; `filter` / `depth` / `ref` (subtree) / `maxChars` (default 20k) keep it small. Traverses open + closed shadow DOM, slots and same-origin iframes. |
+| `browser_snapshot` | Accessibility tree with element refs. Compact mode (default) returns only interactive elements; `filter` / `depth` / `ref` or `selector` (subtree) / `maxChars` (default 20k) keep it small. Traverses open + closed shadow DOM, slots and same-origin iframes. `source: "native"` returns Chrome's own accessibility tree instead of the DOM-derived one ([details](#native-accessibility-tree)). |
 | `browser_screenshot` | Capture a tab as an image over CDP — `maxWidth` / `scale` / `jpeg` to cut tokens, `fullPage` for the whole page, `region` to zoom; reports the pixel → x/y mapping |
 | `browser_text` | Extract text from page or element (incl. shadow DOM); `mode:"article"` = main content only; `offset` paging |
 | `browser_find` | Query elements by natural language ("search input", "Save button") — tokenized, role-aware, shadow DOM + same-origin iframes |
diff --git a/agent-config/AGENTS.md b/agent-config/AGENTS.md
index 2b652fe..e845be9 100644
--- a/agent-config/AGENTS.md
+++ b/agent-config/AGENTS.md
@@ -51,7 +51,7 @@ Debug (tabId required, per-tab, capped 200 entries): `browser_console`, `browser
 ## Pattern
 
 1. `browser_tabs { action: "list" }` → pick a `tabId`
-2. `browser_snapshot { tabId }` to see the page and get refs (refs are tab-scoped)
+2. `browser_snapshot { tabId }` to see the page and get refs (refs are tab-scoped). Add `source: "native"` for Chrome's own accessibility tree (exact accessible names, roles and states; uses the debugger) when the default tree misses or mislabels a control
 3. Use `{ tabId, ref }` with interaction tools
 4. Re-snapshot after navigation/DOM changes to refresh refs
 5. `browser_wait { tabId, selector }` before interacting with dynamic content
diff --git a/agent-config/cursor/rules/browser-controller.mdc b/agent-config/cursor/rules/browser-controller.mdc
index 4b5d0d8..a780535 100644
--- a/agent-config/cursor/rules/browser-controller.mdc
+++ b/agent-config/cursor/rules/browser-controller.mdc
@@ -61,7 +61,7 @@ A `"Tool X disabled"` error means you must activate it via `browser_tools {actio
 - `browser_select` - Select from `<select>`. Params: `tabId`, `ref` OR `selector`, `value` OR `label` OR `index`
 
 ### Reading (all require `tabId`)
-- `browser_snapshot` - Accessibility tree with refs. Params: `tabId`, `selector`, `compact`
+- `browser_snapshot` - Accessibility tree with refs. Params: `tabId`, `selector`, `compact`, `source` (`"dom"` default | `"native"` = Chrome's own computed tree via the debugger)
 - `browser_screenshot` - Capture a tab as image (activates the tab to capture). Params: `tabId`, `format`, `quality`
 - `browser_text` - Get text content. Params: `tabId`, `selector`, `maxLength`
 - `browser_find` - Find elements by natural language. Params: `tabId`, `query`, `limit`
diff --git a/agent-config/skills/browser-automation/SKILL.md b/agent-config/skills/browser-automation/SKILL.md
index fa62563..3feb78b 100644
--- a/agent-config/skills/browser-automation/SKILL.md
+++ b/agent-config/skills/browser-automation/SKILL.md
@@ -34,6 +34,8 @@ The server hides tool definitions until needed (`BROWSER_CONTROLLER_PROGRESSIVE=
 
 For large pages, scope with a selector: `browser_snapshot { tabId, selector: "main" }`.
 
+When the default tree mislabels or misses a control (custom widgets, `aria-labelledby` chains, `aria-hidden` overlays), ask for Chrome's own accessibility tree: `browser_snapshot { tabId, source: "native" }`. Same output shape and the refs work with every tool; it attaches the debugger (yellow banner) and falls back to the default tree, with `nativeUnavailable`, if it can't.
+
 Use `browser_text { tabId }` to extract raw text when you need full content.
 
 ### Reading efficiently (don't re-scan everything)
diff --git a/extension/handlers/ax-snapshot.js b/extension/handlers/ax-snapshot.js
new file mode 100644
index 0000000..d64b4a1
--- /dev/null
+++ b/extension/handlers/ax-snapshot.js
@@ -0,0 +1,235 @@
+/**
+ * browser_snapshot with source:"native": the tree comes from Chrome's own
+ * accessibility engine (CDP Accessibility.getFullAXTree) instead of the DOM
+ * walker. Every ref it returns is bound to the real element in the page's
+ * shared ref registry, so click / type / hover / select / scroll / drag /
+ * fill_form / find ... treat a native ref exactly like a DOM-snapshot ref
+ * (including the smart-selector fallback that survives re-renders).
+ *
+ * How a CDP node becomes a registry element without touching the page:
+ *   1. AX nodes carry `backendDOMNodeId`.
+ *   2. The main world resolves that id to an object (DOM.resolveNode) and
+ *      computes the element's structural path (lib/ax-native.js pathOfTarget).
+ *   3. The isolated world walks the same path — through closed shadow roots
+ *      and same-origin iframes via the shared runtime — verifies the tag, and
+ *      registers the element. No attribute or other DOM mutation anywhere.
+ */
+import { resolveTab, execDom, safeExec, getFallback, assertResponsive, withTimeout } from '../lib/page-exec.js';
+import { withCdp } from '../lib/cdp-session.js';
+import { fallbackByTab, lastNativeFingerprints, persistSessionState, nextRefPrefix } from '../lib/state.js';
+import { PAGE_FALLBACK_INSTALL } from '../utils/smart-selector.js';
+import { mergeFrameTrees, shapeAxTree, applyBindings, backendIdAtPath, pathOfTarget } from '../lib/ax-native.js';
+
+/** AX tree of a very large page can take seconds; a frozen renderer never answers. */
+const AX_TIMEOUT_MS = 12_000;
+/** Same-origin frames merged into one tree (each costs two CDP calls). */
+const MAX_FRAMES = 20;
+/** resolveNode calls in flight / objects passed to one callFunctionOn (per frame). */
+const BRIDGE_CHUNK = 150;
+const OBJECT_GROUP = 'bc-ax-native';
+
+/** Main-world function: paths of every element passed in, in order. */
+const PATHS_FUNCTION = `function (...els) { const f = ${pathOfTarget.toString()}; return els.map((el) => f(null, null, null, el)); }`;
+
+/** Child frames below the top frame, depth-first, capped. */
+function childFrames(frameTree) {
+  const out = [];
+  const visit = (t) => {
+    for (const child of t.childFrames || []) {
+      if (out.length >= MAX_FRAMES) return;
+      out.push(child.frame);
+      visit(child);
+    }
+  };
+  visit(frameTree);
+  return out;
+}
+
+/** Main frame + every same-process child frame, merged into one node list. */
+async function fetchForest(send) {
+  const { frameTree } = await send('Page.getFrameTree');
+  const [main, ...rest] = await Promise.all([
+    send('Accessibility.getFullAXTree'),
+    ...childFrames(frameTree).map(async (frame) => {
+      try {
+        const [ax, owner] = await Promise.all([
+          send('Accessibility.getFullAXTree', { frameId: frame.id }),
+          send('DOM.getFrameOwner', { frameId: frame.id }),
+        ]);
+        return { nodes: ax.nodes || [], ownerBackendNodeId: owner.backendNodeId, url: frame.url };
+      } catch {
+        // Out-of-process (cross-origin) frame: its tree lives in another target.
+        return { skipped: frame.url };
+      }
+    }),
+  ]);
+  const frames = rest.filter((f) => f.nodes);
+  return {
+    nodes: mergeFrameTrees(main.nodes || [], frames),
+    skippedFrames: rest.filter((f) => f.skipped).map((f) => f.skipped),
+  };
+}
+
+/**
+ * backendNodeId -> { path, tag } for the entries that resolve to a live,
+ * reachable element. Batched per frame: objects of different frames belong to
+ * different JS contexts and cannot be passed to one callFunctionOn.
+ */
+async function resolvePaths(send, entries) {
+  const out = new Map();
+  const byFrame = new Map();
+  for (const e of entries) {
+    if (!byFrame.has(e.frame)) byFrame.set(e.frame, []);
+    byFrame.get(e.frame).push(e.backendNodeId);
+  }
+  try {
+    for (const ids of byFrame.values()) {
+      for (let i = 0; i < ids.length; i += BRIDGE_CHUNK) {
+        const chunk = ids.slice(i, i + BRIDGE_CHUNK);
+        const objects = await Promise.all(chunk.map((backendNodeId) => send('DOM.resolveNode', { backendNodeId, objectGroup: OBJECT_GROUP })
+          .then((r) => r?.object?.objectId || null, () => null)));
+        const live = chunk.map((id, k) => ({ id, objectId: objects[k] })).filter((x) => x.objectId);
+        if (!live.length) continue;
+        const res = await send('Runtime.callFunctionOn', {
+          objectId: live[0].objectId,
+          functionDeclaration: PATHS_FUNCTION,
+          arguments: live.map((x) => ({ objectId: x.objectId })),
+          returnByValue: true,
+          silent: true,
+        });
+        const values = res?.result?.value || [];
+        live.forEach((x, k) => { if (values[k] && !values[k].error) out.set(x.id, values[k]); });
+      }
+    }
+  } finally {
+    await send('Runtime.releaseObjectGroup', { objectGroup: OBJECT_GROUP }).catch(() => {});
+  }
+  return out;
+}
+
+/**
+ * Page side (isolated world): walk each path to its element, verify the tag,
+ * register it under its ref and record its smart-selector fallback.
+ * Self-contained: serialized into the page by chrome.scripting.
+ */
+function pageBindNative(entries) {
+  const D = globalThis.__bcDom;
+  if (!D) return { __needDom: true };
+  const gen = (globalThis.__browserControllerFallbackRuntime || {}).generateFallback || null;
+  const origin = location.origin;
+  const bound = {};
+  const fallbacks = {};
+  for (const entry of entries) {
+    let cur = document;
+    for (const step of entry.path) {
+      if (!cur) break;
+      if (step === -1) cur = D.shadowOf(cur);
+      else if (step === -2) cur = D.frameDoc(cur);
+      else cur = cur.children ? cur.children[step] || null : null;
+    }
+    if (!cur || cur.nodeType !== 1 || cur.tagName !== entry.tag) continue; // moved/removed since the AX read
+    D.registry.set(entry.ref, cur);
+    bound[entry.ref] = {};
+    if (cur.tagName === 'A' && typeof cur.href === 'string' && cur.href) {
+      bound[entry.ref].href = cur.href.startsWith(origin + '/') ? cur.href.slice(origin.length) : cur.href;
+    }
+    try { if (gen) fallbacks[entry.ref] = gen(cur); } catch { /* descriptor is best-effort */ }
+  }
+  return { success: true, bound, fallbacks };
+}
+
+/**
+ * @returns the snapshot result, or `{ __fallback: reason }` when Chrome's
+ * accessibility tree is unavailable here (debugger can't attach, timeout…) so
+ * the caller can serve the DOM snapshot instead.
+ */
+export async function handleNativeSnapshot(params, { compact, maxChars }) {
+  const { tabId, selector, ref: rootRef, depth } = params;
+  const tab = await resolveTab(tabId);
+  if (/^(chrome|chrome-extension|devtools|edge|about):/i.test(tab.url || '')) {
+    throw new Error(`Cannot access protected page (${tab.url}). Tab ${tabId} is a browser-internal page.`);
+  }
+  await assertResponsive(tabId);
+
+  // Scope (selector / ref): resolve in the page, then locate the same node by path.
+  let scope = null;
+  if (rootRef || selector) {
+    const hit = await execDom(tabId, pathOfTarget, [rootRef ?? null, selector ?? null, getFallback(tabId, rootRef), null]);
+    if (hit?.error === 'INVALID_SELECTOR') return { success: false, error: `Invalid CSS selector: ${selector}` };
+    if (!hit || hit.error) {
+      return { success: false, error: rootRef ? `ref ${rootRef} is gone — take a new snapshot` : 'Root element not found' };
+    }
+    scope = hit;
+  }
+
+  const refPrefix = nextRefPrefix('s');
+  const prev = lastNativeFingerprints.get(tabId);
+  let stage;
+  try {
+    stage = await withCdp(tabId, async (send) => {
+      const forest = await withTimeout(fetchForest(send), AX_TIMEOUT_MS, () => new Error('accessibility tree timed out'));
+      let rootBackendNodeId;
+      if (scope) {
+        const { root } = await send('DOM.getDocument', { depth: -1, pierce: true });
+        rootBackendNodeId = backendIdAtPath(root, scope.path, scope.tag);
+        if (rootBackendNodeId == null) return { scopeLost: true };
+      }
+      const shaped = shapeAxTree(forest.nodes, {
+        compact, depth, maxChars, rootBackendNodeId, refPrefix, prevFingerprints: prev ? new Set(prev) : null,
+      });
+      if (!shaped.rootFound) return { noAxNode: true };
+      const paths = await resolvePaths(send, shaped.entries);
+      return { shaped, paths, skippedFrames: forest.skippedFrames };
+    });
+  } catch (err) {
+    if (err && err.code === 'TAB_WEDGED') throw err;
+    return { __fallback: `Chrome accessibility tree unavailable (${String(err?.message || err)})` };
+  }
+
+  if (stage.scopeLost) {
+    return { success: false, error: rootRef ? `ref ${rootRef} is gone — take a new snapshot` : 'Root element not found' };
+  }
+  if (stage.noAxNode) {
+    return { success: false, error: 'Root element is not in the accessibility tree (hidden or aria-hidden) — scope to a visible element.' };
+  }
+  const { shaped, paths, skippedFrames } = stage;
+
+  // Bind refs to elements in the page registry (after the fallback generator is installed).
+  const bindEntries = shaped.entries
+    .filter((e) => paths.has(e.backendNodeId))
+    .map((e) => ({ ref: e.ref, path: paths.get(e.backendNodeId).path, tag: paths.get(e.backendNodeId).tag }));
+  let bound = {};
+  if (bindEntries.length) {
+    await safeExec(tabId, PAGE_FALLBACK_INSTALL, []);
+    const bind = await execDom(tabId, pageBindNative, [bindEntries]);
+    bound = bind?.bound || {};
+    if (bind?.fallbacks) {
+      // Merged, not replaced: a scoped snapshot must not invalidate refs from the full one.
+      const map = fallbackByTab.get(tabId) || new Map();
+      for (const [ref, fb] of Object.entries(bind.fallbacks)) map.set(ref, fb);
+      while (map.size > 3000) map.delete(map.keys().next().value);
+      fallbackByTab.set(tabId, map);
+      persistSessionState();
+    }
+  }
+  const tree = applyBindings(shaped.tree, bound, { dropUnbound: compact });
+  lastNativeFingerprints.set(tabId, shaped.fingerprints);
+
+  const unbound = shaped.entries.length - Object.keys(bound).length;
+  const current = await chrome.tabs.get(tabId).catch(() => tab);
+  return {
+    success: true,
+    source: 'native',
+    url: current.url,
+    title: current.title || '',
+    compact,
+    tree,
+    ...(shaped.truncated ? {
+      truncated: true,
+      hint: 'Output capped (maxChars/depth). Scope it with selector or ref (a subtree), or raise maxChars.',
+    } : {}),
+    ...(shaped.refLimited ? { refLimited: true } : {}),
+    ...(unbound > 0 ? { unreachableNodes: unbound } : {}),
+    ...(skippedFrames.length ? { skippedFrames } : {}),
+  };
+}
diff --git a/extension/handlers/inspection.js b/extension/handlers/inspection.js
index f189c06..c6e1efd 100644
--- a/extension/handlers/inspection.js
+++ b/extension/handlers/inspection.js
@@ -8,6 +8,7 @@ import { fallbackByTab, lastSnapshotFingerprints, MAX_RESULT_CHARS, persistSessi
 import { PAGE_FALLBACK_INSTALL } from '../utils/smart-selector.js';
 import { withCdp } from '../lib/cdp-session.js';
 import { cdpEvaluate } from '../lib/cdp-evaluate.js';
+import { handleNativeSnapshot } from './ax-snapshot.js';
 
 /** Default output cap for snapshots (chars of serialized tree). */
 export const SNAPSHOT_MAX_CHARS = 20_000;
@@ -156,7 +157,8 @@ export async function handleScroll(params) {
 
 /**
  * Snapshot (task 2.4): builds an accessibility tree INCLUDING shadow DOM and
- * same-origin iframes. Refs are returned to the agent, while element recovery
+ * same-origin iframes (source:"dom", the default; source:"native" reads Chrome's
+ * real AX tree instead — handlers/ax-snapshot.js). Refs are returned to the agent, while element recovery
  * state is stored in the extension fallback registry instead of mutating page
  * DOM with permanent data-mcp-ref attributes.
  */
@@ -166,6 +168,16 @@ export async function handleSnapshot(params) {
   const compact = params.filter === 'all' ? false : params.filter === 'interactive' ? true : params.compact !== false;
   await resolveTab(tabId);
 
+  // source:"native": Chrome's own accessibility tree (CDP). When the debugger
+  // can't attach (or the AX read fails) the DOM snapshot below answers instead
+  // and says why in `nativeUnavailable`.
+  let nativeUnavailable;
+  if (params.source === 'native') {
+    const native = await handleNativeSnapshot(params, { compact, maxChars });
+    if (!native.__fallback) return native;
+    nativeUnavailable = native.__fallback;
+  }
+
   // Install the fallback page runtime first (v2 install-once pattern): the
   // generator's source is injected natively as a chrome.scripting `func:`.
   // Rebuilding it from a source string via eval() is impossible — MV3's
@@ -360,6 +372,7 @@ export async function handleSnapshot(params) {
       lastSnapshotFingerprints.set(tabId, res.__fingerprints);
       delete res.__fingerprints;
     }
+    if (nativeUnavailable && res && res.success) res.nativeUnavailable = nativeUnavailable;
     return res;
   });
 }
diff --git a/extension/lib/ax-native.js b/extension/lib/ax-native.js
new file mode 100644
index 0000000..d0f9c03
--- /dev/null
+++ b/extension/lib/ax-native.js
@@ -0,0 +1,368 @@
+/**
+ * Native Chrome accessibility tree (CDP `Accessibility.getFullAXTree`) →
+ * the same compact/full tree shape `browser_snapshot` returns from the DOM
+ * walker, so agents and ref tools work unchanged.
+ *
+ * Everything here is pure (no chrome.*, no page access) and unit tested. The
+ * CDP and page plumbing lives in handlers/ax-snapshot.js.
+ *
+ * Why native: Chrome computes roles, accessible names and states itself —
+ * `aria-labelledby` chains, `<label>`/`<fieldset>` rules, native widget roles,
+ * `hidden`/`inert` exclusion, `aria-hidden` subtrees — exactly what assistive
+ * technology sees. The DOM walker approximates that; this is the source.
+ */
+
+/**
+ * Roles a user can act on. Standard ARIA names plus the Chrome-specific ones
+ * observed from Accessibility.getFullAXTree for native widgets: `ColorWell`
+ * (<input type=color>), `Date` / `DateTime` / `InputTime` (date and time
+ * inputs), `DisclosureTriangle` (<summary>).
+ */
+export const AX_INTERACTIVE_ROLES = new Set([
+  'button', 'link', 'textbox', 'searchbox', 'combobox', 'listbox', 'checkbox', 'radio',
+  'switch', 'tab', 'menuitem', 'menuitemcheckbox', 'menuitemradio', 'option', 'slider',
+  'spinbutton', 'treeitem', 'ColorWell', 'Date', 'DateTime', 'InputTime', 'DisclosureTriangle',
+]);
+
+/** Landmarks/regions kept in compact mode (same set the DOM snapshot keeps). */
+export const AX_LANDMARK_ROLES = new Set([
+  'navigation', 'main', 'banner', 'contentinfo', 'form', 'search', 'complementary', 'region', 'dialog', 'alertdialog',
+]);
+
+/** Roles that only wrap other nodes: promoted away, never emitted themselves. */
+const AX_TRANSPARENT_ROLES = new Set([
+  'none', 'presentation', 'generic', 'RootWebArea', 'WebArea', 'Iframe', 'IframePresentational',
+  'InlineTextBox', 'LineBreak', 'LabelText', 'ListMarker',
+]);
+
+/** Hard ceiling on nodes that get a ref (one CDP round-trip each). */
+export const MAX_NATIVE_REFS = 1500;
+const NAME_MAX = 80;
+
+const val = (v) => (v && typeof v === 'object' && 'value' in v ? v.value : v);
+const clean = (v, max = NAME_MAX) => String(v == null ? '' : v).replace(/\s+/g, ' ').trim().slice(0, max);
+
+/** AX property list → plain object (`{ focusable: true, checked: 'mixed', level: 2 }`). */
+export function axProps(node) {
+  const out = {};
+  for (const p of node.properties || []) out[p.name] = val(p.value);
+  return out;
+}
+
+/** AX nodes use string ids that can repeat across frames: namespace each frame's ids. */
+function namespaced(nodes, ns) {
+  if (!ns) return nodes;
+  return nodes.map((n) => ({
+    ...n,
+    nodeId: `${ns}:${n.nodeId}`,
+    ...(n.parentId != null ? { parentId: `${ns}:${n.parentId}` } : {}),
+    ...(n.childIds ? { childIds: n.childIds.map((c) => `${ns}:${c}`) } : {}),
+  }));
+}
+
+/**
+ * Join the per-frame AX forests. `getFullAXTree` stops at an <iframe>: the
+ * frame appears as a childless `Iframe` node, and its content has to be fetched
+ * with its own frameId. Graft each child frame's root under its owner node.
+ *
+ * @param {object[]} mainNodes nodes of the main frame
+ * @param {Array<{nodes: object[], ownerBackendNodeId: number}>} frames child frames
+ * @returns {object[]} one flat node list (ids unique)
+ */
+export function mergeFrameTrees(mainNodes, frames = []) {
+  // Copies (the owner's childIds are rewritten) tagged with the frame they came
+  // from: elements of different frames live in different JS contexts, so the
+  // CDP bridge must batch per frame.
+  const all = mainNodes.map((n) => ({ ...n, frameIndex: 0 }));
+  const byBackend = new Map();
+  for (const n of all) if (n.backendDOMNodeId != null) byBackend.set(n.backendDOMNodeId, n);
+
+  frames.forEach((frame, i) => {
+    const nodes = namespaced(frame.nodes || [], `f${i + 1}`).map((n) => ({ ...n, frameIndex: i + 1 }));
+    if (!nodes.length) return;
+    const owner = byBackend.get(frame.ownerBackendNodeId);
+    if (!owner) return; // owner hidden/removed: its content is not reachable either
+    const root = nodes.find((n) => n.parentId == null) || nodes[0];
+    owner.childIds = [...(owner.childIds || []), root.nodeId];
+    root.parentId = owner.nodeId;
+    for (const n of nodes) {
+      all.push(n);
+      if (n.backendDOMNodeId != null) byBackend.set(n.backendDOMNodeId, n);
+    }
+  });
+  return all;
+}
+
+/**
+ * Accessible-name rules for a text leaf: Chrome gives every link/button a
+ * StaticText child that repeats the parent's name. Dropping the repeats keeps
+ * the tree from doubling in size.
+ */
+function repeatsAncestorName(text, ancestorName) {
+  if (!text) return true;
+  return !!ancestorName && ancestorName.includes(text);
+}
+
+function stateOf(props, role) {
+  const s = {};
+  if (props.disabled === true) s.disabled = true;
+  if (props.focused === true) s.focused = true;
+  const checked = props.checked;
+  if (checked === 'mixed') s.checked = 'mixed';
+  else if (checked === 'true' || checked === true) s.checked = true;
+  else if (checked === 'false' || checked === false) s.checked = false;
+  const pressed = props.pressed;
+  if (pressed === 'mixed') s.pressed = 'mixed';
+  else if (pressed === 'true' || pressed === true) s.pressed = true;
+  if (props.expanded === true) s.expanded = true;
+  else if (props.expanded === false) s.expanded = false;
+  if (props.selected === true) s.selected = true;
+  if (props.required === true) s.required = true;
+  if (props.readonly === true) s.readOnly = true;
+  // CDP spells it as a token: "true" | "false" | "grammar" | "spelling".
+  if (props.invalid && props.invalid !== 'false') s.invalid = props.invalid === true || props.invalid === 'true' ? true : props.invalid;
+  if (props.modal === true) s.modal = true;
+  if (Number.isFinite(props.level) && role === 'heading') s.level = props.level;
+  return s;
+}
+
+/** Plain-text value of a control (checkbox state lives in `checked`, not here). */
+function valueOf(node, role) {
+  if (role === 'checkbox' || role === 'radio' || role === 'switch') return undefined;
+  const v = val(node.value);
+  if (v == null || v === '') return undefined;
+  return clean(v, 200);
+}
+
+/**
+ * Shape the AX forest into the snapshot tree.
+ *
+ * @param {object[]} nodes flat CDP nodes (after mergeFrameTrees)
+ * @param {object} [opts]
+ * @param {boolean} [opts.compact=true] interactive + landmarks + headings only
+ * @param {number} [opts.depth] max nesting of emitted nodes (0 = top level)
+ * @param {number} [opts.maxChars] output budget in serialized characters
+ * @param {number} [opts.rootBackendNodeId] scope to this DOM node's subtree
+ * @param {Set<string>|null} [opts.prevFingerprints] role|name keys of the previous native snapshot
+ * @returns {{tree: object|object[]|null, entries: Array<{ref: string, backendNodeId: number, frame: number}>, fingerprints: string[], truncated: boolean, refLimited: boolean, rootFound: boolean}}
+ *   `entries` are the nodes that want a ref; the caller binds them to page
+ *   elements and drops the refs it could not bind (stripRefs).
+ */
+export function shapeAxTree(nodes, opts = {}) {
+  const {
+    compact = true,
+    depth,
+    maxChars,
+    rootBackendNodeId,
+    prevFingerprints = null,
+    refPrefix = 'n',
+  } = opts;
+  const maxDepth = Number.isInteger(depth) && depth >= 0 ? depth : Infinity;
+  let budget = Number.isInteger(maxChars) && maxChars > 0 ? maxChars : Infinity;
+  let truncated = false;
+  let refLimited = false;
+
+  const byId = new Map();
+  for (const n of nodes) byId.set(n.nodeId, n);
+  const childrenOf = (n) => (n.childIds || []).map((id) => byId.get(id)).filter(Boolean);
+
+  const entries = [];
+  const fingerprints = [];
+  let refSeq = 0;
+
+  let rootNodes;
+  let rootFound = true;
+  if (rootBackendNodeId != null) {
+    const hit = nodes.find((n) => n.backendDOMNodeId === rootBackendNodeId);
+    rootNodes = hit ? [hit] : [];
+    rootFound = !!hit;
+  } else {
+    // Roots: nodes whose parent is absent (the main frame's RootWebArea).
+    rootNodes = nodes.filter((n) => n.parentId == null || !byId.has(n.parentId));
+  }
+
+  /**
+   * What `node` contributes, or null when it only passes its children through.
+   * compact: interactive + landmarks + headings (the DOM snapshot's set).
+   * full: everything with meaning — structural wrappers (generic, RootWebArea,
+   * Iframe…) are still promoted away, text repeating its parent's name is dropped.
+   */
+  function ownRecord(role, name, props, ancestorName) {
+    if (role === 'StaticText') {
+      if (compact) return null;
+      return repeatsAncestorName(name, ancestorName) ? null : { role: 'text' };
+    }
+    // A clickable <div tabindex=0> is just "generic" to Chrome: keep it when it has a name.
+    const interactive = AX_INTERACTIVE_ROLES.has(role) || (role === 'generic' && props.focusable === true && !!name);
+    if (compact) {
+      return interactive || AX_LANDMARK_ROLES.has(role) || role === 'heading' ? { role } : null;
+    }
+    if (interactive) return { role };
+    return AX_TRANSPARENT_ROLES.has(role) ? null : { role };
+  }
+
+  function walk(node, d, ancestorName) {
+    if (budget <= 0) { truncated = true; return null; }
+    const role = val(node.role) || '';
+    if (role === 'InlineTextBox' || role === 'ListMarker') return null;
+    const name = clean(val(node.name));
+    const props = axProps(node);
+
+    // Ignored nodes and wrappers contribute only their children.
+    const passThrough = node.ignored === true;
+    const own = passThrough ? null : ownRecord(role, name, props, ancestorName);
+
+    let rec = null;
+    if (own) {
+      if (d > maxDepth) { truncated = true; return null; }
+      rec = { role: own.role };
+      if (name) rec.name = name;
+      if (own.role !== 'text') {
+        const value = valueOf(node, role);
+        if (value !== undefined) rec.value = value;
+        Object.assign(rec, stateOf(props, role));
+        const desc = clean(val(node.description), NAME_MAX);
+        if (desc && !compact) rec.description = desc;
+        if (node.backendDOMNodeId != null) {
+          if (entries.length >= MAX_NATIVE_REFS) {
+            refLimited = true;
+          } else {
+            rec.ref = `${refPrefix}${refSeq++}`;
+            entries.push({ ref: rec.ref, backendNodeId: node.backendDOMNodeId, frame: node.frameIndex || 0 });
+          }
+        }
+        fingerprints.push(`${own.role}|${name}`);
+        if (prevFingerprints && !prevFingerprints.has(`${own.role}|${name}`)) rec.isNew = true;
+      }
+      budget -= JSON.stringify(rec).length + 16;
+    }
+
+    const kids = [];
+    if (!(own && d >= maxDepth)) {
+      const nextName = own && own.role !== 'text' && name ? name : ancestorName;
+      for (const child of childrenOf(node)) {
+        const c = walk(child, own ? d + 1 : d, nextName);
+        if (c) Array.isArray(c) ? kids.push(...c) : kids.push(c);
+      }
+    } else if (childrenOf(node).length) {
+      truncated = true;
+    }
+
+    if (!rec) return kids.length === 0 ? null : kids.length === 1 ? kids[0] : kids;
+    if (kids.length) rec.children = kids;
+    return rec;
+  }
+
+  const parts = [];
+  for (const root of rootNodes) {
+    const r = walk(root, 0, '');
+    if (r) Array.isArray(r) ? parts.push(...r) : parts.push(r);
+  }
+  const tree = parts.length === 0 ? null : parts.length === 1 ? parts[0] : parts;
+  return { tree, entries, fingerprints, truncated, refLimited, rootFound };
+}
+
+/**
+ * Settle the tree after the page bound what it could: attach hrefs, remove refs
+ * that did not bind. With `dropUnbound` (compact mode) an interactive node that
+ * did not bind is omitted and its children promoted: those are Chrome-internal
+ * controls with no element to act on (the sub-fields and picker button inside a
+ * date input live in a user-agent shadow root) or elements that vanished
+ * mid-snapshot. Returns the new root (null when nothing is left).
+ */
+export function applyBindings(tree, bound, { dropUnbound = false } = {}) {
+  const settle = (list) => {
+    const out = [];
+    for (const node of list) {
+      if (node.children) {
+        node.children = settle(node.children);
+        if (!node.children.length) delete node.children;
+      }
+      if (node.ref && !bound[node.ref]) {
+        if (dropUnbound && (AX_INTERACTIVE_ROLES.has(node.role) || node.role === 'generic')) {
+          out.push(...(node.children || []));
+          continue;
+        }
+        delete node.ref;
+      } else if (node.ref && bound[node.ref].href) {
+        node.href = bound[node.ref].href;
+      }
+      out.push(node);
+    }
+    return out;
+  };
+  const settled = settle(Array.isArray(tree) ? tree : tree ? [tree] : []);
+  return settled.length === 0 ? null : settled.length === 1 ? settled[0] : settled;
+}
+
+/**
+ * Locate a DOM node in a `DOM.getDocument({pierce:true})` dump by the same
+ * structural path the page-side `pathOf` produced, and return its backendNodeId.
+ *
+ * Path grammar (identical in both worlds): a number is an index among the
+ * parent's ELEMENT children; -1 enters the author shadow root of the current
+ * element; -2 enters the content document of the current <iframe>.
+ */
+export function backendIdAtPath(root, path, tag) {
+  let cur = root;
+  for (const step of path) {
+    if (!cur) return null;
+    if (step === -1) {
+      cur = (cur.shadowRoots || []).find((r) => r.shadowRootType !== 'user-agent') || null;
+    } else if (step === -2) {
+      cur = cur.contentDocument || null;
+    } else {
+      cur = (cur.children || []).filter((c) => c.nodeType === 1)[step] || null;
+    }
+  }
+  if (!cur || cur.nodeType !== 1) return null;
+  if (tag && String(cur.nodeName).toUpperCase() !== String(tag).toUpperCase()) return null;
+  return cur.backendNodeId ?? null;
+}
+
+/**
+ * Structural path of an element from its top document. ONE definition, run in
+ * both worlds (serialized with Function#toString, so it must stay
+ * self-contained and close over nothing):
+ *   - main world via CDP `Runtime.callFunctionOn`, with `element` given;
+ *   - the extension's isolated world via chrome.scripting, resolving
+ *     `ref` / `selector` / `fb` through the shared page runtime (scoped snapshots).
+ * Returns `{ path, tag }`, or `{ error }` (INVALID_SELECTOR, REF_GONE, DETACHED).
+ */
+export function pathOfTarget(ref, selector, fb, element) {
+  let el = element || null;
+  if (!el) {
+    const D = globalThis.__bcDom;
+    if (!D) return { __needDom: true };
+    const hit = D.resolve(ref, selector, fb);
+    if (hit.error) return { error: hit.error };
+    el = hit.el;
+  }
+  if (!el || el.nodeType !== 1) return { error: 'REF_GONE' };
+  const path = [];
+  let node = el;
+  for (let guard = 0; guard < 400; guard++) {
+    if (!node) return { error: 'DETACHED' };
+    if (node.nodeType === 9) {
+      let frame;
+      try { frame = node.defaultView && node.defaultView.frameElement; } catch { frame = null; }
+      if (!frame) return { path, tag: el.tagName };
+      path.unshift(-2);
+      node = frame;
+      continue;
+    }
+    const parent = node.parentNode;
+    if (!parent) return { error: 'DETACHED' };
+    const index = Array.prototype.indexOf.call(parent.children, node);
+    if (index < 0) return { error: 'DETACHED' };
+    if (parent.nodeType === 11) {
+      if (!parent.host) return { error: 'DETACHED' };
+      path.unshift(-1, index);
+      node = parent.host;
+    } else {
+      path.unshift(index);
+      node = parent;
+    }
+  }
+  return { error: 'DETACHED' };
+}
diff --git a/extension/lib/state.js b/extension/lib/state.js
index 9d7c20b..5cc0edf 100644
--- a/extension/lib/state.js
+++ b/extension/lib/state.js
@@ -52,6 +52,8 @@ export const replacedTabs = new Map();
  * @type {Map<number, string[]>}
  */
 export const lastSnapshotFingerprints = new Map();
+/** Same, for `browser_snapshot source:"native"` (its roles/names differ from the DOM walker's). */
+export const lastNativeFingerprints = new Map();
 /** Bounded Observation V2 ownership metadata; page-side refs never live here. */
 export const observationSnapshots = new SnapshotRegistry();
 
@@ -137,6 +139,7 @@ export function dropDocumentState(tabId) {
   wedgedTabs.delete(tabId);
   fallbackByTab.delete(tabId);
   lastSnapshotFingerprints.delete(tabId);
+  lastNativeFingerprints.delete(tabId);
   observationSnapshots.invalidateTab(tabId);
 }
 
@@ -147,6 +150,7 @@ export function dropTabState(tabId) {
   networkByTab.delete(tabId);
   fallbackByTab.delete(tabId);
   lastSnapshotFingerprints.delete(tabId);
+  lastNativeFingerprints.delete(tabId);
   observationSnapshots.dropTab(tabId);
   tabLocks.release(tabId);
 }
diff --git a/llms.txt b/llms.txt
index 3d7b667..0c06e3e 100644
--- a/llms.txt
+++ b/llms.txt
@@ -14,7 +14,7 @@ Unlike Playwright MCP or Chrome DevTools MCP, which launch or attach to a separa
 
 Navigation: browser_navigate, browser_tabs
 Interaction: browser_click, browser_click_text, browser_type, browser_press_key, browser_scroll, browser_hover, browser_select, browser_drag, browser_fill_form, browser_upload_file, browser_wait
-Reading: browser_snapshot (compact mode default - interactive elements only), browser_screenshot, browser_text, browser_find
+Reading: browser_snapshot (compact mode default - interactive elements only; source:"native" returns Chrome's own accessibility tree), browser_screenshot, browser_text, browser_find
 JavaScript: browser_evaluate (execute arbitrary JS in page context, supports async/await), browser_run_action (CDP-based, bypasses CSP)
 Dialogs: browser_handle_dialog (handle alert/confirm/prompt)
 Debugging: browser_console, browser_network
diff --git a/mcp-server/src/tools/meta.ts b/mcp-server/src/tools/meta.ts
index 612ebb5..443031b 100644
--- a/mcp-server/src/tools/meta.ts
+++ b/mcp-server/src/tools/meta.ts
@@ -73,7 +73,7 @@ const TOOL_GUIDANCE: Record<string, string> = {
   browser_navigate:
     "Use to go to a URL. Handles hash-only routes correctly (resolves without waiting for a complete event). Returns an optional inline snapshot so you can act immediately.",
   browser_snapshot:
-    "Use to understand page structure and get element refs (e1, e2…) for subsequent click/type calls. Returns the accessibility tree (semantic), not raw DOM.",
+    "Use to understand page structure and get element refs (e1, e2…) for subsequent click/type calls. Returns the accessibility tree (semantic), not raw DOM. source:\"native\" = Chrome's own computed tree (exact names/roles/states; uses the debugger).",
   browser_text:
     'Use to read visible text on the page (incl. shadow DOM). Cheapest read tool. mode:"article" = main content only; page long text with offset/nextOffset. Returns {text, title, url}.',
   browser_find:
diff --git a/mcp-server/src/tools/snapshot.ts b/mcp-server/src/tools/snapshot.ts
index 3c0ef49..340562f 100644
--- a/mcp-server/src/tools/snapshot.ts
+++ b/mcp-server/src/tools/snapshot.ts
@@ -4,8 +4,9 @@ import { requireTabId, forwardHandler } from './types.js';
 
 export const snapshotTool: ToolDefinition = {
   name: 'browser_snapshot',
-  summary: 'Get the accessibility tree with element refs',  description:
-    'Get an accessibility tree snapshot of the page, including shadow DOM (web components), slotted content and same-origin iframes. Returns element refs you can use with click, type, and every other ref tool. Use compact mode (default) for smaller output - only interactive elements, landmarks and headings. Output is capped by maxChars (default 20000); scope big pages with selector or ref.',
+  summary: 'Get the accessibility tree with element refs',
+  description:
+    'Get an accessibility tree snapshot of the page, including shadow DOM (web components), slotted content and same-origin iframes. Returns element refs you can use with click, type, and every other ref tool. Use compact mode (default) for smaller output - only interactive elements, landmarks and headings. Output is capped by maxChars (default 20000); scope big pages with selector or ref. source:"native" reads Chrome\'s own accessibility tree (exact roles, names and states as assistive technology computes them; uses the debugger, falls back to the DOM tree if it cannot attach); the default "dom" builds the tree from the page without the debugger.',
   inputSchema: z.object({
     tabId: requireTabId(),
     selector: z.string().optional().describe('CSS selector to scope the snapshot'),
@@ -13,6 +14,7 @@ export const snapshotTool: ToolDefinition = {
     compact: z.boolean().optional().default(true).describe('When true (default), returns only interactive elements with minimal nesting. Set false for full tree.'),
     filter: z.enum(['interactive', 'all']).optional().describe('Alias of compact: "interactive" = compact, "all" = full tree. Wins over compact when given.'),
     depth: z.number().int().min(0).optional().describe('Max nesting depth of returned nodes (0 = top level only)'),
+    source: z.enum(['dom', 'native']).optional().describe('"dom" (default): tree built from the DOM, no debugger banner. "native": Chrome\'s real accessibility tree via CDP (computed roles/names/states, closed shadow roots, same-origin iframes). Refs from either work with every ref tool. Result says source:"native"; if the debugger cannot attach you get the DOM tree plus nativeUnavailable.'),
     maxChars: z.number().int().min(500).max(200_000).optional().describe('Cap on the serialized tree size (default 20000). The result says truncated:true when hit.'),
   }),
   // Read-only (refs are deterministic given a stable DOM): safe to retry.
diff --git a/tests/ax-native.test.ts b/tests/ax-native.test.ts
new file mode 100644
index 0000000..05af9f5
--- /dev/null
+++ b/tests/ax-native.test.ts
@@ -0,0 +1,350 @@
+import { describe, expect, it } from 'vitest';
+import {
+  AX_INTERACTIVE_ROLES,
+  MAX_NATIVE_REFS,
+  applyBindings,
+  axProps,
+  backendIdAtPath,
+  mergeFrameTrees,
+  shapeAxTree,
+} from '../extension/lib/ax-native.js';
+
+type Spec = {
+  role: string;
+  name?: string;
+  value?: string;
+  description?: string;
+  ignored?: boolean;
+  backend?: number | null;
+  props?: Record<string, unknown>;
+  kids?: Spec[];
+};
+
+/** Build a flat CDP-style node list from a nested spec (ids are "1", "2", … in document order). */
+function forest(root: Spec, firstId = 1): any[] {
+  const nodes: any[] = [];
+  let id = firstId;
+  let backend = 100;
+  const visit = (spec: Spec, parentId?: string): string => {
+    const nodeId = String(id++);
+    const node: any = {
+      nodeId,
+      ignored: !!spec.ignored,
+      role: { type: 'role', value: spec.role },
+      name: { type: 'computedString', value: spec.name ?? '' },
+      childIds: [],
+      ...(spec.backend === null ? {} : { backendDOMNodeId: spec.backend ?? backend++ }),
+      ...(parentId ? { parentId } : {}),
+      ...(spec.value !== undefined ? { value: { type: 'string', value: spec.value } } : {}),
+      ...(spec.description ? { description: { type: 'computedString', value: spec.description } } : {}),
+      properties: Object.entries(spec.props ?? {}).map(([name, value]) => ({ name, value: { type: 'boolean', value } })),
+    };
+    nodes.push(node);
+    for (const kid of spec.kids ?? []) node.childIds.push(visit(kid, nodeId));
+    return nodeId;
+  };
+  visit(root);
+  return nodes;
+}
+
+const page = (...kids: Spec[]): Spec => ({ role: 'RootWebArea', name: 'Page', backend: 1, kids });
+const flat = (tree: any): any[] => {
+  const out: any[] = [];
+  const visit = (n: any) => {
+    if (!n) return;
+    if (Array.isArray(n)) { n.forEach(visit); return; }
+    out.push(n);
+    visit(n.children);
+  };
+  visit(tree);
+  return out;
+};
+
+describe('shapeAxTree — compact', () => {
+  it('keeps interactive nodes, landmarks and headings; promotes everything else', () => {
+    const nodes = forest(page(
+      { role: 'generic', kids: [
+        { role: 'navigation', name: 'Main', kids: [{ role: 'link', name: 'Docs' }] },
+        { role: 'paragraph', kids: [{ role: 'StaticText', name: 'plain text' }] },
+        { role: 'heading', name: 'Title', props: { level: 2 } },
+        { role: 'button', name: 'Save' },
+      ] },
+    ));
+    const { tree } = shapeAxTree(nodes, { refPrefix: 'p-' });
+    expect(tree).toEqual([
+      { role: 'navigation', name: 'Main', ref: 'p-0', children: [{ role: 'link', name: 'Docs', ref: 'p-1' }] },
+      { role: 'heading', name: 'Title', ref: 'p-2', level: 2 },
+      { role: 'button', name: 'Save', ref: 'p-3' },
+    ]);
+  });
+
+  it('reports value and native states, and omits false/absent ones', () => {
+    const nodes = forest(page(
+      { role: 'textbox', name: 'Email', value: 'a@b.c', props: { required: true, focused: true, invalid: 'true' } },
+      { role: 'checkbox', name: 'Agree', props: { checked: 'true' } },
+      { role: 'checkbox', name: 'Maybe', props: { checked: 'mixed' } },
+      { role: 'checkbox', name: 'Off', props: { checked: 'false' } },
+      { role: 'button', name: 'Menu', props: { expanded: false, disabled: true } },
+      { role: 'tab', name: 'One', props: { selected: true } },
+    ));
+    const byName = Object.fromEntries(flat(shapeAxTree(nodes).tree).map((n) => [n.name, n]));
+    expect(byName.Email).toMatchObject({ value: 'a@b.c', required: true, focused: true, invalid: true });
+    expect(flat(shapeAxTree(forest(page({ role: 'textbox', name: 'Spell', props: { invalid: 'spelling' } }))).tree)[0].invalid).toBe('spelling');
+    expect(byName.Agree.checked).toBe(true);
+    expect(byName.Maybe.checked).toBe('mixed');
+    expect(byName.Off.checked).toBe(false);
+    expect(byName.Menu).toMatchObject({ expanded: false, disabled: true });
+    expect(byName.One.selected).toBe(true);
+    expect(byName.Agree).not.toHaveProperty('value'); // checkbox state is `checked`, not a value
+    expect(byName.Save).toBeUndefined();
+  });
+
+  it('drops ignored nodes but still walks their children', () => {
+    const nodes = forest(page(
+      { role: 'none', ignored: true, kids: [{ role: 'button', name: 'Inside ignored wrapper' }] },
+      { role: 'button', name: 'Gone', ignored: true },
+    ));
+    expect(flat(shapeAxTree(nodes).tree).map((n) => n.name)).toEqual(['Inside ignored wrapper']);
+  });
+
+  it('keeps a named focusable generic (a clickable <div tabindex>) as interactive', () => {
+    const nodes = forest(page(
+      { role: 'generic', name: 'Clickable card', props: { focusable: true } },
+      { role: 'generic', name: '', props: { focusable: true } },
+      { role: 'generic', name: 'Not focusable' },
+    ));
+    const out = flat(shapeAxTree(nodes).tree);
+    expect(out).toEqual([{ role: 'generic', name: 'Clickable card', ref: 'n0' }]);
+  });
+
+  it('lists the Chrome-specific widget roles it was observed to report', () => {
+    // Observed from Accessibility.getFullAXTree in Chromium for native controls.
+    for (const role of ['ColorWell', 'Date', 'DateTime', 'InputTime', 'DisclosureTriangle', 'spinbutton', 'searchbox', 'combobox', 'listbox']) {
+      expect(AX_INTERACTIVE_ROLES.has(role), role).toBe(true);
+    }
+    const { tree } = shapeAxTree(forest(page(
+      { role: 'Date', name: 'Birthday' }, { role: 'InputTime', name: 'Start' }, { role: 'ColorWell', name: 'Colour' },
+    )));
+    expect(flat(tree).map((n) => n.role)).toEqual(['Date', 'InputTime', 'ColorWell']);
+  });
+
+  it('skips list markers and text boxes, and gives no ref to nodes with no DOM node', () => {
+    const nodes = forest(page(
+      { role: 'listitem', kids: [{ role: 'ListMarker', name: '• ' }, { role: 'StaticText', name: 'item' }] },
+      { role: 'DisclosureTriangle', name: 'Details' },
+      { role: 'button', name: 'Virtual', backend: null },
+    ));
+    const { tree, entries } = shapeAxTree(nodes);
+    expect(flat(tree).map((n) => [n.name, n.ref])).toEqual([['Details', 'n0'], ['Virtual', undefined]]);
+    expect(entries.map((e) => e.ref)).toEqual(['n0']);
+    expect(flat(shapeAxTree(nodes, { compact: false }).tree).some((n) => n.name === '• ')).toBe(false);
+  });
+
+  it('returns null for a page with nothing actionable', () => {
+    expect(shapeAxTree(forest(page({ role: 'paragraph', kids: [{ role: 'StaticText', name: 'hi' }] }))).tree).toBeNull();
+  });
+});
+
+describe('shapeAxTree — full tree', () => {
+  it('keeps structure and text, promotes wrappers, and drops text repeating its parent name', () => {
+    const nodes = forest(page(
+      { role: 'generic', kids: [
+        { role: 'paragraph', kids: [
+          { role: 'StaticText', name: 'Read the ' },
+          { role: 'link', name: 'docs', kids: [{ role: 'StaticText', name: 'docs' }, { role: 'InlineTextBox', name: 'docs' }] },
+        ] },
+        { role: 'button', name: 'Close dialog', kids: [{ role: 'StaticText', name: 'x' }] },
+      ] },
+    ));
+    const { tree } = shapeAxTree(nodes, { compact: false });
+    expect(tree).toEqual([
+      {
+        role: 'paragraph',
+        ref: 'n0',
+        children: [
+          { role: 'text', name: 'Read the' },
+          { role: 'link', name: 'docs', ref: 'n1' }, // its StaticText child repeats the name: dropped
+        ],
+      },
+      // the visible text "x" is not part of the aria-label name, so it stays
+      { role: 'button', name: 'Close dialog', ref: 'n2', children: [{ role: 'text', name: 'x' }] },
+    ]);
+  });
+
+  it('adds descriptions only in full mode', () => {
+    const nodes = forest(page({ role: 'button', name: 'Pay', description: 'Charges your card' }));
+    expect(flat(shapeAxTree(nodes, { compact: false }).tree)[0].description).toBe('Charges your card');
+    expect(flat(shapeAxTree(nodes, { compact: true }).tree)[0]).not.toHaveProperty('description');
+  });
+});
+
+describe('shapeAxTree — limits, scope and bookkeeping', () => {
+  const many = (count: number) => forest(page(...Array.from({ length: count }, (_, i): Spec => ({ role: 'button', name: `B${i}` }))));
+
+  it('stops at maxChars and says so', () => {
+    const { tree, truncated } = shapeAxTree(many(200), { maxChars: 600 });
+    expect(truncated).toBe(true);
+    expect(flat(tree).length).toBeGreaterThan(0);
+    expect(flat(tree).length).toBeLessThan(200);
+  });
+
+  it('honours depth (0 = top level only) and flags truncation', () => {
+    const nodes = forest(page({ role: 'navigation', name: 'Nav', kids: [{ role: 'link', name: 'In' }] }));
+    const { tree, truncated } = shapeAxTree(nodes, { depth: 0 });
+    expect(tree).toEqual({ role: 'navigation', name: 'Nav', ref: 'n0' });
+    expect(truncated).toBe(true);
+  });
+
+  it('caps nodes that get a ref and reports refLimited', () => {
+    const { entries, refLimited, tree } = shapeAxTree(many(MAX_NATIVE_REFS + 25), { maxChars: 10_000_000 });
+    expect(entries).toHaveLength(MAX_NATIVE_REFS);
+    expect(refLimited).toBe(true);
+    expect(flat(tree).filter((n) => !n.ref)).toHaveLength(25); // still listed, just not actionable
+  });
+
+  it('scopes to the subtree of a DOM node (ignored wrapper included) and reports a missing root', () => {
+    const nodes = forest(page(
+      { role: 'button', name: 'Outside' },
+      { role: 'generic', ignored: true, backend: 777, kids: [{ role: 'button', name: 'Inside' }] },
+    ));
+    const scoped = shapeAxTree(nodes, { rootBackendNodeId: 777 });
+    expect(flat(scoped.tree).map((n) => n.name)).toEqual(['Inside']);
+    expect(scoped.rootFound).toBe(true);
+    expect(shapeAxTree(nodes, { rootBackendNodeId: 424242 })).toMatchObject({ rootFound: false, tree: null });
+  });
+
+  it('marks nodes absent from the previous fingerprints as new', () => {
+    const nodes = forest(page({ role: 'button', name: 'Old' }, { role: 'button', name: 'Fresh' }));
+    const first = shapeAxTree(nodes);
+    expect(first.fingerprints).toEqual(['button|Old', 'button|Fresh']);
+    expect(flat(first.tree).some((n) => n.isNew)).toBe(false);
+    const next = shapeAxTree(nodes.concat([]), { prevFingerprints: new Set(['button|Old']) });
+    expect(flat(next.tree).filter((n) => n.isNew).map((n) => n.name)).toEqual(['Fresh']);
+  });
+
+  it('truncates long names and collapses whitespace', () => {
+    const nodes = forest(page({ role: 'button', name: `  ${'word '.repeat(60)} ` }));
+    const [btn] = flat(shapeAxTree(nodes).tree);
+    expect(btn.name.length).toBeLessThanOrEqual(80);
+    expect(btn.name).not.toMatch(/\s{2,}/);
+  });
+});
+
+describe('mergeFrameTrees', () => {
+  const mainNodes = () => forest(page({ role: 'Iframe', backend: 50 }, { role: 'button', name: 'Top' }));
+  const frameNodes = () => forest({ role: 'RootWebArea', name: 'Frame', backend: 60, kids: [{ role: 'button', name: 'In frame', backend: 61 }] });
+
+  it('grafts a child frame under its owner node and namespaces its ids', () => {
+    const merged = mergeFrameTrees(mainNodes(), [{ nodes: frameNodes(), ownerBackendNodeId: 50 }]);
+    // Same numeric ids in both frames must not collide.
+    expect(new Set(merged.map((n) => n.nodeId)).size).toBe(merged.length);
+    const { tree } = shapeAxTree(merged);
+    expect(flat(tree).map((n) => n.name)).toEqual(['In frame', 'Top']);
+  });
+
+  it('tags nodes with the frame they came from (the bridge batches per frame)', () => {
+    const merged = mergeFrameTrees(mainNodes(), [{ nodes: frameNodes(), ownerBackendNodeId: 50 }]);
+    const { entries } = shapeAxTree(merged);
+    expect(entries.map((e) => [e.backendNodeId, e.frame])).toEqual([[61, 1], [100, 0]]);
+  });
+
+  it('ignores a frame whose owner is not in the tree and never mutates its input', () => {
+    const main = mainNodes();
+    const before = JSON.stringify(main);
+    const merged = mergeFrameTrees(main, [{ nodes: frameNodes(), ownerBackendNodeId: 9999 }]);
+    expect(JSON.stringify(main)).toBe(before);
+    expect(flat(shapeAxTree(merged).tree).map((n) => n.name)).toEqual(['Top']);
+  });
+});
+
+describe('applyBindings', () => {
+  const sample = () => [
+    { role: 'link', name: 'A', ref: 'r0' },
+    { role: 'navigation', ref: 'r1', children: [{ role: 'button', name: 'B', ref: 'r2' }] },
+  ];
+
+  it('removes refs the page could not bind and attaches hrefs', () => {
+    expect(applyBindings(sample(), { r0: { href: '/a' }, r2: {} })).toEqual([
+      { role: 'link', name: 'A', ref: 'r0', href: '/a' },
+      { role: 'navigation', children: [{ role: 'button', name: 'B', ref: 'r2' }] },
+    ]);
+  });
+
+  it('with dropUnbound omits interactive nodes it could not bind (browser-internal controls) and promotes their children', () => {
+    // A date input: the field binds, its sub-fields and picker button live in a user-agent shadow root.
+    const tree = [{ role: 'Date', name: 'Birthday', ref: 'd', children: [
+      { role: 'spinbutton', name: 'Month Month', ref: 'm' },
+      { role: 'spinbutton', name: 'Day Day', ref: 'y' },
+      { role: 'button', name: 'Show date picker', ref: 'p' },
+    ] }];
+    expect(applyBindings(tree, { d: {} }, { dropUnbound: true })).toEqual({ role: 'Date', name: 'Birthday', ref: 'd' });
+    // Landmarks that did not bind stay (without a ref): their bound children are still actionable.
+    expect(applyBindings(sample(), { r2: {} }, { dropUnbound: true })).toEqual(
+      { role: 'navigation', children: [{ role: 'button', name: 'B', ref: 'r2' }] },
+    );
+  });
+
+  it('keeps unbound nodes (ref-less) in the full tree', () => {
+    const tree = [{ role: 'button', name: 'Gone', ref: 'x' }];
+    expect(applyBindings(tree, {})).toEqual({ role: 'button', name: 'Gone' });
+  });
+
+  it('copes with a null tree', () => {
+    expect(applyBindings(null, {})).toBeNull();
+    expect(applyBindings([{ role: 'button', ref: 'x' }], {}, { dropUnbound: true })).toBeNull();
+  });
+});
+
+describe('axProps', () => {
+  it('flattens the property list', () => {
+    expect(axProps({ properties: [{ name: 'focusable', value: { value: true } }, { name: 'level', value: { value: 3 } }] }))
+      .toEqual({ focusable: true, level: 3 });
+    expect(axProps({})).toEqual({});
+  });
+});
+
+describe('backendIdAtPath (CDP DOM.getDocument dump)', () => {
+  const el = (name: string, backendNodeId: number, extra: Record<string, unknown> = {}) => ({ nodeType: 1, nodeName: name, backendNodeId, ...extra });
+  const text = (backendNodeId: number) => ({ nodeType: 3, nodeName: '#text', backendNodeId });
+
+  // document > html > body > [text, div#a, comment, x-host{closed shadow > section > button, UA shadow}, iframe{#document > html > body > b}]
+  const dump = {
+    nodeType: 9, nodeName: '#document', backendNodeId: 1,
+    children: [
+      { nodeType: 10, nodeName: 'html', backendNodeId: 2 },
+      el('HTML', 3, { children: [
+        el('HEAD', 4),
+        el('BODY', 5, { children: [
+          text(6),
+          el('DIV', 7),
+          { nodeType: 8, nodeName: '#comment', backendNodeId: 8 },
+          el('X-HOST', 9, { shadowRoots: [
+            { nodeType: 11, nodeName: '#document-fragment', shadowRootType: 'user-agent', backendNodeId: 10, children: [el('DIV', 11)] },
+            { nodeType: 11, nodeName: '#document-fragment', shadowRootType: 'closed', backendNodeId: 12, children: [el('SECTION', 13, { children: [el('BUTTON', 14)] })] },
+          ] }),
+          el('IFRAME', 15, { contentDocument: { nodeType: 9, nodeName: '#document', backendNodeId: 16, children: [el('HTML', 17, { children: [el('BODY', 18, { children: [el('B', 19)] })] })] } }),
+        ] }),
+      ] }),
+    ],
+  };
+
+  it('counts element children only (text, comments and doctype do not shift indexes)', () => {
+    expect(backendIdAtPath(dump, [0], 'HTML')).toBe(3);
+    expect(backendIdAtPath(dump, [0, 1, 0], 'DIV')).toBe(7);
+  });
+
+  it('enters the author shadow root, never the user-agent one', () => {
+    expect(backendIdAtPath(dump, [0, 1, 1, -1, 0, 0], 'BUTTON')).toBe(14);
+  });
+
+  it('enters iframe content documents', () => {
+    expect(backendIdAtPath(dump, [0, 1, 2, -2, 0, 0, 0], 'B')).toBe(19);
+  });
+
+  it('rejects a path that ends on the wrong tag, off the tree, or on a non-element', () => {
+    expect(backendIdAtPath(dump, [0, 1, 0], 'SPAN')).toBeNull();
+    expect(backendIdAtPath(dump, [0, 9], 'DIV')).toBeNull();
+    expect(backendIdAtPath(dump, [0, 1, 0, -1], 'DIV')).toBeNull();
+    expect(backendIdAtPath(dump, [], 'DIV')).toBeNull(); // the document itself
+  });
+});
diff --git a/tests/extension-ax-snapshot.test.ts b/tests/extension-ax-snapshot.test.ts
new file mode 100644
index 0000000..fac980c
--- /dev/null
+++ b/tests/extension-ax-snapshot.test.ts
@@ -0,0 +1,326 @@
+import { beforeEach, describe, expect, it } from 'vitest';
+import { installFakePage, installFakeFrame, FakeElement, type FakeDocument } from './helpers/fake-dom.js';
+
+/**
+ * browser_snapshot source:"native" end to end, minus Chrome: the real handler
+ * runs against the fake page while chrome.debugger answers the handful of CDP
+ * commands it issues. The Runtime.callFunctionOn mock evaluates the function
+ * source the handler sends (exactly what Chrome would run in the main world)
+ * and enforces Chrome's rule that one call cannot mix JS contexts.
+ */
+
+type Cdp = { method: string; params: Record<string, any> };
+const cdp: Cdp[] = [];
+let tabUrl = 'https://example.test/page';
+let attachError: string | null = null;
+/** backendNodeIds whose DOM.resolveNode fails (node already gone). */
+const unresolvable = new Set<number>();
+/** Runs inside callFunctionOn, after the paths were computed (simulates the page changing mid-snapshot). */
+let afterPaths: (() => void) | null = null;
+
+const ids = new Map<unknown, number>();
+const byId = new Map<number, FakeElement>();
+let nextId = 10;
+const idOf = (el: FakeElement) => {
+  if (!ids.has(el)) { ids.set(el, nextId); byId.set(nextId, el); nextId++; }
+  return ids.get(el)!;
+};
+
+let mainAx: any[] = [];
+let childAx: any[] = [];
+let iframeEl: FakeElement;
+let doc: FakeDocument;
+
+function cdpNode(node: FakeElement): any {
+  const out: any = { nodeType: 1, nodeName: node.tagName, backendNodeId: idOf(node), children: node.children.map(cdpNode) };
+  if (node.shadowRoot) {
+    out.shadowRoots = [{ nodeType: 11, nodeName: '#document-fragment', shadowRootType: 'closed', backendNodeId: nextId++, children: node.shadowRoot.children.map(cdpNode) }];
+  }
+  const inner = (node as unknown as { contentDocument?: FakeDocument }).contentDocument;
+  if (inner) out.contentDocument = { nodeType: 9, nodeName: '#document', backendNodeId: nextId++, children: [cdpNode(inner.documentElement)] };
+  return out;
+}
+
+(globalThis as any).chrome = {
+  tabs: {
+    get: async (id: number) => ({ id, url: id === 99 ? 'chrome://version/' : tabUrl, title: 'Fixture', windowId: 1 }),
+    query: async () => [],
+    onRemoved: { addListener: () => {} },
+  },
+  scripting: { executeScript: async (o: { func: (...a: any[]) => unknown; args?: unknown[] }) => [{ result: await o.func(...(o.args ?? [])) }] },
+  storage: { session: { get: async () => ({}), set: async () => {} }, local: { get: async () => ({}), set: async () => {} } },
+  windows: { get: async () => ({ width: 1200, height: 900 }) },
+  debugger: {
+    attach: async () => { if (attachError) throw new Error(attachError); },
+    detach: async () => {},
+    onDetach: { addListener: () => {} },
+    sendCommand: async (_t: unknown, method: string, params: Record<string, any> = {}) => {
+      cdp.push({ method, params });
+      switch (method) {
+        case 'Page.getFrameTree':
+          return { frameTree: { frame: { id: 'main', url: tabUrl }, childFrames: childAx.length ? [{ frame: { id: 'child', url: 'about:srcdoc' } }] : [] } };
+        case 'Accessibility.getFullAXTree':
+          return { nodes: params.frameId === 'child' ? childAx : mainAx };
+        case 'DOM.getFrameOwner':
+          return { backendNodeId: idOf(iframeEl) };
+        case 'DOM.resolveNode':
+          if (unresolvable.has(params.backendNodeId) || !byId.has(params.backendNodeId)) throw new Error('No node with given id found');
+          return { object: { objectId: `obj-${params.backendNodeId}` } };
+        case 'DOM.getDocument':
+          return { root: { nodeType: 9, nodeName: '#document', backendNodeId: 1, children: [cdpNode(doc.documentElement)] } };
+        case 'Runtime.callFunctionOn': {
+          const elOf = (objectId: string) => byId.get(Number(objectId.slice(4)))!;
+          const els = (params.arguments as Array<{ objectId: string }>).map((a) => elOf(a.objectId));
+          const worlds = new Set([elOf(params.objectId), ...els].map((e) => e.ownerDocument));
+          if (worlds.size > 1) throw new Error('Argument should belong to the same JavaScript world as target object');
+          const fn = new Function(`return (${params.functionDeclaration})`)();
+          const value = fn(...els);
+          if (afterPaths) { afterPaths(); afterPaths = null; }
+          return { result: { value } };
+        }
+        case 'Runtime.evaluate':
+          return { result: { value: 1000 } };
+        default:
+          return {};
+      }
+    },
+  },
+};
+
+const { PAGE_DOM_INSTALL, PAGE_DOM_VERSION } = await import('../extension/lib/page-dom.js');
+const { handleSnapshot } = await import('../extension/handlers/inspection.js');
+const { handleClick } = await import('../extension/handlers/interaction.js');
+const { detachCdp } = await import('../extension/lib/cdp-session.js');
+const { fallbackByTab, lastNativeFingerprints } = await import('../extension/lib/state.js');
+
+const D = () => (globalThis as any).__bcDom;
+
+/** Nested AX spec bound to fake elements: { role, name, el, kids }. */
+type Spec = { role: string; name?: string; el?: FakeElement; ignored?: boolean; props?: Record<string, unknown>; kids?: Spec[] };
+function axNodes(root: Spec): any[] {
+  const nodes: any[] = [];
+  let n = 0;
+  const visit = (spec: Spec, parentId?: string): string => {
+    const nodeId = String(++n);
+    const node: any = {
+      nodeId, ignored: !!spec.ignored, childIds: [],
+      role: { value: spec.role }, name: { value: spec.name ?? '' },
+      ...(spec.el ? { backendDOMNodeId: idOf(spec.el) } : {}),
+      ...(parentId ? { parentId } : {}),
+      properties: Object.entries(spec.props ?? {}).map(([name, value]) => ({ name, value: { value } })),
+    };
+    nodes.push(node);
+    for (const kid of spec.kids ?? []) node.childIds.push(visit(kid, nodeId));
+    return nodeId;
+  };
+  visit(root);
+  return nodes;
+}
+
+const flat = (tree: any): any[] => {
+  const out: any[] = [];
+  const visit = (x: any) => { if (!x) return; if (Array.isArray(x)) { x.forEach(visit); return; } out.push(x); visit(x.children); };
+  visit(tree);
+  return out;
+};
+const named = (tree: any, name: string) => flat(tree).find((n) => n.name === name);
+
+let nav: FakeElement, link: FakeElement, save: FakeElement, dupA: FakeElement, dupB: FakeElement;
+let host: FakeElement, deep: FakeElement, inFrame: FakeElement;
+
+beforeEach(() => {
+  cdp.length = 0;
+  attachError = null;
+  tabUrl = 'https://example.test/page';
+  unresolvable.clear();
+  afterPaths = null;
+  ids.clear(); byId.clear(); nextId = 10;
+  fallbackByTab.clear();
+  lastNativeFingerprints.clear();
+
+  doc = installFakePage();
+  PAGE_DOM_INSTALL(PAGE_DOM_VERSION);
+  link = doc.el('a', { href: '/docs' }, 'Docs');
+  (link as any).href = 'https://example.test/docs';
+  nav = doc.el('nav', { 'aria-label': 'Main' }, link);
+  save = doc.el('button', { id: 'save' }, 'Save');
+  dupA = doc.el('button', {}, 'Dup');
+  dupB = doc.el('button', {}, 'Dup');
+  host = doc.el('x-host');
+  deep = doc.el('button', { class: 'deep' }, 'Deep');
+  host.attachShadow().append(doc.el('section', {}, deep));
+  iframeEl = doc.el('iframe');
+  const inner = installFakeFrame(iframeEl);
+  inFrame = inner.el('button', {}, 'In frame');
+  inner.body.append(inFrame);
+  const main = doc.el('main', {}, doc.el('h1', {}, 'Title'), save, dupA, dupB, host, iframeEl);
+  doc.body.append(nav, main);
+
+  mainAx = axNodes({
+    role: 'RootWebArea', name: 'Fixture', el: doc.documentElement, kids: [
+      { role: 'navigation', name: 'Main', el: nav, kids: [{ role: 'link', name: 'Docs', el: link }] },
+      { role: 'main', el: main, kids: [
+        { role: 'heading', name: 'Title', el: main.children[0], props: { level: 1 } },
+        { role: 'button', name: 'Save', el: save },
+        { role: 'button', name: 'Dup', el: dupA },
+        { role: 'button', name: 'Dup', el: dupB },
+        { role: 'button', name: 'Deep', el: deep },
+        { role: 'Iframe', el: iframeEl },
+      ] },
+    ],
+  });
+  childAx = axNodes({ role: 'RootWebArea', name: 'Frame', el: inner.documentElement, kids: [{ role: 'button', name: 'In frame', el: inFrame }] });
+});
+
+async function native(extra: Record<string, unknown> = {}) {
+  await detachCdp(7); // fresh session per test
+  return handleSnapshot({ tabId: 7, source: 'native', ...extra }) as Promise<any>;
+}
+
+describe('browser_snapshot source:"native"', () => {
+  it('returns Chrome\'s tree and binds every ref to the live element', async () => {
+    const res = await native();
+    expect(res).toMatchObject({ success: true, source: 'native', compact: true, url: 'https://example.test/page', title: 'Fixture' });
+    expect(res.nativeUnavailable).toBeUndefined();
+    expect(flat(res.tree).map((n) => `${n.role}:${n.name ?? ''}`)).toEqual([
+      'navigation:Main', 'link:Docs', 'main:', 'heading:Title', 'button:Save', 'button:Dup', 'button:Dup', 'button:Deep', 'button:In frame',
+    ]);
+    const registry = D().registry as Map<string, unknown>;
+    expect(registry.get(named(res.tree, 'Save').ref)).toBe(save);
+    expect(registry.get(named(res.tree, 'Deep').ref)).toBe(deep); // inside a closed shadow root
+    expect(registry.get(named(res.tree, 'In frame').ref)).toBe(inFrame); // inside an iframe
+    expect(named(res.tree, 'Docs').href).toBe('/docs'); // same-origin links are path-only
+    expect(named(res.tree, 'Title').level).toBe(1);
+  });
+
+  it('batches the CDP bridge per frame (Chrome rejects mixing JS contexts)', async () => {
+    const res = await native();
+    expect(res.success).toBe(true);
+    const calls = cdp.filter((c) => c.method === 'Runtime.callFunctionOn');
+    expect(calls).toHaveLength(2); // top frame, then the iframe
+    expect(cdp.some((c) => c.method === 'Runtime.releaseObjectGroup')).toBe(true);
+  });
+
+  it('keeps same-named siblings apart: acting on a ref hits that element, not the first match', async () => {
+    const res = await native();
+    const [first, second] = flat(res.tree).filter((n) => n.name === 'Dup');
+    expect(first.ref).not.toBe(second.ref);
+    await handleClick({ tabId: 7, ref: second.ref, trusted: false });
+    expect(dupB.events).toContain('click');
+    expect(dupA.events).not.toContain('click');
+  });
+
+  it('records a smart-selector fallback for every bound ref (stale-ref recovery works for native refs)', async () => {
+    // The real generator needs tree walkers the fake DOM lacks: stub it (the installer is idempotent).
+    (globalThis as any).__browserControllerFallbackRuntime = {
+      generateFallback: (el: FakeElement) => ({ tag: el.tagName, text: el.textContent }),
+    };
+    const res = await native();
+    const map = fallbackByTab.get(7)!;
+    expect(map.get(named(res.tree, 'Save').ref)).toEqual({ tag: 'BUTTON', text: 'Save' });
+    expect(map.get(named(res.tree, 'In frame').ref)).toEqual({ tag: 'BUTTON', text: 'In frame' });
+    // A scoped snapshot adds to the map instead of replacing it.
+    const before = map.size;
+    await native({ selector: 'nav' });
+    expect(fallbackByTab.get(7)!.size).toBeGreaterThan(before);
+  });
+
+  it('scopes by selector, including a selector that only matches inside a shadow root', async () => {
+    const navOnly = await native({ selector: 'nav' });
+    expect(flat(navOnly.tree).map((n) => n.name)).toEqual(['Main', 'Docs']);
+    const deepOnly = await native({ selector: 'button.deep' });
+    expect(deepOnly.tree).toMatchObject({ role: 'button', name: 'Deep' });
+    expect((D().registry as Map<string, unknown>).get(deepOnly.tree.ref)).toBe(deep);
+  });
+
+  it('scopes by the ref of an earlier snapshot', async () => {
+    const full = await native();
+    const scoped = await native({ ref: named(full.tree, 'Main').ref });
+    expect(flat(scoped.tree).map((n) => n.name)).toEqual(['Main', 'Docs']);
+  });
+
+  it('reports a bad selector, a missing root and a stale ref without touching CDP results', async () => {
+    expect(await native({ selector: '###' })).toMatchObject({ success: false, error: expect.stringContaining('Invalid CSS selector') });
+    expect(await native({ selector: '.nope' })).toMatchObject({ success: false, error: 'Root element not found' });
+    expect(await native({ ref: 'gone-ref' })).toMatchObject({ success: false, error: expect.stringContaining('ref gone-ref is gone') });
+  });
+
+  it('flags only elements that appeared since the previous native snapshot', async () => {
+    await native();
+    const added = doc.el('button', {}, 'Added');
+    doc.body.append(added);
+    mainAx = axNodes({ role: 'RootWebArea', name: 'Fixture', el: doc.documentElement, kids: [
+      { role: 'button', name: 'Save', el: save },
+      { role: 'button', name: 'Added', el: added },
+    ] });
+    childAx = [];
+    const res = await native();
+    expect(flat(res.tree).filter((n) => n.isNew).map((n) => n.name)).toEqual(['Added']);
+  });
+
+  it('omits controls it could not bind from the compact tree and counts them', async () => {
+    unresolvable.add(idOf(dupB)); // e.g. a control inside a user-agent shadow root
+    const res = await native();
+    expect(flat(res.tree).filter((n) => n.name === 'Dup').map((n) => Boolean(n.ref))).toEqual([true]);
+    expect(res.unreachableNodes).toBe(1);
+  });
+
+  it('keeps them, ref-less, in the full tree', async () => {
+    unresolvable.add(idOf(dupB));
+    const res = await native({ compact: false });
+    expect(flat(res.tree).filter((n) => n.name === 'Dup').map((n) => Boolean(n.ref))).toEqual([true, false]);
+    expect(res.unreachableNodes).toBe(1);
+  });
+
+  it('refuses to bind an element that changed tag between the AX read and the bind', async () => {
+    afterPaths = () => {
+      // The page re-rendered: a <div> now sits where the Save <button> was.
+      const parent = save.parentNode!;
+      const swapped = doc.el('div', {}, 'Save');
+      const i = parent.childNodes.indexOf(save);
+      parent.childNodes.splice(i, 1, swapped);
+      swapped.parentNode = parent;
+    };
+    const res = await native();
+    expect(named(res.tree, 'Save')).toBeUndefined(); // never bound to the wrong element, and not offered
+    expect(res.unreachableNodes).toBe(1);
+    expect(named(res.tree, 'Deep').ref).toBeTruthy(); // the rest still bound
+  });
+
+  it('skips cross-origin frames whose tree is not reachable and reports them', async () => {
+    const original = (globalThis as any).chrome.debugger.sendCommand;
+    (globalThis as any).chrome.debugger.sendCommand = async (t: unknown, m: string, p: Record<string, any>) => {
+      if (m === 'Accessibility.getFullAXTree' && p?.frameId === 'child') throw new Error('Frame with the given id was not found.');
+      return original(t, m, p);
+    };
+    try {
+      const res = await native();
+      expect(res.success).toBe(true);
+      expect(res.skippedFrames).toEqual(['about:srcdoc']);
+      expect(named(res.tree, 'In frame')).toBeUndefined();
+      expect(named(res.tree, 'Save')?.ref).toBeTruthy();
+    } finally {
+      (globalThis as any).chrome.debugger.sendCommand = original;
+    }
+  });
+
+  it('falls back to the DOM tree, with the reason, when the debugger cannot attach', async () => {
+    attachError = 'Cannot attach to this target.';
+    const res = await native();
+    expect(res.success).toBe(true);
+    expect(res.source).toBeUndefined();
+    expect(res.nativeUnavailable).toContain('Cannot attach to this target.');
+    expect(flat(res.tree).some((n) => n.name === 'Save')).toBe(true);
+  });
+
+  it('rejects browser-internal pages like the DOM snapshot does', async () => {
+    await expect(handleSnapshot({ tabId: 99, source: 'native' })).rejects.toThrow(/protected page/);
+  });
+
+  it('is opt-in: the default snapshot never touches the debugger', async () => {
+    const res = await handleSnapshot({ tabId: 7 }) as any;
+    expect(res.success).toBe(true);
+    expect(res.source).toBeUndefined();
+    expect(cdp).toEqual([]);
+  });
+});
diff --git a/tests/helpers/fake-dom.ts b/tests/helpers/fake-dom.ts
index 9842048..776aa45 100644
--- a/tests/helpers/fake-dom.ts
+++ b/tests/helpers/fake-dom.ts
@@ -132,8 +132,17 @@ export class FakeDocument {
   title = 'Fixture';
   activeElement: FakeElement | null = null;
   body: FakeElement;
+  /** The <html> element: parent of body, so element paths reach the document like a real page. */
+  documentElement: FakeElement;
+  parentNode = null;
+  get children() { return [this.documentElement]; }
   defaultView: { getComputedStyle: (el: FakeElement) => Record<string, string>; frameElement: FakeElement | null } = { getComputedStyle: (el: FakeElement) => ({ display: el.attrs.get('style')?.includes('display:contents') ? 'contents' : el.isHiddenInTree ? 'none' : 'block', visibility: 'visible', opacity: '1' }), frameElement: null };
-  constructor() { this.body = new FakeElement(this, 'BODY'); }
+  constructor() {
+    this.documentElement = new FakeElement(this, 'HTML');
+    this.body = new FakeElement(this, 'BODY');
+    this.documentElement.parentNode = this as unknown as FakeShadowRoot;
+    this.documentElement.append(this.body);
+  }
   el(tag: string, attrs: Record<string, string> = {}, ...kids: Array<FakeElement | string>) {
     return new FakeElement(this, tag, attrs).append(...kids);
   }
diff --git a/tests/tools/snapshot.test.ts b/tests/tools/snapshot.test.ts
new file mode 100644
index 0000000..d71dfb7
--- /dev/null
+++ b/tests/tools/snapshot.test.ts
@@ -0,0 +1,42 @@
+import { describe, expect, it } from "vitest";
+import { snapshotTool } from "../../mcp-server/src/tools/snapshot.js";
+import type { ToolHost } from "../../mcp-server/src/tools/types.js";
+
+describe("browser_snapshot schema", () => {
+  const parse = (extra: Record<string, unknown>) =>
+    snapshotTool.inputSchema.safeParse({ tabId: 1, ...extra });
+
+  it('accepts source "dom" and "native", and leaves it optional (DOM stays the default)', () => {
+    expect(parse({ source: "native" }).success).toBe(true);
+    expect(parse({ source: "dom" }).success).toBe(true);
+    const bare = parse({});
+    expect(bare.success).toBe(true);
+    expect(bare.success && bare.data.source).toBeUndefined();
+  });
+
+  it("rejects an unknown source", () => {
+    expect(parse({ source: "axtree" }).success).toBe(false);
+  });
+
+  it("documents the native option for agents", () => {
+    expect(snapshotTool.description).toContain('source:"native"');
+  });
+
+  it("forwards source to the extension untouched", async () => {
+    const seen: Array<{ tool: string; params: Record<string, unknown> }> = [];
+    const host: ToolHost = {
+      callTool: async (tool, params) => {
+        seen.push({ tool, params });
+        return { success: true, source: "native" };
+      },
+    };
+    await snapshotTool.handler(host, { tabId: 4, source: "native", compact: false });
+    expect(seen).toEqual([
+      { tool: "browser_snapshot", params: { tabId: 4, source: "native", compact: false } },
+    ]);
+  });
+
+  it("stays idempotent (safe to retry on timeout)", () => {
+    expect(snapshotTool.idempotent).toBe(true);
+  });
+});