Skip to content

feat(drivers): run cua-driver on Omarchy's Hyprland, and probe Wayland computers with a GTK fixture - #547

Merged
earakely-scale merged 12 commits into
mainfrom
edgararakelyan/fd-5341-o4-cua-driver-on-omarchy-its-wayland
Nov 9, 2026
Merged

earakely-scale merged 12 commits into
mainfrom
edgararakelyan/fd-5341-o4-cua-driver-on-omarchy-its-wayland

Conversation

@earakely-scale

@earakely-scale earakely-scale commented Nov 9, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

cua-driver's driver can now run on a Hyprland desktop (Wayland), and the conformance probe can check a Wayland computer natively. This is the first piece of Omarchy computers. The driver doesn't yet declare an Omarchy desktop in supports: its env.toml has no install for one, so gate 1 would accept it there and the composer would run Ubuntu's install. That declaration comes with the Omarchy install (FD-5339). Nothing changes on X11, macOS or Windows.

  • cua-driver on Hyprland (drivers/envs/cua-driver/driver.py, with what it asks Hyprland's IPC in hyprland.py beside it; a driver's whole folder is installed and importable wherever it runs). Hyprland's session (HYPRLAND_INSTANCE_SIGNATURE) turns this path on, not any Wayland one, since it reaches Hyprland's IPC.
    • Its daemon waits for the compositor's socket rather than X's, and runs cua-driver with CUA_DRIVER_RS_ENABLE_WAYLAND=1, from a socket in the session's runtime folder.
    • Keys and text go to the window Hyprland has focused, with delivery_mode: foreground. Its Hyprland address is the cua-driver window id. Without delivery_mode: foreground, a desktop-scope key with modifiers falls back to libei, which Hyprland doesn't serve ("libei input backend did not become ready within 20s"). With nothing focused, keys go to the desktop. Clicks, drags and scrolls stay desktop-scope.
    • Known gaps in key delivery, to close after O2 pins cua-driver 0.44 on Omarchy (FD-5341): a key aimed at the window skips Hyprland's own shortcuts (Super+2 types "2" into the app); it's refused while a layer such as Omarchy's menu holds the keyboard (foreground_grab); and non-ASCII text is refused. Desktop scope with delivery_mode: foreground handles all three, but Backspace, the arrows and Home/End do nothing in a text box there, on 0.38 and 0.44 alike. So the fix is a hybrid: the window first, Super chords at the desktop, and the desktop again when cua-driver refuses for a grab or for Unicode.
    • No X keymap on Hyprland.
    • A new ready check: Hyprland has cua-driver's plugin loaded, enabled, built for this Hyprland and taking input (transport.ready). After a crash, Omarchy's watchdog restarts Hyprland in --safe-mode with no plugins, and cua-driver's input then never arrives. A plugin loaded again into a running Hyprland answers as configured but has no input seat until the desktop restarts.
    • The same check before every input. The runtime runs ready checks only until they first pass (ensure_ready). So each computer/v1 input operation, and each of cua-driver's own tools that isn't read-only, asks Hyprland first, and fails as device_unavailable, sending nothing, while the plugin is missing or not taking input. Screenshots and read-only tools still answer. When Hyprland doesn't answer at all, as once it restarts under a new instance signature after the driver started, the check says so and to restart the driver with it, rather than calling the plugin missing.
  • A Wayland fixture for the probe (conformance/wayland_fixture.py, checks.py):
    • When the card's platform.display is wayland, the probe stages the Fixture Desk drawn with GTK 3 as a native Wayland client, in place of the Tk desk. Tk runs only under XWayland, which cua-driver's plugin can't type into.
    • The two desks share conformance/desk.py: the layout, the widget sizes, what state.json starts as and how keys and drags are kept. It imports no toolkit, so the GTK desk starts on a computer without Tk, as stock Omarchy is. The probe stages desk.py beside either desk, so the Tk desk on X11, macOS and Windows now stages two files. The two recording integration tests that start the Tk desk themselves stage it too.
    • It goes full screen and takes its origin from Hyprland's IPC, since Wayland tells a client nothing of where its window is. It keeps the clipboard through wl-clipboard.
    • There the probe selects a text box's text with GTK's own Ctrl+A rather than Tk's Ctrl+/.
    • The wheel counts GTK 3's smooth scroll deltas, because GTK 3 on Wayland names a horizontal wheel's discrete direction the wrong way round. A uinput wheel's REL_HWHEEL -1 reaches GTK 3 as RIGHT, while its smooth delta, GTK 4 and cua-driver's own scroll all have it left.
  • Docs: the protocol README's probe section, and a paragraph on cua-driver on Hyprland in the drivers README.
  • The env-var guard (tst/unit/config/test_explain_and_sources.py) counts WAYLAND_DISPLAY and XDG_RUNTIME_DIR as a desktop session's, as it counts DISPLAY.

Testing

  • Unit tests:
    • cua-driver: keys to the focused window, keys to the desktop with nothing focused, the plugin's readiness states (a hand reload included), input refused and unsent once the plugin is gone, and the daemon's Hyprland start.
    • The probe: against a fake Wayland computer, and the GTK desk importing with no Tk.
    • ruff check . is clean. Locally the cua-driver, conformance and config tests pass (91, plus two cua-driver tests that already fail on macOS on main); CI runs the rest, the recording tests included.
  • On Omarchy 4.5.0's published VM image under KVM on EC2, with Omarchy's cua-hyprland-plugin 0.33.2-3, cua-driver 0.38.0 and this branch's driver and probe:
    • The full probe passes 45 of 47 on the stock image, with no Tk installed, and 1 is not applicable. The two failures are cua-driver refusing non-ASCII text on Hyprland ("Hyprland text requires at most 4096 ASCII bytes") and the key-events check that reads that text.
    • The plugin checks: with the plugin unloaded mid-session, computer_type and cua-driver's click were refused as device_unavailable and nothing reached the desk, while list_windows and screenshots answered. Loaded again by hand, input was still refused, with the plugin's reason. After a restart of the desktop, the probe passed again.
    • Keys, through computer_*: typing, select-all and Backspace reach the focused window, and a key on an empty workspace stays out of the window on another one. The gaps above were measured on 0.38 and 0.44, at both scopes.
    • The shared layout changed nothing: the old and new desks wrote the same layout.json and state.json, the Tk desk's under XWayland and the GTK desk's.
    • This run hid the idle cursor (cursor:inactive_timeout = 1), as the Omarchy base will. Otherwise captures draw it at the click point.
    • The safe-mode case: after killing Hyprland and restarting the driver's units, computer-ready answered "cua-driver plugin: Hyprland hasn't loaded cua-driver's plugin" and every tool refused. After a reboot, basic passed 23 of 23.
    • Agent runs, on the first commit (f6753c1) and not repeated since: Claude Sonnet 5.5, given only this driver's cua-driver tools, moved a file into a new folder through Nautilus, 2 of 2. The later commits change readiness, the plugin checks and the probe's fixture, not how input is sent.

FD-5341, FD-5340 (under FD-5336)

🤖 Generated with Claude Code

RetriggerView in GreptileConfidence Score: 5/5

The changes since the previous review appear safe to merge.

Summary

Adds Hyprland support to cua-driver and a native GTK desk for Wayland conformance checks. Since the previous review, only the unit-test fixture changed.

  • The cua-driver adapter sends input through Hyprland when it runs in a Hyprland session.
  • The conformance probe uses a native GTK desk on Wayland computers.

Reviews (13) · Last reviewed commit: "test(drivers): load cua-driver's driver ..." · Reviewed by Greptile

…d computers with a GTK fixture

cua-driver's driver supports a Wayland desktop, Omarchy's Hyprland. Its daemon waits for the compositor and runs
cua-driver's Wayland backend; keys and text go to the focused window in the foreground, since a desktop-scope key falls
back to libei, which Hyprland doesn't serve; there's no X keymap; and the driver is ready only while Hyprland has
cua-driver's plugin loaded, enabled and built for it, which a Hyprland restarted in safe mode doesn't.

The conformance probe draws its Fixture Desk with GTK 3 on a Wayland desktop, since Tk runs only under XWayland, which
a Wayland driver may not reach, and selects a text box's text there with Ctrl+A.

Nothing changes on X11, macOS or Windows. Omarchy's base computer and its install come later (FD-5338, FD-5339).

FD-5341, FD-5340

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@earakely-scale
earakely-scale requested a review from a team as a code owner November 9, 2026 00:19
…nd count the GTK fixture's wheel by its deltas

cua-driver no longer declares an Omarchy desktop: its env.toml has no install for one yet, so gate 1 would have taken it
there and the composer run Ubuntu's install. The Hyprland path stays, turned on by Hyprland's session
(HYPRLAND_INSTANCE_SIGNATURE) rather than any Wayland one, since it reaches Hyprland's IPC, and its socket is in the
session's runtime folder with no fallback path. AGENTS.md goes back to main's row until the driver declares it.

The Wayland fixture's wheel counts GTK 3's smooth scroll deltas: on Wayland GTK 3 names a horizontal wheel's discrete
direction the wrong way round. A uinput wheel's REL_HWHEEL -1 reaches GTK 3 as RIGHT, while its smooth delta, GTK 4 and
cua-driver's own scroll all have it left. On Omarchy 4.5.0 the full probe now passes 45 of 47; the two left are
cua-driver refusing non-ASCII text on Hyprland and the key-events check that reads it.

FD-5341, FD-5340

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@greptile-apps

This comment has been minimized.

earakely-scale and others added 10 commits November 8, 2026 16:59
… the GTK desk starts without Tk

The GTK desk imported its constants from fixture.py, which imports tkinter, so on a stock Omarchy,
which has no Tk, it never started and the probe's full checks were left unverified. desk.py holds the
desk's layout, its sizes, what state.json starts as and how keys and drags are kept, and imports no
toolkit; both desks read it and the probe stages it beside either, so the two can't drift apart.

Also: the probe picks the GTK desk by a flag rather than its file name, the daemon's socket is an
if/elif, the plugin readiness check names itself once per outcome, and the Hyprland unit tests share
one fixture.

On an Omarchy 4.5.0 VM without Tk the GTK desk starts; the old and new desks write the same
layout.json and state.json, Tk's under XWayland and GTK's; and the full probe passes 45 of 47, the two
failures the known non-ASCII text ones.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…lipboard

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…session's, not configuration

cua-driver's driver reads them on Hyprland, as it reads DISPLAY on X11.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…s gone, not only before the first ready check

The runtime runs ready checks only until they first pass, so a Hyprland restarted without the plugin,
as in safe mode after a crash, took input that never arrived. Each computer/v1 input operation, and
each of cua-driver's own tools that isn't read-only, now asks Hyprland first and fails as
device_unavailable, sending nothing, while the plugin is missing; screenshots and reads still answer.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…he probe never sends there

On the GTK desk the probe selects with Ctrl+A, since cua-driver on Hyprland can't press punctuation
keys; the README, the probe's comment and the test fake now say why.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…its transport takes input

A plugin loaded again into a running Hyprland answers cua:status as configured and built for that
Hyprland, but has no input seat until the desktop restarts ("input seat lifetime unavailable"), so
input sent through it never arrives. The readiness check and the per-call check now also require
transport.ready, and name the plugin's own reason when it isn't.

On an Omarchy 4.5.0 VM: with the plugin unloaded, computer_type and cua-driver's click are refused
as device_unavailable and nothing is sent, while list_windows and screenshots still answer; loaded
again by hand, input is still refused, with the plugin's reason; and after a restart of the desktop
the full probe passes 45 of 47, the two failures the known non-ASCII text ones.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…t that drivers can't press /

cua-driver 0.44 presses punctuation keys on Hyprland, so that was no reason to give.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…sing, when hyprctl can't reach it

The driver reads HYPRLAND_INSTANCE_SIGNATURE once, so after Hyprland restarts under a new one its
hyprctl calls reach nothing, and the plugin check refused all input as "Hyprland hasn't loaded
cua-driver's plugin". When cua:status gives no answer, the check now asks Hyprland for its active
workspace too, and when that gets none either it says Hyprland doesn't answer and to restart the
driver with it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…nd document the driver on Hyprland

What the driver asks Hyprland through hyprctl (the focused window, the plugin's readiness, the check
before each input) is now hyprland.py beside driver.py, which calls it only on Hyprland. A driver's
whole folder is installed and importable wherever it runs (_declare and load_class put the folder on
sys.path, and the daemon runs driver.py as a script), so the split needs no install change; both
loaders were checked against it.

The drivers README gains a paragraph for cua-driver on Hyprland: the Wayland backend and plugin, how
keys go, the plugin checks and why they run before every input, and the known gaps in key delivery.
The Hyprland unit tests share one fake of Hyprland's IPC.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…s on macOS and in a Hyprland session

driver.py picks its platform from sys.platform, and on Hyprland from HYPRLAND_INSTANCE_SIGNATURE, at
import. The tests are written for an X11 desktop on Linux, as CI runs them, so two of them failed on a
macOS checkout, main included, and every one would take the Hyprland path when run from a Hyprland
desktop. The module fixture now loads the driver with sys.platform "linux" and without that variable;
a test of another platform sets that platform's flags itself, as before.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@earakely-scale
earakely-scale merged commit 20578b6 into main Nov 9, 2026
36 checks passed
@earakely-scale
earakely-scale deleted the edgararakelyan/fd-5341-o4-cua-driver-on-omarchy-its-wayland branch November 9, 2026 04:39
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant