How to Customize human_config for Typing Delays and Typo Simulation in CloakBrowser

You can customize typing delays and typo simulation in CloakBrowser by passing a human_config object to resolveConfig() for global settings or directly to interaction methods like page.type() for per-call overrides, with all numeric parameters defined in js/src/human/config.ts.

CloakBrowser simulates human-like interactions through a configurable HumanConfig system that controls keystroke timing, pauses, and error generation. The library stores all behavioral parameters in js/src/human/config.ts and applies them via the resolveConfig() and mergeConfig() utilities. This guide demonstrates how to adjust these settings globally for an entire page or override them for specific input fields.

Understanding the HumanConfig Parameters

The HumanConfig interface defines numeric values that control three distinct aspects of keyboard interaction: typing cadence, typo simulation, and physical key mechanics.

Typing Speed Controls

These parameters manage the delay between characters and occasional pauses:

• typing_delay: The base delay in milliseconds between consecutive keystrokes.
• typing_delay_spread: Random variance added to the base delay to avoid robotic consistency.
• typing_pause_chance: Probability (0.0 to 1.0) that the "typist" pauses mid-word.
• typing_pause_range: Tuple defining the minimum and maximum pause length in milliseconds.

Typo Simulation Settings

According to js/src/human/config.ts, these values control realistic error generation:

• mistype_chance: Probability that a keystroke will register as an error.
• mistype_delay_notice: Milliseconds before the typo is detected and backspace is initiated.
• mistype_delay_correct: Milliseconds between backspace and the replacement keystroke.

Key Press Mechanics

Physical interaction timing is controlled by:

• shift_down_delay / shift_up_delay: Delays before and after pressing Shift for capitals or symbols.
• key_hold: Duration in milliseconds that a key remains pressed before release.

Global Configuration Using resolveConfig

To establish default behavior for an entire browser page, use the resolveConfig() function exported from js/src/human/config.ts. This function accepts a preset name ('default' or 'careful') and an optional overrides object, returning a complete configuration object.

The resolveConfig() implementation performs a shallow merge of the preset values with your custom overrides:

// js/src/human/config.ts
export function resolveConfig(preset: HumanPreset = 'default',
                             overrides?: Partial<HumanConfig>): HumanConfig { … }

Apply the configuration globally by patching the page instance:

import { resolveConfig } from 'cloakbrowser/human/config';

// Use default preset but reduce typing delay to 35ms
const cfg = resolveConfig('default', { 
  typing_delay: 35, 
  typing_delay_spread: 20 
});

await cloakBrowser.patch(page, cfg);

The default preset ships with values like typing_delay: 70 and mistype_chance: 0.02, while the 'careful' preset uses slower, more deliberate timing.

Per-Call Overrides in Type Actions

For field-specific customization, pass a human_config object directly to typing methods such as page.type() or elementHandle.type(). Internally, the library calls mergeConfig(cfg, options?.human_config) inside js/src/human/index.ts to create a temporary configuration scoped to that single action.

This approach allows a page patched with default settings to exhibit different behavior when filling specific forms:

// Type into username field quickly without typos
await page.type('#username', 'alice', {
  human_config: {
    typing_delay: 20,
    typing_delay_spread: 5,
    mistype_chance: 0
  }
});

The mergeConfig() utility combines the global configuration with your per-call overrides, ensuring that unspecified parameters inherit from the page defaults while your custom values take precedence for that operation.

Practical Code Examples

1. Customizing Global Typing Speed

Reduce the base typing delay while maintaining default typo behavior across the entire page:

import { resolveConfig } from 'cloakbrowser/human/config';

const cfg = resolveConfig('default', { 
  typing_delay: 35, 
  typing_delay_spread: 20 
});

await cloakBrowser.patch(page, cfg);

Source: js/src/human/config.ts – resolveConfig

2. Disabling Typos for Specific Fields

When you need perfect accuracy for sensitive inputs like usernames or passwords:

await page.type('#username', 'alice', {
  human_config: {
    typing_delay: 20,
    typing_delay_spread: 5,
    mistype_chance: 0
  }
});

Source: js/src/human/index.ts – humanTypeFn

3. Enabling Aggressive Typo Simulation

Start with the slower careful preset and increase error frequency for demo scenarios:

import { resolveConfig } from 'cloakbrowser/human/config';

const cfg = resolveConfig('careful', { mistype_chance: 0.1 });
await cloakBrowser.patch(page, cfg);

Source: js/src/human/config.ts – CAREFUL_CONFIG

4. Combining Global Defaults with Field-Specific Pauses

Patch the page with standard settings, then apply extended pauses only when typing long-form content:

await cloakBrowser.patch(page, resolveConfig('default'));

await page.type('#comment', 'Detailed feedback here', {
  human_config: { 
    typing_pause_chance: 0.3, 
    typing_pause_range: [500, 1500] 
  }
});

Source: js/src/human/index.ts – merge logic used throughout interaction handlers

Summary

• Configuration location: All human_config parameters reside in js/src/human/config.ts, including typing_delay, mistype_chance, and shift_down_delay.
• Global application: Use resolveConfig(preset, overrides) combined with cloakBrowser.patch() to set page-wide defaults.
• Local overrides: Pass human_config directly to page.type() or element.type() for action-specific customization via the internal mergeConfig() function.
• Presets available: Choose between 'default' (standard human-like speed) and 'careful' (slower, more deliberate) as starting points.
• Scope isolation: Per-call overrides merge with global settings, ensuring changes affect only the targeted input without altering page-level behavior.

Frequently Asked Questions

Where are the default human_config values defined in CloakBrowser?

The default values are defined in the DEFAULT_CONFIG constant within js/src/human/config.ts. This object specifies values like typing_delay: 70 and mistype_chance: 0.02, which serve as the baseline when using the 'default' preset in resolveConfig().

Can I disable typo simulation entirely while keeping typing delays?

Yes. Set mistype_chance: 0 in your human_config object either globally via resolveConfig('default', { mistype_chance: 0 }) or per-call within the options argument of page.type(). This prevents the humanType routine from simulating keystroke errors while preserving all delay and timing behaviors.

What is the difference between the 'default' and 'careful' presets?

The 'default' preset uses moderate timing values suitable for most automation tasks, whereas the 'careful' preset, defined as CAREFUL_CONFIG in js/src/human/config.ts, increases delays between actions and adds more variance to appear more deliberate and cautious. The careful preset is useful when interacting with sensitive forms that might flag rapid, robotic input.

How do I apply different typing speeds to different input fields on the same page?

First, patch the page with your base configuration using cloakBrowser.patch(). Then, supply a human_config override object to individual page.type() or element.type() calls. The internal mergeConfig() function in js/src/human/index.ts combines the global settings with your per-call parameters, allowing specific fields to type faster or slower without affecting others.

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