Files
hyprland-headless-stream-pl…/tests/README-keyboard-probe.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

261 lines
14 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`.
### 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** |
```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
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`](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.