feat(cli): turn key binding files into KDE static shortcuts

komorebi users keep their bindings to komorebic in a file of skhd, whkd or
sxhkd. On Plasma under Wayland no client sees the keys of another, and the
program that runs a command on a key is KDE's global shortcut daemon, which runs
inside KWin. A binding that is one combo, pressed, the same in every
application, in a file without modes, can be a static shortcut: a .desktop file
that KWin reads by itself, that shows in System Settings and that works with no
komorebi process at all.

komorebic hotkeys compile reads a file of any of the three formats, plans it
with komorebi-hotkeys in the mode it is given (auto, engine or static; the
default is the crate's), prints the diagnostics of reading and planning, and
writes the static shortcuts to $XDG_DATA_HOME/kglobalaccel or --output,
replacing the files it wrote before and no other. --strict refuses a file with a
warning or an error before writing anything, --dry-run says what a write would
change, and --reload hands each new file to the running KWin. komorebic
export-kde-shortcuts keeps the spike's interface for an skhdrc, in the static
mode. Both are thin: the reading, the plan and the files are the crate's. The
bindings that need the engine are counted; the daemon does not run them yet.

docgen gives a subcommand of a subcommand a page of its own
(hotkeys-compile.md). KOMOREBI_CONFIG_HOME, or ~/.config/komorebi, is where
komorebic looks for a file it is not given.

komorebic check gains a section for the key bindings, between the configuration
and the desktop: the first key binding file of the config home, how many
bindings it has and where they go, the lines that cannot be read (a warning, and
the first five) and the bindings not realized as their own daemon would (a
note), and whether the generated files in the shortcut directory are the ones
hotkeys compile would write now (a warning with how many to add, to change and
to remove). --configuration-only keeps it, as it looks at files.

The VM test vm-keys-static boots a Plasma session with shortcut files that
hotkeys compile wrote into the system profile at build time, presses their keys
through QEMU's keyboard, and sees each command run, a % in one of them included;
then it writes a binding in the middle of the session with export-kde-shortcuts
--reload and presses it. The library gains Keys, which sends a combo as KDE
writes it through QEMU's sendkey.
This commit is contained in:
LGUG2Z committed 2026-10-28 07:20:57 -07:00
1 parent a2e7f12bd3
commit e1a227434b
27 files changed
+1585 -36

No files matched your search

+37 -3
View File
@@ -964,8 +964,9 @@ configuration or a wallpaper that is not there, a wallpaper no theme can be made
that is only a name, which is not tiled, and a workspace that appends windows to a container and
has placement rules, which are not used then (the workspace's `window_container_behaviour`, or the
file's when it has none). [`check_configuration`] also returns the [`Wants`] of the file: whether
it draws borders, which animation style it asks for and whether it has wallpapers. `komorebic`
prints [`Report::render`] and exits with status 1 if [`Report::has_errors`].
it draws borders, which animation style it asks for and whether it has wallpapers. The key binding
file has a section of its own, which `komorebic` makes (see [Key bindings](#key-bindings)).
`komorebic` prints [`Report::render`] and exits with status 1 if [`Report::has_errors`].
[`check_environment`] looks at the desktop, with D-Bus calls of its own on the session bus (they
are in the table of [PLATFORM.md](PLATFORM.md#d-bus)), and `komorebic check --configuration-only`
@@ -1633,6 +1634,27 @@ daemons: skhd (macOS), whkd (Windows) and sxhkd (X11).
- [`tests/fixtures`](../../komorebi-hotkeys/tests/fixtures): the corpus, `<case>.skhdrc`,
`<case>.whkdrc` and `<case>.sxhkdrc`, each case in every format that can express it.
### The front end
[`komorebic/src/hotkeys.rs`](../../komorebic/src/hotkeys.rs) is the command line over the
crate, and decides nothing about what a file means. `komorebic hotkeys compile` reads a file (by default the
first of `skhdrc`, `whkdrc` and `sxhkdrc` in the komorebi config directory, its format from
the end of its name), plans it in the mode it is given (by default `PlanMode::default()`),
prints the diagnostics of reading and of planning on standard error, and writes the static
shortcuts to `$XDG_DATA_HOME/kglobalaccel` or `--output`, replacing the files it wrote before.
With `--strict`, a diagnostic that is a warning or an error stops it before it writes
anything. `--dry-run` writes nothing and prints what a write would change, and `--reload`
hands each new file to the running KWin, which otherwise reads them at the next login.
`komorebic export-kde-shortcuts` is the same for an skhdrc, in `PlanMode::Static`.
`komorebic check` has a section for the key bindings, between the configuration and the desktop.
`hotkeys::check` finds the file as `compile` does, reads and plans it in the default mode, and
returns [`Finding`]s: how many bindings the file has and where they go, how many lines cannot be
read and left out (a warning) and how many bindings are not realized as their own daemon would
(a note), each with the first five, and whether the generated files in the shortcut directory are
the ones `kde::diff` says that plan would write. It reads no file the desktop has no part in, so
`--configuration-only` keeps it.
### What is guaranteed, and by what
| Rule | Enforced by | Proof | Escape hatch |
@@ -1654,6 +1676,12 @@ daemons: skhd (macOS), whkd (Windows) and sxhkd (X11).
| Stopping the engine gives every key back | test, of the effects; carrying them out is the daemon's | `start_activates_the_default_mode_and_stop_gives_everything_back` | none |
| The engine does no I/O and reads no clock | convention only | none | none |
| The whkd reader reads a whkdrc as whkd does | test, on the files it is given | `every_whkdrc_of_the_corpus_reads_as_whkd_reads_it`, `the_example_of_whkds_readme_reads_as_whkd_reads_it` | none |
| `hotkeys compile` writes the static shortcuts of the plan and nothing else, from a file of any format | test, through the binary | `compile_writes_the_same_shortcut_files_from_each_format`, `compile_in_engine_mode_writes_no_shortcut_and_removes_the_ones_it_wrote` | none |
| `komorebic check` reads the key binding file `hotkeys compile` would read, the way it does | framework path: `check` and `export` share `find` and `diagnostics`, and call the same `parse` and `plan` | `the_first_file_of_the_three_formats_is_the_one_that_is_read`, `the_key_binding_file_of_the_config_home_is_read_and_a_line_it_cannot_read_is_a_warning` | none |
| A line of the key binding file that cannot be read does not fail `komorebic check` | test, through the binary | `the_key_binding_file_of_the_config_home_is_read_and_a_line_it_cannot_read_is_a_warning` | none |
| `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 |
## Where to look in the code
@@ -1686,7 +1714,8 @@ daemons: skhd (macOS), whkd (Windows) and sxhkd (X11).
format.
- [`komorebi/src/check.rs`](../../komorebi/src/check.rs): the checks of `komorebic check`, with
their tests; [`komorebic/tests/check.rs`](../../komorebic/tests/check.rs) runs the command on
configurations and on buses that are not there, and reads what it prints and its exit status;
configurations, on key binding files and on buses that are not there, and reads what it prints
and its exit status;
[`nix/tests/vm/suites/check`](../../nix/tests/vm/suites/check/test.py), the desktop check against
a real KWin, with the daemon running, with its script gone, with no daemon and with no KWin.
- [`komorebi/src/process_event.rs`](../../komorebi/src/process_event.rs): what each event
@@ -1836,6 +1865,11 @@ daemons: skhd (macOS), whkd (Windows) and sxhkd (X11).
[`sxhkd.rs`](../../komorebi-hotkeys/src/sxhkd.rs);
[`plan.rs`](../../komorebi-hotkeys/src/plan.rs) and [`kde.rs`](../../komorebi-hotkeys/src/kde.rs)
for the shortcuts, [`engine.rs`](../../komorebi-hotkeys/src/engine.rs) for the engine.
- [`komorebic/src/hotkeys.rs`](../../komorebic/src/hotkeys.rs): `export-kde-shortcuts` and
`hotkeys compile`, and the key bindings section of `komorebic check`;
[`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-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;
+3
View File
@@ -747,6 +747,9 @@ The cost is the robustness of static shortcuts: the engine works only while komo
and a komorebi process that was killed leaves its keys registered and dead until they are
released.
Which of the two is the default is still open for a decision. `PlanMode::default()` is the
one place it is set, and `komorebic hotkeys compile` takes its default from there.
## Why does the engine grab and give back keys, instead of using KDE's own key sequences?
Because KDE's do not work for this, as measured on KWin 6.8.1 (2026-10-27). kglobalacceld
+36 -1
View File
@@ -292,6 +292,31 @@ At time of writing (2026-10-27), the headless KWin of the VM tests (Plasma 6.8)
major version from it. The check does not need the answer: without the line it says that KWin is
there and its version could not be read.
## Global shortcuts
KDE's global shortcut daemon runs inside KWin 6.8: `kwin_wayland` owns `org.kde.kglobalaccel`
on the session bus, and there is no separate `kglobalacceld` process. A KWin started with
`--no-global-shortcuts`, as the headless VM tests start it, has none.
A static shortcut is a `.desktop` file in a `kglobalaccel` directory with
`X-KDE-GlobalAccel-CommandShortcut=true` and the key in `X-KDE-Shortcuts`; KWin runs its
`Exec` line on the key. `komorebic hotkeys compile` and `komorebic export-kde-shortcuts`
write such files. What follows was measured at time of writing (2026-10-27) on KWin 6.8.1:
- KWin reads the files when it starts: those in `$XDG_DATA_HOME/kglobalaccel` and those in
`share/kglobalaccel` of the data directories, the system profile of NixOS among them.
- A file added while KWin runs is not read until something calls
`doRegister(["<file name>", "_launch", "", ""])` on `/kglobalaccel`, which is what `--reload`
does for each new file (through `busctl`); the shortcut then works at once. A file whose
content changed keeps the old content until the next login, and a removed file stays
registered until then too.
- In `Exec`, `%` starts a field code, so a command's `%` is written `%%`.
- A static shortcut ran its command 165 to 436 ms after the key, 233 ms at the median, over 8
presses, in a virtual machine under HVF with 4 cores. A key held for 1.5 s ran the command
once.
- 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.
## Files and directories
| Path | What | Lifetime |
@@ -309,12 +334,18 @@ there and its version could not be read.
| `$XDG_CACHE_HOME/komorebi` (`~/.cache/komorebi`) | the palettes made from wallpapers, a file for each picture and variant, `NAME-HASH.base16.VARIANT.json` | never removed by komorebi; made again when the picture's path, size or time of last change differ |
| `$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 |
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)).
## What `komorebic check` looks at
The key binding file is the first of `skhdrc`, `whkdrc` and `sxhkdrc` in `$KOMOREBI_CONFIG_HOME`,
and the shortcut files it compares with are the generated `komorebi-*.desktop` files in
`$XDG_DATA_HOME/kglobalaccel`; neither needs a bus.
Apart from the bus, it looks at the files that start komorebi at login, in this order, and says which
it found first: `$XDG_CONFIG_HOME/autostart/komorebi.desktop` (the autostart entry),
`$XDG_CONFIG_HOME/systemd/user/komorebi.service`, `/etc/systemd/user/komorebi.service` and
@@ -348,7 +379,9 @@ either. An address with no bus behind it is the first error under [No KWin](#no-
The config home, where komorebi looks for `komorebi.json`: a directory, in which `komorebic
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.
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.
### `XDG_RUNTIME_DIR`
@@ -374,6 +407,8 @@ The logs are written to `$XDG_DATA_HOME/komorebi` (`~/.local/share/komorebi` if
`XDG_DATA_HOME` is not set), which the daemon makes before anything else: a home it cannot
write to stops it at once. When `XDG_RUNTIME_DIR` is not set, the bridge and the socket go
there too.
`komorebic` writes static shortcuts to `$XDG_DATA_HOME/kglobalaccel` unless it is given
`--output`.
### `KWIN_EFFECTS_FORCE_ANIMATIONS`
+19
View File
@@ -184,6 +184,25 @@ the run.
pointer lands within a pixel of where it is asked. The program itself is
[`komorebi_vm/uinput.py`](../../nix/tests/vm/lib/komorebi_vm/uinput.py),
whose arithmetic the `vm-lib` check tests.
- `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).
## Pressing keys
A key test presses keys with QEMU's `sendkey` (`machine.send_key`), through
`Keys`. The key reaches the guest's kernel as a key of the machine's virtual
keyboard, and KWin sees it as it sees a person's: a global shortcut fires on
it, and any other key goes to the focused window. QEMU holds the keys for 100
ms, less than the delay before a key repeats. Phase 0 drove keys from a uinput
device inside the guest instead, as the pointer is driven now; `sendkey` needs
no helper program for keys, and on x86_64 under KVM `vm-keys-static` passed with
it on its first run (2026-10-27).
Global shortcuts need the session node: the headless KWin runs with
`--no-global-shortcuts`, so it has no `org.kde.kglobalaccel`. A static
shortcut written into the system profile by the suite's `node` (as
`vm-keys-static` does) is found when the session starts.
Poll for what the test needs with `wait_for`. A fixed sleep is too long on
KVM and too short on TCG.