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
19 KiB
Stage 0 review — keyboard probe
Reviewed d07a1fd (the plan fold-in) and 19e484b (the probe, its README, and tests/keyboard-probe-2026-10-04.txt) against §B1 of docs/plans/2026-10-04-keyboard-verification.md. The three probe files are that commit, not an untracked add-on. Dirty Stage 1 files in the worktree were not reviewed and were not touched. The probe was not re-run: this environment has no HYPRLAND_INSTANCE_SIGNATURE, so the judgement is the committed transcript read against the script that prints those answer strings.
Verdict
Yes-with-fixes. The run measured the gate and questions (a1), (b)'s key, and (c). The write-up then says things the log does not say, and d07a1fd did not edit the plan. Do not design Stage 3 from the README's (a) excerpt or from its mask sentence. The raw log, read with the script, is usable.
What the evidence actually shows
The script is the B1 sequence with three real deviations and one hole. It is not a one-window probe, it does not call hyprctl dispatch, it refuses a runtime directory that does not contain exactly one wayland-* (tests/keyboard_probe.py:378-389), it dumps every global as global <name> v<version> (:759-760) and returns 2 when zwp_virtual_keyboard_manager_v1 is missing or not version 1 (:761-770). sym is xkb_state_key_get_one_sym(code+8) on a state built from the keymap fd, updated with update_mask (:575-609, :627-632). Cleanup sends key(30, released) and modifiers(0,…) on a new virtual keyboard and prints cleanup=sent (:940-945). Deviations, all visible in the log: the keymap is uploaded before the windows rather than after (a); the idle wait is 0.8 s not 0.6 s; (a2) is 0.4 s after (a1), not immediate.
Gate
Log lines 6–75 are the registry. Line 71 is global zwp_virtual_keyboard_manager_v1 v1. No wp_virtual_keyboard_v1 line. Line 76: ANSWER 1: zwp_virtual_keyboard_manager_v1 is present at version 1. Line 59: zwlr_virtual_pointer_manager_v1 v2. That is the gate. The project continues.
(a)
The log does not prove "a warp onto an unfocused window delivered wl_keyboard.enter." That sentence is the natural reading of the README's annotation "focus, one warp late" (tests/README-keyboard-probe.md:129) and of the commit message, which hangs both results on "warping into the margin that belongs to the first alone." The warp into that margin is (a1). It did not deliver keyboard enter.
What the log actually contains, in order:
108| (a1) one warp after 0.8s of stillness
109| (a1) -> wl_pointer.enter surface=kb-probe-a at 13,7
110| (a2) a second warp, immediately, still inside the same window
111| (a2) -> modifiers depressed=0 latched=0 locked=0 group=0
112| (a2) -> leave surface=kb-probe-b
113| (a2) -> enter surface=kb-probe-a serial=371 keys=[]
117| a1_enter=no a2_enter=yes pointer_reached_kb-probe-a=yes
(a1) is the warp onto unfocused kb-probe-a. The only event in its bucket is wl_pointer.enter at 13,7, which is the chosen point: target 0.0100,0.0100 (log 107) on a 1280×720 output is about (12.8, 7.2), and B's box starts at 120,80 (log 105), so the point is inside A only. No enter surface=kb-probe-a keyboard line in that bucket. a1_enter=no is true, and the startswith test (keyboard_probe.py:820-825) is what keeps wl_pointer.enter from counting. Map-time focus was B (log 89–90 and 106), so this is not the one-window false pass.
The keyboard leave/enter are the next bucket. That bucket is the second motion_absolute (keyboard_probe.py:816: same x, y plus 0.004), sent while the pointer was already on A. There is no second wl_pointer.enter, because the probe does not listen for wl_pointer.motion and pointer focus did not change. So the leave/enter arrived on the motion after the warp onto the window, not on the warp onto the window.
The sentence the log supports is: an idle motion_absolute onto unfocused kb-probe-a delivered wl_pointer.enter and no wl_keyboard.enter; wl_keyboard.leave of B and wl_keyboard.enter of A (serial 371, keys=[]) were observed only in the settle window after a later motion_absolute that stayed inside A.
Line 118's narrower claim — "one idle warp did NOT deliver enter; the SECOND warp did" — matches the buckets, with two caveats the file does not write down. The second request is not "immediate": question_focus pumps SETTLE_S (0.4 s, keyboard_probe.py:124 and :812) and prints the (a1) lines before sending it, and the banner hardcodes the word (:815). And it is not a repeat of the same point. In the v0.56.2 InputManager.cpp on this machine, mouseMoveUnified returns immediately when the floored pixel did not change (:239-240), before it adds to m_mousePosDelta (:253-256). Keyboard focus is that delta compared with follow_mouse_threshold (:711-715). Log 98 says the threshold is 0 and unset, so any non-zero floored distance inside 0.5 s focuses, and a second warp to the same floored pixel does nothing. 0.004 of 720 px is about 3 px, so this nudge cleared that bar. The log never prints the second point, so a reader cannot see that it moved.
pointer acquire is one _warp (src/hhstreamd/manager.py:1620). The consequence that the first key of a lease can hit whatever was already focused follows from (a1) alone, and (a1) supports it. It does not follow from "the landing warp delivered enter, one warp late."
The README excerpt is not the log. It claims a verbatim transcript (README-keyboard-probe.md:90-91) and then prints serial=336 (:129). This run's (a2) enter is serial 371 (log 113). Setup enters are 357 and 365 (log 84, 90), so 336 cannot be this run's focus change. The excerpt also drops log 111 (a modifiers line before leave) and the two configured lines that follow the enter (log 115–116). "Reproduced across six runs" (README:89) has one transcript.
(b)
No release: the log shows it. Mask not cleared: the log does not show what that sentence means.
127| spare -> uploaded keymap format=1 size=35572
128| release_on_destroy=no mask_cleared=no
131| cleanup -> uploaded keymap format=1 size=35572
132| cleanup -> key code=30 state=0 sym=a
133| cleanup -> modifiers depressed=0 latched=0 locked=0 group=0
There is no after destroy -> line. The post-destroy pump is 1.0 s (keyboard_probe.py:915-916) and it recorded nothing: no key code=30 state=0, no modifiers. The script did not send a key-up or a modifiers before destroy (:912). The release it did send is after the verdict, labeled cleanup ->. B1's named false pass (counting step 7, or releasing before destroy) is not this log.
The spare keyboard does not weaken the "no release" half. It is created so the seat still has a keyboard (:904-910). Log 78–79 show why that matters: capabilities go 1 (pointer) then 3 (pointer|keyboard) only once a virtual keyboard exists, and the seat has no libinput keyboard. The spare never pressed code 30 — its only line is the local uploaded keymap. shareKeyFromAllKBs swallows a release only when some other sharing keyboard still has that code down (InputManager.cpp:1891-1911). The spare did not. Silence here is not "the release was delivered to a keyboard we stopped listening on."
The stronger evidence is log 132, which the ANSWER paragraph does not cite. onKeyboardKey drops a release whose code is not in the seat m_pressed (InputManager.cpp:1669-1670). A state=0 for code 30 from a new keyboard means 30 was still in that set after destroy. If destroy had released it, the cleanup up would have been dropped and the client would not have seen state=0.
mask_cleared=no is a different predicate than the README's sentence. The code sets it when the post-destroy bucket contains modifiers depressed=0 (keyboard_probe.py:918-919). The bucket is empty, so the flag is no. The depressed mask was already 0: the last modifiers lines are log 111 and 114, and the probe never sent modifiers with a non-zero mask. The held key is KEY_A (30), not Shift. "Destroy did not emit a modifiers event" is what was measured. "A non-zero mask survived destroy" was not. releasePressed emits key-ups only (VirtualKeyboard.cpp:125-135), so the source still says a mask would survive, but this run is not that measurement. Log 99 supports the option half only: input:virtualkeyboard:release_pressed_on_close is {"int": 0, … "set": false}.
The Shift story (README:156-161, keys=[42, 0, 0, 0]) is not in this transcript. Every enter here has keys=[] (log 84, 90, 113). Do not treat the zeros, or the claim that a key outlived the process, as data from this file.
The ANSWER's kill -9 sentence is an inference. The transcript is an explicit destroy request. In this tree both that request and client disconnect call the same CVirtualKeyboardV1Resource::destroy (VirtualKeyboard.cpp:38-39, :137-140), which consults the option. Fair inference, not a second experiment.
(c)
The log shows exactly one press, and neither the spare, the window, nor repeat_info weakens that count.
82| setup -> repeat_info rate=25 delay=600
121| key code=30 state=1 sym=a
122| press_count=1 repeat_info=(25, 600)
press_count counts state=1 or state=2 for code 30 inside the hold pump (keyboard_probe.py:875-879). One line, state 1, no state 2. The hold is REPEAT_HOLD_S = 1.5 (:120), which is longer than the 600 ms delay on log 101, not shorter. A compositor that repeated at 25 Hz after 600 ms would have put on the order of twenty more key lines in the remaining 0.9 s. It put none. repeat_info was delivered at bind time (log 82), before the hold, which is when Hyprland sends it; printing the stored tuple next to the count is what B1 asked. It does not mean the compositor also repeated. The spare keyboard is created in question_destroy, after this section, so it is not in the (c) setup. The ANSWER text (log 123) already refuses the false pass: press_count=1 is not "a text field will not flood." That part of the file is right, and it is the reading Stage 1 should keep.
sym=a is from the forwarded keymap, not a table. Log 80–81: uploaded format=1 size=35572, and wl_keyboard.keymap format=1 bytes=35572 symbols=xkb_symbols "pc_us_inet(evdev)". The sizes match, which is consistent with the NUL-inclusive memfd (keyboard_probe.py:312-326) being what the compositor mapped. The symbols snippet is not the layout string us.
Defects
-
High. The (a) write-up states a causality the log does not have. README
:114and:129, and the19e484bmessage, read as "warping onto the unfocused window delivered keyboard enter, one warp late." Log 108–113 say the landing warp deliveredwl_pointer.enteronly, and leave/enter came on the next motion. "One warp late" is the wrong mechanism: the first warp's delta is set to 0 (InputManager.cpp:255-256); the enter belongs to the second motion's non-zero delta, not to a delayed effect of the first. Cheapest fix: replace the README excerpt with log 108–117 unchanged, and replace the annotation with the sentence in the (a) section above. Do not leaveserial=336in the file. -
High.
d07a1fddid not fold the eight changes into the plan.git diff 14b3f69 HEAD -- docs/plans/2026-10-03-keyboard-input.mdis empty. The commit addsdocs/plans/2026-10-04-keyboard-verification.mdand nothing else. The commit message is an accurate list of what that review says, and the review text itself is not softened. The plan text is unchanged, so anyone told to follow the plan (the untracked brief says that, and it repeats exit codes 8/9/2/10) still has the contradicted text. Cheapest fix: a banner at the top of2026-10-03-keyboard-input.mdstating that the eight rows in the verification doc's "Changes required before code" table supersede the plan where they differ. Not done here. -
Medium.
mask_cleared=nois reported as a measurement of a held mask. README:150-154. The mask was 0 the whole time (log 111, 114; nomodifiersrequest before destroy). Cheapest fix: one sentence in the README — destroy emitted no key-up and no modifiers event; a non-zero mask was not held, so this run does not show one surviving. Do not re-run unless Stage 2 wants a transcript of Shift specifically. Do not cite the unloggedkeys=[42, 0, 0, 0]run. -
Medium. "A second warp" is underspecified in a way Stage 3 will copy. The report never says the second point differed, and the same floored pixel returns before the focus test (
InputManager.cpp:239-240). Cheapest fix: in the README, say (a2) moved about 3 px and that a secondmotion_absoluteof the same point is not this result. Printing the second normalised point fromquestion_focuswould make the next transcript show it. -
Low. "Immediately" is hardcoded, and the gap is not logged. 0.4 s plus the time to print (a1) is still under Hyprland's 0.5 s window, and the fact that (a2) focused is consistent with that. The word in log 110 is not a measurement. Cheapest fix: print the monotonic gap between the two
motion_absolutecalls. Not worth a re-run by itself. -
Low. Claims with no transcript. "Six runs" (README
:89) and the Shift enter (README:156-161). Cheapest fix: delete both, or attach the log. The committed transcript does not contain them.
Not defects: committing the probe (B1 said not to; the commissioning brief said to; the README says so); uploading the keymap before (a) (log 78–80: no keyboard capability until a virtual keyboard exists, so the listener could not have seen enter otherwise); idle 0.8 s instead of 0.6 s; fullscreen A so the two boxes are not the same 1040×560 (log 104–105 shows they were not); the spare keyboard, for the reason under (b).
What Stage 1 must not build on
- Do not assert
wl_keyboard.enteronpointer acquire. Acquire is one warp. (a1) did not enter. Stage 3's enter subtest stays red until a later motion that changes the floored pixel, orfocuswindow. Do not "fix" it by warping twice to the same bookmark. - Do not read "one warp late" as "the enter is delayed, so wait longer." The (a1) bucket was 0.4 s and contained the pointer enter. The keyboard enter was a different request.
- Do not gate the
keyboard downwarning on this probe having seen repeats. It saw onewl_keyboard.keyand arepeat_infoof 25/600. The warning stays unconditional. Log 123 already says this; the plan at2026-10-03-keyboard-input.md:234still says the opposite ("if it does, the help text says so"). - Do not cite
mask_cleared=noas proof a held Shift survivesdestroy. Keep sendingmodifiers(0,0,0,0)becausereleasePressednever emits modifiers, not because this log held a mask. - Do not treat
keys=[42, 0, 0, 0]as a measured poison. This transcript's enters arekeys=[]. The cleanupstate=0(log 132) is the poison evidence, and it is for code 30 after an explicitdestroy. - Do not expect the scanner to emit
keymap_formatorkey_state. The Hyprland XML this probe used names both and defines neither (protocols/virtual-keyboard-unstable-v1.xmlin the v0.56.2 tree: the request text says "keymap_format enumeration" / "key_state enumeration"; the only enums in the file areerror). The constants inkeyboard_probe.py:89-95are the right workaround. The symbols line to match later isxkb_symbols "pc_us_inet(evdev)", not the bare layout name. - Do not implement exit 2, the NUL, or the layout path from the 2026-10-03 plan text. Those paragraphs were not updated. See carried objections.
Carried objections
d07a1fd preserved the eight pre-code changes intact inside the verification doc and dropped them from the plan. Nothing in the eight was rewritten into something unimplementable. Where the plan still disagrees:
| # | Still binding, from the verification doc :192-201 |
Plan text that was not changed |
|---|---|---|
| 1 | Broker checks shape and the 4096 cap. A driver token for a bad keysym or character maps to invalid_argument (exit 2). Missing global stays driver_refused (exit 10). |
:61 still says exit 2 for a bad keysym, which _drive turns into 10. |
| 2 | Keymap size includes the trailing NUL. format = 1. time is _now_ms(). |
:25 still says "memfd of an XKB text keymap" and never says size == strlen + 1. |
| 3 | release_all no-ops its key half when no virtual keyboard exists, and ends with modifiers(0,0,0,0) when a mask was touched. Also one modifiers(0,…) after the initial upload. |
Not stated. |
| 4 | input:virtualkeyboard:release_pressed_on_close = true in nix/hyprland-conf.nix. The true setting still does not clear the mask. |
:233 still calls destroy-while-held unverified and does not set the option. This run confirms the default is 0 and that explicit destroy releases nothing. |
| 5 | Layout is --xkb-layout on the pointer unit. The driver rejects , before xkb_keymap_new_from_names. A [keyboard] table in the broker TOML is not the upload. |
:111, :115, :176, :208 still emit and test [keyboard] the way [pointer] is emitted. |
| 6 | The modifier-keysym set is written down. The resolver returns (evdev, mask) for any level. key / type do not call _aimed(). |
:189 still has the mask-vs-Shift decision and no keysym set. |
| 7 | Stage 0 expectations as B1 wrote them. keyboard down warns unconditionally. Two windows, or the enter result is a false pass. |
:234 and :253 are still the vague originals. The probe did use two windows; the unconditional warning is the right reading of (c). |
| 8 | Acquire's stderr says keyboard verbs refresh the TTL. Rejected text and driver logs carry an index, not the string. |
Not stated. |
Objection 4 of the verification doc (do not vendor Hyprland's XML; use wayland-protocols unstable/virtual-keyboard/…) is the one item this stage showed is not implementable on this nixpkgs. The protocol's wayland-protocols MR never landed; the file the review names is not where the README looked, and the Hyprland copy is the one the probe compiled. Carry the review's actual reason — the copy does not define the enums — not the path. Switching later, if a nixpkgs grows the file, is a one-line change and does not move the integers.
Unchanged and confirmed, so Stage 1 should not reopen them: zwp_virtual_keyboard_v1 version 1 on the running compositor; no wp_virtual_keyboard_v1; one idle warp does not move keyboard focus under follow_mouse = 1 and threshold 0; do not build dispatch focuswindow in Stage 1.
Stage 1: implement from the eight rows in docs/plans/2026-10-04-keyboard-verification.md, not from the unedited 2026-10-03 plan; do not assert wl_keyboard.enter on acquire's single warp, do not treat a second warp to the same point as the fix, and do not cite mask_cleared=no as a held-mask result.