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
fix(cua-driver): minimal agent cursor badge by default; cursor.badges verbose restores the old badge (#5053)
Francesco Bonacci176d3243c796
diff --git a/docs/content/docs/cua-driver/guides/operate.mdx b/docs/content/docs/cua-driver/guides/operate.mdxindex 9ab58e7d4e..644bfeb0f4 100644--- a/docs/content/docs/cua-driver/guides/operate.mdx+++ b/docs/content/docs/cua-driver/guides/operate.mdx@@ -309,12 +309,20 @@ to another release.## Personalize the cursorThe agent's cursor is an overlay, not the real pointer: a session-colored-pointer (`cua.default`, the only built-in theme) with a badge showing the-session name, delivery (`background` or `foreground`), and target (`ax`,-`pixel`, `browser`, or `desktop`). It is a visual aid, not an authorization-signal.+pointer (`cua.default`, the only built-in theme). Its color tells agents apart.+It is a visual aid, not an authorization signal.-+By default the cursor carries no badge. A small chip appears for about a second+when the agent brings something to the foreground or presses a key combo such+as ⌘C. The session name appears when you hover over the cursor, or while two or+more agent cursors are on screen. Nothing is shown while the cursor moves.++The `cursor.badges` setting changes this for every cursor at once:+`minimal` (the default), `verbose` (the session name on reveal, plus delivery+and target chips on every action), or `off`. For example,+`cua-driver config set cursor.badges verbose` restores the earlier badge:++```bash test="cli-shape" id="cua-driver"cua-driver start_session '{"session":"research"}'diff --git a/docs/content/docs/cua-driver/reference/cli/config.mdx b/docs/content/docs/cua-driver/reference/cli/config.mdxindex 539100a005..4e2411c90c 100644--- a/docs/content/docs/cua-driver/reference/cli/config.mdx+++ b/docs/content/docs/cua-driver/reference/cli/config.mdx@@ -97,7 +97,7 @@ cua-driver config get max_image_dimensionSet one config key.-Cursor motion defaults are saved keys that apply to sessions started afterwards: cursor.motion.style (signature_arc, spring_settle, magnetic, comet_swoop, adaptive, classic), cursor.motion.timing (native, fitts, fixed) and cursor.motion.effects.<trail|glow|magnet|ripple|squish> (on, off, default). Use default for a key to clear it, or cursor.motion default to clear all. A start_session cursor_motion or a set_agent_cursor_motion call overrides the saved default.+Cursor motion defaults are saved keys that apply to sessions started afterwards: cursor.motion.style (signature_arc, spring_settle, magnetic, comet_swoop, adaptive, classic), cursor.motion.timing (native, fitts, fixed) and cursor.motion.effects.<trail|glow|magnet|ripple|squish> (on, off, default). Use default for a key to clear it, or cursor.motion default to clear all. A start_session cursor_motion or a set_agent_cursor_motion call overrides the saved default. cursor.badges (minimal, verbose, off) sets the agent cursor badge for every cursor at once; minimal is the default.```text outputcua-driver config set <key> <value>diff --git a/docs/content/docs/cua-driver/reference/mcp-tools/maintenance.mdx b/docs/content/docs/cua-driver/reference/mcp-tools/maintenance.mdxindex 954316ffc8..18bc5bb27a 100644--- a/docs/content/docs/cua-driver/reference/mcp-tools/maintenance.mdx+++ b/docs/content/docs/cua-driver/reference/mcp-tools/maintenance.mdx@@ -79,6 +79,8 @@ Note: capture_mode is a per-call param (on get_window_state / click), not a storCursor motion defaults: cursor.motion.style, cursor.motion.timing and cursor.motion.effects.<trail|glow|magnet|ripple|squish> are saved to ~/.cua-driver/config.json and seed sessions started afterwards. start_session cursor_motion and set_agent_cursor_motion override them; reduced motion always wins.+Agent cursor badge: cursor.badges is minimal (default), verbose or off, saved to ~/.cua-driver/config.json and applied to every cursor at once.+**macOS parameters**| Parameter | Type | Default | Description |@@ -97,6 +99,8 @@ The experimental_pip keys persist to ~/.cua-driver/config.json and apply on next`cursor.motion.style`, `cursor.motion.timing` and `cursor.motion.effects.<name>` (`on`, `off`, or `default`) save the default cursor motion for sessions started afterwards. `cursor.motion: "default"` clears every saved cursor motion default.+`cursor.badges` (`minimal` default, `verbose`, or `off`) sets the agent cursor badge for every cursor at once.+**Linux parameters**| Parameter | Type | Default | Description |@@ -117,6 +121,7 @@ Known keys:- `experimental_pip_geometry` (string `WxH` or `WxH+X+Y`; persisted; applies on next daemon restart)- `cursor.motion.style`, `cursor.motion.timing`, `cursor.motion.effects.<name>` (`on`, `off`, or `default`): saved default cursor motion for sessions started afterwards. `cursor.motion: "default"` clears every saved cursor motion default.+- `cursor.badges` (`minimal` default, `verbose`, or `off`): agent cursor badge; applies to every cursor at once.Returns the full updated config in the same shape as `get_config`.@@ -135,6 +140,7 @@ Returns the full updated config in the same shape as `get_config`.| Parameter | Type | Default | Description || --- | --- | --- | --- |+| <span id="set_config--cursor-badges"></span>`cursor.badges` | `"minimal" \| "verbose" \| "off" \| "default"` | | Agent cursor badge. minimal (default): no badge at rest; a brief chip for a foreground moment or a key combo, and the session name on hover or when two or more agent cursors are on screen. verbose: the earlier badge with the session name and delivery/target chips on every action. off: no badge. Applies immediately to every cursor. || <span id="set_config--cursor-motion"></span>`cursor.motion` | `"default"` | | Pass `default` to clear every saved cursor motion default. || <span id="set_config--cursor-motion-effects-glow"></span>`cursor.motion.effects.glow` | `"on" \| "off" \| "default"` | | Saved default for the `glow` cursor effect: on, off, or default (the style's own). Omit the key to leave it unchanged. || <span id="set_config--cursor-motion-effects-magnet"></span>`cursor.motion.effects.magnet` | `"on" \| "off" \| "default"` | | Saved default for the `magnet` cursor effect: on, off, or default (the style's own). Omit the key to leave it unchanged. |diff --git a/libs/cua-driver/docs/cursor-modifier-badge-restructuring-plan.md b/libs/cua-driver/docs/cursor-modifier-badge-restructuring-plan.mdindex 6965b6ced7..f8186b867e 100644--- a/libs/cua-driver/docs/cursor-modifier-badge-restructuring-plan.md+++ b/libs/cua-driver/docs/cursor-modifier-badge-restructuring-plan.md@@ -1,6 +1,6 @@# Cursor modifier badge restructuring plan-**Status:** Implemented in [PR #2677](https://github.com/trycua/cua/pull/2677); validation complete+**Status:** Implemented in [PR #2677](https://github.com/trycua/cua/pull/2677); validation complete. This badge is now the `verbose` value of `cursor.badges`; the default is the `minimal` badge described in [cursor-themes.md](cursor-themes.md).**Base:** `main` at `b249df857994ebaebf9f02248e8312b3bd2a5dd2`**Scope:** Move delivery and target modifiers from around the agent pointer into the session badge while preserving action animations beside the pointer.diff --git a/libs/cua-driver/docs/cursor-themes.md b/libs/cua-driver/docs/cursor-themes.mdindex 2ad4648294..0e5070b2d5 100644--- a/libs/cua-driver/docs/cursor-themes.md+++ b/libs/cua-driver/docs/cursor-themes.md@@ -20,8 +20,24 @@ uses Cua blue. Named sessions receive a stable fillfrom the built-in session palette, so concurrent agents remain visuallydistinct.-The native renderer places the sanitized public session name and execution-context in a compact badge below the built-in pointer. The badge uses a+The badge below the pointer follows the `cursor.badges` setting, which applies+to every cursor at once:++- `minimal` (default): no badge at rest. A foreground-delivery moment or a key+ combo (such as ⌘C) shows a short chip: it waits about 0.1 seconds, holds for+ half a second and fades out, about one second in all. The session name shows+ only while the human pointer hovers over the cursor or while two or more+ agent cursors are on screen. Nothing shows while the cursor moves. The chip+ plays once its action has ended and the cursor is at rest, because a real+ foreground click can hide the overlay while it is delivered.+ Background delivery and target chips are not shown. The GNOME Shell helper+ draws one cursor and has no hover, so under `minimal` it shows only the+ foreground chip.+- `verbose`: the earlier badge, described below.+- `off`: no badge.++In `verbose` mode the native renderer places the sanitized public session name+and execution context in a compact badge below the built-in pointer. The badge uses asession-accent gradient and a circular session marker. The session name appearswhen the cursor is first revealed, remains fully visible for two seconds, thenfades over 400 milliseconds while the cursor stays available. Moving the humandiff --git a/libs/cua-driver/rust/crates/cua-driver-core/src/cursor_events.rs b/libs/cua-driver/rust/crates/cua-driver-core/src/cursor_events.rsindex b05e8a9cf5..23fe1cc4cc 100644--- a/libs/cua-driver/rust/crates/cua-driver-core/src/cursor_events.rs+++ b/libs/cua-driver/rust/crates/cua-driver-core/src/cursor_events.rs@@ -8,8 +8,8 @@//! subscribers are intentionally invisible to the tool result.use cua_driver_contract::{- classify_cursor_semantics, CursorAction, CursorMotionSelection, CursorSemantics,- CursorThemeSelection,+ classify_cursor_semantics, CursorAction, CursorDelivery, CursorMotionSelection,+ CursorSemantics, CursorThemeSelection,};use serde_json::Value;use std::sync::{Arc, OnceLock, RwLock};@@ -41,6 +41,12 @@ pub enum CursorEvent {session: String,motion: Value,},+ /// Keys a key action presses together, such as `["cmd", "c"]`. Emitted+ /// after the action's `Begin` so the badge can show the combo briefly.+ KeyCombo {+ session: String,+ keys: Vec<String>,+ },}pub trait CursorEventSink: Send + Sync + 'static {@@ -117,15 +123,60 @@ pub fn begin_tool(name: &str, args: &Value) -> Option<(String, CursorAction)> {}}}- let semantics = classify_cursor_semantics(name, args)?;+ let mut semantics = classify_cursor_semantics(name, args)?;+ if semantics.delivery.is_none() && brings_app_to_front(name) {+ semantics.delivery = Some(CursorDelivery::Foreground);+ }emit(CursorEvent::Action {session: session.clone(),phase: CursorEventPhase::Begin,semantics,});+ if semantics.action == CursorAction::Key {+ let keys = pressed_keys(args);+ if keys.len() > 1 {+ emit(CursorEvent::KeyCombo {+ session: session.clone(),+ keys,+ });+ }+ }Some((session, semantics.action))}+/// Tools whose whole job is to bring an app or window to the foreground.+fn brings_app_to_front(name: &str) -> bool {+ matches!(name, "bring_to_front" | "activate_app" | "browser_activate")+}++/// The keys a key tool presses together: `hotkey`'s `keys` (an array, or a+/// `cmd+c` string), or `press_key`'s `modifiers` plus `key`.+fn pressed_keys(args: &Value) -> Vec<String> {+ let strings = |value: Option<&Value>| -> Vec<String> {+ match value {+ Some(Value::Array(items)) => items+ .iter()+ .filter_map(Value::as_str)+ .map(str::to_owned)+ .collect(),+ Some(Value::String(text)) => text+ .split('+')+ .map(str::trim)+ .filter(|part| !part.is_empty())+ .map(str::to_owned)+ .collect(),+ _ => Vec::new(),+ }+ };+ let keys = strings(args.get("keys"));+ if !keys.is_empty() {+ return keys;+ }+ let mut keys = strings(args.get("modifiers"));+ keys.extend(strings(args.get("key")));+ keys+}+pub fn end_tool(active: Option<(String, CursorAction)>) {let Some((session, action)) = active else {return;@@ -201,6 +252,76 @@ mod tests {));}+ fn capture(run: impl FnOnce()) -> Vec<CursorEvent> {+ let events = Arc::new(Mutex::new(Vec::new()));+ let captured = Arc::clone(&events);+ install_cursor_event_sink(Arc::new(move |event| {+ captured+ .lock()+ .unwrap_or_else(|poisoned| poisoned.into_inner())+ .push(event);+ }));+ run();+ clear_cursor_event_sink();+ let events = events+ .lock()+ .unwrap_or_else(|poisoned| poisoned.into_inner());+ events.clone()+ }++ #[test]+ fn key_combos_follow_their_action_and_bare_keys_emit_none() {+ let _guard = test_sink_guard();+ let events = capture(|| {+ begin_tool("hotkey", &json!({"session":"run","keys":["cmd","c"]}));+ begin_tool(+ "press_key",+ &json!({"session":"run","key":"v","modifiers":["cmd"]}),+ );+ begin_tool("press_key", &json!({"session":"run","key":"return"}));+ begin_tool("type_text", &json!({"session":"run","text":"cmd+c"}));+ });+ let combos: Vec<_> = events+ .iter()+ .filter_map(|event| match event {+ CursorEvent::KeyCombo { keys, .. } => Some(keys.clone()),+ _ => None,+ })+ .collect();+ assert_eq!(+ combos,+ vec![+ vec!["cmd".to_owned(), "c".to_owned()],+ vec!["cmd".to_owned(), "v".to_owned()],+ ]+ );+ assert!(matches!(+ events[0],+ CursorEvent::Action {+ phase: CursorEventPhase::Begin,+ ..+ }+ ));+ assert!(matches!(events[1], CursorEvent::KeyCombo { .. }));+ }++ #[test]+ fn bringing_an_app_forward_is_a_foreground_moment() {+ let _guard = test_sink_guard();+ let events = capture(|| {+ begin_tool("bring_to_front", &json!({"session":"run","pid":1}));+ begin_tool("launch_app", &json!({"session":"run","bundle_id":"x"}));+ });+ let deliveries: Vec<_> = events+ .iter()+ .filter_map(|event| match event {+ CursorEvent::Action { semantics, .. } => Some(semantics.delivery),+ _ => None,+ })+ .collect();+ assert_eq!(deliveries, vec![Some(CursorDelivery::Foreground), None]);+ }+#[test]fn start_session_cursor_motion_is_emitted_before_the_cursor_is_shown() {let _guard = test_sink_guard();diff --git a/libs/cua-driver/rust/crates/cua-driver/src/cli.rs b/libs/cua-driver/rust/crates/cua-driver/src/cli.rsindex efa3abb071..eb93897c07 100644--- a/libs/cua-driver/rust/crates/cua-driver/src/cli.rs+++ b/libs/cua-driver/rust/crates/cua-driver/src/cli.rs@@ -4419,7 +4419,7 @@ fn cli_docs_literal() -> serde_json::Value {"subcommands": [{"name":"show","abstract":"Print the full config.","discussion":"","arguments":[],"options":[],"flags":[],"subcommands":[]},{"name":"get","abstract":"Print one config key.","discussion":"","arguments":[{"name":"key","help":"Config key to read.","type":"String","is_optional":false}],"options":[],"flags":[],"subcommands":[]},- {"name":"set","abstract":"Set one config key.","discussion":"Cursor motion defaults are saved keys that apply to sessions started afterwards: cursor.motion.style (signature_arc, spring_settle, magnetic, comet_swoop, adaptive, classic), cursor.motion.timing (native, fitts, fixed) and cursor.motion.effects.<trail|glow|magnet|ripple|squish> (on, off, default). Use default for a key to clear it, or cursor.motion default to clear all. A start_session cursor_motion or a set_agent_cursor_motion call overrides the saved default.","arguments":[{"name":"key","help":"Config key to write.","type":"String","is_optional":false},{"name":"value","help":"Value to store.","type":"String","is_optional":false}],"options":[],"flags":[],"subcommands":[]},+ {"name":"set","abstract":"Set one config key.","discussion":"Cursor motion defaults are saved keys that apply to sessions started afterwards: cursor.motion.style (signature_arc, spring_settle, magnetic, comet_swoop, adaptive, classic), cursor.motion.timing (native, fitts, fixed) and cursor.motion.effects.<trail|glow|magnet|ripple|squish> (on, off, default). Use default for a key to clear it, or cursor.motion default to clear all. A start_session cursor_motion or a set_agent_cursor_motion call overrides the saved default. cursor.badges (minimal, verbose, off) sets the agent cursor badge for every cursor at once; minimal is the default.","arguments":[{"name":"key","help":"Config key to write.","type":"String","is_optional":false},{"name":"value","help":"Value to store.","type":"String","is_optional":false}],"options":[],"flags":[],"subcommands":[]},{"name":"reset","abstract":"Reset config to defaults.","discussion":"","arguments":[],"options":[],"flags":[],"subcommands":[]}]},@@ -5141,7 +5141,7 @@ pub fn run_config_cmd(Some(k) => k,None => {eprintln!("Usage: cua-driver config get <key>");- eprintln!("Keys: capture_mode, max_image_dimension, version, platform, cursor.motion.style, cursor.motion.timing");+ eprintln!("Keys: capture_mode, max_image_dimension, version, platform, cursor.motion.style, cursor.motion.timing, cursor.badges");process::exit(64);}};@@ -5170,7 +5170,7 @@ pub fn run_config_cmd();} else {eprintln!("Unknown config key: {key}");- eprintln!("Available keys: capture_mode, max_image_dimension, version, platform, agent_cursor.enabled, cursor.motion.style, cursor.motion.timing, cursor.motion.effects");+ eprintln!("Available keys: capture_mode, max_image_dimension, version, platform, agent_cursor.enabled, cursor.motion.style, cursor.motion.timing, cursor.motion.effects, cursor.badges");process::exit(64);}}@@ -5219,10 +5219,10 @@ pub fn run_config_cmd("max_image_dimension": 0});call("set_config", defaults);- // Also clear the saved cursor motion defaults.+ // Also clear the saved cursor motion defaults and badge mode.exit_on_tool_error(&call("set_config",- serde_json::json!({ "cursor.motion": "default" }),+ serde_json::json!({ "cursor.motion": "default", "cursor.badges": "default" }),));println!("Config reset to defaults.");let config = get_config();diff --git a/libs/cua-driver/rust/crates/cursor-overlay/examples/export_gallery_frames.rs b/libs/cua-driver/rust/crates/cursor-overlay/examples/export_gallery_frames.rsindex 238ccc95a7..a0cfd49601 100644--- a/libs/cua-driver/rust/crates/cursor-overlay/examples/export_gallery_frames.rs+++ b/libs/cua-driver/rust/crates/cursor-overlay/examples/export_gallery_frames.rs@@ -128,6 +128,9 @@ fn export_state(output: &Path, state: GalleryState) {..CursorConfig::default()};let mut core = RenderStateCore::new(config);+ // The gallery documents every badge combination, which only the+ // verbose badge shows.+ core.badge_mode_override = Some(cursor_overlay::BadgeMode::Verbose);core.motion.idle_hide_ms = 0.0;core.pos = (f64::from(SIZE) / (2.0 * f64::from(PREVIEW_BACKING_SCALE)),diff --git a/libs/cua-driver/rust/crates/cursor-overlay/src/badge_mode.rs b/libs/cua-driver/rust/crates/cursor-overlay/src/badge_mode.rsnew file mode 100644index 0000000000..27c168b68e--- /dev/null+++ b/libs/cua-driver/rust/crates/cursor-overlay/src/badge_mode.rs@@ -0,0 +1,355 @@+// SPDX-License-Identifier: MIT+// Copyright (c) 2026 Cua AI, Inc.++//! How much the session badge under an agent cursor shows.+//!+//! `cursor.badges` lives in `~/.cua-driver/config.json`+//! (`{"cursor": {"badges": "minimal"}}`) next to the saved motion defaults.+//! Unlike the motion defaults it applies live: every cursor reads the+//! process-wide value on each frame, so a `set_config` write changes cursors+//! that are already on screen.+//!+//! - `minimal` (default): no badge at rest. A short chip appears for a+//! foreground-delivery moment or a held key combo (such as ⌘C), and the+//! session name appears only on hover or while two or more agent cursors+//! are on screen. Nothing shows while the cursor is moving.+//! - `verbose`: the earlier badge. The name shows on reveal, and delivery and+//! target chips follow every action.+//! - `off`: no badge.++use serde_json::{json, Map, Value};+use std::path::Path;+use std::sync::atomic::{AtomicU8, Ordering};++/// Config key this module owns.+pub const BADGES_KEY: &str = "cursor.badges";++#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Hash)]+pub enum BadgeMode {+ #[default]+ Minimal,+ Verbose,+ Off,+}++impl BadgeMode {+ pub const ALL: [BadgeMode; 3] = [BadgeMode::Minimal, BadgeMode::Verbose, BadgeMode::Off];++ pub const fn as_str(self) -> &'static str {+ match self {+ BadgeMode::Minimal => "minimal",+ BadgeMode::Verbose => "verbose",+ BadgeMode::Off => "off",+ }+ }++ pub fn parse(value: &str) -> Option<Self> {+ Self::ALL+ .into_iter()+ .find(|mode| mode.as_str().eq_ignore_ascii_case(value.trim()))+ }++ const fn to_u8(self) -> u8 {+ match self {+ BadgeMode::Minimal => 0,+ BadgeMode::Verbose => 1,+ BadgeMode::Off => 2,+ }+ }++ const fn from_u8(value: u8) -> Self {+ match value {+ 1 => BadgeMode::Verbose,+ 2 => BadgeMode::Off,+ _ => BadgeMode::Minimal,+ }+ }+}++fn allowed() -> String {+ BadgeMode::ALL.map(BadgeMode::as_str).join(", ")+}++/// Parse a config value. `null` and `"default"` mean the built-in default.+pub fn parse_value(value: &Value) -> Result<Option<BadgeMode>, String> {+ if value.is_null() || value.as_str() == Some("default") {+ return Ok(None);+ }+ let name = value+ .as_str()+ .ok_or_else(|| format!("{BADGES_KEY} must be a string, got {value}"))?;+ BadgeMode::parse(name).map(Some).ok_or_else(|| {+ format!(+ "unknown {BADGES_KEY} value `{name}`; expected one of {}",+ allowed()+ )+ })+}++/// Read the saved mode from `path`. A missing file or an invalid value falls+/// back to the default; a bad value is logged, never fatal.+pub fn load_from(path: &Path) -> BadgeMode {+ let saved = std::fs::read_to_string(path)+ .ok()+ .and_then(|text| serde_json::from_str::<Value>(&text).ok())+ .and_then(|json| json.get("cursor")?.get("badges").cloned());+ match saved.map(|value| parse_value(&value)) {+ Some(Ok(mode)) => mode.unwrap_or_default(),+ Some(Err(error)) => {+ tracing::warn!("ignoring saved {BADGES_KEY}: {error}");+ BadgeMode::default()+ }+ None => BadgeMode::default(),+ }+}++/// Validate and persist one write to `path`, keeping every other key in the+/// file. Nothing is written when validation fails.+pub fn set_at(path: &Path, value: &Value) -> Result<BadgeMode, String> {+ let mode = parse_value(value)?;+ let mut root: Value = std::fs::read_to_string(path)+ .ok()+ .and_then(|text| serde_json::from_str(&text).ok())+ .filter(Value::is_object)+ .unwrap_or_else(|| json!({}));+ let object = root.as_object_mut().expect("root is an object");+ let cursor = object.entry("cursor").or_insert_with(|| json!({}));+ if !cursor.is_object() {+ *cursor = json!({});+ }+ let cursor = cursor.as_object_mut().expect("cursor is an object");+ match mode {+ Some(mode) => {+ cursor.insert("badges".into(), json!(mode.as_str()));+ }+ None => {+ cursor.remove("badges");+ }+ }+ if cursor.is_empty() {+ object.remove("cursor");+ }+ if let Some(parent) = path.parent() {+ std::fs::create_dir_all(parent).map_err(|error| error.to_string())?;+ }+ let body = serde_json::to_string_pretty(&root).map_err(|error| error.to_string())?;+ std::fs::write(path, body)+ .map_err(|error| format!("failed to persist {BADGES_KEY}: {error}"))?;+ Ok(mode.unwrap_or_default())+}++// Process-wide mode every cursor reads per frame. It starts at the default so+// unit tests never read the user's file; the daemon loads it at startup+// (`CursorConfig::from_args`) and on every config write.+static ACTIVE: AtomicU8 = AtomicU8::new(0);++/// The mode cursors paint with right now.+pub fn active() -> BadgeMode {+ BadgeMode::from_u8(ACTIVE.load(Ordering::Relaxed))+}++pub fn set_active(mode: BadgeMode) {+ ACTIVE.store(mode.to_u8(), Ordering::Relaxed);+}++/// Load `~/.cua-driver/config.json` into the process-wide value.+pub fn load_active() -> BadgeMode {+ let mode = read_saved();+ set_active(mode);+ mode+}++/// What is saved on disk right now (for `get_config`).+pub fn read_saved() -> BadgeMode {+ crate::motion_defaults::default_config_path()+ .map(|path| load_from(&path))+ .unwrap_or_default()+}++/// Apply a `cursor.badges` write in a `set_config` call: validate, persist,+/// and switch every cursor at once. Returns the key when it was written.+pub fn apply_config_args(args: &Value) -> Result<Option<String>, String> {+ let Some(value) = args.get(BADGES_KEY) else {+ return Ok(None);+ };+ let path = crate::motion_defaults::default_config_path()+ .ok_or_else(|| "$HOME is not set".to_string())?;+ let mode = set_at(&path, value)?;+ set_active(mode);+ Ok(Some(format!("{BADGES_KEY}={}", mode.as_str())))+}++/// Input-schema property to merge into each platform's `set_config` tool.+pub fn config_schema_properties() -> Map<String, Value> {+ let mut properties = Map::new();+ let mut values: Vec<&str> = BadgeMode::ALL.map(BadgeMode::as_str).to_vec();+ values.push("default");+ properties.insert(+ BADGES_KEY.to_owned(),+ json!({+ "type": "string",+ "enum": values,+ "description": "Agent cursor badge. minimal (default): no badge at rest; a brief chip for a foreground moment or a key combo, and the session name on hover or when two or more agent cursors are on screen. verbose: the earlier badge with the session name and delivery/target chips on every action. off: no badge. Applies immediately to every cursor."+ }),+ );+ properties+}++/// Format a key combo for the minimal badge, such as `⌘C` on macOS or+/// `Ctrl+C` elsewhere. `None` unless at least one modifier is held with a+/// non-modifier key: a bare key press does not earn a chip.+pub fn format_key_combo(keys: &[String]) -> Option<String> {+ format_key_combo_for(keys, cfg!(target_os = "macos"))+}++pub(crate) fn format_key_combo_for(keys: &[String], mac: bool) -> Option<String> {+ #[derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]+ enum Modifier {+ Control,+ Option,+ Shift,+ Command,+ }+ let mut modifiers = Vec::new();+ let mut main = None;+ for key in keys {+ let lower = key.trim().to_ascii_lowercase();+ let modifier = match lower.as_str() {+ "cmd" | "command" | "meta" | "super" | "win" | "windows" => Some(Modifier::Command),+ "ctrl" | "control" => Some(Modifier::Control),+ "alt" | "option" | "opt" => Some(Modifier::Option),+ "shift" => Some(Modifier::Shift),+ "" => continue,+ _ => None,+ };+ match modifier {+ Some(modifier) if !modifiers.contains(&modifier) => modifiers.push(modifier),+ Some(_) => {}+ None => main = Some(key.trim().to_owned()),+ }+ }+ let main = main?;+ if modifiers.is_empty() {+ return None;+ }+ modifiers.sort();+ let key_label = {+ let mut chars = main.chars();+ match (chars.next(), chars.next()) {+ (Some(only), None) => only.to_uppercase().collect::<String>(),+ _ => {+ let mut word = main.replace(['_', '-'], " ");+ if let Some(first) = word.get_mut(0..1) {+ first.make_ascii_uppercase();+ }+ word+ }+ }+ };+ let mut label = String::new();+ if mac {+ for modifier in modifiers {+ label.push(match modifier {+ Modifier::Control => '⌃',+ Modifier::Option => '⌥',+ Modifier::Shift => '⇧',+ Modifier::Command => '⌘',+ });+ }+ label.push_str(&key_label);+ } else {+ for modifier in modifiers {+ label.push_str(match modifier {+ Modifier::Control => "Ctrl+",+ Modifier::Option => "Alt+",+ Modifier::Shift => "Shift+",+ Modifier::Command => "Win+",+ });+ }+ label.push_str(&key_label);+ }+ Some(label)+}++#[cfg(test)]+mod tests {+ use super::*;++ fn keys(values: &[&str]) -> Vec<String> {+ values.iter().map(|value| (*value).to_owned()).collect()+ }++ #[test]+ fn default_mode_is_minimal_and_values_round_trip() {+ assert_eq!(BadgeMode::default(), BadgeMode::Minimal);+ for mode in BadgeMode::ALL {+ assert_eq!(BadgeMode::parse(mode.as_str()), Some(mode));+ assert_eq!(BadgeMode::from_u8(mode.to_u8()), mode);+ }+ assert_eq!(parse_value(&json!("VERBOSE")), Ok(Some(BadgeMode::Verbose)));+ assert_eq!(parse_value(&json!("default")), Ok(None));+ assert_eq!(parse_value(&Value::Null), Ok(None));+ assert!(parse_value(&json!("loud"))+ .unwrap_err()+ .contains("minimal, verbose, off"));+ assert!(parse_value(&json!(true)).is_err());+ }++ #[test]+ fn saved_mode_persists_beside_motion_defaults_and_clears() {+ let dir = std::env::temp_dir().join(format!("cua-badge-mode-{}", std::process::id()));+ let _ = std::fs::remove_dir_all(&dir);+ let path = dir.join("config.json");+ crate::motion_defaults::set_key_at(+ &path,+ crate::motion_defaults::STYLE_KEY,+ &json!("magnetic"),+ )+ .unwrap();+ assert_eq!(load_from(&path), BadgeMode::Minimal);++ assert_eq!(set_at(&path, &json!("verbose")), Ok(BadgeMode::Verbose));+ assert_eq!(load_from(&path), BadgeMode::Verbose);+ let saved = crate::motion_defaults::load_from(&path);+ assert_eq!(+ saved.style,+ Some(crate::motion::MotionStyle::Magnetic),+ "badge writes keep motion defaults"+ );++ assert!(set_at(&path, &json!("loud")).is_err());+ assert_eq!(+ load_from(&path),+ BadgeMode::Verbose,+ "invalid writes change nothing"+ );++ assert_eq!(set_at(&path, &json!("default")), Ok(BadgeMode::Minimal));+ let text = std::fs::read_to_string(&path).unwrap();+ assert!(!text.contains("badges"));+ let _ = std::fs::remove_dir_all(&dir);+ }++ #[test]+ fn key_combos_need_a_modifier_and_use_platform_spelling() {+ assert_eq!(+ format_key_combo_for(&keys(&["cmd", "c"]), true).as_deref(),+ Some("⌘C")+ );+ assert_eq!(+ format_key_combo_for(&keys(&["shift", "cmd", "z"]), true).as_deref(),+ Some("⇧⌘Z")+ );+ assert_eq!(+ format_key_combo_for(&keys(&["ctrl", "c"]), false).as_deref(),+ Some("Ctrl+C")+ );+ assert_eq!(+ format_key_combo_for(&keys(&["alt", "page_down"]), false).as_deref(),+ Some("Alt+Page down")+ );+ assert_eq!(format_key_combo_for(&keys(&["return"]), true), None);+ assert_eq!(format_key_combo_for(&keys(&["cmd"]), true), None);+ assert_eq!(format_key_combo_for(&[], true), None);+ }+}diff --git a/libs/cua-driver/rust/crates/cursor-overlay/src/lib.rs b/libs/cua-driver/rust/crates/cursor-overlay/src/lib.rsindex 46177c8534..152c681a0c 100644--- a/libs/cua-driver/rust/crates/cursor-overlay/src/lib.rs+++ b/libs/cua-driver/rust/crates/cursor-overlay/src/lib.rs@@ -13,6 +13,7 @@//! display geometry, so screen-coordinate cursors stay on the pointerpub mod badge_glyphs;+pub mod badge_mode;pub mod bezier;pub mod capture_exclusion;pub mod capture_utils;@@ -30,6 +31,7 @@ pub use cua_cursor_motion::dubins as path_planner;pub mod z_order;pub use badge_glyphs::{BadgeChip, BadgeGlyph};+pub use badge_mode::BadgeMode;pub use bezier::CubicBezier;pub use motion::{MotionConfig, MotionEffects, MotionStyle, MotionTiming, ResolvedEffects, Spring,@@ -117,6 +119,7 @@ impl CursorConfig {// Load the saved `cursor.motion.*` defaults; the render map layers// them under each cursor it creates.motion_defaults::load_active();+ badge_mode::load_active();Self::parse(&args[1..])}@@ -402,6 +405,9 @@ pub enum OverlayCommand {},/// Set the sanitized public label shown beneath this cursor.SetSessionLabel(String),+ /// Keys of a combo the agent is pressing (such as `["cmd", "c"]`). The+ /// minimal badge shows it briefly; other badge modes ignore it.+ ShowKeyCombo(Vec<String>),/// Show a focus-highlight rectangle around an AX-targeted element./// `[x, y, width, height]` in screen coordinates (top-left origin)./// `None` clears the highlight.diff --git a/libs/cua-driver/rust/crates/cursor-overlay/src/render_map.rs b/libs/cua-driver/rust/crates/cursor-overlay/src/render_map.rsindex de95a55784..6c4fc28095 100644--- a/libs/cua-driver/rust/crates/cursor-overlay/src/render_map.rs+++ b/libs/cua-driver/rust/crates/cursor-overlay/src/render_map.rs@@ -186,6 +186,19 @@ pub fn keyed_config(template: &CursorConfig, key: &str) -> CursorConfig {config}+/// Tell each cursor whether another agent cursor is on screen with it, so the+/// minimal badge can name them apart. Call once per tick, before advancing.+pub fn update_peer_presence<'a>(cores: impl Iterator<Item = &'a mut RenderStateCore>) {+ let mut cores: Vec<&mut RenderStateCore> = cores.collect();+ let shown = cores+ .iter()+ .filter(|core| core.is_revealed() && !core.pinned_target_off_workspace)+ .count();+ for core in cores.iter_mut() {+ core.peer_cursors_visible = shown >= 2;+ }+}+/// The keyed render collection plus per-platform state `P` (screen geometry,/// timing stamps) that the adapter owns.pub struct RenderMap<S, P = ()> {@@ -316,6 +329,7 @@ impl<S: RenderEntry, P> RenderMap<S, P> {/// Advance every cursor; returns the keys whose planned path just ended.pub fn tick_all(&mut self, dt: f64) -> Vec<CursorKey> {+ update_peer_presence(self.cursors.values_mut().map(S::core_mut));let mut arrived = Vec::new();for (key, cursor) in self.cursors.iter_mut() {if cursor.tick(dt) {@@ -344,6 +358,30 @@ mod tests {use super::*;use crate::ReducedMotion;+ #[test]+ fn cursors_know_when_another_agent_cursor_is_on_screen() {+ let mut map = Map::new(CursorConfig::default(), ());+ placed(&mut map, "a");+ map.apply_msg(move_msg("a", 100.0, 100.0));+ map.tick_all(0.016);+ assert!(!map.cursors["a"].peer_cursors_visible, "one cursor alone");++ placed(&mut map, "b");+ map.apply_msg(move_msg("b", 400.0, 300.0));+ map.tick_all(0.016);+ map.tick_all(0.016);+ assert!(map.cursors["a"].peer_cursors_visible);+ assert!(map.cursors["b"].peer_cursors_visible);+ assert!(+ !map.cursors[DEFAULT_CURSOR_KEY].is_revealed(),+ "the unplaced default cursor does not count"+ );++ map.remove("b".to_owned());+ map.tick_all(0.016);+ assert!(!map.cursors["a"].peer_cursors_visible);+ }+type Map = RenderMap<RenderStateCore>;fn map() -> Map {diff --git a/libs/cua-driver/rust/crates/cursor-overlay/src/render_state.rs b/libs/cua-driver/rust/crates/cursor-overlay/src/render_state.rsindex 7a18aa0353..482d1867a0 100644--- a/libs/cua-driver/rust/crates/cursor-overlay/src/render_state.rs+++ b/libs/cua-driver/rust/crates/cursor-overlay/src/render_state.rs@@ -35,8 +35,8 @@use crate::trajectory::{plan_move, MoveRequest, Pt, Trajectory};use crate::{- CompiledTheme, CursorAction, CursorConfig, CursorVisualState, DeliveryModifier, MotionConfig,- OverlayCommand, TargetModifier,+ BadgeMode, CompiledTheme, CursorAction, CursorConfig, CursorVisualState, DeliveryModifier,+ MotionConfig, OverlayCommand, SessionBadgeInput, TargetModifier,};use cua_driver_core::agent_cursor::AgentCursorVisibility;use std::sync::Arc;@@ -44,6 +44,65 @@ use std::sync::Arc;pub const SESSION_BADGE_HOLD_SECS: f64 = 2.0;pub const SESSION_BADGE_FADE_SECS: f64 = 0.4;+/// Minimal badge chip timeline, in seconds of the cursor at rest: a short+/// delay (so a cue that is about to move the cursor does not flash first), a+/// quick fade in, a hold, and a fade out. About one second in all.+pub const MINIMAL_CHIP_DELAY_SECS: f64 = 0.12;+pub const MINIMAL_CHIP_FADE_IN_SECS: f64 = 0.08;+pub const MINIMAL_CHIP_HOLD_SECS: f64 = 0.5;+pub const MINIMAL_CHIP_FADE_OUT_SECS: f64 = 0.3;+pub const MINIMAL_CHIP_SECS: f64 = MINIMAL_CHIP_DELAY_SECS+ + MINIMAL_CHIP_FADE_IN_SECS+ + MINIMAL_CHIP_HOLD_SECS+ + MINIMAL_CHIP_FADE_OUT_SECS;+/// How fast the minimal badge's session name fades in or out when another+/// agent cursor appears or leaves.+pub const MINIMAL_NAME_FADE_SECS: f64 = 0.2;+/// An unarmed chip plays anyway after this long, in case its action's end+/// never arrives.+pub const MINIMAL_CHIP_ARM_TIMEOUT_SECS: f64 = 10.0;+/// Text of the minimal chip for a foreground moment without a key combo.+pub const FOREGROUND_CHIP_LABEL: &str = "foreground";++/// The brief chip the minimal badge shows for one action.+#[derive(Debug, Clone, PartialEq)]+pub struct MinimalChip {+ /// Formatted combo such as `⌘C`, when the action holds one.+ pub key_combo: Option<String>,+ /// The action brings something to the foreground.+ pub foreground: bool,+ /// Seconds played. The clock only runs once the action has ended and+ /// the cursor is at rest.+ pub secs: f64,+ /// The action has ended. A real foreground click can hide the overlay+ /// while it is delivered, so the chip plays after the action instead.+ pub armed: bool,+ /// Seconds waited unarmed, so a lost `EndAction` cannot pin the chip.+ pub waiting_secs: f64,+}++impl MinimalChip {+ pub fn alpha(&self) -> f32 {+ let smooth = |t: f64| {+ let t = t.clamp(0.0, 1.0);+ t * t * (3.0 - 2.0 * t)+ };+ let t = self.secs;+ let fade_in_end = MINIMAL_CHIP_DELAY_SECS + MINIMAL_CHIP_FADE_IN_SECS;+ let hold_end = fade_in_end + MINIMAL_CHIP_HOLD_SECS;+ let alpha = if t < MINIMAL_CHIP_DELAY_SECS {+ 0.0+ } else if t < fade_in_end {+ smooth((t - MINIMAL_CHIP_DELAY_SECS) / MINIMAL_CHIP_FADE_IN_SECS)+ } else if t < hold_end {+ 1.0+ } else {+ 1.0 - smooth((t - hold_end) / MINIMAL_CHIP_FADE_OUT_SECS)+ };+ alpha as f32+ }+}+/// Position of a cursor that has never been placed. It lies far outside any/// compositor layout: layouts reach negative coordinates when a monitor sits/// left of or above the primary one, so a small negative sentinel (the old@@ -122,6 +181,17 @@ pub struct RenderStateCore {pub badge_modifiers: Option<(Option<DeliveryModifier>, Option<TargetModifier>)>,/// Elapsed chip fade time after the active semantic action clears.pub badge_modifier_fade_secs: Option<f64>,+ /// Badge mode for this cursor; `None` follows the live `cursor.badges`+ /// setting ([`crate::badge_mode::active`]).+ pub badge_mode_override: Option<BadgeMode>,+ /// Another agent cursor is revealed on this overlay too, so the minimal+ /// badge names this one. The render map refreshes it on every tick.+ pub peer_cursors_visible: bool,+ /// Minimal badge: eased 0..1 presence of the session name while other+ /// agent cursors are on screen.+ pub minimal_name_presence: f32,+ /// Minimal badge: the brief chip for a foreground moment or key combo.+ pub minimal_chip: Option<MinimalChip>,/// Whether this surface can alpha-blend translucent effects (glow,/// trail). Platforms clear it where they cannot, such as X11 without a/// compositing manager.@@ -177,6 +247,10 @@ impl RenderStateCore {session_badge_hovered: false,badge_modifiers: None,badge_modifier_fade_secs: None,+ badge_mode_override: None,+ peer_cursors_visible: false,+ minimal_name_presence: 0.0,+ minimal_chip: None,effects_capable: true,}}@@ -358,10 +432,31 @@ impl RenderStateCore {}}+ /// The badge mode this cursor paints with now.+ pub fn badge_mode(&self) -> BadgeMode {+ self.badge_mode_override+ .unwrap_or_else(crate::badge_mode::active)+ }++ /// Opacity of the session name.pub fn session_badge_alpha(&self) -> f32 {if self.session_label.is_none() {return 0.0;}+ match self.badge_mode() {+ BadgeMode::Off => return 0.0,+ BadgeMode::Minimal => {+ // Text never shows while the cursor moves.+ if self.is_moving() {+ return 0.0;+ }+ if self.session_badge_hovered {+ return 1.0;+ }+ return self.minimal_name_presence;+ }+ BadgeMode::Verbose => {}+ }if self.session_badge_hovered {return 1.0;}@@ -374,7 +469,18 @@ impl RenderStateCore {(1.0 - smooth) as f32}+ /// Opacity of the badge chips.pub fn session_badge_chip_alpha(&self) -> f32 {+ match self.badge_mode() {+ BadgeMode::Off => return 0.0,+ BadgeMode::Minimal => {+ if self.is_moving() {+ return 0.0;+ }+ return self.minimal_chip.as_ref().map_or(0.0, MinimalChip::alpha);+ }+ BadgeMode::Verbose => {}+ }if self.badge_modifiers.is_none() {return 0.0;}@@ -392,11 +498,86 @@ impl RenderStateCore {}pub fn session_badge_needs_frame_tick(&self) -> bool {- self.is_revealed()- && ((self.session_label.is_some()- && self.session_badge_secs < SESSION_BADGE_HOLD_SECS + SESSION_BADGE_FADE_SECS)- || self.badge_modifier_fade_secs.is_some()- || self.visual.resolved_action != CursorAction::Idle)+ if !self.is_revealed() {+ return false;+ }+ let acting = self.visual.resolved_action != CursorAction::Idle;+ match self.badge_mode() {+ BadgeMode::Verbose => {+ (self.session_label.is_some()+ && self.session_badge_secs < SESSION_BADGE_HOLD_SECS + SESSION_BADGE_FADE_SECS)+ || self.badge_modifier_fade_secs.is_some()+ || acting+ }+ BadgeMode::Minimal => {+ self.minimal_chip.is_some()+ || self.minimal_name_presence != self.minimal_name_target()+ || acting+ }+ BadgeMode::Off => acting,+ }+ }++ /// Where the minimal badge's session name is heading: shown at rest while+ /// another agent cursor is on screen, hidden otherwise.+ fn minimal_name_target(&self) -> f32 {+ if self.session_label.is_some() && self.peer_cursors_visible && !self.is_moving() {+ 1.0+ } else {+ 0.0+ }+ }++ /// What the badge paints this frame, for both painting and hover+ /// hit-testing. `cursor` is the badge anchor in the caller's pixels.+ pub fn session_badge_input(+ &self,+ cursor: (f32, f32),+ backing_scale: f32,+ clip: Option<(f32, f32)>,+ ) -> SessionBadgeInput<'_> {+ let mut input = SessionBadgeInput {+ label: None,+ delivery: None,+ target: None,+ cursor,+ backing_scale,+ label_alpha: 0.0,+ chip_alpha: 0.0,+ clip,+ };+ match self.badge_mode() {+ BadgeMode::Off => {}+ BadgeMode::Verbose => {+ let (delivery, target) = self.badge_modifiers.unwrap_or((None, None));+ input.label = self.session_label.as_deref();+ input.delivery = delivery;+ input.target = target;+ input.label_alpha = self.session_badge_alpha();+ input.chip_alpha = self.session_badge_chip_alpha();+ }+ BadgeMode::Minimal => {+ let chip_alpha = self.session_badge_chip_alpha();+ match self.minimal_chip.as_ref().filter(|_| chip_alpha > 0.001) {+ // The chip briefly takes the badge over, then the name+ // (when shown at all) comes back.+ Some(chip) => {+ input.label = chip+ .key_combo+ .as_deref()+ .or(chip.foreground.then_some(FOREGROUND_CHIP_LABEL));+ input.delivery = chip.foreground.then_some(DeliveryModifier::Foreground);+ input.label_alpha = chip_alpha;+ input.chip_alpha = chip_alpha;+ }+ None => {+ input.label = self.session_label.as_deref();+ input.label_alpha = self.session_badge_alpha();+ }+ }+ }+ }+ input}/// Whether the platform overlay should keep a low-frequency hardware@@ -404,7 +585,7 @@ impl RenderStateCore {/// from [`Self::session_badge_needs_frame_tick`]: a faded badge needs hover/// hit-testing, not continuous 60 fps repainting.pub fn session_badge_needs_hover_poll(&self) -> bool {- self.session_label.is_some() && self.is_revealed()+ self.badge_mode() != BadgeMode::Off && self.session_label.is_some() && self.is_revealed()}/// Update hover state from a platform-native hardware pointer sample.@@ -421,16 +602,11 @@ impl RenderStateCore {if dx * dx + dy * dy <= HOVER_RADIUS * HOVER_RADIUS {return true;}- crate::session_badge_layout(crate::SessionBadgeInput {- label: self.session_label.as_deref(),- delivery: self.badge_modifiers.and_then(|modifiers| modifiers.0),- target: self.badge_modifiers.and_then(|modifiers| modifiers.1),- cursor: (self.pos.0 as f32, self.pos.1 as f32),- backing_scale: 1.0,- label_alpha: self.session_badge_alpha(),- chip_alpha: self.session_badge_chip_alpha(),- clip: None,- })+ crate::session_badge_layout(self.session_badge_input(+ (self.pos.0 as f32, self.pos.1 as f32),+ 1.0,+ None,+ )).is_some_and(|layout| {let rect = layout.rect;x >= rect.x() as f64@@ -535,6 +711,7 @@ impl RenderStateCore {self.session_badge_secs = (self.session_badge_secs + dt).min(SESSION_BADGE_HOLD_SECS + SESSION_BADGE_FADE_SECS);}+ self.tick_minimal_badge(dt);// The idle clock and fade curve are the shared agent cursor contract// (`cua_driver_core::agent_cursor`); this only feeds it frame deltas.let idle_hide_ms = self.motion.idle_hide_ms;@@ -558,6 +735,35 @@ impl RenderStateCore {}}+ /// Advance the minimal badge: the chip clock runs only at rest, and the+ /// session name eases toward its target and drops at once on motion.+ fn tick_minimal_badge(&mut self, dt: f64) {+ let moving = self.is_moving();+ if let Some(chip) = self.minimal_chip.as_mut() {+ if !chip.armed {+ // The tick that arms the chip does not play it.+ chip.waiting_secs += dt.max(0.0);+ chip.armed = chip.waiting_secs >= MINIMAL_CHIP_ARM_TIMEOUT_SECS;+ } else if !moving {+ chip.secs += dt.max(0.0);+ if chip.secs >= MINIMAL_CHIP_SECS {+ self.minimal_chip = None;+ }+ }+ }+ let target = self.minimal_name_target();+ self.minimal_name_presence = if moving {+ 0.0+ } else {+ let step = (dt.max(0.0) / MINIMAL_NAME_FADE_SECS) as f32;+ if self.minimal_name_presence < target {+ (self.minimal_name_presence + step).min(target)+ } else {+ (self.minimal_name_presence - step).max(target)+ }+ };+ }+/// Handle the OverlayCommand variants that are identical across all/// three platforms. Returns `true` if the command was consumed; `false`/// for variants the platform must handle itself (e.g. macOS's@@ -739,9 +945,40 @@ impl RenderStateCore {None};self.badge_modifier_fade_secs = None;+ // A new action replaces any chip still playing; only a+ // foreground moment earns one of its own.+ self.minimal_chip =+ (delivery == Some(DeliveryModifier::Foreground)).then_some(MinimalChip {+ key_combo: None,+ foreground: true,+ secs: 0.0,+ armed: false,+ waiting_secs: 0.0,+ });+ true+ }+ OverlayCommand::ShowKeyCombo(keys) => {+ let Some(combo) = crate::badge_mode::format_key_combo(&keys) else {+ return false;+ };+ // Joins the chip its own BeginAction just started.+ let chip = self.minimal_chip.get_or_insert(MinimalChip {+ key_combo: None,+ foreground: false,+ secs: 0.0,+ armed: false,+ waiting_secs: 0.0,+ });+ chip.key_combo = Some(combo);+ chip.secs = 0.0;true}OverlayCommand::EndAction(action) => {+ // The action is over: its chip plays from now.+ if let Some(chip) = self.minimal_chip.as_mut().filter(|chip| !chip.armed) {+ chip.armed = true;+ chip.secs = 0.0;+ }self.visual.end(action);true}@@ -1124,17 +1361,11 @@ pub fn paint_cursor(}paint_effects_over(pm, &effects, effect_rgb, f64::from(alpha_scale), &to_px, sf);- let (delivery, target) = core.badge_modifiers.unwrap_or((None, None));- if let Some(layout) = crate::session_badge_layout(crate::SessionBadgeInput {- label: core.session_label.as_deref(),- delivery,- target,- cursor: (px as f32, py as f32),- backing_scale: backing_scale.max(1.0),- label_alpha: core.session_badge_alpha(),- chip_alpha: core.session_badge_chip_alpha(),- clip: Some((pm.width() as f32, pm.height() as f32)),- }) {+ if let Some(layout) = crate::session_badge_layout(core.session_badge_input(+ (px as f32, py as f32),+ backing_scale.max(1.0),+ Some((pm.width() as f32, pm.height() as f32)),+ )) {crate::paint_session_badge(pm,&layout,@@ -1355,6 +1586,299 @@ mod session_badge_and_action_tests {use super::*;use crate::{CursorConfig, DeliveryModifier, TargetModifier};+ /// The earlier badge, kept as `cursor.badges = verbose`.+ fn verbose_core() -> RenderStateCore {+ let mut core = RenderStateCore::new(CursorConfig::default());+ core.badge_mode_override = Some(BadgeMode::Verbose);+ core+ }++ fn minimal_core() -> RenderStateCore {+ let mut core = RenderStateCore::new(CursorConfig::default());+ core.badge_mode_override = Some(BadgeMode::Minimal);+ core.motion.idle_hide_ms = 0.0;+ core.apply_command_base(+ OverlayCommand::SetSessionLabel("Research run".into()),+ false,+ false,+ );+ core+ }++ const FRAME: f64 = 1.0 / 60.0;++ fn move_to(core: &mut RenderStateCore, x: f64, y: f64) {+ core.apply_command_base(+ OverlayCommand::MoveTo {+ x,+ y,+ end_heading_radians: std::f64::consts::FRAC_PI_4,+ target: None,+ },+ true,+ true,+ );+ }++ /// Tick until the move ends, checking the badge stays empty throughout.+ fn settle_without_text(core: &mut RenderStateCore) {+ for _ in 0..600 {+ if !core.is_moving() {+ return;+ }+ assert_eq!(core.session_badge_alpha(), 0.0, "no name while moving");+ assert_eq!(core.session_badge_chip_alpha(), 0.0, "no chip while moving");+ core.tick_motion(FRAME);+ }+ panic!("the move never ended");+ }++ fn shown(core: &RenderStateCore) -> Option<crate::SessionBadgeLayout> {+ crate::session_badge_layout(core.session_badge_input(+ (core.pos.0 as f32, core.pos.1 as f32),+ 1.0,+ None,+ ))+ }++ #[test]+ fn minimal_is_the_default_badge_mode() {+ let core = RenderStateCore::new(CursorConfig::default());+ assert_eq!(core.badge_mode_override, None);+ assert_eq!(BadgeMode::default(), BadgeMode::Minimal);+ }++ #[test]+ fn minimal_badge_shows_nothing_for_routine_actions() {+ let mut core = minimal_core();+ move_to(&mut core, 300.0, 240.0);+ settle_without_text(&mut core);+ for _ in 0..30 {+ core.tick_motion(FRAME);+ }+ assert!(core.is_revealed());+ assert!(shown(&core).is_none(), "no session name at rest when alone");++ for delivery in [None, Some(DeliveryModifier::Background)] {+ core.apply_command_base(+ OverlayCommand::BeginAction {+ action: CursorAction::Click,+ delivery,+ target: Some(TargetModifier::Ax),+ },+ false,+ false,+ );+ for _ in 0..30 {+ core.tick_motion(FRAME);+ assert!(shown(&core).is_none(), "{delivery:?} earns no chip");+ }+ core.apply_command_base(OverlayCommand::EndAction(CursorAction::Click), false, false);+ }+ // A bare key press has no combo to show.+ core.apply_command_base(+ OverlayCommand::ShowKeyCombo(vec!["return".into()]),+ false,+ false,+ );+ core.tick_motion(0.3);+ assert!(shown(&core).is_none());+ }++ #[test]+ fn minimal_foreground_chip_waits_for_rest_then_fades_within_a_second() {+ let mut core = minimal_core();+ core.apply_command_base(+ OverlayCommand::BeginAction {+ action: CursorAction::Click,+ delivery: Some(DeliveryModifier::Foreground),+ target: Some(TargetModifier::Pixel),+ },+ false,+ false,+ );+ move_to(&mut core, 300.0, 240.0);+ settle_without_text(&mut core);+ // A real foreground click may hide the overlay while it is delivered,+ // so nothing plays until the action ends.+ for _ in 0..60 {+ core.tick_motion(FRAME);+ assert_eq!(+ core.session_badge_chip_alpha(),+ 0.0,+ "waits for the action to end"+ );+ }+ core.apply_command_base(OverlayCommand::EndAction(CursorAction::Click), false, false);++ let mut peak: f32 = 0.0;+ let mut visible_secs = 0.0;+ let mut rest_secs = 0.0;+ while core.minimal_chip.is_some() {+ core.tick_motion(FRAME);+ rest_secs += FRAME;+ let alpha = core.session_badge_chip_alpha();+ peak = peak.max(alpha);+ if alpha > 0.0 {+ visible_secs += FRAME;+ let layout = shown(&core).expect("the chip paints");+ assert_eq!(+ layout.label.as_ref().map(|label| label.text.as_str()),+ Some(FOREGROUND_CHIP_LABEL)+ );+ assert_eq!(+ layout.delivery_chip.map(|chip| chip.glyph),+ Some(crate::BadgeGlyph::Foreground)+ );+ assert!(layout.target_chip.is_none(), "no target chip");+ }+ if core.minimal_chip.is_some() {+ assert!(+ core.session_badge_needs_frame_tick(),+ "the chip keeps frames coming"+ );+ }+ assert!(rest_secs < 2.0, "the chip must end");+ }+ assert_eq!(peak, 1.0);+ assert!(+ (MINIMAL_CHIP_SECS - 0.05..=MINIMAL_CHIP_SECS + 0.05).contains(&rest_secs),+ "{rest_secs}"+ );+ assert!(visible_secs <= 1.0, "{visible_secs}");+ assert!(shown(&core).is_none(), "nothing lingers");+ }++ #[test]+ fn minimal_key_combo_chip_shows_the_combo_and_keeps_foreground() {+ let mut core = minimal_core();+ move_to(&mut core, 300.0, 240.0);+ settle_without_text(&mut core);+ core.apply_command_base(+ OverlayCommand::BeginAction {+ action: CursorAction::Key,+ delivery: Some(DeliveryModifier::Foreground),+ target: None,+ },+ false,+ false,+ );+ assert!(core.apply_command_base(+ OverlayCommand::ShowKeyCombo(vec!["cmd".into(), "c".into()]),+ false,+ false,+ ));+ core.apply_command_base(OverlayCommand::EndAction(CursorAction::Key), false, false);+ core.tick_motion(MINIMAL_CHIP_DELAY_SECS + MINIMAL_CHIP_FADE_IN_SECS + 0.1);+ let layout = shown(&core).expect("the combo paints");+ let expected = crate::badge_mode::format_key_combo(&["cmd".into(), "c".into()]);+ assert_eq!(+ layout.label.as_ref().map(|label| label.text.clone()),+ expected+ );+ assert!(layout.delivery_chip.is_some(), "the foreground mark stays");+ core.tick_motion(MINIMAL_CHIP_SECS);+ assert!(shown(&core).is_none());+ }++ #[test]+ fn minimal_name_shows_on_hover_and_with_peers_but_never_while_moving() {+ let mut core = minimal_core();+ move_to(&mut core, 300.0, 240.0);+ settle_without_text(&mut core);+ assert_eq!(core.session_badge_alpha(), 0.0);++ // Hover reveals the name at once.+ assert!(core.update_session_badge_hover(Some((core.pos.0, core.pos.1))));+ assert_eq!(core.session_badge_alpha(), 1.0);+ assert!(core.update_session_badge_hover(Some((900.0, 900.0))));+ assert_eq!(core.session_badge_alpha(), 0.0);++ // A second agent cursor on screen fades the name in quickly.+ core.peer_cursors_visible = true;+ assert!(core.session_badge_needs_frame_tick());+ core.tick_motion(MINIMAL_NAME_FADE_SECS + FRAME);+ assert_eq!(core.session_badge_alpha(), 1.0);+ let layout = shown(&core).expect("the name paints");+ assert_eq!(+ layout.label.map(|label| label.text),+ Some("Research run".to_owned())+ );++ // It drops the moment the cursor moves, and comes back at rest.+ move_to(&mut core, 600.0, 400.0);+ core.tick_motion(FRAME);+ settle_without_text(&mut core);+ core.tick_motion(MINIMAL_NAME_FADE_SECS + FRAME);+ assert_eq!(core.session_badge_alpha(), 1.0);++ core.peer_cursors_visible = false;+ core.tick_motion(MINIMAL_NAME_FADE_SECS + FRAME);+ assert_eq!(core.session_badge_alpha(), 0.0);+ }++ #[test]+ fn minimal_chip_plays_even_if_its_action_never_ends() {+ let mut core = minimal_core();+ move_to(&mut core, 300.0, 240.0);+ settle_without_text(&mut core);+ core.apply_command_base(+ OverlayCommand::BeginAction {+ action: CursorAction::Key,+ delivery: Some(DeliveryModifier::Foreground),+ target: None,+ },+ false,+ false,+ );+ core.tick_motion(MINIMAL_CHIP_ARM_TIMEOUT_SECS);+ assert_eq!(core.session_badge_chip_alpha(), 0.0);+ core.tick_motion(0.3);+ assert!(core.session_badge_chip_alpha() > 0.0);+ core.tick_motion(MINIMAL_CHIP_SECS);+ assert!(core.minimal_chip.is_none());+ }++ #[test]+ fn off_mode_paints_no_badge_at_all() {+ let mut core = minimal_core();+ core.badge_mode_override = Some(BadgeMode::Off);+ move_to(&mut core, 300.0, 240.0);+ settle_without_text(&mut core);+ core.peer_cursors_visible = true;+ core.apply_command_base(+ OverlayCommand::BeginAction {+ action: CursorAction::Key,+ delivery: Some(DeliveryModifier::Foreground),+ target: Some(TargetModifier::Desktop),+ },+ false,+ false,+ );+ core.apply_command_base(+ OverlayCommand::ShowKeyCombo(vec!["cmd".into(), "v".into()]),+ false,+ false,+ );+ assert!(!core.session_badge_needs_hover_poll());+ for _ in 0..90 {+ core.tick_motion(FRAME);+ assert!(shown(&core).is_none());+ assert!(!core.session_badge_is_visible());+ }+ }++ #[test]+ fn switching_modes_applies_to_a_cursor_already_on_screen() {+ let mut core = minimal_core();+ core.badge_mode_override = Some(BadgeMode::Verbose);+ move_to(&mut core, 300.0, 240.0);+ core.tick_motion(FRAME);+ assert_eq!(core.session_badge_alpha(), 1.0, "verbose names on reveal");+ core.badge_mode_override = Some(BadgeMode::Minimal);+ assert_eq!(core.session_badge_alpha(), 0.0, "minimal drops it at once");+ }+#[test]fn idle_hide_zero_keeps_a_positioned_session_cursor_visible() {let mut core = RenderStateCore::new(CursorConfig::default());@@ -1414,7 +1938,7 @@ mod session_badge_and_action_tests {#[test]fn session_badge_holds_then_fades_once() {- let mut core = RenderStateCore::new(CursorConfig::default());+ let mut core = verbose_core();assert_eq!(core.session_badge_alpha(), 0.0);assert!(core.apply_command_base(OverlayCommand::SetSessionLabel("Research".into()),@@ -1434,7 +1958,7 @@ mod session_badge_and_action_tests {#[test]fn repeated_session_label_metadata_does_not_restart_badge_timer() {- let mut core = RenderStateCore::new(CursorConfig::default());+ let mut core = verbose_core();core.apply_command_base(OverlayCommand::SetSessionLabel("Research".into()),false,@@ -1460,7 +1984,7 @@ mod session_badge_and_action_tests {#[test]fn revealing_hidden_cursor_restarts_badge_without_restarting_on_every_move() {- let mut core = RenderStateCore::new(CursorConfig::default());+ let mut core = verbose_core();core.apply_command_base(OverlayCommand::SetSessionLabel("Research".into()),false,@@ -1571,7 +2095,7 @@ mod session_badge_and_action_tests {#[test]fn modifiers_live_in_the_badge_then_fade_after_action_completion() {- let mut core = RenderStateCore::new(CursorConfig::default());+ let mut core = verbose_core();core.pos = (200.0, 200.0);core.apply_command_base(OverlayCommand::BeginAction {@@ -1607,7 +2131,7 @@ mod session_badge_and_action_tests {#[test]fn modifier_preemption_replaces_the_badge_context_without_cross_fading() {- let mut core = RenderStateCore::new(CursorConfig::default());+ let mut core = verbose_core();core.apply_command_base(OverlayCommand::BeginAction {action: CursorAction::Observe,diff --git a/libs/cua-driver/rust/crates/cursor-overlay/src/session_badge.rs b/libs/cua-driver/rust/crates/cursor-overlay/src/session_badge.rsindex 610316a025..f66e866ad1 100644--- a/libs/cua-driver/rust/crates/cursor-overlay/src/session_badge.rs+++ b/libs/cua-driver/rust/crates/cursor-overlay/src/session_badge.rs@@ -29,7 +29,6 @@ pub const BADGE_CHIP_GROUP_GAP: f32 = 7.0;const FONT_BYTES: &[u8] = include_bytes!("../assets/Inter.ttf");const FONT_SIZE: f32 = 11.5;const HORIZONTAL_PADDING: f32 = 10.0;-const TEXT_OPTICAL_Y_OFFSET: f32 = 1.0;#[derive(Debug, Clone, Copy, PartialEq)]pub struct BadgeExtents {@@ -202,6 +201,12 @@ pub fn sanitize_session_label(input: &str) -> Option<String> {Some(result)}+/// Height of a capital letter above the baseline at `font_size`.+fn cap_height(font: &fontdue::Font, font_size: f32) -> f32 {+ let metrics = font.metrics('H', font_size);+ metrics.height as f32 + metrics.ymin as f32+}+fn rounded_rect(rect: Rect, radius: f32) -> Option<Path> {const K: f32 = 0.552_284_8;let x = rect.x();@@ -376,12 +381,30 @@ pub fn session_badge_layout(input: SessionBadgeInput<'_>) -> Option<SessionBadgelet rect = Rect::from_xywh(x, y, badge_width, badge_height)?;let corner_radius = badge_height * 0.5;- let mut cursor_x = x + HORIZONTAL_PADDING * scale;+ // Centre the label and chips as one group, so a short label in a+ // minimum-width pill is not left-aligned.+ let group_gap = if label_data.is_some() && chip_count > 0 {+ BADGE_CHIP_GROUP_GAP * scale+ } else {+ 0.0+ };+ let content_width = text_width + group_gap + chip_width;+ let mut cursor_x = x + ((badge_width - content_width) * 0.5).max(HORIZONTAL_PADDING * scale);+ // Vertically, names centre the font's cap height so every name shares+ // one baseline. Labels without lowercase (key combos such as ⌘A, whose+ // symbols reach below the baseline) centre their own ink instead. Both+ // snap to whole device pixels so the glyph rounding cannot shift them.+ let baseline = y + badge_height * 0.5 + cap_height(font, font_size) * 0.5;+ let ascent = font+ .horizontal_line_metrics(font_size)+ .map_or(font_size * 0.8, |metrics| metrics.ascent);let label = label_data.map(|(text, bounds)| {- let origin = (- cursor_x - bounds.min_x,- y + (badge_height - bounds.height) * 0.5 - bounds.min_y + TEXT_OPTICAL_Y_OFFSET * scale,- );+ let origin_y = if text.chars().any(char::is_lowercase) {+ baseline - ascent+ } else {+ y + (badge_height - bounds.height) * 0.5 - bounds.min_y+ };+ let origin = (cursor_x - bounds.min_x, origin_y.round());cursor_x += bounds.width + BADGE_CHIP_GROUP_GAP * scale;BadgeLabelLayout { text, origin }});@@ -673,6 +696,119 @@ mod tests {assert!((label.origin.0 - (layout.rect.x() + HORIZONTAL_PADDING)).abs() < 1.5);}+ /// Painted ink box of a badge label, `(left, top, right, bottom)` in+ /// device pixels, using the same rounding as `paint_session_badge`.+ fn label_ink(layout: &SessionBadgeLayout) -> (f32, f32, f32, f32) {+ let font = font().unwrap();+ let label = layout.label.as_ref().unwrap();+ let text = text_layout(font, &label.text, FONT_SIZE * layout.scale);+ let (mut l, mut t, mut r, mut b) = (f32::MAX, f32::MAX, f32::MIN, f32::MIN);+ for glyph in text.glyphs() {+ if glyph.width == 0 || glyph.height == 0 {+ continue;+ }+ let x = (label.origin.0 + glyph.x).round();+ let y = (label.origin.1 + glyph.y).round();+ l = l.min(x);+ t = t.min(y);+ r = r.max(x + glyph.width as f32);+ b = b.max(y + glyph.height as f32);+ }+ (l, t, r, b)+ }++ #[test]+ fn every_badge_kind_centres_its_content_at_every_scale() {+ // Labels whose ink spans exactly the cap height are vertically+ // centred; every label and chip group is horizontally centred.+ let cases: &[(&str, bool, bool)] = &[+ ("⌘A", false, true),+ ("⌘C", false, true),+ ("⇧⌘Z", false, true),+ ("⌃⌥⇧⌘K", false, true),+ ("CTRL+C", false, true),+ ("Ctrl+C", false, false),+ ("research", false, false),+ ("writer", false, false),+ ("foreground", true, false),+ ("⌘V", true, true),+ ("A very long public session label", false, false),+ ];+ for scale in [1.0f32, 2.0, 3.0] {+ for &(text, foreground, caps) in cases {+ let layout = session_badge_layout(SessionBadgeInput {+ label: Some(text),+ delivery: foreground.then_some(DeliveryModifier::Foreground),+ target: None,+ cursor: (400.0 * scale, 60.0 * scale),+ backing_scale: scale,+ label_alpha: 1.0,+ chip_alpha: 1.0,+ clip: None,+ })+ .unwrap();+ let rect = layout.rect;+ let (l, t, r, b) = label_ink(&layout);+ let right_edge = layout+ .delivery_chip+ .map_or(r, |chip| chip.rect.x() + chip.rect.width());+ let left_gap = l - rect.x();+ let right_gap = rect.x() + rect.width() - right_edge;+ let tolerance = 1.0 * scale.max(1.0) + 0.01;+ assert!(+ (left_gap - right_gap).abs() <= tolerance,+ "{text} @{scale}x horizontal: left {left_gap} right {right_gap}"+ );+ if caps {+ let top_gap = t - rect.y();+ let bottom_gap = rect.y() + rect.height() - b;+ assert!(+ (top_gap - bottom_gap).abs() <= tolerance,+ "{text} @{scale}x vertical: top {top_gap} bottom {bottom_gap}"+ );+ }+ if let Some(chip) = layout.delivery_chip {+ let chip_mid = chip.rect.y() + chip.rect.height() * 0.5;+ assert!((chip_mid - (rect.y() + rect.height() * 0.5)).abs() < 0.01);+ }+ }+ }+ }++ #[test]+ fn labels_share_one_baseline() {+ for scale in [1.0f32, 2.0] {+ let origin_y = |text: &str| {+ session_badge_layout(SessionBadgeInput {+ label: Some(text),+ delivery: None,+ target: None,+ cursor: (200.0, 60.0),+ backing_scale: scale,+ label_alpha: 1.0,+ chip_alpha: 0.0,+ clip: None,+ })+ .unwrap()+ .label+ .unwrap()+ .origin+ .1+ };+ assert_eq!(origin_y("research"), origin_y("Typing"));+ assert_eq!(origin_y("research"), origin_y("writer"));+ assert_eq!(origin_y("research"), origin_y("Ctrl+C"));+ }+ }++ #[test]+ fn badge_font_has_the_mac_modifier_symbols() {+ let font = font().expect("badge font");+ for symbol in ['⌘', '⇧', '⌥', '⌃'] {+ assert_ne!(font.lookup_glyph_index(symbol), 0, "{symbol}");+ }+ }+#[test]fn long_label_stays_inside_the_bounded_badge() {let layout = session_badge_layout(SessionBadgeInput {diff --git a/libs/cua-driver/rust/crates/platform-linux/src/overlay.rs b/libs/cua-driver/rust/crates/platform-linux/src/overlay.rsindex 1d35cd553c..4e86686ab8 100644--- a/libs/cua-driver/rust/crates/platform-linux/src/overlay.rs+++ b/libs/cua-driver/rust/crates/platform-linux/src/overlay.rs@@ -335,6 +335,9 @@ pub fn init(cfg: CursorConfig) {reduced_motion: selection.reduced_motion,},),+ CursorEvent::KeyCombo { session, keys } => {+ (session, OverlayCommand::ShowKeyCombo(keys))+ }CursorEvent::SelectMotion { session, motion } => {(session, OverlayCommand::ApplyMotion(motion))}@@ -524,6 +527,17 @@ fn dispatch_shell_helper_command(key: &str, cmd: &OverlayCommand, semantic: booldelivery,target,} if semantic => {+ // The GNOME helper paints its own single-cursor badge. Under the+ // minimal badge it gets only foreground moments; under `off`, no+ // chips at all.+ let (delivery, target) = match cursor_overlay::badge_mode::active() {+ cursor_overlay::BadgeMode::Verbose => (*delivery, *target),+ cursor_overlay::BadgeMode::Minimal => (+ delivery.filter(|value| *value == cursor_overlay::DeliveryModifier::Foreground),+ None,+ ),+ cursor_overlay::BadgeMode::Off => (None, None),+ };crate::wayland::shell_helper::set_cursor_state(action.as_str(),delivery.as_ref().map_or("", |value| value.as_str()),@@ -535,8 +549,12 @@ fn dispatch_shell_helper_command(key: &str, cmd: &OverlayCommand, semantic: boolcrate::wayland::shell_helper::set_cursor_state(action.as_str(), "", "", false);}OverlayCommand::SetSessionLabel(label) if semantic => {+ // The helper has no hover reveal and draws one cursor, so the+ // minimal badge never shows the name there.+ let shown = cursor_overlay::badge_mode::active() == cursor_overlay::BadgeMode::Verbose;crate::wayland::shell_helper::set_session_label(cursor_overlay::sanitize_session_label(label)+ .filter(|_| shown).as_deref().unwrap_or(""),);@@ -4400,6 +4418,7 @@ mod tests {map.platform.scr_h = 2160;let cursor = map.cursors.get_mut("default").unwrap();cursor.core.pos = (4000.0, 1000.0);+ cursor.core.badge_mode_override = Some(cursor_overlay::BadgeMode::Verbose);cursor.apply_command(OverlayCommand::SetSessionLabel("research-run".to_owned()));let tiles = render_x11_tiles(&map);@@ -4419,6 +4438,7 @@ mod tests {map.platform.scr_h = 2160;let cursor = map.cursors.get_mut("default").unwrap();cursor.core.pos = (4000.0, 1000.0);+ cursor.core.badge_mode_override = Some(cursor_overlay::BadgeMode::Verbose);cursor.apply_command(OverlayCommand::BeginAction {action: CursorAction::Click,delivery: Some(cursor_overlay::DeliveryModifier::Foreground),@@ -4432,6 +4452,27 @@ mod tests {assert_eq!(tiles[0].bounds.height, 128);}+ #[test]+ fn minimal_badge_keeps_a_lone_resting_cursor_tile_compact() {+ let mut map = default_render_map();+ map.platform.scr_w = 7680;+ map.platform.scr_h = 2160;+ let cursor = map.cursors.get_mut("default").unwrap();+ cursor.core.pos = (4000.0, 1000.0);+ cursor.core.badge_mode_override = Some(cursor_overlay::BadgeMode::Minimal);+ cursor.apply_command(OverlayCommand::SetSessionLabel("research-run".to_owned()));+ cursor.apply_command(OverlayCommand::BeginAction {+ action: CursorAction::Click,+ delivery: Some(cursor_overlay::DeliveryModifier::Background),+ target: Some(cursor_overlay::TargetModifier::Pixel),+ });++ let tiles = render_x11_tiles(&map);++ assert_eq!(tiles.len(), 1);+ assert_eq!(tiles[0].bounds.width, 128, "no name and no chips");+ }+#[test]fn cursor_tiles_clip_at_screen_edges_and_skip_hidden_cursors() {let mut map = default_render_map();diff --git a/libs/cua-driver/rust/crates/platform-linux/src/tools/impl_.rs b/libs/cua-driver/rust/crates/platform-linux/src/tools/impl_.rsindex c226b0a4ed..31ec9488d4 100644--- a/libs/cua-driver/rust/crates/platform-linux/src/tools/impl_.rs+++ b/libs/cua-driver/rust/crates/platform-linux/src/tools/impl_.rs@@ -13313,7 +13313,10 @@ impl Tool for GetConfigTool {"platform": "linux","capture_mode": cfg.capture_mode,"max_image_dimension": cfg.max_image_dimension,- "cursor": { "motion": cursor_overlay::motion_defaults::read_saved().config_json() },+ "cursor": {+ "motion": cursor_overlay::motion_defaults::read_saved().config_json(),+ "badges": cursor_overlay::badge_mode::read_saved().as_str(),+ },"experimental_pip": pip_enabled,"experimental_pip_geometry": pip_geometry}))@@ -13325,6 +13328,7 @@ impl Tool for GetConfigTool {fn with_cursor_motion_config_properties(mut schema: Value) -> Value {if let Some(properties) = schema.get_mut("properties").and_then(Value::as_object_mut) {properties.extend(cursor_overlay::motion_defaults::config_schema_properties());+ properties.extend(cursor_overlay::badge_mode::config_schema_properties());}schema}@@ -13347,7 +13351,9 @@ impl Tool for SetConfigTool {Linux ships only the trait stub today — see issue #1729).\n\n\`cursor.motion.style`, `cursor.motion.timing` and `cursor.motion.effects.<name>` \(`on`, `off`, or `default`) save the default cursor motion for sessions started afterwards. \- `cursor.motion: \"default\"` clears every saved cursor motion default.".into(),+ `cursor.motion: \"default\"` clears every saved cursor motion default.\n\n\+ `cursor.badges` (`minimal` default, `verbose`, or `off`) sets the agent cursor badge \+ for every cursor at once.".into(),input_schema: with_cursor_motion_config_properties(json!({"type":"object","properties":{"capture_mode":{"type":"string","enum":["ax","vision"],"description":"Default capture mode for get_window_state. (\"som\"/\"screenshot\" still decode as deprecated aliases.)"},"max_image_dimension":{"type":"integer","description":"Max dimension for screenshot resizing (0 = no limit)."},@@ -13373,11 +13379,16 @@ impl Tool for SetConfigTool {Ok(keys) => keys,Err(message) => return ToolResult::error(message),};+ let badge_key = match cursor_overlay::badge_mode::apply_config_args(&args) {+ Ok(key) => key,+ Err(message) => return ToolResult::error(message),+ };let mut cfg = self.state.config.write().unwrap();let mut parts: Vec<String> = motion_keys.iter().map(|key| format!("{key} (applies to sessions started from now on)")).collect();+ parts.extend(badge_key.map(|key| format!("{key} (applies now)")));if let Some(mode) = args.opt_str("capture_mode") {if let Err(e) =pip_preview::write_config_key("capture_mode", Value::String(mode.clone()))diff --git a/libs/cua-driver/rust/crates/platform-linux/src/wayland/overlay.rs b/libs/cua-driver/rust/crates/platform-linux/src/wayland/overlay.rsindex f14e49a07d..1fe4cdf77b 100644--- a/libs/cua-driver/rust/crates/platform-linux/src/wayland/overlay.rs+++ b/libs/cua-driver/rust/crates/platform-linux/src/wayland/overlay.rs@@ -861,6 +861,7 @@ fn earliest_idle_fade_wait(cores: &CursorMap<RenderStateCore>) -> Option<Duratio/// Advance every cursor and return the keys whose planned glide just ended.fn tick_all_cores(cores: &mut CursorMap<RenderStateCore>, dt: f64) -> Vec<CursorKey> {+ cursor_overlay::render_map::update_peer_presence(cores.values_mut());cores.iter_mut().filter_map(|(key, core)| core.tick_motion(dt).then(|| key.clone()))diff --git a/libs/cua-driver/rust/crates/platform-macos/src/cursor/overlay.rs b/libs/cua-driver/rust/crates/platform-macos/src/cursor/overlay.rsindex 7b88534c6a..358037ea5d 100644--- a/libs/cua-driver/rust/crates/platform-macos/src/cursor/overlay.rs+++ b/libs/cua-driver/rust/crates/platform-macos/src/cursor/overlay.rs@@ -253,6 +253,9 @@ pub fn init(cfg: CursorConfig) {reduced_motion: selection.reduced_motion,},),+ CursorEvent::KeyCombo { session, keys } => {+ (session, OverlayCommand::ShowKeyCombo(keys))+ }CursorEvent::SelectMotion { session, motion } => {(session, OverlayCommand::ApplyMotion(motion))}diff --git a/libs/cua-driver/rust/crates/platform-macos/src/tools/get_config.rs b/libs/cua-driver/rust/crates/platform-macos/src/tools/get_config.rsindex 0db24fb1de..ed98ea5e3c 100644--- a/libs/cua-driver/rust/crates/platform-macos/src/tools/get_config.rs+++ b/libs/cua-driver/rust/crates/platform-macos/src/tools/get_config.rs@@ -84,6 +84,7 @@ impl Tool for GetConfigTool {},"cursor": {"motion": cursor_overlay::motion_defaults::read_saved().config_json(),+ "badges": cursor_overlay::badge_mode::read_saved().as_str(),},"experimental_pip": pip_enabled,"experimental_pip_geometry": pip_geometry,diff --git a/libs/cua-driver/rust/crates/platform-macos/src/tools/set_config.rs b/libs/cua-driver/rust/crates/platform-macos/src/tools/set_config.rsindex 731335df73..dd4c83e8dd 100644--- a/libs/cua-driver/rust/crates/platform-macos/src/tools/set_config.rs+++ b/libs/cua-driver/rust/crates/platform-macos/src/tools/set_config.rs@@ -23,6 +23,7 @@ static DEF: std::sync::OnceLock<ToolDef> = std::sync::OnceLock::new();fn with_cursor_motion_properties(mut schema: Value) -> Value {if let Some(properties) = schema.get_mut("properties").and_then(Value::as_object_mut) {properties.extend(cursor_overlay::motion_defaults::config_schema_properties());+ properties.extend(cursor_overlay::badge_mode::config_schema_properties());}schema}@@ -42,7 +43,9 @@ fn def() -> &'static ToolDef {cursor.motion.effects.<trail|glow|magnet|ripple|squish> are saved to \~/.cua-driver/config.json and seed sessions started afterwards. \start_session cursor_motion and set_agent_cursor_motion override them; \- reduced motion always wins."+ reduced motion always wins.\n\nAgent cursor badge: cursor.badges is \+ minimal (default), verbose or off, saved to ~/.cua-driver/config.json \+ and applied to every cursor at once.".into(),input_schema: with_cursor_motion_properties(serde_json::json!({"type": "object",@@ -104,6 +107,11 @@ impl Tool for SetConfigTool {Err(message) => return ToolResult::error(message),};+ let badge_key = match cursor_overlay::badge_mode::apply_config_args(&args) {+ Ok(key) => key,+ Err(message) => return ToolResult::error(message),+ };+let max_dim: Option<u32> = match args.opt_u64("max_image_dimension") {Some(dim) => match u32::try_from(dim) {Ok(d) => Some(d),@@ -177,6 +185,9 @@ impl Tool for SetConfigTool {motion_keys.join(", ")));}+ if let Some(key) = badge_key {+ pip_note.push_str(&format!(" — saved {key} (applies now)"));+ }let scope_note = if session_id.is_some() {" (session-scoped; persisted default unchanged)"} else {diff --git a/libs/cua-driver/rust/crates/platform-windows/src/overlay.rs b/libs/cua-driver/rust/crates/platform-windows/src/overlay.rsindex b00c19ed00..7a2378e6a0 100644--- a/libs/cua-driver/rust/crates/platform-windows/src/overlay.rs+++ b/libs/cua-driver/rust/crates/platform-windows/src/overlay.rs@@ -198,6 +198,9 @@ pub fn init(cfg: CursorConfig) {reduced_motion: selection.reduced_motion,},),+ CursorEvent::KeyCombo { session, keys } => {+ (session, OverlayCommand::ShowKeyCombo(keys))+ }CursorEvent::SelectMotion { session, motion } => {(session, OverlayCommand::ApplyMotion(motion))}diff --git a/libs/cua-driver/rust/crates/platform-windows/src/tools/impl_.rs b/libs/cua-driver/rust/crates/platform-windows/src/tools/impl_.rsindex 9c0c95823b..1dd3d2cebb 100644--- a/libs/cua-driver/rust/crates/platform-windows/src/tools/impl_.rs+++ b/libs/cua-driver/rust/crates/platform-windows/src/tools/impl_.rs@@ -8749,7 +8749,10 @@ impl Tool for GetConfigTool {"capture_mode": cfg.capture_mode,"max_image_dimension": cfg.max_image_dimension,"agent_cursor": { "enabled": cursor_enabled },- "cursor": { "motion": cursor_overlay::motion_defaults::read_saved().config_json() },+ "cursor": {+ "motion": cursor_overlay::motion_defaults::read_saved().config_json(),+ "badges": cursor_overlay::badge_mode::read_saved().as_str(),+ },"experimental_pip": pip_enabled,"experimental_pip_geometry": pip_geometry,});@@ -8764,6 +8767,7 @@ impl Tool for GetConfigTool {fn with_cursor_motion_config_properties(mut schema: Value) -> Value {if let Some(properties) = schema.get_mut("properties").and_then(Value::as_object_mut) {properties.extend(cursor_overlay::motion_defaults::config_schema_properties());+ properties.extend(cursor_overlay::badge_mode::config_schema_properties());}schema}@@ -8787,7 +8791,8 @@ impl Tool for SetConfigTool {- `max_image_dimension` (integer)\n\- `experimental_pip` (boolean; persisted to config.json, applies on next daemon restart — Windows backend stubbed today, see issue #1729)\n\- `experimental_pip_geometry` (string `WxH` or `WxH+X+Y`; persisted; applies on next daemon restart)\n\n\- - `cursor.motion.style`, `cursor.motion.timing`, `cursor.motion.effects.<name>` (`on`, `off`, or `default`) — saved default cursor motion for sessions started afterwards. `cursor.motion: \"default\"` clears every saved cursor motion default.\n\n\+ - `cursor.motion.style`, `cursor.motion.timing`, `cursor.motion.effects.<name>` (`on`, `off`, or `default`) — saved default cursor motion for sessions started afterwards. `cursor.motion: \"default\"` clears every saved cursor motion default.\n\+ - `cursor.badges` (`minimal` default, `verbose`, or `off`) — agent cursor badge; applies to every cursor at once.\n\n\Returns the full updated config in the same shape as `get_config`.".into(),input_schema: with_cursor_motion_config_properties(json!({"type":"object","properties":{"capture_mode":{"type":"string","enum":["ax","vision"],"description":"DEPRECATED and ignored — get_window_state always returns both the UIA tree and a screenshot. Still accepted/persisted for back-compat but has no effect. (\"som\"/\"screenshot\" still decode as deprecated aliases.)"},@@ -8814,7 +8819,11 @@ impl Tool for SetConfigTool {Err(message) => return ToolResult::error(message),};let mut cfg = self.state.config.write().unwrap();- let mut applied = !motion_keys.is_empty();+ let badge_key = match cursor_overlay::badge_mode::apply_config_args(&args) {+ Ok(key) => key,+ Err(message) => return ToolResult::error(message),+ };+ let mut applied = !motion_keys.is_empty() || badge_key.is_some();if let Some(mode) = args.get("capture_mode").and_then(|v| v.as_str()) {cfg.capture_mode = mode.to_owned();if let Err(e) =diff --git a/scripts/docs-generators/cli-specs/cua-driver-mcp-linux.json b/scripts/docs-generators/cli-specs/cua-driver-mcp-linux.jsonindex 02acd029a9..a5be6e6107 100644--- a/scripts/docs-generators/cli-specs/cua-driver-mcp-linux.json+++ b/scripts/docs-generators/cli-specs/cua-driver-mcp-linux.json@@ -2118,7 +2118,7 @@"read_only": true},{- "description": "Update cua-driver-rs configuration. capture_mode / max_image_dimension take effect immediately.\n\nPass each setting as its own field: `{\"capture_mode\": \"som\", \"max_image_dimension\": 0}`.\n\nThe experimental_pip keys persist to ~/.cua-driver/config.json and apply on next daemon restart (the PiP backend is initialised once at startup; Linux ships only the trait stub today — see issue #1729).\n\n`cursor.motion.style`, `cursor.motion.timing` and `cursor.motion.effects.<name>` (`on`, `off`, or `default`) save the default cursor motion for sessions started afterwards. `cursor.motion: \"default\"` clears every saved cursor motion default.",+ "description": "Update cua-driver-rs configuration. capture_mode / max_image_dimension take effect immediately.\n\nPass each setting as its own field: `{\"capture_mode\": \"som\", \"max_image_dimension\": 0}`.\n\nThe experimental_pip keys persist to ~/.cua-driver/config.json and apply on next daemon restart (the PiP backend is initialised once at startup; Linux ships only the trait stub today — see issue #1729).\n\n`cursor.motion.style`, `cursor.motion.timing` and `cursor.motion.effects.<name>` (`on`, `off`, or `default`) save the default cursor motion for sessions started afterwards. `cursor.motion: \"default\"` clears every saved cursor motion default.\n\n`cursor.badges` (`minimal` default, `verbose`, or `off`) sets the agent cursor badge for every cursor at once.","destructive": false,"idempotent": true,"input_schema": {@@ -2132,6 +2132,16 @@],"type": "string"},+ "cursor.badges": {+ "description": "Agent cursor badge. minimal (default): no badge at rest; a brief chip for a foreground moment or a key combo, and the session name on hover or when two or more agent cursors are on screen. verbose: the earlier badge with the session name and delivery/target chips on every action. off: no badge. Applies immediately to every cursor.",+ "enum": [+ "minimal",+ "verbose",+ "off",+ "default"+ ],+ "type": "string"+ },"cursor.motion": {"description": "Pass `default` to clear every saved cursor motion default.","enum": [diff --git a/scripts/docs-generators/cli-specs/cua-driver-mcp-macos.json b/scripts/docs-generators/cli-specs/cua-driver-mcp-macos.jsonindex 8169cb81b4..755b65e64a 100644--- a/scripts/docs-generators/cli-specs/cua-driver-mcp-macos.json+++ b/scripts/docs-generators/cli-specs/cua-driver-mcp-macos.json@@ -1773,12 +1773,22 @@"read_only": true},{- "description": "Update cua-driver-rs configuration. Changes to max_image_dimension take effect immediately. The experimental_pip keys are persisted to ~/.cua-driver/config.json and take effect on the next daemon restart (the PiP backend is initialised once at startup).\n\nNote: capture_mode is a per-call param (on get_window_state / click), not a stored setting. Capture modality is selected by each action's target; the old capture_scope config key is retired.\n\nCursor motion defaults: cursor.motion.style, cursor.motion.timing and cursor.motion.effects.<trail|glow|magnet|ripple|squish> are saved to ~/.cua-driver/config.json and seed sessions started afterwards. start_session cursor_motion and set_agent_cursor_motion override them; reduced motion always wins.",+ "description": "Update cua-driver-rs configuration. Changes to max_image_dimension take effect immediately. The experimental_pip keys are persisted to ~/.cua-driver/config.json and take effect on the next daemon restart (the PiP backend is initialised once at startup).\n\nNote: capture_mode is a per-call param (on get_window_state / click), not a stored setting. Capture modality is selected by each action's target; the old capture_scope config key is retired.\n\nCursor motion defaults: cursor.motion.style, cursor.motion.timing and cursor.motion.effects.<trail|glow|magnet|ripple|squish> are saved to ~/.cua-driver/config.json and seed sessions started afterwards. start_session cursor_motion and set_agent_cursor_motion override them; reduced motion always wins.\n\nAgent cursor badge: cursor.badges is minimal (default), verbose or off, saved to ~/.cua-driver/config.json and applied to every cursor at once.","destructive": false,"idempotent": true,"input_schema": {"additionalProperties": false,"properties": {+ "cursor.badges": {+ "description": "Agent cursor badge. minimal (default): no badge at rest; a brief chip for a foreground moment or a key combo, and the session name on hover or when two or more agent cursors are on screen. verbose: the earlier badge with the session name and delivery/target chips on every action. off: no badge. Applies immediately to every cursor.",+ "enum": [+ "minimal",+ "verbose",+ "off",+ "default"+ ],+ "type": "string"+ },"cursor.motion": {"description": "Pass `default` to clear every saved cursor motion default.","enum": [diff --git a/scripts/docs-generators/cli-specs/cua-driver-mcp-windows.json b/scripts/docs-generators/cli-specs/cua-driver-mcp-windows.jsonindex 3ee1ebce92..989d2e8683 100644--- a/scripts/docs-generators/cli-specs/cua-driver-mcp-windows.json+++ b/scripts/docs-generators/cli-specs/cua-driver-mcp-windows.json@@ -1813,7 +1813,7 @@"read_only": true},{- "description": "Write a setting into the persistent driver config. Values take effect immediately. Pass each setting as its own field.\n\nKnown keys:\n- `capture_mode` (string: `vision` | `ax` | `som`) — DEPRECATED and ignored; `get_window_state` always returns both the UIA tree and a screenshot. Still accepted/persisted for back-compat but has no effect.\n- `max_image_dimension` (integer)\n- `experimental_pip` (boolean; persisted to config.json, applies on next daemon restart — Windows backend stubbed today, see issue #1729)\n- `experimental_pip_geometry` (string `WxH` or `WxH+X+Y`; persisted; applies on next daemon restart)\n\n- `cursor.motion.style`, `cursor.motion.timing`, `cursor.motion.effects.<name>` (`on`, `off`, or `default`) — saved default cursor motion for sessions started afterwards. `cursor.motion: \"default\"` clears every saved cursor motion default.\n\nReturns the full updated config in the same shape as `get_config`.",+ "description": "Write a setting into the persistent driver config. Values take effect immediately. Pass each setting as its own field.\n\nKnown keys:\n- `capture_mode` (string: `vision` | `ax` | `som`) — DEPRECATED and ignored; `get_window_state` always returns both the UIA tree and a screenshot. Still accepted/persisted for back-compat but has no effect.\n- `max_image_dimension` (integer)\n- `experimental_pip` (boolean; persisted to config.json, applies on next daemon restart — Windows backend stubbed today, see issue #1729)\n- `experimental_pip_geometry` (string `WxH` or `WxH+X+Y`; persisted; applies on next daemon restart)\n\n- `cursor.motion.style`, `cursor.motion.timing`, `cursor.motion.effects.<name>` (`on`, `off`, or `default`) — saved default cursor motion for sessions started afterwards. `cursor.motion: \"default\"` clears every saved cursor motion default.\n- `cursor.badges` (`minimal` default, `verbose`, or `off`) — agent cursor badge; applies to every cursor at once.\n\nReturns the full updated config in the same shape as `get_config`.","destructive": false,"idempotent": true,"input_schema": {@@ -1827,6 +1827,16 @@],"type": "string"},+ "cursor.badges": {+ "description": "Agent cursor badge. minimal (default): no badge at rest; a brief chip for a foreground moment or a key combo, and the session name on hover or when two or more agent cursors are on screen. verbose: the earlier badge with the session name and delivery/target chips on every action. off: no badge. Applies immediately to every cursor.",+ "enum": [+ "minimal",+ "verbose",+ "off",+ "default"+ ],+ "type": "string"+ },"cursor.motion": {"description": "Pass `default` to clear every saved cursor motion default.","enum": [diff --git a/scripts/docs-generators/cli-specs/cua-driver.json b/scripts/docs-generators/cli-specs/cua-driver.jsonindex cd969bb101..df8a8291db 100644--- a/scripts/docs-generators/cli-specs/cua-driver.json+++ b/scripts/docs-generators/cli-specs/cua-driver.json@@ -1009,7 +1009,7 @@"type": "String"}],- "discussion": "Cursor motion defaults are saved keys that apply to sessions started afterwards: cursor.motion.style (signature_arc, spring_settle, magnetic, comet_swoop, adaptive, classic), cursor.motion.timing (native, fitts, fixed) and cursor.motion.effects.<trail|glow|magnet|ripple|squish> (on, off, default). Use default for a key to clear it, or cursor.motion default to clear all. A start_session cursor_motion or a set_agent_cursor_motion call overrides the saved default.",+ "discussion": "Cursor motion defaults are saved keys that apply to sessions started afterwards: cursor.motion.style (signature_arc, spring_settle, magnetic, comet_swoop, adaptive, classic), cursor.motion.timing (native, fitts, fixed) and cursor.motion.effects.<trail|glow|magnet|ripple|squish> (on, off, default). Use default for a key to clear it, or cursor.motion default to clear all. A start_session cursor_motion or a set_agent_cursor_motion call overrides the saved default. cursor.badges (minimal, verbose, off) sets the agent cursor badge for every cursor at once; minimal is the default.","examples": [{"command": "cua-driver config set max_image_dimension 1568",