jumpy-lion 0.1.6-beta.9 → 1.0.0-beta.4

package/dist/connection/session-client.js

@@ -0,0 +1,129 @@
+/**
+ * SessionClient - a session-scoped view of the single browser CDP client.
+ *
+ * In flatten-mode transport (ADR 0003) there is ONE websocket to the browser
+ * target; every page is a CDP *session* multiplexed over it, addressed by a
+ * `sessionId`. This proxy presents the familiar `CDP.Client` shape to `CdpPage`
+ * and its sub-modules while injecting the page's `sessionId` into every command
+ * and event subscription. That keeps the ~10 `this.client.Domain.method()` call
+ * sites in `page.ts` (and the input transport / injector / inject-hook) exactly
+ * as written - the proxy is the single seam where sessionId enters.
+ *
+ * How `chrome-remote-interface` (0.33.2) exposes things, which this mirrors:
+ * - a command is `Domain.method(params, sessionId, callback)` (decorated
+ *   `.category === 'command'`); we bind arg 2 to the current sessionId.
+ * - an event is `Domain.event(sessionId, handler)` (`.category === 'event'`);
+ *   we bind arg 1 to the current sessionId. It returns an unsubscribe fn.
+ * - the connection also emits every session event under `${Domain.event}.${sessionId}`
+ *   (chrome.js), so raw `client.on('Domain.event', h)` must be rewritten to the
+ *   session-scoped name or it would fire for *every* page's events.
+ *
+ * `browser()` and `sessionId()` are read at call time, so a browser-socket
+ * reconnect (new underlying client) or a session re-attach (new sessionId) is
+ * picked up transparently - the proxy object itself is stable and never needs
+ * to be recreated.
+ */
+/** Matches a CDP event name `Domain.event` so we only session-scope real events. */
+const CDP_EVENT_NAME = /^[A-Z]\w*\.\w+$/;
+/**
+ * A CDP domain object is an upper-cased property (Page, Network, Runtime, DOM,
+ * Input, Target, …). Everything else on the client (send, _ws, on, protocol,
+ * webSocketUrl, EventEmitter internals) is transport plumbing, not a domain.
+ */
+const isDomainName = (prop) => /^[A-Z]/.test(prop);
+/**
+ * Browser-GLOBAL domains are answered by the browser process itself, not by a
+ * page target, so their commands must be sent WITHOUT a sessionId - tagging e.g.
+ * `Browser.getVersion` with a page's sessionId makes Chrome reject it
+ * (`'Browser.getVersion' wasn't found`). These are returned raw (no injection);
+ * only page-scoped domains (Page, Network, Runtime, DOM, Input, …) get scoped.
+ * `Target` is here because the only page-side use is `close()` detaching by
+ * sessionId, which the proxy handles explicitly against the raw client.
+ */
+const BROWSER_GLOBAL_DOMAINS = new Set(['Browser', 'Target', 'SystemInfo', 'Tracing', 'Tethering']);
+export function createSessionClient(deps) {
+    const { browser, sessionId } = deps;
+    const sessionEventName = (name) => (CDP_EVENT_NAME.test(name) ? `${name}.${sessionId()}` : name);
+    const domainProxies = new Map();
+    /** Read a raw property off the current browser client, binding functions to it. */
+    const rawPassthrough = (prop) => {
+        const rawBrowser = browser();
+        const value = rawBrowser[prop];
+        return typeof value === 'function' ? value.bind(rawBrowser) : value;
+    };
+    const makeDomainProxy = (domainName) => new Proxy(Object.create(null), {
+        get(_target, member) {
+            const domain = browser()[domainName];
+            // Symbol keys (e.g. util.inspect.custom) never carry CDP semantics -
+            // pass them straight through to the raw domain object.
+            if (typeof member === 'symbol')
+                return domain?.[member];
+            // Domain-level shorthand `Domain.on(event, handler)` → session-scoped subscribe.
+            if (member === 'on') {
+                return (eventName, listener) => domain[eventName](sessionId(), listener);
+            }
+            const apiFn = domain?.[member];
+            if (typeof apiFn !== 'function')
+                return apiFn;
+            if (apiFn.category === 'event') {
+                // Event subscription: sessionId is the FIRST positional arg.
+                return (listener) => apiFn(sessionId(), listener);
+            }
+            // Command (or any other fn): sessionId is the SECOND positional arg.
+            return (params, callback) => apiFn(params, sessionId(), callback);
+        },
+    });
+    const handler = {
+        get(_target, prop) {
+            // Symbol keys (util.inspect.custom, Symbol.iterator, …) carry no CDP
+            // semantics; RegExp/Set lookups would throw on them. Pass through raw.
+            if (typeof prop === 'symbol')
+                return rawPassthrough(prop);
+            switch (prop) {
+                case 'send':
+                    // Raw send: default the sessionId if the caller didn't pass one.
+                    return (method, params, sessionIdArg, callback) => browser().send(method, params, sessionIdArg ?? sessionId(), callback);
+                case 'on':
+                case 'once':
+                case 'addListener':
+                    return (name, listener) => browser()[prop](sessionEventName(name), listener);
+                case 'off':
+                case 'removeListener':
+                    return (name, listener) => browser()[prop](sessionEventName(name), listener);
+                case '_ws':
+                    // The websocket is SHARED across all sessions; expose it read-only
+                    // for the keep-alive heartbeat. A page must never close it.
+                    return browser()._ws;
+                case 'close':
+                    // Closing a *page's* client detaches its session only - never the
+                    // shared socket (that would kill every other page). The tab/target
+                    // itself is closed via `Page.close()` on the page-close path.
+                    return async () => {
+                        try {
+                            await browser().Target.detachFromTarget({ sessionId: sessionId() });
+                        }
+                        catch {
+                            // tolerate already-detached session or an already-closed browser
+                        }
+                    };
+                case 'sessionId':
+                    return sessionId();
+                default:
+                    break;
+            }
+            if (isDomainName(prop) && !BROWSER_GLOBAL_DOMAINS.has(prop)) {
+                let domainProxy = domainProxies.get(prop);
+                if (!domainProxy) {
+                    domainProxy = makeDomainProxy(prop);
+                    domainProxies.set(prop, domainProxy);
+                }
+                return domainProxy;
+            }
+            // Browser-global domains and everything else pass through to the raw
+            // browser client with NO sessionId injection.
+            return rawPassthrough(prop);
+        },
+    };
+    return new Proxy(Object.create(null), handler);
+}
+//# sourceMappingURL=session-client.js.map

package/dist/connection/session-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-client.js","sourceRoot":"","sources":["../../src/connection/session-client.ts"],"names":[],"mappings":"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"}

package/dist/crawler.d.ts

@@ -2,102 +2,24 @@ import type { Dictionary } from '@crawlee/types';
 import type { BrowserCrawlerOptions, BrowserCrawlingContext, BrowserHook, BrowserRequestHandler, LaunchContext, LoadedContext, RouterRoutes, RouterHandler } from 'crawlee';
 import { BrowserCrawler, Configuration } from 'crawlee';
 import type CDPBrowserController from './browser-controller.js';
-import CDPBrowserPlugin from './browser-plugin.js';
-import { CdpLauncher, type LaunchReturn } from './launcher-wrap.js';
+import CDPBrowserPlugin, { CdpLauncher, type LaunchReturn } from './browser-plugin.js';
+import type { BaseLaunchBrowserOptions, FingerprintGeneratorOptions } from './browser-process/launch-options.js';
 import type CdpPage from './page.js';
 import type { GotoOptions } from './page.js';
 import type CDPCrawler from './index.js';
 /**
- * Humanization options for simulating realistic user behavior
- * All options are disabled by default for performance
+ * Option types are declared once in `browser-process/launch-options.ts` and
+ * imported here - see issue #80. `LaunchOptions` is `BaseLaunchBrowserOptions`
+ * (the shared launch surface, incl. the `fingerprintOptions` spoof bag) plus
+ * the crawler-facing fields. The internal `fingerprintConfig` / `resolvedLocale`
+ * fields are populated by the plugin/process layers at launch, not by callers,
+ * so they are omitted from the public crawler surface.
  */
-interface HumanizationOptions {
-    /** Enable mouse movement humanization. Default: false */
-    mouse?: boolean;
-    /** Enable keyboard humanization. Default: false */
-    keyboard?: boolean;
-    /** Enable scroll humanization. Default: false */
-    scroll?: boolean;
-}
-interface FingerprintGeneratorOptions {
-    /** Operating systems to generate fingerprints for (e.g., ["windows"], ["macos"], ["linux"]) */
-    operatingSystems?: string[];
-    /** Devices to generate fingerprints for (e.g., ["desktop"], ["mobile"]) */
-    devices?: string[];
-    /** Browsers to generate fingerprints for (e.g., ["chrome"], ["firefox"]) */
-    browsers?: string[];
-    /** Locales to generate fingerprints for (e.g., ["en-US"], ["it-IT"]) */
-    locales?: string[];
-}
-interface LaunchOptions {
-    headless?: boolean;
-    useExperimentalFingerprints?: boolean;
-    windowWidth?: number;
-    windowHeight?: number;
-    ignoreHttpsErrors?: boolean;
-    executablePath?: string;
-    /**
-     * Launch the anti-detect Cromite binary (postinstall-downloaded into
-     * `.browser/<platform>/` by default, or set via ANTI_DETECT_CHROME_PATH).
-     * When true and the binary is resolvable, JS-based fingerprint injection
-     * is skipped because the C++ patches already cover those overrides. If
-     * the binary cannot be found, this flag is transparently downgraded and
-     * the standard Chrome + JS injection path is used instead.
-     */
-    useNativeStealth?: boolean;
+export interface LaunchOptions extends Omit<BaseLaunchBrowserOptions, 'fingerprintConfig' | 'resolvedLocale'> {
     browserType?: string;
     useIncognitoPages?: boolean;
-    userDataDir?: string;
-    keepUserDataDir?: boolean;
-    dnsOverHttpsServer?: string;
-    secureDnsMode?: 'off' | 'automatic' | 'secure';
-    webrtcIpHandlingPolicy?: 'default' | 'default_public_interface_only' | 'default_public_and_private_interfaces' | 'disable_non_proxied_udp';
-    /** Whether to start the browser maximized and fullscreen. Default: true */
-    maximizeWindow?: boolean;
     /** Options for fingerprint generation - passed from browserPoolOptions */
     fingerprintGeneratorOptions?: FingerprintGeneratorOptions;
-    fingerprintOptions?: {
-        enableAdvancedStealth?: boolean;
-        bypassRuntimeEnable?: boolean;
-        spoofWebGL?: boolean;
-        spoofAudioContext?: boolean;
-        spoofClientRects?: boolean;
-        maskAutomationFlags?: boolean;
-        useFingerprintDefaults?: boolean;
-        platform?: 'Win32' | 'MacIntel' | 'Linux x86_64';
-        spoofFonts?: boolean;
-        spoofPerformance?: boolean;
-        spoofLocale?: boolean;
-        detectTimezone?: boolean;
-        /**
-         * BCP-47 locale tag (e.g. 'ko-KR', 'de-DE'). One flag that coherently drives
-         * navigator.language(s), Accept-Language header, Intl defaults, currency
-         * symbol, date/number formatting, and timezone (derived from region).
-         * When unset, falls back to proxy-country lookup → fingerprint language → 'en-US'.
-         */
-        locale?: string;
-        /** Explicit IANA timezone (e.g. 'Asia/Seoul'). Overrides locale-derived timezone. */
-        timezone?: string;
-        /** Explicit Accept-Language header (e.g. 'ko-KR,ko;q=0.9'). Overrides locale-derived list. */
-        languages?: string;
-        bypassCDPDetection?: boolean;
-        spoofStorage?: boolean;
-        spoofTiming?: boolean;
-        enableDataDomeBypass?: boolean;
-        webRtcPolicy?: 'spoof' | 'disable';
-        /** Humanization options (all disabled by default) */
-        humanization?: HumanizationOptions;
-        /** Enable debug logging in browser console. Default: true for debugging */
-        debug?: boolean;
-        /** Use real Chrome device profiles instead of Apify fingerprint-generator. Default: false */
-        useNonApifyFingerprints?: boolean;
-        /**
-         * Mirror of `launchOptions.useNativeStealth`. Historical call sites
-         * place it under `fingerprintOptions`; the runtime checks both
-         * (`opts.useNativeStealth || opts.fingerprintOptions?.useNativeStealth`).
-         */
-        useNativeStealth?: boolean;
-    };
 }
 export interface CDPPluginOptions {
     browserPlugins: [CDPBrowserPlugin];
@@ -125,5 +47,4 @@ export default class Crawler extends BrowserCrawler<CDPPluginOptions, LaunchOpti
 }
 export type CDPRouter<Context extends CDPCrawlingContext = CDPCrawlingContext> = RouterHandler<Context>;
 export declare function createCDPRouter<Context extends CDPCrawlingContext = CDPCrawlingContext>(routes?: RouterRoutes<Context, Dictionary>): CDPRouter<Context>;
-export {};
 //# sourceMappingURL=crawler.d.ts.map

package/dist/crawler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"crawler.d.ts","sourceRoot":"","sources":["../src/crawler.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,KAAK,EAAE,qBAAqB,EAAE,sBAAsB,EAAE,WAAW,EAAE,qBAAqB,EAAE,aAAa,EAAE,aAAa,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC5K,OAAO,EAAE,cAAc,EAAE,aAAa,EAAU,MAAM,SAAS,CAAC;AAEhE,OAAO,KAAK,oBAAoB,MAAM,yBAAyB,CAAC;AAChE,OAAO,gBAAgB,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,WAAW,EAAE,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACpE,OAAO,KAAK,OAAO,MAAM,WAAW,CAAC;AACrC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAE7C,OAAO,KAAK,UAAU,MAAM,YAAY,CAAC;AAEzC;;;GAGG;AACH,UAAU,mBAAmB;IACzB,yDAAyD;IACzD,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,mDAAmD;IACnD,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,iDAAiD;IACjD,MAAM,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,UAAU,2BAA2B;IACjC,+FAA+F;IAC/F,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,2EAA2E;IAC3E,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,4EAA4E;IAC5E,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,wEAAwE;IACxE,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,UAAU,aAAa;IACnB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,2BAA2B,CAAC,EAAE,OAAO,CAAC;IACtC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;;;OAOG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,aAAa,CAAC,EAAE,KAAK,GAAG,WAAW,GAAG,QAAQ,CAAC;IAC/C,sBAAsB,CAAC,EAAE,SAAS,GAAG,+BAA+B,GAAG,uCAAuC,GAAG,yBAAyB,CAAC;IAC3I,2EAA2E;IAC3E,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,0EAA0E;IAC1E,2BAA2B,CAAC,EAAE,2BAA2B,CAAC;IAC1D,kBAAkB,CAAC,EAAE;QACjB,qBAAqB,CAAC,EAAE,OAAO,CAAC;QAChC,mBAAmB,CAAC,EAAE,OAAO,CAAC;QAC9B,UAAU,CAAC,EAAE,OAAO,CAAC;QACrB,iBAAiB,CAAC,EAAE,OAAO,CAAC;QAC5B,gBAAgB,CAAC,EAAE,OAAO,CAAC;QAC3B,mBAAmB,CAAC,EAAE,OAAO,CAAC;QAC9B,sBAAsB,CAAC,EAAE,OAAO,CAAC;QACjC,QAAQ,CAAC,EAAE,OAAO,GAAG,UAAU,GAAG,cAAc,CAAC;QACjD,UAAU,CAAC,EAAE,OAAO,CAAC;QACrB,gBAAgB,CAAC,EAAE,OAAO,CAAC;QAC3B,WAAW,CAAC,EAAE,OAAO,CAAC;QACtB,cAAc,CAAC,EAAE,OAAO,CAAC;QACzB;;;;;WAKG;QACH,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,qFAAqF;QACrF,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,8FAA8F;QAC9F,SAAS,CAAC,EAAE,MAAM,CAAC;QAEnB,kBAAkB,CAAC,EAAE,OAAO,CAAC;QAC7B,YAAY,CAAC,EAAE,OAAO,CAAC;QACvB,WAAW,CAAC,EAAE,OAAO,CAAC;QACtB,oBAAoB,CAAC,EAAE,OAAO,CAAC;QAC/B,YAAY,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;QACnC,qDAAqD;QACrD,YAAY,CAAC,EAAE,mBAAmB,CAAC;QACnC,2EAA2E;QAC3E,KAAK,CAAC,EAAE,OAAO,CAAC;QAChB,6FAA6F;QAC7F,uBAAuB,CAAC,EAAE,OAAO,CAAC;QAClC;;;;WAIG;QACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;KAC9B,CAAC;CACL;AAED,MAAM,WAAW,gBAAgB;IAAG,cAAc,EAAE,CAAC,gBAAgB,CAAC,CAAA;CAAE;AACxE,MAAM,MAAM,cAAc,GAAG,UAAU,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAG5D,MAAM,WAAW,kBAAkB,CAAC,QAAQ,SAAS,UAAU,GAAG,UAAU,CACxE,SAAQ,sBAAsB,CAC1B,OAAO,UAAU,EACjB,OAAO,EACP,QAAQ,EACR,oBAAoB,EACpB,QAAQ,CACX;CAAG;AACR,MAAM,WAAW,gBAAiB,SAAQ,OAAO,CAAC,IAAI,CAAC,aAAa,CAAC,WAAW,EAAE,aAAa,EAAE,YAAY,EAAE,EAAE,EAAE,OAAO,CAAC,EAAE,eAAe,CAAC,CAAC;IAC1I,aAAa,CAAC,EAAE,aAAa,CAAC;CACjC;AAED,MAAM,WAAW,OAAQ,SAAQ,WAAW,CAAC,kBAAkB,EAAE,cAAc,CAAC;CAAG;AACnF,MAAM,WAAW,iBAAkB,SAAQ,qBAAqB,CAAC,aAAa,CAAC,kBAAkB,CAAC,CAAC;IAC/F,CAAC,GAAG,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CACnD;AACD,MAAM,WAAW,iBAAkB,SAAQ,qBAAqB,CAAC,kBAAkB,EAAE,gBAAgB,CAAC;IAClG,aAAa,CAAC,EAAE,gBAAgB,CAAC;IACjC,cAAc,CAAC,EAAE,iBAAiB,CAAC;CACtC;AAGD,MAAM,CAAC,OAAO,OAAO,OAAQ,SAAQ,cAAc,CAC/C,gBAAgB,EAChB,aAAa,EACb,kBAAkB,CACrB;IAGO,OAAO,CAAC,QAAQ,CAAC,cAAc;aACb,MAAM;gBADP,cAAc,GAAE,iBAAsB,EACrC,MAAM,gBAAkC;cAwDrC,kBAAkB,CAAC,eAAe,EAAE,kBAAkB,EAAE,WAAW,EAAE,WAAW,GAAG,OAAO,CAAC,GAAG,CAAC;CAK3H;AAED,MAAM,MAAM,SAAS,CACjB,OAAO,SAAS,kBAAkB,GAAG,kBAAkB,IACvD,aAAa,CAAC,OAAO,CAAC,CAAC;AAE3B,wBAAgB,eAAe,CAC3B,OAAO,SAAS,kBAAkB,GAAG,kBAAkB,EACzD,MAAM,CAAC,EAAE,YAAY,CAAC,OAAO,EAAE,UAAU,CAAC,GAAG,SAAS,CAAC,OAAO,CAAC,CAEhE"}
+{"version":3,"file":"crawler.d.ts","sourceRoot":"","sources":["../src/crawler.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,KAAK,EAAE,qBAAqB,EAAE,sBAAsB,EAAE,WAAW,EAAE,qBAAqB,EAAE,aAAa,EAAE,aAAa,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC5K,OAAO,EAAE,cAAc,EAAE,aAAa,EAAe,MAAM,SAAS,CAAC;AAErE,OAAO,KAAK,oBAAoB,MAAM,yBAAyB,CAAC;AAChE,OAAO,gBAAgB,EAAE,EAAE,WAAW,EAAE,KAAK,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACvF,OAAO,KAAK,EAAE,wBAAwB,EAAE,2BAA2B,EAAsB,MAAM,qCAAqC,CAAC;AAErI,OAAO,KAAK,OAAO,MAAM,WAAW,CAAC;AACrC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAE7C,OAAO,KAAK,UAAU,MAAM,YAAY,CAAC;AAEzC;;;;;;;GAOG;AACH,MAAM,WAAW,aAAc,SAAQ,IAAI,CAAC,wBAAwB,EAAE,mBAAmB,GAAG,gBAAgB,CAAC;IACzG,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,0EAA0E;IAC1E,2BAA2B,CAAC,EAAE,2BAA2B,CAAC;CAC7D;AAED,MAAM,WAAW,gBAAgB;IAAG,cAAc,EAAE,CAAC,gBAAgB,CAAC,CAAA;CAAE;AACxE,MAAM,MAAM,cAAc,GAAG,UAAU,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAG5D,MAAM,WAAW,kBAAkB,CAAC,QAAQ,SAAS,UAAU,GAAG,UAAU,CACxE,SAAQ,sBAAsB,CAC1B,OAAO,UAAU,EACjB,OAAO,EACP,QAAQ,EACR,oBAAoB,EACpB,QAAQ,CACX;CAAG;AACR,MAAM,WAAW,gBAAiB,SAAQ,OAAO,CAAC,IAAI,CAAC,aAAa,CAAC,WAAW,EAAE,aAAa,EAAE,YAAY,EAAE,EAAE,EAAE,OAAO,CAAC,EAAE,eAAe,CAAC,CAAC;IAC1I,aAAa,CAAC,EAAE,aAAa,CAAC;CACjC;AAED,MAAM,WAAW,OAAQ,SAAQ,WAAW,CAAC,kBAAkB,EAAE,cAAc,CAAC;CAAG;AACnF,MAAM,WAAW,iBAAkB,SAAQ,qBAAqB,CAAC,aAAa,CAAC,kBAAkB,CAAC,CAAC;IAC/F,CAAC,GAAG,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CACnD;AACD,MAAM,WAAW,iBAAkB,SAAQ,qBAAqB,CAAC,kBAAkB,EAAE,gBAAgB,CAAC;IAClG,aAAa,CAAC,EAAE,gBAAgB,CAAC;IACjC,cAAc,CAAC,EAAE,iBAAiB,CAAC;CACtC;AAGD,MAAM,CAAC,OAAO,OAAO,OAAQ,SAAQ,cAAc,CAC/C,gBAAgB,EAChB,aAAa,EACb,kBAAkB,CACrB;IAGO,OAAO,CAAC,QAAQ,CAAC,cAAc;aACb,MAAM;gBADP,cAAc,GAAE,iBAAsB,EACrC,MAAM,gBAAkC;cA8NrC,kBAAkB,CAAC,eAAe,EAAE,kBAAkB,EAAE,WAAW,EAAE,WAAW,GAAG,OAAO,CAAC,GAAG,CAAC;CAK3H;AAED,MAAM,MAAM,SAAS,CACjB,OAAO,SAAS,kBAAkB,GAAG,kBAAkB,IACvD,aAAa,CAAC,OAAO,CAAC,CAAC;AAE3B,wBAAgB,eAAe,CAC3B,OAAO,SAAS,kBAAkB,GAAG,kBAAkB,EACzD,MAAM,CAAC,EAAE,YAAY,CAAC,OAAO,EAAE,UAAU,CAAC,GAAG,SAAS,CAAC,OAAO,CAAC,CAEhE"}

package/dist/crawler.js

@@ -1,6 +1,6 @@
-import { BrowserCrawler, Configuration, Router } from 'crawlee';
-import CDPBrowserPlugin from './browser-plugin.js';
-import { CdpLauncher } from './launcher-wrap.js';
+import { BrowserCrawler, Configuration, log, Router } from 'crawlee';
+import CDPBrowserPlugin, { CdpLauncher } from './browser-plugin.js';
+import { describeOsConflict } from './fingerprinting/os-consistency.js';
 // Implement the Crawler class with proper typing
 export default class Crawler extends BrowserCrawler {
     constructor(
@@ -24,12 +24,161 @@ export default class Crawler extends BrowserCrawler {
             launchContext.launchOptions ?? (launchContext.launchOptions = {});
             launchContext.launchOptions.headless = headless;
         }
+        // ── Option-surface guidance (issue #80) ──────────────────────────────
+        // The `launchOptions.fingerprintOptions` (spoof-enforcement) bag and
+        // Crawlee's `browserPoolOptions.fingerprintOptions` (identity-generation)
+        // bag are separate concepts that share a name. Two silent foot-guns are
+        // surfaced here as one-time warnings; the canonical unification (single
+        // OS home + a renamed, non-colliding enforcement bag) lands in 1.0.0.
+        const fpOpts = launchContext.launchOptions?.fingerprintOptions;
+        const stealthEngine = launchContext.launchOptions?.stealth?.engine;
+        // The canonical `stealth` union is configured. Per issue #80, `stealth`
+        // wins when both it and a deprecated alias are set, so we suppress the
+        // deprecation notices below to avoid nagging callers already on canonical.
+        const stealthConfigured = stealthEngine === 'js' || stealthEngine === 'native';
+        const nativeStealthIntent = stealthEngine === 'native'
+            || (stealthEngine !== 'js' && Boolean(launchContext.launchOptions?.useNativeStealth
+                || fpOpts?.useNativeStealth
+                || launchContext?.useNativeStealth));
+        if (fpOpts) {
+            // 1. The JS spoof toggles are deprecated in favor of the canonical
+            //    `stealth = { engine: 'js', overrides }` union (issue #80).
+            const JS_ONLY_KNOBS = [
+                'spoofWebGL', 'spoofAudioContext', 'spoofClientRects',
+                'spoofFonts', 'spoofPerformance', 'bypassCDPDetection',
+                'maskAutomationFlags',
+            ];
+            const setJsKnobs = JS_ONLY_KNOBS.filter(k => fpOpts[k] !== undefined);
+            if (setJsKnobs.length) {
+                if (nativeStealthIntent) {
+                    // Under native stealth the JS override pipeline is skipped
+                    // entirely (the C++ anti-detect binary owns these surfaces),
+                    // so these toggles have no effect - a common source of confusion.
+                    log.warning(`[CDPCrawler] native stealth is enabled, so these launchOptions.fingerprintOptions `
+                        + `toggles are ignored - the anti-detect binary owns those surfaces via its C++ `
+                        + `source-tree edits: ${setJsKnobs.join(', ')}. See issue #80.`);
+                }
+                else if (!stealthConfigured) {
+                    log.deprecated(`[CDPCrawler] launchOptions.fingerprintOptions.{${setJsKnobs.join(', ')}} `
+                        + 'is deprecated and will be removed in 1.0.0 in favor of '
+                        + "launchOptions.stealth = { engine: 'js', overrides: { ... } } (issue #80).");
+                }
+            }
+            // 2. `fingerprintOptions.platform` is a second OS home that duplicates
+            //    (and can contradict) fingerprintGeneratorOptions.operatingSystems.
+            //    It still works today; the single OS source lands in 1.0.0.
+            if (fpOpts.platform !== undefined) {
+                log.deprecated('[CDPCrawler] launchOptions.fingerprintOptions.platform is deprecated and will be removed in '
+                    + '1.0.0 in favor of a single OS source, browserPoolOptions.fingerprintOptions.'
+                    + 'fingerprintGeneratorOptions.operatingSystems (issue #80).');
+            }
+        }
+        // 3. The `useNativeStealth` boolean (at either launchOptions,
+        //    fingerprintOptions, or launchContext level) is deprecated in favor
+        //    of the canonical `stealth` union (issue #80). Suppressed when the
+        //    caller is already on canonical `stealth` (which wins when both set).
+        const useNativeStealthSet = launchContext.launchOptions?.useNativeStealth !== undefined
+            || fpOpts?.useNativeStealth !== undefined
+            || launchContext?.useNativeStealth !== undefined;
+        if (useNativeStealthSet && !stealthConfigured) {
+            log.deprecated('[CDPCrawler] useNativeStealth is deprecated and will be removed in 1.0.0 in favor of '
+                + "launchOptions.stealth = { engine: 'native' } (issue #80).");
+        }
         // Pass fingerprintGeneratorOptions from browserPoolOptions to launchContext
-        // This ensures the browser controller can regenerate fingerprints with correct OS/locale settings
-        const fingerprintGeneratorOptions = poolOptions?.fingerprintOptions?.fingerprintGeneratorOptions;
-        if (fingerprintGeneratorOptions) {
-            launchContext.launchOptions ?? (launchContext.launchOptions = {});
-            launchContext.launchOptions.fingerprintGeneratorOptions = fingerprintGeneratorOptions;
+        // This ensures the browser controller can regenerate fingerprints with correct OS/locale settings.
+        //
+        // Default-OS policy: when the caller hasn't pinned operatingSystems, lock the
+        // fingerprint sampler to the host OS we're actually running on. Without this,
+        // Crawlee's internal FingerprintGenerator draws from the union of macos/linux/
+        // windows samples and (e.g.) a Mac dev box ends up shipping Windows profiles
+        // ~33% of the time - every Worker probe then reports D3D11/AMD GPU against a
+        // host that actually has Metal/Apple Silicon, which is an instant
+        // cross-process consistency tell. Pinning to the host OS keeps the entire
+        // observable stack coherent (UA, UA-CH platform, WEBGL renderer, Worker GPU,
+        // CPU class) without forcing the caller to remember to pass it. Callers can
+        // still override by passing browserPoolOptions.fingerprintOptions.
+        // fingerprintGeneratorOptions.operatingSystems explicitly.
+        //
+        // Kill-switch: when the caller sets `useFingerprints: false` on
+        // browserPoolOptions, Crawlee's internal fingerprint pipeline is
+        // disabled - and so is cdp-crawler's consumption of
+        // `browserPoolOptions.fingerprintOptions.fingerprintGeneratorOptions`.
+        // In that mode `operatingSystems` (the single source of truth, issue
+        // #80) has nothing to drive, so a warning below tells the caller to keep
+        // fingerprints enabled if they need OS pinning. The deprecated
+        // `fingerprintOptions.platform` knob is still honoured downstream as a
+        // fallback until it is removed in 1.0.0.
+        const fingerprintsEnabled = browserPoolOptions.useFingerprints !== false;
+        if (fingerprintsEnabled) {
+            const HOST_OS_MAP = {
+                darwin: 'macos',
+                linux: 'linux',
+                win32: 'windows',
+            };
+            const hostOs = HOST_OS_MAP[process.platform];
+            const callerFingerprintGenOpts = poolOptions?.fingerprintOptions?.fingerprintGeneratorOptions;
+            // Single source of truth (issue #80): `operatingSystems` wins. If the
+            // caller ALSO set the deprecated `fingerprintOptions.platform` and the
+            // two disagree, warn (do not throw) - the resolved OS is derived from
+            // the fingerprint the generator produces for `operatingSystems`.
+            // Only the caller-supplied value triggers this; the host-OS auto-fill
+            // a few lines below is internal policy, not user intent.
+            const osConflict = describeOsConflict(callerFingerprintGenOpts?.operatingSystems?.[0], launchContext.launchOptions?.fingerprintOptions?.platform);
+            if (osConflict)
+                log.warning(osConflict);
+            const resolvedFingerprintGenOpts = {
+                ...(callerFingerprintGenOpts ?? {}),
+            };
+            if (!resolvedFingerprintGenOpts.operatingSystems?.length) {
+                // Derive auto-fill OS from the explicit `platform` pin first; fall
+                // back to the host OS only when no platform was set. This keeps the
+                // auto-fill from contradicting an explicit user platform pin (e.g.
+                // a Mac dev with `platform: 'Linux x86_64'` for testing should not
+                // get operatingSystems auto-filled to ['macos']).
+                const PLATFORM_TO_OS = {
+                    'MacIntel': 'macos',
+                    'Win32': 'windows',
+                    'Linux x86_64': 'linux',
+                };
+                const platformPin = launchContext.launchOptions?.fingerprintOptions?.platform;
+                const derivedOs = PLATFORM_TO_OS[platformPin] ?? hostOs;
+                if (derivedOs) {
+                    resolvedFingerprintGenOpts.operatingSystems = [derivedOs];
+                }
+            }
+            if (resolvedFingerprintGenOpts.operatingSystems?.length) {
+                launchContext.launchOptions ?? (launchContext.launchOptions = {});
+                launchContext.launchOptions.fingerprintGeneratorOptions = resolvedFingerprintGenOpts;
+                // Assign the resolved OS onto our OWN `browserPoolOptions` copy only -
+                // this is the single bag Crawlee's internal FingerprintGenerator reads
+                // (browserPoolOptions.fingerprintOptions.fingerprintGeneratorOptions).
+                // We deliberately do NOT mutate the caller's `poolOptions` object:
+                // options resolve into config we own, never in-place edits of caller
+                // input (issue #80). `browserPoolOptions` was shallow-spread from
+                // `poolOptions`, so replacing its `fingerprintOptions` reference here
+                // leaves the caller's object untouched.
+                browserPoolOptions.fingerprintOptions = {
+                    ...(poolOptions.fingerprintOptions ?? {}),
+                    fingerprintGeneratorOptions: {
+                        ...(poolOptions.fingerprintOptions?.fingerprintGeneratorOptions ?? {}),
+                        operatingSystems: resolvedFingerprintGenOpts.operatingSystems,
+                    },
+                };
+            }
+        }
+        else {
+            // useFingerprints: false → cdp-crawler ignores
+            // browserPoolOptions.fingerprintOptions entirely. Surface a loud
+            // warning if the caller still has non-trivial settings there, so
+            // they don't spend hours wondering why their `operatingSystems`
+            // hint isn't taking effect.
+            const stale = poolOptions?.fingerprintOptions?.fingerprintGeneratorOptions;
+            if (stale && (stale.operatingSystems?.length || stale.locales?.length || stale.devices?.length || stale.browsers?.length)) {
+                log.warning('[CDPCrawler] `browserPoolOptions.fingerprintOptions.fingerprintGeneratorOptions` is set but `useFingerprints: false` - '
+                    + "Crawlee's fingerprint pipeline is disabled, so this setting is ignored. "
+                    + 'To pin the session OS, keep `useFingerprints` enabled and set '
+                    + '`fingerprintGeneratorOptions.operatingSystems`, the single source of truth for OS (issue #80).');
+            }
         }
         // Pass only launchOptions (not the whole launchContext) so CDPBrowserPlugin stores
         // executablePath, useNativeStealth, etc. at the right level.

package/dist/crawler.js.map

@@ -1 +1 @@
-{"version":3,"file":"crawler.js","sourceRoot":"","sources":["../src/crawler.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAGhE,OAAO,gBAAgB,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,WAAW,EAAqB,MAAM,oBAAoB,CAAC;AA+HpE,iDAAiD;AACjD,MAAM,CAAC,OAAO,OAAO,OAAQ,SAAQ,cAIpC;IACG;IACI,6BAA6B;IACZ,iBAAoC,EAAE,EACrC,SAAS,aAAa,CAAC,eAAe,EAAE;QAE1D,MAAM,EACF,aAAa,GAAG,EAAsB,EACtC,QAAQ,GAAG,KAAK,EAChB,kBAAkB,EAAE,WAAW,GAAG,EAAE,EACpC,GAAG,qBAAqB,EAC3B,GAAG,cAAc,CAAC;QAEnB,MAAM,kBAAkB,GAAG;YACvB,GAAG,WAAW;YACd,wDAAwD;YACxD,sBAAsB,EAAE,WAAW,CAAC,sBAAsB,IAAI,CAAC;YAC/D,oBAAoB,EAAE,WAAW,CAAC,oBAAoB,IAAI,GAAG;SAChE,CAAC;QAEF,IAAI,aAAa,CAAC,QAAQ,EAAE,CAAC;YACzB,MAAM,IAAI,KAAK,CAAC,4GAA4G,CAAC,CAAC;QAClI,CAAC;QAED,yDAAyD;QACzD,IAAI,kBAAkB,CAAC,cAAc,EAAE,CAAC;YACpC,MAAM,IAAI,KAAK,CAAC,sFAAsF,CAAC,CAAC;QAC5G,CAAC;QAED,IAAI,QAAQ,IAAI,IAAI,EAAE,CAAC;YACnB,aAAa,CAAC,aAAa,KAA3B,aAAa,CAAC,aAAa,GAAK,EAAE,EAAC;YACnC,aAAa,CAAC,aAAa,CAAC,QAAQ,GAAG,QAAmB,CAAC;QAC/D,CAAC;QAED,4EAA4E;QAC5E,kGAAkG;QAClG,MAAM,2BAA2B,GAAI,WAAmB,EAAE,kBAAkB,EAAE,2BAA2B,CAAC;QAC1G,IAAI,2BAA2B,EAAE,CAAC;YAC9B,aAAa,CAAC,aAAa,KAA3B,aAAa,CAAC,aAAa,GAAK,EAAE,EAAC;YAClC,aAAa,CAAC,aAAqB,CAAC,2BAA2B,GAAG,2BAA2B,CAAC;QACnG,CAAC;QAED,mFAAmF;QACnF,6DAA6D;QAC7D,gFAAgF;QAChF,+EAA+E;QAC/E,kBAAkB,CAAC,cAAc,GAAG;YAChC,IAAI,gBAAgB,CAAC,IAAI,WAAW,EAAE,EAAE,aAAa,CAAC,aAAoB,CAAC;SAC9E,CAAC;QAEF,kEAAkE;QAClE,kDAAkD;QAClD,IAAI;QAEJ,8DAA8D;QAC9D,SAAS;QACT,KAAK,CAAC,EAAE,GAAG,qBAAqB,EAAE,aAAa,EAAE,kBAAkB,EAAE,EAAE,MAAM,CAAC,CAAC;QArD/E;;;;mBAAiB,cAAc;WAAwB;QACvD;;;;mBAAkB,MAAM;WAAkC;IAqD9D,CAAC;IAED,wEAAwE;IACrD,KAAK,CAAC,kBAAkB,CAAC,eAAmC,EAAE,WAAwB;QACrG,MAAM,EAAE,IAAI,EAAE,GAAG,eAAe,CAAC;QAEjC,OAAO,IAAI,CAAC,IAAI,CAAC,eAAe,CAAC,OAAO,CAAC,GAAG,EAAE,WAAW,CAAC,CAAC,CAAC,yBAAyB;IACzF,CAAC;CACJ;AAMD,MAAM,UAAU,eAAe,CAE7B,MAA0C;IACxC,OAAO,MAAM,CAAC,MAAM,CAAU,MAAM,CAAC,CAAC;AAC1C,CAAC"}
+{"version":3,"file":"crawler.js","sourceRoot":"","sources":["../src/crawler.ts"],"names":[],"mappings":"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"}

package/dist/fingerprinting/fingerprint-injector.d.ts

@@ -62,107 +62,10 @@
  */
 import type { BrowserFingerprintWithHeaders } from 'fingerprint-generator';
 import type CdpPage from "../page.js";
-import type { ResolvedLocale } from './locale-resolver.js';
-interface Viewport {
-    width: number;
-    height: number;
-    deviceScaleFactor: number;
-    mobile: boolean;
-}
-/**
- * Humanization options for simulating realistic user behavior
- * All options are disabled by default for performance
- */
-interface HumanizationOptions {
-    /** Enable mouse movement humanization (Bezier curves, natural movement). Default: false */
-    mouse?: boolean;
-    /** Enable keyboard humanization (realistic typing delays). Default: false */
-    keyboard?: boolean;
-    /** Enable scroll humanization (natural physics, momentum). Default: false */
-    scroll?: boolean;
-}
-interface AttachOptions {
-    debug?: boolean;
-    timezone?: string;
-    proxyUrl?: string;
-    detectTimezone?: boolean;
-    viewport?: Viewport;
-    enableAdvancedStealth?: boolean;
-    bypassRuntimeEnable?: boolean;
-    /** @deprecated Use humanization.mouse instead */
-    humanizeInteractions?: boolean;
-    spoofWebGL?: boolean;
-    spoofAudioContext?: boolean;
-    spoofClientRects?: boolean;
-    maskAutomationFlags?: boolean;
-    platform?: 'Win32' | 'MacIntel' | 'Linux x86_64';
-    spoofFonts?: boolean;
-    spoofPerformance?: boolean;
-    spoofLocale?: boolean;
-    useExperimentalFingerprints?: boolean;
-    useFingerprintDefaults?: boolean;
-    /** Enable CDP detection bypass (iframe, eval, sourceURL hiding) */
-    bypassCDPDetection?: boolean;
-    /** Enable storage API consistency (quota, IndexedDB, CacheStorage) */
-    spoofStorage?: boolean;
-    /** Enable timing consistency (Date.now, performance.now alignment) */
-    spoofTiming?: boolean;
-    /** Enable DataDome-specific bypass (JS challenges, proof-of-work) */
-    enableDataDomeBypass?: boolean;
-    /** WebRTC handling strategy. Default: 'spoof'. */
-    webRtcPolicy?: 'spoof' | 'disable';
-    /**
-     * Alias for enableDataDomeBypass - enables all DataDome-specific protections
-     * When true, injects enhanced bypass early in the script chain
-     */
-    bypassDatadome?: boolean;
-    /**
-     * Humanization options for simulating realistic user behavior.
-     * All options are disabled by default for performance.
-     * Enable specific options to simulate human-like interactions.
-     */
-    humanization?: HumanizationOptions;
-    /**
-     * When true, fingerprint was generated by the non-Apify real-device generator.
-     * Currently informational only — the injector behaves identically since the output
-     * matches the BrowserFingerprintWithHeaders shape.
-     */
-    useNonApifyFingerprints?: boolean;
-    /**
-     * Pre-resolved locale triple. When provided, drives CDP Emulation.setLocaleOverride,
-     * Emulation.setTimezoneOverride, Accept-Language header, and the locale-spoofing
-     * script's baked-in values. Supersedes any legacy `timezone`/`detectTimezone` logic:
-     * if resolvedLocale.timezone is set, we skip the ipinfo.io round-trip.
-     */
-    resolvedLocale?: ResolvedLocale;
-    /**
-     * Completely disable all JS fingerprint overrides when the C++ anti-detect browser
-     * is in use. Set this to true when launching with the custom Cromite-based anti-detect
-     * browser (useNativeStealth in LaunchBrowserOptions).
-     *
-     * When true, the ENTIRE JS override pipeline is skipped — no fingerprint scripts are
-     * injected via addScriptToEvaluateOnNewDocument. The C++ patches handle everything:
-     *   - canvas noise (patch 0009 + cromite-override 0002)
-     *   - audio fingerprinting (patch 0010)
-     *   - getBoundingClientRect noise (patch 0011)
-     *   - WebGL vendor/renderer (patch 0004)
-     *   - WebGPU adapter info (patch 0012)
-     *   - screen dimensions (patch 0006)
-     *   - navigator.platform (patch 0002)
-     *   - UA-CH structured data + HTTP headers (patch 0003)
-     *   - navigator.webdriver = false (patch 0001)
-     *   - CDP automation artifacts (patch 0005)
-     *   - Runtime.enable console side effects (patch 0015)
-     *   - automation sourceURL in Error stacks (patch 0015)
-     *
-     * Exception: humanization scripts (mouse/keyboard/scroll movement) are behavioral
-     * rather than fingerprinting — they are still injected if explicitly enabled via
-     * the `humanization` option.
-     *
-     * Default: false
-     */
-    useNativeStealth?: boolean;
-}
+import { type AttachOptions } from './injection-planner.js';
+export type { AttachOptions, HumanizationOptions, Viewport } from './injection-planner.js';
+/** Test-only: drop the process-level runtime caches so runs start fresh. */
+export declare function resetInjectorRuntimeCachesForTesting(): void;
 export declare class CdpFingerprintInjector {
     private page;
     constructor(page: CdpPage);
@@ -191,31 +94,38 @@ export declare class CdpFingerprintInjector {
      */
     private setUserAgentWithMetadata;
     private getTimezoneFromIp;
+    private fetchTimezoneFromIp;
     private setTimezoneOverride;
     /**
      * Override ICU's default locale for the page via CDP. This makes Intl.DateTimeFormat,
      * Intl.NumberFormat, and Date.toLocaleString default to the supplied locale regardless
-     * of the browser binary's --lang setting — our reliable knob for the stock-Chrome path
+     * of the browser binary's --lang setting - our reliable knob for the stock-Chrome path
      * where we don't control the startup args.
      */
     private setLocaleOverride;
     /**
-     * Create a debug script that logs fingerprint override status to the console
-     */
-    private createDebugScript;
-    /**
-     * Extract relevant data from fingerprint for overrides
+     * Identify the browser process behind this page's CDP connection. The
+     * remote-debugging host:port is unique per Chrome process, so it keys the
+     * per-browser-process version cache without bleeding across processes.
      */
-    private extractFingerprintData;
+    private browserEndpointKey;
     private getActualChromeVersion;
-    private alignUserAgentWithBrowserVersion;
+    private probeActualChromeVersion;
     /**
-     * Align UA-CH brand versions with the actual running Chrome binary version.
-     * Updates "Chromium" and "Google Chrome" brand major/full versions while
-     * preserving the "Not_A Brand" GREASE token from the profile as-is.
+     * Mutate the shared fingerprint's navigator UA surfaces (userAgent, appVersion,
+     * userAgentData brands, and the headers UA) to the real binary version, in
+     * place. This is the SAME object Crawlee/BrowserPool's built-in
+     * FingerprintInjector reads in its postPageCreate hook, so aligning it here
+     * keeps navigator.userAgent, the Sec-CH-UA brands, and the wire User-Agent
+     * header all on the real binary version instead of the generator's (#104).
+     * No-op when the version couldn't be probed or the profile has no UA.
      */
-    private alignUAClientHintsVersion;
+    private alignFingerprintUserAgent;
     attachToPage(browserFingerprintWithHeaders: BrowserFingerprintWithHeaders, options?: AttachOptions): Promise<void>;
+    /**
+     * Apply an InjectionPlan to the page. All CDP traffic for fingerprint
+     * injection happens here; every decision was made in the planner.
+     */
+    private applyPlan;
 }
-export {};
 //# sourceMappingURL=fingerprint-injector.d.ts.map