mirror of
https://github.com/LGUG2Z/komorebi.git
synced 2026-11-15 05:12:28 +01:00
3a3a0f8f24f89a80e49707cf06e4e5be23e7e044
18
Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
 LGUG2Z
|
3a3a0f8f24 |
feat(wm): JSON schemas, and the module's typed options
komorebi.json is described as a JSON Schema, made from the Rust types that read it: komorebic prints the schema of komorebi.json, of an applications.json, of a notification and of a message, and the daemon answers the same four questions on its socket. schema.json and schema.asc.json are committed (just jsonschema). The module's config option is typed from the schema: schemars-nixgen makes nix/komorebi-options.nix from schema.json (just nixgen), so a layout komorebi does not have, or a value of the wrong kind, does not evaluate. The module writes config as a komorebi.json and gives it to the daemon with --config. configFile and the file the module writes are checked against the schema when the system is built. applicationSpecificConfiguration takes files from GitHub, and there are none by default, since no community file for Plasma is known. Two checks keep the generated files honest without the tools that make them. schema-fresh compares the schemas with what komorebic prints, and the hash on the first line of the options with the schema. nix-options-validation evaluates the options against the example configuration, written in Nix and in JSON. nixos-module-eval also evaluates the module with the sources turned off: with applicationSpecificConfiguration.enable = false the sources are left out of the config that is written, and with no config either there is nothing to write and the unit passes no --config. ARCHITECTURE has the guarantee row that names the two checks. |
||
|
LGUG2Z
|
ed34286bca |
feat(wm): application specific configuration
Rules for particular applications can be kept in files of their own, applications.json, which komorebi.json names with app_specific_configuration_path: one path or a list. The ignore, manage and floating rules of every application in a file are added to the lists the configuration's own rules go in, so a file can be shared or kept apart from the settings. A path with no file behind it is skipped with a warning, since one komorebi.json is meant to work on every platform and may name a file that only another platform has; a file that is there and is not an applications.json is an error. The titleless and tabbed rules of other platforms are read and do nothing. komorebic/applications.json is a start for Plasma: it floats the calculators, the screenshot tool, the authentication dialog and System Settings. A test opens the windows it names. |
||
|
LGUG2Z
|
5eaa613f50 |
feat(wm): configuration in komorebi.json
The daemon takes its settings from a komorebi.json: the file --config names, or the one in the config home ($KOMOREBI_CONFIG_HOME, else ~/.config/komorebi). Without a file it runs on its defaults, as before. StaticConfig reads the file in three steps, because the monitors are known only after the backend has been asked. preload makes the window manager and applies the settings that are process-wide, postload gives each monitor and workspace the entry of its place (by the index display_index_preferences gives a monitor's serial number id, else in order), and main asks KWin for a desktop for each workspace the file lists. A watcher on the file sends the daemon a ReloadStaticConfiguration about two seconds after it changes, whether an editor wrote the file in place or renamed a new one over it, and a file that does not parse changes nothing. A workspace can change its layout, its work area offset and its layout options with the number of its containers, from the file or with komorebic (workspace-layout-rule, its named form and the two that clear), and layout_defaults gives every workspace of a layout the options it sets none of. One file is meant to serve every platform, so a key that does nothing on Plasma is accepted and ignored. config_parity checks the example and the files of other platforms; the keys of features that are not in yet are listed there, and the test fails when a list names a key that is read. The file also sets what the stacks, the float override, the floating layer and monocle set while the daemon runs: window_container_behaviour, with its rules by container count in a workspace, float_override, float_override_placement, floating_layer_behaviour (for a monitor and a workspace too), floating_layer_placement and monocle_focus_behaviour. Their features come before this commit, but a file to put the keys in does not, so they are part of this one. komorebic gains configuration, generate-static-config and start --config. The NixOS module gets configFile, which the unit gives the daemon as --config. |
||
|
LGUG2Z
|
05de20749b |
feat(wm): maximize
A window could be given the work area only as a tile of the layout, which has padding around it. `komorebic toggle-maximize` has KWin maximize the focused window instead: it gets the work area of its monitor with the panels left alone, and it leaves the layout, so that it is in no container. Toggled again, the window is restored, put in a container of its own at the index it was taken from, and the workspace is tiled again. The window is kept in the workspace as its maximized window, with the index it goes back to, and the state shows both. While it is maximized the workspace asks KWin to maximize it again on every tiling, and does not move the containers behind it. The messages that are about the tiles (move, stack, resize, promote, preselect, lock, float, monocle, and the ones that send a container to another monitor or workspace) are dropped before they are handled, since there is no tile to act on. Focusing in a direction finds no container on any side of it, so the focus goes to the monitor on that side, where a maximized window or a monocle is given the focus whole. Showing the workspace again restores the maximized window and focuses it ahead of the containers' windows. A window in monocle that is maximized leaves the monocle, and one that closes takes the maximize with it. Backend gets a maximize command, which does nothing unless a backend implements it; the fake desktop and the KWin backend do, and the bridge carries it out with KWin's own `setMaximize`. A maximize also makes the bridge forget the position it was last asked to put the window at, which it would otherwise set again on the work area's size when the window's frame changed within a second of a tiling. komorebi/tests/maximize.rs and maximize_commands.rs drive it against the fake desktop, with one monitor and with two. The bridge's tests and the backend's tests read the maximize command from the same fixture, so that what one sends is what the other carries out. vm-features is a new session suite that reads screenshots: the first thing it checks is that the maximized window fills the work area, is the one on top, and goes back to its tile; the vm-commands sweep runs the new command. |
||
|
LGUG2Z
|
0d21dd332c |
feat(wm): monocle
A workspace could show its windows only side by side. Monocle gives one container the whole work area: the focused container is taken out of the workspace's containers, so the layout gives no container a tile, and the next tiling puts its window on the work area less the padding. Turning it off puts the container back at the index it came from, and the tiles come back as they were resized: the container keeps its resize adjustment, and the workspace does not shorten the list of adjustments while a monocle is on. The windows of the other containers are hidden on the parking desktop, as the windows behind the front one of a stack are, and the front window of each is shown again when the monocle is turned off or the window in monocle closes. A stack in monocle stays a stack. `komorebic toggle-monocle` turns it on and off. What focusing in a direction does meanwhile is set with `monocle-focus-behaviour` or switched with `toggle-monocle-focus-behaviour`: with `cycle` the monocle goes to the previous or the next container, with `no-op`, the default, no container is on any side and the focus falls through to the monitor on that side, where the monocle window of its workspace, if it has one, is given the focus, and the command fails where there is no monitor. A container that is moved to a monitor or sent to a workspace in monocle turns that monocle off first. `cycle-focus` always carries the monocle along. Giving the focus to another window gives it back to the monocle window, so that it stays in front. `move` and `cycle-move` are refused and `toggle-float` is ignored while a window is in monocle, since the focused container is not the window in front. The monocle container is in the state, with the index it goes back to, and a window in it that closes takes the monocle with it. komorebi/tests/monocle.rs drives it against the fake desktop, with one monitor and with two. vm-core-e2e checks in a real KWin that the focused window fills the work area, that the state has the monocle container, that toggling back restores the tile, that the cycle behavior gives another window the work area, and that the windows behind a monocle are parked, which a clean stop and the next start after a crash put right; vm-stacks checks a monocle over a stack; the vm-commands sweep runs the new commands. |
||
|
LGUG2Z
|
331db681e2 |
feat(wm): stack out of sight on a parking desktop
A container has one tile, so the windows of a stack that are not in front have to be out of sight. KWin has nothing a script can set to hide a window except a virtual desktop nobody looks at, which the first spike measured to cost no focus change where minimizing a window cost two. Backend::hide takes a window out of sight and Backend::restore brings it back; the KWin backend parks the window on a desktop named komorebi-park, which the table keeps out of the workspaces, and remembers where each hidden window came from so that it is still on its workspace. KWin saves a desktop in kwinrc as soon as it is made, so komorebi removes the parking desktop when it stops, after the windows are back, and the first snapshot of the next run finds one a killed run left, sends its windows home and removes it. The windows komorebi hid are recorded, so that a minimize the compositor reports for one is not mistaken for the user's. komorebic stack, unstack, stack-all and unstack-all stack and unstack windows. The window container behavior and the float override decide whether a window that opens joins the focused container or floats, for every workspace or for one. vm-stacks stacks windows in a headless KWin, shows a workspace and goes back, stops, and kills the daemon with a window parked. |
||
|
LGUG2Z
|
62e37e44cf |
feat(kwin): workspaces are KWin's own desktops
komorebi's workspaces exist on Windows and macOS because neither has a virtual desktop API: switching hides every window of the workspace being left. KWin has virtual desktops, per output since 6.8, so here workspace i is KWin's desktop i on every monitor, and each monitor shows one. KWin shows, hides and focuses the windows of a desktop; komorebi asks for a switch, puts a window on a desktop, and follows what anything else does. The Backend gets the workspace methods (ensure_workspaces, switch_workspace, set_window_workspace, window_workspace, current_workspaces), and the fake its desktops. The bridge reports the desktops, the desktop each output shows and a window's desktops, and carries out output_desktop and desktop commands, typed and tested with the fixtures like the rest. The table turns a switch or a move komorebi did not make into a WorkspaceChange or a WorkspaceMove, and records its own when it sends them, so that KWin's report of those raises nothing. The window manager follows a switch with no command in reply (adopt_workspace_change), puts windows on their desktops before a desktop is shown (focusing a window first would take the monitor back), and loads the windows open at startup onto the workspace of their desktop. Per-output desktops are a kwinrc setting that is off by default, and kwriteconfig6 was not on the PATH of the user service in a live session, so komorebi edits kwinrc itself (kwin::kwinrc) and puts the user's value back when it stops, also after a crash. focus-workspace, move-to-workspace and send-to-workspace come with this commit, since the tests of switching and moving, and vm-workspace-switch, need them; the named and cycling workspace commands follow. vm-workspace-switch runs the daemon against a real KWin; vm-kwin-contract checks what komorebi relies on from KWin's per-output desktops, on a headless KWin with two outputs and no komorebi. |
||
|
LGUG2Z
|
37b06993d2 |
feat(wm): tune layouts, and the scrolling layout
`komorebic layout-ratios --columns ... --rows ...` sets the share of the work area the first columns and rows of the focused workspace's layout take, and `scrolling-layout-columns N` how many columns of the scrolling layout are in view. Both are layout options of the workspace, which komorebi-layouts reads. The scrolling layout is a strip of columns that runs past the edges of the work area, so its tiles are not clamped to it: the windows of the columns out of view are off the screen. When a window of a scrolling workspace gets the focus, the workspace is tiled after the focused container changed, which scrolls the strip to it. KWin moves a window anywhere, but keeps 100 pixels of a window it resizes on an output once the client has drawn at the new size, which pulls the columns out of view back onto the screen. The bridge remembers the position it was asked for, for a second, and asks again for the position alone when KWin moved the window elsewhere, three times at most. komorebi-layouts compiles `Rect::percentage_within_horizontal_bounds` only with its darwin feature, which this repository does not enable, so the workspace has its own copy of it. A new VM suite, vm-scrolling, after the spike's m2-scrolling script, checks in a real KWin that the columns out of view stay where komorebi put them and that the strip follows `komorebic focus`; vm-commands sweeps the two new commands. |
||
|
LGUG2Z
|
a86e2bdc63 |
build(nix): a NixOS module for komorebi
On NixOS, running komorebi should take one flake input and one module line. The flake exports `services.komorebi` as nixosModules.default (and .komorebi). It adds the flake's overlay, which gains komorebi-full, installs komorebi and komorebic, and runs the daemon in every Plasma session as a systemd user unit, wanted by plasma-workspace.target and ordered after plasma-core.target, which Plasma orders after KWin. systemd starts a daemon that fails again; the exit status of a SIGTERM (130) counts as success, so a stopped unit is not failed. The unit's PATH is the one a terminal in the session has, instead of the few store paths NixOS gives a unit. The options are enable, package, logLevel and a read-only execStart, the command line the unit runs. There is no configFile: the daemon reads no configuration file yet, and an option that linked one would do nothing. nixos-module-eval evaluates seven scenarios as real NixOS systems and checks their assertions, the unit and execStart, with builtins.tryEval for the two that must not evaluate. Nothing in it builds a Linux package, so it runs on a Mac as well. The VM nodes import the module, so every suite runs komorebi as the module installs it. The headless node's komorebi@NAME runs execStart, which has --log-level, so the nodes set logLevel to debug and the suites stop passing it; latency, which times the daemon, keeps the default level. The session node starts the module's unit at login; render-smoke turns it off, since a tiled terminal would cover the desktop it looks at. A new fast suite, vm-module, logs in to Plasma and checks that the unit runs the daemon with the module's log level and PATH, that a window opened in the session is tiled, that a killed daemon is started again, and that a stop is not a failure. docs/installation.md covers NixOS first, and building from source on other distributions. There is no binary cache: the Komorebi license does not allow third parties to redistribute binaries. |
||
|
LGUG2Z
|
e2d757bbb0 |
feat(wm): subscribe to notifications
A program such as a status bar has to follow the window manager, and so far it could only ask: komorebi on Windows and on macOS sends notifications for that. The daemon now keeps subscribers, each a Unix socket in its data directory that a program listens on, and after each event and each message it handles, it connects to every subscriber and writes the event or the message with the state after it. A subscriber can ask to be sent only what changed the state; a window that is shown and a new subscription are always sent, so a subscriber has the state as soon as it subscribes. A subscriber that cannot be connected to is dropped with its socket file and not tried again, and a stopping daemon closes an empty connection to each one. komorebic gains subscribe-socket and unsubscribe-socket, and komorebi-client subscribe and subscribe_with_options, which bind the socket and subscribe. The tests subscribe through real sockets against the fake desktop: a shown window is sent with the state that has it, a subscriber that filters is not sent a question that changed nothing, and one that is gone is dropped. |
||
|
LGUG2Z
|
6f657e53e3 |
feat(cli): komorebic
The daemon answers on its socket, but a person has no way to write a message on it. komorebic is that way: each subcommand that asks something of the daemon is one message, sent with komorebi-client, and a question's answer is printed. komorebic is a separate program because the daemon takes no input but its socket, so a key binding, a script and a terminal all drive it the same way. It has what the daemon can answer so far: state, monitor-information, query, retile and stop. Around them, start runs the komorebi on the PATH in the background and passes it what follows a --, such as --fake-backend to try it without a compositor; log follows the daemon's log, which the daemon now writes to a file a day in LOG_DIR as well as to stdout; data-directory shows where the socket is; completions prints a shell completion script. The hidden docgen writes each subcommand's help to docs/cli, in fences that name their language and wrapped at 100 columns whatever the width of the terminal, so that the pages are the same wherever they are generated; just docgen runs it. The user guide starts here: docs/index.md for KDE Plasma, and a page on running komorebi. tests/cli.rs runs each subcommand against a socket the test serves in place of the daemon. In the VM tests the guests get komorebic next to the daemon, and vm-core-e2e reads the daemon's state with it (the windows it manages, the one it focuses, after KWin restarts too) and stops it with komorebic stop, which unloads the bridge and removes the socket. In the VM test library, Kde.state asks again, a second (times the scale) after an empty answer or a failed command, up to 10 times. The daemon drops a query when it cannot take hold of the window manager within a second, and komorebic then prints an empty line and succeeds; komorebic itself gives the daemon a second to answer and fails when that is not enough. A daemon busy with the first windows does either on a machine that is loaded or slow, and a suite that polled the state died on JSONDecodeError. An answer that is not JSON still fails at once. |
||
|
LGUG2Z
|
88aa78b874 |
feat(wm): a command socket and the first messages
Until now the daemon tiled what KWin reported and nothing else could reach it. komorebi takes its orders on a socket, as it does on Windows and on macOS: it handles no key itself, and whatever binds keys runs a command that writes a message. The daemon binds komorebi.sock in $XDG_RUNTIME_DIR/komorebi (DATA_DIR), reads one JSON SocketMessage per line on a thread per connection, and handles each message with the window manager locked, as the thread that handles events does. The first messages are the ones the first komorebic needs: State (the window manager as JSON, from state.rs), MonitorInformation, Query with a StateQuery, Retile and Stop. A question is answered on the same connection, and the answer ends when the daemon closes it. Stop unloads the bridge from KWin, removes the socket and exits; so does a stop signal. The socket is bound once the daemon is connected to KWin, so a komorebi that cannot connect, such as a second one in the same session, which the bus refuses, leaves the socket of the one that runs alone. With --fake-backend the daemon answers on its socket with no compositor at all, which is how the tests run it. komorebi-client is the other end: send_message, send_batch and send_query, and the types the messages are made of. Its doctests serve the socket themselves, tests/daemon.rs runs it against a window manager over the fake desktop, and komorebi/tests/socket.rs runs the daemon binary from its start to a Stop. |
||
|
LGUG2Z
|
4386003e30 |
feat(kwin): survive KWin restarting
KWin can go away under a running daemon while the session bus stays: it crashed, or kwin_wayland --replace took its place. Its windows go with it, and so does the bridge, which would have reported them closing; in the spikes the old windows vanished without a single removed event. What the daemon does see is the bus, so the thread that serves the connection watches NameOwnerChanged for org.kde.KWin. When the name loses its owner, Table::compositor_lost marks every window closed and returns a Destroy for each, so the window manager takes them out of its layout, and their ids are not given out again. When the name has an owner again, the daemon loads the bridge into the new KWin, trying for up to 15 seconds while KWin is not ready for it, and the bridge reports the new desktop in a snapshot. zbus does not end a held call when its caller leaves the bus, so the Poll of the old bridge is still waiting when the new bridge calls, and it was woken first: it took the commands for the new KWin and answered them to nobody. vm-kwin-restart lost the tile of a window opened in the third KWin that way in one run of three, and a recording of the bus showed the batch going to the old bridge. A Poll held since before KWin last left the bus is answered with nothing and passes its wake-up on to the next call, which a unit test holds. The VM suite vm-kwin-restart (from the spike's spike7-resync) restarts the headless KWin twice under a running daemon, through Kde.restart_kwin in the VM library, and checks that the daemon sees KWin go, takes the old windows out of its layout, loads the bridge into the new KWin, and tiles the windows that open there. |
||
|
LGUG2Z
|
b463191d00 |
feat(kwin): move and focus windows through a held call
With the commands of the Backend trait carried out, the daemon tiles a real KWin. A command looks up the UUID KWin knows the window by, is queued as JSON for the bridge, and returns; the held Poll call is answered with the queue, one millisecond after the first command, so that a retile reaches KWin as one batch. The bridge sets the frame, activates, raises, minimizes, restores or closes the window, and reports what it could not do. set_rect records the frame it asked for in the table, so the window manager sees it at once, and the geometry event that follows says what the client made of it. A KWin script cannot move the pointer, so the pointer follows the focus through KWin's own "Move Mouse to Focus" action, invoked over kglobalaccel once KWin reports the window active. The commands are typed in bridge.js, and the declarations of KWin's API let the bridge set a window's frame, its minimized state and the active window, raise and close it, and nothing else. The session the tests of both sides share grows a second batch: the backend's tests check that set_rect, focus, raise, minimize, unminimize and close send it, and the bridge's tests answer the bridge with it and check what KWin is asked to do, down to the command for a window that has closed, which comes back as failed. The bridge's tests also cover findWindow's fallback to KWin's list, a frame set as a plain object, and a command KWin throws on. Three VM suites check it against a real KWin. vm-core-e2e (from the spike's m2-e2e, the sections that need no komorebic) compares what the daemon asked for, read from its debug log, with what KWin has, read with kdotool: three windows inside the screen, not overlapping, sharing it, the same focused window on both sides, and the same again after a minimize, a restore and a close. vm-client-geometry (slow) has eight real clients answer the frames komorebi asks for: Qt programs and xterm take them exactly, foot sizes itself to whole cells, GTK 4 programs and Firefox keep to their minimum sizes. vm-latency (slow) times retiles from a recording of the session bus: on HVF, from the daemon's answer to the last frame KWin reports, p50 17.3 ms, p95 27.7 ms. vm-kwin-events no longer checks that nothing moves. The VM library gives session commands the test user's home and data directories rather than root's, which a GTK client was refused. The bridge's second request for a position after a resize, which matters for windows off the screen, comes with the scrolling layout. |
||
|
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. |
||
|
LGUG2Z
|
02231d232c |
feat(wm): tile what the backend reports
With the model in place, the window manager can do its job: load the desktop from the backend, tile it, and keep it tiled as the compositor reports what happens to windows. The events are the Windows implementation's, each about one window and carrying it: a window is shown, destroyed, given the focus, minimized or restored. A new window gets a container of its own after the focused one, a closed one leaves whichever workspace has it, a window the user minimizes is out of the layout until it is restored, and every event ends with the workspace in front tiled again. At startup every monitor is loaded, and every open window that is normal, alive and not minimized goes on the monitor its middle is on. An index from each managed window to its monitor and workspace is rebuilt around every event, so that the first event komorebi sees can be the close of a window it picked up at startup. Whether a window is managed is, for now, only whether the compositor calls it a normal window and it is alive; the rules that ignore, manage or float applications come later. When a window closes, komorebi leaves the choice of the next focus to KWin unless KWin focuses nothing, so the two do not fight. The daemon runs this against a backend chosen on the command line. --fake-backend, an in-memory desktop with one monitor, is the only one, and without it komorebi exits with a usage error instead of pretending to manage a desktop it cannot reach. |
||
|
LGUG2Z
|
c0345eb0e9 |
feat(wm): windows, containers, workspaces and monitors
The window manager tiles a tree of four levels: monitors, each with a ring of workspaces, each with a ring of containers, each with a ring of windows. It is the model komorebi has on Windows and macOS, and the first thing the daemon keeps that the backend does not give it. A window is a Copy handle that carries the compositor's id and asks the backend for everything else, so moving one is a call on the handle and needs no context passed to it. A workspace tiles itself: the layout gives each container a tile of the work area its monitor hands it, less the offset and the padding, and every window of the container is asked to move there. A locked container keeps its index because the workspace inserts, removes and swaps its containers through LockableSequence. This is tiling only. Stacks, monocle, maximize, the floating layer, resize adjustments, placement rules and the link between workspaces and KWin's desktops come with the commits that use them. impl_ring_elements!, which gives every holder of a ring the same accessors, lands here with its first users. |
||
|
LGUG2Z
|
ed6a8e96c3 |
feat(backend): reach the compositor through one trait
The window manager decides where every window goes, and asks a compositor to put it there. If it asked KWin directly, every test of its logic would have to boot a virtual machine, so everything it needs from the desktop goes through one trait, `Backend`: queries for windows, monitors, the focus and the pointer, and commands to move, focus, raise, minimize and close a window and to put the pointer somewhere. A real backend answers from a table that compositor events keep up to date, so a query never waits for the compositor; a command returns once it has been accepted, not once the client has acted. `FakeBackend` is the other implementation: an in-memory desktop that does what it is told, at once and exactly, and records every command so that a test can assert on what the window manager asked for. A test can also do what a user does without the window manager asking: move a window, close it, change the focus, turn a window into a dialog. It is strict where KWin is (a command about a window that is gone is an error) and clamps where a GTK4 client does (a minimum size). `with_backend` overrides the process-wide backend for the current thread only and puts the previous one back on drop, also on a panic, which is what keeps one test's desktop out of the next. The module is the first to have `#![deny(missing_docs)]`. The contract (what must be implemented, that a backend is `Send + Sync`) is proved by two `compile_fail` examples with their error codes, and the rules nothing checks are listed as such. docs/dev/ARCHITECTURE.md describes the trait, its roles and the layer that enforces each rule, and docs/dev/DESIGN.md has the first decisions with their reasons. Both grow with the code. |