@crawlee/browser 4.0.0-beta.98 → 4.0.0-rc.0

package/internals/browser-crawler.d.ts

@@ -1,14 +1,30 @@
-import type { BasicCrawlerOptions, BasicCrawlingContext, CrawlingContext, EnqueueLinksOptions, ErrorHandler, GetUserDataFromRequest, IRequestManager, LoadedRequest, Request, RequestHandler, RouterHandler, SkippedRequestCallback } from '@crawlee/basic';
+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 { Awaitable, BatchAddRequestsResult, Dictionary, IBrowserPool } from '@crawlee/types';
-import type { RobotsTxtFile } from '@crawlee/utils';
-import type { ReadonlyDeep } from 'type-fest';
+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';
 interface BaseResponse {
     status(): number;
+    /** Optional because only Playwright and Puppeteer responses are guaranteed to carry it. */
+    headers?(): Record<string, string>;
 }
-export interface BrowserCrawlingContext<Page extends CommonPage = CommonPage, Response extends BaseResponse = BaseResponse, UserData extends Dictionary = Dictionary, GoToOptions extends Dictionary = Dictionary> extends CrawlingContext<UserData> {
+/**
+ * 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> {
     /**
      * The browser page object where the web page is loaded and rendered.
      */
@@ -26,18 +42,30 @@ export interface BrowserCrawlingContext<Page extends CommonPage = CommonPage, Re
      * object (or return `{ gotoOptions: ... }`) to influence the navigation.
      */
     gotoOptions: GoToOptions;
+    /**
+     * Extracts URLs from the current page, without adding them to the request queue.
+     */
+    extractLinks: (options?: ExtractLinksOptions) => Promise<string[]>;
     /**
      * Helper function for extracting URLs from the current page and adding them to the request queue.
      */
-    enqueueLinks: (options?: EnqueueLinksOptions) => Promise<BatchAddRequestsResult>;
+    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, Dictionary> = BrowserCrawlingContext<Page, Response, Dictionary>, ContextExtension = Dictionary<never>, ExtendedContext extends Context = Context & ContextExtension, InternalBrowserPoolOptions extends BrowserPoolOptions = BrowserPoolOptions, Routes extends Record<keyof Routes, Dictionary> = Record<string, GetUserDataFromRequest<Context['request']>>, __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>, '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>;
     /**
@@ -48,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;
     /**
@@ -100,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
@@ -169,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.
@@ -225,9 +244,8 @@ 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, Dictionary> = BrowserCrawlingContext<Page, Response, Dictionary>, ContextExtension = Dictionary<never>, ExtendedContext extends Context = Context & ContextExtension, Routes extends Record<keyof Routes, Dictionary> = Record<string, GetUserDataFromRequest<Context['request']>>, GoToOptions extends Dictionary = Dictionary> extends BasicCrawler<Context, ContextExtension, ExtendedContext, Routes> {
-    /** Backs the {@link BrowserCrawler.browserPool|`browserPool`} getter. */
-    private browserPoolDep;
+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
      * {@link IBrowserPool} so custom implementations can be plugged in via the `browserPool` constructor option.
@@ -236,105 +254,131 @@ export declare abstract class BrowserCrawler<Page extends CommonPage = CommonPag
     launchContext: BrowserLaunchContext<LaunchOptions, unknown>;
     protected readonly ignoreShadowRoots: boolean;
     protected readonly ignoreIframes: boolean;
-    private readonly navigationTimeoutMillis;
-    private readonly preNavigationHooks;
-    private readonly postNavigationHooks;
-    private readonly saveResponseCookies;
     protected static optionsShape: {
-// @ts-ignore optional peer dependency or compatibility with es2022
-        navigationTimeoutSecs: import("ow").NumberPredicate & import("ow").BasePredicate<number | undefined>;
-// @ts-ignore optional peer dependency or compatibility with es2022
-        preNavigationHooks: import("ow").ArrayPredicate<unknown> & import("ow").BasePredicate<unknown[] | undefined>;
-// @ts-ignore optional peer dependency or compatibility with es2022
-        postNavigationHooks: import("ow").ArrayPredicate<unknown> & import("ow").BasePredicate<unknown[] | undefined>;
-// @ts-ignore optional peer dependency or compatibility with es2022
-        launchContext: import("ow").ObjectPredicate<object> & import("ow").BasePredicate<object | undefined>;
-// @ts-ignore optional peer dependency or compatibility with es2022
-        headless: import("ow").AnyPredicate<string | boolean>;
-// @ts-ignore optional peer dependency or compatibility with es2022
-        browserPool: import("ow").ObjectPredicate<object> & import("ow").BasePredicate<object | undefined>;
-// @ts-ignore optional peer dependency or compatibility with es2022
-        remoteBrowser: import("ow").ObjectPredicate<object> & import("ow").BasePredicate<object | undefined>;
-// @ts-ignore optional peer dependency or compatibility with es2022
-        browserPoolOptions: import("ow").ObjectPredicate<object> & import("ow").BasePredicate<object | undefined>;
-// @ts-ignore optional peer dependency or compatibility with es2022
-        saveResponseCookies: import("ow").BooleanPredicate & import("ow").BasePredicate<boolean | undefined>;
-// @ts-ignore optional peer dependency or compatibility with es2022
-        proxyConfiguration: import("ow").ObjectPredicate<object> & import("ow").BasePredicate<object | undefined>;
-// @ts-ignore optional peer dependency or compatibility with es2022
-        contextPipelineBuilder: import("ow").ObjectPredicate<object> & import("ow").BasePredicate<object | undefined>;
-// @ts-ignore optional peer dependency or compatibility with es2022
-        extendContext: import("ow").Predicate<Function> & import("ow").BasePredicate<Function | undefined>;
-// @ts-ignore optional peer dependency or compatibility with es2022
-        requestList: import("ow").ObjectPredicate<object> & import("ow").BasePredicate<object | undefined>;
-// @ts-ignore optional peer dependency or compatibility with es2022
-        requestQueue: import("ow").ObjectPredicate<object> & import("ow").BasePredicate<object | undefined>;
-// @ts-ignore optional peer dependency or compatibility with es2022
-        requestHandler: import("ow").Predicate<Function> & import("ow").BasePredicate<Function | undefined>;
-// @ts-ignore optional peer dependency or compatibility with es2022
-        requestHandlerTimeoutSecs: import("ow").NumberPredicate & import("ow").BasePredicate<number | undefined>;
-// @ts-ignore optional peer dependency or compatibility with es2022
-        errorHandler: import("ow").Predicate<Function> & import("ow").BasePredicate<Function | undefined>;
-// @ts-ignore optional peer dependency or compatibility with es2022
-        failedRequestHandler: import("ow").Predicate<Function> & import("ow").BasePredicate<Function | undefined>;
-// @ts-ignore optional peer dependency or compatibility with es2022
-        maxRequestRetries: import("ow").NumberPredicate & import("ow").BasePredicate<number | undefined>;
-// @ts-ignore optional peer dependency or compatibility with es2022
-        sameDomainDelaySecs: import("ow").NumberPredicate & import("ow").BasePredicate<number | undefined>;
-// @ts-ignore optional peer dependency or compatibility with es2022
-        maxRequestsPerCrawl: import("ow").NumberPredicate & import("ow").BasePredicate<number | undefined>;
-// @ts-ignore optional peer dependency or compatibility with es2022
-        maxCrawlDepth: import("ow").NumberPredicate & import("ow").BasePredicate<number | undefined>;
-// @ts-ignore optional peer dependency or compatibility with es2022
-        taskLoopOptions: import("ow").ObjectPredicate<object> & import("ow").BasePredicate<object | undefined>;
-// @ts-ignore optional peer dependency or compatibility with es2022
-        concurrencySystem: import("ow").ObjectPredicate<object> & import("ow").BasePredicate<object | undefined>;
-// @ts-ignore optional peer dependency or compatibility with es2022
-        sessionPool: import("ow").ObjectPredicate<object> & import("ow").BasePredicate<object | undefined>;
-// @ts-ignore optional peer dependency or compatibility with es2022
-        statusMessageLoggingInterval: import("ow").NumberPredicate & import("ow").BasePredicate<number | undefined>;
-// @ts-ignore optional peer dependency or compatibility with es2022
-        statusMessageCallback: import("ow").Predicate<Function> & import("ow").BasePredicate<Function | undefined>;
-// @ts-ignore optional peer dependency or compatibility with es2022
-        additionalHttpErrorStatusCodes: import("ow").ArrayPredicate<number>;
-// @ts-ignore optional peer dependency or compatibility with es2022
-        ignoreHttpErrorStatusCodes: import("ow").ArrayPredicate<number>;
-// @ts-ignore optional peer dependency or compatibility with es2022
-        blockedStatusCodes: import("ow").ArrayPredicate<number>;
-// @ts-ignore optional peer dependency or compatibility with es2022
-        retryOnBlocked: import("ow").BooleanPredicate & import("ow").BasePredicate<boolean | undefined>;
-// @ts-ignore optional peer dependency or compatibility with es2022
-        respectRobotsTxtFile: import("ow").AnyPredicate<boolean | object>;
-// @ts-ignore optional peer dependency or compatibility with es2022
-        onSkippedRequest: import("ow").Predicate<Function> & import("ow").BasePredicate<Function | undefined>;
-// @ts-ignore optional peer dependency or compatibility with es2022
-        httpClient: import("ow").ObjectPredicate<object> & import("ow").BasePredicate<object | undefined>;
-// @ts-ignore optional peer dependency or compatibility with es2022
-        configuration: import("ow").ObjectPredicate<object> & import("ow").BasePredicate<object | undefined>;
-// @ts-ignore optional peer dependency or compatibility with es2022
-        storageBackend: import("ow").ObjectPredicate<object> & import("ow").BasePredicate<object | undefined>;
-// @ts-ignore optional peer dependency or compatibility with es2022
-        eventManager: import("ow").ObjectPredicate<object> & import("ow").BasePredicate<object | undefined>;
-// @ts-ignore optional peer dependency or compatibility with es2022
-        logger: import("ow").ObjectPredicate<object> & import("ow").BasePredicate<object | undefined>;
-// @ts-ignore optional peer dependency or compatibility with es2022
-        minConcurrency: import("ow").NumberPredicate & import("ow").BasePredicate<number | undefined>;
-// @ts-ignore optional peer dependency or compatibility with es2022
-        maxConcurrency: import("ow").NumberPredicate & import("ow").BasePredicate<number | undefined>;
-// @ts-ignore optional peer dependency or compatibility with es2022
-        maxRequestsPerMinute: import("ow").NumberPredicate & import("ow").BasePredicate<number | undefined>;
-// @ts-ignore optional peer dependency or compatibility with es2022
-        keepAlive: import("ow").BooleanPredicate & import("ow").BasePredicate<boolean | undefined>;
-// @ts-ignore optional peer dependency or compatibility with es2022
-        statisticsOptions: import("ow").ObjectPredicate<object> & import("ow").BasePredicate<object | undefined>;
-// @ts-ignore optional peer dependency or compatibility with es2022
-        id: import("ow").StringPredicate & import("ow").BasePredicate<string | undefined>;
+        navigationTimeoutSecs: z.ZodDefault<z.ZodCustom<number, number>>;
+        preNavigationHooks: z.ZodDefault<z.ZodCustom<unknown[], unknown[]>>;
+        postNavigationHooks: z.ZodDefault<z.ZodCustom<unknown[], unknown[]>>;
+        launchContext: z.ZodDefault<z.ZodCustom<Dictionary, Dictionary>>;
+        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>>;
+        saveResponseCookies: z.ZodDefault<z.ZodBoolean>;
+        proxyConfiguration: z.ZodOptional<z.ZodType<Dictionary<any>, unknown, z.core.$ZodTypeInternals<Dictionary<any>, unknown>>>;
+        ignoreIframes: z.ZodDefault<z.ZodBoolean>;
+        ignoreShadowRoots: z.ZodDefault<z.ZodBoolean>;
+        contextPipelineBuilder: z.ZodOptional<z.ZodCustom<Dictionary, Dictionary>>;
+        extendContext: z.ZodOptional<z.ZodCustom<(...args: any[]) => unknown, (...args: any[]) => unknown>>;
+        requestList: z.ZodOptional<z.ZodType<Dictionary<any>, unknown, z.core.$ZodTypeInternals<Dictionary<any>, unknown>>>;
+        requestQueue: z.ZodOptional<z.ZodType<Dictionary<any>, unknown, z.core.$ZodTypeInternals<Dictionary<any>, unknown>>>;
+        requestManager: z.ZodOptional<z.ZodType<Dictionary<any>, unknown, z.core.$ZodTypeInternals<Dictionary<any>, unknown>>>;
+        requestHandler: z.ZodOptional<z.ZodCustom<(...args: any[]) => unknown, (...args: any[]) => unknown>>;
+        requestHandlerTimeoutSecs: z.ZodOptional<z.ZodCustom<number, number>>;
+        errorHandler: z.ZodOptional<z.ZodCustom<(...args: any[]) => unknown, (...args: any[]) => unknown>>;
+        failedRequestHandler: z.ZodOptional<z.ZodCustom<(...args: any[]) => unknown, (...args: any[]) => unknown>>;
+        maxRequestRetries: z.ZodDefault<z.ZodCustom<number, number>>;
+        sameDomainDelaySecs: z.ZodDefault<z.ZodCustom<number, number>>;
+        maxRequestsPerCrawl: z.ZodOptional<z.ZodCustom<number, number>>;
+        maxCrawlDepth: z.ZodOptional<z.ZodCustom<number, number>>;
+        taskLoopOptions: z.ZodOptional<z.ZodCustom<Dictionary, Dictionary>>;
+        concurrencySystem: z.ZodOptional<z.ZodCustom<Dictionary, Dictionary>>;
+        sessionPool: z.ZodOptional<z.ZodType<Dictionary<any>, unknown, z.core.$ZodTypeInternals<Dictionary<any>, unknown>>>;
+        statusMessageLoggingInterval: z.ZodDefault<z.ZodCustom<number, number>>;
+        statusMessageCallback: z.ZodOptional<z.ZodCustom<(...args: any[]) => unknown, (...args: any[]) => unknown>>;
+        additionalHttpErrorStatusCodes: z.ZodDefault<z.ZodArray<z.ZodCustom<number, number>>>;
+        ignoreHttpErrorStatusCodes: z.ZodDefault<z.ZodArray<z.ZodCustom<number, number>>>;
+        blockedStatusCodes: z.ZodOptional<z.ZodArray<z.ZodCustom<number, number>>>;
+        retryOnBlocked: z.ZodDefault<z.ZodBoolean>;
+        respectRobotsTxtFile: z.ZodDefault<z.ZodUnion<readonly [z.ZodBoolean, z.ZodCustom<Dictionary, Dictionary>]>>;
+        transactionalStorage: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
+            requestQueue: z.ZodOptional<z.ZodEnum<{
+                deferred: "deferred";
+                writeThrough: "writeThrough";
+            }>>;
+        }, z.core.$strict>]>>;
+        onSkippedRequest: z.ZodOptional<z.ZodCustom<(...args: any[]) => unknown, (...args: any[]) => unknown>>;
+// @ts-ignore optional peer dependency or compatibility with es2022
+        httpClient: z.ZodOptional<z.ZodCustom<import("@crawlee/http-client").BaseHttpClient, import("@crawlee/http-client").BaseHttpClient>>;
+// @ts-ignore optional peer dependency or compatibility with es2022
+        configuration: z.ZodOptional<z.ZodCustom<import("@crawlee/basic").Configuration, import("@crawlee/basic").Configuration>>;
+        storageBackend: z.ZodOptional<z.ZodType<Dictionary<any>, unknown, z.core.$ZodTypeInternals<Dictionary<any>, unknown>>>;
+// @ts-ignore optional peer dependency or compatibility with es2022
+        eventManager: z.ZodOptional<z.ZodCustom<import("@crawlee/basic").EventManager, import("@crawlee/basic").EventManager>>;
+        logger: z.ZodOptional<z.ZodType<Dictionary<any>, unknown, z.core.$ZodTypeInternals<Dictionary<any>, unknown>>>;
+        minConcurrency: z.ZodOptional<z.ZodCustom<number, number>>;
+        maxConcurrency: z.ZodOptional<z.ZodCustom<number, number>>;
+        maxRequestsPerMinute: z.ZodOptional<z.ZodCustom<number, number>>;
+        keepAlive: z.ZodOptional<z.ZodBoolean>;
+        statistics: z.ZodOptional<z.ZodCustom<Dictionary, Dictionary>>;
+        id: z.ZodOptional<z.ZodString>;
     };
+    protected static optionsSchema: z.ZodObject<{
+        navigationTimeoutSecs: z.ZodDefault<z.ZodCustom<number, number>>;
+        preNavigationHooks: z.ZodDefault<z.ZodCustom<unknown[], unknown[]>>;
+        postNavigationHooks: z.ZodDefault<z.ZodCustom<unknown[], unknown[]>>;
+        launchContext: z.ZodDefault<z.ZodCustom<Dictionary, Dictionary>>;
+        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>>;
+        saveResponseCookies: z.ZodDefault<z.ZodBoolean>;
+        proxyConfiguration: z.ZodOptional<z.ZodType<Dictionary<any>, unknown, z.core.$ZodTypeInternals<Dictionary<any>, unknown>>>;
+        ignoreIframes: z.ZodDefault<z.ZodBoolean>;
+        ignoreShadowRoots: z.ZodDefault<z.ZodBoolean>;
+        contextPipelineBuilder: z.ZodOptional<z.ZodCustom<Dictionary, Dictionary>>;
+        extendContext: z.ZodOptional<z.ZodCustom<(...args: any[]) => unknown, (...args: any[]) => unknown>>;
+        requestList: z.ZodOptional<z.ZodType<Dictionary<any>, unknown, z.core.$ZodTypeInternals<Dictionary<any>, unknown>>>;
+        requestQueue: z.ZodOptional<z.ZodType<Dictionary<any>, unknown, z.core.$ZodTypeInternals<Dictionary<any>, unknown>>>;
+        requestManager: z.ZodOptional<z.ZodType<Dictionary<any>, unknown, z.core.$ZodTypeInternals<Dictionary<any>, unknown>>>;
+        requestHandler: z.ZodOptional<z.ZodCustom<(...args: any[]) => unknown, (...args: any[]) => unknown>>;
+        requestHandlerTimeoutSecs: z.ZodOptional<z.ZodCustom<number, number>>;
+        errorHandler: z.ZodOptional<z.ZodCustom<(...args: any[]) => unknown, (...args: any[]) => unknown>>;
+        failedRequestHandler: z.ZodOptional<z.ZodCustom<(...args: any[]) => unknown, (...args: any[]) => unknown>>;
+        maxRequestRetries: z.ZodDefault<z.ZodCustom<number, number>>;
+        sameDomainDelaySecs: z.ZodDefault<z.ZodCustom<number, number>>;
+        maxRequestsPerCrawl: z.ZodOptional<z.ZodCustom<number, number>>;
+        maxCrawlDepth: z.ZodOptional<z.ZodCustom<number, number>>;
+        taskLoopOptions: z.ZodOptional<z.ZodCustom<Dictionary, Dictionary>>;
+        concurrencySystem: z.ZodOptional<z.ZodCustom<Dictionary, Dictionary>>;
+        sessionPool: z.ZodOptional<z.ZodType<Dictionary<any>, unknown, z.core.$ZodTypeInternals<Dictionary<any>, unknown>>>;
+        statusMessageLoggingInterval: z.ZodDefault<z.ZodCustom<number, number>>;
+        statusMessageCallback: z.ZodOptional<z.ZodCustom<(...args: any[]) => unknown, (...args: any[]) => unknown>>;
+        additionalHttpErrorStatusCodes: z.ZodDefault<z.ZodArray<z.ZodCustom<number, number>>>;
+        ignoreHttpErrorStatusCodes: z.ZodDefault<z.ZodArray<z.ZodCustom<number, number>>>;
+        blockedStatusCodes: z.ZodOptional<z.ZodArray<z.ZodCustom<number, number>>>;
+        retryOnBlocked: z.ZodDefault<z.ZodBoolean>;
+        respectRobotsTxtFile: z.ZodDefault<z.ZodUnion<readonly [z.ZodBoolean, z.ZodCustom<Dictionary, Dictionary>]>>;
+        transactionalStorage: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
+            requestQueue: z.ZodOptional<z.ZodEnum<{
+                deferred: "deferred";
+                writeThrough: "writeThrough";
+            }>>;
+        }, z.core.$strict>]>>;
+        onSkippedRequest: z.ZodOptional<z.ZodCustom<(...args: any[]) => unknown, (...args: any[]) => unknown>>;
+// @ts-ignore optional peer dependency or compatibility with es2022
+        httpClient: z.ZodOptional<z.ZodCustom<import("@crawlee/http-client").BaseHttpClient, import("@crawlee/http-client").BaseHttpClient>>;
+// @ts-ignore optional peer dependency or compatibility with es2022
+        configuration: z.ZodOptional<z.ZodCustom<import("@crawlee/basic").Configuration, import("@crawlee/basic").Configuration>>;
+        storageBackend: z.ZodOptional<z.ZodType<Dictionary<any>, unknown, z.core.$ZodTypeInternals<Dictionary<any>, unknown>>>;
+// @ts-ignore optional peer dependency or compatibility with es2022
+        eventManager: z.ZodOptional<z.ZodCustom<import("@crawlee/basic").EventManager, import("@crawlee/basic").EventManager>>;
+        logger: z.ZodOptional<z.ZodType<Dictionary<any>, unknown, z.core.$ZodTypeInternals<Dictionary<any>, unknown>>>;
+        minConcurrency: z.ZodOptional<z.ZodCustom<number, number>>;
+        maxConcurrency: z.ZodOptional<z.ZodCustom<number, number>>;
+        maxRequestsPerMinute: z.ZodOptional<z.ZodCustom<number, number>>;
+        keepAlive: z.ZodOptional<z.ZodBoolean>;
+        statistics: z.ZodOptional<z.ZodCustom<Dictionary, Dictionary>>;
+        id: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
     /**
      * All `BrowserCrawler` parameters are passed via an options object.
      */
-    protected constructor(options: BrowserCrawlerOptions<Page, Response, Context, ContextExtension, ExtendedContext> & {
+    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>>;
@@ -364,7 +408,7 @@ export declare abstract class BrowserCrawler<Page extends CommonPage = CommonPag
      * Transforms proxy-related errors to `SessionError`.
      */
     private throwIfProxyError;
-    protected abstract _navigationHandler(crawlingContext: BrowserCrawlingContext<Page, Response>, gotoOptions: GoToOptions): Promise<Context['response'] | null | undefined>;
+    protected abstract navigationHandler(crawlingContext: BrowserCrawlingContext<Page, Response>, gotoOptions: GoToOptions): Promise<Context['response'] | null | undefined>;
     private processResponse;
     /**
      * Function for cleaning up after all requests are processed.
@@ -372,26 +416,6 @@ export declare abstract class BrowserCrawler<Page extends CommonPage = CommonPag
      */
     teardown(): Promise<void>;
 }
-/** @internal */
-interface EnqueueLinksInternalOptions {
-    options?: ReadonlyDeep<Omit<EnqueueLinksOptions, 'requestManager'>> & Pick<EnqueueLinksOptions, 'requestManager'>;
-    page: CommonPage;
-    requestManager: IRequestManager;
-    robotsTxtFile?: RobotsTxtFile;
-    onSkippedRequest?: SkippedRequestCallback;
-    originalRequestUrl: string;
-    finalRequestUrl?: string;
-}
-/** @internal */
-interface BoundEnqueueLinksInternalOptions {
-    enqueueLinks: BasicCrawlingContext['enqueueLinks'];
-    options?: ReadonlyDeep<Omit<EnqueueLinksOptions, 'requestManager'>> & Pick<EnqueueLinksOptions, 'requestManager'>;
-    originalRequestUrl: string;
-    finalRequestUrl?: string;
-    page: CommonPage;
-}
-/** @internal */
-export declare function browserCrawlerEnqueueLinks(options: EnqueueLinksInternalOptions | BoundEnqueueLinksInternalOptions): Promise<unknown>;
 /**
  * Extracts URLs from a given page.
  * @ignore

package/internals/browser-crawler.js

@@ -1,8 +1,22 @@
-import { BasicCrawler, browserPoolCookieToToughCookie, ContextPipeline, cookieStringToToughCookie, enqueueLinks, NavigationSkippedError, OwnedOrInjected, remainingNavigationWindowMillis, RequestState, resolveBaseUrlForEnqueueLinksFiltering, SessionError, toughCookieToBrowserPoolCookie, tryAbsoluteURL, validators, } from '@crawlee/basic';
-import { BrowserPool, RemoteBrowserPool } from '@crawlee/browser-pool';
-import { CLOUDFLARE_RETRY_CSS_SELECTORS, RETRY_CSS_SELECTORS, sleep } from '@crawlee/utils';
-import ow from 'ow';
+import { BasicCrawler, browserPoolCookieToToughCookie, ContextPipeline, cookieStringToToughCookie, EnqueueStrategy, NavigationSkippedError, OwnedOrInjected, parseArgument, remainingNavigationWindowMillis, RequestState, RequestThrottledError, resolveBaseUrlForEnqueueLinksFiltering, schemas, SessionError, toughCookieToBrowserPoolCookie, tryAbsoluteURL, validators, } from '@crawlee/basic';
+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];
 /**
@@ -58,40 +72,46 @@ function isNavigationTimeoutError(error) {
  */
 export class BrowserCrawler extends BasicCrawler {
     /** Backs the {@link BrowserCrawler.browserPool|`browserPool`} getter. */
-    browserPoolDep;
+    #browserPoolDep;
     /**
      * A reference to the underlying browser pool that manages the crawler's browsers. Typed as
      * {@link IBrowserPool} so custom implementations can be plugged in via the `browserPool` constructor option.
      */
     get browserPool() {
-        return this.browserPoolDep.value;
+        return this.#browserPoolDep.value;
     }
     launchContext;
     ignoreShadowRoots;
     ignoreIframes;
-    navigationTimeoutMillis;
-    preNavigationHooks;
-    postNavigationHooks;
-    saveResponseCookies;
+    #navigationTimeoutMillis;
+    #preNavigationHooks;
+    #postNavigationHooks;
+    #saveResponseCookies;
     static optionsShape = {
         ...BasicCrawler.optionsShape,
-        navigationTimeoutSecs: ow.optional.number.greaterThan(0),
-        preNavigationHooks: ow.optional.array,
-        postNavigationHooks: ow.optional.array,
-        launchContext: ow.optional.object,
-        headless: ow.optional.any(ow.boolean, ow.string),
-        browserPool: ow.optional.object.validate(validators.browserPool),
-        remoteBrowser: ow.optional.object,
-        browserPoolOptions: ow.optional.object,
-        saveResponseCookies: ow.optional.boolean,
-        proxyConfiguration: ow.optional.object.validate(validators.proxyConfiguration),
+        navigationTimeoutSecs: schemas.anyNumber
+            .refine((value) => value > 0, 'Expected a number greater than 0')
+            .default(60),
+        preNavigationHooks: schemas.anyArray.default(() => []),
+        postNavigationHooks: schemas.anyArray.default(() => []),
+        launchContext: schemas.anyObject.default(() => ({})),
+        browserPool: validators.browserPool.optional(),
+        browserPoolBuilder: schemas.anyFunction.optional(),
+        remoteBrowser: schemas.anyObject.optional(),
+        saveResponseCookies: z.boolean().default(true),
+        proxyConfiguration: validators.proxyConfiguration.optional(),
+        ignoreIframes: z.boolean().default(false),
+        ignoreShadowRoots: z.boolean().default(false),
     };
+    static optionsSchema = z.strictObject(BrowserCrawler.optionsShape);
     /**
      * All `BrowserCrawler` parameters are passed via an options object.
      */
     constructor(options) {
-        ow(options, 'BrowserCrawlerOptions', ow.object.exactShape(BrowserCrawler.optionsShape));
-        const { navigationTimeoutSecs = 60, saveResponseCookies = true, launchContext = {}, browserPool, remoteBrowser, browserPoolOptions, preNavigationHooks = [], postNavigationHooks = [], headless, ignoreIframes = false, ignoreShadowRoots = false, contextPipelineBuilder, extendContext, ...basicCrawlerOptions } = options;
+        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)) ?? {})),
         });
@@ -103,18 +123,18 @@ export class BrowserCrawler extends BasicCrawler {
                 // hook eats into the same window the navigation uses. The navigation itself is bounded by
                 // capping its `gotoOptions.timeout` to the remaining budget.
                 const windowGuard = (step) => skipGuard(async (ctx) => {
-                    const remaining = remainingNavigationWindowMillis(ctx, this.navigationTimeoutMillis);
+                    const remaining = remainingNavigationWindowMillis(ctx, this.#navigationTimeoutMillis);
                     if (remaining <= 0) {
-                        throw new TimeoutError(`Navigation timed out after ${this.navigationTimeoutMillis / 1000} seconds.`);
+                        throw new TimeoutError(`Navigation timed out after ${this.#navigationTimeoutMillis / 1000} seconds.`);
                     }
-                    return addTimeoutToPromise(async () => step(ctx), remaining, `Navigation timed out after ${this.navigationTimeoutMillis / 1000} seconds.`);
+                    return addTimeoutToPromise(async () => step(ctx), remaining, `Navigation timed out after ${this.#navigationTimeoutMillis / 1000} seconds.`);
                 });
                 let pipeline = contextPipelineBuilder().compose({ action: this.prepareNavigation.bind(this) });
-                for (const hook of this.preNavigationHooks) {
+                for (const hook of this.#preNavigationHooks) {
                     pipeline = pipeline.compose(windowGuard(hook));
                 }
                 pipeline = pipeline.compose(skipGuard(this.navigate.bind(this)));
-                for (const hook of this.postNavigationHooks) {
+                for (const hook of this.#postNavigationHooks) {
                     pipeline = pipeline.compose(windowGuard(hook));
                 }
                 return pipeline
@@ -125,50 +145,19 @@ export class BrowserCrawler extends BasicCrawler {
             extendContext,
         });
         this.launchContext = launchContext;
-        this.navigationTimeoutMillis = navigationTimeoutSecs * 1000;
+        this.#navigationTimeoutMillis = navigationTimeoutSecs * 1000;
         // The public option hooks are extension-aware; internal storage uses the base context type
         // (the pipeline composes hooks against the concrete context, which does not statically carry
         // `ContextExtension`). The extension members are present at runtime regardless.
-        this.preNavigationHooks = preNavigationHooks;
-        this.postNavigationHooks = postNavigationHooks;
+        this.#preNavigationHooks = preNavigationHooks;
+        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.#saveResponseCookies = saveResponseCookies;
+        this.#browserPoolDep = OwnedOrInjected.resolve(browserPool, () => browserPoolBuilder(remoteBrowser));
     }
     getNavigationTimeoutMillis() {
-        return this.navigationTimeoutMillis;
+        return this.#navigationTimeoutMillis;
     }
     buildContextPipeline() {
         return ContextPipeline.create().compose({
@@ -217,7 +206,10 @@ export class BrowserCrawler extends BasicCrawler {
             session: crawlingContext.session,
         });
         tryCancel();
-        const contextEnqueueLinks = crawlingContext.enqueueLinks;
+        const addRequests = crawlingContext.addRequests;
+        const extractLinks = async (options) => {
+            return extractUrlsFromPage(page, options?.selector ?? 'a', options?.baseUrl ?? crawlingContext.request.loadedUrl ?? crawlingContext.request.url);
+        };
         return {
             page,
             get response() {
@@ -226,20 +218,20 @@ export class BrowserCrawler extends BasicCrawler {
             get gotoOptions() {
                 throw new Error('The `gotoOptions` property is not available until `prepareNavigation` runs.');
             },
-            enqueueLinks: async (enqueueOptions = {}) => {
-                return (await browserCrawlerEnqueueLinks({
-                    options: {
-                        ...enqueueOptions,
-                        limit: await this.calculateEnqueuedRequestLimit(enqueueOptions?.limit),
-                    },
-                    page,
-                    requestManager: await this.getRequestManager(),
-                    robotsTxtFile: await this.getRobotsTxtFileForUrl(crawlingContext.request.url),
-                    onSkippedRequest: this.handleSkippedRequest,
-                    originalRequestUrl: crawlingContext.request.url,
+            extractLinks,
+            enqueueLinks: async (options = {}) => {
+                const baseUrl = resolveBaseUrlForEnqueueLinksFiltering({
+                    enqueueStrategy: options.strategy,
                     finalRequestUrl: crawlingContext.request.loadedUrl,
-                    enqueueLinks: contextEnqueueLinks,
-                })); // TODO make this type safe
+                    originalRequestUrl: crawlingContext.request.url,
+                    userProvidedBaseUrl: options.baseUrl,
+                });
+                const urls = await extractLinks(options);
+                return addRequests(urls, {
+                    ...options,
+                    baseUrl,
+                    strategy: options.strategy ?? EnqueueStrategy.SameHostname,
+                });
             },
         };
     }
@@ -263,31 +255,31 @@ export class BrowserCrawler extends BasicCrawler {
         return {
             // Default to the full navigation timeout so a pre-navigation hook can read it; `navigate` narrows it
             // to the remaining shared window unless a hook overrode it (see there).
-            gotoOptions: { timeout: this.navigationTimeoutMillis },
-            [COOKIES_BEFORE_HOOKS]: this._getCookieHeaderFromRequest(crawlingContext.request),
+            gotoOptions: { timeout: this.#navigationTimeoutMillis },
+            [COOKIES_BEFORE_HOOKS]: this.getCookieHeaderFromRequest(crawlingContext.request),
         };
     }
     async navigate(crawlingContext) {
         tryCancel();
         const gotoOptions = crawlingContext.gotoOptions;
-        const remaining = remainingNavigationWindowMillis(crawlingContext, this.navigationTimeoutMillis);
+        const remaining = remainingNavigationWindowMillis(crawlingContext, this.#navigationTimeoutMillis);
         if (remaining <= 0) {
-            throw new TimeoutError(`Navigation timed out after ${this.navigationTimeoutMillis / 1000} seconds.`);
+            throw new TimeoutError(`Navigation timed out after ${this.#navigationTimeoutMillis / 1000} seconds.`);
         }
         // If a hook left the default `navigationTimeoutMillis` in place, bound the goto to whatever is left of the
         // shared navigation window. If it overrode the value - including `0`, Playwright's "no timeout" - honour
         // that verbatim as the goto's own timeout. The driver enforces this natively (so a timed-out goto is
         // aborted, not left lingering) and `handleNavigationTimeout` turns its error into our own message.
         const gotoTimeout = gotoOptions;
-        if (gotoTimeout.timeout === this.navigationTimeoutMillis) {
+        if (gotoTimeout.timeout === this.#navigationTimeoutMillis) {
             gotoTimeout.timeout = remaining;
         }
         const cookiesBeforeHooks = readContextField(crawlingContext, COOKIES_BEFORE_HOOKS);
-        const cookiesAfterHooks = this._getCookieHeaderFromRequest(crawlingContext.request);
+        const cookiesAfterHooks = this.getCookieHeaderFromRequest(crawlingContext.request);
         await this.applyCookies(crawlingContext, cookiesBeforeHooks, cookiesAfterHooks);
         let response;
         try {
-            response = (await this._navigationHandler(crawlingContext, gotoOptions)) ?? undefined;
+            response = (await this.navigationHandler(crawlingContext, gotoOptions)) ?? undefined;
         }
         catch (error) {
             await this.handleNavigationTimeout(crawlingContext, error);
@@ -320,7 +312,7 @@ export class BrowserCrawler extends BasicCrawler {
      * Copies cookies from the live browser page into the session cookie jar.
      */
     async persistCookiesFromPage(crawlingContext) {
-        if (!this.saveResponseCookies || !crawlingContext.session) {
+        if (!this.#saveResponseCookies || !crawlingContext.session) {
             return;
         }
         const { cookies } = await this.browserPool.extractPageState(crawlingContext.page);
@@ -329,7 +321,7 @@ export class BrowserCrawler extends BasicCrawler {
         const url = (await crawlingContext.page.url()) || crawlingContext.request.loadedUrl || crawlingContext.request.url;
         for (const cookie of cookies) {
             try {
-                crawlingContext.session.cookieJar.setCookieSync(browserPoolCookieToToughCookie(cookie), url, {
+                await crawlingContext.session.cookieJar.setCookie(browserPoolCookieToToughCookie(cookie), url, {
                     ignoreError: false,
                 });
             }
@@ -370,7 +362,9 @@ export class BrowserCrawler extends BasicCrawler {
         return {};
     }
     async applyCookies({ session, request, page }, preHooksCookies, postHooksCookies) {
-        const sessionCookie = session?.cookieJar.getCookiesSync(request.url).map(toughCookieToBrowserPoolCookie) ?? [];
+        const sessionCookie = session
+            ? (await session.cookieJar.getCookies(request.url)).map(toughCookieToBrowserPoolCookie)
+            : [];
         const parsedPreHooksCookies = preHooksCookies.split(/ *; */).map((c) => cookieStringToToughCookie(c));
         const parsedPostHooksCookies = postHooksCookies.split(/ *; */).map((c) => cookieStringToToughCookie(c));
         const cookies = [...sessionCookie, ...parsedPreHooksCookies, ...parsedPostHooksCookies]
@@ -390,7 +384,7 @@ export class BrowserCrawler extends BasicCrawler {
             session?.markBad();
             // The driver was handed the remaining window (usually shorter than `navigationTimeoutSecs` once the
             // hooks have run), so it names that value in its own error; report the configured window instead.
-            throw new TimeoutError(`Navigation timed out after ${this.navigationTimeoutMillis / 1000} seconds.`);
+            throw new TimeoutError(`Navigation timed out after ${this.#navigationTimeoutMillis / 1000} seconds.`);
         }
     }
     /**
@@ -398,14 +392,23 @@ export class BrowserCrawler extends BasicCrawler {
      */
     throwIfProxyError(error) {
         if (this.isProxyError(error)) {
-            throw new SessionError(this._getMessageFromError(error));
+            throw new SessionError(this.getMessageFromError(error));
         }
     }
     async processResponse(response, crawlingContext) {
         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) {
+                // Both drivers lower-case header names and join duplicates, so a plain lookup is enough.
+                const retryAfter = response.headers?.()['retry-after'];
+                if (this.recordDomainRateLimit(crawlingContext.request.url, retryAfter)) {
+                    throw new RequestThrottledError(`${crawlingContext.request.url} responded with 429.`);
+                }
+            }
             if (this.isErrorStatusCode(status)) {
                 if (this.additionalHttpErrorStatusCodes.has(status)) {
                     throw new Error(`${status} - Error status code was set by user.`);
@@ -415,7 +418,7 @@ export class BrowserCrawler extends BasicCrawler {
         }
         if (this.sessionPool && response && session) {
             if (typeof response === 'object' && typeof response.status === 'function') {
-                this._throwOnBlockedRequest(response.status());
+                this.throwOnBlockedRequest(response.status());
             }
             else {
                 this.log.debug('Got a malformed Browser response.', { request, response });
@@ -428,40 +431,10 @@ export class BrowserCrawler extends BasicCrawler {
      * @ignore
      */
     async teardown() {
-        await this.browserPoolDep.ifOwned((pool) => pool.destroy());
+        await this.#browserPoolDep.ifOwned((pool) => pool.destroy());
         await super.teardown();
     }
 }
-/** @internal */
-function containsEnqueueLinks(options) {
-    return !!options.enqueueLinks;
-}
-/** @internal */
-export async function browserCrawlerEnqueueLinks(options) {
-    const { options: enqueueLinksOptions, finalRequestUrl, originalRequestUrl, page } = options;
-    const baseUrl = resolveBaseUrlForEnqueueLinksFiltering({
-        enqueueStrategy: enqueueLinksOptions?.strategy,
-        finalRequestUrl,
-        originalRequestUrl,
-        userProvidedBaseUrl: enqueueLinksOptions?.baseUrl,
-    });
-    const urls = await extractUrlsFromPage(page, enqueueLinksOptions?.selector ?? 'a', enqueueLinksOptions?.baseUrl ?? finalRequestUrl ?? originalRequestUrl);
-    if (containsEnqueueLinks(options)) {
-        return options.enqueueLinks({
-            urls,
-            baseUrl,
-            ...enqueueLinksOptions,
-        });
-    }
-    return enqueueLinks({
-        requestManager: options.requestManager,
-        robotsTxtFile: options.robotsTxtFile,
-        onSkippedRequest: options.onSkippedRequest,
-        urls,
-        baseUrl,
-        ...enqueueLinksOptions,
-    });
-}
 /**
  * Extracts URLs from a given page.
  * @ignore

package/internals/browser-launcher.d.ts

@@ -1,6 +1,8 @@
 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> {
     /**
      * URL to an HTTP proxy server. It must define the port number,
@@ -64,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
@@ -78,23 +93,25 @@ export declare abstract class BrowserLauncher<Plugin extends BrowserPlugin, Laun
     Plugin: T;
     userAgent?: string;
     protected static optionsShape: {
-// @ts-ignore optional peer dependency or compatibility with es2022
-        proxyUrl: import("ow").StringPredicate & import("ow").BasePredicate<string | undefined>;
-// @ts-ignore optional peer dependency or compatibility with es2022
-        useChrome: import("ow").BooleanPredicate & import("ow").BasePredicate<boolean | undefined>;
-// @ts-ignore optional peer dependency or compatibility with es2022
-        useIncognitoPages: import("ow").BooleanPredicate & import("ow").BasePredicate<boolean | undefined>;
-// @ts-ignore optional peer dependency or compatibility with es2022
-        browserPerProxy: import("ow").BooleanPredicate & import("ow").BasePredicate<boolean | undefined>;
-// @ts-ignore optional peer dependency or compatibility with es2022
-        ignoreProxyCertificate: import("ow").BooleanPredicate & import("ow").BasePredicate<boolean | undefined>;
-// @ts-ignore optional peer dependency or compatibility with es2022
-        userDataDir: import("ow").StringPredicate & import("ow").BasePredicate<string | undefined>;
-// @ts-ignore optional peer dependency or compatibility with es2022
-        launchOptions: import("ow").ObjectPredicate<object> & import("ow").BasePredicate<object | undefined>;
-// @ts-ignore optional peer dependency or compatibility with es2022
-        userAgent: import("ow").StringPredicate & import("ow").BasePredicate<string | undefined>;
+        proxyUrl: z.ZodOptional<z.ZodURL>;
+        useChrome: z.ZodOptional<z.ZodBoolean>;
+        useIncognitoPages: z.ZodOptional<z.ZodBoolean>;
+        browserPerProxy: z.ZodOptional<z.ZodBoolean>;
+        ignoreProxyCertificate: z.ZodOptional<z.ZodBoolean>;
+        userDataDir: z.ZodOptional<z.ZodString>;
+        launchOptions: z.ZodOptional<z.ZodCustom<Dictionary, Dictionary>>;
+        userAgent: z.ZodOptional<z.ZodString>;
     };
+    protected static optionsSchema: z.ZodObject<{
+        proxyUrl: z.ZodOptional<z.ZodURL>;
+        useChrome: z.ZodOptional<z.ZodBoolean>;
+        useIncognitoPages: z.ZodOptional<z.ZodBoolean>;
+        browserPerProxy: z.ZodOptional<z.ZodBoolean>;
+        ignoreProxyCertificate: z.ZodOptional<z.ZodBoolean>;
+        userDataDir: z.ZodOptional<z.ZodString>;
+        launchOptions: z.ZodOptional<z.ZodCustom<Dictionary, Dictionary>>;
+        userAgent: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
     static requireLauncherOrThrow<T>(launcher: string, apifyImageName: string): T;
     /**
      * All `BrowserLauncher` parameters are passed via an launchContext object.
@@ -104,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,8 +1,9 @@
 import fs from 'node:fs';
 import { createRequire } from 'node:module';
 import os from 'node:os';
-import { Configuration } from '@crawlee/basic';
-import ow from 'ow';
+import { Configuration, schemas, serviceLocator } from '@crawlee/basic';
+import { BrowserPool, RemoteBrowserPool } from '@crawlee/browser-pool';
+import { z } from 'zod';
 const DEFAULT_VIEWPORT = {
     width: 1366,
     height: 768,
@@ -23,15 +24,16 @@ export class BrowserLauncher {
     Plugin;
     userAgent;
     static optionsShape = {
-        proxyUrl: ow.optional.string.url,
-        useChrome: ow.optional.boolean,
-        useIncognitoPages: ow.optional.boolean,
-        browserPerProxy: ow.optional.boolean,
-        ignoreProxyCertificate: ow.optional.boolean,
-        userDataDir: ow.optional.string,
-        launchOptions: ow.optional.object,
-        userAgent: ow.optional.string,
+        proxyUrl: z.url().optional(),
+        useChrome: z.boolean().optional(),
+        useIncognitoPages: z.boolean().optional(),
+        browserPerProxy: z.boolean().optional(),
+        ignoreProxyCertificate: z.boolean().optional(),
+        userDataDir: z.string().optional(),
+        launchOptions: schemas.anyObject.optional(),
+        userAgent: z.string().optional(),
     };
+    static optionsSchema = z.strictObject(BrowserLauncher.optionsShape);
     static requireLauncherOrThrow(launcher, apifyImageName) {
         try {
             return require(launcher); // eslint-disable-line
@@ -73,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.98",
+    "version": "4.0.0-rc.0",
     "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,13 +48,13 @@
     },
     "dependencies": {
         "@apify/timeout": "^0.4.4",
-        "@crawlee/basic": "4.0.0-beta.98",
-        "@crawlee/browser-pool": "4.0.0-beta.98",
-        "@crawlee/types": "4.0.0-beta.98",
-        "@crawlee/utils": "4.0.0-beta.98",
-        "ow": "^2.0.0",
+        "@crawlee/basic": "4.0.0-rc.0",
+        "@crawlee/browser-pool": "4.0.0-rc.0",
+        "@crawlee/types": "4.0.0-rc.0",
+        "@crawlee/utils": "4.0.0-rc.0",
         "tslib": "^2.8.1",
-        "type-fest": "^4.41.0"
+        "type-fest": "^4.41.0",
+        "zod": "^4.4.3"
     },
     "peerDependencies": {
         "playwright": "*",
@@ -75,5 +75,5 @@
             }
         }
     },
-    "gitHead": "3b8cd86b13e253ab5fc71e631e12a68f7465cee5"
+    "gitHead": "79ab33dacdacb83e0197e6516d145f3aceef80c7"
 }