@webcrawlerapi/stealth 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 WebCrawlerAPI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,235 @@
-# Temporary Holding Version
+# @webcrawlerapi/stealth
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A **zero-dependency** stealth layer for Puppeteer (or any CDP-driven browser).
+It installs anti-detection patches into the page **before any page script runs**,
+so fingerprints are already clean by the time the target's own JS looks at them.
+
+Works with **both** ways of driving Chrome:
+
+- `puppeteer.launch()` — you start the browser
+- `puppeteer.connect()` — you attach to a browser that is already running
+
+The two functions you normally need are:
+
+- **`installStealth(page, opts)`** — patches a page
+- **`installOopifHook(browser, opts)`** — patches sandboxed / out-of-process iframes
+
+## What it patches
+
+| Vector | Patch |
+|--------|-------|
+| `Function.prototype.toString` + anonymous injected globals | native-looking `toString` via a `WeakSet` cloak |
+| `navigator.webdriver` | deleted + faked to `false` |
+| WebDriver / Selenium / Playwright residue (`cdc_*`, `__webdriver_*`, `__selenium_*`, `__pw*`, `__playwright_*`) | removed |
+| `navigator.languages / platform / hardwareConcurrency / deviceMemory / vendor / onLine` | normalized |
+| `window.chrome` (`runtime`, `loadTimes`, `csi`, `app`) | faked when missing |
+| `navigator.userAgentData` (`brands`, `getHighEntropyValues`) | faked |
+| `navigator.plugins` / `mimeTypes` (when empty) | faked |
+| `navigator.permissions.query` | notifications → `default` |
+| WebGL `UNMASKED_VENDOR_WEBGL` / `UNMASKED_RENDERER_WEBGL` | spoofed (hides SwiftShader / software GL) |
+| `matchMedia` pointer / hover | normalized |
+| `window.outerWidth` / `outerHeight` | corrected to inner + chrome |
+| `Error.prepareStackTrace` | installed if absent |
+
+---
+
+## Install (without npm)
+
+There is nothing to fetch from the npm registry — the whole module is a single
+dependency-free file. Use whichever fits:
+
+### Option 1 — clone the repo
+
+```sh
+git clone https://github.com/WebCrawlerAPI/stealth.git
+cp stealth/stealth.js /your/project/
+```
+
+### Option 2 — single-file download
+
+```sh
+# install.sh ships with the repo
+GH_TOKEN=ghp_xxx sh install.sh            # writes ./stealth.js
+
+# or, by hand (the repo is private → token required)
+curl -fsSL \
+  -H "Authorization: Bearer $GH_TOKEN" \
+  -H "Accept: application/vnd.github.raw" \
+  "https://api.github.com/repos/WebCrawlerAPI/stealth/contents/stealth.js?ref=main" \
+  -o stealth.js
+```
+
+Then:
+
+```js
+const stealth = require('./stealth.js');
+```
+
+No `npm install`, no transitive dependencies. (A `package.json` is included for
+projects that *do* use npm, but it declares **no dependencies**.)
+
+---
+
+## Quick start
+
+```js
+const stealth = require('./stealth.js');
+
+const browser = await /* your browser */;
+const page = await browser.newPage();
+
+await stealth.installStealth(page, {});   // 1. register patches (BEFORE goto)
+stealth.installOopifHook(browser, {});    // 2. patch sandboxed iframes too
+
+await page.goto(url);                     // 3. navigate
+```
+
+> Order matters: `installStealth` uses `page.evaluateOnNewDocument`, so it must
+> run **before** the navigation you want patched.
+
+---
+
+## Usage with `launch()`
+
+If you start the browser yourself, use the bundled helper (it needs puppeteer —
+pass it in or have it resolvable):
+
+```js
+const puppeteer = require('puppeteer-core');
+const stealth = require('./stealth.js');
+
+const browser = await stealth.launch({
+  puppeteer,                              // or it is required lazily
+  executablePath: '/usr/bin/google-chrome',
+  headless: false,
+  userDataDir: '/tmp/my-profile',         // use a FRESH profile
+});
+
+const page = await stealth.newPage(browser, { origin: 'https://example.com' });
+await page.goto('https://example.com');
+```
+
+`newPage()` is shorthand for `browser.newPage()` + `installStealth()` +
+`installOopifHook()`.
+
+## Usage with `connect()`
+
+This is the case when you attach to an already-running browser (e.g. one started
+with `--remote-debugging-port=9222`, or a browser on a server / remote desktop):
+
+```js
+const puppeteer = require('puppeteer-core');
+const stealth = require('./stealth.js');
+
+const browser = await puppeteer.connect({
+  browserURL: 'http://127.0.0.1:9222',    // or browserWSEndpoint: 'ws://...'
+});
+
+const page = await browser.newPage();
+await stealth.installStealth(page, {});   // MUST run before goto()
+stealth.installOopifHook(browser, {});
+
+await page.goto('https://example.com');
+// ...do work...
+await page.close();
+browser.disconnect();                     // do NOT close() a browser you didn't start
+```
+
+### If the page is already loaded
+
+`installStealth()` only affects **future** documents. When you attach to a page
+that is already on the target URL, also patch the current document and reload:
+
+```js
+await stealth.installStealth(page, {});   // future navigations
+await stealth.injectNow(page);            // current document
+await page.reload({ waitUntil: 'domcontentloaded' });
+```
+
+---
+
+## API
+
+### `await installStealth(page, opts?)`
+Registers the bootstrap for every document the page loads from now on.
+Must be called **before** the navigation you want patched.
+Returns the page.
+
+### `installOopifHook(browser, opts?)`
+Hooks `targetcreated` and injects the bootstrap into out-of-process / sandboxed
+iframes (which get their own CDP target and are **not** covered by
+page-level `evaluateOnNewDocument`). Idempotent. Returns the browser.
+
+### `await injectNow(page, opts?)`
+Runs the bootstrap in the page's **current** document. Use after `connect()`
+when the page is already loaded, then reload.
+
+### `await newPage(browser, opts?)`
+`browser.newPage()` + `installStealth` + `installOopifHook`.
+
+### `buildSource(opts?)`
+Returns the bootstrap as a **string** — handy for a raw CDP call:
+
+```js
+await session.send('Page.addScriptToEvaluateOnNewDocument', {
+  source: stealth.buildSource({}),
+  runImmediately: true,
+});
+```
+
+### `await humanMouse(page, points)`
+Tiny human-ish mouse helper: `[{ x, y, steps?, click?, delay? }, ...]`.
+
+### `await launch(opts?)`
+Optional launcher. Requires puppeteer via `opts.puppeteer` or resolved lazily
+(`puppeteer-core`, then `puppeteer`). Never touched unless you call it.
+
+## Options (`opts`)
+
+| Key | Default | Used by |
+|-----|---------|---------|
+| `webglRenderer` / `renderer` | `ANGLE (Intel, ...)` | all |
+| `webglVendor` / `vendor` | `Google Inc. (Intel)` | all |
+| `hardwareConcurrency` | `8` | all |
+| `deviceMemory` | `8` | all |
+| `platform` | `Linux x86_64` | all |
+| `origin` / `permissions` | — | `newPage` |
+| `puppeteer` | lazily resolved | `launch` |
+| `executablePath` | `$CHROME_PATH` | `launch` |
+| `headless` | `false` | `launch` |
+| `userDataDir` | `~/.cache/chrome-stealth-profile` | `launch` |
+| `args` | `[]` | `launch` |
+
+---
+
+## Verify it is working
+
+```js
+await stealth.installStealth(page, {});
+await page.goto('about:blank');
+console.log(await page.evaluate(() => {
+  const c = document.createElement('canvas').getContext('webgl');
+  const e = c.getExtension('WEBGL_debug_renderer_info');
+  return {
+    webdriver: navigator.webdriver,                          // false
+    plugins: navigator.plugins.length,                        // > 0
+    gl: [c.getParameter(e.UNMASKED_VENDOR_WEBGL)],            // not "SwiftShader"
+  };
+}));
+```
+
+## Troubleshooting
+
+- **Still detected after `connect()`** — you probably called `goto()` before
+  `installStealth()`. Install first, then navigate (or use `injectNow()` + reload).
+- **Fresh vs reused profile** — a persistent profile can carry a *stale, already
+  flagged* cookie for the target. Test with a brand-new `userDataDir` to rule
+  that out.
+- **Software WebGL** — servers with no GPU report SwiftShader. The WebGL patch
+  hides this in the page, but make sure `installStealth` actually ran.
+- **Sandboxed iframes** — if the challenge runs in a `<iframe sandbox>`, make
+  sure `installOopifHook(browser)` was called.
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,40 @@
 {
   "name": "@webcrawlerapi/stealth",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Zero-dependency stealth layer for Puppeteer / CDP browsers (works with launch() and connect()).",
+  "main": "stealth.js",
+  "types": "stealth.d.ts",
+  "files": [
+    "stealth.js",
+    "stealth.d.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "example:connect": "node examples/connect.js",
+    "example:launch": "node examples/launch.js"
+  },
+  "engines": {
+    "node": ">=16"
+  },
+  "peerDependencies": {
+    "puppeteer": ">=19",
+    "puppeteer-core": ">=19"
+  },
+  "peerDependenciesMeta": {
+    "puppeteer": {
+      "optional": true
+    },
+    "puppeteer-core": {
+      "optional": true
+    }
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/WebCrawlerAPI/stealth.git"
+  }
+}

package/stealth.d.ts

@@ -0,0 +1,55 @@
+export interface StealthOptions {
+  /** WebGL UNMASKED_RENDERER_WEBGL value to report. */
+  webglRenderer?: string;
+  /** WebGL UNMASKED_VENDOR_WEBGL value to report. */
+  webglVendor?: string;
+  /** navigator.hardwareConcurrency override. */
+  hardwareConcurrency?: number;
+  /** navigator.deviceMemory override. */
+  deviceMemory?: number;
+  /** navigator.platform override. */
+  platform?: string;
+  /** Launch only: injected puppeteer instance. */
+  puppeteer?: unknown;
+  /** Launch only: chrome executable. */
+  executablePath?: string;
+  /** Launch only. */
+  headless?: boolean;
+  /** Launch only: profile dir. */
+  userDataDir?: string;
+  /** Launch only: extra chrome args. */
+  args?: string[];
+  /** newPage only: origin for overridePermissions. */
+  origin?: string;
+  /** newPage only: permissions to grant. */
+  permissions?: string[];
+}
+
+/** Minimal structural types so the module has no puppeteer dependency. */
+export interface PageLike {
+  evaluateOnNewDocument(fn: unknown, arg?: unknown): Promise<unknown>;
+  evaluate(fnOrSource: unknown): Promise<unknown>;
+  mouse: {
+    move(x: number, y: number, opts?: { steps?: number }): Promise<void>;
+    down(): Promise<void>;
+    up(): Promise<void>;
+  };
+}
+
+export interface BrowserLike {
+  on(event: string, listener: (target: any) => void): unknown;
+  newPage(): Promise<PageLike>;
+  defaultBrowserContext?(): { overridePermissions(origin: string, permissions: string[]): Promise<void> };
+}
+
+export declare const VERSION: string;
+export declare const UA: string;
+export declare function buildInitScript(cfg?: StealthOptions): void;
+export declare function buildSource(opts?: StealthOptions): string;
+export declare function installStealth(page: PageLike, opts?: StealthOptions): Promise<PageLike>;
+export declare function injectNow(page: PageLike, opts?: StealthOptions): Promise<PageLike>;
+export declare function installOopifHook(browser: BrowserLike, opts?: StealthOptions): BrowserLike;
+export declare function newPage(browser: BrowserLike, opts?: StealthOptions): Promise<PageLike>;
+export declare function humanMouse(page: PageLike, points: Array<{ x: number; y: number; steps?: number; click?: boolean; delay?: number }>): Promise<void>;
+export declare function getPuppeteer(injected?: unknown): any;
+export declare function launch(opts?: StealthOptions): Promise<BrowserLike>;

package/stealth.js

@@ -0,0 +1,477 @@
+'use strict';
+
+/**
+ * @webcrawlerapi/stealth
+ * Zero-dependency stealth layer for Puppeteer / any CDP-driven browser.
+ *
+ * Works with BOTH puppeteer.launch() and puppeteer.connect():
+ *
+ *   const stealth = require('./stealth.js');
+ *   const page = await browser.newPage();      // or reuse an existing page
+ *   await stealth.installStealth(page, {});    // BEFORE any goto()
+ *   stealth.installOopifHook(browser, {});     // patches sandboxed iframes too
+ *   await page.goto(url);
+ *
+ * There are no runtime dependencies. Puppeteer is only required if you use
+ * the optional `launch()` helper, and even then it is looked up lazily or can
+ * be injected via `opts.puppeteer`.
+ */
+
+const UA =
+  'Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 ' +
+  '(KHTML, like Gecko) Chrome/151.0.0.0 Safari/537.36';
+
+const VERSION = '1.0.0';
+
+const DEFAULT_RENDERER =
+  'ANGLE (Intel, Intel(R) UHD Graphics 630 (0x00003E9B) Direct3D11 vs_5_0 ps_5_0, D3D11)';
+const DEFAULT_VENDOR = 'Google Inc. (Intel)';
+
+/* ------------------------------------------------------------------ *
+ * The in-page bootstrap. Runs inside every document before page JS.  *
+ * Serialized by evaluateOnNewDocument() / addScriptToEvaluateOnNewDocument()
+ * so it must be fully self-contained (no closure over this module).
+ * ------------------------------------------------------------------ */
+function buildInitScript(cfg) {
+  cfg = cfg || {};
+  const renderer = cfg.renderer || 'ANGLE (Intel, Intel(R) UHD Graphics 630 (0x00003E9B) Direct3D11 vs_5_0 ps_5_0, D3D11)';
+  const vendor = cfg.vendor || 'Google Inc. (Intel)';
+
+  const patched = new WeakSet();
+
+  try { Object.defineProperty(window, '__stealth_ts', { value: Date.now(), configurable: true }); } catch (_) {}
+
+  // --- native-looking Function.prototype.toString ---
+  const origToString = Function.prototype.toString;
+  const fakeToString = function toString() {
+    if (patched.has(this)) {
+      const name = (this && this.name) || '';
+      return 'function ' + name + '() { [native code] }';
+    }
+    return origToString.call(this);
+  };
+  patched.add(fakeToString);
+  try { Object.defineProperty(fakeToString, 'name', { value: 'toString' }); } catch (_) {}
+  try { Object.defineProperty(fakeToString, 'length', { value: 0 }); } catch (_) {}
+  Object.defineProperty(Function.prototype, 'toString', {
+    value: fakeToString,
+    writable: true,
+    configurable: true,
+  });
+
+  function cloak(fn, name) {
+    if (typeof fn !== 'function') return fn;
+    patched.add(fn);
+    try {
+      if (name) Object.defineProperty(fn, 'name', { value: name, configurable: true });
+      Object.defineProperty(fn, 'length', { value: fn.length, configurable: true });
+    } catch (_) {}
+    return fn;
+  }
+
+  function getter(obj, prop, value, name) {
+    const get = cloak(function () { return value; }, 'get ' + (name || prop));
+    Object.defineProperty(obj, prop, {
+      get,
+      set: undefined,
+      enumerable: true,
+      configurable: true,
+    });
+  }
+
+  // --- navigator.webdriver ---
+  try { delete Navigator.prototype.webdriver; } catch (_) {}
+  try { getter(Navigator.prototype, 'webdriver', false, 'webdriver'); } catch (_) {}
+
+  // --- window.chrome ---
+  if (!window.chrome || typeof window.chrome !== 'object') window.chrome = {};
+  if (!window.chrome.runtime) {
+    Object.defineProperty(window.chrome, 'runtime', {
+      value: {
+        connect: cloak(function connect() {}, 'connect'),
+        sendMessage: cloak(function sendMessage() {}, 'sendMessage'),
+        id: undefined,
+      },
+      configurable: true,
+    });
+  }
+  if (!window.chrome.loadTimes) {
+    Object.defineProperty(window.chrome, 'loadTimes', {
+      value: cloak(function loadTimes() {
+        return { requestTime: 0, startLoadTime: 0, commitLoadTime: 0, finishLoadTime: 0, navigationType: 'Other', wasNpnNegotiated: false, npnNegotiatedProtocol: 'unknown', wasAlternateProtocolAvailable: false, connectionInfo: 'unknown' };
+      }, 'loadTimes'),
+      configurable: true,
+    });
+  }
+  if (!window.chrome.csi) {
+    Object.defineProperty(window.chrome, 'csi', {
+      value: cloak(function csi() { return { onloadT: Date.now(), startE: Date.now(), pageT: 1, tran: 15 }; }, 'csi'),
+      configurable: true,
+    });
+  }
+  if (!window.chrome.app) {
+    window.chrome.app = {
+      isInstalled: false,
+      InstallState: { DISABLED: 'disabled', INSTALLED: 'installed', NOT_INSTALLED: 'not_installed' },
+      RunningState: { CANNOT_RUN: 'cannot_run', READY_TO_RUN: 'ready_to_run', RUNNING: 'running' },
+    };
+  }
+
+  // --- navigator.languages / language ---
+  try { getter(Navigator.prototype, 'languages', Object.freeze(['en-US', 'en']), 'languages'); } catch (_) {}
+  try { getter(Navigator.prototype, 'language', 'en-US', 'language'); } catch (_) {}
+
+  // --- hardware / platform ---
+  try { getter(Navigator.prototype, 'hardwareConcurrency', cfg.hardwareConcurrency || 8, 'hardwareConcurrency'); } catch (_) {}
+  try { getter(Navigator.prototype, 'deviceMemory', cfg.deviceMemory || 8, 'deviceMemory'); } catch (_) {}
+  try { getter(Navigator.prototype, 'platform', cfg.platform || 'Linux x86_64', 'platform'); } catch (_) {}
+  try { getter(Navigator.prototype, 'maxTouchPoints', 0, 'maxTouchPoints'); } catch (_) {}
+  try { getter(Navigator.prototype, 'vendor', 'Google Inc.', 'vendor'); } catch (_) {}
+  try { getter(Navigator.prototype, 'onLine', true, 'onLine'); } catch (_) {}
+
+  // --- plugins / mimeTypes (only when empty) ---
+  try {
+    if (!navigator.plugins || navigator.plugins.length === 0) {
+      function mkMime(type, suffixes, description) {
+        return { type, suffixes, description, enabledPlugin: null };
+      }
+      const pluginDefs = [
+        { name: 'PDF Viewer', filename: 'internal-pdf-viewer', description: 'Portable Document Format', mimes: [
+          { type: 'application/pdf', suffixes: 'pdf', description: 'Portable Document Format' },
+          { type: 'text/pdf', suffixes: 'pdf', description: 'Portable Document Format' },
+        ]},
+        { name: 'Chrome PDF Viewer', filename: 'internal-pdf-viewer', description: 'Portable Document Format', mimes: [
+          { type: 'application/pdf', suffixes: 'pdf', description: 'Portable Document Format' },
+          { type: 'text/pdf', suffixes: 'pdf', description: 'Portable Document Format' },
+        ]},
+      ];
+      const plugins = [];
+      const mimes = [];
+      for (const p of pluginDefs) {
+        const plugin = { name: p.name, filename: p.filename, description: p.description, length: p.mimes.length };
+        p.mimes.forEach((m, i) => {
+          const mm = mkMime(m.type, m.suffixes, m.description);
+          mm.enabledPlugin = plugin;
+          plugin[i] = mm;
+          if (!mimes.some((x) => x.type === m.type)) mimes.push(mm);
+        });
+        plugins.push(plugin);
+      }
+      plugins.item = cloak(function item(i) { return this[i] || null; }, 'item');
+      plugins.namedItem = cloak(function namedItem() { return null; }, 'namedItem');
+      plugins.refresh = cloak(function refresh() {}, 'refresh');
+      mimes.item = cloak(function item(i) { return this[i] || null; }, 'item');
+      mimes.namedItem = cloak(function namedItem() { return null; }, 'namedItem');
+      Object.defineProperty(plugins, 'length', { value: pluginDefs.length });
+      Object.defineProperty(mimes, 'length', { value: mimes.length });
+      try {
+        const pProto = Object.getPrototypeOf(navigator.plugins);
+        Object.defineProperty(pProto, 'item', { value: cloak(function item(i) { return this[i] || null; }, 'item'), writable: true, configurable: true });
+        Object.defineProperty(pProto, 'namedItem', { value: cloak(function namedItem() { return null; }, 'namedItem'), writable: true, configurable: true });
+        Object.defineProperty(pProto, 'refresh', { value: cloak(function refresh() {}, 'refresh'), writable: true, configurable: true });
+        const mProto = Object.getPrototypeOf(navigator.mimeTypes);
+        Object.defineProperty(mProto, 'item', { value: cloak(function item(i) { return this[i] || null; }, 'item'), writable: true, configurable: true });
+        Object.defineProperty(mProto, 'namedItem', { value: cloak(function namedItem() { return null; }, 'namedItem'), writable: true, configurable: true });
+      } catch (_) {}
+      getter(Navigator.prototype, 'plugins', plugins, 'plugins');
+      getter(Navigator.prototype, 'mimeTypes', mimes, 'mimeTypes');
+    }
+  } catch (_) {}
+
+  // --- permissions ---
+  try {
+    const origQuery = navigator.permissions.query.bind(navigator.permissions);
+    const query = cloak(function query(params) {
+      if (params && params.name === 'notifications') {
+        return Promise.resolve({ state: 'default', name: 'notifications', onchange: null });
+      }
+      return origQuery(params);
+    }, 'query');
+    try {
+      Object.defineProperty(Permissions.prototype, 'query', { value: query, writable: true, configurable: true });
+    } catch (_) {
+      navigator.permissions.query = query;
+    }
+  } catch (_) {}
+
+  // --- userAgentData ---
+  try {
+    const brands = [
+      { brand: 'Chromium', version: '151' },
+      { brand: 'Not?A_Brand', version: '24' },
+      { brand: 'Google Chrome', version: '151' },
+    ];
+    const fullVersionList = brands.map((b) => ({ brand: b.brand, version: b.brand === 'Not?A_Brand' ? '24.0.0.0' : '151.0.7922.108' }));
+    const highEntropy = {
+      architecture: 'x86', bitness: '64', brands, fullVersionList, mobile: false, model: '',
+      platform: 'Linux', platformVersion: '6.8.0', uaFullVersion: '151.0.7922.108', wow64: false,
+    };
+    const data = {
+      brands, mobile: false, platform: 'Linux',
+      getHighEntropyValues: cloak(function getHighEntropyValues(hints) {
+        const out = { brands, mobile: false, platform: 'Linux' };
+        (hints || []).forEach((h) => { if (h in highEntropy) out[h] = highEntropy[h]; });
+        return Promise.resolve(out);
+      }, 'getHighEntropyValues'),
+      toJSON: cloak(function toJSON() { return { brands, mobile: false, platform: 'Linux' }; }, 'toJSON'),
+    };
+    if (navigator.userAgentData) {
+      try {
+        Object.defineProperty(Navigator.prototype, 'userAgentData', { get: cloak(function () { return data; }, 'get userAgentData'), configurable: true });
+      } catch (_) {}
+    } else {
+      getter(Navigator.prototype, 'userAgentData', data, 'userAgentData');
+    }
+  } catch (_) {}
+
+  // --- WebGL vendor / renderer ---
+  try {
+    for (const name of ['WebGLRenderingContext', 'WebGL2RenderingContext']) {
+      const Ctor = window[name];
+      if (!Ctor || !Ctor.prototype) continue;
+      const origGetParameter = Ctor.prototype.getParameter;
+      const origGetExtension = Ctor.prototype.getExtension;
+      const getParameter = cloak(function getParameter(p) {
+        if (p === 37445) return vendor;
+        if (p === 37446) return renderer;
+        return origGetParameter.call(this, p);
+      }, 'getParameter');
+      const getExtension = cloak(function getExtension(n) {
+        if (n === 'WEBGL_debug_renderer_info') {
+          return { UNMASKED_VENDOR_WEBGL: 37445, UNMASKED_RENDERER_WEBGL: 37446 };
+        }
+        return origGetExtension.call(this, n);
+      }, 'getExtension');
+      Object.defineProperty(Ctor.prototype, 'getParameter', { value: getParameter, writable: true, configurable: true });
+      Object.defineProperty(Ctor.prototype, 'getExtension', { value: getExtension, writable: true, configurable: true });
+    }
+  } catch (_) {}
+
+  // --- remove automation residue globals ---
+  try {
+    const keys = [
+      'cdc_adoQpoasnfa76pfcZLmcfl_Array', 'cdc_adoQpoasnfa76pfcZLmcfl_Promise',
+      'cdc_adoQpoasnfa76pfcZLmcfl_Symbol',
+      '__webdriver_evaluate', '__selenium_evaluate', '__fxdriver_evaluate',
+      '__driver_evaluate', '__webdriver_script_function', '__webdriver_script_func',
+      '__webdriver_script_fn', '__webdriverFunc', '_WEBDRIVER_ELEM_CACHE',
+      'domAutomation', 'domAutomationController', '__lastWatirAlert',
+      '__lastWatirConfirm', '__lastWatirPrompt', '__playwright_builtins__',
+      '__pwInitScripts', '__playwright__binding__', '__pwWebSocketDispatch',
+      '__playwright__binding__controller__',
+    ];
+    for (const k of keys) {
+      try {
+        if (k in window) delete window[k];
+        if (k in document) delete document[k];
+      } catch (_) {}
+    }
+    try { if (navigator.webdriver) delete navigator.webdriver; } catch (_) {}
+  } catch (_) {}
+
+  // --- Error.prepareStackTrace integrity ---
+  try {
+    if (typeof Error.prepareStackTrace !== 'function') {
+      Object.defineProperty(Error, 'prepareStackTrace', {
+        value: cloak(function prepareStackTrace(err, stack) {
+          return String(err) + '\n' + stack.map((s) => '    at ' + s.toString()).join('\n');
+        }, 'prepareStackTrace'),
+        writable: true,
+        configurable: true,
+      });
+    }
+  } catch (_) {}
+
+  // --- matchMedia: pointer / hover ---
+  try {
+    const OVERRIDES = {
+      'any-pointer: fine': true, 'any-pointer: coarse': false, 'any-pointer: none': false,
+      'pointer: fine': true, 'pointer: coarse': false, 'pointer: none': false,
+      'any-hover: hover': true, 'any-hover: none': false,
+      'hover: hover': true, 'hover: none': false,
+    };
+    const norm = (q) => String(q).toLowerCase().replace(/\s+/g, ' ').trim().replace(/^\(/, '').replace(/\)$/, '').trim();
+    const orig = window.matchMedia.bind(window);
+    const matchMedia = cloak(function matchMedia(query) {
+      const mql = orig(query);
+      const key = norm(query);
+      if (Object.prototype.hasOwnProperty.call(OVERRIDES, key)) {
+        const val = OVERRIDES[key];
+        try {
+          Object.defineProperty(mql, 'matches', { get: cloak(function () { return val; }, 'get matches'), configurable: true });
+        } catch (_) {}
+      }
+      return mql;
+    }, 'matchMedia');
+    Object.defineProperty(window, 'matchMedia', { value: matchMedia, writable: true, configurable: true });
+  } catch (_) {}
+
+  // --- window geometry drift ---
+  try {
+    const innerH = window.innerHeight || 900;
+    const innerW = window.innerWidth || 1366;
+    getter(window, 'outerHeight', innerH + 20, 'outerHeight');
+    getter(window, 'outerWidth', innerW, 'outerWidth');
+  } catch (_) {}
+}
+
+/* ------------------------------------------------------------------ *
+ * Public API                                                          *
+ * ------------------------------------------------------------------ */
+
+function resolveConfig(opts) {
+  opts = opts || {};
+  return {
+    renderer: opts.webglRenderer || opts.renderer || DEFAULT_RENDERER,
+    vendor: opts.webglVendor || opts.vendor || DEFAULT_VENDOR,
+    hardwareConcurrency: opts.hardwareConcurrency,
+    deviceMemory: opts.deviceMemory,
+    platform: opts.platform,
+  };
+}
+
+/** Serialized source string for CDP `Page.addScriptToEvaluateOnNewDocument`. */
+function buildSource(opts) {
+  const cfg = resolveConfig(opts);
+  return '(' + buildInitScript.toString() + ')(' + JSON.stringify(cfg) + ');';
+}
+
+const INSTALLED = Symbol.for('@webcrawlerapi/stealth.installed');
+
+/**
+ * Install the stealth bootstrap into a page. Call BEFORE the first goto().
+ * Compatible with puppeteer.launch(), puppeteer.connect(), and any object
+ * exposing `evaluateOnNewDocument(fn, arg)`.
+ *
+ * @returns {Promise<any>} the same page
+ */
+async function installStealth(page, opts) {
+  if (!page || typeof page.evaluateOnNewDocument !== 'function') {
+    throw new TypeError('installStealth(page): page must expose evaluateOnNewDocument()');
+  }
+  opts = opts || {};
+  const cfg = resolveConfig(opts);
+  await page.evaluateOnNewDocument(buildInitScript, cfg);
+  try { page[INSTALLED] = true; } catch (_) {}
+  return page;
+}
+
+/**
+ * Also inject the bootstrap into documents that are ALREADY loaded (useful when
+ * you attach with connect() to a page that is already on the target URL).
+ * The patches will not re-run on navigation unless installStealth() is used too.
+ */
+async function injectNow(page, opts) {
+  if (!page || typeof page.evaluate !== 'function') {
+    throw new TypeError('injectNow(page): page must expose evaluate()');
+  }
+  await page.evaluate(buildSource(opts));
+  return page;
+}
+
+/**
+ * Patch out-of-process / sandboxed iframes (DataDome's challenge runs there).
+ * These get their own CDP target and are NOT covered by page-level
+ * evaluateOnNewDocument.
+ */
+function installOopifHook(browser, opts) {
+  if (!browser || typeof browser.on !== 'function') {
+    throw new TypeError('installOopifHook(browser): browser must expose on()');
+  }
+  opts = opts || {};
+  if (browser.__stealthOopifHooked) return browser;
+  browser.__stealthOopifHooked = true;
+
+  const source = buildSource(opts);
+  browser.on('targetcreated', async (target) => {
+    let type = 'unknown';
+    try { type = target.type(); } catch (_) {}
+    if (type === 'browser' || type === 'page' || type === 'service_worker') return;
+    let session;
+    try {
+      session = await target.createCDPSession();
+      await session.send('Page.enable').catch(() => {});
+      await session.send('Page.addScriptToEvaluateOnNewDocument', { source, runImmediately: true }).catch(() => {});
+      await session.send('Runtime.runIfWaitingForDebugger').catch(() => {});
+    } catch (_) {}
+  });
+  return browser;
+}
+
+/** Convenience: open a page and patch it in one call. */
+async function newPage(browser, opts) {
+  if (!browser || typeof browser.newPage !== 'function') {
+    throw new TypeError('newPage(browser): browser must expose newPage()');
+  }
+  opts = opts || {};
+  const context = typeof browser.defaultBrowserContext === 'function' ? browser.defaultBrowserContext() : null;
+  if (context && opts.origin && typeof context.overridePermissions === 'function') {
+    await context.overridePermissions(opts.origin, opts.permissions || []).catch(() => {});
+  }
+  const page = await browser.newPage();
+  await installStealth(page, opts);
+  installOopifHook(browser, opts);
+  return page;
+}
+
+async function humanMouse(page, points) {
+  for (let i = 0; i < points.length; i++) {
+    const p = points[i];
+    await page.mouse.move(p.x, p.y, { steps: p.steps || 12 });
+    if (p.click) { await page.mouse.down(); await page.mouse.up(); }
+    await new Promise((r) => setTimeout(r, p.delay == null ? 40 : p.delay));
+  }
+}
+
+/** Lazily resolve a puppeteer module (never required unless launch() is used). */
+function getPuppeteer(injected) {
+  if (injected) return injected;
+  for (const name of ['puppeteer-core', 'puppeteer']) {
+    try { return require(name); } catch (_) {}
+  }
+  throw new Error('launch() needs puppeteer; pass opts.puppeteer or install puppeteer/puppeteer-core');
+}
+
+/** Optional launcher. Requires puppeteer only when actually called. */
+async function launch(opts) {
+  opts = opts || {};
+  const puppeteer = getPuppeteer(opts.puppeteer);
+  const os = require('os');
+  const path = require('path');
+  const args = opts.args || [];
+  const browser = await puppeteer.launch({
+    executablePath: opts.executablePath || process.env.CHROME_PATH || undefined,
+    headless: opts.headless != null ? opts.headless : false,
+    userDataDir: opts.userDataDir || path.join(os.homedir(), '.cache', 'chrome-stealth-profile'),
+    defaultViewport: opts.viewport || { width: 1366, height: 900 },
+    protocolTimeout: opts.protocolTimeout || 180000,
+    ignoreDefaultArgs: ['--enable-automation', '--headless'],
+    args: [
+      '--no-sandbox',
+      '--disable-setuid-sandbox',
+      '--disable-blink-features=AutomationControlled',
+      '--disable-infobars',
+      '--disable-dev-shm-usage',
+      '--no-first-run',
+      '--no-default-browser-check',
+      '--window-size=1366,900',
+      '--lang=en-US',
+      ...args,
+    ],
+  });
+  return browser;
+}
+
+module.exports = {
+  VERSION,
+  UA,
+  buildInitScript,
+  buildSource,
+  installStealth,
+  injectNow,
+  installOopifHook,
+  newPage,
+  humanMouse,
+  getPuppeteer,
+  launch,
+};