brave-real-puppeteer-core 24.26.1 → 24.33.0

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,

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,
@@ -685,10 +685,8 @@ 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,

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.
    */
@@ -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,
+    });
+  }
+}

package/src/bidi/Browser.ts

@@ -14,6 +14,10 @@ import {
   BrowserEvent,
   type BrowserCloseCallback,
   type BrowserContextOptions,
+  type ScreenInfo,
+  type AddScreenParams,
+  type WindowBounds,
+  type WindowId,
   type DebugInfo,
 } from '../api/Browser.js';
 import {BrowserContextEvent} from '../api/BrowserContext.js';
@@ -22,6 +26,7 @@ import type {Target} from '../api/Target.js';
 import type {Connection as CdpConnection} from '../cdp/Connection.js';
 import type {SupportedWebDriverCapabilities} from '../common/ConnectOptions.js';
 import {ProtocolError} from '../common/Errors.js';
+import {UnsupportedOperation} from '../common/Errors.js';
 import {EventEmitter} from '../common/EventEmitter.js';
 import {debugError} from '../common/util.js';
 import type {Viewport} from '../common/Viewport.js';
@@ -289,6 +294,29 @@ export class BidiBrowser extends Browser {
     await this.#browserCore.uninstallExtension(id);
   }
 
+  override screens(): Promise<ScreenInfo[]> {
+    throw new UnsupportedOperation();
+  }
+
+  override addScreen(_params: AddScreenParams): Promise<ScreenInfo> {
+    throw new UnsupportedOperation();
+  }
+
+  override removeScreen(_screenId: string): Promise<void> {
+    throw new UnsupportedOperation();
+  }
+
+  override getWindowBounds(_windowId: WindowId): Promise<WindowBounds> {
+    throw new UnsupportedOperation();
+  }
+
+  override setWindowBounds(
+    _windowId: WindowId,
+    _windowBounds: WindowBounds,
+  ): Promise<void> {
+    throw new UnsupportedOperation();
+  }
+
   override targets(): Target[] {
     return [
       this.#target,