@browserbasehq/orca 3.1.0-patch.0 → 3.1.0-patch.1

package/dist/cjs/tests/snapshot-cbor.test.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../tests/snapshot-cbor.test.ts"],
+  "sourcesContent": ["import { describe, expect, it } from \"vitest\";\nimport type { Protocol } from \"devtools-protocol\";\n\nimport { captureHybridSnapshot } from \"../lib/v3/understudy/a11y/snapshot/index.js\";\nimport { MockCDPSession } from \"./helpers/mockCDPSession.js\";\nimport type { Page } from \"../lib/v3/understudy/page.js\";\nimport { StagehandDomProcessError } from \"../lib/v3/types/public/sdkErrors.js\";\nimport { CDPSessionLike } from \"../lib/v3/understudy/cdp.js\";\n\ntype Handler = (params?: Record<string, unknown>) => Promise<unknown> | unknown;\n\nfunction createFakePage(session: CDPSessionLike): Page {\n  const frameTree: Protocol.Page.FrameTree = {\n    frame: {\n      id: \"root\" as Protocol.Page.FrameId,\n      loaderId: \"root-loader\" as Protocol.Network.LoaderId,\n      url: \"http://fake\",\n      domainAndRegistry: \"fake\",\n      securityOrigin: \"http://fake\",\n      mimeType: \"text/html\",\n      secureContextType: \"Secure\",\n      crossOriginIsolatedContextType: \"NotIsolated\",\n      gatedAPIFeatures: [],\n    },\n    childFrames: [],\n  };\n\n  return {\n    mainFrameId: () => \"root\",\n    asProtocolFrameTree: () => frameTree,\n    listAllFrameIds: () => [\"root\"],\n    getSessionForFrame: () => session,\n    getOrdinal: () => 0,\n  } as unknown as Page;\n}\n\nfunction completeDomTree(): Protocol.DOM.Node {\n  return {\n    nodeId: 1,\n    backendNodeId: 1,\n    nodeType: 9,\n    nodeName: \"#document\",\n    childNodeCount: 1,\n    children: [\n      {\n        nodeId: 2,\n        backendNodeId: 2,\n        nodeType: 1,\n        nodeName: \"HTML\",\n        childNodeCount: 1,\n        children: [\n          {\n            nodeId: 3,\n            backendNodeId: 3,\n            nodeType: 1,\n            nodeName: \"BODY\",\n            childNodeCount: 1,\n            children: [\n              {\n                nodeId: 4,\n                backendNodeId: 4,\n                nodeType: 1,\n                nodeName: \"DIV\",\n                childNodeCount: 0,\n                children: [],\n              },\n            ],\n          },\n        ],\n      },\n    ],\n  } as Protocol.DOM.Node;\n}\n\nfunction truncatedDomTree(): Protocol.DOM.Node {\n  return {\n    nodeId: 1,\n    backendNodeId: 1,\n    nodeType: 9,\n    nodeName: \"#document\",\n    childNodeCount: 1,\n    children: [\n      {\n        nodeId: 2,\n        backendNodeId: 2,\n        nodeType: 1,\n        nodeName: \"HTML\",\n        childNodeCount: 1,\n        children: [],\n      },\n    ],\n  } as Protocol.DOM.Node;\n}\n\nfunction htmlWithChildren(): Protocol.DOM.Node {\n  return {\n    nodeId: 2,\n    backendNodeId: 2,\n    nodeType: 1,\n    nodeName: \"HTML\",\n    childNodeCount: 1,\n    children: [\n      {\n        nodeId: 3,\n        backendNodeId: 3,\n        nodeType: 1,\n        nodeName: \"BODY\",\n        childNodeCount: 1,\n        children: [\n          {\n            nodeId: 4,\n            backendNodeId: 4,\n            nodeType: 1,\n            nodeName: \"DIV\",\n            childNodeCount: 0,\n            children: [],\n          },\n        ],\n      },\n    ],\n  } as Protocol.DOM.Node;\n}\n\nfunction simpleAxNodes(): Protocol.Accessibility.AXNode[] {\n  const stringType: Protocol.Accessibility.AXValueType = \"string\";\n  return [\n    {\n      nodeId: \"1\",\n      role: { type: stringType, value: \"RootWebArea\" },\n      backendDOMNodeId: 2,\n      childIds: [\"2\"],\n      ignored: false,\n    },\n    {\n      nodeId: \"2\",\n      role: { type: stringType, value: \"generic\" },\n      name: { type: stringType, value: \"Content\" },\n      backendDOMNodeId: 4,\n      parentId: \"1\",\n      childIds: [] as string[],\n      ignored: false,\n    },\n  ];\n}\n\nconst baseHandlers: Record<string, Handler> = {\n  \"DOM.enable\": async () => ({}),\n  \"Runtime.enable\": async () => ({}),\n  \"Accessibility.enable\": async () => ({}),\n  \"Accessibility.getFullAXTree\": async () => ({ nodes: simpleAxNodes() }),\n};\n\nfunction makeCborError(): Error {\n  return new Error(\"CBOR: stack limit exceeded\");\n}\n\ndescribe(\"captureHybridSnapshot CBOR fallbacks\", () => {\n  it(\"retries DOM.getDocument with reduced depths before succeeding\", async () => {\n    let domCalls = 0;\n    const session = new MockCDPSession({\n      ...baseHandlers,\n      \"DOM.getDocument\": async (params) => {\n        domCalls += 1;\n        if (domCalls === 1) throw makeCborError();\n        expect(params?.depth).toBe(256);\n        return { root: completeDomTree() };\n      },\n    });\n\n    const page = createFakePage(session);\n    const snapshot = await captureHybridSnapshot(page);\n\n    expect(snapshot.combinedTree).toContain(\"html\");\n    const depths = session\n      .callsFor(\"DOM.getDocument\")\n      .map((c) => c.params?.depth);\n    expect(depths).toEqual([-1, 256]);\n  });\n\n  it(\"throws StagehandDomProcessError after all DOM.getDocument attempts fail\", async () => {\n    const session = new MockCDPSession({\n      ...baseHandlers,\n      \"DOM.getDocument\": async () => {\n        throw makeCborError();\n      },\n    });\n\n    const page = createFakePage(session);\n    await expect(captureHybridSnapshot(page)).rejects.toThrow(\n      StagehandDomProcessError,\n    );\n  });\n\n  it(\"hydrates truncated nodes by retrying DOM.describeNode depths\", async () => {\n    let domAttempts = 0;\n    let describeAttempts = 0;\n\n    const session = new MockCDPSession({\n      ...baseHandlers,\n      \"DOM.getDocument\": async (params) => {\n        domAttempts += 1;\n        if (domAttempts === 1) throw makeCborError();\n        expect(params?.depth).toBe(256);\n        return { root: truncatedDomTree() };\n      },\n      \"DOM.describeNode\": async (params) => {\n        describeAttempts += 1;\n        if (describeAttempts === 1) throw makeCborError();\n        expect(params?.depth).toBe(64);\n        return { node: htmlWithChildren() };\n      },\n    });\n\n    const page = createFakePage(session);\n    const snapshot = await captureHybridSnapshot(page);\n\n    const describeDepths = session\n      .callsFor(\"DOM.describeNode\")\n      .map((c) => c.params?.depth);\n    expect(describeDepths).toEqual([-1, 64]);\n    expect(snapshot.combinedXpathMap[\"0-4\"]).toBe(\"/html[1]/body[1]/div[1]\");\n  });\n});\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/cjs/tests/snapshot-dom-session-builders.test.js

@@ -0,0 +1,246 @@
+var import_vitest = require("vitest");
+var import_domTree = require("../lib/v3/understudy/a11y/snapshot/domTree.js");
+var import_sdkErrors = require("../lib/v3/types/public/sdkErrors.js");
+var import_mockCDPSession = require("./helpers/mockCDPSession.js");
+let nextNodeId = 1;
+const makeDomNode = (overrides = {}) => {
+  const nodeId = overrides.nodeId ?? nextNodeId++;
+  const backendNodeId = overrides.backendNodeId ?? nextNodeId++;
+  const nodeName = overrides.nodeName ?? "DIV";
+  const nodeType = overrides.nodeType ?? 1;
+  const children = overrides.children ?? [];
+  return {
+    nodeId,
+    backendNodeId,
+    nodeName,
+    nodeType,
+    localName: overrides.localName ?? nodeName.toLowerCase(),
+    nodeValue: overrides.nodeValue ?? "",
+    childNodeCount: overrides.childNodeCount ?? children.length,
+    children,
+    shadowRoots: overrides.shadowRoots,
+    contentDocument: overrides.contentDocument,
+    isScrollable: overrides.isScrollable
+  };
+};
+const buildSampleDomTree = () => {
+  const iframeChild = makeDomNode({ nodeName: "P" });
+  const iframeBody = makeDomNode({
+    nodeName: "BODY",
+    children: [iframeChild],
+    isScrollable: true
+  });
+  const iframeHtml = makeDomNode({ nodeName: "HTML", children: [iframeBody] });
+  const iframeDoc = makeDomNode({
+    nodeName: "#document",
+    nodeType: 9,
+    children: [iframeHtml]
+  });
+  const iframeElement = makeDomNode({
+    nodeName: "IFRAME",
+    contentDocument: iframeDoc
+  });
+  const scrollDiv = makeDomNode({
+    nodeName: "DIV",
+    isScrollable: true
+  });
+  const body = makeDomNode({
+    nodeName: "BODY",
+    children: [scrollDiv, iframeElement]
+  });
+  const html = makeDomNode({ nodeName: "HTML", children: [body] });
+  const root = makeDomNode({
+    nodeName: "#document",
+    nodeType: 9,
+    children: [html]
+  });
+  return {
+    root,
+    html,
+    body,
+    scrollDiv,
+    iframeElement,
+    iframeDoc,
+    iframeHtml,
+    iframeBody,
+    iframeChild
+  };
+};
+(0, import_vitest.describe)("hydrateDomTree", () => {
+  (0, import_vitest.it)("expands truncated nodes by calling DOM.describeNode", async () => {
+    const child = makeDomNode({ nodeName: "DIV" });
+    const root = makeDomNode({
+      nodeName: "HTML",
+      childNodeCount: 1,
+      children: []
+    });
+    const session = new import_mockCDPSession.MockCDPSession({
+      "DOM.describeNode": async () => ({
+        node: {
+          ...root,
+          children: [child],
+          childNodeCount: 1
+        }
+      })
+    });
+    await (0, import_domTree.hydrateDomTree)(session, root, true);
+    (0, import_vitest.expect)(root.children).toEqual([child]);
+  });
+  (0, import_vitest.it)("retries describeNode when CBOR errors occur before succeeding", async () => {
+    const child = makeDomNode({ nodeName: "DIV" });
+    const root = makeDomNode({
+      nodeName: "HTML",
+      childNodeCount: 1,
+      children: []
+    });
+    let attempts = 0;
+    const session = new import_mockCDPSession.MockCDPSession({
+      "DOM.describeNode": async () => {
+        attempts++;
+        if (attempts === 1) throw new Error("CBOR: stack limit exceeded");
+        return { node: { ...root, children: [child], childNodeCount: 1 } };
+      }
+    });
+    await (0, import_domTree.hydrateDomTree)(session, root, true);
+    (0, import_vitest.expect)(attempts).toBe(2);
+    (0, import_vitest.expect)(root.children).toEqual([child]);
+  });
+  (0, import_vitest.it)("throws StagehandDomProcessError after exhausting describeNode retries", async () => {
+    const root = makeDomNode({
+      nodeName: "HTML",
+      childNodeCount: 1,
+      children: []
+    });
+    const session = new import_mockCDPSession.MockCDPSession({
+      "DOM.describeNode": async () => {
+        throw new Error("CBOR: stack limit exceeded");
+      }
+    });
+    await (0, import_vitest.expect)((0, import_domTree.hydrateDomTree)(session, root, true)).rejects.toBeInstanceOf(
+      import_sdkErrors.StagehandDomProcessError
+    );
+  });
+});
+(0, import_vitest.describe)("getDomTreeWithFallback", () => {
+  (0, import_vitest.it)("retries DOM.getDocument after CBOR errors and returns the hydrated root", async () => {
+    const root = makeDomNode({
+      nodeName: "#document",
+      nodeType: 9,
+      children: []
+    });
+    const depths = [];
+    const session = new import_mockCDPSession.MockCDPSession({
+      "DOM.getDocument": async (params) => {
+        const depth = params?.depth ?? 0;
+        depths.push(depth);
+        if (depth === -1) throw new Error("CBOR: stack limit exceeded");
+        return { root };
+      },
+      "DOM.describeNode": async () => ({ node: root })
+    });
+    const result = await (0, import_domTree.getDomTreeWithFallback)(session, true);
+    (0, import_vitest.expect)(result).toBe(root);
+    (0, import_vitest.expect)(depths).toEqual([-1, 256]);
+  });
+  (0, import_vitest.it)("propagates non-CBOR DOM.getDocument errors", async () => {
+    const session = new import_mockCDPSession.MockCDPSession({
+      "DOM.getDocument": async () => {
+        throw new Error("network fail");
+      }
+    });
+    await (0, import_vitest.expect)((0, import_domTree.getDomTreeWithFallback)(session, false)).rejects.toThrow(
+      "network fail"
+    );
+  });
+  (0, import_vitest.it)("throws StagehandDomProcessError when all depth attempts hit CBOR limits", async () => {
+    const session = new import_mockCDPSession.MockCDPSession({
+      "DOM.getDocument": async () => {
+        throw new Error("CBOR: stack limit exceeded");
+      }
+    });
+    await (0, import_vitest.expect)((0, import_domTree.getDomTreeWithFallback)(session, false)).rejects.toBeInstanceOf(
+      import_sdkErrors.StagehandDomProcessError
+    );
+  });
+});
+(0, import_vitest.describe)("buildSessionDomIndex", () => {
+  (0, import_vitest.it)("collects absolute paths, scrollability, and content-document metadata", async () => {
+    const tree = buildSampleDomTree();
+    const session = new import_mockCDPSession.MockCDPSession({
+      "DOM.enable": async () => ({}),
+      "DOM.getDocument": async () => ({ root: tree.root }),
+      "DOM.describeNode": async () => ({ node: tree.root })
+    });
+    const index = await (0, import_domTree.buildSessionDomIndex)(session, true);
+    (0, import_vitest.expect)(index.rootBackend).toBe(tree.root.backendNodeId);
+    (0, import_vitest.expect)(index.absByBe.get(tree.body.backendNodeId)).toBe("/html[1]/body[1]");
+    (0, import_vitest.expect)(index.absByBe.get(tree.scrollDiv.backendNodeId)).toBe(
+      "/html[1]/body[1]/div[1]"
+    );
+    (0, import_vitest.expect)(index.scrollByBe.get(tree.scrollDiv.backendNodeId)).toBe(true);
+    (0, import_vitest.expect)(index.docRootOf.get(tree.iframeHtml.backendNodeId)).toBe(
+      tree.iframeDoc.backendNodeId
+    );
+    (0, import_vitest.expect)(
+      index.contentDocRootByIframe.get(tree.iframeElement.backendNodeId)
+    ).toBe(tree.iframeDoc.backendNodeId);
+  });
+});
+(0, import_vitest.describe)("domMapsForSession", () => {
+  (0, import_vitest.it)("derives frame-relative xpath/tag/scrollable maps for a frame's document root", async () => {
+    const tree = buildSampleDomTree();
+    const session = new import_mockCDPSession.MockCDPSession({
+      "DOM.enable": async () => ({}),
+      "DOM.getDocument": async () => ({ root: tree.root }),
+      "DOM.getFrameOwner": async () => ({
+        backendNodeId: tree.iframeElement.backendNodeId
+      }),
+      "DOM.describeNode": async () => ({ node: tree.root })
+    });
+    const encode = (frameId, backendNodeId) => `${frameId}-${backendNodeId}`;
+    const maps = await (0, import_domTree.domMapsForSession)(
+      session,
+      "frame-A",
+      true,
+      encode,
+      true
+    );
+    const iframeDocKey = `frame-A-${tree.iframeDoc.backendNodeId}`;
+    const iframeBodyKey = `frame-A-${tree.iframeBody.backendNodeId}`;
+    const iframeChildKey = `frame-A-${tree.iframeChild.backendNodeId}`;
+    (0, import_vitest.expect)(maps.tagNameMap[iframeDocKey]).toBe("#document");
+    (0, import_vitest.expect)(maps.xpathMap[iframeDocKey]).toBe("/");
+    (0, import_vitest.expect)(maps.xpathMap[iframeBodyKey]).toBe("/html[1]/body[1]");
+    (0, import_vitest.expect)(maps.xpathMap[iframeChildKey]).toBe("/html[1]/body[1]/p[1]");
+    (0, import_vitest.expect)(maps.scrollableMap[iframeBodyKey]).toBe(true);
+    (0, import_vitest.expect)(Object.keys(maps.tagNameMap)).not.toContain(
+      `frame-A-${tree.html.backendNodeId}`
+    );
+  });
+  (0, import_vitest.it)("falls back to the root document when frame owner lookup fails", async () => {
+    const tree = buildSampleDomTree();
+    const session = new import_mockCDPSession.MockCDPSession({
+      "DOM.enable": async () => ({}),
+      "DOM.getDocument": async () => ({ root: tree.root }),
+      "DOM.getFrameOwner": async () => {
+        throw new Error("owner lookup failed");
+      },
+      "DOM.describeNode": async () => ({ node: tree.root })
+    });
+    const encode = (frameId, backendNodeId) => `${frameId}-${backendNodeId}`;
+    const maps = await (0, import_domTree.domMapsForSession)(
+      session,
+      "frame-B",
+      false,
+      encode,
+      true
+    );
+    (0, import_vitest.expect)(maps.xpathMap[`frame-B-${tree.html.backendNodeId}`]).toBe(
+      "/html[1]"
+    );
+    (0, import_vitest.expect)(maps.xpathMap[`frame-B-${tree.scrollDiv.backendNodeId}`]).toBe(
+      "/html[1]/body[1]/div[1]"
+    );
+  });
+});
+//# sourceMappingURL=snapshot-dom-session-builders.test.js.map

package/dist/cjs/tests/snapshot-dom-session-builders.test.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../tests/snapshot-dom-session-builders.test.ts"],
+  "sourcesContent": ["import type { Protocol } from \"devtools-protocol\";\nimport { describe, expect, it } from \"vitest\";\nimport {\n  buildSessionDomIndex,\n  domMapsForSession,\n  getDomTreeWithFallback,\n  hydrateDomTree,\n} from \"../lib/v3/understudy/a11y/snapshot/domTree.js\";\nimport { StagehandDomProcessError } from \"../lib/v3/types/public/sdkErrors.js\";\nimport { MockCDPSession } from \"./helpers/mockCDPSession.js\";\n\nlet nextNodeId = 1;\nconst makeDomNode = (\n  overrides: Partial<Protocol.DOM.Node> = {},\n): Protocol.DOM.Node => {\n  const nodeId = overrides.nodeId ?? nextNodeId++;\n  const backendNodeId = overrides.backendNodeId ?? nextNodeId++;\n  const nodeName = overrides.nodeName ?? \"DIV\";\n  const nodeType = overrides.nodeType ?? 1;\n  const children = overrides.children ?? [];\n  return {\n    nodeId,\n    backendNodeId,\n    nodeName,\n    nodeType,\n    localName: overrides.localName ?? nodeName.toLowerCase(),\n    nodeValue: overrides.nodeValue ?? \"\",\n    childNodeCount: overrides.childNodeCount ?? children.length,\n    children,\n    shadowRoots: overrides.shadowRoots,\n    contentDocument: overrides.contentDocument,\n    isScrollable: overrides.isScrollable,\n  };\n};\n\nconst buildSampleDomTree = () => {\n  const iframeChild = makeDomNode({ nodeName: \"P\" });\n  const iframeBody = makeDomNode({\n    nodeName: \"BODY\",\n    children: [iframeChild],\n    isScrollable: true,\n  });\n  const iframeHtml = makeDomNode({ nodeName: \"HTML\", children: [iframeBody] });\n  const iframeDoc = makeDomNode({\n    nodeName: \"#document\",\n    nodeType: 9,\n    children: [iframeHtml],\n  });\n  const iframeElement = makeDomNode({\n    nodeName: \"IFRAME\",\n    contentDocument: iframeDoc,\n  });\n  const scrollDiv = makeDomNode({\n    nodeName: \"DIV\",\n    isScrollable: true,\n  });\n  const body = makeDomNode({\n    nodeName: \"BODY\",\n    children: [scrollDiv, iframeElement],\n  });\n  const html = makeDomNode({ nodeName: \"HTML\", children: [body] });\n  const root = makeDomNode({\n    nodeName: \"#document\",\n    nodeType: 9,\n    children: [html],\n  });\n  return {\n    root,\n    html,\n    body,\n    scrollDiv,\n    iframeElement,\n    iframeDoc,\n    iframeHtml,\n    iframeBody,\n    iframeChild,\n  };\n};\n\ndescribe(\"hydrateDomTree\", () => {\n  it(\"expands truncated nodes by calling DOM.describeNode\", async () => {\n    const child = makeDomNode({ nodeName: \"DIV\" });\n    const root = makeDomNode({\n      nodeName: \"HTML\",\n      childNodeCount: 1,\n      children: [],\n    });\n\n    const session = new MockCDPSession({\n      \"DOM.describeNode\": async () => ({\n        node: {\n          ...root,\n          children: [child],\n          childNodeCount: 1,\n        },\n      }),\n    });\n\n    await hydrateDomTree(session, root, true);\n    expect(root.children).toEqual([child]);\n  });\n\n  it(\"retries describeNode when CBOR errors occur before succeeding\", async () => {\n    const child = makeDomNode({ nodeName: \"DIV\" });\n    const root = makeDomNode({\n      nodeName: \"HTML\",\n      childNodeCount: 1,\n      children: [],\n    });\n\n    let attempts = 0;\n    const session = new MockCDPSession({\n      \"DOM.describeNode\": async () => {\n        attempts++;\n        if (attempts === 1) throw new Error(\"CBOR: stack limit exceeded\");\n        return { node: { ...root, children: [child], childNodeCount: 1 } };\n      },\n    });\n\n    await hydrateDomTree(session, root, true);\n    expect(attempts).toBe(2);\n    expect(root.children).toEqual([child]);\n  });\n\n  it(\"throws StagehandDomProcessError after exhausting describeNode retries\", async () => {\n    const root = makeDomNode({\n      nodeName: \"HTML\",\n      childNodeCount: 1,\n      children: [],\n    });\n    const session = new MockCDPSession({\n      \"DOM.describeNode\": async () => {\n        throw new Error(\"CBOR: stack limit exceeded\");\n      },\n    });\n\n    await expect(hydrateDomTree(session, root, true)).rejects.toBeInstanceOf(\n      StagehandDomProcessError,\n    );\n  });\n});\n\ndescribe(\"getDomTreeWithFallback\", () => {\n  it(\"retries DOM.getDocument after CBOR errors and returns the hydrated root\", async () => {\n    const root = makeDomNode({\n      nodeName: \"#document\",\n      nodeType: 9,\n      children: [],\n    });\n    const depths: number[] = [];\n    const session = new MockCDPSession({\n      \"DOM.getDocument\": async (params) => {\n        const depth = (params?.depth ?? 0) as number;\n        depths.push(depth);\n        if (depth === -1) throw new Error(\"CBOR: stack limit exceeded\");\n        return { root };\n      },\n      \"DOM.describeNode\": async () => ({ node: root }),\n    });\n\n    const result = await getDomTreeWithFallback(session, true);\n    expect(result).toBe(root);\n    expect(depths).toEqual([-1, 256]);\n  });\n\n  it(\"propagates non-CBOR DOM.getDocument errors\", async () => {\n    const session = new MockCDPSession({\n      \"DOM.getDocument\": async () => {\n        throw new Error(\"network fail\");\n      },\n    });\n    await expect(getDomTreeWithFallback(session, false)).rejects.toThrow(\n      \"network fail\",\n    );\n  });\n\n  it(\"throws StagehandDomProcessError when all depth attempts hit CBOR limits\", async () => {\n    const session = new MockCDPSession({\n      \"DOM.getDocument\": async () => {\n        throw new Error(\"CBOR: stack limit exceeded\");\n      },\n    });\n    await expect(getDomTreeWithFallback(session, false)).rejects.toBeInstanceOf(\n      StagehandDomProcessError,\n    );\n  });\n});\n\ndescribe(\"buildSessionDomIndex\", () => {\n  it(\"collects absolute paths, scrollability, and content-document metadata\", async () => {\n    const tree = buildSampleDomTree();\n    const session = new MockCDPSession({\n      \"DOM.enable\": async () => ({}),\n      \"DOM.getDocument\": async () => ({ root: tree.root }),\n      \"DOM.describeNode\": async () => ({ node: tree.root }),\n    });\n\n    const index = await buildSessionDomIndex(session, true);\n\n    expect(index.rootBackend).toBe(tree.root.backendNodeId);\n    expect(index.absByBe.get(tree.body.backendNodeId)).toBe(\"/html[1]/body[1]\");\n    expect(index.absByBe.get(tree.scrollDiv.backendNodeId)).toBe(\n      \"/html[1]/body[1]/div[1]\",\n    );\n    expect(index.scrollByBe.get(tree.scrollDiv.backendNodeId)).toBe(true);\n    expect(index.docRootOf.get(tree.iframeHtml.backendNodeId)).toBe(\n      tree.iframeDoc.backendNodeId,\n    );\n    expect(\n      index.contentDocRootByIframe.get(tree.iframeElement.backendNodeId),\n    ).toBe(tree.iframeDoc.backendNodeId);\n  });\n});\n\ndescribe(\"domMapsForSession\", () => {\n  it(\"derives frame-relative xpath/tag/scrollable maps for a frame's document root\", async () => {\n    const tree = buildSampleDomTree();\n    const session = new MockCDPSession({\n      \"DOM.enable\": async () => ({}),\n      \"DOM.getDocument\": async () => ({ root: tree.root }),\n      \"DOM.getFrameOwner\": async () => ({\n        backendNodeId: tree.iframeElement.backendNodeId,\n      }),\n      \"DOM.describeNode\": async () => ({ node: tree.root }),\n    });\n\n    const encode = (frameId: string, backendNodeId: number) =>\n      `${frameId}-${backendNodeId}`;\n    const maps = await domMapsForSession(\n      session,\n      \"frame-A\",\n      true,\n      encode,\n      true,\n    );\n\n    const iframeDocKey = `frame-A-${tree.iframeDoc.backendNodeId}`;\n    const iframeBodyKey = `frame-A-${tree.iframeBody.backendNodeId}`;\n    const iframeChildKey = `frame-A-${tree.iframeChild.backendNodeId}`;\n\n    expect(maps.tagNameMap[iframeDocKey]).toBe(\"#document\");\n    expect(maps.xpathMap[iframeDocKey]).toBe(\"/\");\n    expect(maps.xpathMap[iframeBodyKey]).toBe(\"/html[1]/body[1]\");\n    expect(maps.xpathMap[iframeChildKey]).toBe(\"/html[1]/body[1]/p[1]\");\n    expect(maps.scrollableMap[iframeBodyKey]).toBe(true);\n    expect(Object.keys(maps.tagNameMap)).not.toContain(\n      `frame-A-${tree.html.backendNodeId}`,\n    );\n  });\n\n  it(\"falls back to the root document when frame owner lookup fails\", async () => {\n    const tree = buildSampleDomTree();\n    const session = new MockCDPSession({\n      \"DOM.enable\": async () => ({}),\n      \"DOM.getDocument\": async () => ({ root: tree.root }),\n      \"DOM.getFrameOwner\": async () => {\n        throw new Error(\"owner lookup failed\");\n      },\n      \"DOM.describeNode\": async () => ({ node: tree.root }),\n    });\n\n    const encode = (frameId: string, backendNodeId: number) =>\n      `${frameId}-${backendNodeId}`;\n    const maps = await domMapsForSession(\n      session,\n      \"frame-B\",\n      false,\n      encode,\n      true,\n    );\n\n    expect(maps.xpathMap[`frame-B-${tree.html.backendNodeId}`]).toBe(\n      \"/html[1]\",\n    );\n    expect(maps.xpathMap[`frame-B-${tree.scrollDiv.backendNodeId}`]).toBe(\n      \"/html[1]/body[1]/div[1]\",\n    );\n  });\n});\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/cjs/tests/snapshot-dom-tree-utils.test.js

@@ -0,0 +1,104 @@
+var import_vitest = require("vitest");
+var import_domTree = require("../lib/v3/understudy/a11y/snapshot/domTree.js");
+let nextNodeId = 1;
+const makeNode = (overrides = {}) => {
+  const base = {
+    nodeId: nextNodeId++,
+    backendNodeId: nextNodeId++,
+    nodeType: 1,
+    nodeName: "DIV",
+    localName: "div",
+    nodeValue: "",
+    childNodeCount: overrides.childNodeCount ?? (overrides.children ? overrides.children.length : 0)
+  };
+  return { ...base, ...overrides };
+};
+(0, import_vitest.describe)("shouldExpandNode", () => {
+  (0, import_vitest.it)("returns true when declared children exceed realized children", () => {
+    const node = makeNode({
+      childNodeCount: 2,
+      children: [makeNode()]
+    });
+    (0, import_vitest.expect)((0, import_domTree.shouldExpandNode)(node)).toBe(true);
+  });
+  (0, import_vitest.it)("returns false when all declared children are realized", () => {
+    const child = makeNode();
+    const node = makeNode({
+      childNodeCount: 1,
+      children: [child]
+    });
+    (0, import_vitest.expect)((0, import_domTree.shouldExpandNode)(node)).toBe(false);
+  });
+});
+(0, import_vitest.describe)("mergeDomNodes", () => {
+  (0, import_vitest.it)("overrides structural fields with expanded node data", () => {
+    const originalChildren = [makeNode({ nodeName: "SPAN" })];
+    const target = makeNode({
+      childNodeCount: 1,
+      children: originalChildren,
+      shadowRoots: [makeNode({ nodeName: "shadow-old" })],
+      contentDocument: makeNode({ nodeName: "doc-old" })
+    });
+    const source = makeNode({
+      childNodeCount: 3,
+      children: [makeNode({ nodeName: "DIV" })],
+      shadowRoots: [],
+      contentDocument: makeNode({ nodeName: "doc-new" })
+    });
+    (0, import_domTree.mergeDomNodes)(target, source);
+    (0, import_vitest.expect)(target.childNodeCount).toBe(3);
+    (0, import_vitest.expect)(target.children).toEqual(source.children);
+    (0, import_vitest.expect)(target.shadowRoots).toEqual([]);
+    (0, import_vitest.expect)(target.contentDocument?.nodeName).toBe("doc-new");
+  });
+  (0, import_vitest.it)("preserves original structures when source omits them", () => {
+    const child = makeNode();
+    const target = makeNode({
+      childNodeCount: 1,
+      children: [child]
+    });
+    const source = makeNode({
+      childNodeCount: 5
+    });
+    (0, import_domTree.mergeDomNodes)(target, source);
+    (0, import_vitest.expect)(target.childNodeCount).toBe(5);
+    (0, import_vitest.expect)(target.children).toEqual([child]);
+  });
+});
+(0, import_vitest.describe)("collectDomTraversalTargets", () => {
+  (0, import_vitest.it)("returns children, shadow roots, and content document in order", () => {
+    const childA = makeNode({ nodeName: "CHILD-A" });
+    const childB = makeNode({ nodeName: "CHILD-B" });
+    const shadow = makeNode({ nodeName: "SHADOW" });
+    const content = makeNode({ nodeName: "CONTENT" });
+    const node = makeNode({
+      children: [childA, childB],
+      shadowRoots: [shadow],
+      contentDocument: content
+    });
+    const targets = (0, import_domTree.collectDomTraversalTargets)(node);
+    (0, import_vitest.expect)(targets).toEqual([childA, childB, shadow, content]);
+  });
+});
+(0, import_vitest.describe)("findNodeByBackendId", () => {
+  (0, import_vitest.it)("finds nodes nested within children and shadow roots", () => {
+    const target = makeNode({ backendNodeId: 999, nodeName: "TARGET" });
+    const root = makeNode({
+      children: [
+        makeNode({
+          children: [makeNode(), target]
+        })
+      ],
+      shadowRoots: [makeNode()]
+    });
+    (0, import_vitest.expect)((0, import_domTree.findNodeByBackendId)(root, 999)).toBe(target);
+  });
+  (0, import_vitest.it)("returns undefined when no node matches the backend id", () => {
+    const root = makeNode({
+      children: [makeNode()],
+      shadowRoots: [makeNode()]
+    });
+    (0, import_vitest.expect)((0, import_domTree.findNodeByBackendId)(root, 123456)).toBeUndefined();
+  });
+});
+//# sourceMappingURL=snapshot-dom-tree-utils.test.js.map

package/dist/cjs/tests/snapshot-dom-tree-utils.test.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../tests/snapshot-dom-tree-utils.test.ts"],
+  "sourcesContent": ["import type { Protocol } from \"devtools-protocol\";\nimport { describe, expect, it } from \"vitest\";\nimport {\n  collectDomTraversalTargets,\n  findNodeByBackendId,\n  mergeDomNodes,\n  shouldExpandNode,\n} from \"../lib/v3/understudy/a11y/snapshot/domTree.js\";\n\nlet nextNodeId = 1;\nconst makeNode = (\n  overrides: Partial<Protocol.DOM.Node> = {},\n): Protocol.DOM.Node => {\n  const base: Protocol.DOM.Node = {\n    nodeId: nextNodeId++,\n    backendNodeId: nextNodeId++,\n    nodeType: 1,\n    nodeName: \"DIV\",\n    localName: \"div\",\n    nodeValue: \"\",\n    childNodeCount:\n      overrides.childNodeCount ??\n      (overrides.children ? overrides.children.length : 0),\n  };\n  return { ...base, ...overrides };\n};\n\ndescribe(\"shouldExpandNode\", () => {\n  it(\"returns true when declared children exceed realized children\", () => {\n    const node = makeNode({\n      childNodeCount: 2,\n      children: [makeNode()],\n    });\n    expect(shouldExpandNode(node)).toBe(true);\n  });\n\n  it(\"returns false when all declared children are realized\", () => {\n    const child = makeNode();\n    const node = makeNode({\n      childNodeCount: 1,\n      children: [child],\n    });\n    expect(shouldExpandNode(node)).toBe(false);\n  });\n});\n\ndescribe(\"mergeDomNodes\", () => {\n  it(\"overrides structural fields with expanded node data\", () => {\n    const originalChildren = [makeNode({ nodeName: \"SPAN\" })];\n    const target = makeNode({\n      childNodeCount: 1,\n      children: originalChildren,\n      shadowRoots: [makeNode({ nodeName: \"shadow-old\" })],\n      contentDocument: makeNode({ nodeName: \"doc-old\" }),\n    });\n    const source = makeNode({\n      childNodeCount: 3,\n      children: [makeNode({ nodeName: \"DIV\" })],\n      shadowRoots: [],\n      contentDocument: makeNode({ nodeName: \"doc-new\" }),\n    });\n\n    mergeDomNodes(target, source);\n\n    expect(target.childNodeCount).toBe(3);\n    expect(target.children).toEqual(source.children);\n    expect(target.shadowRoots).toEqual([]);\n    expect(target.contentDocument?.nodeName).toBe(\"doc-new\");\n  });\n\n  it(\"preserves original structures when source omits them\", () => {\n    const child = makeNode();\n    const target = makeNode({\n      childNodeCount: 1,\n      children: [child],\n    });\n    const source = makeNode({\n      childNodeCount: 5,\n    });\n\n    mergeDomNodes(target, source);\n\n    expect(target.childNodeCount).toBe(5);\n    expect(target.children).toEqual([child]);\n  });\n});\n\ndescribe(\"collectDomTraversalTargets\", () => {\n  it(\"returns children, shadow roots, and content document in order\", () => {\n    const childA = makeNode({ nodeName: \"CHILD-A\" });\n    const childB = makeNode({ nodeName: \"CHILD-B\" });\n    const shadow = makeNode({ nodeName: \"SHADOW\" });\n    const content = makeNode({ nodeName: \"CONTENT\" });\n\n    const node = makeNode({\n      children: [childA, childB],\n      shadowRoots: [shadow],\n      contentDocument: content,\n    });\n\n    const targets = collectDomTraversalTargets(node);\n    expect(targets).toEqual([childA, childB, shadow, content]);\n  });\n});\n\ndescribe(\"findNodeByBackendId\", () => {\n  it(\"finds nodes nested within children and shadow roots\", () => {\n    const target = makeNode({ backendNodeId: 999, nodeName: \"TARGET\" });\n    const root = makeNode({\n      children: [\n        makeNode({\n          children: [makeNode(), target],\n        }),\n      ],\n      shadowRoots: [makeNode()],\n    });\n\n    expect(findNodeByBackendId(root, 999)).toBe(target);\n  });\n\n  it(\"returns undefined when no node matches the backend id\", () => {\n    const root = makeNode({\n      children: [makeNode()],\n      shadowRoots: [makeNode()],\n    });\n    expect(findNodeByBackendId(root, 123456)).toBeUndefined();\n  });\n});\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/cjs/tests/snapshot-focus-selectors-utils.test.js

@@ -0,0 +1,45 @@
+var import_vitest = require("vitest");
+var import_focusSelectors = require("../lib/v3/understudy/a11y/snapshot/focusSelectors.js");
+(0, import_vitest.describe)("parseXPathToSteps", () => {
+  (0, import_vitest.it)("records axis direction and normalized names", () => {
+    const steps = (0, import_focusSelectors.parseXPathToSteps)(" //iframe[1]/div[2]//SPAN ");
+    (0, import_vitest.expect)(steps).toEqual([
+      { axis: "desc", raw: "iframe[1]", name: "iframe" },
+      { axis: "child", raw: "div[2]", name: "div" },
+      { axis: "desc", raw: "SPAN", name: "span" }
+    ]);
+  });
+  (0, import_vitest.it)("drops empty segments and returns [] for blank input", () => {
+    (0, import_vitest.expect)((0, import_focusSelectors.parseXPathToSteps)("   ")).toEqual([]);
+    (0, import_vitest.expect)((0, import_focusSelectors.parseXPathToSteps)("/ ")).toEqual([]);
+  });
+});
+(0, import_vitest.describe)("buildXPathFromSteps", () => {
+  (0, import_vitest.it)("reconstructs descendant and child hops as a string", () => {
+    const steps = [
+      { axis: "child", raw: "iframe[1]", name: "iframe" },
+      { axis: "desc", raw: "div[@id='main']", name: "div" },
+      { axis: "child", raw: "span", name: "span" }
+    ];
+    (0, import_vitest.expect)((0, import_focusSelectors.buildXPathFromSteps)(steps)).toBe("/iframe[1]//div[@id='main']/span");
+  });
+  (0, import_vitest.it)("returns '/' for empty sequences", () => {
+    (0, import_vitest.expect)((0, import_focusSelectors.buildXPathFromSteps)([])).toBe("/");
+  });
+});
+(0, import_vitest.describe)("listChildrenOf", () => {
+  (0, import_vitest.it)("returns direct children whose parent matches the provided id", () => {
+    const parentByFrame = /* @__PURE__ */ new Map([
+      ["frame-1", null],
+      ["frame-2", "frame-1"],
+      ["frame-3", "frame-1"],
+      ["frame-4", "frame-2"]
+    ]);
+    (0, import_vitest.expect)((0, import_focusSelectors.listChildrenOf)(parentByFrame, "frame-1")).toEqual([
+      "frame-2",
+      "frame-3"
+    ]);
+    (0, import_vitest.expect)((0, import_focusSelectors.listChildrenOf)(parentByFrame, "frame-4")).toEqual([]);
+  });
+});
+//# sourceMappingURL=snapshot-focus-selectors-utils.test.js.map

package/dist/cjs/tests/snapshot-focus-selectors-utils.test.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../tests/snapshot-focus-selectors-utils.test.ts"],
+  "sourcesContent": ["import type { Step } from \"../lib/v3/types/private/snapshot.js\";\nimport { describe, expect, it } from \"vitest\";\nimport {\n  buildXPathFromSteps,\n  listChildrenOf,\n  parseXPathToSteps,\n} from \"../lib/v3/understudy/a11y/snapshot/focusSelectors.js\";\n\ndescribe(\"parseXPathToSteps\", () => {\n  it(\"records axis direction and normalized names\", () => {\n    const steps = parseXPathToSteps(\" //iframe[1]/div[2]//SPAN \");\n    expect(steps).toEqual([\n      { axis: \"desc\", raw: \"iframe[1]\", name: \"iframe\" },\n      { axis: \"child\", raw: \"div[2]\", name: \"div\" },\n      { axis: \"desc\", raw: \"SPAN\", name: \"span\" },\n    ]);\n  });\n\n  it(\"drops empty segments and returns [] for blank input\", () => {\n    expect(parseXPathToSteps(\"   \")).toEqual([]);\n    expect(parseXPathToSteps(\"/ \")).toEqual([]);\n  });\n});\n\ndescribe(\"buildXPathFromSteps\", () => {\n  it(\"reconstructs descendant and child hops as a string\", () => {\n    const steps: ReadonlyArray<Step> = [\n      { axis: \"child\", raw: \"iframe[1]\", name: \"iframe\" },\n      { axis: \"desc\", raw: \"div[@id='main']\", name: \"div\" },\n      { axis: \"child\", raw: \"span\", name: \"span\" },\n    ];\n    expect(buildXPathFromSteps(steps)).toBe(\"/iframe[1]//div[@id='main']/span\");\n  });\n\n  it(\"returns '/' for empty sequences\", () => {\n    expect(buildXPathFromSteps([])).toBe(\"/\");\n  });\n});\n\ndescribe(\"listChildrenOf\", () => {\n  it(\"returns direct children whose parent matches the provided id\", () => {\n    const parentByFrame = new Map<string, string | null>([\n      [\"frame-1\", null],\n      [\"frame-2\", \"frame-1\"],\n      [\"frame-3\", \"frame-1\"],\n      [\"frame-4\", \"frame-2\"],\n    ]);\n    expect(listChildrenOf(parentByFrame, \"frame-1\")).toEqual([\n      \"frame-2\",\n      \"frame-3\",\n    ]);\n    expect(listChildrenOf(parentByFrame, \"frame-4\")).toEqual([]);\n  });\n});\n"],
+  "mappings": "AACA,oBAAqC;AACrC,4BAIO;AAAA,IAEP,wBAAS,qBAAqB,MAAM;AAClC,wBAAG,+CAA+C,MAAM;AACtD,UAAM,YAAQ,yCAAkB,4BAA4B;AAC5D,8BAAO,KAAK,EAAE,QAAQ;AAAA,MACpB,EAAE,MAAM,QAAQ,KAAK,aAAa,MAAM,SAAS;AAAA,MACjD,EAAE,MAAM,SAAS,KAAK,UAAU,MAAM,MAAM;AAAA,MAC5C,EAAE,MAAM,QAAQ,KAAK,QAAQ,MAAM,OAAO;AAAA,IAC5C,CAAC;AAAA,EACH,CAAC;AAED,wBAAG,uDAAuD,MAAM;AAC9D,kCAAO,yCAAkB,KAAK,CAAC,EAAE,QAAQ,CAAC,CAAC;AAC3C,kCAAO,yCAAkB,IAAI,CAAC,EAAE,QAAQ,CAAC,CAAC;AAAA,EAC5C,CAAC;AACH,CAAC;AAAA,IAED,wBAAS,uBAAuB,MAAM;AACpC,wBAAG,sDAAsD,MAAM;AAC7D,UAAM,QAA6B;AAAA,MACjC,EAAE,MAAM,SAAS,KAAK,aAAa,MAAM,SAAS;AAAA,MAClD,EAAE,MAAM,QAAQ,KAAK,mBAAmB,MAAM,MAAM;AAAA,MACpD,EAAE,MAAM,SAAS,KAAK,QAAQ,MAAM,OAAO;AAAA,IAC7C;AACA,kCAAO,2CAAoB,KAAK,CAAC,EAAE,KAAK,kCAAkC;AAAA,EAC5E,CAAC;AAED,wBAAG,mCAAmC,MAAM;AAC1C,kCAAO,2CAAoB,CAAC,CAAC,CAAC,EAAE,KAAK,GAAG;AAAA,EAC1C,CAAC;AACH,CAAC;AAAA,IAED,wBAAS,kBAAkB,MAAM;AAC/B,wBAAG,gEAAgE,MAAM;AACvE,UAAM,gBAAgB,oBAAI,IAA2B;AAAA,MACnD,CAAC,WAAW,IAAI;AAAA,MAChB,CAAC,WAAW,SAAS;AAAA,MACrB,CAAC,WAAW,SAAS;AAAA,MACrB,CAAC,WAAW,SAAS;AAAA,IACvB,CAAC;AACD,kCAAO,sCAAe,eAAe,SAAS,CAAC,EAAE,QAAQ;AAAA,MACvD;AAAA,MACA;AAAA,IACF,CAAC;AACD,kCAAO,sCAAe,eAAe,SAAS,CAAC,EAAE,QAAQ,CAAC,CAAC;AAAA,EAC7D,CAAC;AACH,CAAC;",
+  "names": []
+}