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(cursor-overlay): retina-aware rendering + arrow/teardrop selection
Francesco Bonaccic172e2acfa03
diff --git a/docs/content/docs/how-to-guides/driver/personalize-cursor.mdx b/docs/content/docs/how-to-guides/driver/personalize-cursor.mdxindex a35b44f756..925b742ac7 100644--- a/docs/content/docs/how-to-guides/driver/personalize-cursor.mdx+++ b/docs/content/docs/how-to-guides/driver/personalize-cursor.mdx@@ -1,12 +1,28 @@---title: Personalize the Cua cursor-description: Swap the agent cursor shape and palette — use the brand default, override at runtime, or bring your own SVG/PNG/ICO.+description: Swap the agent cursor shape and palette — pick a built-in silhouette, override at runtime, or bring your own SVG/PNG/ICO.---import { Tabs, Tab } from 'fumadocs-ui/components/tabs';import { Callout } from 'fumadocs-ui/components/callout';-By default the cua agent cursor is the **cua-brand** pointer — an upward-pointing teardrop with a gradient body and white outline. It rotates to follow motion direction and renders at native resolution on retina displays. You can swap the body color at runtime, replace the shape with your own asset, or scale the bloom halo independently.+The cua agent cursor ships with two built-in silhouettes:++- **`arrow`** (the default) — a procedural gradient diamond drawn from vector primitives each frame. Sharp at any backing scale.+- **`teardrop`** — an embedded `cursor-up` SVG (upward teardrop with notched bottom, gradient body, white outline) rasterised once into a 52 px buffer.++`arrow` is the default while we finish sorting the teardrop's retina rasterisation. Opt into the teardrop with `--cursor-shape teardrop`. You can also replace the silhouette entirely with your own SVG / PNG / JPEG / ICO file via `--cursor-icon <path>`, swap the body palette at runtime, or scale the bloom halo independently.++## Pick a built-in silhouette++```bash+cua-driver serve --cursor-shape teardrop # opt into the SVG teardrop+cua-driver serve --cursor-shape arrow # explicit; same as the default+```++`--cursor-shape` is parsed on `serve` and `mcp`. It's a no-op on one-shot CLI calls like `cua-driver call` — those don't keep the long-lived UI runloop the overlay needs.++`--cursor-icon <path>` always wins over `--cursor-shape`: if you pass both, the custom file is what renders.## Change the cursor look at runtime@@ -19,13 +35,15 @@ Every per-instance cursor accepts a runtime style override via the `set_agent_cu}```-- `gradient_colors`: array of CSS hex strings used as the cursor body's tip-to-tail gradient. An empty array reverts to the brand default (`#F0FBFF` → `#66D9FF` → `#35C6D8`).+- `gradient_colors`: array of CSS hex strings used as the cursor body's tip-to-tail gradient. An empty array reverts to the palette default (`#F0FBFF` → `#66D9FF` → `#35C6D8` on the teardrop; the palette's `cursor_start/mid/end` on the arrow).- `bloom_color`: hex string for the radial halo behind the cursor. Empty string reverts.-- `image_path`: path to a PNG / JPEG / SVG / ICO file. When set, replaces the brand pointer with your asset. Empty string reverts.+- `image_path`: path to a PNG / JPEG / SVG / ICO file. When set, replaces the built-in silhouette with your asset. Empty string reverts.++Switching between `arrow` and `teardrop` at runtime is not exposed via `set_agent_cursor_style` yet — for now it's CLI-only.## Use your own cursor asset-Pass `--cursor-icon <path>` to `cua-driver serve` (or set `image_path` on `set_agent_cursor_style` at runtime). Supported formats: `.svg`, `.png`, `.jpeg`, `.ico`. The asset is rasterised once at startup into a 52×52 RGBA buffer and used in place of the brand pointer.+Pass `--cursor-icon <path>` to `cua-driver serve` (or set `image_path` on `set_agent_cursor_style` at runtime). Supported formats: `.svg`, `.png`, `.jpeg`, `.ico`. The asset is rasterised once at startup into a 52×52 RGBA buffer and used in place of the built-in silhouette.```bashcua-driver serve --cursor-icon ~/my-cursor.svg@@ -38,20 +56,30 @@ Custom cursor assets are rendered with no rotation compensation — the driver a2. **Stick with PNG / static art** if you don't care about motion-aligned rotation — the cursor will render at a fixed orientation regardless of motion direction. This is what most OS cursor packs do.</Callout>-## How the default renders+## How the built-ins render++### `arrow` (default)++- **Path**: procedural gradient diamond. 4-vertex polygon `(14, 0) → (−8, −9) → (−3, 0) → (−8, 9)` rebuilt each frame.+- **Body**: linear gradient from the palette's `cursor_start` to `cursor_end` (runtime `gradient_colors` overrides).+- **Rotation**: tip at +x at rest; `heading + π` aligns the tip with motion direction.+- **Resolution**: drawn from vector primitives every frame, so it stays sharp at any backing scale without rasterisation artifacts.++### `teardrop`- **Path**: classic upward teardrop with a notched bottom (Streamline Iconoir `cursor-up`).- **Body**: linear gradient from `#F0FBFF` at the tip to `#35C6D8` at the tail.-- **Outline**: white 1.5px stroke, rounded caps and joins.+- **Outline**: white 1.5 px stroke, rounded caps and joins.- **Bloom**: soft radial halo behind the cursor, tinted from the palette's bloom color.- **Rotation**: the SVG points up at rest; a `+90°` paint-time offset aligns the tip with motion direction so the cursor faces where it's heading.-- **Resolution**: source rasterised at 2× the display target (52 px) and rendered at backing-aware physical resolution on retina, for pixel-perfect crispness.+- **Resolution**: source rasterised at 2× the display target (52 px) and rendered at backing-aware physical resolution on retina. We're still tightening retina crispness on this path — that's why the default is `arrow` for now.## Things that aren't currently personalizable- **Multiple agent cursors with distinct palettes.** Only one built-in palette today. If you want per-agent distinct cursors, file an issue with the use case.- **Cursor display size.** Fixed at 26 logical pixels (52 physical on retina). The runtime `cursor_size` field controls the **dot-style** cursor's radius and doesn't apply to the shape-based render path.- **Motion-path curve shape.** Glide duration, post-click dwell, idle-hide delay, and spring damping are tunable via `set_agent_cursor_motion`, but the underlying bezier shape of the path is hardcoded.+- **Switching `arrow` ↔ `teardrop` at runtime.** Today it's CLI-only — restart the daemon with a different `--cursor-shape` to swap.## See alsodiff --git a/libs/cua-driver/rust/crates/cua-driver/src/cli.rs b/libs/cua-driver/rust/crates/cua-driver/src/cli.rsindex 6b053015be..b206285bef 100644--- a/libs/cua-driver/rust/crates/cua-driver/src/cli.rs+++ b/libs/cua-driver/rust/crates/cua-driver/src/cli.rs@@ -124,7 +124,7 @@ pub enum Command {/// Flags whose next token is a value (not a subcommand)./// We skip both the flag and its value when scanning for the subcommand.const VALUE_FLAGS: &[&str] = &[- "--cursor-icon", "--cursor-id", "--cursor-palette",+ "--cursor-icon", "--cursor-id", "--cursor-palette", "--cursor-shape","--glide-ms", "--dwell-ms", "--idle-hide-ms","--screenshot-out-file", "--client", "--socket", "--pid-file", "--type",// Experimental PiP preview — value flag for the optional geometry@@ -207,7 +207,9 @@ pub fn parse_command() -> Command {println!(" for a visibly gliding demo. These flags tune the overlay on `serve`/`mcp`:");println!(" --no-overlay Disable the cursor overlay entirely for this daemon.");println!(" --cursor-id <id> Name the default cursor instance (default: 'default').");- println!(" --cursor-icon <path> Use a custom PNG cursor icon.");+ println!(" --cursor-icon <path> Use a custom PNG / JPEG / SVG / ICO cursor asset.");+ println!(" --cursor-shape <name> Built-in silhouette: 'arrow' (default — procedural");+ println!(" gradient diamond) or 'teardrop' (embedded cursor-up SVG).");println!(" --cursor-palette <name> Pick a built-in colour palette for the cursor.");println!(" (These are no-ops for one-shot CLI calls like `cua-driver call` — the overlay");println!(" needs the long-lived AppKit runloop that only `serve` / `mcp` keep alive.)");diff --git a/libs/cua-driver/rust/crates/cursor-overlay/src/lib.rs b/libs/cua-driver/rust/crates/cursor-overlay/src/lib.rsindex 7d395b8e88..fa81e15a5f 100644--- a/libs/cua-driver/rust/crates/cursor-overlay/src/lib.rs+++ b/libs/cua-driver/rust/crates/cursor-overlay/src/lib.rs@@ -22,7 +22,7 @@ pub use palette::Palette;pub use motion::{MotionConfig, Spring};pub use bezier::CubicBezier;pub use path_planner::{PathPlanner, PlannedPath, PathState};-pub use shape::CursorShape;+pub use shape::{BuiltinShape, CursorShape};pub use render_state::{RenderStateCore, FocusRect, render_frame, paint_cursor, draw_default_arrow};pub use z_order::ZOrderEnforcer;@@ -34,10 +34,17 @@ pub struct CursorConfig {/// Defaults to `"default"`.pub cursor_id: String,- /// Custom cursor shape loaded from `--cursor-icon <path>`.- /// `None` means use the built-in gradient arrow.+ /// Custom cursor shape loaded from `--cursor-icon <path>`. Takes+ /// precedence over `builtin_shape` when set. `None` means use the+ /// built-in selected by `builtin_shape`.pub shape: Option<CursorShape>,+ /// Which built-in silhouette to render when no custom `shape` is set.+ /// Defaults to [`BuiltinShape::Arrow`] (the procedural gradient+ /// diamond) until the embedded teardrop's retina rasterisation is+ /// fully sorted; opt into the teardrop via `--cursor-shape teardrop`.+ pub builtin_shape: BuiltinShape,+/// Initial motion config (can be updated at runtime via MCP tool).pub motion: MotionConfig,@@ -51,6 +58,7 @@ impl Default for CursorConfig {Self {cursor_id: "default".into(),shape: None,+ builtin_shape: BuiltinShape::default(),motion: MotionConfig::default(),enabled: true,}@@ -64,6 +72,8 @@ impl CursorConfig {/// ```text/// --cursor-icon <path.svg|path.ico|path.png>/// --cursor-id <id>+ /// --cursor-shape <arrow|teardrop> (selects a built-in silhouette;+ /// default: arrow)/// --cursor-palette <name> (selects a named Palette)/// --no-overlay (start with overlay disabled)/// --glide-ms <f64> (glideDurationMs override)@@ -103,6 +113,17 @@ impl CursorConfig {i += 1;}}+ "--cursor-shape" => {+ if let Some(name) = args.get(i + 1) {+ match BuiltinShape::parse(name) {+ Some(s) => cfg.builtin_shape = s,+ None => tracing::warn!(+ "--cursor-shape {name}: unknown shape (expected arrow|teardrop); falling back to default"+ ),+ }+ i += 1;+ }+ }"--no-overlay" => cfg.enabled = false,"--glide-ms" => {if let Some(v) = args.get(i + 1).and_then(|s| s.parse().ok()) {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 34a07183a2..3295b53175 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@@ -39,8 +39,8 @@//! supplies one via the optional argument).use crate::{- CursorConfig, CursorShape, MotionConfig, OverlayCommand, Palette, PathPlanner, PathState,- PlannedPath, Spring,+ BuiltinShape, CursorConfig, CursorShape, MotionConfig, OverlayCommand, Palette, PathPlanner,+ PathState, PlannedPath, Spring,};/// Platform-agnostic render state shared by macOS / Windows / Linux overlays.@@ -517,6 +517,10 @@ pub struct FocusRect {/// drawing — Windows passes the virtual-screen `(virt_x, virt_y)` so the/// pixmap is laid out in window-local coordinates. macOS / Linux pass/// `(0.0, 0.0)`.+///+/// `backing_scale` is the destination-pixmap-pixels per logical-point ratio+/// (e.g. 2.0 on a retina display where the pixmap is sized at physical+/// pixels). Pass `1.0` when the pixmap is sized at logical pixels.pub fn render_frame(core: &RenderStateCore,width: u32,@@ -524,12 +528,13 @@ pub fn render_frame(origin_x: f64,origin_y: f64,focus_rect: Option<FocusRect>,+ backing_scale: f32,) -> tiny_skia::Pixmap {let w = width.max(1);let h = height.max(1);let mut pm = tiny_skia::Pixmap::new(w, h).unwrap_or_else(|| tiny_skia::Pixmap::new(1, 1).unwrap());- paint_cursor(&mut pm, core, origin_x, origin_y, focus_rect);+ paint_cursor(&mut pm, core, origin_x, origin_y, focus_rect, backing_scale);pm}@@ -541,6 +546,18 @@ pub fn render_frame(////// `origin_x` / `origin_y` are subtracted from `core.pos` before drawing/// (Windows passes the virtual-screen origin; macOS / Linux pass `(0.0, 0.0)`).+/// Both are in **logical** screen points, just like `core.pos`.+///+/// `backing_scale` is the destination-pixmap-pixels per logical-point ratio.+/// On a 2× retina macOS display the caller sizes the pixmap at the screen's+/// PHYSICAL pixel dimensions (logical × backing_scale) and passes `2.0` so+/// the cursor renders at native resolution instead of being upsampled by+/// Core Animation. When the pixmap is sized at LOGICAL pixels, pass `1.0`.+///+/// Everything that operates in pixmap-pixel space (the cursor anchor `px/py`,+/// bloom radius, click-pulse ring radius, stroke widths, focus-rect coords,+/// arrow `display_size`) is multiplied by `backing_scale` so the cursor still+/// occupies the same on-screen logical footprint but at higher pixel fidelity.////// Quiescent / hidden cursors early-return before touching the pixmap, so an/// idle session costs essentially nothing in the per-frame composite loop.@@ -550,17 +567,23 @@ pub fn paint_cursor(origin_x: f64,origin_y: f64,focus_rect: Option<FocusRect>,+ backing_scale: f32,) {if !core.visible || core.pos.0 < -100.0 || core.idle_alpha < 0.004 {return;}- let (px, py) = (core.pos.0 - origin_x, core.pos.1 - origin_y);+ let s = backing_scale.max(1.0) as f64; // logical-pt → pixmap-pixel scale+ let sf = s as f32;++ // Cursor anchor in pixmap-pixel space: subtract the (logical) origin+ // first, then scale into pixmap pixels.+ let (px, py) = ((core.pos.0 - origin_x) * s, (core.pos.1 - origin_y) * s);let heading = core.heading;let alpha_scale = core.idle_alpha as f32;// --- Bloom (radial gradient behind the arrow) ---- let bloom_r: f32 = if core.pressed { 34.0 } else { 22.0 };+ let bloom_r: f32 = if core.pressed { 34.0 * sf } else { 22.0 * sf };// Use runtime bloom_override if set, otherwise fall back to palette.let (br, bg, bb) = if let Some([r, g, b, _]) = core.bloom_override {(r, g, b)@@ -614,7 +637,7 @@ pub fn paint_cursor(ring_paint.shader = tiny_skia::Shader::SolidColor(ring_color);ring_paint.anti_alias = true;let stroke = tiny_skia::Stroke {- width: 3.0,+ width: 3.0 * sf,..Default::default()};let core_fill =@@ -623,7 +646,7 @@ pub fn paint_cursor(fill_paint.shader = tiny_skia::Shader::SolidColor(core_fill);fill_paint.anti_alias = true;let mut pb = tiny_skia::PathBuilder::new();- pb.push_circle(px as f32, py as f32, 6.5);+ pb.push_circle(px as f32, py as f32, 6.5 * sf);if let Some(path) = pb.finish() {pm.fill_path(&path,@@ -634,7 +657,7 @@ pub fn paint_cursor();}let mut pb = tiny_skia::PathBuilder::new();- pb.push_circle(px as f32, py as f32, 13.0);+ pb.push_circle(px as f32, py as f32, 13.0 * sf);if let Some(path) = pb.finish() {pm.stroke_path(&path,@@ -657,9 +680,12 @@ pub fn paint_cursor(// Cyan: #5EC0E8let (cr, cg, cb) = (0x5Eu8, 0xC0u8, 0xE8u8);- if let Some(rect) =- tiny_skia::Rect::from_xywh(fx as f32, fy as f32, fw as f32, fh as f32)- {+ if let Some(rect) = tiny_skia::Rect::from_xywh(+ (fx * s) as f32,+ (fy * s) as f32,+ (fw * s) as f32,+ (fh * s) as f32,+ ) {// Faint filllet mut fill_paint = tiny_skia::Paint::default();fill_paint.shader = tiny_skia::Shader::SolidColor(@@ -674,7 +700,7 @@ pub fn paint_cursor();border_paint.anti_alias = true;let stroke = tiny_skia::Stroke {- width: 2.5,+ width: 2.5 * sf,..Default::default()};let mut pb = tiny_skia::PathBuilder::new();@@ -693,7 +719,9 @@ pub fn paint_cursor(// --- Click pulse ring ---if let Some(t) = core.click_t {- let ring_r = (bloom_r + 20.0 * t as f32) * (1.0 - t as f32 * 0.5);+ // bloom_r already includes backing_scale; the +20pt expansion is+ // logical so scale it explicitly here.+ let ring_r = (bloom_r + 20.0 * sf * t as f32) * (1.0 - t as f32 * 0.5);let alpha = ((1.0 - t) * 180.0 * alpha_scale as f64) as u8;let [cr, cg, cb, _] = core.palette.cursor_mid;let ring_color = tiny_skia::Color::from_rgba8(cr, cg, cb, alpha);@@ -701,7 +729,7 @@ pub fn paint_cursor(ring_paint.shader = tiny_skia::Shader::SolidColor(ring_color);ring_paint.anti_alias = true;let stroke = tiny_skia::Stroke {- width: 2.0,+ width: 2.0 * sf,..Default::default()};let mut pb = tiny_skia::PathBuilder::new();@@ -717,38 +745,79 @@ pub fn paint_cursor(}}- // --- Arrow (custom shape or default gradient arrow) ---- if let Some(ref shape) = core.shape {- // Custom icon: draw as a 32×32 image centered at (px, py), opacity-faded.- let sz = 32.0_f32;- if let Some(pix) =- tiny_skia::PixmapRef::from_bytes(&shape.pixels, shape.width, shape.height)- {- let transform = tiny_skia::Transform::from_rotate_at(- heading.to_degrees() as f32 + 180.0,+ // --- Arrow / silhouette ---+ //+ // Three-way precedence:+ // 1. Per-instance custom asset loaded from `--cursor-icon <path>`+ // (or runtime `set_agent_cursor_style.image_path`) wins.+ // 2. Else the built-in selected by `--cursor-shape`:+ // - `arrow` (default): call `draw_default_arrow` — procedural+ // gradient diamond, sharp at any backing scale because nothing+ // rasterises.+ // - `teardrop`: blit the cached `CursorShape::teardrop()` pixmap+ // — rasterised once at 2× the display target.+ // 3. (No other built-ins today.)+ //+ // Arrow is the default until the teardrop's retina path is fully+ // sorted; opt-in via `--cursor-shape teardrop`.+ let shape: Option<&CursorShape> = match (core.shape.as_ref(), core.cfg.builtin_shape) {+ (Some(custom), _) => Some(custom),+ (None, BuiltinShape::Teardrop) => Some(CursorShape::teardrop()),+ (None, BuiltinShape::Arrow) => {+ let grad_override = if core.gradient_colors.is_empty() {+ None+ } else {+ Some(&core.gradient_colors)+ };+ draw_default_arrow(+ pm,+ &core.palette,+ grad_override,px as f32,py as f32,- )- .pre_translate(px as f32 - sz / 2.0, py as f32 - sz / 2.0);- let mut paint = tiny_skia::PixmapPaint::default();- paint.opacity = alpha_scale;- pm.draw_pixmap(0, 0, pix, &paint, transform, None);- }- } else {- let grad_override = if core.gradient_colors.is_empty() {+ heading as f32,+ alpha_scale,+ );None- } else {- Some(&core.gradient_colors)- };- draw_default_arrow(- pm,- &core.palette,- grad_override,- px as f32,- py as f32,- heading as f32,- alpha_scale,- );+ }+ };+ let shape = match shape {+ Some(s) => s,+ None => return,+ };+ // Display size in pixels. 26 logical points is a touch larger than a+ // default OS arrow — large enough to spot during agent action without+ // overwhelming the workspace. The source raster is shape.width ×+ // shape.height (64×64 for built-ins), so the transform scales down by+ // display_size/shape.width. We multiply by `backing_scale` so the arrow+ // rasterises at the destination pixmap's native resolution (e.g. 52 px+ // on a 2× retina display) — Core Animation then maps 1:1 to the screen+ // instead of upsampling a logical-pixel pixmap.+ let display_size = 26.0_f32 * sf;+ let scale = display_size / shape.width as f32;+ if let Some(pix) =+ tiny_skia::PixmapRef::from_bytes(&shape.pixels, shape.width, shape.height)+ {+ // T = Translate(px, py) * Rotate(angle) * Scale(s) * Translate(-w/2, -h/2)+ // Centres the source on its own origin, scales to display_size, rotates+ // around the scaled centre, lands the centre at (px, py).+ //+ // +90° offset compensates for the SVG's intrinsic orientation: the+ // cursor-up silhouette points UP at rest (CSS y-down angle -π/2),+ // whereas the procedural arrow's rotation convention assumes the+ // shape points RIGHT at rest (angle 0). Without the +90°, motion-+ // right rotation would leave the tip still pointing up.+ let rotation_deg = heading.to_degrees() as f32 + 180.0 + 90.0;+ let transform = tiny_skia::Transform::from_translate(+ -(shape.width as f32) / 2.0,+ -(shape.height as f32) / 2.0,+ )+ .post_scale(scale, scale)+ .post_rotate(rotation_deg)+ .post_translate(px as f32, py as f32);+ let mut paint = tiny_skia::PixmapPaint::default();+ paint.opacity = alpha_scale;+ pm.draw_pixmap(0, 0, pix, &paint, transform, None);}}@@ -914,3 +983,65 @@ mod glide_duration_tests {}}}++#[cfg(test)]+mod backing_scale_tests {+ use super::*;+ use crate::CursorConfig;++ /// Count opaque (alpha > 0) pixels in the pixmap — a proxy for the+ /// cursor's on-pixmap footprint that's independent of palette / gradient.+ fn opaque_pixel_count(pm: &tiny_skia::Pixmap) -> u32 {+ pm.data()+ .chunks_exact(4)+ .filter(|px| px[3] > 0)+ .count() as u32+ }++ fn render_at(backing_scale: f32, logical_size: u32) -> tiny_skia::Pixmap {+ let mut core = RenderStateCore::new(CursorConfig::default());+ // Place the cursor at the centre of the logical area and disable+ // idle-fade so the arrow paints at full alpha regardless of timing.+ let centre = logical_size as f64 / 2.0;+ core.pos = (centre, centre);+ core.idle_alpha = 1.0;+ core.visible = true;++ // The pixmap is sized in *pixmap* pixels (logical × backing_scale)+ // — that's the macOS retina pipeline: allocate at physical pixels,+ // then let paint_cursor scale into them.+ let pm_size = (logical_size as f32 * backing_scale) as u32;+ let mut pm = tiny_skia::Pixmap::new(pm_size, pm_size).unwrap();+ paint_cursor(&mut pm, &core, 0.0, 0.0, None, backing_scale);+ pm+ }++ /// Doubling `backing_scale` doubles every linear dimension of the cursor's+ /// pixel footprint, so the opaque-pixel COUNT should grow ~4× (one factor+ /// of 2 per axis). Exact equality isn't expected — the embedded SVG+ /// downscales from a 52-px source, anti-aliased edges round at integer+ /// boundaries, and the bloom gradient has a soft cutoff — but the ratio+ /// should sit clearly above 3.0 (well past the ~2.0 ceiling we'd hit if+ /// only one dimension were scaling). This is the regression guard for+ /// the retina-blur fix: if a future refactor reverts paint_cursor to+ /// emitting logical-pixel art into a physical-pixel pixmap, the ratio+ /// collapses back toward 1.0.+ #[test]+ fn backing_scale_two_grows_opaque_footprint_roughly_fourfold() {+ let pm_1x = render_at(1.0, 200);+ let pm_2x = render_at(2.0, 200);++ let n_1x = opaque_pixel_count(&pm_1x);+ let n_2x = opaque_pixel_count(&pm_2x);++ assert!(n_1x > 0, "1× render should paint SOMETHING (got {n_1x})");+ assert!(n_2x > 0, "2× render should paint SOMETHING (got {n_2x})");++ let ratio = n_2x as f64 / n_1x as f64;+ assert!(+ ratio > 3.0 && ratio < 5.0,+ "2× backing_scale should produce ~4× more opaque pixels — \+ got n_1x={n_1x}, n_2x={n_2x}, ratio={ratio:.2}"+ );+ }+}diff --git a/libs/cua-driver/rust/crates/cursor-overlay/src/shape.rs b/libs/cua-driver/rust/crates/cursor-overlay/src/shape.rsindex 749ed5aed5..2ed42fb4a4 100644--- a/libs/cua-driver/rust/crates/cursor-overlay/src/shape.rs+++ b/libs/cua-driver/rust/crates/cursor-overlay/src/shape.rs@@ -1,10 +1,46 @@//! Custom cursor shape — rasterised from SVG / ICO / PNG.//!-//! Used when `--cursor-icon <path>` is passed to the MCP binary.-//! Always produces a 64×64 RGBA pixel buffer.+//! Used when `--cursor-icon <path>` is passed to the MCP binary, plus the+//! `teardrop()` built-in (`cursor-up` from svgrepo) selectable via+//! `--cursor-shape teardrop`. Always produces a 64×64 RGBA pixel buffer.use anyhow::{bail, Result};+/// Built-in cursor silhouette selectable via `--cursor-shape <name>`.+/// Used when no `--cursor-icon` custom file overrides the choice.+///+/// `Arrow` is the default until the teardrop's retina rasterisation is+/// fully sorted; users can opt into the SVG via `--cursor-shape teardrop`.+#[derive(Debug, Clone, Copy, PartialEq, Eq)]+pub enum BuiltinShape {+ /// Procedural gradient diamond drawn from vector primitives — the+ /// original cua cursor. Sharp at any backing scale because nothing is+ /// rasterised; `draw_default_arrow` rebuilds the path each frame.+ Arrow,+ /// Embedded `cursor-up` SVG (teardrop with notched bottom). Rasterised+ /// once into a 52 px RGBA buffer and blitted with a runtime transform.+ Teardrop,+}++impl BuiltinShape {+ /// Parse the value of `--cursor-shape`. Case-insensitive. Returns+ /// `None` for unknown names so the caller can warn and fall back to+ /// the default.+ pub fn parse(name: &str) -> Option<Self> {+ match name.to_ascii_lowercase().as_str() {+ "arrow" => Some(Self::Arrow),+ "teardrop" => Some(Self::Teardrop),+ _ => None,+ }+ }+}++impl Default for BuiltinShape {+ fn default() -> Self {+ Self::Arrow+ }+}+/// Rasterised cursor shape at 64×64 RGBA.#[derive(Debug, Clone)]pub struct CursorShape {@@ -14,7 +50,29 @@ pub struct CursorShape {pub height: u32,}-pub const CURSOR_SIZE: u32 = 64;+/// Source rasterisation size. Sized as 2× the runtime display target+/// (26 px in `paint_cursor`) so the downscale ratio stays a clean 2:1 —+/// bilinear handles that without smearing, and on 2× retina displays the+/// pixmap maps 1:1 to physical pixels for perfect crispness. Non-integer+/// ratios (e.g. 64→26 = 0.41×) produce visible downscale blur.+pub const CURSOR_SIZE: u32 = 52;++/// User-supplied "cursor-up" silhouette from svgrepo.com — an upward-pointing+/// teardrop with a notched bottom. Original fill was solid black; we substitute+/// the fleet linear gradient (light blue → teal, top-right to bottom-left) so+/// the runtime `gradient_colors` MCP override has a surface to tint, and add a+/// white stroke for visibility on dark backdrops. Embedded verbatim so the+/// daemon ships the built-in teardrop without an external asset.+const TEARDROP_CURSOR_SVG: &[u8] = br##"<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24">+<defs>+<linearGradient id="cursorGrad" x1="1" x2="0" y1="0" y2="1">+<stop offset="0" stop-color="#F0FBFF"/>+<stop offset="0.55" stop-color="#66D9FF"/>+<stop offset="1" stop-color="#35C6D8"/>+</linearGradient>+</defs>+<path d="M19.87,19.21l-6-15.92a2,2,0,0,0-3.74,0l-6,15.92a2,2,0,0,0,.65,2.3A2.21,2.21,0,0,0,6.17,22a2.24,2.24,0,0,0,1.23-.37L12,18.57l4.6,3.06a2.22,2.22,0,0,0,2.62-.12A2,2,0,0,0,19.87,19.21Z" fill="url(#cursorGrad)" stroke="#FFFFFF" stroke-width="1.5" stroke-linejoin="round" stroke-linecap="round"/>+</svg>"##;impl CursorShape {/// Load from `path`. Supported: `.svg`, `.ico`, `.png`.@@ -29,10 +87,26 @@ impl CursorShape {}}+ /// The built-in teardrop cursor — embedded `cursor-up` silhouette+ /// rasterised once via `OnceLock` so callers can ask for it cheaply.+ /// Selected at runtime by `BuiltinShape::Teardrop`; opt-in via+ /// `--cursor-shape teardrop`.+ pub fn teardrop() -> &'static Self {+ static CACHE: std::sync::OnceLock<CursorShape> = std::sync::OnceLock::new();+ CACHE.get_or_init(|| {+ Self::load_svg_bytes(TEARDROP_CURSOR_SVG)+ .expect("embedded teardrop SVG should parse")+ })+ }+fn load_svg(path: &str) -> Result<Self> {let data = std::fs::read(path)?;+ Self::load_svg_bytes(&data)+ }++ fn load_svg_bytes(data: &[u8]) -> Result<Self> {let opts = usvg::Options::default();- let tree = usvg::Tree::from_data(&data, &opts)?;+ let tree = usvg::Tree::from_data(data, &opts)?;let mut pixmap = tiny_skia::Pixmap::new(CURSOR_SIZE, CURSOR_SIZE).ok_or_else(|| anyhow::anyhow!("Failed to create {CURSOR_SIZE}×{CURSOR_SIZE} pixmap"))?;@@ -41,7 +115,6 @@ impl CursorShape {let sy = CURSOR_SIZE as f32 / tree.size().height();resvg::render(&tree, tiny_skia::Transform::from_scale(sx, sy), &mut pixmap.as_mut());- // tiny-skia gives pre-multiplied RGBA; un-premultiply for straight-alpha consumers.let raw = pixmap.take();let pixels = unpremultiply(raw);Ok(Self { pixels, width: CURSOR_SIZE, height: CURSOR_SIZE })@@ -76,3 +149,35 @@ fn unpremultiply(mut data: Vec<u8>) -> Vec<u8> {}data}++#[cfg(test)]+mod tests {+ use super::*;++ #[test]+ fn builtin_shape_parses_known_names_case_insensitive() {+ assert_eq!(BuiltinShape::parse("arrow"), Some(BuiltinShape::Arrow));+ assert_eq!(BuiltinShape::parse("ARROW"), Some(BuiltinShape::Arrow));+ assert_eq!(BuiltinShape::parse("Arrow"), Some(BuiltinShape::Arrow));+ assert_eq!(BuiltinShape::parse("teardrop"), Some(BuiltinShape::Teardrop));+ assert_eq!(BuiltinShape::parse("TEARDROP"), Some(BuiltinShape::Teardrop));+ assert_eq!(BuiltinShape::parse("Teardrop"), Some(BuiltinShape::Teardrop));+ }++ #[test]+ fn builtin_shape_rejects_unknown_names() {+ assert_eq!(BuiltinShape::parse(""), None);+ assert_eq!(BuiltinShape::parse("diamond"), None);+ assert_eq!(BuiltinShape::parse("arrow "), None); // whitespace-significant+ assert_eq!(BuiltinShape::parse("cua_brand"), None); // legacy name no longer recognised+ }++ /// The default is `Arrow` while the teardrop's retina rasterisation+ /// is still being tightened. If this assertion changes, the+ /// `personalize-cursor.mdx` doc must change to match — the doc+ /// explicitly tells users which built-in they get when no flag is set.+ #[test]+ fn default_builtin_shape_is_arrow() {+ assert_eq!(BuiltinShape::default(), BuiltinShape::Arrow);+ }+}diff --git a/libs/cua-driver/rust/crates/platform-linux/src/overlay.rs b/libs/cua-driver/rust/crates/platform-linux/src/overlay.rsindex 2ae7df7eba..5c8647472f 100644--- a/libs/cua-driver/rust/crates/platform-linux/src/overlay.rs+++ b/libs/cua-driver/rust/crates/platform-linux/src/overlay.rs@@ -427,7 +427,13 @@ fn run_overlay_thread(cfg: CursorConfig, rx: std::sync::mpsc::Receiver<OverlayMslet mut pm = tiny_skia::Pixmap::new(map.scr_w.max(1), map.scr_h.max(1)).unwrap_or_else(|| tiny_skia::Pixmap::new(1, 1).unwrap());for rs in map.cursors.values() {- cursor_overlay::paint_cursor(&mut pm, &rs.core, 0.0, 0.0, None);+ // TODO: thread X11/Wayland scale-factor here so cursors+ // render at native resolution on HiDPI Linux displays+ // (`XRRGetCrtcInfo` reports per-output DPI; the GNOME+ // scale-factor setting is exposed via the screen-scaling+ // protocol). For now we default to 1.0 — preserves+ // pre-retina-fix behaviour on Linux.+ cursor_overlay::paint_cursor(&mut pm, &rs.core, 0.0, 0.0, None, 1.0);}pm})diff --git a/libs/cua-driver/rust/crates/platform-macos/src/cursor/overlay.rs b/libs/cua-driver/rust/crates/platform-macos/src/cursor/overlay.rsindex 11f43b57f5..3da7561a6d 100644--- a/libs/cua-driver/rust/crates/platform-macos/src/cursor/overlay.rs+++ b/libs/cua-driver/rust/crates/platform-macos/src/cursor/overlay.rs@@ -83,6 +83,12 @@ struct RenderMap {cursors: IndexMap<CursorKey, RenderState>,win_w: f64,win_h: f64,+ /// `NSScreen.backingScaleFactor` of the screen the overlay window sits on.+ /// 1.0 on a non-retina display, 2.0 on a typical retina Mac. Drives the+ /// physical-pixel pixmap sizing + `paint_cursor` `backing_scale` so the+ /// rendered cursor is crisp at native resolution instead of being+ /// bilinear-upsampled by Core Animation from a logical-pixel buffer.+ backing_scale: f64,/// Frozen launch-time config used as the template for lazily-created/// cursors (its palette is overridden per-key via `Palette::for_instance`).template: CursorConfig,@@ -161,6 +167,7 @@ pub fn init(cfg: CursorConfig) {cursors,win_w: 0.0,win_h: 0.0,+ backing_scale: 1.0, // overwritten in run_appkit() once the NSScreen is knowntemplate: cfg,ended: std::collections::HashSet::new(),});@@ -497,6 +504,24 @@ unsafe fn run_appkit(_cfg: CursorConfig, rx: std::sync::mpsc::Receiver<OverlayMslet screen_frame: NSRect = msg_send![main_screen, frame];let win_w = screen_frame.size.width;let win_h = screen_frame.size.height;+ // NSScreen.backingScaleFactor is the most direct source of truth — it's+ // what AppKit will use for the layer's native backing surface anyway.+ // Fall back to the CG estimator (pixel mode width ÷ logical bounds) when+ // the AppKit call returns a non-positive value, since downstream paint+ // math divides by this and a 0.0 would zero out the cursor.+ let mut backing_scale: f64 = msg_send![main_screen, backingScaleFactor];+ if !(backing_scale > 0.0) {+ use core_graphics::display::{CGDisplayBounds, CGMainDisplayID};+ let display_id = CGMainDisplayID();+ let bounds = CGDisplayBounds(display_id);+ backing_scale = crate::tools::get_screen_size::get_backing_scale(+ display_id,+ bounds.size.width as i64,+ );+ if !(backing_scale > 0.0) {+ backing_scale = 1.0;+ }+ }// ---- NSWindow: single alloc + initWithContentRect:... ----let win: *mut AnyObject = {@@ -535,8 +560,12 @@ unsafe fn run_appkit(_cfg: CursorConfig, rx: std::sync::mpsc::Receiver<OverlayMslet _: () = msg_send![content_view, setWantsLayer: true];let layer: *mut AnyObject = msg_send![content_view, layer];- // Set layer geometry- let _: () = msg_send![layer, setContentsScale: 1.0_f64];+ // Set layer geometry. contentsScale tells Core Animation that the CGImage+ // we hand to setContents: is already at retina (`backing_scale`×) pixel+ // density — without this, CA would treat our physical-pixel pixmap as a+ // 1× asset and bilinear-downsample it back to logical pixels on screen,+ // re-introducing the blur this pipeline exists to eliminate.+ let _: () = msg_send![layer, setContentsScale: backing_scale];// kCAGravityTopLeft — the string literal "topLeft"let gravity_ns: *mut AnyObject = msg_send![class!(NSString),stringWithUTF8String: b"topLeft\0".as_ptr()@@ -549,6 +578,7 @@ unsafe fn run_appkit(_cfg: CursorConfig, rx: std::sync::mpsc::Receiver<OverlayMsif let Some(m) = guard.as_mut() {m.win_w = win_w;m.win_h = win_h;+ m.backing_scale = backing_scale;}}@@ -689,10 +719,17 @@ fn render_loop(let pixmap = {let guard = RENDER.lock().unwrap();if let Some(map) = guard.as_ref() {- let w = win_w.max(1.0) as u32;- let h = win_h.max(1.0) as u32;+ // Allocate the pixmap at the screen's PHYSICAL pixel+ // dimensions so the cursor rasterises at retina resolution.+ // The cursor's logical coordinates are scaled into pixmap+ // pixels inside `paint_cursor` (it multiplies px/py/sizes+ // by `backing_scale`).+ let scale = map.backing_scale.max(1.0);+ let w = (win_w * scale).max(1.0) as u32;+ let h = (win_h * scale).max(1.0) as u32;let mut pm = tiny_skia::Pixmap::new(w.max(1), h.max(1)).unwrap_or_else(|| tiny_skia::Pixmap::new(1, 1).unwrap());+ let backing_scale_f32 = scale as f32;for (_k, rs) in &map.cursors {let focus = rs.focus_rect.map(|rect| FocusRect {rect,@@ -702,6 +739,7 @@ fn render_loop(&mut pm, &rs.core, 0.0,0.0, // macOS uses screen-local coords (no origin offset)focus,+ backing_scale_f32,);}pm@@ -961,6 +999,7 @@ mod tests {cursors,win_w: 100.0,win_h: 100.0,+ backing_scale: 1.0,template: CursorConfig::default(),ended: std::collections::HashSet::new(),}diff --git a/libs/cua-driver/rust/crates/platform-macos/src/tools/get_screen_size.rs b/libs/cua-driver/rust/crates/platform-macos/src/tools/get_screen_size.rsindex 538cb604d1..5fa196c120 100644--- a/libs/cua-driver/rust/crates/platform-macos/src/tools/get_screen_size.rs+++ b/libs/cua-driver/rust/crates/platform-macos/src/tools/get_screen_size.rs@@ -66,7 +66,7 @@ fn main_screen_size() -> Option<(i64, i64, f64)> {/// Estimate backing scale by comparing the display's pixel mode width to its/// logical (CoreGraphics) bounds width.-fn get_backing_scale(display_id: u32, logical_w: i64) -> f64 {+pub(crate) fn get_backing_scale(display_id: u32, logical_w: i64) -> f64 {use core_graphics::display::CGDisplayPixelsWide;let pixel_w = unsafe { CGDisplayPixelsWide(display_id) } as i64;if pixel_w > 0 && logical_w > 0 {diff --git a/libs/cua-driver/rust/crates/platform-macos/src/tools/mod.rs b/libs/cua-driver/rust/crates/platform-macos/src/tools/mod.rsindex cb5b81c558..c2634540b8 100644--- a/libs/cua-driver/rust/crates/platform-macos/src/tools/mod.rs+++ b/libs/cua-driver/rust/crates/platform-macos/src/tools/mod.rs@@ -20,7 +20,7 @@ mod scroll;// path. The capture functions they wrapped (ScreenCaptureKit, CGWindow,// etc.) live elsewhere under CuaDriverCore::Capture and are reached// through GetWindowStateTool.-mod get_screen_size;+pub(crate) mod get_screen_size;mod get_cursor_position;mod move_cursor;mod cursor_tools;diff --git a/libs/cua-driver/rust/crates/platform-windows/src/overlay.rs b/libs/cua-driver/rust/crates/platform-windows/src/overlay.rsindex c7b8c2cdf5..c1232af4d2 100644--- a/libs/cua-driver/rust/crates/platform-windows/src/overlay.rs+++ b/libs/cua-driver/rust/crates/platform-windows/src/overlay.rs@@ -781,12 +781,18 @@ unsafe extern "system" fn wnd_proc(let mut pm = tiny_skia::Pixmap::new(w.max(1), h.max(1)).unwrap_or_else(|| tiny_skia::Pixmap::new(1, 1).unwrap());for (_k, rs) in &map.cursors {+ // TODO: thread `GetDpiForWindow` / per-monitor+ // DPI awareness here so cursors render crisp on+ // HiDPI Windows displays. For now we default to+ // 1.0 — preserves pre-retina-fix behaviour on+ // Windows.cursor_overlay::paint_cursor(&mut pm,&rs.core,map.virt_x as f64,map.virt_y as f64,None, // focus-rect is macOS-only+ 1.0,);}