How `humanize=True` Creates Human-Like Mouse Bézier Curves in CloakBrowser

When humanize=True is passed to launch(), CloakBrowser patches Playwright's mouse methods to route all cursor movements through a cubic Bézier curve generator that simulates natural human hand tremors, acceleration curves, and overshoot corrections.

CloakBrowser is an open-source automation library designed to evade bot detection by mimicking human behavior. When you enable the humanize=True flag during browser launch, the library intercepts every mouse action—from clicks to hovers—and replaces Playwright's instant cursor jumps with mathematically modeled Bézier paths that replicate real hand movements.

Intercepting Playwright Actions in __init__.py

The humanization process begins in cloakbrowser/human/__init__.py, where the patch_page function replaces native Playwright methods with specialized wrappers. According to the CloakHQ/CloakBrowser source code, this patching occurs around lines 68-94 and redirects standard mouse operations through the human-like movement layer:

• page.click → _human_click
• page.hover → _human_hover
• page.mouse.move → _human_mouse_move

These wrappers ensure that before any click or hover executes, the cursor first travels along a realistic trajectory computed by the human_move function.

Cubic Bézier Generation in mouse.py

The core algorithm resides in cloakbrowser/human/mouse.py. The human_move(raw, start_x, start_y, end_x, end_y, cfg) function constructs a cubic Bézier curve between coordinates, transforming linear paths into organic arcs.

Randomized Control Points

To create natural variation, the implementation calls _random_control_points to generate orthogonal offsets from the straight-line trajectory. These control points introduce the subtle "wiggle" characteristic of human hand movements, ensuring no two cursor paths are identical.

Ease-In-Out Acceleration

The progression along the curve utilizes an _ease_in_out cubic function rather than linear interpolation. This mimics biological motion where muscles require time to accelerate and decelerate, creating the characteristic slowing effect as the cursor approaches its target.

Simulating Biological Imperfections

Beyond smooth curves, CloakBrowser injects specific micro-behaviors observed in real user interactions.

Hand Tremor Simulation

The algorithm applies sinusoidal wobble adjustments controlled by the mouse_wobble_max parameter from HumanConfig. These tiny oscillations replicate the involuntary muscle tremors present even in steady human hands.

Overshoot and Correction

With a probability defined by mouse_overshoot_chance, the cursor deliberately moves slightly past the target before settling back. This mirrors the natural correction behavior when a human overshoots a button and makes a subtle adjustment to land precisely.

Burst Pauses

The system inserts micro-pauses during movement to simulate the brief hesitations and processing delays inherent in biological motor control, breaking the mechanical consistency of automated scripts.

Action Flow: From Method Call to Movement

When _human_click executes, the wrapper follows a precise sequence defined in cloakbrowser/human/__init__.py (lines 69-84):

1. Scroll the target element into view using scroll_to_element
2. Calculate the exact click target via click_target
3. Invoke human_move to traverse from cursor.x, cursor.y to target.x, target.y along a Bézier curve
4. Update cursor position tracking
5. Execute human_click through the raw mouse interface

This same pipeline applies to hover operations and their async equivalents, ensuring consistent human-like behavior across all interaction types.

Configuration Through HumanConfig

Behavioral parameters are centralized in cloakbrowser/human/config.py within the HumanConfig class. Key tunables include:

• mouse_min_steps and mouse_max_steps: Define the resolution of the Bézier curve interpolation
• mouse_wobble_max: Controls the amplitude of sinusoidal tremor injection
• mouse_overshoot_chance: Probability (0.0-1.0) of executing a correction movement
• Timing ranges for delays and pauses between actions

These settings enable emulation of different user personas, from rapid "default" interactions to deliberate "careful" movements.

Implementation Examples

To enable humanized mouse movements, pass humanize=True when launching the browser:

from cloakbrowser import launch

# Launch with human-like mouse behavior

browser = launch(headless=False, humanize=True)
page = browser.new_page()
page.goto("https://example.com")

# All subsequent actions use Bézier curves internally

page.click("#login")          # Smooth approach curve + click

page.hover("#menu")           # Natural arc to hover position

page.type("#search", "test")  # Human-like entry into input field

For async implementations:

from cloakbrowser import launch_async

browser = await launch_async(headless=False, humanize=True)
page = await browser.new_page()
await page.goto("https://example.com")
await page.click("#login")   # Async human_move under the hood

Summary

• humanize=True activates a patching mechanism in cloakbrowser/human/__init__.py that intercepts all Playwright mouse methods
• Movement paths are calculated as cubic Bézier curves in cloakbrowser/human/mouse.py using randomized control points and ease-in-out interpolation
• Realism is enhanced through configurable wobble, overshoot corrections, and burst pauses defined in HumanConfig
• The system preserves the standard Playwright API while replacing instantaneous movements with biologically plausible trajectories

Frequently Asked Questions

Which source file contains the Bézier curve mathematics?

The curve generation logic resides in cloakbrowser/human/mouse.py, specifically within the human_move() function. This file implements the cubic Bézier interpolation, control point randomization via _random_control_points, and easing calculations that define the cursor's trajectory.

Can I adjust the probability of overshoot movements?

Yes. The mouse_overshoot_chance parameter in HumanConfig (defined in cloakbrowser/human/config.py) accepts a float between 0.0 and 1.0 to control how frequently the cursor simulates overshooting and correcting its position. Higher values increase the frequency of these correction micro-movements.

Does humanize mode affect typing speed and keyboard input?

While the primary focus of humanize=True is mouse movement via Bézier curves, the patching layer in cloakbrowser/human/__init__.py also wraps input methods. The system introduces variable delays between keystrokes in page.type() operations to match the irregular rhythm of human typing, though this uses timing distributions rather than spatial curves.

What is the performance impact of calculating Bézier curves?

The overhead is minimal for typical automation tasks. The human_move function generates a discrete point sequence (controlled by mouse_min_steps and mouse_max_steps) and iterates through them with small delays. For most web automation scenarios, the additional 100-400ms of movement time is insignificant compared to network latency and page load times.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}