Skip to content

feat: Split core and puppeteer features #171

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
regseb wants to merge 1 commit into
base: master
Choose a base branch
from
Open

feat: Split core and puppeteer features #171

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 11 additions & 0 deletions package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,17 @@
"version": "1.4.1",
"description": "Move your mouse like a human in puppeteer or generate realistic movements on any 2D plane",
"repository": "https://github.com/Xetera/ghost-cursor",
"exports": {
".": {
"types": "./lib/spoof.d.ts",
"default": "./lib/spoof.js"
},
"./core": {
"types": "./lib/core.d.ts",
"default": "./lib/core.js"
},
Comment on lines +6 to +14
Copy link

Copilot AI Apr 15, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

PR metadata/issue link indicates this should fix TS users who only import path() without having puppeteer installed, but the root export (".") still points to ./lib/spoof.d.ts, which imports puppeteer types. That means import { path } from 'ghost-cursor' will still fail unless consumers switch to ghost-cursor/core. Consider either (a) making the root export point to core and adding an explicit ./spoof subpath for Puppeteer-specific APIs, or (b) updating public docs (README/changelog) to direct non-Puppeteer users to ghost-cursor/core so the linked issue is actually resolved for readers.

Copilot uses AI. Check for mistakes.
Copy link
Copy Markdown
Collaborator

@Niek Niek Apr 15, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@hat do you think @regseb?

Comment on lines +10 to +14
Copy link

Copilot AI Apr 15, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Adding a package exports map restricts consumers from importing any previously-available deep paths (e.g. ghost-cursor/lib/... or ghost-cursor/mouse-helper) unless they are explicitly listed. If this package has downstream users relying on those deep imports, this becomes a breaking change. Consider explicitly exporting any intended public subpaths (at least ./spoof, ./mouse-helper, etc.) or doing this behind a major version bump.

Suggested change
},
"./core": {
"types": "./lib/core.d.ts",
"default": "./lib/core.js"
},
},
"./spoof": {
"types": "./lib/spoof.d.ts",
"default": "./lib/spoof.js"
},
"./core": {
"types": "./lib/core.d.ts",
"default": "./lib/core.js"
},
"./lib/*": "./lib/*",

Copilot uses AI. Check for mistakes.
Copy link
Copy Markdown
Collaborator

@Niek Niek Apr 15, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think people imported these directly, since they are not documented. Right, @regseb?

"./package.json": "./package.json"
},
"main": "lib/spoof.js",
"types": "lib/spoof.d.ts",
"scripts": {
Expand Down
112 changes: 112 additions & 0 deletions src/core.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,112 @@
import {
type Vector,
type TimedVector,
type Rectangle,
bezierCurve,
bezierCurveSpeed,
extrapolate
} from './math'

export interface PathOptions {
/**
* Override the spread of the generated path.
*/
readonly spreadOverride?: number
/**
* Speed of mouse movement.
* Default is random.
*/
readonly moveSpeed?: number

/**
* Generate timestamps for each point in the path.
*/
readonly useTimestamps?: boolean
}

/**
* Calculate the amount of time needed to move from (x1, y1) to (x2, y2)
* given the width of the element being clicked on
* https://en.wikipedia.org/wiki/Fitts%27s_law
*/
const fitts = (distance: number, width: number): number => {
const a = 0
const b = 2
const id = Math.log2(distance / width + 1)
return a + b * id
}

/** Generates a set of points for mouse movement between two coordinates. */
export function path (
start: Vector,
end: Vector | Rectangle,
/**
* Additional options for generating the path.
* Can also be a number which will set `spreadOverride`.
*/
// TODO: remove number arg in next major version change, fine to just allow `spreadOverride` in object.
options?: number | PathOptions): Vector[] | TimedVector[] {
const optionsResolved: PathOptions = typeof options === 'number'
? { spreadOverride: options }
: { ...options }

const DEFAULT_WIDTH = 100
const MIN_STEPS = 25
const width = 'width' in end && end.width !== 0 ? end.width : DEFAULT_WIDTH
const curve = bezierCurve(start, end, optionsResolved.spreadOverride)
const length = curve.length() * 0.8

const speed = optionsResolved.moveSpeed !== undefined && optionsResolved.moveSpeed > 0
? (25 / optionsResolved.moveSpeed)
: Math.random()
const baseTime = speed * MIN_STEPS
const steps = Math.ceil((Math.log2(fitts(length, width) + 1) + baseTime) * 3)
const re = curve.getLUT(steps)
return clampPositive(re, optionsResolved)
}
Comment on lines +39 to +66
Copy link

Copilot AI Apr 15, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

src/core.ts introduces a new public entry point (ghost-cursor/core) and moves core path-generation logic there, but the test suite currently only exercises spoof behavior. Add a small unit test that imports from ../core and asserts basic invariants of path() output (e.g., starts/ends near the requested points, returns non-negative coordinates, timestamps strictly increase when useTimestamps is enabled) to prevent regressions and ensure this entry point stays Puppeteer-free.

Copilot uses AI. Check for mistakes.
Copy link
Copy Markdown
Collaborator

@Niek Niek Apr 15, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@copilot create a unit test based on this feedback. make sure to test the most common edge-cases.


const clampPositive = (vectors: Vector[], options?: PathOptions): Vector[] | TimedVector[] => {
const clampedVectors = vectors.map((vector) => ({
x: Math.max(0, vector.x),
y: Math.max(0, vector.y)
}))

return options?.useTimestamps === true ? generateTimestamps(clampedVectors, options) : clampedVectors
}

const generateTimestamps = (vectors: Vector[], options?: PathOptions): TimedVector[] => {
const speed = options?.moveSpeed ?? (Math.random() * 0.5 + 0.5)
const timeToMove = (P0: Vector, P1: Vector, P2: Vector, P3: Vector, samples: number): number => {
let total = 0
const dt = 1 / samples

for (let t = 0; t < 1; t += dt) {
const v1 = bezierCurveSpeed(t * dt, P0, P1, P2, P3)
const v2 = bezierCurveSpeed(t, P0, P1, P2, P3)
total += (v1 + v2) * dt / 2
}

return Math.round(total / speed)
}

const timedVectors: TimedVector[] = []

for (let i = 0; i < vectors.length; i++) {
if (i === 0) {
timedVectors.push({ ...vectors[i], timestamp: Date.now() })
} else {
const P0 = vectors[i - 1]
const P1 = vectors[i]
const P2 = i + 1 < vectors.length ? vectors[i + 1] : extrapolate(P0, P1)
const P3 = i + 2 < vectors.length ? vectors[i + 2] : extrapolate(P1, P2)
const time = timeToMove(P0, P1, P2, P3, vectors.length)

timedVectors.push({
...vectors[i],
timestamp: timedVectors[i - 1].timestamp + time
})
}
}

return timedVectors
}
5 changes: 5 additions & 0 deletions src/math.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,11 @@ export interface Vector {
export interface TimedVector extends Vector {
timestamp: number
}
export interface Rectangle extends Vector {
width: number
height: number
}

export const origin: Vector = { x: 0, y: 0 }

// maybe i should've just imported a vector library lol
Expand Down
113 changes: 3 additions & 110 deletions src/spoof.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,23 +1,20 @@
import type { ElementHandle, Page, BoundingBox, CDPSession, Protocol } from 'puppeteer'
import debug from 'debug'
import { type PathOptions, path } from './core'
import {
type Vector,
type TimedVector,
bezierCurve,
bezierCurveSpeed,
direction,
magnitude,
origin,
overshoot,
add,
clamp,
scale,
extrapolate
scale
} from './math'
import { installMouseHelper } from './mouse-helper'

// TODO: remove in next major version, is now wrapped in the GhostCursor class.
export { installMouseHelper }
export { type PathOptions, path, installMouseHelper }

const log = debug('ghost-cursor')

Expand Down Expand Up @@ -128,23 +125,6 @@ export interface ClickOptions extends MoveOptions {
readonly clickCount?: number
}

export interface PathOptions {
/**
* Override the spread of the generated path.
*/
readonly spreadOverride?: number
/**
* Speed of mouse movement.
* Default is random.
*/
readonly moveSpeed?: number

/**
* Generate timestamps for each point in the path.
*/
readonly useTimestamps?: boolean
}

export interface RandomMoveOptions extends Pick<MoveOptions, 'moveDelay' | 'randomizeMoveDelay' | 'moveSpeed'> {
/**
* @default 2000
Expand Down Expand Up @@ -205,18 +185,6 @@ const delay = async (ms: number): Promise<void> => {
return await new Promise((resolve) => setTimeout(resolve, ms))
}

/**
* Calculate the amount of time needed to move from (x1, y1) to (x2, y2)
* given the width of the element being clicked on
* https://en.wikipedia.org/wiki/Fitts%27s_law
*/
const fitts = (distance: number, width: number): number => {
const a = 0
const b = 2
const id = Math.log2(distance / width + 1)
return a + b * id
}

/** Get a random point on a box */
const getRandomBoxPoint = (
{ x, y, width, height }: BoundingBox,
Expand Down Expand Up @@ -310,81 +278,6 @@ export const getElementBox = async (
}
}

/** Generates a set of points for mouse movement between two coordinates. */
export function path (
start: Vector,
end: Vector | BoundingBox,
/**
* Additional options for generating the path.
* Can also be a number which will set `spreadOverride`.
*/
// TODO: remove number arg in next major version change, fine to just allow `spreadOverride` in object.
options?: number | PathOptions): Vector[] | TimedVector[] {
const optionsResolved: PathOptions = typeof options === 'number'
? { spreadOverride: options }
: { ...options }

const DEFAULT_WIDTH = 100
const MIN_STEPS = 25
const width = 'width' in end && end.width !== 0 ? end.width : DEFAULT_WIDTH
const curve = bezierCurve(start, end, optionsResolved.spreadOverride)
const length = curve.length() * 0.8

const speed = optionsResolved.moveSpeed !== undefined && optionsResolved.moveSpeed > 0
? (25 / optionsResolved.moveSpeed)
: Math.random()
const baseTime = speed * MIN_STEPS
const steps = Math.ceil((Math.log2(fitts(length, width) + 1) + baseTime) * 3)
const re = curve.getLUT(steps)
return clampPositive(re, optionsResolved)
}

const clampPositive = (vectors: Vector[], options?: PathOptions): Vector[] | TimedVector[] => {
const clampedVectors = vectors.map((vector) => ({
x: Math.max(0, vector.x),
y: Math.max(0, vector.y)
}))

return options?.useTimestamps === true ? generateTimestamps(clampedVectors, options) : clampedVectors
}

const generateTimestamps = (vectors: Vector[], options?: PathOptions): TimedVector[] => {
const speed = options?.moveSpeed ?? (Math.random() * 0.5 + 0.5)
const timeToMove = (P0: Vector, P1: Vector, P2: Vector, P3: Vector, samples: number): number => {
let total = 0
const dt = 1 / samples

for (let t = 0; t < 1; t += dt) {
const v1 = bezierCurveSpeed(t * dt, P0, P1, P2, P3)
const v2 = bezierCurveSpeed(t, P0, P1, P2, P3)
total += (v1 + v2) * dt / 2
}

return Math.round(total / speed)
}

const timedVectors: TimedVector[] = []

for (let i = 0; i < vectors.length; i++) {
if (i === 0) {
timedVectors.push({ ...vectors[i], timestamp: Date.now() })
} else {
const P0 = vectors[i - 1]
const P1 = vectors[i]
const P2 = i + 1 < vectors.length ? vectors[i + 1] : extrapolate(P0, P1)
const P3 = i + 2 < vectors.length ? vectors[i + 2] : extrapolate(P1, P2)
const time = timeToMove(P0, P1, P2, P3, vectors.length)

timedVectors.push({
...vectors[i],
timestamp: timedVectors[i - 1].timestamp + time
})
}
}

return timedVectors
}

const shouldOvershoot = (a: Vector, b: Vector, threshold: number): boolean =>
magnitude(direction(a, b)) > threshold

Expand Down