From 7260c9f772835b06346dab0d38cf04a7c8338331 Mon Sep 17 00:00:00 2001 From: LGUG2Z Date: Sat, 31 Oct 2026 00:31:27 -0700 Subject: [PATCH] docs(seam): findings from the 7c adapters (section 9) Appends section 9 to docs/dev/seam.md: for each method of the shared Backend, what WindowsBackend and MacosBackend do and where that differs from what the daemon calls today (windows() and macOS's registry cannot be written faithfully; set_rect on Windows drops the top flag and keeps animation and guards; hide/restore results are ignored on Windows; macOS hide needs a corner and a display; raise on macOS also focuses; macOS monitors() has to be a main-thread-refreshed cache; set_opacity on Windows is the plain write). Concludes that the trait did not have to change and records three proposals (rect as Option, hide's hidden inputs, windows() as start-up operation). Verified: docs only, not built. Every claim is by reading the code while writing the adapters; what could not be settled by reading is marked 'not verified' in the text. --- docs/dev/seam.md | 61 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 61 insertions(+) diff --git a/docs/dev/seam.md b/docs/dev/seam.md index 9ab32da3..138ad96c 100644 --- a/docs/dev/seam.md +++ b/docs/dev/seam.md @@ -358,3 +358,64 @@ Everything I could not confirm by reading, and how to confirm it. | 13 | The Windows paths of every `WindowsApi` call: section 3.2 lists thread entry points and examples, not every call chain | `cargo` call graph or a `tracing` run that logs the thread name per `WindowsApi` call in a scenario | | 14 | The KDE `block_on` panics inside a runtime thread | Tokio documentation; a unit test calling a `block_on` method from `Handle::spawn` | | 15 | Anything about runtime behaviour: this document is built from reading only; nothing was compiled or run | Run the three gates of the progress log (KDE fast tier, Windows scenarios, macOS by hand) when the trait exists | + +## 9. Findings from the 7c adapters + +Step 7c wrote `WindowsBackend` (`komorebi/src/windows_backend.rs`) and `MacosBackend` (`komorebi-for-mac/komorebi/src/macos_backend.rs`) over the existing static functions, to learn which methods of the shared trait (`crates/komorebi-backend`) cannot be implemented without changing what the daemon does. Both compile (Windows: clippy `-D warnings` clean; macOS: fake-CC `cargo check` 0 errors) and neither is used by its daemon. They have never run: everything below comes from reading the code while writing the adapter, and "not verified" means exactly that. `K/` is `komorebi-for-kde/komorebi/src/`; `W/` and `M/` as in section 1. + +**Verdict.** All 14 required methods and the 4 capabilities could be written on both platforms, so the trait did not have to change. Eleven of them carry a semantic difference that the doc comments of the trait already allow (a request, a platform-defined read) or that the adapter had to choose; those are listed here so steps 8 and 11 decide them knowingly. Nothing in this section is a reason to change the trait yet; the three candidates are marked PROPOSAL. + +### 9.1 Windows (`WindowsBackend`) + +| Method | What the adapter does | What differs from the daemon's own call | +|---|---|---| +| `windows()` | `WindowsApi::alt_tab_windows()` (`W/windows_api.rs:763`), each one read with `info` | **Cannot be written faithfully.** The candidate list the daemon uses is `load_workspace_information` (`:437`), which filters inside the `enum_window` callback while filling the containers of a `WindowManager`. The adapter has no manager, so it lists alt-tab windows, a superset (no `should_manage`, no ignore or float rules). | +| `window(id)` | `IsWindow`, then one call per field (`process_id`, `title`, `class`, `exe`, `path`, `is_iconic`, `is_zoomed`) | `fullscreen` and `normal` are `None`: komorebi decides both in the core, there is no OS query. An error reading the frame leaves `rect` at the default, indistinguishable from a window at the origin (PROPOSAL: `rect: Option` or an error). Five or six kernel calls per call, where KDE answers from a table: do not call it per frame. | +| `monitors()` | `valid_hmonitors()` then `WindowsApi::monitor(hmonitor)` for each | `monitor` re-enumerates every display for each handle (quadratic) and reads the global `DUPLICATE_MONITOR_SERIAL_IDS` (a duplicated serial becomes `None`). Physical pixels, the `Monitor.id` is an `isize` carried bit for bit through `MonitorId::from_hmonitor`. | +| `cursor_pos()` | `GetCursorPos`, an error is `None` | The error is dropped. | +| `set_rect` | `Window::set_position(rect, false)` | `top` (raise to the front in the same `SetWindowPos`) has no place in the trait: it is `false`, a caller raises separately, so one `SetWindowPos` becomes two. `Window::set_position` also keeps its slide-in animation, the live-resize guard (returns `Ok` while the user holds the window) and the early return when the frame is already right (`W/window.rs:329-370`): the call can return `Ok` without writing, which fits "a request" but not "the window will be there". Synchronous by default (waits for the target's thread; see unverified 7). | +| `focus` | `Window::focus(mouse_follows_focus)` | Matches the trait, including the cursor centring. When the window is still sliding in (`transition::is_entering`) the focus is **deferred** and `Ok` is returned. | +| `raise` | `Window::raise` (raises without activating, and the border) | Matches. | +| `hide`, `restore` | `Window::hide`, `Window::restore` | They return `()`: `ShowWindow` and the cloak result are ignored, so `WindowGone` is told only by an `IsWindow` check before the call (a race). They also hide or show the window's border and write `HIDDEN_HWNDS`, and are skipped while a workspace slide owns the window (`is_exiting`, `is_entering`). The default hiding behaviour `Cloak` is not observable by the user; `Hide` and `Minimize` are (finding 11). | +| `minimize` | `Window::minimize` | Silently does nothing for an exe that contains `komorebi-bar`, and returns `Ok`. No error is possible (`()`). | +| `unminimize` | `WindowsApi::restore_window` (`SW_SHOWNOACTIVATE`) | Windows has no unminimize: this is the restore the hiding behaviours use, **without** the `HIDDEN_HWNDS` and border bookkeeping of `Window::restore`. It does not activate. | +| `close` | `Window::close` (`PostMessage WM_CLOSE`) | Matches; the only call with a real error (a failed post), turned into `WindowGone` when the window is gone. | +| `center_cursor_in` | `WindowsApi::center_cursor_in_rect` | Matches (and the one place the rect is honoured, finding 10). | +| `monitor_from_point` | `WindowsApi::monitor_from_point` | **Overrides the trait default** because Windows uses `MONITOR_DEFAULTTONEAREST`: never `None`. The trait documents this; shared code must not use `None` to detect "off screen". | +| `maximize` | `Window::maximize` / `unmaximize` | `()`-returning; removes the window from `HIDDEN_HWNDS` as the daemon does. | +| `set_opacity` | LAYERED extended style, then `WindowsApi::set_transparent(hwnd, alpha)` | **Not what the daemon calls.** `Window::transparent`/`opaque` take the alpha from `transparency_manager::TRANSPARENCY_ALPHA` (a global, not an argument) and may animate (`TransparencyRenderDispatcher`). The adapter writes the plain value both end in, with no animation and no manager bookkeeping. | +| `set_focus_follows_mouse` | `enable_`/`disable_focus_follows_mouse` (the system setting) | The komorebi-implemented focus follows mouse (`W/process_movement.rs`) is a different mechanism with its own thread and is not started or stopped by this; the daemon today picks one by configuration. Both are "focus follows mouse"; the trait method means the OS setting. | +| Workspaces (5) | `Unsupported` | By design: komorebi's own workspaces. | +| Batch | default no-op | Windows does not batch. | +| Thread | any thread | The calls are stateless except for the statics named above (`HIDDEN_HWNDS`, `DUPLICATE_MONITOR_SERIAL_IDS`, the transition and live-resize tables), which are behind locks. `set_rect` and `raise` wait for the target window's thread unless `WINDOW_HANDLING_BEHAVIOUR` is `Async`: the bounded-wait rule of section 7(4) is not met by Windows today. | + +### 9.2 macOS (`MacosBackend`) + +| Method | What the adapter does | What differs from the daemon's own call | +|---|---|---| +| (registry) | `Mutex>` with `register(Window)` and `forget(id)`; every method clones the `Window` out | **The trait needs a feeder the trait does not have.** The daemon must call `register` wherever it creates a `Window` (start-up enumeration by title, AX events) and `forget` on destroy. `Window` carries the element, application and observer, and the adapter keeps the whole clone, so the registry holds the observer too (consequence 1 said the observer could stay outside: it cannot while `Window` is the unit). An id not in the registry is `WindowGone`, which is also what a window the daemon never registered looks like. | +| `windows()` | the registry's windows that are still valid | **Cannot be written faithfully.** The CoreGraphics list joined by title with the AX elements (`M/macos_api.rs:312-374`) lives in `load_workspace_information`, which fills a `WindowManager`. The list is only as complete as the registry. | +| `window(id)` | AX round trips: `is_valid` (attribute names), frame (two reads), title, exe, path, `AXMinimized` | There is no existing "is minimized" query, so the adapter reads `AXMinimized` itself. A dead window gives `None`, so "never known" and "dead" cannot be told apart (the trait allows both). `class`, `fullscreen`, `maximized`, `normal` are `None`. A frame read error leaves `rect` at the default (same PROPOSAL as Windows). Four or more IPC calls to the app per call: slow and blocking on a hung app. | +| `monitors()` | a cache; `refresh_monitors(MainThreadMarker)` fills it from `latest_monitor_information` | **A change in how the daemon works, not just an adapter.** Today every caller runs on main (`exec_sync`). The cache has to be refreshed by the display callback on main (a `try_send` today, `M/display_reconfiguration_listener.rs:12-30`); before the first refresh `monitors()` is an `Err`. The `MainThreadMarker` argument makes a call from another thread a compile error. This is the TARGET rule of consequence 4 made real. | +| `foreground_window` | `MacosApi::foreground_window_id` | Matches (`None` when any AX step fails). | +| `cursor_pos` | `MacosApi::cursor_pos` | Matches, always `Some`; floats are truncated to `i32`. | +| `set_rect` | `Window::set_position` | May write directly or hand the move to the animator, and honours the drag `Snap` state (`M/window.rs:915-940`): a request, as the contract says. A failed write asks `is_valid` to decide between `WindowGone` and a platform error (the reaper's trick, a second round trip inside the error path). | +| `focus` | `Window::focus` | Matches (SkyLight `set_front_process`, then `AXMain`; tabbed apps use `main_window`). Error is `LibraryError`. | +| `raise` | `Window::raise` | **Also focuses**: macOS has no raise without focus (`AXMain` and `AXFocused`). | +| `hide` | `Window::hide(hiding_position)` | **The trait has no place for two inputs `hide` needs.** The corner (`WindowHidingPosition`) is configuration of the monitor; `MacosBackend::new` takes one for all windows. And `hide_on(position, screen)` wants the display the window's monitor owns, "since a window that hangs over the edge is not always on the display the lookup by position finds" (`M/window.rs:610-615`); the adapter passes none and takes the lookup. PROPOSAL (step 11, not now): hide stays as it is and `MacosBackend` learns each window's monitor at `register`. | +| `restore` | `Window::restore` | Matches. A window that was not hidden is left alone, as the contract says. | +| `minimize`, `unminimize` | `Window::minimize`/`unminimize` (`AXMinimized`) | Match (both need `&mut self`; the adapter clones). | +| `close` | `AdhocWindow::close(element)` (presses the close button) | The daemon calls it on the foreground element; here by id. `Ok` when the window has no close button. | +| `center_cursor_in` | `MacosApi::center_cursor_in_rect` | Matches. | +| `monitor_from_point` | `MacosApi::monitor_from_point` (CoreGraphics) | Matches: `None` outside every display. | +| Capabilities | none | By design (rows 16 to 19). | +| Batch | a stack of SkyLight `BatchedUpdates` guards | Matches the daemon's own brackets. Not verified: that nested `SLSDisableUpdate` calls count (the daemon nests none today). The guard holds the main connection id, so it is `Send`; `SLSReenableUpdate` from another thread than the one that disabled is not verified. | +| Thread | any thread except main for everything but `refresh_monitors` | Not verified: whether `hide_on(.., None)`'s lookup by position (`M/window.rs:616-676`) reaches an `NSScreen` and so needs main; if it does, `hide` breaks the rule until the screen is passed (see `hide`). | + +### 9.3 What this means for the trait + +1. **No change was needed to write both adapters.** The capability query, the batch scope, `WindowGone` and the optional fields were all used, and each was necessary: macOS answers `Unsupported` for all four capabilities, Windows for one; `WindowGone` is built from a pre-check on Windows (results ignored) and from a re-check on macOS and KDE; `None` fields are used on both. +2. **PROPOSAL A: `WindowInfo::rect` can fail** on both platforms (a frame read is an API call). If the core must tell "at the origin" from "unknown", the field becomes `Option`. Decided not to change it now: KDE cannot fail, and the shared core has no consumer yet. +3. **PROPOSAL B: `hide` has hidden inputs on macOS** (corner, monitor). Left to step 11, where the registry learns the monitor at registration. +4. **PROPOSAL C: `windows()` is a start-up operation on Windows and macOS** (the filtered list needs the core's rules), and the trait documents it as slow. If the core wants one candidate list, the filter has to move into shared code with the window rules as an argument. +5. **The adapters add non-trait API that the daemons must call** (`MacosBackend::register`, `forget`, `refresh_monitors`; `MacosBackend::new(hiding_position)`). That is the cost of keeping `Window` as it is until step 11(ii).