Commit Graph
3112 Commits
Author SHA1 Message Date
LGUG2Z 26963391a3 feat(analysis): investigate from what you marked
The brief starts from what the user marked as the bug, in their words, and ranks
the events most worth tracing first; findings an agent concludes are saved with
the evidence they cite, which must exist. The commands arrive: `state`, `diff`,
`events`, `window`, `trace`, `code`, `brief`, `overview`, `search`, `annotate`,
`annotations`, `guide` and `schema`, all with `--json`, and a search is bounded
by a budget.
2026-10-27 22:22:56 -07:00
LGUG2Z 079f1ac6d0 feat(analysis): explain one event, follow one window
One event end to end: what its handler logged, what other threads logged
meanwhile, and every change with who made it and how sure that is. The state,
the diff and the events are answered as plain values, an overview ranks what
stands out in a recording, and invariants flag states that are wrong: a window
in two containers, a window parked off screen on the workspace that is showing
(a rule that holds only where komorebi hides windows by moving them, so it is
skipped on Windows).
2026-10-27 22:22:56 -07:00
LGUG2Z 3a325470eb feat(analysis): trace a log line to its source
Every `tracing` statement in komorebi's source is indexed at build time, for
each flavor, so a line of its log can be traced to the statement that wrote it
with the code around it. A recording from a different komorebi than the one
indexed is said to be skewed, decided by the files that differ between the two
commits rather than by commit equality. The `Analysis` facade that every
question is asked of arrives with it, and one window's history through a
recording.
2026-10-27 22:22:56 -07:00
LGUG2Z 72419d89a2 feat(analysis): what komorebi believed, and what changed
A komorebi `State` is read into monitors, workspaces and windows through each
flavor's rules, and what changed between two states is said in terms a person
would use. `at`, `range`, `summary` and `locate` ask what the recording holds
around a video time, and the other way round, with the text and JSON the later
commands share.
2026-10-27 22:22:56 -07:00
LGUG2Z af6e332fed feat(analysis): read komorebi's log as handlers
komorebi's log says what happened but not which handler was running. The log is
parsed into lines with their span chain, and a handler's lines are gathered into
one block, from the line that opens it to the one that ends it, as each flavor's
log marks them: komorebi for Mac logs a header, komorebi for Windows has none
and a block is found from its span.
2026-10-27 22:22:56 -07:00
LGUG2Z e3a1f01fd7 feat(doctor): check what a recording leans on
`doctor` says what the machine can do for a recording: which komorebi runs and
how it logs, whether the screen can be captured and played back, the displays
and their scale, and the host clock. Probes measure one thing: the clock across
a sleep, a short capture, a decode, whether komorebi would tile a window of
ours.
2026-10-27 22:22:56 -07:00
LGUG2Z 3e30d81bc5 feat(av): decode the recorded video
Reading the video back: AVFoundation on macOS, the Media Foundation source
reader on Windows, a clear error elsewhere. A request for the frames between two
times is answered with the frame that was on screen at the start, even when the
decoder had to seek to an earlier key frame. `selftest` records a rendered
on-screen clock and compares the clock the video shows with the time the session
predicts.
2026-10-27 22:22:56 -07:00
LGUG2Z 5291a24fd4 feat(app): the recorder window
Run with no command, `komorebi-recorder` opens a small window with Record and
Stop. It is untitled and borderless because komorebi does not manage windows
without a title, so opening it does not move the layout under investigation, and
it keeps itself out of the video (by process name on macOS, with
`WDA_EXCLUDEFROMCAPTURE` on Windows). `komorebi-recorder-gui` is the same
program built for the GUI subsystem on Windows, so that a shortcut opens no
console; both are in the zips and the installer.
2026-10-27 22:22:56 -07:00
LGUG2Z 05d87908c5 feat(recorder): orchestrate a recording
`komorebi-recorder record` starts every source in the order that makes the
non-video sources a superset of the video, stops them in reverse, and
checkpoints the manifest as it goes, so that a recorder that is killed leaves a
session `reindex` can recover. `--no-video` records everything but the screen,
and Ctrl-C or `--duration` stops and finalizes a recording. The format of
`annotations.jsonl`, the append-only file that bug regions, notes and findings
are written to, is defined here too. The command table arrives with it, with
`displays` and `reindex`, and with the text-and-JSON conventions the later
commands share.
2026-10-27 22:22:56 -07:00
LGUG2Z 1006ec2570 feat(timeline): index a session
`timeline.jsonl` is a merged, time-sorted index that points into the raw files
by byte range, so the raw files are never rewritten and the index can be rebuilt
at any time. It places komorebi's log, events, the OS trace and the recorder's
own incidents on one timeline, and answers what was around a video time and
where in the video a log line or event is. `frames` extracts PNG frames from the
recorded video with ffmpeg, which is never used to capture.
2026-10-27 22:22:56 -07:00
LGUG2Z 383cc3c3db feat(power): ride out sleep, lock and display changes
Docking, sleep and lock are where komorebi bugs show up, so the recording
carries on through them. On Windows a hidden window hears suspend, resume, the
lid, the displays and session lock as Windows delivers them; on a Mac a sleep is
found because the host clock pauses while the wall clock does not, and the lock
is polled on both hosts. A tracker turns these into reactions: a display that is
gone has its video finalized at once, one that returns starts a new segment, and
every stream is started afresh after a wake instead of trusting the old one.
2026-10-27 22:22:56 -07:00
LGUG2Z fb11cb2db9 feat(capture): record the screen
Screen capture behind a `CaptureBackend`: ScreenCaptureKit and AVFoundation on
macOS (HEVC by default), Windows Graphics Capture and a Media Foundation writer
on Windows (H.264). Each display is written as fragmented mp4 in segments with
every frame's master-clock timestamp, and a manager decides, from what the
backend reports, when a segment ends and another begins. The segment logic is
shared by both backends and tested without a screen.
2026-10-27 22:22:56 -07:00
LGUG2Z 9d35869f88 feat(sources): the OS trace
What the OS says while komorebi acts: the unified log (`log stream`) on macOS,
one file per managed application, komorebi's process and the system; on Windows
the WinEvents komorebi hears, folded when repeated, and the Event Log's warnings
and its display, power and GPU providers. Both end up as `oslog/*.ndjson` on the
master clock, and a host with no OS trace says so instead of failing.
2026-10-27 22:22:56 -07:00
LGUG2Z 4724d831ba feat(session): the session directory
A session is a directory and its manifest, `session.json`: the host, the
komorebi flavor, the clock anchors, the log segments and the applications seen,
written atomically. komorebi's own log is recorded as the exact byte range
written while recording (`%TEMP%` on Windows, its data directory on a Mac),
together with the version of the komorebi that wrote it. A generated README in
each session says what every file is, quoting paths the way the host's shell
reads them.
2026-10-27 22:22:56 -07:00
LGUG2Z c748237741 feat(komorebi_link): record what komorebi says
The recorder subscribes to komorebi over its socket (a unix socket on macOS,
`uds_windows` on Windows) and writes every notification with the state it came
with, stamped on the master clock. Its accept loop only hands off to a writer
thread, since komorebi notifies subscribers while holding its locks. What
happens to the recording itself (a komorebi that exits, a stream that dies) is
written as incidents, and a lock file says whether a recorder is still running
in a session.
2026-10-27 22:22:56 -07:00
LGUG2Z 0de0f82840 feat(flavor): read komorebi for Mac and for Windows
Which komorebi produced a session is a separate axis from the host the recorder
ran on. `Flavor` names the two and `Rules` holds what each knows: what its
events look like on the wire, which of them move a window, and which are
komorebi making things up. komorebi for Mac and komorebi for Windows each
implement it, and a missing method is a compile error. The Windows rules were
written from komorebi's source and say so until a recording confirms them.

Events are classified through the rules, and the names of things in a session
(`event:12`, `log:7`) are parsed here too, with the envelope and exit codes
every command will answer in.
2026-10-27 22:22:56 -07:00
LGUG2Z d5eacecef8 feat(clock): the master clock
Every record in a session is stamped on one monotonic clock:
`mach_absolute_time` on macOS and `QueryPerformanceCounter` on Windows, behind a
`platform` facade with a third `unsupported` host that builds anywhere. Anchors
pair that clock with the wall clock, a map interpolates between them, and a jump
detector notices sleep and clock steps by comparing how far each moved. Video
timecodes are parsed and printed here too.

`Host` and `ClockKind` say what a session was recorded on.
2026-10-27 22:22:56 -07:00
LGUG2Z ab0b943ba0 build(wix): an installer for Windows
An MSI for Windows built with WiX and `cargo wix`, for x86_64 and aarch64,
attached to every release and, on tags, offered to winget. It is its own
product: its upgrade code and the GUID of its PATH component are new, since
reusing komorebi's would make the two installers upgrade and uninstall each
other.

WiX only runs on Windows, so `tests/packaging.rs` checks what a Mac can: every
binary the crate builds is in the installer, and the installer is not
komorebi's.
2026-10-27 22:22:56 -07:00
LGUG2Z 928ee8ebaa ci(github): build and attach artifacts for macOS and Windows
One workflow builds both platforms and publishes what they built. macOS builds
and checks through nix on the self-hosted runner; Windows builds natively on
`windows-latest` for x86_64 and aarch64, with fmt, clippy and the tests on
x86_64. A publish job packages the executables and checksums and writes the
release notes with kokai: a `v*` tag makes a release, a scheduled or manual run
on master replaces the rolling nightly, and any other push to master makes a
draft.

There is no nix on the Windows runner, so it checks out the komorebi sources at
the revisions `flake.lock` pins.
2026-10-27 22:22:56 -07:00
LGUG2Z 76bae0630e build(nix): build and check for macOS and Windows
A flake that builds the recorder for macOS and cross-compiles it for Windows
from a Mac (xwin for the SDK, LLVM for the toolchain), with a dev shell for
each, and `nix flake check` running clippy for both targets, rustfmt, taplo,
cargo-deny and the tests.

The sources of komorebi for Mac and komorebi for Windows are flake inputs,
pinned in `flake.lock`: the recorder indexes them so that a line of komorebi's
log can be traced to the statement that wrote it, and the dev shells and every
derivation export where they are.
2026-10-27 22:22:56 -07:00
LGUG2Z af3c080ace chore(repo): a workspace of one crate
A cargo workspace with one member, `komorebi-recorder`, and the files a project
needs around it: toolchain, rustfmt and cargo-deny configuration (both the macOS
and the Windows target are in the dependency graph), a justfile whose `check`
recipe is the one command CONTRIBUTING names, the license, and README and
CONTRIBUTING.

The crate is a skeleton that prints its version; the recorder arrives in the
commits after it.
2026-10-27 22:22:56 -07:00
LGUG2Z 3e59a2b210 fix(process_event): warn when a focus notification is not followed
A notification that an application came to the front is not followed
while another application is in front. That is right when komorebi has
since moved on to another, and it is also all there is to see when the
window server refused to bring the application to the front at all, in
which case focus moves in komorebi and nowhere else. At debug level it
was left out of the log by default, so the only trace of that refusal
was in the OS log. Make it a warning.
2026-10-27 19:56:30 -07:00
LGUG2Z 95ec707852 fix(window): ask the window server to bring an application to the front
Focusing a window activated its application with NSRunningApplication,
which from a background process reaches the window server as a request
stamped with the time komorebi started. Once the user has typed or
clicked since, the window server turns it away as expired ("Rejecting
expired request") and the application that was in front stays there:
focus moves in komorebi, the border, which only marks the window that
has the keyboard, stays unfocused, and the keys keep going to the
terminal that `komorebic focus` was run from.

Ask the window server directly first, with the request marked as the
user's, which is what clicking a window does. The two private symbols
it takes are looked up when first wanted and not linked, so that macOS
taking one away leaves komorebi starting and focusing as it did, with
one warning. A window server that refuses three times in a row is not
asked again, and a process without a serial number is left to the
usual way without counting against it.
2026-10-27 19:56:20 -07:00
LGUG2Z 2d06e68b48 fix(monitor): show a workspace's windows all at once when switching
Switching workspace hides the windows of the others and restores the
windows of the one that is wanted, one window at a time, each through
the accessibility API and each as slow as the app it belongs to. The
handler took 260 to 430 ms in a recording, and frames taken in the
middle of it show both workspaces on screen together: with Zed and Zen
gone, two WezTerm windows from the old workspace still up and Beeper
and Discord from the new one not there yet.

Workspace::update already batches its window moves with SLSDisableUpdate
and SLSReenableUpdate so that they appear together. Hiding and restoring
did not. BatchedUpdates holds the screen back until it is dropped, which
an early return does too, so an error cannot leave it frozen, and
load_focused_workspace keeps one for the hiding and the restoring. The
wallpaper, which can generate a theme, is put up after it is dropped,
which is why Workspace::restore is split into the windows and the
wallpaper. restore does what it did.

The screen does not change at all for as long as it is held, which is
now the length of the switch. How the private SkyLight calls behave
when it is held for that long, and whether it is long enough to notice,
was not tried on a screen.
2026-10-27 18:46:16 -07:00
LGUG2Z 407a011b5e fix(process_event): follow focus only while the app is still in front
komorebi brings an app to the front with activateWithOptions and then
hears about it from NSWorkspace and the accessibility API some time
later, 0.8 to 1.7 s in a recording, by which time it has often brought
another app to the front. The FocusChange handler took every such
notification at its word, which had two effects:

- focus moved back to the app that had had it, so Left, Left landed on
  the window in between rather than the one two along
- the app of a window on a workspace that is not showing made the
  workspace reconciliator switch to that workspace, which undid a
  workspace change that had been asked for a moment earlier

The handler now asks which app is in front and does not follow a
notification about any other. The last notification that is followed
is always about the app that really is in front, so the state ends up
where the system is. Notifications about an app that is not in front
still go through the rest of the handler, and nothing is ignored when
the accessibility API will not say what is in front.

Found in a recording of the installed build at db1c18b. That the
notifications are late and that the OS front process had moved on was
read off the OS trace; the change itself is tested only for the
decision, and was not tried on a screen.
2026-10-27 18:44:46 -07:00
LGUG2Z 88aa78b874 feat(wm): a command socket and the first messages
Until now the daemon tiled what KWin reported and nothing else could reach it.
komorebi takes its orders on a socket, as it does on Windows and on macOS: it
handles no key itself, and whatever binds keys runs a command that writes a
message.

The daemon binds komorebi.sock in $XDG_RUNTIME_DIR/komorebi (DATA_DIR), reads
one JSON SocketMessage per line on a thread per connection, and handles each
message with the window manager locked, as the thread that handles events does.
The first messages are the ones the first komorebic needs: State (the window
manager as JSON, from state.rs), MonitorInformation, Query with a StateQuery,
Retile and Stop. A question is answered on the same connection, and the answer
ends when the daemon closes it. Stop unloads the bridge from KWin, removes the
socket and exits; so does a stop signal.

The socket is bound once the daemon is connected to KWin, so a komorebi that
cannot connect, such as a second one in the same session, which the bus refuses,
leaves the socket of the one that runs alone. With --fake-backend the daemon
answers on its socket with no compositor at all, which is how the tests run it.

komorebi-client is the other end: send_message, send_batch and send_query, and
the types the messages are made of. Its doctests serve the socket themselves,
tests/daemon.rs runs it against a window manager over the fake desktop, and
komorebi/tests/socket.rs runs the daemon binary from its start to a Stop.
2026-10-27 15:17:30 -07:00
LGUG2Z 4386003e30 feat(kwin): survive KWin restarting
KWin can go away under a running daemon while the session bus stays: it crashed,
or kwin_wayland --replace took its place. Its windows go with it, and so does
the bridge, which would have reported them closing; in the spikes the old
windows vanished without a single removed event. What the daemon does see is the
bus, so the thread that serves the connection watches NameOwnerChanged for
org.kde.KWin. When the name loses its owner, Table::compositor_lost marks every
window closed and returns a Destroy for each, so the window manager takes them
out of its layout, and their ids are not given out again. When the name has an
owner again, the daemon loads the bridge into the new KWin, trying for up to 15
seconds while KWin is not ready for it, and the bridge reports the new desktop
in a snapshot.

zbus does not end a held call when its caller leaves the bus, so the Poll of the
old bridge is still waiting when the new bridge calls, and it was woken first:
it took the commands for the new KWin and answered them to nobody.
vm-kwin-restart lost the tile of a window opened in the third KWin that way in
one run of three, and a recording of the bus showed the batch going to the old
bridge. A Poll held since before KWin last left the bus is answered with nothing
and passes its wake-up on to the next call, which a unit test holds.

The VM suite vm-kwin-restart (from the spike's spike7-resync) restarts the
headless KWin twice under a running daemon, through Kde.restart_kwin in the VM
library, and checks that the daemon sees KWin go, takes the old windows out of
its layout, loads the bridge into the new KWin, and tiles the windows that open
there.
2026-10-27 14:50:53 -07:00
LGUG2Z b463191d00 feat(kwin): move and focus windows through a held call
With the commands of the Backend trait carried out, the daemon tiles a real
KWin. A command looks up the UUID KWin knows the window by, is queued as JSON
for the bridge, and returns; the held Poll call is answered with the queue, one
millisecond after the first command, so that a retile reaches KWin as one batch.
The bridge sets the frame, activates, raises, minimizes, restores or closes the
window, and reports what it could not do. set_rect records the frame it asked
for in the table, so the window manager sees it at once, and the geometry event
that follows says what the client made of it.

A KWin script cannot move the pointer, so the pointer follows the focus through
KWin's own "Move Mouse to Focus" action, invoked over kglobalaccel once KWin
reports the window active.

The commands are typed in bridge.js, and the declarations of KWin's API let the
bridge set a window's frame, its minimized state and the active window, raise
and close it, and nothing else. The session the tests of both sides share grows
a second batch: the backend's tests check that set_rect, focus, raise, minimize,
unminimize and close send it, and the bridge's tests answer the bridge with it
and check what KWin is asked to do, down to the command for a window that has
closed, which comes back as failed. The bridge's tests also cover findWindow's
fallback to KWin's list, a frame set as a plain object, and a command KWin
throws on.

Three VM suites check it against a real KWin. vm-core-e2e (from the spike's
m2-e2e, the sections that need no komorebic) compares what the daemon asked for,
read from its debug log, with what KWin has, read with kdotool: three windows
inside the screen, not overlapping, sharing it, the same focused window on both
sides, and the same again after a minimize, a restore and a close.
vm-client-geometry (slow) has eight real clients answer the frames komorebi asks
for: Qt programs and xterm take them exactly, foot sizes itself to whole cells,
GTK 4 programs and Firefox keep to their minimum sizes. vm-latency (slow) times
retiles from a recording of the session bus: on HVF, from the daemon's answer to
the last frame KWin reports, p50 17.3 ms, p95 27.7 ms. vm-kwin-events no longer
checks that nothing moves. The VM library gives session commands the test user's
home and data directories rather than root's, which a GTK client was refused.

The bridge's second request for a position after a resize, which matters for
windows off the screen, comes with the scrolling layout.
2026-10-27 14:48:56 -07:00
LGUG2Z 15ec3c1274 feat(kwin): read the desktop through a script in KWin
KWin has no protocol that lets another process read or set the geometry of a
window, but its scripting API has both, and a signal for every change the window
manager follows. So the KWin backend is in two parts: bridge.js, a script the
daemon loads into KWin, which reports what KWin sees and holds no window manager
logic, and a D-Bus service in the daemon, org.komorebi.Bridge, which the script
calls with every event as a JSON string.

Every decision about what an event means is made by the table in kwin::state,
which is pure and is unit-tested with the JSON the script sends: which windows
may be managed, the ids komorebi gives KWin's windows, and the Show, Destroy,
FocusChange, Minimize and Restore events of the window manager. Events reach the
window manager in the order KWin raised them: the Event interface handles its
calls inline (zbus reordered them otherwise), and one channel and one thread,
window_manager_event_listener and listen_for_events, carry them on.

Commands go to the script as the answer to a Poll call that the script always
has open and the daemon holds until it has something to send: in the spikes this
was as fast as any other channel, and it makes one call every 10 seconds when
nothing happens. Here the only command is the cursor query. Every command of the
Backend trait is refused with "the KWin backend only reads the desktop", so the
daemon follows KWin and moves nothing.

The bridge is JavaScript that KWin runs as it is, and it gets types and tests
without a JavaScript build chain. tsc checks it as strict TypeScript through
JSDoc types of every message, against kwin-api.d.ts, a declaration of the part
of KWin's scripting API it uses, in which every property is read-only and
callDBus takes one string. bridge.test.js runs it under node --test against a
fake KWin in a node:vm context. The messages of a session are JSON fixtures that
both sides' tests read: the bridge's tests check that it sends those events, and
the table's and the backend's tests read the same events and commands, so a
message cannot change on one side alone. just check-js and the flake's
komorebi-bridge-js check run both, with nodejs and typescript from nixpkgs;
there is no package.json.

The daemon now connects to KWin by default, and --fake-backend is hidden. The VM
suite vm-kwin-events starts it against a headless KWin and checks, from its
debug log, that the script loads and reports what was open, that KWin's signals
arrive as events and in order, and that stopping the daemon unloads the script.
docs/dev/PLATFORM.md starts with what komorebi needs from Plasma.

zbus 5's zvariant, zbus_names and zvariant_derive are flagged unmaintained,
since their code moved into zbus 6; deny.toml ignores the three advisories.
2026-10-27 14:46:35 -07:00
LGUG2Z 02231d232c feat(wm): tile what the backend reports
With the model in place, the window manager can do its job: load the desktop
from the backend, tile it, and keep it tiled as the compositor reports what
happens to windows. The events are the Windows implementation's, each about one
window and carrying it: a window is shown, destroyed, given the focus, minimized
or restored. A new window gets a container of its own after the focused one, a
closed one leaves whichever workspace has it, a window the user minimizes is out
of the layout until it is restored, and every event ends with the workspace in
front tiled again.

At startup every monitor is loaded, and every open window that is normal, alive
and not minimized goes on the monitor its middle is on. An index from each
managed window to its monitor and workspace is rebuilt around every event, so
that the first event komorebi sees can be the close of a window it picked up at
startup.

Whether a window is managed is, for now, only whether the compositor calls it a
normal window and it is alive; the rules that ignore, manage or float
applications come later. When a window closes, komorebi leaves the choice of the
next focus to KWin unless KWin focuses nothing, so the two do not fight.

The daemon runs this against a backend chosen on the command line.
--fake-backend, an in-memory desktop with one monitor, is the only one, and
without it komorebi exits with a usage error instead of pretending to manage a
desktop it cannot reach.
2026-10-27 14:07:28 -07:00
LGUG2Z c0345eb0e9 feat(wm): windows, containers, workspaces and monitors
The window manager tiles a tree of four levels: monitors, each with a ring of
workspaces, each with a ring of containers, each with a ring of windows. It is
the model komorebi has on Windows and macOS, and the first thing the daemon
keeps that the backend does not give it.

A window is a Copy handle that carries the compositor's id and asks the backend
for everything else, so moving one is a call on the handle and needs no context
passed to it. A workspace tiles itself: the layout gives each container a tile
of the work area its monitor hands it, less the offset and the padding, and
every window of the container is asked to move there. A locked container keeps
its index because the workspace inserts, removes and swaps its containers
through LockableSequence.

This is tiling only. Stacks, monocle, maximize, the floating layer, resize
adjustments, placement rules and the link between workspaces and KWin's desktops
come with the commits that use them. impl_ring_elements!, which gives every
holder of a ring the same accessors, lands here with its first users.
2026-10-27 14:07:28 -07:00
LGUG2Z ed6a8e96c3 feat(backend): reach the compositor through one trait
The window manager decides where every window goes, and asks a compositor to put
it there. If it asked KWin directly, every test of its logic would have to boot
a virtual machine, so everything it needs from the desktop goes through one
trait, `Backend`: queries for windows, monitors, the focus and the pointer, and
commands to move, focus, raise, minimize and close a window and to put the
pointer somewhere. A real backend answers from a table that compositor events
keep up to date, so a query never waits for the compositor; a command returns
once it has been accepted, not once the client has acted.

`FakeBackend` is the other implementation: an in-memory desktop that does what
it is told, at once and exactly, and records every command so that a test can
assert on what the window manager asked for. A test can also do what a user does
without the window manager asking: move a window, close it, change the focus,
turn a window into a dialog. It is strict where KWin is (a command about a
window that is gone is an error) and clamps where a GTK4 client does (a minimum
size). `with_backend` overrides the process-wide backend for the current thread
only and puts the previous one back on drop, also on a panic, which is what
keeps one test's desktop out of the next.

The module is the first to have `#![deny(missing_docs)]`. The contract (what
must be implemented, that a backend is `Send + Sync`) is proved by two
`compile_fail` examples with their error codes, and the rules nothing checks are
listed as such.

docs/dev/ARCHITECTURE.md describes the trait, its roles and the layer that
enforces each rule, and docs/dev/DESIGN.md has the first decisions with their
reasons. Both grow with the code.
2026-10-27 14:07:28 -07:00
LGUG2Z 507c51f0c0 feat(core): the vocabulary the window manager is written in
Configuration, commands and the layout code all speak in the same small types:
how a new window is added to a workspace, what happens to a window that crosses
a monitor boundary, which kind of window a border colour is for, how an
application is matched by what it calls itself. They are defined once, in
`core`, with the layout types re-exported next to them so that the rest of the
crate imports from one place.

The layouts themselves are `komorebi-layouts` from komorebi, a git dependency as
in komorebi for Mac, at f08aa55 (the tip of master when this was written). That
revision has the fix for resizing a tile by dragging its edge
(LGUG2Z/komorebi#1765) and the placement helpers this port uses, so nothing is
vendored. The crate pulls in serde_yaml, which has an advisory
(RUSTSEC-2024-0449, unmaintained unsafe-libyaml) for reading the Windows-only
custom layouts; nothing here calls it, and deny.toml says so where it ignores
the advisory.

The module also has what the rest is built from. `Ring` is a list with one
focused element, which monitors, workspaces and containers each keep their
children in; it has the unit tests and the example upstream's version never had.
`lockable_sequence` keeps locked containers at their positions when others are
inserted or removed around them. `core::pathext` resolves environment variables
in configured paths, and `core::config_generation` has the rules that match an
application, with tests for the two shapes a rule takes in JSON (an object, and
a list that must all match).

Types that belong to a feature come with the feature: the socket messages, the
placement rules and the animation styles are not here. The `impl_ring_elements`
macro waits for the first type that uses it.

Every module has a `//!` summary, and the README says what the library has.
2026-10-27 14:06:52 -07:00
LGUG2Z 0725705298 ci(github): run the VM tests on KVM
`discover` asks the flake for the suites of each tier
(`legacyPackages.x86_64-linux.vmTiers`) and hands them to two matrices, so a new
directory under `nix/tests/vm/suites` is run without an edit to the workflow.
`vm-fast` runs the fast tier on every pull request, one machine per suite, as a
sandboxed `nix build` of the check. `vm-slow` runs on master, every week, and on
a pull request labeled `ci:vm-slow`; it builds the driver and runs it by hand,
outside the sandbox, so that the screenshots and journals of a failed run are
uploaded with `if: always()`.

A composite action installs nix with the store cached and, for the VM jobs,
frees disk space (a Plasma guest is a closure of about 10 GB), writes the udev
rule that makes /dev/kvm writable for the runner's user, checks it with `test
-w`, and adds `kvm` to nix's system features. KVM on hosted runners is
documented for public repositories only. Whether this private repository has it
is not known: the first run of these jobs says, and if it does not, they need a
different runner.

`lint` no longer runs `nix flake check`: on Linux that now boots every VM suite,
which a runner with no KVM cannot do. It builds the checks that need no virtual
machine, and `vm-lib`, the library's own tests.

CONTRIBUTING.md and docs/dev/vm-tests.md say what runs where.
2026-10-27 14:06:52 -07:00
LGUG2Z fec9c2773a build(nix): a Plasma session node for tests
A virtual KWin has no output to draw on, so every test about pixels, and later
about the pointer, needs a real session. The `session` node is the headless node
plus a login: plasma-login-manager logs the test user in by itself, the way
nixpkgs' own `plasma6` test does, and Plasma draws on the machine's display. The
choice of login manager is made in `nodes/session.nix` and nowhere else, and the
file says how to switch to sddm.

The node adds no display device. The test driver gives every aarch64 guest one
virtio-gpu and takes screenshots of it; a second device is a second KWin output
that screenshots never show, which is what a first attempt did (a blank 1280x800
console).

`Kde.session` attaches to the session once the desktop is up: the shell is
running, the user manager knows the Wayland display, and the splash screen has
gone. The display is read from the user manager because plasma-login-manager's
greeter has its own KWin and takes `wayland-0`, and the user's session gets
`wayland-1`. The splash condition is there because KSplash has over a thousand
colors on it, so a "not blank" check passed on the splash screen. NixOS wraps
programs, which is why processes are found by their command lines: `pgrep -x
plasmashell` never matches `.plasmashell-wrapped`, and an exact match for the
splash would have passed because nothing matched. `Kde.shot` returns a
screenshot as a Pillow image.

`vm-render-smoke` is the first slow suite: it starts a session, opens a
terminal, and checks the middle of the window is dark and that the desktop
behind it has thousands of colors. On aarch64 under HVF five runs gave the same
screenshot, with the desktop up after 34 seconds. docs/dev/vm-tests.md describes
the node and the two traps.
2026-10-27 14:06:52 -07:00
LGUG2Z 3c51b9b4bf build(nix): a NixOS test framework for headless KWin
The unit tests run against a fake desktop and cannot say whether KWin does what
the daemon asks. This adds the other half: NixOS machines with Plasma in them, a
real KWin, and a Python library to drive it.

Every directory under `nix/tests/vm/suites` is a test. The generator lists the
directory, so a new suite appears as `checks.<system>.vm-NAME` on Linux and as
`legacyPackages.<system>.vm.NAME` everywhere, with no edit to the flake. A suite
names its tier and its node and has a `test.py`;
`legacyPackages.<system>.vmTiers` lists the names of each tier as JSON for the
CI matrix, `vmGuests` the guests to build on a Linux builder, and `vmTcg` the
same suites for a machine with no KVM. `scale` multiplies every wait: 1 for KVM,
1.5 for HVF, 8 for TCG.

The headless node runs `kwin_wayland --virtual` as user units of a lingering
user, one pair of units per session (`session-bus@NAME`, `kwin-virtual@NAME`),
so a test can run several sessions with their own bus and socket. A virtual KWin
has no output to draw on, so anything that needs pixels or a pointer needs the
session node.

The library, `komorebi_vm`, has `Checks` (counted checks that fail once, at the
end) and `Kde` (start a session, run clients and tools inside it, read windows
through kdotool, poll with `wait_for`). It depends on a small `Machine` protocol
rather than on the test driver. The `vm-lib` check runs its unit tests against a
fake machine, with ruff and ty. The driver type checks each `test.py` with ty,
which is how a protocol that did not match `QemuMachine.execute` was caught.

`vm-kwin` starts a KWin with two outputs, spawns a foot window, reads it back,
starts a second session and checks that it cannot see the first.

On a Mac the guest is built on a Linux builder and the driver run directly,
because the macOS nix sandbox cannot give QEMU the hypervisor: `scripts/vm-mac`,
`just vm NAME`. docs/dev/vm-tests.md covers this, adding a test, and the
builder.
2026-10-27 14:06:19 -07:00
LGUG2Z 7129778086 chore(deps): cargo update 2026-10-27 12:41:58 -07:00
LGUG2Z db1c18b5b6 fix(wm): make drag-to-resize follow the dragged edge
Dragging a tile's edge was unreliable: long drags were dropped, the
divider next to a different window drifted by a few points, and in
recordings made with komorebi-recorder a drag to the left shrank the tile
instead of growing it. This fixes the causes that were found there.

Resize bounds: bump komorebi-layouts and komorebi-themes to
LGUG2Z/komorebi@f08aa55, where DefaultLayout::resize only accumulates and
no longer refuses any adjustment larger than half of the container's own
size. resize_window now grants the largest amount that keeps every tile
at least a tenth of the work area (or as large as it already is), found
by bisection, instead of all or nothing. Keyboard resizing goes through
the same path. RUSTSEC-2024-0449 is ignored in deny.toml, as upstream
does in the same bump.

The dragged container: ResizeStart records the rect of the dragged window
once, since AXWindowResized fires again all through a drag, and ResizeEnd
hands it to the new WindowManager::resize_by_drag along with the rect the
window ended in. That resizes the container of the dragged window instead
of the focused one, for each edge that moved, instead of guessing the
edges from the difference to latest_layout (which made apps that snap to
a grid of cells resize edges that nobody touched).

Where the drag began: AXWindowResized is first reported after the edge
has moved, and handlers run one at a time, so the rect recorded as the
start can already be 22 points into the drag, or be the rect the drag
ended in. An edge that ended up more than 32 points from its tile is
measured from its tile edge; every other edge from the recorded start.

The reaper: it re-tiled the focused workspace on every mouse-up and
key-up to find windows that had gone away. That ran as soon as the button
went up, ahead of the ResizeEnd queued behind slower handlers, so the
window was back on its tile when ResizeEnd read where it had been dropped
and the drag was measured backwards. It now only looks for windows that
no longer exist and reaps them, without moving any window.

The tests reproduce each of these, including the numbers from the
recordings: a first step of 22 points, a drag already over when it was
first seen, and a mouse-up that must leave the layout alone.
2026-10-27 12:27:40 -07:00
LGUG2Z f08aa55511 chore(deps): cargo update 2026-10-27 09:59:57 -07:00
LGUG2Z a3fac99a0f fix(wm): make resizing a tile by dragging its edge reliable
Measure mouse resizes from the rect the window had when the drag
started, work in edges instead of guessing from rect fields, resize the
container of the dragged window, and bound resizes by the resulting tile
sizes (granting as much as fits) rather than by the size of the
container being resized.
2026-10-27 09:59:57 -07:00
LGUG2Z 3a20a60823 ci(github): check with nix on every push
`ci.yaml` runs two jobs on GitHub-hosted runners, gated on the repository name
so that forks do not run them. `cargo-deny` checks licenses, advisories and
sources. `lint` runs `nix flake check`, which builds every check of the flake,
and the repository's own macro rules from the justfile. The triggers are the
ones komorebi for Mac uses: pull requests, pushes to master, feature and hotfix
branches, version tags, a weekly schedule and a manual run. The Nix store is
cached with cache-nix-action, which needs no account.

komorebi follows the tip of nixpkgs-unstable, so `flake.lock` moves, and KWin
with it. `update-flake-lock.yaml` opens a pull request each week with the title
`chore(deps): flake.lock: Update`; the same jobs run on it, which is what says
whether the new KWin still works.

Dependabot keeps the actions and the crates up to date, and the pull request
template carries over from komorebi for Mac. CONTRIBUTING.md describes what CI
runs.
2026-10-27 09:18:55 -07:00
LGUG2Z 9524b777b3 build(nix): build and check on Linux and macOS
The flake builds the workspace with crane and checks it the way `just check`
does, so that CI and a laptop run the same things: `komorebi-workspace-fmt`
(nightly rustfmt, since rustfmt.toml uses unstable options), `-clippy` with
warnings denied, `-doc` with rustdoc warnings denied, `-toml-fmt`, `-deny` and
`-nextest`. Treefmt and a pre-commit hook format Rust, Nix, TOML and the
justfile. `nix develop` gives a toolchain with the nightly rustfmt, cargo-deny,
nextest and udeps.

Linux is where komorebi runs, so only Linux gets packages and the overlay. An
Apple silicon Mac gets the dev shell, the formatter and the checks; the tests
there run against the fake desktop that arrives with the backend trait.
x86_64-darwin is left out because nixpkgs 26.11 dropped it, and the flake
follows the tip of nixpkgs-unstable.

The commit hash is a constant (`nix-check`) for the dependencies and for every
check, and the real one only goes into the final build. The version crate reads
it with `env!`, so putting it in the shared arguments would rebuild the
dependencies and rerun every check for each commit.

The README and CONTRIBUTING.md describe `nix develop` and `nix flake check`.
2026-10-27 09:17:51 -07:00
LGUG2Z 426409fcfc chore(repo): a workspace of two crates
komorebi for KDE is built up as a Cargo workspace with one crate per concern,
the way komorebi and komorebi for Mac are. The first two crates are the
`komorebi` daemon, which does nothing yet but report its version, and `version`,
which owns the string every binary of the workspace reports.

`version` reads the commit from git when HEAD is on a branch, and from
COMMIT_HASH otherwise. A jj workspace leaves HEAD detached, so
`.cargo/config.toml` defaults the variable to `unknown` (nix will set the real
commit), and a plain `cargo build` in a jj checkout compiles.

The tooling files come from komorebi for Mac: the licence, deny.toml (trimmed to
the licences in use), rustfmt.toml and the toolchain file. `just check` runs the
formatting check, clippy and rustdoc with warnings denied, and the tests.
rustfmt.toml uses an unstable option, so formatting needs a nightly rustfmt. The
`rg` calls in `just lint` name a path because rg reads stdin when it is given
none and stdin is not a terminal.

The README and CONTRIBUTING.md say how to run, check and commit.
2026-10-27 09:11:36 -07:00
LGUG2Z e0709f02bf chore(deps): cargo update 2026-08-22 14:26:23 -07:00
Csaba 83c4e11d99 feat(wm): add initial_window_placement_rules for workspace-level
Adds a new initial_window_placement_rules workspace configuration option
that allows users to control where new tiled windows are inserted in the
container list. Supports placement by named strategy (Primary,
Secondary, BeforeFocused, AfterFocused, Last), fixed container index, or
per-application matching rules with OR/AND logic.
2026-08-22 13:52:38 -07:00
Ransomwave 4ca2ff84dc feat(bar): add default interface options to display friendly name or local IP
Adds a new configuration to the Network widget from komorebi-bar, which
allows you to toggle between viewing your Default Interface's friendly
name, IPv4 or IPv6.

Motivation: I find it very useful to check your local IP at a glance,
and missed the feature heavily from other wms in Linux.
2026-08-22 13:52:01 -07:00
Dylan Anderson 3f3fac8b65 chore(stackbar): tighten deadlock fix comment 2026-08-02 20:24:18 -07:00
Dylan Anderson 5a534eb2ac fix(stackbar): drop containers lock before repositioning stackbar
Stackbar::update held STACKBARS_CONTAINERS across the synchronous
cross-thread SetWindowPos in position_window, while the stackbar wndproc
acquires the same lock on WM_LBUTTONDOWN. A tab click racing an update
storm leaves the wndproc blocked on the lock and the updater blocked in
SetWindowPos waiting on the wndproc's message pump, deadlocking the
whole process. Scope the guard to the insert so the lock is released
before SetWindowPos.

Fixes #1734
2026-08-02 20:24:18 -07:00
dependabot[bot] 1b263b9496 chore(deps): bump shadow-rs from 1.7.1 to 2.0.0
Bumps [shadow-rs](https://github.com/baoyachi/shadow-rs) from 1.7.1 to 2.0.0.
- [Release notes](https://github.com/baoyachi/shadow-rs/releases)
- [Commits](https://github.com/baoyachi/shadow-rs/compare/v1.7.1...v2.0.0)

---
updated-dependencies:
- dependency-name: shadow-rs
  dependency-version: 2.0.0
  dependency-type: direct:production
  update-type: version-update:semver-major
...

Signed-off-by: dependabot[bot] <support@github.com>
2026-08-02 16:22:35 -07:00
dependabot[bot] e4e1b6da18 chore(deps): bump sysinfo from 0.38.4 to 0.39.6
Bumps [sysinfo](https://github.com/GuillaumeGomez/sysinfo) from 0.38.4 to 0.39.6.
- [Changelog](https://github.com/GuillaumeGomez/sysinfo/blob/main/CHANGELOG.md)
- [Commits](https://github.com/GuillaumeGomez/sysinfo/compare/v0.38.4...v0.39.6)

---
updated-dependencies:
- dependency-name: sysinfo
  dependency-version: 0.39.5
  dependency-type: direct:production
  update-type: version-update:semver-minor
...

Signed-off-by: dependabot[bot] <support@github.com>
2026-08-02 16:22:20 -07:00