refactor(repo): move the KDE and macOS docs under docs/ (pure move)

komorebi-for-kde/docs/ -> docs/linux/
komorebi-for-mac/docs/ -> docs/macos/

The Windows docs stay where they are (docs/). Renames only, so links and include paths
that named the old directories are broken at this revision; they are fixed in the revision
that fixes the paths of the whole layout move.
This commit is contained in:
LGUG2Z committed 2026-11-05 15:03:27 -08:00
1 parent 348cb7ae96
commit d781028a2a
390 files changed

No files matched your search

File diff suppressed because it is too large. Load diff
+343
View File
@@ -0,0 +1,343 @@
# What the shared scenarios say about kfde and kfw
[COMPARE.md](COMPARE.md) compares komorebi for KDE Plasma (kfde) with komorebi for Windows (kfw)
from their sources. This document compares them from running them: the scenarios in
`nix/tests/vm/lib/komorebi_vm/core/scenarios` are written once, against the `Platform` of
[vm-tests.md](vm-tests.md), and run on a real KWin and on a real Windows 11 desktop. A scenario that
passes on both says the two ports behave the same in that respect, as far as the scenario looks. A
scenario that fails on one says where they differ, and is a finding to look into, not an assertion
to loosen.
Everything here is a dated result, and says who got it. It is not generated: it is written from the
runs, and goes stale when the code changes.
## Where the results come from
- **kfde**: the suites of this repository, run on 2026-10-29 on a Windows 11 machine's WSL 2 (a
Ryzen 9 5900X, nested KVM), at `scale` 1.5.
- **kfw**: a Windows 11 guest under QEMU on the same machine, running kfw's daemon, driven from
kfw's tree with a copy of `core/` that `scripts/sync-e2e-core` keeps in step. These results were
reported by the session that ran them, and are not repeated here. The guest is a Windows 11
evaluation image. Its display driver was the basic one for the scenarios that have run; a second
display, added and removed while it runs, has since worked with a QXL device and Red Hat's signed
driver for it, which the current image carries. The windows are `komorebi-testwin`, a test window
of its own, where kfde's are `foot` terminals.
## The scenarios
| Scenario | What it checks | kfde | kfw |
|---|---|---|---|
| `tiling` | three windows are tiled: where the layout says, inside the work area, clear of each other | pass | pass |
| `focus` | `focus` and `cycle-focus` move the focus, and the OS and the daemon agree on it | pass | pass |
| `moving` | `move` and `cycle-move` swap tiles, and the focus stays with the window | pass | pass |
| `stacks` | `stack`, `cycle-stack` and `unstack`: the window in view has the focus, the others are put away | pass | pass |
| `monocle` | `toggle-monocle` gives one window the work area and puts the others away | pass | pass |
| `workspaces` | `send-to-workspace` and `focus-workspace` put windows away and bring them back | pass | pass |
| `closing` | a closed window leaves the state, and the others take its room | pass | pass |
| `resize` | dragging the edge two tiles share moves it by what the pointer moved | pass | pass on kfw's `0ffc502c`, **fails** on its master |
| `commands` | every layout, and about 216 commands, leave the daemon healthy | pass, none skipped | pass with a second display, none skipped, when the host is quiet |
| `commands.unknown_monitor` | a window sent to a monitor that does not exist stays managed | pass (fixed) | **known failure** on `0ffc502c`; pass on kfw's `next` (`6d862a11`, 12 checks, no marker) |
| `rules` | initial, permanent and ignore rules by title, and that cleared rules stop applying | see below | pass |
| `rules_class` | a workspace rule and an ignore rule by class (the app id on KDE) send a window or leave it alone | pass | pass |
| `rules_exe` | the same by the program that opened the window; the rule's id is `platform.exe_id(program)`, as kfw's has the `.exe` | pass | pass |
| `config_reload` | rewriting the `komorebi.json` the daemon runs on changes its names, layout and rules | pass | pass |
| `locking` | the screen is locked, a window moved, and unlocked: every window is in its tile again (session suite `core-lock`) | pass | pass |
| `hotplug` | an unplugged display takes its windows to the other, a plugged one is a monitor | pass | pass |
| `placement` | the placement rules of the config put a window first, last, or at a number | pass | 4 of 5 cases pass, **known failure** on `0ffc502c`: the number 2; pass on kfw's `next` (5 of 5) |
| `startup_rules` | the workspace rules of the config apply to a window open before the daemon and to one after | pass | pass |
| `focus_follows_mouse` | the pointer over a window gives it the focus when it is on, not when it is off | pass | pass |
| `lifecycle` | a daemon that stops and starts again takes the windows that were in view up again | pass | pass |
| `lifecycle_hidden` | a window put away on another workspace is managed again after a restart, and those in view are tiled | pass | pass |
| `layouts` | eight layouts, with three and with five windows: each window where the layout says, none over another | pass | pass |
| `floating` | `toggle-float` takes a window out of the tiling, the others take its room, and again it is tiled | pass | pass |
| `minimizing` | a minimized window leaves its room to the others, and a restored one takes it back | pass | pass |
| `padding` | more workspace padding moves the windows in from the edge, more container padding shrinks them, and setting it back restores them | pass | pass |
| `maximizing` | `toggle-maximize` gives a window the work area and the daemon names it, the others stay put | pass | pass |
| `workspace_moves` | `move-to-workspace` takes a window and the focus to another workspace, `focus-last-workspace` goes back and forth | pass | pass |
| `resize_commands` | `resize-axis horizontal increase` and `decrease` widen the focused window and give the width back, with no pointer | pass | pass |
| `promoting` | `promote` puts the window on the first tile and keeps its focus | pass | pass |
| `flipping` | `flip-layout horizontal` mirrors every window's place, and flipping back restores it | pass | pass |
| `pausing` | a paused daemon leaves a new window alone, and an unpaused one takes the next | pass | pass |
| `tiling_off` | `toggle-tiling` leaves the windows where they are, a layout change moves none, and tiling again tiles them | pass | pass |
| `scrolling` | in the scrolling layout each window in turn has the focus and is inside the work area | pass | pass |
| `scrolling.columns` | five windows in two columns: the ones out of view rest at an edge with their width, the strip follows the focus and `pan`, and `consume`, `expel`, `toggle-column-stack` and `scrolling-layout-full-width` work | pass | not run yet |
| `wallpaper` | a monitor's wallpaper at start, a workspace's own while shown, the ring in the hue of the wallpaper, and a changed wallpaper put back | pass 12 | not run yet |
| `scrolling.two_monitors` | a strip with a display next to it: scrolling with `focus` and `pan` shows no window on the second display | pass | not run yet |
| `monitors` | the monitor commands (`send-to-monitor`, `move-to-monitor`, their cycle, workspace and named forms, `focus-monitor`, `cycle-monitor`, `focus-monitor-workspace`, `cycle-move-workspace-to-monitor`, `focus-monitor-at-cursor` where there is a pointer) put each window on the monitor and workspace asked for, tiled in its display, and the focus where each leaves it | not run | not run |
| `layout_flip` | `layout_flip` in the config (`Horizontal`, `Vertical`, `HorizontalAndVertical`) mirrors a workspace's layout from the start, `flip-layout` turns it off and on, and it is the named workspace's own | not run | not run |
`rules` passes on kfde in every check. One run of the suite that holds it also failed a check that
is not the scenario's, that the daemon had exited after `komorebic stop`; the next run passed it,
and the cause is not known.
## What the last runs said
The table above says what each scenario checks. This one is made from the runs themselves, by
`scripts/scenario-status`, from the logs of the suites on KDE and the result files of kfw
(`result.json` for each scenario), so it says what happened and not what somebody wrote. A scenario
a run did not include shows as `-`; kfw's counts are of the checks labelled `shared`. Regenerate
it after a run:
```sh
scripts/scenario-status --kde LOG... --windows DIR --update docs/dev/BEHAVIOUR.md
```
<!-- scenario-status:begin -->
| scenario | kde | windows |
|---|---|---|
| `closing` | pass 5 | pass 5 |
| `commands` | pass 237 | pass 237 |
| `config_reload` | pass 8 | pass 8 |
| `flipping` | pass 3 | pass 3 |
| `floating` | pass 7 | pass 7 |
| `focus` | pass 7 | pass 7 |
| `focus_follows_mouse` | pass 7 | pass 7 |
| `hotplug` | pass 9 | FAIL 1 of 9 |
| `layouts` | pass 50 | pass 50 |
| `lifecycle` | pass 7 | pass 7 |
| `lifecycle_hidden` | pass 6 | pass 6 |
| `locking` | pass 6 | pass 6 |
| `maximizing` | pass 5 | pass 5 |
| `minimizing` | pass 4 | pass 4 |
| `monocle` | pass 7 | pass 7 |
| `moving` | pass 4 | pass 4 |
| `padding` | pass 7 | pass 7 |
| `pausing` | pass 4 | pass 4 |
| `placement` | pass 5 | pass 4, 1 known |
| `promoting` | pass 4 | pass 4 |
| `resize` | pass 8 | pass 8 |
| `resize_commands` | pass 4 | pass 4 |
| `rules` | pass 9 | pass 9 |
| `rules_class` | pass 5 | pass 5 |
| `rules_exe` | pass 5 | pass 5 |
| `scrolling` | pass 4 | pass 4 |
| `stacks` | pass 13 | pass 13 |
| `startup_rules` | pass 6 | pass 5 |
| `tiling` | pass 10 | pass 10 |
| `tiling_off` | pass 6 | pass 6 |
| `unknown_monitor` | pass 0, 2 known | pass 0, 2 known |
| `workspace_moves` | pass 8 | pass 8 |
| `workspaces` | pass 8 | pass 8 |
Only on one port:
| extra | kde | windows |
|---|---|---|
| `commands` | pass 33 | - |
| `core_e2e` | pass 63 | - |
| `drag_resize` | pass 9 | - |
| `hotplug` | pass 19 | - |
| `placement` | pass 5 | - |
| `windows_cloaking` | - | pass 4 |
| `windows_config_file` | - | pass 3 |
| `windows_display_change` | - | pass 7 |
| `windows_padding` | - | pass 2 |
| `windows_second_display` | - | pass 6 |
| `windows_tracking` | - | pass 3 |
| `workspace_rules` | pass 10 | - |
<!-- scenario-status:end -->
## What they have found
**`ignore-rule` drops a rule whose id an earlier rule has, whatever the kind.** `komorebi`'s
`IgnoreRule` handler compares only the ids, so `ignore-rule exe e2e-left` after `ignore-rule
class e2e-left` adds nothing and the window is managed. Seen on kfde; the scenarios use different
names (`rules_exe`). kfw does the same.
**A window sent to a monitor that does not exist was lost, on both ports. Fixed.** After
`komorebic send-to-monitor 7` (or `move-to-monitor 7`) on a desktop with one monitor, the daemon
stopped managing the focused window and left it on the screen with nothing tiling it. On kfw this
was seen on a Windows guest: three windows managed and present, then two managed and three
present, with the command exiting 0 and printing nothing. On kfde `core-e2e` failed the scenario's
check on a real KWin, and the windows after it. The cause:
`WindowManager::move_container_to_monitor` took the focused container out of its workspace with
`remove_focused_container()` and only then looked the monitor up, so the container was gone when
the error was returned; `move_workspace_to_monitor` did the same with the workspace. kfw fixed it
upstream (`837ca257`: check the index first, so the command fails and nothing moves) and the same
fix is in kfde (`017edb40`, with a unit test for each function). On a real KWin `core-e2e` passes
`commands.unknown_monitor` with no known-failure marker (292 checks, 0 failed). On kfw it is fixed on
the `next` branch and a Windows run there passes it (12 checks, no marker); the Windows runner
drops the known-failure marker by itself when the commit under test has the fix, and records it as
a known failure on `0ffc502c`, which does not. `commands.unknown_monitor` can still take a
`known_failure` reason, which `Checks.known_failure` records: such a check does not fail the suite,
and one that holds does, to say the marker can go. The sweep of `commands` is not affected on kfde,
which has two outputs, and on kfw the sweep plugs in a second display first.
**`placement` on kfw.** The rule `initial_window_placement_rules: 2`, with the place as a JSON
number, makes `komorebi.exe` exit at start with `data did not match any variant of untagged enum
InitialWindowPlacementRules`, while the string `"2"` works, and kfde accepts both. kfw's own docs
for the type say an integer is accepted, but its `PlacementTarget` deserializes with
`String::deserialize`, nothing in kfw tests the integer form, and its `schema.json`, generated
from the enum rather than the hand-written deserializer, describes the type as objects
(`{"Placement": ...}` or `{"Index": n}`), which matches neither form. It is a known failure to follow up on later: `placement.run` takes the
description of the case and the reason, and records the case that way, whether the daemon does not
start or puts the windows elsewhere. The other four cases give the same order on both ports.
Fixed upstream in kfw (`3b424dd7`: accept an integer as well as a string, and a schema written by hand);
kfde already had the same fix, and its unit test is in `komorebi/src/core/mod.rs`. A Windows run
of kfw's `next` passes all 5 cases.
**`hotplug` on kfw (fixed upstream).** After a display is unplugged, Windows reports one display within a second,
but kfw's `komorebic state` can keep listing two monitors for as long as it is watched (90 s,
every round of a probe, on master as well as on `0ffc502c`). The daemon's log loops: "potential
monitor removal detected (2 vs 1), verifying in 3s", "verified monitor removal", "removing
disconnected monitors", and again, about every 3 seconds, and the removal never takes effect.
The kfw session's reading, not proven: in `monitor_reconciliator/mod.rs` a monitor counts as
still attached when `serial_number_id` or `device_id` is equal, and a virtual display has no
EDID serial, so `None == None` makes the removed one match the primary; the loop before it
guards with `if let (Some, Some)` and this one does not. Real monitors have serial numbers, so it
may show only with virtual displays. `hotplug` passed 19/19 in several runs and failed that one
check (18/19) in two of three runs of a five-run series, so it is not marked a known failure: a
known failure that holds fails the suite, and this one holds only sometimes. kfde is not
affected: it has no reconciliator loop of this kind, and `hotplug` passes 34/0 there. The kfw
session's reading was right: `None == None` made a display without a serial number match the one
that stayed (and the shared `UNKNOWN` device id did the same for displays with no device path).
Fixed upstream in `5c8e4770`: a serial number identifies a display only when both have one and it
is not empty, a display with no device path is told apart by its name, and the removal goes by index.
kfde needs none of it: its displays are told apart by the serial number when KWin gives one and by
the output's own name when it does not, so two outputs never match each other without a name.
The fix is on kfw's `next`: `hotplug` passed 19/0 in five of the six runs there that completed
(before the fix it failed in about two of three); the sixth crashed with a connection reset to the
guest agent before any check, which is being looked into and is not a check failure. One green run
was thin evidence, so this stands on those five.
**`focus_follows_mouse` on kfw.** The scenario's last check failed on kfw five times in five, and
a replica of its steps passed. The scenario was at fault: it moved the pointer over the window that
already had the focus, waited for a focus that was already there, and moved on at once, so that a
platform that follows the pointer by a hover delay, as Windows' active window tracking does,
never saw the pointer rest there. With the pointer resting for a moment it passes, three times in
three on Windows. A scenario that waits for a state that already holds waits for nothing.
**`resize` on kfw.** Dragging the edge between two tiles by 30, 60 and 120 pixels moved it by 27,
53 and 96 on kfw's master, and by 27, 51 and 106 on its animation branch (`0c9acdf4`), where kfde
moves it by exactly the pointer's distance. The pointer is not the cause: the same drag of the
border of a window that nothing manages moved it by 30, 60 and 120 exactly, with the cursor where
it was asked to be. The loss is in what kfw does with the drag.
A recording of a 60-pixel drag, made with komorebi-recorder on the Windows guest, shows where.
The window grew steadily from 596 to 656 pixels, exactly the distance dragged, which is why the
unmanaged window followed the pointer. kfw's `MoveResizeStart` handler (`process_event.rs`)
reads the rectangle the drag started from with `WindowsApi::window_rect` when it handles the
event, which the recording puts about 100 ms after the drag began, when the window was already
603 to 608 pixels wide. The distance kfw measured was 656 - 603 = 53, and its trace log shows the
resize it asked for with a delta of 106, twice that. A longer drag moves further before the event
is handled, so the loss grows with the distance, as measured. A fix that reads the starting
rectangle from the tile in `latest_layout`, or in the event callback before the event is queued,
was tried afterwards: kfw's `0ffc502c` ("measure a drag from where the tile was") passes the scenario, a 60 pixel drag widening the left tile from 596 to 656 and nothing else moving. kfde reads nothing of the kind and passes. The recording is on the machine that
made it (`~/e2e-w0/rec1/resize/session/rec`), and the write-up is `W1.md` in kfw's tree.
Nothing else moved: no tile went up
or down, none overlapped, and every window stayed inside the work area.
**The padding the state says is not the padding the frames show.** On kfde the state says a
workspace padding of 0 and a container padding of 0, while the windows sit 10 px in from the work
area; on kfw the state says 10 and 10, and the frames of three tiled windows sit 27 px in, 7
more than the 20 the state predicts, on every edge. The kfw 7 px is explained by the kfw session:
it is the room for the borders (a border width of 8 and an offset of -1), taken off the layout when
borders are on, so windows sit padding + container padding + 7 px from each edge and twice
(container padding + 7) apart; a Windows extra checks it. The kfde offset is not explained.
`padding` is not affected: it measures from the padding it sets itself.
**A title change does not make the daemon look at a window again. Decided: kfw's behaviour.** A
window an ignore rule matched when it opened stays unmanaged when it gives itself another title,
and a managed window stays managed. kfw's `TitleUpdate` arm is empty; kfde used to announce a
window it did not have again as a `Show` on a title change, so that a rule on the title it has now
decided (windows are often announced before their title is set), and a window that renamed itself
away from an ignore rule was tiled. The `title_rule` scenario found the difference (kfw's first
Windows run: the window was never managed). The decision is that the ports match, and kfde changed:
`WindowManagerEvent::TitleUpdate` does nothing, the unit tests in `komorebi/tests/rule_commands.rs`
say so, and `title_rule` asserts it on both ports. Passes on a real KWin (5 checks). The price on
KDE: a window that opens with no title and gets one later is decided by the rules on the empty
title only.
**On KDE every monitor has as many workspaces as the one with the most.** Workspaces are KWin's
virtual desktops, and the number of desktops is common to the outputs, so a monitor that gets a
workspace makes the others get empty ones. `cycle-move-workspace-to-monitor` shows it: the
workspace goes to the end of the other monitor's list and is shown there on both ports, but on KDE
the monitor it left is padded back to the common count and shows its last (empty) workspace, where
kfw's shows the one before the removed one (and has no padding). The `monitors` scenario reads the
counts when it needs them and asks only that the monitor it left shows a workspace it has.
**Differences between the ports that the new shared scenarios found.** From the kfw session's
Windows runs on `next` (komorebi `6d862a11`), with the decision of what to do with each:
- **A window the user maximizes** (`maximizing.user`, the title bar button). kfde takes it as the
workspace's maximized window, as for `toggle-maximize`, and kfw's `next` (3fa3d429) does too.
The two ports now agree on what the layout commands do while it is maximized: `move`,
`cycle-move`, `promote`, `unstack`, the resize, send and lock commands and the monocle do
nothing, `toggle-float` floats the maximized window and ends the maximize, and `stack left` and
`stack right` stack the tiles that are left. kfde used to ignore the last two as well; it
follows kfw (**decided**, and the only difference there was). The scenario asserts what is common.
- **A window moved to another display by something other than a drag** (`hotplug.user_move`,
`SetWindowPos` on Windows). kfde follows the window to the other monitor; kfw relocates a window
only when a drag ends (`MoveResizeEnd`) and a move by any other means raises no such event, so it
is not taken there within 45 s. **Decided: a known difference for now**, recorded as a known
failure on Windows.
- **A killed daemon** (`lifecycle_hidden.crash`). On kfw, after `kill -9` during a monocle the windows
it cloaked stayed cloaked and unmanaged. Fixed on kfw's `next` (dc9b2e95, uncloaks what a killed
daemon left): it passes 17/0 there. On KDE it passes (the next start sweeps the parking desktop).
- **Dragging the top edge of the lower tile up** (`resize.edge_cases`, `win3:top:0,-72`). Not a kfw
bug: the scenario pressed 4 px outside the frame, and a Windows window has no invisible border on
its top, so the press hit the desktop. `Platform.resize_grab` gives each port its own press point
(KDE outside the frame, Windows 2 px inside the top row); it passes 18/0 on both ports. On kfw
the scenario is still occasionally flaky (a frame that lags its tile): it now waits for the frames
to match the layout before each press.
## What the scenarios had to allow for
These are differences between the ports that a scenario does not hide, and are not failures:
- **A terminal's size.** A `foot` window sizes itself to whole cells of its font, so its frame is
up to a cell short of the tile (924 by 504 for 925 by 505 in a recorded state). kfw's test window
has no granularity. `Platform.tolerance` is a cell on kfde and 2 pixels on kfw, for the rounding between the DWM
frame and the layout (whether 0 would pass there has not been tried).
- **What "put away" is.** A stack's other windows, the windows of another workspace and those
behind a monocle are on a parking desktop on kfde, and cloaked on kfw. `Platform.hidden` says it
for both.
- **The work area.** A kfw screen of 1280 by 800 has a work area of 1280 by 752, because of the
taskbar. A scenario asks the platform for it.
- **Identity.** A window is told by the title the scenario gave it. kfde's state has its own ids
for windows and monitors, and kfw's has handles, so a scenario never compares them.
- **State shape.** The two `komorebic state` outputs differ in how a window is written and in a few
fields each. `core/snapshot.py` reads both, and its tests read a state recorded from each.
- **What a restart takes up.** `lifecycle` expects every window that was in view to be managed
again. On kfw `komorebic stop` uncloaks a window that was on another workspace, and a new daemon
manages it on the first workspace, but a minimized window stays minimized and is not taken up.
The scenario counts the windows that were in view, so it does not ask for the minimized one.
## Is it stable
On kfw, five consecutive runs of 14 scenarios each (the 13 without `hotplug` and
`focus_follows_mouse`, plus `startup_rules`) on restored guests, komorebi `0ffc502c`, with the
golden image built from scratch by the repo's scripts, had no failure but the two known-failure
markers. `hotplug` is outside that set, because of the monitor-removal finding above. An earlier
set of five had one run lose its agent for over a minute, mid-sweep, which nothing explains.
## Does a broken daemon turn them red
On kfde, with a real KWin: `komorebi/src/workspace.rs` was changed, for one run and never
committed, to make every tile 200 pixels too wide after the layout is calculated, so that tiles
overlap. `core-e2e` failed 7 checks and passed 139: the overlap checks of the suite's own first
tiling and of the `tiling` scenario (two each), the one in the suite that says two windows share
the screen again after a close, and the "not on each other" checks of `stacks` and of `closing`
or `lifecycle`. Nothing else turned red, so the checks name what
is wrong.
The same mutation on kfw, in a scratch worktree of `0ffc502c`: all 14 scenarios ran on restored
guests and 65 checks failed, every one of them about geometry: windows inside the work area, not
on each other, tiles sharing an edge (the precondition of `resize`), and each of the eight
`change-layout` lines of the `commands` sweep. `rules` (9) and `placement` (4) stayed green,
because they only check the order of windows. Nothing else turned red.
## What is not covered
- Pointer input on a second display, on Windows (kfw). `has("pointer")` is true, but the pointer
is QMP's absolute tablet, which Windows maps onto the first display only: with a second display
at (1280, 0) the whole tablet range gave cursor x 0..1279. A scenario that drags across monitors,
or acts on a second display with the pointer, cannot run there; none exists. Source: kfw's
`e2e/platforms/qemu_windows/W1.md`, "The pointer with two displays".
- Suspend and resume, which no guest can test.
- `commands` on kfw under load: it passed 247/0 in the two of four repeat runs that had the host
to themselves, and the two that ran beside a VM suite and a build failed, with `komorebic state`
replies slowing from milliseconds to about a second. Load is the likely cause, not shown.
- Most of what is particular to one port: kfw's cloak and borders, kfde's parking desktop and
KWin effects. Those stay in the suites of each port.
+833
View File
@@ -0,0 +1,833 @@
# komorebi for KDE Plasma compared with komorebi for Windows and for macOS
> **STALE (snapshot of 2026-10-27, kfw 173aa802, kfm 125a9a5):** this comparison predates the consolidation. The three programs now share `crates/` (protocol, config, collections, transport, backend, core, settings, komorebic-core) and one `komorebi`, `komorebic`, `komorebi-client` and `komorebi-bar` package, so counts of duplicated commands, messages and keys below are out of date, and `scripts/compare-gen.py` no longer runs against the current tree (it fails with `cannot find '^enum SubCommand'`, because the command definitions moved to `crates/komorebic-core`). For what is shared and what differs on purpose now, read the repository-level [docs/dev/ARCHITECTURE-UNIFIED.md](../../../docs/dev/ARCHITECTURE-UNIFIED.md) and [docs/dev/core-model.md](../../../docs/dev/core-model.md). The platform-difference tables (KWin versus Win32 versus AppKit mechanisms) remain a fair description of the platform layers.
This document compares komorebi for KDE Plasma on KWin and Wayland (kfde) with komorebi for
Windows (kfw), the original, and komorebi for macOS (kfm). It is written for a reader who knows
komorebi on one of those two systems and wants to know what is the same on KDE, what is different,
what KDE does by itself that komorebi does on the other systems, and what is not supported.
It states facts that can be checked against the code, and does not assign value judgments. "kfw
draws the borders itself and kfde asks the compositor to" is a fact. "The compositor's borders are
better" is not, and is not said here. The reasons behind kfde's choices are in
[DESIGN.md](DESIGN.md), where they are opinions and say so.
It is written for kfde, so it leans toward kfde, and it was written from the sources of the three
programs, not from running them side by side. Where something could not be verified, it says so.
A correction is welcome.
## How to read this document
Every table in a marked block is generated by `scripts/compare-gen.py` from the source trees
of the three programs, so a count or a name in it is what the code had when the block was last
generated. The text around the tables is written by hand and states what the tables say.
```sh
python3 -I scripts/compare-gen.py --update docs/dev/COMPARE.md # rewrite the blocks
python3 -I scripts/compare-gen.py --check docs/dev/COMPARE.md # exit 1 when one is stale
```
The script reads this checkout and checkouts of [kfw](https://github.com/LGUG2Z/komorebi) and
[kfm](https://github.com/LGUG2Z/komorebi-for-mac) (`~/komorebi` and `~/komorebi-for-mac` by
default; `--kfw` and `--kfm` name others). Continuous integration has neither checkout, so it
does not run the script: a change to a command, a message, a key of `komorebi.json`, an event or
a method of `Backend` is followed by `--check` on a machine that has them, and by `--update` and
a read of the text around the block when it reports a stale one. The script also checks the
hand-written notes it holds (why a Windows command has no counterpart, which KWin call stands in
for a Win32 one) against the sources, and the sentences of this document that depend on a
generated fact, and stops on a note or a sentence that is no longer true. The revisions it read
are:
<!-- gen:sources -->
| Name | What | Read from | Revision |
|---|---|---|---|
| kfw | komorebi for Windows, the upstream | `~/komorebi` | 173aa802, 2026-10-27 |
| kfm | komorebi for macOS | `~/komorebi-for-mac` | 125a9a5, 2026-10-27 |
| kfde | this project | this repository | the commit that has this document |
<!-- /gen:sources -->
kfm changes often, so the numbers for kfm in particular are those of that revision.
Terms used below:
- **KWin's script** (the bridge) is a small JavaScript program that komorebi loads into KWin. It is
the only code of kfde that runs inside the compositor, and it contains no window manager logic.
- **A workspace** is komorebi's name for one of the desktops of a monitor, in all three programs.
- **A parking desktop** is a KWin virtual desktop that nobody looks at, which kfde moves windows to
in order to hide them.
- **The strip** is the scrolling layout of kfm, in the crate `komorebi-scrolling`. Since upstream's
`next` branch it is also what the `Scrolling` layout of `komorebi-layouts` is laid out with, in
kfde too ([scrolling-next.md](scrolling-next.md)).
## What is the same
### One tiling model, and the same layouts
The model is the same in all three programs: a list of monitors, each with workspaces, each with
containers, each with windows. kfde adds no layer to it. The layouts come from the crate
`komorebi-layouts`, which kfw owns and kfm and kfde use as a git dependency:
<!-- gen:layouts -->
| `DefaultLayout` | kfw | kfm | kfde |
|---|---|---|---|
| `BSP` | yes | yes | yes |
| `Columns` | yes | yes | yes |
| `Rows` | yes | yes | yes |
| `VerticalStack` | yes | yes | yes |
| `HorizontalStack` | yes | yes | yes |
| `UltrawideVerticalStack` | yes | yes | yes |
| `Grid` | yes | yes | yes |
| `RightMainVerticalStack` | yes | yes | yes |
| `Scrolling` | yes | yes | yes |
The crate each tree builds: kfw: `komorebi-layouts` in the tree; kfm: `komorebi-layouts` at git rev `f08aa55`; kfde: `komorebi-layouts` at git rev `f08aa55`.
Compared file by file with the crate of kfw, kfm: 0 of 13 source files differ from the ones of kfw; kfde: 0 of 13 source files differ from the ones of kfw.
<!-- /gen:layouts -->
The layouts of `komorebi-layouts` are calculated by the same code in the three programs, so the same
windows in the same order get the same rectangles, apart from what the window manager takes off for
the work area, the padding and the borders. The exception is the `Scrolling` layout, which is laid
out with the strip of `komorebi-scrolling` in kfm and in kfde, and not in kfw before its `next`
branch (see the section on configuration). What differs between the programs is
what the system does with the rectangles: the next sections.
### One configuration file, largely portable
A `komorebi.json` written for kfw or kfm loads in kfde. The keys that kfde does not read are
accepted and ignored, not rejected. The tables of the sections on configuration say which keys
those are, and why.
## Commands
`komorebic` has the same shape in the three programs: a command writes a message on the socket of the
daemon, and the message is a variant of the `SocketMessage` of `komorebi-client`. A command's name is
the variant of `SubCommand` in kebab case, which is what the pages of `docs/cli` are named after.
<!-- gen:commands-counts -->
| | kfw | kfm | kfde |
|---|---|---|---|
| Commands `komorebic` has | 192 | 158 | 158 |
| In all three | 148 | 148 | 148 |
| Also in kfw, not in kfm | 7 | - | 7 |
| Also in kfm, not in kfw | - | 1 | 1 |
| Only in kfde | - | - | 2 |
| In kfw or kfm, not in kfde | 37 | 9 | - |
| Same command under another name | - | - | 0 |
<!-- /gen:commands-counts -->
No command of kfw or kfm is kept in kfde under another name, not even as an alias.
### kfde has the commands kfw and kfm share
These commands exist in all three programs, with the same name. The ones that the tiling and the
workspaces are driven with do the same on KDE; where they do it differently (a workspace is a KWin
desktop) the section on workspaces says how.
<!-- gen:commands-all3 -->
`adjust-container-padding`, `adjust-workspace-padding`, `animation`, `animation-duration`, `animation-fps`, `animation-style`, `application-specific-configuration-schema`, `border`, `border-colour`, `border-offset`, `border-width`, `cancel-preselect`, `change-layout`, `clear-all-workspace-rules`, `clear-named-workspace-layout-rules`, `clear-named-workspace-rules`, `clear-session-float-rules`, `clear-workspace-layout-rules`, `clear-workspace-rules`, `close`, `close-workspace`, `configuration`, `container-padding`, `cross-monitor-move-behaviour`, `cycle-empty-workspace`, `cycle-focus`, `cycle-layout`, `cycle-monitor`, `cycle-move`, `cycle-move-to-monitor`, `cycle-move-to-workspace`, `cycle-move-workspace-to-monitor`, `cycle-send-to-monitor`, `cycle-send-to-workspace`, `cycle-stack`, `cycle-stack-index`, `cycle-workspace`, `data-directory`, `disable-autostart`, `display-index-preference`, `docgen`, `eager-focus`, `enable-autostart`, `enforce-workspace-rules`, `ensure-named-workspaces`, `ensure-workspaces`, `flip-layout`, `focus`, `focus-last-workspace`, `focus-monitor`, `focus-monitor-at-cursor`, `focus-monitor-workspace`, `focus-named-workspace`, `focus-stack-window`, `focus-workspace`, `focus-workspaces`, `focused-workspace-container-padding`, `focused-workspace-padding`, `generate-static-config`, `global-state`, `global-work-area-offset`, `ignore-rule`, `initial-named-workspace-rule`, `initial-workspace-rule`, `layout-ratios`, `load-resize`, `log`, `manage`, `manage-rule`, `minimize`, `monitor-information`, `monitor-work-area-offset`, `monocle-focus-behaviour`, `mouse-follows-focus`, `move`, `move-to-last-workspace`, `move-to-monitor`, `move-to-monitor-workspace`, `move-to-named-workspace`, `move-to-workspace`, `move-workspace-to-monitor`, `named-workspace-container-padding`, `named-workspace-layout`, `named-workspace-layout-rule`, `named-workspace-padding`, `named-workspace-rule`, `named-workspace-tiling`, `new-workspace`, `notification-schema`, `preselect-direction`, `promote`, `promote-focus`, `promote-swap`, `promote-window`, `query`, `quick-load-resize`, `quick-save-resize`, `quickstart`, `replace-configuration`, `resize-axis`, `resize-delta`, `resize-edge`, `retile`, `save-resize`, `scrolling-layout-columns`, `send-to-last-workspace`, `send-to-monitor`, `send-to-monitor-workspace`, `send-to-named-workspace`, `send-to-workspace`, `session-float-rule`, `session-float-rules`, `socket-schema`, `stack`, `stack-all`, `start`, `state`, `static-config-schema`, `stop`, `subscribe-socket`, `swap-workspaces-with-monitor`, `toggle-cross-monitor-move-behaviour`, `toggle-float`, `toggle-float-override`, `toggle-lock`, `toggle-monocle`, `toggle-monocle-focus-behaviour`, `toggle-mouse-follows-focus`, `toggle-pause`, `toggle-tiling`, `toggle-window-based-work-area-offset`, `toggle-window-container-behaviour`, `toggle-workspace-float-override`, `toggle-workspace-layer`, `toggle-workspace-window-container-behaviour`, `unmanage`, `unmanaged-window-operation-behaviour`, `unstack`, `unstack-all`, `unsubscribe-socket`, `visible-windows`, `workspace-layout`, `workspace-layout-rule`, `workspace-name`, `workspace-padding`, `workspace-rule`, `workspace-tiling`, `workspace-work-area-offset`
<!-- /gen:commands-all3 -->
### kfde has the commands kfw has and kfm lacks, for the features it took from kfw
kfm has no counterpart for these. kfde has them because it has the feature:
<!-- gen:commands-adopted -->
| Command | What the help of kfw says |
|---|---|
| `check` | Check komorebi configuration and related files for common errors |
| `focus-follows-mouse` | Enable or disable focus follows mouse for the operating system |
| `toggle-focus-follows-mouse` | Toggle focus follows mouse for the operating system |
| `toggle-maximize` | Toggle native maximization for the focused window |
| `toggle-transparency` | Toggle transparency for unfocused windows |
| `transparency` | Enable or disable transparency for unfocused windows |
| `transparency-alpha` | Set the alpha value for unfocused window transparency |
<!-- /gen:commands-adopted -->
`focus-follows-mouse` and `toggle-focus-follows-mouse` are hidden from `--help` in kfw and kfde
alike.
### kfde has the command kfm has and kfw lacks
<!-- gen:commands-kfm -->
| Command | What it does |
|---|---|
| `completions` | Generate komorebic CLI completions for the target shell |
<!-- /gen:commands-kfm -->
### kfde has commands that neither has
These commands are about KDE: a key binding file is turned into KDE's global shortcuts, and the
keys the daemon registers itself are looked at and let go.
<!-- gen:commands-kde -->
| Command | What it does |
|---|---|
| `export-kde-shortcuts` | Turn an skhdrc into KDE global shortcuts (they work over RDP, unlike evdev hotkey daemons) |
| `hotkeys` | Key bindings: KDE global shortcuts from a key binding file, and the keys of the daemon |
<!-- /gen:commands-kde -->
[The user guide on key bindings](../usage/keybindings.md) describes them. `hotkeys` has
subcommands: `komorebic hotkeys compile` does what `export-kde-shortcuts` does for all three
formats, and `state`, `reload` and `release` act on the keys the daemon has registered.
### kfde does not start helper programs
`komorebic start` of kfw can start whkd, AutoHotkey, the bar and masir along with the daemon. In
kfde the daemon reads the key binding files itself and there is no bar, so `start` has one flag the
others share and none of the flags that launch another program:
<!-- gen:commands-flags -->
| Command | Flag | kfw | kfm | kfde |
|---|---|---|---|---|
| `start` | `--ahk` | yes | - | - |
| `start` | `--await-configuration` | yes | - | - |
| `start` | `--bar` | yes | yes | - |
| `start` | `--clean-state` | yes | - | - |
| `start` | `--config` | yes | yes | yes |
| `start` | `--ffm` | yes | - | - |
| `start` | `--masir` | yes | - | - |
| `start` | `--tcp-port` | yes | - | - |
| `start` | `--whkd` | yes | - | - |
| `stop` | `--ahk` | yes | - | - |
| `stop` | `--bar` | yes | yes | - |
| `stop` | `--ignore-restore` | yes | yes | yes |
| `stop` | `--masir` | yes | - | - |
| `stop` | `--whkd` | yes | - | - |
| `check` | `--configuration-only` | - | no command | yes |
| `check` | `--komorebi-config` | yes | no command | yes |
<!-- /gen:commands-flags -->
### kfde has no counterpart for these commands
Every command that kfw or kfm has and kfde lacks is here, with the reason. A group that is a
"Win32 quirk" is a workaround for how Windows treats windows, which a Wayland compositor does not
need.
<!-- gen:commands-missing -->
| Group | Command | In | Why kfde has no counterpart |
|---|---|---|---|
| AutoHotkey and PowerShell | `ahk-app-specific-configuration` | kfw | Writes application rules for `komorebi.ahk`. |
| AutoHotkey and PowerShell | `complete-configuration` | kfw | Part of the legacy `komorebi.ahk` and `komorebi.ps1` configurations. |
| AutoHotkey and PowerShell | `pwsh-app-specific-configuration` | kfw | Writes application rules for a PowerShell script. |
| AutoHotkey and PowerShell | `reload-configuration` | kfw | Part of the legacy `komorebi.ahk` and `komorebi.ps1` configurations. |
| AutoHotkey and PowerShell | `watch-configuration` | kfw | Part of the legacy `komorebi.ahk` and `komorebi.ps1` configurations. `komorebi.json` is watched always. |
| Win32 quirks | `alt-focus-hack` | kfw | Works around the rules Windows has for taking the foreground. |
| Win32 quirks | `force-focus` | kfw | Works around the rules Windows has for taking the foreground. |
| Win32 quirks | `identify-layered-application` | kfw | A Win32 window style. There is no counterpart in a Wayland compositor. |
| Win32 quirks | `identify-object-name-change-application` | kfw | A Win32 event some applications send on launch. |
| Win32 quirks | `identify-tray-application` | kfw | A Win32 notion: an application that closes to the system tray. |
| Windows tooling | `bar-configuration` | kfw | `komorebi-bar` is not ported: the Plasma panel is used, and the work area accounts for it. |
| Windows tooling | `gui` | kfw | Launches `komorebi-gui`, which is not ported. |
| Windows tooling | `kill` | kfw | Stops the helper programs `komorebic start` launches on Windows (whkd, AutoHotkey, the bar, masir). It launches none on KDE. |
| Windows tooling | `toggle-shortcuts` | kfw | Toggles `komorebi-shortcuts`, which is not ported. |
| Windows tooling | `whkdrc` | kfw | Shows the path of the whkd file. The daemon reads key binding files itself. |
| borders | `border-implementation` | kfw | How a Win32 border window is drawn. The compositor draws the border. |
| borders | `border-style` | kfw | How a Win32 border window is drawn. The compositor draws the border. |
| borders | `identify-border-overflow-application` | kfw | A border window that overflows is a Win32 problem. The compositor draws the border. |
| borders | `invisible-borders` | kfw | The size of the invisible frame Windows adds around a window. |
| custom layouts | `load-custom-layout` | kfw | Not supported yet. |
| custom layouts | `named-workspace-custom-layout-rule` | kfw | Not supported yet. |
| custom layouts | `named-workspace-custom-layout` | kfw | Not supported yet. |
| custom layouts | `workspace-custom-layout-rule` | kfw | Not supported yet. |
| custom layouts | `workspace-custom-layout` | kfw | Not supported yet. |
| hiding | `restore-windows` | kfw | Debugging command for windows komorebi hid itself. On KDE `stop` and the next start send parked windows home. |
| hiding | `window-hiding-behaviour` | kfw | One native mechanism hides windows, so there is nothing to choose. |
| kfm scrolling strip | `center-focus` | kfm | Belongs to the scrolling strip of kfm (`komorebi-scrolling`). The Scrolling layout of kfde is the one of `komorebi-layouts`. |
| kfm scrolling strip | `consume` | kfm | Belongs to the scrolling strip of kfm (`komorebi-scrolling`). |
| kfm scrolling strip | `expel` | kfm | Belongs to the scrolling strip of kfm (`komorebi-scrolling`). |
| kfm scrolling strip | `scrolling-layout-full-width` | kfm | Belongs to the scrolling strip of kfm (`komorebi-scrolling`). |
| kfm scrolling strip | `toggle-column-stack` | kfm | Belongs to the scrolling strip of kfm (`komorebi-scrolling`). |
| license | `license` | kfw and kfm | No license check was ported. |
| license | `splash` | kfw and kfm | No splash screen was ported. |
| macOS | `permissions` | kfm | Shows the System Settings dialogs macOS asks for. KDE asks for none. |
| monitors | `monitor-index-preference` | kfw | Identifies a monitor by its size. kfde has `display-index-preference`, which names the display, as kfm does. |
| named pipes | `subscribe-pipe` | kfw | A named pipe is a Windows facility. Subscribers use a Unix domain socket. |
| named pipes | `unsubscribe-pipe` | kfw | A named pipe is a Windows facility. Subscribers use a Unix domain socket. |
| stackbar | `stackbar-mode` | kfw | komorebi draws the tab bar of a stack on Windows. KDE has no counterpart; a stack is cycled with `cycle-stack` and `focus-stack-window`. |
| title bars | `remove-title-bar` | kfw | A window without a title bar has no shadow in KWin, and so no border. |
| title bars | `toggle-title-bars` | kfw | A window without a title bar has no shadow in KWin, and so no border. |
| upstream applications file | `convert-app-specific-configuration` | kfw | Maintains the YAML file of the Windows applications list. |
| upstream applications file | `fetch-app-specific-configuration` | kfw and kfm | Not supported yet: there is no applications file for KDE upstream, so there is nothing to fetch. |
| upstream applications file | `format-app-specific-configuration` | kfw | Maintains the YAML file of the Windows applications list. |
<!-- /gen:commands-missing -->
The groups "hiding", "borders" and "title bars" are Windows workarounds that KDE does natively,
which is the reason the project recorded when it decided not to port them
([DESIGN.md](DESIGN.md#what-is-komorebi-for-kde-the-port-of)). The other reasons say what the code
of kfw and kfm shows each command is for. For "upstream applications file": at time of writing
(2026-10-28) no applications file for KDE exists upstream, so `fetch-app-specific-configuration`
has nothing to fetch. The configuration key that points at a file of application rules works (see
the section on keys), and the user supplies the file.
## The socket protocol
The messages that `komorebi-client` sends are the variants of `SocketMessage`. The counts follow
the ones of the commands, since nearly every command is one message.
<!-- gen:messages-counts -->
| | kfw | kfm | kfde |
|---|---|---|---|
| `SocketMessage` variants | 187 | 153 | 156 |
| In all three | 148 | 148 | 148 |
| In kfde and kfw, not kfm | 6 | - | 6 |
| In kfde and kfm, not kfw | - | 0 | 0 |
| Only in kfde | - | - | 2 |
| In kfw or kfm, not in kfde | 33 | 5 | - |
<!-- /gen:messages-counts -->
Of the messages kfde has, these are not in both of the other programs:
<!-- gen:messages-only -->
- Only in kfde: `HotkeysState`, `ReloadHotkeys`.
- In kfde and kfw, not in kfm: `FocusFollowsMouse`, `ToggleFocusFollowsMouse`, `ToggleMaximize`, `ToggleTransparency`, `Transparency`, `TransparencyAlpha`.
- In kfde and kfm, not in kfw: none.
<!-- /gen:messages-only -->
The two messages that only kfde has are the ones behind `komorebic hotkeys state` and
`komorebic hotkeys reload`. The names of the variants are the same in the programs that share them.
Whether every variant has the same payload in the three programs was not compared. Subscribers use
a Unix domain socket, as in kfm and, next to named pipes, in kfw.
## Configuration
### kfde reads the keys of komorebi.json that both others read
The counts, by struct of `static_config.rs`. "Not read by kfde" is the number of keys that kfw or
kfm has and kfde does not:
<!-- gen:keys-counts -->
| Struct | kfw | kfm | kfde | All three | kfw and kfde | kfm and kfde | kfde only | Not read by kfde |
|---|---|---|---|---|---|---|---|---|
| `StaticConfig` (top level) | 53 | 34 | 37 | 30 | 4 | 3 | 0 | 20 |
| `WorkspaceConfig` (workspace) | 22 | 19 | 20 | 19 | 1 | 0 | 0 | 2 |
| `MonitorConfig` (monitor) | 8 | 9 | 9 | 8 | 0 | 1 | 0 | 0 |
| Total | 83 | 62 | 66 | 57 | 5 | 4 | 0 | 22 |
<!-- /gen:keys-counts -->
The keys that kfw, kfm and kfde all read, which mean the same, apart from what the next
sections say:
<!-- gen:keys-same -->
- top level (`StaticConfig`): `animation`, `app_specific_configuration_path`, `border`, `border_colours`, `border_offset`, `border_width`, `cross_boundary_behaviour`, `cross_monitor_move_behaviour`, `default_container_padding`, `default_workspace_padding`, `display_index_preferences`, `float_override`, `float_override_placement`, `float_rule_placement`, `floating_applications`, `floating_layer_behaviour`, `floating_layer_placement`, `floating_window_aspect_ratio`, `global_work_area_offset`, `ignore_rules`, `layout_defaults`, `manage_rules`, `monitors`, `monocle_focus_behaviour`, `mouse_follows_focus`, `resize_delta`, `theme`, `toggle_float_placement`, `unmanaged_window_operation_behaviour`, `window_container_behaviour`.
- workspace (`WorkspaceConfig`): `apply_window_based_work_area_offset`, `container_padding`, `float_override`, `floating_layer_behaviour`, `initial_workspace_rules`, `layout`, `layout_flip`, `layout_options`, `layout_options_rules`, `layout_rules`, `name`, `tile`, `wallpaper`, `window_container_behaviour`, `window_container_behaviour_rules`, `work_area_offset`, `work_area_offset_rules`, `workspace_padding`, `workspace_rules`.
- monitor (`MonitorConfig`): `container_padding`, `floating_layer_behaviour`, `wallpaper`, `window_based_work_area_offset`, `window_based_work_area_offset_limit`, `work_area_offset`, `workspace_padding`, `workspaces`.
<!-- /gen:keys-same -->
### kfde reads keys from kfw and keys from kfm
kfde reads the keys kfw has for the features it took from kfw, and the ones kfm has that kfw does
not:
<!-- gen:keys-adopted -->
| Key | Level | Also in | What it is |
|---|---|---|---|
| `focus_follows_mouse` | top level | kfw | Focus the window under the pointer. |
| `transparency` | top level | kfw | Add transparency to unfocused windows (default: false) |
| `transparency_alpha` | top level | kfw | Alpha value for unfocused window transparency [[0-255]] (default: 200) |
| `transparency_ignore_rules` | top level | kfw | Individual window transparency ignore rules |
| `border_radius` | top level | kfm | Radius of window borders |
| `tabbed_applications` | top level | kfm | Accepted so that a configuration written for another platform loads, and ignored: a KWin window has no native tabs |
| `titleless_applications` | top level | kfm | Accepted so that a configuration written for another platform loads, and ignored: a KWin window is always a window |
| `initial_window_placement_rules` | workspace | kfw | Initial window placement rules that determine where new tiled windows are placed in the container list. |
| `window_hiding_position` | monitor | kfm | Accepted so that a configuration written for another platform loads, and ignored: there is no hiding position on KDE Plasma |
<!-- /gen:keys-adopted -->
### No key of komorebi.json is read only on KDE
<!-- gen:keys-kde-only -->
none
<!-- /gen:keys-kde-only -->
That is by decision: a file should load on every platform that has the feature
([why](DESIGN.md#why-does-one-komorebijson-work-on-every-platform)). The keys that mean something
else on KDE, or do less, are these:
<!-- gen:keys-differ -->
| Key | Level | What is different on KDE |
|---|---|---|
| `border_width` | top level | At most 20 px: the effect draws the ring in the window's shadow, and a window without a shadow has none. While borders are drawn, the layout leaves `border_width` plus `border_offset` on each side of a window, also past 20. |
| `border_colours` | top level | Six colors, one for each kind of window, when komorebi's build of the border effect is installed. With the stock effect only `single` and `unfocused` take effect, and komorebi says so once in its log. |
| `animation` | top level | `style` is the Qt easing curve of that name (`EaseInOutSine` is `InOutSine`) and a custom cubic Bezier curve is an ease out, when komorebi's build of the Geometry Change effect is installed; the stock effect always eases out exponentially. `fps` is read and ignored: the compositor animates at the refresh rate of the screen. |
| `focus_follows_mouse` | top level | Both implementations kfw names (`Windows` and `Komorebi`) ask KWin for the same thing: its focus policy, put back as the user had it when it is turned off or komorebi exits. |
| `transparency` | top level | KWin's window opacity, set for the unfocused windows of each monitor's shown workspace by kfw's rules (the focused window and a monocled one stay opaque). |
| `theme` | top level | A theme by name or a palette of your own gives the six border colors, and the palette of a wallpaper takes over from it when its workspace is shown. |
| `wallpaper` | workspace | Set through the Plasma shell, which keeps one wallpaper for each screen and not for each desktop, so komorebi changes it as the workspace in front changes. The picture fills the screen. |
| `workspaces` | monitor | Workspace `i` is KWin's desktop `i` on every monitor, so every monitor has as many desktops as the largest workspace count, and where the names differ the desktop takes the first monitor's. |
| `app_specific_configuration_path` | top level | Read as in kfm and kfw. There is no applications file for KDE upstream, so komorebi has none to download. |
<!-- /gen:keys-differ -->
### Some keys are read and do nothing on KDE
They are read so that a file written for another platform loads, and `komorebic check` lists them
once as accepted and ignored:
<!-- gen:keys-no-effect -->
| Key | Level | Also in | Effect on KDE |
|---|---|---|---|
| `tabbed_applications` | top level | kfm | Read, so that a file written for kfm loads, and does nothing on KDE. |
| `titleless_applications` | top level | kfm | Read, so that a file written for kfm loads, and does nothing on KDE. |
| `window_hiding_position` | monitor | kfm | Read, so that a file written for kfm loads, and does nothing on KDE. |
| `animation.fps` | nested | kfw, kfm | Read, and ignored: the compositor animates at the refresh rate of the screen. |
<!-- /gen:keys-no-effect -->
### Some keys are not read at all
These are keys of kfw or kfm that kfde does not have. They are not an error: serde skips a key it
does not know, so the file loads, and `komorebic check` tells them apart from a typo.
<!-- gen:keys-not-read -->
| Key | Level | In | Why kfde does not read it |
|---|---|---|---|
| `bar_configurations` | top level | kfw | `komorebi-bar` is not ported. |
| `border_implementation` | top level | kfw | How a Win32 border window is drawn. The compositor draws the border. |
| `border_overflow_applications` | top level | kfw | How a Win32 border window is drawn. The compositor draws the border. |
| `border_style` | top level | kfw | How a Win32 border window is drawn. The compositor draws the border. |
| `border_z_order` | top level | kfw | How a Win32 border window is drawn. The compositor draws the border. |
| `invisible_borders` | top level | kfw | The size of the invisible frame Windows adds around a window. |
| `layered_applications` | top level | kfw | A Win32 window style. There is no counterpart in a Wayland compositor. |
| `minimum_window_height` | top level | kfw | Marked DISCOURAGED in komorebi for Windows. Commented out in kfde. |
| `minimum_window_width` | top level | kfw | Marked DISCOURAGED in komorebi for Windows. Commented out in kfde. |
| `monitor_index_preferences` | top level | kfw | Identifies a monitor by its size. kfde reads `display_index_preferences`, which names the display, as kfm does. |
| `object_name_change_applications` | top level | kfw | A Win32 event some applications send on launch. |
| `object_name_change_title_ignore_list` | top level | kfw | A Win32 event some applications send on launch. |
| `remove_titlebar_applications` | top level | kfw | A window without a title bar has no shadow in KWin, and so no border. |
| `scrolling` | top level | kfm | The `ScrollingConfig` of the strip in kfm (`komorebi-scrolling`). kfde has the Scrolling layout of `komorebi-layouts`, tuned with `layout_options`. |
| `slow_application_compensation_time` | top level | kfw | A Win32 workaround for applications that are slow to move. |
| `slow_application_identifiers` | top level | kfw | A Win32 workaround for applications that are slow to move. |
| `stackbar` | top level | kfw | KDE has no counterpart of the tab bar komorebi draws on Windows. |
| `tray_and_multi_window_applications` | top level | kfw | A Win32 notion: an application that closes to the system tray. |
| `window_handling_behaviour` | top level | kfw | A Win32 quirk of how windows are moved. |
| `window_hiding_behaviour` | top level | kfw | One native mechanism hides windows, so there is nothing to choose. |
| `custom_layout` | workspace | kfw | Custom layouts are not supported yet. |
| `custom_layout_rules` | workspace | kfw | Custom layouts are not supported yet. |
<!-- /gen:keys-not-read -->
The nested structs have the same keys, except for these:
<!-- gen:keys-nested -->
| Struct | kfw | kfm | kfde | In kfw, not kfde | In kfm, not kfde |
|---|---|---|---|---|---|
| `BorderColours` | 6 | 6 | 6 | - | - |
| `ThemeOptions` | 11 | 8 | 8 | `stackbar_background`, `stackbar_focused_text`, `stackbar_unfocused_text` | - |
| `Wallpaper` | 3 | 3 | 3 | - | - |
| `AnimationsConfig` | 5 | 4 | 4 | `ghost_movement` | - |
<!-- /gen:keys-nested -->
There is one more difference that is not a key. kfm has a `scrolling` key. kfde has the `Scrolling`
layout of `komorebi-layouts`, which is laid out with the same strip as kfm's, with columns that hold
several windows and the commands `consume`, `expel`, `toggle-column-stack`,
`scrolling-layout-full-width`, `center-focus`, `expand` and `pan`, and is tuned with
`layout_options` and the command `scrolling-layout-columns`, which kfw and kfm have too. A
`scrolling` key in a file written for kfm is skipped by kfde. The generated tables above were made
before kfde took these commands: `scripts/compare-gen.py --update` makes them again.
## Events, and what drives them
The window manager reacts to events about windows. In kfw the operating system raises them, through
`SetWinEventHook`, and in kfm through the accessibility API and the notification center. In kfde
the script in KWin connects to the signals of KWin's `workspace` and of each window and sends every
one to the daemon as a JSON string over D-Bus. The daemon turns a signal into a
`WindowManagerEvent`, the way kfw and kfm turn what they get.
<!-- gen:event-sources -->
| Tree | What the OS layer reports | Kinds |
|---|---|---|
| kfw | `WinEvent`, the events of `SetWinEventHook` | 84 |
| kfm | `AccessibilityNotification` and `AppKitWorkspaceNotification` | 41 and 21 |
| kfde | `KWinNotification`, the signals of the KWin script | 16 |
<!-- /gen:event-sources -->
The events follow kfw's model: each is about a window, and a window is a small `Copy` handle. kfm's
events carry a process id and a window id instead. The table puts the events of kfde next to the
ones of the other two that play the same part:
<!-- gen:events -->
| kfde event | Source on KDE | kfw | kfm |
|---|---|---|---|
| `Show` | `workspace.windowAdded` | `Show`, `Uncloak` | `Show` |
| `Destroy` | `workspace.windowRemoved` | `Destroy` | `Destroy` |
| `FocusChange` | `workspace.windowActivated` | `FocusChange`, `Raise` | `FocusChange` |
| `Minimize` | `window.minimizedChanged`, to true | `Minimize` | `Minimize` |
| `Restore` | `window.minimizedChanged`, to false | - | `Restore` |
| `TitleUpdate` | `window.captionChanged` | `TitleUpdate` | - |
| `Manage` | komorebi itself (`manage`, a rule) | `Manage` | `Manage` |
| `Unmanage` | komorebi itself (`unmanage`, a rule) | `Unmanage` | `Unmanage` |
| `MoveStart` | `window.interactiveMoveResizeStarted`, for a move | `MoveResizeStart` | `MoveStart` |
| `MoveEnd` | `window.interactiveMoveResizeFinished`, after a move | `MoveResizeEnd` | `MoveEnd` |
| `ResizeStart` | `window.interactiveMoveResizeStarted`, for a resize | `MoveResizeStart` | `ResizeStart` |
| `ResizeEnd` | `window.interactiveMoveResizeFinished`, after a resize | `MoveResizeEnd` | `ResizeEnd` |
| `ResizeStep` | `window.interactiveMoveResizeStepped` | - | - |
| `WorkspaceChange` | `workspace.currentDesktopChanged` | - | `SpaceChange` |
| `WorkspaceMove` | `window.desktopsChanged` | - | - |
| `OutputChange` | `window.outputChanged` | - | - |
| `MaximizeChange` | `window.maximizedChanged` | - | - |
| `FullscreenChange` | `window.fullScreenChanged` | - | - |
| Event with no counterpart in kfde | In | Why |
|---|---|---|
| `Hide` | kfw | Win32 hides and cloaks windows; kfde has no counterpart because KWin shows and hides windows by desktop, and says so with `WorkspaceChange`. |
| `Cloak` | kfw | Win32 hides and cloaks windows; kfde has no counterpart because KWin shows and hides windows by desktop, and says so with `WorkspaceChange`. |
| `MouseCapture` | kfw | Windows tells komorebi that a mouse button went down on a window. KWin reports the start of a move or resize instead. |
| `ScreenLock` | kfm | KDE locks and unlocks the screen with `org.freedesktop.ScreenSaver`; komorebi hears it in `kwin/power.rs` and reconciles, with no event of this kind. |
| `ScreenUnlock` | kfm | KDE locks and unlocks the screen with `org.freedesktop.ScreenSaver`; komorebi hears it in `kwin/power.rs` and reconciles, with no event of this kind. |
<!-- /gen:events -->
Three things about this are worth knowing:
- A signal reaches the daemon in 0 to 1 ms, from `Date.now()` in the script to the receipt in the
daemon ([the spikes](PLATFORM.md#vocabulary), 2026-10-26, KWin 6.8.1 in a virtual machine on
HVF).
- KWin emits `windowActivated` before `windowAdded` for a new window, so the script announces the
window from the activation, and no event mentions a window before the event that adds it.
- The script contains no logic. [Why](DESIGN.md#why-does-the-bridge-hold-no-logic) and
[why the commands come back to the script as the answer to a held call](DESIGN.md#why-do-commands-go-to-the-bridge-as-the-answer-to-a-held-call)
are in DESIGN.md.
### What the operating system layer is
kfw calls Win32 from `WindowsApi`, kfm calls the accessibility API and Core Graphics from
`MacosApi` and its modules. kfde puts the whole of what the window manager needs behind one trait,
`Backend`, which a test replaces with `FakeBackend` (a desktop in memory). The sizes are not a
measure of the effort: the Win32 and macOS calls are scattered over more modules than the ones the
counts name.
<!-- gen:backend-counts -->
| Tree | The operating system layer | Size |
|---|---|---|
| kfw | `WindowsApi` in `windows_api.rs` | 92 public functions |
| kfm | `MacosApi` in `macos_api.rs`, and the `accessibility`, `core_graphics` and `skylight` modules | 14 public functions in `MacosApi` |
| kfde | `Backend`, with `FakeBackend` for tests and `KWinBackend` for KWin | 31 methods (27 are required, 4 are provided), and a script of 684 lines that runs inside KWin |
<!-- /gen:backend-counts -->
What each method of `Backend` is on KDE, and the function of kfw and kfm that does the same job,
where there is one:
<!-- gen:backend -->
| `Backend` method | On KDE | kfw function | kfm function |
|---|---|---|---|
| `windows` | `workspace.windowList()` once, then the events of the bridge | `enum_windows` | `window_elements` |
| `window` | the table the bridge keeps, fed by events | `window_rect`, `exe_path` | `window_by_title` |
| `foreground_window` | `workspace.activeWindow` | `foreground_window` | `foreground_window` |
| `monitors` | `workspace.screens` and `clientArea(KWin.PlacementArea, ...)`, which leaves out the panel | `load_monitor_information` | `load_monitor_information` |
| `cursor_pos` | `workspace.cursorPos` | `cursor_pos` | `cursor_pos` |
| `drag_origin` | the frame the bridge saw at `interactiveMoveResizeStarted` | none | none |
| `drag_end` | the frame the bridge saw at the last `interactiveMoveResizeStepped` | none | none |
| `set_rect` | `frameGeometry`, and a second request for the position once the size settles | `position_window` | `set_position` |
| `focus` | `workspace.activeWindow = w` | `raise_and_focus_window` | `focus` |
| `raise` | `workspace.raiseWindow(w)` | `raise_window` | `raise` |
| `hide` | moves the window to the parking desktop (`desktops`) | `hide_window` | `hide` |
| `restore` | moves the window back from the parking desktop (`desktops`) | `restore_window` | `restore` |
| `minimize` | `minimized = true` | `minimize_window` | `minimize` |
| `unminimize` | `minimized = false` | `restore_window` | `unminimize` |
| `close` | `closeWindow()` | `close_window` | `close` |
| `center_cursor_in` | the "Move Mouse to Focus" action (`MoveMouseToFocus`) | `center_cursor_in_rect` | `center_cursor_in_rect` |
| `ensure_workspaces` | `createDesktop` on `org.kde.KWin.VirtualDesktopManager` | none | none |
| `switch_workspace` | `setCurrentDesktopForScreen` | none | none |
| `set_window_workspace` | `desktops` of the window | none | none |
| `window_workspace` | `desktops` of the window | none | none |
| `current_workspaces` | `currentDesktopForScreen` | none | none |
| `apply_look` | writes the effects' groups of `kwinrc`, `loadEffect` and `reconfigureEffect` | none | none |
| `set_border_colours` | `org.komorebi.BorderColours1`, which only komorebi's build of the border effect has | none | none |
| `set_opacity` | `opacity` | `set_transparent` | none |
| `set_focus_follows_mouse` | the `FocusPolicy` of `kwinrc`, then `reconfigure` | `enable_focus_follows_mouse` | none |
| `set_wallpaper` | `org.kde.PlasmaShell` `setWallpaper` | `set_wallpaper` | `set_wallpaper` |
| `maximize` | `setMaximize` | `maximize_window` | none |
<!-- /gen:backend -->
A method with "none" in both columns is something kfw and kfm do not need an operating system call
for, because the window manager keeps its own workspaces there, or something they do not have.
[Why everything is behind one trait](DESIGN.md#why-is-everything-the-window-manager-needs-behind-one-trait)
is in DESIGN.md.
## What KDE does by itself
The table lists what kfw and kfm do themselves and what KDE does, for the features where the
compositor, the shell or the desktop has a mechanism of its own. The sections below say what is
different for each.
<!-- gen:native -->
| What | kfw | kfm | On KDE |
|---|---|---|---|
| Workspaces | komorebi's own workspaces; the windows of the other workspaces are hidden | komorebi's own workspaces; the windows of the other workspaces are hidden | KWin's virtual desktops, one set per output (Plasma 6.8): workspace `i` is desktop `i` on every monitor |
| Hiding windows (a stack, a monocle) | `window_hiding_behaviour`: cloak, hide or minimize | moves the window to a corner of the screen | a virtual desktop nobody looks at (`komorebi-park`) |
| Borders | a topmost tool window per border, drawn by komorebi with Direct2D | an `NSWindow` per border, drawn by komorebi | the KDE Rounded Corners effect, with komorebi's patch for one color per kind of window |
| Animation | komorebi moves the window step by step | komorebi moves the window step by step | the Geometry Change effect, with komorebi's patch for the easing curve |
| Transparency of unfocused windows | `SetLayeredWindowAttributes`, called by komorebi | no key or command | KWin's window opacity, through the same patched effect as the borders |
| Focus follows mouse | the Windows setting, or komorebi's own implementation (`focus_follows_mouse`) | no key or command | KWin's focus policy; the user's policy is put back when it is turned off or komorebi exits |
| Maximize | `toggle-maximize`: the Win32 maximize | no key or command | `toggle-maximize`: KWin's maximize, which respects the panel. A window the user maximizes is taken out of the layout until restored |
| Fullscreen windows | no handling of its own in the sources | no handling of its own, except that the reaper keeps a window that fails to move | left alone, and put back in its tile when it leaves fullscreen |
| Wallpapers | the desktop wallpaper of each monitor | the desktop picture of each display | the Plasma shell, asked over D-Bus, one wallpaper per screen |
| Hotkeys | a separate program: `whkd` (or AutoHotkey) | a separate program: `skhd` | KDE global shortcuts: `.desktop` files for plain bindings, and the daemon through KGlobalAccel for modes, chords and scopes |
| Monitors added, removed or changed | a reconciliator thread, fed by `WM_DISPLAYCHANGE` in a hidden window | a reconciliator thread, fed by the display reconfiguration callback | the same thread, fed by the script (when KWin's list of outputs changes) and by `kwin/power.rs`; `reconcile.rs` follows the windows the compositor moved |
| Sleep, wake and lock | power setting and session notifications (`register_power_setting_notification`, `wts_register_session_notification`) | `ScreenLock` and `ScreenUnlock` events | `PrepareForSleep` of logind and `ActiveChanged` of the KDE screen saver, on D-Bus |
| Reloading the configuration | `watch-configuration` is about `komorebi.ahk` and `komorebi.ps1`; `komorebi.json` is watched | `komorebi.json` is watched | `komorebi.json` is watched |
<!-- /gen:native -->
### Workspaces are KWin's virtual desktops
kfw and kfm have a workspace layer of their own: komorebi keeps a list of workspaces for each
monitor, and when one is left it hides the windows of that workspace, because Windows and macOS
have no virtual desktop API to ask. On KDE, KWin 6.8 can give each output its own current desktop,
so komorebi's workspace `i` is KWin's desktop `i` on every monitor, and each monitor shows one at a
time. A switch is one request per monitor, and KWin shows, hides and focuses. komorebi
follows a switch made by something else (the pager, a shortcut, an application raising a window)
and answers it with no command. [Why](DESIGN.md#why-are-komorebis-workspaces-kwins-virtual-desktops)
is in DESIGN.md.
This has consequences that are measured, or read from KWin's sources:
- A switch made by an application raising a window produces one focus event and one switch
(spike 10, 2026-10-27). Answering a switch with commands makes KWin and komorebi fight: a design
in which komorebi did the hiding flipped between two workspaces about 280 times a second, because
KWin delivered focus events it had generated before it applied the commands, and komorebi read
them as new intent. komorebi therefore issues no commands in reply to a switch.
- The workspaces are visible in the pager and in the overview: they are the user's desktops, and a
stop leaves them in place (it removes the parking desktop).
- Desktops are global: every monitor has as many as the largest workspace count, and the name of a
desktop is shared by the monitors (the first monitor's, where they differ).
- A window that komorebi does not manage (a dialog, an ignored application) belongs to the desktop it
opened on, and goes out of view with it. kfw and kfm hide what a workspace holds (its containers,
its floating windows and its monocle) when they leave it, so a window they do not manage stays
visible across workspaces.
- The floor is KWin 6.8, because per-output desktops arrived there. Older KWin versions were not
tested. At time of writing (2026-10-28) the versions run are 6.8.1 (the spikes) and 6.8.2 (the VM
suites), in Plasma 6.8.1 and 6.8.2.
- komorebi turns `PerOutputVirtualDesktops` on in `kwinrc` when it starts and puts it back when it
exits. It edits the file itself: `kwriteconfig6` was not on the path of the user service in the
first live run.
### Hiding windows: cloaking, a corner, or a parking desktop
komorebi hides windows for a stack (the other windows of a container) and for a monocle (the other
containers). kfw offers three ways, chosen with `window_hiding_behaviour`: cloak (an undocumented
Win32 call), minimize, and the end-of-life `SW_HIDE`. kfm moves the window to a bottom corner of
its display, which `window_hiding_position` of a monitor chooses. kfde moves the window to a
parking desktop and moves it back, and there is nothing to choose. The scrolling layout needs none
of this: KWin keeps a window at a position outside the screen when it is moved there.
Three ways were measured on six tiled windows (spike 3, 2026-10-26, KWin 6.8.1):
| Way | Spurious focus events | Geometry restored |
|---|---|---|
| minimize | 2 (KWin picks a new active window as each window minimizes) | 6 of 6 |
| parking desktop | 0 | 6 of 6 |
| a position outside the screen | 0, but the windows stay mapped on the current desktop (task switcher, overview) | 6 of 6 |
KWin saves a virtual desktop in `kwinrc` the moment it is made, so a run that dies leaves the
parking desktop for the next session. komorebi removes it on exit, and the next start finds a stale
one, sends its windows home and removes it. A parked window still appears in the task manager unless
that is set to show the current desktop only (by construction, not measured).
[Why a parking desktop](DESIGN.md#why-are-the-windows-behind-the-front-one-of-a-stack-moved-to-a-parking-desktop)
is in DESIGN.md.
### Borders: komorebi draws them, or the compositor does
kfw draws a topmost tool window for each border, with Direct2D, and kfm an `NSWindow` for each. kfde draws nothing: the
KDE Rounded Corners effect draws the outer outline of every window, and komorebi writes its settings
to `kwinrc` and tells it to read them again. KWin keeps the copy of `kwinrc` it read at start, so
komorebi asks for a reconfiguration every time, also straight after it loads the effect.
The limits, as of 2026-10-27:
- The ring is drawn in the window's shadow, so a window without a shadow has none, and its thickness
is at most 20 px. That is why kfde has no counterpart of `remove_titlebar_applications`: removing
the title bar removes the shadow.
- The stock effect has a color for the active window and one for the others. komorebi's build of it
takes a color for each window over D-Bus (`org.komorebi.BorderColours1`), which gives the six kinds
of kfw's rules: `single`, `stack`, `monocle`, `floating`, `unfocused` and `unfocused_locked`.
Without that build, every kind falls back to `single` and `unfocused`, and komorebi says so once in
its log.
- KDE Rounded Corners 0.10.0 draws the ring about 24 px too low on KWin 6.8 (measured on screenshots
of KWin 6.8.1). kfde builds 0.11.0, which nixpkgs has too at time of writing (2026-10-28).
- KWin finds effects when it starts, so an effect installed later is not loaded until the next
login.
[Why the compositor draws the borders](DESIGN.md#why-does-the-compositor-draw-the-borders-and-not-komorebi),
[why the effects are patched](DESIGN.md#why-are-the-effects-patched) and
[why the border is the outer outline](DESIGN.md#why-is-the-border-the-outer-outline-of-the-effect)
are in DESIGN.md.
### Animation: komorebi moves the window step by step, or the compositor animates
kfw and kfm animate by moving the window a little at a time, at `animation.fps`. kfde sends the final
rectangle and the Geometry Change effect animates the move, so `fps` has nothing to map to: the
compositor animates at the refresh rate of the screen. The styles are Qt's easing curves of the same
name, which komorebi's build of the effect reads from a `Curve` setting. The stock effect eases out
exponentially, whatever the style says. Cross-fading is off.
KWin refuses effects that animate under software rendering, which includes every virtual machine the
tests run in, unless `KWIN_EFFECTS_FORCE_ANIMATIONS=1` is in KWin's environment. A screenshot cannot
show a short animation, because `spectacle` takes seconds and the curve is front-loaded: the look test
uses a 30 s animation to see the effect at work.
### Transparency, themes and wallpapers
Transparency is KWin's window opacity, set from the same rules as kfw. A window drawn through the
border effect comes from a texture with its opacity in it, which the effect redrew only when the
contents changed. komorebi's build redraws it when the opacity changes.
A wallpaper is set through the Plasma shell, over D-Bus (`org.kde.PlasmaShell`), for one screen. The
shell keeps one wallpaper for each screen, not for each virtual desktop, so komorebi sets it when a
workspace comes into view, as kfw and kfm do. If the shell is not running, komorebi tries again for
about half a minute and then says once that it leaves wallpapers alone. A palette made from a
wallpaper is cached in `$XDG_CACHE_HOME/komorebi`, by the name of the picture and a hash of its
path, size and time of change; a large picture takes seconds (not measured further).
### Focus follows mouse
kfw has two implementations to choose from, `Windows` and `Komorebi`, and calls the first legacy. kfm
has none. kfde asks KWin to use its focus policy, "focus follows mouse", with the same result for
both names, and puts the user's policy back when the setting is turned off or komorebi exits. KWin
waits for the pointer to settle before it moves the focus: `DelayFocusInterval`, 300 ms by default
in KWin 6.8.1. kfde sets it to 0 while the setting is on, and puts the user's value back with the
policy; why 0 is not recorded
([DESIGN.md](DESIGN.md#why-is-focus-follows-mouse-kwins-own-focus-policy)).
### Maximize and fullscreen
`toggle-maximize` is kfw's command, and does KWin's maximize on KDE: the window leaves the layout
and goes back to its tile when toggled again, and the panel is respected. A window that the user
maximizes (the title bar, a double click, a shortcut) is the same from then on: the commands that act
on the layout do nothing until it is restored. [Why](DESIGN.md#why-does-a-maximized-window-leave-the-layout-instead-of-being-given-the-work-area)
is in DESIGN.md. A fullscreen window covers its monitor, komorebi never moves it, and it is put back
in its tile when it leaves fullscreen. kfw has no code for fullscreen, and kfm has one
mention of it in its reaper.
## Dragging
All three programs let the user move a tile by dragging it and resize it by dragging an edge. KWin
reports where the pointer has the edge at every step of a resize
(`interactiveMoveResizeStepped`), so in kfde the neighbors follow the edge while it is dragged, and
not only when it is let go. The way a drag is measured, from the frame the window had when the drag
began, and granted as far as the layout can take it, is written down in
[drag-resize.md](../drag-resize.md), for the three programs. The frame KWin reports at the end of a
resize lags the pointer by a moment ([PLATFORM.md](PLATFORM.md#how-clients-answer-a-frame)). kfm
reads the frame of a window with an accessibility call when it needs it (`MacosApi::window_rect`);
whether that frame lags was not measured.
## Key bindings
kfw and kfm leave the keys to a separate program: kfw uses whkd, or AutoHotkey, kfm uses skhd, and
the program runs `komorebic`. On Plasma under Wayland no program sees the keys of another, so kfde
cannot do that: the keys are KDE's global shortcuts, in one of two ways, and komorebi reads the same
three formats a hotkey daemon would (`skhdrc`, `whkdrc`, `sxhkdrc`).
| | kfw | kfm | kfde |
|---|---|---|---|
| Who sees the keys | whkd, or AutoHotkey | skhd | KWin, through KDE's global shortcuts |
| The file the user writes | `whkdrc` | `skhdrc` | `skhdrc`, `whkdrc` or `sxhkdrc`, each read by a parser written for komorebi |
The measurements that decide when each is used, at time of writing (2026-10-27), on aarch64 under HVF
with four cores, KWin 6.8.1:
| What | Result |
|---|---|
| A static shortcut, key to the start of its `Exec` | 165 to 436 ms, median 233 ms, 8 runs of 8 |
| The daemon, key to the signal it gets | median 2.5 ms (min 2.2, max 3.9), 20 of 20 delivered |
| 60 calls to `setInactive` and `setShortcutKeys`, pipelined | answered in 2.4 ms in total |
| A native multi-key shortcut (`Meta+A, B`) | did not fire: the second key reached the focused client |
| A client killed after registering a key | the grab stays, and the key is swallowed, until `unRegister` |
The last two are why the daemon emulates chord chains, and why the module's unit releases the keys
when the daemon stops. A static shortcut works with the daemon stopped and shows in System Settings,
but costs about 0.2 seconds on each press; the daemon's keys are only as reliable as the daemon. The
default mode is the daemon for every binding (`keybindings.mode = "engine"`), which these
measurements favor ([why](DESIGN.md#why-does-the-engine-handle-every-binding-by-default), which
also says that the default is still open for a decision), and `auto` and `static` use shortcut
files for the bindings that can be one.
What is not emulated, and approximated, is listed in
[the user guide](../usage/keybindings.md#what-is-realized-and-what-is-not): side-specific modifiers,
mouse buttons, skhd's `fn`, and the sxhkd chain that a wrong key does not end. The reasons are in
DESIGN.md: [why some bindings are shortcut files](DESIGN.md#why-are-some-bindings-shortcut-files-and-the-others-the-engines)
and [why the engine grabs keys instead of using KDE's key sequences](DESIGN.md#why-does-the-engine-grab-and-give-back-keys-instead-of-using-kdes-own-key-sequences).
Keystrokes over RDP: KDE's shortcuts sit inside KWin's input pipeline and see them, and `swhkd`
reads the kernel's input devices and would not (read from the sources of KRDP and swhkd, not run).
Keys sent over RDP to a session were not verified end to end: the scripted client fails NTLM
against KRDP, and a real client was not tried.
## Multiple monitors, sleep and lock
All three programs have a monitor reconciliator: a thread that takes notifications one at a time to
move the windows of a monitor that went away and to bring them back. In kfw a hidden window
(`WM_DISPLAYCHANGE`) feeds it, and in kfm a display reconfiguration callback. In kfde the script feeds
it, with the whole list of outputs whenever KWin's changes, and so does the code that hears of a wake
or an unlock. The daemon takes the windows of an unplugged monitor over (each container, a stack whole, to the workspace of the same number), keeps what is left
of the monitor for when it comes back, and follows a window that something else moved to another
output. A moment after each notification (1.5 s) it looks at every window again, because KWin has
moved some. A monitor that changes size or scale is tiled again: every coordinate komorebi uses is
KWin's logical one. [Why](DESIGN.md#why-does-komorebi-take-the-windows-of-an-unplugged-monitor-over-itself)
is in DESIGN.md.
For the screen lock, kfm has `ScreenLock` and `ScreenUnlock` events, and kfw registers for power and
session notifications. kfde listens on D-Bus: logind's `PrepareForSleep` for a wake, and KDE's screen
saver `ActiveChanged` for a lock. With the screen off or locked KWin sends clients no frame callbacks,
so what komorebi asked for in that time is not done: komorebi waits 600 ms after an unlock and 2.5 s
after a wake and looks at every window again. The lock screen is a window of KWin's that is in no
task list and on every desktop; komorebi does not manage it.
At time of writing (2026-10-27) a real suspend and resume was not tested: the QEMU guests have no
way to wake from one. The signals are tested on private buses, and the lock screen against a real
KWin in a Plasma session. [PLATFORM.md](PLATFORM.md#sleep-and-lock) says so too.
## Checking the configuration
kfw and kfde have `komorebic check`, and kfm has none. kfw's reads the files in the configuration
home (`komorebi.json`, `komorebi.ahk` and `whkdrc` among them) and shows what is wrong with them.
kfde's reads `komorebi.json` the way the daemon will, tells a key of another platform from a typo
(with the nearest key that is a setting), looks at the key binding file and at whether it has been
made into KDE shortcuts, and then looks at the desktop: a Plasma session on Wayland, KWin 6 on the session bus, komorebi's
script in KWin, which build of each effect is installed, the Plasma shell when there are wallpapers,
and what starts komorebi at login. It exits with status 1 when something stops komorebi from working
(a file that is not JSON, no KWin), and 0 with warnings when it only will not do what was meant.
`--komorebi-config FILE` checks another file and `--configuration-only` leaves the desktop out; the
first flag is kfw's too.
kfw's `check` also asks GitHub for the latest release. kfde's does not look for a newer release, and
it does not know the AutoHotkey and PowerShell files of Windows.
## What kfw and kfm have that kfde does not
From the tables above, and from what has no row in them:
- The bar. `komorebi-bar` is not ported: the Plasma panel is used, and the work area accounts for it
(a panel moved is a change of the work area, and the tiles are made again).
- The stackbar and its settings. A stack is cycled with `cycle-stack` and `focus-stack-window`.
- Custom layouts, which kfw has and kfm does not. Not supported yet.
- The Win32 workarounds of the "Win32 quirks" group, the AutoHotkey and PowerShell configurations,
the named-pipe subscribers, and whkd as a separate program.
- The license check and the splash screen of the macOS and Windows builds.
- The tab and title bar commands (`remove-title-bar`, `toggle-title-bars`).
## What kfde has that kfw and kfm do not
- Native workspaces: they show in KWin's pager and overview, and KWin focuses the window of the
desktop it switches to.
- Borders, animation, transparency and focus follows mouse as a compositor does them, and `check`
for a desktop.
- Key bindings that work from a physical keyboard, the QEMU console and RDP, with modes, chords and
scopes realized by the daemon, and the `skhdrc`, `whkdrc` and `sxhkdrc` formats.
- A NixOS module (`services.komorebi`) with a user unit, the effects, and the key bindings as options,
and a version check of KWin. kfm has a module for nix-darwin, in its own form.
- A test suite that runs the window manager against a real KWin in virtual machines, and a `Backend`
that tests replace with a desktop in memory. [vm-tests.md](vm-tests.md) describes it.
## Costs, measured
At time of writing (2026-10-27), on an Apple silicon Mac, in virtual machines under HVF, KWin 6.8.1
(Plasma 6.8.1, nixpkgs `d3b13ad` of 2026-10-24). No number here compares kfde with kfw or kfm:
nothing of the same kind was measured on them.
| What | Result | Source |
|---|---|---|
| A retile of 10 `foot` windows on a 3840x2160 output, from the answer to `Poll` to the last frame KWin reported (5.5 windows moved on average) | p50 17.3 ms, p95 27.7 ms, max 31.4 ms | `vm-latency`, [PLATFORM.md](PLATFORM.md#how-long-a-retile-takes) |
| The same channel alone, 20 windows in each batch | p50 16 ms, p95 19 ms, max 20 ms | [the spikes](PLATFORM.md#vocabulary) |
| A client's answer to a frame | exact for Qt, GTK 4 down to its minimum, XWayland; `foot` rounds to its cells; GTK 4 Calculator and Firefox keep a minimum size | `vm-client-geometry`, [PLATFORM.md](PLATFORM.md#how-clients-answer-a-frame) |
| A window resized off the screen | KWin keeps 100 px of it on an output | [PLATFORM.md](PLATFORM.md#how-clients-answer-a-frame) |
| KWin restarting under a running daemon | the script is loaded again about 1 s after KWin is back | [the spikes](PLATFORM.md#vocabulary) |
What was not measured is listed in [PLATFORM.md](PLATFORM.md#what-was-not-measured): a real suspend
and resume, KWin before 6.8, activities, outputs beyond a second one, applications in a sandbox,
keys from an RDP client and graphics other than software rendering, among others.
+899
View File
@@ -0,0 +1,899 @@
# Design
This document explains why komorebi for KDE is built the way it is, one decision at a time.
It is opinionated: these are the reasons behind the code, and reasonable people may disagree
with them. Where a reason was not written down, the entry says that it needs one.
It grows with the code: a decision is added in the commit that makes it.
## What is komorebi for KDE the port of?
komorebi has a Windows implementation, the original, and a macOS one, and both were read for
what to adapt. I wanted to keep things as close to komorebi for Windows and for Mac as
possible, so that one configuration file is largely portable across all the platforms, and to
drop the hacks that Windows or macOS needed and Linux does not, relying on what KDE and
Wayland do natively. The events the window manager reacts to follow the Windows ones (a
window is shown, destroyed, focused, minimized, moved, resized), and a window is a small
`Copy` handle, as there. The model the window manager tiles is the one both platforms have:
monitors, each with workspaces, each with containers, each with windows. What the three
programs have in common and where they differ is in [COMPARE.md](COMPARE.md).
## Why is everything the window manager needs behind one trait?
So that the window manager can be tested without a compositor. A test that needs a real
KWin has to boot a virtual machine, which takes a minute or more and needs QEMU with a
hypervisor ([vm-tests.md](vm-tests.md)); a test against an in-memory desktop takes
milliseconds and runs anywhere. The logic (which window goes where, what happens when one
closes, how a stack cycles) is tested with the second kind, and the VM tests are kept for
what only KWin can tell.
The cost is that a second implementation has to be kept honest. A fake that does what it
is told is not KWin: a real client may refuse a size, a compositor may report an event the
fake never raises, and a fake that is too permissive hides a bug that a compositor would
show. The fake is therefore written to be strict where KWin is (a command about a window
that no longer exists is an error) and to clamp where a real client does (a window with a
minimum size keeps to it).
## Why is the backend a process-wide singleton?
So that a window can be a small `Copy` value that carries only its id. A window that
had to hold a reference to its backend would not be `Copy`, and every function that
moves, focuses or hides one would take a context argument as well. That is a lot of
plumbing for a thing that never changes while the daemon runs.
The cost is a global. A test that wants a private desktop overrides it for its own thread
with `with_backend`, which restores the previous one afterwards, also on a panic.
## Why does a backend answer from a table instead of asking the compositor?
A query that waits for the compositor can wait for a long time, and the window manager
asks a lot of questions: every move of a container is followed by a look at where each
window ended up. A backend keeps a table that the compositor's events update, so a query
is a lookup. The trade-off is that the table can be a moment behind the compositor, which
is why a command returns when it has been accepted and not when the client has acted, and
why the frame a window really has is read back afterwards.
## Why does komorebi not pick the next window to focus when one closes?
Because the compositor already has. When a window is destroyed, KWin activates the window
it considers next and reports that as a focus change, which komorebi follows. If komorebi
also focused a window of its own choosing, the two would fight over the focus. komorebi
focuses the window of its focused container only when the compositor has left nothing
focused.
## Why does komorebi run a script inside KWin?
KWin has no protocol that lets another process read and set window geometry. Its scripting
API has both, and a signal for each change komorebi follows: a window added, removed,
activated, minimized, moved or resized. So the part of the backend that sees and touches
windows is a script KWin runs, the bridge, and the daemon talks to it over the session bus.
## Why does the bridge hold no logic?
So that everything the backend decides can be tested without KWin. A script runs only inside
KWin: its own tests run it against a fake of KWin's API, which is only as right as the fake,
and a test of it against KWin needs a virtual machine. The bridge reports what KWin says, as
it says it, and carries out what it is told; what an event means (is this a window komorebi
manages, has it been announced already, which id does it have) is decided by the table in
`kwin::state`, which is plain Rust that takes the bridge's JSON and is unit-tested with it.
## Why is the bridge type-checked and tested without a JavaScript build chain?
I wanted safety, tests and typing around the bridge that do not need a JavaScript build
chain. KWin loads `bridge.js` as it is, so the checks read that file and produce nothing:
- `tsc` checks it as strict TypeScript through its JSDoc comments (`checkJs`, `noEmit`),
against `kwin-api.d.ts`, a hand-written declaration of the part of KWin's scripting API the
bridge uses. KWin publishes no declarations, and the declarations are narrower than the API
where that catches a mistake: a property the bridge has no reason to set is read-only, and
`callDBus` takes one string.
- `bridge.test.js` runs under `node --test`, node's own test runner, and loads the bridge into
a `node:vm` context whose globals are a fake KWin.
- The messages of a session are JSON files that the bridge's tests and the Rust tests both
read, so neither side can change a message alone.
`tsc` and `node` come from nixpkgs, through the dev shell and the flake's
`komorebi-bridge-js` check. There is no package.json, no npm dependency and no bundler.
## Why do commands go to the bridge as the answer to a held call?
Because it was the fastest channel measured, and it costs nothing while nothing happens. Four
ways for the daemon to get commands to a script in KWin were measured in October 2026, on
KWin 6.8.1 in a VM under HVF: twenty windows retiled in one batch, twenty times, timed from
the send until every window reported its new frame.
| Channel | p50 / p95 / max |
|---|---|
| a held `Poll` call, answered when there are commands | 16 / 19 / 20 ms |
| the script polls on a 16 ms timer | 16 / 20 / 32 ms |
| the script polls on a 50 ms timer | 49 / 57 / 65 ms |
| a new script per batch (`loadScript`, `run`, `unloadScript`) | 17 / 18 / 20 ms |
A timer is as fast only at about 60 D-Bus calls a second, forever. A new script per batch is
as fast, but 7 of its 17 ms (p50) are spent in the daemon's calls to KWin. A held call is
answered as soon as there is a batch, and an idle bridge makes one call every 10 seconds.
Rounds after idle gaps of 15 seconds to 10 minutes all completed, the slowest in 49 ms.
The hold is 10 seconds because QtDBus fails a call after 25 seconds. A call that fails is
never answered (the callback of `callDBus` runs on success only), so the bridge has a
one-second watchdog that calls `Poll` again when the last call is older than the hold plus 3
seconds, which is also how it finds a daemon that has restarted.
## Why are events and the held call on two D-Bus objects?
Because events must arrive in order and a held call waits. zbus handles each method call in a
task of its own by default, and two pairs of events were seen swapped. The `Event` interface
is therefore `spawn = false`: zbus handles its calls inline, one after the other, in the
order they arrive. The price is that a handler that waits holds up every call after it, so
`Event` never waits, and `Poll`, which waits by design, is a separate object with the default
spawning.
## Why does everything cross D-Bus as a JSON string?
Because a script cannot choose the D-Bus type of what it sends. `callDBus` sends a JavaScript
number as a 32-bit integer, and a call whose arguments do not match the method's signature
fails with no error the script can see. One string argument always matches, and the daemon
parses it. The declaration of `callDBus` the bridge is type-checked against takes one string,
so `tsc` refuses anything else.
## Why does the pointer follow the focus through a KWin shortcut?
Because a KWin script cannot move the pointer, and KWin can. Its "Move Mouse to Focus" action
puts the pointer in the middle of the window that has the focus, and it can be invoked over
D-Bus, through `kglobalaccel`: in [the spikes](PLATFORM.md#vocabulary) it moved the pointer from the middle of the screen
to the middle of the focused window, for two different windows. The backend asks for it once
KWin reports the window it focused as active, so the action finds the right one. The cost is
that the pointer can go to the middle of the focused window and nowhere else, which is what
komorebi asks for.
## Why does komorebi take every window out of its layout when KWin leaves the session bus?
Because nothing else will say that they have gone. When KWin goes away under a running
session (it crashed, or another KWin replaced it), its clients lose their connection and
their windows go with it, and so does the bridge, which would have reported them closing. In
the spikes KWin was killed and started again under a running daemon on the same bus, twice:
the old windows vanished without a single `removed` event. What the daemon does see is the
bus itself: `NameOwnerChanged` says that `org.kde.KWin` has lost its owner, and later that it
has a new one. So losing the name counts as every window closing, and getting it back as the
moment to load the bridge into the new KWin, which then reports its desktop as it does at
start.
## Why does komorebi take its orders on a socket?
komorebi responds to two things: what the compositor reports about windows, and the
messages it receives on its socket. It handles no keyboard or mouse input. Binding a key to
an action is the job of another program, which runs a command that writes a message on the
socket. This is the architecture that bspwm made popular on Linux and yabai on macOS, and
the one komorebi has on Windows and on macOS
([the design notes of komorebi for Mac](https://github.com/LGUG2Z/komorebi-for-mac/blob/master/docs/design.md)).
## Why is `komorebic` a separate program?
Because the daemon takes no input but its socket. `komorebic` turns a command line into one
message on the socket and, for a question, prints the answer. A key binding, a script and a
person at a terminal all drive komorebi the same way, by running `komorebic` (the design
notes of komorebi for Mac, linked above).
## Why does komorebi send notifications to subscribers?
So that a program such as a status bar can follow the window manager. The README of komorebi
for Windows demonstrates a custom status bar integrated through its notifications
([Window Manager Event Subscriptions](https://github.com/LGUG2Z/komorebi#window-manager-event-subscriptions)),
and komorebi for Mac sends the same notifications to Unix sockets, which is also how
`komorebic` talks to its daemon
([its README](https://github.com/LGUG2Z/komorebi-for-mac#window-manager-event-subscriptions)).
A subscriber here is a Unix socket, as on macOS. The named pipes that komorebi on Windows
sends notifications to are not ported, since the socket subscribers do the same.
## Why does the flake have a NixOS module?
So that komorebi runs on NixOS with one flake input and one module line. The module installs
komorebi and starts it with every Plasma session, and it adds the flake's overlay to nixpkgs
itself, so a configuration needs nothing else to find the package. Its options follow those of
the nix-darwin module of komorebi for Mac: `enable`, `package` and `logLevel`.
## Why does komorebi run as a systemd user unit?
Because a user unit covers every user: it is defined once for the machine and runs for each
user who logs in. It is wanted by `plasma-workspace.target`, so it runs in Plasma sessions and
nowhere else, and it is ordered after `plasma-core.target`, which Plasma orders after KWin's
service: the daemon exits when KWin is not on the session bus. systemd starts a daemon that fails
again.
## Why is there no binary cache?
The Komorebi license does not allow third parties to redistribute binaries. There is no public
binary cache for komorebi, so the flake builds it from source on each machine that installs it.
The releases of this repository are the only binaries
([why](#why-are-binaries-published-only-by-this-repository)).
## Why do the VM tests run on machines built with the module?
So that the tests exercise the module. Every VM suite boots a machine that imports
`nixosModules.default` and installs komorebi through it. The headless node runs the daemon with
the module's read-only `execStart`, and the session node runs the module's unit itself. A change
to the module that breaks how komorebi is installed or started fails the VM suites, and not only
`nixos-module-eval`.
## Why does the bridge ask KWin twice for the position of a window?
KWin moves a window anywhere it is asked to, but when it resizes a window it keeps 100 pixels of
it on an output, and it does so once the client has drawn at the new size, which is after the
bridge has set the frame. The scrolling layout moves the windows of the columns out of view to the
edge of the work area, where a few pixels of them are on the screen, and resizes the ones that
change width in the same command, and a terminal that rounds its size to its cells is resized
again by its client, so KWin pulls both back onto the screen. By then, setting
the position alone is a plain move, which KWin honors. The bridge remembers where it was asked
to put a window for a second, and sets the position again when the window's frame changes to
another one in that time ([PLATFORM.md](PLATFORM.md#how-clients-answer-a-frame)). Three tries
at most keep it from chasing a window that cannot go where it was asked, such as a fullscreen
one.
## Why are komorebi's workspaces KWin's virtual desktops?
Because KWin has virtual desktops, per output since KWin 6.8, and Windows and macOS have no API
for them. komorebi's own workspaces exist there for that reason: switching workspace hides
every window of the workspace being left and restores the windows of the one being entered. On
KDE that is what KWin does with its desktops, and native behavior is preferred over a
workaround (see [What is komorebi for KDE the port of?](#what-is-komorebi-for-kde-the-port-of)):
workspace `i` is desktop `i` on every monitor, and each monitor shows one at a time.
The spikes measured what KWin does with per-output desktops on a headless KWin with two
outputs: showing a desktop on one output left the other output's alone; KWin gave the focus to
a window of the desktop it switched to, by itself; and activating a window on another desktop
of its output (an application raising itself) made KWin switch that output to the window's
desktop and focus the window, by itself. So komorebi asks for a switch and follows the ones it
did not ask for, with no command in reply. A first attempt in which komorebi hid the windows
itself switched between two workspaces about 280 times a second after an application raised a
window of another workspace: KWin delivered focus events it had generated before it carried
out komorebi's commands, and komorebi took each for a new request. With KWin's desktops there
is nothing to debounce, since komorebi answers a switch with nothing.
The costs: desktops are global, so every monitor has as many as the monitor with the most
workspaces, with one name each, and they show in the pager and the overview. A window komorebi
does not manage (a dialog, say) belongs to the desktop it opened on and goes out of view with
it. The desktops komorebi created stay when it stops: by then they are the user's desktops.
## Why does komorebi edit `kwinrc` itself?
Because per-output virtual desktops are off by default, they are a setting in the user's
`kwinrc`, and the program that would set it cannot be counted on. KDE's `kwriteconfig6` was not
on the PATH of komorebi's user service in the first live run in a Plasma session, and
per-output desktops stayed off; `kreadconfig6` is not always installed either. The file is
plain ini, which komorebi changes line by line, and asks KWin to reload its configuration.
It is the user's setting, so the value komorebi found is kept in a backup file and put back
when komorebi stops; a backup a crash left behind keeps the value from before the first run,
and the next run puts it back.
## Why are the windows behind the front one of a stack moved to a parking desktop?
Because a container has one tile, so the windows of a stack that are not in front have to be out
of sight, and a virtual desktop nobody looks at was the one way to do that which the spikes found
to cost no focus change. Spike 3 hid six tiled windows and showed them again three ways.
Minimizing them gave the geometry back exactly, but KWin picked a new active window as each one minimized,
two focus events nobody asked for. Moving them to a virtual desktop of their own gave no focus
event and the geometry back exactly. Moving them off the screen worked too, since KWin does not
clamp a scripted move, but the windows stay mapped on the current desktop, in the window switcher,
the overview and the task manager, so it was not offered. KWin has nothing else: `Window.hidden`
cannot be set by a script. The reading of KWin's sources (6.8.1) is in
[PLATFORM.md](PLATFORM.md#the-parking-desktop). The other platforms have a setting that chooses
how windows are hidden; on KDE there is one way, and so no such setting.
The cost is that KWin keeps a virtual desktop in `kwinrc` as soon as it is made. A run that failed
after making the parking desktop left it there for every later session. So komorebi removes the
desktop when it stops, after the commands that bring the windows back have reached the bridge, and
the first snapshot of the next run finds a leftover, sends the windows on it to the first
workspace's desktop and removes it. A leftover is never used as the parking desktop of the new
run, since it is about to be removed and anything parked on it would go with it; the new run makes
its own the first time it needs one. Before each hide the table also checks that the desktop it
made is still listed, because somebody can remove it in System Settings, and a window sent to a
desktop that is not there has nowhere to go and nothing says so.
Activating a window that is on another desktop makes KWin switch that output to the window's
desktop (see [PLATFORM.md](PLATFORM.md#per-output-virtual-desktops)), so a click on a hidden
window in the task manager would leave the monitor showing the parking desktop, which has nothing
on it but hidden windows. The table sends the monitor straight back to the desktop it showed
before, and the window's own focus change then brings it to the front of its stack.
komorebi keeps a table of the windows it hid, [`HIDDEN_WINDOWS`](../../komorebi/src/lib.rs), and
records a window in it before it asks the backend to hide it. What the compositor reports about a
hidden window (a minimize, a move to another desktop) is the echo of a command komorebi sent, and
the window manager has to be able to tell that from the user's own: a window that the user
minimizes leaves the layout, and one komorebi hid does not.
## Why is the monocle container not one of the containers?
Because a layout gives every container a tile, and the monocle container is the one that has the
whole work area. [`Workspace::new_monocle_container`](../../komorebi/src/workspace.rs) takes the
focused container out of the workspace's containers and remembers its index, and
[`Workspace::update`](../../komorebi/src/workspace.rs) puts the window of the monocle container on
the work area and gives the other containers no tile. The container is taken out and put back
with the plain remove and insert of the ring, and not the ones that respect locked containers:
the comments of the code say that a monocle, like a maximize, takes over the whole screen before
it is reinserted at the same index, which is what respecting the indexes of locked containers
needs.
The container keeps its resize adjustment, "because when this container is inevitably
reintegrated, it would be weird if it doesn't go back to the dimensions it had before", and for
the same reason `update` does not shorten the list of adjustments while there is a monocle
container: with two containers, one of them in monocle, the list would be cut to one, and the
adjustment of the container in monocle would be lost when it came back (the comments in
`new_monocle_container` and `update`).
## Why does a maximized window leave the layout, instead of being given the work area?
Because KWin has a maximize of its own, and komorebi asks for it. The window gets the work area of
its output with the panels left alone, and a restore goes back to where the window was
(see the comment in the bridge where it carries the command out). It is the work
area and not the padded one that [`Workspace::update`](../../komorebi/src/workspace.rs) maximizes
a window to ("the compositor's own maximize, which is the work area and not the padded one"), so
the window cannot be a container: a layout would give it a tile, less the padding. It is held in
`maximized_window` instead, with the index it came from, and when it is restored it goes back to
that index in a container of its own. It is restored before it is tiled again, because "it is its
tile's size that it has to get back, not the compositor's idea of its old size" (the comment in
`reintegrate_maximized_window`).
## Why does one `komorebi.json` work on every platform?
Because a file written for one platform should load on the others, and a key that means
nothing on one of them is no reason to refuse the file. `StaticConfig` has the keys of komorebi
for Windows and for Mac that mean something on KDE Plasma, and serde skips a key it does not
know, so a key that does nothing here is accepted and ignored. The fixtures of `config_parity`
(spike 8) are the evidence: the example of komorebi for Windows, a file with every key that only
Windows has, a real file of komorebi for Mac and this repository's example all load and read
back, and the test checks that the keys the serializer drops are the Windows-only ones
(`WINDOWS_ONLY`) and no others. Where komorebi for Mac has no key that KDE needs
(`focus_follows_mouse`, `transparency`), `StaticConfig` has the one komorebi for Windows has.
[COMPARE.md](COMPARE.md#configuration) lists the keys of the three programs.
## Why does komorebi reload its configuration when the file changes?
It does what komorebi for Mac does: it watches `komorebi.json` and reloads it after about two
seconds. On Windows, `watch-configuration` is about the legacy AutoHotkey and PowerShell files,
which do not exist here. The watcher is `hotwatch`, whose default is to wait two seconds for the events of an
editor to settle. An editor either writes a file in place or replaces it with a new one, so the
daemon reloads on a modification and on a removal, and the test that follows a real daemon
through both of them is `the_daemon_follows_the_file_it_is_given_when_the_file_changes`.
## Why is an applications file that is not there skipped, and one that is broken an error?
Because one `komorebi.json` is meant to work on every platform, and the file it points to may be
one that another platform has: a configuration written for macOS names `applications.mac.json`,
which a KDE desktop does not have. The daemon warns and goes on. A file that exists and is not an
applications.json is a mistake in something the user wrote, and is an error.
## Why is a key komorebi does not know a warning, and a value it cannot read an error?
Because one `komorebi.json` is meant to work on every platform, and a key that komorebi for KDE
does not read may be one that another platform does. serde drops a key the types do not have, so
loading never fails because of one, and `komorebic check` does not fail for one either: the keys
only Windows or macOS reads are listed once as a note, and only a key that no platform has is a
warning, with the nearest key that exists, since it is most likely a typo and komorebi will not
have done what was meant. A value of the wrong kind is a different matter: the daemon does not
read the file (a daemon that is running keeps what it had), so the check shows the line and exits
with status 1. A workspace that is only a name is a warning too: it is not tiled, which is easy to
do without meaning to.
## Why is a daemon that runs without its script in KWin an error, and one that does not run a note?
A daemon without its script in KWin cannot see a window, so it tiles nothing while it runs: that
is an error, the one finding of the desktop check that says a daemon which is running is broken.
A daemon that is not running is not broken, so it is a note, with the command that starts it. A
script that is still in KWin when its daemon is gone is a warning, since starting the daemon
replaces it. The check tells which of the three it is by connecting to the daemon's socket and by
asking KWin whether it has loaded `komorebi-bridge`.
## Why does `nix/komorebi-options.nix` start with the hash of the schema?
Because the check that the options are fresh cannot make them again. `schemars-nixgen` makes
`nix/komorebi-options.nix` from `schema.json`, and it is not in the dev shell or in CI (it is
installed with `cargo install`). `just nixgen` writes the hash of `schema.json` as the first line
of the file, and the check `schema-fresh` compares that with the hash of the committed schema, and
the schema with what `komorebic static-config-schema` prints. A change to a key that leaves the
schema or the options behind fails the check, with no tool but the build.
## Why does `komorebic` write an autostart entry, as well as the module having a unit?
The module is NixOS, and the daemon runs on other distributions too. An XDG autostart entry is
what a Plasma session runs at login for a program that is not part of it, so
`komorebic enable-autostart` writes one, with the `komorebi.json` it is given if any. The entry is
ordered after `plasma-workspace` (`X-KDE-autostart-after`), as the module's unit is ordered after
`plasma-core.target`: the daemon exits when KWin is not on the session bus. The entry and the
unit do not go together, since the session bus gives its name to one komorebi.
## Why does the flake set the version of KDE Rounded Corners?
Because 0.10.0 draws its outline in the wrong place on KWin 6.8, the oldest KWin komorebi
supports: about 24 px too low, across the title bar. 0.11.0 is the release that handles the
texture coordinates KWin 6.8 inverted, so
[`nix/kde-rounded-corners.nix`](../../nix/kde-rounded-corners.nix) sets the version and the
source of the nixpkgs package to it ([PLATFORM.md](PLATFORM.md#kwin-effects)). nixpkgs `d3b13ad`
(2026-10-24) has 0.10.0 and `f05535a` (2026-10-27) has 0.11.0, so at time of writing
(2026-10-28) setting them changes nothing. The package still sets them, because the patch that
gives each window its own color is written for the 0.11.0 source.
## Why are the effects built disabled by default?
So that they cannot load with their own defaults before komorebi configures them. KWin loads
an effect that is enabled by default as soon as it starts, with the settings the effect has
then, and KDE Rounded Corners at its defaults draws a one pixel black outline over the title
bar of every window. Built with `EnabledByDefault` false, an effect is loaded only when
something asks for it with `loadEffect`, which can come after its settings are written. That
KWin then starts without the effect and loads it when asked was measured before the package
was written ([PLATFORM.md](PLATFORM.md#kwin-effects)). Geometry Change ships disabled by
default, and its check asserts it, so that an update of the effect cannot change it unseen.
## Why does the compositor draw the borders, and not komorebi?
Because the compositor has the frames, the corners and the shadows of the windows, and komorebi
has none of them. komorebi decides what the windows look like and describes it to the backend as a
`Look` ([`Backend::apply_look`](../../komorebi/src/backend/mod.rs)); on KWin the effect KDE
Rounded Corners draws it, and komorebi writes the effect's settings. The same code that decides the
look then runs against the fake desktop, which records the look it was asked for.
## Why is the border the outer outline of the effect?
Because the effect's own defaults draw a black outline one pixel thick *inside* every window, over
its title bar and contents, which is what an unconfigured install looks like. So komorebi sets
every inner outline to 0 and uses the outer outline, which is drawn outside the window, in the gap
the layout leaves between tiles. The effect draws the outer outline only in the shadow of the
window (its shader stops where the window's texture is transparent), so it is at most 20 px thick,
and a window that has no shadow has no border. komorebi does not take the title bar off a window
to change that: removing it also removed the shadow, and the border with it, and Plasma 6.8 gives
a window without a shadow one of its own ([PLATFORM.md](PLATFORM.md#kwin-effects)).
## Why does the layout leave room for the border only while it is drawn?
Because the border is outside the window: without room for it, it would fall on the window next
to it. And because komorebi cannot know that a border is drawn. The effect may not be installed
(KWin finds effects when it starts), or borders may be off, so the backend answers whether
`apply_look` drew one, and the layout leaves room only after a yes. A compositor that draws no
border takes none.
## Why does komorebi ask the effect to read its settings again after it loads it?
Because KWin keeps the copy of `kwinrc` it read when it started, and an effect reads its settings
from that copy, also one loaded a moment ago. Writing the file and loading the effect leaves the
effect with the settings the file had at the start of the session. `reconfigureEffect` makes it
read them again, so komorebi calls it every time, after loading too.
## Why does the border effect take a color for each window?
Because komorebi colors a window by what it is to the layout (the focused window of each monitor,
a stack, a monocle, a floating window, a locked container), and the stock effect knows only "the
active window" and "the others". komorebi's build of KDE Rounded Corners takes a color for each
window over D-Bus, through KWin's name ([PLATFORM.md](PLATFORM.md#the-patches)). Without that
build every kind falls back to the two colors of the look, and komorebi says so once in its log.
## Why does komorebi animate nothing itself?
Because the compositor draws the windows: an animation komorebi made would be a series of frames
asked of KWin, each a command, where the Geometry Change effect animates what is painted, in the
compositor, at the refresh rate of the screen. komorebi tells the effect how long an animation
lasts ([`border_manager::current_look`](../../komorebi/src/border_manager/mod.rs)). That is why
`animation-fps` is accepted and does nothing, and why the frame KWin reports for a window is the
final one from the start of the animation: the effect moves what is painted and not the window
([PLATFORM.md](PLATFORM.md#kwin-effects)).
## Why is cross-fading off?
Because cross-fading the old contents of a window into the new while it changes size is the
effect's default, and it costs a redraw of both. A window going to its place is a move and a
resize, and what the window shows does not change.
## Why are komorebi's animation styles Qt's easing curves?
Because KWin animates with `QEasingCurve`, and a style is a curve KWin has when it is Qt's name
without the "Ease": `EaseInOutSine` is `InOutSine`
([`QtCurve::qt_curve`](../../komorebi/src/core/animation.rs)). A custom cubic Bézier is not
one of Qt's curves, and is drawn as an ease out, the kind of curve a window moving to its place
wants. The stock Geometry Change has one curve, an exponential ease out, so komorebi's build of
it reads a `Curve` setting ([PLATFORM.md](PLATFORM.md#the-patches)).
## Why does the window manager keep the opacity it gave each window?
So that the backend is told only what changed. `transparency_manager::apply`
([`transparency_manager.rs`](../../komorebi/src/transparency_manager.rs)) is called after every
event and every message, and most of them change no window's opacity: the window manager keeps
the opacity it gave each window that is not opaque (`WindowManager::opacity_applied`), sends the
difference, makes a window opaque again when it should no longer be see-through (and only if it is
still there), and makes every one opaque when it stops.
## Why is focus follows mouse KWin's own focus policy?
Because KWin has one, and gives the focus to the window under the pointer by itself. komorebi
asks for it by changing the user's `FocusPolicy` and follows the focus, as it follows any change
of focus, and puts the policy back when focus follows mouse is turned off and when it exits
([PLATFORM.md](PLATFORM.md#files-and-directories)). Both implementations komorebi for Windows
names, `Windows` and `Komorebi`, ask KWin for the same thing. Upstream marks the Windows key
end-of-life in favor of masir, a separate program. The code also sets `DelayFocusInterval` to 0,
which is KWin's setting for no delay between the pointer entering a window and the window being
given the focus; why 0 and not the delay KWin has by default is not written down, and needs a
reason.
## Why is a palette kept by the hash of its picture?
Because the name of a picture alone does not say which picture it is: two folders can each have a
`wallpaper.png`, and one wallpaper can be painted over. A palette takes seconds to make for a
large picture, so it is kept, in the user's cache directory (`~/.cache/komorebi`), where it
outlives a login; the runtime directory, where the socket is, does not. The file is named after the
picture, a hash of its path, size and time of last change, and the variant. A palette that cannot
be kept is made again the next time. komorebi for Windows keeps them by file name alone.
## Why does komorebi set the wallpaper when a workspace comes into view?
Because Plasma keeps one wallpaper for each screen, not for each virtual desktop, and a
workspace is a virtual desktop. The shell shows what it was last told, whatever desktop is shown,
so komorebi tells it again as the workspace changes, as komorebi does on Windows and macOS. It does
so wherever a workspace comes into view (its own switches, a pager's, an application raising a
window of another workspace, and the start), since all of them change what the screen should show.
The picture fills the screen, as komorebi's wallpapers do on Windows.
## Why does komorebi ask the shell what the screen shows before it sets a wallpaper?
Because the workspace's wallpaper is asked for every time the workspace comes into view, and the
user may have changed the wallpaper by hand since: a wallpaper that is not the one komorebi wants
is put back, and one that already is, in the same plugin and fill mode, is not touched, so a
switch between two workspaces with the same picture changes nothing on the screen.
## Why is the wallpaper set in the background, and tried again?
Because the shell is another process, which may be slow, and may still be starting when komorebi is
(a session that has just logged in). Switching workspaces never waits for it: the backend notes the
wish for the output and a task on the runtime does the asking, so the request that runs last finds
the newest wish. A shell that is not there is asked again for about half a minute, with longer
waits, and then komorebi says once that it leaves wallpapers alone until the shell answers.
## Why does a wallpaper hand its theme to the borders by a call, and not by a message?
Because on Windows the theme of a wallpaper is sent to komorebi's own socket, and a message to
itself does nothing a call does not do. The call is made before the workspace is shown, so the
colors are the borders' by the time the first window of the workspace is given one.
## Why are the effects patched?
Because the stock effects lack what komorebi needs of them. Each patch leaves the effect
working without komorebi, with the settings the stock effect has:
| Effect | Patched for | Why |
|---|---|---|
| KDE Rounded Corners | a color for each window, set over D-Bus; drawing a window again when its opacity changes | komorebi colors a window by what it is to the layout (the focused window of each monitor, a stack, a monocle, a floating window, a locked container), and the stock effect has one color for the active window and one for the others. It also draws a window from a texture that has the window's opacity in it, made again only when the contents change or the window is resized, so a change of opacity alone would not show |
| Geometry Change | a `Curve` setting, the name of one of Qt's easing curves | komorebi's `animation.style` is an easing curve by name, and its named styles are Qt's curves with "Ease" in front (`EaseInOutSine` is Qt's `InOutSine`); the stock effect has one fixed curve, an exponential ease out, and no setting for it |
The patches are derivative works of the effects and are under the effects' license, the GNU
General Public License version 3 ([PLATFORM.md](PLATFORM.md#the-patches)).
## Why does the end of a drag carry the position of the pointer?
A window dragged onto another tile swaps places with the window there, and one dragged onto
another monitor goes to that monitor. The window manager finds the tile and the monitor by
asking the backend where the pointer is. Only the bridge can read the pointer, so the KWin
backend asks it through the held call, and returns the last position the table has when no
answer comes within 250 ms. The end of a drag is the moment the window manager asks, and the
event that reports it brings the position of the pointer with it, so the last position the
table has is the one that counts.
## Why is a drag of an edge measured from where the window was when it began?
A window is not always on its tile. A client that sizes itself to a grid, such as a terminal that
keeps to whole cells of its font, is a few pixels short of it, and a window with a minimum size
can be larger. Measured against the tile, every drag of such a window would look as if it had
moved the other edges too, and they would be resized as well. The frame the window had when the
drag began is what the user had under the pointer, so the drag is measured from it. KWin reports
the window's frame all through a drag, so the table keeps the frame of the start apart from it,
and the window manager reads that one when it handles the start.
## Why is the end of a resize the frame the user asked for and not the window's frame?
KWin changes the window's frame only once the client has drawn at the new size, so when the user
lets go the frame can be short of where they took the edge
([PLATFORM.md](PLATFORM.md#how-clients-answer-a-frame)). The frame the last step of the drag asked
for is where the user took it. The table keeps it apart from the window's frame, because the window
manager does not handle the end of the drag at once: it may be busy with an earlier event, and the
frame event KWin sends a millisecond after the end changes the frame in the table before the window
manager reads it. The end of the drag has to survive that, so it is not the window's frame. The
frame events go on updating the window's frame, and the retile that ends the drag puts the window on
its tile. A move changes no size, so the end of a move is the frame.
## Why is every step of a drag worked out from where the drag began?
A step says where the user has the edge now, so the drag so far is the distance from the start,
not something to add to the step before. Starting each step, and the end, from the layout as it
was when the user took hold makes the result of a drag the same with its steps as without them,
and a drag that ends where it began puts the neighbors back where they were.
## Why is the window whose edge is being dragged not moved during the drag?
It is the user's until they let go: KWin moves its edge with the pointer, and komorebi puts it on
its tile when the drag ends. A step tiles the workspace to move the neighbors, and so can anything
else that happens during the drag, such as a window that opens. The guard is in
`Window::set_position`, for the windows being resized, so that whatever tiles the workspace leaves
the dragged window alone.
## Why are the steps of a drag thinned out?
The pointer makes far more steps than anyone needs. The bridge sends one every 16 ms at most, the
newest, and a single-shot timer sends the last one of a burst, so the edge's final place is not
lost. Each step says where the edge is now, so one waiting in the window manager's channel is
enough: the window manager asks the window where its edges are when it gets to the step, and that
is the newest.
## Why does the bridge look at the outputs once a second?
Because KWin has no signal for the room a panel leaves, only for the outputs themselves. A
panel that starts, grows, moves or hides changes the work area of an output and raises nothing
the script can connect to, so the bridge reads the work area of every output again when
`screensChanged` is raised and when a dock window opens, closes or moves, and once a second in
its watchdog. Two of the moments are not enough alone: komorebi usually starts before the panel
does, and a panel is laid out after the resolution it follows, so the area at the moment of the
signal is not the final one. The bridge keeps the outputs it last sent and sends them only when
they are not the same, so a second that changed nothing sends nothing. The cost is that a panel
that changes its room with no dock window event is found up to a second late, and that the
bridge does a little work every second.
## Why does komorebi take the windows of an unplugged monitor over itself?
Because nothing else can tile them. When an output goes, KWin takes its windows to the outputs
that are left and puts them where it likes. komorebi has them in the containers of the monitor
that went, whose tiles are on a screen that is gone, so the windows sit untiled wherever KWin
put them. komorebi moves each container to the monitor that now holds the middle of its window,
and tiles the monitors that changed. It keeps the
monitor that went, with its workspaces and settings, so that an output that is plugged in again
gets them back: the windows the monitor had are tiled elsewhere by then, and it comes back
without them.
## Why does komorebi look at every window again a moment after the monitors change?
Because KWin moves windows about for a moment after the outputs change, so what it reports
first is not where the windows end up. An output that went takes its windows to another, one
that is plugged back may take them again, and a change of scale or resolution changes where the
middle of a window is. The monitor reconciliator therefore waits 1.5 seconds after a change of
the monitors (a burst of changes makes one wait) and then finds every container whose window is
on another monitor than the one komorebi has it on, and follows it there. A window that KWin
reports on another output is handled the same way, looking at every window and not only that
one, since when one has moved others may have too. komorebi tiles at once the windows it knows
about when the monitors change, such as those of an output that went; the ones KWin moves
afterwards are tiled up to 1.5 seconds later.
## Why does komorebi look at the desktop again when the machine wakes and the screen is unlocked?
Because nothing komorebi asked for while the screen was locked or the machine asleep was done.
In that time KWin sends its clients no frame callbacks, so a window that was asked to move did
not, a window that something else moved stayed where it was moved, and the monitors can come
back in another order or at another size. Neither an unlock nor a wake is an event about a
window, so komorebi listens for the two signals that say it happened, logind's `PrepareForSleep`
and the lock screen's `ActiveChanged`, and then reads the monitors, finds where every window is,
and puts each in its tile. It waits first: 0.6 seconds after an unlock, because the lock screen
goes before the windows can be seen, and 2.5 seconds after a wake, because the outputs are found
again one after another and the compositor moves windows about as they are. Going to sleep and
locking the screen change nothing, so komorebi does nothing for them.
## Why does the bridge compare the active window with the last one it announced?
Because after the screen is unlocked the window that is active again is not always announced,
and komorebi's idea of the focus would stay the one it had. Once a second the bridge compares the
window KWin has active with the one it last announced, and announces the active one when they
differ. It costs a comparison of two ids a second.
## Why is a window the user maximizes treated like one komorebi maximized?
Because the compositor reports both the same way, and komorebi has to follow it. The comment on the
`MaximizeChange` event says that komorebi's own `toggle-maximize` "does this too and finds the window
already as it asked, but the user's title bar does it without komorebi's knowing". A window that
stayed a tile would be asked to move at the next retile: the code that reads the windows that are
open when komorebi starts says a window that is already maximized is "the maximized window, not a tile
that would be asked to leave the maximized state". So
[`WindowManager::adopt_maximize_change`](../../komorebi/src/window_manager.rs) takes the window out of
the layout as `toggle-maximize` makes a window leave it, and what is asked of the layout does
nothing "until it is restored, by `toggle-maximize` or by the user" (the comment in
`process_command`). Because the report is the same either way, one comparison serves both: a window
that is, or is not, already the workspace's maximized window changes nothing.
## Why does komorebi leave a fullscreen window alone, and tile the workspace when it comes back?
Because the window covers the monitor on purpose. The comment in
[`Window::set_position`](../../komorebi/src/window.rs) says that "moving it would take it out of
fullscreen, or be ignored", and that "it goes back to its tile when it leaves fullscreen". The
window stays in its container, so the other windows are tiled as if it were not fullscreen, and
every move the window manager makes goes through `set_position`, which is where the window is
skipped. When the window comes back, "KWin gives it the frame it had before, which may not be the
tile it has now" (the comment in `handle_event`), so the workspace is tiled again. The bridge's
second request for a position gives up after three tries for the same reason: so that a window that
cannot go where it was asked, "a fullscreen one, say", is left alone rather than chased (the comment
on `settle` in [`bridge.js`](../../komorebi/src/kwin/bridge.js)).
## Why does `initial_window_placement_rules` take a number as well as text?
Because the documentation of the setting shows a number (`"initial_window_placement_rules": 3`),
and a JSON object's keys can only be text: the doc comment on the `Deserialize` of
[`PlacementTarget`](../../komorebi/src/core/mod.rs) says both. The place is read from `"Primary"`,
`"3"` and `3`, so the form the page shows works as well as the form a map's keys force. In komorebi
for Windows, at its commit 83c4e11d, the deserializer reads only text, so the number its page shows
is refused. [The page of this repository](../initial-window-placement-rules.md#on-kde) says which
forms are read.
The JSON schema of the type is written by hand, so that it says the same. The one `schemars`
derives for the enum is an object with a `Placement` or an `Index` key, which the comment on the
`JsonSchema` impl of [`PlacementTarget`](../../komorebi/src/core/mod.rs) calls "not what
`Serialize` and `Deserialize` read and write". The schema `schema.json` has says a name, a number,
or text that is a number, which is also what the module's typed `config` takes.
## Why are the key binding files read by parsers written for komorebi?
All three formats, skhd's, whkd's and sxhkd's, are read by parsers written by hand in
`komorebi-hotkeys`. For whkd there is a Rust parser, `whkd-parser`, but it requires a
`.shell pwsh|powershell|cmd` line, panics in `Shell::from` on any other shell, and its
per-application bindings match Windows process names. It is under the same license as
komorebi, so it stays usable as a dev-dependency: a test reads every whkdrc of the fixture
corpus with both parsers and compares the bindings. For skhd and sxhkd the reason is not
recorded; this entry needs one.
What is not plain syntax is expanded while the file is read: sxhkd's braces become one binding
per alternative, and skhd's `.define` templates and application groups are replaced where
they are used, so the model has only expanded bindings in it.
## Why are some bindings shortcut files, and the others the engine's?
A KDE global shortcut can be a `.desktop` file that KDE reads by itself. Such a static
shortcut is robust: it shows in System Settings, where it can be changed, and it survives a
komorebi process that has died. But it is one combo that runs one command: it cannot be in a
mode, wait for the second key of a chord, fire on release, or do something else in each
application. So a binding is a static shortcut when it is in the default mode, a single combo,
unscoped and a press binding, and the file declares no modes; everything else goes through
the engine, in which komorebi registers the keys itself and decides what each press does. A
blacklist and a pause binding apply to every binding, so a file with either is the engine's
too.
## Why does the engine handle every binding by default?
A static shortcut starts its command later than the engine is told of the key: on KWin 6.8.1
(in a virtual machine, on 2026-10-27) a static shortcut ran its command 165 to 436 ms after the
key, 233 ms at the median, while the engine was told of the key 2.5 ms after it, at the
median. So the default is `PlanMode::Engine`, and `PlanMode::Auto` and `PlanMode::Static` stay
selectable.
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.
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` and the daemon's `--keybindings-mode`
take their default from there; the NixOS module's `keybindings.mode` repeats it, `"engine"`.
## 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.
## Why does the unit release the keys after the daemon stops?
Because nothing else does when a daemon dies. kglobalaccel keeps the actions of a client
that was killed, and their keys with them: on KWin 6.8.1 (2026-10-27) a killed client's key
stayed swallowed, and its signal was sent to nobody, until the action was unregistered. A
daemon that stops on its own unregisters its keys, but one that crashes or is killed cannot,
and the next start may never come. So the NixOS module's unit runs `komorebic hotkeys
release` after the daemon stops, however it stops (`ExecStopPost`), and a start takes over
what is still registered.
## Why does a weekly job build against the tip of nixpkgs?
Because KWin and Plasma come from nixpkgs, and the flake follows the tip of nixpkgs-unstable
rather than a release branch, so a new KWin or Plasma arrives whenever `flake.lock` moves.
Only the VM tests can notice what a new KWin changes, and the pull request that moves the
lock every week runs the slow tier only when it is labeled. The canary job builds every
check, both VM tiers included, against the tip every week, without changing the repository,
and opens an issue when one fails, so that a break is known before the lock moves to it. A
break is fixed in a commit of its own rather than by pinning nixpkgs back.
## Why does the module check the version of KWin?
KWin 6.8 is the oldest KWin komorebi supports, because komorebi relies on the per-output virtual
desktops it introduced: the bridge reads the work area of each output for the desktop that output
shows. A NixOS system with an older KWin fails at evaluation, with a message that names both
versions.
The repository develops against the tip of nixpkgs-unstable, a weekly workflow moves
`flake.lock` to the tip, and a user's own nixpkgs can be newer still, so a system can have a
KWin that no VM suite has run against. Next to the floor,
[`nix/supported-kwin.nix`](../../nix/supported-kwin.nix) records `testedMax`, the newest KWin
every suite has passed against, and the module warns above it.
`services.komorebi.kwin.untestedIsError` turns the warning into an error. The two versions are
written down in that one file, which the module imports and anything else can read with `nix
eval`.
## Why is there a guest for UTM?
Because the QEMU in nixpkgs cannot give a guest a GPU on a Mac. Its `virtio-gpu` is 2D only, so
KWin composites on the guest's CPUs with llvmpipe, and KRDP encodes every frame on the same CPUs,
which is slow to use (it was not benchmarked). That QEMU cannot be rebuilt with GL from nixpkgs on
a Mac: virglrenderer and libepoxy build on `aarch64-darwin`, and ANGLE does not. krunkit 1.2.1
accepts a `virtio-gpu` device and then ignores it. UTM's QEMU has `virtio-gpu-gl`, which renders
the guest's OpenGL on the Mac's GPU through VirGL and shows the guest in a window of its own, with
no RDP in between.
The disk is made with `nixos-install` from a running guest, and not with nixpkgs' disk image
builders: those boot a virtual machine as part of the build, so they need a builder with KVM, and
a Linux builder that is itself a virtual machine on the Mac, as `darwin.linux-builder` is, has no
nested KVM. `nixos-install` is a plain program, in a guest that runs at the speed of the Mac's own
virtualization.
## Why does `run-kde` start the guest in QEMU with KVM, and not in Hyper-V?
The guest is started from a NixOS machine in WSL 2 that has this repository checked out: that is the
machine I named (Windows 11, an AMD CPU, the latest NixOS-WSL, x86_64), and the command is meant to
need nothing else set up. The flake already builds the Plasma guests as a QEMU runner that boots
the system from the host's Nix store, and the VM tests boot the same guests under QEMU with KVM,
so the command starts what CI boots. KVM is what WSL 2 offers inside its own virtual machine when
nested virtualization is on. The command needs it, and refuses to start without it, since Plasma
under software emulation is too slow to try anything; `--tcg` allows it anyway.
Why not Hyper-V, whose virtual machines Windows itself runs? Nobody wrote down a reason, and this
entry does not make one up. What is known is that a Hyper-V guest would be another artifact, a disk
image that Windows' hypervisor boots, and that the repository builds none. The reason for
choosing QEMU over it still needs to be written down.
## Why is the QEMU window the first way to see the guest, and RDP the second?
I decided that the primary view is the QEMU window through WSLg, and that RDP from
Windows (`mstsc`) comes second. The reason was not written down. What bears on it is known: the
guest's RDP server, KRDP, sends H.264 video only, encoded in software on the guest's CPUs when there
is no VAAPI device, FreeRDP built with OpenH264 shows nothing of it, and nobody has tried Windows'
client against it ([PLATFORM.md](PLATFORM.md#rdp-into-the-session)). A window of QEMU has no video
encoder between the guest and the screen. How fast the window is through WSLg has not been
measured: the plan has the probe's number decide which is the default.
## Why does the guest use the GPU wherever the host has one?
Because I want GPU accel where it's available on the host. So the GPU path is part of the design and
not an opt-in: `run-kde` looks for it (`/dev/dxg` on WSL 2, a render node elsewhere, and a host
OpenGL that is not llvmpipe) and starts the guest with `virtio-vga-gl` and QEMU's GTK window with
OpenGL, which gives KWin in the guest real OpenGL through VirGL. When the host has none, it starts the
guest with a software `virtio-vga` and says why. `--gpu auto|on|off` overrides the choice, and KVM is
needed either way.
The display device is not part of the guest. The runner of nixpkgs would fix it when the guest is
built, so the demo guest leaves it out, and `run-kde` gives the runner the device when it starts
the guest: one closure and one disk serve both paths.
## Why is the password made for each user, and shared by a directory?
A guest's closure is in the Nix store of whoever builds it, which every user of that machine can
read, so a password or a key in it would be known to all of them, and would be the same for everyone
who runs the demo. The Plasma guests carry no key and no password already
([utm.md](utm.md)). `run-kde` makes a random RDP password and an ssh key pair when it makes the state
directory, in files that only the user can read, and shares that directory with the guest, which
takes the two files when it boots. Why a shared directory and not another way to hand the guest a
secret was not written down; the guests already get the repository that way.
The guest copies the files as root, and does not read them where they are, because the user of the
host who owns the directory need not be the guest's user: with another owner, and the mode of 0700 the
directory has, the guest's user cannot read it.
## Why are binaries published only by this repository?
The Komorebi License allows anyone to distribute the source code, with changes, but not
binaries built from it. So the releases of this repository, which CI builds, are the only
binaries, and the flake has no public binary cache: nix builds komorebi from source.
The release binaries are built by nix like every other output of the flake, then pointed at
the system's dynamic loader with no library path. As nix builds it, a binary loads glibc from
the store paths of the nixpkgs revision it was built with, which a machine without that
revision in its store does not have.
+943
View File
@@ -0,0 +1,943 @@
# Platform
komorebi for KDE runs in a KDE Plasma session, as a client of KWin. Most of the details on
this page are also written down next to the code that depends on them; this page
centralizes them: which KWin it needs, how it finds it, what it creates in the session and
leaves behind, every environment variable it reads, and what happens when something is
missing.
Facts that change with KWin and Plasma releases are dated. Unless a fact says otherwise, it
was measured with KWin 6.8.1, Plasma 6.8.1 and Qt 6.12.0 from nixpkgs `d3b13ad`
(2026-10-24), in NixOS virtual machines under QEMU on an Apple silicon Mac (HVF). The VM
tests of this repository run against the nixpkgs that `flake.lock` pins: at time of writing
(2026-10-28), `f05535a` (2026-10-27), with KWin 6.8.2, Plasma 6.8.2 and Qt 6.12.0.
## Vocabulary
- **Session**: one user's Plasma login: KWin, the Plasma shell, and a D-Bus session bus they
share.
- **Session bus**: the D-Bus bus of the session. komorebi and KWin talk over it.
- **KWin**: the compositor and window manager of Plasma, `kwin_wayland`.
- **Script**: a JavaScript program that KWin runs inside itself, through its scripting API.
komorebi's is the **bridge**, [`bridge.js`](../../komorebi/src/kwin/bridge.js).
- **Output**: KWin's name for a monitor.
- **Desktop**: one of KWin's virtual desktops. Each output shows one; komorebi's workspace `i`
is desktop `i`.
- **Parking desktop**: the desktop named `komorebi-park`, which komorebi makes to hide the back of
a stack, and the windows behind a monocle, on. It is not a workspace.
- **Headless KWin**: `kwin_wayland --virtual`, a KWin with virtual outputs and no display,
which the VM tests run ([vm-tests.md](vm-tests.md)).
- **The spikes**: throwaway measurements made before komorebi for KDE was written, each
answering one question about KWin (the event stream, the command channel, how to hide
windows, how clients answer a frame, the effects, the native actions, finding KWin again
after a restart, whether one `komorebi.json` can be shared, per-output desktops), numbered
from 1 to 10. They ran on KWin 6.8.1 in NixOS virtual machines under QEMU on an Apple silicon
Mac. Their numbers are quoted where they are used, with the date, and where a VM test repeats
a measurement the test is named. `spikes/config-parity/fixtures` is spike 8's.
## What komorebi needs
### KWin 6.8 or newer
KWin 6.8 is the oldest KWin komorebi supports. komorebi's workspaces are KWin's virtual
desktops, one shown on each output, which needs the per-output virtual desktops KWin 6.8
introduced (`workspace.currentDesktopForScreen`, `workspace.setCurrentDesktopForScreen`, and
the setting `[Windows] PerOutputVirtualDesktops` in `kwinrc`). At time of writing (2026-10-28)
komorebi has been run against KWin 6.8.1 (the spikes) and 6.8.2 (every VM suite); 6.7 and older
have not been tried.
### Per-output virtual desktops
What komorebi relies on KWin to do with them, on KWin 6.8.1 at time of writing (2026-10-27),
measured in the spikes and checked by the VM test `vm-kwin-contract` on a headless KWin with two
outputs:
- With `PerOutputVirtualDesktops=true` in the `[Windows]` group of `kwinrc`, a script that
shows a desktop on one output (`workspace.setCurrentDesktopForScreen`) leaves the other
output's desktop as it was. komorebi turns the setting on when it starts, has KWin reload its
configuration (`org.kde.KWin.reconfigure`), and puts the user's value back when it stops.
- KWin raises `workspace.currentDesktopChanged` when an output shows another desktop. The signal
does not say which output, so the bridge reads the desktop of every output after it.
- KWin gives the focus to a window of the desktop it switched an output to, by itself.
- Activating a window that is on another desktop of its output switches that output to the
window's desktop and gives the window the focus.
- A window that a script moves so that its middle is on another output keeps its desktops;
`window.output` follows the middle. KWin puts a window on the new output's desktop only during
an interactive move.
- Putting a window on another desktop from outside the script raises the window's
`desktopsChanged`.
- Desktops are global: every output has the same desktops, with the same names, and each output
shows one of them. The ids of the desktops are UUIDs; the bridge names them by id.
### The parking desktop
Why komorebi hides windows on a desktop of its own is in
[DESIGN.md](DESIGN.md#why-are-the-windows-behind-the-front-one-of-a-stack-moved-to-a-parking-desktop).
What it relies on KWin for, at time of writing (2026-10-27), measured by the spikes on KWin
6.8.1 (nixpkgs `d3b13ad`, 2026-10-24) unless it says otherwise. The VM test `vm-stacks` runs
komorebi's use of them in a headless KWin:
- A window on another desktop of its output is out of sight, and moving it there and back gives
its frame back exactly. Hiding six windows this way raised no `activated` event; minimizing
them raised two.
- KWin saves a virtual desktop in `kwinrc` as soon as it is made. A desktop that komorebi made
and did not remove, because it was killed, is in every later session.
- Activating a window that is on another desktop of its output switches that output to the
window's desktop (see [Per-output virtual desktops](#per-output-virtual-desktops)), which for a
hidden window is the parking desktop.
- `Window.hidden` is read-only to a script, and the only thing in KWin's 6.8.1 sources that sets
it is a layer-shell window (an auto-hide panel). This is a reading of the sources, not a
measurement.
- A window on the parking desktop is still a window of the session. Whether Plasma's task manager
lists it depends on the task manager's setting for showing the windows of the current desktop
only; the VM tests have no panel, so this is not measured.
[`nix/supported-kwin.nix`](../../nix/supported-kwin.nix) records both ends: `min`, the oldest
KWin komorebi supports (6.8), and `testedMax`, the newest KWin every VM suite has passed against
(6.8.2, with nixpkgs-unstable `f05535a`). The NixOS module reads the file. A system whose KWin
is older than `min` does not evaluate; one whose KWin is newer than `testedMax` builds with a
warning, unless `services.komorebi.kwin.untestedIsError` is set, which makes it an error. Outside
NixOS nothing checks the version.
The repository follows the tip of nixpkgs-unstable, so a newer KWin reaches it with a
`flake.lock` update or shows up first in the weekly canary job, which builds every check and runs
every VM suite against the tip. Once every suite has passed against a newer KWin, a commit raises
`testedMax` to it, with the date and the nixpkgs revision in the file's comment, and says in its
message which run it was and which suites ran ([CONTRIBUTING.md](../../CONTRIBUTING.md#the-nixos-module)).
### Wayland
komorebi runs in a Plasma Wayland session. There is no X11 session of Plasma 6.8 to run it in.
Programs that run on XWayland inside the Wayland session are windows like any other; KWin
reports their X11 class (`XTerm`) where a Wayland client has its app id (`foot`,
`org.kde.konsole`).
### The session bus
komorebi finds KWin on the session bus, and nowhere else. It needs to own the name
`org.komorebi.Bridge` there, and KWin has to own `org.kde.KWin`. See
[`DBUS_SESSION_BUS_ADDRESS`](#dbus_session_bus_address) for how the bus is found.
## Environments
The same questions, for each place the daemon can be started:
1. How it finds KWin.
2. What it does there.
3. What it leaves behind.
### A Plasma session
#### How komorebi finds KWin
Through the session bus. When the daemon is started from the session (a terminal, an
autostart entry, a user unit of the session), the bus is already in its environment.
On NixOS, the module's user unit, `komorebi.service`, is wanted by `plasma-workspace.target`
and ordered after `plasma-core.target`, which Plasma orders after KWin's service,
`plasma-kwin_wayland.service`: the session starts the daemon once KWin's service has started
([installation.md](../installation.md)). The unit's `PATH` is `/run/wrappers/bin`,
`/etc/profiles/per-user/<user>/bin` and `/run/current-system/sw/bin`.
#### What komorebi does
It connects to the session bus as `org.komorebi.Bridge`, writes the bridge to
`$XDG_RUNTIME_DIR/komorebi/bridge.js`, and asks KWin to load it under the name
`komorebi-bridge`, replacing a script of that name left by an earlier run. The script reports
the windows and outputs it finds, and from then on every window that opens, closes, takes the
focus, is minimized or brought back, goes fullscreen or comes back, is maximized or restored,
moves or changes size, the start and the end of every drag of a window by the user, and every
change of the outputs (one that changes resolution or scale, and the room a panel leaves). KWin
has no signal for that room, so the script looks at the outputs again when a dock window opens,
closes or moves, and once a second; it also compares KWin's active window with the one it last
reported once a second. The daemon waits up to 10 seconds for the first report and does not
start without it.
It also watches for the machine waking up and the screen being unlocked, with two signals that
are not KWin's ([D-Bus](#d-bus)): logind's `PrepareForSleep` on the system bus, and the lock
screen's `ActiveChanged` on the session bus. Either one makes it look at the monitors and at
where every window is again, after a delay (2.5 seconds after a wake, 0.6 after an unlock). Where
there is no system bus, as in a container, it logs that it is not watching for sleep, and
carries on.
Before it loads the script, it turns on KWin's per-output virtual desktops in the user's
`kwinrc` (`[Windows] PerOutputVirtualDesktops=true`), unless they are on, and asks KWin to
reload its configuration. If a workspace has no desktop, it creates the missing desktops over
`org.kde.KWin.VirtualDesktopManager`, named "Workspace 1", "Workspace 2" and so on. A desktop
that is already there keeps its name.
When komorebi hides a window for the first time (the back of a stack, or a window behind a
monocle), it makes one more desktop, named `komorebi-park`, after the desktops of the workspaces
(the missing workspace desktops are made by position, so that it stays last), and moves the window
there. The desktop is not a workspace: komorebi counts the workspaces without it, and a window on
it is on the workspace it will come back to. It checks that KWin still lists the desktop before it
sends another window there.
When borders are on, it also asks KWin to load KDE Rounded Corners, the effect that draws them,
after writing the effect's settings into `kwinrc`, and asks it to read them again
([KWin effects](#kwin-effects)). It does the same with Geometry Change, the effect that animates
windows, when animation is on. An effect KWin did not find is reported once in the log. When focus
follows mouse is turned on, it sets KWin's focus policy in `kwinrc` (`[Windows] FocusPolicy=1`,
`DelayFocusInterval=0`) and asks KWin to reload its configuration.
Every command of the window manager (move and resize, focus, raise, hide or restore, minimize,
bring back, maximize, unmaximize or close a window, show a workspace on an output, put a window
on a workspace) is queued for the bridge, which gets the queue as the answer to its held call and
carries the commands out in KWin, in order. A maximize is KWin's own, `setMaximize(true, true)`:
the window gets the work area of its output with the panels left alone, komorebi sets no frame
for it meanwhile, and unmaximizing it gives it back the frame it had. The VM test `vm-features`
checks that the window fills the work area and is on top. The script API cannot move the pointer,
so when the pointer follows the focus komorebi invokes KWin's own "Move Mouse to Focus" shortcut,
which puts the pointer in the middle of the window KWin has focused.
Some of what the bridge reports is the user's doing, not the answer to a command. KWin raises
`maximizedChanged` for komorebi's maximize and for the user's (the title bar, a double click, a
shortcut) alike, and the bridge reports a window as maximized only when it is maximized both
ways (`maximizeMode` 3): a window maximized in one direction is a restored window to komorebi.
The VM test `vm-user-maximize` maximizes windows with `kdotool windowstate`, in both directions,
and passes against KWin 6.8.2 at time of writing (2026-10-28).
A fullscreen window is reported by `fullScreenChanged`, and komorebi asks KWin for no frame for
it while it is fullscreen. When it leaves fullscreen KWin gives it the frame it had before,
whatever komorebi has done to the layout since. The VM test `vm-features` takes a window
fullscreen with `kdotool windowstate`, and checks that it covers the output, that a window that
opens meanwhile leaves it there, and that it is in a tile when it comes back. It passes against
KWin 6.8.2 at time of writing (2026-10-28).
#### When KWin restarts
KWin can go away while the session goes on: it crashed, or `kwin_wayland --replace` took its
place. The session bus stays, and the windows go with the old KWin. komorebi keeps running. It
watches who owns `org.kde.KWin` on the session bus, and when nobody does it takes every window
of the old KWin out of its layout, as if each had been closed: the bridge went with KWin, so
nothing reports them closing. When the name has an owner again, komorebi loads the bridge into
the new KWin, trying again for up to 15 seconds while KWin is not ready for it, and the bridge
reports the new KWin's windows and outputs as it does at start. A window that opens in the new
KWin is tiled. kglobalaccel runs in KWin, so the keys of the engine go with the old KWin:
komorebi watches `org.kde.kglobalaccel` the same way, and when it has an owner again, it reads
its key binding file again and registers the keys with the new one, trying for up to 15
seconds. The VM test `vm-restart-survival` kills the KWin of a Plasma session under the
daemon and presses a key afterwards. In the spikes the bridge was loaded again 1.0 to 1.1 seconds after the name had
an owner again; the VM test `vm-kwin-restart` restarts KWin twice under a running daemon.
#### 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, 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. It also leaves the keys of its engine
grabbed: they are swallowed, and run nothing, until `komorebic hotkeys release` unregisters them, or
the next start takes them over and unregisters those its key bindings no longer have. The NixOS
module's unit runs `komorebic hotkeys release` after the daemon stops, however it stops.
### A headless KWin
`kwin_wayland --virtual` behaves like the KWin of a session for everything komorebi does but
the lock screen, which it has none of (`vm-lock-sleep` runs in a Plasma session): the VM tests
run the daemon against one, on a private session bus of its own. It cannot draw
(see [Rendering](#rendering-in-virtual-machines-and-over-rdp)), so nothing that depends on
pixels can be tested against it. Started with `--no-global-shortcuts`, as the VM tests start
it, KWin does not own `org.kde.kglobalaccel`, and the pointer does not follow the focus; the
daemon logs that at debug level and carries on.
### No KWin
Anywhere else (a session that is not Plasma, a Linux console, a Mac), the daemon exits with an
error that names what is missing:
- "could not connect to the session bus as org.komorebi.Bridge": there is no session bus at
the address the environment gives, or another komorebi owns the name.
- "KWin is not on the session bus": the bus is there and KWin is not.
- "KWin loaded the bridge script but it never reported in": KWin is there, and the script did
not run. KWin logs a script's errors to the journal (`journalctl --user -t kwin_wayland`).
`komorebi --fake-backend` runs the window manager against an in-memory desktop instead, which
works anywhere, for development and testing.
## D-Bus
What komorebi owns, on the session bus:
| Name | Object | Interface | Member | Called by |
|---|---|---|---|---|
| `org.komorebi.Bridge` | `/org/komorebi/Bridge` | `org.komorebi.Bridge` | `Event(s)` | the bridge, for every event |
| `org.komorebi.Bridge` | `/org/komorebi/Bridge/Poll` | `org.komorebi.Bridge.Poll` | `Poll(s) -> s` | the bridge, for commands |
Both take a JSON string. `Poll` is held: the daemon answers it when it has commands for the
bridge, or with an empty list after 10 seconds, and the bridge then calls it again.
What komorebi calls:
| Name | Object | Interface | Member | When |
|---|---|---|---|---|
| `org.kde.KWin` | `/Scripting` | `org.kde.kwin.Scripting` | `unloadScript(s)`, `loadScript(ss) -> i` | at start, and when KWin is back after a restart; `unloadScript` again at exit |
| `org.kde.KWin` | `/Scripting/Script<id>` | `org.kde.kwin.Script` | `run()` | after `loadScript` |
| `org.freedesktop.DBus` | `/org/freedesktop/DBus` | `org.freedesktop.DBus` | `AddMatch(s)`, for the signal `NameOwnerChanged` | at start, to see KWin (`org.kde.KWin`, and `org.kde.kglobalaccel`, which it owns too) leave the bus and come back |
| `org.kde.kglobalaccel` | `/component/kwin` | `org.kde.kglobalaccel.Component` | `invokeShortcut(s)`, with `MoveMouseToFocus` | when the pointer follows the focus |
| `org.kde.KWin` | `/Effects` | `org.kde.kwin.Effects` | `isEffectSupported(s)`, `isEffectLoaded(s)`, `loadEffect(s)`, `unloadEffect(s)`, `reconfigureEffect(s)`, with `kwin4_effect_shapecorners` and `kwin4_effect_geometry_change` | when the look changes (the border is turned on, off or changed), and at exit |
| `org.kde.KWin` | `/org/komorebi/BorderColours` | `org.komorebi.BorderColours1` | `SetColours(asau)`: the UUID of each window and its color, `0xRRGGBB` | when the color of a window's border changes; the object is komorebi's build of the border effect ([The patches](#the-patches)) |
| `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:
| Bus | Sender | Interface | Signal | Meaning |
|---|---|---|---|---|
| system | `org.freedesktop.login1` | `org.freedesktop.login1.Manager` | `PrepareForSleep(b)` | the machine is going to sleep (true) or has woken up (false) |
| session | any | `org.freedesktop.ScreenSaver` | `ActiveChanged(b)` | the lock screen came up (true) or went away (false) |
Only logind is believed about sleep. The lock screen's signal is taken from any sender on the
session bus.
The property `desktops` is introspected as `a(iss)`, a position, an id and a name for each
desktop, and the value on the wire is `a(uss)`: komorebi reads it as that. It is read uncached,
since a read right after `createDesktop` has to see the new desktop.
What `komorebic check` calls, in this order, each with two seconds to answer:
| Name | Object | Interface | Member | For |
|---|---|---|---|---|
| `org.freedesktop.DBus` | `/org/freedesktop/DBus` | `org.freedesktop.DBus` | `NameHasOwner(s) -> b` | whether `org.kde.KWin` is on the bus |
| `org.freedesktop.DBus` | `/org/freedesktop/DBus` | `org.freedesktop.DBus` | `GetConnectionUnixProcessID(s) -> u` | the process that owns `org.kde.KWin`, whose environment says where KWin looks for effects |
| `org.kde.KWin` | `/KWin` | `org.kde.KWin` | `supportInformation() -> s` | KWin's version: the line `KWin version: X.Y.Z` of the text |
| `org.kde.KWin` | `/Scripting` | `org.kde.kwin.Scripting` | `isScriptLoaded(s) -> b` | whether the script `komorebi-bridge` is loaded |
| `org.kde.KWin` | `/Effects` | `org.kde.kwin.Effects` | `isEffectSupported(s) -> b` | whether the border effect (`kwin4_effect_shapecorners`) and the animation effect (`kwin4_effect_geometry_change`) are installed |
| `org.kde.KWin` | `/org/komorebi/BorderColours` | `org.freedesktop.DBus.Introspectable` | `Introspect() -> s` | whether komorebi's build of the border effect is loaded: its object has the interface `org.komorebi.BorderColours1` |
| `org.freedesktop.DBus` | `/org/freedesktop/DBus` | `org.freedesktop.DBus` | `NameHasOwner(s) -> b` | whether `org.kde.plasmashell` is on the bus, when there are wallpapers |
At time of writing (2026-10-27), the headless KWin of the VM tests (Plasma 6.8) answers
`supportInformation` with a text that has that line, and `vm-check` has `komorebic check` read the
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.
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 |
|---|---|---|
| `$KOMOREBI_CONFIG_HOME/komorebi.json` (`~/.config/komorebi/komorebi.json`) | komorebi's configuration, which komorebi never writes: read when the daemon starts, and again when it changes. `--config` names another file | the user's |
| `$XDG_CONFIG_HOME/autostart/komorebi.desktop` (`~/.config/autostart/komorebi.desktop`) | the XDG autostart entry `komorebic enable-autostart` writes: `Exec=komorebi`, or `komorebi --config "FILE"`, and `X-KDE-autostart-after=plasma-workspace`, which a Plasma session starts komorebi from at login | the user's; `komorebic disable-autostart` removes it |
| `$XDG_CONFIG_HOME/kwinrc` (`~/.config/kwinrc`) | KWin's configuration: komorebi sets `PerOutputVirtualDesktops=true` in `[Windows]`, changing that line or adding it and nothing else, and writes the file beside it first and renames it over it | put back as it was when the daemon stops |
| `$XDG_CONFIG_HOME/kwinrc`, group `[Windows]`, keys `FocusPolicy` and `DelayFocusInterval` | `1` and `0` while focus follows mouse is on: KWin's "focus follows mouse" policy, which KWin takes when it is asked to reconfigure | put back, without the other keys of the group, when focus follows mouse is turned off, and with everything else when the daemon stops |
| `$XDG_CONFIG_HOME/kwinrc`, group `[Round-Corners]` | the settings of the border effect, written when borders are on ([KWin effects](#kwin-effects)) | put back, with the rest of `kwinrc`, when borders are turned off and when the daemon stops |
| `$XDG_CONFIG_HOME/kwinrc`, group `[Effect-kwin4_effect_geometry_change]` | the settings of the animation effect, written when animation is on | put back as above, when animation is turned off and when the daemon stops |
| `$XDG_RUNTIME_DIR/komorebi/kwinrc-backup.json` | the value each key of `kwinrc` had before komorebi first changed it | removed when the values are put back; one a crash left behind is used by the next run |
| `$XDG_RUNTIME_DIR/komorebi/bridge.js` | the script KWin loads, with its configuration (the D-Bus names and the hold time of `Poll`) on its first line | written at every start; the directory is removed at logout |
| `$XDG_RUNTIME_DIR/komorebi/komorebi.sock` | the command socket | bound once the daemon is connected to KWin, after a file left there is removed; removed when the daemon stops |
| `$XDG_RUNTIME_DIR/komorebi/NAME` | the socket of a subscriber, which the subscriber binds and names in its subscription | removed by the daemon, with the subscriber, when it cannot connect to it |
| `$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 |
| `/run/current-system/sw/share/kglobalaccel/komorebi-*.desktop` | on NixOS, the static shortcuts of `services.komorebi.keybindings`, which the module compiles at build time into the package `komorebi-keybindings` | the system's: KWin reads them when the session starts |
| `$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` 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)).
## 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
`/run/current-system/etc/systemd/user/komorebi.service`, where the NixOS module's unit is. Whether
the daemon is running is whether `komorebi.sock` in the runtime directory takes a connection, and
the session is the environment of the command itself: `XDG_CURRENT_DESKTOP` has to name KDE, and
`XDG_SESSION_TYPE` or `WAYLAND_DISPLAY` Wayland.
The effects are looked for where KWin looks, which is not where the shell that runs the command
looks: KWin is started by the session, with a `QT_PLUGIN_PATH`, an `XDG_DATA_HOME` and an
`XDG_DATA_DIRS` of its own. `komorebic check` reads them from `/proc/PID/environ`, PID being what
the bus says owns `org.kde.KWin`, and falls back to its own environment and to the places NixOS and
the common distributions put plugins and data. The border effect is a plugin file,
`kwin/effects/plugins/kwin4_effect_shapecorners.so`, in a Qt plugin directory, and the animation
effect a script, `kwin/effects/kwin4_effect_geometry_change/contents/code/main.js`, in a data
directory, where KWin takes the user's before the system's. A build is komorebi's by what it
contains: the plugin file has the name of the interface `org.komorebi.BorderColours1` (or its object
is on the bus), and the script reads a setting called `Curve`.
## Environment variables
### `DBUS_SESSION_BUS_ADDRESS`
The address of the session bus. If it is not set, komorebi uses `$XDG_RUNTIME_DIR/bus`, where
systemd puts the session bus, and `/run/user/<uid>/bus` when `XDG_RUNTIME_DIR` is not set
either. An address with no bus behind it is the first error under [No KWin](#no-kwin), and the one
`komorebic check` reports as "could not connect to the session bus".
### `KOMOREBI_CONFIG_HOME`
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. Environment
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`
The runtime directory of the user, normally `/run/user/<uid>`: komorebi writes the bridge to
the `komorebi` directory in it, and binds its command socket there.
### `XDG_CONFIG_HOME`
Where the user's `kwinrc` is: `$XDG_CONFIG_HOME/kwinrc`, or `~/.config/kwinrc` when it is not
set. Without either, komorebi leaves per-output virtual desktops as they are and logs that it
found no configuration directory.
### `XDG_CONFIG_DIRS`
Where KConfig looks for the system's `kwinrc` when the user's has no value: komorebi reads
`PerOutputVirtualDesktops` the same way, from the user's file and then from the first of these
directories that has it (`/etc/xdg` when the variable is not set), and changes nothing when the
setting is on already.
### `XDG_DATA_HOME`
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`
KWin's own variable, read by KWin and not by komorebi. With software rendering, which is all a
virtual machine has, KWin loads no effect that animates, Geometry Change included, unless it is
`1` in KWin's environment: at time of writing (2026-10-27) a guest loaded 11 effects without it and
29 with. The VM nodes set it ([Rendering](#rendering-in-virtual-machines-and-over-rdp)); a machine
with a GPU needs nothing.
### `RUST_LOG`
Which log lines the daemon prints, in the syntax of `tracing-subscriber`'s `EnvFilter`
(`komorebi=debug`, `komorebi::kwin=trace`). If it is not set, `--log-level` sets it to
`komorebi=<level>`; `--log-level` defaults to `info`.
### `RUST_LIB_BACKTRACE`
Whether an error carries a backtrace. komorebi sets it to `1` when it is not set.
### `NO_COLOR`
When set to anything but the empty string, the log the daemon prints on its standard output
has no ANSI colors, which is what standard output redirected to a file wants. The VM tests
set it. The log files are not affected: one has colors and the other none.
## The autostart entry
At time of writing (2026-10-27), on a Plasma session of a NixOS machine, systemd's autostart
generator makes a user unit of the entry `komorebic enable-autostart` writes,
`app-komorebi@autostart.service`, when the user manager reloads (`systemctl --user
daemon-reload`), and starting that unit starts a daemon that follows the file the entry gave it
(`vm-module`, which does this on x86_64). The test starts the unit by hand, since the session it
runs in has logged in already: it does not show that the next login starts it.
## Watching the configuration
The daemon watches `komorebi.json` with `hotwatch` 0.5, over `notify` 6.1, which on Linux is
inotify. At time of writing (2026-10-27) a change to the file reaches the daemon about two
seconds later, the delay of `hotwatch`'s debouncer, whether an editor wrote the file in place or
renamed a new file over it: `the_daemon_follows_the_file_it_is_given_when_the_file_changes` does
both, on aarch64 Linux. A file the daemon cannot read after a change is logged and leaves the
configuration it has.
## The bridge's environment
What the KWin scripting API offers a script, and what it does not, at time of writing
(2026-10-27). The bridge is written around these, and
[`kwin-api.d.ts`](../../komorebi/src/kwin/kwin-api.d.ts) declares the part of the API it
uses, which `tsc` checks it against with ECMAScript 2016's library and nothing else. Node and
TypeScript are needed only for those checks: in the session the bridge needs KWin alone.
- A window's `opacity` is a number from 0 to 1 that a script may set: `Window.opacity` is KWin's
own property, so komorebi sets the opacity of a window by setting it, and the effect that
draws the border has to draw the window again when it changes
([The patches](#the-patches)).
- `callDBus` sends a JavaScript number as a 32-bit integer, and a call whose arguments do not
match the method's signature fails without a word. The bridge sends every argument as a
JSON string.
- The callback of `callDBus` is called on success only. A call that fails (the daemon has
exited) is never answered, so the bridge re-issues `Poll` from a one-second `QTimer` when
the last one is older than the hold time plus 3 seconds.
- There is a `QTimer`, but no `setTimeout`, and no `Qt` global: a rectangle is assigned as a
plain `{x, y, width, height}` object.
- KWin activates a new window before it announces it (`windowActivated` comes before
`windowAdded`). The bridge announces a window it has not seen when it is activated, so that
no event names a window before the event that announces it.
- A script's `print()` goes to KWin's log, which shows it only when the `kwin_scripting`
logging category is enabled (`QT_LOGGING_RULES="kwin_scripting.debug=true"`, as the VM
tests do).
- A drag of a window by the user is `interactiveMoveResizeStarted` on the window, then a
`frameGeometryChanged` for every frame the pointer moves it by, then
`interactiveMoveResizeFinished`. While it goes on, the window's `move` or `resize` is true,
which tells the two kinds apart. A drag injected as pointer input in a KWin 6.8 session gave
the start, 25 geometry changes and the finish.
## How clients answer a frame
KWin applies a frame komorebi asks for at once, and then the client decides what size it
draws at; the frame KWin reports afterwards (a `geometry` event) is the one the client
chose. Measured at time of writing (2026-10-27) in a headless KWin with eight clients, by the
VM test `vm-client-geometry`, and by the spikes before it with more sizes and at a scale of
1.25:
| Client | Answer | In `vm-client-geometry` |
|---|---|---|
| Konsole, Kate, Dolphin (Qt, KDE) | exactly the frame asked for, also below the minimum size they report (spikes) | Kate asked for 948x527, has 948x527 |
| `xterm` on XWayland | exactly the frame asked for | asked for 229x259, has 229x259 |
| `foot` | sizes itself down to whole cells of its font | asked for 1905x2140, has 1902x2129 |
| GTK 4 Text Editor | exactly the frame asked for, down to its minimum of 360x200 | asked for 469x528, has 469x528 |
| GTK 4 Calculator | never below its minimum of 360x616 | asked for 469x259, has 469x616 |
| Firefox | never below its minimum width of 500 and height of 120 | asked for 230x259, has 500x259 |
Every client keeps the position it is asked for, also one partly off the screen. A fractional
scale of 1.25 gives the same answers as 1.0: every whole logical frame comes back as it was
asked for. komorebi does not ask again when a client keeps to a size of its own: the window
manager reads the frame the window has from the table, and a window larger than its tile
covers part of its neighbor's.
KWin moves a window anywhere it is asked to, off the screen too, but when it *resizes* a window
it keeps 100 pixels of it on an output, and it does that once the client has drawn at the new
size. A window that is moved off the screen and resized at once, as the scrolling layout does
with the columns out of view that change width, is pulled back onto the screen a moment later; so is one whose
client rounds the size, as `foot` does. The bridge therefore remembers the position it was asked
for, for a second, and when the window's frame changes to another position in that time, asks
for the position again, which is a plain move. It tries three times at most, so a window that
cannot go where it was asked is left alone. A maximize makes the bridge forget the position: the
window's frame then changes to the work area, which is not where it was last asked to be. The VM
test `vm-scrolling` checks that the columns out of view stay where komorebi put them.
The same holds for a frame the user asks for. While the user drags an edge of a window, KWin reports
at every step of the drag the frame the pointer asks for (`interactiveMoveResizeStepped`), and the
window's frame follows once the client has drawn at that size. When the user lets go, the frame can
be well short of where they took the edge: at time of writing (2026-10-27), in the spikes, the frame
at the end of a 72-pixel drag of a terminal's edge had moved 12 or 48 pixels. KWin goes on reporting
the client's frames after the end of the drag: in a run of `vm-drag-resize` at time of writing
(2026-10-28), a frame of 660 pixels, which is what `foot` had drawn of the 672 asked for, came 1 ms
after the end, and the window manager, busy with an earlier event, handled the end 17 ms after that.
The bridge sends the frame of the last step with the end of the drag, and the end of a resize is
that frame, which the daemon keeps apart from the frames that follow. It also passes the steps on,
one every 16 ms at most, so that the tiles next to the edge follow it while it is dragged; the VM
test `vm-live-resize` reads them while the button is still down. KWin's window snapping applies to
the edge the user drags, and the tiles that follow it are close to it: at time of writing
(2026-10-27), in `vm-drag-resize` with the default paddings (a gap of 10 pixels between two tiles)
and KWin's default snap zone of 10 pixels, a dragged edge once ended 9 pixels past the pointer. The
drag VM tests set KWin's snap zones to 0. The VM test `vm-drag-resize` drags edges in a Plasma
session with a pointer device that the session node makes with uinput.
## Outputs that change
Measured by the VM test `vm-hotplug` at time of writing (2026-10-27), in a headless KWin 6.8.1
with two outputs of 1920x1080:
- `kscreen-doctor output.<name>.scale.1.5` gives an output the geometry 1280x720. That is what
the script reports and komorebi tiles in: every coordinate komorebi uses is KWin's logical
one. At that scale `kdotool` prints window frames in fractions of a pixel (a width of
695.3333), which the VM library rounds.
- `kscreen-doctor output.<name>.disable` is how a headless KWin loses an output, and `enable`
how it gets it back. The script reports the outputs that are left after the first and all of
them after the second, and komorebi follows both. A disabled output is enabled again by the
name it had.
- A window that a script moves so that the middle of its frame is on the other output is on
that output: `Window.output` follows the middle of the frame (found in the spikes with two
outputs on KWin 6.8.1). Its desktops are not changed by the move, so it stays on the desktop
it was on. KWin raises `outputChanged` for it, which `vm-hotplug` shows by moving windows with
`kdotool windowmove`, as a shortcut or the window menu would.
## Sleep and lock
At time of writing (2026-10-27), a real suspend and resume is not tested: the QEMU guests the VM
tests run in have no way to wake from one. The signals are tested on private buses
(`komorebi/tests/power.rs`), and the lock screen against a real KWin in a Plasma session
(`vm-lock-sleep`, which locks and unlocks with `loginctl lock-session` and `unlock-session`).
## How long a retile takes
Measured by the VM test `vm-latency` at time of writing (2026-10-27), in a headless KWin 6.8.1
under HVF on an Apple silicon Mac, with ten `foot` windows on a 3840x2160 output: twenty
retiles (a window minimized and brought back, ten times over), each of which moved 5.5 windows
on average. From the daemon's answer to `Poll` to the last frame KWin reported for the windows
the batch moved, the client's answer included:
| p50 | p95 | max |
|---|---|---|
| 17.3 ms | 27.7 ms | 31.4 ms |
The spikes measured the channel alone, with twenty windows in each batch, at 16, 19 and 20 ms
([DESIGN.md](DESIGN.md#why-do-commands-go-to-the-bridge-as-the-answer-to-a-held-call)).
## KWin effects
An effect is a plugin of KWin's compositor that changes how windows are drawn. The flake
builds the effects komorebi drives as packages of their own, from source, with komorebi's
patches (see [The patches](#the-patches)):
| Package | Effect | Plugin id | Installed as |
|---|---|---|---|
| `kde-rounded-corners-komorebi` | [KDE Rounded Corners](https://github.com/matinlotfali/KDE-Rounded-Corners) 0.11.0, which draws an outline around each window | `kwin4_effect_shapecorners` | a C++ plugin, `lib/qt-6/plugins/kwin/effects/plugins/kwin4_effect_shapecorners.so` |
| `kwin-effect-geometry-change-komorebi` | [Geometry Change](https://github.com/peterfajdiga/kwin4_effect_geometry_change) 1.5 (revision `398491e`), which animates a window that a program or a script moves or resizes | `kwin4_effect_geometry_change` | a scripted effect, `share/kwin/effects/kwin4_effect_geometry_change/` |
Each package is in the flake's `packages` for Linux and in `overlays.default`, which builds it
with the `callPackage` of the nixpkgs it is applied to, so that it follows that nixpkgs' KWin.
[`nix/tests/effects.nix`](../../nix/tests/effects.nix) has a check for each, which builds the
package and inspects its files the way KWin finds them, without a session.
At time of writing (2026-10-27):
- **KWin finds effects only when it starts.** An effect installed while KWin runs cannot be
loaded (`isEffectSupported` is false and `loadEffect` returns false) until KWin starts
again, which in a session means logging out and back in.
- **KWin loads every effect that is enabled by default when it starts**, with the settings
the effect has then. KDE Rounded Corners 0.11.0 is enabled by default in its
`metadata.json`, and at its defaults it draws a one pixel black outline inside every
window, over its title bar. The package builds it with `"EnabledByDefault": false`: KWin
starts without it (`loadedEffects` lists the built-in effects only), `isEffectSupported`
is true, and `loadEffect` with `kwin4_effect_shapecorners` on `org.kde.KWin`'s `/Effects`
loads it. The metadata is compiled into the plugin, which is where the check reads the
flag, with `qtplugininfo`.
- **KDE Rounded Corners 0.10.0 draws the outline about 24 px too low on KWin 6.8**: across
the title bar at the top, the same distance below the frame at the bottom, and in the right
place at the sides. KWin 6.8 inverted the texture coordinates of the offscreen window, and
Breeze's shadow is deeper below a window than above it; the error is the difference of the
two. 0.11.0 is the release that handles it. nixpkgs `d3b13ad` (2026-10-24) has 0.10.0 and
`f05535a` (2026-10-27) has 0.11.0, which the package here sets as well.
- **KDE Rounded Corners links `libkwin.so.6`**, so it is built against the KWin that loads
it. With the package in a NixOS system's `environment.systemPackages`, KWin finds the
plugin in `/run/current-system/sw/lib/qt-6/plugins/kwin/effects/plugins/`, and the plugin
links the libkwin of the store path the running `kwin_wayland` comes from. The check
asserts the same for the `kdePackages.kwin` of the flake's nixpkgs: the first directory of
the plugin's `RUNPATH` that has `libkwin.so.6` is that KWin's `lib`.
- **KDE Rounded Corners draws its outer outline in the window's shadow**: its shader stops
where the window's texture is transparent. A window without a shadow has no outer outline,
and the outline is at most 20 px thick.
- **Geometry Change ships disabled by default**: its `metadata.json` has
`"EnabledByDefault": false`, which the check asserts. It loads on `loadEffect`, and under
software rendering only with `KWIN_EFFECTS_FORCE_ANIMATIONS=1` in KWin's environment (see
[Rendering](#rendering-in-virtual-machines-and-over-rdp)): without it, a session in a
virtual machine loads 11 effects instead of 29.
- **Geometry Change animates what a program or a script asks for**: a move and a resize made
through KWin's scripting API are animated, and by its source an interactive move or resize
is not. The stock effect always eases out exponentially (`QEasingCurve.OutExpo`), so the
movement is nearly over after a third of its duration. Its settings are in the
`[Effect-kwin4_effect_geometry_change]` group of `kwinrc` (`Duration`, `CrossFade`,
`ExcludedWindowClasses`, and `Curve` with komorebi's patch), and it reads them again on
`reconfigureEffect`: a `Duration` of 4000 written while it ran was the length of the next
animation.
- **The animation moves what is painted, not the window**: the frame KWin reports for the
window (`frameGeometry`) is the final one from the start of the animation.
### What komorebi writes for the border
KDE Rounded Corners reads its settings from the group `[Round-Corners]` of `kwinrc` (the names are
those of the effect's `options.kcfg`). komorebi sets every outline, not only the one it uses:
| Key | Value |
|---|---|
| `OuterOutlineThickness`, `InactiveOuterOutlineThickness` | the border's width, 0 to 20 |
| `OuterOutlineColor`, `InactiveOuterOutlineColor` | `r,g,b`: the focused window's border, and every other window's |
| `Size`, `InactiveCornerRadius` | the corner radius |
| `OutlineThickness`, `InactiveOutlineThickness`, `SecondOutlineThickness`, `InactiveSecondOutlineThickness` | `0`: nothing inside the window |
| `ActiveOuterOutlineAlpha`, `InactiveOuterOutlineAlpha` | `255` |
| `ActiveOuterOutlineUseCustom`, `InactiveOuterOutlineUseCustom` | `true`, so that the colors are komorebi's |
| `ActiveOuterOutlineUsePalette`, `InactiveOuterOutlineUsePalette`, `OuterOutlineIsGradient`, `InactiveOuterOutlineIsGradient` | `false` |
komorebi then calls `reconfigureEffect` on `/Effects`: at time of writing (2026-10-27), KWin 6.8.1
hands an effect the copy of `kwinrc` it read when it started, so the new values reach it only
that way, also for an effect loaded a moment before. A screenshot of a session shows the border
in the pixels just outside the frame the window has in KWin, on all four sides, in the focused
and unfocused colors, and not inside the frame.
### The patches
Each patch is a derivative work of the effect it changes, and is under the same license, the
GNU General Public License version 3; its header states the license and describes the
change. The check of a patched package asserts that the patch is in the build.
[`komorebi-border-colours.patch`](../../nix/kde-rounded-corners/komorebi-border-colours.patch),
for KDE Rounded Corners, makes two changes:
- **A color for each window.** The stock effect has one outline color for the active window
and one for the others. The patched effect exports an object through KWin's name, which
takes a color for each window:
| Name | Object | Interface | Member |
|---|---|---|---|
| `org.kde.KWin` | `/org/komorebi/BorderColours` | `org.komorebi.BorderColours1` | `SetColours(asau)` |
`SetColours` replaces the colors of every window at once: the windows' UUIDs as KWin writes
them (with or without braces), and `0xRRGGBB` values in the same order. A window it does not
name gets the colors of the settings for the active and the other windows. The object is
registered when the effect is loaded, and removed with every color when it is unloaded.
- **A window is drawn again when its opacity changes.** The effect draws a window from a
texture that has the window's opacity in it, and makes the texture again only when the
contents change or the window is resized, so a change of opacity alone would not show. The
patched effect redirects the window again when its opacity changes.
[`curve.patch`](../../nix/kwin-effect-geometry-change/curve.patch), for Geometry Change, adds
a `Curve` setting to the effect's group: the name of any of Qt's easing curves (`OutExpo`,
`InOutSine`, ...), read with the effect's other settings and used for every animation. An
unknown or missing name is the stock effect's curve, `OutExpo`. The check asserts that the
script reads `Curve` and that the effect's settings declare it.
### What komorebi writes for the animation
Geometry Change reads its settings from the group `[Effect-kwin4_effect_geometry_change]` of
`kwinrc`:
| Key | Value |
|---|---|
| `Duration` | the animation's duration, in milliseconds |
| `CrossFade` | `false`: a window that changes size is not cross-faded |
| `Curve` | the name of a Qt easing curve (`Linear`, `OutExpo`, `InOutSine`, ...): komorebi's build of the effect reads it, and the stock effect ignores it |
komorebi then calls `reconfigureEffect`, and at time of writing (2026-10-27) the effect uses the
new `Duration` for the next move: a `Duration` of 4000 written while it ran was the length of the
next animation. An animation cannot be seen in a screenshot of a short one: the screenshot takes
seconds, and the effect eases out exponentially, nearly over after a third of its duration. A
screenshot of a session a few seconds into a 30 s animation shows a window that has not got to its
place, and the same move with animation off is there at once.
## The Plasma shell
The wallpaper of a screen is the Plasma shell's, not KWin's: the shell, `plasmashell` on the
session bus as `org.kde.plasmashell`, keeps one wallpaper for each screen, not for each virtual
desktop. At time of writing (2026-10-27) komorebi asks it three things over `/PlasmaShell`, in
`org.kde.PlasmaShell`, for the output a workspace's monitor is (the name KWin gives it, `DP-1`):
1. `evaluateScript("print(screenForConnector(\"DP-1\"))")`: the number the shell gives the
screen, which it numbers itself and names by connector; `-1` when it has none. The name goes
into the script as a JSON string.
2. `wallpaper(screen)`: what the screen shows, as `a{sv}`, in which `wallpaperPlugin` is the
plugin (`org.kde.image` for a picture), `Image` the picture's URL and `FillMode` a Qt
`Image.fillMode` (2 is `PreserveAspectCrop`: the picture fills the screen and is cropped where it
does not fit).
3. `setWallpaper("org.kde.image", {Image: URL, FillMode: 2}, screen)`: what
`plasma-apply-wallpaperimage` calls, for one screen. It is made only when the answer to 2 is
not already the picture, in that plugin, with that fill.
The URL is `file://` and the path, with every byte but an ASCII letter or digit, `-`, `.`, `_`, `~`
and `/` percent-encoded, so a path with a space in it works. A session with no Plasma shell (a
headless one, or one with another shell) has no such name on the bus: every call fails, and komorebi
tries again, then leaves wallpapers alone ([DESIGN.md](DESIGN.md#why-is-the-wallpaper-set-in-the-background-and-tried-again)).
## Rendering in virtual machines and over RDP
At time of writing (2026-10-27):
- A headless KWin cannot render. Mesa's software rasterizer needs `CREATE_DUMB` on the
primary DRM node and the virtual backend offers only the render node, so KWin reports that
compositing is active while every frame fails, and screenshots are black. KWin does not start at all with no DRM
device. The VM nodes give the guest a `virtio-gpu` device for that reason.
- In a QEMU guest everything is drawn in software (llvmpipe on the guest's CPUs): the
nixpkgs QEMU has only the 2D `virtio-gpu`. KWin then refuses to load animating effects
unless `KWIN_EFFECTS_FORCE_ANIMATIONS=1` is in its environment, which the VM nodes set.
- KRDP 6.8.1, Plasma's RDP server, does not start without a TLS certificate and key, although
its `--help` says it generates one; it logs the error and keeps running with nothing
listening. `xrdp` is not an option, since there is no X11 session to start.
- A guest can have OpenGL through the host's GPU. At time of writing (2026-10-28), the demo guest
started under KVM with `-display gtk,gl=on -device virtio-vga-gl` on an X server (Xvfb) whose
OpenGL is Mesa's llvmpipe, with QEMU 11.1.2 and Mesa 26.2.5 from nixpkgs: KWin drew with the
driver `virgl`, and the guest's renderer string was `virgl (LLVMPIPE (LLVM 21.1.8, 256 bits))`.
The guest names its own driver whatever the host renders with, so it cannot tell a host GPU
from a host software renderer. QEMU's `screendump` answers "no surface" with `virtio-vga-gl`: the picture
has to be read from the window. `-display egl-headless` needs a DRM render node and stops at
startup without one ("egl: no drm render node available", on the machine of these runs, which has
none). A GPU that renders is not measured here.
### RDP into the session
The session guests to develop in ([utm.md](utm.md)) run KRDP as a user unit of the session,
[`nix/dev/krdp.nix`](../../nix/dev/krdp.nix): `krdpserver --plasma`, which asks KWin for the
screen and for input through its own Wayland protocols (KRDP's desktop file lists
`zkde_screencast_unstable_v1` and `org_kde_kwin_fake_input`), so no portal asks the user first. The
unit makes a self-signed certificate, and logs in the session's user with a password the user
writes to a file, or that a guest takes from the host (the demo guest); without a password file it
does not start. At time of writing (2026-10-27), with KWin
and KRDP 6.8.1 and FreeRDP 3.32.2:
- KRDP sends the screen as H.264 only, encoded with x264 in software when there is no VAAPI device
(Constrained Baseline, level 6.0), and every frame is encoded on the guest's CPUs.
- FreeRDP decodes H.264 with OpenH264 when it is built with it, as nixpkgs builds it, and OpenH264
decodes nothing of KRDP's video: it reports a bitstream error on the first frame
(`DecodeFrame2 state: 0x0004`) and no picture after it, and the client's window stays black.
FreeRDP built without OpenH264 decodes with FFmpeg, and shows the desktop: the guests install that
build.
- The VM suite `rdp` checks, in the session node under KVM: that the unit does not start before it
has a password and listens on port 3389 once it has one (a listener in the guest, which `ss`
sees: QEMU's port forwarding accepts a connection whether or not anything listens behind it);
that FreeRDP's client is let in with the password and not with another (`/auth-only`); and that
the picture the client gets, on an X server of its own, is the display: thousands of colors,
within 16 of 255 on average of a screenshot taken right after it (6.7 and 6.6 in two runs, 2.9
seconds after the client started). The VM suite `run-kde` runs the same checks against the
demo guest, whose password comes from a directory of the host that the guest's user cannot
read: the guest copies it before the login, and KRDP starts by itself.
- Keys over RDP are not verified end to end. KRDP injects them into KWin through
`org_kde_kwin_fake_input`, which, read from the sources, puts them through the input pipeline
of KWin that KDE's global shortcuts are part of. No test sends one: aardwolf, a client that can
script keys, fails NTLM against KRDP, FreeRDP's client cannot script keys, and a client inside
the session would send each key back to itself. Whether a key pressed in an RDP client reaches a
global shortcut is therefore not known; no check from a real client has been recorded.
## WSL 2
`run-kde` is written for NixOS in WSL 2 on Windows 11 with an AMD CPU and an x86_64 guest, and
nothing in this section has been measured on that machine yet. The table says what the command
expects and what is still to be recorded, as dated facts, from the probe
(`scripts/wsl2-probe.sh`) when somebody runs it there. The facts that were measured on a Linux machine
with KVM and no WSL, window or GPU are in [Rendering in virtual machines and over
RDP](#rendering-in-virtual-machines-and-over-rdp).
| Probe | What the command expects | Result |
|---|---|---|
| KVM | `/dev/kvm` is there with `nestedVirtualization=true` in `.wslconfig`, the CPU flags show `svm`, and the user is in the group `kvm` | to be recorded |
| KVM | QEMU with `-accel kvm` boots a kernel; how fast a CPU loop runs in the guest against WSL | to be recorded |
| Display | `WAYLAND_DISPLAY` or `DISPLAY` is set by WSLg, and QEMU's GTK window opens | to be recorded |
| Display | the keyboard and the pointer work in the window, and Ctrl + Alt + g grabs and releases them; the frame rate of a moving window | to be recorded |
| GPU | `/dev/dxg` is there, `wsl.useWindowsDriver = true` is in effect, and the host's OpenGL renderer string is d3d12 and not llvmpipe | to be recorded |
| GPU | `-device virtio-vga-gl -display gtk,gl=on` starts, and the guest's renderer is virgl; the frame rate with and without it | to be recorded |
| RDP | `localhost:3389` in Windows reaches the guest; Windows' client shows a picture of KRDP's H.264; keyboard layouts survive | to be recorded |
| Resources | free memory and disk in WSL, the values of `.wslconfig`, the time to build the guest, the size of its closure | to be recorded |
| virtiofs | `virtiofsd` starts as the user and serves `/nix/store` and a directory; the guest mounts both through virtio-fs devices, with its memory in a shared memfd, reads the store, and reads and writes the directory | to be recorded |
### The VM suites on WSL 2
Measured on 2026-10-28 on the machine `run-kde` is written for: Windows 11, a Ryzen 9 5900X (24
threads for WSL 2), 31 GB of memory for WSL 2, NixOS-WSL with `nestedVirtualization=true` and
`/dev/kvm` writable by the build users, so the suites ran under KVM inside Hyper-V. These are the
wall times of `nix build .#checks.x86_64-linux.vm-NAME` from a warm store, the boot of the machine
included. Another VM was running for some of the non-timing suites, and none was for the timing
ones.
| Suites | Wall time | Result at `scale` 1 |
|---|---|---|
| `kwin` | 5 min 21 s, with the guest's Mesa and QEMU built | pass |
| `core-e2e` | about 5 min | pass |
| `drag-resize`, `live-resize`, `lock-sleep`, `look` | 1 to 3 min each | pass |
| `keys-engine`, `keys-skhd`, `keys-static`, `keys-sxhkd`, `keys-whkd` | 1.5 to 2 min each | pass |
| `features` | about 4 min | pass |
| `latency` | 2 min 53 s | fail: p95 128.9 ms, p50 46.0 ms, max 137.4 ms |
The 20 other suites passed too, two at a time. `latency` is the only one that failed at `scale` 1:
its p95 is held to 100 ms times `scale`, and nested virtualization is slower to the tail than x86-1
was. `scale` is 1.5 for every Linux host now (`flake.nix`), and `latency` passed at it with a p95 of
132.4 ms against 150 ms, p50 70.0 ms and max 206.5 ms. The two runs differ by more than the margin
that is left, so a suite that fails on its p95 here may be noise, and a second run says which.
What is known of virtiofs without WSL 2 (nixpkgs' runner mounts the host's `/nix/store` and the
shared directories by virtiofs on a Linux host), at time of writing (2026-10-28): the chain that
the probe's P6 builds, `virtiofsd` 1.14.0 started as an ordinary user with the runner's options, and
a guest that mounts the host's `/nix/store` read-only and a directory read-write, passes on an
`x86_64` machine with KVM, on an `aarch64` machine and under TCG. `virtiofsd` prints two warnings
as an ordinary user (it cannot raise the limit of open files, and it cannot use file handles) and
never opens `/dev/fuse`. A file owned by the host user shows up in the guest with the same numeric
uid. The kernel configuration of WSL 2 (`linux-msft-wsl-6.6.y`, read, not run) has
`CONFIG_FUSE_FS=y`, `CONFIG_MEMFD_CREATE=y`, `CONFIG_USER_NS=y` and `CONFIG_KVM_AMD=m`.
One thing that the command depends on is not in the probe, and is not known either: whether
Windows or WSLg takes any of the Alt combinations of the key bindings before the window sees them.
## What was not measured
At time of writing (2026-10-28) these are gaps, not findings. Nothing on this page says that
they work or that they do not.
- KWin before 6.8: only 6.8.1 and 6.8.2 were run ([KWin 6.8 or newer](#kwin-68-or-newer)).
- Activities.
- More outputs than a second one to the right of the first: the geometry was checked, the
pixels were not.
- Whether a window of a Qt or KDE application is drawn smaller than the minimum size it reports,
or overflows its frame: the frames were measured, not the pixels
([How clients answer a frame](#how-clients-answer-a-frame)).
- What a window on the parking desktop does to the task manager and the overview, and whether
hiding and showing windows flickers. By construction a parked window stays in the task manager
unless the task manager shows only the current desktop.
- The rule identity of an application in a sandbox (Flatpak), which comes from
`/proc/<pid>/exe`; the `class` and the `pid` were checked.
- A real suspend and resume ([Sleep and lock](#sleep-and-lock)).
- A key pressed in an RDP client ([RDP into the session](#rdp-into-the-session)).
- Whether the progress of the stock Geometry Change effect follows `QEasingCurve.OutExpo` against
the clock in a session: one capture four seconds into a 30 s animation showed no progress, where
the curve gives about 60 % ([KWin effects](#kwin-effects)). The log evidence and the comparison
with animation off do not depend on it.
- Graphics other than llvmpipe: every render measured was in software.
- WSL2: KVM, a QEMU window through WSLg, the Windows GPU as OpenGL in WSL, a port that
Windows reaches in WSL, and `virtiofsd` serving a guest's `/nix/store`. The probe that measures
them ([wsl2-probe.md](wsl2-probe.md)) has not run on WSL2.
- The scrolling layout on a monitor that has another beside it. A strip spills onto the
neighbor when that monitor shows the same workspace number, and a window whose middle is on a
monitor that shows another desktop is not drawn. This is read from KWin's sources, not
checked with pixels. The layout no longer leaves a window there: one that would rest or
overhang past an edge with another monitor next to it is hidden, or cut down to its own work
area ([scrolling-next.md](scrolling-next.md)), which only the fake desktop has run.
+86
View File
@@ -0,0 +1,86 @@
# The contract of a Platform
A shared scenario (`nix/tests/vm/lib/komorebi_vm/core/scenarios`) runs on KDE here and on
Windows in kfw's guests, through the `Platform` protocol (`core/platform.py`). A check
that one port answers by how its implementation happens to work, and the other by what
the system says, passes on one port for the wrong reason. This file lists what each member
promises to both ports, and the quirks of each port that a scenario must not lean on. The
docstrings of `Platform` are the contract; this is the audit behind them.
## What each member promises
| Member | Both ports promise | Quirk a scenario must not depend on |
| --- | --- | --- |
| `has(feature)` | `"pointer"`, `"lock"`; a scenario that needs one is skipped, with the reason, where it is false | KDE has `lock` only in a real Plasma session (`session=True`); Windows has both always |
| `tolerance` | how far a frame may be **short** of the one asked for; the frame is never past it | KDE 24 px (a terminal's cells), Windows 2 px (rounding). It bounds what a client rounds to; it is not a measure of a change, so a scenario asks the daemon's layout for the change (`support.layout_rect`) and then that the frame follows it within the tolerance |
| `wait_for(p, t)` | polls `p` until it holds or `t` seconds, scaled for the host | Windows turns a `RuntimeError` of a `komorebic` call in `p` into a false; KDE lets it raise. A predicate answers false for what it cannot tell yet, and relies on neither |
| `komorebic(...)`, `komorebic_status(...)` | `komorebic` raises if the command fails; `_status` returns the exit status and what it printed | the exception type (`AssertionError` on KDE, `RuntimeError` on Windows): a scenario catches `Exception` or nothing |
| `start_komorebi()`, `restart_with(c)` | the daemon starts from a clean state, with the windows that are open taken up | Windows launches it up to three times; KDE once |
| `rewrite_config(c)` | writes the file the daemon watches; returns before the daemon has read it | the delay before a reload is the daemon's (a scenario waits for the state, or `QUIET` for what must not happen) |
| `spawn(title, app_id, exe)` | opens a window and waits until the system has it; raises if it never does | a title is taken as it is and no window has another's; `exe` is a name of letters, digits, `_` and `-`, without an extension (`exe_id(name)` spells it as the daemon names it: `name` on KDE, `name.exe` on Windows) |
| `os_window(c)` | the system's own frame of the window, or `None`; `focused` is the keyboard focus, for at most one window | the frame of a minimized window is wherever the system keeps it; a scenario does not read it |
| `hidden(c)` | true for a window the daemon put away: a stack's other windows, a workspace that is not shown, behind a monocle. False for a window the system does not have, one that is minimized, one that floats | true on KDE for any window on a virtual desktop that is not shown (with more than one output, the desktop of the active output), on Windows for any cloaked window (another Windows desktop included). A scenario that asks for "put away" also asks `state()` where the window is, and counts "in view" through `support.in_view`, which needs the system to have the window |
| `displays()` | each display's rectangle in the desktop's coordinates, left to right, as the system says | displays are not one size (on Windows the first is the basic adapter, 1280x800, and the second, the only one whose mode can change, is 1024x768 by default and follows `resize_display`) and a scenario does not compute where the next begins |
| `add_display()`, `remove_display()` | plugs a display in to the right, unplugs the last; return when the system agrees | Windows removes only a display `add_display` plugged in (a hotplug port is used once); KDE enables a disabled output and disables the last enabled one, so a headless session with two outputs can unplug at once. A scenario unplugs only after plugging in, unless its suite started with more than one display |
| `work_area()` | the area of the first display that windows may take, as the system says: the display less panels, docks and the taskbar | KDE asks KWin (a script: its placement area), and answers with the whole output only if KWin does not answer. A headless session has no panel, so there it is the output |
| `put_file(path, data)`, `wallpaper(display)`, `set_wallpaper(path, display)` | a file the daemon can read; the picture a display shows; the wallpaper as the user sets it | KDE reads and sets it through the Plasma shell's D-Bus API. Windows: `IDesktopWallpaper`. `restart_with` in a real Plasma session restarts the module's unit with the user's `komorebi.json` |
| `resize_grab(frame, grab)` | where the pointer is pressed to take a window by an edge or corner | KDE: the gap outside the frame on every side (`resize.outside_grab`). Windows: left, right and bottom are the invisible border outside the visible frame; the top has none, so it is inside the frame's top row |
| `close`, `minimize`, `activate`, `move_window` | act on the window as the user would; raise if there is no such window | `close` returns before the window is gone (a scenario waits for `os_window` to be `None`); `move_window` puts the top left of the *visible* frame at (x, y) |
| `lock()`, `unlock()` | lock and unlock the screen and return when it is so | the lock screen is `LogonUI` on Windows and the Plasma greeter on KDE; a scenario asks only what the daemon and the windows do |
| `pointer` | moves in the pixels of the first display; a drag is one press, a glide, one release | a window manager that follows the pointer by a hover delay (Windows) or by its own focus policy (KDE) has to be given time: `focus_follows_mouse.SETTLE` |
| `screenshot(name)` | the display as an image | none |
## Findings of the review, and what was done
1. `work_area()` on KDE was the whole output. **Confirmed.** The headless KWin has no panel so
no suite could tell, but a scenario's "inside the work area" was weaker than on Windows
wherever a panel exists. `KdePlatform.work_area()` asks KWin for the placement area of the
leftmost output (`Kde.screens`, a KWin script like the daemon's bridge uses) and falls back
to the output. Monocle and maximize now also check that their window stays inside it. To
verify on KDE: a suite with a panel (`drag-resize`, `run-kde`) and `core-e2e`; the script
(`workspace.clientArea(KWin.PlacementArea, ...)`) has not been run.
2. `tolerance` is 24 on KDE. **Partly confirmed.** Most uses are right: a frame short of a
tile by up to 24 px, in a tile hundreds of pixels wide. Not right: `resize_commands` checked
that a decrease gave back the width within the tolerance, so a daemon that gave back less
than the increase passed for a terminal. It now compares the daemon's layout and then the
frame. `inside(area)` takes no slack for the tolerance, because a frame is never past what
was asked.
3. `hidden()` is true for any window on a desktop that is not shown. **Confirmed as a
difference, refuted as a source of vacuous passes.** Every scenario that asks for a window to
be put away also asks the daemon where it is (`workspace_of`, `containers`, `monocle`), and
a window that was lost is not in view (`support.in_view`). The docstring now says what each
port is true for. With two outputs on KDE only the first output's windows are certain.
4. `focus_follows_mouse` passed `--implementation windows` and a KWin-sized settle. **Confirmed.**
Both ports' `komorebic` default to `windows`, so the flag is gone, and the settle is a named
wait, `SETTLE`, that is longer than either needs.
5. Constants tuned for KDE. **Confirmed for the 400,300 move of `locking`, the absolute room of
`padding` (5000 and 2000 square pixels), the 60 px drag of `resize`, the first display's
rectangle in `hotplug` (the work area is the right area) and the quiet period of 3 s written
in nine places.** They are now derived from the work area or named (`support.QUIET`).
Checked and found neutral: the `1920`, `foot`, `KWin`, `wayland`, `app_id` and `.exe`
words in the shared scenarios are in comments, or go through `exe_id` and `spawn`.
`locking` also did not check that the window moved, so a platform that could not move it while
locked passed; it does now.
6. Checks that pass for how an implementation answers. **Confirmed**: `spawn` did not raise on
KDE if the window never came (a "stays unmanaged" check then passed for a window that was
not there); `close`, `minimize`, `activate` and `move_window` on a window that is not there
did not raise a message; `displays()` was the size the session was started with and not what
KWin says; a program name that Windows rejects was shell-quoted into KDE; a title was a regular
expression on KDE. All fixed. `os_window().focused` is each system's own answer and
the same in meaning. The frame of a minimized window is not specified (KDE keeps it, Windows
may park it off screen): no scenario reads it.
## Open items
- kfw's `windows_platform.py` builds `Rect(left, top, right, bottom)` for `displays()`, `os_window`
and `work_area()`. Checked with the kfw session: its agent returns the width and height under
`right` and `bottom` (the shape `komorebi` itself prints), so it is `(x, y, w, h)` in kfde's
terms; the names are misleading, not wrong.
- `inside(area)` has no slack. On Windows the DWM frame might round one pixel past; if the
first run says so, the slack is a `Platform` member, not a number in the scenarios.
- KDE `hidden()` with two outputs and per-output desktops answers for the desktop of the active
output only.
- Unverified on KDE, to run: `core-e2e` (work_area, spawn raising, `in_view`, `resize_commands`),
`hotplug` (displays from KWin, `work_area` after an unplug), `drag-resize` (the drag distance,
`focus_follows_mouse` with no flag, work area with a panel), `core-lock` (the move while
locked). On Windows: every scenario above.
+63
View File
@@ -0,0 +1,63 @@
# The rework of the Scrolling layout on upstream's `next`
Upstream (LGUG2Z/komorebi) reworked the Scrolling layout on its `next` branch: a platform-free
model of a strip of columns (`komorebi-scrolling`), the glue that every komorebi shares
(`komorebi_layouts::scrolling`), and, on top of them, columns that hold several windows and the
commands that go with them. This page says, for each of the commits of `master...next` that touch
the layout, what it changes, whether komorebi for KDE (kfde) takes it, and how. The review is of
`next` at `6d862a114` (the revision kfde's `Cargo.toml` pins now).
Two things shape what applies. The model and the platform-free glue live in crates that kfde takes
from upstream by git revision, as it already took `komorebi-layouts`, so a commit that only
touches them arrives with the bump of the revision. And what the glue needs of a window (where it
is, whether it is hidden, how wide it really is) is a call to the backend in kfde, not to Win32.
## Commits of the layout
| Commit | What it changes | kfde |
|---|---|---|
| `9ccf2efce` model of a scrollable strip | New crate `komorebi-scrolling`: columns of tiles, widths (proportion or fixed, limits), heights, view offset, centring (`Never`, `Always`, `OnOverflow`), pan, swipe tracker. No Windows code. Tests in the crate. | **Ported by dependency.** `komorebi-scrolling` is a git dependency at the same revision as the layouts. Its tests are upstream's; kfde tests the glue. |
| `abd4fde3e` lay out with the model | The workspace keeps a `ScrollingSpace` keyed by container id; `update()` places containers from it instead of recomputing equal columns from the last layout. | **Ported** (`komorebi/src/scrolling.rs`, `Workspace::update`). |
| `cb127204c` platform-free glue | `komorebi_layouts::scrolling` (options, `place`, `resize`, hand-over between workspaces), `ScrollingCentering` replaces the `bool` of `center_focused_column`; Workspace methods for focus, order, consume, expel, stack. | **Ported:** the layouts half by the bump, the Workspace half in `komorebi/src/scrolling.rs`. |
| `249709e60` commands and config | Socket messages and `komorebic` commands `consume`, `expel`, `toggle-column-stack`, `scrolling-layout-full-width`, `center-focus`, `expand`; focus, move, resize, retile and close go through the strip. The message says a top level `scrolling` section too. | **Ported**, except the `scrolling` section: neither kfw nor kfde has one (only komorebi for Mac has; COMPARE.md says so). |
| `9ff278eb5` schemas | `center_focused_column` is a boolean or a name; docs for the new commands; `schema.bar.json`. | **Ported:** `schema.json`, `nix/komorebi-options.nix`, `docs/cli/`. `schema.bar.json` is kfw's (kfde has no bar). |
| `2dff53095` room for windows that will not get narrow | After windows are placed, a window wider than its column widens the column (never narrower again, never wider than the screen), for an overhang of 16 px or more. | **Ported, with a different trigger.** kfde cannot ask a window how wide it is right after moving it: the frame comes back from KWin a moment later. The widths are read at the first layout after the frames have settled (`WIDTH_SETTLE`), as upstream does with animations on. Covered by unit tests in `scrolling.rs`; no VM check, because it needs a client that will not get narrower and foot has no minimum width. |
| `e75f3db47` rest windows at the edge | A window out of view rests at the edge it left by with 5 px on screen and keeps its size. | **Ported** (`parked`). On KDE this also keeps the window from being resized while it moves out of view, which is what KWin pulls back (PLATFORM.md). |
| `ab1896330` docs | `docs/usage/scrolling-layout.md`, `mkdocs.yml`. | **Ported**, rewritten for KDE (no animation, no borders at the edges, no touchpad). |
| `1531a892a` more than one monitor | Removes the single-monitor restriction; a window out of view past an edge with a monitor next to it is hidden, not parked; a partly visible one is cut to its work area; a window that comes back is shown first, only the one at the front of a stack. | **Ported** (`rest`, `other_monitors`, `should_restore_when_placed`, from `backend().monitors()` and `Window::hide`). kfde never had the restriction. This answers the open question in PLATFORM.md about a strip that spills onto the next monitor. |
| `abb230b45` spread a stack out | The window that stays in the container is restored; focus stays on the column while the containers are inserted. | **Ported.** |
| `ca22b0f81` refocus after Hide | The `Hide` event arm refocuses like `Destroy`. | **Not applicable.** kfde has no `Hide` event: KWin reports a closed window as a destroyed one, which already refocuses. |
| `f2b72a029`, `f22560464` left edge | Resizing a column by its left edge moves that edge, however far. | **By the bump** (`komorebi_layouts::scrolling::resize`). kfde's drag of an edge goes through the same function, and `LiveResize` keeps the strip (below). |
| `1f658fd90` `pan` | `komorebic pan left\|right` moves the view a column. | **Ported.** |
| `09b99700f` touchpad | `pan --stream` reads whkd's gesture stream; `PanGesture`, swipe tracking, pictures over the windows. | **Not applicable.** whkd and the raw touchpad input are Windows only. The swipe tracker is in the model crate if a KDE input path wants it later. |
| `674ae7937`, `5098ff7b7` resize follows the drag | The neighbours follow a dragged edge; the strip is kept with the rest of what the drag started from. | **The strip part ported:** `LiveResize` keeps and restores `Workspace::scrolling`, or every step of a drag would compound on the widths of the one before. The pictures over windows are DWM. |
| `ce13267e1`, `62628f381`, `2a447208f`, `58693ecd3`, `52ad6be78` | Where a drag is measured from; pictures and ghosts for windows being resized or animated. | **Not applicable.** Ghost windows and DWM. kfde measures a drag from `Backend::drag_origin` already. |
| `e5512ca5d` and the other `animation` and `border` commits | Ghosts, workspace slide, border in ghosts, batches of animations. | **Not applicable** (DWM, ghost windows, borders). The Windows session's. |
| `3b424dd70`, `837ca257d`, `5c8e4770d`, `9b9cad997` | Fixes in config, monitors, rules. | **Not scrolling.** Already in kfde or in the hands of the other sessions. |
## What I could not judge
- Whether the 5 px of a parked window pass KWin's rule of keeping 100 px of a resized window on an
output. The bridge's `settle` asks again for a position up to three times, and a parked window
is not resized to be parked, but only the VM says.
- Whether `Window::hide` of a column that scrolls out of view next to another monitor is fast
enough to follow a scroll without a flash. It is what stacks do.
- The 16 px tolerance of `2dff53095` against the clients of `client-geometry` (`foot` rounds to
cells, which is below it).
## What is tested, and where
- `komorebi/src/scrolling.rs`: the glue against a workspace with no desktop (widths, consume, expel,
moving a column, stacking and spreading out with the windows that are hidden, expanding, panning,
where a window rests, which monitors are the others, what a window that will not get narrow
says). The model itself has its tests in upstream's `komorebi-scrolling`.
- `komorebi/tests/scrolling.rs` and `layout_options.rs`: the commands through
`WindowManager::process_command` against the fake desktop, a strip next to another monitor, and a
drag of the left edge of a column.
- `komorebic/tests/linux_cli.rs`: each new subcommand sends its message.
- `nix/tests/vm/lib/komorebi_vm/core/scenarios/scrolling.py` (`columns`, shared with komorebi for
Windows), run by `vm-scrolling` and `core-e2e`: where the daemon keeps a window at the edge and the
commands of the columns, in a real session. Run on KDE: the `scrolling` suite passes
(32 checks, with `two_monitors`). KWin leaves a window resting at the left edge with its right edge a few pixels inside the
work area, or a cell short of them, because foot rounds its frame to whole cells. The shared
`scrolling` scenario passes in `core-e2e` too.
+275
View File
@@ -0,0 +1,275 @@
# Shared scenarios and platform extras: what moved where
A suite runs shared scenarios (`komorebi_vm.core.scenarios`) and what only its platform can check
(`komorebi_vm.platforms.kde.extras`), with the checks labelled `[shared]` and `[kde]`. This is the
ledger of the checks a suite stopped making because a shared check makes them, so that none is
dropped without a replacement. A check that only KDE can make stays, as an extra.
## hotplug
The suite had its own sections, then ran the shared scenario "the same, through the neutral
platform". The sections the shared scenario repeats are gone; the rest are `kde_hotplug` steps.
| Was (section) | Now |
|---|---|
| 1, the daemon answers with both monitors; three windows on the left; the monitor's size; tiled | extra `setup` |
| 2, the scale of the left output changes and returns | extra `scale` (KDE's scale is not a mode, so the shared `display_change` is skipped on KDE) |
| 3, `move-to-monitor 1`: containers, KWin's `OutputChange`, tiled on the right | extra `sent_by_the_daemon` |
| 4, the user moves a window to the right output | shared `hotplug.user_move` (the suite runs it before the unplug) |
| 5, one monitor after the unplug | shared "after a display is unplugged the daemon has one monitor fewer" |
| 5, all three windows on the left monitor | shared "... the daemon still manages every window", and "every window is on the displays that are left" |
| 5, tiled inside the screen that is left, not on each other | shared "... tiled and clear of each other" |
| 5, the daemon alive, its focus KWin's | extra `after` |
| 6, two monitors again | shared "after a display is plugged in the daemon has a monitor for it again" |
| 6, still three windows | shared "... still manages every window" |
| 6, each window somewhere it can be seen | shared "... each where it can be seen" |
| 7, a window moved to the other output again is followed | shared `hotplug.user_move`, run again after the replug |
| 8, the daemon runs and answers | extra `after` |
Not kept: that the daemon's container count on the left monitor is 3 after the unplug. The shared
scenario checks the managed count and where the windows are, not the count of containers per
monitor. The windows are where the layout puts them, which is what that count stood for.
The suite goes from 25 checks plus the shared ones to 28, which is the shared 11 and 17 of KDE's.
## commands
The suite had its own layout loop (section 2) and then called the shared `layouts`, `sweep` and
`prints`. Nothing the shared scenarios check was removed except as listed; the rest moved to
`kde_commands`, which reads KWin and the daemon's log.
| Was (section) | Now |
|---|---|
| 1, the daemon answers with both outputs; five windows | extra `setup` |
| 2, every layout with five windows: inside the outputs, apart, healthy | shared `layouts`; the extra repeats it at five windows, see below |
| 2, every layout with three, two and one windows | shared `commands.layouts` and `layouts.run` (they close windows from the end and open them again); the extra still goes through the counts for the log check |
| 2, each window where the daemon last asked KWin for it | extra `layouts_by_count` (KDE only: reads the daemon's log) |
| 3, the layouts and the sweep of commands | shared `layouts` and `sweep` |
| 3, `replace-configuration` made the window manager from the file | extra `replace_configuration` |
| 3b, `minimize`, `unmanage`, `manage` | shared `handover`; the check that the unmanaged window is centered is now "inside the work area and not on a tile of the layout" |
| 3c, a title rule decides when the window has its title | shared `title_rule` (the window renames itself through `spawn(rename_to=, after=)`). Not kept: the daemon-log line "should not be managed" for the first title, and `healthy` after it |
| 4, every command that only prints | shared `prints` |
| 4, `komorebic query ...`, `quick-save-resize`, `save-resize` | shared `queries`: each answer is compared with the daemon's state, before and after a focus and a layout change, and a saved resize is undone by loading it (was: exit status only) |
| 5, every window is where the daemon last asked; a clean stop | extra `at_the_end` |
The extra's layout loop still goes through five, three, two and one windows, for the daemon's log
check at each count. It no longer states an overlap verdict: the shared `layouts` makes that one at
every count, with the extra's own check left to say only where KWin has the windows.
## drag-resize
The suite's own cases were all KDE's: the pointer put to the pixel, and eight drags of edges and
corners checked against frames, tiles and neighbors. The pointer check is the extra
`pointer_is_exact`. The eight drags are the shared `resize.edge_cases`, which makes its cases from
the daemon's layout (`latest_layout`) and reads the frames from the operating system, not from
KWin: both sides of an edge two tiles share, a horizontal edge, a corner and an edge of the screen.
With three windows in BSP the cases are the same eight as before. What changed: the wait for the
end of a drag is the layout changing (three seconds at most) and the frames settling, not the
daemon's log line `ResizeEnd`; and the strict checks use the platform's `tolerance` where the extra
used the cell of the font. The shared `resize.run` makes one drag of one edge, as before.
One run of the suite failed `win2:left:-240,0` ("frame R moved -96 but was not dragged": the
terminal's frame four cells short of an unchanged tile) and the next passed; not seen again.
## core-e2e
The suite had sections 1 to 11 of its own, written against KWin and the daemon's log, and then ran
the shared scenarios in section 12 through the neutral platform. Sections 2 to 8 made, with KDE's
tools, the checks the shared `tiling`, `focus`, `moving`, `monocle`, `minimizing` and `closing`
make. They are gone; what only KDE can read stayed, as `kde_core` steps after the shared one.
| Was (section) | Now |
|---|---|
| 1, the script is loaded into KWin, which runs it; the daemon answers | extra `start` |
| 2, every window is where the daemon asked for it | extra `windows_where_asked`, after each shared step that moves windows |
| 2, inside the screen; windows apart; none takes the full width; the daemon manages the three | shared `tiling` ("where the layout says", "do not overlap", "share the work area") |
| 2, KWin and the daemon agree on the focus, by the daemon's log | extra `focus_agrees_with_the_log` |
| 2, the daemon's state focuses the window KWin does | shared `tiling` and `focus` |
| 3, 4, the focus by hand, `focus right/left`, `cycle-focus` | shared `focus` |
| 4, moving the focus moved no window | extra `windows_where_asked` after `focus` |
| 5, `move right`, `cycle-move previous`, the focus kept | shared `moving`; extra `windows_where_asked` after it |
| 6, monocle fills the work area, the state says so, back on the tile | shared `monocle` |
| 6, monocle focus behaviour `cycle` | shared `monocle.focus_behaviour` (also `no-op`: the window keeps the work area); extra `windows_where_asked` after it |
| 7, minimize and restore | shared `minimizing`; extra `windows_where_asked` after it |
| 8, close, the others share the screen, the daemon manages the rest | shared `closing` |
| 8, KWin carried out every command | extra `bridge_did_everything` |
| 9, a clean stop undoes what a monocle did | extra `parking` (opens two windows of its own) |
| 10, a crash with a monocle on leaves nothing stuck | shared `lifecycle_hidden.crash` (every window is managed and in view after the restart, and a monocle works again); extra `parking` keeps the KDE half: the stale parking desktop is there after the kill and the next start removes it |
| 11, KWin restarts under the daemon | extra `kwin_restart` (the `kwin-restart` suite also covers it) |
| 13, `komorebic stop`: the socket, the script, the window stays | extra `stopped` |
Changed on purpose: the lifecycle sections run after the shared scenarios, on windows of their
own, so that the stop and the crash no longer depend on windows a shared scenario left behind. The
daemon's frame log is read after four shared steps, not after every one.
Also learned while moving it:
- `KWin carried out every command` was one check after section 8, over a log of three windows' worth
of commands. After every shared step, over the whole corpus, the bridge logs `could not do` for a
`geo` that targets a window a scenario closed a moment later. That is a race, not a failure, so
the check now counts only a command for a window that is still open, and runs after each shared
step so that a real failure names its scenario. A failure there with the window alive is a
finding.
- After a daemon restart the daemon's focused window can differ from the one KWin has active, and
activating a window KWin already has active sends no event. `parking` activates another window
first. Whether the daemon should pick up KWin's active window at start is not decided here.
## workspace-rules
The suite made, with KDE's tools, the checks that the shared `rules` and `startup_rules` make. It
keeps the part that is KWin's: a workspace is a virtual desktop.
| Was (section) | Now |
|---|---|
| 1, an initial rule sends a window to workspace 1; it is put away | shared `rules` |
| 1, it is on the parking desktop while desktop 1 shows; on desktop 2 once shown, not parked; tiled where asked | extra `desktops` |
| 1, the other window is where it opened (desktop 1) | extra `desktops` |
| 2, the user takes the window back; an initial rule does not send it again | shared `rules` |
| 2, a rule by the name of a workspace (`chat`) sends a window; desktop 3 when shown | shared `rules` (the window goes to the named workspace); extra `named_rule` (parked, desktop 3) |
| 2, a new window is an event that applies the rules again | shared `rules` (a window that opens sends the named-rule window back) |
| 2, `enforce-workspace-rules` sends the initial rule's window again | shared `rules` |
| 3, the rules are cleared; a window that opens stays on the workspace in front | shared `rules` (also: the daemon's global state has no rule); extra `cleared` (desktop of the new window) |
| 4, a `komorebi.json` rule, with a window open before the daemon | shared `startup_rules` |
The extras open windows of their own and close them, so that the shared scenarios start from a
daemon with none.
## placement
| Was (section) | Now |
|---|---|
| 1, no rules: after the one in focus | shared `placement` |
| 2, every window to the primary tile | shared `placement` |
| 3, by the number of the place, as a number and as text | shared `placement` |
| 4, by the app id (`Class`), by the title, and after the one in focus | shared `placement`, its case "by the class: first, and by the title: last" |
| 5, `Exe` `foot.exe` matches `foot` | extra `by_program` (KDE: no `.exe` on this port) |
## monitors and layout_flip
Two shared scenarios for gaps no Rust test covers either, in `core-e2e`. Nothing was dropped: the
sweep's multi-monitor commands (`commands`) still only say the daemon stays healthy, and these say
what each does.
- `monitors` (needs two displays; one is plugged in if there is one, and out again) opens four
windows and checks, from the OS and the daemon's state, `send-to-monitor`, `move-to-monitor`,
their `cycle-` forms, the `-monitor-workspace` forms, `send-to-named-workspace`,
`move-to-named-workspace`, `focus-monitor`, `cycle-monitor`, `focus-monitor-workspace` and
`cycle-move-workspace-to-monitor`: each window on the monitor and workspace asked for, the others
where they were, tiled inside the display of their monitor (read from `displays()`, which may
differ in size), and the focus where the command leaves it (a send keeps it, a move takes it).
`monitors.at_cursor` is `focus-monitor-at-cursor`, and runs only where `has("pointer")`.
The suite starts KWin with two outputs and unplugs the second before the daemon starts, so that
every other scenario still sees one display.
- `layout_flip` starts the daemon with the workspace option set (`Horizontal`, `Vertical`,
`HorizontalAndVertical`) over columns, rows and BSP with two and three windows, checks the
mirror from the OS, that `flip-layout` turns the option off and on, that a command adds the other
axis, and that the option is the named workspace's own.
Neither has been run on a real KWin or Windows guest yet; the fake in `tests/fake_desk.py` stands in
for the unit tests (`tests/test_monitors.py`).
## workspace-switch
Nearly everything this suite checks is KWin's: a workspace is a virtual desktop. The shared
`workspaces` and `workspace_moves` scenarios, which `core-e2e` runs, check that `send-to-workspace`
and `focus-workspace` put windows away and back with the focus agreed; here the same commands are
read on KWin's desktops. The suite is the extra `workspace_switch.run`; its one dropped check, "the
daemon answers komorebic", is what `platform.start_komorebi()` waits for. The
shared scenario is not called from this suite, because it starts from windows on the first
workspace and this suite's own start state is a daemon that has not yet turned on KWin's
per-output desktops.
## scrolling
The shared `scrolling` scenario (run by `core-e2e`) puts each window in view in turn. This suite
runs the shared `scrolling.columns`: five windows in two columns, where the daemon rests the ones
that scroll out of view (at an edge, a few pixels of them on the screen, their width kept), that the
strip follows the focus and `pan`, and the commands of the columns of several windows (`consume`,
`toggle-column-stack`, `expel`, `scrolling-layout-full-width`). kfde and komorebi for Windows lay
the strip out with the same model, so none of it is KDE's: the extra `scrolling.run` is gone, and
`core-e2e` runs `scrolling.columns` too, from a workspace with no window. The check that a window
keeps the distance of a column from the one in view, which the layout does not keep any more (a
window rests at the edge), was replaced by two that it rests there and keeps its width.
## stacks
Ported whole as the extra `stacks.run`: all 54 checks. It reads the parking desktop and KWin's
desktops (`kdotool`), which the shared `stacks` and `monocle` scenarios do not. It still repeats,
on KWin's side, some of what they check: that cycling the stack shows the other window and puts
the first away, focus by place in the stack, and a monocle over a stack (sections 3, 4 and 8). The
repeats read a different oracle (the parking desktop, not the operating system's `hidden`), so
they are kept for now; slimming them needs the shared scenarios to report what they leave to be
read, which is the stage hook that was left out. Sections 10 and 11 (a crash, a clean stop) are the
`stack-all` form of `core-e2e`'s `parking`.
## kwin-restart
Ported whole as the extra `kwin_restart.run` (two restarts, 19 checks as run). `core-e2e` had a section
that restarted KWin once with the same four checks; it is gone, and `core-e2e` now only opens the
window `afterwards` that its last section looks for.
## features and user-maximize
`Platform.fullscreen(client, on)` and `Platform.user_maximize(client, on)` are the user's fullscreen
and maximize, which the daemon is not asked to do.
| Was | Now |
|---|---|
| features A, the window fills the work area, is in the daemon's state as the maximized window, and goes back to its tile in a container | shared `maximizing.run`; extra `features.run` keeps what KWin says: the frame of the tile before and after, and that it is on top, by a screenshot |
| features E, a fullscreen window covers the monitor, a window opening meanwhile does not take it out, back from fullscreen it is in a tile and not on another window | shared `fullscreen` (the suite runs it after the extra, on the windows the sections leave: `features.fullscreen_setup`) |
| user-maximize 1, the user maximizes: the daemon has it as its maximized window, it fills the work area, its tile is gone | shared `maximizing.user` |
| user-maximize 2, what is asked of the layout does nothing; the others did not move; nothing floats or is in the monocle | shared `maximizing.user` |
| user-maximize 2, the daemon's log notes that it ignored it; 1, the log has the `MaximizeChange` event | extra `user_maximize.log` |
| user-maximize 3 and 4, `toggle-maximize` and the user's restore put it back in its tile | shared `maximizing.user` |
Not kept: for features A, "komorebi still has all three" (the shared scenario checks the count where
it is a check of the window it moves). The shared `fullscreen` is looser than E in one way: the
window covers the display up to a pixel, where E compared the frame with the monitor exactly.
## wallpaper
Wallpapers and the colors of the borders that come from them are in the config of both ports, so
the shared scenario `wallpaper.run` has what is neutral: a monitor's wallpaper at start, a
workspace's own while it is shown (a path with a space in it), the ring of the focused window in
the hue of the wallpaper, and a wallpaper the user changed being put back. It uses `put_file`,
`wallpaper` and `set_wallpaper`. The extra `wallpaper.run` keeps what only the Plasma shell tells:
the fill mode and how long a switch takes, a switch by a pager, the palette cache, and a daemon
that starts before the shell. 12 checks went to the shared scenario, 12 stayed.
## The KDE-only suites
Moved as they were into `komorebi_vm.platforms.kde.extras`, one module per suite (`kwin`,
`kwin_events`, `kwin_contract`, `client_geometry`, `module`, `restart_survival`, `user_maximize`,
`check`, `features`, `look`, `render_smoke`, `wallpaper`, `rdp`, `latency`, `run_kde`,
`live_resize`, `focus_follows_mouse`, `lock_sleep`, `keys_engine`, `keys_static`, `keys_corpus`).
Each module has `run(machine, checks, scale)`, which is the body of the old script; the suite script
only starts the machine and calls `run_suite(checks, platform_only("kde", ...))`. The three
`keys-*` suites share one script, `keys-corpus.py`, as before. No check was dropped and none was
added; these have no shared scenario to repeat. What each makes on a real KDE, run once after the
move:
| Suite | Passed |
|---|---|
| kwin | 8 |
| kwin-events | 22 |
| kwin-contract | 15 |
| client-geometry | 26 |
| user-maximize | 14 |
| check | 23 |
| latency | 5 (once 4 and 1 failed: a p95 of 173 ms against 150 while the machine was loaded) |
| render-smoke | 4 |
| rdp | 6 |
| keys-static, keys-skhd, keys-whkd, keys-sxhkd | 6, 4, 4, 4 |
| lock-sleep | 11 |
| focus-follows-mouse | 11 |
| restart-survival | 17 |
| module | 33 |
| live-resize | 7 |
| look | 40 |
| wallpaper | 12 |
| features | 30 |
| keys-engine | 34 |
| run-kde | 22 |
The moved modules have long lines the suite scripts were never linted for, so `pyproject.toml` lets
them keep them (`E501` per file); new extras do not get that.
+358
View File
@@ -0,0 +1,358 @@
# Plasma guests to develop in
The VM tests boot a machine, run a scenario and power it off. To try komorebi by hand against a
real KWin, the flake has NixOS guests with Plasma 6 that stay up. Each guest is made for one kind
of host, because the accelerator of a host (HVF on a Mac, KVM on Linux) runs guests of the host's
own architecture:
| Guest | Host | Runs under | What it is |
|---|---|---|---|
| `plasma-vm` | Apple silicon Mac | QEMU from nixpkgs, with HVF | Plasma installed, no login: a console and ssh, to run `kwin_wayland --virtual` and build komorebi from the repository |
| `plasma-vm-session` | Apple silicon Mac | QEMU from nixpkgs, with HVF | the same, plus a Plasma Wayland session that logs in by itself, komorebi running in it, and an RDP server |
| `plasma-utm` | Apple silicon Mac | [UTM](https://mac.getutm.app), with a GPU | the session guest as a disk image that boots by UEFI |
| `plasma-vm-x86_64`, `plasma-vm-session-x86_64` | Linux on x86_64 | QEMU from nixpkgs, with KVM | the first two, as `x86_64-linux` guests |
| `plasma-vm-aarch64`, `plasma-vm-session-aarch64` | Linux on aarch64 | QEMU from nixpkgs, with KVM | the first two, as `aarch64-linux` guests |
| `run-kde-x86_64`, `run-kde-aarch64` | Linux on x86_64, on aarch64 | QEMU from nixpkgs, with KVM | the session guest with a demo on it, which `run-kde` starts ([below](#the-demo-guest)) |
The guests of a Mac are `aarch64-linux`. A guest of a Linux host that has no KVM does not start:
the runner refuses, because Plasma under software emulation is too slow to try anything.
They are `nixosConfigurations` of the flake, made from
[`nix/dev/plasma-vm.nix`](../../nix/dev/plasma-vm.nix),
[`nix/dev/plasma-utm.nix`](../../nix/dev/plasma-utm.nix) and
[`nix/dev/krdp.nix`](../../nix/dev/krdp.nix), by `mkPlasmaGuest` in
[`flake.nix`](../../flake.nix), which takes the system of the guest and the packages of the machine
that runs QEMU. Each one installs komorebi with the flake's NixOS
module, `services.komorebi`, so the komorebi in a guest is the one of the commit the guest was
built from, and in the session guests the module's unit starts it at login. They carry no key,
no password and no configuration of anyone's.
In the QEMU guests the guest has a plain `virtio-gpu`, which has no 3D, so KWin composites on the
CPU (llvmpipe) and every frame then has to be encoded to reach an RDP client. That is slow. On a
Mac the QEMU in nixpkgs cannot do better: it has no 3D at all. UTM's QEMU has `virtio-gpu-gl`,
which gives the guest OpenGL through Mesa's VirGL, rendered on the Mac's GPU, and UTM shows the
guest in a window of its own, so there is no RDP in the path at all. The QEMU of an x86_64 Linux
host has and a window (GTK), at time of writing (QEMU 11.1.2 from nixpkgs, 2026-10-28), which these guests
do not use.
## What a builder has to be, on a Mac
A Mac cannot build a Linux system, so the guests are built on a builder: a machine with Nix that
builds for `aarch64-linux` and that the Mac can reach as a remote store, such as
`ssh-ng://builder@localhost`. Any builder will do: the one `nix run nixpkgs#darwin.linux-builder`
starts, a Linux machine on the network, or the one the VM tests use on a Mac
([vm-tests.md](vm-tests.md#running-a-test-on-a-mac)). A Plasma system is a closure of about 10 GB,
and the builder needs room for it and for its build: the defaults of `darwin.linux-builder` (one
core, 3 GB of memory, a 20 GB disk) are too small. Six cores and 10 GB of memory worked, at time
of writing (2026-10-27).
The examples below use the same variables as `scripts/vm-mac`:
```sh
export KOMOREBI_BUILDER=ssh-ng://builder@localhost # the store URL of your builder
export NIX_SSHOPTS="-p 31022 -i $HOME/.ssh/builder_ed25519 -o IdentitiesOnly=yes" # if it needs them
```
## The QEMU guests on a Mac
The system is built on the builder and copied back, and only the QEMU runner, which is a program
for the Mac, is built on the Mac. A QEMU guest runs the system of its `vmVariant` (which adds the
disk and the shared directory), not the system of the configuration itself:
```sh
guest=plasma-vm-session # or plasma-vm
config=".#nixosConfigurations.$guest.config"
system=$(nix build "$config.virtualisation.vmVariant.system.build.toplevel" \
--eval-store auto --store "$KOMOREBI_BUILDER" --no-link --print-out-paths)
nix copy --from "$KOMOREBI_BUILDER" --substitute-on-destination --no-check-sigs "$system"
nix build "$config.system.build.vm" --builders '' -o .vm/result-$guest
```
The guest mounts the directory `KOMOREBI_REPO` names at `/repo`, and makes its disk,
`plasma-vm.qcow2` or `plasma-vm-session.qcow2`, in the directory it is started from on its first
start, and keeps it there. `.vm` is ignored by git:
```sh
cd .vm && KOMOREBI_REPO=$PWD/.. ./result-$guest/bin/run-$guest-vm
```
The terminal is the guest's console, logged in as the user `komorebi`, who can use `sudo` with no
password. ssh is forwarded from `localhost:2222` (`plasma-vm`) or `localhost:2223`
(`plasma-vm-session`) and takes keys only: put yours in `~/.ssh/authorized_keys` from the console
once, and the disk keeps it. Both guests can run at once.
In the guest, `/repo` is the repository and `CARGO_TARGET_DIR` is in the guest's home, since a
target directory on the shared directory is slow. The session guest shows nothing on the Mac; it
is reached over RDP ([below](#rdp)).
## The QEMU guests on a Linux machine
A Linux host builds a guest itself, so there is no builder to set up. It needs Nix with flakes, KVM
(a `/dev/kvm` that the user can open, which on most distributions means the group `kvm`), and room
for the closure (about 10 GB) and for the guest's disk (20 GB, sparse). The runner is built with
its system, and started the same way as on a Mac:
```sh
guest=plasma-vm-session-x86_64 # or plasma-vm-x86_64, or the -aarch64 pair on an aarch64 host
nix build ".#nixosConfigurations.$guest.config.system.build.vm" -o .vm/result-$guest
cd .vm && KOMOREBI_REPO=$PWD/.. ./result-$guest/bin/run-*-vm
```
The console, the user, the ssh ports (2222 and 2223), the RDP port, the disk and `/repo` are as
described for a Mac. What differs is what nixpkgs' runner does on a Linux host:
- It starts one `virtiofsd` for each shared directory, as the user who runs the guest, and the
guest mounts them by virtiofs where a Mac's guest mounts them by 9p. One of them is the host's
`/nix/store`, so the guest has the closure without a copy of it.
- It refuses to start when `/dev/kvm` is missing or cannot be opened by the user, since the guests
set `virtualisation.qemu.forceAccel`.
A guest has one display device, a virtio-gpu, so that KWin has a DRM device to draw on. The machine
of an x86_64 guest has a VGA of its own, which would be a second display next to the virtio-gpu,
so the guest has `virtio-vga` (a virtio-gpu that is also a VGA) in its place and `-vga none`. The
session guest shows nothing on the host, as on a Mac: it is reached over RDP ([below](#rdp)).
## The demo guest
`run-kde-x86_64` and `run-kde-aarch64` are the session guest with a demo on it, made by
[`nix/dev/run-kde.nix`](../../nix/dev/run-kde.nix) on top of `plasma-vm.nix`. komorebi is
configured by the module's typed `config` (eight workspaces with a layout each, borders and
animation) and by the sample key bindings, `docs/skhdrc.sample`, in the module's default mode. At
login the guest opens two Konsole windows, Kate and Dolphin, which komorebi tiles, and a cheat sheet
that it leaves alone: the main key bindings, `komorebic` commands to try, what KWin draws with, and
the output of `komorebic check` for the configuration the daemon runs. The VM suite `run-kde` boots
the same module on the session node.
The closure is the same for everyone. No password, key or configuration of a person is in it, and
what a person's run needs comes from the environment of the runner:
| Variable | What the guest does with it |
|---|---|
| `KOMOREBI_REPO` | the directory mounted at `/repo` |
| `RUN_KDE_STATE` | the directory mounted at `/run/run-kde`, with `rdp-password` (the password for RDP) and `ssh_key.pub` (the public key that may log in over ssh) |
| `RUN_KDE_MEMORY` | the memory in MiB, which has to be the `-m` of the same run |
| `QEMU_NET_OPTS` | the port forwards, as `hostfwd=tcp:127.0.0.1:2223-:22,hostfwd=tcp:127.0.0.1:3389-:3389` |
| `QEMU_OPTS` | the display device: `-vga none -device virtio-vga,xres=1280,yres=800`, or `-display gtk,gl=on -vga none -device virtio-vga-gl,xres=1280,yres=800` for a GPU |
| `NIX_DISK_IMAGE` | the disk image, which the runner makes when it is not there |
[`run-kde`](#the-command) sets them ([the guide](../trying-it.md) says what a person sees and does);
to start the guest by hand, on a Linux machine:
```sh
nix build .#nixosConfigurations.run-kde-x86_64.config.system.build.vm -o .vm/result-run-kde
mkdir -m 700 .vm/state && cd .vm
ssh-keygen -q -t ed25519 -N '' -f state/ssh_key
printf %s "a password" > state/rdp-password
KOMOREBI_REPO=$PWD/.. RUN_KDE_STATE=$PWD/state RUN_KDE_MEMORY=6144 \
QEMU_NET_OPTS=hostfwd=tcp:127.0.0.1:2223-:22,hostfwd=tcp:127.0.0.1:3389-:3389 \
QEMU_OPTS='-cpu host -vga none -device virtio-vga,xres=1280,yres=800' \
./result-run-kde/bin/run-komorebi-demo-vm -m 6144 -smp 4
```
The guest differs from `plasma-vm-session` in what the runner of nixpkgs would otherwise fix when
the closure is built:
- The display device is not part of the guest (`komorebi.plasmaVm.display` is false). The same
closure and the same disk run with the software `virtio-vga` or with `virtio-vga-gl`, which
renders on the host's GPU through VirGL, as the runner's environment says.
- The ports are not forwarded by the guest, so that a person can choose them.
- The runner does not insist on KVM (`qemu.forceAccel` is false): `run-kde` checks for it and
lets `--tcg` start a guest without.
- The shared memory that virtiofs needs is a memory backend of the guest's memory size, which
nixpkgs fixes at `memorySize` in the command line of the runner. The guest makes its own, from
`RUN_KDE_MEMORY`, so that a run can have less memory than the closure's 8 GB.
- The directory `/run/run-kde` is mounted after the boot and not in the initrd, where a mount
under `/run` is hidden by the `/run` that the booted system mounts.
- The files in it can belong to a user of the host who is not the guest's user, and the guest
cannot read the directory then. The unit `run-kde-credentials` copies the two files as root, to
`/run/run-kde-guest`, where the RDP unit (`komorebi.krdp.passwordFile`) and sshd
(`AuthorizedKeysFile`) read them.
## The command
`run-kde` starts the demo guest on a Linux machine, from a checkout: `nix run .#run-kde -- [options]`,
or `just run-kde [options]`. It is [`scripts/run-kde`](../../scripts/run-kde), which the flake wraps
with the runner of the machine's guest (`run-kde-x86_64` or `run-kde-aarch64`) written into it, as
`packages.<system>.run-kde` and `apps.<system>.run-kde`. The package names the runner and does not
depend on it, so `nix run` does not fetch 4 GB before the command can say what the machine lacks.
In order, it:
1. Checks the machine. `--doctor` prints every check, a tick or a cross or a `!`, with the fix under
each cross and each `!`: WSL 2 or not, Nix, KVM (`/dev/kvm`, the group `kvm`, the CPU's `svm` or
`vmx` flag, the module `kvm_amd` or `kvm_intel`, and on WSL 2 the line
`nestedVirtualization=true` of `.wslconfig`), virtiofs (a `virtiofsd`, the runner's own when it
is built, is started as this user with the runner's options and must make its socket: a cross
when it does not; `/dev/fuse` is a `!`, since `virtiofsd` never opens it), memory, cores, disk, a
window (WSLg: `WAYLAND_DISPLAY`, `DISPLAY`), Windows interop for `--rdp`, the GPU (`/dev/dxg` on
WSL 2, a render node elsewhere, and the OpenGL renderer of the host from `glxinfo`), and the
networking mode of `.wslconfig`. A cross stops the command and `--doctor` exits with 1; a `!`
does not. A missing KVM is a cross, unless `--tcg` allows software emulation, which is too slow
to try anything.
2. Builds the guest when its runner is not in the store, with `nix build` of the checkout's flake and
the build log shown. There is no binary cache: the first run builds komorebi and downloads about
4 GB of Plasma, which are 11 GB in the Nix store. [The first run](../trying-it.md#the-first-run)
says how long that took where it was measured.
3. Makes the state directory, `$XDG_STATE_HOME/komorebi-run-kde` (`~/.local/state/komorebi-run-kde`),
when it is not there: the guest's disk (20 GB, or `--size`, sparse), a random RDP password and an
ed25519 key for ssh, all of mode 0600 in a directory of mode 0700. `--reset` deletes it. Nothing
of it is in the Nix store.
4. Prints a banner and starts the runner with the environment of [the demo guest](#the-demo-guest):
`-cpu host` with KVM, the repository at `/repo` (the checkout, or `KOMOREBI_REPO`), the state
directory at `/run/run-kde`, the ports on `127.0.0.1` (ssh 2223, RDP 3389: `--ssh-port`,
`--rdp-port`), and `-m` and `-smp` from what the machine has (`--memory`, `--cores`): the
machine's memory less 2048 MB, between 4096 and 8192, and its cores up to 6.
The terminal is the guest's console, logged in as `komorebi`. What else the guest shows depends on
the display and on the GPU.
| `--display` | What it does |
|---|---|
| `gtk` | a window of QEMU; the default when `WAYLAND_DISPLAY` or `DISPLAY` is set |
| `rdp` | no window; the guest is reached over RDP; the default otherwise |
| `vnc` | no window; QEMU's VNC server on `127.0.0.1:5900` |
| `none` | no window; `--shell` is this with the GPU off |
`--gpu auto` uses the GPU when the display is a window, the host has a GPU device and the OpenGL of
the host (`glxinfo`) is not llvmpipe. Otherwise it does not, and the banner says why. The GPU is
`-display gtk,gl=on` with `-device virtio-vga-gl`, which renders the guest's OpenGL on the host
through VirGL; without it the guest has `virtio-vga` and renders on its CPUs. `--gpu on` with no
window starts `-display egl-headless`, which needs a DRM render node. The guest says what KWin draws
with in its cheat sheet and on the console (`GPU (virgl)` or `software (llvmpipe)`): the guest's
driver, not the host's.
On WSL 2, `--rdp` starts Windows' own RDP client once ssh says that the unit `krdp` is running:
`cmdkey.exe` stores the password for `TERMSRV/localhost`, `mstsc.exe` connects to
`localhost:3389`, and the credential is deleted when `run-kde` ends.
`--dry-run` prints the environment and the command that would be started, and starts nothing. The
script reads the machine through variables, so that a test can make up a machine:
`RUN_KDE_KVM_DEVICE`, `RUN_KDE_DXG_DEVICE`, `RUN_KDE_DRI_DIR`, `RUN_KDE_MEMINFO`, `RUN_KDE_CPUINFO`,
`RUN_KDE_OSRELEASE`, `RUN_KDE_SYS_MODULE_DIR`, `RUN_KDE_STORE_DIR`, `RUN_KDE_FUSE_DEVICE`,
`RUN_KDE_VIRTIOFSD`, `RUN_KDE_FREE_GB`, `RUN_KDE_CPUS`, `RUN_KDE_HOST_RENDERER` and
`RUN_KDE_WSLCONFIG`, besides `WAYLAND_DISPLAY` and `DISPLAY`; and `RUN_KDE_GUEST` and
`RUN_KDE_RUNNER_BIN`, which the package sets, and `RUN_KDE_QEMU_OPTS`, which adds to the options of
QEMU. The checks `run-kde-dry-run` and `run-kde-doctor`
([`nix/tests/run-kde.nix`](../../nix/tests/run-kde.nix)) run it against a WSL 2 with WSLg and a GPU,
one with WSLg and a software OpenGL, one with WSLg and no GPU device, a Linux machine with no
window, `--tcg` with no KVM, and machines that cannot run the guest (no KVM, a KVM the user cannot
open, a `virtiofsd` that exits), a `/dev/fuse` that is missing or closed, and compare the output
with the texts in [`nix/tests/run-kde`](../../nix/tests/run-kde). The check `run-kde` builds the package, which
shellchecks the script.
## The UTM disk
UTM boots `plasma-utm` from a disk image. The image is made by installing the system onto a blank
disk from a running Linux system with `nixos-install`, which needs no virtualization on the
builder: here, the `plasma-vm` guest, which has the tools for it. Build both systems first: the
`plasma-vm` runner as above, and the `plasma-utm` system, on the builder, copied back:
```sh
system=$(nix build .#nixosConfigurations.plasma-utm.config.system.build.toplevel \
--eval-store auto --store "$KOMOREBI_BUILDER" --no-link --print-out-paths)
nix copy --from "$KOMOREBI_BUILDER" --substitute-on-destination --no-check-sigs "$system"
```
The closure goes into the guest as one file that `nix-store --export` writes, and not through the
guest's view of the Mac's store: macOS stores files whose names differ only by case under other
names (`~nix~case~hack~1`), which a guest reading the directory sees, and nix then rejects the
hashes. An export undoes that. Then boot `plasma-vm` with a blank disk of 40 GB attached:
```sh
mkdir -p .vm/utm && cd .vm
nix-store --export $(nix-store -qR "$system") > utm/plasma-utm.closure
echo "$system" > utm/plasma-utm.system
nix shell nixpkgs#qemu --command qemu-img create -f raw utm/plasma.raw 40G
QEMU_OPTS="-drive file=$PWD/utm/plasma.raw,format=raw,if=none,id=utm -device virtio-blk-pci,drive=utm" \
KOMOREBI_REPO=$PWD/.. ./result-plasma-vm/bin/run-plasma-vm-vm
```
In the guest's console, partition the disk, which is `/dev/vdb`, and install the system onto it:
```sh
sudo parted -s /dev/vdb -- mklabel gpt mkpart ESP fat32 1MiB 512MiB set 1 esp on mkpart nixos ext4 512MiB 100%
sudo mkfs.vfat -F 32 -n ESP /dev/vdb1
sudo mkfs.ext4 -q -L nixos /dev/vdb2
sudo mount /dev/vdb2 /mnt && sudo mkdir -p /mnt/boot && sudo mount /dev/vdb1 /mnt/boot
sudo nix-store --import --store /mnt < /repo/.vm/utm/plasma-utm.closure > /dev/null
sudo nixos-install --system "$(cat /repo/.vm/utm/plasma-utm.system)" --root /mnt --no-root-passwd --no-channel-copy
sudo umount /mnt/boot /mnt && sudo poweroff
```
Back on the Mac, in `.vm`, the raw disk becomes the qcow2 that UTM is pointed at (about 12 GB
used of 40):
```sh
nix shell nixpkgs#qemu --command qemu-img convert -O qcow2 utm/plasma.raw utm/plasma.qcow2
rm utm/plasma.raw utm/plasma-utm.closure
```
## Point UTM at it
1. Install UTM (`brew install --cask utm`, or from its website).
2. New VM → **Virtualize** → **Linux**. Leave the boot ISO empty. Give it 8192 MB and 6 cores.
(The wizard insists on a new disk; delete it in step 3.)
3. Before the first start, open the VM's settings:
- **Drives**: remove the new disk, then **Import** `.vm/utm/plasma.qcow2` (interface VirtIO).
- **Display**: *Emulated Display Card* `virtio-gpu-gl-pci (GPU Supported)`. New Linux VMs get
it by default. Renderer backend *Default* (ANGLE on Metal) or *Apple Core OpenGL* (GL 4.1).
- **Network**: *Shared Network* (the guest gets an address the Mac can reach), or *Emulated VLAN*
with port forwards 2224→22 and 3389→3389.
- Name it `plasma-utm`.
4. Start it. sddm logs in by itself and Plasma comes up with komorebi running.
## Using it
The VM's window is the desktop: click into it and use it. The pointer is an absolute tablet, so it
moves in and out of the window without being grabbed; if the window does capture it,
**Control+Option** releases it (UTM's default; Command+Option also works, and Control+Option
collides with VoiceOver). The Option key is Alt in the guest. macOS takes a few combinations before
UTM sees them (Control-arrow switches Spaces, and anything with Command), and those never reach the
guest. Resizing the window resizes the guest's screen, and the clipboard is shared (spice-vdagent
runs in the guest).
To check that the session is on the GPU, from a terminal in the guest (or over ssh, once a key of
yours is in `~/.ssh/authorized_keys`):
```sh
eglinfo 2>/dev/null | grep -i renderer # virgl (Apple M...)
journalctl --user -b -t kwin_wayland | grep -i "opengl\|renderer" | head
komorebic state | head
```
## RDP
The session guests run KRDP, Plasma's RDP server, as the user unit `krdp`, on port 3389 (forwarded
from `localhost:3389` for `plasma-vm-session`). It logs in the session's user, `komorebi`, with a
password of your choosing, which the unit reads from a file in the guest; until the file is there,
the unit does not start. In the guest:
```sh
umask 077 && mkdir -p ~/.config/komorebi-vm && cat > ~/.config/komorebi-vm/rdp-password # type it, then Ctrl-D
systemctl --user start krdp
```
The server makes a self-signed certificate the first time it starts, so a client warns about it.
The password is passed to `krdpserver` on its command line, which every user of the guest can read
in the process list. [PLATFORM.md](PLATFORM.md#rendering-in-virtual-machines-and-over-rdp) says what
is known about RDP into the session, and what is not.
## What is not known
At time of writing (2026-10-28), the guests of a Mac, made from these files, have been built on an
`aarch64-linux` machine, and not booted: no test covers them, and `plasma-guests-eval` only
evaluates them. The `x86_64` pair for a Linux host was built and started under KVM on an `x86_64`
machine. Both guests reached the login on their serial console and had one DRM device with a render
node, and the session guest drew the Plasma desktop on its display (a screenshot taken through
QEMU's monitor) with komorebi running in the session. The demo guest, `run-kde-x86_64`, was
started under KVM with a state directory: ssh took the key from it, the RDP unit started with the
password from it, komorebi tiled the four windows, and the cheat sheet opened. `run-kde --doctor`,
`--dry-run`, `--build-only` and a start with `--display none` were run on the same machine, which has
no WSL, no window and no GPU: the guest came up with the memory and cores asked for, and it said
`software (llvmpipe)`. The GPU path was started on that machine in QEMU's GTK window on an X server
whose OpenGL is Mesa's llvmpipe. Nothing was run on WSL 2, with WSLg, with a GPU, or with
`mstsc.exe`: what the command does there is not known yet. The `aarch64` guests
for a Linux host were evaluated and not built. The RDP server is the exception to all of this: the
VM suite `rdp` runs the same unit in the test session. That KWin 6.8 runs well on VirGL under UTM
is not known either: the UTM and Mesa notes say VirGL is the way to render a Linux desktop, and
Plasma works on it for other people, but it has not been measured here.
+427
View File
@@ -0,0 +1,427 @@
# VM tests
The unit tests run against a fake desktop. They cannot say whether KWin does
what the daemon asks of it, so a second kind of test boots a NixOS virtual
machine with Plasma in it, starts a real KWin, and drives it. This page says how
they are laid out, how to run them, and how to add one.
## What runs where
| Where | How | Accelerator |
|---|---|---|
| CI, `x86_64-linux` | `nix build -L .#checks.x86_64-linux.vm-NAME` | KVM |
| CI, `x86_64-linux`, the weekly canary | the same, with nixpkgs moved to the tip of nixpkgs-unstable | KVM |
| A Linux machine with KVM | `just vm NAME` | KVM |
| A Mac | `just vm NAME`, which runs `scripts/vm-mac` | HVF |
| A Linux machine with no KVM | `nix build -L .#legacyPackages.SYSTEM.vmTcg.NAME` | TCG |
CI runs the `fast` tier on every pull request and the `slow` tier on `master`,
every week, and on pull requests labeled `ci:vm-slow`
([`ci.yaml`](../../.github/workflows/ci.yaml)). The slow jobs run the driver
by hand instead of building the check, so that the screenshots and journals of a
failed run can be uploaded as an artifact. KVM on GitHub-hosted runners is
documented for public repositories; the first step of each VM job checks that
`/dev/kvm` is writable and fails there if it is not.
The `canary` job runs both tiers once more every week, against the tip of
nixpkgs-unstable instead of the nixpkgs `flake.lock` pins: it runs
`nix flake update nixpkgs` in a copy of the checkout, builds every check there,
the suites one after the other on one machine, and opens an issue when one
fails ([`CONTRIBUTING.md`](../../CONTRIBUTING.md#continuous-integration)). It is
how a new KWin or Plasma that breaks a suite is found before the lock moves to
it.
TCG is software emulation. It is slow enough that only short suites are worth
running that way, and the library's `scale` argument (below) is 8 for it.
Whether a machine has working KVM is not always obvious, and under WSL2 it
depends on settings of Windows. `nix run .#wsl2-probe` boots a tiny guest with
and without KVM and times both ([wsl2-probe.md](wsl2-probe.md)).
The suites are what `testedMax` in
[`nix/supported-kwin.nix`](../../nix/supported-kwin.nix) means: the newest KWin
every suite has passed against. When the weekly canary job, which runs every
suite against the tip of nixpkgs-unstable, passes with a newer KWin, a commit
raises `testedMax` to it and says which suites ran
([CONTRIBUTING.md](../../CONTRIBUTING.md#the-nixos-module)).
Each suite is a directory under
[`nix/tests/vm/suites`](../../nix/tests/vm/suites). The generator in
[`nix/tests/vm/default.nix`](../../nix/tests/vm/default.nix) lists that
directory, so a new suite is a new directory and nothing else: it appears as
`checks.<system>.vm-NAME` on Linux and as `legacyPackages.<system>.vm.NAME`
everywhere. `legacyPackages.<system>.vmTiers` lists the names of each tier as
JSON, which is what CI reads.
A suite has two files:
- `default.nix` sets `tier` (`"fast"` or `"slow"`), `kind` (the node it runs on)
and `timeoutMinutes`, and may set `node`, a NixOS module that adds to the node
for this suite alone (more memory, the clients it starts, the options of
`services.komorebi`).
- `test.py` is the test, a Python script for the NixOS test driver. It is
prefixed with `SCALE = <number>`, how many times slower than KVM the machine
is. Suites that run the same test on different nodes set `script` to a file
they share instead, relative to their directory: `vm-keys-skhd`,
`vm-keys-whkd` and `vm-keys-sxhkd` run `../../keys-corpus.py`, each with the
key bindings of its format in its `node`.
## Nodes
`kind` picks a file under
[`nix/tests/vm/nodes`](../../nix/tests/vm/nodes).
Both nodes are built with the NixOS module, as a user's machine is: they import
`nixosModules.default`, which the generator passes to them, and enable
`services.komorebi`, which installs `komorebi` and `komorebic`, built from the
commit under test. `services.komorebi.logLevel` is `"debug"`, because the tests
read the daemon's debug log. A suite can change either option in its `node`:
`latency`, which times the daemon, runs it at `"info"`.
The checks of the module that need no machine are `nixos-module-eval`
([`nix/tests/nixos-module.nix`](../../nix/tests/nixos-module.nix)), and the
suite `module` checks its unit in a Plasma session.
`headless` is a machine with Plasma installed and no login. Each KWin a test
starts is a pair of user units of the test user, `session-bus@NAME` (a private
D-Bus session bus) and `kwin-virtual@NAME` (`kwin_wayland --virtual` with its
own Wayland socket), so a test can run several sessions side by side and none
touches another. A virtual KWin has no real output, so it cannot draw: it can
place windows and answer questions about them, but it cannot take a screenshot.
A third unit, `komorebi@NAME`, runs the daemon in a session: it is the module's
unit, `komorebi.service`, moved to the session's bus and Wayland socket, and runs
the module's `execStart` followed by the arguments the test gives. It is not
bound to KWin's unit, so a test can restart KWin under a running daemon. The
module's unit itself starts with a Plasma session, which this node does not
have.
KWin wants a DRM render node, which needs a GPU. The test driver gives every aarch64 guest one
`virtio-gpu-pci`; on x86_64 the node adds it, unless `komorebi.vm.renderNode` is false.
`session` is the headless node plus a login: plasma-login-manager logs the test
user in by itself, as in nixpkgs' own `plasma6` test, and Plasma draws on the
machine's display device. The login starts the module's unit, so komorebi runs
in the session from the start, as on a user's machine; `render-smoke`, which
checks that the session draws, turns it off. It is the node for anything that
needs pixels: `features` reads what komorebi does from screenshots of it. The
choice of login manager is made in
[`nodes/session.nix`](../../nix/tests/vm/nodes/session.nix) and nowhere else;
the file says how to switch to sddm, the other one that has been seen to work.
Its display is 1280x800, because screenshots are taken of the machine's one
display device: the `virtio-gpu-pci` that the test driver adds to every aarch64
guest, and the default VGA of an x86_64 one. The node sets
`komorebi.vm.renderNode` to false, so that an x86_64 guest does not get a second
device: KWin would draw on it, and the screenshot would show the other one.
The node also has uinput, with the test user in the group `uinput`, and the
program `komorebi-pointer`, which makes a pointer device with it: a test drives
the pointer from inside the guest, and KWin takes it as a tablet.
On aarch64 under HVF, at time of writing (2026-10-27), the session has the
Wayland socket after 11 to 19 seconds and a painted desktop after 35 seconds.
A suite's `node` can import a module of the repository: `rdp` imports
[`nix/dev/krdp.nix`](../../nix/dev/krdp.nix), the RDP server of the Plasma
guests to develop in, so that the suite checks the unit those guests run, and
`run-kde` imports [`nix/dev/run-kde.nix`](../../nix/dev/run-kde.nix), the demo
guest that the command `run-kde` starts, so that what CI boots is what the
command starts. The node of `run-kde` also makes the directory that the host
shares with that guest (`/run/run-kde`), owned by a user the guest does not
have, with a password and a public key in it, as the guest finds it once it has
mounted it. The guests themselves, which stay up for a person to use, are in
[utm.md](utm.md).
## The library
Suites import from `komorebi_vm`, in
[`nix/tests/vm/lib`](../../nix/tests/vm/lib). It does not depend on the test
driver. It depends on the small `Machine` protocol, and its unit tests pass a
fake machine, so the `vm-lib` check tests it without booting anything. The
check also runs `ruff` and `ty` over it. The driver type checks every
`test.py` with `ty` and `ruff` too, so a typo in a suite fails the build, not
the run.
- The package `komorebi_vm.core` is what does not depend on the platform: `Checks`,
`Rect` and the pixel helpers. It imports nothing of KDE, so that it can move to
the Windows port unchanged. `komorebi_vm` re-exports them, so that a suite
imports them from the same place as before.
- `Snapshot` (`core/snapshot.py`) is the daemon's state in one shape for every port:
`snapshot.parse(json)` reads the `komorebic state` of kfde and of kfw into
monitors, workspaces, containers and windows. What only one port's state has
goes in `Snapshot.extra`. Its unit tests read states recorded from a real run of each
port (`tests/fixtures`: kfde's from `core-e2e`, which writes them into its output, and
kfw's from a Windows guest), and a scene written from the serializers for the shapes
that no run has recorded.
- `Platform` (`core/platform.py`) is what a scenario needs of a platform: start the
daemon, run `komorebic`, read the `Snapshot`, open a window, ask whether the
daemon put it away (`hidden`), ask the operating system for its frame
(`os_window`, the oracle: the daemon's state is the thing under test), and take
a screenshot. Where the platform has a pointer (`has("pointer")`), a scenario moves
it with `pointer.drag`; where it has none, the scenario says so and is skipped.
`core/scenarios` has the scenarios written against it: `tiling`, `focus`, `moving`,
`stacks`, `monocle`, `workspaces`, `closing`, `resize`, `rules`, `hotplug`, `commands`
(every layout and about 216 commands), `lifecycle` (stop, start again), `placement`,
`startup_rules` and `focus_follows_mouse`. A method is added with the first scenario that
needs it: `restart_with(config)` starts the daemon afresh with a `komorebi.json` the
scenario gives. `KdePlatform` (`kde_platform.py`) is a `Kde` session as a `Platform`.
[platform-contract.md](platform-contract.md) says what each member promises both ports and
what a scenario may not lean on. [Writing a scenario](#writing-a-scenario) says how to add one.
A check that a port is known to fail is recorded with `Checks.known_failure(description,
condition, reason)`: it does not fail the suite, the totals say `known failures: N`, and
one that holds fails the suite, so that the marker goes with the bug. Scenarios that can
hit one take the reason from the runner (`unknown_monitor`, `placement`).
The scenarios run on two platforms. KDE runs them in `core-e2e`, except `resize` and
`focus_follows_mouse`, which need a pointer and run at the end of `drag-resize`. A
Windows 11 guest under QEMU, which kfw drives from its own tree with this `core/` copied
unchanged (`scripts/sync-e2e-core` keeps the copy in step until `core/` moves there),
runs all of them against kfw's daemon. [BEHAVIOUR.md](BEHAVIOUR.md) says what each
scenario found on each port, and what turned red when the daemon was deliberately broken.
- `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`, 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`,
`outputs()` counts the enabled outputs through `kscreen-doctor`, `spawn` starts
a client, and `wait_for(predicate, timeout)` polls, with the timeout
multiplied by `scale`.
- `Kde.outputs` has the outputs: `names()` lists them from left to right, and
`disable(name)`, `enable(name)` and `scale(name, factor)` change them with
`kscreen-doctor`, which is how a suite changes the monitors under the daemon.
A disabled output keeps its name, so `names(enabled=False)` finds it to enable
again.
- `Kde.session(machine, scale=)` attaches to the session node's own Plasma
session once its desktop is up, and `shot(name)` returns a screenshot as a
Pillow image, keeping `NAME.png` in the output directory.
- `activate`, `minimize`, `maximize`, `unmaximize`, `fullscreen` and `close` act on a window
through `kdotool`, as the user would (`maximize` does what the title bar's button does, and the
daemon is not asked), and `wid_by_class` finds a window by its app id or X11 class.
`Kde.headless(..., xwayland=True)` gives the session XWayland, for X11
clients.
- `start_komorebi(*args)` starts the daemon in the session, with the module's
`execStart` and `args` after it (not `--log-level`, which `execStart` has),
`stop_komorebi()` stops it with `SIGTERM`, `kill_komorebi()` kills it with
`SIGKILL`, as a crash does, `komorebi_log()` returns its log since it was
last started, and `script_loaded()` asks KWin whether it runs the bridge.
`restart_kwin()` stops the session's KWin and starts a new one on the same
bus, as when the compositor of a running session crashes, and waits for it.
- `komorebic(*args)` runs `komorebic` in the session and returns what it
printed, failing the test if it fails. `state()` is the daemon's state as
`komorebic state` prints it, `managed(workspace)` the number of windows the
daemon has on a workspace of the first monitor, `managed_all()` the number it
has on every workspace of every monitor (floating windows, monocle containers
and maximized windows too), `containers(workspace)` the titles of the windows
of each of its containers, `monocle(workspace)` those of its monocle
container, and `focused_title(workspace)` the title of the window it has
focused there.
- `daemon` reads the daemon's view of the desktop from that log, at the debug
level the nodes set: `daemon.events(log)` lists the window events it handled,
in order, `daemon.window_ids(log)` maps a window's title to the daemon's id
for it, and `daemon.requests(log)` returns the frame the daemon last asked KWin
for, for each window.
- `desk(wid)` is the number of the desktop a window is on and `shown()` the one
KWin shows, both counted from 1 as `kdotool` counts, `desktops()` how many
desktops KWin has, `desktop_names()` their names in order (the parking desktop
of a stack is the one named `komorebi-park`), `kwinrc(group, key)` a value of
the user's `kwinrc`, and `kwinrc_group(group)` every key of a group, which a
test compares before and after komorebi to see that the user's settings are
put back.
- `effect_supported(name)` and `effect_loaded(name)` ask KWin whether an effect is
installed (KWin found it when it started) and loaded, and `unload_effect(name)`
unloads one, whoever loaded it.
- `colored_window(title, color)` opens a terminal that is one color all over, and
waits for KWin to have it, and `close_colored_windows()` closes them: a test
reads the color of a pixel of a screenshot, and wants nothing else there.
- `pixels` reads a screenshot: `pixels.pixel(image, x, y)` is the color of a
pixel, `pixels.near(a, b)` compares two colors within a tolerance, since a
compositor blends the edge of what it draws, `pixels.ring(image, frame,
color)` names the sides of a window's frame that have no ring of `color` just
outside them, which is how a test sees a border, and `pixels.leftmost(image,
y, color)` finds where a row first has a color, which is how a test sees how
far along a window is on its way.
- `kwin_script(name, source, keep=)` runs a KWin script and returns the lines it
reported: the script calls `report(...)`, which `print`s a line marked with
`name` to KWin's log, and ends with `report("done")`. A script that is kept
goes on reporting what its signal handlers see, and `kwin_reports(name)`
reads every line it has reported so far from the journal.
- `monitor_bridge(path)` records the bridge's traffic on the session bus with
`dbus-monitor`, and `latency.rounds` times each batch of commands in it, from
the daemon's answer to the last frame KWin reports for the windows it moved.
- `Pointer.start(machine, (width, height), scale=)` starts `komorebi-pointer` on
a session node, for a screen of that size, and `move(x, y)`, `down()`, `up()`,
`glide(x, y, steps, ms)` and `drag(start, end)` move and click it. Each
returns once the program has done it, and a glide's moves are made in the
guest, milliseconds apart: moves that each wait for the test are seconds
apart, and KWin was seen to lose the horizontal part of such a drag. The
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.
- `RdpClient(machine, kde)` is FreeRDP's client on an X server of its own, for a
node that runs KRDP: `listening()` asks the guest whether the server has its
port, `logs_in(password)` whether a client with that password is let in,
`connect(password)` starts a client that stays, `picture()` reads what it
shows from its X server, and `shows_display()` waits for that to be the
display (more than a thousand colors, within 16 of 255 on average of a
screenshot). The suites `rdp` and `run-kde` both use it.
- `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
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.
Two traps are worth knowing about before writing a screenshot test:
- A splash screen is not a blank screen. KSplash has more than a thousand colors
on it, so "the screenshot is not blank" passes while Plasma is still
starting. `Kde.session` waits for the splash process to exit, and a test
should check a pixel it knows, such as the middle of a terminal.
- The panel comes after the shell. A window tiled before the panel was made is
tiled under it, which hides the bottom of its border from a screenshot, and
nothing tiles it again. `Kde.session` waits until the shell has made a panel. KWin takes
the room for the panel a while after that, and a daemon learns of it up to a second later: a
test that opens windows right after the daemon starts waits with
`Kde.wait_for_panel_room` first. It is a wait and not a check, because a session that is too
slow may never take the room.
- NixOS wraps programs, so a process's name is the wrapper's (`.plasmashell-wrapped`),
and `pgrep -x plasmashell` never matches. Match the command line instead, with
a bracket in the pattern (`pgrep -f '[p]lasmashell'`) so that the shell running
`pgrep` does not match itself.
## Running a test on a Mac
QEMU has to run on the Mac to use HVF, and the guest is Linux, so the guest's
closure is built on a Linux builder and the driver runs on the Mac. The nix
sandbox on macOS cannot give QEMU the hypervisor, so `scripts/vm-mac` runs the
driver directly instead of building the check.
```sh
export KOMOREBI_BUILDER=ssh-ng://builder@localhost
export NIX_SSHOPTS="-p 31022 -i $HOME/.ssh/builder_ed25519 -o IdentitiesOnly=yes"
just vm kwin
```
`KOMOREBI_BUILDER` is the store URL of an `aarch64-linux` builder you can
reach. `nix run nixpkgs#darwin.linux-builder` starts one, with one core and 3 GB
of memory by default; a Plasma guest needs more than that (6 cores and 10 GB
worked, at time of writing, 2026-10-27), and the builder's 20 GB disk holds one
Plasma system closure of about 10 GB, so run `nix-collect-garbage` on it
between builds of different guests.
The script prints where the artifacts (screenshots, logs) are, under
`.vm/out/NAME`.
## Writing a test
1. Create `nix/tests/vm/suites/NAME/default.nix` and `test.py`. Start from
[`suites/kwin`](../../nix/tests/vm/suites/kwin), or from
[`suites/kwin-events`](../../nix/tests/vm/suites/kwin-events) for a test that
runs the daemon.
2. Pick the tier. `fast` suites are the pull request gate and should take
minutes. `slow` suites run on `master` and every week.
3. Run it: `just vm NAME`.
4. If the test covers behavior the daemon has, write the Rust test that covers
the same behavior against the fake desktop in the same commit, and say in
the VM test's first comment what only a real KWin can tell.
Add `git add -N` for new files first: a flake only sees files git knows about.
## Writing a scenario
A scenario is a function `run(platform, checks, ...)` in
`nix/tests/vm/lib/komorebi_vm/core/scenarios/`. It is what runs on every
platform, so it follows four rules:
- It reaches the desktop only through the `Platform`, and the daemon only through
`platform.komorebic` and `platform.state()`. It imports nothing from
`komorebi_vm.kde`, and it names no compositor, no program and no key of a
platform.
- It asks the operating system where a window is (`platform.os_window`) and
never the daemon: the daemon's state is what is under test, so it is read to
find out what the daemon believes and compared with what the OS has. A window
is told by the title the scenario gave it.
- It waits for a state with `platform.wait_for`, not with a sleep, and compares
frames with `platform.tolerance`, because a client may round its size to what
suits it.
- It is checked against a fake first. `tests/fake_platform.py` is a daemon in
memory that follows `focus`, `cycle-focus`, `move`, `cycle-move`, `stack`,
`cycle-stack`, `unstack`, `send-to-workspace` and `focus-workspace` over three tiles, with switches to make it wrong in
one way; a scenario's unit test runs it against the right daemon and against
wrong ones, so that a check that cannot fail is found without a VM.
A command the fake does not know is added to the fake with the scenario, and a
method the scenario needs of a platform is added to the `Platform` protocol, to
`KdePlatform`, and to the fakes, in the same commit. Then call the scenario from
a suite, as `core-e2e` does, and run that suite on KVM: a scenario that passes
the fake and fails on KDE has found a bug in the fake, the library or the daemon.
`Snapshot.focused_title` was found wrong this way, by the `stacks` scenario.
## A faster loop
- **The daemon is built once, not once per commit.** The VM tests install the daemon built with the
constant commit `nix-check` (`nixosModules.forVmTests`), as the checks do, so a new commit does not
build it again. The version a VM test sees is therefore not the commit. The source of the build
leaves out `nix/tests/vm/`, so editing a test, the library or a fixture does not rebuild it either.
`nix build .#komorebi-full`, and what a user installs, still has the real commit.
- **Each step says how long it took.** `run_suite` prints `[scope] module.function: 12.3 s` after
every step, so a log shows which scenario the time went to.
- **Run only some of the steps.** Set `E2E_ONLY` (`KFDE_ONLY` is the older name, still read) to a comma-separated list, and only the steps
whose name (as printed, `module.function`) contains one of the words run; the others are printed
as left out. A step that the others depend on (the one that opens the windows) is made with
`always=True` and runs whatever the list says. Evaluate with `--impure` for the variable to reach
the test:
```sh
E2E_ONLY=stacks,monocle nix build --impure .#checks.x86_64-linux.vm-core-e2e -L
```
A step that is left out returns `None`, so a suite that uses what a step returned must run that
step with `always=True`.
## Recording a run with komorebi-recorder
`komorebi-recorder`'s repository is private, so it is not an input of the flake. A run that wants
it builds it elsewhere and passes the store path, evaluating with `--impure`:
```sh
KOMOREBI_RECORDER=$(nix build ~/komorebi-recorder#komorebi-recorder --no-link --print-out-paths) \
nix build --impure .#checks.x86_64-linux.vm-core-lock -L
```
`core-e2e` and `core-lock` then record the session without video (`komorebi_vm.recorder`), print
the recorder's brief and findings into the log, and keep the session as `recording-NAME.tar.gz`
with the run's other artifacts. A run without the variable records nothing.
## Looking inside a failed run
`nix build -L` prints the guest's console, and a session test keeps its screenshots. Run the driver by hand, as
`scripts/vm-mac` does, to keep the screenshots. For an interactive session
build `driverInteractive` instead of `driver`, run it, and call `start_all()`
and `machine.shell_interact()` at its prompt. In the guest, KWin's own log is
`journalctl --user -u kwin-virtual@NAME` as the test user, and a KWin script's
`print()` goes to the same journal. The daemon's log is
`/run/user/1000/komorebi-NAME.log`. On the session node, the daemon of the
module's unit logs to `journalctl --user -u komorebi`, with colors, and to
`~/.local/share/komorebi/komorebi_plaintext.log.DATE`, without.
+278
View File
@@ -0,0 +1,278 @@
# Probing a NixOS-WSL2 machine
A Plasma guest that runs komorebi can be started on a Windows machine from a
NixOS virtual machine in WSL2: QEMU with KVM boots the guest, and its window is
shown through WSLg. Whether a given machine can do that depends on five things
that nothing but that machine can answer: whether WSL2 passes KVM through,
whether WSLg opens a QEMU window, whether the Windows GPU reaches OpenGL in
WSL, whether Windows can reach a port that the guest listens on, and whether the
guest can mount the host's `/nix/store` by virtiofs. The probe answers them in
about two minutes, and prints what to change for each answer that is not a yes.
It changes nothing on the machine. It reads files and system settings, boots a
tiny guest under QEMU that powers itself off, opens two windows for a few
seconds each, starts `virtiofsd` for a few seconds, and listens on two local
ports until it ends.
## Running it
From a checkout of this repository, in the NixOS-WSL2 shell, with flakes
enabled:
```sh
nix run .#wsl2-probe
```
`just wsl2-probe` runs the same command, and arguments for the script go after
it (`just wsl2-probe --hold 15`). Nix brings QEMU, `virtiofsd`, Mesa's
`eglinfo` and `glxinfo`, `socat` and the guest, about 1.6 GiB in the Nix store
as of 2026-10-28, most of it QEMU's and Mesa's dependencies. The guest is a
kernel and a static busybox from the binary cache, and the two kernel modules
that virtiofs needs, so nothing is compiled; building the module closure also
downloads the kernel's module tree (about 150 MB), which the probe does not keep.
While it runs, look at the Windows desktop: a QEMU window opens twice for 8
seconds (P2, then P3), and after each the script asks whether it appeared. The
answer is one of the things the script cannot find out itself.
| Option | Effect |
|---|---|
| `--only P1,P3` | runs only those probes (P0 always runs: the others read what it found) |
| `--hold SECONDS` | how long a window stays open (default 8) |
| `--yes` | answers yes to "did a window appear?" without asking |
| `--no-prompt` | asks nothing; this is also the case when stdin is not a terminal |
| `--dry-run` | runs P0 and P5, which only read, and prints what the others would start |
| `--report FILE` | where to write the report (default `wsl2-probe-report.txt` in the current directory) |
The exit status is 0 when the probes ran, whatever they found, and 2 for a
mistake in the options.
## Reading the output
Every line that carries a result starts with one of these:
| Tag | Meaning |
|---|---|
| `[PASS]` | the check passed |
| `[WARN]` | it works, but not as it should, or the check cannot say |
| `[FAIL]` | the thing the real guest needs is missing |
| `[SKIP]` | the check did not run, and the line says why |
| `[INFO]` | a value that was read or measured; the summary repeats it |
A `WARN` or a `FAIL` is followed by a `fix:` block with the exact change: the
lines for `%USERPROFILE%\.wslconfig`, an option of the NixOS configuration, or a
command for PowerShell. The checks have numbers (`P1.2`), and the fix of a
check often names another (`see P1.1`).
The output ends with a block between two lines of equals signs, headed
`PASTE THIS`: one verdict per probe, one line per check, and every fact the
probes read or measured. That block is what to send back. The whole output is in
`wsl2-probe-report.txt`, without colors.
## The probes
### P0: the environment
| Check | What it looks at | Verdict |
|---|---|---|
| P0.1 | `WSL_DISTRO_NAME`, `/run/WSL` and `/proc/version` | `PASS` on WSL2; `WARN` on WSL1 or when this is not WSL at all, where the probes can only report what they find |
| P0.2 | `nix config show experimental-features` | `PASS` when flakes are on; `WARN` with the NixOS option when not |
| P0.3 | `trusted-users` against the user and its groups | `PASS` when the user is trusted; `WARN` with the NixOS option when not |
The facts are the kernel, PID 1, `/etc/os-release` and `nixos-version`, the
`nixos-wsl` input of `/etc/nixos/flake.lock` if there is one, memory, the number
of processors, the free disk in `/nix`, the home directory, the directory the
real guest would keep its state in, the current directory and `/mnt/c`, the CPU
vendor, model and virtualization flag, the Nix version and substituters, and,
through interop, the Windows build, `wsl.exe --version` and the `.wslconfig` of
the Windows user. When interop is off, the Windows facts are missing and P4.1
says how to turn it on.
### P1: KVM
| Check | What it looks at | Verdict |
|---|---|---|
| P1.1 | the `svm` (AMD) or `vmx` (Intel) flag of `/proc/cpuinfo` | `FAIL` with the `.wslconfig` lines for nested virtualization when neither is there; `INFO` on a CPU that has neither flag by design |
| P1.2 | `/dev/kvm` exists and the user can open it read-write | `FAIL` when it is missing (nested virtualization) or closed to the user (the `kvm` group, with the exact `extraGroups` line) |
| P1.3 | a guest booted under `-accel kvm -cpu host` and the loop it ran | `PASS` with the loop time and the time of the whole boot; `FAIL` with QEMU's error and a fix chosen from it |
| P1.4 | the same guest under `-accel tcg`, software emulation | `PASS` with the times; `FAIL` means QEMU does not work here at all |
| P1.5 | TCG's loop time divided by KVM's | `PASS` at 3 or more, `WARN` from 1.5, `FAIL` below |
The facts are the nested-virtualization setting of `kvm_amd` or `kvm_intel`, the
QEMU version, the guest's CPU model, memory and flags (whether it sees `svm` or
`vmx` itself, and `hypervisor`, `avx`, `avx2`, `aes`), and the loop timed on the
machine itself with the same busybox.
The loop is 600000 iterations of an `ash` counting loop, timed from
`/proc/uptime` (a resolution of 10 ms, so the loop has to take about a second).
KVM runs the guest's instructions on the CPU, so its time is about that of the
machine itself; TCG translates them, and is several times slower. On a Xeon
6975P with KVM, at time of writing (2026-10-28), the loop took 970 ms on the
machine, 980 ms in a KVM guest and 11370 ms under TCG, 11.6 times as long. A
ratio under 3 means the acceleration is partial or absent, and the figure to
paste is `kvm_vs_tcg`.
### P2: display
| Check | What it looks at | Verdict |
|---|---|---|
| P2.1 | `WAYLAND_DISPLAY`, `DISPLAY`, `XDG_RUNTIME_DIR`, `/mnt/wslg` and the sockets in them | `PASS` when the shell can reach a display; `WARN` when only WSLg's defaults (`/mnt/wslg/runtime-dir/wayland-0`, `:0`) can, which the probe then uses for its windows; `FAIL` on WSL with none (`WARN` elsewhere) |
| P2.2 | `-display gtk -device virtio-vga` for `--hold` seconds, with the guest printing a line a second | `PASS` when QEMU started, the guest ran to its end with the window up, and QEMU exited 0; `FAIL` with QEMU's error otherwise. When the window system the toolkit picked fails and both are available, each is tried by name (`GDK_BACKEND`) |
| P2.3 | your answer to "did a window appear?" | `PASS` for yes; `FAIL` for no; `INFO` when it was not asked (`--no-prompt`, no terminal) or `--yes` answered it |
A line says when the framebuffer's frame rate was not measured: the guest is a
text console, so there is no moving picture to count frames of.
### P3: GPU
| Check | What it looks at | Verdict |
|---|---|---|
| P3.1 | `/dev/dxg`, the device through which WSL2 passes the Windows GPU | `FAIL` on WSL when it is missing: the Windows driver needs WSL support |
| P3.2 | `libd3d12.so`, `libd3d12core.so` and `libdxcore.so` in `/usr/lib/wsl/lib`, where WSL mounts the Windows driver's libraries | `WARN` when they are missing |
| P3.3 | the same libraries linked into `/run/opengl-driver/lib`, which is what `wsl.useWindowsDriver = true` does on NixOS-WSL | `WARN` with the options when they are not |
| P3.4 | the OpenGL renderer that `eglinfo -B` and `glxinfo -B` report on the machine, in four environments: as it is, with `LD_LIBRARY_PATH=/usr/lib/wsl/lib`, with `GALLIUM_DRIVER=d3d12`, and with both | `PASS` when one of them reports a hardware renderer (`d3d12` or other), naming the environment that does; `WARN` when all report `llvmpipe` or none works |
| P3.5 | `qemu -device help` and `-display help` list `virtio-vga-gl` (`virtio-gpu-gl-pci` on aarch64) and `gtk` | `FAIL` when not: the QEMU of nixpkgs lacks it |
| P3.6 | `-display gtk,gl=on -device virtio-vga-gl` for `--hold` seconds | the same as P2.2, with the environment of P3.4's variant tried when the default one fails; QEMU's refusal is printed |
| P3.7 | your answer to "did the VirGL window appear too?" | as P2.3 |
The facts include the contents of `/usr/lib/wsl/lib` and `/usr/lib/wsl/drivers`,
the Windows GPU name and driver version from `Win32_VideoController`, and each
renderer line per variant (`host_gl[default]`, `host_gl[d3d12]`, ...), which names
the renderer that each platform of `eglinfo` (X11, Wayland, GBM, surfaceless)
reports. A renderer string that names `d3d12` is Mesa's Direct3D 12 driver,
which draws on the Windows GPU; `llvmpipe` is Mesa's software rasterizer.
What happens inside the guest is not checked: the guest of this probe has no
graphics stack, so the renderer that a Plasma session in it gets (VirGL on the
host's renderer, or `llvmpipe`) is for the real guest to report.
### P4: the Windows side
| Check | What it looks at | Verdict |
|---|---|---|
| P4.1 | `cmd.exe /c ver` through interop | `FAIL` with the NixOS-WSL interop options when Windows programs do not run from WSL |
| P4.2 | `mstsc.exe`, Windows' RDP client, on `PATH` or in `System32` | `PASS` when found; `WARN` with the `includePath` option when not |
| P4.3 | two `socat` listeners on free ports above 20000, one on `127.0.0.1` and one on `0.0.0.0`, and a TCP connection to each from `powershell.exe`, as `127.0.0.1` and as `localhost` | `PASS` when Windows reaches the loopback listener both ways; `WARN` when only `127.0.0.1` works, or only the `0.0.0.0` listener is reachable; `FAIL` when nothing is, with the `.wslconfig` lines for `localhostForwarding` and `networkingMode` |
The facts are the path of `cmdkey.exe` (which a later step would use to hand
Windows the RDP credentials), the networking mode (`wslinfo --networking-mode`,
or `networkingMode` of `.wslconfig`: NAT by default, or mirrored), the
`localhostForwarding` setting, the WSL machine's addresses, and the four
connection results.
Outside WSL, P4 says so and checks nothing.
### P5: resources
The real guest wants 8 GiB of memory, 4 or more cores, and about 25 GiB of disk,
plus the space the Nix build takes.
| Check | What it looks at | Verdict |
|---|---|---|
| P5.1 | `MemTotal` of the WSL machine | `PASS` from 10 GiB (8 for the guest, 2 for WSL and Nix next to it); `WARN` from 6 GiB, where the guest would run with `--memory 6144`; `FAIL` below, each with the `memory=` and `swap=` lines for `.wslconfig` |
| P5.2 | `nproc` | `PASS` from 4; `WARN` below, with the `processors=` line |
| P5.3 | the free space under `/nix`, or on the Windows drive under the virtual disk when that is less | `PASS` from 40 GiB (25 for the closure and the guest's disk, 10 for the build); `WARN` from 25; `FAIL` below |
On WSL the virtual disk looks like a terabyte; what limits it is the Windows
drive it lives on, so the probe reads `/mnt/c` as well and takes the smaller of
the two.
### P6: virtiofs
The real guest does not copy the host's `/nix/store`: it mounts it. On a Linux
host nixpkgs' QEMU runner starts one `virtiofsd` per shared directory (the
store, the repository, the directory of the credentials), and QEMU joins the
guest's virtio-fs device to each daemon's socket, with the guest's memory in a
shared `memfd`. This probe builds the same chain, with the same options as the
runner, for the host's `/nix/store` (read-only) and a temporary directory
(writable), and a guest whose kernel is the one the real guest boots.
| Check | What it looks at | Verdict |
|---|---|---|
| P6.1 | `/dev/fuse` exists and the user can open it read-write | `PASS`; `WARN` with the NixOS lines when it is missing or closed: `virtiofsd` does not open it (see below), so the guest can still start |
| P6.2 | `virtiofsd` (the one of nixpkgs, as the runner uses) starts as the user, with `--sandbox=none --seccomp=none --translate-uid ...`, and makes its socket, for `/nix/store` read-only and a temporary directory writable | `FAIL` with the daemon's output when a socket does not appear; `SKIP` when the program is not there |
| P6.3 | QEMU boots the guest with `-object memory-backend-memfd,share=on`, `-machine memory-backend=` and two `vhost-user-fs-pci` devices, under KVM when `/dev/kvm` opens and under TCG otherwise | `FAIL` with QEMU's error, or when the guest does not run to its end |
| P6.4 | the guest loads `virtio_pci` and `virtiofs`, mounts `/nix/store` read-only, and its checksum of the busybox it came with equals the host's; a write is refused | `FAIL` with the guest's error and, when the module did not load, that; `WARN` when the share could be written |
| P6.5 | the guest mounts the writable directory, reads a random token the host wrote, and writes a file that the host reads | `FAIL` when any of the three does not work |
The facts are the path and version of `virtiofsd`, the warnings it printed, how
each module loaded in the guest (`built in` for a kernel that has the transport
in its image), the file systems the guest lists, what the guest saw (the
checksum, the owner and mode of the host user's file, of the file it wrote) and
the owner of the file it wrote as the host sees it.
What is known of `virtiofsd` before WSL2 (read at time of writing, 2026-10-28,
from `virtiofsd` 1.14.0 and nixpkgs' runner on Linux machines that are not WSL2):
- it runs as an ordinary user with the runner's options, and prints two
warnings, that it could not raise the limit of open files above the hard limit,
and that it cannot use file handles for the root node (`Operation not
permitted`) and falls back to `O_PATH` descriptors; both are harmless;
- it never opens `/dev/fuse`: a `strace` of its start shows no such open. It
speaks FUSE to the guest's kernel through the vhost-user socket, so the
daemon needs the socket, a shared `memfd` in QEMU, and the directory;
- a file that the host user owns appears in the guest owned by the same numeric
uid and gid (`--translate-uid host:65534:0:1` maps only the host's 65534),
which is why the guest user of the demo cannot read a directory of a host
user whose uid is not 1000 when its mode is 0700;
- the kernel configuration of WSL2 (`linux-msft-wsl-6.6.y`, `config-wsl` for
`x86_64`, read from its repository, not measured on a machine) has
`CONFIG_FUSE_FS=y`, `CONFIG_MEMFD_CREATE=y`, `CONFIG_USER_NS=y`,
`CONFIG_UNIX=y`, `CONFIG_DEVTMPFS=y` and `CONFIG_KVM_AMD=m`: nothing the
chain needs is missing from it. `/dev/fuse` is a device node that the kernel's
devtmpfs makes closed to ordinary users, and udev's default rules open it, so
where udev's rules do not apply it can be closed, which `virtiofsd` does not
mind.
On WSL2 itself the chain is not measured at time of writing: the paste of the
first run is the first fact.
## The NixOS-WSL option names
The fixes name these options of NixOS-WSL: `wsl.useWindowsDriver`,
`wsl.interop.includePath`, `wsl.interop.register` and `wsl.wslConf.interop.enabled`,
and of NixOS itself `users.users.<name>.extraGroups`, `nix.settings.trusted-users`
and `nix.settings.experimental-features`. NixOS-WSL renames options now and then;
when `nixos-rebuild` rejects one, its options page has the current name.
## How the script is checked
The script is `scripts/wsl2-probe.sh` and the flake wraps it
([`nix/dev/wsl2-probe.nix`](../../nix/dev/wsl2-probe.nix)): `packages.<system>.wsl2-probe`
and the app of the same name, and `wsl2-probe-guest`, the kernel and the initrd
(with the modules of virtio's PCI transport and of virtiofs).
The initrd's init and the loop are `nix/dev/wsl2-probe-init.sh` and
`nix/dev/wsl2-probe-loop.sh`; the same loop file is what the script times on the
machine.
Two checks of the flake keep the script from rotting between the times someone
runs it. `wsl2-probe` builds the wrapper, which runs ShellCheck over the script
and over the guest's init, so neither can have a warning. `wsl2-probe-dry-run`
runs `wsl2-probe --dry-run` in the build sandbox, which has no KVM, no network
and no display, and expects a line for every probe, the paste block, and a
refusal of an unknown option. `just lint` runs ShellCheck on the script as well.
The script was exercised, at time of writing (2026-10-28), on machines that
are not WSL2:
- an `x86_64` NixOS machine with KVM: P1 passes with the ratio above; P2 passes
under `xvfb-run` and reports "no display" without one; P3 reports the missing
OpenGL driver and QEMU's refusal of `gl=on`;
- an `aarch64` NixOS machine without KVM: P1 reports the missing `/dev/kvm` and
boots the guest under TCG alone;
- the `x86_64` machine again with stand-ins for Windows' `cmd.exe`,
`powershell.exe` (PowerShell 7, running the script's PowerShell), `wsl.exe`
and `wslpath` on `PATH` and `WSL_DISTRO_NAME` set, for the paths that need
interop, and with `/dev/kvm`, `/proc/cpuinfo` and `/proc/meminfo` replaced
inside a user namespace for the failing and short-of-resources verdicts;
- P6 on the `x86_64` machine with KVM (the whole chain passes; the guest boots
in 1.2 s), on the `aarch64` machine under TCG (passes; 3.7 s), under TCG on
the `x86_64` machine with `/dev/kvm` closed in a user namespace (passes;
4 s), with `/dev/fuse` closed in a user namespace (`WARN`, and the rest
passes), with `virtiofsd` off `PATH` (`SKIP`), with a `virtiofsd` that exits
(`FAIL` with its output), and with a stand-in for QEMU that refuses the shared
memory, or prints what a guest would after each way the mounts can fail (the
verdicts of P6.3 to P6.5 for each).
Nothing in the script has run on WSL2 itself at time of writing, so the paste of
its first run there is the first measurement of any of this on WSL2.