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

43 KiB
Raw Blame History

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 remembers 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 uints 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 mmaps 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 KeyErrors 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 types; 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_toplevels, 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 types 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.