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:
1 parent
b1f2744cf0
commit
e6f4c3bb3f
24 files changed
+2474
-105
No files matched your search
+96
-19
@@ -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
|
||||
|
||||
Reference in new issue
Block a user