The last check of focus_follows_mouse fails on a Windows guest after
the setting was turned off with the pointer on a window and on again;
disable then enable works. The cause is not known, and the scenario is
unchanged.
Reported by the kfw session from a probe: the reconciliator sees the
removal and loops on it, and state lists two monitors for as long as it
is watched. It passes in some runs, so it is not a known failure; the
check stays red when it fails.
Run once on a real KWin with every tile 200 pixels too wide, and not
committed: seven checks failed, all about tiles on each other, and the
other 139 passed.
A port that cannot start with a case's rules, or orders its windows
otherwise, is recorded as a known failure for that case, and the other
cases run on. kfw does not accept the place as a JSON number, so
BEHAVIOUR.md lists the case as a known failure there.
A window kfw had cloaked is uncloaked by the stop and managed again on
the first workspace. A minimized window is left minimized and is not
managed. The lifecycle scenario counts only the windows in view.
The pointer on kfw reaches the first display only, because QMP's
absolute tablet is mapped there. The commands sweep passed in the two
runs that had the host to themselves and failed in the two that ran
beside a VM suite and a build.
kfw's 0ffc502c fixes the resize shortfall: a 60 pixel drag widens the
left tile by exactly 60. The commands sweep passes with a second
display, and rules, hotplug and lifecycle pass on a Windows guest.
The earlier sweep failures came with a kfde suite running beside it.
Checks.known_failure records a check that fails for a reason that is
to be followed up on: the suite does not fail, the totals say how many
known failures there are, and one that holds fails the suite so the
marker goes. unknown_monitor takes the reason, and core-e2e runs it
last, because the window it loses stays lost. BEHAVIOUR.md says so.
The scenario sends the focused window to monitor 7 with send-to-monitor and
move-to-monitor, which no display has, and checks that the daemon still
manages every window. A port may refuse or ignore the command, but a window
that was managed has to stay so: one that is not is left on the screen with
nothing tiling it.
It found a bug in both ports. kfw managed one window fewer than the OS had
afterwards (seen by hand on a Windows guest), and kfde failed it in
core-e2e on a real KWin: move_container_to_monitor takes the focused
container out of its workspace before it looks the monitor up, so the
error for a monitor that is not there comes after the container is gone.
It is not fixed, so the scenario is not in core-e2e, which would fail;
BEHAVIOUR.md has the finding. Its unit tests run it against a fake that
loses the window and one that ignores the command.
A table of the scenarios against the two ports, with where each result
comes from, the resize finding and its cause (kfw reads the rectangle a
drag started from when it handles the start event, about 100 ms after the
drag began, so the distance it measures is short by what the window moved
in that time, and more so for a longer drag), what the scenarios had to
allow for, and what is not covered.
Seven of the eight shared scenarios pass on a Windows 11 guest under QEMU
against kfw's daemon, as the session that ran them reports. The eighth,
resize, ran there and found that the edge moves less than the pointer; an
unmanaged window followed the same drag exactly, so the shortfall is in
what kfw does with the drag.
monocle toggles monocle on the focused window and checks that it fills the
work area up to the layout's padding, that the state has it as the monocle
container, that every other window is put away, that it keeps the focus,
and that toggling back puts every window in view on the tile it had.
closing closes a window and checks that the OS has no frame for it, that
the daemon manages one window fewer, and that the windows left in view
take more room between them, inside the work area and clear of each other.
Platform.close closes a window as its button would; KdePlatform does it
with kdotool. The fake daemon models monocle and closing, and its
os_window now knows the workspace a window is on, which the workspaces
scenario had passed without. core-e2e runs both: 120 checks pass on KVM.
Platform.has says whether a platform can do what a scenario needs, and
Platform.pointer is a Pointer (move, down, up, drag) where it has one;
KdePlatform takes the pointer of a session node. scenarios.resize drags the
edge two tiles share by 60 pixels and checks that the tiles that end at the
edge are that much wider, the ones that start after it start that much
later and end where they did, nothing moves up or down, and tiles that do
not touch the edge are where they were. A platform with no pointer skips
it, and says so.
The fake daemon has a pointer that moves an edge. The scenario runs on KDE
at the end of drag-resize: 19 checks pass on KVM. Its first run failed one
check that was the scenario's: both tiles of a BSP column share the dragged
edge, and the check took the second for one that had not moved.
core-e2e writes the komorebic state of kfde, with three tiled windows and
with one stacked onto another, into its output, and the files are kept in
tests/fixtures beside kfw's three, recorded from a Windows guest (tiled,
stacked, one window floated). test_recorded.py reads all five with the
same checks: three containers of one window, a layout rectangle for each
inside the work area, each window where its container's rectangle is up to
a terminal cell (foot rounds to cells, kfw's test window does not), and a
stack that is a container of two whose focused window is the one the ring
names. Nothing in the parser had to change; the checks passed on the first
real kfw state.
The scenes written from the serializers stay for the shapes no run has
recorded. The sync script copies the fixtures too. The workspaces scenario
prints which windows are in view after the switch: one run of core-e2e
failed that check and passed on the next, and the log did not say which
window had been in view.
tiling has run against kfw's daemon on a Windows 11 guest under QEMU, 10 of
10 checks, with this core copied unchanged; the other four scenarios have
not run there yet. Says so in vm-tests.md, and what keeps the copy in
step.
latency measured a p95 of 128.9 ms against its 100 ms times scale on the
WSL2 machine, under nested KVM with nothing else running, where x86-1 had
passed it at scale 1. Every Linux host is no faster than a Mac to the
suites that time the daemon, so scale is 1.5 on all of them: latency
passes at it with a p95 of 132.4 ms against 150 ms. The run-to-run
difference (p50 46.0 ms, then 70.0) is as large as the margin left, which
PLATFORM.md says.
PLATFORM.md records the wall times of the suites on this machine. All 33
were run there after the library was split: 32 passed at scale 1, and
latency is the one that failed. The other 32 were not rerun at 1.5, which
changes their derivations.
workspaces sends the focused window to workspace 1, checks that it is put
away and that the daemon has it there while the others stay in view,
switches to workspace 1 and checks that only that window is in view and has
the focus, and switches back.
hidden now says a window is out of sight for any reason the daemon has: on
KDE that is the parking desktop and also a desktop that is not the one in
view. Snapshot's workspace, containers and focused_title take the focused
workspace when none is given, and the fake daemon has two workspaces. The
scenario passes in core-e2e on KVM: 106 checks.
hidden says that a window exists but the daemon has put it away: the others
of a stack, here, and later those of another workspace or behind a monocle.
It is a window on the parking desktop on KDE and will be a cloaked one on
Windows. scenarios.stacks stacks the focused window onto its neighbor,
cycles the stack, checks that the window in view has the focus and fills
the tile the first had, and takes the stack apart.
The scenario's fake daemon now models stacks. Running it on KDE found a bug
in Snapshot: focused_title took the first window of the focused container,
and a stack's focused window is the one its ring names. Snapshot keeps that
index now. core-e2e runs the scenario after the others: 98 checks pass on
KVM.
focus moves the focus with focus and cycle-focus and checks that the OS and
the daemon's state agree on the window that has it and that no window moved.
moving swaps the focused window with its neighbor with move and puts every
window back with cycle-move, and checks that the focus stays with it. Both
read the windows through the Platform, so they are what kfw's suite will
run.
Their unit tests run against a fake daemon that follows the commands over
three tiles, and against two that do not (a move that moves nothing, a move
that loses the focus). core-e2e runs them after tiling on KDE: 85 checks
pass on KVM.
KdePlatform is a Kde session seen through the neutral vocabulary: kdotool
for the OS's frames, foot for clients, the cell of its font as the
tolerance. The core-e2e suite runs scenarios.tiling through it as a new
section, so that the scenario that will run on Windows is checked on the
one platform that works; the suite's own sections are unchanged. It passes
on KVM (74 checks) on the WSL2 machine.
komorebic state prints a different JSON on kfde and on kfw: a window is
{id, rect, details} on one and {hwnd, title, exe, class, rect} on the
other, and a monitor and the state itself have fields the other lacks.
core.snapshot.parse reads either into monitors, workspaces, containers and
windows with the same names, keeping what only one has in Snapshot.extra,
so that a scenario does not have to care which port it runs on.
The fixtures in its tests are written from the two serializers, not
recorded; they are replaced by recorded states once a run on each port
exists.
Checks, Rect and the pixel helpers depend on no compositor. They move to
komorebi_vm.core, which may not import komorebi_vm.kde, so that the package
can go to the Windows port unchanged. komorebi_vm re-exports them and no
suite changes. This is the first step of the cross-platform e2e plan.
The guide for the one command: docs/trying-it.md says what a machine needs to
run the demo guest, with the lines of .wslconfig and of the NixOS-WSL
configuration for Windows 11, how to check it with `run-kde --doctor`, what the
command does and shows, the key bindings to try, how the GPU path is chosen, how
to open Windows' own RDP client, how long the first run takes (measured on a
machine with 32 cores and an empty store, by number of cores, with an estimate
for a WSL 2 machine and its caveats), how to start again, how to work on
komorebi in the guest, and what to do when something is wrong, by symptom. It
ends with what was run and what was not: nothing has been run on WSL 2 yet. The
README has a section and a link, and the user guide index a line.
DESIGN.md has four entries. Two record what I decided and want: the QEMU window
first and RDP second, and the GPU wherever the host has one. Two say that a
reason was not written down, for QEMU with KVM and not Hyper-V and for sharing
the password by a directory, and what is known that bears on each; the password
entry also says why a password is made for each user. PLATFORM.md has a section
for WSL 2 with what the command expects, a table of the probe results still to
be recorded (KVM, display, GPU, RDP, resources, virtiofs), and what is known of
virtiofsd without WSL 2.
The demo guest is what the command `run-kde` starts, so it should not stop
working between the times somebody runs it by hand. The suite `run-kde` puts the
guest module, nix/dev/run-kde.nix, on the session node, as the rdp suite does
with krdp.nix, and checks what only a booted session can say: the demo opens two
Konsole windows, Kate and Dolphin and komorebi tiles them clear of the panel,
the cheat sheet is a window that is not a tile, what it shows of `komorebic
check` has no error, and KWin says what it draws with.
The node makes the directory the host shares as the guest finds it once it has
mounted it: owned by a user the guest does not have, with a password and a
public key in it. The suite checks that the guest takes them as root before the
login, that ssh lets in that key and no other, that KRDP starts by itself and
listens, and that a client with the password is let in and shows the display.
The client of those RDP checks moves from the rdp suite into the library as
RdpClient, with unit tests against the fake machine, so that both suites run the
same checks; the machine protocol gains copy_from_machine for it.
Starting the demo guest by hand takes a build, a state directory, a password, a
key, the sizes of the machine and the right arguments for its display, and a
mistake shows up as an error from QEMU a minute later. `run-kde` does all of it:
`nix run .#run-kde` (or `just run-kde`) checks the machine, builds the guest
when its runner is not in the store, with the build log shown, makes the state
directory with a sparse disk, a random RDP password and an ssh key (all mode
0600, none of it in the Nix store), and starts the runner with KVM, the memory
and cores the machine has, the repository at /repo, and the state directory at
/run/run-kde. It prints a banner with the RDP address and password, the ssh
command, how to quit, and which graphics mode it chose and why.
`--doctor` prints every prerequisite as a tick, a cross or a warning with the
exact fix: WSL 2 or not, KVM and its group, nested virtualization, virtiofs (a
virtiofsd started as the user with the options of the guest's runner must serve
a directory, since the guest mounts its /nix/store through one; /dev/fuse is
only a warning), memory, disk, WSLg, Windows interop, the GPU and the OpenGL of
the host, and the lines of .wslconfig. It exits with 1 when something is a
cross, which includes a missing KVM unless `--tcg` allows software emulation.
The GPU is used when the display is a window, the host has a GPU device and its
OpenGL is not llvmpipe, and `--gpu on|off` overrides it; on WSL 2, `--rdp` opens
mstsc with a credential that lasts as long as the run.
The script reads the machine through variables, so `--dry-run` and `--doctor`
can be tested against machines that a check makes up: `run-kde-dry-run` and
`run-kde-doctor` compare their output with the texts in nix/tests/run-kde, and
the package, which shellchecks the script when it is built, is a check too.
A person who wants to see komorebi tile windows should not have to configure a
machine first. `run-kde-x86_64` and `run-kde-aarch64` are the session guest with
a demo on it: the NixOS module configures komorebi from a typed `config` (eight
workspaces, borders, animation) and the sample skhd bindings, and at login the
guest opens two Konsole windows, Kate and Dolphin, which komorebi tiles, and a
cheat sheet window that it leaves alone, with the key bindings, `komorebic`
commands to try, what KWin draws with, and the output of `komorebic check`.
The closure is the same for everyone. No password or key is in it: the host
shares a directory, which the guest mounts at /run/run-kde, and a unit copies
the RDP password and the ssh public key from it, since the files can belong to a
user of the host who is not the guest user. krdp.nix reads the password from the
file that `komorebi.krdp.passwordFile` names when it exists. The display device,
the port forwards, the memory and whether to insist on KVM are left to the
environment of the runner, so that one closure and one disk run with a software
virtio-vga or with a virtio-vga-gl that renders on the host GPU. The module is a
separate file that does not import plasma-vm.nix, so that a VM suite can put it
on the session node.
plasma-guests-eval asserts the same of the demo guests.
The Plasma guests were made for an Apple silicon Mac only: the flake fixed the
guest to aarch64-linux and the host of QEMU to the Mac. `mkPlasmaGuest` now
takes the system of the guest and the packages of the machine that runs QEMU,
and the flake has the two QEMU guests for a Linux machine with KVM as well:
plasma-vm-x86_64 and plasma-vm-session-x86_64, and the same pair for aarch64
(plasma-vm-aarch64, plasma-vm-session-aarch64). The three guests of a Mac keep
their names and are built from the same instructions.
An x86_64 machine has a VGA that QEMU adds unless it is told not to, which would
be a second display next to the virtio-gpu that KWin draws on. An x86_64 guest
therefore gets virtio-vga, a virtio-gpu that is also the VGA, and `-vga none`;
an aarch64 guest has no VGA and keeps virtio-gpu-pci.
plasma-guests-eval evaluates every guest and asserts what each is for: the
architecture of the guest, the system of its host, KVM or HVF, and one display
device. docs/dev/utm.md says which guest is for which host and how to build and
run one on a Linux machine; the README and CONTRIBUTING say that there are
guests for both.
The port can only be tried on a Windows machine, through a NixOS virtual machine
in WSL2, which the machines this history is built on do not have. What such a
machine can do for a Plasma guest is not known until something runs there, and
every guess about it is a risk for what comes next. wsl2-probe is that
something: one command, nix run .#wsl2-probe, that answers in about two minutes
what the guest needs to know and prints, for each answer that is not a yes, the
exact change: the .wslconfig lines, the NixOS option, the PowerShell command.
It checks the environment (WSL2, memory, disk, .wslconfig, Nix); KVM (/dev/kvm,
its group, and a tiny guest booted under KVM and under TCG, with the same loop
timed in both and on the machine itself, which must differ by several times);
the display (a QEMU GTK window through WSLg for a few seconds, and whether you
saw it); the GPU (/dev/dxg, the Windows driver libraries, the OpenGL renderer in
four environments, and virtio-vga-gl with gl=on); the Windows side (interop,
mstsc.exe, whether Windows reaches a port that WSL listens on); whether memory,
cores and disk are enough for the real guest; and virtiofs, which the real guest
uses for its /nix/store and every shared directory (/dev/fuse, virtiofsd as the
user with the options of nixpkgs' runner, and a guest that mounts the host's
/nix/store and a writable directory, reads, writes and compares). Each probe
runs apart from the others, so one that fails leaves the rest alone, and the
output ends in a block to paste back, which is also written to
wsl2-probe-report.txt.
The flake wraps the script with QEMU, virtiofsd, Mesa's eglinfo and glxinfo and
socat from nixpkgs, and builds the guest, a kernel from the binary cache, the
two modules of it that virtiofs needs and a static busybox initrd, as
wsl2-probe-guest, so nothing is compiled on the machine. Two checks keep the
script from rotting: wsl2-probe builds the wrapper, which runs ShellCheck over
the script and over the guest's init, and wsl2-probe-dry-run runs --dry-run in
the build sandbox, which has no KVM, no network and no display.
docs/dev/wsl2-probe.md says what each check means and how to read it.
nixpkgs moves from d3b13ad (2026-10-24) to f05535a (2026-10-27) and rust-overlay
from c7e9d51 to 19ecdd0; the other six inputs have no newer revision. KWin,
Plasma and KRDP go from 6.8.1 to 6.8.2, so testedMax in nix/supported-kwin.nix
goes to 6.8.2, with its dated comment. Qt (6.12.0), FreeRDP (3.32.2) and the
glibc of nixpkgs (2.44) keep their versions. The stable Rust toolchain stays at
1.99.1; the nightly rustfmt moves from 2026-10-27 to 2026-10-28.
nixpkgs now has KDE Rounded Corners 0.11.0. nix/kde-rounded-corners.nix still
sets the version and the source, because its patch is written for the 0.11.0
source, so the package does not change: it builds with its patch, and Geometry
Change builds, against KWin 6.8.2. The dated sentences of README.md, DESIGN.md,
PLATFORM.md, COMPARE.md and of the docs of kwin/effects.rs say 2026-10-28 and
the new versions. Measurements taken on 6.8.1 keep their date and version, since
none was repeated on 6.8.2.
The glibc floor does not move: komorebi and komorebic still need 2.39 on aarch64
and on x86_64 (pidfd_getpid and pidfd_spawnp, both weak references), measured as
the build job measures it, before and after patchelf.
The gate with the nix checks passes on an aarch64 box and on x86-1,
nixos-module-eval among them (the KWin version scenarios included). The VM
suites run against the tip of these two commits; the result is in the message of
the next commit.
The Komorebi License lets anyone distribute the source code but not binaries, so
the flake has no public binary cache and the binaries of komorebi come only from
this repository. The `build` job builds `komorebi` and `komorebic` with nix on
every run, on ubuntu-24.04 and on ubuntu-24.04-arm, and keeps them as an
artifact for 14 days; the arm64 job is `continue-on-error`.
As nix builds them, the binaries load libc, libm and libgcc_s through the
dynamic loader of the store and an RPATH into it, which only a machine with the
same nixpkgs revision in its store has. The job points them at the system's
loader at its standard path and drops the RPATH, with patchelf from the nixpkgs
flake.lock pins, then runs `--version` on the Ubuntu runner to check that they
start. Built from the locked nixpkgs (d3b13ad), the newest glibc symbol version
they need is 2.39, the glibc of Ubuntu 24.04.
The `publish` job runs on a `v*` tag, and on a scheduled or manual run on
master, once lint, vm-fast and build have passed. It zips the two binaries of
each architecture as `komorebi-<version>-<target>.zip` (an architecture whose
build failed is left out with a warning), adds schema.json, the schema of
komorebi.json, when the repository has one (it does), and writes checksums.txt
with sha256sum. The release notes are kokai's, from the commit messages since
the previous version tag, as komorebi for Mac writes them; kokai is not in
nixpkgs, so cargo installs it, pinned at 0.3.1. A tag becomes a release. master
replaces the rolling `nightly` prerelease and its tag; the old nightly tag is
moved to the commit first, so that the notes list the commits since the last
version and not since the last nightly. There is no Homebrew, winget or second
repository.
The cache key of the composite action gets the runner's architecture: the arm64
runner has the same `runner.os` as the x86_64 one, and would restore and save
the other's store.
The steps were run as written on aarch64 and x86_64 machines: the builds, whose
binaries then started in Ubuntu 24.04 root filesystems of both architectures,
and a first nightly, a later nightly and a tag release against a fake gh. GitHub
Actions has not run them yet. CONTRIBUTING.md says how a release is made, the
README where binaries come from and what the license allows, and DESIGN.md why.
The pages that said there were no prebuilt binaries (README, installation.md and
the entry on the binary cache in DESIGN.md) now say that the releases are the
only ones.
docs/dev/COMPARE.md says what komorebi for KDE shares with komorebi for Windows
and komorebi for Mac, what differs, what KDE does by itself and what is not
supported, for a reader who knows komorebi on one of them. Its tables are
generated by scripts/compare-gen.py from this checkout and from checkouts of the
other two, because a count or a name typed by hand is wrong after the next
change to a command, a key or an event. The script also checks the notes that
say why a command has no counterpart, and the sentences of the document that
depend on a table, and stops when one of them is no longer true. CI has neither
checkout and cannot run it; CONTRIBUTING says when to run it. The tables have no
column for the commit that added a row: the plan that numbered the commits is
not in the repository, and a number the script cannot derive for the next commit
would stop it.
The other documents had places that said something the repository does not carry
or does not do:
- DESIGN cited docs/kde.md, which no commit carries, said spike 8 "asked
whether" one komorebi.json could be shared, and described the default of the
key binding mode as a plan. Each entry now states the rule and the evidence.
The first entry no longer says that the Windows implementation is the
reference: both it and the macOS one were read, and the native thing is
preferred where the other two need a workaround.
- "The spikes" was used in PLATFORM, DESIGN and COMPARE and defined nowhere.
PLATFORM's vocabulary defines it, and PLATFORM has a list of what was not
measured, which COMPARE links to.
- ARCHITECTURE said a maximized window is hidden with its workspace and shown
with it, and that the code has a TODO for cycling the focus. A workspace
switch hides nothing, since KWin shows and hides the desktop's windows, and
the cycle leaves a maximized window as it is; the TODO and the commented-out
code under it in window_manager.rs are replaced by a comment that says so. The
Key bindings section no longer repeats the headings of the sections before it.
- README listed the subcommands that work without the daemon, and the list was
short. It gives the rule and one example of each kind.
- The page on changing monitors opened with "nothing to configure" and then
named display_index_preferences.
- COMPARE said KWin waits 300 ms for the pointer to settle before it moves the
focus. That is KWin's default (DelayFocusInterval, in KWin 6.8.1), and
komorebi sets it to 0 while focus follows mouse is on; the page now says so.
- ARCHITECTURE's opening list of what the page describes stopped at the borders
and had no word of animation, themes, wallpapers, transparency, focus follows
mouse or key bindings. Two link definitions that it had twice are there once.
- PLATFORM's list of what was not measured has the progress of the stock
animation effect against the clock: one capture showed none four seconds into
a 30 s animation, where the curve gives about 60 %.
- README, docs/index.md and ARCHITECTURE link COMPARE.md.
- COMPARE's list of the methods of Backend has drag_end, which the end of a
resize is read through, and compare-gen.py has the row and the counts.
The VM tests boot a machine, run a scenario and power it off. Trying a change by
hand needs a Plasma session that stays up, and on a Mac, one that renders on its
GPU.
nix/dev/plasma-vm.nix is a guest for QEMU on an Apple silicon Mac, headless or
with a Plasma session that logs in by itself, and nix/dev/plasma-utm.nix is that
session as a disk image for UTM, whose QEMU renders on the Mac's GPU. They are
nixosConfigurations of the flake, and install komorebi with services.komorebi
from the flake's packages. They carry no key, password or configuration of
anyone's: the console logs in by itself, ssh takes the keys a user puts in the
guest, and the RDP password is a file in the guest. plasma-guests-eval evaluates
the three on every system.
nix/dev/krdp.nix runs KRDP in the session, and the slow suite vm-rdp runs the
same unit in the session node: it waits for a password and listens once it has
one, FreeRDP's client is let in with the password and not with another, and the
picture the client gets on an X server of its own is the display. FreeRDP
decodes KRDP's H.264 with OpenH264 and shows nothing, so the guests' client is
built without it and decodes with FFmpeg. Keys over RDP stay unverified, since
no client can script them against KRDP; PLATFORM.md says so and what the suite
checks.
docs/dev/utm.md says how to build and run the guests, and what a builder has to
be.
komorebi relies on the per-output virtual desktops of KWin 6.8, and the
repository follows the tip of nixpkgs-unstable, so a system can have a KWin that
is too old, or one that no VM suite has run against yet.
nix/supported-kwin.nix records both ends: min, the oldest KWin komorebi
supports, and testedMax, the newest one every VM suite has passed against
(6.8.1, with nixpkgs d3b13ad). It is a plain attribute set, so a CI job can read
it with `nix eval --file`. The module asserts that pkgs.kdePackages.kwin is min
or newer, and warns when it is newer than testedMax;
services.komorebi.kwin.untestedIsError makes that an error.
nixos-module-eval gives the system a KWin of a version of its own, so that no
check depends on the KWin of the lock, which moves with the tip, and checks the
assertion, the warning and the option in ten more checks. CONTRIBUTING.md,
PLATFORM.md and vm-tests.md say how testedMax is raised: by a commit, once every
suite has passed against the newer KWin, that says which suites ran.
komorebi follows the tip of nixpkgs-unstable, so KWin and Plasma move under it
each time flake.lock does, and the pull request that moves the lock runs the
slow VM tier only when it is labeled. The `canary` job of ci.yaml, on the weekly
schedule and on a manual run, copies the checkout, runs `nix flake update
nixpkgs` in the copy and builds every check against the result: the checks that
need no virtual machine, listed as the lint job lists them, then the suites of
both tiers, listed from `vmTiers` as the discover job does. They run one after
the other on one KVM runner, so that komorebi and the guests are built once
against the new nixpkgs; the job may take the six hours a hosted runner allows.
When a check fails, the job opens an issue titled "Canary: a check fails against
the tip of nixpkgs-unstable" with the failed checks, the nixpkgs revision, and
the KWin version at the tip and in flake.lock, or comments on that issue if it
is open. The same report goes to the job summary on every run. The job's token
can read the contents and write issues, nothing more, and the checkout keeps no
credentials, so the repository is never changed.
The composite action takes `cache: "false"`, which the canary passes. The store
cache is keyed on flake.lock: what it restored would be the old nixpkgs, taking
disk the guests need, and what it saved would replace the store of the jobs that
do use the lock.
`just lint` runs actionlint, with shellcheck over the scripts, both from the
nixpkgs flake.lock pins, so the lint job and `just check` check the workflows.
The steps were run as written on an x86_64 machine with KVM, against a fake gh:
GitHub Actions has not run the job yet. CONTRIBUTING.md, docs/dev/vm-tests.md
and DESIGN.md say what it does and why.
On NixOS the key bindings belong in the configuration, with the rest of
komorebi. services.komorebi.keybindings takes the format (skhd, whkd or sxhkd),
the bindings as text or as a file (exactly one of the two, asserted), the mode
(auto, engine or static; engine by default, as PlanMode::default() is),
chordTimeout (3000 ms), layout (us, the only one), strict and appAliases. skhd's
.load is refused by an assertion: the file it reads would not be in the store.
At build time the module runs komorebic hotkeys compile on the file in the
package komorebi-keybindings, whose share/kglobalaccel goes into the system
profile, where KWin finds the static shortcuts when the session starts. Its
diagnostics are in the build log and in diagnostics.txt, and strict passes
--strict, which fails the build on a warning or an error. execStart gains
--keybindings with the same store file, its format and mode, --chord-timeout and
an --app-alias per alias, so the daemon plans the file as the build did and runs
the bindings the build left to the engine. The unit already releases the keys
after the daemon stops.
The check keybindings-fixtures runs every file of the fixture corpus through
komorebic hotkeys compile --mode auto --dry-run, the command the module runs,
and diffs what it prints against nix/tests/keybindings.expected; it also checks
that docs/{skhdrc,whkdrc,sxhkdrc}.sample are the corpus's sample case.
nixos-module-eval gains the key binding scenarios: text, file, both, no format,
.load and a layout that is not us, and one with the typed config together with
key bindings, whose execStart has the checked file and then the keys. The corpus
gains the case vm, in the three formats: a binding a shortcut file can hold, and
one on the comma key, which X-KDE-Shortcuts cannot, so that the engine runs it
in auto mode. The VM suites vm-keys-skhd, vm-keys-whkd and vm-keys-sxhkd
configure the module with that case in their format and press both keys; they
share one script through the generator's script attribute.
For strict, nixos-module-eval has two scenarios with the same skhd text, which
has a line komorebic cannot read: strict = true and the default. Evaluation
never reads the key bindings, so the checks read the script of the build: with
strict it runs hotkeys compile --strict and exits 1 when that fails, without it
there is no --strict and the diagnostics are only printed to the build log. A
third check says the daemon gets the same command line either way. ARCHITECTURE
names them in the row for strict.
komorebic quickstart writes the sample skhdrc next to komorebi.json and
applications.json, from docs/skhdrc.sample, where the daemon and hotkeys compile
read it; the flake's source filter keeps that file for the build.
Docs: the user guide docs/usage/keybindings.md, the three sample files,
docs/example-configurations.md for KDE and NixOS, the options in
docs/installation.md, and the module's section of ARCHITECTURE. Whether the
engine or static shortcuts should be the default stays open in DESIGN: a static
shortcut took 233 ms to run its command at the median on KWin 6.8.1, the engine
3 ms, but only the static shortcut survives a dead daemon.
kglobalaccel keeps the actions of a client that died, and their keys: a daemon
that is killed leaves its keys swallowed and running nothing until they are
unregistered. And kglobalaccel runs inside KWin, so a KWin that restarts forgets
every key komorebi registered. Neither should leave a user without keys.
kwin::hotkeys::release unregisters every action of the component, whatever
registered it, and komorebic hotkeys release runs it, with or without a daemon.
The NixOS module's unit runs it after the daemon stops (ExecStopPost), however
it stops, and a start already takes over what is left. The KWin backend's
NameOwnerChanged watch now also follows org.kde.kglobalaccel: when it has an
owner again, kwin::hotkeys::rebind loads the key bindings into the new one,
trying for 15 seconds.
Loading moves from the daemon's main into kwin::hotkeys::load, which keeps its
settings (Keybindings: file, format, plan mode, engine options), so that reload
can read the file again: the message ReloadHotkeys, komorebic hotkeys reload. A
new engine replaces the running one without unregistering its keys, and takes
them over as a start does, so the keys both files have stay grabbed. The message
HotkeysState answers with the engine's mode, the combos it holds and whether a
chain is pending (null without an engine); komorebic hotkeys state prints it
with the actions kglobalaccel has for the component. komorebic now depends on
komorebi for the two calls to kglobalaccel, and on serde_json for the state.
Tests: the socket messages without key bindings, state and release without a
session bus, reload without a daemon, and a nixos-module-eval check of
ExecStopPost. The VM test vm-restart-survival runs the module's unit in a Plasma
session: a key works, hotkeys state shows it; with the daemon stopped by SIGSTOP
the key runs nothing until hotkeys release gives it back; after SIGKILL the
unit's journal shows the release and the restarted daemon has the key; after the
KWin process is killed, the daemon registers the key with the new KWin; and a
reload of a changed file swaps the key.
vm-keys-engine asks the engine and does not sleep. A key that is not grabbed yet
reaches the focused window, which showed as a binding that does not run, so the
suite presses one once komorebic hotkeys state answers, which it does when the
engine has made the calls of its last event: for a mode, for a chord chain
beginning and ending, and for the keys of the application that takes the focus.
It waits for the old daemon to exit before it starts the next (a daemon started
meanwhile failed to load its KWin script), and activates a window until KWin has
it (KWin lists a window before it can have the focus). The last check reloads
the key bindings with komorebic hotkeys reload while wev has the focus and every
binding is for the terminal, a start with no key to grab.
skhd and whkd can give one key a different action in each application, or none
(skhd's ~, whkd's Ignore), and skhd has a blacklist of applications in which no
key is taken. The engine decides from the focused application whether such a key
is active: inactive, it reaches the application, which is how a key passes
through. What it needs is to be told which application has the focus.
The bridge reports the desktop entry of every window with its class, and the
table now keeps it. Table::focused_application returns the executable, the app
id (or X11 class) and the desktop entry of the window KWin activated last, a
dialog included, or nothing once that window is gone. The KWin backend hands it
to kwin::hotkeys::focus after every event of the bridge; only a change reaches
the engine's thread, and an engine that starts begins with the focus as it was
last seen. The engine matches the names of the file against the three, ignoring
case.
The names in an skhdrc or a whkdrc are those of macOS and Windows applications,
so the daemon takes --app-alias NAME=ALIAS[,ALIAS]..., more than once, for the
engine's app_aliases.
Unit tests cover the focus of the table and the calls of a scoped key as the
focus moves, an alias included. The VM test vm-keys-engine grows a section with
wev and foot open and --app-alias terminal=foot: in wev, Alt+G (for the terminal
only) and Alt+N (which wev ignores) reach wev and run nothing; in foot both run
their bindings; back in wev, Alt+G reaches wev again.
An sxhkd chain (alt + w ; h) is realized by the engine: after the prefix only
the keys that can come next and Escape are grabbed, because KWin 6.8's own key
sequences never fire. What ends a chain that nobody finishes is the chord
timeout, and the engine has no clock: it is told the time with on_tick. Rather
than ticking on a timer forever, the engine now says when its pending chain
times out (Engine::deadline, in komorebi-hotkeys) and the transport sleeps until
then, calls on_tick, and grabs the keys of the mode again. With no chain pending
it does not wake up at all.
The daemon takes --chord-timeout in milliseconds, 3000 by default, the engine's
default and the module's chordTimeout to come.
A unit test follows the calls of a chain from its prefix to its deadline. The VM
test vm-keys-engine grows a section with an sxhkdrc passed as --keybindings and
a timeout of 1.5 s: Alt+W, H runs the binding and H does not reach wev; Alt+W,
Escape lets the next H reach wev; Alt+W and two seconds later L reaches wev and
runs nothing.
skhd's modes, and sxhkd's chains that stay open, are sets of keys that are
active together; a static shortcut cannot be in one. The engine already computes
the keys a mode wants. What the daemon adds is that a mode switch reaches
kglobalaccel as it should: the keys of the mode left are let go with
setInactive, so that they reach the focused window again, and those of the mode
entered are grabbed, bare keys included, before the next key arrives. It logs
the mode after each change, which is the one way to see from outside which mode
the engine is in.
A unit test follows the calls of entering a mode and leaving it with Escape. The
VM test vm-keys-engine grows a section with wev focused: in the default mode a
bare H reaches wev; Alt+R enters the mode resize and runs its command, after
which H runs its binding and does not reach wev; Escape goes back, and H reaches
wev again. That turns "a key the engine does not want reaches the application"
from a convention into a proved rule.
A static shortcut can only be one combo, pressed, the same in every application.
Modes, chord chains, release bindings and per-application bindings need komorebi
to hold the keys and decide what each press does: the engine of
komorebi-hotkeys, a state machine with no I/O. This commit runs it against
KWin's global shortcut daemon, which KWin 6.8 runs inside itself on the session
bus.
kwin::hotkeys owns the component komorebi in kglobalaccel, with one action per
combo, named after the combo (Alt+H). An activation of the engine is
setShortcutKeys(id, [[combo]], 6), with a doRegister the first time; a
deactivation is setInactive, after which the key reaches the focused window
again. The calls of one event are sent without waiting for each other's answers,
which Phase 0 measured at 60 calls in 2.4 ms. globalShortcutPressed and
globalShortcutReleased of /component/komorebi feed the engine;
globalShortcutRepeated is ignored, so a held key runs its binding once. A
komorebic command runs the komorebic next to the daemon with its words when they
need no shell, anything else runs through sh -c. The calls are computed by
Registry, which is pure and tested; the D-Bus part is proved by the VM test.
The engine hears the presses at the path /component/komorebi and does not ask
kglobalaccel for the object with getComponent. kglobalaccel makes the object
when the component gets its first action, so a start with no key to grab (every
binding is for an application other than the one with the focus) has none to ask
for: getComponent fails with NoSuchComponent, and an engine that asked would
never start. A signal is matched by the path it comes from, so the presses are
heard as soon as there is an object. PLATFORM.md says so.
kglobalaccel keeps the actions and the grabs of a client that was killed, so a
start is an idempotent reconcile: the actions of the component that the keymap
names are taken over and released unless the default mode wants them, the others
are unregistered. A stop releases and unregisters everything, from
KWinBackend::shutdown, which SIGINT, SIGTERM and the Stop message all go
through.
The daemon takes --keybindings FILE, --keybindings-format skhd|whkd|sxhkd (by
default from the file's name) and --keybindings-mode (the mode komorebic hotkeys
compile wrote the static shortcuts in, so that the daemon leaves those to KDE);
without --keybindings it reads the first of skhdrc, whkdrc and sxhkdrc in the
config directory (HOME_DIR, KOMOREBI_CONFIG_HOME). It logs one line about the
file and the diagnostics at debug level. An engine that cannot start is logged
and the window manager runs without keys; the fake backend runs none.
The VM test vm-keys-engine starts the daemon in a Plasma session with an skhdrc
in the config directory, presses its keys (a command, one through a shell,
komorebic retile reaching the daemon), kills the daemon and sees its keys stay
registered, starts it with another file and sees the old keys unregistered and
the new ones work, and stops it with komorebic stop, after which no key is
registered and none runs. The library gains spawn_komorebi,
kill_spawned_komorebi and shortcut_actions, and Checks.finish names the checks
that failed, since nix build shows only the last lines of a failed run. The
suite's node turns the module's unit off: the test runs daemons of its own.
komorebi users keep their bindings to komorebic in a file of skhd, whkd or
sxhkd. On Plasma under Wayland no client sees the keys of another, and the
program that runs a command on a key is KDE's global shortcut daemon, which runs
inside KWin. A binding that is one combo, pressed, the same in every
application, in a file without modes, can be a static shortcut: a .desktop file
that KWin reads by itself, that shows in System Settings and that works with no
komorebi process at all.
komorebic hotkeys compile reads a file of any of the three formats, plans it
with komorebi-hotkeys in the mode it is given (auto, engine or static; the
default is the crate's), prints the diagnostics of reading and planning, and
writes the static shortcuts to $XDG_DATA_HOME/kglobalaccel or --output,
replacing the files it wrote before and no other. --strict refuses a file with a
warning or an error before writing anything, --dry-run says what a write would
change, and --reload hands each new file to the running KWin. komorebic
export-kde-shortcuts keeps the spike's interface for an skhdrc, in the static
mode. Both are thin: the reading, the plan and the files are the crate's. The
bindings that need the engine are counted; the daemon does not run them yet.
docgen gives a subcommand of a subcommand a page of its own
(hotkeys-compile.md). KOMOREBI_CONFIG_HOME, or ~/.config/komorebi, is where
komorebic looks for a file it is not given.
komorebic check gains a section for the key bindings, between the configuration
and the desktop: the first key binding file of the config home, how many
bindings it has and where they go, the lines that cannot be read (a warning, and
the first five) and the bindings not realized as their own daemon would (a
note), and whether the generated files in the shortcut directory are the ones
hotkeys compile would write now (a warning with how many to add, to change and
to remove). --configuration-only keeps it, as it looks at files.
The VM test vm-keys-static boots a Plasma session with shortcut files that
hotkeys compile wrote into the system profile at build time, presses their keys
through QEMU's keyboard, and sees each command run, a % in one of them included;
then it writes a binding in the middle of the session with export-kde-shortcuts
--reload and presses it. The library gains Keys, which sends a combo as KDE
writes it through QEMU's sendkey.
What a static shortcut file cannot be (modes, chord chains, release bindings,
per-application bindings, a blacklist, a pause binding) komorebi realizes
itself, with keys it registers in kglobalacceld. The engine is the logic of
that, with no I/O and no clock: it takes the press and the release of an active
combo, a change of the focused window and the time, and returns effects: combos
to activate or deactivate, and commands to run (komorebic's to dispatch
in-process, the others through `sh -c`).
After every event it computes the set of combos it wants from its state (the
mode, the chord chain being typed, the focused application, whether it is
paused) and returns the difference with the active set, so that a key it does
not want reaches the application. That is how everything works, because of what
KWin 6.8.1 was measured to do: KDE's own multi-key sequences never fire, while a
single combo can be grabbed and given back (`setShortcutKeys`, `setInactive`) in
well under a millisecond each. A chain's first combo is an active key, and
pressing it leaves only the next combos and Escape active until one is pressed
or the chord timeout (3 s by default) passes. A scoped key is active only while
the focused application, matched without regard to case on its executable,
app_id or desktop entry and on the configured aliases, has an action for it.
Autorepeat arrives as a separate signal the engine has no input for, so a held
key runs its binding once.
The D-Bus side (registering the component, carrying out the effects, feeding the
signals in) belongs to the daemon and is not here.
The crate documentation now ends with what is emulated and what is not, across
the readers, the plan and the engine.
A binding can reach KDE in two ways. A `.desktop` file in a kglobalaccel
directory is a static shortcut that KDE runs by itself: it shows in System
Settings and survives a dead komorebi, but it is one combo that runs one
command. Modes, chord chains, release bindings, per-application bindings, a
blacklist and a pause binding need the engine, where komorebi registers the keys
and decides what each press does. `plan::plan` sorts a keymap into the two: a
binding is static when it is in the default mode, a single combo, unscoped and
pressed, in a file with no modes, blacklist or pause binding. Notes say why each
other binding goes through the engine.
The static shortcut was meant to be the default unless it proved slow, and it
did: on KWin 6.8.1 a static shortcut ran its command 233 ms after the key at the
median, while the engine heard of it after 3 ms. `PlanMode::Engine` is therefore
the default, and `Auto` and `Static` (no engine; what needs it is left out with
a warning) stay selectable.
`kde` is the skhdrc exporter of the first KDE prototype, moved: the same file
names, the same `Exec` quoting for the desktop entry specification (`%%`
included), the same `X-KDE-GlobalAccel-CommandShortcut` and `X-KDE-Shortcuts`
keys, and `write` and `diff`, which replace the generated files and leave every
other file alone. For the sample configuration the files are byte for byte the
prototype's; its tests come along, and the corpus test checks that the sample
plans into the same 50 files from each format.
The third format is sxhkd's, the hotkey daemon users of tiling window managers
on X11 bind keys with. `sxhkd::parse` reads a hotkey line and the indented
command below it, with comments and continued lines, X keysyms (XF86 media keys
included) and the modifiers sxhkd shares with KDE.
Braces are expanded while reading, in the hotkey and the command together:
`{a,b}`, ranges such as `1-9`, `_` for nothing and `\{` for a literal brace,
with every combination of several pairs, the last changing fastest. A chord
chain (`super + w ; h`) is one binding with two combos, and a chain that stays
open after its last chord (`super + r : {h,l}`) is a mode named after its
prefix, entered by the prefix and left with Escape. `@` makes a release binding.
The diagnostics say what differs from sxhkd: a wrong key does not end a chain
(only Escape and the chord timeout do), a release binding fires on the first
key-up of any key of its combo, `~` does not pass the key on, and the modifiers
KDE has no equivalent for, mouse buttons and keypad keys are left out.
`parse` now picks the reader by format, and the corpus test reads every fixture
with it: the files of each case, in all three formats, read into the same
keymap.
komorebi for Windows' users bind komorebic in a whkdrc. `whkd::parse` reads it
into the same model as an skhdrc: `keys : command` bindings with the Windows
virtual key names whkd takes, per-application lists with `Ignore` and `Default`,
`.pause` and `.pause_hook`. A `#` starts a comment wherever it is, as in whkd.
whkd requires its sections in a fixed order; the reader takes them in any.
`.shell` is noted, since commands run through `sh -c`, side-specific modifiers
are approximated, and keys KDE has no key for (the keypad's) are left out with a
warning.
whkd's own parser, `whkd-parser`, is not used to read: it requires `.shell` to
be pwsh, powershell or cmd and panics on anything else, and it matches Windows
process names. It is under the same license as komorebi, so it is a
dev-dependency at v0.2.10, and a test reads every whkdrc of the corpus and the
example of whkd's README with both parsers and requires the same bindings.
deny.toml allows its git source.
The corpus test now also reads the whkdrc fixtures, and checks that the files of
a case read into the same keymap, apart from where each binding was written.
LGUG2Z