Rebase the Cua Hyprland plugin on Driver 0.32.0 for Hyprland 0.56.2-4 (#772)

* Rebase the Cua Hyprland plugin on Driver 0.32.0 source

Driver 0.31.0 took the independent agent keymaps and Num Lock handling from #473 upstream, so independent-keymaps.patch goes. Upstream also added an up-front check that every key the KEY command can press types the US keysym, modifier keys included, which refuses all foreground typing under ctrl:swapcaps, compose:ralt, altwin:swap_alt_win or compose:102. foreground-remaps.patch makes that check run the per-chord check every key already passes over exactly the chords Driver types text with, with Num Lock off and on, so a string is still admitted or refused before its first key and other remaps are left to the per-chord check.

0.32.0 also gives agent keyboards a real repeat rate, which stops single-seat clients like imv crashing on an agent seat (trycua/cua#4257).

cua-driver-bin stays at 0.28.2, which speaks the same input protocol v3: Driver 0.28.3 through 0.32.0 refuse desktop capture on Hyprland with more than one output or with one away from the origin (trycua/cua#4161).

Co-Authored-By: Codex XHigh <noreply@openai.com>

* Keep restarting fcitx5 from crashing Hyprland under the Cua plugin

With plugin input enabled, fcitx5 requests an input method for each of the three seats, and when it exits Hyprland 0.56.2 can still hold an input-method popup that is mapped although its wl_surface is gone: the popup's surface-destroy handler emits unmap but never clears m_mapped. Tearing down the input method then updates every popup, CInputPopup::updateBox dereferences the missing surface and Hyprland restarts in safe mode. Omarchy's omarchy-restart-xcompose reaches this in normal use.

The plugin now hooks CInputPopup::updateBox and CInputPopup::shouldBeRendered so a popup whose getSurface() is empty is neither placed nor rendered, reports the guard in cua:status, and removes the hooks on unload. The guard is compiled into the module only, so the mock-based tests are unchanged. foreground-remaps.patch becomes downstream.patch now that it carries both changes.

* Pin the Cua Hyprland plugin to Arch's hyprland 0.56.2-4 rebuild

Arch rebuilt Hyprland 0.56.2 against vulkan-sdk 1.4.363 and glslang. The executable and two headers change, so the plugin's exact compositor pin and hashes would block hyprland upgrades for anyone with it installed, and Cua's kit has no profile for it (trycua/cua#4216). The release, compiler and runtime are unchanged, so the derivation now also takes the re-measured compositor executable and header inventory; the build's verifier checks both against the installed package.

* Qualify the Cua plugin README on its input-method guard

The guard is installed best effort, so the README promises the fix only while it is active, and the activation checklist now asks for ime_popup_guard: true. 'No hooks' meant package-manager hooks, which the plugin's new function hooks made ambiguous.

Co-Authored-By: Codex XHigh <noreply@openai.com>

---------

Co-authored-by: Codex XHigh <noreply@openai.com>
This commit is contained in:
Spencer BullandCodex XHigh authored and GitHub committed 2026-10-03 22:37:44 -05:00
1 parent 03b472525f
commit a2c3571672
6 files changed
+403 -1206

No files matched your search

+20 -20
View File
@@ -1,29 +1,25 @@
# Optional Cua Hyprland plugin
This package targets **Omarchy x86_64**, with Inkscape `1.4.4-6` and two independent background-input lanes. Release `0.28.2-2` is an edge candidate built from the plugin source published with Driver `0.28.2`, the version `cua-driver-bin` ships, for glibc `2.44+r50+g1848099f063e-1`; it retains the keyboard-remap patch introduced in release `0.26.1-5`, which includes the Omarchy patch for independent agent keymaps, operation-specific foreground checks, and compatible Num Lock state; the upstream native qualification below covers the unpatched source, not this change. Cua's native qualification is recorded in [the kit's qualification record](https://github.com/trycua/cua/releases/download/cua-hyprland-kit-v1.1.0-omarchy-stable-20260910/QUALIFICATION.md) and [Cua #3698](https://github.com/trycua/cua/pull/3698). Omabot replay and Omarchy's merge decision are recorded in [omarchy-pkgs #346](https://github.com/omacom/omarchy-pkgs/pull/346). Scheduling the recipe does not expand the qualified stable target.
This package targets **Omarchy x86_64**, with Inkscape `1.4.4-6` and two independent background-input lanes. Release `0.32.0-3` is an edge candidate built from the plugin source published with Driver `0.32.0`, paired with `cua-driver-bin` `0.28.2`. That source carries the independent agent keymaps and compatible Num Lock handling that releases `0.26.1-5` through `0.28.2-2` applied as an Omarchy patch; this release applies a smaller one, `downstream.patch`, so foreground typing keeps working with modifier and Compose remaps (see *Keyboard behavior*) and so that, with its guard active, restarting fcitx5 does not crash Hyprland (see *Input-method popups*). The upstream native qualification below covers older, unpatched source. Cua's native qualification is recorded in [the kit's qualification record](https://github.com/trycua/cua/releases/download/cua-hyprland-kit-v1.1.0-omarchy-stable-20260910/QUALIFICATION.md) and [Cua #3698](https://github.com/trycua/cua/pull/3698). Omabot replay and Omarchy's merge decision are recorded in [omarchy-pkgs #346](https://github.com/omacom/omarchy-pkgs/pull/346). Scheduling the recipe does not expand the qualified stable target.
The plugin is optional. Cua Driver works independently, and installation does not load the plugin or enable input. The package follows the normal edge-to-RC-to-stable promotion path instead of the fast release ring. Its PKGBUILD limits builds to x86_64. The upstream qualification covers the original stable profile; the updated Aquamarine profile needs its own Omabot validation before promotion.
## Source and build profile
The package uses the [Driver 0.28.2 plugin source](https://github.com/trycua/cua/releases/tag/cua-driver-rs-v0.28.2), including the [desktop-fault cleanup repair](https://github.com/trycua/cua/pull/3702). Every plugin file in it is byte-identical to the Driver 0.26.1 and 0.27.0 sources; only the release identity in `SOURCE-PROVENANCE.json` differs. It is not a repackaging of the unmodified 0.24.0 plugin.
The package uses the [Driver 0.32.0 plugin source](https://github.com/trycua/cua/releases/tag/cua-driver-rs-v0.32.0). Against the Driver 0.26.1 source the profile kit was qualified with, it adds the keyboard behaviour below ([Cua #3970](https://github.com/trycua/cua/pull/3970), adapted from [#473](https://github.com/omacom/omarchy-pkgs/pull/473)) and gives agent keyboards the user seat's key repeat rate instead of zero ([Cua #4358](https://github.com/trycua/cua/pull/4358)), which crashed single-seat clients such as imv that bound an agent seat ([Cua #4257](https://github.com/trycua/cua/issues/4257)). The input protocol header is unchanged.
The qualified upstream Driver pairing is `cua-driver-bin 0.27.0-1`, with input protocol v3. Driver 0.27.0 contains the bounded stale-geometry retry validated with the upstream module. This package pairs with `cua-driver-bin 0.28.2`, which speaks the same input protocol v3 to the same plugin source; Driver finds the plugin only through its versioned input socket, not through the plugin's provenance. Discovery protocol v2 is separate. The 0.28.2 pairing is a changed pairing and requires affected replay before promotion.
The qualified upstream Driver pairing is `cua-driver-bin 0.27.0-1`, with input protocol v3. Driver 0.27.0 contains the bounded stale-geometry retry validated with the upstream module. This package pairs with `cua-driver-bin 0.28.2`, which speaks the same input protocol v3 to this source; Driver finds the plugin only through its versioned input socket, not through the plugin's provenance. Discovery protocol v2 is separate. `cua-driver-bin` stays at 0.28.2 because Driver 0.28.3 through 0.32.0 refuse desktop capture on Hyprland with more than one output or with one output away from the origin ([Cua #4161](https://github.com/trycua/cua/issues/4161)), where 0.28.2 captures. This pairing is a changed pairing and requires affected replay before promotion.
Profile `omarchy-edge-20260928-remaps`, kit tooling `1.1.0`, and package release `2` pin:
Profile `omarchy-hyprland-0562r4-remaps`, kit tooling `1.1.0`, and package release `3` pin:
- Hyprland `0.56.2-3`, headers `0.56.2`, and measured executable/header hashes.
- Hyprland `0.56.2-4`, headers `0.56.2`, and measured executable/header hashes.
- GCC `16.2.1 20260810`, including compiler bytes and emitted ELF identity.
- Shared runtime `libstdc++.so.6.0.36`, its bytes, and exact ABI package versions, including Aquamarine `0.15.1-1` and glibc `2.44+r50+g1848099f063e-1`.
This profile derives from Cua's `omarchy-stable-20260910` profile. Arch's
Hyprland `-3` package splits out `hyprpm` and changes package dependencies;
its compositor executable and all 498 header/pkg-config files are byte-identical
to `-2`. Both executables have SHA-256
`da8fcacf347bcbed83edc40108c6e2298da095e22246bd764e9bb382786cebb2`.
The checked-in `PROFILE.json` changes only the profile name, package release, source release, and exact Hyprland, Aquamarine and glibc package versions. Compiler, libstdc++ runtime, compositor executable, and header identities remain unchanged; the separately recorded patch changes the build source. The download wrapper verifies the original kit and the Driver 0.28.2 source archive before substituting that archive and its manifest into the kit, deriving the updated profile and provenance, and rendering the recipe from the kit's own `PROFILE-PKGBUILD.in`. It then verifies every derived member against its recorded digest, so the result is the kit Cua's `profile_verify.py` accepts as complete for this profile.
This profile derives from Cua's `omarchy-stable-20260910` profile. Arch's Hyprland `0.56.2-4` is a rebuild of the same 0.56.2 release against vulkan-sdk 1.4.363 and glslang, built with the same GCC `16.2.1 20260810` and linked to the same `libstdc++`. Its executable (SHA-256 `55da553be71222566ee73b973d2f56dbb9939044d8f22f81aa54b66c83f2f6d1`) and two of its 497 headers differ from `-3`: `src/version.h` now names the Aquamarine `0.15.1` and hyprutils `0.14.2` it was built against, and `protocols/hyprland-input-capture-v1.hpp` gains a destroy handler. The header inventory is re-measured the way `profile_verify.py` measures it, giving `1fdefe6ac027a159d04a5dfee4928ec7ebd15544a9a25b5f66d2f5a46fcf364a`; that method reproduces the kit's `-2`/`-3` values exactly.
The checked-in `PROFILE.json` changes only the profile name, package release, source release, exact Hyprland, Aquamarine and glibc package versions, and the re-measured compositor executable and header hashes. Compiler and libstdc++ runtime identities remain Cua's; the separately recorded patch changes the build source. Cua publishes the profile tooling only in the 0.26.1 kit, and the Driver 0.32.0 source manifest has exactly the fields that kit's `profile_verify.py` checks. The download wrapper verifies the original kit and the Driver 0.32.0 source archive before substituting that archive and its manifest into the kit, deriving the updated profile and provenance, and rendering the recipe from the kit's own `PROFILE-PKGBUILD.in`. It then verifies every derived member against its recorded digest, so the result is the kit Cua's `profile_verify.py` accepts as complete for this profile.
The native qualification below was recorded with package `0.26.1-2` and Hyprland `-2`. The downstream keymap change, the Aquamarine and glibc updates, and the Driver 0.28.2 pairing need their own application and Driver replay before promotion. Hyprland `0.56.2-3`, Aquamarine `0.15.1-1` and glibc `2.44+r50+g1848099f063e-1` must all reach a destination channel before this artifact can be installed there; publication still follows edge → RC → stable.
The native qualification below was recorded with package `0.26.1-2` and Hyprland `-2`. The 0.32.0 source and its Omarchy patch, the Aquamarine and glibc updates, and the Driver 0.28.2 pairing need their own application and Driver replay before promotion. Hyprland `0.56.2-4`, Aquamarine `0.15.1-1` and glibc `2.44+r50+g1848099f063e-1` must all reach a destination channel before this artifact can be installed there; publication still follows edge → RC → stable.
The generated `PKGBUILD` identifies the immutable kit download, outer checksum,
and member checksums. The kit records the full source and tooling revisions,
@@ -38,24 +34,28 @@ and production flags remain mandatory. Packaging runs all bundled CTests even
with `--nocheck` or `--repackage`; `--skipinteg` does not bypass recipe checks.
Production input is built in; experimental signed input and tracing are off.
The pristine upstream archive, manifest, and verifier remain unchanged. `independent-keymaps.patch` is applied to a separate source tree, and `DOWNSTREAM-PROVENANCE.json` pins the patch and every resulting source file. Build, check, and package revalidate both trees, including when makepkg integrity checks are skipped. `BUILD-PROVENANCE.json` records the upstream base under `source`, the applied change under `downstream`, and the final module digest; the downstream manifest and patch are installed beside it. This preserves the existing compiler, headers, runtime, and consumer checks without representing the modified module as an unmodified upstream build.
The pristine upstream archive, manifest, and verifier remain unchanged. `downstream.patch` is applied to a separate source tree, and `DOWNSTREAM-PROVENANCE.json` pins the patch and every resulting source file. Build, check, and package revalidate both trees, including when makepkg integrity checks are skipped. `BUILD-PROVENANCE.json` records the upstream base under `source`, the applied change under `downstream`, and the final module digest; the downstream manifest and patch are installed beside it. This preserves the existing compiler, headers, runtime, and consumer checks without representing the modified module as an unmodified upstream build.
## Dependency refresh
Every ABI package is pinned exactly, so an Arch update to any of them makes the published plugin uninstallable until a new profile lands. Release `0.26.1-5` required Aquamarine `0.15.0-2` and stopped resolving when the mirror moved to `0.15.1-1`; release `0.26.1-6` required glibc `2.44+r24+g16be1518495f-1` and stopped resolving when core moved to `2.44+r50+g1848099f063e-1`. In both cases pacman refuses the plugin with `unable to satisfy dependency`, even after a full database refresh. Release `0.28.2-2` derives a new profile from the same verified upstream kit and pins the current versions in both the package dependencies and the installed compatibility verifier. Patch, compiler, compositor, headers, and libstdc++ hashes remain pinned; the original upstream qualification does not establish compatibility with the changed Aquamarine or glibc packages.
Every ABI package is pinned exactly, so an Arch update to any of them makes the published plugin uninstallable until a new profile lands. Release `0.26.1-5` required Aquamarine `0.15.0-2` and stopped resolving when the mirror moved to `0.15.1-1`; release `0.26.1-6` required glibc `2.44+r24+g16be1518495f-1` and stopped resolving when core moved to `2.44+r50+g1848099f063e-1`. In both cases pacman refuses the plugin with `unable to satisfy dependency`, even after a full database refresh. Releases since `0.28.2-2` derive their profile from the same verified upstream kit and pin the current versions in both the package dependencies and the installed compatibility verifier. Compiler, compositor, headers, and libstdc++ hashes remain pinned; the original upstream qualification does not establish compatibility with the changed Aquamarine or glibc packages. An Arch rebuild of the same Hyprland release, with the same header version, compiler and runtime, is re-measured here: the derivation pins the new compositor executable and header inventory, and the build's verifier checks both against the installed package. A new Hyprland release, compiler, or `libstdc++` still needs a new kit from Cua.
A package release bump alone cannot repair future dependency drift: the checked-in profile and derived kit checksums must agree with the new environment, and affected native checks must pass before publication. Do not remove exact dependencies or selectively downgrade a library to bypass a mismatch.
## Keyboard behavior
Each background lane owns a canonical US keymap and independent modifier state. The physical keyboard keeps its layout, Compose key, and remaps. No installation or activation step edits `input:kb_*`. Existing Driver keycodes are interpreted by the agent keyboard, so this does not add Unicode, IME, or new Driver text routes.
Driver 0.31.0 and later implement this upstream. Each background lane owns a canonical US keymap and independent modifier state. The physical keyboard keeps its layout, Compose key, and remaps. No installation or activation step edits `input:kb_*`. Existing Driver keycodes are interpreted by the agent keyboard, so this does not add Unicode, IME, or new Driver text routes.
Plain click, scroll, drag, and foreground activation do not require a canonical keyboard layout. Foreground keys still use the primary seat: the plugin checks the requested key and modifier sequence against its actual XKB map before activation or input. Unrelated remaps are accepted; a sequence whose symbols or modifier/lock transitions differ from the canonical meaning is refused with `unsupported_layout`. Arbitrary foreground layout translation remains outside protocol v3.
Plain click, scroll, drag, and foreground activation do not require a canonical keyboard layout. Foreground keys still use the primary seat, so foreground typing needs a physical keymap under which every chord Driver types text with (the US main-block digits, letters and punctuation with and without Shift, plus Space, Tab and Return) means what it means on the canonical US map, with Num Lock off and on. A different layout, or a remap of one of those keys or of Shift, is refused with `unsupported_layout` before a string starts. Upstream also requires every other key the KEY command can press to match, which refuses all foreground typing under remaps like `ctrl:swapcaps`, `compose:ralt`, `altwin:swap_alt_win`, or `compose:102`; `downstream.patch` limits the up-front check to the text chords and leaves other keys to the per-chord check, which simulates each requested key and modifier sequence against the actual XKB map before activation or input. Under `ctrl:swapcaps`, plain text types and Ctrl+A is refused. Arbitrary foreground layout translation remains outside protocol v3.
Foreground typing preserves Num Lock and admits a requested key sequence only when its symbols and shortcut semantics still match the canonical meaning. Num Lock does not block unaffected letters, top-row digits, Enter, or compatible shortcuts; a keypad sequence whose meaning changes is refused. Caps Lock, other unsupported lock states, held or latched modifiers, and nonzero layout groups remain guarded.
Foreground typing preserves Num Lock and admits a requested key sequence only when its symbols and shortcut semantics still match the canonical meaning. Num Lock does not block unaffected letters, top-row digits, Enter, or compatible shortcuts; a keypad sequence whose meaning changes is refused with `foreground_keyboard_numlock_keypad`. Caps Lock is refused with `foreground_keyboard_caps_lock`; other unsupported lock states, held or latched modifiers, and nonzero layout groups remain guarded.
Both routes retain target/conflict checks and cancellation on desktop/keymap changes. `hyprctl -j cua:status` exposes `keyboard_layout_independent: true` and `foreground_numlock_compatible: true` for installers to distinguish this implementation from an older mapped module. The marker does not identify every future package revision; plugin updates still require a fresh desktop session.
## Input-method popups
With input enabled, the agent seats are ordinary `wl_seat` globals, and fcitx5 requests an input method for every seat it sees: one is accepted and the others are refused. When fcitx5 then exits, which Omarchy's `omarchy-restart-xcompose` does, Hyprland 0.56.2 can be left with an input-method popup that is still mapped although its `wl_surface` is already gone, and it updates every popup as the input method goes away. `CInputPopup::updateBox` dereferences the missing surface and Hyprland crashes into safe mode. Hyprland never marks such a popup unmapped, and its renderer reaches the same missing surface through `CInputPopup::shouldBeRendered`. `downstream.patch` hooks `CInputPopup::updateBox` and `CInputPopup::shouldBeRendered` through Hyprland's function-hook API so that a popup whose `getSurface()` is empty is neither placed nor rendered. The hooks are installed when the module loads and removed when it unloads, and `hyprctl -j cua:status` reports `ime_popup_guard: true` when both are active. If either exact symbol is not found, the plugin loads without the guard and reports `false`. The guard is in the module only; the bundled tests compile `plugin.cpp` against mocks without it.
## Historical upstream qualification
The initial app scope is native Wayland Inkscape `1.4.4-6` with the canonical
@@ -129,7 +129,7 @@ rollout and qualify any changed pairing explicitly.
The package installs the module at
`/usr/lib/cua/hyprland/cua-hyprland-plugin.so` and provenance plus the consumer
verifier under `/usr/share/cua-hyprland-plugin/`. There are no hooks, autoloading,
verifier under `/usr/share/cua-hyprland-plugin/`. There are no package-manager hooks, autoloading,
configuration edits, or hot replacement.
Save your work and exit Hyprland before installing, replacing, or removing the
@@ -140,7 +140,7 @@ kit-provenance digest:
```sh
python3 /usr/share/cua-hyprland-plugin/profile_verify.py \
--kit /usr/share/cua-hyprland-plugin \
--kit-sha256 593e0b59f4d50059e30d32d5f6ac1472862dd17a573229cfbfbda74779fb8f82 \
--kit-sha256 3c2141dcb2583d918ef2cdb6ff3805dec62119a439a29c811a93cc980d621423 \
--consumer /usr/lib/cua/hyprland/cua-hyprland-plugin.so
```
@@ -172,7 +172,7 @@ hyprctl reload
hyprctl -j cua:status
```
Continue only when status reports `keyboard_layout_independent: true`, `foreground_numlock_compatible: true`, input protocol v3, input capability, socket paths, and the expected compositor identity. Do not change `kb_layout`, `kb_options`, or NumLock for background input. If you previously followed the stock-US override instructions, remove only that Cua-specific override and reload to restore your underlying personal settings.
Continue only when status reports `keyboard_layout_independent: true`, `foreground_numlock_compatible: true`, `ime_popup_guard: true`, input protocol v3, input capability, socket paths, and the expected compositor identity. Do not change `kb_layout`, `kb_options`, or NumLock for background input. If you previously followed the stock-US override instructions, remove only that Cua-specific override and reload to restore your underlying personal settings.
Start Driver with `CUA_DRIVER_RS_ENABLE_WAYLAND=1`. In a new disposable Inkscape document, test an admitted background key operation and pointer operation, then verify the result in both a fresh snapshot and a saved/reopened SVG. Driver text-route restrictions still apply. Never test against an existing document or automatically replay an action with a partial or unknown outcome.