cdp-toolkit 2.6.0 → 2.7.0

package/CHANGELOG.md

@@ -5,6 +5,23 @@ All notable changes to cdp-toolkit are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.7.0] - 2026-09-15
+
+**Cross-origin iframes are now discoverable and addressable.** A visible out-of-process iframe used to be a silent hole: `take_snapshot` on the parent page stopped at a bare `Iframe` line with no hint that an entire interactable document lived behind it, `list_pages` hid the iframe's target by default, and the only way to drive it was to know that a raw target id from `list_pages {all:true}` happened to work. Now the snapshot marks the boundary, the docs say the target exists, and a `frame:` selector addresses it by URL. Verified live against Chrome 153 with a real cross-origin iframe: marker present in both snapshot modes, `evaluate_script`/`take_snapshot` drive the frame through both its target id and the new selector, and two iframes with the same URL produce an ambiguity error naming both ids instead of a silent first-match.
+
+### Added
+
+- **OOPIF markers in `take_snapshot`.** When an emitted `<iframe>` node owns an out-of-process (cross-origin) frame, its snapshot line now carries the frame's identity: `[4821] Iframe "Checkout" [frame="F405BF…" frameUrl="https://example.com/"]`. `frame` is the frame id, which IS the iframe's CDP target id — feed it straight back as `target` to any interaction tool. The marker appears in `interactiveOnly` mode too (an iframe at a process boundary is itself the interactable thing), while same-origin iframes are unchanged: their AX subtrees were already merged into the parent tree. Detection drives off the browser's target list correlated through `DOM.getFrameOwner` — deliberately not `Page.getFrameTree`, which omits out-of-process child frames on a page-level attachment (observed Chrome 153) — and is failure-soft end to end: any error in detection degrades to the pre-marker snapshot, never a failed call. (`src/cdp/driver.ts`, `test/iframe-markers.test.ts`)
+- **`frame:<url-substring>` target selector (Chrome).** Resolves against the browser's out-of-process iframe targets by URL substring, so an iframe is addressable without first correlating raw target ids out of `list_pages {all:true}`. Follows the `worker:` arm's rules: an empty needle matches nothing, more than one match is an ambiguity error naming every id+url (never a silent first-match), and a miss lists the live iframes and teaches that only out-of-process iframes appear as targets. Accepted by every tool whose `target` flows through the shared resolver (evaluate_script, take_snapshot, click, screenshot, …); `close_page`/`select_page`/`release_page`/`claim_page` refuse it with a page-only message, and Firefox refuses it with `unsupported` naming the `frame.targets` capability, same as `worker:`. A bare iframe target id still resolves everywhere it did before. (`src/frames.ts`, `src/client.ts`, `src/shared-tools.ts`, `src/bidi/driver.ts`, `test/frame-selector.test.ts`)
+
+### Documented
+
+- `list_pages {all:true}` now says it lists out-of-process iframes (not just workers/background pages) and that a returned non-page targetId is accepted as a bare id by any tool's `target` param — in the tool's deep doc, the manifest, the MCP server instructions, the README tools table and target-grammar bullet, the CLI help grammar, and the CONTRACT grammar rule. The snapshot doc names the cross-origin boundary and the marker. (`src/toolDocs.ts`, `src/mcp.ts`, `src/manifest.ts`, `README.md`, `CONTRACT.md`, `skills/using-cdp-toolkit/SKILL.md`)
+
+### Deferred
+
+- Recursing child-frame accessibility nodes into the parent snapshot is NOT in this release. `backendDOMNodeId` uids are per-renderer-process, so child-frame uids would collide with parent uids under every interaction tool's `DOM.resolveNode` — recursion requires session-aware uid namespacing across all nine interaction tools, plus a BiDi-side answer where no AX domain exists. The marker + `frame:` pair ships the discoverability without that surgery.
+
 ## [2.6.0] - 2026-09-15
 
 **Bun is now a first-class, CI-tested runtime, and the MCP server can serve streamable HTTP.** The package has always declared `engines.bun`, but nothing proved the server actually booted under Bun — or under Node, for that matter. This release pins both: the server and CLI run under Bun ≥ 1.1 or Node ≥ 22, importing `dist/mcp.js` / `dist/cli.js` as libraries is now silent (no server start, no CLI usage dump), and under Bun the same `mcp.js` entry can serve the full MCP surface over loopback HTTP with `--transport streamable-http` for hosts that launch it as an HTTP service instead of a stdio child.

package/CONTRACT.md

@@ -20,7 +20,7 @@ writing a module.
 
    **A worker-typed hit inside `resolveTarget` is the other deliberate exception, added in 1.9.0.** A `worker:<substring>` selector (Chrome only, capability `worker.targets`; one tool in 1.9.0, `evaluate_script` — four as of 1.9.1, see `WORKER_CAPABLE_TOOLS` in `src/workers.ts`) resolves to a service/shared worker target, and `resolveTarget` returns it before reaching `assertLeaseOk` — see the comment at the top of that branch in `src/client.ts`. A lease answers "who is driving this tab"; a worker is not a tab, has no reap-meaningful close, and strict-mode auto-acquire on it would mint a lease file keyed on an id that vanishes the moment Chrome idles the worker out, garbage the page-only reap set (`ReapInput.livePageIds`) can never collect. This also cannot be used to bypass a lease on an actual tab: there is no tab a worker resolution could stand in for. **The three console/network reader tools take a parallel path, not this one** — `resolveRecorderTarget`/`resolveWorkerSelector` in `src/tools/recorder.ts`/`src/cdp/workers.ts` — but the same reasoning holds: neither touches `assertLeaseOk`, tested by asserting zero lease files on a worker read with a page control in the same strict-mode window.
 
-   **The `TargetSelector` grammar itself also has three independent copies, a separate fact from the lease choke points above** — `pickTarget` (`src/client.ts`, what `resolveTarget` calls, and what most tools reach through), `pickPage` (`src/shared-tools.ts`), and `pickContext` (`src/bidi/driver.ts`, Firefox). A prefix arm added to one does not exist for callers routed through another; `label:` (1.9.0) was first wired into only `pickPage` and passed every unit test while `evaluate_script` still rejected it, because `evaluate_script` calls `pickTarget`, not `pickPage`, and only the live smoke caught the gap. The shared lookup core for an arm that needs identical semantics everywhere (as `label:` does) belongs in its own module — see `resolveLiveLabel` in `src/origins.ts` — wired into all three call sites, each keeping its own error class (`CdpError` / `SharedToolError` / `DriverError`). `test/manifest-grammar-drift.test.ts` structurally asserts a completeness property (every `title:` mention also mentions `label:`) and, separately, an exclusion property for `worker:` (only a tool in the `WORKER_CAPABLE_TOOLS` allowlist — four as of 1.9.1 — may name it) — grep `startsWith("title:")` across `src/` before adding a new arm, and extend or scope that test for it.
+   **The `TargetSelector` grammar itself also has three independent copies, a separate fact from the lease choke points above** — `pickTarget` (`src/client.ts`, what `resolveTarget` calls, and what most tools reach through), `pickPage` (`src/shared-tools.ts`), and `pickContext` (`src/bidi/driver.ts`, Firefox). A prefix arm added to one does not exist for callers routed through another; `label:` (1.9.0) was first wired into only `pickPage` and passed every unit test while `evaluate_script` still rejected it, because `evaluate_script` calls `pickTarget`, not `pickPage`, and only the live smoke caught the gap. The shared lookup core for an arm that needs identical semantics everywhere (as `label:` does) belongs in its own module — see `resolveLiveLabel` in `src/origins.ts` — wired into all three call sites, each keeping its own error class (`CdpError` / `SharedToolError` / `DriverError`). `test/manifest-grammar-drift.test.ts` structurally asserts a completeness property (every `title:` mention also mentions `label:`) and, separately, an exclusion property for `worker:` (only a tool in the `WORKER_CAPABLE_TOOLS` allowlist — four as of 1.9.1 — may name it) — grep `startsWith("title:")` across `src/` before adding a new arm, and extend or scope that test for it. `frame:<substr>` (OOPIF iframes) is Chrome-only like `worker:` but resolves through all three parsers with one deliberate asymmetry: an iframe targetId from an unfiltered `list_pages{all:true}` resolves as a bare 32-hex id everywhere, while `worker:` never matches an iframe.
 
 7. **Never dispatch `Input.*` outside `sendInput`.** As of 1.8.0 there is exactly one function that writes a synthesized input command to a Chrome connection: `sendInput(conn, backend, targetId, method, params)` in `src/activity.ts`. `CdpPageDriver.dispatchInput` (the per-driver choke point every interaction method already had to go through) delegates to it, and any tool built outside the Driver abstraction (`dispatch_mouse`, in `src/tools/dispatch-mouse.ts`, is the precedent) must call it directly rather than opening its own `conn.send("Input....", ...)`. This is what keeps the activity beacon's human/agent discrimination (`src/activity.ts`'s dispatch log) correct: a new input path that bypasses `sendInput` will typecheck, pass its own unit tests, and pass `bun test` in full, while silently making the toolkit's own input read as a human using the tab — exactly the 1.8.0 merge bug `test/input-dispatch-wiring.test.ts` now exists to catch (it walks every `.ts` under `src/`, strips comment-only lines, and fails on any line that both sends and names `Input.`). On the Firefox side, `BidiPageDriver.performActions` is the twin choke point and already calls `recordDispatch`; a new BiDi input path goes through it the same way `CdpPageDriver.dispatchInput` is used on Chrome. Mode-toggle commands that dispatch no page input themselves (`Input.setInterceptDrags`'s arm/disarm around HTML5 drag) are still sent through `sendInput` but are on a denylist that skips recording them — classify a new such command explicitly; the default for anything unclassified is to be logged, since over-warning a human is recoverable and silently misattributing their input to "agent" is not.
 

package/README.md

@@ -140,7 +140,7 @@ bun run mcp:smoke   # spawn the server + a real initialize/tools-list/tools-call
 
 Each point below leads with the symptom you've probably hit, then the cause, then the fix.
 
-- **Your agent stalls on a call when a busy background tab is open** → that's the **all-target fan-out**: every operation broadcasts to all attached targets. every cdp-toolkit call resolves *one* target (`active | index:N | url:<substr> | title:<substr> | label:<name> | <targetId>`) and attaches a single WebSocket to just that page, so a busy tab you did not name is never touched.
+- **Your agent stalls on a call when a busy background tab is open** → that's the **all-target fan-out**: every operation broadcasts to all attached targets. every cdp-toolkit call resolves *one* target (`active | index:N | url:<substr> | title:<substr> | label:<name> | <targetId>`, plus `frame:<substr>` for an out-of-process iframe, Chrome-only) and attaches a single WebSocket to just that page, so a busy tab you did not name is never touched.
 - **A tool hangs forever and never returns** → the MCP's eager `Network.enable` on a busy or hung renderer is a known wedge. cdp-toolkit enables domains **lazily**, only where a tool needs them (the recorder enables `Network`/`Runtime`/`Log`; most tools touch only `Page`/`Runtime`/`DOM`).
 - **No way to bound a slow call** → `CdpConnection.send()` enforces `CDP_TIMEOUT_MS` (15s default) on *every* command and **rejects rather than hangs**, so a stuck renderer can never block a caller indefinitely.
 - **Element handles drift across calls** → a `uid` **is** a CDP `backendDOMNodeId`, resolved on demand via `DOM.resolveNode`. There is no server-side handle table to drift or expire.
@@ -434,7 +434,7 @@ The 29 parity tools are 1:1 with `chrome-devtools-mcp`; the 19 superset tools (`
 
 | MCP name | CDP method(s) | Parity notes / gaps |
 |---|---|---|
-| `list_pages` | `GET /json/list` | `all` flag also exposes worker/background targets; MCP lists only page tabs. Each row additionally carries `origin` (`agent` or `unknown`, never `human`) plus `label`/`createdAt` for tabs this toolkit created, and, for a tab under an active lease of this backend, a `lease:{label,pid,idleMs,expiresAt,stale}` field (unconditional on `probe`). `probe:true` pings each page-type target's renderer (one bounded 500ms `Runtime.evaluate`, never more) and adds `responsive:boolean` plus `humanActiveMs` where that round trip found human-attributed input; a wedged/unreachable tab reports `responsive:false`, never an error for the whole call. Under `CDP_REQUIRE_LEASE` also reaps abandoned agent tabs first (destructively, only once a lease is `CDP_REAP_GRACE_MS` past its TTL — see "Staleness" below), reporting closures in an additive `reaped` array. |
+| `list_pages` | `GET /json/list` | `all` flag also exposes worker/background and out-of-process (OOPIF) iframe targets; MCP lists only page tabs. A non-page targetId from this listing is accepted by any tool's `target` param as a bare id, and `take_snapshot` marks a cross-origin iframe node with `frame:"<targetId>"` (input inside such an iframe is invisible to the activity beacon — see "Staleness" below — but the frame itself is fully driveable as its own target). Each row additionally carries `origin` (`agent` or `unknown`, never `human`) plus `label`/`createdAt` for tabs this toolkit created, and, for a tab under an active lease of this backend, a `lease:{label,pid,idleMs,expiresAt,stale}` field (unconditional on `probe`). `probe:true` pings each page-type target's renderer (one bounded 500ms `Runtime.evaluate`, never more) and adds `responsive:boolean` plus `humanActiveMs` where that round trip found human-attributed input; a wedged/unreachable tab reports `responsive:false`, never an error for the whole call. Under `CDP_REQUIRE_LEASE` also reaps abandoned agent tabs first (destructively, only once a lease is `CDP_REAP_GRACE_MS` past its TTL — see "Staleness" below), reporting closures in an additive `reaped` array. |
 | `new_page` | `Target.createTarget` (+ lease file) | Returns `{targetId,url}`; does not await navigation (use `navigate_page`). `claim:true` also claims the new tab and returns a `lease` token (`label`/`ttlMs` optional). Under `CDP_REQUIRE_LEASE` the tab is claimed and a `lease` returned even without `claim:true`. |
 | `close_page` | `Target.closeTarget` (+ lease file) | Reports `success:true` on the empty result newer Chromium returns. A successful close also releases that tab's lease; a failed close leaves it in place. |
 | `select_page` | `Target.activateTarget` + selected-state file | Writes a flat-file selected target; `resolveTarget` does not read it, so `active` still means `index:0` unless a tool opts in. |

package/dist/bidi/mux-daemon.js

@@ -689,6 +689,37 @@ var init_workers = __esm(() => {
   WORKER_SELECTOR_PAGE_ONLY_MESSAGE = "target 'worker:<substring>' selects a service/shared worker, and this tool is page-only " + "(closing, selecting or releasing a worker is meaningless). The tools that accept a worker: target are " + `${WORKER_CAPABLE_TOOLS.join(", ")}.`;
 });
 
+// src/frames.ts
+function isFrameSelector(selector) {
+  return typeof selector === "string" && selector.startsWith(FRAME_SELECTOR_PREFIX);
+}
+function frameNeedle(selector) {
+  return selector.slice(FRAME_SELECTOR_PREFIX.length);
+}
+function isFrameTargetType(type) {
+  return type === FRAME_TARGET_TYPE;
+}
+function resolveFrameTargets(targets, needle) {
+  const liveFrames = targets.filter((t) => isFrameTargetType(t.type));
+  return {
+    matches: needle === "" ? [] : liveFrames.filter((t) => t.url.includes(needle)),
+    liveFrames
+  };
+}
+function frameAmbiguityMessage(needle, matches) {
+  return `'frame:${needle}' matches more than one out-of-process iframe: ` + matches.map((m) => `${m.url} (${m.id})`).join(", ") + ". Narrow the substring, or pass the iframe's target id directly.";
+}
+function frameMissMessage(needle, liveFrames) {
+  const live = liveFrames.length ? ` (out-of-process iframes: ${liveFrames.map((f) => f.url).join(", ")})` : " (no out-of-process iframes are live)";
+  return `no out-of-process iframe whose url contains '${needle}'${live}. ` + "Only a CROSS-ORIGIN iframe gets its own process and therefore its own target; a same-origin iframe " + "runs inside its parent page and is NOT a target at all, so no substring can ever select it — reach a " + "same-origin iframe through its parent page instead (evaluate_script on the page, then the iframe " + "element's contentDocument). An out-of-process iframe whose document navigated away is likewise gone " + "from the listing: re-list with list_pages{all:true} and pass the new target id.";
+}
+var FRAME_SELECTOR_PREFIX = "frame:", FRAME_PAGE_ONLY_TOOLS, FRAME_TARGET_TYPE = "iframe", FRAME_EMPTY_NEEDLE_MESSAGE = "'frame:' needs a substring of the iframe's url, e.g. frame:ads.example.com or frame:player.html", FRAME_SELECTOR_UNSUPPORTED_MESSAGE, FRAME_SELECTOR_PAGE_ONLY_MESSAGE;
+var init_frames = __esm(() => {
+  FRAME_PAGE_ONLY_TOOLS = ["close_page", "select_page", "release_page", "claim_page"];
+  FRAME_SELECTOR_UNSUPPORTED_MESSAGE = "target 'frame:<substring>' selects an out-of-process iframe, which this backend cannot address " + "(WebDriver BiDi has no iframe target — an iframe is a realm inside its tab's browsing context, not a " + "selectable target; Capability 'frame.targets' is Chrome-only). Use --browser chrome to act on a cross-origin iframe.";
+  FRAME_SELECTOR_PAGE_ONLY_MESSAGE = "target 'frame:<substring>' selects an out-of-process iframe, and this tool is page-only " + "(closing, selecting, releasing or claiming an iframe is meaningless; these act on the embedder tab). " + `The page-only tools are ${FRAME_PAGE_ONLY_TOOLS.join(", ")}; every other tool that takes a 'target' ` + "accepts a frame: selector.";
+});
+
 // src/activity.ts
 function dispatchKey(backend, targetId) {
   return `${backend}:${targetId}`;
@@ -2127,6 +2158,17 @@ async function pickTarget(targets, selector) {
       return matches[0];
     throw new CdpError(workerMissMessage(needle, { wakeAttempted: false, liveWorkers }));
   }
+  if (isFrameSelector(selector)) {
+    const needle = frameNeedle(selector);
+    if (needle === "")
+      throw new CdpError(FRAME_EMPTY_NEEDLE_MESSAGE);
+    const { matches, liveFrames } = resolveFrameTargets(targets, needle);
+    if (matches.length > 1)
+      throw new CdpError(frameAmbiguityMessage(needle, matches));
+    if (matches.length === 1)
+      return matches[0];
+    throw new CdpError(frameMissMessage(needle, liveFrames));
+  }
   const byId = targets.find((t) => t.id === selector);
   if (!byId)
     throw new CdpError(`no target with id '${selector}'`);
@@ -2153,6 +2195,7 @@ var init_client2 = __esm(() => {
   init_leases();
   init_origins();
   init_workers();
+  init_frames();
   BASE = process.env.CDP_BASE ?? "http://127.0.0.1:9222";
   DEFAULT_TIMEOUT_MS3 = Number(process.env.CDP_TIMEOUT_MS ?? 15000);
   CdpError = class CdpError extends Error {
@@ -2843,6 +2886,9 @@ async function pickContext(conn, contexts, selector) {
   if (isWorkerSelector(selector)) {
     throw driverError("unsupported", WORKER_SELECTOR_UNSUPPORTED_MESSAGE);
   }
+  if (isFrameSelector(selector)) {
+    throw driverError("unsupported", FRAME_SELECTOR_UNSUPPORTED_MESSAGE);
+  }
   const exact = contexts.find((c) => c.context === selector);
   if (exact)
     return exact;
@@ -3054,6 +3100,7 @@ var init_driver2 = __esm(() => {
   init_leases();
   init_origins();
   init_workers();
+  init_frames();
   init_activity();
   init_client();
   init_session_lease();

package/dist/cli.js

@@ -473,6 +473,37 @@ var init_workers = __esm(() => {
   WORKER_SELECTOR_PAGE_ONLY_MESSAGE = "target 'worker:<substring>' selects a service/shared worker, and this tool is page-only " + "(closing, selecting or releasing a worker is meaningless). The tools that accept a worker: target are " + `${WORKER_CAPABLE_TOOLS.join(", ")}.`;
 });
 
+// src/frames.ts
+function isFrameSelector(selector) {
+  return typeof selector === "string" && selector.startsWith(FRAME_SELECTOR_PREFIX);
+}
+function frameNeedle(selector) {
+  return selector.slice(FRAME_SELECTOR_PREFIX.length);
+}
+function isFrameTargetType(type) {
+  return type === FRAME_TARGET_TYPE;
+}
+function resolveFrameTargets(targets, needle) {
+  const liveFrames = targets.filter((t) => isFrameTargetType(t.type));
+  return {
+    matches: needle === "" ? [] : liveFrames.filter((t) => t.url.includes(needle)),
+    liveFrames
+  };
+}
+function frameAmbiguityMessage(needle, matches) {
+  return `'frame:${needle}' matches more than one out-of-process iframe: ` + matches.map((m) => `${m.url} (${m.id})`).join(", ") + ". Narrow the substring, or pass the iframe's target id directly.";
+}
+function frameMissMessage(needle, liveFrames) {
+  const live = liveFrames.length ? ` (out-of-process iframes: ${liveFrames.map((f) => f.url).join(", ")})` : " (no out-of-process iframes are live)";
+  return `no out-of-process iframe whose url contains '${needle}'${live}. ` + "Only a CROSS-ORIGIN iframe gets its own process and therefore its own target; a same-origin iframe " + "runs inside its parent page and is NOT a target at all, so no substring can ever select it — reach a " + "same-origin iframe through its parent page instead (evaluate_script on the page, then the iframe " + "element's contentDocument). An out-of-process iframe whose document navigated away is likewise gone " + "from the listing: re-list with list_pages{all:true} and pass the new target id.";
+}
+var FRAME_SELECTOR_PREFIX = "frame:", FRAME_PAGE_ONLY_TOOLS, FRAME_TARGET_TYPE = "iframe", FRAME_EMPTY_NEEDLE_MESSAGE = "'frame:' needs a substring of the iframe's url, e.g. frame:ads.example.com or frame:player.html", FRAME_SELECTOR_UNSUPPORTED_MESSAGE, FRAME_SELECTOR_PAGE_ONLY_MESSAGE;
+var init_frames = __esm(() => {
+  FRAME_PAGE_ONLY_TOOLS = ["close_page", "select_page", "release_page", "claim_page"];
+  FRAME_SELECTOR_UNSUPPORTED_MESSAGE = "target 'frame:<substring>' selects an out-of-process iframe, which this backend cannot address " + "(WebDriver BiDi has no iframe target — an iframe is a realm inside its tab's browsing context, not a " + "selectable target; Capability 'frame.targets' is Chrome-only). Use --browser chrome to act on a cross-origin iframe.";
+  FRAME_SELECTOR_PAGE_ONLY_MESSAGE = "target 'frame:<substring>' selects an out-of-process iframe, and this tool is page-only " + "(closing, selecting, releasing or claiming an iframe is meaningless; these act on the embedder tab). " + `The page-only tools are ${FRAME_PAGE_ONLY_TOOLS.join(", ")}; every other tool that takes a 'target' ` + "accepts a frame: selector.";
+});
+
 // src/client.ts
 class CdpConnection {
   wsUrl;
@@ -671,6 +702,17 @@ async function pickTarget(targets, selector) {
       return matches[0];
     throw new CdpError(workerMissMessage(needle, { wakeAttempted: false, liveWorkers }));
   }
+  if (isFrameSelector(selector)) {
+    const needle = frameNeedle(selector);
+    if (needle === "")
+      throw new CdpError(FRAME_EMPTY_NEEDLE_MESSAGE);
+    const { matches, liveFrames } = resolveFrameTargets(targets, needle);
+    if (matches.length > 1)
+      throw new CdpError(frameAmbiguityMessage(needle, matches));
+    if (matches.length === 1)
+      return matches[0];
+    throw new CdpError(frameMissMessage(needle, liveFrames));
+  }
   const byId = targets.find((t) => t.id === selector);
   if (!byId)
     throw new CdpError(`no target with id '${selector}'`);
@@ -697,6 +739,7 @@ var init_client = __esm(() => {
   init_leases();
   init_origins();
   init_workers();
+  init_frames();
   BASE = process.env.CDP_BASE ?? "http://127.0.0.1:9222";
   DEFAULT_TIMEOUT_MS = Number(process.env.CDP_TIMEOUT_MS ?? 15000);
   CdpError = class CdpError extends Error {
@@ -2844,6 +2887,9 @@ async function pickContext(conn, contexts, selector) {
   if (isWorkerSelector(selector)) {
     throw driverError2("unsupported", WORKER_SELECTOR_UNSUPPORTED_MESSAGE);
   }
+  if (isFrameSelector(selector)) {
+    throw driverError2("unsupported", FRAME_SELECTOR_UNSUPPORTED_MESSAGE);
+  }
   const exact = contexts.find((c) => c.context === selector);
   if (exact)
     return exact;
@@ -3055,6 +3101,7 @@ var init_driver2 = __esm(() => {
   init_leases();
   init_origins();
   init_workers();
+  init_frames();
   init_activity();
   init_client2();
   init_session_lease();
@@ -4162,7 +4209,8 @@ var CDP_CAPABILITIES = new Set([
   "emulate.focus",
   "browser.downloads",
   "browser.permissions",
-  "worker.targets"
+  "worker.targets",
+  "frame.targets"
 ]);
 
 class CdpPageDriver {
@@ -4295,6 +4343,7 @@ class CdpPageDriver {
     const interactiveOnly = opts?.interactiveOnly ?? false;
     await this.ensureDomain("Accessibility");
     const { nodes } = await this.conn.send("Accessibility.getFullAXTree");
+    const oopifFrames = await this.detectOopifFrames();
     const byId = new Map;
     for (const n of nodes)
       byId.set(n.nodeId, n);
@@ -4303,11 +4352,17 @@ class CdpPageDriver {
     const walk = (node, depth) => {
       const role = axString(node.role);
       const name = axString(node.name);
-      const backendNodeId = node.backendDOMNodeId;
-      const emitted = !node.ignored && backendNodeId !== undefined && (interactiveOnly ? isInteractive(role) : !!(role || name));
+      const backendDOMNodeId = node.backendDOMNodeId;
+      const marker = backendDOMNodeId !== undefined ? oopifFrames.get(backendDOMNodeId) : undefined;
+      const emitted = !node.ignored && backendDOMNodeId !== undefined && (interactiveOnly ? isInteractive(role) || marker !== undefined : !!(role || name));
       if (emitted) {
         const extras = axExtras(node);
-        out.push({ uid: encodeUid(backendNodeId), role: role ?? "generic", depth, ...name ? { name } : {}, ...Object.keys(extras).length ? { extras } : {} });
+        if (marker) {
+          extras.frame = marker.frameId;
+          if (marker.frameUrl)
+            extras.frameUrl = marker.frameUrl;
+        }
+        out.push({ uid: encodeUid(backendDOMNodeId), role: role ?? "generic", depth, ...name ? { name } : {}, ...Object.keys(extras).length ? { extras } : {} });
       }
       const childDepth = emitted && !interactiveOnly ? depth + 1 : depth;
       for (const childId of node.childIds ?? []) {
@@ -4320,6 +4375,20 @@ class CdpPageDriver {
       walk(root, 0);
     return out;
   }
+  async detectOopifFrames() {
+    const markers = new Map;
+    try {
+      await this.ensureDomainSoft("DOM");
+      const iframeTargets = (await listTargets()).filter((t) => t.type === "iframe");
+      for (const target of iframeTargets) {
+        const owner = await this.conn.send("DOM.getFrameOwner", { frameId: target.id }).catch(() => ({ backendNodeId: undefined }));
+        if (typeof owner.backendNodeId === "number") {
+          markers.set(owner.backendNodeId, { frameId: target.id, ...target.url ? { frameUrl: target.url } : {} });
+        }
+      }
+    } catch {}
+    return markers;
+  }
   async locate(loc) {
     return encodeUid(await backendNodeIdOf(this.conn, loc));
   }
@@ -5497,6 +5566,7 @@ init_leases();
 init_activity();
 init_origins();
 init_workers();
+init_frames();
 var ARTIFACT_DIR = process.env.CDP_ARTIFACT_DIR ?? "/tmp/cdp-toolkit";
 var STATE_DIR = process.env.CDP_STATE_DIR ?? "/tmp/cdp-toolkit";
 
@@ -5553,6 +5623,9 @@ async function pickPage(driver, pages, selector) {
   if (isWorkerSelector(selector)) {
     throw new SharedToolError(backendOf(driver) === "firefox" ? WORKER_SELECTOR_UNSUPPORTED_MESSAGE : WORKER_SELECTOR_PAGE_ONLY_MESSAGE);
   }
+  if (isFrameSelector(selector)) {
+    throw new SharedToolError(backendOf(driver) === "firefox" ? FRAME_SELECTOR_UNSUPPORTED_MESSAGE : FRAME_SELECTOR_PAGE_ONLY_MESSAGE);
+  }
   const exactPage = pages.find((x) => x.id === selector);
   if (exactPage)
     return exactPage;
@@ -8863,7 +8936,7 @@ var MANIFEST = [
         },
         all: {
           type: "boolean",
-          description: "Include non-page targets."
+          description: "Include non-page targets (workers, iframes)."
         },
         probe: {
           type: "boolean",

package/dist/index.js

@@ -472,6 +472,37 @@ var init_workers = __esm(() => {
   WORKER_SELECTOR_PAGE_ONLY_MESSAGE = "target 'worker:<substring>' selects a service/shared worker, and this tool is page-only " + "(closing, selecting or releasing a worker is meaningless). The tools that accept a worker: target are " + `${WORKER_CAPABLE_TOOLS.join(", ")}.`;
 });
 
+// src/frames.ts
+function isFrameSelector(selector) {
+  return typeof selector === "string" && selector.startsWith(FRAME_SELECTOR_PREFIX);
+}
+function frameNeedle(selector) {
+  return selector.slice(FRAME_SELECTOR_PREFIX.length);
+}
+function isFrameTargetType(type) {
+  return type === FRAME_TARGET_TYPE;
+}
+function resolveFrameTargets(targets, needle) {
+  const liveFrames = targets.filter((t) => isFrameTargetType(t.type));
+  return {
+    matches: needle === "" ? [] : liveFrames.filter((t) => t.url.includes(needle)),
+    liveFrames
+  };
+}
+function frameAmbiguityMessage(needle, matches) {
+  return `'frame:${needle}' matches more than one out-of-process iframe: ` + matches.map((m) => `${m.url} (${m.id})`).join(", ") + ". Narrow the substring, or pass the iframe's target id directly.";
+}
+function frameMissMessage(needle, liveFrames) {
+  const live = liveFrames.length ? ` (out-of-process iframes: ${liveFrames.map((f) => f.url).join(", ")})` : " (no out-of-process iframes are live)";
+  return `no out-of-process iframe whose url contains '${needle}'${live}. ` + "Only a CROSS-ORIGIN iframe gets its own process and therefore its own target; a same-origin iframe " + "runs inside its parent page and is NOT a target at all, so no substring can ever select it — reach a " + "same-origin iframe through its parent page instead (evaluate_script on the page, then the iframe " + "element's contentDocument). An out-of-process iframe whose document navigated away is likewise gone " + "from the listing: re-list with list_pages{all:true} and pass the new target id.";
+}
+var FRAME_SELECTOR_PREFIX = "frame:", FRAME_PAGE_ONLY_TOOLS, FRAME_TARGET_TYPE = "iframe", FRAME_EMPTY_NEEDLE_MESSAGE = "'frame:' needs a substring of the iframe's url, e.g. frame:ads.example.com or frame:player.html", FRAME_SELECTOR_UNSUPPORTED_MESSAGE, FRAME_SELECTOR_PAGE_ONLY_MESSAGE;
+var init_frames = __esm(() => {
+  FRAME_PAGE_ONLY_TOOLS = ["close_page", "select_page", "release_page", "claim_page"];
+  FRAME_SELECTOR_UNSUPPORTED_MESSAGE = "target 'frame:<substring>' selects an out-of-process iframe, which this backend cannot address " + "(WebDriver BiDi has no iframe target — an iframe is a realm inside its tab's browsing context, not a " + "selectable target; Capability 'frame.targets' is Chrome-only). Use --browser chrome to act on a cross-origin iframe.";
+  FRAME_SELECTOR_PAGE_ONLY_MESSAGE = "target 'frame:<substring>' selects an out-of-process iframe, and this tool is page-only " + "(closing, selecting, releasing or claiming an iframe is meaningless; these act on the embedder tab). " + `The page-only tools are ${FRAME_PAGE_ONLY_TOOLS.join(", ")}; every other tool that takes a 'target' ` + "accepts a frame: selector.";
+});
+
 // src/client.ts
 class CdpConnection {
   wsUrl;
@@ -670,6 +701,17 @@ async function pickTarget(targets, selector) {
       return matches[0];
     throw new CdpError(workerMissMessage(needle, { wakeAttempted: false, liveWorkers }));
   }
+  if (isFrameSelector(selector)) {
+    const needle = frameNeedle(selector);
+    if (needle === "")
+      throw new CdpError(FRAME_EMPTY_NEEDLE_MESSAGE);
+    const { matches, liveFrames } = resolveFrameTargets(targets, needle);
+    if (matches.length > 1)
+      throw new CdpError(frameAmbiguityMessage(needle, matches));
+    if (matches.length === 1)
+      return matches[0];
+    throw new CdpError(frameMissMessage(needle, liveFrames));
+  }
   const byId = targets.find((t) => t.id === selector);
   if (!byId)
     throw new CdpError(`no target with id '${selector}'`);
@@ -696,6 +738,7 @@ var init_client = __esm(() => {
   init_leases();
   init_origins();
   init_workers();
+  init_frames();
   BASE = process.env.CDP_BASE ?? "http://127.0.0.1:9222";
   DEFAULT_TIMEOUT_MS = Number(process.env.CDP_TIMEOUT_MS ?? 15000);
   CdpError = class CdpError extends Error {
@@ -1564,7 +1607,8 @@ var CDP_CAPABILITIES = new Set([
   "emulate.focus",
   "browser.downloads",
   "browser.permissions",
-  "worker.targets"
+  "worker.targets",
+  "frame.targets"
 ]);
 
 class CdpPageDriver {
@@ -1697,6 +1741,7 @@ class CdpPageDriver {
     const interactiveOnly = opts?.interactiveOnly ?? false;
     await this.ensureDomain("Accessibility");
     const { nodes } = await this.conn.send("Accessibility.getFullAXTree");
+    const oopifFrames = await this.detectOopifFrames();
     const byId = new Map;
     for (const n of nodes)
       byId.set(n.nodeId, n);
@@ -1705,11 +1750,17 @@ class CdpPageDriver {
     const walk = (node, depth) => {
       const role = axString(node.role);
       const name = axString(node.name);
-      const backendNodeId = node.backendDOMNodeId;
-      const emitted = !node.ignored && backendNodeId !== undefined && (interactiveOnly ? isInteractive(role) : !!(role || name));
+      const backendDOMNodeId = node.backendDOMNodeId;
+      const marker = backendDOMNodeId !== undefined ? oopifFrames.get(backendDOMNodeId) : undefined;
+      const emitted = !node.ignored && backendDOMNodeId !== undefined && (interactiveOnly ? isInteractive(role) || marker !== undefined : !!(role || name));
       if (emitted) {
         const extras = axExtras(node);
-        out.push({ uid: encodeUid(backendNodeId), role: role ?? "generic", depth, ...name ? { name } : {}, ...Object.keys(extras).length ? { extras } : {} });
+        if (marker) {
+          extras.frame = marker.frameId;
+          if (marker.frameUrl)
+            extras.frameUrl = marker.frameUrl;
+        }
+        out.push({ uid: encodeUid(backendDOMNodeId), role: role ?? "generic", depth, ...name ? { name } : {}, ...Object.keys(extras).length ? { extras } : {} });
       }
       const childDepth = emitted && !interactiveOnly ? depth + 1 : depth;
       for (const childId of node.childIds ?? []) {
@@ -1722,6 +1773,20 @@ class CdpPageDriver {
       walk(root, 0);
     return out;
   }
+  async detectOopifFrames() {
+    const markers = new Map;
+    try {
+      await this.ensureDomainSoft("DOM");
+      const iframeTargets = (await listTargets()).filter((t) => t.type === "iframe");
+      for (const target of iframeTargets) {
+        const owner = await this.conn.send("DOM.getFrameOwner", { frameId: target.id }).catch(() => ({ backendNodeId: undefined }));
+        if (typeof owner.backendNodeId === "number") {
+          markers.set(owner.backendNodeId, { frameId: target.id, ...target.url ? { frameUrl: target.url } : {} });
+        }
+      }
+    } catch {}
+    return markers;
+  }
   async locate(loc) {
     return encodeUid(await backendNodeIdOf(this.conn, loc));
   }
@@ -2899,6 +2964,7 @@ init_leases();
 init_activity();
 init_origins();
 init_workers();
+init_frames();
 var ARTIFACT_DIR = process.env.CDP_ARTIFACT_DIR ?? "/tmp/cdp-toolkit";
 var STATE_DIR = process.env.CDP_STATE_DIR ?? "/tmp/cdp-toolkit";
 
@@ -2955,6 +3021,9 @@ async function pickPage(driver, pages, selector) {
   if (isWorkerSelector(selector)) {
     throw new SharedToolError(backendOf(driver) === "firefox" ? WORKER_SELECTOR_UNSUPPORTED_MESSAGE : WORKER_SELECTOR_PAGE_ONLY_MESSAGE);
   }
+  if (isFrameSelector(selector)) {
+    throw new SharedToolError(backendOf(driver) === "firefox" ? FRAME_SELECTOR_UNSUPPORTED_MESSAGE : FRAME_SELECTOR_PAGE_ONLY_MESSAGE);
+  }
   const exactPage = pages.find((x) => x.id === selector);
   if (exactPage)
     return exactPage;

package/dist/mcp.js

@@ -473,6 +473,37 @@ var init_workers = __esm(() => {
   WORKER_SELECTOR_PAGE_ONLY_MESSAGE = "target 'worker:<substring>' selects a service/shared worker, and this tool is page-only " + "(closing, selecting or releasing a worker is meaningless). The tools that accept a worker: target are " + `${WORKER_CAPABLE_TOOLS.join(", ")}.`;
 });
 
+// src/frames.ts
+function isFrameSelector(selector) {
+  return typeof selector === "string" && selector.startsWith(FRAME_SELECTOR_PREFIX);
+}
+function frameNeedle(selector) {
+  return selector.slice(FRAME_SELECTOR_PREFIX.length);
+}
+function isFrameTargetType(type) {
+  return type === FRAME_TARGET_TYPE;
+}
+function resolveFrameTargets(targets, needle) {
+  const liveFrames = targets.filter((t) => isFrameTargetType(t.type));
+  return {
+    matches: needle === "" ? [] : liveFrames.filter((t) => t.url.includes(needle)),
+    liveFrames
+  };
+}
+function frameAmbiguityMessage(needle, matches) {
+  return `'frame:${needle}' matches more than one out-of-process iframe: ` + matches.map((m) => `${m.url} (${m.id})`).join(", ") + ". Narrow the substring, or pass the iframe's target id directly.";
+}
+function frameMissMessage(needle, liveFrames) {
+  const live = liveFrames.length ? ` (out-of-process iframes: ${liveFrames.map((f) => f.url).join(", ")})` : " (no out-of-process iframes are live)";
+  return `no out-of-process iframe whose url contains '${needle}'${live}. ` + "Only a CROSS-ORIGIN iframe gets its own process and therefore its own target; a same-origin iframe " + "runs inside its parent page and is NOT a target at all, so no substring can ever select it — reach a " + "same-origin iframe through its parent page instead (evaluate_script on the page, then the iframe " + "element's contentDocument). An out-of-process iframe whose document navigated away is likewise gone " + "from the listing: re-list with list_pages{all:true} and pass the new target id.";
+}
+var FRAME_SELECTOR_PREFIX = "frame:", FRAME_PAGE_ONLY_TOOLS, FRAME_TARGET_TYPE = "iframe", FRAME_EMPTY_NEEDLE_MESSAGE = "'frame:' needs a substring of the iframe's url, e.g. frame:ads.example.com or frame:player.html", FRAME_SELECTOR_UNSUPPORTED_MESSAGE, FRAME_SELECTOR_PAGE_ONLY_MESSAGE;
+var init_frames = __esm(() => {
+  FRAME_PAGE_ONLY_TOOLS = ["close_page", "select_page", "release_page", "claim_page"];
+  FRAME_SELECTOR_UNSUPPORTED_MESSAGE = "target 'frame:<substring>' selects an out-of-process iframe, which this backend cannot address " + "(WebDriver BiDi has no iframe target — an iframe is a realm inside its tab's browsing context, not a " + "selectable target; Capability 'frame.targets' is Chrome-only). Use --browser chrome to act on a cross-origin iframe.";
+  FRAME_SELECTOR_PAGE_ONLY_MESSAGE = "target 'frame:<substring>' selects an out-of-process iframe, and this tool is page-only " + "(closing, selecting, releasing or claiming an iframe is meaningless; these act on the embedder tab). " + `The page-only tools are ${FRAME_PAGE_ONLY_TOOLS.join(", ")}; every other tool that takes a 'target' ` + "accepts a frame: selector.";
+});
+
 // src/client.ts
 class CdpConnection {
   wsUrl;
@@ -671,6 +702,17 @@ async function pickTarget(targets, selector) {
       return matches[0];
     throw new CdpError(workerMissMessage(needle, { wakeAttempted: false, liveWorkers }));
   }
+  if (isFrameSelector(selector)) {
+    const needle = frameNeedle(selector);
+    if (needle === "")
+      throw new CdpError(FRAME_EMPTY_NEEDLE_MESSAGE);
+    const { matches, liveFrames } = resolveFrameTargets(targets, needle);
+    if (matches.length > 1)
+      throw new CdpError(frameAmbiguityMessage(needle, matches));
+    if (matches.length === 1)
+      return matches[0];
+    throw new CdpError(frameMissMessage(needle, liveFrames));
+  }
   const byId = targets.find((t) => t.id === selector);
   if (!byId)
     throw new CdpError(`no target with id '${selector}'`);
@@ -697,6 +739,7 @@ var init_client = __esm(() => {
   init_leases();
   init_origins();
   init_workers();
+  init_frames();
   BASE = process.env.CDP_BASE ?? "http://127.0.0.1:9222";
   DEFAULT_TIMEOUT_MS = Number(process.env.CDP_TIMEOUT_MS ?? 15000);
   CdpError = class CdpError extends Error {
@@ -2844,6 +2887,9 @@ async function pickContext(conn, contexts, selector) {
   if (isWorkerSelector(selector)) {
     throw driverError2("unsupported", WORKER_SELECTOR_UNSUPPORTED_MESSAGE);
   }
+  if (isFrameSelector(selector)) {
+    throw driverError2("unsupported", FRAME_SELECTOR_UNSUPPORTED_MESSAGE);
+  }
   const exact = contexts.find((c) => c.context === selector);
   if (exact)
     return exact;
@@ -3055,6 +3101,7 @@ var init_driver2 = __esm(() => {
   init_leases();
   init_origins();
   init_workers();
+  init_frames();
   init_activity();
   init_client2();
   init_session_lease();
@@ -4175,7 +4222,8 @@ var CDP_CAPABILITIES = new Set([
   "emulate.focus",
   "browser.downloads",
   "browser.permissions",
-  "worker.targets"
+  "worker.targets",
+  "frame.targets"
 ]);
 
 class CdpPageDriver {
@@ -4308,6 +4356,7 @@ class CdpPageDriver {
     const interactiveOnly = opts?.interactiveOnly ?? false;
     await this.ensureDomain("Accessibility");
     const { nodes } = await this.conn.send("Accessibility.getFullAXTree");
+    const oopifFrames = await this.detectOopifFrames();
     const byId = new Map;
     for (const n of nodes)
       byId.set(n.nodeId, n);
@@ -4316,11 +4365,17 @@ class CdpPageDriver {
     const walk = (node, depth) => {
       const role = axString(node.role);
       const name = axString(node.name);
-      const backendNodeId = node.backendDOMNodeId;
-      const emitted = !node.ignored && backendNodeId !== undefined && (interactiveOnly ? isInteractive(role) : !!(role || name));
+      const backendDOMNodeId = node.backendDOMNodeId;
+      const marker = backendDOMNodeId !== undefined ? oopifFrames.get(backendDOMNodeId) : undefined;
+      const emitted = !node.ignored && backendDOMNodeId !== undefined && (interactiveOnly ? isInteractive(role) || marker !== undefined : !!(role || name));
       if (emitted) {
         const extras = axExtras(node);
-        out.push({ uid: encodeUid(backendNodeId), role: role ?? "generic", depth, ...name ? { name } : {}, ...Object.keys(extras).length ? { extras } : {} });
+        if (marker) {
+          extras.frame = marker.frameId;
+          if (marker.frameUrl)
+            extras.frameUrl = marker.frameUrl;
+        }
+        out.push({ uid: encodeUid(backendDOMNodeId), role: role ?? "generic", depth, ...name ? { name } : {}, ...Object.keys(extras).length ? { extras } : {} });
       }
       const childDepth = emitted && !interactiveOnly ? depth + 1 : depth;
       for (const childId of node.childIds ?? []) {
@@ -4333,6 +4388,20 @@ class CdpPageDriver {
       walk(root, 0);
     return out;
   }
+  async detectOopifFrames() {
+    const markers = new Map;
+    try {
+      await this.ensureDomainSoft("DOM");
+      const iframeTargets = (await listTargets()).filter((t) => t.type === "iframe");
+      for (const target of iframeTargets) {
+        const owner = await this.conn.send("DOM.getFrameOwner", { frameId: target.id }).catch(() => ({ backendNodeId: undefined }));
+        if (typeof owner.backendNodeId === "number") {
+          markers.set(owner.backendNodeId, { frameId: target.id, ...target.url ? { frameUrl: target.url } : {} });
+        }
+      }
+    } catch {}
+    return markers;
+  }
   async locate(loc) {
     return encodeUid(await backendNodeIdOf(this.conn, loc));
   }
@@ -5510,6 +5579,7 @@ init_leases();
 init_activity();
 init_origins();
 init_workers();
+init_frames();
 var ARTIFACT_DIR = process.env.CDP_ARTIFACT_DIR ?? "/tmp/cdp-toolkit";
 var STATE_DIR = process.env.CDP_STATE_DIR ?? "/tmp/cdp-toolkit";
 
@@ -5566,6 +5636,9 @@ async function pickPage(driver, pages, selector) {
   if (isWorkerSelector(selector)) {
     throw new SharedToolError(backendOf(driver) === "firefox" ? WORKER_SELECTOR_UNSUPPORTED_MESSAGE : WORKER_SELECTOR_PAGE_ONLY_MESSAGE);
   }
+  if (isFrameSelector(selector)) {
+    throw new SharedToolError(backendOf(driver) === "firefox" ? FRAME_SELECTOR_UNSUPPORTED_MESSAGE : FRAME_SELECTOR_PAGE_ONLY_MESSAGE);
+  }
   const exactPage = pages.find((x) => x.id === selector);
   if (exactPage)
     return exactPage;
@@ -8405,7 +8478,7 @@ var MANIFEST = [
         },
         all: {
           type: "boolean",
-          description: "Include non-page targets."
+          description: "Include non-page targets (workers, iframes)."
         },
         probe: {
           type: "boolean",
@@ -10778,10 +10851,10 @@ function resolveProfile(spec) {
 // src/toolDocs.ts
 var TOOL_DOCS = {
   list_pages: {
-    description: "Enumerate browser page targets (GET /json/list); page-type tabs only unless all=true. Each entry carries its targetId plus an origin field: 'agent' means this toolkit created it (also carries the creating label/createdAt, and stays 'agent' after the lease is released or the creator dies, making stray agent tabs findable), 'unknown' means no creation record - it never says 'human', the honest word for any tab it did not create; a record that exists but won't read adds originUnreadable. An entry under an active, readable lease also carries a 'lease' object {label,pid,idleMs,expiresAt,stale}, with idleMs and expiresAt computed fresh every call (never off disk), independent of probe. Under CDP_REQUIRE_LEASE this call also reaps abandoned agent tabs into an additive reaped array - but a lease reads reclaimable the moment its TTL elapses, while the tab is CLOSED only after a further grace (CDP_REAP_GRACE_MS, default 2700000ms/45min, so 60min total after last use); a dead-pid lease is reaped at once, a tab with no lease never. With probe, each page-type entry also gets 'responsive' (and humanActiveMs where human input is seen); both are absent, never false/null, without probe.",
+    description: "Enumerate browser page targets (GET /json/list); page-type tabs only unless all=true, which also lists workers and out-of-process (OOPIF) iframes. Each entry carries its targetId plus an origin field: 'agent' means this toolkit created it (also carries the creating label/createdAt, and stays 'agent' after the lease is released or the creator dies, making stray agent tabs findable), 'unknown' means no creation record - it never says 'human', the honest word for any tab it did not create; a record that exists but won't read adds originUnreadable. An entry under an active, readable lease also carries a 'lease' object {label,pid,idleMs,expiresAt,stale}, with idleMs and expiresAt computed fresh every call (never off disk), independent of probe. Under CDP_REQUIRE_LEASE this call also reaps abandoned agent tabs into an additive reaped array - but a lease reads reclaimable the moment its TTL elapses, while the tab is CLOSED only after a further grace (CDP_REAP_GRACE_MS, default 2700000ms/45min, so 60min total after last use); a dead-pid lease is reaped at once, a tab with no lease never. With probe, each page-type entry also gets 'responsive' (and humanActiveMs where human input is seen); both are absent, never false/null, without probe.",
     params: {
       lease: "Lease token from claim_page. Omit for a tab this process holds; required for a tab held by another process or one claimed explicitly. Auto-acquired under CDP_REQUIRE_LEASE (then pass target, not lease). See server instructions.",
-      all: "Include non-page targets (service/shared workers, background pages); default false lists page-type tabs only.",
+      all: "Include non-page targets (service/shared workers, background pages, out-of-process (OOPIF) iframes); default false lists page-type tabs only. A returned non-page targetId is accepted as a bare id by any tool's `target` param.",
       probe: "Ping each page-type renderer before returning, one bounded 500ms check per target and never more, so a wedged tab can't stall the listing. Adds 'responsive' (false on timeout/exception/unreachable, never an error for the whole call) and, where the same round trip finds human input, humanActiveMs. Default false. On a backend that cannot answer the ping, responsive is absent too (not false)."
     }
   },
@@ -10882,7 +10955,7 @@ var TOOL_DOCS = {
     }
   },
   take_snapshot: {
-    description: "Captures the page's accessibility tree as an indented text tree, each line prefixed [uid] (a CDP backendDOMNodeId). Every interaction tool (click/hover/fill/etc.) resolves that uid via DOM.resolveNode — run this first to discover uids to act on.",
+    description: `Captures the page's accessibility tree as an indented text tree, each line prefixed [uid] (a CDP backendDOMNodeId). Every interaction tool (click/hover/fill/etc.) resolves that uid via DOM.resolveNode — run this first to discover uids to act on. Cross-origin iframe subtrees are not walked (they live in a separate renderer process); the iframe node itself is emitted with a frame="<targetId>" marker (also in interactiveOnly mode), so the frame is discoverable and driveable via that id or frame:<url-substring>.`,
     params: {
       lease: "Lease token from claim_page. Omit for a tab this process holds; required for a tab held by another process or one claimed explicitly. Auto-acquired under CDP_REQUIRE_LEASE (then pass target, not lease). See server instructions.",
       target: "Page selector: 'active' (default), 'index:N', 'url:<substr>', 'title:<substr>', 'label:<name>', or a 32-hex '<targetId>'. Grammar: see server instructions.",
@@ -11280,7 +11353,7 @@ var TOOL_DOCS = {
 };
 
 // src/version.ts
-var VERSION = "2.6.0";
+var VERSION = "2.7.0";
 
 // src/mcp.ts
 function isDirectRun() {
@@ -11340,8 +11413,8 @@ function auditCoverage() {
 var INSTRUCTIONS = [
   "cdp-toolkit drives a real browser over Chrome DevTools Protocol (or Firefox WebDriver-BiDi): open and drive pages, click/fill/type, screenshot and accessibility-snapshot, read console + network, set cookies, emulate devices, run Lighthouse and performance traces, record screencasts. Conventions shared across its tools:",
   "TOOL AVAILABILITY: tools/list is complete and fixed for this process's life — cache it. Its one-liners are not the full docs: call describe_tool {name} on an unfamiliar tool, or describe_tool {} for the grouped catalog. CDP_TOOL_PROFILE=core (or a group list) lists only those groups; unlisted tools stay callable by name.",
-  "TARGET SELECTOR (the `target` param, unless a tool says otherwise): 'active' (default = first page) | 'index:N' (0-based) | 'url:<substr>' | 'title:<substr>' | 'label:<name>' (exact, from the origin ledger or a live lease) | a 32-hex '<targetId>'. Four Chrome-only tools (evaluate_script, list_network_requests, get_network_request, list_console_messages) also accept 'worker:<substr>' to reach a service/shared worker — e.g. an MV3 extension's background worker (worker:<extension-id> or worker:background.js); an idle-evicted worker is started first (see each tool's `wake`).",
-  "LEASES (the `lease` param): claim_page, and new_page{claim:true}, mint an opaque token. Omit it for a tab THIS process already holds. It is required for a tab held by ANOTHER process, or one claimed explicitly. Under CDP_REQUIRE_LEASE the gate auto-acquires a lease for any tab this process drives — no token is surfaced, so pass `target`, not `lease` — while an explicit claim:true still demands its token on every later call. Without CDP_REQUIRE_LEASE an unleased tab needs no token at all.",
+  "TARGET SELECTOR (the `target` param, unless a tool says otherwise): 'active' (default = first page) | 'index:N' (0-based) | 'url:<substr>' | 'title:<substr>' | 'label:<name>' (exact, ledger or live lease) | a 32-hex '<targetId>' of any target type — an iframe id from list_pages{all:true} drives like a tab. Chrome tools also accept 'frame:<substr>' for OOPIF iframe targets. Four Chrome-only tools (evaluate_script, list_network_requests, get_network_request, list_console_messages) also accept 'worker:<substr>' to reach a service/shared worker (e.g. an MV3 background worker); an idle-evicted worker is started first (see `wake`).",
+  "LEASES (the `lease` param): claim_page, and new_page{claim:true}, mint an opaque token. Omit it for a tab THIS process already holds. It is required for a tab held by ANOTHER process, or one claimed explicitly. Under CDP_REQUIRE_LEASE the gate auto-acquires a lease for any tab this process drives — no token is surfaced, so pass `target`, not `lease` — while an explicit claim:true still demands its token on every later call.",
   "ORIGIN: list_pages and list_leases tag each tab's `origin` as 'agent' (this toolkit created it) or 'unknown' — never 'human', because the toolkit cannot prove a person opened a tab. An 'agent' tab stays findable after its creator releases the lease or dies."
 ].join(`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cdp-toolkit",
-  "version": "2.6.0",
+  "version": "2.7.0",
   "description": "A lightweight chrome-devtools-mcp alternative: an MCP server + CLI that drives the tabs you name, one target per call over one direct WebSocket, with a bounded timeout on every call, so a stuck page can't wedge your agent or force a /mcp restart. Chrome over CDP and Firefox over WebDriver BiDi, with tools a backend can't run absent from tools/list rather than throwing mid-task. 48 tools including built-in network mocking, a cookie group, tab leases with human-activity detection, real HTML5 drag-and-drop, raw mouse/scroll dispatch, downloads, permission grants, and tab-to-video screen recording so several agents can drive one browser without stealing each other's tabs or a human's. No Puppeteer, no all-target fan-out.",
   "type": "module",
   "license": "MIT",

package/src/bidi/driver.ts

@@ -46,6 +46,7 @@ import {
 import { assertLeaseOk, defaultLabel, isPidAlive } from "../leases.ts";
 import { resolveLiveLabel } from "../origins.ts";
 import { isWorkerSelector, WORKER_SELECTOR_UNSUPPORTED_MESSAGE } from "../workers.ts";
+import { FRAME_SELECTOR_UNSUPPORTED_MESSAGE, isFrameSelector } from "../frames.ts";
 import { BEACON_FUNCTION_DECLARATION, BEACON_READ_EXPRESSION, BEACON_SOURCE, recordDispatch } from "../activity.ts";
 import { BidiConnection, BidiError, connectBidiSessionUrl } from "./client.ts";
 import {
@@ -845,6 +846,13 @@ async function pickContext(
     // "no context matching 'worker:abc'" that reads like a typo.
     throw driverError("unsupported", WORKER_SELECTOR_UNSUPPORTED_MESSAGE);
   }
+  if (isFrameSelector(selector)) {
+    // Capability-gated for the same reason as the worker: arm above. WebDriver
+    // BiDi has no iframe TARGET to resolve to — an iframe is a realm inside its
+    // tab's browsing context — so the honest error names the capability
+    // ('frame.targets', Chrome-only) rather than retrying or reading as a typo.
+    throw driverError("unsupported", FRAME_SELECTOR_UNSUPPORTED_MESSAGE);
+  }
   const exact = contexts.find((c) => c.context === selector);
   if (exact) return exact;
   throw driverError("no-such-target", `no context matching '${selector}'`);

package/src/cdp/driver.ts

@@ -652,7 +652,7 @@ const CDP_CAPABILITIES: ReadonlySet<Capability> = new Set<Capability>([
   "screenshot.fullPage", "screenshot.element", "screenshot.scale", "screenshot.renderSize", "screenshot.tile", "network.intercept",
   "snapshot.accessibilityTree", "input.insertTextAtomic", "locate.text", "locate.xpath",
   "capture.screencast", "input.raw", "input.html5Drag", "emulate.focus",
-  "browser.downloads", "browser.permissions", "worker.targets",
+  "browser.downloads", "browser.permissions", "worker.targets", "frame.targets",
 ]);
 /* ---------------------------------- PageDriver ---------------------------------- */
 class CdpPageDriver implements PageDriver {
@@ -820,10 +820,36 @@ class CdpPageDriver implements PageDriver {
     const { objectId } = await resolveElementLocator(this.conn, loc);
     return this.callFn(objectId, functionDeclaration, args, true);
   }
+  /**
+ * OOPIF MARKERS (issue #7 fix 1): which emitted snapshot nodes own an out-of-process iframe.
+ *
+ * Chrome's Accessibility.getFullAXTree includes the <iframe> ELEMENT's AX node (role "Iframe",
+ * with a backendDOMNodeId) but not the subtree of an out-of-process iframe (OOPIF): that subtree
+ * lives in a separate renderer/AX tree, so its contents are simply absent and a caller reading
+ * the snapshot has no signal that an entire interactable document ends at that line. Same-origin
+ * iframes ARE merged into the one response, so they need no marker — only process-isolated
+ * frames do, and process isolation is decided by Chrome, not by any origin heuristic here.
+ *
+ * Truth source: the browser's target list (`/json/list`) names every OOPIF as its own target of
+ * type "iframe", and an OOPIF's target id IS its frame id. `Page.getFrameTree` is deliberately
+ * NOT used here: on a page-level websocket attachment it omits out-of-process child frames
+ * (observed Chrome 153: same DOM with the <iframe>, frame tree with no childFrames), which is
+ * exactly the set this marker exists for. DOM.getFrameOwner maps each candidate frame id to the
+ * backendNodeId of the owning <iframe> element — the node snapshot() is about to emit; it throws
+ * for frame ids this page doesn't own, which is the filter.
+ *
+ * The marker rides the node's existing `extras` map ("frame" = frame/target id, "frameUrl" when
+ * the frame tree reported one) because SnapshotNode is owned by ../driver.ts and shared with the
+ * BiDi driver; renderSnapshotLine renders unknown extras keys quoted, which is the desired shape
+ * (`[frame="A1B2..."]`). Everything here is failure-soft by design: a snapshot must never fail
+ * because marker detection did, so any error returns an empty map and the snapshot degrades to
+ * exactly its pre-marker output.
+ */
   async snapshot(opts?: { interactiveOnly?: boolean }): Promise<SnapshotNode[]> {
     const interactiveOnly = opts?.interactiveOnly ?? false;
     await this.ensureDomain("Accessibility");
     const { nodes } = await this.conn.send<{ nodes: AxNode[] }>("Accessibility.getFullAXTree");
+    const oopifFrames = await this.detectOopifFrames();
     const byId = new Map<string, AxNode>();
     for (const n of nodes) byId.set(n.nodeId, n);
     const roots = nodes.filter((n) => !n.parentId || !byId.has(n.parentId));
@@ -837,11 +863,20 @@ class CdpPageDriver implements PageDriver {
     const walk = (node: AxNode, depth: number): void => {
       const role = axString(node.role);
       const name = axString(node.name);
-      const backendNodeId = node.backendDOMNodeId;
-      const emitted = !node.ignored && backendNodeId !== undefined && (interactiveOnly ? isInteractive(role) : !!(role || name));
+      const backendDOMNodeId = node.backendDOMNodeId;
+      const marker = backendDOMNodeId !== undefined ? oopifFrames.get(backendDOMNodeId) : undefined;
+      // interactiveOnly drops "Iframe" (not in INTERACTIVE_ROLES), but an iframe carrying an
+      // OOPIF marker is itself the accessibility boundary of an entire process, so it is
+      // emitted anyway: the default view must surface that the boundary exists. Everything
+      // else about the emit rule is unchanged, and the depth rule below is untouched.
+      const emitted = !node.ignored && backendDOMNodeId !== undefined && (interactiveOnly ? isInteractive(role) || marker !== undefined : !!(role || name));
       if (emitted) {
         const extras = axExtras(node);
-        out.push({ uid: encodeUid(backendNodeId as number), role: role ?? "generic", depth, ...(name ? { name } : {}), ...(Object.keys(extras).length ? { extras } : {}) });
+        if (marker) {
+          extras.frame = marker.frameId;
+          if (marker.frameUrl) extras.frameUrl = marker.frameUrl;
+        }
+        out.push({ uid: encodeUid(backendDOMNodeId as number), role: role ?? "generic", depth, ...(name ? { name } : {}), ...(Object.keys(extras).length ? { extras } : {}) });
       }
       const childDepth = emitted && !interactiveOnly ? depth + 1 : depth;
       for (const childId of node.childIds ?? []) {
@@ -852,6 +887,36 @@ class CdpPageDriver implements PageDriver {
     for (const root of roots) walk(root, 0);
     return out;
   }
+  /**
+   * The marker map behind snapshot()'s OOPIF annotations (see snapshot()'s OOPIF MARKERS block):
+   * backendNodeId of the owning <iframe> element -> { frameId (= CDP target id), frameUrl }.
+   * Failure-soft end to end: any error anywhere in the round-trip yields an EMPTY map, never a
+   * failed snapshot. DOM.getFrameOwner throws for the main frame, which is why only non-main
+   * frames are visited; ensureDomainSoft covers the DOM.enable it requires without making a
+   * failed enable break anything else (getFrameOwner would simply throw into the same catch).
+   */
+  private async detectOopifFrames(): Promise<Map<number, { frameId: string; frameUrl?: string }>> {
+    const markers = new Map<number, { frameId: string; frameUrl?: string }>();
+    try {
+      await this.ensureDomainSoft("DOM");
+      // Process-isolation truth, not an origin heuristic: every OOPIF has its own iframe-type
+      // CDP target whose id IS its frame id (listTargets is client.ts's /json/list). This page
+      // owns only some of them — DOM.getFrameOwner throws for any frame id the page doesn't own
+      // (notably iframe targets inside OTHER tabs), and that throw is the ownership filter.
+      const iframeTargets = (await listTargets()).filter((t) => t.type === "iframe");
+      for (const target of iframeTargets) {
+        const owner = await this.conn
+          .send<{ backendNodeId?: number }>("DOM.getFrameOwner", { frameId: target.id })
+          .catch(() => ({ backendNodeId: undefined }));
+        if (typeof owner.backendNodeId === "number") {
+          markers.set(owner.backendNodeId, { frameId: target.id, ...(target.url ? { frameUrl: target.url } : {}) });
+        }
+      }
+    } catch {
+      // Deliberately empty: see the doc comment. Markers are an annotation, not a guarantee.
+    }
+    return markers;
+  }
   async locate(loc: ElementLocator): Promise<DriverUid> {
     return encodeUid(await backendNodeIdOf(this.conn, loc));
   }

package/src/client.ts

@@ -15,6 +15,14 @@ import {
   workerNeedle,
   WORKER_EMPTY_NEEDLE_MESSAGE,
 } from "./workers.ts";
+import {
+  frameAmbiguityMessage,
+  frameMissMessage,
+  frameNeedle,
+  isFrameSelector,
+  resolveFrameTargets,
+  FRAME_EMPTY_NEEDLE_MESSAGE,
+} from "./frames.ts";
 
 /** Base HTTP origin of the DevTools endpoint. Override with CDP_BASE. */
 export const BASE = process.env.CDP_BASE ?? "http://127.0.0.1:9222";
@@ -284,6 +292,20 @@ async function pickTarget(targets: Target[], selector: TargetSelector): Promise<
     if (matches.length === 1) return matches[0]!;
     throw new CdpError(workerMissMessage(needle, { wakeAttempted: false, liveWorkers }));
   }
+  if (isFrameSelector(selector)) {
+    // Also resolved against the UNFILTERED listing: an out-of-process iframe is
+    // its own target (site isolation), but not a PAGE target, so `pages` never
+    // contains it. Unlike the worker arm, the returned hit deliberately still
+    // flows through resolveTarget's lease gate below — a bare iframe id does
+    // too today, and this arm is a way of NAMING that same target, not a new
+    // permission to bypass who holds the embedder tab's lease.
+    const needle = frameNeedle(selector);
+    if (needle === "") throw new CdpError(FRAME_EMPTY_NEEDLE_MESSAGE);
+    const { matches, liveFrames } = resolveFrameTargets(targets, needle);
+    if (matches.length > 1) throw new CdpError(frameAmbiguityMessage(needle, matches));
+    if (matches.length === 1) return matches[0]!;
+    throw new CdpError(frameMissMessage(needle, liveFrames));
+  }
   // bare id
   const byId = targets.find((t) => t.id === selector);
   if (!byId) throw new CdpError(`no target with id '${selector}'`);

package/src/driver.ts

@@ -153,7 +153,8 @@ export type Capability =
   | "emulate.focus" // fake page focus without moving the OS window (focus_emulation / click_focus_gated); Chrome only — BiDi's emulation module has no focus primitive
   | "browser.downloads" // capture a file download to a known path (wait_for_download); Chrome only
   | "browser.permissions" // grant/reset browser permissions for an origin (grant_permissions); Chrome only
-  | "worker.targets"; // address a service/shared worker as a target ("worker:<substr>"), incl. waking an evicted MV3 worker; Chrome only
+  | "worker.targets" // address a service/shared worker as a target ("worker:<substr>"), incl. waking an evicted MV3 worker; Chrome only
+  | "frame.targets"; // address an out-of-process (cross-origin) iframe as a target ("frame:<substr>"); Chrome only — same-site iframes are not targets at all
 
 /**
  * Tools whose availability depends on a capability. A tool absent from this

package/src/frames.ts

@@ -0,0 +1,169 @@
+/**
+ * The "frame:<url-substring>" arm of the TargetSelector grammar (issue #7).
+ *
+ * WHAT IT IS FOR. Chrome site isolation gives a CROSS-ORIGIN iframe its own
+ * process, and with it its own CDP target that shows up in /json/list with
+ * type "iframe" and its own webSocketDebuggerUrl. Until now the only way to
+ * name one was its 32-hex targetId, discovered by reading list_pages{all:true}
+ * output by eye. This arm names it by a substring of its url — `frame:ads.example.com`,
+ * `frame:player.html` — exactly the way `url:` names a tab.
+ *
+ * THE OOPIF FACT, which is what the miss message below exists to teach: only
+ * OUT-OF-PROCESS iframes appear as targets at all. A SAME-ORIGIN iframe runs
+ * inside its parent page's process and has no target, no id, no listing entry —
+ * no substring can ever select it, and a caller who does not know that goes
+ * hunting for a typo that is not there. This is the frame arm's counterpart of
+ * the MV3-eviction fact the worker messages teach (see workers.ts).
+ *
+ * WHY DATA, NEVER THROWS (the resolveLiveLabel precedent in origins.ts, and
+ * workers.ts's copy of this rule). The grammar has three independent resolver
+ * copies — `pickTarget` in client.ts, `pickPage` in shared-tools.ts,
+ * `pickContext` in bidi/driver.ts — each with its own error class (CdpError /
+ * SharedToolError / DriverError). A shared resolver that threw would force one
+ * class on all three, so this returns the facts and each caller raises its own
+ * error. What IS shared is the message TEXT below, because the teaching in it
+ * is the point of the feature and three hand-written variants of it would drift
+ * apart within one release.
+ *
+ * WHY THE ALL-TARGETS LISTING. An iframe is not a page target, so the page-only
+ * listing the other url:/title: arms resolve against never contains one. This
+ * arm reads the unfiltered listing, same as the worker: arm. That does NOT
+ * merge the id sets that reap and leases keep apart: see ReapInput.livePageIds's
+ * header. Unlike a worker, an iframe hit is NOT exempted from the lease gate in
+ * client.ts's resolveTarget — a bare iframe id goes through that gate today, and
+ * `frame:` is a way of NAMING the same target, not a new permission for it.
+ */
+
+/** Selector prefix owned by this arm. */
+export const FRAME_SELECTOR_PREFIX = "frame:";
+
+/**
+ * The page-only tools that REFUSE this arm, and the single source of truth for
+ * it: the page-only refusal message below is built from this list.
+ *
+ * WHY A REFUSAL LIST AND NOT workers.ts's WORKER_CAPABLE_TOOLS allowlist: the
+ * worker arm is resolved per-tool (evaluate_script and the three recorders route
+ * it through resolveWorkerSelectorFor), so which tools accept it is a finite,
+ * deliberate list. The frame arm instead lives in client.ts's pickTarget, the
+ * ONE resolver every Chrome tool's `target` argument already flows through, so
+ * every target-taking tool accepts it with no per-tool work — the finite,
+ * deliberate list is the four that must NOT (closing, selecting, releasing or
+ * claiming an iframe is meaningless; those act on the embedder TAB).
+ */
+export const FRAME_PAGE_ONLY_TOOLS = ["close_page", "select_page", "release_page", "claim_page"] as const;
+
+/**
+ * The CDP target type this arm resolves: "iframe". /json/list reports an
+ * out-of-process iframe under exactly this type (a same-origin one is absent
+ * entirely, which is the OOPIF fact the miss message teaches).
+ */
+export const FRAME_TARGET_TYPE = "iframe";
+
+/** The two fields every listing shape (CDP Target, PageInfo) already carries. */
+export interface FrameTargetLike {
+  id: string;
+  url: string;
+  type?: string;
+}
+
+export function isFrameSelector(selector: string | undefined): selector is string {
+  return typeof selector === "string" && selector.startsWith(FRAME_SELECTOR_PREFIX);
+}
+
+/** The substring half of "frame:<substring>". May be empty; callers reject that. */
+export function frameNeedle(selector: string): string {
+  return selector.slice(FRAME_SELECTOR_PREFIX.length);
+}
+
+export function isFrameTargetType(type: string | undefined): boolean {
+  return type === FRAME_TARGET_TYPE;
+}
+
+export interface FrameResolution<T> {
+  /** Out-of-process iframe targets whose url contains the needle. */
+  matches: T[];
+  /** Every live iframe target, for a miss message that lists the alternatives. */
+  liveFrames: T[];
+}
+
+/**
+ * Pure: split a target listing into "iframes matching the needle" and "all live
+ * iframes". An EMPTY needle matches nothing here rather than matching
+ * everything, because `"anything".includes("")` is true and a bare `frame:`
+ * would otherwise silently mean "whichever iframe happens to be first".
+ * Callers reject the empty needle outright with FRAME_EMPTY_NEEDLE_MESSAGE.
+ */
+export function resolveFrameTargets<T extends FrameTargetLike>(targets: readonly T[], needle: string): FrameResolution<T> {
+  const liveFrames = targets.filter((t) => isFrameTargetType(t.type));
+  return {
+    matches: needle === "" ? [] : liveFrames.filter((t) => t.url.includes(needle)),
+    liveFrames,
+  };
+}
+
+/* -------------------------------- shared message text -------------------------------- */
+
+export const FRAME_EMPTY_NEEDLE_MESSAGE =
+  "'frame:' needs a substring of the iframe's url, e.g. frame:ads.example.com or frame:player.html";
+
+/**
+ * The Firefox refusal. A PARAM-level gap, exactly like drag's mode:'html5' and
+ * the worker arm's WORKER_SELECTOR_UNSUPPORTED_MESSAGE: the target-taking tools
+ * stay in tools/list on Firefox because every tab selector still works there,
+ * and only this one arm is refused. Naming the reason matters — WebDriver BiDi
+ * has no iframe TARGET: iframes are realms inside a browsing context, and a
+ * context IS a tab, so there is nothing for a target selector to resolve to.
+ * This is a protocol-model gap, not an unimplemented to-do.
+ */
+export const FRAME_SELECTOR_UNSUPPORTED_MESSAGE =
+  "target 'frame:<substring>' selects an out-of-process iframe, which this backend cannot address " +
+  "(WebDriver BiDi has no iframe target — an iframe is a realm inside its tab's browsing context, not a " +
+  "selectable target; Capability 'frame.targets' is Chrome-only). Use --browser chrome to act on a cross-origin iframe.";
+
+/**
+ * Refusal from the page-only resolvers (close_page / select_page /
+ * release_page / claim_page): those act on the embedder TAB, and an iframe has
+ * no independent existence to close, select, release or claim. Because the arm
+ * is accepted by every OTHER target-taking tool (it resolves inside the shared
+ * pickTarget), the message names the refusing minority rather than an allowlist
+ * of the accepting majority.
+ */
+export const FRAME_SELECTOR_PAGE_ONLY_MESSAGE =
+  "target 'frame:<substring>' selects an out-of-process iframe, and this tool is page-only " +
+  "(closing, selecting, releasing or claiming an iframe is meaningless; these act on the embedder tab). " +
+  `The page-only tools are ${FRAME_PAGE_ONLY_TOOLS.join(", ")}; every other tool that takes a 'target' ` +
+  "accepts a frame: selector.";
+
+/** Ambiguity never resolves to a silent first match: name every candidate. */
+export function frameAmbiguityMessage(needle: string, matches: readonly FrameTargetLike[]): string {
+  return (
+    `'frame:${needle}' matches more than one out-of-process iframe: ` +
+    matches.map((m) => `${m.url} (${m.id})`).join(", ") +
+    ". Narrow the substring, or pass the iframe's target id directly."
+  );
+}
+
+/**
+ * The miss message, and the whole reason this module owns its text. A miss
+ * here is usually NOT a typo, for one of two reasons the caller can act on:
+ *   - the iframe is SAME-ORIGIN: it runs inside its parent page's process, has
+ *     no target at all, and can never be selected by any substring. The fix is
+ *     to go through the parent page (evaluate_script on the page, then
+ *     contentDocument through the iframe element).
+ *   - the frame navigated away or was removed: an OOPIF target is as
+ *     short-lived as the document inside it, so the id seen a moment ago is
+ *     simply gone. The fix is to re-list.
+ */
+export function frameMissMessage(needle: string, liveFrames: readonly FrameTargetLike[]): string {
+  const live = liveFrames.length
+    ? ` (out-of-process iframes: ${liveFrames.map((f) => f.url).join(", ")})`
+    : " (no out-of-process iframes are live)";
+  return (
+    `no out-of-process iframe whose url contains '${needle}'${live}. ` +
+    "Only a CROSS-ORIGIN iframe gets its own process and therefore its own target; a same-origin iframe " +
+    "runs inside its parent page and is NOT a target at all, so no substring can ever select it — reach a " +
+    "same-origin iframe through its parent page instead (evaluate_script on the page, then the iframe " +
+    "element's contentDocument). An out-of-process iframe whose document navigated away is likewise gone " +
+    "from the listing: re-list with list_pages{all:true} and pass the new target id."
+  );
+}

package/src/manifest.ts

@@ -35,7 +35,7 @@ export const MANIFEST: ToolSpec[] = [
         },
         "all": {
           "type": "boolean",
-          "description": "Include non-page targets."
+          "description": "Include non-page targets (workers, iframes)."
         },
         "probe": {
           "type": "boolean",

package/src/mcp.ts

@@ -158,8 +158,8 @@ function auditCoverage(): void {
 const INSTRUCTIONS = [
   "cdp-toolkit drives a real browser over Chrome DevTools Protocol (or Firefox WebDriver-BiDi): open and drive pages, click/fill/type, screenshot and accessibility-snapshot, read console + network, set cookies, emulate devices, run Lighthouse and performance traces, record screencasts. Conventions shared across its tools:",
   "TOOL AVAILABILITY: tools/list is complete and fixed for this process's life — cache it. Its one-liners are not the full docs: call describe_tool {name} on an unfamiliar tool, or describe_tool {} for the grouped catalog. CDP_TOOL_PROFILE=core (or a group list) lists only those groups; unlisted tools stay callable by name.",
-  "TARGET SELECTOR (the `target` param, unless a tool says otherwise): 'active' (default = first page) | 'index:N' (0-based) | 'url:<substr>' | 'title:<substr>' | 'label:<name>' (exact, from the origin ledger or a live lease) | a 32-hex '<targetId>'. Four Chrome-only tools (evaluate_script, list_network_requests, get_network_request, list_console_messages) also accept 'worker:<substr>' to reach a service/shared worker — e.g. an MV3 extension's background worker (worker:<extension-id> or worker:background.js); an idle-evicted worker is started first (see each tool's `wake`).",
-  "LEASES (the `lease` param): claim_page, and new_page{claim:true}, mint an opaque token. Omit it for a tab THIS process already holds. It is required for a tab held by ANOTHER process, or one claimed explicitly. Under CDP_REQUIRE_LEASE the gate auto-acquires a lease for any tab this process drives — no token is surfaced, so pass `target`, not `lease` — while an explicit claim:true still demands its token on every later call. Without CDP_REQUIRE_LEASE an unleased tab needs no token at all.",
+  "TARGET SELECTOR (the `target` param, unless a tool says otherwise): 'active' (default = first page) | 'index:N' (0-based) | 'url:<substr>' | 'title:<substr>' | 'label:<name>' (exact, ledger or live lease) | a 32-hex '<targetId>' of any target type — an iframe id from list_pages{all:true} drives like a tab. Chrome tools also accept 'frame:<substr>' for OOPIF iframe targets. Four Chrome-only tools (evaluate_script, list_network_requests, get_network_request, list_console_messages) also accept 'worker:<substr>' to reach a service/shared worker (e.g. an MV3 background worker); an idle-evicted worker is started first (see `wake`).",
+  "LEASES (the `lease` param): claim_page, and new_page{claim:true}, mint an opaque token. Omit it for a tab THIS process already holds. It is required for a tab held by ANOTHER process, or one claimed explicitly. Under CDP_REQUIRE_LEASE the gate auto-acquires a lease for any tab this process drives — no token is surfaced, so pass `target`, not `lease` — while an explicit claim:true still demands its token on every later call.",
   "ORIGIN: list_pages and list_leases tag each tab's `origin` as 'agent' (this toolkit created it) or 'unknown' — never 'human', because the toolkit cannot prove a person opened a tab. An 'agent' tab stays findable after its creator releases the lease or dies.",
 ].join("\n\n");
 

package/src/shared-tools.ts

@@ -48,6 +48,7 @@ import {
 import { installBeacon, probeRendererActivity, rendererProbeSupported } from "./activity.ts";
 import { newTrackedPage, originIndex, resolveLiveLabel, type PageOrigin } from "./origins.ts";
 import { isWorkerSelector, WORKER_SELECTOR_PAGE_ONLY_MESSAGE, WORKER_SELECTOR_UNSUPPORTED_MESSAGE } from "./workers.ts";
+import { FRAME_SELECTOR_PAGE_ONLY_MESSAGE, FRAME_SELECTOR_UNSUPPORTED_MESSAGE, isFrameSelector } from "./frames.ts";
 import { reapStaleAgentTabs, type ReapedTab } from "./reap.ts";
 
 const ARTIFACT_DIR = process.env.CDP_ARTIFACT_DIR ?? "/tmp/cdp-toolkit";
@@ -150,6 +151,18 @@ export async function pickPage(driver: BrowserDriver, pages: PageInfo[], selecto
       backendOf(driver) === "firefox" ? WORKER_SELECTOR_UNSUPPORTED_MESSAGE : WORKER_SELECTOR_PAGE_ONLY_MESSAGE,
     );
   }
+  if (isFrameSelector(selector)) {
+    // Same contract as the worker: arm above, same reason. Every caller of
+    // pickPage (close_page / select_page / release_page via resolvePage, and
+    // claim_page's takeover) acts on a TAB; an out-of-process iframe has no
+    // independent existence to close, select, release or claim. Refusing with
+    // the reason beats the bare-id fall-through's "no target with id
+    // 'frame:foo'", which reads as a typo. The arm itself lives in client.ts's
+    // pickTarget and every other target-taking tool accepts it.
+    throw new SharedToolError(
+      backendOf(driver) === "firefox" ? FRAME_SELECTOR_UNSUPPORTED_MESSAGE : FRAME_SELECTOR_PAGE_ONLY_MESSAGE,
+    );
+  }
   const exactPage = pages.find((x) => x.id === selector);
   if (exactPage) return exactPage;
   const all = await driver.listPages({ all: true });

package/src/toolDocs.ts

@@ -3,10 +3,10 @@ export type ToolDoc = { readonly description: string; readonly params: Record<st
 
 export const TOOL_DOCS: Record<string, ToolDoc> = {
   "list_pages": {
-    "description": "Enumerate browser page targets (GET /json/list); page-type tabs only unless all=true. Each entry carries its targetId plus an origin field: 'agent' means this toolkit created it (also carries the creating label/createdAt, and stays 'agent' after the lease is released or the creator dies, making stray agent tabs findable), 'unknown' means no creation record - it never says 'human', the honest word for any tab it did not create; a record that exists but won't read adds originUnreadable. An entry under an active, readable lease also carries a 'lease' object {label,pid,idleMs,expiresAt,stale}, with idleMs and expiresAt computed fresh every call (never off disk), independent of probe. Under CDP_REQUIRE_LEASE this call also reaps abandoned agent tabs into an additive reaped array - but a lease reads reclaimable the moment its TTL elapses, while the tab is CLOSED only after a further grace (CDP_REAP_GRACE_MS, default 2700000ms/45min, so 60min total after last use); a dead-pid lease is reaped at once, a tab with no lease never. With probe, each page-type entry also gets 'responsive' (and humanActiveMs where human input is seen); both are absent, never false/null, without probe.",
+    "description": "Enumerate browser page targets (GET /json/list); page-type tabs only unless all=true, which also lists workers and out-of-process (OOPIF) iframes. Each entry carries its targetId plus an origin field: 'agent' means this toolkit created it (also carries the creating label/createdAt, and stays 'agent' after the lease is released or the creator dies, making stray agent tabs findable), 'unknown' means no creation record - it never says 'human', the honest word for any tab it did not create; a record that exists but won't read adds originUnreadable. An entry under an active, readable lease also carries a 'lease' object {label,pid,idleMs,expiresAt,stale}, with idleMs and expiresAt computed fresh every call (never off disk), independent of probe. Under CDP_REQUIRE_LEASE this call also reaps abandoned agent tabs into an additive reaped array - but a lease reads reclaimable the moment its TTL elapses, while the tab is CLOSED only after a further grace (CDP_REAP_GRACE_MS, default 2700000ms/45min, so 60min total after last use); a dead-pid lease is reaped at once, a tab with no lease never. With probe, each page-type entry also gets 'responsive' (and humanActiveMs where human input is seen); both are absent, never false/null, without probe.",
     "params": {
       "lease": "Lease token from claim_page. Omit for a tab this process holds; required for a tab held by another process or one claimed explicitly. Auto-acquired under CDP_REQUIRE_LEASE (then pass target, not lease). See server instructions.",
-      "all": "Include non-page targets (service/shared workers, background pages); default false lists page-type tabs only.",
+      "all": "Include non-page targets (service/shared workers, background pages, out-of-process (OOPIF) iframes); default false lists page-type tabs only. A returned non-page targetId is accepted as a bare id by any tool's `target` param.",
       "probe": "Ping each page-type renderer before returning, one bounded 500ms check per target and never more, so a wedged tab can't stall the listing. Adds 'responsive' (false on timeout/exception/unreachable, never an error for the whole call) and, where the same round trip finds human input, humanActiveMs. Default false. On a backend that cannot answer the ping, responsive is absent too (not false)."
     }
   },
@@ -107,7 +107,7 @@ export const TOOL_DOCS: Record<string, ToolDoc> = {
     }
   },
   "take_snapshot": {
-    "description": "Captures the page's accessibility tree as an indented text tree, each line prefixed [uid] (a CDP backendDOMNodeId). Every interaction tool (click/hover/fill/etc.) resolves that uid via DOM.resolveNode — run this first to discover uids to act on.",
+    "description": "Captures the page's accessibility tree as an indented text tree, each line prefixed [uid] (a CDP backendDOMNodeId). Every interaction tool (click/hover/fill/etc.) resolves that uid via DOM.resolveNode — run this first to discover uids to act on. Cross-origin iframe subtrees are not walked (they live in a separate renderer process); the iframe node itself is emitted with a frame=\"<targetId>\" marker (also in interactiveOnly mode), so the frame is discoverable and driveable via that id or frame:<url-substring>.",
     "params": {
       "lease": "Lease token from claim_page. Omit for a tab this process holds; required for a tab held by another process or one claimed explicitly. Auto-acquired under CDP_REQUIRE_LEASE (then pass target, not lease). See server instructions.",
       "target": "Page selector: 'active' (default), 'index:N', 'url:<substr>', 'title:<substr>', 'label:<name>', or a 32-hex '<targetId>'. Grammar: see server instructions.",

package/src/types.ts

@@ -63,6 +63,19 @@ export interface CdpEvent<P = Record<string, unknown>> {
  *     listing, because a worker is not a page target — and a worker that is
  *     idle-evicted is in no listing at all, which is what `wake` exists for.
  *     See src/workers.ts and src/cdp/workers.ts.
+ *   - "frame:<substring>"    -> the out-of-process (cross-origin) IFRAME target
+ *     whose url contains the substring (site isolation gives an OOPIF its own
+ *     process and its own target, type "iframe"). Chrome-only, like "worker:",
+ *     but accepted by EVERY target-taking tool except the four page-only ones
+ *     (close/select/release/claim act on the embedder tab): the arm lives in
+ *     pickTarget itself, the one resolver every Chrome tool's target flows
+ *     through, so no per-tool wiring was needed or added. Reads the UNFILTERED
+ *     listing; a SAME-ORIGIN iframe is not a target at all (it runs inside its
+ *     parent page) and can only be reached through the parent. Refused with a
+ *     capability error on Firefox (no iframe targets exist in BiDi's context
+ *     model) and by the page-only resolvers. See src/frames.ts. A bare iframe
+ *     targetId from list_pages{all:true} also still resolves via the bare-id
+ *     arm below.
  */
 export type TargetSelector = string | undefined;
 

package/src/version.ts

@@ -6,4 +6,4 @@
  * ready line; keeping it in its own module means a release bump touches one
  * line here plus package.json, not a const buried in the server.
  */
-export const VERSION = "2.6.0";
+export const VERSION = "2.7.0";