docs: website docs for browsers (#9986)

docs/browsers-api/browsers.browser.md

@@ -0,0 +1,21 @@
+---
+sidebar_label: Browser
+---
+
+# Browser enum
+
+Supported browsers.
+
+#### Signature:
+
+```typescript
+export declare enum Browser
+```
+
+## Enumeration Members
+
+| Member   | Value                             | Description |
+| -------- | --------------------------------- | ----------- |
+| CHROME   | <code>&quot;chrome&quot;</code>   |             |
+| CHROMIUM | <code>&quot;chromium&quot;</code> |             |
+| FIREFOX  | <code>&quot;firefox&quot;</code>  |             |

docs/browsers-api/browsers.browserplatform.md

@@ -0,0 +1,23 @@
+---
+sidebar_label: BrowserPlatform
+---
+
+# BrowserPlatform enum
+
+Platform names used to identify a OS platfrom x architecture combination in the way that is relevant for the browser download.
+
+#### Signature:
+
+```typescript
+export declare enum BrowserPlatform
+```
+
+## Enumeration Members
+
+| Member  | Value                            | Description |
+| ------- | -------------------------------- | ----------- |
+| LINUX   | <code>&quot;linux&quot;</code>   |             |
+| MAC     | <code>&quot;mac&quot;</code>     |             |
+| MAC_ARM | <code>&quot;mac_arm&quot;</code> |             |
+| WIN32   | <code>&quot;win32&quot;</code>   |             |
+| WIN64   | <code>&quot;win64&quot;</code>   |             |

docs/browsers-api/browsers.candownload.md

@@ -0,0 +1,21 @@
+---
+sidebar_label: canDownload
+---
+
+# canDownload() function
+
+#### Signature:
+
+```typescript
+export declare function canDownload(options: InstallOptions): Promise<boolean>;
+```
+
+## Parameters
+
+| Parameter | Type                                           | Description |
+| --------- | ---------------------------------------------- | ----------- |
+| options   | [InstallOptions](./browsers.installoptions.md) |             |
+
+**Returns:**
+
+Promise&lt;boolean&gt;

docs/browsers-api/browsers.cdp_websocket_endpoint_regex.md

@@ -0,0 +1,11 @@
+---
+sidebar_label: CDP_WEBSOCKET_ENDPOINT_REGEX
+---
+
+# CDP_WEBSOCKET_ENDPOINT_REGEX variable
+
+#### Signature:
+
+```typescript
+CDP_WEBSOCKET_ENDPOINT_REGEX: RegExp;
+```

docs/browsers-api/browsers.chromereleasechannel.md

@@ -0,0 +1,20 @@
+---
+sidebar_label: ChromeReleaseChannel
+---
+
+# ChromeReleaseChannel enum
+
+#### Signature:
+
+```typescript
+export declare enum ChromeReleaseChannel
+```
+
+## Enumeration Members
+
+| Member | Value                           | Description |
+| ------ | ------------------------------- | ----------- |
+| BETA   | <code>&quot;beta&quot;</code>   |             |
+| CANARY | <code>&quot;canary&quot;</code> |             |
+| DEV    | <code>&quot;dev&quot;</code>    |             |
+| STABLE | <code>&quot;stable&quot;</code> |             |

docs/browsers-api/browsers.cli._constructor_.md

@@ -0,0 +1,22 @@
+---
+sidebar_label: CLI.(constructor)
+---
+
+# CLI.(constructor)
+
+Constructs a new instance of the `CLI` class
+
+#### Signature:
+
+```typescript
+class CLI {
+  constructor(cachePath?: string, rl?: readline.Interface);
+}
+```
+
+## Parameters
+
+| Parameter | Type               | Description  |
+| --------- | ------------------ | ------------ |
+| cachePath | string             | _(Optional)_ |
+| rl        | readline.Interface | _(Optional)_ |

docs/browsers-api/browsers.cli.md

@@ -0,0 +1,23 @@
+---
+sidebar_label: CLI
+---
+
+# CLI class
+
+#### Signature:
+
+```typescript
+export declare class CLI
+```
+
+## Constructors
+
+| Constructor                                                     | Modifiers | Description                                             |
+| --------------------------------------------------------------- | --------- | ------------------------------------------------------- |
+| [(constructor)(cachePath, rl)](./browsers.cli._constructor_.md) |           | Constructs a new instance of the <code>CLI</code> class |
+
+## Methods
+
+| Method                             | Modifiers | Description |
+| ---------------------------------- | --------- | ----------- |
+| [run(argv)](./browsers.cli.run.md) |           |             |

docs/browsers-api/browsers.cli.run.md

@@ -0,0 +1,23 @@
+---
+sidebar_label: CLI.run
+---
+
+# CLI.run() method
+
+#### Signature:
+
+```typescript
+class CLI {
+  run(argv: string[]): Promise<void>;
+}
+```
+
+## Parameters
+
+| Parameter | Type       | Description |
+| --------- | ---------- | ----------- |
+| argv      | string\[\] |             |
+
+**Returns:**
+
+Promise&lt;void&gt;

docs/browsers-api/browsers.computeexecutablepath.md

@@ -0,0 +1,21 @@
+---
+sidebar_label: computeExecutablePath
+---
+
+# computeExecutablePath() function
+
+#### Signature:
+
+```typescript
+export declare function computeExecutablePath(options: Options): string;
+```
+
+## Parameters
+
+| Parameter | Type                             | Description |
+| --------- | -------------------------------- | ----------- |
+| options   | [Options](./browsers.options.md) |             |
+
+**Returns:**
+
+string

docs/browsers-api/browsers.computesystemexecutablepath.md

@@ -0,0 +1,23 @@
+---
+sidebar_label: computeSystemExecutablePath
+---
+
+# computeSystemExecutablePath() function
+
+#### Signature:
+
+```typescript
+export declare function computeSystemExecutablePath(
+  options: SystemOptions
+): string;
+```
+
+## Parameters
+
+| Parameter | Type                                         | Description |
+| --------- | -------------------------------------------- | ----------- |
+| options   | [SystemOptions](./browsers.systemoptions.md) |             |
+
+**Returns:**
+
+string

docs/browsers-api/browsers.createprofile.md

@@ -0,0 +1,25 @@
+---
+sidebar_label: createProfile
+---
+
+# createProfile() function
+
+#### Signature:
+
+```typescript
+export declare function createProfile(
+  browser: Browser,
+  opts: ProfileOptions
+): Promise<void>;
+```
+
+## Parameters
+
+| Parameter | Type                                           | Description |
+| --------- | ---------------------------------------------- | ----------- |
+| browser   | [Browser](./browsers.browser.md)               |             |
+| opts      | [ProfileOptions](./browsers.profileoptions.md) |             |
+
+**Returns:**
+
+Promise&lt;void&gt;

docs/browsers-api/browsers.detectbrowserplatform.md

@@ -0,0 +1,15 @@
+---
+sidebar_label: detectBrowserPlatform
+---
+
+# detectBrowserPlatform() function
+
+#### Signature:
+
+```typescript
+export declare function detectBrowserPlatform(): BrowserPlatform | undefined;
+```
+
+**Returns:**
+
+[BrowserPlatform](./browsers.browserplatform.md) \| undefined

docs/browsers-api/browsers.install.md

@@ -0,0 +1,23 @@
+---
+sidebar_label: install
+---
+
+# install() function
+
+#### Signature:
+
+```typescript
+export declare function install(
+  options: InstallOptions
+): Promise<InstalledBrowser>;
+```
+
+## Parameters
+
+| Parameter | Type                                           | Description |
+| --------- | ---------------------------------------------- | ----------- |
+| options   | [InstallOptions](./browsers.installoptions.md) |             |
+
+**Returns:**
+
+Promise&lt;InstalledBrowser&gt;

docs/browsers-api/browsers.installoptions.md

@@ -0,0 +1,23 @@
+---
+sidebar_label: InstallOptions
+---
+
+# InstallOptions interface
+
+#### Signature:
+
+```typescript
+export interface InstallOptions
+```
+
+## Properties
+
+| Property                 | Modifiers             | Type                                                     | Description                                                                                                    | Default                                                                                                                                                     |
+| ------------------------ | --------------------- | -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| baseUrl                  | <code>optional</code> | string                                                   | Determines the host that will be used for downloading.                                                         | <p>Either</p><p>- https://storage.googleapis.com/chromium-browser-snapshots or - https://archive.mozilla.org/pub/firefox/nightly/latest-mozilla-central</p> |
+| browser                  |                       | [Browser](./browsers.browser.md)                         | Determines which browser to install.                                                                           |                                                                                                                                                             |
+| buildId                  |                       | string                                                   | Determines which buildId to dowloand. BuildId should uniquely identify binaries and they are used for caching. |                                                                                                                                                             |
+| cacheDir                 |                       | string                                                   | Determines the path to download browsers to.                                                                   |                                                                                                                                                             |
+| downloadProgressCallback | <code>optional</code> | (downloadedBytes: number, totalBytes: number) =&gt; void | Provides information about the progress of the download.                                                       |                                                                                                                                                             |
+| platform                 | <code>optional</code> | [BrowserPlatform](./browsers.browserplatform.md)         | Determines which platform the browser will be suited for.                                                      | **Auto-detected.**                                                                                                                                          |
+| unpack                   | <code>optional</code> | boolean                                                  | Whether to unpack and install browser archives.                                                                | <code>true</code>                                                                                                                                           |

docs/browsers-api/browsers.launch.md

@@ -0,0 +1,21 @@
+---
+sidebar_label: launch
+---
+
+# launch() function
+
+#### Signature:
+
+```typescript
+export declare function launch(opts: LaunchOptions): Process;
+```
+
+## Parameters
+
+| Parameter | Type                                         | Description |
+| --------- | -------------------------------------------- | ----------- |
+| opts      | [LaunchOptions](./browsers.launchoptions.md) |             |
+
+**Returns:**
+
+Process

docs/browsers-api/browsers.launchoptions.md

@@ -0,0 +1,22 @@
+---
+sidebar_label: LaunchOptions
+---
+
+# LaunchOptions type
+
+#### Signature:
+
+```typescript
+export type LaunchOptions = {
+  executablePath: string;
+  pipe?: boolean;
+  dumpio?: boolean;
+  args?: string[];
+  env?: Record<string, string | undefined>;
+  handleSIGINT?: boolean;
+  handleSIGTERM?: boolean;
+  handleSIGHUP?: boolean;
+  detached?: boolean;
+  onExit?: () => Promise<void>;
+};
+```

docs/browsers-api/browsers.makeprogresscallback.md

@@ -0,0 +1,25 @@
+---
+sidebar_label: makeProgressCallback
+---
+
+# makeProgressCallback() function
+
+#### Signature:
+
+```typescript
+export declare function makeProgressCallback(
+  browser: Browser,
+  buildId: string
+): (downloadedBytes: number, totalBytes: number) => void;
+```
+
+## Parameters
+
+| Parameter | Type                             | Description |
+| --------- | -------------------------------- | ----------- |
+| browser   | [Browser](./browsers.browser.md) |             |
+| buildId   | string                           |             |
+
+**Returns:**
+
+(downloadedBytes: number, totalBytes: number) => void

docs/browsers-api/browsers.options.md

@@ -0,0 +1,20 @@
+---
+sidebar_label: Options
+---
+
+# Options interface
+
+#### Signature:
+
+```typescript
+export interface Options
+```
+
+## Properties
+
+| Property | Modifiers             | Type                                             | Description                                                                                                    | Default            |
+| -------- | --------------------- | ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------- | ------------------ |
+| browser  |                       | [Browser](./browsers.browser.md)                 | Determines which browser to launch.                                                                            |                    |
+| buildId  |                       | string                                           | Determines which buildId to download. BuildId should uniquely identify binaries and they are used for caching. |                    |
+| cacheDir |                       | string                                           | Root path to the storage directory.                                                                            |                    |
+| platform | <code>optional</code> | [BrowserPlatform](./browsers.browserplatform.md) | Determines which platform the browser will be suited for.                                                      | **Auto-detected.** |

docs/browsers-api/browsers.profileoptions.md

@@ -0,0 +1,18 @@
+---
+sidebar_label: ProfileOptions
+---
+
+# ProfileOptions interface
+
+#### Signature:
+
+```typescript
+export interface ProfileOptions
+```
+
+## Properties
+
+| Property    | Modifiers | Type                          | Description | Default |
+| ----------- | --------- | ----------------------------- | ----------- | ------- |
+| path        |           | string                        |             |         |
+| preferences |           | Record<string, unknown> |             |         |

docs/browsers-api/browsers.resolvebuildid.md

@@ -0,0 +1,27 @@
+---
+sidebar_label: resolveBuildId
+---
+
+# resolveBuildId() function
+
+#### Signature:
+
+```typescript
+export declare function resolveBuildId(
+  browser: Browser,
+  platform: BrowserPlatform,
+  tag: string
+): Promise<string>;
+```
+
+## Parameters
+
+| Parameter | Type                                             | Description |
+| --------- | ------------------------------------------------ | ----------- |
+| browser   | [Browser](./browsers.browser.md)                 |             |
+| platform  | [BrowserPlatform](./browsers.browserplatform.md) |             |
+| tag       | string                                           |             |
+
+**Returns:**
+
+Promise&lt;string&gt;

docs/browsers-api/browsers.systemoptions.md

@@ -0,0 +1,19 @@
+---
+sidebar_label: SystemOptions
+---
+
+# SystemOptions interface
+
+#### Signature:
+
+```typescript
+export interface SystemOptions
+```
+
+## Properties
+
+| Property | Modifiers             | Type                                                       | Description                                               | Default            |
+| -------- | --------------------- | ---------------------------------------------------------- | --------------------------------------------------------- | ------------------ |
+| browser  |                       | [Browser](./browsers.browser.md)                           | Determines which browser to launch.                       |                    |
+| channel  |                       | [ChromeReleaseChannel](./browsers.chromereleasechannel.md) | Release channel to look for on the system.                |                    |
+| platform | <code>optional</code> | [BrowserPlatform](./browsers.browserplatform.md)           | Determines which platform the browser will be suited for. | **Auto-detected.** |

docs/browsers-api/browsers.timeouterror.md

@@ -0,0 +1,17 @@
+---
+sidebar_label: TimeoutError
+---
+
+# TimeoutError class
+
+#### Signature:
+
+```typescript
+export declare class TimeoutError extends Error
+```
+
+**Extends:** Error
+
+## Remarks
+
+The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `TimeoutError` class.

docs/browsers-api/browsers.webdriver_bidi_websocket_endpoint_regex.md

@@ -0,0 +1,11 @@
+---
+sidebar_label: WEBDRIVER_BIDI_WEBSOCKET_ENDPOINT_REGEX
+---
+
+# WEBDRIVER_BIDI_WEBSOCKET_ENDPOINT_REGEX variable
+
+#### Signature:
+
+```typescript
+WEBDRIVER_BIDI_WEBSOCKET_ENDPOINT_REGEX: RegExp;
+```

docs/browsers-api/index.md

@@ -0,0 +1,56 @@
+---
+sidebar_label: API
+---
+
+# API Reference
+
+## Classes
+
+| Class                                      | Description |
+| ------------------------------------------ | ----------- |
+| [CLI](./browsers.cli.md)                   |             |
+| [TimeoutError](./browsers.timeouterror.md) |             |
+
+## Enumerations
+
+| Enumeration                                                | Description                                                                                                                    |
+| ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| [Browser](./browsers.browser.md)                           | Supported browsers.                                                                                                            |
+| [BrowserPlatform](./browsers.browserplatform.md)           | Platform names used to identify a OS platfrom x architecture combination in the way that is relevant for the browser download. |
+| [ChromeReleaseChannel](./browsers.chromereleasechannel.md) |                                                                                                                                |
+
+## Functions
+
+| Function                                                                          | Description |
+| --------------------------------------------------------------------------------- | ----------- |
+| [canDownload(options)](./browsers.candownload.md)                                 |             |
+| [computeExecutablePath(options)](./browsers.computeexecutablepath.md)             |             |
+| [computeSystemExecutablePath(options)](./browsers.computesystemexecutablepath.md) |             |
+| [createProfile(browser, opts)](./browsers.createprofile.md)                       |             |
+| [detectBrowserPlatform()](./browsers.detectbrowserplatform.md)                    |             |
+| [install(options)](./browsers.install.md)                                         |             |
+| [launch(opts)](./browsers.launch.md)                                              |             |
+| [makeProgressCallback(browser, buildId)](./browsers.makeprogresscallback.md)      |             |
+| [resolveBuildId(browser, platform, tag)](./browsers.resolvebuildid.md)            |             |
+
+## Interfaces
+
+| Interface                                      | Description |
+| ---------------------------------------------- | ----------- |
+| [InstallOptions](./browsers.installoptions.md) |             |
+| [Options](./browsers.options.md)               |             |
+| [ProfileOptions](./browsers.profileoptions.md) |             |
+| [SystemOptions](./browsers.systemoptions.md)   |             |
+
+## Variables
+
+| Variable                                                                                         | Description |
+| ------------------------------------------------------------------------------------------------ | ----------- |
+| [CDP_WEBSOCKET_ENDPOINT_REGEX](./browsers.cdp_websocket_endpoint_regex.md)                       |             |
+| [WEBDRIVER_BIDI_WEBSOCKET_ENDPOINT_REGEX](./browsers.webdriver_bidi_websocket_endpoint_regex.md) |             |
+
+## Type Aliases
+
+| Type Alias                                   | Description |
+| -------------------------------------------- | ----------- |
+| [LaunchOptions](./browsers.launchoptions.md) |             |

package.json

@@ -53,6 +53,7 @@
     },
     "build:docs": {
       "dependencies": [
+        "./packages/browsers:build:docs",
         "./packages/puppeteer:build:docs",
         "./packages/puppeteer-core:build:docs"
       ]

packages/browsers/api-extractor.docs.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
+  "mainEntryPointFilePath": "<projectFolder>/lib/esm/main.d.ts",
+
+  "extends": "./api-extractor.json",
+
+  "dtsRollup": {
+    "enabled": false
+  },
+
+  "docModel": {
+    "enabled": true,
+    "apiJsonFilePath": "<projectFolder>/../../docs/<unscopedPackageName>.api.json"
+  }
+}

packages/browsers/api-extractor.json

@@ -0,0 +1,40 @@
+{
+  "$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
+  "mainEntryPointFilePath": "<projectFolder>/lib/esm/main.d.ts",
+  "bundledPackages": [],
+
+  "apiReport": {
+    "enabled": false
+  },
+
+  "docModel": {
+    "enabled": false
+  },
+
+  "tsdocMetadata": {
+    "enabled": false
+  },
+
+  "messages": {
+    "compilerMessageReporting": {
+      "default": {
+        "logLevel": "warning"
+      }
+    },
+
+    "extractorMessageReporting": {
+      "ae-internal-missing-underscore": {
+        "logLevel": "none"
+      },
+      "default": {
+        "logLevel": "warning"
+      }
+    },
+
+    "tsdocMessageReporting": {
+      "default": {
+        "logLevel": "warning"
+      }
+    }
+  }
+}

packages/browsers/package.json

@@ -3,6 +3,7 @@
   "version": "0.3.2",
   "description": "Download and launch browsers",
   "scripts": {
+    "build:docs": "wireit",
     "build": "wireit",
     "build:test": "wireit",
     "clean": "tsc --build --clean && rm -rf lib",
@@ -45,6 +46,17 @@
         "lib/esm/package.json"
       ]
     },
+    "build:docs": {
+      "command": "api-extractor run --local --config \"./api-extractor.docs.json\"",
+      "files": [
+        "api-extractor.docs.json",
+        "lib/esm/main.d.ts",
+        "tsconfig.json"
+      ],
+      "dependencies": [
+        "build"
+      ]
+    },
     "build:test": {
       "command": "tsc -b test/src/tsconfig.json",
       "files": [

packages/browsers/src/browser-data/browser-data.ts

@@ -25,6 +25,8 @@ import {
   ProfileOptions,
 } from './types.js';
 
+export {ProfileOptions};
+
 export const downloadUrls = {
   [Browser.CHROME]: chrome.resolveDownloadUrl,
   [Browser.CHROMIUM]: chromium.resolveDownloadUrl,

packages/browsers/src/install.ts

@@ -52,7 +52,7 @@ function debugTimeEnd(label: string) {
 /**
  * @public
  */
-export interface Options {
+export interface InstallOptions {
   /**
    * Determines the path to download browsers to.
    */
@@ -104,7 +104,9 @@ export type InstalledBrowser = {
   platform: BrowserPlatform;
 };
 
-export async function install(options: Options): Promise<InstalledBrowser> {
+export async function install(
+  options: InstallOptions
+): Promise<InstalledBrowser> {
   options.platform ??= detectBrowserPlatform();
   options.unpack ??= true;
   if (!options.platform) {
@@ -192,7 +194,7 @@ export async function install(options: Options): Promise<InstalledBrowser> {
   };
 }
 
-export async function canDownload(options: Options): Promise<boolean> {
+export async function canDownload(options: InstallOptions): Promise<boolean> {
   options.platform ??= detectBrowserPlatform();
   if (!options.platform) {
     throw new Error(

packages/browsers/src/launch.ts

@@ -117,7 +117,7 @@ export function computeSystemExecutablePath(options: SystemOptions): string {
   return path;
 }
 
-type LaunchOptions = {
+export type LaunchOptions = {
   executablePath: string;
   pipe?: boolean;
   dumpio?: boolean;

packages/browsers/src/main.ts

@@ -19,10 +19,13 @@ export {
   computeExecutablePath,
   computeSystemExecutablePath,
   TimeoutError,
+  LaunchOptions,
+  Options,
+  SystemOptions,
   CDP_WEBSOCKET_ENDPOINT_REGEX,
   WEBDRIVER_BIDI_WEBSOCKET_ENDPOINT_REGEX,
 } from './launch.js';
-export {install, canDownload} from './install.js';
+export {install, canDownload, InstallOptions} from './install.js';
 export {detectBrowserPlatform} from './detectPlatform.js';
 export {
   resolveBuildId,
@@ -30,6 +33,7 @@ export {
   BrowserPlatform,
   ChromeReleaseChannel,
   createProfile,
+  ProfileOptions,
 } from './browser-data/browser-data.js';
 export {CLI, makeProgressCallback} from './CLI.js';
 export {Cache} from './Cache.js';

tools/generate_docs.ts

@@ -118,4 +118,16 @@ function spliceIntoSection(
     ])
     .outputs(['docs/api'])
     .build();
+
+  job('', async ({inputs, outputs}) => {
+    await rm(outputs[0]!, {recursive: true, force: true});
+    generateDocs(inputs[0]!, outputs[0]!);
+    spawnAndLog('prettier', '--ignore-path', 'none', '--write', 'docs');
+  })
+    .inputs([
+      'docs/browsers.api.json',
+      'tools/internal/custom_markdown_documenter.ts',
+    ])
+    .outputs(['docs/browsers-api'])
+    .build();
 })();

website/docusaurus.config.js

@@ -92,12 +92,6 @@ const config = {
         docs: {
           async sidebarItemsGenerator({defaultSidebarItemsGenerator, ...args}) {
             const sidebarItems = await defaultSidebarItemsGenerator(args);
-            const apiItem = sidebarItems.find(value => {
-              return value.type === 'doc' && value.label === 'API';
-            });
-            if (!apiItem) {
-              return sidebarItems;
-            }
 
             /** @type {typeof sidebarItems} */
             const apiSidebarItems = [];
@@ -112,6 +106,67 @@ const config = {
               }
             }
 
+            function addNamespace(namespace, target) {
+              let items = categories.get(namespace);
+              if (!items) {
+                throw new Error(`Namespace ${namespace} not found`);
+              }
+              items.sort((a, b) => {
+                return a.label.localeCompare(b.label);
+              });
+              const main = items.find(item => {
+                return item.label === namespace;
+              });
+              items = items.filter(item => {
+                return item !== main;
+              });
+              target.push({
+                type: 'category',
+                label: namespace,
+                items,
+                link: main
+                  ? {
+                      type: 'doc',
+                      id: main.id,
+                    }
+                  : undefined,
+              });
+              categories.delete(namespace);
+            }
+
+            if (args.item.dirName === 'browsers-api') {
+              const order = [
+                'launch',
+                'install',
+                'canDownload',
+                'createProfile',
+                'computeExecutablePath',
+                'computeSystemExecutablePath',
+                'detectBrowserPlatform',
+                'resolveBuildId',
+                'BrowserPlatform',
+                'Browser',
+                'CLI',
+              ];
+              const apiItem = sidebarItems.find(value => {
+                return value.type === 'doc' && value.label === 'API';
+              });
+              apiSidebarItems.push({
+                type: 'category',
+                label: 'API',
+                items: [],
+                link: apiItem
+                  ? {
+                      type: 'doc',
+                      id: apiItem.id,
+                    }
+                  : undefined,
+              });
+              const container = apiSidebarItems[apiSidebarItems.length - 1];
+              for (const namespace of order) {
+                addNamespace(namespace, container.items);
+              }
+            } else {
               const order = [
                 // PuppeteerNode and Puppeteer go first as the entrypoints into
                 // the Puppeteer API.
@@ -143,37 +198,10 @@ const config = {
                 'EventEmitter',
               ];
 
-            function addNamespace(namespace, target) {
-              let items = categories.get(namespace);
-              if (!items) {
-                throw new Error(`Namespace ${namespace} not found`);
-              }
-              items.sort((a, b) => {
-                return a.label.localeCompare(b.label);
-              });
-              const main = items.find(item => {
-                return item.label === namespace;
-              });
-              items = items.filter(item => {
-                return item !== main;
-              });
-              target.push({
-                type: 'category',
-                label: namespace,
-                items,
-                link: main
-                  ? {
-                      type: 'doc',
-                      id: main.id,
-                    }
-                  : undefined,
-              });
-              categories.delete(namespace);
-            }
-
               for (const namespace of order) {
                 addNamespace(namespace, apiSidebarItems);
               }
+            }
             const otherItems = [];
             apiSidebarItems.push({
               type: 'category',
@@ -186,6 +214,9 @@ const config = {
               return a.localeCompare(b);
             });
             for (const namespace of remaining) {
+              if (namespace === 'API') {
+                continue;
+              }
               addNamespace(namespace, otherItems);
             }
             return apiSidebarItems;
@@ -224,7 +255,12 @@ const config = {
             {
               type: 'docSidebar',
               sidebarId: 'api',
-              label: 'API',
+              label: 'Puppeteer API',
+            },
+            {
+              type: 'docSidebar',
+              sidebarId: 'browsersApi',
+              label: '@puppeteer/browsers API',
             },
           ].map(item => {
             return Object.assign(item, {position: 'left'});

website/sidebars.js

@@ -32,4 +32,10 @@ module.exports = {
       dirName: 'api',
     },
   ],
+  browsersApi: [
+    {
+      type: 'autogenerated',
+      dirName: 'browsers-api',
+    },
+  ],
 };

website/versioned_docs/version-19.8.3/browsers-api/browsers.browser.md

@@ -0,0 +1,21 @@
+---
+sidebar_label: Browser
+---
+
+# Browser enum
+
+Supported browsers.
+
+#### Signature:
+
+```typescript
+export declare enum Browser
+```
+
+## Enumeration Members
+
+| Member   | Value                             | Description |
+| -------- | --------------------------------- | ----------- |
+| CHROME   | <code>&quot;chrome&quot;</code>   |             |
+| CHROMIUM | <code>&quot;chromium&quot;</code> |             |
+| FIREFOX  | <code>&quot;firefox&quot;</code>  |             |

website/versioned_docs/version-19.8.3/browsers-api/browsers.browserplatform.md

@@ -0,0 +1,23 @@
+---
+sidebar_label: BrowserPlatform
+---
+
+# BrowserPlatform enum
+
+Platform names used to identify a OS platfrom x architecture combination in the way that is relevant for the browser download.
+
+#### Signature:
+
+```typescript
+export declare enum BrowserPlatform
+```
+
+## Enumeration Members
+
+| Member  | Value                            | Description |
+| ------- | -------------------------------- | ----------- |
+| LINUX   | <code>&quot;linux&quot;</code>   |             |
+| MAC     | <code>&quot;mac&quot;</code>     |             |
+| MAC_ARM | <code>&quot;mac_arm&quot;</code> |             |
+| WIN32   | <code>&quot;win32&quot;</code>   |             |
+| WIN64   | <code>&quot;win64&quot;</code>   |             |

website/versioned_docs/version-19.8.3/browsers-api/browsers.candownload.md

@@ -0,0 +1,21 @@
+---
+sidebar_label: canDownload
+---
+
+# canDownload() function
+
+#### Signature:
+
+```typescript
+export declare function canDownload(options: InstallOptions): Promise<boolean>;
+```
+
+## Parameters
+
+| Parameter | Type                                           | Description |
+| --------- | ---------------------------------------------- | ----------- |
+| options   | [InstallOptions](./browsers.installoptions.md) |             |
+
+**Returns:**
+
+Promise&lt;boolean&gt;

website/versioned_docs/version-19.8.3/browsers-api/browsers.cdp_websocket_endpoint_regex.md

@@ -0,0 +1,11 @@
+---
+sidebar_label: CDP_WEBSOCKET_ENDPOINT_REGEX
+---
+
+# CDP_WEBSOCKET_ENDPOINT_REGEX variable
+
+#### Signature:
+
+```typescript
+CDP_WEBSOCKET_ENDPOINT_REGEX: RegExp;
+```

website/versioned_docs/version-19.8.3/browsers-api/browsers.chromereleasechannel.md

@@ -0,0 +1,20 @@
+---
+sidebar_label: ChromeReleaseChannel
+---
+
+# ChromeReleaseChannel enum
+
+#### Signature:
+
+```typescript
+export declare enum ChromeReleaseChannel
+```
+
+## Enumeration Members
+
+| Member | Value                           | Description |
+| ------ | ------------------------------- | ----------- |
+| BETA   | <code>&quot;beta&quot;</code>   |             |
+| CANARY | <code>&quot;canary&quot;</code> |             |
+| DEV    | <code>&quot;dev&quot;</code>    |             |
+| STABLE | <code>&quot;stable&quot;</code> |             |

website/versioned_docs/version-19.8.3/browsers-api/browsers.cli._constructor_.md

@@ -0,0 +1,22 @@
+---
+sidebar_label: CLI.(constructor)
+---
+
+# CLI.(constructor)
+
+Constructs a new instance of the `CLI` class
+
+#### Signature:
+
+```typescript
+class CLI {
+  constructor(cachePath?: string, rl?: readline.Interface);
+}
+```
+
+## Parameters
+
+| Parameter | Type               | Description  |
+| --------- | ------------------ | ------------ |
+| cachePath | string             | _(Optional)_ |
+| rl        | readline.Interface | _(Optional)_ |

website/versioned_docs/version-19.8.3/browsers-api/browsers.cli.md

@@ -0,0 +1,23 @@
+---
+sidebar_label: CLI
+---
+
+# CLI class
+
+#### Signature:
+
+```typescript
+export declare class CLI
+```
+
+## Constructors
+
+| Constructor                                                     | Modifiers | Description                                             |
+| --------------------------------------------------------------- | --------- | ------------------------------------------------------- |
+| [(constructor)(cachePath, rl)](./browsers.cli._constructor_.md) |           | Constructs a new instance of the <code>CLI</code> class |
+
+## Methods
+
+| Method                             | Modifiers | Description |
+| ---------------------------------- | --------- | ----------- |
+| [run(argv)](./browsers.cli.run.md) |           |             |

website/versioned_docs/version-19.8.3/browsers-api/browsers.cli.run.md

@@ -0,0 +1,23 @@
+---
+sidebar_label: CLI.run
+---
+
+# CLI.run() method
+
+#### Signature:
+
+```typescript
+class CLI {
+  run(argv: string[]): Promise<void>;
+}
+```
+
+## Parameters
+
+| Parameter | Type       | Description |
+| --------- | ---------- | ----------- |
+| argv      | string\[\] |             |
+
+**Returns:**
+
+Promise&lt;void&gt;

website/versioned_docs/version-19.8.3/browsers-api/browsers.computeexecutablepath.md

@@ -0,0 +1,21 @@
+---
+sidebar_label: computeExecutablePath
+---
+
+# computeExecutablePath() function
+
+#### Signature:
+
+```typescript
+export declare function computeExecutablePath(options: Options): string;
+```
+
+## Parameters
+
+| Parameter | Type                             | Description |
+| --------- | -------------------------------- | ----------- |
+| options   | [Options](./browsers.options.md) |             |
+
+**Returns:**
+
+string

website/versioned_docs/version-19.8.3/browsers-api/browsers.computesystemexecutablepath.md

@@ -0,0 +1,23 @@
+---
+sidebar_label: computeSystemExecutablePath
+---
+
+# computeSystemExecutablePath() function
+
+#### Signature:
+
+```typescript
+export declare function computeSystemExecutablePath(
+  options: SystemOptions
+): string;
+```
+
+## Parameters
+
+| Parameter | Type                                         | Description |
+| --------- | -------------------------------------------- | ----------- |
+| options   | [SystemOptions](./browsers.systemoptions.md) |             |
+
+**Returns:**
+
+string

website/versioned_docs/version-19.8.3/browsers-api/browsers.createprofile.md

@@ -0,0 +1,25 @@
+---
+sidebar_label: createProfile
+---
+
+# createProfile() function
+
+#### Signature:
+
+```typescript
+export declare function createProfile(
+  browser: Browser,
+  opts: ProfileOptions
+): Promise<void>;
+```
+
+## Parameters
+
+| Parameter | Type                                           | Description |
+| --------- | ---------------------------------------------- | ----------- |
+| browser   | [Browser](./browsers.browser.md)               |             |
+| opts      | [ProfileOptions](./browsers.profileoptions.md) |             |
+
+**Returns:**
+
+Promise&lt;void&gt;

website/versioned_docs/version-19.8.3/browsers-api/browsers.detectbrowserplatform.md

@@ -0,0 +1,15 @@
+---
+sidebar_label: detectBrowserPlatform
+---
+
+# detectBrowserPlatform() function
+
+#### Signature:
+
+```typescript
+export declare function detectBrowserPlatform(): BrowserPlatform | undefined;
+```
+
+**Returns:**
+
+[BrowserPlatform](./browsers.browserplatform.md) \| undefined

website/versioned_docs/version-19.8.3/browsers-api/browsers.install.md

@@ -0,0 +1,23 @@
+---
+sidebar_label: install
+---
+
+# install() function
+
+#### Signature:
+
+```typescript
+export declare function install(
+  options: InstallOptions
+): Promise<InstalledBrowser>;
+```
+
+## Parameters
+
+| Parameter | Type                                           | Description |
+| --------- | ---------------------------------------------- | ----------- |
+| options   | [InstallOptions](./browsers.installoptions.md) |             |
+
+**Returns:**
+
+Promise&lt;InstalledBrowser&gt;

website/versioned_docs/version-19.8.3/browsers-api/browsers.installoptions.md

@@ -0,0 +1,23 @@
+---
+sidebar_label: InstallOptions
+---
+
+# InstallOptions interface
+
+#### Signature:
+
+```typescript
+export interface InstallOptions
+```
+
+## Properties
+
+| Property                 | Modifiers             | Type                                                     | Description                                                                                                    | Default                                                                                                                                                     |
+| ------------------------ | --------------------- | -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| baseUrl                  | <code>optional</code> | string                                                   | Determines the host that will be used for downloading.                                                         | <p>Either</p><p>- https://storage.googleapis.com/chromium-browser-snapshots or - https://archive.mozilla.org/pub/firefox/nightly/latest-mozilla-central</p> |
+| browser                  |                       | [Browser](./browsers.browser.md)                         | Determines which browser to install.                                                                           |                                                                                                                                                             |
+| buildId                  |                       | string                                                   | Determines which buildId to dowloand. BuildId should uniquely identify binaries and they are used for caching. |                                                                                                                                                             |
+| cacheDir                 |                       | string                                                   | Determines the path to download browsers to.                                                                   |                                                                                                                                                             |
+| downloadProgressCallback | <code>optional</code> | (downloadedBytes: number, totalBytes: number) =&gt; void | Provides information about the progress of the download.                                                       |                                                                                                                                                             |
+| platform                 | <code>optional</code> | [BrowserPlatform](./browsers.browserplatform.md)         | Determines which platform the browser will be suited for.                                                      | **Auto-detected.**                                                                                                                                          |
+| unpack                   | <code>optional</code> | boolean                                                  | Whether to unpack and install browser archives.                                                                | <code>true</code>                                                                                                                                           |

website/versioned_docs/version-19.8.3/browsers-api/browsers.launch.md

@@ -0,0 +1,21 @@
+---
+sidebar_label: launch
+---
+
+# launch() function
+
+#### Signature:
+
+```typescript
+export declare function launch(opts: LaunchOptions): Process;
+```
+
+## Parameters
+
+| Parameter | Type                                         | Description |
+| --------- | -------------------------------------------- | ----------- |
+| opts      | [LaunchOptions](./browsers.launchoptions.md) |             |
+
+**Returns:**
+
+Process

website/versioned_docs/version-19.8.3/browsers-api/browsers.launchoptions.md

@@ -0,0 +1,22 @@
+---
+sidebar_label: LaunchOptions
+---
+
+# LaunchOptions type
+
+#### Signature:
+
+```typescript
+export type LaunchOptions = {
+  executablePath: string;
+  pipe?: boolean;
+  dumpio?: boolean;
+  args?: string[];
+  env?: Record<string, string | undefined>;
+  handleSIGINT?: boolean;
+  handleSIGTERM?: boolean;
+  handleSIGHUP?: boolean;
+  detached?: boolean;
+  onExit?: () => Promise<void>;
+};
+```

website/versioned_docs/version-19.8.3/browsers-api/browsers.makeprogresscallback.md

@@ -0,0 +1,25 @@
+---
+sidebar_label: makeProgressCallback
+---
+
+# makeProgressCallback() function
+
+#### Signature:
+
+```typescript
+export declare function makeProgressCallback(
+  browser: Browser,
+  buildId: string
+): (downloadedBytes: number, totalBytes: number) => void;
+```
+
+## Parameters
+
+| Parameter | Type                             | Description |
+| --------- | -------------------------------- | ----------- |
+| browser   | [Browser](./browsers.browser.md) |             |
+| buildId   | string                           |             |
+
+**Returns:**
+
+(downloadedBytes: number, totalBytes: number) => void

website/versioned_docs/version-19.8.3/browsers-api/browsers.options.md

@@ -0,0 +1,20 @@
+---
+sidebar_label: Options
+---
+
+# Options interface
+
+#### Signature:
+
+```typescript
+export interface Options
+```
+
+## Properties
+
+| Property | Modifiers             | Type                                             | Description                                                                                                    | Default            |
+| -------- | --------------------- | ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------- | ------------------ |
+| browser  |                       | [Browser](./browsers.browser.md)                 | Determines which browser to launch.                                                                            |                    |
+| buildId  |                       | string                                           | Determines which buildId to download. BuildId should uniquely identify binaries and they are used for caching. |                    |
+| cacheDir |                       | string                                           | Root path to the storage directory.                                                                            |                    |
+| platform | <code>optional</code> | [BrowserPlatform](./browsers.browserplatform.md) | Determines which platform the browser will be suited for.                                                      | **Auto-detected.** |

website/versioned_docs/version-19.8.3/browsers-api/browsers.profileoptions.md

@@ -0,0 +1,18 @@
+---
+sidebar_label: ProfileOptions
+---
+
+# ProfileOptions interface
+
+#### Signature:
+
+```typescript
+export interface ProfileOptions
+```
+
+## Properties
+
+| Property    | Modifiers | Type                          | Description | Default |
+| ----------- | --------- | ----------------------------- | ----------- | ------- |
+| path        |           | string                        |             |         |
+| preferences |           | Record<string, unknown> |             |         |

website/versioned_docs/version-19.8.3/browsers-api/browsers.resolvebuildid.md

@@ -0,0 +1,27 @@
+---
+sidebar_label: resolveBuildId
+---
+
+# resolveBuildId() function
+
+#### Signature:
+
+```typescript
+export declare function resolveBuildId(
+  browser: Browser,
+  platform: BrowserPlatform,
+  tag: string
+): Promise<string>;
+```
+
+## Parameters
+
+| Parameter | Type                                             | Description |
+| --------- | ------------------------------------------------ | ----------- |
+| browser   | [Browser](./browsers.browser.md)                 |             |
+| platform  | [BrowserPlatform](./browsers.browserplatform.md) |             |
+| tag       | string                                           |             |
+
+**Returns:**
+
+Promise&lt;string&gt;

website/versioned_docs/version-19.8.3/browsers-api/browsers.systemoptions.md

@@ -0,0 +1,19 @@
+---
+sidebar_label: SystemOptions
+---
+
+# SystemOptions interface
+
+#### Signature:
+
+```typescript
+export interface SystemOptions
+```
+
+## Properties
+
+| Property | Modifiers             | Type                                                       | Description                                               | Default            |
+| -------- | --------------------- | ---------------------------------------------------------- | --------------------------------------------------------- | ------------------ |
+| browser  |                       | [Browser](./browsers.browser.md)                           | Determines which browser to launch.                       |                    |
+| channel  |                       | [ChromeReleaseChannel](./browsers.chromereleasechannel.md) | Release channel to look for on the system.                |                    |
+| platform | <code>optional</code> | [BrowserPlatform](./browsers.browserplatform.md)           | Determines which platform the browser will be suited for. | **Auto-detected.** |

website/versioned_docs/version-19.8.3/browsers-api/browsers.timeouterror.md

@@ -0,0 +1,17 @@
+---
+sidebar_label: TimeoutError
+---
+
+# TimeoutError class
+
+#### Signature:
+
+```typescript
+export declare class TimeoutError extends Error
+```
+
+**Extends:** Error
+
+## Remarks
+
+The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `TimeoutError` class.

website/versioned_docs/version-19.8.3/browsers-api/browsers.webdriver_bidi_websocket_endpoint_regex.md

@@ -0,0 +1,11 @@
+---
+sidebar_label: WEBDRIVER_BIDI_WEBSOCKET_ENDPOINT_REGEX
+---
+
+# WEBDRIVER_BIDI_WEBSOCKET_ENDPOINT_REGEX variable
+
+#### Signature:
+
+```typescript
+WEBDRIVER_BIDI_WEBSOCKET_ENDPOINT_REGEX: RegExp;
+```

website/versioned_docs/version-19.8.3/browsers-api/index.md

@@ -0,0 +1,56 @@
+---
+sidebar_label: API
+---
+
+# API Reference
+
+## Classes
+
+| Class                                      | Description |
+| ------------------------------------------ | ----------- |
+| [CLI](./browsers.cli.md)                   |             |
+| [TimeoutError](./browsers.timeouterror.md) |             |
+
+## Enumerations
+
+| Enumeration                                                | Description                                                                                                                    |
+| ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| [Browser](./browsers.browser.md)                           | Supported browsers.                                                                                                            |
+| [BrowserPlatform](./browsers.browserplatform.md)           | Platform names used to identify a OS platfrom x architecture combination in the way that is relevant for the browser download. |
+| [ChromeReleaseChannel](./browsers.chromereleasechannel.md) |                                                                                                                                |
+
+## Functions
+
+| Function                                                                          | Description |
+| --------------------------------------------------------------------------------- | ----------- |
+| [canDownload(options)](./browsers.candownload.md)                                 |             |
+| [computeExecutablePath(options)](./browsers.computeexecutablepath.md)             |             |
+| [computeSystemExecutablePath(options)](./browsers.computesystemexecutablepath.md) |             |
+| [createProfile(browser, opts)](./browsers.createprofile.md)                       |             |
+| [detectBrowserPlatform()](./browsers.detectbrowserplatform.md)                    |             |
+| [install(options)](./browsers.install.md)                                         |             |
+| [launch(opts)](./browsers.launch.md)                                              |             |
+| [makeProgressCallback(browser, buildId)](./browsers.makeprogresscallback.md)      |             |
+| [resolveBuildId(browser, platform, tag)](./browsers.resolvebuildid.md)            |             |
+
+## Interfaces
+
+| Interface                                      | Description |
+| ---------------------------------------------- | ----------- |
+| [InstallOptions](./browsers.installoptions.md) |             |
+| [Options](./browsers.options.md)               |             |
+| [ProfileOptions](./browsers.profileoptions.md) |             |
+| [SystemOptions](./browsers.systemoptions.md)   |             |
+
+## Variables
+
+| Variable                                                                                         | Description |
+| ------------------------------------------------------------------------------------------------ | ----------- |
+| [CDP_WEBSOCKET_ENDPOINT_REGEX](./browsers.cdp_websocket_endpoint_regex.md)                       |             |
+| [WEBDRIVER_BIDI_WEBSOCKET_ENDPOINT_REGEX](./browsers.webdriver_bidi_websocket_endpoint_regex.md) |             |
+
+## Type Aliases
+
+| Type Alias                                   | Description |
+| -------------------------------------------- | ----------- |
+| [LaunchOptions](./browsers.launchoptions.md) |             |

website/versioned_sidebars/version-19.8.3-sidebars.json

@@ -32,5 +32,11 @@
       "type": "autogenerated",
       "dirName": "api"
     }
+  ],
+  "browsersApi": [
+    {
+      "type": "autogenerated",
+      "dirName": "browsers-api"
+    }
   ]
 }