# `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`. 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 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. Reproduced across six runs. Full transcript, verbatim: [`keyboard-probe-2026-10-04.txt`](keyboard-probe-2026-10-04.txt). 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.** §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: NO. A second warp immediately after: YES.** Exactly what the review's read of `InputManager::onMouseWarp` predicted, and the reason it insisted (a1) and (a2) be measured separately. ``` box kb-probe-a at 0,0 size 1280x720 <- fullscreen, unfocused box kb-probe-b at 120,80 size 1040x560 <- focused: it mapped last chosen warp target 0.0100,0.0100 (inside kb-probe-a only) (a1) one warp after 0.8s of stillness (a1) -> wl_pointer.enter surface=kb-probe-a at 13,7 <- cursor arrived <- and nothing else (a2) a second warp, immediately, still inside the same window (a2) -> leave surface=kb-probe-b (a2) -> enter surface=kb-probe-a serial=336 keys=[] <- focus, one warp late a1_enter=no a2_enter=yes pointer_reached_kb-probe-a=yes ``` The consequence is the headline risk of this whole feature: **`pointer acquire` is one warp**, so the first key of a lease can be delivered to whatever was focused before. 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 assertion must not be written against a single warp. Worth recording about this probe, because it is the review's own category of false pass and it happened here: an earlier version matched the keyboard `enter` line with `"enter surface=kb-probe-a" in line`, which also matches `wl_pointer.enter surface=kb-probe-a`, and reported `a1_enter=yes`. The match is `startswith` now. ### (b) Does destroying the virtual keyboard release a held key? **NO — `release_on_destroy=no`, `mask_cleared=no`**, measured with a second virtual keyboard keeping the seat's keyboard capability up, so that a release had somewhere to be delivered. `input:virtualkeyboard:release_pressed_on_close` is `0` and unset, which is the default the review read out of `ConfigValues.cpp`. Corroborated by accident on an earlier run, which is the strongest form the evidence takes: a run that exited with `Shift_L` down and no spare device left the key down, and the *next* run's very first `wl_keyboard.enter` carried `keys=[42, 0, 0, 0]` — evdev 42 is `KEY_LEFTSHIFT`. The key outlived the process that pressed it. Sending the release from a different virtual keyboard cleared it, which is why the probe now ends with a fresh keyboard, a key-up and a zeroed mask (the review's step 7). This is worse than "a key stays down": `InputManager::onKeyboardKey` drops a press whose code is already in the seat's `m_pressed`, so after a `kill -9` the next driver's `key down` for that code 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`.** A key left down for 1.5 s — longer than the 600 ms delay — produced exactly one `wl_keyboard.key … state=1`. 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.