leapfrog-mcp 0.6.2 → 0.6.3

package/dist/harness-intelligence.js

@@ -0,0 +1,432 @@
+import { logger } from "./logger.js";
+// ─── Constants ────────────────────────────────────────────────────────────
+const MAX_HISTORY = 50;
+const LOOP_WINDOW = 10;
+const LOOP_THRESHOLD = 3;
+const STUCK_THRESHOLD = 5;
+const BLOCKED_KEYWORDS_STRONG = [
+    "captcha",
+    "verify you're human",
+    "verify you are human",
+    "access denied",
+    "security check",
+    "bot detection",
+    "prove you're not a robot",
+    "i'm not a robot",
+    "unusual traffic",
+];
+const BLOCKED_KEYWORDS_WEAK = [
+    "challenge",
+    "cloudflare",
+    "please wait",
+    "checking your browser",
+    "just a moment",
+    "blocked",
+];
+/** Element count above which only strong challenge signals trigger BLOCKED */
+const BLOCKED_ELEMENT_THRESHOLD = 50;
+const NON_INTERACTIVE_ELEMENTS = new Set([
+    "p", "h1", "h2", "h3", "h4", "h5", "h6",
+    "div", "span", "section", "article", "header", "footer",
+    "main", "nav", "aside", "li", "dt", "dd", "td", "th", "tr",
+]);
+/** ARIA roles that are non-interactive (from snapshot @eN refs) */
+const NON_INTERACTIVE_ROLES = new Set([
+    "paragraph", "heading", "generic", "group", "region",
+    "contentinfo", "banner", "complementary", "navigation",
+    "main", "article", "section", "figure", "list", "listitem",
+    "definition", "term", "cell", "row", "rowgroup", "columnheader",
+    "rowheader", "table", "img", "separator", "presentation", "none",
+    "status", "blockquote", "caption", "code", "deletion", "emphasis",
+    "insertion", "strong", "subscript", "superscript", "time",
+]);
+/** Roles that suggest what the agent should do instead */
+const ROLE_SUGGESTIONS = {
+    paragraph: "Consider using `extract` to read content, or find a link/button nearby.",
+    heading: "Consider using `extract` to read content, or find a link/button nearby.",
+    generic: "This is a non-interactive container. Look for a button, link, or input inside it.",
+    img: "Images aren't clickable unless they contain a link. Check for a parent link or nearby button.",
+    group: "This is a grouping element. Look for interactive elements inside it.",
+    region: "This is a region container. Look for interactive elements inside it.",
+    list: "Click a specific list item's link or button, not the list container.",
+    listitem: "Look for a link or button inside this list item.",
+    cell: "Look for a link or button inside this table cell.",
+    table: "Click a specific cell, link, or button within the table.",
+    navigation: "Look for links or buttons inside this navigation region.",
+};
+const preStates = new Map();
+const histories = new Map();
+// ─── Hashing (djb2) ──────────────────────────────────────────────────────
+function djb2(str) {
+    let hash = 5381;
+    for (let i = 0; i < str.length; i++) {
+        hash = ((hash << 5) + hash + str.charCodeAt(i)) | 0;
+    }
+    // Convert to unsigned 32-bit hex for readability
+    return (hash >>> 0).toString(16);
+}
+// ─── Blocked detection ────────────────────────────────────────────────────
+function isBlockedPage(snapshotText) {
+    const lower = snapshotText.toLowerCase();
+    // Count elements in snapshot (lines starting with @e)
+    const elementCount = (snapshotText.match(/^[ \t]*@e\d+/gm) ?? []).length;
+    // Strong signals always trigger BLOCKED
+    const hasStrongSignal = BLOCKED_KEYWORDS_STRONG.some((kw) => lower.includes(kw));
+    // Weak signals only trigger on small pages (< threshold elements)
+    const hasWeakSignal = BLOCKED_KEYWORDS_WEAK.some((kw) => lower.includes(kw));
+    if (hasStrongSignal) {
+        // Even with strong signals, a page with many elements is likely real content
+        // that happens to mention these words. Require very few elements too.
+        if (elementCount > BLOCKED_ELEMENT_THRESHOLD)
+            return false;
+        return true;
+    }
+    if (hasWeakSignal && elementCount < BLOCKED_ELEMENT_THRESHOLD) {
+        return true;
+    }
+    return false;
+}
+// ─── Outcome classification ───────────────────────────────────────────────
+/**
+ * Extract the tag name from a CSS selector target like "p.intro", "div#main", "h1", "span.text".
+ * Returns lowercase tag name or undefined if not a simple tag selector.
+ */
+function extractTagName(target) {
+    if (!target)
+        return undefined;
+    // Skip ref-style targets like @e5
+    if (target.startsWith("@e"))
+        return undefined;
+    // Match the leading tag name from a CSS selector
+    const match = target.match(/^([a-zA-Z][a-zA-Z0-9]*)/);
+    return match ? match[1].toLowerCase() : undefined;
+}
+/**
+ * Extract the ARIA role from the snapshot text for an @eN target.
+ * Snapshot lines look like: "@e5 paragraph "Some text content""
+ * Returns the role string (e.g. "paragraph") or undefined if not found.
+ */
+function extractRoleFromSnapshot(target, snapshotText) {
+    if (!target || !target.startsWith("@e"))
+        return undefined;
+    // Match the line in the snapshot: "@eN role ..."
+    // Account for optional leading whitespace/indentation
+    const ref = target.replace("@", ""); // "e5"
+    const pattern = new RegExp(`(?:^|\\n)\\s*@${ref}\\s+(\\w[\\w-]*)`, "m");
+    const match = snapshotText.match(pattern);
+    return match ? match[1].toLowerCase() : undefined;
+}
+/**
+ * Build a helpful SILENT_CLICK message for a non-interactive role.
+ */
+function buildNonInteractiveMessage(role) {
+    const suggestion = ROLE_SUGGESTIONS[role] ??
+        "Consider using `extract` to read content, or find a link/button nearby.";
+    return `Clicked non-interactive element (role: ${role}). ${suggestion}`;
+}
+function classifyOutcome(preState, postUrl, postHash, postSnapshot, error, actionType, target) {
+    // Error takes top priority
+    if (error) {
+        return { outcome: "ERROR", detail: error };
+    }
+    // No pre-state captured — graceful degradation
+    if (!preState) {
+        return { outcome: "SUCCESS", detail: "Action completed (no pre-state for comparison)" };
+    }
+    // URL changed → NAVIGATION
+    if (postUrl !== preState.url) {
+        return { outcome: "NAVIGATION", detail: `Navigated: ${preState.url} → ${postUrl}` };
+    }
+    // Check for click on non-interactive CSS selector targets (tag-based detection).
+    // These are pre-hash checks because CSS tag selectors are strong signals
+    // (the agent explicitly used a tag selector like "p" or "div").
+    if (actionType === "click" || actionType === "dblclick") {
+        const tagName = extractTagName(target);
+        if (tagName && NON_INTERACTIVE_ELEMENTS.has(tagName)) {
+            return {
+                outcome: "SILENT_CLICK",
+                detail: `Warning: Clicked a non-interactive element (<${tagName}>). No action was performed. Did you mean to click a button or link?`,
+            };
+        }
+    }
+    // Same snapshot hash → SILENT_CLICK
+    // For @eN targets: also parse the role from the snapshot for better messages.
+    if (postHash === preState.snapshotHash) {
+        if (target && (actionType === "click" || actionType === "dblclick")) {
+            const role = target ? extractRoleFromSnapshot(target, postSnapshot) : undefined;
+            if (role && NON_INTERACTIVE_ROLES.has(role)) {
+                return { outcome: "SILENT_CLICK", detail: buildNonInteractiveMessage(role) };
+            }
+        }
+        return { outcome: "SILENT_CLICK", detail: "No DOM changes detected after action" };
+    }
+    // Hash changed — check for blocked pages
+    if (isBlockedPage(postSnapshot)) {
+        return { outcome: "BLOCKED", detail: "Anti-bot or challenge page detected" };
+    }
+    // Hash changed with normal content
+    return { outcome: "SUCCESS", detail: "DOM changed after action" };
+}
+// ─── Loop detection ───────────────────────────────────────────────────────
+function detectLoop(history) {
+    if (history.length < LOOP_THRESHOLD)
+        return undefined;
+    const window = history.slice(-LOOP_WINDOW);
+    // 1. Same-element loop: same target clicked 3+ times
+    const targetCounts = new Map();
+    for (const rec of window) {
+        if (rec.target) {
+            const key = `${rec.actionType}:${rec.target}`;
+            targetCounts.set(key, (targetCounts.get(key) ?? 0) + 1);
+        }
+    }
+    for (const [key, count] of targetCounts) {
+        if (count >= LOOP_THRESHOLD) {
+            const [, target] = key.split(":");
+            return {
+                type: "same-element",
+                message: `You've interacted with ${target} ${count} times in the last ${window.length} actions with no state change.`,
+                count,
+                suggestion: "Try a different element or scroll to reveal more options.",
+            };
+        }
+    }
+    // 2. Same-URL loop: same URL visited 3+ times
+    const urlCounts = new Map();
+    for (const rec of window) {
+        if (rec.outcome === "NAVIGATION") {
+            urlCounts.set(rec.url, (urlCounts.get(rec.url) ?? 0) + 1);
+        }
+    }
+    for (const [url, count] of urlCounts) {
+        if (count >= LOOP_THRESHOLD) {
+            return {
+                type: "same-url",
+                message: `Navigated to ${url} ${count} times.`,
+                count,
+                suggestion: "You may be stuck in a redirect loop. Try a different approach or URL.",
+            };
+        }
+    }
+    // 3. Ping-pong: alternating between 2 URLs (A→B→A→B)
+    if (window.length >= 4) {
+        const urls = window.map((r) => r.url);
+        const last4 = urls.slice(-4);
+        if (last4[0] === last4[2] &&
+            last4[1] === last4[3] &&
+            last4[0] !== last4[1]) {
+            return {
+                type: "ping-pong",
+                message: `Alternating between ${last4[0]} and ${last4[1]}.`,
+                count: 4,
+                suggestion: "Break the cycle — try a completely different page or action.",
+            };
+        }
+        // Also check ping-pong on targets
+        const targets = window.filter((r) => r.target).map((r) => r.target);
+        if (targets.length >= 4) {
+            const lastTargets = targets.slice(-4);
+            if (lastTargets[0] === lastTargets[2] &&
+                lastTargets[1] === lastTargets[3] &&
+                lastTargets[0] !== lastTargets[1]) {
+                return {
+                    type: "ping-pong",
+                    message: `Alternating between ${lastTargets[0]} and ${lastTargets[1]}.`,
+                    count: 4,
+                    suggestion: "Break the cycle — try a completely different element or approach.",
+                };
+            }
+        }
+    }
+    // 4. Action repetition: same action+target 3+ times with no DOM change
+    const noChangeActions = window.filter((r) => r.outcome === "SILENT_CLICK");
+    if (noChangeActions.length >= LOOP_THRESHOLD) {
+        const repeatCounts = new Map();
+        for (const rec of noChangeActions) {
+            const key = `${rec.actionType}:${rec.target ?? "none"}`;
+            repeatCounts.set(key, (repeatCounts.get(key) ?? 0) + 1);
+        }
+        for (const [key, count] of repeatCounts) {
+            if (count >= LOOP_THRESHOLD) {
+                const [actionType, target] = key.split(":");
+                return {
+                    type: "action-repeat",
+                    message: `${actionType} on ${target} repeated ${count} times with no DOM change.`,
+                    count,
+                    suggestion: "This action isn't producing results. Try a different approach.",
+                };
+            }
+        }
+    }
+    return undefined;
+}
+// ─── Stuck detection ──────────────────────────────────────────────────────
+function detectStuck(history) {
+    if (history.length < STUCK_THRESHOLD)
+        return undefined;
+    // Count consecutive actions from the end where snapshot hash didn't change
+    let consecutiveStatic = 0;
+    const last = history[history.length - 1];
+    for (let i = history.length - 1; i >= 0; i--) {
+        if (history[i].snapshotHash === last.snapshotHash) {
+            consecutiveStatic++;
+        }
+        else {
+            break;
+        }
+    }
+    if (consecutiveStatic < STUCK_THRESHOLD)
+        return undefined;
+    // Build contextual suggestions
+    const suggestions = [];
+    const recentActions = history.slice(-consecutiveStatic);
+    const actionTypes = new Set(recentActions.map((r) => r.actionType));
+    if (!actionTypes.has("scroll")) {
+        suggestions.push("Try scrolling down — content may be below the fold");
+    }
+    if (actionTypes.size === 1 && actionTypes.has("click")) {
+        suggestions.push("Try a different element or check if the page has iframes");
+    }
+    const recentUrls = new Set(recentActions.map((r) => r.url));
+    if (recentUrls.size === 1 && consecutiveStatic >= 5) {
+        suggestions.push("Consider navigating to a different page");
+    }
+    suggestions.push("The page may need JavaScript to update. Try waiting or using extract with JS evaluation.");
+    return {
+        stuckActions: consecutiveStatic,
+        message: `Page appears static after ${consecutiveStatic} actions`,
+        suggestions,
+    };
+}
+// ─── Format harness output ────────────────────────────────────────────────
+export function formatHarnessOutput(state) {
+    const lines = ["--- Harness Intelligence ---"];
+    lines.push(`Outcome: ${state.outcome} — ${state.outcomeDetail}`);
+    if (state.loopWarning) {
+        lines.push(`\u26A0 Loop detected: ${state.loopWarning.message} ${state.loopWarning.suggestion}`);
+    }
+    if (state.stuckWarning) {
+        lines.push(`\u26A0 Stuck: ${state.stuckWarning.message}`);
+        for (const s of state.stuckWarning.suggestions) {
+            lines.push(`  - ${s}`);
+        }
+    }
+    return lines.join("\n");
+}
+// ─── Ring buffer helper ──────────────────────────────────────────────────
+function pushAndCap(sessionId, record) {
+    const history = histories.get(sessionId) ?? [];
+    history.push(record);
+    // Ring buffer: cap at MAX_HISTORY
+    if (history.length > MAX_HISTORY) {
+        history.splice(0, history.length - MAX_HISTORY);
+        // Re-index after splice
+        for (let i = 0; i < history.length; i++) {
+            history[i].index = i;
+        }
+    }
+    histories.set(sessionId, history);
+    return history;
+}
+// ─── Main class ───────────────────────────────────────────────────────────
+export class HarnessIntelligence {
+    /** Record pre-action state. Call BEFORE performing an action. */
+    static capturePreState(sessionId, url, snapshotText) {
+        preStates.set(sessionId, {
+            url,
+            snapshotHash: djb2(snapshotText),
+        });
+        logger.debug("harness:pre-state", { sessionId, url });
+    }
+    /** Analyze post-action state. Call AFTER performing an action. Returns guidance. */
+    static analyzePostAction(sessionId, actionType, target, value, url, snapshotText, error) {
+        const startTime = Date.now();
+        const preState = preStates.get(sessionId);
+        const postHash = djb2(snapshotText);
+        // 1. Classify outcome
+        const { outcome, detail } = classifyOutcome(preState, url, postHash, snapshotText, error, actionType, target);
+        // 2. Record in history
+        const history = histories.get(sessionId) ?? [];
+        const record = {
+            index: history.length,
+            timestamp: Date.now(),
+            actionType,
+            target,
+            value,
+            url,
+            snapshotHash: postHash,
+            outcome,
+            duration: preState ? Date.now() - startTime : 0,
+        };
+        const updatedHistory = pushAndCap(sessionId, record);
+        // Clean up pre-state
+        preStates.delete(sessionId);
+        // 3. Detect loops
+        const loopWarning = detectLoop(updatedHistory);
+        // 4. Detect stuck
+        const stuckWarning = detectStuck(updatedHistory);
+        const state = {
+            outcome,
+            outcomeDetail: detail,
+            loopWarning,
+            stuckWarning,
+        };
+        logger.debug("harness:post-action", {
+            sessionId,
+            outcome,
+            loopDetected: !!loopWarning,
+            stuckDetected: !!stuckWarning,
+        });
+        return state;
+    }
+    /**
+     * Record a tool call (navigate, snapshot, batch_actions, execute, etc.)
+     * so that session_memory returns a complete timeline — not just `act` calls.
+     */
+    static recordToolCall(sessionId, toolName, params, resultSummary, durationMs) {
+        const history = histories.get(sessionId) ?? [];
+        const record = {
+            index: history.length,
+            timestamp: Date.now(),
+            actionType: toolName,
+            target: undefined,
+            value: undefined,
+            url: params.url ?? "",
+            snapshotHash: "",
+            outcome: "SUCCESS",
+            duration: durationMs,
+            toolCall: {
+                toolName,
+                params,
+                resultSummary,
+            },
+        };
+        pushAndCap(sessionId, record);
+        logger.debug("harness:tool-call", { sessionId, toolName, resultSummary });
+    }
+    /** Get action history for a session */
+    static getHistory(sessionId, limit) {
+        const history = histories.get(sessionId) ?? [];
+        if (limit !== undefined && limit > 0) {
+            return history.slice(-limit);
+        }
+        return [...history];
+    }
+    /** Clear all state for a session */
+    static clearSession(sessionId) {
+        preStates.delete(sessionId);
+        histories.delete(sessionId);
+        logger.debug("harness:clear", { sessionId });
+    }
+    /** Get loop/stuck status without recording an action (for diagnostics) */
+    static diagnose(sessionId) {
+        const history = histories.get(sessionId) ?? [];
+        return {
+            loopWarning: detectLoop(history),
+            stuckWarning: detectStuck(history),
+        };
+    }
+}
+// ─── Exported helpers for testing ─────────────────────────────────────────
+export { djb2, extractRoleFromSnapshot };
+export default HarnessIntelligence;

package/dist/humanize-fingerprint.d.ts

@@ -0,0 +1,42 @@
+export interface Fingerprint {
+    userAgent: string;
+    platform: string;
+    viewport: {
+        width: number;
+        height: number;
+    };
+    screen: {
+        width: number;
+        height: number;
+    };
+    devicePixelRatio: number;
+    deviceMemory: number;
+    hardwareConcurrency: number;
+    timezone: string;
+    languages: string[];
+    webgl: {
+        vendor: string;
+        renderer: string;
+    };
+    colorDepth: number;
+    maxTouchPoints: number;
+    doNotTrack: string | null;
+    cookieEnabled: boolean;
+    pdfViewerEnabled: boolean;
+}
+export type BrowserFamily = "chrome" | "firefox" | "edge";
+export interface FingerprintOptions {
+    browserFamily?: BrowserFamily;
+}
+/**
+ * Generate a consistent, realistic browser fingerprint profile.
+ * The fingerprint is internally coherent:
+ * - Platform matches userAgent string
+ * - deviceMemory correlates with screen resolution tier
+ * - hardwareConcurrency scales with deviceMemory
+ * - GPU, timezone, and languages are weighted by real-world distributions
+ *
+ * @param opts - Configuration options
+ * @returns A complete fingerprint profile for Playwright context configuration
+ */
+export declare function generateFingerprint(opts?: FingerprintOptions): Fingerprint;

package/dist/humanize-fingerprint.js

@@ -0,0 +1,161 @@
+// ─── Browser Fingerprint Generation ────────────────────────────────────────
+//
+// Generates internally-coherent browser fingerprint profiles for stealth
+// automation. Platform matches userAgent, deviceMemory correlates with
+// screen tier, GPU and timezone are weighted by real-world distribution.
+// Ported from the validated humanize.js prototype.
+//
+// Integration point: import { generateFingerprint } from "./humanize-fingerprint.js"
+// then pass the returned profile to session_create options or use with
+// stealth.getContextOptions() in src/session-manager.ts.
+//
+// Standalone module — no cross-dependencies on other humanize modules.
+/**
+ * Common screen resolutions weighted by real-world usage (StatCounter 2025).
+ */
+const SCREEN_RESOLUTIONS = [
+    { width: 1920, height: 1080, weight: 0.30 },
+    { width: 1366, height: 768, weight: 0.15 },
+    { width: 1536, height: 864, weight: 0.10 },
+    { width: 2560, height: 1440, weight: 0.12 },
+    { width: 1440, height: 900, weight: 0.08 },
+    { width: 1680, height: 1050, weight: 0.05 },
+    { width: 3840, height: 2160, weight: 0.07 },
+    { width: 1280, height: 720, weight: 0.06 },
+    { width: 1600, height: 900, weight: 0.04 },
+    { width: 2560, height: 1600, weight: 0.03 },
+];
+const PLATFORMS = [
+    { name: "Win32", os: "Windows NT 10.0; Win64; x64", weight: 0.60 },
+    { name: "MacIntel", os: "Macintosh; Intel Mac OS X 10_15_7", weight: 0.25 },
+    { name: "Linux x86_64", os: "X11; Linux x86_64", weight: 0.15 },
+];
+const TIMEZONES = [
+    { tz: "America/New_York", weight: 0.20 },
+    { tz: "America/Chicago", weight: 0.12 },
+    { tz: "America/Denver", weight: 0.06 },
+    { tz: "America/Los_Angeles", weight: 0.15 },
+    { tz: "Europe/London", weight: 0.10 },
+    { tz: "Europe/Berlin", weight: 0.08 },
+    { tz: "Europe/Paris", weight: 0.06 },
+    { tz: "Asia/Tokyo", weight: 0.05 },
+    { tz: "Asia/Shanghai", weight: 0.05 },
+    { tz: "Australia/Sydney", weight: 0.04 },
+    { tz: "America/Sao_Paulo", weight: 0.04 },
+    { tz: "Asia/Kolkata", weight: 0.05 },
+];
+const LANGUAGES = [
+    { langs: ["en-US", "en"], weight: 0.55 },
+    { langs: ["en-GB", "en"], weight: 0.10 },
+    { langs: ["de-DE", "de", "en"], weight: 0.08 },
+    { langs: ["fr-FR", "fr", "en"], weight: 0.06 },
+    { langs: ["es-ES", "es", "en"], weight: 0.06 },
+    { langs: ["ja-JP", "ja"], weight: 0.05 },
+    { langs: ["pt-BR", "pt", "en"], weight: 0.05 },
+    { langs: ["zh-CN", "zh"], weight: 0.05 },
+];
+const GPUS = [
+    { vendor: "Google Inc. (NVIDIA)", renderer: "ANGLE (NVIDIA, NVIDIA GeForce RTX 3060 Direct3D11 vs_5_0 ps_5_0)", weight: 0.12 },
+    { vendor: "Google Inc. (NVIDIA)", renderer: "ANGLE (NVIDIA, NVIDIA GeForce RTX 4070 Direct3D11 vs_5_0 ps_5_0)", weight: 0.10 },
+    { vendor: "Google Inc. (Intel)", renderer: "ANGLE (Intel, Intel(R) UHD Graphics 630 Direct3D11 vs_5_0 ps_5_0)", weight: 0.15 },
+    { vendor: "Google Inc. (Intel)", renderer: "ANGLE (Intel, Intel(R) Iris(R) Xe Graphics Direct3D11 vs_5_0 ps_5_0)", weight: 0.12 },
+    { vendor: "Google Inc. (AMD)", renderer: "ANGLE (AMD, AMD Radeon RX 6700 XT Direct3D11 vs_5_0 ps_5_0)", weight: 0.08 },
+    { vendor: "Apple", renderer: "Apple M1", weight: 0.15 },
+    { vendor: "Apple", renderer: "Apple M2", weight: 0.10 },
+    { vendor: "Mesa", renderer: "Mesa Intel(R) UHD Graphics 630 (CFL GT2)", weight: 0.08 },
+    { vendor: "Mesa", renderer: "llvmpipe (LLVM 15.0.7, 256 bits)", weight: 0.10 },
+];
+// ─── Weighted Selection ────────────────────────────────────────────────────
+/**
+ * Weighted random selection from an array of objects with a `weight` property.
+ */
+function weightedPick(items) {
+    const total = items.reduce((s, i) => s + i.weight, 0);
+    let r = Math.random() * total;
+    for (const item of items) {
+        r -= item.weight;
+        if (r <= 0)
+            return item;
+    }
+    return items[items.length - 1];
+}
+// ─── Generator ─────────────────────────────────────────────────────────────
+/**
+ * Generate a consistent, realistic browser fingerprint profile.
+ * The fingerprint is internally coherent:
+ * - Platform matches userAgent string
+ * - deviceMemory correlates with screen resolution tier
+ * - hardwareConcurrency scales with deviceMemory
+ * - GPU, timezone, and languages are weighted by real-world distributions
+ *
+ * @param opts - Configuration options
+ * @returns A complete fingerprint profile for Playwright context configuration
+ */
+export function generateFingerprint(opts = {}) {
+    const family = opts.browserFamily ?? "chrome";
+    // Pick screen resolution
+    const screen = weightedPick(SCREEN_RESOLUTIONS);
+    // Browser version ranges (realistic as of early 2026)
+    const versions = {
+        chrome: { min: 124, max: 136 },
+        firefox: { min: 124, max: 132 },
+        edge: { min: 124, max: 136 },
+    };
+    const vRange = versions[family] ?? versions.chrome;
+    const majorVersion = vRange.min + Math.floor(Math.random() * (vRange.max - vRange.min + 1));
+    // Platform
+    const platform = weightedPick(PLATFORMS);
+    // Build userAgent
+    let userAgent;
+    const chromeBuild = `${majorVersion}.0.${3000 + Math.floor(Math.random() * 3000)}.${Math.floor(Math.random() * 200)}`;
+    if (family === "chrome") {
+        userAgent = `Mozilla/5.0 (${platform.os}) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/${chromeBuild} Safari/537.36`;
+    }
+    else if (family === "firefox") {
+        userAgent = `Mozilla/5.0 (${platform.os}; rv:${majorVersion}.0) Gecko/20100101 Firefox/${majorVersion}.0`;
+    }
+    else {
+        userAgent = `Mozilla/5.0 (${platform.os}) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/${chromeBuild} Safari/537.36 Edg/${chromeBuild}`;
+    }
+    // Viewport (slightly smaller than screen to simulate browser chrome)
+    const chromeHeights = [80, 90, 100, 110];
+    const chromeHeight = chromeHeights[Math.floor(Math.random() * chromeHeights.length)];
+    const viewport = {
+        width: screen.width,
+        height: screen.height - chromeHeight,
+    };
+    // Device memory (correlated with screen resolution tier)
+    const isHighEnd = screen.width >= 2560;
+    const highEndMemory = [8, 16, 32];
+    const normalMemory = [4, 8, 16];
+    const deviceMemory = isHighEnd
+        ? highEndMemory[Math.floor(Math.random() * highEndMemory.length)]
+        : normalMemory[Math.floor(Math.random() * normalMemory.length)];
+    // Hardware concurrency (correlated similarly)
+    const highEndCores = [8, 12, 16];
+    const normalCores = [4, 6, 8];
+    const hardwareConcurrency = isHighEnd
+        ? highEndCores[Math.floor(Math.random() * highEndCores.length)]
+        : normalCores[Math.floor(Math.random() * normalCores.length)];
+    // Timezone, languages, GPU
+    const tz = weightedPick(TIMEZONES);
+    const lang = weightedPick(LANGUAGES);
+    const gpu = weightedPick(GPUS);
+    return {
+        userAgent,
+        platform: platform.name,
+        viewport,
+        screen: { width: screen.width, height: screen.height },
+        devicePixelRatio: screen.width >= 2560 ? 2 : 1,
+        deviceMemory,
+        hardwareConcurrency,
+        timezone: tz.tz,
+        languages: lang.langs,
+        webgl: { vendor: gpu.vendor, renderer: gpu.renderer },
+        colorDepth: 24,
+        maxTouchPoints: platform.name === "Win32" ? (Math.random() < 0.3 ? 10 : 0) : 0,
+        doNotTrack: Math.random() < 0.15 ? "1" : null,
+        cookieEnabled: true,
+        pdfViewerEnabled: true,
+    };
+}