Stage 1 review fixes, and Stage 2: the broker, the CLI and the module

The Stage 1 review (docs/reviews/2026-10-04-stage1-review.md, verdict
yes-with-fixes) found a real bug, and it was the kind Stage 2 would have
cemented. All five findings:

(1) HIGH, and reproduced before fixing: `key` resolved the action and
    then used only its `code`. So `keyboard key A` sent a bare code 30
    and the window received `a`; on `de`, `at` lost its level-three mask
    and typed `q`. `type` was the only path that used the mask, which is
    why every `type` test stayed green. `key` now sends
    modifiers(baseline | mask) before the down and restores the baseline
    on the up -- the one-character `type` sequence -- and `Shift_L`
    keeps its key-then-mask order, which is the other path on purpose.

    The same hole aliased two names onto one keycode: `down A` then
    `down a` recorded both and pressed 30 twice, Hyprland dropped the
    second, and the held set lied until the lease ended. A second name
    for a code already down is now refused.

(2) HIGH: the shutdown comment claimed hyprland-conf.nix sets
    input:virtualkeyboard:release_pressed_on_close. It did not. The line
    is there now, with the note that it releases keys and still never
    clears a mask -- which is why release_all zeroes the mask on every
    path we control rather than relying on it.

(3) MEDIUM: nothing would have noticed the keymap upload stopping. A
    `main` that connected and listened without uploading passed every
    test in the tree. Now asserted on the real sink: uploaded once,
    before `listen` (one shared ordering log across both stand-ins), the
    payload NUL-terminated with `size == len(utf8) + 1` read back
    through the fd, format 1, one terminator not two, and modifiers(0)
    straight after.

(4) LOW: `key` up now forgets the name only after a successful send,
    like `button` -- otherwise a raise between the two leaves us
    believing a key is up that the compositor still has down, and
    release_all will not try again.

(5) LOW: `\r` no longer aliases to Return (CRLF would have become two
    newlines silently), and an empty layout is refused -- xkbcommon
    compiles "" as the same keymap as `us`, so `--xkb-layout ''` looked
    configured and typed `us`.

Several of the review's named false passes are closed too: Control's
mask is compared against mod_get_index("Control") rather than merely
"not Shift's"; the keymap text assertion names pc_us_inet/pc_de_inet
instead of substring-matching "us"; the capital-under-Control case
asserts the whole sequence; the exit-code mirror is compared against
hhstreamd.protocol; and the module's defaults are read out of
nix/module.nix rather than asserted against themselves.

Stage 2 proper:

  * broker verbs keyboard.key / keyboard.type, both in the mutation set,
    both through _refresh (so they refresh the lease and, like every
    pointer verb, do NOT count as activity)
  * the driver's `kind` token mapped: a bad keysym or character is
    invalid_argument (exit 2), a missing keyboard global stays
    driver_refused (exit 10). The 4096-scalar cap and the shape checks
    are broker-side, because only a broker-side invalid_argument is 2
  * keys[] on pointer.state, keys_lifted[] on pointer.release and on
    pointer_lease_timeout, one release_all for both halves
  * CLI `session keyboard type|key|down|up`, reusing the pointer lease
    and its cache; `type` takes one raw argument and interprets nothing;
    the audit records a character count and never the text
  * sessions.keyboard.{layout,model,variant,options} on the unit's argv,
    layout defaulting to "us" with a type that refuses a comma. NO
    [keyboard] TOML table: hhstreamd reads that file and the driver is a
    different unit, so it would be a setting with no effect
  * CONTRACT-sessions.md bumped to v3; README.dev.md item 3 and
    vm-pointer.nix's header corrected (both still said the conf ships
    follow_mouse = 0 and that the keyboard work would choose)

And the operator decision that acquire grabs both devices: it now sends
two warps a real pixel apart, because one warp onto an idle cursor moves
the cursor and not keyboard focus. follow_mouse_threshold = 0 is set
explicitly in hyprland-conf.nix since the second warp depends on it,
`dispatch focuswindow` is the fallback when the nudge cannot be sent,
and the reply and audit carry which mechanism ran. The acquire test
asserts the pair and that they floor to different pixels -- a test that
only saw wl_pointer.enter would pass while the first keystroke went to
the wrong window.

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

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 04:11:24 +00:00
1 parent b1f2744cf0
commit e6f4c3bb3f
24 files changed
+2474 -105

No files matched your search

+96 -19
View File
@@ -232,6 +232,10 @@ tests/
fake_capture.py writes one fixed PNG to stdout: hhs-fake-capture
assert_stream.py independent contract reader/asserter: hhs-assert-stream
hyprland_diagnostics.sh the failure dump: hhs-hyprland-diagnostics
keyboard_probe.py THROWAWAY: measures the compositor's keyboard behaviour
against the live socket. See README-keyboard-probe.md
and the transcript beside it; delete both once
checks/vm-keyboard.nix asserts the same properties.
unit/ ipc/ containers/ pointer/ sessions/ the pytest suite
```
@@ -259,6 +263,72 @@ Adding a unit test: drop a `test_*.py` under `tests/`. Nothing needs
registering, but the basename must be unique across the tree. Adding a check:
one file in `checks/`, one line in `checks/default.nix`.
## Typing into a session: the keyboard layout
Keys reach whichever surface the compositor's one seat has focused. A virtual
keyboard is seat-global and has no output argument, so unlike the pointer there
is nothing to aim — what aims it is the pointer, and `pointer acquire` takes
both (see item 3 under the known gaps for why that is two warps and not one).
```bash
hhstream session pointer acquire <id> # also authorises typing
hhstream session keyboard type <id> 'hello world' # one argument, raw UTF-8
hhstream session keyboard key <id> Return # a tap: down then up
hhstream session keyboard down <id> Control_L # a chord, held
hhstream session keyboard type <id> c # ...is Ctrl+C
hhstream session keyboard up <id> Control_L
hhstream session pointer release <id> # lifts buttons AND keys
```
`hhstream session pointer state` reports held keys beside held buttons.
### The layout is an operator setting
**The driver compiles one XKB keymap at start-up and uploads it once. That
keymap is the only thing that decides what an injected key means.** Every verb
names an XKB *keysym* — `a`, `A`, `Return`, `BackSpace`, `Left`, `Control_L` —
and the driver resolves that name against the keymap to get the evdev code and
the modifier mask the compositor is sent.
| Option | Default | Notes |
| --- | --- | --- |
| `services.hyprland-headless-stream.sessions.keyboard.layout` | `"us"` | One group only: the option's type refuses `us,ru`, and so does the driver |
| `…sessions.keyboard.model` | `"pc105"` | |
| `…sessions.keyboard.variant` | `""` | A variant whose characters are *dead keys* (`us(intl)`) cannot be typed by v1 |
| `…sessions.keyboard.options` | `""` | Passed to `xkb_keymap_new_from_names`; a value it rejects stops the driver with exit 2 |
```nix
services.hyprland-headless-stream.sessions.keyboard.layout = "de";
```
Three things worth knowing before an agent types anything:
1. **Hyprland's own `input:kb_layout` is not read and has no effect on
injected keys.** It describes the layout for physical keyboards, of which a
headless session has none, and reading it would mean a `hyprctl` reload
could silently change what every agent types. The two can therefore
disagree, and only the option above matters.
2. **A character the layout cannot produce fails the whole string.** There is
no partial type: `keyboard type <id> 'café'` on `us` is exit 2 and emits
nothing, rather than typing `caf` and stopping. The refusal names the scalar
*index*, never the character and never the string, because a typed string is
a password as often as not and these messages are logged. The audit log
records a character count and nothing else.
3. **`keyboard down` of a non-modifier floods the window.** The compositor
sends one key event and publishes a repeat rate; the *application* repeats,
so a held `a` inserts characters until the key-up or the lease TTL (default
30 s). Measured on this build at 25/s after 600 ms. It is not ours to
rate-limit — we do not generate the repeats — so the only safe hold is a
modifier, which is what chords are for.
The layout reaches the driver as `--xkb-layout` on `hhstream-pointer`'s command
line, and **only** there. It is deliberately not a key in the broker's TOML:
that file is read by `hhstreamd`, and the driver is a different unit that never
opens it, so a `[keyboard]` table there would be a setting an operator could
change while every injected key stayed on `us`.
## Known gaps in the interface (as of this branch)
Every item the previous revision of this section listed is closed: the module
@@ -289,13 +359,14 @@ when one closes, so this list stays a description of what is still true.
get a container anyway — so the CLI exits 2 and names the disagreement
instead of lying about what it did.
3. **`nix/hyprland-conf.nix` sets `input:follow_mouse = 0`, and that stops
pointer input reaching anything but the focused window.** The comment
justifying it — "No pointer will ever exist; do not let focus depend on
one" — was true before this build and is false now.
3. **Fixed: `nix/hyprland-conf.nix` sets `input:follow_mouse = 1`.** *(This
item previously said it ships `0`, that pointer input therefore reaches
nothing but the focused window, and that whether to change it was a
decision for the keyboard work. The conf file sets `1`, and the keyboard
work has made that decision; what follows is why, and what is left.)*
Measured by `vm-pointer`, with two sessions and the second holding focus
because its window opened last:
The original measurement, by `vm-pointer`, with two sessions and the second
holding focus because its window opened last:
```
aimed at target-le22h7: it reports [] <- the session the warp named
@@ -303,20 +374,26 @@ when one closes, so this list stays a description of what is still true.
cursor now at {'x': 2048, 'y': 288} <- exactly where it was aimed
```
The compositor moved the cursor to the right pixel, inside the right
window, on the right output, and told no client at all. Every warp and
click in the subtests before that one is delivered perfectly, because there
the aimed-at session is also the focused one — which is why nothing noticed
until a check put two sessions on the screen at once.
With `0`, the compositor moved the cursor to the right pixel, inside the
right window, on the right output, and told no client at all. That defeats
the point of containers and the lease, so the conf sets `1`.
It defeats the point of containers and the lease: an agent could only drive
whichever session the compositor last focused. `vm-pointer` overrides the
single line through the module's `extraConfig` and asserts the property
that fails without it, so the check is green and the defect is still
visible. The fix is one line in `nix/hyprland-conf.nix`; whether it should
be `1` (Hyprland's own default, keyboard focus follows the cursor too) or a
looser setting that leaves keyboard focus alone is a decision for the
keyboard work in PLAN §6.7.
**What is left, and it is a real limitation.** `follow_mouse = 1` moves
keyboard focus too — which is what makes typing possible at all, since a
virtual keyboard is seat-global and has no output to aim. But **one warp
does not move it.** Measured directly against the live compositor
(`tests/README-keyboard-probe.md`): an idle `motion_absolute` onto an
unfocused window delivers `wl_pointer.enter` and no `wl_keyboard.enter`,
because `mouseMoveUnified` zeroes `m_mousePosDelta` when the previous
movement was over 0.5 s ago and keyboard focus is that delta compared
against `input:follow_mouse_threshold`.
So `pointer acquire` sends **two** warps, a real pixel apart, and takes the
keyboard as well as the cursor. The conf now sets
`follow_mouse_threshold = 0` explicitly rather than inheriting the default,
because that is what the second warp depends on; raise it and acquire stops
taking keyboard focus. `dispatch focuswindow` is the fallback if the nudge
cannot be sent, and the acquire reply's `focus` field says which ran.
4. **A container's window rule only binds for an application that reads the
environment.** The broker's only lever on an application's class is