@browserbasehq/orca 3.0.0-preview.0

package/dist/lib/v3/understudy/deepLocator.d.ts

@@ -0,0 +1,69 @@
+import { Locator } from "./locator";
+import type { Frame } from "./frame";
+import type { Page } from "./page";
+/** Build a Locator scoped to the correct frame for a deep XPath crossing iframes. */
+export declare function deepLocatorThroughIframes(page: Page, root: Frame, xpathOrSelector: string): Promise<Locator>;
+/**
+ * Unified resolver that supports '>>' hop notation, deep XPath across iframes,
+ * and plain single-frame selectors. Keeps hop logic in one shared place.
+ */
+export declare function resolveLocatorWithHops(page: Page, root: Frame, selectorRaw: string): Promise<Locator>;
+/**
+ * DeepLocatorDelegate: a lightweight wrapper that looks like a Locator and
+ * resolves to the correct frame/element on each call using hop/deep-XPath logic.
+ *
+ * Returned by `page.deepLocator()` for ergonomic, await-free chaining:
+ *   page.deepLocator('iframe#ifrA >> #btn').click()
+ */
+export declare class DeepLocatorDelegate {
+    private readonly page;
+    private readonly root;
+    private readonly selector;
+    constructor(page: Page, root: Frame, selector: string);
+    private real;
+    click(options?: {
+        button?: "left" | "right" | "middle";
+        clickCount?: number;
+    }): Promise<void>;
+    fill(value: string): Promise<void>;
+    type(text: string, options?: {
+        delay?: number;
+    }): Promise<void>;
+    selectOption(values: string | string[]): Promise<string[]>;
+    scrollTo(percent: number | string): Promise<void>;
+    isVisible(): Promise<boolean>;
+    isChecked(): Promise<boolean>;
+    inputValue(): Promise<string>;
+    textContent(): Promise<string>;
+    innerHtml(): Promise<string>;
+    innerText(): Promise<string>;
+    centroid(): Promise<{
+        x: number;
+        y: number;
+    }>;
+    backendNodeId(): Promise<number>;
+    highlight(options?: {
+        durationMs?: number;
+        borderColor?: {
+            r: number;
+            g: number;
+            b: number;
+            a?: number;
+        };
+        contentColor?: {
+            r: number;
+            g: number;
+            b: number;
+            a?: number;
+        };
+    }): Promise<void>;
+    sendClickEvent(options?: {
+        bubbles?: boolean;
+        cancelable?: boolean;
+        composed?: boolean;
+        detail?: number;
+    }): Promise<void>;
+    first(): this;
+}
+/** Factory to create a deep locator delegate from a Page + root frame. */
+export declare function deepLocatorFromPage(page: Page, root: Frame, selector: string): DeepLocatorDelegate;

package/dist/lib/v3/understudy/executionContextRegistry.d.ts

@@ -0,0 +1,15 @@
+import type { Protocol } from "devtools-protocol";
+import type { CDPSessionLike } from "./cdp";
+type FrameId = Protocol.Page.FrameId;
+type ExecId = Protocol.Runtime.ExecutionContextId;
+export declare class ExecutionContextRegistry {
+    private readonly byFrame;
+    private readonly byExec;
+    /** Wire listeners for this session. Call BEFORE Runtime.enable. */
+    attachSession(session: CDPSessionLike): void;
+    getMainWorld(session: CDPSessionLike, frameId: FrameId): ExecId | null;
+    waitForMainWorld(session: CDPSessionLike, frameId: FrameId, timeoutMs?: number): Promise<ExecId>;
+    private register;
+}
+export declare const executionContexts: ExecutionContextRegistry;
+export {};

package/dist/lib/v3/understudy/frame.d.ts

@@ -0,0 +1,63 @@
+import { Protocol } from "devtools-protocol";
+import type { CDPSessionLike } from "./cdp";
+import { Locator } from "./locator";
+interface FrameManager {
+    session: CDPSessionLike;
+    frameId: string;
+    pageId: string;
+}
+/**
+ * Frame
+ *
+ * A thin, session-bound handle to a specific DOM frame (by frameId).
+ * All CDP calls in this class go through `this.session`, which MUST be the
+ * owning session for `this.frameId`. Page is responsible for constructing
+ * Frames with the correct session.
+ */
+export declare class Frame implements FrameManager {
+    session: CDPSessionLike;
+    frameId: string;
+    pageId: string;
+    /** Owning CDP session id (useful for logs); null for root connection (should not happen for targets) */
+    readonly sessionId: string | null;
+    constructor(session: CDPSessionLike, frameId: string, pageId: string);
+    /** DOM.getNodeForLocation → DOM.describeNode */
+    getNodeAtLocation(x: number, y: number): Promise<Protocol.DOM.Node>;
+    /** CSS selector → DOM.querySelector → DOM.getBoxModel */
+    getLocationForSelector(selector: string): Promise<{
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }>;
+    /** Accessibility.getFullAXTree (+ recurse into child frames if requested) */
+    getAccessibilityTree(withFrames?: boolean): Promise<Protocol.Accessibility.AXNode[]>;
+    /**
+     * Evaluate a function or expression in this frame's isolated world.
+     * - If a string is provided, treated as a JS expression.
+     * - If a function is provided, it is stringified and invoked with the optional argument.
+     */
+    evaluate<R = unknown, Arg = unknown>(pageFunctionOrExpression: string | ((arg: Arg) => R | Promise<R>), arg?: Arg): Promise<R>;
+    /** Page.captureScreenshot (frame-scoped session) */
+    screenshot(options?: {
+        fullPage?: boolean;
+        clip?: {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        };
+    }): Promise<string>;
+    /** Child frames via Page.getFrameTree */
+    childFrames(): Promise<Frame[]>;
+    /** Wait for a lifecycle state (load/domcontentloaded/networkidle) */
+    waitForLoadState(state?: "load" | "domcontentloaded" | "networkidle"): Promise<void>;
+    /** Simple placeholder for your own locator abstraction */
+    locator(selector: string, options?: {
+        deep?: boolean;
+        depth?: number;
+    }): Locator;
+    /** Create/get an isolated world for this frame and return its executionContextId */
+    private getExecutionContextId;
+}
+export {};

package/dist/lib/v3/understudy/frameLocator.d.ts

@@ -0,0 +1,46 @@
+import type { Page } from "./page";
+import { Frame } from "./frame";
+/**
+ * FrameLocator: resolves iframe elements to their child Frames and allows
+ * creating locators scoped to that frame. Supports chaining.
+ */
+export declare class FrameLocator {
+    private readonly parent?;
+    private readonly selector;
+    private readonly page;
+    private readonly root?;
+    constructor(page: Page, selector: string, parent?: FrameLocator, root?: Frame);
+    /** Create a nested FrameLocator under this one. */
+    frameLocator(selector: string): FrameLocator;
+    /** Resolve to the concrete Frame for this FrameLocator chain. */
+    resolveFrame(): Promise<Frame>;
+    /** Return a Locator scoped to this frame. Methods delegate to the frame lazily. */
+    locator(selector: string): LocatorDelegate;
+}
+/** A small delegating wrapper that resolves the frame lazily per call. */
+declare class LocatorDelegate {
+    private readonly fl;
+    private readonly sel;
+    constructor(fl: FrameLocator, sel: string);
+    private real;
+    click(options?: {
+        button?: "left" | "right" | "middle";
+        clickCount?: number;
+    }): Promise<void>;
+    fill(value: string): Promise<void>;
+    type(text: string, options?: {
+        delay?: number;
+    }): Promise<void>;
+    selectOption(values: string | string[]): Promise<string[]>;
+    scrollTo(percent: number | string): Promise<void>;
+    isVisible(): Promise<boolean>;
+    isChecked(): Promise<boolean>;
+    inputValue(): Promise<string>;
+    textContent(): Promise<string>;
+    innerHtml(): Promise<string>;
+    innerText(): Promise<string>;
+    first(): LocatorDelegate;
+}
+/** Factory to start a FrameLocator chain from an arbitrary root Frame. */
+export declare function frameLocatorFromFrame(page: Page, root: Frame, selector: string): FrameLocator;
+export {};

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

@@ -0,0 +1,100 @@
+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;
+    /**
+     * 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/lib/v3/understudy/locator.d.ts

@@ -0,0 +1,196 @@
+import { Protocol } from "devtools-protocol";
+import { Buffer } from "buffer";
+import type { Frame } from "./frame";
+type MouseButton = "left" | "right" | "middle";
+/**
+ * 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?;
+    constructor(frame: Frame, selector: string, options?: {
+        deep?: boolean;
+        depth?: 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: string | string[] | {
+        name: string;
+        mimeType: string;
+        buffer: ArrayBuffer | Uint8Array | Buffer | string;
+    } | Array<{
+        name: string;
+        mimeType: string;
+        buffer: ArrayBuffer | Uint8Array | Buffer | string;
+    }>): Promise<void>;
+    /**
+     * Return the DOM backendNodeId for this locator's target element.
+     * Useful for identity comparisons without needing element handles.
+     */
+    backendNodeId(): Promise<Protocol.DOM.BackendNodeId>;
+    /**
+     * 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>;
+    /**
+     * 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.
+     * - Sets the value/text directly in DOM.
+     * - Dispatches `input` and `change` events to mimic user input.
+     * - Releases the underlying `objectId` afterwards to avoid leaks.
+     */
+    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>;
+    /**
+     * For API parity, returns the same locator (querySelector already returns the first match).
+     */
+    first(): Locator;
+    /**
+     * Resolve `this.selector` within the frame to `{ objectId, nodeId? }`:
+     * - Ensures Runtime/DOM are enabled.
+     * - Creates (or reuses) an isolated world for this frame.
+     * - Evaluates a CSS or XPath query in that isolated world.
+     * - Best-effort: attempts to convert `objectId` to `nodeId`; failure is non-fatal.
+     *
+     * - For XPath: first try page-side resolver (__stagehandV3__.resolveSimpleXPath).
+     *   If it returns null (e.g. closed DSD not captured), fall back to CDP DOM with
+     *   `pierce: true` to traverse closed shadow roots and resolve by backendNodeId.
+     */
+    resolveNode(): Promise<{
+        nodeId: Protocol.DOM.NodeId | null;
+        objectId: Protocol.Runtime.RemoteObjectId;
+    }>;
+    /**
+     * CDP fallback for XPath resolution that needs to cross *closed* shadow roots
+     * created via Declarative Shadow DOM (no attachShadow call to intercept).
+     *
+     * Strategy:
+     *   - Fetch full DOM with `pierce: true` so closed shadow roots are included.
+     *   - Run a small, tolerant XPath stepper over the CDP node tree:
+     *       • supports absolute paths like `/html/body/...`
+     *       • supports `//` descendant jumps
+     *       • supports `tag[n]` numeric predicates per sibling group
+     *       • supports `*`
+     *   - Resolve the winning backendNodeId to an objectId for downstream actions.
+     */
+    private resolveViaDomPierceXPath;
+    /** Compute a center point from a BoxModel content quad */
+    private centerFromBoxContent;
+}
+export {};