komorebi/docs/dev/platform-contract.md

# The contract of a Platform

A shared scenario (`nix/tests/vm/lib/komorebi_vm/core/scenarios`) runs on KDE here and on
Windows in kfw's guests, through the `Platform` protocol (`core/platform.py`). A check
that one port answers by how its implementation happens to work, and the other by what
the system says, passes on one port for the wrong reason. This file lists what each member
promises to both ports, and the quirks of each port that a scenario must not lean on. The
docstrings of `Platform` are the contract; this is the audit behind them.

## What each member promises

| Member | Both ports promise | Quirk a scenario must not depend on |
| --- | --- | --- |
| `has(feature)` | `"pointer"`, `"lock"`; a scenario that needs one is skipped, with the reason, where it is false | KDE has `lock` only in a real Plasma session (`session=True`); Windows has both always |
| `tolerance` | how far a frame may be **short** of the one asked for; the frame is never past it | KDE 24 px (a terminal's cells), Windows 2 px (rounding). It bounds what a client rounds to; it is not a measure of a change, so a scenario asks the daemon's layout for the change (`support.layout_rect`) and then that the frame follows it within the tolerance |
| `wait_for(p, t)` | polls `p` until it holds or `t` seconds, scaled for the host | Windows turns a `RuntimeError` of a `komorebic` call in `p` into a false; KDE lets it raise. A predicate answers false for what it cannot tell yet, and relies on neither |
| `komorebic(...)`, `komorebic_status(...)` | `komorebic` raises if the command fails; `_status` returns the exit status and what it printed | the exception type (`AssertionError` on KDE, `RuntimeError` on Windows): a scenario catches `Exception` or nothing |
| `start_komorebi()`, `restart_with(c)` | the daemon starts from a clean state, with the windows that are open taken up | Windows launches it up to three times; KDE once |
| `rewrite_config(c)` | writes the file the daemon watches; returns before the daemon has read it | the delay before a reload is the daemon's (a scenario waits for the state, or `QUIET` for what must not happen) |
| `spawn(title, app_id, exe)` | opens a window and waits until the system has it; raises if it never does | a title is taken as it is and no window has another's; `exe` is a name of letters, digits, `_` and `-`, without an extension (`exe_id(name)` spells it as the daemon names it: `name` on KDE, `name.exe` on Windows) |
| `os_window(c)` | the system's own frame of the window, or `None`; `focused` is the keyboard focus, for at most one window | the frame of a minimized window is wherever the system keeps it; a scenario does not read it |
| `hidden(c)` | true for a window the daemon put away: a stack's other windows, a workspace that is not shown, behind a monocle. False for a window the system does not have, one that is minimized, one that floats | true on KDE for any window on a virtual desktop that is not shown (with more than one output, the desktop of the active output), on Windows for any cloaked window (another Windows desktop included). A scenario that asks for "put away" also asks `state()` where the window is, and counts "in view" through `support.in_view`, which needs the system to have the window |
| `displays()` | each display's rectangle in the desktop's coordinates, left to right, as the system says | displays are not one size (on Windows the first is the basic adapter, 1280x800, and the second, the only one whose mode can change, is 1024x768 by default and follows `resize_display`) and a scenario does not compute where the next begins |
| `add_display()`, `remove_display()` | plugs a display in to the right, unplugs the last; return when the system agrees | Windows removes only a display `add_display` plugged in (a hotplug port is used once); KDE enables a disabled output and disables the last enabled one, so a headless session with two outputs can unplug at once. A scenario unplugs only after plugging in, unless its suite started with more than one display |
| `work_area()` | the area of the first display that windows may take, as the system says: the display less panels, docks and the taskbar | KDE asks KWin (a script: its placement area), and answers with the whole output only if KWin does not answer. A headless session has no panel, so there it is the output |
| `put_file(path, data)`, `wallpaper(display)`, `set_wallpaper(path, display)` | a file the daemon can read; the picture a display shows; the wallpaper as the user sets it | KDE reads and sets it through the Plasma shell's D-Bus API. Windows: `IDesktopWallpaper`. `restart_with` in a real Plasma session restarts the module's unit with the user's `komorebi.json` |
| `resize_grab(frame, grab)` | where the pointer is pressed to take a window by an edge or corner | KDE: the gap outside the frame on every side (`resize.outside_grab`). Windows: left, right and bottom are the invisible border outside the visible frame; the top has none, so it is inside the frame's top row |
| `close`, `minimize`, `activate`, `move_window` | act on the window as the user would; raise if there is no such window | `close` returns before the window is gone (a scenario waits for `os_window` to be `None`); `move_window` puts the top left of the *visible* frame at (x, y) |
| `lock()`, `unlock()` | lock and unlock the screen and return when it is so | the lock screen is `LogonUI` on Windows and the Plasma greeter on KDE; a scenario asks only what the daemon and the windows do |
| `pointer` | moves in the pixels of the first display; a drag is one press, a glide, one release | a window manager that follows the pointer by a hover delay (Windows) or by its own focus policy (KDE) has to be given time: `focus_follows_mouse.SETTLE` |
| `screenshot(name)` | the display as an image | none |

## Findings of the review, and what was done

1. `work_area()` on KDE was the whole output. **Confirmed.** The headless KWin has no panel so
   no suite could tell, but a scenario's "inside the work area" was weaker than on Windows
   wherever a panel exists. `KdePlatform.work_area()` asks KWin for the placement area of the
   leftmost output (`Kde.screens`, a KWin script like the daemon's bridge uses) and falls back
   to the output. Monocle and maximize now also check that their window stays inside it. To
   verify on KDE: a suite with a panel (`drag-resize`, `run-kde`) and `core-e2e`; the script
   (`workspace.clientArea(KWin.PlacementArea, ...)`) has not been run.
2. `tolerance` is 24 on KDE. **Partly confirmed.** Most uses are right: a frame short of a
   tile by up to 24 px, in a tile hundreds of pixels wide. Not right: `resize_commands` checked
   that a decrease gave back the width within the tolerance, so a daemon that gave back less
   than the increase passed for a terminal. It now compares the daemon's layout and then the
   frame. `inside(area)` takes no slack for the tolerance, because a frame is never past what
   was asked.
3. `hidden()` is true for any window on a desktop that is not shown. **Confirmed as a
   difference, refuted as a source of vacuous passes.** Every scenario that asks for a window to
   be put away also asks the daemon where it is (`workspace_of`, `containers`, `monocle`), and
   a window that was lost is not in view (`support.in_view`). The docstring now says what each
   port is true for. With two outputs on KDE only the first output's windows are certain.
4. `focus_follows_mouse` passed `--implementation windows` and a KWin-sized settle. **Confirmed.**
   Both ports' `komorebic` default to `windows`, so the flag is gone, and the settle is a named
   wait, `SETTLE`, that is longer than either needs.
5. Constants tuned for KDE. **Confirmed for the 400,300 move of `locking`, the absolute room of
   `padding` (5000 and 2000 square pixels), the 60 px drag of `resize`, the first display's
   rectangle in `hotplug` (the work area is the right area) and the quiet period of 3 s written
   in nine places.** They are now derived from the work area or named (`support.QUIET`).
   Checked and found neutral: the `1920`, `foot`, `KWin`, `wayland`, `app_id` and `.exe`
   words in the shared scenarios are in comments, or go through `exe_id` and `spawn`.
   `locking` also did not check that the window moved, so a platform that could not move it while
   locked passed; it does now.
6. Checks that pass for how an implementation answers. **Confirmed**: `spawn` did not raise on
   KDE if the window never came (a "stays unmanaged" check then passed for a window that was
   not there); `close`, `minimize`, `activate` and `move_window` on a window that is not there
   did not raise a message; `displays()` was the size the session was started with and not what
   KWin says; a program name that Windows rejects was shell-quoted into KDE; a title was a regular
   expression on KDE. All fixed. `os_window().focused` is each system's own answer and
   the same in meaning. The frame of a minimized window is not specified (KDE keeps it, Windows
   may park it off screen): no scenario reads it.

## Open items

- kfw's `windows_platform.py` builds `Rect(left, top, right, bottom)` for `displays()`, `os_window`
  and `work_area()`. Checked with the kfw session: its agent returns the width and height under
  `right` and `bottom` (the shape `komorebi` itself prints), so it is `(x, y, w, h)` in kfde's
  terms; the names are misleading, not wrong.
- `inside(area)` has no slack. On Windows the DWM frame might round one pixel past; if the
  first run says so, the slack is a `Platform` member, not a number in the scenarios.
- KDE `hidden()` with two outputs and per-output desktops answers for the desktop of the active
  output only.
- Unverified on KDE, to run: `core-e2e` (work_area, spawn raising, `in_view`, `resize_commands`),
  `hotplug` (displays from KWin, `work_area` after an unplug), `drag-resize` (the drag distance,
  `focus_follows_mouse` with no flag, work area with a panel), `core-lock` (the move while
  locked). On Windows: every scenario above.