From 631d8267f3be9368cae4aa96abba627ea2705e7d Mon Sep 17 00:00:00 2001 From: LGUG2Z Date: Wed, 28 Oct 2026 23:10:22 -0700 Subject: [PATCH] docs(repo): what the shared scenarios found on kfde and on kfw 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. --- docs/dev/BEHAVIOUR.md | 94 +++++++++++++++++++++++++++++++++++++++++++ docs/dev/vm-tests.md | 2 +- 2 files changed, 95 insertions(+), 1 deletion(-) create mode 100644 docs/dev/BEHAVIOUR.md diff --git a/docs/dev/BEHAVIOUR.md b/docs/dev/BEHAVIOUR.md new file mode 100644 index 00000000..760cc0e2 --- /dev/null +++ b/docs/dev/BEHAVIOUR.md @@ -0,0 +1,94 @@ +# What the shared scenarios say about kfde and kfw + +[COMPARE.md](COMPARE.md) compares komorebi for KDE Plasma (kfde) with komorebi for Windows (kfw) +from their sources. This document compares them from running them: the scenarios in +`nix/tests/vm/lib/komorebi_vm/core/scenarios` are written once, against the `Platform` of +[vm-tests.md](vm-tests.md), and run on a real KWin and on a real Windows 11 desktop. A scenario that +passes on both says the two ports behave the same in that respect, as far as the scenario looks. A +scenario that fails on one says where they differ, and is a finding to look into, not an assertion +to loosen. + +Everything here is a dated result, and says who got it. It is not generated: it is written from the +runs, and goes stale when the code changes. + +## Where the results come from + +- **kfde**: the suites of this repository, run on 2026-10-29 on a Windows 11 machine's WSL 2 (a + Ryzen 9 5900X, nested KVM), at `scale` 1.5. +- **kfw**: a Windows 11 guest under QEMU on the same machine, running kfw's daemon, driven from + kfw's tree with a copy of `core/` that `scripts/sync-e2e-core` keeps in step. These results were + reported by the session that ran them, and are not repeated here. The guest is a Windows 11 + evaluation image. Its display driver was the basic one for the scenarios that have run; a second + display, added and removed while it runs, has since worked with a QXL device and Red Hat's signed + driver for it, which the current image carries. The windows are `komorebi-testwin`, a test window + of its own, where kfde's are `foot` terminals. + +## The scenarios + +| Scenario | What it checks | kfde | kfw | +|---|---|---|---| +| `tiling` | three windows are tiled: where the layout says, inside the work area, clear of each other | pass | pass | +| `focus` | `focus` and `cycle-focus` move the focus, and the OS and the daemon agree on it | pass | pass | +| `moving` | `move` and `cycle-move` swap tiles, and the focus stays with the window | pass | pass | +| `stacks` | `stack`, `cycle-stack` and `unstack`: the window in view has the focus, the others are put away | pass | pass | +| `monocle` | `toggle-monocle` gives one window the work area and puts the others away | pass | pass | +| `workspaces` | `send-to-workspace` and `focus-workspace` put windows away and bring them back | pass | pass | +| `closing` | a closed window leaves the state, and the others take its room | pass | pass | +| `resize` | dragging the edge two tiles share moves it by what the pointer moved | pass | **fails**, cause found | +| `commands` | every layout, and about 216 commands, leave the daemon healthy | pass, none skipped | not run | +| `rules` | initial, permanent and ignore rules by title | see below | not run | +| `hotplug` | an unplugged display takes its windows to the other, a plugged one is a monitor | pass | not run | + +`rules` passes on kfde in every check. One run of the suite that holds it also failed a check that +is not the scenario's, that the daemon had exited after `komorebic stop`; the next run passed it, +and the cause is not known. + +## What they have found + +**`resize` on kfw.** Dragging the edge between two tiles by 30, 60 and 120 pixels moved it by 27, +53 and 96 on kfw's master, and by 27, 51 and 106 on its animation branch (`0c9acdf4`), where kfde +moves it by exactly the pointer's distance. The pointer is not the cause: the same drag of the +border of a window that nothing manages moved it by 30, 60 and 120 exactly, with the cursor where +it was asked to be. The loss is in what kfw does with the drag. + +A recording of a 60-pixel drag, made with komorebi-recorder on the Windows guest, shows where. +The window grew steadily from 596 to 656 pixels, exactly the distance dragged, which is why the +unmanaged window followed the pointer. kfw's `MoveResizeStart` handler (`process_event.rs`) +reads the rectangle the drag started from with `WindowsApi::window_rect` when it handles the +event, which the recording puts about 100 ms after the drag began, when the window was already +603 to 608 pixels wide. The distance kfw measured was 656 - 603 = 53, and its trace log shows the +resize it asked for with a delta of 106, twice that. A longer drag moves further before the event +is handled, so the loss grows with the distance, as measured. A fix that reads the starting +rectangle from the tile in `latest_layout`, or in the event callback before the event is queued, +is not tried yet. kfde reads nothing of the kind and passes. The recording is on the machine that +made it (`~/e2e-w0/rec1/resize/session/rec`), and the write-up is `W1.md` in kfw's tree. + +Nothing else moved: no tile went up +or down, none overlapped, and every window stayed inside the work area. + +## What the scenarios had to allow for + +These are differences between the ports that a scenario does not hide, and are not failures: + +- **A terminal's size.** A `foot` window sizes itself to whole cells of its font, so its frame is + up to a cell short of the tile (924 by 504 for 925 by 505 in a recorded state). kfw's test window + has no granularity. `Platform.tolerance` is a cell on kfde and 2 pixels on kfw, for the rounding between the DWM + frame and the layout (whether 0 would pass there has not been tried). +- **What "put away" is.** A stack's other windows, the windows of another workspace and those + behind a monocle are on a parking desktop on kfde, and cloaked on kfw. `Platform.hidden` says it + for both. +- **The work area.** A kfw screen of 1280 by 800 has a work area of 1280 by 752, because of the + taskbar. A scenario asks the platform for it. +- **Identity.** A window is told by the title the scenario gave it. kfde's state has its own ids + for windows and monitors, and kfw's has handles, so a scenario never compares them. +- **State shape.** The two `komorebic state` outputs differ in how a window is written and in a few + fields each. `core/snapshot.py` reads both, and its tests read a state recorded from each. + +## What is not covered + +- Pointer input on a second display, on Windows. The tablet there spans only the first. +- Suspend and resume, which no guest can test. +- `commands`, `rules` and `hotplug` on kfw, which have not run there. Displays can be added and + removed on the Windows guest and kfw follows; it is the scenario that has not run. +- Most of what is particular to one port: kfw's cloak and borders, kfde's parking desktop and + KWin effects. Those stay in the suites of each port. diff --git a/docs/dev/vm-tests.md b/docs/dev/vm-tests.md index 913be05f..228906d0 100644 --- a/docs/dev/vm-tests.md +++ b/docs/dev/vm-tests.md @@ -169,7 +169,7 @@ the run. there too, and the edge moved less than the pointer did (+53 px for a drag of 60): a finding about kfw, not about the setup, because an unmanaged window followed the same drag exactly. `scripts/sync-e2e-core` keeps kfw's copy of `core/` in step until `core/` - moves there. + moves there. [BEHAVIOUR.md](BEHAVIOUR.md) says what each scenario found on each port. - `Checks` counts checks and fails once, at the end, so that one failure does not hide the ones after it. `finish()` prints `passed: N failed: M`, and its error names the checks that failed, which `nix build` shows in the last lines