@browserbasehq/orca 3.1.0-patch.0 → 3.1.0-patch.1

package/dist/cjs/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/cjs/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/cjs/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/cjs/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[];
+};