local-operator-ui 0.32.13 → 0.33.0

package/out/main/index.js

@@ -18758,6 +18758,8 @@ function deadline(op, ms, what) {
 }
 const PROTOCOL_VERSION = "1.3";
 const ALREADY_ATTACHED = /another debugger|already attached/i;
+const STALE_SESSION = /no session|session with given id|no target|target closed/i;
+const FRAME_DETACHED = "frame_detached";
 class CdpPool {
   constructor(options = {}) {
     this.options = options;
@@ -18765,6 +18767,19 @@ class CdpPool {
   attachments = /* @__PURE__ */ new Map();
   /** Per-view CDP event subscribers, by webContents id. See `subscribe`. */
   subscribers = /* @__PURE__ */ new Map();
+  /**
+   * Child-frame sessions, by webContents id then frameId (an out-of-process
+   * iframe's frameId IS its targetId — measured, ARCH-1). Attached on demand and
+   * cached rather than auto-attached: a standing `Target.setAutoAttach` attaches
+   * to every ad frame on every driven page and, with `waitForDebuggerOnStart`,
+   * can hang a page whose resume is missed. Dropped on `detachedFromTarget`, on
+   * a stale-session error, and with the page's own attachment — a child session
+   * never outlives its parent.
+   */
+  frames = /* @__PURE__ */ new Map();
+  /** Attaches in flight, by `<webContentsId>:<frameId>`, shared by concurrent
+   * callers (see `attachFrame`). */
+  frameAttaches = /* @__PURE__ */ new Map();
   /**
    * Observe this view's CDP events for as long as the returned function has not
    * been called.
@@ -18814,6 +18829,7 @@ class CdpPool {
     const existing = this.attachments.get(contents.id);
     if (existing && existing.detachedReason === null) return;
     if (existing) this.releaseListeners(existing);
+    this.frames.delete(contents.id);
     if (!contents.getURL()) {
       await deadline(
         contents.loadURL("about:blank"),
@@ -18839,7 +18855,14 @@ class CdpPool {
         );
       }
     }
-    const messageListener = (_event, method, params) => {
+    const messageListener = (_event, method, params, sessionId2) => {
+      if (sessionId2) return;
+      if (method === "Target.detachedFromTarget") {
+        this.dropFrameSession(
+          contents.id,
+          String(params?.sessionId ?? "")
+        );
+      }
       this.routeEvent(
         contents.id,
         method,
@@ -18848,6 +18871,7 @@ class CdpPool {
     };
     const detachListener = (_event, reason) => {
       attachment.detachedReason = reason || "detached";
+      this.frames.delete(contents.id);
       this.options.log?.(
         `[browser] debugger detached from view ${contents.id}: ${reason}`
       );
@@ -18911,10 +18935,86 @@ class CdpPool {
       contents,
       method,
       params,
-      options.deadlineMs ?? CDP_DEADLINE_MS
+      options.deadlineMs ?? CDP_DEADLINE_MS,
+      options.sessionId
     );
   }
-  async sendTo(contents, method, params, deadlineMs) {
+  /**
+   * The flattened session for one child frame, attached on first use.
+   *
+   * Attached from the PAGE session even for a grandchild (measured: the top
+   * session reaches any frame target by id). Focus emulation goes to the child
+   * for the reason `attach` gives it to the page: `Input.insertText` on an
+   * unfocused target delivers but never replies. `Fetch` is NEVER enabled on a
+   * child: a pause nobody continues would hang the frame.
+   */
+  async attachFrame(contents, frameId) {
+    const cached2 = this.frames.get(contents.id)?.get(frameId);
+    if (cached2) return cached2;
+    const key = `${contents.id}:${frameId}`;
+    const pending = this.frameAttaches.get(key);
+    if (pending) return pending;
+    const attaching = this.openFrameSession(contents, frameId).finally(() => {
+      this.frameAttaches.delete(key);
+    });
+    this.frameAttaches.set(key, attaching);
+    return attaching;
+  }
+  async openFrameSession(contents, frameId) {
+    let attached;
+    try {
+      attached = await this.send(
+        contents,
+        "Target.attachToTarget",
+        { targetId: frameId, flatten: true }
+      );
+    } catch (error) {
+      if (error instanceof BridgeCommandError) throw error;
+      throw new BridgeCommandError(
+        "element_not_found",
+        "that frame is gone or still loading; take a new snapshot and retry",
+        { reason: FRAME_DETACHED }
+      );
+    }
+    const sessionId2 = attached?.sessionId;
+    if (!sessionId2) {
+      throw new BridgeCommandError(
+        "element_not_found",
+        "that frame could not be attached to; take a new snapshot and retry",
+        { reason: FRAME_DETACHED }
+      );
+    }
+    try {
+      await this.send(
+        contents,
+        "Emulation.setFocusEmulationEnabled",
+        { enabled: true },
+        { sessionId: sessionId2 }
+      );
+    } catch (error) {
+      if (!(error instanceof BridgeCommandError && error.data?.reason === FRAME_DETACHED)) {
+        await this.send(contents, "Target.detachFromTarget", {
+          sessionId: sessionId2
+        }).catch(() => void 0);
+      }
+      throw error;
+    }
+    let sessions = this.frames.get(contents.id);
+    if (!sessions) {
+      sessions = /* @__PURE__ */ new Map();
+      this.frames.set(contents.id, sessions);
+    }
+    sessions.set(frameId, sessionId2);
+    return sessionId2;
+  }
+  dropFrameSession(webContentsId, sessionId2) {
+    const sessions = this.frames.get(webContentsId);
+    if (!sessions || !sessionId2) return;
+    for (const [frameId, cached2] of sessions) {
+      if (cached2 === sessionId2) sessions.delete(frameId);
+    }
+  }
+  async sendTo(contents, method, params, deadlineMs, sessionId2) {
     const attachment = this.attachments.get(contents.id);
     if (!attachment) {
       throw new BridgeCommandError(
@@ -18930,11 +19030,29 @@ class CdpPool {
         { reason: attachment.detachedReason }
       );
     }
-    return deadline(
-      contents.debugger.sendCommand(method, params),
-      deadlineMs,
-      method
-    );
+    if (!sessionId2) {
+      return deadline(
+        contents.debugger.sendCommand(method, params),
+        deadlineMs,
+        method
+      );
+    }
+    try {
+      return await deadline(
+        contents.debugger.sendCommand(method, params, sessionId2),
+        deadlineMs,
+        method
+      );
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      if (!STALE_SESSION.test(message)) throw error;
+      this.dropFrameSession(contents.id, sessionId2);
+      throw new BridgeCommandError(
+        "element_not_found",
+        "that frame navigated or closed while it was being driven; retry",
+        { reason: FRAME_DETACHED }
+      );
+    }
   }
   /** Remove this attachment's debugger listeners. Called before the record is
    * replaced by a re-`attach` and before it is dropped, so a view is never left
@@ -18957,6 +19075,7 @@ class CdpPool {
     if (attachment) this.releaseListeners(attachment);
     this.attachments.delete(webContentsId);
     this.subscribers.delete(webContentsId);
+    this.frames.delete(webContentsId);
     stopLogCapture(webContentsId);
   }
   /** Detach cleanly: release the debugger session and the log buffer. */
@@ -18965,6 +19084,7 @@ class CdpPool {
     if (attachment) this.releaseListeners(attachment);
     this.attachments.delete(webContentsId);
     this.subscribers.delete(webContentsId);
+    this.frames.delete(webContentsId);
     stopLogCapture(webContentsId);
     if (!attachment) return;
     try {
@@ -19080,15 +19200,15 @@ async function withOriginGate(ctx, view, requester, approved, operation) {
   const contents = view.webContents;
   const blocked = [];
   const seen = /* @__PURE__ */ new Set();
-  const frameTree = await resolveMainFrameId(ctx, contents);
-  const mainFrameId = frameTree.mainFrameId;
+  const frameTree2 = await resolveMainFrameId(ctx, contents);
+  const mainFrameId = frameTree2.mainFrameId;
   if (mainFrameId === null) {
     ctx.log(
       `[browser] could not read the frame tree for ${requester}; this navigation is gated on every Document request, which may refuse cross-origin frames the page needs${// The domain's state travels with the fallback because it is not
       // inferable from the failure: an enable that resolved and a read that
       // did not left `Page` armed, an enable that never resolved did not
       // (agent review round 2, R3).
-      frameTree.pageEnabled ? " (the Page domain may still be enabled)" : ""}`
+      frameTree2.pageEnabled ? " (the Page domain may still be enabled)" : ""}`
     );
   }
   let unattributed = 0;
@@ -19160,7 +19280,7 @@ async function withOriginGate(ctx, view, requester, approved, operation) {
       await ctx.cdp.send(contents, "Fetch.disable", {});
     } catch {
     }
-    if (frameTree.pageEnabled) {
+    if (frameTree2.pageEnabled) {
       try {
         await ctx.cdp.send(contents, "Page.disable", {});
       } catch {
@@ -19191,6 +19311,399 @@ function pageOf(view) {
     title: view.webContents.isDestroyed() ? "" : view.webContents.getTitle()
   };
 }
+const FRAME_HOP = ">>>";
+const MAX_FRAME_DEPTH = 3;
+const MAX_FRAMES_SEARCHED = 20;
+function sendIn(ctx, contents, sessionId2, method, params) {
+  return sessionId2 ? ctx.cdp.send(contents, method, params, { sessionId: sessionId2 }) : ctx.cdp.send(contents, method, params);
+}
+function parseFrameHops(target2) {
+  if (!target2.includes(FRAME_HOP)) return null;
+  const hops = splitTopLevel(target2);
+  if (hops.length === 1) return null;
+  if (hops.some((hop) => hop === "")) {
+    throw new BridgeCommandError(
+      "element_not_found",
+      `${target2} has an empty side of '${FRAME_HOP}'; write it as <iframe-selector> ${FRAME_HOP} <selector>`
+    );
+  }
+  if (hops.length - 1 > MAX_FRAME_DEPTH) {
+    throw new BridgeCommandError(
+      "element_not_found",
+      `${target2} hops through ${hops.length - 1} frames; at most ${MAX_FRAME_DEPTH} are followed`
+    );
+  }
+  return hops;
+}
+function splitTopLevel(target2) {
+  const parts = [];
+  let quote = null;
+  let depth = 0;
+  let start = 0;
+  for (let i = 0; i < target2.length; i += 1) {
+    const ch = target2[i];
+    if (ch === "\\") {
+      i += 1;
+      continue;
+    }
+    if (quote) {
+      if (ch === quote) quote = null;
+      continue;
+    }
+    if (ch === '"' || ch === "'") quote = ch;
+    else if (ch === "[" || ch === "(") depth += 1;
+    else if ((ch === "]" || ch === ")") && depth > 0) depth -= 1;
+    else if (depth === 0 && target2.startsWith(FRAME_HOP, i)) {
+      parts.push(target2.slice(start, i).trim());
+      i += FRAME_HOP.length - 1;
+      start = i + 1;
+    }
+  }
+  parts.push(target2.slice(start).trim());
+  return parts;
+}
+function assertFrameNotDenied(ctx, scope) {
+  if (!isDeniedFrame(ctx, scope)) return;
+  throw new BridgeCommandError(
+    "origin_not_allowed",
+    `the user denied ${scope.origin} for agent access, and that element is inside a frame from it`,
+    { origin: scope.origin, reason: "denied" }
+  );
+}
+function isDeniedRefusal(error) {
+  return error instanceof BridgeCommandError && error.code === "origin_not_allowed" && error.data?.reason === "denied";
+}
+function isDeniedFrame(ctx, scope) {
+  if (!scope.origin) return false;
+  let url;
+  try {
+    url = new URL(scope.origin);
+  } catch {
+    return false;
+  }
+  return ctx.approvals?.refusalReason(url) === "denied";
+}
+function isFatalWalkError(error) {
+  return error instanceof BridgeCommandError && (error.code === "debugger_conflict" || error.code === "tab_closed");
+}
+async function topScope(ctx, contents) {
+  const document = await ctx.cdp.send(
+    contents,
+    "DOM.getDocument",
+    { depth: 0 }
+  );
+  const rootNodeId = document?.root?.nodeId;
+  if (rootNodeId === void 0) {
+    throw new BridgeCommandError("internal", "the page has no document to query");
+  }
+  return { rootNodeId, hops: [], path: [] };
+}
+async function queryIn(ctx, contents, scope, selector) {
+  const queried = await sendIn(
+    ctx,
+    contents,
+    scope.sessionId,
+    "DOM.querySelector",
+    { nodeId: scope.rootNodeId, selector }
+  );
+  return queried?.nodeId ?? 0;
+}
+const FRAME_NODE_NAMES = /* @__PURE__ */ new Set(["IFRAME", "FRAME"]);
+function originOf(url) {
+  if (!url) return void 0;
+  try {
+    return new URL(url).origin;
+  } catch {
+    return void 0;
+  }
+}
+const PLAIN_ID = /^[A-Za-z_][\w-]*$/;
+function frameSelectorFor(attributes = []) {
+  const attrs = /* @__PURE__ */ new Map();
+  for (let i = 0; i + 1 < attributes.length; i += 2) {
+    attrs.set(attributes[i], attributes[i + 1]);
+  }
+  const id2 = attrs.get("id");
+  if (id2 && PLAIN_ID.test(id2)) return `iframe#${id2}`;
+  for (const key of ["name", "title", "src"]) {
+    const value = attrs.get(key);
+    if (value) return `iframe[${key}=${JSON.stringify(value)}]`;
+  }
+  return "iframe";
+}
+async function enterFrame(ctx, contents, parent, iframeNodeId) {
+  const described = await sendIn(
+    ctx,
+    contents,
+    parent.sessionId,
+    "DOM.describeNode",
+    { nodeId: iframeNodeId, depth: 1 }
+  );
+  const node = described?.node;
+  if (!node || !FRAME_NODE_NAMES.has(String(node.nodeName).toUpperCase())) {
+    throw new BridgeCommandError(
+      "element_not_found",
+      "that element is not an iframe, so there is no frame to step into",
+      { reason: NOT_A_FRAME }
+    );
+  }
+  const hops = [
+    ...parent.hops,
+    { sessionId: parent.sessionId, nodeId: iframeNodeId }
+  ];
+  const path2 = [...parent.path, frameSelectorFor(node.attributes)];
+  const inProcess = node.contentDocument?.backendNodeId;
+  if (inProcess !== void 0) {
+    assertFrameNotDenied(ctx, {
+      origin: originOf(node.contentDocument?.documentURL)
+    });
+    const pushed = await sendIn(
+      ctx,
+      contents,
+      parent.sessionId,
+      "DOM.pushNodesByBackendIdsToFrontend",
+      { backendNodeIds: [inProcess] }
+    );
+    const rootNodeId = pushed?.nodeIds?.[0];
+    if (!rootNodeId) {
+      throw new BridgeCommandError(
+        "element_not_found",
+        "that frame has no document yet; retry once it has loaded"
+      );
+    }
+    return {
+      sessionId: parent.sessionId,
+      frameTargetId: parent.frameTargetId,
+      frameId: node.frameId,
+      rootNodeId,
+      origin: originOf(node.contentDocument?.documentURL),
+      hops,
+      path: path2
+    };
+  }
+  const frameId = node.frameId;
+  if (!frameId) {
+    throw new BridgeCommandError(
+      "element_not_found",
+      "that frame has no document yet; retry once it has loaded"
+    );
+  }
+  const rooted = await childRoot(ctx, contents, frameId);
+  assertFrameNotDenied(ctx, { origin: rooted.origin });
+  return {
+    sessionId: rooted.sessionId,
+    frameTargetId: frameId,
+    frameId,
+    rootNodeId: rooted.rootNodeId,
+    origin: rooted.origin,
+    hops,
+    path: path2
+  };
+}
+async function childRoot(ctx, contents, frameId) {
+  for (let attempt = 0; ; attempt += 1) {
+    try {
+      const sessionId2 = await ctx.cdp.attachFrame(contents, frameId);
+      const document = await ctx.cdp.send(contents, "DOM.getDocument", { depth: 0 }, { sessionId: sessionId2 });
+      const rootNodeId = document?.root?.nodeId;
+      if (rootNodeId === void 0) {
+        throw new BridgeCommandError(
+          "element_not_found",
+          "that frame has no document yet; retry once it has loaded"
+        );
+      }
+      return {
+        sessionId: sessionId2,
+        rootNodeId,
+        origin: originOf(document?.root?.documentURL)
+      };
+    } catch (error) {
+      if (attempt === 0 && isFrameDetached(error)) continue;
+      throw error;
+    }
+  }
+}
+const NOT_A_FRAME = "not_a_frame";
+function isNotAFrame(error) {
+  return error instanceof BridgeCommandError && error.data?.reason === NOT_A_FRAME;
+}
+function isFrameDetached(error) {
+  return error instanceof BridgeCommandError && error.data?.reason === FRAME_DETACHED;
+}
+async function resolveHops(ctx, contents, hops) {
+  let scope = await topScope(ctx, contents);
+  for (const hop of hops.slice(0, -1)) {
+    const iframe = await queryIn(ctx, contents, scope, hop);
+    if (!iframe) {
+      throw new BridgeCommandError(
+        "element_not_found",
+        `frame selector ${hop} matched nothing`
+      );
+    }
+    scope = await enterFrame(ctx, contents, scope, iframe).catch((error) => {
+      if (isNotAFrame(error)) {
+        throw new BridgeCommandError(
+          "element_not_found",
+          `${hop} is not an iframe, so '${FRAME_HOP}' cannot step into it`
+        );
+      }
+      throw error;
+    });
+  }
+  const selector = hops[hops.length - 1];
+  const nodeId = await queryIn(ctx, contents, scope, selector);
+  if (!nodeId) {
+    throw new BridgeCommandError(
+      "element_not_found",
+      `selector ${selector} matched nothing inside ${hops.slice(0, -1).join(` ${FRAME_HOP} `)}`
+    );
+  }
+  return { scope, nodeId };
+}
+async function searchFrames(ctx, contents, selector) {
+  const matches = [];
+  const walk = await listFrames(ctx, contents);
+  for (const scope of walk.frames) {
+    const nodeId = await queryIn(ctx, contents, scope, selector).catch(
+      (error) => {
+        if (isFatalWalkError(error)) throw error;
+        return 0;
+      }
+    );
+    if (nodeId) matches.push({ scope, nodeId });
+  }
+  return { matches, walk };
+}
+async function listFrames(ctx, contents) {
+  const walk = {
+    frames: [],
+    truncated: false,
+    skipped: 0,
+    denied: 0
+  };
+  let level = [await topScope(ctx, contents)];
+  for (let depth = 0; depth < MAX_FRAME_DEPTH && level.length; depth += 1) {
+    const next = [];
+    for (const parent of level) {
+      const listed = await sendIn(
+        ctx,
+        contents,
+        parent.sessionId,
+        "DOM.querySelectorAll",
+        { nodeId: parent.rootNodeId, selector: "iframe, frame" }
+      );
+      for (const iframe of listed?.nodeIds ?? []) {
+        if (walk.frames.length + walk.skipped >= MAX_FRAMES_SEARCHED) {
+          walk.truncated = true;
+          return walk;
+        }
+        let scope;
+        try {
+          scope = await enterFrame(ctx, contents, parent, iframe);
+        } catch (error) {
+          if (isFatalWalkError(error)) throw error;
+          if (isDeniedRefusal(error)) {
+            walk.denied += 1;
+            continue;
+          }
+          if (error instanceof BridgeCommandError) {
+            walk.skipped += 1;
+            continue;
+          }
+          throw error;
+        }
+        walk.frames.push(scope);
+        next.push(scope);
+      }
+    }
+    level = next;
+  }
+  return walk;
+}
+function candidatePath(scope, selector) {
+  return [...scope.path, selector].join(` ${FRAME_HOP} `);
+}
+const EDITABLE_SELECTOR = 'input:not([type=hidden]):not([type=button]):not([type=submit]):not([type=reset]):not([type=checkbox]):not([type=radio]):not([type=file]):not([type=image]):not([type=range]):not([type=color]):not([disabled]):not([readonly]), textarea:not([disabled]):not([readonly]), [contenteditable]:not([contenteditable="false"])';
+const FRAME_EDITABLE_FUNCTION_SOURCE = `function (selector, mode) {
+  const all = Array.from(this.querySelectorAll(selector));
+  if (mode === 'active') {
+    const active = this.activeElement;
+    return active && all.indexOf(active) !== -1 ? active : null;
+  }
+  if (mode === 'only') return all.length === 1 ? all[0] : null;
+  return all.map(function (el) {
+    const tag = String(el.tagName || '').toLowerCase();
+    if (el.id && /^[A-Za-z_][\\w-]*$/.test(el.id)) return '#' + el.id;
+    const name = el.getAttribute && el.getAttribute('name');
+    if (name) return tag + '[name=' + JSON.stringify(name) + ']';
+    // A real selector, not a label: the n-th element of its tag under its parent,
+    // walked up to the document so the path is unique and addressable.
+    const steps = [];
+    for (let node = el; node && node.nodeType === 1 && node.tagName; node = node.parentElement) {
+      const name2 = String(node.tagName).toLowerCase();
+      let nth = 1;
+      for (let sib = node.previousElementSibling; sib; sib = sib.previousElementSibling) {
+        if (sib.tagName === node.tagName) nth += 1;
+      }
+      steps.unshift(name2 + ':nth-of-type(' + nth + ')');
+      if (name2 === 'html') break;
+    }
+    return steps.length ? steps.join(' > ') : tag;
+  });
+}`;
+async function editableInFrame(ctx, contents, scope, target2) {
+  const documentObject = await sendIn(
+    ctx,
+    contents,
+    scope.sessionId,
+    "DOM.resolveNode",
+    { nodeId: scope.rootNodeId }
+  );
+  const documentId = documentObject?.object?.objectId;
+  if (!documentId) {
+    throw new BridgeCommandError(
+      "element_not_found",
+      `could not read the document inside ${target2}`
+    );
+  }
+  const pick = (mode, returnByValue) => sendIn(
+    ctx,
+    contents,
+    scope.sessionId,
+    "Runtime.callFunctionOn",
+    {
+      objectId: documentId,
+      functionDeclaration: FRAME_EDITABLE_FUNCTION_SOURCE,
+      arguments: [{ value: EDITABLE_SELECTOR }, { value: mode }],
+      returnByValue
+    }
+  );
+  let objectId = (await pick("active", false))?.result?.objectId;
+  if (!objectId) objectId = (await pick("only", false))?.result?.objectId;
+  if (!objectId) {
+    const listed = (await pick("list", true))?.result?.value;
+    const fields = Array.isArray(listed) ? listed.map(String) : [];
+    if (fields.length === 0) {
+      throw new BridgeCommandError(
+        "element_not_found",
+        `${target2} is not an editable field (no value setter, not contenteditable), so nothing was typed; it is an iframe and its document holds no editable field either`
+      );
+    }
+    throw new BridgeCommandError(
+      "element_not_found",
+      `${target2} is an iframe holding ${fields.length} editable fields, so nothing was typed; name one: ${fields.map((field) => candidatePath(scope, field)).join(", ")}`,
+      { candidates: fields.map((field) => candidatePath(scope, field)) }
+    );
+  }
+  const requested = await sendIn(
+    ctx,
+    contents,
+    scope.sessionId,
+    "DOM.requestNode",
+    { objectId }
+  );
+  return { nodeId: requested?.nodeId ?? 0, objectId };
+}
 const LANDMARKS = /* @__PURE__ */ new Set(["banner", "main", "navigation", "complementary", "contentinfo", "form", "region"]);
 const INTERACTIVE = /* @__PURE__ */ new Set(["button", "link", "textbox", "checkbox", "radio", "combobox", "menuitem", "tab", "switch", "slider", "spinbutton"]);
 function compactAX(nodes, epoch) {
@@ -19321,7 +19834,16 @@ async function snapshot(ctx, params) {
     await ctx.cdp.send(contents, "Accessibility.disable", {}).catch(() => {
     });
   }
-  const { snapshot: rendered, refs } = compactAX(nodes, record.epoch);
+  const { snapshot: topRendered, refs: topRefs } = compactAX(
+    nodes,
+    record.epoch
+  );
+  const refs = { ...topRefs };
+  let rendered = topRendered;
+  if (nodes.some(isFrameNode)) {
+    const blocks = await frameSnapshots(ctx, record, nodes, refs);
+    if (blocks.length) rendered = [rendered, ...blocks].join("\n");
+  }
   record.refs = refs;
   ctx.registry.touch(record);
   return {
@@ -19331,6 +19853,88 @@ async function snapshot(ctx, params) {
     ...pageOf(record.view)
   };
 }
+function isFrameNode(node) {
+  return node.role?.value === "Iframe" && node.backendDOMNodeId !== void 0;
+}
+const REF_LABEL = /\[e(\d+)\]/g;
+async function frameSnapshots(ctx, record, topNodes, refs) {
+  const contents = record.view.webContents;
+  const blocks = [];
+  let entered = 0;
+  let level = [
+    { scope: await topScope(ctx, contents), nodes: topNodes }
+  ];
+  for (let depth = 0; depth < MAX_FRAME_DEPTH && level.length; depth += 1) {
+    const next = [];
+    for (const { scope: parent, nodes } of level) {
+      for (const frameNode of nodes.filter(isFrameNode)) {
+        if (entered >= MAX_FRAMES_SEARCHED) return blocks;
+        entered += 1;
+        try {
+          const pushed = await sendIn(
+            ctx,
+            contents,
+            parent.sessionId,
+            "DOM.pushNodesByBackendIdsToFrontend",
+            { backendNodeIds: [frameNode.backendDOMNodeId] }
+          );
+          const iframeNodeId = pushed?.nodeIds?.[0];
+          if (!iframeNodeId) continue;
+          const scope = await enterFrame(ctx, contents, parent, iframeNodeId);
+          const frameNodes = await frameTree(ctx, contents, scope);
+          const { snapshot: inner, refs: innerRefs } = compactAX(
+            frameNodes,
+            record.epoch
+          );
+          const offset = Object.keys(refs).length;
+          for (const [name, ref] of Object.entries(innerRefs)) {
+            refs[`e${Number(name.slice(1)) + offset}`] = {
+              ...ref,
+              ...scope.frameTargetId ? { frameId: scope.frameTargetId } : {},
+              frameOrigin: scope.origin ?? ""
+            };
+          }
+          const indent = "  ".repeat(depth);
+          const body = inner.replace(REF_LABEL, (_m, n) => `[e${Number(n) + offset}]`).split("\n").filter(Boolean).map((line) => `${indent}  ${line}`);
+          blocks.push(
+            `${indent}- frame ${scope.path.join(` ${FRAME_HOP} `)}${scope.origin ? ` (${scope.origin})` : ""}:`,
+            ...body
+          );
+          next.push({ scope, nodes: frameNodes });
+        } catch (error) {
+          if (error instanceof BridgeCommandError && error.code !== "debugger_conflict" && error.code !== "tab_closed")
+            continue;
+          throw error;
+        }
+      }
+    }
+    level = next;
+  }
+  return blocks;
+}
+async function frameTree(ctx, contents, scope) {
+  const params = scope.frameTargetId === scope.frameId || !scope.frameId ? {} : { frameId: scope.frameId };
+  await sendIn(ctx, contents, scope.sessionId, "Accessibility.enable", {});
+  try {
+    const tree = await sendIn(
+      ctx,
+      contents,
+      scope.sessionId,
+      "Accessibility.getFullAXTree",
+      params
+    );
+    return Array.isArray(tree?.nodes) ? tree.nodes : [];
+  } finally {
+    await sendIn(
+      ctx,
+      contents,
+      scope.sessionId,
+      "Accessibility.disable",
+      {}
+    ).catch(() => {
+    });
+  }
+}
 const METRICS_EXPRESSION = `(() => {
   const de = document.scrollingElement || document.documentElement;
   const x = window.scrollX, y = window.scrollY;
@@ -19550,11 +20154,13 @@ const READ_VALUE_FUNCTION = `function () {
   return String(this.textContent || '');
 }`;
 const SNAPSHOT_REF = /^e\d+$/;
+function frameFields(node) {
+  return node.frame ? { frame_origin: node.frame.origin ?? "" } : {};
+}
 async function resolveNode(ctx, record, target2) {
   const view = record.view;
   const contents = view.webContents;
   const ref = SNAPSHOT_REF.test(target2) ? record.refs[target2] : void 0;
-  let nodeId;
   if (ref) {
     if (ref.epoch !== record.epoch) {
       throw new BridgeCommandError(
@@ -19562,6 +20168,7 @@ async function resolveNode(ctx, record, target2) {
         "the page navigated since that snapshot; take a new snapshot and retry"
       );
     }
+    if (ref.frameId) return resolveFrameRef(ctx, contents, target2, ref);
     await ctx.cdp.send(contents, "DOM.getDocument", { depth: 0 });
     const pushed = await ctx.cdp.send(
       contents,
@@ -19572,10 +20179,72 @@ async function resolveNode(ctx, record, target2) {
     if (pushedId === void 0) {
       throw new BridgeCommandError("element_not_found", "snapshot ref is stale");
     }
-    nodeId = pushedId;
-  } else {
+    return finishTop(ctx, contents, target2, pushedId, ref.frameOrigin);
+  }
+  const hops = parseFrameHops(target2);
+  if (hops) {
+    const hit = await resolveHops(ctx, contents, hops);
+    return finishInFrame(ctx, contents, target2, hit.scope, hit.nodeId);
+  }
+  let nodeId;
+  try {
     nodeId = await nodeIdForSelector(ctx, view, target2);
+  } catch (error) {
+    if (!(error instanceof BridgeCommandError) || !TOP_MISS.test(error.message)) {
+      throw error;
+    }
+    const { matches, walk } = await searchFrames(ctx, contents, target2);
+    if (matches.length === 0) {
+      if (!walk.truncated && walk.skipped === 0 && walk.denied === 0)
+        throw error;
+      throw new BridgeCommandError(
+        "element_not_found",
+        `selector ${target2} matched nothing in the page itself or the frames searched (${walkNote(walk)}); address the frame explicitly as <iframe-selector> ${FRAME_HOP} <selector>`
+      );
+    }
+    if (matches.length === 1 && (walk.truncated || walk.skipped > 0)) {
+      const candidate = candidatePath(matches[0].scope, target2);
+      throw new BridgeCommandError(
+        "element_not_found",
+        `selector ${target2} matched nothing in the page itself and one element in the frames searched, but not every frame was searched (${walkNote(walk)}), so nothing was done; if this is the one, name it: ${candidate}`,
+        { candidates: [candidate] }
+      );
+    }
+    if (matches.length > 1) {
+      const candidates = matches.map(
+        (match) => candidatePath(match.scope, target2)
+      );
+      throw new BridgeCommandError(
+        "element_not_found",
+        `selector ${target2} matched nothing in the page itself and ${matches.length} elements inside its frames, so nothing was done; name one: ${candidates.join(", ")}`,
+        { candidates }
+      );
+    }
+    return finishInFrame(
+      ctx,
+      contents,
+      target2,
+      matches[0].scope,
+      matches[0].nodeId
+    );
   }
+  return finishTop(ctx, contents, target2, nodeId);
+}
+function walkNote(walk) {
+  const notes = [];
+  if (walk.truncated) notes.push(`stopped at ${MAX_FRAMES_SEARCHED} frames`);
+  if (walk.skipped > 0)
+    notes.push(`${walk.skipped} frame(s) could not be entered`);
+  if (walk.denied > 0)
+    notes.push(
+      `${walk.denied} frame(s) from an origin the user denied were not searched`
+    );
+  return notes.join("; ") || "every frame searched";
+}
+const TOP_MISS = /^selector .* matched nothing$/s;
+async function finishTop(ctx, contents, target2, nodeId, frameOrigin) {
+  if (frameOrigin !== void 0)
+    assertFrameNotDenied(ctx, { origin: frameOrigin });
   await ctx.cdp.send(contents, "DOM.scrollIntoViewIfNeeded", { nodeId });
   const resolved = await ctx.cdp.send(
     contents,
@@ -19589,7 +20258,83 @@ async function resolveNode(ctx, record, target2) {
       `could not resolve ${target2}`
     );
   }
-  return { nodeId, objectId };
+  if (frameOrigin === void 0) return { nodeId, objectId };
+  return {
+    nodeId,
+    objectId,
+    frame: { rootNodeId: 0, origin: frameOrigin, hops: [], path: [] }
+  };
+}
+async function finishInFrame(ctx, contents, target2, scope, nodeId) {
+  assertFrameNotDenied(ctx, scope);
+  for (const hop of scope.hops) {
+    await sendIn(ctx, contents, hop.sessionId, "DOM.scrollIntoViewIfNeeded", {
+      nodeId: hop.nodeId
+    }).catch(() => void 0);
+  }
+  await sendIn(ctx, contents, scope.sessionId, "DOM.scrollIntoViewIfNeeded", {
+    nodeId
+  }).catch(() => void 0);
+  const resolved = await sendIn(
+    ctx,
+    contents,
+    scope.sessionId,
+    "DOM.resolveNode",
+    { nodeId }
+  );
+  const objectId = resolved?.object?.objectId;
+  if (!objectId) {
+    throw new BridgeCommandError(
+      "element_not_found",
+      `could not resolve ${target2}`
+    );
+  }
+  return { nodeId, objectId, sessionId: scope.sessionId, frame: scope };
+}
+async function resolveFrameRef(ctx, contents, target2, ref) {
+  assertFrameNotDenied(ctx, { origin: ref.frameOrigin });
+  let rooted;
+  try {
+    rooted = await childRoot(ctx, contents, String(ref.frameId));
+  } catch (error) {
+    if (isFrameDetached(error)) {
+      throw new BridgeCommandError("element_not_found", "snapshot ref is stale");
+    }
+    throw error;
+  }
+  assertFrameNotDenied(ctx, { origin: rooted.origin });
+  await ctx.cdp.send(contents, "DOM.getFrameOwner", {
+    frameId: ref.frameId
+  }).then(
+    (owner) => owner?.backendNodeId ? ctx.cdp.send(contents, "DOM.scrollIntoViewIfNeeded", {
+      backendNodeId: owner.backendNodeId
+    }) : void 0
+  ).catch(() => void 0);
+  const pushed = await ctx.cdp.send(
+    contents,
+    "DOM.pushNodesByBackendIdsToFrontend",
+    { backendNodeIds: [ref.backendNodeId] },
+    { sessionId: rooted.sessionId }
+  );
+  const nodeId = pushed?.nodeIds?.[0];
+  if (!nodeId) {
+    throw new BridgeCommandError("element_not_found", "snapshot ref is stale");
+  }
+  return finishInFrame(
+    ctx,
+    contents,
+    target2,
+    {
+      sessionId: rooted.sessionId,
+      frameTargetId: ref.frameId,
+      frameId: ref.frameId,
+      rootNodeId: rooted.rootNodeId,
+      origin: ref.frameOrigin ?? rooted.origin,
+      hops: [],
+      path: []
+    },
+    nodeId
+  );
 }
 function targetOf(params) {
   const ref = stringParam(params, "ref");
@@ -19616,7 +20361,7 @@ async function click(ctx, params) {
   };
   contents.on("did-start-navigation", onStart);
   try {
-    await ctx.cdp.send(contents, "Runtime.callFunctionOn", {
+    await sendIn(ctx, contents, node.sessionId, "Runtime.callFunctionOn", {
       objectId: node.objectId,
       functionDeclaration: CLICK_FUNCTION,
       returnByValue: true
@@ -19630,26 +20375,78 @@ async function click(ctx, params) {
   }
   ctx.registry.touch(record);
   const after = pageOf(record.view);
-  return { navigated: navigationSeen || after.url !== before, ...after };
+  return {
+    navigated: navigationSeen || after.url !== before,
+    ...frameFields(node),
+    ...after
+  };
 }
 async function type(ctx, params) {
   const record = ctx.registry.requireSurface(params.tab);
   const contents = record.view.webContents;
-  const node = await resolveNode(ctx, record, targetOf(params));
+  const target2 = targetOf(params);
+  const node = await resolveNode(ctx, record, target2);
   const text = typeof params.text === "string" ? params.text : "";
-  await ctx.cdp.send(contents, "Runtime.callFunctionOn", {
+  const typed = await typeInto(ctx, contents, node, text, target2);
+  if (typed) {
+    ctx.registry.touch(record);
+    return { ...typed, ...frameFields(node), ...pageOf(record.view) };
+  }
+  const frame = await iframeScopeOf(ctx, contents, node);
+  if (frame) {
+    assertFrameNotDenied(ctx, frame);
+    const field = await editableInFrame(ctx, contents, frame, target2);
+    const inner = {
+      nodeId: field.nodeId,
+      objectId: field.objectId,
+      sessionId: frame.sessionId,
+      frame
+    };
+    const typedInFrame = await typeInto(ctx, contents, inner, text, target2);
+    if (typedInFrame) {
+      ctx.registry.touch(record);
+      return {
+        ...typedInFrame,
+        ...frameFields(inner),
+        ...pageOf(record.view)
+      };
+    }
+  }
+  throw new BridgeCommandError(
+    "element_not_found",
+    `${target2} is not an editable field (no value setter, not contenteditable), so nothing was typed${frame ? "; it is an iframe and its document holds no field that took the text either" : `; if the field lives inside an iframe, it cannot be targeted from the top document; address it as <iframe-selector> ${FRAME_HOP} <selector>`}`
+  );
+}
+const NON_ALPHANUMERIC = /[^\p{L}\p{N}]+/gu;
+function foldForComparison(value) {
+  return value.normalize("NFKC").toLowerCase().replace(NON_ALPHANUMERIC, "");
+}
+function holdsTypedText(readBack2, text) {
+  const folded = foldForComparison(text);
+  if (folded === "") return readBack2.includes(text);
+  return foldForComparison(readBack2).includes(folded);
+}
+const SETTLE_BEFORE_REREAD_MS = 100;
+const MAX_QUOTED_READBACK = 80;
+function quoteReadBack(value) {
+  if (value.length <= MAX_QUOTED_READBACK) return `'${value}'`;
+  return `'${value.slice(0, MAX_QUOTED_READBACK)}…' (${value.length} chars)`;
+}
+async function typeInto(ctx, contents, node, text, target2) {
+  await sendIn(ctx, contents, node.sessionId, "Runtime.callFunctionOn", {
     objectId: node.objectId,
     functionDeclaration: FOCUS_AND_SELECT_FUNCTION,
     returnByValue: true
   });
-  await ctx.cdp.send(contents, "Input.insertText", { text });
-  const readBack2 = await conversationReadBack(ctx, node.objectId, contents);
-  if (readBack2.includes(text)) {
-    ctx.registry.touch(record);
-    return { value: readBack2, via: "insert_text", ...pageOf(record.view) };
+  await sendIn(ctx, contents, node.sessionId, "Input.insertText", { text });
+  const readBack2 = await conversationReadBack(ctx, node, contents);
+  if (holdsTypedText(readBack2, text)) {
+    return { value: readBack2, via: "insert_text" };
   }
-  const set2 = await ctx.cdp.send(
+  const set2 = await sendIn(
+    ctx,
     contents,
+    node.sessionId,
     "Runtime.callFunctionOn",
     {
       objectId: node.objectId,
@@ -19659,26 +20456,44 @@ async function type(ctx, params) {
     }
   );
   const setValue = set2?.result?.value;
-  if (setValue === null) {
-    throw new BridgeCommandError(
-      "element_not_found",
-      `${targetOf(params)} is not an editable field (no value setter, not contenteditable), so nothing was typed; if the field lives inside an iframe, it cannot be targeted from the top document`
-    );
+  if (setValue === null) return null;
+  await sleep(SETTLE_BEFORE_REREAD_MS);
+  const settled = await conversationReadBack(ctx, node, contents);
+  if (holdsTypedText(settled, text)) {
+    return {
+      value: settled,
+      via: "value_setter",
+      insert_text_readback: readBack2
+    };
   }
-  ctx.registry.touch(record);
-  return {
-    value: String(setValue ?? readBack2),
-    via: "value_setter",
-    insert_text_readback: readBack2,
-    ...pageOf(record.view)
+  throw new BridgeCommandError(
+    "element_not_found",
+    `${target2} took the value-setter write but does not hold the text (read back ${quoteReadBack(settled)}), so nothing was reported typed`
+  );
+}
+async function iframeScopeOf(ctx, contents, node) {
+  const parent = node.frame ?? {
+    rootNodeId: 0,
+    hops: [],
+    path: []
   };
+  try {
+    return await enterFrame(ctx, contents, parent, node.nodeId);
+  } catch (error) {
+    if (isNotAFrame(error)) {
+      return null;
+    }
+    throw error;
+  }
 }
-async function conversationReadBack(ctx, objectId, contents) {
-  const out = await ctx.cdp.send(
+async function conversationReadBack(ctx, node, contents) {
+  const out = await sendIn(
+    ctx,
     contents,
+    node.sessionId,
     "Runtime.callFunctionOn",
     {
-      objectId,
+      objectId: node.objectId,
       functionDeclaration: READ_VALUE_FUNCTION,
       returnByValue: true
     }
@@ -20661,6 +21476,13 @@ async function upload(ctx, params) {
   const paths = uploadPaths(params);
   const contents = record.view.webContents;
   const node = await resolveNode(ctx, record, selector);
+  if (node.frame) {
+    throw new BridgeCommandError(
+      "element_not_found",
+      `${selector} resolved to an element inside a frame${node.frame.origin ? ` (${node.frame.origin})` : ""}; upload into a frame is not supported yet, so nothing was attached`,
+      { selector, frame_origin: node.frame.origin ?? "" }
+    );
+  }
   const accept = await acceptsOf(ctx, record, node.nodeId);
   await ctx.cdp.send(contents, "DOM.setFileInputFiles", {
     files: paths,