@browserbasehq/orca 3.0.0-preview.1 → 3.0.0-preview.3

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

@@ -1,100 +0,0 @@
-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

@@ -1,196 +0,0 @@
-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 {};

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

@@ -1,241 +0,0 @@
-import { Protocol } from "devtools-protocol";
-import type { CDPSessionLike } from "./cdp";
-import { CdpConnection } from "./cdp";
-import { Frame } from "./frame";
-import { FrameLocator } from "./frameLocator";
-import { LoadState } from "../types";
-export declare class Page {
-    private readonly conn;
-    private readonly mainSession;
-    private readonly _targetId;
-    /** Every CDP child session this page owns (top-level + adopted OOPIF sessions). */
-    private readonly sessions;
-    /** Unified truth for frame topology + ownership. */
-    private readonly registry;
-    /** A convenience wrapper bound to the current main frame id (top-level session). */
-    private mainFrameWrapper;
-    /** Compact ordinal per frameId (used by snapshot encoding). */
-    private frameOrdinals;
-    private nextOrdinal;
-    /** cache Frames per frameId so everyone uses the same one */
-    private readonly frameCache;
-    /** Stable id for Frames created by this Page (use top-level TargetId). */
-    private readonly pageId;
-    private constructor();
-    private cursorEnabled;
-    private ensureCursorScript;
-    enableCursorOverlay(): Promise<void>;
-    private updateCursor;
-    /**
-     * Factory: create Page and seed registry with the shallow tree from Page.getFrameTree.
-     * Assumes Page domain is already enabled on the session passed in.
-     */
-    static create(conn: CdpConnection, session: CDPSessionLike, targetId: string): Promise<Page>;
-    /**
-     * Parent/child session emitted a `frameAttached`.
-     * Topology update + ownership stamped to **emitting session**.
-     */
-    onFrameAttached(frameId: string, parentId: string | null, session: CDPSessionLike): void;
-    /**
-     * Parent/child session emitted a `frameDetached`.
-     */
-    onFrameDetached(frameId: string, reason?: "remove" | "swap" | string): void;
-    /**
-     * Parent/child session emitted a `frameNavigated`.
-     * Topology + ownership update. Handles root swaps.
-     */
-    onFrameNavigated(frame: Protocol.Page.Frame, session: CDPSessionLike): void;
-    /**
-     * An OOPIF child session whose **main** frame id equals the parent iframe’s frameId
-     * has been attached; adopt the session into this Page and seed ownership for its subtree.
-     */
-    adoptOopifSession(childSession: CDPSessionLike, childMainFrameId: string): void;
-    /** Detach an adopted child session and prune its subtree */
-    detachOopifSession(sessionId: string): void;
-    /** Return the owning CDP session for a frameId (falls back to main session) */
-    getSessionForFrame(frameId: string): CDPSessionLike;
-    /** Always returns a Frame bound to the owning session */
-    frameForId(frameId: string): Frame;
-    /** Expose a session by id (used by snapshot to resolve session id -> session) */
-    getSessionById(id: string): CDPSessionLike | undefined;
-    targetId(): string;
-    mainFrameId(): string;
-    mainFrame(): Frame;
-    /**
-     * Close this top-level page (tab). Best-effort via Target.closeTarget.
-     */
-    close(): Promise<void>;
-    getFullFrameTree(): Protocol.Page.FrameTree;
-    asProtocolFrameTree(rootMainFrameId: string): Protocol.Page.FrameTree;
-    private ensureOrdinal;
-    /** Public getter for snapshot code / handlers. */
-    getOrdinal(frameId: string): number;
-    listAllFrameIds(): string[];
-    /**
-     * Navigate the page; optionally wait for a lifecycle state.
-     * Waits on the **current** main frame and follows root swaps during navigation.
-     */
-    goto(url: string, options?: {
-        waitUntil?: LoadState;
-        timeoutMs?: number;
-    }): Promise<void>;
-    /**
-     * Reload the page; optionally wait for a lifecycle state.
-     */
-    reload(options?: {
-        waitUntil?: LoadState;
-        timeoutMs?: number;
-        ignoreCache?: boolean;
-    }): Promise<void>;
-    /**
-     * Navigate back in history if possible; optionally wait for a lifecycle state.
-     */
-    goBack(options?: {
-        waitUntil?: LoadState;
-        timeoutMs?: number;
-    }): Promise<void>;
-    /**
-     * Navigate forward in history if possible; optionally wait for a lifecycle state.
-     */
-    goForward(options?: {
-        waitUntil?: LoadState;
-        timeoutMs?: number;
-    }): Promise<void>;
-    /**
-     * Return the current page URL (from navigation history).
-     */
-    url(): Promise<string>;
-    /**
-     * Return the current page title.
-     * Prefers reading from the active document via Runtime.evaluate to reflect dynamic changes.
-     * Falls back to navigation history title if evaluation is unavailable.
-     */
-    title(): Promise<string>;
-    /**
-     * Capture a screenshot (delegated to the current main frame).
-     */
-    screenshot(options?: {
-        fullPage?: boolean;
-    }): Promise<string>;
-    /**
-     * Create a locator bound to the current main frame.
-     */
-    locator(selector: string): ReturnType<Frame["locator"]>;
-    /**
-     * Deep locator that supports cross-iframe traversal.
-     * - Recognizes '>>' hop notation to enter iframe contexts.
-     * - Supports deep XPath that includes iframe steps (e.g., '/html/body/iframe[2]//div').
-     * Returns a Locator scoped to the appropriate frame.
-     */
-    deepLocator(selector: string): import("./deepLocator").DeepLocatorDelegate;
-    /**
-     * Frame locator similar to Playwright: targets iframe elements and scopes
-     * subsequent locators to that frame. Supports chaining.
-     */
-    frameLocator(selector: string): FrameLocator;
-    /**
-     * List all frames belonging to this page as Frame objects bound to their owning sessions.
-     * The list is ordered by a stable ordinal assigned during the page lifetime.
-     */
-    frames(): Frame[];
-    /**
-     * Wait until the page reaches a lifecycle state on the current main frame.
-     * Mirrors Playwright's API signatures.
-     */
-    waitForLoadState(state: LoadState, timeoutMs?: number): Promise<void>;
-    /**
-     * Evaluate a function or expression in the current main frame's isolated world.
-     * - If a string is provided, it is treated as a JS expression.
-     * - If a function is provided, it is stringified and invoked with the optional argument.
-     * - The return value should be JSON-serializable. Non-serializable objects will
-     *   best-effort serialize via JSON.stringify inside the page context.
-     */
-    evaluate<R = unknown, Arg = unknown>(pageFunctionOrExpression: string | ((arg: Arg) => R | Promise<R>), arg?: Arg): Promise<R>;
-    /**
-     * Force the page viewport to an exact CSS size and device scale factor.
-     * Ensures screenshots match width x height pixels when deviceScaleFactor = 1.
-     */
-    setViewportSize(width: number, height: number, options?: {
-        deviceScaleFactor?: number;
-    }): Promise<void>;
-    /**
-     * Click at absolute page coordinates (CSS pixels).
-     * Dispatches mouseMoved → mousePressed → mouseReleased via CDP Input domain
-     * on the top-level page target's session. Coordinates are relative to the
-     * viewport origin (top-left). Does not scroll.
-     */
-    click(x: number, y: number, options: {
-        button?: "left" | "right" | "middle";
-        clickCount?: number;
-        returnXpath: true;
-    }): Promise<string>;
-    click(x: number, y: number, options?: {
-        button?: "left" | "right" | "middle";
-        clickCount?: number;
-        returnXpath?: false;
-    }): Promise<void>;
-    click(x: number, y: number, options: {
-        button?: "left" | "right" | "middle";
-        clickCount?: number;
-        returnXpath: boolean;
-    }): Promise<void | string>;
-    scroll(x: number, y: number, deltaX: number, deltaY: number, options: {
-        returnXpath: true;
-    }): Promise<string>;
-    scroll(x: number, y: number, deltaX: number, deltaY: number, options?: {
-        returnXpath?: false;
-    }): Promise<void>;
-    scroll(x: number, y: number, deltaX: number, deltaY: number, options: {
-        returnXpath: boolean;
-    }): Promise<void | string>;
-    /**
-     * Drag from (fromX, fromY) to (toX, toY) using mouse events.
-     * Sends mouseMoved → mousePressed → mouseMoved (steps) → mouseReleased.
-     */
-    dragAndDrop(fromX: number, fromY: number, toX: number, toY: number, options: {
-        button?: "left" | "right" | "middle";
-        steps?: number;
-        delay?: number;
-        returnXpath: true;
-    }): Promise<[string, string]>;
-    dragAndDrop(fromX: number, fromY: number, toX: number, toY: number, options?: {
-        button?: "left" | "right" | "middle";
-        steps?: number;
-        delay?: number;
-        returnXpath?: false;
-    }): Promise<void>;
-    dragAndDrop(fromX: number, fromY: number, toX: number, toY: number, options: {
-        button?: "left" | "right" | "middle";
-        steps?: number;
-        delay?: number;
-        returnXpath: boolean;
-    }): Promise<void | [string, string]>;
-    /**
-     * Type a string by dispatching keyDown/keyUp events per character.
-     * Focus must already be on the desired element. Uses CDP Input.dispatchKeyEvent
-     * and never falls back to Input.insertText. Optional delay applies between
-     * successive characters.
-     */
-    type(text: string, options?: {
-        delay?: number;
-        withMistakes?: boolean;
-    }): Promise<void>;
-    /**
-     * Press a single key (keyDown then keyUp). For printable characters,
-     * uses the text path on keyDown; for named keys, sets key/code/VK.
-     */
-    keyPress(key: string, options?: {
-        delay?: number;
-    }): Promise<void>;
-    /**
-     * Create an isolated world for the **current** main frame and return its context id.
-     */
-    private createIsolatedWorldForCurrentMain;
-    /**
-     * Wait until the **current** main frame reaches a lifecycle state.
-     * - Fast path via `document.readyState`.
-     * - Event path listens at the session level and compares incoming `frameId`
-     *   to `mainFrameId()` **at event time** to follow root swaps.
-     */
-    private waitForMainLoadState;
-}

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

@@ -1,4 +0,0 @@
-import type { CDPSessionLike } from "./cdp";
-export declare function installV3PiercerIntoSession(session: CDPSessionLike): Promise<void>;
-/** (Optional) stream patch logs in your node console during bring-up */
-export declare function tapPiercerConsole(session: CDPSessionLike, label: string): void;