leapfrog-mcp 0.6.1 → 0.6.3

package/README.md

@@ -6,7 +6,7 @@
 <p align="center"><strong>Multi-session browser MCP for AI agents.</strong><br/>36 tools. 15 parallel sessions. Stealth. HUD. Self-improvement. Up to 10x fewer tokens.</p>
 
 <p align="center">
-<code>npm i leapfrog</code>&nbsp;&nbsp;|&nbsp;&nbsp;Works with Claude Code, Cursor, Windsurf
+<code>npm i leapfrog-mcp</code>&nbsp;&nbsp;|&nbsp;&nbsp;Works with Claude Code, Cursor, Windsurf
 </p>
 
 ---
@@ -33,9 +33,9 @@ Savings range from 2-10x depending on page complexity. Content-heavy pages see t
 ## Quick Start
 
 ```bash
-npx leapfrog --doctor          # verify everything works
-npx leapfrog --stealth-audit   # test all 19 stealth patches
-npx leapfrog --config          # print MCP config to paste
+npx leapfrog-mcp --doctor          # verify everything works
+npx leapfrog-mcp --stealth-audit   # test all 19 stealth patches
+npx leapfrog-mcp --config          # print MCP config to paste
 ```
 
 Add to `~/.mcp.json` (Claude Code) or your editor's MCP config:
@@ -44,12 +44,11 @@ Add to `~/.mcp.json` (Claude Code) or your editor's MCP config:
 {
   "leapfrog": {
     "command": "npx",
-    "args": ["-y", "leapfrog"],
+    "args": ["-y", "leapfrog-mcp"],
     "env": {
       "LEAP_MAX_SESSIONS": "15",
       "LEAP_TILE": "true",
       "LEAP_HUD": "true",
-      "LEAP_SOUND": "true",
       "LEAP_AUTO_CONSENT": "true"
     }
   }
@@ -57,8 +56,9 @@ Add to `~/.mcp.json` (Claude Code) or your editor's MCP config:
 ```
 
 Leapfrog uses `playwright-core` (15MB) instead of `playwright` (1.6GB) and does **not** bundle a browser. Either:
-- Set `LEAP_CHANNEL=chrome` to use your installed Chrome/Chromium
+- Set `LEAP_CHANNEL=chrome` to use your installed Chrome/Chromium (recommended)
 - Or run `npx playwright-core install chromium` to install the bundled Chromium binary
+- Or set `LEAP_CDP_ENDPOINT` to connect to an already-running Chrome instance
 
 ## Feature Matrix
 
@@ -94,7 +94,14 @@ Leapfrog uses `playwright-core` (15MB) instead of `playwright` (1.6GB) and does
 
 ## Stealth
 
-Leapfrog ships 19 anti-detection patches enabled by default (`LEAP_STEALTH=true`). These cover the vectors that fingerprint services like CreepJS and fingerprint-pro actually check:
+Leapfrog ships 19 anti-detection patches enabled by default (`LEAP_STEALTH=true`). Four modes:
+
+- **`true`** (default) — all 19 patches active
+- **`passive`** — removes automation signals only (webdriver, HeadlessChrome). Does NOT fake identity (WebGL, fonts, audio). Better for sites where trust matters more than evasion.
+- **`auto`** — per-domain EXP3 bandit selects the optimal stealth configuration based on what's worked before
+- **`false`** — no stealth patches
+
+These cover the vectors that fingerprint services like CreepJS and fingerprint-pro actually check:
 
 - Client Hints brands (strips HeadlessChrome)
 - `navigator.webdriver` forced to `undefined`
@@ -231,7 +238,7 @@ Leapfrog learns from every visit. Per-domain knowledge persists at `~/.leapfrog/
 | 6 | **Selector healing** | Remembers element fingerprints → selectors, heals broken refs across visits |
 | 7 | **API endpoint caching** | Discovered API endpoints persist across sessions |
 | 8 | **Interaction heat maps** | Tracks which elements agents actually use, suppresses untouched elements _(coming)_ |
-| 9 | **Strategy selection** | Adversarial bandit (EXP3) for stealth config optimization _(coming)_ |
+| 9 | **Strategy selection** | Adversarial bandit (EXP3) for stealth config optimization. Use `LEAP_STEALTH=auto` to enable. |
 
 LRU eviction at 500 domains. Inspect with the `domain_knowledge` tool.
 
@@ -323,23 +330,29 @@ Leapfrog uses pond metaphors to keep things memorable. Your agent is the frog.
 | `LEAP_MAX_SESSIONS` | `15` | Max concurrent sessions |
 | `LEAP_IDLE_TIMEOUT` | `1800000` | Session idle timeout in ms (30 min). Set `0` to disable. |
 | `LEAP_HEADLESS` | `true` | Set `false` to watch the browser |
+| `LEAP_HEADED` | `false` | Set `true` to watch the browser (positive alternative to `LEAP_HEADLESS`) |
 | `LEAP_CHANNEL` | _(bundled chromium)_ | Set `chrome` to use your installed Chrome |
+| `LEAP_CDP_ENDPOINT` | _(none)_ | Connect to a running Chrome instance (e.g. `http://localhost:9222`) |
+| `LEAP_EXTENSIONS` | _(none)_ | Comma-separated paths to browser extensions to load |
 | `LEAP_ALLOW_JS` | `true` | Allow JS evaluation in `extract` and `wait_for` |
-| `LEAP_STEALTH` | `true` | Stealth mode (anti-bot evasion) — 19 patches |
+| `LEAP_STEALTH` | `true` | Stealth mode: `true` \| `passive` \| `auto` \| `false`. See Stealth section. |
+| `LEAP_STEALTH_PROFILES` | `false` | Enable stealth patches on profile (auth'd) sessions |
+| `LEAP_CDP_STEALTH` | `true` | CDP detection evasion (`Runtime.enable` filtering) |
 | `LEAP_HUMANIZE` | `false` | Experimental. Human-like mouse movement, typing cadence, and scroll behavior. |
 | `LEAP_ALLOW_EXECUTE` | `true` | Allow the `execute` tool (sandboxed Playwright scripts) |
 | `LEAP_BLOCK_LOCALHOST` | `false` | Block localhost/127.x.x.x (allowed by default for local dev) |
 | `LEAP_PROFILES_DIR` | `~/.leapfrog/chrome-profiles` | Directory for persistent browser profiles |
 | `LEAP_TILE` | `false` | Tile sessions in a grid (`true` \| `master` \| `false`) |
 | `LEAP_TILE_PADDING` | `8` | Padding between tiled windows (px) |
+| `LEAP_MULTI_TILE` | `false` | Multi-terminal tiling coordination across Leapfrog instances |
+| `LEAP_SCREEN_WIDTH` | _(auto)_ | Explicit screen width for tiling calculations |
+| `LEAP_SCREEN_HEIGHT` | _(auto)_ | Explicit screen height for tiling calculations |
 | `LEAP_HUD` | `false` | Click ripple, zoom-to-target, scroll-to-target on agent actions |
-| `LEAP_SOUND` | `false` | Marimba chime on intervention detection (macOS) |
-| `LEAP_NOTIFY` | `false` | macOS notification center alerts on intervention detection |
 | `LEAP_AUTO_CONSENT` | `true` | Auto-dismiss cookie consent banners (10 frameworks + fallback) |
 | `LEAP_TRACE` | `false` | Per-session Playwright tracing (screenshots + DOM snapshots) |
 | `LEAP_RECORD` | `false` | Session recording (action history export) |
-| `LEAP_SIDECAR_PORT` | `9222` | Sidecar HTTP server port (used with tiling) |
-| `LEAP_CDP_STEALTH` | `true` | CDP detection evasion (`Runtime.enable` filtering) |
+| `LEAP_REBROWSER` | `false` | Enable Rebrowser integration |
+| `LEAP_AUTO_WARM` | `false` | Auto-warm profiles by loading key URLs on session create |
 | `LEAP_CAPTCHA_PROVIDER` | _(none)_ | External CAPTCHA solver: `capsolver` \| `2captcha` \| `nopecha` |
 | `LEAP_CAPTCHA_API_KEY` | _(none)_ | API key for the configured CAPTCHA provider |
 | `LEAP_MAX_SESSIONS_PER_CLIENT` | _(none)_ | Per-client session pool limit |
@@ -348,10 +361,10 @@ Leapfrog uses pond metaphors to keep things memorable. Your agent is the frog.
 ## Tests
 
 ```
- 815 passing across 33 suites
+ 769 passing across 31 suites
 ```
 
-Session management, snapshot engine, network intelligence, tab management, security, SSRF protection, stealth patches (19), humanization (mouse, typing, scroll), page classification, harness intelligence, API intelligence, script executor, extended actions, HUD overlays, human intervention, cookie consent, domain knowledge, tracing, sidecar HTTP, bug regression, stress tests, benchmarks.
+Session management, snapshot engine, snapshot differ, network intelligence, tab management, security, SSRF protection, stealth patches (19), stealth enhanced, humanization (mouse, typing, scroll), page classification, harness intelligence, API intelligence, script executor, extended actions, HUD overlays, human intervention, cookie consent, domain knowledge, selector healing, stable elements, tile manager, bug regression, integration smoke, stress tests, benchmarks.
 
 ```bash
 npm test

package/dist/index.js

@@ -49,7 +49,9 @@ const MAX_SNAPSHOT_CHARS = 10000;
 const ALLOW_JS = process.env.LEAP_ALLOW_JS !== "false";
 const ALLOW_EXECUTE = process.env.LEAP_ALLOW_EXECUTE !== "false";
 const LEAP_PROFILES_DIR = process.env.LEAP_PROFILES_DIR ?? path.join(os.homedir(), ".leapfrog", "chrome-profiles");
-const LEAP_TILE = process.env.LEAP_TILE;
+// WORKAROUND: Claude Code on Windows does not pass mcp.json env vars to child process.
+// Default to "grid" so tiling works out of the box on all platforms.
+const LEAP_TILE = process.env.LEAP_TILE || "grid";
 const LEAP_TILE_PADDING = Number(process.env.LEAP_TILE_PADDING ?? 8);
 const LEAP_SCREEN_WIDTH = Number(process.env.LEAP_SCREEN_WIDTH || 0);
 const LEAP_SCREEN_HEIGHT = Number(process.env.LEAP_SCREEN_HEIGHT || 0);
@@ -79,9 +81,10 @@ if (LEAP_TILE && LEAP_TILE !== "false") {
 // Zero cost for single-terminal (just tracks one instance). No extra env var needed.
 let tilesCoord = null;
 if (LEAP_TILE && LEAP_TILE !== "false") {
-    // Screen size: prefer env vars, fall back to 1920x1080. CDP detection will update later.
-    const defaultW = LEAP_SCREEN_WIDTH > 0 ? LEAP_SCREEN_WIDTH : 1920;
-    const defaultH = LEAP_SCREEN_HEIGHT > 0 ? LEAP_SCREEN_HEIGHT : 1080;
+    // Screen size: prefer env vars, then auto-detected screen, fall back to 1920x1080.
+    const detectedScreen = tileManager.getScreenSize();
+    const defaultW = LEAP_SCREEN_WIDTH > 0 ? LEAP_SCREEN_WIDTH : detectedScreen?.width ?? 1920;
+    const defaultH = LEAP_SCREEN_HEIGHT > 0 ? LEAP_SCREEN_HEIGHT : detectedScreen?.height ?? 1080;
     tilesCoord = new TilesCoordinator(defaultW, defaultH);
     // File watcher only needed for multi-terminal mode (multiple Leapfrog instances).
     // In single-instance mode, the watcher causes spurious reflows that fight
@@ -3002,7 +3005,7 @@ function printConfig() {
     const config = {
         leapfrog: {
             command: "npx",
-            args: ["-y", "leapfrog"],
+            args: ["-y", "leapfrog-mcp"],
             env: {
                 LEAP_MAX_SESSIONS: "15",
             },

package/dist/session-manager.js

@@ -288,10 +288,9 @@ export class SessionManager {
             if (stealth.isEnabled()) {
                 launchArgs.push(...stealth.getLaunchArgs());
             }
-            // Windows DPI: prevent Chromium from double-scaling window positions
-            if (process.platform === 'win32') {
-                launchArgs.push('--force-device-scale-factor=1');
-            }
+            // Windows DPI: --force-device-scale-factor=1 REMOVED
+            // On high-DPI Windows (250%), it renders content at 1x = unreadable tiny text.
+            // Let Chrome auto-detect DPI; CDP handles window positioning correctly without it.
             // ── Window position args ───────────────────────────────────────
             // When tiling: grid position. Otherwise: just place on the detected screen.
             const screen = tileManager.getScreenSize();
@@ -578,6 +577,22 @@ export class SessionManager {
                 logger.warn("tile.position_failed", { error: e.message });
             }
         }
+        // ── Debounced reflow after creation (Windows only) ─────────────
+        // On Windows, launch args position each window for a grid that includes
+        // only the sessions created so far. Earlier windows end up at stale positions.
+        // Reflow all after a 500ms debounce so rapid batch creates settle into one reflow.
+        // Skipped on macOS where CDP reflow can move windows to the wrong screen.
+        if (process.platform === "win32" && tileManager.isEnabled() && this.sessions.size > 1) {
+            clearTimeout(globalThis.__leapReflowTimer);
+            globalThis.__leapReflowTimer = setTimeout(async () => {
+                try {
+                    await tileManager.reflowAll(this.sessions);
+                }
+                catch (e) {
+                    logger.warn("tile.reflow_after_create_failed", { error: e.message });
+                }
+            }, 500);
+        }
         // ── Auto-reflow on external close ──────────────────────────────
         // When the user manually closes a browser window (X button), clean up
         // the session and reflow remaining tiled windows. Without this, closing

package/dist/tile-manager.d.ts

@@ -48,8 +48,8 @@ declare class TileManager {
      */
     static detectTerminalScreen(): ScreenWorkArea | null;
     /**
-     * Windows: detect which monitor contains the foreground window via PowerShell.
-     * Uses .NET System.Windows.Forms.Screen to map foreground window → screen bounds.
+     * Windows: detect primary screen working area via PowerShell.
+     * Uses System.Windows.Forms.Screen — no DllImport, no escaping issues.
      */
     static detectScreenViaPowershell(): ScreenWorkArea | null;
     detectScreen(page: Page): Promise<ScreenWorkArea>;

package/dist/tile-manager.js

@@ -76,36 +76,12 @@ class TileManager {
         return null;
     }
     /**
-     * Windows: detect which monitor contains the foreground window via PowerShell.
-     * Uses .NET System.Windows.Forms.Screen to map foreground window → screen bounds.
+     * Windows: detect primary screen working area via PowerShell.
+     * Uses System.Windows.Forms.Screen — no DllImport, no escaping issues.
      */
     static detectScreenViaPowershell() {
         try {
-            // PowerShell script:
-            // 1. Get foreground window handle via user32.dll
-            // 2. Get window RECT via user32.dll
-            // 3. Find which Screen contains that RECT
-            // 4. Output WorkingArea (excludes taskbar) as "x y width height"
-            const script = `powershell -NoProfile -NonInteractive -Command "
-Add-Type -AssemblyName System.Windows.Forms
-Add-Type -TypeDefinition '
-using System;
-using System.Runtime.InteropServices;
-public class WinAPI {
-  [DllImport(\\\"user32.dll\\\")] public static extern IntPtr GetForegroundWindow();
-  [DllImport(\\\"user32.dll\\\")] public static extern bool GetWindowRect(IntPtr hWnd, out RECT lpRect);
-  [StructLayout(LayoutKind.Sequential)] public struct RECT { public int Left, Top, Right, Bottom; }
-}
-'
-$hwnd = [WinAPI]::GetForegroundWindow()
-$rect = New-Object WinAPI+RECT
-[void][WinAPI]::GetWindowRect($hwnd, [ref]$rect)
-$pt = New-Object System.Drawing.Point($rect.Left, $rect.Top)
-$scr = [System.Windows.Forms.Screen]::FromPoint($pt)
-$wa = $scr.WorkingArea
-Write-Output ('{0} {1} {2} {3}' -f $wa.X, $wa.Y, $wa.Width, $wa.Height)
-"`;
-            const result = execSync(script, { timeout: 10000, encoding: "utf-8" }).trim();
+            const result = execSync('powershell -NoProfile -NonInteractive -Command "Add-Type -AssemblyName System.Windows.Forms; $wa = [System.Windows.Forms.Screen]::PrimaryScreen.WorkingArea; Write-Output ($wa.X.ToString() + \' \' + $wa.Y.ToString() + \' \' + $wa.Width.ToString() + \' \' + $wa.Height.ToString())"', { timeout: 10000, encoding: "utf-8" }).trim();
             const parts = result.split(/\s+/).map(Number);
             if (parts.length === 4 && parts.every((n) => !isNaN(n))) {
                 return { x: parts[0], y: parts[1], width: parts[2], height: parts[3] };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "leapfrog-mcp",
-  "version": "0.6.1",
+  "version": "0.6.3",
   "description": "Multi-session browser MCP for AI agents — 36 tools, stealth, persistent auth, code-first scripts, API sniffer, agent intelligence",
   "type": "module",
   "main": "dist/index.js",

package/dist/interaction-tracker.d.ts

@@ -1,44 +0,0 @@
-export interface InteractionRecord {
-    fingerprint: string;
-    clicks: number;
-    fills: number;
-    extracts: number;
-    lastUsed: number;
-}
-type InteractionType = 'click' | 'fill' | 'extract';
-export declare class InteractionTracker {
-    private cache;
-    /**
-     * Record an agent interaction with an element on a domain.
-     * Upserts the record, incrementing the relevant counter.
-     */
-    recordInteraction(domain: string, fingerprint: string, type: InteractionType): void;
-    /**
-     * Compute relevance scores (0.0–1.0) for all tracked fingerprints on a domain.
-     * Only activates after MIN_VISIT_THRESHOLD visits (safety threshold).
-     *
-     * Score = (totalInteractions / visitCount) * recencyBoost
-     * Capped at 1.0.
-     */
-    getRelevanceScores(domain: string, visitCount: number): Map<string, number>;
-    /**
-     * Get fingerprints eligible for suppression — elements never interacted with
-     * after enough visits. Excludes form input roles which must never be suppressed.
-     *
-     * NOTE: This returns fingerprints with relevance 0.0 (no interaction records).
-     * The caller must combine this with the full set of known fingerprints from
-     * the snapshot to identify which zero-interaction elements to suppress.
-     * Elements that appear in getRelevanceScores have score > 0 and should NOT
-     * be suppressed. This method returns the set of tracked fingerprints whose
-     * total interactions are zero — which in practice means fingerprints that
-     * were recorded via other means but never acted upon.
-     */
-    getSuppressSet(domain: string, visitCount: number): Set<string>;
-    /** Serialize interaction records for a domain (for persistence in DomainRecord). */
-    toJSON(domain: string): InteractionRecord[];
-    /** Restore interaction records for a domain from persisted data. */
-    fromJSON(domain: string, data: InteractionRecord[]): void;
-    private computeRecencyBoost;
-}
-export declare const interactionTracker: InteractionTracker;
-export {};

package/dist/interaction-tracker.js

@@ -1,148 +0,0 @@
-// ─── Interaction Heat Maps ────────────────────────────────────────────────
-//
-// Tracks which elements agents actually interact with (click, fill, extract)
-// on each domain. After enough visits, elements that were never touched can
-// be suppressed from snapshots for additional token savings on top of the
-// existing stable-element suppression.
-//
-// Storage: piggybacks on DomainRecord persistence via toJSON/fromJSON.
-import { logger } from './logger.js';
-import { normalizeDomain } from './domain-knowledge.js';
-// ─── Constants ────────────────────────────────────────────────────────────
-/** Maximum interaction records per domain (LRU by lastUsed). */
-const MAX_RECORDS_PER_DOMAIN = 200;
-/** Minimum visits before relevance scoring activates. */
-const MIN_VISIT_THRESHOLD = 10;
-/** Recency boost boundaries in milliseconds. */
-const SEVEN_DAYS_MS = 7 * 24 * 60 * 60 * 1000;
-const THIRTY_DAYS_MS = 30 * 24 * 60 * 60 * 1000;
-/** Form input roles that must NEVER be suppressed. */
-const FORM_INPUT_ROLES = new Set([
-    'textbox',
-    'checkbox',
-    'radio',
-    'combobox',
-    'searchbox',
-    'spinbutton',
-    'slider',
-    'switch',
-    'listbox',
-]);
-// ─── Class ────────────────────────────────────────────────────────────────
-export class InteractionTracker {
-    cache = new Map();
-    // ── Recording ─────────────────────────────────────────────────────────
-    /**
-     * Record an agent interaction with an element on a domain.
-     * Upserts the record, incrementing the relevant counter.
-     */
-    recordInteraction(domain, fingerprint, type) {
-        const key = normalizeDomain(domain);
-        let records = this.cache.get(key);
-        if (!records) {
-            records = [];
-            this.cache.set(key, records);
-        }
-        const now = Date.now();
-        const existing = records.find(r => r.fingerprint === fingerprint);
-        if (existing) {
-            existing[type === 'click' ? 'clicks' : type === 'fill' ? 'fills' : 'extracts']++;
-            existing.lastUsed = now;
-        }
-        else {
-            const record = {
-                fingerprint,
-                clicks: type === 'click' ? 1 : 0,
-                fills: type === 'fill' ? 1 : 0,
-                extracts: type === 'extract' ? 1 : 0,
-                lastUsed: now,
-            };
-            records.push(record);
-        }
-        // LRU cap: evict least-recently-used if over limit
-        if (records.length > MAX_RECORDS_PER_DOMAIN) {
-            records.sort((a, b) => b.lastUsed - a.lastUsed);
-            records.length = MAX_RECORDS_PER_DOMAIN;
-        }
-        logger.debug('interaction-tracker:recorded', { domain: key, fingerprint, type });
-    }
-    // ── Scoring ───────────────────────────────────────────────────────────
-    /**
-     * Compute relevance scores (0.0–1.0) for all tracked fingerprints on a domain.
-     * Only activates after MIN_VISIT_THRESHOLD visits (safety threshold).
-     *
-     * Score = (totalInteractions / visitCount) * recencyBoost
-     * Capped at 1.0.
-     */
-    getRelevanceScores(domain, visitCount) {
-        const result = new Map();
-        if (visitCount < MIN_VISIT_THRESHOLD)
-            return result;
-        const key = normalizeDomain(domain);
-        const records = this.cache.get(key);
-        if (!records)
-            return result;
-        const now = Date.now();
-        for (const rec of records) {
-            const total = rec.clicks + rec.fills + rec.extracts;
-            const recencyBoost = this.computeRecencyBoost(now, rec.lastUsed);
-            const score = Math.min((total / visitCount) * recencyBoost, 1.0);
-            result.set(rec.fingerprint, score);
-        }
-        return result;
-    }
-    /**
-     * Get fingerprints eligible for suppression — elements never interacted with
-     * after enough visits. Excludes form input roles which must never be suppressed.
-     *
-     * NOTE: This returns fingerprints with relevance 0.0 (no interaction records).
-     * The caller must combine this with the full set of known fingerprints from
-     * the snapshot to identify which zero-interaction elements to suppress.
-     * Elements that appear in getRelevanceScores have score > 0 and should NOT
-     * be suppressed. This method returns the set of tracked fingerprints whose
-     * total interactions are zero — which in practice means fingerprints that
-     * were recorded via other means but never acted upon.
-     */
-    getSuppressSet(domain, visitCount) {
-        const suppressSet = new Set();
-        if (visitCount < MIN_VISIT_THRESHOLD)
-            return suppressSet;
-        const key = normalizeDomain(domain);
-        const records = this.cache.get(key);
-        if (!records)
-            return suppressSet;
-        for (const rec of records) {
-            const total = rec.clicks + rec.fills + rec.extracts;
-            if (total > 0)
-                continue;
-            // Never suppress form input roles
-            const role = rec.fingerprint.split(':')[0];
-            if (FORM_INPUT_ROLES.has(role))
-                continue;
-            suppressSet.add(rec.fingerprint);
-        }
-        return suppressSet;
-    }
-    // ── Serialization ─────────────────────────────────────────────────────
-    /** Serialize interaction records for a domain (for persistence in DomainRecord). */
-    toJSON(domain) {
-        const key = normalizeDomain(domain);
-        return this.cache.get(key) ?? [];
-    }
-    /** Restore interaction records for a domain from persisted data. */
-    fromJSON(domain, data) {
-        const key = normalizeDomain(domain);
-        this.cache.set(key, data);
-    }
-    // ── Internal ──────────────────────────────────────────────────────────
-    computeRecencyBoost(now, lastUsed) {
-        const age = now - lastUsed;
-        if (age <= SEVEN_DAYS_MS)
-            return 1.0;
-        if (age <= THIRTY_DAYS_MS)
-            return 0.7;
-        return 0.4;
-    }
-}
-// ─── Singleton ────────────────────────────────────────────────────────────
-export const interactionTracker = new InteractionTracker();

package/dist/notify.d.ts

@@ -1,5 +0,0 @@
-export declare function isSoundEnabled(): boolean;
-export declare function isNotifyEnabled(): boolean;
-export declare function playSound(soundPath: string, volume?: number): void;
-export declare function chime(volume?: number): void;
-export declare function alert(title: string, message: string): void;

package/dist/notify.js

@@ -1,50 +0,0 @@
-// ─── Sound & Notification Module ──────────────────────────────────────────
-//
-// Fire-and-forget macOS notifications and sound effects.
-// Silent no-op on non-macOS. Zero npm dependencies.
-//
-// Env: LEAP_SOUND=true, LEAP_SOUND_VOLUME=0.5, LEAP_NOTIFY=true
-import { execFile } from "child_process";
-import * as path from "path";
-import { fileURLToPath } from "url";
-import { logger } from "./logger.js";
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const CHIME_PATH = path.join(__dirname, "..", "assets", "chime.mp3");
-const IS_MAC = process.platform === "darwin";
-export function isSoundEnabled() {
-    return IS_MAC && process.env.LEAP_SOUND === "true";
-}
-export function isNotifyEnabled() {
-    return IS_MAC && process.env.LEAP_NOTIFY === "true";
-}
-export function playSound(soundPath, volume) {
-    if (!isSoundEnabled())
-        return;
-    const vol = volume ?? parseFloat(process.env.LEAP_SOUND_VOLUME || "0.5");
-    logger.debug("notify.playSound", { soundPath, volume: vol });
-    execFile("afplay", ["-v", String(vol), soundPath], (err) => {
-        if (err)
-            logger.debug("notify.playSound.error", { error: err.message });
-    });
-}
-export function chime(volume) {
-    if (!isSoundEnabled())
-        return;
-    const vol = volume ?? parseFloat(process.env.LEAP_SOUND_VOLUME || "0.5");
-    logger.debug("notify.chime", { volume: vol });
-    execFile("afplay", ["-v", String(vol), CHIME_PATH], (err) => {
-        if (err)
-            logger.debug("notify.chime.error", { error: err.message });
-    });
-}
-export function alert(title, message) {
-    if (!isNotifyEnabled())
-        return;
-    logger.debug("notify.alert", { title });
-    const t = title.replace(/"/g, '\\"');
-    const m = message.replace(/"/g, '\\"');
-    execFile("osascript", ["-e", `display notification "${m}" with title "${t}"`], (err) => {
-        if (err)
-            logger.debug("notify.alert.error", { error: err.message });
-    });
-}

package/dist/sidecar.d.ts

@@ -1,25 +0,0 @@
-export interface SidecarDeps {
-    listSessions: () => Array<{
-        id: string;
-        name?: string;
-        url: string;
-    }>;
-    focusSession: (id: string) => Promise<void>;
-    zoomSession: (id: string) => Promise<void>;
-    restoreGrid: () => Promise<void>;
-    setLayout: (layout: string) => Promise<void>;
-    destroyAll: () => Promise<void>;
-    screenshot: (id: string) => Promise<Buffer>;
-}
-export declare class SidecarServer {
-    private server;
-    private deps;
-    constructor(deps: SidecarDeps);
-    start(port?: number): Promise<void>;
-    stop(): Promise<void>;
-    private route;
-    /** Run a handler that requires a session ID, with 404 guard. */
-    private withSession;
-    /** Send a JSON response. */
-    private json;
-}

package/dist/sidecar.js

@@ -1,140 +0,0 @@
-// ─── Sidecar HTTP Control Server ──────────────────────────────────────────
-//
-// Zero-dependency localhost HTTP server for headed-mode session control.
-// Exposes REST-ish endpoints to list, focus, zoom, tile, and screenshot
-// browser sessions.  Started by index.ts when LEAP_TILE is set.
-//
-// All responses are JSON except /screenshot/:id which returns image/png.
-// CORS is wide-open (localhost only, safe).
-import * as http from "node:http";
-import { logger } from "./logger.js";
-// ─── Server ───────────────────────────────────────────────────────────────
-export class SidecarServer {
-    server = null;
-    deps;
-    constructor(deps) {
-        this.deps = deps;
-    }
-    // ── lifecycle ───────────────────────────────────────────────────────────
-    start(port = 9222) {
-        return new Promise((resolve, reject) => {
-            const server = http.createServer((req, res) => {
-                this.route(req, res).catch(() => {
-                    /* already handled inside route() */
-                });
-            });
-            server.once("error", reject);
-            server.listen(port, "127.0.0.1", () => {
-                server.removeListener("error", reject);
-                this.server = server;
-                logger.info("sidecar.start", { port });
-                resolve();
-            });
-        });
-    }
-    stop() {
-        return new Promise((resolve) => {
-            if (!this.server) {
-                resolve();
-                return;
-            }
-            this.server.close(() => {
-                this.server = null;
-                logger.info("sidecar.stop");
-                resolve();
-            });
-        });
-    }
-    // ── routing ─────────────────────────────────────────────────────────────
-    async route(req, res) {
-        const parsed = new URL(req.url ?? "/", `http://${req.headers.host ?? "localhost"}`);
-        const segments = parsed.pathname.replace(/\/+$/, "").split("/").filter(Boolean);
-        // segments: e.g. ["sessions"], ["focus","abc"], ["screenshot","abc"]
-        res.setHeader("Access-Control-Allow-Origin", "*");
-        res.setHeader("Access-Control-Allow-Methods", "GET, OPTIONS");
-        res.setHeader("Access-Control-Allow-Headers", "Content-Type");
-        if (req.method === "OPTIONS") {
-            res.writeHead(204);
-            res.end();
-            return;
-        }
-        const route = segments[0] ?? "";
-        const param = segments[1];
-        try {
-            switch (route) {
-                case "health":
-                    return this.json(res, 200, { ok: true, data: { status: "running" } });
-                case "sessions":
-                    return this.json(res, 200, { ok: true, data: this.deps.listSessions() });
-                case "focus":
-                    return await this.withSession(param, res, async (id) => {
-                        await this.deps.focusSession(id);
-                        return { focused: id };
-                    });
-                case "zoom":
-                    return await this.withSession(param, res, async (id) => {
-                        await this.deps.zoomSession(id);
-                        return { zoomed: id };
-                    });
-                case "grid":
-                    await this.deps.restoreGrid();
-                    return this.json(res, 200, { ok: true, data: { layout: "grid" } });
-                case "layout": {
-                    const layoutType = param ?? "grid";
-                    await this.deps.setLayout(layoutType);
-                    return this.json(res, 200, { ok: true, data: { layout: layoutType } });
-                }
-                case "stop":
-                    await this.deps.destroyAll();
-                    return this.json(res, 200, { ok: true, data: { destroyed: true } });
-                case "screenshot":
-                    return await this.withSession(param, res, async (id) => {
-                        const buf = await this.deps.screenshot(id);
-                        res.writeHead(200, {
-                            "Content-Type": "image/png",
-                            "Content-Length": buf.length,
-                            "Access-Control-Allow-Origin": "*",
-                        });
-                        res.end(buf);
-                        return null; // signal: already sent
-                    });
-                default:
-                    return this.json(res, 404, { ok: false, error: `Unknown route: /${segments.join("/")}` });
-            }
-        }
-        catch (err) {
-            const message = err instanceof Error ? err.message : String(err);
-            logger.error("sidecar.handler", { route, param, error: message });
-            return this.json(res, 500, { ok: false, error: message });
-        }
-    }
-    // ── helpers ─────────────────────────────────────────────────────────────
-    /** Run a handler that requires a session ID, with 404 guard. */
-    async withSession(id, res, handler) {
-        if (!id) {
-            return this.json(res, 400, { ok: false, error: "Missing session ID in URL" });
-        }
-        const sessions = this.deps.listSessions();
-        if (!sessions.some((s) => s.id === id)) {
-            return this.json(res, 404, {
-                ok: false,
-                error: `Session not found: ${id}`,
-                available: sessions.map((s) => s.id),
-            });
-        }
-        const data = await handler(id);
-        if (data !== null) {
-            this.json(res, 200, { ok: true, data });
-        }
-    }
-    /** Send a JSON response. */
-    json(res, status, body) {
-        const payload = JSON.stringify(body);
-        res.writeHead(status, {
-            "Content-Type": "application/json",
-            "Content-Length": Buffer.byteLength(payload),
-            "Access-Control-Allow-Origin": "*",
-        });
-        res.end(payload);
-    }
-}

package/dist/stealth-bandit.d.ts

@@ -1,64 +0,0 @@
-import type { StealthModeType } from './stealth.js';
-declare const STRATEGIES: readonly ["baseline", "tier1-cookies", "tier2-fingerprint", "tier3-full-stealth"];
-export type StealthStrategy = (typeof STRATEGIES)[number];
-export declare function armToStealthMode(armIndex: number): StealthModeType;
-/**
- * Whether the given arm index implies extra behavioral measures
- * beyond the stealth mode (rate limiting, human-like delays).
- * Only tier3-full-stealth (arm 3) triggers these extras.
- */
-export declare function armRequiresExtraMeasures(armIndex: number): boolean;
-export declare class StealthBandit {
-    private weights;
-    private gamma;
-    private numArms;
-    constructor(numArms: number, gamma?: number);
-    /** Probability distribution over arms (EXP3 mixture). */
-    getDistribution(): number[];
-    /** Sample an arm from the distribution. */
-    selectArm(): number;
-    /** Importance-weighted exponential update after observing reward. */
-    update(arm: number, reward: number): void;
-    /** Serialize for persistence in domain records. */
-    toJSON(): {
-        weights: number[];
-        gamma: number;
-        numArms: number;
-    };
-    /** Restore from persisted state. */
-    static fromJSON(data: {
-        weights: number[];
-        gamma: number;
-        numArms?: number;
-    }): StealthBandit;
-}
-export declare class StrategyManager {
-    private bandits;
-    private strategies;
-    constructor(strategies?: readonly string[]);
-    /** Normalize domain: strip www., lowercase. */
-    private normalizeDomain;
-    /** Get or create the bandit for a domain. */
-    private getBandit;
-    /** Select a stealth strategy for the given domain. */
-    selectStrategy(domain: string): {
-        strategy: string;
-        armIndex: number;
-    };
-    /** Record success/failure for a strategy on a domain. */
-    recordOutcome(domain: string, armIndex: number, success: boolean): void;
-    /** Debugging stats for a domain's bandit. */
-    getStats(domain: string): {
-        distribution: number[];
-        strategies: readonly string[];
-    };
-    /** Serialize a domain's bandit for persistence. */
-    toJSON(domain: string): ReturnType<StealthBandit['toJSON']> | null;
-    /** Restore a domain's bandit from persisted data. */
-    fromJSON(domain: string, data: {
-        weights: number[];
-        gamma: number;
-    }): void;
-}
-export declare const strategyManager: StrategyManager;
-export {};

package/dist/stealth-bandit.js

@@ -1,163 +0,0 @@
-// ─── EXP3 Adversarial Bandit for Stealth Strategy Selection ──────────────
-//
-// Bot detection is adversarial — the detector adapts, so static strategies
-// decay. EXP3 provides worst-case regret guarantees regardless of what the
-// detector does. One bandit per domain, because different sites use different
-// detection stacks.
-//
-// Arms map to stealth tiers in DomainRecord.stealthTier:
-//   0 = baseline, 1 = cookies+UA, 2 = fingerprint spoofing, 3 = full stealth
-import { logger } from './logger.js';
-// ─── Strategy Definitions ────────────────────────────────────────────────
-const STRATEGIES = [
-    'baseline',
-    'tier1-cookies',
-    'tier2-fingerprint',
-    'tier3-full-stealth',
-];
-// ─── Arm → Stealth Mode Mapping ─────────────────────────────────────────
-//
-// Maps bandit arm indices to the stealth mode that gets applied per-page.
-//
-//   Arm 0: baseline         → 'off'     — raw Playwright, no stealth patches
-//   Arm 1: tier1-cookies    → 'passive' — remove automation signals only
-//   Arm 2: tier2-fingerprint → 'active' — full fingerprint spoofing
-//   Arm 3: tier3-full-stealth → 'active' — full stealth + extra measures
-//
-// Key insight: passive mode is the sweet spot for most sites. Active
-// fingerprint spoofing is counterproductive on advanced fingerprinters
-// (CreepJS detects the faked identity as "lies"). The bandit should
-// naturally converge on passive (arm 1) for most sites.
-export function armToStealthMode(armIndex) {
-    switch (armIndex) {
-        case 0: return 'off'; // baseline — no stealth at all
-        case 1: return 'passive'; // tier1 — remove automation signals only
-        case 2: return 'active'; // tier2 — full fingerprint spoofing
-        case 3: return 'active'; // tier3 — full stealth (same mode, extra measures elsewhere)
-        default: return 'passive'; // safe fallback
-    }
-}
-/**
- * Whether the given arm index implies extra behavioral measures
- * beyond the stealth mode (rate limiting, human-like delays).
- * Only tier3-full-stealth (arm 3) triggers these extras.
- */
-export function armRequiresExtraMeasures(armIndex) {
-    return armIndex === 3;
-}
-// ─── EXP3 Bandit ─────────────────────────────────────────────────────────
-export class StealthBandit {
-    weights;
-    gamma;
-    numArms;
-    constructor(numArms, gamma) {
-        this.numArms = numArms;
-        // Theoretical EXP3 optimal: sqrt(K * ln(K) / ((e-1) * T)).
-        // Without a known T, we assume T=100 visits per domain as a reasonable
-        // horizon. This keeps exploration meaningful for small K while still
-        // converging.  Clamped to [0.01, 0.5] for stability.
-        this.gamma = gamma ?? Math.min(0.5, Math.max(0.01, Math.sqrt(numArms * Math.log(numArms) / ((Math.E - 1) * 100))));
-        this.weights = new Array(numArms).fill(1.0);
-    }
-    /** Probability distribution over arms (EXP3 mixture). */
-    getDistribution() {
-        const sum = this.weights.reduce((a, b) => a + b, 0);
-        return this.weights.map(w => (1 - this.gamma) * (w / sum) + this.gamma / this.numArms);
-    }
-    /** Sample an arm from the distribution. */
-    selectArm() {
-        const dist = this.getDistribution();
-        let r = Math.random();
-        for (let i = 0; i < dist.length; i++) {
-            r -= dist[i];
-            if (r <= 0)
-                return i;
-        }
-        return this.numArms - 1; // floating-point safety net
-    }
-    /** Importance-weighted exponential update after observing reward. */
-    update(arm, reward) {
-        const dist = this.getDistribution();
-        const estimatedReward = reward / dist[arm];
-        this.weights[arm] *= Math.exp(this.gamma * estimatedReward / this.numArms);
-        // Prevent weight explosion — normalize when any weight exceeds 1e10
-        const maxWeight = Math.max(...this.weights);
-        if (maxWeight > 1e10) {
-            this.weights = this.weights.map(w => w / maxWeight);
-        }
-    }
-    /** Serialize for persistence in domain records. */
-    toJSON() {
-        return { weights: [...this.weights], gamma: this.gamma, numArms: this.numArms };
-    }
-    /** Restore from persisted state. */
-    static fromJSON(data) {
-        const bandit = new StealthBandit(data.weights.length, data.gamma);
-        bandit.weights = [...data.weights];
-        return bandit;
-    }
-}
-// ─── Per-Domain Strategy Manager ─────────────────────────────────────────
-export class StrategyManager {
-    bandits = new Map();
-    strategies;
-    constructor(strategies = STRATEGIES) {
-        this.strategies = strategies;
-    }
-    /** Normalize domain: strip www., lowercase. */
-    normalizeDomain(domain) {
-        return domain.toLowerCase().replace(/^www\./, '');
-    }
-    /** Get or create the bandit for a domain. */
-    getBandit(domain) {
-        const key = this.normalizeDomain(domain);
-        let bandit = this.bandits.get(key);
-        if (!bandit) {
-            bandit = new StealthBandit(this.strategies.length);
-            this.bandits.set(key, bandit);
-            logger.debug('stealth-bandit:created', { domain: key, arms: this.strategies.length });
-        }
-        return bandit;
-    }
-    /** Select a stealth strategy for the given domain. */
-    selectStrategy(domain) {
-        const bandit = this.getBandit(domain);
-        const armIndex = bandit.selectArm();
-        const strategy = this.strategies[armIndex];
-        logger.debug('stealth-bandit:selected', { domain: this.normalizeDomain(domain), strategy, armIndex });
-        return { strategy, armIndex };
-    }
-    /** Record success/failure for a strategy on a domain. */
-    recordOutcome(domain, armIndex, success) {
-        const bandit = this.getBandit(domain);
-        bandit.update(armIndex, success ? 1 : 0);
-        logger.debug('stealth-bandit:outcome', {
-            domain: this.normalizeDomain(domain),
-            arm: armIndex,
-            strategy: this.strategies[armIndex],
-            success,
-        });
-    }
-    /** Debugging stats for a domain's bandit. */
-    getStats(domain) {
-        const bandit = this.getBandit(domain);
-        return {
-            distribution: bandit.getDistribution(),
-            strategies: this.strategies,
-        };
-    }
-    /** Serialize a domain's bandit for persistence. */
-    toJSON(domain) {
-        const key = this.normalizeDomain(domain);
-        const bandit = this.bandits.get(key);
-        return bandit ? bandit.toJSON() : null;
-    }
-    /** Restore a domain's bandit from persisted data. */
-    fromJSON(domain, data) {
-        const key = this.normalizeDomain(domain);
-        this.bandits.set(key, StealthBandit.fromJSON(data));
-        logger.debug('stealth-bandit:restored', { domain: key });
-    }
-}
-// ─── Singleton ───────────────────────────────────────────────────────────
-export const strategyManager = new StrategyManager();