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
feat(cua-driver): cursor floats while moving, soft halo, lean/heading rotation modes (#6325)
Francesco Bonaccib186977ee093
diff --git a/docs/content/docs/cua-driver/guides/operate.mdx b/docs/content/docs/cua-driver/guides/operate.mdxindex 21f8ea2c5a..d5ab984334 100644--- a/docs/content/docs/cua-driver/guides/operate.mdx+++ b/docs/content/docs/cua-driver/guides/operate.mdx@@ -329,19 +329,25 @@ to another release.## Personalize the cursor-The agent's cursor is an overlay, not the real pointer: a plain, upright,+The agent's cursor is an overlay, not the real pointer: a plainsession-colored arrow (`cua.default`, the only built-in theme). Its color tellsagents apart. It is a visual aid, not an authorization signal.-By default the arrow only floats gently up and down while it rests, staying-upright. It shows no marks next to it, and no glow, ripple or bounce. Each-extra is a setting you can change for every cursor at once:+By default the arrow floats gently, with a soft halo in its own+color behind it. While it moves, its tip points along the path; it is upright+again whenever it arrives. It shows no marks next to it, and no ripple or+bounce. Each extra is a setting you can change for every cursor at once:-- `cursor.float`: the gentle float while the cursor rests. It is on by- default; `cua-driver config set cursor.float off` keeps the cursor still.+- `cursor.float`: the gentle float, a slow sway and bob with a slight tilt.+ It is on by default and settles to zero before every click, drag, scroll+ and typing, so they land exactly;+ `cua-driver config set cursor.float off` keeps the cursor still.+- `cursor.halo`: the soft glow behind the arrow. On by default.- `cursor.marks`: a small mark for what the agent is doing (observing,clicking, typing, pressing keys, scrolling and more).-- `cursor.rotate`: the arrow turns toward where it is going.+- `cursor.rotate`: by default (`heading`) the tip points along the path while+ the cursor moves, and it is upright again for every click. `lean` only tilts+ it a little toward where it is going; `off` keeps it upright.- `cursor.motion.effects.glow`, `.ripple` and `.squish`: a glow while it moves,a ring on each click, and a small press on each click.diff --git a/docs/content/docs/cua-driver/reference/cli/serve-and-configure.mdx b/docs/content/docs/cua-driver/reference/cli/serve-and-configure.mdxindex dfc33c6fc4..c6eb3f864d 100644--- a/docs/content/docs/cua-driver/reference/cli/serve-and-configure.mdx+++ b/docs/content/docs/cua-driver/reference/cli/serve-and-configure.mdx@@ -635,7 +635,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.badges (minimal, verbose, off) sets the agent cursor badge for every cursor at once; minimal is the default. cursor.float (resting float) is on, off or default and on by default; cursor.marks (action marks) and cursor.rotate (turn toward travel) are on, off or default and off by default. All three apply to every cursor at once.+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. cursor.float (float at rest and while moving) and cursor.halo (soft glow) are on, off or default and on by default; cursor.marks (action marks) is on, off or default and off by default; cursor.rotate is heading (default), lean, off or default. All apply to every cursor at once.```text outputcua-driver config set <key> <value>diff --git a/docs/content/docs/cua-driver/reference/mcp-tools/batch-recording-and-settings.mdx b/docs/content/docs/cua-driver/reference/mcp-tools/batch-recording-and-settings.mdxindex 42a98f4af1..2d88456ac3 100644--- a/docs/content/docs/cua-driver/reference/mcp-tools/batch-recording-and-settings.mdx+++ b/docs/content/docs/cua-driver/reference/mcp-tools/batch-recording-and-settings.mdx@@ -286,7 +286,7 @@ Cursor motion defaults: cursor.motion.style, cursor.motion.timing and cursor.motAgent cursor badge: cursor.badges is minimal (default), verbose or off, saved to ~/.cua-driver/config.json and applied to every cursor at once.-Agent cursor extras: cursor.float (resting float) is on (default), off or default; cursor.marks (action marks) and cursor.rotate (turn toward travel) are on, off (default) or default. All are saved to ~/.cua-driver/config.json and applied to every cursor at once.+Agent cursor extras: cursor.float (float at rest and while moving) and cursor.halo (soft glow) are on (default), off or default; cursor.marks (action marks) is on, off (default) or default; cursor.rotate is heading (default), lean, off or default. All are saved to ~/.cua-driver/config.json and applied to every cursor at once.**macOS parameters**@@ -308,7 +308,7 @@ The experimental_pip keys persist to ~/.cua-driver/config.json and apply on next`cursor.badges` (`minimal` default, `verbose`, or `off`) sets the agent cursor badge for every cursor at once.-`cursor.float` (resting float) is `on` (default), `off` or `default`; `cursor.marks` (action marks) and `cursor.rotate` (turn toward travel) are `on`, `off` (default) or `default`. All apply to every cursor at once.+`cursor.float` (float at rest and while moving) and `cursor.halo` (soft glow) are `on` (default), `off` or `default`; `cursor.marks` (action marks) is `on`, `off` (default) or `default`; `cursor.rotate` is `heading` (default), `lean`, `off` or `default`. All apply to every cursor at once.**Linux parameters**@@ -331,7 +331,7 @@ Known keys:- `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.-- `cursor.float` (resting float): `on` (default), `off`, or `default`. `cursor.marks` (action marks), `cursor.rotate` (turn toward travel): `on`, `off` (default), or `default`. All apply to every cursor at once.+- `cursor.float` (float at rest and while moving), `cursor.halo` (soft glow): `on` (default), `off`, or `default`. `cursor.marks` (action marks): `on`, `off` (default), or `default`. `cursor.rotate`: `heading` (default), `lean`, `off`, or `default`. All apply to every cursor at once.Returns the full updated config in the same shape as `get_config`.@@ -351,7 +351,8 @@ 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-float"></span>`cursor.float` | `"on" \| "off" \| "default"` | | Agent cursor resting float: a slow up-and-down bob while the cursor rests; the arrow stays upright. on (default). off: the cursor stays still at rest and the overlay stops redrawing. Applies immediately to every cursor. |+| <span id="set_config--cursor-float"></span>`cursor.float` | `"on" \| "off" \| "default"` | | Agent cursor float: a slow four-second sway, bob and slight tilt, at rest and while moving, that eases to zero on every arrival and holds there for the click, drag, drop, scroll or typing, so they land exactly upright on the hotspot. on (default). off: the cursor never floats and a resting overlay stops redrawing. Applies immediately to every cursor. |+| <span id="set_config--cursor-halo"></span>`cursor.halo` | `"on" \| "off" \| "default"` | | Agent cursor halo: a soft glow in the cursor's colour behind the arrow, so it is easier to follow on any background. on (default). off: no halo. Applies immediately to every cursor. || <span id="set_config--cursor-marks"></span>`cursor.marks` | `"on" \| "off" \| "default"` | | Agent cursor action marks: the small cue next to the arrow for observe, click, type, keys, scroll, drag, apps, files, recording and system calls, plus the focus box around a clicked element on macOS. off (default): a plain arrow. 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. |@@ -361,7 +362,7 @@ Returns the full updated config in the same shape as `get_config`.| <span id="set_config--cursor-motion-effects-trail"></span>`cursor.motion.effects.trail` | `"on" \| "off" \| "default"` | | Saved default for the `trail` cursor effect: on, off, or default (the style's own). Omit the key to leave it unchanged. || <span id="set_config--cursor-motion-style"></span>`cursor.motion.style` | `"signature_arc" \| "spring_settle" \| "magnetic" \| "comet_swoop" \| "adaptive" \| "classic"` | | Saved default cursor motion style for new sessions. Overridden by start_session cursor_motion and set_agent_cursor_motion; reduced motion always wins. Built-in default: signature_arc. || <span id="set_config--cursor-motion-timing"></span>`cursor.motion.timing` | `"native" \| "fitts" \| "fixed" \| "relaxed" \| "steady" \| "calm" \| "deliberate"` | | Saved default cursor move timing for new sessions. Built-in default: steady (a 600 ms floor on every move). |-| <span id="set_config--cursor-rotate"></span>`cursor.rotate` | `"on" \| "off" \| "default"` | | Agent cursor rotation: the arrow turns toward the direction it moves and settles upright on arrival. off (default): the arrow always stays upright. Applies immediately to every cursor. |+| <span id="set_config--cursor-rotate"></span>`cursor.rotate` | `"off" \| "lean" \| "heading" \| "on" \| "default"` | | Agent cursor rotation while it moves: heading (default) points the tip along the path; lean tilts the arrow at most 30 degrees toward where it is going (on is the same as heading). Both return upright before arrival, so clicks, typing and scrolling stay upright. off: the arrow always stays upright. Applies immediately to every cursor. || <span id="set_config--max_image_dimension"></span>`max_image_dimension` | `integer` | | Max dimension for screenshot resizing (0 = no limit). || <span id="set_config--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. |diff --git a/libs/cua-driver/docs/cursor-themes.md b/libs/cua-driver/docs/cursor-themes.mdindex 51314dadc5..ccfd82d391 100644--- a/libs/cua-driver/docs/cursor-themes.md+++ b/libs/cua-driver/docs/cursor-themes.md@@ -3,24 +3,43 @@Cua Driver ships one built-in cursor theme: `cua.default`. It is the default onmacOS, Windows, and Linux and cannot be removed. By default the agent cursor isa plain, upright arrow: a colored pointer with a white outline over a soft,-cursor-shaped glow in the same session color. The arrow stands upright like the-system pointer, with its left edge vertical, and keeps that pose while it moves.+cursor-shaped glow in the same session color. At rest the arrow stands upright like the+system pointer, with its left edge vertical. While it moves, its tip points+along the path (`cursor.rotate`, `heading` by default), and it is upright again+before it arrives.The glow softly fades to transparent around the full pointer silhouette, whilethe white outline preserves a crisp boundary on light, dark, and similarlycolored backgrounds. The anonymous/default cursor uses Cua blue. Named sessionsreceive a stable fill from the built-in session palette, so concurrent agentsremain visually distinct.-A resting cursor levitates: it rises about 4 pt and settles back on a-four-second loop, straight up and down, so the arrow stays upright. The cursor-fades out after its idle-hide delay. Turn the float off with+The cursor floats on a slow four-second loop, at rest and while it travels+(moves, click approaches, drags): it sways about 3.3 pt side to side, bobs+about 3.9 pt up and down and tilts 2.5° either way with the bob. The float has+its own clock, so no move, click or action restarts it. Before every click,+double click, drag start, drop, scroll and typing focus it eases to exactly+zero, so the hotspot is precise and the arrow upright, then eases back in+about half a second later. The tilt adds to the `cursor.rotate` heading.+The cursor fades out after its idle-hide delay. Turn the float off with`cua-driver config set cursor.float off`; a resting cursor is then still, sothe macOS, Windows, X11, and Wayland overlays stop rendering once activitysettles.+A soft halo sits behind the arrow body: a round glow about 28 pt across in the+cursor's own color (the session color, or a custom theme's accent), about 11%+opaque at the centre and fading to nothing at its edge. It moves, floats and+turns with the arrow and has no click effect. Turn it off with+`cua-driver config set cursor.halo off`.++On GNOME, where the Shell helper draws the cursor inside the compositor, the+helper plays the same planned path with the same float, halo and rotation+(helper v11 and later). An older helper glides straight to the target+without them.+### Extras-Apart from the float, everything beyond the plain arrow is off by default. Each+Apart from the float and the halo, everything beyond the plain arrow is off by+default. Eachextra is a saved setting in `~/.cua-driver/config.json` that applies at once toevery cursor on screen. Turn one on with `cua-driver config set <key> on`, orwith `set_config`:@@ -28,8 +47,9 @@ with `set_config`:| Key | What it adds || --- | --- || `cursor.marks` | Action marks: a small cue next to the arrow while the agent observes, clicks, types, presses keys, scrolls, drags, manages apps, moves files, records, or makes system calls. Moves and clicks show the navigate and click marks. On macOS, a clicked element also gets a brief focus box. |-| `cursor.float` | On by default. The resting float: a slow vertical bob on a four-second loop while the cursor rests, until the idle fade hides it. The arrow never tilts. |-| `cursor.rotate` | Rotation: the arrow turns toward the direction it moves and settles upright on arrival. |+| `cursor.float` | On by default. A slow sway, bob and slight tilt on a four-second loop, at rest (until the idle fade hides it) and while travelling. It is exactly zero for every click, drag start, drop, scroll and typing focus. |+| `cursor.halo` | On by default. The soft glow behind the arrow body, in the cursor's color. |+| `cursor.rotate` | `heading` by default: the tip points along the path. `lean`: the arrow tilts toward where it is going, at most 30° (15° while dragging). `off`: always upright. Both skip hops under 40 pt and are upright again before the cursor arrives, so clicks, typing and scrolling are always upright. `on` means `heading`. || `cursor.motion.effects.glow` | A soft glow behind the pointer that grows with speed. || `cursor.motion.effects.ripple` | A ring that expands from each click point. || `cursor.motion.effects.squish` | The pointer shrinks briefly on each click and springs back. |@@ -37,7 +57,7 @@ with `set_config`:The motion effects can also be set per session with `set_agent_cursor_motion`(see below). Every semantic mark inherits the float when both are on, so thepointer and mark move as one visual unit. Reduced-motion mode removes the-float, rotation, and every motion effect, and keeps marks on their still frame.+float, rotation, and every motion effect (the halo stays), and keeps marks on their still frame.With `cursor.marks` off, custom themes also paint only their `idle` animation.The badge below the pointer follows the `cursor.badges` setting, which appliesdiff --git a/libs/cua-driver/rust/Skills/cua-driver/RUNTIME.md b/libs/cua-driver/rust/Skills/cua-driver/RUNTIME.mdindex 6dd6004e7b..606e46795f 100644--- a/libs/cua-driver/rust/Skills/cua-driver/RUNTIME.md+++ b/libs/cua-driver/rust/Skills/cua-driver/RUNTIME.md@@ -98,7 +98,7 @@ On Linux, ordinary `move_cursor({x,y})` moves only this synthetic cursor. The exPixel `click` already animates the cursor. Do not precede it with `move_cursor` at the same point: that adds a second glide. Use `move_cursor` to indicate a location without clicking or seed the cursor before accessibility actions.-The default theme is a plain, upright, session-colored arrow with a soft glow that levitates gently at rest (`cursor.float`, on by default; the arrow never tilts). Action marks, rotation toward travel and the glow/ripple/squish motion effects are opt-in (`cursor.marks`, `cursor.rotate`, `cursor.motion.effects.<name>`; off by default). Named sessions have stable palette colors. Native hosts own delivery/target badges separately from theme artwork; cursor state is scoped to the private lifecycle.+The default theme is a session-colored arrow with a soft halo (`cursor.halo`, on by default) that floats gently at rest and while moving (a slow sway, bob and tilt), settling to exactly zero before every click, drag, scroll and typing (`cursor.float`, on by default). While it moves its tip points along the path (`cursor.rotate`: `heading` by default, or `lean` or `off`); it is upright again on arrival, so clicks, typing and scrolling are upright. Action marks and the glow/ripple/squish motion effects are opt-in (off by default). Named sessions have stable palette colors. Native hosts own delivery/target badges separately from theme artwork; cursor state is scoped to the private lifecycle.`set_agent_cursor_enabled` controls idle visibility. `set_agent_cursor_motion` takes `style` (`signature_arc` default, `spring_settle`, `magnetic`, `comet_swoop`, `adaptive`, `classic`), `timing` (`native`, `fitts`, `fixed`), `effects` (`trail`, `glow`, `magnet`, `ripple`, `squish` as `on`, `off`, or `default`; `default` restores the style default, and an omitted effect keeps its current setting), and the arc knobs `start_handle`, `end_handle`, `arc_size`, `arc_flow` (bezier styles) plus `spring` and `turn_radius` (`classic`) where advertised. Choose preinstalled artwork with `set_agent_cursor_theme`; `cursor_id` on input tools is not a theme selector. Never supply inline theme code or arbitrary source paths through agent tools. The trusted local `cursor-theme` workflow owns validation, compilation, preview, installation, and removal.diff --git a/libs/cua-driver/rust/crates/cua-driver/src/cli.rs b/libs/cua-driver/rust/crates/cua-driver/src/cli.rsindex 558bedf01a..4f254a1c38 100644--- a/libs/cua-driver/rust/crates/cua-driver/src/cli.rs+++ b/libs/cua-driver/rust/crates/cua-driver/src/cli.rs@@ -4559,7 +4559,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. cursor.badges (minimal, verbose, off) sets the agent cursor badge for every cursor at once; minimal is the default. cursor.float (resting float) is on, off or default and on by default; cursor.marks (action marks) and cursor.rotate (turn toward travel) are on, off or default and off by default. All three apply to every cursor at once.","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. cursor.float (float at rest and while moving) and cursor.halo (soft glow) are on, off or default and on by default; cursor.marks (action marks) is on, off or default and off by default; cursor.rotate is heading (default), lean, off or default. All apply to every cursor at once.","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":[]}]},@@ -5283,7 +5283,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, cursor.badges, cursor.marks, cursor.float, cursor.rotate");+ eprintln!("Keys: capture_mode, max_image_dimension, version, platform, cursor.motion.style, cursor.motion.timing, cursor.badges, cursor.marks, cursor.float, cursor.halo, cursor.rotate");process::exit(64);}};@@ -5312,7 +5312,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, cursor.badges, cursor.marks, cursor.float, cursor.rotate");+ eprintln!("Available keys: capture_mode, max_image_dimension, version, platform, agent_cursor.enabled, cursor.motion.style, cursor.motion.timing, cursor.motion.effects, cursor.badges, cursor.marks, cursor.float, cursor.halo, cursor.rotate");process::exit(64);}}@@ -5370,6 +5370,7 @@ pub fn run_config_cmd("cursor.badges": "default","cursor.marks": "default","cursor.float": "default",+ "cursor.halo": "default","cursor.rotate": "default",}),));diff --git a/libs/cua-driver/rust/crates/cursor-overlay/examples/render_motion_clip.rs b/libs/cua-driver/rust/crates/cursor-overlay/examples/render_motion_clip.rsnew file mode 100644index 0000000000..ee06460e13--- /dev/null+++ b/libs/cua-driver/rust/crates/cursor-overlay/examples/render_motion_clip.rs@@ -0,0 +1,328 @@+//! Render the agent cursor along a fixed script of moves, clicks, a drag and+//! a scroll with the real overlay renderer, over a light and a dark app+//! window, as raw RGBA frames on stdout. Pipe them into ffmpeg:+//!+//! ```sh+//! cargo run -p cursor-overlay --example render_motion_clip -- heading \+//! | ffmpeg -f rawvideo -pix_fmt rgba -s 1600x1000 -r 60 -i - \+//! -c:v libx264 -pix_fmt yuv420p -crf 24 heading.mp4+//! ```+//!+//! The argument is the `cursor.rotate` mode (`off`, `lean` or `heading`,+//! the default). The float and the halo are on, as by default.++use cursor_overlay::{+ paint_cursor, CursorAction, CursorConfig, CursorOptions, OverlayCommand, RenderStateCore,+ RotateMode,+};+use std::io::Write;+use tiny_skia::{Color, FillRule, Paint, PathBuilder, Pixmap, Rect, Transform};++const SCALE: f32 = 2.0;+const W: f32 = 800.0;+const H: f32 = 500.0;+const FPS: f64 = 60.0;++#[derive(Clone, Copy)]+enum Step {+ Move(f64, f64),+ Click,+ Press,+ Release,+ Scroll(f64),+ Wait(f64),+}++/// A few long moves, a downward move, short hops, clicks, a drag and a+/// scroll, crossing both windows.+const SCRIPT: &[Step] = &[+ Step::Wait(0.4),+ Step::Move(690.0, 410.0),+ Step::Click,+ Step::Move(270.0, 90.0),+ Step::Move(270.0, 420.0),+ Step::Move(298.0, 430.0),+ Step::Move(318.0, 414.0),+ Step::Move(300.0, 440.0),+ Step::Click,+ Step::Move(120.0, 250.0),+ Step::Press,+ Step::Move(560.0, 220.0),+ Step::Release,+ Step::Move(640.0, 150.0),+ Step::Scroll(1.1),+ Step::Wait(0.6),+];++struct Scene {+ clicked: Option<(f64, f64, f64)>,+ card: (f64, f64),+ dragging: bool,+ scroll: f64,+}++fn fill_rect(pm: &mut Pixmap, x: f32, y: f32, w: f32, h: f32, r: f32, rgb: u32) {+ let color = Color::from_rgba8((rgb >> 16) as u8, (rgb >> 8) as u8, rgb as u8, 255);+ let paint = Paint {+ shader: tiny_skia::Shader::SolidColor(color),+ anti_alias: true,+ ..Default::default()+ };+ let (x, y, w, h, r) = (x * SCALE, y * SCALE, w * SCALE, h * SCALE, r * SCALE);+ let mut pb = PathBuilder::new();+ if r <= 0.0 {+ if let Some(rect) = Rect::from_xywh(x, y, w, h) {+ pb.push_rect(rect);+ }+ } else {+ let k = 0.552_284_8 * r;+ pb.move_to(x + r, y);+ pb.line_to(x + w - r, y);+ pb.cubic_to(x + w - r + k, y, x + w, y + r - k, x + w, y + r);+ pb.line_to(x + w, y + h - r);+ pb.cubic_to(x + w, y + h - r + k, x + w - r + k, y + h, x + w - r, y + h);+ pb.line_to(x + r, y + h);+ pb.cubic_to(x + r - k, y + h, x, y + h - r + k, x, y + h - r);+ pb.line_to(x, y + r);+ pb.cubic_to(x, y + r - k, x + r - k, y, x + r, y);+ pb.close();+ }+ if let Some(path) = pb.finish() {+ pm.fill_path(+ &path,+ &paint,+ FillRule::Winding,+ Transform::identity(),+ None,+ );+ }+}++fn window(pm: &mut Pixmap, x: f32, dark: bool, scene: &Scene, t: f64) {+ let (body, bar, side, line, strong, button) = if dark {+ (0x1E1F22, 0x2B2D31, 0x25272B, 0x3A3D43, 0x50545C, 0x3B82F6)+ } else {+ (0xFFFFFF, 0xECEEF1, 0xF4F5F7, 0xE3E6EA, 0xC9CED6, 0x2563EB)+ };+ let (y, w, h) = (24.0, 370.0, 452.0);+ fill_rect(pm, x, y, w, h, 10.0, body);+ fill_rect(pm, x, y, w, 30.0, 10.0, bar);+ fill_rect(pm, x, y + 20.0, w, 10.0, 0.0, bar);+ for (i, c) in [0xFF5F57u32, 0xFEBC2E, 0x28C840].iter().enumerate() {+ fill_rect(+ pm,+ x + 14.0 + i as f32 * 16.0,+ y + 10.0,+ 10.0,+ 10.0,+ 5.0,+ *c,+ );+ }+ fill_rect(pm, x, y + 30.0, 96.0, h - 30.0, 0.0, side);+ for i in 0..7 {+ fill_rect(+ pm,+ x + 14.0,+ y + 50.0 + i as f32 * 26.0,+ 64.0,+ 8.0,+ 4.0,+ line,+ );+ }+ // Content rows; the dark window's list scrolls.+ let offset = if dark { scene.scroll as f32 } else { 0.0 };+ for i in 0..14 {+ let ry = y + 52.0 + i as f32 * 30.0 - offset;+ if ry < y + 40.0 || ry > y + h - 70.0 {+ continue;+ }+ let len = 120.0 + ((i * 53) % 110) as f32;+ fill_rect(+ pm,+ x + 116.0,+ ry,+ len,+ 9.0,+ 4.5,+ if i % 4 == 0 { strong } else { line },+ );+ }+ // A button near the bottom right; it flashes when clicked.+ let (bx, by) = (x + w - 120.0, y + h - 52.0);+ let flash = scene.clicked.is_some_and(|(cx, cy, at)| {+ (cx - f64::from(bx + 50.0)).abs() < 60.0+ && (cy - f64::from(by + 15.0)).abs() < 40.0+ && t - at < 0.25+ });+ fill_rect(+ pm,+ bx,+ by,+ 100.0,+ 30.0,+ 8.0,+ if flash { 0x1D4ED8 } else { button },+ );+ fill_rect(pm, bx + 26.0, by + 12.0, 48.0, 6.0, 3.0, 0xFFFFFF);+}++fn background(scene: &Scene, t: f64) -> Pixmap {+ let mut pm = Pixmap::new((W * SCALE) as u32, (H * SCALE) as u32).unwrap();+ fill_rect(&mut pm, 0.0, 0.0, W, H, 0.0, 0x9AA3AF);+ window(&mut pm, 10.0, false, scene, t);+ window(&mut pm, 420.0, true, scene, t);+ // The card the drag carries.+ let (cx, cy) = scene.card;+ fill_rect(+ &mut pm,+ cx as f32 - 36.0,+ cy as f32 - 14.0,+ 72.0,+ 40.0,+ 8.0,+ 0xF59E0B,+ );+ if scene.dragging {+ fill_rect(+ &mut pm,+ cx as f32 - 30.0,+ cy as f32 - 4.0,+ 40.0,+ 6.0,+ 3.0,+ 0xFFFFFF,+ );+ }+ pm+}++fn main() {+ let rotate = match std::env::args().nth(1).as_deref() {+ Some("lean") => RotateMode::Lean,+ Some("off") => RotateMode::Off,+ _ => RotateMode::Heading,+ };+ let mut core = RenderStateCore::new(CursorConfig::default());+ core.options_override = Some(CursorOptions {+ rotate,+ ..CursorOptions::DEFAULT+ });+ core.motion.idle_hide_ms = 60_000.0;+ core.apply_command_base(+ OverlayCommand::SnapTo {+ x: 0.0,+ y: 0.0,+ heading_radians: None,+ },+ false,+ false,+ );+ let start = cursor_overlay::anchor_for_pointer(120.0, 110.0, core.heading);+ core.pos = start;++ let mut scene = Scene {+ clicked: None,+ card: (120.0, 250.0),+ dragging: false,+ scroll: 0.0,+ };+ let dt = 1.0 / FPS;+ let mut t = 0.0;+ let mut out = std::io::BufWriter::new(std::io::stdout().lock());+ let mut target = (120.0, 110.0);+ let mut frame = |core: &mut RenderStateCore, scene: &mut Scene, t: f64| -> bool {+ let arrived = core.tick_motion(dt);+ let (px, py) = cursor_overlay::pointer_for_anchor(core.pos.0, core.pos.1, core.heading);+ if scene.dragging {+ scene.card = (px, py + 14.0);+ }+ let mut pm = background(scene, t);+ paint_cursor(&mut pm, core, 0.0, 0.0, None, SCALE);+ out.write_all(pm.data()).unwrap();+ arrived+ };+ for step in SCRIPT {+ match *step {+ Step::Move(x, y) => {+ target = (x, y);+ core.apply_command_base(+ OverlayCommand::MoveTo {+ x,+ y,+ end_heading_radians: cursor_overlay::trajectory::REST_HEADING,+ target: None,+ },+ false,+ false,+ );+ loop {+ t += dt;+ if frame(&mut core, &mut scene, t) || core.trajectory.is_none() {+ break;+ }+ }+ // A short beat before the next call, as a real agent has.+ for _ in 0..(0.12 * FPS) as usize {+ t += dt;+ frame(&mut core, &mut scene, t);+ }+ }+ Step::Click => {+ core.apply_command_base(+ OverlayCommand::ClickPulse {+ x: target.0,+ y: target.1,+ },+ false,+ false,+ );+ scene.clicked = Some((target.0, target.1, t));+ for _ in 0..(0.35 * FPS) as usize {+ t += dt;+ frame(&mut core, &mut scene, t);+ }+ }+ Step::Press | Step::Release => {+ let press = matches!(step, Step::Press);+ core.apply_command_base(OverlayCommand::SetPressed(press), false, false);+ scene.dragging = press;+ for _ in 0..(0.15 * FPS) as usize {+ t += dt;+ frame(&mut core, &mut scene, t);+ }+ }+ Step::Scroll(secs) => {+ core.apply_command_base(+ OverlayCommand::BeginAction {+ action: CursorAction::Scroll,+ delivery: None,+ target: None,+ },+ false,+ false,+ );+ let frames = (secs * FPS) as usize;+ for i in 0..frames {+ t += dt;+ let p = i as f64 / frames as f64;+ scene.scroll = 120.0 * (p * p * (3.0 - 2.0 * p));+ frame(&mut core, &mut scene, t);+ }+ core.apply_command_base(+ OverlayCommand::EndAction(CursorAction::Scroll),+ false,+ false,+ );+ }+ Step::Wait(secs) => {+ for _ in 0..(secs * FPS) as usize {+ t += dt;+ frame(&mut core, &mut scene, t);+ }+ }+ }+ }+ eprintln!("{:.2} s", t);+}diff --git a/libs/cua-driver/rust/crates/cursor-overlay/src/cursor_options.rs b/libs/cua-driver/rust/crates/cursor-overlay/src/cursor_options.rsindex 875ae264f8..3d1fa9dec5 100644--- a/libs/cua-driver/rust/crates/cursor-overlay/src/cursor_options.rs+++ b/libs/cua-driver/rust/crates/cursor-overlay/src/cursor_options.rs@@ -3,21 +3,24 @@//! Extras of the agent cursor.//!-//! The default agent cursor is a plain, upright arrow that levitates gently-//! while it rests. Three saved settings in `~/.cua-driver/config.json`+//! The default agent cursor is a plain arrow with a soft halo that levitates+//! gently and points its tip along the path while it moves. Four saved settings in `~/.cua-driver/config.json`//! (`{"cursor": {"marks": true}}`) switch the extras://!//! - `cursor.marks`: the theme's action marks (observe arcs, click lines,//! I-beam, key cap and the rest), including the navigate and click marks a//! move or click used to start by itself, and the macOS focus rectangle//! around a clicked element. Off: every theme paints its idle frame.-//! - `cursor.float` (on by default): the resting float of the built-in-//! theme, a slow vertical bob with the arrow kept upright. Off: a resting-//! cursor is still, so the overlay stops redrawing.-//! - `cursor.rotate`: the arrow turns toward the direction it travels and-//! settles back upright on arrival. Off: the arrow stays upright.-//!-//! `cursor.marks` and `cursor.rotate` are off by default.+//! - `cursor.float` (on by default): the float of the built-in theme, a slow+//! vertical bob at rest and a smaller lift while the cursor travels that+//! settles to exactly zero on arrival. The arrow stays upright. Off: the+//! cursor never floats, so a resting overlay stops redrawing.+//! - `cursor.halo` (on by default): a soft glow in the cursor's accent colour+//! behind the arrow body. No click effect.+//! - `cursor.rotate` (`heading` by default): `heading` points the tip along+//! the path; `lean` tilts the arrow at most 30° toward where it is going;+//! `off` keeps it upright. Both turning modes ease back upright before+//! arrival. `on` is the same as `heading`.//!//! Like `cursor.badges` they apply live: every cursor reads the process-wide//! value on each frame, so a `set_config` write changes cursors already on@@ -30,14 +33,54 @@ use std::sync::atomic::{AtomicU8, Ordering};pub const MARKS_KEY: &str = "cursor.marks";pub const FLOAT_KEY: &str = "cursor.float";pub const ROTATE_KEY: &str = "cursor.rotate";+pub const HALO_KEY: &str = "cursor.halo";++/// How the arrow turns while it travels (`cursor.rotate`).+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]+pub enum RotateMode {+ /// Always upright.+ Off,+ /// Leans toward the direction of travel by at most 30°.+ Lean,+ /// The tip points along the path (the default).+ #[default]+ Heading,+}++impl RotateMode {+ pub const fn as_str(self) -> &'static str {+ match self {+ Self::Off => "off",+ Self::Lean => "lean",+ Self::Heading => "heading",+ }+ }++ const fn to_bits(self) -> u8 {+ match self {+ Self::Off => 0,+ Self::Lean => 1,+ Self::Heading => 2,+ }+ }++ const fn from_bits(bits: u8) -> Self {+ match bits {+ 1 => Self::Lean,+ 2 => Self::Heading,+ _ => Self::Off,+ }+ }+}-/// The cursor extras. `Default` is the float alone; [`CursorOptions::NONE`]+/// The cursor extras. `Default` is the float, the halo and `heading`; [`CursorOptions::NONE`]/// is everything off.#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]pub struct CursorOptions {pub marks: bool,pub float: bool,- pub rotate: bool,+ pub rotate: RotateMode,+ pub halo: bool,}impl Default for CursorOptions {@@ -47,58 +90,71 @@ impl Default for CursorOptions {}impl CursorOptions {- /// The built-in default: a plain upright arrow that floats at rest.+ /// The built-in default: a plain arrow with a halo that floats and points+ /// along its path while it moves.pub const DEFAULT: Self = Self {marks: false,float: true,- rotate: false,+ rotate: RotateMode::Heading,+ halo: true,};/// Every extra off: a plain arrow that is still at rest.pub const NONE: Self = Self {marks: false,float: false,- rotate: false,+ rotate: RotateMode::Off,+ halo: false,};- /// Every extra on: the cursor as it looked before these settings.+ /// Every extra on.pub const ALL_ON: Self = Self {marks: true,float: true,- rotate: true,+ rotate: RotateMode::Heading,+ halo: true,};- const KEYS: [(&'static str, &'static str); 3] = [- (MARKS_KEY, "marks"),- (FLOAT_KEY, "float"),- (ROTATE_KEY, "rotate"),- ];-- fn get(&self, field: &str) -> bool {- match field {- "marks" => self.marks,- "float" => self.float,- _ => self.rotate,+ const KEYS: [&'static str; 4] = [MARKS_KEY, FLOAT_KEY, ROTATE_KEY, HALO_KEY];++ fn field(key: &str) -> &str {+ key.trim_start_matches("cursor.")+ }++ /// The value of one key as `get_config` and `set_config` show it.+ fn value_str(&self, key: &str) -> &'static str {+ let on_off = |flag: bool| if flag { "on" } else { "off" };+ match key {+ MARKS_KEY => on_off(self.marks),+ FLOAT_KEY => on_off(self.float),+ HALO_KEY => on_off(self.halo),+ _ => self.rotate.as_str(),}}- fn set(&mut self, field: &str, value: bool) {- match field {- "marks" => self.marks = value,- "float" => self.float = value,- _ => self.rotate = value,+ fn apply(&mut self, update: Update) {+ let default = Self::DEFAULT;+ match update {+ Update::Marks(value) => self.marks = value.unwrap_or(default.marks),+ Update::Float(value) => self.float = value.unwrap_or(default.float),+ Update::Halo(value) => self.halo = value.unwrap_or(default.halo),+ Update::Rotate(value) => self.rotate = value.unwrap_or(default.rotate),}}const fn to_u8(self) -> u8 {- self.marks as u8 | (self.float as u8) << 1 | (self.rotate as u8) << 2+ self.marks as u8+ | (self.float as u8) << 1+ | self.rotate.to_bits() << 2+ | (self.halo as u8) << 4}const fn from_u8(value: u8) -> Self {Self {marks: value & 1 != 0,float: value & 2 != 0,- rotate: value & 4 != 0,+ rotate: RotateMode::from_bits((value >> 2) & 3),+ halo: value & 16 != 0,}}@@ -106,19 +162,78 @@ impl CursorOptions {pub fn config_json(&self) -> Map<String, Value> {Self::KEYS.iter()- .map(|(_, field)| ((*field).to_owned(), Value::Bool(self.get(field))))+ .map(|key| {+ let value = match *key {+ MARKS_KEY => Value::Bool(self.marks),+ FLOAT_KEY => Value::Bool(self.float),+ HALO_KEY => Value::Bool(self.halo),+ _ => Value::String(self.rotate.as_str().into()),+ };+ (Self::field(key).to_owned(), value)+ }).collect()}}-/// Parse one value: `on`, `off` or `default` (also a bool or null, like the-/// `cursor.motion.effects.*` keys). `None` means the built-in default.+/// One parsed write; `None` means the built-in default.+#[derive(Debug, Clone, Copy, PartialEq)]+enum Update {+ Marks(Option<bool>),+ Float(Option<bool>),+ Halo(Option<bool>),+ Rotate(Option<RotateMode>),+}++impl Update {+ /// What the config file stores for this write; `None` removes the key.+ fn saved(self) -> Option<Value> {+ match self {+ Self::Marks(value) | Self::Float(value) | Self::Halo(value) => value.map(Value::Bool),+ Self::Rotate(value) => value.map(|mode| Value::String(mode.as_str().into())),+ }+ }+}++/// Parse one on/off value: `on`, `off` or `default` (also a bool or null,+/// like the `cursor.motion.effects.*` keys). `None` means the built-in+/// default.pub fn parse_value(key: &str, value: &Value) -> Result<Option<bool>, String> {cua_driver_contract::CursorEffectSetting::from_json(value).map(cua_driver_contract::CursorEffectSetting::override_value).ok_or_else(|| format!("{key} must be on, off or default, got {value}"))}+/// Parse a `cursor.rotate` value: `off`, `lean`, `heading` or `default`.+/// `on` (or `true`), from before the modes existed, means `heading`.+pub fn parse_rotate(value: &Value) -> Result<Option<RotateMode>, String> {+ match value {+ Value::Null => Ok(None),+ Value::Bool(true) => Ok(Some(RotateMode::Heading)),+ Value::Bool(false) => Ok(Some(RotateMode::Off)),+ Value::String(text) => match text.trim().to_ascii_lowercase().as_str() {+ "default" => Ok(None),+ "off" => Ok(Some(RotateMode::Off)),+ "lean" => Ok(Some(RotateMode::Lean)),+ "heading" | "on" => Ok(Some(RotateMode::Heading)),+ _ => Err(format!(+ "{ROTATE_KEY} must be off, lean, heading or default, got {value}"+ )),+ },+ _ => Err(format!(+ "{ROTATE_KEY} must be off, lean, heading or default, got {value}"+ )),+ }+}++fn parse_update(key: &str, value: &Value) -> Result<Update, String> {+ Ok(match key {+ MARKS_KEY => Update::Marks(parse_value(key, value)?),+ FLOAT_KEY => Update::Float(parse_value(key, value)?),+ HALO_KEY => Update::Halo(parse_value(key, value)?),+ _ => Update::Rotate(parse_rotate(value)?),+ })+}+/// Read the saved options from `path`. A missing file or an invalid value/// falls back to the built-in default; a bad value is logged, never fatal.pub fn load_from(path: &Path) -> CursorOptions {@@ -130,10 +245,10 @@ pub fn load_from(path: &Path) -> CursorOptions {let Some(cursor) = cursor else {return options;};- for (key, field) in CursorOptions::KEYS {- if let Some(value) = cursor.get(field) {- match parse_value(key, value) {- Ok(flag) => options.set(field, flag.unwrap_or(CursorOptions::DEFAULT.get(field))),+ for key in CursorOptions::KEYS {+ if let Some(value) = cursor.get(CursorOptions::field(key)) {+ match parse_update(key, value) {+ Ok(update) => options.apply(update),Err(error) => tracing::warn!("ignoring saved {key}: {error}"),}}@@ -146,9 +261,9 @@ pub fn load_from(path: &Path) -> CursorOptions {/// is invalid. Returns the new options and the keys written.pub fn set_at(path: &Path, args: &Value) -> Result<(CursorOptions, Vec<&'static str>), String> {let mut updates = Vec::new();- for (key, field) in CursorOptions::KEYS {+ for key in CursorOptions::KEYS {if let Some(value) = args.get(key) {- updates.push((key, field, parse_value(key, value)?));+ updates.push((key, parse_update(key, value)?));}}let mut root: Value = std::fs::read_to_string(path)@@ -166,10 +281,11 @@ pub fn set_at(path: &Path, args: &Value) -> Result<(CursorOptions, Vec<&'static}let cursor = cursor.as_object_mut().expect("cursor is an object");let mut keys = Vec::new();- for (key, field, flag) in updates {- match flag {- Some(flag) => {- cursor.insert(field.into(), Value::Bool(flag));+ for (key, update) in updates {+ let field = CursorOptions::field(key);+ match update.saved() {+ Some(value) => {+ cursor.insert(field.into(), value);}None => {cursor.remove(field);@@ -233,13 +349,14 @@ pub fn saved_config_json() -> Value {Value::Object(cursor)}-/// Apply the `cursor.marks` / `cursor.float` / `cursor.rotate` writes in a+/// Apply the `cursor.marks` / `cursor.float` / `cursor.rotate` /+/// `cursor.halo` writes in a/// `set_config` call: validate, persist, and switch every cursor at once./// Returns `key=value` for each key written.pub fn apply_config_args(args: &Value) -> Result<Vec<String>, String> {if !CursorOptions::KEYS.iter()- .any(|(key, _)| args.get(*key).is_some())+ .any(|key| args.get(*key).is_some()){return Ok(Vec::new());}@@ -249,35 +366,41 @@ pub fn apply_config_args(args: &Value) -> Result<Vec<String>, String> {set_active(options);Ok(keys.into_iter()- .map(|key| {- let field = key.trim_start_matches("cursor.");- format!("{key}={}", if options.get(field) { "on" } else { "off" })- })+ .map(|key| format!("{key}={}", options.value_str(key))).collect())}/// Input-schema properties to merge into each platform's `set_config` tool.pub fn config_schema_properties() -> Map<String, Value> {let mut properties = Map::new();- for (key, description) in [+ let on_off = ["on", "off", "default"];+ for (key, values, description) in [(MARKS_KEY,+ &on_off[..],"Agent cursor action marks: the small cue next to the arrow for observe, click, type, keys, scroll, drag, apps, files, recording and system calls, plus the focus box around a clicked element on macOS. off (default): a plain arrow. Applies immediately to every cursor.",),(FLOAT_KEY,- "Agent cursor resting float: a slow up-and-down bob while the cursor rests; the arrow stays upright. on (default). off: the cursor stays still at rest and the overlay stops redrawing. Applies immediately to every cursor.",+ &on_off[..],+ "Agent cursor float: a slow four-second sway, bob and slight tilt, at rest and while moving, that eases to zero on every arrival and holds there for the click, drag, drop, scroll or typing, so they land exactly upright on the hotspot. on (default). off: the cursor never floats and a resting overlay stops redrawing. Applies immediately to every cursor.",+ ),+ (+ HALO_KEY,+ &on_off[..],+ "Agent cursor halo: a soft glow in the cursor's colour behind the arrow, so it is easier to follow on any background. on (default). off: no halo. Applies immediately to every cursor.",),(ROTATE_KEY,- "Agent cursor rotation: the arrow turns toward the direction it moves and settles upright on arrival. off (default): the arrow always stays upright. Applies immediately to every cursor.",+ &["off", "lean", "heading", "on", "default"][..],+ "Agent cursor rotation while it moves: heading (default) points the tip along the path; lean tilts the arrow at most 30 degrees toward where it is going (on is the same as heading). Both return upright before arrival, so clicks, typing and scrolling stay upright. off: the arrow always stays upright. Applies immediately to every cursor.",),] {properties.insert(key.to_owned(),json!({"type": "string",- "enum": ["on", "off", "default"],+ "enum": values,"description": description,}),);@@ -302,8 +425,12 @@ mod tests {}#[test]- fn only_the_float_is_on_by_default() {- assert_eq!(CursorOptions::default(), CursorOptions::from_u8(2));+ fn the_float_the_halo_and_heading_are_on_by_default() {+ let default = CursorOptions::default();+ assert!(default.float && default.halo);+ assert!(!default.marks);+ assert_eq!(default.rotate, RotateMode::Heading);+ assert_eq!(default, CursorOptions::from_u8(2 | 8 | 16));assert_eq!(CursorOptions::NONE, CursorOptions::from_u8(0));assert_eq!(active(), CursorOptions::DEFAULT);let path = temp_config("missing");@@ -314,7 +441,14 @@ mod tests {fn the_float_can_be_turned_off_and_reset() {let path = temp_config("float-off");let (options, _) = set_at(&path, &json!({"cursor.float": "off"})).unwrap();- assert_eq!(options, CursorOptions::NONE);+ assert_eq!(+ options,+ CursorOptions {+ halo: true,+ rotate: RotateMode::Heading,+ ..CursorOptions::NONE+ }+ );let saved: Value = serde_json::from_str(&std::fs::read_to_string(&path).unwrap()).unwrap();assert_eq!(saved["cursor"]["float"], false);@@ -325,10 +459,21 @@ mod tests {#[test]fn round_trips_through_the_bit_packing() {- for bits in 0..8 {- assert_eq!(CursorOptions::from_u8(bits).to_u8(), bits);+ for marks in [false, true] {+ for float in [false, true] {+ for halo in [false, true] {+ for rotate in [RotateMode::Off, RotateMode::Lean, RotateMode::Heading] {+ let options = CursorOptions {+ marks,+ float,+ rotate,+ halo,+ };+ assert_eq!(CursorOptions::from_u8(options.to_u8()), options);+ }+ }+ }}- assert_eq!(CursorOptions::ALL_ON.to_u8(), 7);}#[test]@@ -348,8 +493,7 @@ mod tests {options,CursorOptions {marks: true,- float: true,- rotate: false+ ..CursorOptions::DEFAULT});let saved: Value = serde_json::from_str(&std::fs::read_to_string(&path).unwrap()).unwrap();@@ -376,8 +520,50 @@ mod tests {#[test]fn schema_lists_every_key() {let properties = config_schema_properties();- for key in [MARKS_KEY, FLOAT_KEY, ROTATE_KEY] {+ for key in [MARKS_KEY, FLOAT_KEY, ROTATE_KEY, HALO_KEY] {assert!(properties.contains_key(key), "{key}");}+ assert_eq!(+ properties[ROTATE_KEY]["enum"],+ json!(["off", "lean", "heading", "on", "default"])+ );+ }++ #[test]+ fn rotate_takes_a_mode_and_on_means_heading() {+ let path = temp_config("rotate");+ let (options, keys) = set_at(&path, &json!({"cursor.rotate": "lean"})).unwrap();+ assert_eq!(keys, vec![ROTATE_KEY]);+ assert_eq!(options.rotate, RotateMode::Lean);+ let saved: Value = serde_json::from_str(&std::fs::read_to_string(&path).unwrap()).unwrap();+ assert_eq!(saved["cursor"]["rotate"], "lean");+ assert_eq!(options.config_json()["rotate"], "lean");+ assert_eq!(options.value_str(ROTATE_KEY), "lean");++ for (value, mode) in [+ (json!("heading"), RotateMode::Heading),+ (json!("on"), RotateMode::Heading),+ (json!(true), RotateMode::Heading),+ (json!("off"), RotateMode::Off),+ (json!(false), RotateMode::Off),+ (json!("default"), RotateMode::Heading),+ ] {+ let (options, _) = set_at(&path, &json!({ "cursor.rotate": value })).unwrap();+ assert_eq!(options.rotate, mode, "{value}");+ }+ assert!(set_at(&path, &json!({"cursor.rotate": "spin"})).is_err());+ let _ = std::fs::remove_dir_all(path.parent().unwrap());+ }++ #[test]+ fn the_halo_can_be_turned_off() {+ let path = temp_config("halo");+ let (options, _) = set_at(&path, &json!({"cursor.halo": "off"})).unwrap();+ assert!(!options.halo);+ assert!(options.float);+ assert_eq!(options.config_json()["halo"], false);+ let (options, _) = set_at(&path, &json!({"cursor.halo": "default"})).unwrap();+ assert!(options.halo);+ let _ = std::fs::remove_dir_all(path.parent().unwrap());}}diff --git a/libs/cua-driver/rust/crates/cursor-overlay/src/cursor_pose.rs b/libs/cua-driver/rust/crates/cursor-overlay/src/cursor_pose.rsnew file mode 100644index 0000000000..1ae477b1c8--- /dev/null+++ b/libs/cua-driver/rust/crates/cursor-overlay/src/cursor_pose.rs@@ -0,0 +1,561 @@+// SPDX-License-Identifier: MIT+// Copyright (c) 2026 Cua AI, Inc.++//! Paint-time pose of the agent cursor: the float (`cursor.float`), the+//! rotation while it travels (`cursor.rotate`) and the halo (`cursor.halo`).+//!+//! All of it is visual only. The planner, its golden fixtures and the+//! hotspot are untouched: the float settles to exactly zero and the rotation+//! to upright by the time the hotspot arrives, so clicks land where they did.+//! Every motion the overlay plays (moves, click approaches, drags, the+//! magnetic snap, scroll and typing focus moves) is one planned trajectory,+//! so these functions cover all of them.++use crate::cursor_options::RotateMode;+use crate::trajectory::{wrap_angle, Trajectory};+use std::f64::consts::TAU;++/// Theme canvas units per point of the painted cursor.+const CANVAS_PT: f64 = crate::theme::DISPLAY_SIZE as f64 / crate::theme::CANVAS_SIZE as f64;++/// One float loop. The float is the one the cursor had from July to+/// October 2026 (#2603): a loop that sways side to side, bobs up and down+/// and tilts with the bob, at rest and while travelling.+pub const FLOAT_SECS: f64 = 4.0;+/// Horizontal sway amplitude, in points (5 canvas units; 3.3 pt peak to peak).+pub const FLOAT_SWAY_PT: f64 = 5.0 * CANVAS_PT;+/// Vertical bob amplitude, in points (6 canvas units; 3.9 pt peak to peak).+pub const FLOAT_BOB_PT: f64 = 6.0 * CANVAS_PT;+/// The bob is centred this far above the hotspot (5 canvas units).+pub const FLOAT_LIFT_PT: f64 = 5.0 * CANVAS_PT;+/// Tilt amplitude, phased with the bob.+pub const FLOAT_TILT_RADIANS: f64 = 2.5 * std::f64::consts::PI / 180.0;++/// After the cursor settles (an arrival, or a click, press, scroll or+/// typing cue at rest) the float stays at exactly 0 this long, so the+/// action that follows lands on the hotspot ...+pub const FLOAT_HOLD_SECS: f64 = 0.5;+/// ... then eases back in over this long.+pub const FLOAT_EASE_IN_SECS: f64 = 0.8;+/// A cue at rest with no move before it eases the float out this fast.+pub const FLOAT_EASE_OUT_SECS: f64 = 0.2;+/// Hops shorter than this keep no float while travelling (whatever float+/// they start with still eases out to 0).+pub const FLOAT_MIN_HOP_PT: f64 = 30.0;+const FLOAT_RAMP_IN_SECS: f64 = 0.25;+const FLOAT_RAMP_OUT_SECS: f64 = 0.35;++/// A float offset: `dx`, `dy` in points (y down, negative is up) and `tilt`+/// in radians (clockwise, y down), added to the heading rotation.+#[derive(Debug, Clone, Copy, PartialEq, Default)]+pub struct FloatOffset {+ pub dx: f64,+ pub dy: f64,+ pub tilt: f64,+}++impl FloatOffset {+ pub const ZERO: Self = Self {+ dx: 0.0,+ dy: 0.0,+ tilt: 0.0,+ };++ /// This offset at `amplitude` (0..1). Exactly [`Self::ZERO`] at 0.+ pub fn scaled(self, amplitude: f64) -> Self {+ if amplitude <= 0.0 {+ return Self::ZERO;+ }+ let k = amplitude.min(1.0);+ Self {+ dx: self.dx * k,+ dy: self.dy * k,+ tilt: self.tilt * k,+ }+ }+}++/// The full float `secs` into its clock: sway `sin`, bob and tilt `cos`.+/// The clock belongs to the cursor and runs on across every action, so the+/// phase never snaps back.+pub fn float_at(secs: f64) -> FloatOffset {+ let angle = secs.rem_euclid(FLOAT_SECS) / FLOAT_SECS * TAU;+ FloatOffset {+ dx: FLOAT_SWAY_PT * angle.sin(),+ dy: FLOAT_BOB_PT * angle.cos() - FLOAT_LIFT_PT,+ tilt: FLOAT_TILT_RADIANS * angle.cos(),+ }+}++/// Float amplitude (0..1) at rest, `hold` seconds after the cursor last+/// settled, with amplitude `from` at that moment: `from` eases out to 0,+/// holds at 0 for [`FLOAT_HOLD_SECS`], then eases back in to 1.+pub fn rest_amplitude(hold: f64, from: f64) -> f64 {+ let out = from.clamp(0.0, 1.0) * (1.0 - smoothstep(hold / FLOAT_EASE_OUT_SECS));+ let back = smoothstep((hold - FLOAT_HOLD_SECS) / FLOAT_EASE_IN_SECS);+ out.max(back)+}++/// Float amplitude (0..1) while travelling, `t` seconds into `traj`, from+/// `start` (the amplitude when the move began, so nothing jumps). Full+/// mid-move on hops of [`FLOAT_MIN_HOP_PT`] or more; exactly 0 at arrival.+pub fn travel_amplitude(traj: &Trajectory, t: f64, start: f64) -> f64 {+ let arrival = traj.arrival_t;+ if t >= arrival {+ return 0.0;+ }+ let (p_in, p_out) = ramps(t, arrival, FLOAT_RAMP_IN_SECS, FLOAT_RAMP_OUT_SECS);+ let carry = start.clamp(0.0, 1.0) * (1.0 - p_in) * p_out;+ let full = if hop_length(traj) < FLOAT_MIN_HOP_PT {+ 0.0+ } else {+ 1.0+ };+ (carry + full * p_in * p_out).min(1.0)+}++/// `lean` turns the arrow at most this far.+pub const LEAN_MAX_RADIANS: f64 = 30.0 * std::f64::consts::PI / 180.0;+/// ... and at most this far while a button is held (drags).+pub const LEAN_MAX_DRAG_RADIANS: f64 = 15.0 * std::f64::consts::PI / 180.0;+/// Hops shorter than this never rotate.+pub const ROTATE_MIN_HOP_PT: f64 = 40.0;+const ROTATE_RAMP_IN_SECS: f64 = 0.15;+const ROTATE_RAMP_OUT_SECS: f64 = 0.25;++/// Centre of the upright `cua.default` arrow body, in points from the+/// hotspot (x right, y down).+pub const BODY_OFFSET_PT: (f64, f64) = (2.0, 11.9);++/// Direction from the arrow body to its tip (the hotspot) for the upright+/// arrow, in radians, y down.+pub fn tip_axis() -> f64 {+ (-BODY_OFFSET_PT.1).atan2(-BODY_OFFSET_PT.0)+}++/// Halo diameter is twice this, in points.+pub const HALO_RADIUS_PT: f32 = 14.0;+/// Halo opacity at its centre; it fades to 0 at the edge.+pub const HALO_PEAK_ALPHA: f32 = 0.11;+/// Halo gradient stops: (offset from the centre 0..1, share of the peak).+pub const HALO_STOPS: [(f32, f32); 3] = [(0.0, 1.0), (0.45, 0.55), (1.0, 0.0)];++fn smoothstep(x: f64) -> f64 {+ let t = x.clamp(0.0, 1.0);+ t * t * (3.0 - 2.0 * t)+}++/// Ease-in after the start and ease-out before arrival, each at most half+/// the travel so short moves still reach exactly 0 at both ends.+fn ramps(t: f64, arrival: f64, ramp_in: f64, ramp_out: f64) -> (f64, f64) {+ let ramp_in = ramp_in.min(arrival * 0.5).max(1e-6);+ let ramp_out = ramp_out.min(arrival * 0.5).max(1e-6);+ (+ smoothstep(t / ramp_in),+ smoothstep((arrival - t) / ramp_out),+ )+}++/// Straight-line length of the move, hotspot start to end.+pub fn hop_length(traj: &Trajectory) -> f64 {+ let (a, b) = (traj.samples[0], traj.end());+ (b.x - a.x).hypot(b.y - a.y)+}++/// Whether the hotspot is still on its way (before arrival).+pub fn travelling(traj: &Trajectory, t: f64) -> bool {+ t < traj.arrival_t+}++/// Rotation in radians from upright, `t` seconds into `traj`. Upright at+/// the start, at arrival, after it, and on hops under+/// [`ROTATE_MIN_HOP_PT`]. `pressed` (a drag) caps `lean` at 15°.+pub fn travel_rotation(traj: &Trajectory, t: f64, mode: RotateMode, pressed: bool) -> f64 {+ if mode == RotateMode::Off || !travelling(traj, t) || hop_length(traj) < ROTATE_MIN_HOP_PT {+ return 0.0;+ }+ let (a, b) = (traj.samples[0], traj.end());+ let chord = (b.y - a.y).atan2(b.x - a.x);+ // `heading` can turn the arrow up to 180° (upside down on a move+ // straight down). Stretch its ramps with the size of the turn so a big+ // turn eases in and out as gently as a lean, with no flip.+ let stretch = match mode {+ RotateMode::Heading => 1.0 + wrap_angle(chord - tip_axis()).abs() / std::f64::consts::PI,+ _ => 1.0,+ };+ let (p_in, p_out) = ramps(+ t,+ traj.arrival_t,+ ROTATE_RAMP_IN_SECS * stretch,+ ROTATE_RAMP_OUT_SECS * stretch,+ );+ let (vx, vy) = traj.velocity_at(t);+ let travel = if vx.hypot(vy) > 1.0 {+ vy.atan2(vx)+ } else {+ chord+ };+ // Unwrap around the chord so a path that wobbles near straight down+ // never flips between +180° and -180°.+ let target = wrap_angle(chord - tip_axis()) + wrap_angle(travel - chord);+ let shaped = match mode {+ RotateMode::Lean => {+ let cap = if pressed {+ LEAN_MAX_DRAG_RADIANS+ } else {+ LEAN_MAX_RADIANS+ };+ cap * (target / cap).tanh()+ }+ _ => target,+ };+ shaped * p_in * p_out+}++/// Halo colour: the theme's accent with the same session tint the arrow+/// gets, so it follows theme and session changes.+pub fn halo_rgb(theme: Option<&crate::CompiledTheme>, cursor_id: &str) -> [u8; 3] {+ let session = crate::session_fill_rgba(cursor_id);+ let fallback;+ let theme = match theme {+ Some(theme) => theme,+ None => {+ fallback = crate::embedded_default_theme();+ &*fallback+ }+ };+ let tint = (theme.id == crate::DEFAULT_THEME_ID).then_some(session);+ let [r, g, b, _] = crate::theme_artifact::theme_accent_rgba(theme, tint).unwrap_or(session);+ [r, g, b]+}++/// Paint the halo: a radial glow of `radius` px around `(cx, cy)`, `peak`+/// opacity at the centre fading to 0 at the edge.+pub fn paint_halo(+ pm: &mut tiny_skia::Pixmap,+ cx: f32,+ cy: f32,+ radius: f32,+ rgb: [u8; 3],+ peak: f32,+) {+ use tiny_skia::{Color, GradientStop, PathBuilder, Point, RadialGradient, SpreadMode};+ let color = |a: f32| {+ Color::from_rgba8(+ rgb[0],+ rgb[1],+ rgb[2],+ (a.clamp(0.0, 1.0) * 255.0).round() as u8,+ )+ };+ if peak <= 0.0 || radius <= 0.0 {+ return;+ }+ let Some(shader) = RadialGradient::new(+ Point::from_xy(cx, cy),+ Point::from_xy(cx, cy),+ radius,+ HALO_STOPS+ .iter()+ .map(|&(offset, share)| GradientStop::new(offset, color(peak * share)))+ .collect(),+ SpreadMode::Pad,+ tiny_skia::Transform::identity(),+ ) else {+ return;+ };+ let paint = tiny_skia::Paint {+ shader,+ anti_alias: true,+ ..Default::default()+ };+ if let Some(circle) = PathBuilder::from_circle(cx, cy, radius) {+ pm.fill_path(+ &circle,+ &paint,+ tiny_skia::FillRule::Winding,+ tiny_skia::Transform::identity(),+ None,+ );+ }+}++#[cfg(test)]+mod tests {+ use super::*;+ use crate::trajectory::{plan_move, MoveRequest, Pt, REST_HEADING};+ use crate::MotionConfig;+ use std::f64::consts::PI;++ fn plan(from: (f64, f64), to: (f64, f64)) -> Trajectory {+ plan_move(+ &MotionConfig::default(),+ &MoveRequest {+ from: Pt::new(from.0, from.1),+ from_heading: REST_HEADING,+ to: Pt::new(to.0, to.1),+ end_heading: REST_HEADING,+ target: None,+ seed: "pose".into(),+ reduced_motion: false,+ },+ )+ }++ fn times(traj: &Trajectory) -> impl Iterator<Item = f64> + '_ {+ (0..=400).map(move |i| traj.arrival_t * f64::from(i) / 400.0)+ }++ #[test]+ fn the_float_is_the_historical_loop_within_its_bounds() {+ // #2603: sway 5, bob 6 about a lift of 5 canvas units, tilt 2.5°,+ // one loop every 4 s.+ let k = f64::from(crate::theme::DISPLAY_SIZE) / f64::from(crate::theme::CANVAS_SIZE);+ let at = |phase: f64| float_at(phase * FLOAT_SECS);+ let close = |a: f64, b: f64| (a - b).abs() < 1e-9;+ assert!(close(at(0.0).dy, k) && close(at(0.0).dx, 0.0));+ assert!(close(at(0.0).tilt, 2.5f64.to_radians()));+ assert!(close(at(0.25).dx, 5.0 * k) && close(at(0.25).dy, -5.0 * k));+ assert!(close(at(0.5).dy, -11.0 * k) && close(at(0.5).tilt, -2.5f64.to_radians()));+ let (a, b) = (float_at(1.3), float_at(1.3 + FLOAT_SECS));+ assert!(+ close(a.dx, b.dx) && close(a.dy, b.dy) && close(a.tilt, b.tilt),+ "a 4 s loop"+ );+ let (mut dx, mut dy, mut tilt) = ((0f64, 0f64), (0f64, 0f64), (0f64, 0f64));+ for i in 0..=4000 {+ let f = float_at(FLOAT_SECS * f64::from(i) / 4000.0);+ dx = (dx.0.min(f.dx), dx.1.max(f.dx));+ dy = (dy.0.min(f.dy), dy.1.max(f.dy));+ tilt = (tilt.0.min(f.tilt), tilt.1.max(f.tilt));+ }+ // About 3.3 pt of sway, 3.9 pt of bob and 5° of tilt, peak to peak.+ assert!((dx.1 - dx.0 - 3.28).abs() < 0.01, "{dx:?}");+ assert!((dy.1 - dy.0 - 3.94).abs() < 0.01, "{dy:?}");+ assert!(+ (tilt.1 - tilt.0 - 5f64.to_radians()).abs() < 1e-6,+ "{tilt:?}"+ );+ // Never more than 3.61 pt from the hotspot (the old miss at a click).+ assert!(dy.0 >= -11.0 * k - 1e-9 && dy.1 <= k + 1e-9);+ // Any amplitude stays within the full float, and 0 is exactly 0.+ for amp in [0.0, 0.3, 0.7, 1.0, 1.4] {+ let f = float_at(2.1).scaled(amp);+ assert!(+ f.dx.abs() <= FLOAT_SWAY_PT + 1e-9 && f.tilt.abs() <= FLOAT_TILT_RADIANS + 1e-9+ );+ assert!(f.dy.abs() <= FLOAT_LIFT_PT + FLOAT_BOB_PT + 1e-9);+ }+ assert_eq!(float_at(2.1).scaled(0.0), FloatOffset::ZERO);+ }++ #[test]+ fn the_rest_amplitude_eases_out_holds_at_zero_and_eases_back_in() {+ assert_eq!(rest_amplitude(0.0, 0.0), 0.0);+ assert_eq!(rest_amplitude(0.0, 0.8), 0.8, "no jump when a cue arrives");+ assert_eq!(rest_amplitude(FLOAT_EASE_OUT_SECS, 1.0), 0.0);+ assert_eq!(rest_amplitude(FLOAT_HOLD_SECS, 1.0), 0.0, "held at 0");+ assert_eq!(+ rest_amplitude(FLOAT_HOLD_SECS + FLOAT_EASE_IN_SECS, 0.0),+ 1.0+ );+ let mut last = rest_amplitude(0.0, 1.0);+ for i in 1..=600 {+ let a = rest_amplitude(f64::from(i) / 300.0, 1.0);+ assert!((0.0..=1.0).contains(&a));+ assert!((a - last).abs() < 0.05, "smooth at {i}: {last} -> {a}");+ last = a;+ }+ }++ #[test]+ fn the_travel_amplitude_carries_in_and_is_exactly_zero_at_arrival() {+ let traj = plan((100.0, 100.0), (700.0, 400.0));+ for start in [0.0, 0.4, 1.0] {+ assert_eq!(+ travel_amplitude(&traj, 0.0, start),+ start,+ "no jump at the start"+ );+ assert_eq!(travel_amplitude(&traj, traj.arrival_t, start), 0.0);+ assert!(travel_amplitude(&traj, traj.arrival_t - 1e-4, start) < 1e-3);+ assert_eq!(+ travel_amplitude(&traj, traj.arrival_t * 0.5, start),+ 1.0,+ "floats in travel"+ );+ let mut last = start;+ for t in times(&traj) {+ let a = travel_amplitude(&traj, t, start);+ assert!((0.0..=1.0).contains(&a), "{a}");+ assert!((a - last).abs() < 0.1, "jump at {t}: {last} -> {a}");+ last = a;+ }+ }+ }++ #[test]+ fn short_hops_only_ease_the_float_out() {+ let traj = plan((100.0, 100.0), (120.0, 110.0));+ for t in times(&traj) {+ let a = travel_amplitude(&traj, t, 0.6);+ assert!((0.0..=0.6).contains(&a), "{a}");+ }+ assert_eq!(travel_amplitude(&traj, traj.arrival_t, 0.6), 0.0);+ }++ #[test]+ fn lean_is_capped_and_upright_at_both_ends() {+ for to in [+ (700.0, 400.0),+ (100.0, 600.0),+ (100.0, 20.0),+ (-400.0, 100.0),+ ] {+ let traj = plan((100.0, 100.0), to);+ let mut peak: f64 = 0.0;+ for t in times(&traj) {+ let r = travel_rotation(&traj, t, RotateMode::Lean, false);+ assert!(r.abs() <= LEAN_MAX_RADIANS + 1e-9, "{to:?} {r}");+ let dragging = travel_rotation(&traj, t, RotateMode::Lean, true);+ assert!(+ dragging.abs() <= LEAN_MAX_DRAG_RADIANS + 1e-9,+ "{to:?} {dragging}"+ );+ peak = peak.max(r.abs());+ }+ assert!(peak > 10f64.to_radians(), "{to:?} leans: {peak}");+ assert_eq!(travel_rotation(&traj, 0.0, RotateMode::Lean, false), 0.0);+ assert_eq!(+ travel_rotation(&traj, traj.arrival_t, RotateMode::Lean, false),+ 0.0+ );+ assert_eq!(+ travel_rotation(&traj, traj.duration(), RotateMode::Heading, false),+ 0.0+ );+ }+ }++ #[test]+ fn heading_points_the_tip_along_the_path() {+ let traj = plan((100.0, 300.0), (900.0, 300.0));+ let t = traj.arrival_t * 0.5;+ let (vx, vy) = traj.velocity_at(t);+ let travel = vy.atan2(vx);+ let r = travel_rotation(&traj, t, RotateMode::Heading, false);+ let tip = tip_axis() + r;+ assert!(+ wrap_angle(tip - travel).abs() < 0.05,+ "tip {tip} travel {travel}"+ );+ // A straight downward move turns the tip well past the 30° lean.+ let down = plan((300.0, 100.0), (300.0, 700.0));+ let r = travel_rotation(&down, down.arrival_t * 0.5, RotateMode::Heading, false);+ assert!(r.abs() > PI / 2.0, "{r}");+ }++ #[test]+ fn heading_turns_upside_down_on_downward_moves_without_a_snap() {+ // Straight down and a few degrees either side, where the angle+ // crosses +-180°: the turn stays continuous at 120 Hz.+ for to in [+ (300.0, 700.0),+ (290.0, 700.0),+ (310.0, 700.0),+ (240.0, 700.0),+ ] {+ let traj = plan((300.0, 100.0), to);+ let mut last = travel_rotation(&traj, 0.0, RotateMode::Heading, false);+ let mut peak: f64 = 0.0;+ let steps = (traj.arrival_t * 120.0).ceil() as usize;+ for i in 1..=steps {+ let t = traj.arrival_t * i as f64 / steps as f64;+ let r = travel_rotation(&traj, t, RotateMode::Heading, false);+ assert!(+ (r - last).abs() < 10f64.to_radians(),+ "{to:?}: jumped {:.1}° at {t:.3}",+ (r - last).abs().to_degrees()+ );+ peak = peak.max(r.abs());+ last = r;+ }+ assert!(peak > 2.0 * PI / 3.0, "{to:?} turns over: {peak}");+ assert!(last.abs() < 1e-9, "{to:?} upright at arrival: {last}");+ }+ }++ #[test]+ fn short_hops_and_off_never_rotate() {+ let hop = plan((100.0, 100.0), (130.0, 110.0));+ let long = plan((100.0, 100.0), (700.0, 400.0));+ for t in times(&hop) {+ assert_eq!(travel_rotation(&hop, t, RotateMode::Heading, false), 0.0);+ }+ for t in times(&long) {+ assert_eq!(travel_rotation(&long, t, RotateMode::Off, false), 0.0);+ }+ }++ #[test]+ fn the_halo_takes_the_theme_accent_with_the_session_tint() {+ let default = crate::embedded_default_theme();+ let [r, g, b, _] = crate::DEFAULT_CURSOR_FILL;+ assert_eq!(halo_rgb(Some(&default), "default"), [r, g, b]);+ let [r, g, b, _] = crate::session_fill_rgba("agent-1");+ assert_eq!(halo_rgb(Some(&default), "agent-1"), [r, g, b]);+ assert_eq!(halo_rgb(None, "agent-1"), [r, g, b]);++ // A custom theme keeps its own accent, whatever the session.+ let mut custom = (*default).clone();+ custom.id = "example.orange".into();+ for animation in custom.actions.values_mut() {+ for frame in &mut animation.frames {+ for command in &mut frame.commands {+ if command.fill == Some(crate::DEFAULT_CURSOR_FILL) {+ command.fill = Some([250, 120, 20, 255]);+ }+ }+ }+ }+ assert_eq!(halo_rgb(Some(&custom), "agent-1"), [250, 120, 20]);+ }++ #[test]+ fn the_halo_peaks_at_eleven_percent_and_fades_to_nothing_at_its_edge() {+ let mut pm = tiny_skia::Pixmap::new(64, 64).unwrap();+ paint_halo(&mut pm, 32.0, 32.0, 28.0, [94, 192, 232], HALO_PEAK_ALPHA);+ let alpha = |x: u32, y: u32| pm.pixel(x, y).unwrap().alpha();+ let centre = alpha(32, 32);+ assert!((25..=30).contains(¢re), "{centre}");+ assert!(alpha(32 + 20, 32) < centre / 2);+ assert!(alpha(32 + 27, 32) <= 2);+ assert_eq!(alpha(1, 1), 0);+ }++ #[test]+ fn the_body_offset_is_the_centre_of_the_painted_arrow() {+ let mut core = crate::RenderStateCore::new(crate::CursorConfig::default());+ core.options_override = Some(crate::CursorOptions::NONE);+ core.pos = crate::anchor_for_pointer(60.0, 40.0, REST_HEADING);+ core.placed = true;+ let mut pm = tiny_skia::Pixmap::new(120, 100).unwrap();+ crate::paint_cursor(&mut pm, &core, 0.0, 0.0, None, 1.0);+ let (mut sx, mut sy, mut n) = (0.0, 0.0, 0.0);+ for y in 0..100 {+ for x in 0..120 {+ if pm.pixel(x, y).unwrap().alpha() > 128 {+ sx += f64::from(x) + 0.5;+ sy += f64::from(y) + 0.5;+ n += 1.0;+ }+ }+ }+ let (cx, cy) = (sx / n - 60.0, sy / n - 40.0);+ assert!((cx - BODY_OFFSET_PT.0).abs() < 0.5, "{cx}");+ assert!((cy - BODY_OFFSET_PT.1).abs() < 0.5, "{cy}");+ // The tip axis points up and a little left of the body.+ let axis = tip_axis().to_degrees();+ assert!((-105.0..-95.0).contains(&axis), "{axis}");+ }+}diff --git a/libs/cua-driver/rust/crates/cursor-overlay/src/lib.rs b/libs/cua-driver/rust/crates/cursor-overlay/src/lib.rsindex 8feb2befa4..e69e7f5344 100644--- a/libs/cua-driver/rust/crates/cursor-overlay/src/lib.rs+++ b/libs/cua-driver/rust/crates/cursor-overlay/src/lib.rs@@ -14,8 +14,10 @@ pub mod badge_mode;pub mod capture_exclusion;pub mod capture_utils;pub mod cursor_options;+pub mod cursor_pose;pub mod motion;pub mod motion_defaults;+pub mod pose_stream;pub mod render_map;pub mod render_state;pub mod session_badge;@@ -29,7 +31,7 @@ pub mod z_order;pub use badge_glyphs::{BadgeChip, BadgeGlyph};pub use badge_mode::BadgeMode;-pub use cursor_options::CursorOptions;+pub use cursor_options::{CursorOptions, RotateMode};pub use motion::{MotionConfig, MotionEffects, MotionStyle, MotionTiming, ResolvedEffects, Spring,DEFAULT_FIXED_MS,diff --git a/libs/cua-driver/rust/crates/cursor-overlay/src/pose_stream.rs b/libs/cua-driver/rust/crates/cursor-overlay/src/pose_stream.rsnew file mode 100644index 0000000000..7423c9d0ae--- /dev/null+++ b/libs/cua-driver/rust/crates/cursor-overlay/src/pose_stream.rs@@ -0,0 +1,721 @@+// SPDX-License-Identifier: MIT+// Copyright (c) 2026 Cua AI, Inc.++//! Poses for a cursor surface that draws and animates the cursor itself.+//!+//! The GNOME Shell helper paints the agent cursor inside the compositor, so+//! it cannot run [`crate::paint_cursor`]. It still gets the same motion: a+//! [`PoseModel`] keeps one [`RenderStateCore`] per session, advanced by the+//! wall clock, and every planned move becomes a [`PoseTrack`] of hotspot+//! position, float and rotation sampled from that core. The helper only plays+//! the samples back, then carries the float on at rest from the clock at the+//! end of the track ([`RestFloat`]) as [`PoseLook`] describes it, until the+//! next move. The planner, the float, the rotation modes and the+//! halo colour therefore come from one place for every backend.++use std::time::Instant;++use serde_json::json;++use crate::{+ CursorConfig, CursorKey, KeyedOverlayCommand, OverlayCommand, OverlayMsg, RenderMap,+ RenderStateCore,+};++/// Sample spacing of a [`PoseTrack`]. The helper interpolates between them.+pub const POSE_STEP_SECS: f64 = 1.0 / 60.0;+/// Upper bound on samples per track (the longest legal glide is 5 s; the+/// settle after it is short).+const MAX_SAMPLES: usize = 1_200;++/// One pose of the cursor: the hotspot, the float offset in points (y down,+/// negative is up) and the rotation from upright in radians (clockwise,+/// y down; the heading rotation plus the float tilt).+#[derive(Debug, Clone, Copy, PartialEq)]+pub struct PoseSample {+ /// Seconds from the start of the track.+ pub t: f64,+ pub x: f64,+ pub y: f64,+ pub float_dx: f64,+ pub float_dy: f64,+ pub rotation: f64,+}++/// The float clock at the end of a track, so the surface carries it on at+/// rest with no snap: see [`crate::cursor_pose::rest_amplitude`].+#[derive(Debug, Clone, Copy, PartialEq)]+pub struct RestFloat {+ /// Seconds into the float loop.+ pub phase_secs: f64,+ /// Seconds since the float settled.+ pub hold_secs: f64,+ /// Amplitude it settled from.+ pub from: f64,+}++/// A planned move (or a snap) as poses to play back.+#[derive(Debug, Clone, PartialEq)]+pub struct PoseTrack {+ /// In time order. The first is the start pose, the last the end pose.+ pub samples: Vec<PoseSample>,+ /// Seconds into the track at which the hotspot arrives, where the float+ /// is exactly 0. `None` for a snap.+ pub arrival: Option<f64>,+ /// The float clock at the last sample.+ pub rest: RestFloat,+}++/// The halo as the surface should paint it.+#[derive(Debug, Clone, Copy, PartialEq)]+pub struct HaloLook {+ pub rgb: [u8; 3],+ pub radius_pt: f32,+ pub peak_alpha: f32,+ /// Gradient stops: (offset 0..1, share of `peak_alpha`).+ pub stops: [(f32, f32); 3],+ /// Centre of the arrow body from the hotspot, upright, in points.+ pub body_offset_pt: (f64, f64),+}++/// The float of [`crate::cursor_pose::float_at`] and its rest envelope, for+/// a surface that runs it itself at rest.+#[derive(Debug, Clone, Copy, PartialEq)]+pub struct FloatLook {+ pub secs: f64,+ pub sway_pt: f64,+ pub bob_pt: f64,+ pub lift_pt: f64,+ pub tilt_radians: f64,+ pub hold_secs: f64,+ pub ease_in_secs: f64,+ pub ease_out_secs: f64,+}++impl FloatLook {+ pub const DEFAULT: Self = Self {+ secs: crate::cursor_pose::FLOAT_SECS,+ sway_pt: crate::cursor_pose::FLOAT_SWAY_PT,+ bob_pt: crate::cursor_pose::FLOAT_BOB_PT,+ lift_pt: crate::cursor_pose::FLOAT_LIFT_PT,+ tilt_radians: crate::cursor_pose::FLOAT_TILT_RADIANS,+ hold_secs: crate::cursor_pose::FLOAT_HOLD_SECS,+ ease_in_secs: crate::cursor_pose::FLOAT_EASE_IN_SECS,+ ease_out_secs: crate::cursor_pose::FLOAT_EASE_OUT_SECS,+ };+}++/// What the surface paints at rest and around the arrow.+#[derive(Debug, Clone, Copy, PartialEq)]+pub struct PoseLook {+ /// `None` when the cursor rests still (`cursor.float` off, reduced+ /// motion, a custom theme or a cursor that never hides).+ pub float: Option<FloatLook>,+ /// `None` with `cursor.halo` off or on a surface that cannot blend.+ pub halo: Option<HaloLook>,+}++fn round(value: f64, places: i32) -> f64 {+ let scale = 10f64.powi(places);+ (value * scale).round() / scale+}++impl PoseTrack {+ /// Compact JSON for the helper: `{"samples": [[t, x, y, dx, dy, rot],+ /// ...], "arrival": t | null, "rest": [phase, hold, from]}`.+ pub fn to_json(&self) -> String {+ let samples: Vec<[f64; 6]> = self+ .samples+ .iter()+ .map(|s| {+ [+ round(s.t, 4),+ round(s.x, 2),+ round(s.y, 2),+ round(s.float_dx, 3),+ round(s.float_dy, 3),+ round(s.rotation, 4),+ ]+ })+ .collect();+ json!({+ "samples": samples,+ "arrival": self.arrival.map(|t| round(t, 4)),+ "rest": [+ round(self.rest.phase_secs, 4),+ round(self.rest.hold_secs.min(3_600.0), 4),+ round(self.rest.from, 4),+ ],+ })+ .to_string()+ }++ /// Seconds the hotspot takes to reach its target.+ pub fn arrival_secs(&self) -> f64 {+ self.arrival+ .unwrap_or_else(|| self.samples.last().map_or(0.0, |s| s.t))+ }+}++impl PoseLook {+ /// JSON for the helper: `{"float": {"secs", "sway", "bob", "lift",+ /// "tilt", "hold", "ease_in", "ease_out"} | null, "halo": {"rgb":+ /// "#rrggbb", "radius": pt, "peak": a, "stops": [[o, k], ...], "body":+ /// [x, y]} | null}`.+ pub fn to_json(&self) -> String {+ let float = self.float.map(|f| {+ json!({+ "secs": f.secs,+ "sway": round(f.sway_pt, 4),+ "bob": round(f.bob_pt, 4),+ "lift": round(f.lift_pt, 4),+ "tilt": round(f.tilt_radians, 5),+ "hold": f.hold_secs,+ "ease_in": f.ease_in_secs,+ "ease_out": f.ease_out_secs,+ })+ });+ let halo = self.halo.map(|halo| {+ let [r, g, b] = halo.rgb;+ json!({+ "rgb": format!("#{r:02x}{g:02x}{b:02x}"),+ "radius": halo.radius_pt,+ "peak": halo.peak_alpha,+ "stops": halo.stops.iter().map(|&(o, k)| [o, k]).collect::<Vec<_>>(),+ "body": [round(halo.body_offset_pt.0, 3), round(halo.body_offset_pt.1, 3)],+ })+ });+ json!({+ "float": float,+ "halo": halo,+ })+ .to_string()+ }+}++impl RenderStateCore {+ /// The rest of the current planned move as poses, `step` seconds apart,+ /// plus an exact sample at the arrival. Floats and rotation follow+ /// [`Self::float_offset`] and [`Self::painted_rotation`] on the cursor's+ /// own float clock, so the phase runs on and they are exactly 0 and+ /// upright at the arrival. `None` when no move is in flight.+ pub fn pose_track(&self, step: f64) -> Option<PoseTrack> {+ let traj = self.trajectory.as_ref()?;+ let step = if step.is_finite() && step > 0.0 {+ step+ } else {+ POSE_STEP_SECS+ };+ let (start, end, arrival) = (self.motion_t, traj.duration(), traj.arrival_t);+ // The float clock at `t`, as `tick_motion` will advance it.+ let rest_at = |t: f64| {+ let phase_secs = self.float_secs + (t - start);+ if t >= arrival && start < arrival {+ RestFloat {+ phase_secs,+ hold_secs: t - arrival,+ from: 0.0,+ }+ } else {+ RestFloat {+ phase_secs,+ hold_secs: self.float_hold_secs + (t - start),+ from: self.float_from,+ }+ }+ };+ let pose = |t: f64| {+ let rest = rest_at(t);+ let float = self.float_offset_at(t, rest.phase_secs, rest.hold_secs, rest.from);+ let s = traj.sample_at(t);+ PoseSample {+ t: t - start,+ x: s.x,+ y: s.y,+ float_dx: float.dx,+ float_dy: float.dy,+ rotation: self.heading_rotation_at(t) + float.tilt,+ }+ };+ let mut samples = Vec::new();+ let mut t = start;+ let mut arrival_added = arrival < start;+ while t < end && samples.len() < MAX_SAMPLES {+ if !arrival_added && t >= arrival {+ if t > arrival {+ samples.push(pose(arrival));+ }+ arrival_added = true;+ }+ samples.push(pose(t));+ t += step;+ }+ if !arrival_added && arrival < end {+ samples.push(pose(arrival));+ }+ let last = end.max(start);+ samples.push(pose(last));+ Some(PoseTrack {+ samples,+ arrival: Some((arrival - start).max(0.0)),+ rest: rest_at(last),+ })+ }++ /// The float clock now, for a surface that carries it on at rest.+ pub fn rest_float(&self) -> RestFloat {+ RestFloat {+ phase_secs: self.float_secs,+ hold_secs: self.float_hold_secs,+ from: self.float_from,+ }+ }++ /// The resting float and halo this cursor paints with now.+ pub fn pose_look(&self) -> PoseLook {+ // A cursor that never hides rests still, like `has_resting_motion`.+ let rests_floating = self.floats() && self.motion.idle_hide_ms > 0.0;+ let options = self.options();+ PoseLook {+ float: rests_floating.then_some(FloatLook::DEFAULT),+ halo: (options.halo && self.effects_capable).then(|| HaloLook {+ rgb: crate::cursor_pose::halo_rgb(self.theme.as_deref(), &self.cfg.cursor_id),+ radius_pt: crate::cursor_pose::HALO_RADIUS_PT,+ peak_alpha: crate::cursor_pose::HALO_PEAK_ALPHA,+ stops: crate::cursor_pose::HALO_STOPS,+ body_offset_pt: crate::cursor_pose::BODY_OFFSET_PT,+ }),+ }+ }++ fn hotspot(&self) -> (f64, f64) {+ crate::pointer_for_anchor(self.pos.0, self.pos.1, self.heading)+ }+}++/// Per-session cursor state for a self-animating surface, advanced by the+/// wall clock instead of a render loop.+pub struct PoseModel {+ map: RenderMap<RenderStateCore>,+ last_tick: Option<Instant>,+ /// Hotspot the surface last showed, so a session drawing on it for the+ /// first time starts from there instead of jumping.+ surface_hotspot: Option<(f64, f64)>,+}++impl PoseModel {+ pub fn new(template: CursorConfig) -> Self {+ Self {+ map: RenderMap::new(template, ()),+ last_tick: None,+ surface_hotspot: None,+ }+ }++ fn advance(&mut self, now: Instant) {+ if let Some(last) = self.last_tick {+ let dt = now.saturating_duration_since(last).as_secs_f64();+ if dt > 0.0 {+ self.map.tick_all(dt);+ }+ }+ self.last_tick = Some(now);+ }++ /// `key`'s cursor, created when absent. `None` for an ended session.+ pub fn cursor_mut(&mut self, key: &str) -> Option<&mut RenderStateCore> {+ self.map.cursor_mut(key)+ }++ /// Apply one overlay message at `now`. `draws` says whether it reaches+ /// the surface. Returns the poses to play for a move or snap that does.+ pub fn apply(&mut self, msg: &OverlayMsg, draws: bool, now: Instant) -> Option<PoseTrack> {+ self.advance(now);+ let OverlayMsg::Cmd(KeyedOverlayCommand { key, cmd }) = msg else {+ if let OverlayMsg::Remove(key) = msg {+ if draws {+ self.surface_hotspot = None;+ }+ self.map.remove(key.clone());+ } else if let OverlayMsg::Revive(key) = msg {+ self.map.revive(key.clone());+ }+ return None;+ };+ if let OverlayCommand::MoveTo { x, y, .. } = cmd {+ let from = self.surface_hotspot.filter(|_| draws);+ if let Some(core) = self.map.cursor_mut(key).filter(|core| !core.placed) {+ core.pos = match from {+ Some((hx, hy)) => crate::anchor_for_pointer(hx, hy, core.heading),+ None => crate::seed_position(*x, *y, None),+ };+ core.placed = true;+ }+ }+ self.map.apply_command(key.clone(), cmd.clone());+ if !draws {+ return None;+ }+ let core = self.map.cursors.get(key)?;+ let track = match cmd {+ OverlayCommand::MoveTo { .. } => core.pose_track(POSE_STEP_SECS),+ OverlayCommand::SnapTo { .. } => {+ let (x, y) = core.hotspot();+ let float = core.float_offset();+ Some(PoseTrack {+ samples: vec![PoseSample {+ t: 0.0,+ x,+ y,+ float_dx: float.dx,+ float_dy: float.dy,+ rotation: float.tilt,+ }],+ arrival: None,+ rest: core.rest_float(),+ })+ }+ OverlayCommand::ClickPulse { x, y } => {+ self.surface_hotspot = Some((*x, *y));+ None+ }+ _ => None,+ };+ if let Some(end) = track.as_ref().and_then(|track| track.samples.last()) {+ self.surface_hotspot = Some((end.x, end.y));+ }+ track+ }++ /// The look `key`'s cursor paints with now.+ pub fn look(&mut self, key: &str) -> Option<PoseLook> {+ self.map.cursor_mut(key).map(|core| core.pose_look())+ }++ /// Moves planned so far for `key`; a later move replaces an earlier one.+ pub fn move_seq(&self, key: &CursorKey) -> Option<u64> {+ self.map.cursors.get(key).map(|core| core.move_seq)+ }+}++#[cfg(test)]+mod tests {+ use super::*;+ use crate::cursor_options::RotateMode;+ use crate::cursor_pose::{+ FLOAT_LIFT_PT, FLOAT_SWAY_PT, FLOAT_TILT_RADIANS, LEAN_MAX_DRAG_RADIANS, LEAN_MAX_RADIANS,+ };+ use crate::CursorOptions;+ use std::time::Duration;++ fn cmd(key: &str, cmd: OverlayCommand) -> OverlayMsg {+ OverlayMsg::Cmd(KeyedOverlayCommand {+ key: key.to_owned(),+ cmd,+ })+ }++ fn move_to(x: f64, y: f64) -> OverlayCommand {+ OverlayCommand::MoveTo {+ x,+ y,+ end_heading_radians: std::f64::consts::FRAC_PI_4,+ target: None,+ }+ }++ fn model_with(key: &str, options: CursorOptions) -> PoseModel {+ let mut model = PoseModel::new(CursorConfig::default());+ model.cursor_mut(key).unwrap().options_override = Some(options);+ model+ }++ fn opts(rotate: RotateMode) -> CursorOptions {+ CursorOptions {+ float: true,+ halo: true,+ rotate,+ ..CursorOptions::default()+ }+ }++ fn arrival_sample(track: &PoseTrack) -> PoseSample {+ let at = track.arrival.unwrap();+ *track.samples.iter().find(|s| s.t == at).unwrap()+ }++ fn placed_model(key: &str, options: CursorOptions, now: Instant) -> PoseModel {+ let mut model = model_with(key, options);+ model.apply(+ &cmd(+ key,+ OverlayCommand::SnapTo {+ x: 100.0,+ y: 100.0,+ heading_radians: None,+ },+ ),+ true,+ now,+ );+ model+ }++ #[test]+ fn a_move_floats_while_travelling_and_arrives_settled_and_upright() {+ for mode in [RotateMode::Off, RotateMode::Lean, RotateMode::Heading] {+ let now = Instant::now();+ let mut model = placed_model("s", opts(mode), now);+ let track = model+ .apply(&cmd("s", move_to(800.0, 500.0)), true, now)+ .expect("a move plays");+ let first = track.samples[0];+ let last = *track.samples.last().unwrap();+ assert_eq!(first.t, 0.0);+ assert!((last.x - 800.0).abs() < 1.0 && (last.y - 500.0).abs() < 1.0);+ let arrival = arrival_sample(&track);+ assert_eq!(+ (arrival.float_dx, arrival.float_dy, arrival.rotation),+ (0.0, 0.0, 0.0),+ "{mode:?}: settled and upright at arrival"+ );+ assert!(+ track+ .samples+ .iter()+ .any(|s| s.float_dx.hypot(s.float_dy) > 1.0),+ "{mode:?}: floats while travelling"+ );+ assert!(+ track.samples.iter().any(|s| s.float_dx.abs() > 0.5),+ "{mode:?}: sways while travelling"+ );+ assert!(track.samples.windows(2).all(|w| w[0].t < w[1].t));+ let peak = track+ .samples+ .iter()+ .map(|s| s.rotation.abs())+ .fold(0.0, f64::max);+ match mode {+ RotateMode::Off => assert!(peak <= FLOAT_TILT_RADIANS + 1e-9, "only the tilt"),+ RotateMode::Lean => {+ assert!(peak > 0.1 && peak <= LEAN_MAX_RADIANS + FLOAT_TILT_RADIANS + 1e-9)+ }+ RotateMode::Heading => assert!(peak > LEAN_MAX_RADIANS),+ }+ }+ }++ #[test]+ fn a_drag_leans_at_most_15_degrees_and_drops_settled() {+ let now = Instant::now();+ let mut model = placed_model("s", opts(RotateMode::Lean), now);+ model.apply(&cmd("s", OverlayCommand::SetPressed(true)), true, now);+ let track = model+ .apply(&cmd("s", move_to(700.0, 160.0)), true, now)+ .unwrap();+ let peak = track+ .samples+ .iter()+ .map(|s| s.rotation.abs())+ .fold(0.0, f64::max);+ assert!(+ peak > 0.05 && peak <= LEAN_MAX_DRAG_RADIANS + FLOAT_TILT_RADIANS + 1e-9,+ "{peak}"+ );+ assert!(track+ .samples+ .iter()+ .any(|s| s.float_dx.hypot(s.float_dy) > 1.0));+ let drop = arrival_sample(&track);+ assert_eq!(+ (drop.float_dx, drop.float_dy, drop.rotation),+ (0.0, 0.0, 0.0)+ );+ }++ #[test]+ fn short_hops_stay_upright_and_snaps_keep_the_resting_loop() {+ let now = Instant::now();+ let mut model = placed_model("s", opts(RotateMode::Heading), now);+ let hop = model+ .apply(&cmd("s", move_to(120.0, 110.0)), true, now)+ .unwrap();+ // Only the float tilt, which eases out; no heading turn.+ assert!(hop+ .samples+ .iter()+ .all(|s| s.rotation.abs() <= FLOAT_TILT_RADIANS + 1e-9));+ assert_eq!(arrival_sample(&hop).rotation, 0.0);+ let snap = model+ .apply(+ &cmd(+ "s",+ OverlayCommand::SnapTo {+ x: 400.0,+ y: 300.0,+ heading_radians: None,+ },+ ),+ true,+ now + Duration::from_secs(3),+ )+ .unwrap();+ assert_eq!(snap.samples.len(), 1);+ assert_eq!(snap.arrival, None);+ // The float clock ran on: the snap keeps the phase.+ let core = model.cursor_mut("s").unwrap();+ assert_eq!(snap.rest.phase_secs, core.float_secs);+ assert!(snap.rest.phase_secs >= 2.99);+ }++ #[test]+ fn the_float_phase_runs_on_across_moves() {+ let now = Instant::now();+ let mut model = placed_model("s", opts(RotateMode::Heading), now);+ let first = model+ .apply(&cmd("s", move_to(700.0, 400.0)), true, now)+ .unwrap();+ let later = now + Duration::from_secs_f64(first.samples.last().unwrap().t + 0.7);+ let second = model+ .apply(&cmd("s", move_to(200.0, 500.0)), true, later)+ .unwrap();+ // The second track starts on the clock the first one left off at,+ // 0.7 s on, rather than from phase 0.+ let carried = first.rest.phase_secs + 0.7;+ let phase = model.cursor_mut("s").unwrap().float_secs;+ assert!((phase - carried).abs() < 1e-3, "{phase} vs {carried}");+ assert!((second.rest.phase_secs - phase - second.samples.last().unwrap().t).abs() < 1e-6);+ }++ #[test]+ fn the_float_carries_over_from_rest_without_a_jump() {+ let now = Instant::now();+ let mut model = placed_model("s", opts(RotateMode::Off), now);+ // Two seconds into the loop the resting cursor is at its peak lift.+ let later = now + Duration::from_secs(2);+ let track = model+ .apply(&cmd("s", move_to(900.0, 600.0)), true, later)+ .unwrap();+ let first = track.samples[0];+ assert!(+ (first.float_dy + FLOAT_LIFT_PT + crate::cursor_pose::FLOAT_BOB_PT).abs() < 0.05,+ "starts at the resting float: {}",+ first.float_dy+ );+ for w in track.samples.windows(2) {+ let step = (w[1].float_dx - w[0].float_dx)+ .abs()+ .max((w[1].float_dy - w[0].float_dy).abs());+ assert!(step < 0.5, "no jump between samples: {step}");+ assert!(w[1].float_dx.abs() <= FLOAT_SWAY_PT + 1e-9);+ }+ let end = arrival_sample(&track);+ assert_eq!((end.float_dx, end.float_dy, end.rotation), (0.0, 0.0, 0.0));+ }++ #[test]+ fn float_off_and_reduced_motion_send_still_poses() {+ let now = Instant::now();+ let options = CursorOptions {+ float: false,+ ..opts(RotateMode::Lean)+ };+ let mut model = placed_model("s", options, now);+ let track = model+ .apply(&cmd("s", move_to(900.0, 600.0)), true, now)+ .unwrap();+ assert!(track+ .samples+ .iter()+ .all(|s| s.float_dy == 0.0 && s.float_dx == 0.0));+ assert_eq!(model.look("s").unwrap().float, None);++ let mut model = placed_model("r", opts(RotateMode::Heading), now);+ model.cursor_mut("r").unwrap().visual.reduced_motion = crate::ReducedMotion::On;+ let track = model+ .apply(&cmd("r", move_to(900.0, 600.0)), true, now)+ .unwrap();+ assert!(track+ .samples+ .iter()+ .all(|s| s.float_dy == 0.0 && s.float_dx == 0.0 && s.rotation == 0.0));+ let look = model.look("r").unwrap();+ assert_eq!(look.float, None);+ assert!(look.halo.is_some(), "reduced motion keeps the halo");+ }++ #[test]+ fn the_look_follows_cursor_halo_and_the_session_colour() {+ let mut model = model_with("a", opts(RotateMode::Off));+ let look = model.look("a").unwrap();+ assert_eq!(look.float, Some(FloatLook::DEFAULT));+ let halo = look.halo.unwrap();+ assert_eq!(halo.rgb, crate::cursor_pose::halo_rgb(None, "a"));+ assert_eq!(halo.peak_alpha, crate::cursor_pose::HALO_PEAK_ALPHA);+ assert_eq!(halo.radius_pt, crate::cursor_pose::HALO_RADIUS_PT);+ model.cursor_mut("b").unwrap().options_override = Some(opts(RotateMode::Off));+ assert_ne!(model.look("b").unwrap().halo.unwrap().rgb, halo.rgb);++ model.cursor_mut("a").unwrap().options_override = Some(CursorOptions {+ halo: false,+ ..opts(RotateMode::Off)+ });+ assert_eq!(model.look("a").unwrap().halo, None);+ model.cursor_mut("b").unwrap().effects_capable = false;+ assert_eq!(model.look("b").unwrap().halo, None);+ }++ #[test]+ fn a_new_session_starts_from_where_the_surface_shows_the_cursor() {+ let now = Instant::now();+ let mut model = placed_model("a", opts(RotateMode::Off), now);+ model.apply(&cmd("a", move_to(500.0, 400.0)), true, now);+ model.cursor_mut("b").unwrap().options_override = Some(opts(RotateMode::Off));+ let track = model+ .apply(&cmd("b", move_to(900.0, 700.0)), true, now)+ .unwrap();+ let start = track.samples[0];+ assert!((start.x - 500.0).abs() < 1.0 && (start.y - 400.0).abs() < 1.0);+ // A session that does not reach the surface sends nothing.+ assert!(model+ .apply(&cmd("c", move_to(10.0, 10.0)), false, now)+ .is_none());+ }++ #[test]+ fn the_json_carries_every_sample_and_the_look() {+ let now = Instant::now();+ let mut model = placed_model("s", opts(RotateMode::Lean), now);+ let track = model+ .apply(&cmd("s", move_to(640.0, 480.0)), true, now)+ .unwrap();+ let parsed: serde_json::Value = serde_json::from_str(&track.to_json()).unwrap();+ let samples = parsed["samples"].as_array().unwrap();+ assert_eq!(samples.len(), track.samples.len());+ assert!(samples.iter().all(|s| s.as_array().unwrap().len() == 6));+ assert_eq!(+ parsed["arrival"].as_f64().unwrap(),+ round(track.arrival.unwrap(), 4)+ );+ assert_eq!(parsed["rest"].as_array().unwrap().len(), 3);+ assert!(track.arrival_secs() > 0.0);++ let look: serde_json::Value =+ serde_json::from_str(&model.look("s").unwrap().to_json()).unwrap();+ assert!(look["halo"]["rgb"].as_str().unwrap().starts_with('#'));+ assert_eq!(look["halo"]["stops"].as_array().unwrap().len(), 3);+ assert_eq!(look["float"]["secs"].as_f64().unwrap(), 4.0);+ assert!((look["float"]["sway"].as_f64().unwrap() - FLOAT_SWAY_PT).abs() < 1e-3);+ }++ #[test]+ fn an_ended_session_plays_nothing() {+ let now = Instant::now();+ let mut model = placed_model("s", opts(RotateMode::Off), now);+ model.apply(&OverlayMsg::Remove("s".into()), true, now);+ assert!(model+ .apply(&cmd("s", move_to(300.0, 300.0)), true, now)+ .is_none());+ }+}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 908d531159..4f5644f2ac 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@@ -33,6 +33,7 @@//! element highlight — drawn inside [`render_frame`] when the caller//! supplies one via the optional argument).+use crate::cursor_pose::FloatOffset;use crate::trajectory::{plan_move, MoveRequest, Pt, Trajectory};use crate::{BadgeMode, CompiledTheme, CursorAction, CursorConfig, CursorOptions, CursorVisualState,@@ -120,6 +121,18 @@ pub struct RenderStateCore {pub motion_t: f64,/// Whether the current trajectory still owes its arrival signal.pub arrival_pending: bool,+ /// Seconds into the float loop. Owned by the cursor, not the action,+ /// and never reset, so the phase carries on across every move, click+ /// and cue. Only the amplitude settles to 0 for precise actions.+ pub float_secs: f64,+ /// Seconds since the float last settled (an arrival, or a click, press+ /// or semantic cue at rest); see [`crate::cursor_pose::rest_amplitude`].+ pub float_hold_secs: f64,+ /// Float amplitude when it last settled, eased out from there.+ pub float_from: f64,+ /// Float amplitude when the current move began, eased out during the+ /// move so the float never jumps.+ pub float_start_amp: f64,/// Moves planned so far; seeds each trajectory.pub move_seq: u64,/// Seconds since the last click, while click effects play.@@ -220,6 +233,12 @@ impl RenderStateCore {trajectory: None,motion_t: 0.0,arrival_pending: false,+ float_secs: 0.0,+ // A fresh cursor floats fully at rest.+ float_hold_secs: crate::cursor_pose::FLOAT_HOLD_SECS+ + crate::cursor_pose::FLOAT_EASE_IN_SECS,+ float_from: 0.0,+ float_start_amp: 1.0,move_seq: 0,click_age: None,click_point: (0.0, 0.0),@@ -379,6 +398,94 @@ impl RenderStateCore {}}+ /// Float offset painted this frame: the historical 4 s sway, bob and+ /// tilt ([`crate::cursor_pose::float_at`]) at the current amplitude.+ /// Exactly 0 at every arrival and while a click, press, drop, scroll or+ /// typing cue holds it; [`FloatOffset::ZERO`] with `cursor.float` off,+ /// reduced motion or a custom theme.+ pub fn float_offset(&self) -> FloatOffset {+ self.float_offset_at(+ self.motion_t,+ self.float_secs,+ self.float_hold_secs,+ self.float_from,+ )+ }++ /// Float amplitude (0..1) painted this frame.+ pub fn float_amplitude(&self) -> f64 {+ self.float_amplitude_at(self.motion_t, self.float_hold_secs, self.float_from)+ }++ pub(crate) fn float_amplitude_at(&self, motion_t: f64, hold: f64, from: f64) -> f64 {+ if !self.floats() {+ return 0.0;+ }+ match self.trajectory.as_ref() {+ Some(traj) if crate::cursor_pose::travelling(traj, motion_t) => {+ crate::cursor_pose::travel_amplitude(traj, motion_t, self.float_start_amp)+ }+ _ => crate::cursor_pose::rest_amplitude(hold, from),+ }+ }++ /// [`Self::float_offset`] with the move `motion_t` seconds in, the float+ /// clock at `float_secs`, `hold` seconds since it settled from `from`.+ pub(crate) fn float_offset_at(+ &self,+ motion_t: f64,+ float_secs: f64,+ hold: f64,+ from: f64,+ ) -> FloatOffset {+ crate::cursor_pose::float_at(float_secs)+ .scaled(self.float_amplitude_at(motion_t, hold, from))+ }++ /// Settle the float for a precise action at rest: the amplitude eases+ /// out from where it is, holds at 0, then eases back in. The phase runs+ /// on. While travelling the arrival settles it instead.+ fn settle_float(&mut self) {+ let travelling = self+ .trajectory+ .as_ref()+ .is_some_and(|traj| crate::cursor_pose::travelling(traj, self.motion_t));+ if !travelling {+ self.float_from = self.float_amplitude();+ self.float_hold_secs = 0.0;+ }+ }++ /// Whether this cursor floats at all: `cursor.float` on, the built-in+ /// theme, and no reduced motion.+ pub fn floats(&self) -> bool {+ let default_theme = self+ .theme+ .as_deref()+ .is_none_or(|theme| theme.id == crate::DEFAULT_THEME_ID);+ self.options().float && default_theme && !self.reduced_motion()+ }++ /// Rotation from upright (radians) painted this frame: the heading+ /// rotation (`cursor.rotate`) plus the float tilt. Upright at every+ /// arrival and while a click, press, scroll or typing cue holds the+ /// float.+ pub fn painted_rotation(&self) -> f64 {+ self.heading_rotation_at(self.motion_t) + self.float_offset().tilt+ }++ /// The `cursor.rotate` part of [`Self::painted_rotation`] with the move+ /// `motion_t` seconds in: only while travelling, upright at arrival.+ pub(crate) fn heading_rotation_at(&self, motion_t: f64) -> f64 {+ let mode = self.options().rotate;+ match self.trajectory.as_ref() {+ Some(traj) if !self.reduced_motion() => {+ crate::cursor_pose::travel_rotation(traj, motion_t, mode, self.pressed)+ }+ _ => 0.0,+ }+ }+/// The opt-in extras this cursor paints with now.pub fn options(&self) -> CursorOptions {self.options_override@@ -662,8 +769,18 @@ impl RenderStateCore {pub fn tick_motion(&mut self, dt: f64) -> bool {let dt = if dt.is_finite() { dt.max(0.0) } else { 0.0 };let mut fire_arrival = false;+ self.float_secs = (self.float_secs + dt) % (86_400.0 * crate::cursor_pose::FLOAT_SECS);+ self.float_hold_secs = (self.float_hold_secs + dt).min(3_600.0);if let Some(traj) = self.trajectory.as_ref() {+ let was_travelling = crate::cursor_pose::travelling(traj, self.motion_t);self.motion_t += dt;+ if was_travelling && !crate::cursor_pose::travelling(traj, self.motion_t) {+ // The travel float is exactly 0 at arrival: it holds there+ // for the click, drop or typing that follows. The phase+ // runs on.+ self.float_hold_secs = self.motion_t - traj.arrival_t;+ self.float_from = 0.0;+ }let s = traj.sample_at(self.motion_t);self.pos = crate::anchor_for_pointer(s.x, s.y, s.heading);self.heading = s.heading;@@ -816,6 +933,7 @@ impl RenderStateCore {// Plan the hotspot so it lands on `(x, y)`; the anchor follows// from the heading at every sample.let (fx, fy) = crate::pointer_for_anchor(self.pos.0, self.pos.1, self.heading);+ self.float_start_amp = self.float_amplitude();self.move_seq += 1;let request = MoveRequest {from: Pt::new(fx, fy),@@ -860,7 +978,18 @@ impl RenderStateCore {if let Some(heading) = heading_radians {self.heading = heading;}+ // A snap mid-move settles the float from where it was; at+ // rest it carries on.+ let travelling = self+ .trajectory+ .as_ref()+ .is_some_and(|traj| crate::cursor_pose::travelling(traj, self.motion_t));+ let amplitude = self.float_amplitude();self.cancel_motion();+ if travelling {+ self.float_from = amplitude;+ self.float_hold_secs = 0.0;+ }// The navigate mark a move plays by itself is an opt-in// action mark (`cursor.marks`).if self.options().marks@@ -900,6 +1029,9 @@ impl RenderStateCore {self.click_t = Some(0.0);self.click_age = Some(0.0);self.click_point = (x, y);+ // The move here already settled the float to 0; keep it+ // there through the click (and a double click's second).+ self.settle_float();// Likewise the click mark (`cursor.marks`).if self.options().marks&& matches!(@@ -922,6 +1054,8 @@ impl RenderStateCore {}OverlayCommand::SetPressed(v) => {self.pressed = v;+ // Drag start and drop land on the hotspot.+ self.settle_float();if v {let delivery = self.visual.delivery;let target = self.visual.target;@@ -963,6 +1097,8 @@ impl RenderStateCore {} => {self.visual.begin(action, delivery, target);self.semantic_cue = true;+ // Typing focus, scrolls and keys hold the float at 0 too.+ self.settle_float();// A semantic cue re-reveals an idle-faded cursor that already// has a position; `tick_idle` keeps it visible until the cue ends.self.idle_secs = 0.0;@@ -1285,15 +1421,12 @@ pub fn paint_cursor(let options = core.options();// Themes pivot on their hotspot, which is drawn at the pointer point.let (tip_x, tip_y) = crate::pointer_for_anchor(core.pos.0, core.pos.1, core.heading);- // The arrow stays upright (the rest heading, no rotation) unless- // `cursor.rotate` turns it toward the direction of travel. The hotspot- // above still follows the planned heading, so it lands on the target- // either way.- let heading = if options.rotate {- core.heading- } else {- crate::trajectory::REST_HEADING- };+ // The arrow is upright (the rest heading) unless `cursor.rotate` turns+ // it while it travels. The hotspot above still follows the planned+ // heading, so it lands on the target either way.+ let rotation = core.painted_rotation();+ let heading = crate::trajectory::REST_HEADING + rotation;+ let float = core.float_offset();let (tip_x, tip_y) = ((tip_x - origin_x) * s, (tip_y - origin_y) * s);let alpha_scale = core.idle_alpha as f32;@@ -1353,6 +1486,22 @@ pub fn paint_cursor(let effects = core.effect_frame();let effect_rgb = effect_rgb(crate::session_fill_rgba(&core.cfg.cursor_id));let to_px = |x: f64, y: f64| (((x - origin_x) * s) as f32, ((y - origin_y) * s) as f32);+ // The halo (`cursor.halo`) sits behind the arrow body and moves, floats+ // and turns with it. Translucent, so not on surfaces that cannot blend.+ if options.halo && core.effects_capable {+ let (bx, by) = crate::cursor_pose::BODY_OFFSET_PT;+ let (sin, cos) = rotation.sin_cos();+ let cx = tip_x + (bx * cos - by * sin + float.dx) * s;+ let cy = tip_y + (bx * sin + by * cos + float.dy) * s;+ crate::cursor_pose::paint_halo(+ pm,+ cx as f32,+ cy as f32,+ crate::cursor_pose::HALO_RADIUS_PT * sf,+ crate::cursor_pose::halo_rgb(core.theme.as_deref(), &core.cfg.cursor_id),+ crate::cursor_pose::HALO_PEAK_ALPHA * alpha_scale,+ );+ }paint_effects_under(pm, &effects, effect_rgb, f64::from(alpha_scale), &to_px, sf);// Click squish scales the artwork about its hotspot.let art_scale = backing_scale.max(1.0) * (1.0 - effects.squish as f32);@@ -1382,7 +1531,8 @@ pub fn paint_cursor(art_scale,alpha_scale,tint,- options.float,+ float.dx as f32,+ float.dy as f32,);} else {// Defensive fallback for a manually constructed RenderStateCore. The@@ -2539,6 +2689,11 @@ mod pointer_anchor_tests {fn cursor() -> RenderStateCore {let mut core = RenderStateCore::new(CursorConfig::default());core.theme = Some(hotspot_marker_theme());+ // The halo would pull the measured centroid off the marker.+ core.options_override = Some(crate::CursorOptions {+ halo: false,+ ..crate::CursorOptions::DEFAULT+ });core.motion.idle_hide_ms = 0.0;core}@@ -3111,7 +3266,7 @@ mod motion_equivalence_tests {#[cfg(test)]mod plain_cursor_tests {use super::*;- use crate::{CursorConfig, CursorOptions};+ use crate::{CursorConfig, CursorOptions, MotionStyle, RotateMode};use std::f64::consts::FRAC_PI_4;fn core(options: CursorOptions) -> RenderStateCore {@@ -3130,13 +3285,14 @@ mod plain_cursor_tests {}#[test]- fn only_the_float_is_on_by_default() {+ fn the_float_the_halo_and_heading_are_on_by_default() {assert_eq!(CursorOptions::default(),CursorOptions {marks: false,float: true,- rotate: false,+ rotate: RotateMode::Heading,+ halo: true,});let core = RenderStateCore::new(CursorConfig::default());@@ -3220,21 +3376,38 @@ mod plain_cursor_tests {#[test]fn the_arrow_stays_upright_unless_rotation_is_on() {- let upright = paint(&core(CursorOptions::NONE), None);- let mut turned = core(CursorOptions::NONE);- turned.heading = FRAC_PI_4 + 0.6;- turned.pos = crate::anchor_for_pointer(100.0, 100.0, turned.heading);- assert_eq!(- paint(&turned, None),- upright,- "heading does not turn the art"- );-- turned.options_override = Some(CursorOptions {- rotate: true,+ let options = |rotate| CursorOptions {+ rotate,..CursorOptions::NONE- });- assert_ne!(paint(&turned, None), upright, "cursor.rotate turns it");+ };+ let mut upright = core(options(RotateMode::Off));+ move_to(&mut upright, 200.0, 190.0);+ let mut lean = core(options(RotateMode::Lean));+ move_to(&mut lean, 200.0, 190.0);+ let mut heading = core(options(RotateMode::Heading));+ move_to(&mut heading, 200.0, 190.0);+ for cursor in [&mut upright, &mut lean, &mut heading] {+ let t = cursor.trajectory.as_ref().unwrap().arrival_t * 0.5;+ cursor.tick_motion(t);+ }+ assert_eq!(upright.painted_rotation(), 0.0);+ assert!(lean.painted_rotation().abs() > 0.1);+ assert!(lean.painted_rotation().abs() <= crate::cursor_pose::LEAN_MAX_RADIANS);+ assert!(heading.painted_rotation().abs() > lean.painted_rotation().abs());+ // Paint the same pose with and without the turn.+ heading.pos = upright.pos;+ heading.heading = upright.heading;+ assert_ne!(+ paint(&heading, None),+ paint(&upright, None),+ "heading turns it"+ );+ // A turned planner heading at rest never turns the art.+ let mut resting = core(options(RotateMode::Heading));+ let still = paint(&resting, None);+ resting.heading = FRAC_PI_4 + 0.6;+ resting.pos = crate::anchor_for_pointer(100.0, 100.0, resting.heading);+ assert_eq!(paint(&resting, None), still);}#[test]@@ -3242,18 +3415,312 @@ mod plain_cursor_tests {let mut still = core(CursorOptions::NONE);still.motion.idle_hide_ms = 20_000.0;let before = paint(&still, None);- still.visual.elapsed_secs = 1.3;+ still.float_secs = 1.3;assert_eq!(paint(&still, None), before);assert!(!still.has_resting_motion());let mut floating = core(CursorOptions::default());floating.motion.idle_hide_ms = 20_000.0;let before = paint(&floating, None);- floating.visual.elapsed_secs = 1.3;+ floating.float_secs = 1.3;assert_ne!(paint(&floating, None), before);assert!(floating.has_resting_motion());}+ #[test]+ fn a_new_action_keeps_the_phase_and_settles_the_float_upright() {+ use crate::cursor_pose::{+ float_at, FLOAT_EASE_IN_SECS, FLOAT_EASE_OUT_SECS, FLOAT_HOLD_SECS,+ };+ for action in [CursorAction::Scroll, CursorAction::Text, CursorAction::Key] {+ let mut cursor = core(CursorOptions::default());+ cursor.tick_motion(1.3);+ let before = cursor.float_offset();+ assert!(before.dy < -1.0 && before.dx.abs() > 1.0, "{before:?}");+ let phase = cursor.float_secs;+ cursor.apply_command_base(+ OverlayCommand::BeginAction {+ action,+ delivery: None,+ target: None,+ },+ false,+ false,+ );+ let label = action.as_str();+ assert_eq!(cursor.float_secs, phase, "{label}: the phase runs on");+ assert_eq!(cursor.float_offset(), before, "{label}: no jump");+ cursor.tick_motion(FLOAT_EASE_OUT_SECS);+ assert_eq!(cursor.float_offset(), FloatOffset::ZERO, "{label}: settled");+ assert_eq!(cursor.painted_rotation(), 0.0, "{label}: upright");+ cursor.tick_motion(FLOAT_HOLD_SECS + FLOAT_EASE_IN_SECS);+ assert_eq!(+ cursor.float_offset(),+ float_at(cursor.float_secs),+ "{label}: eases back in on the same clock"+ );+ assert!((cursor.float_secs - (phase + 1.5)).abs() < 1e-9);+ }+ }++ fn move_to(cursor: &mut RenderStateCore, x: f64, y: f64) {+ cursor.apply_command_base(+ OverlayCommand::MoveTo {+ x,+ y,+ end_heading_radians: FRAC_PI_4,+ target: None,+ },+ true,+ true,+ );+ }++ /// Play the current move at 120 Hz to its arrival, where the driver+ /// performs the click, press or drop. Returns the float and rotation on+ /// the arrival tick, plus the peak lift and peak rotation. The float+ /// phase runs on at exactly the tick rate throughout.+ fn play(cursor: &mut RenderStateCore) -> (FloatOffset, f64, f64, f64) {+ let mut at_arrival = None;+ let (mut peak_lift, mut peak_turn) = (0.0f64, 0.0f64);+ let mut last = (cursor.float_offset(), cursor.float_secs);+ while cursor.trajectory.is_some() {+ let arrived = cursor.tick_motion(1.0 / 120.0);+ let float = cursor.float_offset();+ peak_lift = peak_lift.min(float.dy);+ peak_turn = peak_turn.max(cursor.painted_rotation().abs());+ assert!(+ (float.dx - last.0.dx).abs() < 0.2 && (float.dy - last.0.dy).abs() < 0.2,+ "the float jumped: {:?} -> {float:?}",+ last.0+ );+ assert!(+ (cursor.float_secs - last.1 - 1.0 / 120.0).abs() < 1e-9,+ "phase reset"+ );+ last = (float, cursor.float_secs);+ if arrived {+ at_arrival = Some((float, cursor.painted_rotation()));+ break;+ }+ }+ let (float, rot) = at_arrival.expect("the move arrives");+ (float, rot, peak_lift, peak_turn)+ }++ #[test]+ fn every_motion_style_floats_while_travelling_and_settles_on_arrival() {+ for style in MotionStyle::ALL {+ for rotate in [RotateMode::Off, RotateMode::Lean, RotateMode::Heading] {+ let mut cursor = core(CursorOptions {+ rotate,+ ..CursorOptions::DEFAULT+ });+ cursor.motion.style = style;+ cursor.tick_motion(1.3); // mid resting bob+ move_to(&mut cursor, 700.0, 420.0);+ let (float, rot, lift, turn) = play(&mut cursor);+ let label = format!("{style:?} {rotate:?}");+ assert_eq!(float, FloatOffset::ZERO, "{label}: float at arrival");+ assert_eq!(rot, 0.0, "{label}: upright at arrival");+ assert!(lift < -1.5, "{label}: floats while travelling ({lift})");+ match rotate {+ RotateMode::Off => assert!(+ turn <= crate::cursor_pose::FLOAT_TILT_RADIANS + 1e-9,+ "{label}: only the float tilt ({turn})"+ ),+ RotateMode::Lean => assert!(+ turn > 0.1 && turn <= crate::cursor_pose::LEAN_MAX_RADIANS + 1e-9,+ "{label}: {turn}"+ ),+ RotateMode::Heading => assert!(turn > 0.1, "{label}: {turn}"),+ }+ // The click that follows, and a double click's second, land+ // on the hotspot: float exactly 0 and upright.+ for _ in 0..2 {+ cursor.apply_command_base(+ OverlayCommand::ClickPulse { x: 700.0, y: 420.0 },+ true,+ true,+ );+ assert_eq!(cursor.float_offset(), FloatOffset::ZERO, "{label}: click");+ assert_eq!(cursor.painted_rotation(), 0.0, "{label}: click upright");+ cursor.tick_motion(0.12);+ assert_eq!(cursor.float_offset(), FloatOffset::ZERO, "{label}: held");+ }+ // Then it eases back in on the same clock.+ cursor.tick_motion(1.4);+ assert!(cursor.float_amplitude() > 0.99, "{label}: back in");+ }+ }+ }++ #[test]+ fn drags_float_and_lean_less_and_the_drop_lands_settled() {+ let mut cursor = core(CursorOptions {+ rotate: RotateMode::Lean,+ ..CursorOptions::DEFAULT+ });+ cursor.tick_motion(1.3);+ move_to(&mut cursor, 160.0, 300.0);+ play(&mut cursor);+ // Drag start: on the hotspot.+ cursor.apply_command_base(OverlayCommand::SetPressed(true), false, false);+ assert_eq!(cursor.float_offset(), FloatOffset::ZERO, "press settled");+ move_to(&mut cursor, 600.0, 380.0);+ let (float, rot, lift, turn) = play(&mut cursor);+ assert!(+ float == FloatOffset::ZERO && rot == 0.0,+ "drop settled: {float:?} {rot}"+ );+ assert!(lift < -1.5, "floats during the drag: {lift}");+ assert!(+ turn > 0.05+ && turn+ <= crate::cursor_pose::LEAN_MAX_DRAG_RADIANS+ + crate::cursor_pose::FLOAT_TILT_RADIANS+ + 1e-9,+ "{turn}"+ );+ cursor.apply_command_base(OverlayCommand::SetPressed(false), false, false);+ assert_eq!(cursor.float_offset(), FloatOffset::ZERO, "drop settled");+ assert_eq!(cursor.painted_rotation(), 0.0);+ }++ #[test]+ fn short_hops_and_snaps_stay_upright() {+ let mut cursor = core(CursorOptions {+ rotate: RotateMode::Heading,+ ..CursorOptions::DEFAULT+ });+ move_to(&mut cursor, 125.0, 110.0);+ let (float, _, lift, turn) = play(&mut cursor);+ assert!(+ turn <= crate::cursor_pose::FLOAT_TILT_RADIANS + 1e-9,+ "no heading turn on a short hop: {turn}"+ );+ assert!(+ lift > -0.5 && float == FloatOffset::ZERO,+ "no travel float on a short hop: {lift}"+ );+ cursor.apply_command_base(+ OverlayCommand::SnapTo {+ x: 400.0,+ y: 300.0,+ heading_radians: None,+ },+ false,+ false,+ );+ assert_eq!(cursor.painted_rotation(), 0.0);+ }++ /// How much alpha the halo adds 9 pt from the body centre: the pixel+ /// painted as is, minus the same frame with `cursor.halo` off.+ fn halo_probe(cursor: &mut RenderStateCore) -> u8 {+ let alpha_at = |cursor: &RenderStateCore| {+ let mut pixmap = tiny_skia::Pixmap::new(240, 240).unwrap();+ paint_cursor(&mut pixmap, cursor, 0.0, 0.0, None, 1.0);+ let (tx, ty) = crate::pointer_for_anchor(cursor.pos.0, cursor.pos.1, cursor.heading);+ let (bx, by) = crate::cursor_pose::BODY_OFFSET_PT;+ let (x, y) = (tx + bx - 9.0, ty + by + 2.0);+ pixmap+ .pixel(x.round() as u32, y.round() as u32)+ .unwrap()+ .alpha()+ };+ let with = alpha_at(cursor);+ let saved = cursor.options_override;+ let options = cursor.options();+ cursor.options_override = Some(CursorOptions {+ halo: false,+ ..options+ });+ let without = alpha_at(cursor);+ cursor.options_override = saved;+ with.saturating_sub(without)+ }++ #[test]+ fn the_halo_shows_in_every_state_follows_drags_and_hides_with_the_cursor() {+ let mut cursor = core(CursorOptions {+ float: false,+ // The probe reads the upright body; rotation has its own tests.+ rotate: RotateMode::Off,+ ..CursorOptions::DEFAULT+ });+ let resting = halo_probe(&mut cursor);+ assert!(resting > 0, "halo at rest");+ let mut plain = core(CursorOptions::NONE);+ assert_eq!(halo_probe(&mut plain), 0, "cursor.halo off");+ plain.options_override = Some(CursorOptions {+ halo: true,+ ..CursorOptions::NONE+ });+ assert_eq!(+ halo_probe(&mut plain),+ resting,+ "the halo needs no other extra"+ );++ // Click: no ring, no grow, no pulse; the halo is unchanged.+ cursor.apply_command_base(+ OverlayCommand::ClickPulse { x: 100.0, y: 100.0 },+ true,+ true,+ );+ assert_eq!(+ halo_probe(&mut cursor),+ resting,+ "no click effect on the halo"+ );++ // Drag: pressed and moving, the halo travels with the arrow.+ cursor.apply_command_base(OverlayCommand::SetPressed(true), false, false);+ assert_eq!(+ halo_probe(&mut cursor),+ resting,+ "no press effect on the halo"+ );+ move_to(&mut cursor, 180.0, 160.0);+ cursor.tick_motion(cursor.trajectory.as_ref().unwrap().arrival_t * 0.5);+ assert!(halo_probe(&mut cursor) > 0, "halo mid-drag");+ play(&mut cursor);+ assert_eq!(halo_probe(&mut cursor), resting, "halo at the drop point");++ // Scroll and typing keep it.+ cursor.apply_command_base(+ OverlayCommand::BeginAction {+ action: CursorAction::Scroll,+ delivery: None,+ target: None,+ },+ false,+ false,+ );+ assert_eq!(halo_probe(&mut cursor), resting);++ // It fades with the idle fade and is gone when the session ends.+ cursor.idle_alpha = 0.5;+ assert!(halo_probe(&mut cursor) < resting);+ cursor.idle_alpha = 1.0;+ cursor.apply_command_base(OverlayCommand::SetEnabled(false), false, false);+ assert_eq!(halo_probe(&mut cursor), 0, "hidden with the cursor");+ // Surfaces that cannot blend get no halo.+ cursor.apply_command_base(OverlayCommand::SetEnabled(true), false, false);+ cursor.effects_capable = false;+ assert_eq!(halo_probe(&mut cursor), 0);+ }++ #[test]+ fn each_session_cursor_gets_its_own_halo_colour() {+ let colours: std::collections::HashSet<_> = ["default", "agent-1", "agent-2", "agent-3"]+ .into_iter()+ .map(|id| crate::cursor_pose::halo_rgb(None, id))+ .collect();+ assert_eq!(colours.len(), 4);+ }+#[test]fn the_focus_rect_is_a_mark() {let focus = Some(FocusRect {diff --git a/libs/cua-driver/rust/crates/cursor-overlay/src/surface_fit.rs b/libs/cua-driver/rust/crates/cursor-overlay/src/surface_fit.rsindex 04edfa1b0c..e930d38740 100644--- a/libs/cua-driver/rust/crates/cursor-overlay/src/surface_fit.rs+++ b/libs/cua-driver/rust/crates/cursor-overlay/src/surface_fit.rs@@ -179,6 +179,11 @@ mod tests {fn painted_pointer(surface: SurfaceGeometry, pointer: (f64, f64)) -> Option<(f64, f64)> {let mut core = RenderStateCore::new(CursorConfig::default());core.theme = Some(hotspot_marker_theme());+ // The halo would pull the measured centroid off the marker.+ core.options_override = Some(crate::CursorOptions {+ halo: false,+ ..crate::CursorOptions::DEFAULT+ });core.apply_command_base(track_pointer_command(pointer.0, pointer.1), false, false);let (w, h) = surface.pixel_size();let mut pixmap = tiny_skia::Pixmap::new(w, h).unwrap();diff --git a/libs/cua-driver/rust/crates/cursor-overlay/src/theme.rs b/libs/cua-driver/rust/crates/cursor-overlay/src/theme.rsindex 7637906212..99cf4dfc37 100644--- a/libs/cua-driver/rust/crates/cursor-overlay/src/theme.rs+++ b/libs/cua-driver/rust/crates/cursor-overlay/src/theme.rs@@ -2,8 +2,8 @@//!//! The default artwork is authored as a checked-in dotLottie archive and//! compiled into the bounded artifact embedded by [`crate::theme_artifact`].-//! This module owns transport-neutral state, session colors, and the shared-//! runtime float transform. It does not parse Lottie at runtime.+//! This module owns transport-neutral state and session colors. It does not+//! parse Lottie at runtime.use serde::{Deserialize, Serialize};@@ -17,7 +17,6 @@ pub const DEFAULT_THEME_VERSION: &str = "2.0.0";pub const THEME_PROFILE: &str = "cua-driver-actions-v2";pub const CANVAS_SIZE: f32 = 128.0;pub const DISPLAY_SIZE: f32 = 42.0;-const FLOAT_DURATION_SECS: f32 = 4.0;pub const DEFAULT_CURSOR_FILL: [u8; 4] = [94, 192, 232, 255];@@ -179,24 +178,6 @@ impl CursorVisualState {}}-/// Peak lift of the resting float, in theme canvas units (about 4 pt).-const FLOAT_LIFT: f32 = 12.0;--/// Vertical offset (theme canvas units, negative is up) of the resting-/// float: the arrow rises and settles back on a 4 s loop. It never moves-/// sideways or tilts, so the arrow stays upright, and it starts and ends-/// each loop on the hotspot, so a cursor that just arrived does not jump.-pub(crate) fn shared_float_motion(visual: &CursorVisualState) -> f32 {- if visual.reduced_motion == ReducedMotion::On {- return 0.0;- }-- let progress =- (visual.elapsed_secs as f32).rem_euclid(FLOAT_DURATION_SECS) / FLOAT_DURATION_SECS;- let angle = progress * std::f32::consts::TAU;- -0.5 * FLOAT_LIFT * (1.0 - angle.cos())-}-/// Paint one frame of the embedded actions-v2 theme.////// `anchor_x/y` is where the theme hotspot is drawn. `heading` and the@@ -390,55 +371,6 @@ mod tests {assert_eq!(pixmap.data(), base.data());}- #[test]- fn every_action_inherits_the_same_floating_base_motion() {- let idle = CursorVisualState {- elapsed_secs: 0.75,- ..CursorVisualState::default()- };- let expected = shared_float_motion(&idle);- assert!(expected < 0.0, "the float lifts the arrow");-- for action in CursorAction::ALL {- let mut visual = CursorVisualState::default();- visual.begin(action, None, None);- visual.elapsed_secs = 0.75;- assert_eq!(- shared_float_motion(&visual),- expected,- "{} did not inherit the shared floating motion",- action.as_str()- );- }- }-- #[test]- fn the_float_is_a_vertical_lift_that_returns_to_the_hotspot() {- let at = |elapsed_secs| {- shared_float_motion(&CursorVisualState {- elapsed_secs,- ..CursorVisualState::default()- })- };- assert_eq!(at(0.0), 0.0);- assert!((at(f64::from(FLOAT_DURATION_SECS) / 2.0) + FLOAT_LIFT).abs() < 1e-4);- assert!(at(f64::from(FLOAT_DURATION_SECS)).abs() < 1e-4);- for step in 0..40 {- let dy = at(f64::from(step) * 0.1);- assert!((-FLOAT_LIFT - 1e-4..=1e-4).contains(&dy), "{dy}");- }- }-- #[test]- fn reduced_motion_disables_shared_floating_motion() {- let visual = CursorVisualState {- elapsed_secs: 0.75,- reduced_motion: ReducedMotion::On,- ..CursorVisualState::default()- };- assert_eq!(shared_float_motion(&visual), 0.0);- }-#[test]fn one_shot_returns_to_idle() {let mut state = CursorVisualState::default();diff --git a/libs/cua-driver/rust/crates/cursor-overlay/src/theme_artifact.rs b/libs/cua-driver/rust/crates/cursor-overlay/src/theme_artifact.rsindex ce0102c4fe..ad1d5ca4df 100644--- a/libs/cua-driver/rust/crates/cursor-overlay/src/theme_artifact.rs+++ b/libs/cua-driver/rust/crates/cursor-overlay/src/theme_artifact.rs@@ -651,6 +651,36 @@ fn resolved_color(mut color: [u8; 4], tint: Option<[u8; 4]>) -> [u8; 4] {color}+/// The theme's accent: the most colourful fill or stroke of its idle frame,+/// with `tint` applied like the artwork. `None` for a theme drawn only in+/// greys.+pub(crate) fn theme_accent_rgba(theme: &CompiledTheme, tint: Option<[u8; 4]>) -> Option<[u8; 4]> {+ let animation = theme.animation_for_action(CursorAction::Idle)?;+ let frame = animation+ .frames+ .get(usize::from(animation.still_frame))+ .or_else(|| animation.frames.first())?;+ frame+ .commands+ .iter()+ .flat_map(|command| {+ command+ .fill+ .into_iter()+ .chain(command.stroke.map(|s| s.color))+ })+ .filter(|color| color[3] > 0)+ .map(|color| resolved_color(color, tint))+ .map(|color| {+ let max = color[..3].iter().max().copied().unwrap_or(0);+ let min = color[..3].iter().min().copied().unwrap_or(0);+ (max - min, color)+ })+ .filter(|(chroma, _)| *chroma >= 24)+ .max_by_key(|(chroma, _)| *chroma)+ .map(|(_, color)| color)+}+fn vector_paint(color: [u8; 4], opacity: f32, tint: Option<[u8; 4]>) -> Paint<'static> {let color = resolved_color(color, tint);let alpha = (f32::from(color[3]) / 255.0 * opacity.clamp(0.0, 1.0)).clamp(0.0, 1.0);@@ -790,13 +820,14 @@ pub fn paint_compiled_theme_with_tint(backing_scale,alpha,tint,- false,+ 0.0,+ 0.0,);}-/// [`paint_compiled_theme_with_tint`] with the resting float-/// (`cursor.float`, on by default) of the built-in theme: a vertical bob-/// that never tilts the arrow. Custom themes never float.+/// [`paint_compiled_theme_with_tint`] moved by the float of the agent+/// cursor (`cursor.float`): `float_dx`, `float_dy` points (negative is up).+/// The float tilt is part of `heading`. See [`crate::cursor_pose`].#[allow(clippy::too_many_arguments)]pub fn paint_compiled_theme_with_float(target: &mut tiny_skia::Pixmap,@@ -808,19 +839,18 @@ pub fn paint_compiled_theme_with_float(backing_scale: f32,alpha: f32,tint: Option<[u8; 4]>,- float: bool,+ float_dx: f32,+ float_dy: f32,) {let scale = crate::theme::DISPLAY_SIZE * backing_scale / crate::theme::CANVAS_SIZE;- let float_dy = if float && theme.id == crate::DEFAULT_THEME_ID {- crate::theme::shared_float_motion(visual)- } else {- 0.0- };let transform =Transform::from_translate(-f32::from(theme.hotspot[0]), -f32::from(theme.hotspot[1])).post_scale(scale, scale).post_rotate((heading - std::f32::consts::FRAC_PI_4).to_degrees())- .post_translate(anchor_x, anchor_y + float_dy * scale);+ .post_translate(+ anchor_x + float_dx * backing_scale,+ anchor_y + float_dy * backing_scale,+ );let reduced = visual.reduced_motion == crate::ReducedMotion::On;if let Some(animation) = theme.animation_for_action(visual.resolved_action) {draw_layer(diff --git a/libs/cua-driver/rust/crates/platform-linux/src/overlay.rs b/libs/cua-driver/rust/crates/platform-linux/src/overlay.rsindex 91a6c8eb40..7debfaab00 100644--- a/libs/cua-driver/rust/crates/platform-linux/src/overlay.rs+++ b/libs/cua-driver/rust/crates/platform-linux/src/overlay.rs@@ -433,8 +433,7 @@ fn try_send_command_for(key: CursorKey, cmd: OverlayCommand) -> bool {);}#[cfg(target_os = "linux")]- let layer_shell_queued = native_wayland- && dispatch_wayland_overlay_message(&msg) == WaylandOverlayBackend::LayerShell;+ let layer_shell_queued = native_wayland && dispatch_wayland_overlay_message(&msg);#[cfg(not(target_os = "linux"))]let layer_shell_queued = false;x11_queued || layer_shell_queued@@ -532,37 +531,165 @@ fn start_shell_helper_idle_watch() {});}+/// Per-session poses for the GNOME Shell helper cursor (helper API 11). The+/// helper draws its own cursor, so the shared planner, float, rotation and+/// halo reach it as pose tracks instead of painted frames.#[cfg(target_os = "linux")]-fn dispatch_wayland_overlay_message(msg: &OverlayMsg) -> WaylandOverlayBackend {+struct ShellHelperPoses {+ model: cursor_overlay::pose_stream::PoseModel,+ /// The look last sent, so it is sent again only when it changes.+ look_sent: Option<String>,+}++#[cfg(target_os = "linux")]+static SHELL_HELPER_POSES: Mutex<Option<ShellHelperPoses>> = Mutex::new(None);++/// Whether the helper plays pose tracks. Checked once, like the backend.+#[cfg(target_os = "linux")]+fn shell_helper_plays_poses() -> bool {+ static POSES: OnceLock<bool> = OnceLock::new();+ *POSES.get_or_init(crate::wayland::shell_helper::pose_cursor_available)+}++/// What one command sends the pose-playing helper, besides the command.+#[cfg(target_os = "linux")]+#[derive(Debug, Default, PartialEq)]+struct ShellHelperPoseUpdate {+ /// The look JSON, when it changed.+ look: Option<String>,+ /// The track JSON of a move or snap.+ track: Option<String>,+ /// For a move: when its hotspot arrives, and which move it is.+ arrival: Option<(Duration, u64)>,+}++/// Feed one message to the helper's pose model. `draws` says whether it+/// reaches the helper (from [`shell_helper_surface_event`]).+#[cfg(target_os = "linux")]+fn shell_helper_pose_update(+ poses: &mut ShellHelperPoses,+ msg: &OverlayMsg,+ draws: bool,+ now: Instant,+) -> ShellHelperPoseUpdate {+ let track = poses.model.apply(msg, draws, now);+ let mut update = ShellHelperPoseUpdate::default();+ let OverlayMsg::Cmd(command) = msg else {+ if draws {+ // The helper hides; send the look again with the next draw.+ poses.look_sent = None;+ }+ return update;+ };+ if !draws {+ return update;+ }+ if let Some(look) = poses.model.look(&command.key).map(|look| look.to_json()) {+ if poses.look_sent.as_deref() != Some(look.as_str()) {+ poses.look_sent = Some(look.clone());+ update.look = Some(look);+ }+ }+ if let Some(track) = track {+ if matches!(command.cmd, OverlayCommand::MoveTo { .. }) {+ if let Some(seq) = poses.model.move_seq(&command.key) {+ update.arrival = Some((Duration::from_secs_f64(track.arrival_secs()), seq));+ }+ }+ update.track = Some(track.to_json());+ }+ update+}++/// Release `key`'s arrival waiter once the helper's hotspot has arrived,+/// unless a later move replaced this one. Returns whether it is scheduled.+#[cfg(target_os = "linux")]+fn schedule_shell_helper_arrival(key: CursorKey, wait: Duration, seq: u64) -> bool {+ std::thread::Builder::new()+ .name("cua-shell-cursor-arrival".into())+ .spawn(move || {+ std::thread::sleep(wait);+ let current = SHELL_HELPER_POSES+ .lock()+ .ok()+ .and_then(|guard| guard.as_ref().and_then(|p| p.model.move_seq(&key)));+ if current == Some(seq) {+ arrival_fire(&key);+ }+ })+ .is_ok()+}++/// Dispatch one message to the Wayland backend. Returns whether a renderer+/// will fire this command's arrival: the native layer-shell overlay, or the+/// pose-playing shell helper for a move.+#[cfg(target_os = "linux")]+fn dispatch_wayland_overlay_message(msg: &OverlayMsg) -> bool {let backend = wayland_overlay_backend();match backend {WaylandOverlayBackend::SemanticShellHelper | WaylandOverlayBackend::LegacyShellHelper => {let semantic = backend == WaylandOverlayBackend::SemanticShellHelper;- if shell_helper_surface_event(msg, Instant::now()) {- if let OverlayMsg::Cmd(command) = msg {- dispatch_shell_helper_command(&command.key, &command.cmd, semantic);- } else {- crate::wayland::shell_helper::hide_cursor();- }+ let now = Instant::now();+ let reach = shell_helper_surface_event(msg, now);+ let poses = (semantic && shell_helper_plays_poses()).then(|| {+ // Read the launch template before taking the pose lock.+ let uninitialised = SHELL_HELPER_POSES.lock().unwrap().is_none();+ let template = uninitialised+ .then(|| read_render(|map| map.template.clone()))+ .flatten();+ let mut guard = SHELL_HELPER_POSES.lock().unwrap();+ let poses = guard.get_or_insert_with(|| ShellHelperPoses {+ model: cursor_overlay::pose_stream::PoseModel::new(+ template.unwrap_or_default(),+ ),+ look_sent: None,+ });+ shell_helper_pose_update(poses, msg, reach, now)+ });+ if !reach {+ return false;}+ let OverlayMsg::Cmd(command) = msg else {+ crate::wayland::shell_helper::hide_cursor();+ return false;+ };+ dispatch_shell_helper_command(&command.key, &command.cmd, semantic, poses.as_ref());+ poses+ .and_then(|update| update.arrival)+ .is_some_and(|(wait, seq)| {+ schedule_shell_helper_arrival(command.key.clone(), wait, seq)+ })}- WaylandOverlayBackend::LayerShell if !crate::wayland::overlay::forward(msg) => {- return WaylandOverlayBackend::None;- }- WaylandOverlayBackend::LayerShell | WaylandOverlayBackend::None => {}+ WaylandOverlayBackend::LayerShell => crate::wayland::overlay::forward(msg),+ WaylandOverlayBackend::None => false,}- backend}#[cfg(target_os = "linux")]-fn dispatch_shell_helper_command(key: &str, cmd: &OverlayCommand, semantic: bool) {+fn dispatch_shell_helper_command(+ key: &str,+ cmd: &OverlayCommand,+ semantic: bool,+ poses: Option<&ShellHelperPoseUpdate>,+) {if semantic {crate::wayland::shell_helper::set_cursor_color(&cursor_overlay::session_fill_hex(key));}+ if let Some(look) = poses.and_then(|update| update.look.as_deref()) {+ crate::wayland::shell_helper::set_cursor_look(look);+ }match cmd {OverlayCommand::ClickPulse { x, y } if semantic => {crate::wayland::shell_helper::click_pulse(*x as i32, *y as i32);}+ // The pose-playing helper follows the planned path itself.+ OverlayCommand::MoveTo { .. } | OverlayCommand::SnapTo { .. }+ if poses.is_some_and(|update| update.track.is_some()) =>+ {+ if let Some(track) = poses.and_then(|update| update.track.as_deref()) {+ crate::wayland::shell_helper::play_cursor_path(track);+ }+ }OverlayCommand::MoveTo { x, y, .. }| OverlayCommand::SnapTo { x, y, .. }| OverlayCommand::ClickPulse { x, y } => {@@ -5781,4 +5908,80 @@ mod shell_helper_surface_tests {));assert!(shell_helper_surface_event(&cmd(b), now));}++ fn keyed(key: &str, cmd: OverlayCommand) -> OverlayMsg {+ OverlayMsg::Cmd(KeyedOverlayCommand {+ key: key.to_owned(),+ cmd,+ })+ }++ fn poses() -> ShellHelperPoses {+ ShellHelperPoses {+ model: cursor_overlay::pose_stream::PoseModel::new(CursorConfig::default()),+ look_sent: None,+ }+ }++ fn move_to(x: f64, y: f64) -> OverlayCommand {+ OverlayCommand::MoveTo {+ x,+ y,+ end_heading_radians: std::f64::consts::FRAC_PI_4,+ target: None,+ }+ }++ /// The helper gets the shared planner's path for a move, with the+ /// arrival that releases the waiting action, and a one-pose track for+ /// a snap. Only commands that reach it send anything.+ #[test]+ fn moves_and_snaps_reach_the_helper_as_pose_tracks() {+ let now = Instant::now();+ let mut poses = poses();+ let snap = shell_helper_pose_update(&mut poses, &cmd("a"), true, now);+ let track: serde_json::Value =+ serde_json::from_str(snap.track.as_deref().unwrap()).unwrap();+ assert_eq!(track["samples"].as_array().unwrap().len(), 1);+ assert!(track["arrival"].is_null());+ assert_eq!(track["rest"].as_array().unwrap().len(), 3);+ assert_eq!(snap.arrival, None, "a snap has no glide to wait for");++ let glide =+ shell_helper_pose_update(&mut poses, &keyed("a", move_to(600.0, 400.0)), true, now);+ let track: serde_json::Value =+ serde_json::from_str(glide.track.as_deref().unwrap()).unwrap();+ let samples = track["samples"].as_array().unwrap();+ assert!(samples.len() > 10, "the planned path, not one jump");+ let last = samples.last().unwrap().as_array().unwrap();+ assert!((last[1].as_f64().unwrap() - 600.0).abs() < 1.0);+ assert!((last[2].as_f64().unwrap() - 400.0).abs() < 1.0);+ let (wait, seq) = glide.arrival.unwrap();+ assert!(wait > Duration::ZERO);+ assert_eq!(poses.model.move_seq(&"a".to_owned()), Some(seq));++ let elsewhere =+ shell_helper_pose_update(&mut poses, &keyed("b", move_to(9.0, 9.0)), false, now);+ assert_eq!(elsewhere, ShellHelperPoseUpdate::default());+ }++ /// The look (resting float, halo colour) is sent once, again when it+ /// changes (another session's colour), and again after the helper hid.+ #[test]+ fn the_helper_look_is_sent_only_when_it_changes() {+ let now = Instant::now();+ let mut poses = poses();+ let first = shell_helper_pose_update(&mut poses, &cmd("a"), true, now);+ assert!(first.look.is_some());+ assert_eq!(+ shell_helper_pose_update(&mut poses, &cmd("a"), true, now).look,+ None+ );+ let other = shell_helper_pose_update(&mut poses, &cmd("b"), true, now);+ assert!(other.look.is_some() && other.look != first.look);+ shell_helper_pose_update(&mut poses, &OverlayMsg::Remove("b".to_owned()), true, now);+ assert!(shell_helper_pose_update(&mut poses, &cmd("a"), true, now)+ .look+ .is_some());+ }}diff --git a/libs/cua-driver/rust/crates/platform-linux/src/tools/set_config.rs b/libs/cua-driver/rust/crates/platform-linux/src/tools/set_config.rsindex 27103b56dd..fc194683c0 100644--- a/libs/cua-driver/rust/crates/platform-linux/src/tools/set_config.rs+++ b/libs/cua-driver/rust/crates/platform-linux/src/tools/set_config.rs@@ -40,9 +40,10 @@ impl Tool for SetConfigTool {`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.\n\n\- `cursor.float` (resting float) is `on` (default), `off` or `default`; \- `cursor.marks` (action marks) and `cursor.rotate` (turn toward travel) are `on`, \- `off` (default) or `default`. All apply to every cursor at once.".into(),+ `cursor.float` (float at rest and while moving) and `cursor.halo` (soft glow) are \+ `on` (default), `off` or `default`; `cursor.marks` (action marks) is `on`, \+ `off` (default) or `default`; `cursor.rotate` is `heading` (default), `lean`, \+ `off` or `default`. All apply to 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)."},diff --git a/libs/cua-driver/rust/crates/platform-linux/src/wayland/shell_helper.rs b/libs/cua-driver/rust/crates/platform-linux/src/wayland/shell_helper.rsindex 0ce650af71..349521b175 100644--- a/libs/cua-driver/rust/crates/platform-linux/src/wayland/shell_helper.rs+++ b/libs/cua-driver/rust/crates/platform-linux/src/wayland/shell_helper.rs@@ -15,6 +15,9 @@//! cursor as a Clutter actor on the compositor stage.//! - `SetCursorState(...)` / `SetCursorColor(...)` — keep the compositor cursor//! aligned with the shared semantic theme and active session identity.+//! - `PlayCursorPath(json)` / `SetCursorLook(json)` (API 11) — play the shared+//! planner's poses (path, float, rotation) and paint the shared halo+//! (`cursor_overlay::pose_stream`).//! - `CaptureWindow(id,pid)` (API 9) / `CaptureWindowPreview(id,pid,max)`//! (API 10) — snapshot one window's own actor, so a covering window never//! shows; the preview variant downscales on the GPU first.@@ -48,6 +51,9 @@ const SEMANTIC_CURSOR_API_VERSION: u32 = 8;pub const WINDOW_CAPTURE_API_VERSION: u32 = 9;/// `CaptureWindowPreview(id, pid, max_dimension)`: GPU-downscaled capture.pub const WINDOW_PREVIEW_API_VERSION: u32 = 10;+/// `SetCursorLook(json)` / `PlayCursorPath(json)`: the helper plays the+/// shared planner's poses (float, rotation) and paints the shared halo.+pub const POSE_CURSOR_API_VERSION: u32 = 11;#[derive(Debug, Clone)]struct ShellWindow {@@ -75,6 +81,12 @@ pub fn gnome_shell_session() -> bool {.is_some()}+/// Whether the helper plays pose tracks ([`POSE_CURSOR_API_VERSION`]).+pub fn pose_cursor_available() -> bool {+ shell_owner_with_min_version(Some(POSE_CURSOR_API_VERSION), operation_deadline(CALL_CAP))+ .is_some()+}+pub fn semantic_cursor_available() -> bool {shell_owner_with_min_version(Some(SEMANTIC_CURSOR_API_VERSION),@@ -706,6 +718,26 @@ pub fn set_cursor_state(action: &str, delivery: &str, target: &str, active: bool);}+/// Set the resting float and halo the compositor cursor paints+/// ([`cursor_overlay::pose_stream::PoseLook::to_json`]). Helper API 11.+pub fn set_cursor_look(look_json: &str) {+ let _ = gdbus_call(+ "SetCursorLook",+ &[look_json.to_owned()],+ operation_deadline(CALL_CAP),+ );+}++/// Play a planned move on the compositor cursor+/// ([`cursor_overlay::pose_stream::PoseTrack::to_json`]). Helper API 11.+pub fn play_cursor_path(track_json: &str) {+ let _ = gdbus_call(+ "PlayCursorPath",+ &[track_json.to_owned()],+ operation_deadline(CALL_CAP),+ );+}+/// Set the renderer-visible public session label for the compositor cursor.pub fn set_session_label(label: &str) {let _ = gdbus_call(@@ -1114,7 +1146,11 @@ mod tests {#[test]fn bundled_helper_uses_host_owned_modifier_badge_chips() {assert!(EXTENSION_SOURCE.contains("GetVersion()"));- assert!(EXTENSION_SOURCE.contains("return 10;"));+ assert!(EXTENSION_SOURCE.contains("return 11;"));+ assert!(EXTENSION_SOURCE.contains("PlayCursorPath(trackJson)"));+ assert!(EXTENSION_SOURCE.contains("SetCursorLook(lookJson)"));+ assert!(EXTENSION_SOURCE.contains("function drawCursorHalo"));+ assert_eq!(POSE_CURSOR_API_VERSION, 11);assert!(EXTENSION_SOURCE.contains("SetCursorState"));assert!(EXTENSION_SOURCE.contains("SetCursorColor"));assert!(EXTENSION_SOURCE.contains("SetSessionLabel"));@@ -1139,7 +1175,7 @@ mod tests {assert!(!EXTENSION_SOURCE.contains("function drawModifiers"));let metadata: serde_json::Value =serde_json::from_str(EXTENSION_METADATA).expect("valid bundled helper metadata");- assert_eq!(metadata["version"], 10);+ assert_eq!(metadata["version"], 11);for action in ["idle", "observe", "click", "drag", "scroll", "text", "key", "navigate", "app",diff --git a/libs/cua-driver/rust/crates/platform-linux/src/wayland/shell_helper/transport.rs b/libs/cua-driver/rust/crates/platform-linux/src/wayland/shell_helper/transport.rsindex b4d6af5c7c..4b3e025755 100644--- a/libs/cua-driver/rust/crates/platform-linux/src/wayland/shell_helper/transport.rs+++ b/libs/cua-driver/rust/crates/platform-linux/src/wayland/shell_helper/transport.rs@@ -107,6 +107,8 @@ async fn invoke(| "GetConnectionUnixProcessID"| "GetConnectionUnixUser"| "SetCursorColor"+ | "SetCursorLook"+ | "PlayCursorPath"| "SetSessionLabel",[value],) => send!((value.as_str(),)),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 61334dc939..0db91885ae 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@@ -47,9 +47,10 @@ fn def() -> &'static ToolDef {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.\n\nAgent cursor extras: \- cursor.float (resting float) is on (default), off or default; \- cursor.marks (action marks) and cursor.rotate (turn toward travel) \- are on, off (default) or default. All are saved to \+ cursor.float (float at rest and while moving) and cursor.halo (soft \+ glow) are on (default), off or default; cursor.marks (action marks) \+ is on, off (default) or default; cursor.rotate is heading (default), \+ lean, off or default. All are saved to \~/.cua-driver/config.json and applied to every cursor at once.".into(),input_schema: with_cursor_motion_properties(serde_json::json!({diff --git a/libs/cua-driver/rust/crates/platform-windows/src/tools/set_config.rs b/libs/cua-driver/rust/crates/platform-windows/src/tools/set_config.rsindex 78b0864df4..680e8bf450 100644--- a/libs/cua-driver/rust/crates/platform-windows/src/tools/set_config.rs+++ b/libs/cua-driver/rust/crates/platform-windows/src/tools/set_config.rs@@ -40,7 +40,7 @@ impl Tool for SetConfigTool {- `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\- - `cursor.float` (resting float): `on` (default), `off`, or `default`. `cursor.marks` (action marks), `cursor.rotate` (turn toward travel): `on`, `off` (default), or `default`. All apply to every cursor at once.\n\n\+ - `cursor.float` (float at rest and while moving), `cursor.halo` (soft glow): `on` (default), `off`, or `default`. `cursor.marks` (action marks): `on`, `off` (default), or `default`. `cursor.rotate`: `heading` (default), `lean`, `off`, or `default`. All apply 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.)"},diff --git a/libs/cua-driver/scripts/tests/test_wayland_helper_safety.mjs b/libs/cua-driver/scripts/tests/test_wayland_helper_safety.mjsindex 14812550a7..89f8ac639d 100644--- a/libs/cua-driver/scripts/tests/test_wayland_helper_safety.mjs+++ b/libs/cua-driver/scripts/tests/test_wayland_helper_safety.mjs@@ -21,7 +21,7 @@ globalThis.helperMocks = {bus_own_name: () => bump('own'), bus_unown_name: () => bump('unown'),},GLib: {- get_monotonic_time: () => 0,+ get_monotonic_time: () => (globalThis.helperClock ?? 0) * 1_000_000,timeout_add: () => bump('timer'), source_remove: () => bump('remove'),},Shell: { Screenshot: class {} },@@ -69,7 +69,7 @@ for (const version of ['50', '50.1', '50.beta', '50.rc', '51', '45', '46', '47',assert.deepEqual(counts, {});} else {helper.enable();- assert.equal(helper.GetVersion(), 10);+ assert.equal(helper.GetVersion(), 11);assert.equal(counts.export, 1);assert.equal(counts.own, 1);assert.equal(counts.actor, 5);@@ -82,3 +82,122 @@ for (const version of ['50', '50.1', '50.beta', '50.rc', '51', '45', '46', '47',}const metadata = JSON.parse(await readFile(new URL('metadata.json', extension)));assert.deepEqual(metadata['shell-version'], ['45', '46', '47', '48', '49']);++// API 11: the helper plays cua-driver's planned poses and paints its halo.+{+ globalThis.shellVersion = '49';+ globalThis.helperClock = 100;+ const { default: Extension } = await import(`${extension}?poses`);+ const helper = new Extension();+ helper.enable();+ for (const key of Object.keys(counts)) delete counts[key];+ const near = (actual, expected) => assert.ok(Math.abs(actual - expected) < 1e-9, `${actual} != ${expected}`);++ // Until a look arrives the older glow stays; a bad look is ignored.+ assert.equal(helper._look, null);+ helper.SetCursorLook('not json');+ const float = { secs: 4, sway: 1.6406, bob: 1.9688, lift: 1.6406, tilt: 0.04363, hold: 0.5, ease_in: 0.8, ease_out: 0.2 };+ helper.SetCursorLook(JSON.stringify({ float: { ...float, sway: -1 }, halo: null }));+ helper.SetCursorLook(JSON.stringify({ float: { ...float, ease_out: 0 }, halo: null }));+ assert.equal(helper._look, null);+ const look = {+ float,+ halo: { rgb: '#5ec0e8', radius: 14, peak: 0.11, stops: [[0, 1], [0.45, 0.55], [1, 0]], body: [2, 11.9] },+ };+ helper.SetCursorLook(JSON.stringify(look));+ assert.deepEqual(helper._look.halo.rgb, [0x5e, 0xc0, 0xe8]);+ helper.SetCursorLook(JSON.stringify({ ...look, halo: null }));+ assert.equal(helper._look.halo, null, 'cursor.halo off');+ helper.SetCursorLook(JSON.stringify(look));++ // Before any track a fresh cursor floats fully: the historical loop.+ near(helper._pose(100).dy, float.bob - float.lift);+ near(helper._pose(100).rotation, float.tilt);+ near(helper._pose(101).dx, float.sway);+ near(helper._pose(102).dy, -float.bob - float.lift);++ // A move: poses interpolate, and the float is exactly 0 at the arrival.+ const samples = [+ [0, 100, 100, 0.5, -1, 0],+ [0.2, 300, 200, 1, -2.2, 0.4],+ [0.4, 500, 300, 0, 0, 0],+ [0.5, 501, 300, 0, 0, 0],+ ];+ // The float clock at the last sample: phase 7.3 s, held 0.1 s from 0.+ const rest = [7.3, 0.1, 0];+ helper.PlayCursorPath(JSON.stringify({ samples, arrival: 0.4, rest }));+ assert.equal(counts.timer, 1, 'one frame timer while the path plays');+ assert.ok(helper._path);+ near(helper._pose(100).dy, -1);+ near(helper._pose(100.1).dx, 0.75);+ near(helper._pose(100.1).dy, -1.6);+ near(helper._pose(100.1).rotation, 0.2);+ near(helper._pose(100.4).dy, 0);+ near(helper._pose(100.4).dx, 0);+ near(helper._pose(100.4).rotation, 0);+ near(helper._rest.at, 100.5);++ // Malformed tracks change nothing.+ for (const bad of [+ '{}',+ JSON.stringify({ samples: [], rest }),+ JSON.stringify({ samples: [[0, 1, 2, 3, 4]], rest }),+ JSON.stringify({ samples: [[0, 0, 0, 0, 0]], rest }),+ JSON.stringify({ samples: [[0.2, 0, 0, 0, 0, 0], [0.1, 0, 0, 0, 0, 0]], rest }),+ JSON.stringify({ samples: [[0, Infinity, 0, 0, 0, 0]], rest }),+ JSON.stringify({ samples: [[0, 0, 0, 0, 0, 0]], arrival: -1, rest }),+ JSON.stringify({ samples: [[0, 0, 0, 0, 0, 0]], arrival: null }),+ JSON.stringify({ samples: [[0, 0, 0, 0, 0, 0]], arrival: null, rest: [0, -1, 0] }),+ ])+ helper.PlayCursorPath(bad);+ assert.deepEqual(helper._path.samples, samples);++ // A click on the point the move settles onto lets it finish.+ helper.ClickPulse(501, 300);+ assert.ok(helper._path, 'settling move kept');+ near(helper._rest.phase, 7.3);+ // A click elsewhere ends it and snaps.+ helper.ClickPulse(800, 600);+ assert.equal(helper._path, null);+ assert.equal(helper._cursorX, 800);+ assert.equal(counts.remove, 1);++ // At rest the float carries on from the track's clock: still held at 0+ // just after, then eased back in on the same phase (no restart).+ helper.PlayCursorPath(JSON.stringify({ samples: [[0, 800, 600, 0, 0, 0]], arrival: null, rest }));+ near(helper._rest.at, 100);+ assert.equal(helper._pose(100.3).dx, 0);+ assert.equal(helper._pose(100.3).rotation, 0);+ // 2 s on: phase 9.3 s (0.325 of a loop), amplitude 1.+ const angle = (9.3 % 4) / 4 * 2 * Math.PI;+ near(helper._pose(102).dx, float.sway * Math.sin(angle));+ near(helper._pose(102).dy, float.bob * Math.cos(angle) - float.lift);+ near(helper._pose(102).rotation, float.tilt * Math.cos(angle));++ // A cue at rest (typing, scroll) eases it out from where it is, keeps+ // the phase and holds it at exactly 0.+ globalThis.helperClock = 102;+ const before = helper._pose(102);+ helper.SetCursorState('text', '', '', true);+ near(helper._rest.phase, 9.3);+ near(helper._pose(102).dy, before.dy);+ assert.equal(helper._pose(102.25).dy, 0);+ assert.equal(helper._pose(102.25).rotation, 0);+ assert.ok(Math.abs(helper._pose(104).dy) > 0.1, 'back in after the hold');+ // And a click at rest holds it at 0 too.+ globalThis.helperClock = 104;+ helper.ClickPulse(800, 600);+ globalThis.helperClock = 104.3;+ assert.equal(helper._pose(104.3).dx, 0);++ // Float off: the look carries no float.+ helper.SetCursorLook(JSON.stringify({ ...look, float: null }));+ assert.equal(helper._pose(106.4).dy, 0);+ assert.equal(helper._pose(106.4).rotation, 0);++ helper.PlayCursorPath(JSON.stringify({ samples, arrival: 0.4, rest }));+ helper.HideCursor();+ assert.equal(helper._path, null, 'hiding stops the path');+ helper.disable();+ delete globalThis.helperClock;+}diff --git a/libs/cua-driver/wayland-helper/README.md b/libs/cua-driver/wayland-helper/README.mdindex e5ba5d76d8..bb77339b64 100644--- a/libs/cua-driver/wayland-helper/README.md+++ b/libs/cua-driver/wayland-helper/README.md@@ -31,6 +31,20 @@ It exposes `org.cua.WinRects` on the session bus:- `SetCursorColor(fill_color)`: apply the stable per-session fill selected bycua-driver. The helper validates the `#RRGGBB` value, updates the matchingglow, and keeps a white pointer outline.+- `PlayCursorPath(track_json)` (API 11): play one planned move as poses+ (`[t, x, y, float_dx, float_dy, rotation]` samples, the arrival time and+ the float clock `[phase, hold, from]` at the last sample) from cua-driver's+ shared motion planner, so the cursor follows the same path, float and+ `cursor.rotate` turn as on every other desktop. The helper interpolates the+ samples, then carries the float on at rest from that clock, so its phase+ never restarts. It plans nothing itself. A single sample is a snap. A click+ or an action cue at rest eases the float out and holds it at 0.+- `SetCursorLook(look_json)` (API 11): the float (loop length, sway, bob,+ lift, tilt and the rest envelope; `null` for `cursor.float off`) and the+ `cursor.halo` glow (colour,+ radius, peak opacity, gradient stops, body offset). Until a driver sends a+ look, the helper keeps its older glow. Both methods validate every field+ and ignore malformed input.- `CaptureWindow(id,pid) -> png_base64` (API 9): snapshot one window's owncompositor actor (`paint_to_content`), not the stage, so a covering windownever shows and the target is not activated. `pid` 0 skips the owner check.@@ -58,7 +72,7 @@ Existing v8/v10 users on GNOME 50 must run`gnome-extensions disable winrects@cua` before further diagnostics and keepit disabled. Replacing files does not unload an already-active extension.-API 10 is retained because the method set is unchanged. T3 Code's v10 does+API 11 adds `PlayCursorPath` and `SetCursorLook` and keeps this guard. T3 Code's v10 doesnot have this safety guard. Both installers overwrite an installed helperof the same version, so whichever app installed last determines whether theguard is present. Keep `winrects@cua` disabled on GNOME 50 regardless.diff --git a/libs/cua-driver/wayland-helper/winrects@cua/extension.js b/libs/cua-driver/wayland-helper/winrects@cua/extension.jsindex 56011b40c2..b8208f4be1 100644--- a/libs/cua-driver/wayland-helper/winrects@cua/extension.js+++ b/libs/cua-driver/wayland-helper/winrects@cua/extension.js@@ -23,6 +23,8 @@ const IFACE = `<node><interface name="org.cua.WinRects"><method name="ClickPulse"><arg type="i" direction="in" name="x"/><arg type="i" direction="in" name="y"/></method><method name="SetCursorColor"><arg type="s" direction="in" name="fill_color"/></method><method name="SetCursorState"><arg type="s" direction="in" name="action"/><arg type="s" direction="in" name="delivery"/><arg type="s" direction="in" name="target"/><arg type="b" direction="in" name="active"/></method>+<method name="SetCursorLook"><arg type="s" direction="in" name="look_json"/></method>+<method name="PlayCursorPath"><arg type="s" direction="in" name="track_json"/></method><method name="SetSessionLabel"><arg type="s" direction="in" name="label"/></method><method name="HideCursor"></method></interface></node>`;@@ -70,6 +72,208 @@ const ACTION_DURATIONS = {system: 1.6,};+// cua-driver plans every move with the shared planner and sends it as poses+// (PlayCursorPath), with the resting float and halo it paints with+// (SetCursorLook). The helper only plays them back and carries the float on at+// rest from the clock each track ends on; it plans nothing.+const TIP_X = 55;+const TIP_Y = 30;+const MAX_POSE_JSON = 256 * 1024;+const MAX_PATH_SAMPLES = 2000;+const PATH_FRAME_MS = 16;++function finiteWithin(value, limit) {+ return typeof value === 'number' && Number.isFinite(value) && Math.abs(value) <= limit;+}++function parseJsonObject(json) {+ if (typeof json !== 'string' || json.length === 0 || json.length > MAX_POSE_JSON) return null;+ try {+ const value = JSON.parse(json);+ return value && typeof value === 'object' && !Array.isArray(value) ? value : null;+ } catch (_error) {+ return null;+ }+}++function parseFloatLook(value) {+ if (value === null || value === undefined) return null;+ const f = value;+ const ok =+ finiteWithin(f?.secs, 60) && f.secs >= 0.1 &&+ finiteWithin(f.sway, 50) && f.sway >= 0 &&+ finiteWithin(f.bob, 50) && f.bob >= 0 &&+ finiteWithin(f.lift, 50) && f.lift >= 0 &&+ finiteWithin(f.tilt, 1) && f.tilt >= 0 &&+ finiteWithin(f.hold, 60) && f.hold >= 0 &&+ finiteWithin(f.ease_in, 60) && f.ease_in > 0 &&+ finiteWithin(f.ease_out, 60) && f.ease_out > 0;+ if (!ok) return undefined;+ return {+ secs: f.secs,+ sway: f.sway,+ bob: f.bob,+ lift: f.lift,+ tilt: f.tilt,+ hold: f.hold,+ easeIn: f.ease_in,+ easeOut: f.ease_out,+ };+}++function parseCursorLook(json) {+ const look = parseJsonObject(json);+ if (!look) return null;+ const float = parseFloatLook(look.float);+ if (float === undefined) return null;+ let halo = null;+ if (look.halo !== null && look.halo !== undefined) {+ const h = look.halo;+ const rgb = typeof h?.rgb === 'string' ? /^#([0-9a-fA-F]{6})$/.exec(h.rgb) : null;+ const stops = Array.isArray(h?.stops) ? h.stops : [];+ const body = Array.isArray(h?.body) ? h.body : [];+ if (+ !rgb ||+ !finiteWithin(h.radius, 200) ||+ h.radius <= 0 ||+ !finiteWithin(h.peak, 1) ||+ h.peak < 0 ||+ stops.length < 1 ||+ stops.length > 8 ||+ !stops.every(+ (stop) =>+ Array.isArray(stop) &&+ stop.length === 2 &&+ stop.every((part) => finiteWithin(part, 1) && part >= 0)+ ) ||+ body.length !== 2 ||+ !body.every((part) => finiteWithin(part, 200))+ )+ return null;+ const value = Number.parseInt(rgb[1], 16);+ halo = {+ rgb: [(value >> 16) & 0xff, (value >> 8) & 0xff, value & 0xff],+ radius: h.radius,+ peak: h.peak,+ stops: stops.map(([offset, share]) => [offset, share]),+ body: [body[0], body[1]],+ };+ }+ return { float, halo };+}++function parseCursorPath(json) {+ const track = parseJsonObject(json);+ if (!track || !Array.isArray(track.samples)) return null;+ const samples = track.samples;+ if (samples.length < 1 || samples.length > MAX_PATH_SAMPLES) return null;+ let previous = 0;+ for (const sample of samples) {+ if (!Array.isArray(sample) || sample.length !== 6) return null;+ const [t, x, y, dx, dy, rotation] = sample;+ if (!finiteWithin(t, 30) || t < previous) return null;+ if (!finiteWithin(x, 100000) || !finiteWithin(y, 100000)) return null;+ if (!finiteWithin(dx, 100) || !finiteWithin(dy, 100) || !finiteWithin(rotation, 8)) return null;+ previous = t;+ }+ const arrival = track.arrival;+ if (arrival !== null && arrival !== undefined && (!finiteWithin(arrival, 30) || arrival < 0))+ return null;+ // The float clock at the last sample: [phase, hold, from].+ const rest = track.rest;+ if (+ !Array.isArray(rest) ||+ rest.length !== 3 ||+ !finiteWithin(rest[0], 1e7) ||+ !finiteWithin(rest[1], 3600) ||+ rest[1] < 0 ||+ !finiteWithin(rest[2], 1) ||+ rest[2] < 0+ )+ return null;+ return {+ samples,+ arrival: arrival ?? null,+ rest: { phase: rest[0], hold: rest[1], from: rest[2] },+ };+}++// Linear interpolation between the planner's samples, clamped to the ends.+function samplePath(samples, t) {+ if (t <= samples[0][0]) return samples[0];+ const last = samples[samples.length - 1];+ if (t >= last[0]) return last;+ let lo = 0;+ let hi = samples.length - 1;+ while (hi - lo > 1) {+ const mid = (lo + hi) >> 1;+ if (samples[mid][0] <= t) lo = mid;+ else hi = mid;+ }+ const a = samples[lo];+ const b = samples[hi];+ const f = b[0] > a[0] ? (t - a[0]) / (b[0] - a[0]) : 1;+ return a.map((value, index) => value + (b[index] - value) * f);+}++function smoothstep(x) {+ const t = Math.min(1, Math.max(0, x));+ return t * t * (3 - 2 * t);+}++// cursor_pose::rest_amplitude: `from` eases out to 0, holds at 0 for the+// click, drop or typing that follows, then eases back in to 1.+function restAmplitude(float, hold, from) {+ const out = Math.min(1, Math.max(0, from)) * (1 - smoothstep(hold / float.easeOut));+ const back = smoothstep((hold - float.hold) / float.easeIn);+ return Math.max(out, back);+}++const STILL = Object.freeze({ dx: 0, dy: 0, rotation: 0 });++// cursor_pose::float_at at the rest amplitude: the 4 s sway, bob and tilt,+// `now - rest.at` seconds on from the clock `rest` (phase, hold, from). The+// phase never restarts.+function restingFloat(look, rest, now) {+ const float = look?.float;+ if (!float || !rest) return STILL;+ const elapsed = Math.max(0, now - rest.at);+ const amp = restAmplitude(float, rest.hold + elapsed, rest.from);+ if (amp <= 0) return STILL;+ const angle = (((rest.phase + elapsed) % float.secs) / float.secs) * 2 * Math.PI;+ return {+ dx: amp * float.sway * Math.sin(angle),+ dy: amp * (float.bob * Math.cos(angle) - float.lift),+ rotation: amp * float.tilt * Math.cos(angle),+ };+}++// The halo of cursor_pose::paint_halo, centred on the arrow body, in canvas+// units with the tip at (TIP_X, TIP_Y).+function drawCursorHalo(cr, halo, rotation) {+ const sin = Math.sin(rotation);+ const cos = Math.cos(rotation);+ const bx = halo.body[0] / SCALE;+ const by = halo.body[1] / SCALE;+ const cx = TIP_X + bx * cos - by * sin;+ const cy = TIP_Y + bx * sin + by * cos;+ const radius = halo.radius / SCALE;+ const gradient = new Cairo.RadialGradient(cx, cy, 0, cx, cy, radius);+ for (const [offset, share] of halo.stops)+ gradient.addColorStopRGBA(+ offset,+ halo.rgb[0] / 255,+ halo.rgb[1] / 255,+ halo.rgb[2] / 255,+ halo.peak * share+ );+ cr.save();+ cr.setSource(gradient);+ cr.arc(cx, cy, radius, 0, 2 * Math.PI);+ cr.fill();+ cr.restore();+}+function nowSeconds() {return GLib.get_monotonic_time() / 1_000_000;}@@ -705,6 +909,12 @@ export default class WinRectsExtension extends Extension {this._fillColor = [94, 192, 232];this._fillColorCss = '#5ec0e8';this._glowSurface = createGlowSurface(this._fillColor);+ // Null until cua-driver sends a look: an older driver keeps the glow.+ this._look = null;+ this._path = null;+ this._pathFrameId = 0;+ // The float clock at `at`: a fresh cursor floats fully.+ this._rest = { at: nowSeconds(), phase: 0, hold: 3600, from: 0 };this._cursor = new St.DrawingArea({width: ACTOR_SIZE,height: ACTOR_SIZE,@@ -717,11 +927,19 @@ export default class WinRectsExtension extends Extension {const duration = ACTION_DURATIONS[this._action] ?? 1.6;const elapsed = nowSeconds() - this._actionStarted;const progress = (elapsed % duration) / duration;+ const pose = this._pose(nowSeconds());cr.save();cr.translate(ACTOR_CENTER, ACTOR_CENTER);cr.scale(SCALE, SCALE);cr.translate(-CANVAS_SIZE / 2, -CANVAS_SIZE / 2);- drawCursorGlow(cr, progress, this._action, this._glowSurface);+ // The float moves the whole cursor; the rotation (heading plus the+ // float tilt) turns it about its tip.+ cr.translate(pose.dx / SCALE, pose.dy / SCALE);+ if (!this._look) drawCursorGlow(cr, progress, this._action, this._glowSurface);+ else if (this._look.halo) drawCursorHalo(cr, this._look.halo, pose.rotation);+ cr.translate(TIP_X, TIP_Y);+ cr.rotate(pose.rotation);+ cr.translate(-TIP_X, -TIP_Y);drawActionCue(cr, this._action, progress, this._fillColor);drawCursorBody(cr, progress, this._action, this._fillColor);cr.restore();@@ -836,6 +1054,7 @@ export default class WinRectsExtension extends Extension {GLib.source_remove(this._frameId);this._frameId = 0;}+ this._stopPath();if (this._cursor) {this._cursor.destroy();this._cursor = null;@@ -861,7 +1080,7 @@ export default class WinRectsExtension extends Extension {}}GetVersion() {- return 10;+ return 11;}GetRects() {const actors = global.get_window_actors();@@ -1027,6 +1246,7 @@ export default class WinRectsExtension extends Extension {}MoveCursor(x, y) {if (!this._cursor) return;+ this._stopPath();const revealBadge = !this._cursor.visible;this._cursorX = x;this._cursorY = y;@@ -1043,12 +1263,20 @@ export default class WinRectsExtension extends Extension {ClickPulse(x, y) {if (!this._cursor) return;const revealBadge = !this._cursor.visible;- this._cursorX = x;- this._cursorY = y;- this._cursor.set_position(x - ACTOR_CENTER, y - ACTOR_CENTER);- this._positionBadge(x, y, 0);+ // A move still settling onto the click point finishes by itself.+ const end = this._path?.samples[this._path.samples.length - 1];+ const settling = end && Math.hypot(end[1] - x, end[2] - y) <= 2;+ if (!settling) {+ this._stopPath();+ this._cursor.remove_all_transitions();+ this._cursorX = x;+ this._cursorY = y;+ this._cursor.set_position(x - ACTOR_CENTER, y - ACTOR_CENTER);+ this._positionBadge(x, y, 0);+ }if (['idle', 'navigate', 'click'].includes(this._action))this._setCursorState('click', this._delivery, this._target);+ this._settleFloat();this._cursor.show();this._cursor.queue_repaint();if (revealBadge) this._revealBadge();@@ -1066,10 +1294,91 @@ export default class WinRectsExtension extends Extension {this._glowSurface = createGlowSurface(this._fillColor);if (this._cursor) this._cursor.queue_repaint();}+ SetCursorLook(lookJson) {+ const look = parseCursorLook(lookJson);+ if (!look) return;+ this._look = look;+ if (this._cursor) this._cursor.queue_repaint();+ }+ PlayCursorPath(trackJson) {+ if (!this._cursor) return;+ const track = parseCursorPath(trackJson);+ if (!track) return;+ const revealBadge = !this._cursor.visible;+ const now = nowSeconds();+ this._stopPath();+ this._cursor.remove_all_transitions();+ this._badge?.remove_all_transitions();+ // At rest the float carries on from the clock the track ends on.+ const end = track.samples[track.samples.length - 1][0];+ this._rest = { at: now + end, ...track.rest };+ const first = track.samples[0];+ this._placeCursor(first[1], first[2]);+ this._cursor.show();+ if (track.samples.length > 1) {+ this._path = { samples: track.samples, start: now };+ this._pathFrameId = GLib.timeout_add(GLib.PRIORITY_DEFAULT, PATH_FRAME_MS, () => {+ if (!this._cursor || !this._path) {+ this._pathFrameId = 0;+ return GLib.SOURCE_REMOVE;+ }+ const t = nowSeconds() - this._path.start;+ const samples = this._path.samples;+ const [, x, y] = samplePath(samples, t);+ this._placeCursor(x, y);+ this._cursor.queue_repaint();+ if (t >= samples[samples.length - 1][0]) {+ this._path = null;+ this._pathFrameId = 0;+ return GLib.SOURCE_REMOVE;+ }+ return GLib.SOURCE_CONTINUE;+ });+ }+ this._cursor.queue_repaint();+ if (revealBadge) this._revealBadge();+ }+ // Float offset (points) and rotation (radians) painted at `now`.+ _pose(now) {+ if (this._path) {+ const [, , , dx, dy, rotation] = samplePath(this._path.samples, now - this._path.start);+ return { dx, dy, rotation };+ }+ return restingFloat(this._look, this._rest, now);+ }+ // RenderStateCore::settle_float: a click or cue at rest eases the float+ // out from where it is and holds it at 0. The phase runs on. A path in+ // flight already settles at its arrival.+ _settleFloat() {+ if (this._path || !this._look?.float) return;+ const now = nowSeconds();+ // Negative when a click cut a path short: the phase is linear in time.+ const elapsed = now - this._rest.at;+ const amp = restAmplitude(+ this._look.float,+ Math.max(0, this._rest.hold + elapsed),+ this._rest.from+ );+ this._rest = { at: now, phase: this._rest.phase + elapsed, hold: 0, from: amp };+ }+ _placeCursor(x, y) {+ this._cursorX = x;+ this._cursorY = y;+ this._cursor.set_position(Math.round(x - ACTOR_CENTER), Math.round(y - ACTOR_CENTER));+ this._positionBadge(x, y, 0);+ }+ _stopPath() {+ if (this._pathFrameId) {+ GLib.source_remove(this._pathFrameId);+ this._pathFrameId = 0;+ }+ this._path = null;+ }SetCursorState(action, delivery, target, active) {if (!ACTIONS.has(action)) return;if (active) {this._setCursorState(action, delivery, target);+ this._settleFloat();} else if (this._action === action && !ONE_SHOT_ACTIONS.has(action)) {this._endingAt = nowSeconds() + 0.4;}@@ -1142,6 +1451,7 @@ export default class WinRectsExtension extends Extension {}}HideCursor() {+ this._stopPath();if (this._cursor) this._cursor.hide();if (this._badge) this._badge.hide();this._badgeRevealedAt = null;diff --git a/libs/cua-driver/wayland-helper/winrects@cua/metadata.json b/libs/cua-driver/wayland-helper/winrects@cua/metadata.jsonindex 6be4464e7b..99870afafe 100644--- a/libs/cua-driver/wayland-helper/winrects@cua/metadata.json+++ b/libs/cua-driver/wayland-helper/winrects@cua/metadata.json@@ -3,5 +3,5 @@"name": "WinRects","description": "Expose window geometry, capture, cursor, and verified activation for cua-driver on Wayland.","shell-version": ["45", "46", "47", "48", "49"],- "version": 10+ "version": 11}diff --git a/scripts/docs-generators/cli-specs/cua-driver-mcp-linux.json b/scripts/docs-generators/cli-specs/cua-driver-mcp-linux.jsonindex c52e97a41e..aea010729e 100644--- a/scripts/docs-generators/cli-specs/cua-driver-mcp-linux.json+++ b/scripts/docs-generators/cli-specs/cua-driver-mcp-linux.json@@ -2123,7 +2123,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.\n\n`cursor.badges` (`minimal` default, `verbose`, or `off`) sets the agent cursor badge for every cursor at once.\n\n`cursor.float` (resting float) is `on` (default), `off` or `default`; `cursor.marks` (action marks) and `cursor.rotate` (turn toward travel) are `on`, `off` (default) or `default`. All apply to every cursor at once.",+ "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.\n\n`cursor.float` (float at rest and while moving) and `cursor.halo` (soft glow) are `on` (default), `off` or `default`; `cursor.marks` (action marks) is `on`, `off` (default) or `default`; `cursor.rotate` is `heading` (default), `lean`, `off` or `default`. All apply to every cursor at once.","destructive": false,"idempotent": true,"input_schema": {@@ -2148,7 +2148,16 @@"type": "string"},"cursor.float": {- "description": "Agent cursor resting float: a slow up-and-down bob while the cursor rests; the arrow stays upright. on (default). off: the cursor stays still at rest and the overlay stops redrawing. Applies immediately to every cursor.",+ "description": "Agent cursor float: a slow four-second sway, bob and slight tilt, at rest and while moving, that eases to zero on every arrival and holds there for the click, drag, drop, scroll or typing, so they land exactly upright on the hotspot. on (default). off: the cursor never floats and a resting overlay stops redrawing. Applies immediately to every cursor.",+ "enum": [+ "on",+ "off",+ "default"+ ],+ "type": "string"+ },+ "cursor.halo": {+ "description": "Agent cursor halo: a soft glow in the cursor's colour behind the arrow, so it is easier to follow on any background. on (default). off: no halo. Applies immediately to every cursor.","enum": ["on","off",@@ -2243,10 +2252,12 @@"type": "string"},"cursor.rotate": {- "description": "Agent cursor rotation: the arrow turns toward the direction it moves and settles upright on arrival. off (default): the arrow always stays upright. Applies immediately to every cursor.",+ "description": "Agent cursor rotation while it moves: heading (default) points the tip along the path; lean tilts the arrow at most 30 degrees toward where it is going (on is the same as heading). Both return upright before arrival, so clicks, typing and scrolling stay upright. off: the arrow always stays upright. Applies immediately to every cursor.","enum": [- "on","off",+ "lean",+ "heading",+ "on","default"],"type": "string"diff --git a/scripts/docs-generators/cli-specs/cua-driver-mcp-macos.json b/scripts/docs-generators/cli-specs/cua-driver-mcp-macos.jsonindex a1ee73c27f..7885b20235 100644--- a/scripts/docs-generators/cli-specs/cua-driver-mcp-macos.json+++ b/scripts/docs-generators/cli-specs/cua-driver-mcp-macos.json@@ -1859,7 +1859,7 @@"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.\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.\n\nAgent cursor extras: cursor.float (resting float) is on (default), off or default; cursor.marks (action marks) and cursor.rotate (turn toward travel) are on, off (default) or default. All are saved to ~/.cua-driver/config.json and applied to every cursor at once.",+ "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.\n\nAgent cursor extras: cursor.float (float at rest and while moving) and cursor.halo (soft glow) are on (default), off or default; cursor.marks (action marks) is on, off (default) or default; cursor.rotate is heading (default), lean, off or default. All are saved to ~/.cua-driver/config.json and applied to every cursor at once.","destructive": false,"idempotent": true,"input_schema": {@@ -1876,7 +1876,16 @@"type": "string"},"cursor.float": {- "description": "Agent cursor resting float: a slow up-and-down bob while the cursor rests; the arrow stays upright. on (default). off: the cursor stays still at rest and the overlay stops redrawing. Applies immediately to every cursor.",+ "description": "Agent cursor float: a slow four-second sway, bob and slight tilt, at rest and while moving, that eases to zero on every arrival and holds there for the click, drag, drop, scroll or typing, so they land exactly upright on the hotspot. on (default). off: the cursor never floats and a resting overlay stops redrawing. Applies immediately to every cursor.",+ "enum": [+ "on",+ "off",+ "default"+ ],+ "type": "string"+ },+ "cursor.halo": {+ "description": "Agent cursor halo: a soft glow in the cursor's colour behind the arrow, so it is easier to follow on any background. on (default). off: no halo. Applies immediately to every cursor.","enum": ["on","off",@@ -1971,10 +1980,12 @@"type": "string"},"cursor.rotate": {- "description": "Agent cursor rotation: the arrow turns toward the direction it moves and settles upright on arrival. off (default): the arrow always stays upright. Applies immediately to every cursor.",+ "description": "Agent cursor rotation while it moves: heading (default) points the tip along the path; lean tilts the arrow at most 30 degrees toward where it is going (on is the same as heading). Both return upright before arrival, so clicks, typing and scrolling stay upright. off: the arrow always stays upright. Applies immediately to every cursor.","enum": [- "on","off",+ "lean",+ "heading",+ "on","default"],"type": "string"diff --git a/scripts/docs-generators/cli-specs/cua-driver-mcp-windows.json b/scripts/docs-generators/cli-specs/cua-driver-mcp-windows.jsonindex 374c224d69..262daa5640 100644--- a/scripts/docs-generators/cli-specs/cua-driver-mcp-windows.json+++ b/scripts/docs-generators/cli-specs/cua-driver-mcp-windows.json@@ -1817,7 +1817,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- `cursor.badges` (`minimal` default, `verbose`, or `off`) — agent cursor badge; applies to every cursor at once.\n- `cursor.float` (resting float): `on` (default), `off`, or `default`. `cursor.marks` (action marks), `cursor.rotate` (turn toward travel): `on`, `off` (default), or `default`. All apply to every cursor at once.\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- `cursor.float` (float at rest and while moving), `cursor.halo` (soft glow): `on` (default), `off`, or `default`. `cursor.marks` (action marks): `on`, `off` (default), or `default`. `cursor.rotate`: `heading` (default), `lean`, `off`, or `default`. All apply to every cursor at once.\n\nReturns the full updated config in the same shape as `get_config`.","destructive": false,"idempotent": true,"input_schema": {@@ -1842,7 +1842,16 @@"type": "string"},"cursor.float": {- "description": "Agent cursor resting float: a slow up-and-down bob while the cursor rests; the arrow stays upright. on (default). off: the cursor stays still at rest and the overlay stops redrawing. Applies immediately to every cursor.",+ "description": "Agent cursor float: a slow four-second sway, bob and slight tilt, at rest and while moving, that eases to zero on every arrival and holds there for the click, drag, drop, scroll or typing, so they land exactly upright on the hotspot. on (default). off: the cursor never floats and a resting overlay stops redrawing. Applies immediately to every cursor.",+ "enum": [+ "on",+ "off",+ "default"+ ],+ "type": "string"+ },+ "cursor.halo": {+ "description": "Agent cursor halo: a soft glow in the cursor's colour behind the arrow, so it is easier to follow on any background. on (default). off: no halo. Applies immediately to every cursor.","enum": ["on","off",@@ -1937,10 +1946,12 @@"type": "string"},"cursor.rotate": {- "description": "Agent cursor rotation: the arrow turns toward the direction it moves and settles upright on arrival. off (default): the arrow always stays upright. Applies immediately to every cursor.",+ "description": "Agent cursor rotation while it moves: heading (default) points the tip along the path; lean tilts the arrow at most 30 degrees toward where it is going (on is the same as heading). Both return upright before arrival, so clicks, typing and scrolling stay upright. off: the arrow always stays upright. Applies immediately to every cursor.","enum": [- "on","off",+ "lean",+ "heading",+ "on","default"],"type": "string"diff --git a/scripts/docs-generators/cli-specs/cua-driver.json b/scripts/docs-generators/cli-specs/cua-driver.jsonindex ef0d08d444..ee9fafb46c 100644--- a/scripts/docs-generators/cli-specs/cua-driver.json+++ b/scripts/docs-generators/cli-specs/cua-driver.json@@ -1020,7 +1020,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. cursor.badges (minimal, verbose, off) sets the agent cursor badge for every cursor at once; minimal is the default. cursor.float (resting float) is on, off or default and on by default; cursor.marks (action marks) and cursor.rotate (turn toward travel) are on, off or default and off by default. All three apply to every cursor at once.",+ "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. cursor.float (float at rest and while moving) and cursor.halo (soft glow) are on, off or default and on by default; cursor.marks (action marks) is on, off or default and off by default; cursor.rotate is heading (default), lean, off or default. All apply to every cursor at once.","examples": [{"command": "cua-driver config set max_image_dimension 1568",