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

package/dist/cjs/lib/v3/understudy/frameRegistry.d.ts

@@ -0,0 +1,101 @@
+import type { Protocol } from "devtools-protocol";
+/**
+ * FrameRegistry
+ *
+ * Purpose:
+ * A single, authoritative source of truth for **both**:
+ *   1) Frame topology (parent/children, current main/root id, last-seen CDP `Frame`)
+ *   2) Frame → Session ownership (which CDP session owns a given frameId)
+ *   3) Optional iframe-owner metadata (backendNodeId of the <iframe> element in the parent doc)
+ *
+ *
+ * Model:
+ *  - This class is **CDP-agnostic**; it stores **sessionId strings** (not session objects).
+ *  - Context bridges (wiring Target/Page events) must call the mutators below (onAttached,
+ *    onNavigated, onDetached, adoptChildSession, seedFromFrameTree, setOwnerBackendNodeId).
+ *  - Consumers ask read APIs (getOwnerSessionId, getParent, asProtocolFrameTree, listAll, …)
+ *    and never probe ownership at run time.
+ */
+type FrameId = string;
+type SessionId = string;
+export declare class FrameRegistry {
+    /** Owner target id (top-level target); informational only */
+    private readonly ownerTargetId;
+    /** Current main/root frame id (changes on root swaps) */
+    private rootFrameId;
+    /** frameId → FrameInfo */
+    private frames;
+    /** sessionId → Set<frameId> (inverse map for diagnostics/fast membership checks) */
+    private framesBySession;
+    constructor(ownerTargetId: string, mainFrameId: FrameId);
+    /**
+     * Record that a frame attached. If `parentId` is null and `frameId` differs from the current
+     * root, this is a root swap and we rename the root id.
+     *
+     * IMPORTANT: The emitter's `sessionId` is the **owner** for the new/attached frame.
+     */
+    onFrameAttached(frameId: FrameId, parentId: FrameId | null, sessionId: SessionId): void;
+    /**
+     * Record a navigation with the full CDP `Frame`. Also updates ownership based on the emitting
+     * session id. Handles root swap if the navigated frame is the new main (no parentId).
+     */
+    onFrameNavigated(frame: Protocol.Page.Frame, sessionId: SessionId): void;
+    onNavigatedWithinDocument(frameId: FrameId, url: string, sessionId: SessionId): void;
+    /**
+     * Record that a frame detached. If `reason !== "swap"`, remove the subtree from the graph,
+     * and clean the inverse maps. For “swap” we keep the node to preserve continuity.
+     */
+    onFrameDetached(frameId: FrameId, reason?: "remove" | "swap" | string): void;
+    /**
+     * An adopted OOPIF child session was created whose **main** frame id equals the parent iframe’s frameId.
+     * We mark the entire child subtree as owned by `childSessionId`.
+     * (Topology edges remain aligned by the parent session’s `frameAttached` events.)
+     */
+    adoptChildSession(childSessionId: SessionId, childMainFrameId: FrameId): void;
+    /**
+     * Seed topology and ownership from an existing `Page.getFrameTree` snapshot, typically right after
+     * a session is attached. This is a best-effort: we record frames and set the provided `sessionId`
+     * as owner for the subtree **if** an owner isn't already set.
+     */
+    seedFromFrameTree(sessionId: SessionId, frameTree: Protocol.Page.FrameTree): void;
+    /**
+     * Set the backendNodeId of the `<iframe>` element for a child frame **as seen from its parent**.
+     * This is useful for building absolute XPath prefixes later (from the parent document).
+     */
+    setOwnerBackendNodeId(childFrameId: FrameId, backendNodeId: number): void;
+    mainFrameId(): FrameId;
+    /**
+     * Return the owner session id for this frame. If unknown, returns `undefined`.
+     */
+    getOwnerSessionId(frameId: FrameId): SessionId | undefined;
+    /**
+     * Return the owner backendNodeId (iframe element) if recorded.
+     * This is in the **parent** document; pair it with `getParent`.
+     */
+    getOwnerBackendNodeId(frameId: FrameId): number | undefined;
+    /**
+     * Return the parent frame id, or null for root/unknown.
+     */
+    getParent(frameId: FrameId): FrameId | null;
+    /**
+     * List frame ids in root-first DFS order (same shape as CDP’s FrameTree traversal).
+     */
+    listAllFrames(): FrameId[];
+    /**
+     * Serialize to `Protocol.Page.FrameTree` starting at the given root id (typically mainFrameId()).
+     */
+    asProtocolFrameTree(rootId: FrameId): Protocol.Page.FrameTree;
+    /**
+     * For diagnostics: return the current owner sessions for a frame id (0..n),
+     * usually 0 or 1, but helpful to see potential inconsistencies during wiring.
+     */
+    sessionsForFrame(frameId: FrameId): SessionId[];
+    /**
+     * For diagnostics: return current frame set per session.
+     */
+    framesForSession(sessionId: SessionId): FrameId[];
+    private ensureNode;
+    private renameNodeId;
+    private setOwnerSessionIdInternal;
+}
+export {};

package/dist/cjs/lib/v3/understudy/initScripts.d.ts

@@ -0,0 +1,2 @@
+import { InitScriptSource } from "../types/private/index.js";
+export declare function normalizeInitScriptSource<Arg>(script: InitScriptSource<Arg>, arg?: Arg, caller?: string): Promise<string>;

package/dist/cjs/lib/v3/understudy/lifecycleWatcher.d.ts

@@ -0,0 +1,64 @@
+import type { LoadState } from "../types/public/page.js";
+import type { CDPSessionLike } from "./cdp.js";
+import type { NetworkManager } from "./networkManager.js";
+import type { Page } from "./page.js";
+/**
+ * Coordinates page lifecycle waits (load/domcontentloaded/networkidle) while
+ * following main-frame swaps and navigation aborts. Each navigation spawns a
+ * one-off watcher that listens for relevant CDP events and resolves or rejects
+ * depending on the requested `waitUntil` state.
+ */
+/**
+ * Small utility that mirrors Playwright's lifecycle watcher semantics. Bridges
+ * main-frame lifecycle events with the NetworkManager's idle signal so callers
+ * can await `load`, `domcontentloaded`, or `networkidle` with a single promise.
+ */
+export declare class LifecycleWatcher {
+    private readonly page;
+    private readonly mainSession;
+    private readonly networkManager;
+    private readonly waitUntil;
+    private readonly timeoutMs;
+    private readonly startTime;
+    private readonly navigationCommandId;
+    private currentLoaderId;
+    private idleStartTime;
+    private cleanupCallbacks;
+    private idleHandle;
+    private abortReject;
+    private abortPromise;
+    private abortError;
+    private disposed;
+    private expectedLoaderId;
+    private initialLoaderId;
+    private pendingFollowupNavigation;
+    /**
+     * Create a watcher; callers should subsequently invoke {@link wait}.
+     */
+    constructor(params: {
+        page: Page;
+        mainSession: CDPSessionLike;
+        networkManager: NetworkManager;
+        waitUntil: LoadState;
+        timeoutMs: number;
+        navigationCommandId: number;
+    });
+    /** Hint the watcher with the loader id returned by Page.navigate. */
+    setExpectedLoaderId(loaderId: string | undefined): void;
+    /** Wait for the requested lifecycle state or throw on timeout/abort. */
+    wait(): Promise<void>;
+    /** Cancel any outstanding network-idle waits and remove event listeners. */
+    dispose(): void;
+    /** Subscribe to main-frame events to detect abort conditions. */
+    private installSessionListeners;
+    /** Compute remaining time until the shared deadline elapses. */
+    private timeRemaining;
+    /** Await an operation but abort early if navigation replacement fires. */
+    private awaitWithAbort;
+    /** Mark the watcher as aborted and reject any pending waiters. */
+    private triggerAbort;
+    private waitForNetworkIdle;
+    private shouldRestartAfterFollowup;
+    private adoptNewMainLoader;
+    private buildIdleFilter;
+}

package/dist/cjs/lib/v3/understudy/locator.d.ts

@@ -0,0 +1,194 @@
+import { Protocol } from "devtools-protocol";
+import type { Frame } from "./frame.js";
+import { SetInputFilesArgument, MouseButton } from "../types/public/locator.js";
+/**
+ * Locator
+ *
+ * Purpose:
+ * A small, CDP-based element interaction helper scoped to a specific `Frame`.
+ * It resolves a CSS/XPath selector inside the frame’s **isolated world**, and then
+ * performs low-level actions (click, type, select) using DOM/Runtime/Input
+ * protocol domains with minimal abstraction.
+ *
+ * Key change:
+ * - Prefer **objectId**-based CDP calls (scroll, geometry) to avoid brittle
+ *   frontend nodeId mappings. nodeId is resolved on a best-effort basis and
+ *   returned for compatibility, but actions do not depend on it.
+ *
+ * Notes:
+ * - Resolution is lazy: every action resolves the selector again.
+ * - Uses `Page.createIsolatedWorld` so evaluation is isolated from page scripts.
+ * - Releases remote objects (`Runtime.releaseObject`) where appropriate.
+ */
+export declare class Locator {
+    private readonly frame;
+    private readonly selector;
+    private readonly options?;
+    private readonly selectorResolver;
+    private readonly selectorQuery;
+    private readonly nthIndex;
+    constructor(frame: Frame, selector: string, options?: {
+        deep?: boolean;
+        depth?: number;
+    }, nthIndex?: number);
+    /** Return the owning Frame for this locator (typed accessor, no private access). */
+    getFrame(): Frame;
+    /**
+     * Set files on an <input type="file"> element.
+     *
+     * Mirrors Playwright's Locator.setInputFiles basics:
+     * - Accepts file path(s) or payload object(s) { name, mimeType, buffer }.
+     * - Uses CDP DOM.setFileInputFiles under the hood.
+     * - Best‑effort dispatches change/input via CDP (Chrome does by default).
+     * - Passing an empty array clears the selection.
+     */
+    setInputFiles(files: SetInputFilesArgument): Promise<void>;
+    /**
+     * Remote browser fallback: build File objects inside the page and attach them via JS.
+     *
+     * When Stagehand is driving a browser that cannot see the local filesystem (Browserbase,
+     * remote CDP, etc.), CDP's DOM.setFileInputFiles would fail because Chrome can't reach
+     * our temp files. Instead we base64-encode the payloads, send them into the page, and
+     * let a DOM helper create File objects + dispatch change/input events.
+     */
+    private assignFilesViaPayloadInjection;
+    /**
+     * Return the DOM backendNodeId for this locator's target element.
+     * Useful for identity comparisons without needing element handles.
+     */
+    backendNodeId(): Promise<Protocol.DOM.BackendNodeId>;
+    /** Return how many nodes the current selector resolves to. */
+    count(): Promise<number>;
+    /**
+     * Return the center of the element's bounding box in the owning frame's viewport
+     * (CSS pixels), rounded to integers. Scrolls into view best-effort.
+     */
+    centroid(): Promise<{
+        x: number;
+        y: number;
+    }>;
+    /**
+     * Highlight the element's bounding box using the CDP Overlay domain.
+     * - Scrolls element into view best-effort.
+     * - Shows a semi-transparent overlay briefly, then hides it.
+     */
+    highlight(options?: {
+        durationMs?: number;
+        borderColor?: {
+            r: number;
+            g: number;
+            b: number;
+            a?: number;
+        };
+        contentColor?: {
+            r: number;
+            g: number;
+            b: number;
+            a?: number;
+        };
+    }): Promise<void>;
+    /**
+     * Move the mouse cursor to the element's visual center without clicking.
+     * - Scrolls into view best-effort, resolves geometry, then dispatches a mouse move.
+     */
+    hover(): Promise<void>;
+    /**
+     * Click the element at its visual center.
+     * Steps:
+     *  1) Resolve selector to { objectId } in the frame world.
+     *  2) Scroll into view via `DOM.scrollIntoViewIfNeeded({ objectId })`.
+     *  3) Read geometry via `DOM.getBoxModel({ objectId })` → compute a center point.
+     *  4) Synthesize mouse press + release via `Input.dispatchMouseEvent`.
+     */
+    click(options?: {
+        button?: MouseButton;
+        clickCount?: number;
+    }): Promise<void>;
+    /**
+     * Dispatch a DOM 'click' MouseEvent on the element itself.
+     * - Does not synthesize real pointer input; directly dispatches an event.
+     * - Useful for elements that rely on click handlers without needing hit-testing.
+     */
+    sendClickEvent(options?: {
+        bubbles?: boolean;
+        cancelable?: boolean;
+        composed?: boolean;
+        detail?: number;
+    }): Promise<void>;
+    /**
+     * Scroll the element vertically to a given percentage (0–100).
+     * - If the element is <html> or <body>, scrolls the window/document.
+     * - Otherwise, scrolls the element itself via element.scrollTo.
+     */
+    scrollTo(percent: number | string): Promise<void>;
+    /**
+     * Fill an input/textarea/contenteditable element.
+     * Mirrors Playwright semantics: the DOM helper either applies the native
+     * value setter (for special input types) or asks us to type text via the CDP
+     * Input domain after focusing/selecting.
+     */
+    fill(value: string): Promise<void>;
+    /**
+     * Type text into the element (focuses first).
+     * - Focus via element.focus() in page JS (no DOM.focus(nodeId)).
+     * - If no delay, uses `Input.insertText` for efficiency.
+     * - With delay, synthesizes `keyDown`/`keyUp` per character.
+     */
+    type(text: string, options?: {
+        delay?: number;
+    }): Promise<void>;
+    /**
+     * Select one or more options on a `<select>` element.
+     * Returns the values actually selected after the operation.
+     */
+    selectOption(values: string | string[]): Promise<string[]>;
+    /**
+     * Return true if the element is attached and visible (rough heuristic).
+     */
+    isVisible(): Promise<boolean>;
+    /**
+     * Return true if the element is an input[type=checkbox|radio] and is checked.
+     * Also considers aria-checked for ARIA widgets.
+     */
+    isChecked(): Promise<boolean>;
+    /**
+     * Return the element's input value (for input/textarea/select/contenteditable).
+     */
+    inputValue(): Promise<string>;
+    /**
+     * Return the element's textContent (raw, not innerText).
+     */
+    textContent(): Promise<string>;
+    /**
+     * Return the element's innerHTML string.
+     */
+    innerHtml(): Promise<string>;
+    /**
+     * Return the element's innerText (layout-aware, visible text).
+     */
+    innerText(): Promise<string>;
+    /**
+     * Return a locator narrowed to the first match.
+     */
+    first(): Locator;
+    /** Return a locator narrowed to the element at the given zero-based index. */
+    nth(index: number): Locator;
+    /**
+     * Resolve `this.selector` within the frame to `{ objectId, nodeId? }`:
+     * Delegates to a shared selector resolver so all selector logic stays in sync.
+     */
+    resolveNode(): Promise<{
+        nodeId: Protocol.DOM.NodeId | null;
+        objectId: Protocol.Runtime.RemoteObjectId;
+    }>;
+    /**
+     * Resolve all matching nodes for this locator.
+     * If the locator is narrowed via nth(), only that index is returned.
+     */
+    resolveNodesForMask(): Promise<Array<{
+        nodeId: Protocol.DOM.NodeId | null;
+        objectId: Protocol.Runtime.RemoteObjectId;
+    }>>;
+    /** Compute a center point from a BoxModel content quad */
+    private centerFromBoxContent;
+}

package/dist/cjs/lib/v3/understudy/locatorInvocation.d.ts

@@ -0,0 +1,8 @@
+import { type LocatorScriptName } from "../dom/build/locatorScripts.generated.js";
+/**
+ * Build an expression that injects the locator bundle (if needed) and invokes a
+ * specific helper via its stable global reference. This keeps Runtime.evaluate
+ * payloads tiny while guaranteeing our selector utilities are present in any
+ * execution context.
+ */
+export declare function buildLocatorInvocation(name: LocatorScriptName, args: string[]): string;

package/dist/cjs/lib/v3/understudy/navigationResponseTracker.d.ts

@@ -0,0 +1,84 @@
+/**
+ * NavigationResponseTracker
+ * -------------------------
+ *
+ * Tracks DevTools Protocol network events for a single navigation command so
+ * Stagehand can surface a Playwright-like response object from `Page.goto` and
+ * related APIs. The tracker listens for `Network.responseReceived` events that
+ * correspond to the targeted document navigation, handles loader-id churn that
+ * arises from redirects or preloading, and enriches the resulting
+ * `Response` with extra header information. It also observes
+ * `Network.loadingFinished` / `Network.loadingFailed` to fulfil the
+ * `response.finished()` contract exposed to consumers.
+ */
+import type { CDPSessionLike } from "./cdp.js";
+import type { Page } from "./page.js";
+import { Response } from "./response.js";
+/**
+ * Watches CDP events on a given session and resolves with the navigation's
+ * primary document response once identified.
+ */
+export declare class NavigationResponseTracker {
+    private readonly page;
+    private readonly session;
+    private readonly navigationCommandId;
+    private expectedLoaderId;
+    private selectedRequestId;
+    private selectedResponse;
+    private acceptNextWithoutLoader;
+    private responseResolved;
+    private resolveResponse;
+    private responsePromise;
+    private readonly pendingResponsesByLoader;
+    private readonly pendingExtraInfo;
+    private readonly listeners;
+    /**
+     * Create a tracker bound to a specific navigation command. The tracker begins
+     * listening for network events immediately so it should be constructed before
+     * the navigation request is dispatched.
+     */
+    constructor(params: {
+        page: Page;
+        session: CDPSessionLike;
+        navigationCommandId: number;
+    });
+    /** Stop listening for CDP events and release any pending bookkeeping. */
+    dispose(): void;
+    /**
+     * Hint the tracker with the loader id returned by `Page.navigate`. Chrome only
+     * emits this once the browser begins navigating, so we store early responses
+     * and match them once the loader id is known.
+     */
+    setExpectedLoaderId(loaderId: string | undefined): void;
+    /**
+     * Some navigation APIs (reload/history traversal) do not provide a loader id
+     * up front. This flag instructs the tracker to accept the next qualifying
+     * document response even if no loader id has been announced yet.
+     */
+    expectNavigationWithoutKnownLoader(): void;
+    /**
+     * Returns a promise that resolves with the matched response (or `null` when
+     * no document response was observed).
+     */
+    navigationCompleted(): Promise<Response | null>;
+    /** Expose the raw response promise (mainly for tests). */
+    response(): Promise<Response | null>;
+    /** Register all CDP listeners relevant to navigation tracking. */
+    private installListeners;
+    /** Attach a CDP listener and track it for later disposal. */
+    private addListener;
+    /** Handle the initial response payload for document navigations. */
+    private onResponseReceived;
+    /** Merge auxiliary header information once Chrome exposes it. */
+    private onResponseReceivedExtraInfo;
+    /** Resolve the response's finished promise when the request completes. */
+    private onLoadingFinished;
+    /** Resolve the response's finished promise with an error on failure. */
+    private onLoadingFailed;
+    /**
+     * Create the `Response` wrapper for the chosen document response and
+     * resolve awaiting consumers. Subsequent events flesh out the header/body
+     * helpers and mark the request as finished.
+     */
+    private selectResponse;
+}

package/dist/cjs/lib/v3/understudy/networkManager.d.ts

@@ -0,0 +1,53 @@
+import type { CDPSessionLike } from "./cdp.js";
+import { NetworkObserver, WaitForIdleHandle, WaitForIdleOptions } from "../types/private/network.js";
+/**
+ * Cross-session network tracker.
+ *
+ * Centralises network bookkeeping for a Page: every CDP session (top-level and OOPIF)
+ * funnels `Network.*` events through here so higher-level waiters can reason about
+ * in-flight requests across the entire frame tree. The manager exposes a simple
+ * observer interface plus a "wait until idle" helper that resolves once no filtered
+ * requests remain for a quiet window.
+ */
+/**
+ * Aggregates network information for all CDP sessions owned by a Page.
+ */
+export declare class NetworkManager {
+    private readonly sessions;
+    private readonly observers;
+    private readonly requests;
+    private readonly documentRequestsByFrame;
+    /**
+     * Begin tracking network traffic for a CDP session (top-level or OOPIF).
+     * Safe to call multiple times; duplicate registrations are ignored.
+     */
+    trackSession(session: CDPSessionLike): void;
+    /**
+     * Stop tracking a session and discard any inflight bookkeeping owned by it.
+     */
+    untrackSession(rawSessionId: string | undefined): void;
+    /**
+     * Register a passive observer for request lifecycle notifications.
+     * Returns a disposer that removes the observer.
+     */
+    addObserver(observer: NetworkObserver): () => void;
+    /**
+     * Resolve once no (filtered) requests are in flight for the given quiet window.
+     * The waiter automatically unregisters itself on completion or timeout.
+     */
+    waitForIdle(options: WaitForIdleOptions): WaitForIdleHandle;
+    /**
+     * Tear down all session listeners and clear observers/bookkeeping.
+     */
+    dispose(): void;
+    /** Fan-out helper when a tracked request starts. */
+    private emitStart;
+    /** Fan-out helper when a tracked request completes successfully. */
+    private emitFinish;
+    /** Fan-out helper when a tracked request fails mid-flight. */
+    private emitFailure;
+    /** Compute a stable key for a session (falls back to synthetic root id). */
+    private sessionKey;
+    /** Compose the unique key for tracking a request under a session. */
+    private requestKey;
+}