@browserbasehq/orca 3.0.9-alpha-3 → 3.1.0-headers

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

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

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

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

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

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

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

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveXpathForLocation = exports.diffCombinedTrees = exports.computeActiveElementXpath = exports.captureHybridSnapshot = void 0;
+var capture_js_1 = require("./capture.js");
+Object.defineProperty(exports, "captureHybridSnapshot", { enumerable: true, get: function () { return capture_js_1.captureHybridSnapshot; } });
+var activeElement_js_1 = require("./activeElement.js");
+Object.defineProperty(exports, "computeActiveElementXpath", { enumerable: true, get: function () { return activeElement_js_1.computeActiveElementXpath; } });
+var treeFormatUtils_js_1 = require("./treeFormatUtils.js");
+Object.defineProperty(exports, "diffCombinedTrees", { enumerable: true, get: function () { return treeFormatUtils_js_1.diffCombinedTrees; } });
+var coordinateResolver_js_1 = require("./coordinateResolver.js");
+Object.defineProperty(exports, "resolveXpathForLocation", { enumerable: true, get: function () { return coordinateResolver_js_1.resolveXpathForLocation; } });
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../../../lib/v3/understudy/a11y/snapshot/index.ts"],"names":[],"mappings":";;;AAAA,2CAAqD;AAA5C,mHAAA,qBAAqB,OAAA;AAC9B,uDAA+D;AAAtD,6HAAA,yBAAyB,OAAA;AAClC,2DAAyD;AAAhD,uHAAA,iBAAiB,OAAA;AAC1B,iEAAkE;AAAzD,gIAAA,uBAAuB,OAAA","sourcesContent":["export { captureHybridSnapshot } from \"./capture.js\";\nexport { computeActiveElementXpath } from \"./activeElement.js\";\nexport { diffCombinedTrees } from \"./treeFormatUtils.js\";\nexport { resolveXpathForLocation } from \"./coordinateResolver.js\";\n"]}

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

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

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"sessions.js","sourceRoot":"","sources":["../../../../../../../lib/v3/understudy/a11y/snapshot/sessions.ts"],"names":[],"mappings":";;AAWA,oCAEC;AAOD,sCAUC;AA1BD;;;;GAIG;AAEH,uEAAuE;AACvE,SAAgB,YAAY,CAAC,IAAU,EAAE,OAAe;IACtD,OAAO,IAAI,CAAC,kBAAkB,CAAC,OAAO,CAAC,CAAC;AAC1C,CAAC;AAED;;;;GAIG;AACH,SAAgB,aAAa,CAC3B,IAAU,EACV,aAA+B,EAC/B,OAAe;IAEf,MAAM,QAAQ,GAAG,aAAa,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,IAAI,CAAC;IACpD,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,OAAO,IAAI,CAAC,kBAAkB,CAAC,OAAO,CAAC,CAAC;IAC1C,CAAC;IACD,OAAO,IAAI,CAAC,kBAAkB,CAAC,QAAQ,CAAC,CAAC;AAC3C,CAAC","sourcesContent":["import type { CDPSessionLike } from \"../../cdp.js\";\nimport { Page } from \"../../page.js\";\nimport type { FrameParentIndex } from \"../../../types/private/snapshot.js\";\n\n/**\n * Session helpers ensure DOM lookups are always executed against the session\n * that actually owns a frame. Keeping this logic centralized prevents subtle\n * bugs when OOPIF adoption changes session ownership mid-capture.\n */\n\n/** Return the owning session for a frame as registered on the Page. */\nexport function ownerSession(page: Page, frameId: string): CDPSessionLike {\n  return page.getSessionForFrame(frameId);\n}\n\n/**\n * DOM.getFrameOwner must be called against the parent frame's session.\n * This helper hides the lookup (including main-frame fallback) so callers\n * always reach for the correct connection.\n */\nexport function parentSession(\n  page: Page,\n  parentByFrame: FrameParentIndex,\n  frameId: string,\n): CDPSessionLike {\n  const parentId = parentByFrame.get(frameId) ?? null;\n  if (!parentId) {\n    return page.getSessionForFrame(frameId);\n  }\n  return page.getSessionForFrame(parentId);\n}\n"]}

package/dist/cjs/lib/v3/understudy/a11y/snapshot/treeFormatUtils.d.ts

@@ -0,0 +1,28 @@
+import type { A11yNode } from "../../../types/private/snapshot.js";
+/**
+ * Render a formatted outline (with encoded ids) for the accessibility tree.
+ * Keeps indentation logic shared between modules so unit tests can cover these
+ * pure formatting helpers without a full snapshot pipeline.
+ */
+export declare function formatTreeLine(node: A11yNode, level?: number): string;
+/**
+ * Inject each child frame outline under the parent's iframe node line.
+ * Keys in `idToTree` are the parent's iframe encoded ids.
+ */
+export declare function injectSubtrees(rootOutline: string, idToTree: Map<string, string>): string;
+export declare function indentBlock(block: string, indent: string): string;
+/**
+ * Return the lines that appear in `nextTree` but not in `prevTree`.
+ * Comparison is done line-by-line, ignoring leading whitespace in both trees.
+ * The returned block is re-indented so the minimal indent becomes column 0.
+ */
+export declare function diffCombinedTrees(prevTree: string, nextTree: string): string;
+/**
+ * Remove whitespace noise and invisible code points before rendering names.
+ */
+export declare function cleanText(input: string): string;
+/**
+ * Collapse all whitespace runs in a string to a single space without trimming.
+ * Exported for pruning routines that need the same normalization.
+ */
+export declare function normaliseSpaces(s: string): string;

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

@@ -0,0 +1,143 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatTreeLine = formatTreeLine;
+exports.injectSubtrees = injectSubtrees;
+exports.indentBlock = indentBlock;
+exports.diffCombinedTrees = diffCombinedTrees;
+exports.cleanText = cleanText;
+exports.normaliseSpaces = normaliseSpaces;
+/**
+ * Render a formatted outline (with encoded ids) for the accessibility tree.
+ * Keeps indentation logic shared between modules so unit tests can cover these
+ * pure formatting helpers without a full snapshot pipeline.
+ */
+function formatTreeLine(node, level = 0) {
+    const indent = "  ".repeat(level);
+    const labelId = node.encodedId ?? node.nodeId;
+    const label = `[${labelId}] ${node.role}${node.name ? `: ${cleanText(node.name)}` : ""}`;
+    const kids = node.children?.map((c) => formatTreeLine(c, level + 1)).join("\n") ?? "";
+    return kids ? `${indent}${label}\n${kids}` : `${indent}${label}`;
+}
+/**
+ * Inject each child frame outline under the parent's iframe node line.
+ * Keys in `idToTree` are the parent's iframe encoded ids.
+ */
+function injectSubtrees(rootOutline, idToTree) {
+    const out = [];
+    const visited = new Set();
+    const stack = [{ lines: rootOutline.split("\n"), i: 0 }];
+    while (stack.length) {
+        const top = stack[stack.length - 1];
+        if (top.i >= top.lines.length) {
+            stack.pop();
+            continue;
+        }
+        const raw = top.lines[top.i++];
+        out.push(raw);
+        const indent = raw.match(/^(\s*)/)?.[1] ?? "";
+        const content = raw.slice(indent.length);
+        const m = content.match(/^\[([^\]]+)]/);
+        if (!m)
+            continue;
+        const encId = m[1];
+        const childOutline = idToTree.get(encId);
+        if (!childOutline || visited.has(encId))
+            continue;
+        visited.add(encId);
+        const fullyInjectedChild = injectSubtrees(childOutline, idToTree);
+        out.push(indentBlock(fullyInjectedChild.trimEnd(), indent + "  "));
+    }
+    return out.join("\n");
+}
+function indentBlock(block, indent) {
+    if (!block)
+        return "";
+    return block
+        .split("\n")
+        .map((line) => (line.length ? indent + line : indent + line))
+        .join("\n");
+}
+/**
+ * Return the lines that appear in `nextTree` but not in `prevTree`.
+ * Comparison is done line-by-line, ignoring leading whitespace in both trees.
+ * The returned block is re-indented so the minimal indent becomes column 0.
+ */
+function diffCombinedTrees(prevTree, nextTree) {
+    const prevSet = new Set((prevTree || "")
+        .split("\n")
+        .map((l) => l.trim())
+        .filter((l) => l.length > 0));
+    const nextLines = (nextTree || "").split("\n");
+    const added = [];
+    for (const line of nextLines) {
+        const core = line.trim();
+        if (!core)
+            continue;
+        if (!prevSet.has(core))
+            added.push(line);
+    }
+    if (added.length === 0)
+        return "";
+    let minIndent = Infinity;
+    for (const l of added) {
+        if (!l.trim())
+            continue;
+        const m = l.match(/^\s*/);
+        const indentLen = m ? m[0].length : 0;
+        if (indentLen < minIndent)
+            minIndent = indentLen;
+    }
+    if (!isFinite(minIndent))
+        minIndent = 0;
+    const out = added.map((l) => l.length >= minIndent ? l.slice(minIndent) : l);
+    return out.join("\n");
+}
+/**
+ * Remove whitespace noise and invisible code points before rendering names.
+ */
+function cleanText(input) {
+    const PUA_START = 0xe000;
+    const PUA_END = 0xf8ff;
+    const NBSP = new Set([0x00a0, 0x202f, 0x2007, 0xfeff]);
+    let out = "";
+    let prevSpace = false;
+    for (let i = 0; i < input.length; i++) {
+        const code = input.charCodeAt(i);
+        if (code >= PUA_START && code <= PUA_END)
+            continue;
+        if (NBSP.has(code)) {
+            if (!prevSpace) {
+                out += " ";
+                prevSpace = true;
+            }
+            continue;
+        }
+        out += input[i];
+        prevSpace = input[i] === " ";
+    }
+    return out.trim();
+}
+/**
+ * Collapse all whitespace runs in a string to a single space without trimming.
+ * Exported for pruning routines that need the same normalization.
+ */
+function normaliseSpaces(s) {
+    let out = "";
+    let inWs = false;
+    for (let i = 0; i < s.length; i++) {
+        const ch = s[i];
+        const isWs = /\s/.test(ch);
+        if (isWs) {
+            if (!inWs) {
+                out += " ";
+                inWs = true;
+            }
+        }
+        else {
+            out += ch;
+            inWs = false;
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=treeFormatUtils.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"treeFormatUtils.js","sourceRoot":"","sources":["../../../../../../../lib/v3/understudy/a11y/snapshot/treeFormatUtils.ts"],"names":[],"mappings":"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","sourcesContent":["import type { A11yNode } from \"../../../types/private/snapshot.js\";\n\n/**\n * Render a formatted outline (with encoded ids) for the accessibility tree.\n * Keeps indentation logic shared between modules so unit tests can cover these\n * pure formatting helpers without a full snapshot pipeline.\n */\nexport function formatTreeLine(node: A11yNode, level = 0): string {\n  const indent = \"  \".repeat(level);\n  const labelId = node.encodedId ?? node.nodeId;\n  const label = `[${labelId}] ${node.role}${node.name ? `: ${cleanText(node.name)}` : \"\"}`;\n  const kids =\n    node.children?.map((c) => formatTreeLine(c, level + 1)).join(\"\\n\") ?? \"\";\n  return kids ? `${indent}${label}\\n${kids}` : `${indent}${label}`;\n}\n\n/**\n * Inject each child frame outline under the parent's iframe node line.\n * Keys in `idToTree` are the parent's iframe encoded ids.\n */\nexport function injectSubtrees(\n  rootOutline: string,\n  idToTree: Map<string, string>,\n): string {\n  type Frame = { lines: string[]; i: number };\n  const out: string[] = [];\n  const visited = new Set<string>();\n  const stack: Frame[] = [{ lines: rootOutline.split(\"\\n\"), i: 0 }];\n\n  while (stack.length) {\n    const top = stack[stack.length - 1];\n    if (top.i >= top.lines.length) {\n      stack.pop();\n      continue;\n    }\n\n    const raw = top.lines[top.i++];\n    out.push(raw);\n\n    const indent = raw.match(/^(\\s*)/)?.[1] ?? \"\";\n    const content = raw.slice(indent.length);\n\n    const m = content.match(/^\\[([^\\]]+)]/);\n    if (!m) continue;\n\n    const encId = m[1]!;\n    const childOutline = idToTree.get(encId);\n    if (!childOutline || visited.has(encId)) continue;\n\n    visited.add(encId);\n\n    const fullyInjectedChild = injectSubtrees(childOutline, idToTree);\n    out.push(indentBlock(fullyInjectedChild.trimEnd(), indent + \"  \"));\n  }\n\n  return out.join(\"\\n\");\n}\n\nexport function indentBlock(block: string, indent: string): string {\n  if (!block) return \"\";\n  return block\n    .split(\"\\n\")\n    .map((line) => (line.length ? indent + line : indent + line))\n    .join(\"\\n\");\n}\n\n/**\n * Return the lines that appear in `nextTree` but not in `prevTree`.\n * Comparison is done line-by-line, ignoring leading whitespace in both trees.\n * The returned block is re-indented so the minimal indent becomes column 0.\n */\nexport function diffCombinedTrees(prevTree: string, nextTree: string): string {\n  const prevSet = new Set(\n    (prevTree || \"\")\n      .split(\"\\n\")\n      .map((l) => l.trim())\n      .filter((l) => l.length > 0),\n  );\n\n  const nextLines = (nextTree || \"\").split(\"\\n\");\n  const added: string[] = [];\n  for (const line of nextLines) {\n    const core = line.trim();\n    if (!core) continue;\n    if (!prevSet.has(core)) added.push(line);\n  }\n\n  if (added.length === 0) return \"\";\n\n  let minIndent = Infinity;\n  for (const l of added) {\n    if (!l.trim()) continue;\n    const m = l.match(/^\\s*/);\n    const indentLen = m ? m[0]!.length : 0;\n    if (indentLen < minIndent) minIndent = indentLen;\n  }\n  if (!isFinite(minIndent)) minIndent = 0;\n\n  const out = added.map((l) =>\n    l.length >= minIndent ? l.slice(minIndent) : l,\n  );\n  return out.join(\"\\n\");\n}\n\n/**\n * Remove whitespace noise and invisible code points before rendering names.\n */\nexport function cleanText(input: string): string {\n  const PUA_START = 0xe000;\n  const PUA_END = 0xf8ff;\n  const NBSP = new Set<number>([0x00a0, 0x202f, 0x2007, 0xfeff]);\n\n  let out = \"\";\n  let prevSpace = false;\n  for (let i = 0; i < input.length; i++) {\n    const code = input.charCodeAt(i);\n    if (code >= PUA_START && code <= PUA_END) continue;\n    if (NBSP.has(code)) {\n      if (!prevSpace) {\n        out += \" \";\n        prevSpace = true;\n      }\n      continue;\n    }\n    out += input[i];\n    prevSpace = input[i] === \" \";\n  }\n  return out.trim();\n}\n\n/**\n * Collapse all whitespace runs in a string to a single space without trimming.\n * Exported for pruning routines that need the same normalization.\n */\nexport function normaliseSpaces(s: string): string {\n  let out = \"\";\n  let inWs = false;\n  for (let i = 0; i < s.length; i++) {\n    const ch = s[i]!;\n    const isWs = /\\s/.test(ch);\n    if (isWs) {\n      if (!inWs) {\n        out += \" \";\n        inWs = true;\n      }\n    } else {\n      out += ch;\n      inWs = false;\n    }\n  }\n  return out;\n}\n"]}

package/dist/cjs/lib/v3/understudy/a11y/snapshot/xpathUtils.d.ts

@@ -0,0 +1,26 @@
+import type { Protocol } from "devtools-protocol";
+import type { CDPSessionLike } from "../../cdp.js";
+/**
+ * Build the absolute XPath for a node by walking through every iframe host
+ * we've traversed so far followed by the leaf backend node.
+ */
+export declare function buildAbsoluteXPathFromChain(chain: Array<{
+    parentSession: CDPSessionLike;
+    iframeBackendNodeId: number;
+}>, leafSession: CDPSessionLike, leafBackendNodeId: number): Promise<string | null>;
+/**
+ * Resolve a backend node to an absolute XPath within the provided session.
+ * The CDP Runtime is used so we can invoke a small helper that walks the DOM.
+ */
+export declare function absoluteXPathForBackendNode(session: CDPSessionLike, backendNodeId: number): Promise<string | null>;
+/**
+ * Prefix `child` XPath with an absolute iframe path `parentAbs`.
+ * Handles root slashes and shadow hops (“//”) cleanly.
+ */
+export declare function prefixXPath(parentAbs: string, child: string): string;
+/** Normalize an XPath: strip `xpath=`, ensure leading '/', remove trailing '/'. */
+export declare function normalizeXPath(x?: string): string;
+/** Build per-sibling XPath steps for DOM traversal. */
+export declare function buildChildXPathSegments(kids: Protocol.DOM.Node[]): string[];
+/** Join two XPath fragments while preserving special shadow-root hops. */
+export declare function joinXPath(base: string, step: string): string;