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

package/dist/esm/lib/v3/types/public/sdkErrors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sdkErrors.js","sourceRoot":"","sources":["../../../../../../lib/v3/types/public/sdkErrors.ts"],"names":[],"mappings":"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","sourcesContent":["import { ZodError } from \"zod\";\n// Avoid .js extension so bundlers resolve TS source\nimport { STAGEHAND_VERSION } from \"../../../version.js\";\n\nexport class StagehandError extends Error {\n  public readonly cause?: unknown;\n\n  constructor(message: string, cause?: unknown) {\n    super(message);\n    this.name = this.constructor.name;\n    if (cause !== undefined) {\n      this.cause = cause;\n    }\n  }\n}\n\nexport class StagehandDefaultError extends StagehandError {\n  constructor(error?: unknown) {\n    if (error instanceof Error || error instanceof StagehandError) {\n      super(\n        `\\nHey! We're sorry you ran into an error. \\nStagehand version: ${STAGEHAND_VERSION} \\nIf you need help, please open a Github issue or reach out to us on Discord: https://stagehand.dev/discord\\n\\nFull error:\\n${error.message}`,\n      );\n    }\n  }\n}\n\nexport class StagehandEnvironmentError extends StagehandError {\n  constructor(\n    currentEnvironment: string,\n    requiredEnvironment: string,\n    feature: string,\n  ) {\n    super(\n      `You seem to be setting the current environment to ${currentEnvironment}.` +\n        `Ensure the environment is set to ${requiredEnvironment} if you want to use ${feature}.`,\n    );\n  }\n}\n\nexport class MissingEnvironmentVariableError extends StagehandError {\n  constructor(missingEnvironmentVariable: string, feature: string) {\n    super(\n      `${missingEnvironmentVariable} is required to use ${feature}.` +\n        `Please set ${missingEnvironmentVariable} in your environment.`,\n    );\n  }\n}\n\nexport class UnsupportedModelError extends StagehandError {\n  constructor(supportedModels: string[], feature?: string) {\n    const message = feature\n      ? `${feature} requires a valid model.`\n      : `Unsupported model.`;\n\n    const guidance =\n      `\\n\\nPlease use the provider/model format (e.g., \"openai/gpt-4o\", \"anthropic/claude-sonnet-4-5\", \"google/gemini-3-flash-preview\").` +\n      `\\n\\nFor a complete list of supported models and providers, see: https://docs.stagehand.dev/v3/configuration/models#configuration-setup`;\n\n    super(`${message}${guidance}`);\n  }\n}\n\nexport class UnsupportedModelProviderError extends StagehandError {\n  constructor(supportedProviders: string[], feature?: string) {\n    super(\n      feature\n        ? `${feature} requires one of the following model providers: ${supportedProviders}`\n        : `please use one of the supported model providers: ${supportedProviders}`,\n    );\n  }\n}\n\nexport class UnsupportedAISDKModelProviderError extends StagehandError {\n  constructor(provider: string, supportedProviders: string[]) {\n    super(\n      `${provider} is not currently supported for aiSDK. please use one of the supported model providers: ${supportedProviders}`,\n    );\n  }\n}\n\nexport class InvalidAISDKModelFormatError extends StagehandError {\n  constructor(modelName: string) {\n    super(\n      `${modelName} does not follow correct format for specifying aiSDK models. Please define your model as 'provider/model-name'. For example: \\`model: 'openai/gpt-4o-mini'\\``,\n    );\n  }\n}\n\nexport class StagehandNotInitializedError extends StagehandError {\n  constructor(prop: string) {\n    super(\n      `You seem to be calling \\`${prop}\\` on a page in an uninitialized \\`Stagehand\\` object. ` +\n        `Ensure you are running \\`await stagehand.init()\\` on the Stagehand object before ` +\n        `referencing the \\`page\\` object.`,\n    );\n  }\n}\n\nexport class BrowserbaseSessionNotFoundError extends StagehandError {\n  constructor() {\n    super(\"No Browserbase session ID found\");\n  }\n}\n\nexport class CaptchaTimeoutError extends StagehandError {\n  constructor() {\n    super(\"Captcha timeout\");\n  }\n}\n\nexport class MissingLLMConfigurationError extends StagehandError {\n  constructor() {\n    super(\n      \"No LLM API key or LLM Client configured. An LLM API key or a custom LLM Client \" +\n        \"is required to use act, extract, or observe.\",\n    );\n  }\n}\n\nexport class HandlerNotInitializedError extends StagehandError {\n  constructor(handlerType: string) {\n    super(`${handlerType} handler not initialized`);\n  }\n}\n\nexport class StagehandInvalidArgumentError extends StagehandError {\n  constructor(message: string) {\n    super(`InvalidArgumentError: ${message}`);\n  }\n}\n\nexport class CookieValidationError extends StagehandError {\n  constructor(message: string) {\n    super(message);\n  }\n}\n\nexport class CookieSetError extends StagehandError {\n  constructor(message: string) {\n    super(message);\n  }\n}\n\nexport class StagehandElementNotFoundError extends StagehandError {\n  constructor(xpaths: string[]) {\n    super(`Could not find an element for the given xPath(s): ${xpaths}`);\n  }\n}\n\nexport class AgentScreenshotProviderError extends StagehandError {\n  constructor(message: string) {\n    super(`ScreenshotProviderError: ${message}`);\n  }\n}\n\nexport class StagehandMissingArgumentError extends StagehandError {\n  constructor(message: string) {\n    super(`MissingArgumentError: ${message}`);\n  }\n}\n\nexport class CreateChatCompletionResponseError extends StagehandError {\n  constructor(message: string) {\n    super(`CreateChatCompletionResponseError: ${message}`);\n  }\n}\n\nexport class StagehandEvalError extends StagehandError {\n  constructor(message: string) {\n    super(`StagehandEvalError: ${message}`);\n  }\n}\n\nexport class StagehandDomProcessError extends StagehandError {\n  constructor(message: string) {\n    super(`Error Processing Dom: ${message}`);\n  }\n}\n\nexport class StagehandLocatorError extends StagehandError {\n  constructor(action: string, selector: string, message: string) {\n    super(\n      `Error ${action} Element with selector: ${selector} Reason: ${message}`,\n    );\n  }\n}\n\nexport class StagehandClickError extends StagehandError {\n  constructor(message: string, selector: string) {\n    super(\n      `Error Clicking Element with selector: ${selector} Reason: ${message}`,\n    );\n  }\n}\n\nexport class LLMResponseError extends StagehandError {\n  constructor(primitive: string, message: string) {\n    super(`${primitive} LLM response error: ${message}`);\n  }\n}\n\nexport class StagehandIframeError extends StagehandError {\n  constructor(frameUrl: string, message: string) {\n    super(\n      `Unable to resolve frameId for iframe with URL: ${frameUrl} Full error: ${message}`,\n    );\n  }\n}\n\nexport class ContentFrameNotFoundError extends StagehandError {\n  constructor(selector: string) {\n    super(`Unable to obtain a content frame for selector: ${selector}`);\n  }\n}\n\nexport class XPathResolutionError extends StagehandError {\n  constructor(xpath: string) {\n    super(`XPath \"${xpath}\" does not resolve in the current page or frames`);\n  }\n}\n\nexport class ExperimentalApiConflictError extends StagehandError {\n  constructor() {\n    super(\n      \"`experimental` mode cannot be used together with the Stagehand API. \" +\n        \"To use experimental features, set experimental: true and disableAPI: true in the stagehand constructor. \" +\n        \"To use the Stagehand API, set experimental: false and disableAPI: false (or omit it) in the stagehand constructor.\",\n    );\n  }\n}\n\nexport class ExperimentalNotConfiguredError extends StagehandError {\n  constructor(featureName: string) {\n    super(`Feature \"${featureName}\" is an experimental feature, and cannot be configured when disableAPI: false.\n    Please set experimental: true and disableAPI: true in the stagehand constructor to use this feature.\n    If you wish to use the Stagehand API, please ensure ${featureName} is not defined in your function call,\n    and set experimental: false, disableAPI: false (or omit it) in the Stagehand constructor.`);\n  }\n}\n\nexport class CuaModelRequiredError extends StagehandError {\n  constructor(availableModels: readonly string[]) {\n    super(\n      `To use the computer use agent (CUA), please provide a CUA model in the agent constructor or stagehand config. ` +\n        `Try one of our supported CUA models: ${availableModels.join(\", \")}`,\n    );\n  }\n}\n\nexport class ZodSchemaValidationError extends Error {\n  constructor(\n    public readonly received: unknown,\n    public readonly issues: ReturnType<ZodError[\"format\"]>,\n  ) {\n    super(`Zod schema validation failed\n\n— Received —\n${JSON.stringify(received, null, 2)}\n\n— Issues —\n${JSON.stringify(issues, null, 2)}`);\n    this.name = \"ZodSchemaValidationError\";\n  }\n}\n\nexport class StagehandInitError extends StagehandError {\n  constructor(message: string) {\n    super(message);\n  }\n}\n\nexport class MCPConnectionError extends StagehandError {\n  public readonly serverUrl: string;\n  public readonly originalError: unknown;\n\n  constructor(serverUrl: string, originalError: unknown) {\n    const errorMessage =\n      originalError instanceof Error\n        ? originalError.message\n        : String(originalError);\n\n    super(\n      `Failed to connect to MCP server at \"${serverUrl}\". ${errorMessage}. ` +\n        `Please verify the server URL is correct and the server is running.`,\n    );\n\n    this.serverUrl = serverUrl;\n    this.originalError = originalError;\n  }\n}\n\nexport class StagehandShadowRootMissingError extends StagehandError {\n  constructor(detail?: string) {\n    super(\n      `No shadow root present on the resolved host` +\n        (detail ? `: ${detail}` : \"\"),\n    );\n  }\n}\n\nexport class StagehandShadowSegmentEmptyError extends StagehandError {\n  constructor() {\n    super(`Empty selector segment after shadow-DOM hop (\"//\")`);\n  }\n}\n\nexport class StagehandShadowSegmentNotFoundError extends StagehandError {\n  constructor(segment: string, hint?: string) {\n    super(\n      `Shadow segment '${segment}' matched no element inside shadow root` +\n        (hint ? ` ${hint}` : \"\"),\n    );\n  }\n}\n\nexport class ElementNotVisibleError extends StagehandError {\n  constructor(selector: string) {\n    super(`Element not visible (no box model): ${selector}`);\n  }\n}\n\nexport class ResponseBodyError extends StagehandError {\n  constructor(message: string) {\n    super(`Failed to retrieve response body: ${message}`);\n  }\n}\n\nexport class ResponseParseError extends StagehandError {\n  constructor(message: string) {\n    super(`Failed to parse response: ${message}`);\n  }\n}\n\nexport class TimeoutError extends StagehandError {\n  constructor(operation: string, timeoutMs: number) {\n    super(`${operation} timed out after ${timeoutMs}ms`);\n  }\n}\n\nexport class ActTimeoutError extends TimeoutError {\n  constructor(timeoutMs: number) {\n    super(\"act()\", timeoutMs);\n    this.name = \"ActTimeoutError\";\n  }\n}\n\nexport class ExtractTimeoutError extends TimeoutError {\n  constructor(timeoutMs: number) {\n    super(\"extract()\", timeoutMs);\n    this.name = \"ExtractTimeoutError\";\n  }\n}\n\nexport class ObserveTimeoutError extends TimeoutError {\n  constructor(timeoutMs: number) {\n    super(\"observe()\", timeoutMs);\n    this.name = \"ObserveTimeoutError\";\n  }\n}\n\nexport class PageNotFoundError extends StagehandError {\n  constructor(identifier: string) {\n    super(`No Page found for ${identifier}`);\n  }\n}\n\nexport class ConnectionTimeoutError extends StagehandError {\n  constructor(message: string) {\n    super(`Connection timeout: ${message}`);\n  }\n}\n\nexport class StreamingCallbacksInNonStreamingModeError extends StagehandError {\n  public readonly invalidCallbacks: string[];\n\n  constructor(invalidCallbacks: string[]) {\n    super(\n      `Streaming-only callback(s) \"${invalidCallbacks.join('\", \"')}\" cannot be used in non-streaming mode. ` +\n        `Set 'stream: true' in AgentConfig to use these callbacks.`,\n    );\n    this.invalidCallbacks = invalidCallbacks;\n  }\n}\n\nexport class AgentAbortError extends StagehandError {\n  public readonly reason: string;\n\n  constructor(reason?: string) {\n    const message = reason\n      ? `Agent execution was aborted: ${reason}`\n      : \"Agent execution was aborted\";\n    super(message);\n    this.reason = reason || \"aborted\";\n  }\n}\n\nexport class StagehandClosedError extends StagehandError {\n  constructor() {\n    super(\"Stagehand session was closed\");\n  }\n}\n\nexport class CdpConnectionClosedError extends StagehandError {\n  constructor(reason: string) {\n    super(`CDP connection closed: ${reason}`);\n  }\n}\n\nexport class StagehandSetExtraHTTPHeadersError extends StagehandError {\n  public readonly failures: string[];\n\n  constructor(failures: string[]) {\n    super(\n      `setExtraHTTPHeaders failed for ${failures.length} session(s): ${failures.join(\", \")}`,\n    );\n    this.failures = failures;\n  }\n}\n\nexport class StagehandSnapshotError extends StagehandError {\n  constructor(cause?: unknown) {\n    const suffix =\n      cause instanceof Error\n        ? `: ${cause.message}`\n        : cause\n          ? `: ${String(cause)}`\n          : \"\";\n    super(`error taking snapshot${suffix}`, cause);\n  }\n}\n\nexport class UnderstudyCommandException extends StagehandError {\n  constructor(message: string, cause?: unknown) {\n    super(message, cause);\n    this.name = \"UnderstudyCommandException\";\n  }\n}\n"]}

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

@@ -0,0 +1,15 @@
+import type { Protocol } from "devtools-protocol";
+import type { CDPSessionLike } from "../../cdp.js";
+import type { A11yNode, A11yOptions, AccessibilityTreeResult } from "../../../types/private/snapshot.js";
+/**
+ * Fetch and prune the accessibility tree for a frame, optionally scoping the
+ * output to a selector root for faster targeted snapshots.
+ */
+export declare function a11yForFrame(session: CDPSessionLike, frameId: string | undefined, opts: A11yOptions): Promise<AccessibilityTreeResult>;
+export declare function decorateRoles(nodes: Protocol.Accessibility.AXNode[], opts: A11yOptions): A11yNode[];
+export declare function buildHierarchicalTree(nodes: A11yNode[], opts: A11yOptions): Promise<{
+    tree: A11yNode[];
+}>;
+export declare function isStructural(role: string): boolean;
+export declare function extractUrlFromAXNode(ax: Protocol.Accessibility.AXNode): string | undefined;
+export declare function removeRedundantStaticTextChildren(parent: A11yNode, children: A11yNode[]): A11yNode[];

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

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

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

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

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

@@ -0,0 +1,8 @@
+import { Page } from "../../page.js";
+/**
+ * Compute the absolute XPath for the currently focused element.
+ * - Detects which frame has focus via document.hasFocus().
+ * - Finds the deepest activeElement (dives into shadow DOM).
+ * - Builds an absolute, cross-frame XPath by prefixing iframe hosts.
+ */
+export declare function computeActiveElementXpath(page: Page): Promise<string | null>;

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

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

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

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

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

@@ -0,0 +1,77 @@
+import { Page } from "../../page.js";
+import type { FrameContext, FrameDomMaps, HybridSnapshot, SnapshotOptions, SessionDomIndex } from "../../../types/private/index.js";
+/**
+ * Capture a hybrid DOM + Accessibility snapshot for the provided page.
+ *
+ * Flow overview:
+ * 1. (Optional) Scope directly to a requested selector. We walk iframe hops to
+ *    find the owning frame, build just that frame’s DOM + AX tree, and bail out
+ *    early when the subtree satisfies the caller.
+ * 2. Build DOM indexes for every unique CDP session. DOM.getDocument is called
+ *    once per session and hydrated so per-frame slices can share the result.
+ * 3. Slice each frame’s DOM data from its session index and fetch its AX tree.
+ *    This yields relative XPath/tag/url maps for the document rooted at that frame.
+ * 4. Walk the frame tree to compute absolute iframe prefixes. Every child frame
+ *    needs the XPath of the iframe element that hosts it so we can prefix maps.
+ * 5. Merge all per-frame results into global combined maps and stitch the text
+ *    outline. The final payload mirrors the legacy shape but is built in layers.
+ *
+ * Each numbered block below references the step above for easier debugging.
+ */
+export declare function captureHybridSnapshot(page: Page, options?: SnapshotOptions): Promise<HybridSnapshot>;
+/**
+ * Snapshot the current frame tree so downstream helpers have consistent topology
+ * without re-querying CDP. The map is intentionally shallow (frameId → parentId)
+ * so it is serializable/testable without holding on to CDP handles.
+ */
+export declare function buildFrameContext(page: Page): FrameContext;
+/**
+ * Step 1 – scoped snapshot fast-path. If a selector is provided we try to:
+ *  1) Resolve the selector (XPath or CSS) across iframes.
+ *  2) Build DOM + AX data only for the owning frame.
+ *  3) Bail out early when the selector's subtree satisfies the request.
+ *
+ * Returns `null` when scoping fails (e.g., selector miss) so the caller can
+ * fall back to the full multi-frame snapshot.
+ */
+export declare function tryScopedSnapshot(page: Page, options: SnapshotOptions | undefined, context: FrameContext, pierce: boolean): Promise<HybridSnapshot | null>;
+/**
+ * Step 2 – call DOM.getDocument once per unique CDP session and hydrate the
+ * result so per-frame slices can share the structure. We key by session id
+ * because same process iframes live inside the same session.
+ */
+export declare function buildSessionIndexes(page: Page, frames: string[], pierce: boolean): Promise<Map<string, SessionDomIndex>>;
+/**
+ * Step 3 – derive per-frame DOM maps and accessibility outlines.
+ * Each frame:
+ *  - slices the shared session index down to its document root
+ *  - builds frame-aware encoded ids (ordinal-backendNodeId)
+ *  - collects tag/xpath/scrollability maps for DOM-based lookups
+ *  - fetches its AX tree to produce outlines and URL maps
+ */
+export declare function collectPerFrameMaps(page: Page, context: FrameContext, sessionToIndex: Map<string, SessionDomIndex>, options: SnapshotOptions | undefined, pierce: boolean, frameIds: string[]): Promise<{
+    perFrameMaps: Map<string, FrameDomMaps>;
+    perFrameOutlines: Array<{
+        frameId: string;
+        outline: string;
+    }>;
+}>;
+/**
+ * Step 4 – walk the frame tree (parent-first) to compute absolute prefixes for
+ * every frame. The prefix is the absolute XPath of the iframe element hosting
+ * the frame, so we can later convert relative XPaths into cross-frame ones.
+ */
+export declare function computeFramePrefixes(page: Page, context: FrameContext, perFrameMaps: Map<string, FrameDomMaps>, frameIds: string[]): Promise<{
+    absPrefix: Map<string, string>;
+    iframeHostEncByChild: Map<string, string>;
+}>;
+/**
+ * Step 5 – merge per-frame maps into the combined snapshot payload. We prefix
+ * each frame's relative XPaths with the absolute path collected in step 4,
+ * merge URL maps, and stitch text outlines by nesting child trees under the
+ * encoded id of their parent iframe host.
+ */
+export declare function mergeFramesIntoSnapshot(context: FrameContext, perFrameMaps: Map<string, FrameDomMaps>, perFrameOutlines: Array<{
+    frameId: string;
+    outline: string;
+}>, absPrefix: Map<string, string>, iframeHostEncByChild: Map<string, string>, frameIds: string[]): HybridSnapshot;