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.

docs(cua-driver): update delivery_mode wording in comments (#2092)

injaneitye46456923c13
diff --git a/docs/content/docs/reference/cua-driver/mcp-tools.mdx b/docs/content/docs/reference/cua-driver/mcp-tools.mdx
index 58f59b8159..7618e109d3 100644
--- a/docs/content/docs/reference/cua-driver/mcp-tools.mdx
+++ b/docs/content/docs/reference/cua-driver/mcp-tools.mdx
@@ -183,7 +183,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. Fronts the exact macOS window through WindowServer when `window_id` is present, with app-level Cocoa activation as a fallback. 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. Fronts the exact macOS window through WindowServer when `window_id` is present, with app-level Cocoa activation as a fallback. This DOES steal foreground — explicit opt-in, never used by the input ladder.
**Arguments:**
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 a71831a292..29c6b66c03 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
@@ -248,7 +248,7 @@ fn harness_winui3_xaml_popup_open() {
/// 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 43e334432f..61f48b5f71 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
@@ -24,7 +24,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
@@ -95,7 +95,7 @@ fn launch_harness_with_state_file(
// 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)
@@ -535,7 +535,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(
@@ -666,7 +666,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(
@@ -709,7 +709,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(
@@ -1144,7 +1144,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.
//
@@ -1323,7 +1323,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",
@@ -1363,7 +1363,7 @@ fn harness_wpf_radio_select() {
let snap = snapshot(driver, pid, wid);
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 response = driver.call(
"click",
serde_json::json!({
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 75f5908165..d2aaa26eee 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
@@ -35,7 +35,7 @@ fn def() -> &'static ToolDef {
name: "bring_to_front".into(),
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 93aca9a094..e5c641d0a0 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
@@ -187,7 +187,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);
}
@@ -200,7 +200,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);
}
@@ -323,7 +323,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 7c22217467..e47db06a2d 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
@@ -297,7 +297,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 = {