brave-real-puppeteer-core 24.25.0 → 24.33.0-patch.1

package/src/api/BluetoothEmulation.ts

@@ -0,0 +1,103 @@
+/**
+ * @license
+ * Copyright 2025 Google Inc.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * @public
+ * Emulated bluetooth adapter state.
+ */
+export type AdapterState = 'absent' | 'powered-off' | 'powered-on';
+
+/**
+ * @public
+ * Represents the simulated bluetooth peripheral's manufacturer data.
+ */
+export interface BluetoothManufacturerData {
+  /**
+   * The company identifier, as defined by the {@link https://www.bluetooth.com/specifications/assigned-numbers/company-identifiers/|Bluetooth SIG}.
+   */
+  key: number;
+  /**
+   * The manufacturer-specific data as a base64-encoded string.
+   */
+  data: string;
+}
+
+/**
+ * @public
+ * A bluetooth peripheral to be simulated.
+ */
+export interface PreconnectedPeripheral {
+  address: string;
+  name: string;
+  manufacturerData: BluetoothManufacturerData[];
+  knownServiceUuids: string[];
+}
+
+/**
+ * Exposes the bluetooth emulation abilities.
+ *
+ * @remarks {@link https://webbluetoothcg.github.io/web-bluetooth/#simulated-bluetooth-adapter|Web Bluetooth specification}
+ * requires the emulated adapters should be isolated per top-level navigable. However,
+ * at the moment Chromium's bluetooth emulation implementation is tight to the browser
+ * context, not the page. This means the bluetooth emulation exposed from different pages
+ * of the same browser context would interfere their states.
+ *
+ * @example
+ *
+ * ```ts
+ * await page.bluetooth.emulateAdapter('powered-on');
+ * await page.bluetooth.simulatePreconnectedPeripheral({
+ *   address: '09:09:09:09:09:09',
+ *   name: 'SOME_NAME',
+ *   manufacturerData: [
+ *     {
+ *       key: 17,
+ *       data: 'AP8BAX8=',
+ *     },
+ *   ],
+ *   knownServiceUuids: ['12345678-1234-5678-9abc-def123456789'],
+ * });
+ * await page.bluetooth.disableEmulation();
+ * ```
+ *
+ * @experimental
+ * @public
+ */
+export interface BluetoothEmulation {
+  /**
+   * Emulate Bluetooth adapter. Required for bluetooth simulations
+   * See {@link https://webbluetoothcg.github.io/web-bluetooth/#bluetooth-simulateAdapter-command|bluetooth.simulateAdapter}.
+   *
+   * @param state - The desired bluetooth adapter state.
+   * @param leSupported - Mark if the adapter supports low-energy bluetooth.
+   *
+   * @experimental
+   * @public
+   */
+  emulateAdapter(state: AdapterState, leSupported?: boolean): Promise<void>;
+
+  /**
+   * Disable emulated bluetooth adapter.
+   * See {@link https://webbluetoothcg.github.io/web-bluetooth/#bluetooth-disableSimulation-command|bluetooth.disableSimulation}.
+   *
+   * @experimental
+   * @public
+   */
+  disableEmulation(): Promise<void>;
+
+  /**
+   * Simulated preconnected Bluetooth Peripheral.
+   * See {@link https://webbluetoothcg.github.io/web-bluetooth/#bluetooth-simulateconnectedperipheral-command|bluetooth.simulatePreconnectedPeripheral}.
+   *
+   * @param preconnectedPeripheral - The peripheral to simulate.
+   *
+   * @experimental
+   * @public
+   */
+  simulatePreconnectedPeripheral(
+    preconnectedPeripheral: PreconnectedPeripheral,
+  ): Promise<void>;
+}

package/src/api/Browser.ts

@@ -210,6 +210,95 @@ export interface DebugInfo {
   pendingProtocolErrors: Error[];
 }
 
+/**
+ * @public
+ */
+export type WindowState = 'normal' | 'minimized' | 'maximized' | 'fullscreen';
+
+/**
+ * @public
+ */
+export interface WindowBounds {
+  left?: number;
+  top?: number;
+  width?: number;
+  height?: number;
+  windowState?: WindowState;
+}
+
+/**
+ * @public
+ */
+export type WindowId = string;
+
+/**
+ * @public
+ */
+export type CreatePageOptions =
+  | {
+      type: 'tab';
+    }
+  | {
+      type: 'window';
+      windowBounds?: WindowBounds;
+    };
+
+/**
+ * @public
+ */
+export interface ScreenOrientation {
+  angle: number;
+  type: string;
+}
+
+/**
+ * @public
+ */
+export interface ScreenInfo {
+  left: number;
+  top: number;
+  width: number;
+  height: number;
+  availLeft: number;
+  availTop: number;
+  availWidth: number;
+  availHeight: number;
+  devicePixelRatio: number;
+  colorDepth: number;
+  orientation: ScreenOrientation;
+  isExtended: boolean;
+  isInternal: boolean;
+  isPrimary: boolean;
+  label: string;
+  id: string;
+}
+
+/**
+ * @public
+ */
+export interface WorkAreaInsets {
+  top?: number;
+  left?: number;
+  bottom?: number;
+  right?: number;
+}
+
+/**
+ * @public
+ */
+export interface AddScreenParams {
+  left: number;
+  top: number;
+  width: number;
+  height: number;
+  workAreaInsets?: WorkAreaInsets;
+  devicePixelRatio?: number;
+  rotation?: number;
+  colorDepth?: number;
+  label?: string;
+  isInternal?: boolean;
+}
+
 /**
  * {@link Browser} represents a browser instance that is either:
  *
@@ -324,7 +413,20 @@ export abstract class Browser extends EventEmitter<BrowserEvents> {
    * Creates a new {@link Page | page} in the
    * {@link Browser.defaultBrowserContext | default browser context}.
    */
-  abstract newPage(): Promise<Page>;
+  abstract newPage(options?: CreatePageOptions): Promise<Page>;
+
+  /**
+   * Gets the specified window {@link WindowBounds | bounds}.
+   */
+  abstract getWindowBounds(windowId: WindowId): Promise<WindowBounds>;
+
+  /**
+   * Sets the specified window {@link WindowBounds | bounds}.
+   */
+  abstract setWindowBounds(
+    windowId: WindowId,
+    windowBounds: WindowBounds,
+  ): Promise<void>;
 
   /**
    * Gets all active {@link Target | targets}.
@@ -380,13 +482,15 @@ export abstract class Browser extends EventEmitter<BrowserEvents> {
    * returns all {@link Page | pages} in all
    * {@link BrowserContext | browser contexts}.
    *
+   * @param includeAll - experimental, setting to true includes all kinds of pages.
+   *
    * @remarks Non-visible {@link Page | pages}, such as `"background_page"`,
    * will not be listed here. You can find them using {@link Target.page}.
    */
-  async pages(): Promise<Page[]> {
+  async pages(includeAll = false): Promise<Page[]> {
     const contextPages = await Promise.all(
       this.browserContexts().map(context => {
-        return context.pages();
+        return context.pages(includeAll);
       }),
     );
     // Flatten array.
@@ -495,6 +599,29 @@ export abstract class Browser extends EventEmitter<BrowserEvents> {
    */
   abstract uninstallExtension(id: string): Promise<void>;
 
+  /**
+   * Gets a list of {@link ScreenInfo | screen information objects}.
+   */
+  abstract screens(): Promise<ScreenInfo[]>;
+
+  /**
+   * Adds a new screen, returns the added {@link ScreenInfo | screen information object}.
+   *
+   * @remarks
+   *
+   * Only supported in headless mode.
+   */
+  abstract addScreen(params: AddScreenParams): Promise<ScreenInfo>;
+
+  /**
+   * Removes a screen.
+   *
+   * @remarks
+   *
+   * Only supported in headless mode. Fails if the primary screen id is specified.
+   */
+  abstract removeScreen(screenId: string): Promise<void>;
+
   /**
    * Whether Puppeteer is connected to this {@link Browser | browser}.
    *

package/src/api/BrowserContext.ts

@@ -25,7 +25,12 @@ import {
 import {asyncDisposeSymbol, disposeSymbol} from '../util/disposable.js';
 import {Mutex} from '../util/Mutex.js';
 
-import type {Browser, Permission, WaitForTargetOptions} from './Browser.js';
+import type {
+  Browser,
+  CreatePageOptions,
+  Permission,
+  WaitForTargetOptions,
+} from './Browser.js';
 import type {Page} from './Page.js';
 import type {Target} from './Target.js';
 
@@ -181,10 +186,12 @@ export abstract class BrowserContext extends EventEmitter<BrowserContextEvents>
    * Gets a list of all open {@link Page | pages} inside this
    * {@link BrowserContext | browser context}.
    *
+   * @param includeAll - experimental, setting to true includes all kinds of pages.
+   *
    * @remarks Non-visible {@link Page | pages}, such as `"background_page"`,
    * will not be listed here. You can find them using {@link Target.page}.
    */
-  abstract pages(): Promise<Page[]>;
+  abstract pages(includeAll?: boolean): Promise<Page[]>;
 
   /**
    * Grants this {@link BrowserContext | browser context} the given
@@ -230,7 +237,7 @@ export abstract class BrowserContext extends EventEmitter<BrowserContextEvents>
    * Creates a new {@link Page | page} in this
    * {@link BrowserContext | browser context}.
    */
-  abstract newPage(): Promise<Page>;
+  abstract newPage(options?: CreatePageOptions): Promise<Page>;
 
   /**
    * Gets the {@link Browser | browser} associated with this

package/src/api/CDPSession.ts

@@ -41,8 +41,7 @@ export namespace CDPSessionEvent {
  * @public
  */
 export interface CDPSessionEvents
-  extends CDPEvents,
-    Record<EventType, unknown> {
+  extends CDPEvents, Record<EventType, unknown> {
   /** @internal */
   [CDPSessionEvent.Disconnected]: undefined;
   /** @internal */

package/src/api/DeviceRequestPrompt.ts

@@ -0,0 +1,71 @@
+/**
+ * @license
+ * Copyright 2025 Google Inc.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type {WaitTimeoutOptions} from './Page.js';
+
+/**
+ * Device in a request prompt.
+ *
+ * @public
+ */
+export interface DeviceRequestPromptDevice {
+  /**
+   * Device id during a prompt.
+   */
+  id: string;
+
+  /**
+   * Device name as it appears in a prompt.
+   */
+  name: string;
+}
+
+/**
+ * Device request prompts let you respond to the page requesting for a device
+ * through an API like WebBluetooth.
+ *
+ * @remarks
+ * `DeviceRequestPrompt` instances are returned via the
+ * {@link Page.waitForDevicePrompt} method.
+ *
+ * @example
+ *
+ * ```ts
+ * const [devicePrompt] = Promise.all([
+ *   page.waitForDevicePrompt(),
+ *   page.click('#connect-bluetooth'),
+ * ]);
+ * await devicePrompt.select(
+ *   await devicePrompt.waitForDevice(({name}) => name.includes('My Device')),
+ * );
+ * ```
+ *
+ * @public
+ */
+export abstract class DeviceRequestPrompt {
+  /**
+   * Current list of selectable devices.
+   */
+  readonly devices: DeviceRequestPromptDevice[] = [];
+
+  /**
+   * Resolve to the first device in the prompt matching a filter.
+   */
+  abstract waitForDevice(
+    filter: (device: DeviceRequestPromptDevice) => boolean,
+    options?: WaitTimeoutOptions,
+  ): Promise<DeviceRequestPromptDevice>;
+
+  /**
+   * Select a device in the prompt's list.
+   */
+  abstract select(device: DeviceRequestPromptDevice): Promise<void>;
+
+  /**
+   * Cancel the prompt.
+   */
+  abstract cancel(): Promise<void>;
+}

package/src/api/ElementHandle.ts

@@ -562,10 +562,8 @@ export abstract class ElementHandle<
   async $$eval<
     Selector extends string,
     Params extends unknown[],
-    Func extends EvaluateFuncWith<
-      Array<NodeFor<Selector>>,
-      Params
-    > = EvaluateFuncWith<Array<NodeFor<Selector>>, Params>,
+    Func extends EvaluateFuncWith<Array<NodeFor<Selector>>, Params> =
+      EvaluateFuncWith<Array<NodeFor<Selector>>, Params>,
   >(
     selector: Selector,
     pageFunction: Func | string,
@@ -1521,7 +1519,7 @@ export abstract class ElementHandle<
     } = {},
   ): Promise<boolean> {
     await this.assertConnectedElement();
-    // eslint-disable-next-line rulesdir/use-using -- Returns `this`.
+    // eslint-disable-next-line @puppeteer/use-using -- Returns `this`.
     const handle = await this.#asSVGElementHandle();
     using target = handle && (await handle.#getOwnerSVGElement());
     return await ((target ?? this) as ElementHandle<Element>).evaluate(

package/src/api/Frame.ts

@@ -15,7 +15,6 @@ import type {
   WaitTimeoutOptions,
 } from '../api/Page.js';
 import type {Accessibility} from '../cdp/Accessibility.js';
-import type {DeviceRequestPrompt} from '../cdp/DeviceRequestPrompt.js';
 import type {PuppeteerLifeCycleEvent} from '../cdp/LifecycleWatcher.js';
 import {EventEmitter, type EventType} from '../common/EventEmitter.js';
 import {getQueryHandlerAndSelector} from '../common/GetQueryHandler.js';
@@ -33,6 +32,7 @@ import {assert} from '../util/assert.js';
 import {throwIfDisposed} from '../util/decorators.js';
 
 import type {CDPSession} from './CDPSession.js';
+import type {DeviceRequestPrompt} from './DeviceRequestPrompt.js';
 import type {KeyboardTypeOptions} from './Input.js';
 import {
   FunctionLocator,
@@ -557,7 +557,7 @@ export abstract class Frame extends EventEmitter<FrameEvents> {
   async $<Selector extends string>(
     selector: Selector,
   ): Promise<ElementHandle<NodeFor<Selector>> | null> {
-    // eslint-disable-next-line rulesdir/use-using -- This is cached.
+    // eslint-disable-next-line @puppeteer/use-using -- This is cached.
     const document = await this.#document();
     return await document.$(selector);
   }
@@ -589,7 +589,7 @@ export abstract class Frame extends EventEmitter<FrameEvents> {
     selector: Selector,
     options?: QueryOptions,
   ): Promise<Array<ElementHandle<NodeFor<Selector>>>> {
-    // eslint-disable-next-line rulesdir/use-using -- This is cached.
+    // eslint-disable-next-line @puppeteer/use-using -- This is cached.
     const document = await this.#document();
     return await document.$$(selector, options);
   }
@@ -642,7 +642,7 @@ export abstract class Frame extends EventEmitter<FrameEvents> {
     ...args: Params
   ): Promise<Awaited<ReturnType<Func>>> {
     pageFunction = withSourcePuppeteerURLIfNone(this.$eval.name, pageFunction);
-    // eslint-disable-next-line rulesdir/use-using -- This is cached.
+    // eslint-disable-next-line @puppeteer/use-using -- This is cached.
     const document = await this.#document();
     return await document.$eval(selector, pageFunction, ...args);
   }
@@ -685,17 +685,15 @@ export abstract class Frame extends EventEmitter<FrameEvents> {
   async $$eval<
     Selector extends string,
     Params extends unknown[],
-    Func extends EvaluateFuncWith<
-      Array<NodeFor<Selector>>,
-      Params
-    > = EvaluateFuncWith<Array<NodeFor<Selector>>, Params>,
+    Func extends EvaluateFuncWith<Array<NodeFor<Selector>>, Params> =
+      EvaluateFuncWith<Array<NodeFor<Selector>>, Params>,
   >(
     selector: Selector,
     pageFunction: string | Func,
     ...args: Params
   ): Promise<Awaited<ReturnType<Func>>> {
     pageFunction = withSourcePuppeteerURLIfNone(this.$$eval.name, pageFunction);
-    // eslint-disable-next-line rulesdir/use-using -- This is cached.
+    // eslint-disable-next-line @puppeteer/use-using -- This is cached.
     const document = await this.#document();
     return await document.$$eval(selector, pageFunction, ...args);
   }

package/src/api/HTTPRequest.ts

@@ -285,7 +285,7 @@ export abstract class HTTPRequest {
   abstract method(): string;
 
   /**
-   * The request's post body, if any.
+   * @deprecated Use {@link HTTPRequest.fetchPostData}.
    */
   abstract postData(): string | undefined;
 

package/src/api/Page.ts

@@ -32,7 +32,6 @@ import type {HTTPRequest} from '../api/HTTPRequest.js';
 import type {HTTPResponse} from '../api/HTTPResponse.js';
 import type {Accessibility} from '../cdp/Accessibility.js';
 import type {Coverage} from '../cdp/Coverage.js';
-import type {DeviceRequestPrompt} from '../cdp/DeviceRequestPrompt.js';
 import type {NetworkConditions} from '../cdp/NetworkManager.js';
 import type {Tracing} from '../cdp/Tracing.js';
 import type {ConsoleMessage} from '../common/ConsoleMessage.js';
@@ -82,9 +81,11 @@ import {
 } from '../util/disposable.js';
 import {stringToTypedArray} from '../util/encoding.js';
 
-import type {Browser} from './Browser.js';
+import type {BluetoothEmulation} from './BluetoothEmulation.js';
+import type {Browser, WindowId} from './Browser.js';
 import type {BrowserContext} from './BrowserContext.js';
 import type {CDPSession} from './CDPSession.js';
+import type {DeviceRequestPrompt} from './DeviceRequestPrompt.js';
 import type {Dialog} from './Dialog.js';
 import type {
   BoundingBox,
@@ -306,7 +307,7 @@ export interface ScreenshotOptions {
    * relative to current working directory. If no path is provided, the image
    * won't be saved to the disk.
    */
-  path?: `${string}.${ImageFormat}`;
+  path?: string;
   /**
    * Specifies the region of the page/element to clip.
    */
@@ -507,7 +508,7 @@ export const enum PageEvent {
   Metrics = 'metrics',
   /**
    * Emitted when an uncaught exception happens within the page. Contains an
-   * `Error`.
+   * `Error` or data of type unknown.
    */
   PageError = 'pageerror',
   /**
@@ -602,7 +603,7 @@ export interface PageEvents extends Record<EventType, unknown> {
   [PageEvent.FrameNavigated]: Frame;
   [PageEvent.Load]: undefined;
   [PageEvent.Metrics]: {title: string; metrics: Metrics};
-  [PageEvent.PageError]: Error;
+  [PageEvent.PageError]: Error | unknown;
   [PageEvent.Popup]: Page | null;
   [PageEvent.Request]: HTTPRequest;
   [PageEvent.Response]: HTTPResponse;
@@ -633,6 +634,19 @@ export function setDefaultScreenshotOptions(options: ScreenshotOptions): void {
   options.captureBeyondViewport ??= true;
 }
 
+/**
+ * @public
+ */
+export interface ReloadOptions extends WaitForOptions {
+  /**
+   * If set to true, the browser caches are ignored for the page reload.
+   *
+   * @defaultValue true
+   * @public
+   */
+  ignoreCache?: boolean;
+}
+
 /**
  * Page provides methods to interact with a single tab or
  * {@link https://developer.chrome.com/extensions/background_pages | extension background page}
@@ -1442,10 +1456,8 @@ export abstract class Page extends EventEmitter<PageEvents> {
   async $$eval<
     Selector extends string,
     Params extends unknown[],
-    Func extends EvaluateFuncWith<
-      Array<NodeFor<Selector>>,
-      Params
-    > = EvaluateFuncWith<Array<NodeFor<Selector>>, Params>,
+    Func extends EvaluateFuncWith<Array<NodeFor<Selector>>, Params> =
+      EvaluateFuncWith<Array<NodeFor<Selector>>, Params>,
   >(
     selector: Selector,
     pageFunction: Func | string,
@@ -1743,7 +1755,7 @@ export abstract class Page extends EventEmitter<PageEvents> {
    * multiple redirects, the navigation will resolve with the response of the
    * last redirect.
    */
-  abstract reload(options?: WaitForOptions): Promise<HTTPResponse | null>;
+  abstract reload(options?: ReloadOptions): Promise<HTTPResponse | null>;
 
   /**
    * Waits for the page to navigate to a new URL or to reload. It is useful when
@@ -2691,6 +2703,13 @@ export abstract class Page extends EventEmitter<PageEvents> {
     return typedArray;
   }
 
+  /**
+   * Emulates focus state of the page.
+   *
+   * @param enabled - Whether to emulate focus.
+   */
+  abstract emulateFocusedPage(enabled: boolean): Promise<void>;
+
   /**
    * @internal
    */
@@ -3136,7 +3155,7 @@ export abstract class Page extends EventEmitter<PageEvents> {
 
   /**
    * Resizes the browser window the page is in so that the content area
-   * (excluding browser UI) is according to the specified widht and height.
+   * (excluding browser UI) is according to the specified width and height.
    *
    * @experimental
    * @internal
@@ -3146,6 +3165,13 @@ export abstract class Page extends EventEmitter<PageEvents> {
     contentHeight: number;
   }): Promise<void>;
 
+  /**
+   * Returns the page's window id.
+   *
+   * @experimental
+   */
+  abstract windowId(): Promise<WindowId>;
+
   /** @internal */
   override [disposeSymbol](): void {
     return void this.close().catch(debugError);
@@ -3155,6 +3181,17 @@ export abstract class Page extends EventEmitter<PageEvents> {
   [asyncDisposeSymbol](): Promise<void> {
     return this.close();
   }
+
+  /**
+   * Opens DevTools for the current Page and returns the DevTools Page. This
+   * method is only available in Chrome.
+   */
+  abstract openDevTools(): Promise<Page>;
+
+  /**
+   * {@inheritDoc BluetoothEmulation}
+   */
+  abstract get bluetooth(): BluetoothEmulation;
 }
 
 /**

package/src/api/api.ts

@@ -4,9 +4,11 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+export type * from './BluetoothEmulation.js';
 export * from './Browser.js';
 export * from './BrowserContext.js';
 export * from './CDPSession.js';
+export * from './DeviceRequestPrompt.js';
 export * from './Dialog.js';
 export * from './ElementHandle.js';
 export type * from './Environment.js';

package/src/bidi/BidiOverCdp.ts

@@ -48,6 +48,7 @@ export async function connectBidiOverCdp(
   const pptrBiDiConnection = new BidiConnection(
     cdp.url(),
     pptrTransport,
+    cdp._idGenerator,
     cdp.delay,
     cdp.timeout,
   );

package/src/bidi/BluetoothEmulation.ts

@@ -0,0 +1,52 @@
+/**
+ * @license
+ * Copyright 2025 Google Inc.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type {
+  AdapterState,
+  BluetoothEmulation,
+  PreconnectedPeripheral,
+} from '../api/BluetoothEmulation.js';
+
+import type {Session} from './core/Session.js';
+
+/**
+ * @internal
+ */
+export class BidiBluetoothEmulation implements BluetoothEmulation {
+  readonly #session: Session;
+  readonly #contextId: string;
+
+  constructor(contextId: string, session: Session) {
+    this.#contextId = contextId;
+    this.#session = session;
+  }
+
+  async emulateAdapter(state: AdapterState, leSupported = true): Promise<void> {
+    await this.#session.send('bluetooth.simulateAdapter', {
+      context: this.#contextId,
+      state,
+      leSupported,
+    });
+  }
+
+  async disableEmulation(): Promise<void> {
+    await this.#session.send('bluetooth.disableSimulation', {
+      context: this.#contextId,
+    });
+  }
+
+  async simulatePreconnectedPeripheral(
+    preconnectedPeripheral: PreconnectedPeripheral,
+  ): Promise<void> {
+    await this.#session.send('bluetooth.simulatePreconnectedPeripheral', {
+      context: this.#contextId,
+      address: preconnectedPeripheral.address,
+      name: preconnectedPeripheral.name,
+      manufacturerData: preconnectedPeripheral.manufacturerData,
+      knownServiceUuids: preconnectedPeripheral.knownServiceUuids,
+    });
+  }
+}