From c239607af997a1ee5c92b98d22a16e5f80d6bb9f Mon Sep 17 00:00:00 2001 From: LGUG2Z Date: Tue, 27 Oct 2026 15:07:16 -0700 Subject: [PATCH] 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. --- docs/usage/investigating-a-recording.md | 3 +- docs/usage/recording-a-bug-repro.md | 9 ++-- komorebi-recorder/src/analysis/ghost.rs | 4 +- komorebi-recorder/src/asc/submit.rs | 2 +- komorebi-recorder/src/cli/record.rs | 53 ++++++++++++++++++++--- komorebi-recorder/src/guide.md | 2 +- komorebi-recorder/src/viewer/loaded.rs | 3 +- komorebi-recorder/tests/windows_flavor.rs | 17 ++++++++ 8 files changed, 77 insertions(+), 16 deletions(-) diff --git a/docs/usage/investigating-a-recording.md b/docs/usage/investigating-a-recording.md index f811b890..55a2eeba 100644 --- a/docs/usage/investigating-a-recording.md +++ b/docs/usage/investigating-a-recording.md @@ -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 diff --git a/docs/usage/recording-a-bug-repro.md b/docs/usage/recording-a-bug-repro.md index c04acc9b..59dd454a 100644 --- a/docs/usage/recording-a-bug-repro.md +++ b/docs/usage/recording-a-bug-repro.md @@ -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 diff --git a/komorebi-recorder/src/analysis/ghost.rs b/komorebi-recorder/src/analysis/ghost.rs index bd305d75..d0fa3c5f 100644 --- a/komorebi-recorder/src/analysis/ghost.rs +++ b/komorebi-recorder/src/analysis/ghost.rs @@ -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 /// diff --git a/komorebi-recorder/src/asc/submit.rs b/komorebi-recorder/src/asc/submit.rs index 72c4a229..f0110f0b 100644 --- a/komorebi-recorder/src/asc/submit.rs +++ b/komorebi-recorder/src/asc/submit.rs @@ -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 { diff --git a/komorebi-recorder/src/cli/record.rs b/komorebi-recorder/src/cli/record.rs index 42ca33a7..85cd5c2a 100644 --- a/komorebi-recorder/src/cli/record.rs +++ b/komorebi-recorder/src/cli/record.rs @@ -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<()> { diff --git a/komorebi-recorder/src/guide.md b/komorebi-recorder/src/guide.md index 01bc9b1c..84b4b371 100644 --- a/komorebi-recorder/src/guide.md +++ b/komorebi-recorder/src/guide.md @@ -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), diff --git a/komorebi-recorder/src/viewer/loaded.rs b/komorebi-recorder/src/viewer/loaded.rs index b962f0a8..fae069c0 100644 --- a/komorebi-recorder/src/viewer/loaded.rs +++ b/komorebi-recorder/src/viewer/loaded.rs @@ -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, } diff --git a/komorebi-recorder/tests/windows_flavor.rs b/komorebi-recorder/tests/windows_flavor.rs index ebede8e6..cb309150 100644 --- a/komorebi-recorder/tests/windows_flavor.rs +++ b/komorebi-recorder/tests/windows_flavor.rs @@ -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}"); +}