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

package/dist/cjs/lib/v3/understudy/a11y/snapshot/focusSelectors.d.ts

@@ -0,0 +1,24 @@
+import type { CDPSessionLike } from "../../cdp.js";
+import { Page } from "../../page.js";
+import type { FrameParentIndex, ResolvedCssFocus, ResolvedFocusFrame, Step } from "../../../types/private/snapshot.js";
+/**
+ * Parse a cross-frame XPath into discrete steps. Each step tracks whether it
+ * represents a descendant hop (“//”) or a single-child hop (“/”).
+ */
+export declare function parseXPathToSteps(path: string): Step[];
+/** Rebuild an XPath string from parsed steps. */
+export declare function buildXPathFromSteps(steps: ReadonlyArray<Step>): string;
+/**
+ * Given a cross-frame XPath, walk iframe steps to resolve:
+ * - the target frameId (last iframe hop)
+ * - the tail XPath (within the target frame)
+ * - the absolute XPath prefix up to the iframe element hosting that frame
+ */
+export declare function resolveFocusFrameAndTail(page: Page, absoluteXPath: string, parentByFrame: FrameParentIndex, rootId: string): Promise<ResolvedFocusFrame>;
+/** Resolve focus frame and tail CSS selector using '>>' to hop iframes. */
+export declare function resolveCssFocusFrameAndTail(page: Page, rawSelector: string, parentByFrame: FrameParentIndex, rootId: string): Promise<ResolvedCssFocus>;
+/** Resolve an XPath to a Runtime remoteObjectId in the given CDP session. */
+export declare function resolveObjectIdForXPath(session: CDPSessionLike, xpath: string, frameId?: string): Promise<string | null>;
+/** Resolve a CSS selector (supports '>>' within the same frame only) to a Runtime objectId. */
+export declare function resolveObjectIdForCss(session: CDPSessionLike, selector: string, frameId?: string): Promise<string | null>;
+export declare function listChildrenOf(parentByFrame: FrameParentIndex, parentId: string): string[];

package/dist/cjs/lib/v3/understudy/a11y/snapshot/index.d.ts

@@ -0,0 +1,4 @@
+export { captureHybridSnapshot } from "./capture.js";
+export { computeActiveElementXpath } from "./activeElement.js";
+export { diffCombinedTrees } from "./treeFormatUtils.js";
+export { resolveXpathForLocation } from "./coordinateResolver.js";

package/dist/cjs/lib/v3/understudy/a11y/snapshot/sessions.d.ts

@@ -0,0 +1,16 @@
+import type { CDPSessionLike } from "../../cdp.js";
+import { Page } from "../../page.js";
+import type { FrameParentIndex } from "../../../types/private/snapshot.js";
+/**
+ * Session helpers ensure DOM lookups are always executed against the session
+ * that actually owns a frame. Keeping this logic centralized prevents subtle
+ * bugs when OOPIF adoption changes session ownership mid-capture.
+ */
+/** Return the owning session for a frame as registered on the Page. */
+export declare function ownerSession(page: Page, frameId: string): CDPSessionLike;
+/**
+ * DOM.getFrameOwner must be called against the parent frame's session.
+ * This helper hides the lookup (including main-frame fallback) so callers
+ * always reach for the correct connection.
+ */
+export declare function parentSession(page: Page, parentByFrame: FrameParentIndex, frameId: string): CDPSessionLike;

package/dist/cjs/lib/v3/understudy/a11y/snapshot/treeFormatUtils.d.ts

@@ -0,0 +1,28 @@
+import type { A11yNode } from "../../../types/private/snapshot.js";
+/**
+ * Render a formatted outline (with encoded ids) for the accessibility tree.
+ * Keeps indentation logic shared between modules so unit tests can cover these
+ * pure formatting helpers without a full snapshot pipeline.
+ */
+export declare function formatTreeLine(node: A11yNode, level?: number): string;
+/**
+ * Inject each child frame outline under the parent's iframe node line.
+ * Keys in `idToTree` are the parent's iframe encoded ids.
+ */
+export declare function injectSubtrees(rootOutline: string, idToTree: Map<string, string>): string;
+export declare function indentBlock(block: string, indent: string): string;
+/**
+ * Return the lines that appear in `nextTree` but not in `prevTree`.
+ * Comparison is done line-by-line, ignoring leading whitespace in both trees.
+ * The returned block is re-indented so the minimal indent becomes column 0.
+ */
+export declare function diffCombinedTrees(prevTree: string, nextTree: string): string;
+/**
+ * Remove whitespace noise and invisible code points before rendering names.
+ */
+export declare function cleanText(input: string): string;
+/**
+ * Collapse all whitespace runs in a string to a single space without trimming.
+ * Exported for pruning routines that need the same normalization.
+ */
+export declare function normaliseSpaces(s: string): string;

package/dist/cjs/lib/v3/understudy/a11y/snapshot/xpathUtils.d.ts

@@ -0,0 +1,26 @@
+import type { Protocol } from "devtools-protocol";
+import type { CDPSessionLike } from "../../cdp.js";
+/**
+ * Build the absolute XPath for a node by walking through every iframe host
+ * we've traversed so far followed by the leaf backend node.
+ */
+export declare function buildAbsoluteXPathFromChain(chain: Array<{
+    parentSession: CDPSessionLike;
+    iframeBackendNodeId: number;
+}>, leafSession: CDPSessionLike, leafBackendNodeId: number): Promise<string | null>;
+/**
+ * Resolve a backend node to an absolute XPath within the provided session.
+ * The CDP Runtime is used so we can invoke a small helper that walks the DOM.
+ */
+export declare function absoluteXPathForBackendNode(session: CDPSessionLike, backendNodeId: number): Promise<string | null>;
+/**
+ * Prefix `child` XPath with an absolute iframe path `parentAbs`.
+ * Handles root slashes and shadow hops (“//”) cleanly.
+ */
+export declare function prefixXPath(parentAbs: string, child: string): string;
+/** Normalize an XPath: strip `xpath=`, ensure leading '/', remove trailing '/'. */
+export declare function normalizeXPath(x?: string): string;
+/** Build per-sibling XPath steps for DOM traversal. */
+export declare function buildChildXPathSegments(kids: Protocol.DOM.Node[]): string[];
+/** Join two XPath fragments while preserving special shadow-root hops. */
+export declare function joinXPath(base: string, step: string): string;

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

@@ -0,0 +1,8 @@
+import { type A11yScriptName } from "../dom/build/a11yScripts.generated.js";
+/**
+ * Wrap a generated a11y script in a self-invoking expression that first ensures
+ * the bootstrap has run, then calls the requested helper via its global ref.
+ * This mirrors the locator resolver’s injection path so any CDP Runtime.evaluate
+ * can reuse the shared bundle without inlining JS strings.
+ */
+export declare function buildA11yInvocation(name: A11yScriptName, args: string[]): string;

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

@@ -0,0 +1,69 @@
+import type { Protocol } from "devtools-protocol";
+/**
+ * CDP transport & session multiplexer
+ *
+ * Owns the browser WebSocket and multiplexes flattened Target sessions.
+ * Tracks inflight CDP calls, routes responses to the right session, and forwards events.
+ *
+ * This does not interpret Page/DOM/Runtime semantics — callers own that logic.
+ */
+export interface CDPSessionLike {
+    send<R = unknown>(method: string, params?: object): Promise<R>;
+    on<P = unknown>(event: string, handler: (params: P) => void): void;
+    off<P = unknown>(event: string, handler: (params: P) => void): void;
+    close(): Promise<void>;
+    readonly id: string | null;
+}
+type EventHandler = (params: unknown) => void;
+export declare class CdpConnection implements CDPSessionLike {
+    private ws;
+    private nextId;
+    private inflight;
+    private eventHandlers;
+    private sessions;
+    /** Maps sessionId -> targetId (1:1 mapping) */
+    private sessionToTarget;
+    readonly id: string | null;
+    private transportCloseHandlers;
+    /** Optional CDP logger - set this to receive all outgoing CDP method calls */
+    cdpLogger?: (info: {
+        method: string;
+        params?: object;
+        targetId?: string | null;
+    }) => void;
+    /** Optional CDP event logger - set this to receive all incoming CDP events */
+    cdpEventLogger?: (info: {
+        method: string;
+        params?: unknown;
+        targetId?: string | null;
+    }) => void;
+    onTransportClosed(handler: (why: string) => void): void;
+    offTransportClosed(handler: (why: string) => void): void;
+    private emitTransportClosed;
+    private constructor();
+    static connect(wsUrl: string): Promise<CdpConnection>;
+    enableAutoAttach(): Promise<void>;
+    send<R = unknown>(method: string, params?: object): Promise<R>;
+    on<P = unknown>(event: string, handler: (params: P) => void): void;
+    off<P = unknown>(event: string, handler: (params: P) => void): void;
+    close(): Promise<void>;
+    getSession(sessionId: string): CdpSession | undefined;
+    attachToTarget(targetId: string): Promise<CdpSession>;
+    getTargets(): Promise<Protocol.Target.TargetInfo[]>;
+    private onMessage;
+    _sendViaSession<R = unknown>(sessionId: string, method: string, params?: object): Promise<R>;
+    _onSessionEvent(sessionId: string, event: string, handler: EventHandler): void;
+    _offSessionEvent(sessionId: string, event: string, handler: EventHandler): void;
+    _dispatchToSession(sessionId: string, event: string, params: unknown): void;
+}
+export declare class CdpSession implements CDPSessionLike {
+    private readonly root;
+    readonly id: string;
+    constructor(root: CdpConnection, id: string);
+    send<R = unknown>(method: string, params?: object): Promise<R>;
+    on<P = unknown>(event: string, handler: (params: P) => void): void;
+    off<P = unknown>(event: string, handler: (params: P) => void): void;
+    close(): Promise<void>;
+    dispatch(event: string, params: unknown): void;
+}
+export {};

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

@@ -0,0 +1,22 @@
+import type { Protocol } from "devtools-protocol";
+import type { Page } from "./page.js";
+type RemoteObject = Protocol.Runtime.RemoteObject;
+export type ConsoleListener = (message: ConsoleMessage) => void;
+export declare class ConsoleMessage {
+    private readonly event;
+    private readonly pageRef?;
+    constructor(event: Protocol.Runtime.ConsoleAPICalledEvent, pageRef?: Page);
+    type(): Protocol.Runtime.ConsoleAPICalledEvent["type"];
+    text(): string;
+    args(): RemoteObject[];
+    location(): {
+        url?: string;
+        lineNumber?: number;
+        columnNumber?: number;
+    };
+    page(): Page | undefined;
+    timestamp(): number | undefined;
+    raw(): Protocol.Runtime.ConsoleAPICalledEvent;
+    toString(): string;
+}
+export {};

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

@@ -0,0 +1,132 @@
+import type { Protocol } from "devtools-protocol";
+import { CdpConnection } from "./cdp.js";
+import { Page } from "./page.js";
+import type { StagehandAPIClient } from "../api.js";
+import { LocalBrowserLaunchOptions } from "../types/public/index.js";
+import { InitScriptSource } from "../types/private/index.js";
+/**
+ * V3Context
+ *
+ * Owns the root CDP connection and wires Target/Page events into Page.
+ * Maintains one Page per top-level target, adopts OOPIF child sessions into the owner Page,
+ * and tracks target→page and (root) frame→target mappings for lookups.
+ *
+ * IMPORTANT: FrameId → session ownership is managed inside Page (via its FrameRegistry).
+ * Context never “guesses” owners; it simply forwards events (with the emitting session)
+ * so Page can record the correct owner at event time.
+ */
+export declare class V3Context {
+    readonly conn: CdpConnection;
+    private readonly env;
+    private readonly apiClient;
+    private readonly localBrowserLaunchOptions;
+    private constructor();
+    private readonly _piercerInstalled;
+    private _lastPopupSignalAt;
+    private readonly _targetSessionListeners;
+    private readonly _sessionInit;
+    private pagesByTarget;
+    private mainFrameToTarget;
+    private sessionOwnerPage;
+    private frameOwnerPage;
+    private pendingOopifByMainFrame;
+    private createdAtByTarget;
+    private typeByTarget;
+    private _pageOrder;
+    private pendingCreatedTargetUrl;
+    private readonly initScripts;
+    private installTargetSessionListeners;
+    /**
+     * Create a Context for a given CDP websocket URL and bootstrap target wiring.
+     */
+    static create(wsUrl: string, opts?: {
+        env?: "LOCAL" | "BROWSERBASE";
+        apiClient?: StagehandAPIClient | null;
+        localBrowserLaunchOptions?: LocalBrowserLaunchOptions | null;
+    }): Promise<V3Context>;
+    /**
+     * Wait until at least one top-level Page has been created and registered.
+     * We poll internal maps that bootstrap/onAttachedToTarget populate.
+     */
+    private waitForFirstTopLevelPage;
+    private waitForInitialTopLevelTargets;
+    private ensurePiercer;
+    /** Mark a page target as the most-recent one (active). */
+    private _pushActive;
+    /** Remove a page target from the recency list (used on close). */
+    private _removeFromOrder;
+    /** Return the current active Page (most-recent page that still exists). */
+    activePage(): Page | undefined;
+    /** Explicitly mark a known Page as the most-recent active page (and focus it). */
+    setActivePage(page: Page): void;
+    addInitScript<Arg>(script: InitScriptSource<Arg>, arg?: Arg): Promise<void>;
+    /**
+     * Return top-level `Page`s (oldest → newest). OOPIF targets are not included.
+     */
+    pages(): Page[];
+    private applyInitScriptsToPage;
+    /**
+     * Resolve an owning `Page` by the **top-level main frame id**.
+     * Note: child (OOPIF) roots are intentionally not present in this mapping.
+     */
+    resolvePageByMainFrameId(frameId: string): Page | undefined;
+    /**
+     * Serialize the full frame tree for a given top-level main frame id.
+     */
+    getFullFrameTreeByMainFrameId(rootMainFrameId: string): Promise<Protocol.Page.FrameTree>;
+    /**
+     * Create a new top-level page (tab) with the given URL and return its Page object.
+     * Waits until the target is attached and registered.
+     */
+    newPage(url?: string): Promise<Page>;
+    /**
+     * Close CDP and clear all mappings. Best-effort cleanup.
+     */
+    close(): Promise<void>;
+    /**
+     * Bootstrap target lifecycle:
+     * - Attach to existing targets.
+     * - Handle auto-attach events.
+     * - Clean up on detach/destroy.
+     */
+    private bootstrap;
+    /**
+     * Handle a newly attached target (top-level or potential OOPIF):
+     * - Enable Page domain and lifecycle events.
+     * - If top-level → create Page, wire listeners, resume.
+     * - Else → probe child root frame id via `Page.getFrameTree` and adopt immediately
+     *   if the parent is known; otherwise stage until parent `frameAttached`.
+     * - Resume the target only after listeners are wired.
+     */
+    private onAttachedToTarget;
+    /**
+     * Detach handler:
+     * - Remove child session ownership and prune its subtree.
+     * - If a top-level target, cleanup its `Page` and mappings.
+     * - Drop any staged child for this session.
+     */
+    private onDetachedFromTarget;
+    /**
+     * Cleanup a top-level Page by target id, removing its root and staged children.
+     */
+    private cleanupByTarget;
+    /**
+     * Wire Page-domain frame events for a session into the owning Page & mappings.
+     * We forward the *emitting session* with every event so Page can stamp ownership precisely.
+     */
+    private installFrameEventBridges;
+    /**
+     * Register that a session belongs to a Page (used by event routing).
+     */
+    private wireSessionToOwnerPage;
+    /**
+     * Utility: reverse-lookup the top-level target id that owns a given Page.
+     */
+    private findTargetIdByPage;
+    private _notePopupSignal;
+    /**
+     * Await the current active page, waiting briefly if a popup/open was just triggered.
+     * Normal path returns immediately; popup path waits up to timeoutMs for the new page.
+     */
+    awaitActivePage(timeoutMs?: number): Promise<Page>;
+}

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

@@ -0,0 +1,87 @@
+import { Locator } from "./locator.js";
+import type { Frame } from "./frame.js";
+import type { Page } from "./page.js";
+export type ResolvedLocatorTarget = {
+    frame: Frame;
+    selector: string;
+};
+/** 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 resolveLocatorTarget(page: Page, root: Frame, selectorRaw: string): Promise<ResolvedLocatorTarget>;
+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;
+    private readonly nthIndex;
+    constructor(page: Page, root: Frame, selector: string, nthIndex?: number);
+    private real;
+    click(options?: {
+        button?: "left" | "right" | "middle";
+        clickCount?: number;
+    }): Promise<void>;
+    count(): Promise<number>;
+    hover(): 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>;
+    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>;
+    first(): DeepLocatorDelegate;
+    nth(index: number): DeepLocatorDelegate;
+}
+/** 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/cjs/lib/v3/understudy/executionContextRegistry.d.ts

@@ -0,0 +1,15 @@
+import type { Protocol } from "devtools-protocol";
+import type { CDPSessionLike } from "./cdp.js";
+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/cjs/lib/v3/understudy/fileUploadUtils.d.ts

@@ -0,0 +1,13 @@
+import { Buffer } from "buffer";
+import { SetInputFilesArgument } from "../types/public/locator.js";
+import { NormalizedFilePayload } from "../types/private/locator.js";
+/**
+ * Normalize user-provided setInputFiles arguments into in-memory payloads.
+ * - Resolves string paths relative to the provided base directory.
+ * - Validates that each path exists and is a regular file.
+ * - Converts all buffers into Node Buffers for downstream processing.
+ */
+export declare function normalizeInputFiles(files: SetInputFilesArgument, opts?: {
+    baseDir?: string;
+}): Promise<NormalizedFilePayload[]>;
+export declare function toBuffer(data: ArrayBuffer | Uint8Array | Buffer | string): Buffer;

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

@@ -0,0 +1,69 @@
+import { Protocol } from "devtools-protocol";
+import type { CDPSessionLike } from "./cdp.js";
+import { Locator } from "./locator.js";
+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;
+    private readonly remoteBrowser;
+    /** 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, remoteBrowser: boolean);
+    /** True when the controlled browser runs on a different machine. */
+    isBrowserRemote(): boolean;
+    /** 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 main 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;
+        };
+        type?: "png" | "jpeg";
+        quality?: number;
+        scale?: number;
+    }): Promise<Buffer>;
+    /** Child frames via Page.getFrameTree */
+    childFrames(): Promise<Frame[]>;
+    /** Wait for a lifecycle state (load/domcontentloaded/networkidle) */
+    waitForLoadState(state?: "load" | "domcontentloaded" | "networkidle", timeoutMs?: number): Promise<void>;
+    /** Simple placeholder for your own locator abstraction */
+    locator(selector: string, options?: {
+        deep?: boolean;
+        depth?: number;
+    }): Locator;
+    /** Resolve the main-world execution context id for this frame. */
+    private getMainWorldExecutionContextId;
+}
+export {};

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

@@ -0,0 +1,50 @@
+import type { Page } from "./page.js";
+import { Frame } from "./frame.js";
+/**
+ * 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;
+    private readonly nthIndex;
+    constructor(fl: FrameLocator, sel: string, nthIndex?: number);
+    private real;
+    click(options?: {
+        button?: "left" | "right" | "middle";
+        clickCount?: number;
+    }): Promise<void>;
+    hover(): 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>;
+    count(): Promise<number>;
+    first(): LocatorDelegate;
+    nth(index: number): LocatorDelegate;
+}
+/** Factory to start a FrameLocator chain from an arbitrary root Frame. */
+export declare function frameLocatorFromFrame(page: Page, root: Frame, selector: string): FrameLocator;
+export {};