jumpy-lion 0.1.6-beta.7 → 1.0.0-beta.0

package/dist/browser-plugin.js

@@ -1,13 +1,39 @@
-import net from 'net';
+import { promises as fs } from 'fs';
+import os from 'os';
+import path from 'path';
+import CDP from 'chrome-remote-interface';
 import { BrowserPlugin, log } from 'crawlee';
 import CDPBrowserController from './browser-controller.js';
 import { launchChromeBrowserWithNewProfile } from './browser-process/browser.js';
-import { generateFingerprintConfig } from './browser-process/anti-detect-config.js';
-import { getChromeBinaryVersion, getAntiDetectBrowserPath, resolveAntiDetectBrowserPath } from './browser-process/get-chrome-executable.js';
-import { generateNonApifyFingerprint } from './fingerprinting/non-apify-fingerprint-generator.js';
+import { prepareForLaunch } from './browser-process/fingerprint-config.js';
+import { resolveAntiDetectBrowserPath } from './browser-process/get-chrome-executable.js';
+import { PortAllocator } from './browser-process/port-allocator.js';
+import { ensureWidevineCdm } from './browser-process/widevine-cdm.js';
 import { fetchProxyCountry, resolveLocale } from './fingerprinting/locale-resolver.js';
-import { CdpLauncher } from './launcher-wrap.js';
 import { anonymizeProxySugar } from './proxy/anonymize-proxy.js';
+import { untarUserDataDir } from './session/tar-data-dir.js';
+import { assertValidBundle } from './session/types.js';
+import { resolveUseNativeStealth } from './session-profile.js';
+/**
+ * Type-only marker satisfying Crawlee's BrowserPlugin generic. CDP has no
+ * Puppeteer-style library object - the connection happens directly in
+ * CDPBrowserPlugin._openCdpConnection, so `launch` is never invoked at runtime;
+ * the declaration exists purely so Crawlee can infer LibraryOptions /
+ * LaunchResult from the generic. Constructable (`new CdpLauncher()`) because the
+ * Crawler and the e2e harness pass an instance to the plugin constructor; the
+ * body is intentionally empty rather than the former throw-only stub.
+ */
+export class CdpLauncher {
+}
+/**
+ * Overall budget for the browser to print its "DevTools listening on ws://…"
+ * line and become connectable. Covers a slow cold start (first launch of the
+ * anti-detect binary, cold page cache) while still failing in bounded time if
+ * the process is wedged without having exited. The process-exit rejection is
+ * handled separately by the endpoint promise itself, so this only fires for a
+ * genuine hang.
+ */
+const CDP_READINESS_TIMEOUT_MS = 30000;
 class CDPBrowserPlugin extends BrowserPlugin {
     /**
      * Accept flat LaunchBrowserOptions directly (not nested inside BrowserPluginOptions).
@@ -17,117 +43,20 @@ class CDPBrowserPlugin extends BrowserPlugin {
      */
     constructor(library, launchOptions) {
         super(library, { launchOptions: (launchOptions ?? {}) });
-    }
-    async getNextAvailablePort() {
-        const maxAttempts = CDPBrowserPlugin.PORT_RANGE.max - CDPBrowserPlugin.PORT_RANGE.min + 1; // Try all ports in range
-        let attempts = 0;
-        while (attempts < maxAttempts) {
-            // Wait if another instance is currently assigning a port
-            while (CDPBrowserPlugin.portLock) {
-                await new Promise(resolve => setTimeout(resolve, 100 + Math.random() * 100));
-            }
-            try {
-                // Set lock before port assignment
-                CDPBrowserPlugin.portLock = true;
-                // Increment the last assigned port, wrapping around if necessary
-                CDPBrowserPlugin.lastAssignedPort++;
-                if (CDPBrowserPlugin.lastAssignedPort > CDPBrowserPlugin.PORT_RANGE.max) {
-                    CDPBrowserPlugin.lastAssignedPort = CDPBrowserPlugin.PORT_RANGE.min;
-                    log.debug('Port range wrapped around, starting from beginning');
-                }
-                const candidatePort = CDPBrowserPlugin.lastAssignedPort;
-                // Skip if port is already tracked as in use
-                if (CDPBrowserPlugin.usedPorts.has(candidatePort)) {
-                    attempts++;
-                    continue;
-                }
-                // Check if port is actually available
-                if (await this._isPortAvailable(candidatePort)) {
-                    CDPBrowserPlugin.usedPorts.add(candidatePort);
-                    log.debug(`Reserved port ${candidatePort} for browser instance (attempt ${attempts + 1})`);
-                    return candidatePort;
-                }
-                // Port is not available, mark it as used temporarily to avoid immediate retry
-                CDPBrowserPlugin.usedPorts.add(candidatePort);
-                setTimeout(() => {
-                    CDPBrowserPlugin.usedPorts.delete(candidatePort);
-                }, 5000); // Remove from used ports after 5 seconds
-            }
-            finally {
-                // Always release the lock
-                CDPBrowserPlugin.portLock = false;
-            }
-            attempts++;
-        }
-        // If we've tried all ports and none are available, try to clean up stale ports
-        log.warning(`All ports in range ${CDPBrowserPlugin.PORT_RANGE.min}-${CDPBrowserPlugin.PORT_RANGE.max} are in use. Attempting cleanup.`);
-        await this._cleanupStalePorts();
-        // Try once more after cleanup
-        for (let port = CDPBrowserPlugin.PORT_RANGE.min; port <= CDPBrowserPlugin.PORT_RANGE.max; port++) {
-            if (!CDPBrowserPlugin.usedPorts.has(port) && await this._isPortAvailable(port)) {
-                CDPBrowserPlugin.usedPorts.add(port);
-                log.debug(`Reserved port ${port} after cleanup`);
-                return port;
-            }
-        }
-        throw new Error(`No available ports found in the configured range ${CDPBrowserPlugin.PORT_RANGE.min}-${CDPBrowserPlugin.PORT_RANGE.max} after maximum attempts and cleanup`);
-    }
-    async _cleanupStalePorts() {
-        log.debug('Cleaning up stale ports');
-        const portsToCheck = Array.from(CDPBrowserPlugin.usedPorts);
-        for (const port of portsToCheck) {
-            if (await this._isPortAvailable(port)) {
-                CDPBrowserPlugin.usedPorts.delete(port);
-                log.debug(`Cleaned up stale port ${port}`);
-            }
-        }
-    }
-    async _isPortAvailable(port) {
-        return new Promise((resolve) => {
-            const server = net.createServer();
-            let resolved = false;
-            const cleanup = () => {
-                if (!resolved) {
-                    resolved = true;
-                    try {
-                        server.close();
-                    }
-                    catch (e) {
-                        // Ignore errors during cleanup
-                    }
-                }
-            };
-            server.once('error', () => {
-                cleanup();
-                resolve(false);
-            });
-            server.once('listening', () => {
-                cleanup();
-                resolve(true);
-            });
-            // Add timeout to prevent hanging
-            setTimeout(() => {
-                cleanup();
-                resolve(false);
-            }, 2000); // Reduced timeout
-            try {
-                server.listen(port, '127.0.0.1');
-            }
-            catch (e) {
-                cleanup();
-                resolve(false);
-            }
+        /**
+         * Debug-port pool: acquisition serialization, wraparound scan, probe-busy
+         * quarantine, and stale-port sweep all live in PortAllocator. The plugin
+         * only acquires on launch and releases from the browser event handlers.
+         * One pool per process (matching the former static state): two crawlers in
+         * one process - e.g. a session-bundle restore - must not race the same range.
+         */
+        Object.defineProperty(this, "portAllocator", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: CDPBrowserPlugin.sharedPortAllocator
         });
     }
-    releasePort(port) {
-        if (CDPBrowserPlugin.usedPorts.has(port)) {
-            CDPBrowserPlugin.usedPorts.delete(port);
-            log.debug(`Released port ${port} back to pool. Used ports: ${CDPBrowserPlugin.usedPorts.size}/${CDPBrowserPlugin.PORT_RANGE.max - CDPBrowserPlugin.PORT_RANGE.min + 1}`);
-        }
-        else {
-            log.debug(`Attempted to release port ${port} that was not in use`);
-        }
-    }
     /**
      */
     async _addProxyToLaunchOptions() {
@@ -148,211 +77,149 @@ class CDPBrowserPlugin extends BrowserPlugin {
      * @private
      */
     async _launch(launchContext) {
-        const debuggingPort = await this.getNextAvailablePort();
+        const debuggingPort = await this.portAllocator.acquire();
         let browserProcess;
+        // Idempotent teardown for the anonymize proxy server. Reassigned the
+        // moment the anonymize promise exists; a no-op until then so the outer
+        // catch can always call it even when we fail before proxy setup.
+        let closeAnonymizedProxyOnce = async () => { };
         try {
-            const { launchOptions, useIncognitoPages, proxyUrl, fingerprint } = launchContext;
-            if (!launchOptions.browserType) {
-                launchOptions.browserType = "chrome";
-            }
-            // useNativeStealth may be set in three places (canonical, nested, or at
-            // launchContext root) — normalize to launchOptions.useNativeStealth so the
-            // rest of the pipeline reads one source of truth.
-            const nativeStealthRequested = !!launchOptions.useNativeStealth ||
-                !!launchOptions.fingerprintOptions?.useNativeStealth ||
-                !!launchContext?.useNativeStealth;
-            if (nativeStealthRequested) {
-                launchOptions.useNativeStealth = true;
-            }
-            // Auto-resolve the anti-detect binary so consumers can simply pass
-            // `useNativeStealth: true` without having to walk node_modules to find it.
-            // If the user pinned an explicit executablePath, respect it.
-            if (launchOptions.useNativeStealth && !launchOptions.executablePath) {
-                launchOptions.executablePath = resolveAntiDetectBrowserPath();
-                log.info('[AntiDetect] Auto-resolved anti-detect binary', {
-                    executablePath: launchOptions.executablePath,
-                });
-            }
-            // Extract screen dimensions from fingerprint if available and not already set
-            if (fingerprint?.fingerprint?.screen && !launchOptions.windowWidth && !launchOptions.windowHeight) {
-                const screen = fingerprint.fingerprint.screen;
-                launchOptions.windowWidth = screen.width || 1920;
-                launchOptions.windowHeight = screen.height || 1080;
-                log.info('Using fingerprint screen dimensions for browser window', {
-                    width: launchOptions.windowWidth,
-                    height: launchOptions.windowHeight,
-                    devicePixelRatio: screen.devicePixelRatio,
-                });
-            }
-            else if (launchOptions.windowWidth && launchOptions.windowHeight) {
-                log.info('Using explicitly set window dimensions', {
-                    width: launchOptions.windowWidth,
-                    height: launchOptions.windowHeight,
-                });
-            }
-            else {
-                log.warning('No fingerprint screen dimensions and no explicit dimensions - will use defaults or maximize');
-            }
+            const { launchOptions, useIncognitoPages, proxyUrl } = launchContext;
+            this._normalizeLaunchIdentity(launchContext);
             let browser;
             launchOptions.useIncognitoPages = useIncognitoPages;
             log.debug("Launch options", { ...launchOptions, debuggingPort });
-            const [anonymizedProxyUrl, close] = await anonymizeProxySugar(proxyUrl);
+            // If the caller handed us a previously-captured session bundle, hydrate
+            // launch state from it BEFORE any locale resolution / fingerprint
+            // generation runs - so the downstream code paths see the bundle's values
+            // as if the user had set them by hand and we never call the generators.
+            // This stays serial and ahead of the parallel block below because hydration
+            // may pin resolvedLocale / userDataDir that _ensureResolvedLocale then reads.
+            const { sessionBundle } = launchOptions;
+            if (sessionBundle) {
+                await this._hydrateFromSessionBundle(launchContext, sessionBundle);
+            }
+            // Proxy anonymization and locale resolution are independent launch I/O:
+            // both only READ the original proxyUrl and write to disjoint targets
+            // (anonymize returns [url, close]; ensureLocale writes launchOptions.resolvedLocale).
+            // Run them concurrently to cut one round-trip off the launch path.
+            //
+            // The anonymize close handle must be reachable from every cleanup path
+            // even if a *later* await in this method throws before we destructure
+            // the result - including the race where locale resolution rejects
+            // before anonymize has resolved. So we hold the anonymize promise in
+            // _launch scope and wrap its close in a single idempotent guard that
+            // awaits the promise itself: whoever fires first (inner catch, outer
+            // catch, or a browser close/error/disconnect handler) closes the
+            // server exactly once, and a proxy that resolves only after the
+            // failure is still torn down rather than leaked.
+            const anonymizePromise = anonymizeProxySugar(proxyUrl);
+            let proxyClosed = false;
+            closeAnonymizedProxyOnce = async () => {
+                if (proxyClosed)
+                    return;
+                proxyClosed = true;
+                try {
+                    const [, close] = await anonymizePromise;
+                    await close();
+                }
+                catch {
+                    // anonymizeProxySugar itself rejected - nothing was started,
+                    // so there is nothing to close.
+                }
+            };
+            const [[anonymizedProxyUrl]] = await Promise.all([
+                anonymizePromise,
+                this._ensureResolvedLocale(launchOptions, proxyUrl, launchContext.fingerprint),
+            ]);
             if (anonymizedProxyUrl) {
                 launchOptions.proxyUrl = anonymizedProxyUrl;
             }
-            // Resolve the locale triple once per launch so native-stealth args, CDP overrides,
-            // and the FingerprintConfigJson all read the same { locale, languages, timezone }.
-            // Priority: explicit fingerprintOptions.locale → proxy country (via ipinfo.io) →
-            // fingerprint-generator language → 'en-US'.
-            {
-                const fpOpts = launchOptions.fingerprintOptions;
-                const fingerprintLanguage = fingerprint?.headers
-                    ? (fingerprint.headers['accept-language'] ?? fingerprint.headers['Accept-Language'])
-                    : undefined;
-                // Only pay the ipinfo.io roundtrip if we actually need it — skip when the user
-                // has already pinned an explicit locale.
-                const proxyCountry = fpOpts?.locale ? undefined : await fetchProxyCountry(proxyUrl);
-                launchOptions.resolvedLocale = resolveLocale({
-                    locale: fpOpts?.locale,
-                    timezone: fpOpts?.timezone,
-                    languages: fpOpts?.languages,
-                    proxyCountry,
-                    fingerprintLanguage: fingerprintLanguage?.split(',')[0]?.trim(),
-                });
-                log.debug('[Locale] Resolved locale triple', {
-                    locale: launchOptions.resolvedLocale.locale,
-                    timezone: launchOptions.resolvedLocale.timezone,
-                    languages: launchOptions.resolvedLocale.languages,
-                    source: fpOpts?.locale ? 'user' : proxyCountry ? 'proxy' : 'fingerprint',
-                });
-            }
             // Pre-generate a per-session C++ fingerprint config for the anti-detect browser.
-            // The static default_fingerprint.json always uses the same GPU/screen/CPU — every
-            // browser instance looks identical. By generating the config from the fingerprint
-            // profile before launch, each session gets unique hardware-level C++ patches.
-            if (launchOptions.useNativeStealth) {
-                const _fpOpts = launchOptions.fingerprintOptions;
-                const proxySeedKey = proxyUrl
-                    ? (proxyUrl.match(/session-([^,&]+)/i)?.[1] ?? null)
-                    : null;
-                // If non-Apify real-device profiles are requested, generate the profile now
-                // so C++ gets the same profile that the fingerprint injector will use.
-                let fpForConfig = fingerprint;
-                if (_fpOpts?.useNonApifyFingerprints) {
-                    // User-supplied fingerprintOptions.platform wins; falls back to
-                    // whatever the existing Crawlee-generated fingerprint says.
-                    const userPlatform = _fpOpts?.platform;
-                    const osHint = (() => {
-                        const p = (fingerprint?.fingerprint?.navigator?.platform || '').toLowerCase();
-                        if (p.includes('mac'))
-                            return 'macos';
-                        if (p.includes('linux'))
-                            return 'linux';
-                        return 'windows';
-                    })();
-                    const nonApifyFp = await generateNonApifyFingerprint({
-                        platform: userPlatform,
-                        os: osHint,
-                        proxySeedKey,
-                    });
-                    fpForConfig = nonApifyFp;
-                    // Store for browser-controller._newPage() — it will reuse this instead of
-                    // generating a different profile (session consistency).
-                    launchContext.fingerprint = fpForConfig;
-                }
-                if (fpForConfig) {
-                    try {
-                        const cfg = generateFingerprintConfig(fpForConfig, proxySeedKey ?? undefined, launchOptions.resolvedLocale);
-                        // Align UA version with actual binary before writing the config.
-                        const binaryPath = getAntiDetectBrowserPath() ?? launchOptions.executablePath;
-                        if (binaryPath) {
-                            const binaryVersion = getChromeBinaryVersion(binaryPath);
-                            if (binaryVersion) {
-                                const major = binaryVersion.split('.')[0];
-                                if (cfg.navigator.userAgent) {
-                                    cfg.navigator.userAgent = cfg.navigator.userAgent.replace(/Chrome\/\d+\.\d+\.\d+\.\d+/, `Chrome/${major}.0.0.0`);
-                                }
-                                if (cfg.navigator.userAgentData) {
-                                    cfg.navigator.userAgentData.uaFullVersion = binaryVersion;
-                                    cfg.navigator.userAgentData.brands = cfg.navigator.userAgentData.brands.map(b => b.brand === 'Not_A Brand' ? b : { ...b, version: major, full_version: binaryVersion });
-                                    cfg.navigator.userAgentData.fullVersionList = cfg.navigator.userAgentData.brands;
-                                }
-                            }
-                        }
-                        launchOptions.fingerprintConfig = cfg;
-                        log.debug('[AntiDetect] Pre-generated per-session fingerprint config', {
-                            platform: cfg.navigator.platform,
-                            gpu: cfg.webgl.renderer.substring(0, 60),
-                            screen: `${cfg.screen.width}x${cfg.screen.height}`,
-                        });
-                    }
-                    catch (cfgErr) {
-                        log.debug('[AntiDetect] Could not pre-generate fingerprint config:', { error: cfgErr });
-                    }
-                }
+            // Skipped when a sessionBundle pre-supplied the config - that is the whole point
+            // of byte-for-byte replay.
+            if (launchOptions.useNativeStealth && !sessionBundle) {
+                await this._prepareNativeFingerprintConfig(launchContext);
             }
             browserProcess = await this._launchBrowser(debuggingPort, launchOptions);
             log.debug("Browser process started", { pid: browserProcess.pid, debuggingPort });
             try {
-                browser = await this._connectWithRetry(debuggingPort, 10, 4000);
-                // Add cleanup handlers
-                browser.on('close', async () => {
-                    try {
-                        this.releasePort(debuggingPort);
-                        if (anonymizedProxyUrl) {
-                            await close();
-                        }
-                        log.debug(`Browser on port ${debuggingPort} closed cleanly`);
-                    }
-                    catch (error) {
-                        log.warning(`Error during browser close cleanup on port ${debuggingPort}:`, { error });
-                        // Still release the port even if other cleanup fails
-                        this.releasePort(debuggingPort);
-                    }
-                });
-                // Add error handler to ensure cleanup
-                browser.on('error', async (error) => {
+                browser = await this._connectViaWsEndpoint(browserProcess, debuggingPort);
+                // Single once-guarded teardown wired to every terminal browser
+                // event (close / error / disconnect). Any of them can fire - and
+                // more than one can fire for the same instance - so the guard
+                // ensures the port is released and the anonymize proxy closed
+                // exactly once regardless of which event(s) arrive. Both
+                // portAllocator.release and closeAnonymizedProxyOnce are already
+                // idempotent; the guard additionally avoids duplicate log lines
+                // and redundant work.
+                let teardownDone = false;
+                const teardown = async (reason) => {
+                    if (teardownDone)
+                        return;
+                    teardownDone = true;
                     try {
-                        log.warning(`Browser error on port ${debuggingPort}:`, error);
-                        this.releasePort(debuggingPort);
-                        if (anonymizedProxyUrl) {
-                            await close();
-                        }
+                        this.portAllocator.release(debuggingPort);
+                        await closeAnonymizedProxyOnce();
+                        log.debug(`Browser on port ${debuggingPort} cleaned up (${reason})`);
                     }
                     catch (cleanupError) {
-                        log.error(`Error during browser error cleanup on port ${debuggingPort}:`, { error: cleanupError });
-                        // Still release the port even if other cleanup fails
-                        this.releasePort(debuggingPort);
+                        log.warning(`Error during browser ${reason} cleanup on port ${debuggingPort}:`, { error: cleanupError });
+                        // Still release the port even if other cleanup fails.
+                        this.portAllocator.release(debuggingPort);
                     }
+                };
+                browser.on('close', async () => teardown('close'));
+                browser.on('error', async (error) => {
+                    log.warning(`Browser error on port ${debuggingPort}:`, error);
+                    return teardown('error');
                 });
-                // Add disconnect handler for CDP connection issues
                 browser.on('disconnect', async () => {
-                    try {
-                        log.warning(`Browser disconnected on port ${debuggingPort}, cleaning up`);
-                        this.releasePort(debuggingPort);
-                        if (anonymizedProxyUrl) {
-                            await close();
-                        }
+                    log.warning(`Browser disconnected on port ${debuggingPort}, cleaning up`);
+                    return teardown('disconnect');
+                });
+                // Widevine, before the first navigation rather than after it. Real
+                // Chrome bundles the CDM and reports support immediately; ours has to
+                // fetch it, and only a FOREGROUND component check is served (#141).
+                // Doing it here means a page never observes the pre-CDM state where
+                // `requestMediaKeySystemAccess('com.widevine.alpha')` rejects - a
+                // divergence a detector needs one line to find. Cold cache costs this
+                // once per host; after that the profile is seeded before launch.
+                if (launchOptions.useNativeStealth) {
+                    const widevine = await ensureWidevineCdm({
+                        session: browser,
+                        userDataDir: browserProcess.getUserDataDir(),
+                    });
+                    const detail = { ...widevine, port: debuggingPort };
+                    if (widevine.usableThisSession) {
+                        log.debug('[AntiDetect] Widevine CDM ready before first navigation', detail);
                     }
-                    catch (cleanupError) {
-                        log.error(`Error during browser disconnect cleanup on port ${debuggingPort}:`, { error: cleanupError });
-                        // Still release the port even if other cleanup fails
-                        this.releasePort(debuggingPort);
+                    else if (widevine.outcome === 'installed-pending-restart') {
+                        // Linux binds the CDM at startup, so this session still reports
+                        // no Widevine; the profile and the host cache now have it, so
+                        // every later launch is correct from the first navigation.
+                        log.debug('[AntiDetect] Widevine CDM fetched; active from the next launch (Linux startup binding)', detail);
                     }
-                });
+                    else {
+                        log.debug('[AntiDetect] Widevine CDM unavailable this session', detail);
+                    }
+                }
                 launchContext.debuggingPort = debuggingPort;
                 launchContext.process = browserProcess;
                 return browser;
             }
             catch (error) {
-                if (anonymizedProxyUrl) {
-                    await close();
-                }
+                await closeAnonymizedProxyOnce();
                 throw error;
             }
         }
         catch (error) {
-            this.releasePort(debuggingPort);
+            this.portAllocator.release(debuggingPort);
+            // Close the anonymize proxy on any failure before the browser's own
+            // handlers were wired - covers a locale-resolution / fingerprint /
+            // launch failure that rejected the outer try before we ever connected.
+            // Idempotent, so it is a no-op if the inner catch already ran it.
+            await closeAnonymizedProxyOnce();
             // Ensure browser process is killed if it was started
             if (browserProcess) {
                 try {
@@ -365,6 +232,155 @@ class CDPBrowserPlugin extends BrowserPlugin {
             throw error;
         }
     }
+    /**
+     * Phase 1 of _launch - normalize the launch identity in place:
+     * default browserType, normalize useNativeStealth from its three legacy
+     * locations, auto-resolve the anti-detect binary, and adopt the
+     * fingerprint's screen dimensions when the caller didn't pin any.
+     */
+    _normalizeLaunchIdentity(launchContext) {
+        const { launchOptions, fingerprint } = launchContext;
+        if (!launchOptions.browserType) {
+            launchOptions.browserType = "chrome";
+        }
+        // Default to the non-Apify real-device fingerprint pool. Real Chrome
+        // device profiles unblock materially better than the synthetic Apify
+        // pool, so `useNonApifyFingerprints` defaults ON. Only fill it when the
+        // caller left it unset (explicit `false` is honored), and never for a
+        // session-bundle restore - that path pins its own captured fingerprint
+        // and must not re-roll from any pool. Clone the nested bag so we default
+        // on our per-launch copy, never the caller's object (issue #80).
+        if (!launchOptions.sessionBundle) {
+            const fpOpts = { ...(launchOptions.fingerprintOptions ?? {}) };
+            if (fpOpts.useNonApifyFingerprints === undefined) {
+                fpOpts.useNonApifyFingerprints = true;
+            }
+            launchOptions.fingerprintOptions = fpOpts;
+        }
+        // useNativeStealth may be set in three places (canonical, nested, or at
+        // launchContext root) - normalize to launchOptions.useNativeStealth so the
+        // rest of the pipeline reads one source of truth.
+        const nativeStealthRequested = resolveUseNativeStealth(launchOptions, launchContext);
+        if (nativeStealthRequested) {
+            launchOptions.useNativeStealth = true;
+        }
+        // Auto-resolve the anti-detect binary so consumers can simply pass
+        // `useNativeStealth: true` without having to walk node_modules to find it.
+        // If the user pinned an explicit executablePath, respect it.
+        if (launchOptions.useNativeStealth && !launchOptions.executablePath) {
+            launchOptions.executablePath = resolveAntiDetectBrowserPath();
+            log.debug('[AntiDetect] Auto-resolved anti-detect binary', {
+                executablePath: launchOptions.executablePath,
+            });
+        }
+        // Extract screen dimensions from fingerprint if available and not already set
+        if (fingerprint?.fingerprint?.screen && !launchOptions.windowWidth && !launchOptions.windowHeight) {
+            const { screen } = fingerprint.fingerprint;
+            launchOptions.windowWidth = screen.width || 1920;
+            launchOptions.windowHeight = screen.height || 1080;
+            log.info('Using fingerprint screen dimensions for browser window', {
+                width: launchOptions.windowWidth,
+                height: launchOptions.windowHeight,
+                devicePixelRatio: screen.devicePixelRatio,
+            });
+        }
+        else if (launchOptions.windowWidth && launchOptions.windowHeight) {
+            log.debug('Using explicitly set window dimensions', {
+                width: launchOptions.windowWidth,
+                height: launchOptions.windowHeight,
+            });
+        }
+        else {
+            log.warning('No fingerprint screen dimensions and no explicit dimensions - will use defaults or maximize');
+        }
+    }
+    /**
+     * Phase 2 of _launch - hydrate launch state from a previously-captured
+     * session bundle: untar the user-data-dir, pin the resolved locale +
+     * fingerprintConfig verbatim, and replace the fingerprint so no generator
+     * runs (byte-for-byte replay).
+     */
+    async _hydrateFromSessionBundle(launchContext, sessionBundle) {
+        const { launchOptions } = launchContext;
+        assertValidBundle(sessionBundle);
+        if (sessionBundle.userDataDir && !launchOptions.userDataDir) {
+            const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), 'cdp-crawler-session-'));
+            await untarUserDataDir(sessionBundle.userDataDir, tempDir);
+            launchOptions.userDataDir = tempDir;
+            log.info('[session] Restored user-data-dir from bundle', {
+                tempDir,
+                sizeBytes: sessionBundle.userDataDir.sizeBytes,
+                capturedFiles: sessionBundle.userDataDir.capturedFiles,
+            });
+        }
+        launchOptions.resolvedLocale = sessionBundle.resolvedLocale;
+        launchOptions.fingerprintConfig = sessionBundle.fingerprintConfig;
+        launchOptions.fingerprintOptions = {
+            ...(launchOptions.fingerprintOptions ?? {}),
+            ...sessionBundle.fingerprintInput,
+            useNonApifyFingerprints: false,
+        };
+        launchContext.fingerprint = sessionBundle.fingerprint;
+        log.info('[session] Hydrated launchContext from sessionBundle', {
+            cookies: sessionBundle.cookies.length,
+            localStorageOrigins: Object.keys(sessionBundle.localStorage).length,
+            sessionStorageOrigins: Object.keys(sessionBundle.sessionStorage).length,
+            locale: sessionBundle.resolvedLocale.locale,
+            timezone: sessionBundle.resolvedLocale.timezone,
+        });
+    }
+    /**
+     * Phase 3 of _launch - resolve the locale triple once per launch so
+     * native-stealth args, CDP overrides, and the FingerprintConfigJson all
+     * read the same { locale, languages, timezone }. No-op when a session
+     * bundle (or an earlier caller) already pinned the triple.
+     */
+    async _ensureResolvedLocale(launchOptions, proxyUrl, fingerprint) {
+        // Resolve the locale triple once per launch so native-stealth args, CDP overrides,
+        // and the FingerprintConfigJson all read the same { locale, languages, timezone }.
+        // Priority: explicit fingerprintOptions.locale → proxy country (via ipinfo.io) →
+        // fingerprint-generator language → 'en-US'. Skipped when a sessionBundle already
+        // pinned the triple above.
+        if (!launchOptions.resolvedLocale) {
+            const fpOpts = launchOptions.fingerprintOptions;
+            const fingerprintLanguage = fingerprint?.headers
+                ? (fingerprint.headers['accept-language'] ?? fingerprint.headers['Accept-Language'])
+                : undefined;
+            // Only pay the ipinfo.io roundtrip if we actually need it - skip when the user
+            // has already pinned an explicit locale.
+            const proxyCountry = fpOpts?.locale ? undefined : await fetchProxyCountry(proxyUrl);
+            launchOptions.resolvedLocale = resolveLocale({
+                locale: fpOpts?.locale,
+                timezone: fpOpts?.timezone,
+                languages: fpOpts?.languages,
+                proxyCountry,
+                fingerprintLanguage: fingerprintLanguage?.split(',')[0]?.trim(),
+            });
+            let localeSource;
+            if (fpOpts?.locale)
+                localeSource = 'user';
+            else if (proxyCountry)
+                localeSource = 'proxy';
+            else
+                localeSource = 'fingerprint';
+            log.debug('[Locale] Resolved locale triple', {
+                locale: launchOptions.resolvedLocale.locale,
+                timezone: launchOptions.resolvedLocale.timezone,
+                languages: launchOptions.resolvedLocale.languages,
+                source: localeSource,
+            });
+        }
+    }
+    /**
+     * Phase 4 of _launch - thin delegate to the FingerprintConfig module's
+     * pre-launch path. It selects a clean (uncontaminated, OS-matching) profile,
+     * generates + aligns the FingerprintConfigJson, stamps the config onto
+     * launchOptions for browser-process to write, and records the selection on
+     * the launch context for the post-launch path to reuse.
+     */
+    async _prepareNativeFingerprintConfig(launchContext) {
+        await prepareForLaunch(launchContext);
+    }
     /**
      * Creates a new browser controller.
      *
@@ -383,11 +399,27 @@ class CDPBrowserPlugin extends BrowserPlugin {
     async _launchBrowser(debuggingPort, launchOptions) {
         const { proxyUrl, browserType, ignoreHttpsErrors = true, headless, executablePath, useNativeStealth, useExperimentalFingerprints, fingerprintOptions, fingerprintConfig, maximizeWindow, windowWidth, windowHeight, userDataDir, keepUserDataDir, dnsOverHttpsServer, secureDnsMode, webrtcIpHandlingPolicy, } = launchOptions;
         if (executablePath) {
-            log.info(`[AntiDetect] Launching browser binary: ${executablePath}`);
+            log.debug(`[AntiDetect] Launching browser binary: ${executablePath}`);
         }
         let browserProcess;
         switch (browserType) {
             case "chrome": {
+                // Anti-Detect 2026-05-18: when native stealth is active and the
+                // caller didn't pin an explicit policy, default to
+                // `disable_non_proxied_udp` - the strictest setting, which
+                // tells Chromium's WebRTC stack to refuse UDP traffic unless
+                // it's tunneled through the proxy. This prevents host/srflx
+                // ICE candidate GATHERING at the network layer (which would
+                // otherwise add the real LAN/public IP to
+                // peerConnection.localDescription.sdp regardless of any
+                // JS-visible event filter). Pairs with the renderer-side
+                // candidate filter in rtc_peer_connection.cc::
+                // DidGenerateICECandidate that catches anything the policy
+                // misses on the trickle-ICE event path. Detection vectors
+                // covered: browserleaks.com/webrtc, ipleak.net,
+                // FingerprintJS WebRTC panel.
+                const effectiveWebrtcPolicy = webrtcIpHandlingPolicy
+                    ?? (useNativeStealth ? 'disable_non_proxied_udp' : undefined);
                 browserProcess = await launchChromeBrowserWithNewProfile({
                     debuggingPort,
                     anonymizedProxyUrl: proxyUrl,
@@ -405,7 +437,7 @@ class CDPBrowserPlugin extends BrowserPlugin {
                     keepUserDataDir,
                     dnsOverHttpsServer,
                     secureDnsMode,
-                    webrtcIpHandlingPolicy,
+                    webrtcIpHandlingPolicy: effectiveWebrtcPolicy,
                 });
                 break;
             }
@@ -413,108 +445,73 @@ class CDPBrowserPlugin extends BrowserPlugin {
                 throw new Error(`No browser found with this type: ${browserType}!`);
             }
         }
-        return new Promise((resolve, reject) => {
-            this._waitForPort(debuggingPort)
-                .then(() => {
-                log.info(`Browser is ready on port ${debuggingPort}`);
-                resolve(browserProcess);
-            })
-                .catch((err) => {
-                log.error(`Failed to connect to browser on port: ${debuggingPort}`, err);
-                reject(new Error(`Failed to connect to browser on port: ${debuggingPort}`));
-            });
-        });
+        // Readiness is now driven off the browser's stderr (the "DevTools
+        // listening on ws://…" line), awaited by _connectViaWsEndpoint. No TCP
+        // port poll here - just hand back the live process.
+        return browserProcess;
     }
     /**
-     * Waits for a port to be available.
-     *
-     * @private
+     * Open the raw CDP connection. The newPage guard is part of the public
+     * contract: pages are created through CDPBrowserController, never here.
+     * @protected for test seams.
      */
-    async _waitForPort(port, timeout = 30000, retryDelay = 500) {
-        const startTime = Date.now();
-        return new Promise((resolve, reject) => {
-            (function tryConnect() {
-                const socket = net.createConnection(port, '127.0.0.1');
-                socket.on('connect', () => {
-                    socket.end();
-                    resolve(true);
-                }).on('error', (_err) => {
-                    if (Date.now() - startTime > timeout) {
-                        reject(new Error(`Timeout waiting for port ${port}`));
-                    }
-                    else {
-                        setTimeout(tryConnect, retryDelay); // Retry after a delay
-                    }
-                });
-            }());
-        });
+    async _openCdpConnection(options) {
+        const cdp = await CDP(options);
+        // @ts-expect-error newPage is not part of the CDP client type
+        cdp.newPage = () => { throw new Error("Use BrowserController class for creating new page!"); };
+        return cdp;
     }
     /**
-     * Tries to connect to the browser using CDP with retries.
+     * Readiness + connect, Puppeteer-style. Await the browser-level CDP
+     * WebSocket endpoint the launcher parsed from Chromium's stderr, then open
+     * the CDP connection straight to that ws URL as the target. The endpoint
+     * promise already rejects fast (with the stderr tail) if the process dies,
+     * so a genuinely dead binary fails immediately instead of spinning a retry
+     * loop; a slow cold start still wins as long as it comes up within
+     * CDP_READINESS_TIMEOUT_MS. The overall timeout only guards a wedged process
+     * that never prints the line and never exits.
      *
      * @private
      */
-    async _connectWithRetry(port, maxRetries, retryDelay) {
-        let attempt = 0;
-        let lastError = null;
-        // Add delay before first attempt to allow browser to fully start
-        await new Promise(resolve => setTimeout(resolve, 1000));
-        while (attempt < maxRetries) {
-            try {
-                const cdpLauncher = new CdpLauncher();
-                const browser = await Promise.race([
-                    cdpLauncher.launch({ port }),
-                    new Promise((_, reject) => setTimeout(() => reject(new Error('Launch timeout')), 10000)),
-                ]);
-                log.info(`Connected to browser on port ${port} on attempt ${attempt + 1}`);
-                return browser;
-            }
-            catch (error) {
-                attempt++;
-                if (error instanceof Error) {
-                    lastError = error;
-                }
-                else {
-                    lastError = new Error(String(error));
-                }
-                log.warning(`Failed to connect to browser on attempt ${attempt}. Error: ${lastError.message}`);
-                if (attempt < maxRetries) {
-                    // Exponential backoff
-                    const backoffDelay = retryDelay * 2 ** (attempt - 1);
-                    await new Promise(resolve => setTimeout(resolve, backoffDelay));
-                }
-            }
+    async _connectViaWsEndpoint(browserProcess, debuggingPort) {
+        let timeoutHandle;
+        const timeout = new Promise((_, reject) => {
+            timeoutHandle = setTimeout(() => reject(new Error(`Timed out after ${CDP_READINESS_TIMEOUT_MS}ms waiting for the CDP WebSocket endpoint on port ${debuggingPort}`)), CDP_READINESS_TIMEOUT_MS);
+        });
+        try {
+            // Race the timeout against the WHOLE readiness+connect sequence, not
+            // just the ws-endpoint wait: chrome-remote-interface's protocol fetch
+            // and ws handshake have no built-in timeout, so a browser that prints
+            // the DevTools banner and then stalls the handshake (wedged renderer /
+            // resource exhaustion under high concurrency) would otherwise hang
+            // _launch forever and leak the port + Chromium process.
+            return await Promise.race([
+                (async () => {
+                    const wsUrl = await browserProcess.wsEndpoint();
+                    log.debug(`Browser CDP endpoint ready on port ${debuggingPort}`, { wsUrl });
+                    // `local: true` makes chrome-remote-interface use its bundled
+                    // protocol instead of fetching it over the DevTools HTTP
+                    // endpoint. Without it the connect opens a second TCP socket
+                    // (an HTTP /json/protocol GET kept alive) alongside the ws -
+                    // an /json round-trip ADR 0003 set out to remove, and a
+                    // second live socket on the single-socket transport. The
+                    // reconnect path (browser-controller) already connects this way.
+                    return this._openCdpConnection({ target: wsUrl, local: true });
+                })(),
+                timeout,
+            ]);
+        }
+        finally {
+            if (timeoutHandle)
+                clearTimeout(timeoutHandle);
         }
-        // Always throw the wrapped error with our standard message
-        throw new Error(`Failed to connect to browser after ${maxRetries} attempts.`);
     }
 }
-Object.defineProperty(CDPBrowserPlugin, "PORT_RANGE", {
-    enumerable: true,
-    configurable: true,
-    writable: true,
-    value: {
-        min: 9200,
-        max: 9600, // Give a range of 400 ports instead of 200
-    }
-});
-Object.defineProperty(CDPBrowserPlugin, "usedPorts", {
-    enumerable: true,
-    configurable: true,
-    writable: true,
-    value: new Set()
-});
-Object.defineProperty(CDPBrowserPlugin, "lastAssignedPort", {
-    enumerable: true,
-    configurable: true,
-    writable: true,
-    value: CDPBrowserPlugin.PORT_RANGE.min - 1
-});
-Object.defineProperty(CDPBrowserPlugin, "portLock", {
+Object.defineProperty(CDPBrowserPlugin, "sharedPortAllocator", {
     enumerable: true,
     configurable: true,
     writable: true,
-    value: false
+    value: new PortAllocator({ min: 9200, max: 9600 })
 });
 export default CDPBrowserPlugin;
 //# sourceMappingURL=browser-plugin.js.map