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

package/dist/esm/lib/v3/types/private/handlers.d.ts

@@ -0,0 +1,38 @@
+import { Page } from "../../understudy/page.js";
+import { ModelConfiguration } from "../public/model.js";
+import type { StagehandZodSchema } from "../../zodCompat.js";
+export interface ActHandlerParams {
+    instruction: string;
+    model?: ModelConfiguration;
+    variables?: Record<string, string>;
+    timeout?: number;
+    page: Page;
+}
+export interface ExtractHandlerParams<T extends StagehandZodSchema> {
+    instruction?: string;
+    schema?: T;
+    model?: ModelConfiguration;
+    timeout?: number;
+    selector?: string;
+    page: Page;
+}
+export interface ObserveHandlerParams {
+    instruction?: string;
+    model?: ModelConfiguration;
+    timeout?: number;
+    selector?: string;
+    page: Page;
+}
+export declare enum SupportedUnderstudyAction {
+    CLICK = "click",
+    FILL = "fill",
+    TYPE = "type",
+    PRESS = "press",
+    SCROLL = "scrollTo",
+    NEXT_CHUNK = "nextChunk",
+    PREV_CHUNK = "prevChunk",
+    SELECT_OPTION_FROM_DROPDOWN = "selectOptionFromDropdown",
+    HOVER = "hover",
+    DOUBLE_CLICK = "doubleClick",
+    DRAG_AND_DROP = "dragAndDrop"
+}

package/dist/esm/lib/v3/types/private/handlers.js

@@ -0,0 +1,16 @@
+// We can use this enum to list the actions supported in performUnderstudyMethod
+export var SupportedUnderstudyAction;
+(function (SupportedUnderstudyAction) {
+    SupportedUnderstudyAction["CLICK"] = "click";
+    SupportedUnderstudyAction["FILL"] = "fill";
+    SupportedUnderstudyAction["TYPE"] = "type";
+    SupportedUnderstudyAction["PRESS"] = "press";
+    SupportedUnderstudyAction["SCROLL"] = "scrollTo";
+    SupportedUnderstudyAction["NEXT_CHUNK"] = "nextChunk";
+    SupportedUnderstudyAction["PREV_CHUNK"] = "prevChunk";
+    SupportedUnderstudyAction["SELECT_OPTION_FROM_DROPDOWN"] = "selectOptionFromDropdown";
+    SupportedUnderstudyAction["HOVER"] = "hover";
+    SupportedUnderstudyAction["DOUBLE_CLICK"] = "doubleClick";
+    SupportedUnderstudyAction["DRAG_AND_DROP"] = "dragAndDrop";
+})(SupportedUnderstudyAction || (SupportedUnderstudyAction = {}));
+//# sourceMappingURL=handlers.js.map

package/dist/esm/lib/v3/types/private/handlers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"handlers.js","sourceRoot":"","sources":["../../../../../../lib/v3/types/private/handlers.ts"],"names":[],"mappings":"AA6BA,gFAAgF;AAChF,MAAM,CAAN,IAAY,yBAYX;AAZD,WAAY,yBAAyB;IACnC,4CAAe,CAAA;IACf,0CAAa,CAAA;IACb,0CAAa,CAAA;IACb,4CAAe,CAAA;IACf,gDAAmB,CAAA;IACnB,qDAAwB,CAAA;IACxB,qDAAwB,CAAA;IACxB,qFAAwD,CAAA;IACxD,4CAAe,CAAA;IACf,yDAA4B,CAAA;IAC5B,0DAA6B,CAAA;AAC/B,CAAC,EAZW,yBAAyB,KAAzB,yBAAyB,QAYpC","sourcesContent":["import { Page } from \"../../understudy/page.js\";\nimport { ModelConfiguration } from \"../public/model.js\";\nimport type { StagehandZodSchema } from \"../../zodCompat.js\";\n\nexport interface ActHandlerParams {\n  instruction: string;\n  model?: ModelConfiguration;\n  variables?: Record<string, string>;\n  timeout?: number;\n  page: Page;\n}\n\nexport interface ExtractHandlerParams<T extends StagehandZodSchema> {\n  instruction?: string;\n  schema?: T;\n  model?: ModelConfiguration;\n  timeout?: number;\n  selector?: string;\n  page: Page;\n}\n\nexport interface ObserveHandlerParams {\n  instruction?: string;\n  model?: ModelConfiguration;\n  timeout?: number;\n  selector?: string;\n  page: Page;\n}\n\n// We can use this enum to list the actions supported in performUnderstudyMethod\nexport enum SupportedUnderstudyAction {\n  CLICK = \"click\",\n  FILL = \"fill\",\n  TYPE = \"type\",\n  PRESS = \"press\",\n  SCROLL = \"scrollTo\",\n  NEXT_CHUNK = \"nextChunk\",\n  PREV_CHUNK = \"prevChunk\",\n  SELECT_OPTION_FROM_DROPDOWN = \"selectOptionFromDropdown\",\n  HOVER = \"hover\",\n  DOUBLE_CLICK = \"doubleClick\",\n  DRAG_AND_DROP = \"dragAndDrop\",\n}\n"]}

package/dist/esm/lib/v3/types/private/index.d.ts

@@ -0,0 +1,7 @@
+export * from "./api.js";
+export * from "./handlers.js";
+export * from "./internal.js";
+export * from "./evaluator.js";
+export * from "./cache.js";
+export * from "./agent.js";
+export * from "./snapshot.js";

package/dist/esm/lib/v3/types/private/index.js

@@ -0,0 +1,8 @@
+export * from "./api.js";
+export * from "./handlers.js";
+export * from "./internal.js";
+export * from "./evaluator.js";
+export * from "./cache.js";
+export * from "./agent.js";
+export * from "./snapshot.js";
+//# sourceMappingURL=index.js.map

package/dist/esm/lib/v3/types/private/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../../lib/v3/types/private/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC","sourcesContent":["export * from \"./api.js\";\nexport * from \"./handlers.js\";\nexport * from \"./internal.js\";\nexport * from \"./evaluator.js\";\nexport * from \"./cache.js\";\nexport * from \"./agent.js\";\nexport * from \"./snapshot.js\";\n"]}

package/dist/esm/lib/v3/types/private/internal.d.ts

@@ -0,0 +1,39 @@
+import Browserbase from "@browserbasehq/sdk";
+import { LaunchedChrome } from "chrome-launcher";
+export type InitState = {
+    kind: "UNINITIALIZED";
+} | {
+    kind: "LOCAL";
+    chrome: LaunchedChrome;
+    ws: string;
+    userDataDir?: string;
+    createdTempProfile?: boolean;
+    preserveUserDataDir?: boolean;
+} | {
+    kind: "BROWSERBASE";
+    bb: Browserbase;
+    sessionId: string;
+    ws: string;
+};
+export type EncodedId = `${number}-${number}`;
+/**
+ * Represents a path through a Zod schema from the root object down to a
+ * particular field. The `segments` array describes the chain of keys/indices.
+ *
+ * - **String** segments indicate object property names.
+ * - **Number** segments indicate array indices.
+ *
+ * For example, `["users", 0, "homepage"]` might describe reaching
+ * the `homepage` field in `schema.users[0].homepage`.
+ */
+export interface ZodPathSegments {
+    /**
+     * The ordered list of keys/indices leading from the schema root
+     * to the targeted field.
+     */
+    segments: Array<string | number>;
+}
+export type InitScriptSource<Arg> = string | {
+    path?: string;
+    content?: string;
+} | ((arg: Arg) => unknown);

package/dist/esm/lib/v3/types/private/internal.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=internal.js.map

package/dist/esm/lib/v3/types/private/internal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"internal.js","sourceRoot":"","sources":["../../../../../../lib/v3/types/private/internal.ts"],"names":[],"mappings":"","sourcesContent":["import Browserbase from \"@browserbasehq/sdk\";\nimport { LaunchedChrome } from \"chrome-launcher\";\n\nexport type InitState =\n  | { kind: \"UNINITIALIZED\" }\n  | {\n      kind: \"LOCAL\";\n      chrome: LaunchedChrome;\n      ws: string;\n      userDataDir?: string;\n      createdTempProfile?: boolean;\n      preserveUserDataDir?: boolean;\n    }\n  | { kind: \"BROWSERBASE\"; bb: Browserbase; sessionId: string; ws: string };\n\nexport type EncodedId = `${number}-${number}`;\n\n/**\n * Represents a path through a Zod schema from the root object down to a\n * particular field. The `segments` array describes the chain of keys/indices.\n *\n * - **String** segments indicate object property names.\n * - **Number** segments indicate array indices.\n *\n * For example, `[\"users\", 0, \"homepage\"]` might describe reaching\n * the `homepage` field in `schema.users[0].homepage`.\n */\nexport interface ZodPathSegments {\n  /**\n   * The ordered list of keys/indices leading from the schema root\n   * to the targeted field.\n   */\n  segments: Array<string | number>;\n}\n\nexport type InitScriptSource<Arg> =\n  | string\n  | { path?: string; content?: string }\n  | ((arg: Arg) => unknown);\n"]}

package/dist/esm/lib/v3/types/private/locator.d.ts

@@ -0,0 +1,9 @@
+import { Buffer } from "buffer";
+export interface NormalizedFilePayload {
+    name: string;
+    mimeType: string;
+    buffer: Buffer;
+    lastModified: number;
+    /** Absolute path to the source file when provided by the caller. */
+    absolutePath?: string;
+}

package/dist/esm/lib/v3/types/private/locator.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=locator.js.map

package/dist/esm/lib/v3/types/private/locator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"locator.js","sourceRoot":"","sources":["../../../../../../lib/v3/types/private/locator.ts"],"names":[],"mappings":"","sourcesContent":["import { Buffer } from \"buffer\";\n\nexport interface NormalizedFilePayload {\n  name: string;\n  mimeType: string;\n  buffer: Buffer;\n  lastModified: number;\n  /** Absolute path to the source file when provided by the caller. */\n  absolutePath?: string;\n}\n"]}

package/dist/esm/lib/v3/types/private/network.d.ts

@@ -0,0 +1,34 @@
+import { Protocol } from "devtools-protocol";
+/** Metadata tracked for each network request currently in-flight. */
+export type NetworkRequestInfo = {
+    sessionId: string;
+    requestId: string;
+    requestKey: string;
+    frameId?: string;
+    loaderId?: string;
+    url?: string;
+    timestamp: number;
+    resourceType?: Protocol.Network.ResourceType;
+    documentRequest: boolean;
+};
+/** Callback hooks consumers can implement to observe network transitions. */
+export interface NetworkObserver {
+    onRequestStarted(info: NetworkRequestInfo): void;
+    onRequestFinished(info: NetworkRequestInfo): void;
+    onRequestFailed(info: NetworkRequestInfo): void;
+}
+/** Options for the idle waiter helper. */
+export type WaitForIdleOptions = {
+    startTime?: number;
+    timeoutMs: number;
+    idleTimeMs?: number;
+    filter?: (info: NetworkRequestInfo) => boolean;
+    totalBudgetMs?: number;
+};
+export declare const DEFAULT_IDLE_WAIT = 500;
+export declare const IGNORED_RESOURCE_TYPES: Set<Protocol.Network.ResourceType>;
+/** The handle returned by the network manager idle helper. */
+export type WaitForIdleHandle = {
+    promise: Promise<void>;
+    dispose: () => void;
+};

package/dist/esm/lib/v3/types/private/network.js

@@ -0,0 +1,3 @@
+export const DEFAULT_IDLE_WAIT = 500;
+export const IGNORED_RESOURCE_TYPES = new Set(["EventSource", "WebSocket"]);
+//# sourceMappingURL=network.js.map

package/dist/esm/lib/v3/types/private/network.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"network.js","sourceRoot":"","sources":["../../../../../../lib/v3/types/private/network.ts"],"names":[],"mappings":"AA+BA,MAAM,CAAC,MAAM,iBAAiB,GAAG,GAAG,CAAC;AACrC,MAAM,CAAC,MAAM,sBAAsB,GAAG,IAAI,GAAG,CAE3C,CAAC,aAAa,EAAE,WAAW,CAAC,CAAC,CAAC","sourcesContent":["import { Protocol } from \"devtools-protocol\";\n\n/** Metadata tracked for each network request currently in-flight. */\nexport type NetworkRequestInfo = {\n  sessionId: string;\n  requestId: string;\n  requestKey: string;\n  frameId?: string;\n  loaderId?: string;\n  url?: string;\n  timestamp: number;\n  resourceType?: Protocol.Network.ResourceType;\n  documentRequest: boolean;\n};\n\n/** Callback hooks consumers can implement to observe network transitions. */\nexport interface NetworkObserver {\n  onRequestStarted(info: NetworkRequestInfo): void;\n  onRequestFinished(info: NetworkRequestInfo): void;\n  onRequestFailed(info: NetworkRequestInfo): void;\n}\n\n/** Options for the idle waiter helper. */\nexport type WaitForIdleOptions = {\n  startTime?: number;\n  timeoutMs: number;\n  idleTimeMs?: number;\n  filter?: (info: NetworkRequestInfo) => boolean;\n  totalBudgetMs?: number;\n};\n\nexport const DEFAULT_IDLE_WAIT = 500;\nexport const IGNORED_RESOURCE_TYPES = new Set<\n  Protocol.Network.ResourceType | undefined\n>([\"EventSource\", \"WebSocket\"]);\n\n/** The handle returned by the network manager idle helper. */\nexport type WaitForIdleHandle = {\n  promise: Promise<void>;\n  dispose: () => void;\n};\n"]}

package/dist/esm/lib/v3/types/private/shutdown.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Internal-only types for the shutdown supervisor process.
+ */
+export type ShutdownSupervisorConfig = {
+    kind: "LOCAL";
+    keepAlive: boolean;
+    pid: number;
+    userDataDir?: string;
+    createdTempProfile?: boolean;
+    preserveUserDataDir?: boolean;
+} | {
+    kind: "STAGEHAND_API";
+    keepAlive: boolean;
+    sessionId: string;
+    apiKey: string;
+    projectId: string;
+};
+export type ShutdownSupervisorMessage = {
+    type: "config";
+    config: ShutdownSupervisorConfig;
+} | {
+    type: "exit";
+} | {
+    type: "ready";
+};
+export interface ShutdownSupervisorHandle {
+    /** Best-effort signal to stop the supervisor without running cleanup. */
+    stop: () => void;
+    /** Resolves once the supervisor acknowledges config or times out. */
+    ready: Promise<void>;
+}

package/dist/esm/lib/v3/types/private/shutdown.js

@@ -0,0 +1,5 @@
+/**
+ * Internal-only types for the shutdown supervisor process.
+ */
+export {};
+//# sourceMappingURL=shutdown.js.map

package/dist/esm/lib/v3/types/private/shutdown.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shutdown.js","sourceRoot":"","sources":["../../../../../../lib/v3/types/private/shutdown.ts"],"names":[],"mappings":"AAAA;;GAEG","sourcesContent":["/**\n * Internal-only types for the shutdown supervisor process.\n */\n\nexport type ShutdownSupervisorConfig =\n  | {\n      kind: \"LOCAL\";\n      keepAlive: boolean;\n      pid: number;\n      userDataDir?: string;\n      createdTempProfile?: boolean;\n      preserveUserDataDir?: boolean;\n    }\n  | {\n      kind: \"STAGEHAND_API\";\n      keepAlive: boolean;\n      sessionId: string;\n      apiKey: string;\n      projectId: string;\n    };\n\nexport type ShutdownSupervisorMessage =\n  | { type: \"config\"; config: ShutdownSupervisorConfig }\n  | { type: \"exit\" }\n  | { type: \"ready\" };\n\nexport interface ShutdownSupervisorHandle {\n  /** Best-effort signal to stop the supervisor without running cleanup. */\n  stop: () => void;\n  /** Resolves once the supervisor acknowledges config or times out. */\n  ready: Promise<void>;\n}\n"]}

package/dist/esm/lib/v3/types/private/shutdownErrors.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Internal-only errors for the shutdown supervisor.
+ */
+export declare class ShutdownSupervisorError extends Error {
+    constructor(message: string);
+}
+export declare class ShutdownSupervisorResolveError extends ShutdownSupervisorError {
+    constructor(message: string);
+}
+export declare class ShutdownSupervisorSpawnError extends ShutdownSupervisorError {
+    constructor(message: string);
+}

package/dist/esm/lib/v3/types/private/shutdownErrors.js

@@ -0,0 +1,22 @@
+/**
+ * Internal-only errors for the shutdown supervisor.
+ */
+export class ShutdownSupervisorError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ShutdownSupervisorError";
+    }
+}
+export class ShutdownSupervisorResolveError extends ShutdownSupervisorError {
+    constructor(message) {
+        super(message);
+        this.name = "ShutdownSupervisorResolveError";
+    }
+}
+export class ShutdownSupervisorSpawnError extends ShutdownSupervisorError {
+    constructor(message) {
+        super(message);
+        this.name = "ShutdownSupervisorSpawnError";
+    }
+}
+//# sourceMappingURL=shutdownErrors.js.map

package/dist/esm/lib/v3/types/private/shutdownErrors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shutdownErrors.js","sourceRoot":"","sources":["../../../../../../lib/v3/types/private/shutdownErrors.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,OAAO,uBAAwB,SAAQ,KAAK;IAChD,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAC;IACxC,CAAC;CACF;AAED,MAAM,OAAO,8BAA+B,SAAQ,uBAAuB;IACzE,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,gCAAgC,CAAC;IAC/C,CAAC;CACF;AAED,MAAM,OAAO,4BAA6B,SAAQ,uBAAuB;IACvE,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,8BAA8B,CAAC;IAC7C,CAAC;CACF","sourcesContent":["/**\n * Internal-only errors for the shutdown supervisor.\n */\n\nexport class ShutdownSupervisorError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = \"ShutdownSupervisorError\";\n  }\n}\n\nexport class ShutdownSupervisorResolveError extends ShutdownSupervisorError {\n  constructor(message: string) {\n    super(message);\n    this.name = \"ShutdownSupervisorResolveError\";\n  }\n}\n\nexport class ShutdownSupervisorSpawnError extends ShutdownSupervisorError {\n  constructor(message: string) {\n    super(message);\n    this.name = \"ShutdownSupervisorSpawnError\";\n  }\n}\n"]}

package/dist/esm/lib/v3/types/private/snapshot.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Options that control how hybrid snapshots and targeted scopes are captured.
+ */
+export type SnapshotOptions = {
+    /**
+     * Filter the snapshot to a specific element/subtree using a selector that can cross iframes.
+     * Supports XPath (prefixed with `xpath=` or starting with `/`) and CSS with iframe hops via `>>`.
+     */
+    focusSelector?: string;
+    /**
+     * Pierce shadow DOM when calling DOM.getDocument. Defaults to true to retain the
+     * existing behaviour.
+     */
+    pierceShadow?: boolean;
+    /**
+     * Toggle whether iframe subtrees are included in the merged snapshot. Defaults to true.
+     */
+    includeIframes?: boolean;
+    /**
+     * Optional feature flag that surfaces experimental traversal tweaks in the Accessibility layer.
+     */
+    experimental?: boolean;
+};
+/**
+ * Hybrid snapshot payload consumed by act/extract/observe handlers.
+ */
+export type HybridSnapshot = {
+    /** Merged outline across every frame. */
+    combinedTree: string;
+    /** EncodedId (frameOrdinal-backendNodeId) -> absolute XPath. */
+    combinedXpathMap: Record<string, string>;
+    /** EncodedId -> URL extracted from AX properties. */
+    combinedUrlMap: Record<string, string>;
+    /** Per-frame payloads expose the original relative data for debugging. */
+    perFrame?: PerFrameSnapshot[];
+};
+export type PerFrameSnapshot = {
+    frameId: string;
+    outline: string;
+    xpathMap: Record<string, string>;
+    urlMap: Record<string, string>;
+};
+/**
+ * Compact encoding of DOM data for an entire session. Shared between capture
+ * and focus helpers so DOM traversal can be unit tested in isolation.
+ */
+export type SessionDomIndex = {
+    rootBackend: number;
+    absByBe: Map<number, string>;
+    tagByBe: Map<number, string>;
+    scrollByBe: Map<number, boolean>;
+    docRootOf: Map<number, number>;
+    contentDocRootByIframe: Map<number, number>;
+};
+export type FrameDomMaps = {
+    tagNameMap: Record<string, string>;
+    xpathMap: Record<string, string>;
+    scrollableMap: Record<string, boolean>;
+    urlMap: Record<string, string>;
+};
+export type ResolvedLocation = {
+    frameId: string;
+    backendNodeId: number;
+    absoluteXPath: string;
+};
+export type ResolvedFocusFrame = {
+    targetFrameId: string;
+    tailXPath: string;
+    absPrefix: string;
+};
+export type ResolvedCssFocus = {
+    targetFrameId: string;
+    tailSelector: string;
+    absPrefix: string;
+};
+export type Axis = "child" | "desc";
+export type Step = {
+    axis: Axis;
+    raw: string;
+    name: string;
+};
+export type A11yNode = {
+    role: string;
+    name?: string;
+    description?: string;
+    value?: string | number | boolean;
+    nodeId: string;
+    backendDOMNodeId?: number;
+    parentId?: string;
+    childIds?: string[];
+    children?: A11yNode[];
+    encodedId?: string;
+};
+export type A11yOptions = {
+    focusSelector?: string;
+    experimental: boolean;
+    tagNameMap: Record<string, string>;
+    scrollableMap: Record<string, boolean>;
+    encode: (backendNodeId: number) => string;
+};
+export type AccessibilityTreeResult = {
+    outline: string;
+    urlMap: Record<string, string>;
+    scopeApplied: boolean;
+};
+export type FrameParentIndex = Map<string, string | null>;
+/**
+ * Shared frame metadata that every snapshot step needs.
+ * - `rootId`: stable identifier for the main frame so we can detect root prefixes.
+ * - `parentByFrame`: lookup table for iframe parentage (used by focus scoping and prefixing).
+ * - `frames`: DFS-ordered frame ids so merging walks parents before children.
+ */
+export type FrameContext = {
+    rootId: string;
+    parentByFrame: FrameParentIndex;
+    frames: string[];
+};

package/dist/esm/lib/v3/types/private/snapshot.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=snapshot.js.map

package/dist/esm/lib/v3/types/private/snapshot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot.js","sourceRoot":"","sources":["../../../../../../lib/v3/types/private/snapshot.ts"],"names":[],"mappings":"","sourcesContent":["/**\n * Options that control how hybrid snapshots and targeted scopes are captured.\n */\nexport type SnapshotOptions = {\n  /**\n   * Filter the snapshot to a specific element/subtree using a selector that can cross iframes.\n   * Supports XPath (prefixed with `xpath=` or starting with `/`) and CSS with iframe hops via `>>`.\n   */\n  focusSelector?: string;\n  /**\n   * Pierce shadow DOM when calling DOM.getDocument. Defaults to true to retain the\n   * existing behaviour.\n   */\n  pierceShadow?: boolean;\n  /**\n   * Toggle whether iframe subtrees are included in the merged snapshot. Defaults to true.\n   */\n  includeIframes?: boolean;\n  /**\n   * Optional feature flag that surfaces experimental traversal tweaks in the Accessibility layer.\n   */\n  experimental?: boolean;\n};\n\n/**\n * Hybrid snapshot payload consumed by act/extract/observe handlers.\n */\nexport type HybridSnapshot = {\n  /** Merged outline across every frame. */\n  combinedTree: string;\n  /** EncodedId (frameOrdinal-backendNodeId) -> absolute XPath. */\n  combinedXpathMap: Record<string, string>;\n  /** EncodedId -> URL extracted from AX properties. */\n  combinedUrlMap: Record<string, string>;\n  /** Per-frame payloads expose the original relative data for debugging. */\n  perFrame?: PerFrameSnapshot[];\n};\n\nexport type PerFrameSnapshot = {\n  frameId: string;\n  outline: string;\n  xpathMap: Record<string, string>;\n  urlMap: Record<string, string>;\n};\n\n/**\n * Compact encoding of DOM data for an entire session. Shared between capture\n * and focus helpers so DOM traversal can be unit tested in isolation.\n */\nexport type SessionDomIndex = {\n  rootBackend: number;\n  absByBe: Map<number, string>;\n  tagByBe: Map<number, string>;\n  scrollByBe: Map<number, boolean>;\n  docRootOf: Map<number, number>;\n  contentDocRootByIframe: Map<number, number>;\n};\n\nexport type FrameDomMaps = {\n  tagNameMap: Record<string, string>;\n  xpathMap: Record<string, string>;\n  scrollableMap: Record<string, boolean>;\n  urlMap: Record<string, string>;\n};\n\nexport type ResolvedLocation = {\n  frameId: string;\n  backendNodeId: number;\n  absoluteXPath: string;\n};\n\nexport type ResolvedFocusFrame = {\n  targetFrameId: string;\n  tailXPath: string;\n  absPrefix: string;\n};\n\nexport type ResolvedCssFocus = {\n  targetFrameId: string;\n  tailSelector: string;\n  absPrefix: string;\n};\n\nexport type Axis = \"child\" | \"desc\";\n\nexport type Step = {\n  axis: Axis;\n  raw: string;\n  name: string;\n};\n\nexport type A11yNode = {\n  role: string;\n  name?: string;\n  description?: string;\n  value?: string | number | boolean;\n  nodeId: string;\n  backendDOMNodeId?: number;\n  parentId?: string;\n  childIds?: string[];\n  children?: A11yNode[];\n  encodedId?: string;\n};\n\nexport type A11yOptions = {\n  focusSelector?: string;\n  experimental: boolean;\n  tagNameMap: Record<string, string>;\n  scrollableMap: Record<string, boolean>;\n  encode: (backendNodeId: number) => string;\n};\n\nexport type AccessibilityTreeResult = {\n  outline: string;\n  urlMap: Record<string, string>;\n  scopeApplied: boolean;\n};\n\nexport type FrameParentIndex = Map<string, string | null>;\n\n/**\n * Shared frame metadata that every snapshot step needs.\n * - `rootId`: stable identifier for the main frame so we can detect root prefixes.\n * - `parentByFrame`: lookup table for iframe parentage (used by focus scoping and prefixing).\n * - `frames`: DFS-ordered frame ids so merging walks parents before children.\n */\nexport type FrameContext = {\n  rootId: string;\n  parentByFrame: FrameParentIndex;\n  frames: string[];\n};\n"]}