Skip to content

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

fix: reject click mode with humanize

Bosch5117fb079d69
diff --git a/docs/reference/click.md b/docs/reference/click.md
index d5c25b60..99210951 100644
--- a/docs/reference/click.md
+++ b/docs/reference/click.md
@@ -25,7 +25,7 @@ OK
| `--dialog-text` | Prompt response text (with `--dialog-action accept`) |
| `--x`, `--y` | Click at specific coordinates |
| `--humanize` | Use humanized bezier+jitter input path (overrides instance config) |
-| `--mode dom\|dispatch` | Override the default click behavior. Omit `--mode` for the normal click path, use `dom` for `element.click()`, or `dispatch` for synthetic click events on the target |
+| `--mode dom\|dispatch` | Broad low-level escape hatch for click delivery. Omit `--mode` for the normal click path, use `dom` for `element.click()`, or `dispatch` for synthetic click events on the target |
| `--json` | Full JSON response |
| `--tab` | Target specific tab |
@@ -52,8 +52,8 @@ pinchtab click --x 100 --y 200 # Click at coordinates
- Missing selectors fail immediately; use `pinchtab wait` first for dynamic UI (see [`commands.md`](../commands.md))
- The API also accepts `selector` field: `{"kind":"click","selector":"#login"}`
- Click behavior works like this: omit `mode` for the normal click path, use `mode:"dom"` for `element.click()`, or `mode:"dispatch"` for synthetic click events.
-- `mode:"dom"` and `mode:"dispatch"` are mainly useful when the target is occluded by an overlay or popup.
-- `mode` and `humanize` are separate knobs: `mode` changes how the click is delivered to the target, while `humanize:true` keeps the normal pointer-click path but makes it slower and more human-like.
+- Treat `mode` as a broad, low-level escape hatch for click delivery. Occlusion bypass is the common case, but it can also help with pages that need a non-default click path.
+- `mode` and `humanize:true` are mutually exclusive.
- To opt a click into the slower humanized path for a page that needs it, pass `humanize:true` in the action JSON or set `instanceDefaults.humanize:true`.
## Related Pages
diff --git a/docs/reference/mcp-tools.md b/docs/reference/mcp-tools.md
index 0dbc0529..21bdd24e 100644
--- a/docs/reference/mcp-tools.md
+++ b/docs/reference/mcp-tools.md
@@ -35,7 +35,7 @@ All element-action tools accept the unified `selector` and the legacy aliases `r
| Tool | Key Parameters | Notes |
| --- | --- | --- |
-| `pinchtab_click` | `selector`, `ref`, `query`, `tabId`, `x`, `y`, `nodeId`, `dialogAction`, `dialogText`, `waitNav`, `mode`, `snap` | Click element by selector or coordinate; `mode` accepts `dom` or `dispatch` to bypass occlusion; `dialogAction` handles a dialog opened by the click; `waitNav=true` waits for navigation; `snap=true` returns a snapshot |
+| `pinchtab_click` | `selector`, `ref`, `query`, `tabId`, `x`, `y`, `nodeId`, `dialogAction`, `dialogText`, `waitNav`, `mode`, `snap` | Click element by selector or coordinate; `mode` accepts `dom` or `dispatch` as a broad low-level escape hatch for click delivery; `mode` and `humanize` are mutually exclusive; `dialogAction` handles a dialog opened by the click; `waitNav=true` waits for navigation; `snap=true` returns a snapshot |
| `pinchtab_type` | `selector`, `ref`, `query`, `text` required, `tabId` | Sends key events at the targeted input |
| `pinchtab_press` | `key` required, `tabId` | Press a key such as `Enter` |
| `pinchtab_hover` | `selector`, `ref`, `query`, `tabId`, `x`, `y`, `nodeId` | Hover an element or coordinate |
diff --git a/internal/bridge/action_request.go b/internal/bridge/action_request.go
index bf5c11fa..fdbbc3b5 100644
--- a/internal/bridge/action_request.go
+++ b/internal/bridge/action_request.go
@@ -5,6 +5,7 @@ import (
"encoding/json"
"fmt"
"log/slog"
+ "strings"
)
// ActionFunc is the type for action handlers.
@@ -147,6 +148,9 @@ func hasJSONKey(raw map[string]json.RawMessage, key string) bool {
func (b *Bridge) ExecuteAction(ctx context.Context, kind string, req ActionRequest) (map[string]any, error) {
kind = CanonicalActionKind(kind)
req.Kind = CanonicalActionKind(req.Kind)
+ if kind == ActionClick && req.Humanize != nil && *req.Humanize && strings.TrimSpace(req.Mode) != "" {
+ return nil, fmt.Errorf("mode and humanize are mutually exclusive")
+ }
fn, ok := b.Actions[kind]
if !ok {
return nil, fmt.Errorf("unknown action: %s", kind)
diff --git a/internal/bridge/actions_test.go b/internal/bridge/actions_test.go
index 0f13f8cf..64cea3c3 100644
--- a/internal/bridge/actions_test.go
+++ b/internal/bridge/actions_test.go
@@ -350,6 +350,22 @@ func TestRemovedHumanActionKindsAreUnknown(t *testing.T) {
}
}
+func TestExecuteAction_ClickRejectsModeAndHumanizeTogether(t *testing.T) {
+ b := New(context.TODO(), nil, &config.RuntimeConfig{})
+ _, err := b.ExecuteAction(context.Background(), ActionClick, ActionRequest{
+ Kind: ActionClick,
+ Ref: "e5",
+ Mode: "dom",
+ Humanize: boolPtr(true),
+ })
+ if err == nil {
+ t.Fatal("expected error when mode and humanize are both set")
+ }
+ if !strings.Contains(err.Error(), "mutually exclusive") {
+ t.Fatalf("expected mutually exclusive error, got: %v", err)
+ }
+}
+
func TestClickAction_HumanizeOptInUsesHumanizedPath(t *testing.T) {
raw := New(context.TODO(), nil, &config.RuntimeConfig{Humanize: true})
ctx, cancel := context.WithCancel(context.Background())
diff --git a/internal/cli/actions/actions_element.go b/internal/cli/actions/actions_element.go
index 4a2d99be..ddd1b7ee 100644
--- a/internal/cli/actions/actions_element.go
+++ b/internal/cli/actions/actions_element.go
@@ -46,8 +46,14 @@ func Action(client *http.Client, base, token, kind, selectorArg string, cmd *cob
if waitNav {
body["waitNav"] = true
}
- if v, _ := cmd.Flags().GetString("mode"); v != "" {
- body["mode"] = v
+ mode, _ := cmd.Flags().GetString("mode")
+ if mode != "" {
+ body["mode"] = mode
+ }
+ if mode != "" && cmd.Flags().Changed("humanize") {
+ if humanize, _ := cmd.Flags().GetBool("humanize"); humanize {
+ cli.Fatal("Error: mode and humanize are mutually exclusive")
+ }
}
// --dismiss-banners only fires when --wait-nav is set; without nav,
// banners haven't changed and the dismissal pass would be wasted.
diff --git a/internal/mcp/handlers_interaction.go b/internal/mcp/handlers_interaction.go
index 90ccce96..f3532e79 100644
--- a/internal/mcp/handlers_interaction.go
+++ b/internal/mcp/handlers_interaction.go
@@ -59,6 +59,9 @@ func handleAction(c *Client, kind string) func(context.Context, mcp.CallToolRequ
if mode != "dom" && mode != "dispatch" {
return mcp.NewToolResultError("mode must be 'dom' or 'dispatch'"), nil
}
+ if humanize, ok := optBool(r, "humanize"); ok && humanize {
+ return mcp.NewToolResultError("mode and humanize are mutually exclusive"), nil
+ }
payload["mode"] = mode
}
dialogAction := strings.ToLower(firstNonEmptyString(r, "dialogAction", "onDialog"))
diff --git a/internal/mcp/handlers_interaction_test.go b/internal/mcp/handlers_interaction_test.go
index 65566cdb..14052b61 100644
--- a/internal/mcp/handlers_interaction_test.go
+++ b/internal/mcp/handlers_interaction_test.go
@@ -63,6 +63,20 @@ func TestHandleClickModeRejectsInvalidValue(t *testing.T) {
}
}
+func TestHandleClickRejectsModeAndHumanizeTogether(t *testing.T) {
+ srv := mockPinchTab()
+ defer srv.Close()
+
+ r := callTool(t, "pinchtab_click", map[string]any{
+ "ref": "e5",
+ "mode": "dom",
+ "humanize": true,
+ }, srv)
+ if !r.IsError {
+ t.Fatal("expected error when mode and humanize are both set")
+ }
+}
+
func TestHandleClickMissingRef(t *testing.T) {
srv := mockPinchTab()
defer srv.Close()
diff --git a/skills/pinchtab/SKILL.md b/skills/pinchtab/SKILL.md
index 02d310f6..0d716875 100644
--- a/skills/pinchtab/SKILL.md
+++ b/skills/pinchtab/SKILL.md
@@ -31,8 +31,8 @@ CLI-first browser skill. Use `pinchtab` commands.
2. Navigate: `pinchtab nav <url> --snap` — auto-starts the local server if needed, then returns tab ID + interactive snapshot in one call.
3. Interact: `pinchtab click <ref> --snap-diff` — returns OK + only changed elements (most token-efficient).
- Click behavior: omit `--mode` for the normal click path, use `--mode dom`, or use `--mode dispatch`.
- - Occlusion workaround: `pinchtab click <ref> --mode dom` or `pinchtab click <ref> --mode dispatch`
- - `--humanize` is separate: it keeps the normal pointer-click path, but makes it slower and more human-like.
+ - Treat `--mode` as a broad, low-level escape hatch. Occlusion workaround is the common case: `pinchtab click <ref> --mode dom` or `pinchtab click <ref> --mode dispatch`
+ - `--mode` and `--humanize` are mutually exclusive.
4. For read-only observation: `pinchtab text` when you won't act on refs.
**Key optimization**: Use `--snap-diff` on `click`, `fill`, `select`, `back`, `forward`, `reload` to get only added/changed/removed elements — most token-efficient for multi-step flows. Use `--snap` when you need the full snapshot (e.g., first navigation, or after major page changes). Use `--text` when you need prose content for verification (skips snap, returns page text directly).
@@ -196,8 +196,8 @@ Rules:
- **Prefer `--snap-diff`** with `click`, `fill`, `select`, `back`, `forward`, `reload` — returns `OK` + only changed elements. Use `--snap` when you need the full snapshot (first nav, major page change).
- Prefer `fill` for form entry; `type` only when the site depends on keystroke events.
- Click behavior: omit `--mode` for the normal click path, use `click --mode dom` for `element.click()`, or `click --mode dispatch` for synthetic click events.
-- `click --mode dom` and `click --mode dispatch` are mainly for bypassing occlusion.
-- `click --humanize` is different from `--mode`: it still uses pointer input, just with slower human-like motion/timing.
+- Treat `click --mode dom` and `click --mode dispatch` as broad low-level escape hatches; bypassing occlusion is the common case.
+- `click --mode ...` and `click --humanize` are mutually exclusive.
- `click --wait-nav` when a click navigates. May return `{"success":true}` or `Error 409: unexpected page navigation` — treat 409 as success and verify with fresh `snap`/`text`.
- `--dismiss-banners` on `nav`/`back`/`forward`/`reload` (and on `click --wait-nav`) runs a best-effort pass that clicks a visible Accept all / Got it / OK / Close / Dismiss button, or removes obvious cookie/consent/dialog/overlay containers. Use when a fresh page-load shows a modal that blocks interaction (typical symptom: `Error 500: action click: element is occluded`). Heuristic — can misfire on pages that label legitimate UI as `overlay` or `modal`; not a substitute for an explicit selector when one is known.
- Use low-level `mouse` only for drag handles, canvas widgets, or exact pointer sequences.
diff --git a/skills/pinchtab/references/api.md b/skills/pinchtab/references/api.md
index 2cff0844..50404b42 100644
--- a/skills/pinchtab/references/api.md
+++ b/skills/pinchtab/references/api.md
@@ -154,8 +154,8 @@ curl -X POST /action -H 'Content-Type: application/json' \
Notes:
- click behavior works like this: omit `mode` for the normal click path, use `mode:"dom"` for `element.click()`, or `mode:"dispatch"` for synthetic click events
-- `mode:"dom"` and `mode:"dispatch"` are mainly for bypassing occlusion
-- `mode` is separate from `humanize:true`, which keeps the normal pointer path but makes it slower and more human-like
+- treat `mode` as a broad low-level escape hatch; bypassing occlusion is the common case
+- `mode` and `humanize:true` are mutually exclusive
- selector-based click and double-click paths resolve through backend node IDs before dispatching pointer events
- low-level pointer actions accept `ref`, `selector`, `nodeId`, or `x`/`y`
- `mouse-down` and `mouse-up` accept `button` with `left`, `right`, or `middle`
diff --git a/skills/pinchtab/references/mcp.md b/skills/pinchtab/references/mcp.md
index 88690e6b..46e8ae53 100644
--- a/skills/pinchtab/references/mcp.md
+++ b/skills/pinchtab/references/mcp.md
@@ -59,7 +59,7 @@ All tool names are prefixed with `pinchtab_`.
### Interaction
| Tool | Description |
|------|-------------|
-| `pinchtab_click` | Click element by selector. Required: `selector` or legacy `ref`. Optional: `waitNav`, `mode` (`dom` or `dispatch`), `tabId`. |
+| `pinchtab_click` | Click element by selector. Required: `selector` or legacy `ref`. Optional: `waitNav`, `mode` (`dom` or `dispatch` as a broad low-level escape hatch), `tabId`. `mode` and `humanize` are mutually exclusive. |
| `pinchtab_type` | Type text keystroke-by-keystroke. Required: `selector` or legacy `ref`, plus `text`. Optional: `tabId`. |
| `pinchtab_fill` | Fill input via JS dispatch. Required: `selector` or legacy `ref`, plus `value`. Optional: `tabId`. |
| `pinchtab_press` | Press a named key (`Enter`, `Tab`, `Escape`, etc.). Required: `key`. Optional: `tabId`. |