@browserbasehq/orca 3.1.0-patch.3 → 3.2.0-preview.1

package/dist/cjs/lib/v3/understudy/a11y/snapshot/a11yTree.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"a11yTree.js","sourceRoot":"","sources":["../../../../../../../lib/v3/understudy/a11y/snapshot/a11yTree.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Protocol } from \"devtools-protocol\";\nimport type { CDPSessionLike } from \"../../cdp.js\";\nimport type {\n  A11yNode,\n  A11yOptions,\n  AccessibilityTreeResult,\n} from \"../../../types/private/snapshot.js\";\nimport {\n  resolveObjectIdForCss,\n  resolveObjectIdForXPath,\n} from \"./focusSelectors.js\";\nimport { formatTreeLine, normaliseSpaces } from \"./treeFormatUtils.js\";\n\n/**\n * Fetch and prune the accessibility tree for a frame, optionally scoping the\n * output to a selector root for faster targeted snapshots.\n */\nexport async function a11yForFrame(\n  session: CDPSessionLike,\n  frameId: string | undefined,\n  opts: A11yOptions,\n): Promise<AccessibilityTreeResult> {\n  await session.send(\"Accessibility.enable\").catch(() => {});\n  await session.send(\"Runtime.enable\").catch(() => {});\n  await session.send(\"DOM.enable\").catch(() => {});\n\n  let nodes: Protocol.Accessibility.AXNode[] = [];\n  try {\n    const params = frameId ? ({ frameId } as Record<string, unknown>) : {};\n    ({ nodes } = await session.send<{\n      nodes: Protocol.Accessibility.AXNode[];\n    }>(\"Accessibility.getFullAXTree\", params));\n  } catch (e) {\n    const msg = String((e as Error)?.message ?? e ?? \"\");\n    const isFrameScopeError =\n      msg.includes(\"Frame with the given\") ||\n      msg.includes(\"does not belong to the target\") ||\n      msg.includes(\"is not found\");\n    if (!isFrameScopeError || !frameId) throw e;\n    ({ nodes } = await session.send<{\n      nodes: Protocol.Accessibility.AXNode[];\n    }>(\"Accessibility.getFullAXTree\"));\n  }\n\n  const urlMap: Record<string, string> = {};\n  for (const n of nodes) {\n    const be = n.backendDOMNodeId;\n    if (typeof be !== \"number\") continue;\n    const url = extractUrlFromAXNode(n);\n    if (!url) continue;\n    const enc = opts.encode(be);\n    urlMap[enc] = url;\n  }\n\n  let scopeApplied = false;\n  const nodesForOutline = await (async () => {\n    const sel = opts.focusSelector?.trim();\n    if (!sel) return nodes;\n    try {\n      const looksLikeXPath = /^xpath=/i.test(sel) || sel.startsWith(\"/\");\n      const objectId = looksLikeXPath\n        ? await resolveObjectIdForXPath(session, sel, frameId)\n        : await resolveObjectIdForCss(session, sel, frameId);\n      if (!objectId) return nodes;\n      const desc = await session.send<{ node?: { backendNodeId?: number } }>(\n        \"DOM.describeNode\",\n        { objectId },\n      );\n      const be = desc.node?.backendNodeId;\n      if (typeof be !== \"number\") return nodes;\n      const target = nodes.find((n) => n.backendDOMNodeId === be);\n      if (!target) return nodes;\n      scopeApplied = true;\n      const keep = new Set<string>([target.nodeId]);\n      const queue: Protocol.Accessibility.AXNode[] = [target];\n      while (queue.length) {\n        const cur = queue.shift()!;\n        for (const id of cur.childIds ?? []) {\n          if (keep.has(id)) continue;\n          keep.add(id);\n          const child = nodes.find((n) => n.nodeId === id);\n          if (child) queue.push(child);\n        }\n      }\n      return nodes\n        .filter((n) => keep.has(n.nodeId))\n        .map((n) =>\n          n.nodeId === target.nodeId ? { ...n, parentId: undefined } : n,\n        );\n    } catch {\n      return nodes;\n    }\n  })();\n\n  const decorated = decorateRoles(nodesForOutline, opts);\n  const { tree } = await buildHierarchicalTree(decorated, opts);\n\n  const simplified = tree.map((n) => formatTreeLine(n)).join(\"\\n\");\n  return { outline: simplified.trimEnd(), urlMap, scopeApplied };\n}\n\nexport function decorateRoles(\n  nodes: Protocol.Accessibility.AXNode[],\n  opts: A11yOptions,\n): A11yNode[] {\n  const asRole = (n: Protocol.Accessibility.AXNode) =>\n    String(n.role?.value ?? \"\");\n\n  return nodes.map((n) => {\n    let encodedId: string | undefined;\n    if (typeof n.backendDOMNodeId === \"number\") {\n      try {\n        encodedId = opts.encode(n.backendDOMNodeId);\n      } catch {\n        //\n      }\n    }\n\n    let role = asRole(n);\n\n    const domIsScrollable = encodedId\n      ? opts.scrollableMap[encodedId] === true\n      : false;\n    const tag = encodedId ? opts.tagNameMap[encodedId] : undefined;\n    const isHtmlElement = tag === \"html\";\n    if ((domIsScrollable || isHtmlElement) && tag !== \"#document\") {\n      const tagLabel = tag && tag.startsWith(\"#\") ? tag.slice(1) : tag;\n      role = tagLabel\n        ? `scrollable, ${tagLabel}`\n        : `scrollable${role ? `, ${role}` : \"\"}`;\n    }\n\n    return {\n      role,\n      name: n.name?.value,\n      description: n.description?.value,\n      value: n.value?.value,\n      nodeId: n.nodeId,\n      backendDOMNodeId: n.backendDOMNodeId,\n      parentId: n.parentId,\n      childIds: n.childIds,\n      encodedId,\n    };\n  });\n}\n\nexport async function buildHierarchicalTree(\n  nodes: A11yNode[],\n  opts: A11yOptions,\n): Promise<{ tree: A11yNode[] }> {\n  const nodeMap = new Map<string, A11yNode>();\n\n  for (const n of nodes) {\n    const keep =\n      !!(n.name && n.name.trim()) ||\n      !!(n.childIds && n.childIds.length) ||\n      !isStructural(n.role);\n    if (!keep) continue;\n    nodeMap.set(n.nodeId, { ...n });\n  }\n\n  for (const n of nodes) {\n    if (!n.parentId) continue;\n    const parent = nodeMap.get(n.parentId);\n    const cur = nodeMap.get(n.nodeId);\n    if (parent && cur) (parent.children ??= []).push(cur);\n  }\n\n  const roots = nodes\n    .filter((n) => !n.parentId && nodeMap.has(n.nodeId))\n    .map((n) => nodeMap.get(n.nodeId)!) as A11yNode[];\n\n  const cleaned = (await Promise.all(roots.map(pruneStructuralSafe))).filter(\n    Boolean,\n  ) as A11yNode[];\n\n  return { tree: cleaned };\n\n  async function pruneStructuralSafe(node: A11yNode): Promise<A11yNode | null> {\n    if (+node.nodeId < 0) return null;\n\n    const children = node.children ?? [];\n    if (!children.length) {\n      return isStructural(node.role) ? null : node;\n    }\n\n    const cleanedKids = (\n      await Promise.all(children.map(pruneStructuralSafe))\n    ).filter(Boolean) as A11yNode[];\n\n    const prunedStatic = removeRedundantStaticTextChildren(node, cleanedKids);\n\n    if (isStructural(node.role)) {\n      if (prunedStatic.length === 1) return prunedStatic[0]!;\n      if (prunedStatic.length === 0) return null;\n    }\n\n    let newRole = node.role;\n    if ((newRole === \"generic\" || newRole === \"none\") && node.encodedId) {\n      const tagName = opts.tagNameMap[node.encodedId];\n      if (tagName) newRole = tagName;\n    }\n\n    if (newRole === \"combobox\" && node.encodedId) {\n      const tagName = opts.tagNameMap[node.encodedId];\n      if (tagName === \"select\") newRole = \"select\";\n    }\n\n    return { ...node, role: newRole, children: prunedStatic };\n  }\n}\n\nexport function isStructural(role: string): boolean {\n  const r = role?.toLowerCase();\n  return r === \"generic\" || r === \"none\" || r === \"inlinetextbox\";\n}\n\nexport function extractUrlFromAXNode(\n  ax: Protocol.Accessibility.AXNode,\n): string | undefined {\n  const props = ax.properties ?? [];\n  const urlProp = props.find((p) => p.name === \"url\");\n  const value = urlProp?.value?.value;\n  return typeof value === \"string\" && value.trim() ? value.trim() : undefined;\n}\n\nexport function removeRedundantStaticTextChildren(\n  parent: A11yNode,\n  children: A11yNode[],\n): A11yNode[] {\n  if (!parent.name) return children;\n  const parentNorm = normaliseSpaces(parent.name).trim();\n  let combined = \"\";\n  for (const c of children) {\n    if (c.role === \"StaticText\" && c.name) {\n      combined += normaliseSpaces(c.name).trim();\n    }\n  }\n  if (combined === parentNorm) {\n    return children.filter((c) => c.role !== \"StaticText\");\n  }\n  return children;\n}\n"]}

package/dist/cjs/lib/v3/understudy/a11y/snapshot/activeElement.js

@@ -0,0 +1,124 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeActiveElementXpath = computeActiveElementXpath;
+const executionContextRegistry_js_1 = require("../../executionContextRegistry.js");
+const a11yInvocation_js_1 = require("../../a11yInvocation.js");
+const a11yScripts_generated_js_1 = require("../../../dom/build/a11yScripts.generated.js");
+const xpathUtils_js_1 = require("./xpathUtils.js");
+/**
+ * Compute the absolute XPath for the currently focused element.
+ * - Detects which frame has focus via document.hasFocus().
+ * - Finds the deepest activeElement (dives into shadow DOM).
+ * - Builds an absolute, cross-frame XPath by prefixing iframe hosts.
+ */
+async function computeActiveElementXpath(page) {
+    const tree = page.getFullFrameTree();
+    const parentByFrame = new Map();
+    (function index(n, parent) {
+        parentByFrame.set(n.frame.id, parent);
+        for (const c of n.childFrames ?? [])
+            index(c, n.frame.id);
+    })(tree, null);
+    const frames = page.listAllFrameIds();
+    let focusedFrameId = null;
+    for (const fid of frames) {
+        const sess = page.getSessionForFrame(fid);
+        try {
+            await sess.send("Runtime.enable").catch(() => { });
+            const ctxId = await executionContextRegistry_js_1.executionContexts
+                .waitForMainWorld(sess, fid, 1000)
+                .catch(() => { });
+            const hasFocusExpr = (0, a11yInvocation_js_1.buildA11yInvocation)("documentHasFocusStrict", []);
+            const evalParams = ctxId
+                ? {
+                    contextId: ctxId,
+                    expression: hasFocusExpr,
+                    returnByValue: true,
+                }
+                : { expression: hasFocusExpr, returnByValue: true };
+            const { result } = await sess.send("Runtime.evaluate", evalParams);
+            if (result?.value === true) {
+                focusedFrameId = fid;
+                break;
+            }
+        }
+        catch {
+            //
+        }
+    }
+    if (!focusedFrameId)
+        focusedFrameId = page.mainFrameId();
+    const focusedSession = page.getSessionForFrame(focusedFrameId);
+    let objectId;
+    try {
+        await focusedSession.send("Runtime.enable").catch(() => { });
+        const ctxId = await executionContextRegistry_js_1.executionContexts
+            .waitForMainWorld(focusedSession, focusedFrameId, 1000)
+            .catch(() => { });
+        const activeExpr = (0, a11yInvocation_js_1.buildA11yInvocation)("resolveDeepActiveElement", []);
+        const evalParams = ctxId
+            ? {
+                contextId: ctxId,
+                expression: activeExpr,
+                returnByValue: false,
+            }
+            : { expression: activeExpr, returnByValue: false };
+        const { result } = await focusedSession.send("Runtime.evaluate", evalParams);
+        objectId = result?.objectId;
+    }
+    catch {
+        objectId = undefined;
+    }
+    if (!objectId)
+        return null;
+    const leafXPath = await (async () => {
+        try {
+            const { result } = await focusedSession.send("Runtime.callFunctionOn", {
+                objectId,
+                functionDeclaration: a11yScripts_generated_js_1.a11yScriptSources.nodeToAbsoluteXPath,
+                returnByValue: true,
+            });
+            try {
+                await focusedSession.send("Runtime.releaseObject", { objectId });
+            }
+            catch {
+                //
+            }
+            const xp = result?.value || "";
+            return typeof xp === "string" && xp ? xp : null;
+        }
+        catch {
+            try {
+                await focusedSession.send("Runtime.releaseObject", { objectId });
+            }
+            catch {
+                //
+            }
+            return null;
+        }
+    })();
+    if (!leafXPath)
+        return null;
+    let prefix = "";
+    let cur = focusedFrameId;
+    while (cur) {
+        const parent = parentByFrame.get(cur) ?? null;
+        if (!parent)
+            break;
+        const parentSess = page.getSessionForFrame(parent);
+        try {
+            const { backendNodeId } = await parentSess.send("DOM.getFrameOwner", { frameId: cur });
+            if (typeof backendNodeId === "number") {
+                const xp = await (0, xpathUtils_js_1.absoluteXPathForBackendNode)(parentSess, backendNodeId);
+                if (xp)
+                    prefix = prefix ? (0, xpathUtils_js_1.prefixXPath)(prefix, xp) : (0, xpathUtils_js_1.normalizeXPath)(xp);
+            }
+        }
+        catch {
+            //
+        }
+        cur = parent;
+    }
+    return prefix ? (0, xpathUtils_js_1.prefixXPath)(prefix, leafXPath) : (0, xpathUtils_js_1.normalizeXPath)(leafXPath);
+}
+//# sourceMappingURL=activeElement.js.map

package/dist/cjs/lib/v3/understudy/a11y/snapshot/activeElement.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"activeElement.js","sourceRoot":"","sources":["../../../../../../../lib/v3/understudy/a11y/snapshot/activeElement.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Protocol } from \"devtools-protocol\";\nimport { Page } from \"../../page.js\";\nimport { executionContexts } from \"../../executionContextRegistry.js\";\nimport { buildA11yInvocation } from \"../../a11yInvocation.js\";\nimport { a11yScriptSources } from \"../../../dom/build/a11yScripts.generated.js\";\nimport {\n  absoluteXPathForBackendNode,\n  normalizeXPath,\n  prefixXPath,\n} from \"./xpathUtils.js\";\n\n/**\n * Compute the absolute XPath for the currently focused element.\n * - Detects which frame has focus via document.hasFocus().\n * - Finds the deepest activeElement (dives into shadow DOM).\n * - Builds an absolute, cross-frame XPath by prefixing iframe hosts.\n */\nexport async function computeActiveElementXpath(\n  page: Page,\n): Promise<string | null> {\n  const tree = page.getFullFrameTree();\n  const parentByFrame = new Map<string, string | null>();\n  (function index(n: Protocol.Page.FrameTree, parent: string | null) {\n    parentByFrame.set(n.frame.id, parent);\n    for (const c of n.childFrames ?? []) index(c, n.frame.id);\n  })(tree, null);\n\n  const frames = page.listAllFrameIds();\n  let focusedFrameId: string | null = null;\n  for (const fid of frames) {\n    const sess = page.getSessionForFrame(fid);\n    try {\n      await sess.send(\"Runtime.enable\").catch(() => {});\n      const ctxId = await executionContexts\n        .waitForMainWorld(sess, fid, 1000)\n        .catch(() => {});\n      const hasFocusExpr = buildA11yInvocation(\"documentHasFocusStrict\", []);\n      const evalParams = ctxId\n        ? {\n            contextId: ctxId,\n            expression: hasFocusExpr,\n            returnByValue: true,\n          }\n        : { expression: hasFocusExpr, returnByValue: true };\n      const { result } = await sess.send<Protocol.Runtime.EvaluateResponse>(\n        \"Runtime.evaluate\",\n        evalParams,\n      );\n      if (result?.value === true) {\n        focusedFrameId = fid;\n        break;\n      }\n    } catch {\n      //\n    }\n  }\n  if (!focusedFrameId) focusedFrameId = page.mainFrameId();\n  const focusedSession = page.getSessionForFrame(focusedFrameId);\n\n  let objectId: string | undefined;\n  try {\n    await focusedSession.send(\"Runtime.enable\").catch(() => {});\n    const ctxId = await executionContexts\n      .waitForMainWorld(focusedSession, focusedFrameId, 1000)\n      .catch(() => {});\n    const activeExpr = buildA11yInvocation(\"resolveDeepActiveElement\", []);\n    const evalParams = ctxId\n      ? {\n          contextId: ctxId,\n          expression: activeExpr,\n          returnByValue: false,\n        }\n      : { expression: activeExpr, returnByValue: false };\n    const { result } =\n      await focusedSession.send<Protocol.Runtime.EvaluateResponse>(\n        \"Runtime.evaluate\",\n        evalParams,\n      );\n    objectId = result?.objectId as string | undefined;\n  } catch {\n    objectId = undefined;\n  }\n  if (!objectId) return null;\n\n  const leafXPath = await (async () => {\n    try {\n      const { result } = await focusedSession.send<{\n        result: { value?: string };\n      }>(\"Runtime.callFunctionOn\", {\n        objectId,\n        functionDeclaration: a11yScriptSources.nodeToAbsoluteXPath,\n        returnByValue: true,\n      });\n      try {\n        await focusedSession.send(\"Runtime.releaseObject\", { objectId });\n      } catch {\n        //\n      }\n      const xp = result?.value || \"\";\n      return typeof xp === \"string\" && xp ? xp : null;\n    } catch {\n      try {\n        await focusedSession.send(\"Runtime.releaseObject\", { objectId });\n      } catch {\n        //\n      }\n      return null;\n    }\n  })();\n\n  if (!leafXPath) return null;\n\n  let prefix = \"\";\n  let cur: string | null | undefined = focusedFrameId;\n  while (cur) {\n    const parent = parentByFrame.get(cur) ?? null;\n    if (!parent) break;\n    const parentSess = page.getSessionForFrame(parent);\n    try {\n      const { backendNodeId } = await parentSess.send<{\n        backendNodeId?: number;\n      }>(\"DOM.getFrameOwner\", { frameId: cur });\n      if (typeof backendNodeId === \"number\") {\n        const xp = await absoluteXPathForBackendNode(parentSess, backendNodeId);\n        if (xp) prefix = prefix ? prefixXPath(prefix, xp) : normalizeXPath(xp);\n      }\n    } catch {\n      //\n    }\n    cur = parent;\n  }\n\n  return prefix ? prefixXPath(prefix, leafXPath) : normalizeXPath(leafXPath);\n}\n"]}

package/dist/cjs/lib/v3/understudy/a11y/snapshot/capture.js

@@ -0,0 +1,345 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.captureHybridSnapshot = captureHybridSnapshot;
+exports.buildFrameContext = buildFrameContext;
+exports.tryScopedSnapshot = tryScopedSnapshot;
+exports.buildSessionIndexes = buildSessionIndexes;
+exports.collectPerFrameMaps = collectPerFrameMaps;
+exports.computeFramePrefixes = computeFramePrefixes;
+exports.mergeFramesIntoSnapshot = mergeFramesIntoSnapshot;
+const logger_js_1 = require("../../../logger.js");
+const a11yTree_js_1 = require("./a11yTree.js");
+const focusSelectors_js_1 = require("./focusSelectors.js");
+const domTree_js_1 = require("./domTree.js");
+const treeFormatUtils_js_1 = require("./treeFormatUtils.js");
+const sessions_js_1 = require("./sessions.js");
+const xpathUtils_js_1 = require("./xpathUtils.js");
+/**
+ * Capture a hybrid DOM + Accessibility snapshot for the provided page.
+ *
+ * Flow overview:
+ * 1. (Optional) Scope directly to a requested selector. We walk iframe hops to
+ *    find the owning frame, build just that frame’s DOM + AX tree, and bail out
+ *    early when the subtree satisfies the caller.
+ * 2. Build DOM indexes for every unique CDP session. DOM.getDocument is called
+ *    once per session and hydrated so per-frame slices can share the result.
+ * 3. Slice each frame’s DOM data from its session index and fetch its AX tree.
+ *    This yields relative XPath/tag/url maps for the document rooted at that frame.
+ * 4. Walk the frame tree to compute absolute iframe prefixes. Every child frame
+ *    needs the XPath of the iframe element that hosts it so we can prefix maps.
+ * 5. Merge all per-frame results into global combined maps and stitch the text
+ *    outline. The final payload mirrors the legacy shape but is built in layers.
+ *
+ * Each numbered block below references the step above for easier debugging.
+ */
+async function captureHybridSnapshot(page, options) {
+    const pierce = options?.pierceShadow ?? true;
+    const includeIframes = options?.includeIframes !== false;
+    const context = buildFrameContext(page);
+    const scopedSnapshot = await tryScopedSnapshot(page, options, context, pierce);
+    if (scopedSnapshot)
+        return scopedSnapshot;
+    const framesInScope = includeIframes ? [...context.frames] : [context.rootId];
+    if (!framesInScope.includes(context.rootId)) {
+        framesInScope.unshift(context.rootId);
+    }
+    const sessionToIndex = await buildSessionIndexes(page, framesInScope, pierce);
+    const { perFrameMaps, perFrameOutlines } = await collectPerFrameMaps(page, context, sessionToIndex, options, pierce, framesInScope);
+    const { absPrefix, iframeHostEncByChild } = await computeFramePrefixes(page, context, perFrameMaps, framesInScope);
+    return mergeFramesIntoSnapshot(context, perFrameMaps, perFrameOutlines, absPrefix, iframeHostEncByChild, framesInScope);
+}
+/**
+ * Snapshot the current frame tree so downstream helpers have consistent topology
+ * without re-querying CDP. The map is intentionally shallow (frameId → parentId)
+ * so it is serializable/testable without holding on to CDP handles.
+ */
+function buildFrameContext(page) {
+    const rootId = page.mainFrameId();
+    const frameTree = page.asProtocolFrameTree(rootId);
+    const parentByFrame = new Map();
+    (function index(n, parent) {
+        parentByFrame.set(n.frame.id, parent);
+        for (const c of n.childFrames ?? [])
+            index(c, n.frame.id);
+    })(frameTree, null);
+    const frames = page.listAllFrameIds();
+    return { rootId, parentByFrame, frames };
+}
+/**
+ * Step 1 – scoped snapshot fast-path. If a selector is provided we try to:
+ *  1) Resolve the selector (XPath or CSS) across iframes.
+ *  2) Build DOM + AX data only for the owning frame.
+ *  3) Bail out early when the selector's subtree satisfies the request.
+ *
+ * Returns `null` when scoping fails (e.g., selector miss) so the caller can
+ * fall back to the full multi-frame snapshot.
+ */
+async function tryScopedSnapshot(page, options, context, pierce) {
+    const requestedFocus = options?.focusSelector?.trim();
+    if (!requestedFocus)
+        return null;
+    const logScopeFallback = () => {
+        (0, logger_js_1.v3Logger)({
+            message: `Unable to narrow scope with selector. Falling back to using full DOM`,
+            level: 1,
+            auxiliary: {
+                arguments: {
+                    value: `selector: ${options?.focusSelector?.trim()}`,
+                    type: "string",
+                },
+            },
+        });
+    };
+    try {
+        let targetFrameId;
+        let tailSelector;
+        let absPrefix;
+        const looksLikeXPath = /^xpath=/i.test(requestedFocus) || requestedFocus.startsWith("/");
+        if (looksLikeXPath) {
+            const focus = (0, xpathUtils_js_1.normalizeXPath)(requestedFocus);
+            const hit = await (0, focusSelectors_js_1.resolveFocusFrameAndTail)(page, focus, context.parentByFrame, context.rootId);
+            targetFrameId = hit.targetFrameId;
+            tailSelector = hit.tailXPath || undefined;
+            absPrefix = hit.absPrefix;
+        }
+        else {
+            const cssHit = await (0, focusSelectors_js_1.resolveCssFocusFrameAndTail)(page, requestedFocus, context.parentByFrame, context.rootId);
+            targetFrameId = cssHit.targetFrameId;
+            tailSelector = cssHit.tailSelector || undefined;
+            absPrefix = cssHit.absPrefix;
+        }
+        const owningSess = (0, sessions_js_1.ownerSession)(page, targetFrameId);
+        const parentId = context.parentByFrame.get(targetFrameId);
+        const sameSessionAsParent = !!parentId &&
+            (0, sessions_js_1.ownerSession)(page, parentId) === (0, sessions_js_1.ownerSession)(page, targetFrameId);
+        const { tagNameMap, xpathMap, scrollableMap } = await (0, domTree_js_1.domMapsForSession)(owningSess, targetFrameId, pierce, (fid, be) => `${page.getOrdinal(fid)}-${be}`, sameSessionAsParent);
+        const { outline, urlMap, scopeApplied } = await (0, a11yTree_js_1.a11yForFrame)(owningSess, targetFrameId, {
+            focusSelector: tailSelector || undefined,
+            tagNameMap,
+            experimental: options?.experimental ?? false,
+            scrollableMap,
+            encode: (backendNodeId) => `${page.getOrdinal(targetFrameId)}-${backendNodeId}`,
+        });
+        const scopedXpathMap = {};
+        const abs = absPrefix ?? "";
+        const isRoot = !abs || abs === "/";
+        if (isRoot) {
+            Object.assign(scopedXpathMap, xpathMap);
+        }
+        else {
+            // Prefix relative XPaths so the scoped result matches the global encoding.
+            for (const [encId, xp] of Object.entries(xpathMap)) {
+                scopedXpathMap[encId] = (0, xpathUtils_js_1.prefixXPath)(abs, xp);
+            }
+        }
+        const scopedUrlMap = { ...urlMap };
+        const snapshot = {
+            combinedTree: outline,
+            combinedXpathMap: scopedXpathMap,
+            combinedUrlMap: scopedUrlMap,
+            perFrame: [
+                {
+                    frameId: targetFrameId,
+                    outline,
+                    xpathMap,
+                    urlMap,
+                },
+            ],
+        };
+        if (scopeApplied) {
+            return snapshot;
+        }
+        logScopeFallback();
+    }
+    catch {
+        logScopeFallback();
+    }
+    return null;
+}
+/**
+ * Step 2 – call DOM.getDocument once per unique CDP session and hydrate the
+ * result so per-frame slices can share the structure. We key by session id
+ * because same process iframes live inside the same session.
+ */
+async function buildSessionIndexes(page, frames, pierce) {
+    const sessionToIndex = new Map();
+    const sessionById = new Map();
+    for (const frameId of frames) {
+        const sess = (0, sessions_js_1.ownerSession)(page, frameId);
+        const sid = sess.id ?? "root";
+        if (!sessionById.has(sid))
+            sessionById.set(sid, sess);
+    }
+    for (const [sid, sess] of sessionById.entries()) {
+        const idx = await (0, domTree_js_1.buildSessionDomIndex)(sess, pierce);
+        sessionToIndex.set(sid, idx);
+    }
+    return sessionToIndex;
+}
+/**
+ * Step 3 – derive per-frame DOM maps and accessibility outlines.
+ * Each frame:
+ *  - slices the shared session index down to its document root
+ *  - builds frame-aware encoded ids (ordinal-backendNodeId)
+ *  - collects tag/xpath/scrollability maps for DOM-based lookups
+ *  - fetches its AX tree to produce outlines and URL maps
+ */
+async function collectPerFrameMaps(page, context, sessionToIndex, options, pierce, frameIds) {
+    const perFrameMaps = new Map();
+    const perFrameOutlines = [];
+    for (const frameId of frameIds) {
+        const sess = (0, sessions_js_1.ownerSession)(page, frameId);
+        const sid = sess.id ?? "root";
+        let idx = sessionToIndex.get(sid);
+        if (!idx) {
+            idx = await (0, domTree_js_1.buildSessionDomIndex)(sess, pierce);
+            sessionToIndex.set(sid, idx);
+        }
+        const parentId = context.parentByFrame.get(frameId);
+        const sameSessionAsParent = !!parentId && (0, sessions_js_1.ownerSession)(page, parentId) === sess;
+        let docRootBe = idx.rootBackend;
+        if (sameSessionAsParent) {
+            try {
+                const { backendNodeId } = await sess.send("DOM.getFrameOwner", { frameId });
+                if (typeof backendNodeId === "number") {
+                    const cdBe = idx.contentDocRootByIframe.get(backendNodeId);
+                    if (typeof cdBe === "number")
+                        docRootBe = cdBe;
+                }
+            }
+            catch {
+                //
+            }
+        }
+        const tagNameMap = {};
+        const xpathMap = {};
+        const scrollableMap = {};
+        const enc = (be) => `${page.getOrdinal(frameId)}-${be}`;
+        const baseAbs = idx.absByBe.get(docRootBe) ?? "/";
+        for (const [be, nodeAbs] of idx.absByBe.entries()) {
+            const nodeDocRoot = idx.docRootOf.get(be);
+            if (nodeDocRoot !== docRootBe)
+                continue;
+            // Translate absolute XPaths into document-relative ones for this frame.
+            const rel = (0, domTree_js_1.relativizeXPath)(baseAbs, nodeAbs);
+            const key = enc(be);
+            xpathMap[key] = rel;
+            const tag = idx.tagByBe.get(be);
+            if (tag)
+                tagNameMap[key] = tag;
+            if (idx.scrollByBe.get(be))
+                scrollableMap[key] = true;
+        }
+        const { outline, urlMap } = await (0, a11yTree_js_1.a11yForFrame)(sess, frameId, {
+            experimental: options?.experimental ?? false,
+            tagNameMap,
+            scrollableMap,
+            encode: (backendNodeId) => `${page.getOrdinal(frameId)}-${backendNodeId}`,
+        });
+        perFrameOutlines.push({ frameId, outline });
+        perFrameMaps.set(frameId, { tagNameMap, xpathMap, scrollableMap, urlMap });
+    }
+    return { perFrameMaps, perFrameOutlines };
+}
+/**
+ * Step 4 – walk the frame tree (parent-first) to compute absolute prefixes for
+ * every frame. The prefix is the absolute XPath of the iframe element hosting
+ * the frame, so we can later convert relative XPaths into cross-frame ones.
+ */
+async function computeFramePrefixes(page, context, perFrameMaps, frameIds) {
+    const absPrefix = new Map();
+    const iframeHostEncByChild = new Map();
+    absPrefix.set(context.rootId, "");
+    const included = new Set(frameIds);
+    const queue = [];
+    if (included.has(context.rootId)) {
+        queue.push(context.rootId);
+    }
+    while (queue.length) {
+        const parent = queue.shift();
+        const parentAbs = absPrefix.get(parent);
+        for (const child of context.frames) {
+            if (!included.has(child))
+                continue;
+            if (context.parentByFrame.get(child) !== parent)
+                continue;
+            queue.push(child);
+            const parentSess = (0, sessions_js_1.parentSession)(page, context.parentByFrame, child);
+            const ownerBackendNodeId = await (async () => {
+                try {
+                    const { backendNodeId } = await parentSess.send("DOM.getFrameOwner", { frameId: child });
+                    return backendNodeId;
+                }
+                catch {
+                    return undefined;
+                }
+            })();
+            if (!ownerBackendNodeId) {
+                // OOPIFs resolved via a different session inherit the parent prefix.
+                absPrefix.set(child, parentAbs);
+                continue;
+            }
+            const parentDom = perFrameMaps.get(parent);
+            const iframeEnc = `${page.getOrdinal(parent)}-${ownerBackendNodeId}`;
+            const iframeXPath = parentDom?.xpathMap[iframeEnc];
+            const childAbs = iframeXPath
+                ? (0, xpathUtils_js_1.prefixXPath)(parentAbs || "/", iframeXPath)
+                : parentAbs;
+            absPrefix.set(child, childAbs);
+            iframeHostEncByChild.set(child, iframeEnc);
+        }
+    }
+    return { absPrefix, iframeHostEncByChild };
+}
+/**
+ * Step 5 – merge per-frame maps into the combined snapshot payload. We prefix
+ * each frame's relative XPaths with the absolute path collected in step 4,
+ * merge URL maps, and stitch text outlines by nesting child trees under the
+ * encoded id of their parent iframe host.
+ */
+function mergeFramesIntoSnapshot(context, perFrameMaps, perFrameOutlines, absPrefix, iframeHostEncByChild, frameIds) {
+    const combinedXpathMap = {};
+    const combinedUrlMap = {};
+    for (const frameId of frameIds) {
+        const maps = perFrameMaps.get(frameId);
+        if (!maps)
+            continue;
+        const abs = absPrefix.get(frameId) ?? "";
+        const isRoot = abs === "" || abs === "/";
+        if (isRoot) {
+            Object.assign(combinedXpathMap, maps.xpathMap);
+            Object.assign(combinedUrlMap, maps.urlMap);
+            continue;
+        }
+        for (const [encId, xp] of Object.entries(maps.xpathMap)) {
+            combinedXpathMap[encId] = (0, xpathUtils_js_1.prefixXPath)(abs, xp);
+        }
+        Object.assign(combinedUrlMap, maps.urlMap);
+    }
+    const idToTree = new Map();
+    for (const { frameId, outline } of perFrameOutlines) {
+        const parentEnc = iframeHostEncByChild.get(frameId);
+        // The key is the parent iframe's encoded id so injectSubtrees can nest lines.
+        if (parentEnc)
+            idToTree.set(parentEnc, outline);
+    }
+    const rootOutline = perFrameOutlines.find((o) => o.frameId === context.rootId)?.outline ??
+        perFrameOutlines[0]?.outline ??
+        "";
+    const combinedTree = (0, treeFormatUtils_js_1.injectSubtrees)(rootOutline, idToTree);
+    return {
+        combinedTree,
+        combinedXpathMap,
+        combinedUrlMap,
+        perFrame: perFrameOutlines.map(({ frameId, outline }) => {
+            const maps = perFrameMaps.get(frameId);
+            return {
+                frameId,
+                outline,
+                xpathMap: maps?.xpathMap ?? {},
+                urlMap: maps?.urlMap ?? {},
+            };
+        }),
+    };
+}
+//# sourceMappingURL=capture.js.map

package/dist/cjs/lib/v3/understudy/a11y/snapshot/capture.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capture.js","sourceRoot":"","sources":["../../../../../../../lib/v3/understudy/a11y/snapshot/capture.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 { v3Logger } from \"../../../logger.js\";\nimport type {\n  FrameContext,\n  FrameDomMaps,\n  FrameParentIndex,\n  HybridSnapshot,\n  SnapshotOptions,\n  SessionDomIndex,\n} from \"../../../types/private/index.js\";\nimport { a11yForFrame } from \"./a11yTree.js\";\nimport {\n  resolveCssFocusFrameAndTail,\n  resolveFocusFrameAndTail,\n} from \"./focusSelectors.js\";\nimport {\n  buildSessionDomIndex,\n  domMapsForSession,\n  relativizeXPath,\n} from \"./domTree.js\";\nimport { injectSubtrees } from \"./treeFormatUtils.js\";\nimport { ownerSession, parentSession } from \"./sessions.js\";\nimport { normalizeXPath, prefixXPath } from \"./xpathUtils.js\";\n\n/**\n * Capture a hybrid DOM + Accessibility snapshot for the provided page.\n *\n * Flow overview:\n * 1. (Optional) Scope directly to a requested selector. We walk iframe hops to\n *    find the owning frame, build just that frame’s DOM + AX tree, and bail out\n *    early when the subtree satisfies the caller.\n * 2. Build DOM indexes for every unique CDP session. DOM.getDocument is called\n *    once per session and hydrated so per-frame slices can share the result.\n * 3. Slice each frame’s DOM data from its session index and fetch its AX tree.\n *    This yields relative XPath/tag/url maps for the document rooted at that frame.\n * 4. Walk the frame tree to compute absolute iframe prefixes. Every child frame\n *    needs the XPath of the iframe element that hosts it so we can prefix maps.\n * 5. Merge all per-frame results into global combined maps and stitch the text\n *    outline. The final payload mirrors the legacy shape but is built in layers.\n *\n * Each numbered block below references the step above for easier debugging.\n */\nexport async function captureHybridSnapshot(\n  page: Page,\n  options?: SnapshotOptions,\n): Promise<HybridSnapshot> {\n  const pierce = options?.pierceShadow ?? true;\n  const includeIframes = options?.includeIframes !== false;\n\n  const context = buildFrameContext(page);\n\n  const scopedSnapshot = await tryScopedSnapshot(\n    page,\n    options,\n    context,\n    pierce,\n  );\n  if (scopedSnapshot) return scopedSnapshot;\n\n  const framesInScope = includeIframes ? [...context.frames] : [context.rootId];\n  if (!framesInScope.includes(context.rootId)) {\n    framesInScope.unshift(context.rootId);\n  }\n\n  const sessionToIndex = await buildSessionIndexes(page, framesInScope, pierce);\n  const { perFrameMaps, perFrameOutlines } = await collectPerFrameMaps(\n    page,\n    context,\n    sessionToIndex,\n    options,\n    pierce,\n    framesInScope,\n  );\n  const { absPrefix, iframeHostEncByChild } = await computeFramePrefixes(\n    page,\n    context,\n    perFrameMaps,\n    framesInScope,\n  );\n\n  return mergeFramesIntoSnapshot(\n    context,\n    perFrameMaps,\n    perFrameOutlines,\n    absPrefix,\n    iframeHostEncByChild,\n    framesInScope,\n  );\n}\n\n/**\n * Snapshot the current frame tree so downstream helpers have consistent topology\n * without re-querying CDP. The map is intentionally shallow (frameId → parentId)\n * so it is serializable/testable without holding on to CDP handles.\n */\nexport function buildFrameContext(page: Page): FrameContext {\n  const rootId = page.mainFrameId();\n  const frameTree = page.asProtocolFrameTree(rootId);\n  const parentByFrame: FrameParentIndex = new Map();\n  (function index(n: Protocol.Page.FrameTree, parent: string | null) {\n    parentByFrame.set(n.frame.id, parent);\n    for (const c of n.childFrames ?? []) index(c, n.frame.id);\n  })(frameTree, null);\n  const frames = page.listAllFrameIds();\n  return { rootId, parentByFrame, frames };\n}\n\n/**\n * Step 1 – scoped snapshot fast-path. If a selector is provided we try to:\n *  1) Resolve the selector (XPath or CSS) across iframes.\n *  2) Build DOM + AX data only for the owning frame.\n *  3) Bail out early when the selector's subtree satisfies the request.\n *\n * Returns `null` when scoping fails (e.g., selector miss) so the caller can\n * fall back to the full multi-frame snapshot.\n */\nexport async function tryScopedSnapshot(\n  page: Page,\n  options: SnapshotOptions | undefined,\n  context: FrameContext,\n  pierce: boolean,\n): Promise<HybridSnapshot | null> {\n  const requestedFocus = options?.focusSelector?.trim();\n  if (!requestedFocus) return null;\n\n  const logScopeFallback = () => {\n    v3Logger({\n      message: `Unable to narrow scope with selector. Falling back to using full DOM`,\n      level: 1,\n      auxiliary: {\n        arguments: {\n          value: `selector: ${options?.focusSelector?.trim()}`,\n          type: \"string\",\n        },\n      },\n    });\n  };\n\n  try {\n    let targetFrameId: string;\n    let tailSelector: string | undefined;\n    let absPrefix: string | undefined;\n\n    const looksLikeXPath =\n      /^xpath=/i.test(requestedFocus) || requestedFocus.startsWith(\"/\");\n    if (looksLikeXPath) {\n      const focus = normalizeXPath(requestedFocus);\n      const hit = await resolveFocusFrameAndTail(\n        page,\n        focus,\n        context.parentByFrame,\n        context.rootId,\n      );\n      targetFrameId = hit.targetFrameId;\n      tailSelector = hit.tailXPath || undefined;\n      absPrefix = hit.absPrefix;\n    } else {\n      const cssHit = await resolveCssFocusFrameAndTail(\n        page,\n        requestedFocus,\n        context.parentByFrame,\n        context.rootId,\n      );\n      targetFrameId = cssHit.targetFrameId;\n      tailSelector = cssHit.tailSelector || undefined;\n      absPrefix = cssHit.absPrefix;\n    }\n\n    const owningSess = ownerSession(page, targetFrameId);\n    const parentId = context.parentByFrame.get(targetFrameId);\n    const sameSessionAsParent =\n      !!parentId &&\n      ownerSession(page, parentId) === ownerSession(page, targetFrameId);\n    const { tagNameMap, xpathMap, scrollableMap } = await domMapsForSession(\n      owningSess,\n      targetFrameId,\n      pierce,\n      (fid, be) => `${page.getOrdinal(fid)}-${be}`,\n      sameSessionAsParent,\n    );\n\n    const { outline, urlMap, scopeApplied } = await a11yForFrame(\n      owningSess,\n      targetFrameId,\n      {\n        focusSelector: tailSelector || undefined,\n        tagNameMap,\n        experimental: options?.experimental ?? false,\n        scrollableMap,\n        encode: (backendNodeId) =>\n          `${page.getOrdinal(targetFrameId)}-${backendNodeId}`,\n      },\n    );\n\n    const scopedXpathMap: Record<string, string> = {};\n    const abs = absPrefix ?? \"\";\n    const isRoot = !abs || abs === \"/\";\n    if (isRoot) {\n      Object.assign(scopedXpathMap, xpathMap);\n    } else {\n      // Prefix relative XPaths so the scoped result matches the global encoding.\n      for (const [encId, xp] of Object.entries(xpathMap)) {\n        scopedXpathMap[encId] = prefixXPath(abs, xp);\n      }\n    }\n\n    const scopedUrlMap: Record<string, string> = { ...urlMap };\n\n    const snapshot: HybridSnapshot = {\n      combinedTree: outline,\n      combinedXpathMap: scopedXpathMap,\n      combinedUrlMap: scopedUrlMap,\n      perFrame: [\n        {\n          frameId: targetFrameId,\n          outline,\n          xpathMap,\n          urlMap,\n        },\n      ],\n    };\n\n    if (scopeApplied) {\n      return snapshot;\n    }\n\n    logScopeFallback();\n  } catch {\n    logScopeFallback();\n  }\n  return null;\n}\n\n/**\n * Step 2 – call DOM.getDocument once per unique CDP session and hydrate the\n * result so per-frame slices can share the structure. We key by session id\n * because same process iframes live inside the same session.\n */\nexport async function buildSessionIndexes(\n  page: Page,\n  frames: string[],\n  pierce: boolean,\n): Promise<Map<string, SessionDomIndex>> {\n  const sessionToIndex = new Map<string, SessionDomIndex>();\n  const sessionById = new Map<string, CDPSessionLike>();\n  for (const frameId of frames) {\n    const sess = ownerSession(page, frameId);\n    const sid = sess.id ?? \"root\";\n    if (!sessionById.has(sid)) sessionById.set(sid, sess);\n  }\n  for (const [sid, sess] of sessionById.entries()) {\n    const idx = await buildSessionDomIndex(sess, pierce);\n    sessionToIndex.set(sid, idx);\n  }\n  return sessionToIndex;\n}\n\n/**\n * Step 3 – derive per-frame DOM maps and accessibility outlines.\n * Each frame:\n *  - slices the shared session index down to its document root\n *  - builds frame-aware encoded ids (ordinal-backendNodeId)\n *  - collects tag/xpath/scrollability maps for DOM-based lookups\n *  - fetches its AX tree to produce outlines and URL maps\n */\nexport async function collectPerFrameMaps(\n  page: Page,\n  context: FrameContext,\n  sessionToIndex: Map<string, SessionDomIndex>,\n  options: SnapshotOptions | undefined,\n  pierce: boolean,\n  frameIds: string[],\n): Promise<{\n  perFrameMaps: Map<string, FrameDomMaps>;\n  perFrameOutlines: Array<{ frameId: string; outline: string }>;\n}> {\n  const perFrameMaps = new Map<string, FrameDomMaps>();\n  const perFrameOutlines: Array<{ frameId: string; outline: string }> = [];\n\n  for (const frameId of frameIds) {\n    const sess = ownerSession(page, frameId);\n    const sid = sess.id ?? \"root\";\n    let idx = sessionToIndex.get(sid);\n    if (!idx) {\n      idx = await buildSessionDomIndex(sess, pierce);\n      sessionToIndex.set(sid, idx);\n    }\n\n    const parentId = context.parentByFrame.get(frameId);\n    const sameSessionAsParent =\n      !!parentId && ownerSession(page, parentId) === sess;\n    let docRootBe = idx.rootBackend;\n    if (sameSessionAsParent) {\n      try {\n        const { backendNodeId } = await sess.send<{ backendNodeId?: number }>(\n          \"DOM.getFrameOwner\",\n          { frameId },\n        );\n        if (typeof backendNodeId === \"number\") {\n          const cdBe = idx.contentDocRootByIframe.get(backendNodeId);\n          if (typeof cdBe === \"number\") docRootBe = cdBe;\n        }\n      } catch {\n        //\n      }\n    }\n\n    const tagNameMap: Record<string, string> = {};\n    const xpathMap: Record<string, string> = {};\n    const scrollableMap: Record<string, boolean> = {};\n    const enc = (be: number) => `${page.getOrdinal(frameId)}-${be}`;\n    const baseAbs = idx.absByBe.get(docRootBe) ?? \"/\";\n\n    for (const [be, nodeAbs] of idx.absByBe.entries()) {\n      const nodeDocRoot = idx.docRootOf.get(be);\n      if (nodeDocRoot !== docRootBe) continue;\n\n      // Translate absolute XPaths into document-relative ones for this frame.\n      const rel = relativizeXPath(baseAbs, nodeAbs);\n      const key = enc(be);\n      xpathMap[key] = rel;\n      const tag = idx.tagByBe.get(be);\n      if (tag) tagNameMap[key] = tag;\n      if (idx.scrollByBe.get(be)) scrollableMap[key] = true;\n    }\n\n    const { outline, urlMap } = await a11yForFrame(sess, frameId, {\n      experimental: options?.experimental ?? false,\n      tagNameMap,\n      scrollableMap,\n      encode: (backendNodeId) => `${page.getOrdinal(frameId)}-${backendNodeId}`,\n    });\n\n    perFrameOutlines.push({ frameId, outline });\n    perFrameMaps.set(frameId, { tagNameMap, xpathMap, scrollableMap, urlMap });\n  }\n\n  return { perFrameMaps, perFrameOutlines };\n}\n\n/**\n * Step 4 – walk the frame tree (parent-first) to compute absolute prefixes for\n * every frame. The prefix is the absolute XPath of the iframe element hosting\n * the frame, so we can later convert relative XPaths into cross-frame ones.\n */\nexport async function computeFramePrefixes(\n  page: Page,\n  context: FrameContext,\n  perFrameMaps: Map<string, FrameDomMaps>,\n  frameIds: string[],\n): Promise<{\n  absPrefix: Map<string, string>;\n  iframeHostEncByChild: Map<string, string>;\n}> {\n  const absPrefix = new Map<string, string>();\n  const iframeHostEncByChild = new Map<string, string>();\n  absPrefix.set(context.rootId, \"\");\n  const included = new Set(frameIds);\n\n  const queue: string[] = [];\n  if (included.has(context.rootId)) {\n    queue.push(context.rootId);\n  }\n\n  while (queue.length) {\n    const parent = queue.shift()!;\n    const parentAbs = absPrefix.get(parent)!;\n\n    for (const child of context.frames) {\n      if (!included.has(child)) continue;\n      if (context.parentByFrame.get(child) !== parent) continue;\n      queue.push(child);\n\n      const parentSess = parentSession(page, context.parentByFrame, child);\n\n      const ownerBackendNodeId = await (async () => {\n        try {\n          const { backendNodeId } = await parentSess.send<{\n            backendNodeId?: number;\n          }>(\"DOM.getFrameOwner\", { frameId: child });\n          return backendNodeId;\n        } catch {\n          return undefined;\n        }\n      })();\n\n      if (!ownerBackendNodeId) {\n        // OOPIFs resolved via a different session inherit the parent prefix.\n        absPrefix.set(child, parentAbs);\n        continue;\n      }\n\n      const parentDom = perFrameMaps.get(parent);\n      const iframeEnc = `${page.getOrdinal(parent)}-${ownerBackendNodeId}`;\n      const iframeXPath = parentDom?.xpathMap[iframeEnc];\n\n      const childAbs = iframeXPath\n        ? prefixXPath(parentAbs || \"/\", iframeXPath)\n        : parentAbs;\n\n      absPrefix.set(child, childAbs);\n      iframeHostEncByChild.set(child, iframeEnc);\n    }\n  }\n\n  return { absPrefix, iframeHostEncByChild };\n}\n\n/**\n * Step 5 – merge per-frame maps into the combined snapshot payload. We prefix\n * each frame's relative XPaths with the absolute path collected in step 4,\n * merge URL maps, and stitch text outlines by nesting child trees under the\n * encoded id of their parent iframe host.\n */\nexport function mergeFramesIntoSnapshot(\n  context: FrameContext,\n  perFrameMaps: Map<string, FrameDomMaps>,\n  perFrameOutlines: Array<{ frameId: string; outline: string }>,\n  absPrefix: Map<string, string>,\n  iframeHostEncByChild: Map<string, string>,\n  frameIds: string[],\n): HybridSnapshot {\n  const combinedXpathMap: Record<string, string> = {};\n  const combinedUrlMap: Record<string, string> = {};\n\n  for (const frameId of frameIds) {\n    const maps = perFrameMaps.get(frameId);\n    if (!maps) continue;\n\n    const abs = absPrefix.get(frameId) ?? \"\";\n    const isRoot = abs === \"\" || abs === \"/\";\n\n    if (isRoot) {\n      Object.assign(combinedXpathMap, maps.xpathMap);\n      Object.assign(combinedUrlMap, maps.urlMap);\n      continue;\n    }\n\n    for (const [encId, xp] of Object.entries(maps.xpathMap)) {\n      combinedXpathMap[encId] = prefixXPath(abs, xp);\n    }\n    Object.assign(combinedUrlMap, maps.urlMap);\n  }\n\n  const idToTree = new Map<string, string>();\n  for (const { frameId, outline } of perFrameOutlines) {\n    const parentEnc = iframeHostEncByChild.get(frameId);\n    // The key is the parent iframe's encoded id so injectSubtrees can nest lines.\n    if (parentEnc) idToTree.set(parentEnc, outline);\n  }\n\n  const rootOutline =\n    perFrameOutlines.find((o) => o.frameId === context.rootId)?.outline ??\n    perFrameOutlines[0]?.outline ??\n    \"\";\n  const combinedTree = injectSubtrees(rootOutline, idToTree);\n\n  return {\n    combinedTree,\n    combinedXpathMap,\n    combinedUrlMap,\n    perFrame: perFrameOutlines.map(({ frameId, outline }) => {\n      const maps = perFrameMaps.get(frameId);\n      return {\n        frameId,\n        outline,\n        xpathMap: maps?.xpathMap ?? {},\n        urlMap: maps?.urlMap ?? {},\n      };\n    }),\n  };\n}\n"]}