diff --git a/docs/plans/2026-10-04-keyboard-verification.md b/docs/plans/2026-10-04-keyboard-verification.md new file mode 100644 index 0000000..b15b9aa --- /dev/null +++ b/docs/plans/2026-10-04-keyboard-verification.md @@ -0,0 +1,347 @@ +# Keyboard plan — verification and tests + +Adversarial check of `docs/plans/2026-10-03-keyboard-input.md` (commit `14b3f69` on `feat/keyboard-input`; that file is not in this checkout). Source citations are from this tree. `git diff 14b3f69 HEAD -- src nix tests checks docs/CONTRACT-sessions.md docs/PLAN-workspaces-and-pointer.md` is empty, so the pointer/broker code the plan describes is the code reviewed here. + +Compositor claims below are from the Hyprland **v0.56.2** tree `PLAN-workspaces-and-pointer.md` says it measured (not from a registry dump on `/run/hypr-stream`). Stage 0 still has to confirm the running binary. Until it does, treat the source as the prior, not as a pass. + +**Bet, up front:** do not implement the plan as written. The shape is right (same driver, same lease, `zwp_virtual_keyboard_v1`, names on our JSON, evdev only on the Wayland `key` request, mask rather than a synthetic Shift key). Five plan edits are load-bearing and cheap only before Stage 1: the exit-2 vs `driver_refused` contradiction, NUL included in the keymap `size`, `release_pressed_on_close` (default is off, and destroy does not clear the modifier mask), focus is not a coin-flip, and the layout option reaches the keymap only via the pointer unit's argv. Detail below. + +--- + +## Layout option (operator decision, not re-litigated) + +The layout is a NixOS option on the pointer unit's command line. It is not a broker TOML key. `[pointer]` is read by `hhstreamd` (`policy.py` `settings_from_dict`, `__main__.py` around the `load_settings` call) for lease numbers only. The driver is a different unit (`nix/module.nix` `systemd.services.hhstream-pointer`) and never sees that file. Emitting `[keyboard]` "the way `[pointer]` is emitted" (plan §2 file table) does not upload a keymap. + +| | | +| --- | --- | +| Attribute | `services.hyprland-headless-stream.sessions.keyboard.layout` | +| Type | `lib.types.strMatching "[A-Za-z0-9_-]+"` | +| Default | `"us"` | +| Description | XKB layout the `hhstream-pointer` unit uploads once as the virtual keyboard keymap (`rules` `evdev`, model `pc105`). Injected keys are decoded with this keymap. Hyprland `input:kb_layout` is not read. One group: a comma-separated list does not match the type. `de` is the value the VM check uses for a non-`us` proof. | + +`variant` / `options` / `model` stay as the plan wrote them (`""`, `""`, `"pc105"`). They are not required for the `de` y/z proof. Do not add a `rules` option; the driver hardcodes `evdev`. + +Path to the upload, in order: + +1. `nix/module.nix` `hhstream-pointer` `ExecStart` (today the frozen two-flag line at the `ExecStart = lib.escapeShellArgs` block, ~986–992) gains `--xkb-layout ${cfg.sessions.keyboard.layout}` plus the plan's `--xkb-model`, `--xkb-variant`, `--xkb-options`. +2. `hhstream_pointer/__main__.py` parses them. A comma in `layout`, or a layout `xkb_keymap_new_from_names` rejects, returns `EXIT_USAGE` (2) **before** `WaylandSink.connect`. xkbcommon accepts `us,ru`; the driver must reject `,` itself. The Nix type does not cover a hand-run binary. +3. `keymap.py` compiles `rules=evdev`, `model`, `layout`, `variant`, `options` and returns one text keymap. Same object for every later `type`. +4. `backend.py` `create_virtual_keyboard(seat)` once, then one `keymap` request, then `listen`. Not on acquire, not per string. + +`CONTRACT-sessions.md` §3.4's "command line the module will pass, exactly" and the unit comment that quotes it (`module.nix` ~981–985) have to be amended in the same change. §5's binary and socket names do not change. + +--- + +## A. What the plan gets right + +Do not reopen these. + +- **Not a new service.** `CONTRACT-sessions.md` §5 freezes binary `hhstream-pointer` and socket `/run/hhstream/pointer.sock`. A CLI group on `hhstream session` is not a new binary. No second socket, no second unit. +- **No `touch`.** §4: `touch` is the only activity mark; every `pointer.*` verb leaves the idle clock alone. `pointer_click` never calls `registry.touch` (`manager.py` `pointer_click`). Routing `keyboard.*` through `_refresh` and not through `touch` is the same rule, and it is testable the way `test_pointer_verbs_do_not_reset_the_idle_clock` already is (`command_count`). +- **One lease, no `keyboard` flag.** `PLAN` §6.7's flag cannot name which keys to lift. `_Held.buttons` is an insertion-ordered dict because `release_all` must (`pointer.py` `_Held`, `ops.py` `_pressed`). A `keys` dict beside it is the same pattern. `acquire` already raises `LeaseBusy` for the current holder (`pointer.py` `acquire`), so a second id cannot replace a half-typed chord. Two leases would let session B warp while A types: one `wl_seat`, and `follow_mouse = 1` (`nix/hyprland-conf.nix`). +- **Exit 9 is implementable where the plan says.** Gesture verbs go through `_refresh` (`manager.py`): live session, `_expire_pointer`, then `PointerLease.refresh`, and `LeaseInvalid` becomes `no_lease`. The CLI already refuses with exit 9 before the broker when the cache is empty (`hhstream_session/__init__.py` `_lease_of` / `_no_lease`), using `lease.py`'s `pointer-leases.json`. There is no second cache to add. Another session's hold is 9, not 8; 8 is only `LeaseBusy` on a second `pointer.acquire` (`pointer_busy` → `ExitCode.BUSY`). +- **`expire()` stays `LeaseInfo` only.** §3.3. `_expire_pointer` already reads `pressed()` before `expire()` and then calls one `release_all`. Reading `keys_pressed()` on that same line is the whole of the lease-side change. Do not add `release_all_keys`. +- **Replay mechanism is the click mechanism.** `server.py` `_dispatch` looks up `request_id` before the handler and `remember`s after, success or failure. Membership is `MUTATING_VERBS` (`protocol.py`). `pointer.state` is not in that set. Putting `keyboard.key` and `keyboard.type` in it, and not `pointer.state`, matches `test_a_retried_click_with_the_same_request_id_clicks_once` (`tests/sessions/integration/test_containers.py`). +- **Names on our JSON, evdev only on the Wayland request.** This is what the plan's own driver examples say (`{"op":"key","key":"Return"}`), and it is what `buttons.py` does: names on the broker and driver sockets, `code_for` inside `ops.py`, integers only in `PointerSink.button`. The shorthand "evdev codes on the driver wire" is not the plan and would force a keymap into the broker. Do not "correct" the plan toward that. +- **No keyboard `frame`.** `zwp_virtual_keyboard_v1` v1 requests are `keymap`, `key`, `modifiers`, `destroy`. `backend.py` `display.flush()` on every pointer method is a socket flush, not a `wl_pointer.frame`. `ops.py` `frame` is a separate op because the pointer protocol delivers on `frame` (`PointerSink.frame` docstring; `driver.py` `frame` docstring). A key queued until `frame` would never be sent. Keyboard requests must flush inside the sink the way `button` does, and must not call `_aimed()` — keys are not per output (`ops.py` `_aimed` raises when nothing has been warped). +- **Missing keyboard global must not `ManagerTooOld`.** That exception is the pointer manager below version 2 (`backend.py`, `__main__.py` `connect`), because a v1 pointer aims at the desktop. A missing `zwp_virtual_keyboard_manager_v1` is a different failure. Pointer ops have to keep working. +- **Mask, not a synthetic Shift, for a capital.** Confirmed against v0.56.2 below. VM must print mask and keycode, not only the character. +- **Validate the whole string before the first sink call.** Same reason a bad axis emits nothing (`test_an_unknown_axis_is_refused_by_the_driver_not_invented`). +- **Audit stores a count.** `AuditLog.emit` writes every field it is given (`audit.py`). The generic `request` line in `server.py` stores the error **name**, not the body. A dedicated `keyboard_type` event is the leak. `chars` and not `text` is the right shape; click stores `button` and `count` (`pointer_click`). +- **VM proof is required.** `docs/TODO/scroll-has-no-compositor-proof.md` is the precedent the plan cites. Unit tests do not show a client decode a symbol. +- **Rollback.** Unknown `op` is `Rejected` and the connection stays (`ops.py` `_handle`). Old brokers never send `key` / `type`. + +--- + +## A. Protocol + +`zwp_virtual_keyboard_manager_v1` version 1 is what Hyprland v0.56.2 binds (`ProtocolManager.cpp` constructs `CVirtualKeyboardProtocol` with version 1). There is no `wp_virtual_keyboard_v1` in that tree. uinput is a second privilege the pointer path does not have (`WaylandSink` is a client; the unit's only extra privilege is group `hhstream` so it can open the Wayland socket, `module.nix` `SupplementaryGroups`). Rejecting `wtype` as the mechanism is right: one process, one keymap, one `release_all`. + +v1 requests and the values the plan never writes down: + +| Request | Arguments | Values that matter | +| --- | --- | --- | +| `keymap` | `format: uint`, `fd: fd`, `size: uint` | Protocol `keymap_format.xkb_v1 = 1`. That format is a **null-terminated** libxkbcommon text keymap. The `key` event's code is an evdev code; clients add 8. | +| `key` | `time: uint`, `key: uint`, `state: uint` | `key_state.released = 0`, `pressed = 1`. Same integers as `buttons.STATES`. `time` is milliseconds, undefined base, **one clock for the object**. | +| `modifiers` | four `uint`s | depressed, latched, locked, group. Not derived by this protocol from `key`. | +| `destroy` | destructor | See held keys below. | + +`key` or `modifiers` before `keymap` is protocol error `no_keymap` (0). Hyprland posts it and the client connection dies (`VirtualKeyboard.cpp` `setKey` / `setModifiers`). That is not `{"ok": false}` and not a retry. "Upload once, after connect, before `listen`" is the right order (`__main__.py` already treats a listening socket as a promise). A second `keymap` is not a refresh: Hyprland replaces the xkb state and does **not** walk `m_pressed` (`setKeymap` in the same file). + +What the plan gets wrong or leaves out: + +1. **`size` must include the trailing NUL.** Hyprland `mmap`s exactly `len` bytes and passes the pointer to `xkb_keymap_new_from_string` (`VirtualKeyboard.cpp` keymap handler). No NUL inside that map reads off the end. The plan says "memfd of an XKB text keymap" and never says `size == strlen + 1`. +2. **`time` is unspecified.** Pointer methods pass `_now_ms()` (`backend.py`, monotonic ms, low 32 bits). The keyboard sink has to use that same function. A constant 0 is one clock and therefore legal, but it is a second clock the moment anything else on the object uses monotonic time. +3. **Hyprland ignores `format` and parses as `XKB_KEYMAP_FORMAT_TEXT_V2`.** Send `format = 1` anyway. A `TEXT_V1` string from `xkb_keymap_get_as_string` is what V2 accepts. Do not pass `XKB_KEYMAP_FORMAT_TEXT_V2` (the integer 2) as the Wayland format. +4. **Do not vendor Hyprland's `protocols/virtual-keyboard-unstable-v1.xml`.** That v0.56.2 copy mentions `keymap_format` and `key_state` and does not define them. The plan's wayland-protocols path is the right file (`share/wayland-protocols/unstable/virtual-keyboard/virtual-keyboard-unstable-v1.xml`). `regenerate.py` must seed the import map from core `wl_*` the way it already does; scanning this XML alone `KeyError`s on `wl_seat`. +5. **`release_all` with no keyboard object must still lift buttons.** The plan says a missing global is not fatal, and also says `release_all` grows key-ups and a `modifiers(0,…)`. If the key half throws, `_expire_pointer`'s one `release_all` stops lifting buttons. Key-ups and `modifiers` run only when `create_virtual_keyboard` succeeded. +6. **Upload failure is exit 10 and must not `listen`.** A keymap Hyprland rejects is `noMemory` on that resource, i.e. a dead connection. Layout rejection before connect stays exit 2. The plan specifies only the second. + +`ManagerTooOld` wording in the plan matches the code. "No per-output target" matches the XML (`create_virtual_keyboard(seat)` only) and is why `key` must not go through `_aimed()`. + +--- + +## A. Surface and lease + +§4 and §5 hold, with one contract edit the plan already schedules (§3.3 key mirror, §3.4 ops and argv, §4 verb rows). Do not renumber `ExitCode`. New verbs do not call `touch`. + +**Exit codes do not match the pointer path the plan says it copies.** + +`_drive` turns every driver `ok: false` into `ManagerError("driver_refused")` (`manager.py`), and `driver_refused` is exit **10** (`protocol.py` `EXIT_CODE_FOR_ERROR`). An unknown button is not exit 2: `_button_name` only checks "non-empty string", and `test_an_unknown_button_is_refused_by_the_driver_not_invented` asserts `driver_refused`. The plan says both "Rejected, same as a bad button" and "exit 2 for a bad keysym or an unmappable character". Those are different codes. Exit 2 happens only for `invalid_argument` raised in the broker **before** `_drive` (`_checked_count`, a non-string button). + +So, as written: + +| Case | What the plan says | What the current mapping does if resolution stays in the driver | +| --- | --- | --- | +| text longer than 4096 scalars | `invalid_argument` (2) | 2, **if** the broker checks `len` before `_drive`. The driver check alone is 10. | +| bad keysym, `é` on `us`, C0 other than `\n`/`\t`, dead key, `type` while a non-modifier is held | 2 | **10** `driver_refused` | +| no keyboard global, or the Wayland connection died | 10 | 10. Right. | +| no lease / other holder | 9 | 9 via `_refresh`. Right. | +| second `pointer.acquire` | 8 | 8. Right. `keyboard.*` must not call `acquire`. | + +Pick one before Stage 1. Recommended, because a bad character is not a dead compositor: broker rejects non-string text, the 4096 cap, and a bad `state` as `invalid_argument`. Driver rejections that are caller errors carry a stable token (not only a sentence), and `_drive` maps that token to `invalid_argument`. `driver_refused` stays "the keyboard global is missing". Copying the button path and then asserting exit 2 in the tests will fail. + +**Acquire's own stderr contradicts the lease story.** `__init__.py` prints "expires in … with no further **pointer** verb". A `keyboard.*` verb that goes through `_refresh` moves `expires_at`. That sentence has to say any pointer or keyboard verb. Otherwise the TTL test looks "flaky" against the help text. + +`type` refreshes once per broker verb because `_refresh` is once per verb. It must not call `refresh` per character. Explicit modifier holds live in `_Held.keys` across later `type`s; `release()` drops the whole `_Held`, so the mirror does not leak into the next holder. `pointer_release` already calls `_release_all_buttons` before `PointerLease.release`. One extended `release_all` covers keys. Audit for release already has `buttons_lifted` from the **driver** list, not from `LeaseOutcome` (`pointer_release`). `keys_lifted` goes next to that field, not into a new release body. `pointer_lease_timeout` already records `pressed` and `buttons_lifted`; add `keys_lifted` there. + +`_refresh` still requires a container output (`_pointer_output`). Typing has no output argument, but the lease gate does. A session with no container gets `no_container` (exit 10) the same way a click does. That is existing behaviour, not a new keyboard rule. Do not special-case it. + +--- + +## A. Idempotency and audit + +A completed `keyboard.type` with a given `request_id` does not type twice, **for the same reason a completed click does not click twice**: lookup hits, the handler is not called, the reply is the stored object plus `deduplicated: true`. A stored failure is replayed too (`test_a_recorded_failure_is_replayed_as_the_failure_it_was`), so a retried unmappable `type` must not touch the sink either. + +The plan does not get a stronger guarantee than click, and it should not claim one: + +- The cache key is `request_id` alone (`IdempotencyCache.lookup`). A `keyboard.type` that reuses a `pointer.click` id returns the click reply and does not type. +- `remember` runs after the handler returns. Two connections in flight with the same id both miss the cache. The driver lock serialises the Wayland writes; it does not collapse them. Both strings are typed. +- Capacity is `DEDUP_ENTRIES` (64). An older id is forgotten and will type again. +- A driver death **mid-string** is not the unmappable case. Validation-before-emit stops a bad character from typing a prefix. A connection drop after character 2 of 5 still typed 2, the error is then cached, and the replay does not finish the word or undo it. Click has the same hole between down and up. Say so; do not let the "no prefix" sentence cover it. + +Audit: `keyboard_key` may store the keysym name and `down`/`up`. `keyboard_type` stores `chars` (scalar count) and nothing else from the string. Driver logs and `Rejected` messages must use an index ("unmappable at scalar 3"), not the character and not the string. `emit` will happily write a `text` field if a caller passes one. The shell and `ps` still show the CLI argument; that is outside this audit rule. + +--- + +## A. Correctness traps + +### Typing `A` (nothing else held, layout `us`, model `pc105`) + +Evdev `KEY_A` is **30**. The XKB keycode is 38. The Wayland `key` request and `wl_keyboard.key` both carry **30**. Shift's modifier index on the evdev `us` map is 0, so the depressed mask is `1 << 0` = **1**. Do not hardcode 1 in the resolver; ask xkbcommon (`xkb_keymap_key_get_mods_for_level` or the equivalent level lookup). On `us` the lookup returns 1. + +`devices/Keyboard.cpp` (libinput keyboards) calls `updateXkbStateWithKey`. `devices/VirtualKeyboard.cpp` does not: `updatePressed` only edits `m_pressed` (`IKeyboard.cpp`). A virtual `key(KEY_LEFTSHIFT)` does **not** change Hyprland's modifier mask and does **not** cause `wl_keyboard.modifiers`. The `modifiers` request is required. The plan is right. + +Sequence on `zwp_virtual_keyboard_v1`, one object, `time` from `_now_ms()`: + +``` +modifiers(mods_depressed=1, mods_latched=0, mods_locked=0, group=0) +key(time, key=30, state=1) # pressed +key(time, key=30, state=0) # released +modifiers(0, 0, 0, 0) +``` + +Not in that sequence: evdev 42 (`KEY_LEFTSHIFT`), XKB code 38, a pointer `frame`. `modifiers` goes **before** the key. A client that decodes with the mask from the last `wl_keyboard.modifiers` (foot, GTK) emits `a` if the key comes first. + +`keyboard down Shift_L` is the other path, and the plan is right to keep it different: send `key(42, pressed)` **and** `modifiers(1, 0, 0, 0)`, and remember both. `release_all` key-ups in press order, then `modifiers(0, 0, 0, group)`. The `modifiers(0)` is not optional. Virtual key-ups do not clear the mask, because `updateXkbStateWithKey` never runs for this device. A `release_all` that only key-ups leaves Shift latched in every client that trusts the mask. + +`type` while `Shift_L` is already held ORs the character mask with that baseline (still 1 for `a`) and must not emit a second Shift key. `type` while a non-modifier is held emits nothing. The plan never defines "modifier". Define it as the keysyms that contribute to the depressed mask on this keymap: `Shift_L/R`, `Control_L/R`, `Alt_L/R`, `Meta_L/R`, `Super_L/R`, `Hyper_L/R`, `ISO_Level3_Shift`, `ISO_Level5_Shift`. `Caps_Lock` and `Num_Lock` are locks, not that set; v1 rejects `type` while they are held. A Shift-only special case fails the `de` VM check (`@` is a level-3 mask, not Shift). + +Ctrl is index 2, mask 4, on the same map. `down Control_L` then `type c` is `modifiers(4)`, `key(KEY_C)`, `modifiers(4)`, and `Control_L` still in `keys`. + +### Warp does not guarantee `wl_keyboard.enter` + +The plan's risk is right, and understated. v0.56.2 already answers it for the shipped config. + +`onMouseWarp` calls `mouseMoveUnified(time)` with `refocus=false` (`InputManager.cpp`). With `follow_mouse == 1`, the distance added to `m_mousePosDelta` is the distance of **this** warp only when the previous cursor movement was **under 0.5 s** ago; otherwise the delta is set to 0. Keyboard focus then requires `m_mousePosDelta > follow_mouse_threshold` or `refocus`. The threshold option defaults to **0**, so the test is `> 0`. One warp after the cursor has been still does not pass it. + +Pointer focus is updated later in the same function with no threshold. That is why `vm-pointer` saw clicks land, and why `follow_mouse = 0` delivered clicks to nobody (`hyprland-conf.nix` comment, `checks/vm-pointer.nix` header). Those measurements are not `wl_keyboard.enter`. + +`rawWindowFocus` still runs if `keyboardFocus == nullptr`. A single mapped window is usually focused at map time, so a one-window probe prints `enter` and proves nothing about the warp. `cursor.no_warps = true` in our conf blocks `PointerController::warpTo`, not a virtual pointer's `warpAbsolute`. The cursor does move. Focus still does not. + +A second warp inside 0.5 s adds a non-zero delta and can focus. Stage 0 has to measure **one idle warp** and **a second warp inside the window** separately. `dispatch focuswindow` stays the fallback the plan names, and it is likely mandatory, not a surprise Stage 4. Do not build it in Stage 1. Do not write Stage 3's enter assertion against one window. + +### Destroy, expiry, `kill -9` + +Three different paths. + +| Path | What runs | v0.56.2 result | +| --- | --- | --- | +| TTL, `pointer release`, kill/reap of the **holder** | Broker `release_all`: button-ups, key-ups, `modifiers(0,0,0,0)`. Object stays. | Keys and mask clear **if we send them**. `input:virtualkeyboard:release_pressed_on_close` is irrelevant. | +| Driver `SIGTERM` | `__main__.py` `finally` → `_lift_everything` → `release_all`, then `sink.close`. | Same, once `release_all` lifts keys. The comment today says buttons only. | +| `destroy` of the resource, client disconnect, `kill -9` | `CVirtualKeyboardV1Resource::destroy`. `releasePressed()` runs only when `input:virtualkeyboard:release_pressed_on_close` is true. | Default is **false** (`ConfigValues.cpp`; device default `INT{0}` in `ConfigManager.cpp`). No key-ups. `releasePressed` emits key-ups only, never `modifiers`. The destructor emits `destroy` and does not release. | + +Stuck keys are worse than "a key stays down". `InputManager::onKeyboardKey` drops a press whose code is already in the seat's `m_pressed`, and drops a release that is not (`if (CONTAINS && pressed) return`). After `kill -9` with the default config, that code stays in `m_pressed`. The next driver's `key down` for it is ignored. The seat looks dead for that key until some client sends a matching `key up`. + +Required plan change, one line in `nix/hyprland-conf.nix`: `input:virtualkeyboard:release_pressed_on_close = true`. Still send explicit ups on the clean path. Still send `modifiers(0, 0, 0, 0)` once after the initial keymap upload, because even the true setting does not clear a mask, and a client keeps the last `wl_keyboard.modifiers` until the next one. Stage 0 confirms the running binary; the default in this tree is not an open question with even odds. + +`share_states` defaults to 2 (`only_non_ime`). Our client is not an IME grab, so the mask Hyprland forwards is the OR of every sharing keyboard (`shareModsFromAllKBs`). Headless config sets `WLR_LIBINPUT_NO_DEVICES=1` (`module.nix`). With no second keyboard the OR is a no-op. A second virtual keyboard with Shift held will keep Shift in the forwarded mask after our `modifiers(0)`. Not v1's problem; do not paper over it with a retry loop. + +### Auto-repeat + +Hyprland does not re-send `wl_keyboard.key` for a held key. It stores `input:repeat_rate` (default **25**) and `input:repeat_delay` (default **600**) on the keyboard and sends `wl_keyboard.repeat_info` (`Seat.cpp`). The client repeats. `KeybindManager`'s timer repeats **binds**, and virtual keys go through `onKeyEvent` unless the client is the IME (`shouldIgnoreVirtualKeyboard`). A bound key may never reach the window, and the bind may repeat. + +The plan's "if Stage 0 shows no repeat, the help text stays quiet" is the wrong gate. A raw client that counts `wl_keyboard.key` will see one press. foot/GTK/Qt will insert characters until key-up or TTL (default 30 s) from that one press plus `repeat_info`. `keyboard down` of a non-modifier must say so in the help text regardless of the probe. `type` and `keyboard key` are taps (down then up) and stay under the delay if the pair is immediate. The justified hold is a modifier chord, which clients do not repeat as text. + +There is no `repeated` state on `zwp_virtual_keyboard_v1.key` (Wayland's `wl_keyboard.key_state.repeated = 2` is client-facing, since version 10). We cannot ask the compositor for a repeat rate. + +--- + +## A. Changes required before code, cheapest first + +| # | Change | If it waits until after Stage 1 | +| --- | --- | --- | +| 1 | Resolve exit 2 vs `driver_refused`. Broker-side checks for shape and the 4096 cap. A distinct driver token for "your keysym/character", mapped to `invalid_argument`. Missing global stays 10. | Help text, `test_exit_codes.py`, and every verb test encode the wrong code. | +| 2 | Keymap `size` includes the NUL; fd stays alive across `flush`. `format = 1`. `time` is `_now_ms()`. | First real `type` kills the driver or types nothing. Looks like "Hyprland has no global". | +| 3 | `release_all` no-ops the key half when no virtual keyboard exists. `modifiers(0,…)` after upload, and at the end of every `release_all` that touched a mask. | A missing global breaks button expiry. A crash mid-`A` leaves Shift on for the next holder. | +| 4 | Set `input:virtualkeyboard:release_pressed_on_close = true` in `hyprland-conf.nix`. Document that this still does not clear the mask. | First `kill -9` during Stage 1 poisons `m_pressed`. Later downs of that key vanish. | +| 5 | Layout option as specified above, on the unit argv. Driver rejects `,` before `xkb_keymap_new_from_names`. Do not treat `[keyboard]` in the TOML as the upload path. | VM "non-us" checks the broker file, the driver stays on `us`, test is a false pass or a surprise. | +| 6 | Write down the modifier-keysym set. Resolver returns `(evdev, mask)` for any level, not a Shift special case. `key`/`type` do not call `_aimed()`. | `de` and Ctrl+C get a second code path that disagrees with `us`. `type` without a prior warp fails only in a test that forgot to acquire. | +| 7 | Stage 0 expectations: one idle warp does not `enter`; destroy with the default config does not release; one held key is one `wl_keyboard.key`, while `repeat_info` is still sent. Help text for `down` warns unconditionally. Two-window probe, or the enter result is a false pass. | Stage 3 goes red, or goes green because the only window was focused at map time. Stage 4 arrives as a surprise. | +| 8 | Acquire stderr says keyboard verbs refresh the TTL. `Rejected` text and driver logs carry an index, not the string. | Operators release during a `type` that would have kept the lease. A password lands in the journal even though `events.jsonl` is clean. | + +Not required to change: the protocol choice, the process boundary, the single lease, names-vs-evdev, no `frame`, no `touch`, `expire()`'s return type, one `release_all`, mutation-set replay, `chars` not `text`, single group, xkbcommon as a hard test dependency, a real VM check. + +--- + +## B. Tests + +Gate for Stages 1–2 stays `nix develop -c python -m pytest tests/pointer tests/sessions/unit -q`. No test sleeps except the VM and the Stage 0 probe. No test in `tests/sessions/integration/` grows a fake compositor. + +### B1. Stage 0 probe + +One throwaway client, not committed, not run via the broker. It is not `hhstream`. It does not open `/run/hhstream/control.sock` or `pointer.sock`. + +Run it as the broker account (supplementary group `hhstream`, `module.nix` `sessions.user` description — that group is what makes `wayland-*` openable; the directory is `0750`): + +``` +sudo -u hermes -g hhstream env \ + XDG_RUNTIME_DIR=/run/hypr-stream \ + WAYLAND_DISPLAY="$(sudo -u hermes -g hhstream \ + find /run/hypr-stream -maxdepth 1 -name 'wayland-*' ! -name '*.lock' -printf '%f\n')" \ + python3 /tmp/kb-probe.py +``` + +Refuse to start if `find` prints more than one name (`backend.py` `find_wayland_display` does). Read-only `hyprctl` (`clients -j`, `monitors -j`, `getoption`) is allowed so the warp hits a known box. `hyprctl dispatch` is not allowed: `dispatch focuswindow` answers question (a) by cheating. + +The script uses pywayland. It binds `wl_compositor`, `wl_shm`, `xdg_wm_base`, `wl_seat`, `wl_output`, `zwlr_virtual_pointer_manager_v1`, `zwp_virtual_keyboard_manager_v1`. It prints every global as `global v` and exits 2 if the keyboard manager is missing or not version 1. Two `xdg_toplevel`s, app ids `kb-probe-a` and `kb-probe-b`, both mapped and acknowledged. `wl_keyboard` listener prints, flushed: + +``` +enter surface= serial= keys=[...] +leave surface= +repeat_info rate= delay= +keymap bytes= symbols= +modifiers depressed= latched= locked= group= +key code= state=<0|1|2> sym= +``` + +`sym` comes from `xkb_state` built from the **keymap fd the compositor sent**, updated with `xkb_state_update_mask` on `modifiers` and `xkb_state_key_get_one_sym(key+8)` on `key`. Not from a table inside the script. + +Sequence, printing a banner line before each step: + +1. Map A, map B. Sleep 0.6 s so the cursor has been still longer than Hyprland's 0.5 s window. +2. **(a1)** One `motion_absolute` of a virtual pointer bound to B's output, into A's box (normalised, from `hyprctl clients`). Sleep 0.3 s. Assert-by-printing: no new `enter` for A. An `enter` here means this binary does not match the v0.56.2 threshold logic; say so and continue. +3. **(a2)** A second warp, still inside A, immediately. Print whether A then gets `enter` and B gets `leave`. This is the double-warp question, separate from (a1). +4. Upload an `us` / `pc105` keymap (`format=1`, `size` includes NUL) on a virtual keyboard. Print `uploaded`. +5. **(c)** `key(KEY_A=30, pressed)` once. Sleep 1.5 s (longer than the 600 ms default delay). Print `press_count=` of `state=1` or `state=2` events for code 30. Do not key-up yet. +6. **(b)** `destroy` the virtual keyboard. Roundtrip. Sleep 0.2 s. Print `release_on_destroy=` and `mask_cleared=`. Do not send `key up` or `modifiers` before this. +7. Cleanup, required: a **new** virtual keyboard, keymap again, `key(30, released)`, `modifiers(0,0,0,0)`, destroy. Print `cleanup=sent`. This undoes a poisoned `m_pressed` if step 6 released nothing. + +**(a) passes** only if the log shows, in order: B entered at map; after (a1) A has no new `enter`; the line says which warp, if any, produced A's `enter`. A pass that is a lie: only one window, or `enter` counted with no check that it happened after the warp rather than at map, or a `hyprctl dispatch focuswindow` before the warp. + +**(b) passes** as a measurement, not as a green feature: print the `getoption` value of `input:virtualkeyboard:release_pressed_on_close` next to `release_on_destroy`. On v0.56.2 with the default, expect `release_on_destroy=no` and `mask_cleared=no`. A pass that is a lie: the script sent `key up` before `destroy`, or it counted a release from step 7. + +**(c) passes** as a measurement: `press_count` and the `repeat_info` line are both printed. Expect `press_count=1` and a non-zero rate on this source. Interpreting `press_count=1` as "`keyboard down` will not flood a text field" is the false pass. The flood is the client's repeat, which this probe does not implement on purpose. + +### B2. Unit tests (Stages 1 and 2) + +Match existing files. Dispatcher tests use a recording sink and do not grant authority (`tests/pointer/test_ops.py` module docstring). Lease tests use the injected clock (`tests/pointer/conftest.py`). Broker tests use the real UNIX socket and `FakeDriver` (`tests/sessions/unit/test_pointer_verbs.py`). + +`tests/pointer/test_keymap.py` — real xkbcommon, not a stub. + +| Case | Pass | False pass | +| --- | --- | --- | +| `us`: `a` → `(30, 0)`; `A` → `(30, mask)` with mask equal to `1 << xkb_keymap_mod_get_index(..., "Shift")`; `Return` and `"\n"` → `KEY_ENTER` (28); `Tab` and `"\t"` → 15 | Those tuples | Asserting xkb code 38, or hardcoding mask `1` without reading the index (breaks the day the resolver is used for `de`) | +| `""` → `[]` | Empty, no error | | +| `"é"`, `"\x01"`, keysym `dead_acute` raise | Exception type the dispatcher already maps to `Rejected` | Asserting the message contains `é` (that string would be logged) | +| `"abé"` through the dispatcher | `ok: false` and **zero** sink calls | Asserting only that no event carried `é`, while `a` and `b` were emitted | +| 4096 scalars of `a` accepted; 4097 rejected with zero sink calls; one case is 4096 scalars of `😀` (`len == 4096`) | Boundary as scalars | ASCII only: a byte cap and a scalar cap agree, so a `len(utf8)` check stays green | +| Two `type`s | The keymap **object** is built once, and the sink's `keymap` method is called once | Asserting only that `keymap.py` returns equal strings. A backend that uploads on every `type` stays green | + +`tests/pointer/test_ops.py` — extend `RecordingSink` with `key(code, state)` and `modifiers(dep, latch, lock, group)`. + +| Case | Pass | False pass | +| --- | --- | --- | +| `key` `down` then `pressed` | `keys == ["Return"]` (name, not 28) | | +| `up` of a key that was not down | `ok: true`, not listed as lifted. Same as `unpress` | | +| `release_all` after `Control_L` then `a` | key-ups in that order, then one `modifiers(0,0,0,0)`, even if the last warp was a different output. No `frame` added for the keys | A sink that ignores the output argument. Warp to output B and assert the key calls were not tagged with B | +| `type "A"` with nothing held | `modifiers(shift), key(30,1), key(30,0), modifiers(0,…)` and `keys == []`. No code 42 | Asserting the sink was called at all, or that some event's code was 30, without the mask before the press and without the absence of 42 | +| `type` with `Control_L` held | Mask ORed, `Control_L` still in `keys`, no Control key-up | | +| `type` with `a` held | `ok: false`, zero new sink calls, `a` still held | | +| `type "Hi"` with **no prior warp** | Keys emitted. Must not return the `_aimed()` error | Every test warps first because it copied `test_ops` helpers. Delete the warp in this one test | +| `release_all` when the sink has no keyboard | Buttons still lift; no exception | Only running it when the keyboard exists | + +`tests/pointer/test_lease.py` — `press_key` order matches `press`. `expire()`'s return has no key list. The test reads `keys_pressed()`, then `expire()`, then sees no holder. Existing busy / stale / `lease_id` tests stay. + +`tests/pointer/test_vendored_protocol.py` — interface `zwp_virtual_keyboard_manager_v1`; requests `keymap`, `key`, `modifiers` on `zwp_virtual_keyboard_v1`; enum values `xkb_v1 == 1`, `pressed == 1`, `released == 0`. No display. + +`tests/sessions/unit/test_keyboard_verbs.py` — copy the `test_pointer_verbs.py` harness. + +| Case | Pass | False pass | +| --- | --- | --- | +| No lease, and another session holds it | `no_lease` (exit 9), not `pointer_busy` | | +| Second `pointer.acquire` while a key is held | `pointer_busy` (8). The held key is still the first holder's | Acquiring from the holder and treating 8 as success | +| `type` and the clock | Advance less than `ttl` after `type`: holder remains. Advance past it: one `release_all`, and that reply's `lifted_keys` contains the key that was down | Advancing the clock without running `_expire_pointer` / the sweep. The unit test must call the sweep or the next verb, the way the pointer expiry test does | +| Driver `ok: false` on `key` | Lease `keys` unchanged | Asserting the error only | +| `type` | `last_activity_boottime` and `command_count` unchanged | `command_count` alone if a future change updates the timestamp without counting a command. Assert the timestamp | +| `pointer.release` and `kill` | Driver `lifted_keys` contains what was down; `pointer.state` holder is null; `keys` is `[]` | `kill` of a session that does not hold the lease (green, lifted nothing) | +| `pointer.state` | `keys` present, names not codes | | +| Replay | Same shape as `test_a_retried_click_…`: second reply `deduplicated: true`, sink `key` count unchanged. Also replay an **unmappable** `type`: still zero sink calls | Asserting `deduplicated` and not the sink. A handler that types and then sets the flag stays green | +| Unmappable / over cap at the broker | Exit 2 `invalid_argument` for the cap and for a non-string. Exit 2 for an unmappable character **only after change 1**; until that mapping exists this assertion fails, which is the point | Treating `driver_refused` as 2 because the CLI printed "usage" somewhere in the hint | + +`tests/sessions/unit/test_settings.py` — only if `[keyboard]` is actually read. If the option lives solely on the unit argv, this test does not belong here; a TOML default of `us` that nothing uploads is the false pass `test_settings.py`'s own docstring warns about. Prefer asserting the driver's flag parser: omitted `--xkb-layout` is `us`, `--xkb-layout de` is `de`, `--xkb-layout us,ru` exits 2 and does not connect (inject a connect function and assert it was not called). + +`test_cli_surface.py` — `keyboard` in `hhstream session --help`; the keyboard help says exit 9 until `pointer acquire`; `pointer --help` does not grow a keyboard tutorial. False pass: the word `keyboard` appears in the pointer help because of the acquire-stderr fix, and the test greps the whole binary help. + +`test_broker_protocol.py` — `keyboard.type` and `keyboard.key` in `VERBS` and `MUTATING_VERBS`; `pointer.state` still absent from the mutating set. `test_every_verb_the_protocol_names_is_one_the_daemon_answers` already fails if only one of the lists is updated. Keep it. + +`test_exit_codes.py` — no new integer. If a new error **name** is added for the driver token, map it in `EXIT_CODE_FOR_ERROR` and add a row. A name that is not in the table becomes exit 4 `BAD_STATE` (`exit_code_for`). That is the false pass for "we return 2": the CLI exits 4 and the test only checked `ok: false`. + +### B3. VM proof (Stage 3) + +New `checks/vm-keyboard.nix`, same shape as `checks/vm-pointer.nix` (`testers.runNixOSTest`, `session-machine.nix`, `session-prelude.nix`, `globalTimeout` on the order of `vm-pointer`'s 1800). Do not fold it into `vm-pointer`. Real time, no injected clock; the expiry subtest in `vm-pointer` says why. + +Victim: a sibling of `checks/lib/pointer_target.py`, not foot and not Chromium. It sets `xdg_toplevel` app id from `$HHSTREAM_APP_ID` (the reason `pointer_target.py` exists: foot ignores the variable and is quarantined). It prints the same keyboard lines as the Stage 0 probe, from the keymap fd. Read-back is `hhstream session logs`, as in `vm-pointer`. + +Subtests: + +1. **Enter.** Two sessions, A and B, B started last so B is focused (the `vm-pointer` measurement that already bit them). `pointer acquire` on A, one warp. A's log shows `enter` for A's app id **after** the acquire, and B's log shows `leave`. If (a1) of Stage 0 was "no enter", this subtest is expected red until the double-warp or `focuswindow` fallback is in, and the assertion is not weakened to "cursor coordinates look right". +2. **`keyboard type` of `A` then of `hello`.** A's log contains, in order, `modifiers depressed=1`, `key code=30 state=1 sym=A`, `key code=30 state=0`, `modifiers depressed=0`, and **no** `code=42` on that span; then five key downs decoding to `h,e,l,l,o`. B's log has no `key ` line from this span. +3. **TTL.** `keyboard down Shift_L`, `--ttl` of a few seconds, wait it out in real time. A's log shows code 42 released and `modifiers depressed=0`. `pointer state` has `holder` null and `keys` empty. A second `pointer acquire` from B during the hold, before the wait, exits 8. +4. **Layout.** Same VM expression with `sessions.keyboard.layout = "de"` (module argument, so the unit argv changes). Do **not** set Hyprland `input:kb_layout` (leave it unset / `us`). `keyboard type y` decodes to sym `z`; `keyboard type z` decodes to sym `y`. The keymap line from the fd contains the symbols name `de`. + +False passes: + +| Assertion | Looks green while broken | +| --- | --- | +| Characters on A | The log is searched for the substring `hello`, and the session log also contains the broker command or the test script echoing the argument. Match `sym=h` lines from the victim only. `pointer_target.py` prints what the **client** received for this reason | +| Silence on B | B never bound `wl_keyboard`, or B's window was never mapped, so B is silent even when focus is still on B and A also received nothing. (1) and (2) are one assertion: A positive and B negative | +| Keymap was uploaded | A decodes `hello` with a keymap compiled inside the victim. Require the sym to come from the fd, and fail the subtest if no `keymap bytes=` line precedes the keys. The plan's mutation rule (`PLAN` §14): keycodes without a decoded `hello` are a failure | +| Non-`us` | The test greps the guest's systemd unit for `--xkb-layout de` and never types `y`. Or Hyprland `kb_layout` was also set to `de`, so a client that ignored our keymap still decodes `z` | +| TTL key-up | The waiter matches a `state=0` from the earlier `hello` taps. Use code 42, which `type` must not emit | +| Second acquire exits 8 | A leftover holder from a previous subtest. This subtest acquires, holds, and only then has the other session acquire | +| Enter | One session. Map-time `enter` satisfies "A saw enter" | + +Stage 0's script is the wrong place to prove the broker lease. The VM is the wrong place to prove replay. Keep them apart. + +--- + +## If I had to bet + +The plan is safe to **build on** and not safe to **implement as written**. + +I would not reopen `zwp_virtual_keyboard_v1`, the pointer process, the single lease, keysym names on the broker and driver sockets, or "Shift for `A` is a mask". Those match the code and, for the mask, match Hyprland v0.56.2 (`updateXkbStateWithKey` is only on the libinput keyboard). + +I would refuse a Stage 1 that starts from the plan text unchanged. The exit-code paragraph disagrees with `_drive` and with `test_an_unknown_button_is_refused_by_the_driver_not_invented`. The keymap upload omits the NUL that Hyprland's `mmap` requires. Destroy-while-held is not an open question in this tree: `release_pressed_on_close` defaults to false, and the true setting still does not clear modifiers, so `kill -9` poisons `m_pressed`. A single idle warp does not send `wl_keyboard.enter` under `follow_mouse = 1` with the default threshold; a one-window VM check will say it did. The layout option the operator asked for reaches the keymap only as `--xkb-layout` on `hhstream-pointer`, not as a `[keyboard]` table copied from `[pointer]`. + +Those are plan edits, all cheaper than the first driver commit. After them, Stage 0 is a measurement against `/run/hypr-stream` with the expectations above, not a research project, and Stage 1 has a test that goes red for a prefix-typed `é`, a second keymap upload, a replay that types twice, and an `A` that was a Shift keycode instead of a mask.