@crawlee/stagehand 4.0.0-beta.99 → 4.0.0-rc.0

package/index.d.ts

@@ -51,6 +51,8 @@
  */
 export * from '@crawlee/browser';
 export { StagehandCrawler, createStagehandRouter } from './internals/stagehand-crawler';
+export { stagehandBrowserPool, remoteStagehandBrowserPool } from './internals/stagehand-browser-pool';
+export type { StagehandBrowserPool, StagehandBrowserPoolOptions, RemoteStagehandBrowserPoolOptions, } from './internals/stagehand-browser-pool';
 export type { StagehandOptions, StagehandPage, StagehandCrawlingContext, StagehandHook, StagehandRequestHandler, StagehandGotoOptions, StagehandCrawlerOptions, } from './internals/stagehand-crawler';
 export type { StagehandLaunchContext } from './internals/stagehand-launcher';
 export * as stagehandUtils from './internals/utils/stagehand-utils';

package/index.js

@@ -51,7 +51,7 @@
  * @module @crawlee/stagehand
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.stagehandUtils = exports.createStagehandRouter = exports.StagehandCrawler = void 0;
+exports.stagehandUtils = exports.remoteStagehandBrowserPool = exports.stagehandBrowserPool = exports.createStagehandRouter = exports.StagehandCrawler = void 0;
 const tslib_1 = require("tslib");
 // Re-export everything from @crawlee/browser for convenience
 tslib_1.__exportStar(require("@crawlee/browser"), exports);
@@ -59,5 +59,9 @@ tslib_1.__exportStar(require("@crawlee/browser"), exports);
 var stagehand_crawler_1 = require("./internals/stagehand-crawler");
 Object.defineProperty(exports, "StagehandCrawler", { enumerable: true, get: function () { return stagehand_crawler_1.StagehandCrawler; } });
 Object.defineProperty(exports, "createStagehandRouter", { enumerable: true, get: function () { return stagehand_crawler_1.createStagehandRouter; } });
+// Export the browser pool factories, which are how a pool with non-default options reaches the crawler
+var stagehand_browser_pool_1 = require("./internals/stagehand-browser-pool");
+Object.defineProperty(exports, "stagehandBrowserPool", { enumerable: true, get: function () { return stagehand_browser_pool_1.stagehandBrowserPool; } });
+Object.defineProperty(exports, "remoteStagehandBrowserPool", { enumerable: true, get: function () { return stagehand_browser_pool_1.remoteStagehandBrowserPool; } });
 // Export utilities as namespace
 exports.stagehandUtils = tslib_1.__importStar(require("./internals/utils/stagehand-utils"));

package/index.mjs

@@ -3,13 +3,13 @@ import mod from "./index.js";
 export default mod;
 export const API_PROCESSED_REQUESTS_DELAY_MILLIS = mod.API_PROCESSED_REQUESTS_DELAY_MILLIS;
 export const ApifyLogAdapter = mod.ApifyLogAdapter;
+export const ArgumentValidationError = mod.ArgumentValidationError;
 export const AutoscaledPool = mod.AutoscaledPool;
 export const BLOCKED_STATUS_CODES = mod.BLOCKED_STATUS_CODES;
 export const BaseCrawleeLogger = mod.BaseCrawleeLogger;
 export const BasicCrawler = mod.BasicCrawler;
 export const BrowserCrawler = mod.BrowserCrawler;
 export const BrowserLauncher = mod.BrowserLauncher;
-export const ClientLoadSignal = mod.ClientLoadSignal;
 export const ConcurrencySystem = mod.ConcurrencySystem;
 export const Configuration = mod.Configuration;
 export const ContextPipeline = mod.ContextPipeline;
@@ -46,19 +46,19 @@ export const NavigationSkippedError = mod.NavigationSkippedError;
 export const NonRetryableError = mod.NonRetryableError;
 export const OwnedOrInjected = mod.OwnedOrInjected;
 export const PERSIST_STATE_KEY = mod.PERSIST_STATE_KEY;
+export const PersistentRateLimitError = mod.PersistentRateLimitError;
 export const ProxyConfiguration = mod.ProxyConfiguration;
-export const PseudoUrl = mod.PseudoUrl;
 export const QUERY_HEAD_BUFFER = mod.QUERY_HEAD_BUFFER;
 export const QUERY_HEAD_MIN_LENGTH = mod.QUERY_HEAD_MIN_LENGTH;
 export const REQUESTS_PERSISTENCE_KEY = mod.REQUESTS_PERSISTENCE_KEY;
 export const RecoverableState = mod.RecoverableState;
 export const Request = mod.Request;
 export const RequestHandlerError = mod.RequestHandlerError;
-export const RequestHandlerResult = mod.RequestHandlerResult;
 export const RequestList = mod.RequestList;
 export const RequestManagerTandem = mod.RequestManagerTandem;
 export const RequestQueue = mod.RequestQueue;
 export const RequestState = mod.RequestState;
+export const RequestThrottledError = mod.RequestThrottledError;
 export const RequestValidationError = mod.RequestValidationError;
 export const RetryRequestError = mod.RetryRequestError;
 export const Router = mod.Router;
@@ -73,21 +73,27 @@ export const SitemapRequestLoader = mod.SitemapRequestLoader;
 export const SnapshotStore = mod.SnapshotStore;
 export const Snapshotter = mod.Snapshotter;
 export const StagehandCrawler = mod.StagehandCrawler;
+export const StateValidationError = mod.StateValidationError;
 export const Statistics = mod.Statistics;
+export const StorageBackendLoadSignal = mod.StorageBackendLoadSignal;
 export const StorageInstanceManager = mod.StorageInstanceManager;
 export const StorageStatsTracker = mod.StorageStatsTracker;
+export const StorageTransaction = mod.StorageTransaction;
 export const SystemStatus = mod.SystemStatus;
+export const ThrottlingRequestManager = mod.ThrottlingRequestManager;
+export const activeStorageTransaction = mod.activeStorageTransaction;
 export const applyRequestTransform = mod.applyRequestTransform;
+export const assertBrowserPoolNotConfigured = mod.assertBrowserPoolNotConfigured;
 export const assertJsonSerializable = mod.assertJsonSerializable;
 export const bindMethodsToServiceLocator = mod.bindMethodsToServiceLocator;
-export const browserCrawlerEnqueueLinks = mod.browserCrawlerEnqueueLinks;
 export const browserPoolCookieToToughCookie = mod.browserPoolCookieToToughCookie;
-export const checkStorageAccess = mod.checkStorageAccess;
+export const buildEnqueueStrategyPatterns = mod.buildEnqueueStrategyPatterns;
 export const coerceBoolean = mod.coerceBoolean;
 export const coerceNumber = mod.coerceNumber;
 export const constructGlobObjectsFromGlobs = mod.constructGlobObjectsFromGlobs;
-export const constructRegExpObjectsFromPseudoUrls = mod.constructRegExpObjectsFromPseudoUrls;
 export const constructRegExpObjectsFromRegExps = mod.constructRegExpObjectsFromRegExps;
+export const constructUrlPatternObjects = mod.constructUrlPatternObjects;
+export const convertStateSync = mod.convertStateSync;
 export const cookieStringToToughCookie = mod.cookieStringToToughCookie;
 export const crawleeConfigFields = mod.crawleeConfigFields;
 export const createBasicRouter = mod.createBasicRouter;
@@ -96,9 +102,10 @@ export const createDualIterable = mod.createDualIterable;
 export const createRequestDebugInfo = mod.createRequestDebugInfo;
 export const createRequestOptions = mod.createRequestOptions;
 export const createStagehandRouter = mod.createStagehandRouter;
+export const createStorageTransaction = mod.createStorageTransaction;
+export const currentStorageTransaction = mod.currentStorageTransaction;
 export const defaultRoute = mod.defaultRoute;
 export const deserializeArray = mod.deserializeArray;
-export const enqueueLinks = mod.enqueueLinks;
 export const evaluateLoadSignalSample = mod.evaluateLoadSignalSample;
 export const extractUrlsFromPage = mod.extractUrlsFromPage;
 export const field = mod.field;
@@ -111,20 +118,31 @@ export const inspectValue = mod.inspectValue;
 export const log = mod.log;
 export const mergeCookies = mod.mergeCookies;
 export const navigationDeadlineKey = mod.navigationDeadlineKey;
+export const operationRejectedInTransaction = mod.operationRejectedInTransaction;
+export const parseArgument = mod.parseArgument;
+export const parseRetryAfterHeader = mod.parseRetryAfterHeader;
 export const parseValue = mod.parseValue;
 export const purgeDefaultStorages = mod.purgeDefaultStorages;
+export const rejectOperationInTransaction = mod.rejectOperationInTransaction;
 export const remainingNavigationWindowMillis = mod.remainingNavigationWindowMillis;
+export const remoteStagehandBrowserPool = mod.remoteStagehandBrowserPool;
 export const resolveBaseUrlForEnqueueLinksFiltering = mod.resolveBaseUrlForEnqueueLinksFiltering;
 export const resolveStorageIdentifier = mod.resolveStorageIdentifier;
+export const schemas = mod.schemas;
 export const serializeArray = mod.serializeArray;
 export const serializeValue = mod.serializeValue;
 export const serviceLocator = mod.serviceLocator;
+export const snapshotValue = mod.snapshotValue;
+export const stagehandBrowserPool = mod.stagehandBrowserPool;
 export const stagehandUtils = mod.stagehandUtils;
+export const supportsDomainThrottling = mod.supportsDomainThrottling;
 export const toughCookieToBrowserPoolCookie = mod.toughCookieToBrowserPoolCookie;
 export const tryAbsoluteURL = mod.tryAbsoluteURL;
 export const updateEnqueueLinksPatternCache = mod.updateEnqueueLinksPatternCache;
+export const urlPatternSchema = mod.urlPatternSchema;
 export const useState = mod.useState;
 export const validateGlobPattern = mod.validateGlobPattern;
 export const validateUserData = mod.validateUserData;
 export const validators = mod.validators;
-export const withCheckedStorageAccess = mod.withCheckedStorageAccess;
+export const withDirectStorageAccess = mod.withDirectStorageAccess;
+export const withStorageTransaction = mod.withStorageTransaction;

package/internals/stagehand-browser-pool.d.ts

@@ -0,0 +1,63 @@
+import type { Configuration } from '@crawlee/browser';
+import type { BrowserPool, BrowserPoolHooks, BrowserPoolOptions, RemoteBrowserPool, RemoteBrowserPoolOptions } from '@crawlee/browser-pool';
+// @ts-ignore optional peer dependency or compatibility with es2022
+import type { Page } from 'playwright';
+import type { StagehandOptions } from './stagehand-crawler';
+import type { StagehandLaunchContext } from './stagehand-launcher';
+import type { StagehandPlugin } from './stagehand-plugin';
+/** A {@link BrowserPool} of Stagehand browsers, as built by {@link stagehandBrowserPool}. */
+export type StagehandBrowserPool = BrowserPool<{
+    browserPlugins: [StagehandPlugin];
+}, [StagehandPlugin]>;
+export interface StagehandBrowserPoolOptions extends Omit<BrowserPoolOptions, 'browserPlugins'>, BrowserPoolHooks<ReturnType<StagehandPlugin['createController']>, ReturnType<StagehandPlugin['createLaunchContext']>, Page> {
+    /** How to launch the browser: which Playwright browser type, proxy, user data dir, ... */
+    launchContext?: StagehandLaunchContext;
+    /** Stagehand configuration for the AI behavior and Browserbase integration. */
+    stagehandOptions?: StagehandOptions;
+    /**
+     * Whether to run the browser in headless mode. Shorthand for `launchContext.launchOptions.headless`.
+     * Defaults to `true`, and can also be set via {@link Configuration}.
+     */
+    headless?: boolean;
+    /** Configuration to read the browser defaults from. Defaults to the global configuration. */
+    configuration?: Configuration;
+}
+export interface RemoteStagehandBrowserPoolOptions extends Pick<StagehandBrowserPoolOptions, 'launchContext' | 'stagehandOptions' | 'headless' | 'configuration'>, Omit<RemoteBrowserPoolOptions, 'browserPlugins'> {
+}
+/**
+ * Builds a {@link BrowserPool} of Stagehand browsers to pass to a {@link StagehandCrawler} as its
+ * {@link BrowserCrawlerOptions.browserPool|`browserPool`}.
+ *
+ * It accepts every {@link BrowserPoolOptions|`BrowserPool` option} plus the crawler's own `launchContext`,
+ * `stagehandOptions` and `headless`, and derives the browser plugin from them - so a pool built here always
+ * matches the crawler it is given to, and configuring one never means assembling a {@link StagehandPlugin}
+ * by hand.
+ *
+ * **Example usage:**
+ *
+ * ```javascript
+ * const crawler = new StagehandCrawler({
+ *     browserPool: stagehandBrowserPool({
+ *         maxOpenPagesPerBrowser: 1,
+ *         stagehandOptions: { env: 'LOCAL', model: 'openai/gpt-4.1-mini' },
+ *     }),
+ *     requestHandler: async ({ page }) => { ... },
+ * });
+ * ```
+ *
+ * The returned pool is *not* torn down by the crawler, which is what makes it shareable between crawlers.
+ *
+ * @category Browser management
+ */
+export declare function stagehandBrowserPool(options?: StagehandBrowserPoolOptions): StagehandBrowserPool;
+/**
+ * The {@link RemoteBrowserPool} counterpart of {@link stagehandBrowserPool}: connects to a remote browser
+ * service with a Stagehand plugin derived from `launchContext` and `stagehandOptions`.
+ *
+ * A {@link StagehandCrawler} accepts the same connection details directly via
+ * {@link BrowserCrawlerOptions.remoteBrowser|`remoteBrowser`}; reach for this factory when you also need to
+ * tune the wrapping pool, or to share one remote pool between crawlers.
+ *
+ * @category Browser management
+ */
+export declare function remoteStagehandBrowserPool(options: RemoteStagehandBrowserPoolOptions): RemoteBrowserPool<Page>;

package/internals/stagehand-browser-pool.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stagehandBrowserPool = stagehandBrowserPool;
+exports.remoteStagehandBrowserPool = remoteStagehandBrowserPool;
+const stagehand_launcher_1 = require("./stagehand-launcher");
+/**
+ * Builds a {@link BrowserPool} of Stagehand browsers to pass to a {@link StagehandCrawler} as its
+ * {@link BrowserCrawlerOptions.browserPool|`browserPool`}.
+ *
+ * It accepts every {@link BrowserPoolOptions|`BrowserPool` option} plus the crawler's own `launchContext`,
+ * `stagehandOptions` and `headless`, and derives the browser plugin from them - so a pool built here always
+ * matches the crawler it is given to, and configuring one never means assembling a {@link StagehandPlugin}
+ * by hand.
+ *
+ * **Example usage:**
+ *
+ * ```javascript
+ * const crawler = new StagehandCrawler({
+ *     browserPool: stagehandBrowserPool({
+ *         maxOpenPagesPerBrowser: 1,
+ *         stagehandOptions: { env: 'LOCAL', model: 'openai/gpt-4.1-mini' },
+ *     }),
+ *     requestHandler: async ({ page }) => { ... },
+ * });
+ * ```
+ *
+ * The returned pool is *not* torn down by the crawler, which is what makes it shareable between crawlers.
+ *
+ * @category Browser management
+ */
+function stagehandBrowserPool(options = {}) {
+    const { launchContext, stagehandOptions, headless, configuration, ...poolOptions } = options;
+    return stagehandLauncher(launchContext, stagehandOptions, headless, configuration).createBrowserPool(poolOptions);
+}
+/**
+ * The {@link RemoteBrowserPool} counterpart of {@link stagehandBrowserPool}: connects to a remote browser
+ * service with a Stagehand plugin derived from `launchContext` and `stagehandOptions`.
+ *
+ * A {@link StagehandCrawler} accepts the same connection details directly via
+ * {@link BrowserCrawlerOptions.remoteBrowser|`remoteBrowser`}; reach for this factory when you also need to
+ * tune the wrapping pool, or to share one remote pool between crawlers.
+ *
+ * @category Browser management
+ */
+function remoteStagehandBrowserPool(options) {
+    const { launchContext, stagehandOptions, headless, configuration, ...remoteOptions } = options;
+    return stagehandLauncher(launchContext, stagehandOptions, headless, configuration).createRemoteBrowserPool(remoteOptions);
+}
+function stagehandLauncher(launchContext = {}, stagehandOptions = {}, headless, configuration) {
+    return new stagehand_launcher_1.StagehandLauncher({
+        ...launchContext,
+        stagehandOptions,
+        ...(headless == null ? {} : { launchOptions: { ...launchContext.launchOptions, headless } }),
+    }, configuration);
+}

package/internals/stagehand-controller.d.ts

@@ -18,8 +18,7 @@ import type { StagehandPlugin } from './stagehand-plugin';
  * @ignore
  */
 export declare class StagehandController extends BrowserController<BrowserType, LaunchOptions, PlaywrightBrowser> {
-    private stagehand;
-    private readonly stagehandInstances;
+    #private;
     constructor(browserPlugin: StagehandPlugin, stagehandInstances: WeakMap<PlaywrightBrowser, Stagehand>);
     /**
      * Gets the Stagehand instance associated with this controller's browser.

package/internals/stagehand-controller.js

@@ -18,23 +18,23 @@ const utils_1 = require("@crawlee/utils");
  * @ignore
  */
 class StagehandController extends browser_pool_1.BrowserController {
-    stagehand = null;
-    stagehandInstances;
+    #stagehand = null;
+    #stagehandInstances;
     constructor(browserPlugin, stagehandInstances) {
         super(browserPlugin);
-        this.stagehandInstances = stagehandInstances;
+        this.#stagehandInstances = stagehandInstances;
     }
     /**
      * Gets the Stagehand instance associated with this controller's browser.
      */
     getStagehand() {
-        if (!this.stagehand) {
-            this.stagehand = this.stagehandInstances.get(this.browser);
-            if (!this.stagehand) {
+        if (!this.#stagehand) {
+            this.#stagehand = this.#stagehandInstances.get(this.browser);
+            if (!this.#stagehand) {
                 throw new Error('Stagehand instance not found for browser');
             }
         }
-        return this.stagehand;
+        return this.#stagehand;
     }
     /**
      * Creates a new page using the browser's default context.

package/internals/stagehand-crawler.d.ts

@@ -4,9 +4,8 @@ import { BrowserCrawler } from '@crawlee/browser';
 import type { Dictionary } from '@crawlee/types';
 // @ts-ignore optional peer dependency or compatibility with es2022
 import type { LaunchOptions, Page, Response } from 'playwright';
-import type { z } from 'zod';
+import { z } from 'zod';
 import type { StagehandLaunchContext } from './stagehand-launcher';
-import type { StagehandPlugin } from './stagehand-plugin';
 /**
  * Stagehand-specific configuration options.
  */
@@ -172,7 +171,7 @@ export interface StagehandPage extends Page {
  * Goto options for StagehandCrawler navigation.
  */
 export type StagehandGotoOptions = NonNullable<Parameters<Page['goto']>[1]>;
-export interface StagehandCrawlingContext<UserData extends Dictionary = Dictionary> extends BrowserCrawlingContext<StagehandPage, Response, UserData, StagehandGotoOptions> {
+export interface StagehandCrawlingContext<UserData extends Dictionary = any> extends BrowserCrawlingContext<StagehandPage, Response, UserData, StagehandGotoOptions> {
     /**
      * Enhanced Playwright page with Stagehand AI methods.
      * Use page.act(), page.extract(), page.observe(), page.agent() for AI-powered operations.
@@ -187,8 +186,7 @@ export interface StagehandCrawlingContext<UserData extends Dictionary = Dictiona
 /**
  * Hook function for StagehandCrawler.
  */
-export interface StagehandHook extends BrowserHook<StagehandCrawlingContext> {
-}
+export type StagehandHook<UserData extends Dictionary = any> = BrowserHook<StagehandCrawlingContext<UserData>>;
 /**
  * Request handler for StagehandCrawler.
  */
@@ -197,9 +195,7 @@ export interface StagehandRequestHandler extends RequestHandler<LoadedContext<St
 /**
  * Options for StagehandCrawler.
  */
-export interface StagehandCrawlerOptions<ContextExtension = Dictionary<never>, ExtendedContext extends StagehandCrawlingContext = StagehandCrawlingContext & ContextExtension, Routes extends Record<keyof Routes, Dictionary> = Record<string, GetUserDataFromRequest<StagehandCrawlingContext['request']>>> extends BrowserCrawlerOptions<StagehandPage, Response, StagehandCrawlingContext, ContextExtension, ExtendedContext, {
-    browserPlugins: [StagehandPlugin];
-}, Routes> {
+export interface StagehandCrawlerOptions<ContextExtension = Dictionary<never>, ExtendedContext extends StagehandCrawlingContext = StagehandCrawlingContext & ContextExtension, Routes extends Record<keyof Routes, Dictionary> = Record<string, GetUserDataFromRequest<StagehandCrawlingContext['request']>>, StatisticStateExtension extends object = {}> extends BrowserCrawlerOptions<StagehandPage, Response, StagehandCrawlingContext, ContextExtension, ExtendedContext, Routes, StatisticStateExtension> {
     /**
      * Stagehand-specific configuration options.
      * These options configure the AI behavior and Browserbase integration.
@@ -209,6 +205,11 @@ export interface StagehandCrawlerOptions<ContextExtension = Dictionary<never>, E
      * Launch context with Stagehand-specific options.
      */
     launchContext?: StagehandLaunchContext;
+    /**
+     * Whether to run browser in headless mode. Defaults to `true`.
+     * Can be also set via {@link Configuration}.
+     */
+    headless?: boolean;
     /**
      * Function that is called to process each request.
      *
@@ -257,11 +258,11 @@ export interface StagehandCrawlerOptions<ContextExtension = Dictionary<never>, E
     /**
      * Async functions that are sequentially evaluated before the navigation.
      */
-    preNavigationHooks?: StagehandHook[];
+    preNavigationHooks?: BrowserHook<StagehandCrawlingContext<GetUserDataFromRequest<ExtendedContext['request']>>, ContextExtension>[];
     /**
      * Async functions that are sequentially evaluated after the navigation.
      */
-    postNavigationHooks?: StagehandHook[];
+    postNavigationHooks?: BrowserHook<StagehandCrawlingContext<GetUserDataFromRequest<ExtendedContext['request']>>, ContextExtension>[];
 }
 /**
  * StagehandCrawler provides AI-powered web crawling using Browserbase's Stagehand library.
@@ -312,107 +313,131 @@ export interface StagehandCrawlerOptions<ContextExtension = Dictionary<never>, E
  * await crawler.run(['https://example.com']);
  * ```
  */
-export declare class StagehandCrawler<ContextExtension = Dictionary<never>, ExtendedContext extends StagehandCrawlingContext = StagehandCrawlingContext & ContextExtension, Routes extends Record<keyof Routes, Dictionary> = Record<string, GetUserDataFromRequest<StagehandCrawlingContext['request']>>> extends BrowserCrawler<StagehandPage, Response, {
-    browserPlugins: [StagehandPlugin];
-}, LaunchOptions, StagehandCrawlingContext, ContextExtension, ExtendedContext, Routes> {
+export declare class StagehandCrawler<ContextExtension = Dictionary<never>, ExtendedContext extends StagehandCrawlingContext = StagehandCrawlingContext & ContextExtension, Routes extends Record<keyof Routes, Dictionary> = Record<string, GetUserDataFromRequest<StagehandCrawlingContext['request']>>, StatisticStateExtension extends object = {}> extends BrowserCrawler<StagehandPage, Response, LaunchOptions, StagehandCrawlingContext, ContextExtension, ExtendedContext, Routes, StatisticStateExtension> {
     protected static optionsShape: {
-// @ts-ignore optional peer dependency or compatibility with es2022
-        stagehandOptions: import("ow", { with: { "resolution-mode": "import" } }).ObjectPredicate<object> & import("ow", { with: { "resolution-mode": "import" } }).BasePredicate<object | undefined>;
-// @ts-ignore optional peer dependency or compatibility with es2022
-        browserPoolOptions: import("ow", { with: { "resolution-mode": "import" } }).ObjectPredicate<object> & import("ow", { with: { "resolution-mode": "import" } }).BasePredicate<object | undefined>;
-// @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
-        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>;
+        stagehandOptions: z.ZodOptional<z.ZodCustom<Dictionary, Dictionary>>;
+        headless: z.ZodOptional<z.ZodBoolean>;
+        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/browser").Configuration, import("@crawlee/browser").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/browser").EventManager, import("@crawlee/browser").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<{
+        stagehandOptions: z.ZodOptional<z.ZodCustom<Dictionary, Dictionary>>;
+        headless: z.ZodOptional<z.ZodBoolean>;
+        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/browser").Configuration, import("@crawlee/browser").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/browser").EventManager, import("@crawlee/browser").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>;
     /**
      * Creates a new instance of StagehandCrawler.
      *
      * @param options - Crawler configuration options
      */
-    constructor(options?: StagehandCrawlerOptions<ContextExtension, ExtendedContext, Routes>);
+    constructor(options?: StagehandCrawlerOptions<ContextExtension, ExtendedContext, Routes, StatisticStateExtension>);
     protected buildContextPipeline(): ContextPipeline<CrawlingContext, StagehandCrawlingContext>;
     /**
      * Resolves the {@link StagehandController} that owns the given page, or
@@ -432,7 +457,7 @@ export declare class StagehandCrawler<ContextExtension = Dictionary<never>, Exte
      * Navigation handler for Stagehand crawler.
      * Uses standard Playwright navigation.
      */
-    protected _navigationHandler(crawlingContext: StagehandCrawlingContext, gotoOptions: StagehandGotoOptions): Promise<Response | null>;
+    protected navigationHandler(crawlingContext: StagehandCrawlingContext, gotoOptions: StagehandGotoOptions): Promise<Response | null>;
 }
 /**
  * Creates a new router for StagehandCrawler with type-safe route handlers.
@@ -450,7 +475,7 @@ export declare class StagehandCrawler<ContextExtension = Dictionary<never>, Exte
  * });
  *
  * router.addDefaultHandler(async ({ page, enqueueLinks }) => {
- *   await enqueueLinks({ globs: ['https://example.com/products/*'] });
+ *   await enqueueLinks({ include: ['https://example.com/products/*'] });
  * });
  *
  * const crawler = new StagehandCrawler({

package/internals/stagehand-crawler.js

@@ -2,10 +2,9 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.StagehandCrawler = void 0;
 exports.createStagehandRouter = createStagehandRouter;
-const tslib_1 = require("tslib");
 const browser_1 = require("@crawlee/browser");
-const ow_1 = tslib_1.__importDefault(require("ow"));
-const stagehand_launcher_1 = require("./stagehand-launcher");
+const zod_1 = require("zod");
+const stagehand_browser_pool_1 = require("./stagehand-browser-pool");
 const stagehand_utils_1 = require("./utils/stagehand-utils");
 /**
  * StagehandCrawler provides AI-powered web crawling using Browserbase's Stagehand library.
@@ -59,31 +58,46 @@ const stagehand_utils_1 = require("./utils/stagehand-utils");
 class StagehandCrawler extends browser_1.BrowserCrawler {
     static optionsShape = {
         ...browser_1.BrowserCrawler.optionsShape,
-        stagehandOptions: ow_1.default.optional.object,
-        browserPoolOptions: ow_1.default.optional.object,
+        stagehandOptions: browser_1.schemas.anyObject.optional(),
+        headless: zod_1.z.boolean().optional(),
     };
+    static optionsSchema = zod_1.z.strictObject(StagehandCrawler.optionsShape);
     /**
      * Creates a new instance of StagehandCrawler.
      *
      * @param options - Crawler configuration options
      */
     constructor(options = {}) {
-        (0, ow_1.default)(options, 'StagehandCrawlerOptions', ow_1.default.object.exactShape(StagehandCrawler.optionsShape));
-        const { stagehandOptions = {}, launchContext = {}, contextPipelineBuilder, ...browserCrawlerOptions } = options;
-        const browserPoolOptions = {
-            ...options.browserPoolOptions,
-        };
-        // Create launcher with Stagehand plugin
-        const launcher = new stagehand_launcher_1.StagehandLauncher({
-            ...launchContext,
-            stagehandOptions,
-        });
-        browserPoolOptions.browserPlugins = [launcher.createBrowserPlugin()];
-        // Initialize BrowserCrawler with Stagehand plugin and fingerprinting enabled
+        const parsedOptions = (0, browser_1.parseArgument)(options, StagehandCrawler.optionsSchema, 'StagehandCrawlerOptions');
+        const { stagehandOptions, launchContext, headless, configuration, contextPipelineBuilder, ...browserCrawlerOptions } = parsedOptions;
+        if (options.browserPool) {
+            // The raw options, not the parsed ones: `launchContext` has a default, so by now it is always set.
+            (0, browser_1.assertBrowserPoolNotConfigured)(new.target.name, {
+                launchContext: options.launchContext,
+                stagehandOptions: options.stagehandOptions,
+                headless: options.headless,
+            });
+        }
         super({
             ...browserCrawlerOptions,
             launchContext,
-            browserPoolOptions,
+            configuration,
+            // The pool serves plain Playwright pages - a page only becomes a `StagehandPage` further down the
+            // pipeline, once `setUpStagehand` enhances it - so its page type is narrower than the crawler's.
+            browserPoolBuilder: (remoteBrowser) => (remoteBrowser
+                ? (0, stagehand_browser_pool_1.remoteStagehandBrowserPool)({
+                    ...remoteBrowser,
+                    launchContext,
+                    stagehandOptions,
+                    headless,
+                    configuration,
+                })
+                : (0, stagehand_browser_pool_1.stagehandBrowserPool)({
+                    launchContext,
+                    stagehandOptions,
+                    headless,
+                    configuration,
+                })),
             contextPipelineBuilder: contextPipelineBuilder ?? (() => this.buildContextPipeline()),
         });
     }
@@ -123,7 +137,7 @@ class StagehandCrawler extends browser_1.BrowserCrawler {
      * Navigation handler for Stagehand crawler.
      * Uses standard Playwright navigation.
      */
-    async _navigationHandler(crawlingContext, gotoOptions) {
+    async navigationHandler(crawlingContext, gotoOptions) {
         // Use standard page.goto for navigation
         return crawlingContext.page.goto(crawlingContext.request.url, gotoOptions);
     }

package/internals/stagehand-launcher.d.ts

@@ -2,6 +2,7 @@ import type { BrowserLaunchContext } from '@crawlee/browser';
 import { BrowserLauncher, Configuration } from '@crawlee/browser';
 // @ts-ignore optional peer dependency or compatibility with es2022
 import type { BrowserType, LaunchOptions } from 'playwright';
+import { z } from 'zod';
 import type { StagehandOptions } from './stagehand-crawler';
 import { StagehandPlugin } from './stagehand-plugin';
 /**
@@ -54,32 +55,42 @@ export interface StagehandLaunchContext extends BrowserLaunchContext<LaunchOptio
  * @ignore
  */
 export declare class StagehandLauncher extends BrowserLauncher<StagehandPlugin> {
+    #private;
     readonly configuration: Configuration;
     protected static optionsShape: {
 // @ts-ignore optional peer dependency or compatibility with es2022
-        launcher: import("ow", { with: { "resolution-mode": "import" } }).ObjectPredicate<object> & import("ow", { with: { "resolution-mode": "import" } }).BasePredicate<object | undefined>;
+        launcher: z.ZodOptional<z.ZodCustom<import("@crawlee/types", { with: { "resolution-mode": "import" } }).Dictionary, import("@crawlee/types", { with: { "resolution-mode": "import" } }).Dictionary>>;
 // @ts-ignore optional peer dependency or compatibility with es2022
-        launchContextOptions: import("ow", { with: { "resolution-mode": "import" } }).ObjectPredicate<object> & import("ow", { with: { "resolution-mode": "import" } }).BasePredicate<object | undefined>;
+        launchContextOptions: z.ZodOptional<z.ZodCustom<import("@crawlee/types", { with: { "resolution-mode": "import" } }).Dictionary, import("@crawlee/types", { with: { "resolution-mode": "import" } }).Dictionary>>;
 // @ts-ignore optional peer dependency or compatibility with es2022
-        stagehandOptions: import("ow", { with: { "resolution-mode": "import" } }).ObjectPredicate<object> & import("ow", { with: { "resolution-mode": "import" } }).BasePredicate<object | undefined>;
+        stagehandOptions: z.ZodOptional<z.ZodCustom<import("@crawlee/types", { with: { "resolution-mode": "import" } }).Dictionary, import("@crawlee/types", { with: { "resolution-mode": "import" } }).Dictionary>>;
+        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>;
 // @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>;
+        launchOptions: z.ZodOptional<z.ZodCustom<import("@crawlee/types", { with: { "resolution-mode": "import" } }).Dictionary, import("@crawlee/types", { with: { "resolution-mode": "import" } }).Dictionary>>;
+        userAgent: z.ZodOptional<z.ZodString>;
+    };
+    protected static optionsSchema: z.ZodObject<{
 // @ts-ignore optional peer dependency or compatibility with es2022
-        ignoreProxyCertificate: import("ow").BooleanPredicate & import("ow").BasePredicate<boolean | undefined>;
+        launcher: z.ZodOptional<z.ZodCustom<import("@crawlee/types", { with: { "resolution-mode": "import" } }).Dictionary, import("@crawlee/types", { with: { "resolution-mode": "import" } }).Dictionary>>;
 // @ts-ignore optional peer dependency or compatibility with es2022
-        userDataDir: import("ow").StringPredicate & import("ow").BasePredicate<string | undefined>;
+        launchContextOptions: z.ZodOptional<z.ZodCustom<import("@crawlee/types", { with: { "resolution-mode": "import" } }).Dictionary, import("@crawlee/types", { with: { "resolution-mode": "import" } }).Dictionary>>;
 // @ts-ignore optional peer dependency or compatibility with es2022
-        launchOptions: import("ow").ObjectPredicate<object> & import("ow").BasePredicate<object | undefined>;
+        stagehandOptions: z.ZodOptional<z.ZodCustom<import("@crawlee/types", { with: { "resolution-mode": "import" } }).Dictionary, import("@crawlee/types", { with: { "resolution-mode": "import" } }).Dictionary>>;
+        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>;
 // @ts-ignore optional peer dependency or compatibility with es2022
-        userAgent: import("ow").StringPredicate & import("ow").BasePredicate<string | undefined>;
-    };
-    private readonly stagehandOptions;
+        launchOptions: z.ZodOptional<z.ZodCustom<import("@crawlee/types", { with: { "resolution-mode": "import" } }).Dictionary, import("@crawlee/types", { with: { "resolution-mode": "import" } }).Dictionary>>;
+        userAgent: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
     /**
      * All StagehandLauncher parameters are passed via the launchContext object.
      */

package/internals/stagehand-launcher.js

@@ -1,9 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.StagehandLauncher = void 0;
-const tslib_1 = require("tslib");
 const browser_1 = require("@crawlee/browser");
-const ow_1 = tslib_1.__importDefault(require("ow"));
+const zod_1 = require("zod");
 const stagehand_plugin_1 = require("./stagehand-plugin");
 /**
  * StagehandLauncher is based on BrowserLauncher and creates StagehandPlugin instances.
@@ -15,29 +14,31 @@ class StagehandLauncher extends browser_1.BrowserLauncher {
     configuration;
     static optionsShape = {
         ...browser_1.BrowserLauncher.optionsShape,
-        launcher: ow_1.default.optional.object,
-        launchContextOptions: ow_1.default.optional.object,
-        stagehandOptions: ow_1.default.optional.object,
+        // Passthrough schemas — the launcher module object must keep its prototype through parsing.
+        launcher: browser_1.schemas.anyObject.optional(),
+        launchContextOptions: browser_1.schemas.anyObject.optional(),
+        stagehandOptions: browser_1.schemas.anyObject.optional(),
     };
-    stagehandOptions;
+    static optionsSchema = zod_1.z.strictObject(StagehandLauncher.optionsShape);
+    #stagehandOptions;
     /**
      * All StagehandLauncher parameters are passed via the launchContext object.
      */
     constructor(launchContext = {}, configuration = browser_1.Configuration.getGlobalConfiguration()) {
-        (0, ow_1.default)(launchContext, 'StagehandLaunchContext', ow_1.default.object.exactShape(StagehandLauncher.optionsShape));
-        const { launcher = browser_1.BrowserLauncher.requireLauncherOrThrow('playwright', 'apify/actor-node-playwright-*').chromium, stagehandOptions = {}, } = launchContext;
-        const { launchOptions = {}, ...rest } = launchContext;
+        const parsedContext = (0, browser_1.parseArgument)(launchContext, StagehandLauncher.optionsSchema, 'StagehandLaunchContext');
+        const { launcher = browser_1.BrowserLauncher.requireLauncherOrThrow('playwright', 'apify/actor-node-playwright-*').chromium, stagehandOptions = {}, } = parsedContext;
+        const { launchOptions = {}, ...rest } = parsedContext;
         // Call super first before initializing properties
         super({
             ...rest,
             launchOptions: {
                 ...launchOptions,
-                executablePath: getDefaultExecutablePath(launchContext, configuration),
+                executablePath: getDefaultExecutablePath(parsedContext, configuration),
             },
             launcher,
         }, configuration);
         this.configuration = configuration;
-        this.stagehandOptions = {
+        this.#stagehandOptions = {
             env: 'LOCAL',
             model: 'openai/gpt-4.1-mini',
             ...stagehandOptions,
@@ -52,7 +53,7 @@ class StagehandLauncher extends browser_1.BrowserLauncher {
             ...this.otherLaunchContextProps,
             proxyUrl: this.proxyUrl,
             launchOptions: this.createLaunchOptions(),
-            stagehandOptions: this.stagehandOptions, // Set AFTER to override any unresolved options
+            stagehandOptions: this.#stagehandOptions, // Set AFTER to override any unresolved options
         });
     }
 }

package/internals/stagehand-plugin.d.ts

@@ -27,8 +27,8 @@ export interface StagehandPluginOptions extends BrowserPluginOptions<LaunchOptio
  * - Some fingerprinting options may not be fully applied (Stagehand controls browser launch)
  */
 export declare class StagehandPlugin extends BrowserPlugin<BrowserType, LaunchOptions, PlaywrightBrowser> {
+    #private;
     readonly stagehandOptions: StagehandOptions;
-    private readonly stagehandInstances;
     constructor(library: BrowserType, options?: StagehandPluginOptions);
     /**
      * Launches a browser using Stagehand and connects Playwright to it via CDP.
@@ -37,7 +37,7 @@ export declare class StagehandPlugin extends BrowserPlugin<BrowserType, LaunchOp
     /**
      * Cleans up Stagehand instance when browser disconnects.
      */
-    private _cleanupStagehand;
+    private cleanupStagehand;
     /**
      * Creates a controller for the Stagehand browser.
      */
@@ -45,15 +45,15 @@ export declare class StagehandPlugin extends BrowserPlugin<BrowserType, LaunchOp
     /**
      * Adds proxy configuration to launch options.
      */
-    protected _addProxyToLaunchOptions(launchContext: LaunchContext<BrowserType>): Promise<void>;
+    protected addProxyToLaunchOptions(launchContext: LaunchContext<BrowserType>): Promise<void>;
     /**
      * Determines if this is a Chromium-based browser.
      */
-    protected _isChromiumBasedBrowser(): boolean;
+    protected isChromiumBasedBrowser(): boolean;
     /**
      * Augments launch errors with helpful context.
      */
-    private _augmentLaunchError;
+    private augmentLaunchError;
     /**
      * Gets the Stagehand instance for a given browser.
      */

package/internals/stagehand-plugin.js

@@ -22,7 +22,7 @@ const stagehand_controller_1 = require("./stagehand-controller");
  */
 class StagehandPlugin extends browser_pool_1.BrowserPlugin {
     stagehandOptions;
-    stagehandInstances = new WeakMap();
+    #stagehandInstances = new WeakMap();
     constructor(library, options = {}) {
         super(library, options);
         this.stagehandOptions = options.stagehandOptions ?? {};
@@ -76,10 +76,10 @@ class StagehandPlugin extends browser_pool_1.BrowserPlugin {
             }
             const browser = await playwright_1.chromium.connectOverCDP(cdpUrl);
             // Store the Stagehand instance for AI operations
-            this.stagehandInstances.set(browser, stagehand);
+            this.#stagehandInstances.set(browser, stagehand);
             // Handle browser disconnection - cleanup both Stagehand and anonymized proxy
             browser.on('disconnected', async () => {
-                await this._cleanupStagehand(browser);
+                await this.cleanupStagehand(browser);
                 await closeAnonymizedProxy();
             });
             return browser;
@@ -88,7 +88,7 @@ class StagehandPlugin extends browser_pool_1.BrowserPlugin {
             // Clean up on failure
             await stagehand.close().catch(() => { });
             await closeAnonymizedProxy();
-            const augmentedError = this._augmentLaunchError(error, launchContext);
+            const augmentedError = this.augmentLaunchError(error, launchContext);
             core_1.serviceLocator.getLogger().error('Stagehand browser launch failed', { message: augmentedError.message });
             throw augmentedError;
         }
@@ -96,8 +96,8 @@ class StagehandPlugin extends browser_pool_1.BrowserPlugin {
     /**
      * Cleans up Stagehand instance when browser disconnects.
      */
-    async _cleanupStagehand(browser) {
-        const stagehand = this.stagehandInstances.get(browser);
+    async cleanupStagehand(browser) {
+        const stagehand = this.#stagehandInstances.get(browser);
         if (stagehand) {
             try {
                 await stagehand.close();
@@ -105,19 +105,19 @@ class StagehandPlugin extends browser_pool_1.BrowserPlugin {
             catch {
                 // Ignore cleanup errors
             }
-            this.stagehandInstances.delete(browser);
+            this.#stagehandInstances.delete(browser);
         }
     }
     /**
      * Creates a controller for the Stagehand browser.
      */
     createController() {
-        return new stagehand_controller_1.StagehandController(this, this.stagehandInstances);
+        return new stagehand_controller_1.StagehandController(this, this.#stagehandInstances);
     }
     /**
      * Adds proxy configuration to launch options.
      */
-    async _addProxyToLaunchOptions(launchContext) {
+    async addProxyToLaunchOptions(launchContext) {
         launchContext.launchOptions ??= {};
         const { launchOptions, proxyUrl } = launchContext;
         if (proxyUrl) {
@@ -132,14 +132,14 @@ class StagehandPlugin extends browser_pool_1.BrowserPlugin {
     /**
      * Determines if this is a Chromium-based browser.
      */
-    _isChromiumBasedBrowser() {
+    isChromiumBasedBrowser() {
         const name = this.library?.name?.();
         return name === 'chromium';
     }
     /**
      * Augments launch errors with helpful context.
      */
-    _augmentLaunchError(error, launchContext) {
+    augmentLaunchError(error, launchContext) {
         const message = error instanceof Error ? error.message : String(error);
         const model = this.stagehandOptions.model;
         let helpText = '';
@@ -163,7 +163,7 @@ class StagehandPlugin extends browser_pool_1.BrowserPlugin {
      * Gets the Stagehand instance for a given browser.
      */
     getStagehandForBrowser(browser) {
-        return this.stagehandInstances.get(browser);
+        return this.#stagehandInstances.get(browser);
     }
 }
 exports.StagehandPlugin = StagehandPlugin;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@crawlee/stagehand",
-    "version": "4.0.0-beta.99",
+    "version": "4.0.0-rc.0",
     "description": "AI-powered web crawling with Stagehand integration for Crawlee - enables natural language browser automation with act(), extract(), and observe() methods.",
     "engines": {
         "node": ">=22.0.0"
@@ -57,18 +57,17 @@
     },
     "dependencies": {
         "@apify/timeout": "^0.4.4",
-        "@crawlee/browser": "4.0.0-beta.99",
-        "@crawlee/browser-pool": "4.0.0-beta.99",
-        "@crawlee/core": "4.0.0-beta.99",
-        "@crawlee/types": "4.0.0-beta.99",
-        "@crawlee/utils": "4.0.0-beta.99",
-        "ow": "^2.0.0",
-        "tslib": "^2.8.1"
+        "@crawlee/browser": "4.0.0-rc.0",
+        "@crawlee/browser-pool": "4.0.0-rc.0",
+        "@crawlee/core": "4.0.0-rc.0",
+        "@crawlee/types": "4.0.0-rc.0",
+        "@crawlee/utils": "4.0.0-rc.0",
+        "tslib": "^2.8.1",
+        "zod": "^4.4.3"
     },
     "peerDependencies": {
         "@browserbasehq/stagehand": "^3.0.0",
-        "playwright": "*",
-        "zod": "^3.0.0 || ^4.0.0"
+        "playwright": "*"
     },
     "peerDependenciesMeta": {
         "@browserbasehq/stagehand": {
@@ -76,15 +75,11 @@
         },
         "playwright": {
             "optional": true
-        },
-        "zod": {
-            "optional": true
         }
     },
     "devDependencies": {
         "@browserbasehq/stagehand": "3.0.7",
-        "playwright": "^1.60.0",
-        "zod": "^4.3.5"
+        "playwright": "^1.60.0"
     },
     "lerna": {
         "command": {
@@ -93,5 +88,5 @@
             }
         }
     },
-    "gitHead": "ad2748380941842bb10cff100f4b4caad92049e3"
+    "gitHead": "79ab33dacdacb83e0197e6516d145f3aceef80c7"
 }