cdp-toolkit 2.6.0 → 3.0.0

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;