Files
hyprland-headless-stream-pl…/docs/plans/2026-10-04-keyboard-verification.md
T
HermenixandClaude Opus 5 561e0c28f5 Stage 2 fixes: the two tests the review named, and the docs drift
From docs/reviews/2026-10-04-stage2-3-review.md (Stage 3 done; Stage 2
done-with-fixes). Its findings 1, 2, 3 and 5, which it called the only
things standing before merge.

(A) REPLAY, THROUGH THE SINK. What existed was
    `test_every_keyboard_verb_is_cached_for_the_same_reason`, which
    asserts the two verbs are in MUTATING_VERBS -- and the verification
    doc had already named that as the false pass: "asserting
    `deduplicated` and not the sink. A handler that types and then sets
    the flag stays green." Two integration tests now, modelled on
    `test_a_retried_click_with_the_same_request_id_clicks_once`:

      test_a_retried_type_with_the_same_request_id_types_once
        `keyboard.type` of "ab" twice with request_id="retry-me".
        Asserts `deduplicated`, chars == 2 on both, and that the sink
        still has exactly 4 key events -- two characters, a down and an
        up each -- so a replay that typed again is caught by the count
        and not by the flag.

      test_a_retried_unmappable_type_stays_refused_and_types_nothing
        `café` twice with one id. Both refusals are `invalid_argument`,
        the second carries `deduplicated` (a recorded failure is
        replayed as the failure it was), and the sink is empty after
        both -- there is no partial type on either call.

    Mutation-checked rather than assumed: removing `keyboard.key` and
    `keyboard.type` from MUTATING_VERBS fails both.

(B) KILL, THROUGH kill(). `test_killing_the_holder_lifts_its_keys` calls
    `_drop_lease_for` directly, so it proves that helper lifts keys and
    says nothing about whether `kill` still calls it. The integration
    kill test now holds `Shift_L` before the kill and asserts the SINK
    saw `("key", 42, 0)` and `("modifiers", 0, 0, 0, 0)` -- the lease
    forgetting a key is not the compositor being told it came up, and
    only the second matters to the application. Code 42 because `type`
    never emits it, so the release cannot be a leftover.

    Mutation-checked: stubbing out the `_drop_lease_for` call in
    `kill()` fails it. Before this it stayed green.

(C) DOCS. The plan's stage table and risk paragraph still said acquire
    is one warp and that `focuswindow` was unbuilt Stage 4 work. The
    contract (v3 §4) describes what shipped; the plan did not. Rewritten
    so they agree, and the plan now says outright that the contract wins
    where they differ:

      * risk 1 marked RESOLVED, describing the two warps, the pinned
        `follow_mouse_threshold`, and `focuswindow` as the
        nudge-failure fallback selecting on `address:` (not
        `stable_id`, which is not a Hyprland selector)
      * Stage 3 marked Done; Stage 4 struck as not existing -- the
        answer to Stage 0 was the second warp, not a focus dispatch
      * the top banner, the §5 VM assertion list and open question 2
        no longer say "one warp"
      * verification §B3 subtest 1 amended: it is a live assertion
        rather than an expected red, and the check additionally requires
        `focus == "warp"` so the fallback is not accepted as success

    Also amended one sentence the review did not list, because leaving
    it would contradict the edit above inside the same document:
    verification §"Warp does not guarantee wl_keyboard.enter" predicted
    `focuswindow` was "likely mandatory". It was not; the second warp
    was.

    Written down rather than smoothed over: the `focuswindow` branch
    itself has no test, and if both mechanisms fail acquire still
    returns ok with `focus="none"` -- a lease whose first key may go to
    the previously focused window.

(D) The tap docstring claimed the `up` is sent even if the `down` was
    refused after sending. The next lines return early on `not ok`, and
    that early return is right: a refusal means the key was never
    pressed, so an `up` would ask the compositor to release something it
    never had. Sentence replaced with why the early return is correct
    and what actually covers a lost reply (the broker's `release_all`,
    not the CLI, which cannot know whether the request arrived).

Not done, and not claimed: findings 4, 6 and 7 (the broker chord test
checking first/last mask rather than the key; the at-cap test not
looking at the sink; the module-defaults test being a substring match).
The review rates all three as not holes in the claim, and the driver
tests are the locks for the first two.

  nix develop -c python -m pytest tests -q
    907 passed in 67.71s
  nix develop -c python -m pytest tests/pointer tests/sessions/unit -q
    605 passed in 27.16s

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GhNPM6rGcuzxocM1nATnuM
2026-10-05 04:43:56 +00:00

352 lines
43 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 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.
**[AMENDED after Stage 2 — "likely mandatory" was the wrong prediction.]** Stage 0 measured exactly what this paragraph predicted, and the fix that shipped is the **second warp**, not the focus dispatch: `pointer_acquire` sends a nudge and then the target, which is the "second warp inside 0.5 s" above. `focuswindow` did ship, but as the narrow fallback for a nudge that could not be *sent*, inside acquire — not as the mechanism that moves focus. So Stage 4 is not pending work of any kind. See `docs/CONTRACT-sessions.md` v3 §4 and §B3 subtest 1 below.
### 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 <name> v<version>` 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=<app-id> serial=<n> keys=[...]
leave surface=<app-id>
repeat_info rate=<n> delay=<n>
keymap bytes=<n> symbols=<snippet>
modifiers depressed=<n> latched=<n> locked=<n> group=<n>
key code=<evdev> state=<0|1|2> sym=<name>
```
`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=<n>` 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=<yes|no>` and `mask_cleared=<yes|no>`. 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. A's log shows `enter` for A's app id **after** the acquire, and B's log shows `leave`. The assertion is not weakened to "cursor coordinates look right".
**[AMENDED after Stage 0 and Stage 2 — this said "one warp", and "expected red until the double-warp or `focuswindow` fallback is in".]** Stage 0's (a1) did measure "no enter", and the answer shipped in Stage 2: **acquire is two warps**, a real pixel apart, which is the double-warp this sentence anticipated. So this subtest is a live assertion, not an expected red. `focuswindow` also shipped, but it is *not* what makes this pass — it runs only when the nudge warp cannot be sent — so the check additionally requires the reply's `focus == "warp"` and treats `focuswindow` or `none` as failure. And it asserts `wl_pointer.enter` on A separately from `wl_keyboard.enter`: a check that saw only the cursor arrive would go green while A had the cursor, B had the keys, and the first keystroke of the lease went to B. `docs/CONTRACT-sessions.md` v3 §4 is the authority on the mechanism.
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.