A throwaway client against the live /run/hypr-stream that answers the
four open questions. It touches no broker, no lease and no session; it
opens two windows of its own and moves the one cursor, because keyboard
focus cannot be measured without doing both, and it refuses to send a
key until it sees wl_keyboard.enter on a surface it owns.
What it found, with the transcript beside it:
1 zwp_virtual_keyboard_manager_v1 is present at version 1. The gate
the plan hangs on holds against the running binary, not just
against §6.7's [RAN] claim.
a ONE IDLE WARP DOES NOT MOVE KEYBOARD FOCUS. A second warp
immediately after does. Measured with an unfocused fullscreen
window under a focused floating one, warping into the margin that
belongs to the first alone -- and `pointer acquire` is one warp, so
the first key of a lease can land in the previously focused
window. Neither plan permits building the fallback here, so this
branch does not; it is the objection in the final report.
b destroy with a key down releases nothing and clears no mask
(release_pressed_on_close is 0 and unset). An earlier run proved it
by accident: it exited with Shift_L down and the NEXT run's first
enter carried keys=[42, 0, 0, 0].
c one held key is one wl_keyboard.key, with repeat_info 25/600. The
flood is the client's repeat, not ours -- which is why `down` warns
unconditionally rather than only if the probe saw repeats.
The XML both plans name does not exist in this nixpkgs: not in
wayland-protocols 1.49, not in wlr-protocols, not in wlroots. Hyprland's
own copy is the only one, so that is what is used -- and because it
names keymap_format and key_state without defining them, both are
written down as cited constants instead of read off an enum.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GhNPM6rGcuzxocM1nATnuM
187 lines
9.4 KiB
Markdown
187 lines
9.4 KiB
Markdown
# `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.
|