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