@browserbasehq/orca 3.0.9-alpha-3 → 3.1.0-patch.0

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

@@ -0,0 +1,330 @@
+/**
+ * Response
+ * -----------------
+ *
+ * This module implements a Playwright-inspired response wrapper that exposes
+ * navigation metadata and helpers for retrieving HTTP response bodies. The
+ * abstraction is consumed by navigation routines (e.g. `Page.goto`) so callers
+ * can synchronously inspect status codes, lazily fetch body text, or await the
+ * network layer finishing the request. The implementation is built directly on
+ * Chrome DevTools Protocol primitives – it holds the originating `requestId`
+ * so it can request payloads via `Network.getResponseBody`, and it listens for
+ * `responseReceivedExtraInfo`, `loadingFinished`, and `loadingFailed` events to
+ * hydrate the richer header view and resolve callers waiting on completion.
+ */
+import { ResponseBodyError, ResponseParseError, } from "../types/public/sdkErrors.js";
+export function isSerializableResponse(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const candidate = value;
+    if (typeof candidate.requestId !== "string")
+        return false;
+    if (!candidate.response || typeof candidate.response !== "object") {
+        return false;
+    }
+    return true;
+}
+function createDeferred() {
+    let resolve;
+    let reject;
+    const promise = new Promise((res, rej) => {
+        resolve = res;
+        reject = rej;
+    });
+    return { promise, resolve, reject };
+}
+/** Normalise header names to lowercase for case-insensitive lookups. */
+function normaliseHeaderName(name) {
+    return name.toLowerCase();
+}
+/** Split multi-value header strings into discrete values while trimming. */
+function splitHeaderValues(value) {
+    return value
+        .split(/\r?\n/)
+        .map((part) => part.trim())
+        .filter(Boolean);
+}
+/**
+ * Parse an HTTP header text block (as emitted by CDP) into an ordered array of
+ * name/value pairs while preserving the wire casing.
+ */
+function parseHeadersText(headersText) {
+    if (!headersText)
+        return [];
+    const lines = headersText.split(/\r?\n/);
+    const entries = [];
+    for (const line of lines) {
+        if (!line || line.startsWith("HTTP/"))
+            continue;
+        const index = line.indexOf(":");
+        if (index === -1)
+            continue;
+        const name = line.slice(0, index).trim();
+        const value = line.slice(index + 1).trim();
+        entries.push({ name, value });
+    }
+    return entries;
+}
+/**
+ * Thin wrapper around CDP response metadata that mirrors the ergonomics of
+ * Playwright's `Response` class. The class intentionally keeps the same method
+ * names so upstream integrations can transition with minimal code changes.
+ */
+export class Response {
+    page;
+    session;
+    requestId;
+    frameId;
+    loaderId;
+    response;
+    fromServiceWorkerFlag;
+    serverAddress;
+    headersObject;
+    headersArrayCache = null;
+    allHeadersCache = null;
+    headerValuesMap = new Map();
+    finishedDeferred = createDeferred();
+    finishedSettled = false;
+    extraInfoHeaders = null;
+    extraInfoHeadersText;
+    /**
+     * Build a response wrapper from the CDP notification associated with a
+     * navigation. The constructor captures the owning page/session so follow-up
+     * methods (body/text/json) can query CDP on-demand. The `response` payload is
+     * the raw `Protocol.Network.Response` object emitted by Chrome.
+     */
+    constructor(params) {
+        this.page = params.page;
+        this.session = params.session;
+        this.requestId = params.requestId;
+        this.frameId = params.frameId;
+        this.loaderId = params.loaderId;
+        this.response = params.response;
+        this.fromServiceWorkerFlag = params.fromServiceWorker;
+        if (params.response.remoteIPAddress &&
+            params.response.remotePort !== undefined) {
+            this.serverAddress = {
+                ipAddress: params.response.remoteIPAddress,
+                port: params.response.remotePort,
+            };
+        }
+        else {
+            this.serverAddress = null;
+        }
+        this.headersObject = {};
+        for (const [name, value] of Object.entries(this.response.headers ?? {})) {
+            const lower = normaliseHeaderName(name);
+            if (value === undefined)
+                continue;
+            const values = splitHeaderValues(String(value));
+            this.headerValuesMap.set(lower, values);
+            this.headersObject[lower] = values.join(", ");
+        }
+    }
+    /** URL associated with the navigation request. */
+    url() {
+        return this.response.url;
+    }
+    /** HTTP status code reported by Chrome. */
+    status() {
+        return this.response.status;
+    }
+    /** Human-readable status text that accompanied the response. */
+    statusText() {
+        return this.response.statusText;
+    }
+    /** Convenience predicate that checks for 2xx statuses. */
+    ok() {
+        const status = this.status();
+        return status >= 200 && status <= 299;
+    }
+    /** Returns the Stagehand frame object that initiated the navigation. */
+    frame() {
+        if (!this.frameId)
+            return null;
+        try {
+            return this.page.frameForId(this.frameId);
+        }
+        catch {
+            return null;
+        }
+    }
+    /** Indicates whether the response was serviced by a Service Worker. */
+    fromServiceWorker() {
+        return this.fromServiceWorkerFlag;
+    }
+    /**
+     * Returns TLS security metadata when provided by the browser. In practice
+     * this includes certificate issuer, protocol, and validity interval.
+     */
+    async securityDetails() {
+        return this.response.securityDetails ?? null;
+    }
+    /** Returns the resolved server address for the navigation when available. */
+    async serverAddr() {
+        return this.serverAddress ?? null;
+    }
+    /**
+     * Returns the response headers normalised to lowercase keys. Matches the
+     * behaviour of Playwright's `headers()` by eliding duplicate header entries.
+     */
+    headers() {
+        return { ...this.headersObject };
+    }
+    /**
+     * Returns all headers including those only surfaced through
+     * `responseReceivedExtraInfo` such as `set-cookie`. Values are reported as the
+     * browser sends them (no further splitting or concatenation).
+     */
+    async allHeaders() {
+        if (this.allHeadersCache)
+            return { ...this.allHeadersCache };
+        const source = this.extraInfoHeaders ?? this.response.headers ?? {};
+        const map = {};
+        for (const [name, value] of Object.entries(source)) {
+            map[name] = String(value);
+        }
+        this.allHeadersCache = map;
+        return { ...map };
+    }
+    /** Returns a concatenated header string for the supplied header name. */
+    async headerValue(name) {
+        const values = await this.headerValues(name);
+        if (!values.length)
+            return null;
+        return values.join(", ");
+    }
+    /** Returns all values for a header (case-insensitive lookup). */
+    async headerValues(name) {
+        const lower = normaliseHeaderName(name);
+        if (this.extraInfoHeaders) {
+            const raw = this.extraInfoHeaders[name] ?? this.extraInfoHeaders[lower];
+            if (raw !== undefined) {
+                return splitHeaderValues(String(raw));
+            }
+        }
+        const values = this.headerValuesMap.get(lower);
+        return values ? [...values] : [];
+    }
+    /**
+     * Returns header entries preserving their original wire casing and ordering.
+     * Falls back to the CDP object when the raw header text is unavailable.
+     */
+    async headersArray() {
+        if (this.headersArrayCache)
+            return [...this.headersArrayCache];
+        const entriesFromText = parseHeadersText(this.extraInfoHeadersText);
+        if (entriesFromText.length > 0) {
+            this.headersArrayCache = entriesFromText;
+            return [...entriesFromText];
+        }
+        const entries = [];
+        const source = this.extraInfoHeaders ?? this.response.headers ?? {};
+        for (const [name, value] of Object.entries(source)) {
+            const values = splitHeaderValues(String(value));
+            for (const val of values) {
+                entries.push({ name, value: val });
+            }
+        }
+        this.headersArrayCache = entries;
+        return [...entries];
+    }
+    /**
+     * Requests the raw response body from Chrome DevTools Protocol. The method is
+     * intentionally lazy because not every caller needs the payload, and CDP only
+     * allows retrieving it once the response completes.
+     */
+    async body() {
+        const result = await this.session
+            .send("Network.getResponseBody", { requestId: this.requestId })
+            .catch((error) => {
+            throw new ResponseBodyError(String(error));
+        });
+        if (result.base64Encoded) {
+            return Buffer.from(result.body, "base64");
+        }
+        return Buffer.from(result.body, "utf-8");
+    }
+    /** Decodes the response body as UTF-8 text. */
+    async text() {
+        const buffer = await this.body();
+        return buffer.toString("utf-8");
+    }
+    /** Parses the response body as JSON and throws if parsing fails. */
+    async json() {
+        const text = await this.text();
+        try {
+            return JSON.parse(text);
+        }
+        catch (error) {
+            throw new ResponseParseError(String(error));
+        }
+    }
+    /**
+     * Resolves once the underlying network request completes or fails. Mirrors
+     * Playwright's behaviour by resolving to `null` on success and to an `Error`
+     * instance when Chrome reports `Network.loadingFailed`.
+     */
+    async finished() {
+        return this.finishedDeferred.promise;
+    }
+    /**
+     * Internal helper invoked by the navigation tracker when CDP reports extra
+     * header information. This keeps the cached header views in sync with the
+     * richer metadata.
+     */
+    applyExtraInfo(event) {
+        this.extraInfoHeaders = event.headers;
+        this.extraInfoHeadersText = event.headersText;
+        this.allHeadersCache = null;
+        this.headersArrayCache = null;
+        this.headersObject = {};
+        this.headerValuesMap.clear();
+        const source = event.headers ?? {};
+        for (const [name, value] of Object.entries(source)) {
+            const lower = normaliseHeaderName(name);
+            const segments = splitHeaderValues(String(value));
+            this.headerValuesMap.set(lower, segments);
+            this.headersObject[lower] = segments.join(", ");
+        }
+    }
+    /**
+     * Internal helper for creating a Response object from a Serializable
+     * goto response from the Stagehand API
+     */
+    static fromSerializable(serialized, context) {
+        const reconstructed = new Response({
+            page: context.page,
+            session: context.session,
+            requestId: serialized.requestId,
+            frameId: serialized.frameId,
+            loaderId: serialized.loaderId,
+            response: serialized.response,
+            fromServiceWorker: serialized.fromServiceWorkerFlag ?? false,
+        });
+        if (serialized.extraInfoHeaders) {
+            reconstructed.applyExtraInfo({
+                requestId: serialized.requestId,
+                headers: serialized.extraInfoHeaders,
+                headersText: serialized.extraInfoHeadersText,
+            });
+        }
+        if (serialized.finishedSettled) {
+            reconstructed.markFinished(null);
+        }
+        return reconstructed;
+    }
+    /** Marks the response as finished and resolves the `finished()` promise. */
+    markFinished(error) {
+        if (this.finishedSettled)
+            return;
+        this.finishedSettled = true;
+        if (error) {
+            this.finishedDeferred.resolve(error);
+        }
+        else {
+            this.finishedDeferred.resolve(null);
+        }
+    }
+}
+//# sourceMappingURL=response.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"response.js","sourceRoot":"","sources":["../../../../../lib/v3/understudy/response.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Response\n * -----------------\n *\n * This module implements a Playwright-inspired response wrapper that exposes\n * navigation metadata and helpers for retrieving HTTP response bodies. The\n * abstraction is consumed by navigation routines (e.g. `Page.goto`) so callers\n * can synchronously inspect status codes, lazily fetch body text, or await the\n * network layer finishing the request. The implementation is built directly on\n * Chrome DevTools Protocol primitives – it holds the originating `requestId`\n * so it can request payloads via `Network.getResponseBody`, and it listens for\n * `responseReceivedExtraInfo`, `loadingFinished`, and `loadingFailed` events to\n * hydrate the richer header view and resolve callers waiting on completion.\n */\n\nimport type { Protocol } from \"devtools-protocol\";\nimport type { SerializableResponse } from \"../types/private/index.js\";\nimport {\n  ResponseBodyError,\n  ResponseParseError,\n} from \"../types/public/sdkErrors.js\";\nimport type { CDPSessionLike } from \"./cdp.js\";\nimport type { Frame } from \"./frame.js\";\nimport type { Page } from \"./page.js\";\n\ntype ServerAddr = { ipAddress: string; port: number };\n\nexport function isSerializableResponse(\n  value: unknown,\n): value is SerializableResponse {\n  if (!value || typeof value !== \"object\") return false;\n  const candidate = value as Partial<SerializableResponse>;\n  if (typeof candidate.requestId !== \"string\") return false;\n  if (!candidate.response || typeof candidate.response !== \"object\") {\n    return false;\n  }\n  return true;\n}\n\n/**\n * Minimal deferred helper that lets navigation tracking hand out a promise and\n * later control the resolution from event callbacks. Each response owns a\n * single deferred covering the \"finished\" promise so consumers can mirror\n * Playwright's `response.finished()` behaviour.\n */\ntype Deferred<T> = {\n  promise: Promise<T>;\n  resolve: (value: T) => void;\n  reject: (error: Error) => void;\n};\n\nfunction createDeferred<T>(): Deferred<T> {\n  let resolve!: (value: T) => void;\n  let reject!: (error: Error) => void;\n  const promise = new Promise<T>((res, rej) => {\n    resolve = res;\n    reject = rej;\n  });\n  return { promise, resolve, reject };\n}\n\n/** Normalise header names to lowercase for case-insensitive lookups. */\nfunction normaliseHeaderName(name: string): string {\n  return name.toLowerCase();\n}\n\n/** Split multi-value header strings into discrete values while trimming. */\nfunction splitHeaderValues(value: string): string[] {\n  return value\n    .split(/\\r?\\n/)\n    .map((part) => part.trim())\n    .filter(Boolean);\n}\n\n/**\n * Parse an HTTP header text block (as emitted by CDP) into an ordered array of\n * name/value pairs while preserving the wire casing.\n */\nfunction parseHeadersText(\n  headersText: string | undefined,\n): Array<{ name: string; value: string }> {\n  if (!headersText) return [];\n  const lines = headersText.split(/\\r?\\n/);\n  const entries: Array<{ name: string; value: string }> = [];\n  for (const line of lines) {\n    if (!line || line.startsWith(\"HTTP/\")) continue;\n    const index = line.indexOf(\":\");\n    if (index === -1) continue;\n    const name = line.slice(0, index).trim();\n    const value = line.slice(index + 1).trim();\n    entries.push({ name, value });\n  }\n  return entries;\n}\n\n/**\n * Thin wrapper around CDP response metadata that mirrors the ergonomics of\n * Playwright's `Response` class. The class intentionally keeps the same method\n * names so upstream integrations can transition with minimal code changes.\n */\nexport class Response {\n  private readonly page: Page;\n  private readonly session: CDPSessionLike;\n  private readonly requestId: string;\n  private readonly frameId?: string;\n  private readonly loaderId?: string;\n  private readonly response: Protocol.Network.Response;\n  private readonly fromServiceWorkerFlag: boolean;\n  private readonly serverAddress?: ServerAddr | null;\n\n  private headersObject: Record<string, string>;\n  private headersArrayCache: Array<{ name: string; value: string }> | null =\n    null;\n  private allHeadersCache: Record<string, string> | null = null;\n  private readonly headerValuesMap = new Map<string, string[]>();\n\n  private finishedDeferred = createDeferred<null | Error>();\n  private finishedSettled = false;\n\n  private extraInfoHeaders: Protocol.Network.Headers | null = null;\n  private extraInfoHeadersText: string | undefined;\n\n  /**\n   * Build a response wrapper from the CDP notification associated with a\n   * navigation. The constructor captures the owning page/session so follow-up\n   * methods (body/text/json) can query CDP on-demand. The `response` payload is\n   * the raw `Protocol.Network.Response` object emitted by Chrome.\n   */\n  constructor(params: {\n    page: Page;\n    session: CDPSessionLike;\n    requestId: string;\n    frameId?: string;\n    loaderId?: string;\n    response: Protocol.Network.Response;\n    fromServiceWorker: boolean;\n  }) {\n    this.page = params.page;\n    this.session = params.session;\n    this.requestId = params.requestId;\n    this.frameId = params.frameId;\n    this.loaderId = params.loaderId;\n    this.response = params.response;\n    this.fromServiceWorkerFlag = params.fromServiceWorker;\n\n    if (\n      params.response.remoteIPAddress &&\n      params.response.remotePort !== undefined\n    ) {\n      this.serverAddress = {\n        ipAddress: params.response.remoteIPAddress,\n        port: params.response.remotePort,\n      };\n    } else {\n      this.serverAddress = null;\n    }\n\n    this.headersObject = {};\n    for (const [name, value] of Object.entries(this.response.headers ?? {})) {\n      const lower = normaliseHeaderName(name);\n      if (value === undefined) continue;\n      const values = splitHeaderValues(String(value));\n      this.headerValuesMap.set(lower, values);\n      this.headersObject[lower] = values.join(\", \");\n    }\n  }\n\n  /** URL associated with the navigation request. */\n  url(): string {\n    return this.response.url;\n  }\n\n  /** HTTP status code reported by Chrome. */\n  status(): number {\n    return this.response.status;\n  }\n\n  /** Human-readable status text that accompanied the response. */\n  statusText(): string {\n    return this.response.statusText;\n  }\n\n  /** Convenience predicate that checks for 2xx statuses. */\n  ok(): boolean {\n    const status = this.status();\n    return status >= 200 && status <= 299;\n  }\n\n  /** Returns the Stagehand frame object that initiated the navigation. */\n  frame(): Frame | null {\n    if (!this.frameId) return null;\n    try {\n      return this.page.frameForId(this.frameId);\n    } catch {\n      return null;\n    }\n  }\n\n  /** Indicates whether the response was serviced by a Service Worker. */\n  fromServiceWorker(): boolean {\n    return this.fromServiceWorkerFlag;\n  }\n\n  /**\n   * Returns TLS security metadata when provided by the browser. In practice\n   * this includes certificate issuer, protocol, and validity interval.\n   */\n  async securityDetails(): Promise<Protocol.Network.SecurityDetails | null> {\n    return this.response.securityDetails ?? null;\n  }\n\n  /** Returns the resolved server address for the navigation when available. */\n  async serverAddr(): Promise<ServerAddr | null> {\n    return this.serverAddress ?? null;\n  }\n\n  /**\n   * Returns the response headers normalised to lowercase keys. Matches the\n   * behaviour of Playwright's `headers()` by eliding duplicate header entries.\n   */\n  headers(): Record<string, string> {\n    return { ...this.headersObject };\n  }\n\n  /**\n   * Returns all headers including those only surfaced through\n   * `responseReceivedExtraInfo` such as `set-cookie`. Values are reported as the\n   * browser sends them (no further splitting or concatenation).\n   */\n  async allHeaders(): Promise<Record<string, string>> {\n    if (this.allHeadersCache) return { ...this.allHeadersCache };\n    const source = this.extraInfoHeaders ?? this.response.headers ?? {};\n    const map: Record<string, string> = {};\n    for (const [name, value] of Object.entries(source)) {\n      map[name] = String(value);\n    }\n    this.allHeadersCache = map;\n    return { ...map };\n  }\n\n  /** Returns a concatenated header string for the supplied header name. */\n  async headerValue(name: string): Promise<string | null> {\n    const values = await this.headerValues(name);\n    if (!values.length) return null;\n    return values.join(\", \");\n  }\n\n  /** Returns all values for a header (case-insensitive lookup). */\n  async headerValues(name: string): Promise<string[]> {\n    const lower = normaliseHeaderName(name);\n    if (this.extraInfoHeaders) {\n      const raw = this.extraInfoHeaders[name] ?? this.extraInfoHeaders[lower];\n      if (raw !== undefined) {\n        return splitHeaderValues(String(raw));\n      }\n    }\n    const values = this.headerValuesMap.get(lower);\n    return values ? [...values] : [];\n  }\n\n  /**\n   * Returns header entries preserving their original wire casing and ordering.\n   * Falls back to the CDP object when the raw header text is unavailable.\n   */\n  async headersArray(): Promise<Array<{ name: string; value: string }>> {\n    if (this.headersArrayCache) return [...this.headersArrayCache];\n\n    const entriesFromText = parseHeadersText(this.extraInfoHeadersText);\n    if (entriesFromText.length > 0) {\n      this.headersArrayCache = entriesFromText;\n      return [...entriesFromText];\n    }\n\n    const entries: Array<{ name: string; value: string }> = [];\n    const source = this.extraInfoHeaders ?? this.response.headers ?? {};\n    for (const [name, value] of Object.entries(source)) {\n      const values = splitHeaderValues(String(value));\n      for (const val of values) {\n        entries.push({ name, value: val });\n      }\n    }\n    this.headersArrayCache = entries;\n    return [...entries];\n  }\n\n  /**\n   * Requests the raw response body from Chrome DevTools Protocol. The method is\n   * intentionally lazy because not every caller needs the payload, and CDP only\n   * allows retrieving it once the response completes.\n   */\n  async body(): Promise<Buffer> {\n    const result = await this.session\n      .send<Protocol.Network.GetResponseBodyResponse>(\n        \"Network.getResponseBody\",\n        { requestId: this.requestId },\n      )\n      .catch((error) => {\n        throw new ResponseBodyError(String(error));\n      });\n\n    if (result.base64Encoded) {\n      return Buffer.from(result.body, \"base64\");\n    }\n    return Buffer.from(result.body, \"utf-8\");\n  }\n\n  /** Decodes the response body as UTF-8 text. */\n  async text(): Promise<string> {\n    const buffer = await this.body();\n    return buffer.toString(\"utf-8\");\n  }\n\n  /** Parses the response body as JSON and throws if parsing fails. */\n  async json<T = unknown>(): Promise<T> {\n    const text = await this.text();\n    try {\n      return JSON.parse(text) as T;\n    } catch (error) {\n      throw new ResponseParseError(String(error));\n    }\n  }\n\n  /**\n   * Resolves once the underlying network request completes or fails. Mirrors\n   * Playwright's behaviour by resolving to `null` on success and to an `Error`\n   * instance when Chrome reports `Network.loadingFailed`.\n   */\n  async finished(): Promise<null | Error> {\n    return this.finishedDeferred.promise;\n  }\n\n  /**\n   * Internal helper invoked by the navigation tracker when CDP reports extra\n   * header information. This keeps the cached header views in sync with the\n   * richer metadata.\n   */\n  public applyExtraInfo(\n    event: Protocol.Network.ResponseReceivedExtraInfoEvent,\n  ): void {\n    this.extraInfoHeaders = event.headers;\n    this.extraInfoHeadersText = event.headersText;\n    this.allHeadersCache = null;\n    this.headersArrayCache = null;\n    this.headersObject = {};\n    this.headerValuesMap.clear();\n\n    const source = event.headers ?? {};\n    for (const [name, value] of Object.entries(source)) {\n      const lower = normaliseHeaderName(name);\n      const segments = splitHeaderValues(String(value));\n      this.headerValuesMap.set(lower, segments);\n      this.headersObject[lower] = segments.join(\", \");\n    }\n  }\n\n  /**\n   * Internal helper for creating a Response object from a Serializable\n   * goto response from the Stagehand API\n   */\n  public static fromSerializable(\n    serialized: SerializableResponse,\n    context: { page: Page; session: CDPSessionLike },\n  ): Response {\n    const reconstructed = new Response({\n      page: context.page,\n      session: context.session,\n      requestId: serialized.requestId,\n      frameId: serialized.frameId,\n      loaderId: serialized.loaderId,\n      response: serialized.response as Protocol.Network.Response,\n      fromServiceWorker: serialized.fromServiceWorkerFlag ?? false,\n    });\n\n    if (serialized.extraInfoHeaders) {\n      reconstructed.applyExtraInfo({\n        requestId: serialized.requestId,\n        headers: serialized.extraInfoHeaders,\n        headersText: serialized.extraInfoHeadersText,\n      } as Protocol.Network.ResponseReceivedExtraInfoEvent);\n    }\n\n    if (serialized.finishedSettled) {\n      reconstructed.markFinished(null);\n    }\n\n    return reconstructed;\n  }\n\n  /** Marks the response as finished and resolves the `finished()` promise. */\n  public markFinished(error: Error | null): void {\n    if (this.finishedSettled) return;\n    this.finishedSettled = true;\n    if (error) {\n      this.finishedDeferred.resolve(error);\n    } else {\n      this.finishedDeferred.resolve(null);\n    }\n  }\n}\n"]}

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

@@ -0,0 +1,16 @@
+import type { CDPSessionLike } from "./cdp.js";
+import type { Frame } from "./frame.js";
+import type { Locator } from "./locator.js";
+import type { Page } from "./page.js";
+import type { ScreenshotClip, ScreenshotScaleOption } from "../types/public/screenshotTypes.js";
+export type ScreenshotCleanup = () => Promise<void> | void;
+export declare function collectFramesForScreenshot(page: Page): Frame[];
+export declare function normalizeScreenshotClip(clip: ScreenshotClip): ScreenshotClip;
+export declare function computeScreenshotScale(page: Page, mode: ScreenshotScaleOption): Promise<number | undefined>;
+export declare function setTransparentBackground(session: CDPSessionLike): Promise<ScreenshotCleanup>;
+export declare function applyStyleToFrames(frames: Frame[], css: string, label: string): Promise<ScreenshotCleanup>;
+export declare function disableAnimations(frames: Frame[]): Promise<ScreenshotCleanup>;
+export declare function hideCaret(frames: Frame[]): Promise<ScreenshotCleanup>;
+export declare function applyMaskOverlays(locators: Locator[], color: string): Promise<ScreenshotCleanup>;
+export declare function runScreenshotCleanups(cleanups: ScreenshotCleanup[]): Promise<void>;
+export declare function withScreenshotTimeout<T>(timeoutMs: number | undefined, task: () => Promise<T>): Promise<T>;