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:
1 parent
d07a1fd045
commit
19e484b388
3 files changed
+1333
No files matched your search
@@ -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.
|
||||
@@ -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
Reference in new issue
Block a user