@achamm/veilbrowser 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Armani Cunningham
+
+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

@@ -0,0 +1,272 @@
+# Veil
+
+**A stealth automation runtime for AI agents. Drives real Chrome over raw CDP — no Playwright, no Puppeteer, no WebDriver, zero runtime dependencies.**
+
+![Veil passing bot.sannysoft.com and Cloudflare's challenge](assets/demo.gif)
+
+*Veil driving real Chrome: bot.sannysoft.com all-green, then straight through Cloudflare's JS challenge — no patches, no plugins.*
+
+To Instagram, Google, Reddit, Cloudflare — Veil *is* Chrome. Same binary, same
+TLS, same JS engine, same canvas/WebGL/font fingerprint a human's browser has. We
+don't reimplement the browser (that's Chromium's 20-year, 1000-engineer job, and a
+hand-rolled engine is *easier* to fingerprint, not harder). We replace the part that
+gets you caught: **the automation layer.**
+
+---
+
+## Why not Playwright / Puppeteer?
+
+They're powerful and great for scripted QA. For *agents on hostile sites* they have three structural problems:
+
+| Problem | Playwright/Puppeteer | Veil |
+|---|---|---|
+| **Detectable** | `navigator.webdriver=true`, `--enable-automation`, the `Runtime.enable` CDP tell, `HeadlessChrome` UA | webdriver scrubbed, no automation switches, no `Runtime.enable`, UA + client-hints normalized |
+| **Robotic input** | instant teleport clicks, fixed-cadence typing → behavioural detection | curved Bézier mouse paths, eased timing, human keystroke cadence |
+| **Brittle for agents** | CSS/XPath selectors that break constantly | accessibility-tree snapshot → stable integer `ref`s; agents never write a selector |
+
+Veil is **dependency-free** — Node 24 / Bun ship a global `WebSocket`, so the entire
+CDP transport is ~120 lines we own. Nothing to patch, nothing to leak.
+
+## How Veil compares (honest)
+
+The "real Chrome over raw CDP" idea isn't new — Python's [`nodriver`](https://github.com/ultrafunkamsterdam/nodriver)
+pioneered it, and [Camoufox](https://camoufox.com) (a C++-patched Firefox) scores even
+better on pure stealth. Veil isn't claiming to out-stealth them. Its wedge is **where it
+lives and how agents use it**:
+
+- **TypeScript-native.** The JS/TS agent ecosystem (Vercel AI SDK, LangChain.js, MCP) has
+  no strong raw-CDP stealth driver — it's stuck on Playwright + stealth plugins, or
+  shelling out to Python `nodriver`. Veil is that missing piece.
+- **MCP-native.** Ships an MCP server, so any agent gets stealth browsing as tools with
+  zero glue.
+- **Agent-first, not scraper-first.** Accessibility-tree refs and human input are built for
+  an LLM driving the browser, not for a scraping script.
+- **Does two things the others don't.** Drives the native **"Sign in with Google" (FedCM)**
+  account chooser over CDP — agents are otherwise walled out of Google-SSO apps entirely —
+  and **blocks visited sites from port-scanning your localhost/LAN** (on by default). Neither
+  `nodriver`, Camoufox, nor Playwright-stealth does either.
+
+If you're in Python and just want raw stealth, use `nodriver` or Camoufox — they're great.
+Veil is for **TypeScript agents and MCP hosts.**
+
+## Quick start
+
+**Prerequisites:** Chrome/Chromium on PATH (or `VEIL_CHROME=/path/to/chrome`), and Bun.
+
+```bash
+bun install
+bun run examples/selftest.ts   # launches real Chrome, runs the full chain
+```
+
+**In your own project** — `bun add @achamm/veilbrowser` (or `npm install @achamm/veilbrowser`):
+
+```ts
+import { Browser } from "@achamm/veilbrowser";
+
+const browser = await Browser.launch({ headless: false });   // headful = stealthiest
+const page = await browser.newPage();
+await page.goto("https://example.com");
+
+// Accessibility-tree snapshot → stable integer refs (no selectors).
+const snap = await page.snapshot();
+console.log(snap.text);
+//  [1] textbox "Search"
+//  [2] button "Sign in"
+
+await page.fill(1, "hello");          // act by ref — human typing, jittered timing
+await page.click(2);                  // curved Bézier mouse path, real CDP input
+const png = await page.screenshot();  // PNG buffer for a vision model
+
+await browser.close();
+```
+
+## How the stealth works
+
+1. **Launch (`launcher.ts`)** — a real Chrome with the flags a *normal* profile uses,
+   minus the automation switches Playwright adds. `--disable-blink-features=AutomationControlled`
+   flips `navigator.webdriver` to `false` at the engine level. Persistent `userDataDir`
+   so the profile looks *used* (history, cookies), not freshly minted.
+2. **Transport (`cdp.ts`)** — raw WebSocket, flat session mode. **We never call
+   `Runtime.enable`** — that command is a primary CDP detection vector. `Runtime.evaluate`
+   works without it.
+3. **Page patch (`stealth.ts`)** — injected via `addScriptToEvaluateOnNewDocument`
+   *before* any site code, on every frame: normalizes `webdriver`, `window.chrome`,
+   `plugins`, `languages`, `permissions.query`, WebGL vendor — and makes the patched
+   functions' `toString()` look native so the patch itself can't be detected. Kept
+   deliberately small; over-patching is its own fingerprint.
+4. **UA / client hints (`page.ts`)** — strips the `HeadlessChrome` token from the UA
+   *and* the `Sec-CH-UA` brand headers.
+5. **Human input (`human.ts`)** — seedable PRNG drives curved mouse paths and
+   jittered keystroke timing.
+
+## Agent tooling (the other half of the product)
+
+The selling point isn't only stealth — it's that agents drive it *well*:
+
+- **`snapshot()`** returns the page as a flat numbered index from the accessibility
+  tree (the semantic layer screen readers use). The #1 cause of agent breakage —
+  guessed CSS/XPath selectors — is gone. The agent acts on a stable `ref`.
+- **`screenshot()`** returns a PNG buffer, ready for vision grounding.
+- **`click` / `fill` / `type`** drive real CDP input with human dynamics.
+- **`waitFor(expr)`** replaces flaky fixed sleeps.
+
+## Federated sign-in (FedCM)
+
+"Sign in with Google" one-tap and the newer `navigator.credentials.get({identity})`
+flows render their account chooser as **native browser UI** — the button is a
+cross-origin IdP iframe and the chooser is browser chrome, so no synthetic click can
+reach either. That's a wall for agents logging into Google-SSO apps. Veil drives it
+over CDP's FedCM domain instead:
+
+```ts
+// Passive / one-tap (fires on load once you're signed in to the IdP):
+await page.enableFedCm();          // autoSelectFirst — picks account 0 for you
+await page.goto("https://app.example.com/");
+await page.waitForFedCmDialog();   // chooser intercepted + auto-selected
+await page.disableFedCm();
+
+// Active "Sign in with Google" button, one call:
+const account = await page.signInWithFedCm({ triggerRef: btn.ref });
+```
+
+`enableFedCm` also `resetCooldown`s (Chrome silently suppresses the dialog after
+repeated dismissals) and binds account selection to the page's own CDP session — pick
+the wrong target and the dialog, plus the page's `credentials.get()`, hangs forever.
+Enable it **on demand**, right before the sign-in: turning it on globally hangs any
+site that silently probes FedCM at load. End-to-end run against the canonical demo IdP:
+`bun run examples/fedcm.ts`.
+
+## No localhost / LAN leak (private-network block)
+
+Fingerprinters (iphey, pixelscan, …) don't read your process list — they can't.
+They **port-scan `127.0.0.1` from page JavaScript**, timing which local ports answer,
+and map open ports to software: VNC on `:5900`, an antidetect API on `:3001`, a dev
+server on `:3000`. That both fingerprints you *and* leaks your LAN to every site you
+visit. Most stealth stacks (nodriver, Camoufox, Playwright-stealth) don't stop it.
+
+Veil does, **on by default**. Every HTTP-family request (`fetch`/XHR/`EventSource`/
+`<img>`/`<script>`) from a page to a loopback or private (`127.0.0.0/8`, `10/8`,
+`172.16/12`, `192.168/16`, `::1`, `.localhost`) address is failed **uniformly and
+instantly** — the same error whether the port is open or closed — so a scan can't tell
+them apart and comes back empty. (That's the vector real detectors use; the `:3001`
+antidetect API and `:5900` VNC probes are plain HTTP.)
+
+```ts
+const browser = await Browser.launch();                 // block is on
+const browser = await Browser.launch({ blockPrivateNetwork: false }); // opt out
+// per-page, toggle at runtime:
+await page.blockPrivateNetwork();
+await page.unblockPrivateNetwork();
+```
+
+Still allowed: the agent's own top-level navigation to a private host
+(`page.goto("http://localhost:3000")`), and a localhost page loading its own localhost
+resources — only a **public page reaching a private host** is blocked. Known gaps (honest):
+raw **WebSocket** to a private host isn't interceptable via CDP's Fetch domain, so those
+fall back to Chrome's own Private Network Access (a timeout, not a uniform block); and
+exotic IP encodings (decimal/hex) aren't matched — real-world scanners use the canonical
+forms above.
+
+## Detection scorecard (measured, Chrome 148)
+
+Run it yourself: `bun run examples/detect.ts` (headless) or `VEIL_HEADFUL=1 bun run
+examples/detect.ts` (headful — Veil auto-starts its own Xvfb, no wrapper needed).
+
+Measured on an AMD Radeon (Renoir APU) host, real hardware GL via ANGLE/EGL:
+
+| Detector | Mode | sannysoft | CreepJS "headless" | CreepJS "stealth" |
+|---|---|---|---|---|
+| **Veil — headful + auto-Xvfb + real GPU** | recommended | **57/57** | **0%** | **0%** |
+| Veil — headless + real GPU | server/fast | **57/57** | 33% | 0% |
+| _(earlier: SwiftShader + heavy stealth)_ | _superseded_ | 57/57 | 67% | 20% |
+
+**Live targets** — the full [scrapingcourse.com](https://www.scrapingcourse.com/) challenge
+suite, reproducible with `bun run examples/scrapingcourse.ts` (residential IP, headful):
+
+| Target | Result |
+|---|---|
+| Antibot Challenge | **Bypassed** — "You bypassed the Antibot challenge" (~3s auto-solve) |
+| Cloudflare JS Challenge | **Bypassed** — "You bypassed the Cloudflare challenge" |
+| Cloudflare Antibot + login | **Bypassed** — cleared the wall, rendered the real login form |
+| Cloudflare **Turnstile** + login | **Passed** — managed Turnstile issues its token to real Chrome (a 700+ char `cf-turnstile-response`); the form submits. We don't *solve* a captcha — the real browser *earns* the token |
+| Demo suite — JS rendering, infinite scroll, pagination, table parsing, load-more, CSRF/login | all served clean |
+| Reddit — incl. its JS challenge | served clean (challenge auto-solved) |
+| Instagram — public profile | served clean |
+
+**12/12 cleared** on a clean residential IP. Two honest caveats, not hidden:
+Cloudflare's JS *interstitial* difficulty scales with **IP reputation** — hammer one IP
+and it escalates (that's IP rep, not a browser tell; use proxies at volume). And what we
+do **not** yet claim: an **interactive checkbox** reCAPTCHA/Turnstile that demands a human
+click, enterprise DataDome/Kasada, and high-volume behavioural trust on logged-in sessions.
+We test before we claim.
+
+**What moved the needle (each verified by re-running the suite):**
+1. **Real GPU, not SwiftShader.** `--use-gl=angle --use-angle=gl-egl` drives the actual
+   AMD GPU → an authentic, self-consistent WebGL fingerprint. No vendor spoof = no *lie*
+   for CreepJS's pixel-hash to catch.
+2. **Headful on a server.** Veil manages its own Xvfb display, so "headful" needs no
+   desktop. Eliminates the headless render quirks + tiny-screen tell (33% → 0%).
+3. **Slim, self-gating stealth.** The biggest surprise: the *stealth patches themselves*
+   were the "20% stealth" signal. A correctly-launched Chrome already reports
+   `webdriver === false` (the right human value — forcing `undefined` is *worse*), 5
+   plugins, a real `chrome` object. So each patch now fires only when the value is
+   genuinely anomalous; on healthy Chrome it's a no-op. Smaller surface = nothing to detect.
+
+## Use from an AI agent (MCP)
+
+Veil ships an MCP server (`src/mcp.ts`) — already wired into **persoje**
+(`~/.config/persoje/mcp.json`), exposing 10 tools: `goto`, `snapshot`, `click`, `fill`,
+`type`, `screenshot`, `eval`, `fedcm_enable`, `fedcm_signin`, `close`. Verified end-to-end
+through persoje's own MCP client (discover → goto → snapshot). Any MCP host works:
+
+```jsonc
+{ "servers": { "veil": {
+  "command": "/home/armani/.bun/bin/bun",
+  "args": ["run", "/home/armani/projects/veil/src/mcp.ts"],
+  "env": {}                          // headful + auto-Xvfb + real GPU (0% CreepJS).
+                                     // Set VEIL_HEADLESS=1 for the faster server mode.
+} } }
+```
+
+## Testing
+
+```bash
+bun run examples/selftest.ts   # end-to-end: launch, stealth, snapshot, interact
+bun run examples/detect.ts     # bot-detection scorecard (bot.sannysoft.com, etc.)
+bun test                       # unit tests (browser-launching ones skip under CI)
+```
+
+Unit tests cover:
+- **PRNG (`human.test.ts`)**: xorshift32 determinism, range/int bounds, keystroke cadence, mouse timing
+- **Snapshot refs (`snapshot.test.ts`)**: ref numbering (1-based, sequential, no gaps), AX-tree filtering
+- **CDP framing (`cdp-messages.test.ts`)**: JSON-RPC structure, sessionId routing, command/response correlation
+- **Private-network classifier (`private-host.test.ts`)**: loopback/RFC1918 vs public host detection (the block's decision)
+- **Lifecycle (`lifecycle.test.ts`, local only)**: launch/close, process-group reaping, profile-lock refusal
+
+## Status
+
+**Working today** (verified against Chrome 148):
+- Zero-dep CDP runtime (raw WebSocket, flat session mode)
+- Stealth launch + page-script injection (`--disable-blink-features=AutomationControlled`)
+- UA/client-hint scrub (no "HeadlessChrome" token)
+- WebGL backend selection (hardware GPU via ANGLE/EGL, or SwiftShader + vendor masking)
+- AX-tree snapshot → stable integer refs for agent-friendly interaction
+- Human-like input: curved Bézier mouse paths, jittered keystroke timing, real CDP input
+- PNG screenshots (vision-model ready)
+- Headful-on-server via **auto-managed Xvfb** — "headful" with no desktop (best fingerprint scores)
+- **FedCM sign-in** — drives the native "Sign in with Google" / `credentials.get()` account chooser over CDP (`examples/fedcm.ts`)
+- **No localhost/LAN leak** — blocks visited sites from port-scanning your private network (on by default)
+- Clean process lifecycle — detached process groups + a reaper, so Ctrl-C/crash never orphans Chrome
+- MCP server (`src/mcp.ts`) — stdio JSON-RPC; persoje, Claude, any MCP host drives Veil natively
+
+**Roadmap toward production:**
+- [ ] Adversarial fingerprint suite — continuous scoring (CreepJS, sannysoft, Datadome demo)
+- [ ] `Runtime.enable`-leak hardening via isolated worlds for all eval
+- [ ] Profile + residential-proxy pools (the "Veil Cloud" layer)
+- [ ] Vision-based element grounding fallback (sparse AX-trees, canvas apps)
+- [ ] Response-body capture; session persistence & profile warm-up
+- [ ] Per-tab concurrency (many tabs, one socket — transport already supports it)
+
+## License
+
+MIT.

package/dist/browser.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Browser: the top-level handle. Launches Chrome, opens the CDP socket, and
+ * hands out Page objects attached via flat sessions.
+ */
+import { type LaunchOptions } from "./launcher.js";
+import { Page } from "./page.js";
+export declare class Browser {
+    private cdp;
+    private launch;
+    private blockPrivate;
+    private constructor();
+    static launch(opts?: LaunchOptions): Promise<Browser>;
+    /** Open a fresh tab and return an initialised Page. */
+    newPage(): Promise<Page>;
+    close(): Promise<void>;
+}

package/dist/browser.js

@@ -0,0 +1,43 @@
+/**
+ * Browser: the top-level handle. Launches Chrome, opens the CDP socket, and
+ * hands out Page objects attached via flat sessions.
+ */
+import { launchChrome } from "./launcher.js";
+import { CDP } from "./cdp.js";
+import { Page } from "./page.js";
+export class Browser {
+    cdp;
+    launch;
+    blockPrivate;
+    constructor(cdp, launch, blockPrivate) {
+        this.cdp = cdp;
+        this.launch = launch;
+        this.blockPrivate = blockPrivate;
+    }
+    static async launch(opts = {}) {
+        const launch = await launchChrome(opts);
+        const cdp = await CDP.connect(launch.webSocketDebuggerUrl);
+        // Default ON: a stealth browser shouldn't let visited sites port-scan your
+        // localhost/LAN. Opt out with { blockPrivateNetwork: false }.
+        return new Browser(cdp, launch, opts.blockPrivateNetwork ?? true);
+    }
+    /** Open a fresh tab and return an initialised Page. */
+    async newPage() {
+        const { targetId } = await this.cdp.send("Target.createTarget", { url: "about:blank" });
+        const { sessionId } = await this.cdp.send("Target.attachToTarget", {
+            targetId,
+            flatten: true,
+        });
+        const page = new Page(this.cdp, sessionId, targetId);
+        await page.init({ maskWebgl: this.launch.maskWebgl, blockPrivateNetwork: this.blockPrivate });
+        return page;
+    }
+    async close() {
+        try {
+            await this.cdp.send("Browser.close");
+        }
+        catch { }
+        this.cdp.close();
+        this.launch.kill();
+    }
+}

package/dist/cdp.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Raw Chrome DevTools Protocol client.
+ *
+ * No puppeteer, no playwright, no chrome-remote-interface. Just a WebSocket and
+ * the protocol. We use "flat" session mode (Target.attachToTarget {flatten:true})
+ * so every command/event is tagged with a sessionId and we can talk to the
+ * browser and any number of page targets over a single socket.
+ *
+ * Crucially: we never call `Runtime.enable`. That command is one of the loudest
+ * automation tells on the web (it creates a detectable execution-context binding
+ * and fires events sites listen for). `Runtime.evaluate` works fine without it.
+ */
+type EventHandler = (params: any) => void;
+export declare class CDP {
+    private url;
+    private ws;
+    private nextId;
+    private pending;
+    private handlers;
+    private closed;
+    private constructor();
+    static connect(webSocketDebuggerUrl: string): Promise<CDP>;
+    private open;
+    private onMessage;
+    /** Send a CDP command. Optionally scoped to a session (page target). */
+    send<T = any>(method: string, params?: Record<string, any>, sessionId?: string): Promise<T>;
+    /** Subscribe to an event. Pass sessionId, or "*" to match any session. */
+    on(method: string, handler: EventHandler, sessionId?: string): () => void;
+    /** Resolve once an event fires (with optional predicate / timeout). */
+    once(method: string, opts?: {
+        sessionId?: string;
+        predicate?: (p: any) => boolean;
+        timeout?: number;
+    }): Promise<any>;
+    /** Remove all handlers for a specific sessionId. Called on page close to prevent accumulation. */
+    clearHandlers(sessionId: string): void;
+    close(): void;
+}
+export {};

package/dist/cdp.js

@@ -0,0 +1,128 @@
+/**
+ * Raw Chrome DevTools Protocol client.
+ *
+ * No puppeteer, no playwright, no chrome-remote-interface. Just a WebSocket and
+ * the protocol. We use "flat" session mode (Target.attachToTarget {flatten:true})
+ * so every command/event is tagged with a sessionId and we can talk to the
+ * browser and any number of page targets over a single socket.
+ *
+ * Crucially: we never call `Runtime.enable`. That command is one of the loudest
+ * automation tells on the web (it creates a detectable execution-context binding
+ * and fires events sites listen for). `Runtime.evaluate` works fine without it.
+ */
+export class CDP {
+    url;
+    ws;
+    nextId = 1;
+    pending = new Map();
+    // key: `${sessionId ?? ""}:${method}` -> set of handlers
+    handlers = new Map();
+    closed = false;
+    constructor(url) {
+        this.url = url;
+    }
+    static async connect(webSocketDebuggerUrl) {
+        const cdp = new CDP(webSocketDebuggerUrl);
+        await cdp.open();
+        return cdp;
+    }
+    open() {
+        return new Promise((resolve, reject) => {
+            this.ws = new WebSocket(this.url);
+            this.ws.addEventListener("open", () => resolve());
+            this.ws.addEventListener("error", (e) => reject(new Error(`CDP socket error: ${e?.message ?? "unknown"}`)));
+            this.ws.addEventListener("close", () => {
+                this.closed = true;
+                for (const { reject } of this.pending.values())
+                    reject(new Error("CDP connection closed"));
+                this.pending.clear();
+            });
+            this.ws.addEventListener("message", (ev) => this.onMessage(String(ev.data)));
+        });
+    }
+    onMessage(data) {
+        let msg;
+        try {
+            msg = JSON.parse(data);
+        }
+        catch {
+            return;
+        }
+        if (typeof msg.id === "number") {
+            const p = this.pending.get(msg.id);
+            if (!p)
+                return;
+            this.pending.delete(msg.id);
+            if (msg.error)
+                p.reject(new Error(`${p.method}: ${msg.error.message} (${msg.error.code})`));
+            else
+                p.resolve(msg.result);
+            return;
+        }
+        // Event. Dispatch to handlers keyed with and without sessionId.
+        if (msg.method) {
+            const sid = msg.sessionId ?? "";
+            for (const key of [`${sid}:${msg.method}`, `*:${msg.method}`]) {
+                const set = this.handlers.get(key);
+                if (set)
+                    for (const h of [...set])
+                        h(msg.params ?? {});
+            }
+        }
+    }
+    /** Send a CDP command. Optionally scoped to a session (page target). */
+    send(method, params = {}, sessionId) {
+        if (this.closed)
+            return Promise.reject(new Error("CDP connection closed"));
+        const id = this.nextId++;
+        const payload = { id, method, params };
+        if (sessionId)
+            payload.sessionId = sessionId;
+        return new Promise((resolve, reject) => {
+            this.pending.set(id, { resolve, reject, method });
+            this.ws.send(JSON.stringify(payload));
+        });
+    }
+    /** Subscribe to an event. Pass sessionId, or "*" to match any session. */
+    on(method, handler, sessionId = "*") {
+        const key = `${sessionId}:${method}`;
+        let set = this.handlers.get(key);
+        if (!set)
+            this.handlers.set(key, (set = new Set()));
+        set.add(handler);
+        return () => set.delete(handler);
+    }
+    /** Resolve once an event fires (with optional predicate / timeout). */
+    once(method, opts = {}) {
+        return new Promise((resolve, reject) => {
+            const off = this.on(method, (p) => {
+                if (opts.predicate && !opts.predicate(p))
+                    return;
+                clearTimeout(timer);
+                off();
+                resolve(p);
+            }, opts.sessionId ?? "*");
+            const timer = setTimeout(() => {
+                off();
+                reject(new Error(`Timed out waiting for ${method}`));
+            }, opts.timeout ?? 30000);
+        });
+    }
+    /** Remove all handlers for a specific sessionId. Called on page close to prevent accumulation. */
+    clearHandlers(sessionId) {
+        // Remove all handlers keyed with this sessionId
+        const prefix = `${sessionId}:`;
+        for (const key of this.handlers.keys()) {
+            if (key.startsWith(prefix)) {
+                this.handlers.delete(key);
+            }
+        }
+    }
+    close() {
+        this.closed = true;
+        try {
+            this.ws.close();
+        }
+        catch { }
+    }
+}

package/dist/human.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Human-like input timing.
+ *
+ * Robotic automation moves the mouse in straight teleports and types at a
+ * perfectly fixed cadence. Behavioural-fingerprinting scripts (Akamai, PerimeterX,
+ * Datadome) watch for exactly that. We move along a curved path with eased,
+ * jittered timing and vary keystroke intervals around human norms.
+ *
+ * Determinism note: we draw randomness from a seedable PRNG so runs can be made
+ * reproducible for tests, while still being non-uniform on the wire.
+ */
+export declare class Rng {
+    private s;
+    constructor(seed?: number);
+    next(): number;
+    range(min: number, max: number): number;
+    int(min: number, max: number): number;
+}
+export interface Point {
+    x: number;
+    y: number;
+}
+/**
+ * Sample a curved path from `from` to `to` using a quadratic Bézier whose control
+ * point is offset perpendicular to the travel direction — the gentle arc a real
+ * hand makes. Returns ~steps points with eased spacing (slow-fast-slow).
+ */
+export declare function mousePath(from: Point, to: Point, rng: Rng): Point[];
+/** Per-step delay (ms) for mouse moves — short, slightly jittered. */
+export declare function moveDelay(rng: Rng): number;
+/** Per-character delay (ms) for typing — human burst-and-pause cadence. */
+export declare function keyDelay(rng: Rng, char: string): number;
+export declare const sleep: (ms: number) => Promise<unknown>;

package/dist/human.js

@@ -0,0 +1,73 @@
+/**
+ * Human-like input timing.
+ *
+ * Robotic automation moves the mouse in straight teleports and types at a
+ * perfectly fixed cadence. Behavioural-fingerprinting scripts (Akamai, PerimeterX,
+ * Datadome) watch for exactly that. We move along a curved path with eased,
+ * jittered timing and vary keystroke intervals around human norms.
+ *
+ * Determinism note: we draw randomness from a seedable PRNG so runs can be made
+ * reproducible for tests, while still being non-uniform on the wire.
+ */
+export class Rng {
+    s;
+    constructor(seed = (Date.now() ^ (process.pid << 16)) >>> 0) {
+        this.s = seed >>> 0 || 1;
+    }
+    next() {
+        // xorshift32
+        let x = this.s;
+        x ^= x << 13;
+        x ^= x >>> 17;
+        x ^= x << 5;
+        this.s = x >>> 0;
+        return this.s / 0xffffffff;
+    }
+    range(min, max) {
+        return min + this.next() * (max - min);
+    }
+    int(min, max) {
+        return Math.floor(this.range(min, max + 1));
+    }
+}
+/**
+ * Sample a curved path from `from` to `to` using a quadratic Bézier whose control
+ * point is offset perpendicular to the travel direction — the gentle arc a real
+ * hand makes. Returns ~steps points with eased spacing (slow-fast-slow).
+ */
+export function mousePath(from, to, rng) {
+    const dx = to.x - from.x;
+    const dy = to.y - from.y;
+    const dist = Math.hypot(dx, dy);
+    const steps = Math.max(8, Math.min(40, Math.round(dist / 12)));
+    // Perpendicular control-point offset, scaled to distance, signed randomly.
+    const mag = Math.min(dist * 0.18, 60) * (rng.next() < 0.5 ? -1 : 1) * rng.range(0.4, 1);
+    const mx = (from.x + to.x) / 2 + (-dy / (dist || 1)) * mag;
+    const my = (from.y + to.y) / 2 + (dx / (dist || 1)) * mag;
+    const pts = [];
+    for (let i = 1; i <= steps; i++) {
+        let t = i / steps;
+        // ease-in-out so the cursor accelerates then settles
+        t = t < 0.5 ? 2 * t * t : 1 - Math.pow(-2 * t + 2, 2) / 2;
+        const u = 1 - t;
+        const x = u * u * from.x + 2 * u * t * mx + t * t * to.x;
+        const y = u * u * from.y + 2 * u * t * my + t * t * to.y;
+        // sub-pixel jitter
+        pts.push({ x: x + rng.range(-0.6, 0.6), y: y + rng.range(-0.6, 0.6) });
+    }
+    pts[pts.length - 1] = { x: to.x, y: to.y }; // land exactly on target
+    return pts;
+}
+/** Per-step delay (ms) for mouse moves — short, slightly jittered. */
+export function moveDelay(rng) {
+    return rng.range(4, 12);
+}
+/** Per-character delay (ms) for typing — human burst-and-pause cadence. */
+export function keyDelay(rng, char) {
+    if (char === " ")
+        return rng.range(60, 140);
+    if (/[.,!?]/.test(char))
+        return rng.range(120, 260); // micro-pause at punctuation
+    return rng.range(45, 130);
+}
+export const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { Browser } from "./browser.js";
+export { Page, isPrivateHost, type Snapshot, type Element, type FedCmAccount, type FedCmDialog } from "./page.js";
+export { launchChrome, findChrome, type LaunchOptions } from "./launcher.js";
+export { CDP } from "./cdp.js";
+export { STEALTH_SOURCE } from "./stealth.js";
+export { Rng, mousePath } from "./human.js";

package/dist/index.js

@@ -0,0 +1,6 @@
+export { Browser } from "./browser.js";
+export { Page, isPrivateHost } from "./page.js";
+export { launchChrome, findChrome } from "./launcher.js";
+export { CDP } from "./cdp.js";
+export { STEALTH_SOURCE } from "./stealth.js";
+export { Rng, mousePath } from "./human.js";