Skip to content

High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.

feat: exposing humanize for some action, default to false

Luigi Agostiaed8be8d7250
diff --git a/cmd/pinchtab/cmd_cli_register.go b/cmd/pinchtab/cmd_cli_register.go
index 88e74ffa..1aba5a64 100644
--- a/cmd/pinchtab/cmd_cli_register.go
+++ b/cmd/pinchtab/cmd_cli_register.go
@@ -147,26 +147,35 @@ func configureBrowserFlags() {
clickCmd.Flags().Bool("text", false, "Output page text after action (for verification)")
clickCmd.Flags().String("dialog-action", "", "Auto-handle a JS dialog opened by the click: accept | dismiss")
clickCmd.Flags().String("dialog-text", "", "Prompt response text (with --dialog-action accept on prompt())")
+ clickCmd.Flags().Bool("humanize", false, "Use humanized bezier+jitter input path (overrides instance config)")
dblclickCmd.Flags().String("css", "", "CSS selector instead of ref")
addPointFlags(dblclickCmd, "dblclick")
+ dblclickCmd.Flags().Bool("humanize", false, "Use humanized bezier+jitter input path (overrides instance config)")
hoverCmd.Flags().String("css", "", "CSS selector instead of ref")
addPointFlags(hoverCmd, "hover")
+ hoverCmd.Flags().Bool("humanize", false, "Use humanized bezier+jitter input path (overrides instance config)")
mouseMoveCmd.Flags().String("css", "", "CSS selector instead of ref")
addPointFlags(mouseMoveCmd, bridge.ActionMouseMove)
+ mouseMoveCmd.Flags().Bool("humanize", false, "Use humanized bezier+jitter input path (overrides instance config)")
mouseDownCmd.Flags().String("css", "", "CSS selector instead of ref")
addPointFlags(mouseDownCmd, bridge.ActionMouseDown)
mouseDownCmd.Flags().String("button", "left", "Mouse button: left, right, middle")
+ mouseDownCmd.Flags().Bool("humanize", false, "Use humanized bezier+jitter input path (overrides instance config)")
mouseUpCmd.Flags().String("css", "", "CSS selector instead of ref")
addPointFlags(mouseUpCmd, bridge.ActionMouseUp)
mouseUpCmd.Flags().String("button", "left", "Mouse button: left, right, middle")
+ mouseUpCmd.Flags().Bool("humanize", false, "Use humanized bezier+jitter input path (overrides instance config)")
mouseWheelCmd.Flags().String("css", "", "CSS selector instead of ref")
addPointFlags(mouseWheelCmd, bridge.ActionMouseWheel)
+ mouseWheelCmd.Flags().Bool("humanize", false, "Use humanized bezier+jitter input path (overrides instance config)")
+
+ typeCmd.Flags().Bool("humanize", false, "Use humanized per-character keypress timing (overrides instance config)")
mouseWheelCmd.Flags().Int("dx", 0, "Wheel delta X")
mouseWheelCmd.Flags().Int("dy", 0, "Wheel delta Y")
diff --git a/internal/bridge/action_pointer.go b/internal/bridge/action_pointer.go
index c4c4d55e..8eed8547 100644
--- a/internal/bridge/action_pointer.go
+++ b/internal/bridge/action_pointer.go
@@ -16,6 +16,28 @@ var mouseMoveByCoordinateAction = MouseMoveByCoordinate
var mouseDownByCoordinateAction = MouseDownByCoordinate
var mouseUpByCoordinateAction = MouseUpByCoordinate
+// effectiveHumanize resolves whether an action should use the humanized
+// (bezier + per-event jitter + pre-press sleeps) input path. Precedence:
+//
+// 1. Per-request override: ActionRequest.Humanize (if non-nil)
+// 2. Per-instance default: bridge Config.Humanize
+// 3. Built-in default: false
+//
+// The action kind is intentionally NOT consulted — both click/type and
+// humanClick/humanType honour the same resolution. This means
+// `kind: humanClick` defaults to raw input unless config.humanize=true
+// or the request explicitly sets humanize:true; callers who relied on
+// the legacy auto-humanizing behaviour need to opt in.
+func (b *Bridge) effectiveHumanize(req ActionRequest) bool {
+ if req.Humanize != nil {
+ return *req.Humanize
+ }
+ if b != nil && b.Config != nil {
+ return b.Config.Humanize
+ }
+ return false
+}
+
const (
dialogAutoHandlePollInterval = 10 * time.Millisecond
dialogAutoHandleSettleDelay = 40 * time.Millisecond
@@ -85,6 +107,13 @@ func submitFormIfButton(ctx context.Context, selector string) (bool, error) {
}
func (b *Bridge) actionClick(ctx context.Context, req ActionRequest) (map[string]any, error) {
+ // Promote to the humanized click path when the caller (or instance
+ // config) opted in via humanize=true. The guard on req.Kind avoids
+ // ping-ponging when actionHumanClick has already delegated here.
+ if req.Kind != ActionHumanClick && b.effectiveHumanize(req) {
+ return b.actionHumanClick(ctx, req)
+ }
+
// Arm a one-shot dialog auto-handler if the caller expects the click
// to open a native JS dialog. Without this, the click would hang
// waiting for the dialog to be handled from a separate request.
@@ -435,6 +464,14 @@ func (b *Bridge) actionDrag(ctx context.Context, req ActionRequest) (map[string]
}
func (b *Bridge) actionHumanClick(ctx context.Context, req ActionRequest) (map[string]any, error) {
+ // Fall through to the raw click path when humanization is disabled.
+ // `kind: humanClick` is preserved as an action name for back-compat,
+ // but its bezier+sleeps semantics now require humanize=true (either
+ // per-request or via instance config).
+ if !b.effectiveHumanize(req) {
+ return b.actionClick(ctx, req)
+ }
+
var backendNodeID cdp.BackendNodeID
switch {
case req.NodeID > 0:
diff --git a/internal/bridge/action_request.go b/internal/bridge/action_request.go
index e500e102..55933709 100644
--- a/internal/bridge/action_request.go
+++ b/internal/bridge/action_request.go
@@ -61,6 +61,12 @@ type ActionRequest struct {
Fast bool `json:"fast"`
Owner string `json:"owner"`
+ // Humanize, when set, overrides the per-instance `humanize` default for
+ // this action only. nil = use the configured default. true forces the
+ // bezier/jitter/pre-press-sleep code path; false forces the raw
+ // straight-to-target dispatch.
+ Humanize *bool `json:"humanize,omitempty"`
+
// DialogAction arms a one-shot dialog auto-handler before the action
// executes. Used when clicking a button/link that opens a JS dialog
// (alert/confirm/prompt). Values: "accept" or "dismiss". When set, the
diff --git a/internal/bridge/action_text.go b/internal/bridge/action_text.go
index 7d044f5f..aee37970 100644
--- a/internal/bridge/action_text.go
+++ b/internal/bridge/action_text.go
@@ -52,6 +52,12 @@ func (b *Bridge) actionHumanType(ctx context.Context, req ActionRequest) (map[st
return nil, fmt.Errorf("text required for humanType")
}
+ // Fall through to the raw keyboard path when humanization is disabled.
+ // Mirrors the actionHumanClick → actionClick fallback.
+ if !b.effectiveHumanize(req) {
+ return b.actionKeyboardType(ctx, req)
+ }
+
if req.Selector != "" {
if err := chromedp.Run(ctx, chromedp.Focus(req.Selector, chromedp.ByQuery)); err != nil {
return nil, err
@@ -86,6 +92,13 @@ func (b *Bridge) actionKeyboardType(ctx context.Context, req ActionRequest) (map
return nil, fmt.Errorf("text required for keyboard-type")
}
+ // Promote to the humanized typing path when humanize=true was opted
+ // into. Guard on req.Kind so actionHumanType's delegation doesn't
+ // bounce back here.
+ if req.Kind != ActionHumanType && b.effectiveHumanize(req) {
+ return b.actionHumanType(ctx, req)
+ }
+
// For long strings, use insertText to avoid timeout (issue #413).
// We still fire a keydown at the start and keyup at the end to trigger
// any key-event listeners that apps might depend on.
diff --git a/internal/cli/actions/actions_element.go b/internal/cli/actions/actions_element.go
index c8ebc266..dbdcd10c 100644
--- a/internal/cli/actions/actions_element.go
+++ b/internal/cli/actions/actions_element.go
@@ -57,6 +57,16 @@ func Action(client *http.Client, base, token, kind, selectorArg string, cmd *cob
}
}
+ // --humanize lets the caller opt into the bezier+jitter input path on
+ // any pointer/typing action. Honours the same precedence as the API
+ // flag (per-request override > instance config > built-in default).
+ // Only set the body field when the flag was explicitly provided so
+ // nil/null is preserved when omitted.
+ if cmd.Flags().Changed("humanize") {
+ v, _ := cmd.Flags().GetBool("humanize")
+ body["humanize"] = v
+ }
+
postAction(client, base, token, cmd, body)
}
@@ -278,6 +288,11 @@ func MouseAction(client *http.Client, base, token, kind string, args []string, c
cli.Fatal("unsupported mouse action: %s", kind)
}
+ if cmd.Flags().Changed("humanize") {
+ v, _ := cmd.Flags().GetBool("humanize")
+ body["humanize"] = v
+ }
+
postAction(client, base, token, cmd, body)
}
@@ -416,5 +431,10 @@ func ActionSimple(client *http.Client, base, token, kind string, args []string,
body["key"] = args[0]
}
+ if cmd.Flags().Changed("humanize") {
+ v, _ := cmd.Flags().GetBool("humanize")
+ body["humanize"] = v
+ }
+
postAction(client, base, token, cmd, body)
}
diff --git a/internal/config/config_file_json.go b/internal/config/config_file_json.go
index 4a27435b..a2642e94 100644
--- a/internal/config/config_file_json.go
+++ b/internal/config/config_file_json.go
@@ -45,6 +45,7 @@ type instanceDefaultsConfigJSON struct {
MaxParallelTabs *int `json:"maxParallelTabs"`
UserAgent string `json:"userAgent"`
NoAnimations *bool `json:"noAnimations"`
+ Humanize *bool `json:"humanize"`
StealthLevel string `json:"stealthLevel"`
TabEvictionPolicy string `json:"tabEvictionPolicy"`
TabPolicy *TabPolicyDefaults `json:"tabPolicy,omitempty"`
diff --git a/internal/config/config_file_marshal.go b/internal/config/config_file_marshal.go
index 2baac6c5..db626512 100644
--- a/internal/config/config_file_marshal.go
+++ b/internal/config/config_file_marshal.go
@@ -83,6 +83,7 @@ func (fc FileConfig) MarshalJSON() ([]byte, error) {
MaxParallelTabs: fc.InstanceDefaults.MaxParallelTabs,
UserAgent: fc.InstanceDefaults.UserAgent,
NoAnimations: fc.InstanceDefaults.NoAnimations,
+ Humanize: fc.InstanceDefaults.Humanize,
StealthLevel: fc.InstanceDefaults.StealthLevel,
TabEvictionPolicy: fc.InstanceDefaults.TabEvictionPolicy,
TabPolicy: fc.InstanceDefaults.TabPolicy,
@@ -242,6 +243,7 @@ func FileConfigFromRuntime(cfg *RuntimeConfig) FileConfig {
maxTabs := cfg.MaxTabs
maxParallelTabs := cfg.MaxParallelTabs
noAnimations := cfg.NoAnimations
+ humanize := cfg.Humanize
allowEvaluate := cfg.AllowEvaluate
allowMacro := cfg.AllowMacro
allowScreencast := cfg.AllowScreencast
@@ -330,6 +332,7 @@ func FileConfigFromRuntime(cfg *RuntimeConfig) FileConfig {
MaxParallelTabs: &maxParallelTabs,
UserAgent: cfg.UserAgent,
NoAnimations: &noAnimations,
+ Humanize: &humanize,
StealthLevel: cfg.StealthLevel,
TabEvictionPolicy: cfg.TabEvictionPolicy,
TabPolicy: tabPolicyDefaultsFromRuntime(cfg),
diff --git a/internal/config/config_load.go b/internal/config/config_load.go
index 4572b0c8..6cd85e81 100644
--- a/internal/config/config_load.go
+++ b/internal/config/config_load.go
@@ -57,6 +57,7 @@ func Load() *RuntimeConfig {
ExtensionPaths: []string{defaultExtensionsDir(userConfigDir())},
UserAgent: "",
NoAnimations: false,
+ Humanize: false,
StealthLevel: "light",
TabEvictionPolicy: "close_lru",
TabLifecyclePolicy: "close_idle",
@@ -400,6 +401,9 @@ func applyFileConfig(cfg *RuntimeConfig, fc *FileConfig) {
if fc.InstanceDefaults.NoAnimations != nil {
cfg.NoAnimations = *fc.InstanceDefaults.NoAnimations
}
+ if fc.InstanceDefaults.Humanize != nil {
+ cfg.Humanize = *fc.InstanceDefaults.Humanize
+ }
if fc.InstanceDefaults.StealthLevel != "" {
cfg.StealthLevel = fc.InstanceDefaults.StealthLevel
}
diff --git a/internal/config/config_types.go b/internal/config/config_types.go
index 731b1837..5d8a6921 100644
--- a/internal/config/config_types.go
+++ b/internal/config/config_types.go
@@ -60,6 +60,7 @@ type RuntimeConfig struct {
ExtensionPaths []string
UserAgent string
NoAnimations bool
+ Humanize bool // when true, mouse moves and clicks use a humanized bezier path with per-step jitter and pre-press delays; default false (raw, fast input)
StealthLevel string
TabEvictionPolicy string // "close_lru" (default), "reject", "close_oldest" — fires on MaxTabs pressure
TabLifecyclePolicy string // "close_idle" (default), "keep" — fires on idle after read/action
@@ -291,6 +292,7 @@ type InstanceDefaultsConfig struct {
MaxParallelTabs *int `json:"maxParallelTabs,omitempty"`
UserAgent string `json:"userAgent,omitempty"`
NoAnimations *bool `json:"noAnimations,omitempty"`
+ Humanize *bool `json:"humanize,omitempty"`
StealthLevel string `json:"stealthLevel,omitempty"`
TabEvictionPolicy string `json:"tabEvictionPolicy,omitempty"` // Deprecated: use TabPolicy.Eviction
TabPolicy *TabPolicyDefaults `json:"tabPolicy,omitempty"`
diff --git a/internal/config/editor_get.go b/internal/config/editor_get.go
index e81e3fd4..dd8a85d0 100644
--- a/internal/config/editor_get.go
+++ b/internal/config/editor_get.go
@@ -170,6 +170,8 @@ func getInstanceDefaultsField(c *InstanceDefaultsConfig, field string) (string,
return c.UserAgent, nil
case "noAnimations":
return formatBoolPtr(c.NoAnimations), nil
+ case "humanize":
+ return formatBoolPtr(c.Humanize), nil
case "stealthLevel":
return c.StealthLevel, nil
case "tabEvictionPolicy":
diff --git a/internal/config/editor_set.go b/internal/config/editor_set.go
index 1a46d1f4..7c268ae7 100644
--- a/internal/config/editor_set.go
+++ b/internal/config/editor_set.go
@@ -260,6 +260,12 @@ func setInstanceDefaultsField(c *InstanceDefaultsConfig, field, value string) er
return fmt.Errorf("instanceDefaults.noAnimations: %w", err)
}
c.NoAnimations = &b
+ case "humanize":
+ b, err := parseBool(value)
+ if err != nil {
+ return fmt.Errorf("instanceDefaults.humanize: %w", err)
+ }
+ c.Humanize = &b
case "stealthLevel":
c.StealthLevel = value
case "tabEvictionPolicy":
diff --git a/tests/e2e/helpers/api-actions.sh b/tests/e2e/helpers/api-actions.sh
index f78b94df..7c7a4728 100644
--- a/tests/e2e/helpers/api-actions.sh
+++ b/tests/e2e/helpers/api-actions.sh
@@ -29,10 +29,13 @@ action_type() {
}
# Human-like click by ref (uses mouse events).
+# Sets humanize=true explicitly: with the new opt-in default, kind=humanClick
+# alone falls through to a raw click. These helpers exist specifically to
+# exercise the bezier+jitter+pre-press-sleep path, so we always opt in.
# Usage: action_human_click "$ref"
action_human_click() {
local ref="$1"
- pt_post /action -d "{\"kind\":\"humanClick\",\"ref\":\"$ref\"}" > /dev/null
+ pt_post /action -d "{\"kind\":\"humanClick\",\"ref\":\"$ref\",\"humanize\":true}" > /dev/null
assert_ok "humanClick ref=$ref"
}
@@ -41,7 +44,7 @@ action_human_click() {
action_human_type() {
local ref="$1"
local text="$2"
- pt_post /action -d "{\"kind\":\"humanType\",\"ref\":\"$ref\",\"text\":\"$text\"}" > /dev/null
+ pt_post /action -d "{\"kind\":\"humanType\",\"ref\":\"$ref\",\"text\":\"$text\",\"humanize\":true}" > /dev/null
assert_ok "humanType '$text' into ref=$ref"
}
@@ -50,7 +53,7 @@ action_human_type() {
action_human_type_selector() {
local selector="$1"
local text="$2"
- pt_post /action -d "{\"kind\":\"humanType\",\"selector\":\"$selector\",\"text\":\"$text\"}" > /dev/null
+ pt_post /action -d "{\"kind\":\"humanType\",\"selector\":\"$selector\",\"text\":\"$text\",\"humanize\":true}" > /dev/null
assert_ok "humanType '$text' into $selector"
}
diff --git a/tests/e2e/scenarios/infra/network-extended.sh b/tests/e2e/scenarios/infra/network-extended.sh
index e99363c4..19f2d1b0 100755
--- a/tests/e2e/scenarios/infra/network-extended.sh
+++ b/tests/e2e/scenarios/infra/network-extended.sh
@@ -266,19 +266,30 @@ end_test
# ─────────────────────────────────────────────────────────────────
start_test "GET /network/export/stream: SSE events on navigation"
-# Start a streaming export in background, navigate, then check output.
-# We use a short timeout curl to capture initial SSE events.
-STREAM_OUTPUT=$(e2e_curl -s -N \
- --max-time 5 \
+# The previous version of this test ran curl as foreground command
+# substitution, which blocked for the whole --max-time before the
+# navigate fired — so no SSE events ever overlapped the stream and
+# the assertion silently fell through to the "no events captured"
+# pass branch. Background the curl so it actually overlaps the
+# navigate, drop the foreground budget from 5s to ~2s.
+STREAM_TMP=$(mktemp)
+e2e_curl -s -N --max-time 2 \
-H "Content-Type: application/json" \
"${E2E_SERVER}/network/export/stream?tabId=${TAB_ID}&format=har&path=e2e-stream.har" \
- 2>/dev/null || true)
+ > "$STREAM_TMP" 2>/dev/null &
+SSE_PID=$!
-# Trigger traffic while the stream might still be running
+# Brief delay to let the stream open before generating traffic.
+sleep 0.2
+
+# Trigger traffic while the stream is still running.
pt_post /navigate "{\"url\":\"${FIXTURES_URL}/form.html\"}"
-sleep 2
-# The curl with --max-time will have timed out by now. Check output.
+# Wait for the SSE curl to hit --max-time and return.
+wait "$SSE_PID" 2>/dev/null || true
+STREAM_OUTPUT=$(cat "$STREAM_TMP")
+rm -f "$STREAM_TMP"
+
if echo "$STREAM_OUTPUT" | grep -q "event:"; then
echo -e " ${GREEN}✓${NC} received SSE events from stream"
((ASSERTIONS_PASSED++)) || true
diff --git a/tests/e2e/scenarios/infra/orchestrator-extended.sh b/tests/e2e/scenarios/infra/orchestrator-extended.sh
index 1e8541b2..ca48afa7 100644
--- a/tests/e2e/scenarios/infra/orchestrator-extended.sh
+++ b/tests/e2e/scenarios/infra/orchestrator-extended.sh
@@ -156,6 +156,16 @@ assert_ok "instance tabs"
end_test
+# ─────────────────────────────────────────────────────────────────
+# Run the ID-format check before the stop test so it can reuse the
+# still-running INST_ID from "launch new instance" instead of paying
+# another full launch+stop cycle (~6s) just to inspect the prefix.
+start_test "orchestrator: ID format (inst_ prefix)"
+
+assert_instance_id_prefix "$INST_ID"
+
+end_test
+
# ─────────────────────────────────────────────────────────────────
start_test "orchestrator: stop instance"
@@ -168,19 +178,6 @@ assert_instance_list_absent "$INST_ID" "instance removed after stop" "instance s
end_test
-# ─────────────────────────────────────────────────────────────────
-start_test "orchestrator: ID format (inst_ prefix)"
-
-pt_post /instances/start '{"mode":"headless"}'
-assert_ok "launch"
-ID_CHECK_INST=$(echo "$RESULT" | jq -r '.id')
-
-assert_instance_id_prefix "$ID_CHECK_INST"
-
-pt_post "/instances/${ID_CHECK_INST}/stop" '{}'
-
-end_test
-
# ─────────────────────────────────────────────────────────────────
start_test "orchestrator: ports, isolation, and cleanup"
diff --git a/tests/e2e/scenarios/infra/system-extended.sh b/tests/e2e/scenarios/infra/system-extended.sh
index 5e650dc8..00bc6bd2 100644
--- a/tests/e2e/scenarios/infra/system-extended.sh
+++ b/tests/e2e/scenarios/infra/system-extended.sh
@@ -289,8 +289,10 @@ end_test
# ─────────────────────────────────────────────────────────────────
start_test "idpi: same-tab domain pivot warns in warn mode"
+# idpi_setup already does navigate + sleep 1, which covers the fixture's
+# 250ms setTimeout pivot and the follow-up navigation settle. The extra
+# sleep 2 here was redundant.
TAB_ID=$(idpi_setup "$E2E_SERVER" "${FIXTURES_URL}/idpi-domain-pivot.html")
-sleep 2
idpi_request GET "$E2E_SERVER" "/tabs/${TAB_ID}/text" "" "X-IDPI-Warning"
assert_ok "text allowed after domain pivot in warn mode"
assert_header_present "X-IDPI-Warning present after domain pivot"
@@ -300,8 +302,9 @@ end_test
# ─────────────────────────────────────────────────────────────────
start_test "idpi: same-tab domain pivot blocks in strict mode"
+# See note on the warn-mode pivot test above — idpi_setup's internal
+# sleep 1 already covers the pivot timer.
TAB_ID=$(idpi_setup "$E2E_SECURE_SERVER" "${FIXTURES_URL}/idpi-domain-pivot.html")
-sleep 2
idpi_request GET "$E2E_SECURE_SERVER" "/tabs/${TAB_ID}/text" "" "X-IDPI-Warning"
assert_http_status 403 "text blocked after domain pivot in strict mode"
assert_header_present "X-IDPI-Warning present on strict block"