Files
hyprland-headless-stream-pl…/docs/reviews/2026-10-04-stage0-review.md
T
HermenixandClaude Opus 5 b1f2744cf0 Stage 0 review: correct what the log does not say, and edit the plan
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
2026-10-04 03:46:53 +00:00

19 KiB
Raw Blame History

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

  1. High. The (a) write-up states a causality the log does not have. README :114 and :129, and the 19e484b message, read as "warping onto the unfocused window delivered keyboard enter, one warp late." Log 108–113 say the landing warp delivered wl_pointer.enter only, 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 leave serial=336 in the file.

  2. High. d07a1fd did not fold the eight changes into the plan. git diff 14b3f69 HEAD -- docs/plans/2026-10-03-keyboard-input.md is empty. The commit adds docs/plans/2026-10-04-keyboard-verification.md and 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 of 2026-10-03-keyboard-input.md stating that the eight rows in the verification doc's "Changes required before code" table supersede the plan where they differ. Not done here.

  3. Medium. mask_cleared=no is reported as a measurement of a held mask. README :150-154. The mask was 0 the whole time (log 111, 114; no modifiers request 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 unlogged keys=[42, 0, 0, 0] run.

  4. 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 second motion_absolute of the same point is not this result. Printing the second normalised point from question_focus would make the next transcript show it.

  5. 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_absolute calls. Not worth a re-run by itself.

  6. 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.enter on pointer 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, or focuswindow. 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 down warning on this probe having seen repeats. It saw one wl_keyboard.key and a repeat_info of 25/600. The warning stays unconditional. Log 123 already says this; the plan at 2026-10-03-keyboard-input.md:234 still says the opposite ("if it does, the help text says so").
  • Do not cite mask_cleared=no as proof a held Shift survives destroy. Keep sending modifiers(0,0,0,0) because releasePressed never 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 are keys=[]. The cleanup state=0 (log 132) is the poison evidence, and it is for code 30 after an explicit destroy.
  • Do not expect the scanner to emit keymap_format or key_state. The Hyprland XML this probe used names both and defines neither (protocols/virtual-keyboard-unstable-v1.xml in the v0.56.2 tree: the request text says "keymap_format enumeration" / "key_state enumeration"; the only enums in the file are error). The constants in keyboard_probe.py:89-95 are the right workaround. The symbols line to match later is xkb_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.