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
This commit is contained in:
HermenixandClaude Opus 5 committed 2026-10-04 03:21:14 +00:00
1 parent d07a1fd045
commit 19e484b388
3 files changed
+1333

No files matched your search

+186
View File
@@ -0,0 +1,186 @@
# `keyboard_probe.py` — Stage 0 of the keyboard plan
Stage 0 of [`docs/plans/2026-10-03-keyboard-input.md`](../docs/plans/2026-10-03-keyboard-input.md),
written to the probe spec in
[`docs/plans/2026-10-04-keyboard-verification.md`](../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":
```bash
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** |
```bash
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`](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.
+136
View File
@@ -0,0 +1,136 @@
keyboard_probe.py, 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. Verbatim; nothing edited.
=== 1. globals on this compositor ===
global ext_background_effect_manager_v1 v1
global ext_data_control_manager_v1 v1
global ext_foreign_toplevel_image_capture_source_manager_v1 v1
global ext_foreign_toplevel_list_v1 v1
global ext_idle_notifier_v1 v2
global ext_image_copy_capture_manager_v1 v1
global ext_output_image_capture_source_manager_v1 v1
global ext_session_lock_manager_v1 v1
global ext_workspace_manager_v1 v1
global hyprland_ctm_control_manager_v1 v2
global hyprland_focus_grab_manager_v1 v1
global hyprland_global_shortcuts_manager_v1 v1
global hyprland_input_capture_manager_v1 v1
global hyprland_lock_notifier_v1 v1
global hyprland_surface_manager_v1 v2
global hyprland_toplevel_export_manager_v1 v2
global hyprland_toplevel_mapping_manager_v1 v1
global org_kde_kwin_server_decoration_manager v1
global vicinae_hotkey_manager_v1 v1
global wl_compositor v6
global wl_data_device_manager v3
global wl_drm v2
global wl_output v4
global wl_seat v9
global wl_shm v2
global wl_subcompositor v1
global wp_alpha_modifier_v1 v1
global wp_color_manager_v1 v3
global wp_commit_timing_manager_v1 v1
global wp_content_type_manager_v1 v1
global wp_cursor_shape_manager_v1 v2
global wp_drm_lease_device_v1 v1
global wp_fifo_manager_v1 v1
global wp_fractional_scale_manager_v1 v1
global wp_pointer_warp_v1 v1
global wp_presentation v2
global wp_security_context_manager_v1 v1
global wp_single_pixel_buffer_manager_v1 v1
global wp_tearing_control_manager_v1 v1
global wp_viewporter v1
global xdg_activation_v1 v1
global xdg_system_bell_v1 v1
global xdg_toplevel_tag_manager_v1 v1
global xdg_wm_base v7
global xdg_wm_dialog_v1 v1
global xwayland_shell_v1 v1
global zwlr_data_control_manager_v1 v2
global zwlr_foreign_toplevel_manager_v1 v3
global zwlr_gamma_control_manager_v1 v1
global zwlr_layer_shell_v1 v5
global zwlr_output_manager_v1 v4
global zwlr_output_power_manager_v1 v1
global zwlr_screencopy_manager_v1 v3
global zwlr_virtual_pointer_manager_v1 v2
global zwp_idle_inhibit_manager_v1 v1
global zwp_input_method_manager_v2 v1
global zwp_keyboard_shortcuts_inhibit_manager_v1 v1
global zwp_linux_dmabuf_v1 v5
global zwp_pointer_constraints_v1 v1
global zwp_pointer_gestures_v1 v3
global zwp_primary_selection_device_manager_v1 v1
global zwp_relative_pointer_manager_v1 v1
global zwp_tablet_manager_v2 v1
global zwp_text_input_manager_v1 v1
global zwp_text_input_manager_v3 v1
global zwp_virtual_keyboard_manager_v1 v1
global zxdg_decoration_manager_v1 v2
global zxdg_exporter_v2 v1
global zxdg_importer_v2 v1
global zxdg_output_manager_v1 v3
ANSWER 1: zwp_virtual_keyboard_manager_v1 is present at version 1.
zwlr_virtual_pointer_manager_v1 v2 (needed for (a)).
setup -> seat capabilities=1
setup -> seat capabilities=3
setup -> uploaded keymap format=1 size=35572
setup -> wl_keyboard.keymap format=1 bytes=35572 symbols=xkb_symbols "pc_us_inet(evdev)" {
setup -> repeat_info rate=25 delay=600
setup -> configured surface=kb-probe-a 640x360
setup -> enter surface=kb-probe-a serial=357 keys=[]
setup -> modifiers depressed=0 latched=0 locked=0 group=0
setup -> configured surface=kb-probe-a 1280x720
setup -> configured surface=kb-probe-b 640x360
setup -> modifiers depressed=0 latched=0 locked=0 group=0
setup -> leave surface=kb-probe-a
setup -> enter surface=kb-probe-b serial=365 keys=[]
setup -> modifiers depressed=0 latched=0 locked=0 group=0
setup -> configured surface=kb-probe-b 1040x560
setup -> configured surface=kb-probe-a 1280x720
=== (a) does a virtual-pointer warp move wl_keyboard focus? ===
options this measurement depends on:
input:follow_mouse = {"int": 1, "option": "input:follow_mouse", "set": true}
input:follow_mouse_threshold = {"float": 0.0, "option": "input:follow_mouse_threshold", "set": false}
input:virtualkeyboard:release_pressed_on_close = {"int": 0, "option": "input:virtualkeyboard:release_pressed_on_close", "set": false}
input:repeat_rate = {"int": 25, "option": "input:repeat_rate", "set": false}
input:repeat_delay = {"int": 600, "option": "input:repeat_delay", "set": false}
input:kb_layout = {"option": "input:kb_layout", "set": false, "str": "us"}
output Virtual-1 mode 1280x720
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)
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
(a2) a second warp, immediately, still inside the same window
(a2) -> modifiers depressed=0 latched=0 locked=0 group=0
(a2) -> leave surface=kb-probe-b
(a2) -> enter surface=kb-probe-a serial=371 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
a1_enter=no a2_enter=yes pointer_reached_kb-probe-a=yes
ANSWER (a): one idle warp did NOT deliver enter; the SECOND warp did. Exactly what the review predicted. A lease's `acquire` is one warp, so the first key of a lease can land in the previously focused window: Stage 4 (or a second warp) is needed, and Stage 3's enter assertion must not be written against a single warp.
=== (c) is one held virtual key one wl_keyboard.key? ===
key code=30 state=1 sym=a
press_count=1 repeat_info=(25, 600)
ANSWER (c): press_count=1 — the compositor does not repeat on the wire; it published repeat_info (25, 600) and the CLIENT repeats. This is NOT 'keyboard down will not flood a text field': foot/GTK/Qt will insert characters from this one press until the key-up or the lease TTL. The help text must warn unconditionally.
(key code=30 deliberately left down, for (b))
=== (b) does destroying the virtual keyboard release a held key? ===
spare -> uploaded keymap format=1 size=35572
release_on_destroy=no mask_cleared=no
(compare with input:virtualkeyboard:release_pressed_on_close, printed above)
ANSWER (b): NO — destroy delivered no release, with another keyboard keeping the seat's capability up. So a driver killed with -9 leaves evdev 30 in the seat's m_pressed, and InputManager::onKeyboardKey then DROPS the next press of that code: the key is dead until something sends a matching up. _lift_everything is the only guard on the clean path, and SIGKILL skips it.
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
cleanup=sent
Done. Nothing here touched the broker, the lease or any session.
File diff suppressed because it is too large. Load diff