cdp-toolkit 2.5.1 → 2.7.0

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();
@@ -3697,6 +3744,15 @@ var init_driver2 = __esm(() => {
 // src/mcp.ts
 import { Server } from "@modelcontextprotocol/server";
 import { serveStdio } from "@modelcontextprotocol/server/stdio";
+import {
+  createMcpHandler,
+  hostHeaderValidationResponse,
+  localhostAllowedHostnames,
+  localhostAllowedOrigins,
+  originValidationResponse
+} from "@modelcontextprotocol/server";
+import { realpathSync } from "node:fs";
+import { fileURLToPath as fileURLToPath2 } from "node:url";
 
 // src/cdp/driver.ts
 init_client();
@@ -4166,7 +4222,8 @@ var CDP_CAPABILITIES = new Set([
   "emulate.focus",
   "browser.downloads",
   "browser.permissions",
-  "worker.targets"
+  "worker.targets",
+  "frame.targets"
 ]);
 
 class CdpPageDriver {
@@ -4299,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);
@@ -4307,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 ?? []) {
@@ -4324,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));
   }
@@ -5501,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";
 
@@ -5557,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;
@@ -8396,7 +8478,7 @@ var MANIFEST = [
         },
         all: {
           type: "boolean",
-          description: "Include non-page targets."
+          description: "Include non-page targets (workers, iframes)."
         },
         probe: {
           type: "boolean",
@@ -10769,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)."
     }
   },
@@ -10873,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.",
@@ -11271,9 +11353,48 @@ var TOOL_DOCS = {
 };
 
 // src/version.ts
-var VERSION = "2.5.1";
+var VERSION = "2.7.0";
 
 // src/mcp.ts
+function isDirectRun() {
+  const entry = process.argv[1];
+  if (!entry)
+    return false;
+  try {
+    return fileURLToPath2(import.meta.url) === realpathSync(entry);
+  } catch {
+    return false;
+  }
+}
+function parseServeOptions(argv) {
+  const out = { transport: "stdio", port: 3000, host: "127.0.0.1" };
+  const transportIdx = argv.indexOf("--transport");
+  if (transportIdx !== -1) {
+    const value = argv[transportIdx + 1];
+    if (value !== "stdio" && value !== "streamable-http") {
+      throw new Error(`unknown --transport '${value ?? ""}': expected 'stdio' or 'streamable-http'`);
+    }
+    out.transport = value;
+  }
+  const portIdx = argv.indexOf("--port");
+  if (portIdx !== -1) {
+    const raw = argv[portIdx + 1];
+    const port = Number(raw);
+    if (raw === undefined || !/^\d+$/.test(raw) || port < 0 || port > 65535) {
+      throw new Error(`invalid --port '${raw ?? ""}': expected an integer 0-65535`);
+    }
+    out.port = port;
+  }
+  const hostIdx = argv.indexOf("--host");
+  if (hostIdx !== -1) {
+    const raw = argv[hostIdx + 1];
+    if (raw === undefined || raw === "") {
+      throw new Error(`invalid --host '${raw ?? ""}': expected a hostname or address`);
+    }
+    out.host = raw;
+  }
+  return out;
+}
 var { kind: BROWSER, endpoint: FIREFOX_ENDPOINT } = resolveBackend(process.argv.slice(2));
 var AVAILABILITY = toolAvailability(BROWSER);
 var AVAILABLE_NAMES = new Set(AVAILABILITY.available);
@@ -11292,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(`
 
@@ -11407,25 +11528,64 @@ function buildServer() {
   });
   return server;
 }
-auditCoverage();
-markLongLivedProcess();
-var handle = serveStdio(({ era }) => {
-  console.error(`[cdp-toolkit] connection pinned to the ${era} protocol era`);
-  return buildServer();
-}, { onerror: (err) => console.error(`[cdp-toolkit] stdio: ${err.message}`) });
-console.error(`[cdp-toolkit] MCP server v${VERSION} ready, browser=${BROWSER}${FIREFOX_ENDPOINT ? ` (attach ${FIREFOX_ENDPOINT})` : ""}, ${AVAILABILITY.available.length} tools available, ${LISTING.length} listed (CDP_TOOL_PROFILE=${PROFILE.label}), CDP_BASE=${BASE}`);
-var shuttingDown = false;
-async function shutdown() {
-  if (shuttingDown)
-    return;
-  shuttingDown = true;
-  await disposeFirefoxSession();
-  await disposeBrowserSession();
-  await handle.close().catch(() => {
+async function run2(argv) {
+  const serve = parseServeOptions(argv);
+  auditCoverage();
+  markLongLivedProcess();
+  let stdioHandle;
+  let httpHandler;
+  let listener;
+  let shuttingDown = false;
+  async function shutdown() {
+    if (shuttingDown)
+      return;
+    shuttingDown = true;
+    await disposeFirefoxSession();
+    await disposeBrowserSession();
+    if (stdioHandle)
+      await stdioHandle.close().catch(() => {
+        return;
+      });
+    if (httpHandler)
+      await httpHandler.close().catch(() => {
+        return;
+      });
+    if (listener)
+      listener.stop();
+    process.exit(0);
+  }
+  process.on("SIGINT", () => void shutdown());
+  process.on("SIGTERM", () => void shutdown());
+  if (serve.transport === "stdio") {
+    stdioHandle = serveStdio(({ era }) => {
+      console.error(`[cdp-toolkit] connection pinned to the ${era} protocol era`);
+      return buildServer();
+    }, { onerror: (err) => console.error(`[cdp-toolkit] stdio: ${err.message}`) });
+    process.stdin.on("close", () => void shutdown());
+    console.error(`[cdp-toolkit] MCP server v${VERSION} ready, browser=${BROWSER}${FIREFOX_ENDPOINT ? ` (attach ${FIREFOX_ENDPOINT})` : ""}, ${AVAILABILITY.available.length} tools available, ${LISTING.length} listed (CDP_TOOL_PROFILE=${PROFILE.label}), CDP_BASE=${BASE}`);
     return;
+  }
+  if (typeof Bun === "undefined") {
+    console.error("[cdp-toolkit] --transport streamable-http needs Bun's HTTP listener (Bun.serve). Re-run with bun, or use the default stdio transport.");
+    process.exit(1);
+  }
+  httpHandler = createMcpHandler(({ era }) => {
+    console.error(`[cdp-toolkit] connection pinned to the ${era} protocol era`);
+    return buildServer();
+  }, { onerror: (err) => console.error(`[cdp-toolkit] http: ${err.message}`) });
+  listener = Bun.serve({
+    port: serve.port,
+    hostname: serve.host,
+    fetch: (req) => hostHeaderValidationResponse(req, localhostAllowedHostnames()) ?? originValidationResponse(req, localhostAllowedOrigins()) ?? httpHandler.fetch(req)
+  });
+  console.error(`[cdp-toolkit] MCP server v${VERSION} listening on streamable-http port ${listener.port} (http://${serve.host}:${listener.port}/), browser=${BROWSER}${FIREFOX_ENDPOINT ? ` (attach ${FIREFOX_ENDPOINT})` : ""}, ${AVAILABILITY.available.length} tools available, ${LISTING.length} listed (CDP_TOOL_PROFILE=${PROFILE.label}), CDP_BASE=${BASE}`);
+}
+if (isDirectRun()) {
+  run2(process.argv.slice(2)).catch((err) => {
+    console.error(`[cdp-toolkit] ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
   });
-  process.exit(0);
 }
-process.on("SIGINT", () => void shutdown());
-process.on("SIGTERM", () => void shutdown());
-process.stdin.on("close", () => void shutdown());
+export {
+  buildServer
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cdp-toolkit",
-  "version": "2.5.1",
+  "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",
@@ -73,6 +73,7 @@
     "mcp": "bun run ./src/mcp.ts",
     "typecheck": "tsc --noEmit",
     "test": "bun test",
+    "test:runtime": "bun test test/runtime-entry.test.ts",
     "smoke": "bun run ./test/smoke.ts",
     "mock:smoke": "bun run ./test/mock-smoke.ts",
     "screencast:smoke": "bun run ./test/screencast-smoke.ts",

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/cli.ts

@@ -29,6 +29,26 @@ import { FIREFOX_TOOLS } from "./firefox-tools.ts";
 import { leaseFromArgs, withLeaseScope } from "./leases.ts";
 import { MANIFEST } from "./manifest.ts";
 import { runInstaller } from "./install/wizard.ts";
+import { realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+/**
+ * True when this module is the process's entry script — the ONLY condition under which main()
+ * runs. Works under both node and bun, ESM included: compare this module's real path with the
+ * realpath of argv[1] (realpath resolves the bunx/npm bin symlink and any /tmp-style symlinked
+ * directory). Importing this module (tests, embedders) leaves argv[1] pointing elsewhere, so the
+ * import stays silent — no tool dispatch, no usage message.
+ */
+function isDirectRun(): boolean {
+  const entry = process.argv[1];
+  if (!entry) return false;
+  try {
+    return fileURLToPath(import.meta.url) === realpathSync(entry);
+  } catch {
+    // argv[1] may not exist as a file (eval strings, wrappers); never treat that as direct.
+    return false;
+  }
+}
 
 const USAGE = `cdp-toolkit: raw single-target CDP, 29-tool chrome-devtools-mcp parity, plus a Firefox backend over WebDriver BiDi.
 
@@ -330,10 +350,12 @@ async function main(): Promise<number> {
   });
 }
 
-main()
-  .then((code) => process.exit(code))
-  .catch((err: unknown) => {
-    const message = err instanceof Error ? err.message : String(err);
-    process.stderr.write(`${JSON.stringify({ error: message })}\n`);
-    process.exit(1);
-  });
+if (isDirectRun()) {
+  main()
+    .then((code) => process.exit(code))
+    .catch((err: unknown) => {
+      const message = err instanceof Error ? err.message : String(err);
+      process.stderr.write(`${JSON.stringify({ error: message })}\n`);
+      process.exit(1);
+    });
+}

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