bezier-mouse-js

Lightweight library to generate human-like mouse movements with Bezier curves.

Straight-line mouse movements are a dead giveaway for automation. This library generates natural, curved paths that look human — plug the points into Playwright, Puppeteer, or any framework that takes {x, y} coordinates. Or use the built-in nut-js integration to control the mouse directly.

Use cases

• Browser automation — Natural mouse paths for Playwright, Puppeteer, or Selenium scripts
• Desktop automation — Control the mouse with human-like movement via nut-js
• AI computer-use agents — Give screen-controlling agents realistic cursor behavior

Getting Started

# Core library (curve generation only — works everywhere)
npm install bezier-mouse-js

# With mouse control (requires @nut-tree/nut-js)
npm install bezier-mouse-js @nut-tree/nut-js

ESM

import { BezierMouse } from "bezier-mouse-js";

const bezMouse = new BezierMouse();

// Generate curve points (no dependencies required)
const points = bezMouse.bezierCurveTo({ x: 100, y: 100 }, { x: 700, y: 700 });

// Move and click (requires @nut-tree/nut-js)
await bezMouse.moveAndClick({ x: 100, y: 100 }, { x: 700, y: 700 });

CommonJS

const { BezierMouse } = require("bezier-mouse-js");

const bezMouse = new BezierMouse();
await bezMouse.moveAndClick({ x: 100, y: 100 }, { x: 700, y: 700 });

API

new BezierMouse(mouseSpeed?)

| Param | Type | Default | Description | |-------|------|---------|-------------| | mouseSpeed | number | 100 | Mouse movement speed in pixels per second (used with nut-js) |

bezierCurveTo(initPos, finPos, opts?) → Point[]

Generate an array of {x, y} points along a human-like Bezier curve. Pure math — no dependencies required.

| Param | Type | Default | Description | |-------|------|---------|-------------| | initPos | {x, y} | — | Starting position | | finPos | {x, y} | — | Target position | | opts.deviation | number | 20 | Curve deviation magnitude. Larger = more curve | | opts.flip | boolean | false | Anchor control points from initPos instead of finPos | | opts.steps | number | 100 | Number of points on the curve |

cubicBezierCurve(initPos, finPos, opts?) → Bezier

Returns the raw bezier-js Bezier object for a cubic curve. Pure math.

| Param | Type | Default | Description | |-------|------|---------|-------------| | initPos | {x, y} | — | Starting position | | finPos | {x, y} | — | Target position | | opts.deviation | number | 20 | Curve deviation magnitude | | opts.flip | boolean | false | Anchor control points from initPos |

getBezierControlPoint(initPos, finPos, opts?) → Point

Compute a single pseudo-random Bezier control point. Pure math.

| Param | Type | Default | Description | |-------|------|---------|-------------| | initPos | {x, y} | — | Starting position | | finPos | {x, y} | — | Target position | | opts.deviation | number | 20 | Curve deviation magnitude | | opts.flip | boolean | false | Anchor control points from initPos |

moveAndClick(initPos, finPos, clickType?, opts?) → Promise<void>

Move the mouse along a Bezier curve and click. Requires @nut-tree/nut-js.

| Param | Type | Default | Description | |-------|------|---------|-------------| | initPos | {x, y} | — | Starting position | | finPos | {x, y} | — | Target position | | clickType | "LEFT" \| "MIDDLE" \| "RIGHT" | "LEFT" | Mouse button | | opts.preciseClick | boolean | false | Click exact coordinates (no random deviation) | | opts.deviation | number | 20 | Curve deviation magnitude | | opts.flip | boolean | false | Anchor control points from initPos | | opts.steps | number | 100 | Number of points on the curve |

moveAndDoubleClick(initPos, finPos, clickType?, opts?) → Promise<void>

Same as moveAndClick but double-clicks. Requires @nut-tree/nut-js.

move(initPos, finPos, opts?) → Promise<void>

Move the mouse along a Bezier curve without clicking. Requires @nut-tree/nut-js.

| Param | Type | Default | Description | |-------|------|---------|-------------| | initPos | {x, y} | — | Starting position | | finPos | {x, y} | — | Target position | | opts.preciseClick | boolean | false | Move to exact coordinates (no random deviation) | | opts.deviation | number | 20 | Curve deviation magnitude | | opts.flip | boolean | false | Anchor control points from initPos | | opts.steps | number | 100 | Number of points on the curve |

Using with Playwright

import { BezierMouse } from "bezier-mouse-js";
import { chromium } from "playwright";

const browser = await chromium.launch();
const page = await browser.newPage();
await page.goto("https://example.com");

const bezMouse = new BezierMouse();
const points = bezMouse.bezierCurveTo(
  { x: 100, y: 100 },
  { x: 500, y: 300 },
  { steps: 50 }
);

// Move through each point with a small delay for natural movement
for (const point of points) {
  await page.mouse.move(point.x, point.y);
}
await page.mouse.click(500, 300);

Using with Puppeteer

import { BezierMouse } from "bezier-mouse-js";
import puppeteer from "puppeteer";

const browser = await puppeteer.launch();
const page = await browser.newPage();
await page.goto("https://example.com");

const bezMouse = new BezierMouse();
const points = bezMouse.bezierCurveTo(
  { x: 100, y: 100 },
  { x: 500, y: 300 },
  { steps: 50 }
);

for (const point of points) {
  await page.mouse.move(point.x, point.y);
}
await page.mouse.click(500, 300);

Demo

Live Demo

License

MIT