feat(kwin): the daemon registers with KGlobalAccel

A static shortcut can only be one combo, pressed, the same in every application.
Modes, chord chains, release bindings and per-application bindings need komorebi
to hold the keys and decide what each press does: the engine of
komorebi-hotkeys, a state machine with no I/O. This commit runs it against
KWin's global shortcut daemon, which KWin 6.8 runs inside itself on the session
bus.

kwin::hotkeys owns the component komorebi in kglobalaccel, with one action per
combo, named after the combo (Alt+H). An activation of the engine is
setShortcutKeys(id, [[combo]], 6), with a doRegister the first time; a
deactivation is setInactive, after which the key reaches the focused window
again. The calls of one event are sent without waiting for each other's answers,
which Phase 0 measured at 60 calls in 2.4 ms. globalShortcutPressed and
globalShortcutReleased of /component/komorebi feed the engine;
globalShortcutRepeated is ignored, so a held key runs its binding once. A
komorebic command runs the komorebic next to the daemon with its words when they
need no shell, anything else runs through sh -c. The calls are computed by
Registry, which is pure and tested; the D-Bus part is proved by the VM test.

The engine hears the presses at the path /component/komorebi and does not ask
kglobalaccel for the object with getComponent. kglobalaccel makes the object
when the component gets its first action, so a start with no key to grab (every
binding is for an application other than the one with the focus) has none to ask
for: getComponent fails with NoSuchComponent, and an engine that asked would
never start. A signal is matched by the path it comes from, so the presses are
heard as soon as there is an object. PLATFORM.md says so.

kglobalaccel keeps the actions and the grabs of a client that was killed, so a
start is an idempotent reconcile: the actions of the component that the keymap
names are taken over and released unless the default mode wants them, the others
are unregistered. A stop releases and unregisters everything, from
KWinBackend::shutdown, which SIGINT, SIGTERM and the Stop message all go
through.

The daemon takes --keybindings FILE, --keybindings-format skhd|whkd|sxhkd (by
default from the file's name) and --keybindings-mode (the mode komorebic hotkeys
compile wrote the static shortcuts in, so that the daemon leaves those to KDE);
without --keybindings it reads the first of skhdrc, whkdrc and sxhkdrc in the
config directory (HOME_DIR, KOMOREBI_CONFIG_HOME). It logs one line about the
file and the diagnostics at debug level. An engine that cannot start is logged
and the window manager runs without keys; the fake backend runs none.

The VM test vm-keys-engine starts the daemon in a Plasma session with an skhdrc
in the config directory, presses its keys (a command, one through a shell,
komorebic retile reaching the daemon), kills the daemon and sees its keys stay
registered, starts it with another file and sees the old keys unregistered and
the new ones work, and stops it with komorebic stop, after which no key is
registered and none runs. The library gains spawn_komorebi,
kill_spawned_komorebi and shortcut_actions, and Checks.finish names the checks
that failed, since nix build shows only the last lines of a failed run. The
suite's node turns the module's unit off: the test runs daemons of its own.
This commit is contained in:
LGUG2Z committed 2026-10-28 07:21:14 -07:00
1 parent e1a227434b
commit b49c4fab0a
16 files changed
+1109 -21

No files matched your search

+31
View File
@@ -1655,6 +1655,28 @@ read and left out (a warning) and how many bindings are not realized as their ow
the ones `kde::diff` says that plan would write. It reads no file the desktop has no part in, so
`--configuration-only` keeps it.
### The engine in the daemon
[`komorebi/src/kwin/hotkeys.rs`](../../komorebi/src/kwin/hotkeys.rs) runs the engine against
kglobalaccel, on a session bus connection and a thread of its own. The daemon reads the file
it is given with `--keybindings` (or the first it finds in the config directory), plans it in
`--keybindings-mode`, and hands the plan's engine keymap to `kwin::hotkeys::start`, unless the
plan needs no engine. A failure to start is logged, and the window manager runs without keys.
- **Calls**: each effect becomes calls on `/kglobalaccel` (`Registry`): an activation is
`setShortcutKeys(id, [[combo]], 6)`, preceded by `doRegister` the first time; a deactivation
is `setInactive`. The calls of one event are sent together, and only those for one action
wait for each other.
- **Signals**: `globalShortcutPressed` and `globalShortcutReleased` of `/component/komorebi`
are the engine's presses and releases. `globalShortcutRepeated` is not listened to.
- **Commands**: a `komorebic` command runs `komorebic` (the one next to the daemon) with its
words when it needs no shell, and anything else runs through `sh -c`, as processes the
daemon does not wait for.
- **Start**: the component's actions that the keymap names are taken over, and released
unless the default mode wants them; the others are unregistered.
- **Stop**: every key is released and every action unregistered, from
`KWinBackend::shutdown`, which every way the daemon stops goes through.
### What is guaranteed, and by what
| Rule | Enforced by | Proof | Escape hatch |
@@ -1682,6 +1704,11 @@ the ones `kde::diff` says that plan would write. It reads no file the desktop ha
| `komorebic check` says when the shortcut files are not the ones `hotkeys compile` would write | test | `shortcut_files_that_are_not_the_ones_of_the_plan_are_a_warning_that_says_how_many`, `shortcut_files_the_file_does_not_call_for_are_a_warning_until_compile_replaces_them` | none |
| `--strict` writes nothing when a diagnostic is a warning or an error | test, through the binary | `strict_refuses_a_file_with_a_warning_and_writes_nothing` | none |
| KWin runs a static shortcut's command on its key, from the system profile at the start of a session and from the user's directory after `--reload` | VM test | `vm-keys-static` | none |
| An effect becomes the calls that carry it out, and an action is registered once | test | `Registry` doctest, `a_start_with_nothing_left_behind_registers_and_grabs_the_default_mode` | none |
| A start takes over the keys a killed daemon left, releases those the default mode does not want, and unregisters the actions its keymap does not name | test, of the calls; VM test, against kglobalaccel | `a_start_takes_over_the_keys_of_a_killed_komorebi_and_drops_the_rest`, `vm-keys-engine` | none |
| A stop of the daemon unregisters every action | framework path: `KWinBackend::shutdown` calls `kwin::hotkeys::stop`, and both ways to stop call it; VM test | `vm-keys-engine` (`komorebic stop`) | `SIGKILL` leaves the keys until the next start |
| A press of a grabbed key runs its binding's command, `komorebic` without a shell where it needs none | test, of the process; VM test | `command` doctest, `a_press_runs_the_command_and_changes_no_key`, `vm-keys-engine` | none |
| Holding a key runs its binding once | convention only: the transport listens to `globalShortcutPressed` and not to `globalShortcutRepeated` | none (measured in PLATFORM.md) | none |
## Where to look in the code
@@ -1870,6 +1897,10 @@ the ones `kde::diff` says that plan would write. It reads no file the desktop ha
[`komorebic/tests/hotkeys.rs`](../../komorebic/tests/hotkeys.rs), what they write.
- [`nix/tests/vm/suites/keys-static`](../../nix/tests/vm/suites/keys-static/test.py): static
shortcuts run by a real KWin.
- [`komorebi/src/kwin/hotkeys.rs`](../../komorebi/src/kwin/hotkeys.rs): the engine against
kglobalaccel, and
[`nix/tests/vm/suites/keys-engine`](../../nix/tests/vm/suites/keys-engine/test.py), keys
pressed in a real KWin with the daemon running.
- [`komorebi-hotkeys/tests`](../../komorebi-hotkeys/tests): the corpus test and the comparison
with `whkd-parser`.
- [`nix/nixos-module.nix`](../../nix/nixos-module.nix): the NixOS module;
+45 -12
View File
@@ -196,20 +196,22 @@ an owner again; the VM test `vm-kwin-restart` restarts KWin twice under a runnin
#### What komorebi leaves behind
When it is stopped with `SIGINT`, `SIGTERM` or a `Stop` message on its socket, it brings back
the windows it hid, waits until the commands that do so have reached the bridge, removes the
parking desktop, unloads the effects it loaded, puts back the values the keys it set in `kwinrc`
had (`PerOutputVirtualDesktops`, the focus policy, and the keys of the effects), or removes a key
the user had not set, and asks KWin to reload its configuration, asks KWin to unload the script,
closes an empty connection to each subscriber, and removes the socket. The desktops it created for
workspaces stay: they are the user's desktops from then on. A `StopIgnoreRestore` message stops it
the same way, except that it does not bring the windows back: the parking desktop is removed all
the same. The file `bridge.js` stays in the runtime
the windows it hid, unregisters the keys of its engine, waits until the commands that do so have
reached the bridge, removes the parking desktop, unloads the effects it loaded, puts back the
values the keys it set in `kwinrc` had (`PerOutputVirtualDesktops`, the focus policy, and the keys
of the effects), or removes a key the user had not set, and asks KWin to reload its configuration,
asks KWin to unload the script, closes an empty connection to each subscriber, and removes the
socket. The desktops it created for workspaces stay: they are the user's desktops from then on. A
`StopIgnoreRestore` message stops it the same way, except that it does not bring the windows back:
the parking desktop is removed all the same. The file `bridge.js` stays in the runtime
directory, which is removed at logout. A daemon that is killed leaves the script running in
KWin, reporting to nobody, the socket file in the runtime directory, per-output desktops
on, and the parking desktop with the hidden windows on it, until the next start replaces the
script and the socket, sends the windows on the parking desktop to the first workspace's desktop
and removes the desktop, and its stop puts the setting back (the backup in the runtime
directory keeps the user's value), or the session ends.
directory keeps the user's value), or the session ends. It also leaves the keys of its engine
grabbed: they are swallowed, and run nothing, until the next start takes them over and unregisters
those its key bindings no longer have.
### A headless KWin
@@ -260,6 +262,9 @@ What komorebi calls:
| `org.kde.KWin` | `/KWin` | `org.kde.KWin` | `reconfigure()` | after komorebi changed `kwinrc`, at start and at exit |
| `org.kde.KWin` | `/VirtualDesktopManager` | `org.kde.KWin.VirtualDesktopManager` | the properties `desktops` and `count`, `createDesktop(us)`, `setDesktopName(ss)`, `removeDesktop(s)` | when a workspace has no desktop, and at start; `createDesktop` also for the parking desktop, the first time a window is hidden, and `removeDesktop` for it when komorebi stops and for one a killed run left |
| `org.kde.plasmashell` | `/PlasmaShell` | `org.kde.PlasmaShell` | `evaluateScript(s) -> s`, `wallpaper(u) -> a{sv}`, `setWallpaper(sa{sv}u)` | when a workspace with a wallpaper comes into view ([The Plasma shell](#the-plasma-shell)) |
| `org.kde.kglobalaccel` | `/kglobalaccel` | `org.kde.KGlobalAccel` | `allActionsForComponent(as) -> aas` | when the engine starts |
| `org.kde.kglobalaccel` | `/kglobalaccel` | `org.kde.KGlobalAccel` | `doRegister(as)`, `setShortcutKeys(as, a(ai), u) -> a(ai)`, `setInactive(as)`, `unRegister(as)` | when the engine grabs and lets go of keys, and when it starts and stops |
| `org.freedesktop.DBus` | `/org/freedesktop/DBus` | `org.freedesktop.DBus` | `AddMatch(s)`, for `globalShortcutPressed` and `globalShortcutReleased` of `/component/komorebi` | when the engine starts |
What komorebi listens to, for the machine sleeping and the screen being locked:
@@ -317,6 +322,34 @@ write such files. What follows was measured at time of writing (2026-10-27) on K
- The VM test `vm-keys-static` presses the keys of shortcut files in the system profile, and of
one written and handed over in the middle of the session.
The engine registers its keys itself, in the component `komorebi`, with one action per combo
named after the combo (`Alt+H`); an action's id is `["komorebi", "Alt+H", "komorebi",
"Alt+H"]`. What was measured of that interface at time of writing (2026-10-27), on KWin
6.8.1 in a virtual machine under HVF with 4 cores:
- `setShortcutKeys(as id, a(ai) keys, u flags) -> a(ai)` takes a list of key sequences, each
a struct of one Qt key code per key of the sequence, and returns the keys it set. Flags 6
(`SetPresent | NoAutoloading`) grab the key at once, whatever kglobalaccel saved for the
action. A key that another action has is not set: the answer is not what was asked for, and
komorebi logs a warning.
- A grabbed key does not reach the focused window, a bare key (`H`, `Escape`) included, and
each tap is a `globalShortcutPressed` and then a `globalShortcutReleased` signal
(`ssx`: component, action, timestamp) on `/component/komorebi`. The signal reached a client
2.5 ms after the key at the median (2.2 to 3.9 ms, 20 presses), also after another window
had taken the focus.
- A key held for 1.2 s sent one pressed signal, 15 `globalShortcutRepeated` and one released
signal, in that order.
- After `setInactive`, the key reaches the focused window and no signal is sent;
`setShortcutKeys` grabs it again. Sixty such calls, sent without waiting for the answers,
were all answered in 2.4 ms, and the state afterwards was right.
- A client that is killed leaves its actions and its grabs: the key stays swallowed and its
signal is sent to nobody until `unRegister`.
- A sequence of two keys (`[[Meta+A, B]]`) is accepted and stored, but never fires: the
second key reaches the focused window.
- `getComponent` fails until the component has an action, so the engine does not ask for the
object of its component: it listens at the object's path, `/component/komorebi`, which a
signal is matched by, and a start with no key to grab is a start all the same.
## Files and directories
| Path | What | Lifetime |
@@ -335,7 +368,7 @@ write such files. What follows was measured at time of writing (2026-10-27) on K
| `$XDG_DATA_HOME/komorebi/komorebi.log.YYYY-MM-DD` | the daemon's log, with colors, which `komorebic log` follows | a file a day (the UTC date), never removed by komorebi |
| `$XDG_DATA_HOME/komorebi/komorebi_plaintext.log.YYYY-MM-DD` | the same log without colors | as above |
| `$XDG_DATA_HOME/kglobalaccel/komorebi-*.desktop` | the static shortcuts `komorebic hotkeys compile` and `komorebic export-kde-shortcuts` write, each with `X-Komorebi-Generated=true` | replaced at every write: the files with that key are removed, and no other |
| `$KOMOREBI_CONFIG_HOME/{skhdrc,whkdrc,sxhkdrc}` | the key binding file `komorebic hotkeys compile` reads when it is given none (the first that exists), and the skhdrc of `export-kde-shortcuts` | the user's |
| `$KOMOREBI_CONFIG_HOME/{skhdrc,whkdrc,sxhkdrc}` | the key binding file `komorebic hotkeys compile` and the daemon read when they are given none (the first that exists), and the skhdrc of `export-kde-shortcuts` | the user's; the daemon reads it once, at start |
Without `XDG_RUNTIME_DIR` the bridge and the socket are in `komorebi` in the local data
directory instead, with the logs (see [`XDG_DATA_HOME`](#xdg_data_home)).
@@ -380,8 +413,8 @@ The config home, where komorebi looks for `komorebi.json`: a directory, in which
configuration` and the daemon look for the file. Without it the config home is
`~/.config/komorebi`, whatever `XDG_CONFIG_HOME` is. When it is set and is not a directory, the
daemon and `komorebic` panic when they first need the config home, and say so. Environment
variables in it are expanded (`$HOME/komorebi`). `komorebic hotkeys compile` looks in it for the
key binding file it is not given.
variables in it are expanded (`$HOME/komorebi`). The daemon and `komorebic hotkeys compile` look
in it for the key binding file they are not given.
### `XDG_RUNTIME_DIR`
+8 -1
View File
@@ -106,7 +106,9 @@ check also runs `ruff` and `ty` over it. The driver type checks every
the run.
- `Checks` counts checks and fails once, at the end, so that one failure does
not hide the ones after it. `finish()` prints `passed: N failed: M`.
not hide the ones after it. `finish()` prints `passed: N failed: M`, and its
error names the checks that failed, which `nix build` shows in the last lines
of the run.
- `Kde` is one KWin session. `Kde.headless(machine, name, size=, outputs=,
scale=)` starts the units and waits for KWin to own its name on the private
bus. `wid`, `rect`, `title` and `active` read windows through `kdotool`,
@@ -187,6 +189,11 @@ the run.
- `Keys(machine).send("alt-shift-k")` presses a combo on the machine's
keyboard, written as KDE writes it in lower case with `-` between the keys
(`meta` and `super` are the left Super key).
- `spawn_komorebi(*args)` starts a daemon of the test's own in the session
node's Plasma session, logging to the file `komorebi_log()` reads;
`kill_spawned_komorebi()` kills it with `SIGKILL`; `shortcut_actions()` lists the
actions komorebi has registered with kglobalaccel. A suite that spawns its own
daemon turns the module's unit off in its `node`.
## Pressing keys