diff --git a/docs/dev/bar-e2e.md b/docs/dev/bar-e2e.md index b83ef1e0..1bf78358 100644 --- a/docs/dev/bar-e2e.md +++ b/docs/dev/bar-e2e.md @@ -11,7 +11,7 @@ E2E_GOLDEN=golden KOMOREBI_E2E_SCALE=1.5 nix run .#e2e-windows -- OUT bar # another commit: build-ref.sh REF bins; KOMOREBI_E2E_BINS=bins ... (bins must have komorebi-bar.exe) ``` -It checks: the `--schema` output equals `schema.bar.json`; the configuration (storage, time, +It checks: the `--schema` output equals `schemas/windows/schema.bar.json`; the configuration (storage, time, applications, komorebi workspaces and layout, Keyboard, Systray, a `mouse` block with a message and a command) is accepted and the bar starts; its window appears; it keeps running 15 s; the daemon keeps answering and does not tile the bar; the bar survives the daemon stopping and starting again diff --git a/docs/dev/bar-unification.md b/docs/dev/bar-unification.md index b9484b71..5cdb8219 100644 --- a/docs/dev/bar-unification.md +++ b/docs/dev/bar-unification.md @@ -2,6 +2,8 @@ > **Status (wip-cand4):** B0-B3 done (one `komorebi-bar` package, a module per platform, schema views); B4 (merging the rendering code) not done and cannot be shown mechanical without a screen; macOS bar never rendered by these changes. +> **Paths (cutover stack):** this document was written before the directories were renamed and keeps the paths of its time. Now: `komorebi/` is `komorebi-windows/`, `komorebi-for-kde/komorebi/` is `komorebi-linux/`, `komorebi-for-mac/komorebi/` is `komorebi-macos/`, `komorebi-for-kde/komorebi-hotkeys/` is `komorebi-hotkeys/`, `komorebi-for-kde/nix/` and `komorebi-for-mac/nix/` are `nix/linux/` and `nix/macos/`, `komorebi-for-kde/docs/` and `komorebi-for-mac/docs/` are `docs/linux/` and `docs/macos/`, `schema*.json` are in `schemas/{windows,linux,macos}/`, and every package is at version 0.2.0 (the 0.1.x numbers below are history). + Status at the revision that adds this file. Everything below was measured on this tree with `diff` (counts are lines that differ, `<`/`>` lines of `diff`, hunks in parentheses). Nothing here was rendered: the bars cannot run on Linux. Gates that did run are named; the ones that diff --git a/docs/dev/core-model.md b/docs/dev/core-model.md index 369ae503..7969e5ad 100644 --- a/docs/dev/core-model.md +++ b/docs/dev/core-model.md @@ -2,6 +2,8 @@ > **Status (wip-cand4):** measurement plus a running log. `komorebi-core` has `Container`, `Monitor`, `Workspace` (incl. `update_shared`) over KDE, Windows and macOS; `WindowManager
`, the router and `process_event` are NOT shared yet (sections 17 and 18 give the blockers); sections 8 and 12 are the designs that were then implemented. +> **Paths (cutover stack):** this document was written before the directories were renamed and keeps the paths of its time. Now: `komorebi/` is `komorebi-windows/`, `komorebi-for-kde/komorebi/` is `komorebi-linux/`, `komorebi-for-mac/komorebi/` is `komorebi-macos/`, `komorebi-for-kde/komorebi-hotkeys/` is `komorebi-hotkeys/`, `komorebi-for-kde/nix/` and `komorebi-for-mac/nix/` are `nix/linux/` and `nix/macos/`, `komorebi-for-kde/docs/` and `komorebi-for-mac/docs/` are `docs/linux/` and `docs/macos/`, `schema*.json` are in `schemas/{windows,linux,macos}/`, and every package is at version 0.2.0 (the 0.1.x numbers below are history). + Status: measurement and proposal (plan step 9 preparation, KDE side). Measured at the tip of `wip-u-kfde` (based on `wip-main` 633e7453); the Windows tree is `komorebi/src`, KDE is `komorebi-for-kde/komorebi/src`, macOS (`komorebi-for-mac/komorebi/src`) is listed only where it diff --git a/docs/dev/e2e-to-unit.md b/docs/dev/e2e-to-unit.md index 62e63124..b9e1de7c 100644 --- a/docs/dev/e2e-to-unit.md +++ b/docs/dev/e2e-to-unit.md @@ -1,5 +1,7 @@ # From e2e to unit: what the shared crates made testable natively +> **Paths (cutover stack):** this document was written before the directories were renamed and keeps the paths of its time. Now: `komorebi/` is `komorebi-windows/`, `komorebi-for-kde/komorebi/` is `komorebi-linux/`, `komorebi-for-mac/komorebi/` is `komorebi-macos/`, `komorebi-for-kde/komorebi-hotkeys/` is `komorebi-hotkeys/`, `komorebi-for-kde/nix/` and `komorebi-for-mac/nix/` are `nix/linux/` and `nix/macos/`, `komorebi-for-kde/docs/` and `komorebi-for-mac/docs/` are `docs/linux/` and `docs/macos/`, `schema*.json` are in `schemas/{windows,linux,macos}/`, and every package is at version 0.2.0 (the 0.1.x numbers below are history). + Base: `wip-cand5` plus the revisions that add the tests named here. Written 2026-10-31. Before the shared crates, the Windows daemon could only be tested through a Windows guest (its crate @@ -43,7 +45,7 @@ times (Windows `komorebi/src/window.rs:1178`, KDE `window.rs:661`, macOS `window | maximizing (29) | toggle-maximize, unmaximize on float, monocle wins | A: `workspace_layers.rs` `floating_the_maximized_window_*`, `update_shared.rs` `the_monocle_container_wins_over_a_maximized_window`; user-maximize event C | - | - | med | | promoting (4), moving (4), focus (7) | promote first tile, swap/cycle-move, focus order | A: `workspace_containers.rs` `promoting_*`, `swapping_containers_*`, `cycling_wraps_*`, `directions_follow_the_layout_and_the_flip`; focus OS agreement C | - | - | low | | workspaces (8), workspace_moves (8) | send/move/focus workspace, last-workspace | A: `monitor_workspaces.rs` (focus, last focused, ensure, remove); the OS hide/show is C | - | - | med | -| commands (265, 7.6 min) | every komorebic command leaves the daemon alive, answers state, manages every window | A now for command line (`crates/komorebic-core/tests/e2e_sweep.rs`: every SWEEP/PRINTED line is a Windows command; macOS lacks exactly 8) and for the KDE model (`komorebi-for-kde/komorebi/tests/command_sweep.rs`, about 185 messages, 0.2 s); B: same sweep for the Windows and macOS daemons (needs seam, below); C: stall-family (daemon busy 8 s), socket answering | S done / L for Win+mac | highest: biggest, flakiest scenario | +| commands (265, 7.6 min) | every komorebic command leaves the daemon alive, answers state, manages every window | A now for command line (`crates/komorebic-core/tests/e2e_sweep.rs`: every SWEEP/PRINTED line is a Windows command; macOS lacks exactly 8) and for the KDE model (`komorebi-linux/tests/command_sweep.rs`, about 185 messages, 0.2 s); B: same sweep for the Windows and macOS daemons (needs seam, below); C: stall-family (daemon busy 8 s), socket answering | S done / L for Win+mac | highest: biggest, flakiest scenario | | unknown_monitor (12) | a window sent to a monitor that does not exist stays managed | B: shared `Monitor`/`Workspace::add_container` errors are covered (`monitor_workspaces.rs` `adding_a_container_to_a_workspace_that_is_not_there_is_an_error`); the daemon handler is per platform: needs seam | M | med (known flaky marker) | | rules (12), rules_class (5), rules_exe (5), manage_rules (4), title_rule (5), startup_rules (5) | which window a rule catches (kind, strategy, composite, last wins, manage over ignore); the workspace it goes to | A now for matching, once for all three daemons: `crates/komorebi-config/tests/rule_matching.rs` (16 tests, KDE/macOS and Windows input shapes; the matching moved to `komorebi_config::rules`, see `docs/dev/rule-matching.md`); KDE keeps the manage-rule rescue test. Workspace of a rule: A in core: `workspace_containers.rs` `initial_placement_rules_choose_where_a_new_window_goes`. When-evaluated (open vs rename), hide/show: C | M to move the function into `komorebi-config` and test once for three daemons (recommended seam) | high | | state_fidelity (5) | state names title/exe/class/path as opened | A: `state_roundtrip.rs` (kfw/kfde fixtures, `the_fixtures_are_the_ones_the_e2e_library_has`, `a_windows_tiled_state_is_written_as_it_was_read`); what the OS reports C | - | - | low | @@ -70,7 +72,7 @@ dependent and meant for the Mini: the hide-spot corner per monitor (`hide_spot` ## KDE VM suites (33 suites with a test.py) All of them need a headless or Plasma KWin: C. The model parts of them are already native through -the KDE tests (`komorebi-for-kde/komorebi/tests`, about 880): `core-e2e` and `hotplug`, `placement`, +the KDE tests (`komorebi-linux/tests`, formerly `komorebi-for-kde/komorebi/tests`, about 880): `core-e2e` and `hotplug`, `placement`, `workspace-rules`, `scrolling`, `stacks`, `user-maximize`, `commands`, `core-lock`, `focus-follows-mouse`, `wallpaper` have a native model twin; `kwin*`, `check`, `module`, `keys-*`, `look`, `features`, `rdp`, `render-smoke`, `latency`, `client-geometry`, `drag-resize`, @@ -134,8 +136,8 @@ Not saved: boot and golden image (3 s from a state), the C scenarios. |---|---|---| | `komorebi-layouts/tests/layouts_everywhere.rs` | 8 | layouts, flipping, layout_flip, padding, tiling, closing | | `crates/komorebi-core/tests/e2e_layouts.rs` | 6 | layouts, flipping, layout_flip, padding, closing, minimizing, floating, stacks, tiling, tiling_off | -| `komorebi-for-kde/komorebi/tests/rule_matching.rs` | 13 | rules, rules_class, rules_exe, manage_rules, title_rule | -| `komorebi-for-kde/komorebi/tests/command_sweep.rs` | 1 (185 messages) | commands | +| `komorebi-linux/tests/rule_matching.rs` | 13 | rules, rules_class, rules_exe, manage_rules, title_rule | +| `komorebi-linux/tests/command_sweep.rs` | 1 (185 messages) | commands | | `crates/komorebic-core/tests/e2e_sweep.rs` | 3 | commands | Each test says what stays e2e: the OS frame equals the tile, borders, event timing, the daemon's own diff --git a/docs/dev/known-issues.md b/docs/dev/known-issues.md index 1b073c7f..b7db67c7 100644 --- a/docs/dev/known-issues.md +++ b/docs/dev/known-issues.md @@ -1,12 +1,14 @@ # Known issues that need a decision +> **Paths (cutover stack):** this document was written before the directories were renamed and keeps the paths of its time. Now: `komorebi/` is `komorebi-windows/`, `komorebi-for-kde/komorebi/` is `komorebi-linux/`, `komorebi-for-mac/komorebi/` is `komorebi-macos/`, `komorebi-for-kde/komorebi-hotkeys/` is `komorebi-hotkeys/`, `komorebi-for-kde/nix/` and `komorebi-for-mac/nix/` are `nix/linux/` and `nix/macos/`, `komorebi-for-kde/docs/` and `komorebi-for-mac/docs/` are `docs/linux/` and `docs/macos/`, `schema*.json` are in `schemas/{windows,linux,macos}/`, and every package is at version 0.2.0 (the 0.1.x numbers below are history). + Findings of the consolidation reviews and tests that are NOT fixed because whether they are bugs, or how to fix them, is a decision for the owner. Each has the evidence, why it may or may not be a bug, the platforms, and a proposed fix. Paths are relative to the repository root at the time of writing and may have moved. ## 1. RESOLVED (wip-u-ptr): KDE FocusWorkspaceNumber, FocusWorkspaceNumbers and FocusLastWorkspace skipped the pointer-monitor preamble -- **Resolution**: the owner approved Windows behaviour for all platforms. The preamble now runs for all three daemons in the shared `komorebi_core::command` functions (`focus_workspace_number`, `focus_workspace_numbers`, `focus_last_workspace`, and the others). KDE is covered by `komorebi-for-kde/komorebi/tests/pointer_monitor.rs`, core by `crates/komorebi-core/tests/commands.rs`. Owed: KDE VM commands and workspace-switch, macOS hand check H1 (docs/dev/macos-handcheck.md). The text below is the original finding. +- **Resolution**: the owner approved Windows behaviour for all platforms. The preamble now runs for all three daemons in the shared `komorebi_core::command` functions (`focus_workspace_number`, `focus_workspace_numbers`, `focus_last_workspace`, and the others). KDE is covered by `komorebi-linux/tests/pointer_monitor.rs`, core by `crates/komorebi-core/tests/commands.rs`. Owed: KDE VM commands and workspace-switch, macOS hand check H1 (docs/dev/macos-handcheck.md). The text below is the original finding. -- **Evidence**: komorebi-for-kde/komorebi/src/process_command.rs lines 1245-1277: the arms for the three messages call `focus_workspace` on the focused monitor directly. The Windows daemon (komorebi/src/process_command.rs:972-987 for `FocusWorkspaceNumber`, and lines about 2185 and 2215 for the helpers behind `FocusLastWorkspace` and `FocusWorkspaceNumbers`) first checks `monitor_idx_from_current_pos()`: when the pointer is on another monitor whose focused workspace is empty, that monitor becomes the focused one. KDE has the same preamble only in `cycle_focus_workspace` (line 897-909). +- **Evidence**: komorebi-for-kde/komorebi/src/process_command.rs [now komorebi-linux/src/process_command.rs] lines 1245-1277: the arms for the three messages call `focus_workspace` on the focused monitor directly. The Windows daemon (komorebi/src/process_command.rs [now komorebi-windows/src/process_command.rs]:972-987 for `FocusWorkspaceNumber`, and lines about 2185 and 2215 for the helpers behind `FocusLastWorkspace` and `FocusWorkspaceNumbers`) first checks `monitor_idx_from_current_pos()`: when the pointer is on another monitor whose focused workspace is empty, that monitor becomes the focused one. KDE has the same preamble only in `cycle_focus_workspace` (line 897-909). - **Why it may be a bug**: on a secondary monitor with an empty workspace and the pointer on it, `focus-workspace 2` switches the workspace of the monitor that was focused before, not the one the user is pointing at, unlike on Windows and unlike KDE's own `cycle-focus-workspace`. **Why not**: KWin may not report an empty monitor as pointed at the same way; the KDE tests do not cover it, so it may have been left out on purpose. - **Platforms**: KDE only (the Windows and macOS daemons are not known to be affected; not checked on macOS). - **Proposed fix**: add the preamble to the three arms, with a KDE unit test that the monitor under the pointer becomes the focused one; needs the owner to say which behaviour is intended. diff --git a/docs/dev/rule-matching.md b/docs/dev/rule-matching.md index fbed6e89..fbd8b531 100644 --- a/docs/dev/rule-matching.md +++ b/docs/dev/rule-matching.md @@ -1,5 +1,7 @@ # Window-rule matching: the three copies and the shared one +> **Paths (cutover stack):** this document was written before the directories were renamed and keeps the paths of its time. Now: `komorebi/` is `komorebi-windows/`, `komorebi-for-kde/komorebi/` is `komorebi-linux/`, `komorebi-for-mac/komorebi/` is `komorebi-macos/`, `komorebi-for-kde/komorebi-hotkeys/` is `komorebi-hotkeys/`, `komorebi-for-kde/nix/` and `komorebi-for-mac/nix/` are `nix/linux/` and `nix/macos/`, `komorebi-for-kde/docs/` and `komorebi-for-mac/docs/` are `docs/linux/` and `docs/macos/`, `schema*.json` are in `schemas/{windows,linux,macos}/`, and every package is at version 0.2.0 (the 0.1.x numbers below are history). + `should_act` (the last rule of a list that matches a window, a composite rule needing all its conditions) and `should_act_individual` (one condition, by its matching strategy) existed three times: `komorebi/src/window.rs` (Windows), `komorebi-for-kde/komorebi/src/window.rs` and diff --git a/docs/dev/seam.md b/docs/dev/seam.md index a47edcd9..4453a36e 100644 --- a/docs/dev/seam.md +++ b/docs/dev/seam.md @@ -2,6 +2,8 @@ > **Status (wip-cand4):** the evidence for `crates/komorebi-backend`, which has landed (trait, `FakeBackend`, contract tests); the Windows daemon goes through it for the clusters in [backend-switch.md](backend-switch.md); read section 8 as the list of what was never verified. +> **Paths (cutover stack):** this document was written before the directories were renamed and keeps the paths of its time. Now: `komorebi/` is `komorebi-windows/`, `komorebi-for-kde/komorebi/` is `komorebi-linux/`, `komorebi-for-mac/komorebi/` is `komorebi-macos/`, `komorebi-for-kde/komorebi-hotkeys/` is `komorebi-hotkeys/`, `komorebi-for-kde/nix/` and `komorebi-for-mac/nix/` are `nix/linux/` and `nix/macos/`, `komorebi-for-kde/docs/` and `komorebi-for-mac/docs/` are `docs/linux/` and `docs/macos/`, `schema*.json` are in `schemas/{windows,linux,macos}/`, and every package is at version 0.2.0 (the 0.1.x numbers below are history). + Status: evidence document (step 7a of the consolidation). No `Backend` trait is proposed here as code, and none may be written before this document has been reviewed. Every statement about the code carries a citation; where I could not confirm something it says "not verified" and the item is collected in section 8. ## 1. Purpose and how to read it @@ -16,9 +18,9 @@ Tips read: integration line `wip-main` at `aa52fdc4d9e5` (`build(nix): relock th | Tree | Prefix used below | Path | |---|---|---| -| Windows (repo root) | `W/` | `komorebi/src/` | -| KDE | `K/` | `komorebi-for-kde/komorebi/src/` | -| macOS | `M/` | `komorebi-for-mac/komorebi/src/` | +| Windows (repo root) | `W/` | `komorebi/src/` (now `komorebi-windows/src/`) | +| KDE | `K/` | `komorebi-for-kde/komorebi/src/` (now `komorebi-linux/src/`) | +| macOS | `M/` | `komorebi-for-mac/komorebi/src/` (now `komorebi-macos/src/`) | Shared crates are cited with their full path (`komorebi-layouts/src/rect.rs`). Only reading and `grep` were used; nothing was compiled or run, and no macOS or Windows runtime behaviour was observed. diff --git a/docs/dev/settings.md b/docs/dev/settings.md index e7442380..38e6fb73 100644 --- a/docs/dev/settings.md +++ b/docs/dev/settings.md @@ -2,6 +2,8 @@ > **Status (wip-cand4):** design plus landing log. `crates/komorebi-settings` exists and the three daemons read the paddings, aspect ratio, layout defaults and display preferences through it; the remaining statics (see the section list) are still process-wide; macOS runtime is unverified. +> **Paths (cutover stack):** this document was written before the directories were renamed and keeps the paths of its time. Now: `komorebi/` is `komorebi-windows/`, `komorebi-for-kde/komorebi/` is `komorebi-linux/`, `komorebi-for-mac/komorebi/` is `komorebi-macos/`, `komorebi-for-kde/komorebi-hotkeys/` is `komorebi-hotkeys/`, `komorebi-for-kde/nix/` and `komorebi-for-mac/nix/` are `nix/linux/` and `nix/macos/`, `komorebi-for-kde/docs/` and `komorebi-for-mac/docs/` are `docs/linux/` and `docs/macos/`, `schema*.json` are in `schemas/{windows,linux,macos}/`, and every package is at version 0.2.0 (the 0.1.x numbers below are history). + Status: design (plan step 10, phase 1). Measured on `wip-main` 633e7453 (the Windows tree `komorebi/src`, KDE `komorebi-for-kde/komorebi/src`, macOS `komorebi-for-mac/komorebi/src`). Nothing here was run: counts come from `grep` and reading, and macOS cannot run on this host. The shared type