chrome-devtools-frontend 1.0.1690116 → 1.0.1695017

package/front_end/third_party/puppeteer/package/src/api/Page.ts

@@ -119,6 +119,7 @@ import {
   type AwaitedLocator,
 } from './locators/locators.js';
 import type {Realm} from './Realm.js';
+import type {ScreenRecording} from './ScreenRecording.js';
 import type {Target} from './Target.js';
 import type {WebWorker} from './WebWorker.js';
 
@@ -463,6 +464,46 @@ export interface ScreencastOptions {
   ffmpegPath?: string;
 }
 
+/**
+ * @public
+ * @experimental
+ */
+export interface RecordOptions {
+  /**
+   * File path to save the recording to.
+   */
+  path?: string;
+  /**
+   * Specifies whether to overwrite output file,
+   * or exit immediately if it already exists.
+   *
+   * @defaultValue `true`
+   */
+  overwrite?: boolean;
+  /**
+   * Whether to record audio.
+   *
+   * @defaultValue `false`
+   */
+  audio?: boolean;
+  /**
+   * Maximum frame width in pixels.
+   */
+  maxWidth?: number;
+  /**
+   * Maximum frame height in pixels.
+   */
+  maxHeight?: number;
+  /**
+   * Maximum frame rate in frames per second.
+   */
+  frameRate?: number;
+  /**
+   * Frame rate in frames per second (alias for frameRate).
+   */
+  fps?: number;
+}
+
 /**
  * @public
  */
@@ -2138,7 +2179,7 @@ export abstract class Page extends EventEmitter<PageEvents> {
    *
    * ```ts
    * import {KnownDevices} from 'puppeteer';
-   * const iPhone = KnownDevices['iPhone 15 Pro'];
+   * const iPhone = KnownDevices['iPhone 17 Pro'];
    *
    * const browser = await puppeteer.launch();
    * const page = await browser.newPage();
@@ -2512,7 +2553,7 @@ export abstract class Page extends EventEmitter<PageEvents> {
   }
 
   /**
-   * Captures a screencast of this {@link Page | page}.
+   * Captures a screencast of this {@link Page | page}. Works in Chrome 153+.
    *
    * @example
    * Recording a {@link Page | page}:
@@ -2542,7 +2583,7 @@ export abstract class Page extends EventEmitter<PageEvents> {
    *
    * @param options - Configures screencast behavior.
    *
-   * @experimental
+   * @deprecated Use {@link Page.record} instead.
    *
    * @remarks
    *
@@ -2638,6 +2679,96 @@ export abstract class Page extends EventEmitter<PageEvents> {
     return recorder;
   }
 
+  /**
+   * @internal
+   */
+  protected abstract createScreenRecording(
+    options: Readonly<RecordOptions>,
+  ): ScreenRecording;
+
+  /**
+   * Records this {@link Page | page} using the Chrome DevTools Protocol
+   * {@link https://chromedevtools.github.io/devtools-protocol/tot/Page/#method-startScreenRecording | Page.startScreenRecording}
+   * API.
+   *
+   * Outputs mp4 video stream.
+   *
+   * @example
+   * Recording a {@link Page | page}:
+   *
+   * ```ts
+   * import puppeteer from 'puppeteer';
+   *
+   * // Launch a browser
+   * const browser = await puppeteer.launch();
+   *
+   * // Create a new page
+   * const page = await browser.newPage();
+   *
+   * // Go to your site.
+   * await page.goto('https://www.example.com');
+   *
+   * // Start recording.
+   * const recorder = await page.record({path: 'recording.mp4'});
+   *
+   * // Do something.
+   *
+   * // Stop recording.
+   * await recorder.stop();
+   *
+   * await browser.close();
+   * ```
+   *
+   * @param options - Configures recording behavior.
+   *
+   * @experimental
+   */
+  async record(
+    options: Readonly<RecordOptions> = {},
+  ): Promise<ScreenRecording> {
+    if (options.maxWidth !== undefined && options.maxWidth <= 0) {
+      throw new Error('`maxWidth` must be greater than 0.');
+    }
+    if (options.maxHeight !== undefined && options.maxHeight <= 0) {
+      throw new Error('`maxHeight` must be greater than 0.');
+    }
+    if (options.frameRate !== undefined && options.frameRate <= 0) {
+      throw new Error('`frameRate` must be greater than 0.');
+    }
+    if (options.fps !== undefined && options.fps <= 0) {
+      throw new Error('`fps` must be greater than 0.');
+    }
+
+    if (options.path && environment.value.path) {
+      await environment.value.mkdir(
+        environment.value.path.dirname(options.path),
+        {recursive: options.overwrite ?? true},
+      );
+    }
+
+    const stream = options.path
+      ? environment.value.createWriteStream(options.path, {
+          encoding: 'binary',
+          overwrite: options.overwrite,
+        })
+      : undefined;
+
+    const recording = this.createScreenRecording(options);
+
+    try {
+      await recording._start();
+    } catch (error) {
+      void recording.stop();
+      throw error;
+    }
+
+    if (stream) {
+      recording.pipe(stream);
+    }
+
+    return recording;
+  }
+
   #screencastSessionCount = 0;
   #startScreencastPromise: Promise<void> | undefined;
 
@@ -2647,15 +2778,16 @@ export abstract class Page extends EventEmitter<PageEvents> {
   async _startScreencast(): Promise<void> {
     ++this.#screencastSessionCount;
     if (!this.#startScreencastPromise) {
-      this.#startScreencastPromise = this.mainFrame()
-        .client.send('Page.startScreencast', {format: 'png'})
+      const client = this.mainFrame().client;
+      const firstFrame = new Promise<void>(resolve => {
+        return client.once('Page.screencastFrame', () => {
+          return resolve();
+        });
+      });
+      this.#startScreencastPromise = client
+        .send('Page.startScreencast', {format: 'png'})
         .then(() => {
-          // Wait for the first frame.
-          return new Promise(resolve => {
-            return this.mainFrame().client.once('Page.screencastFrame', () => {
-              return resolve();
-            });
-          });
+          return firstFrame;
         });
     }
     await this.#startScreencastPromise;

package/front_end/third_party/puppeteer/package/src/api/ScreenRecording.ts

@@ -0,0 +1,145 @@
+/**
+ * @license
+ * Copyright 2026 Google Inc.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type {Logger} from '../common/Debug.js';
+import {asyncDisposeSymbol} from '../util/disposable.js';
+
+import type {Page, RecordOptions} from './Page.js';
+
+/**
+ * @public
+ */
+export interface WritableDestination {
+  write(chunk: Uint8Array): boolean;
+  end(): unknown;
+  writableFinished?: boolean;
+  closed?: boolean;
+  destroyed?: boolean;
+  once?(event: string, cb: (arg?: unknown) => void): unknown;
+}
+
+/**
+ * @public
+ */
+export abstract class ScreenRecording extends ReadableStream<Uint8Array> {
+  /**
+   * @internal
+   */
+  protected page: Page;
+  /**
+   * @internal
+   */
+  protected options: RecordOptions;
+  /**
+   * @internal
+   */
+  protected logger: Logger;
+  /**
+   * @internal
+   */
+  protected controller!: ReadableStreamDefaultController<Uint8Array>;
+  /**
+   * @internal
+   */
+  protected destinations = new Set<WritableDestination>();
+  /**
+   * @internal
+   */
+  protected stopped = false;
+
+  /**
+   * @internal
+   */
+  constructor(page: Page, options: RecordOptions = {}, logger: Logger) {
+    let controller!: ReadableStreamDefaultController<Uint8Array>;
+    super({
+      start(c) {
+        controller = c;
+      },
+    });
+    this.controller = controller;
+
+    this.page = page;
+    this.options = options;
+    this.logger = logger;
+  }
+
+  /**
+   * @internal
+   */
+  abstract _start(): Promise<void>;
+
+  /**
+   * Pipes the recorded stream to a destination stream.
+   *
+   * @public
+   */
+  pipe<T extends WritableStream<Uint8Array>>(destination: T): Promise<void>;
+  pipe<T extends WritableDestination>(destination: T): T;
+  pipe(
+    destination: WritableStream<Uint8Array> | WritableDestination,
+  ): Promise<void> | WritableDestination {
+    if (
+      'getWriter' in destination &&
+      typeof destination.getWriter === 'function'
+    ) {
+      return this.pipeTo(destination as WritableStream<Uint8Array>);
+    }
+    const dest = destination as WritableDestination;
+    this.destinations.add(dest);
+    dest.once?.('unpipe', () => {
+      this.destinations.delete(dest);
+    });
+    dest.once?.('error', () => {
+      this.destinations.delete(dest);
+    });
+    dest.once?.('close', () => {
+      this.destinations.delete(dest);
+    });
+    dest.once?.('finish', () => {
+      this.destinations.delete(dest);
+    });
+    return dest;
+  }
+
+  /**
+   * Stops the screen recording.
+   *
+   * @public
+   */
+  abstract stop(): Promise<void>;
+
+  /**
+   * @internal
+   */
+  protected async closeDestinations(): Promise<void> {
+    try {
+      this.controller.close();
+    } catch {
+      // Controller might already be closed.
+    }
+    for (const dest of this.destinations) {
+      dest.end();
+    }
+    const destinationPromises = Array.from(this.destinations).map(dest => {
+      return new Promise(resolve => {
+        if (dest.writableFinished || dest.closed || dest.destroyed) {
+          resolve(undefined);
+        } else {
+          dest.once?.('finish', resolve);
+          dest.once?.('close', resolve);
+          dest.once?.('error', resolve);
+        }
+      });
+    });
+
+    await Promise.all(destinationPromises);
+  }
+
+  async [asyncDisposeSymbol](): Promise<void> {
+    await this.stop();
+  }
+}

package/front_end/third_party/puppeteer/package/src/api/api.ts

@@ -21,6 +21,7 @@ export type * from './Issue.js';
 export * from './JSHandle.js';
 export * from './Page.js';
 export * from './Realm.js';
+export * from './ScreenRecording.js';
 export * from './Target.js';
 export * from './WebWorker.js';
 export * from './locators/locators.js';

package/front_end/third_party/puppeteer/package/src/bidi/Page.ts

@@ -22,6 +22,7 @@ import type {
   HeapSnapshotOptions,
   MediaFeature,
   PageEvents,
+  RecordOptions,
   ReloadOptions,
   WaitTimeoutOptions,
 } from '../api/Page.js';
@@ -70,6 +71,7 @@ import {BidiFrame} from './Frame.js';
 import type {BidiHTTPResponse} from './HTTPResponse.js';
 import {BidiKeyboard, BidiMouse, BidiTouchscreen} from './Input.js';
 import type {BidiJSHandle} from './JSHandle.js';
+import {BidiScreenRecording} from './ScreenRecording.js';
 import {rewriteNavigationError} from './util.js';
 import type {BidiWebWorker} from './WebWorker.js';
 
@@ -1033,6 +1035,15 @@ export class BidiPage extends Page {
   override extensionRealms(): Realm[] {
     throw new UnsupportedOperation();
   }
+
+  /**
+   * @internal
+   */
+  override createScreenRecording(
+    options: Readonly<RecordOptions>,
+  ): BidiScreenRecording {
+    return new BidiScreenRecording(this, options, this.logger);
+  }
 }
 
 // eslint-disable-next-line @typescript-eslint/no-unsafe-function-type

package/front_end/third_party/puppeteer/package/src/bidi/ScreenRecording.ts

@@ -0,0 +1,106 @@
+/**
+ * @license
+ * Copyright 2026 Google Inc.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type {RecordOptions} from '../api/Page.js';
+import {ScreenRecording} from '../api/ScreenRecording.js';
+import {DEBUG_PREFIXES, type Logger} from '../common/Debug.js';
+import {environment} from '../environment.js';
+import {guarded} from '../util/decorators.js';
+
+import type {BidiPage} from './Page.js';
+
+/**
+ * @internal
+ */
+export class BidiScreenRecording extends ScreenRecording {
+  declare protected page: BidiPage;
+  #screencastId?: string;
+  #path?: string;
+
+  /**
+   * @internal
+   */
+  constructor(page: BidiPage, options: RecordOptions = {}, logger: Logger) {
+    super(page, options, logger);
+
+    const browsingContext = this.page.mainFrame().browsingContext;
+    browsingContext?.once?.('closed', () => {
+      void this.stop().catch(err => {
+        this.logger(DEBUG_PREFIXES.error)?.(err);
+      });
+    });
+  }
+
+  /**
+   * @internal
+   */
+  override async _start(): Promise<void> {
+    const frameRate = this.options.frameRate ?? this.options.fps;
+    const video =
+      this.options.maxWidth !== undefined ||
+      this.options.maxHeight !== undefined ||
+      frameRate !== undefined
+        ? {
+            width: this.options.maxWidth,
+            height: this.options.maxHeight,
+            frameRate,
+          }
+        : undefined;
+
+    const result = await this.page.mainFrame().browsingContext.startScreencast({
+      audio: this.options.audio,
+      video,
+    });
+    this.#screencastId = result.screencast;
+    this.#path = result.path;
+  }
+
+  /**
+   * Stops the screen recording.
+   *
+   * @public
+   */
+  @guarded()
+  override async stop(): Promise<void> {
+    if (this.stopped) {
+      return;
+    }
+    this.stopped = true;
+
+    try {
+      if (!this.#screencastId) {
+        return;
+      }
+
+      const result = await this.page
+        .mainFrame()
+        .browsingContext.stopScreencast(this.#screencastId)
+        .catch(err => {
+          this.logger(DEBUG_PREFIXES.error)?.(err);
+          return undefined;
+        });
+
+      if (result?.error) {
+        this.logger(DEBUG_PREFIXES.error)?.(result.error);
+      }
+
+      const filePath = result?.path ?? this.#path;
+      if (filePath) {
+        try {
+          const buffer = await environment.value.readFile(filePath);
+          this.controller.enqueue(buffer);
+          for (const dest of this.destinations) {
+            dest.write(buffer);
+          }
+        } catch (err) {
+          this.logger(DEBUG_PREFIXES.error)?.(err);
+        }
+      }
+    } finally {
+      await this.closeDestinations();
+    }
+  }
+}

package/front_end/third_party/puppeteer/package/src/bidi/bidi.ts

@@ -16,3 +16,4 @@ export * from './Input.js';
 export * from './JSHandle.js';
 export * from './Page.js';
 export * from './Realm.js';
+export * from './ScreenRecording.js';

package/front_end/third_party/puppeteer/package/src/bidi/core/BrowsingContext.ts

@@ -72,6 +72,14 @@ export type SetViewportOptions = Omit<
   'context'
 >;
 
+/**
+ * @internal
+ */
+export type StartScreencastOptions = Omit<
+  Bidi.BrowsingContext.StartScreencastParameters,
+  'context'
+>;
+
 /**
  * @internal
  */
@@ -390,6 +398,39 @@ export class BrowsingContext extends EventEmitter<{
     return data;
   }
 
+  @throwIfDisposed<BrowsingContext>(context => {
+    // SAFETY: Disposal implies this exists.
+    return context.#reason!;
+  })
+  async startScreencast(
+    options: StartScreencastOptions = {},
+  ): Promise<Bidi.BrowsingContext.StartScreencastResult> {
+    const {result} = await this.#session.send(
+      'browsingContext.startScreencast',
+      {
+        context: this.id,
+        ...options,
+      },
+    );
+    return result;
+  }
+
+  @throwIfDisposed<BrowsingContext>(context => {
+    // SAFETY: Disposal implies this exists.
+    return context.#reason!;
+  })
+  async stopScreencast(
+    screencast: Bidi.BrowsingContext.Screencast,
+  ): Promise<Bidi.BrowsingContext.StopScreencastResult> {
+    const {result} = await this.#session.send(
+      'browsingContext.stopScreencast',
+      {
+        screencast,
+      },
+    );
+    return result;
+  }
+
   @throwIfDisposed<BrowsingContext>(context => {
     // SAFETY: Disposal implies this exists.
     return context.#reason!;

package/front_end/third_party/puppeteer/package/src/cdp/Page.ts

@@ -20,6 +20,7 @@ import type {JSHandle} from '../api/JSHandle.js';
 import type {
   Credentials,
   HeapSnapshotOptions,
+  RecordOptions,
   ReloadOptions,
 } from '../api/Page.js';
 import {
@@ -81,6 +82,7 @@ import type {IsolatedWorld} from './IsolatedWorld.js';
 import {MAIN_WORLD} from './IsolatedWorlds.js';
 import {releaseObject} from './JSHandle.js';
 import type {NetworkConditions} from './NetworkManager.js';
+import {CdpScreenRecording} from './ScreenRecording.js';
 import type {CdpTarget} from './Target.js';
 import {TargetManagerEvent} from './TargetManageEvents.js';
 import type {TargetManager} from './TargetManager.js';
@@ -1361,6 +1363,15 @@ export class CdpPage extends Page {
   override extensionRealms(): Realm[] {
     return this.mainFrame().extensionRealms();
   }
+
+  /**
+   * @internal
+   */
+  override createScreenRecording(
+    options: Readonly<RecordOptions>,
+  ): CdpScreenRecording {
+    return new CdpScreenRecording(this, options, this.logger);
+  }
 }
 
 const supportedMetrics = new Set<string>([

package/front_end/third_party/puppeteer/package/src/cdp/ScreenRecording.ts

@@ -0,0 +1,101 @@
+/**
+ * @license
+ * Copyright 2026 Google Inc.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {CDPSessionEvent} from '../api/CDPSession.js';
+import type {RecordOptions} from '../api/Page.js';
+import {ScreenRecording} from '../api/ScreenRecording.js';
+import {DEBUG_PREFIXES, type Logger} from '../common/Debug.js';
+import {guarded} from '../util/decorators.js';
+import {stringToTypedArray} from '../util/encoding.js';
+
+import type {CdpPage} from './Page.js';
+
+/**
+ * @internal
+ */
+export class CdpScreenRecording extends ScreenRecording {
+  declare protected page: CdpPage;
+  #streamHandle?: string;
+
+  /**
+   * @internal
+   */
+  constructor(page: CdpPage, options: RecordOptions = {}, logger: Logger) {
+    super(page, options, logger);
+
+    const {client} = this.page.mainFrame();
+    client?.once?.(CDPSessionEvent.Disconnected, () => {
+      void this.stop().catch(err => {
+        this.logger(DEBUG_PREFIXES.error)?.(err);
+      });
+    });
+  }
+
+  /**
+   * @internal
+   */
+  override async _start(): Promise<void> {
+    const {client} = this.page.mainFrame();
+    const frameRate = this.options.frameRate ?? this.options.fps;
+    // @ts-expect-error Page.startScreenRecording is not yet in devtools-protocol
+    const result = (await client.send('Page.startScreenRecording', {
+      audio: this.options.audio,
+      maxWidth: this.options.maxWidth,
+      maxHeight: this.options.maxHeight,
+      frameRate,
+    })) as {stream: string};
+    this.#streamHandle = result.stream;
+  }
+
+  /**
+   * Stops the screen recording.
+   *
+   * @public
+   */
+  @guarded()
+  override async stop(): Promise<void> {
+    if (this.stopped) {
+      return;
+    }
+    this.stopped = true;
+
+    try {
+      const {client} = this.page.mainFrame();
+      await client
+        // @ts-expect-error Page.stopScreenRecording is not yet in devtools-protocol
+        .send('Page.stopScreenRecording')
+        .catch(err => {
+          this.logger(DEBUG_PREFIXES.error)?.(err);
+        });
+
+      if (!this.#streamHandle) {
+        throw new Error('Screen recording stream handle is missing.');
+      }
+
+      let eof = false;
+      while (!eof) {
+        const {
+          data,
+          base64Encoded,
+          eof: isEof,
+        } = await client.send('IO.read', {handle: this.#streamHandle});
+        eof = isEof;
+        if (data) {
+          const buffer = stringToTypedArray(data, base64Encoded ?? false);
+          this.controller.enqueue(buffer);
+          for (const dest of this.destinations) {
+            dest.write(buffer);
+          }
+        }
+      }
+      await client.send('IO.close', {handle: this.#streamHandle}).catch(err => {
+        this.logger(DEBUG_PREFIXES.error)?.(err);
+      });
+    } finally {
+      await this.closeDestinations();
+    }
+  }
+}

package/front_end/third_party/puppeteer/package/src/cdp/cdp.ts

@@ -35,6 +35,7 @@ export * from './NetworkEventManager.js';
 export * from './NetworkManager.js';
 export * from './Page.js';
 export * from './PredefinedNetworkConditions.js';
+export * from './ScreenRecording.js';
 export * from './Target.js';
 export * from './TargetManager.js';
 export * from './TargetManageEvents.js';