@browserbasehq/orca 3.0.9-alpha-4 → 3.1.0-patch.1

package/dist/cjs/lib/v3/types/public/apiErrors.d.ts

@@ -0,0 +1,18 @@
+export declare class StagehandAPIError extends Error {
+    constructor(message: string);
+}
+export declare class StagehandAPIUnauthorizedError extends StagehandAPIError {
+    constructor(message?: string);
+}
+export declare class StagehandHttpError extends StagehandAPIError {
+    constructor(message: string);
+}
+export declare class StagehandServerError extends StagehandAPIError {
+    constructor(message: string);
+}
+export declare class StagehandResponseBodyError extends StagehandAPIError {
+    constructor();
+}
+export declare class StagehandResponseParseError extends StagehandAPIError {
+    constructor(message: string);
+}

package/dist/cjs/lib/v3/types/public/index.d.ts

@@ -0,0 +1,12 @@
+export * from "./agent.js";
+export * as Api from "./api.js";
+export * from "./apiErrors.js";
+export * from "./logs.js";
+export * from "./methods.js";
+export * from "./metrics.js";
+export * from "./model.js";
+export * from "./options.js";
+export * from "./page.js";
+export * from "./sdkErrors.js";
+export { AISdkClient } from "../../external_clients/aisdk.js";
+export { CustomOpenAIClient } from "../../external_clients/customOpenAI.js";

package/dist/cjs/lib/v3/types/public/locator.d.ts

@@ -0,0 +1,9 @@
+import { Buffer } from "buffer";
+export type MouseButton = "left" | "right" | "middle";
+export interface SetInputFilePayload {
+    name: string;
+    mimeType?: string;
+    buffer: ArrayBuffer | Uint8Array | Buffer | string;
+    lastModified?: number;
+}
+export type SetInputFilesArgument = string | string[] | SetInputFilePayload | SetInputFilePayload[];

package/dist/cjs/lib/v3/types/public/logs.d.ts

@@ -0,0 +1,23 @@
+export type LogLevel = 0 | 1 | 2;
+/**
+ * Mapping between numeric log levels and their names
+ *
+ * 0 - error/warn - Critical issues or important warnings
+ * 1 - info - Standard information messages
+ * 2 - debug - Detailed information for debugging
+ */
+export declare const LOG_LEVEL_NAMES: Record<LogLevel, string>;
+export type LogLine = {
+    id?: string;
+    category?: string;
+    message: string;
+    level?: LogLevel;
+    timestamp?: string;
+    auxiliary?: {
+        [key: string]: {
+            value: string;
+            type: "object" | "string" | "html" | "integer" | "float" | "boolean";
+        };
+    };
+};
+export type Logger = (logLine: LogLine) => void;

package/dist/cjs/lib/v3/types/public/methods.d.ts

@@ -0,0 +1,56 @@
+import { Page as PatchrightPage } from "patchright-core";
+import { Page as PlaywrightPage } from "playwright-core";
+import { Page as PuppeteerPage } from "puppeteer-core";
+import { z } from "zod";
+import type { InferStagehandSchema, StagehandZodSchema } from "../../zodCompat.js";
+import { Page } from "../../understudy/page.js";
+import { ModelConfiguration } from "../public/model.js";
+export interface ActOptions {
+    model?: ModelConfiguration;
+    variables?: Record<string, string>;
+    timeout?: number;
+    page?: PlaywrightPage | PuppeteerPage | PatchrightPage | Page;
+}
+export interface ActResult {
+    success: boolean;
+    message: string;
+    actionDescription: string;
+    actions: Action[];
+}
+export type ExtractResult<T extends StagehandZodSchema> = InferStagehandSchema<T>;
+export interface Action {
+    selector: string;
+    description: string;
+    method?: string;
+    arguments?: string[];
+}
+export interface HistoryEntry {
+    method: "act" | "extract" | "observe" | "navigate" | "agent";
+    parameters: unknown;
+    result: unknown;
+    timestamp: string;
+}
+export interface ExtractOptions {
+    model?: ModelConfiguration;
+    timeout?: number;
+    selector?: string;
+    page?: PlaywrightPage | PuppeteerPage | PatchrightPage | Page;
+}
+export declare const defaultExtractSchema: z.ZodObject<{
+    extraction: z.ZodString;
+}, z.core.$strip>;
+export declare const pageTextSchema: z.ZodObject<{
+    pageText: z.ZodString;
+}, z.core.$strip>;
+export interface ObserveOptions {
+    model?: ModelConfiguration;
+    timeout?: number;
+    selector?: string;
+    page?: PlaywrightPage | PuppeteerPage | PatchrightPage | Page;
+}
+export declare enum V3FunctionName {
+    ACT = "ACT",
+    EXTRACT = "EXTRACT",
+    OBSERVE = "OBSERVE",
+    AGENT = "AGENT"
+}

package/dist/cjs/lib/v3/types/public/metrics.d.ts

@@ -0,0 +1,27 @@
+export interface StagehandMetrics {
+    actPromptTokens: number;
+    actCompletionTokens: number;
+    actReasoningTokens: number;
+    actCachedInputTokens: number;
+    actInferenceTimeMs: number;
+    extractPromptTokens: number;
+    extractCompletionTokens: number;
+    extractReasoningTokens: number;
+    extractCachedInputTokens: number;
+    extractInferenceTimeMs: number;
+    observePromptTokens: number;
+    observeCompletionTokens: number;
+    observeReasoningTokens: number;
+    observeCachedInputTokens: number;
+    observeInferenceTimeMs: number;
+    agentPromptTokens: number;
+    agentCompletionTokens: number;
+    agentReasoningTokens: number;
+    agentCachedInputTokens: number;
+    agentInferenceTimeMs: number;
+    totalPromptTokens: number;
+    totalCompletionTokens: number;
+    totalReasoningTokens: number;
+    totalCachedInputTokens: number;
+    totalInferenceTimeMs: number;
+}

package/dist/cjs/lib/v3/types/public/model.d.ts

@@ -0,0 +1,65 @@
+import type { ClientOptions as AnthropicClientOptionsBase } from "@anthropic-ai/sdk";
+import type { GoogleVertexProviderSettings as GoogleVertexProviderSettingsBase } from "@ai-sdk/google-vertex";
+import type { LanguageModelV2 } from "@ai-sdk/provider";
+import type { ClientOptions as OpenAIClientOptionsBase } from "openai";
+import type { AgentProviderType } from "./agent.js";
+export type OpenAIClientOptions = Pick<OpenAIClientOptionsBase, "baseURL" | "apiKey">;
+export type AnthropicClientOptions = Pick<AnthropicClientOptionsBase, "baseURL" | "apiKey">;
+export interface GoogleServiceAccountCredentials {
+    type?: string;
+    project_id?: string;
+    private_key_id?: string;
+    private_key?: string;
+    client_email?: string;
+    client_id?: string;
+    auth_uri?: string;
+    token_uri?: string;
+    auth_provider_x509_cert_url?: string;
+    client_x509_cert_url?: string;
+    universe_domain?: string;
+}
+export type GoogleVertexProviderSettings = Pick<GoogleVertexProviderSettingsBase, "project" | "location"> & {
+    googleAuthOptions?: {
+        credentials?: GoogleServiceAccountCredentials;
+    };
+};
+export type AnthropicJsonSchemaObject = {
+    definitions?: {
+        MySchema?: {
+            properties?: Record<string, unknown>;
+            required?: string[];
+        };
+    };
+    properties?: Record<string, unknown>;
+    required?: string[];
+} & Record<string, unknown>;
+export interface LLMTool {
+    type: "function";
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+}
+export type AISDKProvider = (modelName: string) => LanguageModelV2;
+export type AISDKCustomProvider = (options: ClientOptions) => AISDKProvider;
+export type AvailableModel = "gpt-4.1" | "gpt-4.1-mini" | "gpt-4.1-nano" | "o4-mini" | "o3" | "o3-mini" | "o1" | "o1-mini" | "gpt-4o" | "gpt-4o-mini" | "gpt-4o-2024-08-06" | "gpt-4.5-preview" | "o1-preview" | "claude-3-5-sonnet-latest" | "claude-3-5-sonnet-20241022" | "claude-3-5-sonnet-20240620" | "claude-3-7-sonnet-latest" | "claude-3-7-sonnet-20250219" | "cerebras-llama-3.3-70b" | "cerebras-llama-3.1-8b" | "groq-llama-3.3-70b-versatile" | "groq-llama-3.3-70b-specdec" | "gemini-1.5-flash" | "gemini-1.5-pro" | "gemini-1.5-flash-8b" | "gemini-2.0-flash-lite" | "gemini-2.0-flash" | "gemini-2.5-flash-preview-04-17" | "gemini-2.5-pro-preview-03-25" | string;
+export type ModelProvider = "openai" | "anthropic" | "cerebras" | "groq" | "google" | "aisdk";
+export type ClientOptions = (OpenAIClientOptions | AnthropicClientOptions | GoogleVertexProviderSettings) & {
+    apiKey?: string;
+    provider?: AgentProviderType;
+    baseURL?: string;
+    /** OpenAI organization ID */
+    organization?: string;
+    /** Delay between agent actions in ms */
+    waitBetweenActions?: number;
+    /** Anthropic thinking budget for extended thinking */
+    thinkingBudget?: number;
+    /** Environment type for CUA agents (browser, mac, windows, ubuntu) */
+    environment?: string;
+    /** Max images for Microsoft FARA agent */
+    maxImages?: number;
+    /** Temperature for model inference */
+    temperature?: number;
+};
+export type ModelConfiguration = AvailableModel | (ClientOptions & {
+    modelName: AvailableModel;
+});

package/dist/cjs/lib/v3/types/public/options.d.ts

@@ -0,0 +1,70 @@
+import { z } from "zod";
+import { LLMClient } from "../../llm/LLMClient.js";
+import { ModelConfiguration } from "./model.js";
+import { LogLine } from "./logs.js";
+import { type BrowserbaseSessionCreateParams, LocalBrowserLaunchOptionsSchema } from "./api.js";
+export type V3Env = "LOCAL" | "BROWSERBASE";
+export declare const localBrowserLaunchOptionsSchema: z.ZodObject<{
+    args: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    executablePath: z.ZodOptional<z.ZodString>;
+    port: z.ZodOptional<z.ZodNumber>;
+    userDataDir: z.ZodOptional<z.ZodString>;
+    preserveUserDataDir: z.ZodOptional<z.ZodBoolean>;
+    headless: z.ZodOptional<z.ZodBoolean>;
+    devtools: z.ZodOptional<z.ZodBoolean>;
+    chromiumSandbox: z.ZodOptional<z.ZodBoolean>;
+    ignoreDefaultArgs: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodArray<z.ZodString>]>>;
+    proxy: z.ZodOptional<z.ZodObject<{
+        server: z.ZodString;
+        bypass: z.ZodOptional<z.ZodString>;
+        username: z.ZodOptional<z.ZodString>;
+        password: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    locale: z.ZodOptional<z.ZodString>;
+    viewport: z.ZodOptional<z.ZodObject<{
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+    }, z.core.$strip>>;
+    deviceScaleFactor: z.ZodOptional<z.ZodNumber>;
+    hasTouch: z.ZodOptional<z.ZodBoolean>;
+    ignoreHTTPSErrors: z.ZodOptional<z.ZodBoolean>;
+    cdpUrl: z.ZodOptional<z.ZodString>;
+    connectTimeoutMs: z.ZodOptional<z.ZodNumber>;
+    downloadsPath: z.ZodOptional<z.ZodString>;
+    acceptDownloads: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+export type LocalBrowserLaunchOptions = z.infer<typeof LocalBrowserLaunchOptionsSchema>;
+/** Constructor options for V3 */
+export interface V3Options {
+    env: V3Env;
+    apiKey?: string;
+    projectId?: string;
+    /**
+     * Optional: fine-tune Browserbase session creation or resume an existing session.
+     */
+    browserbaseSessionCreateParams?: BrowserbaseSessionCreateParams;
+    browserbaseSessionID?: string;
+    /**
+     * Controls browser keepalive behavior. When set, it overrides any value in
+     * browserbaseSessionCreateParams.keepAlive.
+     */
+    keepAlive?: boolean;
+    localBrowserLaunchOptions?: LocalBrowserLaunchOptions;
+    model?: ModelConfiguration;
+    llmClient?: LLMClient;
+    systemPrompt?: string;
+    logInferenceToFile?: boolean;
+    experimental?: boolean;
+    verbose?: 0 | 1 | 2;
+    selfHeal?: boolean;
+    waitForCaptchaSolves?: boolean;
+    actTimeoutMs?: number;
+    /** Disable pino logging backend (useful for tests or minimal environments). */
+    disablePino?: boolean;
+    /** Optional external logger hook for integrating with host apps. */
+    logger?: (line: LogLine) => void;
+    /** Directory used to persist cached actions for act(). */
+    cacheDir?: string;
+    domSettleTimeout?: number;
+    disableAPI?: boolean;
+}

package/dist/cjs/lib/v3/types/public/page.d.ts

@@ -0,0 +1,18 @@
+import { Page } from "../../understudy/page.js";
+import { Page as PlaywrightPage } from "playwright-core";
+import { Page as PatchrightPage } from "patchright-core";
+import { Page as PuppeteerPage } from "puppeteer-core";
+export type { PlaywrightPage, PatchrightPage, PuppeteerPage, Page };
+export type AnyPage = PlaywrightPage | PuppeteerPage | PatchrightPage | Page;
+export { ConsoleMessage } from "../../understudy/consoleMessage.js";
+export type { ConsoleListener } from "../../understudy/consoleMessage.js";
+export type LoadState = "load" | "domcontentloaded" | "networkidle";
+export { Response } from "../../understudy/response.js";
+export type SnapshotResult = {
+    formattedTree: string;
+    xpathMap: Record<string, string>;
+    urlMap: Record<string, string>;
+};
+export type PageSnapshotOptions = {
+    includeIframes?: boolean;
+};

package/dist/cjs/lib/v3/types/public/screenshotTypes.d.ts

@@ -0,0 +1,25 @@
+import type { Locator } from "../../understudy/locator.js";
+export type ScreenshotAnimationsOption = "disabled" | "allow";
+export type ScreenshotCaretOption = "hide" | "initial";
+export type ScreenshotScaleOption = "css" | "device";
+export interface ScreenshotClip {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface ScreenshotOptions {
+    animations?: ScreenshotAnimationsOption;
+    caret?: ScreenshotCaretOption;
+    clip?: ScreenshotClip;
+    fullPage?: boolean;
+    mask?: Locator[];
+    maskColor?: string;
+    omitBackground?: boolean;
+    path?: string;
+    quality?: number;
+    scale?: ScreenshotScaleOption;
+    style?: string;
+    timeout?: number;
+    type?: "png" | "jpeg";
+}

package/dist/cjs/lib/v3/types/public/sdkErrors.d.ts

@@ -0,0 +1,152 @@
+import { ZodError } from "zod";
+export declare class StagehandError extends Error {
+    readonly cause?: unknown;
+    constructor(message: string, cause?: unknown);
+}
+export declare class StagehandDefaultError extends StagehandError {
+    constructor(error?: unknown);
+}
+export declare class StagehandEnvironmentError extends StagehandError {
+    constructor(currentEnvironment: string, requiredEnvironment: string, feature: string);
+}
+export declare class MissingEnvironmentVariableError extends StagehandError {
+    constructor(missingEnvironmentVariable: string, feature: string);
+}
+export declare class UnsupportedModelError extends StagehandError {
+    constructor(supportedModels: string[], feature?: string);
+}
+export declare class UnsupportedModelProviderError extends StagehandError {
+    constructor(supportedProviders: string[], feature?: string);
+}
+export declare class UnsupportedAISDKModelProviderError extends StagehandError {
+    constructor(provider: string, supportedProviders: string[]);
+}
+export declare class InvalidAISDKModelFormatError extends StagehandError {
+    constructor(modelName: string);
+}
+export declare class StagehandNotInitializedError extends StagehandError {
+    constructor(prop: string);
+}
+export declare class BrowserbaseSessionNotFoundError extends StagehandError {
+    constructor();
+}
+export declare class CaptchaTimeoutError extends StagehandError {
+    constructor();
+}
+export declare class MissingLLMConfigurationError extends StagehandError {
+    constructor();
+}
+export declare class HandlerNotInitializedError extends StagehandError {
+    constructor(handlerType: string);
+}
+export declare class StagehandInvalidArgumentError extends StagehandError {
+    constructor(message: string);
+}
+export declare class StagehandElementNotFoundError extends StagehandError {
+    constructor(xpaths: string[]);
+}
+export declare class AgentScreenshotProviderError extends StagehandError {
+    constructor(message: string);
+}
+export declare class StagehandMissingArgumentError extends StagehandError {
+    constructor(message: string);
+}
+export declare class CreateChatCompletionResponseError extends StagehandError {
+    constructor(message: string);
+}
+export declare class StagehandEvalError extends StagehandError {
+    constructor(message: string);
+}
+export declare class StagehandDomProcessError extends StagehandError {
+    constructor(message: string);
+}
+export declare class StagehandLocatorError extends StagehandError {
+    constructor(action: string, selector: string, message: string);
+}
+export declare class StagehandClickError extends StagehandError {
+    constructor(message: string, selector: string);
+}
+export declare class LLMResponseError extends StagehandError {
+    constructor(primitive: string, message: string);
+}
+export declare class StagehandIframeError extends StagehandError {
+    constructor(frameUrl: string, message: string);
+}
+export declare class ContentFrameNotFoundError extends StagehandError {
+    constructor(selector: string);
+}
+export declare class XPathResolutionError extends StagehandError {
+    constructor(xpath: string);
+}
+export declare class ExperimentalApiConflictError extends StagehandError {
+    constructor();
+}
+export declare class ExperimentalNotConfiguredError extends StagehandError {
+    constructor(featureName: string);
+}
+export declare class CuaModelRequiredError extends StagehandError {
+    constructor(availableModels: readonly string[]);
+}
+export declare class ZodSchemaValidationError extends Error {
+    readonly received: unknown;
+    readonly issues: ReturnType<ZodError["format"]>;
+    constructor(received: unknown, issues: ReturnType<ZodError["format"]>);
+}
+export declare class StagehandInitError extends StagehandError {
+    constructor(message: string);
+}
+export declare class MCPConnectionError extends StagehandError {
+    readonly serverUrl: string;
+    readonly originalError: unknown;
+    constructor(serverUrl: string, originalError: unknown);
+}
+export declare class StagehandShadowRootMissingError extends StagehandError {
+    constructor(detail?: string);
+}
+export declare class StagehandShadowSegmentEmptyError extends StagehandError {
+    constructor();
+}
+export declare class StagehandShadowSegmentNotFoundError extends StagehandError {
+    constructor(segment: string, hint?: string);
+}
+export declare class ElementNotVisibleError extends StagehandError {
+    constructor(selector: string);
+}
+export declare class ResponseBodyError extends StagehandError {
+    constructor(message: string);
+}
+export declare class ResponseParseError extends StagehandError {
+    constructor(message: string);
+}
+export declare class TimeoutError extends StagehandError {
+    constructor(operation: string, timeoutMs: number);
+}
+export declare class ActTimeoutError extends TimeoutError {
+    constructor(timeoutMs: number);
+}
+export declare class ExtractTimeoutError extends TimeoutError {
+    constructor(timeoutMs: number);
+}
+export declare class ObserveTimeoutError extends TimeoutError {
+    constructor(timeoutMs: number);
+}
+export declare class PageNotFoundError extends StagehandError {
+    constructor(identifier: string);
+}
+export declare class ConnectionTimeoutError extends StagehandError {
+    constructor(message: string);
+}
+export declare class StreamingCallbacksInNonStreamingModeError extends StagehandError {
+    readonly invalidCallbacks: string[];
+    constructor(invalidCallbacks: string[]);
+}
+export declare class AgentAbortError extends StagehandError {
+    readonly reason: string;
+    constructor(reason?: string);
+}
+export declare class StagehandClosedError extends StagehandError {
+    constructor();
+}
+export declare class StagehandSnapshotError extends StagehandError {
+    constructor(cause?: unknown);
+}

package/dist/cjs/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/cjs/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/cjs/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;

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

@@ -0,0 +1,7 @@
+import { Page } from "../../page.js";
+import type { ResolvedLocation } from "../../../types/private/snapshot.js";
+/**
+ * Resolve deepest node for a page coordinate and compute its absolute XPath across frames.
+ * More efficient than building a full hybrid snapshot when only a single node’s XPath is needed.
+ */
+export declare function resolveXpathForLocation(page: Page, x: number, y: number): Promise<ResolvedLocation | null>;

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

@@ -0,0 +1,46 @@
+import type { Protocol } from "devtools-protocol";
+import type { CDPSessionLike } from "../../cdp.js";
+import type { SessionDomIndex } from "../../../types/private/snapshot.js";
+/**
+ * Determine if CDP truncated a node's children when streaming the DOM tree.
+ * childNodeCount stays accurate even when `children` are omitted; we use this to
+ * decide whether DOM.describeNode must be re-run for that node.
+ */
+export declare function shouldExpandNode(node: Protocol.DOM.Node): boolean;
+/** Merge an expanded DescribeNode payload back into the original shallow node. */
+export declare function mergeDomNodes(target: Protocol.DOM.Node, source: Protocol.DOM.Node): void;
+/** Helper that returns every nested collection we recurse through uniformly. */
+export declare function collectDomTraversalTargets(node: Protocol.DOM.Node): Protocol.DOM.Node[];
+/**
+ * Rehydrate a truncated DOM tree by repeatedly calling DOM.describeNode with
+ * decreasing depths. Any non-CBOR failure is surfaced as a StagehandDomProcessError.
+ */
+export declare function hydrateDomTree(session: CDPSessionLike, root: Protocol.DOM.Node, pierce: boolean): Promise<void>;
+/**
+ * Attempt DOM.getDocument with progressively shallower depths until CBOR stops
+ * complaining. When a shallower snapshot is returned we hydrate the missing
+ * branches so downstream DOM traversals see the full tree shape.
+ */
+export declare function getDomTreeWithFallback(session: CDPSessionLike, pierce: boolean): Promise<Protocol.DOM.Node>;
+/**
+ * Build tag name and XPath maps for a single frame session.
+ * EncodedId is produced by a frame-aware encoder provided by the caller.
+ */
+export declare function domMapsForSession(session: CDPSessionLike, frameId: string, pierce: boolean, encode: (fid: string, backendNodeId: number) => string, attemptOwnerLookup?: boolean): Promise<{
+    tagNameMap: Record<string, string>;
+    xpathMap: Record<string, string>;
+    scrollableMap: Record<string, boolean>;
+}>;
+/**
+ * Build an index of absolute XPath/tag metadata for an entire CDP session.
+ * Once the index is cached, per-frame slices are derived without extra DOM
+ * calls, which keeps snapshot capture linear in the number of frames.
+ */
+export declare function buildSessionDomIndex(session: CDPSessionLike, pierce: boolean): Promise<SessionDomIndex>;
+/**
+ * Relativize an absolute XPath against a document root's absolute path.
+ * When the node lives outside the document we return the absolute path as-is.
+ */
+export declare function relativizeXPath(baseAbs: string, nodeAbs: string): string;
+/** Find a node by backendNodeId inside a DOM.getDocument tree. */
+export declare function findNodeByBackendId(root: Protocol.DOM.Node, backendNodeId: number): Protocol.DOM.Node | undefined;