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
+119
-20
@@ -1,7 +1,7 @@
|
||||
# CONTRACT — sessions build (sessions-v1)
|
||||
# CONTRACT — sessions build (sessions-v3)
|
||||
|
||||
This file is the interface for the **session** work: the broker, containers,
|
||||
compositor IPC and pointer input. It is the sibling of `docs/CONTRACT.md`, which
|
||||
compositor IPC and pointer **and keyboard** input. It is the sibling of `docs/CONTRACT.md`, which
|
||||
freezes the *frame-socket* wire format; that one is untouched by this build.
|
||||
|
||||
**Immutable without a version bump.** Every slice codes against this and nothing
|
||||
@@ -9,10 +9,23 @@ else. If something here is wrong or missing, **stop and report it in your final
|
||||
message** — the parent edits this file, not you. Do not widen your slice to work
|
||||
around a gap.
|
||||
|
||||
Version: sessions-v2 (2026-10-02). v1 was the freeze the four slices built against;
|
||||
v2 records the decisions their reports asked for. Every v2 change is either a
|
||||
clarification or an addition — **no v1 signature changed meaning** — so v1 code
|
||||
stays valid except where noted. Changes:
|
||||
Version: sessions-v3 (2026-10-04). v1 was the freeze the four slices built
|
||||
against; v2 recorded the decisions their reports asked for; v3 adds the
|
||||
keyboard. Every change in both has been an addition or a clarification — **no
|
||||
v1 or v2 signature changed meaning** — so earlier code stays valid except where
|
||||
noted.
|
||||
|
||||
v3 changes, all of them keyboard (`docs/plans/2026-10-03-keyboard-input.md` as
|
||||
amended by `docs/plans/2026-10-04-keyboard-verification.md`):
|
||||
|
||||
| § | Change | Why |
|
||||
| --- | --- | --- |
|
||||
| §3.3 | `PointerLease` gains `press_key` / `unpress_key` / `keys_pressed`; `LeaseOutcome` gains `keys_lifted`. **`expire()` still returns `LeaseInfo` and nothing else.** | One `wl_seat` means one keyboard focus, so the keyboard shares the pointer's lease. §6.7's "the lease gains a `keyboard` flag" is the wrong shape: a boolean cannot say to lift `Control_L` and not `a`, and order matters for the same reason it does for buttons. |
|
||||
| §3.4 | Driver ops `key` and `type`; `pressed` gains `keys[]`; `release_all` gains `lifted_keys[]`; the frozen command line gains four `--xkb-*` flags. A rejected request may carry a `kind`. | There is no keyboard `frame` and no `release_all_keys`: the protocol has no frame, and expiry has one call site. The flags are the **only** path a layout has to the uploaded keymap — the broker's TOML is read by `hhstreamd`, and the driver is a different unit that never opens it. |
|
||||
| §4 | Verbs `keyboard.key` and `keyboard.type`, both in the mutation set; `pointer.state` gains `keys[]`; `pointer.release` gains `keys_lifted[]`. | A retried `type` must not type twice, for the reason a retried click must not click twice. |
|
||||
| §4 | **`pointer.acquire` takes keyboard focus as well as the cursor**, and is two `warp`s on the driver socket rather than one. | Measured (`tests/README-keyboard-probe.md`): one warp onto an idle cursor delivers `wl_pointer.enter` and no `wl_keyboard.enter`, so a one-warp acquire aims the cursor at the session and leaves the keys with whatever was focused before. |
|
||||
|
||||
v2 changes:
|
||||
|
||||
| § | Change | Why |
|
||||
| --- | --- | --- |
|
||||
@@ -236,13 +249,27 @@ class PointerLease:
|
||||
def press(self, session_id: str, button: str) -> None: ...
|
||||
def unpress(self, session_id: str, button: str) -> list[str]: ...
|
||||
def pressed(self) -> list[str]: ...
|
||||
# v3: the same three for keysym names. A `keys` dict beside `buttons` on
|
||||
# the held record, not a `keyboard` boolean: `release_all` has to know
|
||||
# *which* keys went down and in what order.
|
||||
def press_key(self, session_id: str, key: str) -> None: ...
|
||||
def unpress_key(self, session_id: str, key: str) -> list[str]: ...
|
||||
def keys_pressed(self) -> list[str]: ...
|
||||
|
||||
**`expire()` carries no bookmark and no lifted buttons** — it returns the lease
|
||||
that was released, nothing more. The broker therefore has two duties on expiry:
|
||||
read `pressed()` *before* calling `expire()` if it wants the lease's view of what
|
||||
was down, and lift those buttons on the driver (`release_all`), because the lease
|
||||
cannot lift them itself. The bookmark is not `expire()`'s to keep: the broker
|
||||
already stores it with the session (§1), which is where it belongs.
|
||||
**`expire()` carries no bookmark, no lifted buttons and no lifted keys** — it
|
||||
returns the lease that was released, nothing more. The broker therefore has two
|
||||
duties on expiry: read `pressed()` **and `keys_pressed()`** *before* calling
|
||||
`expire()` if it wants the lease's view of what was down, and lift them on the
|
||||
driver (one `release_all`), because the lease cannot lift anything itself. The
|
||||
bookmark is not `expire()`'s to keep: the broker already stores it with the
|
||||
session (§1), which is where it belongs.
|
||||
|
||||
v3 deliberately did **not** widen this return. The ordering it forces — read,
|
||||
then expire — is the only thing stopping a key from being forgotten before the
|
||||
driver has been told to lift it, and on this compositor a forgotten key is
|
||||
worse than a forgotten button: `InputManager::onKeyboardKey` drops the *next*
|
||||
press of a code it still believes is down, so the key is dead rather than
|
||||
merely stuck.
|
||||
|
||||
def window_to_absolute(point: tuple[int, int], window: tuple[int, int, int, int],
|
||||
monitor: tuple[int, int, int, int]) -> tuple[float, float]:
|
||||
@@ -258,8 +285,27 @@ blocked driver must not stall the broker.
|
||||
|
||||
- Entry point `hhstream-pointer` (add to `pyproject.toml`:
|
||||
`hhstream-pointer = "hhstream_pointer.__main__:main"`).
|
||||
- Command line the module will pass, exactly:
|
||||
`hhstream-pointer --socket /run/hhstream/pointer.sock --compositor-runtime-dir /run/hypr-stream`
|
||||
- Command line the module will pass, exactly (**amended in v3**: the four
|
||||
`--xkb-*` flags, whose defaults are the values below):
|
||||
|
||||
```
|
||||
hhstream-pointer --socket /run/hhstream/pointer.sock \
|
||||
--compositor-runtime-dir /run/hypr-stream \
|
||||
--xkb-layout us --xkb-model pc105 \
|
||||
--xkb-variant '' --xkb-options ''
|
||||
```
|
||||
|
||||
These flags are the **only** path a layout has to the uploaded keymap. There
|
||||
is deliberately no `[keyboard]` table in the broker's TOML: that file is read
|
||||
by `hhstreamd`, and this is a different unit that never opens it, so such a
|
||||
table would be a setting an operator could change while every injected key
|
||||
stayed on `us`.
|
||||
|
||||
A layout `xkb_keymap_new_from_names` rejects — and a comma-separated one,
|
||||
and an empty one — is exit **2**, raised *before* the compositor is
|
||||
contacted. A keymap the compositor refuses is exit **10**, and the socket is
|
||||
never listened on: `key` before `keymap` is the protocol error `no_keymap`,
|
||||
which kills the connection rather than returning anything reportable.
|
||||
- Uses **pywayland** (packaged as `python3Packages.pywayland`) and the **wlr
|
||||
virtual pointer XML** from `pkgs.wlr-protocols`, which lives at
|
||||
`share/wlr-protocols/unstable/wlr-virtual-pointer-unstable-v1.xml` (the v1
|
||||
@@ -280,10 +326,39 @@ blocked driver must not stall the broker.
|
||||
{"op": "button", "button": "left", "state": "down"} -> {"ok": true}
|
||||
{"op": "axis", "axis": "vertical", "value": 3.0} -> {"ok": true}
|
||||
{"op": "frame"} -> {"ok": true}
|
||||
{"op": "pressed"} -> {"ok": true, "buttons": ["left"]}
|
||||
{"op": "release_all"} -> {"ok": true, "lifted": ["left"]}
|
||||
{"op": "pressed"} -> {"ok": true, "buttons": ["left"], "keys": ["Control_L"]}
|
||||
{"op": "release_all"} -> {"ok": true, "lifted": ["left"], "lifted_keys": ["Control_L"]}
|
||||
{"op": "key", "key": "Return", "state": "down"} -> {"ok": true, "keys": ["Return"], "lifted": []}
|
||||
{"op": "type", "text": "Hello"} -> {"ok": true, "keys": []}
|
||||
```
|
||||
|
||||
**Amended in v3 — `key` and `type`, for the keyboard.** Names on this socket,
|
||||
evdev codes only on the Wayland request: the driver owns the keymap, so it is
|
||||
the only thing that can say which keycode `z` is on the uploaded layout. Four
|
||||
rules that are not interchangeable:
|
||||
|
||||
- **No output and no frame.** A virtual keyboard is seat-global, so `key` and
|
||||
`type` take no output and must not require a prior `warp`. And
|
||||
`zwp_virtual_keyboard_v1` has no `frame` request — a key queued until one
|
||||
would never arrive — so each request is flushed the way `button` already is.
|
||||
- **`pressed` and `release_all` grow key fields** rather than gaining a
|
||||
parallel `release_all_keys`. Expiry has one call site, and a second op would
|
||||
be a second thing to forget in the path that runs when nobody is watching.
|
||||
`release_all` lifts buttons, then keys in press order, then sends
|
||||
`modifiers(0, 0, 0, 0)` if a mask was ever set — a virtual key-up clears no
|
||||
modifier state, so without that a lease that ended under Shift hands the
|
||||
next holder a keyboard where every letter is a capital.
|
||||
- **`type` is one request for the whole string.** The driver resolves every
|
||||
character before emitting anything, so an unmappable one types no prefix.
|
||||
Capped at 4096 Unicode **scalars** (not bytes) in the driver and in the
|
||||
broker.
|
||||
- **A rejection may carry `kind`.** `{"ok": false, "error": "…", "kind":
|
||||
"invalid_argument"}` is the caller's mistake — a keysym the layout does not
|
||||
have, an unmappable character, a bad `state`, a string over the cap — and the
|
||||
broker maps it to exit 2. Any other value, and an older driver's absent
|
||||
field, stay `driver_refused` (exit 10), which is what the button and axis
|
||||
paths already do.
|
||||
|
||||
**Amended after the freeze — `axis`, for scrolling.** Added to the op set above
|
||||
and to the broker's verbs as `pointer.scroll`. Positive vertical is *down* and
|
||||
positive horizontal is *right*: the protocol's direction, not a choice of ours,
|
||||
@@ -316,8 +391,26 @@ code will be called with):
|
||||
| `pointer.move` | `id`, `lease_id`, `x`, `y` \| `dx`, `dy` | `bookmark` |
|
||||
| `pointer.button` | `id`, `lease_id`, `button`, `state` | `buttons[]` |
|
||||
| `pointer.click` | `id`, `lease_id`, `button?`, `count?` | `bookmark` |
|
||||
| `pointer.release` | `id`, `lease_id` | `bookmark`, `released_by` |
|
||||
| `pointer.state` | — | `holder`, `since`, `lease_id` |
|
||||
| `pointer.release` | `id`, `lease_id` | `bookmark`, `released_by`, `buttons_lifted[]`, `keys_lifted[]` |
|
||||
| `pointer.state` | — | `holder`, `since`, `lease_id`, `buttons[]`, `keys[]` |
|
||||
| `keyboard.key` (v3) | `id`, `lease_id`, `key`, `state` | `keys[]` |
|
||||
| `keyboard.type` (v3) | `id`, `lease_id`, `text` | `chars`, `keys[]` |
|
||||
|
||||
**v3, the keyboard.** `keyboard.*` verbs take the **pointer** lease: there is
|
||||
no `keyboard.acquire` and no second lease id. One `wl_seat` means one keyboard
|
||||
focus, and the shipped `input:follow_mouse = 1` means another session's warp
|
||||
retargets the keys, so two leases would let session B move the pointer while
|
||||
session A believed it was typing into its own window. Both verbs are in the
|
||||
`request_id` mutation set, for the reason `pointer.click` is: a retried `type`
|
||||
that typed twice is the one failure an agent cannot undo.
|
||||
|
||||
**v3, acquire takes the keyboard too.** `pointer.acquire` sends **two** warps
|
||||
to the driver — a neighbouring pixel, then the real target — because one warp
|
||||
onto an idle cursor moves the cursor and not keyboard focus. Measured; see
|
||||
`tests/README-keyboard-probe.md`. The reply gains `focus`, naming which
|
||||
mechanism took it (`warp`, `focuswindow`, or `none`). This depends on
|
||||
`input:follow_mouse_threshold` being 0, which `nix/hyprland-conf.nix` now sets
|
||||
explicitly rather than inheriting.
|
||||
|
||||
### Error codes (extend `ExitCode`, do not renumber)
|
||||
|
||||
@@ -325,8 +418,13 @@ code will be called with):
|
||||
| 6 POLICY | 7 TIMEOUT | 8 BUSY | **9 NO_LEASE (new)** | **10 COMPOSITOR (new)** |
|
||||
|
||||
Activity accounting is unchanged and load-bearing: **`touch` is the only mark of
|
||||
activity**; `list`, `status`, `logs`, `gc`, and every `pointer.*` verb do **not**
|
||||
reset the idle clock.
|
||||
activity**; `list`, `status`, `logs`, `gc`, and every `pointer.*` **and
|
||||
`keyboard.*`** verb do **not** reset the idle clock. A session being typed into
|
||||
is still a session nobody has said they want kept.
|
||||
|
||||
The *lease* clock is a different one, and v3 widens it: every `pointer.*` and
|
||||
`keyboard.*` gesture verb refreshes the lease's idle deadline, because they all
|
||||
go through the same gate. `pointer acquire`'s own stderr says so.
|
||||
|
||||
---
|
||||
|
||||
@@ -346,6 +444,7 @@ reset the idle clock.
|
||||
| Container workspace band | `1000 + slot`, allocated from the registry's free list |
|
||||
| Container mode | `1280x720` |
|
||||
| Units | `hyprland-headless`, `hyprland-headless-stream`, `hhstream-sessions`, `hhstream-pointer` |
|
||||
| Keyboard layout | **option default** `us` (`sessions.keyboard.layout`), reaching the driver as `--xkb-layout`. One group: a comma is refused. Hyprland's `input:kb_layout` is not read. |
|
||||
| Binaries | `hhstream`, `hhstreamd`, `hhstream-server`, `hhstream-client`, `hhstream-pointer` |
|
||||
| Service account | `hermes`, supplementary group `hhstream` |
|
||||
|
||||
|
||||
Reference in new issue
Block a user