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.mdindex 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 Pagesdiff --git a/docs/reference/mcp-tools.md b/docs/reference/mcp-tools.mdindex 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.goindex 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.goindex 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.goindex 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 *cobif 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.goindex 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.CallToolRequif 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.goindex 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.mdindex 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.mdindex 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.mdindex 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`. |