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

package/dist/cjs/lib/v3/understudy/a11y/snapshot/xpathUtils.js

@@ -0,0 +1,110 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildAbsoluteXPathFromChain = buildAbsoluteXPathFromChain;
+exports.absoluteXPathForBackendNode = absoluteXPathForBackendNode;
+exports.prefixXPath = prefixXPath;
+exports.normalizeXPath = normalizeXPath;
+exports.buildChildXPathSegments = buildChildXPathSegments;
+exports.joinXPath = joinXPath;
+const a11yScripts_generated_js_1 = require("../../../dom/build/a11yScripts.generated.js");
+/**
+ * Build the absolute XPath for a node by walking through every iframe host
+ * we've traversed so far followed by the leaf backend node.
+ */
+async function buildAbsoluteXPathFromChain(chain, leafSession, leafBackendNodeId) {
+    let prefix = "";
+    for (const step of chain) {
+        const xp = await absoluteXPathForBackendNode(step.parentSession, step.iframeBackendNodeId);
+        if (!xp)
+            continue;
+        prefix = prefix ? prefixXPath(prefix, xp) : normalizeXPath(xp);
+    }
+    const leaf = await absoluteXPathForBackendNode(leafSession, leafBackendNodeId);
+    if (!leaf)
+        return prefix || "/";
+    return prefix ? prefixXPath(prefix, leaf) : normalizeXPath(leaf);
+}
+/**
+ * Resolve a backend node to an absolute XPath within the provided session.
+ * The CDP Runtime is used so we can invoke a small helper that walks the DOM.
+ */
+async function absoluteXPathForBackendNode(session, backendNodeId) {
+    try {
+        const { object } = await session.send("DOM.resolveNode", { backendNodeId });
+        const objectId = object?.objectId;
+        if (!objectId)
+            return null;
+        const { result } = await session.send("Runtime.callFunctionOn", {
+            objectId,
+            functionDeclaration: a11yScripts_generated_js_1.a11yScriptSources.nodeToAbsoluteXPath,
+            returnByValue: true,
+        });
+        await session.send("Runtime.releaseObject", { objectId }).catch(() => { });
+        return typeof result?.value === "string" && result.value
+            ? result.value
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Prefix `child` XPath with an absolute iframe path `parentAbs`.
+ * Handles root slashes and shadow hops (“//”) cleanly.
+ */
+function prefixXPath(parentAbs, child) {
+    const p = parentAbs === "/" ? "" : parentAbs.replace(/\/$/, "");
+    if (!child || child === "/")
+        return p || "/";
+    if (child.startsWith("//"))
+        return p ? `${p}//${child.slice(2)}` : `//${child.slice(2)}`;
+    const c = child.replace(/^\//, "");
+    return p ? `${p}/${c}` : `/${c}`;
+}
+/** Normalize an XPath: strip `xpath=`, ensure leading '/', remove trailing '/'. */
+function normalizeXPath(x) {
+    if (!x)
+        return "";
+    let s = x.trim().replace(/^xpath=/i, "");
+    if (!s.startsWith("/"))
+        s = "/" + s;
+    if (s.length > 1 && s.endsWith("/"))
+        s = s.slice(0, -1);
+    return s;
+}
+/** Build per-sibling XPath steps for DOM traversal. */
+function buildChildXPathSegments(kids) {
+    const segs = [];
+    const ctr = {};
+    for (const child of kids) {
+        const tag = String(child.nodeName).toLowerCase();
+        const key = `${child.nodeType}:${tag}`;
+        const idx = (ctr[key] = (ctr[key] ?? 0) + 1);
+        if (child.nodeType === 3) {
+            segs.push(`text()[${idx}]`);
+        }
+        else if (child.nodeType === 8) {
+            segs.push(`comment()[${idx}]`);
+        }
+        else {
+            segs.push(tag.includes(":") ? `*[name()='${tag}'][${idx}]` : `${tag}[${idx}]`);
+        }
+    }
+    return segs;
+}
+/** Join two XPath fragments while preserving special shadow-root hops. */
+function joinXPath(base, step) {
+    if (step === "//") {
+        if (!base || base === "/")
+            return "//";
+        return base.endsWith("/") ? `${base}/` : `${base}//`;
+    }
+    if (!base || base === "/")
+        return step ? `/${step}` : "/";
+    if (base.endsWith("//"))
+        return `${base}${step}`;
+    if (!step)
+        return base;
+    return `${base}/${step}`;
+}
+//# sourceMappingURL=xpathUtils.js.map

package/dist/cjs/lib/v3/understudy/a11y/snapshot/xpathUtils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"xpathUtils.js","sourceRoot":"","sources":["../../../../../../../lib/v3/understudy/a11y/snapshot/xpathUtils.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Protocol } from \"devtools-protocol\";\nimport type { CDPSessionLike } from \"../../cdp.js\";\nimport { a11yScriptSources } from \"../../../dom/build/a11yScripts.generated.js\";\n\n/**\n * Build the absolute XPath for a node by walking through every iframe host\n * we've traversed so far followed by the leaf backend node.\n */\nexport async function buildAbsoluteXPathFromChain(\n  chain: Array<{\n    parentSession: CDPSessionLike;\n    iframeBackendNodeId: number;\n  }>,\n  leafSession: CDPSessionLike,\n  leafBackendNodeId: number,\n): Promise<string | null> {\n  let prefix = \"\";\n  for (const step of chain) {\n    const xp = await absoluteXPathForBackendNode(\n      step.parentSession,\n      step.iframeBackendNodeId,\n    );\n    if (!xp) continue;\n    prefix = prefix ? prefixXPath(prefix, xp) : normalizeXPath(xp);\n  }\n  const leaf = await absoluteXPathForBackendNode(\n    leafSession,\n    leafBackendNodeId,\n  );\n  if (!leaf) return prefix || \"/\";\n  return prefix ? prefixXPath(prefix, leaf) : normalizeXPath(leaf);\n}\n\n/**\n * Resolve a backend node to an absolute XPath within the provided session.\n * The CDP Runtime is used so we can invoke a small helper that walks the DOM.\n */\nexport async function absoluteXPathForBackendNode(\n  session: CDPSessionLike,\n  backendNodeId: number,\n): Promise<string | null> {\n  try {\n    const { object } = await session.send<{ object: { objectId?: string } }>(\n      \"DOM.resolveNode\",\n      { backendNodeId },\n    );\n    const objectId = object?.objectId;\n    if (!objectId) return null;\n\n    const { result } = await session.send<{ result: { value?: string } }>(\n      \"Runtime.callFunctionOn\",\n      {\n        objectId,\n        functionDeclaration: a11yScriptSources.nodeToAbsoluteXPath,\n        returnByValue: true,\n      },\n    );\n    await session.send(\"Runtime.releaseObject\", { objectId }).catch(() => {});\n    return typeof result?.value === \"string\" && result.value\n      ? result.value\n      : null;\n  } catch {\n    return null;\n  }\n}\n\n/**\n * Prefix `child` XPath with an absolute iframe path `parentAbs`.\n * Handles root slashes and shadow hops (“//”) cleanly.\n */\nexport function prefixXPath(parentAbs: string, child: string): string {\n  const p = parentAbs === \"/\" ? \"\" : parentAbs.replace(/\\/$/, \"\");\n  if (!child || child === \"/\") return p || \"/\";\n  if (child.startsWith(\"//\"))\n    return p ? `${p}//${child.slice(2)}` : `//${child.slice(2)}`;\n  const c = child.replace(/^\\//, \"\");\n  return p ? `${p}/${c}` : `/${c}`;\n}\n\n/** Normalize an XPath: strip `xpath=`, ensure leading '/', remove trailing '/'. */\nexport function normalizeXPath(x?: string): string {\n  if (!x) return \"\";\n  let s = x.trim().replace(/^xpath=/i, \"\");\n  if (!s.startsWith(\"/\")) s = \"/\" + s;\n  if (s.length > 1 && s.endsWith(\"/\")) s = s.slice(0, -1);\n  return s;\n}\n\n/** Build per-sibling XPath steps for DOM traversal. */\nexport function buildChildXPathSegments(kids: Protocol.DOM.Node[]): string[] {\n  const segs: string[] = [];\n  const ctr: Record<string, number> = {};\n  for (const child of kids) {\n    const tag = String(child.nodeName).toLowerCase();\n    const key = `${child.nodeType}:${tag}`;\n    const idx = (ctr[key] = (ctr[key] ?? 0) + 1);\n    if (child.nodeType === 3) {\n      segs.push(`text()[${idx}]`);\n    } else if (child.nodeType === 8) {\n      segs.push(`comment()[${idx}]`);\n    } else {\n      segs.push(\n        tag.includes(\":\") ? `*[name()='${tag}'][${idx}]` : `${tag}[${idx}]`,\n      );\n    }\n  }\n  return segs;\n}\n\n/** Join two XPath fragments while preserving special shadow-root hops. */\nexport function joinXPath(base: string, step: string): string {\n  if (step === \"//\") {\n    if (!base || base === \"/\") return \"//\";\n    return base.endsWith(\"/\") ? `${base}/` : `${base}//`;\n  }\n  if (!base || base === \"/\") return step ? `/${step}` : \"/\";\n  if (base.endsWith(\"//\")) return `${base}${step}`;\n  if (!step) return base;\n  return `${base}/${step}`;\n}\n"]}

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

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

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

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildA11yInvocation = buildA11yInvocation;
+const a11yScripts_generated_js_1 = require("../dom/build/a11yScripts.generated.js");
+/**
+ * Wrap a generated a11y script in a self-invoking expression that first ensures
+ * the bootstrap has run, then calls the requested helper via its global ref.
+ * This mirrors the locator resolver’s injection path so any CDP Runtime.evaluate
+ * can reuse the shared bundle without inlining JS strings.
+ */
+function buildA11yInvocation(name, args) {
+    const invocation = `${a11yScripts_generated_js_1.a11yScriptGlobalRefs[name]}(${args.join(", ")})`;
+    return `(() => { ${a11yScripts_generated_js_1.a11yScriptBootstrap}; return ${invocation}; })()`;
+}
+//# sourceMappingURL=a11yInvocation.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"a11yInvocation.js","sourceRoot":"","sources":["../../../../../lib/v3/understudy/a11yInvocation.ts"],"names":[],"mappings":";;AAYA,kDAMC;AAlBD,oFAI+C;AAE/C;;;;;GAKG;AACH,SAAgB,mBAAmB,CACjC,IAAoB,EACpB,IAAc;IAEd,MAAM,UAAU,GAAG,GAAG,+CAAoB,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC;IACvE,OAAO,YAAY,8CAAmB,YAAY,UAAU,QAAQ,CAAC;AACvE,CAAC","sourcesContent":["import {\n  a11yScriptBootstrap,\n  a11yScriptGlobalRefs,\n  type A11yScriptName,\n} from \"../dom/build/a11yScripts.generated.js\";\n\n/**\n * Wrap a generated a11y script in a self-invoking expression that first ensures\n * the bootstrap has run, then calls the requested helper via its global ref.\n * This mirrors the locator resolver’s injection path so any CDP Runtime.evaluate\n * can reuse the shared bundle without inlining JS strings.\n */\nexport function buildA11yInvocation(\n  name: A11yScriptName,\n  args: string[],\n): string {\n  const invocation = `${a11yScriptGlobalRefs[name]}(${args.join(\", \")})`;\n  return `(() => { ${a11yScriptBootstrap}; return ${invocation}; })()`;\n}\n"]}

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

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

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

@@ -0,0 +1,317 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CdpSession = exports.CdpConnection = void 0;
+// lib/v3/understudy/cdp.ts
+const ws_1 = __importDefault(require("ws"));
+const version_js_1 = require("../../version.js");
+const sdkErrors_js_1 = require("../types/public/sdkErrors.js");
+class CdpConnection {
+    ws;
+    nextId = 1;
+    inflight = new Map();
+    eventHandlers = new Map();
+    sessions = new Map();
+    /** Maps sessionId -> targetId (1:1 mapping) */
+    sessionToTarget = new Map();
+    sessionDispatchWaiters = new Set();
+    id = null; // root
+    transportCloseHandlers = new Set();
+    /** Optional CDP logger - set this to receive all outgoing CDP method calls */
+    cdpLogger;
+    /** Optional CDP event logger - set this to receive all incoming CDP events */
+    cdpEventLogger;
+    onTransportClosed(handler) {
+        this.transportCloseHandlers.add(handler);
+    }
+    offTransportClosed(handler) {
+        this.transportCloseHandlers.delete(handler);
+    }
+    emitTransportClosed(why) {
+        for (const h of this.transportCloseHandlers) {
+            try {
+                h(why);
+            }
+            catch {
+                //
+            }
+        }
+    }
+    constructor(ws) {
+        this.ws = ws;
+        this.ws.on("close", (code, reason) => {
+            // Reason is a Buffer in ws; stringify defensively
+            const why = `socket-close code=${code} reason=${String(reason || "")}`;
+            this.rejectAllInflight(why);
+            this.emitTransportClosed(why);
+        });
+        this.ws.on("error", (err) => {
+            const why = `socket-error ${err?.message ?? String(err)}`;
+            this.rejectAllInflight(why);
+            this.emitTransportClosed(why);
+        });
+        this.ws.on("message", (data) => this.onMessage(data.toString()));
+    }
+    static async connect(wsUrl, options) {
+        // Include User-Agent header for server-side observability and version tracking
+        // Merge user-provided headers, letting them override defaults
+        const headers = {
+            "User-Agent": `Stagehand/${version_js_1.STAGEHAND_VERSION}`,
+            ...options?.headers,
+        };
+        const ws = new ws_1.default(wsUrl, { headers });
+        await new Promise((resolve, reject) => {
+            ws.once("open", () => resolve());
+            ws.once("error", (e) => reject(e));
+        });
+        return new CdpConnection(ws);
+    }
+    async enableAutoAttach() {
+        await this.send("Target.setAutoAttach", {
+            autoAttach: true,
+            flatten: true,
+            waitForDebuggerOnStart: true,
+        });
+        await this.send("Target.setDiscoverTargets", { discover: true });
+    }
+    async send(method, params) {
+        const id = this.nextId++;
+        const payload = { id, method, params };
+        const stack = new Error().stack?.split("\n").slice(1, 4).join("\n");
+        const p = new Promise((resolve, reject) => {
+            this.inflight.set(id, {
+                resolve,
+                reject,
+                sessionId: null,
+                method,
+                params,
+                stack,
+                ts: Date.now(),
+            });
+        });
+        // Prevent unhandledRejection if a session detaches before the caller awaits.
+        void p.catch(() => { });
+        this.cdpLogger?.({ method, params, targetId: null });
+        this.ws.send(JSON.stringify(payload));
+        return p;
+    }
+    on(event, handler) {
+        const set = this.eventHandlers.get(event) ?? new Set();
+        set.add(handler);
+        this.eventHandlers.set(event, set);
+    }
+    off(event, handler) {
+        const set = this.eventHandlers.get(event);
+        if (set)
+            set.delete(handler);
+    }
+    async close() {
+        if (this.ws.readyState === ws_1.default.CLOSED)
+            return;
+        await new Promise((resolve) => {
+            this.ws.once("close", () => resolve());
+            this.ws.close();
+        });
+    }
+    rejectAllInflight(why) {
+        for (const [id, entry] of this.inflight.entries()) {
+            entry.reject(new sdkErrors_js_1.CdpConnectionClosedError(why));
+            this.inflight.delete(id);
+        }
+        for (const waiter of Array.from(this.sessionDispatchWaiters)) {
+            waiter.reject(new sdkErrors_js_1.CdpConnectionClosedError(why));
+        }
+    }
+    getSession(sessionId) {
+        return this.sessions.get(sessionId);
+    }
+    waitForSessionDispatch(sessionId, method, match) {
+        return new Promise((resolve, reject) => {
+            const waiter = {
+                sessionId,
+                method,
+                match,
+                resolve: () => {
+                    this.sessionDispatchWaiters.delete(waiter);
+                    resolve();
+                },
+                reject: (error) => {
+                    this.sessionDispatchWaiters.delete(waiter);
+                    reject(error);
+                },
+            };
+            this.sessionDispatchWaiters.add(waiter);
+        });
+    }
+    async attachToTarget(targetId) {
+        const { sessionId } = (await this.send("Target.attachToTarget", { targetId, flatten: true }));
+        let session = this.sessions.get(sessionId);
+        if (!session) {
+            session = new CdpSession(this, sessionId);
+            this.sessions.set(sessionId, session);
+        }
+        this.sessionToTarget.set(sessionId, targetId);
+        return session;
+    }
+    async getTargets() {
+        const res = await this.send("Target.getTargets");
+        return res.targetInfos;
+    }
+    onMessage(json) {
+        const msg = JSON.parse(json);
+        if ("id" in msg) {
+            const rec = this.inflight.get(msg.id);
+            if (!rec)
+                return;
+            this.inflight.delete(msg.id);
+            if ("error" in msg && msg.error) {
+                rec.reject(new Error(`${msg.error.code} ${msg.error.message}`));
+            }
+            else {
+                rec.resolve(msg.result);
+            }
+            return;
+        }
+        if ("method" in msg) {
+            if (msg.method === "Target.attachedToTarget") {
+                const p = msg
+                    .params;
+                if (!this.sessions.has(p.sessionId)) {
+                    this.sessions.set(p.sessionId, new CdpSession(this, p.sessionId));
+                }
+                this.sessionToTarget.set(p.sessionId, p.targetInfo.targetId);
+            }
+            else if (msg.method === "Target.detachedFromTarget") {
+                const p = msg
+                    .params;
+                for (const [id, entry] of this.inflight.entries()) {
+                    if (entry.sessionId === p.sessionId) {
+                        entry.reject(new sdkErrors_js_1.PageNotFoundError(`target closed before CDP response (sessionId=${p.sessionId}, targetId=${p.targetId})`));
+                        this.inflight.delete(id);
+                    }
+                }
+                for (const waiter of Array.from(this.sessionDispatchWaiters)) {
+                    if (waiter.sessionId === p.sessionId) {
+                        waiter.reject(new sdkErrors_js_1.PageNotFoundError(`target closed before CDP send (sessionId=${p.sessionId}, targetId=${p.targetId})`));
+                    }
+                }
+                this.sessions.delete(p.sessionId);
+                this.sessionToTarget.delete(p.sessionId);
+            }
+            else if (msg.method === "Target.targetDestroyed") {
+                const p = msg.params;
+                // Remove any session mapping for this target
+                for (const [sessionId, targetId] of this.sessionToTarget.entries()) {
+                    if (targetId === p.targetId) {
+                        this.sessionToTarget.delete(sessionId);
+                        break;
+                    }
+                }
+            }
+            const { method, params, sessionId } = msg;
+            // Log incoming CDP events
+            const targetId = this.sessionToTarget.get(sessionId) || sessionId;
+            this.cdpEventLogger?.({ method, params, targetId });
+            if (sessionId) {
+                const session = this.sessions.get(sessionId);
+                session?.dispatch(method, params);
+                // Forward target lifecycle events to root listeners as well.
+                // Some browsers emit these via a parent session rather than the root
+                // connection; fan-out keeps target tracking consistent.
+                if (method.startsWith("Target.")) {
+                    const handlers = this.eventHandlers.get(method);
+                    if (handlers)
+                        for (const h of handlers)
+                            h(params);
+                }
+            }
+            else {
+                const handlers = this.eventHandlers.get(method);
+                if (handlers)
+                    for (const h of handlers)
+                        h(params);
+            }
+        }
+    }
+    _sendViaSession(sessionId, method, params) {
+        const id = this.nextId++;
+        const payload = { id, method, params, sessionId };
+        const stack = new Error().stack?.split("\n").slice(1, 4).join("\n");
+        const p = new Promise((resolve, reject) => {
+            this.inflight.set(id, {
+                resolve,
+                reject,
+                sessionId,
+                method,
+                params,
+                stack,
+                ts: Date.now(),
+            });
+        });
+        // Prevent unhandledRejection if a session detaches before the caller awaits.
+        void p.catch(() => { });
+        const targetId = this.sessionToTarget.get(sessionId) ?? null;
+        this.cdpLogger?.({ method, params, targetId });
+        for (const waiter of Array.from(this.sessionDispatchWaiters)) {
+            if (waiter.sessionId !== sessionId)
+                continue;
+            if (waiter.method !== method)
+                continue;
+            if (waiter.match && !waiter.match(params))
+                continue;
+            waiter.resolve();
+            break;
+        }
+        this.ws.send(JSON.stringify(payload));
+        return p;
+    }
+    _onSessionEvent(sessionId, event, handler) {
+        const key = `${sessionId}:${event}`;
+        const set = this.eventHandlers.get(key) ?? new Set();
+        set.add(handler);
+        this.eventHandlers.set(key, set);
+    }
+    _offSessionEvent(sessionId, event, handler) {
+        const key = `${sessionId}:${event}`;
+        const set = this.eventHandlers.get(key);
+        if (set)
+            set.delete(handler);
+    }
+    _dispatchToSession(sessionId, event, params) {
+        const key = `${sessionId}:${event}`;
+        const handlers = this.eventHandlers.get(key);
+        if (handlers)
+            for (const h of handlers)
+                h(params);
+    }
+}
+exports.CdpConnection = CdpConnection;
+class CdpSession {
+    root;
+    id;
+    constructor(root, id) {
+        this.root = root;
+        this.id = id;
+    }
+    send(method, params) {
+        return this.root._sendViaSession(this.id, method, params);
+    }
+    on(event, handler) {
+        this.root._onSessionEvent(this.id, event, handler);
+    }
+    off(event, handler) {
+        this.root._offSessionEvent(this.id, event, handler);
+    }
+    async close() {
+        await this.root.send("Target.detachFromTarget", {
+            sessionId: this.id,
+        });
+    }
+    dispatch(event, params) {
+        this.root._dispatchToSession(this.id, event, params);
+    }
+}
+exports.CdpSession = CdpSession;
+//# sourceMappingURL=cdp.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cdp.js","sourceRoot":"","sources":["../../../../../lib/v3/understudy/cdp.ts"],"names":[],"mappings":"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","sourcesContent":["// lib/v3/understudy/cdp.ts\nimport WebSocket from \"ws\";\nimport type { Protocol } from \"devtools-protocol\";\nimport { STAGEHAND_VERSION } from \"../../version.js\";\nimport {\n  CdpConnectionClosedError,\n  PageNotFoundError,\n} from \"../types/public/sdkErrors.js\";\n\n/**\n * CDP transport & session multiplexer\n *\n * Owns the browser WebSocket and multiplexes flattened Target sessions.\n * Tracks inflight CDP calls, routes responses to the right session, and forwards events.\n *\n * This does not interpret Page/DOM/Runtime semantics — callers own that logic.\n */\nexport interface CDPSessionLike {\n  send<R = unknown>(method: string, params?: object): Promise<R>;\n  on<P = unknown>(event: string, handler: (params: P) => void): void;\n  off<P = unknown>(event: string, handler: (params: P) => void): void;\n  close(): Promise<void>;\n  readonly id: string | null;\n}\n\ntype Inflight = {\n  resolve: (v: unknown) => void;\n  reject: (e: Error) => void;\n  sessionId?: string | null;\n  method: string;\n  params?: object;\n  stack?: string;\n  ts: number;\n};\n\ntype EventHandler = (params: unknown) => void;\ntype SessionDispatchWaiter = {\n  sessionId: string;\n  method: string;\n  match?: (params?: object) => boolean;\n  resolve: () => void;\n  reject: (error: Error) => void;\n};\n\ntype RawMessage =\n  | {\n      id: number;\n      result?: unknown;\n      error?: { code: number; message: string; data?: unknown };\n      sessionId?: string;\n    }\n  | { method: string; params?: unknown; sessionId?: string };\n\nexport class CdpConnection implements CDPSessionLike {\n  private ws: WebSocket;\n  private nextId = 1;\n  private inflight = new Map<number, Inflight>();\n  private eventHandlers = new Map<string, Set<EventHandler>>();\n  private sessions = new Map<string, CdpSession>();\n  /** Maps sessionId -> targetId (1:1 mapping) */\n  private sessionToTarget = new Map<string, string>();\n  private sessionDispatchWaiters = new Set<SessionDispatchWaiter>();\n  public readonly id: string | null = null; // root\n  private transportCloseHandlers = new Set<(why: string) => void>();\n\n  /** Optional CDP logger - set this to receive all outgoing CDP method calls */\n  public cdpLogger?: (info: {\n    method: string;\n    params?: object;\n    targetId?: string | null;\n  }) => void;\n\n  /** Optional CDP event logger - set this to receive all incoming CDP events */\n  public cdpEventLogger?: (info: {\n    method: string;\n    params?: unknown;\n    targetId?: string | null;\n  }) => void;\n\n  public onTransportClosed(handler: (why: string) => void): void {\n    this.transportCloseHandlers.add(handler);\n  }\n  public offTransportClosed(handler: (why: string) => void): void {\n    this.transportCloseHandlers.delete(handler);\n  }\n\n  private emitTransportClosed(why: string) {\n    for (const h of this.transportCloseHandlers) {\n      try {\n        h(why);\n      } catch {\n        //\n      }\n    }\n  }\n\n  private constructor(ws: WebSocket) {\n    this.ws = ws;\n    this.ws.on(\"close\", (code, reason) => {\n      // Reason is a Buffer in ws; stringify defensively\n      const why = `socket-close code=${code} reason=${String(reason || \"\")}`;\n      this.rejectAllInflight(why);\n      this.emitTransportClosed(why);\n    });\n\n    this.ws.on(\"error\", (err) => {\n      const why = `socket-error ${err?.message ?? String(err)}`;\n      this.rejectAllInflight(why);\n      this.emitTransportClosed(why);\n    });\n    this.ws.on(\"message\", (data) => this.onMessage(data.toString()));\n  }\n\n  static async connect(\n    wsUrl: string,\n    options?: { headers?: Record<string, string> },\n  ): Promise<CdpConnection> {\n    // Include User-Agent header for server-side observability and version tracking\n    // Merge user-provided headers, letting them override defaults\n    const headers = {\n      \"User-Agent\": `Stagehand/${STAGEHAND_VERSION}`,\n      ...options?.headers,\n    };\n    const ws = new WebSocket(wsUrl, { headers });\n    await new Promise<void>((resolve, reject) => {\n      ws.once(\"open\", () => resolve());\n      ws.once(\"error\", (e) => reject(e));\n    });\n    return new CdpConnection(ws);\n  }\n\n  async enableAutoAttach(): Promise<void> {\n    await this.send(\"Target.setAutoAttach\", {\n      autoAttach: true,\n      flatten: true,\n      waitForDebuggerOnStart: true,\n    });\n    await this.send(\"Target.setDiscoverTargets\", { discover: true });\n  }\n\n  async send<R = unknown>(method: string, params?: object): Promise<R> {\n    const id = this.nextId++;\n    const payload = { id, method, params };\n    const stack = new Error().stack?.split(\"\\n\").slice(1, 4).join(\"\\n\");\n    const p = new Promise<R>((resolve, reject) => {\n      this.inflight.set(id, {\n        resolve,\n        reject,\n        sessionId: null,\n        method,\n        params,\n        stack,\n        ts: Date.now(),\n      });\n    });\n    // Prevent unhandledRejection if a session detaches before the caller awaits.\n    void p.catch(() => {});\n    this.cdpLogger?.({ method, params, targetId: null });\n    this.ws.send(JSON.stringify(payload));\n    return p;\n  }\n\n  on<P = unknown>(event: string, handler: (params: P) => void): void {\n    const set = this.eventHandlers.get(event) ?? new Set<EventHandler>();\n    set.add(handler as EventHandler);\n    this.eventHandlers.set(event, set);\n  }\n\n  off<P = unknown>(event: string, handler: (params: P) => void): void {\n    const set = this.eventHandlers.get(event);\n    if (set) set.delete(handler as EventHandler);\n  }\n\n  async close(): Promise<void> {\n    if (this.ws.readyState === WebSocket.CLOSED) return;\n    await new Promise<void>((resolve) => {\n      this.ws.once(\"close\", () => resolve());\n      this.ws.close();\n    });\n  }\n\n  private rejectAllInflight(why: string): void {\n    for (const [id, entry] of this.inflight.entries()) {\n      entry.reject(new CdpConnectionClosedError(why));\n      this.inflight.delete(id);\n    }\n    for (const waiter of Array.from(this.sessionDispatchWaiters)) {\n      waiter.reject(new CdpConnectionClosedError(why));\n    }\n  }\n\n  getSession(sessionId: string): CdpSession | undefined {\n    return this.sessions.get(sessionId);\n  }\n\n  waitForSessionDispatch(\n    sessionId: string,\n    method: string,\n    match?: (params?: object) => boolean,\n  ): Promise<void> {\n    return new Promise<void>((resolve, reject) => {\n      const waiter: SessionDispatchWaiter = {\n        sessionId,\n        method,\n        match,\n        resolve: () => {\n          this.sessionDispatchWaiters.delete(waiter);\n          resolve();\n        },\n        reject: (error: Error) => {\n          this.sessionDispatchWaiters.delete(waiter);\n          reject(error);\n        },\n      };\n      this.sessionDispatchWaiters.add(waiter);\n    });\n  }\n\n  async attachToTarget(targetId: string): Promise<CdpSession> {\n    const { sessionId } = (await this.send<{ sessionId: string }>(\n      \"Target.attachToTarget\",\n      { targetId, flatten: true },\n    )) as { sessionId: string };\n\n    let session = this.sessions.get(sessionId);\n    if (!session) {\n      session = new CdpSession(this, sessionId);\n      this.sessions.set(sessionId, session);\n    }\n    this.sessionToTarget.set(sessionId, targetId);\n    return session;\n  }\n\n  async getTargets(): Promise<Protocol.Target.TargetInfo[]> {\n    const res = await this.send<{\n      targetInfos: Protocol.Target.TargetInfo[];\n    }>(\"Target.getTargets\");\n    return res.targetInfos;\n  }\n\n  private onMessage(json: string): void {\n    const msg = JSON.parse(json) as RawMessage;\n\n    if (\"id\" in msg) {\n      const rec = this.inflight.get(msg.id);\n      if (!rec) return;\n\n      this.inflight.delete(msg.id);\n\n      if (\"error\" in msg && msg.error) {\n        rec.reject(new Error(`${msg.error.code} ${msg.error.message}`));\n      } else {\n        rec.resolve((msg as { result?: unknown }).result);\n      }\n      return;\n    }\n\n    if (\"method\" in msg) {\n      if (msg.method === \"Target.attachedToTarget\") {\n        const p = (msg as { params: Protocol.Target.AttachedToTargetEvent })\n          .params;\n        if (!this.sessions.has(p.sessionId)) {\n          this.sessions.set(p.sessionId, new CdpSession(this, p.sessionId));\n        }\n        this.sessionToTarget.set(p.sessionId, p.targetInfo.targetId);\n      } else if (msg.method === \"Target.detachedFromTarget\") {\n        const p = (msg as { params: Protocol.Target.DetachedFromTargetEvent })\n          .params;\n        for (const [id, entry] of this.inflight.entries()) {\n          if (entry.sessionId === p.sessionId) {\n            entry.reject(\n              new PageNotFoundError(\n                `target closed before CDP response (sessionId=${p.sessionId}, targetId=${p.targetId})`,\n              ),\n            );\n            this.inflight.delete(id);\n          }\n        }\n        for (const waiter of Array.from(this.sessionDispatchWaiters)) {\n          if (waiter.sessionId === p.sessionId) {\n            waiter.reject(\n              new PageNotFoundError(\n                `target closed before CDP send (sessionId=${p.sessionId}, targetId=${p.targetId})`,\n              ),\n            );\n          }\n        }\n        this.sessions.delete(p.sessionId);\n        this.sessionToTarget.delete(p.sessionId);\n      } else if (msg.method === \"Target.targetDestroyed\") {\n        const p = (msg as { params: { targetId: string } }).params;\n        // Remove any session mapping for this target\n        for (const [sessionId, targetId] of this.sessionToTarget.entries()) {\n          if (targetId === p.targetId) {\n            this.sessionToTarget.delete(sessionId);\n            break;\n          }\n        }\n      }\n\n      const { method, params, sessionId } = msg;\n\n      // Log incoming CDP events\n      const targetId = this.sessionToTarget.get(sessionId) || sessionId;\n      this.cdpEventLogger?.({ method, params, targetId });\n\n      if (sessionId) {\n        const session = this.sessions.get(sessionId);\n        session?.dispatch(method, params);\n\n        // Forward target lifecycle events to root listeners as well.\n        // Some browsers emit these via a parent session rather than the root\n        // connection; fan-out keeps target tracking consistent.\n        if (method.startsWith(\"Target.\")) {\n          const handlers = this.eventHandlers.get(method);\n          if (handlers) for (const h of handlers) h(params);\n        }\n      } else {\n        const handlers = this.eventHandlers.get(method);\n        if (handlers) for (const h of handlers) h(params);\n      }\n    }\n  }\n\n  _sendViaSession<R = unknown>(\n    sessionId: string,\n    method: string,\n    params?: object,\n  ): Promise<R> {\n    const id = this.nextId++;\n    const payload = { id, method, params, sessionId };\n    const stack = new Error().stack?.split(\"\\n\").slice(1, 4).join(\"\\n\");\n\n    const p = new Promise<R>((resolve, reject) => {\n      this.inflight.set(id, {\n        resolve,\n        reject,\n        sessionId,\n        method,\n        params,\n        stack,\n        ts: Date.now(),\n      });\n    });\n    // Prevent unhandledRejection if a session detaches before the caller awaits.\n    void p.catch(() => {});\n    const targetId = this.sessionToTarget.get(sessionId) ?? null;\n    this.cdpLogger?.({ method, params, targetId });\n    for (const waiter of Array.from(this.sessionDispatchWaiters)) {\n      if (waiter.sessionId !== sessionId) continue;\n      if (waiter.method !== method) continue;\n      if (waiter.match && !waiter.match(params)) continue;\n      waiter.resolve();\n      break;\n    }\n    this.ws.send(JSON.stringify(payload));\n    return p;\n  }\n\n  _onSessionEvent(\n    sessionId: string,\n    event: string,\n    handler: EventHandler,\n  ): void {\n    const key = `${sessionId}:${event}`;\n    const set = this.eventHandlers.get(key) ?? new Set<EventHandler>();\n    set.add(handler);\n    this.eventHandlers.set(key, set);\n  }\n\n  _offSessionEvent(\n    sessionId: string,\n    event: string,\n    handler: EventHandler,\n  ): void {\n    const key = `${sessionId}:${event}`;\n    const set = this.eventHandlers.get(key);\n    if (set) set.delete(handler);\n  }\n\n  _dispatchToSession(sessionId: string, event: string, params: unknown): void {\n    const key = `${sessionId}:${event}`;\n    const handlers = this.eventHandlers.get(key);\n    if (handlers) for (const h of handlers) h(params);\n  }\n}\n\nexport class CdpSession implements CDPSessionLike {\n  constructor(\n    private readonly root: CdpConnection,\n    public readonly id: string,\n  ) {}\n\n  send<R = unknown>(method: string, params?: object): Promise<R> {\n    return this.root._sendViaSession<R>(this.id, method, params);\n  }\n\n  on<P = unknown>(event: string, handler: (params: P) => void): void {\n    this.root._onSessionEvent(this.id, event, handler as EventHandler);\n  }\n\n  off<P = unknown>(event: string, handler: (params: P) => void): void {\n    this.root._offSessionEvent(this.id, event, handler as EventHandler);\n  }\n\n  async close(): Promise<void> {\n    await this.root.send<void>(\"Target.detachFromTarget\", {\n      sessionId: this.id,\n    });\n  }\n\n  dispatch(event: string, params: unknown): void {\n    this.root._dispatchToSession(this.id, event, params);\n  }\n}\n"]}

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

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