From 96332b2578f77916496e809858014aab61444ba2 Mon Sep 17 00:00:00 2001 From: LGUG2Z Date: Sat, 31 Oct 2026 19:13:35 -0700 Subject: [PATCH 1/5] refactor(windows): PlatformMonitorId next to PlatformWindowId; monitor_idx_from_current_pos has KDE's text komorebi-core gets pub type PlatformMonitorId

=

::Id, the monitor counterpart of PlatformWindowId (blocker 5 of core-model.md section 18). The Windows daemon aliases it (window::PlatformMonitorId, the shared MonitorId) and gets window::monitor_id_at_cursor() like KDE's, so monitor_idx_from_current_pos reads: ask the monitor id at the cursor, compare monitor.id == monitor_id, and only then the Windows-only stale-handle fallback (WindowsApi::monitor(monitor_id.to_hmonitor())). Same calls as before (cursor_pos, monitor_from_point), in the same order. Not a behaviour change. kfde: the alias is generic over MonitorPlatform; KDE and macOS can alias it the same way. Verified: tools/fast-check native (core tests), bare Windows clippy -D warnings, KDE check + lib tests, macOS fake-CC type-check PASS; e2e: commands (monitor-from-cursor commands), hotplug scenarios if any. --- crates/komorebi-core/src/monitor.rs | 3 +++ komorebi/src/window.rs | 11 +++++++++++ komorebi/src/window_manager.rs | 7 ++++--- 3 files changed, 18 insertions(+), 3 deletions(-) diff --git a/crates/komorebi-core/src/monitor.rs b/crates/komorebi-core/src/monitor.rs index 27644982..9e279de7 100644 --- a/crates/komorebi-core/src/monitor.rs +++ b/crates/komorebi-core/src/monitor.rs @@ -23,6 +23,9 @@ use serde::de::DeserializeOwned; use std::collections::VecDeque; use std::fmt::Debug; +/// What names a monitor of platform `P`, as [`PlatformWindowId`] does for a window +pub type PlatformMonitorId

=

::Id; + /// What the shared [`Monitor`] needs of a platform, besides what its workspaces need. pub trait MonitorPlatform: WorkspacePlatform { /// What names a monitor: `isize` on Windows (a monitor handle), `u32` on KDE. diff --git a/komorebi/src/window.rs b/komorebi/src/window.rs index 1d825d0b..278f908f 100644 --- a/komorebi/src/window.rs +++ b/komorebi/src/window.rs @@ -74,6 +74,17 @@ pub fn foreground_window_id() -> Option { WindowsApi::foreground_window().ok() } +/// What names a monitor: the type the shared monitor and window manager code compares ids as +pub type PlatformMonitorId = komorebi_core::PlatformMonitorId; + +/// The monitor the pointer is on, if the system says (the nearest one when it is on none) +pub fn monitor_id_at_cursor() -> Option { + let point = WindowsApi::cursor_pos().ok()?; + Some(PlatformMonitorId::from_hmonitor( + WindowsApi::monitor_from_point(point), + )) +} + /// Where the pointer is, if the system says pub fn cursor_position() -> Option<(i32, i32)> { WindowsApi::cursor_pos() diff --git a/komorebi/src/window_manager.rs b/komorebi/src/window_manager.rs index 2abcb4f4..e3d66a57 100644 --- a/komorebi/src/window_manager.rs +++ b/komorebi/src/window_manager.rs @@ -74,6 +74,7 @@ use crate::static_config::StaticConfig; use crate::static_config::StaticConfigExt; use crate::transparency_manager; use crate::window::Window; +use crate::window::monitor_id_at_cursor; use crate::window_manager_event::WindowManagerEvent; use crate::windows_api::WindowsApi; use crate::winevent_listener; @@ -3786,17 +3787,17 @@ impl WindowManager { } pub fn monitor_idx_from_current_pos(&mut self) -> Option { - let hmonitor = WindowsApi::monitor_from_point(WindowsApi::cursor_pos().ok()?); + let monitor_id = monitor_id_at_cursor()?; for (i, monitor) in self.monitors().iter().enumerate() { - if monitor.id.to_hmonitor() == hmonitor { + if monitor.id == monitor_id { return Option::from(i); } } // our hmonitor might be stale, so if we didn't return above, try querying via the latest // info taken from win32_display_data and update our hmonitor while we're at it - if let Ok(latest) = WindowsApi::monitor(hmonitor) { + if let Ok(latest) = WindowsApi::monitor(monitor_id.to_hmonitor()) { for (i, monitor) in self.monitors_mut().iter_mut().enumerate() { if monitor.extra.device_id == latest.extra.device_id { monitor.id = latest.id; From 911ce46ce14bf45050c381fcd8af61748b1d7a0d Mon Sep 17 00:00:00 2001 From: LGUG2Z Date: Sat, 31 Oct 2026 19:32:58 -0700 Subject: [PATCH 2/5] fix(deny): clarify the license of the workspace crates the Windows and KDE deny checks see The root and KDE deny.toml only clarified the old crate names, so cargo deny failed with unlicensed for the crates of the unified workspace. The root deny.toml gets entries (LicenseRef-Komorebi-2.0, as for the existing ones) for komorebi-backend, -bar-core, -collections, -config, -core, -protocol, -settings, -transport, komorebic-core, komorebi-e2e-agent and komorebi-testwin; the KDE one for the same crates that it sees. The KDE deny check also excludes komorebi-bar-core, which is not a KDE dependency and brings the git egui-phosphor source that the KDE policy does not allow. Verified: cargo deny --offline --workspace with the flake's --exclude lists and `check --config bans licenses sources` (nix shell nixpkgs#cargo-deny): root, KDE and macOS: bans ok, licenses ok, sources ok (before: licenses FAILED for root and KDE, sources FAILED for KDE); taplo --check passes on both files. Not built in nix. --- deny.toml | 55 ++++++++++++++++++++++++++++++++++++++ komorebi-for-kde/deny.toml | 51 +++++++++++++++++++++++++++++++++++ komorebi-for-kde/flake.nix | 1 + 3 files changed, 107 insertions(+) diff --git a/deny.toml b/deny.toml index 61f56194..65b0694b 100644 --- a/deny.toml +++ b/deny.toml @@ -97,6 +97,61 @@ crate = "komorebi-shortcuts" expression = "LicenseRef-Komorebi-2.0" license-files = [] +[[licenses.clarify]] +crate = "komorebi-backend" +expression = "LicenseRef-Komorebi-2.0" +license-files = [] + +[[licenses.clarify]] +crate = "komorebi-bar-core" +expression = "LicenseRef-Komorebi-2.0" +license-files = [] + +[[licenses.clarify]] +crate = "komorebi-collections" +expression = "LicenseRef-Komorebi-2.0" +license-files = [] + +[[licenses.clarify]] +crate = "komorebi-config" +expression = "LicenseRef-Komorebi-2.0" +license-files = [] + +[[licenses.clarify]] +crate = "komorebi-core" +expression = "LicenseRef-Komorebi-2.0" +license-files = [] + +[[licenses.clarify]] +crate = "komorebi-e2e-agent" +expression = "LicenseRef-Komorebi-2.0" +license-files = [] + +[[licenses.clarify]] +crate = "komorebi-protocol" +expression = "LicenseRef-Komorebi-2.0" +license-files = [] + +[[licenses.clarify]] +crate = "komorebi-settings" +expression = "LicenseRef-Komorebi-2.0" +license-files = [] + +[[licenses.clarify]] +crate = "komorebi-testwin" +expression = "LicenseRef-Komorebi-2.0" +license-files = [] + +[[licenses.clarify]] +crate = "komorebi-transport" +expression = "LicenseRef-Komorebi-2.0" +license-files = [] + +[[licenses.clarify]] +crate = "komorebic-core" +expression = "LicenseRef-Komorebi-2.0" +license-files = [] + [[licenses.clarify]] crate = "whkd-core" expression = "LicenseRef-Komorebi-2.0" diff --git a/komorebi-for-kde/deny.toml b/komorebi-for-kde/deny.toml index eab867dd..a474e33a 100644 --- a/komorebi-for-kde/deny.toml +++ b/komorebi-for-kde/deny.toml @@ -88,6 +88,57 @@ crate = "base16-egui-themes" expression = "MIT" license-files = [] + +[[licenses.clarify]] +crate = "komorebi-backend" +expression = "LicenseRef-Komorebi-2.0" +license-files = [] + +[[licenses.clarify]] +crate = "komorebi-client" +expression = "LicenseRef-Komorebi-2.0" +license-files = [] + +[[licenses.clarify]] +crate = "komorebi-collections" +expression = "LicenseRef-Komorebi-2.0" +license-files = [] + +[[licenses.clarify]] +crate = "komorebi-config" +expression = "LicenseRef-Komorebi-2.0" +license-files = [] + +[[licenses.clarify]] +crate = "komorebi-core" +expression = "LicenseRef-Komorebi-2.0" +license-files = [] + +[[licenses.clarify]] +crate = "komorebi-protocol" +expression = "LicenseRef-Komorebi-2.0" +license-files = [] + +[[licenses.clarify]] +crate = "komorebi-settings" +expression = "LicenseRef-Komorebi-2.0" +license-files = [] + +[[licenses.clarify]] +crate = "komorebi-transport" +expression = "LicenseRef-Komorebi-2.0" +license-files = [] + +[[licenses.clarify]] +crate = "komorebic" +expression = "LicenseRef-Komorebi-2.0" +license-files = [] + +[[licenses.clarify]] +crate = "komorebic-core" +expression = "LicenseRef-Komorebi-2.0" +license-files = [] + [bans] multiple-versions = "allow" wildcards = "allow" diff --git a/komorebi-for-kde/flake.nix b/komorebi-for-kde/flake.nix index 13dab98e..a1c4fc83 100644 --- a/komorebi-for-kde/flake.nix +++ b/komorebi-for-kde/flake.nix @@ -374,6 +374,7 @@ cargoDenyExtraArgs = "--workspace " + lib.concatMapStringsSep " " (p: "--exclude ${p}") [ + "komorebi-bar-core" "komorebi-windows" "komorebi-gui" "komorebic-no-console" From 1944fd67c462d3e926f74b0e6e7a240a830c345e Mon Sep 17 00:00:00 2001 From: LGUG2Z Date: Sat, 31 Oct 2026 19:39:25 -0700 Subject: [PATCH 3/5] refactor(windows): promote-focus on a custom layout is a hook of WorkspacePlatform The Windows promote_focus_to_front focused the first column of a custom layout that has no primary column (first_container_idx(primary_idx().unwrap_or(0))) where the shared primary_container_idx fails for it; this was one of the Layout::Custom differences of core-model.md section 18. WorkspacePlatform gets promote_focus_container_idx(layout) -> usize, defaulting to primary_container_idx(layout).unwrap_or(0), so a shared promote_focus_to_front can call it on every platform; the Windows platform overrides it with the exact expression it had (default layouts 0, custom layouts the first container of the primary column, else of column 0). window_manager.rs calls the hook. A core test pins the default for the default layouts. Not a behaviour change on Windows (the same expression, moved). KDE and macOS see a new defaulted trait method only. Verified: tools/fast-check native (core tests), bare Windows clippy -D warnings, KDE check + lib tests, macOS fake-CC type-check PASS; e2e: commands (promote-focus), layouts (custom layout). --- crates/komorebi-core/src/workspace.rs | 16 ++++++++++++++++ komorebi/src/window_manager.rs | 7 +++---- komorebi/src/workspace.rs | 10 ++++++++++ 3 files changed, 29 insertions(+), 4 deletions(-) diff --git a/crates/komorebi-core/src/workspace.rs b/crates/komorebi-core/src/workspace.rs index 9462957d..bc46e047 100644 --- a/crates/komorebi-core/src/workspace.rs +++ b/crates/komorebi-core/src/workspace.rs @@ -164,6 +164,14 @@ pub trait WorkspacePlatform: Sized + Clone + std::fmt::Debug + PartialEq + 'stat Ok(0) } + /// The index of the container that `promote-focus` focuses: the primary position of the layout, + /// and the first container when the layout has none (a custom layout without a primary + /// column). Where [`WorkspacePlatform::primary_container_idx`] fails, the default falls back + /// to 0. + fn promote_focus_container_idx(layout: &Layout) -> usize { + Self::primary_container_idx(layout).unwrap_or(0) + } + /// Gives the maximized window back to the layout, for the platforms where that is something /// to tell the window (KDE asks the compositor; on Windows there is nothing to do). fn unmaximize_window(_window: &Self::Window) -> eyre::Result<()> { @@ -2190,4 +2198,12 @@ mod tests { assert!(workspace.tile); assert_eq!(workspace.layout, Layout::Default(DefaultLayout::BSP)); } + + #[test] + fn promote_focus_falls_back_to_the_primary_position_and_then_to_zero() { + assert_eq!( + Plat::promote_focus_container_idx(&Layout::Default(DefaultLayout::BSP)), + 0 + ); + } } diff --git a/komorebi/src/window_manager.rs b/komorebi/src/window_manager.rs index e3d66a57..9551ce3a 100644 --- a/komorebi/src/window_manager.rs +++ b/komorebi/src/window_manager.rs @@ -48,8 +48,10 @@ use crate::core::WindowContainerBehaviour; use crate::core::WindowManagementBehaviour; use crate::core::config_generation::MatchingRule; use crate::windows_backend::backend; +use crate::workspace::WindowsPlatform; use komorebi_backend::WindowId; use komorebi_core::ContainerWindow; +use komorebi_core::WorkspacePlatform; use crate::CrossBoundaryBehaviour; use crate::DATA_DIR; @@ -3048,10 +3050,7 @@ impl WindowManager { tracing::info!("promoting focus"); - let target_idx = match &workspace.layout { - Layout::Default(_) => 0, - Layout::Custom(custom) => custom.first_container_idx(custom.primary_idx().unwrap_or(0)), - }; + let target_idx = WindowsPlatform::promote_focus_container_idx(&workspace.layout); workspace.focus_container(target_idx); self.update_focused_workspace(self.mouse_follows_focus, true) diff --git a/komorebi/src/workspace.rs b/komorebi/src/workspace.rs index 6189503c..667dc9e2 100644 --- a/komorebi/src/workspace.rs +++ b/komorebi/src/workspace.rs @@ -86,6 +86,16 @@ impl komorebi_core::WorkspacePlatform for WindowsPlatform { }) } + /// `promote-focus` on a custom layout without a primary column focuses its first column rather + /// than failing, which is what the Windows daemon always did; the other layouts have the + /// primary position first. + fn promote_focus_container_idx(layout: &Layout) -> usize { + match layout { + Layout::Default(_) => 0, + Layout::Custom(custom) => custom.first_container_idx(custom.primary_idx().unwrap_or(0)), + } + } + fn begin_update(_workspace: &mut Workspace) -> eyre::Result { if !INITIAL_CONFIGURATION_LOADED.load(Ordering::SeqCst) { return Ok(komorebi_core::Flow::Skip); From c0ca0a83ad0549c54df1ca5860c01b33dde69afa Mon Sep 17 00:00:00 2001 From: LGUG2Z Date: Sat, 31 Oct 2026 19:32:58 -0700 Subject: [PATCH 4/5] fix(nix): check the Windows formatting with the nightly rustfmt over the Windows files; add tools/format-all The Windows fmt check ran the stable `cargo fmt` over the stubbed workspace source: it failed on the empty stub lib.rs files of the other platforms, on `mod linux;`/`mod macos;` of the shared entry files (the Windows source does not have those modules), and its stable rustfmt ignores the nightly options of rustfmt.toml. It is now a runCommand running tools/format-all --tree windows with the nightly rustfmt over the files of the Windows source (build.real, no stubs), file by file with skip_children. tools/format-all runs the same check locally (--check, or --apply to format; --tree windows|mac|kde|all; the nightly rustfmt from $RUSTFMT, PATH or the root dev shell). mac is the explicit-file invocation of the kfm check, kde is `cargo fmt -p ...` as the KDE check does. Verified: in a throwaway copy of wip-cand7, --apply formats 17 Windows files (+211 -88; crates/ komorebi-backend, bar-core, core, protocol, bar windows modules, client windows.rs, komorebi-gui, testwin) and 12 KDE files (+22 -29); afterwards --check passes for windows, mac and kde. The formatting itself is not in this revision (other agents are editing those files). The nix attribute evaluates; not built. --- flake.nix | 19 ++++++++---- tools/format-all | 81 ++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 94 insertions(+), 6 deletions(-) create mode 100755 tools/format-all diff --git a/flake.nix b/flake.nix index 7b867cbe..614f8bdf 100644 --- a/flake.nix +++ b/flake.nix @@ -522,12 +522,19 @@ } ); - komorebi-workspace-fmt = build.craneLib.cargoFmt { - inherit (build) src; - pname = "komorebi-workspace"; - version = "0.1.0"; - cargoToml = "${build.real}/Cargo.toml"; - }; + # the nightly rustfmt over the Windows files, as tools/format-all --tree windows does locally. Not + # `cargo fmt`: it ran the stable rustfmt (which ignores the nightly options of rustfmt.toml) over + # the stub sources of the other platforms and followed `mod linux;` into files the Windows source + # does not have. + komorebi-workspace-fmt = + pkgs.runCommand "komorebi-workspace-fmt" + { + nativeBuildInputs = [ nightlyRustfmt ]; + } + '' + RUSTFMT=rustfmt bash ${./tools/format-all} --check --tree windows --root ${build.real} + touch $out + ''; komorebi-workspace-toml-fmt = build.craneLib.taploFmt { src = pkgs.lib.sources.sourceFilesBySuffices build.real [ ".toml" ]; diff --git a/tools/format-all b/tools/format-all new file mode 100755 index 00000000..eb6c1a30 --- /dev/null +++ b/tools/format-all @@ -0,0 +1,81 @@ +#!/usr/bin/env bash +# format-all: the formatting checks of the nix flakes, runnable locally, and the fix for them. +# +# Usage: tools/format-all [--check | --apply] [--tree windows|kde|mac|all] [--root DIR] +# --check (default) fails if any file is not formatted; prints the diff +# --apply formats the files in place (do it LAST on a candidate: it touches many files) +# --tree which flake's check to reproduce (default all) +# --root the repository (default: the one this script is in; the nix check passes its source) +# +# The checks use the nightly rustfmt (rustfmt.toml has nightly options) and edition 2024, the +# edition of every manifest: +# windows every .rs file of the Windows crates with the root rustfmt.toml, file by file +# (skip_children: the entry files name modules of other platforms that are not in the +# Windows source, which rustfmt would fail to find); the linux and macos modules of the +# shared crates belong to the kde and mac trees +# mac komorebi-for-mac/**/*.rs and the macos modules of the shared crates, with +# komorebi-for-mac/rustfmt.toml +# kde `cargo fmt -p `, as komorebi-for-kde/flake.nix does +# The nightly rustfmt is $RUSTFMT if set, else `rustfmt` if that is a nightly, else the one of the +# dev shell of the root flake (`nix develop`), which is the one the nix checks use (a nightly of the +# pinned rust-overlay; another nightly may format a little differently). +set -uo pipefail + +mode=check +tree=all +root=$(cd "$(dirname "$0")/.." && pwd) +while [ $# -gt 0 ]; do + case $1 in + --check) mode=check ;; + --apply) mode=apply ;; + --tree) tree=$2; shift ;; + --root) root=$2; shift ;; + -h | --help) sed -n 2,23p "$0"; exit 0 ;; + *) echo "format-all: unknown argument $1" >&2; exit 2 ;; + esac + shift +done +root=$(cd "$root" && pwd) + +if [ -z "${RUSTFMT:-}" ]; then + if rustfmt --version 2>/dev/null | grep -q nightly; then + RUSTFMT=rustfmt + elif [ -z "${FORMAT_ALL_IN_SHELL:-}" ] && command -v nix >/dev/null; then + FORMAT_ALL_IN_SHELL=1 exec nix develop "$root" --command "$0" "$@" --root "$root" + else + echo "format-all: no nightly rustfmt (set RUSTFMT)" >&2; exit 2 + fi +fi +export RUSTFMT +cd "$root" || exit 2 + +flag=--check +[ "$mode" = apply ] && flag= +status=0 + +# the linux and macos modules of the shared crates (the Windows source filter of flake.nix leaves them out) +other_platform='(^|/)(komorebic/src/(linux|macos)|komorebic/tests/(linux|macos)_|komorebi-client/src/(linux|macos)\.rs|komorebi-client/tests/(linux|macos)_|komorebi-bar/src/macos|komorebi-daemon/tests/(linux|macos)_)' + +rs_files() { find . -name '*.rs' -not -path '*/target/*' -not -path './.git/*' -not -path './.jj/*' | sed 's|^\./||' | sort; } + +run_rustfmt() { # config-file, files on stdin + local cfg=$1 files + mapfile -t files + [ ${#files[@]} -eq 0 ] && { echo "format-all: no files for $cfg" >&2; return 1; } + "$RUSTFMT" --edition 2024 --config-path "$cfg" --config skip_children=true $flag "${files[@]}" +} + +if [ "$tree" = windows ] || [ "$tree" = all ]; then + echo "format-all: windows" + rs_files | grep -v '^komorebi-for-\(kde\|mac\)/' | grep -Ev "$other_platform" | run_rustfmt rustfmt.toml || status=1 +fi +if [ "$tree" = mac ] || [ "$tree" = all ]; then + echo "format-all: mac" + { rs_files | grep '^komorebi-for-mac/'; rs_files | grep -E "^(komorebic/src/macos|komorebi-bar/src/macos|komorebi-client/src/macos\.rs)"; } \ + | run_rustfmt komorebi-for-mac/rustfmt.toml || status=1 +fi +if [ "$tree" = kde ] || [ "$tree" = all ]; then + echo "format-all: kde" + cargo fmt -p komorebi -p komorebi-linux -p komorebic -p komorebi-client -p komorebi-hotkeys -- $flag || status=1 +fi +exit $status From e5f93516211adf290f0cdfb2ab006286e25bf7fc Mon Sep 17 00:00:00 2001 From: LGUG2Z Date: Sat, 31 Oct 2026 19:41:49 -0700 Subject: [PATCH 5/5] docs(core-model): what Windows keeps platform-specific for a shared WindowManager

(section 22) Section 22 of docs/dev/core-model.md, the hook list for kfde: why the unmanaged-window gate was NOT moved from 18 Windows functions to the router (the router form refuses every message, an arm that works before its gated call, the layer split of FocusWindow/MoveWindow/CycleFocusWindow, and callers that bypass the router), with the defaulted gate_message hook that expresses both shapes; the WindowManagerPlatform hooks (new, init, stop, restore_all_windows, resize_window, focus_workspace plan/execute, enforce_workspace_rules, the cross-monitor DPI check, the floating-window functions); a BorderPlatform hook for the border calls and the monocle floating hide/restore; wallpaper, window handling behaviour, workspace names and custom layouts; the result of the cosmetic re-read (nothing left); and an order for the implementation with the Windows gates. Docs only. --- docs/dev/core-model.md | 104 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 104 insertions(+) diff --git a/docs/dev/core-model.md b/docs/dev/core-model.md index a26aa3d9..10260836 100644 --- a/docs/dev/core-model.md +++ b/docs/dev/core-model.md @@ -1409,3 +1409,107 @@ or field, so moving them means moving `WindowManager`, the blockers of section 1 `WorkAreaOffset`, ...): thin calls of `WindowManager` methods that edit a workspace and re-layout, the same coupling; - queries, configuration, borders, animations, transparency, schema: statics and the platform. + +## 22. What Windows keeps platform-specific for a shared `WindowManager

` (kfw, wip-u-win-deep) + +Written against `wip-cand7` plus the revisions of `wip-u-win-deep`: `PlatformMonitorId

` is in +`komorebi-core` (blocker 5 of section 18), the Windows `monitor_idx_from_current_pos` has KDE's text, and +`promote-focus` on a custom layout is the `WorkspacePlatform::promote_focus_container_idx` hook (blocker +6, the fallback part). This is the hook list kfde can implement: every item says what Windows does, what +KDE and macOS do (from sections 17, 18 and 20), and the proposed shape. Items are ordered by how many +shared functions they touch. + +### 22.1 The unmanaged-window gate (blocker 1): not converged, and why + +`handle_unmanaged_window_behaviour()` (refuse a command when `OperationBehaviour::NoOp` is set and the +focused window is not in a container of the focused workspace) is called at the top of 18 functions on +Windows: `move_container_to_monitor`, `move_container_to_workspace`, `focus_container_in_direction`, +`move_container_in_direction`, `focus_container_in_cycle_direction`, `move_container_in_cycle_direction`, +`cycle_container_window_in_direction`, `cycle_container_window_index_in_direction`, +`focus_container_window`, `stack_all`, `unstack_all`, `add_window_to_container`, +`promote_container_to_front`, `promote_container_swap`, `promote_focus_to_front`, +`remove_window_from_container`, `toggle_monocle`, `toggle_maximize`. KDE and macOS call it once in the +router, before the `match`, for every message. Moving Windows to the router is **not** behaviour-neutral +and was not done: the reading of `process_command` shows four ways in which the two forms differ. + +1. The router form refuses every message, including queries, rule and configuration commands, the + workspace-focus commands and `stop` (those never call one of the 18); the per-function form refuses + only what reaches one. A router that gated the same set would need a message list + (`requires_managed_focus(&SocketMessage)`) that nothing shares. +2. An arm that does other work first is not refused as a whole on Windows: `FocusStackWindow` focuses the + monitor under the pointer and only then calls `focus_container_window`; `MoveContainerToNamedWorkspace` + and the `Cycle*Container*` arms look up the target first; a router gate would refuse before any of it. +3. The layer split: `FocusWindow`, `MoveWindow` and `CycleFocusWindow` call a gated function in the Tiling + layer and an ungated floating function in the Floating layer, so one message is refused in one layer + only; a router gate refuses both. +4. Nested and direct callers that do not pass the router: `focus_container_window` is also called from the + arm of `process_command` that focuses a window by its location (`WorkspaceWindowLocation::Monocle` and + `Container`), `move_container_to_workspace` from `move_container_to_monitor` and from + `move_container_in_direction`, `toggle_monocle` and `toggle_maximize` from + `move_container_in_direction` and the cycle functions, and the unit tests of `window_manager.rs` call + all of them directly. The nested calls are covered by the outer gate; the direct ones are not. + +The hook that makes both shapes expressible is a defaulted method on the shared router, +`fn gate_message(&self, message: &SocketMessage) -> eyre::Result<()>`: the default (KDE, macOS) calls +`handle_unmanaged_window_behaviour` for every message; Windows returns `Ok(())` and keeps the call inside +the 18 functions (they stay Windows text until the owner decides that Windows should refuse more). + +### 22.2 Hooks of the window manager (`WindowManagerPlatform`) + +| Windows keeps | What it is | KDE / macOS | Shape | +|---|---|---|---| +| `new`, `init` | `new` takes the command listener, the event channel and the socket; `init` loads monitor and workspace information through `WindowsApi`, uncloaks left-behind windows, starts the border and stackbar machinery | KDE: backend monitors and desktops; macOS: run loop and AX | `fn init(&mut WindowManager)`, `fn new(..)` as associated functions; the struct's platform fields in `P::State` (section 2: `known_hwnds`, `virtual_desktop_id`, `uncloack_to_ignore`, `has_pending_raise_op`, `pending_move_op` with handle and rect, `already_moved_window_handles`) | +| `stop` | writes `komorebi.state.json`, switches animations off, waits for them, restores every window, turns focus-follows-mouse off, shuts the subscriber sockets, removes the socket file, waits for a bar restart in progress, `process::exit(0)` | KDE: `backend().shutdown()`; macOS: its own | `fn stop(&mut WindowManager, ignore_restore: bool)`; the shared part is the restore, the rest is the hook | +| `restore_all_windows` | restores each window by `WindowsApi` (cloak/hide/minimize, the maximized and monocle windows), skipping windows the user hid | KDE and macOS have their own | `fn restore_all_windows(..)`; Windows' body stays | +| `resize_window` | resizes by edge with DPI scaling and the min-size rules (58 lines); `ResizeWindowEdge` additionally goes through the live-resize guard | macOS 52 lines of its own, KDE none (the compositor) | `fn resize_window(..)`; the arm `ResizeWindowEdge` is a hook too | +| `focus_workspace` | plans a slide transition (`workspace_transition_plan`, `focus_workspace_towards`) and runs the animation, or shows and hides windows | KDE asks the compositor for the desktop | plan/execute split: `fn plan_workspace_transition(..) -> Plan` (shared) and `fn execute(plan)` (hook) | +| `enforce_workspace_rules`, `manage_focused_window`, `unmanage_focused_window`, `monitor_idx_from_window` | rules apply to windows found by `WindowsApi` and move them with `SetWindowPos`; manage/unmanage are fed by an event on Windows and a notification on KDE | differ in input | hooks `fn windows_to_enforce(..)`, `fn manage_focused(..)` | +| `move_container_in_direction` | a DPI check across monitors (`monitors_have_same_dpi`) before a cross-monitor move | none | `fn before_cross_monitor_move(a, b) -> eyre::Result<()>`, no-op default | +| `move_floating_window_in_direction`, `focus_floating_window_in_direction` | border offsets and the floating-window search (105 lines) | KDE and macOS: 29-line variants | stay platform; extension trait | + +### 22.3 Borders, stackbars, animations: the `BorderPlatform` hook + +`window_manager.rs` calls the border manager in few places: `cycle_monocle` destroys the borders +(`border_manager::destroy_all_borders`), `stop` reads the border implementation, the ghost kinds are set in +one free function; the router arms `Border*`, `Retile*`, `ReloadStaticConfiguration` and `TogglePause` set +`force_update_borders` and notify the border thread. `monocle_on` and `monocle_off` also hide and restore +the floating windows (through the backend). The stackbar manager is not called from `window_manager.rs`. KDE draws borders in the +compositor and calls none of these, macOS has its own border thread. Shape: a defaulted +`BorderPlatform` with `fn borders_changed(&mut self)`, `fn destroy_borders(&mut self)`, +`fn hide_floating_for_monocle(&mut self, hide: bool)`; defaults do nothing (KDE) and macOS implements +its own. The `force_update_borders` flag of the router becomes the return value of those hooks, as +`replace_configuration` already returns it. + +### 22.4 Wallpaper, window-handling behaviour, workspace names, custom layouts + +- **Wallpaper.** `apply_wallpaper_for_monitor_workspace` finds the wallpaper of a monitor/workspace pair + and calls `Workspace::apply_wallpaper` (which is the `WorkspacePlatform::apply_wallpaper` hook: + `WindowsApi::set_wallpaper` through COM on Windows, the backend on KDE, nothing on macOS); the shared + function takes a `PlatformMonitorId` now and can move as it is. +- **Window handling behaviour.** `WINDOW_HANDLING_BEHAVIOUR` (Sync/Async, the `ASYNC_WINDOW_POS` flag of + `SetWindowPos`) is read inside `WindowsApi::position_window`, never in `window_manager.rs`: it is a + setting of the Windows `set_rect`, not a hook of the window manager. Keep it in `Settings::platform`. +- **Workspace names.** `set_workspace_name` records the name in the monitor's `Extra` (`workspace_names`), + and `known_workspace_name` is already the `MonitorPlatform` hook; a shared `set_workspace_name` calls a + `fn record_workspace_name(monitor: &mut Monitor, idx: usize, name: &str)` hook (default: nothing). +- **Custom layouts.** `Layout::Custom` stays in `komorebi-layouts`; the Windows arms of `cycle_layout`, + `promote_container_swap` and `change_workspace_layout_default` fail for a custom layout without a primary + column, which `primary_container_idx` already expresses; the one real difference (`promote-focus` falls + back to the first column) is `promote_focus_container_idx`, done in this branch. + +### 22.5 Cosmetic differences: nothing left to do + +Section 18 lists which near-identical functions were cosmetic and converged (`bail!`, `Lockable`, log +text, the `SessionFloatRules` and `State` arms); the rest of its table is real. Re-reading the Windows and +KDE copies of the functions that differ by at most four lines against that table found no cosmetic +difference left (`float_window` and the `focus_*` family read `mouse_follows_focus` into a local on KDE +because of a borrow, and Windows has no such need: they stay as they are). + +### 22.6 Order for kfde + +1. `fn gate_message` on the shared router (22.1), Windows `Ok(())`. +2. `BorderPlatform` (22.3) with no-op defaults: unblocks `cycle_monocle`, `retile_all`, `monocle_on/off`. +3. `record_workspace_name` (22.4) and the `PlatformMonitorId` use in the shared wallpaper function. +4. The plan/execute split of `focus_workspace`, then `init`/`stop`/`new`/`restore_all_windows` as hooks. +Gates for each: Windows `commands`, `workspaces`, `focus`, `stacking`, `monocle` (maximizing), `borders`, +`layouts` scenarios; KDE fast tier and VM for the router change.