Commit Graph
14 Commits
Author SHA1 Message Date
LGUG2Z 9cb26daf38 build(nix): keybindings in the module
On NixOS the key bindings belong in the configuration, with the rest of
komorebi. services.komorebi.keybindings takes the format (skhd, whkd or sxhkd),
the bindings as text or as a file (exactly one of the two, asserted), the mode
(auto, engine or static; engine by default, as PlanMode::default() is),
chordTimeout (3000 ms), layout (us, the only one), strict and appAliases. skhd's
.load is refused by an assertion: the file it reads would not be in the store.

At build time the module runs komorebic hotkeys compile on the file in the
package komorebi-keybindings, whose share/kglobalaccel goes into the system
profile, where KWin finds the static shortcuts when the session starts. Its
diagnostics are in the build log and in diagnostics.txt, and strict passes
--strict, which fails the build on a warning or an error. execStart gains
--keybindings with the same store file, its format and mode, --chord-timeout and
an --app-alias per alias, so the daemon plans the file as the build did and runs
the bindings the build left to the engine. The unit already releases the keys
after the daemon stops.

The check keybindings-fixtures runs every file of the fixture corpus through
komorebic hotkeys compile --mode auto --dry-run, the command the module runs,
and diffs what it prints against nix/tests/keybindings.expected; it also checks
that docs/{skhdrc,whkdrc,sxhkdrc}.sample are the corpus's sample case.
nixos-module-eval gains the key binding scenarios: text, file, both, no format,
.load and a layout that is not us, and one with the typed config together with
key bindings, whose execStart has the checked file and then the keys. The corpus
gains the case vm, in the three formats: a binding a shortcut file can hold, and
one on the comma key, which X-KDE-Shortcuts cannot, so that the engine runs it
in auto mode. The VM suites vm-keys-skhd, vm-keys-whkd and vm-keys-sxhkd
configure the module with that case in their format and press both keys; they
share one script through the generator's script attribute.

For strict, nixos-module-eval has two scenarios with the same skhd text, which
has a line komorebic cannot read: strict = true and the default. Evaluation
never reads the key bindings, so the checks read the script of the build: with
strict it runs hotkeys compile --strict and exits 1 when that fails, without it
there is no --strict and the diagnostics are only printed to the build log. A
third check says the daemon gets the same command line either way. ARCHITECTURE
names them in the row for strict.

komorebic quickstart writes the sample skhdrc next to komorebi.json and
applications.json, from docs/skhdrc.sample, where the daemon and hotkeys compile
read it; the flake's source filter keeps that file for the build.

Docs: the user guide docs/usage/keybindings.md, the three sample files,
docs/example-configurations.md for KDE and NixOS, the options in
docs/installation.md, and the module's section of ARCHITECTURE. Whether the
engine or static shortcuts should be the default stays open in DESIGN: a static
shortcut took 233 ms to run its command at the median on KWin 6.8.1, the engine
3 ms, but only the static shortcut survives a dead daemon.
2026-10-28 07:39:49 -07:00
LGUG2Z 2f61b62276 feat(kwin): survive restarts of the daemon and KWin
kglobalaccel keeps the actions of a client that died, and their keys: a daemon
that is killed leaves its keys swallowed and running nothing until they are
unregistered. And kglobalaccel runs inside KWin, so a KWin that restarts forgets
every key komorebi registered. Neither should leave a user without keys.

kwin::hotkeys::release unregisters every action of the component, whatever
registered it, and komorebic hotkeys release runs it, with or without a daemon.
The NixOS module's unit runs it after the daemon stops (ExecStopPost), however
it stops, and a start already takes over what is left. The KWin backend's
NameOwnerChanged watch now also follows org.kde.kglobalaccel: when it has an
owner again, kwin::hotkeys::rebind loads the key bindings into the new one,
trying for 15 seconds.

Loading moves from the daemon's main into kwin::hotkeys::load, which keeps its
settings (Keybindings: file, format, plan mode, engine options), so that reload
can read the file again: the message ReloadHotkeys, komorebic hotkeys reload. A
new engine replaces the running one without unregistering its keys, and takes
them over as a start does, so the keys both files have stay grabbed. The message
HotkeysState answers with the engine's mode, the combos it holds and whether a
chain is pending (null without an engine); komorebic hotkeys state prints it
with the actions kglobalaccel has for the component. komorebic now depends on
komorebi for the two calls to kglobalaccel, and on serde_json for the state.

Tests: the socket messages without key bindings, state and release without a
session bus, reload without a daemon, and a nixos-module-eval check of
ExecStopPost. The VM test vm-restart-survival runs the module's unit in a Plasma
session: a key works, hotkeys state shows it; with the daemon stopped by SIGSTOP
the key runs nothing until hotkeys release gives it back; after SIGKILL the
unit's journal shows the release and the restarted daemon has the key; after the
KWin process is killed, the daemon registers the key with the new KWin; and a
reload of a changed file swaps the key.

vm-keys-engine asks the engine and does not sleep. A key that is not grabbed yet
reaches the focused window, which showed as a binding that does not run, so the
suite presses one once komorebic hotkeys state answers, which it does when the
engine has made the calls of its last event: for a mode, for a chord chain
beginning and ending, and for the keys of the application that takes the focus.
It waits for the old daemon to exit before it starts the next (a daemon started
meanwhile failed to load its KWin script), and activates a window until KWin has
it (KWin lists a window before it can have the focus). The last check reloads
the key bindings with komorebic hotkeys reload while wev has the focus and every
binding is for the terminal, a start with no key to grab.
2026-10-28 07:39:49 -07:00
LGUG2Z 47d3a471d7 feat(kwin): per-application key bindings follow the focus
skhd and whkd can give one key a different action in each application, or none
(skhd's ~, whkd's Ignore), and skhd has a blacklist of applications in which no
key is taken. The engine decides from the focused application whether such a key
is active: inactive, it reaches the application, which is how a key passes
through. What it needs is to be told which application has the focus.

The bridge reports the desktop entry of every window with its class, and the
table now keeps it. Table::focused_application returns the executable, the app
id (or X11 class) and the desktop entry of the window KWin activated last, a
dialog included, or nothing once that window is gone. The KWin backend hands it
to kwin::hotkeys::focus after every event of the bridge; only a change reaches
the engine's thread, and an engine that starts begins with the focus as it was
last seen. The engine matches the names of the file against the three, ignoring
case.

The names in an skhdrc or a whkdrc are those of macOS and Windows applications,
so the daemon takes --app-alias NAME=ALIAS[,ALIAS]..., more than once, for the
engine's app_aliases.

Unit tests cover the focus of the table and the calls of a scoped key as the
focus moves, an alias included. The VM test vm-keys-engine grows a section with
wev and foot open and --app-alias terminal=foot: in wev, Alt+G (for the terminal
only) and Alt+N (which wev ignores) reach wev and run nothing; in foot both run
their bindings; back in wev, Alt+G reaches wev again.
2026-10-28 07:39:49 -07:00
LGUG2Z 260d8ff03e feat(kwin): end a chord chain at its timeout
An sxhkd chain (alt + w ; h) is realized by the engine: after the prefix only
the keys that can come next and Escape are grabbed, because KWin 6.8's own key
sequences never fire. What ends a chain that nobody finishes is the chord
timeout, and the engine has no clock: it is told the time with on_tick. Rather
than ticking on a timer forever, the engine now says when its pending chain
times out (Engine::deadline, in komorebi-hotkeys) and the transport sleeps until
then, calls on_tick, and grabs the keys of the mode again. With no chain pending
it does not wake up at all.

The daemon takes --chord-timeout in milliseconds, 3000 by default, the engine's
default and the module's chordTimeout to come.

A unit test follows the calls of a chain from its prefix to its deadline. The VM
test vm-keys-engine grows a section with an sxhkdrc passed as --keybindings and
a timeout of 1.5 s: Alt+W, H runs the binding and H does not reach wev; Alt+W,
Escape lets the next H reach wev; Alt+W and two seconds later L reaches wev and
runs nothing.
2026-10-28 07:21:14 -07:00
LGUG2Z 3f72eb84d1 feat(kwin): realize the modes of a key binding file in the daemon
skhd's modes, and sxhkd's chains that stay open, are sets of keys that are
active together; a static shortcut cannot be in one. The engine already computes
the keys a mode wants. What the daemon adds is that a mode switch reaches
kglobalaccel as it should: the keys of the mode left are let go with
setInactive, so that they reach the focused window again, and those of the mode
entered are grabbed, bare keys included, before the next key arrives. It logs
the mode after each change, which is the one way to see from outside which mode
the engine is in.

A unit test follows the calls of entering a mode and leaving it with Escape. The
VM test vm-keys-engine grows a section with wev focused: in the default mode a
bare H reaches wev; Alt+R enters the mode resize and runs its command, after
which H runs its binding and does not reach wev; Escape goes back, and H reaches
wev again. That turns "a key the engine does not want reaches the application"
from a convention into a proved rule.
2026-10-28 07:21:14 -07:00
LGUG2Z b49c4fab0a 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.
2026-10-28 07:21:14 -07:00
LGUG2Z 44f7236698 feat(cli): check the desktop
komorebi fails quietly when the desktop is not what it was made for: over ssh
there is no session bus, a daemon whose script is not in KWin tiles nothing
while it runs, and komorebi needs KWin 6. `komorebic check` now looks at the
desktop after the configuration, and `--configuration-only` leaves that out for
a machine that is not the one komorebi will run on.

It looks at the session (KDE, Wayland), the session bus, KWin on it and KWin's
version, the daemon and its script (the daemon is running when its socket takes
a connection, the script is in KWin when KWin says it has loaded it), and what
starts komorebi at login. A bus that cannot be connected to or does not answer,
and no KWin on it, are errors, and the looking stops there because nothing after
them can be answered. Every call has two seconds to answer, so a bus that never
does cannot hold the check.

The test of the missing session bus used to remove the address and the runtime
directory from the environment and so depended on it: a machine with a user bus
at /run/user/UID/bus answered it. It now gives an address with no socket behind
it. A bus that accepts and never answers, the autostart finding and
--configuration-only have tests too, and the VM suite vm-check runs the command
against a real KWin with the daemon running, with its script gone, with no
daemon and with no KWin on the bus.

It also looks at the two effects KWin draws and animates with, and at the Plasma
shell. Only komorebi's builds of them do everything komorebi asks (a color for
each kind of window, every animation style), so the check tells a build by what
it contains: the interface of the border effect in its plugin file or its object
on the bus, a Curve setting in the animation effect's script. It looks for them
where KWin looks, from KWin's own environment, and a stock effect is a warning
only when the configuration asks for what it cannot do (borders, an animation
style other than the stock curve), and so is a copy in the user's own data
directory that hides komorebi's. The Plasma shell is looked for when the file
has wallpapers. vm-check runs all of it against KWin.
2026-10-28 07:20:57 -07:00
LGUG2Z c6874ff5db feat(cli): quickstart, autostart and the config commands
komorebic quickstart writes an example komorebi.json and applications.json into
the config home, asking before it writes over a file, so a new user has a
configuration to start from. komorebic enable-autostart writes the XDG autostart
entry that has Plasma start komorebi at login, with the komorebi.json it is
given if any, and disable-autostart takes it away; the NixOS module does the
same job for a machine that has it.

komorebic replace-configuration makes the running daemon start over from another
komorebi.json: it pauses its window manager and brings back the windows it hid,
the back of a stack, so that none is out of sight for the new one to miss, then
makes the window manager again from the file, with the monitors and the windows
the backend has, and watches the new file in place of the old one. A file that
does not read is logged and the daemon carries on as it was.
2026-10-28 07:20:37 -07:00
LGUG2Z 5eaa613f50 feat(wm): configuration in komorebi.json
The daemon takes its settings from a komorebi.json: the file --config names, or
the one in the config home ($KOMOREBI_CONFIG_HOME, else ~/.config/komorebi).
Without a file it runs on its defaults, as before.

StaticConfig reads the file in three steps, because the monitors are known only
after the backend has been asked. preload makes the window manager and applies
the settings that are process-wide, postload gives each monitor and workspace
the entry of its place (by the index display_index_preferences gives a monitor's
serial number id, else in order), and main asks KWin for a desktop for each
workspace the file lists. A watcher on the file sends the daemon a
ReloadStaticConfiguration about two seconds after it changes, whether an editor
wrote the file in place or renamed a new one over it, and a file that does not
parse changes nothing.

A workspace can change its layout, its work area offset and its layout options
with the number of its containers, from the file or with komorebic
(workspace-layout-rule, its named form and the two that clear), and
layout_defaults gives every workspace of a layout the options it sets none of.
One file is meant to serve every platform, so a key that does nothing on Plasma
is accepted and ignored. config_parity checks the example and the files of other
platforms; the keys of features that are not in yet are listed there, and the
test fails when a list names a key that is read.

The file also sets what the stacks, the float override, the floating layer and
monocle set while the daemon runs: window_container_behaviour, with its rules by
container count in a workspace, float_override, float_override_placement,
floating_layer_behaviour (for a monitor and a workspace too),
floating_layer_placement and monocle_focus_behaviour. Their features come before
this commit, but a file to put the keys in does not, so they are part of this
one.

komorebic gains configuration, generate-static-config and start --config. The
NixOS module gets configFile, which the unit gives the daemon as --config.
2026-10-28 07:20:37 -07:00
LGUG2Z 0d21dd332c feat(wm): monocle
A workspace could show its windows only side by side. Monocle gives one
container the whole work area: the focused container is taken out of the
workspace's containers, so the layout gives no container a tile, and the next
tiling puts its window on the work area less the padding. Turning it off puts
the container back at the index it came from, and the tiles come back as they
were resized: the container keeps its resize adjustment, and the workspace does
not shorten the list of adjustments while a monocle is on.

The windows of the other containers are hidden on the parking desktop, as the
windows behind the front one of a stack are, and the front window of each is
shown again when the monocle is turned off or the window in monocle closes. A
stack in monocle stays a stack.

`komorebic toggle-monocle` turns it on and off. What focusing in a direction
does meanwhile is set with `monocle-focus-behaviour` or switched with
`toggle-monocle-focus-behaviour`: with `cycle` the monocle goes to the previous
or the next container, with `no-op`, the default, no container is on any side
and the focus falls through to the monitor on that side, where the monocle
window of its workspace, if it has one, is given the focus, and the command
fails where there is no monitor. A container that is moved to a monitor or sent
to a workspace in monocle turns that monocle off first. `cycle-focus` always
carries the monocle along. Giving the focus to another window gives it back to
the monocle window, so that it stays in front. `move` and `cycle-move` are
refused and `toggle-float` is ignored while a window is in monocle, since the
focused container is not the window in front. The monocle container is in the
state, with the index it goes back to, and a window in it that closes takes the
monocle with it.

komorebi/tests/monocle.rs drives it against the fake desktop, with one monitor
and with two. vm-core-e2e checks in a real KWin that the focused window fills
the work area, that the state has the monocle container, that toggling back
restores the tile, that the cycle behavior gives another window the work area,
and that the windows behind a monocle are parked, which a clean stop and the
next start after a crash put right; vm-stacks checks a monocle over a stack; the
vm-commands sweep runs the new commands.
2026-10-28 07:20:37 -07:00
LGUG2Z 331db681e2 feat(wm): stack out of sight on a parking desktop
A container has one tile, so the windows of a stack that are not in front have
to be out of sight. KWin has nothing a script can set to hide a window except a
virtual desktop nobody looks at, which the first spike measured to cost no focus
change where minimizing a window cost two. Backend::hide takes a window out of
sight and Backend::restore brings it back; the KWin backend parks the window on
a desktop named komorebi-park, which the table keeps out of the workspaces, and
remembers where each hidden window came from so that it is still on its
workspace.

KWin saves a desktop in kwinrc as soon as it is made, so komorebi removes the
parking desktop when it stops, after the windows are back, and the first
snapshot of the next run finds one a killed run left, sends its windows home and
removes it. The windows komorebi hid are recorded, so that a minimize the
compositor reports for one is not mistaken for the user's.

komorebic stack, unstack, stack-all and unstack-all stack and unstack windows.
The window container behavior and the float override decide whether a window
that opens joins the focused container or floats, for every workspace or for
one. vm-stacks stacks windows in a headless KWin, shows a workspace and goes
back, stops, and kills the daemon with a window parked.
2026-10-28 07:20:37 -07:00
LGUG2Z a86e2bdc63 build(nix): a NixOS module for komorebi
On NixOS, running komorebi should take one flake input and one module line. The
flake exports `services.komorebi` as nixosModules.default (and .komorebi). It
adds the flake's overlay, which gains komorebi-full, installs komorebi and
komorebic, and runs the daemon in every Plasma session as a systemd user unit,
wanted by plasma-workspace.target and ordered after plasma-core.target, which
Plasma orders after KWin. systemd starts a daemon that fails again; the exit
status of a SIGTERM (130) counts as success, so a stopped unit is not failed.
The unit's PATH is the one a terminal in the session has, instead of the few
store paths NixOS gives a unit.

The options are enable, package, logLevel and a read-only execStart, the command
line the unit runs. There is no configFile: the daemon reads no configuration
file yet, and an option that linked one would do nothing.

nixos-module-eval evaluates seven scenarios as real NixOS systems and checks
their assertions, the unit and execStart, with builtins.tryEval for the two that
must not evaluate. Nothing in it builds a Linux package, so it runs on a Mac as
well.

The VM nodes import the module, so every suite runs komorebi as the module
installs it. The headless node's komorebi@NAME runs execStart, which has
--log-level, so the nodes set logLevel to debug and the suites stop passing it;
latency, which times the daemon, keeps the default level. The session node
starts the module's unit at login; render-smoke turns it off, since a tiled
terminal would cover the desktop it looks at. A new fast suite, vm-module, logs
in to Plasma and checks that the unit runs the daemon with the module's log
level and PATH, that a window opened in the session is tiled, that a killed
daemon is started again, and that a stop is not a failure.

docs/installation.md covers NixOS first, and building from source on other
distributions. There is no binary cache: the Komorebi license does not allow
third parties to redistribute binaries.
2026-10-28 07:20:37 -07:00
LGUG2Z e2d757bbb0 feat(wm): subscribe to notifications
A program such as a status bar has to follow the window manager, and so far it
could only ask: komorebi on Windows and on macOS sends notifications for that.
The daemon now keeps subscribers, each a Unix socket in its data directory that
a program listens on, and after each event and each message it handles, it
connects to every subscriber and writes the event or the message with the state
after it.

A subscriber can ask to be sent only what changed the state; a window that is
shown and a new subscription are always sent, so a subscriber has the state as
soon as it subscribes. A subscriber that cannot be connected to is dropped with
its socket file and not tried again, and a stopping daemon closes an empty
connection to each one.

komorebic gains subscribe-socket and unsubscribe-socket, and komorebi-client
subscribe and subscribe_with_options, which bind the socket and subscribe. The
tests subscribe through real sockets against the fake desktop: a shown window is
sent with the state that has it, a subscriber that filters is not sent a
question that changed nothing, and one that is gone is dropped.
2026-10-28 07:20:37 -07:00
LGUG2Z 6f657e53e3 feat(cli): komorebic
The daemon answers on its socket, but a person has no way to write a message on
it. komorebic is that way: each subcommand that asks something of the daemon is
one message, sent with komorebi-client, and a question's answer is printed.
komorebic is a separate program because the daemon takes no input but its
socket, so a key binding, a script and a terminal all drive it the same way.

It has what the daemon can answer so far: state, monitor-information, query,
retile and stop. Around them, start runs the komorebi on the PATH in the
background and passes it what follows a --, such as --fake-backend to try it
without a compositor; log follows the daemon's log, which the daemon now writes
to a file a day in LOG_DIR as well as to stdout; data-directory shows where the
socket is; completions prints a shell completion script. The hidden docgen
writes each subcommand's help to docs/cli, in fences that name their language
and wrapped at 100 columns whatever the width of the terminal, so that the pages
are the same wherever they are generated; just docgen runs it.

The user guide starts here: docs/index.md for KDE Plasma, and a page on running
komorebi. tests/cli.rs runs each subcommand against a socket the test serves in
place of the daemon. In the VM tests the guests get komorebic next to the
daemon, and vm-core-e2e reads the daemon's state with it (the windows it
manages, the one it focuses, after KWin restarts too) and stops it with
komorebic stop, which unloads the bridge and removes the socket.

In the VM test library, Kde.state asks again, a second (times the scale) after
an empty answer or a failed command, up to 10 times. The daemon drops a query
when it cannot take hold of the window manager within a second, and komorebic
then prints an empty line and succeeds; komorebic itself gives the daemon a
second to answer and fails when that is not enough. A daemon busy with the first
windows does either on a machine that is loaded or slow, and a suite that polled
the state died on JSONDecodeError. An answer that is not JSON still fails at
once.
2026-10-28 07:20:37 -07:00