@browserbasehq/orca 3.0.9-alpha-3 → 3.1.0-patch.0

package/dist/esm/lib/v3/understudy/lifecycleWatcher.js

@@ -0,0 +1,245 @@
+import { TimeoutError } from "../types/public/sdkErrors.js";
+import { DEFAULT_IDLE_WAIT, IGNORED_RESOURCE_TYPES, } from "../types/private/network.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 class LifecycleWatcher {
+    page;
+    mainSession;
+    networkManager;
+    waitUntil;
+    timeoutMs;
+    startTime;
+    navigationCommandId;
+    currentLoaderId;
+    idleStartTime;
+    cleanupCallbacks = [];
+    idleHandle = null;
+    abortReject = null;
+    abortPromise;
+    abortError = null;
+    disposed = false;
+    expectedLoaderId;
+    initialLoaderId;
+    pendingFollowupNavigation = false;
+    /**
+     * Create a watcher; callers should subsequently invoke {@link wait}.
+     */
+    constructor(params) {
+        this.page = params.page;
+        this.mainSession = params.mainSession;
+        this.networkManager = params.networkManager;
+        this.waitUntil = params.waitUntil;
+        this.timeoutMs = params.timeoutMs;
+        this.startTime = Date.now();
+        this.navigationCommandId = params.navigationCommandId;
+        this.idleStartTime = this.startTime;
+        this.abortPromise = new Promise((_, reject) => {
+            this.abortReject = reject;
+        });
+        this.installSessionListeners();
+    }
+    /** Hint the watcher with the loader id returned by Page.navigate. */
+    setExpectedLoaderId(loaderId) {
+        if (!loaderId)
+            return;
+        this.expectedLoaderId = loaderId;
+        this.initialLoaderId = loaderId;
+        this.currentLoaderId = loaderId;
+        this.idleStartTime = Date.now();
+    }
+    /** Wait for the requested lifecycle state or throw on timeout/abort. */
+    async wait() {
+        const deadline = Date.now() + this.timeoutMs;
+        try {
+            if (this.waitUntil === "domcontentloaded") {
+                await this.awaitWithAbort(this.page.waitForMainLoadState("domcontentloaded", this.timeRemaining(deadline)));
+                return;
+            }
+            while (true) {
+                await this.awaitWithAbort(this.page.waitForMainLoadState("load", this.timeRemaining(deadline)));
+                if (this.waitUntil !== "networkidle")
+                    break;
+                try {
+                    await this.awaitWithAbort(this.waitForNetworkIdle(deadline));
+                    break;
+                }
+                catch (error) {
+                    if (this.shouldRestartAfterFollowup(error)) {
+                        continue;
+                    }
+                    throw error;
+                }
+            }
+        }
+        finally {
+            this.dispose();
+        }
+        if (this.abortError)
+            throw this.abortError;
+    }
+    /** Cancel any outstanding network-idle waits and remove event listeners. */
+    dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        if (this.idleHandle) {
+            void this.idleHandle.promise.catch(() => { });
+            this.idleHandle.dispose();
+            this.idleHandle = null;
+        }
+        for (const fn of this.cleanupCallbacks) {
+            try {
+                fn();
+            }
+            catch {
+                // ignore listener cleanup errors
+            }
+        }
+        this.cleanupCallbacks = [];
+        this.abortReject = null;
+    }
+    /** Subscribe to main-frame events to detect abort conditions. */
+    installSessionListeners() {
+        const onFrameNavigated = (evt) => {
+            if (!evt?.frame?.id)
+                return;
+            const mainFrameId = this.page.mainFrameId();
+            if (evt.frame.id !== mainFrameId)
+                return;
+            const loaderId = evt.frame.loaderId;
+            if (!loaderId)
+                return;
+            if (!this.initialLoaderId) {
+                this.initialLoaderId = loaderId;
+                this.currentLoaderId = loaderId;
+                this.idleStartTime = Date.now();
+            }
+            if (!this.expectedLoaderId) {
+                this.expectedLoaderId = loaderId;
+                this.currentLoaderId = loaderId;
+                this.idleStartTime = Date.now();
+                return;
+            }
+            if (loaderId !== this.expectedLoaderId) {
+                if (!this.page.isCurrentNavigationCommand(this.navigationCommandId)) {
+                    this.triggerAbort(new Error("Navigation was superseded by a new request"));
+                    return;
+                }
+                this.adoptNewMainLoader(loaderId);
+            }
+        };
+        const onFrameDetached = (evt) => {
+            if (!evt?.frameId)
+                return;
+            const mainFrameId = this.page.mainFrameId();
+            if (evt.frameId !== mainFrameId)
+                return;
+            if (evt.reason === "swap")
+                return;
+            this.triggerAbort(new Error("Main frame was detached"));
+        };
+        this.mainSession.on("Page.frameNavigated", onFrameNavigated);
+        this.cleanupCallbacks.push(() => {
+            this.mainSession.off("Page.frameNavigated", onFrameNavigated);
+        });
+        this.mainSession.on("Page.frameDetached", onFrameDetached);
+        this.cleanupCallbacks.push(() => {
+            this.mainSession.off("Page.frameDetached", onFrameDetached);
+        });
+    }
+    /** Compute remaining time until the shared deadline elapses. */
+    timeRemaining(deadline) {
+        const remaining = deadline - Date.now();
+        if (remaining <= 0) {
+            throw new TimeoutError("Lifecycle wait", this.timeoutMs);
+        }
+        return remaining;
+    }
+    /** Await an operation but abort early if navigation replacement fires. */
+    async awaitWithAbort(operation) {
+        try {
+            return await Promise.race([operation, this.abortPromise]);
+        }
+        catch (error) {
+            if (this.abortError)
+                throw this.abortError;
+            throw error;
+        }
+    }
+    /** Mark the watcher as aborted and reject any pending waiters. */
+    triggerAbort(error) {
+        if (this.abortError)
+            return;
+        this.abortError = error;
+        if (this.abortReject) {
+            this.abortReject(error);
+            this.abortReject = null;
+        }
+    }
+    waitForNetworkIdle(deadline) {
+        this.pendingFollowupNavigation = false;
+        const remaining = this.timeRemaining(deadline);
+        const idleWindow = Math.min(DEFAULT_IDLE_WAIT, remaining);
+        this.idleHandle = this.networkManager.waitForIdle({
+            startTime: this.idleStartTime,
+            timeoutMs: remaining,
+            totalBudgetMs: this.timeoutMs,
+            idleTimeMs: idleWindow,
+            filter: this.buildIdleFilter(),
+        });
+        return this.idleHandle.promise.catch((error) => {
+            if (this.abortError)
+                throw this.abortError;
+            throw error;
+        });
+    }
+    shouldRestartAfterFollowup(error) {
+        if (!this.pendingFollowupNavigation)
+            return false;
+        if (!(error instanceof Error))
+            return false;
+        if (error.message !== "waitForIdle disposed")
+            return false;
+        this.pendingFollowupNavigation = false;
+        return true;
+    }
+    adoptNewMainLoader(loaderId) {
+        this.expectedLoaderId = loaderId;
+        this.currentLoaderId = loaderId;
+        this.idleStartTime = Date.now();
+        if (this.waitUntil !== "networkidle")
+            return;
+        this.pendingFollowupNavigation = true;
+        if (this.idleHandle) {
+            const handle = this.idleHandle;
+            this.idleHandle = null;
+            void handle.promise.catch(() => { });
+            handle.dispose();
+        }
+    }
+    buildIdleFilter() {
+        const loaderId = this.currentLoaderId;
+        const mainFrameId = this.page.mainFrameId();
+        return (info) => {
+            if (IGNORED_RESOURCE_TYPES.has(info.resourceType))
+                return false;
+            if (loaderId && info.loaderId) {
+                return info.loaderId === loaderId;
+            }
+            if (!info.loaderId && info.frameId) {
+                return info.frameId === mainFrameId;
+            }
+            return true;
+        };
+    }
+}
+//# sourceMappingURL=lifecycleWatcher.js.map

package/dist/esm/lib/v3/understudy/lifecycleWatcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycleWatcher.js","sourceRoot":"","sources":["../../../../../lib/v3/understudy/lifecycleWatcher.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Protocol } from \"devtools-protocol\";\nimport type { LoadState } from \"../types/public/page.js\";\nimport type { CDPSessionLike } from \"./cdp.js\";\nimport type { NetworkManager } from \"./networkManager.js\";\nimport type { Page } from \"./page.js\";\nimport { TimeoutError } from \"../types/public/sdkErrors.js\";\nimport {\n  DEFAULT_IDLE_WAIT,\n  IGNORED_RESOURCE_TYPES,\n  type NetworkRequestInfo,\n  WaitForIdleHandle,\n} from \"../types/private/network.js\";\n\n/**\n * Coordinates page lifecycle waits (load/domcontentloaded/networkidle) while\n * following main-frame swaps and navigation aborts. Each navigation spawns a\n * one-off watcher that listens for relevant CDP events and resolves or rejects\n * depending on the requested `waitUntil` state.\n */\n\n/**\n * Small utility that mirrors Playwright's lifecycle watcher semantics. Bridges\n * main-frame lifecycle events with the NetworkManager's idle signal so callers\n * can await `load`, `domcontentloaded`, or `networkidle` with a single promise.\n */\nexport class LifecycleWatcher {\n  private readonly page: Page;\n  private readonly mainSession: CDPSessionLike;\n  private readonly networkManager: NetworkManager;\n  private readonly waitUntil: LoadState;\n  private readonly timeoutMs: number;\n  private readonly startTime: number;\n  private readonly navigationCommandId: number;\n  private currentLoaderId: string | undefined;\n  private idleStartTime: number;\n\n  private cleanupCallbacks: Array<() => void> = [];\n  private idleHandle: WaitForIdleHandle | null = null;\n\n  private abortReject: ((error: Error) => void) | null = null;\n  private abortPromise: Promise<never>;\n  private abortError: Error | null = null;\n  private disposed = false;\n\n  private expectedLoaderId: string | undefined;\n  private initialLoaderId: string | undefined;\n  private pendingFollowupNavigation = false;\n\n  /**\n   * Create a watcher; callers should subsequently invoke {@link wait}.\n   */\n  constructor(params: {\n    page: Page;\n    mainSession: CDPSessionLike;\n    networkManager: NetworkManager;\n    waitUntil: LoadState;\n    timeoutMs: number;\n    navigationCommandId: number;\n  }) {\n    this.page = params.page;\n    this.mainSession = params.mainSession;\n    this.networkManager = params.networkManager;\n    this.waitUntil = params.waitUntil;\n    this.timeoutMs = params.timeoutMs;\n    this.startTime = Date.now();\n    this.navigationCommandId = params.navigationCommandId;\n    this.idleStartTime = this.startTime;\n\n    this.abortPromise = new Promise<never>((_, reject) => {\n      this.abortReject = reject;\n    });\n\n    this.installSessionListeners();\n  }\n\n  /** Hint the watcher with the loader id returned by Page.navigate. */\n  public setExpectedLoaderId(loaderId: string | undefined): void {\n    if (!loaderId) return;\n    this.expectedLoaderId = loaderId;\n    this.initialLoaderId = loaderId;\n    this.currentLoaderId = loaderId;\n    this.idleStartTime = Date.now();\n  }\n\n  /** Wait for the requested lifecycle state or throw on timeout/abort. */\n  public async wait(): Promise<void> {\n    const deadline = Date.now() + this.timeoutMs;\n\n    try {\n      if (this.waitUntil === \"domcontentloaded\") {\n        await this.awaitWithAbort(\n          this.page.waitForMainLoadState(\n            \"domcontentloaded\",\n            this.timeRemaining(deadline),\n          ),\n        );\n        return;\n      }\n\n      while (true) {\n        await this.awaitWithAbort(\n          this.page.waitForMainLoadState(\"load\", this.timeRemaining(deadline)),\n        );\n\n        if (this.waitUntil !== \"networkidle\") break;\n\n        try {\n          await this.awaitWithAbort(this.waitForNetworkIdle(deadline));\n          break;\n        } catch (error) {\n          if (this.shouldRestartAfterFollowup(error)) {\n            continue;\n          }\n          throw error;\n        }\n      }\n    } finally {\n      this.dispose();\n    }\n\n    if (this.abortError) throw this.abortError;\n  }\n\n  /** Cancel any outstanding network-idle waits and remove event listeners. */\n  public dispose(): void {\n    if (this.disposed) return;\n    this.disposed = true;\n\n    if (this.idleHandle) {\n      void this.idleHandle.promise.catch(() => {});\n      this.idleHandle.dispose();\n      this.idleHandle = null;\n    }\n\n    for (const fn of this.cleanupCallbacks) {\n      try {\n        fn();\n      } catch {\n        // ignore listener cleanup errors\n      }\n    }\n    this.cleanupCallbacks = [];\n    this.abortReject = null;\n  }\n\n  /** Subscribe to main-frame events to detect abort conditions. */\n  private installSessionListeners(): void {\n    const onFrameNavigated = (evt: Protocol.Page.FrameNavigatedEvent) => {\n      if (!evt?.frame?.id) return;\n\n      const mainFrameId = this.page.mainFrameId();\n      if (evt.frame.id !== mainFrameId) return;\n\n      const loaderId = evt.frame.loaderId;\n      if (!loaderId) return;\n\n      if (!this.initialLoaderId) {\n        this.initialLoaderId = loaderId;\n        this.currentLoaderId = loaderId;\n        this.idleStartTime = Date.now();\n      }\n\n      if (!this.expectedLoaderId) {\n        this.expectedLoaderId = loaderId;\n        this.currentLoaderId = loaderId;\n        this.idleStartTime = Date.now();\n        return;\n      }\n\n      if (loaderId !== this.expectedLoaderId) {\n        if (!this.page.isCurrentNavigationCommand(this.navigationCommandId)) {\n          this.triggerAbort(\n            new Error(\"Navigation was superseded by a new request\"),\n          );\n          return;\n        }\n\n        this.adoptNewMainLoader(loaderId);\n      }\n    };\n\n    const onFrameDetached = (evt: Protocol.Page.FrameDetachedEvent) => {\n      if (!evt?.frameId) return;\n      const mainFrameId = this.page.mainFrameId();\n      if (evt.frameId !== mainFrameId) return;\n      if (evt.reason === \"swap\") return;\n      this.triggerAbort(new Error(\"Main frame was detached\"));\n    };\n\n    this.mainSession.on(\"Page.frameNavigated\", onFrameNavigated);\n    this.cleanupCallbacks.push(() => {\n      this.mainSession.off(\"Page.frameNavigated\", onFrameNavigated);\n    });\n\n    this.mainSession.on(\"Page.frameDetached\", onFrameDetached);\n    this.cleanupCallbacks.push(() => {\n      this.mainSession.off(\"Page.frameDetached\", onFrameDetached);\n    });\n  }\n\n  /** Compute remaining time until the shared deadline elapses. */\n  private timeRemaining(deadline: number): number {\n    const remaining = deadline - Date.now();\n    if (remaining <= 0) {\n      throw new TimeoutError(\"Lifecycle wait\", this.timeoutMs);\n    }\n    return remaining;\n  }\n\n  /** Await an operation but abort early if navigation replacement fires. */\n  private async awaitWithAbort<T>(operation: Promise<T>): Promise<T> {\n    try {\n      return await Promise.race([operation, this.abortPromise]);\n    } catch (error) {\n      if (this.abortError) throw this.abortError;\n      throw error;\n    }\n  }\n\n  /** Mark the watcher as aborted and reject any pending waiters. */\n  private triggerAbort(error: Error): void {\n    if (this.abortError) return;\n    this.abortError = error;\n    if (this.abortReject) {\n      this.abortReject(error);\n      this.abortReject = null;\n    }\n  }\n  private waitForNetworkIdle(deadline: number): Promise<void> {\n    this.pendingFollowupNavigation = false;\n    const remaining = this.timeRemaining(deadline);\n    const idleWindow = Math.min(DEFAULT_IDLE_WAIT, remaining);\n    this.idleHandle = this.networkManager.waitForIdle({\n      startTime: this.idleStartTime,\n      timeoutMs: remaining,\n      totalBudgetMs: this.timeoutMs,\n      idleTimeMs: idleWindow,\n      filter: this.buildIdleFilter(),\n    });\n\n    return this.idleHandle.promise.catch((error) => {\n      if (this.abortError) throw this.abortError;\n      throw error;\n    });\n  }\n\n  private shouldRestartAfterFollowup(error: unknown): boolean {\n    if (!this.pendingFollowupNavigation) return false;\n    if (!(error instanceof Error)) return false;\n    if (error.message !== \"waitForIdle disposed\") return false;\n    this.pendingFollowupNavigation = false;\n    return true;\n  }\n\n  private adoptNewMainLoader(loaderId: string): void {\n    this.expectedLoaderId = loaderId;\n    this.currentLoaderId = loaderId;\n    this.idleStartTime = Date.now();\n    if (this.waitUntil !== \"networkidle\") return;\n\n    this.pendingFollowupNavigation = true;\n\n    if (this.idleHandle) {\n      const handle = this.idleHandle;\n      this.idleHandle = null;\n      void handle.promise.catch(() => {});\n      handle.dispose();\n    }\n  }\n\n  private buildIdleFilter(): (info: NetworkRequestInfo) => boolean {\n    const loaderId = this.currentLoaderId;\n    const mainFrameId = this.page.mainFrameId();\n\n    return (info: NetworkRequestInfo) => {\n      if (IGNORED_RESOURCE_TYPES.has(info.resourceType)) return false;\n\n      if (loaderId && info.loaderId) {\n        return info.loaderId === loaderId;\n      }\n\n      if (!info.loaderId && info.frameId) {\n        return info.frameId === mainFrameId;\n      }\n\n      return true;\n    };\n  }\n}\n"]}

package/dist/esm/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;
+}