arn-browser 0.0.3 → 0.0.5

package/src/human-cursor/HumanCursor.js

@@ -0,0 +1,448 @@
+/**
+ * HumanCursor - Human-like cursor movements for Playwright
+ * Drop-in replacement for Page with human cursor for click/fill/type/hover
+ */
+
+import { HumanizeMouseTrajectory } from './bezier.js';
+import { generateRandomCurveParameters, calculateAbsoluteOffset } from './randomizer.js';
+
+/**
+ * Random integer between min and max (inclusive)
+ */
+function randInt(min, max) {
+    return Math.floor(Math.random() * (max - min + 1)) + min;
+}
+
+/**
+ * Sleep for specified milliseconds
+ */
+function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+/**
+ * Creates a HumanLocator that wraps a Playwright Locator
+ * with human-like cursor movement for actions
+ */
+function createHumanLocator(cursor, locator) {
+    // Methods that need human cursor movement
+    const humanMethods = {
+        async click(options = {}) {
+            // If humanize is disabled, use native Playwright click
+            if (!cursor.config.humanize) {
+                return await locator.click(options);
+            }
+
+            await cursor._moveToLocator(locator, options);
+            const clicks = options.clickCount || 1;
+            const button = options.button || 'left';
+
+            for (let i = 0; i < clicks; i++) {
+                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 }
+                    );
+                }
+                if (i < clicks - 1) {
+                    await sleep(randInt(170, 280));
+                }
+            }
+        },
+
+        async dblclick(options = {}) {
+            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]
+            );
+        },
+
+        async fill(value, options = {}) {
+            if (!cursor.config.humanize) {
+                return await locator.fill(value, options);
+            }
+            await this.click(options);
+            await cursor._page.keyboard.press('Control+A');
+            await sleep(randInt(50, 100));
+            await cursor._type(value, options);
+        },
+
+        async type(text, options = {}) {
+            if (!cursor.config.humanize) {
+                return await locator.type(text, options);
+            }
+            await this.click(options);
+            await cursor._type(text, options);
+        },
+
+        async hover(options = {}) {
+            if (!cursor.config.humanize) {
+                return await locator.hover(options);
+            }
+            await cursor._moveToLocator(locator, options);
+        },
+
+        async press(key, options = {}) {
+            if (!cursor.config.humanize) {
+                return await locator.press(key, options);
+            }
+            await this.click(options);
+            await cursor._page.keyboard.press(key);
+        },
+
+        // Chainable methods that return new HumanLocators
+        filter(options) {
+            return createHumanLocator(cursor, locator.filter(options));
+        },
+        first() {
+            return createHumanLocator(cursor, locator.first());
+        },
+        last() {
+            return createHumanLocator(cursor, locator.last());
+        },
+        nth(index) {
+            return createHumanLocator(cursor, locator.nth(index));
+        },
+        locator(selector) {
+            return createHumanLocator(cursor, locator.locator(selector));
+        },
+        getByText(text, options) {
+            return createHumanLocator(cursor, locator.getByText(text, options));
+        },
+        getByRole(role, options) {
+            return createHumanLocator(cursor, locator.getByRole(role, options));
+        },
+        getByLabel(text, options) {
+            return createHumanLocator(cursor, locator.getByLabel(text, options));
+        },
+        getByPlaceholder(text, options) {
+            return createHumanLocator(cursor, locator.getByPlaceholder(text, options));
+        },
+        getByTestId(testId) {
+            return createHumanLocator(cursor, locator.getByTestId(testId));
+        }
+    };
+
+    // Use Proxy to pass through all other methods to original locator
+    return new Proxy(locator, {
+        get(target, prop) {
+            // Human methods override
+            if (prop in humanMethods) {
+                return humanMethods[prop];
+            }
+            // Pass through to original locator
+            const value = target[prop];
+            if (typeof value === 'function') {
+                return value.bind(target);
+            }
+            return value;
+        }
+    });
+}
+
+/**
+ * Create a HumanCursor that acts as a drop-in replacement for Page
+ * All page methods work, but click/fill/type/hover use human cursor
+ * 
+ * @param {import('playwright').Page} page - Playwright Page object
+ * @param {Object} options - Configuration options
+ * @returns {import('playwright').Page & HumanCursorMethods}
+ */
+export function createCursor(page, options = {}) {
+    const config = {
+        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
+    };
+
+    // Internal state
+    const cursor = {
+        _page: page,
+        originCoordinates: [0, 0],
+        config,
+
+        async _moveToLocator(locator, options = {}) {
+            await locator.scrollIntoViewIfNeeded();
+            const bounds = await locator.boundingBox();
+
+            if (!bounds) {
+                throw new Error('Element not found or not visible');
+            }
+
+            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);
+            }
+
+            const destination = [bounds.x + xOffset, bounds.y + yOffset];
+            return await this._moveToPoint(destination, options);
+        },
+
+        async _moveToPoint(destination, options = {}) {
+            const viewport = page.viewportSize() || { width: 1280, height: 720 };
+
+            const params = generateRandomCurveParameters(
+                viewport,
+                this.originCoordinates,
+                destination
+            );
+
+            if (options.steady) {
+                params.offsetBoundaryX = 10;
+                params.offsetBoundaryY = 10;
+                params.distortionMean = 1.2;
+                params.distortionStdDev = 1.2;
+                params.distortionFrequency = 1;
+            }
+
+            const curve = new HumanizeMouseTrajectory(
+                this.originCoordinates,
+                destination,
+                {
+                    offsetBoundaryX: params.offsetBoundaryX,
+                    offsetBoundaryY: params.offsetBoundaryY,
+                    knotsCount: params.knotsCount,
+                    distortionMean: params.distortionMean,
+                    distortionStdDev: params.distortionStdDev,
+                    distortionFrequency: params.distortionFrequency,
+                    tweening: params.tween,
+                    targetPoints: params.targetPoints
+                }
+            );
+
+            const distance = Math.sqrt(
+                Math.pow(destination[0] - this.originCoordinates[0], 2) +
+                Math.pow(destination[1] - this.originCoordinates[1], 2)
+            );
+            const totalTime = Math.min(
+                config.maxTime,
+                Math.max(config.minTime, distance / 1000)
+            ) * 1000;
+            const baseDelay = totalTime / curve.points.length;
+            const speedMultiplier = options.moveSpeed || 1.0;
+
+            for (const point of curve.points) {
+                await page.mouse.move(point[0], point[1]);
+                if (baseDelay > 0) {
+                    await sleep((baseDelay / speedMultiplier) + Math.random() * 2);
+                }
+            }
+
+            this.originCoordinates = destination;
+            return destination;
+        },
+
+        async _type(text, options = {}) {
+            const minDelay = options.minDelay ?? 50;
+            const maxDelay = options.maxDelay ?? 150;
+
+            for (const char of text) {
+                await page.keyboard.type(char);
+                await sleep(randInt(minDelay, maxDelay));
+            }
+        },
+
+        async showCursor() {
+            await page.evaluate(() => {
+                if (window.__humanCursorDot) return;
+
+                let cursor;
+                function updateCursor(event) {
+                    const x = event.clientX;
+                    const y = event.clientY;
+
+                    if (!cursor) {
+                        // Create cursor container
+                        cursor = document.createElement('div');
+                        cursor.id = '__human_cursor';
+                        cursor.style.cssText = `
+                            position: fixed;
+                            pointer-events: none;
+                            z-index: 2147483647;
+                            transition: left 0.05s ease-out, top 0.05s ease-out;
+                        `;
+
+                        // Outer ring (animated)
+                        const ring = document.createElement('div');
+                        ring.style.cssText = `
+                            width: 28px;
+                            height: 28px;
+                            border: 2px solid rgba(59, 130, 246, 0.6);
+                            border-radius: 50%;
+                            box-sizing: border-box;
+                            position: absolute;
+                            top: -14px;
+                            left: -14px;
+                            animation: pulse 1.5s ease-in-out infinite;
+                        `;
+
+                        // Inner dot
+                        const dot = document.createElement('div');
+                        dot.style.cssText = `
+                            width: 10px;
+                            height: 10px;
+                            background: linear-gradient(135deg, #3b82f6, #8b5cf6);
+                            border-radius: 50%;
+                            position: absolute;
+                            top: -5px;
+                            left: -5px;
+                            box-shadow: 0 0 12px rgba(59, 130, 246, 0.8), 0 0 4px rgba(255, 255, 255, 0.9);
+                        `;
+
+                        // Click indicator
+                        const clickRing = document.createElement('div');
+                        clickRing.id = '__human_cursor_click';
+                        clickRing.style.cssText = `
+                            width: 36px;
+                            height: 36px;
+                            border: 2px solid rgba(239, 68, 68, 0.8);
+                            border-radius: 50%;
+                            box-sizing: border-box;
+                            position: absolute;
+                            top: -18px;
+                            left: -18px;
+                            opacity: 0;
+                            transform: scale(0.5);
+                            transition: opacity 0.15s, transform 0.15s;
+                        `;
+
+                        // Add pulse animation
+                        const style = document.createElement('style');
+                        style.textContent = `
+                            @keyframes pulse {
+                                0%, 100% { transform: scale(1); opacity: 0.6; }
+                                50% { transform: scale(1.2); opacity: 0.3; }
+                            }
+                        `;
+                        document.head.appendChild(style);
+
+                        cursor.appendChild(ring);
+                        cursor.appendChild(dot);
+                        cursor.appendChild(clickRing);
+                        document.body.appendChild(cursor);
+
+                        // Click effect
+                        document.addEventListener('mousedown', () => {
+                            const click = document.getElementById('__human_cursor_click');
+                            if (click) {
+                                click.style.opacity = '1';
+                                click.style.transform = 'scale(1)';
+                            }
+                        });
+                        document.addEventListener('mouseup', () => {
+                            const click = document.getElementById('__human_cursor_click');
+                            if (click) {
+                                click.style.opacity = '0';
+                                click.style.transform = 'scale(0.5)';
+                            }
+                        });
+                    }
+
+                    cursor.style.left = x + 'px';
+                    cursor.style.top = y + 'px';
+                }
+
+                document.addEventListener('mousemove', updateCursor);
+                window.__humanCursorDot = true;
+            });
+        }
+    };
+
+    // Methods that return HumanLocators
+    const locatorMethods = {
+        locator(selector) {
+            return createHumanLocator(cursor, page.locator(selector));
+        },
+        getByText(text, opts) {
+            return createHumanLocator(cursor, page.getByText(text, opts));
+        },
+        getByRole(role, opts) {
+            return createHumanLocator(cursor, page.getByRole(role, opts));
+        },
+        getByLabel(text, opts) {
+            return createHumanLocator(cursor, page.getByLabel(text, opts));
+        },
+        getByPlaceholder(text, opts) {
+            return createHumanLocator(cursor, page.getByPlaceholder(text, opts));
+        },
+        getByAltText(text, opts) {
+            return createHumanLocator(cursor, page.getByAltText(text, opts));
+        },
+        getByTitle(text, opts) {
+            return createHumanLocator(cursor, page.getByTitle(text, opts));
+        },
+        getByTestId(testId) {
+            return createHumanLocator(cursor, page.getByTestId(testId));
+        }
+    };
+
+    // Wrap goto to auto-show cursor after navigation
+    const originalGoto = page.goto.bind(page);
+    const wrappedGoto = async (...args) => {
+        const result = await originalGoto(...args);
+        if (config.showCursor) {
+            await cursor.showCursor();
+        }
+        return result;
+    };
+
+    // Use Proxy to create drop-in page replacement
+    return new Proxy(page, {
+        get(target, prop) {
+            // Override goto to auto-show cursor
+            if (prop === 'goto') {
+                return wrappedGoto;
+            }
+            // Locator methods return HumanLocators
+            if (prop in locatorMethods) {
+                return locatorMethods[prop];
+            }
+            // Expose cursor utilities
+            if (prop === 'showCursor') {
+                return cursor.showCursor.bind(cursor);
+            }
+            if (prop === 'originCoordinates') {
+                return cursor.originCoordinates;
+            }
+            if (prop === 'setPosition') {
+                return (x, y) => { cursor.originCoordinates = [x, y]; };
+            }
+            // Pass through everything else to original page
+            const value = target[prop];
+            if (typeof value === 'function') {
+                return value.bind(target);
+            }
+            return value;
+        }
+    });
+}
+
+// Legacy class export for backwards compatibility
+export class HumanCursor {
+    constructor(page, options = {}) {
+        this.page = page;
+        this.originCoordinates = [0, 0];
+        this.options = {
+            maxTime: options.maxTime ?? 1.5,
+            minTime: options.minTime ?? 0.5,
+            showCursor: options.showCursor ?? true  // Show cursor by default
+        };
+
+        // Return proxy instead of class instance
+        return createCursor(page, options);
+    }
+}

package/src/human-cursor/bezier.js

@@ -0,0 +1,248 @@
+/**
+ * Bezier curve calculator and human-like trajectory generator
+ * Ported from Python HumanCursor library
+ */
+
+import { easeOutQuad } from './tweening.js';
+
+/**
+ * Calculates the binomial coefficient "n choose k"
+ * @param {number} n
+ * @param {number} k
+ * @returns {number}
+ */
+function binomial(n, k) {
+    let result = 1;
+    for (let i = 1; i <= k; i++) {
+        result = result * (n - i + 1) / i;
+    }
+    return result;
+}
+
+/**
+ * Calculate the i-th component of a Bernstein polynomial of degree n
+ * @param {number} x - Point on curve (0 to 1)
+ * @param {number} i - Index
+ * @param {number} n - Degree
+ * @returns {number}
+ */
+function bernsteinPolynomialPoint(x, i, n) {
+    return binomial(n, i) * Math.pow(x, i) * Math.pow(1 - x, n - i);
+}
+
+/**
+ * Returns a function that calculates a point on the Bezier curve
+ * @param {Array<[number, number]>} points - Control points
+ * @returns {function(number): [number, number]}
+ */
+function bernsteinPolynomial(points) {
+    return function (t) {
+        const n = points.length - 1;
+        let x = 0;
+        let y = 0;
+        for (let i = 0; i <= n; i++) {
+            const bern = bernsteinPolynomialPoint(t, i, n);
+            x += points[i][0] * bern;
+            y += points[i][1] * bern;
+        }
+        return [x, y];
+    };
+}
+
+/**
+ * Calculate n points on a Bezier curve
+ * @param {number} n - Number of points to generate
+ * @param {Array<[number, number]>} points - Control points
+ * @returns {Array<[number, number]>}
+ */
+function calculatePointsInCurve(n, points) {
+    const curvePoints = [];
+    const getBezierPoint = bernsteinPolynomial(points);
+    for (let i = 0; i < n; i++) {
+        const t = i / (n - 1);
+        curvePoints.push(getBezierPoint(t));
+    }
+    return curvePoints;
+}
+
+/**
+ * Check if a value is numeric
+ * @param {*} val
+ * @returns {boolean}
+ */
+function isNumeric(val) {
+    return typeof val === 'number' && !isNaN(val);
+}
+
+/**
+ * Check if list contains valid points
+ * @param {Array} list
+ * @returns {boolean}
+ */
+function isListOfPoints(list) {
+    if (!Array.isArray(list)) return false;
+    return list.every(p =>
+        Array.isArray(p) &&
+        p.length === 2 &&
+        isNumeric(p[0]) &&
+        isNumeric(p[1])
+    );
+}
+
+/**
+ * Random integer between min and max (inclusive)
+ * @param {number} min
+ * @param {number} max
+ * @returns {number}
+ */
+function randInt(min, max) {
+    return Math.floor(Math.random() * (max - min + 1)) + min;
+}
+
+/**
+ * Random float with normal distribution
+ * @param {number} mean
+ * @param {number} stdDev
+ * @returns {number}
+ */
+function randomNormal(mean, stdDev) {
+    // Box-Muller transform
+    const u1 = Math.random();
+    const u2 = Math.random();
+    const z0 = Math.sqrt(-2.0 * Math.log(u1)) * Math.cos(2.0 * Math.PI * u2);
+    return z0 * stdDev + mean;
+}
+
+/**
+ * Generates human-like mouse trajectory using Bezier curves
+ */
+export class HumanizeMouseTrajectory {
+    /**
+     * @param {[number, number]} fromPoint - Starting point [x, y]
+     * @param {[number, number]} toPoint - Ending point [x, y]
+     * @param {Object} options - Curve generation options
+     */
+    constructor(fromPoint, toPoint, options = {}) {
+        this.fromPoint = fromPoint;
+        this.toPoint = toPoint;
+        this.points = this.generateCurve(options);
+    }
+
+    /**
+     * Generates the curve based on options
+     * @param {Object} options
+     * @returns {Array<[number, number]>}
+     */
+    generateCurve(options) {
+        const offsetBoundaryX = options.offsetBoundaryX ?? 80;
+        const offsetBoundaryY = options.offsetBoundaryY ?? 80;
+        const leftBoundary = (options.leftBoundary ?? Math.min(this.fromPoint[0], this.toPoint[0])) - offsetBoundaryX;
+        const rightBoundary = (options.rightBoundary ?? Math.max(this.fromPoint[0], this.toPoint[0])) + offsetBoundaryX;
+        const downBoundary = (options.downBoundary ?? Math.min(this.fromPoint[1], this.toPoint[1])) - offsetBoundaryY;
+        const upBoundary = (options.upBoundary ?? Math.max(this.fromPoint[1], this.toPoint[1])) + offsetBoundaryY;
+        const knotsCount = options.knotsCount ?? 2;
+        const distortionMean = options.distortionMean ?? 1;
+        const distortionStdDev = options.distortionStdDev ?? 1;
+        const distortionFrequency = options.distortionFrequency ?? 0.5;
+        const tween = options.tweening ?? easeOutQuad;
+        const targetPoints = options.targetPoints ?? 100;
+
+        const internalKnots = this.generateInternalKnots(
+            leftBoundary, rightBoundary, downBoundary, upBoundary, knotsCount
+        );
+        let points = this.generatePoints(internalKnots);
+        points = this.distortPoints(points, distortionMean, distortionStdDev, distortionFrequency);
+        points = this.tweenPoints(points, tween, targetPoints);
+        return points;
+    }
+
+    /**
+     * Generates random internal knots for the curve
+     * @param {number} lBoundary
+     * @param {number} rBoundary
+     * @param {number} dBoundary
+     * @param {number} uBoundary
+     * @param {number} knotsCount
+     * @returns {Array<[number, number]>}
+     */
+    generateInternalKnots(lBoundary, rBoundary, dBoundary, uBoundary, knotsCount) {
+        if (knotsCount < 0) knotsCount = 0;
+        if (lBoundary > rBoundary) {
+            throw new Error('leftBoundary must be less than or equal to rightBoundary');
+        }
+        if (dBoundary > uBoundary) {
+            throw new Error('downBoundary must be less than or equal to upperBoundary');
+        }
+
+        const knots = [];
+        for (let i = 0; i < knotsCount; i++) {
+            const x = randInt(Math.floor(lBoundary), Math.floor(rBoundary));
+            const y = randInt(Math.floor(dBoundary), Math.floor(uBoundary));
+            knots.push([x, y]);
+        }
+        return knots;
+    }
+
+    /**
+     * Generates points from Bezier curve
+     * @param {Array<[number, number]>} knots
+     * @returns {Array<[number, number]>}
+     */
+    generatePoints(knots) {
+        const midPtsCnt = Math.max(
+            Math.abs(this.fromPoint[0] - this.toPoint[0]),
+            Math.abs(this.fromPoint[1] - this.toPoint[1]),
+            2
+        );
+        const allKnots = [this.fromPoint, ...knots, this.toPoint];
+        return calculatePointsInCurve(Math.floor(midPtsCnt), allKnots);
+    }
+
+    /**
+     * Distorts points to add human-like imperfections
+     * @param {Array<[number, number]>} points
+     * @param {number} distortionMean
+     * @param {number} distortionStdDev
+     * @param {number} distortionFrequency
+     * @returns {Array<[number, number]>}
+     */
+    distortPoints(points, distortionMean, distortionStdDev, distortionFrequency) {
+        if (distortionFrequency < 0 || distortionFrequency > 1) {
+            throw new Error('distortionFrequency must be in range [0, 1]');
+        }
+
+        const distorted = [points[0]];
+        for (let i = 1; i < points.length - 1; i++) {
+            const [x, y] = points[i];
+            const delta = Math.random() < distortionFrequency
+                ? randomNormal(distortionMean, distortionStdDev)
+                : 0;
+            distorted.push([x, y + delta]);
+        }
+        distorted.push(points[points.length - 1]);
+        return distorted;
+    }
+
+    /**
+     * Applies tweening to points
+     * @param {Array<[number, number]>} points
+     * @param {function(number): number} tween
+     * @param {number} targetPoints
+     * @returns {Array<[number, number]>}
+     */
+    tweenPoints(points, tween, targetPoints) {
+        if (targetPoints < 2) {
+            throw new Error('targetPoints must be >= 2');
+        }
+
+        const result = [];
+        for (let i = 0; i < targetPoints; i++) {
+            const t = i / (targetPoints - 1);
+            const index = Math.floor(tween(t) * (points.length - 1));
+            result.push(points[index]);
+        }
+        return result;
+    }
+}
+
+export { calculatePointsInCurve, bernsteinPolynomial };