Skip to content

armgit / cua

Public Imported from GitHub
0

Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.

fix(cua-driver): background browser clicks reach pointer-driven rows (#5110)

Francesco Bonaccia7c4a0ea5e19
diff --git a/docs/content/docs/cua-driver/concepts/platform-support.mdx b/docs/content/docs/cua-driver/concepts/platform-support.mdx
index 5e7024e4f1..0397ab8ce5 100644
--- a/docs/content/docs/cua-driver/concepts/platform-support.mdx
+++ b/docs/content/docs/cua-driver/concepts/platform-support.mdx
@@ -80,7 +80,8 @@ Browser mutation always starts from an exact native `(pid, window_id)` binding.
| Surface | Proven | Limit |
| --- | --- | --- |
| Chrome and Edge on Windows | Snapshot, navigate, type, trusted background click, DOM pointer actions, dialogs, file assignment, downloads, frames, multi-tab | Elevated-integrity targets refuse. |
-| Chrome on macOS; Chrome and Edge on Linux X11 | The same, except trusted pointer input | Trusted pointer returns `browser_input_trust_unavailable`; Linux dialogs need foreground. |
+| Chrome on macOS | The same | Trusted pointer input stays in the background, including inactive tabs. |
+| Chrome and Edge on Linux X11 | The same, except trusted pointer input | Trusted pointer returns `browser_input_trust_unavailable`; dialogs need foreground. |
| Chrome on Sway | Exact binding when compositor identity and geometry agree | Generic GNOME or KDE Wayland is read-only. |
| Electron (Windows, macOS, X11, Sway) | Typed mutation while one native window maps to one page | A second page or window invalidates the route. |
| Brave, Vivaldi, Opera, Arc | Detected, not release-accepted | Use at your own risk. |
diff --git a/docs/content/docs/cua-driver/guides/browsers.mdx b/docs/content/docs/cua-driver/guides/browsers.mdx
index f464d11fd9..47b9826e9f 100644
--- a/docs/content/docs/cua-driver/guides/browsers.mdx
+++ b/docs/content/docs/cua-driver/guides/browsers.mdx
@@ -64,7 +64,7 @@ end_session({"session": "research-1"})
| Tool | Notes |
| --- | --- |
-| `browser_click` | Trusted CDP input by default. Works fully in the background for Chrome and Edge on Windows; macOS and Linux return `browser_input_trust_unavailable` because the browser would activate. Pass `input_route: "dom_event"` for a synthetic DOM click that stays in the background but returns `effect: "unverifiable"`. |
+| `browser_click` | Trusted CDP input by default. Works fully in the background for Chrome and Edge on Windows and Chrome on macOS, including inactive tabs; Linux returns `browser_input_trust_unavailable` because the browser would activate. Pass `input_route: "dom_event"` for a synthetic pointer, mouse and click sequence that stays in the background but returns `effect: "unverifiable"`. |
| `browser_type` | `insert_text` by default; `mode: "keystrokes"` for per-key events; `replace: true` to overwrite. |
| `browser_pointer` | `hover`, `right_click`, `double_click`, `scroll`, `drag` (with `destination_ref` in the same frame). |
| `browser_dialog` | `inspect`, then `accept` or `dismiss` the returned `dialog_id`. Linux needs `delivery_mode: "foreground"`. |
diff --git a/docs/content/docs/cua-driver/reference/mcp-tools/browser-input.mdx b/docs/content/docs/cua-driver/reference/mcp-tools/browser-input.mdx
index a2a66ca34c..66e4039dfe 100644
--- a/docs/content/docs/cua-driver/reference/mcp-tools/browser-input.mdx
+++ b/docs/content/docs/cua-driver/reference/mcp-tools/browser-input.mdx
@@ -23,7 +23,7 @@ Served by `cua-driver mcp`; see [MCP tools](/cua-driver/reference/mcp-tools) for
## `browser_click`
-Click a page element (by ref) or viewport coordinates in an exactly-bound tab. Default route is trusted hardware-like input (Input.dispatchMouseEvent), and refuses where that route cannot preserve standalone-browser background posture unless delivery_mode="foreground" accepts that the browser window may activate (including Linux Chromium and macOS Chromium configurations whose trusted route cannot stay in the background; for example a browser inside a sandbox). input_route="dom_event" (synthetic el.click(), ref required) is used only when explicitly requested; it proves dispatch, not control activation, because trust-gated controls may ignore synthetic events. Refused for heuristic bindings.
+Click a page element (by ref) or viewport coordinates in an exactly-bound tab. Default route is trusted hardware-like input (Input.dispatchMouseEvent), and refuses where that route cannot preserve standalone-browser background posture unless delivery_mode="foreground" accepts that the browser window may activate (including Linux Chromium configurations whose trusted route cannot stay in the background; for example a browser inside a sandbox). input_route="dom_event" (synthetic pointer and mouse down/up/click sequence at the element's center, ref required) is used only when explicitly requested; it proves dispatch, not control activation, because trust-gated controls may ignore synthetic events. Refused for heuristic bindings.
Effect: mutating. Platforms: macOS, Linux, Windows.
diff --git a/libs/cua-driver/rust/Skills/cua-driver/BROWSER.md b/libs/cua-driver/rust/Skills/cua-driver/BROWSER.md
index a2980d73c2..dce2cab2e6 100644
--- a/libs/cua-driver/rust/Skills/cua-driver/BROWSER.md
+++ b/libs/cua-driver/rust/Skills/cua-driver/BROWSER.md
@@ -370,11 +370,12 @@ browser_click
Before dispatch, the driver refreshes the element box and hit-tests the point.
It refuses stale, covered, or ambiguous targets.
-Standalone Chromium on macOS and Linux can activate its native window when
-trusted CDP pointer input is used. CUA Driver detects that limitation and
-returns `browser_input_trust_unavailable` before dispatch instead of claiming
-background delivery. Windows Chrome and Edge have validated trusted
-background delivery.
+Standalone Chromium on Linux can activate its native window when trusted CDP
+pointer input is used. CUA Driver detects that limitation and returns
+`browser_input_trust_unavailable` before dispatch instead of claiming
+background delivery. Chrome and Edge on Windows, and Chrome on macOS, deliver
+trusted input in the background, including to an inactive (hidden) tab,
+without activating or raising the browser window.
When the application semantics allow a synthetic JavaScript click, request it
explicitly with a current ref:
@@ -385,8 +386,11 @@ browser_click
"input_route":"dom_event","session":"browser-run-1"}'
```
-`dom_event` calls the page element's click behavior without pretending that a
-trusted pointer event occurred. It requires a ref and is the full-background
+`dom_event` replays a primary-button click as synthetic DOM events at the
+element's center: pointer and mouse over, move, down, up, then `click`. Apps
+that open rows or menus from pointer or mouse down/up, as many React tables
+do, respond to it; it does not pretend that a trusted pointer event occurred.
+Controls that check `event.isTrusted` still need the trusted route. It requires a ref and is the full-background
alternative where supported. Dispatch is not proof that the control activated:
trust-gated controls can ignore synthetic events, so refresh page state and
verify the expected postcondition. Never silently change trust class or
diff --git a/libs/cua-driver/rust/Skills/cua-driver/MACOS.md b/libs/cua-driver/rust/Skills/cua-driver/MACOS.md
index 04ce019572..888a8c6be2 100644
--- a/libs/cua-driver/rust/Skills/cua-driver/MACOS.md
+++ b/libs/cua-driver/rust/Skills/cua-driver/MACOS.md
@@ -585,11 +585,11 @@ window, and PID-routes its bounded checkbox-pixel fallback. The same control's
state must verify after mutation; unsupported appearance, scale, zoom,
window-size, or toolbar geometry refuses without a click.
-Standalone Chromium activates its window when CDP's trusted pointer route is
-used on macOS. The driver therefore returns
-`browser_input_trust_unavailable` before dispatch rather than falsely claiming
-background delivery. Use `input_route:"dom_event"` only when synthetic click
-semantics are acceptable. Embedded Electron has a separately bounded route;
+CDP's trusted pointer route (the `browser_click` and `browser_pointer`
+default) stays in the background on macOS Chrome: it delivers trusted events
+to the bound tab, even an inactive one, without activating or raising the
+browser window. Use `input_route:"dom_event"` only when synthetic events are
+acceptable; controls that check `event.isTrusted` ignore it. Embedded Electron has a separately bounded route;
do not infer that route for arbitrary WKWebView or Tauri hosts.
For a declared session, typed browser click, type, and pointer mutations animate
diff --git a/libs/cua-driver/rust/crates/cua-driver-core/src/browser/tools.rs b/libs/cua-driver/rust/crates/cua-driver-core/src/browser/tools.rs
index 4aed3981f4..ee333e2915 100644
--- a/libs/cua-driver/rust/crates/cua-driver-core/src/browser/tools.rs
+++ b/libs/cua-driver/rust/crates/cua-driver-core/src/browser/tools.rs
@@ -952,10 +952,10 @@ impl BrowserClickTool {
(Input.dispatchMouseEvent), and refuses where that route cannot \
preserve standalone-browser background posture unless \
delivery_mode=\"foreground\" accepts that the browser window may \
- activate (including Linux Chromium and macOS Chromium configurations whose trusted route cannot stay in the background; \
+ activate (including Linux Chromium configurations whose trusted route cannot stay in the background; \
for example a browser inside a sandbox). \
- input_route=\"dom_event\" (synthetic \
- el.click(), ref required) is used only when explicitly requested; \
+ input_route=\"dom_event\" (synthetic pointer and mouse \
+ down/up/click sequence at the element's center, ref required) is used only when explicitly requested; \
it proves dispatch, not control activation, because trust-gated \
controls may ignore synthetic events. \
Refused for heuristic bindings."
@@ -1215,7 +1215,7 @@ impl Tool for BrowserClickTool {
"Runtime.callFunctionOn",
json!({
"objectId": object_id,
- "functionDeclaration": "function() { this.click(); }",
+ "functionDeclaration": DOM_EVENT_CLICK_SEQUENCE,
}),
)
.await
@@ -1394,6 +1394,47 @@ fn quad_center(box_model: &Value) -> Option<(f64, f64)> {
Some((xs.iter().sum::<f64>() / 4.0, ys.iter().sum::<f64>() / 4.0))
}
+/// Synthetic click for `input_route:"dom_event"`, evaluated ON the ref's node.
+///
+/// `HTMLElement.click()` fires only a bare `click` with no coordinates, so
+/// apps that open rows or menus from `pointerdown`/`mousedown`/`pointerup`
+/// (common in React tables and grids) ignore it. This dispatches the sequence
+/// a real primary-button mouse click produces, at the element's center and on
+/// the hit-tested descendant there: hover, move, down, focus, up, click. Like
+/// a real click, `preventDefault()` on `pointerdown` suppresses the
+/// compatibility mouse events, and on `mousedown` suppresses the focus move.
+/// The events stay untrusted (`isTrusted === false`).
+const DOM_EVENT_CLICK_SEQUENCE: &str = "function() { \
+ const el = this; \
+ const doc = el.ownerDocument; \
+ const view = doc.defaultView; \
+ const r = el.getBoundingClientRect(); \
+ const x = r.left + r.width / 2, y = r.top + r.height / 2; \
+ const root = el.getRootNode(); \
+ const hit = ('elementFromPoint' in root) ? root.elementFromPoint(x, y) : null; \
+ const target = (hit && el.contains(hit)) ? hit : el; \
+ const sx = x + (view.screenX || 0), sy = y + (view.screenY || 0); \
+ const base = { bubbles: true, cancelable: true, composed: true, view, \
+ clientX: x, clientY: y, screenX: sx, screenY: sy, button: 0 }; \
+ const P = (type, buttons, extra) => target.dispatchEvent(new view.PointerEvent(type, \
+ { ...base, buttons, pointerId: 1, pointerType: 'mouse', isPrimary: true, \
+ width: 1, height: 1, pressure: buttons ? 0.5 : 0, ...extra })); \
+ const M = (type, buttons, extra) => target.dispatchEvent(new view.MouseEvent(type, \
+ { ...base, buttons, detail: 0, ...extra })); \
+ P('pointerover', 0); P('pointerenter', 0, { bubbles: false, cancelable: false }); \
+ M('mouseover', 0); M('mouseenter', 0, { bubbles: false, cancelable: false }); \
+ P('pointermove', 0); M('mousemove', 0); \
+ const compat = P('pointerdown', 1); \
+ if (compat && M('mousedown', 1, { detail: 1 })) { \
+ const focusable = target.closest('a[href],button,input,select,textarea,summary,[tabindex],[contenteditable=\"\"],[contenteditable=\"true\"]'); \
+ if (focusable && typeof focusable.focus === 'function') focusable.focus({ preventScroll: true }); \
+ } \
+ P('pointerup', 0); \
+ if (compat) M('mouseup', 0, { detail: 1 }); \
+ M('click', 0, { detail: 1 }); \
+ return true; \
+}";
+
// ── browser_type ─────────────────────────────────────────────────────────────
/// Editability check evaluated ON the ref's node (`this`), so focus is
diff --git a/libs/cua-driver/rust/crates/cua-driver-core/src/browser/v2_tests.rs b/libs/cua-driver/rust/crates/cua-driver-core/src/browser/v2_tests.rs
index 15c8c3085d..34b8f8ffba 100644
--- a/libs/cua-driver/rust/crates/cua-driver-core/src/browser/v2_tests.rs
+++ b/libs/cua-driver/rust/crates/cua-driver-core/src/browser/v2_tests.rs
@@ -2680,7 +2680,38 @@ async fn trusted_click_refuses_when_standalone_background_posture_is_unavailable
"{public}"
);
assert!(public.get("status").is_none(), "{public}");
- assert!(!recorded_calls(&f, "Runtime.callFunctionOn").is_empty());
+ let dispatches = recorded_calls(&f, "Runtime.callFunctionOn");
+ let click_sequence = dispatches
+ .iter()
+ .filter_map(|(_, params)| params["functionDeclaration"].as_str())
+ .find(|declaration| declaration.contains("'pointerdown'"))
+ .expect("dom_event click dispatches a pointer sequence, not a bare click()");
+ // Apps that open rows from pointer/mouse down+up ignore a bare click(),
+ // so the synthetic route must replay the whole primary-button sequence
+ // at the element's center, in order.
+ let order = [
+ "'pointermove'",
+ "'pointerdown'",
+ "'mousedown'",
+ "'pointerup'",
+ "'mouseup'",
+ "'click'",
+ ];
+ let positions: Vec<usize> = order
+ .iter()
+ .map(|event| {
+ click_sequence
+ .find(event)
+ .unwrap_or_else(|| panic!("missing {event}"))
+ })
+ .collect();
+ assert!(
+ positions.windows(2).all(|w| w[0] < w[1]),
+ "{click_sequence}"
+ );
+ assert!(click_sequence.contains("clientX: x"), "{click_sequence}");
+ assert!(!click_sequence.contains("this.click()"), "{click_sequence}");
+ assert!(recorded_calls(&f, "Input.dispatchMouseEvent").is_empty());
assert!(recorded_calls(&f, "Page.bringToFront").is_empty());
assert!(recorded_calls(&f, "Target.activateTarget").is_empty());
}
diff --git a/libs/cua-driver/rust/crates/cua-driver-e2e/tests/standalone_browser_behavior_test.rs b/libs/cua-driver/rust/crates/cua-driver-e2e/tests/standalone_browser_behavior_test.rs
index f33d10d60b..04ae655746 100644
--- a/libs/cua-driver/rust/crates/cua-driver-e2e/tests/standalone_browser_behavior_test.rs
+++ b/libs/cua-driver/rust/crates/cua-driver-e2e/tests/standalone_browser_behavior_test.rs
@@ -2432,7 +2432,7 @@ fn run_trusted_click(spec: &BrowserSpec) {
std::env::consts::OS,
spec.name
);
- let case = if cfg!(any(target_os = "linux", target_os = "macos")) {
+ let case = if cfg!(target_os = "linux") {
refusal_case(
&spec.name,
"trusted_click",
@@ -2459,7 +2459,7 @@ fn run_trusted_click(spec: &BrowserSpec) {
"session": session,
}),
);
- if cfg!(any(target_os = "linux", target_os = "macos")) {
+ if cfg!(target_os = "linux") {
assert_eq!(click.action_effect(), Some("refused"), "{}", click.raw);
assert!(
click.text().contains("browser_input_trust_unavailable"),
@@ -3536,7 +3536,7 @@ fn run_multi_tab(spec: &BrowserSpec) {
"session": session,
}),
);
- let trusted_clicks = if cfg!(target_os = "windows") {
+ let trusted_clicks = if !cfg!(target_os = "linux") {
assert_eq!(
trusted.action_effect(),
Some("unverifiable"),
diff --git a/libs/cua-driver/rust/crates/cua-driver/tests/protocol_schema_test.rs b/libs/cua-driver/rust/crates/cua-driver/tests/protocol_schema_test.rs
index 8a0b00b9ca..a7633bb55a 100644
--- a/libs/cua-driver/rust/crates/cua-driver/tests/protocol_schema_test.rs
+++ b/libs/cua-driver/rust/crates/cua-driver/tests/protocol_schema_test.rs
@@ -276,11 +276,10 @@ fn assert_tools_list_schema_shape(mut d: RawDriver) {
.find(|tool| tool["name"] == "browser_click")
.expect("browser_click not found in tools/list");
assert!(
- browser_click["description"]
- .as_str()
- .is_some_and(|description| description
- .contains("including Linux Chromium and macOS Chromium configurations")),
- "browser_click description should name macOS and Linux: {}",
+ browser_click["description"].as_str().is_some_and(
+ |description| description.contains("including Linux Chromium configurations")
+ ),
+ "browser_click description should name Linux: {}",
browser_click["description"]
);
let schema_tools: BTreeSet<&str> = tools
diff --git a/libs/cua-driver/rust/crates/platform-macos/src/browser/platform.rs b/libs/cua-driver/rust/crates/platform-macos/src/browser/platform.rs
index f56ce6973e..5a97ce0bd6 100644
--- a/libs/cua-driver/rust/crates/platform-macos/src/browser/platform.rs
+++ b/libs/cua-driver/rust/crates/platform-macos/src/browser/platform.rs
@@ -886,7 +886,15 @@ impl BrowserPlatform for MacOsBrowserPlatform {
}
fn standalone_trusted_input_background_limitation(&self) -> Option<&'static str> {
- Some("Chromium's trusted CDP Input route activates its standalone browser window on macOS")
+ // Measured on Chrome 155 with another app frontmost: CDP
+ // Input.dispatchMouseEvent (with and without focus emulation) into a
+ // hidden background tab, and into the active tab of a window behind
+ // another app, delivered trusted events (isTrusted=true) without
+ // changing the frontmost app or raising the browser window, including
+ // clicks that focus inputs, buttons, links and selects. The
+ // background click route never calls Page.bringToFront or
+ // Target.activateTarget.
+ None
}
fn existing_profile_attach_background_limitation(&self) -> Option<&'static str> {
diff --git a/libs/cua/skills/cua-driver/BROWSER.md b/libs/cua/skills/cua-driver/BROWSER.md
index 7ddd90977d..af3670ceae 100644
--- a/libs/cua/skills/cua-driver/BROWSER.md
+++ b/libs/cua/skills/cua-driver/BROWSER.md
@@ -364,11 +364,12 @@ browser_click
Before dispatch, the driver refreshes the element box and hit-tests the point.
It refuses stale, covered, or ambiguous targets.
-Standalone Chromium on macOS and Linux can activate its native window when
-trusted CDP pointer input is used. CUA Driver detects that limitation and
-returns `browser_input_trust_unavailable` before dispatch instead of claiming
-background delivery. Windows Chrome and Edge have validated trusted
-background delivery.
+Standalone Chromium on Linux can activate its native window when trusted CDP
+pointer input is used. CUA Driver detects that limitation and returns
+`browser_input_trust_unavailable` before dispatch instead of claiming
+background delivery. Chrome and Edge on Windows, and Chrome on macOS, deliver
+trusted input in the background, including to an inactive (hidden) tab,
+without activating or raising the browser window.
When the application semantics allow a synthetic JavaScript click, request it
explicitly with a current ref:
@@ -379,8 +380,11 @@ browser_click
"input_route":"dom_event","session":"browser-run-1"}'
```
-`dom_event` calls the page element's click behavior without pretending that a
-trusted pointer event occurred. It requires a ref and is the full-background
+`dom_event` replays a primary-button click as synthetic DOM events at the
+element's center: pointer and mouse over, move, down, up, then `click`. Apps
+that open rows or menus from pointer or mouse down/up, as many React tables
+do, respond to it; it does not pretend that a trusted pointer event occurred.
+Controls that check `event.isTrusted` still need the trusted route. It requires a ref and is the full-background
alternative where supported. Dispatch is not proof that the control activated:
trust-gated controls can ignore synthetic events, so refresh page state and
verify the expected postcondition. Never silently change trust class or
diff --git a/libs/cua/skills/cua-driver/MACOS.md b/libs/cua/skills/cua-driver/MACOS.md
index 496cbe8c57..10b24ed403 100644
--- a/libs/cua/skills/cua-driver/MACOS.md
+++ b/libs/cua/skills/cua-driver/MACOS.md
@@ -479,11 +479,11 @@ window, and PID-routes its bounded checkbox-pixel fallback. The same control's
state must verify after mutation; unsupported appearance, scale, zoom,
window-size, or toolbar geometry refuses without a click.
-Standalone Chromium activates its window when CDP's trusted pointer route is
-used on macOS. The driver therefore returns
-`browser_input_trust_unavailable` before dispatch rather than falsely claiming
-background delivery. Use `input_route:"dom_event"` only when synthetic click
-semantics are acceptable. Embedded Electron has a separately bounded route;
+CDP's trusted pointer route (the `browser_click` and `browser_pointer`
+default) stays in the background on macOS Chrome: it delivers trusted events
+to the bound tab, even an inactive one, without activating or raising the
+browser window. Use `input_route:"dom_event"` only when synthetic events are
+acceptable; controls that check `event.isTrusted` ignore it. Embedded Electron has a separately bounded route;
do not infer that route for arbitrary WKWebView or Tauri hosts.
For a declared session, typed browser click, type, and pointer mutations animate
diff --git a/scripts/docs-generators/cli-specs/cua-driver-mcp-linux.json b/scripts/docs-generators/cli-specs/cua-driver-mcp-linux.json
index a5be6e6107..657428edad 100644
--- a/scripts/docs-generators/cli-specs/cua-driver-mcp-linux.json
+++ b/scripts/docs-generators/cli-specs/cua-driver-mcp-linux.json
@@ -2557,7 +2557,7 @@
"read_only": false
},
{
- "description": "Click a page element (by ref) or viewport coordinates in an exactly-bound tab. Default route is trusted hardware-like input (Input.dispatchMouseEvent), and refuses where that route cannot preserve standalone-browser background posture unless delivery_mode=\"foreground\" accepts that the browser window may activate (including Linux Chromium and macOS Chromium configurations whose trusted route cannot stay in the background; for example a browser inside a sandbox). input_route=\"dom_event\" (synthetic el.click(), ref required) is used only when explicitly requested; it proves dispatch, not control activation, because trust-gated controls may ignore synthetic events. Refused for heuristic bindings.",
+ "description": "Click a page element (by ref) or viewport coordinates in an exactly-bound tab. Default route is trusted hardware-like input (Input.dispatchMouseEvent), and refuses where that route cannot preserve standalone-browser background posture unless delivery_mode=\"foreground\" accepts that the browser window may activate (including Linux Chromium configurations whose trusted route cannot stay in the background; for example a browser inside a sandbox). input_route=\"dom_event\" (synthetic pointer and mouse down/up/click sequence at the element's center, ref required) is used only when explicitly requested; it proves dispatch, not control activation, because trust-gated controls may ignore synthetic events. Refused for heuristic bindings.",
"destructive": false,
"idempotent": false,
"input_schema": {
diff --git a/scripts/docs-generators/cli-specs/cua-driver-mcp-macos.json b/scripts/docs-generators/cli-specs/cua-driver-mcp-macos.json
index 755b65e64a..7acbb7af4f 100644
--- a/scripts/docs-generators/cli-specs/cua-driver-mcp-macos.json
+++ b/scripts/docs-generators/cli-specs/cua-driver-mcp-macos.json
@@ -2204,7 +2204,7 @@
"read_only": false
},
{
- "description": "Click a page element (by ref) or viewport coordinates in an exactly-bound tab. Default route is trusted hardware-like input (Input.dispatchMouseEvent), and refuses where that route cannot preserve standalone-browser background posture unless delivery_mode=\"foreground\" accepts that the browser window may activate (including Linux Chromium and macOS Chromium configurations whose trusted route cannot stay in the background; for example a browser inside a sandbox). input_route=\"dom_event\" (synthetic el.click(), ref required) is used only when explicitly requested; it proves dispatch, not control activation, because trust-gated controls may ignore synthetic events. Refused for heuristic bindings.",
+ "description": "Click a page element (by ref) or viewport coordinates in an exactly-bound tab. Default route is trusted hardware-like input (Input.dispatchMouseEvent), and refuses where that route cannot preserve standalone-browser background posture unless delivery_mode=\"foreground\" accepts that the browser window may activate (including Linux Chromium configurations whose trusted route cannot stay in the background; for example a browser inside a sandbox). input_route=\"dom_event\" (synthetic pointer and mouse down/up/click sequence at the element's center, ref required) is used only when explicitly requested; it proves dispatch, not control activation, because trust-gated controls may ignore synthetic events. Refused for heuristic bindings.",
"destructive": false,
"idempotent": false,
"input_schema": {
diff --git a/scripts/docs-generators/cli-specs/cua-driver-mcp-windows.json b/scripts/docs-generators/cli-specs/cua-driver-mcp-windows.json
index 989d2e8683..927cf82609 100644
--- a/scripts/docs-generators/cli-specs/cua-driver-mcp-windows.json
+++ b/scripts/docs-generators/cli-specs/cua-driver-mcp-windows.json
@@ -2252,7 +2252,7 @@
"read_only": false
},
{
- "description": "Click a page element (by ref) or viewport coordinates in an exactly-bound tab. Default route is trusted hardware-like input (Input.dispatchMouseEvent), and refuses where that route cannot preserve standalone-browser background posture unless delivery_mode=\"foreground\" accepts that the browser window may activate (including Linux Chromium and macOS Chromium configurations whose trusted route cannot stay in the background; for example a browser inside a sandbox). input_route=\"dom_event\" (synthetic el.click(), ref required) is used only when explicitly requested; it proves dispatch, not control activation, because trust-gated controls may ignore synthetic events. Refused for heuristic bindings.",
+ "description": "Click a page element (by ref) or viewport coordinates in an exactly-bound tab. Default route is trusted hardware-like input (Input.dispatchMouseEvent), and refuses where that route cannot preserve standalone-browser background posture unless delivery_mode=\"foreground\" accepts that the browser window may activate (including Linux Chromium configurations whose trusted route cannot stay in the background; for example a browser inside a sandbox). input_route=\"dom_event\" (synthetic pointer and mouse down/up/click sequence at the element's center, ref required) is used only when explicitly requested; it proves dispatch, not control activation, because trust-gated controls may ignore synthetic events. Refused for heuristic bindings.",
"destructive": false,
"idempotent": false,
"input_schema": {