feat(cua-driver): cursor style customization and bare binary release artifact

[ddupont808]

Summary

• Custom cursor colors: AgentCursorStyle now accepts strokeGradientStops (array of AgentCursorGradientStop) and bloomColor (NSColor) — change the arrow gradient and glow hue from Swift or via the new set_agent_cursor_style MCP tool. NSColor(hex:) convenience initializer added for CSS hex strings.
• Custom cursor image: AgentCursorStyle.image: NSImage? — when set, replaces the procedural arrow with the provided image (PNG, JPEG, PDF, or SVG via NSImage(contentsOf:)), drawn at shapeSize × shapeSize points and rotated to track the motion heading. Bloom halo still rendered underneath.
• Swift dep API: AgentCursor.shared.setStyle(_:) — one-call style override for Swift dep users (e.g. Clicky) without going through MCP.
• MCP tool: set_agent_cursor_style — gradient_colors, bloom_color, image_path fields, all optional. Persists to config across restarts.
• Focus rect: drawFocusRect now reads style.bloomColor instead of hardcoded cyan, so focus highlights always match the cursor's theme.
• Style persistence: AgentCursorConfig.Style added to config.json schema; applied on daemon boot via apply(config:).
• Bare binary release artifact: cd-swift-cua-driver.yml packages the signed inner cua-driver Mach-O as cua-driver-*-binary.tar.gz for third-party apps that want to embed and re-sign it under their own bundle identity (stashed locally pending workflow scope — see below).
• Docs: Swift integration guide updated with cursor customization examples; MCP tools reference documents set_agent_cursor_style.

Context

This unblocks Clicky's integration ask: they want to brand the cursor and avoid double TCC permission prompts by embedding cua-driver as a Swift dep under their own bundle identity.

Test plan

• swift build --configuration release passes (confirmed locally — Build complete!)
• AgentCursorRenderer.shared.style = AgentCursorStyle(image: NSImage(...)) renders custom image
• AgentCursorRenderer.shared.style = AgentCursorStyle(strokeGradientStops: [...], bloomColor: ...) renders custom colors
• set_agent_cursor_style '{"gradient_colors": ["#A855F7", "#6366F1"], "bloom_color": "#A855F7"}' applies and persists
• set_agent_cursor_style '{"image_path": "~/cursor.png"}' loads and renders image
• set_agent_cursor_style '{"gradient_colors": [], "bloom_color": "", "image_path": ""}' reverts to default
• Focus rect color tracks bloomColor
• Config round-trips through daemon restart

Note on bare binary workflow change

The cd-swift-cua-driver.yml change (bare binary artifact) is stashed locally. It needs workflow scope on the token to push. Run gh auth refresh -s workflow then git stash pop && git push to include it in this PR.

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Agent cursor styling is now customizable with gradient colors, bloom effects, and custom image assets
  • Cursor style settings persist across application sessions

• Documentation

  • Added guide for customizing agent cursor appearance in Swift-integrated applications
  • Updated API reference documentation with new cursor style configuration options

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
docs	Ready	Preview, Comment	Apr 30, 2026 9:19pm

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

📝 Walkthrough

Walkthrough

This pull request adds configurable cursor styling to the CUA driver. It introduces a new MCP tool set_agent_cursor_style that allows runtime customization of agent cursor appearance through gradient colors, bloom color, and custom images. Configuration is persisted and applied through an observable style property on the renderer.

Changes

Cohort / File(s)	Summary
Documentation docs/content/docs/cua-driver/guide/getting-started/swift-integration.mdx, docs/content/docs/cua-driver/reference/mcp-tools.mdx	Adds new Swift integration guide for cursor customization and documents the set_agent_cursor_style MCP tool with field specifications and defaults.
Configuration & Persistence libs/cua-driver/Sources/CuaDriverCore/Config/CuaDriverConfig.swift	Introduces AgentCursorConfig.Style struct with optional gradient colors, bloom color, and image path fields; adds custom decoder for safe deserialization.
Core Cursor Styling libs/cua-driver/Sources/CuaDriverCore/Cursor/AgentCursor.swift	Refactors AgentCursorStyle into a defaultable struct; adds NSColor(hex:) initializer; implements setStyle and applyStyleConfig to convert hex colors and load custom images at runtime.
Renderer & View libs/cua-driver/Sources/CuaDriverCore/Cursor/AgentCursorRenderer.swift, libs/cua-driver/Sources/CuaDriverCore/Cursor/AgentCursorView.swift	Exposes observable style property on renderer; updates focus-rectangle and cursor rendering to use style-driven bloom colors, gradient stops, and custom image support.
MCP Tool & Registry libs/cua-driver/Sources/CuaDriverServer/Tools/SetAgentCursorStyleTool.swift, libs/cua-driver/Sources/CuaDriverServer/ToolRegistry.swift	Adds set_agent_cursor_style MCP tool handler that updates style configuration, applies changes via MainActor, and persists to ConfigStore.

Sequence Diagram

sequenceDiagram
    participant Client as MCP Client
    participant Tool as SetAgentCursorStyleTool
    participant Config as ConfigStore
    participant Cursor as AgentCursor
    participant Renderer as AgentCursorRenderer
    participant View as AgentCursorView

    Client->>Tool: set_agent_cursor_style(gradient_colors, bloom_color, image_path)
    Tool->>Config: read current style
    Config-->>Tool: AgentCursorConfig.Style
    Tool->>Tool: merge updates (nil = default)
    Tool->>Cursor: applyStyleConfig(updated style)
    Cursor->>Cursor: parse hex colors & load image
    Cursor->>Renderer: setStyle(AgentCursorStyle)
    Renderer->>Renderer: update observable style property
    Renderer->>View: render next frame
    View->>View: apply bloom color & gradient stops
    View-->>Renderer: rendered frame
    Tool->>Config: persist updated style
    Config-->>Tool: success/failure
    Tool-->>Client: result (configured fields or revert to default)

Loading

Estimated Code Review Effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Poem

🐰 A cursor with colors so bright,
Gradients bloom in the night,
Custom images dance with flair,
Styled with config beyond compare,
The agent's pointer now has its care! ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Title check	❓ Inconclusive	The PR title mentions 'cursor style customization' which aligns with the main changes (custom colors, images, and styling), but also mentions 'bare binary release artifact' which is not reflected in the provided raw_summary changes and appears to be incomplete/stashed.	Clarify whether the bare binary release artifact changes are included in this PR. If they are stashed/incomplete, update the title to focus only on 'feat(cua-driver): cursor style customization' or include the workflow changes in the PR.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Docstring Coverage	✅ Passed	Docstring coverage is 80.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/cursor-customization-and-bare-binary

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Review rate limit: 7/8 reviews remaining, refill in 7 minutes and 30 seconds.}

_{Comment @coderabbitai help to get the list of available commands and usage tips.}