@crawlee/browser-pool 4.0.0-beta.21 → 4.0.0-beta.210

package/playwright/playwright-plugin.js

@@ -1,14 +1,37 @@
 import fs from 'node:fs';
 import { BrowserPlugin } from '../abstract-classes/browser-plugin.js';
 import { anonymizeProxySugar } from '../anonymize-proxy.js';
-import { log } from '../logger.js';
 import { getLocalProxyAddress } from '../proxy-server.js';
 import { PlaywrightBrowser as PlaywrightBrowserWithPersistentContext } from './playwright-browser.js';
 import { PlaywrightController } from './playwright-controller.js';
 export class PlaywrightPlugin extends BrowserPlugin {
-    _browserVersion;
-    _containerProxyServer;
+    #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.
@@ -20,7 +43,9 @@ export class PlaywrightPlugin extends BrowserPlugin {
         if (this.library.name() === 'webkit') {
             launchOptions.args = launchOptions.args?.filter((arg) => arg !== '--no-sandbox');
         }
-        const [anonymizedProxyUrl, close] = await anonymizeProxySugar(proxyUrl);
+        const [anonymizedProxyUrl, close] = await anonymizeProxySugar(proxyUrl, undefined, undefined, {
+            ignoreProxyCertificate: launchContext.ignoreProxyCertificate,
+        });
         if (anonymizedProxyUrl) {
             launchOptions.proxy = {
                 server: anonymizedProxyUrl,
@@ -30,7 +55,7 @@ export class PlaywrightPlugin extends BrowserPlugin {
         try {
             if (useIncognitoPages) {
                 browser = await this.library.launch(launchOptions).catch((error) => {
-                    return this._throwOnFailedLaunch(launchContext, error);
+                    return this.throwOnFailedLaunch(launchContext, error);
                 });
                 if (anonymizedProxyUrl) {
                     browser.on('disconnected', async () => {
@@ -42,7 +67,7 @@ export class PlaywrightPlugin extends BrowserPlugin {
                 const browserContext = await this.library
                     .launchPersistentContext(userDataDir, launchOptions)
                     .catch((error) => {
-                    return this._throwOnFailedLaunch(launchContext, error);
+                    return this.throwOnFailedLaunch(launchContext, error);
                 });
                 browserContext.once('close', () => {
                     if (userDataDir.includes('apify-playwright-firefox-taac-')) {
@@ -57,18 +82,20 @@ export class PlaywrightPlugin extends BrowserPlugin {
                         await close();
                     });
                 }
-                if (!this._browserVersion) {
+                if (!this.#browserVersion) {
                     // Launches unused browser just to get the browser version.
                     const inactiveBrowser = await this.library.launch(launchOptions);
-                    this._browserVersion = inactiveBrowser.version();
+                    this.#browserVersion = inactiveBrowser.version();
                     inactiveBrowser.close().catch((error) => {
-                        log.exception(error, 'Failed to close browser.');
+                        this.log.exception(error, 'Failed to close browser.');
                     });
                 }
-                browser = new PlaywrightBrowserWithPersistentContext({
+                const persistentBrowser = new PlaywrightBrowserWithPersistentContext({
                     browserContext,
-                    version: this._browserVersion,
+                    version: this.#browserVersion,
                 });
+                persistentBrowser.setBrowserType(this.library);
+                browser = persistentBrowser;
             }
         }
         catch (error) {
@@ -77,13 +104,13 @@ export class PlaywrightPlugin extends BrowserPlugin {
         }
         return browser;
     }
-    _throwOnFailedLaunch(launchContext, cause) {
-        this._throwAugmentedLaunchError(cause, launchContext.launchOptions?.executablePath, '`apify/actor-node-playwright-*` (with a correct browser name)', 'Try installing the required dependencies by running `npx playwright install --with-deps` (https://playwright.dev/docs/browsers).');
+    throwOnFailedLaunch(launchContext, cause) {
+        this.throwAugmentedLaunchError(cause, launchContext.launchOptions?.executablePath, '`apify/actor-node-playwright-*` (with a correct browser name)', 'Try installing the required dependencies by running `npx playwright install --with-deps` (https://playwright.dev/docs/browsers).');
     }
     createController() {
         return new PlaywrightController(this);
     }
-    async _addProxyToLaunchOptions(launchContext) {
+    async addProxyToLaunchOptions(launchContext) {
         launchContext.launchOptions ??= {};
         const { launchOptions, proxyUrl } = launchContext;
         if (proxyUrl) {
@@ -95,9 +122,8 @@ export class PlaywrightPlugin extends BrowserPlugin {
             };
         }
     }
-    _isChromiumBasedBrowser() {
+    isChromiumBasedBrowser() {
         const name = this.library.name();
         return name === 'chromium';
     }
 }
-//# sourceMappingURL=playwright-plugin.js.map

package/proxy-server.d.ts

@@ -1,2 +1 @@
 export declare function getLocalProxyAddress(): Promise<string>;
-//# sourceMappingURL=proxy-server.d.ts.map

package/proxy-server.js

@@ -10,4 +10,3 @@ export async function getLocalProxyAddress() {
     await listenPromise;
     return `http://127.0.0.1:${server.port}`;
 }
-//# sourceMappingURL=proxy-server.js.map

package/puppeteer/puppeteer-controller.d.ts

@@ -9,6 +9,7 @@ export interface PuppeteerNewPageOptions extends PuppeteerTypes.BrowserContextOp
     proxyPassword?: string;
 }
 export declare class PuppeteerController extends BrowserController<typeof Puppeteer, PuppeteerTypes.LaunchOptions, PuppeteerTypes.Browser, PuppeteerNewPageOptions> {
+    /** @internal */
     normalizeProxyOptions(proxyUrl: string | undefined, pageOptions: any): Record<string, unknown>;
     protected _newPage(contextOptions?: PuppeteerNewPageOptions): Promise<PuppeteerTypes.Page>;
     protected _close(): Promise<void>;
@@ -16,4 +17,3 @@ export declare class PuppeteerController extends BrowserController<typeof Puppet
     protected _getCookies(page: PuppeteerTypes.Page): Promise<Cookie[]>;
     protected _setCookies(page: PuppeteerTypes.Page, cookies: Cookie[]): Promise<void>;
 }
-//# sourceMappingURL=puppeteer-controller.d.ts.map

package/puppeteer/puppeteer-controller.js

@@ -1,9 +1,9 @@
 import { tryCancel } from '@apify/timeout';
 import { BrowserController } from '../abstract-classes/browser-controller.js';
 import { anonymizeProxySugar } from '../anonymize-proxy.js';
-import { log } from '../logger.js';
 const PROCESS_KILL_TIMEOUT_MILLIS = 5000;
 export class PuppeteerController extends BrowserController {
+    /** @internal */
     normalizeProxyOptions(proxyUrl, pageOptions) {
         if (!proxyUrl) {
             return {};
@@ -12,7 +12,7 @@ export class PuppeteerController extends BrowserController {
         const username = decodeURIComponent(url.username);
         const password = decodeURIComponent(url.password);
         return {
-            proxyServer: url.origin,
+            proxyServer: `${url.protocol}//${url.host}`,
             proxyUsername: username,
             proxyPassword: password,
             proxyBypassList: pageOptions?.proxyBypassList,
@@ -25,7 +25,7 @@ export class PuppeteerController extends BrowserController {
             }
             let close = async () => { };
             if (contextOptions.proxyServer) {
-                const [anonymizedProxyUrl, closeProxy] = await anonymizeProxySugar(contextOptions.proxyServer, contextOptions.proxyUsername, contextOptions.proxyPassword);
+                const [anonymizedProxyUrl, closeProxy] = await anonymizeProxySugar(contextOptions.proxyServer, contextOptions.proxyUsername, contextOptions.proxyPassword, { ignoreProxyCertificate: this.launchContext.ignoreProxyCertificate });
                 if (anonymizedProxyUrl) {
                     contextOptions.proxyServer = anonymizedProxyUrl;
                     delete contextOptions.proxyUsername;
@@ -52,17 +52,18 @@ export class PuppeteerController extends BrowserController {
                     tryCancel();
                 }
                 */
-                page.once('close', async () => {
-                    this.activePages--;
-                    try {
-                        await context.close();
-                    }
-                    catch (error) {
-                        log.exception(error, 'Failed to close context.');
-                    }
-                    finally {
-                        await close();
-                    }
+                this.registerPageTeardown(page, async () => {
+                    // The proxy server is not chained behind the context close: that can hang on
+                    // the same target the page hung on, and the proxy runs in this process, so it
+                    // has to be reclaimed either way.
+                    const contextClosed = context.close().catch((error) => {
+                        this.log.exception(error, 'Failed to close context.');
+                    });
+                    await close();
+                    await contextClosed;
+                });
+                page.once('close', () => {
+                    this.registerPageClosed(page);
                 });
                 return page;
             }
@@ -74,7 +75,7 @@ export class PuppeteerController extends BrowserController {
         const page = await this.browser.newPage();
         tryCancel();
         page.once('close', () => {
-            this.activePages--;
+            this.registerPageClosed(page);
         });
         return page;
     }
@@ -84,7 +85,7 @@ export class PuppeteerController extends BrowserController {
     async _kill() {
         const browserProcess = this.browser.process();
         if (!browserProcess) {
-            log.debug('Browser was connected using the `puppeteer.connect` method no browser to kill.');
+            this.log.debug('Browser was connected using the `puppeteer.connect` method no browser to kill.');
             return;
         }
         const timeout = setTimeout(() => {
@@ -98,14 +99,22 @@ export class PuppeteerController extends BrowserController {
             clearTimeout(timeout);
         }
         catch (error) {
-            log.debug('Browser was already killed.', { error });
+            this.log.debug('Browser was already killed.', { error });
         }
     }
     async _getCookies(page) {
-        return page.cookies();
+        const cookies = await page.browserContext().cookies();
+        // Puppeteer 25+ can report `sameSite: 'Default'`, which means the attribute is unspecified.
+        return cookies.map(({ sameSite, ...rest }) => ({
+            ...rest,
+            sameSite: sameSite === 'Default' ? undefined : sameSite,
+        }));
     }
     async _setCookies(page, cookies) {
-        return page.setCookie(...cookies);
+        // BrowserContext.setCookie requires `url` or `domain`; the page-level API used to back-fill
+        // the page's current URL for us. Replicate that so callers who pass neither don't get rejected.
+        const pageUrl = page.url();
+        const normalized = cookies.map((cookie) => cookie.url || cookie.domain ? cookie : { ...cookie, url: pageUrl });
+        return page.browserContext().setCookie(...normalized);
     }
 }
-//# sourceMappingURL=puppeteer-controller.js.map

package/puppeteer/puppeteer-plugin.d.ts

@@ -4,12 +4,18 @@ 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 declare class PuppeteerPlugin extends BrowserPlugin<typeof Puppeteer, PuppeteerTypes.LaunchOptions, PuppeteerTypes.Browser, PuppeteerNewPageOptions> {
+    /**
+     * Pages share cookies/storage on the remote browser (Puppeteer defaults to non-incognito).
+     *
+     * @internal
+     */
+    useRemoteConnection(connection: RemoteConnection, parameters?: RemoteConnectionParameters): void;
     protected _launch(launchContext: LaunchContext<typeof Puppeteer, PuppeteerTypes.LaunchOptions, PuppeteerTypes.Browser, PuppeteerNewPageOptions>): Promise<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;
+    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;
 }
-//# sourceMappingURL=puppeteer-plugin.d.ts.map

package/puppeteer/puppeteer-plugin.js

@@ -1,11 +1,22 @@
 import { readFile } from 'node:fs/promises';
 import { BrowserPlugin } from '../abstract-classes/browser-plugin.js';
 import { anonymizeProxySugar } from '../anonymize-proxy.js';
-import { log } from '../logger.js';
 import { noop } from '../utils.js';
 import { PuppeteerController } from './puppeteer-controller.js';
 const PROXY_SERVER_ARG = '--proxy-server=';
 export class PuppeteerPlugin extends BrowserPlugin {
+    /**
+     * Pages share cookies/storage on the remote browser (Puppeteer defaults to non-incognito).
+     *
+     * @internal
+     */
+    useRemoteConnection(connection, parameters = {}) {
+        super.useRemoteConnection(connection, parameters);
+        if (!this.useIncognitoPages) {
+            this.log.info('Remote Puppeteer connection — pages will share cookies and storage on the remote ' +
+                'browser instance (useIncognitoPages defaults to false).');
+        }
+    }
     async _launch(launchContext) {
         let oldPuppeteerVersion = false;
         try {
@@ -17,58 +28,80 @@ export class PuppeteerPlugin extends BrowserPlugin {
         catch {
             // ignore
         }
-        const { launchOptions, userDataDir, useIncognitoPages, proxyUrl } = launchContext;
-        launchOptions.userDataDir = launchOptions.userDataDir ?? userDataDir;
-        if (launchOptions.headless === false) {
-            if (Array.isArray(launchOptions.args)) {
-                launchOptions.args.push('--disable-site-isolation-trials');
-            }
-            else {
-                launchOptions.args = ['--disable-site-isolation-trials'];
-            }
-        }
-        if (launchOptions.headless === true && oldPuppeteerVersion) {
-            launchOptions.headless = 'new';
-        }
+        const { useIncognitoPages, proxyUrl, ignoreProxyCertificate } = launchContext;
         let browser;
-        {
-            const [anonymizedProxyUrl, close] = await anonymizeProxySugar(proxyUrl);
-            if (proxyUrl) {
-                const proxyArg = `${PROXY_SERVER_ARG}${anonymizedProxyUrl ?? proxyUrl}`;
+        if (this.remoteConnection) {
+            browser = await this.connectToRemoteBrowser(launchContext, async (url) => {
+                const connectOptions = this.remoteConnectionParameters?.connectOptions ?? {};
+                this.log.info('Connecting to remote browser via connect (CDP).');
+                return this.library.connect({ ...connectOptions, browserWSEndpoint: url });
+            });
+        }
+        else {
+            const { launchOptions, userDataDir, experimentalContainers } = launchContext;
+            if (experimentalContainers) {
+                throw new Error('Experimental containers are only available with Playwright');
+            }
+            launchOptions.userDataDir = launchOptions.userDataDir ?? userDataDir;
+            if (launchOptions.headless === false) {
                 if (Array.isArray(launchOptions.args)) {
-                    launchOptions.args.push(proxyArg);
+                    launchOptions.args.push('--disable-site-isolation-trials');
                 }
                 else {
-                    launchOptions.args = [proxyArg];
+                    launchOptions.args = ['--disable-site-isolation-trials'];
                 }
             }
-            try {
-                browser = await this.library.launch(launchOptions);
-                if (anonymizedProxyUrl) {
-                    browser.on('disconnected', async () => {
-                        await close();
-                    });
-                }
+            if (launchOptions.headless === true && oldPuppeteerVersion) {
+                launchOptions.headless = 'new';
             }
-            catch (error) {
-                await close();
-                this._throwAugmentedLaunchError(error, launchContext.launchOptions?.executablePath, '`apify/actor-node-puppeteer-chrome`', "Try installing a browser, if it's missing, by running `npx @puppeteer/browsers install chromium --path [path]` and pointing `executablePath` to the downloaded executable (https://pptr.dev/browsers-api)");
+            {
+                const [anonymizedProxyUrl, close] = await anonymizeProxySugar(proxyUrl, undefined, undefined, {
+                    ignoreProxyCertificate: launchContext.ignoreProxyCertificate,
+                });
+                if (proxyUrl) {
+                    const proxyArg = `${PROXY_SERVER_ARG}${anonymizedProxyUrl ?? proxyUrl}`;
+                    if (Array.isArray(launchOptions.args)) {
+                        launchOptions.args.push(proxyArg);
+                    }
+                    else {
+                        launchOptions.args = [proxyArg];
+                    }
+                }
+                try {
+                    browser = await this.library.launch(launchOptions);
+                    if (anonymizedProxyUrl) {
+                        browser.on('disconnected', async () => {
+                            await close();
+                        });
+                    }
+                }
+                catch (error) {
+                    await close();
+                    this.throwAugmentedLaunchError(error, launchContext.launchOptions?.executablePath, '`apify/actor-node-puppeteer-chrome`', "Try installing a browser, if it's missing, by running `npx @puppeteer/browsers install chromium --path [path]` and pointing `executablePath` to the downloaded executable (https://pptr.dev/browsers-api)");
+                }
             }
         }
-        browser.on('targetcreated', async (target) => {
+        const targetCreatedHandler = async (target) => {
             try {
                 const page = await target.page();
                 if (page) {
                     page.on('error', (error) => {
-                        log.exception(error, 'Page crashed.');
+                        this.log.exception(error, 'Page crashed.');
                         page.close().catch(noop);
                     });
                 }
             }
             catch (error) {
-                log.exception(error, 'Failed to retrieve page from target.');
+                this.log.exception(error, 'Failed to retrieve page from target.');
             }
-        });
+        };
+        browser.on('targetcreated', targetCreatedHandler);
+        // Clean up the listener when a remote browser disconnects to prevent leaks
+        if (this.remoteConnection) {
+            browser.once('disconnected', () => {
+                browser.off('targetcreated', targetCreatedHandler);
+            });
+        }
         const boundMethods = [
             'newPage',
             'close',
@@ -78,6 +111,7 @@ export class PuppeteerPlugin extends BrowserPlugin {
             'version',
             'on',
             'process',
+            'pages',
         ].reduce((map, method) => {
             map[method] = browser[method]?.bind(browser);
             return map;
@@ -89,22 +123,30 @@ export class PuppeteerPlugin extends BrowserPlugin {
                     return async (...args) => {
                         let page;
                         if (useIncognitoPages) {
-                            const [anonymizedProxyUrl, close] = await anonymizeProxySugar(proxyUrl);
+                            // Skip proxy setup for remote connections — proxy is managed by the remote service.
+                            const effectiveProxyUrl = this.remoteConnection ? undefined : proxyUrl;
+                            const [anonymizedProxyUrl, close] = effectiveProxyUrl
+                                ? await anonymizeProxySugar(effectiveProxyUrl, undefined, undefined, {
+                                    ignoreProxyCertificate,
+                                })
+                                : [undefined, noop];
+                            const proxyServer = anonymizedProxyUrl ?? effectiveProxyUrl;
+                            const contextOptions = proxyServer ? { proxyServer } : {};
+                            const context = (await browser[method](contextOptions));
                             try {
-                                const context = (await browser[method]({
-                                    proxyServer: anonymizedProxyUrl ?? proxyUrl,
-                                }));
                                 page = await context.newPage(...args);
-                                if (anonymizedProxyUrl) {
-                                    page.on('close', async () => {
-                                        await close();
-                                    });
-                                }
                             }
                             catch (error) {
+                                await context.close().catch(noop);
                                 await close();
                                 throw error;
                             }
+                            page.once('close', async () => {
+                                if (anonymizedProxyUrl) {
+                                    await close();
+                                }
+                                await context.close().catch(noop);
+                            });
                         }
                         else {
                             page = await boundMethods.newPage(...args);
@@ -139,7 +181,7 @@ export class PuppeteerPlugin extends BrowserPlugin {
     createController() {
         return new PuppeteerController(this);
     }
-    async _addProxyToLaunchOptions(_launchContext) {
+    async addProxyToLaunchOptions(_launchContext) {
         /*
         // DO NOT USE YET! DOING SO DISABLES CACHE WHICH IS 50% PERFORMANCE HIT!
         launchContext.launchOptions ??= {};
@@ -166,8 +208,7 @@ export class PuppeteerPlugin extends BrowserPlugin {
         }
         */
     }
-    _isChromiumBasedBrowser(_launchContext) {
+    isChromiumBasedBrowser(_launchContext) {
         return true;
     }
 }
-//# sourceMappingURL=puppeteer-plugin.js.map

package/remote-browser-pool.d.ts

@@ -0,0 +1,178 @@
+import type { IBrowserPool, NewPageOptions, PageState } from '@crawlee/types';
+import type { BrowserPlugin } from './abstract-classes/browser-plugin.js';
+import { BrowserPool } from './browser-pool.js';
+import type { BrowserPoolHooks, BrowserPoolOptions } from './browser-pool.js';
+import { RemoteBrowserProvider } from './remote-browser-provider.js';
+/**
+ * The result of resolving a remote browser endpoint: the URL to connect to plus an optional opaque
+ * `context` object that is handed back to `release`.
+ */
+export interface ResolvedRemoteEndpoint {
+    /** The browser endpoint URL to connect to. */
+    url: string;
+    /** Opaque metadata passed back to `release()` — e.g. session IDs, API tokens. */
+    context?: Record<string, unknown>;
+}
+/**
+ * A remote browser endpoint: either a static URL string, or a function called once per browser launch
+ * that returns a URL (optionally with a `context` for `release`).
+ *
+ * The function receives the `proxyUrl` resolved by Crawlee's proxy configuration for the launch, so it
+ * can forward it to the remote service's proxy API.
+ */
+export type RemoteBrowserEndpoint = string | ((options?: {
+    proxyUrl?: string;
+}) => string | ResolvedRemoteEndpoint | Promise<string | ResolvedRemoteEndpoint>);
+/**
+ * The bridge a {@link RemoteBrowserPool} injects into a {@link BrowserPlugin} so the plugin can
+ * connect to a remote browser without owning any remote-session policy.
+ *
+ * The plugin only knows how to make the library-specific `connect()` call; everything else — resolving
+ * the endpoint, calling the user's `release()`, and guaranteeing release fires at most once — lives in
+ * the pool. The plugin calls {@link RemoteConnection.resolve|resolve} before connecting, stores the
+ * returned `token` on its launch context, and the controller later calls
+ * {@link RemoteConnection.release|release} with that token when the browser closes.
+ */
+export interface RemoteConnection {
+    /** Resolves the endpoint for a single browser launch. The `token` identifies the session for release. */
+    resolve(options?: {
+        proxyUrl?: string;
+    }): Promise<{
+        url: string;
+        token: number;
+    }>;
+    /** Releases the remote session for `token`. Idempotent — safe to call from both `close()` and `kill()`. */
+    release(token: number): Promise<void>;
+}
+/**
+ * Per-plugin remote connection parameters, passed to {@link BrowserPlugin.useRemoteConnection}.
+ * The endpoint is supplied per-launch via {@link RemoteConnection}; these are the static connect()
+ * parameters (protocol, headers, timeouts, …).
+ */
+export interface RemoteConnectionParameters {
+    /**
+     * Playwright only: which protocol to connect with. `'cdp'` uses `connectOverCDP()` (the default),
+// @ts-ignore optional peer dependency or compatibility with es2022
+     * `'playwright'` uses `connect()` (Playwright's own WebSocket protocol). Ignored by Puppeteer.
+     */
+    protocol?: 'cdp' | 'playwright';
+    /** Extra options forwarded to the library `connect()` / `connectOverCDP()` call (endpoint excluded). */
+    connectOptions?: Record<string, unknown>;
+}
+export interface RemoteBrowserPoolOptions {
+    /**
+     * The browser plugin(s) used to connect to the remote service — e.g. `new PlaywrightPlugin(playwright.chromium)`
+     * or `new PuppeteerPlugin(puppeteer)`. The pool configures them for remote connection; do not set a local
+     * `launchOptions` on them.
+     */
+    browserPlugins: BrowserPlugin[];
+    /**
+     * The remote browser endpoint: a static URL, a function returning one per launch, or a
+     * {@link RemoteBrowserProvider} instance encapsulating a session create/release lifecycle.
+     */
+    endpoint: RemoteBrowserEndpoint | RemoteBrowserProvider<any>;
+    /**
+     * Cleanup callback invoked when a browser closes, crashes, or the pool is destroyed. Receives the
+     * `context` returned by a function endpoint. Errors are caught and logged. Ignored when `endpoint`
+     * is a {@link RemoteBrowserProvider} (its own `release()` is used instead).
+     */
+    release?: (info: {
+        endpoint: string;
+        context?: Record<string, unknown>;
+    }) => unknown;
+    /**
+     * Maximum number of remote browsers open at once. When reached, {@link RemoteBrowserPool.newPage|newPage}
+     * waits for a browser to close before connecting a new one. Set it to your service's concurrent-session limit
+     * to avoid `429` errors. Defaults to the {@link RemoteBrowserProvider.maxOpenBrowsers|provider's value}, or
+     * `Infinity`.
+     */
+    maxOpenBrowsers?: number;
+    /** Static connect() parameters (Playwright protocol selection, headers, timeouts, …). */
+    connection?: RemoteConnectionParameters;
+    /** Extra {@link BrowserPool} options (lifecycle hooks, page limits, fingerprinting, …). */
+    browserPoolOptions?: Omit<BrowserPoolOptions, 'browserPlugins'> & BrowserPoolHooks<any, any, any>;
+    /**
+     * Fallback poll interval (ms) while waiting for a free browser slot. The wait is event-driven; this only bounds it.
+     * @default 500
+     * @internal
+     */
+    slotPollIntervalMillis?: number;
+}
+/**
+ * The remote-connection configuration a browser crawler accepts on its `remoteBrowser` option: the
+ * {@link RemoteBrowserPoolOptions} minus the `browserPlugins` (the crawler builds the correct one for its
+ * browser, which is what makes this path mismatch-proof) and minus `browserPoolOptions` — tuning the wrapping
+ * pool means building the pool yourself, through the `remote*BrowserPool()` factory for your crawler.
+ */
+export type CrawlerRemoteBrowserOptions = Omit<RemoteBrowserPoolOptions, 'browserPlugins' | 'browserPoolOptions'>;
+/**
+ * An {@link IBrowserPool} implementation for remote browser services.
+ *
+ * Unlike configuring a remote browser through a crawler's `launchContext`, this pool is the single owner
+ * of all remote-session concerns:
+ * - **endpoint resolution** — static URL, per-launch function, or {@link RemoteBrowserProvider};
+ * - **release lifecycle** — `release()` fires exactly once per session on close/crash/teardown (no leaks,
+ *   no double-release);
+ * - **concurrency** — {@link RemoteBrowserPoolOptions.maxOpenBrowsers|maxOpenBrowsers} is enforced inside
+ *   {@link RemoteBrowserPool.newPage|newPage}, which waits for a free slot rather than overshooting.
+ *
+ * The wrapped {@link BrowserPool} and its plugin only perform the library-specific `connect()` call.
+ *
+ * Pass an instance as the crawler's `browserPool` option:
+ *
+ * ```typescript
+ * import { PlaywrightPlugin, RemoteBrowserPool } from '@crawlee/browser-pool';
+ * import { PlaywrightCrawler } from 'crawlee';
+// @ts-ignore optional peer dependency or compatibility with es2022
+ * import playwright from 'playwright';
+ *
+ * const browserPool = new RemoteBrowserPool({
+ *     browserPlugins: [new PlaywrightPlugin(playwright.chromium)],
+ *     endpoint: 'wss://production-sfo.browserless.io?token=xxx',
+ *     maxOpenBrowsers: 2,
+ * });
+ *
+ * const crawler = new PlaywrightCrawler({ browserPool });
+ * ```
+ *
+ * @category Browser management
+ */
+export declare class RemoteBrowserPool<Page = unknown> implements IBrowserPool<Page> {
+    #private;
+    /**
+     * The wrapped pool that performs the remote connections and serves pages.
+     *
+     * @internal
+     */
+    readonly browserPool: BrowserPool;
+    constructor(options: RemoteBrowserPoolOptions);
+    /** Maximum number of remote browsers that may be open at the same time. */
+    get maxOpenBrowsers(): number;
+    set maxOpenBrowsers(value: number);
+    /**
+     * Opens a new page, waiting first until {@link RemoteBrowserPoolOptions.maxOpenBrowsers|maxOpenBrowsers}
+     * allows it (either a new browser slot is free, or an active browser still has page capacity).
+     */
+    newPage(options?: NewPageOptions): Promise<Page>;
+    closePage(page: Page, options?: {
+        error?: Error;
+    }): Promise<void>;
+    extractPageState(page: Page): Promise<PageState>;
+    injectPageState(page: Page, state: PageState): Promise<void>;
+    /**
+     * Closes all browsers and releases their remote sessions, leaving the pool usable. Closing a browser is what
+     * releases its session (see the constructor), so this needs no separate release pass.
+     */
+    releaseAllBrowsers(): Promise<void>;
+    [Symbol.asyncDispose](): Promise<void>;
+    /** Closes all browsers, releases any still-open remote sessions, and tears down the wrapped pool. */
+    destroy(): Promise<void>;
+    /** Resolves once the wrapped pool can serve another page without exceeding `maxOpenBrowsers`. */
+    private waitForFreeSlot;
+    /**
+     * Resolves on the next browser-retired / page-closed event, or after `slotPollIntervalMillis`. All
+     * concurrently-waiting `newPage` calls share a single promise (and a single pair of event listeners)
+     * per tick, so a fleet of saturated callers doesn't fan out into N listener pairs on the pool.
+     */
+    private nextCapacityChange;
+}