@crawlee/browser 4.0.0-beta.125 → 4.0.0-beta.127

package/internals/browser-crawler.d.ts

@@ -1,6 +1,6 @@
 import type { AddRequestsBatchedResult, BasicCrawlerOptions, CrawlingContext, EnqueueLinksOptions, ErrorHandler, ExtractLinksOptions, GetUserDataFromRequest, LoadedRequest, Request, RequestHandler, RouterHandler } from '@crawlee/basic';
 import { BasicCrawler, ContextPipeline } from '@crawlee/basic';
-import type { BrowserController, BrowserPlugin, BrowserPoolHooks, BrowserPoolOptions, CommonPage, CrawlerRemoteBrowserOptions, InferBrowserPluginArray, LaunchContext } from '@crawlee/browser-pool';
+import type { CommonPage, CrawlerRemoteBrowserOptions } from '@crawlee/browser-pool';
 import type { Awaitable, Dictionary, IBrowserPool } from '@crawlee/types';
 import { z } from 'zod';
 import type { BrowserLaunchContext } from './browser-launcher.js';
@@ -9,6 +9,20 @@ interface BaseResponse {
     /** Optional because only Playwright and Puppeteer responses are guaranteed to carry it. */
     headers?(): Record<string, string>;
 }
+/**
+ * The type of a browser pool the crawler builds (and therefore owns) for itself. It's an {@link IBrowserPool} that
+ * additionally exposes `destroy()` — the crawler only ever tears down pools it created, which is why {@link IBrowserPool}
+ * itself intentionally omits `destroy`.
+ */
+export type OwnedBrowserPool<Page> = IBrowserPool<Page> & {
+    destroy: () => Promise<void>;
+};
+/**
+ * Rejects options that exist only to configure the browser pool the crawler would have built for itself.
+ * Accepting them alongside a pre-built `browserPool` and quietly ignoring them is how `browserPoolOptions` grew
+ * into a second, half-working way of configuring the same pool.
+ */
+export declare function assertBrowserPoolNotConfigured(crawlerName: string, ignoredOptions: Dictionary): void;
 export interface BrowserCrawlingContext<Page extends CommonPage = CommonPage, Response extends BaseResponse = BaseResponse, UserData extends Dictionary = any, // with default to Dictionary we cant use a typed router in untyped crawler
 GoToOptions extends Dictionary = Dictionary> extends CrawlingContext<UserData> {
     /**
@@ -38,12 +52,20 @@ GoToOptions extends Dictionary = Dictionary> extends CrawlingContext<UserData> {
     enqueueLinks: (options?: EnqueueLinksOptions) => Promise<AddRequestsBatchedResult>;
 }
 export type BrowserHook<Context = BrowserCrawlingContext, ContextExtension = {}> = (crawlingContext: Context & ContextExtension) => Awaitable<void | Partial<Context>>;
-export interface BrowserCrawlerOptions<Page extends CommonPage = CommonPage, Response extends BaseResponse = BaseResponse, Context extends BrowserCrawlingContext<Page, Response> = BrowserCrawlingContext<Page, Response>, ContextExtension = Dictionary<never>, ExtendedContext extends Context = Context & ContextExtension, InternalBrowserPoolOptions extends BrowserPoolOptions = BrowserPoolOptions, Routes extends Record<keyof Routes, Dictionary> = Record<string, GetUserDataFromRequest<Context['request']>>, StatisticStateExtension extends object = {}, __BrowserPlugins extends BrowserPlugin[] = InferBrowserPluginArray<InternalBrowserPoolOptions['browserPlugins']>, __BrowserControllerReturn extends BrowserController = ReturnType<__BrowserPlugins[number]['createController']>, __LaunchContextReturn extends LaunchContext = ReturnType<__BrowserPlugins[number]['createLaunchContext']>> extends Omit<BasicCrawlerOptions<Context, ContextExtension, ExtendedContext, Routes, StatisticStateExtension>, 'requestHandler' | 'failedRequestHandler' | 'errorHandler'> {
+export interface BrowserCrawlerOptions<Page extends CommonPage = CommonPage, Response extends BaseResponse = BaseResponse, Context extends BrowserCrawlingContext<Page, Response> = BrowserCrawlingContext<Page, Response>, ContextExtension = Dictionary<never>, ExtendedContext extends Context = Context & ContextExtension, Routes extends Record<keyof Routes, Dictionary> = Record<string, GetUserDataFromRequest<Context['request']>>, StatisticStateExtension extends object = {}> extends Omit<BasicCrawlerOptions<Context, ContextExtension, ExtendedContext, Routes, StatisticStateExtension>, 'requestHandler' | 'failedRequestHandler' | 'errorHandler'> {
     launchContext?: BrowserLaunchContext<any, any>;
     /**
-     * An existing browser pool instance to use. When provided, the crawler will use this pool directly instead of
-     * constructing a new one from `browserPoolOptions`, enabling browser sharing across multiple crawlers. The crawler
-     * will not tear down a shared pool — the caller is responsible for its lifecycle.
+     * The browser pool the crawler should serve its pages from. This is the single way to run a pool with
+     * non-default options: build one with the factory that matches your crawler
+     * ({@link playwrightBrowserPool}, {@link puppeteerBrowserPool}, {@link stagehandBrowserPool}) - it
+     * accepts every {@link BrowserPoolOptions|`BrowserPool` option} and supplies the correct browser plugin
+     * itself, so the pool can never mismatch the crawler.
+     *
+     * A pool passed in this way is borrowed, not owned: the crawler will not tear it down, which is what makes it
+     * shareable across crawlers. Since the crawler then builds nothing itself, the options that configure its own
+     * pool (`launchContext`, `headless`, `remoteBrowser`) are rejected rather than silently ignored.
+     *
+     * When omitted, the crawler builds - and tears down - a default pool for its own browser.
      */
     browserPool?: IBrowserPool<Page>;
     /**
@@ -54,8 +76,9 @@ export interface BrowserCrawlerOptions<Page extends CommonPage = CommonPage, Res
      * crawler. Supply the connection details only: a static `endpoint` URL, a function returning one per launch,
      * or a {@link RemoteBrowserProvider}.
      *
-     * Ignored when `browserPool` is set. For sharing a remote pool across crawlers, construct a
-     * {@link RemoteBrowserPool} yourself and pass it as `browserPool` instead.
+     * Cannot be combined with `browserPool`. To tune the pool wrapping the remote connection, or to share it
+     * across crawlers, build it with the remote factory for your crawler ({@link remotePlaywrightBrowserPool},
+     * {@link remotePuppeteerBrowserPool}, {@link remoteStagehandBrowserPool}) and pass it as `browserPool`.
      */
     remoteBrowser?: CrawlerRemoteBrowserOptions;
     /**
@@ -106,11 +129,6 @@ export interface BrowserCrawlerOptions<Page extends CommonPage = CommonPage, Res
      * represents the last error thrown during processing of the request.
      */
     failedRequestHandler?: ErrorHandler<CrawlingContext, ExtendedContext>;
-    /**
-     * Custom options passed to the underlying {@link BrowserPool} constructor.
-     * We can tweak those to fine-tune browser management.
-     */
-    browserPoolOptions?: Partial<BrowserPoolOptions> & Partial<BrowserPoolHooks<__BrowserControllerReturn, __LaunchContextReturn>>;
     /**
      * Async functions that are sequentially evaluated before the navigation. Good for setting additional cookies
      * or browser properties before navigation. The function receives the `crawlingContext`; the options object
@@ -175,11 +193,6 @@ export interface BrowserCrawlerOptions<Page extends CommonPage = CommonPage, Res
      * Defines whether the cookies should be persisted for sessions. Enabled by default.
      */
     saveResponseCookies?: boolean;
-    /**
-     * Whether to run browser in headless mode. Defaults to `true`.
-     * Can be also set via {@link Configuration}.
-     */
-    headless?: boolean | 'new' | 'old';
     /**
      * Whether to ignore custom elements (and their #shadow-roots) when processing the page content via `parseWithCheerio` helper.
      * By default, they are expanded automatically. Use this option to disable this behavior.
@@ -231,7 +244,7 @@ export interface BrowserCrawlerOptions<Page extends CommonPage = CommonPage, Res
  *
  * @category Crawlers
  */
-export declare abstract class BrowserCrawler<Page extends CommonPage = CommonPage, Response extends BaseResponse = BaseResponse, InternalBrowserPoolOptions extends BrowserPoolOptions = BrowserPoolOptions, LaunchOptions extends Dictionary | undefined = Dictionary, Context extends BrowserCrawlingContext<Page, Response> = BrowserCrawlingContext<Page, Response>, ContextExtension = Dictionary<never>, ExtendedContext extends Context = Context & ContextExtension, Routes extends Record<keyof Routes, Dictionary> = Record<string, GetUserDataFromRequest<Context['request']>>, StatisticStateExtension extends object = {}, GoToOptions extends Dictionary = Dictionary> extends BasicCrawler<Context, ContextExtension, ExtendedContext, Routes, StatisticStateExtension> {
+export declare abstract class BrowserCrawler<Page extends CommonPage = CommonPage, Response extends BaseResponse = BaseResponse, LaunchOptions extends Dictionary | undefined = Dictionary, Context extends BrowserCrawlingContext<Page, Response> = BrowserCrawlingContext<Page, Response>, ContextExtension = Dictionary<never>, ExtendedContext extends Context = Context & ContextExtension, Routes extends Record<keyof Routes, Dictionary> = Record<string, GetUserDataFromRequest<Context['request']>>, StatisticStateExtension extends object = {}, GoToOptions extends Dictionary = Dictionary> extends BasicCrawler<Context, ContextExtension, ExtendedContext, Routes, StatisticStateExtension> {
     #private;
     /**
      * A reference to the underlying browser pool that manages the crawler's browsers. Typed as
@@ -246,10 +259,9 @@ export declare abstract class BrowserCrawler<Page extends CommonPage = CommonPag
         preNavigationHooks: z.ZodDefault<z.ZodCustom<unknown[], unknown[]>>;
         postNavigationHooks: z.ZodDefault<z.ZodCustom<unknown[], unknown[]>>;
         launchContext: z.ZodDefault<z.ZodCustom<Dictionary, Dictionary>>;
-        headless: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodString]>>;
         browserPool: z.ZodOptional<z.ZodType<Dictionary<any>, unknown, z.core.$ZodTypeInternals<Dictionary<any>, unknown>>>;
+        browserPoolBuilder: z.ZodOptional<z.ZodCustom<(...args: any[]) => unknown, (...args: any[]) => unknown>>;
         remoteBrowser: z.ZodOptional<z.ZodCustom<Dictionary, Dictionary>>;
-        browserPoolOptions: z.ZodOptional<z.ZodCustom<Dictionary, Dictionary>>;
         saveResponseCookies: z.ZodDefault<z.ZodBoolean>;
         proxyConfiguration: z.ZodOptional<z.ZodType<Dictionary<any>, unknown, z.core.$ZodTypeInternals<Dictionary<any>, unknown>>>;
         ignoreIframes: z.ZodDefault<z.ZodBoolean>;
@@ -304,10 +316,9 @@ export declare abstract class BrowserCrawler<Page extends CommonPage = CommonPag
         preNavigationHooks: z.ZodDefault<z.ZodCustom<unknown[], unknown[]>>;
         postNavigationHooks: z.ZodDefault<z.ZodCustom<unknown[], unknown[]>>;
         launchContext: z.ZodDefault<z.ZodCustom<Dictionary, Dictionary>>;
-        headless: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodString]>>;
         browserPool: z.ZodOptional<z.ZodType<Dictionary<any>, unknown, z.core.$ZodTypeInternals<Dictionary<any>, unknown>>>;
+        browserPoolBuilder: z.ZodOptional<z.ZodCustom<(...args: any[]) => unknown, (...args: any[]) => unknown>>;
         remoteBrowser: z.ZodOptional<z.ZodCustom<Dictionary, Dictionary>>;
-        browserPoolOptions: z.ZodOptional<z.ZodCustom<Dictionary, Dictionary>>;
         saveResponseCookies: z.ZodDefault<z.ZodBoolean>;
         proxyConfiguration: z.ZodOptional<z.ZodType<Dictionary<any>, unknown, z.core.$ZodTypeInternals<Dictionary<any>, unknown>>>;
         ignoreIframes: z.ZodDefault<z.ZodBoolean>;
@@ -360,8 +371,14 @@ export declare abstract class BrowserCrawler<Page extends CommonPage = CommonPag
     /**
      * All `BrowserCrawler` parameters are passed via an options object.
      */
-    protected constructor(options: BrowserCrawlerOptions<Page, Response, Context, ContextExtension, ExtendedContext, BrowserPoolOptions, Routes, StatisticStateExtension> & {
+    protected constructor(options: BrowserCrawlerOptions<Page, Response, Context, ContextExtension, ExtendedContext, Routes, StatisticStateExtension> & {
         contextPipelineBuilder: () => ContextPipeline<CrawlingContext, Context>;
+        /**
+         * Builds the pool the crawler owns, used only when the user injected no `browserPool`. Supplied by the
+         * concrete crawler, which is the only place that knows which browser plugin to run - that is also why
+         * `remoteBrowser` is handed to it rather than acted upon here.
+         */
+        browserPoolBuilder: (remoteBrowser?: CrawlerRemoteBrowserOptions) => OwnedBrowserPool<Page>;
     });
     protected getNavigationTimeoutMillis(): number;
     protected buildContextPipeline(): ContextPipeline<CrawlingContext, BrowserCrawlingContext<Page, Response, Dictionary>>;

package/internals/browser-crawler.js

@@ -1,9 +1,22 @@
 import { BasicCrawler, browserPoolCookieToToughCookie, ContextPipeline, cookieStringToToughCookie, EnqueueStrategy, NavigationSkippedError, OwnedOrInjected, parseArgument, remainingNavigationWindowMillis, RequestState, RequestThrottledError, resolveBaseUrlForEnqueueLinksFiltering, schemas, SessionError, toughCookieToBrowserPoolCookie, tryAbsoluteURL, validators, } from '@crawlee/basic';
-import { BrowserPool, RemoteBrowserPool } from '@crawlee/browser-pool';
 import { CLOUDFLARE_RETRY_CSS_SELECTORS, RETRY_CSS_SELECTORS } from '@crawlee/utils/internal';
 import { sleep } from '@crawlee/utils';
 import { z } from 'zod';
 import { addTimeoutToPromise, TimeoutError, tryCancel } from '@apify/timeout';
+/**
+ * Rejects options that exist only to configure the browser pool the crawler would have built for itself.
+ * Accepting them alongside a pre-built `browserPool` and quietly ignoring them is how `browserPoolOptions` grew
+ * into a second, half-working way of configuring the same pool.
+ */
+export function assertBrowserPoolNotConfigured(crawlerName, ignoredOptions) {
+    const names = Object.keys(ignoredOptions).filter((name) => ignoredOptions[name] !== undefined);
+    if (names.length === 0) {
+        return;
+    }
+    throw new Error(`${crawlerName}: ${names.map((name) => `\`${name}\``).join(', ')} cannot be combined with \`browserPool\`, ` +
+        `${names.length > 1 ? 'they configure' : 'it configures'} the browser pool the crawler would build for ` +
+        'itself. Configure the pool you pass in instead.');
+}
 const COOKIES_BEFORE_HOOKS = Symbol('cookiesBeforeHooks');
 const readContextField = (ctx, key) => ctx[key];
 /**
@@ -82,10 +95,9 @@ export class BrowserCrawler extends BasicCrawler {
         preNavigationHooks: schemas.anyArray.default(() => []),
         postNavigationHooks: schemas.anyArray.default(() => []),
         launchContext: schemas.anyObject.default(() => ({})),
-        headless: z.union([z.boolean(), z.string()]).optional(),
         browserPool: validators.browserPool.optional(),
+        browserPoolBuilder: schemas.anyFunction.optional(),
         remoteBrowser: schemas.anyObject.optional(),
-        browserPoolOptions: schemas.anyObject.optional(),
         saveResponseCookies: z.boolean().default(true),
         proxyConfiguration: validators.proxyConfiguration.optional(),
         ignoreIframes: z.boolean().default(false),
@@ -96,7 +108,10 @@ export class BrowserCrawler extends BasicCrawler {
      * All `BrowserCrawler` parameters are passed via an options object.
      */
     constructor(options) {
-        const { navigationTimeoutSecs, saveResponseCookies, launchContext, browserPool, remoteBrowser, browserPoolOptions, preNavigationHooks, postNavigationHooks, headless, ignoreIframes, ignoreShadowRoots, contextPipelineBuilder, extendContext, ...basicCrawlerOptions } = parseArgument(options, BrowserCrawler.optionsSchema, 'BrowserCrawlerOptions');
+        const { navigationTimeoutSecs, saveResponseCookies, launchContext, browserPool, remoteBrowser, preNavigationHooks, postNavigationHooks, ignoreIframes, ignoreShadowRoots, contextPipelineBuilder, browserPoolBuilder, extendContext, ...basicCrawlerOptions } = parseArgument(options, BrowserCrawler.optionsSchema, 'BrowserCrawlerOptions');
+        if (browserPool) {
+            assertBrowserPoolNotConfigured(new.target.name, { remoteBrowser });
+        }
         const skipGuard = (action) => ({
             action: async (ctx) => (ctx.request.skipNavigation ? {} : ((await action(ctx)) ?? {})),
         });
@@ -138,39 +153,8 @@ export class BrowserCrawler extends BasicCrawler {
         this.#postNavigationHooks = postNavigationHooks;
         this.ignoreIframes = ignoreIframes;
         this.ignoreShadowRoots = ignoreShadowRoots;
-        if (headless != null) {
-            this.launchContext.launchOptions ??= {};
-            this.launchContext.launchOptions.headless = headless;
-        }
         this.#saveResponseCookies = saveResponseCookies;
-        // `browserPool` wins over `remoteBrowser` — a passed-in pool is used as-is (borrowed), the sugar is ignored.
-        // The default is only built when no pool was injected, so all the option/launchContext fiddling below stays
-        // inside the factory.
-        this.#browserPoolDep = OwnedOrInjected.resolve(browserPool, () => {
-            const resolvedBrowserPoolOptions = browserPoolOptions ?? {};
-            if (launchContext?.userAgent) {
-                if (resolvedBrowserPoolOptions.useFingerprints)
-                    this.log.info('Custom user agent provided, disabling automatic browser fingerprint injection!');
-                resolvedBrowserPoolOptions.useFingerprints = false;
-            }
-            if (remoteBrowser) {
-                // The crawler already built the right plugin for its browser — hand it to a RemoteBrowserPool so the
-                // remote connection is always for the matching browser (no plugin to construct, no way to mismatch).
-                const { browserPlugins, ...remoteBrowserPoolOptions } = resolvedBrowserPoolOptions;
-                return new RemoteBrowserPool({
-                    browserPlugins: browserPlugins,
-                    ...remoteBrowser,
-                    browserPoolOptions: remoteBrowserPoolOptions,
-                });
-            }
-            // Double cast: `BrowserPool` implements `IBrowserPool<PageReturn>`, where `PageReturn` is derived from the
-            // plugin/controller generics and doesn't overlap with the crawler's free `Page` type param, so TS won't
-            // narrow it directly. The concrete pool does satisfy the `Page`/`destroy` contract at runtime — this is the
-            // long-standing `Page` variance gap, not a `destroy`-related hole.
-            return new BrowserPool({
-                ...resolvedBrowserPoolOptions,
-            });
-        });
+        this.#browserPoolDep = OwnedOrInjected.resolve(browserPool, () => browserPoolBuilder(remoteBrowser));
     }
     getNavigationTimeoutMillis() {
         return this.#navigationTimeoutMillis;
@@ -415,7 +399,7 @@ export class BrowserCrawler extends BasicCrawler {
         const { session, request, page } = crawlingContext;
         if (typeof response === 'object' && typeof response.status === 'function') {
             const status = response.status();
-            this.stats.registerStatusCode(status);
+            this.statistics.registerStatusCode(status);
             // Ahead of the error-status throw below: a 429 the user opted into treating as an error is still a
             // rate limit the domain should back off from.
             if (status === 429) {

package/internals/browser-launcher.d.ts

@@ -1,5 +1,6 @@
 import { Configuration } from '@crawlee/basic';
-import type { BrowserPlugin, BrowserPluginOptions } from '@crawlee/browser-pool';
+import type { BrowserPlugin, BrowserPluginOptions, BrowserPoolHooks, BrowserPoolOptions, RemoteBrowserPoolOptions } from '@crawlee/browser-pool';
+import { BrowserPool, RemoteBrowserPool } from '@crawlee/browser-pool';
 import type { Constructor, Dictionary } from '@crawlee/types';
 import { z } from 'zod';
 export interface BrowserLaunchContext<TOptions, Launcher> extends BrowserPluginOptions<TOptions> {
@@ -65,6 +66,19 @@ export interface BrowserLaunchContext<TOptions, Launcher> extends BrowserPluginO
      */
     launcher?: Launcher;
 }
+/**
+ * The {@link BrowserPool} options a launcher-built pool accepts: everything the pool itself takes except
+ * `browserPlugins`, which the launcher derives from its launch context. The hooks are deliberately unconstrained -
+ * the browser they run against is only known to the concrete `*BrowserPool()` factory, which is where the
+ * caller-facing types are pinned down.
+ */
+export type LauncherBrowserPoolOptions = Omit<BrowserPoolOptions, 'browserPlugins'> & {
+    [Hook in keyof BrowserPoolHooks<any, any, any>]?: readonly ((...args: any[]) => unknown)[];
+};
+/**
+ * The {@link RemoteBrowserPool} counterpart of {@link LauncherBrowserPoolOptions}.
+ */
+export type LauncherRemoteBrowserPoolOptions = Omit<RemoteBrowserPoolOptions, 'browserPlugins'>;
 /**
  * Abstract class for creating browser launchers, such as `PlaywrightLauncher` and `PuppeteerLauncher`.
  * @ignore
@@ -107,6 +121,26 @@ export declare abstract class BrowserLauncher<Plugin extends BrowserPlugin, Laun
      * @ignore
      */
     createBrowserPlugin(): Plugin;
+    /**
+     * Builds a {@link BrowserPool} running a single plugin for this launcher's browser. Shared body of the
+     * per-library `*BrowserPool()` factories, which exist so that configuring a pool never requires assembling
+     * a plugin by hand — and therefore never lets the plugin drift away from the crawler it is used with.
+     * @internal
+     */
+    createBrowserPool(options?: LauncherBrowserPoolOptions): BrowserPool<{
+        browserPlugins: [Plugin];
+    }, [Plugin]>;
+    /**
+     * The {@link RemoteBrowserPool} counterpart of {@link BrowserLauncher.createBrowserPool}: the launcher
+     * supplies the plugin, the caller supplies the remote connection details.
+     * @internal
+     */
+    createRemoteBrowserPool<Page>(options: LauncherRemoteBrowserPoolOptions): RemoteBrowserPool<Page>;
+    /**
+     * A custom `userAgent` and Crawlee's fingerprint injection would both write the same headers, so an
+     * explicitly requested user agent wins.
+     */
+    private resolveFingerprinting;
     /**
      * Launches a browser instance based on the plugin.
      * @returns Browser instance.

package/internals/browser-launcher.js

@@ -1,7 +1,8 @@
 import fs from 'node:fs';
 import { createRequire } from 'node:module';
 import os from 'node:os';
-import { Configuration, schemas } from '@crawlee/basic';
+import { Configuration, schemas, serviceLocator } from '@crawlee/basic';
+import { BrowserPool, RemoteBrowserPool } from '@crawlee/browser-pool';
 import { z } from 'zod';
 const DEFAULT_VIEWPORT = {
     width: 1366,
@@ -74,6 +75,49 @@ export class BrowserLauncher {
             ...this.otherLaunchContextProps,
         });
     }
+    /**
+     * Builds a {@link BrowserPool} running a single plugin for this launcher's browser. Shared body of the
+     * per-library `*BrowserPool()` factories, which exist so that configuring a pool never requires assembling
+     * a plugin by hand — and therefore never lets the plugin drift away from the crawler it is used with.
+     * @internal
+     */
+    createBrowserPool(options = {}) {
+        // The hook types `BrowserPool` derives from `Plugin` are unresolvable while `Plugin` is still a free type
+        // parameter, so the argument cannot be checked here. The concrete `*BrowserPool()` factories are where the
+        // caller-facing hook types get pinned down.
+        return new BrowserPool({
+            ...this.resolveFingerprinting(options),
+            browserPlugins: [this.createBrowserPlugin()],
+        });
+    }
+    /**
+     * The {@link RemoteBrowserPool} counterpart of {@link BrowserLauncher.createBrowserPool}: the launcher
+     * supplies the plugin, the caller supplies the remote connection details.
+     * @internal
+     */
+    createRemoteBrowserPool(options) {
+        return new RemoteBrowserPool({
+            ...options,
+            browserPlugins: [this.createBrowserPlugin()],
+            browserPoolOptions: this.resolveFingerprinting(options.browserPoolOptions ?? {}),
+        });
+    }
+    /**
+     * A custom `userAgent` and Crawlee's fingerprint injection would both write the same headers, so an
+     * explicitly requested user agent wins.
+     */
+    resolveFingerprinting(options) {
+        if (!this.userAgent) {
+            return options;
+        }
+        if (options.useFingerprints) {
+            serviceLocator
+                .getLogger()
+                .child({ prefix: 'BrowserLauncher' })
+                .info('Custom user agent provided, disabling automatic browser fingerprint injection!');
+        }
+        return { ...options, useFingerprints: false };
+    }
     /**
      * Launches a browser instance based on the plugin.
      * @returns Browser instance.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@crawlee/browser",
-    "version": "4.0.0-beta.125",
+    "version": "4.0.0-beta.127",
     "description": "The scalable web crawling and scraping library for JavaScript/Node.js. Enables development of data extraction and web automation jobs (not only) with headless Chrome and Puppeteer.",
     "engines": {
         "node": ">=22.0.0"
@@ -48,10 +48,10 @@
     },
     "dependencies": {
         "@apify/timeout": "^0.4.4",
-        "@crawlee/basic": "4.0.0-beta.125",
-        "@crawlee/browser-pool": "4.0.0-beta.125",
-        "@crawlee/types": "4.0.0-beta.125",
-        "@crawlee/utils": "4.0.0-beta.125",
+        "@crawlee/basic": "4.0.0-beta.127",
+        "@crawlee/browser-pool": "4.0.0-beta.127",
+        "@crawlee/types": "4.0.0-beta.127",
+        "@crawlee/utils": "4.0.0-beta.127",
         "tslib": "^2.8.1",
         "type-fest": "^4.41.0",
         "zod": "^4.4.3"
@@ -75,5 +75,5 @@
             }
         }
     },
-    "gitHead": "04a7212dd4abe4a5f94f5fc9632acb6089819c8b"
+    "gitHead": "4aa4a4d8d105bb530649ac5cd9197a3169106bd9"
 }