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

package/dist/esm/tests/snapshot-frame-merge.test.js

@@ -0,0 +1,391 @@
+import { describe, expect, it } from "vitest";
+import { MockCDPSession } from "./helpers/mockCDPSession.js";
+import {
+  computeFramePrefixes,
+  mergeFramesIntoSnapshot
+} from "../lib/v3/understudy/a11y/snapshot/capture.js";
+const makePage = (sessions) => ({
+  getSessionForFrame: (frameId) => sessions[frameId] ?? sessions.root,
+  getOrdinal: (frameId) => frameId === "frame-1" ? 0 : frameId === "frame-2" ? 1 : 2
+});
+describe("computeFramePrefixes", () => {
+  it("derives prefixes from parent iframe xpaths within the same session", async () => {
+    const parentSession = new MockCDPSession({
+      "DOM.getFrameOwner": async () => ({ backendNodeId: 200 })
+    });
+    const page = makePage({
+      "frame-1": parentSession,
+      "frame-2": parentSession,
+      root: parentSession
+    });
+    const perFrameMaps = /* @__PURE__ */ new Map([
+      [
+        "frame-1",
+        {
+          tagNameMap: {},
+          scrollableMap: {},
+          urlMap: {},
+          xpathMap: { "0-200": "/html[1]/body[1]/iframe[1]" }
+        }
+      ]
+    ]);
+    const context = {
+      rootId: "frame-1",
+      frames: ["frame-1", "frame-2"],
+      parentByFrame: /* @__PURE__ */ new Map([
+        ["frame-1", null],
+        ["frame-2", "frame-1"]
+      ])
+    };
+    const { absPrefix, iframeHostEncByChild } = await computeFramePrefixes(
+      page,
+      context,
+      perFrameMaps,
+      context.frames
+    );
+    expect(absPrefix.get("frame-1")).toBe("");
+    expect(absPrefix.get("frame-2")).toBe("/html[1]/body[1]/iframe[1]");
+    expect(iframeHostEncByChild.get("frame-2")).toBe("0-200");
+  });
+  it("inherits the parent prefix when frame owner lookups fail (OOPIF)", async () => {
+    const parentSession = new MockCDPSession({
+      "DOM.getFrameOwner": async (params) => {
+        if (params?.frameId === "frame-2") return { backendNodeId: 200 };
+        if (params?.frameId === "frame-3") throw new Error("unavailable");
+        return {};
+      }
+    });
+    const page = makePage({
+      "frame-1": parentSession,
+      "frame-2": parentSession,
+      "frame-3": parentSession,
+      root: parentSession
+    });
+    const perFrameMaps = /* @__PURE__ */ new Map([
+      [
+        "frame-1",
+        {
+          tagNameMap: {},
+          scrollableMap: {},
+          urlMap: {},
+          xpathMap: { "0-200": "/iframe[1]" }
+        }
+      ],
+      [
+        "frame-2",
+        {
+          tagNameMap: {},
+          scrollableMap: {},
+          urlMap: {},
+          xpathMap: { "1-300": "/div[1]/iframe[1]" }
+        }
+      ]
+    ]);
+    const context = {
+      rootId: "frame-1",
+      frames: ["frame-1", "frame-2", "frame-3"],
+      parentByFrame: /* @__PURE__ */ new Map([
+        ["frame-1", null],
+        ["frame-2", "frame-1"],
+        ["frame-3", "frame-2"]
+      ])
+    };
+    const maps = await computeFramePrefixes(
+      page,
+      context,
+      perFrameMaps,
+      context.frames
+    );
+    expect(maps.absPrefix.get("frame-2")).toBe("/iframe[1]");
+    expect(maps.absPrefix.get("frame-3")).toBe("/iframe[1]");
+  });
+  it("inherits parent prefix when iframe xpath mapping is missing", async () => {
+    const session = new MockCDPSession({
+      "DOM.getFrameOwner": async () => ({ backendNodeId: 999 })
+    });
+    const page = makePage({
+      "frame-1": session,
+      "frame-2": session,
+      root: session
+    });
+    const perFrameMaps = /* @__PURE__ */ new Map([
+      [
+        "frame-1",
+        {
+          tagNameMap: {},
+          scrollableMap: {},
+          urlMap: {},
+          xpathMap: {}
+        }
+      ]
+    ]);
+    const context = {
+      rootId: "frame-1",
+      frames: ["frame-1", "frame-2"],
+      parentByFrame: /* @__PURE__ */ new Map([
+        ["frame-1", null],
+        ["frame-2", "frame-1"]
+      ])
+    };
+    const result = await computeFramePrefixes(
+      page,
+      context,
+      perFrameMaps,
+      context.frames
+    );
+    expect(result.absPrefix.get("frame-2")).toBe("");
+  });
+  it("does not compute prefixes for frames excluded from the scope", async () => {
+    const session = new MockCDPSession({
+      "DOM.getFrameOwner": async () => ({ backendNodeId: 200 })
+    });
+    const page = makePage({
+      "frame-1": session,
+      "frame-2": session,
+      root: session
+    });
+    const perFrameMaps = /* @__PURE__ */ new Map([
+      [
+        "frame-1",
+        {
+          tagNameMap: {},
+          scrollableMap: {},
+          urlMap: {},
+          xpathMap: { "0-200": "/iframe[1]" }
+        }
+      ]
+    ]);
+    const context = {
+      rootId: "frame-1",
+      frames: ["frame-1", "frame-2"],
+      parentByFrame: /* @__PURE__ */ new Map([
+        ["frame-1", null],
+        ["frame-2", "frame-1"]
+      ])
+    };
+    const { absPrefix, iframeHostEncByChild } = await computeFramePrefixes(
+      page,
+      context,
+      perFrameMaps,
+      ["frame-1"]
+    );
+    expect(absPrefix.has("frame-2")).toBe(false);
+    expect(iframeHostEncByChild.has("frame-2")).toBe(false);
+  });
+});
+describe("mergeFramesIntoSnapshot", () => {
+  it("merges root and child maps, prefixing child xpaths and injecting subtrees", () => {
+    const context = {
+      rootId: "frame-1",
+      frames: ["frame-1", "frame-2"],
+      parentByFrame: /* @__PURE__ */ new Map([
+        ["frame-1", null],
+        ["frame-2", "frame-1"]
+      ])
+    };
+    const perFrameMaps = /* @__PURE__ */ new Map([
+      [
+        "frame-1",
+        {
+          tagNameMap: {},
+          scrollableMap: {},
+          urlMap: { "0-10": "https://example.com" },
+          xpathMap: { "0-10": "/html[1]/body[1]" }
+        }
+      ],
+      [
+        "frame-2",
+        {
+          tagNameMap: {},
+          scrollableMap: {},
+          urlMap: { "1-20": "https://child.com" },
+          xpathMap: { "1-20": "/div[1]/span[1]" }
+        }
+      ]
+    ]);
+    const perFrameOutlines = [
+      { frameId: "frame-1", outline: "[0-10] body\n  [0-200] iframe" },
+      { frameId: "frame-2", outline: "[1-20] child" }
+    ];
+    const absPrefix = /* @__PURE__ */ new Map([
+      ["frame-1", ""],
+      ["frame-2", "/html[1]/body[1]/iframe[1]"]
+    ]);
+    const iframeHostEncByChild = /* @__PURE__ */ new Map([
+      ["frame-2", "0-200"]
+    ]);
+    const snapshot = mergeFramesIntoSnapshot(
+      context,
+      perFrameMaps,
+      perFrameOutlines,
+      absPrefix,
+      iframeHostEncByChild,
+      context.frames
+    );
+    expect(snapshot.combinedXpathMap["0-10"]).toBe("/html[1]/body[1]");
+    expect(snapshot.combinedXpathMap["1-20"]).toBe(
+      "/html[1]/body[1]/iframe[1]/div[1]/span[1]"
+    );
+    expect(snapshot.combinedUrlMap["1-20"]).toBe("https://child.com");
+    expect(snapshot.combinedTree).toContain("[1-20] child");
+  });
+  it("skips frames without maps and handles missing iframe mappings", () => {
+    const context = {
+      rootId: "frame-1",
+      frames: ["frame-1", "frame-2"],
+      parentByFrame: /* @__PURE__ */ new Map([
+        ["frame-1", null],
+        ["frame-2", "frame-1"]
+      ])
+    };
+    const perFrameMaps = /* @__PURE__ */ new Map([
+      [
+        "frame-1",
+        {
+          tagNameMap: {},
+          scrollableMap: {},
+          urlMap: {},
+          xpathMap: { "0-10": "/html[1]" }
+        }
+      ]
+    ]);
+    const perFrameOutlines = [
+      { frameId: "frame-1", outline: "[0-10] html" },
+      { frameId: "frame-2", outline: "[1-20] orphan" }
+    ];
+    const absPrefix = /* @__PURE__ */ new Map([
+      ["frame-1", ""],
+      ["frame-2", "/missing"]
+    ]);
+    const snapshot = mergeFramesIntoSnapshot(
+      context,
+      perFrameMaps,
+      perFrameOutlines,
+      absPrefix,
+      /* @__PURE__ */ new Map(),
+      context.frames
+    );
+    expect(snapshot.combinedXpathMap["1-20"]).toBeUndefined();
+    expect(snapshot.combinedTree).toBe("[0-10] html");
+  });
+  it("falls back to first outline when root frame outline is missing", () => {
+    const context = {
+      rootId: "frame-1",
+      frames: ["frame-1", "frame-2"],
+      parentByFrame: /* @__PURE__ */ new Map([
+        ["frame-1", null],
+        ["frame-2", "frame-1"]
+      ])
+    };
+    const perFrameMaps = /* @__PURE__ */ new Map([
+      [
+        "frame-2",
+        {
+          tagNameMap: {},
+          scrollableMap: {},
+          urlMap: {},
+          xpathMap: {}
+        }
+      ]
+    ]);
+    const perFrameOutlines = [
+      { frameId: "frame-2", outline: "[child] frame2" }
+    ];
+    const snapshot = mergeFramesIntoSnapshot(
+      context,
+      perFrameMaps,
+      perFrameOutlines,
+      /* @__PURE__ */ new Map([["frame-2", "/iframe[1]"]]),
+      /* @__PURE__ */ new Map(),
+      context.frames
+    );
+    expect(snapshot.combinedTree).toBe("[child] frame2");
+  });
+  it("overwrites duplicate iframe host entries when multiple children map to the same parent", () => {
+    const context = {
+      rootId: "frame-1",
+      frames: ["frame-1", "frame-2", "frame-3"],
+      parentByFrame: /* @__PURE__ */ new Map([
+        ["frame-1", null],
+        ["frame-2", "frame-1"],
+        ["frame-3", "frame-1"]
+      ])
+    };
+    const perFrameMaps = /* @__PURE__ */ new Map([
+      [
+        "frame-1",
+        {
+          tagNameMap: {},
+          scrollableMap: {},
+          urlMap: {},
+          xpathMap: {}
+        }
+      ]
+    ]);
+    const perFrameOutlines = [
+      { frameId: "frame-1", outline: "[root] frame1\n  [0-200] iframe slot" },
+      { frameId: "frame-2", outline: "[child] frame2" },
+      { frameId: "frame-3", outline: "[child] frame3" }
+    ];
+    const snapshot = mergeFramesIntoSnapshot(
+      context,
+      perFrameMaps,
+      perFrameOutlines,
+      /* @__PURE__ */ new Map([
+        ["frame-1", ""],
+        ["frame-2", ""],
+        ["frame-3", ""]
+      ]),
+      /* @__PURE__ */ new Map([
+        ["frame-2", "0-200"],
+        ["frame-3", "0-200"]
+      ]),
+      context.frames
+    );
+    expect(snapshot.combinedTree).toContain("[child] frame3");
+    expect(snapshot.combinedTree).not.toContain("[child] frame2");
+  });
+  it("only merges xpath and url maps for frames included in frameIds", () => {
+    const context = {
+      rootId: "frame-1",
+      frames: ["frame-1", "frame-2"],
+      parentByFrame: /* @__PURE__ */ new Map([
+        ["frame-1", null],
+        ["frame-2", "frame-1"]
+      ])
+    };
+    const perFrameMaps = /* @__PURE__ */ new Map([
+      [
+        "frame-1",
+        {
+          tagNameMap: {},
+          scrollableMap: {},
+          urlMap: { "0-10": "https://root.test" },
+          xpathMap: { "0-10": "/html[1]" }
+        }
+      ],
+      [
+        "frame-2",
+        {
+          tagNameMap: {},
+          scrollableMap: {},
+          urlMap: { "1-20": "https://child.test" },
+          xpathMap: { "1-20": "/div[1]" }
+        }
+      ]
+    ]);
+    const perFrameOutlines = [{ frameId: "frame-1", outline: "[root] doc" }];
+    const snapshot = mergeFramesIntoSnapshot(
+      context,
+      perFrameMaps,
+      perFrameOutlines,
+      /* @__PURE__ */ new Map([["frame-1", ""]]),
+      /* @__PURE__ */ new Map(),
+      ["frame-1"]
+    );
+    expect(snapshot.combinedXpathMap["0-10"]).toBe("/html[1]");
+    expect(snapshot.combinedXpathMap["1-20"]).toBeUndefined();
+    expect(snapshot.perFrame?.map((pf) => pf.frameId)).toEqual(["frame-1"]);
+  });
+});
+//# sourceMappingURL=snapshot-frame-merge.test.js.map

package/dist/esm/tests/snapshot-frame-merge.test.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../tests/snapshot-frame-merge.test.ts"],
+  "sourcesContent": ["import { describe, expect, it } from \"vitest\";\nimport type {\n  FrameContext,\n  FrameDomMaps,\n} from \"../lib/v3/types/private/index.js\";\nimport type { Page } from \"../lib/v3/understudy/page.js\";\nimport { MockCDPSession } from \"./helpers/mockCDPSession.js\";\nimport {\n  computeFramePrefixes,\n  mergeFramesIntoSnapshot,\n} from \"../lib/v3/understudy/a11y/snapshot/capture.js\";\n\nconst makePage = (sessions: Record<string, MockCDPSession>): Page =>\n  ({\n    getSessionForFrame: (frameId: string) => sessions[frameId] ?? sessions.root,\n    getOrdinal: (frameId: string) =>\n      frameId === \"frame-1\" ? 0 : frameId === \"frame-2\" ? 1 : 2,\n  }) as unknown as Page;\n\ndescribe(\"computeFramePrefixes\", () => {\n  it(\"derives prefixes from parent iframe xpaths within the same session\", async () => {\n    const parentSession = new MockCDPSession({\n      \"DOM.getFrameOwner\": async () => ({ backendNodeId: 200 }),\n    });\n    const page = makePage({\n      \"frame-1\": parentSession,\n      \"frame-2\": parentSession,\n      root: parentSession,\n    });\n\n    const perFrameMaps = new Map<string, FrameDomMaps>([\n      [\n        \"frame-1\",\n        {\n          tagNameMap: {},\n          scrollableMap: {},\n          urlMap: {},\n          xpathMap: { \"0-200\": \"/html[1]/body[1]/iframe[1]\" },\n        },\n      ],\n    ]);\n\n    const context: FrameContext = {\n      rootId: \"frame-1\",\n      frames: [\"frame-1\", \"frame-2\"],\n      parentByFrame: new Map([\n        [\"frame-1\", null],\n        [\"frame-2\", \"frame-1\"],\n      ]),\n    };\n\n    const { absPrefix, iframeHostEncByChild } = await computeFramePrefixes(\n      page,\n      context,\n      perFrameMaps,\n      context.frames,\n    );\n\n    expect(absPrefix.get(\"frame-1\")).toBe(\"\");\n    expect(absPrefix.get(\"frame-2\")).toBe(\"/html[1]/body[1]/iframe[1]\");\n    expect(iframeHostEncByChild.get(\"frame-2\")).toBe(\"0-200\");\n  });\n\n  it(\"inherits the parent prefix when frame owner lookups fail (OOPIF)\", async () => {\n    const parentSession = new MockCDPSession({\n      \"DOM.getFrameOwner\": async (params) => {\n        if (params?.frameId === \"frame-2\") return { backendNodeId: 200 };\n        if (params?.frameId === \"frame-3\") throw new Error(\"unavailable\");\n        return {};\n      },\n    });\n    const page = makePage({\n      \"frame-1\": parentSession,\n      \"frame-2\": parentSession,\n      \"frame-3\": parentSession,\n      root: parentSession,\n    });\n\n    const perFrameMaps = new Map<string, FrameDomMaps>([\n      [\n        \"frame-1\",\n        {\n          tagNameMap: {},\n          scrollableMap: {},\n          urlMap: {},\n          xpathMap: { \"0-200\": \"/iframe[1]\" },\n        },\n      ],\n      [\n        \"frame-2\",\n        {\n          tagNameMap: {},\n          scrollableMap: {},\n          urlMap: {},\n          xpathMap: { \"1-300\": \"/div[1]/iframe[1]\" },\n        },\n      ],\n    ]);\n\n    const context: FrameContext = {\n      rootId: \"frame-1\",\n      frames: [\"frame-1\", \"frame-2\", \"frame-3\"],\n      parentByFrame: new Map([\n        [\"frame-1\", null],\n        [\"frame-2\", \"frame-1\"],\n        [\"frame-3\", \"frame-2\"],\n      ]),\n    };\n\n    const maps = await computeFramePrefixes(\n      page,\n      context,\n      perFrameMaps,\n      context.frames,\n    );\n\n    expect(maps.absPrefix.get(\"frame-2\")).toBe(\"/iframe[1]\");\n    expect(maps.absPrefix.get(\"frame-3\")).toBe(\"/iframe[1]\");\n  });\n\n  it(\"inherits parent prefix when iframe xpath mapping is missing\", async () => {\n    const session = new MockCDPSession({\n      \"DOM.getFrameOwner\": async () => ({ backendNodeId: 999 }),\n    });\n    const page = makePage({\n      \"frame-1\": session,\n      \"frame-2\": session,\n      root: session,\n    });\n\n    const perFrameMaps = new Map<string, FrameDomMaps>([\n      [\n        \"frame-1\",\n        {\n          tagNameMap: {},\n          scrollableMap: {},\n          urlMap: {},\n          xpathMap: {},\n        },\n      ],\n    ]);\n\n    const context: FrameContext = {\n      rootId: \"frame-1\",\n      frames: [\"frame-1\", \"frame-2\"],\n      parentByFrame: new Map([\n        [\"frame-1\", null],\n        [\"frame-2\", \"frame-1\"],\n      ]),\n    };\n\n    const result = await computeFramePrefixes(\n      page,\n      context,\n      perFrameMaps as Map<string, FrameDomMaps>,\n      context.frames,\n    );\n    expect(result.absPrefix.get(\"frame-2\")).toBe(\"\");\n  });\n\n  it(\"does not compute prefixes for frames excluded from the scope\", async () => {\n    const session = new MockCDPSession({\n      \"DOM.getFrameOwner\": async () => ({ backendNodeId: 200 }),\n    });\n    const page = makePage({\n      \"frame-1\": session,\n      \"frame-2\": session,\n      root: session,\n    });\n\n    const perFrameMaps = new Map<string, FrameDomMaps>([\n      [\n        \"frame-1\",\n        {\n          tagNameMap: {},\n          scrollableMap: {},\n          urlMap: {},\n          xpathMap: { \"0-200\": \"/iframe[1]\" },\n        },\n      ],\n    ]);\n\n    const context: FrameContext = {\n      rootId: \"frame-1\",\n      frames: [\"frame-1\", \"frame-2\"],\n      parentByFrame: new Map([\n        [\"frame-1\", null],\n        [\"frame-2\", \"frame-1\"],\n      ]),\n    };\n\n    const { absPrefix, iframeHostEncByChild } = await computeFramePrefixes(\n      page,\n      context,\n      perFrameMaps,\n      [\"frame-1\"],\n    );\n\n    expect(absPrefix.has(\"frame-2\")).toBe(false);\n    expect(iframeHostEncByChild.has(\"frame-2\")).toBe(false);\n  });\n});\n\ndescribe(\"mergeFramesIntoSnapshot\", () => {\n  it(\"merges root and child maps, prefixing child xpaths and injecting subtrees\", () => {\n    const context: FrameContext = {\n      rootId: \"frame-1\",\n      frames: [\"frame-1\", \"frame-2\"],\n      parentByFrame: new Map([\n        [\"frame-1\", null],\n        [\"frame-2\", \"frame-1\"],\n      ]),\n    };\n\n    const perFrameMaps = new Map<string, FrameDomMaps>([\n      [\n        \"frame-1\",\n        {\n          tagNameMap: {},\n          scrollableMap: {},\n          urlMap: { \"0-10\": \"https://example.com\" },\n          xpathMap: { \"0-10\": \"/html[1]/body[1]\" },\n        },\n      ],\n      [\n        \"frame-2\",\n        {\n          tagNameMap: {},\n          scrollableMap: {},\n          urlMap: { \"1-20\": \"https://child.com\" },\n          xpathMap: { \"1-20\": \"/div[1]/span[1]\" },\n        },\n      ],\n    ]);\n\n    const perFrameOutlines = [\n      { frameId: \"frame-1\", outline: \"[0-10] body\\n  [0-200] iframe\" },\n      { frameId: \"frame-2\", outline: \"[1-20] child\" },\n    ];\n\n    const absPrefix = new Map<string, string>([\n      [\"frame-1\", \"\"],\n      [\"frame-2\", \"/html[1]/body[1]/iframe[1]\"],\n    ]);\n    const iframeHostEncByChild = new Map<string, string>([\n      [\"frame-2\", \"0-200\"],\n    ]);\n\n    const snapshot = mergeFramesIntoSnapshot(\n      context,\n      perFrameMaps,\n      perFrameOutlines,\n      absPrefix,\n      iframeHostEncByChild,\n      context.frames,\n    );\n\n    expect(snapshot.combinedXpathMap[\"0-10\"]).toBe(\"/html[1]/body[1]\");\n    expect(snapshot.combinedXpathMap[\"1-20\"]).toBe(\n      \"/html[1]/body[1]/iframe[1]/div[1]/span[1]\",\n    );\n    expect(snapshot.combinedUrlMap[\"1-20\"]).toBe(\"https://child.com\");\n    expect(snapshot.combinedTree).toContain(\"[1-20] child\");\n  });\n\n  it(\"skips frames without maps and handles missing iframe mappings\", () => {\n    const context: FrameContext = {\n      rootId: \"frame-1\",\n      frames: [\"frame-1\", \"frame-2\"],\n      parentByFrame: new Map([\n        [\"frame-1\", null],\n        [\"frame-2\", \"frame-1\"],\n      ]),\n    };\n\n    const perFrameMaps = new Map<string, FrameDomMaps>([\n      [\n        \"frame-1\",\n        {\n          tagNameMap: {},\n          scrollableMap: {},\n          urlMap: {},\n          xpathMap: { \"0-10\": \"/html[1]\" },\n        },\n      ],\n    ]);\n\n    const perFrameOutlines = [\n      { frameId: \"frame-1\", outline: \"[0-10] html\" },\n      { frameId: \"frame-2\", outline: \"[1-20] orphan\" },\n    ];\n\n    const absPrefix = new Map<string, string>([\n      [\"frame-1\", \"\"],\n      [\"frame-2\", \"/missing\"],\n    ]);\n\n    const snapshot = mergeFramesIntoSnapshot(\n      context,\n      perFrameMaps,\n      perFrameOutlines,\n      absPrefix,\n      new Map(),\n      context.frames,\n    );\n\n    expect(snapshot.combinedXpathMap[\"1-20\"]).toBeUndefined();\n    expect(snapshot.combinedTree).toBe(\"[0-10] html\");\n  });\n\n  it(\"falls back to first outline when root frame outline is missing\", () => {\n    const context: FrameContext = {\n      rootId: \"frame-1\",\n      frames: [\"frame-1\", \"frame-2\"],\n      parentByFrame: new Map([\n        [\"frame-1\", null],\n        [\"frame-2\", \"frame-1\"],\n      ]),\n    };\n\n    const perFrameMaps = new Map<string, FrameDomMaps>([\n      [\n        \"frame-2\",\n        {\n          tagNameMap: {},\n          scrollableMap: {},\n          urlMap: {},\n          xpathMap: {},\n        },\n      ],\n    ]);\n\n    const perFrameOutlines = [\n      { frameId: \"frame-2\", outline: \"[child] frame2\" },\n    ];\n\n    const snapshot = mergeFramesIntoSnapshot(\n      context,\n      perFrameMaps,\n      perFrameOutlines,\n      new Map([[\"frame-2\", \"/iframe[1]\"]]),\n      new Map(),\n      context.frames,\n    );\n\n    expect(snapshot.combinedTree).toBe(\"[child] frame2\");\n  });\n\n  it(\"overwrites duplicate iframe host entries when multiple children map to the same parent\", () => {\n    const context: FrameContext = {\n      rootId: \"frame-1\",\n      frames: [\"frame-1\", \"frame-2\", \"frame-3\"],\n      parentByFrame: new Map([\n        [\"frame-1\", null],\n        [\"frame-2\", \"frame-1\"],\n        [\"frame-3\", \"frame-1\"],\n      ]),\n    };\n\n    const perFrameMaps = new Map<string, FrameDomMaps>([\n      [\n        \"frame-1\",\n        {\n          tagNameMap: {},\n          scrollableMap: {},\n          urlMap: {},\n          xpathMap: {},\n        },\n      ],\n    ]);\n\n    const perFrameOutlines = [\n      { frameId: \"frame-1\", outline: \"[root] frame1\\n  [0-200] iframe slot\" },\n      { frameId: \"frame-2\", outline: \"[child] frame2\" },\n      { frameId: \"frame-3\", outline: \"[child] frame3\" },\n    ];\n\n    const snapshot = mergeFramesIntoSnapshot(\n      context,\n      perFrameMaps,\n      perFrameOutlines,\n      new Map([\n        [\"frame-1\", \"\"],\n        [\"frame-2\", \"\"],\n        [\"frame-3\", \"\"],\n      ]),\n      new Map([\n        [\"frame-2\", \"0-200\"],\n        [\"frame-3\", \"0-200\"],\n      ]),\n      context.frames,\n    );\n\n    expect(snapshot.combinedTree).toContain(\"[child] frame3\");\n    expect(snapshot.combinedTree).not.toContain(\"[child] frame2\");\n  });\n\n  it(\"only merges xpath and url maps for frames included in frameIds\", () => {\n    const context: FrameContext = {\n      rootId: \"frame-1\",\n      frames: [\"frame-1\", \"frame-2\"],\n      parentByFrame: new Map([\n        [\"frame-1\", null],\n        [\"frame-2\", \"frame-1\"],\n      ]),\n    };\n\n    const perFrameMaps = new Map<string, FrameDomMaps>([\n      [\n        \"frame-1\",\n        {\n          tagNameMap: {},\n          scrollableMap: {},\n          urlMap: { \"0-10\": \"https://root.test\" },\n          xpathMap: { \"0-10\": \"/html[1]\" },\n        },\n      ],\n      [\n        \"frame-2\",\n        {\n          tagNameMap: {},\n          scrollableMap: {},\n          urlMap: { \"1-20\": \"https://child.test\" },\n          xpathMap: { \"1-20\": \"/div[1]\" },\n        },\n      ],\n    ]);\n\n    const perFrameOutlines = [{ frameId: \"frame-1\", outline: \"[root] doc\" }];\n\n    const snapshot = mergeFramesIntoSnapshot(\n      context,\n      perFrameMaps,\n      perFrameOutlines,\n      new Map([[\"frame-1\", \"\"]]),\n      new Map(),\n      [\"frame-1\"],\n    );\n\n    expect(snapshot.combinedXpathMap[\"0-10\"]).toBe(\"/html[1]\");\n    expect(snapshot.combinedXpathMap[\"1-20\"]).toBeUndefined();\n    expect(snapshot.perFrame?.map((pf) => pf.frameId)).toEqual([\"frame-1\"]);\n  });\n});\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/esm/tests/snapshot-tree-format-utils.test.js

@@ -0,0 +1,113 @@
+import { describe, expect, it } from "vitest";
+import {
+  cleanText,
+  diffCombinedTrees,
+  formatTreeLine,
+  indentBlock,
+  injectSubtrees,
+  normaliseSpaces
+} from "../lib/v3/understudy/a11y/snapshot/treeFormatUtils.js";
+describe("formatTreeLine", () => {
+  it("includes encoded ids and indents children", () => {
+    const outline = formatTreeLine({
+      role: "section",
+      name: "Container",
+      encodedId: "frame-1",
+      nodeId: "ax-1",
+      children: [
+        {
+          role: "button",
+          name: "Submit",
+          nodeId: "ax-2"
+        }
+      ]
+    });
+    expect(outline).toBe(
+      "[frame-1] section: Container\n  [ax-2] button: Submit"
+    );
+  });
+});
+describe("injectSubtrees", () => {
+  it("nests child outlines under iframe encoded ids", () => {
+    const rootOutline = `[root] document
+  [iframe-1] iframe
+  [leaf] item`;
+    const iframeOutline = `[child-root] child
+  [nested-frame] iframe`;
+    const nestedOutline = `[nested-leaf] nested`;
+    const merged = injectSubtrees(
+      rootOutline,
+      /* @__PURE__ */ new Map([
+        ["iframe-1", iframeOutline],
+        ["nested-frame", nestedOutline]
+      ])
+    );
+    expect(merged).toBe(
+      `[root] document
+  [iframe-1] iframe
+    [child-root] child
+      [nested-frame] iframe
+        [nested-leaf] nested
+  [leaf] item`
+    );
+  });
+  it("injects child outline only once when the same id repeats", () => {
+    const rootOutline = `[root] document
+  [iframe-1] iframe
+  [iframe-1] iframe`;
+    const iframeOutline = `[child-root] child`;
+    const merged = injectSubtrees(
+      rootOutline,
+      /* @__PURE__ */ new Map([["iframe-1", iframeOutline]])
+    );
+    expect(merged).toBe(
+      `[root] document
+  [iframe-1] iframe
+    [child-root] child
+  [iframe-1] iframe`
+    );
+  });
+  it("returns the original outline when no encoded ids are matched", () => {
+    const outline = `[root] document
+  [leaf] item`;
+    expect(injectSubtrees(outline, /* @__PURE__ */ new Map([["other", "[x] child"]]))).toBe(
+      outline
+    );
+  });
+});
+describe("indentBlock", () => {
+  it("prefixes each line with the provided indent", () => {
+    expect(indentBlock("a\nb", "  ")).toBe("  a\n  b");
+    expect(indentBlock("", "  ")).toBe("");
+  });
+});
+describe("diffCombinedTrees", () => {
+  it("returns newly-added lines relative to previous outline", () => {
+    const prev = `[root] document
+  [child] a`;
+    const next = `[root] document
+  [child] a
+  [child-2] b`;
+    expect(diffCombinedTrees(prev, next)).toBe("[child-2] b");
+  });
+  it("normalizes indentation for added lines with stray spaces", () => {
+    const prev = `[root] document
+    [child] a`;
+    const next = `[root] document
+    [child] a
+        [child-2] b`;
+    expect(diffCombinedTrees(prev, next)).toBe("[child-2] b");
+  });
+});
+describe("cleanText", () => {
+  it("removes NBSP and private-use characters while collapsing spaces", () => {
+    const dirty = `Hello\xA0\xA0world\uE000 !`;
+    expect(cleanText(dirty)).toBe("Hello world !");
+  });
+});
+describe("normaliseSpaces", () => {
+  it("replaces whitespace runs with a single space", () => {
+    expect(normaliseSpaces("a   b	c\nd")).toBe("a b c d");
+  });
+});
+//# sourceMappingURL=snapshot-tree-format-utils.test.js.map

package/dist/esm/tests/snapshot-tree-format-utils.test.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../tests/snapshot-tree-format-utils.test.ts"],
+  "sourcesContent": ["import { describe, expect, it } from \"vitest\";\nimport {\n  cleanText,\n  diffCombinedTrees,\n  formatTreeLine,\n  indentBlock,\n  injectSubtrees,\n  normaliseSpaces,\n} from \"../lib/v3/understudy/a11y/snapshot/treeFormatUtils.js\";\n\ndescribe(\"formatTreeLine\", () => {\n  it(\"includes encoded ids and indents children\", () => {\n    const outline = formatTreeLine({\n      role: \"section\",\n      name: \"Container\",\n      encodedId: \"frame-1\",\n      nodeId: \"ax-1\",\n      children: [\n        {\n          role: \"button\",\n          name: \"Submit\",\n          nodeId: \"ax-2\",\n        },\n      ],\n    });\n\n    expect(outline).toBe(\n      \"[frame-1] section: Container\\n  [ax-2] button: Submit\",\n    );\n  });\n});\n\ndescribe(\"injectSubtrees\", () => {\n  it(\"nests child outlines under iframe encoded ids\", () => {\n    const rootOutline = `[root] document\\n  [iframe-1] iframe\\n  [leaf] item`;\n    const iframeOutline = `[child-root] child\\n  [nested-frame] iframe`;\n    const nestedOutline = `[nested-leaf] nested`;\n\n    const merged = injectSubtrees(\n      rootOutline,\n      new Map([\n        [\"iframe-1\", iframeOutline],\n        [\"nested-frame\", nestedOutline],\n      ]),\n    );\n\n    expect(merged).toBe(\n      `[root] document\n  [iframe-1] iframe\n    [child-root] child\n      [nested-frame] iframe\n        [nested-leaf] nested\n  [leaf] item`,\n    );\n  });\n\n  it(\"injects child outline only once when the same id repeats\", () => {\n    const rootOutline = `[root] document\n  [iframe-1] iframe\n  [iframe-1] iframe`;\n    const iframeOutline = `[child-root] child`;\n\n    const merged = injectSubtrees(\n      rootOutline,\n      new Map([[\"iframe-1\", iframeOutline]]),\n    );\n\n    expect(merged).toBe(\n      `[root] document\n  [iframe-1] iframe\n    [child-root] child\n  [iframe-1] iframe`,\n    );\n  });\n\n  it(\"returns the original outline when no encoded ids are matched\", () => {\n    const outline = `[root] document\\n  [leaf] item`;\n    expect(injectSubtrees(outline, new Map([[\"other\", \"[x] child\"]]))).toBe(\n      outline,\n    );\n  });\n});\n\ndescribe(\"indentBlock\", () => {\n  it(\"prefixes each line with the provided indent\", () => {\n    expect(indentBlock(\"a\\nb\", \"  \")).toBe(\"  a\\n  b\");\n    expect(indentBlock(\"\", \"  \")).toBe(\"\");\n  });\n});\n\ndescribe(\"diffCombinedTrees\", () => {\n  it(\"returns newly-added lines relative to previous outline\", () => {\n    const prev = `[root] document\\n  [child] a`;\n    const next = `[root] document\\n  [child] a\\n  [child-2] b`;\n    expect(diffCombinedTrees(prev, next)).toBe(\"[child-2] b\");\n  });\n\n  it(\"normalizes indentation for added lines with stray spaces\", () => {\n    const prev = `[root] document\\n    [child] a`;\n    const next = `[root] document\\n    [child] a\\n        [child-2] b`;\n    expect(diffCombinedTrees(prev, next)).toBe(\"[child-2] b\");\n  });\n});\n\ndescribe(\"cleanText\", () => {\n  it(\"removes NBSP and private-use characters while collapsing spaces\", () => {\n    const dirty = `Hello\\u00A0\\u00A0world\\uE000 !`;\n    expect(cleanText(dirty)).toBe(\"Hello world !\");\n  });\n});\n\ndescribe(\"normaliseSpaces\", () => {\n  it(\"replaces whitespace runs with a single space\", () => {\n    expect(normaliseSpaces(\"a   b\\tc\\nd\")).toBe(\"a b c d\");\n  });\n});\n"],
+  "mappings": "AAAA,SAAS,UAAU,QAAQ,UAAU;AACrC;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;AAEP,SAAS,kBAAkB,MAAM;AAC/B,KAAG,6CAA6C,MAAM;AACpD,UAAM,UAAU,eAAe;AAAA,MAC7B,MAAM;AAAA,MACN,MAAM;AAAA,MACN,WAAW;AAAA,MACX,QAAQ;AAAA,MACR,UAAU;AAAA,QACR;AAAA,UACE,MAAM;AAAA,UACN,MAAM;AAAA,UACN,QAAQ;AAAA,QACV;AAAA,MACF;AAAA,IACF,CAAC;AAED,WAAO,OAAO,EAAE;AAAA,MACd;AAAA,IACF;AAAA,EACF,CAAC;AACH,CAAC;AAED,SAAS,kBAAkB,MAAM;AAC/B,KAAG,iDAAiD,MAAM;AACxD,UAAM,cAAc;AAAA;AAAA;AACpB,UAAM,gBAAgB;AAAA;AACtB,UAAM,gBAAgB;AAEtB,UAAM,SAAS;AAAA,MACb;AAAA,MACA,oBAAI,IAAI;AAAA,QACN,CAAC,YAAY,aAAa;AAAA,QAC1B,CAAC,gBAAgB,aAAa;AAAA,MAChC,CAAC;AAAA,IACH;AAEA,WAAO,MAAM,EAAE;AAAA,MACb;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,IAMF;AAAA,EACF,CAAC;AAED,KAAG,4DAA4D,MAAM;AACnE,UAAM,cAAc;AAAA;AAAA;AAGpB,UAAM,gBAAgB;AAEtB,UAAM,SAAS;AAAA,MACb;AAAA,MACA,oBAAI,IAAI,CAAC,CAAC,YAAY,aAAa,CAAC,CAAC;AAAA,IACvC;AAEA,WAAO,MAAM,EAAE;AAAA,MACb;AAAA;AAAA;AAAA;AAAA,IAIF;AAAA,EACF,CAAC;AAED,KAAG,gEAAgE,MAAM;AACvE,UAAM,UAAU;AAAA;AAChB,WAAO,eAAe,SAAS,oBAAI,IAAI,CAAC,CAAC,SAAS,WAAW,CAAC,CAAC,CAAC,CAAC,EAAE;AAAA,MACjE;AAAA,IACF;AAAA,EACF,CAAC;AACH,CAAC;AAED,SAAS,eAAe,MAAM;AAC5B,KAAG,+CAA+C,MAAM;AACtD,WAAO,YAAY,QAAQ,IAAI,CAAC,EAAE,KAAK,UAAU;AACjD,WAAO,YAAY,IAAI,IAAI,CAAC,EAAE,KAAK,EAAE;AAAA,EACvC,CAAC;AACH,CAAC;AAED,SAAS,qBAAqB,MAAM;AAClC,KAAG,0DAA0D,MAAM;AACjE,UAAM,OAAO;AAAA;AACb,UAAM,OAAO;AAAA;AAAA;AACb,WAAO,kBAAkB,MAAM,IAAI,CAAC,EAAE,KAAK,aAAa;AAAA,EAC1D,CAAC;AAED,KAAG,4DAA4D,MAAM;AACnE,UAAM,OAAO;AAAA;AACb,UAAM,OAAO;AAAA;AAAA;AACb,WAAO,kBAAkB,MAAM,IAAI,CAAC,EAAE,KAAK,aAAa;AAAA,EAC1D,CAAC;AACH,CAAC;AAED,SAAS,aAAa,MAAM;AAC1B,KAAG,mEAAmE,MAAM;AAC1E,UAAM,QAAQ;AACd,WAAO,UAAU,KAAK,CAAC,EAAE,KAAK,eAAe;AAAA,EAC/C,CAAC;AACH,CAAC;AAED,SAAS,mBAAmB,MAAM;AAChC,KAAG,gDAAgD,MAAM;AACvD,WAAO,gBAAgB,YAAa,CAAC,EAAE,KAAK,SAAS;AAAA,EACvD,CAAC;AACH,CAAC;",
+  "names": []
+}

package/dist/esm/tests/snapshot-xpath-utils.test.js

@@ -0,0 +1,79 @@
+import { describe, expect, it } from "vitest";
+import {
+  buildChildXPathSegments,
+  joinXPath,
+  normalizeXPath,
+  prefixXPath
+} from "../lib/v3/understudy/a11y/snapshot/xpathUtils.js";
+import { relativizeXPath } from "../lib/v3/understudy/a11y/snapshot/domTree.js";
+describe("prefixXPath", () => {
+  it("treats root prefixes as no-op", () => {
+    expect(prefixXPath("/", "/div[1]")).toBe("/div[1]");
+    expect(prefixXPath("/", "//div[1]")).toBe("//div[1]");
+  });
+  it("handles descendant hops and blank children", () => {
+    expect(prefixXPath("/html/body", "//slot[1]")).toBe("/html/body//slot[1]");
+    expect(prefixXPath("/html/body", "/")).toBe("/html/body");
+    expect(prefixXPath("/html/body/", "")).toBe("/html/body");
+  });
+});
+describe("normalizeXPath", () => {
+  it("strips prefixes, trims whitespace, and enforces absolute roots", () => {
+    expect(normalizeXPath("   xpath=/html/body/ ")).toBe("/html/body");
+    expect(normalizeXPath("div/span")).toBe("/div/span");
+    expect(normalizeXPath("")).toBe("");
+    expect(normalizeXPath()).toBe("");
+  });
+});
+describe("relativizeXPath", () => {
+  it("returns '/' when paths match exactly", () => {
+    expect(relativizeXPath("/html/body", "/html/body")).toBe("/");
+  });
+  it("omits duplicate prefixes and preserves descendant hops", () => {
+    expect(relativizeXPath("/html/body", "/html/body/div[2]")).toBe("/div[2]");
+    expect(relativizeXPath("/html/body", "/html/body//shadow-root[1]")).toBe(
+      "//shadow-root[1]"
+    );
+  });
+  it("falls back to absolute paths outside of the base document", () => {
+    expect(relativizeXPath("/html/body", "/head")).toBe("/head");
+    expect(relativizeXPath("/", "/html/body")).toBe("/html/body");
+  });
+});
+describe("buildChildXPathSegments", () => {
+  it("produces positional selectors for each node type", () => {
+    const makeNode = (nodeType, nodeName, override) => ({
+      nodeId: 1,
+      backendNodeId: 1,
+      localName: nodeName.toLowerCase(),
+      nodeValue: "",
+      ...override,
+      nodeType,
+      nodeName
+    });
+    const nodes = [
+      makeNode(1, "DIV"),
+      makeNode(1, "DIV"),
+      makeNode(1, "svg:path"),
+      makeNode(3, "#text"),
+      makeNode(8, "#comment")
+    ];
+    expect(buildChildXPathSegments(nodes)).toEqual([
+      "div[1]",
+      "div[2]",
+      "*[name()='svg:path'][1]",
+      "text()[1]",
+      "comment()[1]"
+    ]);
+  });
+});
+describe("joinXPath", () => {
+  it("joins base and steps while preserving special hops", () => {
+    expect(joinXPath("", "div[1]")).toBe("/div[1]");
+    expect(joinXPath("/", "span[1]")).toBe("/span[1]");
+    expect(joinXPath("/html/body", "//")).toBe("/html/body//");
+    expect(joinXPath("/html//", "slot[1]")).toBe("/html//slot[1]");
+    expect(joinXPath("/html/body", "")).toBe("/html/body");
+  });
+});
+//# sourceMappingURL=snapshot-xpath-utils.test.js.map

package/dist/esm/tests/snapshot-xpath-utils.test.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../tests/snapshot-xpath-utils.test.ts"],
+  "sourcesContent": ["import type { Protocol } from \"devtools-protocol\";\nimport { describe, expect, it } from \"vitest\";\nimport {\n  buildChildXPathSegments,\n  joinXPath,\n  normalizeXPath,\n  prefixXPath,\n} from \"../lib/v3/understudy/a11y/snapshot/xpathUtils.js\";\nimport { relativizeXPath } from \"../lib/v3/understudy/a11y/snapshot/domTree.js\";\n\ndescribe(\"prefixXPath\", () => {\n  it(\"treats root prefixes as no-op\", () => {\n    expect(prefixXPath(\"/\", \"/div[1]\")).toBe(\"/div[1]\");\n    expect(prefixXPath(\"/\", \"//div[1]\")).toBe(\"//div[1]\");\n  });\n\n  it(\"handles descendant hops and blank children\", () => {\n    expect(prefixXPath(\"/html/body\", \"//slot[1]\")).toBe(\"/html/body//slot[1]\");\n    expect(prefixXPath(\"/html/body\", \"/\")).toBe(\"/html/body\");\n    expect(prefixXPath(\"/html/body/\", \"\")).toBe(\"/html/body\");\n  });\n});\n\ndescribe(\"normalizeXPath\", () => {\n  it(\"strips prefixes, trims whitespace, and enforces absolute roots\", () => {\n    expect(normalizeXPath(\"   xpath=/html/body/ \")).toBe(\"/html/body\");\n    expect(normalizeXPath(\"div/span\")).toBe(\"/div/span\");\n    expect(normalizeXPath(\"\")).toBe(\"\");\n    expect(normalizeXPath()).toBe(\"\");\n  });\n});\n\ndescribe(\"relativizeXPath\", () => {\n  it(\"returns '/' when paths match exactly\", () => {\n    expect(relativizeXPath(\"/html/body\", \"/html/body\")).toBe(\"/\");\n  });\n\n  it(\"omits duplicate prefixes and preserves descendant hops\", () => {\n    expect(relativizeXPath(\"/html/body\", \"/html/body/div[2]\")).toBe(\"/div[2]\");\n    expect(relativizeXPath(\"/html/body\", \"/html/body//shadow-root[1]\")).toBe(\n      \"//shadow-root[1]\",\n    );\n  });\n\n  it(\"falls back to absolute paths outside of the base document\", () => {\n    expect(relativizeXPath(\"/html/body\", \"/head\")).toBe(\"/head\");\n    expect(relativizeXPath(\"/\", \"/html/body\")).toBe(\"/html/body\");\n  });\n});\n\ndescribe(\"buildChildXPathSegments\", () => {\n  it(\"produces positional selectors for each node type\", () => {\n    const makeNode = (\n      nodeType: number,\n      nodeName: string,\n      override?: Partial<Protocol.DOM.Node>,\n    ): Protocol.DOM.Node => ({\n      nodeId: 1,\n      backendNodeId: 1,\n      localName: nodeName.toLowerCase(),\n      nodeValue: \"\",\n      ...override,\n      nodeType,\n      nodeName,\n    });\n\n    const nodes: Protocol.DOM.Node[] = [\n      makeNode(1, \"DIV\"),\n      makeNode(1, \"DIV\"),\n      makeNode(1, \"svg:path\"),\n      makeNode(3, \"#text\"),\n      makeNode(8, \"#comment\"),\n    ];\n\n    expect(buildChildXPathSegments(nodes)).toEqual([\n      \"div[1]\",\n      \"div[2]\",\n      \"*[name()='svg:path'][1]\",\n      \"text()[1]\",\n      \"comment()[1]\",\n    ]);\n  });\n});\n\ndescribe(\"joinXPath\", () => {\n  it(\"joins base and steps while preserving special hops\", () => {\n    expect(joinXPath(\"\", \"div[1]\")).toBe(\"/div[1]\");\n    expect(joinXPath(\"/\", \"span[1]\")).toBe(\"/span[1]\");\n    expect(joinXPath(\"/html/body\", \"//\")).toBe(\"/html/body//\");\n    expect(joinXPath(\"/html//\", \"slot[1]\")).toBe(\"/html//slot[1]\");\n    expect(joinXPath(\"/html/body\", \"\")).toBe(\"/html/body\");\n  });\n});\n"],
+  "mappings": "AACA,SAAS,UAAU,QAAQ,UAAU;AACrC;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;AACP,SAAS,uBAAuB;AAEhC,SAAS,eAAe,MAAM;AAC5B,KAAG,iCAAiC,MAAM;AACxC,WAAO,YAAY,KAAK,SAAS,CAAC,EAAE,KAAK,SAAS;AAClD,WAAO,YAAY,KAAK,UAAU,CAAC,EAAE,KAAK,UAAU;AAAA,EACtD,CAAC;AAED,KAAG,8CAA8C,MAAM;AACrD,WAAO,YAAY,cAAc,WAAW,CAAC,EAAE,KAAK,qBAAqB;AACzE,WAAO,YAAY,cAAc,GAAG,CAAC,EAAE,KAAK,YAAY;AACxD,WAAO,YAAY,eAAe,EAAE,CAAC,EAAE,KAAK,YAAY;AAAA,EAC1D,CAAC;AACH,CAAC;AAED,SAAS,kBAAkB,MAAM;AAC/B,KAAG,kEAAkE,MAAM;AACzE,WAAO,eAAe,uBAAuB,CAAC,EAAE,KAAK,YAAY;AACjE,WAAO,eAAe,UAAU,CAAC,EAAE,KAAK,WAAW;AACnD,WAAO,eAAe,EAAE,CAAC,EAAE,KAAK,EAAE;AAClC,WAAO,eAAe,CAAC,EAAE,KAAK,EAAE;AAAA,EAClC,CAAC;AACH,CAAC;AAED,SAAS,mBAAmB,MAAM;AAChC,KAAG,wCAAwC,MAAM;AAC/C,WAAO,gBAAgB,cAAc,YAAY,CAAC,EAAE,KAAK,GAAG;AAAA,EAC9D,CAAC;AAED,KAAG,0DAA0D,MAAM;AACjE,WAAO,gBAAgB,cAAc,mBAAmB,CAAC,EAAE,KAAK,SAAS;AACzE,WAAO,gBAAgB,cAAc,4BAA4B,CAAC,EAAE;AAAA,MAClE;AAAA,IACF;AAAA,EACF,CAAC;AAED,KAAG,6DAA6D,MAAM;AACpE,WAAO,gBAAgB,cAAc,OAAO,CAAC,EAAE,KAAK,OAAO;AAC3D,WAAO,gBAAgB,KAAK,YAAY,CAAC,EAAE,KAAK,YAAY;AAAA,EAC9D,CAAC;AACH,CAAC;AAED,SAAS,2BAA2B,MAAM;AACxC,KAAG,oDAAoD,MAAM;AAC3D,UAAM,WAAW,CACf,UACA,UACA,cACuB;AAAA,MACvB,QAAQ;AAAA,MACR,eAAe;AAAA,MACf,WAAW,SAAS,YAAY;AAAA,MAChC,WAAW;AAAA,MACX,GAAG;AAAA,MACH;AAAA,MACA;AAAA,IACF;AAEA,UAAM,QAA6B;AAAA,MACjC,SAAS,GAAG,KAAK;AAAA,MACjB,SAAS,GAAG,KAAK;AAAA,MACjB,SAAS,GAAG,UAAU;AAAA,MACtB,SAAS,GAAG,OAAO;AAAA,MACnB,SAAS,GAAG,UAAU;AAAA,IACxB;AAEA,WAAO,wBAAwB,KAAK,CAAC,EAAE,QAAQ;AAAA,MAC7C;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,IACF,CAAC;AAAA,EACH,CAAC;AACH,CAAC;AAED,SAAS,aAAa,MAAM;AAC1B,KAAG,sDAAsD,MAAM;AAC7D,WAAO,UAAU,IAAI,QAAQ,CAAC,EAAE,KAAK,SAAS;AAC9C,WAAO,UAAU,KAAK,SAAS,CAAC,EAAE,KAAK,UAAU;AACjD,WAAO,UAAU,cAAc,IAAI,CAAC,EAAE,KAAK,cAAc;AACzD,WAAO,UAAU,WAAW,SAAS,CAAC,EAAE,KAAK,gBAAgB;AAC7D,WAAO,UAAU,cAAc,EAAE,CAAC,EAAE,KAAK,YAAY;AAAA,EACvD,CAAC;AACH,CAAC;",
+  "names": []
+}