leapfrog-mcp 0.6.2 → 0.6.3

package/dist/humanize-scroll.js

@@ -0,0 +1,185 @@
+// ─── Humanized Scrolling ───────────────────────────────────────────────────
+//
+// Inertial scroll simulation with ramp-up and momentum decay, variable
+// scroll amounts, read-pause-scroll cycles, overshoot/scroll-back, and
+// cursor-scroll correlation (sympathetic mouse movement).
+//
+// Ported from the validated humanize.js prototype (tested on 3090 box,
+// statistically verified).
+//
+// Integration point: import { humanScroll } from "./humanize-scroll.js"
+// then call humanScroll.scroll(page, distance) inside the act tool handler
+// (src/index.ts) as an alternative to page.mouse.wheel().
+//
+// Standalone module — no cross-dependencies on other humanize modules.
+import { gaussianRandom, clamp, humanDelay, sleep, isHumanizeEnabled, normalRandom } from "./humanize-utils.js";
+// ─── Scroll Plan ───────────────────────────────────────────────────────────
+/**
+ * Generate a human-like scroll plan for a given pixel distance.
+ * Simulates inertial scrolling with ease-out momentum decay.
+ *
+ * The scroll is broken into increments that start small (ramp-up / finger
+ * contact), hit peak velocity, then taper off (friction / momentum loss),
+ * similar to real touchpad scrolling.
+ *
+ * @param distance - Total scroll distance in pixels (positive = down)
+ * @param opts - Configuration options
+ * @returns Array of scroll steps with deltas and delays
+ */
+export function humanScrollPlan(distance, opts = {}) {
+    const maxIncrement = opts.maxIncrement ?? 120;
+    const friction = opts.friction ?? 0.82;
+    const direction = distance >= 0 ? 1 : -1;
+    let remaining = Math.abs(distance);
+    const steps = [];
+    let cumulative = 0;
+    // Phase 1: Ramp-up (2-3 small increments to simulate finger contact)
+    const rampSteps = Math.floor(Math.random() * 2) + 2;
+    for (let i = 0; i < rampSteps && remaining > 0; i++) {
+        const fraction = (i + 1) / (rampSteps + 1);
+        const base = maxIncrement * fraction * 0.6;
+        const delta = Math.min(Math.round(base + gaussianRandom(0, 5)), remaining);
+        remaining -= delta;
+        cumulative += delta * direction;
+        steps.push({
+            delta: delta * direction,
+            delay: humanDelay(12, 25),
+            cumulative,
+        });
+    }
+    // Phase 2: Momentum decay (ease-out)
+    let velocity = maxIncrement + gaussianRandom(0, 15);
+    while (remaining > 2) {
+        velocity *= friction + gaussianRandom(0, 0.03);
+        velocity = clamp(velocity, 3, maxIncrement * 1.2);
+        const delta = Math.min(Math.round(velocity), remaining);
+        remaining -= delta;
+        cumulative += delta * direction;
+        steps.push({
+            delta: delta * direction,
+            delay: humanDelay(14, 30),
+            cumulative,
+        });
+    }
+    // Mop up any remainder
+    if (remaining > 0) {
+        cumulative += remaining * direction;
+        steps.push({
+            delta: remaining * direction,
+            delay: humanDelay(20, 50),
+            cumulative,
+        });
+    }
+    return steps;
+}
+// ─── HumanScroll Class ─────────────────────────────────────────────────────
+export class HumanScroll {
+    /**
+     * Whether humanized scrolling is enabled.
+     * Returns false unless LEAP_HUMANIZE=true or LEAP_HUMANIZE=1 is set.
+     */
+    isEnabled() {
+        return isHumanizeEnabled();
+    }
+    /**
+     * Scroll the page by the given pixel distance using a human-like
+     * ramp-up + momentum decay pattern.
+     *
+     * Each step in the scroll plan is dispatched as a mouse wheel event
+     * with an inter-step delay to simulate real scrolling inertia.
+     *
+     * Enhancements over basic scroll:
+     * - Variable scroll amounts (normalRandom instead of fixed)
+     * - Read-pause-scroll cycles (800-3000ms reading gaps between chunks)
+     * - 10% chance of overshoot + scroll-back correction
+     * - Sympathetic cursor micro-movements during scrolling
+     *
+     * No-op if humanization is disabled.
+     *
+     * @param page - Playwright page instance
+     * @param distance - Total scroll distance in pixels (positive = down, negative = up)
+     */
+    async scroll(page, distance) {
+        if (!this.isEnabled())
+            return;
+        // Variable scroll amount: apply Gaussian variation to the requested distance.
+        // Humans rarely scroll an exact number of pixels — add +/-15% noise.
+        const variableDistance = distance === 0
+            ? 0
+            : Math.round(distance + gaussianRandom(0, Math.abs(distance) * 0.05));
+        // Break long scrolls into read-pause-scroll chunks.
+        // Each chunk is a "scroll gesture" followed by a reading pause.
+        const chunkSize = Math.round(Math.abs(normalRandom(350, 100)));
+        const effectiveChunk = Math.max(chunkSize, 80); // floor at 80px
+        const totalAbs = Math.abs(variableDistance);
+        const direction = variableDistance >= 0 ? 1 : -1;
+        let scrolled = 0;
+        let isFirstChunk = true;
+        while (scrolled < totalAbs) {
+            // Read-pause: wait between scroll gestures (skip before first chunk)
+            if (!isFirstChunk) {
+                const readPause = humanDelay(800, 3000);
+                await sleep(readPause);
+            }
+            isFirstChunk = false;
+            const chunkRemaining = Math.min(effectiveChunk, totalAbs - scrolled);
+            const plan = humanScrollPlan(chunkRemaining * direction);
+            // Sympathetic cursor movement: small random mouse moves during scrolling
+            // to simulate hand-on-trackpad/mouse-wheel posture
+            for (const step of plan) {
+                await sleep(step.delay);
+                await page.mouse.wheel(0, step.delta);
+                // Cursor-scroll correlation: ~30% chance of small sympathetic mouse move
+                if (Math.random() < 0.3) {
+                    const sympatheticX = gaussianRandom(0, 1.5);
+                    const sympatheticY = gaussianRandom(0, 2.0);
+                    try {
+                        await page.mouse.move(400 + sympatheticX, // approximate center-ish x with jitter
+                        300 + sympatheticY, // approximate center-ish y with jitter
+                        { steps: 1 });
+                    }
+                    catch {
+                        // Mouse move during scroll can fail if page is navigating — safe to ignore
+                    }
+                }
+            }
+            scrolled += chunkRemaining;
+        }
+        // Overshoot + scroll-back: 10% of scroll operations overshoot then correct
+        if (totalAbs > 0 && Math.random() < 0.10) {
+            const overshootAmount = Math.round(50 + Math.random() * 50); // 50-100px
+            const overshootPlan = humanScrollPlan(overshootAmount * direction);
+            for (const step of overshootPlan) {
+                await sleep(step.delay);
+                await page.mouse.wheel(0, step.delta);
+            }
+            // Brief pause before correction (realizing overshoot)
+            await sleep(humanDelay(150, 400));
+            // Scroll back to correct
+            const correctionPlan = humanScrollPlan(overshootAmount * -direction);
+            for (const step of correctionPlan) {
+                await sleep(step.delay);
+                await page.mouse.wheel(0, step.delta);
+            }
+        }
+    }
+    /**
+     * Scroll with variable distance. Uses normalRandom(350, 100) to determine
+     * a natural scroll distance, then executes the humanized scroll.
+     *
+     * Useful when the caller just wants "scroll down some" without a specific
+     * pixel target.
+     *
+     * @param page - Playwright page instance
+     * @param direction - "down" (positive) or "up" (negative)
+     */
+    async scrollVariable(page, direction = "down") {
+        if (!this.isEnabled())
+            return;
+        const amount = Math.round(Math.abs(normalRandom(350, 100)));
+        const distance = direction === "down" ? amount : -amount;
+        await this.scroll(page, distance);
+    }
+}
+export const humanScroll = new HumanScroll();
+export default humanScroll;

package/dist/humanize-typing.d.ts

@@ -0,0 +1,60 @@
+import type { Page } from "playwright-core";
+export interface KeystrokeEvent {
+    /** The character to press (or '\b' for backspace) */
+    char: string;
+    /** Delay before this keystroke in ms (flight time / inter-key interval) */
+    delay: number;
+    /** Key dwell time in ms (how long the key is held down) */
+    dwell: number;
+    /** Whether this keystroke is a typo */
+    isTypo: boolean;
+    /** If non-null, the correct character that was retyped after a typo correction */
+    correction: string | null;
+    /** Whether this keystroke should overlap with the previous key release (rollover) */
+    rollover: boolean;
+}
+export interface TypeOptions {
+    /** Median inter-key delay in ms (log-normal center). Default: 200 */
+    baseDelay?: number;
+    /** Base probability of a typo per alphabetic character. Default: 0.02 */
+    typoRate?: number;
+}
+/**
+ * Generate a sequence of keystroke events with humanized timing and typo simulation.
+ *
+ * Timing model (research-backed):
+ * - Base delay: Log-normal with 200ms median, sigma 0.45 (right-skewed, heavy-tailed)
+ * - Bigram-aware: hand-alternation pairs 30% faster, same-finger pairs 40% slower
+ * - Longer pauses at word boundaries (~250ms median) and after punctuation
+ * - Burst typing: occasional faster sequences (50% of base delay)
+ * - Key dwell time: log-normal with 70ms median (50-130ms typical range)
+ * - Rollover: next key pressed before previous released on fast hand-alternation bigrams
+ *
+ * Typo model:
+ * - 2% base rate for alphabetic characters
+ * - Higher rate (4%) for characters with many adjacent keys
+ * - Typo character is chosen from QWERTY adjacency map
+ * - Correction: backspace + retype after a short pause (200-400ms)
+ */
+export declare function humanTypeString(text: string, opts?: TypeOptions): KeystrokeEvent[];
+export declare class HumanTyping {
+    /**
+     * Whether humanized typing is enabled.
+     * Returns false unless LEAP_HUMANIZE=true or LEAP_HUMANIZE=1 is set.
+     */
+    isEnabled(): boolean;
+    /**
+     * Type text with humanized inter-key delays, key dwell time, rollover,
+     * occasional typos, and corrections.
+     *
+     * Uses page.keyboard.down() / up() for full timing control:
+     *   - Per-key flight time (variable IKI via log-normal distribution)
+     *   - Per-key dwell time (variable hold duration)
+     *   - Rollover simulation (next keydown before previous keyup)
+     *
+     * No-op if humanization is disabled.
+     */
+    typeText(page: Page, text: string, opts?: TypeOptions): Promise<void>;
+}
+export declare const humanTyping: HumanTyping;
+export default humanTyping;

package/dist/humanize-typing.js

@@ -0,0 +1,258 @@
+// ─── Humanized Typing ──────────────────────────────────────────────────────
+//
+// Log-normal–distributed inter-key delays, key dwell time, rollover typing,
+// bigram-aware timing, burst typing, and a QWERTY-adjacency typo model with
+// backspace correction.
+//
+// Research basis: 03-typing-humanization.md
+//   - Log-normal distribution (right-skewed, heavy-tailed — matches 136M
+//     keystrokes study, Monaco et al. 2021 log-logistic finding)
+//   - 200ms median IKI (~52 WPM, population mean)
+//   - Key dwell time 70ms median (50-130ms range)
+//   - Rollover typing on hand-alternation bigrams
+//   - Bigram-aware speed multipliers (hand alternation, same-finger)
+//
+// Integration point: import { humanTyping } from "./humanize-typing.js"
+// then call humanTyping.typeText(page, text) inside the act tool handler
+// (src/index.ts) as an alternative to page.keyboard.type().
+//
+// Standalone module — no cross-dependencies on other humanize modules.
+import { humanDelay, logNormalDelay, sleep, isHumanizeEnabled } from "./humanize-utils.js";
+// ─── QWERTY Adjacency Map ──────────────────────────────────────────────────
+/**
+ * QWERTY adjacency map for simulating realistic typos.
+ * Each key maps to its physically adjacent keys on a standard QWERTY layout.
+ */
+const QWERTY_ADJACENT = {
+    q: ["w", "a"], w: ["q", "e", "a", "s"], e: ["w", "r", "s", "d"],
+    r: ["e", "t", "d", "f"], t: ["r", "y", "f", "g"], y: ["t", "u", "g", "h"],
+    u: ["y", "i", "h", "j"], i: ["u", "o", "j", "k"], o: ["i", "p", "k", "l"],
+    p: ["o", "l"],
+    a: ["q", "w", "s", "z"], s: ["a", "w", "e", "d", "z", "x"],
+    d: ["s", "e", "r", "f", "x", "c"], f: ["d", "r", "t", "g", "c", "v"],
+    g: ["f", "t", "y", "h", "v", "b"], h: ["g", "y", "u", "j", "b", "n"],
+    j: ["h", "u", "i", "k", "n", "m"], k: ["j", "i", "o", "l", "m"],
+    l: ["k", "o", "p"],
+    z: ["a", "s", "x"], x: ["z", "s", "d", "c"], c: ["x", "d", "f", "v"],
+    v: ["c", "f", "g", "b"], b: ["v", "g", "h", "n"], n: ["b", "h", "j", "m"],
+    m: ["n", "j", "k"],
+};
+// ─── Bigram Timing ─────────────────────────────────────────────────────────
+/**
+ * Hand-alternation bigrams — typed fastest because both hands work in parallel.
+ * (Salthouse 1986: 30-60ms faster than same-hand bigrams)
+ */
+const ALTERNATING_BIGRAMS = new Set([
+    "th", "ht", "di", "id", "en", "ne", "ri", "ir", "to", "ot",
+    "do", "od", "gu", "ug", "ha", "ah", "fi", "if", "pe", "ep",
+    "wo", "ow", "bi", "ib", "tu", "ut", "ry", "yr", "ck", "kc",
+]);
+/**
+ * Same-finger bigrams — typed slowest because one finger must travel between rows.
+ */
+const SAME_FINGER_BIGRAMS = new Set([
+    "ed", "de", "nu", "un", "my", "ym", "ce", "ec", "rb", "br",
+    "ft", "tf", "ju", "uj", "ki", "ik", "lo", "ol", "ws", "sw",
+]);
+/**
+ * Return a speed multiplier based on the bigram (previous + current character).
+ * Hand alternation = 0.7x (30% faster), same finger = 1.4x (40% slower).
+ */
+function bigramMultiplier(prev, curr) {
+    const pair = (prev + curr).toLowerCase();
+    if (ALTERNATING_BIGRAMS.has(pair))
+        return 0.7;
+    if (SAME_FINGER_BIGRAMS.has(pair))
+        return 1.4;
+    return 1.0;
+}
+// ─── Dwell Time ────────────────────────────────────────────────────────────
+/** Default dwell time config (research: 50-130ms range, median ~70ms) */
+const DWELL_MEDIAN = 70;
+const DWELL_SIGMA = 0.3;
+/**
+ * Compute key dwell time (keydown-to-keyup duration) for a character.
+ * Backspace has a shorter dwell (~40ms). Regular keys ~70ms median.
+ */
+function computeDwell(char) {
+    if (char === "\b")
+        return logNormalDelay(40, 0.25, 20);
+    return logNormalDelay(DWELL_MEDIAN, DWELL_SIGMA, 30);
+}
+// ─── Keystroke Plan ────────────────────────────────────────────────────────
+/**
+ * Generate a sequence of keystroke events with humanized timing and typo simulation.
+ *
+ * Timing model (research-backed):
+ * - Base delay: Log-normal with 200ms median, sigma 0.45 (right-skewed, heavy-tailed)
+ * - Bigram-aware: hand-alternation pairs 30% faster, same-finger pairs 40% slower
+ * - Longer pauses at word boundaries (~250ms median) and after punctuation
+ * - Burst typing: occasional faster sequences (50% of base delay)
+ * - Key dwell time: log-normal with 70ms median (50-130ms typical range)
+ * - Rollover: next key pressed before previous released on fast hand-alternation bigrams
+ *
+ * Typo model:
+ * - 2% base rate for alphabetic characters
+ * - Higher rate (4%) for characters with many adjacent keys
+ * - Typo character is chosen from QWERTY adjacency map
+ * - Correction: backspace + retype after a short pause (200-400ms)
+ */
+export function humanTypeString(text, opts = {}) {
+    const baseDelay = opts.baseDelay ?? 200;
+    const typoRate = opts.typoRate ?? 0.02;
+    const events = [];
+    let inBurst = false;
+    let burstRemaining = 0;
+    let prevChar = "";
+    // ── Fatigue model ─────────────────────────────────────────────────
+    // After ~30 seconds of continuous typing (estimated from char count × avg IKI),
+    // gradually slow down by 10-15%. This simulates reduced motor performance
+    // during sustained input — a strong human signal absent in bots.
+    const FATIGUE_ONSET_CHARS = 150; // ~30s at 200ms avg IKI
+    const FATIGUE_MAX_MULTIPLIER = 1.15; // 15% slower at peak fatigue
+    const FATIGUE_RAMP_CHARS = 100; // chars over which fatigue ramps from 1.0 to max
+    // Log-normal sigma: controls the right-skew / heavy tail.
+    // 0.45 produces mode ~170ms, mean ~215ms with occasional spikes to 400-600ms.
+    const ikiSigma = 0.45;
+    for (let i = 0; i < text.length; i++) {
+        const char = text[i];
+        const lower = char.toLowerCase();
+        const isAlpha = /[a-z]/.test(lower);
+        // ── Fatigue multiplier ───────────────────────────────────────
+        let fatigueMultiplier = 1.0;
+        if (i > FATIGUE_ONSET_CHARS) {
+            const fatigueProgress = Math.min(1.0, (i - FATIGUE_ONSET_CHARS) / FATIGUE_RAMP_CHARS);
+            fatigueMultiplier = 1.0 + fatigueProgress * (FATIGUE_MAX_MULTIPLIER - 1.0);
+        }
+        // ── Compute inter-key delay (flight time) ──────────────────────
+        let delay;
+        if (burstRemaining > 0) {
+            // Burst: 50% of base delay, still log-normal distributed
+            delay = logNormalDelay(Math.round(baseDelay * 0.5), 0.35, 25);
+            burstRemaining--;
+            if (burstRemaining === 0)
+                inBurst = false;
+        }
+        else if (char === " ") {
+            // Word boundary: research shows ~250ms median inter-word pause
+            delay = logNormalDelay(250, 0.4, 80);
+        }
+        else if (/[.,;:!?]/.test(char)) {
+            // Punctuation: slightly longer pause
+            delay = logNormalDelay(200, 0.4, 80);
+        }
+        else if (char === "\n") {
+            // Line break: cognitive pause
+            delay = logNormalDelay(400, 0.5, 150);
+        }
+        else {
+            // Regular character: log-normal around baseDelay with bigram adjustment
+            const multiplier = prevChar ? bigramMultiplier(prevChar, lower) : 1.0;
+            delay = logNormalDelay(Math.round(baseDelay * multiplier), ikiSigma, 40);
+        }
+        // Apply fatigue to the computed delay
+        delay = Math.round(delay * fatigueMultiplier);
+        // ── Cognitive pause: 12% chance of a think-pause at word starts ──
+        if (prevChar === " " && isAlpha && !inBurst && Math.random() < 0.12) {
+            delay = logNormalDelay(400, 0.5, 150);
+        }
+        // ── Burst initiation: ~8% chance after spaces ──────────────────
+        if (!inBurst && char === " " && Math.random() < 0.08) {
+            inBurst = true;
+            burstRemaining = Math.floor(Math.random() * 6) + 3; // 3-8 chars
+        }
+        // ── Rollover detection ─────────────────────────────────────────
+        // On hand-alternation bigrams with short flight times, the next key
+        // is pressed before the previous key is released. This is a strong
+        // human signal that sequential bots lack.
+        let rollover = false;
+        if (prevChar && delay < 180) {
+            const pair = (prevChar + lower).toLowerCase();
+            if (ALTERNATING_BIGRAMS.has(pair) && Math.random() < 0.3) {
+                rollover = true;
+            }
+        }
+        // ── Compute dwell time ─────────────────────────────────────────
+        const dwell = computeDwell(char);
+        // ── Typo check ─────────────────────────────────────────────────
+        const adjacents = QWERTY_ADJACENT[lower];
+        const effectiveRate = adjacents && adjacents.length >= 5 ? typoRate * 2 : typoRate;
+        if (isAlpha && Math.random() < effectiveRate && adjacents) {
+            const typoChar = adjacents[Math.floor(Math.random() * adjacents.length)];
+            const displayTypo = char === char.toUpperCase() ? typoChar.toUpperCase() : typoChar;
+            // Push the wrong keystroke
+            events.push({ char: displayTypo, delay, dwell: computeDwell(displayTypo), isTypo: true, correction: null, rollover });
+            // Push the backspace after a reaction delay
+            events.push({ char: "\b", delay: humanDelay(150, 350), dwell: computeDwell("\b"), isTypo: false, correction: null, rollover: false });
+            // Push the correct keystroke
+            events.push({ char, delay: humanDelay(50, 120), dwell, isTypo: false, correction: char, rollover: false });
+        }
+        else {
+            events.push({ char, delay, dwell, isTypo: false, correction: null, rollover });
+        }
+        prevChar = lower;
+    }
+    return events;
+}
+// ─── HumanTyping Class ─────────────────────────────────────────────────────
+export class HumanTyping {
+    /**
+     * Whether humanized typing is enabled.
+     * Returns false unless LEAP_HUMANIZE=true or LEAP_HUMANIZE=1 is set.
+     */
+    isEnabled() {
+        return isHumanizeEnabled();
+    }
+    /**
+     * Type text with humanized inter-key delays, key dwell time, rollover,
+     * occasional typos, and corrections.
+     *
+     * Uses page.keyboard.down() / up() for full timing control:
+     *   - Per-key flight time (variable IKI via log-normal distribution)
+     *   - Per-key dwell time (variable hold duration)
+     *   - Rollover simulation (next keydown before previous keyup)
+     *
+     * No-op if humanization is disabled.
+     */
+    async typeText(page, text, opts) {
+        if (!this.isEnabled())
+            return;
+        const events = humanTypeString(text, opts);
+        let prevKeyDown = null;
+        for (const event of events) {
+            const key = event.char === "\b" ? "Backspace" : event.char;
+            if (event.rollover && prevKeyDown) {
+                // Rollover: press next key BEFORE releasing previous key.
+                // Overlap by a portion of the flight time.
+                const overlap = logNormalDelay(25, 0.3, 10);
+                const preOverlapWait = Math.max(0, event.delay - overlap);
+                await sleep(preOverlapWait);
+                await page.keyboard.down(key);
+                await sleep(overlap);
+                await page.keyboard.up(prevKeyDown);
+                await sleep(event.dwell);
+                await page.keyboard.up(key);
+                prevKeyDown = null;
+            }
+            else {
+                // Release previous key if still held (shouldn't normally happen,
+                // but guard against it)
+                if (prevKeyDown) {
+                    await page.keyboard.up(prevKeyDown);
+                    prevKeyDown = null;
+                }
+                // Standard keystroke: wait flight time, then keydown, hold, keyup
+                await sleep(event.delay);
+                await page.keyboard.down(key);
+                await sleep(event.dwell);
+                await page.keyboard.up(key);
+            }
+        }
+        // Ensure final key is released
+        if (prevKeyDown) {
+            await page.keyboard.up(prevKeyDown);
+        }
+    }
+}
+export const humanTyping = new HumanTyping();
+export default humanTyping;

package/dist/humanize-utils.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Generate a normally-distributed random number using the Box-Muller transform.
+ * @param mean - Center of the distribution
+ * @param stddev - Standard deviation
+ * @returns A sample from N(mean, stddev^2)
+ */
+export declare function gaussianRandom(mean?: number, stddev?: number): number;
+/**
+ * Clamp a value between min and max.
+ */
+export declare function clamp(val: number, min: number, max: number): number;
+/**
+ * Generate a human-like delay (in ms) drawn from a Gaussian distribution.
+ * The result is clamped to [min, max] so it never produces absurd values.
+ *
+ * @param min - Minimum delay in ms
+ * @param max - Maximum delay in ms
+ * @returns Delay in ms, Gaussian-distributed around the midpoint
+ */
+export declare function humanDelay(min?: number, max?: number): number;
+/**
+ * Sleep for the specified number of milliseconds.
+ */
+export declare function sleep(ms: number): Promise<void>;
+/**
+ * Generate a log-normal–distributed random delay.
+ *
+ * Log-normal produces the right-skewed, heavy-tailed shape that matches
+ * real keystroke timing data (Monaco et al., 2021). The distribution has
+ * a mode slightly below the median and occasional long-tail spikes — a
+ * signature of human typing that Gaussian distributions lack.
+ *
+ * @param median - Median delay in ms (the 50th-percentile value)
+ * @param sigma  - Shape parameter controlling spread / skew (0.3–0.5 typical)
+ * @param floor  - Hard floor in ms (below 40ms is physically impossible)
+ * @returns Delay in ms, rounded to an integer
+ */
+export declare function logNormalDelay(median: number, sigma: number, floor?: number): number;
+/**
+ * Generate a normally-distributed random value with the given mean and stddev.
+ * Convenience alias for gaussianRandom — named to match the spec convention
+ * used across humanize modules (e.g., `normalRandom(350, 100)`).
+ */
+export declare function normalRandom(mean: number, stddev: number): number;
+/**
+ * Compute a Gaussian-distributed click offset within an element's bounding box.
+ *
+ * Real humans click in a Gaussian distribution around the center of a target
+ * element, NOT at the exact geometric center. Dead-center clicks are a known
+ * bot detection fingerprint (DataDome, PerimeterX track this pattern).
+ *
+ * @param center      - The geometric center of the element on this axis
+ * @param elementSize - The element's width or height on this axis
+ * @param elementStart - The element's x or y origin on this axis
+ * @returns A coordinate within the element bounds, Gaussian-distributed around center
+ */
+export declare function gaussianClickOffset(center: number, elementSize: number, elementStart: number): number;
+/**
+ * Check whether the LEAP_HUMANIZE env var is enabled.
+ * Returns false unless LEAP_HUMANIZE is explicitly set to "true" or "1".
+ */
+export declare function isHumanizeEnabled(): boolean;

package/dist/humanize-utils.js

@@ -0,0 +1,100 @@
+// ─── Humanize Shared Utilities ─────────────────────────────────────────────
+//
+// Pure math primitives shared across all humanize-* modules.
+// Zero external dependencies. All distributions are self-contained.
+//
+// Standalone module — no cross-dependencies on other leapfrog modules.
+/**
+ * Generate a normally-distributed random number using the Box-Muller transform.
+ * @param mean - Center of the distribution
+ * @param stddev - Standard deviation
+ * @returns A sample from N(mean, stddev^2)
+ */
+export function gaussianRandom(mean = 0, stddev = 1) {
+    let u, v, s;
+    do {
+        u = Math.random() * 2 - 1;
+        v = Math.random() * 2 - 1;
+        s = u * u + v * v;
+    } while (s >= 1 || s === 0);
+    const mul = Math.sqrt(-2 * Math.log(s) / s);
+    return mean + stddev * u * mul;
+}
+/**
+ * Clamp a value between min and max.
+ */
+export function clamp(val, min, max) {
+    return Math.max(min, Math.min(max, val));
+}
+/**
+ * Generate a human-like delay (in ms) drawn from a Gaussian distribution.
+ * The result is clamped to [min, max] so it never produces absurd values.
+ *
+ * @param min - Minimum delay in ms
+ * @param max - Maximum delay in ms
+ * @returns Delay in ms, Gaussian-distributed around the midpoint
+ */
+export function humanDelay(min = 50, max = 200) {
+    const mean = (min + max) / 2;
+    const stddev = (max - min) / 6; // 99.7% of values fall within [min, max]
+    return Math.round(clamp(gaussianRandom(mean, stddev), min, max));
+}
+/**
+ * Sleep for the specified number of milliseconds.
+ */
+export function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Generate a log-normal–distributed random delay.
+ *
+ * Log-normal produces the right-skewed, heavy-tailed shape that matches
+ * real keystroke timing data (Monaco et al., 2021). The distribution has
+ * a mode slightly below the median and occasional long-tail spikes — a
+ * signature of human typing that Gaussian distributions lack.
+ *
+ * @param median - Median delay in ms (the 50th-percentile value)
+ * @param sigma  - Shape parameter controlling spread / skew (0.3–0.5 typical)
+ * @param floor  - Hard floor in ms (below 40ms is physically impossible)
+ * @returns Delay in ms, rounded to an integer
+ */
+export function logNormalDelay(median, sigma, floor = 40) {
+    const mu = Math.log(median);
+    const normal = gaussianRandom(0, 1);
+    return Math.max(floor, Math.round(Math.exp(mu + sigma * normal)));
+}
+/**
+ * Generate a normally-distributed random value with the given mean and stddev.
+ * Convenience alias for gaussianRandom — named to match the spec convention
+ * used across humanize modules (e.g., `normalRandom(350, 100)`).
+ */
+export function normalRandom(mean, stddev) {
+    return gaussianRandom(mean, stddev);
+}
+/**
+ * Compute a Gaussian-distributed click offset within an element's bounding box.
+ *
+ * Real humans click in a Gaussian distribution around the center of a target
+ * element, NOT at the exact geometric center. Dead-center clicks are a known
+ * bot detection fingerprint (DataDome, PerimeterX track this pattern).
+ *
+ * @param center      - The geometric center of the element on this axis
+ * @param elementSize - The element's width or height on this axis
+ * @param elementStart - The element's x or y origin on this axis
+ * @returns A coordinate within the element bounds, Gaussian-distributed around center
+ */
+export function gaussianClickOffset(center, elementSize, elementStart) {
+    const sigma = elementSize * 0.15;
+    const offset = gaussianRandom(center, sigma);
+    // Clamp within element bounds with a 5% inset margin on each side
+    const margin = elementSize * 0.05;
+    return clamp(offset, elementStart + margin, elementStart + elementSize - margin);
+}
+/**
+ * Check whether the LEAP_HUMANIZE env var is enabled.
+ * Returns false unless LEAP_HUMANIZE is explicitly set to "true" or "1".
+ */
+export function isHumanizeEnabled() {
+    const val = process.env.LEAP_HUMANIZE;
+    return val === "true" || val === "1";
+}