Stage 0 review: correct what the log does not say, and edit the plan

The Stage 0 review (docs/reviews/2026-10-04-stage0-review.md, verdict
yes-with-fixes) found that the measurements were sound and the write-up
was not. All four of its high and medium defects, verified against the
committed transcript before fixing:

(1) 19e484b's README claimed a verbatim excerpt and printed serial=336
    while the run's (a2) enter was serial 371. It also claimed six
    reproductions with one transcript, and cited a `keys=[42, 0, 0, 0]`
    enter from a run whose log was never kept -- every enter in the
    committed file is `keys=[]`. The excerpt is now copied from the log
    with line numbers to check it against, the reproduction claim is
    gone, and the Shift observation is named as not-in-this-log.

(2) THE (a) CONCLUSION WAS WRONG, and it is the one that matters. The
    first idle warp onto the unfocused window gave wl_pointer.enter and
    NO keyboard enter; the leave/enter arrived on the LATER motion. So
    it is not "enter, one warp late" -- the first warp's delta is set to
    0, the threshold is 0.0, and the second motion's own non-zero delta
    is what focused. Two corollaries the old text got backwards: a
    second warp to the SAME point returns before mouseMoveUnified
    touches the delta and proves nothing, and waiting longer does not
    help. The probe now prints both targets and the measured gap
    (0.401s) instead of hardcoding the word "immediately", and its
    ANSWER string says the mechanism.

    Consequence, now stated everywhere it belongs: `pointer acquire` is
    one warp, so the first key of a lease can land on whatever was
    already focused. Stage 3's enter subtest must not be designed from
    acquire's single warp, and must not be made to pass by warping twice
    to the same bookmark.

(3) d07a1fd did not edit the plan -- `git diff 14b3f69 HEAD --
    docs/plans/2026-10-03-keyboard-input.md` was empty, so anyone told
    to follow the plan still had the contradicted text. All eight
    pre-code changes are now folded into that file, each marked
    [SUPERSEDED], plus a banner at the top. Changes 5 and 7 were the
    ones that had survived intact in four places: the [keyboard] TOML
    table (dropped -- the broker reads that file and the driver is a
    different unit, so it would have been a setting with no effect) and
    "if it repeats, the help text says so" (now unconditional). The four
    closed open questions and the stage table are updated with what
    Stage 0 measured, including that Stage 4 is no longer contingent.

(4) mask_cleared=no was reported as a held mask surviving destroy. The
    held key was a letter, so the mask was 0 throughout; the README now
    says destroy emitted no key-up and no modifiers event, and that the
    reason release_all still sends modifiers(0,0,0,0) is
    VirtualKeyboard.cpp's releasePressed, not this line. The real
    poison evidence is promoted: onKeyboardKey drops a release whose
    code is not in m_pressed, so the cleanup's `key code=30 state=0`
    arriving from a brand-new keyboard proves 30 was still in that set.

The transcript is a fresh run of the corrected probe, so the file and
the claims about it agree line for line.

19e484b's message carries defect (2)'s wrong causality. It is corrected
here rather than by rewriting that commit, so the hashes the reviewer
cites keep resolving.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GhNPM6rGcuzxocM1nATnuM
This commit is contained in:
HermenixandClaude Opus 5 committed 2026-10-04 03:46:53 +00:00
1 parent f931858f30
commit b1f2744cf0
5 files changed
+439 -106

No files matched your search

+84 -17
View File
@@ -1,5 +1,33 @@
# Keyboard input for sessions
> **Superseded in eight places. Read this first.**
>
> `docs/plans/2026-10-04-keyboard-verification.md` is an adversarial review of
> this file against the tree and against Hyprland v0.56.2. Its verdict is "safe
> to build on, not safe to implement as written", and the eight rows of its
> **"Changes required before code"** table **override this document wherever
> they differ**. Each one is also folded into the text below, marked
> `[SUPERSEDED]`, so nobody following a single paragraph gets the contradicted
> version:
>
> | # | What changed |
> | --- | --- |
> | 1 | Exit 2 vs `driver_refused` — §2's exit-code paragraph was wrong about what `_drive` does |
> | 2 | The keymap `size` includes the trailing NUL; `format = 1`; `time` is `_now_ms()` |
> | 3 | `release_all` no-ops its key half with no keyboard, and ends with `modifiers(0,0,0,0)` |
> | 4 | `input:virtualkeyboard:release_pressed_on_close = true` — destroy-while-held is no longer an open question |
> | 5 | The layout reaches the keymap **only** as `--xkb-layout` on the driver unit; no `[keyboard]` TOML table |
> | 6 | The modifier-keysym set is measured from the keymap; no Shift special case |
> | 7 | Stage 0's expectations, and `keyboard down` warns unconditionally |
> | 8 | Acquire's stderr mentions keyboard verbs; refusals carry a scalar index, never the string |
>
> **Stage 0 has run** (`tests/README-keyboard-probe.md`, with its transcript).
> The three open behavioural questions are answered, and one answer is worse
> than this document assumes: **a single idle warp does not move keyboard
> focus**, so `pointer acquire` — which is one warp — can leave the first key
> of a lease going to whatever was already focused. §6 risk 1 still holds and
> the fallback is still not built in Stages 1–2.
Typing stops being a non-goal. `docs/PLAN-workspaces-and-pointer.md` §1 defers it, and §6.7 already specifies the shape: same seat, same serialisation, `zwp_virtual_keyboard_manager_v1`, and the existing pointer lease rather than a new lock. Stages 0–3 of that plan are what the tree implements today (broker lease in `src/hhstreamd/pointer.py`, driver in `src/hhstream_pointer/`, CLI in `src/hhstream_session/__init__.py`). This plan is §6.7, with one correction noted under lease semantics.
The Chrome path in `examples/agent-eyes-demo.py` (`Input.insertText`) is not this feature. It never touches the seat. This plan is for whatever window is focused on the compositor's one seat.
@@ -23,6 +51,14 @@ The Chrome path in `examples/agent-eyes-demo.py` (`Input.insertText`) is not thi
- **Keycode, not keysym, on the wire to the compositor.** `key` takes a Linux evdev code (the same value `wl_keyboard.key` carries; clients add 8 to reach an XKB keycode). Keysym names stay on our socket, the way button names stay on ours and evdev codes cross into `zwlr_virtual_pointer_v1` (`src/hhstream_pointer/buttons.py`).
- **Keymap upload is mandatory.** Until `keymap` is sent (format `xkb_v1`, memfd of an XKB text keymap), clients cannot decode a key to a character. Upload **once**, after connect and before `listen`, matching `__main__.py`'s rule that a listening socket is a promise the device works. Do not upload again per string: a second `keymap` resets client state under held keys.
**[SUPERSEDED — change 2.]** Three values this bullet left unstated, each of which fails silently:
- the `size` argument **includes the trailing NUL**. Hyprland `mmap`s exactly `size` bytes and hands the pointer to `xkb_keymap_new_from_string`, which wants a C string, so `size = len(text)` reads off the end of the mapping. The symptom is a keymap that will not compile, which from our side is indistinguishable from a compositor with no keyboard at all;
- the fd must outlive a **round trip**, not a flush: the compositor has to have received and mapped it before we close our end;
- `format` is the integer **1** (`XKB_KEYMAP_FORMAT_TEXT_V1`). Hyprland ignores it and parses as `TEXT_V2`, which accepts a V1 string; do not send 2;
- `time` on every `key` is `backend._now_ms()`, the same monotonic source the pointer requests use. The protocol requires one clock per object.
Also, a *second* upload is worse than "resets client state": Hyprland replaces its XKB state without walking the keys it believes are down, so re-uploading under a held modifier strands it.
- **No unicode request.** A codepoint is typeable only when the uploaded layout has a keysym for it. No `Ctrl+Shift+u`, no per-string custom keymap, no compose sequences in v1.
- **Modifiers are a separate request.** The compositor does not derive the modifier mask from `key`. Shifted text needs `modifiers` as well as the letter key. Details in §4.
- **No per-output target.** Unlike `create_virtual_pointer_with_output` (`backend.py`), a virtual keyboard is seat-global. Keys hit whichever surface has keyboard focus. There is no output argument to add.
@@ -60,6 +96,14 @@ hhstream session keyboard up ID NAME
Extend `src/hhstreamd/protocol.py` (do not renumber `ExitCode`). Same codes as pointer: **8 BUSY** only on a second acquire, **9 NO_LEASE** when this session does not hold the lease, **2 USAGE** for a bad keysym or an unmappable character, **10 COMPOSITOR** when the driver has no keyboard global or the connection dies.
**[SUPERSEDED — change 1.]** "Exit 2 for a bad keysym" and "`Rejected`, same as a bad button" are not the same code, and this paragraph asserted both. `SessionManager._drive` turns *every* driver `ok: false` into `ManagerError("driver_refused")`, which is exit **10** — that is why `test_an_unknown_button_is_refused_by_the_driver_not_invented` asserts `driver_refused` and not usage. Exit 2 happens only for an `invalid_argument` the broker raises *before* `_drive`. So:
- the **broker** checks shape before it calls the driver: `text` must be a string, `state` must be `down`/`up`, `key` must be a non-empty string, and `text` must be within the 4096-scalar cap. Those are `invalid_argument`, exit 2;
- the **driver** tags a rejection it caused the caller to earn with a stable token, `kind: "invalid_argument"` (`hhstream_pointer.ops.KIND_INVALID`) — a bad keysym, an unmappable character, a dead key, a `type` under a held non-modifier. `_drive` maps that token to `invalid_argument`, exit 2;
- everything else keeps `kind: "refused"` and stays `driver_refused`, exit **10**: no keyboard global, no aimed output, a dead connection.
The token exists because the alternative is the broker telling "no such keysym on your layout" from "this compositor has no keyboard" by matching on English.
| Verb | Request beyond `verb`, `request_id` | Response |
| --- | --- | --- |
| `keyboard.key` | `id`, `lease_id`, `key`, `state` (`down`/`up`) | `keys[]` |
@@ -75,6 +119,13 @@ Cap `text` at **4096** Unicode scalars in both broker and driver. Over the cap i
**Audit:** `keyboard_key` records the keysym name and state. `keyboard_type` records `chars` (an integer) and **not the text**. Typed strings will include passwords; the audit log is the wrong place for them.
**[SUPERSEDED — change 8.]** `events.jsonl` is not the only place a string leaks, and the plan secured only that one. Two more:
- **Refusal messages and driver logs carry the scalar *index*, never the character and never the string.** "unmappable at scalar 3" is the whole of what a reader needs, and the alternative ends up in the journal. `AuditLog.emit` will happily write a `text` field if a caller passes one, so the rule is about every message, not only the audit event.
- **`pointer acquire`'s stderr is wrong once this lands.** It says "expires in … with no further **pointer** verb". A `keyboard.*` verb goes through `_refresh` and *does* move `expires_at`, so the sentence has to name both — otherwise an operator releases during a `type` that would have kept the lease, and the TTL test looks flaky against the help text.
(What the shell and `ps` show of the CLI argument is outside this rule: the text is an argv word by the time anything here sees it.)
### Driver socket (`CONTRACT-sessions.md` §3.4)
The driver stays an executor with no lease (`ops.py` docstring, `driver.py` docstring). New ops:
@@ -91,6 +142,11 @@ There is no keyboard `frame`. `zwp_virtual_keyboard_v1` has none. Do not reuse t
`pressed` and `release_all` grow key fields. Do not add a parallel `release_all_keys` op. Expiry has one call site (`SessionManager._expire_pointer`).
**[SUPERSEDED — change 3.]** Two things follow from there being exactly one call site, and this plan stated neither:
- `release_all` must **no-op its key half when no virtual keyboard exists**. If the key half raised, the one `release_all` would abandon the buttons it had just been asked to lift — and a lease that expired with a mouse button down is the failure the whole TTL exists to prevent.
- `release_all` ends with `modifiers(0, 0, 0, 0)` **whenever a mask was set**, because a virtual key-up clears no modifier state on this compositor. Without it a lease that ended under Shift hands the next holder a keyboard where every letter is a capital. One `modifiers(0, 0, 0, 0)` also goes out immediately after the initial keymap upload, so a previous driver's mask is not inherited.
Unknown keysym, non-finite or over-long text, and `type` while a non-modifier key is held are `Rejected` (answered, connection kept), same as a bad button.
### File-by-file
@@ -108,13 +164,13 @@ Unknown keysym, non-finite or over-long text, and `type` while a non-modifier ke
| `src/hhstreamd/pointer.py` | Not a new class. On `_Held`, a `keys` dict beside `buttons`. `press_key` / `unpress_key` / `keys_pressed`, mirroring `press` / `unpress` / `pressed`. `expire()` still returns `LeaseInfo` only — no keys. Callers read `keys_pressed()` first, as they must read `pressed()` first (`CONTRACT-sessions.md` §3.3). |
| `src/hhstreamd/manager.py` | `keyboard_key` and `keyboard_type` go through `_refresh` (live session, holder, not expired, container output required). Driver first, then the lease mirror — the `pointer_button` order, so a refused key is not recorded as down. `_expire_pointer` reads keys before `expire()` and uses the one `release_all`. Same on `pointer_release`, kill, reap, and driver loss. |
| `src/hhstreamd/protocol.py` | Verb allowlist plus the mutation set. |
| `src/hhstreamd/policy.py` | `[keyboard]` next to `[pointer]`. |
| `src/hhstreamd/policy.py` | **[SUPERSEDED — change 5.] No change.** A `[keyboard]` table here would be read by nothing: `settings_from_dict` is read by `hhstreamd`, and the driver is a *different unit* that never opens that file. An operator could change the layout and every injected key would stay on `us`. The layout travels as `--xkb-layout` on the driver's argv, and nowhere else. |
| `src/hhstream_session/__init__.py` | `_build_keyboard` beside `_build_pointer`. |
| `src/hhstream_session/format.py` | `render_pointer_state` shows held keys. |
| `src/hhstream_session/lease.py` | No new store. `pointer-leases.json` remains the cache. |
| `nix/module.nix` | No new unit. Extend `hhstream-pointer.service` argv. Emit `[keyboard]` into the generated TOML the way `[pointer]` is emitted. Options under `sessions.keyboard`: `layout` (default `"us"`), `variant` (default `""`), `options` (default `""`), `model` (default `"pc105"`). |
| `nix/module.nix` | No new unit. Extend `hhstream-pointer.service` argv — **and nothing else**: **[SUPERSEDED — change 5]** the `[keyboard]` TOML emission is dropped, see `policy.py` above. Options under `sessions.keyboard`: `layout` (`lib.types.strMatching "[A-Za-z0-9_-]+"`, default `"us"` — the type is what refuses a comma-separated list), `variant` (default `""`), `options` (default `""`), `model` (default `"pc105"`). The driver also refuses a comma itself, before `xkb_keymap_new_from_names`, because the NixOS type cannot reach a binary run by hand. §3.4's "command line the module will pass, exactly" and the unit comment quoting it are amended in the same change. |
| `nix/package.nix`, `flake.nix` devshell, `pyproject.toml` | `xkbcommon` for the driver and for unit tests. No new console script. |
| `nix/hyprland-conf.nix` | Keep `input:follow_mouse = 1`. Extend the comment: keyboard events have no output, so this warp is what moves keyboard focus, and the lease is what stops another session stealing it mid-string. |
| `nix/hyprland-conf.nix` | Keep `input:follow_mouse = 1`. Extend the comment: keyboard events have no output, so the warp is what moves keyboard focus — but see §6 risk 1 and Stage 0, because **one** warp does not — and the lease is what stops another session stealing it mid-string. **[SUPERSEDED — change 4]** Also set `input:virtualkeyboard:release_pressed_on_close = true`, with the note that it releases keys and still does not clear the modifier mask. |
| `docs/CONTRACT-sessions.md` | Amend §3.3 (key mirror, `expire()` still carries no keys), §3.4 (ops above), §4 (verbs, idle rule). |
| `README.dev.md` item 3, `checks/vm-pointer.nix` header | Stale relative to the conf file as read: they still say `hyprland-conf.nix` ships `follow_mouse = 0` and that the keyboard task will choose. The conf file sets `1`. Fix the prose when implementing; do not set the conf back to `0`. |
@@ -184,12 +240,19 @@ Do not query `hyprctl getoption` to fill a default. The broker's rule is that un
- If any **non-modifier** key is already held, `type` is rejected and emits nothing.
- Validation is complete before the first sink call. Unmappable character → the whole request fails, no prefix typed. This includes `é` on `us`.
- Dead keys (`dead_acute` and the like) are a rejection even if the layout names them. v1 does not emit a two-event compose. `us(intl)` is therefore a poor choice until a later stage; default `us` does not need it.
- No auto-repeat timer in our process. Whether Hyprland repeats a virtual key that we leave down is unverified (Stage 0).
- No auto-repeat timer in our process. **[SUPERSEDED — change 7, and Stage 0 has measured it.]** Hyprland does not repeat on the wire: a key held 1.5 s produced exactly one `wl_keyboard.key`, and it publishes `repeat_info rate=25 delay=600` so the *client* repeats. That is not good news — a focused text field will insert characters from that one press until the key-up or the TTL — so the `down` help text warns **unconditionally** rather than only if a probe saw repeats, and v1 has no rate to offer because we do not generate them.
**Modifier decision:** for a shifted character, send `modifiers(shift_mask, 0, 0, 0)` and the letter's `key` down/up, then restore the previous mask. Do **not** also synthesize `Shift_L` down/up for that character. For an explicit `keyboard down Shift_L`, send the Shift **key** and a matching `modifiers` update, and remember both in the held-key record so `release_all` undoes both. Sending both a synthetic Shift key and a mask for an ordinary capital is how toolkits apply Shift twice or not at all; the VM check in §5 is what proves the letter path against a real `wl_keyboard` client.
Named non-character keysyms used by `key`/`down`/`up` go through the same resolver, not a second table that can disagree with the layout. `buttons.py` can stay a hand-written evdev table because the protocol takes those codes directly; keysyms cannot.
**[SUPERSEDED — change 6.]** This section never defined "modifier", and a Shift-only reading of it is wrong: `@` on `de` is a **level-three** symbol, so a resolver that only knew about Shift would type the wrong character. The definition is *measured from the keymap*, not listed — press each keycode in a throwaway XKB state and read the serialised masks back:
- a non-zero **depressed** mask and no locked mask makes it a **modifier**: on `us`/`pc105` that is exactly `Shift_L/R`, `Control_L/R`, `Alt_L/R`, `Super_L/R`, `ISO_Level3_Shift`, `ISO_Level5_Shift`. (`Meta_L/R` and `Hyper_L/R` are canonical modifier keysyms that **no keycode on this layout carries** — which is the argument for measuring rather than listing.)
- a non-zero **locked** mask makes it a **lock**: `Caps_Lock`, `Num_Lock`. A lock is not a modifier, and `type` refuses while one is held rather than producing a case nobody asked for.
The resolver returns `(evdev code, mask)` for a keysym at *any* level, so one code path serves `us` and `de`. And `key`/`type` never call `_aimed()`: a keyboard has no output, so demanding a prior warp would refuse a caller who only ever wanted to type.
---
## 5. Tests
@@ -205,7 +268,7 @@ Match the split already in the tree: the dispatcher is tested against a recordin
| `tests/pointer/test_lease.py` | `press_key` / `keys_pressed` order. `expire()` still returns no key list; the test reads `keys_pressed()` first, then `expire()`, then sees an empty lease. Existing busy/stale/`lease_id` cases stay as they are. |
| `tests/pointer/test_vendored_protocol.py` | Interface name `zwp_virtual_keyboard_manager_v1` and requests `keymap`, `key`, `modifiers`. No display. |
| `tests/sessions/unit/test_keyboard_verbs.py` | New, harness copied from `test_pointer_verbs.py`. No lease → 9. Other session holds the lease → 9 (not 8). Second `pointer.acquire` while typing → 8. `type` refreshes TTL: advance the `ManualClock` by less than `ttl` after a type and the lease survives; advance past it and `release_all` runs with the held key. Driver rejection does not stick the key in the lease. `type` does not move `last_activity_boottime`. `pointer.release` and kill both lift keys. `pointer.state` includes `keys`. |
| `tests/sessions/unit/test_settings.py` | `[keyboard]` defaults to `us`; a non-table is `PolicyError`; `us,ru` is rejected. |
| ~~`tests/sessions/unit/test_settings.py`~~ | **[SUPERSEDED — change 5.] Dropped.** A TOML default of `us` that nothing uploads is precisely the false pass that file's own docstring warns about. Replaced by `tests/pointer/test_driver_flags.py`: an omitted `--xkb-layout` is `us`, `de` is `de`, and `us,ru` exits 2 **with an injected sink proving the compositor was never touched**. |
| CLI surface test (`tests/sessions/unit/test_cli_surface.py`) and broker verb list (`test_broker_protocol.py`) | `keyboard` in help; help says the pointer lease is required; `keyboard.type` / `keyboard.key` are known verbs and are in the mutation set. |
`nix develop -c python -m pytest tests/pointer tests/sessions/unit -q` is the gate. Not run for this plan.
@@ -229,9 +292,11 @@ Match the split already in the tree: the dispatcher is tested against a recordin
### Risks
- **Focus may not follow a virtual pointer.** The conf comment says `follow_mouse = 1` was set so pointer motion moves keyboard focus, after `vm-pointer` measured that `follow_mouse = 0` delivers clicks to nobody when the aimed window is unfocused. That measurement was pointer delivery, not `wl_keyboard.enter`. Unverified for a `zwlr_virtual_pointer_v1` warp. If Stage 0 shows no `enter`, the fallback is one existing IPC call — `dispatch focuswindow` on the session's `window.stable_id` — immediately before the first key of a lease. Do not build that fallback in Stages 1–2.
- **Hard death of the virtual keyboard can leave a key down inside Hyprland** if destroy does not release keys. Unverified on this build. Our shutdown path sends key-ups first (`_lift_everything`). A killed `-9` driver skips it. Do not add a retry loop the button path does not have.
- **Auto-repeat.** If Hyprland repeats a virtual key we leave down, `keyboard down a` floods the window until TTL (default 30 s). Stage 0 records whether it repeats. If it does, the help text says so; v1 still has no repeat-rate control. Chords (`Control_L` held across a `type`) are the justified use of `down`.
- **Focus does not follow a single virtual-pointer warp. [MEASURED — Stage 0, and this is the headline risk of the feature.]** One `motion_absolute` onto an unfocused window, after the cursor had been still for 0.8 s, delivered `wl_pointer.enter` and **no** `wl_keyboard.enter`; the focus change arrived only after a *later* motion that changed the floored pixel. The mechanism is `InputManager::onMouseWarp` → `mouseMoveUnified(refocus=false)`: the delta is set to 0 when the previous movement was over 0.5 s ago, `mouseMoveUnified` returns early when the floored pixel did not change at all, and keyboard focus is that delta compared against `input:follow_mouse_threshold` (measured 0.0, unset). Transcript in `tests/README-keyboard-probe.md`.
**`pointer acquire` is one warp**, so the first key of a lease can land in whatever was already focused. The fallback is the one named below — `dispatch focuswindow` on the session's `window.stable_id`, immediately before the first key of a lease — and **it is still not built in Stages 1–2.** Two things that are *not* the fix: warping twice to the same bookmark (the same floored pixel returns early), and waiting longer after the warp (the first warp's settle window was 0.4 s and contained the pointer enter alone). Stage 3's enter subtest must not be written against acquire's single warp.
- **Destroy of the virtual keyboard leaves a key down inside Hyprland. [MEASURED — Stage 0.]** `destroy` with a key held, with a second virtual keyboard keeping the seat's capability up, delivered no key-up; `input:virtualkeyboard:release_pressed_on_close` is `0` and unset. Worse than "stuck": `InputManager::onKeyboardKey` drops a *press* whose code is already in the seat's `m_pressed`, so the next driver's press of that code is ignored and the key is **dead** until something sends a matching up. Our shutdown path sends key-ups first (`_lift_everything`); a `-9` skips it, which is why **[change 4]** `nix/hyprland-conf.nix` now sets `release_pressed_on_close = true`. That setting emits key-ups only and still never clears the modifier mask, so `release_all` keeps sending `modifiers(0, 0, 0, 0)` regardless. Still no retry loop the button path does not have.
- **Auto-repeat is the client's, which does not make it harmless. [MEASURED — Stage 0.]** `press_count=1` over a 1.5 s hold, with `repeat_info rate=25 delay=600` published at bind time. So the flood is real and it is foot/GTK/Qt producing it from our one press, for as long as the key is down — up to the TTL (default 30 s). **[SUPERSEDED — change 7]** the help text for `down` therefore warns unconditionally; the old "if it does, the help text says so" is the false pass the review named. v1 has no repeat-rate control, and `zwp_virtual_keyboard_v1` has no `repeated` state to ask the compositor about. Chords (`Control_L` held across a `type`) remain the justified use of `down`.
- **Mask versus Shift keycode.** §4's letter path can still be wrong for a toolkit that ignores `modifiers` and only shifts when it sees `KEY_LEFTSHIFT`. The VM victim must print both the mask and the decoded sym. Chromium is not the first victim (`vm-pointer` avoided it; it is expensive and the app-id rule in `README.dev.md` item 4 only binds clients that honour `$HHSTREAM_APP_ID`).
- **The lease is not a security boundary.** `PLAN` §6.6: any client may bind the pointer global. The keyboard global is the same. Stage 4 sandboxing is unchanged and out of this work.
- **Concurrent typing is impossible** on one compositor, for the same reason concurrent pointers are (`PLAN` §1). A second seat is Stage 5 and still CPU-gated. This work does not pretend otherwise.
@@ -239,21 +304,23 @@ Match the split already in the tree: the dispatcher is tested against a recordin
### Open questions
1. Stage 0 global name and version on the actual `/run/hypr-stream` socket. §6.7's [RAN] is the claim; this session did not repeat it.
2. Does acquire's warp produce `wl_keyboard.enter` on the aimed window under the shipped `follow_mouse = 1`?
3. On virtual-keyboard resource destroy, does Hyprland release keys that were down?
4. Does Hyprland auto-repeat those keys?
5. Operator: is default layout `us` acceptable for this machine, or must the NixOS option be set to something else before the VM check is written?
Questions 1–4 are **closed by Stage 0** (`tests/README-keyboard-probe.md` and its transcript). Question 5 is answered by the operator.
1. ~~Stage 0 global name and version on the actual `/run/hypr-stream` socket.~~ **`zwp_virtual_keyboard_manager_v1` at version 1.** No `wp_virtual_keyboard_v1`. The gate holds.
2. ~~Does acquire's warp produce `wl_keyboard.enter`?~~ **No — not from a single idle warp.** See risk 1 above; this is the one answer worse than the plan assumed.
3. ~~On destroy, does Hyprland release keys that were down?~~ **No.** See risk 2.
4. ~~Does Hyprland auto-repeat those keys?~~ **Not on the wire; the client does.** See the auto-repeat risk.
5. **Answered: `us`, and configurable.** The operator's decision is a NixOS option in the `hhstream` namespace, string, default `"us"`, documented in `README.dev.md` — reaching the keymap as `--xkb-layout` on the driver unit, per change 5.
6. A later stage, only if agents must type arbitrary UTF-8: a throwaway keymap that maps spare keycodes to `0x01000000 + codepoint` for the duration of one `type`, then restores the layout keymap. Not v1. It reintroduces the "upload resets held modifiers" problem, so it has to refuse to run while any key is held.
### Stages
| Stage | Work | Rough size | Gate |
| --- | --- | --- | --- |
| 0 | Read-only. Dump globals. One tiny client, or a few minutes in the existing VM, to record `enter`, repeat, and destroy-while-held. Write the results down next to the check. No broker changes. | S, about half a day | Named global is `zwp_virtual_keyboard_manager_v1`. Anything else stops the project. |
| 0 | **Done.** `tests/keyboard_probe.py`, its README and its transcript. Two windows, not one; read-only `hyprctl` for the boxes; `(a1)` and `(a2)` measured separately; no `hyprctl dispatch`. | S | **Passed.** Named global is `zwp_virtual_keyboard_manager_v1` v1. |
| 1 | Driver: vendor, `keymap.py`, ops, backend upload, `__main__` flags, pointer unit tests. Pointer still runs if the global is missing. | M, about 3–5 days | `pytest tests/pointer` green. `type` of an unmappable character emits no events. |
| 2 | Broker mirror, verbs, CLI, policy, module argv, session unit tests, contract doc amendments, stale `follow_mouse` comments. | M, about 2–4 days | `pytest tests/pointer tests/sessions/unit` green. Expiry test shows `release_all` lifting a held key. No new unit file under `nix/module.nix` beyond argv and TOML. |
| 3 | `vm-keyboard.nix` and the keyboard target client. | M, about 2–3 days | Characters on A, silence on B, key-up after a real TTL, second acquire is 8. Red if the keymap was not uploaded. |
| 4 | Only if Stage 0 or Stage 3 shows no `wl_keyboard.enter` after warp. `focuswindow` via the broker's existing compositor IPC, then re-run Stage 3. | S, about a day, contingent | The Stage 3 enter assertion goes green without loosening it. |
| 2 | Broker mirror, verbs, CLI, module argv, session unit tests, contract doc amendments, stale `follow_mouse` comments. **No `policy.py` and no TOML table** (change 5). | M, about 2–4 days | `pytest tests/pointer tests/sessions/unit` green. Expiry test shows `release_all` lifting a held key. No new unit under `nix/module.nix`, and nothing there beyond argv. |
| 3 | `vm-keyboard.nix` and the keyboard target client. **Do not design its enter subtest from acquire's single warp** — Stage 0 says that does not focus. | M, about 2–3 days | Characters on A, silence on B, key-up after a real TTL, second acquire is 8. Red if the keymap was not uploaded. |
| 4 | **No longer contingent: Stage 0 showed no `enter` after a single idle warp.** `focuswindow` via the broker's existing compositor IPC, immediately before a lease's first key, then re-run Stage 3. Still not to be built in Stages 1–2. | S, about a day | The Stage 3 enter assertion goes green without loosening it. |
Rollback of Stages 1–2 is reverting the commit: old brokers never send `key`/`type`, and an old driver rejects unknown ops with `ok: false` (`ops.py` already answers unknown `op` instead of dropping the connection). No registry schema bump. Bookmarks stay as they are.
+128
View File
@@ -0,0 +1,128 @@
# Stage 0 review — keyboard probe
Reviewed `d07a1fd` (the plan fold-in) and `19e484b` (the probe, its README, and `tests/keyboard-probe-2026-10-04.txt`) against §B1 of `docs/plans/2026-10-04-keyboard-verification.md`. The three probe files are that commit, not an untracked add-on. Dirty Stage 1 files in the worktree were not reviewed and were not touched. The probe was not re-run: this environment has no `HYPRLAND_INSTANCE_SIGNATURE`, so the judgement is the committed transcript read against the script that prints those answer strings.
## Verdict
**Yes-with-fixes.** The run measured the gate and questions (a1), (b)'s key, and (c). The write-up then says things the log does not say, and `d07a1fd` did not edit the plan. Do not design Stage 3 from the README's (a) excerpt or from its mask sentence. The raw log, read with the script, is usable.
## What the evidence actually shows
The script is the B1 sequence with three real deviations and one hole. It is not a one-window probe, it does not call `hyprctl dispatch`, it refuses a runtime directory that does not contain exactly one `wayland-*` (`tests/keyboard_probe.py:378-389`), it dumps every global as `global <name> v<version>` (`:759-760`) and returns 2 when `zwp_virtual_keyboard_manager_v1` is missing or not version 1 (`:761-770`). `sym` is `xkb_state_key_get_one_sym(code+8)` on a state built from the keymap fd, updated with `update_mask` (`:575-609`, `:627-632`). Cleanup sends `key(30, released)` and `modifiers(0,…)` on a new virtual keyboard and prints `cleanup=sent` (`:940-945`). Deviations, all visible in the log: the keymap is uploaded before the windows rather than after (a); the idle wait is 0.8 s not 0.6 s; (a2) is 0.4 s after (a1), not immediate.
### Gate
Log lines 6–75 are the registry. Line 71 is `global zwp_virtual_keyboard_manager_v1 v1`. No `wp_virtual_keyboard_v1` line. Line 76: `ANSWER 1: zwp_virtual_keyboard_manager_v1 is present at version 1.` Line 59: `zwlr_virtual_pointer_manager_v1 v2`. That is the gate. The project continues.
### (a)
**The log does not prove "a warp onto an unfocused window delivered `wl_keyboard.enter`."** That sentence is the natural reading of the README's annotation "focus, one warp late" (`tests/README-keyboard-probe.md:129`) and of the commit message, which hangs both results on "warping into the margin that belongs to the first alone." The warp into that margin is (a1). It did not deliver keyboard enter.
What the log actually contains, in order:
```
108| (a1) one warp after 0.8s of stillness
109| (a1) -> wl_pointer.enter surface=kb-probe-a at 13,7
110| (a2) a second warp, immediately, still inside the same window
111| (a2) -> modifiers depressed=0 latched=0 locked=0 group=0
112| (a2) -> leave surface=kb-probe-b
113| (a2) -> enter surface=kb-probe-a serial=371 keys=[]
117| a1_enter=no a2_enter=yes pointer_reached_kb-probe-a=yes
```
(a1) is the warp onto unfocused `kb-probe-a`. The only event in its bucket is `wl_pointer.enter` at 13,7, which is the chosen point: target `0.0100,0.0100` (log 107) on a 1280×720 output is about (12.8, 7.2), and B's box starts at 120,80 (log 105), so the point is inside A only. No `enter surface=kb-probe-a` keyboard line in that bucket. `a1_enter=no` is true, and the `startswith` test (`keyboard_probe.py:820-825`) is what keeps `wl_pointer.enter` from counting. Map-time focus was B (log 89–90 and 106), so this is not the one-window false pass.
The keyboard `leave`/`enter` are the next bucket. That bucket is the second `motion_absolute` (`keyboard_probe.py:816`: same x, y plus 0.004), sent while the pointer was already on A. There is no second `wl_pointer.enter`, because the probe does not listen for `wl_pointer.motion` and pointer focus did not change. So the leave/enter arrived on the motion *after* the warp onto the window, not on the warp onto the window.
The sentence the log supports is: an idle `motion_absolute` onto unfocused `kb-probe-a` delivered `wl_pointer.enter` and no `wl_keyboard.enter`; `wl_keyboard.leave` of B and `wl_keyboard.enter` of A (serial 371, `keys=[]`) were observed only in the settle window after a later `motion_absolute` that stayed inside A.
Line 118's narrower claim — "one idle warp did NOT deliver enter; the SECOND warp did" — matches the buckets, with two caveats the file does not write down. The second request is not "immediate": `question_focus` pumps `SETTLE_S` (0.4 s, `keyboard_probe.py:124` and `:812`) and prints the (a1) lines before sending it, and the banner hardcodes the word (`:815`). And it is not a repeat of the same point. In the v0.56.2 `InputManager.cpp` on this machine, `mouseMoveUnified` returns immediately when the floored pixel did not change (`:239-240`), *before* it adds to `m_mousePosDelta` (`:253-256`). Keyboard focus is that delta compared with `follow_mouse_threshold` (`:711-715`). Log 98 says the threshold is 0 and unset, so any non-zero floored distance inside 0.5 s focuses, and a second warp to the same floored pixel does nothing. 0.004 of 720 px is about 3 px, so this nudge cleared that bar. The log never prints the second point, so a reader cannot see that it moved.
`pointer acquire` is one `_warp` (`src/hhstreamd/manager.py:1620`). The consequence that the first key of a lease can hit whatever was already focused follows from (a1) alone, and (a1) supports it. It does not follow from "the landing warp delivered enter, one warp late."
The README excerpt is not the log. It claims a verbatim transcript (`README-keyboard-probe.md:90-91`) and then prints `serial=336` (`:129`). This run's (a2) enter is serial 371 (log 113). Setup enters are 357 and 365 (log 84, 90), so 336 cannot be this run's focus change. The excerpt also drops log 111 (a `modifiers` line *before* `leave`) and the two `configured` lines that follow the enter (log 115–116). "Reproduced across six runs" (`README:89`) has one transcript.
### (b)
**No release: the log shows it. Mask not cleared: the log does not show what that sentence means.**
```
127| spare -> uploaded keymap format=1 size=35572
128| release_on_destroy=no mask_cleared=no
131| cleanup -> uploaded keymap format=1 size=35572
132| cleanup -> key code=30 state=0 sym=a
133| cleanup -> modifiers depressed=0 latched=0 locked=0 group=0
```
There is no `after destroy ->` line. The post-destroy pump is 1.0 s (`keyboard_probe.py:915-916`) and it recorded nothing: no `key code=30 state=0`, no `modifiers`. The script did not send a key-up or a `modifiers` before `destroy` (`:912`). The release it did send is after the verdict, labeled `cleanup ->`. B1's named false pass (counting step 7, or releasing before destroy) is not this log.
The spare keyboard does not weaken the "no release" half. It is created so the seat still has a keyboard (`:904-910`). Log 78–79 show why that matters: capabilities go `1` (pointer) then `3` (pointer|keyboard) only once a virtual keyboard exists, and the seat has no libinput keyboard. The spare never pressed code 30 — its only line is the local `uploaded keymap`. `shareKeyFromAllKBs` swallows a release only when some *other* sharing keyboard still has that code down (`InputManager.cpp:1891-1911`). The spare did not. Silence here is not "the release was delivered to a keyboard we stopped listening on."
The stronger evidence is log 132, which the ANSWER paragraph does not cite. `onKeyboardKey` drops a release whose code is not in the seat `m_pressed` (`InputManager.cpp:1669-1670`). A `state=0` for code 30 from a *new* keyboard means 30 was still in that set after `destroy`. If destroy had released it, the cleanup up would have been dropped and the client would not have seen `state=0`.
`mask_cleared=no` is a different predicate than the README's sentence. The code sets it when the post-destroy bucket contains `modifiers depressed=0` (`keyboard_probe.py:918-919`). The bucket is empty, so the flag is `no`. The depressed mask was already 0: the last modifiers lines are log 111 and 114, and the probe never sent `modifiers` with a non-zero mask. The held key is `KEY_A` (30), not Shift. "Destroy did not emit a modifiers event" is what was measured. "A non-zero mask survived destroy" was not. `releasePressed` emits key-ups only (`VirtualKeyboard.cpp:125-135`), so the source still says a mask would survive, but this run is not that measurement. Log 99 supports the option half only: `input:virtualkeyboard:release_pressed_on_close` is `{"int": 0, … "set": false}`.
The Shift story (`README:156-161`, `keys=[42, 0, 0, 0]`) is not in this transcript. Every `enter` here has `keys=[]` (log 84, 90, 113). Do not treat the zeros, or the claim that a key outlived the process, as data from this file.
The ANSWER's `kill -9` sentence is an inference. The transcript is an explicit `destroy` request. In this tree both that request and client disconnect call the same `CVirtualKeyboardV1Resource::destroy` (`VirtualKeyboard.cpp:38-39`, `:137-140`), which consults the option. Fair inference, not a second experiment.
### (c)
**The log shows exactly one press, and neither the spare, the window, nor `repeat_info` weakens that count.**
```
82| setup -> repeat_info rate=25 delay=600
121| key code=30 state=1 sym=a
122| press_count=1 repeat_info=(25, 600)
```
`press_count` counts `state=1` or `state=2` for code 30 inside the hold pump (`keyboard_probe.py:875-879`). One line, state 1, no state 2. The hold is `REPEAT_HOLD_S = 1.5` (`:120`), which is longer than the 600 ms delay on log 101, not shorter. A compositor that repeated at 25 Hz after 600 ms would have put on the order of twenty more `key` lines in the remaining 0.9 s. It put none. `repeat_info` was delivered at bind time (log 82), before the hold, which is when Hyprland sends it; printing the stored tuple next to the count is what B1 asked. It does not mean the compositor also repeated. The spare keyboard is created in `question_destroy`, after this section, so it is not in the (c) setup. The ANSWER text (log 123) already refuses the false pass: `press_count=1` is not "a text field will not flood." That part of the file is right, and it is the reading Stage 1 should keep.
`sym=a` is from the forwarded keymap, not a table. Log 80–81: uploaded `format=1 size=35572`, and `wl_keyboard.keymap format=1 bytes=35572 symbols=xkb_symbols "pc_us_inet(evdev)"`. The sizes match, which is consistent with the NUL-inclusive memfd (`keyboard_probe.py:312-326`) being what the compositor mapped. The symbols snippet is not the layout string `us`.
## Defects
1. **High. The (a) write-up states a causality the log does not have.** README `:114` and `:129`, and the `19e484b` message, read as "warping onto the unfocused window delivered keyboard enter, one warp late." Log 108–113 say the landing warp delivered `wl_pointer.enter` only, and leave/enter came on the next motion. "One warp late" is the wrong mechanism: the first warp's delta is set to 0 (`InputManager.cpp:255-256`); the enter belongs to the second motion's non-zero delta, not to a delayed effect of the first. Cheapest fix: replace the README excerpt with log 108–117 unchanged, and replace the annotation with the sentence in the (a) section above. Do not leave `serial=336` in the file.
2. **High. `d07a1fd` did not fold the eight changes into the plan.** `git diff 14b3f69 HEAD -- docs/plans/2026-10-03-keyboard-input.md` is empty. The commit adds `docs/plans/2026-10-04-keyboard-verification.md` and nothing else. The commit message is an accurate list of what that review says, and the review text itself is not softened. The plan text is unchanged, so anyone told to follow the plan (the untracked brief says that, and it repeats exit codes 8/9/2/10) still has the contradicted text. Cheapest fix: a banner at the top of `2026-10-03-keyboard-input.md` stating that the eight rows in the verification doc's "Changes required before code" table supersede the plan where they differ. Not done here.
3. **Medium. `mask_cleared=no` is reported as a measurement of a held mask.** README `:150-154`. The mask was 0 the whole time (log 111, 114; no `modifiers` request before destroy). Cheapest fix: one sentence in the README — destroy emitted no key-up and no modifiers event; a non-zero mask was not held, so this run does not show one surviving. Do not re-run unless Stage 2 wants a transcript of Shift specifically. Do not cite the unlogged `keys=[42, 0, 0, 0]` run.
4. **Medium. "A second warp" is underspecified in a way Stage 3 will copy.** The report never says the second point differed, and the same floored pixel returns before the focus test (`InputManager.cpp:239-240`). Cheapest fix: in the README, say (a2) moved about 3 px and that a second `motion_absolute` of the same point is not this result. Printing the second normalised point from `question_focus` would make the next transcript show it.
5. **Low. "Immediately" is hardcoded, and the gap is not logged.** 0.4 s plus the time to print (a1) is still under Hyprland's 0.5 s window, and the fact that (a2) focused is consistent with that. The word in log 110 is not a measurement. Cheapest fix: print the monotonic gap between the two `motion_absolute` calls. Not worth a re-run by itself.
6. **Low. Claims with no transcript.** "Six runs" (README `:89`) and the Shift enter (README `:156-161`). Cheapest fix: delete both, or attach the log. The committed transcript does not contain them.
Not defects: committing the probe (B1 said not to; the commissioning brief said to; the README says so); uploading the keymap before (a) (log 78–80: no keyboard capability until a virtual keyboard exists, so the listener could not have seen enter otherwise); idle 0.8 s instead of 0.6 s; fullscreen A so the two boxes are not the same 1040×560 (log 104–105 shows they were not); the spare keyboard, for the reason under (b).
## What Stage 1 must not build on
- **Do not assert `wl_keyboard.enter` on `pointer acquire`.** Acquire is one warp. (a1) did not enter. Stage 3's enter subtest stays red until a later motion that changes the floored pixel, or `focuswindow`. Do not "fix" it by warping twice to the same bookmark.
- **Do not read "one warp late" as "the enter is delayed, so wait longer."** The (a1) bucket was 0.4 s and contained the pointer enter. The keyboard enter was a different request.
- **Do not gate the `keyboard down` warning on this probe having seen repeats.** It saw one `wl_keyboard.key` and a `repeat_info` of 25/600. The warning stays unconditional. Log 123 already says this; the plan at `2026-10-03-keyboard-input.md:234` still says the opposite ("if it does, the help text says so").
- **Do not cite `mask_cleared=no` as proof a held Shift survives `destroy`.** Keep sending `modifiers(0,0,0,0)` because `releasePressed` never emits modifiers, not because this log held a mask.
- **Do not treat `keys=[42, 0, 0, 0]` as a measured poison.** This transcript's enters are `keys=[]`. The cleanup `state=0` (log 132) is the poison evidence, and it is for code 30 after an explicit `destroy`.
- **Do not expect the scanner to emit `keymap_format` or `key_state`.** The Hyprland XML this probe used names both and defines neither (`protocols/virtual-keyboard-unstable-v1.xml` in the v0.56.2 tree: the request text says "keymap_format enumeration" / "key_state enumeration"; the only enums in the file are `error`). The constants in `keyboard_probe.py:89-95` are the right workaround. The symbols line to match later is `xkb_symbols "pc_us_inet(evdev)"`, not the bare layout name.
- **Do not implement exit 2, the NUL, or the layout path from the 2026-10-03 plan text.** Those paragraphs were not updated. See carried objections.
## Carried objections
`d07a1fd` preserved the eight pre-code changes intact inside the verification doc and dropped them from the plan. Nothing in the eight was rewritten into something unimplementable. Where the plan still disagrees:
| # | Still binding, from the verification doc `:192-201` | Plan text that was not changed |
| --- | --- | --- |
| 1 | Broker checks shape and the 4096 cap. A driver token for a bad keysym or character maps to `invalid_argument` (exit 2). Missing global stays `driver_refused` (exit 10). | `:61` still says exit 2 for a bad keysym, which `_drive` turns into 10. |
| 2 | Keymap `size` includes the trailing NUL. `format = 1`. `time` is `_now_ms()`. | `:25` still says "memfd of an XKB text keymap" and never says `size == strlen + 1`. |
| 3 | `release_all` no-ops its key half when no virtual keyboard exists, and ends with `modifiers(0,0,0,0)` when a mask was touched. Also one `modifiers(0,…)` after the initial upload. | Not stated. |
| 4 | `input:virtualkeyboard:release_pressed_on_close = true` in `nix/hyprland-conf.nix`. The true setting still does not clear the mask. | `:233` still calls destroy-while-held unverified and does not set the option. This run confirms the default is 0 and that explicit destroy releases nothing. |
| 5 | Layout is `--xkb-layout` on the pointer unit. The driver rejects `,` before `xkb_keymap_new_from_names`. A `[keyboard]` table in the broker TOML is not the upload. | `:111`, `:115`, `:176`, `:208` still emit and test `[keyboard]` the way `[pointer]` is emitted. |
| 6 | The modifier-keysym set is written down. The resolver returns `(evdev, mask)` for any level. `key` / `type` do not call `_aimed()`. | `:189` still has the mask-vs-Shift decision and no keysym set. |
| 7 | Stage 0 expectations as B1 wrote them. `keyboard down` warns unconditionally. Two windows, or the enter result is a false pass. | `:234` and `:253` are still the vague originals. The probe did use two windows; the unconditional warning is the right reading of (c). |
| 8 | Acquire's stderr says keyboard verbs refresh the TTL. `Rejected` text and driver logs carry an index, not the string. | Not stated. |
Objection 4 of the verification doc (do not vendor Hyprland's XML; use wayland-protocols `unstable/virtual-keyboard/…`) is the one item this stage showed is not implementable on this nixpkgs. The protocol's wayland-protocols MR never landed; the file the review names is not where the README looked, and the Hyprland copy is the one the probe compiled. Carry the review's actual reason — the copy does not define the enums — not the path. Switching later, if a nixpkgs grows the file, is a one-line change and does not move the integers.
Unchanged and confirmed, so Stage 1 should not reopen them: `zwp_virtual_keyboard_v1` version 1 on the running compositor; no `wp_virtual_keyboard_v1`; one idle warp does not move keyboard focus under `follow_mouse = 1` and threshold 0; do not build `dispatch focuswindow` in Stage 1.
Stage 1: implement from the eight rows in `docs/plans/2026-10-04-keyboard-verification.md`, not from the unedited 2026-10-03 plan; do not assert `wl_keyboard.enter` on acquire's single warp, do not treat a second warp to the same point as the fix, and do not cite `mask_cleared=no` as a held-mask result.
+126 -52
View File
@@ -49,6 +49,18 @@ protocol rather than growing a second copy.
Flags: `--runtime-dir` (default `/run/hypr-stream`), `--xml`, `--output` (only
needed if the compositor has more than one), `--xkb-layout`, `--xkb-model`.
### Where it deviates from the review's §B1 sequence
All three are visible in the transcript and none of them changes an answer:
- the keymap is uploaded **before** the windows are opened, not after. It has
to be: the seat has no libinput keyboard, so `wl_seat.capabilities` does not
include `keyboard` until a virtual one exists (the setup block goes `1` then
`3`), and a listener bound any later would have seen nothing at all;
- the idle wait before (a1) is 0.8 s rather than 0.6 s;
- (a2) follows (a1) after the settle window and a print — measured at 0.401 s
rather than being "immediate", and still inside the 0.5 s that matters.
Exit codes: **2** if `zwp_virtual_keyboard_manager_v1` is missing or is not
version 1 — the gate the plan says stops the project — and 0 otherwise. The
answers are in the output, not in the exit status: a measurement that came back
@@ -85,10 +97,14 @@ path.
## What it answered
Run 2026-10-04 against the live `/run/hypr-stream`: Hyprland 0.56.2, one output
`Virtual-1` at 1280x720, two Chromium windows already on screen. Reproduced
across six runs. Full transcript, verbatim:
[`keyboard-probe-2026-10-04.txt`](keyboard-probe-2026-10-04.txt).
One run, 2026-10-04, against the live `/run/hypr-stream`: Hyprland 0.56.2, one
output `Virtual-1` at 1280x720, two Chromium windows already on screen. The
committed transcript is that run and nothing else —
[`keyboard-probe-2026-10-04.txt`](keyboard-probe-2026-10-04.txt) — and every
excerpt below is copied from it, with the line numbers to check it against. An
earlier draft of this file claimed several reproductions and quoted a serial
from a run it had not kept. If a claim here is not in that file, it is not
evidence.
The configuration the answers depend on, as the compositor reports it:
@@ -103,68 +119,121 @@ input:kb_layout = us (default)
### 1. The global — the gate the whole project hangs on
**`zwp_virtual_keyboard_manager_v1` is present at version 1.** §6.7's `[RAN]`
claim holds against the running binary. `wp_virtual_keyboard_v1` is not
**`zwp_virtual_keyboard_manager_v1` is present at version 1** (transcript
line 71, answered on line 76). §6.7's `[RAN]` claim holds against the running
binary. `wp_virtual_keyboard_v1` is not
advertised, as both plans predicted. `zwlr_virtual_pointer_manager_v1` is at
v2, so the driver's existing version-2 requirement is still met. The project
continues.
### (a) Does a virtual-pointer warp move `wl_keyboard` focus?
**One idle warp: NO. A second warp immediately after: YES.** Exactly what the
review's read of `InputManager::onMouseWarp` predicted, and the reason it
insisted (a1) and (a2) be measured separately.
**One idle warp onto an unfocused window: NO.** It moved the cursor and
nothing else. The keyboard focus change arrived only after a *later*
`motion_absolute`, and it belongs to that motion rather than to the first.
Transcript, lines 104–120, unedited:
```
box kb-probe-a at 0,0 size 1280x720 <- fullscreen, unfocused
box kb-probe-b at 120,80 size 1040x560 <- focused: it mapped last
chosen warp target 0.0100,0.0100 (inside kb-probe-a only)
(a1) one warp after 0.8s of stillness
(a1) -> wl_pointer.enter surface=kb-probe-a at 13,7 <- cursor arrived
<- and nothing else
(a2) a second warp, immediately, still inside the same window
(a2) -> leave surface=kb-probe-b
(a2) -> enter surface=kb-probe-a serial=336 keys=[] <- focus, one warp late
a1_enter=no a2_enter=yes pointer_reached_kb-probe-a=yes
box kb-probe-a at 0,0 size 1280x720
box kb-probe-b at 120,80 size 1040x560
focus at map time: kb-probe-b (expected kb-probe-b: it mapped last)
(a1) target 0.0100,0.0100 (inside kb-probe-a only)
(a2) target 0.0100,0.0140 — about 3px lower, so the FLOORED pixel changes. A second warp to the same point would return before mouseMoveUnified touched the delta, and would prove nothing.
(a1) one warp after 0.8s of stillness
(a1) -> wl_pointer.enter surface=kb-probe-a at 13,7
(a2) a second warp, to the (a2) target above
(a2) -> modifiers depressed=0 latched=0 locked=0 group=0
(a2) -> leave surface=kb-probe-b
(a2) -> enter surface=kb-probe-a serial=406 keys=[]
(a2) -> modifiers depressed=0 latched=0 locked=0 group=0
(a2) -> configured surface=kb-probe-b 1040x560
(a2) -> configured surface=kb-probe-a 1280x720
gap between the two motion_absolute calls: 0.401s (under Hyprland's 0.5s delta window)
a1_enter=no a2_enter=yes pointer_reached_kb-probe-a=yes
```
The consequence is the headline risk of this whole feature: **`pointer
acquire` is one warp**, so the first key of a lease can be delivered to
whatever was focused before. Neither plan permits building the fallback in
Stages 1–2 (`docs/plans/2026-10-03-keyboard-input.md` §6 risk 1; the review's
"Do not build it in Stage 1"), so Stages 1–2 do not, and the final report
carries the objection. Stage 3's enter assertion must not be written against a
single warp.
The sentence this supports, and no stronger one: **an idle `motion_absolute`
onto unfocused `kb-probe-a` delivered `wl_pointer.enter` and no
`wl_keyboard.enter`; `kb-probe-b`'s `leave` and `kb-probe-a`'s `enter` were
observed only in the settle window after a later `motion_absolute` that stayed
inside `kb-probe-a`.** Map-time focus was `kb-probe-b`, and the two boxes
genuinely differ (`0,0 1280x720` against `120,80 1040x560`), so this is not the
one-window false pass.
Worth recording about this probe, because it is the review's own category of
false pass and it happened here: an earlier version matched the keyboard
`enter` line with `"enter surface=kb-probe-a" in line`, which also matches
`wl_pointer.enter surface=kb-probe-a`, and reported `a1_enter=yes`. The match
is `startswith` now.
It is **not** "the enter was one warp late", which is what an earlier draft of
this file said. The mechanism is in `InputManager.cpp` at v0.56.2:
`mouseMoveUnified` returns before it touches `m_mousePosDelta` when the floored
pixel did not change; the delta is *set to* 0 when the previous movement was
more than 0.5 s ago; and keyboard focus compares that delta against
`input:follow_mouse_threshold`, which the options block above shows is `0.0`
and unset. So the first warp contributed nothing to the delta, and the second
warp's own non-zero delta is what focused. Two consequences the draft got
wrong:
- **A second warp to the same point is not the fix.** It returns early. (a2)
moves about 3 px, deliberately, and the report prints both targets so a
reader can see that it moved.
- **"Immediately" was never measured.** The gap is 0.401 s, now printed, and it
matters only because it is under the 0.5 s window.
**`pointer acquire` is one warp** (`src/hhstreamd/manager.py`, the `_warp` in
`pointer_acquire`), so the first key of a lease can be delivered to whatever
was already focused. Neither plan permits building the fallback in Stages 1–2
(`docs/plans/2026-10-03-keyboard-input.md` §6 risk 1; the review's "Do not
build it in Stage 1"), so Stages 1–2 do not, and the final report carries the
objection. **Stage 3's enter subtest must not be written against acquire's
single warp**, and it must not be made to pass by warping twice to the same
bookmark.
Two false passes this probe itself walked into, both worth carrying into the VM
check:
- `"enter surface=kb-probe-a" in line` also matches
`wl_pointer.enter surface=kb-probe-a`, and an earlier version reported
`a1_enter=yes` off a *pointer* event. The match is `startswith` now.
- An earlier version used one window. A single mapped window is focused at map
time, so it prints `enter` whatever the warp does.
### (b) Does destroying the virtual keyboard release a held key?
**NO — `release_on_destroy=no`, `mask_cleared=no`**, measured with a second
virtual keyboard keeping the seat's keyboard capability up, so that a release
had somewhere to be delivered. `input:virtualkeyboard:release_pressed_on_close`
is `0` and unset, which is the default the review read out of
`ConfigValues.cpp`.
**No release: `release_on_destroy=no`** (transcript line 131), measured with a
second virtual keyboard keeping the seat's keyboard capability up so a release
had somewhere to be delivered, and with nothing of ours having sent a key-up
before `destroy`. `input:virtualkeyboard:release_pressed_on_close` is `0` and
unset, which is the default the review read out of `ConfigValues.cpp`.
Corroborated by accident on an earlier run, which is the strongest form the
evidence takes: a run that exited with `Shift_L` down and no spare device left
the key down, and the *next* run's very first `wl_keyboard.enter` carried
`keys=[42, 0, 0, 0]` — evdev 42 is `KEY_LEFTSHIFT`. The key outlived the
process that pressed it. Sending the release from a different virtual keyboard
cleared it, which is why the probe now ends with a fresh keyboard, a key-up and
a zeroed mask (the review's step 7).
**Read `mask_cleared=no` narrowly.** It says only that the post-destroy window
contained no `modifiers` event. The held key was `KEY_A`, a letter, so the
depressed mask was 0 for the whole run — **this is not a measurement of a
non-zero mask surviving `destroy`**, and an earlier draft of this file claimed
it was. `releasePressed` in `VirtualKeyboard.cpp` emits key-ups only and never
a `modifiers`, so the source still says a mask would survive; it is simply not
what this transcript shows. `release_all` sends `modifiers(0, 0, 0, 0)` for
that reason, not because of this line.
This is worse than "a key stays down": `InputManager::onKeyboardKey` drops a
press whose code is already in the seat's `m_pressed`, so after a `kill -9` the
next driver's `key down` for that code is ignored and the key is dead until
something sends a matching up. Handled in Stage 2 by
The confirming evidence is the *cleanup*, transcript lines 136–138:
```
cleanup -> uploaded keymap format=1 size=35572
cleanup -> key code=30 state=0 sym=a
cleanup -> modifiers depressed=0 latched=0 locked=0 group=0
```
`InputManager::onKeyboardKey` **drops** a release whose code is not in the
seat's `m_pressed`. A `state=0` for code 30 that the client actually received,
sent from a *brand new* virtual keyboard, therefore means 30 was still in that
set after `destroy`. Had destroy released it, that cleanup key-up would have
been dropped and nothing would have reached the client.
One thing the transcript does **not** contain, and which this file used to cite:
an earlier, unkept run whose first `wl_keyboard.enter` carried
`keys=[42, 0, 0, 0]`. Every `enter` in the committed log is `keys=[]`.
So this is worse than "a key stays down": the code stays in `m_pressed`, and
`onKeyboardKey` also drops a *press* whose code is already there — the next
driver's `key down` for it is ignored, and the key is dead until something
sends a matching up. Handled in Stage 2 by
`input:virtualkeyboard:release_pressed_on_close = true` in
`nix/hyprland-conf.nix` (the review's change 4), with the explicit note that
the setting releases keys and still does not clear the modifier mask — which is
@@ -173,8 +242,13 @@ regardless.
### (c) Does Hyprland auto-repeat a held virtual key?
**`press_count=1`, `repeat_info rate=25 delay=600`.** A key left down for 1.5 s
— longer than the 600 ms delay — produced exactly one `wl_keyboard.key … state=1`.
**`press_count=1`, `repeat_info rate=25 delay=600`** (transcript lines
124–125). A key left down for `REPEAT_HOLD_S = 1.5` s — longer than the 600 ms
delay, not shorter — produced exactly one `key code=30 state=1` and no
`state=2`. A compositor repeating at 25 Hz after 600 ms would have added about
twenty more lines in the remaining 0.9 s; it added none. `repeat_info` arrives
at bind time, before the hold, and is printed next to the count because the
review asked for both — not because the compositor repeated.
This is **not** "`keyboard down` will not flood a text field", and reading it
that way is the review's named false pass. The compositor does not repeat on
+12 -7
View File
@@ -81,13 +81,13 @@ ANSWER 1: zwp_virtual_keyboard_manager_v1 is present at version 1.
setup -> wl_keyboard.keymap format=1 bytes=35572 symbols=xkb_symbols "pc_us_inet(evdev)" {
setup -> repeat_info rate=25 delay=600
setup -> configured surface=kb-probe-a 640x360
setup -> enter surface=kb-probe-a serial=357 keys=[]
setup -> enter surface=kb-probe-a serial=392 keys=[]
setup -> modifiers depressed=0 latched=0 locked=0 group=0
setup -> configured surface=kb-probe-a 1280x720
setup -> configured surface=kb-probe-b 640x360
setup -> modifiers depressed=0 latched=0 locked=0 group=0
setup -> leave surface=kb-probe-a
setup -> enter surface=kb-probe-b serial=365 keys=[]
setup -> enter surface=kb-probe-b serial=400 keys=[]
setup -> modifiers depressed=0 latched=0 locked=0 group=0
setup -> configured surface=kb-probe-b 1040x560
setup -> configured surface=kb-probe-a 1280x720
@@ -104,18 +104,21 @@ ANSWER 1: zwp_virtual_keyboard_manager_v1 is present at version 1.
box kb-probe-a at 0,0 size 1280x720
box kb-probe-b at 120,80 size 1040x560
focus at map time: kb-probe-b (expected kb-probe-b: it mapped last)
chosen warp target 0.0100,0.0100 (inside kb-probe-a only)
(a1) target 0.0100,0.0100 (inside kb-probe-a only)
(a2) target 0.0100,0.0140 — about 3px lower, so the FLOORED pixel changes. A second warp to the same point would return before mouseMoveUnified touched the delta, and would prove nothing.
(a1) one warp after 0.8s of stillness
(a1) -> wl_pointer.enter surface=kb-probe-a at 13,7
(a2) a second warp, immediately, still inside the same window
(a2) a second warp, to the (a2) target above
(a2) -> modifiers depressed=0 latched=0 locked=0 group=0
(a2) -> leave surface=kb-probe-b
(a2) -> enter surface=kb-probe-a serial=371 keys=[]
(a2) -> enter surface=kb-probe-a serial=406 keys=[]
(a2) -> modifiers depressed=0 latched=0 locked=0 group=0
(a2) -> configured surface=kb-probe-b 1040x560
(a2) -> configured surface=kb-probe-a 1280x720
gap between the two motion_absolute calls: 0.401s (under Hyprland's 0.5s delta window)
a1_enter=no a2_enter=yes pointer_reached_kb-probe-a=yes
ANSWER (a): one idle warp did NOT deliver enter; the SECOND warp did. Exactly what the review predicted. A lease's `acquire` is one warp, so the first key of a lease can land in the previously focused window: Stage 4 (or a second warp) is needed, and Stage 3's enter assertion must not be written against a single warp.
ANSWER (a): the idle warp onto unfocused kb-probe-a delivered wl_pointer.enter and NO wl_keyboard.enter. kb-probe-b's leave and kb-probe-a's enter arrived only after the LATER motion_absolute, the one that changed the floored pixel -- so the enter belongs to that motion's non-zero m_mousePosDelta and is NOT a delayed effect of the first warp.
Consequence: `pointer acquire` is one warp, so the first key of a lease can land in whatever was already focused. Stage 3's enter subtest must not be written against acquire's single warp, and warping twice to the same bookmark is not the fix -- the same floored pixel returns early.
=== (c) is one held virtual key one wl_keyboard.key? ===
key code=30 state=1 sym=a
@@ -127,7 +130,9 @@ ANSWER (c): press_count=1 — the compositor does not repeat on the wire; it pub
spare -> uploaded keymap format=1 size=35572
release_on_destroy=no mask_cleared=no
(compare with input:virtualkeyboard:release_pressed_on_close, printed above)
ANSWER (b): NO — destroy delivered no release, with another keyboard keeping the seat's capability up. So a driver killed with -9 leaves evdev 30 in the seat's m_pressed, and InputManager::onKeyboardKey then DROPS the next press of that code: the key is dead until something sends a matching up. _lift_everything is the only guard on the clean path, and SIGKILL skips it.
ANSWER (b): NO RELEASE — destroy delivered no key-up, with a second keyboard keeping the seat's capability up and with nothing of ours having sent an up beforehand.
Read `mask_cleared` narrowly: it says only that destroy emitted no `modifiers` event. The held key is a letter, so the depressed mask was 0 throughout -- this is NOT a measurement of a non-zero mask surviving destroy. releasePressed emits key-ups only (VirtualKeyboard.cpp), which is why release_all sends modifiers(0,0,0,0) regardless.
The confirming evidence is the cleanup below: onKeyboardKey DROPS a release whose code is not in the seat's m_pressed, so a `key code=30 state=0` arriving from a BRAND NEW keyboard means the code was still in that set after destroy. A driver killed with -9 leaves it there and the next driver's press of it is dropped: dead, not merely stuck. _lift_everything is the only guard on the clean path and SIGKILL skips it.
cleanup -> uploaded keymap format=1 size=35572
cleanup -> key code=30 state=0 sym=a
cleanup -> modifiers depressed=0 latched=0 locked=0 group=0
+89 -30
View File
@@ -15,13 +15,27 @@ that script. It prints what it saw, not what it hoped for.
mask cleared?
(c) Is one held key one `wl_keyboard.key`, with `repeat_info` still sent?
(a1) and (a2) are separate questions on purpose. `InputManager::onMouseWarp`
calls `mouseMoveUnified(refocus=false)`, and with `follow_mouse = 1` keyboard
focus needs `m_mousePosDelta > follow_mouse_threshold` (default 0) — and the
delta is reset to 0 when the previous cursor movement was more than 0.5 s ago.
So one idle warp is expected *not* to move keyboard focus and a second one is.
A probe that reported a single yes/no would hide exactly the thing the lease's
`acquire` does: one warp, then immediately a key.
(a1) and (a2) are separate questions on purpose, and (a2) is not a repeat of
(a1). `InputManager::onMouseWarp` calls `mouseMoveUnified(refocus=false)`;
with `follow_mouse = 1`, keyboard focus needs
`m_mousePosDelta > follow_mouse_threshold`, that threshold is 0 by default, and
the delta is *set to* 0 when the previous cursor movement was more than 0.5 s
ago. So an idle warp is expected to move the cursor and not keyboard focus,
and a following motion that changes the floored pixel inside 0.5 s is expected
to focus.
Two things follow, and both are printed rather than assumed:
* **(a2) must land on a different pixel.** `mouseMoveUnified` returns before
it touches the delta when the floored position did not change, so a second
`motion_absolute` to the *same* point proves nothing. (a2) offsets by about
3 px and the report prints both normalised points.
* **The gap between them is a measurement, not the word "immediately".** It
has to stay under 0.5 s for (a2) to be the in-window case, so the report
prints the monotonic gap it achieved.
A probe that collapsed the two into one yes/no would hide exactly what the
lease's `acquire` does: *one* warp, and then a key.
It talks to the compositor and to nothing else: **no broker, no lease, no
`hhstreamd` socket, no `hhstream` CLI**. Read-only `hyprctl` is used to learn
@@ -123,6 +137,12 @@ REPEAT_HOLD_S = 1.5
#: would be read as a NO.
SETTLE_S = 0.4
#: How far (a2) moves, as a fraction of the output's height. About 3 px on a
#: 720-line output, which is what makes the floored pixel change —
#: `mouseMoveUnified` returns early otherwise and never touches the delta
#: keyboard focus is compared against.
A2_OFFSET = 0.004
APP_A, APP_B = "kb-probe-a", "kb-probe-b"
#: Hyprland options the answers depend on, printed so a reader never has to
@@ -800,7 +820,14 @@ def question_focus(probe: Probe, output_name: str, mode: tuple[int, int]) -> Non
"Measure it in vm-keyboard, where two sessions have two outputs."
)
return
say(f" chosen warp target {target[0]:.4f},{target[1]:.4f} (inside {APP_A} only)")
second = (target[0], min(1.0, target[1] + A2_OFFSET))
say(f" (a1) target {target[0]:.4f},{target[1]:.4f} (inside {APP_A} only)")
say(
f" (a2) target {second[0]:.4f},{second[1]:.4f} — about "
f"{round(A2_OFFSET * mode[1])}px lower, so the FLOORED pixel changes. A "
"second warp to the same point would return before mouseMoveUnified "
"touched the delta, and would prove nothing."
)
# The whole point of (a1): the cursor must have been still for longer than
# Hyprland's 0.5 s window, or the delta from an earlier move carries it.
@@ -808,23 +835,33 @@ def question_focus(probe: Probe, output_name: str, mode: tuple[int, int]) -> Non
probe.report("idle -> ")
say(f" (a1) one warp after {IDLE_S}s of stillness")
first_sent = time.monotonic()
probe.warp(*target)
probe.pump(SETTLE_S)
first = probe.report("(a1) -> ")
first_bucket = probe.report("(a1) -> ")
say(" (a2) a second warp, immediately, still inside the same window")
probe.warp(target[0], min(1.0, target[1] + 0.004))
say(" (a2) a second warp, to the (a2) target above")
gap = time.monotonic() - first_sent
probe.warp(*second)
probe.pump(SETTLE_S)
second = probe.report("(a2) -> ")
second_bucket = probe.report("(a2) -> ")
# Timed rather than asserted in prose: (a2) is the in-window case only
# while this stays under 0.5 s, and an earlier version of this script
# printed the word "immediately" about a gap it never measured.
say(
f" gap between the two motion_absolute calls: {gap:.3f}s "
f"({'under' if gap < 0.5 else 'OVER'} Hyprland's 0.5s delta window)"
)
# `startswith`, not `in`: `wl_pointer.enter surface=kb-probe-a` contains
# the substring `enter surface=kb-probe-a`, and an `in` test here reported
# a1_enter=yes off a pointer event. That is the review's own category of
# false pass, found in this probe.
entered_a1 = any(line.startswith(f"enter surface={APP_A}") for line in first)
entered_a2 = any(line.startswith(f"enter surface={APP_A}") for line in second)
entered_a1 = any(line.startswith(f"enter surface={APP_A}") for line in first_bucket)
entered_a2 = any(line.startswith(f"enter surface={APP_A}") for line in second_bucket)
pointer_moved = any(
line.startswith(f"wl_pointer.enter surface={APP_A}") for line in first + second
line.startswith(f"wl_pointer.enter surface={APP_A}")
for line in first_bucket + second_bucket
)
say(
f" a1_enter={'yes' if entered_a1 else 'no'} "
@@ -833,18 +870,26 @@ def question_focus(probe: Probe, output_name: str, mode: tuple[int, int]) -> Non
)
if entered_a1:
say(
f"ANSWER (a): one idle warp DID deliver enter to {APP_A}. That is not "
"what v0.56.2's threshold logic predicts, so this binary does not "
"match the read of InputManager::onMouseWarp. Stage 3 must still "
"assert it rather than assume it."
f"ANSWER (a): the idle warp DID deliver wl_keyboard.enter to {APP_A}. "
"That is not what v0.56.2's threshold logic predicts, so this binary "
"does not match the read of InputManager::onMouseWarp. Stage 3 must "
"still assert it rather than assume it."
)
elif entered_a2:
say(
f"ANSWER (a): one idle warp did NOT deliver enter; the SECOND warp "
f"did. Exactly what the review predicted. A lease's `acquire` is one "
"warp, so the first key of a lease can land in the previously "
"focused window: Stage 4 (or a second warp) is needed, and Stage 3's "
"enter assertion must not be written against a single warp."
f"ANSWER (a): the idle warp onto unfocused {APP_A} delivered "
f"wl_pointer.enter and NO wl_keyboard.enter. {APP_B}'s leave and "
f"{APP_A}'s enter arrived only after the LATER motion_absolute, the "
"one that changed the floored pixel -- so the enter belongs to that "
"motion's non-zero m_mousePosDelta and is NOT a delayed effect of "
"the first warp."
)
say(
" Consequence: `pointer acquire` is one warp, so the first "
"key of a lease can land in whatever was already focused. Stage 3's "
"enter subtest must not be written against acquire's single warp, "
"and warping twice to the same bookmark is not the fix -- the same "
"floored pixel returns early."
)
elif pointer_moved:
say(
@@ -926,12 +971,26 @@ def question_destroy(probe: Probe) -> None:
say("ANSWER (b): YES — destroy released the held key.")
else:
say(
"ANSWER (b): NO — destroy delivered no release, with another keyboard "
"keeping the seat's capability up. So a driver killed with -9 leaves "
f"evdev {KEY_A} in the seat's m_pressed, and InputManager::"
"onKeyboardKey then DROPS the next press of that code: the key is "
"dead until something sends a matching up. _lift_everything is the "
"only guard on the clean path, and SIGKILL skips it."
"ANSWER (b): NO RELEASE — destroy delivered no key-up, with a second "
"keyboard keeping the seat's capability up and with nothing of ours "
"having sent an up beforehand."
)
say(
" Read `mask_cleared` narrowly: it says only that destroy "
"emitted no `modifiers` event. The held key is a letter, so the "
"depressed mask was 0 throughout -- this is NOT a measurement of a "
"non-zero mask surviving destroy. releasePressed emits key-ups only "
"(VirtualKeyboard.cpp), which is why release_all sends "
"modifiers(0,0,0,0) regardless."
)
say(
" The confirming evidence is the cleanup below: "
"onKeyboardKey DROPS a release whose code is not in the seat's "
f"m_pressed, so a `key code={KEY_A} state=0` arriving from a BRAND "
"NEW keyboard means the code was still in that set after destroy. A "
"driver killed with -9 leaves it there and the next driver's press "
"of it is dropped: dead, not merely stuck. _lift_everything is the "
"only guard on the clean path and SIGKILL skips it."
)
# Required cleanup, and it is the review's step 7: a NEW virtual keyboard,