From 95aa23647efb759a9b37a808d2c2e794671808ce Mon Sep 17 00:00:00 2001
From: unohee <unohee.official@gmail.com>
Date: Fri, 23 Oct 2026 14:36:27 +0900
Subject: [PATCH] feat(native): the tree view and aria-refs, into cross-site
 iframes too (phase 4)

read_page(mode="tree") now runs on the native driver, and click /
type_text / any element tool take its aria-refs.

- snapshot: Accessibility.getFullAXTree frame by frame, written as
  Playwright's aria_snapshot(mode="ai", boxes=True) so compact_snapshot reads
  it unchanged. Chrome's internal roles are mapped back (MenuListOption is an
  option, StaticText a text), a link's /url is its href as written (Chrome's
  tree has the resolved URL), boxes are in the element's own frame's
  viewport as Playwright gives them, and refs go to every rendered node with
  a box: e<n> in the top frame, f<k>e<n> in the k-th frame met. A snapshot
  replaces the page's ref table, so refs belong to the latest read.
- frames: out-of-process iframes are auto-attached (no waitForDebuggerOnStart,
  as for tabs: cdp_guard holds them) and every frame maps to the session that
  speaks for its document; nested OOPIFs included. Coordinates from an OOPIF
  session get the owner <iframe> content boxes added on the way out, so input
  lands where it should in the window.
- locator: elements carry their frame (and session) through every action;
  an aria-ref selector switches to the ref's frame, an unknown or stale one
  matches nothing, and one into a frame that is gone raises Playwright's
  "Invalid frame in aria-ref selector" (read as not_found).

Verified: pytest 1745 passed (2 pre-existing macOS sha256sum failures
deselected); tests/native 82; testing/native_tree_parity_261023_v1.py,
headless and headful (headful twice): read_page(mode="tree") on the native
and the playwright driver gives the same 75 elements in the same in-view
order; refs click a button in the top frame, in a same-site iframe and in a
cross-site OOPIF, type Korean into an OOPIF field and submit it, and a ref
from before a navigation answers not_found. The phase 1-2 and phase 3
smokes still pass.
---
 README.md                                   |   2 +-
 src/lyra_browser/native/frames.py           | 179 +++++++++++++++
 src/lyra_browser/native/locator.py          | 239 ++++++++++++++------
 src/lyra_browser/native/page.py             |  39 +++-
 src/lyra_browser/native/snapshot.py         | 233 +++++++++++++++++++
 tests/native/test_native_snapshot_frames.py | 117 ++++++++++
 6 files changed, 732 insertions(+), 77 deletions(-)
 create mode 100644 src/lyra_browser/native/frames.py
 create mode 100644 src/lyra_browser/native/snapshot.py
 create mode 100644 tests/native/test_native_snapshot_frames.py

diff --git a/README.md b/README.md
index 5af6667..64d675c 100644
--- a/README.md
+++ b/README.md
@@ -800,7 +800,7 @@ Windows are not measured. `python scripts/verify_npx_e2e.py` reproduces it. See
 | `LYRA_BROWSER_CHANNEL` | — | Force one channel (`chrome`/`msedge`). Unset = try chrome→msedge→bundled. |
 | `LYRA_BROWSER_ALLOW_BUNDLED` | `true` | Allow bundled-Chromium fallback (only exists after `playwright install`). |
 | `LYRA_BROWSER_AUDIT_STDERR` | `false` | Also write every audit record to stderr as one JSON line. For a host whose disk is ephemeral but whose stderr is collected (the Cloudflare image sets it). |
-| `LYRA_BROWSER_DRIVER` | `auto` | Which driver launches the browser: `auto` takes `patchright` when installed and falls back to `playwright`; either name pins it. `native` (experimental, opt-in) drives an installed Chrome over raw DevTools with no Playwright at all, always with the `cdp` guard, the sandbox on and no `Runtime.enable`. Selectors cover css (open shadow roots pierced), `text=`, `role=…[name=…]`, `xpath=`, `nth=`, `:visible` and `:has-text()`; the tree view (`read_page(mode="tree")` and its refs) is not in it yet. `open_browser` reports the one in use as `driver`. |
+| `LYRA_BROWSER_DRIVER` | `auto` | Which driver launches the browser: `auto` takes `patchright` when installed and falls back to `playwright`; either name pins it. `native` (experimental, opt-in) drives an installed Chrome over raw DevTools with no Playwright at all, always with the `cdp` guard, the sandbox on and no `Runtime.enable`. Selectors cover css (open shadow roots pierced), `text=`, `role=…[name=…]`, `xpath=`, `nth=`, `:visible` and `:has-text()`; `read_page(mode="tree")` comes from Chrome's accessibility tree in Playwright's format, and its refs reach into same-site and cross-site iframes. `open_browser` reports the one in use as `driver`. |
 | `LYRA_BROWSER_SANDBOX` | on | `native` driver only: Chrome's renderer sandbox. Playwright always launches with `--no-sandbox`; the native driver keeps the sandbox unless this is off (a container without user namespaces). |
 | `LYRA_BROWSER_GUARD` | `route` | Where the navigation guard stands: `route` (Playwright's route) or `cdp` (a second DevTools connection: every redirect hop judged, cache on, DataDome lets the browser in, a loopback debugging port, `guard_lost` if the guard fails). See Guard backends. |
 | `LYRA_UAT_CLAUDE_BIN` | `claude` on `PATH` | The Claude Code executable the `claude-code` UAT brain runs. See UAT mode. |
diff --git a/src/lyra_browser/native/frames.py b/src/lyra_browser/native/frames.py
new file mode 100644
index 0000000..ee8d433
--- /dev/null
+++ b/src/lyra_browser/native/frames.py
@@ -0,0 +1,179 @@
+"""Which DevTools session each frame of a page lives in, out-of-process iframes included.
+
+A same-site iframe renders in the page's own process and is reached through the page's
+session with its ``frameId``. A cross-site one (an OOPIF) runs in another process: Chrome
+gives it a target of its own, and every command about its document has to go to that
+target's session. ``FrameTracker`` auto-attaches to those (without
+``waitForDebuggerOnStart``, as the context does for tabs: ``cdp_guard`` holds them) and
+keeps the map, so a locator or a snapshot asks one question, ``frame(frame_id)``, and gets
+the session to use.
+
+Coordinates differ the same way. Inside one session, ``DOM.getContentQuads`` answers in
+the viewport of that session's top frame; an OOPIF's answers are in its own viewport.
+``viewport_offset`` adds up the owner ``<iframe>`` boxes on the way out, so input lands
+in the right place in the top-level window.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from .errors import ProtocolError, TargetClosedError
+
+if TYPE_CHECKING:
+    from .page import NativePage
+
+_IFRAME_ATTACH = {
+    "autoAttach": True,
+    "waitForDebuggerOnStart": False,
+    "flatten": True,
+    "filter": [{"type": "iframe"}, {"exclude": True}],
+}
+SETUP_TIMEOUT_S = 10.0
+
+
+@dataclass(frozen=True)
+class FrameRef:
+    """A frame and the session that speaks for its document."""
+
+    id: str
+    session: str
+
+
+class FrameTracker:
+    def __init__(self, page: NativePage) -> None:
+        self._page = page
+        # frame id -> session, for frames that live outside the page's own session
+        self._session_of: dict[str, str] = {}
+        # OOPIF session -> its root frame id
+        self._root_of: dict[str, str] = {}
+        # OOPIF root frame id -> the session whose document holds its <iframe>
+        self._parent_of: dict[str, str] = {}
+        self._tasks: set[asyncio.Task] = set()
+
+    # -- lookup ---------------------------------------------------------------------
+
+    def frame(self, frame_id: str) -> FrameRef:
+        return FrameRef(frame_id, self._session_of.get(frame_id, self._page._session))
+
+    def knows(self, frame_id: str) -> bool:
+        return frame_id in self._session_of or self._page.owns_frame(frame_id)
+
+    def is_out_of_process(self, frame_id: str) -> bool:
+        return frame_id in self._parent_of
+
+    # -- attach ---------------------------------------------------------------------
+
+    async def watch(self, session: str) -> None:
+        """Hear about the OOPIFs whose ``<iframe>`` lives in ``session``'s documents."""
+        conn = self._page._context._conn
+        conn.on("Target.attachedToTarget", lambda p, s: self._on_attached(p, s), session=session)
+        conn.on("Target.detachedFromTarget", lambda p, _s: self._on_detached(p), session=session)
+        await conn.send(
+            "Target.setAutoAttach", _IFRAME_ATTACH, session=session, timeout=SETUP_TIMEOUT_S
+        )
+
+    def _on_attached(self, params: dict, parent: str | None) -> None:
+        info = params.get("targetInfo") or {}
+        child = params.get("sessionId")
+        if info.get("type") != "iframe" or not child or parent is None:
+            return
+        frame_id = info.get("targetId", "")
+        self._session_of[frame_id] = child
+        self._root_of[child] = frame_id
+        self._parent_of[frame_id] = parent
+        # Its world in the parent process went with the document that moved out.
+        self._page._worlds.forget(frame_id)
+        task = asyncio.ensure_future(self._setup(child))
+        self._tasks.add(task)
+        task.add_done_callback(self._tasks.discard)
+
+    async def _setup(self, session: str) -> None:
+        page = self._page
+        conn = page._context._conn
+
+        def navigated(params: dict, _s: str | None) -> None:
+            frame = params.get("frame") or {}
+            if frame.get("id"):
+                self._session_of.setdefault(frame["id"], session)
+                page._worlds.forget(frame["id"])
+
+        def attached(params: dict, _s: str | None) -> None:
+            if params.get("frameId"):
+                self._session_of.setdefault(params["frameId"], session)
+
+        def detached(params: dict, _s: str | None) -> None:
+            frame_id = params.get("frameId", "")
+            page._worlds.forget(frame_id)
+            if self._session_of.get(frame_id) == session and frame_id not in self._parent_of:
+                del self._session_of[frame_id]
+
+        conn.on("Page.frameNavigated", navigated, session=session)
+        conn.on("Page.frameAttached", attached, session=session)
+        conn.on("Page.frameDetached", detached, session=session)
+        try:
+            await conn.send("Page.enable", session=session, timeout=SETUP_TIMEOUT_S)
+            await self.watch(session)
+            tree = await conn.send("Page.getFrameTree", session=session, timeout=SETUP_TIMEOUT_S)
+        except (ProtocolError, TargetClosedError, TimeoutError):
+            return  # gone again already (an ad that reloads itself away)
+        self._absorb(tree.get("frameTree") or {}, session)
+
+    def _absorb(self, node: dict, session: str) -> None:
+        frame = node.get("frame") or {}
+        if frame.get("id"):
+            self._session_of.setdefault(frame["id"], session)
+        for child in node.get("childFrames") or ():
+            self._absorb(child, session)
+
+    def _on_detached(self, params: dict) -> None:
+        session = params.get("sessionId")
+        root = self._root_of.pop(session or "", None)
+        if root is None:
+            return
+        self._parent_of.pop(root, None)
+        for frame_id in [f for f, s in self._session_of.items() if s == session]:
+            del self._session_of[frame_id]
+            self._page._worlds.forget(frame_id)
+
+    # -- geometry -------------------------------------------------------------------
+
+    async def frame_origin(self, frame: FrameRef) -> tuple[float, float]:
+        """Where ``frame``'s viewport starts, in the coordinates of its own session.
+
+        Zero for a session's top frame; for a same-process child, the content box of
+        its ``<iframe>``.
+        """
+        if frame.id == self._page.main_frame_id or frame.id in self._parent_of:
+            return 0.0, 0.0
+        return await self._owner_content(frame.session, frame.id)
+
+    async def viewport_offset(self, frame: FrameRef) -> tuple[float, float]:
+        """What to add to ``frame.session`` coordinates to get top-level viewport ones."""
+        x = y = 0.0
+        session = frame.session
+        seen: set[str] = set()
+        while session != self._page._session and session not in seen:
+            seen.add(session)
+            root = self._root_of.get(session)
+            parent = self._parent_of.get(root or "")
+            if root is None or parent is None:
+                break
+            dx, dy = await self._owner_content(parent, root)
+            x, y = x + dx, y + dy
+            session = parent
+        return x, y
+
+    async def _owner_content(self, session: str, frame_id: str) -> tuple[float, float]:
+        page = self._page
+        with contextlib.suppress(ProtocolError):
+            owner = await page._send_on(session, "DOM.getFrameOwner", {"frameId": frame_id})
+            box = await page._send_on(
+                session, "DOM.getBoxModel", {"backendNodeId": owner["backendNodeId"]}
+            )
+            content = box["model"]["content"]
+            return float(content[0]), float(content[1])
+        return 0.0, 0.0
diff --git a/src/lyra_browser/native/locator.py b/src/lyra_browser/native/locator.py
index 3e5fc0e..3906ac5 100644
--- a/src/lyra_browser/native/locator.py
+++ b/src/lyra_browser/native/locator.py
@@ -21,6 +21,7 @@
 import contextlib
 import itertools
 from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
 from pathlib import Path
 from typing import TYPE_CHECKING, Any
 
@@ -40,8 +41,10 @@
     STEP_JS,
 )
 from .selectors import Part, describe, parse
+from .snapshot import aria_snapshot as _snapshot
 
 if TYPE_CHECKING:
+    from .frames import FrameRef
     from .page import NativePage
 
 DEFAULT_TIMEOUT_MS = 30_000.0
@@ -60,6 +63,14 @@
 _groups = itertools.count(1)
 
 
+@dataclass(frozen=True)
+class _El:
+    """A matched element: its remote object, and the frame (and session) it lives in."""
+
+    frame: FrameRef
+    object_id: str
+
+
 class _Retry:
     """Returned by an attempt that should be tried again."""
 
@@ -123,46 +134,76 @@ def locator(self, selector: str) -> Locator:
 
     # -- resolution ---------------------------------------------------------------
 
-    async def _resolve(self, group: str) -> tuple[str, list[str]]:
-        """The frame the elements live in, and the matched elements (isolated world)."""
+    async def _resolve(self, group: str) -> list[_El]:
+        """The matched elements, each with the frame it lives in (isolated world)."""
         page = self._page
-        frame_id = page.main_frame_id
+        frame = page._frame(page.main_frame_id)
         for frame_selector in self._frames:
-            owners = await self._run(frame_id, [*parse(frame_selector), Part("nth", "0")], group)
+            owners = await self._run(frame, [*parse(frame_selector), Part("nth", "0")], group)
             if not owners:
-                return frame_id, []
-            node = (await page._send("DOM.describeNode", {"objectId": owners[0]}))["node"]
+                return []
+            node = (
+                await page._send_on(frame.session, "DOM.describeNode", {"objectId": owners[0]})
+            )["node"]
             child = node.get("frameId")
             if not child or node.get("nodeName", "").upper() not in ("IFRAME", "FRAME"):
                 raise Error(f"Selector {describe(frame_selector)} does not match an <iframe>")
-            frame_id = child
-        return frame_id, await self._run(frame_id, parse(self._selector), group)
+            frame = page._frame(child)
+        steps = parse(self._selector)
+        start: list[str] | None = None
+        if steps and steps[0].engine == "aria-ref":
+            if self._frames:
+                raise Error(f"aria-ref cannot be used inside a frame locator: {self._selector}")
+            target = page._ref_target(steps[0].body)
+            if target is None:
+                return []
+            frame, backend = target
+            context_id = await page._context_id(frame.id)
+            try:
+                resolved = await page._send_on(
+                    frame.session,
+                    "DOM.resolveNode",
+                    {
+                        "backendNodeId": backend,
+                        "executionContextId": context_id,
+                        "objectGroup": group,
+                    },
+                )
+            except ProtocolError as exc:
+                if _is_detached(exc):
+                    return []
+                raise
+            start, steps = [resolved["object"]["objectId"]], steps[1:]
+        elif any(step.engine == "aria-ref" for step in steps):
+            raise Error(f"aria-ref has to start the selector: {self._selector}")
+        return [_El(frame, oid) for oid in await self._run(frame, steps, group, start)]
 
-    async def _run(self, frame_id: str, steps: list[Part], group: str) -> list[str]:
+    async def _run(
+        self, frame: FrameRef, steps: list[Part], group: str, start: list[str] | None = None
+    ) -> list[str]:
         page = self._page
-        context_id = await page._context_id(frame_id)
-        current: list[str] | None = None
+        context_id = await page._context_id(frame.id)
+        current: list[str] | None = start
         for step in steps:
             if step.engine == "nth":
                 items = current or []
                 index = int(step.body)
                 current = [items[index]] if -len(items) <= index < len(items) else []
             elif step.engine == "role":
-                current = await self._role_step(context_id, step, current, group)
-            elif step.engine == "aria-ref":
-                current = await page._resolve_ref(step.body, frame_id, context_id, group)
+                current = await self._role_step(frame, context_id, step, current, group)
             else:
-                current = await self._js_step(context_id, step, current, group)
+                current = await self._js_step(frame, context_id, step, current, group)
             if not current:
                 return []
         return current or []
 
     async def _js_step(
-        self, context_id: int, step: Part, scopes: list[str] | None, group: str
+        self, frame: FrameRef, context_id: int, step: Part, scopes: list[str] | None, group: str
     ) -> list[str]:
         page = self._page
         arguments = [{"value": step.as_js()}, *({"objectId": o} for o in scopes or ())]
-        reply = await page._send(
+        reply = await page._send_on(
+            frame.session,
             "Runtime.callFunctionOn",
             {
                 "functionDeclaration": STEP_JS,
@@ -177,8 +218,8 @@ async def _js_step(
         array_id = (reply.get("result") or {}).get("objectId")
         if not array_id:
             return []
-        props = await page._send(
-            "Runtime.getProperties", {"objectId": array_id, "ownProperties": True}
+        props = await page._send_on(
+            frame.session, "Runtime.getProperties", {"objectId": array_id, "ownProperties": True}
         )
         items = [
             (int(p["name"]), p["value"]["objectId"])
@@ -188,11 +229,12 @@ async def _js_step(
         return [object_id for _i, object_id in sorted(items)]
 
     async def _role_step(
-        self, context_id: int, step: Part, scopes: list[str] | None, group: str
+        self, frame: FrameRef, context_id: int, step: Part, scopes: list[str] | None, group: str
     ) -> list[str]:
         page = self._page
         if scopes is None:
-            reply = await page._send(
+            reply = await page._send_on(
+                frame.session,
                 "Runtime.evaluate",
                 {"expression": "document", "contextId": context_id, "objectGroup": group},
             )
@@ -201,8 +243,10 @@ async def _role_step(
         seen: set[int] = set()
         for scope in scopes:
             nodes = (
-                await page._send(
-                    "Accessibility.queryAXTree", {"objectId": scope, "role": step.role}
+                await page._send_on(
+                    frame.session,
+                    "Accessibility.queryAXTree",
+                    {"objectId": scope, "role": step.role},
                 )
             ).get("nodes", [])
             for node in nodes:
@@ -217,7 +261,8 @@ async def _role_step(
                 if not _states_match(node, step.states):
                     continue
                 seen.add(backend)
-                resolved = await page._send(
+                resolved = await page._send_on(
+                    frame.session,
                     "DOM.resolveNode",
                     {
                         "backendNodeId": backend,
@@ -231,13 +276,14 @@ async def _role_step(
     # -- helpers on one element -----------------------------------------------------
 
     async def _call(
-        self, element: str, source: str, *args: Any, by_value: bool = True, api: str = "Locator"
+        self, element: _El, source: str, *args: Any, by_value: bool = True, api: str = "Locator"
     ) -> Any:
-        reply = await self._page._send(
+        reply = await self._page._send_on(
+            element.frame.session,
             "Runtime.callFunctionOn",
             {
                 "functionDeclaration": source,
-                "objectId": element,
+                "objectId": element.object_id,
                 "arguments": [call_argument(a) for a in args],
                 "returnByValue": by_value,
                 "awaitPromise": True,
@@ -245,13 +291,24 @@ async def _call(
         )
         return decode_result(api, reply)
 
-    async def _point(self, element: str) -> tuple[float, float] | None:
+    async def _quads(self, element: _El) -> list[list[float]]:
+        """The element's content quads in top-level viewport coordinates."""
+        page = self._page
+        quads = (
+            await page._send_on(
+                element.frame.session, "DOM.getContentQuads", {"objectId": element.object_id}
+            )
+        ).get("quads", [])
+        if quads and element.frame.session != page._session:
+            dx, dy = await page._frame_map.viewport_offset(element.frame)
+            quads = [[v + (dx if i % 2 == 0 else dy) for i, v in enumerate(q)] for q in quads]
+        return quads
+
+    async def _point(self, element: _El) -> tuple[float, float] | None:
         """The centre of the element in viewport coordinates, if it is inside the viewport."""
         page = self._page
         try:
-            quads = (await page._send("DOM.getContentQuads", {"objectId": element})).get(
-                "quads", []
-            )
+            quads = await self._quads(element)
         except ProtocolError as exc:
             if _is_detached(exc):
                 raise
@@ -268,9 +325,13 @@ async def _point(self, element: str) -> tuple[float, float] | None:
             return None
         return x, y
 
-    async def _scroll_into_view(self, element: str) -> None:
+    async def _scroll_into_view(self, element: _El) -> None:
         with contextlib.suppress(ProtocolError):
-            await self._page._send("DOM.scrollIntoViewIfNeeded", {"objectId": element})
+            await self._page._send_on(
+                element.frame.session,
+                "DOM.scrollIntoViewIfNeeded",
+                {"objectId": element.object_id},
+            )
 
     # -- the retry loop -----------------------------------------------------------
 
@@ -278,11 +339,11 @@ async def _attempts(
         self,
         api: str,
         timeout: float | None,
-        attempt: Callable[[str, str, list[str]], Awaitable[Any]],
+        attempt: Callable[[_El | None, list[str]], Awaitable[Any]],
         *,
         need_element: bool = True,
     ) -> Any:
-        """Resolve and run ``attempt(frame_id, element, log)`` until it is not ``RETRY``."""
+        """Resolve and run ``attempt(element, log)`` until it is not ``RETRY``."""
         page = self._page
         loop = asyncio.get_running_loop()
         timeout_ms = DEFAULT_TIMEOUT_MS if timeout is None else float(timeout)
@@ -291,9 +352,9 @@ async def _attempts(
         for round_no in itertools.count():
             group = f"lyra-{next(_groups)}"
             try:
-                frame_id, elements = await self._resolve(group)
+                elements = await self._resolve(group)
                 if elements or not need_element:
-                    result = await attempt(frame_id, elements[0] if elements else "", log)
+                    result = await attempt(elements[0] if elements else None, log)
                     if result is not RETRY:
                         return result
             except ProtocolError as exc:
@@ -309,13 +370,13 @@ async def _attempts(
             await asyncio.sleep(max(0.0, min(delay, deadline - loop.time())))
         raise AssertionError("unreachable")
 
-    async def _state(self, element: str, log: list[str]) -> dict:
+    async def _state(self, element: _El, log: list[str]) -> dict:
         state = await self._call(element, STATE_JS)
         _note(log, f"  - locator resolved to {state.get('html', '')}", once=True)
         return state
 
     async def _ready(
-        self, element: str, log: list[str], *, enabled: bool = False, editable: bool = False
+        self, element: _El, log: list[str], *, enabled: bool = False, editable: bool = False
     ) -> bool:
         state = await self._state(element, log)
         if not state.get("connected"):
@@ -333,7 +394,7 @@ async def _ready(
         return True
 
     async def _pointer(
-        self, element: str, log: list[str], action: str, *, enabled: bool
+        self, element: _El, log: list[str], action: str, *, enabled: bool
     ) -> tuple[float, float] | _Retry:
         """Every check a pointer action makes, and the point it acts at."""
         if not await self._ready(element, log, enabled=enabled):
@@ -361,8 +422,7 @@ async def _pointer(
     async def count(self) -> int:
         group = f"lyra-{next(_groups)}"
         try:
-            _frame, elements = await self._resolve(group)
-            return len(elements)
+            return len(await self._resolve(group))
         except ProtocolError as exc:
             if _is_detached(exc):
                 self._page._worlds.clear()
@@ -374,7 +434,7 @@ async def count(self) -> int:
     async def is_visible(self) -> bool:
         group = f"lyra-{next(_groups)}"
         try:
-            _frame, elements = await self._resolve(group)
+            elements = await self._resolve(group)
             if not elements:
                 return False
             return bool((await self._call(elements[0], STATE_JS)).get("visible"))
@@ -382,13 +442,13 @@ async def is_visible(self) -> bool:
             self._page._release_group(group)
 
     async def is_enabled(self, *, timeout: float | None = None) -> bool:
-        async def attempt(_frame: str, element: str, log: list[str]) -> bool:
+        async def attempt(element: _El, log: list[str]) -> bool:
             return bool((await self._state(element, log)).get("enabled"))
 
         return await self._attempts("Locator.is_enabled", timeout, attempt)
 
     async def click(self, *, timeout: float | None = None, **_ignored: Any) -> None:
-        async def attempt(_frame: str, element: str, log: list[str]) -> Any:
+        async def attempt(element: _El, log: list[str]) -> Any:
             point = await self._pointer(element, log, "click", enabled=True)
             if point is RETRY:
                 return RETRY
@@ -399,7 +459,7 @@ async def attempt(_frame: str, element: str, log: list[str]) -> Any:
         await self._attempts("Locator.click", timeout, attempt)
 
     async def hover(self, *, timeout: float | None = None, **_ignored: Any) -> None:
-        async def attempt(_frame: str, element: str, log: list[str]) -> Any:
+        async def attempt(element: _El, log: list[str]) -> Any:
             point = await self._pointer(element, log, "hover", enabled=False)
             if point is RETRY:
                 return RETRY
@@ -412,7 +472,7 @@ async def attempt(_frame: str, element: str, log: list[str]) -> Any:
     async def fill(self, value: str, *, timeout: float | None = None, **_ignored: Any) -> None:
         api = "Locator.fill"
 
-        async def attempt(_frame: str, element: str, log: list[str]) -> Any:
+        async def attempt(element: _El, log: list[str]) -> Any:
             if not await self._ready(element, log, enabled=True, editable=True):
                 return RETRY
             prepared = await self._call(element, FILL_JS, api=api)
@@ -430,7 +490,7 @@ async def attempt(_frame: str, element: str, log: list[str]) -> Any:
         await self._attempts(api, timeout, attempt)
 
     async def press(self, key: str, *, timeout: float | None = None, **_ignored: Any) -> None:
-        async def attempt(_frame: str, element: str, log: list[str]) -> Any:
+        async def attempt(element: _El, log: list[str]) -> Any:
             await self._call(element, FOCUS_JS)
             await self._page.keyboard.press(key)
             return None
@@ -440,7 +500,7 @@ async def attempt(_frame: str, element: str, log: list[str]) -> Any:
     async def check(self, *, timeout: float | None = None, **_ignored: Any) -> None:
         api = "Locator.check"
 
-        async def attempt(_frame: str, element: str, log: list[str]) -> Any:
+        async def attempt(element: _El, log: list[str]) -> Any:
             state = await self._state(element, log)
             if state.get("checked") is None:
                 raise Error(with_call_log(api, "Error: Not a checkbox or radio button", log))
@@ -477,7 +537,7 @@ async def select_option(
         else:
             raise Error(f"{api}: no option to select was given")
 
-        async def attempt(_frame: str, element: str, log: list[str]) -> Any:
+        async def attempt(element: _El, log: list[str]) -> Any:
             if not await self._ready(element, log, enabled=True):
                 return RETRY
             result = await self._call(element, SELECT_JS, want, api=api)
@@ -491,7 +551,7 @@ async def attempt(_frame: str, element: str, log: list[str]) -> Any:
         return await self._attempts(api, timeout, attempt)
 
     async def input_value(self, *, timeout: float | None = None) -> str:
-        async def attempt(_frame: str, element: str, log: list[str]) -> str:
+        async def attempt(element: _El, log: list[str]) -> str:
             return str(await self._call(element, INPUT_VALUE_JS, api="Locator.input_value"))
 
         return await self._attempts("Locator.input_value", timeout, attempt)
@@ -503,19 +563,21 @@ async def set_input_files(
         paths = [files] if isinstance(files, (str, Path)) else list(files)
         resolved = [str(Path(p).resolve()) for p in paths]
 
-        async def attempt(_frame: str, element: str, log: list[str]) -> Any:
+        async def attempt(element: _El, log: list[str]) -> Any:
             problem = await self._call(element, FILE_INPUT_JS, len(resolved), api=api)
             if problem:
                 raise Error(with_call_log(api, f"Error: {problem}", log))
-            await self._page._send(
-                "DOM.setFileInputFiles", {"files": resolved, "objectId": element}
+            await self._page._send_on(
+                element.frame.session,
+                "DOM.setFileInputFiles",
+                {"files": resolved, "objectId": element.object_id},
             )
             return None
 
         await self._attempts(api, timeout, attempt)
 
     async def inner_text(self, *, timeout: float | None = None) -> str:
-        async def attempt(_frame: str, element: str, log: list[str]) -> str:
+        async def attempt(element: _El, log: list[str]) -> str:
             return str(await self._call(element, INNER_TEXT_JS, api="Locator.inner_text") or "")
 
         return await self._attempts("Locator.inner_text", timeout, attempt)
@@ -534,19 +596,23 @@ async def evaluate(
             expression if is_function(expression) else f"function () {{ return ({expression}); }}"
         )
 
-        async def attempt(_frame: str, element: str, log: list[str]) -> Any:
-            target = element
+        async def attempt(element: _El, log: list[str]) -> Any:
+            session = element.frame.session
+            target = element.object_id
             if world == MAIN:
-                node = (await self._page._send("DOM.describeNode", {"objectId": element}))["node"]
+                node = (
+                    await self._page._send_on(session, "DOM.describeNode", {"objectId": target})
+                )["node"]
                 target = (
-                    await self._page._send(
-                        "DOM.resolveNode", {"backendNodeId": node["backendNodeId"]}
+                    await self._page._send_on(
+                        session, "DOM.resolveNode", {"backendNodeId": node["backendNodeId"]}
                     )
                 )["object"]["objectId"]
             arguments = [{"objectId": target}]
             if arg is not NO_ARG:
                 arguments.append(call_argument(arg))
-            reply = await self._page._send(
+            reply = await self._page._send_on(
+                session,
                 "Runtime.callFunctionOn",
                 {
                     "functionDeclaration": source,
@@ -562,10 +628,14 @@ async def attempt(_frame: str, element: str, log: list[str]) -> Any:
         return await self._attempts(api, timeout, attempt)
 
     async def scroll_into_view_if_needed(self, *, timeout: float | None = None) -> None:
-        async def attempt(_frame: str, element: str, log: list[str]) -> Any:
+        async def attempt(element: _El, log: list[str]) -> Any:
             if not await self._ready(element, log):
                 return RETRY
-            await self._page._send("DOM.scrollIntoViewIfNeeded", {"objectId": element})
+            await self._page._send_on(
+                element.frame.session,
+                "DOM.scrollIntoViewIfNeeded",
+                {"objectId": element.object_id},
+            )
             return None
 
         await self._attempts("Locator.scroll_into_view_if_needed", timeout, attempt)
@@ -573,13 +643,11 @@ async def attempt(_frame: str, element: str, log: list[str]) -> Any:
     async def screenshot(self, *, timeout: float | None = None, **_ignored: Any) -> bytes:
         api = "Locator.screenshot"
 
-        async def attempt(_frame: str, element: str, log: list[str]) -> Any:
+        async def attempt(element: _El, log: list[str]) -> Any:
             if not await self._ready(element, log):
                 return RETRY
             await self._scroll_into_view(element)
-            quads = (await self._page._send("DOM.getContentQuads", {"objectId": element})).get(
-                "quads", []
-            )
+            quads = await self._quads(element)
             if not quads:
                 _note(log, "  - element is not visible")
                 return RETRY
@@ -612,8 +680,8 @@ async def wait_for(self, *, state: str = "visible", timeout: float | None = None
         if state not in ("attached", "detached", "visible", "hidden"):
             raise Error(f"{api}: state: expected one of (attached|detached|visible|hidden)")
 
-        async def attempt(_frame: str, element: str, log: list[str]) -> Any:
-            if not element:
+        async def attempt(element: _El | None, log: list[str]) -> Any:
+            if element is None:
                 return None if state in ("detached", "hidden") else RETRY
             if state == "attached":
                 return None
@@ -624,8 +692,37 @@ async def attempt(_frame: str, element: str, log: list[str]) -> Any:
 
         await self._attempts(api, timeout, attempt, need_element=False)
 
-    async def aria_snapshot(self, *, timeout: float | None = None) -> str:
-        raise Error("Locator.aria_snapshot is not implemented by the native driver yet")
+    async def aria_snapshot(
+        self,
+        *,
+        timeout: float | None = None,
+        depth: int | None = None,
+        mode: str | None = None,
+        boxes: bool = False,
+    ) -> str:
+        """Playwright's YAML snapshot of this element's subtree (see ``snapshot.py``).
+
+        ``mode="ai"`` adds refs and replaces the page's ref table; ``boxes`` adds geometry.
+        The keyword names are what ``read_page`` feature-detects.
+        """
+        page = self._page
+
+        async def attempt(element: _El, log: list[str]) -> str:
+            node = (
+                await page._send_on(
+                    element.frame.session, "DOM.describeNode", {"objectId": element.object_id}
+                )
+            )["node"]
+            return await _snapshot(
+                page,
+                element.frame,
+                node.get("backendNodeId"),
+                refs=mode == "ai",
+                boxes=boxes,
+                depth=depth,
+            )
+
+        return await self._attempts("Locator.aria_snapshot", timeout, attempt)
 
 
 def _note(log: list[str], line: str, *, once: bool = False) -> None:
diff --git a/src/lyra_browser/native/page.py b/src/lyra_browser/native/page.py
index 9b3b267..1a27415 100644
--- a/src/lyra_browser/native/page.py
+++ b/src/lyra_browser/native/page.py
@@ -35,6 +35,7 @@
     is_function,
     is_stale_context,
 )
+from .frames import FrameRef, FrameTracker
 from .input import Keyboard, Mouse
 from .locator import FrameLocator, Locator
 
@@ -103,6 +104,9 @@ def __init__(
         self._failed_loads: dict[str, str] = {}
         self.keyboard = Keyboard(self)
         self.mouse = Mouse(self, self.keyboard)
+        self._frame_map = FrameTracker(self)
+        # aria-ref -> (frame id, backend node id), from the latest snapshot only.
+        self._refs: dict[str, tuple[str, int]] = {}
 
     # -- plumbing -------------------------------------------------------------------
 
@@ -130,6 +134,17 @@ async def _send(
             method, params, session=self._session, timeout=timeout
         )
 
+    async def _send_on(
+        self, session: str, method: str, params: dict | None = None, *, timeout: float | None = None
+    ) -> dict:
+        """A command to one of this page's sessions (its own, or an OOPIF's)."""
+        if self._closed:
+            raise TargetClosedError()
+        return await self._context._conn.send(method, params, session=session, timeout=timeout)
+
+    def _frame(self, frame_id: str) -> FrameRef:
+        return self._frame_map.frame(frame_id)
+
     def _on(self, method: str, handler: Callable[[dict], None]) -> None:
         self._context._conn.on(method, lambda params, _s: handler(params), session=self._session)
 
@@ -182,6 +197,7 @@ async def _initialize(
                 self._send("Emulation.setDeviceMetricsOverride", metrics, timeout=INIT_TIMEOUT_S)
             )
         await asyncio.gather(*commands)
+        await self._frame_map.watch(self._session)
         tree = await self._send("Page.getFrameTree", timeout=INIT_TIMEOUT_S)
         self._absorb_tree(tree.get("frameTree") or {})
 
@@ -451,8 +467,11 @@ async def _context_id(self, frame_id: str) -> int:
         cached = self._worlds.get(frame_id)
         if cached is not None:
             return cached
-        reply = await self._send(
-            "Page.createIsolatedWorld", {"frameId": frame_id, "worldName": UTILITY_WORLD}
+        frame = self._frame(frame_id)
+        reply = await self._send_on(
+            frame.session,
+            "Page.createIsolatedWorld",
+            {"frameId": frame_id, "worldName": UTILITY_WORLD},
         )
         context_id = int(reply["executionContextId"])
         self._worlds.put(frame_id, context_id)
@@ -528,9 +547,19 @@ def locator(self, selector: str) -> Locator:
     def frame_locator(self, selector: str) -> FrameLocator:
         return FrameLocator(self, (selector,))
 
-    async def _resolve_ref(self, ref: str, frame_id: str, context_id: int, group: str) -> list[str]:
-        """The element an ``aria-ref`` names (filled in by the snapshot phase)."""
-        return []
+    def _ref_target(self, ref: str) -> tuple[FrameRef, int] | None:
+        """The frame and node an ``aria-ref`` of the latest snapshot names, or None.
+
+        A ref into a frame that is gone raises, worded as Playwright words it
+        (``describe_failure`` reads "aria-ref selector" as a missing element).
+        """
+        target = self._refs.get(ref)
+        if target is None:
+            return None
+        frame_id, backend = target
+        if frame_id != self.main_frame_id and not self._frame_map.knows(frame_id):
+            raise Error(f'Error: Invalid frame in aria-ref selector "aria-ref={ref}"')
+        return self._frame(frame_id), backend
 
     def _release_group(self, group: str) -> None:
         """Drop the remote objects one locator attempt created; nobody waits for it."""
diff --git a/src/lyra_browser/native/snapshot.py b/src/lyra_browser/native/snapshot.py
new file mode 100644
index 0000000..329a6f6
--- /dev/null
+++ b/src/lyra_browser/native/snapshot.py
@@ -0,0 +1,233 @@
+"""``aria_snapshot``: Chrome's accessibility tree, written the way Playwright writes its own.
+
+``read_page(mode="tree")`` reads Playwright's ``aria_snapshot(mode="ai", boxes=True)``
+through ``tools.reading.compact_snapshot``. This produces the same text from
+``Accessibility.getFullAXTree``, frame by frame (an out-of-process iframe through its own
+session), so the reader does not change:
+
+    - button "Save" [disabled] [ref=e12] [box=964,128,46,22]
+    - link "Home" [ref=e3] [box=8,8,40,20]
+      - /url: /home
+    - iframe [ref=e31] [box=269,337,404,124]
+      - button "Inner" [ref=f1e2] [box=8,8,120,22]
+
+- Roles are Chrome's computed ARIA roles; the few internal ones it adds are mapped back
+  (``MenuListOption`` is an ``option``, ``StaticText`` a ``text``) or skipped.
+- ``box`` is the element's content box in its own frame's viewport (CSS pixels), as
+  Playwright gives it; ``compact_snapshot`` adds the frame offsets itself.
+- A ref goes to every rendered node with a non-empty box, ``e<n>`` in the top frame and
+  ``f<k>e<n>`` in the k-th frame met. Refs belong to the latest snapshot: taking one
+  replaces the page's ref table, which ``aria-ref=`` selectors resolve against.
+
+Measured in the phase-0 spike: 324 of 324 listed elements matched Playwright's (role,
+name, states, href) on a page with forms, a same-site and a cross-site iframe, an open
+shadow root, Korean text and a 300-button list.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from typing import TYPE_CHECKING
+
+from .errors import ProtocolError
+
+if TYPE_CHECKING:
+    from .frames import FrameRef
+    from .page import NativePage
+
+# Chrome's internal roles, mapped to what Playwright prints, or None to print nothing
+# (the children are kept, one level up).
+_ROLE_MAP: dict[str, str | None] = {
+    "MenuListOption": "option",
+    "MenuListPopup": None,
+    "RootWebArea": None,
+    "WebArea": None,
+    "StaticText": "text",
+    "InlineTextBox": None,
+    "LineBreak": None,
+    "LabelText": None,
+    "DisclosureTriangle": "group",
+    "Iframe": "iframe",
+    "IframePresentational": "iframe",
+    "image": "img",
+    "generic": "generic",
+    "none": None,
+    "ListMarker": None,
+}
+# Nodes that get neither a ref nor a box: text runs, and wrappers nobody acts on.
+_NO_REF = frozenset({"text"})
+_STATES = ("checked", "disabled", "expanded", "pressed", "selected", "level")
+
+
+def _prop(node: dict, name: str):
+    for prop in node.get("properties", ()):
+        if prop.get("name") == name:
+            return (prop.get("value") or {}).get("value")
+    return None
+
+
+def _states(node: dict) -> list[str]:
+    out = []
+    for state in _STATES:
+        value = _prop(node, state)
+        if value is None or value is False or value == "false":
+            continue
+        out.append(state if value is True or value == "true" else f"{state}={value}")
+    return out
+
+
+class _Builder:
+    def __init__(self, page: NativePage, *, refs: bool, boxes: bool, depth: int | None) -> None:
+        self._page = page
+        self._refs = refs
+        self._boxes = boxes
+        self._depth = depth
+        self._frames_seen = 0
+        self.table: dict[str, tuple[str, int]] = {}
+
+    async def frame(
+        self, frame: FrameRef, root_backend: int | None, prefix: str, indent: int
+    ) -> list[str]:
+        page = self._page
+        params = {} if page._frame_map.is_out_of_process(frame.id) else {"frameId": frame.id}
+        try:
+            nodes = (await page._send_on(frame.session, "Accessibility.getFullAXTree", params)).get(
+                "nodes", []
+            )
+        except ProtocolError:
+            return []
+        if not nodes:
+            return []
+        by_id = {n["nodeId"]: n for n in nodes}
+        root = None
+        if root_backend is not None:
+            root = next((n for n in nodes if n.get("backendDOMNodeId") == root_backend), None)
+        if root is None:
+            root = next((n for n in nodes if "parentId" not in n), nodes[0])
+
+        # Pass 1: which nodes print, at which depth.
+        printed: list[tuple[dict, str, int]] = []
+
+        def walk(node: dict, depth: int) -> None:
+            role = node.get("role", {}).get("value", "")
+            mapped = _ROLE_MAP.get(role, role)
+            below = depth
+            if not node.get("ignored") and mapped:
+                printed.append((node, mapped, depth))
+                below = depth + 1
+            if mapped == "iframe" or (self._depth is not None and below - indent > self._depth):
+                return
+            for child_id in node.get("childIds", ()):
+                child = by_id.get(child_id)
+                if child is not None:
+                    walk(child, below)
+
+        walk(root, indent)
+
+        # Pass 2: boxes (one round, concurrently) and the frames iframes own.
+        origin = await page._frame_map.frame_origin(frame)
+        boxed = [n for n, role, _d in printed if role not in _NO_REF and n.get("backendDOMNodeId")]
+        links = [n for n, role, _d in printed if role == "link" and n.get("backendDOMNodeId")]
+        quads, hrefs = await asyncio.gather(
+            asyncio.gather(*(self._box(frame, n["backendDOMNodeId"], origin) for n in boxed)),
+            asyncio.gather(*(self._href(frame, n["backendDOMNodeId"]) for n in links)),
+        )
+        box_of = {id(n): q for n, q in zip(boxed, quads, strict=True)}
+        href_of = {id(n): h for n, h in zip(links, hrefs, strict=True)}
+
+        lines: list[str] = []
+        counter = 0
+        for node, role, depth in printed:
+            name = (node.get("name") or {}).get("value", "") or ""
+            if role == "iframe":
+                name = ""  # Playwright names a frame by its content, not its title
+            attrs = _states(node)
+            box = box_of.get(id(node))
+            backend = node.get("backendDOMNodeId")
+            if box is not None:
+                if self._refs:
+                    counter += 1
+                    ref = f"{prefix}e{counter}"
+                    attrs.append(f"ref={ref}")
+                    self.table[ref] = (frame.id, backend)
+                if self._boxes:
+                    attrs.append("box=" + ",".join(str(round(v)) for v in box))
+            key = role + (f" {json.dumps(str(name), ensure_ascii=False)}" if name else "")
+            key += "".join(f" [{a}]" for a in attrs)
+            lines.append(f"{'  ' * depth}- {key}")
+            url = href_of.get(id(node)) or _prop(node, "url")
+            if role == "link" and url:
+                lines.append(f"{'  ' * (depth + 1)}- /url: {url}")
+            if role == "iframe" and backend:
+                lines.extend(await self._child_frame(frame, backend, depth + 1))
+        return lines
+
+    async def _child_frame(self, frame: FrameRef, backend: int, indent: int) -> list[str]:
+        page = self._page
+        try:
+            node = (
+                await page._send_on(frame.session, "DOM.describeNode", {"backendNodeId": backend})
+            )["node"]
+        except ProtocolError:
+            return []
+        child_id = node.get("frameId")
+        if not child_id:
+            return []
+        self._frames_seen += 1
+        return await self.frame(page._frame(child_id), None, f"f{self._frames_seen}", indent)
+
+    async def _href(self, frame: FrameRef, backend: int) -> str | None:
+        """A link's ``href`` as written, which is what Playwright prints (Chrome's tree has
+        the resolved URL)."""
+        try:
+            node = (
+                await self._page._send_on(
+                    frame.session, "DOM.describeNode", {"backendNodeId": backend}
+                )
+            )["node"]
+        except ProtocolError:
+            return None
+        attrs = node.get("attributes") or []
+        for name, value in zip(attrs[0::2], attrs[1::2], strict=False):
+            if name == "href":
+                return value
+        return None
+
+    async def _box(
+        self, frame: FrameRef, backend: int, origin: tuple[float, float]
+    ) -> tuple[float, float, float, float] | None:
+        try:
+            quads = (
+                await self._page._send_on(
+                    frame.session, "DOM.getContentQuads", {"backendNodeId": backend}
+                )
+            ).get("quads", [])
+        except ProtocolError:
+            return None
+        if not quads:
+            return None
+        xs = quads[0][0::2]
+        ys = quads[0][1::2]
+        x, y = min(xs), min(ys)
+        width, height = max(xs) - x, max(ys) - y
+        if width <= 0 or height <= 0:
+            return None
+        return x - origin[0], y - origin[1], width, height
+
+
+async def aria_snapshot(
+    page: NativePage,
+    frame: FrameRef,
+    root_backend: int | None,
+    *,
+    refs: bool,
+    boxes: bool,
+    depth: int | None = None,
+) -> str:
+    """The snapshot of ``root_backend``'s subtree; with ``refs``, the page's new ref table."""
+    builder = _Builder(page, refs=refs, boxes=boxes, depth=depth)
+    lines = await builder.frame(frame, root_backend, "", 0)
+    if refs:
+        page._refs = builder.table
+    return "\n".join(lines)
diff --git a/tests/native/test_native_snapshot_frames.py b/tests/native/test_native_snapshot_frames.py
new file mode 100644
index 0000000..561a066
--- /dev/null
+++ b/tests/native/test_native_snapshot_frames.py
@@ -0,0 +1,117 @@
+"""The snapshot writer's node rules and the frame tracker's session and offset bookkeeping.
+
+The tree itself is compared against Playwright's in a real browser
+(``testing/native_tree_parity_261023_v1.py``: 75 of 75 elements and the same in-view
+order, refs acted on in a same-site and a cross-site iframe). These pin the parts that
+decide what that comparison sees.
+"""
+
+from __future__ import annotations
+
+import asyncio
+
+from lyra_browser.native.frames import FrameRef, FrameTracker
+from lyra_browser.native.snapshot import _ROLE_MAP, _states
+from lyra_browser.tools.reading import compact_snapshot
+
+
+def _node(**props) -> dict:
+    return {"properties": [{"name": k, "value": {"value": v}} for k, v in props.items()]}
+
+
+def test_states_print_as_playwright_prints_them():
+    assert _states(_node(checked="true", level=1, disabled=False)) == ["checked", "level=1"]
+    assert _states(_node(checked="mixed")) == ["checked=mixed"]
+    assert _states(_node(expanded="false", pressed=True)) == ["pressed"]
+
+
+def test_chromes_internal_roles_map_to_what_the_reader_lists():
+    assert _ROLE_MAP["MenuListOption"] == "option"
+    assert _ROLE_MAP["StaticText"] == "text"
+    assert _ROLE_MAP["image"] == "img"
+    assert _ROLE_MAP["RootWebArea"] is None and _ROLE_MAP["InlineTextBox"] is None
+
+
+def test_the_written_format_reads_back_through_compact_snapshot():
+    raw = "\n".join(
+        [
+            '- heading "Title" [level=1] [ref=e1] [box=8,8,200,30]',
+            '- link "Home" [ref=e2] [box=8,40,40,20]',
+            "  - /url: /home",
+            '- button "Say \\"hi\\": now" [disabled] [ref=e3] [box=8,70,80,22]',
+            "- iframe [ref=e4] [box=300,0,400,100]",
+            '  - button "Inner" [ref=f1e1] [box=8,8,60,22]',
+            '- button "Far" [ref=e5] [box=8,2000,60,22]',
+        ]
+    )
+    tree = compact_snapshot(raw, refs=True, viewport=(1280, 800))
+    lines = tree.text.splitlines()
+    assert lines[:4] == [
+        'aria-ref=e1 heading "Title" [level=1]',
+        'aria-ref=e2 link "Home" -> /home',
+        'aria-ref=e3 button "Say \\"hi\\": now" [disabled]',
+        'aria-ref=f1e1 button "Inner"',
+    ]
+    assert tree.in_viewport == 4 and lines[-1] == 'aria-ref=e5 button "Far"'
+
+
+class _FakePage:
+    """What FrameTracker asks of a page: its session, its frames, and box answers."""
+
+    _session = "PAGE"
+    main_frame_id = "MAIN"
+
+    def __init__(self) -> None:
+        self.sent: list[tuple[str, str, dict]] = []
+
+        class Worlds:
+            def forget(self, _frame_id):
+                pass
+
+        self._worlds = Worlds()
+
+    def owns_frame(self, frame_id: str) -> bool:
+        return frame_id in {"MAIN", "SAME"}
+
+    async def _send_on(self, session: str, method: str, params: dict | None = None, **_kw) -> dict:
+        self.sent.append((session, method, params or {}))
+        if method == "DOM.getFrameOwner":
+            return {"backendNodeId": {"OOPIF": 7, "NESTED": 9}[params["frameId"]]}
+        if method == "DOM.getBoxModel":
+            offsets = {7: (100, 50), 9: (10, 5)}[params["backendNodeId"]]
+            x, y = offsets
+            return {"model": {"content": [x, y, x + 300, y, x + 300, y + 200, x, y + 200]}}
+        return {}
+
+
+def test_frames_route_to_their_session_and_offsets_add_up_across_processes(monkeypatch):
+    page = _FakePage()
+    tracker = FrameTracker(page)  # type: ignore[arg-type]
+    monkeypatch.setattr(asyncio, "ensure_future", lambda coro: (coro.close(), _done())[1])
+    tracker._on_attached(
+        {"targetInfo": {"type": "iframe", "targetId": "OOPIF"}, "sessionId": "S1"}, "PAGE"
+    )
+    tracker._on_attached(
+        {"targetInfo": {"type": "iframe", "targetId": "NESTED"}, "sessionId": "S2"}, "S1"
+    )
+
+    assert tracker.frame("MAIN") == FrameRef("MAIN", "PAGE")
+    assert tracker.frame("SAME") == FrameRef("SAME", "PAGE")
+    assert tracker.frame("NESTED") == FrameRef("NESTED", "S2")
+    assert tracker.is_out_of_process("OOPIF") and not tracker.is_out_of_process("SAME")
+
+    offset = asyncio.run(tracker.viewport_offset(tracker.frame("NESTED")))
+    assert offset == (110.0, 55.0)
+    assert asyncio.run(tracker.viewport_offset(tracker.frame("SAME"))) == (0.0, 0.0)
+
+    tracker._on_detached({"sessionId": "S2"})
+    assert tracker.frame("NESTED") == FrameRef("NESTED", "PAGE")
+    assert not tracker.knows("NESTED")
+
+
+def _done():
+    class Done:
+        def add_done_callback(self, _cb):
+            pass
+
+    return Done()