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

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

@@ -0,0 +1,131 @@
+import type { ActOptions, ActResult, AvailableModel, Logger, AgentResult, Action, LoadState } from "../public/index.js";
+import { CacheStorage } from "../../cache/CacheStorage.js";
+import type { ActHandler } from "../../handlers/actHandler.js";
+import type { V3Context } from "../../understudy/context.js";
+import type { LLMClient } from "../../llm/LLMClient.js";
+export type ActFn = (instruction: string, options?: ActOptions) => Promise<ActResult>;
+export type AgentCacheContext = {
+    instruction: string;
+    startUrl: string;
+    options: SanitizedAgentExecuteOptions;
+    configSignature: string;
+    cacheKey: string;
+    variableKeys: string[] /** Variable keys used in this execution (for cache key) */;
+    /** Variable values to substitute during replay */
+    variables?: Record<string, string>;
+};
+export type AgentCacheTransferPayload = {
+    cacheKey: string;
+    entry: CachedAgentEntry;
+};
+export type AgentCacheDeps = {
+    storage: CacheStorage;
+    logger: Logger;
+    getActHandler: () => ActHandler | null;
+    getContext: () => V3Context | null;
+    getDefaultLlmClient: () => LLMClient;
+    getBaseModelName: () => AvailableModel;
+    getSystemPrompt: () => string | undefined;
+    domSettleTimeoutMs?: number;
+    act: ActFn;
+    bufferLatestEntry?: boolean;
+};
+export type ActCacheContext = {
+    instruction: string;
+    cacheKey: string;
+    pageUrl: string;
+    variableKeys: string[];
+    variables?: Record<string, string>;
+};
+export type ActCacheDeps = {
+    storage: CacheStorage;
+    logger: Logger;
+    getActHandler: () => ActHandler | null;
+    getDefaultLlmClient: () => LLMClient;
+    domSettleTimeoutMs?: number;
+};
+export type ReadJsonResult<T> = {
+    value: T | null;
+    path?: string;
+    error?: unknown;
+};
+export type WriteJsonResult = {
+    path?: string;
+    error?: unknown;
+};
+export interface CachedActEntry {
+    version: 1;
+    instruction: string;
+    url: string;
+    variableKeys: string[];
+    actions: Action[];
+    actionDescription?: string;
+    message?: string;
+}
+export type AgentReplayStep = AgentReplayActStep | AgentReplayFillFormStep | AgentReplayGotoStep | AgentReplayScrollStep | AgentReplayWaitStep | AgentReplayNavBackStep | AgentReplayKeysStep | {
+    type: string;
+    [key: string]: unknown;
+};
+export interface AgentReplayActStep {
+    type: "act";
+    instruction: string;
+    actions?: Action[];
+    actionDescription?: string;
+    message?: string;
+    timeout?: number;
+}
+export interface AgentReplayFillFormStep {
+    type: "fillForm";
+    fields?: Array<{
+        action: string;
+        value: string;
+    }>;
+    observeResults?: Action[];
+    actions?: Action[];
+}
+export interface AgentReplayGotoStep {
+    type: "goto";
+    url: string;
+    waitUntil?: LoadState;
+}
+export interface AgentReplayScrollStep {
+    type: "scroll";
+    deltaX?: number;
+    deltaY?: number;
+    anchor?: {
+        x: number;
+        y: number;
+    };
+}
+export interface AgentReplayWaitStep {
+    type: "wait";
+    timeMs: number;
+}
+export interface AgentReplayNavBackStep {
+    type: "navback";
+    waitUntil?: LoadState;
+}
+export interface AgentReplayKeysStep {
+    type: "keys";
+    instruction?: string;
+    playwrightArguments: {
+        method: "type" | "press";
+        text?: string;
+        keys?: string;
+        times?: number;
+    };
+}
+export interface SanitizedAgentExecuteOptions {
+    maxSteps?: number;
+    highlightCursor?: boolean;
+}
+export interface CachedAgentEntry {
+    version: 1;
+    instruction: string;
+    startUrl: string;
+    options: SanitizedAgentExecuteOptions;
+    configSignature: string;
+    steps: AgentReplayStep[];
+    result: AgentResult;
+    timestamp: string;
+}

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../../../../../../lib/v3/types/private/cache.ts"],"names":[],"mappings":"","sourcesContent":["import type {\n  ActOptions,\n  ActResult,\n  AvailableModel,\n  Logger,\n  AgentResult,\n  Action,\n  LoadState,\n} from \"../public/index.js\";\nimport { CacheStorage } from \"../../cache/CacheStorage.js\";\nimport type { ActHandler } from \"../../handlers/actHandler.js\";\nimport type { V3Context } from \"../../understudy/context.js\";\nimport type { LLMClient } from \"../../llm/LLMClient.js\";\n\nexport type ActFn = (\n  instruction: string,\n  options?: ActOptions,\n) => Promise<ActResult>;\n\nexport type AgentCacheContext = {\n  instruction: string;\n  startUrl: string;\n  options: SanitizedAgentExecuteOptions;\n  configSignature: string;\n  cacheKey: string;\n  variableKeys: string[] /** Variable keys used in this execution (for cache key) */;\n  /** Variable values to substitute during replay */\n  variables?: Record<string, string>;\n};\n\nexport type AgentCacheTransferPayload = {\n  cacheKey: string;\n  entry: CachedAgentEntry;\n};\n\nexport type AgentCacheDeps = {\n  storage: CacheStorage;\n  logger: Logger;\n  getActHandler: () => ActHandler | null;\n  getContext: () => V3Context | null;\n  getDefaultLlmClient: () => LLMClient;\n  getBaseModelName: () => AvailableModel;\n  getSystemPrompt: () => string | undefined;\n  domSettleTimeoutMs?: number;\n  act: ActFn;\n  bufferLatestEntry?: boolean;\n};\n\nexport type ActCacheContext = {\n  instruction: string;\n  cacheKey: string;\n  pageUrl: string;\n  variableKeys: string[];\n  variables?: Record<string, string>;\n};\n\nexport type ActCacheDeps = {\n  storage: CacheStorage;\n  logger: Logger;\n  getActHandler: () => ActHandler | null;\n  getDefaultLlmClient: () => LLMClient;\n  domSettleTimeoutMs?: number;\n};\n\nexport type ReadJsonResult<T> = {\n  value: T | null;\n  path?: string;\n  error?: unknown;\n};\n\nexport type WriteJsonResult = {\n  path?: string;\n  error?: unknown;\n};\n\nexport interface CachedActEntry {\n  version: 1;\n  instruction: string;\n  url: string;\n  variableKeys: string[];\n  actions: Action[];\n  actionDescription?: string;\n  message?: string;\n}\n\nexport type AgentReplayStep =\n  | AgentReplayActStep\n  | AgentReplayFillFormStep\n  | AgentReplayGotoStep\n  | AgentReplayScrollStep\n  | AgentReplayWaitStep\n  | AgentReplayNavBackStep\n  | AgentReplayKeysStep\n  | { type: string; [key: string]: unknown };\n\nexport interface AgentReplayActStep {\n  type: \"act\";\n  instruction: string;\n  actions?: Action[];\n  actionDescription?: string;\n  message?: string;\n  timeout?: number;\n}\n\nexport interface AgentReplayFillFormStep {\n  type: \"fillForm\";\n  fields?: Array<{ action: string; value: string }>;\n  observeResults?: Action[];\n  actions?: Action[];\n}\n\nexport interface AgentReplayGotoStep {\n  type: \"goto\";\n  url: string;\n  waitUntil?: LoadState;\n}\n\nexport interface AgentReplayScrollStep {\n  type: \"scroll\";\n  deltaX?: number;\n  deltaY?: number;\n  anchor?: { x: number; y: number };\n}\n\nexport interface AgentReplayWaitStep {\n  type: \"wait\";\n  timeMs: number;\n}\n\nexport interface AgentReplayNavBackStep {\n  type: \"navback\";\n  waitUntil?: LoadState;\n}\n\nexport interface AgentReplayKeysStep {\n  type: \"keys\";\n  instruction?: string;\n  playwrightArguments: {\n    method: \"type\" | \"press\";\n    text?: string;\n    keys?: string;\n    times?: number;\n  };\n}\n\nexport interface SanitizedAgentExecuteOptions {\n  maxSteps?: number;\n  highlightCursor?: boolean;\n}\n\nexport interface CachedAgentEntry {\n  version: 1;\n  instruction: string;\n  startUrl: string;\n  options: SanitizedAgentExecuteOptions;\n  configSignature: string;\n  steps: AgentReplayStep[];\n  result: AgentResult;\n  timestamp: string;\n}\n"]}

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

@@ -0,0 +1,40 @@
+export type EvaluateOptions = {
+    /** The question to ask about the task state */
+    question: string;
+    /** The answer to the question */
+    answer?: string;
+    /** Whether to take a screenshot of the task state, or array of screenshots to evaluate */
+    screenshot?: boolean | Buffer[];
+    /** Custom system prompt for the evaluator */
+    systemPrompt?: string;
+    /** Delay in milliseconds before taking the screenshot @default 250 */
+    screenshotDelayMs?: number;
+    /** The agent's reasoning/thought process for completing the task */
+    agentReasoning?: string;
+};
+export type BatchAskOptions = {
+    /** Array of questions with optional answers */
+    questions: Array<{
+        question: string;
+        answer?: string;
+    }>;
+    /** Whether to take a screenshot of the task state */
+    screenshot?: boolean;
+    /** Custom system prompt for the evaluator */
+    systemPrompt?: string;
+    /** Delay in milliseconds before taking the screenshot @default 1000 */
+    screenshotDelayMs?: number;
+};
+/**
+ * Result of an evaluation
+ */
+export interface EvaluationResult {
+    /**
+     * The evaluation result ('YES', 'NO', or 'INVALID' if parsing failed or value was unexpected)
+     */
+    evaluation: "YES" | "NO" | "INVALID";
+    /**
+     * The reasoning behind the evaluation
+     */
+    reasoning: string;
+}

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"evaluator.js","sourceRoot":"","sources":["../../../../../../lib/v3/types/private/evaluator.ts"],"names":[],"mappings":"","sourcesContent":["export type EvaluateOptions = {\n  /** The question to ask about the task state */\n  question: string;\n  /** The answer to the question */\n  answer?: string;\n  /** Whether to take a screenshot of the task state, or array of screenshots to evaluate */\n  screenshot?: boolean | Buffer[];\n  /** Custom system prompt for the evaluator */\n  systemPrompt?: string;\n  /** Delay in milliseconds before taking the screenshot @default 250 */\n  screenshotDelayMs?: number;\n  /** The agent's reasoning/thought process for completing the task */\n  agentReasoning?: string;\n};\n\nexport type BatchAskOptions = {\n  /** Array of questions with optional answers */\n  questions: Array<{\n    question: string;\n    answer?: string;\n  }>;\n  /** Whether to take a screenshot of the task state */\n  screenshot?: boolean;\n  /** Custom system prompt for the evaluator */\n  systemPrompt?: string;\n  /** Delay in milliseconds before taking the screenshot @default 1000 */\n  screenshotDelayMs?: number;\n};\n\n/**\n * Result of an evaluation\n */\nexport interface EvaluationResult {\n  /**\n   * The evaluation result ('YES', 'NO', or 'INVALID' if parsing failed or value was unexpected)\n   */\n  evaluation: \"YES\" | \"NO\" | \"INVALID\";\n  /**\n   * The reasoning behind the evaluation\n   */\n  reasoning: string;\n}\n"]}

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

@@ -0,0 +1,39 @@
+import { Page } from "../../understudy/page.js";
+import { ModelConfiguration } from "../public/model.js";
+import type { StagehandZodSchema } from "../../zodCompat.js";
+import type { Variables } from "../public/agent.js";
+export interface ActHandlerParams {
+    instruction: string;
+    model?: ModelConfiguration;
+    variables?: Variables;
+    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":"AA8BA,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\";\nimport type { Variables } from \"../public/agent.js\";\n\nexport interface ActHandlerParams {\n  instruction: string;\n  model?: ModelConfiguration;\n  variables?: Variables;\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,19 @@
+/**
+ * Internal-only types for the shutdown supervisor process.
+ */
+export type ShutdownSupervisorConfig = {
+    kind: "LOCAL";
+    pid: number;
+    userDataDir?: string;
+    createdTempProfile?: boolean;
+    preserveUserDataDir?: boolean;
+} | {
+    kind: "STAGEHAND_API";
+    sessionId: string;
+    apiKey: string;
+    projectId?: string;
+};
+export interface ShutdownSupervisorHandle {
+    /** Best-effort signal to stop the supervisor process. */
+    stop: () => 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      pid: number;\n      userDataDir?: string;\n      createdTempProfile?: boolean;\n      preserveUserDataDir?: boolean;\n    }\n  | {\n      kind: \"STAGEHAND_API\";\n      sessionId: string;\n      apiKey: string;\n      projectId?: string;\n    };\n\nexport interface ShutdownSupervisorHandle {\n  /** Best-effort signal to stop the supervisor process. */\n  stop: () => 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"]}