arn-browser 0.0.4 → 0.0.5

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 };

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

@@ -0,0 +1,154 @@
+/**
+ * TypeScript declarations for human-cursor-playwright
+ */
+
+import type { Page, Locator, Response, PageScreenshotOptions, WaitForURLOptions } from 'playwright';
+
+// ============= Tweening Functions =============
+
+export type EasingFunction = (n: number) => number;
+
+export function linear(n: number): number;
+export function easeOutQuad(n: number): number;
+export function easeInQuad(n: number): number;
+export function easeInOutQuad(n: number): number;
+export function easeOutCubic(n: number): number;
+export function easeInCubic(n: number): number;
+export function easeInOutCubic(n: number): number;
+export function easeOutQuart(n: number): number;
+export function easeInQuart(n: number): number;
+export function easeInOutQuart(n: number): number;
+export function easeOutQuint(n: number): number;
+export function easeInQuint(n: number): number;
+export function easeInOutQuint(n: number): number;
+export function easeOutSine(n: number): number;
+export function easeInSine(n: number): number;
+export function easeInOutSine(n: number): number;
+export function easeOutExpo(n: number): number;
+export function easeInExpo(n: number): number;
+export function easeInOutExpo(n: number): number;
+export function easeOutCirc(n: number): number;
+export function easeInCirc(n: number): number;
+export function easeInOutCirc(n: number): number;
+
+export const easingFunctions: Record<string, EasingFunction>;
+
+// ============= Bezier Curve =============
+
+export interface CurveOptions {
+    offsetBoundaryX?: number;
+    offsetBoundaryY?: number;
+    knotsCount?: number;
+    distortionMean?: number;
+    distortionStdDev?: number;
+    distortionFrequency?: number;
+    tweening?: EasingFunction;
+    targetPoints?: number;
+}
+
+export class HumanizeMouseTrajectory {
+    fromPoint: [number, number];
+    toPoint: [number, number];
+    points: Array<[number, number]>;
+
+    constructor(fromPoint: [number, number], toPoint: [number, number], options?: CurveOptions);
+}
+
+// ============= HumanLocator =============
+
+export interface HumanClickOptions {
+    clickCount?: number;
+    button?: 'left' | 'right' | 'middle';
+    delay?: number;
+    position?: { x: number; y: number };
+    steady?: boolean;
+    moveSpeed?: number;
+}
+
+export interface HumanFillOptions extends HumanClickOptions {
+    minDelay?: number;
+    maxDelay?: number;
+}
+
+/**
+ * Locator with human-like cursor movement
+ * All Playwright Locator methods work, with click/fill/type using human cursor
+ */
+export interface HumanLocator extends Locator {
+    click(options?: HumanClickOptions): Promise<void>;
+    dblclick(options?: HumanClickOptions): Promise<void>;
+    fill(value: string, options?: HumanFillOptions): Promise<void>;
+    type(text: string, options?: HumanFillOptions): Promise<void>;
+    hover(options?: HumanClickOptions): Promise<void>;
+    press(key: string, options?: HumanClickOptions): Promise<void>;
+
+    // Chainable methods return HumanLocator
+    filter(options: { has?: Locator; hasNot?: Locator; hasText?: string | RegExp }): HumanLocator;
+    first(): HumanLocator;
+    last(): HumanLocator;
+    nth(index: number): HumanLocator;
+    locator(selector: string): HumanLocator;
+    getByText(text: string | RegExp, options?: { exact?: boolean }): HumanLocator;
+    getByRole(role: string, options?: { name?: string | RegExp; exact?: boolean }): HumanLocator;
+    getByLabel(text: string | RegExp, options?: { exact?: boolean }): HumanLocator;
+    getByPlaceholder(text: string | RegExp, options?: { exact?: boolean }): HumanLocator;
+    getByTestId(testId: string | RegExp): HumanLocator;
+}
+
+// ============= HumanCursor Options =============
+
+export interface CreateCursorOptions {
+    /** Enable/disable human-like cursor movement (default: true) */
+    humanize?: boolean;
+    /** Maximum movement time in seconds (default: 1.5) */
+    maxTime?: number;
+    /** Minimum movement time in seconds (default: 0.5) */
+    minTime?: number;
+    /** Auto-show cursor indicator after goto (default: true) */
+    showCursor?: boolean;
+}
+
+// ============= HumanPage =============
+
+/**
+ * Page with human-like cursor movement
+ * All Playwright Page methods work, with locator methods returning HumanLocators
+ */
+export interface HumanPage extends Page {
+    // Override locator methods to return HumanLocator
+    locator(selector: string): HumanLocator;
+    getByText(text: string | RegExp, options?: { exact?: boolean }): HumanLocator;
+    getByRole(role: string, options?: { name?: string | RegExp; exact?: boolean }): HumanLocator;
+    getByLabel(text: string | RegExp, options?: { exact?: boolean }): HumanLocator;
+    getByPlaceholder(text: string | RegExp, options?: { exact?: boolean }): HumanLocator;
+    getByAltText(text: string | RegExp, options?: { exact?: boolean }): HumanLocator;
+    getByTitle(text: string | RegExp, options?: { exact?: boolean }): HumanLocator;
+    getByTestId(testId: string | RegExp): HumanLocator;
+
+    // Additional cursor utilities
+    showCursor(): Promise<void>;
+    originCoordinates: [number, number];
+    setPosition(x: number, y: number): void;
+}
+
+// ============= Main Export =============
+
+/**
+ * Create a cursor that acts as a drop-in replacement for Page
+ * All Page methods work, but locator actions (click, fill, type, hover) use human cursor
+ * 
+ * @example
+ * ```ts
+ * const cursor = createCursor(page, { showCursor: true });
+ * await cursor.goto('https://example.com');
+ * await cursor.locator('button').click(); // Uses human cursor!
+ * ```
+ */
+export function createCursor(page: Page, options?: CreateCursorOptions): HumanPage;
+
+/**
+ * @deprecated Use createCursor() instead
+ */
+export class HumanCursor {
+    constructor(page: Page, options?: CreateCursorOptions);
+}

package/src/human-cursor/index.js

@@ -0,0 +1,9 @@
+/**
+ * human-cursor-playwright
+ * Human-like cursor movements for Playwright
+ */
+
+export { HumanCursor, createCursor } from './HumanCursor.js';
+export { HumanizeMouseTrajectory, calculatePointsInCurve, bernsteinPolynomial } from './bezier.js';
+export * from './tweening.js';
+export { generateRandomCurveParameters, calculateAbsoluteOffset } from './randomizer.js';

package/src/human-cursor/randomizer.js

@@ -0,0 +1,149 @@
+/**
+ * Random curve parameter generation
+ * Ported from Python HumanCursor library
+ */
+
+import * as tweening from './tweening.js';
+
+/**
+ * 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;
+}
+
+/**
+ * Randomly select from array
+ * @template T
+ * @param {T[]} arr
+ * @returns {T}
+ */
+function randomChoice(arr) {
+    return arr[Math.floor(Math.random() * arr.length)];
+}
+
+/**
+ * Weighted random selection
+ * @template T
+ * @param {T[]} choices
+ * @param {number[]} weights
+ * @returns {T}
+ */
+function weightedChoice(choices, weights) {
+    const totalWeight = weights.reduce((a, b) => a + b, 0);
+    let random = Math.random() * totalWeight;
+    for (let i = 0; i < choices.length; i++) {
+        random -= weights[i];
+        if (random <= 0) return choices[i];
+    }
+    return choices[choices.length - 1];
+}
+
+/**
+ * Calculate exact pixel offsets from relative position values
+ * @param {{ width: number, height: number }} size - Element dimensions
+ * @param {[number, number]} relativePosition - [x, y] percentages (0 to 1)
+ * @returns {[number, number]} Absolute pixel offsets
+ */
+export function calculateAbsoluteOffset(size, relativePosition) {
+    const xFinal = size.width * relativePosition[0];
+    const yFinal = size.height * relativePosition[1];
+    return [Math.floor(xFinal), Math.floor(yFinal)];
+}
+
+/**
+ * List of easing functions for random selection
+ */
+const tweenOptions = [
+    tweening.easeOutExpo,
+    tweening.easeInOutQuint,
+    tweening.easeInOutSine,
+    tweening.easeInOutQuart,
+    tweening.easeInOutExpo,
+    tweening.easeInOutCubic,
+    tweening.easeInOutCirc,
+    tweening.linear,
+    tweening.easeOutSine,
+    tweening.easeOutQuart,
+    tweening.easeOutQuint,
+    tweening.easeOutCubic,
+    tweening.easeOutCirc,
+];
+
+/**
+ * Generate random parameters for human-like curve
+ * @param {{ width: number, height: number }} viewportSize - Browser viewport size
+ * @param {[number, number]} preOrigin - Starting point
+ * @param {[number, number]} postDestination - Ending point
+ * @returns {Object} Curve parameters
+ */
+export function generateRandomCurveParameters(viewportSize, preOrigin, postDestination) {
+    const viewportWidth = viewportSize.width;
+    const viewportHeight = viewportSize.height;
+
+    const minWidth = viewportWidth * 0.15;
+    const maxWidth = viewportWidth * 0.85;
+    const minHeight = viewportHeight * 0.15;
+    const maxHeight = viewportHeight * 0.85;
+
+    const tween = randomChoice(tweenOptions);
+
+    let offsetBoundaryX = randomChoice(
+        weightedChoice(
+            [[20, 45], [45, 75], [75, 100]],
+            [0.2, 0.65, 0.15]
+        ).map(v => randInt(v, v))
+    ) || randInt(45, 75);
+
+    let offsetBoundaryY = randomChoice(
+        weightedChoice(
+            [[20, 45], [45, 75], [75, 100]],
+            [0.2, 0.65, 0.15]
+        ).map(v => randInt(v, v))
+    ) || randInt(45, 75);
+
+    let knotsCount = weightedChoice(
+        [1, 2, 3, 4, 5, 6, 7, 8, 9, 10],
+        [0.15, 0.36, 0.17, 0.12, 0.08, 0.04, 0.03, 0.02, 0.015, 0.005]
+    );
+
+    const distortionMean = randInt(80, 110) / 100;
+    const distortionStdDev = randInt(85, 110) / 100;
+    const distortionFrequency = randInt(25, 70) / 100;
+
+    const targetPoints = randomChoice(
+        weightedChoice(
+            [[35, 45], [45, 60], [60, 80]],
+            [0.53, 0.32, 0.15]
+        ).map(range => randInt(range[0], range[1]))
+    ) || randInt(45, 60);
+
+    // Reduce curve complexity if near viewport edges
+    const isOriginNearEdge =
+        preOrigin[0] < minWidth || preOrigin[0] > maxWidth ||
+        preOrigin[1] < minHeight || preOrigin[1] > maxHeight;
+
+    const isDestNearEdge =
+        postDestination[0] < minWidth || postDestination[0] > maxWidth ||
+        postDestination[1] < minHeight || postDestination[1] > maxHeight;
+
+    if (isOriginNearEdge || isDestNearEdge) {
+        offsetBoundaryX = 1;
+        offsetBoundaryY = 1;
+        knotsCount = 1;
+    }
+
+    return {
+        offsetBoundaryX,
+        offsetBoundaryY,
+        knotsCount,
+        distortionMean,
+        distortionStdDev,
+        distortionFrequency,
+        tween,
+        targetPoints
+    };
+}