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
261 lines
14 KiB
Markdown
261 lines
14 KiB
Markdown
# `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.
|