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.
This commit is contained in:
LGUG2Z committed 2026-10-28 07:20:37 -07:00
1 parent ac265de1e3
commit 331db681e2
41 files changed
+3234 -94

No files matched your search

+131 -14
View File
@@ -8,9 +8,9 @@ tested, without one.
This page describes that trait, who implements and calls it, where each of its rules is
enforced, the model of the desktop the window manager tiles, the backend that reaches KWin,
how an event about a window becomes a tile, how workspaces are the compositor's desktops, how
a message on the daemon's socket is answered, how subscribers are notified of both, what the
orders a message gives do, and how the NixOS module runs the daemon. It grows with the code:
each part of the daemon that is added has its place here.
a stack hides its windows, how a message on the daemon's socket is answered, how subscribers
are notified of both, what the orders a message gives do, and how the NixOS module runs the
daemon. It grows with the code: each part of the daemon that is added has its place here.
## Vocabulary
@@ -27,6 +27,13 @@ each part of the daemon that is added has its place here.
desktop of its own.
- **Container**: what a layout places. It gets one tile, and every window in it is put on
that tile.
- **Stack**: a container with more than one window. It has one tile, and the window in front
(the container's focused window) is in sight; the others are hidden.
- **Hidden window**: a window of a stack that is not in front, which komorebi has taken out of
sight ([`Backend::hide`]) and recorded in [`HIDDEN_WINDOWS`]. It is alive, not minimized, and
on its workspace.
- **Parking desktop**: the virtual desktop, named `komorebi-park`, that the KWin backend hides
windows on. It is not a workspace.
- **Layout**: the arrangement (BSP, columns, rows, ...) that turns a work area and a
number of containers into one rectangle, a **tile**, for each container.
- **Event**: what the compositor reports about a window: it was shown, destroyed, given
@@ -87,9 +94,9 @@ The desktop, as the window manager sees it, is two lists and a pointer:
- **The pointer**, a position if the compositor says where it is, and the **focus**, the id
of the window that has it.
A command is one of: move and resize a window, focus it, raise it, minimize it or bring it
back, close it, put the pointer in the middle of a rectangle, make desktops for the
workspaces, show a workspace on a monitor, and put a window on a workspace. The workspace a
A command is one of: move and resize a window, focus it, raise it, hide it or restore it,
minimize it or bring it back, close it, put the pointer in the middle of a rectangle, make
desktops for the workspaces, show a workspace on a monitor, and put a window on a workspace. The workspace a
window is on, and the one each monitor shows, are queries.
The window manager tiles a tree of four levels, each level a [`Ring`]: a list with one
@@ -103,8 +110,10 @@ the same thing at every level.
own, whether it takes the monitor's window-based offset, its containers, in order, and its
floating windows, which are in no container and which the layout does not tile.
- A **container** ([`Container`]) has its windows. A new window gets a container of its
own. A container can be locked, which keeps it at its index while others are inserted,
removed or swapped around it.
own, unless the window container behavior says to put it in the focused one. With more than
one window it is a stack: the focused window is in front and the others are hidden. A
container can be locked, which keeps it at its index while others are inserted, removed or
swapped around it.
- A **window** ([`Window`]) is a `Copy` handle that carries only the compositor's id.
Everything else about the window, and every change to it, goes through the backend.
@@ -224,6 +233,54 @@ window put on another desktop by something else (the window menu's "Move to Desk
and move come back from KWin as the same reports; the table records them when the command is
sent ([`Table::switch_commands`], [`Table::window_workspace_commands`]), so they raise nothing.
## Stacks
A container has one tile, so when it has more than one window the others have to be out of
sight, and out of the way of the pointer and the focus: the window manager hides them
([`Window::hide`]). Minimizing them would not do. KWin reports a minimize as the user's, and
the windows would be taken for ones the user does not want tiled. What komorebi uses is the one
thing KWin has that hides a window and leaves it alone: a virtual desktop nobody looks at, the
parking desktop. The reasons are in
[DESIGN.md](DESIGN.md#why-are-the-windows-behind-the-front-one-of-a-stack-moved-to-a-parking-desktop).
A container keeps its front window in sync with what is in sight ([`Container::add_window`],
[`Container::load_focused_window`]): the window that is added or focused is shown, and every
other one is hidden. Operations that change which window is in front, or which container a
window is in, end with that call: stacking and unstacking ([`Workspace::move_window_to_container`],
[`Workspace::new_container_for_focused_window`]), a window that closes
([`Workspace::remove_window`], which brings the next one forward and focuses it), a window that
is floated, and a focus change to a window that is behind ([`Workspace::focus_container_by_window`]).
[`Window::hide`] puts the window's id in [`HIDDEN_WINDOWS`] before it asks the backend, and
[`Window::restore`] takes it out, so that when the compositor reports something about the window
because of the hide the window manager knows who did it. A `Minimize` for a window in the set is
not the user's and changes nothing. On the way out, [`WindowManager::stop`] and the daemon's
`SIGINT` and `SIGTERM` handler restore every window in the set before the backend shuts down
([`WindowManager::restore_all_windows`]).
The KWin backend hides a window by putting it on the parking desktop. The table keeps for each
window whether it is parked and the desktop it came from ([`Table::hide_commands`],
[`Table::restore_commands`]): a hidden window is still on its workspace for every query
([`Table::window_workspace`]), a window put on another workspace while it is hidden is hidden
still and comes back there ([`Table::window_workspace_commands`]), and KWin's report that the
window moved to the parking desktop is not a `WorkspaceMove`. The parking desktop is made the
first time it is needed ([`NeedsPark`], `create_park_desktop` in [`kwin`]), by position, so
that it stays after the workspaces' desktops. The table checks that KWin still lists it before it
sends a window there, and asks for a new one when somebody removed it.
An application that raises a hidden window, or a click on it in the task manager, makes KWin
switch that monitor to the parking desktop. The table notices that a monitor shows it, sends the
monitor back to the desktop it showed before, and raises no `WorkspaceChange`; the window's own
`FocusChange` then brings it to the front of its stack.
KWin keeps its virtual desktops in `kwinrc` as soon as one is made, so a parking desktop that
komorebi does not remove stays for every later session. The backend removes it in `shutdown`,
after the restoring commands have reached the bridge. A daemon that was killed leaves it, with
windows on it: the first snapshot the next daemon gets lists a desktop with that name, which the
table treats as stale ([`Table::stale_park`]). It is never the parking desktop of the new run.
The snapshot sends the windows on it to the first workspace's desktop, and half a second later
the backend removes it (`sweep_stale_park`).
## The command socket
The daemon takes messages on a Unix socket, `komorebi.sock` in [`DATA_DIR`]
@@ -363,6 +420,24 @@ any other, so its events find it, and [`Workspace::update`] leaves it where it i
floated window goes is [`WindowManagementBehaviour::toggle_float_placement`]: by default it
stays where it is.
`StackWindow` puts the focused window and the window of the container in a direction in one
container ([`WindowManager::add_window_to_container`]): the focused window goes to the front of
that container, or, when the focused container is a stack and the other is not, the other
container's window goes into the stack. `UnstackWindow` takes the front window out of a stack
into a container of its own after it ([`WindowManager::remove_window_from_container`]), `StackAll`
puts every window of the workspace in one container ([`WindowManager::stack_all`]), and
`UnstackAll` takes them out again ([`WindowManager::unstack_all`]). Each ends with the workspace
tiled again, and the window that was in front has the focus.
A window that opens gets the behavior [`WindowManager::window_management_behaviour`] says for
its workspace: a container of its own (`Create`, the default), or a place in the focused
container (`Append`), and a floating window with the float override on. A workspace's own
[`Workspace::window_container_behaviour`] and [`Workspace::float_override`] win over the window
manager's, and `Append` on an empty workspace is `Create`. `ToggleWindowContainerBehaviour` and
`ToggleFloatOverride` flip the window manager's, and `ToggleWorkspaceWindowContainerBehaviour` and
`ToggleWorkspaceFloatOverride` the focused workspace's, which starts from the opposite of the
window manager's value the first time.
`ToggleLock` locks the focused container, or unlocks it ([`WindowManager::toggle_lock`]), and
`LockMonitorWorkspaceContainer` and `UnlockMonitorWorkspaceContainer` do the same for a
container given by its indices. A lock changes nothing until containers are inserted, removed or
@@ -522,10 +597,10 @@ module's unit.
operations on it (tile the workspace in front, tile every monitor, take a minimized
window out, move the focus, move the focused container, change the layout, resize or
promote the focused container, float a window, lock a container, set the padding of a
workspace, manage and unmanage a window, show a workspace, move a container to another
workspace, follow a workspace switch made by something else, name a workspace and find
it by its name, set the layout of a workspace that is not in front, focus another monitor,
and move containers and workspaces between monitors).
workspace, manage and unmanage a window, stack and unstack windows, show a workspace, move a
container to another workspace, follow a workspace switch made by something else, name a
workspace and find it by its name, set the layout of a workspace that is not in front, focus
another monitor, and move containers and workspaces between monitors).
- [`desktop`](../../komorebi/src/desktop.rs): loads the monitors and the open windows from
the backend.
- [`window_manager_event`](../../komorebi/src/window_manager_event.rs) and
@@ -537,7 +612,8 @@ module's unit.
- [`kwin`](../../komorebi/src/kwin/mod.rs): the KWin backend, its D-Bus service and the held
call; [`kwin::state`](../../komorebi/src/kwin/state.rs), the table;
[`kwin::kwinrc`](../../komorebi/src/kwin/kwinrc.rs), the editor of the user's `kwinrc`, which
keeps the values it changes and puts them back; and
keeps the values it changes and puts them back; the parking desktop is made, swept and removed
in `kwin` and tracked in `kwin::state`; and
[`bridge.js`](../../komorebi/src/kwin/bridge.js), the bridge.
- [`process_command`](../../komorebi/src/process_command.rs): the thread that listens on the
socket, and what the window manager does with each message.
@@ -583,6 +659,10 @@ the fake. The window manager is its only caller, through [`backend`]. The contra
backend asked for a workspace that has no desktop makes the desktops up to it
(`ensure_workspaces`). The compositor shows and hides the windows of the desktops, and a
backend reports a switch or a move it did not make as an event.
- A hidden window (`hide`) is out of sight, alive, not minimized, and on the workspace it was
on until `restore`: `window_workspace` still names that workspace, and
`set_window_workspace` changes where it comes back to, not where it is hidden. Only the back of
a stack is hidden: nothing is hidden to leave a workspace.
- `shutdown`, `is_window`, `window_rect` and `monitor_from_point` have defaults, written in
terms of the queries. An implementor should not need to override them, except `shutdown`
when it created something in the compositor that has to be given up.
@@ -595,7 +675,7 @@ the fake. The window manager is its only caller, through [`backend`]. The contra
| A backend can be shared between threads | type system: `Backend: Send + Sync + 'static` | `compile_fail,E0277` on [`Backend`] | none |
| The window manager asks for a backend that was never installed | runtime error: [`backend`] panics, naming [`set_backend`] and [`with_backend`] | `# Panics` on [`backend`] | none |
| A test's backend does not outlive the test | framework path: [`with_backend`] restores the previous one on drop | `with_backend_puts_the_previous_backend_back_when_the_closure_panics` | none |
| A command about a missing window is an error, not a panic | test | `a_command_about_a_window_nobody_opened_is_an_error` and `a_command_about_a_closed_window_is_an_error` against the fake, `a_command_about_a_window_the_table_does_not_know_is_an_error_and_sends_nothing` against the KWin backend | none |
| A command about a missing window is an error, not a panic | test | `a_command_about_a_window_nobody_opened_is_an_error`, `a_command_about_a_closed_window_is_an_error` and `hiding_or_restoring_a_window_nobody_opened_is_an_error` against the fake, `a_command_about_a_window_the_table_does_not_know_is_an_error_and_sends_nothing` against the KWin backend | none |
| A locked container keeps its index | framework path: a [`Workspace`] inserts, removes and swaps its containers through `LockableSequence` | `test_locked_containers_with_new_window`, `test_locked_containers_remove_window`, `a_window_that_opens_does_not_push_a_locked_container_from_its_index` | `containers_mut()` is the `VecDeque` itself |
| A window komorebi does not manage is never moved | framework path: `handle_event` asks [`Window::should_manage`] before it acts on any event but a destroy | `dialogs_and_other_non_normal_windows_are_left_alone`, `an_ignore_rule_keeps_a_window_unmanaged` | `ManageRule` |
| A window the user unmanaged stays out of the layout until it is managed again | framework path: `handle_event` checks the list of unmanaged windows before it acts on any event but a removal | `unmanage_takes_the_focused_window_out_until_manage_takes_it_back` | none |
@@ -630,6 +710,15 @@ the fake. The window manager is its only caller, through [`backend`]. The contra
| A workspace is closed only when it has no window and no name and is not the monitor's last | framework path: the `CloseWorkspace` arm of [`WindowManager::process_command`] checks all three | `new_workspace_adds_one_and_close_workspace_removes_it_when_it_is_empty_and_unnamed` | none |
| The focus and a move at the edge of a monitor go to the monitor on that side, and fail only when there is none | framework path: the `None` arms of [`WindowManager::focus_container_in_direction`] and [`WindowManager::move_container_in_direction`] | `the_focus_crosses_to_the_monitor_on_that_side`, `a_move_at_the_edge_of_a_monitor_swaps_with_the_window_on_the_next_one_by_default`, `focus_towards_a_side_with_no_window_is_an_error_and_changes_nothing` | `NoOp` keeps a move on its monitor |
| A window shown or focused on another monitor focuses that monitor, and nothing else does | framework path: `handle_event` focuses the monitor of a `Show` or `FocusChange` before it acts on it | `a_window_that_opens_on_the_monitor_that_is_not_focused_focuses_it`, `a_scrolling_strip_on_the_next_monitor_over_does_not_take_focus_with_it` | none |
| Only the window in front of a stack is in sight | framework path: [`Container::add_window`] and [`Container::load_focused_window`] hide every window of the container but the focused one, and every operation that changes the front ends with the call | `a_window_added_to_a_container_is_in_front_and_the_others_are_hidden`, `loading_the_focused_window_shows_it_and_hides_the_rest`, `stacking_puts_two_windows_in_one_container_and_hides_the_one_behind`, `vm-stacks` ("exactly one window is on it") | none |
| A hidden window is still on its workspace, and is not reported as moved | framework path: the table keeps the desktop a window came from, and a move to the parking desktop is its own | `parking_a_window_hides_it_without_unmanaging_it`, `komorebis_own_move_and_its_park_and_restore_raise_nothing_new`, `a_window_is_put_on_a_workspace_by_putting_it_on_its_desktop` | none |
| What the compositor reports about a window komorebi hid is not taken for the user's doing | framework path: [`Window::hide`] records the window in [`HIDDEN_WINDOWS`] before it asks the backend, and the `Minimize` arm of `handle_event` checks it | `a_minimize_komorebi_asked_for_is_not_mistaken_for_the_user`, `a_minimize_the_user_asked_for_takes_the_window_out_of_the_layout` | none |
| Closing the window in front of a stack brings the next one forward | framework path: [`Workspace::remove_window`] shows the container's new front window and focuses it | `closing_the_window_in_front_of_a_stack_brings_the_next_one_forward`, `vm-stacks` ("closing the window in view") | none |
| The back of a stack stays hidden when its workspace is shown again | framework path: [`Workspace::restore`] restores the front window of each container and no other | `the_back_of_a_stack_stays_hidden_across_a_workspace_round_trip`, `vm-stacks` ("a workspace round trip") | none |
| A window is never sent to a parking desktop that is not there | framework path: [`Table::hide_commands`] asks for a new one unless KWin lists the one it made | `a_parking_desktop_that_has_gone_is_made_again_not_sent_windows` | none |
| A monitor raised onto the parking desktop is sent back | framework path: the table sends the monitor back to the desktop it showed before | `following_a_hidden_window_to_the_parking_desktop_sends_that_output_back` | none |
| A clean stop leaves no window hidden and no parking desktop | framework path: [`WindowManager::stop`] and the signal handler restore every hidden window, and the backend's `shutdown` removes the desktop after the restoring commands have gone out | `restoring_every_window_brings_back_the_hidden_ones_unless_it_is_told_to_ignore_that`, `vm-stacks` ("a clean stop puts every window back") | `SIGKILL`, and `StopIgnoreRestore`, which restores nothing |
| A parking desktop a dead daemon left is swept by the next one, and its windows go home | startup check: the first snapshot marks it stale, sends its windows to the first workspace's desktop, and the backend removes it | `a_parking_desktop_left_by_a_crashed_run_is_swept`, `a_stale_parking_desktop_is_not_the_one_windows_are_hidden_on`, `vm-stacks` ("a crash leaves a parking desktop") | none |
| Moving the focus moves no window | test | `focus_gives_the_focus_to_the_window_on_that_side_and_moves_nothing`, `vm-core-e2e` ("moving the focus moved no window") | none |
| A subscriber that is gone is dropped, not retried | test | `a_subscriber_that_is_gone_is_dropped_and_not_tried_again` | none |
| The bridge holds no window manager logic | convention, with every decision about an event in the table, which the `kwin::state` unit tests pin | the unit tests in `komorebi/src/kwin/state.rs` | none |
@@ -767,6 +856,10 @@ A window is shown, and ends up on a tile:
[`komorebi/tests/monitors.rs`](../../komorebi/tests/monitors.rs), two monitors: crossing from
one to the other, the monitor commands and `EagerFocus`; [`komorebi/src/kwin/kwinrc.rs`](../../komorebi/src/kwin/kwinrc.rs), the
`kwinrc` editor and its tests.
- [`komorebi/tests/stacks.rs`](../../komorebi/tests/stacks.rs): stacking, unstacking and the windows
a stack hides, the behavior of new windows and the float override, against the fake;
[`nix/tests/vm/suites/stacks`](../../nix/tests/vm/suites/stacks/test.py), the same in a real
KWin, with the parking desktop, a crash and a stop.
- [`nix/tests/vm/suites/workspace-switch`](../../nix/tests/vm/suites/workspace-switch/test.py):
workspaces as a real KWin's desktops, switched by `komorebic` and by KWin;
[`nix/tests/vm/suites/kwin-contract`](../../nix/tests/vm/suites/kwin-contract/test.py), the
@@ -798,6 +891,30 @@ A window is shown, and ends up on a tile:
[`MatchingRule`]: ../../komorebi/src/core/config_generation.rs
[`ApplicationIdentifier`]: ../../komorebi/src/core/mod.rs
[`Window::set_position`]: ../../komorebi/src/window.rs
[`Window::hide`]: ../../komorebi/src/window.rs
[`Window::restore`]: ../../komorebi/src/window.rs
[`HIDDEN_WINDOWS`]: ../../komorebi/src/lib.rs
[`Container::add_window`]: ../../komorebi/src/container.rs
[`Container::load_focused_window`]: ../../komorebi/src/container.rs
[`Workspace::move_window_to_container`]: ../../komorebi/src/workspace.rs
[`Workspace::new_container_for_focused_window`]: ../../komorebi/src/workspace.rs
[`Workspace::remove_window`]: ../../komorebi/src/workspace.rs
[`Workspace::focus_container_by_window`]: ../../komorebi/src/workspace.rs
[`Workspace::restore`]: ../../komorebi/src/workspace.rs
[`Workspace::window_container_behaviour`]: ../../komorebi/src/workspace.rs
[`Workspace::float_override`]: ../../komorebi/src/workspace.rs
[`WindowManager::add_window_to_container`]: ../../komorebi/src/window_manager.rs
[`WindowManager::remove_window_from_container`]: ../../komorebi/src/window_manager.rs
[`WindowManager::stack_all`]: ../../komorebi/src/window_manager.rs
[`WindowManager::unstack_all`]: ../../komorebi/src/window_manager.rs
[`WindowManager::restore_all_windows`]: ../../komorebi/src/window_manager.rs
[`WindowManager::window_management_behaviour`]: ../../komorebi/src/window_manager.rs
[`Backend::hide`]: ../../komorebi/src/backend/mod.rs
[`Table::hide_commands`]: ../../komorebi/src/kwin/state.rs
[`Table::restore_commands`]: ../../komorebi/src/kwin/state.rs
[`Table::window_workspace`]: ../../komorebi/src/kwin/state.rs
[`Table::stale_park`]: ../../komorebi/src/kwin/state.rs
[`NeedsPark`]: ../../komorebi/src/kwin/state.rs
[`Workspace::new_container_for_window`]: ../../komorebi/src/workspace.rs
[`WindowManager`]: ../../komorebi/src/window_manager.rs
[`WindowManager::process_event`]: ../../komorebi/src/process_event.rs
+37
View File
@@ -259,3 +259,40 @@ plain ini, which komorebi changes line by line, and asks KWin to reload its conf
It is the user's setting, so the value komorebi found is kept in a backup file and put back
when komorebi stops; a backup a crash left behind keeps the value from before the first run,
and the next run puts it back.
## Why are the windows behind the front one of a stack moved to a parking desktop?
Because a container has one tile, so the windows of a stack that are not in front have to be out
of sight, and a virtual desktop nobody looks at was the one way to do that which the spikes found
to cost no focus change. The first spike hid six tiled windows and showed them again three ways.
Minimizing
them gave the geometry back exactly, but KWin picked a new active window as each one minimized,
two focus events nobody asked for. Moving them to a virtual desktop of their own gave no focus
event and the geometry back exactly. Moving them off the screen worked too, since KWin does not
clamp a scripted move, but the windows stay mapped on the current desktop, in the window switcher,
the overview and the task manager, so it was not offered. KWin has nothing else: `Window.hidden`
cannot be set by a script. The spike's source reading, KWin 6.8.1, is in
[PLATFORM.md](PLATFORM.md#the-parking-desktop). The other platforms have a setting that chooses
how windows are hidden; on KDE there is one way, and so no such setting.
The cost is that KWin keeps a virtual desktop in `kwinrc` as soon as it is made. A run that failed
after making the parking desktop left it there for every later session. So komorebi removes the
desktop when it stops, after the commands that bring the windows back have reached the bridge, and
the first snapshot of the next run finds a leftover, sends the windows on it to the first
workspace's desktop and removes it. A leftover is never used as the parking desktop of the new
run, since it is about to be removed and anything parked on it would go with it; the new run makes
its own the first time it needs one. Before each hide the table also checks that the desktop it
made is still listed, because somebody can remove it in System Settings, and a window sent to a
desktop that is not there has nowhere to go and nothing says so.
Activating a window that is on another desktop makes KWin switch that output to the window's
desktop (see [PLATFORM.md](PLATFORM.md#per-output-virtual-desktops)), so a click on a hidden
window in the task manager would leave the monitor showing the parking desktop, which has nothing
on it but hidden windows. The table sends the monitor straight back to the desktop it showed
before, and the window's own focus change then brings it to the front of its stack.
komorebi keeps a table of the windows it hid, [`HIDDEN_WINDOWS`](../../komorebi/src/lib.rs), and
records a window in it before it asks the backend to hide it. What the compositor reports about a
hidden window (a minimize, a move to another desktop) is the echo of a command komorebi sent, and
the window manager has to be able to tell that from the user's own: a window that the user
minimizes leaves the layout, and one komorebi hid does not.
+48 -11
View File
@@ -21,6 +21,8 @@ was measured with KWin 6.8.1, Plasma 6.8.1 and Qt 6.12.0 from nixpkgs `d3b13ad`
- **Output**: KWin's name for a monitor.
- **Desktop**: one of KWin's virtual desktops. Each output shows one; komorebi's workspace `i`
is desktop `i`.
- **Parking desktop**: the desktop named `komorebi-park`, which komorebi makes to hide the back of
a stack on. It is not a workspace.
- **Headless KWin**: `kwin_wayland --virtual`, a KWin with virtual outputs and no display,
which the VM tests run ([vm-tests.md](vm-tests.md)).
@@ -58,6 +60,29 @@ outputs:
- Desktops are global: every output has the same desktops, with the same names, and each output
shows one of them. The ids of the desktops are UUIDs; the bridge names them by id.
### The parking desktop
Why komorebi hides windows on a desktop of its own is in
[DESIGN.md](DESIGN.md#why-are-the-windows-behind-the-front-one-of-a-stack-moved-to-a-parking-desktop).
What it relies on KWin for, at time of writing (2026-10-27), measured by the spikes on KWin
6.8.1 (nixpkgs `d3b13ad`, 2026-10-24) unless it says otherwise. The VM test `vm-stacks` runs
komorebi's use of them in a headless KWin:
- A window on another desktop of its output is out of sight, and moving it there and back gives
its frame back exactly. Hiding six windows this way raised no `activated` event; minimizing
them raised two.
- KWin saves a virtual desktop in `kwinrc` as soon as it is made. A desktop that komorebi made
and did not remove, because it was killed, is in every later session.
- Activating a window that is on another desktop of its output switches that output to the
window's desktop (see [Per-output virtual desktops](#per-output-virtual-desktops)), which for a
hidden window is the parking desktop.
- `Window.hidden` is read-only to a script, and the only thing in KWin's 6.8.1 sources that sets
it is a layer-shell window (an auto-hide panel). This is a reading of the sources, not a
measurement.
- A window on the parking desktop is still a window of the session. Whether Plasma's task manager
lists it depends on the task manager's setting for showing the windows of the current desktop
only; the VM tests have no panel, so this is not measured.
### Wayland
komorebi runs in a Plasma Wayland session. There is no X11 session of Plasma 6.8 to run it in.
@@ -107,8 +132,15 @@ reload its configuration. If a workspace has no desktop, it creates the missing
`org.kde.KWin.VirtualDesktopManager`, named "Workspace 1", "Workspace 2" and so on. A desktop
that is already there keeps its name.
Every command of the window manager (move and resize, focus, raise, minimize, bring back or
close a window, show a workspace on an output, put a window on a workspace) is queued for the
When a stack hides a window for the first time, it makes one more desktop, named `komorebi-park`,
after the desktops of the workspaces (the missing workspace desktops are made by position, so that
it stays last), and moves the window there. The desktop is not a workspace: komorebi counts the
workspaces without it, and a window on it is on the workspace it will come back to. It checks that
KWin still lists the desktop before it sends another window there.
Every command of the window manager (move and resize, focus, raise, hide or restore, minimize,
bring back or close a window, show a workspace on an output, put a window on a workspace) is
queued for the
bridge, which gets the queue as the answer to its held call and carries the commands out in
KWin, in order. The script API cannot move the pointer, so
when the pointer follows the focus komorebi invokes KWin's own "Move Mouse to Focus" shortcut,
@@ -128,15 +160,20 @@ an owner again; the VM test `vm-kwin-restart` restarts KWin twice under a runnin
#### What komorebi leaves behind
When it is stopped with `SIGINT`, `SIGTERM` or a `Stop` message on its socket, it puts back
the value `PerOutputVirtualDesktops` had in `kwinrc` (or removes the key, when the user had
none) and asks KWin to reload its configuration, asks KWin to unload the script, closes an
empty connection to each subscriber, and removes the socket. The desktops it created stay:
they are the user's desktops from then on. The file `bridge.js` stays in the runtime
When it is stopped with `SIGINT`, `SIGTERM` or a `Stop` message on its socket, it brings back
the windows it hid, waits until the commands that do so have reached the bridge, removes the
parking desktop, puts back the value `PerOutputVirtualDesktops` had in `kwinrc` (or removes the
key, when the user had none) and asks KWin to reload its configuration, asks KWin to unload the
script, closes an empty connection to each subscriber, and removes the socket. The desktops it
created for workspaces stay: they are the user's desktops from then on. A `StopIgnoreRestore`
message stops it the same way, except that it does not bring the windows back: the parking desktop
is removed all the same. The file `bridge.js` stays in the runtime
directory, which is removed at logout. A daemon that is killed leaves the script running in
KWin, reporting to nobody, the socket file in the runtime directory, and per-output desktops
on, until the next start replaces the script and the socket, and its stop puts the setting
back (the backup in the runtime directory keeps the user's value), or the session ends.
KWin, reporting to nobody, the socket file in the runtime directory, per-output desktops
on, and the parking desktop with the hidden windows on it, until the next start replaces the
script and the socket, sends the windows on the parking desktop to the first workspace's desktop
and removes the desktop, and its stop puts the setting back (the backup in the runtime
directory keeps the user's value), or the session ends.
### A headless KWin
@@ -182,7 +219,7 @@ What komorebi calls:
| `org.freedesktop.DBus` | `/org/freedesktop/DBus` | `org.freedesktop.DBus` | `AddMatch(s)`, for the signal `NameOwnerChanged` | at start, to see KWin leave the bus and come back |
| `org.kde.kglobalaccel` | `/component/kwin` | `org.kde.kglobalaccel.Component` | `invokeShortcut(s)`, with `MoveMouseToFocus` | when the pointer follows the focus |
| `org.kde.KWin` | `/KWin` | `org.kde.KWin` | `reconfigure()` | after komorebi changed `kwinrc`, at start and at exit |
| `org.kde.KWin` | `/VirtualDesktopManager` | `org.kde.KWin.VirtualDesktopManager` | the property `desktops`, `createDesktop(us)`, `setDesktopName(ss)` | when a workspace has no desktop, and at start |
| `org.kde.KWin` | `/VirtualDesktopManager` | `org.kde.KWin.VirtualDesktopManager` | the properties `desktops` and `count`, `createDesktop(us)`, `setDesktopName(ss)`, `removeDesktop(s)` | when a workspace has no desktop, and at start; `createDesktop` also for the parking desktop, the first time a window is hidden, and `removeDesktop` for it when komorebi stops and for one a killed run left |
The property `desktops` is introspected as `a(iss)`, a position, an id and a name for each
desktop, and the value on the wire is `a(uss)`: komorebi reads it as that. It is read uncached,
+9 -6
View File
@@ -118,17 +118,18 @@ the run.
clients.
- `start_komorebi(*args)` starts the daemon in the session, with the module's
`execStart` and `args` after it (not `--log-level`, which `execStart` has),
`stop_komorebi()` stops it with `SIGTERM`, `komorebi_log()` returns its log
since it was last started, and `script_loaded()` asks KWin whether it runs
the bridge.
`stop_komorebi()` stops it with `SIGTERM`, `kill_komorebi()` kills it with
`SIGKILL`, as a crash does, `komorebi_log()` returns its log since it was
last started, and `script_loaded()` asks KWin whether it runs the bridge.
`restart_kwin()` stops the session's KWin and starts a new one on the same
bus, as when the compositor of a running session crashes, and waits for it.
- `komorebic(*args)` runs `komorebic` in the session and returns what it
printed, failing the test if it fails. `state()` is the daemon's state as
`komorebic state` prints it, `managed(workspace)` the number of windows the
daemon has on a workspace of the first monitor, `managed_all()` the number it
has on every workspace of every monitor (floating windows too), and
`focused_title(workspace)` the title of the window it has focused there.
has on every workspace of every monitor (floating windows too),
`containers(workspace)` the titles of the windows of each of its containers,
and `focused_title(workspace)` the title of the window it has focused there.
- `daemon` reads the daemon's view of the desktop from that log, at the debug
level the nodes set: `daemon.events(log)` lists the window events it handled,
in order, `daemon.window_ids(log)` maps a window's title to the daemon's id
@@ -136,7 +137,9 @@ the run.
for, for each window.
- `desk(wid)` is the number of the desktop a window is on and `shown()` the one
KWin shows, both counted from 1 as `kdotool` counts, `desktops()` how many
desktops KWin has, and `kwinrc(group, key)` a value of the user's `kwinrc`.
desktops KWin has, `desktop_names()` their names in order (the parking desktop
of a stack is the one named `komorebi-park`), and `kwinrc(group, key)` a value
of the user's `kwinrc`.
- `kwin_script(name, source, keep=)` runs a KWin script and returns the lines it
reported: the script calls `report(...)`, which `print`s a line marked with
`name` to KWin's log, and ends with `report("done")`. A script that is kept