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.

40.1 KB
Raw Blame
// 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}");
    }
}