@crawlee/browser-pool 4.0.0-beta.25 → 4.0.0-beta.251

package/playwright/playwright-plugin.js

@@ -1,13 +1,11 @@
 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;
     async _launch(launchContext) {
         const { launchOptions, useIncognitoPages, userDataDir, proxyUrl } = launchContext;
         let browser;
@@ -20,7 +18,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 +30,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 +42,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 +57,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,27 +79,26 @@ 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) {
             const url = new URL(proxyUrl);
             launchOptions.proxy = {
-                server: url.origin,
+                server: `${url.protocol}//${url.host}`,
                 username: decodeURIComponent(url.username),
                 password: decodeURIComponent(url.password),
             };
         }
     }
-    _isChromiumBasedBrowser() {
+    isChromiumBasedBrowser() {
         const name = this.library.name();
         return name === 'chromium';
     }
 }
-//# sourceMappingURL=playwright-plugin.js.map

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/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

@@ -6,10 +6,18 @@ import { BrowserPlugin } from '../abstract-classes/browser-plugin.js';
 import type { LaunchContext } from '../launch-context.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: LaunchContext<typeof Puppeteer, PuppeteerTypes.LaunchOptions, PuppeteerTypes.Browser, PuppeteerNewPageOptions>): Promise<PuppeteerTypes.Browser>;
+    protected _launch(launchContext: PuppeteerLaunchContext): Promise<PuppeteerTypes.Browser>;
+    /** @internal */
+    protected isOldPuppeteerVersion(): Promise<boolean>;
+    /**
+     * Attaches page crash handling and the incognito-context-per-page `newPage` proxy. Shared by the local launch
+     * and {@link RemotePuppeteerPlugin}.
+     * @internal
+     */
+    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;
+    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,23 +1,16 @@
 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 {
     async _launch(launchContext) {
-        let oldPuppeteerVersion = false;
-        try {
-            const jsonPath = require.resolve('puppeteer/package.json');
-            const parsed = JSON.parse(await readFile(jsonPath, 'utf-8'));
-            const version = +parsed.version.split('.')[0];
-            oldPuppeteerVersion = version < 22;
-        }
-        catch {
-            // ignore
+        const oldPuppeteerVersion = await this.isOldPuppeteerVersion();
+        const { launchOptions, userDataDir, experimentalContainers, proxyUrl } = launchContext;
+        if (experimentalContainers) {
+            throw new Error('Experimental containers are only available with Playwright');
         }
-        const { launchOptions, userDataDir, useIncognitoPages, proxyUrl } = launchContext;
         launchOptions.userDataDir = launchOptions.userDataDir ?? userDataDir;
         if (launchOptions.headless === false) {
             if (Array.isArray(launchOptions.args)) {
@@ -30,45 +23,71 @@ export class PuppeteerPlugin extends BrowserPlugin {
         if (launchOptions.headless === true && oldPuppeteerVersion) {
             launchOptions.headless = 'new';
         }
-        let browser;
-        {
-            const [anonymizedProxyUrl, close] = await anonymizeProxySugar(proxyUrl);
-            if (proxyUrl) {
-                const proxyArg = `${PROXY_SERVER_ARG}${anonymizedProxyUrl ?? proxyUrl}`;
-                if (Array.isArray(launchOptions.args)) {
-                    launchOptions.args.push(proxyArg);
-                }
-                else {
-                    launchOptions.args = [proxyArg];
-                }
+        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);
             }
-            try {
-                browser = await this.library.launch(launchOptions);
-                if (anonymizedProxyUrl) {
-                    browser.on('disconnected', async () => {
-                        await close();
-                    });
-                }
+            else {
+                launchOptions.args = [proxyArg];
             }
-            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)");
+        }
+        let browser;
+        try {
+            browser = await this.library.launch(launchOptions);
+            if (anonymizedProxyUrl) {
+                browser.on('disconnected', async () => {
+                    await close();
+                });
             }
         }
-        browser.on('targetcreated', async (target) => {
+        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)");
+        }
+        return this.wrapBrowser(browser, launchContext, oldPuppeteerVersion);
+    }
+    /** @internal */
+    async isOldPuppeteerVersion() {
+        try {
+            const jsonPath = require.resolve('puppeteer/package.json');
+            const parsed = JSON.parse(await readFile(jsonPath, 'utf-8'));
+            return +parsed.version.split('.')[0] < 22;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Attaches page crash handling and the incognito-context-per-page `newPage` proxy. Shared by the local launch
+     * and {@link RemotePuppeteerPlugin}.
+     * @internal
+     */
+    wrapBrowser(browser, launchContext, oldPuppeteerVersion) {
+        const { useIncognitoPages, proxyUrl, ignoreProxyCertificate, isRemote } = launchContext;
+        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);
+        if (isRemote) {
+            browser.once('disconnected', () => {
+                browser.off('targetcreated', targetCreatedHandler);
+            });
+        }
         const boundMethods = [
             'newPage',
             'close',
@@ -78,6 +97,7 @@ export class PuppeteerPlugin extends BrowserPlugin {
             'version',
             'on',
             'process',
+            'pages',
         ].reduce((map, method) => {
             map[method] = browser[method]?.bind(browser);
             return map;
@@ -89,22 +109,30 @@ export class PuppeteerPlugin extends BrowserPlugin {
                     return async (...args) => {
                         let page;
                         if (useIncognitoPages) {
-                            const [anonymizedProxyUrl, close] = await anonymizeProxySugar(proxyUrl);
+                            // Proxy is managed by the remote service.
+                            const effectiveProxyUrl = isRemote ? 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 +167,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 +194,7 @@ export class PuppeteerPlugin extends BrowserPlugin {
         }
         */
     }
-    _isChromiumBasedBrowser(_launchContext) {
+    isChromiumBasedBrowser(_launchContext) {
         return true;
     }
 }
-//# sourceMappingURL=puppeteer-plugin.js.map

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

@@ -0,0 +1,22 @@
+// @ts-ignore optional peer dependency or compatibility with es2022
+import type Puppeteer from 'puppeteer';
+// @ts-ignore optional peer dependency or compatibility with es2022
+import type * as PuppeteerTypes from 'puppeteer';
+import type { BrowserPluginOptions, CreateLaunchContextOptions } from '../abstract-classes/browser-plugin.js';
+import { type RemoteBrowserOptions } from '../remote-browser-plugin.js';
+import type { PuppeteerNewPageOptions } from './puppeteer-controller.js';
+import { type PuppeteerLaunchContext, PuppeteerPlugin } from './puppeteer-plugin.js';
+export interface RemotePuppeteerPluginOptions extends BrowserPluginOptions<PuppeteerTypes.LaunchOptions>, RemoteBrowserOptions {
+}
+/**
+ * A {@link PuppeteerPlugin} that connects to a remote browser service (Browserbase, Browserless, Steel, …)
+ * over CDP instead of launching locally. `launchOptions` are ignored — the remote service owns the browser.
+ */
+export declare class RemotePuppeteerPlugin extends PuppeteerPlugin {
+    #private;
+    constructor(library: typeof Puppeteer, options: RemotePuppeteerPluginOptions);
+    createLaunchContext(options?: CreateLaunchContextOptions<typeof Puppeteer, PuppeteerTypes.LaunchOptions, PuppeteerTypes.Browser, PuppeteerNewPageOptions>): PuppeteerLaunchContext;
+    /** Skips the local proxy and webdriver-stealth preparation; the remote service owns the browser. */
+    launch(launchContext?: PuppeteerLaunchContext): Promise<PuppeteerTypes.Browser>;
+    protected _launch(launchContext: PuppeteerLaunchContext): Promise<PuppeteerTypes.Browser>;
+}

package/puppeteer/remote-puppeteer-plugin.js

@@ -0,0 +1,31 @@
+import { connectRemoteBrowser } from '../remote-browser-plugin.js';
+import { PuppeteerPlugin } from './puppeteer-plugin.js';
+/**
+ * A {@link PuppeteerPlugin} that connects to a remote browser service (Browserbase, Browserless, Steel, …)
+ * over CDP instead of launching locally. `launchOptions` are ignored — the remote service owns the browser.
+ */
+export class RemotePuppeteerPlugin extends PuppeteerPlugin {
+    #remote;
+    constructor(library, options) {
+        super(library, options);
+        this.#remote = options;
+        if (!this.useIncognitoPages) {
+            this.log.info('Remote Puppeteer connection — pages will share cookies and storage on the remote ' +
+                'browser instance (useIncognitoPages defaults to false).');
+        }
+    }
+    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 browser = await connectRemoteBrowser(this.#remote, launchContext.proxyUrl, this.log, async (url) => {
+            this.log.info('Connecting to remote browser via connect (CDP).');
+            return this.library.connect({ ...this.#remote.connectOptions, browserWSEndpoint: url });
+        });
+        return this.wrapBrowser(browser, launchContext, await this.isOldPuppeteerVersion());
+    }
+}

package/remote-browser-plugin.d.ts

@@ -0,0 +1,49 @@
+import type { CrawleeLogger } from '@crawlee/core';
+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 WebSocket / CDP URL to connect to. */
+    url: string;
+    /** Opaque per-session data (e.g. a session ID) passed back to `release`. */
+    context?: Record<string, unknown>;
+}
+/**
+ * A remote browser endpoint: either a static URL string, or a function called once per browser launch
+ * that returns the URL (optionally with a `context` for `release`). The function receives the proxy URL
+ * Crawlee resolved for the browser, so it can be forwarded to services that accept an external proxy.
+ */
+export type RemoteBrowserEndpoint = string | ((options?: {
+    proxyUrl?: string;
+}) => string | ResolvedRemoteEndpoint | Promise<string | ResolvedRemoteEndpoint>);
+/** Options shared by all remote browser plugins. */
+export interface RemoteBrowserOptions {
+    /**
+     * 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 the browser disconnects or the connection fails right after the endpoint
+     * resolved. 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;
+    /** Extra options forwarded to the library `connect()` call (endpoint excluded). */
+    connectOptions?: Record<string, unknown>;
+}
+/**
+ * Resolves `endpoint` for one launch, runs the library-specific `connect`, and ties the session's `release` to
+ * the browser's `disconnected` event. On connect failure the session is released and the error is wrapped in a
+ * {@link BrowserLaunchError}.
+ *
+ * @internal
+ */
+export declare function connectRemoteBrowser<Browser extends {
+    on(event: 'disconnected', listener: () => void): unknown;
+}>(options: RemoteBrowserOptions, proxyUrl: string | undefined, log: CrawleeLogger, connect: (url: string) => Promise<Browser>): Promise<Browser>;