From 4f2cd1fc42a7a288c0dcd23d6cb007267a2423ba Mon Sep 17 00:00:00 2001 From: Zane Chee Date: Wed, 1 Jul 2026 23:26:48 +0800 Subject: [PATCH 1/2] docs(cua-driver): update delivery_mode wording in comments --- .../cua-driver/tests/harness_winui3_test.rs | 2 +- .../crates/cua-driver/tests/harness_wpf_test.rs | 16 ++++++++-------- .../cua-driver/tests/modality_input_e2e_test.rs | 6 +++--- .../platform-macos/src/tools/bring_to_front.rs | 4 ++-- .../platform-windows/src/input/delivery.rs | 6 +++--- .../rust/crates/platform-windows/src/uia/mod.rs | 2 +- 6 files changed, 18 insertions(+), 18 deletions(-) diff --git a/libs/cua-driver/rust/crates/cua-driver/tests/harness_winui3_test.rs b/libs/cua-driver/rust/crates/cua-driver/tests/harness_winui3_test.rs index 63aad3f33a..4f2eec8999 100644 --- a/libs/cua-driver/rust/crates/cua-driver/tests/harness_winui3_test.rs +++ b/libs/cua-driver/rust/crates/cua-driver/tests/harness_winui3_test.rs @@ -178,7 +178,7 @@ where /// Regression guard for the click → TogglePattern dispatch fix. /// cua-driver `click` now tries Invoke → Toggle → SelectionItem → /// ExpandCollapse before falling through to PostMessage, so WinUI3 -/// CheckBox toggles correctly via UIA without needing dispatch:foreground. +/// CheckBox toggles correctly via UIA without needing delivery_mode:foreground. #[test] #[ignore] fn harness_winui3_checkbox_toggle() { diff --git a/libs/cua-driver/rust/crates/cua-driver/tests/harness_wpf_test.rs b/libs/cua-driver/rust/crates/cua-driver/tests/harness_wpf_test.rs index 9aa6f74e17..aad48908ec 100644 --- a/libs/cua-driver/rust/crates/cua-driver/tests/harness_wpf_test.rs +++ b/libs/cua-driver/rust/crates/cua-driver/tests/harness_wpf_test.rs @@ -26,7 +26,7 @@ //! sandbox runner unignores them explicitly via the `--ignored` arg. //! //! **Foreground-lock caveat:** a handful of these tests (`double_click`, -//! `right_click`, `type_text`) rely on `dispatch:"foreground"` to reach +//! `right_click`, `type_text`) rely on `delivery_mode:"foreground"` to reach //! WPF's input chain reliably. Windows' system-wide foreground-lock //! kicks in after ~30s with no real user input — once that happens, //! `SetForegroundWindow` is denied for non-UIAccess processes and the @@ -78,7 +78,7 @@ fn launch_harness(driver: &mut McpDriver) -> Option { // wait happens via polling in find_window. A 200ms-only // wait turned out to be too short for the harness to establish // foreground reliably under test-batch load, which caused - // SetForegroundWindow-needing tests (dispatch:foreground) to + // SetForegroundWindow-needing tests (delivery_mode:foreground) to // fail with a foreground-lock rejection. std::thread::sleep(Duration::from_millis(800)); Some(pid) @@ -192,7 +192,7 @@ fn harness_wpf_type_text() { // WPF's TextBox needs *keyboard focus* for WM_CHAR delivery — and // PostMessage(WM_LBUTTONDOWN) doesn't reliably transfer keyboard // focus (WPF's input system treats posted events differently from - // real ones). Use dispatch:"foreground" → SendInput synthesizes + // real ones). Use delivery_mode:"foreground" → SendInput synthesizes // an OS-level click that WPF treats identically to a user mouse, // landing actual keyboard focus on the TextBox. let _ = driver.call("bring_to_front", serde_json::json!({ @@ -279,7 +279,7 @@ fn harness_wpf_right_click() { let snap = snapshot(driver, pid, wid); let idx = ax::element_index_by_id(snap.text(), "border-click-target") .expect("border-click-target not in snapshot"); - // Same dispatch:foreground rationale as type_text — PostMessage + // Same delivery_mode:foreground rationale as type_text — PostMessage // WM_RBUTTONDOWN doesn't always reach WPF's MouseRightButtonDown // routed-event chain (intermittent in batch runs). let resp = driver.call("right_click", serde_json::json!({ @@ -308,7 +308,7 @@ fn harness_wpf_double_click() { let snap = snapshot(driver, pid, wid); let idx = ax::element_index_by_id(snap.text(), "border-click-target") .expect("border-click-target not in snapshot"); - // dispatch:foreground for the same reason as right_click — + // delivery_mode:foreground for the same reason as right_click — // PostMessage WM_LBUTTONDOWN ×2 doesn't always reach WPF's // MouseDoubleClick / ClickCount=2 path under test-batch load. let resp = driver.call("double_click", serde_json::json!({ @@ -534,7 +534,7 @@ fn harness_wpf_slider_drag() { // Regression guard for the SendInput drag path. PostMessage drag // doesn't update GetKeyState, so WPF's Thumb-drag handler (which // polls Mouse.LeftButton via GetKeyState) never sees the button - // held — the thumb stays put. dispatch:"foreground" routes through + // held — the thumb stays put. delivery_mode:"foreground" routes through // send_drag_synthesized which goes via the system input queue and // DOES update GetKeyState, so the thumb actually tracks. // @@ -620,7 +620,7 @@ fn harness_wpf_checkbox_toggle() { // CheckBox exposes UIA TogglePattern (actions=[toggle]), not Invoke. // cua-driver's click tool tries UIA Invoke first; for elements that // don't support it the PostMessage fallback path runs. Use - // dispatch:"foreground" to land a SendInput click that WPF + // delivery_mode:"foreground" to land a SendInput click that WPF // recognises as a real user click and processes through Toggle. let resp = driver.call("click", serde_json::json!({ "pid": pid as i64, "window_id": wid, "element_index": idx, @@ -645,7 +645,7 @@ fn harness_wpf_radio_select() { let idx = ax::element_index_by_id(snap.text(), "rdo-high") .expect("rdo-high missing"); // RadioButton exposes SelectionItem pattern (actions=[select]). - // Same dispatch:foreground rationale as the checkbox test. + // Same delivery_mode:foreground rationale as the checkbox test. let _ = driver.call("click", serde_json::json!({ "pid": pid as i64, "window_id": wid, "element_index": idx, "delivery_mode": "foreground" diff --git a/libs/cua-driver/rust/crates/cua-driver/tests/modality_input_e2e_test.rs b/libs/cua-driver/rust/crates/cua-driver/tests/modality_input_e2e_test.rs index 511522449d..80572367fe 100644 --- a/libs/cua-driver/rust/crates/cua-driver/tests/modality_input_e2e_test.rs +++ b/libs/cua-driver/rust/crates/cua-driver/tests/modality_input_e2e_test.rs @@ -4,8 +4,8 @@ //! WITHOUT the target window ever being raised to the foreground. //! //! Verified two ways per action: -//! 1. The tool succeeds in the DEFAULT dispatch mode — no -//! `background_unavailable` error, no `dispatch:"foreground"` needed. +//! 1. The tool succeeds in the DEFAULT delivery mode — no +//! `background_unavailable` error, no `delivery_mode:"foreground"` needed. //! 2. The `focus-monitor-win` sentinel records ZERO foreground losses across //! the action == the target window was not z-raised over the user's //! window (same oracle as `harness_bg_modality_test`). @@ -351,7 +351,7 @@ fn webview_click_case(label: &str, exe: PathBuf) { assert!(!errored, "{label}: default-mode click errored: {delivered}"); assert!( !needs_foreground, - "{label}: click should not need dispatch:foreground, got {delivered:?}" + "{label}: click should not need delivery_mode:foreground, got {delivered:?}" ); // Delivery is confirmed by the driver's own ✅ result (UIA Invoke fires the // element's default action / DOM `click`). The /events pointer-log is info diff --git a/libs/cua-driver/rust/crates/platform-macos/src/tools/bring_to_front.rs b/libs/cua-driver/rust/crates/platform-macos/src/tools/bring_to_front.rs index 7a067cb9de..3839596f9a 100644 --- a/libs/cua-driver/rust/crates/platform-macos/src/tools/bring_to_front.rs +++ b/libs/cua-driver/rust/crates/platform-macos/src/tools/bring_to_front.rs @@ -4,7 +4,7 @@ //! swap before driving a focus-proxy target — a window that only accepts input //! while its host app genuinely holds activation. The macOS input rungs never //! need this internally: every `CGEvent.postToPid` dispatch reaches a -//! backgrounded window, and the `dispatch:"foreground"` rung does its own +//! backgrounded window, and the `delivery_mode:"foreground"` rung does its own //! sub-millisecond front→act→restore flash. The one surface that flash can't //! satisfy is a remote-desktop client (e.g. Microsoft's Windows App / RDP), //! which re-establishes its keyboard channel with the remote host *on @@ -34,7 +34,7 @@ fn def() -> &'static ToolDef { description: "Persistently activate an app so it genuinely holds macOS foreground, \ then leave it there. Most input does NOT need this — every macOS \ - dispatch reaches backgrounded windows, and `dispatch:\"foreground\"` \ + dispatch reaches backgrounded windows, and `delivery_mode:\"foreground\"` \ does its own brief front→act→restore. Reach for `bring_to_front` only \ for a focus-proxy surface that re-arms its own input channel on \ activation and must stay frontmost across the interaction — chiefly a \ diff --git a/libs/cua-driver/rust/crates/platform-windows/src/input/delivery.rs b/libs/cua-driver/rust/crates/platform-windows/src/input/delivery.rs index bea65de2f4..a877cbde5c 100644 --- a/libs/cua-driver/rust/crates/platform-windows/src/input/delivery.rs +++ b/libs/cua-driver/rust/crates/platform-windows/src/input/delivery.rs @@ -168,7 +168,7 @@ pub fn would_be_silently_dropped(hwnd: u64, kind: EventKind) -> bool { // clicks, drawing-area widgets accept them. We cannot distinguish // at the HWND level (single HWND for the whole GTK window) so we // flag mouse clicks broadly. Canvas-style drag works in practice; - // caller can still opt to retry with dispatch:"background" on the + // caller can still opt to retry with delivery_mode:"background" on the // drag path if the click error wasn't actually load-bearing. return matches!(kind, MouseClick); } @@ -181,7 +181,7 @@ pub fn would_be_silently_dropped(hwnd: u64, kind: EventKind) -> bool { // Alt+F4) silently fail. Plain WM_CHAR text input through the // document widgets still works (verified end-to-end against // Writer's main editing area). Flag the keystroke-class events - // so dispatch:"background" surfaces a structured error instead + // so delivery_mode:"background" surfaces a structured error instead // of pretending to succeed. return matches!(kind, Keystroke | KeyCombo); } @@ -275,7 +275,7 @@ pub fn read_class_name(hwnd: u64) -> String { } /// Build the structured `background_unavailable` error returned when -/// `dispatch:"background"` would silently drop. +/// `delivery_mode:"background"` would silently drop. pub fn background_unavailable_error( hwnd: u64, kind: EventKind, diff --git a/libs/cua-driver/rust/crates/platform-windows/src/uia/mod.rs b/libs/cua-driver/rust/crates/platform-windows/src/uia/mod.rs index dc6f68259a..4e5abfe90a 100644 --- a/libs/cua-driver/rust/crates/platform-windows/src/uia/mod.rs +++ b/libs/cua-driver/rust/crates/platform-windows/src/uia/mod.rs @@ -286,7 +286,7 @@ unsafe fn walk_tree_unsafe( // The diagnostic tells callers exactly how to drive the SAL // dialog without the tree: pixel click off the screenshot // get_window_state always returns, or press_key with - // dispatch:"foreground" for accelerator-style dismissal. That's enough for the + // delivery_mode:"foreground" for accelerator-style dismissal. That's enough for the // common modal-dismissal case (Yes/No/Esc on a Confirmation), // which is what SAL dialogs almost always need. let is_sal = { From 924ca72fce0fac7b4c505ba4db880458bf90d946 Mon Sep 17 00:00:00 2001 From: Zane Chee Date: Thu, 2 Jul 2026 11:03:02 +0800 Subject: [PATCH 2/2] docs(cua-driver): regenerate MCP tool reference --- docs/content/docs/reference/cua-driver/mcp-tools.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/docs/reference/cua-driver/mcp-tools.mdx b/docs/content/docs/reference/cua-driver/mcp-tools.mdx index 2817733de0..357170df0d 100644 --- a/docs/content/docs/reference/cua-driver/mcp-tools.mdx +++ b/docs/content/docs/reference/cua-driver/mcp-tools.mdx @@ -180,7 +180,7 @@ Force-terminate a process by pid (kill -9 equivalent on macOS / Linux; taskkill ### `bring_to_front` -Persistently activate an app so it genuinely holds macOS foreground, then leave it there. Most input does NOT need this — every macOS dispatch reaches backgrounded windows, and `dispatch:"foreground"` does its own brief front→act→restore. Reach for `bring_to_front` only for a focus-proxy surface that re-arms its own input channel on activation and must stay frontmost across the interaction — chiefly a remote-desktop client (Microsoft Windows App / RDP), where the brief flash drops keystrokes. Activates the owning app by pid (`NSRunningApplication.activate`); `window_id` is accepted for parity but activation is app-level. This DOES steal foreground — explicit opt-in, never used by the input ladder. +Persistently activate an app so it genuinely holds macOS foreground, then leave it there. Most input does NOT need this — every macOS dispatch reaches backgrounded windows, and `delivery_mode:"foreground"` does its own brief front→act→restore. Reach for `bring_to_front` only for a focus-proxy surface that re-arms its own input channel on activation and must stay frontmost across the interaction — chiefly a remote-desktop client (Microsoft Windows App / RDP), where the brief flash drops keystrokes. Activates the owning app by pid (`NSRunningApplication.activate`); `window_id` is accepted for parity but activation is app-level. This DOES steal foreground — explicit opt-in, never used by the input ladder. **Arguments:**