@crawlee/browser-pool 4.0.0-beta.1 → 4.0.0-beta.100

package/browser-pool.d.ts

@@ -1,3 +1,4 @@
+import type { IBrowserPool, NewPageOptions, PageState } from '@crawlee/types';
 import type { BrowserFingerprintWithHeaders } from 'fingerprint-generator';
 import { FingerprintGenerator } from 'fingerprint-generator';
 import { FingerprintInjector } from 'fingerprint-injector';
@@ -246,9 +247,10 @@ export interface BrowserPoolHooks<BC extends BrowserController, LC extends Launc
  * });
  * ```
  */
-export declare class BrowserPool<Options extends BrowserPoolOptions = BrowserPoolOptions, BrowserPlugins extends BrowserPlugin[] = InferBrowserPluginArray<Options['browserPlugins']>, BrowserControllerReturn extends BrowserController = ReturnType<BrowserPlugins[number]['createController']>, LaunchContextReturn extends LaunchContext = ReturnType<BrowserPlugins[number]['createLaunchContext']>, PageOptions = Parameters<BrowserControllerReturn['newPage']>[0], PageReturn extends UnwrapPromise<ReturnType<BrowserControllerReturn['newPage']>> = UnwrapPromise<ReturnType<BrowserControllerReturn['newPage']>>> extends TypedEmitter<BrowserPoolEvents<BrowserControllerReturn, PageReturn>> {
+export declare class BrowserPool<Options extends BrowserPoolOptions = BrowserPoolOptions, BrowserPlugins extends BrowserPlugin[] = InferBrowserPluginArray<Options['browserPlugins']>, BrowserControllerReturn extends BrowserController = ReturnType<BrowserPlugins[number]['createController']>, LaunchContextReturn extends LaunchContext = ReturnType<BrowserPlugins[number]['createLaunchContext']>, PageOptions = Parameters<BrowserControllerReturn['newPage']>[0], PageReturn extends UnwrapPromise<ReturnType<BrowserControllerReturn['newPage']>> = UnwrapPromise<ReturnType<BrowserControllerReturn['newPage']>>> extends TypedEmitter<BrowserPoolEvents<BrowserControllerReturn, PageReturn>> implements IBrowserPool<PageReturn> {
     browserPlugins: BrowserPlugins;
     maxOpenPagesPerBrowser: number;
+    maxOpenBrowsers: number;
     retireBrowserAfterPageCount: number;
     operationTimeoutMillis: number;
     closeInactiveBrowserAfterMillis: number;
@@ -263,6 +265,7 @@ export declare class BrowserPool<Options extends BrowserPoolOptions = BrowserPoo
     pageCounter: number;
     pages: Map<string, PageReturn>;
     pageIds: WeakMap<PageReturn, string>;
+    startingBrowserControllers: Set<BrowserControllerReturn>;
     activeBrowserControllers: Set<BrowserControllerReturn>;
     retiredBrowserControllers: Set<BrowserControllerReturn>;
     pageToBrowserController: WeakMap<PageReturn, BrowserControllerReturn>;
@@ -272,11 +275,24 @@ export declare class BrowserPool<Options extends BrowserPoolOptions = BrowserPoo
     private browserKillerInterval?;
     private browserRetireInterval?;
     private limiter;
+    private log;
     constructor(options: Options & BrowserPoolHooks<BrowserControllerReturn, LaunchContextReturn, PageReturn>);
     /**
      * Opens a new page in one of the running browsers or launches
      * a new browser and opens a page there, if no browsers are active,
      * or their page limits have been exceeded.
+     *
+     * **Session injection (best-effort):** When a {@link NewPageOptions.session|session} is
+     * provided, this implementation uses it as a cache key for browser fingerprints (when
+     * fingerprinting is enabled) and reads
+     * {@link ProxyInfo.url|session.proxyInfo.url} /
+     * {@link ProxyInfo.ignoreTlsErrors|session.proxyInfo.ignoreTlsErrors} as defaults
+     * for `proxyUrl` and `ignoreTlsErrors` respectively. Explicit `proxyUrl` /
+     * `ignoreTlsErrors` values in the options take precedence.
+     *
+     * Beyond fingerprint caching and proxy configuration, no other session
+     * properties are consumed — cookie and header injection remain the
+     * crawler's responsibility.
      */
     newPage(options?: BrowserPoolNewPageOptions<PageOptions, BrowserPlugins[number]>): Promise<PageReturn>;
     /**
@@ -346,6 +362,43 @@ export declare class BrowserPool<Options extends BrowserPoolOptions = BrowserPoo
      * closed after all its pages are closed.
      */
     retireBrowserByPage(page: PageReturn): void;
+    /**
+     * Releases a page back to the pool. The page is closed and, if the
+     * optional `error` is a {@link SessionError}, the browser controller
+     * that served the page is retired so that its tainted state (cookies,
+     * storage, etc.) cannot leak into future sessions.
+     *
+     * This is the primary way the crawler should return pages to the pool.
+     *
+     * @param page The page to release.
+     * @param options.error The error that caused the page to be released, if any.
+     */
+    closePage(page: PageReturn, options?: {
+        error?: Error;
+    }): Promise<void>;
+    /**
+     * Extracts the relevant state (currently just cookies) from a page via its
+     * owning {@link BrowserController}. Returns empty state when the page is
+     * no longer associated with a controller.
+     *
+     * As with {@link BrowserPool.injectPageState}, cookies are isolated per
+     * page only when the pool is configured with `useIncognitoPages: true`.
+     * With the default `useIncognitoPages: false`, the extracted cookies
+     * include those set by any sibling page sharing the same browser.
+     */
+    extractPageState(page: PageReturn): Promise<PageState>;
+    /**
+     * Injects state into a page via its owning {@link BrowserController}.
+     *
+     * No-op when the page is no longer associated with a controller.
+     *
+     * Note that cookies are isolated per page only when the pool is configured
+     * with `useIncognitoPages: true` — each page then gets its own browser
+     * context. With the default `useIncognitoPages: false`, all pages in a
+     * browser share a single context, so injected cookies are visible to every
+     * page served by that browser.
+     */
+    injectPageState(page: PageReturn, state: PageState): Promise<void>;
     /**
      * Removes all active browsers from the pool. The browsers will be
      * closed after all their pages are closed.
@@ -373,15 +426,45 @@ export declare class BrowserPool<Options extends BrowserPoolOptions = BrowserPoo
     private _overridePageClose;
     private _executeHooks;
     private _closeRetiredBrowserWithNoPages;
+    /**
+     * Returns `true` if the pool can accept a new browser launch without exceeding
+     * {@link BrowserPoolOptions.maxOpenBrowsers}. Counts starting, active, and retired browsers.
+     */
+    hasFreeBrowserSlot(): boolean;
+    /**
+     * Returns `true` if any active browser has room for another page.
+     */
+    hasActiveBrowserWithFreeCapacity(): boolean;
     private _initializeFingerprinting;
     private _addFingerprintHooks;
 }
-export interface BrowserPoolNewPageOptions<PageOptions, BP extends BrowserPlugin> {
+export interface BrowserPoolNewPageOptions<PageOptions, BP extends BrowserPlugin> extends NewPageOptions {
+    /**
+     * The proxy URL the pool uses internally to route the page: it keys browser
+     * reuse (with `browserPerProxy`, only a browser already on this proxy is
+     * reused), configures the launched browser, and is applied to incognito
+     * pages. When omitted, it is derived from the
+     * {@link NewPageOptions.session|session}'s `proxyInfo`; an explicit value
+     * here takes precedence.
+     *
+     * This is an implementation detail of the built-in `BrowserPool`'s proxy
+     * handling and is intentionally not part of the {@link IBrowserPool}
+     * contract — through that interface the proxy is supplied via the session.
+     */
+    proxyUrl?: string;
     /**
-     * Assign a custom ID to the page. If you don't a random string ID
-     * will be generated.
+     * Disable TLS certificate verification for MITM proxies. Applied both when
+     * launching a new browser and when creating a page in an existing one. When
+     * omitted, it is derived from the
+     * {@link NewPageOptions.session|session}'s `proxyInfo`; an explicit value
+     * here takes precedence.
+     *
+     * This is an implementation detail of the built-in `BrowserPool` and is
+     * intentionally not part of the {@link IBrowserPool} contract — through
+     * that interface, configure it via the session's `proxyInfo` or through the
+     * browser's `launchOptions`.
      */
-    id?: string;
+    ignoreTlsErrors?: boolean;
     /**
      * Some libraries (Playwright) allow you to open new pages with specific
      * options. Use this property to set those options.
@@ -396,14 +479,6 @@ export interface BrowserPoolNewPageOptions<PageOptions, BP extends BrowserPlugin
      * see the `newPageInNewBrowser` function.
      */
     browserPlugin?: BP;
-    /**
-     * Proxy URL.
-     */
-    proxyUrl?: string;
-    /**
-     * Proxy tier.
-     */
-    proxyTier?: number;
 }
 export interface BrowserPoolNewPageInNewBrowserOptions<PageOptions, BP extends BrowserPlugin> {
     /**
@@ -434,4 +509,3 @@ export interface BrowserPoolNewPageInNewBrowserOptions<PageOptions, BP extends B
      */
     launchOptions?: BP['launchOptions'];
 }
-//# sourceMappingURL=browser-pool.d.ts.map

package/browser-pool.js

@@ -1,3 +1,5 @@
+import { AsyncResource } from 'node:async_hooks';
+import { SessionError, serviceLocator } from '@crawlee/core';
 import { FingerprintGenerator } from 'fingerprint-generator';
 import { FingerprintInjector } from 'fingerprint-injector';
 import { nanoid } from 'nanoid';
@@ -7,7 +9,7 @@ import QuickLRU from 'quick-lru';
 import { TypedEmitter } from 'tiny-typed-emitter';
 import { addTimeoutToPromise, tryCancel } from '@apify/timeout';
 import { createFingerprintPreLaunchHook, createPostPageCreateHook, createPrePageCreateHook, } from './fingerprinting/hooks.js';
-import { log } from './logger.js';
+const PAGE_CLOSE_TIMEOUT_MILLIS = 5000;
 const PAGE_CLOSE_KILL_TIMEOUT_MILLIS = 1000;
 const BROWSER_KILLER_INTERVAL_MILLIS = 10 * 1000;
 /**
@@ -60,6 +62,7 @@ const BROWSER_KILLER_INTERVAL_MILLIS = 10 * 1000;
 export class BrowserPool extends TypedEmitter {
     browserPlugins;
     maxOpenPagesPerBrowser;
+    maxOpenBrowsers;
     retireBrowserAfterPageCount;
     operationTimeoutMillis;
     closeInactiveBrowserAfterMillis;
@@ -74,6 +77,7 @@ export class BrowserPool extends TypedEmitter {
     pageCounter = 0;
     pages = new Map();
     pageIds = new WeakMap();
+    startingBrowserControllers = new Set();
     activeBrowserControllers = new Set();
     retiredBrowserControllers = new Set();
     pageToBrowserController = new WeakMap();
@@ -83,8 +87,10 @@ export class BrowserPool extends TypedEmitter {
     browserKillerInterval = setInterval(async () => this._closeInactiveRetiredBrowsers(), BROWSER_KILLER_INTERVAL_MILLIS);
     browserRetireInterval;
     limiter = pLimit(1);
+    log;
     constructor(options) {
         super();
+        this.log = serviceLocator.getLogger().child({ prefix: 'BrowserPool' });
         this.browserKillerInterval.unref();
         ow(options, ow.object.exactShape({
             browserPlugins: ow.array.minLength(1),
@@ -114,6 +120,7 @@ export class BrowserPool extends TypedEmitter {
         }
         this.browserPlugins = browserPlugins;
         this.maxOpenPagesPerBrowser = maxOpenPagesPerBrowser;
+        this.maxOpenBrowsers = Infinity;
         this.retireBrowserAfterPageCount = retireBrowserAfterPageCount;
         this.operationTimeoutMillis = operationTimeoutSecs * 1000;
         this.closeInactiveBrowserAfterMillis = closeInactiveBrowserAfterSecs * 1000;
@@ -142,23 +149,46 @@ export class BrowserPool extends TypedEmitter {
      * Opens a new page in one of the running browsers or launches
      * a new browser and opens a page there, if no browsers are active,
      * or their page limits have been exceeded.
+     *
+     * **Session injection (best-effort):** When a {@link NewPageOptions.session|session} is
+     * provided, this implementation uses it as a cache key for browser fingerprints (when
+     * fingerprinting is enabled) and reads
+     * {@link ProxyInfo.url|session.proxyInfo.url} /
+     * {@link ProxyInfo.ignoreTlsErrors|session.proxyInfo.ignoreTlsErrors} as defaults
+     * for `proxyUrl` and `ignoreTlsErrors` respectively. Explicit `proxyUrl` /
+     * `ignoreTlsErrors` values in the options take precedence.
+     *
+     * Beyond fingerprint caching and proxy configuration, no other session
+     * properties are consumed — cookie and header injection remain the
+     * crawler's responsibility.
      */
     async newPage(options = {}) {
-        const { id = nanoid(), pageOptions, browserPlugin = this._pickBrowserPlugin(), proxyUrl, proxyTier } = options;
+        const { id = nanoid(), pageOptions, browserPlugin = this._pickBrowserPlugin(), session, proxyUrl = session?.proxyInfo?.url, ignoreTlsErrors = session?.proxyInfo?.ignoreTlsErrors, } = options;
         if (this.pages.has(id)) {
             throw new Error(`Page with ID: ${id} already exists.`);
         }
         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.
+        // 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(async () => {
-            let browserController = this._pickBrowserWithFreeCapacity(browserPlugin, { proxyTier, proxyUrl });
+        return this.limiter(AsyncResource.bind(async () => {
+            let browserController = this._pickBrowserWithFreeCapacity(browserPlugin, { proxyUrl });
             if (!browserController)
-                browserController = await this._launchBrowser(id, { browserPlugin, proxyTier, proxyUrl });
+                browserController = await this._launchBrowser(id, {
+                    browserPlugin,
+                    proxyUrl,
+                    ignoreTlsErrors,
+                });
             tryCancel();
-            return await this._createPageForBrowser(id, browserController, pageOptions, proxyUrl);
-        });
+            return await this._createPageForBrowser(id, browserController, pageOptions, proxyUrl, ignoreTlsErrors);
+        }));
     }
     /**
      * Unlike {@link newPage}, `newPageInNewBrowser` always launches a new
@@ -238,7 +268,7 @@ export class BrowserPool extends TypedEmitter {
     getPageId(page) {
         return this.pageIds.get(page);
     }
-    async _createPageForBrowser(pageId, browserController, pageOptions = {}, proxyUrl) {
+    async _createPageForBrowser(pageId, browserController, pageOptions = {}, proxyUrl, ignoreTlsErrors) {
         // This is needed for concurrent newPage calls to wait for the browser launch.
         // It's not ideal though, we need to come up with a better API.
         // eslint-disable-next-line dot-notation -- accessing private property
@@ -247,6 +277,12 @@ export class BrowserPool extends TypedEmitter {
         const finalPageOptions = browserController.launchContext.useIncognitoPages ? pageOptions : undefined;
         if (finalPageOptions) {
             Object.assign(finalPageOptions, browserController.normalizeProxyOptions(proxyUrl, pageOptions));
+            if (ignoreTlsErrors) {
+                Object.assign(finalPageOptions, {
+                    ignoreHTTPSErrors: true,
+                    acceptInsecureCerts: true,
+                });
+            }
         }
         await this._executeHooks(this.prePageCreateHooks, pageId, browserController, finalPageOptions);
         tryCancel();
@@ -278,11 +314,14 @@ export class BrowserPool extends TypedEmitter {
      *
      */
     retireBrowserController(browserController) {
-        const hasBeenRetiredOrKilled = !this.activeBrowserControllers.has(browserController);
+        const isStarting = this.startingBrowserControllers.has(browserController);
+        const isActive = this.activeBrowserControllers.has(browserController);
+        const hasBeenRetiredOrKilled = !isStarting && !isActive;
         if (hasBeenRetiredOrKilled)
             return;
         this.retiredBrowserControllers.add(browserController);
         this.emit("browserRetired" /* BROWSER_POOL_EVENTS.BROWSER_RETIRED */, browserController);
+        this.startingBrowserControllers.delete(browserController);
         this.activeBrowserControllers.delete(browserController);
     }
     /**
@@ -294,12 +333,65 @@ export class BrowserPool extends TypedEmitter {
         if (browserController)
             this.retireBrowserController(browserController);
     }
+    /**
+     * Releases a page back to the pool. The page is closed and, if the
+     * optional `error` is a {@link SessionError}, the browser controller
+     * that served the page is retired so that its tainted state (cookies,
+     * storage, etc.) cannot leak into future sessions.
+     *
+     * This is the primary way the crawler should return pages to the pool.
+     *
+     * @param page The page to release.
+     * @param options.error The error that caused the page to be released, if any.
+     */
+    async closePage(page, options) {
+        if (options?.error instanceof SessionError) {
+            this.retireBrowserByPage(page);
+        }
+        // Puppeteer 25+ can hang `page.close()` indefinitely when the page's navigation was aborted, don't let it block the crawler.
+        await addTimeoutToPromise(async () => page.close(), PAGE_CLOSE_TIMEOUT_MILLIS, `page.close() timed out after ${PAGE_CLOSE_TIMEOUT_MILLIS / 1000} seconds`);
+    }
+    /**
+     * Extracts the relevant state (currently just cookies) from a page via its
+     * owning {@link BrowserController}. Returns empty state when the page is
+     * no longer associated with a controller.
+     *
+     * As with {@link BrowserPool.injectPageState}, cookies are isolated per
+     * page only when the pool is configured with `useIncognitoPages: true`.
+     * With the default `useIncognitoPages: false`, the extracted cookies
+     * include those set by any sibling page sharing the same browser.
+     */
+    async extractPageState(page) {
+        const controller = this.getBrowserControllerByPage(page);
+        if (!controller) {
+            return { cookies: [] };
+        }
+        return { cookies: await controller.getCookies(page) };
+    }
+    /**
+     * Injects state into a page via its owning {@link BrowserController}.
+     *
+     * No-op when the page is no longer associated with a controller.
+     *
+     * Note that cookies are isolated per page only when the pool is configured
+     * with `useIncognitoPages: true` — each page then gets its own browser
+     * context. With the default `useIncognitoPages: false`, all pages in a
+     * browser share a single context, so injected cookies are visible to every
+     * page served by that browser.
+     */
+    async injectPageState(page, state) {
+        const controller = this.getBrowserControllerByPage(page);
+        if (!controller) {
+            return;
+        }
+        await controller.setCookies(page, state.cookies);
+    }
     /**
      * Removes all active browsers from the pool. The browsers will be
      * closed after all their pages are closed.
      */
     retireAllBrowsers() {
-        this.activeBrowserControllers.forEach((controller) => {
+        [...this.startingBrowserControllers, ...this.activeBrowserControllers].forEach((controller) => {
             this.retireBrowserController(controller);
         });
     }
@@ -326,23 +418,36 @@ export class BrowserPool extends TypedEmitter {
         this._teardown();
     }
     _teardown() {
+        this.startingBrowserControllers.clear();
         this.activeBrowserControllers.clear();
         this.retiredBrowserControllers.clear();
         this.removeAllListeners();
     }
     _getAllBrowserControllers() {
-        return new Set([...this.activeBrowserControllers, ...this.retiredBrowserControllers]);
+        return new Set([
+            ...this.startingBrowserControllers,
+            ...this.activeBrowserControllers,
+            ...this.retiredBrowserControllers,
+        ]);
     }
     async _launchBrowser(pageId, options) {
-        const { browserPlugin, launchOptions, proxyTier, proxyUrl } = options;
+        const { browserPlugin, launchOptions, proxyUrl, ignoreTlsErrors } = options;
         const browserController = browserPlugin.createController();
-        this.activeBrowserControllers.add(browserController);
+        this.startingBrowserControllers.add(browserController);
         const launchContext = browserPlugin.createLaunchContext({
             id: pageId,
             launchOptions,
-            proxyTier,
             proxyUrl,
         });
+        // Disable SSL verification for MITM proxies
+        if (ignoreTlsErrors) {
+            /**
+             * @see https://playwright.dev/docs/api/class-browser/#browser-new-context
+             * @see https://github.com/puppeteer/puppeteer/blob/main/docs/api.md
+             */
+            launchContext.launchOptions.ignoreHTTPSErrors = true;
+            launchContext.launchOptions.acceptInsecureCerts = true;
+        }
         try {
             // If the hooks or the launch fails, we need to delete the controller,
             // because otherwise it would be stuck in limbo without a browser.
@@ -353,11 +458,10 @@ export class BrowserPool extends TypedEmitter {
             browserController.assignBrowser(browser, launchContext);
         }
         catch (err) {
-            this.activeBrowserControllers.delete(browserController);
+            this.startingBrowserControllers.delete(browserController);
             throw err;
         }
-        log.debug('Launched new browser.', { id: browserController.id });
-        browserController.proxyTier = proxyTier;
+        this.log.debug('Launched new browser.', { id: browserController.id });
         browserController.proxyUrl = proxyUrl;
         try {
             // If the launch fails on the post-launch hooks, we need to clean up
@@ -365,9 +469,9 @@ export class BrowserPool extends TypedEmitter {
             await this._executeHooks(this.postLaunchHooks, pageId, browserController);
         }
         catch (err) {
-            this.activeBrowserControllers.delete(browserController);
+            this.startingBrowserControllers.delete(browserController);
             browserController.close().catch((closeErr) => {
-                log.error(`Could not close browser whose post-launch hooks failed.\nCause:${closeErr.message}`, {
+                this.log.error(`Could not close browser whose post-launch hooks failed.\nCause:${closeErr.message}`, {
                     id: browserController.id,
                 });
             });
@@ -375,6 +479,8 @@ export class BrowserPool extends TypedEmitter {
         }
         tryCancel();
         browserController.activate();
+        this.startingBrowserControllers.delete(browserController);
+        this.activeBrowserControllers.add(browserController);
         this.emit("browserLaunched" /* BROWSER_POOL_EVENTS.BROWSER_LAUNCHED */, browserController);
         return browserController;
     }
@@ -392,13 +498,11 @@ export class BrowserPool extends TypedEmitter {
             const hasCapacity = controller.activePages < this.maxOpenPagesPerBrowser;
             const isCorrectPlugin = controller.browserPlugin === browserPlugin;
             const isSameProxyUrl = controller.proxyUrl === options?.proxyUrl;
-            const isCorrectProxyTier = controller.proxyTier === options?.proxyTier;
             return (isCorrectPlugin &&
                 hasCapacity &&
-                ((!controller.launchContext.browserPerProxy && !options?.proxyTier) ||
-                    (options?.proxyTier && isCorrectProxyTier) ||
+                (!controller.launchContext.browserPerProxy ||
                     (options?.proxyUrl && isSameProxyUrl) ||
-                    (!options?.proxyUrl && !options?.proxyTier && !controller.proxyUrl && !controller.proxyTier)));
+                    (!options?.proxyUrl && !controller.proxyUrl)));
         });
     }
     async _closeInactiveRetiredBrowsers() {
@@ -409,14 +513,14 @@ export class BrowserPool extends TypedEmitter {
             const isBrowserEmpty = controller.activePages === 0;
             if (isBrowserIdle || isBrowserEmpty) {
                 const { id } = controller;
-                log.debug('Closing retired browser.', { id });
+                this.log.debug('Closing retired browser.', { id });
                 await controller.close();
                 this.retiredBrowserControllers.delete(controller);
                 closedBrowserIds.push(id);
             }
         }
         if (closedBrowserIds.length) {
-            log.debug('Closed retired browsers.', {
+            this.log.debug('Closed retired browsers.', {
                 count: closedBrowserIds.length,
                 closedBrowserIds,
             });
@@ -429,7 +533,7 @@ export class BrowserPool extends TypedEmitter {
         page.close = async (...args) => {
             await this._executeHooks(this.prePageCloseHooks, page, browserController);
             await originalPageClose.apply(page, args).catch((err) => {
-                log.debug(`Could not close page.\nCause:${err.message}`, { id: browserController.id });
+                this.log.debug(`Could not close page.\nCause:${err.message}`, { id: browserController.id });
             });
             await this._executeHooks(this.postPageCloseHooks, pageId, browserController);
             this.pages.delete(pageId);
@@ -447,13 +551,33 @@ export class BrowserPool extends TypedEmitter {
             // Run this with a delay, otherwise page.close()
             // might fail with "Protocol error (Target.closeTarget): Target closed."
             setTimeout(() => {
-                log.debug('Closing retired browser because it has no active pages', { id: browserController.id });
+                this.log.debug('Closing retired browser because it has no active pages', { id: browserController.id });
                 void browserController.close().finally(() => {
                     this.retiredBrowserControllers.delete(browserController);
                 });
             }, PAGE_CLOSE_KILL_TIMEOUT_MILLIS);
         }
     }
+    /**
+     * Returns `true` if the pool can accept a new browser launch without exceeding
+     * {@link BrowserPoolOptions.maxOpenBrowsers}. Counts starting, active, and retired browsers.
+     */
+    hasFreeBrowserSlot() {
+        const total = this.startingBrowserControllers.size +
+            this.activeBrowserControllers.size +
+            this.retiredBrowserControllers.size;
+        return total < this.maxOpenBrowsers;
+    }
+    /**
+     * Returns `true` if any active browser has room for another page.
+     */
+    hasActiveBrowserWithFreeCapacity() {
+        for (const controller of this.activeBrowserControllers) {
+            if (controller.activePages < this.maxOpenPagesPerBrowser)
+                return true;
+        }
+        return false;
+    }
     _initializeFingerprinting() {
         const { useFingerprintCache = true, fingerprintCacheSize = 10_000 } = this.fingerprintOptions;
         this.fingerprintGenerator = new FingerprintGenerator(this.fingerprintOptions.fingerprintGeneratorOptions);
@@ -474,4 +598,3 @@ export class BrowserPool extends TypedEmitter {
         this.postPageCreateHooks = [createPostPageCreateHook(this.fingerprintInjector), ...this.postPageCreateHooks];
     }
 }
-//# sourceMappingURL=browser-pool.js.map

package/container-proxy-server.d.ts

@@ -9,4 +9,3 @@ export declare function createProxyServerForContainers(fallbackProxyUrl?: string
     ipToProxy: Map<string, string>;
     close(closeConnections: boolean): Promise<void>;
 }>;
-//# sourceMappingURL=container-proxy-server.d.ts.map

package/container-proxy-server.js

@@ -40,4 +40,3 @@ export async function createProxyServerForContainers(fallbackProxyUrl) {
         },
     };
 }
-//# sourceMappingURL=container-proxy-server.js.map

package/events.d.ts

@@ -8,4 +8,3 @@ export declare const enum BROWSER_POOL_EVENTS {
 export declare const enum BROWSER_CONTROLLER_EVENTS {
     BROWSER_CLOSED = "browserClosed"
 }
-//# sourceMappingURL=events.d.ts.map

package/events.js

@@ -10,4 +10,3 @@ export var BROWSER_CONTROLLER_EVENTS;
 (function (BROWSER_CONTROLLER_EVENTS) {
     BROWSER_CONTROLLER_EVENTS["BROWSER_CLOSED"] = "browserClosed";
 })(BROWSER_CONTROLLER_EVENTS || (BROWSER_CONTROLLER_EVENTS = {}));
-//# sourceMappingURL=events.js.map

package/fingerprinting/hooks.d.ts

@@ -14,4 +14,3 @@ export declare function createPrePageCreateHook(): (_pageId: string, browserCont
  * @internal
  */
 export declare function createPostPageCreateHook(fingerprintInjector: FingerprintInjector): (page: any, browserController: BrowserController) => Promise<void>;
-//# sourceMappingURL=hooks.d.ts.map

package/fingerprinting/hooks.js

@@ -1,27 +1,39 @@
 import { PlaywrightPlugin } from '../playwright/playwright-plugin.js';
 import { PuppeteerPlugin } from '../puppeteer/puppeteer-plugin.js';
 import { getGeneratorDefaultOptions } from './utils.js';
+function applySessionHints(base, fingerprint) {
+    if (!fingerprint)
+        return base;
+    return {
+        ...base,
+        ...(fingerprint.browser ? { browsers: [{ name: fingerprint.browser }] } : {}),
+        ...(fingerprint.platform ? { operatingSystems: [fingerprint.platform] } : {}),
+        ...(fingerprint.device ? { devices: [fingerprint.device] } : {}),
+    };
+}
 /**
  * @internal
  */
 export function createFingerprintPreLaunchHook(browserPool) {
     const { fingerprintGenerator, fingerprintCache, fingerprintOptions: { fingerprintGeneratorOptions }, } = browserPool;
     return (_pageId, launchContext) => {
+        // Remote browsers may have their own fingerprinting — skip local fingerprint injection
+        if (launchContext.isRemote)
+            return;
         const { useIncognitoPages } = launchContext;
-        const cacheKey = launchContext.session?.id ?? launchContext.proxyUrl;
+        const session = launchContext.session;
+        const cacheKey = session?.id ?? launchContext.proxyUrl;
         const { launchOptions } = launchContext;
-        // If no options are passed we try to pass best default options as possible to match browser and OS.
-        const fingerprintGeneratorFinalOptions = fingerprintGeneratorOptions || getGeneratorDefaultOptions(launchContext);
         let fingerprint;
         if (cacheKey && fingerprintCache?.has(cacheKey)) {
             fingerprint = fingerprintCache.get(cacheKey);
         }
-        else if (cacheKey) {
-            fingerprint = fingerprintGenerator.getFingerprint(fingerprintGeneratorFinalOptions);
-            fingerprintCache?.set(cacheKey, fingerprint);
-        }
         else {
-            fingerprint = fingerprintGenerator.getFingerprint(fingerprintGeneratorFinalOptions);
+            const baseOptions = fingerprintGeneratorOptions || getGeneratorDefaultOptions(launchContext);
+            const finalOptions = applySessionHints(baseOptions, session?.fingerprint);
+            fingerprint = fingerprintGenerator.getFingerprint(finalOptions);
+            if (cacheKey)
+                fingerprintCache?.set(cacheKey, fingerprint);
         }
         launchContext.extend({ fingerprint });
         if (useIncognitoPages) {
@@ -41,6 +53,8 @@ export function createFingerprintPreLaunchHook(browserPool) {
 export function createPrePageCreateHook() {
     return (_pageId, browserController, pageOptions) => {
         const { launchContext, browserPlugin } = browserController;
+        if (launchContext.isRemote)
+            return;
         const { fingerprint } = launchContext.fingerprint;
         if (launchContext.useIncognitoPages && browserPlugin instanceof PlaywrightPlugin && pageOptions) {
             pageOptions.userAgent ??= fingerprint.navigator.userAgent;
@@ -57,6 +71,8 @@ export function createPrePageCreateHook() {
 export function createPostPageCreateHook(fingerprintInjector) {
     return async (page, browserController) => {
         const { browserPlugin, launchContext } = browserController;
+        if (launchContext.isRemote)
+            return;
         const fingerprint = launchContext.fingerprint;
         // TODO this will require refactoring, we should use common API instead of branching based on plugin type,
         //  and there should be no public methods specific to some browser.
@@ -79,4 +95,3 @@ export function createPostPageCreateHook(fingerprintInjector) {
         }
     };
 }
-//# sourceMappingURL=hooks.js.map

package/fingerprinting/types.d.ts

@@ -61,4 +61,3 @@ export declare const enum DeviceCategory {
     desktop = "desktop"
 }
 export {};
-//# sourceMappingURL=types.d.ts.map

package/fingerprinting/types.js

@@ -32,4 +32,3 @@ export var DeviceCategory;
      */
     DeviceCategory["desktop"] = "desktop";
 })(DeviceCategory || (DeviceCategory = {}));
-//# sourceMappingURL=types.js.map

package/fingerprinting/utils.d.ts

@@ -1,4 +1,3 @@
 import type { LaunchContext } from '../launch-context.js';
 import type { FingerprintGeneratorOptions } from './types.js';
 export declare const getGeneratorDefaultOptions: (launchContext: LaunchContext) => FingerprintGeneratorOptions;
-//# sourceMappingURL=utils.d.ts.map

package/fingerprinting/utils.js

@@ -42,4 +42,3 @@ const getOperatingSystem = () => {
             return "linux" /* OperatingSystemsName.linux */;
     }
 };
-//# sourceMappingURL=utils.js.map