The Stage 0 review (docs/reviews/2026-10-04-stage0-review.md, verdict
yes-with-fixes) found that the measurements were sound and the write-up
was not. All four of its high and medium defects, verified against the
committed transcript before fixing:
(1) 19e484b's README claimed a verbatim excerpt and printed serial=336
while the run's (a2) enter was serial 371. It also claimed six
reproductions with one transcript, and cited a `keys=[42, 0, 0, 0]`
enter from a run whose log was never kept -- every enter in the
committed file is `keys=[]`. The excerpt is now copied from the log
with line numbers to check it against, the reproduction claim is
gone, and the Shift observation is named as not-in-this-log.
(2) THE (a) CONCLUSION WAS WRONG, and it is the one that matters. The
first idle warp onto the unfocused window gave wl_pointer.enter and
NO keyboard enter; the leave/enter arrived on the LATER motion. So
it is not "enter, one warp late" -- the first warp's delta is set to
0, the threshold is 0.0, and the second motion's own non-zero delta
is what focused. Two corollaries the old text got backwards: a
second warp to the SAME point returns before mouseMoveUnified
touches the delta and proves nothing, and waiting longer does not
help. The probe now prints both targets and the measured gap
(0.401s) instead of hardcoding the word "immediately", and its
ANSWER string says the mechanism.
Consequence, now stated everywhere it belongs: `pointer acquire` is
one warp, so the first key of a lease can land on whatever was
already focused. Stage 3's enter subtest must not be designed from
acquire's single warp, and must not be made to pass by warping twice
to the same bookmark.
(3) d07a1fd did not edit the plan -- `git diff 14b3f69 HEAD --
docs/plans/2026-10-03-keyboard-input.md` was empty, so anyone told
to follow the plan still had the contradicted text. All eight
pre-code changes are now folded into that file, each marked
[SUPERSEDED], plus a banner at the top. Changes 5 and 7 were the
ones that had survived intact in four places: the [keyboard] TOML
table (dropped -- the broker reads that file and the driver is a
different unit, so it would have been a setting with no effect) and
"if it repeats, the help text says so" (now unconditional). The four
closed open questions and the stage table are updated with what
Stage 0 measured, including that Stage 4 is no longer contingent.
(4) mask_cleared=no was reported as a held mask surviving destroy. The
held key was a letter, so the mask was 0 throughout; the README now
says destroy emitted no key-up and no modifiers event, and that the
reason release_all still sends modifiers(0,0,0,0) is
VirtualKeyboard.cpp's releasePressed, not this line. The real
poison evidence is promoted: onKeyboardKey drops a release whose
code is not in m_pressed, so the cleanup's `key code=30 state=0`
arriving from a brand-new keyboard proves 30 was still in that set.
The transcript is a fresh run of the corrected probe, so the file and
the claims about it agree line for line.
19e484b's message carries defect (2)'s wrong causality. It is corrected
here rather than by rewriting that commit, so the hashes the reviewer
cites keep resolving.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GhNPM6rGcuzxocM1nATnuM
14 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.
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.capabilitiesdoes not includekeyboarduntil a virtual one exists (the setup block goes1then3), 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 |
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 — 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 linealso matcheswl_pointer.enter surface=kb-probe-a, and an earlier version reporteda1_enter=yesoff a pointer event. The match isstartswithnow.- An earlier version used one window. A single mapped window is focused at map
time, so it prints
enterwhatever 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.