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.

feat(platform-macos): WindowChangeDetector + FocusGuard per-action focus suppression (#1526) (#1531)

Francesco Bonaccia91a2fbd15c8
diff --git a/libs/cua-driver-rs/PARITY.md b/libs/cua-driver-rs/PARITY.md
index 7a3c8d16c7..8c71dc8803 100644
--- a/libs/cua-driver-rs/PARITY.md
+++ b/libs/cua-driver-rs/PARITY.md
@@ -416,12 +416,12 @@ filter at the tool layer.
## MCP tool: `click`
- Swift: `libs/cua-driver/Sources/CuaDriverServer/Tools/ClickTool.swift:29-595`
- Rust:
- - macOS=`crates/platform-macos/src/tools/click.rs` (TBD audit)
+ - macOS=`crates/platform-macos/src/tools/click.rs` (focus-suppression wrap VERIFIED; full audit pending)
- windows=`crates/platform-windows/src/tools/impl_.rs` (ClickTool)
- linux=`crates/platform-linux/src/tools/impl_.rs` (ClickTool)
- Status:
- windows: VERIFIED (text format + error wording); schema divergences documented below
- - macOS: OPEN (already exists; line-by-line audit pending)
+ - macOS: VERIFIED (focus-suppression wrap — see [Per-action focus suppression](#per-action-focus-suppression)); full line-by-line audit pending
- linux: OPEN
- Test: `crates/platform-windows/examples/click_parity.rs`
@@ -579,9 +579,9 @@ Windows's `click` takes `{button: enum}` instead. Rationale:
- Swift: `libs/cua-driver/Sources/CuaDriverServer/Tools/PressKeyTool.swift:20-202`
- Rust:
- windows=`crates/platform-windows/src/tools/impl_.rs` (PressKeyTool)
- - macOS=`crates/platform-macos/src/tools/press_key.rs` (TBD)
+ - macOS=`crates/platform-macos/src/tools/press_key.rs` (focus-suppression wrap VERIFIED; full audit pending)
- linux=`crates/platform-linux/src/tools/impl_.rs` (TBD)
-- Status: windows VERIFIED; macOS / linux OPEN
+- Status: windows VERIFIED; macOS VERIFIED (focus-suppression wrap — see [Per-action focus suppression](#per-action-focus-suppression)); linux OPEN
- Test: `crates/platform-windows/examples/press_key_parity.rs`
### Fixed (Windows)
@@ -623,9 +623,9 @@ Windows's `click` takes `{button: enum}` instead. Rationale:
- Swift: `libs/cua-driver/Sources/CuaDriverServer/Tools/HotkeyTool.swift:6-142`
- Rust:
- windows=`crates/platform-windows/src/tools/impl_.rs` (HotkeyTool)
- - macOS=`crates/platform-macos/src/tools/hotkey.rs` (TBD)
+ - macOS=`crates/platform-macos/src/tools/hotkey.rs` (focus-suppression wrap VERIFIED; full audit pending)
- linux=`crates/platform-linux/src/tools/impl_.rs` (TBD)
-- Status: windows VERIFIED; macOS / linux OPEN
+- Status: windows VERIFIED; macOS VERIFIED (focus-suppression wrap — see [Per-action focus suppression](#per-action-focus-suppression)); linux OPEN
- Test: `crates/platform-windows/examples/hotkey_parity.rs`
### Fixed (Windows)
@@ -1497,11 +1497,15 @@ Now uses prefix `cua-driver-rs-v` (Rust port's actual tag prefix).
## Focus-steal prevention
-Cross-cutting infrastructure (not an MCP tool) used by `launch_app` today
-and slated for use by `click`/`hotkey`/AX-action tools when those are
-ported to Rust macOS. Catches apps that self-activate during launch
-(Chrome, Electron, Safari) and re-activates the prior frontmost app
-before the user perceives the steal.
+Cross-cutting infrastructure (not an MCP tool) used by `launch_app` and
+by the 7 action tools (`click`, `type_text`, `hotkey`, `press_key`,
+`drag`, `scroll`, `set_value`) via the
+[Per-action focus suppression](#per-action-focus-suppression) wrap.
+Catches apps that self-activate during launch (Chrome, Electron,
+Safari) or as a side-effect of an action (Safari opening a new tab in
+response to AXPress, autocomplete pulling itself forward), and
+re-activates the prior frontmost app before the user perceives the
+steal.
- Swift: `libs/cua-driver/Sources/CuaDriverCore/Focus/SystemFocusStealPreventer.swift`
- Swift hardening: open PR [#1521](https://github.com/trycua/cua/pull/1521)
@@ -1549,13 +1553,110 @@ before the user perceives the steal.
### Intentional simplifications vs Swift
-- **No `FocusGuard.withFocusSuppressed` analogue yet** — Swift's
- per-AX-action wrapper. The Rust `click` AX path doesn't exist yet, so
- there's nothing to wrap. Port when the AX action path lands.
-- **No `WindowChangeDetector` analogue yet** — same reason; the Rust port
- has no snapshot/detect cycle to wrap. Port when WindowChangeDetector
- lands.
+- **`FocusGuard.withFocusSuppressed` ships layer 3 only** — see
+ [Per-action focus suppression](#per-action-focus-suppression). The
+ reactive suppressor is wired up across the 7 action tools; the
+ enablement (`AXManualAccessibility`/`AXEnhancedUserInterface`) and
+ synthetic-focus (`AXFocused`/`AXMain` write+restore) layers are
+ deferred because the AX assertion + attribute-write plumbing isn't
+ yet ported. Empirically the layer-3 guard combined with
+ `WindowChangeDetector`'s wildcard catches the majority of
+ side-effects on real-world workflows.
+- **`WindowChangeDetector` ported and wired** — see
+ [Per-action focus suppression](#per-action-focus-suppression).
- **Janitor uses `tokio::sync::watch`** — Swift uses Task cancellation;
Rust's tokio idiom is the watch-channel select pattern. Behavior is
identical: idle dispatcher → janitor sleeps; new entry → janitor
wakes; map drains → janitor exits and waits for the next add.
+
+---
+
+## Per-action focus suppression
+
+Per-action wrap around the 7 macOS action tools (`click`, `type_text`,
+`hotkey`, `press_key`, `drag`, `scroll`, `set_value`) that catches
+side-effect side-effects of dispatching an action on a backgrounded
+app — Safari opening a new tab in response to AXPress, a "Sign In"
+button opening a sheet, an autocomplete popover floating into view,
+etc. Mirrors Swift's `WindowChangeDetector` + `FocusGuard` cross-cutting
+helpers wired into ClickTool / TypeTextTool / SetValueTool.
+
+- Swift:
+ - `libs/cua-driver/Sources/CuaDriverServer/Tools/WindowChangeDetector.swift`
+ - `libs/cua-driver/Sources/CuaDriverCore/Focus/FocusGuard.swift`
+- Rust:
+ - `crates/platform-macos/src/window_change_detector.rs`
+ - `crates/platform-macos/src/focus_guard.rs`
+- Status: macOS VERIFIED (action tools wired up; result-suffix wording
+ matches Swift verbatim). windows/linux N/A (different focus model).
+- Tests:
+ - Rust unit: `window_change_detector::tests` (8 cases — diff +
+ result_suffix branches) and `focus_guard::tests` (4 cases —
+ arm/skip lifecycle).
+ - Integration: existing `tests/integration/test_focus_steal_parity.py`
+ + `tests/integration/test_api_parity.py` — confirmed no regression
+ after the action-tool wiring (identical pass/fail to main).
+
+### Snapshot → action → detect cycle
+
+Each wrapped action follows the same shape:
+
+```rust
+let prior = apps::frontmost_pid();
+let snapshot = WindowChangeDetector::snapshot(); // arms wildcard
+let result = focus_guard::with_focus_suppressed(
+ Some(target_pid), prior, "<tool>.<origin>",
+ || async { do_action(...).await }
+).await;
+let changes = snapshot.detect_async().await; // drops wildcard
+// append changes.result_suffix() to success text
+```
+
+Two suppression entries are armed in series:
+
+1. **Wildcard** (armed in `snapshot()`, dropped in `detect()`) —
+ `target_pid = None`, `restore_to = current frontmost`. Catches any
+ activation other than the prior frontmost during the full
+ snapshot → action → detect window. Mirrors Swift's
+ `WindowChangeDetector.snapshot()` wildcard.
+2. **Targeted** (armed by `FocusGuard::with_focus_suppressed` around
+ the action call) — `target_pid = Some(action_pid)`,
+ `restore_to = prior frontmost`. Catches a target-self-activation
+ triggered by the AX call itself. Skipped when target ==
+ frontmost (no point fighting ourselves). 50ms post-action settle
+ before the lease drops, giving any in-flight reflex activation
+ time to be observed.
+
+### Result-suffix verbatim
+
+The `Changes.result_suffix()` wording matches Swift's
+`WindowChangeDetector.Changes.resultSuffix`:
+
+- New windows: `"\n\n🪟 Action opened new window(s): App (\"Title\")."`
+ (multiple windows grouped by app, titles in quotes, joined with a
+ `,` (comma followed by a space); multiple apps joined with a `;`
+ (semicolon followed by a space); alphabetical by app name).
+- Foreground-only change (no new windows): `"\n\n🔀 Action caused a
+ different app to become frontmost."`.
+- No change: empty string.
+
+MCP callers can string-match on either lead emoji to detect a
+side-effect without per-binary special-casing.
+
+### Intentional simplifications vs Swift
+
+- **FocusGuard layers 1+2 (enablement, synthetic-focus) deferred** —
+ Swift's `AXManualAccessibility` / `AXEnhancedUserInterface`
+ assertion and `AXFocused`/`AXMain` write+restore aren't ported yet.
+ The Rust port ships only layer 3 (reactive suppressor). Empirically
+ the wildcard + targeted reactive pair catches the majority of
+ side-effects; layers 1+2 are a follow-up when the AX assertion
+ plumbing lands.
+- **Pure-function diff exposed for tests** — `Snapshot::diff` is
+ `pub(crate)` so unit tests can pin down opened/closed semantics
+ without driving the live `CGWindowList` enumerator. Swift tests
+ the same way via `currentWindowIds()` indirection.
+- **`detect_async()` runs on `spawn_blocking`** — Swift's poll loop
+ uses `Task.sleep`; Rust's blocking `std::thread::sleep` is cheap to
+ offload via `tokio::task::spawn_blocking` and keeps the runtime
+ responsive to other in-flight work.
diff --git a/libs/cua-driver-rs/crates/platform-macos/src/focus_guard.rs b/libs/cua-driver-rs/crates/platform-macos/src/focus_guard.rs
new file mode 100644
index 0000000000..62f3d25f47
--- /dev/null
+++ b/libs/cua-driver-rs/crates/platform-macos/src/focus_guard.rs
@@ -0,0 +1,205 @@
+//! FocusGuard — Rust port of Swift's `FocusGuard.withFocusSuppressed`
+//! (`libs/cua-driver/Sources/CuaDriverCore/Focus/FocusGuard.swift`).
+//!
+//! ## What this does
+//!
+//! Wraps an individual AX-action call (the inside of a click / type /
+//! set_value / drag dispatch) with a **targeted** focus-steal suppression
+//! lease. Catches the case where dispatching an AX attribute write
+//! triggers a reflexive self-activation in the target app — Safari /
+//! WebKit will sometimes pull itself to the front when an
+//! `AXSelectedText` write hits a focused input, even when the AX call
+//! itself doesn't go through `NSApp.activate(…)`.
+//!
+//! ## Layering relative to Swift
+//!
+//! Swift's `FocusGuard.withFocusSuppressed` does three things:
+//!
+//! 1. **Enablement** — set `AXManualAccessibility` /
+//! `AXEnhancedUserInterface` on the app root so Chromium/Electron
+//! targets respond to attribute-level dispatch.
+//! 2. **Synthetic focus** — write `AXFocused` / `AXMain` on the
+//! enclosing window + element before the action, restore after.
+//! Makes AppKit behave as if the action came from a focused
+//! process, preventing reflex activations.
+//! 3. **Reactive** — arm `SystemFocusStealPreventer` with a targeted
+//! entry. If the target self-activates anyway, re-activates the
+//! prior frontmost.
+//!
+//! This Rust port only ships **layer 3** (the reactive suppressor).
+//! Layers 1+2 require AX assertion + AX attribute write/restore machinery
+//! that isn't yet ported — and empirically the layer-3 reactive guard
+//! catches the majority of side-effects when combined with
+//! `WindowChangeDetector`'s wildcard lease at the snapshot→detect
+//! boundary. We document this gap in PARITY.md so the port is auditable.
+//!
+//! ## Why this is a separate module
+//!
+//! `focus_steal::with_suppression` already exists as a thin closure
+//! API around the dispatcher. `focus_guard::with_focus_suppressed`
+//! wraps it with:
+//!
+//! 1. A "is target already frontmost?" check so we don't arm a useless
+//! self→self suppressor (matches Swift's `isTargetFrontmost` guard).
+//! 2. A 50ms post-action sleep that gives any in-flight focus-grab
+//! reflex time to fire and be observed by the suppressor before the
+//! lease is dropped. Matches Swift's `Task.sleep(nanoseconds: 50ms)`.
+//! 3. A static `origin` label for tracing — call sites pass a short
+//! string like `"click.AXPress"` so leaked leases / late-firing
+//! observers can be traced back to the caller.
+
+use std::time::Duration;
+
+use crate::apps;
+use crate::focus_steal;
+
+/// Wrap an async closure `f` with a targeted focus-steal suppressor.
+///
+/// - `target_pid` — the pid the action is dispatched to. `Some(pid)` is
+/// the standard case; `None` skips the targeted entry entirely
+/// (caller relies on the surrounding `WindowChangeDetector` wildcard
+/// lease).
+/// - `prior_frontmost` — the pid to restore focus to if the target
+/// activates. Typically captured from `apps::frontmost_pid()` before
+/// the snapshot.
+/// - `origin` — short static label for tracing, e.g. `"click.AXPress"`.
+/// - `f` — the action to run with suppression armed.
+///
+/// Returns whatever `f` returns. Drops the lease ~50ms after `f`
+/// resolves so any in-flight reflex activation is observed before
+/// suppression ends.
+///
+/// If `target_pid` is already the frontmost app (no point fighting
+/// ourselves) or `prior_frontmost` is `None` (no app to restore to),
+/// the function still runs `f` — just without the lease. This keeps
+/// the call sites simple (no per-tool `if frontmost == target` ladders).
+pub async fn with_focus_suppressed<F, Fut, R>(
+ target_pid: Option<i32>,
+ prior_frontmost: Option<i32>,
+ origin: &'static str,
+ f: F,
+) -> R
+where
+ F: FnOnce() -> Fut,
+ Fut: std::future::Future<Output = R>,
+{
+ // Decide whether to arm a targeted lease. Three conditions must hold:
+ // 1. We have a known target pid (Some).
+ // 2. We have a prior frontmost to restore to (Some).
+ // 3. The target isn't already frontmost — Swift's
+ // `isTargetFrontmost` short-circuit, mirrored here. Without
+ // it we'd arm an entry that re-activates the prior frontmost
+ // against a no-op activation, fighting our own previous
+ // restore.
+ let should_arm = match (target_pid, prior_frontmost) {
+ (Some(tp), Some(pf)) => tp != pf,
+ _ => false,
+ };
+
+ let _lease = if should_arm {
+ // unwrap()s are safe — `should_arm` is true only when both are Some.
+ Some(focus_steal::begin_suppression(
+ target_pid,
+ prior_frontmost.unwrap(),
+ origin,
+ ))
+ } else {
+ None
+ };
+
+ let result = f().await;
+
+ // Post-action settle — give the reactive observer time to fire on
+ // any side-effect activation before we drop the lease. Matches
+ // Swift's 50ms sleep in `FocusGuard.withFocusSuppressed`.
+ if _lease.is_some() {
+ tokio::time::sleep(Duration::from_millis(50)).await;
+ }
+
+ // _lease drops here (RAII end_suppression).
+ result
+}
+
+/// Convenience wrapper that captures the current frontmost via
+/// `apps::frontmost_pid()` at call time. Use when the caller doesn't
+/// already have a `prior_frontmost` from a surrounding snapshot —
+/// e.g. tools that only opt into the layer-3 guard without the
+/// snapshot/detect cycle.
+///
+/// Most action tools should prefer `with_focus_suppressed` with an
+/// explicit `prior_frontmost` captured *before* the snapshot, so the
+/// wildcard lease + targeted lease both restore to the same pid.
+pub async fn with_focus_suppressed_now<F, Fut, R>(
+ target_pid: Option<i32>,
+ origin: &'static str,
+ f: F,
+) -> R
+where
+ F: FnOnce() -> Fut,
+ Fut: std::future::Future<Output = R>,
+{
+ let prior = apps::frontmost_pid();
+ with_focus_suppressed(target_pid, prior, origin, f).await
+}
+
+// ── Tests ────────────────────────────────────────────────────────────────────
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ /// `with_focus_suppressed` runs the closure and returns its value.
+ /// Skip-arming path (no prior frontmost) still executes f.
+ #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+ async fn runs_closure_without_prior_frontmost() {
+ let n = with_focus_suppressed(
+ Some(42),
+ None, // no prior → no lease armed
+ "test.no_prior",
+ || async { 7 },
+ )
+ .await;
+ assert_eq!(n, 7);
+ }
+
+ /// Skip-arming path: target == prior_frontmost (self → self).
+ #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+ async fn runs_closure_when_target_is_prior_frontmost() {
+ let n = with_focus_suppressed(
+ Some(42),
+ Some(42), // self → self → skip
+ "test.self_to_self",
+ || async { 11 },
+ )
+ .await;
+ assert_eq!(n, 11);
+ }
+
+ /// Arming path: target != prior_frontmost. The lease is armed,
+ /// closure runs, lease drops on the way out (we can't directly
+ /// observe the dispatcher state through the public API here —
+ /// the focus_steal module's own tests cover the lease lifecycle —
+ /// but we exercise the codepath to make sure it compiles and the
+ /// 50ms sleep doesn't deadlock.
+ #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+ async fn arms_lease_when_target_differs_from_prior() {
+ let n = with_focus_suppressed(
+ Some(123),
+ Some(456),
+ "test.armed",
+ || async { 99 },
+ )
+ .await;
+ assert_eq!(n, 99);
+ }
+
+ /// `with_focus_suppressed_now` resolves prior_frontmost via the
+ /// live NSWorkspace query — exercise the codepath end-to-end.
+ /// In a unit-test context (no NSApp main thread) the query may
+ /// return None; the closure must still run.
+ #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+ async fn now_variant_runs_even_when_frontmost_is_none() {
+ let n = with_focus_suppressed_now(Some(7), "test.now", || async { 5 }).await;
+ assert_eq!(n, 5);
+ }
+}
diff --git a/libs/cua-driver-rs/crates/platform-macos/src/lib.rs b/libs/cua-driver-rs/crates/platform-macos/src/lib.rs
index cf8d92bef1..f2c51cdea0 100644
--- a/libs/cua-driver-rs/crates/platform-macos/src/lib.rs
+++ b/libs/cua-driver-rs/crates/platform-macos/src/lib.rs
@@ -25,6 +25,10 @@ pub mod focus_steal;
#[cfg(target_os = "macos")]
pub mod permissions;
#[cfg(target_os = "macos")]
+pub mod focus_guard;
+#[cfg(target_os = "macos")]
+pub mod window_change_detector;
+#[cfg(target_os = "macos")]
pub mod tools;
use mcp_server::tool::ToolRegistry;
diff --git a/libs/cua-driver-rs/crates/platform-macos/src/tools/click.rs b/libs/cua-driver-rs/crates/platform-macos/src/tools/click.rs
index 59c2a7d1d2..aa71f007e4 100644
--- a/libs/cua-driver-rs/crates/platform-macos/src/tools/click.rs
+++ b/libs/cua-driver-rs/crates/platform-macos/src/tools/click.rs
@@ -22,6 +22,9 @@ use crate::ax::bindings::{
copy_action_names, copy_children, copy_string_attr, element_screen_rect,
AXUIElementRef,
};
+use crate::apps;
+use crate::focus_guard;
+use crate::window_change_detector::WindowChangeDetector;
use core_foundation::base::CFRelease;
use super::ToolState;
@@ -134,19 +137,41 @@ impl Tool for ClickTool {
crate::cursor::overlay::animate_cursor_to(cx, cy).await;
}
+ // ── Focus-suppression wrap (Swift WindowChangeDetector + FocusGuard) ──
+ // Capture prior frontmost, arm the wildcard suppressor in the
+ // snapshot, then arm a targeted suppressor across the AX action
+ // itself via FocusGuard. After the action returns, detect any
+ // new-window / foreground side-effects and append a one-liner
+ // suffix matching Swift's wording.
+ let prior_front = apps::frontmost_pid();
+ let snapshot = WindowChangeDetector::snapshot(prior_front);
+
// Run AX work on a blocking thread (can't block async executor).
let action_clone = action.clone();
- let result = tokio::task::spawn_blocking(move || {
- perform_ax_click(element_ptr, idx, pid, wid, &action_clone)
- }).await;
+ let result = focus_guard::with_focus_suppressed(
+ Some(pid),
+ prior_front,
+ "click.AXPress",
+ || async move {
+ tokio::task::spawn_blocking(move || {
+ perform_ax_click(element_ptr, idx, pid, wid, &action_clone)
+ })
+ .await
+ },
+ )
+ .await;
+
+ // Drop the wildcard lease + detect window/foreground side-effects.
+ let changes = snapshot.detect_async().await;
match result {
- Ok(Ok((msg, needs_webkit_delay))) => {
+ Ok(Ok((mut msg, needs_webkit_delay))) => {
// For text inputs, wait 800ms for WebKit DOM focus to settle
// before returning — matches the Swift reference behaviour.
if needs_webkit_delay {
tokio::time::sleep(std::time::Duration::from_millis(800)).await;
}
+ msg.push_str(&changes.result_suffix());
ToolResult::text(msg)
}
Ok(Err(e)) => ToolResult::error(format!("AX action failed: {e}")),
@@ -264,25 +289,46 @@ impl Tool for ClickTool {
cursor_overlay::OverlayCommand::ClickPulse { x: screen_x, y: screen_y }
);
+ // ── Focus-suppression wrap (Swift WindowChangeDetector + FocusGuard) ──
+ // A pixel click can land on a "Sign In" button that opens a sheet
+ // or a Safari link that activates a new tab — same side-effect
+ // shape as the AX path, so we wrap identically.
+ let prior_front = apps::frontmost_pid();
+ let snapshot = WindowChangeDetector::snapshot(prior_front);
+
let mods_owned = modifiers.clone();
- let result = tokio::task::spawn_blocking(move || {
- let m: Vec<&str> = mods_owned.iter().map(String::as_str).collect();
- // When we know the window_id, pass the window-local coordinates so
- // `click_at_xy_with_window_local` can stamp `CGEventSetWindowLocation`
- // and Chromium-specific fields (f40, f51, f58, f91, f92) onto events
- // for better backgrounded-target delivery.
- if let Some(wid) = window_id {
- return crate::input::mouse::click_at_xy_with_window_local(
- pid, screen_x, screen_y,
- win_local_x, win_local_y,
- wid, count, &m,
- );
- }
- crate::input::mouse::click_at_xy(pid, screen_x, screen_y, count, &m)
- }).await;
+ let result = focus_guard::with_focus_suppressed(
+ Some(pid),
+ prior_front,
+ "click.pixel",
+ || async move {
+ tokio::task::spawn_blocking(move || {
+ let m: Vec<&str> = mods_owned.iter().map(String::as_str).collect();
+ // When we know the window_id, pass the window-local coordinates so
+ // `click_at_xy_with_window_local` can stamp `CGEventSetWindowLocation`
+ // and Chromium-specific fields (f40, f51, f58, f91, f92) onto events
+ // for better backgrounded-target delivery.
+ if let Some(wid) = window_id {
+ return crate::input::mouse::click_at_xy_with_window_local(
+ pid, screen_x, screen_y,
+ win_local_x, win_local_y,
+ wid, count, &m,
+ );
+ }
+ crate::input::mouse::click_at_xy(pid, screen_x, screen_y, count, &m)
+ })
+ .await
+ },
+ )
+ .await;
+
+ let changes = snapshot.detect_async().await;
match result {
- Ok(Ok(())) => ToolResult::text(format!("✅ Posted click to pid {pid}.")),
+ Ok(Ok(())) => ToolResult::text(format!(
+ "✅ Posted click to pid {pid}.{}",
+ changes.result_suffix()
+ )),
Ok(Err(e)) => ToolResult::error(format!("Click failed: {e}")),
Err(e) => ToolResult::error(format!("Task error: {e}")),
}
diff --git a/libs/cua-driver-rs/crates/platform-macos/src/tools/drag.rs b/libs/cua-driver-rs/crates/platform-macos/src/tools/drag.rs
index 1debbf2f58..6e50724f80 100644
--- a/libs/cua-driver-rs/crates/platform-macos/src/tools/drag.rs
+++ b/libs/cua-driver-rs/crates/platform-macos/src/tools/drag.rs
@@ -12,7 +12,10 @@ use mcp_server::{protocol::ToolResult, tool::{Tool, ToolDef}};
use serde_json::Value;
use std::sync::Arc;
+use crate::apps;
+use crate::focus_guard;
use crate::input::mouse::DragButton;
+use crate::window_change_detector::WindowChangeDetector;
use super::ToolState;
pub struct DragTool {
@@ -199,23 +202,42 @@ impl Tool for DragTool {
}
crate::cursor::overlay::animate_cursor_to(from_sx, from_sy).await;
+ // ── Focus-suppression wrap (Swift WindowChangeDetector + FocusGuard) ──
+ // Drags can trigger drag-and-drop side-effects that spawn helper
+ // windows (drop on Dock, drop on background app icon) and the
+ // mouseDown half-event alone can activate the target app on some
+ // Chromium builds. Wrap to catch + report both.
+ let prior_front = apps::frontmost_pid();
+ let snapshot = WindowChangeDetector::snapshot(prior_front);
+
// Dispatch blocking drag synthesis.
let mods_owned = modifiers.clone();
- let result = tokio::task::spawn_blocking(move || {
- let m: Vec<&str> = mods_owned.iter().map(String::as_str).collect();
- crate::input::mouse::drag_at_xy(
- pid,
- from_sx, from_sy,
- to_sx, to_sy,
- Some((from_lx, from_ly)),
- Some((to_lx, to_ly)),
- window_id,
- duration_ms,
- steps,
- &m,
- button,
- )
- }).await;
+ let result = focus_guard::with_focus_suppressed(
+ Some(pid),
+ prior_front,
+ "drag.CGEvent",
+ || async move {
+ tokio::task::spawn_blocking(move || {
+ let m: Vec<&str> = mods_owned.iter().map(String::as_str).collect();
+ crate::input::mouse::drag_at_xy(
+ pid,
+ from_sx, from_sy,
+ to_sx, to_sy,
+ Some((from_lx, from_ly)),
+ Some((to_lx, to_ly)),
+ window_id,
+ duration_ms,
+ steps,
+ &m,
+ button,
+ )
+ })
+ .await
+ },
+ )
+ .await;
+
+ let changes = snapshot.detect_async().await;
// Animate cursor to end position.
crate::cursor::overlay::animate_cursor_to(to_sx, to_sy).await;
@@ -239,11 +261,12 @@ impl Tool for DragTool {
"✅ Posted drag{btn_suffix}{mod_suffix} to pid {pid} \
from window-pixel ({}, {}) → ({}, {}), \
screen ({}, {}) → ({}, {}) \
- in {duration_ms}ms / {steps} steps.",
+ in {duration_ms}ms / {steps} steps.{}",
from_x as i64, from_y as i64,
to_x as i64, to_y as i64,
from_sx as i64, from_sy as i64,
to_sx as i64, to_sy as i64,
+ changes.result_suffix(),
)),
Ok(Err(e)) => ToolResult::error(format!("drag failed: {e}")),
Err(e) => ToolResult::error(format!("Task error: {e}")),
diff --git a/libs/cua-driver-rs/crates/platform-macos/src/tools/hotkey.rs b/libs/cua-driver-rs/crates/platform-macos/src/tools/hotkey.rs
index 5c2b89819b..cde28faa09 100644
--- a/libs/cua-driver-rs/crates/platform-macos/src/tools/hotkey.rs
+++ b/libs/cua-driver-rs/crates/platform-macos/src/tools/hotkey.rs
@@ -4,6 +4,10 @@ use serde_json::Value;
use std::sync::Arc;
use libc;
+use crate::apps;
+use crate::focus_guard;
+use crate::window_change_detector::WindowChangeDetector;
+
use super::ToolState;
pub struct HotkeyTool {
@@ -112,20 +116,43 @@ impl Tool for HotkeyTool {
let key_display = raw_keys.join("+");
let window_id = args.get("window_id").and_then(|v| v.as_u64()).map(|v| v as u32);
- let result = tokio::task::spawn_blocking(move || {
- let m: Vec<&str> = modifiers.iter().map(String::as_str).collect();
- if let Some(wid) = window_id {
- crate::input::skylight::with_menu_shortcut_activation(pid as libc::pid_t, wid, || {
- crate::input::keyboard::hotkey_no_auth(pid, &key, &m)
- })?;
- Ok(())
- } else {
- crate::input::keyboard::hotkey(pid, &key, &m)
- }
- }).await;
+ // ── Focus-suppression wrap (Swift WindowChangeDetector + FocusGuard) ──
+ // Hotkeys like Cmd+N, Cmd+W, Cmd+T explicitly open/close
+ // windows. The NSMenu path also briefly activates the target via
+ // SLPSSetFrontProcessWithOptions which can race the wildcard
+ // suppressor — wrapping ensures both side-effects are observed
+ // and the prior frontmost is restored if the activation lingers.
+ let prior_front = apps::frontmost_pid();
+ let snapshot = WindowChangeDetector::snapshot(prior_front);
+
+ let result = focus_guard::with_focus_suppressed(
+ Some(pid),
+ prior_front,
+ "hotkey.CGEvent",
+ || async move {
+ tokio::task::spawn_blocking(move || {
+ let m: Vec<&str> = modifiers.iter().map(String::as_str).collect();
+ if let Some(wid) = window_id {
+ crate::input::skylight::with_menu_shortcut_activation(pid as libc::pid_t, wid, || {
+ crate::input::keyboard::hotkey_no_auth(pid, &key, &m)
+ })?;
+ Ok(())
+ } else {
+ crate::input::keyboard::hotkey(pid, &key, &m)
+ }
+ })
+ .await
+ },
+ )
+ .await;
+
+ let changes = snapshot.detect_async().await;
match result {
- Ok(Ok(())) => ToolResult::text(format!("Pressed {key_display} on pid {pid}.")),
+ Ok(Ok(())) => ToolResult::text(format!(
+ "Pressed {key_display} on pid {pid}.{}",
+ changes.result_suffix()
+ )),
Ok(Err(e)) => ToolResult::error(format!("hotkey failed: {e}")),
Err(e) => ToolResult::error(format!("Task error: {e}")),
}
diff --git a/libs/cua-driver-rs/crates/platform-macos/src/tools/press_key.rs b/libs/cua-driver-rs/crates/platform-macos/src/tools/press_key.rs
index 0a3b8df3e7..fd8066ba48 100644
--- a/libs/cua-driver-rs/crates/platform-macos/src/tools/press_key.rs
+++ b/libs/cua-driver-rs/crates/platform-macos/src/tools/press_key.rs
@@ -4,6 +4,10 @@ use serde_json::Value;
use std::sync::Arc;
use libc;
+use crate::apps;
+use crate::focus_guard;
+use crate::window_change_detector::WindowChangeDetector;
+
use super::ToolState;
pub struct PressKeyTool {
@@ -86,32 +90,65 @@ impl Tool for PressKeyTool {
};
let display_key = key_raw.clone();
- // Pre-focus element if requested (element_index + window_id path).
- if let (Some(idx), Some(wid)) = (element_index, window_id) {
- if let Some(element_ptr) = self.state.element_cache.get_element_ptr(pid, wid, idx) {
- let _ = tokio::task::spawn_blocking(move || {
- crate::input::ax_actions::focus_element(element_ptr)
- }).await;
- tokio::time::sleep(std::time::Duration::from_millis(30)).await;
- }
- }
+ // Resolve the pre-focus element pointer (if requested) outside
+ // the suppression closure — only the focus_element() write itself
+ // needs to run under suppression, the cache lookup does not.
+ let pre_focus_ptr: Option<usize> = if let (Some(idx), Some(wid)) = (element_index, window_id) {
+ self.state.element_cache.get_element_ptr(pid, wid, idx)
+ } else {
+ None
+ };
- let result = tokio::task::spawn_blocking(move || {
- let m: Vec<&str> = modifiers.iter().map(String::as_str).collect();
- if let Some(wid) = window_id {
- if element_index.is_none() {
- // NSMenu path: window_id set but no element_index.
- crate::input::skylight::with_menu_shortcut_activation(pid as libc::pid_t, wid, || {
- crate::input::keyboard::press_key_no_auth(pid, &key, &m)
- })?;
- return Ok(());
+ // ── Focus-suppression wrap (Swift WindowChangeDetector + FocusGuard) ──
+ // Single-key presses can fire autocomplete (Return on a search
+ // box opens a results popover) or trigger menu shortcuts that
+ // open windows. Wrapping mirrors the hotkey path.
+ //
+ // The AX focus_element() pre-write also runs inside the closure
+ // so any reflex activations it triggers are caught by both the
+ // wildcard snapshot suppressor and the targeted FocusGuard lease.
+ let prior_front = apps::frontmost_pid();
+ let snapshot = WindowChangeDetector::snapshot(prior_front);
+
+ let result = focus_guard::with_focus_suppressed(
+ Some(pid),
+ prior_front,
+ "press_key.CGEvent",
+ || async move {
+ // Pre-focus the element under suppression so its
+ // side-effects are captured by the snapshot + lease.
+ if let Some(element_ptr) = pre_focus_ptr {
+ let _ = tokio::task::spawn_blocking(move || {
+ crate::input::ax_actions::focus_element(element_ptr)
+ }).await;
+ tokio::time::sleep(std::time::Duration::from_millis(30)).await;
}
- }
- crate::input::keyboard::press_key(pid, &key, &m)
- }).await;
+
+ tokio::task::spawn_blocking(move || {
+ let m: Vec<&str> = modifiers.iter().map(String::as_str).collect();
+ if let Some(wid) = window_id {
+ if element_index.is_none() {
+ // NSMenu path: window_id set but no element_index.
+ crate::input::skylight::with_menu_shortcut_activation(pid as libc::pid_t, wid, || {
+ crate::input::keyboard::press_key_no_auth(pid, &key, &m)
+ })?;
+ return Ok(());
+ }
+ }
+ crate::input::keyboard::press_key(pid, &key, &m)
+ })
+ .await
+ },
+ )
+ .await;
+
+ let changes = snapshot.detect_async().await;
match result {
- Ok(Ok(())) => ToolResult::text(format!("✅ Pressed {display_key} on pid {pid}.")),
+ Ok(Ok(())) => ToolResult::text(format!(
+ "✅ Pressed {display_key} on pid {pid}.{}",
+ changes.result_suffix()
+ )),
Ok(Err(e)) => ToolResult::error(format!("press_key failed: {e}")),
Err(e) => ToolResult::error(format!("Task error: {e}")),
}
diff --git a/libs/cua-driver-rs/crates/platform-macos/src/tools/scroll.rs b/libs/cua-driver-rs/crates/platform-macos/src/tools/scroll.rs
index ea8b642da1..cb07976470 100644
--- a/libs/cua-driver-rs/crates/platform-macos/src/tools/scroll.rs
+++ b/libs/cua-driver-rs/crates/platform-macos/src/tools/scroll.rs
@@ -3,6 +3,10 @@ use mcp_server::{protocol::ToolResult, tool::{Tool, ToolDef}};
use serde_json::Value;
use std::sync::Arc;
+use crate::apps;
+use crate::focus_guard;
+use crate::window_change_detector::WindowChangeDetector;
+
use super::ToolState;
pub struct ScrollTool {
@@ -73,15 +77,14 @@ impl Tool for ScrollTool {
let element_index = args.get("element_index").and_then(|v| v.as_u64()).map(|v| v as usize);
let window_id = args.get("window_id").and_then(|v| v.as_u64()).map(|v| v as u32);
- // Pre-focus element if requested.
- if let (Some(idx), Some(wid)) = (element_index, window_id) {
- if let Some(element_ptr) = self.state.element_cache.get_element_ptr(pid, wid, idx) {
- let _ = tokio::task::spawn_blocking(move || {
- crate::input::ax_actions::focus_element(element_ptr)
- }).await;
- tokio::time::sleep(std::time::Duration::from_millis(30)).await;
- }
- }
+ // Resolve the pre-focus element pointer (if requested) outside
+ // the suppression closure — only the focus_element() write itself
+ // needs to run under suppression, the cache lookup does not.
+ let pre_focus_ptr: Option<usize> = if let (Some(idx), Some(wid)) = (element_index, window_id) {
+ self.state.element_cache.get_element_ptr(pid, wid, idx)
+ } else {
+ None
+ };
let key = match (by.as_str(), direction.as_str()) {
("page", "down") | (_, "down") if by == "page" => "pagedown",
@@ -94,18 +97,52 @@ impl Tool for ScrollTool {
};
let key = key.to_owned();
- let result = tokio::task::spawn_blocking(move || {
- for _ in 0..amount {
- if let Err(e) = crate::input::keyboard::press_key(pid, &key, &[]) {
- return Err(e);
+ // ── Focus-suppression wrap (Swift WindowChangeDetector + FocusGuard) ──
+ // Scroll keystrokes (PageDown / arrow) into search-box autocomplete
+ // can spawn floating helper windows; rare but real. Wrap for parity
+ // with the other action tools.
+ //
+ // The AX focus_element() pre-write also runs inside the closure so
+ // any reflex activations it triggers are caught by both the wildcard
+ // snapshot suppressor and the targeted FocusGuard lease.
+ let prior_front = apps::frontmost_pid();
+ let snapshot = WindowChangeDetector::snapshot(prior_front);
+
+ let result = focus_guard::with_focus_suppressed(
+ Some(pid),
+ prior_front,
+ "scroll.CGEvent",
+ || async move {
+ // Pre-focus the element under suppression so its
+ // side-effects are captured by the snapshot + lease.
+ if let Some(element_ptr) = pre_focus_ptr {
+ let _ = tokio::task::spawn_blocking(move || {
+ crate::input::ax_actions::focus_element(element_ptr)
+ }).await;
+ tokio::time::sleep(std::time::Duration::from_millis(30)).await;
}
- std::thread::sleep(std::time::Duration::from_millis(50));
- }
- Ok(())
- }).await;
+
+ tokio::task::spawn_blocking(move || {
+ for _ in 0..amount {
+ if let Err(e) = crate::input::keyboard::press_key(pid, &key, &[]) {
+ return Err(e);
+ }
+ std::thread::sleep(std::time::Duration::from_millis(50));
+ }
+ Ok(())
+ })
+ .await
+ },
+ )
+ .await;
+
+ let changes = snapshot.detect_async().await;
match result {
- Ok(Ok(())) => ToolResult::text(format!("Scrolled {direction} by {by} × {amount}.")),
+ Ok(Ok(())) => ToolResult::text(format!(
+ "Scrolled {direction} by {by} × {amount}.{}",
+ changes.result_suffix()
+ )),
Ok(Err(e)) => ToolResult::error(format!("Scroll failed: {e}")),
Err(e) => ToolResult::error(format!("Task error: {e}")),
}
diff --git a/libs/cua-driver-rs/crates/platform-macos/src/tools/set_value.rs b/libs/cua-driver-rs/crates/platform-macos/src/tools/set_value.rs
index 85d4e17cd2..2380be7779 100644
--- a/libs/cua-driver-rs/crates/platform-macos/src/tools/set_value.rs
+++ b/libs/cua-driver-rs/crates/platform-macos/src/tools/set_value.rs
@@ -16,10 +16,13 @@ use mcp_server::{protocol::ToolResult, tool::{Tool, ToolDef}};
use serde_json::Value;
use std::sync::Arc;
+use crate::apps;
use crate::ax::bindings::{
copy_children, copy_string_attr, perform_action, set_string_attr,
kAXErrorSuccess, AXUIElementRef,
};
+use crate::focus_guard;
+use crate::window_change_detector::WindowChangeDetector;
use core_foundation::base::CFRelease;
use super::ToolState;
@@ -105,12 +108,33 @@ impl Tool for SetValueTool {
)),
};
- let result = tokio::task::spawn_blocking(move || {
- set_value_blocking(element_ptr, element_index, pid, &value)
- }).await;
+ // ── Focus-suppression wrap (Swift WindowChangeDetector + FocusGuard) ──
+ // AXValue writes on popups / sliders can cause reflex activations
+ // in Chromium-based apps; the AXPopUpButton path also AXPresses a
+ // child option which can trigger app activation in some setups.
+ let prior_front = apps::frontmost_pid();
+ let snapshot = WindowChangeDetector::snapshot(prior_front);
+
+ let result = focus_guard::with_focus_suppressed(
+ Some(pid),
+ prior_front,
+ "set_value.AXValue",
+ || async move {
+ tokio::task::spawn_blocking(move || {
+ set_value_blocking(element_ptr, element_index, pid, &value)
+ })
+ .await
+ },
+ )
+ .await;
+
+ let changes = snapshot.detect_async().await;
match result {
- Ok(Ok(msg)) => ToolResult::text(msg),
+ Ok(Ok(mut msg)) => {
+ msg.push_str(&changes.result_suffix());
+ ToolResult::text(msg)
+ }
Ok(Err(e)) => ToolResult::error(format!("set_value failed: {e}")),
Err(e) => ToolResult::error(format!("Task error: {e}")),
}
diff --git a/libs/cua-driver-rs/crates/platform-macos/src/tools/type_text.rs b/libs/cua-driver-rs/crates/platform-macos/src/tools/type_text.rs
index 8040e0b4eb..9c5e4d63d2 100644
--- a/libs/cua-driver-rs/crates/platform-macos/src/tools/type_text.rs
+++ b/libs/cua-driver-rs/crates/platform-macos/src/tools/type_text.rs
@@ -22,6 +22,9 @@ use crate::ax::bindings::{
copy_string_attr, focused_element_of_pid, kAXErrorSuccess, set_string_attr,
AXUIElementRef,
};
+use crate::apps;
+use crate::focus_guard;
+use crate::window_change_detector::WindowChangeDetector;
use core_foundation::base::CFRelease;
use super::ToolState;
@@ -120,13 +123,33 @@ impl Tool for TypeTextTool {
let text_clone = text.clone();
let char_count = text.chars().count();
- let result = tokio::task::spawn_blocking(move || {
- type_text_blocking(pid, &text_clone, element_ptr, delay_ms)
- }).await;
+ // ── Focus-suppression wrap (Swift WindowChangeDetector + FocusGuard) ──
+ // Typing into a field can trigger autocomplete popovers or
+ // Chrome/Safari's "Save Password?" prompt, both of which open
+ // helper windows. Wrap so callers see them in the result suffix
+ // and the wildcard suppressor catches reflex activations.
+ let prior_front = apps::frontmost_pid();
+ let snapshot = WindowChangeDetector::snapshot(prior_front);
+
+ let result = focus_guard::with_focus_suppressed(
+ Some(pid),
+ prior_front,
+ "type_text.AXSelectedText",
+ || async move {
+ tokio::task::spawn_blocking(move || {
+ type_text_blocking(pid, &text_clone, element_ptr, delay_ms)
+ })
+ .await
+ },
+ )
+ .await;
+
+ let changes = snapshot.detect_async().await;
match result {
Ok(Ok(detail)) => ToolResult::text(format!(
- "✅ Inserted {char_count} char(s){detail}."
+ "✅ Inserted {char_count} char(s){detail}.{}",
+ changes.result_suffix()
)),
Ok(Err(e)) => ToolResult::error(format!("type_text failed: {e}")),
Err(e) => ToolResult::error(format!("Task error: {e}")),
diff --git a/libs/cua-driver-rs/crates/platform-macos/src/window_change_detector.rs b/libs/cua-driver-rs/crates/platform-macos/src/window_change_detector.rs
new file mode 100644
index 0000000000..aab84209e0
--- /dev/null
+++ b/libs/cua-driver-rs/crates/platform-macos/src/window_change_detector.rs
@@ -0,0 +1,485 @@
+//! Window-change detector — Rust port of Swift's
+//! `WindowChangeDetector` (`libs/cua-driver/Sources/CuaDriverServer/Tools/WindowChangeDetector.swift`).
+//!
+//! ## What this does
+//!
+//! Action tools (click, type_text, hotkey, …) on a backgrounded app can
+//! trigger window/foreground side-effects: a "Sign In" button opens a
+//! modal sheet, a Safari link spawns a new tab, an autocomplete dropdown
+//! pops a helper window. The Rust port mirrors Swift's
+//! snapshot → action → detect cycle so tool results can:
+//!
+//! 1. Surface the side-effect to the agent (one-line suffix on the
+//! tool result, matching Swift verbatim).
+//! 2. Arm a **wildcard** focus-steal suppression entry that covers the
+//! full snapshot→detect window. Wildcards (`target_pid = None`)
+//! catch any activation other than the prior frontmost — so even an
+//! app we didn't know about (Safari activating because a UTM Gallery
+//! link routed to it) is suppressed before the first compositor
+//! frame.
+//!
+//! ## Usage
+//!
+//! ```ignore
+//! // Callers capture frontmost BEFORE the snapshot so the wildcard
+//! // suppressor and the snapshot's recorded frontmost agree on the
+//! // pid to restore to — avoids a race where another app activates
+//! // between the caller's `frontmost_pid()` and the detector's own.
+//! let prior_front = apps::frontmost_pid();
+//! let snapshot = WindowChangeDetector::snapshot(prior_front);
+//! // … perform action …
+//! let changes = snapshot.detect();
+//! // changes.result_suffix() — append to ToolResult text.
+//! ```
+//!
+//! Dropping the `Snapshot` ends the suppression lease (RAII). `detect()`
+//! also drops the lease before returning — the lease's `Drop` is
+//! idempotent so explicit-detect + later-drop is safe.
+
+use std::collections::HashSet;
+use std::time::{Duration, Instant};
+
+use crate::apps;
+use crate::focus_steal::{self, SuppressionLease};
+use crate::windows::{self, WindowInfo};
+
+/// One window that appeared between `snapshot()` and `detect()`.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct WindowEvent {
+ pub window_id: u32,
+ pub pid: i32,
+ pub app_name: String,
+ pub title: String,
+}
+
+/// Categorical diff entry. We mirror Swift which only emits
+/// `WindowEvent` rows for *new* windows — closed/changed never appear
+/// in the result suffix — but keep them as enum variants for future
+/// extensibility and so unit tests can pin down the diff semantics.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum WindowChange {
+ Opened(WindowEvent),
+ Closed { window_id: u32 },
+}
+
+/// State captured immediately before the action fires.
+///
+/// Holds:
+/// - `window_ids` — the set of visible layer-0 window IDs at snapshot
+/// time. `detect()` diffs against this.
+/// - `front_pid` — the OS frontmost pid at snapshot time. `detect()`
+/// reports whether a *different* pid became frontmost. The wildcard
+/// suppressor in `focus_steal` will normally restore the original
+/// front before `detect()`'s poll loop observes the change, so this
+/// field is best-effort.
+/// - `_lease` — the wildcard suppression lease. Dropping the snapshot
+/// ends suppression. Held inside `Option` so `detect()` can take it
+/// and drop early.
+pub struct Snapshot {
+ window_ids: HashSet<u32>,
+ front_pid: Option<i32>,
+ _lease: Option<SuppressionLease>,
+}
+
+/// Result of `detect()` — what changed during the action window.
+#[derive(Debug, Clone)]
+pub struct Changes {
+ pub new_windows: Vec<WindowEvent>,
+ pub foreground_changed: bool,
+}
+
+impl Changes {
+ pub fn no_change() -> Self {
+ Self {
+ new_windows: Vec::new(),
+ foreground_changed: false,
+ }
+ }
+
+ /// True when we found evidence that the action triggered a cross-app
+ /// side-effect that required (or would have required) a foreground
+ /// restore. Matches Swift's `Changes.needsRestore`.
+ pub fn needs_restore(&self) -> bool {
+ self.foreground_changed || !self.new_windows.is_empty()
+ }
+
+ /// One-liner summary to append to a tool result, or empty string
+ /// when nothing interesting happened.
+ ///
+ /// Format mirrors Swift `WindowChangeDetector.Changes.resultSuffix`
+ /// **verbatim** so MCP callers that key off the suffix wording
+ /// don't need a per-binary special case.
+ pub fn result_suffix(&self) -> String {
+ if !self.needs_restore() {
+ return String::new();
+ }
+
+ if !self.new_windows.is_empty() {
+ // Group by app name (stable order), join titles per app.
+ let mut by_app: std::collections::BTreeMap<&str, Vec<&str>> =
+ std::collections::BTreeMap::new();
+ for w in &self.new_windows {
+ by_app.entry(&w.app_name).or_default().push(&w.title);
+ }
+ let summaries: Vec<String> = by_app
+ .into_iter()
+ .map(|(app, titles)| {
+ let titles: Vec<String> = titles
+ .into_iter()
+ .filter(|t| !t.is_empty())
+ .map(|t| format!("\"{t}\""))
+ .collect();
+ if titles.is_empty() {
+ app.to_string()
+ } else {
+ format!("{app} ({})", titles.join(", "))
+ }
+ })
+ .collect();
+ format!(
+ "\n\n🪟 Action opened new window(s): {}.",
+ summaries.join("; ")
+ )
+ } else {
+ "\n\n🔀 Action caused a different app to become frontmost.".to_string()
+ }
+ }
+}
+
+/// Default poll deadline — new windows triggered by a click typically
+/// appear within ~200ms on macOS; 1.0s gives the wildcard suppressor
+/// time to fire and settle.
+const DEFAULT_TIMEOUT: Duration = Duration::from_millis(1000);
+
+/// Default inter-poll interval. Matches Swift's 50ms.
+const DEFAULT_POLL_INTERVAL: Duration = Duration::from_millis(50);
+
+/// Public API. Mirrors Swift `enum WindowChangeDetector` — no state of
+/// its own; all state lives inside the returned `Snapshot`.
+pub struct WindowChangeDetector;
+
+impl WindowChangeDetector {
+ /// Capture the current window set + frontmost pid and arm the
+ /// wildcard focus-steal suppressor. Call immediately before
+ /// dispatching the action.
+ ///
+ /// `prior_front` is the frontmost pid the **caller** already
+ /// observed — typically captured one line earlier via
+ /// `apps::frontmost_pid()` for the surrounding `focus_guard`
+ /// lease. We use the caller's value (not a fresh re-read) so the
+ /// wildcard suppressor's `restore_to` matches what the focus-guard
+ /// lease saw; a race where another app became frontmost between
+ /// the caller's read and this method would otherwise leave the
+ /// two leases targeting different pids.
+ ///
+ /// Returns `Snapshot`. Drop ends suppression (via the held
+ /// `SuppressionLease`); call `Snapshot::detect()` to consume the
+ /// snapshot and get a `Changes` summary.
+ ///
+ /// Safe to call from any thread — `CGWindowListCopyWindowInfo` is
+ /// documented as thread-safe.
+ pub fn snapshot(prior_front: Option<i32>) -> Snapshot {
+ let window_ids: HashSet<u32> = windows::visible_windows()
+ .into_iter()
+ .filter(|w| w.layer == 0)
+ .map(|w| w.window_id)
+ .collect();
+
+ // Arm wildcard suppression — covers snapshot → detect window.
+ // restore_to = caller-captured frontmost; target = wildcard
+ // (any other pid). If there's no frontmost (rare — screensaver,
+ // login window), we skip the lease; foreground-change tracking
+ // still runs.
+ let lease = prior_front.map(|restore_to| {
+ focus_steal::begin_suppression(
+ None, // wildcard
+ restore_to,
+ "WindowChangeDetector.snapshot",
+ )
+ });
+
+ Snapshot {
+ window_ids,
+ front_pid: prior_front,
+ _lease: lease,
+ }
+ }
+}
+
+impl Snapshot {
+ /// Frontmost pid at snapshot time, if any.
+ pub fn front_pid(&self) -> Option<i32> {
+ self.front_pid
+ }
+
+ /// Poll for up to `DEFAULT_TIMEOUT` for new windows or a
+ /// foreground-app change. Returns as soon as a change is detected
+ /// or the timeout elapses.
+ ///
+ /// Consumes the snapshot — the wildcard suppression lease is
+ /// dropped when this returns (covers the full action + detection
+ /// window).
+ pub fn detect(self) -> Changes {
+ self.detect_with(DEFAULT_TIMEOUT, DEFAULT_POLL_INTERVAL)
+ }
+
+ /// Async wrapper around `detect()` — runs the synchronous poll
+ /// loop on a `spawn_blocking` thread so it doesn't stall the
+ /// tokio runtime. Most action-tool call sites should prefer this
+ /// over the blocking `detect()`.
+ pub async fn detect_async(self) -> Changes {
+ // Move the Snapshot (and its embedded lease) onto the blocking
+ // thread; the lease's Drop runs there when detect_with returns.
+ tokio::task::spawn_blocking(move || self.detect())
+ .await
+ .unwrap_or_else(|_| Changes::no_change())
+ }
+
+ /// Same as `detect()` but with configurable timing — exposed for
+ /// tests / callers that want a tighter or looser poll window.
+ pub fn detect_with(self, timeout: Duration, poll_interval: Duration) -> Changes {
+ let deadline = Instant::now() + timeout;
+ loop {
+ std::thread::sleep(poll_interval);
+
+ let current: Vec<WindowInfo> = windows::visible_windows()
+ .into_iter()
+ .filter(|w| w.layer == 0)
+ .collect();
+ let current_ids: HashSet<u32> = current.iter().map(|w| w.window_id).collect();
+
+ let new_windows: Vec<WindowEvent> = current
+ .iter()
+ .filter(|w| !self.window_ids.contains(&w.window_id))
+ .map(|w| WindowEvent {
+ window_id: w.window_id,
+ pid: w.pid,
+ app_name: w.app_name.clone(),
+ title: w.title.clone(),
+ })
+ .collect();
+ // Diff the other direction too — keeps unit tests honest
+ // even though Swift's result_suffix only uses opened windows.
+ let _closed: Vec<u32> = self
+ .window_ids
+ .iter()
+ .copied()
+ .filter(|id| !current_ids.contains(id))
+ .collect();
+
+ let current_front = apps::frontmost_pid();
+ let foreground_changed = match (self.front_pid, current_front) {
+ (Some(orig), Some(cur)) => orig != cur,
+ _ => false,
+ };
+
+ if !new_windows.is_empty() || foreground_changed {
+ return Changes {
+ new_windows,
+ foreground_changed,
+ };
+ }
+ if Instant::now() >= deadline {
+ return Changes::no_change();
+ }
+ }
+ }
+
+ // ── Internal helpers — also used by unit tests via the `pub(super)`
+ // path so the diff logic can be exercised without driving the live
+ // window enumerator. ────────────────────────────────────────────
+
+ /// Pure-function diff: given the snapshot's window-id set + a
+ /// list of currently-visible windows, return the (opened, closed)
+ /// classification.
+ pub(crate) fn diff(
+ snapshot_ids: &HashSet<u32>,
+ current: &[WindowInfo],
+ ) -> (Vec<WindowEvent>, Vec<u32>) {
+ let current_ids: HashSet<u32> = current.iter().map(|w| w.window_id).collect();
+ let opened: Vec<WindowEvent> = current
+ .iter()
+ .filter(|w| !snapshot_ids.contains(&w.window_id))
+ .map(|w| WindowEvent {
+ window_id: w.window_id,
+ pid: w.pid,
+ app_name: w.app_name.clone(),
+ title: w.title.clone(),
+ })
+ .collect();
+ let closed: Vec<u32> = snapshot_ids
+ .iter()
+ .copied()
+ .filter(|id| !current_ids.contains(id))
+ .collect();
+ (opened, closed)
+ }
+}
+
+// ── Tests ────────────────────────────────────────────────────────────────────
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+ use crate::windows::WindowBounds;
+
+ fn win(id: u32, pid: i32, app: &str, title: &str) -> WindowInfo {
+ WindowInfo {
+ window_id: id,
+ pid,
+ app_name: app.into(),
+ title: title.into(),
+ bounds: WindowBounds {
+ x: 0.,
+ y: 0.,
+ width: 100.,
+ height: 100.,
+ },
+ layer: 0,
+ z_index: 0,
+ is_on_screen: true,
+ on_current_space: None,
+ space_ids: None,
+ }
+ }
+
+ #[test]
+ fn diff_finds_opened_window() {
+ let snap: HashSet<u32> = [1, 2].into_iter().collect();
+ let cur = vec![
+ win(1, 100, "Safari", "Home"),
+ win(2, 100, "Safari", "Tab2"),
+ win(3, 101, "Mail", "Inbox"),
+ ];
+ let (opened, closed) = Snapshot::diff(&snap, &cur);
+ assert_eq!(opened.len(), 1);
+ assert_eq!(opened[0].window_id, 3);
+ assert_eq!(opened[0].app_name, "Mail");
+ assert_eq!(opened[0].title, "Inbox");
+ assert!(closed.is_empty());
+ }
+
+ #[test]
+ fn diff_finds_closed_window() {
+ let snap: HashSet<u32> = [1, 2, 3].into_iter().collect();
+ let cur = vec![win(1, 100, "Safari", "Home")];
+ let (opened, closed) = Snapshot::diff(&snap, &cur);
+ assert!(opened.is_empty());
+ assert_eq!(closed.len(), 2);
+ let closed_set: HashSet<u32> = closed.into_iter().collect();
+ assert!(closed_set.contains(&2));
+ assert!(closed_set.contains(&3));
+ }
+
+ #[test]
+ fn diff_no_change() {
+ let snap: HashSet<u32> = [1, 2].into_iter().collect();
+ let cur = vec![win(1, 100, "Safari", "A"), win(2, 100, "Safari", "B")];
+ let (opened, closed) = Snapshot::diff(&snap, &cur);
+ assert!(opened.is_empty());
+ assert!(closed.is_empty());
+ }
+
+ #[test]
+ fn changes_result_suffix_no_change_is_empty() {
+ let c = Changes::no_change();
+ assert_eq!(c.result_suffix(), "");
+ assert!(!c.needs_restore());
+ }
+
+ #[test]
+ fn changes_result_suffix_single_new_window_with_title() {
+ let c = Changes {
+ new_windows: vec![WindowEvent {
+ window_id: 99,
+ pid: 100,
+ app_name: "Chrome".into(),
+ title: "New Tab".into(),
+ }],
+ foreground_changed: false,
+ };
+ assert!(c.needs_restore());
+ assert_eq!(
+ c.result_suffix(),
+ "\n\n🪟 Action opened new window(s): Chrome (\"New Tab\")."
+ );
+ }
+
+ #[test]
+ fn changes_result_suffix_groups_windows_by_app() {
+ let c = Changes {
+ new_windows: vec![
+ WindowEvent {
+ window_id: 1,
+ pid: 100,
+ app_name: "Chrome".into(),
+ title: "Tab A".into(),
+ },
+ WindowEvent {
+ window_id: 2,
+ pid: 100,
+ app_name: "Chrome".into(),
+ title: "Tab B".into(),
+ },
+ WindowEvent {
+ window_id: 3,
+ pid: 101,
+ app_name: "Mail".into(),
+ title: "".into(),
+ },
+ ],
+ foreground_changed: true,
+ };
+ let suffix = c.result_suffix();
+ // BTreeMap sort order is alphabetical by app name → Chrome before Mail.
+ assert_eq!(
+ suffix,
+ "\n\n🪟 Action opened new window(s): Chrome (\"Tab A\", \"Tab B\"); Mail."
+ );
+ }
+
+ #[test]
+ fn changes_result_suffix_foreground_change_only() {
+ let c = Changes {
+ new_windows: vec![],
+ foreground_changed: true,
+ };
+ assert!(c.needs_restore());
+ assert_eq!(
+ c.result_suffix(),
+ "\n\n🔀 Action caused a different app to become frontmost."
+ );
+ }
+
+ #[test]
+ fn changes_result_suffix_empty_title_is_dropped() {
+ let c = Changes {
+ new_windows: vec![WindowEvent {
+ window_id: 1,
+ pid: 100,
+ app_name: "Finder".into(),
+ title: "".into(),
+ }],
+ foreground_changed: false,
+ };
+ // No title → just the app name, no parentheses.
+ assert_eq!(c.result_suffix(), "\n\n🪟 Action opened new window(s): Finder.");
+ }
+
+ /// Regression: `snapshot(prior_front)` must store the caller's
+ /// captured front pid verbatim (rather than re-reading it inside
+ /// the function and racing with concurrent activations).
+ #[test]
+ fn snapshot_stores_caller_prior_front() {
+ // Use an obviously bogus pid so we'd notice if the impl silently
+ // fell back to the live frontmost on this test runner.
+ let bogus_prior = Some(424242_i32);
+ let snap = WindowChangeDetector::snapshot(bogus_prior);
+ assert_eq!(snap.front_pid(), bogus_prior);
+
+ // None must round-trip too — and must skip the lease without
+ // panicking (no frontmost to restore to).
+ let snap_none = WindowChangeDetector::snapshot(None);
+ assert_eq!(snap_none.front_pid(), None);
+ }
+}