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 style customization (color, image/SVG) via Swift API and MCP tool (#1412)
ddupont01d4cc23b366
diff --git a/docs/content/docs/cua-driver/guide/getting-started/swift-integration.mdx b/docs/content/docs/cua-driver/guide/getting-started/swift-integration.mdxindex 36019a9a18..e5e981ddfe 100644--- a/docs/content/docs/cua-driver/guide/getting-started/swift-integration.mdx+++ b/docs/content/docs/cua-driver/guide/getting-started/swift-integration.mdx@@ -96,3 +96,56 @@ Calling AX or screen-capture APIs from an embedded library still requires the ho- **Screen Recording** — for `WindowCapture` screenshots.Grant these under **System Settings → Privacy & Security** against your app's bundle identifier, the same as for the standalone `CuaDriver.app`.++## Cursor customization++`AgentCursorRenderer.shared` drives the visual style applied to every click animation. Set it at app startup from the `@MainActor` context — changes take effect on the next rendered frame.++### Custom gradient colors++```swift+import CuaDriverCore++await MainActor.run {+ AgentCursorRenderer.shared.style = AgentCursorStyle(+ strokeGradientStops: [+ AgentCursorGradientStop(color: NSColor(hex: "#A855F7")!, location: 0),+ AgentCursorGradientStop(color: NSColor(hex: "#6366F1")!, location: 1),+ ],+ bloomColor: NSColor(hex: "#A855F7")!+ )+}+```++### Custom PNG / SVG cursor image++Replace the default arrow with any image `NSImage` can load (PNG, JPEG, PDF, SVG on macOS 12+):++```swift+import CuaDriverCore++await MainActor.run {+ let img = NSImage(contentsOf: Bundle.main.url(forResource: "cursor", withExtension: "png")!)+ AgentCursorRenderer.shared.style = AgentCursorStyle(image: img)+}+```++The image is drawn at `shapeSize × shapeSize` points (default 22 pt), centered on the cursor position and rotated to track the motion heading. To suppress the bloom halo behind it, pass `bloomCenterAlpha: 0`.++### Revert to default++```swift+await MainActor.run {+ AgentCursorRenderer.shared.style = .default+}+```++### All style knobs++| Parameter | Type | Default | Description |+|---|---|---|---|+| `image` | `NSImage?` | `nil` | Custom cursor image (replaces arrow when non-nil) |+| `strokeGradientStops` | `[AgentCursorGradientStop]` | ice-blue → cyan → mint | Arrow fill gradient |+| `bloomColor` | `NSColor` | cyan `#5EC0E8` | Bloom halo and focus-rect color |+| `bloomCenterAlpha` | `CGFloat` | `0.55` | Center opacity of the bloom glow |+| `shapeSize` | `CGFloat` | `22` | Width and height of the cursor shape (points) |diff --git a/docs/content/docs/cua-driver/reference/mcp-tools.mdx b/docs/content/docs/cua-driver/reference/mcp-tools.mdxindex ccec23346e..0b19c1f3b7 100644--- a/docs/content/docs/cua-driver/reference/mcp-tools.mdx+++ b/docs/content/docs/cua-driver/reference/mcp-tools.mdx@@ -388,6 +388,22 @@ Toggle the overlay. Persists to config.Tune the Bezier-arc + spring motion knobs. All fields are optional; omitted fields keep their current value.+### set_agent_cursor_style++Customize the cursor's visual appearance. All fields optional; omitted fields keep their current value. Changes persist to config across restarts.++**Arguments:**++- `gradient_colors` (array of string, optional): CSS hex color strings (`#RRGGBB` or `#RGB`) defining the arrow fill gradient from tip to tail. Pass an empty array `[]` to revert to the default.+- `bloom_color` (string, optional): CSS hex color for the bloom halo and the focus-rect highlight around clicked elements. Pass `""` to revert.+- `image_path` (string, optional): Absolute or `~`-rooted path to a PNG, JPEG, PDF, or SVG file. When set, replaces the default procedural arrow. Pass `""` to revert to the arrow.++```json+{"gradient_colors": ["#A855F7", "#6366F1"], "bloom_color": "#A855F7"}+{"image_path": "~/cursors/my-cursor.png"}+{"gradient_colors": [], "bloom_color": "", "image_path": ""}+```+**Arguments:**- `start_handle` (number, optional): Start-handle fraction in [0, 1]. Default 0.3.diff --git a/libs/cua-driver/Sources/CuaDriverCore/Config/CuaDriverConfig.swift b/libs/cua-driver/Sources/CuaDriverCore/Config/CuaDriverConfig.swiftindex 963f123905..f104a61566 100644--- a/libs/cua-driver/Sources/CuaDriverCore/Config/CuaDriverConfig.swift+++ b/libs/cua-driver/Sources/CuaDriverCore/Config/CuaDriverConfig.swift@@ -191,6 +191,10 @@ public struct AgentCursorConfig: Codable, Sendable, Equatable {/// five sibling fields fighting for space with `enabled`.public var motion: Motion+ /// Persisted cursor style overrides. Applied to `AgentCursorRenderer.shared`+ /// at daemon startup via `AgentCursor.shared.apply(config:)`.+ public var style: Style+public struct Motion: Codable, Sendable, Equatable {/// Start-handle fraction along the straight line, in `[0, 1]`.public var startHandle: Double@@ -220,12 +224,55 @@ public struct AgentCursorConfig: Codable, Sendable, Equatable {public static let `default` = Motion()}+ /// Persisted visual style overrides. Only non-nil fields are applied;+ /// nil fields fall back to `AgentCursorStyle.default`.+ public struct Style: Codable, Sendable, Equatable {+ /// Gradient color stops as CSS hex strings (#RRGGBB / #RGB).+ /// When set, replaces the default ice-blue→cyan→mint gradient.+ public var gradientColors: [String]?++ /// Bloom halo color as a CSS hex string. When set, also tints the+ /// focus-rect highlight drawn around clicked AX elements.+ public var bloomColor: String?++ /// Absolute or `~`-rooted path to a PNG, JPEG, PDF, or SVG file+ /// that replaces the default procedural arrow shape.+ public var imagePath: String?++ public init(+ gradientColors: [String]? = nil,+ bloomColor: String? = nil,+ imagePath: String? = nil+ ) {+ self.gradientColors = gradientColors+ self.bloomColor = bloomColor+ self.imagePath = imagePath+ }++ public static let `default` = Style()+ }++ private enum CodingKeys: String, CodingKey {+ case enabled+ case motion+ case style+ }+public init(enabled: Bool = true,- motion: Motion = .default+ motion: Motion = .default,+ style: Style = .default) {self.enabled = enabledself.motion = motion+ self.style = style+ }++ public init(from decoder: Decoder) throws {+ let container = try decoder.container(keyedBy: CodingKeys.self)+ self.enabled = (try? container.decode(Bool.self, forKey: .enabled)) ?? true+ self.motion = (try? container.decode(Motion.self, forKey: .motion)) ?? .default+ self.style = (try? container.decode(Style.self, forKey: .style)) ?? .default}public static let `default` = AgentCursorConfig()diff --git a/libs/cua-driver/Sources/CuaDriverCore/Cursor/AgentCursor.swift b/libs/cua-driver/Sources/CuaDriverCore/Cursor/AgentCursor.swiftindex 937ee984cd..c73ac7ecf8 100644--- a/libs/cua-driver/Sources/CuaDriverCore/Cursor/AgentCursor.swift+++ b/libs/cua-driver/Sources/CuaDriverCore/Cursor/AgentCursor.swift@@ -5,7 +5,7 @@ import SwiftUI/// Named color stop for the agent-cursor's axial stroke gradient./// Pairing color + location keeps the spec's lavender stops grep-able/// in one place — touch these values to retint the pointer.-public struct AgentCursorGradientStop: Sendable {+public struct AgentCursorGradientStop: @unchecked Sendable {public let color: NSColorpublic let location: CGFloatpublic init(color: NSColor, location: CGFloat) {@@ -14,53 +14,72 @@ public struct AgentCursorGradientStop: Sendable {}}-/// Visual constants for the agent cursor — shape sizing, gradient-/// stops, bloom falloff, stroke widths. Hard-coded and grep-able per-/// the design spec (see `docs/_local/agent-cursor-redesign.md`). Not-/// exposed via `set_agent_cursor_motion`; a separate-/// `set_agent_cursor_style` tool can land later if per-session theming-/// becomes a real ask.-public struct AgentCursorStyle: Sendable {- /// Container layer size. Grew 25pt → 60pt to hold the bloom- /// without clipping. Window frame is unchanged — the container is- /// visual only, no hit-test implication.+/// Visual constants for the agent cursor — shape sizing, gradient stops,+/// bloom falloff, stroke widths, and an optional custom image.+///+/// ## Custom cursor image+///+/// Set `image` to an `NSImage` (PNG, JPEG, PDF, or SVG loaded via+/// `NSImage(contentsOf:)`) to replace the default procedural arrow with+/// your own graphic. The image is drawn at `shapeSize × shapeSize` points,+/// rotated to track the motion heading. The bloom halo is still rendered+/// underneath — set `bloomCenterAlpha: 0` to suppress it.+///+/// ## Custom colors+///+/// Override `strokeGradientStops` to change the arrow fill, and+/// `bloomColor` / `bloomCenterAlpha` to change the glow hue. Parse hex+/// strings with `NSColor(hex:)`.+///+/// ## `@unchecked Sendable`+///+/// NSColor and NSImage are reference types without formal Sendable+/// conformance in Swift 6. All fields are `let` (immutable after init),+/// so concurrent reads are safe — hence `@unchecked`.+public struct AgentCursorStyle: @unchecked Sendable {+ /// Container layer size (points). Default 60.public let containerSize: CGFloat- /// Rounded-arrow shape size (tip-to-base). Unchanged from the- /// previous triangle: 15pt reads as a cursor tip without feeling- /// chunky.+ /// Drawn size of the cursor shape (points). Default 22.public let shapeSize: CGFloat- /// Axial stroke gradient — lavender family. 135° rotation (set via- /// `strokeGradientAngleDegrees`) puts the near-white stop at the- /// top-left (tip) and the indigo stop at the bottom-right (tail).+ /// Axial stroke gradient stops for the procedural arrow. Ignored when+ /// `image` is set.public let strokeGradientStops: [AgentCursorGradientStop]public let strokeGradientAngleDegrees: CGFloatpublic let strokeWidth: CGFloatpublic let highlightStrokeWidth: CGFloat- /// Lavender bloom — single radial `CAGradientLayer` below the- /// stroke. The hex stays constant; the envelope is an opacity- /// curve. `bloomCenterAlpha` is the resting center alpha;- /// `bloomBreathPeak` is the max the glide animation breathes up- /// to. `bloomMidAlpha` is the alpha at the 50% color-stop.+ /// Bloom halo color. Also used for the focus-rect highlight.public let bloomColor: NSColorpublic let bloomCenterAlpha: CGFloatpublic let bloomMidAlpha: CGFloatpublic let bloomBreathPeak: CGFloat+ /// Optional custom cursor image. When non-nil, the procedural arrow+ /// is replaced by this image rendered at `shapeSize × shapeSize`+ /// points, rotated to track the motion heading. Accepts any format+ /// NSImage can load: PNG, JPEG, PDF, SVG (macOS 12+).+ ///+ /// Load from a file path:+ /// ```swift+ /// AgentCursorStyle(image: NSImage(contentsOf: URL(fileURLWithPath: "/path/to/cursor.png")))+ /// ```+ public let image: NSImage?+public init(- containerSize: CGFloat,- shapeSize: CGFloat,- strokeGradientStops: [AgentCursorGradientStop],- strokeGradientAngleDegrees: CGFloat,- strokeWidth: CGFloat,- highlightStrokeWidth: CGFloat,- bloomColor: NSColor,- bloomCenterAlpha: CGFloat,- bloomMidAlpha: CGFloat,- bloomBreathPeak: CGFloat+ containerSize: CGFloat = 60,+ shapeSize: CGFloat = 22,+ strokeGradientStops: [AgentCursorGradientStop] = AgentCursorStyle.defaultGradientStops,+ strokeGradientAngleDegrees: CGFloat = 135,+ strokeWidth: CGFloat = 2,+ highlightStrokeWidth: CGFloat = 0.5,+ bloomColor: NSColor = NSColor(red: 0x5E / 255, green: 0xC0 / 255, blue: 0xE8 / 255, alpha: 1),+ bloomCenterAlpha: CGFloat = 0.55,+ bloomMidAlpha: CGFloat = 0.15,+ bloomBreathPeak: CGFloat = 0.75,+ image: NSImage? = nil) {self.containerSize = containerSizeself.shapeSize = shapeSize@@ -72,49 +91,60 @@ public struct AgentCursorStyle: Sendable {self.bloomCenterAlpha = bloomCenterAlphaself.bloomMidAlpha = bloomMidAlphaself.bloomBreathPeak = bloomBreathPeak+ self.image = image}- /// The single locked-in style. Values per the design spec. Edit- /// these to retint / resize the pointer — no other call sites- /// should be reading them directly.- public static let `default` = AgentCursorStyle(- containerSize: 60,- // SVG content fills ~18/24 of the shape frame (has built-in- // padding), so the effective drawn size is 75% of `shapeSize`.- // 22pt gives a visible cursor around 16-17pt — comparable to the- // macOS system cursor.- shapeSize: 22,- // cua-driver heritage gradient: ice-blue tip → cyan body → mint- // tail. Axial 135° (from upper-left to lower-right) traces the- // cursor's own tip-to-tail axis, so the tip reads brightest.- strokeGradientStops: [- AgentCursorGradientStop(- color: NSColor(red: 0xDB / 255, green: 0xEE / 255, blue: 0xFF / 255, alpha: 1),- location: 0.0- ),- AgentCursorGradientStop(- color: NSColor(red: 0x5E / 255, green: 0xC0 / 255, blue: 0xE8 / 255, alpha: 1),- location: 0.53- ),- AgentCursorGradientStop(- color: NSColor(red: 0x54 / 255, green: 0xCD / 255, blue: 0xA0 / 255, alpha: 1),- location: 1.0- ),- ],- strokeGradientAngleDegrees: 135,- // 2pt white outline wraps the gradient-filled shape. Highlight- // stroke field is retained in the style struct for back-compat- // but not used by the current renderer (the layer tree has- // gradient-fill + white-border, no separate highlight stroke).- strokeWidth: 2,- highlightStrokeWidth: 0.5,- // Bloom matches the gradient's mid stop (cyan) so the halo reads- // as the cursor "exhaling color" rather than an unrelated hue.- bloomColor: NSColor(red: 0x5E / 255, green: 0xC0 / 255, blue: 0xE8 / 255, alpha: 1),- bloomCenterAlpha: 0.55,- bloomMidAlpha: 0.15,- bloomBreathPeak: 0.75- )+ // cua-driver heritage gradient: ice-blue tip → cyan body → mint tail.+ public static let defaultGradientStops: [AgentCursorGradientStop] = [+ AgentCursorGradientStop(+ color: NSColor(red: 0xDB / 255, green: 0xEE / 255, blue: 0xFF / 255, alpha: 1),+ location: 0.0+ ),+ AgentCursorGradientStop(+ color: NSColor(red: 0x5E / 255, green: 0xC0 / 255, blue: 0xE8 / 255, alpha: 1),+ location: 0.53+ ),+ AgentCursorGradientStop(+ color: NSColor(red: 0x54 / 255, green: 0xCD / 255, blue: 0xA0 / 255, alpha: 1),+ location: 1.0+ ),+ ]++ public static let `default` = AgentCursorStyle()+}++// MARK: - NSColor hex parsing++extension NSColor {+ /// Parse a CSS hex color string: `#RGB`, `#RRGGBB`, or `#RRGGBBAA`.+ /// Returns nil when the string is not a valid hex color.+ public convenience init?(hex: String) {+ var str = hex.trimmingCharacters(in: .whitespaces)+ if str.hasPrefix("#") { str = String(str.dropFirst()) }+ if str.count == 3 {+ str = str.map { "\($0)\($0)" }.joined()+ }+ var value: UInt64 = 0+ guard Scanner(string: str).scanHexInt64(&value) else { return nil }+ switch str.count {+ case 6:+ self.init(+ red: CGFloat((value >> 16) & 0xFF) / 255,+ green: CGFloat((value >> 8) & 0xFF) / 255,+ blue: CGFloat(value & 0xFF) / 255,+ alpha: 1+ )+ case 8:+ self.init(+ red: CGFloat((value >> 24) & 0xFF) / 255,+ green: CGFloat((value >> 16) & 0xFF) / 255,+ blue: CGFloat((value >> 8) & 0xFF) / 255,+ alpha: CGFloat(value & 0xFF) / 255+ )+ default:+ return nil+ }+ }}/// The agent cursor overlay — a purely visual floating arrow that@@ -273,6 +303,39 @@ public final class AgentCursor {arcFlow: CGFloat(config.motion.arcFlow),spring: CGFloat(config.motion.spring))+ applyStyleConfig(config.style)+ }++ /// Apply a custom visual style to the cursor overlay. Takes effect+ /// immediately — the next rendered frame picks up the new style.+ /// Swift dep users call this directly; MCP users go through+ /// `set_agent_cursor_style`.+ public func setStyle(_ style: AgentCursorStyle) {+ AgentCursorRenderer.shared.style = style+ }++ public func applyStyleConfig(_ styleConfig: AgentCursorConfig.Style) {+ let gradientStops: [AgentCursorGradientStop]+ if let hexColors = styleConfig.gradientColors, !hexColors.isEmpty {+ gradientStops = hexColors.enumerated().compactMap { i, hex -> AgentCursorGradientStop? in+ guard let color = NSColor(hex: hex) else { return nil }+ let loc = CGFloat(i) / CGFloat(max(hexColors.count - 1, 1))+ return AgentCursorGradientStop(color: color, location: loc)+ }+ } else {+ gradientStops = AgentCursorStyle.defaultGradientStops+ }+ let bloomColor = styleConfig.bloomColor.flatMap { NSColor(hex: $0) }+ ?? NSColor(red: 0x5E / 255, green: 0xC0 / 255, blue: 0xE8 / 255, alpha: 1)+ var nsImage: NSImage? = nil+ if let path = styleConfig.imagePath {+ nsImage = NSImage(contentsOf: URL(fileURLWithPath: (path as NSString).expandingTildeInPath))+ }+ setStyle(AgentCursorStyle(+ strokeGradientStops: gradientStops,+ bloomColor: bloomColor,+ image: nsImage+ ))}/// Show the overlay window. Idempotent — successive calls arediff --git a/libs/cua-driver/Sources/CuaDriverCore/Cursor/AgentCursorRenderer.swift b/libs/cua-driver/Sources/CuaDriverCore/Cursor/AgentCursorRenderer.swiftindex 453bf6a50c..db24f285e7 100644--- a/libs/cua-driver/Sources/CuaDriverCore/Cursor/AgentCursorRenderer.swift+++ b/libs/cua-driver/Sources/CuaDriverCore/Cursor/AgentCursorRenderer.swift@@ -56,6 +56,11 @@ public final class AgentCursorRenderer {/// Nil when no element is targeted or the cursor is hidden.public var focusRect: CGRect? = nil+ /// Visual style applied to the cursor overlay. Changing this property+ /// takes effect on the next rendered frame — `AgentCursorView` reads+ /// it via `@Observable`. Set via `AgentCursor.shared.setStyle(_:)`.+ public var style: AgentCursorStyle = .default+// -------- Internal state ---------------------------------------------private var path: PlannedPath?diff --git a/libs/cua-driver/Sources/CuaDriverCore/Cursor/AgentCursorView.swift b/libs/cua-driver/Sources/CuaDriverCore/Cursor/AgentCursorView.swiftindex e2dbf13e2d..b02d972c16 100644--- a/libs/cua-driver/Sources/CuaDriverCore/Cursor/AgentCursorView.swift+++ b/libs/cua-driver/Sources/CuaDriverCore/Cursor/AgentCursorView.swift@@ -28,16 +28,11 @@ public struct AgentCursorView: View {}/// Draw a glowing highlight rectangle around the currently targeted AX- /// element (if `renderer.focusRect` is set). The rect is in screen-point- /// coordinates; the overlay window's frame is the full screen, so we- /// convert from screen-point to canvas-local by subtracting the screen's- /// origin. Uses a cyan-glow border with a faint fill to mark the target.+ /// element (if `renderer.focusRect` is set). Color is derived from the+ /// current cursor style's bloom color so the focus rect always matches+ /// the cursor's visual identity.private func drawFocusRect(in ctx: GraphicsContext, canvasSize: CGSize) {guard let screenRect = renderer.focusRect else { return }- // The overlay window covers the whole screen, and the canvas's- // coordinate origin is the top-left of the screen. Screen-point- // coordinates (CoreGraphics, top-left origin on macOS) map- // directly to canvas coordinates — no offset needed.let r = CGRect(x: screenRect.minX,y: screenRect.minY,@@ -46,92 +41,77 @@ public struct AgentCursorView: View {)let cornerRadius: CGFloat = 4let rounded = Path(roundedRect: r, cornerRadius: cornerRadius)+ let baseColor = Color(nsColor: renderer.style.bloomColor)- // Faint fill — shows the full extent of the target.- ctx.fill(- rounded,- with: .color(- Color(red: 0x5E/255, green: 0xC0/255, blue: 0xE8/255).opacity(0.08)- )- )-- // Solid bright border.- ctx.stroke(- rounded,- with: .color(- Color(red: 0x5E/255, green: 0xC0/255, blue: 0xE8/255).opacity(0.90)- ),- lineWidth: 2- )-- // Wide soft glow stroke for the neon halo effect.- ctx.stroke(- rounded,- with: .color(- Color(red: 0x5E/255, green: 0xC0/255, blue: 0xE8/255).opacity(0.30)- ),- lineWidth: 8- )+ ctx.fill(rounded, with: .color(baseColor.opacity(0.08)))+ ctx.stroke(rounded, with: .color(baseColor.opacity(0.90)), lineWidth: 2)+ ctx.stroke(rounded, with: .color(baseColor.opacity(0.30)), lineWidth: 8)}- /// Draw the cursor arrow centered on `renderer.position`, rotated to- /// `renderer.heading`. The shape is a 4-vertex pointer arrow with- /// the tip along +x before rotation, which the caller rotates by- /// `heading + π` (so the visible tip trails opposite the motion- /// vector — matching macOS cursor convention).+ /// Draw the cursor centered on `renderer.position`, rotated to+ /// `renderer.heading`. When `renderer.style.image` is set, draws that+ /// image instead of the default gradient arrow.private func drawCursor(in ctx: GraphicsContext) {let p = renderer.positionguard p.x > -100 else { return } // skip until first moveTo- // Arrow path — tip at (14, 0), tail extends to the left.- var shape = Path()- shape.move(to: CGPoint(x: 14, y: 0))- shape.addLine(to: CGPoint(x: -8, y: -9))- shape.addLine(to: CGPoint(x: -3, y: 0))- shape.addLine(to: CGPoint(x: -8, y: 9))- shape.closeSubpath()-- // `renderer.heading` is the visual heading = motion_direction + π.- // The arrow path has its tip at +x, so we rotate by heading + π- // to make the tip point in the motion direction (standard cursor- // convention where the pointer leads rather than trails).- let transform = CGAffineTransform(translationX: p.x, y: p.y)- .rotated(by: CGFloat(renderer.heading + .pi))-- let transformed = shape.applying(transform)-- // Ice-blue gradient fill (matches existing agent-cursor palette).- ctx.fill(- transformed,- with: .linearGradient(- Gradient(colors: [- Color(red: 0xDB/255, green: 0xEE/255, blue: 0xFF/255),- Color(red: 0x5E/255, green: 0xC0/255, blue: 0xE8/255),- Color(red: 0x54/255, green: 0xCD/255, blue: 0xA0/255),- ]),- startPoint: CGPoint(x: p.x + 14, y: p.y - 9),- endPoint: CGPoint(x: p.x - 8, y: p.y + 9)- )- )- // White outline for legibility on any background.- ctx.stroke(transformed, with: .color(.white), lineWidth: 1.5)-- // Cyan bloom halo — radial glow that reads as agent presence.+ let style = renderer.style+ let bloomColor = Color(nsColor: style.bloomColor)let bloomR: CGFloat = 22let bloomRect = CGRect(x: p.x - bloomR, y: p.y - bloomR,width: bloomR * 2, height: bloomR * 2)++ // Bloom halo — drawn first (underneath) regardless of cursor mode.ctx.fill(Path(ellipseIn: bloomRect),with: .radialGradient(Gradient(colors: [- Color(red: 0x5E/255, green: 0xC0/255, blue: 0xE8/255).opacity(0.45),- Color(red: 0x5E/255, green: 0xC0/255, blue: 0xE8/255).opacity(0.10),- Color(red: 0x5E/255, green: 0xC0/255, blue: 0xE8/255).opacity(0.0),+ bloomColor.opacity(style.bloomCenterAlpha),+ bloomColor.opacity(style.bloomMidAlpha),+ bloomColor.opacity(0),]),center: p,startRadius: 0,endRadius: bloomR))++ if let nsImage = style.image {+ // Custom image mode: draw the image centered on `p`, rotated+ // to heading. GraphicsContext is a value type — copy before+ // applying the transform so the bloom above is unaffected.+ var imgCtx = ctx+ imgCtx.translateBy(x: p.x, y: p.y)+ imgCtx.rotate(by: Angle(radians: renderer.heading + .pi))+ let s = style.shapeSize+ imgCtx.draw(Image(nsImage: nsImage),+ in: CGRect(x: -s / 2, y: -s / 2, width: s, height: s))+ } else {+ // Procedural arrow mode: 4-vertex pointer shape with gradient fill.+ var shape = Path()+ shape.move(to: CGPoint(x: 14, y: 0))+ shape.addLine(to: CGPoint(x: -8, y: -9))+ shape.addLine(to: CGPoint(x: -3, y: 0))+ shape.addLine(to: CGPoint(x: -8, y: 9))+ shape.closeSubpath()++ let transform = CGAffineTransform(translationX: p.x, y: p.y)+ .rotated(by: CGFloat(renderer.heading + .pi))+ let transformed = shape.applying(transform)++ let gradientColors = style.strokeGradientStops.isEmpty+ ? AgentCursorStyle.defaultGradientStops.map { Color(nsColor: $0.color) }+ : style.strokeGradientStops.map { Color(nsColor: $0.color) }++ ctx.fill(+ transformed,+ with: .linearGradient(+ Gradient(colors: gradientColors),+ startPoint: CGPoint(x: p.x + 14, y: p.y - 9),+ endPoint: CGPoint(x: p.x - 8, y: p.y + 9)+ )+ )+ ctx.stroke(transformed, with: .color(.white), lineWidth: style.strokeWidth)+ }}}diff --git a/libs/cua-driver/Sources/CuaDriverServer/ToolRegistry.swift b/libs/cua-driver/Sources/CuaDriverServer/ToolRegistry.swiftindex 2b6f1e9a28..c5ef3cd6ca 100644--- a/libs/cua-driver/Sources/CuaDriverServer/ToolRegistry.swift+++ b/libs/cua-driver/Sources/CuaDriverServer/ToolRegistry.swift@@ -235,6 +235,7 @@ public struct ToolRegistry: Sendable {SetValueTool.handler,SetAgentCursorEnabledTool.handler,SetAgentCursorMotionTool.handler,+ SetAgentCursorStyleTool.handler,GetAgentCursorStateTool.handler,SetRecordingTool.handler,GetRecordingStateTool.handler,diff --git a/libs/cua-driver/Sources/CuaDriverServer/Tools/SetAgentCursorStyleTool.swift b/libs/cua-driver/Sources/CuaDriverServer/Tools/SetAgentCursorStyleTool.swiftnew file mode 100644index 0000000000..2caada5b70--- /dev/null+++ b/libs/cua-driver/Sources/CuaDriverServer/Tools/SetAgentCursorStyleTool.swift@@ -0,0 +1,111 @@+import CuaDriverCore+import Foundation+import MCP++/// Set the visual style of the agent-cursor overlay. All fields are+/// optional — omit any field to keep its current value.+///+/// Changes take effect on the next rendered frame. Style choices are+/// persisted to config so the next daemon restart restores them.+public enum SetAgentCursorStyleTool {+ public static let handler = ToolHandler(+ tool: Tool(+ name: "set_agent_cursor_style",+ description: """+ Customize the agent-cursor's visual appearance. All fields+ optional; omitted fields keep their current value.++ - gradient_colors: Array of CSS hex strings (#RRGGBB or+ #RGB) defining the arrow fill gradient from tip to tail.+ E.g. ["#FF6B6B", "#FF8E53"] for a red-orange arrow.+ - bloom_color: CSS hex string for the glow halo and the+ focus-rect highlight drawn around clicked elements.+ - image_path: Absolute or ~-rooted path to a PNG, JPEG,+ PDF, or SVG file. When set, replaces the default arrow+ with this image (drawn at shapeSize × shapeSize points,+ rotated to match the motion heading). Set to "" (empty+ string) to revert to the procedural arrow.++ Example — brand-colored arrow:+ {"gradient_colors": ["#A855F7", "#6366F1"], "bloom_color": "#A855F7"}++ Example — custom PNG cursor:+ {"image_path": "~/cursors/my-cursor.png"}++ Example — revert to default:+ {"gradient_colors": [], "bloom_color": "", "image_path": ""}+ """,+ inputSchema: [+ "type": "object",+ "properties": [+ "gradient_colors": [+ "type": "array",+ "items": ["type": "string"],+ "description": "CSS hex color strings for gradient stops (tip to tail). Empty array reverts to default.",+ ],+ "bloom_color": [+ "type": "string",+ "description": "CSS hex color for the bloom halo and focus rect. Empty string reverts to default.",+ ],+ "image_path": [+ "type": "string",+ "description": "Path to PNG/JPEG/PDF/SVG cursor image. Empty string reverts to arrow.",+ ],+ ],+ "additionalProperties": false,+ ],+ annotations: .init(+ readOnlyHint: false,+ destructiveHint: false,+ idempotentHint: true,+ openWorldHint: false+ )+ ),+ invoke: { arguments in+ // Read current persisted style; we'll mutate only the supplied fields.+ var styleConfig = await ConfigStore.shared.load().agentCursor.style++ if let colors = arguments?["gradient_colors"]?.arrayValue {+ let hexes = colors.compactMap { $0.stringValue }+ styleConfig.gradientColors = hexes.isEmpty ? nil : hexes+ }++ if let bloomStr = arguments?["bloom_color"]?.stringValue {+ styleConfig.bloomColor = bloomStr.isEmpty ? nil : bloomStr+ }++ if let pathStr = arguments?["image_path"]?.stringValue {+ styleConfig.imagePath = pathStr.isEmpty ? nil : pathStr+ }++ // Apply live so the change is immediate.+ await MainActor.run {+ AgentCursor.shared.applyStyleConfig(styleConfig)+ }++ // Persist.+ do {+ try await ConfigStore.shared.mutate { config in+ config.agentCursor.style = styleConfig+ }+ } catch {+ return CallTool.Result(+ content: [.text(+ text: "Style applied live but persisting to config failed: \(error.localizedDescription)",+ annotations: nil, _meta: nil+ )],+ isError: true+ )+ }++ var parts: [String] = []+ if let gc = styleConfig.gradientColors { parts.append("gradient_colors=[\(gc.joined(separator: ","))]") }+ if let bc = styleConfig.bloomColor { parts.append("bloom_color=\(bc)") }+ if let ip = styleConfig.imagePath { parts.append("image_path=\(ip)") }+ let summary = parts.isEmpty ? "reverted to default" : parts.joined(separator: " ")+ return CallTool.Result(+ content: [.text(text: "✅ cursor style: \(summary)", annotations: nil, _meta: nil)]+ )+ }+ )+}