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

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

@@ -0,0 +1,790 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Locator = void 0;
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const locatorScripts_generated_js_1 = require("../dom/build/locatorScripts.generated.js");
+const selectorResolver_js_1 = require("./selectorResolver.js");
+const sdkErrors_js_1 = require("../types/public/sdkErrors.js");
+const fileUploadUtils_js_1 = require("./fileUploadUtils.js");
+const MAX_REMOTE_UPLOAD_BYTES = 50 * 1024 * 1024; // 50MB guard copied from Playwright
+/**
+ * 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.
+ */
+class Locator {
+    frame;
+    selector;
+    options;
+    selectorResolver;
+    selectorQuery;
+    // -1 means "no explicit nth()"; default locator resolves to first match for actions.
+    nthIndex;
+    constructor(frame, selector, options, nthIndex = -1) {
+        this.frame = frame;
+        this.selector = selector;
+        this.options = options;
+        this.selectorResolver = new selectorResolver_js_1.FrameSelectorResolver(this.frame);
+        this.selectorQuery = selectorResolver_js_1.FrameSelectorResolver.parseSelector(selector);
+        const normalized = Number.isFinite(nthIndex) ? Math.floor(nthIndex) : -1;
+        this.nthIndex = normalized < 0 ? -1 : normalized;
+    }
+    /** Return the owning Frame for this locator (typed accessor, no private access). */
+    getFrame() {
+        return this.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.
+     */
+    async setInputFiles(files) {
+        const session = this.frame.session;
+        const { objectId } = await this.resolveNode();
+        const tempFiles = [];
+        try {
+            // Validate element is an <input type="file">
+            try {
+                const res = await session.send("Runtime.callFunctionOn", {
+                    objectId,
+                    functionDeclaration: locatorScripts_generated_js_1.locatorScriptSources.ensureFileInputElement,
+                    returnByValue: true,
+                });
+                const ok = Boolean(res.result.value);
+                if (!ok)
+                    throw new sdkErrors_js_1.StagehandInvalidArgumentError('Target is not an <input type="file"> element');
+            }
+            catch (e) {
+                throw new sdkErrors_js_1.StagehandInvalidArgumentError(e instanceof Error
+                    ? e.message
+                    : "Unable to verify file input element");
+            }
+            const normalized = await (0, fileUploadUtils_js_1.normalizeInputFiles)(files);
+            if (!normalized.length) {
+                await session.send("DOM.setFileInputFiles", {
+                    objectId,
+                    files: [],
+                });
+                return;
+            }
+            if (this.frame.isBrowserRemote()) {
+                await this.assignFilesViaPayloadInjection(objectId, normalized);
+                return;
+            }
+            const filePaths = [];
+            for (const payload of normalized) {
+                if (payload.absolutePath) {
+                    filePaths.push(payload.absolutePath);
+                    continue;
+                }
+                const ext = path.extname(payload.name);
+                const tmp = path.join(os.tmpdir(), `stagehand-upload-${Date.now()}-${Math.random().toString(36).slice(2)}${ext}`);
+                await fs.promises.writeFile(tmp, payload.buffer);
+                tempFiles.push(tmp);
+                filePaths.push(tmp);
+            }
+            await session.send("DOM.setFileInputFiles", {
+                objectId,
+                files: filePaths,
+            });
+        }
+        finally {
+            // Cleanup: release element and remove any temporary files we created
+            await session
+                .send("Runtime.releaseObject", { objectId })
+                .catch(() => { });
+            for (const p of tempFiles) {
+                try {
+                    await fs.promises.unlink(p);
+                }
+                catch {
+                    // ignore
+                }
+            }
+        }
+    }
+    /**
+     * 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.
+     */
+    async assignFilesViaPayloadInjection(objectId, files) {
+        const session = this.frame.session;
+        for (const payload of files) {
+            if (payload.buffer.length > MAX_REMOTE_UPLOAD_BYTES) {
+                throw new sdkErrors_js_1.StagehandInvalidArgumentError(`setInputFiles(): file "${payload.name}" is larger than the 50MB limit for remote uploads`);
+            }
+        }
+        const serialized = files.map((payload) => ({
+            name: payload.name,
+            mimeType: payload.mimeType,
+            lastModified: payload.lastModified,
+            base64: payload.buffer.toString("base64"),
+        }));
+        const res = await session.send("Runtime.callFunctionOn", {
+            objectId,
+            functionDeclaration: locatorScripts_generated_js_1.locatorScriptSources.assignFilePayloadsToInputElement,
+            arguments: [
+                {
+                    value: serialized,
+                },
+            ],
+            returnByValue: true,
+        });
+        const ok = Boolean(res.result?.value);
+        if (!ok) {
+            throw new sdkErrors_js_1.StagehandInvalidArgumentError("Unable to assign file payloads to remote input element");
+        }
+    }
+    /**
+     * Return the DOM backendNodeId for this locator's target element.
+     * Useful for identity comparisons without needing element handles.
+     */
+    async backendNodeId() {
+        const session = this.frame.session;
+        const { objectId } = await this.resolveNode();
+        try {
+            await session.send("DOM.enable").catch(() => { });
+            const { node } = await session.send("DOM.describeNode", { objectId });
+            return node.backendNodeId;
+        }
+        finally {
+            await session
+                .send("Runtime.releaseObject", { objectId })
+                .catch(() => { });
+        }
+    }
+    /** Return how many nodes the current selector resolves to. */
+    async count() {
+        const session = this.frame.session;
+        await session.send("Runtime.enable");
+        await session.send("DOM.enable");
+        return this.selectorResolver.count(this.selectorQuery);
+    }
+    /**
+     * 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.
+     */
+    async centroid() {
+        const session = this.frame.session;
+        const { objectId } = await this.resolveNode();
+        try {
+            await session
+                .send("DOM.scrollIntoViewIfNeeded", { objectId })
+                .catch(() => { });
+            const box = await session.send("DOM.getBoxModel", { objectId });
+            if (!box.model)
+                throw new sdkErrors_js_1.ElementNotVisibleError(this.selector);
+            const { cx, cy } = this.centerFromBoxContent(box.model.content);
+            return { x: Math.round(cx), y: Math.round(cy) };
+        }
+        finally {
+            await session
+                .send("Runtime.releaseObject", { objectId })
+                .catch(() => { });
+        }
+    }
+    /**
+     * 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.
+     */
+    async highlight(options) {
+        const session = this.frame.session;
+        const { objectId } = await this.resolveNode();
+        const duration = Math.max(0, options?.durationMs ?? 800);
+        const borderColor = options?.borderColor ?? { r: 255, g: 0, b: 0, a: 0.9 };
+        const contentColor = options?.contentColor ?? { r: 255, g: 200, b: 0, a: 0.2 };
+        try {
+            await session.send("Overlay.enable").catch(() => { });
+            await session
+                .send("DOM.scrollIntoViewIfNeeded", { objectId })
+                .catch(() => { });
+            // Prefer backendNodeId to keep highlight stable even if objectId is released.
+            await session.send("DOM.enable").catch(() => { });
+            let backendNodeId;
+            try {
+                const { node } = await session.send("DOM.describeNode", { objectId });
+                backendNodeId = node.backendNodeId;
+            }
+            catch {
+                backendNodeId = undefined;
+            }
+            const highlightConfig = {
+                showInfo: false,
+                showStyles: false,
+                showRulers: false,
+                showExtensionLines: false,
+                borderColor,
+                contentColor,
+            };
+            const highlightOnce = async () => {
+                await session.send("Overlay.highlightNode", {
+                    ...(backendNodeId ? { backendNodeId } : { objectId }),
+                    highlightConfig,
+                });
+            };
+            // Initial draw
+            await highlightOnce();
+            // Keep alive until duration elapses to resist overlay clears on mouse move/repaints
+            if (duration > 0) {
+                const start = Date.now();
+                const tick = Math.min(300, Math.max(100, Math.floor(duration / 50)));
+                while (Date.now() - start < duration) {
+                    await new Promise((r) => setTimeout(r, tick));
+                    try {
+                        await highlightOnce();
+                    }
+                    catch {
+                        // ignore transient errors
+                    }
+                }
+                await session.send("Overlay.hideHighlight").catch(() => { });
+            }
+        }
+        finally {
+            // Releasing objectId should not affect highlight when using backendNodeId.
+            await session
+                .send("Runtime.releaseObject", { objectId })
+                .catch(() => { });
+        }
+    }
+    /**
+     * Move the mouse cursor to the element's visual center without clicking.
+     * - Scrolls into view best-effort, resolves geometry, then dispatches a mouse move.
+     */
+    async hover() {
+        const session = this.frame.session;
+        const { objectId } = await this.resolveNode();
+        try {
+            await session
+                .send("DOM.scrollIntoViewIfNeeded", { objectId })
+                .catch(() => { });
+            const box = await session.send("DOM.getBoxModel", { objectId });
+            if (!box.model)
+                throw new sdkErrors_js_1.ElementNotVisibleError(this.selector);
+            const { cx, cy } = this.centerFromBoxContent(box.model.content);
+            await session.send("Input.dispatchMouseEvent", {
+                type: "mouseMoved",
+                x: cx,
+                y: cy,
+                button: "none",
+            });
+        }
+        finally {
+            await session
+                .send("Runtime.releaseObject", { objectId })
+                .catch(() => { });
+        }
+    }
+    /**
+     * 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`.
+     */
+    async click(options) {
+        const session = this.frame.session;
+        const { objectId } = await this.resolveNode();
+        const button = options?.button ?? "left";
+        const clickCount = options?.clickCount ?? 1;
+        try {
+            // Scroll into view using objectId (avoids frontend nodeId dependence)
+            await session.send("DOM.scrollIntoViewIfNeeded", { objectId });
+            // Get geometry using objectId
+            const box = await session.send("DOM.getBoxModel", { objectId });
+            if (!box.model)
+                throw new sdkErrors_js_1.ElementNotVisibleError(this.selector);
+            const { cx, cy } = this.centerFromBoxContent(box.model.content);
+            // Dispatch click events in a pipelined burst to reduce inter-click delay
+            // from network/CPU jitter between round trips.
+            const dispatches = [];
+            dispatches.push(session.send("Input.dispatchMouseEvent", {
+                type: "mouseMoved",
+                x: cx,
+                y: cy,
+                button: "none",
+            }));
+            for (let i = 1; i <= clickCount; i++) {
+                dispatches.push(session.send("Input.dispatchMouseEvent", {
+                    type: "mousePressed",
+                    x: cx,
+                    y: cy,
+                    button,
+                    clickCount: i,
+                }));
+                dispatches.push(session.send("Input.dispatchMouseEvent", {
+                    type: "mouseReleased",
+                    x: cx,
+                    y: cy,
+                    button,
+                    clickCount: i,
+                }));
+            }
+            await Promise.all(dispatches);
+        }
+        finally {
+            // release the element handle
+            try {
+                await session.send("Runtime.releaseObject", { objectId });
+            }
+            catch {
+                // If the context navigated or was destroyed (e.g., link opens new tab),
+                // releaseObject may fail with -32000. Ignore as best-effort cleanup.
+            }
+        }
+    }
+    /**
+     * 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.
+     */
+    async sendClickEvent(options) {
+        const session = this.frame.session;
+        const { objectId } = await this.resolveNode();
+        const bubbles = options?.bubbles ?? true;
+        const cancelable = options?.cancelable ?? true;
+        const composed = options?.composed ?? true;
+        const detail = options?.detail ?? 1;
+        try {
+            await session
+                .send("DOM.scrollIntoViewIfNeeded", { objectId })
+                .catch(() => { });
+            await session.send("Runtime.callFunctionOn", {
+                objectId,
+                functionDeclaration: locatorScripts_generated_js_1.locatorScriptSources.dispatchDomClick,
+                arguments: [
+                    {
+                        value: { bubbles, cancelable, composed, detail },
+                    },
+                ],
+                returnByValue: true,
+            });
+        }
+        finally {
+            await session
+                .send("Runtime.releaseObject", { objectId })
+                .catch(() => { });
+        }
+    }
+    /**
+     * 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.
+     */
+    async scrollTo(percent) {
+        const session = this.frame.session;
+        const { objectId } = await this.resolveNode();
+        try {
+            await session.send("Runtime.callFunctionOn", {
+                objectId,
+                functionDeclaration: locatorScripts_generated_js_1.locatorScriptSources.scrollElementToPercent,
+                arguments: [{ value: percent }],
+                returnByValue: true,
+            });
+        }
+        finally {
+            await session
+                .send("Runtime.releaseObject", { objectId })
+                .catch(() => { });
+        }
+    }
+    /**
+     * 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.
+     */
+    async fill(value) {
+        const session = this.frame.session;
+        // Use the bundled locator globals; the raw fill snippet depends on helper symbols.
+        const fillDeclaration = `function(value) { ${locatorScripts_generated_js_1.locatorScriptBootstrap}; return ${locatorScripts_generated_js_1.locatorScriptGlobalRefs.fillElementValue}.call(this, value); }`;
+        const { objectId } = await this.resolveNode();
+        let releaseNeeded = true;
+        try {
+            const res = await session.send("Runtime.callFunctionOn", {
+                objectId,
+                functionDeclaration: fillDeclaration,
+                arguments: [{ value }],
+                returnByValue: true,
+            });
+            if (res.exceptionDetails) {
+                // prefer exception.description over text (eg "Uncaught")
+                const message = res.exceptionDetails.exception?.description ??
+                    res.exceptionDetails.text ??
+                    "Unknown exception during locator().fill()";
+                throw new sdkErrors_js_1.StagehandLocatorError("Filling", this.selector, message);
+            }
+            const result = res.result.value;
+            const status = typeof result === "object" && result ? result.status : undefined;
+            if (status === "done") {
+                return;
+            }
+            if (status === "needsinput") {
+                // Release the current handle before synthesizing keyboard input to avoid leaking it.
+                await session
+                    .send("Runtime.releaseObject", { objectId })
+                    .catch(() => { });
+                releaseNeeded = false;
+                const valueToType = typeof result?.value === "string" ? result.value : value;
+                let prepared = false;
+                try {
+                    const { objectId: prepObjectId } = await this.resolveNode();
+                    try {
+                        const prepRes = await session.send("Runtime.callFunctionOn", {
+                            objectId: prepObjectId,
+                            functionDeclaration: locatorScripts_generated_js_1.locatorScriptSources.prepareElementForTyping,
+                            returnByValue: true,
+                        });
+                        prepared = Boolean(prepRes.result.value);
+                    }
+                    finally {
+                        await session
+                            .send("Runtime.releaseObject", { objectId: prepObjectId })
+                            .catch(() => { });
+                    }
+                }
+                catch {
+                    // Ignore preparation failures; we'll fall back to typing best-effort.
+                }
+                if (!prepared && valueToType.length > 0) {
+                    await this.type(valueToType);
+                    return;
+                }
+                if (valueToType.length === 0) {
+                    // Simulate deleting the currently selected text to clear the field.
+                    await session.send("Input.dispatchKeyEvent", {
+                        type: "keyDown",
+                        key: "Backspace",
+                        code: "Backspace",
+                        windowsVirtualKeyCode: 8,
+                        nativeVirtualKeyCode: 8,
+                    });
+                    await session.send("Input.dispatchKeyEvent", {
+                        type: "keyUp",
+                        key: "Backspace",
+                        code: "Backspace",
+                        windowsVirtualKeyCode: 8,
+                        nativeVirtualKeyCode: 8,
+                    });
+                }
+                else {
+                    await session.send("Input.insertText", { text: valueToType });
+                }
+                return;
+            }
+            if (status === "error") {
+                const reason = typeof result?.reason === "string" && result.reason.length > 0
+                    ? result.reason
+                    : "Failed to fill element";
+                throw new sdkErrors_js_1.StagehandInvalidArgumentError(`Failed to fill element (${reason})`);
+            }
+            // Backward compatibility: if no status is returned (older bundle), fall back to setter logic.
+            if (!status) {
+                await this.type(value);
+            }
+        }
+        finally {
+            if (releaseNeeded) {
+                await session
+                    .send("Runtime.releaseObject", { objectId })
+                    .catch(() => { });
+            }
+        }
+    }
+    /**
+     * 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.
+     */
+    async type(text, options) {
+        const session = this.frame.session;
+        const { objectId } = await this.resolveNode();
+        try {
+            // Focus using JS (avoids DOM.focus(nodeId))
+            await session.send("Runtime.callFunctionOn", {
+                objectId,
+                functionDeclaration: locatorScripts_generated_js_1.locatorScriptSources.focusElement,
+                returnByValue: true,
+            });
+            if (!options?.delay) {
+                await session.send("Input.insertText", { text });
+                return;
+            }
+            for (const ch of text) {
+                await session.send("Input.dispatchKeyEvent", {
+                    type: "keyDown",
+                    text: ch,
+                    key: ch,
+                });
+                await session.send("Input.dispatchKeyEvent", {
+                    type: "keyUp",
+                    text: ch,
+                    key: ch,
+                });
+                await new Promise((r) => setTimeout(r, options.delay));
+            }
+        }
+        finally {
+            await session.send("Runtime.releaseObject", { objectId });
+        }
+    }
+    /**
+     * Select one or more options on a `<select>` element.
+     * Returns the values actually selected after the operation.
+     */
+    async selectOption(values) {
+        const session = this.frame.session;
+        const desired = Array.isArray(values) ? values : [values];
+        const { objectId } = await this.resolveNode();
+        try {
+            const res = await session.send("Runtime.callFunctionOn", {
+                objectId,
+                functionDeclaration: locatorScripts_generated_js_1.locatorScriptSources.selectElementOptions,
+                arguments: [{ value: desired }],
+                returnByValue: true,
+            });
+            return res.result.value ?? [];
+        }
+        finally {
+            await session.send("Runtime.releaseObject", { objectId });
+        }
+    }
+    /**
+     * Return true if the element is attached and visible (rough heuristic).
+     */
+    async isVisible() {
+        const session = this.frame.session;
+        const { objectId } = await this.resolveNode();
+        try {
+            const res = await session.send("Runtime.callFunctionOn", {
+                objectId,
+                functionDeclaration: locatorScripts_generated_js_1.locatorScriptSources.isElementVisible,
+                returnByValue: true,
+            });
+            return Boolean(res.result.value);
+        }
+        finally {
+            await session.send("Runtime.releaseObject", { objectId });
+        }
+    }
+    /**
+     * Return true if the element is an input[type=checkbox|radio] and is checked.
+     * Also considers aria-checked for ARIA widgets.
+     */
+    async isChecked() {
+        const session = this.frame.session;
+        const { objectId } = await this.resolveNode();
+        try {
+            const res = await session.send("Runtime.callFunctionOn", {
+                objectId,
+                functionDeclaration: locatorScripts_generated_js_1.locatorScriptSources.isElementChecked,
+                returnByValue: true,
+            });
+            return Boolean(res.result.value);
+        }
+        finally {
+            await session.send("Runtime.releaseObject", { objectId });
+        }
+    }
+    /**
+     * Return the element's input value (for input/textarea/select/contenteditable).
+     */
+    async inputValue() {
+        const session = this.frame.session;
+        const { objectId } = await this.resolveNode();
+        try {
+            const res = await session.send("Runtime.callFunctionOn", {
+                objectId,
+                functionDeclaration: locatorScripts_generated_js_1.locatorScriptSources.readElementInputValue,
+                returnByValue: true,
+            });
+            return String(res.result.value ?? "");
+        }
+        finally {
+            await session.send("Runtime.releaseObject", { objectId });
+        }
+    }
+    /**
+     * Return the element's textContent (raw, not innerText).
+     */
+    async textContent() {
+        const session = this.frame.session;
+        const { objectId } = await this.resolveNode();
+        try {
+            const res = await session.send("Runtime.callFunctionOn", {
+                objectId,
+                functionDeclaration: locatorScripts_generated_js_1.locatorScriptSources.readElementTextContent,
+                returnByValue: true,
+            });
+            return String(res.result.value ?? "");
+        }
+        finally {
+            await session.send("Runtime.releaseObject", { objectId });
+        }
+    }
+    /**
+     * Return the element's innerHTML string.
+     */
+    async innerHtml() {
+        const session = this.frame.session;
+        const { objectId } = await this.resolveNode();
+        try {
+            const res = await session.send("Runtime.callFunctionOn", {
+                objectId,
+                functionDeclaration: locatorScripts_generated_js_1.locatorScriptSources.readElementInnerHTML,
+                returnByValue: true,
+            });
+            return String(res.result.value ?? "");
+        }
+        finally {
+            await session.send("Runtime.releaseObject", { objectId });
+        }
+    }
+    /**
+     * Return the element's innerText (layout-aware, visible text).
+     */
+    async innerText() {
+        const session = this.frame.session;
+        const { objectId } = await this.resolveNode();
+        try {
+            const res = await session.send("Runtime.callFunctionOn", {
+                objectId,
+                functionDeclaration: locatorScripts_generated_js_1.locatorScriptSources.readElementInnerText,
+                returnByValue: true,
+            });
+            return String(res.result.value ?? "");
+        }
+        finally {
+            await session.send("Runtime.releaseObject", { objectId });
+        }
+    }
+    /**
+     * Return a locator narrowed to the first match.
+     */
+    first() {
+        return this.nth(0);
+    }
+    /** Return a locator narrowed to the element at the given zero-based index. */
+    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 Locator(this.frame, this.selector, this.options, nextIndex);
+    }
+    // ---------- helpers ----------
+    /**
+     * Resolve `this.selector` within the frame to `{ objectId, nodeId? }`:
+     * Delegates to a shared selector resolver so all selector logic stays in sync.
+     */
+    async resolveNode() {
+        const session = this.frame.session;
+        await session.send("Runtime.enable");
+        await session.send("DOM.enable");
+        const index = this.nthIndex < 0 ? 0 : this.nthIndex;
+        const resolved = await this.selectorResolver.resolveAtIndex(this.selectorQuery, index);
+        if (!resolved) {
+            throw new sdkErrors_js_1.StagehandElementNotFoundError([this.selector]);
+        }
+        return resolved;
+    }
+    /**
+     * Resolve all matching nodes for this locator.
+     * If the locator is narrowed via nth(), only that index is returned.
+     */
+    async resolveNodesForMask() {
+        const session = this.frame.session;
+        await session.send("Runtime.enable");
+        await session.send("DOM.enable");
+        if (this.nthIndex >= 0) {
+            const resolved = await this.selectorResolver.resolveAtIndex(this.selectorQuery, this.nthIndex);
+            if (!resolved) {
+                throw new sdkErrors_js_1.StagehandElementNotFoundError([this.selector]);
+            }
+            return [resolved];
+        }
+        const resolved = await this.selectorResolver.resolveAll(this.selectorQuery);
+        if (!resolved.length) {
+            throw new sdkErrors_js_1.StagehandElementNotFoundError([this.selector]);
+        }
+        return resolved;
+    }
+    /** Compute a center point from a BoxModel content quad */
+    centerFromBoxContent(content) {
+        // content is [x1,y1, x2,y2, x3,y3, x4,y4]
+        if (!content || content.length < 8) {
+            throw new sdkErrors_js_1.StagehandInvalidArgumentError("Invalid box model content quad");
+        }
+        const xs = [content[0], content[2], content[4], content[6]];
+        const ys = [content[1], content[3], content[5], content[7]];
+        const cx = (xs[0] + xs[1] + xs[2] + xs[3]) / 4;
+        const cy = (ys[0] + ys[1] + ys[2] + ys[3]) / 4;
+        return { cx, cy };
+    }
+}
+exports.Locator = Locator;
+//# sourceMappingURL=locator.js.map