komorebi/docs/dev/bar-unification.md

# One `komorebi-bar` for Windows and macOS

> **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
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`).