@crawlee/browser-pool 4.0.0-beta.223 → 4.0.0-beta.224

package/abstract-classes/browser-plugin.d.ts

@@ -2,8 +2,7 @@ import { type CrawleeLogger, CriticalError } from '@crawlee/core';
 import type { Dictionary } from '@crawlee/types';
 import type { LaunchContextOptions } from '../launch-context.js';
 import { LaunchContext } from '../launch-context.js';
-import type { RemoteConnection, RemoteConnectionParameters } from '../remote-browser-pool.js';
-import { type UnwrapPromise } from '../utils.js';
+import type { UnwrapPromise } from '../utils.js';
 import type { BrowserController } from './browser-controller.js';
 /**
  * The default User Agent used by `PlaywrightCrawler`, `launchPlaywright`, 'PuppeteerCrawler' and 'launchPuppeteer'
@@ -97,34 +96,7 @@ export declare abstract class BrowserPlugin<Library extends CommonLibrary = Comm
     useIncognitoPages: boolean;
     readonly browserPerProxy?: boolean;
     readonly ignoreProxyCertificate?: boolean;
-    /**
-     * Set by {@link RemoteBrowserPool} when this plugin connects to a remote browser service instead of
-     * launching locally. Holds the bridge the plugin uses to resolve endpoints and release sessions; all
-     * remote-session policy lives in the pool, not here.
-     *
-     * @internal
-     */
-    remoteConnection?: RemoteConnection;
-    /** Static connect() parameters for a remote connection (protocol, headers, …). @internal */
-    remoteConnectionParameters?: RemoteConnectionParameters;
     constructor(library: Library, options?: BrowserPluginOptions<LibraryOptions>);
-    /**
-     * Configures this plugin to connect to a remote browser using the given {@link RemoteConnection}.
-     * Called by {@link RemoteBrowserPool}; subclasses may override to apply library-specific defaults
-     * (e.g. forcing incognito pages).
-     *
-     * @internal
-     */
-    useRemoteConnection(connection: RemoteConnection, parameters?: RemoteConnectionParameters): void;
-    /**
-     * Resolves a remote endpoint via the injected {@link RemoteConnection}, stores the session token on
-     * the launch context (so the controller can release it on close), and runs the library-specific `connect`.
-     * On failure the session is released and the error is wrapped in a {@link BrowserLaunchError}.
-     *
-     * Subclasses implement only the `connect` callback — the resolve / token / release / error-wrap scaffolding
-     * lives here so it stays identical across plugins.
-     */
-    protected connectToRemoteBrowser(launchContext: LaunchContext<Library, LibraryOptions, LaunchResult, NewPageOptions, NewPageResult>, connect: (url: string) => Promise<LaunchResult>): Promise<LaunchResult>;
     /**
      * Creates a `LaunchContext` with all the information needed
      * to launch a browser. Aside from library specific launch options,

package/abstract-classes/browser-plugin.js

@@ -1,7 +1,6 @@
 import { CriticalError, serviceLocator } from '@crawlee/core';
 import merge from 'lodash.merge';
 import { LaunchContext } from '../launch-context.js';
-import { sanitizeEndpointForLog } from '../utils.js';
 /**
  * The default User Agent used by `PlaywrightCrawler`, `launchPlaywright`, 'PuppeteerCrawler' and 'launchPuppeteer'
  * when Chromium/Chrome browser is launched:
@@ -33,16 +32,6 @@ export class BrowserPlugin {
     useIncognitoPages;
     browserPerProxy;
     ignoreProxyCertificate;
-    /**
-     * Set by {@link RemoteBrowserPool} when this plugin connects to a remote browser service instead of
-     * launching locally. Holds the bridge the plugin uses to resolve endpoints and release sessions; all
-     * remote-session policy lives in the pool, not here.
-     *
-     * @internal
-     */
-    remoteConnection;
-    /** Static connect() parameters for a remote connection (protocol, headers, …). @internal */
-    remoteConnectionParameters;
     constructor(library, options = {}) {
         const { launchOptions = {}, proxyUrl, userDataDir, useIncognitoPages = false, browserPerProxy = false, ignoreProxyCertificate = false, } = options;
         this.log = serviceLocator.getLogger().child({ prefix: 'BrowserPool' });
@@ -54,45 +43,6 @@ export class BrowserPlugin {
         this.browserPerProxy = browserPerProxy;
         this.ignoreProxyCertificate = ignoreProxyCertificate;
     }
-    /**
-     * Configures this plugin to connect to a remote browser using the given {@link RemoteConnection}.
-     * Called by {@link RemoteBrowserPool}; subclasses may override to apply library-specific defaults
-     * (e.g. forcing incognito pages).
-     *
-     * @internal
-     */
-    useRemoteConnection(connection, parameters = {}) {
-        this.remoteConnection = connection;
-        this.remoteConnectionParameters = parameters;
-    }
-    /**
-     * Resolves a remote endpoint via the injected {@link RemoteConnection}, stores the session token on
-     * the launch context (so the controller can release it on close), and runs the library-specific `connect`.
-     * On failure the session is released and the error is wrapped in a {@link BrowserLaunchError}.
-     *
-     * Subclasses implement only the `connect` callback — the resolve / token / release / error-wrap scaffolding
-     * lives here so it stays identical across plugins.
-     */
-    async connectToRemoteBrowser(launchContext, connect) {
-        const connection = this.remoteConnection;
-        let url;
-        let token;
-        try {
-            ({ url, token } = await connection.resolve({ proxyUrl: launchContext.proxyUrl }));
-        }
-        catch (cause) {
-            throw new BrowserLaunchError('Failed to resolve the remote browser endpoint.', { cause });
-        }
-        launchContext.remoteToken = token;
-        try {
-            return await connect(url);
-        }
-        catch (cause) {
-            await connection.release(token);
-            throw new BrowserLaunchError(`Failed to connect to remote browser at "${sanitizeEndpointForLog(url)}". ` +
-                'Check that the endpoint is reachable and accepts the configured protocol.', { cause });
-        }
-    }
     /**
      * Creates a `LaunchContext` with all the information needed
      * to launch a browser. Aside from library specific launch options,
@@ -100,7 +50,7 @@ export class BrowserPlugin {
      * management of the pool and extra features.
      */
     createLaunchContext(options = {}) {
-        const { id, launchOptions = {}, proxyUrl = this.proxyUrl, useIncognitoPages = this.useIncognitoPages, userDataDir = this.userDataDir, browserPerProxy = this.browserPerProxy, ignoreProxyCertificate = this.ignoreProxyCertificate, isRemote = !!this.remoteConnection, } = options;
+        const { id, launchOptions = {}, proxyUrl = this.proxyUrl, useIncognitoPages = this.useIncognitoPages, userDataDir = this.userDataDir, browserPerProxy = this.browserPerProxy, ignoreProxyCertificate = this.ignoreProxyCertificate, isRemote, } = options;
         return new LaunchContext({
             id,
             launchOptions: merge({}, this.launchOptions, launchOptions),
@@ -117,13 +67,12 @@ export class BrowserPlugin {
      * Launches the browser using provided launch context.
      */
     async launch(launchContext = this.createLaunchContext()) {
-        // launchOptions is only used by the local launch path below — remote connections ignore it.
         launchContext.launchOptions ??= {};
         const { proxyUrl, launchOptions } = launchContext;
-        if (proxyUrl && !launchContext.isRemote) {
+        if (proxyUrl) {
             await this.addProxyToLaunchOptions(launchContext);
         }
-        if (!launchContext.isRemote && this.isChromiumBasedBrowser(launchContext)) {
+        if (this.isChromiumBasedBrowser(launchContext)) {
             // This will set the args for chromium based browsers to hide the webdriver.
             launchOptions.args = this.#mergeArgsToHideWebdriver(launchOptions.args);
             // When User-Agent is not set, and we're using Chromium in headless mode,
@@ -134,9 +83,6 @@ export class BrowserPlugin {
                 launchOptions.args.push(`--user-agent=${DEFAULT_USER_AGENT}`);
             }
         }
-        if (launchContext.isRemote) {
-            this.log.info('Connecting to remote browser (skipping local proxy and webdriver stealth configuration).');
-        }
         return this._launch(launchContext);
     }
     #mergeArgsToHideWebdriver(originalArgs) {

package/browser-pool.d.ts

@@ -54,6 +54,16 @@ export interface BrowserPoolOptions<Plugin extends BrowserPlugin = BrowserPlugin
      * @default 20
      */
     maxOpenPagesPerBrowser?: number;
+    /**
+     * Maximum number of browser processes alive at once. A browser counts from the moment its launch starts until it
+     * actually closes — a retired browser that is still finishing its last pages still occupies a slot. Once the
+     * limit is reached, {@link BrowserPool.newPage|newPage} waits for a slot (a browser closing, or an open
+     * browser with page capacity to spare) instead of launching another. Set it to a remote browser service's
+     * concurrent-session limit to avoid `429` errors.
+     *
+     * @default Infinity
+     */
+    maxOpenBrowsers?: number;
     /**
      * Browsers tend to get bloated after processing a lot of pages. This option
      * configures the maximum number of processed pages after which the browser will
@@ -251,8 +261,6 @@ export declare class BrowserPool<Options extends BrowserPoolOptions = BrowserPoo
     #private;
     browserPlugins: BrowserPlugins;
     /** @internal */
-    maxOpenBrowsers: number;
-    /** @internal */
     fingerprintOptions: FingerprintOptions;
     /** @internal */
     fingerprintInjector?: FingerprintInjector;
@@ -412,20 +420,9 @@ export declare class BrowserPool<Options extends BrowserPoolOptions = BrowserPoo
      * Returns `true` if the pool can accept a new browser launch without exceeding `maxOpenBrowsers`.
      * Counts starting, active, and retired browsers.
      *
-     * A plain `BrowserPool` leaves `maxOpenBrowsers` at `Infinity`, so this only returns `false` when something
-     * has set a cap — {@link RemoteBrowserPool} does, from its own
-     * {@link RemoteBrowserPoolOptions.maxOpenBrowsers|`maxOpenBrowsers`} option. There is no
-     * `BrowserPoolOptions` key for it.
-     *
      * @internal
      */
     hasFreeBrowserSlot(): boolean;
-    /**
-     * Returns `true` if any active browser has room for another page.
-     *
-     * @internal
-     */
-    hasActiveBrowserWithFreeCapacity(): boolean;
 }
 export interface BrowserPoolNewPageOptions<PageOptions, BP extends BrowserPlugin> extends NewPageOptions {
     /**

package/browser-pool.js

@@ -1,4 +1,3 @@
-import { AsyncResource } from 'node:async_hooks';
 import { SessionError, serviceLocator } from '@crawlee/core';
 import { parseArgument, schemas } from '@crawlee/utils/internal';
 import { FingerprintGenerator } from 'fingerprint-generator';
@@ -14,9 +13,11 @@ import { createFingerprintPreLaunchHook, createPostPageCreateHook, createPrePage
 const PAGE_CLOSE_TIMEOUT_MILLIS = 5000;
 const PAGE_CLOSE_KILL_TIMEOUT_MILLIS = 1000;
 const BROWSER_KILLER_INTERVAL_MILLIS = 10 * 1000;
+const SLOT_POLL_INTERVAL_MILLIS = 500;
 const browserPoolOptionsSchema = z.strictObject({
     browserPlugins: schemas.anyArray.refine((value) => value.length >= 1, 'Expected a non-empty array'),
     maxOpenPagesPerBrowser: schemas.anyNumber.default(20),
+    maxOpenBrowsers: schemas.anyNumber.default(Infinity),
     retireBrowserAfterPageCount: schemas.anyNumber.default(100),
     operationTimeoutSecs: schemas.anyNumber.default(15),
     closeInactiveBrowserAfterSecs: schemas.anyNumber.default(300),
@@ -80,8 +81,6 @@ const browserPoolOptionsSchema = z.strictObject({
 export class BrowserPool extends TypedEmitter {
     browserPlugins;
     /** @internal */
-    maxOpenBrowsers;
-    /** @internal */
     fingerprintOptions;
     /** @internal */
     fingerprintInjector;
@@ -89,6 +88,7 @@ export class BrowserPool extends TypedEmitter {
     /** @internal */
     fingerprintCache;
     #maxOpenPagesPerBrowser;
+    #maxOpenBrowsers;
     #retireBrowserAfterPageCount;
     #operationTimeoutMillis;
     #closeInactiveBrowserAfterMillis;
@@ -113,10 +113,12 @@ export class BrowserPool extends TypedEmitter {
     #browserRetireInterval;
     #limiter = pLimit(1);
     #log;
+    /** Shared by all `newPage` callers waiting for a free slot, so they don't each register their own listeners. */
+    #capacityChange;
     constructor(options) {
         super();
         this.#log = serviceLocator.getLogger().child({ prefix: 'BrowserPool' });
-        const { browserPlugins, maxOpenPagesPerBrowser, retireBrowserAfterPageCount, operationTimeoutSecs, closeInactiveBrowserAfterSecs, retireInactiveBrowserAfterSecs, preLaunchHooks, postLaunchHooks, prePageCreateHooks, postPageCreateHooks, prePageCloseHooks, postPageCloseHooks, useFingerprints, fingerprintOptions, } = parseArgument(options, browserPoolOptionsSchema);
+        const { browserPlugins, maxOpenPagesPerBrowser, maxOpenBrowsers, retireBrowserAfterPageCount, operationTimeoutSecs, closeInactiveBrowserAfterSecs, retireInactiveBrowserAfterSecs, preLaunchHooks, postLaunchHooks, prePageCreateHooks, postPageCreateHooks, prePageCloseHooks, postPageCloseHooks, useFingerprints, fingerprintOptions, } = parseArgument(options, browserPoolOptionsSchema);
         const firstPluginConstructor = browserPlugins[0].constructor;
         for (let i = 1; i < browserPlugins.length; i++) {
             const providedPlugin = browserPlugins[i];
@@ -127,7 +129,7 @@ export class BrowserPool extends TypedEmitter {
             }
         }
         this.browserPlugins = browserPlugins;
-        this.maxOpenBrowsers = Infinity;
+        this.#maxOpenBrowsers = maxOpenBrowsers;
         this.fingerprintOptions = fingerprintOptions;
         this.#maxOpenPagesPerBrowser = maxOpenPagesPerBrowser;
         this.#retireBrowserAfterPageCount = retireBrowserAfterPageCount;
@@ -189,28 +191,18 @@ export class BrowserPool extends TypedEmitter {
         if (browserPlugin && !this.browserPlugins.includes(browserPlugin)) {
             throw new Error('Provided browserPlugin is not one of the plugins used by BrowserPool.');
         }
-        // Bind the limiter callback to the current async-hooks context. p-limit
-        // otherwise resumes queued callbacks in the previous task's
-        // AsyncLocalStorage context, leaking aborted cancelTasks across unrelated
-        // requests (https://github.com/apify/crawlee/issues/3670). Mirrors the
-        // fix p-limit landed upstream in v5 (sindresorhus/p-limit#71); v5 is an
-        // ESM-only rewrite, so we can't bump it in Crawlee v3.
-        // Besides the cancelTask leak, the wrapper also keeps the per-request *storage transaction*
-        // ALS-scoped: without it, a queued callback would resume in the previous request's async
-        // context and run request B's storage writes inside request A's transaction.
-        // TODO(crawlee@v4): bump p-limit to v5 and drop this AsyncResource.bind wrapper.
         // Limiter is necessary - https://github.com/apify/crawlee/issues/1126
-        return this.#limiter(AsyncResource.bind(async () => {
+        return this.#limiter(async () => {
             let browserController = this.#pickBrowserWithFreeCapacity(browserPlugin, { proxyUrl });
-            if (!browserController)
-                browserController = await this.#launchBrowser(id, {
-                    browserPlugin,
-                    proxyUrl,
-                    ignoreTlsErrors,
-                });
+            // Checked under the limiter so concurrent waiters can't all pass on the same freed slot.
+            while (!browserController && !this.hasFreeBrowserSlot()) {
+                await this.#nextCapacityChange();
+                browserController = this.#pickBrowserWithFreeCapacity(browserPlugin, { proxyUrl });
+            }
+            browserController ??= await this.#launchBrowser(id, { browserPlugin, proxyUrl, ignoreTlsErrors });
             tryCancel();
             return await this.#createPageForBrowser(id, browserController, pageOptions, proxyUrl, ignoreTlsErrors);
-        }));
+        });
     }
     /**
      * Unlike {@link newPage}, `newPageInNewBrowser` always launches a new
@@ -628,30 +620,33 @@ export class BrowserPool extends TypedEmitter {
      * Returns `true` if the pool can accept a new browser launch without exceeding `maxOpenBrowsers`.
      * Counts starting, active, and retired browsers.
      *
-     * A plain `BrowserPool` leaves `maxOpenBrowsers` at `Infinity`, so this only returns `false` when something
-     * has set a cap — {@link RemoteBrowserPool} does, from its own
-     * {@link RemoteBrowserPoolOptions.maxOpenBrowsers|`maxOpenBrowsers`} option. There is no
-     * `BrowserPoolOptions` key for it.
-     *
      * @internal
      */
     hasFreeBrowserSlot() {
         const total = this.#startingBrowserControllers.size +
             this.activeBrowserControllers.size +
             this.retiredBrowserControllers.size;
-        return total < this.maxOpenBrowsers;
+        return total < this.#maxOpenBrowsers;
     }
     /**
-     * Returns `true` if any active browser has room for another page.
-     *
-     * @internal
+     * Resolves on the next browser-retired / page-closed event, or after a short fallback interval. All
+     * concurrently-waiting `newPage` calls share a single promise (and a single pair of event listeners) per tick.
      */
-    hasActiveBrowserWithFreeCapacity() {
-        for (const controller of this.activeBrowserControllers) {
-            if (controller.activePages < this.#maxOpenPagesPerBrowser)
-                return true;
-        }
-        return false;
+    #nextCapacityChange() {
+        this.#capacityChange ??= new Promise((resolve) => {
+            const done = () => {
+                clearTimeout(timer);
+                this.off(BROWSER_POOL_EVENTS.BROWSER_RETIRED, done);
+                this.off(BROWSER_POOL_EVENTS.PAGE_CLOSED, done);
+                this.#capacityChange = undefined;
+                resolve();
+            };
+            const timer = setTimeout(done, SLOT_POLL_INTERVAL_MILLIS);
+            timer.unref?.();
+            this.once(BROWSER_POOL_EVENTS.BROWSER_RETIRED, done);
+            this.once(BROWSER_POOL_EVENTS.PAGE_CLOSED, done);
+        });
+        return this.#capacityChange;
     }
     #initializeFingerprinting() {
         const { useFingerprintCache = true, fingerprintCacheSize = 10_000 } = this.fingerprintOptions;

package/index.d.ts

@@ -26,7 +26,9 @@
  */
 export * from './browser-pool.js';
 export * from './playwright/playwright-plugin.js';
+export * from './playwright/remote-playwright-plugin.js';
 export * from './puppeteer/puppeteer-plugin.js';
+export * from './puppeteer/remote-puppeteer-plugin.js';
 export * from './events.js';
 export type { FingerprintGeneratorOptions } from './fingerprinting/types.js';
 export { BrowserName, DeviceCategory, OperatingSystemsName } from './fingerprinting/types.js';
@@ -40,8 +42,7 @@ export { BrowserPlugin, BrowserLaunchError, DEFAULT_USER_AGENT } from './abstrac
 export type { LaunchContextOptions } from './launch-context.js';
 export { LaunchContext } from './launch-context.js';
 export { RemoteBrowserProvider } from './remote-browser-provider.js';
-export { RemoteBrowserPool } from './remote-browser-pool.js';
-export type { RemoteBrowserPoolOptions, CrawlerRemoteBrowserOptions, RemoteBrowserEndpoint, ResolvedRemoteEndpoint, RemoteConnection, RemoteConnectionParameters, } from './remote-browser-pool.js';
+export type { RemoteBrowserEndpoint, RemoteBrowserOptions, ResolvedRemoteEndpoint } from './remote-browser-plugin.js';
 export type { InferBrowserPluginArray, UnwrapPromise } from './utils.js';
 export { anonymizeProxySugar, type AnonymizeProxySugarOptions } from './anonymize-proxy.js';
 export type { IBrowserPool, NewPageOptions } from '@crawlee/types';

package/index.js

@@ -24,7 +24,9 @@
  */
 export * from './browser-pool.js';
 export * from './playwright/playwright-plugin.js';
+export * from './playwright/remote-playwright-plugin.js';
 export * from './puppeteer/puppeteer-plugin.js';
+export * from './puppeteer/remote-puppeteer-plugin.js';
 export * from './events.js';
 export { BrowserName, DeviceCategory, OperatingSystemsName } from './fingerprinting/types.js';
 export { BrowserController } from './abstract-classes/browser-controller.js';
@@ -34,5 +36,4 @@ export { PlaywrightBrowser } from './playwright/playwright-browser.js';
 export { BrowserPlugin, BrowserLaunchError, DEFAULT_USER_AGENT } from './abstract-classes/browser-plugin.js';
 export { LaunchContext } from './launch-context.js';
 export { RemoteBrowserProvider } from './remote-browser-provider.js';
-export { RemoteBrowserPool } from './remote-browser-pool.js';
 export { anonymizeProxySugar } from './anonymize-proxy.js';

package/launch-context.d.ts

@@ -67,12 +67,6 @@ export declare class LaunchContext<Library extends CommonLibrary = CommonLibrary
     readonly isRemote: boolean;
     ignoreProxyCertificate?: boolean;
     fingerprint?: BrowserFingerprintWithHeaders;
-    /**
-     * Token identifying the remote browser session this context connected to, set by the plugin and read by
-     * the {@link RemoteBrowserPool} to release the session on close. Only present for remote connections.
-     * @internal
-     */
-    remoteToken?: number;
     [K: PropertyKey]: unknown;
     constructor(options: LaunchContextOptions<Library, LibraryOptions, LaunchResult, NewPageOptions, NewPageResult>);
     /**

package/launch-context.js

@@ -10,12 +10,6 @@ export class LaunchContext {
     #proxyUrl;
     #reservedFieldNames;
     fingerprint;
-    /**
-     * Token identifying the remote browser session this context connected to, set by the plugin and read by
-     * the {@link RemoteBrowserPool} to release the session on close. Only present for remote connections.
-     * @internal
-     */
-    remoteToken;
     constructor(options) {
         const { id, browserPlugin, launchOptions, proxyUrl, useIncognitoPages, browserPerProxy, userDataDir = '', ignoreProxyCertificate, isRemote, } = options;
         this.id = id;
@@ -29,7 +23,7 @@ export class LaunchContext {
         this.#proxyUrl = proxyUrl;
         // Computed here (not in a field initializer) so that all fields already exist; the accessors live on
         // the prototype, so they are never own keys and have to be listed explicitly.
-        this.#reservedFieldNames = [...Reflect.ownKeys(this), 'proxyUrl', 'remoteToken', 'extend'];
+        this.#reservedFieldNames = [...Reflect.ownKeys(this), 'proxyUrl', 'extend'];
     }
     /**
      * Extend the launch context with any extra fields.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@crawlee/browser-pool",
-    "version": "4.0.0-beta.223",
+    "version": "4.0.0-beta.224",
     "description": "Rotate multiple browsers using popular automation libraries such as Playwright or Puppeteer.",
     "engines": {
         "node": ">=22.13.0"
@@ -31,9 +31,9 @@
     },
     "dependencies": {
         "@apify/timeout": "^1.0.1",
-        "@crawlee/core": "4.0.0-beta.223",
-        "@crawlee/types": "4.0.0-beta.223",
-        "@crawlee/utils": "4.0.0-beta.223",
+        "@crawlee/core": "4.0.0-beta.224",
+        "@crawlee/types": "4.0.0-beta.224",
+        "@crawlee/utils": "4.0.0-beta.224",
         "fingerprint-generator": "^2.1.68",
         "fingerprint-injector": "^2.1.68",
         "lodash.merge": "^4.6.2",
@@ -64,5 +64,5 @@
             }
         }
     },
-    "gitHead": "cfcbcbebeabd9ca2dfd7a17afe559db16307250d"
+    "gitHead": "669f726126327dee3b1d6b950663fd4fceace651"
 }

package/playwright/playwright-plugin.d.ts

@@ -2,18 +2,10 @@
 import type { Browser as PlaywrightBrowser, BrowserType } from 'playwright';
 import { BrowserPlugin } from '../abstract-classes/browser-plugin.js';
 import type { LaunchContext } from '../launch-context.js';
-import type { RemoteConnection, RemoteConnectionParameters } from '../remote-browser-pool.js';
 import type { SafeParameters } from '../utils.js';
 import { PlaywrightController } from './playwright-controller.js';
 export declare class PlaywrightPlugin extends BrowserPlugin<BrowserType, SafeParameters<BrowserType['launch']>[0], PlaywrightBrowser> {
     #private;
-    /**
-     * Playwright remote connections only support incognito pages — `connect()` / `connectOverCDP()` don't
-     * accept persistent contexts. Force it on (and inform the user) when wired for a remote connection.
-     *
-     * @internal
-     */
-    useRemoteConnection(connection: RemoteConnection, parameters?: RemoteConnectionParameters): void;
     protected _launch(launchContext: LaunchContext<BrowserType>): Promise<PlaywrightBrowser>;
     createController(): PlaywrightController;
     protected addProxyToLaunchOptions(launchContext: LaunchContext<BrowserType>): Promise<void>;

package/playwright/playwright-plugin.js

@@ -6,32 +6,7 @@ import { PlaywrightBrowser as PlaywrightBrowserWithPersistentContext } from './p
 import { PlaywrightController } from './playwright-controller.js';
 export class PlaywrightPlugin extends BrowserPlugin {
     #browserVersion;
-    /**
-     * Playwright remote connections only support incognito pages — `connect()` / `connectOverCDP()` don't
-     * accept persistent contexts. Force it on (and inform the user) when wired for a remote connection.
-     *
-     * @internal
-     */
-    useRemoteConnection(connection, parameters = {}) {
-        super.useRemoteConnection(connection, parameters);
-        if (!this.useIncognitoPages) {
-            this.log.info('Remote Playwright connection — useIncognitoPages forced to true. ' +
-                'Pages will not share cookies/storage between each other; use the SessionPool for shared state.');
-        }
-        this.useIncognitoPages = true;
-    }
     async _launch(launchContext) {
-        if (this.remoteConnection) {
-            return this.connectToRemoteBrowser(launchContext, async (url) => {
-                const connectOptions = (this.remoteConnectionParameters?.connectOptions ?? {});
-                if (this.remoteConnectionParameters?.protocol === 'playwright') {
-                    this.log.info('Connecting to remote browser via connect (Playwright WebSocket).');
-                    return this.library.connect(url, connectOptions);
-                }
-                this.log.info('Connecting to remote browser via connectOverCDP.');
-                return this.library.connectOverCDP(url, connectOptions);
-            });
-        }
         const { launchOptions, useIncognitoPages, userDataDir, proxyUrl } = launchContext;
         let browser;
         // Required for the `proxy` context option to work.

package/playwright/remote-playwright-plugin.d.ts

@@ -0,0 +1,29 @@
+// @ts-ignore optional peer dependency or compatibility with es2022
+import type { Browser as PlaywrightBrowser, BrowserType } from 'playwright';
+import type { BrowserPluginOptions, CreateLaunchContextOptions } from '../abstract-classes/browser-plugin.js';
+import type { LaunchContext } from '../launch-context.js';
+import { type RemoteBrowserOptions } from '../remote-browser-plugin.js';
+import type { SafeParameters } from '../utils.js';
+import { PlaywrightPlugin } from './playwright-plugin.js';
+export interface RemotePlaywrightPluginOptions extends BrowserPluginOptions<SafeParameters<BrowserType['launch']>[0]>, RemoteBrowserOptions {
+    /**
+     * Which protocol to connect with. `'cdp'` uses `connectOverCDP()` (the default), `'playwright'` uses
+     * `connect()` (Playwright's own WebSocket protocol, for endpoints started with `launchServer()`).
+     */
+    protocol?: 'cdp' | 'playwright';
+}
+/**
+ * A {@link PlaywrightPlugin} that connects to a remote browser service (Browserbase, Browserless, Steel, …)
+ * instead of launching locally. `launchOptions` are ignored — the remote service owns the browser.
+ *
+ * Remote connections only support incognito pages (`connect()` / `connectOverCDP()` don't accept persistent
+ * contexts), so `useIncognitoPages` is always `true`.
+ */
+export declare class RemotePlaywrightPlugin extends PlaywrightPlugin {
+    #private;
+    constructor(library: BrowserType, options: RemotePlaywrightPluginOptions);
+    createLaunchContext(options?: CreateLaunchContextOptions<BrowserType>): LaunchContext<BrowserType>;
+    /** Skips the local proxy and webdriver-stealth preparation; the remote service owns the browser. */
+    launch(launchContext?: LaunchContext<BrowserType>): Promise<PlaywrightBrowser>;
+    protected _launch(launchContext: LaunchContext<BrowserType>): Promise<PlaywrightBrowser>;
+}

package/playwright/remote-playwright-plugin.js

@@ -0,0 +1,38 @@
+import { connectRemoteBrowser } from '../remote-browser-plugin.js';
+import { PlaywrightPlugin } from './playwright-plugin.js';
+/**
+ * A {@link PlaywrightPlugin} that connects to a remote browser service (Browserbase, Browserless, Steel, …)
+ * instead of launching locally. `launchOptions` are ignored — the remote service owns the browser.
+ *
+ * Remote connections only support incognito pages (`connect()` / `connectOverCDP()` don't accept persistent
+ * contexts), so `useIncognitoPages` is always `true`.
+ */
+export class RemotePlaywrightPlugin extends PlaywrightPlugin {
+    #remote;
+    constructor(library, options) {
+        super(library, { ...options, useIncognitoPages: true });
+        this.#remote = options;
+        if (options.useIncognitoPages === false) {
+            this.log.info('Remote Playwright connection — useIncognitoPages forced to true. ' +
+                'Pages will not share cookies/storage between each other; use the SessionPool for shared state.');
+        }
+    }
+    createLaunchContext(options = {}) {
+        return super.createLaunchContext({ ...options, isRemote: true });
+    }
+    /** Skips the local proxy and webdriver-stealth preparation; the remote service owns the browser. */
+    async launch(launchContext = this.createLaunchContext()) {
+        return this._launch(launchContext);
+    }
+    async _launch(launchContext) {
+        const { protocol, connectOptions = {} } = this.#remote;
+        return connectRemoteBrowser(this.#remote, launchContext.proxyUrl, this.log, async (url) => {
+            if (protocol === 'playwright') {
+                this.log.info('Connecting to remote browser via connect (Playwright WebSocket).');
+                return this.library.connect(url, connectOptions);
+            }
+            this.log.info('Connecting to remote browser via connectOverCDP.');
+            return this.library.connectOverCDP(url, connectOptions);
+        });
+    }
+}

package/puppeteer/puppeteer-plugin.d.ts

@@ -4,17 +4,19 @@ import type Puppeteer from 'puppeteer';
 import type * as PuppeteerTypes from 'puppeteer';
 import { BrowserPlugin } from '../abstract-classes/browser-plugin.js';
 import type { LaunchContext } from '../launch-context.js';
-import type { RemoteConnection, RemoteConnectionParameters } from '../remote-browser-pool.js';
 import type { PuppeteerNewPageOptions } from './puppeteer-controller.js';
 import { PuppeteerController } from './puppeteer-controller.js';
+export type PuppeteerLaunchContext = LaunchContext<typeof Puppeteer, PuppeteerTypes.LaunchOptions, PuppeteerTypes.Browser, PuppeteerNewPageOptions>;
 export declare class PuppeteerPlugin extends BrowserPlugin<typeof Puppeteer, PuppeteerTypes.LaunchOptions, PuppeteerTypes.Browser, PuppeteerNewPageOptions> {
+    protected _launch(launchContext: PuppeteerLaunchContext): Promise<PuppeteerTypes.Browser>;
+    /** @internal */
+    protected isOldPuppeteerVersion(): Promise<boolean>;
     /**
-     * Pages share cookies/storage on the remote browser (Puppeteer defaults to non-incognito).
-     *
+     * Attaches page crash handling and the incognito-context-per-page `newPage` proxy. Shared by the local launch
+     * and {@link RemotePuppeteerPlugin}.
      * @internal
      */
-    useRemoteConnection(connection: RemoteConnection, parameters?: RemoteConnectionParameters): void;
-    protected _launch(launchContext: LaunchContext<typeof Puppeteer, PuppeteerTypes.LaunchOptions, PuppeteerTypes.Browser, PuppeteerNewPageOptions>): Promise<PuppeteerTypes.Browser>;
+    protected wrapBrowser(browser: PuppeteerTypes.Browser, launchContext: PuppeteerLaunchContext, oldPuppeteerVersion: boolean): PuppeteerTypes.Browser;
     createController(): PuppeteerController;
     protected addProxyToLaunchOptions(_launchContext: LaunchContext<typeof Puppeteer, PuppeteerTypes.LaunchOptions, PuppeteerTypes.Browser, PuppeteerNewPageOptions>): Promise<void>;
     protected isChromiumBasedBrowser(_launchContext: LaunchContext<typeof Puppeteer, PuppeteerTypes.LaunchOptions, PuppeteerTypes.Browser, PuppeteerNewPageOptions>): boolean;