chore(repo): combine the review fixes, new tests and docs (candidate 5)

Candidate 5: wip-cand4 plus kfw's review fixes (wip-u-fix5: revert of the subscriber write timeout and the hwnd writer thread, BAR_RUNNING tied to the message, dead-window HIDDEN_HWNDS cleanup, core in default-members), kfm's macOS registry fixes (wip-u-kfm3), kfde's hook rename and per-pass title-bar snapshot (wip-u-core4), the komorebi-core characterization tests (wip-u-coretests) and the docs (wip-u-docs). Conflicts, if any, are resolved here.
This commit is contained in:
LGUG2Z committed 2026-11-05 15:03:26 -08:00
37 files changed
+5739 -67

No files matched your search

+134
View File
@@ -0,0 +1,134 @@
# komorebi after the consolidation: a map of the repository
Status (wip-cand4): current map. Windows, KDE Plasma and macOS build from one workspace and one
`komorebi`, one `komorebic`, one `komorebi-client` and one `komorebi-bar` package, the platform chosen by
`cfg(target_os)`. The cutover (shim packages, one flake, final directories, one version number) is not done;
section 6 lists what is still old. macOS has only been type-checked on Linux and compiled/unit-tested on a
Mac Mini; no macOS daemon behaviour has been observed.
How to build and test: [build-and-test.md](build-and-test.md). Why things are shaped as they are:
[seam.md](seam.md) (the `Backend` trait), [core-model.md](core-model.md) (the shared model),
[settings.md](settings.md), [unified-binaries.md](unified-binaries.md), [bar-unification.md](bar-unification.md),
[backend-switch.md](backend-switch.md). What a person with a Mac has to check: [macos-handcheck.md](macos-handcheck.md).
## 1. Three platform trees, one workspace
The root `Cargo.toml` is the only workspace. It has members in three places:
| Tree | What is in it | Platform |
|---|---|---|
| the repository root (`komorebi/`, `komorebi-bar/`, `komorebic/`, ...) | the Windows daemon library, the unified packages, the Windows-only tools (`komorebi-gui`, `komorebi-shortcuts`, `komorebic-no-console`), `komorebi-layouts`, `komorebi-scrolling`, `komorebi-themes`, `e2e/`, `wix/` | Windows (the original) |
| `komorebi-for-kde/` | the KDE daemon library `komorebi-linux` (`komorebi/`), `komorebi-hotkeys/`, the `version-linux` crate, the NixOS module, the VM test suites (`nix/tests/vm`), KDE docs (`docs/dev`) | Linux, KDE Plasma on KWin (Wayland) |
| `komorebi-for-mac/` | the macOS daemon library `komorebi-macos` (`komorebi/`), the `version-macos` crate, the nix darwin module, macOS docs | macOS |
`komorebi-for-kde/` and `komorebi-for-mac/` still have their own flakes, `justfile`s and docs; the root flake
imports them as `kfde-*` and `kfm-*` (section 5). They have no `Cargo.toml` workspace of their own any more:
`cargo` run inside them uses the root one.
## 2. The packages (what a user runs)
| Package (binary) | Directory | How the platform is chosen |
|---|---|---|
| `komorebi` (`komorebi`) | `komorebi-daemon/` | `src/main.rs` is a `cfg_select!` that calls `daemon::run()` of the library of the target OS; the libraries are target-gated dependencies in `Cargo.toml` |
| `komorebic` (`komorebic`) | `komorebic/` | `src/windows.rs`, `src/linux/`, `src/macos/`, one `cfg` per target; the arguments are in `crates/komorebic-core` |
| `komorebi-client` (library) | `komorebi-client/` | `src/windows.rs`, `src/linux.rs`, `src/macos.rs` re-export the daemon library of the target OS behind one `Connection` |
| `komorebi-bar` (`komorebi-bar`) | `komorebi-bar/` | `src/windows/` and `src/macos/` modules; shared code in `crates/komorebi-bar-core`. **KDE has no bar** |
The daemon libraries are `komorebi-windows` (`komorebi/`), `komorebi-linux` (`komorebi-for-kde/komorebi/`) and
`komorebi-macos` (`komorebi-for-mac/komorebi/`). They have no binary: each has a `daemon.rs` with
`run()`, the old `main`. `-p komorebi-windows` etc. still build, as libraries.
Shim packages exist until the cutover (each is a `#[path]` include of the unified module, same binary
name): `komorebic-linux`, `komorebic-macos`, `komorebi-client-linux`, `komorebi-client-macos`,
`komorebi-bar-macos`. Never build `komorebic` together with `komorebic-linux` or `komorebic-macos`: the
binary name is the same.
## 3. The shared crates (`crates/`)
| Crate | What it holds | Used by |
|---|---|---|
| `komorebi-protocol` | the wire types: `SocketMessage` and payloads; per-platform goldens in `tests/golden/` | daemons, client, komorebic |
| `komorebi-config` | the `komorebi.json` types (`StaticConfig` and what it is made of) and schema generation | daemons, komorebic |
| `komorebi-collections` | `Ring`, `LockableSequence` | the three daemons |
| `komorebi-transport` | the command transport: pause filter, listener, subscriber registry | the three daemons |
| `komorebi-backend` | the `Backend` trait (what a daemon asks of its platform), `WindowId`, plain-data infos, `FakeBackend`, the contract tests every backend must pass | daemons; Windows goes through it for the clusters in backend-switch.md |
| `komorebi-core` | the shared model, generic over the platform window: `Container<W>`, `Monitor<P>`, `Workspace<P>` with `update_shared`, `WorkspaceGlobals`. `WindowManager<P>` is not shared yet | the three daemons |
| `komorebi-settings` | the settings a daemon reads at run time as one immutable snapshot, instead of process-wide statics | the three daemons |
| `komorebi-bar-core` | the bar's configuration, widgets and platform seam | `komorebi-bar` |
| `komorebic-core` | the command line definitions of every platform (`cli`, `docgen`, `platform::{windows,macos,...}`) | `komorebic` |
Also shared by path from the Windows tree: `komorebi-layouts`, `komorebi-scrolling`, `komorebi-themes`.
## 4. Where the platforms differ on purpose
These are intentional, not leftovers; before "unifying" one, read the document named.
- Window system and hiding: Win32 (cloaking, own border windows, DWM animations), KWin (a JavaScript
bridge loaded into KWin, desktops as workspaces, parking desktop), AppKit/Accessibility (own `NSWindow`
borders). `komorebi-backend` is the seam; the rules and what each platform keeps are in [seam.md](seam.md).
- The model: `Container`, `Monitor`, `Workspace` are shared; `WindowManager`, the command router and event
processing are still per platform, with the blockers listed in [core-model.md](core-model.md) sections 17
and 18.
- Settings: [settings.md](settings.md) says which process-wide statics became snapshot fields and which
remain.
- Packaging: [unified-binaries.md](unified-binaries.md): library per OS, one binary; `cfg(target_os)`, not
features.
- The bar: [bar-unification.md](bar-unification.md): one package, one module per OS; rendering code differs
(frame margins, `network.rs`, window seams) and B4 (merging it) was not done.
- Command line: each platform keeps its help text and its own commands (Windows 34, KDE 2, macOS 1 are
platform-only; most are common). `komorebic` pages in `docs/cli` of each tree are the oracle.
- macOS: everything except compile and unit tests is unverified; [macos-handcheck.md](macos-handcheck.md).
- KDE: no bar; hotkeys through `komorebi-hotkeys` and exported KDE shortcuts; the module is NixOS.
- Windows: the e2e under QEMU (`e2e/`), `komorebi-gui`, `komorebi-shortcuts`, `komorebic-no-console`, wix.
## 5. The oracles (what stops a refactor from changing behaviour silently)
| Oracle | Where | Detects | Run by |
|---|---|---|---|
| Wire goldens | `crates/komorebi-protocol/tests/golden*` | a change of what each daemon sends or accepts on the socket | `cargo test -p komorebi-protocol` |
| Config schemas | `schema.json`, `schema.asc.json` of the three trees; `crates/komorebi-config/tests/schemas.rs`; KDE `komorebi/tests/schemas.rs` | a changed key of `komorebi.json` | `cargo test -p komorebi-config` (KDE: `-p komorebi-linux --test schemas -- --test-threads=1`) |
| Bar schema views | `schema.bar.json` (Windows), `komorebi-for-mac/schema.bar.json`; `crates/komorebi-bar-core/tests/schema_oracle.rs` pins size and hash; `komorebi-bar --schema` prints the view of the target OS | a changed bar configuration | `cargo test -p komorebi-bar-core`; Windows e2e scenario `bar` compares `--schema` byte for byte |
| CLI docs | `docs/cli` of each tree; `crates/komorebic-core/tests/docs_cli.rs` and `platforms.rs` | a changed subcommand or help text | `cargo test -p komorebic-core`; `komorebic docgen --output DIR` regenerates |
| Schema docs completeness | `check_schema_docs.py` (root) | schema entries with no description | by hand |
| Drift of derivations | `nix eval .#packages.x86_64-linux.default.drvPath` and the check derivations | an unintended change of what nix builds | by hand (see build-and-test.md) |
| Backend contract | `komorebi-backend/src/contract.rs` | a backend that breaks a rule of the trait | `cargo test -p komorebi-backend` and each daemon's tests |
| Runtime | Windows e2e (QEMU), KDE VM suites | real behaviour | tier 3 below |
Windows `docs/cli` was found stale against the binary in the step-4 measurement (see the progress notes,
decision D20); regenerate before treating it as an oracle.
## 6. What is still the old layout (cutover list)
Shim packages and their directories under `komorebi-for-kde/` and `komorebi-for-mac/`; `version-linux` and
`version-macos`; three flakes (the root one imports the other two as `kfde-*` and `kfm-*`); three `deny.toml`;
three version numbers (Windows libraries and packages 0.1.42, KDE 0.1.0, macOS library 0.1.1 and its `version` crate 0.1.0). Some docs still describe the old layout; those that were
found wrong have been corrected, [COMPARE.md](../../komorebi-for-kde/docs/dev/COMPARE.md) is marked stale.
`komorebi-for-kde/justfile` still has recipes written for a KDE-only workspace (`just check` runs
`cargo test --workspace`, which on Linux would build the Windows crates): use the commands in
build-and-test.md.
## 7. Feedback loops, from cheap to expensive
| Tier | What | Time | How |
|---|---|---|---|
| 0 | docs and links | none | nothing builds; a docs-only commit leaves every nix check a cache hit, except text under `komorebi-for-kde/` and `komorebi-for-mac/`, which are inputs of their derivations |
| 1 | native Linux: `cargo check/test` of the shared crates and the KDE daemon | seconds to minutes | build-and-test.md, section 2 |
| 2 | cross-compile and nix checks: Windows clippy, macOS type-check with a fake C compiler, KDE non-VM checks, schema and CLI oracles | minutes | build-and-test.md, sections 1 and 3 |
| 3 | e2e: Windows QEMU scenarios, KDE VM suites (`fast`, `slow`) | tens of minutes, batched | build-and-test.md, sections 4 and 5 |
| 4 | a real Mac | by hand | macos-handcheck.md |
### The helper tools (outside the repository)
The agents that did the consolidation used scripts that live outside the repository, in
`/home/jado/komomono-work/tools` on the build host. They are not part of the repository. Proposal, not
done: commit the ones that encode project knowledge under `scripts/dev/`, and leave the host-specific ones out.
| Tool | What it does | Worth committing? |
|---|---|---|
| `fast-check` (+ its README) | runs only the checks that the touched paths need (tier 1 and 2), with persistent target dirs | yes: it is the quickest way to get the right gate for a change; needs its scratch paths made configurable (`FAST_CHECK_SCRATCH`, already an env var) |
| `mac-check.sh` | macOS type-check through a fake C compiler | yes, merged into `fast-check` (it has hard-coded paths to a workspace) |
| `kde-closure-check` | fails when `komorebi-for-kde/nix/root-crates.json` and the KDE cargo closure differ | yes: it protects the KDE source filter; run after any dependency change in the KDE tree or the crates it uses |
| `lite-env` | env vars for builds without debug info | optional (one `.env` file) |
| `gate-lock` | host-wide FIFO lock so heavy gates and timing-sensitive e2e do not overlap | host policy; commit only if more than one person shares a build host |
| `e2e-needed` | says whether a diff touches anything the Windows e2e binaries are built from (decides whether the e2e gate is owed) | yes, next to `fast-check` |
| `host-sample`, `jitter-probe`, `trim-target`, `mini` | measurement and housekeeping for this host (`mini` is an SSH wrapper for one Mac Mini) | no |
+2
View File
@@ -1,5 +1,7 @@
# Windows: which call sites go through `backend()`
> **Status (wip-cand4):** in progress. The clusters in "Switched" are landed (each BEHAVIOUR, e2e-gated); the rest is deliberately left on `WindowsApi`, see the two "not switched" tables; nothing here is planned further until `WindowManager<P>` ([core-model.md](core-model.md) section 18).
Step 8 of the unified-binaries plan. `komorebi::windows_backend::backend()` returns the shared
`komorebi_backend::Backend` (a stateless `WindowsBackend` over `WindowsApi` and `Window`). The daemon
is switched one cluster at a time; each switch is its own revision marked BEHAVIOUR.
+2
View File
@@ -1,5 +1,7 @@
# Windows e2e for komorebi-bar
> **Status (wip-cand4):** current; the `bar` scenario exists and is the runtime gate for `komorebi-bar` and `komorebi-bar-core` on Windows.
The `bar` scenario (`e2e/platforms/qemu_windows/extras/bar.py`, registered as `EXTRAS["bar"]` in
`run.py`) is the runtime gate for changes to `komorebi-bar` and `komorebi-bar-core`: the unit tests
and the schema oracle cannot run the bar. Run it on the golden Windows guest:
+2
View File
@@ -1,5 +1,7 @@
# One `komorebi-bar` for Windows and macOS
> **Status (wip-cand4):** B0-B3 done (one `komorebi-bar` package, a module per platform, schema views); B4 (merging the rendering code) not done and cannot be shown mechanical without a screen; macOS bar never rendered by these changes.
Status at the revision that adds this file. Everything below was measured on this tree with
`diff` (counts are lines that differ, `<`/`>` lines of `diff`, hunks in parentheses). Nothing
here was rendered: the bars cannot run on Linux. Gates that did run are named; the ones that
+231
View File
@@ -0,0 +1,231 @@
# Build and test, per platform
Status (wip-cand4): current. Every command below was read from `flake.nix`, the justfiles, the Cargo
manifests or the e2e README; the ones marked "ran" were run on the Linux host at this revision (cheap checks
only: `cargo metadata --no-deps`, `cargo check -p komorebi-linux -p komorebi -p komorebic` in
`komorebi-for-kde/`). Everything else, including every nix build, e2e and VM run, is documented but was not
run for this page. macOS cannot be built or run on Linux; Linux can only type-check it.
The map of the repository is [ARCHITECTURE-UNIFIED.md](ARCHITECTURE-UNIFIED.md). Package names in this
repository (`cargo metadata --no-deps`, ran): `komorebi` (the daemon, `komorebi-daemon/`), `komorebic`,
`komorebi-client`, `komorebi-bar`, the libraries `komorebi-windows`, `komorebi-linux`, `komorebi-macos`, the
shims `komorebic-linux`, `komorebic-macos`, `komorebi-client-linux`, `komorebi-client-macos`,
`komorebi-bar-macos`, and `komorebi-backend`, `-bar-core`, `komorebic-core`, `-collections`, `-config`,
`-core`, `-protocol`, `-settings`, `-transport`.
## 0. General rules
- Platform is chosen by `cfg(target_os)`: `cargo build -p komorebi -p komorebic -p komorebi-bar` builds the
program of the OS you are on. The Windows daemon is only buildable for the Windows target (cross build in
section 1); on Linux `-p komorebi` is the KDE daemon, on macOS the macOS one.
- Never put `komorebic` and `komorebic-linux`/`komorebic-macos` in one command (same binary name). The shims
stay until the cutover.
- Without a `.git` (a jj workspace) the build script of the macOS and KDE trees needs `COMMIT_HASH=dev`; the
`nix flake check --no-build` command fails with `attribute 'dirtyRev' missing` for the same reason. Do not run
`nix flake check` on the root flake at all (it builds the VM suites); name the check.
- Text edits under `komorebi-for-kde/` and `komorebi-for-mac/` change those trees' nix derivations (they are
inputs); a docs-only edit elsewhere does not, because the commit stamp is a constant in the checks
(`COMMIT_HASH=nix-check`) and only `packages.default` carries the real commit.
- Heavy builds and e2e should not run at the same time as a timing-sensitive e2e: the Windows `commands`
scenario is the most sensitive (section 6).
## 1. Windows (cross build from Linux via nix)
Binaries (the flake cross-compiles to `x86_64-pc-windows-msvc` with an xwin SDK):
```sh
nix build .#komorebi .#komorebic .#komorebi-bar # result*/bin/*.exe; also komorebic-no-console, komorebi-gui, komorebi-shortcuts, komorebi-testwin
nix build .#default # komorebi-full: everything, with the real commit stamp
```
Checks (crane; the clippy one is the pre-landing gate, about 3.5 min warm deps; the dependency derivation is
shared by all of them):
```sh
nix build -L --no-link .#checks.x86_64-linux.komorebi-workspace-clippy
nix build -L --no-link .#checks.x86_64-linux.komorebi-workspace-nextest
nix build -L --no-link .#checks.x86_64-linux.komorebi-workspace-fmt .#checks.x86_64-linux.komorebi-workspace-toml-fmt .#checks.x86_64-linux.komorebi-workspace-deny
nix build -L --no-link .#checks.x86_64-linux.e2e-tests # the Python of the e2e (pytest), no guest needed
```
Quick loop without nix (what `fast-check` runs; clippy of the Windows tree from the nix dev shell):
```sh
nix develop --command cargo clippy --workspace --locked --all-targets -- -D warnings
```
On a Windows machine itself: `just build` / `just install` (the root `justfile`, PowerShell), or
`cargo build -p komorebi -p komorebic -p komorebi-bar --locked`.
Platform-neutral crates test natively on Linux, with no cross toolchain: `cargo test -p komorebi-protocol
-p komorebi-config -p komorebi-collections -p komorebi-core -p komorebi-backend -p komorebi-settings
-p komorebi-transport -p komorebic-core -p komorebi-bar-core -p komorebi-layouts -p komorebi-scrolling`.
## 2. KDE Plasma (native Linux)
From `komorebi-for-kde/` (cargo finds the root workspace; a C compiler is needed, `nix shell nixpkgs#gcc -c`
or the dev shell):
```sh
cargo check -p komorebi-linux -p komorebi -p komorebic # ran, 27 s with a warm target
cargo test -p komorebi-linux --lib # the daemon's unit tests (294 passed at the step-8 measurement)
cargo test -p komorebi-linux --test schemas -- --test-threads=1 # the schema oracle; shares a pid-only socket path, keep one thread
cargo test -p komorebi -p komorebic -p komorebi-client -p komorebi-hotkeys # daemon-binary, CLI and client tests (tests/linux_*.rs)
```
A single test file: `cargo test -p komorebi-linux --test NAME` (the files are in `komorebi-for-kde/komorebi/tests`).
The `-p komorebi --lib` that older notes use is the thin binary package now: the unit tests are in
`komorebi-linux`.
Run `tools/kde-closure-check` after any dependency change in the KDE tree or the crates it uses: the KDE
flake takes only the crates listed in `komorebi-for-kde/nix/root-crates.json`.
KDE nix checks (no VM): from the root flake they are prefixed `kfde-`, and the VM checks are left out:
```sh
nix build -L --no-link .#checks.x86_64-linux.kfde-komorebi-workspace-clippy
nix build -L --no-link .#checks.x86_64-linux.kfde-komorebi-workspace-nextest
# also kfde-komorebi-workspace-{fmt,toml-fmt,deny,doc}, kfde-nix-options-validation, kfde-nixos-module-eval,
# kfde-keybindings-fixtures, kfde-schema-fresh
nix build -L .#packages.x86_64-linux.kfde-komorebi .#packages.x86_64-linux.kfde-komorebic
```
Inside `komorebi-for-kde/` the same checks have no prefix (`nix build .#checks.x86_64-linux.NAME`).
`komorebi-for-kde/justfile` (`just check`, `just docgen`, `just jsonschema`) still assumes a KDE-only
workspace: `just check` runs `cargo test --workspace`, which would build the Windows crates on Linux. Use the
commands above; `just vm NAME` and `just nixgen` are fine.
### KDE VM suites
Each suite under `komorebi-for-kde/nix/tests/vm/suites/NAME` boots NixOS with Plasma and KWin; they need KVM
(nested is enough under WSL2; `nix run .#wsl2-probe` from `komorebi-for-kde/` measures it).
```sh
# from komorebi-for-kde/
just vm NAME # = nix build -L .#checks.x86_64-linux.vm-NAME
just vm-all # every suite in the order of the flake
# from the repository root (the VM checks are left out of the root `checks`, the suites are here)
nix build -L .#legacyPackages.x86_64-linux.kfde-vm.NAME
# from komorebi-for-kde/: the names of each tier as JSON (ran; CI reads it)
nix eval --json .#legacyPackages.x86_64-linux.vmTiers
```
Tiers (the `tier` in each suite's `default.nix`; CI runs `fast` on every pull request, `slow` on master):
- fast: `check hotplug commands kwin-restart kwin-events scrolling workspace-rules core-e2e kwin-contract kwin
workspace-switch stacks module placement user-maximize run-kde`
- slow: `client-geometry restart-survival keys-whkd core-lock keys-sxhkd render-smoke drag-resize rdp features
focus-follows-mouse latency keys-engine live-resize lock-sleep look keys-skhd keys-static wallpaper`
- `vm-lib` (a check, not a suite) runs the unit tests of the VM library; no VM boots.
To run only some steps of a suite: `E2E_ONLY=stacks,monocle nix build --impure .#checks.x86_64-linux.vm-core-e2e -L`
(from `komorebi-for-kde/`; a substring of the printed `module.function`; `KFDE_ONLY` is the old name).
To record a run: `KOMOREBI_RECORDER=$(nix build ~/komorebi-recorder#komorebi-recorder --no-link --print-out-paths)
nix build --impure .#checks.x86_64-linux.vm-core-lock -L` (the recorder's repository is private; `core-e2e` and
`core-lock` keep `recording-NAME.tar.gz`). Details, the library and how to add a suite:
[komorebi-for-kde/docs/dev/vm-tests.md](../../komorebi-for-kde/docs/dev/vm-tests.md). The suites use a daemon
built once with the constant stamp, so a new commit does not rebuild it.
## 3. macOS
On a Mac (aarch64-darwin), from the repository root (a `.git` checkout, or `COMMIT_HASH=dev` in the
environment). These are the commands for the Mac Mini; none has been run on a Mac against wip-cand4 unless
[macos-handcheck.md](macos-handcheck.md) says so:
```sh
cargo build --locked -p komorebi -p komorebic -p komorebi-bar
cargo clippy --locked -p komorebi -p komorebi-macos -p komorebic -p komorebi-client -p komorebi-bar -p komorebi-bar-core --all-targets -- -D warnings
cargo test --locked -p komorebi-macos -p komorebic -p komorebi-client -p komorebi-bar-core -p komorebi-bar
cargo build --locked --features deadlock_detection -p komorebi # the feature is forwarded
target/debug/komorebi --version # komorebi 0.1.0 (the macOS version crate)
target/debug/komorebic --help; target/debug/komorebic docgen --output /tmp/docs-mac
target/debug/komorebi-bar --schema | cmp - komorebi-for-mac/schema.bar.json
```
Never `-p komorebic-macos` together with `-p komorebic` (the shims `komorebic-macos`, `komorebi-client-macos`
and `komorebi-bar-macos` still build alone). Before any change that touches macOS code, run the unit tests on
the Mac first: nothing else can run them. After that walk [macos-handcheck.md](macos-handcheck.md).
On Linux, macOS can only be type-checked, through a fake C compiler and the target
`aarch64-apple-darwin` (`tools/fast-check` does it; it cannot link or run):
```sh
COMMIT_HASH=dev cargo check --target aarch64-apple-darwin --workspace --all-targets # with CC_aarch64_apple_darwin set to a fake cc
```
Nix, on a Mac: the checks of `komorebi-for-mac/flake.nix` (`komorebi-workspace-{clippy,fmt,toml-fmt,deny,nextest}`,
`nix-options-validation`, `darwin-module-validation`). From Linux they can be evaluated only
(`nix flake show --all-systems`, `nix eval`), which proves nothing builds. Through the root flake they are
`kfm-*`.
## 4. Windows e2e (QEMU guest)
Full text: `e2e/platforms/qemu_windows/README.md` (building the golden image, every variable). Short form:
```sh
E2E_GOLDEN=golden nix run .#e2e-windows -- OUT SCENARIO... # e.g. OUT tiling focus commands
E2E_GOLDEN=golden KOMOREBI_E2E_SCALE=1.5 nix run .#e2e-windows -- OUT bar # the komorebi-bar scenario
```
The app uses this checkout's binaries, built with the constant stamp `e2e` (so a docs-only commit reuses them);
the commit under test is `KOMOREBI_E2E_COMMIT` (default: the flake revision). To test another commit:
`build-ref.sh REF bins` then `KOMOREBI_E2E_BINS=bins ...` (`bins` needs `komorebi-bar.exe` for `bar`).
| Variable | Effect |
|---|---|
| `E2E_ONLY=word,word` | run only the steps whose printed name contains a word (a rerun of one step) |
| `KOMOREBI_E2E_LOG_LEVEL=trace` | the daemon's log level (`debug`, `trace`) |
| `KOMOREBI_E2E_RECORDER=DIR` | record with komorebi-recorder (a folder with `komorebi-recorder.exe`); comes back as `recording.zip` |
| `KOMOREBI_E2E_KEEP_GUEST=1` | keep the guest's run directory (overlay, TPM state) instead of deleting it |
| `KOMOREBI_E2E_SCALE=1.5` | every wait is 1.5 times as long, for a busy host |
| `KOMOREBI_E2E_STATE=DIR` | restore guests from a saved state (3 s instead of 50-90 s start) |
| `KOMOREBI_E2E_CAPTURE=DIR` | save raw `komorebic state` fixtures |
| `SWEEP_TWO_DISPLAYS=1` | `commands` adds a second display |
Keep output and run directories on a short path (unix socket paths are limited to about 108 bytes). Each
scenario gets its own guest (about 4 vCPU and 6 GB). Results are in `OUT/<scenario>/result.json`; trust it over
the printed line. `docs/dev/bar-e2e.md` describes the `bar` scenario.
A change to the Windows daemon or bar needs these before it is considered landed (commit types BEHAVIOUR):
`commands`, plus the scenario of the cluster named in the revision body (see backend-switch.md for the table).
## 5. What runs where (summary)
| Change touches | Run |
|---|---|
| `crates/*` (not bar/komorebic) | section 1 native crate tests, then Windows clippy (section 1), KDE (section 2) and macOS type-check (section 3) |
| `komorebi/` (Windows daemon) | Windows clippy and nextest, then e2e (section 4) |
| `komorebi-for-kde/` | section 2 cargo, then KDE checks, VM `fast` tier |
| `komorebi-for-mac/` | macOS type-check on Linux; build and tests on a Mac |
| `komorebi-bar/`, `komorebi-bar-core` | Windows clippy, `cargo test -p komorebi-bar-core`, macOS type-check, e2e `bar` |
| `komorebic*`, `komorebic-core` | `cargo test -p komorebic-core` (CLI doc oracle), all three platforms' checks |
| `*.nix`, `flake.lock` | evaluation only (`nix eval ...drvPath`) before a build |
| docs only | nothing, unless under a platform tree (see section 0) |
## 6. Known flakes
Policy: on any e2e or VM failure, check this list by check name and by log signature first; do not soak to
re-prove a known flake. Write rates as `failures/runs` with the commit and host load. A known flake needs
`baseline-seen` evidence (it occurred before the consolidation) or at least 3 occurrences with the same
signature. A name-only match gets one rerun on a calm host at `trace` with logs kept; no match gets one calm
rerun, and a second failure is a regression candidate to bisect by revision. A soak is only for a candidate
that failed twice or a flake whose rate looks more than 2x higher with at least 3 failures. Passing under
load stays a pass; failing under high load is not evidence of a regression. A full `commands` sweep takes 4
to 6 minutes, so the `E2E_ONLY` runs come first.
| Check | Platform | What is seen | Rate (from a measured set) |
|---|---|---|---|
| `commands`, daemon stops answering `komorebic state` | Windows | the daemon logs nothing from any thread for 3 to 3.6 s after answering `State`; the reply write hits a closed socket (`os error 10054`); `border manager: stuck for ~3000 ms in locking the window manager`; `could not acquire window manager lock`. Cause not found (host I/O stalls are a candidate) | 1/10 sweeps before the consolidation, 1/12 after; probe 0.35% vs 0.39% of calls |
| `lifecycle_hidden` (monocle after crash) | Windows | no signature captured (capture at `trace` next time) | 1/10 before, 2/12 after |
| `resize` (drag checks `win2:bottomleft`, `win3:top`) | Windows | drag checks fail, pass on rerun; documented as flaky | 1 failure in the first run, passed twice |
| daemon does not start (`failed call to AllowSetForegroundWindow after 5 retries`) | Windows | the scenario prints "did not run, counted as 1 failed", no `result.json`; only seen at load 6.6-8 | candidate, 4/~45 starts at that load vs 0/~150 at load 3-5 |
| `hotplug` with the recorder on (`AgentLost ... during exec tasklist`) | Windows | after the display unplug, in the recorder collection step; the rerun passed | candidate, 1 occurrence |
| `maximizing.user`, `placement` (integer case), `unknown_monitor` (2) | Windows | not flakes: the same 4 checks fail on every commit (stale known-failure markers) | fix or re-mark them |
| `focus_follows_mouse` "did not run" | Windows | reporting quirk of the runner, `result.json` says 15/0 | ignore the line |
| `vm-commands`, `vm-core-e2e` | KDE | `commands.py` (guest D-Bus stops replying, BrokenPipe), `handover.py` ("win3 is inside the work area and not on a tile"), `lifecycle_hidden.py`, `manage_rules.py` (window never appeared, 30 s), `core_e2e.py` (KWin script never reported in) | 0 green in 6 runs before the consolidation at host load 25 to 190; load-dependent is plausible, not shown; no gate decision until one calm-host run exists |
| `golden` test of `komorebi-protocol` | native | "5 passed; 1 failed" once, six reruns passed, text not captured | 1 occurrence; keep the text if it recurs |
| KDE `tests/schemas.rs` | native | shares a pid-only socket path | keep `--test-threads=1` |
Observed rates are consistent with a wide range: 1 failure in 10 runs fits anything from about 0.3% to 45% per
run. Quote the counts, not "flaky". The source registry of the consolidation runs (with commits and logs) is
kept by whoever runs the gates; add new occurrences there and update this table when a rate changes.
+16 -1
View File
@@ -1,5 +1,7 @@
# The core model: KDE and Windows compared, and the split into `komorebi-core`
> **Status (wip-cand4):** measurement plus a running log. `komorebi-core` has `Container`, `Monitor`, `Workspace` (incl. `update_shared`) over KDE, Windows and macOS; `WindowManager<P>`, the router and `process_event` are NOT shared yet (sections 17 and 18 give the blockers); sections 8 and 12 are the designs that were then implemented.
Status: measurement and proposal (plan step 9 preparation, KDE side). Measured at the tip of
`wip-u-kfde` (based on `wip-main` 633e7453); the Windows tree is `komorebi/src`, KDE is
`komorebi-for-kde/komorebi/src`, macOS (`komorebi-for-mac/komorebi/src`) is listed only where it
@@ -1122,7 +1124,7 @@ compiles unchanged; the defaults of the ones a daemon must provide return an err
implementation departs from section 12: `adjust_layout` and `place_container` take the container
and the tile, not its index; the guard of `begin_update` is a boxed `dyn Any` (no associated type, so
macOS needs nothing); the KDE closure around the placement is gone (it had nothing between it and
its `?`); the Windows title-bar tables are read once per container instead of once per pass.
its `?`); the Windows title-bar tables were first read once per container instead of once per pass, which was a regression, not an improvement: section 19 (the `begin_pass` hook) takes them once per pass again.
**What macOS keeps (kfm's `update`, not touched):** its `update` is another shape, not the same text
with other hooks. It wraps the placement in SkyLight's `SLSDisableUpdate`/`SLSReenableUpdate` (a
@@ -1302,3 +1304,16 @@ Recommended next step: shared text first between KDE and macOS (kfm and kfde), w
functions and most router arms are already identical, then Windows converges onto it function by
function against the blocker list above; creating `WindowManager<P>` before blockers 1 to 3 are decided
would move less than half of the file.
## 19. Corrections after the review of `komorebi-core` (findings F2 and F3)
- **F2, the floating-window hook.** `Workspace::remove_floating_window` calls the hook before it takes the
window out of the ring (the KDE and macOS originals move the focus first, and the focus index moves
back by one whatever the length), so the hook is `before_floating_removed`, not `after_floating_removed`
as sections 8 to 11 call it. Behaviour is unchanged; a test pins the order.
- **F3, the title-bar snapshot.** The original Windows `update` read `REMOVE_TITLEBARS`, `NO_TITLEBAR` and
`REGEX_IDENTIFIERS` once per placement pass; the first Windows `place_container` read them per container,
so a configuration reload in the middle of a pass could give two containers two tables (section 16
wrongly called this an improvement). `WorkspacePlatform::begin_pass` is called once per pass after the
layout is computed and its answer reaches the hooks as `Placement::pass`; Windows takes the snapshot
there and `place_container` reads it, as the original did.
+70
View File
@@ -1,5 +1,7 @@
# macOS hand-check list
> **Status (wip-cand4):** OPEN, for the user on a real Mac; only compile and unit tests have run on a Mac Mini, no macOS daemon behaviour has been observed; commands for the Mac are in [build-and-test.md](build-and-test.md).
Status: written by the `kfm` agent for the user, 2026-10-31. Nothing here has been run: macOS cannot be built, linked or tested on the Linux host, only type-checked through a fake C compiler (`tools/fast-check`). Every revision below is `type-checks, not run`. Revision ids are jj change ids (stable) with the commit id they had when this was written (commit ids change when a revision is rewritten; use `jj log -r <change id>`).
How to use it: build the unified (or, until they exist, the per-tree) macOS `komorebi`, `komorebic` and `komorebi-bar`, run `cargo test --workspace` on the Mac first (the 399+ unit tests have never run against these changes), then walk the sections in order. For before/after capture use `komorebi-recorder` against a build of the baseline `wip-main` ancestor `ff3711dc` and the tip. A section is done when the "look for" column is true.
@@ -8,6 +10,73 @@ How to use it: build the unified (or, until they exist, the per-tree) macOS `kom
The real-Mac runs so far (Mac Mini, rustc and clippy 1.93, tip a35573d8) are **compile and unit tests only**: `cargo test --workspace` in komorebi-for-mac passed (daemon 366 passed, 1 ignored; 368 total, 0 failed) and clippy `-D warnings` was clean apart from the two items fixed afterwards. Nothing was run as a daemon: no focus, tiling, borders, animations or bar rendering has been observed on the Mini. Every walk-through item below is still open.
## Prioritised checks from the independent review (H1-H12)
Source: the macOS review of the candidate (S/review/mac.md). It found no must-fix; the fixes it asked for
are the `wip-u-kfm3` revisions (inert application in the registry, register on observe, no forget in
`Window::drop`, `forget_pid` first, forget on reap). Prerequisites: build `komorebi-macos` from the
candidate, grant Accessibility and Screen Recording, run `komorebi` with `RUST_LOG=komorebi=debug`;
use `komorebic state` for state. Order is by risk to a user's day.
1. **H1 hide spot on the right display (HideSpot).** Two displays; one workspace with a window
straddling the left edge of display 2 (drag it half off). Switch workspace on display 2 and back.
Expect: the window is hidden in the `BottomLeft` corner of display 2 (not display 1, not left in
view) and restored to the same frame. Repeat with `window_hiding_position: BottomRight` in the
monitor config. Stacks: a 3-window stack (`komorebic stack`), `cycle-stack`: only the front window is
visible, the others sit in the monitor corner.
2. **H3 event latency and stall.** A many-window app (Chrome, about 20 windows): restart komorebi and
note the time to ready in the log against the original build (registering is now once per observed
window, which removes the n x n cost of the first revision). Then `kill -STOP <pid>` an app with a managed
window and press `komorebic focus right` 5 times: commands are handled again within the AX timeout
after `kill -CONT`; a log line `invalidating application observer for process id` for a live app
after the CONT is the bug.
3. **H7 native tabs.** Finder or Terminal with two native tabs: switch tab, close the first tab; the
window stays managed, focus works, and `komorebic state` shows one window id per container with
no duplicates.
4. **H2 floating and monocle on workspace switch.** `toggle-float` a window, switch workspaces twice:
it hides and comes back at its old frame. `toggle-monocle`, switch workspace and back.
5. **H8 scrolling workspace.** `komorebic change-layout scrolling`, open 5 windows, pan with the
gesture and with `focus left/right`; windows scrolled out of view are parked at the screen edge (not in
the corner) and return on focus; switch workspace and back.
6. **H9 config reload visibility.** Set `default_container_padding`, `default_workspace_padding`,
`floating_window_aspect_ratio`, `layout_defaults` and `display_index_preferences` in komorebi.json and
apply with `komorebic replace-configuration` (or restart): padding on every workspace (not only the
focused one), `toggle-float` aspect ratio; removing `layout_defaults` or `floating_window_aspect_ratio`
and reapplying resets them (none, and Standard 4:3), while removing a padding key keeps the previous
value.
7. **H10 old state and the bar.** `komorebic state > old.json` on the ORIGINAL build; start the new
`komorebi-bar` against the new daemon and confirm it renders; the new daemon's `komorebic state` must
parse in the bar (workspaces, monitors with `window_hiding_position`).
8. **H6 pause and quit.** `komorebic toggle-pause`, quit an app with managed windows, `komorebic
toggle-pause`: its windows are gone from `komorebic state`. (That its registry entries are gone
is covered by the unit test of `forget_pid` and visible only in a debug log.)
9. **H11 bar config.** Put a Keyboard, Media and Systray widget and a `mouse` block in
komorebi.bar.json: the bar starts, logs "the Keyboard widget is not supported on this platform and is
skipped" (three times) and the `mouse` warning, and renders the other widgets. Then break the file
(`"mouse": {"on_scroll_up": 5}`, or an unknown widget name): the bar must refuse to load it with an error.
10. **H12 unsupported commands.** `echo '"ToggleMaximize"' | nc -U $DATA_DIR/komorebi.sock`: a
not-supported reply, no state change, the daemon keeps running.
11. **H4 registry growth.** Note `lsof -p $(pgrep -x komorebi) | wc -l` and `lsmp -p $(pgrep -x
komorebi) | tail -1` (Mach ports). In TextEdit open and close the Open and Save panels 200 times.
Compare the counts: steady growth means entries (and observers) are retained; it would also answer
whether an `AXObserver` holds a port (not verified).
12. **H5 hung subscriber (known, pre-existing).** `kill -STOP $(pgrep komorebi-bar)`; run `komorebic
focus left` 10 times and watch the log for "could not acquire window manager lock". Expect the
daemon to stop reacting once the socket buffer fills; `kill -CONT` recovers it. See the known issue
below: this is how the original behaves and it is deliberately not changed.
### Known issue, not fixed: a subscriber that stops reading can stall the daemon
`notify_subscribers` writes to each subscriber socket under the window manager lock, and the macOS
connect closure sets no write timeout, so a subscriber that accepted the connection and does not read
(a stopped bar, a debugger) makes `write_all` block once the notification outgrows the socket buffer;
the event thread then holds the lock and every command logs "could not acquire window manager lock".
The original daemon behaves the same. A write timeout was considered and **not added**: the
Windows review found that a write timeout can truncate the JSON notification in the middle (the
subscriber then reads half a message) and does not bound the stall in the way the timeout suggests, so
the fix needs a design (a bounded queue per subscriber written off the lock) and not a one-line
timeout. Until then H5 documents the hang.
## A. Revisions that change what the daemon does (BEHAVIOUR)
| Revision | What changed | Look for on a Mac |
@@ -27,6 +96,7 @@ The real-Mac runs so far (Mac Mini, rustc and clippy 1.93, tip a35573d8) are **c
| 11(iii) Container: `refactor(mac): the daemon's Container is komorebi_core::Container<Window>` (see `jj log -r wip-u-kfm2`) | `Container` is the shared generic type over the macOS `Window` (its id, windows, focus, `remove_*`, `idx_*` functions are the shared ones). The four functions that need the monitor's hiding corner and can fail (`add_window`, `load_focused_window`, `hide`, `restore`) stay macOS's, renamed `add_window_at`, `load_focused_window_at`, `hide_on`, `restore_focused_window` (`ContainerExt`); `Window::hide/restore/minimize/unminimize` take `&self`. State JSON must not change (pinned by two tests in container.rs). | Run `cargo test` (the container, workspace and scrolling tests use these). Then by hand: stack windows (`komorebic stack`), unstack, cycle the stack (hidden members go to the monitor's corner, the front one is restored); switch workspaces and come back (restore of the front window of each stack); `komorebic state | jq '.monitors.elements[0].workspaces.elements[0].containers.elements[0]'` still has `id`, `locked`, `windows.{elements,focused}` and nothing else. Set `window_hiding_position` per monitor in the config and check each monitor hides into its own corner. |
| 11(iii) Workspace: `refactor(mac): the daemon's Workspace is komorebi_core::Workspace<MacosPlatform>` (see `jj log -r wip-u-kfm2`) | About 50 workspace functions (container and focus operations, placement, resize constraints, window lookups, floating helpers, the stack and monocle operations that hide windows) are now the shared ones; `hide`, `new_container_for_window` and the stack functions pass the monitor's corner through `MacosPlatform::hide_spot` (kept in `MacosWorkspaceState`, set by the monitor with the globals), and `hide` passes the display bounds for the containers through `hide_spot_on_display`. macOS's own `update`, `apply_wallpaper`, `restore`, `remove_window`, `load_static_config`, `prune_duplicate_windows`, `visible_window_details`, `reap_invalid_windows_for_application`, `restore_windows`, `calculate_layouts` and `set_scrolling_columns` are `WorkspaceExt`; the scrolling methods are `WorkspaceScrolling`. | `cargo test` first (the workspace, scrolling and window_manager tests). Then: stack and unstack, switch workspaces both ways (each stack shows its front window, the hidden ones are in their monitor's corner), toggle monocle and back, float and unfloat a window, cycle the monocle container, move a window to another workspace, move a container across monitors; with a different `window_hiding_position` on each monitor check each monitor's windows park in their own corner and that a floating window that overhangs the edge of a display is still parked on its own display. `komorebic state` keys of a workspace are unchanged (pinned by `state_pin`). Scrolling layout: focus, move, consume and expel, pan, resize a column. |
| 11(iii) Monitor: `refactor(mac): the daemon's Monitor is komorebi_core::Monitor<MacosPlatform>` (see `jj log -r wip-u-kfm2`) | The monitor is the shared generic type; the corner (`window_hiding_position`) is the platform's flattened `extra` (written last, as before), the constructors, `update_*_globals`, `load_focused_workspace`, `move_container_to_workspace(1)`, `add_container_with_direction`, `hide_unfocused_workspaces` and `restore_focused_workspace` are `MonitorExt`; `focus_workspace`, `add_container`, `remove_workspace*`, `ensure_workspace_count` and the name and layout lookups are the shared ones. The monitor gives its workspaces the corner through `workspace.state` when it updates their globals. | `cargo test` (monitor tests, `state_pin`). By hand: `komorebic state | jq '.monitors.elements[0] | keys_unsorted'` is the same list as before with `window_hiding_position` last; switch workspaces on each monitor (hide and restore of the whole workspace), focus-workspace by index and by name, move a container to another workspace and to another monitor, unplug and replug a display (the monitor and its workspaces are rebuilt through `Monitor::new` and `update_all_workspace_globals`), a config with `window_hiding_position` per monitor. |
| `wip-u-kfm3` registry fixes (see `jj log -r wip-u-kfm3`) | The registry keeps inert application copies (no blocking Accessibility call when an entry is dropped), a window is registered when its observer is attached, a clone being dropped no longer deregisters its window, `forget_pid` runs ahead of the pause and other-space returns, and the application reaper forgets what it reaps. Nothing reads the registry except the unused `MacosBackend`. | H3, H4, H6, H7 above, and the usual walk-through: no change in what the daemon does is expected. |
Revisions in section B change no behaviour on purpose (rename, move, route); they still need the sections C walk-through, because a mechanical mistake would show there.
+2
View File
@@ -1,5 +1,7 @@
# The platform seam: evidence
> **Status (wip-cand4):** the evidence for `crates/komorebi-backend`, which has landed (trait, `FakeBackend`, contract tests); the Windows daemon goes through it for the clusters in [backend-switch.md](backend-switch.md); read section 8 as the list of what was never verified.
Status: evidence document (step 7a of the consolidation). No `Backend` trait is proposed here as code, and none may be written before this document has been reviewed. Every statement about the code carries a citation; where I could not confirm something it says "not verified" and the item is collected in section 8.
## 1. Purpose and how to read it
+2
View File
@@ -1,5 +1,7 @@
# Settings: replacing the process-wide statics
> **Status (wip-cand4):** design plus landing log. `crates/komorebi-settings` exists and the three daemons read the paddings, aspect ratio, layout defaults and display preferences through it; the remaining statics (see the section list) are still process-wide; macOS runtime is unverified.
Status: design (plan step 10, phase 1). Measured on `wip-main` 633e7453 (the Windows tree
`komorebi/src`, KDE `komorebi-for-kde/komorebi/src`, macOS `komorebi-for-mac/komorebi/src`). Nothing
here was run: counts come from `grep` and reading, and macOS cannot run on this host. The shared type
+2
View File
@@ -1,5 +1,7 @@
# One `komorebi`, one `komorebic`, one `komorebi-bar`
> **Status (wip-cand4):** steps 0-8 done: one `komorebi` (`komorebi-daemon/`), `komorebic`, `komorebi-client` and `komorebi-bar` package, platform by `cfg(target_os)`; the cutover (shim packages, one flake, final directories, one version) is open. The older sections below are history: in particular the note "never write `-p komorebi`" was true before step 8 and is wrong now; see [build-and-test.md](build-and-test.md) for current commands.
Goal: three packages and three binaries that build on Windows, KDE (Linux) and macOS, the platform
chosen by `cfg(target_os)` (generics, `cfg_select!`, exhaustive `match`; no macros as a design tool).
This file records a spike (throwaway revisions on bookmark `wip-u-pkg-spike`, titled `spike:`; nothing