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

+56 -4
View File
@@ -22,6 +22,12 @@ What they prove and what they do not:
recorder. So the protocol, the framing, the driver's own button bookkeeping
and — importantly — which backend failures become ``ok: false`` and which
kill the connection are the shipped ones; only the compositor is absent.
The **keymap is real too**, a compiled ``us`` layout rather than a stub,
because what these tests assert about the keyboard is which evdev code and
which modifier mask went on the wire — and a stub would answer whatever the
test expected. ``keyboard=False`` builds a driver with no keyboard at all,
which is the compositor-has-no-global case.
"""
from __future__ import annotations
@@ -34,10 +40,36 @@ from typing import Any
import pytest
from hhstream_pointer import keymap as keymaps
from hhstream_pointer.__main__ import _handler
from hhstream_pointer.ops import Dispatcher
from hhstream_pointer.server import PointerServer
#: evdev codes the keyboard tests name. From ``linux/input-event-codes.h``,
#: and the values that cross the Wayland request -- never XKB keycodes, which
#: are 8 higher and never leave the driver.
KEY_A = 30
KEY_LEFTSHIFT = 42
KEY_LEFTCTRL = 29
_us_keymap: keymaps.Keymap | None = None
def us_keymap() -> keymaps.Keymap:
"""One compiled ``us`` keymap, shared.
Compiling is the slow part (xkbcommon reads the rules files), and the
object is immutable once built -- it is a lookup table plus the keymap text
-- so one per process is right. Shared deliberately rather than per-fixture
for the same reason the driver builds it once at start-up: a *second*
keymap in a process would be a second answer to "which code is `z`".
"""
global _us_keymap
if _us_keymap is None:
_us_keymap = keymaps.build(layout="us")
return _us_keymap
#: Linux's sun_path is 108 bytes including the NUL.
SUN_PATH_MAX = 107
@@ -390,8 +422,11 @@ class FakeCompositor:
class RecordingSink:
"""A :class:`hhstream_pointer.ops.PointerSink` that writes nothing anywhere."""
def __init__(self) -> None:
def __init__(self, *, keyboard: bool = True) -> None:
self.calls: list[tuple] = []
#: Whether a virtual keyboard was created at start-up. False is the
#: compositor-with-no-global case, which must leave the cursor working.
self.keyboard = keyboard
#: An exception to raise from the next call. The shipped driver
#: answers an ``OutputUnknown`` on the wire and lets anything else
#: take the connection down, so which one is raised here decides which
@@ -414,6 +449,23 @@ class RecordingSink:
self._check()
self.calls.append(("frame", output))
# -- the keyboard half -------------------------------------------------
#
# No output on either of these, and that is the assertion as much as the
# recording: a virtual keyboard is seat-global, so a sink that accepted an
# output would let a per-output implementation look correct.
def has_keyboard(self) -> bool:
return self.keyboard
def key(self, code: int, state: int) -> None:
self._check()
self.calls.append(("key", code, state))
def modifiers(self, depressed: int, latched: int, locked: int, group: int) -> None:
self._check()
self.calls.append(("modifiers", depressed, latched, locked, group))
def _check(self) -> None:
if self.fail is not None:
raise self.fail
@@ -433,11 +485,11 @@ class FakeDriver:
everything a test is actually asserting about still runs the real code.
"""
def __init__(self, socket_path: Path) -> None:
def __init__(self, socket_path: Path, *, keyboard: bool = True) -> None:
check_path(Path(socket_path))
self.socket_path = Path(socket_path)
self.sink = RecordingSink()
self.dispatcher = Dispatcher(self.sink)
self.sink = RecordingSink(keyboard=keyboard)
self.dispatcher = Dispatcher(self.sink, us_keymap() if keyboard else None)
self.server = PointerServer(self.socket_path, _handler(self.dispatcher))
self.server.listen()
self.connections: list[socket.socket] = []