feat(hotkeys): the engine as a pure state machine

What a static shortcut file cannot be (modes, chord chains, release bindings,
per-application bindings, a blacklist, a pause binding) komorebi realizes
itself, with keys it registers in kglobalacceld. The engine is the logic of
that, with no I/O and no clock: it takes the press and the release of an active
combo, a change of the focused window and the time, and returns effects: combos
to activate or deactivate, and commands to run (komorebic's to dispatch
in-process, the others through `sh -c`).

After every event it computes the set of combos it wants from its state (the
mode, the chord chain being typed, the focused application, whether it is
paused) and returns the difference with the active set, so that a key it does
not want reaches the application. That is how everything works, because of what
KWin 6.8.1 was measured to do: KDE's own multi-key sequences never fire, while a
single combo can be grabbed and given back (`setShortcutKeys`, `setInactive`) in
well under a millisecond each. A chain's first combo is an active key, and
pressing it leaves only the next combos and Escape active until one is pressed
or the chord timeout (3 s by default) passes. A scoped key is active only while
the focused application, matched without regard to case on its executable,
app_id or desktop entry and on the configured aliases, has an action for it.
Autorepeat arrives as a separate signal the engine has no input for, so a held
key runs its binding once.

The D-Bus side (registering the component, carrying out the effects, feeding the
signals in) belongs to the daemon and is not here.

The crate documentation now ends with what is emulated and what is not, across
the readers, the plan and the engine.
This commit is contained in:
LGUG2Z committed 2026-10-28 07:20:57 -07:00
1 parent 8f5d4a32ef
commit a2e7f12bd3
6 files changed
+837 -8

No files matched your search

+23
View File
@@ -746,3 +746,26 @@ at the median, while the engine was told of the key 3 ms after it. So the defaul
The cost is the robustness of static shortcuts: the engine works only while komorebi runs,
and a komorebi process that was killed leaves its keys registered and dead until they are
released.
## 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
accepts a sequence of keys for one action (`Meta+A, B`), but the action never fired: the
second key reached the focused application instead. What does work is grabbing and giving
back single combos: a combo registered with `setShortcutKeys` is swallowed and reported,
also a bare key with no modifier, and after `setInactive` the same key reaches the
application again. Sixty such calls, sent without waiting for the answers, were all answered
in 2.4 ms.
So the engine realizes everything with one set of active combos. A chord chain is a combo
that, when pressed, makes only the combos that can come next (and Escape) active, until one
is pressed or the chord timeout passes. A mode is a different set. A per-application binding
is in the set only while the focused application has an action for it, so that elsewhere
the key reaches the application. After every event the engine computes the set it wants and
returns the difference.
A held key sends one pressed signal, then repeated ones, then one released signal. The
engine acts on the pressed signal only, so holding a key runs its binding once.
The engine itself does no I/O: it returns what to do, and the daemon does it. This entry
needs the reason for that split.