Platform Support
Current operating-system and window-system support, proven surfaces, and known capability boundaries.
cua-driver supports Windows, macOS, and Linux. Support is defined by observed behavior in a real application, not by whether a tool call returned success. The exact delivery route depends on the operating system, window system, application toolkit, action, and whether the target may be brought forward.
For definitions of AX, PX, foreground, background, window scope, and desktop scope, see Capture and delivery modalities.
Support levels#
| Level | Meaning |
|---|---|
| Supported | A canonical Rust harness test proves the result against application-owned or desktop-owned state. |
| Supported with limits | Common paths are proven, but the platform or window system cannot safely provide every delivery shape. Unsupported paths return a structured refusal. |
| Experimental | The backend exists, but representative coverage is incomplete. Do not assume unlisted actions work. |
Platform overview#
| Platform | Window system and automation APIs | Current state |
|---|---|---|
| Windows | Win32, UI Automation (UIA), native input, and targeted window messages | Supported. Canonical coverage includes Electron, Tauri, WPF, WinUI 3, and WebView2. Some background Chromium gestures and elevated-integrity boundaries remain unavailable or unproven. |
| macOS | AppKit, Accessibility (AX), Quartz/HID, and ScreenCaptureKit | Supported. Canonical coverage includes Electron, Tauri, AppKit, SwiftUI, and WKWebView. Accessibility and screen-recording permissions are required. Some background scroll and drag shapes return structured refusals. |
| Linux X11 | X11/EWMH, XTest, AT-SPI, and toolkit accessibility bridges | Supported with toolkit-specific limits. Foreground input and semantic background actions are broadly covered. Toolkits that reject synthetic background events receive an explicit refusal instead of a silent success. |
| Linux Wayland | AT-SPI plus compositor-specific discovery, capture, activation, and portal input | Supported with compositor-specific limits. Semantic background actions work where the application exposes them. Raw input cannot generally be sent to an arbitrary occluded surface. |
Wayland portal grants belong to the compositor/runtime scope that issued them. A direct runtime or private worker reports its resolved display and portal scope, and a replacement runtime may prompt again. Do not treat a successful portal grant as a durable credential that migrates to a later process generation.
Browser-tool routes#
Browser mutation always starts from an exact native (pid, window_id) binding.
The table records the strongest browser route currently proven by the Rust
harnesses; an unlisted trust class or host shape is not implied.
| Surface | Proven page routes | Explicit limit |
|---|---|---|
| Standalone Chrome and Edge on Windows | Snapshot, navigation, ref-bound typing, trusted background click, explicit DOM click and pointer actions, JavaScript dialogs, file assignment, approved downloads, frames, multi-tab, and exact ambiguity refusal | Elevated-integrity and unsupported native-host relationships still refuse |
| Standalone Chrome on macOS | Snapshot, navigation, ref-bound typing, explicit DOM click and pointer actions, JavaScript dialogs, file assignment, approved downloads, frames, multi-tab, and exact ambiguity refusal | Trusted CDP pointer input returns browser_input_trust_unavailable before dispatch |
| Standalone Chrome and Edge on Linux X11 | Snapshot, navigation, ref-bound typing, explicit DOM click and pointer actions, foreground JavaScript-dialog resolution, file assignment, approved downloads, frames, multi-tab, and exact ambiguity refusal | Trusted CDP pointer input and background JavaScript-dialog resolution return browser_input_trust_unavailable before dispatch |
| Electron on Windows, macOS, X11, and validated Sway | Typed mutation while one proven native window maps to one CDP page | A second page or native window invalidates the bounded exact route |
| Tauri, WKWebView, WebKitGTK, and common split-process WebView2 | Browser identity plus a side-effect-free structured refusal | No exact native-host-to-engine relationship is currently proven |
| Safari and Firefox | Native discovery and native AX/PX fallbacks | No typed browser mutation engine is currently advertised |
browser_prepare may launch a separate driver-owned Chromium profile after an
approved destructive call. isolated_new processes and their complete child
trees are reaped and the marked profile is removed when the owning session
ends.
Existing-profile attachment is proven for Chrome and Edge on macOS and Windows, for Chrome on Linux X11, and for Chrome in the native Sway lane. The same exact descriptor route covers Chromium and Edge on Linux, subject to a complete AT-SPI renderer tree and product-specific acceptance evidence. The harness proves exact interactive approval, setup-control identity, browser-owned consent, PID-owned loopback endpoint discovery, temporary-tab cleanup, focus restoration, and an exact native/CDP rebind without restarting, copying, or editing the profile. Unsupported products and unproven Wayland compositors return a structured refusal.
Linux window systems#
Linux support is recorded per window system and Wayland compositor. "Wayland" is not one uniform automation API: compositors expose different discovery, capture, activation, and input protocols.
| Environment | State | What is proven | Main limits |
|---|---|---|---|
| X11/Xorg | Supported | Window discovery and capture, AT-SPI trees and actions, foreground pointer and keyboard input, semantic background delivery, desktop scope, and structured refusals | Raw background delivery depends on the target toolkit. X11 accepting an event does not prove the application handled it. |
| Sway (wlroots reference lane) | Supported with limits | The complete typed Electron, Tauri, GTK, capture, and desktop-scope catalog, including foreground/background and AX/PX outcomes | Focus-bound and raw background input shapes without a target-addressed protocol return structured refusals. Other wlroots compositors are expected to share protocol support but are not yet proven. |
| GNOME/Mutter | Supported with limits | AT-SPI actions, GTK controls, compositor-backed window geometry and capture, verified foreground activation, and portal/libei foreground input | The bundled WinRects Shell helper and one Shell-session restart are prerequisites for authoritative geometry and activation. Portal video recording remains incomplete. |
| KDE/KWin | Experimental | Plasma 6 session startup, GTK AT-SPI discovery, generic discovery where exposed, and portal interface availability | cua-driver does not yet have a target-addressable KWin activation adapter, and no complete behavioral matrix is accepted. Focus-bound input refuses rather than risking delivery to the wrong application. |
cua-compositor nested session | Experimental | Native GTK behavior, capture and scope, private route metadata, independent observation, and per-cell video | The complete shared renderer matrix is not accepted. Unicode text and a canonical parallel-drag row remain unproven; this route does not establish a stock-Wayland capability. |
| XWayland | Supported with limits | X11 routes are used when the application exposes a real X11 window; native Wayland and AT-SPI fallbacks cover mixed sessions | Capabilities depend on whether the application is actually using X11 or native Wayland. |
Wayland background AX and PX#
Background AX works when the target exposes a semantic AT-SPI action. For example, the driver can invoke an accessible button without raising its window. The passing test must also prove that focus and z-order did not change and that input did not leak into the foreground application.
Background PX is proven only for the action/surface cells declared by the catalog. A caller may address a target by pixel while the safe delivery route hit-tests that point and invokes a semantic AT-SPI action. Renderer and gesture cells without a safe target-addressed route return an exact refusal. Neither outcome establishes arbitrary raw background injection.
Arbitrary raw background PX is not available to an ordinary client on a standard Wayland compositor. Reconstructing a window's coordinate system tells cua-driver where the target is, but portal/libei and virtual input still deliver through the compositor's active seat. An occluding surface therefore receives a raw event sent at that screen coordinate.
cua-driver also contains an opt-in exception: the nested cua-compositor
backend owns the compositor and can route wl_pointer and wl_keyboard events
directly to a selected client surface through CUA_INJECT_SOCKET, without
changing seat focus. This implements focus-free raw click, text, named-key, and
multi-pointer drag paths. The backend is covered by the converged typed matrix,
but remains experimental until the shared renderer matrix also passes. Unicode
text, multi-pointer behavior, canvas/game input, and any row without external
fixture evidence remain unproven.
A structured background_unavailable or background_occluded result is part of the contract. It
means cua-driver refused an unsafe or unsupported route before it could disturb the user's active
desktop. It is not a silent success.
Related documentation#
- How Cua Driver is validated explains why unit tests and application-owned E2E evidence have different roles.
- Platform roadmap records the remaining engineering work, evidence gaps, and platform boundaries.
- Known limits lists target-specific constraints and available alternatives.
- Development provides contributor entry points and canonical validation commands.