Files
hyprland-headless-stream-pl…/tests/README-keyboard-probe.md
T
HermenixandClaude Opus 5 19e484b388 Stage 0: measure the compositor instead of reading its source
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
2026-10-04 03:21:14 +00:00

9.4 KiB
Raw 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.

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.