# `keyboard_probe.py` — Stage 0 of the keyboard plan Stage 0 of [`docs/plans/2026-10-03-keyboard-input.md`](../docs/plans/2026-10-03-keyboard-input.md), written to the probe spec in [`docs/plans/2026-10-04-keyboard-verification.md`](../docs/plans/2026-10-04-keyboard-verification.md) §B1. It measures the things neither plan would let Stage 1 guess at, and prints what it saw. It is **throwaway**: delete it once `checks/vm-keyboard.nix` asserts the same properties in a VM. The review says not to commit it at all; the brief that commissioned this work says to commit it under `examples/` or `tests/` with a README, and that is what this is. Nothing downstream imports it. It speaks to the compositor and to nothing else — **no broker, no lease, no `hhstreamd` control socket, no `hhstream` CLI, no session**. Read-only `hyprctl` (`clients -j`, `getoption -j`) is used so the warp hits a box it knows the coordinates of; `hyprctl dispatch` is never used, because `dispatch focuswindow` would answer (a) by cheating. It does two things that are not read-only, because keyboard focus cannot be measured without them: it opens two small windows of its own, and it moves the one cursor. It refuses to send a key until it has seen `wl_keyboard.enter` on a surface it owns, and it lifts everything it pressed on the way out — including through a fresh virtual keyboard, because of what (b) turned out to be. ## Running it It needs `pywayland` (the dev shell has it), `xkbcommon` (the dev shell does not, until Stage 1 adds it), `hyprctl`, and the protocol XML. One command, in the shape `hhstream_pointer._protocol.regenerate`'s docstring already uses for "this needs something the dev shell lacks": ```bash cd /var/lib/hermes/projects/hhstream-keyboard # or wherever this checkout is XML="$(nix eval --raw nixpkgs#hyprland.src)/protocols" sg hhstream -c "HHSTREAM_PROTOCOL_DIR='$XML' PYTHONPATH=src \ nix shell --impure --expr 'with (builtins.getFlake \"nixpkgs\").legacyPackages.\${builtins.currentSystem}; [ (python3.withPackages (p: [ p.pywayland p.xkbcommon ])) hyprland ]' \ --command python3 tests/keyboard_probe.py" ``` `sg hhstream` is not optional: `/run/hypr-stream` is `0750 hhstream:hhstream`, so a login that predates the group membership cannot open the Wayland socket at all. (The review's `sudo -u hermes -g hhstream env …` form does the same thing and also works; `sg` is what the brief asked for and needs no root.) `PYTHONPATH=src` is how it reaches the driver's already-vendored wlr *pointer* protocol rather than growing a second copy. Flags: `--runtime-dir` (default `/run/hypr-stream`), `--xml`, `--output` (only needed if the compositor has more than one), `--xkb-layout`, `--xkb-model`. ### Where it deviates from the review's §B1 sequence All three are visible in the transcript and none of them changes an answer: - the keymap is uploaded **before** the windows are opened, not after. It has to be: the seat has no libinput keyboard, so `wl_seat.capabilities` does not include `keyboard` until a virtual one exists (the setup block goes `1` then `3`), and a listener bound any later would have seen nothing at all; - the idle wait before (a1) is 0.8 s rather than 0.6 s; - (a2) follows (a1) after the settle window and a print — measured at 0.401 s rather than being "immediate", and still inside the 0.5 s that matters. Exit codes: **2** if `zwp_virtual_keyboard_manager_v1` is missing or is not version 1 — the gate the plan says stops the project — and 0 otherwise. The answers are in the output, not in the exit status: a measurement that came back "no" is still a successful measurement. ### Where the XML is, and where both plans say it is Both plans say the XML is wayland-protocols' `unstable/virtual-keyboard/virtual-keyboard-unstable-v1.xml`, and the review's objection 4 says specifically *not* to use Hyprland's copy. **Neither is possible here.** Checked, on this machine: | Source | Has it? | | --- | --- | | `wayland-protocols` 1.49 (this flake's own nixpkgs input), `unstable/`, `staging/`, `stable/` | no — there is no `virtual-keyboard` directory at all | | `pkgs.wlr-protocols` (nixpkgs' 2022-09-05 snapshot), output *and* `.src` | no — ten XMLs, the virtual *pointer* among them, not this one | | `pkgs.wlroots.src` | no | | `pkgs.hyprland.src` → `protocols/virtual-keyboard-unstable-v1.xml` | **yes, and it is the only copy** | ```bash echo "$(nix eval --raw nixpkgs#hyprland.src)/protocols/virtual-keyboard-unstable-v1.xml" ``` So the probe, and Stage 1's vendoring, use the Hyprland copy. The review's reason for avoiding it is real and is handled rather than ignored: that copy *names* `keymap_format` and `key_state` in prose and never defines them, so the generated module carries no enum for either. Both are therefore written down as constants with a citation — in this file as `XKB_FORMAT_TEXT_V1` and `RELEASED`/`PRESSED`, and in the driver as `hhstream_pointer.keymap.XKB_V1` beside the existing `buttons.STATES` (which already holds the same two integers, as the review notes). Same class of correction `docs/CONTRACT-sessions.md` §3.4 already had to make for the wlr pointer XML path. ## What it answered One run, 2026-10-04, against the live `/run/hypr-stream`: Hyprland 0.56.2, one output `Virtual-1` at 1280x720, two Chromium windows already on screen. The committed transcript is that run and nothing else — [`keyboard-probe-2026-10-04.txt`](keyboard-probe-2026-10-04.txt) — and every excerpt below is copied from it, with the line numbers to check it against. An earlier draft of this file claimed several reproductions and quoted a serial from a run it had not kept. If a claim here is not in that file, it is not evidence. The configuration the answers depend on, as the compositor reports it: ``` input:follow_mouse = 1 (set) input:follow_mouse_threshold = 0.0 (default) input:virtualkeyboard:release_pressed_on_close = 0 (default) input:repeat_rate = 25 (default) input:repeat_delay = 600 (default) input:kb_layout = us (default) ``` ### 1. The global — the gate the whole project hangs on **`zwp_virtual_keyboard_manager_v1` is present at version 1** (transcript line 71, answered on line 76). §6.7's `[RAN]` claim holds against the running binary. `wp_virtual_keyboard_v1` is not advertised, as both plans predicted. `zwlr_virtual_pointer_manager_v1` is at v2, so the driver's existing version-2 requirement is still met. The project continues. ### (a) Does a virtual-pointer warp move `wl_keyboard` focus? **One idle warp onto an unfocused window: NO.** It moved the cursor and nothing else. The keyboard focus change arrived only after a *later* `motion_absolute`, and it belongs to that motion rather than to the first. Transcript, lines 104–120, unedited: ``` box kb-probe-a at 0,0 size 1280x720 box kb-probe-b at 120,80 size 1040x560 focus at map time: kb-probe-b (expected kb-probe-b: it mapped last) (a1) target 0.0100,0.0100 (inside kb-probe-a only) (a2) target 0.0100,0.0140 — about 3px lower, so the FLOORED pixel changes. A second warp to the same point would return before mouseMoveUnified touched the delta, and would prove nothing. (a1) one warp after 0.8s of stillness (a1) -> wl_pointer.enter surface=kb-probe-a at 13,7 (a2) a second warp, to the (a2) target above (a2) -> modifiers depressed=0 latched=0 locked=0 group=0 (a2) -> leave surface=kb-probe-b (a2) -> enter surface=kb-probe-a serial=406 keys=[] (a2) -> modifiers depressed=0 latched=0 locked=0 group=0 (a2) -> configured surface=kb-probe-b 1040x560 (a2) -> configured surface=kb-probe-a 1280x720 gap between the two motion_absolute calls: 0.401s (under Hyprland's 0.5s delta window) a1_enter=no a2_enter=yes pointer_reached_kb-probe-a=yes ``` The sentence this supports, and no stronger one: **an idle `motion_absolute` onto unfocused `kb-probe-a` delivered `wl_pointer.enter` and no `wl_keyboard.enter`; `kb-probe-b`'s `leave` and `kb-probe-a`'s `enter` were observed only in the settle window after a later `motion_absolute` that stayed inside `kb-probe-a`.** Map-time focus was `kb-probe-b`, and the two boxes genuinely differ (`0,0 1280x720` against `120,80 1040x560`), so this is not the one-window false pass. It is **not** "the enter was one warp late", which is what an earlier draft of this file said. The mechanism is in `InputManager.cpp` at v0.56.2: `mouseMoveUnified` returns before it touches `m_mousePosDelta` when the floored pixel did not change; the delta is *set to* 0 when the previous movement was more than 0.5 s ago; and keyboard focus compares that delta against `input:follow_mouse_threshold`, which the options block above shows is `0.0` and unset. So the first warp contributed nothing to the delta, and the second warp's own non-zero delta is what focused. Two consequences the draft got wrong: - **A second warp to the same point is not the fix.** It returns early. (a2) moves about 3 px, deliberately, and the report prints both targets so a reader can see that it moved. - **"Immediately" was never measured.** The gap is 0.401 s, now printed, and it matters only because it is under the 0.5 s window. **`pointer acquire` is one warp** (`src/hhstreamd/manager.py`, the `_warp` in `pointer_acquire`), so the first key of a lease can be delivered to whatever was already focused. Neither plan permits building the fallback in Stages 1–2 (`docs/plans/2026-10-03-keyboard-input.md` §6 risk 1; the review's "Do not build it in Stage 1"), so Stages 1–2 do not, and the final report carries the objection. **Stage 3's enter subtest must not be written against acquire's single warp**, and it must not be made to pass by warping twice to the same bookmark. Two false passes this probe itself walked into, both worth carrying into the VM check: - `"enter surface=kb-probe-a" in line` also matches `wl_pointer.enter surface=kb-probe-a`, and an earlier version reported `a1_enter=yes` off a *pointer* event. The match is `startswith` now. - An earlier version used one window. A single mapped window is focused at map time, so it prints `enter` whatever the warp does. ### (b) Does destroying the virtual keyboard release a held key? **No release: `release_on_destroy=no`** (transcript line 131), measured with a second virtual keyboard keeping the seat's keyboard capability up so a release had somewhere to be delivered, and with nothing of ours having sent a key-up before `destroy`. `input:virtualkeyboard:release_pressed_on_close` is `0` and unset, which is the default the review read out of `ConfigValues.cpp`. **Read `mask_cleared=no` narrowly.** It says only that the post-destroy window contained no `modifiers` event. The held key was `KEY_A`, a letter, so the depressed mask was 0 for the whole run — **this is not a measurement of a non-zero mask surviving `destroy`**, and an earlier draft of this file claimed it was. `releasePressed` in `VirtualKeyboard.cpp` emits key-ups only and never a `modifiers`, so the source still says a mask would survive; it is simply not what this transcript shows. `release_all` sends `modifiers(0, 0, 0, 0)` for that reason, not because of this line. The confirming evidence is the *cleanup*, transcript lines 136–138: ``` cleanup -> uploaded keymap format=1 size=35572 cleanup -> key code=30 state=0 sym=a cleanup -> modifiers depressed=0 latched=0 locked=0 group=0 ``` `InputManager::onKeyboardKey` **drops** a release whose code is not in the seat's `m_pressed`. A `state=0` for code 30 that the client actually received, sent from a *brand new* virtual keyboard, therefore means 30 was still in that set after `destroy`. Had destroy released it, that cleanup key-up would have been dropped and nothing would have reached the client. One thing the transcript does **not** contain, and which this file used to cite: an earlier, unkept run whose first `wl_keyboard.enter` carried `keys=[42, 0, 0, 0]`. Every `enter` in the committed log is `keys=[]`. So this is worse than "a key stays down": the code stays in `m_pressed`, and `onKeyboardKey` also drops a *press* whose code is already there — the next driver's `key down` for it is ignored, and the key is dead until something sends a matching up. Handled in Stage 2 by `input:virtualkeyboard:release_pressed_on_close = true` in `nix/hyprland-conf.nix` (the review's change 4), with the explicit note that the setting releases keys and still does not clear the modifier mask — which is why `release_all` ends with `modifiers(0, 0, 0, 0)` on the clean path regardless. ### (c) Does Hyprland auto-repeat a held virtual key? **`press_count=1`, `repeat_info rate=25 delay=600`** (transcript lines 124–125). A key left down for `REPEAT_HOLD_S = 1.5` s — longer than the 600 ms delay, not shorter — produced exactly one `key code=30 state=1` and no `state=2`. A compositor repeating at 25 Hz after 600 ms would have added about twenty more lines in the remaining 0.9 s; it added none. `repeat_info` arrives at bind time, before the hold, and is printed next to the count because the review asked for both — not because the compositor repeated. This is **not** "`keyboard down` will not flood a text field", and reading it that way is the review's named false pass. The compositor does not repeat on the wire; it publishes a rate and the *client* repeats. A focused foot, GTK or Qt text field will insert characters from that one press until the key-up or the lease TTL (default 30 s). So `keyboard down` of a non-modifier warns unconditionally in the CLI help, and v1 has no repeat rate to offer because we do not generate the repeats. `zwp_virtual_keyboard_v1` has no `repeated` state and there is nothing to ask the compositor for.