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.
This commit is contained in:
LGUG2Z committed 2026-10-28 16:24:29 -07:00
1 parent 93a024f0f1
commit c239607af9
8 files changed
+77 -16

No files matched your search

+2 -1
View File
@@ -71,7 +71,8 @@ enough to leave the application's other windows alone:
The entry is put where it sorts and the rest of the file is unchanged, line for line.
What counts as a ghost tile depends on what the recording can say. On Windows it needs `record --probe-windows` (see
What counts as a ghost tile depends on what the recording can say. On Windows it needs the window probes that `record` takes by
default (see
[Probing windows on Windows](recording-a-bug-repro.md#probing-windows-on-windows)): Windows says whether each window is
on screen, and a ghost is one it said was cloaked or not visible on every read and never on screen. A Mac cannot be
asked, so there it is a window whose frame, as komorebi read it from the accessibility API, was never one a person
+5 -4
View File
@@ -92,7 +92,7 @@ Useful options:
| `--oslog-all` | One extra unfiltered system-wide stream (very large) |
| `--no-oslog`, `--no-komorebi` | Skip the OS trace, or skip touching komorebi entirely |
| `--no-video` | Do not capture the screen; record everything else on the same clock (see below) |
| `--probe-windows` | Windows: after each window event, record what Windows says about that window (see below) |
| `--no-probe-windows` | Windows: do not record what Windows says about each window event, which is on by default (see below) |
| `--fps N`, `--retina`, `--codec hevc\|h264` | Video settings (30 fps cap, logical points, HEVC by default) |
### Marking where the bug is
@@ -116,14 +116,15 @@ started, and there is nothing for `frames` to show.
### Probing windows on Windows
komorebi for Windows hides a window by _cloaking_ it where it is, so its state cannot show whether a
window is really hidden. `record --probe-windows` follows each window event with a read of the
window is really hidden. So on Windows `record` follows each window event with a read of the
window's real state from Windows (visible, cloaked, minimized, where it is) and, now and then, asks
komorebi whether it manages the window and which rules matched. `overview` then compares the two:
a window komorebi shows that Windows has hidden, one it hides that Windows shows, and a visible
window it does not manage (usually correct, with komorebi's explanation). It costs a few system
calls per event and a query to komorebi the first time a window is seen, and it reads nothing but
those facts. It does nothing on a Mac, where a hidden window is parked in a corner and the state
says so.
those facts. `--no-probe-windows` turns it off, and without it `overview` cannot say whether a window is
really hidden, nor find a ghost tile. It does nothing on a Mac, where a hidden window is parked in a
corner and the state says so, and asking for `--probe-windows` there is an error.
### Checking your setup
+2 -2
View File
@@ -19,7 +19,7 @@
//! them can be asked:
//!
//! - **komorebi for Windows.** Windows can be asked whether a window is on screen, and a recording
//! made with `--probe-windows` has the answer for the window of each event
//! made with window probes (on by default on Windows) has the answer for the window of each event
//! ([`crate::sources::winprobe`]). A ghost is a window Windows said was `cloaked` or `not
//! visible` on every probe of it, and never on screen or minimized (a window that was ever shown
//! and is hidden now is in a transition, and a minimized one is something a person did).
@@ -229,7 +229,7 @@ impl Analysis {
/// Returns the ghost tiles of the recording, the longest-lived first.
///
/// What is one, and what a recording needs for there to be any, is in the [module](self)
/// documentation. A recording of komorebi for Windows made without `--probe-windows` has none.
/// documentation. A recording of komorebi for Windows made with `--no-probe-windows` has none.
///
/// # Errors
///
+1 -1
View File
@@ -187,7 +187,7 @@ impl Proposal {
),
};
let recorded_with = match platform {
Platform::Windows => "with `komorebi-recorder record --probe-windows`",
Platform::Windows => "with window probes on (komorebi-recorder's default on Windows)",
Platform::Macos => "of komorebi for Mac",
};
let reads = match platform {
+47 -6
View File
@@ -63,12 +63,18 @@ pub struct RecordArgs {
#[arg(long)]
pub no_komorebi: bool,
/// komorebi for Windows hides a window by cloaking it in place, which its state cannot show.
/// With this, each window event is followed by a read of what Windows says about that window
/// (visible, cloaked, minimized, where it is) and, now and then, komorebi's own answer to "would
/// you manage this window, and why", so that a window komorebi shows but Windows has hidden (or
/// the reverse) can be found. Windows only
#[arg(long)]
/// So each window event is followed by a read of what Windows says about that window (visible,
/// cloaked, minimized, where it is) and, now and then, komorebi's own answer to "would you manage
/// this window, and why", so that a window komorebi shows but Windows has hidden (or the
/// reverse) can be found. This is what a recording on Windows does unless told not to
/// (`--no-probe-windows`); on a Mac there is nothing to read, and asking for it is an error
#[arg(long, conflicts_with = "no_probe_windows")]
pub probe_windows: bool,
/// Do not read what Windows says about each window (see `--probe-windows`, which Windows
/// recordings do by default): the recording then cannot show a window komorebi has in front that
/// Windows has hidden, such as a ghost tile
#[arg(long)]
pub no_probe_windows: bool,
/// Do not capture the screen: record everything else (komorebi's events and log, the OS
/// trace and incidents) on the same clock
#[arg(long, conflicts_with = "displays")]
@@ -114,6 +120,7 @@ impl Default for RecordArgs {
no_komorebi: false,
no_video: false,
probe_windows: false,
no_probe_windows: false,
no_oslog: false,
oslog_apps: AppsMode::Managed,
oslog_all: false,
@@ -178,9 +185,43 @@ impl RecordArgs {
duration: self.duration.map(Duration::from_secs_f64),
no_komorebi: self.no_komorebi,
no_video: self.no_video,
probe_windows: self.probe_windows,
probe_windows: self.probes_windows(),
}
}
/// Returns whether the recording reads what Windows says about each window.
///
/// It does on Windows, unless `--no-probe-windows` says not to, and it does not elsewhere,
/// where there is nothing to read: `--probe-windows` asked for outright is kept as asked, so
/// that a host that cannot do it says so instead of recording without it. The recorder window
/// takes its options from [`RecordArgs::default`], so it follows the same rule.
///
/// # Example
///
/// ```rust
/// use komorebi_recorder::cli::RecordArgs;
///
/// // the default follows the host: Windows can be asked, a Mac cannot
/// assert_eq!(RecordArgs::default().probes_windows(), cfg!(windows));
///
/// // and can be turned off
/// let off = RecordArgs {
/// no_probe_windows: true,
/// ..RecordArgs::default()
/// };
/// assert!(!off.probes_windows());
///
/// // asking for it where it cannot be done is kept, to be refused when recording starts
/// let asked = RecordArgs {
/// probe_windows: true,
/// ..RecordArgs::default()
/// };
/// assert!(asked.probes_windows());
/// ```
#[must_use]
pub fn probes_windows(&self) -> bool {
!self.no_probe_windows && (self.probe_windows || cfg!(windows))
}
}
pub(super) fn displays() -> eyre::Result<()> {
+1 -1
View File
@@ -70,7 +70,7 @@ locations as hints.
- An `AXError` in komorebi's log comes from the application or the OS, not from komorebi.
- komorebi for Windows hides a window by **cloaking it where it is**, so its `State` cannot say
whether a window is really hidden, and the position-based hidden-window checks do not apply. A
recording made with `--probe-windows` stores, with each window event, what Windows said about that
recording made on Windows (unless with `--no-probe-windows`) stores, with each window event, what Windows said about that
window just after it (`exists`, `visible`, `cloaked`, `minimized`, `rect`, and now and then
komorebi's own `DebugWindow` verdict with the rules that matched); `overview` then reports
`visible-window-hidden` (komorebi has it in front, Windows has it cloaked or minimized),
+2 -1
View File
@@ -92,7 +92,8 @@ pub struct Loaded {
/// How the komorebi source this build indexed compares with the komorebi that was recorded.
pub skew: Skew,
/// The ghost tiles the recording shows: tiles that held a window a person could not see.
/// Empty for a recording made without `--probe-windows`, and for one of komorebi for Mac.
/// Empty for a recording of komorebi for Windows made without window probes
/// (`--no-probe-windows`).
pub ghosts: Vec<GhostTile>,
}
+17
View File
@@ -281,3 +281,20 @@ fn a_host_that_is_not_windows_refuses_to_probe_windows_before_it_records_anythin
assert!(stderr.contains("not Windows"), "{stderr}");
assert!(!out.exists(), "no session was started");
}
#[test]
fn asking_for_window_probes_and_against_them_is_an_error_on_any_host() {
let output = Command::new(env!("CARGO_BIN_EXE_komorebi-recorder"))
.args([
"record",
"--probe-windows",
"--no-probe-windows",
"--no-video",
])
.output()
.expect("run");
assert!(!output.status.success());
let stderr = String::from_utf8_lossy(&output.stderr);
assert!(stderr.contains("cannot be used with"), "{stderr}");
}