Commit Graph
2793 Commits
Author SHA1 Message Date
LGUG2Z f6ad736dca feat(windows): time the steps of process_event
The event thread logs, per event, how long it waited for the window manager
lock and how long handling took (debug, or info when either is 200 ms or more:
"process_event <event>: waited for the lock N ms, handled in N ms"), and
process_event logs how long should_manage took (debug). The stall analysis of
the cand5 gate puts every remaining real hold of 1 to 4.5 s in process_event
for Show/Uncloak/FocusChange of new windows, silent before the first log line
of the handler; these lines say whether that is should_manage (Win32 and rule
matching on the new window) or the rest.

Diagnostics only, no behaviour change. Verified: tools/fast-check Windows
clippy -D warnings PASS; e2e: none needed.
2026-11-05 15:03:26 -08:00
LGUG2Z 1acdd9bb20 fix(windows): the lock-holder record is released with the lock guard, not after it
The Held record was a separate local next to the lock guard, so it outlived
the guard where the guard was dropped early: in the border manager the record
ran on through everything the thread does after drop(state) (foreground
lookup, border windows, painting), and in the monitor reconciliator through the
3 s thread::sleep of the "potential monitor removal" verification, which runs
with the lock released. The stall analysis of the cand5 gate counted both as
holds (rank 2 and 3 of the ranking; artifacts). lock_holder::lock(&mutex,
site) now returns a HeldGuard that owns the lock guard and the record, derefs
to the window manager, and drops the record first and the guard second, so
drop(guard) ends both together. All six sites that recorded a holder use it
(process_event, reaper, border manager, monitor reconciliator including its two
re-locks, transparency and stackbar managers); the per-command record in
process_command stays (it is dropped just before the transport's guard).

Diagnostics only, no behaviour change (the locks are taken and released where
they were). Verified: tools/fast-check Windows clippy -D warnings (default
members, own target dir) PASS; e2e: none needed, the next gate's hold ranking
should lose the two artifacts.
2026-11-05 15:03:26 -08:00
LGUG2Z 2d6919438b perf(nix): keep the dependency derivations independent of the source files
cargoLock, cargoToml and the vendor directory of the three flakes were taken
as "${real}/Cargo.lock" and crane.vendorCargoDeps { src = real; }. A string
that names a file inside the filtered source carries the whole source in its
context, so every edit of any file in it (a .rs file, a doc) changed the
dependency derivation (komorebi-workspace-deps, about 1000 crates) and the
dependencies rebuilt on every change: the constant COMMIT_HASH alone did not
help once the stubbed workspace source was introduced.

The lock and the root manifest are now builtins.path copies of those two
files (lockFile, tomlFile) and the vendor directory is made from the lock
(vendorCargoDeps { cargoLock = lockFile; }), so the dependencies depend on
Cargo.lock, Cargo.toml and the manifests the dummy source keeps, as before.

Verified (nix eval of drvPath in a throwaway git copy, three commits:
unchanged tree, an edit of crates/komorebi-config, a docs edit): Windows
deps and kfde deps are identical in all three (before: both changed with any
edit); Windows clippy changes with the source edit and the docs edit (docs are
in the Windows source), kfde clippy and vm stacks change with the
komorebi-config edit only; the kfm deny attribute still evaluates. The kfm
deps and clippy cannot be evaluated on this Linux host (the same change was
made there by analogy). Not built: one cold build, then a second commit must
be a cache hit.
2026-11-05 15:03:26 -08:00
LGUG2Z 219cf65b83 style(macos): format the files the merge of settings3 left unformatted
Pure formatting, no other change: the same rustfmt invocation as the kfm fmt
check (nightly rustfmt, edition 2024, komorebi-for-mac/rustfmt.toml) over
komorebi-for-mac/komorebi/src/animation/mod.rs and static_config.rs, which the
merge took from wip-u-settings3 unformatted.

Verified: the check's rustfmt --check over the macOS files passes after it.
2026-11-05 15:03:26 -08:00
LGUG2Z 97c21b9360 merge: wip-cand6
Merge of wip-cand5, wip-u-bugfix, wip-u-wm, wip-u-settings3, wip-u-repotools,
wip-u-nix3 and wip-u-e2e2unit.

Resolutions:
- docs/dev/macos-handcheck.md: every section is kept, in order. The bugfix
  agent's section F (bar clicks) and the settings agent's section (also
  headed F) both appended after E; the settings one is renamed G, text
  unchanged.
- komorebi-for-mac/komorebi/src/animation/mod.rs and static_config.rs: the
  formatting-only revision of wip-u-nix3 (76ab52da, import order) conflicts
  with the semantic edits of wip-u-settings3 (S4/S5). The files are taken
  from wip-u-settings3 as they are; the following style(macos) revision
  formats them again with the check's rustfmt invocation.

Verified: see the following revisions and the report.
2026-11-05 15:03:26 -08:00
LGUG2Z acbe816fb4 test(core): follow the rename of the floating-window hook to before_floating_removed
wip-u-coretests (written against the hook's old name after_floating_removed) and wip-u-core4 (which renamed it to before_floating_removed because it runs before the window leaves the ring) were merged in candidate 5; the stub platform and the expected hook logs now use the new name. No behaviour change: the order test already pinned 'before the removal'. Verified: cargo test -p komorebi-core (with and without the schemars feature).
2026-11-05 15:03:26 -08:00
LGUG2Z b212b554cd docs(dev): macOS hand-check rows for the bar clicks and a list of findings needing a decision
macos-handcheck.md gets section F (rows M1-M3) for the battery, CPU/network
and update clicks fixed in the two preceding revisions (appended, the file is
kfm's). known-issues.md is new: four findings that are not fixed because
whether they are bugs, or the fix, is the owner's call, each with evidence
(file and line), why it may or may not be a bug, the platforms and a proposed
fix: KDE FocusWorkspaceNumber/Numbers/LastWorkspace without the pointer
monitor preamble, Monitor::focus_workspace overwriting a workspace name,
remove_container focusing focused-1, and the macOS subscriber push without a
write timeout.

Docs only. The line references were read in this tree (pointer-monitor
preamble compared between the Windows and KDE process_command.rs); nothing
was run.
2026-11-05 15:03:26 -08:00
LGUG2Z 7b070fffda docs: KDE and macOS window_manager.rs and router after the converge, and the blockers
docs/dev/core-model.md section 20: what the converge batch did (two
platform accessors, eleven macOS arms onto KDE's named methods), where the
two daemons stand (137 of 155 router arms byte-identical, 45% of KDE's
window_manager function lines identical with macOS), why it is below the
60% bar (macOS's ContainerExt against the shared Container with a hiding
spot, the ? against let _ policy, the platform entry points, the one-sided
functions) and the four blockers with the recommended next step.

Verified: not applicable (documentation); counts from the arm and function
comparison at this tip.
2026-11-05 15:03:26 -08:00
LGUG2Z 278ef8f3fc docs(settings): S4 and S5 as landed, macOS hand-check section F
docs/dev/settings.md section 10: what S4 and S5 moved, the differences
between the daemons that were kept on purpose (KDE resets transparency keys
on load and Windows keeps them; Windows animates a kind when the global flag
is on or the per-kind value is true, KDE and macOS let the per-kind value
win; the scoped guard on KDE, the suspend counter on macOS, the Windows
shutdown write). docs/dev/macos-handcheck.md section F (appended, nothing
else changed): the Mac checks for S3 and S5.

Verified: not applicable (documentation).
2026-11-05 15:03:26 -08:00
LGUG2Z f9b18a6f34 docs(tools): add tools/README.md and point build-and-test.md at the committed tools
tools/README.md describes each tool, the tiered loops of fast-check (tier 1 cargo check and
unit tests of the edited tree, tier 2 other-platform type-check or clippy, nix builds as the
pre-landing gate), the prerequisites (jj, nix develop, jq, flock) and how the fake C compiler
works for the macOS type-check. The measured warm times come from the host README and are dated
2026-10-31 (revision c89651fa). Personal progress-log and scratchpad references are removed.

docs/dev/build-and-test.md gets a "Developer tools" section and links to tools/ where it named
fast-check, kde-closure-check and the fake-CC command (the macOS block now says
`tools/mac-check.sh`).

Verified: links and commands read against the committed scripts; nothing else run.
2026-11-05 15:03:26 -08:00
LGUG2Z 7bfaf6479d perf(nix): stamp the commit only into the final macOS package
As for Windows and KDE: COMMIT_HASH was in the kfm commonArgs, so
buildDepsOnly (about 1000 dependencies) and every kfm check got a new
derivation for every commit and rebuilt in full on the Mac. commonArgs now
has the constant "nix-check"; only fullBuild, and so packages.default and
the extracted binaries, gets the real commit.

Verified: the darwin clippy, nextest and deps attributes cannot be
evaluated on this Linux host (a derivation of the stub source has to be
built), so the drvPath table of the other attributes is the evidence; see
the report. Needs a Mac build: after one cold build of the clippy check, a
docs-only commit must be a cache hit.
2026-11-05 15:03:26 -08:00
LGUG2Z f085064af9 docs(dev): e2e-to-unit, which e2e checks the shared crates made testable natively
Inventory of every Windows/shared e2e scenario and the KDE VM suites against the
native tests that exist after the consolidation: class A (covered, cited), B
(coverable with the shared crates, proposed test) and C (needs a real OS), with
effort and value, ordered with the Windows-only e2e behaviours first. Gives the
estimate of gate minutes saved today and if the B items existed, the seams the
shared crates lack (daemon command handler, rule matching shared in
komorebi-config, monitor reconciliation, stack cycling), and the tests added
with the e2e check each mirrors.

Verified: not applicable (documentation); the cited tests were read, and the
added ones were run (see their revisions).
2026-11-05 15:03:26 -08:00
LGUG2Z ba094355d4 chore(repo): combine the review fixes, new tests and docs (candidate 5)
Candidate 5: wip-cand4 plus kfw's review fixes (wip-u-fix5: revert of the subscriber write timeout and the hwnd writer thread, BAR_RUNNING tied to the message, dead-window HIDDEN_HWNDS cleanup, core in default-members), kfm's macOS registry fixes (wip-u-kfm3), kfde's hook rename and per-pass title-bar snapshot (wip-u-core4), the komorebi-core characterization tests (wip-u-coretests) and the docs (wip-u-docs). Conflicts, if any, are resolved here.
2026-11-05 15:03:26 -08:00
LGUG2Z 89f2872609 fix(bar): open the macOS settings, Activity Monitor and links with open
The macOS bar's battery click spawned cmd.exe /C start ms-settings:batterysaver
and the update click spawned explorer.exe, neither of which exists on macOS
(the move kept them on purpose, handcheck D.B). Both now go through `open`,
as the CPU, memory and network clicks already did.

The decision which program and arguments a click runs is a pure function,
system_tool_command(&SystemTool) -> (program, args), so the argv is unit
tested: task manager is `open -a 'Activity Monitor'`, the battery is
`open x-apple.systempreferences:com.apple.Battery-Settings.extension` (the
pane id of System Settings in macOS 13 and later, the scheme the network pane
already used; unconfirmed on a real Mac, hand-check row added), a URL is
opened as is, a storage label opens its path. The module is macOS only
(cfg(target_os = "macos") at the crate root), so none of this is built
elsewhere.

BEHAVIOUR (macOS): clicks on the battery and update widgets now open
something. Gate: macOS hand-check rows M1-M3 in docs/dev/macos-handcheck.md and
the unit tests on the Mac (cargo test -p komorebi-bar). Verified: type-check
only on Linux (see the fast-check result in the progress log); tests not run
here.
2026-11-05 15:03:26 -08:00
LGUG2Z 595e9c46a1 refactor(kde,mac): monitor_idx_from_current_pos asks window::monitor_id_at_cursor()
Both daemons' window.rs have monitor_id_at_cursor() (KDE: the backend's
pointer position resolved to the monitor under it; macOS: MacosApi's
monitor_from_point of its cursor position), and monitor_idx_from_current_pos
in both window_manager.rs files is now the same text up to its macOS-only
comment block. No behaviour change.

Verified: KDE cargo test -p komorebi-linux (lite env): 664 passed, 0
failed; fake-CC cargo clippy -p komorebi-macos ... --all-targets -D
warnings: PASS; Windows cargo clippy -p komorebi-windows --locked
--all-targets -D warnings: PASS (the whole-workspace Windows clippy fails
in komorebi-bar, E0046 missing release_page_url, which is not in this
change and fails at the base). Not run: the macOS tests (the Mac Mini).
2026-11-05 15:03:26 -08:00
LGUG2Z b12be4b1a7 refactor(windows): move window_handling_behaviour to the platform settings, scoped guard in the border test
Plan step 10, part of S7 and the scoped guard asked for in S5.
WINDOW_HANDLING_BEHAVIOUR is no longer a static: it is
settings().platform.window_handling_behaviour (WindowsSettings, default
Sync). The load writes it with one update when the key is present (a missing
key keeps it, as before); windows_api (the position calls) and scrolling read
it through settings::window_handling_behaviour(), once per call.

The border paint test (border_manager/border.rs is_painted) saved the static,
stored a value and stored the old one back, which overwrote any change made in
between. It now holds Handle::scoped on the field, which puts the previous value
back on drop only if the field still holds the value it set.

BEHAVIOUR: the position calls read a snapshot instead of an atomic cell (one
RwLock read and Arc clone per call), and the load publishes the key through the
handle. Gate: Windows e2e (commands, config_reload, lifecycle; anything that
moves windows with window_handling_behaviour async if configured).

Verified: Windows clippy -D warnings --locked --all-targets on
komorebi-windows (cross): clean. e2e not run; the border paint test needs a
desktop and was not run.
2026-11-05 15:03:26 -08:00
LGUG2Z 1879b86a5c build(tools): add trim-target, gate-lock and lite-env
Optional helpers for a shared host: trim-target deletes stale test executables from the
persistent cargo target dirs, gate-lock is a FIFO flock for heavy and timing-sensitive gates,
lite-env sources debug-info-off cargo settings. Copies of the host-side scripts with these
differences:
- trim-target: the default scratch dir is `${XDG_CACHE_HOME:-$HOME/.cache}/komorebi-fast-check`
  (was a /tmp/claude-1000/... scratchpad path), the same as fast-check;
- gate-lock: GATE_LOCK_DIR defaults to `${XDG_STATE_HOME:-$HOME/.local/state}/komorebi-gate`
  (was /home/jado/komomono-work/.gate), in the header and in the code;
- gate-lock: "/proc/$pid/cmdline" is quoted and a shellcheck directive disables SC2012 and
  SC2016 (ls of plain queue ticket names, and a bash -c script expanding its own $1);
- lite-env: a `# shellcheck shell=bash` first line.
Not committed: mini (host and credential specific), host-sample and jitter-probe (host
measurement), the .bak files.

Verified: bash -n and shellcheck clean. Not run: gate-lock was tested by its author with a scratch
GATE_LOCK_DIR before this change; the default path change is untested.
2026-11-05 15:03:26 -08:00
LGUG2Z af5ac69749 fix(deny): clarify the license of the workspace crates the macOS deny check sees
The kfm deny check failed with `licenses FAILED`: the unified workspace's
crates have no license field and the macOS deny.toml only clarified the old
crate names. Twelve clarify entries (LicenseRef-Komorebi-2.0, as for the
existing ones) now cover komorebi-backend, -bar, -bar-core, -client,
-collections, -config, -core, -protocol, -settings, -transport, komorebic and
komorebic-core.

Verified: cargo deny --offline --workspace with the flake's 11 --exclude
arguments and `check --config komorebi-for-mac/deny.toml bans licenses
sources` (nix shell nixpkgs#cargo-deny, on the Linux host over the same
Cargo.lock): bans ok, licenses ok, sources ok; taplo --check passes on the
file. The check on the Mini is not re-run.
2026-11-05 15:03:26 -08:00
LGUG2Z 231e50b3fc test(core): tiling arithmetic of update_shared as native checks of the e2e layouts
The Windows e2e scenarios layouts (111 checks), flipping, layout_flip, padding,
closing, minimizing, floating, stacks, tiling and tiling_off assert where the
tiles of a workspace are. Since the consolidation every daemon gets those tiles
from komorebi-core's Workspace::update_shared, so they can be checked on the
stub platform on Linux (and on the Mac Mini for macOS) instead of in a guest.

crates/komorebi-core/tests/e2e_layouts.rs (6 tests) runs update_shared on a
StubPlatform workspace for the 8 layouts of the scenario, 1 to 8 containers and
three padding settings: one tile per container, inside the work area, not on
each other; workspace padding moves tiles 40 px in, container padding shrinks
every tile, and back as it was; each of the three flips equals the plain tiles
mirrored (as a set); removing a container (what a closed, minimized or floated
window does) leaves the others at least as much room; two containers, one a
stack of two, are two tiles; with tiling off nothing is placed in any layout.
Each test names the e2e checks it mirrors. They protect Windows, KDE and macOS
alike. Platform dependent: the stub adds no border and no frame adjustment, so
the Windows border of 7 px (windows_padding) and each daemon's own
adjust_layout stay e2e only, as does the OS frame matching the tile.

Verified: cargo test -p komorebi-core --test e2e_layouts, 6 passed (native
Linux; macOS crates run later on the Mini). No source change, no bug found.
2026-11-05 15:03:26 -08:00
LGUG2Z 4a829a886c chore(repo): komorebi-core is a default member of the workspace
Review finding 3. crates/komorebi-core was a member but not in default-members,
so a bare cargo test or cargo clippy at the root did not build it and its tests
(27, 30 with the schemars feature) never ran in the Windows set. komorebi-daemon
was already in the list. cargo test -p komorebi-core passes with and without
--features schemars: komorebi-layouts keeps Layout::Custom without the Win32
dependency, so no cfg needed fixing. (The komorebi-config crate prints an
unused-import warning of its own when built alone with default-features off,
pre-existing and not an error in the workspace build, where features unify.)

Verified: cargo test -p komorebi-core: 27 passed; with --features schemars: 30
passed; tools/fast-check (native, Windows clippy -D warnings, KDE, macOS) PASS.
2026-11-05 15:03:26 -08:00
LGUG2Z ba25355cca docs(macos): the review's checks H1-H12, the registry's lifetime rules, and the known subscriber hang
docs/dev/macos-handcheck.md: a prioritised section with the independent review's twelve
hand checks and their exact steps (hide spot on the right display, event
latency with a stopped app, native tabs, floating and monocle, scrolling, config
reload, old state with the bar, pause and quit, bar config, unsupported commands,
registry growth, hung subscriber), a row for the wip-u-kfm3 registry fixes, and
a known-issue note: a subscriber that stops reading can stall the daemon (the
push writes under the window manager lock with no timeout; pre-existing and
the same in the original). A write timeout was deliberately not added: the
Windows review found it can truncate the JSON notification and does not bound
the stall, so the fix is a design, not a timeout.

ax_registry.rs module docs: when an entry is created (when the observer is
attached), the inert application, where it ends (the reapers, application
quit), why not in Window::drop, and what is not enforced (an observed
window that closes without passing through the reapers keeps its entry until its
application quits; cost and the unverified Mach-port question).

Verified: fake-CC cargo clippy --locked -p komorebi-macos --all-targets -D
warnings clean; tools/fast-check --since wip-cand4: native, Windows clippy, KDE
check + lib tests, macOS PASS; cargo test -p komorebi-core -p komorebi-backend
pass. Not verified: any run on macOS.
2026-11-05 15:03:26 -08:00
LGUG2Z 48861ece10 docs: correct the title-bar claim and name the renamed hook (F2, F3)
docs/dev/core-model.md section 19: remove_floating_window's hook is
before_floating_removed (behaviour unchanged), and the Windows title-bar
tables are taken once per pass through begin_pass; the sentence of
section 16 that called the per-container read an improvement is
corrected.

Verified: not applicable (documentation).
2026-11-05 15:03:26 -08:00
LGUG2Z fa3ec1ba2e test(core): add the review's gaps: floating hook order, placement rules, hook defaults, key sets
Follow-up to the review of komorebi-core (S/review/core.md, F2 and F4 and its
untested-behaviours list); most of the list was already pinned, this adds the rest:
- the after_floating_removed hook is pinned to run BEFORE the window is taken out
  (it sees both windows and the old focus index), today's KDE/macOS order, although
  the trait doc says after; the stub now logs len and focus for the hook.
- resolve_placement_index with Rules maps (Single and Many matching, Secondary,
  no match falls back after the focused container); the stub gained a match id and a
  path (a window without a path never matches Rules: it falls back).
- the JSON key set of a default workspace, and of Windows and macOS monitors per extra.
- the documented defaults of every optional hook on a platform that overrides nothing
  (the KDE-shaped test platform), and that the default place hooks make update_shared fail.
- Monitor remove_workspace_by_idx at the length, and an old monitor file with a
  non-empty ring of workspaces missing optional keys.

Verified: cargo test -p komorebi-core 215 passed, 1 ignored (the known bug), and with
--features schemars 217 passed, 1 ignored; clippy --all-targets has no warning in the
crate. No non-test source changed.
2026-11-05 15:03:26 -08:00
LGUG2Z 824c8b6d07 docs: point CONTRIBUTING.md at the developer documentation
The root CONTRIBUTING.md is only the licence terms and did not say where the
layout and the build commands are. It now names docs/dev/ARCHITECTURE-UNIFIED.md
and docs/dev/build-and-test.md. Docs only, nothing built.
2026-11-05 15:03:26 -08:00
LGUG2Z d7673d436f fix(bar): the update widget asks the platform for its release URLs
The update widget's refresh thread polled the Windows repository's GitHub
API on every platform (a hard-coded second URL, while the first fetch went
through BarPlatform::latest_release_api_url), and the page the click opens
was built for the Windows repository, so on macOS the widget compared the
mac version against Windows releases after the first refresh and linked to
the wrong project.

The refresh now uses latest_release_api_url, and a new
BarPlatform::release_page_url(version) builds the click target: Windows
keeps https://github.com/LGUG2Z/komorebi/releases/v{version} exactly,
macOS gets https://github.com/LGUG2Z/komorebi-for-mac/releases/tag/v{version}.

BEHAVIOUR (macOS): the update widget compares against and links to the
komorebi-for-mac releases. Windows output is unchanged (same URLs). Gate:
macOS hand-check (see docs/dev/macos-handcheck.md); Windows needs no e2e.
Verified: see the following revisions' fast-check results; not run on a Mac.
2026-11-05 15:03:26 -08:00
LGUG2Z 4836a39b1c refactor(mac): ToggleWorkspaceWindowContainerBehaviour calls the named method KDE has
The arm was the same code inline as toggle_workspace_window_container_behaviour
on KDE (the two differ only in how rustfmt wrapped the match arms). The macOS
arm calls a method with that name and body. No behaviour change.

Verified: fake-CC cargo clippy -p komorebi-macos ... --all-targets -D
warnings: PASS (type-check only). Not run: the macOS tests (the Mac Mini).
2026-11-05 15:03:26 -08:00
LGUG2Z 482c42d64f refactor(windows): move the animation settings to settings
Plan step 10, S5 for Windows. The six ANIMATION_* statics (global enabled,
style, duration; per-kind enabled, style, duration) and ANIMATION_FPS are
gone (ANIMATION_MANAGER and GHOST_MOVEMENT_ENABLED stay: runtime state and a
Windows-only setting). The Animation, AnimationDuration, AnimationFps and
AnimationStyle commands each write settings().shared.animation with one
update; the animation block of a load is one update through
SharedDelta::apply (a global value clears that setting's per-kind map, a map
replaces it, a block without fps has the default, no block keeps all);
shutdown (daemon.rs, window_manager.rs) is animation_off_for_good(), one
update that clears the per-kind map and turns the global flag off.

Readers keep Windows' own rules, which are NOT the KDE and macOS ones: a kind
is animated when the global flag is on OR its per-kind value is true (a
per-kind false does not turn off a global true), and the workspace transition
helpers keep their per-kind-wins rule; the accessors in settings.rs
(animation_enabled_for, animation_for) encode the first and the existing
transitions_enabled_by / duration_for / style_for are fed from one snapshot.
Window::move/transparent/opaque and the maximize wait read enabled, duration
and style from one snapshot, and no longer hold the per-kind map's lock for the
rest of the function.

BEHAVIOUR: no thread can see half an animation reload; one publish per load or
command. Gate: Windows e2e (animation, config_reload, lifecycle for the
shutdown path, commands).

Verified: Windows clippy -D warnings --locked --all-targets on
komorebi-windows (cross): clean. e2e not run.
2026-11-05 15:03:26 -08:00
LGUG2Z 27b36a457e build(tools): add kde-closure-check and e2e-needed
kde-closure-check fails when komorebi-for-kde/nix/root-crates.json differs from the KDE cargo
closure; e2e-needed says whether a diff touches anything the Windows e2e binaries are built
from. Copies of the host-side scripts with these differences only:
- kde-closure-check: none (it already finds the repository relative to the script); verbatim.
- e2e-needed: `tools/*` joins the paths that cannot change the binaries (docs, .github), so a
  change to the tools is NO instead of "not understood: treated as needed";
- e2e-needed: `# shellcheck disable=SC2001` before `set` (the sed one-liners indent multi-line
  output); no behaviour change.

Verified: bash -n and shellcheck clean; `tools/kde-closure-check .` prints "ok: 11 root crates
match the KDE cargo closure"; `tools/e2e-needed --since <rev>` gives the same output as the host
copy on a range without tools/ files, and NO for a tools-only range.
2026-11-05 15:03:26 -08:00
LGUG2Z e3c1702aa6 style(manifests): format six Cargo.toml files with taplo
Pure formatting, no other change: taplo fmt (default configuration, taplo
0.10.0) over the manifests that the kfm toml-fmt check reported as not
properly formatted: crates/komorebi-bar-core, crates/komorebi-protocol,
komorebi-client, komorebi-daemon, komorebi-for-mac/komorebi and
komorebi-for-mac/komorebic. The other 19 files that check lists were
already clean.

Effect on other platforms: the first four are Windows manifests and
komorebi-protocol is also in the KDE closure. crane's dependency derivation
contains the manifests, so the Windows and KDE dependency derivations and
checks change once with this revision (one cold rebuild of the
dependencies, then stable again).

Verified: taplo fmt --check over the 25 files of the check passes after it
(it failed on exactly these six before).
2026-11-05 15:03:26 -08:00
LGUG2Z ddc4b95b8d test(komorebic-core): the commands of the e2e sweep are commands of the command lines
The commands e2e scenario learns that a command does not exist in a platform only
by running it in a guest (error: unrecognized subcommand, skipped with its name),
about 7.6 minutes per Windows run.

crates/komorebic-core/tests/e2e_sweep.rs reads SWEEP and PRINTED out of
e2e/lib/komorebi_vm/core/scenarios/commands.py (skipped when the e2e library is not
in the source tree) and parses each line with the platform's clap command: every
one is a command of the Windows komorebic, and the macOS one lacks exactly the
eight the scenario would skip there (focus-follows-mouse enable/disable, the
Windows implementation of toggle-focus-follows-mouse, toggle-maximize, the
transparency commands). 3 tests. mirrors: commands / <command> (the command is
understood, for the command line only).

Stays e2e only: that the daemon then answers; the KDE komorebic's own command set.

Verified: cargo test -p komorebic-core --test e2e_sweep, 3 passed (native Linux;
platform independent). No source change.
2026-11-05 15:03:26 -08:00
LGUG2Z 74042cd70c fix(windows): a dead window is taken out of HIDDEN_HWNDS when the backend refuses it
Review finding 5. WindowsBackend::live() failed with WindowGone before
Window::hide, restore, maximize and unmaximize ran, so the bookkeeping those
do to HIDDEN_HWNDS never happened for a dead handle: restore, maximize and
unmaximize always removed the handle from the list (original behaviour), and
a handle hidden before its window died stayed in the list for ever (the
reaper's cache and the border and layout code read it). live() now removes the
handle (forget_hidden, a pure helper) before it returns the early WindowGone,
which callers that need it still get. Every backend operation goes through
live() (hide, restore, minimize, unminimize, maximize, close, raise, focus,
set_rect), so every path cleans up. A hide of a dead window no longer pushes
the dead handle into the list, which the original did and nothing ever removed.

Tests: forget_hidden (pure, native logic) and live() on a handle that is not a
window; they compile here (clippy --all-targets passes) but the Windows crate's
tests cannot run on this host: NOT run.

BEHAVIOUR: dead-window cleanup only. e2e: lifecycle_hidden, commands.
Verified: Windows clippy -D warnings via tools/fast-check PASS.
2026-11-05 15:03:26 -08:00
LGUG2Z 1a20d58eec test(backend): registering drops nothing; a replaced handle is dropped by the caller
Pins the cost rule the macOS fix depends on: Registry::insert of a new id runs no
handle's drop, a replaced handle is handed back and dropped only when the
caller drops it, get drops nothing, and remove hands the handle back. A probe
handle counts its drops.

Verified: native cargo test -p komorebi-backend: 40 unit, 7 doc, 1 compile_fail
passed, 0 failed.
2026-11-05 15:03:26 -08:00
LGUG2Z 483a38cff6 refactor(windows): the title-bar rules are taken once per pass, through begin_pass
BEHAVIOUR (Windows runtime): restores the original read of the title-bar
tables. WindowsPlatform::begin_pass takes REMOVE_TITLEBARS, NO_TITLEBAR
and REGEX_IDENTIFIERS once per placement pass (after the layout is
computed, as the old pass loop did) and place_container reads that
snapshot from Placement::pass, instead of locking and cloning the two
tables for every container, where a configuration reload in the middle of
a pass could give two containers two tables. Reviewer finding F3
(Windows review finding 6).

Windows e2e scenarios needed: layouts, stackbars and title-bar scenarios
(remove-title-bar, toggle-title-bars, no_titlebar rules), config_reload
(a reload while windows are being placed).

Verified: Windows clippy --locked --all-targets -D warnings: PASS; KDE
cargo test -p komorebi-linux (lite env): 664 passed, 0 failed; macOS
fake-CC check: PASS; komorebi-core tests: 30 passed. Not run: Windows
tests, e2e.
2026-11-05 15:03:26 -08:00
LGUG2Z 38f1295251 test(core): pin the state JSON of the three daemons from real fixtures
tests/state_roundtrip.rs (15 tests) reads the monitors of the e2e fixtures
(Windows kfw-tiled, kfw-stack, kfw-float; KDE kfde-tiled, kfde-stack) into the
shared Monitor<P> with a platform shaped like each daemon (Windows: isize id,
optional serial number, the name/device_id/workspace_names extra; KDE: u32 id,
string serial number, no extra; macOS: window_hiding_position extra), writes
them again and compares the parsed JSON: every fixture is written as it was
read. Also pins that the corner is the last macOS monitor key and cannot be
omitted, that the workspace keys are the same whatever the platform, the exact
set of KDE monitor keys, and which keys an old state file may omit (23 optional
keys at monitor, workspace and container level, e.g. container locked and
workspace layout_options_rules) and which it may not (18 required keys,
including layer, work_area_offset_rules and apply_window_based_work_area_offset:
a file from before those existed does not load; pinned, not judged).

The fixtures are copied into tests/common/fixtures.rs as Rust text because the
nix source filters keep .rs files and drop .json; a test compares the copies with
e2e/lib/tests/fixtures when the checkout has them. The macOS fixture is NOT real
macOS output: it is kfde-tiled reshaped with jq to the macOS window and monitor
shape of the state_pin tests (no Mac here), and says so in its comment; replace
it with 'komorebic state' from a Mac when one is at hand.

Verified: cargo test -p komorebi-core (27 unit + 179 integration passed, 1
ignored) with and without --features schemars; cargo clippy -p komorebi-core
--all-targets has no warning in the crate. Windows clippy and macOS check not run:
the tests are portable crate tests and no platform source changed.
2026-11-05 15:03:26 -08:00
LGUG2Z 9c2c50cc40 docs: build-and-test.md, the commands and the known flakes per platform
One page with the exact commands for each platform, so nobody has to
reconstruct them from the flakes and the progress notes:

- Windows: nix cross build of the binaries, the crane checks (clippy is the
  pre-landing gate), the e2e-tests check, native tests of the neutral crates;
- KDE: cargo check/test with the right package names (the unit tests are in
  komorebi-linux, not the thin komorebi binary package), the schema test with
  one thread, the kfde-* checks of the root flake, the VM suites with `just vm`,
  the tier lists, E2E_ONLY and KOMOREBI_RECORDER for VM runs;
- macOS: cargo build/test/clippy with `-p komorebic -p komorebi -p komorebi-bar`,
  never `-p komorebic-macos` together with `-p komorebic`, and the Linux-only
  type-check;
- Windows e2e: `nix run .#e2e-windows`, the `bar` scenario, E2E_ONLY, trace,
  recorder, KEEP_GUEST, SCALE, STATE, bins from another commit;
- a what-to-run table and the known flakes with counts, summarised from the
  flake registry kept by the gate runs (no personal paths).

It also records that komorebi-for-kde/justfile still assumes a KDE-only
workspace (`just check` would build the Windows crates).

Verified by running: `cargo metadata --no-deps` (package names), `cargo check
-p komorebi-linux -p komorebi -p komorebic` in komorebi-for-kde (ok), `nix eval
--json .#legacyPackages.x86_64-linux.vmTiers` (the tier lists match). Other
commands were read from flake.nix, justfiles and the e2e README, not run.
2026-11-05 15:03:26 -08:00
LGUG2Z 0f851bfb0a docs(cli): regenerate the stale Windows command pages
docs/cli lagged behind the Windows komorebic: 35 pages had out-of-date
help text (possible values now listed with their descriptions, new doc
comments, the Scrolling commands without the komorebic.exe usage name) and
3 pages did not exist yet. They are regenerated from the current Windows
CLI definition (komorebic-core docgen-all example, platform windows,
COLUMNS=1000 so nothing is re-wrapped like the existing pages), and the
page conventions of each file are kept: header line only where the page had
one, komorebic.exe as the binary name, trailing newline. The other 149
pages are byte-identical to the fresh output. The KDE and macOS pages are
untouched (decision D20: Windows was the only stale set).

Docs only, no behaviour. Verified: regenerated twice, second compare shows no
diff; the real Windows binary was not run (the pages come from the shared
definition rendered on Linux, class text normalised to the Windows one).
2026-11-05 15:03:26 -08:00
LGUG2Z 55a57cb030 refactor(mac): four more process_command arms call the named methods KDE has
LayoutRatios, Query, NamedWorkspaceRule and InitialNamedWorkspaceRule were
the same code inline on macOS as set_layout_ratios, answer_query,
add_named_workspace_rule and add_initial_named_workspace_rule on KDE
(compared with whitespace removed). The macOS arms call methods with those
names and bodies and are byte-identical to KDE's. No behaviour change. The
other inline macOS arms differ in what they do (ReplaceConfiguration has
the run loop and no warning, ToggleWorkspaceWindowContainerBehaviour,
SessionFloatRule, IgnoreRule, ToggleWorkspaceLayer and ResizeWindowAxis
have other bodies) and stay.

Verified: fake-CC cargo clippy -p komorebi-macos ... --all-targets -D
warnings: PASS (type-check only). Not run: the macOS tests (the Mac Mini).
2026-11-05 15:03:26 -08:00
LGUG2Z d6c0c6f115 refactor(windows): move transparency enabled and alpha to settings
Plan step 10, S4 for Windows. TRANSPARENCY_ENABLED and TRANSPARENCY_ALPHA are
no longer statics: the Transparency, TransparencyAlpha and ToggleTransparency
commands write settings().shared.transparency with one update, the load
applies the two keys as one update (Windows keeps the value when a key is
absent, unlike KDE), the transparency thread, process_event, window.rs and
the state/config dump read through the accessors.

BEHAVIOUR: ToggleTransparency was a load then a store and is now one update;
a load publishes the two keys together. Gate: Windows e2e (transparency,
config_reload).

Verified: Windows clippy -D warnings --locked --all-targets on
komorebi-windows (cross): clean. e2e not run.
2026-11-05 15:03:26 -08:00
LGUG2Z 131a3cb9f8 build(tools): add fast-check, the minimal checks for the touched paths
Runs only the checks a jj diff needs (KDE cargo check and tests, macOS type-check, Windows
clippy through the nix dev shell, native crate tests, nix evaluation only) with persistent
target dirs, and prints the time of each. Copy of the host-side script (the original stays
in use outside the repository) with these differences:
- FAST_CHECK_SCRATCH defaults to `${XDG_CACHE_HOME:-$HOME/.cache}/komorebi-fast-check`
  instead of a /tmp/claude-1000/... scratchpad path (usage text updated);
- the fake C compiler is `$HERE/cc-fake.sh` (the script directory, resolved with readlink -f)
  instead of `$S/kfm/cc-fake.sh`;
- `tools/*` is classified like docs (no check), so a change to the tools alone prints
  "nothing to run" instead of listing every file as unclassified;
- the second `case` arm lost the patterns `Cargo.toml | Cargo.lock | .cargo/*`, which an earlier
  arm already catches (shellcheck SC2221/SC2222; no change in behaviour);
- header comment: "from anywhere inside a jj workspace of the repository", no mention of komomono.
Everything else is byte-identical (diff against the host copy).

Verified: bash -n and shellcheck clean; `tools/fast-check --list` from this workspace.
2026-11-05 15:03:26 -08:00
LGUG2Z e95d146bae style(macos): format the macOS code with the project's rustfmt settings
Pure formatting, no other change: nightly rustfmt --edition 2024 with
komorebi-for-mac/rustfmt.toml (imports_granularity = Item) over
komorebi-for-mac/**/*.rs and the macOS modules in the shared directories
komorebic/src/macos and komorebi-bar/src/macos. 11 files; the kfm fmt check
of the previous revision reported them. Windows and KDE code is not touched,
and the Windows source filter excludes those macos files, so no Windows or
KDE derivation changes.

Verified: the rustfmt --check command of the fmt check passes on the result
locally; nix eval of drvPath in a throwaway git copy: Windows deps and
clippy, kfde deps, clippy and vm stacks are identical before and after it.
2026-11-05 15:03:26 -08:00
LGUG2Z b3589b7b7b test(kde): sweep of the model commands through process_command
The commands e2e scenario (265 checks, about 7.6 minutes on the Windows gate, a
stall-prone sweep) asserts after each of about 216 komorebic commands that the
daemon is alive, answers state and manages every window. For the commands that
only mutate the model that is not a property of a real OS.

komorebi-for-kde/komorebi/tests/command_sweep.rs sends the SocketMessage of each
model command of the scenario's SWEEP, in its order (focus, move, stack,
resize, promote, flip, layouts, toggles, workspaces, monitors, offsets,
padding, behaviours, rules, scrolling), through WindowManager::process_command
over a FakeBackend with two monitors and three windows, and after each asserts
that every window is still managed (any monitor, workspace, layer), and that the
state query answers JSON. A command may refuse (a direction with no window): only
that refusal is accepted as an error. The sweep runs in 0.2 s.

mirrors: commands / <command> leaves the daemon healthy.

What stays e2e only: komorebic parsing each command and writing that message,
the pointer, files and config reload commands, a command that stalls the
daemon while the socket waits, and everything the real OS does with the windows
(the sweep's healthy check against the OS's windows).

Verified: cargo test -p komorebi-linux --test command_sweep in komorebi-for-kde,
1 passed (native, Linux). KDE daemon only: the Windows and macOS daemons have no
native harness. No source change, no bug found.
2026-11-05 15:03:26 -08:00
LGUG2Z b5a634f59c revert: write komorebi.hwnd.json from a writer thread
Reverts 3d2386e3 (review finding 8). The detached latest-wins writer thread
left the file lagging behind the daemon (a command that returned, or stop, could
precede the write, and std::process::exit cut a write in progress), and it
opened and truncated the file in place, so a reader could see it half written.
The file is small and the synchronous write was the original behaviour; the
stall analysis did not show it to be a cause of any hold (the per-step and
lock-holder instrumentation of the same stack will show whether it ever is).
Restoring the synchronous write in update_known_hwnds and the reaper is the
simplest form that is correct: the file is complete when the command returns
and when stop exits.

Behaviour is the original again for the file. Verified: Windows clippy
-D warnings via tools/fast-check PASS; e2e: lifecycle and commands (the file is
written again before the reply).
2026-11-05 15:03:26 -08:00
LGUG2Z 5b5647ea34 fix(mac): forget the windows that the application reaper removes
BEHAVIOUR (registry only). Review finding 4, the part that can be done where a
window id is known.

Window::observe now registers the windows that are really observed (previous
revision), and a window that closes while its application runs left its entry
until the application quit. WindowManagerEvent::Destroy carries no window id,
but reap_invalid_windows_for_application is where the daemon works out which of
the application's windows are gone, and it already removes them from the
workspace: it now also forgets them in the registry (tiled and floating
alike); the reaper's reap_window did already.

What stays: an observed window that closes without passing through either
(for example one that was unmanaged and then closed, or whose Destroy was not
followed by a reap) keeps its entry (an element, an observer and an inert
application) until its application quits; the table is bounded by the number
of windows the daemon has observed per running application, and a periodic
sweep would cost one Accessibility call per entry under the window manager lock.
Hand check H4 measures the Mach ports held (the one unverified cost: whether an
AXObserver holds a port).

Verified: macOS fake-CC type-check (tools/fast-check) PASS. Not verified: any
run. Verified on the Mini: not yet.
2026-11-05 15:03:26 -08:00
LGUG2Z 66fb7ef585 feat(core): update_shared has a begin_pass hook whose answer the hooks of the pass see
WorkspacePlatform::begin_pass(workspace) is called once per placement
pass, after the layout is computed and before the containers are placed,
and what it returns is handed to adjust_layout and place_container as
Placement::pass (Placement now carries that borrow). A platform that has
something to read once for the whole pass takes it here, so that two
containers of a pass cannot see two different values. The default returns
None. A test with the stub platform pins the order (once per pass, before
the placements) and that the hooks see the answer.

For reviewer finding F3 (S/review/core.md): the Windows title-bar tables
were read once per pass and the shared update read them once per
container; the Windows revision that follows uses this hook.

Verified: cargo test -p komorebi-core --features schemars (native): 30
passed, 0 failed. Not run: the daemons (the next revision builds them).
2026-11-05 15:03:26 -08:00
LGUG2Z f74e201f64 test(core): pin Monitor workspace management
tests/monitor_workspaces.rs (22 tests) over the recording stub platform:
ensure_workspace_count (grows with default workspaces, never shrinks, leaves
the focus), focus_workspace (last_focused_workspace bookkeeping including
focusing the focused one, creating every workspace up to a focused index past
the end, the empty monitor), the known workspace name (without a known name
names stay; with one only the focused workspace takes it, and an EXISTING
workspace's name is overwritten at every focus although the comment says
only at creation: pinned as it is, inherited from the Windows tree),
remove_workspace_by_idx (index not moved, past-the-end focuses idx-1 creating
workspaces, empty monitor gets a default one), remove_workspaces, add_container
with and without a workspace index and the error cases, the focused layout
only while tiling, and the JSON of last_focused_workspace and a round trip.

Verified: cargo test -p komorebi-core --test monitor_workspaces, 22 passed.
No non-test source changed.
2026-11-05 15:03:26 -08:00
LGUG2Z 0008c6c27d docs: ARCHITECTURE-UNIFIED.md, a map of the repository after the consolidation
A new reader had no single page that said where things are: three platform
trees, nine shared crates, the four unified packages, the shims that remain,
and which differences are on purpose. The page gives:

- the three trees and what lives in each (root = Windows, komorebi-for-kde,
  komorebi-for-mac) and that the root Cargo.toml is the only workspace;
- the packages komorebi (komorebi-daemon, cfg_select! over komorebi-windows,
  komorebi-linux, komorebi-macos), komorebic, komorebi-client, komorebi-bar
  and their cfg(target_os) layout, and the shim packages until the cutover;
- the crates/ map (protocol, config, collections, transport, backend, core,
  settings, bar-core, komorebic-core);
- where the platforms differ on purpose, with a pointer to seam.md,
  core-model.md, settings.md, unified-binaries.md, bar-unification.md and
  macos-handcheck.md;
- the oracles (wire goldens, config and bar schemas, CLI docs, derivation
  drift) and the tiered feedback loops;
- the tools outside the repository (fast-check, mac-check.sh,
  kde-closure-check, e2e-needed, gate-lock, ...) with a proposal of which to
  commit; nothing was moved.

Statements were checked against Cargo manifests (cargo metadata --no-deps
lists the package names used), flake.nix and the source directories. The
version numbers and the packages list were read from manifests. Not built;
macOS statements are what the progress log says, not observed.
2026-11-05 15:03:26 -08:00
LGUG2Z 3cc8ff63b3 fix(core): constrain the main container of the right-main vertical stack at index 0
enforce_resize_for_right_vertical_stack said "Zero is actually on the right"
but locked top, bottom and right of resize_dimensions[1], so the main
container (index 0, drawn on the right: arrangement.rs primary_left =
area.right - primary_width) was never constrained and the first stack
container could not be resized at all. Index 0 now loses top, bottom and
right (it can only grow to the left); the stack loop over [1..] is unchanged
(nothing in it goes left, first not up, last not down).

The test that pinned the buggy result is replaced by the previously ignored
test of the intended behaviour, un-ignored and extended to 1 to 4 tiles:
[l, rb], [l, rb, tr], [l, rb, trb, tr].

BEHAVIOUR (all three daemons share this function): resizing in the
right-main-vertical-stack layout changes. Gate: Windows e2e resize
scenarios; the ones that run in right-main-vertical-stack are none by name
(resize_commands uses the default layout; layouts.py and commands.py only
tile and cycle through right-main-vertical-stack), so a pointer or
resize-edge scenario in that layout would need adding.

Verified: cargo test -p komorebi-core, with and without --features schemars,
all pass; no e2e run.
2026-11-05 15:03:26 -08:00
LGUG2Z ddc1a231c5 refactor(mac): seven process_command arms call the named methods KDE has
Part of the router converge between KDE and macOS: CycleFocusWorkspace,
CycleFocusEmptyWorkspace, CloseWorkspace, MoveContainerToLastWorkspace
(and SendContainerToLastWorkspace, which is the same method with
follow = false), EagerFocus and BorderColour were the same lines inline on
macOS as the methods cycle_focus_workspace, cycle_focus_empty_workspace,
close_workspace, move_container_to_last_workspace, eager_focus and
set_border_colour on KDE (compared with the arms' text, apart from where
rustfmt wrapped a line). The macOS arms now call methods with those names
and bodies; the arms are byte-identical to KDE's. No behaviour change.

Verified: fake-CC cargo clippy -p komorebi-macos -p komorebic-macos -p
komorebi-client-macos -p komorebi-bar-macos --all-targets -D warnings:
PASS (type-check only). Not run: the macOS tests (the Mac Mini), KDE and
Windows gates (no KDE or Windows file changed).
2026-11-05 15:03:26 -08:00
LGUG2Z 04af7fcbbf test(settings): pin the transparency and animation load rules
tests/reload.rs: transparency is kept by a load without the key when the
daemon passes the keys as they are (Windows) and reset to false and 200 when
it passes unwrap_or (KDE); an animation block with a per-kind map replaces
the map and leaves the global flag, a load with no block keeps everything, a
global flag clears the map and a block without fps resets fps to 60. Test
only.

Verified: native cargo test -p komorebi-settings: 18 unit + 5 integration
passed.
2026-11-05 15:03:26 -08:00
LGUG2Z 2a8b71f1c9 build(tools): add the fake C compiler and mac-check.sh for the macOS type-check on Linux
macOS cannot be built or linked on the Linux host; the way to type-check it is
`cargo check --target aarch64-apple-darwin --all-targets` with a fake C compiler so the
C -sys crates' build scripts succeed. That compiler was only a scratchpad file outside the
repository and mac-check.sh hardcoded a workspace path.

tools/cc-fake.sh: verbatim copy of the scratchpad cc-fake.sh (emits an empty object for
every compile, hands -E to the real gcc). No difference.

tools/mac-check.sh: new copy of the old script with these differences:
- no hardcoded `cd /home/jado/komomono-work/ws-step4/komorebi-for-mac`: the root comes from
  `jj root` (fallback `git rev-parse --show-toplevel`);
- the fake CC is `$HERE/cc-fake.sh` (next to the script) instead of `$S/kfm/cc-fake.sh`;
- the target dir is `${FAST_CHECK_SCRATCH:-${XDG_CACHE_HOME:-$HOME/.cache}/komorebi-fast-check}/target-fast-mac`
  instead of a /tmp/claude-1000 scratchpad;
- in the merged tree (komorebi-for-kde has its own Cargo.toml only in the old layout) it checks the
  packages fast-check checks (-p komorebi -p komorebi-macos -p komorebic-macos
  -p komorebi-client-macos -p komorebi-bar-macos) from the root; with the old separate workspace it
  keeps `cd komorebi-for-mac` and --workspace;
- /bin/sh became bash with `set -euo pipefail`; the old script's omission of --locked is kept
  (pass it as an extra argument).

Verified: bash -n and shellcheck clean. Not run: the check itself needs nix and the toolchain build.
2026-11-05 15:03:26 -08:00