@browserbasehq/orca 3.0.9-alpha-4 → 3.1.0-headers

package/dist/cjs/lib/v3/understudy/frame.js

@@ -0,0 +1,232 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Frame = void 0;
+const locator_js_1 = require("./locator.js");
+const sdkErrors_js_1 = require("../types/public/sdkErrors.js");
+const executionContextRegistry_js_1 = require("./executionContextRegistry.js");
+/**
+ * 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.
+ */
+class Frame {
+    session;
+    frameId;
+    pageId;
+    remoteBrowser;
+    /** Owning CDP session id (useful for logs); null for root connection (should not happen for targets) */
+    sessionId;
+    constructor(session, frameId, pageId, remoteBrowser) {
+        this.session = session;
+        this.frameId = frameId;
+        this.pageId = pageId;
+        this.remoteBrowser = remoteBrowser;
+        this.sessionId = this.session.id ?? null;
+    }
+    /** True when the controlled browser runs on a different machine. */
+    isBrowserRemote() {
+        return this.remoteBrowser;
+    }
+    /** DOM.getNodeForLocation → DOM.describeNode */
+    async getNodeAtLocation(x, y) {
+        await this.session.send("DOM.enable");
+        const { backendNodeId } = await this.session.send("DOM.getNodeForLocation", {
+            x,
+            y,
+            includeUserAgentShadowDOM: true,
+            ignorePointerEventsNone: false,
+        });
+        const { node } = await this.session.send("DOM.describeNode", { backendNodeId });
+        return node;
+    }
+    /** CSS selector → DOM.querySelector → DOM.getBoxModel */
+    async getLocationForSelector(selector) {
+        await this.session.send("DOM.enable");
+        const { root } = await this.session.send("DOM.getDocument");
+        const { nodeId } = await this.session.send("DOM.querySelector", { nodeId: root.nodeId, selector });
+        const { model } = await this.session.send("DOM.getBoxModel", { nodeId });
+        const x = model.content[0];
+        const y = model.content[1];
+        const width = model.width;
+        const height = model.height;
+        return { x, y, width, height };
+    }
+    /** Accessibility.getFullAXTree (+ recurse into child frames if requested) */
+    async getAccessibilityTree(withFrames = false) {
+        await this.session.send("Accessibility.enable");
+        let nodes;
+        try {
+            ({ nodes } = await this.session.send("Accessibility.getFullAXTree", { frameId: this.frameId }));
+        }
+        catch (e) {
+            const msg = String(e?.message ?? e ?? "");
+            const isFrameScopeError = msg.includes("Frame with the given") ||
+                msg.includes("does not belong to the target") ||
+                msg.includes("is not found");
+            if (!isFrameScopeError)
+                throw e;
+            // Retry unscoped: on OOPIF sessions, returns the child doc's AX tree.
+            ({ nodes } = await this.session.send("Accessibility.getFullAXTree"));
+        }
+        if (!withFrames)
+            return nodes;
+        const children = await this.childFrames();
+        for (const child of children) {
+            const childNodes = await child.getAccessibilityTree(false);
+            nodes.push(...childNodes);
+        }
+        return nodes;
+    }
+    /**
+     * 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.
+     */
+    async evaluate(pageFunctionOrExpression, arg) {
+        await this.session.send("Runtime.enable").catch(() => { });
+        const contextId = await this.getMainWorldExecutionContextId();
+        const isString = typeof pageFunctionOrExpression === "string";
+        let expression;
+        if (isString) {
+            expression = String(pageFunctionOrExpression);
+        }
+        else {
+            const fnSrc = pageFunctionOrExpression.toString();
+            const argJson = JSON.stringify(arg);
+            expression = `(() => {
+        const __fn = ${fnSrc};
+        const __arg = ${argJson};
+        try {
+          const __res = __fn(__arg);
+          return Promise.resolve(__res).then(v => {
+            try { return JSON.parse(JSON.stringify(v)); } catch { return v; }
+          });
+        } catch (e) { throw e; }
+      })()`;
+        }
+        let res;
+        try {
+            res = await this.session.send("Runtime.evaluate", {
+                expression,
+                contextId,
+                awaitPromise: true,
+                returnByValue: true,
+            });
+        }
+        catch (error) {
+            // Execution contexts can be recreated between context lookup and
+            // Runtime.evaluate during popup/navigate churn. Retry once with a fresh id.
+            const msg = error instanceof Error ? error.message : String(error);
+            if (!msg.includes("Cannot find context with specified id"))
+                throw error;
+            const freshContextId = await this.getMainWorldExecutionContextId();
+            res = await this.session.send("Runtime.evaluate", {
+                expression,
+                contextId: freshContextId,
+                awaitPromise: true,
+                returnByValue: true,
+            });
+        }
+        if (res.exceptionDetails) {
+            throw new sdkErrors_js_1.StagehandEvalError(res.exceptionDetails.text ?? "Evaluation failed");
+        }
+        return res.result.value;
+    }
+    /** Page.captureScreenshot (frame-scoped session) */
+    async screenshot(options) {
+        await this.session.send("Page.enable");
+        const format = options?.type ?? "png";
+        const params = {
+            format,
+            fromSurface: true,
+            captureBeyondViewport: options?.fullPage,
+        };
+        const clampScale = (value) => Math.min(2, Math.max(0.1, value));
+        const normalizedScale = typeof options?.scale === "number"
+            ? clampScale(options.scale)
+            : undefined;
+        if (options?.clip) {
+            const clip = {
+                x: options.clip.x,
+                y: options.clip.y,
+                width: options.clip.width,
+                height: options.clip.height,
+                scale: normalizedScale ?? 1,
+            };
+            params.clip = clip;
+        }
+        else if (normalizedScale !== undefined && normalizedScale !== 1) {
+            params.scale = normalizedScale;
+        }
+        if (format === "jpeg" && typeof options?.quality === "number") {
+            const q = Math.round(options.quality);
+            params.quality = Math.min(100, Math.max(0, q));
+        }
+        const { data } = await this.session.send("Page.captureScreenshot", params);
+        return Buffer.from(data, "base64");
+    }
+    /** Child frames via Page.getFrameTree */
+    async childFrames() {
+        const { frameTree } = await this.session.send("Page.getFrameTree");
+        const frames = [];
+        const collect = (tree) => {
+            if (tree.frame.parentId === this.frameId) {
+                frames.push(new Frame(this.session, tree.frame.id, this.pageId, this.remoteBrowser));
+            }
+            tree.childFrames?.forEach(collect);
+        };
+        collect(frameTree);
+        return frames;
+    }
+    /** Wait for a lifecycle state (load/domcontentloaded/networkidle) */
+    async waitForLoadState(state = "load", timeoutMs = 15_000) {
+        await this.session.send("Page.enable");
+        const targetState = state.toLowerCase();
+        const timeout = Math.max(0, timeoutMs);
+        await new Promise((resolve, reject) => {
+            let done = false;
+            let timer = null;
+            const finish = () => {
+                if (done)
+                    return;
+                done = true;
+                this.session.off("Page.lifecycleEvent", handler);
+                if (timer) {
+                    clearTimeout(timer);
+                    timer = null;
+                }
+                resolve();
+            };
+            const handler = (evt) => {
+                const sameFrame = evt.frameId === this.frameId;
+                // need to normalize here because CDP lifecycle names look like 'DOMContentLoaded'
+                // but we accept 'domcontentloaded'
+                const lifecycleName = String(evt.name ?? "").toLowerCase();
+                if (sameFrame && lifecycleName === targetState) {
+                    finish();
+                }
+            };
+            this.session.on("Page.lifecycleEvent", handler);
+            timer = setTimeout(() => {
+                if (done)
+                    return;
+                done = true;
+                this.session.off("Page.lifecycleEvent", handler);
+                reject(new Error(`waitForLoadState(${state}) timed out after ${timeout}ms for frame ${this.frameId}`));
+            }, timeout);
+        });
+    }
+    /** Simple placeholder for your own locator abstraction */
+    locator(selector, options) {
+        return new locator_js_1.Locator(this, selector, options);
+    }
+    /** Resolve the main-world execution context id for this frame. */
+    async getMainWorldExecutionContextId() {
+        return executionContextRegistry_js_1.executionContexts.waitForMainWorld(this.session, this.frameId, 1000);
+    }
+}
+exports.Frame = Frame;
+//# sourceMappingURL=frame.js.map

package/dist/cjs/lib/v3/understudy/frame.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"frame.js","sourceRoot":"","sources":["../../../../../lib/v3/understudy/frame.ts"],"names":[],"mappings":"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","sourcesContent":["// lib/v3/understudy/frame.ts\nimport { Protocol } from \"devtools-protocol\";\nimport type { CDPSessionLike } from \"./cdp.js\";\nimport { Locator } from \"./locator.js\";\nimport { StagehandEvalError } from \"../types/public/sdkErrors.js\";\nimport { executionContexts } from \"./executionContextRegistry.js\";\n\ninterface FrameManager {\n  session: CDPSessionLike;\n  frameId: string;\n  pageId: string;\n}\n\n/**\n * Frame\n *\n * A thin, session-bound handle to a specific DOM frame (by frameId).\n * All CDP calls in this class go through `this.session`, which MUST be the\n * owning session for `this.frameId`. Page is responsible for constructing\n * Frames with the correct session.\n */\nexport class Frame implements FrameManager {\n  /** Owning CDP session id (useful for logs); null for root connection (should not happen for targets) */\n  public readonly sessionId: string | null;\n\n  constructor(\n    public session: CDPSessionLike,\n    public frameId: string,\n    public pageId: string,\n    private readonly remoteBrowser: boolean,\n  ) {\n    this.sessionId = this.session.id ?? null;\n  }\n\n  /** True when the controlled browser runs on a different machine. */\n  public isBrowserRemote(): boolean {\n    return this.remoteBrowser;\n  }\n\n  /** DOM.getNodeForLocation → DOM.describeNode */\n  async getNodeAtLocation(x: number, y: number): Promise<Protocol.DOM.Node> {\n    await this.session.send(\"DOM.enable\");\n    const { backendNodeId } = await this.session.send<{\n      backendNodeId: Protocol.DOM.BackendNodeId;\n    }>(\"DOM.getNodeForLocation\", {\n      x,\n      y,\n      includeUserAgentShadowDOM: true,\n      ignorePointerEventsNone: false,\n    });\n\n    const { node } = await this.session.send<{\n      node: Protocol.DOM.Node;\n    }>(\"DOM.describeNode\", { backendNodeId });\n\n    return node;\n  }\n\n  /** CSS selector → DOM.querySelector → DOM.getBoxModel */\n  async getLocationForSelector(\n    selector: string,\n  ): Promise<{ x: number; y: number; width: number; height: number }> {\n    await this.session.send(\"DOM.enable\");\n\n    const { root } = await this.session.send<{ root: Protocol.DOM.Node }>(\n      \"DOM.getDocument\",\n    );\n\n    const { nodeId } = await this.session.send<{ nodeId: Protocol.DOM.NodeId }>(\n      \"DOM.querySelector\",\n      { nodeId: root.nodeId, selector },\n    );\n\n    const { model } = await this.session.send<{ model: Protocol.DOM.BoxModel }>(\n      \"DOM.getBoxModel\",\n      { nodeId },\n    );\n\n    const x = model.content[0];\n    const y = model.content[1];\n    const width = model.width;\n    const height = model.height;\n    return { x, y, width, height };\n  }\n\n  /** Accessibility.getFullAXTree (+ recurse into child frames if requested) */\n  async getAccessibilityTree(\n    withFrames = false,\n  ): Promise<Protocol.Accessibility.AXNode[]> {\n    await this.session.send(\"Accessibility.enable\");\n    let nodes: Protocol.Accessibility.AXNode[];\n    try {\n      ({ nodes } = await this.session.send<{\n        nodes: Protocol.Accessibility.AXNode[];\n      }>(\"Accessibility.getFullAXTree\", { frameId: this.frameId }));\n    } catch (e) {\n      const msg = String((e as Error)?.message ?? e ?? \"\");\n      const isFrameScopeError =\n        msg.includes(\"Frame with the given\") ||\n        msg.includes(\"does not belong to the target\") ||\n        msg.includes(\"is not found\");\n      if (!isFrameScopeError) throw e;\n      // Retry unscoped: on OOPIF sessions, returns the child doc's AX tree.\n      ({ nodes } = await this.session.send<{\n        nodes: Protocol.Accessibility.AXNode[];\n      }>(\"Accessibility.getFullAXTree\"));\n    }\n\n    if (!withFrames) return nodes;\n\n    const children = await this.childFrames();\n    for (const child of children) {\n      const childNodes = await child.getAccessibilityTree(false);\n      nodes.push(...childNodes);\n    }\n    return nodes;\n  }\n\n  /**\n   * Evaluate a function or expression in this frame's main world.\n   * - If a string is provided, treated as a JS expression.\n   * - If a function is provided, it is stringified and invoked with the optional argument.\n   */\n  async evaluate<R = unknown, Arg = unknown>(\n    pageFunctionOrExpression: string | ((arg: Arg) => R | Promise<R>),\n    arg?: Arg,\n  ): Promise<R> {\n    await this.session.send(\"Runtime.enable\").catch(() => {});\n    const contextId = await this.getMainWorldExecutionContextId();\n\n    const isString = typeof pageFunctionOrExpression === \"string\";\n    let expression: string;\n\n    if (isString) {\n      expression = String(pageFunctionOrExpression);\n    } else {\n      const fnSrc = pageFunctionOrExpression.toString();\n      const argJson = JSON.stringify(arg);\n      expression = `(() => {\n        const __fn = ${fnSrc};\n        const __arg = ${argJson};\n        try {\n          const __res = __fn(__arg);\n          return Promise.resolve(__res).then(v => {\n            try { return JSON.parse(JSON.stringify(v)); } catch { return v; }\n          });\n        } catch (e) { throw e; }\n      })()`;\n    }\n\n    let res: Protocol.Runtime.EvaluateResponse;\n    try {\n      res = await this.session.send<Protocol.Runtime.EvaluateResponse>(\n        \"Runtime.evaluate\",\n        {\n          expression,\n          contextId,\n          awaitPromise: true,\n          returnByValue: true,\n        },\n      );\n    } catch (error) {\n      // Execution contexts can be recreated between context lookup and\n      // Runtime.evaluate during popup/navigate churn. Retry once with a fresh id.\n      const msg = error instanceof Error ? error.message : String(error);\n      if (!msg.includes(\"Cannot find context with specified id\")) throw error;\n      const freshContextId = await this.getMainWorldExecutionContextId();\n      res = await this.session.send<Protocol.Runtime.EvaluateResponse>(\n        \"Runtime.evaluate\",\n        {\n          expression,\n          contextId: freshContextId,\n          awaitPromise: true,\n          returnByValue: true,\n        },\n      );\n    }\n    if (res.exceptionDetails) {\n      throw new StagehandEvalError(\n        res.exceptionDetails.text ?? \"Evaluation failed\",\n      );\n    }\n    return res.result.value as R;\n  }\n\n  /** Page.captureScreenshot (frame-scoped session) */\n  async screenshot(options?: {\n    fullPage?: boolean;\n    clip?: { x: number; y: number; width: number; height: number };\n    type?: \"png\" | \"jpeg\";\n    quality?: number;\n    scale?: number;\n  }): Promise<Buffer> {\n    await this.session.send(\"Page.enable\");\n    const format = options?.type ?? \"png\";\n    const params: Protocol.Page.CaptureScreenshotRequest & { scale?: number } =\n      {\n        format,\n        fromSurface: true,\n        captureBeyondViewport: options?.fullPage,\n      };\n\n    const clampScale = (value: number): number =>\n      Math.min(2, Math.max(0.1, value));\n\n    const normalizedScale =\n      typeof options?.scale === \"number\"\n        ? clampScale(options.scale)\n        : undefined;\n\n    if (options?.clip) {\n      const clip = {\n        x: options.clip.x,\n        y: options.clip.y,\n        width: options.clip.width,\n        height: options.clip.height,\n        scale: normalizedScale ?? 1,\n      };\n      params.clip = clip;\n    } else if (normalizedScale !== undefined && normalizedScale !== 1) {\n      params.scale = normalizedScale;\n    }\n\n    if (format === \"jpeg\" && typeof options?.quality === \"number\") {\n      const q = Math.round(options.quality);\n      params.quality = Math.min(100, Math.max(0, q));\n    }\n\n    const { data } =\n      await this.session.send<Protocol.Page.CaptureScreenshotResponse>(\n        \"Page.captureScreenshot\",\n        params,\n      );\n    return Buffer.from(data, \"base64\");\n  }\n\n  /** Child frames via Page.getFrameTree */\n  async childFrames(): Promise<Frame[]> {\n    const { frameTree } = await this.session.send<{\n      frameTree: Protocol.Page.FrameTree;\n    }>(\"Page.getFrameTree\");\n    const frames: Frame[] = [];\n\n    const collect = (tree: Protocol.Page.FrameTree) => {\n      if (tree.frame.parentId === this.frameId) {\n        frames.push(\n          new Frame(\n            this.session,\n            tree.frame.id,\n            this.pageId,\n            this.remoteBrowser,\n          ),\n        );\n      }\n      tree.childFrames?.forEach(collect);\n    };\n\n    collect(frameTree);\n    return frames;\n  }\n\n  /** Wait for a lifecycle state (load/domcontentloaded/networkidle) */\n  async waitForLoadState(\n    state: \"load\" | \"domcontentloaded\" | \"networkidle\" = \"load\",\n    timeoutMs: number = 15_000,\n  ): Promise<void> {\n    await this.session.send(\"Page.enable\");\n    const targetState = state.toLowerCase();\n    const timeout = Math.max(0, timeoutMs);\n    await new Promise<void>((resolve, reject) => {\n      let done = false;\n      let timer: ReturnType<typeof setTimeout> | null = null;\n      const finish = () => {\n        if (done) return;\n        done = true;\n        this.session.off(\"Page.lifecycleEvent\", handler);\n        if (timer) {\n          clearTimeout(timer);\n          timer = null;\n        }\n        resolve();\n      };\n      const handler = (evt: Protocol.Page.LifecycleEventEvent) => {\n        const sameFrame = evt.frameId === this.frameId;\n        // need to normalize here because CDP lifecycle names look like 'DOMContentLoaded'\n        // but we accept 'domcontentloaded'\n        const lifecycleName = String(evt.name ?? \"\").toLowerCase();\n        if (sameFrame && lifecycleName === targetState) {\n          finish();\n        }\n      };\n      this.session.on(\"Page.lifecycleEvent\", handler);\n\n      timer = setTimeout(() => {\n        if (done) return;\n        done = true;\n        this.session.off(\"Page.lifecycleEvent\", handler);\n        reject(\n          new Error(\n            `waitForLoadState(${state}) timed out after ${timeout}ms for frame ${this.frameId}`,\n          ),\n        );\n      }, timeout);\n    });\n  }\n\n  /** Simple placeholder for your own locator abstraction */\n  locator(\n    selector: string,\n    options?: { deep?: boolean; depth?: number },\n  ): Locator {\n    return new Locator(this, selector, options);\n  }\n\n  /** Resolve the main-world execution context id for this frame. */\n  private async getMainWorldExecutionContextId(): Promise<number> {\n    return executionContexts.waitForMainWorld(this.session, this.frameId, 1000);\n  }\n}\n"]}

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 {};

package/dist/cjs/lib/v3/understudy/frameLocator.js

@@ -0,0 +1,260 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FrameLocator = void 0;
+exports.frameLocatorFromFrame = frameLocatorFromFrame;
+const executionContextRegistry_js_1 = require("./executionContextRegistry.js");
+const sdkErrors_js_1 = require("../types/public/sdkErrors.js");
+/**
+ * FrameLocator: resolves iframe elements to their child Frames and allows
+ * creating locators scoped to that frame. Supports chaining.
+ */
+class FrameLocator {
+    parent;
+    selector;
+    page;
+    root;
+    constructor(page, selector, parent, root) {
+        this.page = page;
+        this.selector = selector;
+        this.parent = parent;
+        this.root = root;
+    }
+    /** Create a nested FrameLocator under this one. */
+    frameLocator(selector) {
+        return new FrameLocator(this.page, selector, this);
+    }
+    /** Resolve to the concrete Frame for this FrameLocator chain. */
+    async resolveFrame() {
+        const parentFrame = this.parent
+            ? await this.parent.resolveFrame()
+            : (this.root ?? this.page.mainFrame());
+        // Resolve the iframe element inside the parent frame
+        const tmp = parentFrame.locator(this.selector);
+        const parentSession = parentFrame.session;
+        const { objectId } = await tmp.resolveNode();
+        try {
+            await parentSession.send("DOM.enable").catch(() => { });
+            const desc = await parentSession.send("DOM.describeNode", { objectId });
+            const iframeBackendNodeId = desc.node.backendNodeId;
+            // Find direct child frames under the parent by consulting the Page's registry
+            const childIds = await listDirectChildFrameIdsFromRegistry(this.page, parentFrame.frameId, 1000);
+            for (const fid of childIds) {
+                try {
+                    const owner = await parentSession.send("DOM.getFrameOwner", { frameId: fid });
+                    if (owner.backendNodeId === iframeBackendNodeId) {
+                        // Ensure child frame is ready (handles OOPIF adoption or same-process)
+                        await ensureChildFrameReady(this.page, parentFrame, fid, 1200);
+                        return this.page.frameForId(fid);
+                    }
+                }
+                catch {
+                    // ignore and try next
+                }
+            }
+            throw new sdkErrors_js_1.ContentFrameNotFoundError(this.selector);
+        }
+        finally {
+            await parentSession
+                .send("Runtime.releaseObject", { objectId })
+                .catch(() => { });
+        }
+    }
+    /** Return a Locator scoped to this frame. Methods delegate to the frame lazily. */
+    locator(selector) {
+        return new LocatorDelegate(this, selector);
+    }
+}
+exports.FrameLocator = FrameLocator;
+/** A small delegating wrapper that resolves the frame lazily per call. */
+class LocatorDelegate {
+    fl;
+    sel;
+    nthIndex;
+    constructor(fl, sel, nthIndex = -1) {
+        this.fl = fl;
+        this.sel = sel;
+        this.nthIndex = nthIndex;
+    }
+    async real() {
+        const frame = await this.fl.resolveFrame();
+        const locator = frame.locator(this.sel);
+        if (this.nthIndex < 0)
+            return locator;
+        return locator.nth(this.nthIndex);
+    }
+    // Locator API delegates
+    async click(options) {
+        return (await this.real()).click(options);
+    }
+    async hover() {
+        return (await this.real()).hover();
+    }
+    async fill(value) {
+        return (await this.real()).fill(value);
+    }
+    async type(text, options) {
+        return (await this.real()).type(text, options);
+    }
+    async selectOption(values) {
+        return (await this.real()).selectOption(values);
+    }
+    async scrollTo(percent) {
+        return (await this.real()).scrollTo(percent);
+    }
+    async isVisible() {
+        return (await this.real()).isVisible();
+    }
+    async isChecked() {
+        return (await this.real()).isChecked();
+    }
+    async inputValue() {
+        return (await this.real()).inputValue();
+    }
+    async textContent() {
+        return (await this.real()).textContent();
+    }
+    async innerHtml() {
+        return (await this.real()).innerHtml();
+    }
+    async innerText() {
+        return (await this.real()).innerText();
+    }
+    async count() {
+        return (await this.real()).count();
+    }
+    first() {
+        return this.nth(0);
+    }
+    nth(index) {
+        const value = Number(index);
+        if (!Number.isFinite(value) || value < 0) {
+            throw new sdkErrors_js_1.StagehandInvalidArgumentError("locator().nth() expects a non-negative index");
+        }
+        const nextIndex = Math.floor(value);
+        if (nextIndex === this.nthIndex)
+            return this;
+        return new LocatorDelegate(this.fl, this.sel, nextIndex);
+    }
+}
+/** Factory to start a FrameLocator chain from an arbitrary root Frame. */
+function frameLocatorFromFrame(page, root, selector) {
+    return new FrameLocator(page, selector, undefined, root);
+}
+async function listDirectChildFrameIdsFromRegistry(page, parentFrameId, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    while (true) {
+        try {
+            const tree = page.getFullFrameTree();
+            const node = findFrameNode(tree, parentFrameId);
+            const ids = node?.childFrames?.map((c) => c.frame.id) ?? [];
+            if (ids.length > 0 || Date.now() >= deadline)
+                return ids;
+        }
+        catch {
+            // ignore
+        }
+        await new Promise((r) => setTimeout(r, 50));
+    }
+}
+function findFrameNode(tree, targetId) {
+    if (tree.frame.id === targetId)
+        return tree;
+    for (const c of tree.childFrames ?? []) {
+        const hit = findFrameNode(c, targetId);
+        if (hit)
+            return hit;
+    }
+    return undefined;
+}
+/**
+ * Ensure we can evaluate in the child frame with minimal delay.
+ * - If the child is same-process: parent session owns it and main world appears quickly.
+ * - If OOPIF and adoption not finished: wait briefly for ownership change, then main world.
+ */
+async function ensureChildFrameReady(page, parentFrame, childFrameId, budgetMs) {
+    const parentSession = parentFrame.session;
+    const deadline = Date.now() + Math.max(0, budgetMs);
+    // If already owned by a different session (OOPIF adopted), wait briefly there.
+    const owner = page.getSessionForFrame(childFrameId);
+    if (owner && owner !== parentSession) {
+        try {
+            await executionContextRegistry_js_1.executionContexts.waitForMainWorld(owner, childFrameId, 600);
+        }
+        catch {
+            // best effort
+        }
+        return;
+    }
+    const hasMainWorldOnParent = () => {
+        try {
+            return (executionContextRegistry_js_1.executionContexts.getMainWorld(parentSession, childFrameId) !== null);
+        }
+        catch {
+            return false;
+        }
+    };
+    if (hasMainWorldOnParent())
+        return;
+    await parentSession
+        .send("Page.setLifecycleEventsEnabled", { enabled: true })
+        .catch(() => { });
+    await parentSession.send("Runtime.enable").catch(() => { });
+    await new Promise((resolve) => {
+        let done = false;
+        const finish = () => {
+            if (done)
+                return;
+            done = true;
+            parentSession.off("Page.lifecycleEvent", onLifecycle);
+            resolve();
+        };
+        const onLifecycle = (evt) => {
+            if (evt.frameId !== childFrameId ||
+                (evt.name !== "DOMContentLoaded" &&
+                    evt.name !== "load" &&
+                    evt.name !== "networkIdle" &&
+                    evt.name !== "networkidle")) {
+                return;
+            }
+            if (hasMainWorldOnParent())
+                return finish();
+            try {
+                const nowOwner = page.getSessionForFrame(childFrameId);
+                if (nowOwner && nowOwner !== parentSession) {
+                    const left = Math.max(150, deadline - Date.now());
+                    executionContextRegistry_js_1.executionContexts
+                        .waitForMainWorld(nowOwner, childFrameId, left)
+                        .finally(finish);
+                }
+            }
+            catch {
+                // ignore
+            }
+        };
+        parentSession.on("Page.lifecycleEvent", onLifecycle);
+        const tick = () => {
+            if (done)
+                return;
+            if (hasMainWorldOnParent())
+                return finish();
+            try {
+                const nowOwner = page.getSessionForFrame(childFrameId);
+                if (nowOwner && nowOwner !== parentSession) {
+                    const left = Math.max(150, deadline - Date.now());
+                    executionContextRegistry_js_1.executionContexts
+                        .waitForMainWorld(nowOwner, childFrameId, left)
+                        .finally(finish);
+                    return;
+                }
+            }
+            catch {
+                // ignore
+            }
+            if (Date.now() >= deadline)
+                return finish();
+            setTimeout(tick, 50);
+        };
+        tick();
+    });
+}
+//# sourceMappingURL=frameLocator.js.map

package/dist/cjs/lib/v3/understudy/frameLocator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"frameLocator.js","sourceRoot":"","sources":["../../../../../lib/v3/understudy/frameLocator.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Protocol } from \"devtools-protocol\";\nimport { Locator } from \"./locator.js\";\nimport type { Page } from \"./page.js\";\nimport { Frame } from \"./frame.js\";\nimport { executionContexts } from \"./executionContextRegistry.js\";\nimport {\n  ContentFrameNotFoundError,\n  StagehandInvalidArgumentError,\n} from \"../types/public/sdkErrors.js\";\n\n/**\n * FrameLocator: resolves iframe elements to their child Frames and allows\n * creating locators scoped to that frame. Supports chaining.\n */\nexport class FrameLocator {\n  private readonly parent?: FrameLocator;\n  private readonly selector: string;\n  private readonly page: Page;\n  private readonly root?: Frame;\n\n  constructor(\n    page: Page,\n    selector: string,\n    parent?: FrameLocator,\n    root?: Frame,\n  ) {\n    this.page = page;\n    this.selector = selector;\n    this.parent = parent;\n    this.root = root;\n  }\n\n  /** Create a nested FrameLocator under this one. */\n  frameLocator(selector: string): FrameLocator {\n    return new FrameLocator(this.page, selector, this);\n  }\n\n  /** Resolve to the concrete Frame for this FrameLocator chain. */\n  async resolveFrame(): Promise<Frame> {\n    const parentFrame: Frame = this.parent\n      ? await this.parent.resolveFrame()\n      : (this.root ?? this.page.mainFrame());\n\n    // Resolve the iframe element inside the parent frame\n    const tmp = parentFrame.locator(this.selector);\n    const parentSession = parentFrame.session;\n    const { objectId } = await tmp.resolveNode();\n\n    try {\n      await parentSession.send(\"DOM.enable\").catch(() => {});\n      const desc = await parentSession.send<Protocol.DOM.DescribeNodeResponse>(\n        \"DOM.describeNode\",\n        { objectId },\n      );\n      const iframeBackendNodeId = desc.node.backendNodeId;\n\n      // Find direct child frames under the parent by consulting the Page's registry\n      const childIds = await listDirectChildFrameIdsFromRegistry(\n        this.page,\n        parentFrame.frameId,\n        1000,\n      );\n\n      for (const fid of childIds) {\n        try {\n          const owner = await parentSession.send<{\n            backendNodeId: Protocol.DOM.BackendNodeId;\n            nodeId?: Protocol.DOM.NodeId;\n          }>(\"DOM.getFrameOwner\", { frameId: fid as Protocol.Page.FrameId });\n          if (owner.backendNodeId === iframeBackendNodeId) {\n            // Ensure child frame is ready (handles OOPIF adoption or same-process)\n            await ensureChildFrameReady(this.page, parentFrame, fid, 1200);\n            return this.page.frameForId(fid);\n          }\n        } catch {\n          // ignore and try next\n        }\n      }\n      throw new ContentFrameNotFoundError(this.selector);\n    } finally {\n      await parentSession\n        .send(\"Runtime.releaseObject\", { objectId })\n        .catch(() => {});\n    }\n  }\n\n  /** Return a Locator scoped to this frame. Methods delegate to the frame lazily. */\n  locator(selector: string): LocatorDelegate {\n    return new LocatorDelegate(this, selector);\n  }\n}\n\n/** A small delegating wrapper that resolves the frame lazily per call. */\nclass LocatorDelegate {\n  constructor(\n    private readonly fl: FrameLocator,\n    private readonly sel: string,\n    private readonly nthIndex: number = -1,\n  ) {}\n\n  private async real(): Promise<Locator> {\n    const frame = await this.fl.resolveFrame();\n    const locator = frame.locator(this.sel);\n    if (this.nthIndex < 0) return locator;\n    return locator.nth(this.nthIndex);\n  }\n\n  // Locator API delegates\n  async click(options?: {\n    button?: \"left\" | \"right\" | \"middle\";\n    clickCount?: number;\n  }) {\n    return (await this.real()).click(options);\n  }\n  async hover() {\n    return (await this.real()).hover();\n  }\n  async fill(value: string) {\n    return (await this.real()).fill(value);\n  }\n  async type(text: string, options?: { delay?: number }) {\n    return (await this.real()).type(text, options);\n  }\n  async selectOption(values: string | string[]) {\n    return (await this.real()).selectOption(values);\n  }\n  async scrollTo(percent: number | string) {\n    return (await this.real()).scrollTo(percent);\n  }\n  async isVisible() {\n    return (await this.real()).isVisible();\n  }\n  async isChecked() {\n    return (await this.real()).isChecked();\n  }\n  async inputValue() {\n    return (await this.real()).inputValue();\n  }\n  async textContent() {\n    return (await this.real()).textContent();\n  }\n  async innerHtml() {\n    return (await this.real()).innerHtml();\n  }\n  async innerText() {\n    return (await this.real()).innerText();\n  }\n  async count() {\n    return (await this.real()).count();\n  }\n  first(): LocatorDelegate {\n    return this.nth(0);\n  }\n  nth(index: number): LocatorDelegate {\n    const value = Number(index);\n    if (!Number.isFinite(value) || value < 0) {\n      throw new StagehandInvalidArgumentError(\n        \"locator().nth() expects a non-negative index\",\n      );\n    }\n\n    const nextIndex = Math.floor(value);\n    if (nextIndex === this.nthIndex) return this;\n\n    return new LocatorDelegate(this.fl, this.sel, nextIndex);\n  }\n}\n\n/** Factory to start a FrameLocator chain from an arbitrary root Frame. */\nexport function frameLocatorFromFrame(\n  page: Page,\n  root: Frame,\n  selector: string,\n): FrameLocator {\n  return new FrameLocator(page, selector, undefined, root);\n}\n\nasync function listDirectChildFrameIdsFromRegistry(\n  page: Page,\n  parentFrameId: string,\n  timeoutMs: number,\n): Promise<string[]> {\n  const deadline = Date.now() + timeoutMs;\n  while (true) {\n    try {\n      const tree = page.getFullFrameTree();\n      const node = findFrameNode(tree, parentFrameId);\n      const ids = node?.childFrames?.map((c) => c.frame.id as string) ?? [];\n      if (ids.length > 0 || Date.now() >= deadline) return ids;\n    } catch {\n      // ignore\n    }\n    await new Promise((r) => setTimeout(r, 50));\n  }\n}\n\nfunction findFrameNode(\n  tree: Protocol.Page.FrameTree,\n  targetId: string,\n): Protocol.Page.FrameTree | undefined {\n  if (tree.frame.id === targetId) return tree;\n  for (const c of tree.childFrames ?? []) {\n    const hit = findFrameNode(c, targetId);\n    if (hit) return hit;\n  }\n  return undefined;\n}\n\n/**\n * Ensure we can evaluate in the child frame with minimal delay.\n * - If the child is same-process: parent session owns it and main world appears quickly.\n * - If OOPIF and adoption not finished: wait briefly for ownership change, then main world.\n */\nasync function ensureChildFrameReady(\n  page: Page,\n  parentFrame: Frame,\n  childFrameId: string,\n  budgetMs: number,\n): Promise<void> {\n  const parentSession = parentFrame.session;\n  const deadline = Date.now() + Math.max(0, budgetMs);\n\n  // If already owned by a different session (OOPIF adopted), wait briefly there.\n  const owner = page.getSessionForFrame(childFrameId);\n  if (owner && owner !== parentSession) {\n    try {\n      await executionContexts.waitForMainWorld(owner, childFrameId, 600);\n    } catch {\n      // best effort\n    }\n    return;\n  }\n\n  const hasMainWorldOnParent = (): boolean => {\n    try {\n      return (\n        executionContexts.getMainWorld(parentSession, childFrameId) !== null\n      );\n    } catch {\n      return false;\n    }\n  };\n\n  if (hasMainWorldOnParent()) return;\n\n  await parentSession\n    .send(\"Page.setLifecycleEventsEnabled\", { enabled: true })\n    .catch(() => {});\n  await parentSession.send(\"Runtime.enable\").catch(() => {});\n\n  await new Promise<void>((resolve) => {\n    let done = false;\n    const finish = () => {\n      if (done) return;\n      done = true;\n      parentSession.off(\"Page.lifecycleEvent\", onLifecycle);\n      resolve();\n    };\n    const onLifecycle = (evt: Protocol.Page.LifecycleEventEvent) => {\n      if (\n        evt.frameId !== childFrameId ||\n        (evt.name !== \"DOMContentLoaded\" &&\n          evt.name !== \"load\" &&\n          evt.name !== \"networkIdle\" &&\n          evt.name !== \"networkidle\")\n      ) {\n        return;\n      }\n      if (hasMainWorldOnParent()) return finish();\n      try {\n        const nowOwner = page.getSessionForFrame(childFrameId);\n        if (nowOwner && nowOwner !== parentSession) {\n          const left = Math.max(150, deadline - Date.now());\n          executionContexts\n            .waitForMainWorld(nowOwner, childFrameId, left)\n            .finally(finish);\n        }\n      } catch {\n        // ignore\n      }\n    };\n    parentSession.on(\"Page.lifecycleEvent\", onLifecycle);\n\n    const tick = () => {\n      if (done) return;\n      if (hasMainWorldOnParent()) return finish();\n      try {\n        const nowOwner = page.getSessionForFrame(childFrameId);\n        if (nowOwner && nowOwner !== parentSession) {\n          const left = Math.max(150, deadline - Date.now());\n          executionContexts\n            .waitForMainWorld(nowOwner, childFrameId, left)\n            .finally(finish);\n          return;\n        }\n      } catch {\n        // ignore\n      }\n      if (Date.now() >= deadline) return finish();\n      setTimeout(tick, 50);\n    };\n    tick();\n  });\n}\n"]}