scrapely 1.2.26 → 1.2.28

package/dist/patch-browser-pool.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.PUPPETEER_NODE_ESM_SUFFIX = exports.PUPPETEER_NODE_ESM_URL_RE = exports.PUPPETEER_NODE_PATCH_GLOBAL = void 0;
 exports.setCdpUrl = setCdpUrl;
 exports.getCdpUrlForTests = getCdpUrlForTests;
 exports.resetBrowserProxyWarningsForTests = resetBrowserProxyWarningsForTests;
@@ -7,7 +8,11 @@ exports.applyProxyInfoToCdpUrl = applyProxyInfoToCdpUrl;
 exports.patchBrowserPoolModule = patchBrowserPoolModule;
 exports.patchCrawleeCrawlerModule = patchCrawleeCrawlerModule;
 exports.patchLoadedCrawleeCopies = patchLoadedCrawleeCopies;
+exports.patchBrowserLauncherModule = patchBrowserLauncherModule;
 exports.patchRawBrowserType = patchRawBrowserType;
+exports.patchPuppeteerNodeClass = patchPuppeteerNodeClass;
+exports.patchLoadedModules = patchLoadedModules;
+exports.esmPuppeteerInstalled = esmPuppeteerInstalled;
 /**
  * Redirects every browser launch (Crawlee browser pool, raw playwright /
  * puppeteer) to the Scrapely remote browser over CDP. The remote browser
@@ -19,6 +24,7 @@ exports.patchRawBrowserType = patchRawBrowserType;
 const browser_configuration_js_1 = require("./browser-configuration.js");
 const browser_locations_js_1 = require("./browser-locations.js");
 const cdp_retry_js_1 = require("./cdp-retry.js");
+const node_wrapper_js_1 = require("./node-wrapper.js");
 let _cdpUrl;
 /**
  * Lazily get CDP URL from environment or cached value.
@@ -485,52 +491,79 @@ function patchLoadedCrawleeCopies() {
         }
     }
 }
-try {
-    // Use Crawlee's ow (0.28.x CJS). Do not import top-level ow@1.x (ESM-only).
-    const owModule = require(require.resolve('ow', { paths: [require.resolve('@crawlee/browser')] }));
-    const ow = owModule.default ?? owModule;
-    // Playwright + Puppeteer plugins of the SDK's own @crawlee/browser-pool copy.
-    // Actor-local copies are patched by the Module._load hook further down.
-    try {
-        patchBrowserPoolModule(require('@crawlee/browser-pool'));
-    }
-    catch {
-        // @crawlee/browser-pool not installed — skip plugin patches
-    }
-    try {
-        const launcherPath = require.resolve('@crawlee/playwright').replace(/[/\\][^/\\]+$/, '') +
-            '/internals/playwright-launcher.js';
-        const { PlaywrightLauncher } = require(launcherPath);
-        PlaywrightLauncher.optionsShape.cdpUrl = ow.optional.string;
-    }
-    catch {
-        // @crawlee/playwright not installed — skip Playwright patches
-    }
-    try {
-        const puppeteerLauncherPath = require.resolve('@crawlee/puppeteer').replace(/[/\\][^/\\]+$/, '') +
-            '/internals/puppeteer-launcher.js';
-        const { PuppeteerLauncher } = require(puppeteerLauncherPath);
-        PuppeteerLauncher.optionsShape.cdpUrl = ow.optional.string;
+// ─── Crawlee launchers: `cdpUrl` option + gVisor-safe local launch args ─────
+//
+// Applied when a launcher module loads (Module._load hook below), never by
+// importing Crawlee up front: loading @crawlee/browser-pool and playwright
+// eagerly cost ~2.4 s per Node process under gVisor.
+/** Requests that load a Crawlee launcher file (`require('./internals/browser-launcher')`). */
+const LAUNCHER_REQUEST_RE = /(^|[/\\])internals[/\\](browser|playwright|puppeteer)-launcher(\.js)?$/;
+/** Cached module filenames of Crawlee launcher files (any copy). */
+const LAUNCHER_FILENAME_RE = /[/\\]@crawlee[/\\](browser|playwright|puppeteer)[/\\]internals[/\\](browser|playwright|puppeteer)-launcher\.js$/;
+/**
+ * An `ow.optional.string` predicate from the same ow copy as the launcher's
+ * own shape (a predicate from another ow copy is not recognized by
+ * exactShape). Reuses an existing optional-string entry, else loads ow next
+ * to the module that required the launcher.
+ */
+function optionalStringPredicate(shape, parentFilename) {
+    if (shape.userAgent)
+        return shape.userAgent;
+    if (shape.userDataDir)
+        return shape.userDataDir;
+    if (!parentFilename)
+        return undefined;
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const { createRequire } = require('module');
+    const owModule = createRequire(parentFilename)('ow');
+    return (owModule.default ?? owModule).optional.string;
+}
+function addCdpUrlOption(Launcher, parentFilename) {
+    const shape = Launcher?.optionsShape;
+    if (!shape || typeof shape !== 'object' || 'cdpUrl' in shape)
+        return;
+    const predicate = optionalStringPredicate(shape, parentFilename);
+    if (predicate)
+        shape.cdpUrl = predicate;
+}
+/**
+ * Patch the launcher classes exported by one loaded Crawlee launcher file (or
+ * package index). Idempotent.
+ *
+ * - `cdpUrl` becomes a valid launcher option (PlaywrightLauncher and
+ *   PuppeteerLauncher copy BrowserLauncher's shape when their file loads, so
+ *   each class gets it; browser-launcher.js loads first, so the copies inherit it).
+ * - Local launches get gVisor-safe Chrome args under runsc. Playwright/Puppeteer
+ *   pool launches use CDP and skip this.
+ *
+ * @internal Exported for tests.
+ */
+function patchBrowserLauncherModule(mod, parentFilename) {
+    if (!mod || (typeof mod !== 'object' && typeof mod !== 'function'))
+        return;
+    for (const key of ['BrowserLauncher', 'PlaywrightLauncher', 'PuppeteerLauncher']) {
+        let Launcher;
+        try {
+            Launcher = mod[key];
+        }
+        catch {
+            continue;
+        }
+        if (typeof Launcher !== 'function')
+            continue;
+        addCdpUrlOption(Launcher, parentFilename);
     }
-    catch {
-        // @crawlee/puppeteer not installed — plugin patch above is enough
-    }
-    // Patch @crawlee/browser BrowserLauncher when available
-    const browserPkg = require.resolve('@crawlee/browser');
-    const browserLauncherPath = browserPkg.replace(/[/\\][^/\\]+$/, '') + '/internals/browser-launcher.js';
-    const { BrowserLauncher } = require(browserLauncherPath);
-    BrowserLauncher.optionsShape.cdpUrl = ow.optional.string;
-    // Patch createLaunchOptions to inject gVisor-safe Chrome args for any residual
-    // local launch path. Playwright/Puppeteer pool launches use CDP and skip this.
-    // Only applies when SCRAPELY_CONTAINER_RUNTIME=runsc (gVisor sandbox).
-    const origCreateLaunchOptions = BrowserLauncher.prototype.createLaunchOptions;
-    BrowserLauncher.prototype.createLaunchOptions = function () {
-        const launchOptions = origCreateLaunchOptions.call(this);
-        // Inject crashpad-disabling args when running under gVisor
-        // gVisor doesn't support Chrome's crashpad_handler process
-        // Also needed with ReadonlyRootfs + tmpfs /tmp where /tmp/.X11-unix
-        // and crashpad database dir don't persist from the base image.
-        if (process.env.SCRAPELY_CONTAINER_RUNTIME === 'runsc') {
+    const BrowserLauncher = mod.BrowserLauncher;
+    const proto = BrowserLauncher?.prototype;
+    if (!proto || typeof proto.createLaunchOptions !== 'function' || proto._scrapelyGVisorArgsPatched)
+        return;
+    const origCreateLaunchOptions = proto.createLaunchOptions;
+    proto.createLaunchOptions = function (...args) {
+        const launchOptions = origCreateLaunchOptions.apply(this, args);
+        // gVisor doesn't support Chrome's crashpad_handler process. Also needed
+        // with ReadonlyRootfs + tmpfs /tmp where /tmp/.X11-unix and the crashpad
+        // database dir don't persist from the base image.
+        if (process.env.SCRAPELY_CONTAINER_RUNTIME === 'runsc' && launchOptions) {
             launchOptions.args = launchOptions.args || [];
             for (const arg of GVISOR_CHROME_ARGS) {
                 if (!launchOptions.args.includes(arg)) {
@@ -540,9 +573,7 @@ try {
         }
         return launchOptions;
     };
-}
-catch {
-    // @crawlee/browser not installed — skip browser pool patches (e.g. cheerio-only actors)
+    proto._scrapelyGVisorArgsPatched = true;
 }
 /**
  * Split our `browserConfiguration` option off raw launch options. The options
@@ -681,72 +712,87 @@ function patchRawPlaywrightModule(pw) {
     }
 }
 /**
- * Patch a raw puppeteer launcher: the default export (also exposed as module
- * props). Both the full puppeteer package and puppeteer-core ship the same
- * launcher shape (launch/connect) — patch whichever was loaded.
+ * The patched puppeteer `launch`: remote CDP connect on the platform, the
+ * original local launch otherwise. `connect` is the launcher's (retry-wrapped)
+ * connect; `origLaunch` the unpatched launch, both called with `self`.
+ */
+async function puppeteerLaunchPatched(self, origLaunch, moduleName, launchOptions = {}) {
+    const { options, browserConfiguration } = takeBrowserConfiguration(launchOptions);
+    if (browserPatchDisabled())
+        return origLaunch.call(self, withGVisorArgs(options));
+    const cdpUrl = rawLaunchCdpUrl(options, browserConfiguration);
+    if (!cdpUrl) {
+        if (!isAtHome())
+            return origLaunch.call(self, options);
+        throw new Error('cdpUrl is required. Local browser launch is disabled — all runs must use the remote browser.');
+    }
+    const dropped = Object.keys(options).filter((k) => k !== 'timeout' && k !== 'slowMo' && k !== 'protocol');
+    if (dropped.length > 0) {
+        console.warn(`[scrapely] ${moduleName}.launch redirected to the remote CDP browser; ` +
+            `local launch options ignored: ${dropped.join(', ')}.`);
+    }
+    return self.connect({ browserWSEndpoint: cdpUrl, ...rawConnectOptions(options) });
+}
+/**
+ * Patch puppeteer's PuppeteerNode class (puppeteer-core `node/PuppeteerNode.js`,
+ * shared by puppeteer and puppeteer-core, CJS and ESM builds). The package
+ * entry creates its default instance right after this class loads, and the
+ * constructor binds `launch`/`connect` from the prototype, so patching the
+ * prototype first also covers the named exports (`import { launch } from
+ * 'puppeteer'`), which are those bound methods. Idempotent per class.
+ *
+ * @internal Exported for tests.
+ */
+function patchPuppeteerNodeClass(PuppeteerNode) {
+    const proto = PuppeteerNode?.prototype;
+    if (!proto || typeof proto.launch !== 'function')
+        return;
+    if (Object.prototype.hasOwnProperty.call(proto, '_scrapelyRawCdpPatched'))
+        return;
+    (0, cdp_retry_js_1.wrapConnectWithRetry)(proto, 'connect', getCdpUrl);
+    const origLaunch = proto.launch;
+    proto.launch = function rawPuppeteerLaunchPatched(launchOptions) {
+        const moduleName = this?._isPuppeteerCore === false ? 'puppeteer' : 'puppeteer-core';
+        return puppeteerLaunchPatched(this, origLaunch, moduleName, launchOptions);
+    };
+    proto._scrapelyRawCdpPatched = true;
+}
+/**
+ * Patch a raw puppeteer launcher instance: the default export (also exposed as
+ * module props). Covers puppeteer copies whose instance already exists (loaded
+ * before this module) or whose class could not be patched first. Skipped when
+ * the instance's class is already patched.
  */
 function patchRawPuppeteerModule(mod, moduleName) {
     const launcher = mod?.default ?? mod;
     if (typeof launcher?.launch !== 'function' || launcher._scrapelyRawCdpPatched) {
         return;
     }
+    const origBoundLaunch = launcher.launch;
+    const origBoundConnect = launcher.connect;
     (0, cdp_retry_js_1.wrapConnectWithRetry)(launcher, 'connect', getCdpUrl);
     const origLaunch = launcher.launch.bind(launcher);
     launcher.launch = async function rawPuppeteerLaunchPatched(launchOptions = {}) {
-        const { options, browserConfiguration } = takeBrowserConfiguration(launchOptions);
-        if (browserPatchDisabled())
-            return origLaunch(withGVisorArgs(options));
-        const cdpUrl = rawLaunchCdpUrl(options, browserConfiguration);
-        if (!cdpUrl) {
-            if (!isAtHome())
-                return origLaunch(options);
-            throw new Error('cdpUrl is required. Local browser launch is disabled — all runs must use the remote browser.');
-        }
-        const dropped = Object.keys(options).filter((k) => k !== 'timeout' && k !== 'slowMo' && k !== 'protocol');
-        if (dropped.length > 0) {
-            console.warn(`[scrapely] ${moduleName}.launch redirected to the remote CDP browser; ` +
-                `local launch options ignored: ${dropped.join(', ')}.`);
-        }
-        return launcher.connect({ browserWSEndpoint: cdpUrl, ...rawConnectOptions(options) });
+        return puppeteerLaunchPatched(launcher, origLaunch, moduleName, launchOptions);
     };
     launcher._scrapelyRawCdpPatched = true;
-}
-/**
- * Eager pass: patch whatever playwright/puppeteer is resolvable from this
- * module's own dependency tree right now (the SDK tree under
- * /opt/scrapely/node_modules in the base image). Actor-local installs are
- * covered by the Module._load hook below — a bare require() from this file
- * can never resolve them.
- */
-function patchSdkTreeRawModules() {
-    for (const pwModuleName of ['playwright', 'playwright-core']) {
-        try {
-            // eslint-disable-next-line @typescript-eslint/no-var-requires
-            patchRawPlaywrightModule(require(pwModuleName));
-        }
-        catch {
-            // not installed in the SDK tree — actor-local copies still get the hook
-        }
-    }
-    // Raw puppeteer API: default export launcher (also exposed as module props).
-    // Both the full puppeteer package and puppeteer-core ship the same launcher
-    // shape (launch/connect) — patch whichever is installed.
-    for (const puppeteerModuleName of ['puppeteer', 'puppeteer-core']) {
-        try {
-            // eslint-disable-next-line @typescript-eslint/no-var-requires
-            patchRawPuppeteerModule(require(puppeteerModuleName), puppeteerModuleName);
-        }
-        catch {
-            // not installed in the SDK tree — actor-local copies still get the hook
+    // Named exports (`exports.launch = puppeteer.launch`) hold the original
+    // bound methods; point them at the patched ones.
+    if (mod && mod !== launcher) {
+        for (const [key, original] of [
+            ['launch', origBoundLaunch],
+            ['connect', origBoundConnect],
+        ]) {
+            try {
+                if (mod[key] === original && mod[key] !== launcher[key])
+                    mod[key] = launcher[key];
+            }
+            catch {
+                // read-only export binding — the default export is still patched
+            }
         }
     }
 }
-/**
- * Apply the raw patches to a module coming back from the hooked loader.
- * `request` is the specifier as written by the caller, `loaded` is whatever
- * instance it actually resolved to, and `loadRoot` resolves a package root
- * through the original loader (no hook recursion) for subpath requests.
- */
 /**
  * Requests that load (a part of) some copy of @crawlee/browser-pool:
  * - the bare package name (require from @crawlee/playwright etc.),
@@ -754,7 +800,22 @@ function patchSdkTreeRawModules() {
  * - the relative plugin files the package's own index.js requires.
  */
 const BROWSER_POOL_REQUEST_RE = /^@crawlee\/browser-pool$|[/\\]@crawlee[/\\]browser-pool[/\\]index\.js$|(^|[/\\])(playwright|puppeteer)-plugin(\.js)?$/;
-function patchLoadedRawModule(request, loaded, loadRoot) {
+/** Cached module filenames of @crawlee/browser-pool (index or plugin files, any copy). */
+const BROWSER_POOL_FILENAME_RE = /[/\\]@crawlee[/\\]browser-pool[/\\](index|playwright[/\\]playwright-plugin|puppeteer[/\\]puppeteer-plugin)\.js$/;
+/** playwright / playwright-core package entry, by filename (ESM imports and require.cache). */
+const PLAYWRIGHT_ENTRY_FILENAME_RE = /[/\\]node_modules[/\\](playwright|playwright-core)[/\\]index\.js$/;
+/** puppeteer / puppeteer-core CJS package entry (default instance), by filename. */
+const PUPPETEER_ENTRY_FILENAME_RE = /[/\\]node_modules[/\\](puppeteer|puppeteer-core)[/\\]lib[/\\]cjs[/\\]puppeteer[/\\](puppeteer|puppeteer-core)\.js$/;
+/** puppeteer-core's PuppeteerNode class file (CJS), as requested by node/node.js or cached. */
+const PUPPETEER_NODE_REQUEST_RE = /(^|[/\\])PuppeteerNode(\.js)?$/;
+/**
+ * Apply the patches to a module coming back from the hooked loader.
+ * `request` is the specifier as written by the caller (an absolute filename
+ * when ESM imports a CJS package), `loaded` is whatever instance it actually
+ * resolved to, and `loadRoot` resolves a package root through the original
+ * loader (no hook recursion) for subpath requests.
+ */
+function patchLoadedRawModule(request, loaded, loadRoot, parentFilename) {
     if (typeof request !== 'string')
         return;
     // Crawlee browser pool — the actor's own copy (e.g. /usr/src/app/node_modules)
@@ -763,18 +824,31 @@ function patchLoadedRawModule(request, loaded, loadRoot) {
         patchBrowserPoolModule(loaded);
         return;
     }
+    if (LAUNCHER_REQUEST_RE.test(request)) {
+        patchBrowserLauncherModule(loaded, parentFilename);
+        return;
+    }
     if (CRAWLER_REQUEST_RE.test(request)) {
         patchCrawleeCrawlerModule(loaded);
         return;
     }
-    if (request === 'playwright' || request === 'playwright-core') {
+    if (request === 'playwright' || request === 'playwright-core' || PLAYWRIGHT_ENTRY_FILENAME_RE.test(request)) {
         patchRawPlaywrightModule(loaded);
         return;
     }
+    if (PUPPETEER_NODE_REQUEST_RE.test(request)) {
+        patchPuppeteerNodeClass(loaded?.PuppeteerNode);
+        return;
+    }
     if (request === 'puppeteer' || request === 'puppeteer-core') {
         patchRawPuppeteerModule(loaded, request);
         return;
     }
+    const puppeteerEntry = PUPPETEER_ENTRY_FILENAME_RE.exec(request);
+    if (puppeteerEntry) {
+        patchRawPuppeteerModule(loaded, puppeteerEntry[1]);
+        return;
+    }
     // BrowserType subpath loads, e.g. require('playwright/chromium') — the
     // export is the BrowserType itself, not the package root. Resolve the root
     // for its chromium (the connectOverCDP anchor), patch the root, then the
@@ -796,15 +870,48 @@ function patchLoadedRawModule(request, loaded, loadRoot) {
     }
 }
 /**
- * Hook the CommonJS loader so the raw patches reach actor-local installs.
+ * `require('puppeteer')` of an ESM-only puppeteer (v25+) on Node without
+ * module.registerHooks (Node 20, 22.0-22.14): require(esm) bypasses both
+ * Module._load for its inner modules and the off-thread ESM hook, and the
+ * returned namespace is frozen, so the named `launch` export would keep the
+ * original. Load and patch the PuppeteerNode class first (same ESM module
+ * instance the entry imports), so the entry's default instance binds the
+ * patched methods. Older CJS builds are covered by the regular hook anyway.
+ */
+const puppeteerEntriesPreloaded = new Set();
+function preloadPuppeteerNodeClass(request, parent, origLoad) {
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const Module = require('module');
+    if (typeof Module.registerHooks === 'function')
+        return;
+    const parentDir = typeof parent?.path === 'string' ? parent.path : '';
+    const key = `${parentDir}\0${request}`;
+    if (puppeteerEntriesPreloaded.has(key))
+        return;
+    puppeteerEntriesPreloaded.add(key);
+    try {
+        // puppeteer's own puppeteer-core (may be nested under puppeteer).
+        const entry = Module._resolveFilename(request, parent, false);
+        const coreRequest = 'puppeteer-core/internal/node/PuppeteerNode.js';
+        const corePath = Module.createRequire(entry).resolve(coreRequest);
+        if (!/[/\\]lib[/\\]puppeteer[/\\]node[/\\]PuppeteerNode\.js$/.test(corePath))
+            return;
+        patchPuppeteerNodeClass(origLoad(corePath, parent, false)?.PuppeteerNode);
+    }
+    catch {
+        // not installed / different layout: the regular patches still apply
+    }
+}
+/**
+ * Hook the CommonJS loader so the patches reach every copy of the browser
+ * libraries and Crawlee, whenever they load.
  *
- * The eager pass above can only see this module's own dependency tree; an
- * actor bundling playwright/puppeteer in its workdir resolves a different,
- * unpatched instance. Module._load is the chokepoint every require() passes
- * through AFTER resolution — including CJS packages imported from ESM, which
- * Node funnels through the CJS loader — so patching here covers whichever
- * copy (SDK tree or actor workdir) the request actually resolved to. Chained
- * onto the current _load (composes with tsx's hook in dev) and idempotent.
+ * Module._load is the chokepoint every require() passes through AFTER
+ * resolution — including CJS packages imported from ESM, which Node funnels
+ * through the CJS loader with the resolved filename — so patching here covers
+ * whichever copy (SDK tree or actor workdir) the request actually resolved to.
+ * Chained onto the current _load (composes with tsx's hook in dev) and
+ * idempotent.
  */
 function installRawModuleLoadHook() {
     // eslint-disable-next-line @typescript-eslint/no-var-requires
@@ -813,9 +920,12 @@ function installRawModuleLoadHook() {
     if (typeof origLoad !== 'function' || origLoad._scrapelyRawCdpHook)
         return;
     const hookedLoad = function (request, parent, isMain) {
+        if (request === 'puppeteer' || request === 'puppeteer-core') {
+            preloadPuppeteerNodeClass(request, parent, origLoad);
+        }
         const loaded = origLoad.apply(this, [request, parent, isMain]);
         try {
-            patchLoadedRawModule(request, loaded, (name) => origLoad(name, parent, isMain));
+            patchLoadedRawModule(request, loaded, (name) => origLoad(name, parent, isMain), typeof parent?.filename === 'string' ? parent.filename : undefined);
         }
         catch (err) {
             // Never break the actor's module loading — warn and hand back the
@@ -827,9 +937,134 @@ function installRawModuleLoadHook() {
     hookedLoad._scrapelyRawCdpHook = true;
     Module._load = hookedLoad;
 }
+/**
+ * Patch copies that loaded before this module (e.g. a local run that imports
+ * crawlee or playwright before scrapely). Copies loaded later are patched by
+ * the loader hooks.
+ *
+ * @internal Exported for tests.
+ */
+function patchLoadedModules() {
+    const cache = require.cache ?? {};
+    for (const [filename, cached] of Object.entries(cache)) {
+        const mod = cached?.exports;
+        if (!mod || !cached?.loaded)
+            continue;
+        try {
+            if (CRAWLER_FILENAME_RE.test(filename))
+                patchCrawleeCrawlerModule(mod);
+            if (BROWSER_POOL_FILENAME_RE.test(filename))
+                patchBrowserPoolModule(mod);
+            if (LAUNCHER_FILENAME_RE.test(filename))
+                patchBrowserLauncherModule(mod, filename);
+            if (PLAYWRIGHT_ENTRY_FILENAME_RE.test(filename))
+                patchRawPlaywrightModule(mod);
+            const puppeteerEntry = PUPPETEER_ENTRY_FILENAME_RE.exec(filename);
+            // Existing instance first: once its class is patched, the instance
+            // reads as patched but still holds the original bound methods.
+            if (puppeteerEntry)
+                patchRawPuppeteerModule(mod, puppeteerEntry[1]);
+        }
+        catch (err) {
+            console.warn(`[scrapely] CDP patch failed for '${filename}':`, err?.message);
+        }
+    }
+    for (const [filename, cached] of Object.entries(cache)) {
+        if (cached?.loaded && /[/\\]lib[/\\]cjs[/\\]puppeteer[/\\]node[/\\]PuppeteerNode\.js$/.test(filename)) {
+            patchPuppeteerNodeClass(cached.exports?.PuppeteerNode);
+        }
+    }
+}
+// ─── Pure-ESM puppeteer ─────────────────────────────────────────────────────
+//
+// `import puppeteer from 'puppeteer'` loads puppeteer's ESM build, which never
+// passes through Module._load. A module load hook appends one call to
+// PuppeteerNode.js that hands the class to patchPuppeteerNodeClass (through a
+// global, so it also works from Node 20's off-thread loader). The hook is only
+// registered when puppeteer is installed where ESM code can import it (ESM
+// resolution ignores NODE_PATH), so other actors pay nothing.
+/** @internal Global the ESM load hook's appended code calls. */
+exports.PUPPETEER_NODE_PATCH_GLOBAL = 'scrapely.patchPuppeteerNodeClass';
+/** puppeteer-core's ESM PuppeteerNode.js (URL): lib/esm/puppeteer/... up to v24, lib/puppeteer/... (ESM only) from v25. */
+exports.PUPPETEER_NODE_ESM_URL_RE = /\/puppeteer-core\/lib\/(esm\/)?puppeteer\/node\/PuppeteerNode\.js$/;
+/** Appended to the ESM PuppeteerNode.js source; runs right after the class is defined. */
+exports.PUPPETEER_NODE_ESM_SUFFIX = `\n;globalThis[Symbol.for(${JSON.stringify(exports.PUPPETEER_NODE_PATCH_GLOBAL)})]?.(PuppeteerNode);\n`;
+/** Directories ESM code in this process resolves bare imports from: cwd and the main script's ancestors. */
+function esmLookupDirs() {
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const path = require('path');
+    const starts = [process.cwd()];
+    if (process.argv[1])
+        starts.push(path.dirname(path.resolve(process.argv[1])));
+    const dirs = new Set();
+    for (const start of starts) {
+        let dir = start;
+        for (;;) {
+            dirs.add(dir);
+            const parent = path.dirname(dir);
+            if (parent === dir)
+                break;
+            dir = parent;
+        }
+    }
+    return [...dirs];
+}
+/** @internal Whether an ESM import of puppeteer / puppeteer-core could succeed in this process. */
+function esmPuppeteerInstalled() {
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const fs = require('fs');
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const path = require('path');
+    for (const dir of esmLookupDirs()) {
+        for (const name of ['puppeteer-core', 'puppeteer']) {
+            if (fs.existsSync(path.join(dir, 'node_modules', name, 'package.json')))
+                return true;
+        }
+    }
+    return false;
+}
+function installEsmPuppeteerHook() {
+    globalThis[Symbol.for(exports.PUPPETEER_NODE_PATCH_GLOBAL)] = patchPuppeteerNodeClass;
+    if (process.env.SCRAPELY_ESM_PUPPETEER_HOOK === '0' || !esmPuppeteerInstalled())
+        return;
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const Module = require('module');
+    if (Module._scrapelyEsmPuppeteerHook)
+        return;
+    Module._scrapelyEsmPuppeteerHook = true;
+    try {
+        if (typeof Module.registerHooks === 'function') {
+            // Node 22.15+ / 23.5+: synchronous, in-thread.
+            Module.registerHooks({
+                load(url, context, nextLoad) {
+                    const result = nextLoad(url, context);
+                    if (result?.format === 'module' && result.source != null && exports.PUPPETEER_NODE_ESM_URL_RE.test(url)) {
+                        const source = typeof result.source === 'string' ? result.source : new TextDecoder().decode(result.source);
+                        return { ...result, source: source + exports.PUPPETEER_NODE_ESM_SUFFIX };
+                    }
+                    return result;
+                },
+            });
+        }
+        else if (typeof Module.register === 'function') {
+            // Node 20.6+ / 22.0-22.14: off-thread loader (esm-loader-hooks.mjs).
+            // eslint-disable-next-line @typescript-eslint/no-var-requires
+            const { pathToFileURL } = require('url');
+            Module.register('./esm-loader-hooks.mjs', pathToFileURL(__filename));
+        }
+    }
+    catch (err) {
+        console.warn('[scrapely] ESM puppeteer hook unavailable:', err?.message);
+    }
+}
 function applyRawBrowserPatches() {
-    patchSdkTreeRawModules();
     installRawModuleLoadHook();
-    patchLoadedCrawleeCopies();
+    installEsmPuppeteerHook();
+    patchLoadedModules();
+}
+// Package-manager processes (npm/npx/yarn/pnpm) only spawn the actor; they
+// never run actor code, so they get no hooks. `npm start` whose script is a
+// plain `node <file>` runs that node process directly (see node-wrapper.ts).
+if (!(0, node_wrapper_js_1.handlePackageManagerProcess)()) {
+    applyRawBrowserPatches();
 }
-applyRawBrowserPatches();

package/dist/proxy-configuration.js

@@ -27,7 +27,7 @@ function getPlatformProxyEnv() {
     };
 }
 const BYOP_WARNING = '[Scrapely] No proxy configured. Scrapely injects platform proxy credentials (APIFY_PROXY_*/SCRAPELY_PROXY_*) into runs when your account has proxy access. ' +
-    'Locally, either add proxyUrls to your actor input, or copy your proxy credentials from the Scrapely console (Proxy page) into the ' +
+    'Locally, either add proxyUrls to your actor input, or copy your proxy credentials from the Scrapely dashboard (Proxy page) into the ' +
     'SCRAPELY_PROXY_HOSTNAME, SCRAPELY_PROXY_PORT, SCRAPELY_PROXY_USERNAME and SCRAPELY_PROXY_PASSWORD environment variables. ' +
     'Using the platform proxy from outside Scrapely requires an active plan or a prepaid (PAYG) balance of at least $1; ' +
     'free accounts get run-scoped credentials injected into their on-platform runs only.';

package/package.json

@@ -1,9 +1,22 @@
 {
     "name": "scrapely",
-    "version": "1.2.26",
+    "version": "1.2.28",
     "description": "Scrapely SDK for building JavaScript and TypeScript Actors",
     "main": "dist/index.js",
     "types": "dist/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.mjs",
+            "require": "./dist/index.js",
+            "default": "./dist/index.js"
+        },
+        "./package.json": "./package.json",
+        "./dist/*.js": "./dist/*.js",
+        "./dist/*.mjs": "./dist/*.mjs",
+        "./dist/*": "./dist/*.js",
+        "./*": "./*"
+    },
     "files": [
         "dist",
         "LICENSE",
@@ -48,7 +61,8 @@
         "test:cdp-retry": "npx tsx --test tests/cdp-retry.test.ts",
         "test:proxy-input-aliases": "npx tsx --test tests/proxy-input-aliases.test.ts",
         "test:charge-retries": "npx tsx --test tests/charge-retries.test.ts",
-        "test:solver": "npx tsx --test tests/solver.test.ts"
+        "test:solver": "npx tsx --test tests/solver.test.ts",
+        "test:lazy-preload": "npx tsx --test tests/lazy-preload.test.ts"
     },
     "author": "SandeepDev1",
     "license": "ISC AND Apache-2.0",