@browserbasehq/orca 3.0.9-alpha-4 → 3.1.0-patch.0

package/dist/esm/lib/v3/understudy/a11y/snapshot/domTree.js

@@ -0,0 +1,274 @@
+import { StagehandDomProcessError } from "../../../types/public/sdkErrors.js";
+import { buildChildXPathSegments, joinXPath, normalizeXPath, } from "./xpathUtils.js";
+// starting from infinite depth (-1), exponentially shrink down to 1
+const DOM_DEPTH_ATTEMPTS = [-1, 256, 128, 64, 32, 16, 8, 4, 2, 1];
+const DESCRIBE_DEPTH_ATTEMPTS = [-1, 64, 32, 16, 8, 4, 2, 1];
+/** Identify CDP failures caused by deep DOM trees blowing the CBOR encoder stack. */
+function isCborStackError(message) {
+    return message.includes("CBOR: stack limit exceeded");
+}
+/**
+ * Determine if CDP truncated a node's children when streaming the DOM tree.
+ * childNodeCount stays accurate even when `children` are omitted; we use this to
+ * decide whether DOM.describeNode must be re-run for that node.
+ */
+export function shouldExpandNode(node) {
+    const declaredChildren = node.childNodeCount ?? 0;
+    const realizedChildren = node.children?.length ?? 0;
+    return declaredChildren > realizedChildren;
+}
+/** Merge an expanded DescribeNode payload back into the original shallow node. */
+export function mergeDomNodes(target, source) {
+    target.childNodeCount = source.childNodeCount ?? target.childNodeCount;
+    target.children = source.children ?? target.children;
+    target.shadowRoots = source.shadowRoots ?? target.shadowRoots;
+    target.contentDocument = source.contentDocument ?? target.contentDocument;
+}
+/** Helper that returns every nested collection we recurse through uniformly. */
+export function collectDomTraversalTargets(node) {
+    const targets = [];
+    if (node.children)
+        targets.push(...node.children);
+    if (node.shadowRoots)
+        targets.push(...node.shadowRoots);
+    if (node.contentDocument)
+        targets.push(node.contentDocument);
+    return targets;
+}
+/**
+ * Rehydrate a truncated DOM tree by repeatedly calling DOM.describeNode with
+ * decreasing depths. Any non-CBOR failure is surfaced as a StagehandDomProcessError.
+ */
+export async function hydrateDomTree(session, root, pierce) {
+    const stack = [root];
+    const expandedNodeIds = new Set();
+    const expandedBackendIds = new Set();
+    while (stack.length) {
+        const node = stack.pop();
+        const nodeId = typeof node.nodeId === "number" && node.nodeId > 0
+            ? node.nodeId
+            : undefined;
+        const backendId = typeof node.backendNodeId === "number" && node.backendNodeId > 0
+            ? node.backendNodeId
+            : undefined;
+        const seenByNode = nodeId ? expandedNodeIds.has(nodeId) : false;
+        const seenByBackend = !nodeId && backendId ? expandedBackendIds.has(backendId) : false;
+        if (seenByNode || seenByBackend)
+            continue;
+        if (nodeId)
+            expandedNodeIds.add(nodeId);
+        else if (backendId)
+            expandedBackendIds.add(backendId);
+        const needsExpansion = shouldExpandNode(node);
+        if (needsExpansion && (nodeId || backendId)) {
+            const describeParamsBase = nodeId
+                ? { nodeId }
+                : { backendNodeId: backendId };
+            let expanded = false;
+            for (const depth of DESCRIBE_DEPTH_ATTEMPTS) {
+                try {
+                    const described = await session.send("DOM.describeNode", {
+                        ...describeParamsBase,
+                        depth,
+                        pierce,
+                    });
+                    mergeDomNodes(node, described.node);
+                    if (!nodeId && described.node.nodeId && described.node.nodeId > 0) {
+                        node.nodeId = described.node.nodeId;
+                        expandedNodeIds.add(described.node.nodeId);
+                    }
+                    expanded = true;
+                    break;
+                }
+                catch (err) {
+                    const message = err instanceof Error ? err.message : String(err);
+                    if (isCborStackError(message)) {
+                        continue;
+                    }
+                    const identifier = nodeId ?? backendId ?? "unknown";
+                    throw new StagehandDomProcessError(`Failed to expand DOM node ${identifier}: ${String(err)}`);
+                }
+            }
+            if (!expanded) {
+                const identifier = nodeId ?? backendId ?? "unknown";
+                throw new StagehandDomProcessError(`Unable to expand DOM node ${identifier} after describeNode depth retries`);
+            }
+        }
+        for (const child of collectDomTraversalTargets(node)) {
+            stack.push(child);
+        }
+    }
+}
+/**
+ * Attempt DOM.getDocument with progressively shallower depths until CBOR stops
+ * complaining. When a shallower snapshot is returned we hydrate the missing
+ * branches so downstream DOM traversals see the full tree shape.
+ */
+export async function getDomTreeWithFallback(session, pierce) {
+    let lastCborMessage = "";
+    for (const depth of DOM_DEPTH_ATTEMPTS) {
+        try {
+            const { root } = await session.send("DOM.getDocument", { depth, pierce });
+            if (depth !== -1) {
+                await hydrateDomTree(session, root, pierce);
+            }
+            return root;
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            if (isCborStackError(message)) {
+                lastCborMessage = message;
+                continue;
+            }
+            throw err;
+        }
+    }
+    throw new StagehandDomProcessError(lastCborMessage
+        ? `CDP DOM.getDocument failed after adaptive depth retries: ${lastCborMessage}`
+        : "CDP DOM.getDocument failed after adaptive depth retries.");
+}
+/**
+ * Build tag name and XPath maps for a single frame session.
+ * EncodedId is produced by a frame-aware encoder provided by the caller.
+ */
+export async function domMapsForSession(session, frameId, pierce, encode, attemptOwnerLookup = true) {
+    await session.send("DOM.enable").catch(() => { });
+    const root = await getDomTreeWithFallback(session, pierce);
+    let startNode = root;
+    if (attemptOwnerLookup) {
+        try {
+            const owner = await session.send("DOM.getFrameOwner", { frameId });
+            const ownerBackendId = owner.backendNodeId;
+            if (typeof ownerBackendId === "number") {
+                const ownerEl = findNodeByBackendId(root, ownerBackendId);
+                if (ownerEl?.contentDocument) {
+                    startNode = ownerEl.contentDocument;
+                }
+            }
+        }
+        catch {
+            // OOPIF or race → keep startNode = root
+        }
+    }
+    const tagNameMap = {};
+    const xpathMap = {};
+    const scrollableMap = {};
+    const stack = [{ node: startNode, xpath: "" }];
+    while (stack.length) {
+        const { node, xpath } = stack.pop();
+        if (node.backendNodeId) {
+            const encId = encode(frameId, node.backendNodeId);
+            tagNameMap[encId] = String(node.nodeName).toLowerCase();
+            xpathMap[encId] = xpath || "/";
+            const isScrollable = node?.isScrollable === true;
+            if (isScrollable)
+                scrollableMap[encId] = true;
+        }
+        const kids = node.children ?? [];
+        if (kids.length) {
+            const segs = buildChildXPathSegments(kids);
+            for (let i = kids.length - 1; i >= 0; i--) {
+                const child = kids[i];
+                const step = segs[i];
+                stack.push({
+                    node: child,
+                    xpath: joinXPath(xpath, step),
+                });
+            }
+        }
+        for (const sr of node.shadowRoots ?? []) {
+            stack.push({
+                node: sr,
+                xpath: joinXPath(xpath, "//"),
+            });
+        }
+    }
+    return { tagNameMap, xpathMap, scrollableMap };
+}
+/**
+ * Build an index of absolute XPath/tag metadata for an entire CDP session.
+ * Once the index is cached, per-frame slices are derived without extra DOM
+ * calls, which keeps snapshot capture linear in the number of frames.
+ */
+export async function buildSessionDomIndex(session, pierce) {
+    await session.send("DOM.enable").catch(() => { });
+    const root = await getDomTreeWithFallback(session, pierce);
+    const absByBe = new Map();
+    const tagByBe = new Map();
+    const scrollByBe = new Map();
+    const docRootOf = new Map();
+    const contentDocRootByIframe = new Map();
+    const rootBe = root.backendNodeId;
+    const stack = [{ node: root, xp: "/", docRootBe: rootBe }];
+    while (stack.length) {
+        const { node, xp, docRootBe } = stack.pop();
+        if (node.backendNodeId) {
+            absByBe.set(node.backendNodeId, xp || "/");
+            tagByBe.set(node.backendNodeId, String(node.nodeName).toLowerCase());
+            if (node?.isScrollable === true)
+                scrollByBe.set(node.backendNodeId, true);
+            docRootOf.set(node.backendNodeId, docRootBe);
+        }
+        const kids = node.children ?? [];
+        if (kids.length) {
+            const segs = buildChildXPathSegments(kids);
+            for (let i = kids.length - 1; i >= 0; i--) {
+                const child = kids[i];
+                const step = segs[i];
+                stack.push({ node: child, xp: joinXPath(xp, step), docRootBe });
+            }
+        }
+        for (const sr of node.shadowRoots ?? []) {
+            stack.push({ node: sr, xp: joinXPath(xp, "//"), docRootBe });
+        }
+        const cd = node.contentDocument;
+        if (cd && typeof cd.backendNodeId === "number") {
+            contentDocRootByIframe.set(node.backendNodeId, cd.backendNodeId);
+            stack.push({ node: cd, xp, docRootBe: cd.backendNodeId });
+        }
+    }
+    return {
+        rootBackend: rootBe,
+        absByBe,
+        tagByBe,
+        scrollByBe,
+        docRootOf,
+        contentDocRootByIframe,
+    };
+}
+/**
+ * Relativize an absolute XPath against a document root's absolute path.
+ * When the node lives outside the document we return the absolute path as-is.
+ */
+export function relativizeXPath(baseAbs, nodeAbs) {
+    const base = normalizeXPath(baseAbs);
+    const abs = normalizeXPath(nodeAbs);
+    if (abs === base)
+        return "/";
+    if (abs.startsWith(base)) {
+        const tail = abs.slice(base.length);
+        if (!tail)
+            return "/";
+        return tail.startsWith("/") || tail.startsWith("//") ? tail : `/${tail}`;
+    }
+    if (base === "/")
+        return abs;
+    return abs;
+}
+/** Find a node by backendNodeId inside a DOM.getDocument tree. */
+export function findNodeByBackendId(root, backendNodeId) {
+    const stack = [root];
+    while (stack.length) {
+        const n = stack.pop();
+        if (n.backendNodeId === backendNodeId)
+            return n;
+        if (n.children)
+            for (const c of n.children)
+                stack.push(c);
+        if (n.shadowRoots)
+            for (const s of n.shadowRoots)
+                stack.push(s);
+    }
+    return undefined;
+}
+//# sourceMappingURL=domTree.js.map

package/dist/esm/lib/v3/understudy/a11y/snapshot/domTree.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"domTree.js","sourceRoot":"","sources":["../../../../../../../lib/v3/understudy/a11y/snapshot/domTree.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Protocol } from \"devtools-protocol\";\nimport type { CDPSessionLike } from \"../../cdp.js\";\nimport { StagehandDomProcessError } from \"../../../types/public/sdkErrors.js\";\nimport type { SessionDomIndex } from \"../../../types/private/snapshot.js\";\nimport {\n  buildChildXPathSegments,\n  joinXPath,\n  normalizeXPath,\n} from \"./xpathUtils.js\";\n\n// starting from infinite depth (-1), exponentially shrink down to 1\nconst DOM_DEPTH_ATTEMPTS = [-1, 256, 128, 64, 32, 16, 8, 4, 2, 1];\nconst DESCRIBE_DEPTH_ATTEMPTS = [-1, 64, 32, 16, 8, 4, 2, 1];\n\n/** Identify CDP failures caused by deep DOM trees blowing the CBOR encoder stack. */\nfunction isCborStackError(message: string): boolean {\n  return message.includes(\"CBOR: stack limit exceeded\");\n}\n\n/**\n * Determine if CDP truncated a node's children when streaming the DOM tree.\n * childNodeCount stays accurate even when `children` are omitted; we use this to\n * decide whether DOM.describeNode must be re-run for that node.\n */\nexport function shouldExpandNode(node: Protocol.DOM.Node): boolean {\n  const declaredChildren = node.childNodeCount ?? 0;\n  const realizedChildren = node.children?.length ?? 0;\n  return declaredChildren > realizedChildren;\n}\n\n/** Merge an expanded DescribeNode payload back into the original shallow node. */\nexport function mergeDomNodes(\n  target: Protocol.DOM.Node,\n  source: Protocol.DOM.Node,\n): void {\n  target.childNodeCount = source.childNodeCount ?? target.childNodeCount;\n  target.children = source.children ?? target.children;\n  target.shadowRoots = source.shadowRoots ?? target.shadowRoots;\n  target.contentDocument = source.contentDocument ?? target.contentDocument;\n}\n\n/** Helper that returns every nested collection we recurse through uniformly. */\nexport function collectDomTraversalTargets(\n  node: Protocol.DOM.Node,\n): Protocol.DOM.Node[] {\n  const targets: Protocol.DOM.Node[] = [];\n  if (node.children) targets.push(...node.children);\n  if (node.shadowRoots) targets.push(...node.shadowRoots);\n  if (node.contentDocument) targets.push(node.contentDocument);\n  return targets;\n}\n\n/**\n * Rehydrate a truncated DOM tree by repeatedly calling DOM.describeNode with\n * decreasing depths. Any non-CBOR failure is surfaced as a StagehandDomProcessError.\n */\nexport async function hydrateDomTree(\n  session: CDPSessionLike,\n  root: Protocol.DOM.Node,\n  pierce: boolean,\n): Promise<void> {\n  const stack: Protocol.DOM.Node[] = [root];\n  const expandedNodeIds = new Set<number>();\n  const expandedBackendIds = new Set<number>();\n\n  while (stack.length) {\n    const node = stack.pop()!;\n    const nodeId =\n      typeof node.nodeId === \"number\" && node.nodeId > 0\n        ? node.nodeId\n        : undefined;\n    const backendId =\n      typeof node.backendNodeId === \"number\" && node.backendNodeId > 0\n        ? node.backendNodeId\n        : undefined;\n\n    const seenByNode = nodeId ? expandedNodeIds.has(nodeId) : false;\n    const seenByBackend =\n      !nodeId && backendId ? expandedBackendIds.has(backendId) : false;\n    if (seenByNode || seenByBackend) continue;\n    if (nodeId) expandedNodeIds.add(nodeId);\n    else if (backendId) expandedBackendIds.add(backendId);\n\n    const needsExpansion = shouldExpandNode(node);\n    if (needsExpansion && (nodeId || backendId)) {\n      const describeParamsBase = nodeId\n        ? { nodeId }\n        : { backendNodeId: backendId! };\n      let expanded = false;\n      for (const depth of DESCRIBE_DEPTH_ATTEMPTS) {\n        try {\n          const described =\n            await session.send<Protocol.DOM.DescribeNodeResponse>(\n              \"DOM.describeNode\",\n              {\n                ...describeParamsBase,\n                depth,\n                pierce,\n              },\n            );\n          mergeDomNodes(node, described.node);\n          if (!nodeId && described.node.nodeId && described.node.nodeId > 0) {\n            node.nodeId = described.node.nodeId;\n            expandedNodeIds.add(described.node.nodeId);\n          }\n          expanded = true;\n          break;\n        } catch (err) {\n          const message = err instanceof Error ? err.message : String(err);\n          if (isCborStackError(message)) {\n            continue;\n          }\n          const identifier = nodeId ?? backendId ?? \"unknown\";\n          throw new StagehandDomProcessError(\n            `Failed to expand DOM node ${identifier}: ${String(err)}`,\n          );\n        }\n      }\n      if (!expanded) {\n        const identifier = nodeId ?? backendId ?? \"unknown\";\n        throw new StagehandDomProcessError(\n          `Unable to expand DOM node ${identifier} after describeNode depth retries`,\n        );\n      }\n    }\n\n    for (const child of collectDomTraversalTargets(node)) {\n      stack.push(child);\n    }\n  }\n}\n\n/**\n * Attempt DOM.getDocument with progressively shallower depths until CBOR stops\n * complaining. When a shallower snapshot is returned we hydrate the missing\n * branches so downstream DOM traversals see the full tree shape.\n */\nexport async function getDomTreeWithFallback(\n  session: CDPSessionLike,\n  pierce: boolean,\n): Promise<Protocol.DOM.Node> {\n  let lastCborMessage = \"\";\n\n  for (const depth of DOM_DEPTH_ATTEMPTS) {\n    try {\n      const { root } = await session.send<{ root: Protocol.DOM.Node }>(\n        \"DOM.getDocument\",\n        { depth, pierce },\n      );\n\n      if (depth !== -1) {\n        await hydrateDomTree(session, root, pierce);\n      }\n\n      return root;\n    } catch (err) {\n      const message = err instanceof Error ? err.message : String(err);\n      if (isCborStackError(message)) {\n        lastCborMessage = message;\n        continue;\n      }\n      throw err;\n    }\n  }\n\n  throw new StagehandDomProcessError(\n    lastCborMessage\n      ? `CDP DOM.getDocument failed after adaptive depth retries: ${lastCborMessage}`\n      : \"CDP DOM.getDocument failed after adaptive depth retries.\",\n  );\n}\n\n/**\n * Build tag name and XPath maps for a single frame session.\n * EncodedId is produced by a frame-aware encoder provided by the caller.\n */\nexport async function domMapsForSession(\n  session: CDPSessionLike,\n  frameId: string,\n  pierce: boolean,\n  encode: (fid: string, backendNodeId: number) => string,\n  attemptOwnerLookup = true,\n): Promise<{\n  tagNameMap: Record<string, string>;\n  xpathMap: Record<string, string>;\n  scrollableMap: Record<string, boolean>;\n}> {\n  await session.send(\"DOM.enable\").catch(() => {});\n  const root = await getDomTreeWithFallback(session, pierce);\n\n  let startNode: Protocol.DOM.Node = root;\n  if (attemptOwnerLookup) {\n    try {\n      const owner = await session.send<{ backendNodeId?: number }>(\n        \"DOM.getFrameOwner\",\n        { frameId },\n      );\n      const ownerBackendId = owner.backendNodeId;\n      if (typeof ownerBackendId === \"number\") {\n        const ownerEl = findNodeByBackendId(root, ownerBackendId);\n        if (ownerEl?.contentDocument) {\n          startNode = ownerEl.contentDocument;\n        }\n      }\n    } catch {\n      // OOPIF or race → keep startNode = root\n    }\n  }\n\n  const tagNameMap: Record<string, string> = {};\n  const xpathMap: Record<string, string> = {};\n  const scrollableMap: Record<string, boolean> = {};\n\n  type StackEntry = { node: Protocol.DOM.Node; xpath: string };\n  const stack: StackEntry[] = [{ node: startNode, xpath: \"\" }];\n\n  while (stack.length) {\n    const { node, xpath } = stack.pop()!;\n\n    if (node.backendNodeId) {\n      const encId = encode(frameId, node.backendNodeId);\n      tagNameMap[encId] = String(node.nodeName).toLowerCase();\n      xpathMap[encId] = xpath || \"/\";\n      const isScrollable = node?.isScrollable === true;\n      if (isScrollable) scrollableMap[encId] = true;\n    }\n\n    const kids = node.children ?? [];\n    if (kids.length) {\n      const segs = buildChildXPathSegments(kids);\n      for (let i = kids.length - 1; i >= 0; i--) {\n        const child = kids[i]!;\n        const step = segs[i]!;\n        stack.push({\n          node: child,\n          xpath: joinXPath(xpath, step),\n        });\n      }\n    }\n\n    for (const sr of node.shadowRoots ?? []) {\n      stack.push({\n        node: sr,\n        xpath: joinXPath(xpath, \"//\"),\n      });\n    }\n  }\n\n  return { tagNameMap, xpathMap, scrollableMap };\n}\n\n/**\n * Build an index of absolute XPath/tag metadata for an entire CDP session.\n * Once the index is cached, per-frame slices are derived without extra DOM\n * calls, which keeps snapshot capture linear in the number of frames.\n */\nexport async function buildSessionDomIndex(\n  session: CDPSessionLike,\n  pierce: boolean,\n): Promise<SessionDomIndex> {\n  await session.send(\"DOM.enable\").catch(() => {});\n  const root = await getDomTreeWithFallback(session, pierce);\n\n  const absByBe = new Map<number, string>();\n  const tagByBe = new Map<number, string>();\n  const scrollByBe = new Map<number, boolean>();\n  const docRootOf = new Map<number, number>();\n  const contentDocRootByIframe = new Map<number, number>();\n\n  type Entry = { node: Protocol.DOM.Node; xp: string; docRootBe: number };\n  const rootBe = root.backendNodeId!;\n  const stack: Entry[] = [{ node: root, xp: \"/\", docRootBe: rootBe }];\n\n  while (stack.length) {\n    const { node, xp, docRootBe } = stack.pop()!;\n    if (node.backendNodeId) {\n      absByBe.set(node.backendNodeId, xp || \"/\");\n      tagByBe.set(node.backendNodeId, String(node.nodeName).toLowerCase());\n      if (node?.isScrollable === true) scrollByBe.set(node.backendNodeId, true);\n      docRootOf.set(node.backendNodeId, docRootBe);\n    }\n\n    const kids = node.children ?? [];\n    if (kids.length) {\n      const segs = buildChildXPathSegments(kids);\n      for (let i = kids.length - 1; i >= 0; i--) {\n        const child = kids[i]!;\n        const step = segs[i]!;\n        stack.push({ node: child, xp: joinXPath(xp, step), docRootBe });\n      }\n    }\n\n    for (const sr of node.shadowRoots ?? []) {\n      stack.push({ node: sr, xp: joinXPath(xp, \"//\"), docRootBe });\n    }\n\n    const cd = node.contentDocument as Protocol.DOM.Node | undefined;\n    if (cd && typeof cd.backendNodeId === \"number\") {\n      contentDocRootByIframe.set(node.backendNodeId!, cd.backendNodeId);\n      stack.push({ node: cd, xp, docRootBe: cd.backendNodeId });\n    }\n  }\n\n  return {\n    rootBackend: rootBe,\n    absByBe,\n    tagByBe,\n    scrollByBe,\n    docRootOf,\n    contentDocRootByIframe,\n  };\n}\n\n/**\n * Relativize an absolute XPath against a document root's absolute path.\n * When the node lives outside the document we return the absolute path as-is.\n */\nexport function relativizeXPath(baseAbs: string, nodeAbs: string): string {\n  const base = normalizeXPath(baseAbs);\n  const abs = normalizeXPath(nodeAbs);\n  if (abs === base) return \"/\";\n  if (abs.startsWith(base)) {\n    const tail = abs.slice(base.length);\n    if (!tail) return \"/\";\n    return tail.startsWith(\"/\") || tail.startsWith(\"//\") ? tail : `/${tail}`;\n  }\n  if (base === \"/\") return abs;\n  return abs;\n}\n\n/** Find a node by backendNodeId inside a DOM.getDocument tree. */\nexport function findNodeByBackendId(\n  root: Protocol.DOM.Node,\n  backendNodeId: number,\n): Protocol.DOM.Node | undefined {\n  const stack: Protocol.DOM.Node[] = [root];\n  while (stack.length) {\n    const n = stack.pop()!;\n    if (n.backendNodeId === backendNodeId) return n;\n    if (n.children) for (const c of n.children) stack.push(c);\n    if (n.shadowRoots) for (const s of n.shadowRoots) stack.push(s);\n  }\n  return undefined;\n}\n"]}

package/dist/esm/lib/v3/understudy/a11y/snapshot/focusSelectors.d.ts

@@ -0,0 +1,24 @@
+import type { CDPSessionLike } from "../../cdp.js";
+import { Page } from "../../page.js";
+import type { FrameParentIndex, ResolvedCssFocus, ResolvedFocusFrame, Step } from "../../../types/private/snapshot.js";
+/**
+ * Parse a cross-frame XPath into discrete steps. Each step tracks whether it
+ * represents a descendant hop (“//”) or a single-child hop (“/”).
+ */
+export declare function parseXPathToSteps(path: string): Step[];
+/** Rebuild an XPath string from parsed steps. */
+export declare function buildXPathFromSteps(steps: ReadonlyArray<Step>): string;
+/**
+ * Given a cross-frame XPath, walk iframe steps to resolve:
+ * - the target frameId (last iframe hop)
+ * - the tail XPath (within the target frame)
+ * - the absolute XPath prefix up to the iframe element hosting that frame
+ */
+export declare function resolveFocusFrameAndTail(page: Page, absoluteXPath: string, parentByFrame: FrameParentIndex, rootId: string): Promise<ResolvedFocusFrame>;
+/** Resolve focus frame and tail CSS selector using '>>' to hop iframes. */
+export declare function resolveCssFocusFrameAndTail(page: Page, rawSelector: string, parentByFrame: FrameParentIndex, rootId: string): Promise<ResolvedCssFocus>;
+/** Resolve an XPath to a Runtime remoteObjectId in the given CDP session. */
+export declare function resolveObjectIdForXPath(session: CDPSessionLike, xpath: string, frameId?: string): Promise<string | null>;
+/** Resolve a CSS selector (supports '>>' within the same frame only) to a Runtime objectId. */
+export declare function resolveObjectIdForCss(session: CDPSessionLike, selector: string, frameId?: string): Promise<string | null>;
+export declare function listChildrenOf(parentByFrame: FrameParentIndex, parentId: string): string[];

package/dist/esm/lib/v3/understudy/a11y/snapshot/focusSelectors.js

@@ -0,0 +1,216 @@
+import { executionContexts } from "../../executionContextRegistry.js";
+import { buildLocatorInvocation } from "../../locatorInvocation.js";
+import { StagehandIframeError } from "../../../types/public/sdkErrors.js";
+import { prefixXPath } from "./xpathUtils.js";
+/**
+ * Parse a cross-frame XPath into discrete steps. Each step tracks whether it
+ * represents a descendant hop (“//”) or a single-child hop (“/”).
+ */
+export function parseXPathToSteps(path) {
+    const s = path.trim();
+    let i = 0;
+    const steps = [];
+    while (i < s.length) {
+        let axis = "child";
+        if (s.startsWith("//", i)) {
+            axis = "desc";
+            i += 2;
+        }
+        else if (s[i] === "/") {
+            axis = "child";
+            i += 1;
+        }
+        const start = i;
+        while (i < s.length && s[i] !== "/")
+            i++;
+        const raw = s.slice(start, i).trim();
+        if (!raw)
+            continue;
+        const name = raw.replace(/\[\d+\]\s*$/u, "").toLowerCase();
+        steps.push({ axis, raw, name });
+    }
+    return steps;
+}
+/** Rebuild an XPath string from parsed steps. */
+export function buildXPathFromSteps(steps) {
+    let out = "";
+    for (const st of steps) {
+        out += st.axis === "desc" ? "//" : "/";
+        out += st.raw;
+    }
+    return out || "/";
+}
+const IFRAME_STEP_RE = /^iframe(?:\[\d+])?$/i;
+/**
+ * Given a cross-frame XPath, walk iframe steps to resolve:
+ * - the target frameId (last iframe hop)
+ * - the tail XPath (within the target frame)
+ * - the absolute XPath prefix up to the iframe element hosting that frame
+ */
+export async function resolveFocusFrameAndTail(page, absoluteXPath, parentByFrame, rootId) {
+    const steps = parseXPathToSteps(absoluteXPath);
+    let ctxFrameId = rootId;
+    let buf = [];
+    let absPrefix = "";
+    const flushIntoChild = async () => {
+        if (!buf.length)
+            return;
+        const selectorForIframe = buildXPathFromSteps(buf);
+        const parentSess = page.getSessionForFrame(ctxFrameId);
+        const objectId = await resolveObjectIdForXPath(parentSess, selectorForIframe, ctxFrameId);
+        if (!objectId)
+            throw new StagehandIframeError(selectorForIframe, "Failed to resolve iframe element by XPath");
+        try {
+            await parentSess.send("DOM.enable").catch(() => { });
+            const desc = await parentSess.send("DOM.describeNode", { objectId });
+            const iframeBackendNodeId = desc.node.backendNodeId;
+            let childFrameId;
+            for (const fid of listChildrenOf(parentByFrame, ctxFrameId)) {
+                try {
+                    const { backendNodeId } = await parentSess.send("DOM.getFrameOwner", { frameId: fid });
+                    if (backendNodeId === iframeBackendNodeId) {
+                        childFrameId = fid;
+                        break;
+                    }
+                }
+                catch {
+                    continue;
+                }
+            }
+            if (!childFrameId)
+                throw new StagehandIframeError(selectorForIframe, "Could not map iframe to child frameId");
+            absPrefix = prefixXPath(absPrefix || "/", selectorForIframe);
+            ctxFrameId = childFrameId;
+        }
+        finally {
+            await parentSess
+                .send("Runtime.releaseObject", { objectId })
+                .catch(() => { });
+        }
+        buf = [];
+    };
+    for (const st of steps) {
+        buf.push(st);
+        if (IFRAME_STEP_RE.test(st.name)) {
+            await flushIntoChild();
+        }
+    }
+    const tailXPath = buildXPathFromSteps(buf);
+    return { targetFrameId: ctxFrameId, tailXPath, absPrefix };
+}
+/** Resolve focus frame and tail CSS selector using '>>' to hop iframes. */
+export async function resolveCssFocusFrameAndTail(page, rawSelector, parentByFrame, rootId) {
+    const parts = rawSelector
+        .split(">>")
+        .map((s) => s.trim())
+        .filter(Boolean);
+    let ctxFrameId = rootId;
+    const absPrefix = "";
+    for (let i = 0; i < Math.max(0, parts.length - 1); i++) {
+        const parentSess = page.getSessionForFrame(ctxFrameId);
+        const objectId = await resolveObjectIdForCss(parentSess, parts[i], ctxFrameId);
+        if (!objectId)
+            throw new StagehandIframeError(parts[i], "Failed to resolve iframe via CSS hop");
+        try {
+            await parentSess.send("DOM.enable").catch(() => { });
+            const desc = await parentSess.send("DOM.describeNode", { objectId });
+            const iframeBackendNodeId = desc.node.backendNodeId;
+            let childFrameId;
+            for (const fid of listChildrenOf(parentByFrame, ctxFrameId)) {
+                try {
+                    const { backendNodeId } = await parentSess.send("DOM.getFrameOwner", { frameId: fid });
+                    if (backendNodeId === iframeBackendNodeId) {
+                        childFrameId = fid;
+                        break;
+                    }
+                }
+                catch {
+                    continue;
+                }
+            }
+            if (!childFrameId)
+                throw new StagehandIframeError(parts[i], "Could not map CSS iframe hop to child frameId");
+            ctxFrameId = childFrameId;
+        }
+        finally {
+            await parentSess
+                .send("Runtime.releaseObject", { objectId })
+                .catch(() => { });
+        }
+    }
+    const tailSelector = parts[parts.length - 1] ?? "*";
+    return { targetFrameId: ctxFrameId, tailSelector, absPrefix };
+}
+/** Resolve an XPath to a Runtime remoteObjectId in the given CDP session. */
+export async function resolveObjectIdForXPath(session, xpath, frameId) {
+    let contextId;
+    try {
+        if (frameId) {
+            contextId = await executionContexts
+                .waitForMainWorld(session, frameId, 800)
+                .catch(() => executionContexts.getMainWorld(session, frameId) ?? undefined);
+        }
+    }
+    catch {
+        contextId = undefined;
+    }
+    const expr = buildLocatorInvocation("resolveXPathMainWorld", [
+        JSON.stringify(xpath),
+        "0",
+    ]);
+    const { result, exceptionDetails } = await session.send("Runtime.evaluate", {
+        expression: expr,
+        returnByValue: false,
+        contextId,
+        awaitPromise: true,
+    });
+    if (exceptionDetails)
+        return null;
+    return result?.objectId ?? null;
+}
+/** Resolve a CSS selector (supports '>>' within the same frame only) to a Runtime objectId. */
+export async function resolveObjectIdForCss(session, selector, frameId) {
+    let contextId;
+    try {
+        if (frameId) {
+            contextId = await executionContexts
+                .waitForMainWorld(session, frameId, 800)
+                .catch(() => executionContexts.getMainWorld(session, frameId) ?? undefined);
+        }
+    }
+    catch {
+        contextId = undefined;
+    }
+    const primaryExpr = buildLocatorInvocation("resolveCssSelector", [
+        JSON.stringify(selector),
+        "0",
+    ]);
+    const fallbackExpr = buildLocatorInvocation("resolveCssSelectorPierce", [
+        JSON.stringify(selector),
+        "0",
+    ]);
+    const evaluate = async (expression) => {
+        const { result, exceptionDetails } = await session.send("Runtime.evaluate", {
+            expression,
+            returnByValue: false,
+            contextId,
+            awaitPromise: true,
+        });
+        if (exceptionDetails)
+            return null;
+        return result?.objectId ?? null;
+    };
+    const primary = await evaluate(primaryExpr);
+    if (primary)
+        return primary;
+    return evaluate(fallbackExpr);
+}
+export function listChildrenOf(parentByFrame, parentId) {
+    const out = [];
+    for (const [fid, p] of parentByFrame.entries()) {
+        if (p === parentId)
+            out.push(fid);
+    }
+    return out;
+}
+//# sourceMappingURL=focusSelectors.js.map

package/dist/esm/lib/v3/understudy/a11y/snapshot/focusSelectors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"focusSelectors.js","sourceRoot":"","sources":["../../../../../../../lib/v3/understudy/a11y/snapshot/focusSelectors.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Protocol } from \"devtools-protocol\";\nimport type { CDPSessionLike } from \"../../cdp.js\";\nimport { Page } from \"../../page.js\";\nimport { executionContexts } from \"../../executionContextRegistry.js\";\nimport { buildLocatorInvocation } from \"../../locatorInvocation.js\";\nimport { StagehandIframeError } from \"../../../types/public/sdkErrors.js\";\nimport type {\n  Axis,\n  FrameParentIndex,\n  ResolvedCssFocus,\n  ResolvedFocusFrame,\n  Step,\n} from \"../../../types/private/snapshot.js\";\nimport { prefixXPath } from \"./xpathUtils.js\";\n\n/**\n * Parse a cross-frame XPath into discrete steps. Each step tracks whether it\n * represents a descendant hop (“//”) or a single-child hop (“/”).\n */\nexport function parseXPathToSteps(path: string): Step[] {\n  const s = path.trim();\n  let i = 0;\n  const steps: Step[] = [];\n  while (i < s.length) {\n    let axis: Axis = \"child\";\n    if (s.startsWith(\"//\", i)) {\n      axis = \"desc\";\n      i += 2;\n    } else if (s[i] === \"/\") {\n      axis = \"child\";\n      i += 1;\n    }\n\n    const start = i;\n    while (i < s.length && s[i] !== \"/\") i++;\n    const raw = s.slice(start, i).trim();\n    if (!raw) continue;\n    const name = raw.replace(/\\[\\d+\\]\\s*$/u, \"\").toLowerCase();\n    steps.push({ axis, raw, name });\n  }\n  return steps;\n}\n\n/** Rebuild an XPath string from parsed steps. */\nexport function buildXPathFromSteps(steps: ReadonlyArray<Step>): string {\n  let out = \"\";\n  for (const st of steps) {\n    out += st.axis === \"desc\" ? \"//\" : \"/\";\n    out += st.raw;\n  }\n  return out || \"/\";\n}\n\nconst IFRAME_STEP_RE = /^iframe(?:\\[\\d+])?$/i;\n\n/**\n * Given a cross-frame XPath, walk iframe steps to resolve:\n * - the target frameId (last iframe hop)\n * - the tail XPath (within the target frame)\n * - the absolute XPath prefix up to the iframe element hosting that frame\n */\nexport async function resolveFocusFrameAndTail(\n  page: Page,\n  absoluteXPath: string,\n  parentByFrame: FrameParentIndex,\n  rootId: string,\n): Promise<ResolvedFocusFrame> {\n  const steps = parseXPathToSteps(absoluteXPath);\n  let ctxFrameId = rootId;\n  let buf: Step[] = [];\n  let absPrefix = \"\";\n\n  const flushIntoChild = async (): Promise<void> => {\n    if (!buf.length) return;\n    const selectorForIframe = buildXPathFromSteps(buf);\n    const parentSess = page.getSessionForFrame(ctxFrameId);\n    const objectId = await resolveObjectIdForXPath(\n      parentSess,\n      selectorForIframe,\n      ctxFrameId,\n    );\n    if (!objectId)\n      throw new StagehandIframeError(\n        selectorForIframe,\n        \"Failed to resolve iframe element by XPath\",\n      );\n\n    try {\n      await parentSess.send(\"DOM.enable\").catch(() => {});\n      const desc = await parentSess.send<Protocol.DOM.DescribeNodeResponse>(\n        \"DOM.describeNode\",\n        { objectId },\n      );\n      const iframeBackendNodeId = desc.node.backendNodeId;\n\n      let childFrameId: string | undefined;\n      for (const fid of listChildrenOf(parentByFrame, ctxFrameId)) {\n        try {\n          const { backendNodeId } = await parentSess.send<{\n            backendNodeId: number;\n          }>(\"DOM.getFrameOwner\", { frameId: fid });\n          if (backendNodeId === iframeBackendNodeId) {\n            childFrameId = fid;\n            break;\n          }\n        } catch {\n          continue;\n        }\n      }\n      if (!childFrameId)\n        throw new StagehandIframeError(\n          selectorForIframe,\n          \"Could not map iframe to child frameId\",\n        );\n\n      absPrefix = prefixXPath(absPrefix || \"/\", selectorForIframe);\n      ctxFrameId = childFrameId;\n    } finally {\n      await parentSess\n        .send(\"Runtime.releaseObject\", { objectId })\n        .catch(() => {});\n    }\n\n    buf = [];\n  };\n\n  for (const st of steps) {\n    buf.push(st);\n    if (IFRAME_STEP_RE.test(st.name)) {\n      await flushIntoChild();\n    }\n  }\n\n  const tailXPath = buildXPathFromSteps(buf);\n  return { targetFrameId: ctxFrameId, tailXPath, absPrefix };\n}\n\n/** Resolve focus frame and tail CSS selector using '>>' to hop iframes. */\nexport async function resolveCssFocusFrameAndTail(\n  page: Page,\n  rawSelector: string,\n  parentByFrame: FrameParentIndex,\n  rootId: string,\n): Promise<ResolvedCssFocus> {\n  const parts = rawSelector\n    .split(\">>\")\n    .map((s) => s.trim())\n    .filter(Boolean);\n  let ctxFrameId = rootId;\n  const absPrefix = \"\";\n\n  for (let i = 0; i < Math.max(0, parts.length - 1); i++) {\n    const parentSess = page.getSessionForFrame(ctxFrameId);\n    const objectId = await resolveObjectIdForCss(\n      parentSess,\n      parts[i]!,\n      ctxFrameId,\n    );\n    if (!objectId)\n      throw new StagehandIframeError(\n        parts[i]!,\n        \"Failed to resolve iframe via CSS hop\",\n      );\n    try {\n      await parentSess.send(\"DOM.enable\").catch(() => {});\n      const desc = await parentSess.send<Protocol.DOM.DescribeNodeResponse>(\n        \"DOM.describeNode\",\n        { objectId },\n      );\n      const iframeBackendNodeId = desc.node.backendNodeId;\n      let childFrameId: string | undefined;\n      for (const fid of listChildrenOf(parentByFrame, ctxFrameId)) {\n        try {\n          const { backendNodeId } = await parentSess.send<{\n            backendNodeId: number;\n          }>(\"DOM.getFrameOwner\", { frameId: fid });\n          if (backendNodeId === iframeBackendNodeId) {\n            childFrameId = fid;\n            break;\n          }\n        } catch {\n          continue;\n        }\n      }\n      if (!childFrameId)\n        throw new StagehandIframeError(\n          parts[i]!,\n          \"Could not map CSS iframe hop to child frameId\",\n        );\n      ctxFrameId = childFrameId;\n    } finally {\n      await parentSess\n        .send(\"Runtime.releaseObject\", { objectId })\n        .catch(() => {});\n    }\n  }\n\n  const tailSelector = parts[parts.length - 1] ?? \"*\";\n  return { targetFrameId: ctxFrameId, tailSelector, absPrefix };\n}\n\n/** Resolve an XPath to a Runtime remoteObjectId in the given CDP session. */\nexport async function resolveObjectIdForXPath(\n  session: CDPSessionLike,\n  xpath: string,\n  frameId?: string,\n): Promise<string | null> {\n  let contextId: number | undefined;\n  try {\n    if (frameId) {\n      contextId = await executionContexts\n        .waitForMainWorld(session, frameId, 800)\n        .catch(\n          () => executionContexts.getMainWorld(session, frameId) ?? undefined,\n        );\n    }\n  } catch {\n    contextId = undefined;\n  }\n  const expr = buildLocatorInvocation(\"resolveXPathMainWorld\", [\n    JSON.stringify(xpath),\n    \"0\",\n  ]);\n  const { result, exceptionDetails } = await session.send<{\n    result: { objectId?: string | undefined };\n    exceptionDetails?: Protocol.Runtime.ExceptionDetails;\n  }>(\"Runtime.evaluate\", {\n    expression: expr,\n    returnByValue: false,\n    contextId,\n    awaitPromise: true,\n  });\n  if (exceptionDetails) return null;\n  return result?.objectId ?? null;\n}\n\n/** Resolve a CSS selector (supports '>>' within the same frame only) to a Runtime objectId. */\nexport async function resolveObjectIdForCss(\n  session: CDPSessionLike,\n  selector: string,\n  frameId?: string,\n): Promise<string | null> {\n  let contextId: number | undefined;\n  try {\n    if (frameId) {\n      contextId = await executionContexts\n        .waitForMainWorld(session, frameId, 800)\n        .catch(\n          () => executionContexts.getMainWorld(session, frameId) ?? undefined,\n        );\n    }\n  } catch {\n    contextId = undefined;\n  }\n  const primaryExpr = buildLocatorInvocation(\"resolveCssSelector\", [\n    JSON.stringify(selector),\n    \"0\",\n  ]);\n  const fallbackExpr = buildLocatorInvocation(\"resolveCssSelectorPierce\", [\n    JSON.stringify(selector),\n    \"0\",\n  ]);\n\n  const evaluate = async (expression: string): Promise<string | null> => {\n    const { result, exceptionDetails } = await session.send<{\n      result: { objectId?: string | undefined };\n      exceptionDetails?: Protocol.Runtime.ExceptionDetails;\n    }>(\"Runtime.evaluate\", {\n      expression,\n      returnByValue: false,\n      contextId,\n      awaitPromise: true,\n    });\n    if (exceptionDetails) return null;\n    return result?.objectId ?? null;\n  };\n\n  const primary = await evaluate(primaryExpr);\n  if (primary) return primary;\n  return evaluate(fallbackExpr);\n}\n\nexport function listChildrenOf(\n  parentByFrame: FrameParentIndex,\n  parentId: string,\n): string[] {\n  const out: string[] = [];\n  for (const [fid, p] of parentByFrame.entries()) {\n    if (p === parentId) out.push(fid);\n  }\n  return out;\n}\n"]}

package/dist/esm/lib/v3/understudy/a11y/snapshot/index.d.ts

@@ -0,0 +1,4 @@
+export { captureHybridSnapshot } from "./capture.js";
+export { computeActiveElementXpath } from "./activeElement.js";
+export { diffCombinedTrees } from "./treeFormatUtils.js";
+export { resolveXpathForLocation } from "./coordinateResolver.js";

package/dist/esm/lib/v3/understudy/a11y/snapshot/index.js

@@ -0,0 +1,5 @@
+export { captureHybridSnapshot } from "./capture.js";
+export { computeActiveElementXpath } from "./activeElement.js";
+export { diffCombinedTrees } from "./treeFormatUtils.js";
+export { resolveXpathForLocation } from "./coordinateResolver.js";
+//# sourceMappingURL=index.js.map

package/dist/esm/lib/v3/understudy/a11y/snapshot/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../../../lib/v3/understudy/a11y/snapshot/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,EAAE,yBAAyB,EAAE,MAAM,oBAAoB,CAAC;AAC/D,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AACzD,OAAO,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC","sourcesContent":["export { captureHybridSnapshot } from \"./capture.js\";\nexport { computeActiveElementXpath } from \"./activeElement.js\";\nexport { diffCombinedTrees } from \"./treeFormatUtils.js\";\nexport { resolveXpathForLocation } from \"./coordinateResolver.js\";\n"]}

package/dist/esm/lib/v3/understudy/a11y/snapshot/sessions.d.ts

@@ -0,0 +1,16 @@
+import type { CDPSessionLike } from "../../cdp.js";
+import { Page } from "../../page.js";
+import type { FrameParentIndex } from "../../../types/private/snapshot.js";
+/**
+ * Session helpers ensure DOM lookups are always executed against the session
+ * that actually owns a frame. Keeping this logic centralized prevents subtle
+ * bugs when OOPIF adoption changes session ownership mid-capture.
+ */
+/** Return the owning session for a frame as registered on the Page. */
+export declare function ownerSession(page: Page, frameId: string): CDPSessionLike;
+/**
+ * DOM.getFrameOwner must be called against the parent frame's session.
+ * This helper hides the lookup (including main-frame fallback) so callers
+ * always reach for the correct connection.
+ */
+export declare function parentSession(page: Page, parentByFrame: FrameParentIndex, frameId: string): CDPSessionLike;

package/dist/esm/lib/v3/understudy/a11y/snapshot/sessions.js

@@ -0,0 +1,22 @@
+/**
+ * Session helpers ensure DOM lookups are always executed against the session
+ * that actually owns a frame. Keeping this logic centralized prevents subtle
+ * bugs when OOPIF adoption changes session ownership mid-capture.
+ */
+/** Return the owning session for a frame as registered on the Page. */
+export function ownerSession(page, frameId) {
+    return page.getSessionForFrame(frameId);
+}
+/**
+ * DOM.getFrameOwner must be called against the parent frame's session.
+ * This helper hides the lookup (including main-frame fallback) so callers
+ * always reach for the correct connection.
+ */
+export function parentSession(page, parentByFrame, frameId) {
+    const parentId = parentByFrame.get(frameId) ?? null;
+    if (!parentId) {
+        return page.getSessionForFrame(frameId);
+    }
+    return page.getSessionForFrame(parentId);
+}
+//# sourceMappingURL=sessions.js.map