Merge keyboard input (feat/keyboard-input @561e0c2) for a live trial on this machine
The same shape as the merge that branch got on 2026-10-05 (edbf15f on
feat/session-live-stream): this machine's own config sets
`sessions.keyboard.layout`, so a ref without the keyboard work does not
evaluate -- and the point of this branch is to be consumed here.
The stream branch's own commit is the first parent, so PR #2 stays based on
main and carries none of this merge. Conflicts were additive on both sides
(new option blocks, new checks, new README rows) and are resolved by keeping
both.
This commit is contained in:
commit
994fdb1cfb
51 files changed
+8994
-233
No files matched your search
+110
-19
@@ -222,6 +222,10 @@ checks/
|
||||
vm-containers.nix nixosTest, one output and one workspace per session
|
||||
vm-pointer.nix nixosTest, the lease, the driver and a click that lands
|
||||
vm-stream-firewall.nix nixosTest, the stream's port in the guest's firewall
|
||||
vm-keyboard.nix nixosTest, the uploaded keymap, keyboard focus, and a
|
||||
symbol a client decoded. Exposed TWICE -- `vm-keyboard`
|
||||
(layout us) and `vm-keyboard-de` -- because the layout
|
||||
reaches the keymap only through the driver unit's argv
|
||||
lib/test-tools.nix packages the tests/ helpers for the guest
|
||||
lib/session-tools.nix packages the two guest programs below
|
||||
lib/session-machine.nix the guest the three session checks share
|
||||
@@ -231,10 +235,16 @@ checks/
|
||||
lib/ipc_watch.py subscribes to the event socket: hhs-ipc-watch
|
||||
lib/pointer_target.py a Wayland window that reports pointer events it receives:
|
||||
hhs-pointer-target
|
||||
lib/keyboard_target.py a Wayland window that reports KEY events, decoded with
|
||||
the keymap the compositor forwarded: hhs-keyboard-target
|
||||
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
|
||||
```
|
||||
|
||||
@@ -258,10 +268,84 @@ print the pointer events it receives with the coordinates it was given.
|
||||
`foot` and `wev` do neither and ignore the environment entirely, which makes
|
||||
them good *unmatched* windows and useless as matched ones.
|
||||
|
||||
`hhs-keyboard-target` is its sibling, and the thing that makes it a separate
|
||||
program rather than a flag is **where its symbols come from**: it compiles the
|
||||
keymap the compositor forwarded over `wl_keyboard.keymap` and decodes every key
|
||||
through that. A client with its own keymap would decode `hello` whether or not
|
||||
the driver ever uploaded one, so the check would be asserting that the check
|
||||
can spell. It is also why `session-tools.nix` builds it against a python with
|
||||
`xkbcommon` while the pointer target gets one with only `pywayland`.
|
||||
|
||||
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
|
||||
@@ -292,13 +376,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
|
||||
@@ -306,20 +391,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