@browserbasehq/orca 3.1.0-patch.3 → 3.2.0-preview.1

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

@@ -54,7 +54,7 @@ export class Frame {
     /** Accessibility.getFullAXTree (+ recurse into child frames if requested) */
     async getAccessibilityTree(withFrames = false) {
         await this.session.send("Accessibility.enable");
-        let nodes = [];
+        let nodes;
         try {
             ({ nodes } = await this.session.send("Accessibility.getFullAXTree", { frameId: this.frameId }));
         }
@@ -104,12 +104,29 @@ export class Frame {
         } catch (e) { throw e; }
       })()`;
         }
-        const res = await this.session.send("Runtime.evaluate", {
-            expression,
-            contextId,
-            awaitPromise: true,
-            returnByValue: true,
-        });
+        let res;
+        try {
+            res = await this.session.send("Runtime.evaluate", {
+                expression,
+                contextId,
+                awaitPromise: true,
+                returnByValue: true,
+            });
+        }
+        catch (error) {
+            // Execution contexts can be recreated between context lookup and
+            // Runtime.evaluate during popup/navigate churn. Retry once with a fresh id.
+            const msg = error instanceof Error ? error.message : String(error);
+            if (!msg.includes("Cannot find context with specified id"))
+                throw error;
+            const freshContextId = await this.getMainWorldExecutionContextId();
+            res = await this.session.send("Runtime.evaluate", {
+                expression,
+                contextId: freshContextId,
+                awaitPromise: true,
+                returnByValue: true,
+            });
+        }
         if (res.exceptionDetails) {
             throw new StagehandEvalError(res.exceptionDetails.text ?? "Evaluation failed");
         }

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

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

package/dist/esm/lib/v3/understudy/page.d.ts

@@ -39,6 +39,7 @@ export declare class Page {
     private readonly consoleHandlers;
     /** Document-start scripts installed across every session this page owns. */
     private readonly initScripts;
+    private extraHTTPHeaders;
     private constructor();
     private installInitScriptOnSession;
     private applyInitScriptsToSession;
@@ -118,6 +119,7 @@ export declare class Page {
     close(): Promise<void>;
     getFullFrameTree(): Protocol.Page.FrameTree;
     asProtocolFrameTree(rootMainFrameId: string): Protocol.Page.FrameTree;
+    private applyExtraHTTPHeadersToSession;
     private ensureOrdinal;
     /** Public getter for snapshot code / handlers. */
     getOrdinal(frameId: string): number;
@@ -202,6 +204,17 @@ export declare class Page {
      * @param options.type Image format (`"png"` by default).
      */
     screenshot(options?: ScreenshotOptions): Promise<Buffer>;
+    /**
+     * specifies additional HTTP headers to be included in every request sent by
+     * the root CDP session of the page, and all of its child CDP sessions.
+     *
+     * @param headers - the headers to be set.
+     * @throws {StagehandSetExtraHTTPHeadersError}
+     * Thrown when one or more CDP sessions fail to enable the Network domain or fail
+     * to apply the headers (i.e. `Network.enable` and/or `Network.setExtraHTTPHeaders` rejects).
+     * @return void
+     */
+    setExtraHTTPHeaders(headers: Record<string, string>): Promise<void>;
     /**
      * Create a locator bound to the current main frame.
      */

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

@@ -46,11 +46,12 @@ import { LifecycleWatcher } from "./lifecycleWatcher.js";
 import { NavigationResponseTracker } from "./navigationResponseTracker.js";
 import { Response, isSerializableResponse } from "./response.js";
 import { ConsoleMessage } from "./consoleMessage.js";
-import { StagehandSnapshotError, } from "../types/public/index.js";
+import { StagehandSetExtraHTTPHeadersError, StagehandSnapshotError, } from "../types/public/index.js";
 import { StagehandInvalidArgumentError, StagehandEvalError, } from "../types/public/sdkErrors.js";
 import { normalizeInitScriptSource } from "./initScripts.js";
 import { buildLocatorInvocation } from "./locatorInvocation.js";
-import { applyMaskOverlays, applyStyleToFrames, collectFramesForScreenshot, computeScreenshotScale, disableAnimations, hideCaret, normalizeScreenshotClip, runScreenshotCleanups, setTransparentBackground, withScreenshotTimeout, } from "./screenshotUtils.js";
+import { applyMaskOverlays, applyStyleToFrames, collectFramesForScreenshot, computeScreenshotScale, disableAnimations, hideCaret, normalizeScreenshotClip, runScreenshotCleanups, setTransparentBackground, } from "./screenshotUtils.js";
+import { withTimeout } from "../timeoutConfig.js";
 /**
  * Page
  *
@@ -152,6 +153,7 @@ let Page = (() => {
         consoleHandlers = new Map();
         /** Document-start scripts installed across every session this page owns. */
         initScripts = [];
+        extraHTTPHeaders;
         constructor(conn, mainSession, _targetId, mainFrameId, apiClient, browserIsRemote = false) {
             this.conn = conn;
             this.mainSession = mainSession;
@@ -305,8 +307,12 @@ let Page = (() => {
          * Assumes Page domain is already enabled on the session passed in.
          */
         static async create(conn, session, targetId, apiClient, localBrowserLaunchOptions, browserIsRemote = false) {
-            await session.send("Page.enable").catch(() => { });
-            await session
+            // Context already issues Page.enable + lifecycle enable before resume.
+            // Re-issue here only as best-effort and do not block page registration on
+            // their acknowledgements; some remote CDP backends can delay these replies
+            // long after the target is otherwise ready.
+            void session.send("Page.enable").catch(() => { });
+            void session
                 .send("Page.setLifecycleEventsEnabled", { enabled: true })
                 .catch(() => { });
             const { frameTree } = await session.send("Page.getFrameTree");
@@ -390,6 +396,8 @@ let Page = (() => {
             if (childSession.id)
                 this.sessions.set(childSession.id, childSession);
             this.networkManager.trackSession(childSession);
+            if (this.extraHTTPHeaders)
+                void this.applyExtraHTTPHeadersToSession(childSession, this.extraHTTPHeaders).catch(() => { });
             void this.applyInitScriptsToSession(childSession).catch(() => { });
             if (this.consoleListeners.size > 0) {
                 this.installConsoleTap(childSession);
@@ -576,6 +584,12 @@ let Page = (() => {
         asProtocolFrameTree(rootMainFrameId) {
             return this.registry.asProtocolFrameTree(rootMainFrameId);
         }
+        async applyExtraHTTPHeadersToSession(session, headers) {
+            await session.send("Network.enable");
+            await session.send("Network.setExtraHTTPHeaders", {
+                headers: headers,
+            });
+        }
         ensureOrdinal(frameId) {
             const hit = this.frameOrdinals.get(frameId);
             if (hit !== undefined)
@@ -952,7 +966,46 @@ let Page = (() => {
                     await runScreenshotCleanups(cleanupTasks);
                 }
             };
-            return withScreenshotTimeout(opts.timeout, exec);
+            return await withTimeout(exec(), opts.timeout, "screenshot");
+        }
+        /**
+         * specifies additional HTTP headers to be included in every request sent by
+         * the root CDP session of the page, and all of its child CDP sessions.
+         *
+         * @param headers - the headers to be set.
+         * @throws {StagehandSetExtraHTTPHeadersError}
+         * Thrown when one or more CDP sessions fail to enable the Network domain or fail
+         * to apply the headers (i.e. `Network.enable` and/or `Network.setExtraHTTPHeaders` rejects).
+         * @return void
+         */
+        async setExtraHTTPHeaders(headers) {
+            const headersToSet = { ...headers };
+            this.extraHTTPHeaders = headersToSet;
+            // get the session(s) for this page:
+            const sessions = [this.mainSession];
+            for (const session of this.sessions.values()) {
+                if (session === this.mainSession)
+                    continue;
+                sessions.push(session);
+            }
+            const results = await Promise.allSettled(sessions.map(async (session) => {
+                await this.applyExtraHTTPHeadersToSession(session, headersToSet);
+            }));
+            // get list of objects containing results & corresponding session IDs
+            const pairs = results.map((result, index) => ({
+                result,
+                id: sessions[index].id,
+            }));
+            const filtered = pairs.filter((pair) => pair.result.status === "rejected");
+            const errors = filtered.map((pair) => {
+                const reason = pair.result.reason;
+                const sessId = pair.id ?? "root";
+                const message = reason?.message ?? String(reason);
+                return `session=${sessId} error=${message}`;
+            });
+            if (errors.length > 0) {
+                throw new StagehandSetExtraHTTPHeadersError(errors);
+            }
         }
         /**
          * Create a locator bound to the current main frame.