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.

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.mdx
index 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 cursor
The 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.
-![All session badge combinations for background and foreground delivery across accessibility, pixel, browser, and desktop targets](https://github.com/user-attachments/assets/071dbfd0-b0d4-442f-9654-994c84db3029)
+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:
+
+![Verbose badge combinations for background and foreground delivery across accessibility, pixel, browser, and desktop targets](https://github.com/user-attachments/assets/071dbfd0-b0d4-442f-9654-994c84db3029)
```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.mdx
index 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_dimension
Set 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 output
cua-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.mdx
index 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 stor
Cursor motion defaults: cursor.motion.style, cursor.motion.timing and cursor.motion.effects.&lt;trail|glow|magnet|ripple|squish&gt; 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.md
index 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.md
index 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 fill
from the built-in session palette, so concurrent agents remain visually
distinct.
-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 a
session-accent gradient and a circular session marker. The session name appears
when the cursor is first revealed, remains fully visible for two seconds, then
fades over 400 milliseconds while the cursor stays available. Moving the human
diff --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.rs
index 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.rs
index 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.rs
index 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.rs
new file mode 100644
index 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.rs
index 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 pointer
pub 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.rs
index 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.rs
index 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.rs
index 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<SessionBadge
let 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.rs
index 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: bool
delivery,
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: bool
crate::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_.rs
index 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.rs
index 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.rs
index 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.rs
index 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.rs
index 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.rs
index 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_.rs
index 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.json
index 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.json
index 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.json
index 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.json
index 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",