Files
komorebi/justfile
T
LGUG2Z 15ec3c1274 feat(kwin): read the desktop through a script in KWin
KWin has no protocol that lets another process read or set the geometry of a
window, but its scripting API has both, and a signal for every change the window
manager follows. So the KWin backend is in two parts: bridge.js, a script the
daemon loads into KWin, which reports what KWin sees and holds no window manager
logic, and a D-Bus service in the daemon, org.komorebi.Bridge, which the script
calls with every event as a JSON string.

Every decision about what an event means is made by the table in kwin::state,
which is pure and is unit-tested with the JSON the script sends: which windows
may be managed, the ids komorebi gives KWin's windows, and the Show, Destroy,
FocusChange, Minimize and Restore events of the window manager. Events reach the
window manager in the order KWin raised them: the Event interface handles its
calls inline (zbus reordered them otherwise), and one channel and one thread,
window_manager_event_listener and listen_for_events, carry them on.

Commands go to the script as the answer to a Poll call that the script always
has open and the daemon holds until it has something to send: in the spikes this
was as fast as any other channel, and it makes one call every 10 seconds when
nothing happens. Here the only command is the cursor query. Every command of the
Backend trait is refused with "the KWin backend only reads the desktop", so the
daemon follows KWin and moves nothing.

The bridge is JavaScript that KWin runs as it is, and it gets types and tests
without a JavaScript build chain. tsc checks it as strict TypeScript through
JSDoc types of every message, against kwin-api.d.ts, a declaration of the part
of KWin's scripting API it uses, in which every property is read-only and
callDBus takes one string. bridge.test.js runs it under node --test against a
fake KWin in a node:vm context. The messages of a session are JSON fixtures that
both sides' tests read: the bridge's tests check that it sends those events, and
the table's and the backend's tests read the same events and commands, so a
message cannot change on one side alone. just check-js and the flake's
komorebi-bridge-js check run both, with nodejs and typescript from nixpkgs;
there is no package.json.

The daemon now connects to KWin by default, and --fake-backend is hidden. The VM
suite vm-kwin-events starts it against a headless KWin and checks, from its
debug log, that the script loads and reports what was open, that KWin's signals
arrive as events and in order, and that stopping the daemon unloads the script.
docs/dev/PLATFORM.md starts with what komorebi needs from Plasma.

zbus 5's zvariant, zbus_names and zvariant_derive are flagged unmaintained,
since their code moved into zbus 6; deny.toml ignores the three advisories.
2026-10-27 14:46:35 -07:00

48 lines
1.8 KiB
Makefile

export RUST_BACKTRACE := "full"
# format the Rust sources (needs a nightly rustfmt: rustfmt.toml uses unstable options)
fmt:
cargo fmt
# everything a change has to pass before it is pushed
check: lint check-js
cargo fmt --check
cargo clippy --workspace --all-targets --locked -- -D warnings
cargo test --workspace --locked
RUSTDOCFLAGS="-D warnings" cargo doc --workspace --no-deps --locked
# the KWin bridge, which is JavaScript: its types, checked by tsc from its JSDoc comments, and its
# tests, which node runs against a fake KWin (no package.json, no build step)
check-js:
cd komorebi/src/kwin && tsc -p tsconfig.json
node --test komorebi/src/kwin/bridge.test.js
# the macros the codebase has agreed not to use
lint:
test -z "$(rg 'eyre!' --type rust .)" || (echo "eyre! macro not allowed"; false)
test -z "$(rg 'dbg!' --type rust .)" || (echo "dbg! macro not allowed"; false)
test -z "$(rg 'println!' --type rust ./komorebi/src)" || (echo "println! macro not allowed"; false)
# one VM test, on this machine: `just vm kwin`. Linux boots the guest under KVM through the
# flake check; a Mac builds the guest on a builder and runs the driver (see docs/dev/vm-tests.md)
vm name:
#!/usr/bin/env bash
set -euo pipefail
if [ "$(uname)" = Darwin ]; then
scripts/vm-mac {{ name }}
else
nix build -L .#checks.{{ arch() }}-linux.vm-{{ name }}
fi
# every VM test, in the order of the flake
vm-all:
#!/usr/bin/env bash
set -euo pipefail
system=$(nix eval --raw --impure --expr builtins.currentSystem)
for name in $(nix eval --json ".#legacyPackages.$system.vm" --apply builtins.attrNames | jq -r '.[]'); do
just vm "$name"
done
run target *args:
cargo run --bin {{ target }} --locked -- {{ args }}