Skip to content

armgit / cua

Public Imported from GitHub
0

Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.

feat(cua-driver)!: move cursor context into session badges (#2677)

Francesco Bonacci11c4647128a9
diff --git a/.github/workflows/ci-rust-linux.yml b/.github/workflows/ci-rust-linux.yml
index 1a92ff6c6f..4d6e8e79c3 100644
--- a/.github/workflows/ci-rust-linux.yml
+++ b/.github/workflows/ci-rust-linux.yml
@@ -66,7 +66,7 @@ jobs:
libei-dev libxkbcommon-dev libx11-dev libxi-dev libxtst-dev libxext-dev
- name: Run Linux Rust tests
working-directory: libs/cua-driver/rust
- run: cargo test -p cua-driver -p cua-driver-contract -p cua-driver-core -p cua-driver-testkit -p platform-linux --all-targets --locked
+ run: cargo test -p cua-driver -p cua-driver-contract -p cua-driver-core -p cua-driver-testkit -p cursor-overlay -p cursor-theme-cli -p platform-linux --all-targets --locked
- name: Compile portable GNOME/KDE portal input
working-directory: libs/cua-driver/rust
run: cargo check -p cua-driver --features portal-input --locked
diff --git a/.github/workflows/ci-rust-windows.yml b/.github/workflows/ci-rust-windows.yml
index 9b720dc3ad..cc39734bd6 100644
--- a/.github/workflows/ci-rust-windows.yml
+++ b/.github/workflows/ci-rust-windows.yml
@@ -63,10 +63,17 @@ jobs:
working-directory: libs/cua-driver/rust
# Compile every Rust target without executing desktop-dependent integration
# tests; interactive behavior belongs in e2e-rust-windows.yml.
- run: cargo test -p cua-driver -p cua-driver-core -p cua-driver-sdk -p cua-driver-testkit -p platform-windows -p cua-driver-uia --all-targets --no-run --locked
+ run: cargo test -p cua-driver -p cua-driver-core -p cua-driver-sdk -p cua-driver-testkit -p cursor-overlay -p cursor-theme-cli -p platform-windows -p cua-driver-uia --all-targets --no-run --locked
+ - name: Run cross-platform cursor renderer unit tests
+ working-directory: libs/cua-driver/rust
+ run: |
+ cargo test -p cursor-overlay --lib --locked
+ if ($LASTEXITCODE -ne 0) { throw "cursor renderer tests failed with exit $LASTEXITCODE" }
+ cargo test -p cursor-theme-cli --locked
+ if ($LASTEXITCODE -ne 0) { throw "cursor theme compiler tests failed with exit $LASTEXITCODE" }
- name: Run Windows delivery guidance unit tests
working-directory: libs/cua-driver/rust
- run: 'cargo test -p platform-windows input::delivery::tests:: --lib --locked'
+ run: "cargo test -p platform-windows input::delivery::tests:: --lib --locked"
- name: Run transport-independent authorization and SDK tests
working-directory: libs/cua-driver/rust
run: |
diff --git a/docs/content/docs/how-to-guides/driver/personalize-cursor.mdx b/docs/content/docs/how-to-guides/driver/personalize-cursor.mdx
index c26700b759..efa3301bcc 100644
--- a/docs/content/docs/how-to-guides/driver/personalize-cursor.mdx
+++ b/docs/content/docs/how-to-guides/driver/personalize-cursor.mdx
@@ -49,6 +49,13 @@ whitespace, and shortens labels longer than 28 characters. The label is visual
identity only. It does not grant authorization, select another session's
capabilities, or expose Cua's private runtime identifier.
+The badge also shows execution context when it applies. A filled delivery chip
+identifies `background` or `foreground`, followed by an outlined target chip
+for `ax`, `pixel`, `browser`, or `desktop`. These chips stay visible while the
+action is active and fade independently from the session name. They are drawn
+by Cua Driver, so their meaning stays consistent across themes and operating
+systems.
+
The old `set_agent_cursor_style` operation and its `cursor_id`, shape, color,
label, size, opacity, image-path, gradient, and bloom styling fields have been
removed. (`cursor_id` may still appear on input-delivery tools where it names a
@@ -64,8 +71,6 @@ A source theme is a dotLottie archive with:
- a `cua/theme.json` semantic manifest;
- all twelve actions: `idle`, `observe`, `click`, `drag`, `scroll`, `text`,
`key`, `navigate`, `app`, `transfer`, `record`, and `system`;
-- all six modifiers: `background`, `foreground`, `ax`, `pixel`, `browser`, and
- `desktop`;
- a representative `still_frame` for every animation;
- an author and license.
@@ -75,7 +80,7 @@ author, and license. It preserves paths and strokes as vectors, so the native
renderer can draw them at the current display scale instead of enlarging a
fixed-resolution image.
-![The six delivery and target modifiers supported by Cua cursor themes](/img/cua-driver/cursor-themes/delivery-target-context.gif)
+![The host-rendered delivery and target context chips](/img/cua-driver/cursor-themes/delivery-target-context.gif)
Validate, compile, inspect, and preview the source:
@@ -96,9 +101,15 @@ cua-driver set_agent_cursor_theme \
'{"session":"demo","theme_id":"com.example.cursor.studio"}'
```
-Profile v1 does not compile dotLottie color/theme variants. Publish each
+Profile v2 does not compile dotLottie color/theme variants. Publish each
visually distinct design under a separate theme ID.
+Profile v2 contains action animations only. The source manifest uses
+`"schema": "cua.cursor-theme/2"`,
+`"profile": "cua-driver-actions-v2"`, and `"semantics": 2`. V1 source and
+compiled artifacts are rejected. Remove the old `modifiers` section and rebuild
+the theme with the current compiler.
+
## Why installation is separate
Theme authoring is a trusted local workflow. The short-lived compiler validates
@@ -113,9 +124,10 @@ cannot install source or submit inline animation data.
The built-in `cua.default` theme uses the same compiler and renderer. Cua ships
its compiled artifact inside the driver, so users do not need to install it.
-The driver applies the stable session color and shared floating motion after
-compositing the default theme's action and modifier layers. Installed custom
-themes keep their authored colors.
+The driver applies the stable session color and shared floating motion to the
+default theme's action layer. Installed custom themes keep their authored
+colors. The host renders delivery and target chips in the badge for both the
+default and custom themes.
Remove a custom theme with:
diff --git a/libs/cua-driver/docs/action-icon-catalog.md b/libs/cua-driver/docs/action-icon-catalog.md
index d988c2cbaa..3d868fff1a 100644
--- a/libs/cua-driver/docs/action-icon-catalog.md
+++ b/libs/cua-driver/docs/action-icon-catalog.md
@@ -1,6 +1,6 @@
# Cua Driver action and icon catalog
-**Status:** Semantic source catalog for cursor theme profile v1
+**Status:** Semantic source catalog for cursor theme profile v2
**Source:** Cua Driver public contract and platform tool registries
@@ -41,7 +41,7 @@ need unrelated illustrations. A maintainable asset system uses:
1. a base intent glyph or animation (`click`, `type`, `scroll`, `drag`);
2. a targeting treatment (`ax`, `px`, `desktop`, `page`, `browser`);
-3. a delivery treatment (`background`, `foreground`);
+3. a host-rendered delivery chip (`background`, `foreground`);
4. a small qualifier where it changes the visible gesture (`right`, `double`,
`down`, `page`, and so on).
@@ -49,25 +49,25 @@ need unrelated illustrations. A maintainable asset system uses:
### Targeting
-| Token | Meaning | How it is selected |
-| --- | --- | --- |
-| `ax` | Accessibility-addressed element action | `element_token` or `element_index` |
-| `px` | Window-local pixel action | Window target plus `x`/`y` coordinates |
-| `focused` | Acts on the target's currently focused control | No element or point supplied |
-| `desktop` | Screen-absolute action | `scope:"desktop"` without a window target |
-| `page` | Legacy page/DOM action | A `page[action=…]` operation |
-| `browser_trusted` | Typed browser action through trusted CDP Input events | `input_route:"trusted"` or omitted |
-| `browser_dom` | Explicit synthetic DOM event | `input_route:"dom_event"` |
+| Token | Meaning | How it is selected |
+| ----------------- | ----------------------------------------------------- | ----------------------------------------- |
+| `ax` | Accessibility-addressed element action | `element_token` or `element_index` |
+| `px` | Window-local pixel action | Window target plus `x`/`y` coordinates |
+| `focused` | Acts on the target's currently focused control | No element or point supplied |
+| `desktop` | Screen-absolute action | `scope:"desktop"` without a window target |
+| `page` | Legacy page/DOM action | A `page[action=…]` operation |
+| `browser_trusted` | Typed browser action through trusted CDP Input events | `input_route:"trusted"` or omitted |
+| `browser_dom` | Explicit synthetic DOM event | `input_route:"dom_event"` |
### Delivery
-| Token | Meaning |
-| --- | --- |
-| `background` | Targeted delivery without raising or fronting the target |
-| `foreground` | Briefly front target, act, then restore the previous foreground app |
-| `persistent_foreground` | `bring_to_front`; target stays foreground |
-| `fixed_background` | Browser or Linux low-level operation whose contract never fronts |
-| `none` | Read-only or lifecycle operation with no input-delivery posture |
+| Token | Meaning |
+| ----------------------- | ------------------------------------------------------------------- |
+| `background` | Targeted delivery without raising or fronting the target |
+| `foreground` | Briefly front target, act, then restore the previous foreground app |
+| `persistent_foreground` | `bring_to_front`; target stays foreground |
+| `fixed_background` | Browser or Linux low-level operation whose contract never fronts |
+| `none` | Read-only or lifecycle operation with no input-delivery posture |
The desktop input family exposing `delivery_mode` is:
@@ -87,15 +87,15 @@ scroll
### Gesture qualifiers
-| Dimension | Values |
-| --- | --- |
-| Button | `left`, `right`, `middle` |
-| Click count | `single`, `double`, `triple` |
-| AX click action | `press`, `show_menu`, `pick`, `confirm`, `cancel`, `open` |
-| Scroll direction | `up`, `down`, `left`, `right` |
-| Scroll unit | `line`, `page` |
-| Browser input route | `trusted`, `dom_event` |
-| Browser typing | `insert_text`, `keystrokes` |
+| Dimension | Values |
+| ------------------- | --------------------------------------------------------- |
+| Button | `left`, `right`, `middle` |
+| Click count | `single`, `double`, `triple` |
+| AX click action | `press`, `show_menu`, `pick`, `confirm`, `cancel`, `open` |
+| Scroll direction | `up`, `down`, `left`, `right` |
+| Scroll unit | `line`, `page` |
+| Browser input route | `trusted`, `dom_event` |
+| Browser typing | `insert_text`, `keystrokes` |
Modifiers such as Command, Control, Alt/Option, and Shift belong in the
animation payload or label. They do not require separate base icons.
@@ -105,61 +105,62 @@ animation payload or label. They do not require separate base icons.
These are the action identities that should drive cursor animations.
Brace-delimited values are finite variants, not literal asset names.
-| Public tool | Resolved action keys |
-| --- | --- |
-| `click` | `native.click.ax.{background\|foreground}.{press\|show_menu\|pick\|confirm\|cancel\|open}` |
-| `click` | `native.click.px.{background\|foreground}.{left\|right\|middle}.{single\|double\|triple}` |
-| `click` | `native.click.desktop.{left\|right\|middle}.{single\|double\|triple}` |
-| `double_click` | `native.double_click.{ax\|px}.{background\|foreground}` |
-| `right_click` | `native.right_click.{ax\|px}.{background\|foreground}` |
-| `drag` | `native.drag.px.{background\|foreground}.{left\|right\|middle}` |
-| `drag` | `native.drag.desktop.{left\|right\|middle}` |
-| `type_text` | `native.type_text.{ax\|px\|focused}.{background\|foreground}` |
-| `type_text` | `native.type_text.desktop` |
-| `press_key` | `native.press_key.{ax\|px\|focused}.{background\|foreground}` |
-| `press_key` | `native.press_key.desktop` |
-| `hotkey` | `native.hotkey.{px\|focused}.{background\|foreground}` |
-| `hotkey` | `native.hotkey.desktop` |
-| `set_value` | `native.set_value.ax.background` |
-| `scroll` | `native.scroll.{ax\|px}.{background\|foreground}.{up\|down\|left\|right}.{line\|page}` |
-| `scroll` | `native.scroll.desktop.{up\|down\|left\|right}.{line\|page}` |
-| `move_cursor` | `agent_cursor.move.window`, `native.pointer.move.desktop` |
-| `zoom` | `native.zoom.window` |
-| `bring_to_front` | `native.window.persistent_foreground` |
+| Public tool | Resolved action keys |
+| ---------------- | ------------------------------------------------------------------------------------------ |
+| `click` | `native.click.ax.{background\|foreground}.{press\|show_menu\|pick\|confirm\|cancel\|open}` |
+| `click` | `native.click.px.{background\|foreground}.{left\|right\|middle}.{single\|double\|triple}` |
+| `click` | `native.click.desktop.{left\|right\|middle}.{single\|double\|triple}` |
+| `double_click` | `native.double_click.{ax\|px}.{background\|foreground}` |
+| `right_click` | `native.right_click.{ax\|px}.{background\|foreground}` |
+| `drag` | `native.drag.px.{background\|foreground}.{left\|right\|middle}` |
+| `drag` | `native.drag.desktop.{left\|right\|middle}` |
+| `type_text` | `native.type_text.{ax\|px\|focused}.{background\|foreground}` |
+| `type_text` | `native.type_text.desktop` |
+| `press_key` | `native.press_key.{ax\|px\|focused}.{background\|foreground}` |
+| `press_key` | `native.press_key.desktop` |
+| `hotkey` | `native.hotkey.{px\|focused}.{background\|foreground}` |
+| `hotkey` | `native.hotkey.desktop` |
+| `set_value` | `native.set_value.ax.background` |
+| `scroll` | `native.scroll.{ax\|px}.{background\|foreground}.{up\|down\|left\|right}.{line\|page}` |
+| `scroll` | `native.scroll.desktop.{up\|down\|left\|right}.{line\|page}` |
+| `move_cursor` | `agent_cursor.move.window`, `native.pointer.move.desktop` |
+| `zoom` | `native.zoom.window` |
+| `bring_to_front` | `native.window.persistent_foreground` |
Do not generate every Cartesian product as a fully independent illustration.
-For example, all `native.scroll.*` actions should share one scroll animation,
-with direction, delivery, and targeting represented as composable treatments.
+For example, all `native.scroll.*` actions share one scroll animation.
+Delivery and targeting are composable host-rendered badge chips rather than
+theme animations.
## Page compound actions
The public `page` tool contains seven operations:
-| Resolved action key | Effect | Platform note |
-| --- | --- | --- |
-| `page.get_text` | Read visible page text | Cross-platform |
-| `page.query_dom` | Query elements with a CSS selector | Cross-platform |
-| `page.execute_javascript` | Execute JavaScript | Cross-platform where a supported page backend is available |
-| `page.click_element` | Click a CSS-selected element | Cross-platform |
-| `page.insert_text` | Insert text at current DOM focus | macOS implementation currently documented |
-| `page.type_keystrokes` | Dispatch durable per-character key events | macOS implementation currently documented |
-| `page.enable_javascript_apple_events` | Enable Safari JavaScript automation | macOS only |
+| Resolved action key | Effect | Platform note |
+| ------------------------------------- | ----------------------------------------- | ---------------------------------------------------------- |
+| `page.get_text` | Read visible page text | Cross-platform |
+| `page.query_dom` | Query elements with a CSS selector | Cross-platform |
+| `page.execute_javascript` | Execute JavaScript | Cross-platform where a supported page backend is available |
+| `page.click_element` | Click a CSS-selected element | Cross-platform |
+| `page.insert_text` | Insert text at current DOM focus | macOS implementation currently documented |
+| `page.type_keystrokes` | Dispatch durable per-character key events | macOS implementation currently documented |
+| `page.enable_javascript_apple_events` | Enable Safari JavaScript automation | macOS only |
## Typed browser actions
-| Public tool | Resolved action keys |
-| --- | --- |
-| `get_browser_state` | `browser.bind`, `browser.snapshot.dom_refs_v1`, `browser.snapshot.semantic_v2` |
-| `browser_prepare` | `browser.prepare.detect`, `browser.prepare.isolated_new`, `browser.prepare.isolated_named`, `browser.prepare.existing_profile` |
-| `browser_navigate` | `browser.navigate` |
-| `browser_click` | `browser.click.trusted.{ref\|viewport}`, `browser.click.dom_event.ref` |
-| `browser_type` | `browser.type.insert_text`, `browser.type.keystrokes` |
-| `browser_dialog` | `browser.dialog.inspect` |
-| `browser_dialog` | `browser.dialog.accept.{background\|foreground}` |
-| `browser_dialog` | `browser.dialog.dismiss.{background\|foreground}` |
-| `browser_set_input_files` | `browser.files.set_input` |
-| `browser_download` | `browser.download` |
-| `browser_pointer` | `browser.pointer.{hover\|right_click\|double_click\|scroll\|drag}.{trusted\|dom_event}` |
+| Public tool | Resolved action keys |
+| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `get_browser_state` | `browser.bind`, `browser.snapshot.dom_refs_v1`, `browser.snapshot.semantic_v2` |
+| `browser_prepare` | `browser.prepare.detect`, `browser.prepare.isolated_new`, `browser.prepare.isolated_named`, `browser.prepare.existing_profile` |
+| `browser_navigate` | `browser.navigate` |
+| `browser_click` | `browser.click.trusted.{ref\|viewport}`, `browser.click.dom_event.ref` |
+| `browser_type` | `browser.type.insert_text`, `browser.type.keystrokes` |
+| `browser_dialog` | `browser.dialog.inspect` |
+| `browser_dialog` | `browser.dialog.accept.{background\|foreground}` |
+| `browser_dialog` | `browser.dialog.dismiss.{background\|foreground}` |
+| `browser_set_input_files` | `browser.files.set_input` |
+| `browser_download` | `browser.download` |
+| `browser_pointer` | `browser.pointer.{hover\|right_click\|double_click\|scroll\|drag}.{trusted\|dom_event}` |
Typed browser clicks and pointer operations have fixed background posture. The
`trusted` and `dom_event` routes are materially different and should remain
@@ -167,26 +168,26 @@ distinct resolved action IDs.
## Session, recording, cursor, and maintenance variants
-| Public tool | Resolved action keys |
-| --- | --- |
-| `start_session` | `session.start.{auto\|window\|desktop}` |
-| `escalate_session` | `session.escalate.desktop` |
-| `get_session_state` | `session.inspect` |
-| `end_session` | `session.end` |
-| `start_recording` | `recording.start.trajectory`, `recording.start.video` |
-| `stop_recording` | `recording.stop` |
-| `get_recording_state` | `recording.inspect` |
-| `replay_trajectory` | `recording.replay` |
-| `set_agent_cursor_enabled` | `agent_cursor.show`, `agent_cursor.hide` |
-| `set_agent_cursor_motion` | `agent_cursor.configure_motion` |
-| `set_agent_cursor_theme` | `agent_cursor.set_theme` |
-| `get_agent_cursor_state` | `agent_cursor.inspect` |
-| `check_permissions` | `permissions.inspect`, `permissions.request` |
-| `health_report` | `system.health.inspect` |
-| `get_config` | `config.inspect` |
-| `set_config` | `config.update` |
-| `check_for_update` | `update.inspect` |
-| `install_ffmpeg` | `dependency.ffmpeg.plan`, `dependency.ffmpeg.install` |
+| Public tool | Resolved action keys |
+| -------------------------- | ----------------------------------------------------- |
+| `start_session` | `session.start.{auto\|window\|desktop}` |
+| `escalate_session` | `session.escalate.desktop` |
+| `get_session_state` | `session.inspect` |
+| `end_session` | `session.end` |
+| `start_recording` | `recording.start.trajectory`, `recording.start.video` |
+| `stop_recording` | `recording.stop` |
+| `get_recording_state` | `recording.inspect` |
+| `replay_trajectory` | `recording.replay` |
+| `set_agent_cursor_enabled` | `agent_cursor.show`, `agent_cursor.hide` |
+| `set_agent_cursor_motion` | `agent_cursor.configure_motion` |
+| `set_agent_cursor_theme` | `agent_cursor.set_theme` |
+| `get_agent_cursor_state` | `agent_cursor.inspect` |
+| `check_permissions` | `permissions.inspect`, `permissions.request` |
+| `health_report` | `system.health.inspect` |
+| `get_config` | `config.inspect` |
+| `set_config` | `config.update` |
+| `check_for_update` | `update.inspect` |
+| `install_ffmpeg` | `dependency.ffmpeg.plan`, `dependency.ffmpeg.install` |
## Complete public tool-name union
@@ -194,62 +195,62 @@ The source-built macOS registry contains 49 tools. Windows adds
`debug_window_info`. Linux adds four low-level pointer tools. The union is 54
public tool names.
-| # | Tool | Category | Platform | Primary icon intent |
-| ---: | --- | --- | --- | --- |
-| 1 | `list_apps` | Inspection | All | Apps/list |
-| 2 | `list_windows` | Inspection | All | Windows/list |
-| 3 | `get_window_state` | Inspection | All | Window inspect; optional capture treatment |
-| 4 | `launch_app` | App lifecycle | All | Launch |
-| 5 | `kill_app` | App lifecycle | All | Force stop |
-| 6 | `bring_to_front` | Window lifecycle | All | Persistent foreground |
-| 7 | `click` | Pointer input | All | Click plus target/delivery/button/count |
-| 8 | `double_click` | Pointer input | All | Double click plus target/delivery |
-| 9 | `right_click` | Pointer input | All | Context click plus target/delivery |
-| 10 | `drag` | Pointer input | All | Drag plus delivery |
-| 11 | `type_text` | Keyboard input | All | Type plus target/delivery |
-| 12 | `press_key` | Keyboard input | All | Single key plus target/delivery |
-| 13 | `hotkey` | Keyboard input | All | Key chord plus delivery |
-| 14 | `set_value` | Accessibility input | All | Set semantic value |
-| 15 | `scroll` | Pointer/accessibility input | All | Scroll plus target/delivery/direction |
-| 16 | `get_screen_size` | Inspection | All | Screen dimensions |
-| 17 | `get_desktop_state` | Inspection | All | Desktop capture |
-| 18 | `get_cursor_position` | Inspection | All | Cursor location |
-| 19 | `move_cursor` | Pointer/overlay input | All | Agent-cursor move in window scope; real-pointer move in desktop scope |
-| 20 | `set_agent_cursor_enabled` | Agent cursor | All | Show/hide cursor |
-| 21 | `set_agent_cursor_motion` | Agent cursor | All | Motion configuration |
-| 22 | `set_agent_cursor_theme` | Agent cursor | All | Select an installed visual theme |
-| 23 | `get_agent_cursor_state` | Agent cursor | All | Cursor inspect |
-| 24 | `check_permissions` | Permissions | All; prompting is macOS-specific | Permission inspect/request |
-| 25 | `health_report` | Maintenance | All | Health check |
-| 26 | `get_config` | Configuration | All | Config inspect |
-| 27 | `set_config` | Configuration | All | Config update |
-| 28 | `get_accessibility_tree` | Inspection | All | Desktop accessibility inspect |
-| 29 | `zoom` | Inspection | All | Zoom/crop |
-| 30 | `page` | Page/DOM | All, with operation-specific limits | Use the seven page operation icons |
-| 31 | `get_browser_state` | Typed browser | All | Bind or snapshot |
-| 32 | `browser_prepare` | Typed browser | All | Browser preparation/profile |
-| 33 | `browser_navigate` | Typed browser | All | Navigate |
-| 34 | `browser_click` | Typed browser | All | Browser click plus route |
-| 35 | `browser_type` | Typed browser | All | Browser type plus mode |
-| 36 | `browser_dialog` | Typed browser | All | Inspect/accept/dismiss dialog |
-| 37 | `browser_set_input_files` | Typed browser | All | Upload/attach files |
-| 38 | `browser_download` | Typed browser | All | Download |
-| 39 | `browser_pointer` | Typed browser | All | Use the ten browser-pointer operation icons |
-| 40 | `start_recording` | Recording | All | Start trajectory/video recording |
-| 41 | `stop_recording` | Recording | All | Stop recording |
-| 42 | `get_recording_state` | Recording | All | Recording inspect |
-| 43 | `replay_trajectory` | Recording | All | Replay |
-| 44 | `install_ffmpeg` | Maintenance | Windows/Linux; no-op when unnecessary | Plan/install dependency |
-| 45 | `start_session` | Session lifecycle | All | Start session plus capture scope |
-| 46 | `escalate_session` | Session lifecycle | All | Escalate to desktop |
-| 47 | `get_session_state` | Session lifecycle | All | Session inspect |
-| 48 | `end_session` | Session lifecycle | All | End session |
-| 49 | `check_for_update` | Maintenance | All | Update check |
-| 50 | `debug_window_info` | Diagnostic | Windows only | Window diagnostic |
-| 51 | `mouse_button_down` | Low-level pointer | Linux only | Hold button |
-| 52 | `mouse_drag` | Low-level pointer | Linux only | Move held pointer |
-| 53 | `mouse_button_up` | Low-level pointer | Linux only | Release button |
-| 54 | `parallel_mouse_drag` | Multi-pointer | Linux only | Concurrent drags |
+| # | Tool | Category | Platform | Primary icon intent |
+| --: | -------------------------- | --------------------------- | ------------------------------------- | --------------------------------------------------------------------- |
+| 1 | `list_apps` | Inspection | All | Apps/list |
+| 2 | `list_windows` | Inspection | All | Windows/list |
+| 3 | `get_window_state` | Inspection | All | Window inspect; optional capture treatment |
+| 4 | `launch_app` | App lifecycle | All | Launch |
+| 5 | `kill_app` | App lifecycle | All | Force stop |
+| 6 | `bring_to_front` | Window lifecycle | All | Persistent foreground |
+| 7 | `click` | Pointer input | All | Click plus target/delivery/button/count |
+| 8 | `double_click` | Pointer input | All | Double click plus target/delivery |
+| 9 | `right_click` | Pointer input | All | Context click plus target/delivery |
+| 10 | `drag` | Pointer input | All | Drag plus delivery |
+| 11 | `type_text` | Keyboard input | All | Type plus target/delivery |
+| 12 | `press_key` | Keyboard input | All | Single key plus target/delivery |
+| 13 | `hotkey` | Keyboard input | All | Key chord plus delivery |
+| 14 | `set_value` | Accessibility input | All | Set semantic value |
+| 15 | `scroll` | Pointer/accessibility input | All | Scroll plus target/delivery/direction |
+| 16 | `get_screen_size` | Inspection | All | Screen dimensions |
+| 17 | `get_desktop_state` | Inspection | All | Desktop capture |
+| 18 | `get_cursor_position` | Inspection | All | Cursor location |
+| 19 | `move_cursor` | Pointer/overlay input | All | Agent-cursor move in window scope; real-pointer move in desktop scope |
+| 20 | `set_agent_cursor_enabled` | Agent cursor | All | Show/hide cursor |
+| 21 | `set_agent_cursor_motion` | Agent cursor | All | Motion configuration |
+| 22 | `set_agent_cursor_theme` | Agent cursor | All | Select an installed visual theme |
+| 23 | `get_agent_cursor_state` | Agent cursor | All | Cursor inspect |
+| 24 | `check_permissions` | Permissions | All; prompting is macOS-specific | Permission inspect/request |
+| 25 | `health_report` | Maintenance | All | Health check |
+| 26 | `get_config` | Configuration | All | Config inspect |
+| 27 | `set_config` | Configuration | All | Config update |
+| 28 | `get_accessibility_tree` | Inspection | All | Desktop accessibility inspect |
+| 29 | `zoom` | Inspection | All | Zoom/crop |
+| 30 | `page` | Page/DOM | All, with operation-specific limits | Use the seven page operation icons |
+| 31 | `get_browser_state` | Typed browser | All | Bind or snapshot |
+| 32 | `browser_prepare` | Typed browser | All | Browser preparation/profile |
+| 33 | `browser_navigate` | Typed browser | All | Navigate |
+| 34 | `browser_click` | Typed browser | All | Browser click plus route |
+| 35 | `browser_type` | Typed browser | All | Browser type plus mode |
+| 36 | `browser_dialog` | Typed browser | All | Inspect/accept/dismiss dialog |
+| 37 | `browser_set_input_files` | Typed browser | All | Upload/attach files |
+| 38 | `browser_download` | Typed browser | All | Download |
+| 39 | `browser_pointer` | Typed browser | All | Use the ten browser-pointer operation icons |
+| 40 | `start_recording` | Recording | All | Start trajectory/video recording |
+| 41 | `stop_recording` | Recording | All | Stop recording |
+| 42 | `get_recording_state` | Recording | All | Recording inspect |
+| 43 | `replay_trajectory` | Recording | All | Replay |
+| 44 | `install_ffmpeg` | Maintenance | Windows/Linux; no-op when unnecessary | Plan/install dependency |
+| 45 | `start_session` | Session lifecycle | All | Start session plus capture scope |
+| 46 | `escalate_session` | Session lifecycle | All | Escalate to desktop |
+| 47 | `get_session_state` | Session lifecycle | All | Session inspect |
+| 48 | `end_session` | Session lifecycle | All | End session |
+| 49 | `check_for_update` | Maintenance | All | Update check |
+| 50 | `debug_window_info` | Diagnostic | Windows only | Window diagnostic |
+| 51 | `mouse_button_down` | Low-level pointer | Linux only | Hold button |
+| 52 | `mouse_drag` | Low-level pointer | Linux only | Move held pointer |
+| 53 | `mouse_button_up` | Low-level pointer | Linux only | Release button |
+| 54 | `parallel_mouse_drag` | Multi-pointer | Linux only | Concurrent drags |
## Linux low-level pointer action keys
diff --git a/libs/cua-driver/docs/cursor-modifier-badge-restructuring-plan.md b/libs/cua-driver/docs/cursor-modifier-badge-restructuring-plan.md
new file mode 100644
index 0000000000..f29a8c5a7d
--- /dev/null
+++ b/libs/cua-driver/docs/cursor-modifier-badge-restructuring-plan.md
@@ -0,0 +1,424 @@
+# Cursor modifier badge restructuring plan
+
+**Status:** Implemented in [PR #2677](https://github.com/trycua/cua/pull/2677); validation complete
+**Base:** `main` at `b249df857994ebaebf9f02248e8312b3bd2a5dd2`
+**Scope:** Move delivery and target modifiers from around the agent pointer into the session badge while preserving action animations beside the pointer.
+
+## Outcome
+
+Cua Driver should present two kinds of cursor information in two clear places:
+
+- The pointer shows the current action, such as click, drag, scroll, or text.
+- The badge shows execution context:
+ - delivery: background or foreground
+ - target: AX, pixel, browser, or desktop
+
+The badge remains lightweight. The session name fades using the existing two-second hold and 400-millisecond fade. Modifier chips appear only while their action is active, followed by a 400-millisecond trailing fade. When the name is hidden, the badge contracts to a compact session orb and active modifier chips. Hovering the pointer restores the full session name where hover observation is supported.
+
+This is visual feedback only. It is not an authorization indicator, a security boundary, or evidence that an action succeeded.
+
+## Definition of done
+
+The work is complete when:
+
+1. Action animations remain visually unchanged beside the pointer.
+2. Pointer-relative delivery and target artwork is no longer painted.
+3. Delivery and target appear as upright badge chips on macOS, Windows, X11, native Wayland, and the GNOME helper path.
+4. A delivery chip and target chip can appear together without overlap.
+5. Session-name and modifier visibility use independent, deterministic timing.
+6. Badge geometry, timing, glyph semantics, and dirty extents live in shared code wherever the platform permits it.
+7. The cursor theme source contract moves cleanly to v2 with twelve action animations and no modifier animation section.
+8. Compiled v2 themes contain action artwork only and reject obsolete v1 artifacts with a clear rebuild message.
+9. Cursor overlay tests run in CI instead of only on developer machines.
+10. Unit, gallery, cross-platform E2E, documentation, and visual evidence are updated.
+
+## Design decision
+
+### One badge with independently fading content
+
+Use one pill rather than adding a second persistent status capsule.
+
+| Badge content | Visibility |
+| ------------------------- | --------------------------------------------------------------------------------------- |
+| Session orb and name | Existing reveal, two-second hold, 400-millisecond fade; hover restores full opacity |
+| Delivery and target chips | Full opacity while modifiers are active; 400-millisecond trailing fade after they clear |
+| Badge chrome | Visible while either the name or modifier chips are visible |
+
+Starting an action must not restart the session-name timer. Otherwise a long session name would flash on every tool call. Modifier changes reveal or update the chips only.
+
+When the name has faded, the pill contracts to the session orb and active chips. If no public session label exists, modifier-bearing actions still get this compact session-colored capsule. This preserves context without requiring a display name.
+
+### Host-owned modifier glyphs
+
+The badge owns six small vector glyphs:
+
+- background
+- foreground
+- AX
+- pixel
+- browser
+- desktop
+
+They are rendered through the shared Skia path at the live backing scale. Delivery uses a filled chip treatment. Target uses an outlined chip treatment. Shape, not color alone, communicates the difference.
+
+Do not reuse theme-authored modifier frames inside the badge:
+
+- Existing frames contain pointer-relative placement, not centered glyph geometry.
+- Their authored colors and stroke weights cannot guarantee badge legibility.
+- The background animation is a long gesture trail and does not fit a square chip.
+- The GNOME helper is a separate renderer and cannot consume compiled `.cua-theme` artifacts.
+- Reusing them would require an artifact version bump and a permanent compatibility decoder.
+
+The badge and its modifier glyphs therefore remain outside the dotLottie theme contract.
+
+### Preserve the current badge envelope
+
+Keep:
+
+- `BADGE_HEIGHT = 28`
+- `BADGE_MAX_WIDTH = 188`
+- `BADGE_CURSOR_GAP = 25`
+
+Use 18-point modifier chips with a four-point gap. The text budget becomes dynamic:
+
+- no chips: current text width
+- one chip: reduced text width
+- two chips: further reduced text width
+
+The label must ellipsize to its measured width and never wrap. The current font layout can wrap a wide 28-character label outside the pill, so this restructuring must fix that existing defect before reducing the text budget.
+
+## Breaking theme contract
+
+This change deliberately replaces the recently introduced v1 theme contract rather than carrying an unused compatibility layer.
+
+Use:
+
+- `cua.cursor-theme/2`
+- semantic vocabulary version `2`
+- `cua-driver-actions-v2`
+- compiled artifact version `3`
+- `CUATHEM3`
+
+The v2 source manifest contains only `actions`. A `modifiers` field is rejected with a focused migration message. The compiled `CompiledTheme` structure drops its modifier map entirely.
+
+Existing v1 `.cua-theme` files are rejected with a clear instruction to rebuild the source as v2. No decoder shim, aliases, ignored fields, or transitional profile are added.
+
+Regenerate `cua.default.lottie` and `cua.default.cua-theme` without modifier animations. The new source hash and artifact are checked in together and verified reproducibly.
+
+## Shared renderer changes
+
+### Badge geometry
+
+Refactor `cursor-overlay/src/session_badge.rs` so geometry is computed before painting.
+
+Add shared inputs and outputs similar to:
+
+```rust
+pub struct SessionBadgeInput<'a> {
+ pub label: Option<&'a str>,
+ pub delivery: Option<DeliveryModifier>,
+ pub target: Option<TargetModifier>,
+ pub cursor: (f32, f32),
+ pub backing_scale: f32,
+ pub label_alpha: f32,
+ pub chip_alpha: f32,
+ pub clip: Option<(f32, f32)>,
+}
+
+pub struct SessionBadgeLayout {
+ pub rect: Rect,
+ pub orb: Rect,
+ pub label: Option<BadgeLabelLayout>,
+ pub delivery_chip: Option<BadgeChip>,
+ pub target_chip: Option<BadgeChip>,
+ pub pill_alpha: f32,
+ pub label_alpha: f32,
+ pub chip_alpha: f32,
+}
+
+pub fn session_badge_layout(
+ input: SessionBadgeInput<'_>,
+) -> Option<SessionBadgeLayout>;
+
+pub fn paint_session_badge(
+ pixmap: &mut Pixmap,
+ layout: &SessionBadgeLayout,
+ session_fill: [u8; 4],
+ alpha_scale: f32,
+);
+
+pub const fn session_badge_extents() -> BadgeExtents;
+```
+
+The shared layout function owns:
+
+- chip ordering
+- dynamic text width
+- ellipsis
+- edge clamping
+- full and contracted pill widths
+- modifier and badge hit geometry
+- worst-case dirty extents
+
+Platform adapters must derive their dirty regions from `session_badge_extents()` instead of copying badge widths.
+
+### Modifier glyphs
+
+Add `cursor-overlay/src/badge_glyphs.rs` with host-owned vector geometry and typed mapping from `DeliveryModifier` and `TargetModifier`.
+
+Glyphs must:
+
+- remain upright and unrotated
+- use the session fill and white-outline visual language
+- render cleanly at 1x, 2x, 3x, and fractional backing scales
+- fit entirely inside an 18-point chip
+- retain shape distinction in monochrome screenshots
+
+### Badge state
+
+Extend `RenderStateCore` with a short-lived modifier latch so chips can fade after `CursorVisualState` returns to idle:
+
+```rust
+pub badge_modifiers:
+ Option<(Option<DeliveryModifier>, Option<TargetModifier>)>,
+pub badge_modifier_clear_secs: Option<f64>,
+```
+
+Add shared methods for:
+
+- modifier chip alpha
+- whether any badge content is visible
+- producing `SessionBadgeInput`
+- hit testing the pointer plus current badge geometry
+
+`BeginAction` updates the modifier latch without revealing the session name. `tick_idle` starts the trailing fade when semantic modifiers clear. Idle cursor opacity still multiplies the entire badge, so the badge cannot outlive the cursor.
+
+### Theme painting
+
+In `theme_artifact.rs`, stop compositing delivery and target animation layers with the pointer transform. Continue painting the selected action animation exactly as before.
+
+Remove modifier animation storage and compositing from the compiled artifact.
+
+## Platform work
+
+### macOS
+
+Use the common renderer and layout without platform-specific badge geometry. The existing full-screen overlay and hardware-pointer hover polling remain unchanged.
+
+### Windows
+
+Derive the layered-window dirty envelope from shared badge extents. Fix the current stale invariant where `CURSOR_PAD = 192` no longer covers `BADGE_MAX_WIDTH + 8`.
+
+Run the invariant test in CI instead of compiling it without executing it.
+
+### X11
+
+Derive horizontal and vertical tile margins from shared badge extents. The current vertical tile margin has little spare room below the badge and should not depend on a copied constant.
+
+Use shared badge visibility rather than `session_label.is_some()` when deciding whether the tile must include badge space.
+
+### Native Wayland
+
+Continue using the shared renderer. Modifier chips and timed visibility work identically. Hover reveal remains unavailable through the stock protocol because the client cannot observe another client's global pointer.
+
+### GNOME helper
+
+Remove pointer-relative modifier drawing. Render the same two badge chip slots in the Shell badge and mirror the shared timing constants.
+
+Keep the D-Bus action payload unchanged. Bump the bundled helper version and its Rust-side version pin together. Add parity fixtures so glyph identity, ordering, and timing cannot drift silently.
+
+## Implementation sequence
+
+### Phase 0: make current tests trustworthy
+
+1. Run `cursor-overlay` unit tests in Linux CI.
+2. Execute pure renderer tests in Windows CI.
+3. Expose and fix the stale Windows dirty-envelope assertion.
+4. Add CI coverage for shared modifier and badge tests before behavior changes.
+
+### Phase 1: extract shared geometry with no visual change
+
+1. Add `SessionBadgeInput`, `SessionBadgeLayout`, and `session_badge_extents`.
+2. Reimplement the existing label-only badge on that layout.
+3. Add width-based ellipsis and prevent wrapping.
+4. Prove label-only rendering and timing are unchanged.
+5. Derive Windows and X11 envelopes from shared extents.
+
+### Phase 2: add badge glyphs and modifier lifecycle
+
+1. Add the six shared badge glyphs.
+2. Add delivery and target chip slots.
+3. Add the modifier latch and trailing fade.
+4. Support compact chips-only layout for faded or unlabeled sessions.
+5. Extend hover hit testing to the visible badge rect while keeping the overlay click-through.
+6. Verify label reveal is not restarted by tool actions.
+
+### Phase 3: move presentation away from the pointer
+
+1. Temporarily render badge chips alongside existing pointer modifiers for visual comparison.
+2. Approve glyph legibility at production size.
+3. Remove modifier compositing from `paint_compiled_theme_with_tint`.
+4. Replace pointer-position tests with tests proving modifiers no longer change pointer pixels.
+
+### Phase 4: replace the theme contract
+
+1. Introduce source schema v2, semantic version 2, profile v2, and artifact v3.
+2. Remove `modifiers` from the source manifest and `CompiledTheme`.
+3. Reject v1 sources and artifacts with focused migration messages.
+4. Update CLI validation, inspection, and preview behavior.
+5. Regenerate the default dotLottie source and compiled artifact without modifier animations.
+6. Verify the regenerated artifact is reproducible and contains exactly twelve actions.
+
+### Phase 5: complete GNOME parity
+
+1. Add badge chip widgets and timing.
+2. Remove pointer-relative modifiers.
+3. Support compact badge content without a public label.
+4. Bump helper version and tests.
+5. Verify GNOME and shared-renderer state transitions against common fixtures.
+
+### Phase 6: gallery, documentation, and evidence
+
+1. Rebuild modifier gallery fixtures using complete `RenderStateCore` badge rendering.
+2. Update the combined foreground and pixel example.
+3. Add:
+ - full label with one chip
+ - full label with two chips
+ - contracted orb with one chip
+ - contracted orb with two chips
+ - no-label modifier capsule
+4. Regenerate the public delivery and target GIF.
+5. Update cursor personalization documentation and theme author instructions.
+6. Record native videos on macOS, Windows, X11, and Wayland.
+7. Upload durable review media to the implementation PR.
+
+## Test matrix
+
+### Shared unit tests
+
+- all delivery and target combinations
+- no label, short label, and maximum-length label
+- label ellipsis without wrapping
+- full and contracted layouts
+- stable delivery-then-target chip order
+- chip and text non-overlap
+- edge clamping on every screen edge
+- backing scale at 1x, 2x, 3x, and a fractional scale
+- reduced-motion still frames
+- modifier fade after one-shot, held, and looping actions
+- modifier changes while the session name is faded
+- action start does not restart the name timer
+- idle cursor fade hides all badge content
+- hover restores the full name without changing modifier state
+- v2 source manifests reject a `modifiers` section
+- v1 source and compiled artifacts produce focused rebuild guidance
+- compiled themes contain exactly the required action map and no modifier payload
+- delivery and target state no longer changes pointer pixels
+
+### Platform verification
+
+| Platform | Required evidence |
+| -------------- | ----------------------------------------------------------------------------------------------- |
+| macOS | Lume install from exact source SHA; full action sequence; hover reveal; edge placement; video |
+| Windows | GitHub Actions plus interactive VM when available; layered-window edges; two-chip layout; video |
+| Linux X11 | GitHub Actions or VM; tile bounds at all edges; two-chip layout; video |
+| Native Wayland | Shared-renderer chips and timing; bottom-edge clipping; documented hover limitation; video |
+| GNOME helper | Version handshake; label and chip timing; empty-label capsule; parity recording |
+
+Use semantic and pixel oracles. A successful tool result alone is not visual proof.
+Cursor review media must come from the overlay-enabled
+`agent_cursor_showcase_test`. The shared behavior matrix intentionally launches
+its daemons with `--no-overlay` so cursor pixels cannot contaminate its action
+oracles; those recordings prove tool behavior, not cursor rendering.
+
+## Documentation updates
+
+Update:
+
+- `libs/cua-driver/docs/cursor-themes.md`
+- the public cursor personalization page
+- `tools/cursor-gallery/README.md`
+- gallery headings, descriptions, combined-state examples, and legends
+- theme manifest examples
+- post-install or upgrade notes only if the GNOME helper requires user action
+
+Document clearly:
+
+- action animations belong to the pointer
+- delivery and target context belong to the badge
+- modifiers are host-rendered and not theme-customizable
+- v2 themes contain twelve action animations and no modifier animations
+- v1 themes must be rebuilt for the v2 contract
+- chips describe intended execution context only
+- Wayland hover limitations do not affect modifier rendering
+
+## Risks and mitigations
+
+| Risk | Mitigation |
+| ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| Chips are too small at 1x | Review exact production pixels before removing pointer modifiers; increase chip size only within the unchanged badge envelope |
+| Long labels collide with two chips | Measure and ellipsize text; never wrap |
+| Badge becomes too noisy | Do not reveal the name on action start; chips exist only during actions plus one shared trailing fade |
+| Existing v1 custom themes stop loading | Provide clear rebuild guidance in the CLI and upgrade documentation |
+| Platform geometry drifts | Centralize layout and extents; adapters consume shared outputs |
+| GNOME renderer drifts | Share protocol semantics and fixtures; version the helper; verify recordings |
+| Modifier chips are mistaken for permission status | Avoid security language and colors; explicitly document that they are informational |
+| Rollback crosses incompatible artifact versions | Keep the v2 source archive reproducible and document that driver and theme artifacts must move together |
+
+## Acceptance checklist
+
+- [x] Pointer action animations are unchanged.
+- [x] Pointer-relative modifier artwork is gone.
+- [x] Delivery and target chips can appear together in the badge.
+- [x] Session name and chips follow independent fade rules.
+- [x] Compact chip layout works with and without a public label.
+- [x] Badge height and maximum width remain unchanged.
+- [x] Platform dirty regions derive from shared extents.
+- [x] The v2 theme contract contains exactly twelve action animations.
+- [x] V1 source and compiled themes fail with clear rebuild guidance.
+- [x] Cursor overlay tests execute in CI.
+- [x] macOS, Windows, X11, native Wayland, and GNOME implementation paths are verified.
+- [x] Gallery, public docs, personalization docs, and review media are updated.
+
+## Implementation evidence
+
+The implementation was validated from the PR source with no failed behavioral
+cells:
+
+| Platform | Result |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| macOS Lume VM | 151 pass-equivalent cells: 143 delivered and 8 expected refusals |
+| Windows GitHub runner | 83 pass-equivalent cells: 61 delivered and 22 expected refusals |
+| Linux X11 GitHub runner | 82 pass-equivalent cells: 47 delivered and 35 expected refusals |
+| Native Wayland GitHub runner | 82 pass-equivalent cells: 47 delivered and 35 expected refusals |
+| Native cursor showcase | Overlay-enabled pixel oracle and move, click, type, scroll, and drag recording passed on Windows, X11, and Wayland |
+| GNOME helper | API version handshake, metadata, label and chip timing, compact layout, and Rust-to-helper parity tests passed |
+
+The PR also passes the Linux and Windows Rust suites, portable contract parity
+on macOS, Linux, and Windows, Nix builds and tests, generated contract checks,
+documentation synchronization, link checks, and publish-bundle validation.
+
+Native review recordings are attached to the PR for macOS, Windows, X11, and
+Wayland. A live GNOME Shell recording was not captured in this PR. The GNOME
+renderer is verified through its versioned helper contract and automated parity
+tests, while the other Linux recording exercises the shared renderer used by
+native Wayland.
+
+## Rollback
+
+The first two phases are additive and should remain even if the visual move is rejected because they fix test, padding, and label-layout defects.
+
+The behavioral switch can be rolled back by restoring the v1 default source and artifact together with modifier layer compositing. Because the contract is intentionally breaking, the driver and installed theme artifact version must move together.
+
+The GNOME helper and Rust helper-version pin must always roll forward or back together.
+
+## Review decisions
+
+The plan recommends:
+
+1. Show compact session-colored badge chrome for modifier-bearing actions even when the session has no public label.
+2. Replace the v1 theme contract instead of retaining unused modifier animations.
+3. Upgrade the GNOME helper atomically with the driver.
+4. Judge final chip size using the production renderer at 1x before removing pointer modifiers.
+
+The breaking theme-contract choice is approved. The remaining visual decisions are reviewed against exact production pixels.
diff --git a/libs/cua-driver/docs/cursor-themes.md b/libs/cua-driver/docs/cursor-themes.md
index a213e913f4..4ab01093a8 100644
--- a/libs/cua-driver/docs/cursor-themes.md
+++ b/libs/cua-driver/docs/cursor-themes.md
@@ -5,31 +5,40 @@ macOS, Windows, and Linux and cannot be removed. The theme uses a colored
pointer with a white outline over a larger, cursor-shaped glow in the same
session color. The glow softly fades to transparent around the full pointer
silhouette, while the white outline preserves a crisp boundary on light, dark,
-and similarly colored backgrounds. Its semantic action and modifier marks use
+and similarly colored backgrounds. Its semantic action marks use
the same session-colored center and white-outline treatment as the pointer,
plus a tighter, softer glow so they remain legible without competing with it.
Every semantic state inherits the same gentle levitation and rotation as the
-idle pointer, with its action-specific motion layered on top. The pointer,
-semantic mark, and active modifiers therefore move as one visual unit.
+idle pointer, with its action-specific motion layered on top. The pointer and
+semantic mark therefore move as one visual unit.
Reduced-motion mode removes this shared movement. The anonymous/default cursor
uses Cua blue. Named sessions receive a stable fill
from the built-in session palette, so concurrent agents remain visually
distinct.
-The native renderer places the sanitized public session name in a compact badge
-below the built-in pointer. The badge uses a session-accent gradient and a
-circular session marker. It appears when the cursor is first revealed, remains
-fully visible for two seconds, then fades over 400 milliseconds while the
-cursor stays available. Moving the human pointer over the synthetic cursor
-temporarily reveals the badge again, and moving it away hides the badge.
+The native renderer places the sanitized public session name and execution
+context in a compact badge below the built-in pointer. The badge uses a
+session-accent gradient and a circular session marker. The session name appears
+when the cursor is first revealed, remains fully visible for two seconds, then
+fades over 400 milliseconds while the cursor stays available. Moving the human
+pointer over the synthetic cursor temporarily reveals the name again, and
+moving it away hides the name.
Hiding and revealing the cursor also shows the badge again. Hover reveal uses
the native global-pointer APIs on macOS, Windows, and X11. Stock Wayland does
not expose another client's global pointer position, so native Wayland keeps
the timed reveal but cannot offer hover reveal without a compositor-owned
adapter. The click-through overlay never captures pointer input to fake this
capability.
-The badge is not part of the dotLottie theme artifact, so custom theme authors
-do not need to provide badge artwork or a font. Cua Driver strips control
+
+Delivery and target context appears as up to two chips inside the same badge.
+The delivery chip comes first and is filled; the target chip comes second and
+is outlined. Chips stay visible for the active action and fade over 400
+milliseconds when it ends. They do not reveal a session name that has already
+faded. An unlabeled session gets a compact marker-and-chips badge.
+
+The badge and its context glyphs are not part of the dotLottie theme artifact,
+so custom theme authors do not need to provide badge artwork or a font. Cua
+Driver strips control
characters, collapses whitespace, and shortens labels longer than 28 characters
before rendering the bundled Inter typeface.
@@ -101,9 +110,7 @@ A full custom theme must provide all twelve action animations:
| `record` | loop |
| `system` | one shot |
-It must also provide six transparent modifier animations. The renderer
-composites at most one delivery modifier and one target modifier over the
-action:
+Delivery and target context is host-owned rather than theme-owned:
- delivery: `background`, `foreground`
- target: `ax`, `pixel`, `browser`, `desktop`
@@ -127,12 +134,12 @@ theme.lottie
Every animation must be a transparent 128×128 Lottie animation at 30 fps and
contain no more than 120 frames. A compiled theme may contain at most 1,000
-frames in total across its actions and modifiers. The compiler samples
+frames in total across its actions. The compiler samples
animation timing at 30 fps but preserves the artwork as vector paths, ellipses,
rounded rectangles, solid fills, strokes, and transforms. The overlay then
rasterizes those commands at the display's live backing scale.
-Profile v1 accepts shape layers with static path geometry and animated layer
+Profile v2 accepts shape layers with static path geometry and animated layer
position, scale, rotation, opacity, solid color, and stroke width. Shape-layer
transforms must remain at their identity values; place animation on the layer
transform instead. Groups, animated path geometry, expressions, scripts,
@@ -144,15 +151,15 @@ unbounded archives, and other unsupported Lottie features are rejected.
```json
{
- "schema": "cua.cursor-theme/1",
+ "schema": "cua.cursor-theme/2",
"id": "com.example.cursor.studio",
"name": "Studio Cursor",
"version": "1.0.0",
"author": "Example Studio",
"license": "MIT",
"compatibility": {
- "profile": "cua-driver-full-v1",
- "semantics": 1
+ "profile": "cua-driver-actions-v2",
+ "semantics": 2
},
"canvas": { "width": 128, "height": 128, "fps": 30 },
"hotspot": { "x": 55, "y": 30 },
@@ -169,22 +176,19 @@ unbounded archives, and other unsupported Lottie features are rejected.
"transfer": { "animation": "action_transfer", "still_frame": 16 },
"record": { "animation": "action_record", "still_frame": 16 },
"system": { "animation": "action_system", "still_frame": 18 }
- },
- "modifiers": {
- "background": { "animation": "modifier_background", "still_frame": 0 },
- "foreground": { "animation": "modifier_foreground", "still_frame": 0 },
- "ax": { "animation": "modifier_ax", "still_frame": 0 },
- "pixel": { "animation": "modifier_pixel", "still_frame": 0 },
- "browser": { "animation": "modifier_browser", "still_frame": 0 },
- "desktop": { "animation": "modifier_desktop", "still_frame": 0 }
}
}
```
The `still_frame` is used when reduced motion is active. Use a reverse-DNS
-theme ID. Profile v1 does not compile dotLottie color/theme variants; publish a
+theme ID. Profile v2 does not compile dotLottie color/theme variants; publish a
visually distinct variant under a separate theme ID.
+Profile v2 is intentionally breaking. V1 source manifests and compiled
+artifacts are rejected with rebuild guidance. Remove the `modifiers` section,
+set the schema and semantic version to 2, use the
+`cua-driver-actions-v2` profile, and rebuild the artifact.
+
## Validate, compile, and install
Run the authoring workflow locally, outside an agent tool call:
@@ -224,7 +228,8 @@ The built-in default follows the same path. Its canonical
`cursor-overlay/assets/`. The resulting bounded `cua.default.cua-theme` is
embedded in the binary and decoded by the same renderer used for installed
custom themes. Only the embedded default receives the runtime session-color
-tint and shared float transform. The artifact contains no fixed-resolution
+tint and shared float transform. Delivery and target chips remain consistent
+because the host badge renders them for every theme. The artifact contains no fixed-resolution
pixel atlas, so the cursor stays crisp at 1×, 2×, 3×, and fractional display
scales.
diff --git a/libs/cua-driver/docs/test-harnesses-guide.md b/libs/cua-driver/docs/test-harnesses-guide.md
index cb4e03a290..7c6a01f96c 100644
--- a/libs/cua-driver/docs/test-harnesses-guide.md
+++ b/libs/cua-driver/docs/test-harnesses-guide.md
@@ -62,12 +62,12 @@ cua/
The important separation is:
-| Layer | Owns | Does not own |
-| --- | --- | --- |
-| Rust integration test | Scenarios, driver calls, assertions, action metadata | OS setup and fixture compilation |
-| `cua-driver-testkit` | Session helpers, fixture launching, screenshots, recordings, trajectories | The scenario list |
-| Fixture app | Visible controls and externally observable state markers | Driver correctness assertions |
-| OS runner | Build environment, user session, test selection, artifact collection | Test behavior definitions |
+| Layer | Owns | Does not own |
+| --------------------- | ------------------------------------------------------------------------- | -------------------------------- |
+| Rust integration test | Scenarios, driver calls, assertions, action metadata | OS setup and fixture compilation |
+| `cua-driver-testkit` | Session helpers, fixture launching, screenshots, recordings, trajectories | The scenario list |
+| Fixture app | Visible controls and externally observable state markers | Driver correctness assertions |
+| OS runner | Build environment, user session, test selection, artifact collection | Test behavior definitions |
There is deliberately no second Python E2E implementation that the Rust suite
has to mirror.
@@ -100,13 +100,13 @@ refusal and the absence of focus or input side effects.
These run without a repo-local GUI application and normally run without
`--ignored`:
-| Location or prefix | What it proves |
-| --- | --- |
-| `rust/crates/*/src/**` | Core driver, platform-independent logic, schemas, and helpers |
-| `protocol_*_test.rs` | MCP handshake, tool calls, sessions, media, and errors |
-| `schema_*_test.rs` | Shared schema and backend consistency |
-| `transport_config_persistence_test.rs` | CLI/MCP configuration persistence |
-| `protocol_element_token_test.rs` | Element-token protocol behavior |
+| Location or prefix | What it proves |
+| -------------------------------------- | ------------------------------------------------------------- |
+| `rust/crates/*/src/**` | Core driver, platform-independent logic, schemas, and helpers |
+| `protocol_*_test.rs` | MCP handshake, tool calls, sessions, media, and errors |
+| `schema_*_test.rs` | Shared schema and backend consistency |
+| `transport_config_persistence_test.rs` | CLI/MCP configuration persistence |
+| `protocol_element_token_test.rs` | Element-token protocol behavior |
These tests should be fast, deterministic, and safe to run on ordinary CI
workers. They do not prove that a real click, key, scroll, or background input
@@ -126,9 +126,9 @@ ordinary unit command.
The canonical E2E suite has two behavior owners:
-| Owner | Purpose |
-| --- | --- |
-| Shared app | Same web behavior tested through Electron and Tauri |
+| Owner | Purpose |
+| -------------- | ---------------------------------------------------- |
+| Shared app | Same web behavior tested through Electron and Tauri |
| Native harness | Toolkit-specific controls and native window behavior |
WebView, CDP, and page-tool integration stays inside the shared or native
@@ -149,16 +149,16 @@ invocation.
Runner: `scripts/ci/windows/run-rust-e2e.ps1`
-| Runner area | Rust test | Real harness or app |
-| --- | --- | --- |
-| Shared app matrix | `cross_platform_behavior_test.rs` | Electron and Tauri |
-| Native controls | `harness_wpf_test.rs` | Repo-local WPF app |
-| Native controls | `harness_winui3_test.rs` | Repo-local WinUI3 app |
-| Web integration | `harness_web_test.rs` | WebView2 and Electron |
-| Capture contract | `capture_contract_test.rs` | WPF plus driver tree/image output |
-| Launch contract | `launch_windows_test.rs` | Repo-local Electron launch and focus behavior |
-| Agent cursor | `agent_cursor_windows_test.rs` | Source-built cursor overlay and pixel evidence |
-| Desktop scope | `desktop_scope_windows_test.rs` | Windowless desktop input and scope rejection |
+| Runner area | Rust test | Real harness or app |
+| ----------------- | --------------------------------- | ---------------------------------------------- |
+| Shared app matrix | `cross_platform_behavior_test.rs` | Electron and Tauri |
+| Native controls | `harness_wpf_test.rs` | Repo-local WPF app |
+| Native controls | `harness_winui3_test.rs` | Repo-local WinUI3 app |
+| Web integration | `harness_web_test.rs` | WebView2 and Electron |
+| Capture contract | `capture_contract_test.rs` | WPF plus driver tree/image output |
+| Launch contract | `launch_windows_test.rs` | Repo-local Electron launch and focus behavior |
+| Agent cursor | `agent_cursor_windows_test.rs` | Source-built cursor overlay and pixel evidence |
+| Desktop scope | `desktop_scope_windows_test.rs` | Windowless desktop input and scope rejection |
Cross-cutting instrumentation used by these rows includes the testkit
`DesktopObserver`, capture validation, cursor evidence, and desktop-scope
@@ -174,16 +174,16 @@ background delivery is tested.
Runner: `libs/cua-driver/tests/runners/macos-lume/run-all.sh`
-| Runner area | Rust test | Real harness or app |
-| --- | --- | --- |
-| Shared app matrix | `cross_platform_behavior_test.rs` | Electron and Tauri |
-| Native web matrix | `cross_platform_behavior_test.rs` | Repo-local WKWebView host |
-| Native controls | `harness_appkit_test.rs` | Repo-local AppKit app |
-| Native controls | `harness_swiftui_test.rs` | Repo-local SwiftUI app |
-| Installed app launch | `installed_app_launch_macos_test.rs` | Calculator and TextEdit |
-| Installed app AX delivery | `installed_app_textedit_macos_test.rs` | TextEdit |
-| Capture contract | `capture_contract_test.rs` | Installed driver and macOS capture APIs |
-| Desktop scope | `desktop_scope_macos_test.rs` | macOS window and desktop scope |
+| Runner area | Rust test | Real harness or app |
+| ------------------------- | -------------------------------------- | --------------------------------------- |
+| Shared app matrix | `cross_platform_behavior_test.rs` | Electron and Tauri |
+| Native web matrix | `cross_platform_behavior_test.rs` | Repo-local WKWebView host |
+| Native controls | `harness_appkit_test.rs` | Repo-local AppKit app |
+| Native controls | `harness_swiftui_test.rs` | Repo-local SwiftUI app |
+| Installed app launch | `installed_app_launch_macos_test.rs` | Calculator and TextEdit |
+| Installed app AX delivery | `installed_app_textedit_macos_test.rs` | TextEdit |
+| Capture contract | `capture_contract_test.rs` | Installed driver and macOS capture APIs |
+| Desktop scope | `desktop_scope_macos_test.rs` | macOS window and desktop scope |
The WKWebView host runs the same typed shared-web catalog as Electron and
Tauri. Calculator and TextEdit add typed supporting rows for built-in app
@@ -197,12 +197,12 @@ to `scripts/ci/macos/run-rust-e2e.sh`.
Runner: `scripts/ci/linux/run-rust-e2e.sh`
-| Runner area | Rust test | Real harness or app |
-| --- | --- | --- |
-| Shared app matrix | `cross_platform_behavior_test.rs` | Electron and Tauri |
-| Native controls | `harness_gtk3_test.rs` | Repo-local GTK3 app |
-| Capture contract | `capture_contract_test.rs` | Linux capture backend |
-| Desktop scope | `desktop_scope_linux_test.rs` | X11/Wayland desktop scope |
+| Runner area | Rust test | Real harness or app |
+| ----------------- | --------------------------------- | ------------------------- |
+| Shared app matrix | `cross_platform_behavior_test.rs` | Electron and Tauri |
+| Native controls | `harness_gtk3_test.rs` | Repo-local GTK3 app |
+| Capture contract | `capture_contract_test.rs` | Linux capture backend |
+| Desktop scope | `desktop_scope_linux_test.rs` | X11/Wayland desktop scope |
Linux has separate X11 and Wayland concerns. Nix supplies the reproducible
build and desktop environment, but the E2E test still needs an actual X11 or
@@ -230,14 +230,14 @@ delivery, refusal, and unproven-action ledger.
These terms describe different dimensions:
-| Term | Meaning |
-| --- | --- |
-| AX | Address a target through its accessibility/UI automation element |
-| PX | Address a target by screen coordinates or pointer geometry |
-| Foreground | The target may be brought to the foreground for delivery |
-| Background | The target should receive the action without being raised or stealing focus |
-| Window scope | Capture or action is limited to one target window |
-| Desktop scope | Capture or action covers the full desktop |
+| Term | Meaning |
+| ------------- | --------------------------------------------------------------------------- |
+| AX | Address a target through its accessibility/UI automation element |
+| PX | Address a target by screen coordinates or pointer geometry |
+| Foreground | The target may be brought to the foreground for delivery |
+| Background | The target should receive the action without being raised or stealing focus |
+| Window scope | Capture or action is limited to one target window |
+| Desktop scope | Capture or action covers the full desktop |
The shared and native action matrices should test left click, right click,
double click, typing, keys, hotkeys, scroll, child windows, and drag across
@@ -267,14 +267,14 @@ sentinel journals keyboard, pointer, wheel, visibility, focus, and heartbeat
events while it fully covers the target. Background rows opt into both pieces
of instrumentation directly; there is no special guard suite.
-| Invariant or scenario | What it checks |
-| --- | --- |
+| Invariant or scenario | What it checks |
+| ------------------------- | ---------------------------------------------------------------------------- |
| Background click/type/key | The target action does not move focus away from the user's foreground window |
-| Minimized app launch | `launch_app(start_minimized=true)` does not raise the new app |
-| Background hotkey | A keyboard chord does not steal focus |
-| Child-window click | A target-created window does not unexpectedly become foreground |
-| Background screenshot | Reading the target does not change focus or z-order |
-| Agent cursor visibility | The cursor appears in the captured pixels when enabled and moved |
+| Minimized app launch | `launch_app(start_minimized=true)` does not raise the new app |
+| Background hotkey | A keyboard chord does not steal focus |
+| Child-window click | A target-created window does not unexpectedly become foreground |
+| Background screenshot | Reading the target does not change focus or z-order |
+| Agent cursor visibility | The cursor appears in the captured pixels when enabled and moved |
The sentinel contract fails closed when the target is only partly covered or
the heartbeat stops. Before any behavioral cells run, the strict environment
@@ -343,6 +343,10 @@ need normal test output and logs; they do not need desktop video.
posture. A 300 ms baseline precedes dispatch, and capture continues through
external oracle collection. `trajectory.json` must finish with
`behavior_video.status = "finalized"`.
+- Use `agent_cursor_showcase_test` for cursor review media. Shared behavior
+ matrix daemons deliberately use `--no-overlay` so synthetic cursor pixels do
+ not contaminate action oracles; their videos prove tool behavior, not cursor
+ rendering.
- Windows hosted runs use `GetConsoleWindow` to select the inherited
HostedComputeAgent/runner console, verify its identity, and minimize it
through `ShowWindow(SW_MINIMIZE)` before fixture or sentinel posture is
diff --git a/libs/cua-driver/rust/Skills/cua-driver/SKILL.md b/libs/cua-driver/rust/Skills/cua-driver/SKILL.md
index 906a52f5c7..339d8820a6 100644
--- a/libs/cua-driver/rust/Skills/cua-driver/SKILL.md
+++ b/libs/cua-driver/rust/Skills/cua-driver/SKILL.md
@@ -168,7 +168,7 @@ default for declared sessions; anonymous actions remain cursor-less. Toggle with
`set_agent_cursor_enabled` to hide or re-show it. The embedded
`cua.default` theme uses a session-colored pointer over a larger,
cursor-shaped glow in the same session color. The glow fades to transparent
-around the full silhouette. Action and modifier marks use the same
+around the full silhouette. Action marks use the same
session-colored center and white-outline treatment, plus a tighter, softer
glow. This pairing preserves contrast across varied backgrounds. It provides animations for
idle, observe, click, drag, scroll, text, key, navigation, app, transfer,
@@ -177,6 +177,11 @@ recording, and system activity. Motion knobs:
`end_handle`, `arc_size`, `arc_flow`, `spring` — tuneable at runtime,
persisted to config.
+Delivery and target context is shown as host-owned chips inside the session
+badge. Themes own the twelve action animations only. The session name and
+context chips fade independently, so an active tool can show its execution
+context without revealing a session name that has already faded.
+
**Per-session cursors.** Each MCP session automatically owns its own
cursor, keyed by the session's id (the proxy mints one session id per
MCP connection and the daemon scopes the cursor, config overrides, and
diff --git a/libs/cua-driver/rust/crates/cursor-overlay/assets/README.md b/libs/cua-driver/rust/crates/cursor-overlay/assets/README.md
index 2629823d76..f6fab52dee 100644
--- a/libs/cua-driver/rust/crates/cursor-overlay/assets/README.md
+++ b/libs/cua-driver/rust/crates/cursor-overlay/assets/README.md
@@ -28,4 +28,5 @@ inside the compiled artifact matches the checked-in `.lottie` bytes.
The source uses Cua blue as a palette key and white for outlines. At runtime,
only the embedded default is recolored to the stable session fill. Installed
custom themes retain their authored colors. The shared floating motion is
-applied after compositing so action and modifier layers remain synchronized.
+applied to the selected action animation. Delivery and target context is
+painted by the host-owned session badge and is not part of theme artifacts.
diff --git a/libs/cua-driver/rust/crates/cursor-overlay/assets/build_default_theme.py b/libs/cua-driver/rust/crates/cursor-overlay/assets/build_default_theme.py
index 759842fb30..681f5aac32 100644
--- a/libs/cua-driver/rust/crates/cursor-overlay/assets/build_default_theme.py
+++ b/libs/cua-driver/rust/crates/cursor-overlay/assets/build_default_theme.py
@@ -12,7 +12,7 @@ The runtime applies two bounded effects after decoding the compiled theme:
* the shared four-second float transform is applied to the composed theme.
Those effects are runtime concerns because they must stay synchronized across
-the action, delivery, and target layers.
+all action layers. Delivery and target context is rendered by the host badge.
"""
from __future__ import annotations
@@ -584,85 +584,8 @@ def action_system() -> dict[str, Any]:
return lottie("action_system", frames, [*cursor_layers(frames), *cue])
-def modifier_layers(name: str, geometry: Sequence[dict[str, Any]], *, width: float = 2.5) -> dict[str, Any]:
- return lottie(
- f"modifier_{name}",
- 1,
- cue_layers(1, name.title(), geometry, 1, width=width),
- )
-
-
-def modifier_background() -> dict[str, Any]:
- dots = [
- ellipse(x, y, 3, 3, name=f"Background dot {index}")
- for index, (x, y) in enumerate(
- [(34, 23), (27, 28), (22, 35), (19, 44), (20, 54), (22, 64), (26, 74), (32, 84), (39, 94), (48, 102)]
- )
- ]
- layers = [
- shape_layer(1, "Background outline", [*dots, fill(WHITE)], 1),
- shape_layer(2, "Background color", [*dots, fill(BLUE)], 1, scale=static([62, 62])),
- ]
- return lottie("modifier_background", 1, layers)
-
-
-def modifier_foreground() -> dict[str, Any]:
- return modifier_layers("foreground", [ellipse(25, 90, 18, 18, name="Foreground ring")], width=3)
-
-
-def modifier_ax() -> dict[str, Any]:
- geometry = [
- ellipse(x, y, 6, 6, name=f"AX node {index}")
- for index, (x, y) in enumerate([(104, 89), (94, 104), (114, 104)])
- ]
- geometry.extend(
- [
- points([(104, 92), (104, 97), (94, 101)], name="AX left"),
- points([(104, 97), (114, 101)], name="AX right"),
- ]
- )
- return modifier_layers("ax", geometry)
-
-
-def modifier_pixel() -> dict[str, Any]:
- geometry = [
- points(segment, name=f"Pixel segment {index}")
- for index, segment in enumerate(
- [
- [(94, 91), (100, 91)],
- [(106, 91), (113, 91)],
- [(113, 91), (113, 98)],
- [(113, 104), (113, 110)],
- [(113, 110), (106, 110)],
- [(100, 110), (94, 110)],
- [(94, 110), (94, 104)],
- [(94, 98), (94, 91)],
- ]
- )
- ]
- return modifier_layers("pixel", geometry)
-
-
-def modifier_browser() -> dict[str, Any]:
- geometry = [
- ellipse(104, 100, 20, 20, name="Browser globe"),
- points([(94, 100), (114, 100)], name="Browser equator"),
- points([(104, 90), (100, 100), (104, 110)], name="Browser left"),
- points([(104, 90), (108, 100), (104, 110)], name="Browser right"),
- ]
- return modifier_layers("browser", geometry)
-
-
-def modifier_desktop() -> dict[str, Any]:
- geometry = [
- rectangle(103.5, 97.5, 21, 15, roundness=2, name="Desktop screen"),
- points([(103.5, 105), (103.5, 110), (97, 110), (110, 110)], name="Desktop stand"),
- ]
- return modifier_layers("desktop", geometry)
-
-
def all_animations() -> dict[str, dict[str, Any]]:
- actions = {
+ return {
"action_idle": action_idle(),
"action_observe": action_observe(),
"action_click": action_click(),
@@ -676,15 +599,6 @@ def all_animations() -> dict[str, dict[str, Any]]:
"action_record": action_record(),
"action_system": action_system(),
}
- modifiers = {
- "modifier_background": modifier_background(),
- "modifier_foreground": modifier_foreground(),
- "modifier_ax": modifier_ax(),
- "modifier_pixel": modifier_pixel(),
- "modifier_browser": modifier_browser(),
- "modifier_desktop": modifier_desktop(),
- }
- return {**actions, **modifiers}
def semantic_manifest() -> dict[str, Any]:
@@ -707,20 +621,16 @@ def semantic_manifest() -> dict[str, Any]:
}
actions["click"]["still_frame"] = 8
return {
- "schema": "cua.cursor-theme/1",
+ "schema": "cua.cursor-theme/2",
"id": "cua.default",
"name": "Cua Default",
- "version": "1.0.0",
+ "version": "2.0.0",
"author": "Cua",
"license": "MIT",
- "compatibility": {"profile": "cua-driver-full-v1", "semantics": 1},
+ "compatibility": {"profile": "cua-driver-actions-v2", "semantics": 2},
"canvas": {"width": CANVAS, "height": CANVAS, "fps": FPS},
"hotspot": {"x": 55, "y": 30},
"actions": actions,
- "modifiers": {
- name: {"animation": f"modifier_{name}", "still_frame": 0}
- for name in ["background", "foreground", "ax", "pixel", "browser", "desktop"]
- },
}
diff --git a/libs/cua-driver/rust/crates/cursor-overlay/assets/cua.default.cua-theme b/libs/cua-driver/rust/crates/cursor-overlay/assets/cua.default.cua-theme
index f37618bd46..0beb13487d 100644
Binary files a/libs/cua-driver/rust/crates/cursor-overlay/assets/cua.default.cua-theme and b/libs/cua-driver/rust/crates/cursor-overlay/assets/cua.default.cua-theme differ
diff --git a/libs/cua-driver/rust/crates/cursor-overlay/assets/cua.default.lottie b/libs/cua-driver/rust/crates/cursor-overlay/assets/cua.default.lottie
index d0bf16bd37..7eb34db807 100644
Binary files a/libs/cua-driver/rust/crates/cursor-overlay/assets/cua.default.lottie and b/libs/cua-driver/rust/crates/cursor-overlay/assets/cua.default.lottie differ
diff --git a/libs/cua-driver/rust/crates/cursor-overlay/examples/export_gallery_frames.rs b/libs/cua-driver/rust/crates/cursor-overlay/examples/export_gallery_frames.rs
index aedc75a857..51657088ea 100644
--- a/libs/cua-driver/rust/crates/cursor-overlay/examples/export_gallery_frames.rs
+++ b/libs/cua-driver/rust/crates/cursor-overlay/examples/export_gallery_frames.rs
@@ -1,9 +1,8 @@
use cursor_overlay::{
- render_frame, theme::paint_default_theme, CursorAction, CursorConfig, CursorVisualState,
- DeliveryModifier, OverlayCommand, ReducedMotion, RenderStateCore, TargetModifier,
+ render_frame, CursorAction, CursorConfig, DeliveryModifier, OverlayCommand, RenderStateCore,
+ TargetModifier,
};
use std::{fs, path::Path};
-use tiny_skia::Pixmap;
const SIZE: u32 = 256;
const FPS: u32 = 30;
@@ -73,6 +72,15 @@ fn export_session_badge(output: &Path) {
false,
false,
);
+ core.apply_command_base(
+ OverlayCommand::BeginAction {
+ action: CursorAction::Observe,
+ delivery: Some(DeliveryModifier::Background),
+ target: Some(TargetModifier::Browser),
+ },
+ false,
+ false,
+ );
core.tick_motion(f64::from(frame) / f64::from(FPS));
let pixmap = render_frame(&core, SIZE, SIZE, 0.0, 0.0, None, PREVIEW_BACKING_SCALE);
let pixels = unpremultiply_rgba(pixmap.data().to_vec());
@@ -96,26 +104,26 @@ fn export_state(
) {
fs::create_dir_all(output).expect("create frame output");
for frame in 0..FPS * DURATION_SECS {
- let mut pixmap = Pixmap::new(SIZE, SIZE).expect("create frame");
- let visual = CursorVisualState {
- requested_action: action,
- resolved_action: action,
- delivery,
- target,
- elapsed_secs: f64::from(frame) / f64::from(FPS),
- ending_secs: None,
- reduced_motion: ReducedMotion::Off,
- preempted_count: 0,
- };
- paint_default_theme(
- &mut pixmap,
- &visual,
- SIZE as f32 / 2.0,
- SIZE as f32 / 2.0,
- std::f32::consts::FRAC_PI_4,
- PREVIEW_BACKING_SCALE,
- 1.0,
+ let mut config = CursorConfig::default();
+ config.cursor_id = "gallery-session".into();
+ let mut core = RenderStateCore::new(config);
+ core.motion.idle_hide_ms = 0.0;
+ core.pos = (
+ f64::from(SIZE) / (2.0 * f64::from(PREVIEW_BACKING_SCALE)),
+ f64::from(SIZE) / (2.0 * f64::from(PREVIEW_BACKING_SCALE)),
);
+ core.heading = f64::from(std::f32::consts::FRAC_PI_4);
+ core.apply_command_base(
+ OverlayCommand::BeginAction {
+ action,
+ delivery,
+ target,
+ },
+ false,
+ false,
+ );
+ core.visual.elapsed_secs = f64::from(frame) / f64::from(FPS);
+ let pixmap = render_frame(&core, SIZE, SIZE, 0.0, 0.0, None, PREVIEW_BACKING_SCALE);
let pixels = unpremultiply_rgba(pixmap.data().to_vec());
image::save_buffer_with_format(
output.join(format!("{frame:04}.png")),
diff --git a/libs/cua-driver/rust/crates/cursor-overlay/src/badge_glyphs.rs b/libs/cua-driver/rust/crates/cursor-overlay/src/badge_glyphs.rs
new file mode 100644
index 0000000000..0279863903
--- /dev/null
+++ b/libs/cua-driver/rust/crates/cursor-overlay/src/badge_glyphs.rs
@@ -0,0 +1,306 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Cua AI, Inc.
+
+//! Host-owned delivery and target glyphs painted inside the session badge.
+//!
+//! These glyphs deliberately sit outside cursor theme artifacts. Themes own
+//! action artwork; the host owns the compact, upright execution-context marks
+//! that must remain consistent across platforms and themes.
+
+use crate::{DeliveryModifier, TargetModifier};
+use tiny_skia::{
+ Color, FillRule, LineCap, LineJoin, Paint, Path, PathBuilder, Pixmap, Rect, Stroke, Transform,
+};
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum BadgeGlyph {
+ Background,
+ Foreground,
+ Ax,
+ Pixel,
+ Browser,
+ Desktop,
+}
+
+impl From<DeliveryModifier> for BadgeGlyph {
+ fn from(value: DeliveryModifier) -> Self {
+ match value {
+ DeliveryModifier::Background => Self::Background,
+ DeliveryModifier::Foreground => Self::Foreground,
+ }
+ }
+}
+
+impl From<TargetModifier> for BadgeGlyph {
+ fn from(value: TargetModifier) -> Self {
+ match value {
+ TargetModifier::Ax => Self::Ax,
+ TargetModifier::Pixel => Self::Pixel,
+ TargetModifier::Browser => Self::Browser,
+ TargetModifier::Desktop => Self::Desktop,
+ }
+ }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct BadgeChip {
+ pub glyph: BadgeGlyph,
+ pub rect: Rect,
+ pub filled: bool,
+}
+
+fn rounded_rect(rect: Rect, radius: f32) -> Option<Path> {
+ const K: f32 = 0.552_284_8;
+ let x = rect.x();
+ let y = rect.y();
+ let width = rect.width();
+ let height = rect.height();
+ let radius = radius.min(width * 0.5).min(height * 0.5).max(0.0);
+ let mut builder = PathBuilder::new();
+ builder.move_to(x + radius, y);
+ builder.line_to(x + width - radius, y);
+ builder.cubic_to(
+ x + width - radius + radius * K,
+ y,
+ x + width,
+ y + radius - radius * K,
+ x + width,
+ y + radius,
+ );
+ builder.line_to(x + width, y + height - radius);
+ builder.cubic_to(
+ x + width,
+ y + height - radius + radius * K,
+ x + width - radius + radius * K,
+ y + height,
+ x + width - radius,
+ y + height,
+ );
+ builder.line_to(x + radius, y + height);
+ builder.cubic_to(
+ x + radius - radius * K,
+ y + height,
+ x,
+ y + height - radius + radius * K,
+ x,
+ y + height - radius,
+ );
+ builder.line_to(x, y + radius);
+ builder.cubic_to(
+ x,
+ y + radius - radius * K,
+ x + radius - radius * K,
+ y,
+ x + radius,
+ y,
+ );
+ builder.close();
+ builder.finish()
+}
+
+fn paint_color(color: [u8; 4], alpha_scale: f32) -> Paint<'static> {
+ Paint {
+ shader: tiny_skia::Shader::SolidColor(Color::from_rgba8(
+ color[0],
+ color[1],
+ color[2],
+ (f32::from(color[3]) * alpha_scale.clamp(0.0, 1.0)).round() as u8,
+ )),
+ anti_alias: true,
+ ..Default::default()
+ }
+}
+
+fn stroke_path(pixmap: &mut Pixmap, path: &Path, width: f32, alpha: f32) {
+ pixmap.stroke_path(
+ path,
+ &paint_color([255, 255, 255, 238], alpha),
+ &Stroke {
+ width,
+ line_cap: LineCap::Round,
+ line_join: LineJoin::Round,
+ ..Default::default()
+ },
+ Transform::identity(),
+ None,
+ );
+}
+
+fn line_path(points: &[(f32, f32)]) -> Option<Path> {
+ let (&(x, y), rest) = points.split_first()?;
+ let mut builder = PathBuilder::new();
+ builder.move_to(x, y);
+ for &(x, y) in rest {
+ builder.line_to(x, y);
+ }
+ builder.finish()
+}
+
+fn circle_path(x: f32, y: f32, radius: f32) -> Option<Path> {
+ PathBuilder::from_circle(x, y, radius)
+}
+
+pub(crate) fn paint_badge_chip(
+ pixmap: &mut Pixmap,
+ chip: BadgeChip,
+ session_fill: [u8; 4],
+ alpha: f32,
+) {
+ let alpha = alpha.clamp(0.0, 1.0);
+ if alpha <= 0.0 {
+ return;
+ }
+ let rect = chip.rect;
+ let scale = (rect.width() / 18.0).max(0.5);
+ let Some(well) = rounded_rect(rect, 5.0 * scale) else {
+ return;
+ };
+ if chip.filled {
+ pixmap.fill_path(
+ &well,
+ &paint_color(
+ [session_fill[0], session_fill[1], session_fill[2], 220],
+ alpha,
+ ),
+ FillRule::Winding,
+ Transform::identity(),
+ None,
+ );
+ stroke_path(pixmap, &well, 1.0 * scale, alpha * 0.72);
+ } else {
+ pixmap.fill_path(
+ &well,
+ &paint_color([255, 255, 255, 22], alpha),
+ FillRule::Winding,
+ Transform::identity(),
+ None,
+ );
+ stroke_path(pixmap, &well, 1.0 * scale, alpha * 0.42);
+ }
+
+ let x = rect.x();
+ let y = rect.y();
+ let left = x + 4.0 * scale;
+ let right = x + 14.0 * scale;
+ let top = y + 4.0 * scale;
+ let bottom = y + 14.0 * scale;
+ let cx = x + 9.0 * scale;
+ let cy = y + 9.0 * scale;
+ let width = 1.35 * scale;
+
+ match chip.glyph {
+ BadgeGlyph::Background => {
+ for (offset, opacity) in [(0.0, 0.58), (2.4 * scale, 1.0)] {
+ let Some(layer_rect) =
+ Rect::from_xywh(left + offset, top + offset, 7.0 * scale, 7.0 * scale)
+ else {
+ continue;
+ };
+ if let Some(layer) = rounded_rect(layer_rect, 1.8 * scale) {
+ stroke_path(pixmap, &layer, width, alpha * opacity);
+ }
+ }
+ }
+ BadgeGlyph::Foreground => {
+ let Some(window_rect) = Rect::from_xywh(left, top + scale, 10.0 * scale, 9.0 * scale)
+ else {
+ return;
+ };
+ if let Some(window) = rounded_rect(window_rect, 1.8 * scale) {
+ stroke_path(pixmap, &window, width, alpha);
+ }
+ if let Some(title) = line_path(&[
+ (left + scale, top + 3.6 * scale),
+ (right - scale, top + 3.6 * scale),
+ ]) {
+ stroke_path(pixmap, &title, width, alpha);
+ }
+ }
+ BadgeGlyph::Ax => {
+ if let Some(connectors) =
+ line_path(&[(cx, top + scale), (cx, cy), (left + scale, bottom - scale)])
+ {
+ stroke_path(pixmap, &connectors, width, alpha);
+ }
+ if let Some(right_connector) = line_path(&[(cx, cy), (right - scale, bottom - scale)]) {
+ stroke_path(pixmap, &right_connector, width, alpha);
+ }
+ for (x, y) in [
+ (cx, top + scale),
+ (left + scale, bottom - scale),
+ (right - scale, bottom - scale),
+ ] {
+ if let Some(node) = circle_path(x, y, 1.35 * scale) {
+ pixmap.fill_path(
+ &node,
+ &paint_color([255, 255, 255, 245], alpha),
+ FillRule::Winding,
+ Transform::identity(),
+ None,
+ );
+ }
+ }
+ }
+ BadgeGlyph::Pixel => {
+ for points in [
+ [
+ (left, top + 3.0 * scale),
+ (left, top),
+ (left + 3.0 * scale, top),
+ ],
+ [
+ (right - 3.0 * scale, top),
+ (right, top),
+ (right, top + 3.0 * scale),
+ ],
+ [
+ (right, bottom - 3.0 * scale),
+ (right, bottom),
+ (right - 3.0 * scale, bottom),
+ ],
+ [
+ (left + 3.0 * scale, bottom),
+ (left, bottom),
+ (left, bottom - 3.0 * scale),
+ ],
+ ] {
+ if let Some(path) = line_path(&points) {
+ stroke_path(pixmap, &path, width, alpha);
+ }
+ }
+ }
+ BadgeGlyph::Browser => {
+ if let Some(globe) = circle_path(cx, cy, 5.0 * scale) {
+ stroke_path(pixmap, &globe, width, alpha);
+ }
+ if let Some(equator) = line_path(&[(left, cy), (right, cy)]) {
+ stroke_path(pixmap, &equator, width * 0.9, alpha);
+ }
+ if let Some(meridian) = line_path(&[
+ (cx, top),
+ (cx - 2.0 * scale, cy),
+ (cx, bottom),
+ (cx + 2.0 * scale, cy),
+ (cx, top),
+ ]) {
+ stroke_path(pixmap, &meridian, width * 0.85, alpha);
+ }
+ }
+ BadgeGlyph::Desktop => {
+ let Some(screen_rect) = Rect::from_xywh(left, top, 10.0 * scale, 7.6 * scale) else {
+ return;
+ };
+ if let Some(screen) = rounded_rect(screen_rect, 1.3 * scale) {
+ stroke_path(pixmap, &screen, width, alpha);
+ }
+ if let Some(stand) = line_path(&[
+ (cx, top + 7.6 * scale),
+ (cx, bottom),
+ (cx - 3.0 * scale, bottom),
+ (cx + 3.0 * scale, bottom),
+ ]) {
+ stroke_path(pixmap, &stand, width, alpha);
+ }
+ }
+ }
+}
diff --git a/libs/cua-driver/rust/crates/cursor-overlay/src/lib.rs b/libs/cua-driver/rust/crates/cursor-overlay/src/lib.rs
index e8d4583dd4..f5ab60eb1c 100644
--- a/libs/cua-driver/rust/crates/cursor-overlay/src/lib.rs
+++ b/libs/cua-driver/rust/crates/cursor-overlay/src/lib.rs
@@ -6,6 +6,7 @@
//! - `CubicBezier` + `PathPlanner` — Bezier path math (ported 1:1 from C#)
//! - `OverlayCommand` — messages sent from MCP tools to the overlay thread
+pub mod badge_glyphs;
pub mod bezier;
pub mod capture_utils;
pub mod motion;
@@ -17,11 +18,20 @@ pub mod theme_artifact;
pub mod util;
pub mod z_order;
+pub use badge_glyphs::{BadgeChip, BadgeGlyph};
pub use bezier::CubicBezier;
pub use motion::{MotionConfig, Spring};
pub use path_planner::{PathPlanner, PathState, PlannedPath};
-pub use render_state::{paint_cursor, render_frame, FocusRect, RenderStateCore};
-pub use session_badge::{paint_session_badge, sanitize_session_label};
+pub use render_state::{
+ paint_cursor, render_frame, FocusRect, RenderStateCore, SESSION_BADGE_FADE_SECS,
+ SESSION_BADGE_HOLD_SECS,
+};
+pub use session_badge::{
+ paint_session_badge, sanitize_session_label, session_badge_extents, session_badge_layout,
+ BadgeExtents, BadgeLabelLayout, SessionBadgeInput, SessionBadgeLayout, BADGE_CHIP_GAP,
+ BADGE_CHIP_GROUP_GAP, BADGE_CHIP_SIZE, BADGE_CURSOR_GAP, BADGE_HEIGHT, BADGE_MAX_WIDTH,
+ MAX_SESSION_LABEL_CHARS,
+};
pub use theme::{
session_fill_hex, session_fill_rgba, CursorAction, CursorVisualState, DeliveryModifier,
PlaybackKind, ReducedMotion, TargetModifier, DEFAULT_CURSOR_FILL, DEFAULT_THEME_ID,
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.rs
index dc6dd4f3df..a5505ebc50 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
@@ -35,8 +35,8 @@
//! supplies one via the optional argument).
use crate::{
- CompiledTheme, CursorAction, CursorConfig, CursorVisualState, MotionConfig, OverlayCommand,
- PathPlanner, PathState, PlannedPath, Spring,
+ CompiledTheme, CursorAction, CursorConfig, CursorVisualState, DeliveryModifier, MotionConfig,
+ OverlayCommand, PathPlanner, PathState, PlannedPath, Spring, TargetModifier,
};
use std::sync::Arc;
@@ -90,6 +90,12 @@ pub struct RenderStateCore {
/// cursor. Hover temporarily reveals an already-faded session badge
/// without changing its one-shot reveal timer.
pub session_badge_hovered: bool,
+ /// Last action-scoped delivery and target context shown in the badge.
+ /// This is latched briefly after the semantic action ends so the chips
+ /// can fade without keeping modifier artwork inside the Lottie theme.
+ pub badge_modifiers: Option<(Option<DeliveryModifier>, Option<TargetModifier>)>,
+ /// Elapsed chip fade time after the active semantic action clears.
+ pub badge_modifier_fade_secs: Option<f64>,
}
impl RenderStateCore {
@@ -135,6 +141,8 @@ impl RenderStateCore {
session_label: None,
session_badge_secs: SESSION_BADGE_HOLD_SECS + SESSION_BADGE_FADE_SECS,
session_badge_hovered: false,
+ badge_modifiers: None,
+ badge_modifier_fade_secs: None,
}
}
@@ -164,10 +172,29 @@ impl RenderStateCore {
(1.0 - smooth) as f32
}
+ pub fn session_badge_chip_alpha(&self) -> f32 {
+ if self.badge_modifiers.is_none() {
+ return 0.0;
+ }
+ let Some(elapsed) = self.badge_modifier_fade_secs else {
+ return 1.0;
+ };
+ let fade = (elapsed / SESSION_BADGE_FADE_SECS).clamp(0.0, 1.0);
+ let smooth = fade * fade * (3.0 - 2.0 * fade);
+ (1.0 - smooth) as f32
+ }
+
+ pub fn session_badge_is_visible(&self) -> bool {
+ self.cursor_is_revealed()
+ && (self.session_badge_alpha() > 0.001 || self.session_badge_chip_alpha() > 0.001)
+ }
+
pub fn session_badge_needs_frame_tick(&self) -> bool {
- self.session_label.is_some()
- && self.session_badge_secs < SESSION_BADGE_HOLD_SECS + SESSION_BADGE_FADE_SECS
- && self.cursor_is_revealed()
+ self.cursor_is_revealed()
+ && ((self.session_label.is_some()
+ && self.session_badge_secs < SESSION_BADGE_HOLD_SECS + SESSION_BADGE_FADE_SECS)
+ || self.badge_modifier_fade_secs.is_some()
+ || self.visual.resolved_action != CursorAction::Idle)
}
/// Whether the platform overlay should keep a low-frequency hardware
@@ -189,7 +216,26 @@ impl RenderStateCore {
&& pointer.is_some_and(|(x, y)| {
let dx = x - self.pos.0;
let dy = y - self.pos.1;
- dx * dx + dy * dy <= HOVER_RADIUS * HOVER_RADIUS
+ if dx * dx + dy * dy <= HOVER_RADIUS * HOVER_RADIUS {
+ return true;
+ }
+ crate::session_badge_layout(crate::SessionBadgeInput {
+ label: self.session_label.as_deref(),
+ delivery: self.badge_modifiers.and_then(|modifiers| modifiers.0),
+ target: self.badge_modifiers.and_then(|modifiers| modifiers.1),
+ cursor: (self.pos.0 as f32, self.pos.1 as f32),
+ backing_scale: 1.0,
+ label_alpha: self.session_badge_alpha(),
+ chip_alpha: self.session_badge_chip_alpha(),
+ clip: None,
+ })
+ .is_some_and(|layout| {
+ let rect = layout.rect;
+ x >= rect.x() as f64
+ && x <= (rect.x() + rect.width()) as f64
+ && y >= rect.y() as f64
+ && y <= (rect.y() + rect.height()) as f64
+ })
});
let changed = hovered != self.session_badge_hovered;
self.session_badge_hovered = hovered;
@@ -435,7 +481,27 @@ impl RenderStateCore {
/// moving, then fade `idle_alpha` from 1→0 over 180ms once
/// `motion.idle_hide_ms` has elapsed. Identical across all platforms.
fn tick_idle(&mut self, dt: f64) {
+ let modifiers_before_tick = (self.visual.delivery, self.visual.target);
self.visual.tick(dt);
+ let modifiers_after_tick = (self.visual.delivery, self.visual.target);
+ if modifiers_after_tick.0.is_some() || modifiers_after_tick.1.is_some() {
+ self.badge_modifiers = Some(modifiers_after_tick);
+ self.badge_modifier_fade_secs = None;
+ } else if (modifiers_before_tick.0.is_some() || modifiers_before_tick.1.is_some())
+ && self.badge_modifiers.is_some()
+ && self.badge_modifier_fade_secs.is_none()
+ {
+ self.badge_modifier_fade_secs = Some(0.0);
+ }
+ if let Some(elapsed) = self.badge_modifier_fade_secs {
+ let next = elapsed + dt.max(0.0);
+ if next >= SESSION_BADGE_FADE_SECS {
+ self.badge_modifiers = None;
+ self.badge_modifier_fade_secs = None;
+ } else {
+ self.badge_modifier_fade_secs = Some(next);
+ }
+ }
if self.session_label.is_some() {
self.session_badge_secs = (self.session_badge_secs + dt)
.min(SESSION_BADGE_HOLD_SECS + SESSION_BADGE_FADE_SECS);
@@ -517,7 +583,9 @@ impl RenderStateCore {
self.visual.resolved_action,
CursorAction::Idle | CursorAction::Navigate
) {
- self.visual.begin(CursorAction::Navigate, None, None);
+ let delivery = self.visual.delivery;
+ let target = self.visual.target;
+ self.visual.begin(CursorAction::Navigate, delivery, target);
}
self.idle_secs = 0.0;
self.idle_alpha = 1.0;
@@ -544,7 +612,9 @@ impl RenderStateCore {
self.visual.resolved_action,
CursorAction::Idle | CursorAction::Navigate
) {
- self.visual.begin(CursorAction::Navigate, None, None);
+ let delivery = self.visual.delivery;
+ let target = self.visual.target;
+ self.visual.begin(CursorAction::Navigate, delivery, target);
}
self.idle_secs = 0.0;
self.idle_alpha = 1.0;
@@ -575,7 +645,9 @@ impl RenderStateCore {
self.visual.resolved_action,
CursorAction::Idle | CursorAction::Navigate | CursorAction::Click
) {
- self.visual.begin(CursorAction::Click, None, None);
+ let delivery = self.visual.delivery;
+ let target = self.visual.target;
+ self.visual.begin(CursorAction::Click, delivery, target);
}
self.idle_secs = 0.0;
self.idle_alpha = 1.0;
@@ -587,7 +659,9 @@ impl RenderStateCore {
OverlayCommand::SetPressed(v) => {
self.pressed = v;
if v {
- self.visual.begin(CursorAction::Drag, None, None);
+ let delivery = self.visual.delivery;
+ let target = self.visual.target;
+ self.visual.begin(CursorAction::Drag, delivery, target);
} else {
self.visual.end(CursorAction::Drag);
}
@@ -617,6 +691,12 @@ impl RenderStateCore {
target,
} => {
self.visual.begin(action, delivery, target);
+ self.badge_modifiers = if delivery.is_some() || target.is_some() {
+ Some((delivery, target))
+ } else {
+ None
+ };
+ self.badge_modifier_fade_secs = None;
true
}
OverlayCommand::EndAction(action) => {
@@ -825,16 +905,22 @@ pub fn paint_cursor(
);
}
- if let Some(label) = core.session_label.as_deref() {
- let badge_alpha = core.session_badge_alpha();
+ let (delivery, target) = core.badge_modifiers.unwrap_or((None, None));
+ if let Some(layout) = crate::session_badge_layout(crate::SessionBadgeInput {
+ label: core.session_label.as_deref(),
+ delivery,
+ target,
+ cursor: (px as f32, py as f32),
+ backing_scale: backing_scale.max(1.0),
+ label_alpha: core.session_badge_alpha(),
+ chip_alpha: core.session_badge_chip_alpha(),
+ clip: Some((pm.width() as f32, pm.height() as f32)),
+ }) {
crate::paint_session_badge(
pm,
- label,
- px as f32,
- py as f32,
- backing_scale.max(1.0),
- alpha_scale * badge_alpha,
+ &layout,
crate::session_fill_rgba(&core.cfg.cursor_id),
+ alpha_scale,
);
}
}
@@ -902,7 +988,7 @@ mod glide_duration_tests {
#[cfg(test)]
mod session_badge_and_action_tests {
use super::*;
- use crate::{CursorConfig, TargetModifier};
+ use crate::{CursorConfig, DeliveryModifier, TargetModifier};
#[test]
fn session_badge_holds_then_fades_once() {
@@ -1042,6 +1128,101 @@ mod session_badge_and_action_tests {
assert_eq!(core.visual.resolved_action, CursorAction::Text);
assert_eq!(core.visual.target, Some(TargetModifier::Ax));
}
+
+ #[test]
+ fn modifiers_live_in_the_badge_then_fade_after_action_completion() {
+ let mut core = RenderStateCore::new(CursorConfig::default());
+ core.pos = (200.0, 200.0);
+ core.apply_command_base(
+ OverlayCommand::BeginAction {
+ action: CursorAction::Click,
+ delivery: Some(DeliveryModifier::Foreground),
+ target: Some(TargetModifier::Pixel),
+ },
+ false,
+ false,
+ );
+ assert_eq!(
+ core.badge_modifiers,
+ Some((
+ Some(DeliveryModifier::Foreground),
+ Some(TargetModifier::Pixel)
+ ))
+ );
+ assert_eq!(core.session_badge_chip_alpha(), 1.0);
+ assert!(core.session_badge_is_visible());
+
+ let frame = 1.0 / 60.0;
+ for _ in 0..=((CursorAction::Click.duration_secs() / frame).ceil() as usize) {
+ core.tick_motion(frame);
+ }
+ assert!(core.session_badge_chip_alpha() > 0.0);
+ assert!(core.session_badge_chip_alpha() < 1.0);
+ assert!(core.session_badge_needs_frame_tick());
+
+ core.tick_motion(SESSION_BADGE_FADE_SECS);
+ assert_eq!(core.badge_modifiers, None);
+ assert_eq!(core.session_badge_chip_alpha(), 0.0);
+ }
+
+ #[test]
+ fn modifier_preemption_replaces_the_badge_context_without_cross_fading() {
+ let mut core = RenderStateCore::new(CursorConfig::default());
+ core.apply_command_base(
+ OverlayCommand::BeginAction {
+ action: CursorAction::Observe,
+ delivery: Some(DeliveryModifier::Background),
+ target: Some(TargetModifier::Ax),
+ },
+ false,
+ false,
+ );
+ core.apply_command_base(
+ OverlayCommand::BeginAction {
+ action: CursorAction::Text,
+ delivery: Some(DeliveryModifier::Foreground),
+ target: Some(TargetModifier::Browser),
+ },
+ false,
+ false,
+ );
+ assert_eq!(
+ core.badge_modifiers,
+ Some((
+ Some(DeliveryModifier::Foreground),
+ Some(TargetModifier::Browser)
+ ))
+ );
+ assert_eq!(core.badge_modifier_fade_secs, None);
+ assert_eq!(core.session_badge_chip_alpha(), 1.0);
+ }
+
+ #[test]
+ fn click_pulse_preserves_declared_context_until_the_action_fades() {
+ let mut core = RenderStateCore::new(CursorConfig::default());
+ core.apply_command_base(
+ OverlayCommand::BeginAction {
+ action: CursorAction::Click,
+ delivery: Some(DeliveryModifier::Background),
+ target: Some(TargetModifier::Ax),
+ },
+ false,
+ false,
+ );
+ core.apply_command_base(
+ OverlayCommand::ClickPulse { x: 40.0, y: 60.0 },
+ false,
+ false,
+ );
+ assert_eq!(
+ (core.visual.delivery, core.visual.target),
+ (Some(DeliveryModifier::Background), Some(TargetModifier::Ax))
+ );
+ assert_eq!(
+ core.badge_modifiers,
+ Some((Some(DeliveryModifier::Background), Some(TargetModifier::Ax)))
+ );
+ }
}
#[cfg(test)]
diff --git a/libs/cua-driver/rust/crates/cursor-overlay/src/session_badge.rs b/libs/cua-driver/rust/crates/cursor-overlay/src/session_badge.rs
index 2fd7575f22..65f301c86e 100644
--- a/libs/cua-driver/rust/crates/cursor-overlay/src/session_badge.rs
+++ b/libs/cua-driver/rust/crates/cursor-overlay/src/session_badge.rs
@@ -7,6 +7,10 @@
//! private runtime key, so rendering a friendly name never weakens session
//! isolation.
+use crate::{
+ badge_glyphs::{paint_badge_chip, BadgeChip, BadgeGlyph},
+ DeliveryModifier, TargetModifier,
+};
use fontdue::layout::{CoordinateSystem, Layout, LayoutSettings, TextStyle};
use std::sync::OnceLock;
use tiny_skia::{
@@ -18,6 +22,9 @@ pub const MAX_SESSION_LABEL_CHARS: usize = 28;
pub const BADGE_MAX_WIDTH: f32 = 188.0;
pub const BADGE_HEIGHT: f32 = 28.0;
pub const BADGE_CURSOR_GAP: f32 = 25.0;
+pub const BADGE_CHIP_SIZE: f32 = 18.0;
+pub const BADGE_CHIP_GAP: f32 = 4.0;
+pub const BADGE_CHIP_GROUP_GAP: f32 = 7.0;
const FONT_BYTES: &[u8] = include_bytes!("../assets/Inter.ttf");
const FONT_SIZE: f32 = 11.5;
@@ -26,6 +33,54 @@ const ORB_SIZE: f32 = 10.0;
const ORB_GAP: f32 = 7.0;
const TEXT_OPTICAL_Y_OFFSET: f32 = 1.0;
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct BadgeExtents {
+ pub horizontal: f32,
+ pub above: f32,
+ pub below: f32,
+}
+
+#[derive(Debug, Clone, PartialEq)]
+pub struct BadgeLabelLayout {
+ pub text: String,
+ pub origin: (f32, f32),
+}
+
+#[derive(Debug, Clone, PartialEq)]
+pub struct SessionBadgeLayout {
+ pub rect: Rect,
+ pub corner_radius: f32,
+ pub orb_center: (f32, f32),
+ pub label: Option<BadgeLabelLayout>,
+ pub delivery_chip: Option<BadgeChip>,
+ pub target_chip: Option<BadgeChip>,
+ pub pill_alpha: f32,
+ pub label_alpha: f32,
+ pub chip_alpha: f32,
+ pub scale: f32,
+}
+
+#[derive(Debug, Clone, Copy)]
+pub struct SessionBadgeInput<'a> {
+ pub label: Option<&'a str>,
+ pub delivery: Option<DeliveryModifier>,
+ pub target: Option<TargetModifier>,
+ pub cursor: (f32, f32),
+ pub backing_scale: f32,
+ pub label_alpha: f32,
+ pub chip_alpha: f32,
+ pub clip: Option<(f32, f32)>,
+}
+
+pub const fn session_badge_extents() -> BadgeExtents {
+ const GLOW_ALLOWANCE: f32 = 8.0;
+ BadgeExtents {
+ horizontal: BADGE_MAX_WIDTH * 0.5 + GLOW_ALLOWANCE,
+ above: GLOW_ALLOWANCE,
+ below: BADGE_CURSOR_GAP + BADGE_HEIGHT + GLOW_ALLOWANCE,
+ }
+}
+
fn font() -> Option<&'static fontdue::Font> {
static FONT: OnceLock<Option<fontdue::Font>> = OnceLock::new();
FONT.get_or_init(|| {
@@ -41,6 +96,79 @@ fn font() -> Option<&'static fontdue::Font> {
.as_ref()
}
+#[derive(Debug, Clone, Copy)]
+struct TextBounds {
+ min_x: f32,
+ min_y: f32,
+ width: f32,
+ height: f32,
+}
+
+fn text_layout(font: &fontdue::Font, text: &str, font_size: f32) -> Layout {
+ let mut layout = Layout::new(CoordinateSystem::PositiveYDown);
+ layout.reset(&LayoutSettings::default());
+ layout.append(&[font], &TextStyle::new(text, font_size, 0));
+ layout
+}
+
+fn text_bounds(layout: &Layout) -> Option<TextBounds> {
+ let glyphs = layout.glyphs();
+ if glyphs.is_empty() {
+ return None;
+ }
+ let min_x = glyphs
+ .iter()
+ .map(|glyph| glyph.x)
+ .fold(f32::INFINITY, f32::min);
+ let max_x = glyphs
+ .iter()
+ .map(|glyph| glyph.x + glyph.width as f32)
+ .fold(f32::NEG_INFINITY, f32::max);
+ let min_y = glyphs
+ .iter()
+ .map(|glyph| glyph.y)
+ .fold(f32::INFINITY, f32::min);
+ let max_y = glyphs
+ .iter()
+ .map(|glyph| glyph.y + glyph.height as f32)
+ .fold(f32::NEG_INFINITY, f32::max);
+ Some(TextBounds {
+ min_x,
+ min_y,
+ width: max_x - min_x,
+ height: max_y - min_y,
+ })
+}
+
+fn ellipsize_to_width(
+ font: &fontdue::Font,
+ label: &str,
+ font_size: f32,
+ max_width: f32,
+) -> Option<(String, TextBounds)> {
+ let layout = text_layout(font, label, font_size);
+ let bounds = text_bounds(&layout)?;
+ if bounds.width <= max_width {
+ return Some((label.to_owned(), bounds));
+ }
+
+ let mut characters = label.chars().collect::<Vec<_>>();
+ if characters.last() == Some(&'…') {
+ characters.pop();
+ }
+ while !characters.is_empty() {
+ characters.pop();
+ let candidate = format!("{}…", characters.iter().collect::<String>());
+ let layout = text_layout(font, &candidate, font_size);
+ let bounds = text_bounds(&layout)?;
+ if bounds.width <= max_width {
+ return Some((candidate, bounds));
+ }
+ }
+ let layout = text_layout(font, "…", font_size);
+ text_bounds(&layout).map(|bounds| ("…".to_owned(), bounds))
+}
+
/// Convert an untrusted public session label into compact display text.
///
/// Controls are removed, all whitespace runs collapse to one ASCII space,
@@ -188,82 +316,155 @@ fn paint_diffuse_glow(
}
}
-/// Paint the label below the cursor without rotating it with cursor heading.
-pub fn paint_session_badge(
- pixmap: &mut Pixmap,
- label: &str,
- cursor_x: f32,
- cursor_y: f32,
- backing_scale: f32,
- alpha_scale: f32,
- session_fill: [u8; 4],
-) {
+pub fn session_badge_layout(input: SessionBadgeInput<'_>) -> Option<SessionBadgeLayout> {
let Some(font) = font() else {
- return;
+ return None;
};
- let scale = backing_scale.max(1.0);
- let font_size = FONT_SIZE * scale;
- let max_text_width = (BADGE_MAX_WIDTH - HORIZONTAL_PADDING * 2.0 - ORB_SIZE - ORB_GAP) * scale;
-
- let mut layout = Layout::new(CoordinateSystem::PositiveYDown);
- layout.reset(&LayoutSettings {
- max_width: Some(max_text_width),
- max_height: Some(BADGE_HEIGHT * scale),
- ..Default::default()
- });
- layout.append(&[font], &TextStyle::new(label, font_size, 0));
- let glyphs = layout.glyphs();
- if glyphs.is_empty() {
- return;
+ let scale = input.backing_scale.max(1.0);
+ let label_alpha = input.label_alpha.clamp(0.0, 1.0);
+ let chip_alpha = input.chip_alpha.clamp(0.0, 1.0);
+ let show_label = input.label.is_some() && label_alpha > 0.001;
+ let delivery = (chip_alpha > 0.001).then_some(input.delivery).flatten();
+ let target = (chip_alpha > 0.001).then_some(input.target).flatten();
+ let chip_count = usize::from(delivery.is_some()) + usize::from(target.is_some());
+ if !show_label && chip_count == 0 {
+ return None;
}
- let glyph_min_x = glyphs
- .iter()
- .map(|glyph| glyph.x)
- .fold(f32::INFINITY, f32::min);
- let glyph_max_x = glyphs
- .iter()
- .map(|glyph| glyph.x + glyph.width as f32)
- .fold(f32::NEG_INFINITY, f32::max);
- let glyph_min_y = glyphs
- .iter()
- .map(|glyph| glyph.y)
- .fold(f32::INFINITY, f32::min);
- let glyph_max_y = glyphs
- .iter()
- .map(|glyph| glyph.y + glyph.height as f32)
- .fold(f32::NEG_INFINITY, f32::max);
- let text_width = (glyph_max_x - glyph_min_x).min(max_text_width);
- let text_height = glyph_max_y - glyph_min_y;
- let badge_width =
- (HORIZONTAL_PADDING * 2.0 * scale + ORB_SIZE * scale + ORB_GAP * scale + text_width)
- .min(BADGE_MAX_WIDTH * scale)
- .max(72.0 * scale);
+
+ let font_size = FONT_SIZE * scale;
+ let chip_width = match chip_count {
+ 0 => 0.0,
+ 1 => BADGE_CHIP_SIZE,
+ _ => BADGE_CHIP_SIZE * 2.0 + BADGE_CHIP_GAP,
+ } * scale;
+ let fixed_width = (HORIZONTAL_PADDING * 2.0 + ORB_SIZE + ORB_GAP) * scale
+ + chip_width
+ + if show_label && chip_count > 0 {
+ BADGE_CHIP_GROUP_GAP * scale
+ } else {
+ 0.0
+ };
+ let max_text_width = (BADGE_MAX_WIDTH * scale - fixed_width).max(0.0);
+ let label_data = if show_label {
+ input
+ .label
+ .and_then(|label| ellipsize_to_width(font, label, font_size, max_text_width))
+ } else {
+ None
+ };
+ let text_width = label_data.as_ref().map_or(0.0, |(_, bounds)| bounds.width);
+ let minimum_width = if show_label {
+ 72.0 * scale
+ } else {
+ fixed_width
+ };
+ let badge_width = (fixed_width + text_width)
+ .min(BADGE_MAX_WIDTH * scale)
+ .max(minimum_width);
let badge_height = BADGE_HEIGHT * scale;
- let x = (cursor_x - badge_width * 0.5).clamp(
- 2.0 * scale,
- pixmap.width() as f32 - badge_width - 2.0 * scale,
- );
- let y = (cursor_y + BADGE_CURSOR_GAP * scale).clamp(
- 2.0 * scale,
- pixmap.height() as f32 - badge_height - 2.0 * scale,
- );
- let Some(rect) = Rect::from_xywh(x, y, badge_width, badge_height) else {
- return;
+ let unclamped_x = input.cursor.0 - badge_width * 0.5;
+ let unclamped_y = input.cursor.1 + BADGE_CURSOR_GAP * scale;
+ let (x, y) = if let Some((clip_width, clip_height)) = input.clip {
+ (
+ unclamped_x.clamp(
+ 2.0 * scale,
+ (clip_width - badge_width - 2.0 * scale).max(2.0 * scale),
+ ),
+ unclamped_y.clamp(
+ 2.0 * scale,
+ (clip_height - badge_height - 2.0 * scale).max(2.0 * scale),
+ ),
+ )
+ } else {
+ (unclamped_x, unclamped_y)
};
+ let rect = Rect::from_xywh(x, y, badge_width, badge_height)?;
let corner_radius = badge_height * 0.5;
- let Some(path) = rounded_rect(rect, corner_radius) else {
+
+ let orb_center = (
+ x + HORIZONTAL_PADDING * scale + ORB_SIZE * scale * 0.5,
+ y + badge_height * 0.5,
+ );
+ let mut cursor_x = x + (HORIZONTAL_PADDING + ORB_SIZE + ORB_GAP) * scale;
+ let label = label_data.map(|(text, bounds)| {
+ let origin = (
+ cursor_x - bounds.min_x,
+ y + (badge_height - bounds.height) * 0.5 - bounds.min_y + TEXT_OPTICAL_Y_OFFSET * scale,
+ );
+ cursor_x += bounds.width + BADGE_CHIP_GROUP_GAP * scale;
+ BadgeLabelLayout { text, origin }
+ });
+ let chip_y = y + (badge_height - BADGE_CHIP_SIZE * scale) * 0.5;
+ let delivery_chip = delivery.and_then(|delivery| {
+ let rect = Rect::from_xywh(
+ cursor_x,
+ chip_y,
+ BADGE_CHIP_SIZE * scale,
+ BADGE_CHIP_SIZE * scale,
+ )?;
+ cursor_x += (BADGE_CHIP_SIZE + BADGE_CHIP_GAP) * scale;
+ Some(BadgeChip {
+ glyph: BadgeGlyph::from(delivery),
+ rect,
+ filled: true,
+ })
+ });
+ let target_chip = target.and_then(|target| {
+ let rect = Rect::from_xywh(
+ cursor_x,
+ chip_y,
+ BADGE_CHIP_SIZE * scale,
+ BADGE_CHIP_SIZE * scale,
+ )?;
+ Some(BadgeChip {
+ glyph: BadgeGlyph::from(target),
+ rect,
+ filled: false,
+ })
+ });
+
+ Some(SessionBadgeLayout {
+ rect,
+ corner_radius,
+ orb_center,
+ label,
+ delivery_chip,
+ target_chip,
+ pill_alpha: label_alpha.max(chip_alpha),
+ label_alpha,
+ chip_alpha,
+ scale,
+ })
+}
+
+/// Paint the badge below the cursor without rotating it with cursor heading.
+pub fn paint_session_badge(
+ pixmap: &mut Pixmap,
+ layout: &SessionBadgeLayout,
+ session_fill: [u8; 4],
+ alpha_scale: f32,
+) {
+ let Some(font) = font() else {
return;
};
-
- let opacity = alpha_scale.clamp(0.0, 1.0);
+ let rect = layout.rect;
+ let x = rect.x();
+ let y = rect.y();
+ let badge_width = rect.width();
+ let badge_height = rect.height();
+ let scale = layout.scale;
+ let opacity = (alpha_scale * layout.pill_alpha).clamp(0.0, 1.0);
if opacity <= 0.0 {
return;
}
+ let Some(path) = rounded_rect(rect, layout.corner_radius) else {
+ return;
+ };
paint_diffuse_glow(
pixmap,
rect,
- corner_radius,
+ layout.corner_radius,
scale,
[0, 0, 0],
8.0 * opacity,
@@ -272,7 +473,7 @@ pub fn paint_session_badge(
paint_diffuse_glow(
pixmap,
rect,
- corner_radius,
+ layout.corner_radius,
scale,
[session_fill[0], session_fill[1], session_fill[2]],
10.0 * opacity,
@@ -334,10 +535,11 @@ pub fn paint_session_badge(
None,
);
- let orb_center_x = x + HORIZONTAL_PADDING * scale + ORB_SIZE * scale * 0.5;
- let orb_center_y = y + badge_height * 0.5;
- if let Some(orb) = PathBuilder::from_circle(orb_center_x, orb_center_y, ORB_SIZE * scale * 0.5)
- {
+ if let Some(orb) = PathBuilder::from_circle(
+ layout.orb_center.0,
+ layout.orb_center.1,
+ ORB_SIZE * scale * 0.5,
+ ) {
let orb_paint = Paint {
shader: tiny_skia::Shader::SolidColor(Color::from_rgba8(
session_fill[0],
@@ -377,34 +579,42 @@ pub fn paint_session_badge(
);
}
- let text_origin_x = x + HORIZONTAL_PADDING * scale + (ORB_SIZE + ORB_GAP) * scale - glyph_min_x;
- let text_origin_y =
- y + (badge_height - text_height) * 0.5 - glyph_min_y + TEXT_OPTICAL_Y_OFFSET * scale;
- for glyph in glyphs {
- let (metrics, bitmap) = font.rasterize_config(glyph.key);
- if metrics.width == 0 || metrics.height == 0 {
- continue;
- }
- let Some(mut glyph_pixmap) = Pixmap::new(metrics.width as u32, metrics.height as u32)
- else {
- continue;
- };
- for (pixel, coverage) in glyph_pixmap
- .data_mut()
- .chunks_exact_mut(4)
- .zip(bitmap.iter().copied())
- {
- let alpha = ((coverage as f32) * opacity) as u8;
- pixel.copy_from_slice(&[alpha, alpha, alpha, alpha]);
+ if let Some(label) = &layout.label {
+ let label_opacity = (alpha_scale * layout.label_alpha).clamp(0.0, 1.0);
+ let text = text_layout(font, &label.text, FONT_SIZE * scale);
+ for glyph in text.glyphs() {
+ let (metrics, bitmap) = font.rasterize_config(glyph.key);
+ if metrics.width == 0 || metrics.height == 0 {
+ continue;
+ }
+ let Some(mut glyph_pixmap) = Pixmap::new(metrics.width as u32, metrics.height as u32)
+ else {
+ continue;
+ };
+ for (pixel, coverage) in glyph_pixmap
+ .data_mut()
+ .chunks_exact_mut(4)
+ .zip(bitmap.iter().copied())
+ {
+ let alpha = ((coverage as f32) * label_opacity) as u8;
+ pixel.copy_from_slice(&[alpha, alpha, alpha, alpha]);
+ }
+ pixmap.draw_pixmap(
+ (label.origin.0 + glyph.x).round() as i32,
+ (label.origin.1 + glyph.y).round() as i32,
+ glyph_pixmap.as_ref(),
+ &PixmapPaint::default(),
+ Transform::identity(),
+ None,
+ );
}
- pixmap.draw_pixmap(
- (text_origin_x + glyph.x).round() as i32,
- (text_origin_y + glyph.y).round() as i32,
- glyph_pixmap.as_ref(),
- &PixmapPaint::default(),
- Transform::identity(),
- None,
- );
+ }
+ let chip_opacity = (alpha_scale * layout.chip_alpha).clamp(0.0, 1.0);
+ if let Some(chip) = layout.delivery_chip {
+ paint_badge_chip(pixmap, chip, session_fill, chip_opacity);
+ }
+ if let Some(chip) = layout.target_chip {
+ paint_badge_chip(pixmap, chip, session_fill, chip_opacity);
}
}
@@ -428,15 +638,18 @@ mod tests {
fn badge_paints_at_one_and_two_x_backing_scales() {
for scale in [1.0, 2.0] {
let mut pixmap = Pixmap::new((240.0 * scale) as u32, (160.0 * scale) as u32).unwrap();
- paint_session_badge(
- &mut pixmap,
- "Research run",
- 120.0 * scale,
- 60.0 * scale,
- scale,
- 1.0,
- [94, 192, 232, 255],
- );
+ let layout = session_badge_layout(SessionBadgeInput {
+ label: Some("Research run"),
+ delivery: Some(DeliveryModifier::Foreground),
+ target: Some(TargetModifier::Browser),
+ cursor: (120.0 * scale, 60.0 * scale),
+ backing_scale: scale,
+ label_alpha: 1.0,
+ chip_alpha: 1.0,
+ clip: Some((pixmap.width() as f32, pixmap.height() as f32)),
+ })
+ .unwrap();
+ paint_session_badge(&mut pixmap, &layout, [94, 192, 232, 255], 1.0);
assert!(pixmap.data().chunks_exact(4).any(|pixel| pixel[3] > 0));
}
}
@@ -446,34 +659,60 @@ mod tests {
let mut blue = Pixmap::new(240, 160).unwrap();
let mut purple = Pixmap::new(240, 160).unwrap();
let mut hidden = Pixmap::new(240, 160).unwrap();
- paint_session_badge(
- &mut blue,
- "Research run",
- 120.0,
- 60.0,
- 1.0,
- 1.0,
- [94, 192, 232, 255],
- );
- paint_session_badge(
- &mut purple,
- "Research run",
- 120.0,
- 60.0,
- 1.0,
- 1.0,
- [178, 132, 255, 255],
- );
- paint_session_badge(
- &mut hidden,
- "Research run",
- 120.0,
- 60.0,
- 1.0,
- 0.0,
- [94, 192, 232, 255],
- );
+ let layout = session_badge_layout(SessionBadgeInput {
+ label: Some("Research run"),
+ delivery: None,
+ target: None,
+ cursor: (120.0, 60.0),
+ backing_scale: 1.0,
+ label_alpha: 1.0,
+ chip_alpha: 0.0,
+ clip: Some((240.0, 160.0)),
+ })
+ .unwrap();
+ paint_session_badge(&mut blue, &layout, [94, 192, 232, 255], 1.0);
+ paint_session_badge(&mut purple, &layout, [178, 132, 255, 255], 1.0);
+ paint_session_badge(&mut hidden, &layout, [94, 192, 232, 255], 0.0);
assert_ne!(blue.data(), purple.data());
assert!(hidden.data().chunks_exact(4).all(|pixel| pixel[3] == 0));
}
+
+ #[test]
+ fn modifier_only_badge_is_compact_and_keeps_delivery_before_target() {
+ let layout = session_badge_layout(SessionBadgeInput {
+ label: None,
+ delivery: Some(DeliveryModifier::Background),
+ target: Some(TargetModifier::Pixel),
+ cursor: (120.0, 60.0),
+ backing_scale: 1.0,
+ label_alpha: 0.0,
+ chip_alpha: 1.0,
+ clip: None,
+ })
+ .unwrap();
+ assert!(layout.label.is_none());
+ assert!(layout.rect.width() < 80.0);
+ let delivery = layout.delivery_chip.unwrap();
+ let target = layout.target_chip.unwrap();
+ assert!(delivery.filled);
+ assert!(!target.filled);
+ assert!(delivery.rect.x() < target.rect.x());
+ }
+
+ #[test]
+ fn long_label_stays_inside_the_bounded_badge() {
+ let layout = session_badge_layout(SessionBadgeInput {
+ label: Some("A very long public session label"),
+ delivery: Some(DeliveryModifier::Foreground),
+ target: Some(TargetModifier::Desktop),
+ cursor: (120.0, 60.0),
+ backing_scale: 1.0,
+ label_alpha: 1.0,
+ chip_alpha: 1.0,
+ clip: None,
+ })
+ .unwrap();
+ assert!(layout.rect.width() <= BADGE_MAX_WIDTH);
+ assert!(layout.label.unwrap().text.ends_with('…'));
+ }
}
diff --git a/libs/cua-driver/rust/crates/cursor-overlay/src/theme.rs b/libs/cua-driver/rust/crates/cursor-overlay/src/theme.rs
index 92d5c197fb..d84cb08fab 100644
--- a/libs/cua-driver/rust/crates/cursor-overlay/src/theme.rs
+++ b/libs/cua-driver/rust/crates/cursor-overlay/src/theme.rs
@@ -13,8 +13,8 @@ pub use cua_driver_contract::{
};
pub const DEFAULT_THEME_ID: &str = "cua.default";
-pub const DEFAULT_THEME_VERSION: &str = "1.0.0";
-pub const THEME_PROFILE: &str = "cua-driver-full-v1";
+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;
@@ -194,7 +194,7 @@ pub(crate) fn shared_float_motion(visual: &CursorVisualState) -> (f32, f32, f32)
)
}
-/// Paint one frame of the embedded Full-v1 theme.
+/// Paint one frame of the embedded actions-v2 theme.
///
/// `anchor_x/y` is the existing overlay's cursor centre. The Lottie canvas is
/// centred there so the established click offset and path physics remain
@@ -360,7 +360,7 @@ mod tests {
}
#[test]
- fn foreground_and_pixel_modifiers_render_on_opposite_sides() {
+ fn action_theme_ignores_host_owned_modifiers() {
let mut base = tiny_skia::Pixmap::new(128, 128).unwrap();
let mut pixmap = tiny_skia::Pixmap::new(128, 128).unwrap();
let base_visual = CursorVisualState {
@@ -394,18 +394,7 @@ mod tests {
[12, 34, 56, 255],
);
- let changed_pixels = |x_range: std::ops::Range<u32>| {
- (0..128)
- .flat_map(|y| x_range.clone().map(move |x| (x, y)))
- .filter(|(x, y)| {
- let index = ((y * pixmap.width() + x) * 4) as usize;
- pixmap.data()[index..index + 4] != base.data()[index..index + 4]
- })
- .count()
- };
-
- assert!(changed_pixels(0..50) > 5);
- assert!(changed_pixels(78..128) > 5);
+ assert_eq!(pixmap.data(), base.data());
}
#[test]
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.rs
index a0e8afd5c3..e3b5ae415d 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
@@ -4,7 +4,7 @@
//! header. The privileged overlay never parses Lottie, ZIP, JSON, fonts,
//! expressions, URLs, or arbitrary source paths.
-use crate::{CursorAction, CursorVisualState, DeliveryModifier, TargetModifier};
+use crate::{CursorAction, CursorVisualState};
use anyhow::{anyhow, bail, Context, Result};
use serde::{Deserialize, Serialize};
use sha2::{Digest, Sha256};
@@ -17,9 +17,10 @@ use std::{
};
use tiny_skia::{Color, FillRule, LineCap, LineJoin, Paint, PathBuilder, Stroke, Transform};
-const MAGIC: &[u8; 8] = b"CUATHEM2";
+const MAGIC: &[u8; 8] = b"CUATHEM3";
+const LEGACY_MAGIC: &[u8; 8] = b"CUATHEM2";
const HEADER_LEN: usize = 8 + 2 + 4 + 32;
-const ARTIFACT_VERSION: u16 = 2;
+const ARTIFACT_VERSION: u16 = 3;
const MAX_COMPRESSED_BYTES: usize = 24 * 1024 * 1024;
const MAX_DECOMPRESSED_BYTES: usize = 24 * 1024 * 1024;
const MAX_TOTAL_FRAMES: usize = 1_000;
@@ -111,7 +112,6 @@ pub struct CompiledTheme {
pub source_hash: [u8; 32],
pub hotspot: [u16; 2],
pub actions: BTreeMap<String, CompiledAnimation>,
- pub modifiers: BTreeMap<String, CompiledAnimation>,
}
impl CompiledTheme {
@@ -126,10 +126,6 @@ impl CompiledTheme {
pub fn animation_for_action(&self, action: CursorAction) -> Option<&CompiledAnimation> {
self.actions.get(action.as_str())
}
-
- fn modifier(&self, name: &str) -> Option<&CompiledAnimation> {
- self.modifiers.get(name)
- }
}
fn valid_theme_id(value: &str) -> bool {
@@ -281,24 +277,12 @@ pub fn validate_compiled_theme(theme: &CompiledTheme, full: bool) -> Result<()>
bail!("full profile is missing action `{}`", action.as_str());
}
}
- for modifier in [
- "background",
- "foreground",
- "ax",
- "pixel",
- "browser",
- "desktop",
- ] {
- if !theme.modifiers.contains_key(modifier) {
- bail!("full profile is missing modifier `{modifier}`");
- }
- }
} else if !theme.actions.contains_key("idle") || !theme.actions.contains_key("click") {
bail!("development profile requires at least `idle` and `click`");
}
let mut total_frames = 0usize;
- for (name, animation) in theme.actions.iter().chain(theme.modifiers.iter()) {
+ for (name, animation) in &theme.actions {
total_frames += validate_animation(name, animation)?;
if total_frames > MAX_TOTAL_FRAMES {
bail!("theme exceeds the {MAX_TOTAL_FRAMES}-frame limit");
@@ -329,6 +313,11 @@ pub fn encode_theme(theme: &CompiledTheme) -> Result<Vec<u8>> {
}
pub fn decode_theme(bytes: &[u8]) -> Result<CompiledTheme> {
+ if bytes.len() >= LEGACY_MAGIC.len() && &bytes[..LEGACY_MAGIC.len()] == LEGACY_MAGIC {
+ bail!(
+ "cursor-theme artifact targets the retired v1 contract; rebuild the source as cua.cursor-theme/2"
+ );
+ }
if bytes.len() < HEADER_LEN || &bytes[..8] != MAGIC {
bail!("not a Cua cursor-theme artifact");
}
@@ -810,42 +799,6 @@ pub fn paint_compiled_theme_with_tint(
tint,
);
}
- if let Some(delivery) = visual.delivery {
- let name = match delivery {
- DeliveryModifier::Background => "background",
- DeliveryModifier::Foreground => "foreground",
- };
- if let Some(animation) = theme.modifier(name) {
- draw_layer(
- target,
- animation,
- visual.elapsed_secs,
- reduced,
- transform,
- alpha,
- tint,
- );
- }
- }
- if let Some(target_modifier) = visual.target {
- let name = match target_modifier {
- TargetModifier::Ax => "ax",
- TargetModifier::Pixel => "pixel",
- TargetModifier::Browser => "browser",
- TargetModifier::Desktop => "desktop",
- };
- if let Some(animation) = theme.modifier(name) {
- draw_layer(
- target,
- animation,
- visual.elapsed_secs,
- reduced,
- transform,
- alpha,
- tint,
- );
- }
- }
}
fn hex_digest(bytes: &[u8]) -> String {
@@ -893,14 +846,13 @@ mod tests {
version: "1.0.0".into(),
author: "Example Author".into(),
license: "MIT".into(),
- profile: "cua-driver-development-v1".into(),
+ profile: "cua-driver-development-v2".into(),
source_hash: [7; 32],
hotspot: [55, 30],
actions: BTreeMap::from([
("idle".into(), animation.clone()),
("click".into(), animation),
]),
- modifiers: BTreeMap::new(),
}
}
@@ -913,7 +865,16 @@ mod tests {
}
#[test]
- fn full_profile_requires_every_action_and_modifier() {
+ fn rejects_v1_artifacts_with_rebuild_guidance() {
+ let mut bytes = encode_theme(&minimal_theme()).unwrap();
+ bytes[..LEGACY_MAGIC.len()].copy_from_slice(LEGACY_MAGIC);
+ let message = decode_theme(&bytes).unwrap_err().to_string();
+ assert!(message.contains("retired v1 contract"));
+ assert!(message.contains("cua.cursor-theme/2"));
+ }
+
+ #[test]
+ fn full_profile_requires_every_action() {
let mut theme = minimal_theme();
theme.profile = crate::THEME_PROFILE.into();
assert!(validate_compiled_theme(&theme, true).is_err());
@@ -931,11 +892,9 @@ mod tests {
let theme = embedded_default_theme();
assert_eq!(theme.id, crate::DEFAULT_THEME_ID);
assert_eq!(theme.actions.len(), CursorAction::ALL.len());
- assert_eq!(theme.modifiers.len(), 6);
assert!(theme
.actions
.values()
- .chain(theme.modifiers.values())
.flat_map(|animation| &animation.frames)
.any(|frame| !frame.commands.is_empty()));
validate_compiled_theme(&theme, true).unwrap();
diff --git a/libs/cua-driver/rust/crates/cursor-theme-cli/src/main.rs b/libs/cua-driver/rust/crates/cursor-theme-cli/src/main.rs
index 3ddd2511c8..b9f385a527 100644
--- a/libs/cua-driver/rust/crates/cursor-theme-cli/src/main.rs
+++ b/libs/cua-driver/rust/crates/cursor-theme-cli/src/main.rs
@@ -5,7 +5,7 @@ use cursor_overlay::{
encode_theme, inspect_artifact, install_artifact, list_installed_themes, uninstall_theme,
validate_compiled_theme, CompiledAnimation, CompiledDrawCommand, CompiledFrame,
CompiledGeometry, CompiledStroke, CompiledTheme, CompiledTransform, CursorAction,
- CursorVisualState, DeliveryModifier, ReducedMotion, TargetModifier, THEME_PROFILE,
+ CursorVisualState, ReducedMotion, THEME_PROFILE,
};
use serde::Deserialize;
use serde_json::Value;
@@ -30,6 +30,7 @@ type SourceArchiveEntries = BTreeMap<String, Vec<u8>>;
type SourceArchive = (Vec<u8>, SourceArchiveEntries);
#[derive(Debug, Deserialize)]
+#[serde(deny_unknown_fields)]
struct ThemeManifest {
schema: String,
id: String,
@@ -41,7 +42,6 @@ struct ThemeManifest {
canvas: Canvas,
hotspot: Hotspot,
actions: BTreeMap<String, AnimationRef>,
- modifiers: BTreeMap<String, AnimationRef>,
#[serde(default)]
variants: BTreeMap<String, String>,
}
@@ -111,11 +111,10 @@ fn run() -> Result<()> {
let full = !args.iter().any(|value| value == "--development");
let theme = compile_source(&source, full)?;
println!(
- "valid: {} {} ({} actions, {} modifiers, profile {})",
+ "valid: {} {} ({} actions, profile {})",
theme.id,
theme.version,
theme.actions.len(),
- theme.modifiers.len(),
theme.profile
);
}
@@ -147,7 +146,6 @@ fn run() -> Result<()> {
println!("profile: {}", theme.profile);
println!("content hash: {}", theme.content_hash());
println!("actions: {}", theme.actions.len());
- println!("modifiers: {}", theme.modifiers.len());
}
}
"preview" => {
@@ -278,11 +276,22 @@ fn compile_source(path: &Path, full: bool) -> Result<CompiledTheme> {
let manifest_bytes = entries
.get("cua/theme.json")
.ok_or_else(|| anyhow!("archive is missing cua/theme.json"))?;
- let manifest: ThemeManifest = parse_json(manifest_bytes, "cua/theme.json")?;
- if manifest.schema != "cua.cursor-theme/1" {
+ let manifest_value: Value = parse_json(manifest_bytes, "cua/theme.json")?;
+ let source_schema = manifest_value
+ .get("schema")
+ .and_then(Value::as_str)
+ .unwrap_or_default();
+ if source_schema == "cua.cursor-theme/1" {
+ bail!(
+ "cursor-theme source targets the retired v1 contract; remove `modifiers` and rebuild as cua.cursor-theme/2"
+ );
+ }
+ let manifest: ThemeManifest =
+ serde_json::from_value(manifest_value).context("parse cua/theme.json")?;
+ if manifest.schema != "cua.cursor-theme/2" {
bail!("unsupported source schema `{}`", manifest.schema);
}
- if manifest.compatibility.semantics != 1 {
+ if manifest.compatibility.semantics != 2 {
bail!(
"unsupported cursor semantic version {}",
manifest.compatibility.semantics
@@ -292,14 +301,14 @@ fn compile_source(path: &Path, full: bool) -> Result<CompiledTheme> {
|| manifest.canvas.height != CANVAS
|| (manifest.canvas.fps - FPS).abs() > f32::EPSILON
{
- bail!("Cua cursor profile v1 requires a 128×128 canvas at 30 fps");
+ bail!("Cua cursor profile v2 requires a 128×128 canvas at 30 fps");
}
if full && manifest.compatibility.profile != THEME_PROFILE {
bail!("full validation requires profile `{THEME_PROFILE}`");
}
if !manifest.variants.is_empty() {
bail!(
- "cursor-theme variants are not supported by profile v1; publish each visual variant as a separate theme id"
+ "cursor-theme variants are not supported by profile v2; publish each visual variant as a separate theme id"
);
}
@@ -313,7 +322,6 @@ fn compile_source(path: &Path, full: bool) -> Result<CompiledTheme> {
let referenced: BTreeSet<&str> = manifest
.actions
.values()
- .chain(manifest.modifiers.values())
.map(|item| item.animation.as_str())
.collect();
let standard_ids: BTreeSet<&str> = standard
@@ -357,30 +365,6 @@ fn compile_source(path: &Path, full: bool) -> Result<CompiledTheme> {
)?,
);
}
- let allowed_modifiers = [
- "background",
- "foreground",
- "ax",
- "pixel",
- "browser",
- "desktop",
- ];
- let mut modifiers = BTreeMap::new();
- for (name, reference) in manifest.modifiers {
- if !allowed_modifiers.contains(&name.as_str()) {
- bail!("unknown modifier `{name}`");
- }
- modifiers.insert(
- name,
- with_still_frame(
- compiled
- .get(&reference.animation)
- .cloned()
- .ok_or_else(|| anyhow!("missing compiled modifier"))?,
- reference.still_frame,
- )?,
- );
- }
let mut hasher = Sha256::new();
hasher.update(&source);
let source_hash: [u8; 32] = hasher.finalize().into();
@@ -394,7 +378,6 @@ fn compile_source(path: &Path, full: bool) -> Result<CompiledTheme> {
source_hash,
hotspot: [manifest.hotspot.x, manifest.hotspot.y],
actions,
- modifiers,
};
validate_compiled_theme(&theme, full)?;
Ok(theme)
@@ -903,7 +886,7 @@ fn compile_animation(bytes: &[u8], id: &str) -> Result<CompiledAnimation> {
fn preview(theme: &CompiledTheme, output: &Path) -> Result<()> {
fs::create_dir_all(output).with_context(|| format!("create {}", output.display()))?;
- for name in theme.actions.keys().chain(theme.modifiers.keys()) {
+ for name in theme.actions.keys() {
let mut visual = CursorVisualState {
reduced_motion: ReducedMotion::On,
..CursorVisualState::default()
@@ -915,15 +898,7 @@ fn preview(theme: &CompiledTheme, output: &Path) -> Result<()> {
visual.requested_action = action;
visual.resolved_action = action;
} else {
- match name.as_str() {
- "background" => visual.delivery = Some(DeliveryModifier::Background),
- "foreground" => visual.delivery = Some(DeliveryModifier::Foreground),
- "ax" => visual.target = Some(TargetModifier::Ax),
- "pixel" => visual.target = Some(TargetModifier::Pixel),
- "browser" => visual.target = Some(TargetModifier::Browser),
- "desktop" => visual.target = Some(TargetModifier::Desktop),
- _ => bail!("unknown compiled semantic `{name}`"),
- }
+ bail!("unknown compiled action `{name}`");
}
let mut pixmap = tiny_skia::Pixmap::new(CANVAS, CANVAS)
.ok_or_else(|| anyhow!("create preview pixmap"))?;
@@ -1000,6 +975,14 @@ mod tests {
}
fn source_archive(standard_id: &str, variants: &str) -> tempfile::NamedTempFile {
+ source_archive_with_schema(standard_id, variants, "cua.cursor-theme/2")
+ }
+
+ fn source_archive_with_schema(
+ standard_id: &str,
+ variants: &str,
+ schema: &str,
+ ) -> tempfile::NamedTempFile {
let file = tempfile::Builder::new()
.suffix(".lottie")
.tempfile()
@@ -1007,22 +990,29 @@ mod tests {
let mut archive = ZipWriter::new(file.reopen().unwrap());
let options = SimpleFileOptions::default();
let standard = format!(r#"{{"version":"2","animations":[{{"id":"{standard_id}"}}]}}"#);
+ let legacy = schema == "cua.cursor-theme/1";
+ let profile = if legacy {
+ "cua-driver-full-v1"
+ } else {
+ "cua-driver-development-v2"
+ };
+ let semantics = if legacy { 1 } else { 2 };
+ let modifiers = if legacy { r#","modifiers":{}"# } else { "" };
let semantic = format!(
r#"{{
- "schema":"cua.cursor-theme/1",
+ "schema":"{schema}",
"id":"com.example.test",
"name":"Test",
"version":"1.0.0",
"author":"Example Author",
"license":"MIT",
- "compatibility":{{"profile":"cua-driver-development-v1","semantics":1}},
+ "compatibility":{{"profile":"{profile}","semantics":{semantics}}},
"canvas":{{"width":128,"height":128,"fps":30}},
"hotspot":{{"x":55,"y":30}},
"actions":{{
"idle":{{"animation":"base","still_frame":0}},
"click":{{"animation":"base","still_frame":0}}
- }},
- "modifiers":{{}},
+ }}{modifiers},
"variants":{variants}
}}"#
);
@@ -1144,7 +1134,7 @@ mod tests {
}
#[test]
- fn rejects_noop_variants_in_profile_v1() {
+ fn rejects_noop_variants_in_profile_v2() {
let source = source_archive("base", r#"{"dark":"dark"}"#);
assert!(compile_source(source.path(), false)
.unwrap_err()
@@ -1152,6 +1142,17 @@ mod tests {
.contains("variants are not supported"));
}
+ #[test]
+ fn rejects_v1_sources_with_rebuild_guidance() {
+ let source = source_archive_with_schema("base", "{}", "cua.cursor-theme/1");
+ let message = compile_source(source.path(), false)
+ .unwrap_err()
+ .to_string();
+ assert!(message.contains("retired v1 contract"));
+ assert!(message.contains("remove `modifiers`"));
+ assert!(message.contains("cua.cursor-theme/2"));
+ }
+
#[test]
fn rejects_parent_paths() {
let traversal = archive_with_entries(&[("../theme.json", b"{}")]);
diff --git a/libs/cua-driver/rust/crates/platform-linux/src/overlay.rs b/libs/cua-driver/rust/crates/platform-linux/src/overlay.rs
index d3fd32db84..54eecdac3e 100644
--- a/libs/cua-driver/rust/crates/platform-linux/src/overlay.rs
+++ b/libs/cua-driver/rust/crates/platform-linux/src/overlay.rs
@@ -24,6 +24,8 @@ use std::sync::{Mutex, OnceLock};
#[cfg(target_os = "linux")]
use std::time::{Duration, Instant};
+#[cfg(all(test, target_os = "linux"))]
+use cursor_overlay::CursorAction;
#[cfg(target_os = "linux")]
use cursor_overlay::ZOrderEnforcer;
use cursor_overlay::{
@@ -988,7 +990,8 @@ fn x11_compositor_present(conn: &impl x11rb::connection::Connection, screen_num:
#[cfg(target_os = "linux")]
const X11_CURSOR_TILE_MARGIN: f64 = 64.0;
#[cfg(target_os = "linux")]
-const X11_LABELED_CURSOR_HORIZONTAL_MARGIN: f64 = 96.0;
+const X11_BADGED_CURSOR_HORIZONTAL_MARGIN: f64 =
+ cursor_overlay::session_badge_extents().horizontal as f64 + 2.0;
#[cfg(target_os = "linux")]
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
@@ -1017,8 +1020,8 @@ fn cursor_tile_bounds(
let screen_width = i32::try_from(screen_width).ok()?;
let screen_height = i32::try_from(screen_height).ok()?;
- let horizontal_margin = if core.session_label.is_some() {
- X11_LABELED_CURSOR_HORIZONTAL_MARGIN
+ let horizontal_margin = if core.session_badge_is_visible() {
+ X11_BADGED_CURSOR_HORIZONTAL_MARGIN
} else {
X11_CURSOR_TILE_MARGIN
};
@@ -1647,16 +1650,36 @@ mod tests {
map.scr_h = 2160;
let cursor = map.cursors.get_mut("default").unwrap();
cursor.core.pos = (4000.0, 1000.0);
- cursor.core.session_label = Some("research-run".to_owned());
+ cursor.apply_command(OverlayCommand::SetSessionLabel("research-run".to_owned()));
let tiles = render_x11_tiles(&map);
assert_eq!(tiles.len(), 1);
- assert_eq!(tiles[0].bounds.width, 192);
+ assert_eq!(tiles[0].bounds.width, 208);
assert_eq!(tiles[0].bounds.height, 128);
assert!(tiles[0].pixmap.data().len() < (map.scr_w * map.scr_h * 4) as usize);
}
+ #[test]
+ fn modifier_only_badge_expands_the_local_cursor_tile() {
+ let mut map = default_render_map();
+ map.scr_w = 7680;
+ map.scr_h = 2160;
+ let cursor = map.cursors.get_mut("default").unwrap();
+ cursor.core.pos = (4000.0, 1000.0);
+ cursor.apply_command(OverlayCommand::BeginAction {
+ action: CursorAction::Click,
+ delivery: Some(cursor_overlay::DeliveryModifier::Foreground),
+ target: Some(cursor_overlay::TargetModifier::Pixel),
+ });
+
+ let tiles = render_x11_tiles(&map);
+
+ assert_eq!(tiles.len(), 1);
+ assert_eq!(tiles[0].bounds.width, 208);
+ assert_eq!(tiles[0].bounds.height, 128);
+ }
+
#[test]
fn cursor_tiles_clip_at_screen_edges_and_skip_hidden_cursors() {
let mut map = default_render_map();
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.rs
index 0f9de296dc..19e92e6aa5 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
@@ -35,7 +35,7 @@ const DBUS_DEST: &str = "org.freedesktop.DBus";
const DBUS_PATH: &str = "/org/freedesktop/DBus";
const DBUS_IFACE: &str = "org.freedesktop.DBus";
const BROWSER_HELPER_API_VERSION: u32 = 4;
-const SEMANTIC_CURSOR_API_VERSION: u32 = 7;
+const SEMANTIC_CURSOR_API_VERSION: u32 = 8;
#[derive(Debug, Clone)]
struct ShellWindow {
@@ -541,7 +541,7 @@ pub fn set_cursor_color(fill_color: &str) {
/// Update the compositor-owned cursor's semantic action state.
///
-/// Callers gate this method on helper v5 so an older helper cannot silently
+/// Callers gate this method on helper v8 so an older helper cannot silently
/// render the retired cursor artwork.
pub fn set_cursor_state(action: &str, delivery: &str, target: &str, active: bool) {
let _ = gdbus_call(
@@ -627,8 +627,9 @@ mod tests {
}
#[test]
- fn bundled_helper_v7_uses_the_compact_semantic_cursor_and_session_badge() {
- assert!(EXTENSION_SOURCE.contains("GetVersion() { return 7; }"));
+ fn bundled_helper_v8_uses_host_owned_modifier_badge_chips() {
+ assert!(EXTENSION_SOURCE.contains("GetVersion()"));
+ assert!(EXTENSION_SOURCE.contains("return 8;"));
assert!(EXTENSION_SOURCE.contains("SetCursorState"));
assert!(EXTENSION_SOURCE.contains("SetCursorColor"));
assert!(EXTENSION_SOURCE.contains("SetSessionLabel"));
@@ -641,7 +642,18 @@ mod tests {
assert!(EXTENSION_SOURCE.contains("width - 1"));
assert!(EXTENSION_SOURCE.contains("createGlowSurface(this._fillColor)"));
assert!(EXTENSION_SOURCE.contains("cr.translate(-GLOW_PADDING, -GLOW_PADDING);"));
- assert!(EXTENSION_METADATA.contains("\"version\":7"));
+ assert!(EXTENSION_SOURCE.contains("function drawBadgeChip"));
+ assert!(EXTENSION_SOURCE.contains("this._badge.add_child(this._badgeDot)"));
+ assert!(EXTENSION_SOURCE.contains("this._badge.add_child(this._badgeLabel)"));
+ assert!(EXTENSION_SOURCE.contains("this._deliveryChip"));
+ assert!(EXTENSION_SOURCE.contains("this._targetChip"));
+ assert!(EXTENSION_SOURCE.contains("const badgeAlpha = Math.max(labelAlpha, chipAlpha)"));
+ assert!(EXTENSION_SOURCE.contains("this._badgeLabel.hide()"));
+ assert!(!EXTENSION_SOURCE.contains("this._badgeIdentity"));
+ 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"], 8);
for action in [
"idle", "observe", "click", "drag", "scroll", "text", "key", "navigate", "app",
diff --git a/libs/cua-driver/rust/crates/platform-windows/src/overlay.rs b/libs/cua-driver/rust/crates/platform-windows/src/overlay.rs
index cb0ed0f7b0..58cfee2348 100644
--- a/libs/cua-driver/rust/crates/platform-windows/src/overlay.rs
+++ b/libs/cua-driver/rust/crates/platform-windows/src/overlay.rs
@@ -796,12 +796,12 @@ impl DirtyRect {
}
/// Conservative half-extent for the checked-in theme plus the session badge.
-/// The badge is up to 176 px wide and clamps independently at display edges,
-/// so a cursor at an edge can have badge pixels almost 176 px to one side.
+/// The badge is up to 188 px wide and clamps independently at display edges,
+/// so a cursor at an edge can have badge pixels almost 188 px to one side.
/// Custom themes use a full-surface dirty rect because their bounded artifact
/// coordinates can legitimately extend beyond this default-theme envelope.
#[cfg_attr(not(target_os = "windows"), allow(dead_code))]
-const CURSOR_PAD: i32 = 192;
+const CURSOR_PAD: i32 = cursor_overlay::session_badge::BADGE_MAX_WIDTH as i32 + 12;
#[cfg(target_os = "windows")]
struct WinSurface {
diff --git a/libs/cua-driver/tools/cursor-gallery/README.md b/libs/cua-driver/tools/cursor-gallery/README.md
index 4b59c0f445..fe041c7506 100644
--- a/libs/cua-driver/tools/cursor-gallery/README.md
+++ b/libs/cua-driver/tools/cursor-gallery/README.md
@@ -14,3 +14,7 @@ From the repository root:
`export-docs` requires Chrome, Node.js with WebSocket support, Python 3, and
ffmpeg. It regenerates the public documentation GIFs deterministically from the
same rendered frames.
+
+The gallery keeps action animations and host-rendered delivery and target
+badge chips in separate review sections. The generated modifier media is badge
+output from the production renderer, not modifier artwork from the theme.
diff --git a/libs/cua-driver/tools/cursor-gallery/index.html b/libs/cua-driver/tools/cursor-gallery/index.html
index bb54af3dc0..f30a25b352 100644
--- a/libs/cua-driver/tools/cursor-gallery/index.html
+++ b/libs/cua-driver/tools/cursor-gallery/index.html
@@ -48,10 +48,10 @@
<section class="gallery-section" aria-labelledby="modifiers-title">
<div class="section-heading">
<div>
- <p class="section-count">6 modifiers</p>
+ <p class="section-count">6 context chips</p>
<h2 id="modifiers-title">Delivery and target context</h2>
</div>
- <p>Modifiers can appear together with any action.</p>
+ <p>Host-rendered context chips can appear together with any action.</p>
</div>
<div id="modifiers-grid" class="state-grid"></div>
@@ -59,7 +59,7 @@
<div>
<p class="section-count">Combined state</p>
<h3>Foreground click at an exact pixel</h3>
- <p>Delivery stays on the left and target context stays on the right.</p>
+ <p>The filled delivery chip comes first, followed by the outlined target chip.</p>
</div>
<div class="demo">
<video
@@ -83,7 +83,9 @@
<div>
<p class="section-count">Session identity</p>
<h3>Compact label on cursor reveal</h3>
- <p>The session-tinted badge holds for two seconds, then fades while the cursor remains.</p>
+ <p>
+ The session-tinted badge holds for two seconds, then fades while the cursor remains.
+ </p>
</div>
<div class="demo">
<video
diff --git a/libs/cua-driver/wayland-helper/README.md b/libs/cua-driver/wayland-helper/README.md
index 523a0eb7e3..8e9c3735df 100644
--- a/libs/cua-driver/wayland-helper/README.md
+++ b/libs/cua-driver/wayland-helper/README.md
@@ -25,10 +25,9 @@ It exposes `org.cua.WinRects` on the session bus:
- `MoveCursor(x,y)` / `ClickPulse(x,y)` / `HideCursor()` — position and hide
the agent cursor as a Clutter actor on the compositor stage.
- `SetCursorState(action,delivery,target,active)` — render the same 12 semantic
- action states and delivery/target modifiers as the cross-platform
- `cua.default` cursor theme. The marks use session-colored centers, white
- outlines, and a tighter matching glow, while the pointer uses the larger
- cursor-shaped glow. This method was added in helper v5.
+ action states as the cross-platform `cua.default` cursor theme. Delivery and
+ target context appears as host-owned chips in the session badge rather than
+ pointer-relative theme artwork. This contract requires helper v8.
- `SetCursorColor(fill_color)` — apply the stable per-session fill selected by
cua-driver. The helper validates the `#RRGGBB` value, updates the matching
glow, and keeps a white pointer outline.
@@ -50,7 +49,7 @@ still work when it is absent, but pixel geometry, the Shell cursor, and safe
foreground portal input are unavailable. cua-driver refuses focus-bound input
instead of injecting into an unverified target.
-The semantic cursor requires helper v5. When an older helper is still loaded,
+The semantic cursor requires helper v8. When an older helper is still loaded,
cua-driver does not draw its legacy cursor. Re-run the helper installer, then
reload the GNOME session so the new compositor-owned artwork becomes active.
diff --git a/libs/cua-driver/wayland-helper/winrects@cua/extension.js b/libs/cua-driver/wayland-helper/winrects@cua/extension.js
index 444a6c9036..dd2d6044bc 100644
--- a/libs/cua-driver/wayland-helper/winrects@cua/extension.js
+++ b/libs/cua-driver/wayland-helper/winrects@cua/extension.js
@@ -5,7 +5,7 @@ import St from 'gi://St';
import Clutter from 'gi://Clutter';
import Cairo from 'cairo';
import * as Main from 'resource:///org/gnome/shell/ui/main.js';
-import {Extension} from 'resource:///org/gnome/shell/extensions/extension.js';
+import { Extension } from 'resource:///org/gnome/shell/extensions/extension.js';
Gio._promisify(Shell.Screenshot.prototype, 'screenshot');
@@ -35,721 +35,1030 @@ const GLOW_PADDING = 24;
const BADGE_Y_OFFSET = 29;
const BADGE_HOLD_SECONDS = 2.0;
const BADGE_FADE_SECONDS = 0.4;
+const BADGE_CHIP_SIZE = 18;
const ACTIONS = new Set([
- 'idle', 'observe', 'click', 'drag', 'scroll', 'text',
- 'key', 'navigate', 'app', 'transfer', 'record', 'system',
+ 'idle',
+ 'observe',
+ 'click',
+ 'drag',
+ 'scroll',
+ 'text',
+ 'key',
+ 'navigate',
+ 'app',
+ 'transfer',
+ 'record',
+ 'system',
]);
const ONE_SHOT_ACTIONS = new Set(['click', 'key', 'navigate', 'app', 'system']);
const ACTION_DURATIONS = {
- idle: 4.0,
- click: 0.67,
- observe: 1.6,
- drag: 1.6,
- scroll: 1.6,
- text: 1.6,
- key: 1.6,
- navigate: 1.6,
- app: 1.6,
- transfer: 1.6,
- record: 1.6,
- system: 1.6,
+ idle: 4.0,
+ click: 0.67,
+ observe: 1.6,
+ drag: 1.6,
+ scroll: 1.6,
+ text: 1.6,
+ key: 1.6,
+ navigate: 1.6,
+ app: 1.6,
+ transfer: 1.6,
+ record: 1.6,
+ system: 1.6,
};
function nowSeconds() {
- return GLib.get_monotonic_time() / 1_000_000;
+ return GLib.get_monotonic_time() / 1_000_000;
}
function mixChannel(base, accent, weight) {
- return Math.round(base * (1 - weight) + accent * weight);
+ return Math.round(base * (1 - weight) + accent * weight);
}
function badgeStyle(fillColor) {
- const start = fillColor.map((channel, index) =>
- mixChannel([94, 151, 178][index], channel, 0.52));
- const end = fillColor.map((channel, index) =>
- mixChannel([13, 27, 38][index], channel, 0.18));
- return [
- 'spacing: 7px',
- 'padding: 6px 10px',
- `background-gradient-start: rgba(${start[0]}, ${start[1]}, ${start[2]}, 0.93)`,
- `background-gradient-end: rgba(${end[0]}, ${end[1]}, ${end[2]}, 0.96)`,
- 'background-gradient-direction: horizontal',
- 'border: 1px solid rgba(255, 255, 255, 0.63)',
- 'border-radius: 14px',
- 'box-shadow: 0 2px 9px rgba(0, 0, 0, 0.30)',
- ].join(';');
+ const start = fillColor.map((channel, index) => mixChannel([94, 151, 178][index], channel, 0.52));
+ const end = fillColor.map((channel, index) => mixChannel([13, 27, 38][index], channel, 0.18));
+ return [
+ 'spacing: 7px',
+ 'padding: 6px 10px',
+ `background-gradient-start: rgba(${start[0]}, ${start[1]}, ${start[2]}, 0.93)`,
+ `background-gradient-end: rgba(${end[0]}, ${end[1]}, ${end[2]}, 0.96)`,
+ 'background-gradient-direction: horizontal',
+ 'border: 1px solid rgba(255, 255, 255, 0.63)',
+ 'border-radius: 14px',
+ 'box-shadow: 0 2px 9px rgba(0, 0, 0, 0.30)',
+ ].join(';');
}
function easeInOut(value) {
- const t = Math.max(0, Math.min(1, value));
- return t * t * (3 - 2 * t);
+ const t = Math.max(0, Math.min(1, value));
+ return t * t * (3 - 2 * t);
}
function triangleWave(value) {
- const t = ((value % 1) + 1) % 1;
- return t < 0.5 ? t * 2 : (1 - t) * 2;
+ const t = ((value % 1) + 1) % 1;
+ return t < 0.5 ? t * 2 : (1 - t) * 2;
}
function setInk(cr, alpha = 1) {
- cr.setSourceRGBA(1, 1, 1, alpha);
+ cr.setSourceRGBA(1, 1, 1, alpha);
}
function setPaper(cr, alpha = 1) {
- cr.setSourceRGBA(1, 1, 1, alpha);
+ cr.setSourceRGBA(1, 1, 1, alpha);
}
function setFill(cr, color, alpha = 1) {
- cr.setSourceRGBA(color[0] / 255, color[1] / 255, color[2] / 255, alpha);
+ cr.setSourceRGBA(color[0] / 255, color[1] / 255, color[2] / 255, alpha);
}
function glowPath(cr, width, alpha, glowColor) {
- if (!glowColor)
- return;
- const layers = 12;
- const outerExpansion = 13;
- const innerExpansion = 2.5;
- const maxOpacity = 0.17;
- let accumulatedOpacity = 0;
- for (let layer = 0; layer < layers; layer++) {
- const progress = (layer + 1) / layers;
- const expansion = outerExpansion + (innerExpansion - outerExpansion) * progress;
- const targetOpacity = maxOpacity * Math.max(0, Math.min(1, alpha)) *
- Math.pow(progress, 1.6);
- const layerOpacity = (targetOpacity - accumulatedOpacity) /
- Math.max(0.001, 1 - accumulatedOpacity);
- accumulatedOpacity = targetOpacity;
- cr.setLineWidth(width + expansion);
- cr.setLineCap(Cairo.LineCap.ROUND);
- cr.setLineJoin(Cairo.LineJoin.ROUND);
- setFill(cr, glowColor, layerOpacity);
- cr.strokePreserve();
- }
-}
-
-function strokePath(cr, width, alpha = 1, glowColor = null) {
- glowPath(cr, width, alpha, glowColor);
- cr.setLineWidth(glowColor ? width + 1.5 : width);
+ if (!glowColor) return;
+ const layers = 12;
+ const outerExpansion = 13;
+ const innerExpansion = 2.5;
+ const maxOpacity = 0.17;
+ let accumulatedOpacity = 0;
+ for (let layer = 0; layer < layers; layer++) {
+ const progress = (layer + 1) / layers;
+ const expansion = outerExpansion + (innerExpansion - outerExpansion) * progress;
+ const targetOpacity = maxOpacity * Math.max(0, Math.min(1, alpha)) * Math.pow(progress, 1.6);
+ const layerOpacity =
+ (targetOpacity - accumulatedOpacity) / Math.max(0.001, 1 - accumulatedOpacity);
+ accumulatedOpacity = targetOpacity;
+ cr.setLineWidth(width + expansion);
cr.setLineCap(Cairo.LineCap.ROUND);
cr.setLineJoin(Cairo.LineJoin.ROUND);
- setInk(cr, alpha);
- if (!glowColor) {
- cr.stroke();
- return;
- }
+ setFill(cr, glowColor, layerOpacity);
cr.strokePreserve();
- cr.setLineWidth(Math.max(1.5, width - 1));
- setFill(cr, glowColor, alpha);
+ }
+}
+
+function strokePath(cr, width, alpha = 1, glowColor = null) {
+ glowPath(cr, width, alpha, glowColor);
+ cr.setLineWidth(glowColor ? width + 1.5 : width);
+ cr.setLineCap(Cairo.LineCap.ROUND);
+ cr.setLineJoin(Cairo.LineJoin.ROUND);
+ setInk(cr, alpha);
+ if (!glowColor) {
cr.stroke();
+ return;
+ }
+ cr.strokePreserve();
+ cr.setLineWidth(Math.max(1.5, width - 1));
+ setFill(cr, glowColor, alpha);
+ cr.stroke();
}
function fillPath(cr, glowWidth, alpha = 1, glowColor = null) {
- glowPath(cr, glowWidth, alpha, glowColor);
- cr.setLineWidth(3);
- cr.setLineCap(Cairo.LineCap.ROUND);
- cr.setLineJoin(Cairo.LineJoin.ROUND);
- setInk(cr, alpha);
- cr.strokePreserve();
- setFill(cr, glowColor, alpha);
- cr.fill();
+ glowPath(cr, glowWidth, alpha, glowColor);
+ cr.setLineWidth(3);
+ cr.setLineCap(Cairo.LineCap.ROUND);
+ cr.setLineJoin(Cairo.LineJoin.ROUND);
+ setInk(cr, alpha);
+ cr.strokePreserve();
+ setFill(cr, glowColor, alpha);
+ cr.fill();
}
function linePath(cr, points, width = 4, alpha = 1, glowColor = null) {
- if (points.length === 0)
- return;
- cr.moveTo(points[0][0], points[0][1]);
- for (let i = 1; i < points.length; i++)
- cr.lineTo(points[i][0], points[i][1]);
- strokePath(cr, width, alpha, glowColor);
+ if (points.length === 0) return;
+ cr.moveTo(points[0][0], points[0][1]);
+ for (let i = 1; i < points.length; i++) cr.lineTo(points[i][0], points[i][1]);
+ strokePath(cr, width, alpha, glowColor);
}
function roundedRect(cr, x, y, width, height, radius) {
- const r = Math.max(0, Math.min(radius, width / 2, height / 2));
- const k = 0.5522848;
- cr.moveTo(x + r, y);
- cr.lineTo(x + width - r, y);
- cr.curveTo(x + width - r + r * k, y, x + width, y + r - r * k, x + width, y + r);
- cr.lineTo(x + width, y + height - r);
- cr.curveTo(x + width, y + height - r + r * k, x + width - r + r * k, y + height, x + width - r, y + height);
- cr.lineTo(x + r, y + height);
- cr.curveTo(x + r - r * k, y + height, x, y + height - r + r * k, x, y + height - r);
- cr.lineTo(x, y + r);
- cr.curveTo(x, y + r - r * k, x + r - r * k, y, x + r, y);
- cr.closePath();
+ const r = Math.max(0, Math.min(radius, width / 2, height / 2));
+ const k = 0.5522848;
+ cr.moveTo(x + r, y);
+ cr.lineTo(x + width - r, y);
+ cr.curveTo(x + width - r + r * k, y, x + width, y + r - r * k, x + width, y + r);
+ cr.lineTo(x + width, y + height - r);
+ cr.curveTo(
+ x + width,
+ y + height - r + r * k,
+ x + width - r + r * k,
+ y + height,
+ x + width - r,
+ y + height
+ );
+ cr.lineTo(x + r, y + height);
+ cr.curveTo(x + r - r * k, y + height, x, y + height - r + r * k, x, y + height - r);
+ cr.lineTo(x, y + r);
+ cr.curveTo(x, y + r - r * k, x + r - r * k, y, x + r, y);
+ cr.closePath();
}
function traceCursorBody(cr) {
- cr.moveTo(55, 30);
- cr.curveTo(48, 28, 42, 33, 43, 41);
- cr.lineTo(64, 98);
- cr.curveTo(67, 106, 73, 106, 77, 99);
- cr.lineTo(86, 79);
- cr.curveTo(88, 75, 91, 72, 95, 70);
- cr.lineTo(108, 63);
- cr.curveTo(115, 59, 114, 53, 107, 50);
- cr.closePath();
+ cr.moveTo(55, 30);
+ cr.curveTo(48, 28, 42, 33, 43, 41);
+ cr.lineTo(64, 98);
+ cr.curveTo(67, 106, 73, 106, 77, 99);
+ cr.lineTo(86, 79);
+ cr.curveTo(88, 75, 91, 72, 95, 70);
+ cr.lineTo(108, 63);
+ cr.curveTo(115, 59, 114, 53, 107, 50);
+ cr.closePath();
}
function drawCursorGlowShape(cr, fillColor) {
- const layers = 36;
- const outerWidth = 44;
- const innerWidth = 7;
- const maxOpacity = 0.34;
- let accumulatedOpacity = 0;
-
- for (let layer = 0; layer < layers; layer++) {
- const progress = (layer + 1) / layers;
- const width = outerWidth + (innerWidth - outerWidth) * progress;
- const targetOpacity = maxOpacity * Math.pow(progress, 1.65);
- const layerOpacity =
- (targetOpacity - accumulatedOpacity) / Math.max(0.001, 1 - accumulatedOpacity);
- accumulatedOpacity = targetOpacity;
- if (layerOpacity <= 0)
- continue;
-
- traceCursorBody(cr);
- cr.setLineWidth(width);
- cr.setLineCap(Cairo.LineCap.ROUND);
- cr.setLineJoin(Cairo.LineJoin.ROUND);
- setFill(cr, fillColor, layerOpacity);
- cr.stroke();
- }
+ const layers = 36;
+ const outerWidth = 44;
+ const innerWidth = 7;
+ const maxOpacity = 0.34;
+ let accumulatedOpacity = 0;
+
+ for (let layer = 0; layer < layers; layer++) {
+ const progress = (layer + 1) / layers;
+ const width = outerWidth + (innerWidth - outerWidth) * progress;
+ const targetOpacity = maxOpacity * Math.pow(progress, 1.65);
+ const layerOpacity =
+ (targetOpacity - accumulatedOpacity) / Math.max(0.001, 1 - accumulatedOpacity);
+ accumulatedOpacity = targetOpacity;
+ if (layerOpacity <= 0) continue;
+
+ traceCursorBody(cr);
+ cr.setLineWidth(width);
+ cr.setLineCap(Cairo.LineCap.ROUND);
+ cr.setLineJoin(Cairo.LineJoin.ROUND);
+ setFill(cr, fillColor, layerOpacity);
+ cr.stroke();
+ }
}
function createGlowSurface(fillColor) {
- const surface = new Cairo.ImageSurface(
- Cairo.Format.ARGB32,
- (CANVAS_SIZE + GLOW_PADDING * 2) * GLOW_SURFACE_SCALE,
- (CANVAS_SIZE + GLOW_PADDING * 2) * GLOW_SURFACE_SCALE
- );
- const cr = new Cairo.Context(surface);
- cr.scale(GLOW_SURFACE_SCALE, GLOW_SURFACE_SCALE);
- cr.translate(GLOW_PADDING, GLOW_PADDING);
- drawCursorGlowShape(cr, fillColor);
- cr.$dispose();
- return surface;
+ const surface = new Cairo.ImageSurface(
+ Cairo.Format.ARGB32,
+ (CANVAS_SIZE + GLOW_PADDING * 2) * GLOW_SURFACE_SCALE,
+ (CANVAS_SIZE + GLOW_PADDING * 2) * GLOW_SURFACE_SCALE
+ );
+ const cr = new Cairo.Context(surface);
+ cr.scale(GLOW_SURFACE_SCALE, GLOW_SURFACE_SCALE);
+ cr.translate(GLOW_PADDING, GLOW_PADDING);
+ drawCursorGlowShape(cr, fillColor);
+ cr.$dispose();
+ return surface;
}
function sharedFloatMotion(progress) {
- const angle = progress * Math.PI * 2;
- return {
- dx: Math.sin(angle) * 5,
- dy: Math.cos(angle) * 6 - 5,
- rotation: Math.cos(angle) * (2.5 * Math.PI / 180),
- scale: 1,
- };
+ const angle = progress * Math.PI * 2;
+ return {
+ dx: Math.sin(angle) * 5,
+ dy: Math.cos(angle) * 6 - 5,
+ rotation: Math.cos(angle) * ((2.5 * Math.PI) / 180),
+ scale: 1,
+ };
}
function cursorBodyMotion(progress, action) {
- let dx = 0;
- let dy = 0;
- let rotation = 0;
- let scale = 1;
-
- if (action === 'click') {
- if (progress < 0.35)
- scale = 1 - easeInOut(progress / 0.35) * 0.07;
- else if (progress < 0.6)
- scale = 0.93 + easeInOut((progress - 0.35) / 0.25) * 0.10;
- else
- scale = 1.03 - easeInOut((progress - 0.6) / 0.4) * 0.03;
- } else if (action === 'drag') {
- const held = easeInOut(triangleWave(progress));
- dx = held * 7;
- dy = held * 3;
- }
+ let dx = 0;
+ let dy = 0;
+ let rotation = 0;
+ let scale = 1;
+
+ if (action === 'click') {
+ if (progress < 0.35) scale = 1 - easeInOut(progress / 0.35) * 0.07;
+ else if (progress < 0.6) scale = 0.93 + easeInOut((progress - 0.35) / 0.25) * 0.1;
+ else scale = 1.03 - easeInOut((progress - 0.6) / 0.4) * 0.03;
+ } else if (action === 'drag') {
+ const held = easeInOut(triangleWave(progress));
+ dx = held * 7;
+ dy = held * 3;
+ }
- return {dx, dy, rotation, scale};
+ return { dx, dy, rotation, scale };
}
function applyCursorBodyMotion(cr, motion) {
- cr.translate(64 + motion.dx, 64 + motion.dy);
- cr.rotate(motion.rotation);
- cr.scale(motion.scale, motion.scale);
- cr.translate(-64, -64);
+ cr.translate(64 + motion.dx, 64 + motion.dy);
+ cr.rotate(motion.rotation);
+ cr.scale(motion.scale, motion.scale);
+ cr.translate(-64, -64);
}
function drawCursorGlow(cr, progress, action, glowSurface) {
- const motion = cursorBodyMotion(progress, action);
- cr.save();
- applyCursorBodyMotion(cr, motion);
- cr.translate(-GLOW_PADDING, -GLOW_PADDING);
- cr.scale(1 / GLOW_SURFACE_SCALE, 1 / GLOW_SURFACE_SCALE);
- cr.setSourceSurface(glowSurface, 0, 0);
- cr.paint();
- cr.restore();
+ const motion = cursorBodyMotion(progress, action);
+ cr.save();
+ applyCursorBodyMotion(cr, motion);
+ cr.translate(-GLOW_PADDING, -GLOW_PADDING);
+ cr.scale(1 / GLOW_SURFACE_SCALE, 1 / GLOW_SURFACE_SCALE);
+ cr.setSourceSurface(glowSurface, 0, 0);
+ cr.paint();
+ cr.restore();
}
function drawCursorBody(cr, progress, action, fillColor) {
- const motion = cursorBodyMotion(progress, action);
- cr.save();
- applyCursorBodyMotion(cr, motion);
- traceCursorBody(cr);
- setFill(cr, fillColor);
- cr.fillPreserve();
- cr.setLineWidth(5);
- cr.setLineCap(Cairo.LineCap.ROUND);
- cr.setLineJoin(Cairo.LineJoin.ROUND);
- setPaper(cr);
- cr.stroke();
- cr.restore();
+ const motion = cursorBodyMotion(progress, action);
+ cr.save();
+ applyCursorBodyMotion(cr, motion);
+ traceCursorBody(cr);
+ setFill(cr, fillColor);
+ cr.fillPreserve();
+ cr.setLineWidth(5);
+ cr.setLineCap(Cairo.LineCap.ROUND);
+ cr.setLineJoin(Cairo.LineJoin.ROUND);
+ setPaper(cr);
+ cr.stroke();
+ cr.restore();
}
function drawActionCue(cr, action, progress, fillColor) {
- const wave = triangleWave(progress);
- const strokeCue = (width, alpha = 1) =>
- strokePath(cr, width, alpha, fillColor);
- const lineCue = (points, width = 4, alpha = 1) =>
- linePath(cr, points, width, alpha, fillColor);
- cr.save();
- switch (action) {
+ const wave = triangleWave(progress);
+ const strokeCue = (width, alpha = 1) => strokePath(cr, width, alpha, fillColor);
+ const lineCue = (points, width = 4, alpha = 1) => linePath(cr, points, width, alpha, fillColor);
+ cr.save();
+ switch (action) {
case 'observe': {
- const opacity = Math.min(1, progress * 7);
- cr.translate(8, -10);
- cr.moveTo(38, 28);
- cr.curveTo(27, 29, 20, 38, 20, 49);
- strokeCue(4, opacity);
- cr.moveTo(42, 19);
- cr.curveTo(23, 19, 11, 33, 11, 51);
- strokeCue(4, opacity);
- break;
+ const opacity = Math.min(1, progress * 7);
+ cr.translate(8, -10);
+ cr.moveTo(38, 28);
+ cr.curveTo(27, 29, 20, 38, 20, 49);
+ strokeCue(4, opacity);
+ cr.moveTo(42, 19);
+ cr.curveTo(23, 19, 11, 33, 11, 51);
+ strokeCue(4, opacity);
+ break;
}
case 'click': {
- const cueProgress = Math.max(0, Math.min(1, progress / 0.65));
- const opacity = Math.max(0, Math.min(1,
- Math.min(1 - Math.pow(cueProgress, 1.35), cueProgress * 5)));
- const cueScale = 1.1 + easeInOut(cueProgress) * 0.4;
- cr.translate(35, 28);
- cr.scale(cueScale, cueScale);
- cr.translate(-25, -25);
- lineCue([[35, 20], [34, 11]], 4, opacity);
- lineCue([[27, 25], [19, 19]], 4, opacity);
- lineCue([[25, 34], [15, 34]], 4, opacity);
- break;
+ const cueProgress = Math.max(0, Math.min(1, progress / 0.65));
+ const opacity = Math.max(
+ 0,
+ Math.min(1, Math.min(1 - Math.pow(cueProgress, 1.35), cueProgress * 5))
+ );
+ const cueScale = 1.1 + easeInOut(cueProgress) * 0.4;
+ cr.translate(35, 28);
+ cr.scale(cueScale, cueScale);
+ cr.translate(-25, -25);
+ lineCue(
+ [
+ [35, 20],
+ [34, 11],
+ ],
+ 4,
+ opacity
+ );
+ lineCue(
+ [
+ [27, 25],
+ [19, 19],
+ ],
+ 4,
+ opacity
+ );
+ lineCue(
+ [
+ [25, 34],
+ [15, 34],
+ ],
+ 4,
+ opacity
+ );
+ break;
}
case 'drag': {
- const offset = easeInOut(wave) * 7;
- cr.translate(offset, offset * 0.43);
- lineCue([[28, 38], [16, 35]], 4, 0.2 + wave * 0.8);
- lineCue([[26, 48], [12, 45]], 4, 0.2 + wave * 0.8);
- break;
+ const offset = easeInOut(wave) * 7;
+ cr.translate(offset, offset * 0.43);
+ lineCue(
+ [
+ [28, 38],
+ [16, 35],
+ ],
+ 4,
+ 0.2 + wave * 0.8
+ );
+ lineCue(
+ [
+ [26, 48],
+ [12, 45],
+ ],
+ 4,
+ 0.2 + wave * 0.8
+ );
+ break;
}
case 'scroll': {
- cr.translate(-5, 4 - wave * 8);
- lineCue([[23, 31], [31, 22], [39, 31]], 4, 0.42 + wave * 0.58);
- lineCue([[23, 49], [31, 58], [39, 49]], 4, 0.42 + wave * 0.58);
- break;
+ cr.translate(-5, 4 - wave * 8);
+ lineCue(
+ [
+ [23, 31],
+ [31, 22],
+ [39, 31],
+ ],
+ 4,
+ 0.42 + wave * 0.58
+ );
+ lineCue(
+ [
+ [23, 49],
+ [31, 58],
+ [39, 49],
+ ],
+ 4,
+ 0.42 + wave * 0.58
+ );
+ break;
}
case 'text': {
- const opacity = progress < 0.34 || progress > 0.64 ? 1 : 0.18;
- cr.translate(-4, 0);
- lineCue([[31, 22], [31, 58]], 4, opacity);
- lineCue([[24, 22], [38, 22]], 4, opacity);
- lineCue([[24, 58], [38, 58]], 4, opacity);
- break;
+ const opacity = progress < 0.34 || progress > 0.64 ? 1 : 0.18;
+ cr.translate(-4, 0);
+ lineCue(
+ [
+ [31, 22],
+ [31, 58],
+ ],
+ 4,
+ opacity
+ );
+ lineCue(
+ [
+ [24, 22],
+ [38, 22],
+ ],
+ 4,
+ opacity
+ );
+ lineCue(
+ [
+ [24, 58],
+ [38, 58],
+ ],
+ 4,
+ opacity
+ );
+ break;
}
case 'key': {
- const bounce = Math.sin(progress * Math.PI * 2) * (1 - progress) * 3;
- cr.translate(-9, bounce);
- roundedRect(cr, 14, 25, 28, 28, 6);
- strokeCue(3.5);
- lineCue([[23, 32], [23, 46], [23, 39], [33, 32], [24, 39], [34, 46]], 3.5);
- break;
+ const bounce = Math.sin(progress * Math.PI * 2) * (1 - progress) * 3;
+ cr.translate(-9, bounce);
+ roundedRect(cr, 14, 25, 28, 28, 6);
+ strokeCue(3.5);
+ lineCue(
+ [
+ [23, 32],
+ [23, 46],
+ [23, 39],
+ [33, 32],
+ [24, 39],
+ [34, 46],
+ ],
+ 3.5
+ );
+ break;
}
case 'navigate': {
- cr.translate(-10 + easeInOut(progress) * 9, 0);
- lineCue([[15, 29], [25, 40], [15, 51]], 4, 0.2 + wave * 0.8);
- lineCue([[29, 29], [39, 40], [29, 51]], 4, 0.2 + wave * 0.8);
- break;
+ cr.translate(-10 + easeInOut(progress) * 9, 0);
+ lineCue(
+ [
+ [15, 29],
+ [25, 40],
+ [15, 51],
+ ],
+ 4,
+ 0.2 + wave * 0.8
+ );
+ lineCue(
+ [
+ [29, 29],
+ [39, 40],
+ [29, 51],
+ ],
+ 4,
+ 0.2 + wave * 0.8
+ );
+ break;
}
case 'app': {
- const s = 0.2 + easeInOut(Math.min(1, progress * 2)) * 0.8;
- cr.translate(21, 39);
- cr.scale(s, s);
- cr.translate(-26, -39);
- for (const [x, y] of [[13, 26], [29, 26], [13, 42], [29, 42]]) {
- roundedRect(cr, x, y, 10, 10, 2);
- strokeCue(3.5);
- }
- break;
+ const s = 0.2 + easeInOut(Math.min(1, progress * 2)) * 0.8;
+ cr.translate(21, 39);
+ cr.scale(s, s);
+ cr.translate(-26, -39);
+ for (const [x, y] of [
+ [13, 26],
+ [29, 26],
+ [13, 42],
+ [29, 42],
+ ]) {
+ roundedRect(cr, x, y, 10, 10, 2);
+ strokeCue(3.5);
+ }
+ break;
}
case 'transfer':
- cr.translate(-9, 6 - wave * 12);
- lineCue([[22, 50], [22, 20], [14, 28], [22, 20], [30, 28]], 4, 0.38 + wave * 0.62);
- lineCue([[37, 28], [37, 58], [29, 50], [37, 58], [45, 50]], 4, 0.38 + wave * 0.62);
- break;
+ cr.translate(-9, 6 - wave * 12);
+ lineCue(
+ [
+ [22, 50],
+ [22, 20],
+ [14, 28],
+ [22, 20],
+ [30, 28],
+ ],
+ 4,
+ 0.38 + wave * 0.62
+ );
+ lineCue(
+ [
+ [37, 28],
+ [37, 58],
+ [29, 50],
+ [37, 58],
+ [45, 50],
+ ],
+ 4,
+ 0.38 + wave * 0.62
+ );
+ break;
case 'record':
- cr.translate(-12, 0);
- cr.arc(29, 39, 17, 0, Math.PI * 2);
- strokeCue(4);
- cr.arc(29, 39, 3.6 + wave * 2.1, 0, Math.PI * 2);
- fillPath(cr, (3.6 + wave * 2.1) * 1.25, 0.42 + wave * 0.58, fillColor);
- break;
+ cr.translate(-12, 0);
+ cr.arc(29, 39, 17, 0, Math.PI * 2);
+ strokeCue(4);
+ cr.arc(29, 39, 3.6 + wave * 2.1, 0, Math.PI * 2);
+ fillPath(cr, (3.6 + wave * 2.1) * 1.25, 0.42 + wave * 0.58, fillColor);
+ break;
case 'system': {
- cr.translate(15, 39);
- cr.rotate((easeInOut(progress) * 68 - 18) * Math.PI / 180);
- cr.translate(-29, -39);
- for (const radius of [12, 4]) {
- cr.arc(29, 39, radius, 0, Math.PI * 2);
- strokeCue(3.5);
- }
- for (const points of [
- [[29, 20], [29, 25]], [[29, 53], [29, 58]],
- [[10, 39], [15, 39]], [[43, 39], [48, 39]],
- [[16, 26], [20, 30]], [[38, 48], [42, 52]],
- [[16, 52], [20, 48]], [[38, 30], [42, 26]],
- ])
- lineCue(points, 3.5);
- break;
+ cr.translate(15, 39);
+ cr.rotate(((easeInOut(progress) * 68 - 18) * Math.PI) / 180);
+ cr.translate(-29, -39);
+ for (const radius of [12, 4]) {
+ cr.arc(29, 39, radius, 0, Math.PI * 2);
+ strokeCue(3.5);
+ }
+ for (const points of [
+ [
+ [29, 20],
+ [29, 25],
+ ],
+ [
+ [29, 53],
+ [29, 58],
+ ],
+ [
+ [10, 39],
+ [15, 39],
+ ],
+ [
+ [43, 39],
+ [48, 39],
+ ],
+ [
+ [16, 26],
+ [20, 30],
+ ],
+ [
+ [38, 48],
+ [42, 52],
+ ],
+ [
+ [16, 52],
+ [20, 48],
+ ],
+ [
+ [38, 30],
+ [42, 26],
+ ],
+ ])
+ lineCue(points, 3.5);
+ break;
}
default:
- break;
- }
- cr.restore();
+ break;
+ }
+ cr.restore();
}
-function drawModifiers(cr, delivery, target, fillColor) {
- const strokeCue = (width, alpha = 1) =>
- strokePath(cr, width, alpha, fillColor);
- const lineCue = (points, width = 4, alpha = 1) =>
- linePath(cr, points, width, alpha, fillColor);
- if (delivery === 'background') {
- cr.save();
- cr.setDash([1, 5], 0);
- cr.moveTo(34, 23);
- cr.curveTo(20, 31, 17, 48, 21, 63);
- cr.curveTo(25, 80, 38, 95, 53, 106);
- strokeCue(2.5, 0.75);
- cr.restore();
- } else if (delivery === 'foreground') {
- cr.arc(25, 90, 9, 0, Math.PI * 2);
- strokeCue(3);
- }
+function drawBadgeChip(cr, glyph, filled, fillColor) {
+ roundedRect(cr, 0.5, 0.5, 17, 17, 5);
+ if (filled) {
+ cr.setSourceRGBA(fillColor[0] / 255, fillColor[1] / 255, fillColor[2] / 255, 0.86);
+ cr.fillPreserve();
+ } else {
+ cr.setSourceRGBA(1, 1, 1, 0.09);
+ cr.fillPreserve();
+ }
+ cr.setSourceRGBA(1, 1, 1, filled ? 0.72 : 0.42);
+ cr.setLineWidth(1);
+ cr.stroke();
+ cr.setSourceRGBA(1, 1, 1, 0.95);
+ cr.setLineWidth(1.35);
+ cr.setLineCap(Cairo.LineCap.ROUND);
+ cr.setLineJoin(Cairo.LineJoin.ROUND);
- switch (target) {
+ const stroke = () => cr.stroke();
+ const line = (points) => {
+ cr.moveTo(points[0][0], points[0][1]);
+ for (const [x, y] of points.slice(1)) cr.lineTo(x, y);
+ stroke();
+ };
+ switch (glyph) {
+ case 'background':
+ roundedRect(cr, 4, 4, 7, 7, 1.8);
+ stroke();
+ roundedRect(cr, 6.4, 6.4, 7, 7, 1.8);
+ stroke();
+ break;
+ case 'foreground':
+ roundedRect(cr, 4, 5, 10, 9, 1.8);
+ stroke();
+ line([
+ [5, 7.6],
+ [13, 7.6],
+ ]);
+ break;
case 'ax':
- for (const [x, y] of [[104, 89], [94, 104], [114, 104]]) {
- cr.arc(x, y, 3, 0, Math.PI * 2);
- strokeCue(2.5);
- }
- lineCue([[104, 92], [104, 97], [94, 101], [104, 97], [114, 101]], 2.5);
- break;
+ line([
+ [9, 5],
+ [9, 9],
+ [5, 13],
+ ]);
+ line([
+ [9, 9],
+ [13, 13],
+ ]);
+ for (const [x, y] of [
+ [9, 5],
+ [5, 13],
+ [13, 13],
+ ]) {
+ cr.arc(x, y, 1.35, 0, Math.PI * 2);
+ cr.fill();
+ }
+ break;
case 'pixel':
- cr.save();
- cr.setDash([2, 3], 0);
- cr.rectangle(94, 91, 19, 19);
- strokeCue(2.5);
- cr.restore();
- break;
+ line([
+ [4, 7],
+ [4, 4],
+ [7, 4],
+ ]);
+ line([
+ [11, 4],
+ [14, 4],
+ [14, 7],
+ ]);
+ line([
+ [14, 11],
+ [14, 14],
+ [11, 14],
+ ]);
+ line([
+ [7, 14],
+ [4, 14],
+ [4, 11],
+ ]);
+ break;
case 'browser':
- cr.arc(104, 100, 10, 0, Math.PI * 2);
- strokeCue(2.5);
- lineCue([[94, 100], [114, 100]], 2.5);
- lineCue([[104, 90], [100, 100], [104, 110]], 2.5);
- lineCue([[104, 90], [108, 100], [104, 110]], 2.5);
- break;
+ cr.arc(9, 9, 5, 0, Math.PI * 2);
+ stroke();
+ line([
+ [4, 9],
+ [14, 9],
+ ]);
+ line([
+ [9, 4],
+ [7, 9],
+ [9, 14],
+ [11, 9],
+ [9, 4],
+ ]);
+ break;
case 'desktop':
- roundedRect(cr, 93, 90, 21, 15, 2);
- strokeCue(2.5);
- lineCue([[103.5, 105], [103.5, 110], [97, 110], [110, 110]], 2.5);
- break;
+ roundedRect(cr, 4, 4, 10, 7.6, 1.3);
+ stroke();
+ line([
+ [9, 11.6],
+ [9, 14],
+ [6, 14],
+ [12, 14],
+ ]);
+ break;
default:
- break;
- }
+ break;
+ }
}
export default class WinRectsExtension extends Extension {
- enable() {
- this._impl = Gio.DBusExportedObject.wrapJSObject(IFACE, this);
- this._impl.export(Gio.DBus.session, '/org/cua/WinRects');
- this._nameId = Gio.bus_own_name(Gio.BusType.SESSION, 'org.cua.WinRects',
- Gio.BusNameOwnerFlags.REPLACE, null, null, null);
- this._action = 'idle';
- this._delivery = '';
- this._target = '';
- this._actionStarted = nowSeconds();
- this._endingAt = null;
- this._fillColor = [94, 192, 232];
- this._fillColorCss = '#5ec0e8';
- this._glowSurface = createGlowSurface(this._fillColor);
- this._cursor = new St.DrawingArea({
- width: ACTOR_SIZE,
- height: ACTOR_SIZE,
- visible: false,
- reactive: false,
- can_focus: false,
- });
- this._cursor.connect('repaint', (area) => {
- const cr = area.get_context();
- const duration = ACTION_DURATIONS[this._action] ?? 1.6;
- const elapsed = nowSeconds() - this._actionStarted;
- const progress = (elapsed % duration) / duration;
- const floatProgress = (elapsed % FLOAT_DURATION) / FLOAT_DURATION;
- cr.save();
- cr.translate(ACTOR_CENTER, ACTOR_CENTER);
- cr.scale(SCALE, SCALE);
- cr.translate(-CANVAS_SIZE / 2, -CANVAS_SIZE / 2);
- applyCursorBodyMotion(cr, sharedFloatMotion(floatProgress));
- drawCursorGlow(cr, progress, this._action, this._glowSurface);
- drawActionCue(cr, this._action, progress, this._fillColor);
- drawCursorBody(cr, progress, this._action, this._fillColor);
- drawModifiers(cr, this._delivery, this._target, this._fillColor);
- cr.restore();
- cr.$dispose();
- });
- this._cursor.set_pivot_point(0.5, 0.5);
- Main.layoutManager.addTopChrome(this._cursor);
- this._badgeDot = new St.Widget({
- width: 10,
- height: 10,
- style: `background-color: ${this._fillColorCss}; border: 1px solid white; border-radius: 99px;`,
- y_align: Clutter.ActorAlign.CENTER,
- });
- this._badgeLabel = new St.Label({
- text: '',
- y_align: Clutter.ActorAlign.CENTER,
- style: 'font-size: 11px; font-weight: 600; color: white;',
- });
- this._badge = new St.BoxLayout({
- visible: false,
- reactive: false,
- can_focus: false,
- style: badgeStyle(this._fillColor),
- });
- this._badge.add_child(this._badgeDot);
- this._badge.add_child(this._badgeLabel);
- Main.layoutManager.addTopChrome(this._badge);
- this._cursorX = null;
- this._cursorY = null;
- this._badgeRevealedAt = null;
- this._frameId = GLib.timeout_add(GLib.PRIORITY_DEFAULT, 33, () => {
- if (!this._cursor)
- return GLib.SOURCE_REMOVE;
- const now = nowSeconds();
- if (this._endingAt !== null && now >= this._endingAt)
- this._setCursorState('idle', '', '');
- if (ONE_SHOT_ACTIONS.has(this._action) &&
- now - this._actionStarted >= ACTION_DURATIONS[this._action])
- this._setCursorState('idle', '', '');
- if (this._cursor.visible)
- this._cursor.queue_repaint();
- if (this._badge?.visible && this._badgeRevealedAt !== null) {
- const badgeElapsed = now - this._badgeRevealedAt;
- if (badgeElapsed <= BADGE_HOLD_SECONDS) {
- this._badge.opacity = 255;
- } else if (badgeElapsed < BADGE_HOLD_SECONDS + BADGE_FADE_SECONDS) {
- const fade = (badgeElapsed - BADGE_HOLD_SECONDS) / BADGE_FADE_SECONDS;
- this._badge.opacity = Math.round(255 * (1 - fade));
- } else {
- this._badge.hide();
- this._badgeRevealedAt = null;
- }
- }
- return GLib.SOURCE_CONTINUE;
- });
- }
- disable() {
- if (this._frameId) {
- GLib.source_remove(this._frameId);
- this._frameId = 0;
+ enable() {
+ this._impl = Gio.DBusExportedObject.wrapJSObject(IFACE, this);
+ this._impl.export(Gio.DBus.session, '/org/cua/WinRects');
+ this._nameId = Gio.bus_own_name(
+ Gio.BusType.SESSION,
+ 'org.cua.WinRects',
+ Gio.BusNameOwnerFlags.REPLACE,
+ null,
+ null,
+ null
+ );
+ this._action = 'idle';
+ this._delivery = '';
+ this._target = '';
+ this._actionStarted = nowSeconds();
+ this._endingAt = null;
+ this._fillColor = [94, 192, 232];
+ this._fillColorCss = '#5ec0e8';
+ this._glowSurface = createGlowSurface(this._fillColor);
+ this._cursor = new St.DrawingArea({
+ width: ACTOR_SIZE,
+ height: ACTOR_SIZE,
+ visible: false,
+ reactive: false,
+ can_focus: false,
+ });
+ this._cursor.connect('repaint', (area) => {
+ const cr = area.get_context();
+ const duration = ACTION_DURATIONS[this._action] ?? 1.6;
+ const elapsed = nowSeconds() - this._actionStarted;
+ const progress = (elapsed % duration) / duration;
+ const floatProgress = (elapsed % FLOAT_DURATION) / FLOAT_DURATION;
+ cr.save();
+ cr.translate(ACTOR_CENTER, ACTOR_CENTER);
+ cr.scale(SCALE, SCALE);
+ cr.translate(-CANVAS_SIZE / 2, -CANVAS_SIZE / 2);
+ applyCursorBodyMotion(cr, sharedFloatMotion(floatProgress));
+ drawCursorGlow(cr, progress, this._action, this._glowSurface);
+ drawActionCue(cr, this._action, progress, this._fillColor);
+ drawCursorBody(cr, progress, this._action, this._fillColor);
+ cr.restore();
+ cr.$dispose();
+ });
+ this._cursor.set_pivot_point(0.5, 0.5);
+ Main.layoutManager.addTopChrome(this._cursor);
+ this._badgeDot = new St.Widget({
+ width: 10,
+ height: 10,
+ style: `background-color: ${this._fillColorCss}; border: 1px solid white; border-radius: 99px;`,
+ y_align: Clutter.ActorAlign.CENTER,
+ });
+ this._badgeLabel = new St.Label({
+ text: '',
+ visible: false,
+ y_align: Clutter.ActorAlign.CENTER,
+ style: 'font-size: 11px; font-weight: 600; color: white;',
+ });
+ this._deliveryChip = new St.DrawingArea({
+ width: BADGE_CHIP_SIZE,
+ height: BADGE_CHIP_SIZE,
+ visible: false,
+ });
+ this._deliveryChip.connect('repaint', (area) => {
+ const cr = area.get_context();
+ drawBadgeChip(cr, this._delivery, true, this._fillColor);
+ cr.$dispose();
+ });
+ this._targetChip = new St.DrawingArea({
+ width: BADGE_CHIP_SIZE,
+ height: BADGE_CHIP_SIZE,
+ visible: false,
+ });
+ this._targetChip.connect('repaint', (area) => {
+ const cr = area.get_context();
+ drawBadgeChip(cr, this._target, false, this._fillColor);
+ cr.$dispose();
+ });
+ this._badge = new St.BoxLayout({
+ visible: false,
+ reactive: false,
+ can_focus: false,
+ style: badgeStyle(this._fillColor),
+ });
+ this._badge.add_child(this._badgeDot);
+ this._badge.add_child(this._badgeLabel);
+ this._badge.add_child(this._deliveryChip);
+ this._badge.add_child(this._targetChip);
+ Main.layoutManager.addTopChrome(this._badge);
+ this._cursorX = null;
+ this._cursorY = null;
+ this._badgeRevealedAt = null;
+ this._modifierFadeAt = null;
+ this._frameId = GLib.timeout_add(GLib.PRIORITY_DEFAULT, 33, () => {
+ if (!this._cursor) return GLib.SOURCE_REMOVE;
+ const now = nowSeconds();
+ if (this._endingAt !== null && now >= this._endingAt) this._setCursorState('idle', '', '');
+ if (
+ ONE_SHOT_ACTIONS.has(this._action) &&
+ now - this._actionStarted >= ACTION_DURATIONS[this._action]
+ )
+ this._setCursorState('idle', '', '');
+ if (this._cursor.visible) this._cursor.queue_repaint();
+ let labelAlpha = this._badgeRevealedAt === null ? 0 : 1;
+ if (this._badgeRevealedAt !== null) {
+ const badgeElapsed = now - this._badgeRevealedAt;
+ if (
+ badgeElapsed > BADGE_HOLD_SECONDS &&
+ badgeElapsed < BADGE_HOLD_SECONDS + BADGE_FADE_SECONDS
+ ) {
+ const fade = (badgeElapsed - BADGE_HOLD_SECONDS) / BADGE_FADE_SECONDS;
+ labelAlpha = 1 - easeInOut(fade);
+ } else if (badgeElapsed >= BADGE_HOLD_SECONDS + BADGE_FADE_SECONDS) {
+ labelAlpha = 0;
+ this._badgeRevealedAt = null;
}
- if (this._cursor) { this._cursor.destroy(); this._cursor = null; }
- if (this._badge) { this._badge.destroy(); this._badge = null; }
- this._badgeDot = null;
- this._badgeLabel = null;
- if (this._glowSurface) {
- this._glowSurface.finish();
- this._glowSurface = null;
+ }
+ let chipAlpha = this._delivery || this._target ? 1 : 0;
+ if (this._modifierFadeAt !== null) {
+ const fade = (now - this._modifierFadeAt) / BADGE_FADE_SECONDS;
+ chipAlpha = 1 - easeInOut(fade);
+ if (fade >= 1) {
+ chipAlpha = 0;
+ this._modifierFadeAt = null;
+ this._delivery = '';
+ this._target = '';
+ this._updateModifierChips();
}
- if (this._impl) { this._impl.unexport(); this._impl = null; }
- if (this._nameId) { Gio.bus_unown_name(this._nameId); this._nameId = 0; }
- }
- GetVersion() { return 7; }
- GetRects() {
- const actors = global.get_window_actors();
- const actorByWindow = new Map();
- for (const actor of actors) {
- if (actor.meta_window)
- actorByWindow.set(actor.meta_window, actor);
+ }
+ const badgeAlpha = Math.max(labelAlpha, chipAlpha);
+ if (this._badgeDot) this._badgeDot.opacity = Math.round(255 * badgeAlpha);
+ if (this._badgeLabel) {
+ this._badgeLabel.opacity = Math.round(255 * labelAlpha);
+ if (labelAlpha <= 0.001 && this._badgeLabel.visible) {
+ this._badgeLabel.hide();
+ if (this._cursorX !== null && this._cursorY !== null)
+ this._positionBadge(this._cursorX, this._cursorY, 0);
}
- const windows = global.display.sort_windows_by_stacking([...actorByWindow.keys()]);
- const focusedWindow = global.display.focus_window;
- const out = [];
- for (let stacking = 0; stacking < windows.length; stacking++) {
- const w = windows[stacking];
- const actor = actorByWindow.get(w);
- const r = w.get_frame_rect();
- let buffer = r;
- try {
- buffer = w.get_buffer_rect();
- } catch (_error) {
- // Older Shell releases may not expose the buffer rectangle.
- }
- const minimized = Boolean(w.minimized);
- out.push({
- id: w.get_stable_sequence(),
- pid: w.get_pid(),
- title: w.get_title() ?? '',
- x: r.x,
- y: r.y,
- w: r.width,
- h: r.height,
- buffer_x: buffer.x,
- buffer_y: buffer.y,
- focused: focusedWindow === w,
- minimized,
- visible: Boolean(actor?.visible) && !minimized,
- stacking,
- });
+ }
+ if (this._deliveryChip) this._deliveryChip.opacity = Math.round(255 * chipAlpha);
+ if (this._targetChip) this._targetChip.opacity = Math.round(255 * chipAlpha);
+ if (this._badge) {
+ if (labelAlpha > 0.001 || chipAlpha > 0.001) {
+ this._badge.opacity = 255;
+ this._badge.show();
+ } else {
+ this._badge.hide();
}
- return JSON.stringify(out);
+ }
+ return GLib.SOURCE_CONTINUE;
+ });
+ }
+ disable() {
+ if (this._frameId) {
+ GLib.source_remove(this._frameId);
+ this._frameId = 0;
}
- async CaptureAsync(_params, invocation) {
- try {
- const shooter = new Shell.Screenshot();
- const stream = Gio.MemoryOutputStream.new_resizable();
- const [width, height] = global.display.get_size();
- if (width <= 0 || height <= 0)
- throw new Error(`Invalid display size ${width}x${height}`);
- // GNOME 50's stage-content capture copies the real cursor sprite
- // after painting the stage. Remote/headless pointer seats can
- // expose a 0x0 sprite, and that copy can crash Shell. The stream
- // API has an explicit include_cursor flag, so keep cursor capture
- // disabled; cua-driver draws its own agent cursor.
- await shooter.screenshot(false, stream);
- stream.close(null);
- const encoded = GLib.base64_encode(stream.steal_as_bytes().get_data());
- invocation.return_value(new GLib.Variant('(s)', [encoded]));
- } catch (error) {
- invocation.return_dbus_error('org.cua.WinRects.CaptureFailed', String(error));
- }
+ if (this._cursor) {
+ this._cursor.destroy();
+ this._cursor = null;
}
- ActivateAsync([id], invocation) {
- const target = global.get_window_actors()
- .map(actor => actor.meta_window)
- .find(window => window?.get_stable_sequence() === id);
- if (!target) {
- invocation.return_value(new GLib.Variant('(b)', [false]));
- return;
- }
- target.activate(global.get_current_time());
- GLib.timeout_add(GLib.PRIORITY_DEFAULT, 100, () => {
- invocation.return_value(new GLib.Variant(
- '(b)',
- [global.display.focus_window === target]
- ));
- return GLib.SOURCE_REMOVE;
- });
+ if (this._badge) {
+ this._badge.destroy();
+ this._badge = null;
}
- MoveCursor(x, y) {
- if (!this._cursor) return;
- const revealBadge = !this._cursor.visible;
- this._cursorX = x;
- this._cursorY = y;
- this._cursor.show();
- this._cursor.ease({
- x: x - ACTOR_CENTER,
- y: y - ACTOR_CENTER,
- duration: 480,
- mode: Clutter.AnimationMode.EASE_OUT_CUBIC,
- });
- this._positionBadge(x, y, 480);
- if (revealBadge)
- this._revealBadge();
+ this._badgeDot = null;
+ this._badgeLabel = null;
+ this._deliveryChip = null;
+ this._targetChip = null;
+ if (this._glowSurface) {
+ this._glowSurface.finish();
+ this._glowSurface = null;
}
- 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);
- if (['idle', 'navigate', 'click'].includes(this._action))
- this._setCursorState('click', this._delivery, this._target);
- this._cursor.show();
- this._cursor.queue_repaint();
- if (revealBadge)
- this._revealBadge();
+ if (this._impl) {
+ this._impl.unexport();
+ this._impl = null;
}
- SetCursorColor(fillColor) {
- const match = /^#([0-9a-fA-F]{6})$/.exec(fillColor);
- if (!match)
- return;
- const rgb = Number.parseInt(match[1], 16);
- this._fillColor = [(rgb >> 16) & 0xff, (rgb >> 8) & 0xff, rgb & 0xff];
- this._fillColorCss = `#${match[1].toLowerCase()}`;
- if (this._badgeDot)
- this._badgeDot.set_style(
- `background-color: ${this._fillColorCss}; border: 1px solid white; border-radius: 99px;`
- );
- if (this._badge)
- this._badge.set_style(badgeStyle(this._fillColor));
- if (this._glowSurface)
- this._glowSurface.finish();
- this._glowSurface = createGlowSurface(this._fillColor);
- if (this._cursor)
- this._cursor.queue_repaint();
+ if (this._nameId) {
+ Gio.bus_unown_name(this._nameId);
+ this._nameId = 0;
}
- SetCursorState(action, delivery, target, active) {
- if (!ACTIONS.has(action))
- return;
- if (active) {
- this._setCursorState(action, delivery, target);
- } else if (this._action === action && !ONE_SHOT_ACTIONS.has(action)) {
- this._endingAt = nowSeconds() + 0.4;
- }
+ }
+ GetVersion() {
+ return 8;
+ }
+ GetRects() {
+ const actors = global.get_window_actors();
+ const actorByWindow = new Map();
+ for (const actor of actors) {
+ if (actor.meta_window) actorByWindow.set(actor.meta_window, actor);
}
- SetSessionLabel(label) {
- if (!this._badgeLabel || !this._badge)
- return;
- this._badgeLabel.set_text(label);
- if (label.length === 0 || !this._cursor?.visible) {
- this._badge.hide();
- this._badgeRevealedAt = null;
- return;
- }
- if (this._cursorX !== null && this._cursorY !== null) {
- this._positionBadge(this._cursorX, this._cursorY, 0);
- this._revealBadge();
- }
+ const windows = global.display.sort_windows_by_stacking([...actorByWindow.keys()]);
+ const focusedWindow = global.display.focus_window;
+ const out = [];
+ for (let stacking = 0; stacking < windows.length; stacking++) {
+ const w = windows[stacking];
+ const actor = actorByWindow.get(w);
+ const r = w.get_frame_rect();
+ let buffer = r;
+ try {
+ buffer = w.get_buffer_rect();
+ } catch (_error) {
+ // Older Shell releases may not expose the buffer rectangle.
+ }
+ const minimized = Boolean(w.minimized);
+ out.push({
+ id: w.get_stable_sequence(),
+ pid: w.get_pid(),
+ title: w.get_title() ?? '',
+ x: r.x,
+ y: r.y,
+ w: r.width,
+ h: r.height,
+ buffer_x: buffer.x,
+ buffer_y: buffer.y,
+ focused: focusedWindow === w,
+ minimized,
+ visible: Boolean(actor?.visible) && !minimized,
+ stacking,
+ });
}
- _positionBadge(x, y, duration) {
- if (!this._badge || !this._badgeLabel ||
- this._badgeLabel.get_text().length === 0)
- return;
- const [, naturalWidth] = this._badge.get_preferred_width(-1);
- const badgeX = Math.round(x - naturalWidth / 2);
- const badgeY = Math.round(y + BADGE_Y_OFFSET);
- if (duration > 0) {
- this._badge.ease({
- x: badgeX,
- y: badgeY,
- duration,
- mode: Clutter.AnimationMode.EASE_OUT_CUBIC,
- });
- } else {
- this._badge.set_position(badgeX, badgeY);
- }
+ return JSON.stringify(out);
+ }
+ async CaptureAsync(_params, invocation) {
+ try {
+ const shooter = new Shell.Screenshot();
+ const stream = Gio.MemoryOutputStream.new_resizable();
+ const [width, height] = global.display.get_size();
+ if (width <= 0 || height <= 0) throw new Error(`Invalid display size ${width}x${height}`);
+ // GNOME 50's stage-content capture copies the real cursor sprite
+ // after painting the stage. Remote/headless pointer seats can
+ // expose a 0x0 sprite, and that copy can crash Shell. The stream
+ // API has an explicit include_cursor flag, so keep cursor capture
+ // disabled; cua-driver draws its own agent cursor.
+ await shooter.screenshot(false, stream);
+ stream.close(null);
+ const encoded = GLib.base64_encode(stream.steal_as_bytes().get_data());
+ invocation.return_value(new GLib.Variant('(s)', [encoded]));
+ } catch (error) {
+ invocation.return_dbus_error('org.cua.WinRects.CaptureFailed', String(error));
+ }
+ }
+ ActivateAsync([id], invocation) {
+ const target = global
+ .get_window_actors()
+ .map((actor) => actor.meta_window)
+ .find((window) => window?.get_stable_sequence() === id);
+ if (!target) {
+ invocation.return_value(new GLib.Variant('(b)', [false]));
+ return;
+ }
+ target.activate(global.get_current_time());
+ GLib.timeout_add(GLib.PRIORITY_DEFAULT, 100, () => {
+ invocation.return_value(new GLib.Variant('(b)', [global.display.focus_window === target]));
+ return GLib.SOURCE_REMOVE;
+ });
+ }
+ MoveCursor(x, y) {
+ if (!this._cursor) return;
+ const revealBadge = !this._cursor.visible;
+ this._cursorX = x;
+ this._cursorY = y;
+ this._cursor.show();
+ this._cursor.ease({
+ x: x - ACTOR_CENTER,
+ y: y - ACTOR_CENTER,
+ duration: 480,
+ mode: Clutter.AnimationMode.EASE_OUT_CUBIC,
+ });
+ this._positionBadge(x, y, 480);
+ if (revealBadge) this._revealBadge();
+ }
+ 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);
+ if (['idle', 'navigate', 'click'].includes(this._action))
+ this._setCursorState('click', this._delivery, this._target);
+ this._cursor.show();
+ this._cursor.queue_repaint();
+ if (revealBadge) this._revealBadge();
+ }
+ SetCursorColor(fillColor) {
+ const match = /^#([0-9a-fA-F]{6})$/.exec(fillColor);
+ if (!match) return;
+ const rgb = Number.parseInt(match[1], 16);
+ this._fillColor = [(rgb >> 16) & 0xff, (rgb >> 8) & 0xff, rgb & 0xff];
+ this._fillColorCss = `#${match[1].toLowerCase()}`;
+ if (this._badgeDot)
+ this._badgeDot.set_style(
+ `background-color: ${this._fillColorCss}; border: 1px solid white; border-radius: 99px;`
+ );
+ if (this._badge) this._badge.set_style(badgeStyle(this._fillColor));
+ this._deliveryChip?.queue_repaint();
+ this._targetChip?.queue_repaint();
+ if (this._glowSurface) this._glowSurface.finish();
+ this._glowSurface = createGlowSurface(this._fillColor);
+ if (this._cursor) this._cursor.queue_repaint();
+ }
+ SetCursorState(action, delivery, target, active) {
+ if (!ACTIONS.has(action)) return;
+ if (active) {
+ this._setCursorState(action, delivery, target);
+ } else if (this._action === action && !ONE_SHOT_ACTIONS.has(action)) {
+ this._endingAt = nowSeconds() + 0.4;
+ }
+ }
+ SetSessionLabel(label) {
+ if (!this._badgeLabel || !this._badge) return;
+ this._badgeLabel.set_text(label);
+ if (label.length === 0 || !this._cursor?.visible) {
+ this._badgeLabel.hide();
+ this._badgeRevealedAt = null;
+ if (!this._delivery && !this._target) this._badge.hide();
+ return;
+ }
+ if (this._cursorX !== null && this._cursorY !== null) {
+ this._positionBadge(this._cursorX, this._cursorY, 0);
+ this._revealBadge();
+ }
+ }
+ _positionBadge(x, y, duration) {
+ if (!this._badge) return;
+ const [, naturalWidth] = this._badge.get_preferred_width(-1);
+ const badgeX = Math.round(x - naturalWidth / 2);
+ const badgeY = Math.round(y + BADGE_Y_OFFSET);
+ if (duration > 0) {
+ this._badge.ease({
+ x: badgeX,
+ y: badgeY,
+ duration,
+ mode: Clutter.AnimationMode.EASE_OUT_CUBIC,
+ });
+ } else {
+ this._badge.set_position(badgeX, badgeY);
}
- _revealBadge() {
- if (!this._badge || !this._badgeLabel ||
- this._badgeLabel.get_text().length === 0)
- return;
- this._badgeRevealedAt = nowSeconds();
- this._badge.opacity = 255;
- this._badge.show();
+ }
+ _revealBadge() {
+ if (!this._badge || !this._badgeLabel || this._badgeLabel.get_text().length === 0) return;
+ this._badgeLabel.show();
+ if (this._cursorX !== null && this._cursorY !== null)
+ this._positionBadge(this._cursorX, this._cursorY, 0);
+ this._badgeRevealedAt = nowSeconds();
+ this._badge.opacity = 255;
+ this._badge.show();
+ }
+ _setCursorState(action, delivery, target) {
+ this._action = ACTIONS.has(action) ? action : 'idle';
+ const nextDelivery = delivery ?? '';
+ const nextTarget = target ?? '';
+ if (nextDelivery || nextTarget) {
+ this._delivery = nextDelivery;
+ this._target = nextTarget;
+ this._modifierFadeAt = null;
+ } else if ((this._delivery || this._target) && this._modifierFadeAt === null) {
+ this._modifierFadeAt = nowSeconds();
}
- _setCursorState(action, delivery, target) {
- this._action = ACTIONS.has(action) ? action : 'idle';
- this._delivery = delivery ?? '';
- this._target = target ?? '';
- this._actionStarted = nowSeconds();
- this._endingAt = null;
- if (this._cursor)
- this._cursor.queue_repaint();
+ this._updateModifierChips();
+ this._actionStarted = nowSeconds();
+ this._endingAt = null;
+ if (this._cursor) this._cursor.queue_repaint();
+ if (this._cursorX !== null && this._cursorY !== null)
+ this._positionBadge(this._cursorX, this._cursorY, 0);
+ }
+ _updateModifierChips() {
+ if (this._deliveryChip) {
+ this._deliveryChip.visible = this._delivery.length > 0;
+ this._deliveryChip.queue_repaint();
}
- HideCursor() {
- if (this._cursor) this._cursor.hide();
- if (this._badge) this._badge.hide();
- this._badgeRevealedAt = null;
+ if (this._targetChip) {
+ this._targetChip.visible = this._target.length > 0;
+ this._targetChip.queue_repaint();
}
+ }
+ HideCursor() {
+ if (this._cursor) this._cursor.hide();
+ if (this._badge) this._badge.hide();
+ this._badgeRevealedAt = null;
+ this._modifierFadeAt = null;
+ this._delivery = '';
+ this._target = '';
+ this._updateModifierChips();
+ }
}
diff --git a/libs/cua-driver/wayland-helper/winrects@cua/metadata.json b/libs/cua-driver/wayland-helper/winrects@cua/metadata.json
index 434b8a5eae..3faf86b779 100644
--- a/libs/cua-driver/wayland-helper/winrects@cua/metadata.json
+++ b/libs/cua-driver/wayland-helper/winrects@cua/metadata.json
@@ -1 +1,7 @@
-{"uuid":"winrects@cua","name":"WinRects","description":"Expose window geometry, capture, cursor, and verified activation for cua-driver on Wayland.","shell-version":["45","46","47","48","49","50"],"version":7}
+{
+ "uuid": "winrects@cua",
+ "name": "WinRects",
+ "description": "Expose window geometry, capture, cursor, and verified activation for cua-driver on Wayland.",
+ "shell-version": ["45", "46", "47", "48", "49", "50"],
+ "version": 8
+}