chore(repo): combine the kfde, bar and settings stacks (staging)

Staging merge of three stacks that make no runtime change on Windows or KDE: the KDE Backend/Container/process_command refactors (wip-u-kfde), the shared bar core moves (wip-u-bar) and komorebi-settings with the S1/S2 pins (wip-u-settings). Conflicts, if any, are resolved here. Not yet gated: the KDE VM suites and the Windows bar check are owed.
This commit is contained in:
LGUG2Z committed 2026-10-31 11:25:59 -07:00
59 files changed
+3566 -3722

No files matched your search

+180
View File
@@ -0,0 +1,180 @@
# One `komorebi-bar` for Windows and macOS
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
did not are listed at the end.
KDE has no bar: `komorebi-for-kde` has no `komorebi-bar` package and no `schema.bar.json`.
The plan below is for two platforms; a KDE bar would add a third shell and a third schema view.
## What exists
- `crates/komorebi-bar-core` (4,592 lines): the code both bars share, one copy each.
`selected_frame`, `ui`, `statics`, `alignment`, `render`, `config` (the leaf types and the whole
`KomobarConfig` with the mouse options), the widgets `applications`, `battery`, `cpu`, `date`,
`memory`, `storage`, `time`, `update`, `komorebi_layout`, the icon cache (`widgets/icons.rs`),
all widget configuration types (`komorebi_config`, `network_config`, `platform_config` for
keyboard, media and systray), `WidgetConfig` with a variant for every widget, the `BarWidget`
trait, `platform` (`BarPlatform`, `SystemTool`, a once-installed global) and `schema`
(per-platform views, see below).
- `BarPlatform` hooks: `open_system_tool`, `latest_release_api_url`, `calendar_icon`,
`command_icon`, `exec_shell_command`, `send_komorebi_message`, `send_komorebi_batch`.
- Two shells, `komorebi-bar` (Windows, root workspace, version 0.1.42) and
`komorebi-for-mac/komorebi-bar` (own workspace, own `Cargo.lock`, own flake, version 0.1.1).
Each keeps `main.rs`, `bar.rs`, `os.rs`, the one-line `config.rs`, and the widgets whose
runtime differs: `komorebi.rs`, `network.rs`, and on Windows `keyboard.rs`, `media.rs`,
`systray.rs`. `widgets/widget.rs` is only `WidgetConfigExt` (config -> widget).
- The schema oracle regenerates the macOS file natively
(`tests/schema_oracle.rs`, module `generated`); the Windows file is still checked by the
out-of-tree harness because three descriptions read differently when compiled for Windows.
## Why one package is not possible yet (the structural blocker)
The two trees are two Cargo workspaces with two lockfiles and two flakes. A package belongs to
one workspace, so a single `komorebi-bar` that builds on both platforms needs one workspace
first: the Windows root `Cargo.toml` and `komorebi-for-mac/Cargo.toml` merged, one `Cargo.lock`,
one version (0.1.42 vs 0.1.0), one `komorebi-client` (the two `lib.rs` differ in 150 lines:
Windows re-exports the daemon crate and `State`/`Window`/`Workspace`, macOS has its own
types) and `windows`/`objc2` dependencies under `[target.'cfg(...)'.dependencies]`. That is a
repository-level cutover (the plan's "final naming of the outputs and the unified app/devShell
is a cutover decision"), not a bar change. Until then the bars share the crate and converge,
they do not merge. Everything in this stack is ordered so the merge later is a package move.
## The schema is solved: views of one union
`schema.bar.json` differs between the platforms in 40 hunks (5,381 lines of 9,091 / 3,774).
Analysed by definition (`jq` over `$defs`):
- 42 definitions exist only on Windows: all reachable only through `MouseConfig` (which holds a
`SocketMessage`, hence the closure) and the `Keyboard`/`Media`/`Systray` widgets. Removing the
`mouse` property and the three widget variants and pruning unreachable definitions removes
all 42.
- 14 differences remain in the 55 shared definitions, all text or default: root description
(macOS names its own schema URL), `height` default `50` vs `50.0`, the margin and padding
examples (`10` vs `10.0`, a sentence about defaults, a trailing comma), `show_icon`
(deprecated flag and backticks), `KomorebiLayout` (untagged `anyOf` on Windows, externally
tagged `oneOf` on macOS), `NetworkConfig.default_interface_options` (Windows only),
four storage descriptions (`C:\` vs `/`), `TimeConfig.changing_icon` (`default: false` only
on macOS), `TimeFormat` title of `Custom` (macOS says `Default`, a mislabel), the
`WidgetConfig` variants above.
`komorebi_bar_core::schema` holds this as data (`schema/changes.rs`, 16 changes) in the same
design as `komorebi-config`: the union is the Windows text, `view_of` applies a platform's
changes and prunes. `tests/schema_oracle.rs` proves that the macOS view of the checked-in Windows
file is byte-identical to `komorebi-for-mac/schema.bar.json`, that the Windows view is the
identity, and that views are idempotent. Both bars print `--schema` through their view
(`schema::generated_text`), so the files and `nix/komorebi-bar-options.nix` do not change when
code is converged onto the Windows spelling.
The out-of-tree harness (`S/bar2/regen.sh`, real bar sources over the real
`komorebi-protocol`/`komorebi-config`) regenerates both files on Linux. Since `config.rs` moved, the
in-repo oracle regenerates the macOS file itself (`generated` tests); only Windows needs the harness.
## What is still per platform (measured at this tip)
| file | win / mac lines | differing | what differs and why it is not moved |
|---|---|---|---|
| `widgets/komorebi.rs` | 940 / 986 | 136 (17) | Two things. (1) Real rendering differences: macOS wraps `show_label` and the "all icons" painter in a `Frame` with a margin and a minimum height (`bar.show_label(...)`, a method, vs an associated function on Windows), `1.0` vs `1.0_f32`. Taking either spelling is a visual change on the other platform: needs a screen. (2) The conversion from the daemon state: Windows uses `komorebi_client::{State, Window, Workspace, Container}` (`hwnd`, `title()`, `process_id()`, windows-icons), macOS its own client types (`details.title`, `details.icon_path`, `icns_to_rgba`, `device`, no `Layout::Custom`). A State-to-snapshot split (`WindowInfo`/`MonitorInfo` of `komorebi-backend` as the carrier) is not clean yet: the macOS and Windows `komorebi_client` `State` are different types, the bar subscribes to the daemons with different notification shapes, and I cannot test either subscription here. Not attempted. |
| `widgets/network.rs` | 598 / 578 | 82 (19) | Windows reads `default_interface_options` (friendly name, IPv4, IPv6), macOS does not (the config type is shared and macOS logs a warning); `std::sync::Mutex` (poisoning handled) vs `parking_lot`; `netdev` 0.46 vs 0.40 and a different interface match key (friendly name vs `name`); `cmd.exe /C ncpa` vs `open x-apple...`. Functional on macOS: BEHAVIOUR, needs a Mac. Known difference, left as is. |
| `bar.rs` | 1,399 / 1,105 | 444 (35) | Windows: PowerShell session (`exec_powershell`, behind the hook), `hwnd`, virtual-desktop restore/minimize, `position_bar` through `komorebi_client::Window`, CJK font fallbacks, `scale_factor`, the Windows mouse handling. macOS: unboxed notification type, window shadow and level. Not behaviour-preserving without a screen. |
| `main.rs` | 402 / 388 | 92 (14) | `process_hwnd`/`enum_window`, DPI awareness, `set_read_timeout`; macOS activation policy and window level (AppKit), config dir `~/.config/komorebi`. Window and viewport setup belongs behind `BarPlatform` hooks (`init_process`, `viewport_builder`, `after_creation`), not written: it cannot be exercised here. |
| `os.rs` | 83 / 60 | 71 (14) | the platform implementations themselves; stays per platform (`cfg(target_os)` modules after the merge). |
| `widgets/widget.rs`, `widgets/mod.rs` | 41 / 49, 22 / 19 | 20, 5 | `WidgetConfigExt` (macOS builds a no-op `Unsupported` for the three Windows-only widgets) and the module lists. |
Windows-only and not shared: `widgets/keyboard.rs` (167), `media.rs` (322), `systray.rs` (1,205);
their config types are in the core. The macOS copies of keyboard and media were dead and are deleted.
### Known macOS/Windows differences that were kept (D-coord-1)
- `network.rs`: see above. The macOS bar ignores `default_interface_options`.
- Windows-only config keys are accepted on macOS and skipped with a logged warning (BEHAVIOUR on
macOS, as for `StaticConfig`): `Keyboard`, `Media` and `Systray` widgets
(`widgets::widget::warn_unsupported`), the `mouse` options and the network
`default_interface_options`. Before, the first group failed to deserialize and rejected the whole
config, the other two were ignored silently.
- macOS commands that spawn programs that do not exist there are preserved, not fixed:
`SystemTool::PowerSettings` (battery click) spawns `cmd.exe /C start ms-settings:...`,
`SystemTool::Url` (update click) spawns `explorer.exe`, and `UserCommand::launch_if_ready` of the
applications widget spawns `cmd /C <command>` in both bars. `update.rs` still has a second GitHub
API URL for the Windows repository. The macOS spawns live in
`komorebi-for-mac/komorebi-bar/src/os.rs`; the storage click is `SystemTool::StorageLocation` and
each shell spawns what it spawned before.
- `KomorebiLayout` is `#[serde(untagged)]` in both bars now (the macOS source converged; the macOS
schema view restores the macOS text). Its `Deserialize` is hand-written and nothing in the bar
serializes it, so this changes only the derived schema and `Serialize`. The coordinator said to
leave it alone; it is a separate revision (`mac-bar: converge komorebi.rs config text and
komorebi_layout.rs`) and can be dropped, at the price of keeping `KomorebiLayout` and its
widget in the shells.
## The merged package layout (for the coordinator's workspace merge)
Not done and not prepared in the tree (no workspace or lockfile structure was changed). When the
root workspace and `komorebi-for-mac` are merged the bar should look like this:
- Package `komorebi-bar` (one, in `komorebi-bar/`) plus `crates/komorebi-bar-core` as today.
Version: the workspace version. The macOS tree's `komorebi-bar` 0.1.1 and the `v0.1.0` text in
its schema description are a view concern (`schema/changes.rs`), not a package one.
- `src/main.rs` (shared: the argument parsing, config read, `--schema`, the event loop shell)
and `src/bar.rs` split into `src/bar/mod.rs` (shared `Komobar`) with
`#[cfg(target_os = "windows")] mod windows;` and `#[cfg(target_os = "macos")] mod macos;`
for the window handle, DPI, activation policy, window level, position and the PowerShell
session. `src/os.rs` becomes `src/os/{windows,macos}.rs` (the `BarPlatform` implementations,
selected by `cfg(target_os)` and installed first thing in `main`). Windows-only widgets
(`keyboard`, `media`, `systray`) are `#[cfg(target_os = "windows")]` modules; `komorebi.rs` and
`network.rs` stay two files (`komorebi/{windows,macos}.rs` behind one `widgets::komorebi`
facade) until the snapshot split.
- `Cargo.toml`: `windows`, `windows-core`, `windows-icons*`, `systray-util`, `font-loader` under
`[target.'cfg(windows)'.dependencies]`; `objc2`, `objc2-app-kit`, `raw-window-handle`, `icns`
under `[target.'cfg(target_os = "macos")'.dependencies]`; `netdev` has two versions (0.46,
0.40): pick one when `network.rs` converges, until then a target-specific rename
(`netdev-win`, `netdev-mac`). `komorebi-client`: one crate (the two differ in 150 lines).
Features: `schemars` as now (it forwards to the core). No new feature per platform: the
platform is `cfg(target_os)`.
- Schema: the checked-in files stay (`schema.bar.json`, `komorebi-for-mac/schema.bar.json`, or one
directory for both after the merge). `--schema` prints the view of the running platform
(`SchemaPlatform` from `cfg(target_os)`); a `--schema-for <platform>` flag would let one host
regenerate both, as the Windows union is the Windows text. Windows' three
platform-dependent descriptions (protocol `PathBuf`, themes) need the Windows target to
regenerate, so the Windows file is only verifiable on Windows or with the harness.
- Lock files: the macOS `Cargo.lock` folds into the root one; the lines this stack added to both
(`image`, `komorebi-config`, `komorebi-layouts`, `komorebi-protocol`, `komorebi-themes`,
`tracing`, `lazy_static`, `color-eyre` for bar-core) are the same crates in both, so the merge
adds no new versions beyond `netdev` and `starship-battery`/`sysinfo` (already unified here).
- Nix: `komorebi-for-mac/nix/komorebi-bar-options.nix` is generated from the macOS file and does
not change; the two flakes' `extractBinary "komorebi-bar"` become one derivation per system.
## The plan, in order
1. Done: schema views and oracle; storage, time, applications, komorebi layout widget, icon
cache, all widget config types, `WidgetConfig`, `config.rs` moved; hooks for platform
spawns, the shell session and the komorebi client.
2. Not done, needs a screen or a Mac: `bar.rs`/`main.rs` window code behind `BarPlatform`
(`init_process`, `viewport_builder`, `after_creation`, position/DPI/activation), then
`Komobar<P>` and the shared `app` body into the core.
3. Not done, needs the snapshot split: `komorebi.rs`. It needs `State`-to-snapshot conversion
per platform and one renderer; the frame/margin difference must be decided by looking at both.
4. Decision for `network.rs`: converge on the Windows widget (macOS gains friendly-name,
IPv4/IPv6 and the `netdev` bump) or keep two.
5. Workspace merge (above), then the two shells collapse into one package.
6. The oracle then compares generated text with the files for both platforms.
## What to check by hand
Windows (coordinator, screenshot e2e): the bar starts; the storage, time, applications (icons
from executables), komorebi layout (click opens the options, choosing one changes the layout,
Monocle/Floating toggles, paused) and komorebi workspaces widgets render; a click on storage
opens Explorer on the drive; a config with `mouse` options and a `Systray`/`Keyboard`/`Media`
widget still works (this is the Windows path through the moved `config.rs`, `WidgetConfig` and
the `exec_shell_command` hook: a `Command` mouse message must still reach the PowerShell session);
`komorebi-bar --schema` equals `schema.bar.json`.
macOS (also in the section for `docs/dev/macos-handcheck.md`): the bar starts with your real
config; the time widget renders (format variants, `changing_icon`); clicking a storage widget
opens the mounted volume in Finder (`open <path>`); the komorebi layout widget click works as
before; a config that contains a `Keyboard`, `Media` or `Systray` widget, a `mouse` block, or
`default_interface_options` under `Network` starts the bar and logs one warning per item (before:
the widget case failed to load the config); `komorebi-bar --schema` equals
`komorebi-for-mac/schema.bar.json`; the battery and update clicks still fail the way they did
(preserved, one-function fix in `os.rs`).
+320
View File
@@ -0,0 +1,320 @@
# Settings: replacing the process-wide statics
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
is landed as the crate `crates/komorebi-settings` (phase 2) and **no daemon uses it yet**.
Abbreviations: `W/`, `K/`, `M/` are the three `src` trees. `apply_globals` is
`StaticConfig::apply_globals` (`W/static_config.rs:396`, `K/static_config.rs:414`,
`M/static_config.rs:392`).
## 1. What the statics are
Declarations of `static`, `static ref` and `lazy_static` (thread locals and per-call counters left out):
**Windows 126, KDE 53, macOS 74.** Most are not settings. Four kinds:
| kind | examples | goes into `Settings`? |
|---|---|---|
| **config**: written by `komorebi.json` load and/or a `SocketMessage`, read by other threads | `BORDER_*`, `ANIMATION_*`, paddings, rule lists, stackbar | yes |
| **session state**: changes while running, is not configuration | `SESSION_FLOATING_APPLICATIONS`, `UNMANAGED_WINDOW_IDS`, `HIDDEN_HWNDS`, `WORKSPACE_MATCHING_RULES`, `INITIAL_CONFIGURATION_LOADED`, `CUSTOM_FFM` (command line) | no; stays where it is (core step 9) |
| **plumbing**: channels, `OnceLock<Sender>`, caches of OS handles, per-window tables | `CHANNEL`, `BORDER_STATE`, `MONITOR_CACHE`, `HWNDS_CACHE`, `PARKED_WINDOWS`, `live_resize.rs` flags | no |
| **environment**: computed once | `HOME_DIR`, `DATA_DIR`, `AHK_EXE`, `WINDOWS_11` | no |
Config-class statics by my count: **Windows 61, KDE 35, macOS 36** (these include the session-state
rule lists that sit next to them; see 2.3). What `apply_globals` itself writes (distinct statics,
counted on the function body): **Windows 51, KDE 29, macOS 28.** The plan's "19-27 written per
platform" counted scalar settings only; the 11 rule lists, the 7 per-animation/global animation
statics and the stackbar block make the totals larger.
## 2. The inventory (config class)
"Writers": `load` is `apply_globals` (runs on start-up through `preload`, and again on every
`ReloadConfiguration` through `reload`), `cmd` is a `SocketMessage` arm of `process_command.rs`,
`theme` is `theme_manager`, `thr` is another thread. "Readers" lists only threads that are not the
window-manager thread; "wm" means code that runs under the window-manager lock. Match is the name
on the other platforms (`=` same name and type, `~` same name, different default or type, `-`
absent).
### 2.1 Scalars and small values
| static | type | writers | readers | W / K / M | shared? | note |
|---|---|---|---|---|---|---|
| `BORDER_ENABLED` | AtomicBool | load, cmd `Border` | border thread (all 3), wm | = = = | shared | K reads it to decide whether borders take room in the layout (`BORDER_DRAWN` is its derived twin, K only) |
| `BORDER_WIDTH` | AtomicI32 | load, cmd | border thread, wm (offsets), stackbar (W) | ~ default 8 / 10 / 10 | shared | |
| `BORDER_OFFSET` | AtomicI32 | load, cmd | border thread, wm | ~ default -1 / 0 / 0 | shared | |
| `BORDER_RADIUS` | AtomicI32 | load | K effect, M `ns_window` | - K M | K+M | Windows draws square or via DWM (`STYLE`) |
| `BORDER_OFFSET_ADJUSTMENT` | `static i32` = 7 | nobody | M border | - - M | platform constant | stays a constant |
| `FOCUSED UNFOCUSED UNFOCUSED_LOCKED MONOCLE STACK FLOATING` | 6 x AtomicU32 | load, cmd `BorderColour`, theme | border thread | = = = | shared | `UNFOCUSED_LOCKED` is written by theme only (load never writes it); one theme change writes 6 border and (W) 3 stackbar values one by one |
| `STYLE` | AtomicCell<BorderStyle> | load, cmd | border thread, wm | W only | W platform | load resets it to default when the file has none |
| `IMPLEMENTATION` | AtomicCell<BorderImplementation> | load, cmd | border thread | W only | W platform | |
| `ANIMATION_ENABLED_GLOBAL` | Arc<AtomicBool> | load, cmd, **scoped override**, shutdown | W animation engine, M animator and lane threads, wm | = = = | shared | see 4 (override) |
| `ANIMATION_STYLE_GLOBAL` | Arc<Mutex<AnimationStyle>> | load, cmd | same | = = = | shared | |
| `ANIMATION_DURATION_GLOBAL` | Arc<AtomicU64> | load, cmd | same | = = = | shared | |
| `ANIMATION_{ENABLED,STYLE,DURATION}_PER_ANIMATION` | Arc<Mutex<HashMap<AnimationPrefix, _>>> x3 | load, cmd (2 sites for style), shutdown (enabled) | same | = = = | shared | `load` clears the map when a global value is given, replaces it when a prefix map is given |
| `ANIMATION_FPS` | AtomicU64 | load, cmd | W engine, M animator (`frame_period`) | = = = | shared | load writes the default when `animation` is present but `fps` is not |
| `GHOST_MOVEMENT_ENABLED` | AtomicBool | load | W ghost dispatcher, live resize | W only | W platform | |
| `TRANSPARENCY_ALPHA` | AtomicU8 | load, cmd | W/K transparency manager | = = - | shared (W, K) | default 200 |
| `TRANSPARENCY_ENABLED` | AtomicBool | load (`transparency`), cmd (set, toggle) | transparency manager, W process_event | = = - | shared (W, K) | a command toggles what the file set; a reload overwrites it only when the key is present |
| `DEFAULT_WORKSPACE_PADDING`, `DEFAULT_CONTAINER_PADDING` | AtomicI32 | load | wm (every layout), W stackbar | ~ default 10 / 5 / 5 | shared | load keeps the old value when the key is absent |
| `DEFAULT_RESIZE_DELTA`, `DEFAULT_MOUSE_FOLLOWS_FOCUS` | `static i32 / bool` | nobody | wm | = = = | shared constants | become part of the platform defaults |
| `FLOATING_WINDOW_TOGGLE_ASPECT_RATIO` | Arc<Mutex<AspectRatio>> | load (2 sites) | wm | = = = | shared | load writes a default when absent |
| `LAYOUT_DEFAULTS` | Arc<Mutex<HashMap<DefaultLayout, LayoutDefaultEntry>>> | load (replace or clear) | wm | = = = | shared | |
| `DISPLAY_INDEX_PREFERENCES` | Arc<RwLock<HashMap<usize, String>>> | load, cmd | monitor reconciliator thread, wm | = = = | shared | |
| `MONITOR_INDEX_PREFERENCES` | Arc<Mutex<HashMap<usize, Rect>>> | load, cmd | W windows_api, reconciliator | W only | W platform | commented out of macOS and KDE load |
| `DUPLICATE_MONITOR_SERIAL_IDS` | Arc<RwLock<Vec<String>>> | reconciliator, windows_api | windows_api | W only | **not config** | derived from the monitor list |
| `HIDING_BEHAVIOUR` | Arc<Mutex<HidingBehaviour>> | load, cmd, (state loader) | **reaper thread** (every 20 ms), wm | W only | W platform | reaper reads it without the wm lock |
| `WINDOW_HANDLING_BEHAVIOUR` | AtomicCell<WindowHandlingBehaviour> | load, **scoped override** in `border.rs:831-851` | W windows_api (every position call), ghost dispatcher, scrolling | W only | W platform | see 4 |
| `MINIMUM_WIDTH`, `MINIMUM_HEIGHT` | AtomicI32 x2 | load | wm | W only | W platform | commented out of the macOS load |
| `SLOW_APPLICATION_COMPENSATION_TIME` | AtomicU64 | nobody after init | W window | W only | W platform | effectively constant 20 |
| `REMOVE_TITLEBARS` | AtomicBool | cmd | wm, workspace | W only | W platform | runtime toggle, not in `apply_globals` |
| `STACKBAR_*` (9: font size/family, focused/unfocused text, tab background, height, width, label, mode) | AtomicI32/U32/Cell, `Mutex<Option<String>>` | load, cmd, theme (3 colours) | stackbar threads, wm | W only | W platform | load sets font size and family unconditionally (0 / None) when `stackbar.tabs` is present |
| `STACKBAR_TEMPORARILY_DISABLED` | AtomicBool | ghost dispatcher | stackbar manager | W only | session state | |
| `CURRENT_THEME` | AtomicCell<Option<Theme>> | theme thread | theme thread only | = = = | not config | read nowhere else |
| `TABBED_APPLICATIONS`, `TITLELESS_APPLICATIONS`, `DO_NOT_OBSERVE_APPLICATIONS` | Arc<Mutex<Vec<String>>> | load (first two) | M window, process_event | M only | M platform | |
### 2.2 Rule lists (the lock-ordered set)
| static | writers | readers | W / K / M |
|---|---|---|---|
| `FLOATING_APPLICATIONS`, `IGNORE_IDENTIFIERS`, `MANAGE_IDENTIFIERS` | load (all three held at once) | wm; W also `winevent` and `window_manager_event` threads through `window_is_eligible` | = = = |
| `TRANSPARENCY_BLACKLIST` | load | transparency manager | = = - (K: pub) |
| `LAYERED_WHITELIST`, `TRAY_AND_MULTI_WINDOW_IDENTIFIERS`, `OBJECT_NAME_CHANGE_ON_LAUNCH`, `OBJECT_NAME_CHANGE_TITLE_IGNORE_LIST`, `SLOW_APPLICATION_IDENTIFIERS`, `NO_TITLEBAR` | load | wm, event threads | W only |
| `REGEX_IDENTIFIERS` | load (clears), every rule check (compiles on demand) | every rule check | = = = |
| `PERMAIGNORE_CLASSES` (W also `WSL2_UI_PROCESSES`) | nobody after init | window eligibility | = = = (W: +1) |
| `SESSION_FLOATING_APPLICATIONS` | cmd (add/remove at run time) | window eligibility | = = = |
| `WORKSPACE_MATCHING_RULES` | cmd, **reload (clears, then refills after `apply_globals`)** | wm, reconciliator, M process_event | = = = |
### 2.3 Lock-order relations
The documented order (comment above the statics in `komorebi/src/lib.rs` on `wip-u-kfw`; it is the
only one: KDE and macOS declare no order and take the same lists in whatever order the code does):
```
FLOATING_APPLICATIONS, SESSION_FLOATING_APPLICATIONS, TRANSPARENCY_BLACKLIST, IGNORE_IDENTIFIERS,
MANAGE_IDENTIFIERS, LAYERED_WHITELIST, TRAY_AND_MULTI_WINDOW_IDENTIFIERS, OBJECT_NAME_CHANGE_ON_LAUNCH,
OBJECT_NAME_CHANGE_TITLE_IGNORE_LIST, SLOW_APPLICATION_IDENTIFIERS, NO_TITLEBAR,
WORKSPACE_MATCHING_RULES, REGEX_IDENTIFIERS
```
`REGEX_IDENTIFIERS` is last (every rule check holds a list and then the regexes); `PERMAIGNORE_CLASSES`
and `WSL2_UI_PROCESSES` are leaves. The window-manager lock is above all of them: `apply_globals` runs
with it held (the `reload` signature takes `&mut WindowManager`), but the event threads of Windows
(`winevent_listener` to `window_manager_event`) and the transparency manager also lock single lists
without it.
Two findings:
1. `apply_globals` on Windows takes **eleven** list locks in a fixed order and keeps them for the whole
function (`W/static_config.rs:562-572`), so the rules change atomically with respect to each other,
but not with respect to the scalars (written before and after).
2. `reload` clears `WORKSPACE_MATCHING_RULES` and refills it per monitor afterwards (`M/static_config.rs`
after `apply_globals`, same on W and K): for the duration of the loop a reader that does not hold the
wm lock sees an **empty** list. This is a live partial-update window today.
With `Settings` the immutable lists are fields of one `Arc` snapshot: readers take no lock, there is no
order to follow, and the lock order shrinks to: wm lock, then the two session mutexes
(`SESSION_FLOATING_APPLICATIONS`, the regex cache), never nested the other way round.
## 3. The design
### 3.1 Crates
New crate `crates/komorebi-settings` (std plus `parking_lot`; types from `komorebi-config`,
`komorebi-protocol` and `komorebi-layouts`; no daemon dependency, so it tests natively):
```rust
pub struct Settings<P> {
pub shared: Shared, // the same struct on all three platforms
pub platform: P, // Windows: border style, stackbar, hiding/handling behaviour, ...
} // KDE: nothing yet (the compositor owns look); macOS: tabbed/titleless apps
pub struct Shared {
pub border: Border, // enabled, width, offset, six colours
pub animation: Animation, // global + per-prefix enabled/style/duration, fps; motion_for(prefix)
pub defaults: Defaults, // container/workspace padding, resize delta, mouse-follows-focus
pub transparency: Transparency, // enabled, alpha (Windows and KDE; macOS keeps the default)
pub floating_window_aspect_ratio: AspectRatio,
pub layout_defaults: HashMap<DefaultLayout, LayoutDefaultEntry>,
pub display_index_preferences: HashMap<usize, String>,
}
pub struct Handle<P> { /* RwLock<Arc<Settings<P>>> + a writer mutex */ }
impl<P: Clone> Handle<P> {
pub fn snapshot(&self) -> Arc<Settings<P>>; // readers
pub fn replace(&self, s: Settings<P>); // whole new value
pub fn update<R>(&self, f: impl FnOnce(&mut Settings<P>) -> R) -> R; // copy, edit, swap; writers serialised
pub fn scoped<T>(&self, field: fn(&mut Settings<P>) -> &mut T, value: T) -> Scoped<'_, P, T>;
}
```
The **platform part** is a plain type parameter `P` (not a trait): each daemon names its struct
(`WindowsSettings`, `MacosSettings`, `KdeSettings`) and the handle is `static SETTINGS: LazyLock<Handle<P>>`
behind a `settings()` function of the daemon crate. `P` needs only `Clone + Debug`. A trait would add
nothing, because the shared code never calls into `P`: only the platform's own subsystems read it. When
the daemons become one crate this is `#[cfg(target_os)] type Platform = ...`.
The lists of rules and the stackbar block move into the platform parts first (they are Windows only or
differ); the rule lists join `Shared` in step G7 below once the lock order is retired.
### 3.2 How readers get a consistent snapshot
* A reader calls `settings().snapshot()` **once per unit of work** (one render pass of a border, one
`motion_for` call, one layout pass, one window eligibility check) and uses that `Arc` for the whole
unit. Cost: one uncontended `RwLock` read and an `Arc` clone; no atomics are needed on the hot
paths I found (border thread loops once per notification, animator once per frame, rule checks once per
event). If a measurement shows one needs it, add an `AtomicBool` *mirror* of that single field written by
the same `update`; do not read the mirror and the snapshot for the same decision.
* `ArcSwap` was the first idea. It is **not in any of the three lockfiles** (checked), so it would add a
dependency to three lockfiles and the flake hashes for no gain at this read rate. `Handle` hides the
representation: swapping `RwLock<Arc<_>>` for `ArcSwap<_>` later changes one file.
* Writers go through `update`, which holds a mutex while it clones, edits and publishes, so two writers
(a `SocketMessage` and a config reload, a theme change and a command) never lose each other's field. The
statics lose such updates today only when both write the same field, but a theme change writes nine
separate atomics and a command can interleave.
* A config load builds the new value and publishes it **once**; a theme change is one `update`.
### 3.3 Semantics that must survive: reload merges, it does not replace
`apply_globals` is a field-by-field merge: `if let Some(x) = self.border_width { store }`. A key absent
from a reloaded `komorebi.json` **keeps the previous value** (and a command-set value); a few fields are
instead reset (listed in section 4, "reset on reload"). A "build a fresh Settings from the file and swap"
would reset every absent key to its default. So the migration keeps the merge: `Settings::apply(delta)`
is written as the same sequence of `if let Some` over a copy of the **current** snapshot, published once.
Replacing instead of merging is a separate, optional BEHAVIOUR change, last in the list.
### 3.4 The scoped override
Two places write a setting, do work and put it back: Windows `border.rs:831-851`
(`WINDOW_HANDLING_BEHAVIOUR`: load, store `handling`, ..., store `previous`) and KDE
`process_command.rs:607-609` (`ANIMATION_ENABLED_GLOBAL.swap(false)`, `add_window_to_container`,
`store(restore)`). Both clobber a concurrent change (a reload or a command in between is overwritten with the old value). macOS
already has the right pattern: `animation::suspend()` returns a guard that counts and `motion_for` returns
`None` while it is held (`M/animation/mod.rs:36-71`). `Handle::scoped` gives the same for any field:
it sets the value and, on drop, puts the previous value back **only if the field still holds the
override value**, so a change made meanwhile wins. For animations KDE and Windows should adopt
macOS's `suspend` counter instead (a field of `Shared::animation`, not a scoped value).
## 4. Statics whose behaviour would change
Everything here is a **BEHAVIOUR** change if it is not made to keep today's semantics. Flagged items
say what the migration does about each.
**Partial updates visible mid-reload (today).** `apply_globals` publishes about 28 to 51 values
one at a time while the border, animator, reaper and transparency threads keep reading. A border
thread can draw once with the new width and the old colours; `motion_for` (macOS) reads enabled,
duration and style as three separate lock/atomic reads and can mix two configurations. With `Handle` all
readers see the old or the new `Settings`, never a mix: **BEHAVIOUR (intended, can only remove
tears)**, on every static of the table. The e2e that would show it is `config_reload`.
**Reset on reload (must be kept as written):** `LAYOUT_DEFAULTS` (cleared when absent),
`FLOATING_WINDOW_TOGGLE_ASPECT_RATIO` (default when absent), `ANIMATION_FPS` (default when `animation` is present
without `fps`), `GHOST_MOVEMENT_ENABLED` (W), `STYLE` and `IMPLEMENTATION` (W: default when absent),
`STACKBAR_FONT_SIZE` / `STACKBAR_FONT_FAMILY` (W: 0 / None when `stackbar.tabs` is present),
`ANIMATION_*_PER_ANIMATION` (cleared when the global form is used) and the rule lists (`apply_globals`
clears each only when the new file gives that list; check per list in G7).
**Keeps the old value when absent (must be kept):** borders (width, offset, radius, enabled, colours),
paddings, transparency alpha, hiding and handling behaviour, minimum size, stackbar scalars, display index
preferences.
**Scoped override (3.4):** KDE `ANIMATION_ENABLED_GLOBAL.swap/store` pair and Windows `WINDOW_HANDLING_BEHAVIOUR`
pair become guards. A concurrent reload no longer gets clobbered: BEHAVIOUR.
**Shutdown writes** (`main.rs:367-368`, `window_manager.rs:1445-1446` on W; the Stop handler on K and M): they
disable animation permanently before restoring windows. These are plain `update`s, not scoped.
**`WORKSPACE_MATCHING_RULES` empty window** (2.3): stays in the core until step 9 (session state); not part
of `Settings`, so not changed here.
**Defaults differ per platform** (border width 8/10/10, offset -1/0/0, padding 10/5/5, KDE border radius):
`Shared::defaults_for(PlatformDefaults::{WINDOWS, KDE, MACOS})`. Changing any default is user visible and is
not part of this step.
**Threads read the statics without the wm lock:** border thread (all three), W reaper
(`HIDING_BEHAVIOUR`), W winevent and window_manager_event threads (rule lists), W transparency manager,
macOS animator thread and the per-pid lane threads, macOS border thread. These are the readers whose behaviour a snapshot
changes (from "latest value on each read" to "value of the snapshot taken at the start of the unit"); the
gap is at most one unit of work.
## 5. Migration order (least to most risky)
Each group is one revision per platform tree (or per platform file set), moving the writers and **all**
readers of that group together, never dual-writing a static and a field. P = pure refactor (same
observable behaviour); B = BEHAVIOUR (marked in the revision body, not landed until its gate ran).
| step | group | kind | gate |
|---|---|---|---|
| S0 | the crate and its tests (landed, phase 2) | P | native `cargo test -p komorebi-settings` |
| S1 | `DEFAULT_RESIZE_DELTA`, `DEFAULT_MOUSE_FOLLOWS_FOCUS`, `BORDER_OFFSET_ADJUSTMENT`: constants into `PlatformDefaults` | P | KDE `cargo test -p komorebi --lib`, Windows clippy, macOS fake-CC check |
| S2 | install `settings()` in each daemon with the platform defaults (no reader yet) | P | same |
| S3 | paddings, aspect ratio, layout defaults, display index preferences (wm-lock readers and the reconciliator) | P for the readers; the load writes the new place once: B (tear) | KDE lib tests; Windows `config_reload`, `layouts`, `workspaces` e2e; macOS: reload with changed padding |
| S4 | transparency enabled and alpha (W, K) | P | Windows `config_reload` plus the transparency scenario if it exists; KDE lib tests |
| S5 | animation (global, per-prefix, fps): `motion_for`, engine, animator; KDE/Windows adopt `suspend()` guards | **B** (tear removed, override semantics) | KDE VM suites that stack windows (`stacks`); Windows animation e2e; **macOS hand-check**: animation on, switch workspace, change `animation.duration` by `komorebic` mid-animation, stack a window |
| S6 | border scalars and colours, theme colours as one `update` | **B** (the 6 colour atomics change together) | Windows border e2e (screenshot) and `config_reload`; KDE VM `borders`/look suites; **macOS hand-check**: `border-colour`, `border-width`, theme change, reload with changed border |
| S7 | Windows platform part: `HIDING_BEHAVIOUR`, `WINDOW_HANDLING_BEHAVIOUR` (with `scoped`), min size, stackbar block, border style/implementation, ghost movement | **B** (reaper reads a snapshot; override guard) | Windows: `commands`, `config_reload`, `lifecycle`, `lifecycle_hidden`, stackbars, border e2e |
| S8 | rule lists into `Shared` (immutable `Arc<RuleSet>`), session floating and regex cache stay mutexes; retire the lock-order comment | **B** (hot path of every window event; deadlock class removed) | Windows `config_reload` (lock order), `commands`, `focus`, `lifecycle`; KDE lib tests plus VM suites; macOS: manage/ignore rules by hand |
| S9 | `apply_globals` as one `update` (single publish), and one decision on merge versus replace | **B** | Windows `config_reload`; macOS reload by hand |
Risk grows with the number of threads that read without the wm lock and with how hot the read is:
S3 has none, S5 and S6 have the macOS threads the plan names, S7 has the reaper, S8 is every event.
Do S8 only after the Windows lock-order e2e from the `wip-u-kfw` stack has run once on the current
tree.
## 6. What is not in `Settings`
`SESSION_FLOATING_APPLICATIONS`, `UNMANAGED_WINDOW_IDS`, `HIDDEN_HWNDS`/`HIDDEN_WINDOWS`,
`WORKSPACE_MATCHING_RULES`, `REMOVE_TITLEBARS`, `CUSTOM_FFM`,
`INITIAL_CONFIGURATION_LOADED`, subscriptions, `*_CHANNEL`s, caches, `BORDER_STATE`: these are session or
plumbing state and belong to the model (step 9) or the subsystem. `Settings` is only what the user
configures.
## 7. What landed (phase 2) and findings from writing it
`crates/komorebi-settings` (native tests, 18 passed): `Settings<P>`, `Handle<P>` (`snapshot`, `replace`,
`update`, `scoped`), `Shared` (border, animation with `motion_for`, paddings and constants, transparency,
aspect ratio, layout defaults, display index preferences), `PlatformDefaults::{WINDOWS, KDE, MACOS}` and
`SharedDelta::apply`, which is `apply_globals` for the shared keys written as a function of the current
value. Not yet in the crate: rule lists, theme application as one update, anything platform specific.
Findings that only showed up while encoding the semantics:
* `FLOATING_WINDOW_TOGGLE_ASPECT_RATIO` starts at **Widescreen** on all three platforms, but a load
whose file has no `floating_window_aspect_ratio` writes **Standard** (`unwrap_or`). So the first
reload of a file without the key changes the ratio. `SharedDelta::apply` keeps this; fixing it is a
separate user-visible change.
* `TRANSPARENCY_ENABLED` is written by the load (`transparency`) and by the toggle command, so it is a
setting, not session state (corrected from the first draft of this document's table).
* `komorebi-config` warns about an unused import (`crate::defaults`, `static_config.rs:39`) when it is
built with `default-features = false`; the settings crate builds it that way. Not touched.
* Windows `reload` runs `apply_globals` twice per reload: in `preload` of the new window manager
(while the old one is paused) and again in `reload`; both writes become visible to the threads that
read without the wm lock. One `update` per load keeps the two visible publishes.
## 8. S1 and S2 as landed for KDE and macOS, and the Windows patch (not applied)
KDE and macOS (`wip-u-settings`): S1 (the `DEFAULT_*` statics take their values from
`komorebi_settings::shared`, paddings from `PlatformDefaults::{KDE, MACOS}`; the statics keep their
names and types) and S2 (`src/settings.rs` with `KdeSettings` / `MacosSettings` and `settings()`;
a test pins that the starting settings equal the starting values of the border and default
statics). The new crate is a path dependency of both workspaces (manifest, package manifest,
`Cargo.lock` +1 package). S3 was **not** started: it moves the writers (`apply_globals`) and the
readers in `monitor.rs`, `workspace.rs`, `window.rs`, `process_command.rs`, which the KDE and macOS
stacks are editing, and the load would publish once instead of storing key by key, which is the tear
removal marked BEHAVIOUR in section 5. It needs the rebase onto the merged stacks and its gate.
Windows S1/S2, to apply when told (all in the files kfw is changing, so not done):
1. `komorebi/Cargo.toml`: `komorebi-settings = { path = "../crates/komorebi-settings" }` (the crate is
already a root workspace member; `Cargo.lock` gets the dependency edge, no new package).
2. `komorebi/src/lib.rs`: `DEFAULT_WORKSPACE_PADDING` / `DEFAULT_CONTAINER_PADDING` start from
`PlatformDefaults::WINDOWS.workspace_padding` / `.container_padding` (10, 10);
`DEFAULT_RESIZE_DELTA` and `DEFAULT_MOUSE_FOLLOWS_FOCUS` are `komorebi_settings::shared::...`
(50, true); add `pub mod settings;`.
3. New `komorebi/src/settings.rs`, a copy of the KDE one with `WindowsSettings` (empty) and
`PlatformDefaults::WINDOWS`; its pin test compares the paddings, resize delta, mouse-follows-focus,
`BORDER_ENABLED`, `BORDER_WIDTH` (8), `BORDER_OFFSET` (-1) and the six colours, and leaves out
`border.radius` (Windows has no `BORDER_RADIUS`).
4. Gate: Windows clippy (`-D warnings`) and `cargo test -p komorebi --lib`; `tools/e2e-needed` will
say YES (the crate is in the closure of `komorebi.exe`) so one e2e run is owed, but behaviour is
unchanged.