Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.
Rust agentai-agentapplecomputer-usecomputer-use-agentcontainerizationcuadesktop-automationhacktoberfestlumemacosmanusoperatorswiftvirtualizationvirtualization-frameworkwindowswindows-sandbox
// SPDX-License-Identifier: MIT
// Copyright (c) 2026 Cua AI, Inc.
//! X11 foreground steps (`delivery_mode:"foreground"`) that
//! [`crate::interaction::with_x11_foreground`] runs.
//!
//! A foreground action behaves like a user at the keyboard: activate + raise the
//! target toplevel, wait until the window manager confirms that it is the
//! active window AND that the core X input focus sits inside it, then inject
//! real input (XTest) and report where focus ended up. Pointer and key actions
//! leave the target active afterwards — restoring the previously active window
//! would pop down any menu the click just opened and would move keyboard focus
//! away from the widget a following `type_text` needs. `type_text` restores
//! the prior active window once its text is in.
//!
//! Everything here is bounded: the activation/confirmation phase and the
//! post-check run on watchdog threads with hard deadlines, so a wedged X
//! server, a client holding a server grab, or a window that never takes focus
//! yields a structured `foreground_timeout` / `foreground_unavailable` error
//! instead of a hung tool call. Only x11rb (a pure-Rust, thread-safe client)
//! is used: protocol errors come back as `Result`s rather than going through
//! Xlib's process-wide error handler.
use crate::interaction::operation_deadline;
use anyhow::{anyhow, Result};
use cua_driver_core::window_observation::WindowObservationBounds;
use std::sync::mpsc;
use std::time::{Duration, Instant};
use x11rb::connection::Connection as _;
use x11rb::protocol::xproto::{
AtomEnum, ClientMessageEvent, ConnectionExt as _, CreateWindowAux, EventMask, InputFocus,
PropMode, Window, WindowClass, CLIENT_MESSAGE_EVENT,
};
use x11rb::protocol::Event;
use x11rb::rust_connection::RustConnection;
use x11rb::COPY_DEPTH_FROM_PARENT;
/// Error-code prefixes carried in the `anyhow` message (`<code>: <detail>`)
/// so tool handlers can attach a structured `code` without a bespoke error type.
pub const CODE_UNAVAILABLE: &str = "foreground_unavailable";
pub const CODE_TIMEOUT: &str = "foreground_timeout";
/// Tunables for one foreground transaction.
#[derive(Clone, Copy, Debug)]
pub struct ForegroundOptions {
/// How long to wait for the WM to confirm activation + input focus.
pub settle: Duration,
/// Whether the body injects keyboard input. Keyboard delivery is routed by
/// the X input focus, so the post-check is reported for it.
pub keyboard: bool,
/// The process the caller resolved the target window to. The post-check
/// otherwise reads `_NET_WM_PID` off the window itself, which an
/// override-redirect popup (a LibreOffice VCL menu) never carries — and
/// which is gone by the post-check when the click closed it.
pub target_pid: Option<u32>,
}
impl ForegroundOptions {
/// Pointer actions land by stacking; a short confirmation suffices.
pub fn pointer() -> Self {
Self {
settle: Duration::from_millis(800),
keyboard: false,
target_pid: None,
}
}
/// Keyboard actions need the input focus, which GTK/VCL toplevels accept a
/// beat after being raised; give them a real budget.
pub fn keyboard() -> Self {
Self {
settle: Duration::from_millis(1500),
keyboard: true,
target_pid: None,
}
}
/// Name the process the target window belongs to (see `target_pid`).
pub fn for_pid(mut self, pid: u32) -> Self {
self.target_pid = Some(pid);
self
}
}
/// Where the X input focus was after the body ran.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum FocusAfter {
/// Inside the target toplevel.
Target,
/// Inside another toplevel owned by the same process (a dialog opened or
/// closed, a new document window, ...).
SamePid,
/// Somewhere else entirely.
Elsewhere,
/// Could not be determined before the post-check deadline.
Unknown,
}
impl FocusAfter {
pub fn as_str(self) -> &'static str {
match self {
Self::Target => "target",
Self::SamePid => "same_pid",
Self::Elsewhere => "elsewhere",
Self::Unknown => "unknown",
}
}
}
/// What the transaction observed; surfaced in tool structured content.
#[derive(Clone, Debug)]
pub struct ForegroundReport {
/// The target was already active and focused; no activation was sent.
pub already_active: bool,
/// Activation had to be re-sent once before the WM confirmed it.
pub retried_activation: bool,
/// Milliseconds from start until activation + focus were confirmed.
pub confirm_ms: u64,
/// Focus location after the body.
pub focus_after: FocusAfter,
/// Toplevels of the target's process (managed windows and popup menus)
/// that appeared or vanished between the activation and the post-check:
/// a menu opened, a dialog mapped or closed. `None` when nothing changed
/// or the observation was unavailable.
pub window_change: Option<String>,
/// A window in `window_change` is positively attributed to the target
/// process: its pid was known and the window resolved to it. The window
/// set also lists override-redirect popups that name no pid (a VCL menu,
/// but equally another client's popup) and, when the target pid is
/// unknown, every on-screen window; a change among those alone is not
/// the target's own.
pub window_change_owned: bool,
}
impl ForegroundReport {
pub fn to_json(&self) -> serde_json::Value {
let mut v = serde_json::json!({
"activated": !self.already_active,
"retried_activation": self.retried_activation,
"confirm_ms": self.confirm_ms,
"focus_after": self.focus_after.as_str(),
});
if let Some(change) = &self.window_change {
v["window_change"] = serde_json::json!(change);
}
v
}
/// Focus is proven to have stayed inside the target process after the
/// body ran (the target toplevel itself, or a dialog/popup it owns).
pub fn focus_kept(&self) -> bool {
matches!(self.focus_after, FocusAfter::Target | FocusAfter::SamePid)
}
/// The window change confirms the action wherever the focus ended up
/// when the changed window is the target process's own (a dialog closed
/// by its own OK button takes the focus with it); a change among
/// unattributed windows only counts while the focus stayed in the
/// target process.
pub fn window_change_confirms(&self) -> bool {
self.window_change.is_some() && (self.window_change_owned || self.focus_kept())
}
}
/// One on-screen toplevel of a window set read for a before/after diff.
#[derive(Clone, Debug)]
struct WindowEntry {
window: u64,
description: String,
/// Positively attributed to the target pid (see
/// [`ForegroundReport::window_change_owned`]).
owned: bool,
}
/// What changed between two window sets.
#[derive(Clone, Debug, PartialEq, Eq)]
struct WindowChange {
summary: String,
owned: bool,
}
/// The on-screen toplevels of `pid` (managed windows plus override-redirect
/// popups) for a before/after diff. Managed windows are listed by resolved
/// owner, so they are `owned` whenever `pid` is known; a popup is `owned`
/// only when it carries `pid` itself.
fn pid_window_set(pid: Option<u32>) -> Vec<WindowEntry> {
let mut set: Vec<WindowEntry> = crate::x11::list_windows(pid)
.into_iter()
.filter(|w| w.is_on_screen)
.map(|w| {
let title = if w.title.is_empty() {
String::new()
} else {
format!(" \"{}\"", w.title)
};
WindowEntry {
window: w.xid,
description: format!("window {}{title}", w.xid),
owned: pid.is_some(),
}
})
.collect();
set.extend(
super::mapped_popup_windows()
.into_iter()
.filter(|p| pid.is_none() || p.pid.is_none() || p.pid == pid)
.map(|p| WindowEntry {
window: p.window,
description: p.describe(),
owned: pid.is_some() && p.pid == pid,
}),
);
set
}
/// Describe what changed between two window sets, or `None` when nothing did.
fn describe_window_change(before: &[WindowEntry], after: &[WindowEntry]) -> Option<WindowChange> {
let absent_from =
|set: &[WindowEntry], entry: &WindowEntry| !set.iter().any(|e| e.window == entry.window);
let appeared: Vec<&WindowEntry> = after.iter().filter(|e| absent_from(before, e)).collect();
let vanished: Vec<&WindowEntry> = before.iter().filter(|e| absent_from(after, e)).collect();
if appeared.is_empty() && vanished.is_empty() {
return None;
}
let join = |entries: &[&WindowEntry]| {
entries
.iter()
.map(|e| e.description.as_str())
.collect::<Vec<_>>()
.join(", ")
};
let mut parts = Vec::new();
if !appeared.is_empty() {
parts.push(format!("appeared: {}", join(&appeared)));
}
if !vanished.is_empty() {
parts.push(format!("closed: {}", join(&vanished)));
}
Some(WindowChange {
summary: parts.join("; "),
owned: appeared.iter().chain(&vanished).any(|e| e.owned),
})
}
/// How often the target process's window set is re-read after the body.
const WINDOW_CHANGE_POLL: Duration = Duration::from_millis(50);
/// How long a toolkit gets to map a menu / dialog after the body before the
/// window set is declared unchanged. GTK / VCL menus and dialogs map within
/// ~100 ms of the click; a Qt file dialog (VLC "Add...", "Convert / Save")
/// takes 300-600 ms, which a fixed 150 ms settle reported as no change.
const WINDOW_CHANGE_DEADLINE: Duration = Duration::from_millis(800);
/// After the first change is seen, a beat for the new window's title
/// (`_NET_WM_NAME` arrives a moment after the map) so the summary names it.
const WINDOW_CHANGE_TITLE_GRACE: Duration = Duration::from_millis(60);
/// How long the post-check retries a core focus that says nothing about
/// where input went: `None` / `PointerRoot`, or a window of the window
/// manager's own X client. A popup destroyed by the click leaves the focus
/// unset for a beat before the toolkit re-focuses its toplevel, and mutter
/// parks the focus on its `no_focus_window` while it picks the next window
/// after a dialog closes (measured on GNOME 42: from ~500 ms after the close
/// for ~200 ms).
const FOCUS_RETRY: Duration = Duration::from_millis(500);
/// Post-action observation bounds: `WINDOW_CHANGE_DEADLINE` /
/// `WINDOW_CHANGE_POLL` unless the embedding host set
/// `CUA_DRIVER_WINDOW_CHANGE_TIMEOUT_MS` / `CUA_DRIVER_WINDOW_CHANGE_POLL_MS`
/// on the daemon environment (shared parsing with macOS in
/// `cua_driver_core::window_observation`).
fn window_change_bounds() -> WindowObservationBounds {
WindowObservationBounds::from_env(WINDOW_CHANGE_DEADLINE, WINDOW_CHANGE_POLL)
}
/// Poll `pid`'s window set until it differs from `before` or the deadline
/// passes. Returns the last set read and the change description, if any.
///
/// A zero timeout reads the set once (the post-check still needs it to
/// recognise focus inside a popup of the target process) and reports no
/// change, so the action falls back to `unverifiable` rather than claiming
/// `confirmed` window-change evidence it never looked for.
fn wait_for_window_change(
pid: Option<u32>,
before: &[WindowEntry],
bounds: WindowObservationBounds,
deadline: Instant,
) -> (Vec<WindowEntry>, Option<WindowChange>) {
if bounds.skips_observation() {
return (pid_window_set(pid), None);
}
loop {
let after = pid_window_set(pid);
if let Some(change) = describe_window_change(before, &after) {
std::thread::sleep(remaining(deadline).min(WINDOW_CHANGE_TITLE_GRACE));
let settled = pid_window_set(pid);
return match describe_window_change(before, &settled) {
Some(change) => (settled, Some(change)),
None => (after, Some(change)),
};
}
if Instant::now() >= deadline {
return (after, None);
}
std::thread::sleep(remaining(deadline).min(bounds.poll));
}
}
/// Extract the structured code prefix from a foreground error message.
pub fn error_code(error: &anyhow::Error) -> Option<&'static str> {
let text = error.to_string();
if text.starts_with(CODE_TIMEOUT) {
Some(CODE_TIMEOUT)
} else if text.starts_with(CODE_UNAVAILABLE) {
Some(CODE_UNAVAILABLE)
} else {
None
}
}
/// Run `f` on a detached thread and wait at most `deadline` for its result.
///
/// All current callers (`confirm_phase`, `wait_for_window_change`,
/// `post_check`) already bound themselves cooperatively with their own
/// internal deadline loop, so in the common case the worker returns well
/// inside `deadline` and this wrapper's timeout never fires. The residual
/// leak this guards against is a single blocking X11 socket call (connect,
/// or a request/reply round trip inside `X11::open`/`activate`) hanging past
/// `deadline` because the X server itself has stopped answering — a
/// synchronous X11 read cannot be interrupted or polled from the outside
/// without switching the whole call chain to non-blocking I/O, which is out
/// of scope here. In that rare case the thread is intentionally leaked: it
/// is bounded (it exits as soon as the stalled X call returns, or the
/// process exits), and its completion is harmless because `tx.send` below
/// ignores a disconnected receiver (`let _ =`) rather than panicking, so a
/// late result from a leaked thread is silently dropped instead of crashing
/// the caller that already moved on.
fn run_with_deadline<T: Send + 'static>(
deadline: Instant,
f: impl FnOnce() -> T + Send + 'static,
) -> Option<T> {
let (tx, rx) = mpsc::channel();
std::thread::Builder::new()
.name("cua-x11-foreground".into())
.spawn(move || {
let _ = tx.send(f());
})
.ok()?;
rx.recv_timeout(remaining(deadline)).ok()
}
fn remaining(deadline: Instant) -> Duration {
deadline.saturating_duration_since(Instant::now())
}
struct X11 {
conn: RustConnection,
root: Window,
net_active_window: u32,
net_wm_pid: u32,
resource_id_mask: u32,
/// The window manager's `_NET_SUPPORTING_WM_CHECK` window, when one is
/// advertised: any window sharing its X client base belongs to the WM.
wm_check_window: Option<Window>,
}
/// Whether two X resource ids were allocated by the same client: the server
/// hands each client a base and lets it fill in the bits under
/// `resource_id_mask`.
fn same_x11_client(a: Window, b: Window, resource_id_mask: u32) -> bool {
a & !resource_id_mask == b & !resource_id_mask
}
impl X11 {
fn open() -> Result<Self> {
let (conn, screen) = RustConnection::connect(None).map_err(|e| {
anyhow!("{CODE_UNAVAILABLE}: cannot open DISPLAY to verify X11 input focus: {e}")
})?;
super::action::fence(conn.stream())?;
let root = conn.setup().roots[screen].root;
let resource_id_mask = conn.setup().resource_id_mask;
let net_active_window = conn
.intern_atom(false, b"_NET_ACTIVE_WINDOW")?
.reply()?
.atom;
let net_wm_pid = conn.intern_atom(false, b"_NET_WM_PID")?.reply()?.atom;
let wm_check = conn
.intern_atom(false, b"_NET_SUPPORTING_WM_CHECK")?
.reply()?
.atom;
let wm_check_window = conn
.get_property(false, root, wm_check, AtomEnum::WINDOW, 0, 1)
.ok()
.and_then(|cookie| cookie.reply().ok())
.and_then(|reply| reply.value32()?.next())
.filter(|w| *w != 0);
Ok(Self {
conn,
root,
net_active_window,
net_wm_pid,
resource_id_mask,
wm_check_window,
})
}
/// The focus sits on a window the window manager created for itself
/// (mutter's `no_focus_window` between two focused clients): a parking
/// spot, not a destination.
fn held_by_window_manager(&self, focused: Window) -> bool {
self.wm_check_window
.is_some_and(|check| same_x11_client(focused, check, self.resource_id_mask))
}
fn active_window(&self) -> Option<Window> {
let reply = self
.conn
.get_property(
false,
self.root,
self.net_active_window,
AtomEnum::WINDOW,
0,
1,
)
.ok()?
.reply()
.ok()?;
let value = reply.value32()?.next();
value.filter(|w| *w != 0)
}
fn window_pid(&self, window: Window) -> Option<u32> {
let reply = self
.conn
.get_property(false, window, self.net_wm_pid, AtomEnum::CARDINAL, 0, 1)
.ok()?
.reply()
.ok()?;
let value = reply.value32()?.next();
value.filter(|p| *p != 0)
}
/// Current server time via the PropertyNotify round-trip. `_NET_ACTIVE_WINDOW`
/// stamped `CurrentTime` (0) loses to focus-stealing prevention whenever any
/// newer user input exists. Bounded: falls back to 0 after 300 ms or at
/// `deadline`.
fn server_time(&self, deadline: Instant) -> u32 {
let probe = match self.conn.generate_id() {
Ok(id) => id,
Err(_) => return 0,
};
let aux = CreateWindowAux::new().event_mask(EventMask::PROPERTY_CHANGE);
if self
.conn
.create_window(
COPY_DEPTH_FROM_PARENT,
probe,
self.root,
-1,
-1,
1,
1,
0,
WindowClass::INPUT_OUTPUT,
0,
&aux,
)
.is_err()
{
return 0;
}
let _ = x11rb::protocol::xproto::change_property(
&self.conn,
PropMode::REPLACE,
probe,
self.net_wm_pid,
AtomEnum::STRING,
8,
1,
&[0u8],
);
let _ = self.conn.flush();
let deadline = deadline.min(Instant::now() + Duration::from_millis(300));
let mut time = 0;
while Instant::now() < deadline {
match self.conn.poll_for_event() {
Ok(Some(Event::PropertyNotify(e))) if e.window == probe => {
time = e.time;
break;
}
Ok(Some(_)) => continue,
Ok(None) => std::thread::sleep(remaining(deadline).min(Duration::from_millis(5))),
Err(_) => break,
}
}
let _ = self.conn.destroy_window(probe);
let _ = self.conn.flush();
time
}
fn activate(&self, target: Window, prior: Window, deadline: Instant) -> Result<()> {
let time = self.server_time(deadline);
let event =
ClientMessageEvent::new(32, target, self.net_active_window, [2, time, prior, 0, 0]);
debug_assert_eq!(event.response_type, CLIENT_MESSAGE_EVENT);
super::action::admit(|| {
self.conn.send_event(
false,
self.root,
EventMask::SUBSTRUCTURE_REDIRECT | EventMask::SUBSTRUCTURE_NOTIFY,
event,
)
})??;
// Set the core focus explicitly as well (what `xdotool windowactivate`
// does): WMs with focus-stealing prevention honour `_NET_ACTIVE_WINDOW`
// as raise-only. BadMatch on a not-yet-viewable window is expected and
// ignored; the confirmation loop decides.
if let Ok(cookie) =
self.conn
.set_input_focus(InputFocus::PARENT, target, x11rb::CURRENT_TIME)
{
let _ = cookie.check();
}
self.conn.flush()?;
Ok(())
}
fn focused(&self) -> Option<Window> {
self.conn
.get_input_focus()
.ok()?
.reply()
.ok()
.map(|r| r.focus)
.filter(|f| *f > 1) // 0 = None, 1 = PointerRoot
}
/// Whether `focused` is `target` or one of its descendants.
fn is_within(&self, mut focused: Window, target: Window) -> bool {
for _ in 0..64 {
if focused == target {
return true;
}
if focused == 0 || focused == self.root {
return false;
}
let Ok(cookie) = self.conn.query_tree(focused) else {
return false;
};
let Ok(reply) = cookie.reply() else {
return false;
};
if reply.parent == 0 || reply.parent == focused {
return false;
}
focused = reply.parent;
}
false
}
/// Walk up from `window` to the first ancestor carrying `_NET_WM_PID`.
fn owning_pid(&self, window: Window) -> Option<u32> {
self.ancestors(window)
.find_map(|window| self.window_pid(window))
}
/// `window` and its ancestors below the root (bounded).
fn ancestors(&self, window: Window) -> impl Iterator<Item = Window> + '_ {
std::iter::successors(Some(window), move |&window| {
let parent = self.conn.query_tree(window).ok()?.reply().ok()?.parent;
(parent != 0 && parent != self.root && parent != window).then_some(parent)
})
.take(64)
}
/// First `WM_CLASS` class (else instance) name on `window` or one of its
/// ancestors.
fn wm_class(&self, window: Window) -> Option<String> {
self.ancestors(window).find_map(|window| {
let (instance, class) = crate::x11::get_window_class(&self.conn, window)?;
Some(if class.is_empty() { instance } else { class })
})
}
/// Who holds the X input focus, for a refusal that has to explain why the
/// target could not take it.
fn focus_holder(&self) -> String {
let focus = self
.conn
.get_input_focus()
.ok()
.and_then(|cookie| cookie.reply().ok())
.map(|reply| reply.focus);
let Some(focus) = focus else {
return "unknown".into();
};
let pid = (focus > 1).then(|| self.owning_pid(focus)).flatten();
let comm = pid.and_then(|pid| {
std::fs::read_to_string(format!("/proc/{pid}/comm"))
.ok()
.map(|comm| comm.trim().to_owned())
});
let class = (focus > 1).then(|| self.wm_class(focus)).flatten();
describe_focus_holder(focus, class.as_deref(), pid, comm.as_deref())
}
fn focus_is_within(&self, target: Window) -> bool {
match self.focused() {
Some(f) => self.is_within(f, target),
None => false,
}
}
}
struct ConfirmOutcome {
confirmed: bool,
already_active: bool,
retried: bool,
elapsed: Duration,
active_after: Window,
focus_within: bool,
/// Set when the activation was not confirmed: see [`X11::focus_holder`].
focus_holder: Option<String>,
}
fn confirmed(target: Window, active: Option<Window>, focus_within: bool) -> bool {
crate::interaction::policy::focused(
&target,
&crate::interaction::facts::Fact::Known(active.filter(|_| focus_within)),
)
}
fn confirm_phase(target: Window, deadline: Instant) -> Result<ConfirmOutcome> {
let x = X11::open()?;
let start = Instant::now();
let prior = x.active_window().unwrap_or(0);
let mut retried = false;
// Already active and focused: leave the window (and any open menu / grab)
// untouched — re-activating is what popped GTK menus back down.
if confirmed(target, Some(prior), x.focus_is_within(target)) {
return Ok(ConfirmOutcome {
confirmed: true,
already_active: true,
retried: false,
elapsed: start.elapsed(),
active_after: target,
focus_within: true,
focus_holder: None,
});
}
x.activate(target, prior, deadline)?;
let retry_at = start + deadline.saturating_duration_since(start).mul_f32(0.4);
let mut retry_pending = true;
loop {
let focus_within = x.focus_is_within(target);
if confirmed(target, x.active_window(), focus_within) {
return Ok(ConfirmOutcome {
confirmed: true,
already_active: false,
retried,
elapsed: start.elapsed(),
active_after: target,
focus_within: true,
focus_holder: None,
});
}
let now = Instant::now();
if now >= deadline {
return Ok(ConfirmOutcome {
confirmed: false,
already_active: false,
retried,
elapsed: start.elapsed(),
active_after: x.active_window().unwrap_or(0),
focus_within,
focus_holder: Some(x.focus_holder()),
});
}
if retry_pending && now >= retry_at {
retry_pending = false;
retried = true;
x.activate(target, x.active_window().unwrap_or(0), deadline)?;
}
std::thread::sleep(remaining(deadline).min(Duration::from_millis(15)));
}
}
/// Poll `read_focus` until it names a window that is not a parking spot
/// (`read_focus` already drops `None` / `PointerRoot`; `parked` marks the
/// window manager's own windows) or `deadline` passes.
fn await_focus_destination(
deadline: Instant,
mut read_focus: impl FnMut() -> Option<Window>,
parked: impl Fn(Window) -> bool,
) -> Option<Window> {
loop {
if let Some(focused) = read_focus().filter(|f| !parked(*f)) {
return Some(focused);
}
if Instant::now() >= deadline {
return None;
}
std::thread::sleep(remaining(deadline).min(Duration::from_millis(25)));
}
}
/// Where the focus sits after the body. `pid_windows` is the target
/// process's window set read after the body (managed windows and popups):
/// focus inside any of them is `SamePid` even when neither the target nor
/// the focused window carries `_NET_WM_PID` (a VCL popup menu closed by the
/// click, the popup that the click opened). A focus that is unset or parked
/// on the window manager's own window for the whole `FOCUS_RETRY` is
/// `Unknown`: it names no client the input could have reached.
fn post_check(
target: Window,
target_pid: Option<u32>,
pid_windows: &[WindowEntry],
deadline: Instant,
) -> FocusAfter {
let Ok(x) = X11::open() else {
return FocusAfter::Unknown;
};
let Some(focused) = await_focus_destination(
deadline,
|| x.focused(),
|focused| x.held_by_window_manager(focused),
) else {
return FocusAfter::Unknown;
};
crate::interaction::policy::focus_after(
x.is_within(focused, target),
pid_windows
.iter()
.any(|entry| x.is_within(focused, entry.window as Window)),
target_pid.or_else(|| x.owning_pid(target)),
x.owning_pid(focused),
)
}
/// The target window confirmed active and focused, with the target
/// process's window set read before the body for [`Activated::report`].
pub struct Activated {
target: Window,
target_pid: Option<u32>,
outcome: ConfirmOutcome,
windows_before: Vec<WindowEntry>,
}
/// Activate `xid` and read back that it holds the active window + input
/// focus within `opts.settle`, capped by the action's deadline. Returns `foreground_unavailable` (no input
/// sent) when the WM never confirms, and `foreground_timeout` when the X
/// server stops answering.
pub fn activate(xid: u64, opts: ForegroundOptions) -> Result<Activated> {
let target = xid as Window;
let started = Instant::now();
let settle = operation_deadline(opts.settle);
let phase = operation_deadline(opts.settle + Duration::from_millis(1500));
let outcome =
run_with_deadline(phase, move || confirm_phase(target, settle)).ok_or_else(|| {
anyhow!(
"{CODE_TIMEOUT}: the X server did not answer the activation of window \
0x{xid:x} within {:?}; no input was sent",
started.elapsed()
)
})??;
if !outcome.confirmed {
let holder = outcome.focus_holder.as_deref().unwrap_or("unknown");
let cause = if outcome.active_after == 0 {
"No window is active at all: the window manager has not set \
_NET_ACTIVE_WINDOW (it may be restarting, or showing a modal surface of \
its own that no window list includes)"
} else {
"The window may be minimized, on another workspace, or blocked by a modal \
dialog — bring_to_front it or target that dialog instead"
};
return Err(anyhow!(
"{CODE_UNAVAILABLE}: window 0x{xid:x} did not become the active, focused \
window within {:?} (active=0x{:x}, focus_within_target={}, \
input focus: {holder}); no input was sent. {cause}",
outcome.elapsed,
outcome.active_after,
outcome.focus_within
));
}
let target_pid = crate::x11::window_pid(xid).or(opts.target_pid);
Ok(Activated {
target,
target_pid,
outcome,
windows_before: pid_window_set(target_pid),
})
}
impl Activated {
/// Where focus and the target process's window set ended up once the
/// body ran.
pub fn report(self) -> ForegroundReport {
let Activated {
target,
target_pid,
outcome,
windows_before,
} = self;
// The post-check is what the tool reports as evidence for both keyboard
// and pointer bodies: a real click that opened a menu or a dialog moves
// the window set / focus within the target's process, and one that
// landed elsewhere moves focus out of it. The window set is polled
// rather than read after a fixed settle: it returns on the first change.
let bounds = window_change_bounds();
let observed = operation_deadline(bounds.timeout);
let (windows_after, window_change) = run_with_deadline(
operation_deadline(
bounds.timeout
+ bounds.poll
+ WINDOW_CHANGE_TITLE_GRACE
+ Duration::from_millis(1500),
),
move || wait_for_window_change(target_pid, &windows_before, bounds, observed),
)
.unwrap_or((Vec::new(), None));
let focus_retry = operation_deadline(FOCUS_RETRY);
let focus_after =
run_with_deadline(operation_deadline(Duration::from_millis(1500)), move || {
post_check(target, target_pid, &windows_after, focus_retry)
})
.unwrap_or(FocusAfter::Unknown);
ForegroundReport {
already_active: outcome.already_active,
retried_activation: outcome.retried,
confirm_ms: outcome.elapsed.as_millis() as u64,
focus_after,
window_change_owned: window_change.as_ref().is_some_and(|c| c.owned),
window_change: window_change.map(|c| c.summary),
}
}
}
/// `0x…` plus what owns it: the class and process of a client window, or a
/// note that the focus sits on a window no client claims (the window
/// manager's own, or the root).
fn describe_focus_holder(
focus: Window,
class: Option<&str>,
pid: Option<u32>,
comm: Option<&str>,
) -> String {
match focus {
0 => return "none".into(),
1 => return "PointerRoot".into(),
_ => {}
}
let owner = match (pid, comm) {
(Some(pid), Some(comm)) => format!("pid {pid} {comm}"),
(Some(pid), None) => format!("pid {pid}"),
_ => "no _NET_WM_PID".into(),
};
match class {
Some(class) => format!("0x{focus:x} ({class}, {owner})"),
None => format!("0x{focus:x} (no WM_CLASS, {owner})"),
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn focus_holder_names_the_owner() {
assert_eq!(describe_focus_holder(0, None, None, None), "none");
assert_eq!(describe_focus_holder(1, None, None, None), "PointerRoot");
assert_eq!(
describe_focus_holder(
0x520000a,
Some("Gnome-terminal"),
Some(1865),
Some("gnome-terminal-")
),
"0x520000a (Gnome-terminal, pid 1865 gnome-terminal-)"
);
assert_eq!(
describe_focus_holder(0x800003, None, None, None),
"0x800003 (no WM_CLASS, no _NET_WM_PID)"
);
}
#[test]
fn error_code_recognises_prefixes() {
assert_eq!(
error_code(&anyhow!("{CODE_TIMEOUT}: x")),
Some(CODE_TIMEOUT)
);
assert_eq!(
error_code(&anyhow!("{CODE_UNAVAILABLE}: y")),
Some(CODE_UNAVAILABLE)
);
assert_eq!(error_code(&anyhow!("other")), None);
}
#[test]
fn deadline_returns_none_when_work_hangs() {
let started = Instant::now();
let result = run_with_deadline(Instant::now() + Duration::from_millis(50), || {
std::thread::sleep(Duration::from_secs(5));
1
});
assert!(result.is_none());
assert!(started.elapsed() < Duration::from_secs(2));
}
#[test]
fn window_change_bounds_default_to_the_linux_deadline() {
let unset = WindowObservationBounds::from_raw(
None,
None,
WINDOW_CHANGE_DEADLINE,
WINDOW_CHANGE_POLL,
);
assert_eq!(unset.timeout, WINDOW_CHANGE_DEADLINE);
assert_eq!(unset.poll, WINDOW_CHANGE_POLL);
let host = WindowObservationBounds::from_raw(
Some("120"),
Some("20"),
WINDOW_CHANGE_DEADLINE,
WINDOW_CHANGE_POLL,
);
assert_eq!(host.timeout, Duration::from_millis(120));
assert_eq!(host.poll, Duration::from_millis(20));
}
/// A zero host timeout never reports window-change evidence (which would
/// upgrade the action to `effect: confirmed`) even when the before-set
/// differs from the live one. Read-only: no input is sent.
#[test]
fn zero_window_change_timeout_reports_no_change() {
let bounds = WindowObservationBounds::from_raw(
Some("0"),
None,
WINDOW_CHANGE_DEADLINE,
WINDOW_CHANGE_POLL,
);
let before = vec![entry(u64::MAX, "window that never existed", true)];
let started = Instant::now();
let (_after, change) = wait_for_window_change(
Some(u32::MAX),
&before,
bounds,
Instant::now() + bounds.timeout,
);
assert_eq!(change, None);
assert!(started.elapsed() < WINDOW_CHANGE_DEADLINE);
}
/// mutter's `no_focus_window` (0x1600058) and its `_NET_SUPPORTING_WM_CHECK`
/// window (0x1600006) share the client base above the 21-bit resource mask;
/// a LibreOffice toplevel (0x3e00096) does not.
#[test]
fn wm_windows_share_the_wm_check_client_base() {
let mask = 0x1f_ffff;
assert!(same_x11_client(0x160_0058, 0x160_0006, mask));
assert!(!same_x11_client(0x3e0_0096, 0x160_0006, mask));
}
/// The focus sequence mutter produces after a focused dialog closes:
/// unset, then parked on its own window, then the next toplevel. The
/// post-check waits the parking out and reports the toplevel.
#[test]
fn focus_parked_on_the_window_manager_is_waited_out() {
let mask = 0x1f_ffff;
let wm_check = 0x160_0006;
let mut readings = [None, Some(0x160_0058), Some(0x160_0058), Some(0x3e0_0096)].into_iter();
let focused = await_focus_destination(
Instant::now() + Duration::from_secs(2),
|| readings.next().flatten(),
|w| same_x11_client(w, wm_check, mask),
);
assert_eq!(focused, Some(0x3e0_0096));
}
/// A focus that never leaves the window manager names no destination:
/// `None` at the deadline, never the parking window itself.
#[test]
fn focus_left_on_the_window_manager_is_unknown_at_the_deadline() {
let mask = 0x1f_ffff;
let deadline = Instant::now() + Duration::from_millis(80);
let focused = await_focus_destination(
deadline,
|| Some(0x160_0058),
|w| same_x11_client(w, 0x160_0006, mask),
);
assert_eq!(focused, None);
assert!(Instant::now() >= deadline);
}
/// A focus already on a client window returns on the first read: the
/// happy path pays no retry.
#[test]
fn settled_focus_returns_without_waiting() {
let started = Instant::now();
let focused = await_focus_destination(
started + Duration::from_secs(2),
|| Some(0x3e0_0096),
|_| false,
);
assert_eq!(focused, Some(0x3e0_0096));
assert!(started.elapsed() < Duration::from_millis(25));
}
#[test]
fn deadline_returns_value_when_work_finishes() {
assert_eq!(
run_with_deadline(Instant::now() + Duration::from_secs(2), || 7),
Some(7)
);
}
#[test]
fn keyboard_budget_exceeds_pointer_budget() {
assert!(ForegroundOptions::keyboard().settle > ForegroundOptions::pointer().settle);
}
#[test]
fn options_carry_the_caller_resolved_pid() {
assert_eq!(ForegroundOptions::pointer().target_pid, None);
assert_eq!(
ForegroundOptions::keyboard().for_pid(42).target_pid,
Some(42)
);
assert!(!ForegroundOptions::pointer().for_pid(1).keyboard);
}
#[test]
fn report_json_shape() {
let report = ForegroundReport {
already_active: true,
retried_activation: false,
confirm_ms: 3,
focus_after: FocusAfter::SamePid,
window_change: Some("appeared: popup window 7 (200x300 at 1,2)".into()),
window_change_owned: false,
};
let json = report.to_json();
assert_eq!(json["activated"], false);
assert_eq!(json["focus_after"], "same_pid");
assert_eq!(json["confirm_ms"], 3);
assert_eq!(
json["window_change"],
"appeared: popup window 7 (200x300 at 1,2)"
);
assert!(report.focus_kept());
}
fn entry(window: u64, description: &str, owned: bool) -> WindowEntry {
WindowEntry {
window,
description: description.to_string(),
owned,
}
}
#[test]
fn window_change_diff_names_appeared_and_closed() {
let before = vec![
entry(1, "window 1 \"GIMP\"", true),
entry(2, "window 2", true),
];
let after = vec![
entry(1, "window 1 \"GIMP\"", true),
entry(9, "popup window 9", false),
];
assert_eq!(
describe_window_change(&before, &after),
Some(WindowChange {
summary: "appeared: popup window 9; closed: window 2".into(),
owned: true,
})
);
assert_eq!(describe_window_change(&before, &before), None);
}
/// A popup that names no pid (a VCL menu, or another client's) is listed
/// in the target's set, but its change alone is not the target's own.
#[test]
fn unattributed_popup_change_is_not_owned() {
let before = vec![entry(1, "window 1 \"Calc\"", true)];
let after = vec![
entry(1, "window 1 \"Calc\"", true),
entry(9, "popup window 9", false),
];
let change = describe_window_change(&before, &after).expect("a popup appeared");
assert!(!change.owned);
}
#[test]
fn unavailable_display_is_structured() {
let display = crate::test_env::unreachable_x11_display();
let result = activate(0x1234, ForegroundOptions::pointer());
drop(display);
let Err(error) = result else {
panic!("connect must fail")
};
assert!(error_code(&error).is_some(), "{error}");
}
}