From f3b9d926fbe4087061b938edfff0feaddc12fc1a Mon Sep 17 00:00:00 2001 From: LGUG2Z Date: Sat, 31 Oct 2026 20:11:30 -0700 Subject: [PATCH 1/8] refactor(config): push_simple_rule, adding a simple rule once per kind and id Moves KDE's push_simple_rule (and its test) to komorebi_config::matching: add a simple rule that matches id as a kind with the legacy strategy unless a simple rule of that kind and id is there already; a rule of another kind with the same id and a composite rule do not stop it. The KDE daemon and, next, the macOS daemon use it for the ignore and manage rules. Nothing calls it yet. Verified: native cargo test -p komorebi-config 5 + 16 + 9 + 1 passed. --- crates/komorebi-config/src/matching.rs | 39 ++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) diff --git a/crates/komorebi-config/src/matching.rs b/crates/komorebi-config/src/matching.rs index 899124fa..fb0c32ba 100644 --- a/crates/komorebi-config/src/matching.rs +++ b/crates/komorebi-config/src/matching.rs @@ -94,6 +94,23 @@ impl From for IdWithIdentifier { } } +/// Adds a simple rule that matches `id` as a `kind` (with the legacy matching strategy), unless a +/// simple rule of that kind and id is there already. A rule of another kind with the same id, or a +/// composite rule, does not stop it. +pub fn push_simple_rule(rules: &mut Vec, kind: ApplicationIdentifier, id: &str) { + let exists = rules + .iter() + .any(|r| matches!(r, MatchingRule::Simple(r) if r.kind == kind && r.id.eq(id))); + + if !exists { + rules.push(MatchingRule::Simple(IdWithIdentifier { + kind, + id: id.to_string(), + matching_strategy: Option::from(MatchingStrategy::Legacy), + })); + } +} + #[cfg(test)] mod tests { use super::*; @@ -158,4 +175,26 @@ mod tests { assert_eq!(plain.id, "/usr/bin/kcalc"); assert_eq!(plain.matching_strategy, None); } + + #[test] + fn push_simple_rule_keeps_rules_of_another_kind_with_the_same_id() { + let mut rules = vec![]; + + push_simple_rule(&mut rules, ApplicationIdentifier::Class, "foo"); + push_simple_rule(&mut rules, ApplicationIdentifier::Exe, "foo"); + assert_eq!(rules.len(), 2); + + push_simple_rule(&mut rules, ApplicationIdentifier::Exe, "foo"); + push_simple_rule(&mut rules, ApplicationIdentifier::Class, "foo"); + assert_eq!(rules.len(), 2); + + rules.clear(); + rules.push(MatchingRule::Composite(vec![IdWithIdentifier { + kind: ApplicationIdentifier::Exe, + id: "foo".to_string(), + matching_strategy: None, + }])); + push_simple_rule(&mut rules, ApplicationIdentifier::Exe, "foo"); + assert_eq!(rules.len(), 2); + } } From 544767c86390b1ac13a71ff6edf50ee990c4ae9e Mon Sep 17 00:00:00 2001 From: LGUG2Z Date: Sat, 31 Oct 2026 20:12:43 -0700 Subject: [PATCH 2/8] refactor(mac): ignore and manage rules go through the shared push_simple_rule BEHAVIOUR (a small fix, KDE's behaviour). Router arm ManageRule and the method add_ignore_rule used an inline loop that skipped a rule when any simple rule had the same id, whatever its kind: 'ignore-rule class foo' after 'ignore-rule exe foo' was dropped. They now call komorebi_config::matching::push_simple_rule (kind and id), as KDE does (its test pins it), and the ManageRule arm is the KDE text. Verified: fast-check macOS PASS; fake-CC cargo clippy -p komorebi-macos --all-targets -D warnings clean; tools/format-all --check --tree mac clean. Not verified: any macOS run. Verified on the Mini: not yet. Hand check row added. --- docs/dev/macos-handcheck.md | 1 + .../komorebi/src/process_command.rs | 35 ++----------------- 2 files changed, 4 insertions(+), 32 deletions(-) diff --git a/docs/dev/macos-handcheck.md b/docs/dev/macos-handcheck.md index 48bd431a..9a7e35bd 100644 --- a/docs/dev/macos-handcheck.md +++ b/docs/dev/macos-handcheck.md @@ -99,6 +99,7 @@ timeout. Until then H5 documents the hang. | `wip-u-kfm3` registry fixes (see `jj log -r wip-u-kfm3`) | The registry keeps inert application copies (no blocking Accessibility call when an entry is dropped), a window is registered when its observer is attached, a clone being dropped no longer deregisters its window, `forget_pid` runs ahead of the pause and other-space returns, and the application reaper forgets what it reaps. Nothing reads the registry except the unused `MacosBackend`. | H3, H4, H6, H7 above, and the usual walk-through: no change in what the daemon does is expected. | | deep dedup 1: `refactor(mac): the daemon uses the shared Container API with the hide spot` (see `jj log -r wip-u-mac-deep`) | `ContainerExt` (`add_window_at`, `load_focused_window_at`, `hide_on`, `restore_focused_window`) is gone: every call is the shared `Container::{add_window, load_focused_window, hide, restore}` with `workspace.hide_spot()`. `monocle_on` and `cycle_monocle` took the corner from the monitor (`monitor.extra`) and now take it from the workspace (`workspace.state`), which the monitor writes with the globals; `restore()` now skips the Accessibility call under `cfg!(test)`. | `cargo test`; then H1 (hide spot) and: toggle monocle on a workspace with two containers on a monitor with `window_hiding_position: BottomRight` (every other container parks in that corner), cycle the monocle container, stack with `komorebic stack`/`stack-all`, `cycle-stack`, `add-window-to-container`, switch workspaces. Change the monitor's `window_hiding_position` in the config, reload, and toggle monocle at once: the corner must be the new one. | | deep dedup 2: `refactor(mac): five router arms are methods with the KDE names` | `ToggleWorkspaceLayer`, `ResizeWindowAxis`, `SessionFloatRule`, `IgnoreRule` and `ReplaceConfiguration` call `toggle_workspace_layer`, `resize_window_axis`, `add_session_float_rule`, `add_ignore_rule(identifier, id: &str)` and `replace_configuration(&PathBuf)`, with the bodies the arms had (a pure move; the router arms are now the KDE text). `id` of the ignore rule is a `&str`, compared with `==`. | `cargo test`; by hand: `komorebic toggle-workspace-layer` twice (tiling to floating and back: a window of the layer is focused, the others hide at the corner and come back), `resize-axis horizontal|vertical increase|decrease`, `komorebic session-float-rule` on a window, `komorebic ignore-rule exe ` and `ignore-rule title/class` (the matching windows leave the workspaces), `komorebic replace-configuration ` (the daemon restarts its windows under the new config; with a broken file it is left alone). | +| wm2 1: `refactor(mac): ignore and manage rules go through the shared push_simple_rule` | `ignore-rule` and `manage-rule` add a rule unless a simple rule of the same kind and id exists. The macOS code checked only the id, so `ignore-rule class foo` after `ignore-rule exe foo` was silently dropped; it is added now (this is the KDE behaviour, which a KDE test pins). | `komorebic ignore-rule exe Notes`, then `ignore-rule title Notes`: both rules are in `komorebic state` ... `ignore_identifiers` (before, the second was not). Running the same command twice adds one rule. `manage-rule` the same. | Revisions in section B change no behaviour on purpose (rename, move, route); they still need the sections C walk-through, because a mechanical mistake would show there. diff --git a/komorebi-for-mac/komorebi/src/process_command.rs b/komorebi-for-mac/komorebi/src/process_command.rs index 3b3f0732..e775bb44 100644 --- a/komorebi-for-mac/komorebi/src/process_command.rs +++ b/komorebi-for-mac/komorebi/src/process_command.rs @@ -33,6 +33,7 @@ use crate::core::config_generation::WorkspaceMatchingRule; use crate::monitor::MonitorExt; use crate::scrolling::WorkspaceScrolling; use crate::workspace::WorkspaceExt; +use komorebi_config::matching::push_simple_rule; use crate::core_graphics::CoreGraphicsApi; use crate::current_space_id; @@ -906,22 +907,7 @@ impl WindowManager { SocketMessage::ManageRule(identifier, ref id) => { let mut manage_identifiers = MANAGE_IDENTIFIERS.lock(); - let mut should_push = true; - for m in &*manage_identifiers { - if let MatchingRule::Simple(m) = m - && m.id.eq(id) - { - should_push = false; - } - } - - if should_push { - manage_identifiers.push(MatchingRule::Simple(IdWithIdentifier { - kind: identifier, - id: id.clone(), - matching_strategy: Option::from(MatchingStrategy::Legacy), - })); - } + push_simple_rule(&mut manage_identifiers, identifier, id); } SocketMessage::NewWorkspace => { self.new_workspace()?; @@ -1585,22 +1571,7 @@ impl WindowManager { ) -> eyre::Result<()> { let mut ignore_identifiers = IGNORE_IDENTIFIERS.lock(); - let mut should_push = true; - for i in &*ignore_identifiers { - if let MatchingRule::Simple(i) = i - && i.id == id - { - should_push = false; - } - } - - if should_push { - ignore_identifiers.push(MatchingRule::Simple(IdWithIdentifier { - kind: identifier, - id: id.to_string(), - matching_strategy: Option::from(MatchingStrategy::Legacy), - })); - } + push_simple_rule(&mut ignore_identifiers, identifier, id); let offset = self.work_area_offset; From fe652566591b5cc70da25ffcdfe48aa720199e39 Mon Sep 17 00:00:00 2001 From: LGUG2Z Date: Sat, 31 Oct 2026 20:14:00 -0700 Subject: [PATCH 3/8] refactor(kde): the ignore and manage rules use the shared push_simple_rule The KDE copy of push_simple_rule and its test moved to komorebi_config::matching (the config revision of this stack); the daemon imports it. No behaviour change: the function is the same text. Verified: KDE cargo check --all-targets and lib tests (fast-check) PASS; native cargo test -p komorebi-config has the moved test; tools/format-all --apply --tree kde ran. --- .../komorebi/src/process_command.rs | 39 +------------------ 1 file changed, 1 insertion(+), 38 deletions(-) diff --git a/komorebi-for-kde/komorebi/src/process_command.rs b/komorebi-for-kde/komorebi/src/process_command.rs index 9a9e4dc6..fc38bd9e 100644 --- a/komorebi-for-kde/komorebi/src/process_command.rs +++ b/komorebi-for-kde/komorebi/src/process_command.rs @@ -270,6 +270,7 @@ use crate::workspace::WorkspaceWindowLocation; use color_eyre::eyre; use color_eyre::eyre::Context; use color_eyre::eyre::OptionExt; +use komorebi_config::matching::push_simple_rule; use komorebi_themes::colour::Rgb; use komorebi_transport::CommandTarget; use komorebi_transport::NoPolicy; @@ -1993,22 +1994,6 @@ pub fn read_commands_uds(wm: &Arc>, stream: UnixStream) -> komorebi_transport::read_commands::(wm, stream, &NoPolicy) } -/// Add a simple socket-created rule unless one with the same kind and id is already present; -/// a rule of another kind with the same id is a different rule -fn push_simple_rule(rules: &mut Vec, kind: ApplicationIdentifier, id: &str) { - let exists = rules - .iter() - .any(|r| matches!(r, MatchingRule::Simple(r) if r.kind == kind && r.id.eq(id))); - - if !exists { - rules.push(MatchingRule::Simple(IdWithIdentifier { - kind, - id: id.to_string(), - matching_strategy: Option::from(MatchingStrategy::Legacy), - })); - } -} - /// The window manager as the shared commands of `komorebi_core::command` see it impl komorebi_core::CommandHost for WindowManager { type P = crate::workspace::KdePlatform; @@ -2394,26 +2379,4 @@ mod tests { std::fs::remove_file(socket_path).unwrap(); } - - #[test] - fn push_simple_rule_keeps_rules_of_another_kind_with_the_same_id() { - let mut rules = vec![]; - - push_simple_rule(&mut rules, ApplicationIdentifier::Class, "foo"); - push_simple_rule(&mut rules, ApplicationIdentifier::Exe, "foo"); - assert_eq!(rules.len(), 2); - - push_simple_rule(&mut rules, ApplicationIdentifier::Exe, "foo"); - push_simple_rule(&mut rules, ApplicationIdentifier::Class, "foo"); - assert_eq!(rules.len(), 2); - - rules.clear(); - rules.push(MatchingRule::Composite(vec![IdWithIdentifier { - kind: ApplicationIdentifier::Exe, - id: "foo".to_string(), - matching_strategy: None, - }])); - push_simple_rule(&mut rules, ApplicationIdentifier::Exe, "foo"); - assert_eq!(rules.len(), 2); - } } From 4811a056e9dfedcb13b25470d9612b4827fbb328 Mon Sep 17 00:00:00 2001 From: LGUG2Z Date: Sat, 31 Oct 2026 20:16:07 -0700 Subject: [PATCH 4/8] refactor(kde): Minimize, Close and DebugWindow are methods with the macOS names The inline router arms become minimize_foreground_window, close_foreground_window and debug_window(window_id, reply) with the bodies they had, so that the three arms are the same text as macOS's (the bodies differ by the platform: the backend and Window::from here, the foreground element and the Accessibility window list there). Pure move, no behaviour change. Verified: KDE cargo check --all-targets and lib tests PASS; tools/format-all --apply --tree kde ran. --- .../komorebi/src/process_command.rs | 68 ++++++++++++------- 1 file changed, 43 insertions(+), 25 deletions(-) diff --git a/komorebi-for-kde/komorebi/src/process_command.rs b/komorebi-for-kde/komorebi/src/process_command.rs index fc38bd9e..1d660b58 100644 --- a/komorebi-for-kde/komorebi/src/process_command.rs +++ b/komorebi-for-kde/komorebi/src/process_command.rs @@ -1330,18 +1330,8 @@ impl WindowManager { SocketMessage::ResizeWindowAxis(axis, sizing) => { self.resize_window_axis(axis, sizing)? } - SocketMessage::Minimize => { - let foreground_window = backend() - .foreground_window() - .ok_or_eyre("there is no foreground window")?; - Window::from(foreground_window).minimize()?; - } - SocketMessage::Close => { - let foreground_window = backend() - .foreground_window() - .ok_or_eyre("there is no foreground window")?; - Window::from(foreground_window).close()?; - } + SocketMessage::Minimize => self.minimize_foreground_window()?, + SocketMessage::Close => self.close_foreground_window()?, SocketMessage::ManageFocusedWindow => { self.manage_focused_window()?; } @@ -1819,19 +1809,7 @@ impl WindowManager { workspace.resize_dimensions = resize; self.update_focused_workspace(false, false)?; } - SocketMessage::DebugWindow(window_id) => { - // an id that is not a u32 is not a window - let window = u32::try_from(window_id).map(Window::from); - if let Ok(window) = window - && window.is_valid() - { - let mut rule_debug = RuleDebug::default(); - let _ = window.should_manage(None, &mut rule_debug); - let schema = serde_json::to_string_pretty(&rule_debug)?; - - reply.write_all(schema.as_bytes())?; - } - } + SocketMessage::DebugWindow(window_id) => self.debug_window(window_id, &mut reply)?, SocketMessage::Border(enable) => { border_manager::BORDER_ENABLED.store(enable, Ordering::SeqCst); if !enable { @@ -1994,6 +1972,46 @@ pub fn read_commands_uds(wm: &Arc>, stream: UnixStream) -> komorebi_transport::read_commands::(wm, stream, &NoPolicy) } +impl WindowManager { + /// Minimizes the window that has the focus + pub fn minimize_foreground_window(&mut self) -> eyre::Result<()> { + let foreground_window = backend() + .foreground_window() + .ok_or_eyre("there is no foreground window")?; + Window::from(foreground_window).minimize()?; + Ok(()) + } + + /// Closes the window that has the focus + pub fn close_foreground_window(&mut self) -> eyre::Result<()> { + let foreground_window = backend() + .foreground_window() + .ok_or_eyre("there is no foreground window")?; + Window::from(foreground_window).close()?; + Ok(()) + } + + /// Answers with why the window of this id is, or is not, managed + pub fn debug_window( + &self, + window_id: i64, + reply: &mut impl std::io::Write, + ) -> eyre::Result<()> { + // an id that is not a u32 is not a window + let window = u32::try_from(window_id).map(Window::from); + if let Ok(window) = window + && window.is_valid() + { + let mut rule_debug = RuleDebug::default(); + let _ = window.should_manage(None, &mut rule_debug); + let schema = serde_json::to_string_pretty(&rule_debug)?; + + reply.write_all(schema.as_bytes())?; + } + Ok(()) + } +} + /// The window manager as the shared commands of `komorebi_core::command` see it impl komorebi_core::CommandHost for WindowManager { type P = crate::workspace::KdePlatform; From 5e553a7da488c6881be05d656cef3b9a1e893afd Mon Sep 17 00:00:00 2001 From: LGUG2Z Date: Sat, 31 Oct 2026 20:13:05 -0700 Subject: [PATCH 5/8] docs: MIGRATION-SUMMARY.md, the final state of the consolidation A maintainer who was not here had no one place that says what the repository is now, what was shared and how, what was kept per platform on purpose, how it was verified and what was not, what is still open, and how to go on. The page gives: the four unified packages and how cfg(target_os) selects the platform; the three trees; the shared crates (protocol, config with the one rule matcher, collections, transport, backend, core with Container/Workspace/Monitor/ update_shared/command, settings, bar-core, komorebic-core) and the way each was moved; what stays per platform (WindowManager, router, events, macOS update, borders and other subsystems, bar rendering) with links into core-model.md, seam.md, settings.md, bar-unification.md and unified-binaries.md; the oracles and the gate results per candidate (Windows e2e, KDE VM, Mac Mini compile, unit and nix) with the flake summary; what is not verified (macOS never ran as a daemon, bar runtime under software rendering, the KDE slow tier, candidate 8 gates still running at the time of writing); known issues; the cutover list (shims, version crates, flakes, workflows, docs, tools) with a CI and release proposal that is not decided; how to continue; and a table of 26 decisions rewritten without agent names. Facts were taken from the progress and decisions logs, the revision list wip-cand4..wip-cand8 and the docs in docs/dev; no host or personal paths are included. Not built. Gate results are as recorded, not re-run. --- docs/dev/MIGRATION-SUMMARY.md | 182 ++++++++++++++++++++++++++++++++++ 1 file changed, 182 insertions(+) create mode 100644 docs/dev/MIGRATION-SUMMARY.md diff --git a/docs/dev/MIGRATION-SUMMARY.md b/docs/dev/MIGRATION-SUMMARY.md new file mode 100644 index 00000000..5dcfa05f --- /dev/null +++ b/docs/dev/MIGRATION-SUMMARY.md @@ -0,0 +1,182 @@ +# The consolidation of komorebi, komorebi-for-kde and komorebi-for-mac: final-state summary + +Status (written at wip-cand8, b6f4c2ae, 2026-10-31): a summary for a maintainer who was not there. +Gates for candidate 8 were still running when this was written; the results stated below are the ones +that had finished, with the candidate they ran on. Companion documents: [ARCHITECTURE-UNIFIED.md](ARCHITECTURE-UNIFIED.md) +(the map), [build-and-test.md](build-and-test.md) (commands, flakes), [macos-hand-check-plan.md](macos-hand-check-plan.md) +(what the owner must run on a Mac), [known-issues.md](known-issues.md) (open decisions). + +## 1. What the repository is now + +Three programs (Windows, KDE Plasma, macOS) were three repositories with copies of the same ideas. They are +one repository with one Cargo workspace (one `Cargo.lock`), shared crates under `crates/`, and one package +per user-facing program, the platform chosen by `cfg(target_os)`. + +| Package (binary) | Directory | How the platform is chosen | +|---|---|---| +| `komorebi` | `komorebi-daemon/` | `main.rs` is a `cfg_select!` calling `daemon::run()` of `komorebi-windows`, `komorebi-linux` or `komorebi-macos`, which are target-gated dependencies | +| `komorebic` | `komorebic/` | `src/windows.rs`, `src/linux/`, `src/macos/`; the arguments are in `crates/komorebic-core` | +| `komorebi-client` | `komorebi-client/` | `src/{windows,linux,macos}.rs` behind one `Connection` | +| `komorebi-bar` | `komorebi-bar/` | `src/windows/`, `src/macos/`; shared part in `crates/komorebi-bar-core`. KDE has no bar | + +Three platform trees remain, because the platform layers are different code: the repository root (Windows: +`komorebi/` is the library `komorebi-windows`), `komorebi-for-kde/` (`komorebi-linux`, hotkeys, NixOS module, +the VM suites) and `komorebi-for-mac/` (`komorebi-macos`, nix-darwin module). The daemon libraries have no +binary; the `komorebi` package is the binary. The crate map and the tree layout are in +[ARCHITECTURE-UNIFIED.md](ARCHITECTURE-UNIFIED.md); how to build each is in [build-and-test.md](build-and-test.md). + +## 2. What was shared, and how + +| Crate | What it holds | How it was moved | +|---|---|---| +| `komorebi-collections` | `Ring`, `LockableSequence` | the KDE copy was canonical; Windows and macOS switched to it | +| `komorebi-protocol` | `SocketMessage`, payloads, state types | one enum for all platforms (guard arms for platform-only messages); the wire format is pinned by per-platform goldens generated from the three daemons before the move | +| `komorebi-config` | `StaticConfig` and the `komorebi.json` types, schema generation, and the **one window-rule matcher** (`komorebi_config::rules`: `should_act`, `should_act_individual`; see [rule-matching.md](rule-matching.md)) | one union type with per-platform schema views; the matcher replaced three copies, each daemon keeps a thin wrapper with its own signature | +| `komorebi-transport` | the command listener, pause filter, subscriber registry, `EventChannel` | the daemons take the window manager lock; the crate does not name a mutex | +| `komorebi-backend` | the `Backend` trait (what a daemon asks of its platform), plain-data infos, `FakeBackend`, contract tests, the id `Registry` | derived from the evidence in [seam.md](seam.md); Windows goes through it for the clusters in [backend-switch.md](backend-switch.md); KDE runs on it; macOS has an adapter the daemon does not use yet | +| `komorebi-core` | the model, generic over the platform window: `Container`, `Workspace

` (with `update_shared`, a skeleton with hooks), `Monitor

`, `WorkspaceGlobals`, and `command` (the shared commands over a `CommandHost`: workspace navigation, moves across workspaces and monitors, lock and unlock, focus-workspace with the pointer preamble) | converge in place, then pure move, then converge per daemon; hooks (`WorkspacePlatform`, `MonitorPlatform`, `HideSpot`) carry what differs; details in [core-model.md](core-model.md) | +| `komorebi-settings` | the run-time settings as one immutable snapshot replaced as a whole, instead of process-wide statics (paddings, aspect ratio, layout defaults, display preferences, animation, transparency, window-handling behaviour) | see [settings.md](settings.md) | +| `komorebi-bar-core` | bar configuration, widgets, platform seam, schema views | [bar-unification.md](bar-unification.md) | +| `komorebic-core` | the command line of every platform (clap definitions, docgen), platform enums | the generated `docs/cli` pages were the oracle | + +The state JSON each daemon prints is unchanged by the shared `Monitor

`/`Workspace

` (platform extras are +flattened in, pinned by tests). Native tests of the shared code run on Linux and protect all three daemons +([e2e-to-unit.md](e2e-to-unit.md) says which e2e checks became native). + +## 3. What intentionally stays per platform, and why + +- **The window manager, the command router and event processing.** About 26-37% of the text is shared and the + rest is real behaviour (Win32 cloaking, rule engines with different lists, KWin desktops, AppKit + accessibility). `WindowManager

` is not built: [core-model.md](core-model.md) sections 17, 18, 20 and 24 list the + blockers per platform; section 21 documents the commands that were shared; section 23 is a design note for a + common event vocabulary ("thin events"), not implemented. +- **macOS `Workspace::update`.** It differs in a scrolling early return and a wider SkyLight disable/re-enable + batch; adopting `update_shared` would change scrolling on macOS and cannot be verified without a Mac + (section 22; decision D15 below). +- **Backends and subsystems**: borders, animations, DWM ghosts, KWin bridge and effects, AppKit observers, + wallpapers, hotkeys. The trait is the seam; the rules are in [seam.md](seam.md). +- **The bar's rendering code** (frame margins, `network.rs`, the window seams in `bar.rs`/`main.rs`): step B4 of + [bar-unification.md](bar-unification.md) was not done because it cannot be shown mechanical without a screen. +- **Command line**: each platform keeps its own commands and help text; most are common. +- **Packaging**: [unified-binaries.md](unified-binaries.md): one binary, a library per OS. + +## 4. How it was verified + +### Oracles (checked in files, compared byte for byte) + +Wire goldens (`komorebi-protocol`), the three `schema.json` and `schema.asc.json`, the two `schema.bar.json` +(size and hash pinned in `komorebi-bar-core`), the `docs/cli` pages of each tree, JSON pins of `Container`, +`Monitor` and the state of the three daemons from real fixtures, and derivation drift (`nix eval ...drvPath`). +Details in [ARCHITECTURE-UNIFIED.md](ARCHITECTURE-UNIFIED.md) section 5. + +### Gates, by candidate + +Each candidate was a merge of the finished stacks, gated once. Results as recorded (host load and flakes noted +in [build-and-test.md](build-and-test.md) section 6): + +| Candidate | Windows e2e (QEMU guest) | KDE VM | macOS (a Mac Mini: compile, unit tests, nix) | nix pre-landing | +|---|---|---|---|---| +| baseline (before the work) | stale markers (4 checks) fail; `commands` fails about 1 in 10 sweeps | `vm-commands` never green; `vm-core-e2e` once | n/a | n/a | +| 5 (core: Container, Workspace, Monitor, `update_shared`, settings) | 38 scenarios: green apart from the 4 stale markers and flakes (`commands` 265/1 and `config_reload` 7/1 from a lock-hold stall, `resize` 25/1); the `bar` scenario could not open a window (guest has no OpenGL 2.0), schema byte-equal | 16 of 16 fast suites green, `vm-commands` green for the first time | cargo unit tests and clippy green; nix: packages and module checks green after toolchain and source-filter fixes | n/a | +| 7 (shared rule matcher, shared commands, stall fixes) | not run as a whole | not run | cargo green, nix green | Windows clippy green; Windows fmt and deny, and two KDE clippy lints, failed and were fixed in 8; packages built | +| 8 (pointer picks the monitor, bar wgpu fallback, macOS deep dedup, formatting) | in progress at the time of writing: `commands` 266/0 (first fully clean), `config_reload` 8/0 | queued | nix all green, cargo 665 passed, 0 failed, 1 ignored | in progress | + +Stress runs of lock-heavy command sequences compared baseline and candidate 5: non-answers of `komorebic state` +fell from 80-83% to 14-15%, and "border manager stuck" warnings from 21-31 to 3-5 (the stall fixes work; the +stall itself still occurs now and then). + +### Flake registry (summary; full table in build-and-test.md) + +Known: Windows `commands` stall (about 1 in 10-12 sweeps, cause not found), `lifecycle_hidden`, `resize`, four +stale known-failure markers (`maximizing.user`, `placement` integer case, `unknown_monitor` x2, same on baseline), +a runner quirk for `focus_follows_mouse`. Candidates: daemon start failing with `AllowSetForegroundWindow` at high +load, `hotplug` with the recorder. KDE: `vm-commands` and `vm-core-e2e` were load-dependent on the old baseline. + +## 5. What is NOT verified + +- **macOS has never run as a daemon in these builds.** Only compile, clippy, unit tests and nix builds ran on a + Mac. Every behaviour change that touches macOS (hiding, the registry, the shared Container API, settings, + pointer-picks-monitor, bar clicks) is listed in [macos-hand-check-plan.md](macos-hand-check-plan.md). +- **The bar at run time.** The Windows `bar` scenario passes schema and config checks; the guest has only + software rendering, so window checks depend on the new wgpu fallback (WARP), which had not run in a guest when + this was written. The macOS bar never rendered under these changes. +- **The KDE `slow` VM tier** (18 suites: keys, rdp, drag and live resize, lock-sleep, wallpaper, look, ...) was not + run; only the `fast` tier (16 suites) was, on candidate 5. Candidate 8 had not been run on the VM yet. +- Windows: no scenario covers transparency or animation; only `config_reload` touches the settings path. +- Behaviour changes marked BEHAVIOUR in revision bodies are landed only after the e2e or VM gate named in the body. + +## 6. Known issues + +From [known-issues.md](known-issues.md): (1) KDE skipped the pointer-monitor preamble for three workspace +commands, now resolved for all platforms by owner decision; (2) `Monitor::focus_workspace` overwrites a workspace +name; (3) `Workspace::remove_container` focuses the container next to the focused one rather than the removed +one; (4) a subscriber that stops reading can stall the daemon on macOS (a 1 s write timeout was tried and reverted +because it can truncate a notification). Items 2-4 are inherited behaviour, pinned by tests, left for a decision. +Other open items: the Windows lock-hold stall; `komorebi-for-kde/justfile` recipes assume a KDE-only workspace; +`docs/dev/COMPARE.md` and `scripts/compare-gen.py` are stale. + +## 7. Cutover list (not done) + +What must be deleted or merged to finish; nothing below was changed. + +| Item | State | Action | +|---|---|---| +| shim packages | `komorebic-linux`, `komorebic-macos`, `komorebi-client-linux`, `komorebi-client-macos`, `komorebi-bar-macos` are `#[path]` includes of the unified modules | delete them and their directories under `komorebi-for-kde/` and `komorebi-for-mac/`; update the flakes and justfiles that name them | +| version crates | `version-linux`, `version-macos` | one `version` crate; one workspace version (Windows 0.1.42, KDE 0.1.0, macOS 0.1.1 today) | +| flakes | three flakes; the root one imports the other two as `kfde-*` and `kfm-*` | one flake with the platform trees moved to final directories; KDE's VM suites and module, macOS's darwin module stay as outputs | +| `deny.toml`, `rustfmt.toml`, toolchain files | one per tree | one of each | +| workflows | root: `windows.yaml`, `feature-check.yaml`; KDE: `ci.yaml` (nix checks, VM tiers, canary, release), `update-flake-lock.yaml`, `rerun-no-kvm.yaml`; macOS: `nix.yaml`, `release.yaml` (Homebrew formula) | a proposal, not decided: one CI that builds the three packages, runs `crates/` natively, the nix checks, the Windows e2e on a host with KVM, and the KDE VM tiers as today; one release workflow producing the Windows, Linux and macOS artifacts with one tag and one version | +| docs | per-tree `docs/`, CONTRIBUTING, READMEs | one docs tree; `docs/cli` per platform stays until commands are merged; retire COMPARE.md | +| justfiles | three | one | +| tools | `tools/` is committed (fast-check, format-all, kde-closure-check, e2e-needed, gate-lock, ...); see `tools/README.md` | keep; delete the per-tree copies of what they replace | + +## 8. How to continue + +1. **Get the macOS pass done first.** [macos-hand-check-plan.md](macos-hand-check-plan.md). Nothing deeper should land + on macOS before it. +2. **`WindowManager

`.** Blockers per platform: [core-model.md](core-model.md) sections 20 (KDE, macOS) and 24 + (Windows). The unmanaged-window gate is not behaviour-neutral to move into the router (a `gate_message` hook is + proposed in section 22.1). Rule: gate every step with the e2e/VM suites, one daemon at a time. +3. **Thin events.** Design note in section 23 (`CoreEvent`, shared handlers for gone, appeared and minimized); + risks: side-effect order per arm, macOS focus change carries no window. +4. **Commands.** `komorebi_core::command` is partial: sixteen arms and focus-workspace are shared; the remaining + arms are per platform (section 21 lists what stays and why). **The rule matcher is done** (one implementation). +5. **The deeper-dedup boundary.** Share a function only when a native test can pin it; where the text differs for + a real platform reason, put the difference behind a hook (as `HideSpot` and `begin_pass` do) rather than + converging behaviour you cannot verify. +6. **Decide items 2-4 of the known issues**, then move them into the shared code with the e2e gate. +7. **Complete the cutover** (section 7), then regenerate the Windows `docs/cli` and the schema docs. + +## 9. The decisions that shaped the design + +Rewritten from the decisions log. "Owner" marks a decision the owner made; the others were made to unblock and are +reversible as stated. + +| # | Decision | Why | Reverse | +|---|---|---|---| +| 1 | One workspace, one `Cargo.lock`; flakes re-export the nested ones and the root builds them from the whole repo | a spike showed 859 to 900 packages with no conflicts; the root source can then be shared | keep three workspaces | +| 2 | macOS checks on Linux use a fake C compiler and only type-check | nothing else runs without a Mac | none | +| 3 | The wire oracle is a schema-driven golden generator run on the three daemons before the move | the move must not change what is sent | none | +| 4 | One union `StaticConfig` with per-platform schema views; per-platform defaults documented in a table instead of converging every doc | users' files must keep loading; schemas are checked in | one type per platform | +| 5 | `komorebic-core` generic over the platform, no `cfg` in the definitions; the CLI docs of each tree are the oracle | the pages are what users read | per-platform clap structs | +| 6 | Shared transport: the daemon locks the window manager, the crate never names a mutex | different locks per daemon | none | +| 7 | The bar is `komorebi-bar-core` plus a platform trait, one config enum, schema = per-platform views of one union; macOS accepts and skips Windows-only keys with a warning | one config file works everywhere | separate bars | +| 8 | `Backend` is derived from evidence (seam.md), not written from memory of one platform | a trait written from one platform bakes in its assumptions | none | +| 9 | Settings handle is `RwLock>>` with a writer mutex; the platform part is a type parameter | no new dependency; one consistent snapshot per use | use `ArcSwap` | +| 10 | Unified layout: one package each for `komorebic`, `komorebi-bar`, `komorebi-client`; the daemon as three OS-gated libraries behind one thin binary | rewriting about 1700 `crate::` paths and moving KDE tests was the alternative | merge the libraries later | +| 11 | Shared `Monitor

` keeps each daemon's state JSON (flattened platform extras); the runtime `required` order in generated schemas may change | state JSON is pinned by fixtures and user tooling | one superset JSON | +| 12 | `Workspace`/`Monitor` move by classifying each difference (cosmetic, same behaviour, real, missing), converging, then moving | a 25-member trait would hide real differences | per-platform copies | +| 13 | `Workspace

` hook signatures: fallible `begin_update`, `end_update` returns a pass, `place_window` returns a result; the Workspace move is atomic | review of the first design against KDE and Windows | finer hooks | +| 14 | Windows `komorebic visible-windows` lists unreadable windows with empty strings | a shared `visible_window_details` needs infallible details | restore the skip | +| 15 | `Layout::Custom` stays behind a Windows hook in the shared Workspace | unreachable on KDE; no KDE change | move the arms later | +| 16 | The KDE `vm-commands` handover failure is a test-precondition bug: fix the scenario, keep the check strict | an empty workspace cannot recalculate its layout; a check that cannot pass tests nothing | weaker check (rejected) | +| 17 | Freeze new behavioural stacks and stop the model move at the `WindowManager` boundary until gates catch up | shared text is 26-37%; gates were the critical path | resume sharing after gates | +| 18 | Revert the 1 s subscriber write timeout; fix the stale bar-running flag, the hwnd writer, dead-window bookkeeping, and add `komorebi-core` to default members | the timeout can truncate a notification and does not bound the stall | none (design needed: a bounded queue per subscriber) | +| 19 | Owner: KDE and macOS get the Windows pointer-picks-the-monitor behaviour for the workspace commands | consistency across platforms | per-platform preamble | +| 20 | Owner: explore deeper deduplication where it improves cross-platform testing | tests protect all three | stop at the boundary | +| 21 | Owner: software OpenGL fallback for the Windows bar (eframe `wgpu`, glow first, retry on failure) | the e2e guest has no OpenGL 2.0 | remove the feature | +| 22 | macOS keeps its own `Workspace::update` | adopting `update_shared` changes scrolling and cannot be verified without a Mac | adopt after the Mac pass | +| 23 | Formatting of real sources is applied last, with `tools/format-all` | formatting early conflicts with every open stack | none | +| 24 | The rule-list lock order is documented at the statics of each daemon (KDE, macOS, Windows) | two orders deadlocked on reload | none | +| 25 | Constant commit stamp (`nix-check`, `e2e`) in checks and e2e builds; only `packages.default` carries the real commit | a docs-only commit must be a cache hit | none | +| 26 | Gates are batched into candidates; a rebase invalidates a claim, so the gate is re-run at the tip | one revision compiled only because of a later fix | none | From 59c19da785f42d346c71e38572484b1806d1db8f Mon Sep 17 00:00:00 2001 From: LGUG2Z Date: Sat, 31 Oct 2026 20:16:07 -0700 Subject: [PATCH 6/8] refactor(mac): Minimize, Close and DebugWindow are methods BEHAVIOUR (a pure move; type-checked and clippy-clean with the fake CC). The three inline router arms of process_command.rs become minimize_foreground_window, close_foreground_window and debug_window(window_id, reply), with the bodies the arms had (the foreground element through AdhocWindow, the CoreGraphics window list walked for the id); the arms are the same text as KDE's now. The bodies stay macOS's: there is no way to share them without a window abstraction that hides the element, which is the registry work of a later step. This is the part of the owner's item (4) that can be done without changing behaviour. Verified: fast-check macOS PASS; fake-CC cargo clippy -p komorebi-macos --all-targets -D warnings clean; tools/format-all --check --tree mac clean. Not verified: any macOS run. Verified on the Mini: not yet. Hand check row added. --- docs/dev/macos-handcheck.md | 1 + .../komorebi/src/process_command.rs | 82 +++++++++++-------- 2 files changed, 51 insertions(+), 32 deletions(-) diff --git a/docs/dev/macos-handcheck.md b/docs/dev/macos-handcheck.md index 9a7e35bd..79edbcbe 100644 --- a/docs/dev/macos-handcheck.md +++ b/docs/dev/macos-handcheck.md @@ -100,6 +100,7 @@ timeout. Until then H5 documents the hang. | deep dedup 1: `refactor(mac): the daemon uses the shared Container API with the hide spot` (see `jj log -r wip-u-mac-deep`) | `ContainerExt` (`add_window_at`, `load_focused_window_at`, `hide_on`, `restore_focused_window`) is gone: every call is the shared `Container::{add_window, load_focused_window, hide, restore}` with `workspace.hide_spot()`. `monocle_on` and `cycle_monocle` took the corner from the monitor (`monitor.extra`) and now take it from the workspace (`workspace.state`), which the monitor writes with the globals; `restore()` now skips the Accessibility call under `cfg!(test)`. | `cargo test`; then H1 (hide spot) and: toggle monocle on a workspace with two containers on a monitor with `window_hiding_position: BottomRight` (every other container parks in that corner), cycle the monocle container, stack with `komorebic stack`/`stack-all`, `cycle-stack`, `add-window-to-container`, switch workspaces. Change the monitor's `window_hiding_position` in the config, reload, and toggle monocle at once: the corner must be the new one. | | deep dedup 2: `refactor(mac): five router arms are methods with the KDE names` | `ToggleWorkspaceLayer`, `ResizeWindowAxis`, `SessionFloatRule`, `IgnoreRule` and `ReplaceConfiguration` call `toggle_workspace_layer`, `resize_window_axis`, `add_session_float_rule`, `add_ignore_rule(identifier, id: &str)` and `replace_configuration(&PathBuf)`, with the bodies the arms had (a pure move; the router arms are now the KDE text). `id` of the ignore rule is a `&str`, compared with `==`. | `cargo test`; by hand: `komorebic toggle-workspace-layer` twice (tiling to floating and back: a window of the layer is focused, the others hide at the corner and come back), `resize-axis horizontal|vertical increase|decrease`, `komorebic session-float-rule` on a window, `komorebic ignore-rule exe ` and `ignore-rule title/class` (the matching windows leave the workspaces), `komorebic replace-configuration ` (the daemon restarts its windows under the new config; with a broken file it is left alone). | | wm2 1: `refactor(mac): ignore and manage rules go through the shared push_simple_rule` | `ignore-rule` and `manage-rule` add a rule unless a simple rule of the same kind and id exists. The macOS code checked only the id, so `ignore-rule class foo` after `ignore-rule exe foo` was silently dropped; it is added now (this is the KDE behaviour, which a KDE test pins). | `komorebic ignore-rule exe Notes`, then `ignore-rule title Notes`: both rules are in `komorebic state` ... `ignore_identifiers` (before, the second was not). Running the same command twice adds one rule. `manage-rule` the same. | +| wm2 2: `refactor(mac): Minimize, Close and DebugWindow are methods` | The arms call `minimize_foreground_window`, `close_foreground_window` and `debug_window(window_id, reply)` with the bodies they had. | `komorebic minimize` and `komorebic close` on the focused window of another app (the window minimizes / closes; with no foreground window an error is logged), `komorebic debug-window ` for a real window id (the rule debug JSON is printed) and for an id that does not exist (nothing printed, no error). | Revisions in section B change no behaviour on purpose (rename, move, route); they still need the sections C walk-through, because a mechanical mistake would show there. diff --git a/komorebi-for-mac/komorebi/src/process_command.rs b/komorebi-for-mac/komorebi/src/process_command.rs index e775bb44..65bcade6 100644 --- a/komorebi-for-mac/komorebi/src/process_command.rs +++ b/komorebi-for-mac/komorebi/src/process_command.rs @@ -524,16 +524,8 @@ impl WindowManager { let _suspended_animations = animation::suspend(); self.focus_container_window(idx)?; } - SocketMessage::Minimize => { - let foreground_window = - MacosApi::foreground_window().ok_or_eyre("there is no foreground window")?; - AdhocWindow::minimize(&foreground_window)?; - } - SocketMessage::Close => { - let foreground_window = - MacosApi::foreground_window().ok_or_eyre("there is no foreground window")?; - AdhocWindow::close(&foreground_window)?; - } + SocketMessage::Minimize => self.minimize_foreground_window()?, + SocketMessage::Close => self.close_foreground_window()?, SocketMessage::ManageFocusedWindow => { self.manage_focused_window()?; } @@ -1217,28 +1209,7 @@ impl WindowManager { workspace.resize_dimensions = resize; self.update_focused_workspace(false, false)?; } - SocketMessage::DebugWindow(window_id) => { - if let Some(window_list_info) = CoreGraphicsApi::window_list_info() { - for raw_window_info in cf_array_as::(&window_list_info) { - let raw_info = WindowInfo::new(raw_window_info); - let application = Application::new(raw_info.owner_pid)?; - if let Some(elements) = application.window_elements() { - for element in elements { - if let Ok(wid) = crate::ax_registry::identify(&element) - && i64::from(wid) == window_id - && let Ok(window) = Window::new(element, application.clone()) - { - let mut rule_debug = RuleDebug::default(); - let _ = window.should_manage(None, &mut rule_debug); - let schema = serde_json::to_string_pretty(&rule_debug)?; - - reply.write_all(schema.as_bytes())?; - } - } - } - } - } - } + SocketMessage::DebugWindow(window_id) => self.debug_window(window_id, &mut reply)?, SocketMessage::DisplayIndexPreference(index_preference, ref display) => { crate::settings::settings().update(|settings| { settings @@ -1663,6 +1634,53 @@ impl WindowManager { } } +impl WindowManager { + /// Minimizes the window that has the focus + pub fn minimize_foreground_window(&mut self) -> eyre::Result<()> { + let foreground_window = + MacosApi::foreground_window().ok_or_eyre("there is no foreground window")?; + AdhocWindow::minimize(&foreground_window)?; + Ok(()) + } + + /// Closes the window that has the focus + pub fn close_foreground_window(&mut self) -> eyre::Result<()> { + let foreground_window = + MacosApi::foreground_window().ok_or_eyre("there is no foreground window")?; + AdhocWindow::close(&foreground_window)?; + Ok(()) + } + + /// Answers with why the window of this id is, or is not, managed + pub fn debug_window( + &self, + window_id: i64, + reply: &mut impl std::io::Write, + ) -> eyre::Result<()> { + if let Some(window_list_info) = CoreGraphicsApi::window_list_info() { + for raw_window_info in cf_array_as::(&window_list_info) { + let raw_info = WindowInfo::new(raw_window_info); + let application = Application::new(raw_info.owner_pid)?; + if let Some(elements) = application.window_elements() { + for element in elements { + if let Ok(wid) = crate::ax_registry::identify(&element) + && i64::from(wid) == window_id + && let Ok(window) = Window::new(element, application.clone()) + { + let mut rule_debug = RuleDebug::default(); + let _ = window.should_manage(None, &mut rule_debug); + let schema = serde_json::to_string_pretty(&rule_debug)?; + + reply.write_all(schema.as_bytes())?; + } + } + } + } + } + Ok(()) + } +} + /// The window manager as the shared commands of `komorebi_core::command` see it impl komorebi_core::CommandHost for WindowManager { type P = crate::workspace::MacosPlatform; From f53060833f944c1ba27319b1ad672a0d3a4df598 Mon Sep 17 00:00:00 2001 From: LGUG2Z Date: Sat, 31 Oct 2026 20:15:02 -0700 Subject: [PATCH 7/8] docs: macos-hand-check-plan.md, one prioritised runbook for the Mac pass macos-handcheck.md grew by appending sections from several authors (A-H, the review checks H1-H12, deep-dedup rows, bar clicks, settings rows), so the owner had to merge them by hand. The new runbook orders every item by what could make the daemon unusable first: prerequisites, startup and the command path (shared transport, shared SocketMessage, lock order), hiding and restoring (shared Container/Workspace/Monitor, HideSpot), the window registry and leaks, the pointer preamble, settings reload, the rest of the walk-through, the bar, then the known issues that are expected to misbehave. Each item has steps, the expected result, how to stop or roll back, the revision that introduced it, a mark where a second display, trackpad or cables are needed, and a time estimate per block (about 5 hours in all). It opens with the list of commands that must not be run on a Mac that has a live komorebi (stop, start, quickstart, autostart, pkill, state-changing komorebic commands, SIGSTOP on pids not just started), with the reasons read from the code: a second daemon exits when a process named komorebi exists, and a daemon deletes the socket in the user data directory on exit. The original document is kept as the source. Commands were checked against the checked-in macOS docs/cli page list; nothing was run on a Mac. Not built. --- docs/dev/macos-hand-check-plan.md | 286 ++++++++++++++++++++++++++++++ 1 file changed, 286 insertions(+) create mode 100644 docs/dev/macos-hand-check-plan.md diff --git a/docs/dev/macos-hand-check-plan.md b/docs/dev/macos-hand-check-plan.md new file mode 100644 index 00000000..222d1adb --- /dev/null +++ b/docs/dev/macos-hand-check-plan.md @@ -0,0 +1,286 @@ +# macOS hand-check plan: one runbook for the Mac pass + +Status (wip-cand8, b6f4c2ae): OPEN. This is the ordered runbook that replaces reading +[macos-handcheck.md](macos-handcheck.md) top to bottom; that document stays as the source (rows A1-A..., B, C, D, +E, F, G, H and the review's H1-H12), and every item below says which row it came from. **Nothing here has been +run on a Mac as a daemon.** What did run, on a Mac Mini: `cargo build`, `clippy -D warnings`, `cargo test` (665 +passed, 0 failed, 1 ignored at candidate 8) and the nix builds of `komorebi`, `komorebic`, `komorebi-bar` and the +darwin checks. No window has been tiled, hidden, focused or bordered by these builds. + +How to read an item: **Steps**, **Expect**, **Stop / roll back**, **Introduced by** (jj bookmark or change id; +`jj log -r ` in the repository, commit ids move when a revision is rewritten). Items marked `[2 displays]`, +`[trackpad]`, `[physical]` need a second screen, a trackpad gesture, or someone to plug cables; `[2nd person]` is +useful where you cannot watch the screen and type at the same time. Block times are for a person who has the build +ready. + +Order is by what could make the daemon unusable first. If a block fails, stop there, write down the block, item, +macOS version and the log lines, and do not continue to later blocks that depend on it (blocks 3 onwards assume +hiding and the event loop work). + +## Do NOT run these on a Mac that has a live komorebi + +The owner's Mac Mini runs their own komorebi. This runbook is for another Mac, or for a clean run on the Mini +after quitting the live daemon on purpose. Reasons are in the code: a second `komorebi` process exits with +"komorebi is already running" (it counts processes named `komorebi`), and on exit or Ctrl-C a daemon deletes +`$DATA_DIR/komorebi.sock`; all `komorebic` commands talk to the socket in the user's data directory, so they +reach whichever daemon owns it. + +- Do not run `komorebic stop`, `komorebic stop --bar`, `komorebic start`, `komorebic quickstart`, + `komorebic enable-autostart` or `disable-autostart` (they run `launchctl load/unload`), `pkill`/`killall` + `komorebi` or `komorebi-bar` (`stop --bar` runs `pkill komorebi-bar`), or Ctrl-C the test daemon while the live + one shares the data directory. +- Do not run any `komorebic` command that changes state (`replace-configuration`, + `ignore-rule`, `session-float-rule`, `toggle-pause`, `focus-*`, `stack`, ...) unless you know which daemon it + reaches. `komorebic state` and `komorebic --help` are read-only. +- Do not `kill -STOP` or `kill -CONT` a pid you did not just start; items 8.2 and 8.3 are the only ones that use + signals and must use the pid of the test daemon or test bar, taken from `pgrep` right after you start them. +- Do not `cargo install`, `brew install/upgrade komorebi*` or overwrite the installed binaries; run from + `target/debug`. +- Do not use your real `~/.config/komorebi`: use the clean config in 0.2. +- Do not test on the live Mac's Accessibility grant by removing and re-adding it in System Settings; grant the + terminal that runs the test build. + +A clean run on the Mini needs: quit the live daemon and bar in the way you normally do, confirm with +`pgrep -l komorebi` that nothing is left, run the runbook, then start your own again. `launchd` will restart an +auto-started daemon unless you disabled autostart yourself first. + +## Block 0. Prerequisites and a build you can trust (about 25 min) + +**0.1 Build and test.** From the repository root, with a `.git` checkout (or `COMMIT_HASH=dev`): + +```sh +cargo build --locked -p komorebi -p komorebic -p komorebi-bar +cargo test --locked -p komorebi-macos -p komorebic -p komorebi-client -p komorebi-bar-core -p komorebi-bar -p komorebi-core -p komorebi-config -p komorebi-protocol +cargo clippy --locked -p komorebi -p komorebi-macos -p komorebic -p komorebi-client -p komorebi-bar -p komorebi-bar-core --all-targets -- -D warnings +``` + +Never name `-p komorebic-macos` together with `-p komorebic` (same binary name). Expect: 0 failures (the Mini +saw 665 passed, 0 failed, 1 ignored). Roll back: nothing to do; if a test fails, stop and report its name. + +**0.2 A clean config and data directory.** Make an empty directory for the run, put a minimal +`komorebi.json` in it (copy `komorebi-for-mac/docs/komorebi.example.json`), and set `KOMOREBI_CONFIG_HOME` to it. +The data directory (socket, logs) is the user's `~/Library/Application Support/komorebi`, which this variable does +not change; use another Mac or a throwaway macOS user if you cannot guarantee the live daemon is not running. +Expect: `pgrep -l komorebi` prints nothing before you start. + +**0.3 Permissions.** System Settings, Privacy and Security: grant Accessibility and Screen Recording to the +terminal you start the daemon from. Start the daemon in a visible terminal so you can Ctrl-C it: +`RUST_LOG=komorebi=debug target/debug/komorebi 2>&1 | tee run.log`. + +**0.4 Baseline for comparison (optional).** Build the baseline ancestor `ff3711dc` of `wip-main` in another +checkout; a recording with `komorebi-recorder` on both builds makes before/after comparisons exact. The items +below say "as before" where this matters. + +## Block 1. Startup, event loop and the command path (about 40 min) + +The riskiest changes: the daemon now starts from a shared `daemon::run`, the command listener, pause filter, +subscriber push and event channel are the shared transport, and `SocketMessage` is the shared enum. + +**1.1 Start and stop.** Steps: start the daemon (0.3); in another terminal `target/debug/komorebic state | head`, +`komorebic global-state | head`, `komorebic --version`, `target/debug/komorebi --version` (expect `komorebi 0.1.0` +with the macOS version crate). Then Ctrl-C the daemon. Expect: state is JSON; the daemon logs the restore of all +windows and exits (code 130), all windows are back where they were, `komorebi.sock` is gone. Stop: Ctrl-C; if the +daemon does not exit, `kill` the pid you started (not `pkill`). Introduced by: `wip-u-pkg2` (one `komorebi` +package, `1326f041`) and the shared transport revisions `nvwvptpv`, `ywwwwpwm`, `kzynysto`. + +**1.2 Every command is answered.** Steps: run one command of each family: `focus left`, `move left`, +`resize-axis horizontal increase`, `stack`, `unstack`, `toggle-float`, `toggle-monocle`, `focus-workspace 1`, +`cycle-workspace next`, `toggle-pause` twice. Expect: each returns promptly; the log shows no +"could not acquire window manager lock". Introduced by: `lrqkuuzq`, `sowrttxs` (one `SocketMessage`), `nvwvptpv`. +Also `komorebic debug-window ` for a real window id from `state`, if your build lists it in `komorebic --help`. + +**1.3 Pause filter.** `komorebic toggle-pause`; while paused only `toggle-pause`, `state`, `global-state`, `stop` +work, everything else is ignored; unpause and check that windows tile again. Introduced by: `ywwwwpwm`. + +**1.4 Reload loop (the lock order).** Steps: in one terminal run `for i in $(seq 50); do komorebic +replace-configuration clean/komorebi.json; done` while you open +and close Finder windows and Terminal tabs. Expect: every call answered, no hang, new windows still tile; float, +ignore and manage rules from the config and from `komorebic session-float-rule`, `ignore-rule`, `manage-rule` still apply. +Stop: if the daemon stops answering, copy the log, `kill` the test daemon. Introduced by: `ummqkuvp` 01b9cbed +(one lock order; before it the order could deadlock) and `wip-u-rulematch` (the shared rule matcher: also try a +regex rule and a composite rule). + +**1.5 Event channel under load.** Drag a window edge continuously (live resize), pan with the trackpad +`[trackpad]`, and switch workspaces with 10 or more windows. Expect: no stalls, no repeated "drop" warnings, the +layout follows. Introduced by: `ovsplvmn` (shared `EventChannel`). + +**1.6 Subscribers.** `komorebic subscribe-socket mytest` in a terminal (and with options): events arrive for focus, +move, workspace change, monitor change, theme and config reload; kill the subscriber (Ctrl-C) and confirm the +daemon keeps answering. Introduced by: `kzynysto`. + +Block done when: 1.1 to 1.6 hold. Do not go on if 1.1 or 1.4 fail. + +## Block 2. Hiding and restoring windows (about 45 min; `[2 displays]` for 2.1) + +The daemon's `Container`, `Workspace` and `Monitor` are now the shared `komorebi-core` types and hiding takes a +`HideSpot`. A bug here leaves windows stuck in a corner or lost. + +**2.1 Hide spot on the right display (review H1) `[2 displays]`.** Steps: a window straddling the left edge of +display 2 (drag it half off). Switch workspace on display 2 and back. Repeat with `window_hiding_position: +"BottomRight"` in the monitor config (then `komorebic replace-configuration`). Stacks: `stack` three windows, +`cycle-stack`. Expect: the window is hidden in the `BottomLeft` corner of display 2 (not display 1, not left in +view) and restored to the same frame; only the front window of a stack is visible, the others sit in the corner. +Stop: Ctrl-C the test daemon (it restores every window on exit). Introduced by: `wip-u-kfm2` (Container, Workspace, +Monitor), the `HideSpot` revisions `ywowyyrz` and `losvwsls`, `wip-u-mac-deep` (`wlmxvuso`, `pulywuwk`, BEHAVIOUR: +the corner now comes from the workspace, not the monitor). + +**2.2 Stacks, monocle and floating (H2 and the deep-dedup rows).** `toggle-float` a window, switch workspaces +twice: it hides and returns at its old frame. `toggle-monocle`, switch and back; with `window_hiding_position: +"BottomRight"` every other container parks in that corner while monocle is on; `cycle-focus` while monocle is on; `stack-all`; +change `window_hiding_position` in the config, reload and toggle monocle at once: the +corner must be the new one. Introduced by: `wip-u-mac-deep`. + +**2.3 Workspaces.** `focus-workspace`, `send-to-workspace`, `move-to-workspace`, `cycle-move-to-workspace`, +`cycle-move-to-monitor` `[2 displays]`: windows of the workspace you left are hidden, those of the new one +restored where they were; focus-workspace by name too. Introduced by: `wip-u-kfm2`, `wip-u-cmd` (the moves are the +shared `komorebi-core::command` since candidate 7). + +**2.4 Router arms moved to methods.** `toggle-workspace-layer` twice; `resize-axis horizontal|vertical +increase|decrease`; `session-float-rule` on a window; `ignore-rule exe ` and `title`/`class` (matching +windows leave the workspaces); `replace-configuration ` (windows re-laid out under the new +configuration; with a broken file the daemon is left alone). Introduced by: `wip-u-mac-deep` (`tkpoootr`). + +**2.5 Minimize, unminimize, close.** `minimize`, `close`, un-minimize from the Dock; closing removes the window +from its container. Introduced by: `Window` methods taking `&self` (`nrsnmwmo`). + +Block done when: no window is ever left in a corner after unstack, quit or Ctrl-C, and `komorebic state` keys of a +container, workspace and monitor are unchanged (a container has `id`, `locked`, `windows.{elements,focused}`; a +monitor ends with `window_hiding_position`). + +## Block 3. The window registry and leaks (about 40 min) + +The daemon keeps a table from window id to Accessibility element (`ax_registry`) with retained references and +observers. Failures here show as memory growth or a hang, not as a wrong tile. + +**3.1 Registry growth (H4).** Note `lsof -p $(pgrep -x komorebi) | wc -l` and `lsmp -p $(pgrep -x komorebi) | +tail -1` (Mach ports). In TextEdit open and close the Open and Save panels 200 times. Expect: no steady growth +(it also answers whether an `AXObserver` holds a port). Introduced by: `oywqqkuy`, `wip-u-kfm3`. + +**3.2 Quit apps (H6).** `toggle-pause`, quit an app with managed windows, `toggle-pause`: its windows are gone from +`komorebic state`; with `RUST_LOG=debug` no new errors at quit; open and close 50 windows (Finder, Terminal, +Safari) and quit several apps: the daemon's memory in Activity Monitor does not climb. Introduced by: `wip-u-kfm3` +(`forget_pid`, forget on reap). + +**3.3 Native tabs (H7).** Finder or Terminal with two native tabs: switch tab, close the first tab, open a new +tab, focus the window with `komorebic focus`, move and resize it. Expect: the window stays managed, focus works, +`komorebic state` shows one window id per container with no duplicates, no stuck border. Introduced by: +`oqnvyqvw` e0687167, `wip-u-kfm3`. + +**3.4 A many-window app and a stopped one (H3).** Chrome with about 20 windows: restart the test daemon and note +the time to ready in the log against the baseline build. Then `kill -STOP ` +and press `komorebic focus right` 5 times, then `kill -CONT `: commands are handled again within the AX +timeout after the CONT; a log line `invalidating application observer for process id` for a live app after the CONT +is the bug. Stop: always `kill -CONT` the app. Use the pid of a throwaway app (TextEdit), never of a system process. + +## Block 4. Pointer picks the monitor (about 10 min, `[2 displays]`) + +**4.1** An empty workspace on the second display with the pointer over it while the first display is focused: +`komorebic focus-workspace 1`, `focus-workspaces 1` and `focus-last-workspace` first focus the display under the +pointer, then switch its workspace (before, `focus-workspace` and `focus-workspaces` acted on the focused display). +With the pointer on the focused display nothing changes. Stop: move the pointer back and `focus-workspace` again. +Introduced by: `wip-u-ptr` (BEHAVIOUR, owner decision; shared `focus_workspace_number(s)`; macOS check H1 of +section H of the old list). + +## Block 5. Settings and configuration reload (about 30 min) + +Run settings are one snapshot (`komorebi-settings`) instead of statics. Test with `replace-configuration` or a +restart. + +**5.1 Paddings, aspect ratio, layout defaults, display preferences (H9, G.1).** `default_workspace_padding` 20 and +`default_container_padding` 15: tiles 20 px from the work area and 15 apart on every workspace, not only the +focused. Drop the key and reload: padding stays; set 5: 5. `layout_defaults`: set, reload, workspaces use it; remove +and reload: reset. `floating_window_aspect_ratio`: `toggle-float` with centring uses it; remove and reload: 4:3. +`display_index_preference 0 `: monitor order follows it. Reload during a drag or workspace switch: no +one-frame flash of half-new padding. Introduced by: `wip-u-settings2`, `wip-u-settings3` (`qsxslsmy`). + +**5.2 Animation (G.2, BEHAVIOUR).** `komorebic animation true`, switch workspace: a transition plays. During one, +`animation-duration 1000`, `animation-style`, `animation false`: the running transition is not torn, the next one +follows the new values. `animation true --movement` then `animation false`: movement is off again. Reload a file +with `"animation": {"enabled": {"movement": true}}`: only movement animates; with `"enabled": true` and no fps: fps +60; with no animation block: values keep. `animation-fps 30`. `stack` a window: no animation during the stack, back +after it. Introduced by: `mquxryqt` (settings S5). + +**5.3 Schema and config loading (H-rows).** A real `komorebi.json` of yours loads with no new warning and every key +works (borders, padding, animations, scrolling, rules, workspaces); `komorebic static-config-schema` equals +`komorebi-for-mac/schema.json`. Introduced by: `kvtvnouo`, `stxmqnop` (StaticConfig from `komorebi-config`). + +## Block 6. The rest of the daemon walk-through (about 60 min) + +Compare with the baseline build where you can. Source: section C of the old list, with the Introduced-by rows A +and B for bisecting a regression (the B rows only rename and route: a failure there means a call went to the wrong +receiver). + +6.1 Focus: `focus left|right|up|down`, `cycle-focus`, `focus-stack-window `, mouse-follows-focus on and off, a tabbed +app (right tab focused). 6.2 Move and resize: `move`, `resize-axis`, `resize-edge`, a manual drag (the layout +puts the window back), live resize of one edge moves the neighbour, a fixed-size app. 6.3 Scrolling workspace (H8) +`[trackpad]`: `change-layout scrolling`, 5 windows, pan with the gesture and with `focus left/right`; scrolled-out +windows park at the screen edge (not the corner) and return on focus; switch workspace and back; consume, expel, +resize a column. 6.4 Borders: colours follow focus and animated windows; vanish and return on workspace switch; +none left behind after closing. 6.5 Animations on and off, ghost images, cancel by a new command mid-way. 6.6 Display +change `[physical]`: plug or unplug a monitor or change the resolution: work areas update, workspaces go to the +right monitors, rules re-apply (this is the thread that may deadlock, see 8.4). 6.7 Sleep and wake `[physical]`: +windows where they were, daemon answers, bar returns. 6.8 Start and stop: `komorebic start --bar`, `start +--await-configuration`, `stop`, `stop --bar` **only on a Mac with no live komorebi**, and `komorebic --help` plus a +few ` --help` texts (about 15 help texts now use the Windows wording). Introduced by: rows B and the +`komorebic` revisions `qukywpss`, `zwkwptox`, `sxptsttt` (shared launcher and pan). + +## Block 7. The bar (about 25 min) + +The bar is now the `komorebi-bar` package (module `macos`) over `komorebi-bar-core`, with `sysinfo` 0.39 and +`starship-battery` 0.11. + +**7.1 Renders.** `target/debug/komorebi-bar` against the running test daemon: workspaces, layout, CPU %, memory, +battery % and charging, date and the calendar icon, all sane. `komorebi-bar --schema | cmp - komorebi-for-mac/schema.bar.json` +is silent. Introduced by: `wip-u-pkg-mig` bar revisions (`7d4ea893`, `bdd811f2`), `nottqpms` and the bar-core hooks. + +**7.2 Old state and the bar (H10).** `komorebic state > old.json` on the ORIGINAL build; start the new bar against +the new daemon and confirm it renders; the new daemon's `state` parses in the bar. + +**7.3 Bar config (H11).** A Keyboard, Media and Systray widget and a `mouse` block in `komorebi.bar.json`: the bar +starts, logs "the Keyboard widget is not supported on this platform and is skipped" (three times) and the `mouse` +warning, and renders the other widgets. Break the file (`"mouse": {"on_scroll_up": 5}` or an unknown widget): the bar +refuses to load it with an error. Introduced by: bar decision (macOS accepts and skips Windows-only keys). + +**7.4 Clicks (old M1-M3).** Battery click opens System Settings on the Battery pane (macOS 13 or later; write down +the macOS version and what opened if wrong); CPU and memory click opens Activity Monitor; network opens the +Network pane; storage opens the folder in Finder; update widget (installed version older than the latest release) +shows the new version and the click opens `https://github.com/LGUG2Z/komorebi-for-mac/releases/tag/v`; +after 12 hours (or a small `data_refresh_interval`) it still compares against komorebi-for-mac releases. +Introduced by: `tpwlsxpm`, `tsxllpxz`. + +## Block 8. Known issues to confirm (about 20 min; these are expected to misbehave) + +**8.1 Unsupported commands (H12).** `echo '"ToggleMaximize"' | nc -U "$HOME/Library/Application Support/komorebi/komorebi.sock"`: +a not-supported reply, no state change, the daemon keeps running. + +**8.2 Hung subscriber (H5, known, not fixed).** `kill -STOP $(pgrep komorebi-bar)` (the bar you started in 7), +then `komorebic focus left` 10 times and watch the log for "could not acquire window manager lock": the daemon is +expected to stop reacting once the socket buffer fills. Roll back: `kill -CONT` that bar pid. See +[known-issues.md](known-issues.md) item 4. + +**8.3 Deadlock window (old bug A, by reading only).** Spam `komorebic retile` and workspace switches (with +animations) while plugging and unplugging a monitor `[physical]`; the symptom is a daemon that answers no command +(`komorebic state` hangs). Stop: `kill` the test daemon; windows may stay hidden, so quit it with Ctrl-C if it still responds (the daemon +restores windows on exit), otherwise `kill` it and move the hidden windows back by hand. + +**8.4 Other bugs on the old list (D, B, C)** that remain by design: raw Accessibility calls outside `Window`, the +update widget second URL (now fixed by `tsxllpxz`), the `cmd.exe`/`explorer.exe` clicks (fixed by `tpwlsxpm`). + +## Time and what to report + +| Block | Needs | Time | +|---|---|---| +| 0 prerequisites | build, a spare Mac | 25 min | +| 1 startup and command path | 1 display | 40 min | +| 2 hiding and restoring | 2 displays for 2.1, 2.3 (monitor move) | 45 min | +| 3 registry and leaks | Activity Monitor, `lsof`, `lsmp` | 40 min | +| 4 pointer picks the monitor | 2 displays | 10 min | +| 5 settings and reload | none | 30 min | +| 6 walk-through | trackpad, display cables, lid | 60 min | +| 7 bar | none | 25 min | +| 8 known issues | cables | 20 min | +| total | | about 5 hours | + +Report per item: block and item number, macOS version, pass or fail, and for a failure the `run.log` lines and +`komorebic state`. A failure in Block 1 or 2 blocks landing any further macOS change; failures in later blocks are +bugs to fix in the revision named under Introduced by. From 85f8e2af2b189680a35a91abf76c9e69168a470e Mon Sep 17 00:00:00 2001 From: LGUG2Z Date: Sat, 31 Oct 2026 20:18:26 -0700 Subject: [PATCH 8/8] docs(core): section 23, the macOS side of the shared router and WindowManagerPlatform Records, while kfde's gate_message hook and WindowManagerPlatform trait did not exist yet: macOS gates every message with the same call at the same place as KDE (so the default gate_message needs no macOS override), the macOS entry points as hooks with their size and seam note (focus_workspace keeps the pre-existing main-queue dispatch under the lock, no hook adds one), what was done meanwhile (Minimize, Close, DebugWindow as methods; push_simple_rule), and that update stays macOS's (D-coord-15). Verified: documentation only. --- docs/dev/core-model.md | 35 +++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) diff --git a/docs/dev/core-model.md b/docs/dev/core-model.md index 6452fff9..0d60ea57 100644 --- a/docs/dev/core-model.md +++ b/docs/dev/core-model.md @@ -1597,3 +1597,38 @@ because of a borrow, and Windows has no such need: they stay as they are). 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. + +## 23. The macOS side of the shared router and `WindowManagerPlatform` (kfm, wip-u-mac-wm2) + +Written while kfde's `gate_message` hook and `WindowManagerPlatform` trait (branch `wip-u-wm2`) did +not exist yet, so nothing here implements them; it records what macOS needs and what was done meanwhile. + +**The gate (22.1).** macOS calls `handle_unmanaged_window_behaviour()` once, in `process_command`, after +`State::from` and before the `match`, for every message: the same call at the same place as KDE (KDE has +`is_layout_command` and maximized check before it, which macOS does not need, and macOS has a space-id +return before it, which KDE does not have). The body is the same text. So the default `gate_message` +(call it for every message) is what macOS does today, and macOS needs no override. + +**Entry points as hooks** (the table of 22.2 for macOS; none takes the window manager lock from a main +queue closure, none dispatches to main itself; the ones that already block main under the lock keep the +hazard of `seam.md` 3.3 and do not add one): + +| function | what it is on macOS | hook shape | seam note | +|---|---|---|---| +| `new(run_loop, incoming, custom_socket_path)` (50 lines) | takes the main run loop; builds monitors from nothing; a thin forward as `P::new(..)` needs the run loop as a platform argument | `fn new(&PlatformArgs) -> WindowManager` with the run loop in the platform's args | no lock | +| `init` (5 lines) | `MacosApi::load_monitor_information` then `load_workspace_information` (AX and CoreGraphics, on the calling thread) | `fn init(&mut WindowManager)` | runs before the daemon's threads start (main.rs), no lock contention | +| `stop(ignore_restore)` (26 lines) | restores windows, writes the state, closes subscriber sockets (takes `SUBSCRIPTION_SOCKETS`), exits | `fn stop(..)` | takes only the registry-like statics, not the WM lock again | +| `restore_all_windows(ignore_restore)` (17 lines) | AX restore per window | the shared part is the loop; the restore is `Container::restore` with the spot | AX under the WM lock, as before | +| `focus_workspace` (38) | calls `border_manager::hide_borders_on`, an `exec_sync` to main **under the WM lock** (the pre-existing hazard of 3.3) | hook `workspace_transition` | unchanged hazard; the hook must not make it worse (no second dispatch) | +| `resize_window` (240), `move_container_to_monitor` (130), `focus_floating_window_in_direction` (245), `enforce_workspace_rules` (202), `manage_focused_window` and `unmanage_focused_window` (19, 15) | the live-resize and AX identity code | stay macOS's; not hooks | | + +`ReplaceConfiguration` is `replace_configuration`, taking the run loop from `self` (section 22 of this +document says it is a method since the deep dedup); the hook, if any, is `P::preload`. + +**Done meanwhile.** `Minimize`, `Close` and `DebugWindow` are methods on both daemons (the arms are the same +text, the bodies the platform's); the ignore and manage rules use the shared `push_simple_rule` +(kind and id; macOS used to compare only the id, a small fix). + +**`update` stays macOS's** (D-coord-15): section 22 gives the two blockers (the scrolling early return and +the width of the SkyLight batch), and the shared `WindowManager

` does not need `update`: it calls +`update_focused_workspace`, which is the daemon's.