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

187 lines
9.4 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# `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.