From 788f692e1adeaa66af76145ed716f61c158bd6bc Mon Sep 17 00:00:00 2001
From: Blake V <87083504+bvandercar-vt@users.noreply.github.com>
Date: Wed, 8 May 2024 03:07:39 -0600
Subject: [PATCH] feat: overshootThreshold option (#127)

* feat: allow overshootThreshold option

* feat: readme

* style: docstring
---
 README.md    |  1 +
 src/spoof.ts | 26 ++++++++++++++++++++++----
 2 files changed, 23 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index 2a7fa3e..542c634 100644
--- a/README.md
+++ b/README.md
@@ -100,6 +100,7 @@ Moves the mouse to the specified selector or element.
   - `moveDelay (number):` Delay after moving the mouse in milliseconds. Default is `2000`.
   - `maxTries (number):` Maximum number of attempts to mouse-over the element. Default is `10`.
   - `moveSpeed (number):` Speed of mouse movement. Default is random.
+  - `overshootThreshold (number):` Distance from current location to destination that triggers overshoot to occur. (Below this distance, no overshoot will occur). Default is `500`.
 
 #### `moveTo(destination: Vector): Promise<void>`
 
diff --git a/src/spoof.ts b/src/spoof.ts
index c16e62f..01e7328 100644
--- a/src/spoof.ts
+++ b/src/spoof.ts
@@ -41,6 +41,12 @@ export interface MoveOptions extends BoxOptions {
    * Default is random.
    */
   readonly moveSpeed?: number
+  /**
+   * Distance from current location to destination that triggers overshoot to
+   * occur. (Below this distance, no overshoot will occur).
+   * @default 500
+   */
+  readonly overshootThreshold?: number
 }
 
 export interface ClickOptions extends MoveOptions {
@@ -218,9 +224,8 @@ const clampPositive = (vectors: Vector[]): Vector[] => {
   })
 }
 
-const overshootThreshold = 500
-const shouldOvershoot = (a: Vector, b: Vector): boolean =>
-  magnitude(direction(a, b)) > overshootThreshold
+const shouldOvershoot = (a: Vector, b: Vector, threshold: number): boolean =>
+  magnitude(direction(a, b)) > threshold
 
 const intersectsElement = (vec: Vector, box: BoundingBox): boolean => {
   return (
@@ -247,7 +252,16 @@ const boundingBoxWithFallback = async (
 
 export const createCursor = (
   page: Page,
+  /**
+   * Cursor start position.
+   * @default { x: 0, y: 0 }
+   */
   start: Vector = origin,
+  /**
+   * Initially perform random movements.
+   * If `move`,`click`, etc. is performed, these random movements end.
+   * @default false
+   */
   performRandomMoves: boolean = false
 ): GhostCursor => {
   // this is kind of arbitrary, not a big fan but it seems to work
@@ -383,7 +397,11 @@ export const createCursor = (
         const { height, width } = box
         const destination = getRandomBoxPoint(box, options)
         const dimensions = { height, width }
-        const overshooting = shouldOvershoot(previous, destination)
+        const overshooting = shouldOvershoot(
+          previous,
+          destination,
+          options?.overshootThreshold ?? 500
+        )
         const to = overshooting
           ? overshoot(destination, overshootRadius)
           : destination