Commit Graph
84 Commits
Author SHA1 Message Date
LGUG2Z bdd0a5593c feat(probe): a prober of komorebi for KDE, and findings that name KWin 2026-10-28 22:50:41 -07:00
LGUG2Z cbf7441009 feat(linux): ask KWin about a window, to probe it as Windows is 2026-10-28 22:50:41 -07:00
LGUG2Z 748e788b45 feat(analysis): ghost tiles for komorebi for KDE 2026-10-28 22:50:41 -07:00
LGUG2Z 202d46f733 fix(linux): stamp screencast frames on the system clock, as the master clock reads, and not on PipeWire's 2026-10-28 22:50:41 -07:00
LGUG2Z ffac28eb7e docs(platform): own-window exclusion and ghost tiles on KDE 2026-10-28 22:50:41 -07:00
LGUG2Z 135324be89 feat(asc): a Kde platform, for which no rule is written yet 2026-10-28 22:50:41 -07:00
LGUG2Z 22f73ec27b feat(linux): leave the recorder's own window out of the screencast with a KWin window rule 2026-10-28 22:50:41 -07:00
LGUG2Z 092b4db8ad feat(linux): follow the journal as the OS trace 2026-10-28 22:50:41 -07:00
LGUG2Z 65787b5656 ci(linux): build and check the Linux host 2026-10-28 22:50:41 -07:00
LGUG2Z 3c245da782 docs(platform): Linux (KDE Plasma) in the platform guide, and the checks still to make on a real session 2026-10-28 22:50:41 -07:00
LGUG2Z af80aa4817 build(deny): check the Linux target too
The GStreamer bindings read the target with target-lexicon (Apache-2.0 with the LLVM exception), and
zbus's zvariant family, which eframe's accessibility layer used on Linux already, is flagged as
unmaintained; each is listed with its reason.
2026-10-28 22:50:40 -07:00
LGUG2Z f191fa9806 feat(linux): hear sleep, wake and the lock from D-Bus, and read whether the session is locked
logind's PrepareForSleep on the system bus, and the screen saver's ActiveChanged on the session
bus, which komorebi for KDE listens to as well; GetActive says whether the screen is locked.
2026-10-28 22:50:40 -07:00
LGUG2Z caab37e4aa feat(linux): list the windows komorebi for KDE manages, for the window track
A Wayland client cannot list the windows of other programs, so the list is komorebi's own state:
each window with its rect and program, shown when its workspace is showing and it is in front of
its stack. --window-track is allowed on Linux.
2026-10-28 22:50:40 -07:00
LGUG2Z 4216d7fd6f feat(doctor): say what KWin needs to offer the screencast, on Linux
KWin offers zkde_screencast_unstable_v1 only to a program whose desktop file lists it. The note
has the file to write, with the path of this executable in it.
2026-10-28 22:50:40 -07:00
LGUG2Z a061757598 feat(linux): capture the screen with KDE's screencast, read by GStreamer
The displays are the compositor's outputs, with the id komorebi for KDE gives a monitor with no
serial number. A screencast of one is a PipeWire node that pipewiresrc reads, stamped on the
master clock, into a segment written by the capture writer. KWin offers the screencast only to
a program whose desktop file asks for it, and says so when it does not.
2026-10-28 22:50:40 -07:00
LGUG2Z 97aa82751c feat(capture): write a Linux segment with GStreamer, from any source of frames
DisplayCapture::start_with takes a function that connects a source to the frames' sink, which
also hears why a source died. Frames are placed in the file's time, logged and measured as on
Windows, a still display has its last frame repeated, and the file is fragmented H.264 written
by x264enc and mp4mux. The tests are a source of their own, and read the video back with the
decoder. The default codec on Linux is H.264.
2026-10-28 22:50:40 -07:00
LGUG2Z 48330b5017 build(nix): the libraries that Wayland, the window and the GPU are reached through 2026-10-28 22:50:40 -07:00
LGUG2Z 815d3c0693 feat(linux): the compositor's outputs and screencasts, over Wayland
One connection and a thread that reads its events keep the list of outputs, hotplug included,
so asking for it is cheap. A screencast of an output is KDE's zkde_screencast_unstable_v1,
which gives a PipeWire node and asks the user nothing.
2026-10-28 22:50:40 -07:00
LGUG2Z 47e458e793 feat(av): decode the recorded video on Linux with GStreamer
A pipeline per decode, filesrc ! decodebin ! videoconvert ! videoscale ! appsink, gives BGRA
frames at the size asked for. The time of a frame is its stream time, because an MP4's edit
list puts the media time of the first frame after zero. The playback and viewer tests that
need decoded video pass on Linux.
2026-10-28 22:50:40 -07:00
LGUG2Z bbd374ae24 feat(flavor): komorebi for KDE, with rules written from its source
Flavor::Kde is the flavor of a Linux host. Its rules are checked against a log and events
of komorebi for KDE's in-memory desktop, but not against a real desktop, so an analysis
of a KDE session says so. There are no ghost tiles for it yet.
2026-10-28 22:50:40 -07:00
LGUG2Z 1d80eb0272 build(gstreamer): GStreamer on Linux, to decode and encode the recorded video 2026-10-28 22:50:40 -07:00
LGUG2Z 7455c4df5e feat(blocks): the handler of komorebi for KDE's events is the span handle_event
Lines logged inside it belong to the event's block, as those inside process_event do.
2026-10-28 22:50:40 -07:00
LGUG2Z 098433155f feat(ignore): ask komorebi for KDE to ignore the recorder's window by its class
The window's Wayland application id is komorebi-recorder; komorebic ignore-rule class
registers it before the window exists, as the exe rule does on Windows.
2026-10-28 22:50:40 -07:00
LGUG2Z 121b4e9f48 feat(link): komorebi for KDE's sockets are in XDG_RUNTIME_DIR
socket_dir is the data directory everywhere but on Linux, where komorebi for KDE
keeps its sockets in $XDG_RUNTIME_DIR/komorebi.
2026-10-28 22:50:40 -07:00
LGUG2Z 5d08867da6 build(index): index the source of komorebi for KDE as well 2026-10-28 22:50:40 -07:00
LGUG2Z b762a5ca4d feat(platform): a Linux host with its own clock, process and shell
The rest of the host (apps, capture, power, session, trace) is still the
unsupported host's, and is replaced one module at a time.
2026-10-28 20:15:44 -07:00
LGUG2Z b39b17dd6e feat(platform): a Linux clock kind and Host::is_linux 2026-10-28 20:00:20 -07:00
LGUG2Z 17d44cbcba build(deps): libc for every unix host, not only macOS 2026-10-28 20:00:13 -07:00
LGUG2Z 0dd3997a4d fix(nix): use stdenv.hostPlatform.isDarwin, which replaces the deprecated stdenv.isDarwin 2026-10-28 20:00:13 -07:00
LGUG2Z 18d211eb22 build(nix): support x86_64-linux
Add x86_64-linux to the flake's systems, and apply the Darwin-only cctools
dependency and libiconv postFixup only when building for Darwin.
2026-10-28 19:42:27 -07:00
LGUG2Z 8e454e1e03 feat(gui): one window for recording and reviewing
The recorder is now the pinned first tab (Record, not closable, with a REC
marker while recording) of the viewer window; sessions follow as tabs. There
is one process and one window: komorebi-recorder, gui and view all claim the
same socket, and a second launch forwards (gui shows the Record tab, view
opens tabs) and exits. The request protocol gains an optional "tab" field;
old requests still parse. gui takes the record options (they only seed the
window that is started) and --new-window.

The window starts compact (420x380, always on top, Record tab only) when
launched plainly and full size for view; opening any session expands it,
and Compact / Expand is remembered in the prefs. RecorderApp::poll runs on
every frame whichever tab is showing, so recordings continue and finalize
while another tab is looked at. Cmd/Ctrl+0 shows the Record tab; Cmd/Ctrl+W
on it does nothing; closing the last session tab returns to Record.

KOMOREBI_RECORDER_PREFS_DIR and KOMOREBI_RECORDER_NO_IGNORE_RULE let tests
and end-to-end runs avoid the real prefs and the real komorebi.

The macOS/unix cfg branches (hidden title bar spacing) mirror the existing
tested patterns and could not be compiled on the Windows machine this was
written on.
2026-10-28 17:41:27 -07:00
LGUG2Z 72d600c8f6 feat(viewer): open sessions as tabs of one window
The viewer is now one window with a tab per session. Opening a session
(Open..., recents, the recorder window's buttons, `view SESSION...`) follows
one rule: focus the tab that has it, else load into the current start-screen
or failed tab, else add a tab. Only the tab in view plays; closing a tab
cancels its scan and stops its playback. Keys: Cmd/Ctrl T, W, 1-9,
Ctrl+Tab (and Cmd+Shift+[ ] on a Mac).

`view` and the recorder window hand sessions to a running viewer over a
local socket (komorebi-recorder-viewer.sock in the data dir, one JSON line
each way) and only start a process when none answers; `view --new-window`
opts out. The socket uses komorebi_link's cfg pattern (std unix sockets, or
uds_windows on Windows). The unix/macOS branches could not be compiled
here, only the Windows one.
2026-10-28 16:58:55 -07:00
LGUG2Z 19886f96fe feat(gui): name the windows komorebi-recorder, once komorebi is told to ignore them
The recorder and viewer windows were untitled so komorebi would not tile
them. They now get the title komorebi-recorder, but only when that is safe:
before the window exists, on Windows, the recorder runs
komorebic ignore-rule exe <name> (live rule, nothing persisted, 3 s timeout,
no console) for its own exe and komorebi-recorder-gui.exe. Registered, or no
komorebi running, means titled; komorebic missing or failing, and every
non-Windows host, stays untitled with one line on stderr (and in the
recorder window's message area). doctor gains a dry-check line.

No macOS-specific code was added (cfg!(windows) only); nothing here was
built for macOS.
2026-10-28 16:58:55 -07:00
LGUG2Z 13713d65e8 feat(assert): scripted pass/fail checks over a recording's findings, log, motion and notes
assert <session> --check "<kind> <args> <metric><op><number>" evaluates checks
with the existing analyses (findings, logq, motion, blank, annotations), one
Check trait and one registry line per kind. Exit 6 (ExitKind::Assertion) when a
check fails; checks that cannot be measured are errors (2/3/4), never a pass.
JSON envelope assert/1.
2026-10-28 16:24:29 -07:00
LGUG2Z e7283ae45d docs(dev): what ETW would tell us about window management
Spike with logman and tracerpt against Win32k, User32, Dwm-Core and
Shell-Core while driving a throwaway window. Sessions start without
elevation, but no event carries a window's rect, flags or caller.
Recommends not building an ETW tap.
2026-10-28 16:24:29 -07:00
LGUG2Z f9f4e437e4 feat(annotate): mark the timeline from a script while recording
`komorebi-recorder mark "text"` appends a point note (author script) to the
session being recorded, found by --session, KOMOREBI_RECORDER_SESSION or the
newest running recording. Notes now show as ticks on the viewer's bug lane.
2026-10-28 16:24:29 -07:00
LGUG2Z cf15fc978c feat(cli): record until a command exits, findings and brief --compact, and --json everywhere
record --until-exit -- <command> runs the command while recording (with
KOMOREBI_RECORDER_SESSION set) and stops when it exits; its status is reported
apart from the recorder's. record, displays, reindex and selftest take --json
(record/1, displays/1, reindex/1, selftest/1). brief --compact is a 40-line
brief, and findings merges detector findings (with stable f-xxxxxx ids) with
an agent's. annotate --ref log:"text" / log:HH:MM:SS.mmm / log:<video time>
resolves to a log line and says which.
2026-10-28 16:24:29 -07:00
LGUG2Z 3c4f352846 feat(record): sample every window's rect at video rate, and draw them on sheets
record --window-track[=HZ] (off by default, 30 Hz without a value, 1..=120)
writes windows.jsonl: a sampler thread lists every top-level window once per
tick and writes the full window list only when something changed, plus a
keyframe each second, so a still desktop costs about a row a second.
platform::window::list gives generic facts (Windows: EnumWindows + DWM
cloaked/frame bounds; macOS: CGWindowList bounds and on-screen flag).
The manifest records the track (rows, late ticks) and warns if it stopped
or fell behind. Analysis::window_track answers 'windows at mach_ns T', and
sheet --windows draws each window's rect and label on every frame (cloaked
windows dim), or notes that the session has no track.

The macOS part (platform/macos/apps.rs window_list) was written against the
objc2 sources and is NOT built or run: this was developed on Windows.
2026-10-28 16:24:29 -07:00
LGUG2Z 6af9eabd27 feat(video): motion, framediff, blank and compare for recordings
Built-in frame analysis for agents that scripted ffmpeg tblend/signalstats.
motion is changes with an optional --region (display points) and a peak
mean luma delta; framediff compares two frames (or one moment of two
recordings with --against) with an optional PNG; blank reports stretches
where a region is near-uniform (named colour) or frozen; compare sets two
recordings side by side. changes now shares the engine with motion and
behaves as before. The crop API takes a rect so a window rect can be
passed later. No macOS-specific code touched (not buildable here).
2026-10-28 16:24:29 -07:00
LGUG2Z 1f6e4cef05 feat(logq): query komorebi's log by field, with counts and group-by
logq <session> 'level=ERROR and hwnd=0x77179C' filters komorebi.log by
level, target, message, line, the span chain, the handled command and
event, or any span field, with and/or/parentheses, = != ~ !~, --count,
--group-by, --from/--to and a paged logq/1 envelope whose hits carry log:N
references. hwnd compares equal in decimal and hex. logparse keeps the
span chain as written (Line::chain).
2026-10-28 16:24:29 -07:00
LGUG2Z f3811fc24f feat(time): one clock for every time argument, and no slow handlers that are really delivery delay
at, range, frames and locate --utc now read any TimeSpec form (falling back to
video timecodes, so existing usage is unchanged). New: logtime:HH:MM:SS[.mmm[uuu]]
(also log-time: and wall:HH:MM:SS), a UTC time of day on the session's date, the
one inside the recording if it crosses midnight. A bare time of day stays video time.

komorebi's own send time (its 'pushed notification' log line) is now lined up with
events in order, so an event received long after it was sent still pairs with its
handler. Pair gains pushed_mach_ns and delivery_ms, and a handler view shows
pushed_video_s and delivery_ms beside the receive time. slow-handler without a push
time is info and says it may be delivery delay; a new delivery-batching finding
(info) describes notifications delivered in clumps. A bare process_command{Cmd(arg)}
span is now read as the command (it was nameless), and commands that differ only in
arguments are separate handlers.

No cfg(target_os = "macos") code touched.
2026-10-28 16:24:29 -07:00
LGUG2Z 11f028b8c9 feat(capture): record at the display's refresh rate, and give each frame its real duration
Windows Graphics Capture holds a capture to 60 frames a second unless it is
given a minimum update interval, so a 120 Hz display was recorded at half its
rate and a one-refresh flash could fall between two frames. ScreenCaptureKit
was asked for at most 30 (the default --fps), so macOS lost frames the same
way.

--fps now means the most frames a second, and 0, the new default, means no
cap: Windows sets the session's minimum update interval to a millisecond (or
a frame at --fps), and macOS sets a zero minimum frame interval. The encoder
is told 60 fps when there is no cap.

On Windows each sample was also stamped to last 1/fps whatever the gap to the
next frame. A frame is now held until the next arrives and given the real
time between them; the last one still gets a frame at the nominal rate. macOS
passes ScreenCaptureKit's own sample timing through, so needs no change.

Checked on a Mac with a 120 Hz display and komorebi for Mac running: with no
cap a display is recorded a frame every 8.3 ms, and --fps 30 holds it to about
30 a second. The video holds as many frames as the frame log has rows, and the
state komorebi was recorded in matches what the frames show. The macOS encoder
never reads fps, so CaptureConfig::fps now says it reaches only the Windows
one.
2026-10-28 16:24:29 -07:00
LGUG2Z d79ef03f21 test(ghost): what a Mac can say about a ghost tile, beyond the obvious
A Mac recording has no probe to read: a ghost tile there is found from the
frames komorebi read, so what counts as a frame no one can see matters more
than it does on Windows, and only the plain cases were held.

Added, with a Mac state of two displays, the second at negative coordinates as
a display arranged to the left of the main one is:

- a window filling the left display is not outside every display, and the same
  shape past its edge is
- one read of a frame no one can see is not enough, and two are
- a window on a workspace the display is not showing is not a ghost
- nothing is while komorebi is paused

The tests take their states from the session fixture and nothing from the host,
so they run on Windows as well as on a Mac: checked to type-check there (just
check-windows), not run.
2026-10-28 16:24:29 -07:00
LGUG2Z 93189eeb15 chore(deps): cargo update 2026-10-28 16:24:29 -07:00
LGUG2Z c239607af9 feat(record): read what Windows says about each window by default
--probe-windows was off unless asked for, so a recording made on Windows without
it could not say whether a window komorebi has in front is really on screen, and
had no ghost tiles to find: the most useful thing a Windows recording holds was
the one a person had to know to switch on.

On Windows record now probes each window event by default, and --no-probe-windows
turns it off. RecordArgs::probes_windows is the one place that decides, so the
command line and the recorder window (which takes RecordArgs::default) agree.
Elsewhere it stays off, because there is nothing to read: asking for
--probe-windows outright on a Mac is still an error, as it was, and the two flags
together are refused by clap on any host.

Checked on this Windows machine: a recording with no flag has a probe on 47 of
its 52 events, and with --no-probe-windows none of its 58.

The docs and help text say so, and a doc comment that said a Mac recording has no
ghost tiles is corrected: it has them, from the frames komorebi read.
2026-10-28 16:24:29 -07:00
LGUG2Z 93a024f0f1 test: skip what needs komorebi for Mac's source when there is none
Sixteen tests read the source of komorebi for Mac, through the catalog that
build.rs indexes from KOMOREBI_MAC_SRC (which nix develop sets) or the checkout
itself, and panicked or failed their assertions on a machine without it: every
Windows machine, and a Mac outside nix develop. That is not a failure of
anything, so they now say why and stop, as the tests that need ffmpeg do:

  skipped: KOMOREBI_MAC_SRC is not set, or this build was made without it

testkit::komorebi_mac_source_available says whether both the variable and the
indexed catalog are there, and skip_without_komorebi_mac_source! is its use at
the top of a test. With the source they run exactly as before.

On Windows the whole suite now passes.
2026-10-28 16:24:29 -07:00
LGUG2Z 7c692138c7 docs(usage): proposing a rule for a ghost tile
What the viewer offers under a bug region that was marked over a ghost tile, what
sending does and which credentials it uses, where the rule goes for each komorebi
(applications.json or applications.mac.json), how narrow it is, and what a
recording needs for there to be any ghost tile to propose on each host.
2026-10-28 16:24:29 -07:00
LGUG2Z 4bc35ef5d2 feat(viewer): offer to propose a rule for a ghost tile
Under a bug region that was marked while a ghost tile was there, the Bugs tab
says so and offers a rule. The button opens a form with what the recording showed
of the window, the application's name to change, and the rule as it would be
written, narrow enough to leave the program's other windows alone; if no such
rule can be written (nothing tells the ghost from a window that is on screen) it
says why and sends nothing. Nothing is sent until the user presses the button.

Sending runs on a background thread, and the form lists the steps as they happen
and ends with the link to the pull request, a link to open one, or, if something
failed, where the clone is kept (with a button to open the folder) and the
instructions to finish by hand. Escape closes the form, but not while it is
sending.

The recording's ghost tiles are found when it is opened, for the platform the
recording is of: the words are those of that komorebi, and the rule goes in its
file, whatever the viewer runs on.
2026-10-28 16:24:29 -07:00
LGUG2Z 9638dc44c5 feat(asc): propose a rule to komorebi-application-specific-configuration
A rule written from what a recording shows, and the pull request that sends it,
for either komorebi: the rule goes in the file of the komorebi the recording is
of (applications.json or applications.mac.json), not of the machine it is looked
at on.

asc::rule is the rule. It is an ignore rule, always composite so that never the
whole program is ignored: the program and the class on Windows, the application
and the title on a Mac, which has no class. When the program's other windows in
the recording share the ghost's class, the title is added; when nothing tells the
ghost from a window that is on screen no rule is written, and it says why. It
puts the rule into the file changing the lines of the rule and no others: a new
application is a pure insertion where it sorts (case ignored, as just sort does
it), a known one gets the rule in its ignore list and its comma. The result is
checked to be the old file and the rule and nothing more, and a file not laid out
as jq prints it is refused instead of reprinted. Applied to the real
applications.json: 16 lines added and none removed.

asc::submit clones the repository into a temporary directory, branches, commits
with a message that says what was seen, why an ignore rule and why one this
narrow, and pushes. With gh signed in it pushes to the repository if the user may
and to their fork if not (making one), and opens the pull request; without, it
pushes with git and gives a link. git is used for every push, so it is the user's
own credential helper that is asked. gh is looked for where Homebrew puts it, for
a program started from Finder. Anything that fails leaves the clone, with the
commit in it, and says what is left to do. Every location is injectable, and the
tests send to local repositories, a fake gh and a hook that refuses, never to
GitHub.
2026-10-28 16:24:29 -07:00
LGUG2Z 22a1930a48 feat(analysis): ghost tiles
A ghost tile is a tile of the layout holding a window a person cannot see: one
komorebi has in front on a workspace that is showing, and that was never on
screen, on at least two reads over half a second or still so at the last. Anything
less is a transition (a workspace switch, an application starting up) or
something a person did.

How the recording shows it depends on the host, since only one can be asked:

- komorebi for Windows: Windows says the window is cloaked or not visible on
  every probe of it, and never on screen or minimized. This needs a recording
  made with --probe-windows; without probes there are none here, which is not
  knowing and not none.
- komorebi for Mac: macOS cannot be asked, but komorebi's state has each window's
  frame, read live from the accessibility API. A ghost is a window whose frame is
  zero-sized or outside every display on every read, and never one a person can
  see. That is weaker evidence than Windows saying so, and is documented as such.
  It was not run against a real Mac recording.

A ghost carries the program, class and title komorebi has for it, and the other
windows of the same program that the recording saw (siblings), so that a rule for
it can be narrow enough to leave them alone. overlaps() says whether it was there
while a bug region was marked.
2026-10-28 16:24:29 -07:00