feat: colour the cursor with the accent unless a fill is set

- Draw the cursor body in the accent colour by default, so one `--accent` colours the whole cursor
- Keep `--fill` for a body colour other than the accent, and leave it out of the style when unset
- Update the help, docs and skill that described a white default

Author: ctate

apps/docs/content/docs/commands/system.mdx

@@ -129,7 +129,8 @@ agent-desktop --session "$AGENT_DESKTOP_SESSION" cursor-overlay disable
   <tbody>
     <tr><td><code>--multi-agent</code></td><td>off</td><td>Require an agent id for desktop actions. Rejected together with <code>--agent-id</code>.</td></tr>
     <tr><td><code>--label TEXT</code>, <code>--max-words N</code></td><td>none, <code>6</code></td><td>Intent text beside the cursor, limited to 1 to 12 words, drawn as a black pill sized to the text.</td></tr>
-    <tr><td><code>--fill HEX</code>, <code>--rim HEX</code>, <code>--accent HEX</code></td><td><code>#FFFFFF</code>, <code>#111318</code>, <code>#4299FF</code></td><td>Cursor body, outline, and ripple colors.</td></tr>
+    <tr><td><code>--accent HEX</code></td><td><code>#4299FF</code></td><td>Cursor body, ripple, element outline and caret color.</td></tr>
+    <tr><td><code>--fill HEX</code>, <code>--rim HEX</code></td><td>the accent, <code>#111318</code></td><td>Cursor body and outline colors. <code>--fill</code> sets a body color other than the accent.</td></tr>
     <tr><td><code>--size N</code></td><td><code>1.0</code></td><td>Size multiplier, 0.5 to 4.0.</td></tr>
     <tr><td><code>--no-ripple</code>, <code>--no-highlight</code></td><td>off</td><td>Turn off the click ripple or the element outline.</td></tr>
     <tr><td><code>--image PATH</code>, <code>--hotspot X,Y</code></td><td>built-in arrow</td><td>Draw the cursor from a PNG (at most 2 MiB and 1024 pixels per side) with its click point.</td></tr>
@@ -151,7 +152,7 @@ agent-desktop --session "$AGENT_DESKTOP_SESSION" cursor-overlay disable
     "cursor_overlay": {
       "enabled": true,
       "max_words": 6,
-      "style": { "accent": "#4299FF", "fill": "#FFFFFF", "highlight": true, "rim": "#111318", "ripple": true, "size": 1.0 }
+      "style": { "accent": "#4299FF", "highlight": true, "rim": "#111318", "ripple": true, "size": 1.0 }
     },
     "next": "export AGENT_DESKTOP_SESSION=run-1793353372413-23159-0",
     "rendered": true,

crates/core/src/cursor_overlay/image_tests.rs

@@ -326,3 +326,15 @@ fn fifo_image_is_rejected_promptly() {
     assert_eq!(error.code, crate::ErrorCode::InvalidArgs);
     assert!(error.message.contains("not a regular file"));
 }
+
+#[test]
+fn the_cursor_body_takes_the_accent_unless_a_fill_is_set() {
+    let mut style = CursorOverlayStyle::default();
+    style.set_accent("#FF8000".into());
+    assert_eq!(style.fill_rgb(), style.accent_rgb());
+    assert!(!serde_json::to_string(&style).unwrap().contains("fill"));
+    style.set_fill("#FFFFFF".into());
+    assert_eq!(style.fill_rgb(), [1.0, 1.0, 1.0]);
+    let parsed: CursorOverlayStyle = serde_json::from_str(r##"{"accent":"#FF8000"}"##).unwrap();
+    assert_eq!(parsed.fill_rgb(), parsed.accent_rgb());
+}

crates/core/src/cursor_overlay/style.rs

@@ -2,7 +2,6 @@ use super::{CursorImage, CursorImages};
 use crate::{AdapterError, ErrorCode};
 use serde::{Deserialize, Serialize};
 
-const DEFAULT_FILL: &str = "#FFFFFF";
 const DEFAULT_RIM: &str = "#111318";
 const DEFAULT_ACCENT: &str = "#4299FF";
 const MIN_SIZE: f64 = 0.5;
@@ -11,8 +10,10 @@ const MAX_SIZE: f64 = 4.0;
 #[derive(Debug, Clone, Deserialize, PartialEq, Serialize)]
 #[serde(deny_unknown_fields)]
 pub struct CursorOverlayStyle {
-    #[serde(default = "default_fill")]
-    fill: String,
+    /// The cursor body's colour; without one it takes the accent, so a single
+    /// `--accent` colours the whole cursor.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    fill: Option<String>,
     #[serde(default = "default_rim")]
     rim: String,
     #[serde(default = "default_accent")]
@@ -33,7 +34,10 @@ impl CursorOverlayStyle {
     }
 
     pub fn validated(mut self) -> Result<Self, AdapterError> {
-        for color in [&self.fill, &self.rim, &self.accent] {
+        for color in [self.fill.as_ref(), Some(&self.rim), Some(&self.accent)]
+            .into_iter()
+            .flatten()
+        {
             rgb(color).ok_or_else(|| {
                 AdapterError::new(
                     ErrorCode::InvalidArgs,
@@ -52,7 +56,7 @@ impl CursorOverlayStyle {
     }
 
     pub fn set_fill(&mut self, fill: String) {
-        self.fill = fill;
+        self.fill = Some(fill);
     }
 
     pub fn set_rim(&mut self, rim: String) {
@@ -93,7 +97,10 @@ impl CursorOverlayStyle {
     }
 
     pub fn fill_rgb(&self) -> [f64; 3] {
-        rgb(&self.fill).unwrap_or([1.0, 1.0, 1.0])
+        self.fill
+            .as_deref()
+            .and_then(rgb)
+            .unwrap_or_else(|| self.accent_rgb())
     }
 
     pub fn rim_rgb(&self) -> [f64; 3] {
@@ -120,7 +127,7 @@ impl CursorOverlayStyle {
 impl Default for CursorOverlayStyle {
     fn default() -> Self {
         Self {
-            fill: default_fill(),
+            fill: None,
             rim: default_rim(),
             accent: default_accent(),
             size: default_size(),
@@ -131,10 +138,6 @@ impl Default for CursorOverlayStyle {
     }
 }
 
-fn default_fill() -> String {
-    DEFAULT_FILL.into()
-}
-
 fn default_rim() -> String {
     DEFAULT_RIM.into()
 }

skills/agent-desktop/references/commands-system.md

@@ -194,6 +194,7 @@ On macOS:
 On macOS and Windows:
 
 - The label is a black pill with white text in the system font (SF Pro on macOS, Segoe UI on Windows), sized to the text and set below and right of the cursor's tip. A label wider than 360 pt is cut with an ellipsis, and an empty label shows no pill.
+- `--accent` colours the cursor body as well as the ripple, the element outline and the caret; `--fill` gives the body a different colour.
 - `--image` and `--pointer-image` take a PNG of at most 2 MiB and 1024 pixels per side, drawn at `--size` with the hotspot on the point the cursor targets. Relative paths resolve at `enable`. `--fill` and `--rim` conflict with `--image`. A missing or invalid image falls back to the arrow. With `--image`, `enable` draws no greeting.
 - The pointer image shows on arrival at a pressable control. Text fields keep the arrow.
 

src/cli_args/cursor_overlay_style.rs

@@ -6,7 +6,7 @@ pub(crate) struct CursorOverlayStyleArgs {
     #[arg(
         long,
         conflicts_with = "image",
-        help = "Cursor body colour as a hex value (default #FFFFFF)"
+        help = "Cursor body colour as a hex value (default: the accent colour)"
     )]
     pub fill: Option<String>,
     #[arg(
@@ -17,7 +17,7 @@ pub(crate) struct CursorOverlayStyleArgs {
     pub rim: Option<String>,
     #[arg(
         long,
-        help = "Ripple and element highlight colour as a hex value (default #4299FF)"
+        help = "Cursor, ripple and element highlight colour as a hex value (default #4299FF)"
     )]
     pub accent: Option<String>,
     #[arg(long, help = "Cursor size multiplier from 0.5 to 4.0 (default 1.0)")]