Files
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

14 KiB
Raw Permalink Blame History

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.capabilities does not include keyboard until a virtual one exists (the setup block goes 1 then 3), 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 line also matches wl_pointer.enter surface=kb-probe-a, and an earlier version reported a1_enter=yes off a pointer event. The match is startswith now.
  • An earlier version used one window. A single mapped window is focused at map time, so it prints enter whatever 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.