Skip to content

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

fix: wire click mode through cli and mcp

Bosch036fb9782e5b
diff --git a/cmd/pinchtab/cmd_cli_register.go b/cmd/pinchtab/cmd_cli_register.go
index 3fa07957..e37c980a 100644
--- a/cmd/pinchtab/cmd_cli_register.go
+++ b/cmd/pinchtab/cmd_cli_register.go
@@ -185,6 +185,7 @@ 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().String("mode", "", "Click delivery mode override: dom | dispatch")
clickCmd.Flags().Bool("humanize", false, "Use humanized bezier+jitter input path (overrides instance config)")
dblclickCmd.Flags().String("css", "", "CSS selector instead of ref")
diff --git a/docs/reference/mcp-tools.md b/docs/reference/mcp-tools.md
index e1b0c3af..0dbc0529 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`, `snap` | Click element by selector or coordinate; `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` to bypass occlusion; `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/mcp/handlers_interaction.go b/internal/mcp/handlers_interaction.go
index 2621c2b0..90ccce96 100644
--- a/internal/mcp/handlers_interaction.go
+++ b/internal/mcp/handlers_interaction.go
@@ -55,6 +55,12 @@ func handleAction(c *Client, kind string) func(context.Context, mcp.CallToolRequ
if waitNav, ok := optBool(r, "waitNav"); ok && waitNav {
payload["waitNav"] = true
}
+ if mode := strings.ToLower(strings.TrimSpace(optTrimmedString(r, "mode"))); mode != "" {
+ if mode != "dom" && mode != "dispatch" {
+ return mcp.NewToolResultError("mode must be 'dom' or 'dispatch'"), nil
+ }
+ payload["mode"] = mode
+ }
dialogAction := strings.ToLower(firstNonEmptyString(r, "dialogAction", "onDialog"))
if dialogAction != "" {
if dialogAction != "accept" && dialogAction != "dismiss" {
diff --git a/internal/mcp/handlers_interaction_test.go b/internal/mcp/handlers_interaction_test.go
index 0dbae3b8..65566cdb 100644
--- a/internal/mcp/handlers_interaction_test.go
+++ b/internal/mcp/handlers_interaction_test.go
@@ -34,6 +34,35 @@ func TestHandleClickWaitNav(t *testing.T) {
}
}
+func TestHandleClickMode(t *testing.T) {
+ srv := mockPinchTab()
+ defer srv.Close()
+
+ r := callTool(t, "pinchtab_click", map[string]any{
+ "ref": "e5",
+ "mode": "dispatch",
+ }, srv)
+
+ resp := resultJSON(t, r)
+ body, _ := resp["body"].(map[string]any)
+ if got, _ := body["mode"].(string); got != "dispatch" {
+ t.Fatalf("mode = %q, want dispatch", got)
+ }
+}
+
+func TestHandleClickModeRejectsInvalidValue(t *testing.T) {
+ srv := mockPinchTab()
+ defer srv.Close()
+
+ r := callTool(t, "pinchtab_click", map[string]any{
+ "ref": "e5",
+ "mode": "raw",
+ }, srv)
+ if !r.IsError {
+ t.Fatal("expected error for invalid mode")
+ }
+}
+
func TestHandleClickMissingRef(t *testing.T) {
srv := mockPinchTab()
defer srv.Close()
diff --git a/internal/mcp/tools.go b/internal/mcp/tools.go
index 83eec314..4a477844 100644
--- a/internal/mcp/tools.go
+++ b/internal/mcp/tools.go
@@ -58,6 +58,7 @@ func allTools() []mcp.Tool {
mcp.WithNumber("y", mcp.Description("Optional Y coordinate for coordinate click")),
mcp.WithNumber("nodeId", mcp.Description("Optional backend node ID to target directly")),
mcp.WithBoolean("waitNav", mcp.Description("Wait for navigation after the click when the element triggers a page change")),
+ mcp.WithString("mode", mcp.Description("Optional click delivery override: 'dom' for element.click() or 'dispatch' for synthetic click events on the target")),
mcp.WithBoolean("snap", mcp.Description("Return interactive compact snapshot after click (saves a round-trip)")),
mcp.WithString("tabId", mcp.Description("Target tab ID")),
),
diff --git a/skills/pinchtab/references/mcp.md b/skills/pinchtab/references/mcp.md
index 2cb902ad..88690e6b 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`, `tabId`. |
+| `pinchtab_click` | Click element by selector. Required: `selector` or legacy `ref`. Optional: `waitNav`, `mode` (`dom` or `dispatch`), `tabId`. |
| `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`. |
diff --git a/tests/e2e/scenarios/cli/actions-extended.sh b/tests/e2e/scenarios/cli/actions-extended.sh
index f375e2a3..deb3b5ba 100644
--- a/tests/e2e/scenarios/cli/actions-extended.sh
+++ b/tests/e2e/scenarios/cli/actions-extended.sh
@@ -49,6 +49,38 @@ pt_ok click --css "button[type=submit]"
end_test
+# ─────────────────────────────────────────────────────────────────
+start_test "pinchtab click --mode dom|dispatch"
+
+pt_ok nav "${FIXTURES_URL}/occluded-click.html"
+pt_ok snap --interactive --compact=false
+
+TARGET_REF=$(find_ref_by_role_and_name "button" "Proceed" "$PT_OUT")
+if assert_ref_found "$TARGET_REF" "occluded target ref"; then
+ pt click "$TARGET_REF"
+ assert_exit_code 1 "plain cli click fails on occlusion"
+ if printf '%s\n%s\n' "$PT_OUT" "$PT_ERR" | grep -q "element is occluded"; then
+ pass_assert "plain cli click surfaces occlusion"
+ else
+ fail_assert "plain cli click surfaces occlusion"
+ echo -e " ${RED}stdout: $PT_OUT${NC}"
+ echo -e " ${RED}stderr: $PT_ERR${NC}"
+ fi
+
+ pt_ok click "$TARGET_REF" --mode dom
+ assert_output_contains "OK" "dom mode click succeeds"
+ pt_ok eval "JSON.stringify(window.occludedClickState)"
+ assert_json_jq "$PT_OUT" '.clicked == true and .clicks == 1' "dom mode updated click state" "dom mode did not trigger click"
+
+ pt_ok eval "window.occludedClickState = { clicked: false, clicks: 0, lastClientX: null, lastClientY: null }; JSON.stringify(window.occludedClickState)"
+ pt_ok click "$TARGET_REF" --mode dispatch
+ assert_output_contains "OK" "dispatch mode click succeeds"
+ pt_ok eval "JSON.stringify(window.occludedClickState)"
+ assert_json_jq "$PT_OUT" '.clicked == true and .clicks == 1' "dispatch mode updated click state" "dispatch mode did not trigger click"
+fi
+
+end_test
+
# ─────────────────────────────────────────────────────────────────
start_test "pinchtab hover <ref>"