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

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

@@ -0,0 +1,204 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DeepLocatorDelegate = void 0;
+exports.deepLocatorThroughIframes = deepLocatorThroughIframes;
+exports.resolveLocatorTarget = resolveLocatorTarget;
+exports.resolveLocatorWithHops = resolveLocatorWithHops;
+exports.deepLocatorFromPage = deepLocatorFromPage;
+const locator_js_1 = require("./locator.js");
+const frameLocator_js_1 = require("./frameLocator.js");
+const sdkErrors_js_1 = require("../types/public/sdkErrors.js");
+const focusSelectors_js_1 = require("./a11y/snapshot/focusSelectors.js");
+/** Parse XPath into steps preserving '/' vs '//' and the raw token (with [n]) */
+function parseXPath(path) {
+    const s = path.trim();
+    let i = 0;
+    const steps = [];
+    while (i < s.length) {
+        let axis = "child";
+        if (s.startsWith("//", i)) {
+            axis = "desc";
+            i += 2;
+        }
+        else if (s[i] === "/") {
+            axis = "child";
+            i += 1;
+        }
+        const start = i;
+        while (i < s.length && s[i] !== "/")
+            i++;
+        const raw = s.slice(start, i).trim();
+        if (!raw)
+            continue;
+        const name = raw.replace(/\[\d+\]\s*$/u, "").toLowerCase();
+        steps.push({ axis, raw, name });
+    }
+    return steps;
+}
+function buildXPathFromSteps(steps) {
+    let out = "";
+    for (const st of steps) {
+        out += st.axis === "desc" ? "//" : "/";
+        out += st.raw; // keep predicates intact
+    }
+    return out || "/";
+}
+/** Build a Locator scoped to the correct frame for a deep XPath crossing iframes. */
+async function deepLocatorThroughIframes(page, root, xpathOrSelector) {
+    const target = await resolveDeepXPathTarget(page, root, xpathOrSelector);
+    return new locator_js_1.Locator(target.frame, target.selector);
+}
+/**
+ * Unified resolver that supports '>>' hop notation, deep XPath across iframes,
+ * and plain single-frame selectors. Keeps hop logic in one shared place.
+ */
+async function resolveLocatorTarget(page, root, selectorRaw) {
+    const sel = selectorRaw.trim();
+    const parts = sel
+        .split(">>")
+        .map((s) => s.trim())
+        .filter(Boolean);
+    if (parts.length > 1) {
+        // Build a FrameLocator chain for all but the last segment
+        let fl = (0, frameLocator_js_1.frameLocatorFromFrame)(page, root, parts[0]);
+        for (let i = 1; i < parts.length - 1; i++) {
+            fl = fl.frameLocator(parts[i]);
+        }
+        const targetFrame = await fl.resolveFrame();
+        return { frame: targetFrame, selector: parts[parts.length - 1] };
+    }
+    // No hops — delegate to XPath-aware deep resolver when needed
+    const isXPath = sel.startsWith("xpath=") || sel.startsWith("/");
+    if (isXPath) {
+        return resolveDeepXPathTarget(page, root, sel);
+    }
+    return { frame: root, selector: sel };
+}
+async function resolveLocatorWithHops(page, root, selectorRaw) {
+    const target = await resolveLocatorTarget(page, root, selectorRaw);
+    return new locator_js_1.Locator(target.frame, target.selector);
+}
+/**
+ * DeepLocatorDelegate: a lightweight wrapper that looks like a Locator and
+ * resolves to the correct frame/element on each call using hop/deep-XPath logic.
+ *
+ * Returned by `page.deepLocator()` for ergonomic, await-free chaining:
+ *   page.deepLocator('iframe#ifrA >> #btn').click()
+ */
+class DeepLocatorDelegate {
+    page;
+    root;
+    selector;
+    nthIndex;
+    constructor(page, root, selector, nthIndex = 0) {
+        this.page = page;
+        this.root = root;
+        this.selector = selector;
+        this.nthIndex = nthIndex;
+    }
+    async real() {
+        const base = await resolveLocatorWithHops(this.page, this.root, this.selector);
+        return base.nth(this.nthIndex);
+    }
+    // Locator API delegates
+    async click(options) {
+        return (await this.real()).click(options);
+    }
+    async count() {
+        return (await this.real()).count();
+    }
+    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 centroid() {
+        return (await this.real()).centroid();
+    }
+    async backendNodeId() {
+        return (await this.real()).backendNodeId();
+    }
+    async highlight(options) {
+        return (await this.real()).highlight(options);
+    }
+    async sendClickEvent(options) {
+        return (await this.real()).sendClickEvent(options);
+    }
+    async setInputFiles(files) {
+        return (await this.real()).setInputFiles(files);
+    }
+    first() {
+        return this.nth(0);
+    }
+    nth(index) {
+        const value = Number(index);
+        if (!Number.isFinite(value) || value < 0) {
+            throw new sdkErrors_js_1.StagehandInvalidArgumentError("deepLocator().nth() expects a non-negative index");
+        }
+        const nextIndex = Math.floor(value);
+        if (nextIndex === this.nthIndex)
+            return this;
+        return new DeepLocatorDelegate(this.page, this.root, this.selector, nextIndex);
+    }
+}
+exports.DeepLocatorDelegate = DeepLocatorDelegate;
+/** Factory to create a deep locator delegate from a Page + root frame. */
+function deepLocatorFromPage(page, root, selector) {
+    return new DeepLocatorDelegate(page, root, selector);
+}
+async function resolveDeepXPathTarget(page, root, xpathOrSelector) {
+    let path = xpathOrSelector.trim();
+    if (path.startsWith("xpath="))
+        path = path.slice("xpath=".length).trim();
+    if (!path.startsWith("/"))
+        path = "/" + path;
+    const steps = parseXPath(path);
+    let fl;
+    let buf = [];
+    const flushIntoFrameLocator = () => {
+        if (!buf.length)
+            return;
+        const selectorForIframe = "xpath=" + buildXPathFromSteps(buf);
+        fl = fl
+            ? fl.frameLocator(selectorForIframe)
+            : (0, frameLocator_js_1.frameLocatorFromFrame)(page, root, selectorForIframe);
+        buf = [];
+    };
+    for (const st of steps) {
+        buf.push(st);
+        if (focusSelectors_js_1.IFRAME_STEP_RE.test(st.name))
+            flushIntoFrameLocator();
+    }
+    const finalSelector = "xpath=" + buildXPathFromSteps(buf);
+    const targetFrame = fl ? await fl.resolveFrame() : root;
+    return { frame: targetFrame, selector: finalSelector };
+}
+//# sourceMappingURL=deepLocator.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"deepLocator.js","sourceRoot":"","sources":["../../../../../lib/v3/understudy/deepLocator.ts"],"names":[],"mappings":"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","sourcesContent":["import { Locator } from \"./locator.js\";\nimport type { Frame } from \"./frame.js\";\nimport type { Page } from \"./page.js\";\nimport { FrameLocator, frameLocatorFromFrame } from \"./frameLocator.js\";\nimport { StagehandInvalidArgumentError } from \"../types/public/sdkErrors.js\";\nimport { IFRAME_STEP_RE } from \"./a11y/snapshot/focusSelectors.js\";\n\ntype Axis = \"child\" | \"desc\";\ntype Step = { axis: Axis; raw: string; name: string };\n\nexport type ResolvedLocatorTarget = {\n  frame: Frame;\n  selector: string;\n};\n\n/** Parse XPath into steps preserving '/' vs '//' and the raw token (with [n]) */\nfunction parseXPath(path: string): Step[] {\n  const s = path.trim();\n  let i = 0;\n  const steps: Step[] = [];\n  while (i < s.length) {\n    let axis: Axis = \"child\";\n    if (s.startsWith(\"//\", i)) {\n      axis = \"desc\";\n      i += 2;\n    } else if (s[i] === \"/\") {\n      axis = \"child\";\n      i += 1;\n    }\n\n    const start = i;\n    while (i < s.length && s[i] !== \"/\") i++;\n    const raw = s.slice(start, i).trim();\n    if (!raw) continue;\n\n    const name = raw.replace(/\\[\\d+\\]\\s*$/u, \"\").toLowerCase();\n    steps.push({ axis, raw, name });\n  }\n  return steps;\n}\n\nfunction buildXPathFromSteps(steps: ReadonlyArray<Step>): string {\n  let out = \"\";\n  for (const st of steps) {\n    out += st.axis === \"desc\" ? \"//\" : \"/\";\n    out += st.raw; // keep predicates intact\n  }\n  return out || \"/\";\n}\n\n/** Build a Locator scoped to the correct frame for a deep XPath crossing iframes. */\nexport async function deepLocatorThroughIframes(\n  page: Page,\n  root: Frame,\n  xpathOrSelector: string,\n): Promise<Locator> {\n  const target = await resolveDeepXPathTarget(page, root, xpathOrSelector);\n  return new Locator(target.frame, target.selector);\n}\n\n/**\n * Unified resolver that supports '>>' hop notation, deep XPath across iframes,\n * and plain single-frame selectors. Keeps hop logic in one shared place.\n */\nexport async function resolveLocatorTarget(\n  page: Page,\n  root: Frame,\n  selectorRaw: string,\n): Promise<ResolvedLocatorTarget> {\n  const sel = selectorRaw.trim();\n  const parts = sel\n    .split(\">>\")\n    .map((s) => s.trim())\n    .filter(Boolean);\n\n  if (parts.length > 1) {\n    // Build a FrameLocator chain for all but the last segment\n    let fl = frameLocatorFromFrame(page, root, parts[0]!);\n    for (let i = 1; i < parts.length - 1; i++) {\n      fl = fl.frameLocator(parts[i]!);\n    }\n    const targetFrame = await fl.resolveFrame();\n    return { frame: targetFrame, selector: parts[parts.length - 1]! };\n  }\n\n  // No hops — delegate to XPath-aware deep resolver when needed\n  const isXPath = sel.startsWith(\"xpath=\") || sel.startsWith(\"/\");\n  if (isXPath) {\n    return resolveDeepXPathTarget(page, root, sel);\n  }\n  return { frame: root, selector: sel };\n}\n\nexport async function resolveLocatorWithHops(\n  page: Page,\n  root: Frame,\n  selectorRaw: string,\n): Promise<Locator> {\n  const target = await resolveLocatorTarget(page, root, selectorRaw);\n  return new Locator(target.frame, target.selector);\n}\n\n/**\n * DeepLocatorDelegate: a lightweight wrapper that looks like a Locator and\n * resolves to the correct frame/element on each call using hop/deep-XPath logic.\n *\n * Returned by `page.deepLocator()` for ergonomic, await-free chaining:\n *   page.deepLocator('iframe#ifrA >> #btn').click()\n */\nexport class DeepLocatorDelegate {\n  constructor(\n    private readonly page: Page,\n    private readonly root: Frame,\n    private readonly selector: string,\n    private readonly nthIndex: number = 0,\n  ) {}\n\n  private async real(): Promise<Locator> {\n    const base = await resolveLocatorWithHops(\n      this.page,\n      this.root,\n      this.selector,\n    );\n    return base.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 count() {\n    return (await this.real()).count();\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 centroid() {\n    return (await this.real()).centroid();\n  }\n  async backendNodeId() {\n    return (await this.real()).backendNodeId();\n  }\n  async highlight(options?: {\n    durationMs?: number;\n    borderColor?: { r: number; g: number; b: number; a?: number };\n    contentColor?: { r: number; g: number; b: number; a?: number };\n  }) {\n    return (await this.real()).highlight(options);\n  }\n  async sendClickEvent(options?: {\n    bubbles?: boolean;\n    cancelable?: boolean;\n    composed?: boolean;\n    detail?: number;\n  }) {\n    return (await this.real()).sendClickEvent(options);\n  }\n  async setInputFiles(\n    files:\n      | string\n      | string[]\n      | {\n          name: string;\n          mimeType: string;\n          buffer: ArrayBuffer | Uint8Array | Buffer | string;\n        }\n      | Array<{\n          name: string;\n          mimeType: string;\n          buffer: ArrayBuffer | Uint8Array | Buffer | string;\n        }>,\n  ) {\n    return (await this.real()).setInputFiles(files);\n  }\n  first() {\n    return this.nth(0);\n  }\n  nth(index: number): DeepLocatorDelegate {\n    const value = Number(index);\n    if (!Number.isFinite(value) || value < 0) {\n      throw new StagehandInvalidArgumentError(\n        \"deepLocator().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 DeepLocatorDelegate(\n      this.page,\n      this.root,\n      this.selector,\n      nextIndex,\n    );\n  }\n}\n\n/** Factory to create a deep locator delegate from a Page + root frame. */\nexport function deepLocatorFromPage(\n  page: Page,\n  root: Frame,\n  selector: string,\n): DeepLocatorDelegate {\n  return new DeepLocatorDelegate(page, root, selector);\n}\n\nasync function resolveDeepXPathTarget(\n  page: Page,\n  root: Frame,\n  xpathOrSelector: string,\n): Promise<ResolvedLocatorTarget> {\n  let path = xpathOrSelector.trim();\n  if (path.startsWith(\"xpath=\")) path = path.slice(\"xpath=\".length).trim();\n  if (!path.startsWith(\"/\")) path = \"/\" + path;\n\n  const steps = parseXPath(path);\n  let fl: FrameLocator | undefined;\n  let buf: Step[] = [];\n\n  const flushIntoFrameLocator = () => {\n    if (!buf.length) return;\n    const selectorForIframe = \"xpath=\" + buildXPathFromSteps(buf);\n    fl = fl\n      ? fl.frameLocator(selectorForIframe)\n      : frameLocatorFromFrame(page, root, selectorForIframe);\n    buf = [];\n  };\n\n  for (const st of steps) {\n    buf.push(st);\n    if (IFRAME_STEP_RE.test(st.name)) flushIntoFrameLocator();\n  }\n\n  const finalSelector = \"xpath=\" + buildXPathFromSteps(buf);\n  const targetFrame = fl ? await fl.resolveFrame() : root;\n  return { frame: targetFrame, selector: finalSelector };\n}\n"]}

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

@@ -0,0 +1,15 @@
+import type { Protocol } from "devtools-protocol";
+import type { CDPSessionLike } from "./cdp.js";
+type FrameId = Protocol.Page.FrameId;
+type ExecId = Protocol.Runtime.ExecutionContextId;
+export declare class ExecutionContextRegistry {
+    private readonly byFrame;
+    private readonly byExec;
+    /** Wire listeners for this session. Call BEFORE Runtime.enable. */
+    attachSession(session: CDPSessionLike): void;
+    getMainWorld(session: CDPSessionLike, frameId: FrameId): ExecId | null;
+    waitForMainWorld(session: CDPSessionLike, frameId: FrameId, timeoutMs?: number): Promise<ExecId>;
+    private register;
+}
+export declare const executionContexts: ExecutionContextRegistry;
+export {};

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

@@ -0,0 +1,87 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.executionContexts = exports.ExecutionContextRegistry = void 0;
+class ExecutionContextRegistry {
+    byFrame = new WeakMap();
+    byExec = new WeakMap();
+    /** Wire listeners for this session. Call BEFORE Runtime.enable. */
+    attachSession(session) {
+        const onCreated = (evt) => {
+            const aux = (evt.context.auxData ?? {});
+            if (aux.isDefault === true && typeof aux.frameId === "string") {
+                this.register(session, aux.frameId, evt.context.id);
+            }
+        };
+        const onDestroyed = (evt) => {
+            const rev = this.byExec.get(session);
+            const fwd = this.byFrame.get(session);
+            if (!rev || !fwd)
+                return;
+            const frameId = rev.get(evt.executionContextId);
+            if (!frameId)
+                return;
+            rev.delete(evt.executionContextId);
+            if (fwd.get(frameId) === evt.executionContextId)
+                fwd.delete(frameId);
+        };
+        const onCleared = () => {
+            this.byFrame.delete(session);
+            this.byExec.delete(session);
+        };
+        session.on("Runtime.executionContextCreated", onCreated);
+        session.on("Runtime.executionContextDestroyed", onDestroyed);
+        session.on("Runtime.executionContextsCleared", onCleared);
+    }
+    getMainWorld(session, frameId) {
+        return this.byFrame.get(session)?.get(frameId) ?? null;
+    }
+    async waitForMainWorld(session, frameId, timeoutMs = 800) {
+        const cached = this.getMainWorld(session, frameId);
+        if (cached)
+            return cached;
+        await session.send("Runtime.enable").catch(() => { });
+        const after = this.getMainWorld(session, frameId);
+        if (after)
+            return after;
+        return await new Promise((resolve, reject) => {
+            let done = false;
+            const onCreated = (evt) => {
+                const aux = (evt.context.auxData ?? {});
+                if (aux.isDefault === true && aux.frameId === frameId) {
+                    this.register(session, frameId, evt.context.id);
+                    if (!done) {
+                        done = true;
+                        clearTimeout(timer);
+                        session.off("Runtime.executionContextCreated", onCreated);
+                        resolve(evt.context.id);
+                    }
+                }
+            };
+            const timer = setTimeout(() => {
+                if (!done) {
+                    done = true;
+                    session.off("Runtime.executionContextCreated", onCreated);
+                    reject(new Error(`main world not ready for frame ${frameId}`));
+                }
+            }, timeoutMs);
+            session.on("Runtime.executionContextCreated", onCreated);
+        });
+    }
+    register(session, frameId, ctxId) {
+        let fwd = this.byFrame.get(session);
+        if (!fwd) {
+            fwd = new Map();
+            this.byFrame.set(session, fwd);
+        }
+        let rev = this.byExec.get(session);
+        if (!rev) {
+            rev = new Map();
+            this.byExec.set(session, rev);
+        }
+        fwd.set(frameId, ctxId);
+        rev.set(ctxId, frameId);
+    }
+}
+exports.ExecutionContextRegistry = ExecutionContextRegistry;
+exports.executionContexts = new ExecutionContextRegistry();
+//# sourceMappingURL=executionContextRegistry.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"executionContextRegistry.js","sourceRoot":"","sources":["../../../../../lib/v3/understudy/executionContextRegistry.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Protocol } from \"devtools-protocol\";\nimport type { CDPSessionLike } from \"./cdp.js\";\n\ntype FrameId = Protocol.Page.FrameId;\ntype ExecId = Protocol.Runtime.ExecutionContextId;\n\nexport class ExecutionContextRegistry {\n  private readonly byFrame = new WeakMap<\n    CDPSessionLike,\n    Map<FrameId, ExecId>\n  >();\n  private readonly byExec = new WeakMap<CDPSessionLike, Map<ExecId, FrameId>>();\n\n  /** Wire listeners for this session. Call BEFORE Runtime.enable. */\n  attachSession(session: CDPSessionLike): void {\n    const onCreated = (\n      evt: Protocol.Runtime.ExecutionContextCreatedEvent,\n    ): void => {\n      const aux = (evt.context.auxData ?? {}) as {\n        frameId?: string;\n        isDefault?: boolean;\n      };\n      if (aux.isDefault === true && typeof aux.frameId === \"string\") {\n        this.register(session, aux.frameId as FrameId, evt.context.id);\n      }\n    };\n    const onDestroyed = (\n      evt: Protocol.Runtime.ExecutionContextDestroyedEvent,\n    ): void => {\n      const rev = this.byExec.get(session);\n      const fwd = this.byFrame.get(session);\n      if (!rev || !fwd) return;\n      const frameId = rev.get(evt.executionContextId);\n      if (!frameId) return;\n      rev.delete(evt.executionContextId);\n      if (fwd.get(frameId) === evt.executionContextId) fwd.delete(frameId);\n    };\n    const onCleared = (): void => {\n      this.byFrame.delete(session);\n      this.byExec.delete(session);\n    };\n\n    session.on(\"Runtime.executionContextCreated\", onCreated);\n    session.on(\"Runtime.executionContextDestroyed\", onDestroyed);\n    session.on(\"Runtime.executionContextsCleared\", onCleared);\n  }\n\n  getMainWorld(session: CDPSessionLike, frameId: FrameId): ExecId | null {\n    return this.byFrame.get(session)?.get(frameId) ?? null;\n  }\n\n  async waitForMainWorld(\n    session: CDPSessionLike,\n    frameId: FrameId,\n    timeoutMs: number = 800,\n  ): Promise<ExecId> {\n    const cached = this.getMainWorld(session, frameId);\n    if (cached) return cached;\n\n    await session.send(\"Runtime.enable\").catch(() => {});\n    const after = this.getMainWorld(session, frameId);\n    if (after) return after;\n\n    return await new Promise<ExecId>((resolve, reject) => {\n      let done = false;\n      const onCreated = (\n        evt: Protocol.Runtime.ExecutionContextCreatedEvent,\n      ): void => {\n        const aux = (evt.context.auxData ?? {}) as {\n          frameId?: string;\n          isDefault?: boolean;\n        };\n        if (aux.isDefault === true && aux.frameId === frameId) {\n          this.register(session, frameId, evt.context.id);\n          if (!done) {\n            done = true;\n            clearTimeout(timer);\n            session.off(\"Runtime.executionContextCreated\", onCreated);\n            resolve(evt.context.id);\n          }\n        }\n      };\n      const timer = setTimeout(() => {\n        if (!done) {\n          done = true;\n          session.off(\"Runtime.executionContextCreated\", onCreated);\n          reject(new Error(`main world not ready for frame ${frameId}`));\n        }\n      }, timeoutMs);\n      session.on(\"Runtime.executionContextCreated\", onCreated);\n    });\n  }\n\n  private register(\n    session: CDPSessionLike,\n    frameId: FrameId,\n    ctxId: ExecId,\n  ): void {\n    let fwd = this.byFrame.get(session);\n    if (!fwd) {\n      fwd = new Map<FrameId, ExecId>();\n      this.byFrame.set(session, fwd);\n    }\n    let rev = this.byExec.get(session);\n    if (!rev) {\n      rev = new Map<ExecId, FrameId>();\n      this.byExec.set(session, rev);\n    }\n    fwd.set(frameId, ctxId);\n    rev.set(ctxId, frameId);\n  }\n}\n\nexport const executionContexts = new ExecutionContextRegistry();\n"]}

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

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

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

@@ -0,0 +1,88 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeInputFiles = normalizeInputFiles;
+exports.toBuffer = toBuffer;
+const fs_1 = require("fs");
+const path_1 = __importDefault(require("path"));
+const buffer_1 = require("buffer");
+const sdkErrors_js_1 = require("../types/public/sdkErrors.js");
+const DEFAULT_MIME_TYPE = "application/octet-stream";
+/**
+ * Normalize user-provided setInputFiles arguments into in-memory payloads.
+ * - Resolves string paths relative to the provided base directory.
+ * - Validates that each path exists and is a regular file.
+ * - Converts all buffers into Node Buffers for downstream processing.
+ */
+async function normalizeInputFiles(files, opts = {}) {
+    if (files === null || files === undefined)
+        return [];
+    const flattened = Array.isArray(files)
+        ? files
+        : [files];
+    if (!flattened.length)
+        return [];
+    const baseDir = opts.baseDir ?? process.cwd();
+    const normalized = [];
+    for (const entry of flattened) {
+        if (typeof entry === "string") {
+            const absolutePath = path_1.default.isAbsolute(entry)
+                ? entry
+                : path_1.default.resolve(baseDir, entry);
+            const stat = await statFile(absolutePath);
+            if (!stat.isFile()) {
+                throw new sdkErrors_js_1.StagehandInvalidArgumentError(`setInputFiles(): expected a file but received directory or special entry at ${absolutePath}`);
+            }
+            const buffer = await fs_1.promises.readFile(absolutePath);
+            normalized.push({
+                name: path_1.default.basename(absolutePath) || "upload.bin",
+                mimeType: DEFAULT_MIME_TYPE,
+                buffer,
+                lastModified: stat.mtimeMs || Date.now(),
+                absolutePath,
+            });
+            continue;
+        }
+        if (entry && typeof entry === "object" && "buffer" in entry) {
+            const payload = entry;
+            const buffer = toBuffer(payload.buffer);
+            normalized.push({
+                name: payload.name || "upload.bin",
+                mimeType: payload.mimeType || DEFAULT_MIME_TYPE,
+                buffer,
+                lastModified: typeof payload.lastModified === "number"
+                    ? payload.lastModified
+                    : Date.now(),
+            });
+            continue;
+        }
+        throw new sdkErrors_js_1.StagehandInvalidArgumentError("setInputFiles(): expected file path(s) or payload object(s)");
+    }
+    return normalized;
+}
+async function statFile(absolutePath) {
+    try {
+        return await fs_1.promises.stat(absolutePath);
+    }
+    catch (error) {
+        const code = error?.code;
+        if (code === "ENOENT") {
+            throw new sdkErrors_js_1.StagehandInvalidArgumentError(`setInputFiles(): file not found at ${absolutePath}`);
+        }
+        throw error;
+    }
+}
+function toBuffer(data) {
+    if (buffer_1.Buffer.isBuffer(data))
+        return data;
+    if (data instanceof Uint8Array)
+        return buffer_1.Buffer.from(data);
+    if (typeof data === "string")
+        return buffer_1.Buffer.from(data);
+    if (data instanceof ArrayBuffer)
+        return buffer_1.Buffer.from(new Uint8Array(data));
+    throw new sdkErrors_js_1.StagehandInvalidArgumentError("Unsupported file payload buffer type");
+}
+//# sourceMappingURL=fileUploadUtils.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"fileUploadUtils.js","sourceRoot":"","sources":["../../../../../lib/v3/understudy/fileUploadUtils.ts"],"names":[],"mappings":";;;;;AAkBA,kDAyDC;AAgBD,4BAUC;AArGD,2BAAgD;AAChD,gDAAwB;AACxB,mCAAgC;AAChC,+DAA6E;AAO7E,MAAM,iBAAiB,GAAG,0BAA0B,CAAC;AAErD;;;;;GAKG;AACI,KAAK,UAAU,mBAAmB,CACvC,KAA4B,EAC5B,OAA6B,EAAE;IAE/B,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,EAAE,CAAC;IAErD,MAAM,SAAS,GAAG,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QACpC,CAAC,CAAE,KAA6C;QAChD,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;IACZ,IAAI,CAAC,SAAS,CAAC,MAAM;QAAE,OAAO,EAAE,CAAC;IAEjC,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;IAC9C,MAAM,UAAU,GAA4B,EAAE,CAAC;IAE/C,KAAK,MAAM,KAAK,IAAI,SAAS,EAAE,CAAC;QAC9B,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YAC9B,MAAM,YAAY,GAAG,cAAI,CAAC,UAAU,CAAC,KAAK,CAAC;gBACzC,CAAC,CAAC,KAAK;gBACP,CAAC,CAAC,cAAI,CAAC,OAAO,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;YACjC,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,YAAY,CAAC,CAAC;YAC1C,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,CAAC;gBACnB,MAAM,IAAI,4CAA6B,CACrC,+EAA+E,YAAY,EAAE,CAC9F,CAAC;YACJ,CAAC;YACD,MAAM,MAAM,GAAG,MAAM,aAAE,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC;YAC/C,UAAU,CAAC,IAAI,CAAC;gBACd,IAAI,EAAE,cAAI,CAAC,QAAQ,CAAC,YAAY,CAAC,IAAI,YAAY;gBACjD,QAAQ,EAAE,iBAAiB;gBAC3B,MAAM;gBACN,YAAY,EAAE,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC,GAAG,EAAE;gBACxC,YAAY;aACb,CAAC,CAAC;YACH,SAAS;QACX,CAAC;QAED,IAAI,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,QAAQ,IAAI,KAAK,EAAE,CAAC;YAC5D,MAAM,OAAO,GAAG,KAA4B,CAAC;YAC7C,MAAM,MAAM,GAAG,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;YACxC,UAAU,CAAC,IAAI,CAAC;gBACd,IAAI,EAAE,OAAO,CAAC,IAAI,IAAI,YAAY;gBAClC,QAAQ,EAAE,OAAO,CAAC,QAAQ,IAAI,iBAAiB;gBAC/C,MAAM;gBACN,YAAY,EACV,OAAO,OAAO,CAAC,YAAY,KAAK,QAAQ;oBACtC,CAAC,CAAC,OAAO,CAAC,YAAY;oBACtB,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE;aACjB,CAAC,CAAC;YACH,SAAS;QACX,CAAC;QAED,MAAM,IAAI,4CAA6B,CACrC,6DAA6D,CAC9D,CAAC;IACJ,CAAC;IAED,OAAO,UAAU,CAAC;AACpB,CAAC;AAED,KAAK,UAAU,QAAQ,CAAC,YAAoB;IAC1C,IAAI,CAAC;QACH,OAAO,MAAM,aAAE,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;IACrC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,GAAI,KAA+B,EAAE,IAAI,CAAC;QACpD,IAAI,IAAI,KAAK,QAAQ,EAAE,CAAC;YACtB,MAAM,IAAI,4CAA6B,CACrC,sCAAsC,YAAY,EAAE,CACrD,CAAC;QACJ,CAAC;QACD,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC;AAED,SAAgB,QAAQ,CACtB,IAAgD;IAEhD,IAAI,eAAM,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IACvC,IAAI,IAAI,YAAY,UAAU;QAAE,OAAO,eAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACzD,IAAI,OAAO,IAAI,KAAK,QAAQ;QAAE,OAAO,eAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACvD,IAAI,IAAI,YAAY,WAAW;QAAE,OAAO,eAAM,CAAC,IAAI,CAAC,IAAI,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC;IAC1E,MAAM,IAAI,4CAA6B,CACrC,sCAAsC,CACvC,CAAC;AACJ,CAAC","sourcesContent":["import { promises as fs, type Stats } from \"fs\";\nimport path from \"path\";\nimport { Buffer } from \"buffer\";\nimport { StagehandInvalidArgumentError } from \"../types/public/sdkErrors.js\";\nimport {\n  SetInputFilesArgument,\n  SetInputFilePayload,\n} from \"../types/public/locator.js\";\nimport { NormalizedFilePayload } from \"../types/private/locator.js\";\n\nconst DEFAULT_MIME_TYPE = \"application/octet-stream\";\n\n/**\n * Normalize user-provided setInputFiles arguments into in-memory payloads.\n * - Resolves string paths relative to the provided base directory.\n * - Validates that each path exists and is a regular file.\n * - Converts all buffers into Node Buffers for downstream processing.\n */\nexport async function normalizeInputFiles(\n  files: SetInputFilesArgument,\n  opts: { baseDir?: string } = {},\n): Promise<NormalizedFilePayload[]> {\n  if (files === null || files === undefined) return [];\n\n  const flattened = Array.isArray(files)\n    ? (files as Array<string | SetInputFilePayload>)\n    : [files];\n  if (!flattened.length) return [];\n\n  const baseDir = opts.baseDir ?? process.cwd();\n  const normalized: NormalizedFilePayload[] = [];\n\n  for (const entry of flattened) {\n    if (typeof entry === \"string\") {\n      const absolutePath = path.isAbsolute(entry)\n        ? entry\n        : path.resolve(baseDir, entry);\n      const stat = await statFile(absolutePath);\n      if (!stat.isFile()) {\n        throw new StagehandInvalidArgumentError(\n          `setInputFiles(): expected a file but received directory or special entry at ${absolutePath}`,\n        );\n      }\n      const buffer = await fs.readFile(absolutePath);\n      normalized.push({\n        name: path.basename(absolutePath) || \"upload.bin\",\n        mimeType: DEFAULT_MIME_TYPE,\n        buffer,\n        lastModified: stat.mtimeMs || Date.now(),\n        absolutePath,\n      });\n      continue;\n    }\n\n    if (entry && typeof entry === \"object\" && \"buffer\" in entry) {\n      const payload = entry as SetInputFilePayload;\n      const buffer = toBuffer(payload.buffer);\n      normalized.push({\n        name: payload.name || \"upload.bin\",\n        mimeType: payload.mimeType || DEFAULT_MIME_TYPE,\n        buffer,\n        lastModified:\n          typeof payload.lastModified === \"number\"\n            ? payload.lastModified\n            : Date.now(),\n      });\n      continue;\n    }\n\n    throw new StagehandInvalidArgumentError(\n      \"setInputFiles(): expected file path(s) or payload object(s)\",\n    );\n  }\n\n  return normalized;\n}\n\nasync function statFile(absolutePath: string): Promise<Stats> {\n  try {\n    return await fs.stat(absolutePath);\n  } catch (error) {\n    const code = (error as NodeJS.ErrnoException)?.code;\n    if (code === \"ENOENT\") {\n      throw new StagehandInvalidArgumentError(\n        `setInputFiles(): file not found at ${absolutePath}`,\n      );\n    }\n    throw error;\n  }\n}\n\nexport function toBuffer(\n  data: ArrayBuffer | Uint8Array | Buffer | string,\n): Buffer {\n  if (Buffer.isBuffer(data)) return data;\n  if (data instanceof Uint8Array) return Buffer.from(data);\n  if (typeof data === \"string\") return Buffer.from(data);\n  if (data instanceof ArrayBuffer) return Buffer.from(new Uint8Array(data));\n  throw new StagehandInvalidArgumentError(\n    \"Unsupported file payload buffer type\",\n  );\n}\n"]}

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

@@ -0,0 +1,69 @@
+import { Protocol } from "devtools-protocol";
+import type { CDPSessionLike } from "./cdp.js";
+import { Locator } from "./locator.js";
+interface FrameManager {
+    session: CDPSessionLike;
+    frameId: string;
+    pageId: string;
+}
+/**
+ * Frame
+ *
+ * A thin, session-bound handle to a specific DOM frame (by frameId).
+ * All CDP calls in this class go through `this.session`, which MUST be the
+ * owning session for `this.frameId`. Page is responsible for constructing
+ * Frames with the correct session.
+ */
+export declare class Frame implements FrameManager {
+    session: CDPSessionLike;
+    frameId: string;
+    pageId: string;
+    private readonly remoteBrowser;
+    /** Owning CDP session id (useful for logs); null for root connection (should not happen for targets) */
+    readonly sessionId: string | null;
+    constructor(session: CDPSessionLike, frameId: string, pageId: string, remoteBrowser: boolean);
+    /** True when the controlled browser runs on a different machine. */
+    isBrowserRemote(): boolean;
+    /** DOM.getNodeForLocation → DOM.describeNode */
+    getNodeAtLocation(x: number, y: number): Promise<Protocol.DOM.Node>;
+    /** CSS selector → DOM.querySelector → DOM.getBoxModel */
+    getLocationForSelector(selector: string): Promise<{
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }>;
+    /** Accessibility.getFullAXTree (+ recurse into child frames if requested) */
+    getAccessibilityTree(withFrames?: boolean): Promise<Protocol.Accessibility.AXNode[]>;
+    /**
+     * Evaluate a function or expression in this frame's main world.
+     * - If a string is provided, treated as a JS expression.
+     * - If a function is provided, it is stringified and invoked with the optional argument.
+     */
+    evaluate<R = unknown, Arg = unknown>(pageFunctionOrExpression: string | ((arg: Arg) => R | Promise<R>), arg?: Arg): Promise<R>;
+    /** Page.captureScreenshot (frame-scoped session) */
+    screenshot(options?: {
+        fullPage?: boolean;
+        clip?: {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        };
+        type?: "png" | "jpeg";
+        quality?: number;
+        scale?: number;
+    }): Promise<Buffer>;
+    /** Child frames via Page.getFrameTree */
+    childFrames(): Promise<Frame[]>;
+    /** Wait for a lifecycle state (load/domcontentloaded/networkidle) */
+    waitForLoadState(state?: "load" | "domcontentloaded" | "networkidle", timeoutMs?: number): Promise<void>;
+    /** Simple placeholder for your own locator abstraction */
+    locator(selector: string, options?: {
+        deep?: boolean;
+        depth?: number;
+    }): Locator;
+    /** Resolve the main-world execution context id for this frame. */
+    private getMainWorldExecutionContextId;
+}
+export {};