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
9.4 KiB
keyboard_probe.py — Stage 0 of the keyboard plan
Stage 0 of docs/plans/2026-10-03-keyboard-input.md,
written to the probe spec in
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":
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 |
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.
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.