arn-browser 0.0.7 → 0.0.9

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "arn-browser",
-	"version": "0.0.7",
+	"version": "0.0.9",
 	"description": "A lightweight, browser autmation helper.",
 	"main": "src/index.js",
 	"types": "src/index.d.ts",

package/src/human-cursor/HumanCursor.js

@@ -1,10 +1,18 @@
 /**
  * HumanCursor - Human-like cursor movements for Playwright
  * Drop-in replacement for Page with human cursor for click/fill/type/hover
+ * 
+ * Anti-Bot Detection Features:
+ * - Micro-pauses and hesitations during movement
+ * - Variable (non-linear) movement speed
+ * - Overshoot and correction behavior
+ * - Human-like click timing with jitter
+ * - Gaussian-weighted element targeting
+ * - Pre-movement hover and assessment behavior
  */
 
 import { HumanizeMouseTrajectory } from './bezier.js';
-import { generateRandomCurveParameters, calculateAbsoluteOffset } from './randomizer.js';
+import { generateRandomCurveParameters } from './randomizer.js';
 
 /**
  * Random integer between min and max (inclusive)
@@ -20,6 +28,21 @@ function sleep(ms) {
     return new Promise(resolve => setTimeout(resolve, ms));
 }
 
+/**
+ * Gaussian random number generator (Box-Muller transform)
+ * Returns value centered around mean with given standard deviation
+ * @param {number} mean - Center of distribution (default: 0.5)
+ * @param {number} stdDev - Standard deviation (default: 0.15)
+ * @returns {number} - Value clamped between 0.1 and 0.9
+ */
+function gaussianRandom(mean = 0.5, stdDev = 0.15) {
+    let u1 = Math.random();
+    if (u1 === 0) u1 = 0.000001; // Avoid log(0)
+    const u2 = Math.random();
+    const z0 = Math.sqrt(-2.0 * Math.log(u1)) * Math.cos(2.0 * Math.PI * u2);
+    return Math.max(0.1, Math.min(0.9, z0 * stdDev + mean));
+}
+
 /**
  * Simple mutex for serializing keyboard operations
  */
@@ -50,23 +73,32 @@ function createHumanLocator(cursor, locator) {
             }
 
             await cursor._moveToLocator(locator, options);
+
+            // Pre-click hover - humans don't click instantly after arriving
+            if (Math.random() < 0.35) {
+                await sleep(randInt(30, 120));
+            }
+
             const clicks = options.clickCount || 1;
             const button = options.button || 'left';
 
             for (let i = 0; i < clicks; i++) {
+                // Variable mouse down/up timing
+                const holdTime = randInt(50, 120);
+
                 if (options.delay) {
                     await cursor._page.mouse.down({ button });
                     await sleep(options.delay);
                     await cursor._page.mouse.up({ button });
                 } else {
-                    await cursor._page.mouse.click(
-                        cursor.originCoordinates[0],
-                        cursor.originCoordinates[1],
-                        { button }
-                    );
+                    await cursor._page.mouse.down({ button });
+                    await sleep(holdTime);
+                    await cursor._page.mouse.up({ button });
                 }
+
                 if (i < clicks - 1) {
-                    await sleep(randInt(170, 280));
+                    // Jittery timing between multi-clicks
+                    await sleep(randInt(120, 320));
                 }
             }
         },
@@ -75,11 +107,28 @@ function createHumanLocator(cursor, locator) {
             if (!cursor.config.humanize) {
                 return await locator.dblclick(options);
             }
+
             await cursor._moveToLocator(locator, options);
-            await cursor._page.mouse.dblclick(
-                cursor.originCoordinates[0],
-                cursor.originCoordinates[1]
-            );
+
+            // Pre-click hover
+            if (Math.random() < 0.25) {
+                await sleep(randInt(40, 100));
+            }
+
+            const button = options.button || 'left';
+
+            // First click with variable hold
+            await cursor._page.mouse.down({ button });
+            await sleep(randInt(40, 90));
+            await cursor._page.mouse.up({ button });
+
+            // Gap between clicks - humans vary widely here
+            await sleep(randInt(60, 180));
+
+            // Second click
+            await cursor._page.mouse.down({ button });
+            await sleep(randInt(35, 85));
+            await cursor._page.mouse.up({ button });
         },
 
         async fill(value, options = {}) {
@@ -233,7 +282,11 @@ export function createCursor(page, options = {}) {
         humanize: options.humanize ?? true,  // Enable human cursor by default
         maxTime: options.maxTime ?? 1.5,
         minTime: options.minTime ?? 0.5,
-        showCursor: options.showCursor ?? true  // Show cursor by default
+        showCursor: options.showCursor ?? true,  // Show cursor by default
+        // Anti-detection tuning
+        overshootProbability: options.overshootProbability ?? 0.15,
+        microPauseProbability: options.microPauseProbability ?? 0.08,
+        preMoveJitterProbability: options.preMoveJitterProbability ?? 0.10
     };
 
     // Internal state
@@ -242,6 +295,10 @@ export function createCursor(page, options = {}) {
         originCoordinates: [0, 0],
         config,
 
+        /**
+         * Move cursor to locator with human-like behavior
+         * Includes overshoot/correction and pre-movement jitter
+         */
         async _moveToLocator(locator, options = {}) {
             await locator.scrollIntoViewIfNeeded();
             const bounds = await locator.boundingBox();
@@ -250,19 +307,65 @@ export function createCursor(page, options = {}) {
                 throw new Error('Element not found or not visible');
             }
 
+            // Pre-movement jitter - small "looking around" before heading to target
+            if (Math.random() < config.preMoveJitterProbability) {
+                const jitterX = this.originCoordinates[0] + randInt(-40, 40);
+                const jitterY = this.originCoordinates[1] + randInt(-25, 25);
+                await this._moveToPoint([jitterX, jitterY], { steady: true, quick: true });
+                await sleep(randInt(60, 180));
+            }
+
+            // Gaussian-weighted targeting - clusters clicks naturally around center
             let xOffset, yOffset;
             if (options.position) {
                 xOffset = options.position.x;
                 yOffset = options.position.y;
             } else {
-                xOffset = bounds.width * (randInt(25, 75) / 100);
-                yOffset = bounds.height * (randInt(25, 75) / 100);
+                // Use Gaussian distribution for more natural click targeting
+                xOffset = bounds.width * gaussianRandom(0.5, 0.18);
+                yOffset = bounds.height * gaussianRandom(0.5, 0.18);
             }
 
             const destination = [bounds.x + xOffset, bounds.y + yOffset];
-            return await this._moveToPoint(destination, options);
+
+            // Calculate distance for overshoot decision
+            const distance = Math.sqrt(
+                Math.pow(destination[0] - this.originCoordinates[0], 2) +
+                Math.pow(destination[1] - this.originCoordinates[1], 2)
+            );
+
+            // Overshoot and correction for longer movements
+            const shouldOvershoot = Math.random() < config.overshootProbability && distance > 80;
+
+            if (shouldOvershoot) {
+                // Calculate overshoot direction and magnitude
+                const overshootMagnitude = randInt(5, 18);
+                const angle = Math.atan2(
+                    destination[1] - this.originCoordinates[1],
+                    destination[0] - this.originCoordinates[0]
+                );
+
+                // Overshoot past the target in the direction of movement
+                const overshootX = destination[0] + Math.cos(angle) * overshootMagnitude;
+                const overshootY = destination[1] + Math.sin(angle) * overshootMagnitude;
+
+                await this._moveToPoint([overshootX, overshootY], options);
+
+                // Brief pause - "oops, went too far"
+                await sleep(randInt(40, 100));
+
+                // Correction movement - steadier, more direct
+                await this._moveToPoint(destination, { ...options, steady: true, quick: true });
+            } else {
+                await this._moveToPoint(destination, options);
+            }
+
+            return destination;
         },
 
+        /**
+         * Move cursor to a specific point with variable speed and micro-pauses
+         */
         async _moveToPoint(destination, options = {}) {
             const viewport = page.viewportSize() || { width: 1280, height: 720 };
 
@@ -280,6 +383,11 @@ export function createCursor(page, options = {}) {
                 params.distortionFrequency = 1;
             }
 
+            // Reduce points for quick movements (corrections)
+            if (options.quick) {
+                params.targetPoints = Math.max(20, Math.floor(params.targetPoints * 0.4));
+            }
+
             const curve = new HumanizeMouseTrajectory(
                 this.originCoordinates,
                 destination,
@@ -306,10 +414,34 @@ export function createCursor(page, options = {}) {
             const baseDelay = totalTime / curve.points.length;
             const speedMultiplier = options.moveSpeed || 1.0;
 
-            for (const point of curve.points) {
+            // Variable speed movement with micro-pauses
+            const pointCount = curve.points.length;
+            for (let i = 0; i < pointCount; i++) {
+                const point = curve.points[i];
+                const progress = i / pointCount;
+
+                // Variable speed: accelerate from start, random variations in middle, decelerate at end
+                let speedFactor = 1;
+                if (progress < 0.15) {
+                    // Accelerating phase - start slower
+                    speedFactor = 0.6 + progress * 2.5;
+                } else if (progress > 0.85) {
+                    // Decelerating phase - slow down approaching target
+                    speedFactor = 0.6 + (1 - progress) * 2.5;
+                } else {
+                    // Middle phase - random speed bursts
+                    speedFactor = 0.7 + Math.random() * 0.6;
+                }
+
                 await page.mouse.move(point[0], point[1]);
-                if (baseDelay > 0) {
-                    await sleep((baseDelay / speedMultiplier) + Math.random() * 2);
+
+                // Calculate delay with speed variation
+                const adjustedDelay = (baseDelay / speedMultiplier) * (1 / speedFactor);
+                await sleep(adjustedDelay + Math.random() * 3);
+
+                // Micro-pause - random hesitations during movement (humans aren't smooth)
+                if (Math.random() < config.microPauseProbability && progress > 0.2 && progress < 0.8) {
+                    await sleep(randInt(40, 180));
                 }
             }
 
@@ -317,13 +449,31 @@ export function createCursor(page, options = {}) {
             return destination;
         },
 
+        /**
+         * Human-like typing with variable delays and occasional pauses
+         */
         async _type(text, options = {}) {
             const minDelay = options.minDelay ?? 50;
             const maxDelay = options.maxDelay ?? 150;
 
-            for (const char of text) {
+            for (let i = 0; i < text.length; i++) {
+                const char = text[i];
                 await page.keyboard.type(char);
-                await sleep(randInt(minDelay, maxDelay));
+
+                // Base delay between characters
+                let delay = randInt(minDelay, maxDelay);
+
+                // Longer pause after punctuation (thinking)
+                if (['.', ',', '!', '?', ';', ':'].includes(char)) {
+                    delay += randInt(80, 200);
+                }
+
+                // Occasional longer pause mid-word (thinking/hesitation)
+                if (Math.random() < 0.03) {
+                    delay += randInt(100, 300);
+                }
+
+                await sleep(delay);
             }
         },
 

package/src/human-cursor/index.d.ts

@@ -113,6 +113,23 @@ export interface CreateCursorOptions {
     minTime?: number;
     /** Auto-show cursor indicator after goto (default: true) */
     showCursor?: boolean;
+
+    // Anti-bot detection tuning options
+    /** 
+     * Probability of overshoot and correction behavior (0-1)
+     * Higher values = more overshoots (default: 0.15)
+     */
+    overshootProbability?: number;
+    /** 
+     * Probability of micro-pauses during movement (0-1)
+     * Higher values = more hesitations (default: 0.08)
+     */
+    microPauseProbability?: number;
+    /** 
+     * Probability of pre-movement jitter/looking around (0-1)
+     * Higher values = more exploratory movement (default: 0.10)
+     */
+    preMoveJitterProbability?: number;
 }
 
 // ============= HumanPage =============

package/src/utility/launchBrowser.d.ts

@@ -205,43 +205,53 @@ export interface LaunchOptions {
 }
 
 /**
- * The object returned by launchBrowser.
+ * Successful browser launch result.
+ * When launchError is null, browser/context/page are guaranteed to be valid.
  */
-export interface BrowserController {
-	/**
-	 * The Playwright Browser or BrowserContext instance.
-	 * Note: Multilogin and Persistent profiles return a BrowserContext here.
-	 */
-	browser: Browser | BrowserContext | null;
-
-	/**
-	 * The active BrowserContext.
-	 */
-	context: BrowserContext | null;
-
+export interface BrowserControllerSuccess {
+	/** The Playwright Browser or BrowserContext instance. */
+	browser: Browser | BrowserContext;
+	/** The active BrowserContext. */
+	context: BrowserContext;
 	/**
 	 * The initial Page object.
 	 * When humanize_options is provided, this will be a HumanPage with human-like cursor methods.
 	 * All standard Playwright Page methods are available.
 	 */
-	page: Page | HumanPage | null;
-
-	/**
-	 * Checks if the browser context is currently active.
-	 */
+	page: Page | HumanPage;
+	/** Returns true since the browser is running. */
 	isBrowserRunning: () => boolean;
-
-	/**
-	 * Safely closes the browser and cleans up temporary directories if applicable.
-	 */
+	/** Safely closes the browser and cleans up temporary directories if applicable. */
 	closeBrowser: () => Promise<boolean>;
+	/** No error occurred during launch. */
+	launchError: null;
+}
 
-	/**
-	 * Captures any error that occurred during launch.
-	 */
-	launchError: Error | null;
+/**
+ * Failed browser launch result.
+ * When launchError is set, browser/context/page are null.
+ */
+export interface BrowserControllerError {
+	/** Null on launch failure. */
+	browser: null;
+	/** Null on launch failure. */
+	context: null;
+	/** Null on launch failure. */
+	page: null;
+	/** Returns false since the browser failed to launch. */
+	isBrowserRunning: () => boolean;
+	/** No-op cleanup function. */
+	closeBrowser: () => Promise<boolean>;
+	/** The error that occurred during launch. */
+	launchError: Error;
 }
 
+/**
+ * The object returned by launchBrowser.
+ * Check launchError to discriminate between success and failure states.
+ */
+export type BrowserController = BrowserControllerSuccess | BrowserControllerError;
+
 /**
  * Launches a browser based on the provided options.
  */

package/src/utility/launchBrowser.js

@@ -196,9 +196,11 @@ export async function launchBrowser({
 		let browserInstance;
 
 		// Humanize is ON by default for non-camoufox browsers
-		// Only disabled if explicitly set to false: humanize_options: { humanize: false }
-		const shouldHumanize = which_browser !== "camoufox" && humanize_options?.humanize !== false;
-		const effectiveHumanizeOptions = shouldHumanize ? humanize_options : null;
+		// Even when disabled, we still wrap to provide custom methods like fillSequentially
+		// The HumanCursor wrapper checks the humanize flag internally and falls back to native Playwright
+		const effectiveHumanizeOptions = which_browser !== "camoufox"
+			? { humanize: humanize_options?.humanize !== false, ...humanize_options }
+			: null;
 
 		switch (which_browser) {
 			case "chromium":
@@ -256,7 +258,7 @@ export async function launchBrowser({
 		return browserInstance;
 	} catch (error) {
 		console.error("❌ [LaunchBrowser] Critical Error:", error.message || error);
-		return { data: null, error: error, closeBrowser: async () => { } };
+		return { browser: null, context: null, page: null, isBrowserRunning: () => false, closeBrowser: async () => false, launchError: error };
 	}
 }
 
@@ -727,7 +729,7 @@ async function launchExistingMultiloginProfile(profileId, humanize_options = nul
 		try {
 			await stopMultiloginProfile(profileId);
 		} catch (e) { }
-		return { data: null, error, closeBrowser: async () => { } };
+		return { browser: null, context: null, page: null, isBrowserRunning: () => false, closeBrowser: async () => false, launchError: error };
 	}
 }
 
@@ -799,7 +801,7 @@ async function launchQuickMultiloginProfile({ os_type, proxy, canvas_noise, medi
 	} catch (error) {
 		console.error("Quick Profile Error:", error);
 		if (profileId) await stopMultiloginProfile(profileId);
-		return { data: null, error, closeBrowser: async () => { } };
+		return { browser: null, context: null, page: null, isBrowserRunning: () => false, closeBrowser: async () => false, launchError: error };
 	}
 }