diff --git a/README.dev.md b/README.dev.md index 38a4091..8cd27d8 100644 --- a/README.dev.md +++ b/README.dev.md @@ -219,6 +219,10 @@ checks/ vm-ipc.nix nixosTest, the compositor's request and event sockets 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-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 @@ -228,10 +232,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 ``` @@ -255,10 +265,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 # also authorises typing +hhstream session keyboard type 'hello world' # one argument, raw UTF-8 +hhstream session keyboard key Return # a tap: down then up +hhstream session keyboard down Control_L # a chord, held +hhstream session keyboard type c # ...is Ctrl+C +hhstream session keyboard up Control_L +hhstream session pointer release # 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 '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 +373,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 +388,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 diff --git a/checks/default.nix b/checks/default.nix index 8f01f56..73f739c 100644 --- a/checks/default.nix +++ b/checks/default.nix @@ -7,13 +7,20 @@ # vm-ipc -- the compositor's IPC sockets, and an event that arrives # vm-containers -- one output and one workspace per session # vm-pointer -- the lease, the driver, and a click the application saw +# vm-keyboard -- the uploaded keymap, keyboard focus, and a decoded symbol +# vm-keyboard-de -- the same check with sessions.keyboard.layout = "de" # # What the guests need lives in checks/lib: `test-tools.nix` for the fake # capture and the contract asserter, `session-tools.nix` for the event -# subscriber and the pointer target, `session-machine.nix` for the guest the -# three session checks share, and `session-prelude.nix` for their test-script +# subscriber and the two input targets, `session-machine.nix` for the guest the +# session checks share, and `session-prelude.nix` for their test-script # helpers. # +# `vm-keyboard` and `vm-keyboard-de` are one file twice over, and that is the +# point: `sessions.keyboard.layout` reaches the uploaded keymap only through +# the driver unit's argv, and a single-layout check cannot tell that path from +# a hardcoded `us`. See the header of vm-keyboard.nix. +# # Run them ONE AT A TIME. Each boots a VM with a software-rendered compositor; # two at once on a two-core machine make the timing-sensitive assertions flake, # and a flaky green is worth less than a slow one. @@ -26,9 +33,9 @@ let hhstream = self.packages.${system}.hhstream; hhsModule = self.nixosModules.default; testTools = pkgs.callPackage ./lib/test-tools.nix { }; - # The three session checks take the same five arguments; naming them once - # keeps a new check from being wired up with a different compositor or a - # different package than its neighbours. + # The session checks take the same arguments; naming them once keeps a new + # check from being wired up with a different compositor or a different + # package than its neighbours. sessionArgs = { inherit hhstream hhsModule testTools; }; @@ -53,4 +60,10 @@ in vm-containers = pkgs.callPackage ./vm-containers.nix sessionArgs; vm-pointer = pkgs.callPackage ./vm-pointer.nix sessionArgs; + + vm-keyboard = pkgs.callPackage ./vm-keyboard.nix sessionArgs; + + vm-keyboard-de = pkgs.callPackage ./vm-keyboard.nix ( + sessionArgs // { keyboardLayout = "de"; } + ); } diff --git a/checks/lib/keyboard_target.py b/checks/lib/keyboard_target.py new file mode 100644 index 0000000..732fe98 --- /dev/null +++ b/checks/lib/keyboard_target.py @@ -0,0 +1,339 @@ +#!/usr/bin/env python3 +"""A Wayland client that says which keys it was sent, in the layout's own words. + +A sibling of ``pointer_target.py`` and deliberately not an extension of it: +that client's contract is "report pointer events", this one's is "report +keyboard events, decoded with the keymap the compositor forwarded", and the +second needs a dependency (xkbcommon) and a seat capability the first does not. +Two small programs read better than one with a mode switch, and the pointer +checks should not start failing because the keyboard check needed a new +listener. + +Three things it does that matter to the assertions: + +* **It sets ``xdg_toplevel`` app id from ``$HHSTREAM_APP_ID``**, which is what + gets its window into its session's container. ``foot`` and ``wev`` ignore + the environment, keep their own class, match no per-session rule and are + swept into the quarantine workspace — so there would be nothing for the + cursor to land in. Same reason ``pointer_target.py`` exists. + +* **Every keysym it prints is decoded from the keymap the compositor sent it**, + over ``wl_keyboard.keymap``, compiled here with xkbcommon and updated with + ``xkb_state_update_mask`` on every ``modifiers`` event. Never from a table + in this file. That is the whole mutation rule for the check: keycodes that + arrive with no decodable symbol are a failure, not a pass, so a driver that + stopped uploading its keymap cannot leave the check green. If no keymap + arrived, ``sym`` is printed as ``?`` and says so. + +* **It prints the raw evdev code beside the symbol, and the modifier mask + beside both.** A toolkit that ignored ``wl_keyboard.modifiers`` and shifted + only on ``KEY_LEFTSHIFT`` would decode a capital wrongly, so the check has to + see the mask the compositor forwarded *and* the absence of a Shift keycode — + the mask is how this build makes a capital, and sending both is how a + capital gets shifted twice or not at all. + +It also binds ``wl_pointer`` and prints ``enter``/``leave`` for it. Not +decoration: a cursor that arrives in a window whose keyboard focus did not +follow is exactly the failure a one-warp ``acquire`` produces, and without the +pointer line the check could not tell that apart from a warp that never +arrived at all. + +Deliberately loud and deliberately unbuffered: the broker captures stdout into +the session log, so ``hhstream session logs`` is the read-back, and a check +that goes red says whether the window was never mapped, never focused, or +focused and sent the wrong symbol. +""" + +from __future__ import annotations + +import argparse +import mmap +import os +import signal +import struct +import sys + +from pywayland.client import Display +from pywayland.protocol.wayland import WlCompositor, WlSeat, WlShm +from pywayland.protocol.xdg_shell import XdgWmBase +from xkbcommon import xkb + +#: Opaque 32-bit colour. Something has to be in the buffer for the compositor +#: to map the surface at all, and an unmapped surface is never focused. +FILL = 0xFF2A4D6E + +#: Fallback size for a compositor that configures 0x0 ("you choose"). +DEFAULT_SIZE = (640, 360) + +#: A Wayland/evdev keycode is the XKB keycode minus 8. ``wl_keyboard.key`` +#: carries the evdev value; xkbcommon's tables are indexed by the XKB one. +EVDEV_OFFSET = 8 + +#: ``wl_keyboard.key_state``. ``2`` is ``repeated`` and only reaches a version +#: 10 client; it is named here so a count of presses cannot miss one. +STATE_NAMES = {0: "released", 1: "pressed", 2: "repeated"} + + +def say(line: str) -> None: + """One line, flushed. The reader is a log tail.""" + + print(line, flush=True) + + +class Target: + def __init__(self, app_id: str, title: str) -> None: + self.app_id = app_id + self.title = title + self.display: Display | None = None + self.compositor = None + self.shm = None + self.wm_base = None + self.seat = None + self.window: _Window | None = None + self.keyboard = None + self.pointer = None + + #: The compositor's own keymap, as forwarded, and a state machine over + #: it. Every `sym=` comes from here; see the module docstring. + self._keymap = None + self._state = None + + # -- setup --------------------------------------------------------- + + def run(self) -> int: + self.display = Display() + self.display.connect() + registry = self.display.get_registry() + registry.dispatcher["global"] = self._on_global + self.display.roundtrip() + + missing = [ + name + for name, value in ( + ("wl_compositor", self.compositor), + ("wl_shm", self.shm), + ("xdg_wm_base", self.wm_base), + ("wl_seat", self.seat), + ) + if value is None + ] + if missing: + say(f"target: FATAL missing globals: {', '.join(missing)}") + return 1 + self.wm_base.dispatcher["ping"] = lambda base, serial: base.pong(serial) + self.seat.dispatcher["capabilities"] = self._on_capabilities + + self.window = _Window(self) + self.display.roundtrip() + say(f"target: app_id={self.app_id} pid={os.getpid()}") + + while True: + # Blocking dispatch: this process exists to report events, so there + # is nothing to do between them and nothing to poll for. + if self.display.dispatch(block=True) < 0: + say("target: display disconnected") + return 1 + + def _on_global(self, registry, global_id: int, interface: str, version: int) -> None: + if interface == WlCompositor.name: + self.compositor = registry.bind(global_id, WlCompositor, min(version, 4)) + elif interface == WlShm.name: + self.shm = registry.bind(global_id, WlShm, 1) + elif interface == XdgWmBase.name: + self.wm_base = registry.bind(global_id, XdgWmBase, min(version, 2)) + elif interface == WlSeat.name and self.seat is None: + self.seat = registry.bind(global_id, WlSeat, min(version, 5)) + + def _on_capabilities(self, seat, capabilities: int) -> None: + """Bind what the seat has, and say out loud what it has not. + + A headless seat has **no keyboard capability at all** until something + creates a virtual one — there is no input device here — so + "keyboard not bound" is a statement about the driver, not about this + client, and a check that saw no key events needs to know which. + """ + + say(f"target: seat capabilities={capabilities}") + if capabilities & WlSeat.capability.keyboard.value and self.keyboard is None: + self.keyboard = seat.get_keyboard() + self.keyboard.dispatcher["keymap"] = self._on_keymap + self.keyboard.dispatcher["enter"] = self._on_enter + self.keyboard.dispatcher["leave"] = self._on_leave + self.keyboard.dispatcher["key"] = self._on_key + self.keyboard.dispatcher["modifiers"] = self._on_modifiers + self.keyboard.dispatcher["repeat_info"] = self._on_repeat_info + say("target: keyboard bound") + elif not capabilities & WlSeat.capability.keyboard.value: + say("target: seat has no keyboard capability yet") + + if capabilities & WlSeat.capability.pointer.value and self.pointer is None: + self.pointer = seat.get_pointer() + self.pointer.dispatcher["enter"] = self._on_pointer_enter + self.pointer.dispatcher["leave"] = self._on_pointer_leave + say("target: pointer bound") + + # -- keyboard ------------------------------------------------------ + + def _on_keymap(self, keyboard, format_: int, fd: int, size: int) -> None: + """Compile what the compositor forwarded, and decode with it. + + The size on the wire includes the NUL terminator, so the text is + everything up to the first one. A keymap that will not compile is + reported rather than swallowed: it is indistinguishable, from here, + from a compositor that was never given one, and the two have very + different causes. + """ + + try: + with os.fdopen(fd, "rb", closefd=True) as handle: + raw = handle.read(size) + except OSError as exc: + say(f"keyboard keymap bytes={size} UNREADABLE {exc}") + return + text = raw.split(b"\0", 1)[0].decode("utf-8", "replace") + symbols = next( + (line.strip() for line in text.splitlines() if "xkb_symbols" in line), "?" + ) + try: + self._keymap = xkb.Context().keymap_new_from_string(text) + self._state = self._keymap.state_new() + except Exception as exc: + say(f"keyboard keymap bytes={size} WILL-NOT-COMPILE {exc}") + return + # `symbols=` is the line the check greps to prove *which* layout was + # uploaded: `pc_us_inet(evdev)` against `pc_de_inet(evdev)`. + say(f"keyboard keymap format={format_} bytes={size} symbols={symbols}") + + def _sym(self, code: int) -> str: + """The keysym name for an evdev code, under the forwarded keymap.""" + + if self._state is None: + # `?` and not a guess: the check treats a key with no symbol as a + # failure, which is what makes "the keymap was uploaded" an + # assertion rather than an assumption. + return "?" + return xkb.keysym_get_name(self._state.key_get_one_sym(code + EVDEV_OFFSET)) + + def _on_enter(self, keyboard, serial, surface, keys) -> None: + held = list(keys) if keys else [] + say(f"keyboard enter serial={serial} keys={held}") + + def _on_leave(self, keyboard, serial, surface) -> None: + say(f"keyboard leave serial={serial}") + + def _on_key(self, keyboard, serial, time_, key: int, state: int) -> None: + say( + f"keyboard key code={key} state={state}" + f" ({STATE_NAMES.get(state, 'unknown')}) sym={self._sym(key)}" + ) + + def _on_modifiers(self, keyboard, serial, depressed, latched, locked, group) -> None: + if self._state is not None: + # The mask first, then the sym lookup above is the one a real + # client does: `A` is only `A` because Shift is in this mask. + self._state.update_mask(depressed, latched, locked, 0, 0, group) + say( + f"keyboard modifiers depressed={depressed} latched={latched}" + f" locked={locked} group={group}" + ) + + def _on_repeat_info(self, keyboard, rate: int, delay: int) -> None: + say(f"keyboard repeat_info rate={rate} delay={delay}") + + # -- pointer, for telling two failures apart ------------------------ + + def _on_pointer_enter(self, pointer, serial, surface, x, y) -> None: + say(f"pointer enter x={x:.2f} y={y:.2f}") + + def _on_pointer_leave(self, pointer, serial, surface) -> None: + say("pointer leave") + + +class _Window: + """One toplevel: a surface, its xdg wrapper, and an shm buffer.""" + + def __init__(self, target: Target) -> None: + self.target = target + self.size = DEFAULT_SIZE + self.buffer = None + self._pool = None + self._map: mmap.mmap | None = None + + self.surface = target.compositor.create_surface() + self.xdg_surface = target.wm_base.get_xdg_surface(self.surface) + self.xdg_surface.dispatcher["configure"] = self._on_configure + self.toplevel = self.xdg_surface.get_toplevel() + # The whole reason this program exists rather than `wev`. + self.toplevel.set_app_id(target.app_id) + self.toplevel.set_title(target.title) + self.toplevel.dispatcher["configure"] = self._on_toplevel_configure + self.toplevel.dispatcher["close"] = lambda *_: sys.exit(0) + self.surface.commit() + + def _on_toplevel_configure(self, toplevel, width, height, states) -> None: + if width and height: + self.size = (width, height) + + def _on_configure(self, xdg_surface, serial) -> None: + xdg_surface.ack_configure(serial) + self._paint() + say(f"target: window configured {self.size[0]}x{self.size[1]}") + + def _paint(self) -> None: + width, height = self.size + stride = width * 4 + size = stride * height + if self._map is None or self._map.size() < size: + self._allocate(size) + # A flat fill, written once per resize: the pixels are not the subject + # of any assertion, they only make the surface mappable. + self._map.seek(0) + self._map.write(struct.pack(" None: + fd = os.memfd_create("hhs-keyboard-target", 0) + os.ftruncate(fd, size) + self._map = mmap.mmap(fd, size) + self._pool = self.target.shm.create_pool(fd, size) + os.close(fd) + + +def main(argv: list[str] | None = None) -> int: + parser = argparse.ArgumentParser( + prog="hhs-keyboard-target", + description="A Wayland window that reports the key events it receives, " + "decoded with the keymap the compositor forwarded.", + ) + parser.add_argument( + "--app-id", + default=None, + help="xdg_toplevel app id; the default is $HHSTREAM_APP_ID, which is how " + "a session's window rule finds its container", + ) + parser.add_argument("--title", default="hhs-keyboard-target") + args = parser.parse_args(argv) + + app_id = args.app_id or os.environ.get("HHSTREAM_APP_ID") + if not app_id: + print( + "hhs-keyboard-target: no --app-id and no $HHSTREAM_APP_ID; refusing to " + "guess, because the app id is the whole point of this program", + file=sys.stderr, + ) + return 2 + + # The broker kills the process group; exit on the first signal rather than + # leaving the compositor to notice a dead client. + signal.signal(signal.SIGTERM, lambda *_: sys.exit(0)) + signal.signal(signal.SIGINT, lambda *_: sys.exit(0)) + return Target(app_id, args.title).run() + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/checks/lib/session-machine.nix b/checks/lib/session-machine.nix index b09fb76..fd3a6e9 100644 --- a/checks/lib/session-machine.nix +++ b/checks/lib/session-machine.nix @@ -29,6 +29,17 @@ # Only read when `pointer` is true; the module's own defaults otherwise. leaseTtl ? 30, leaseMax ? 300, + # The XKB layout the pointer unit uploads as its virtual keyboard's keymap. + # There is no `keyboard.enable`: the keyboard is the same unit, the same + # process and the same lease as the pointer, so `pointer = true` is what + # turns typing on. This is only the layout, and `vm-keyboard` is the only + # check that sets it to anything but the default -- it runs twice, once per + # layout, because the layout only reaches the keymap through this unit's + # argv and a second value is the only way to prove that. + keyboardLayout ? "us", + keyboardModel ? "pc105", + keyboardVariant ? "", + keyboardOptions ? "", width ? 1280, height ? 720, fps ? 30, @@ -73,6 +84,12 @@ enable = pointer; inherit leaseTtl leaseMax; }; + keyboard = { + layout = keyboardLayout; + model = keyboardModel; + variant = keyboardVariant; + options = keyboardOptions; + }; }; }; @@ -106,7 +123,7 @@ environment.systemPackages = [ testTools # hhs-hyprland-diagnostics - sessionTools # hhs-ipc-watch, hhs-pointer-target + sessionTools # hhs-ipc-watch, hhs-pointer-target, hhs-keyboard-target hhstream # the CLI under test hyprland # hyprctl: the compositor is the source of truth here foot diff --git a/checks/lib/session-tools.nix b/checks/lib/session-tools.nix index ea956ab..7a06632 100644 --- a/checks/lib/session-tools.nix +++ b/checks/lib/session-tools.nix @@ -1,55 +1,105 @@ # The guest programs the session checks need, packaged with the interpreters # they actually require. # -# Separate from `test-tools.nix` because these two need things that one does -# not: `hhs-ipc-watch` imports the shipped `hhstreamd.ipc` (so it needs the -# package on PYTHONPATH -- it is the client under test, not a reimplementation -# of it), and `hhs-pointer-target` is a Wayland client (so it needs pywayland). +# Separate from `test-tools.nix` because these need things that one does not: +# `hhs-ipc-watch` imports the shipped `hhstreamd.ipc` (so it needs the package +# on PYTHONPATH -- it is the client under test, not a reimplementation of it), +# and the two targets are Wayland clients (so they need pywayland, and the +# keyboard one also xkbcommon). # -# Both are self-tested at build time, for the same reason test-tools.nix does -# it: a broken helper otherwise surfaces as a baffling VM failure three layers -# away, long after the thing that would have explained it scrolled past. +# All three are self-tested at build time, for the same reason test-tools.nix +# does it: a broken helper otherwise surfaces as a baffling VM failure three +# layers away, long after the thing that would have explained it scrolled past. +# +# ─── NO HEREDOC HERE, AND THAT IS NOT A STYLE PREFERENCE ───────────────────── +# This file used to write the `hhs-ipc-watch` shim with `cat > $out/bin/... < $out/bin/hhs-ipc-watch < /dev/null $out/bin/hhs-pointer-target --help > /dev/null + $out/bin/hhs-keyboard-target --help > /dev/null ${waylandPython}/bin/python3 -c 'from pywayland.protocol.xdg_shell import XdgWmBase' - # The target refuses to guess an app id, and the checks depend on that + + # xkbcommon, and a keymap that really compiles: the keyboard target decodes + # every symbol through this, so a broken binding would show up in the guest + # as every key arriving with an undecodable symbol and no explanation. + ${keyboardPython}/bin/python3 -c 'from xkbcommon import xkb; k = xkb.Context().keymap_new_from_names(rules="evdev", model="pc105", layout="us"); assert xkb.keysym_get_name(k.state_new().key_get_one_sym(38)) == "a"' + + # Both targets refuse to guess an app id, and the checks depend on that # refusal being exit 2 rather than a window with somebody else's class. - if $out/bin/hhs-pointer-target; then - echo "hhs-pointer-target started with no app id; it must refuse" >&2 - exit 1 - fi + for target in hhs-pointer-target hhs-keyboard-target; do + if $out/bin/$target; then + echo "$target started with no app id; it must refuse" >&2 + exit 1 + fi + done '' diff --git a/checks/unit.nix b/checks/unit.nix index de0ac15..4a29301 100644 --- a/checks/unit.nix +++ b/checks/unit.nix @@ -18,7 +18,13 @@ hhstream, }: let - pytestEnv = python3.withPackages (ps: [ ps.pytest ps.pywayland ]); + # `xkbcommon` beside `pywayland`, and it is not optional: `tests/pointer/ + # test_keymap.py` compiles a real `us` keymap and a real `de` one, because + # only xkbcommon can say that `é` is unmappable on `us` and that `@` on `de` + # needs a level-three mask rather than Shift. A suite that could skip those + # would let the unmappable-character path rot, which is the path that decides + # whether a bad string types a prefix. + pytestEnv = python3.withPackages (ps: [ ps.pytest ps.pywayland ps.xkbcommon ]); # Only the suite itself, so an editor's droppings or a local .pytest_cache # cannot change the derivation's hash. diff --git a/checks/vm-keyboard.nix b/checks/vm-keyboard.nix new file mode 100644 index 0000000..efbc969 --- /dev/null +++ b/checks/vm-keyboard.nix @@ -0,0 +1,975 @@ +# checks..vm-keyboard -- the keymap, the focus, and a symbol a client decoded. +# +# The resolver's arithmetic is already proved by the unit suite against real +# xkbcommon, and the lease's by an injected clock. What no fake can prove is +# the half this check is for: that the keymap we upload reaches a real +# compositor, that `pointer acquire` leaves the aimed window holding the +# *keyboard* and not merely the cursor, and that an application underneath +# decodes the symbol we meant from the keymap it was forwarded. +# +# `docs/TODO/scroll-has-no-compositor-proof.md` is the precedent this exists to +# avoid: scroll shipped on the driver socket with no compositor proof. The +# keyboard's only purpose is that a client receives symbols, so a unit suite +# alone would be testing the shape of a request nobody answered. +# +# ─── WHY THE VICTIM DECODES, AND WHY THAT IS THE MUTATION RULE ─────────────── +# PLAN §14: read back the *application's* state. For the keyboard that is +# sharper than for the pointer, because there are two ways to be wrong and +# only one of them shows in the keycodes. +# +# `hhs-keyboard-target` (checks/lib/keyboard_target.py) compiles the keymap the +# compositor sent it over `wl_keyboard.keymap` and decodes every key through +# that, printing `code= state= sym=`. So: +# +# * a driver that stopped uploading a keymap leaves the client with nothing +# to decode with, every key arrives as `sym=?`, and the character +# assertions go red -- which is the mutation PLAN §14 asks for: keycodes +# without a decoded `hello` are a failure, not a pass; +# * a driver that uploaded the WRONG layout is caught by the same lines, in +# two places: the `symbols=` line names `pc_us_inet(evdev)` against +# `pc_de_inet(evdev)`, and a keysym's evdev code differs between them. +# +# A victim with its own keymap would decode `hello` from either, and the check +# would be asserting that this file can spell. +# ───────────────────────────────────────────────────────────────────────────── +# +# ─── WHY IT RUNS TWICE, ONCE PER LAYOUT ────────────────────────────────────── +# `sessions.keyboard.layout` reaches the uploaded keymap through exactly one +# path: `--xkb-layout` on `hhstream-pointer`'s ExecStart. A single-layout check +# cannot tell that path from a hardcoded `us`, and the unit test that reads the +# flag cannot tell it from a module that renders the option somewhere nothing +# reads -- which is what an earlier draft of the plan proposed (`[keyboard]` in +# the broker's TOML, read by `hhstreamd`, which is a different unit). +# +# So `default.nix` exposes `vm-keyboard` (layout `us`) and `vm-keyboard-de` +# (layout `de`), both from this file. Everything is asserted in both; the +# layout-dependent expectations come from `EXPECT` below. Hyprland's own +# `input:kb_layout` is deliberately left alone in both -- it stays `us`, so on +# the `de` run a client that ignored our keymap would decode the `us` answer +# and the check would say so. +# ───────────────────────────────────────────────────────────────────────────── +# +# ─── WHERE THIS DEVIATES FROM THE WRITTEN SPEC, AND WHY ────────────────────── +# `docs/plans/2026-10-04-keyboard-verification.md` §B3's layout subtest says +# "`keyboard type y` decodes to sym `z`". **That expectation is wrong for a +# victim that decodes from the forwarded keymap**, which the same section +# requires two paragraphs earlier. `keyboard type y` resolves keysym `y` +# against the uploaded layout and sends *that layout's* code for it; the client +# then decodes the same code with the same keymap and gets `y` back. The sym is +# `y` on both layouts, by construction, and a check asserting `z` would fail +# against a correct driver. +# +# What actually differs between the layouts, and is asserted here instead: +# +# * the EVDEV CODE keysym `y` lives on (21 on us, 44 on de -- they swap); +# * the `symbols=` name in the forwarded keymap; +# * whether `ü` is typeable at all (exit 2 on us, `udiaeresis` on de). +# +# The third is the strongest: it is a behavioural difference no amount of +# decoding confusion can fake. +# +# §B3's subtest 1 says "`pointer acquire` on A, **one warp**", and +# `docs/reviews/2026-10-04-stage0-review.md` is blunter: "Do not assert +# `wl_keyboard.enter` on `pointer acquire`. Acquire is one warp." Both were +# right when written and are now superseded by an operator decision: acquire +# grabs the keyboard as well as the cursor, so it sends **two** warps a real +# pixel apart and `nix/hyprland-conf.nix` pins the threshold the second one +# depends on. The enter assertion is therefore live rather than expected-red -- +# and the review's reason for doubting it is exactly why this check asserts the +# keyboard half separately from the pointer half, instead of trusting that a +# delivered cursor implies delivered keys. +# +# The victim's lines are the Stage 0 probe's with two deliberate differences: +# every line is prefixed `keyboard ` or `pointer `, and the key state carries +# its name. The prefix is not cosmetic -- `wl_pointer.enter` contains the +# substring `enter`, and an unanchored match of one reporting the other is a +# false pass this project has already shipped once, in the probe itself. +# ───────────────────────────────────────────────────────────────────────────── +# +# Real time, no injected clock, same as `vm-pointer`: the expiry subtest uses a +# caller-supplied `--ttl` of a few seconds and waits for it. An injected clock +# would prove the arithmetic the unit suite already proves, and not the +# sweeper, the `release_all` it calls, or the key-up the client has to be told +# about. +{ + testers, + hhstream, + hhsModule, + testTools, + hyprland, + foot, + jq, + grim, + procps, + coreutils, + dejavu_fonts, + width ? 1280, + height ? 720, + sessionUser ? "hermes", + # Deliberately much longer than `vm-pointer`'s, and the expiry subtest does + # not use them: it supplies its own `--ttl` of a few seconds, which is the + # only place a deadline is under test. + # + # These are generous because every verb below is a `systemd-run` round trip + # of several seconds and this check has three times as many of them. At + # `vm-pointer`'s 120 s hard cap, the lease taken in the acquire subtest would + # expire somewhere in the middle of the script -- and the symptom would be a + # later subtest failing with exit 9 for a reason that has nothing to do with + # what it asserts. `hold()` in the script is the other half of that guard. + leaseTtl ? 60, + leaseMax ? 600, + # `us` or `de`; see the block above for why both exist. + keyboardLayout ? "us", +}: +testers.runNixOSTest ( + { pkgs, lib, ... }: + let + tools = pkgs.callPackage ./lib/session-tools.nix { inherit hhstream; }; + guest = import ./lib/session-machine.nix { + inherit + hhsModule + hhstream + hyprland + testTools + foot + jq + procps + grim + coreutils + dejavu_fonts + ; + sessionTools = tools; + }; + prelude = import ./lib/session-prelude.nix { + inherit hhstream coreutils sessionUser; + }; + target = pkgs.writeShellScript "hhs-keyboard-target-wrapper" '' + exec ${tools}/bin/hhs-keyboard-target --app-id "$HHSTREAM_APP_ID" "$@" + ''; + + # What this layout is expected to do, as data rather than as branches in + # the script. Both runs assert every row; only the values differ. + expectations = { + us = { + symbols = "pc_us_inet(evdev)"; + yCode = 21; # KEY_Y + zCode = 44; # KEY_Z + # `ü` has no keysym on a plain `us` map, so the whole string is refused + # and nothing is typed. + diaeresisTypeable = false; + }; + de = { + symbols = "pc_de_inet(evdev)"; + # The swap: keysym `y` is on the physical Z key and vice versa. + yCode = 44; + zCode = 21; + diaeresisTypeable = true; + }; + }; + expect = + expectations.${keyboardLayout} + or (throw "vm-keyboard has no expectations for layout ${keyboardLayout}"); + in + { + name = "hhstream-vm-keyboard-${keyboardLayout}"; + + # The order of `vm-pointer`'s. This check boots a VM with a + # software-rendered compositor and waits out a real lease TTL; that is slow + # and is not a reason to fold it into a unit test. + globalTimeout = 1800; + + nodes.machine = guest { + inherit + width + height + sessionUser + leaseTtl + leaseMax + keyboardLayout + ; + pointer = true; + apps.target = { + exec = "${target}"; + argsAllow = [ ]; + }; + # NOT set: `input:kb_layout`. It stays at the compositor's own default + # (`us`) in both runs, which is what makes the `de` run meaningful -- a + # client that ignored our uploaded keymap would decode the `us` answer. + # And NOT set: `follow_mouse`, which `nix/hyprland-conf.nix` now ships as + # `1` with `follow_mouse_threshold = 0` beside it. `vm-pointer` overrides + # the first through `extraConfig`; this check deliberately does not, + # because acquire's focus guarantee depends on the shipped values and an + # override here would hide a regression in them. + extraConfig = ""; + }; + + testScript = + prelude + + '' + import re + + LAYOUT = "${keyboardLayout}" + SYMBOLS = "${expect.symbols}" + Y_CODE = ${toString expect.yCode} + Z_CODE = ${toString expect.zCode} + DIAERESIS_TYPEABLE = ${if expect.diaeresisTypeable then "True" else "False"} + POINTER_SOCKET = "/run/hhstream/pointer.sock" + + #: evdev codes from `linux/input-event-codes.h`. These are the integers + #: `wl_keyboard.key` carries; the XKB keycode is 8 higher and never + #: leaves the driver, so asserting 38 for `a` would be asserting an + #: index no client ever sees. + KEY_A = 30 + KEY_LEFTSHIFT = 42 + + #: `wl_keyboard.key_state`. + RELEASED, PRESSED = 0, 1 + + + def target_log(session_id, lines=800): + """Every line the victim has printed so far. + + The session log is the application's own captured stdout and + nothing else -- no broker commands, no echoed arguments -- which is + what makes grepping it an assertion about the client. The parsers + below anchor at the start of a line anyway. + """ + + return machine.succeed(cli(f"logs {session_id} --lines {lines}"), timeout=120) + + + def keys(session_id): + """(code, state, sym) from every `keyboard key` line, in order.""" + + found = [] + for line in target_log(session_id).splitlines(): + match = re.match( + r"keyboard key code=(\d+) state=(\d+) \(\w+\) sym=(\S+)$", line + ) + if match: + found.append( + (int(match.group(1)), int(match.group(2)), match.group(3)) + ) + return found + + + def masks(session_id): + """The `depressed` mask from every `keyboard modifiers` line.""" + + found = [] + for line in target_log(session_id).splitlines(): + match = re.match(r"keyboard modifiers depressed=(\d+) ", line) + if match: + found.append(int(match.group(1))) + return found + + + def events(session_id, prefix): + """Lines starting with `prefix`, in order. + + Anchored, because `pointer enter` and `keyboard enter` both contain + `enter` -- and an unanchored match on one of them reporting the + other is a false pass this project has already made once, in the + Stage 0 probe. + """ + + return [ + line + for line in target_log(session_id).splitlines() + if line.startswith(prefix) + ] + + + def keymap_lines(session_id): + return events(session_id, "keyboard keymap ") + + + def typed(session_id, since): + """The symbols of the key-DOWNS after index `since`. + + Downs only: a tap is a pair, and "the client was told h,e,l,l,o" + reads better as five symbols than as ten. + """ + + return [sym for code, state, sym in keys(session_id)[since:] if state == PRESSED] + + + def first_index(session_id, prefix): + """Line number of the first line starting with `prefix`, or None.""" + + for index, line in enumerate(target_log(session_id).splitlines()): + if line.startswith(prefix): + return index + return None + + + def hold(session_id): + """Make sure `session_id` holds the lease, acquiring if it does not. + + Not laziness: this check runs dozens of verbs and the hard cap is + real, so a lease taken in one subtest cannot be assumed to survive + to a later one. Without this, a cap that expired mid-script would + show up as some unrelated subtest failing with exit 9 -- which is + a true statement about the lease and a useless one about the + assertion that was being made. + + It never *releases*, so a subtest that is deliberately holding a + key keeps it. + """ + + state = cli_json("pointer state --json") + if state["holder"] == session_id: + return state["lease_id"] + if state["holder"] is not None: + machine.succeed(cli(f"pointer release {state['holder']}"), timeout=120) + return cli_json(f"pointer acquire --json {session_id}", timeout=120)["lease_id"] + + + def start_target(): + """Start a session and wait for its window to reach its container. + + It dumps its *own* session's log on failure rather than leaving + that to the caller, and that is not tidiness: the caller's + `alpha, alpha_output = start_target()` has not bound `alpha` yet + when this raises, so a `dump(..., locals().get("alpha"))` in the + subtest gets `None` and prints every diagnostic except the one + that matters -- the application's own captured output. Measured, + by a run that failed here and said nothing about why. + """ + + session_id = machine.succeed(cli("start target"), timeout=180).strip() + output = f"hh-{session_id}" + try: + machine.wait_until_succeeds( + f"{HYPRCTL} clients | jq -e --arg m {output}" + " 'any(.initialClass == $m)' >/dev/null", + timeout=120, + ) + wait_for( + lambda: "target: keyboard bound" in target_log(session_id), + timeout=120, + what=f"{session_id} to bind wl_keyboard", + ) + except Exception: + dump(f"{session_id} never mapped a window or bound a keyboard", session_id) + raise + return session_id, output + + + start_all() + bring_up("the compositor and broker") + + with subtest("the driver comes up and uploaded a keymap for this layout"): + # The unit's own journal is where a layout xkbcommon refused shows + # up, as exit 2 before any Wayland call -- which is a restart loop + # with its own words in it rather than a silent default. + try: + machine.wait_for_unit("hhstream-pointer.service", timeout=180) + machine.wait_for_file(POINTER_SOCKET, timeout=120) + restarts = machine.succeed( + "systemctl show -p NRestarts --value hhstream-pointer.service" + ).strip() + assert restarts == "0", ( + f"the driver has restarted {restarts} time(s); read its journal" + ) + journal = machine.succeed( + "journalctl --no-pager --boot --unit hhstream-pointer.service" + ) + print(journal) + assert "uploaded a" in journal and "keymap" in journal, ( + "the driver never logged a keymap upload. `key` before " + "`keymap` is the protocol error `no_keymap`, which kills " + "the connection rather than answering, so this must happen " + "before the socket listens:\n" + journal + ) + # The flag really is on the command line, with this layout. + argv = machine.succeed( + "systemctl show -p ExecStart --value hhstream-pointer.service" + ) + print(argv) + assert f"--xkb-layout {LAYOUT}" in argv, ( + f"the unit does not pass --xkb-layout {LAYOUT}: {argv}" + ) + except Exception: + dump("the driver did not come up with a keymap") + raise + + with subtest("a session's window is in its container, and binds a keyboard"): + # The seat of a headless session has no keyboard capability until + # something creates a virtual one: there is no input device here. + # So "target: keyboard bound" is itself proof that the driver's + # `zwp_virtual_keyboard_v1` reached the seat, and not merely that + # the broker believes it sent something. + try: + alpha, alpha_output = start_target() + print(f"session {alpha} -> {alpha_output}") + print(target_log(alpha)) + except Exception: + # `start_target` dumps its own session's log; this covers the + # case where `start` itself failed and there is no session id + # to dump -- a target that exited immediately, for instance, + # which is exit 4 with the reason only in the broker's log. + dump("the victim never got a window or a keyboard", locals().get("alpha")) + raise + + with subtest("the client was forwarded the keymap this layout names"): + # The direct proof that our upload arrived, and the thing that + # tells the two layouts apart independently of any keystroke. + try: + lines = wait_for( + lambda: keymap_lines(alpha), + timeout=120, + what="the compositor to forward a keymap", + ) + print("\n".join(lines)) + assert len(lines) == 1, ( + f"the client was sent {len(lines)} keymaps; the driver uploads " + f"exactly one, after connect and before listen: {lines}" + ) + assert "WILL-NOT-COMPILE" not in lines[0], lines[0] + assert "UNREADABLE" not in lines[0], lines[0] + assert "format=1" in lines[0], ( + f"the keymap arrived in a format other than xkb_v1: {lines[0]}" + ) + assert SYMBOLS in lines[0], ( + f"the forwarded keymap is not {LAYOUT}: {lines[0]}. Expected " + f"symbols={SYMBOLS}. A `de` run that says pc_us_inet means " + "--xkb-layout never reached xkb_keymap_new_from_names." + ) + # And it arrived BEFORE any key did, which is the verification + # doc's own rule: a decoded symbol is only evidence of our + # upload if the client had the keymap when the key arrived. + # Asserted on log position and not on subtest order, because + # subtest order is this file's choice and log position is the + # compositor's. + keymap_at = first_index(alpha, "keyboard keymap ") + key_at = first_index(alpha, "keyboard key ") + print(f"keymap at line {keymap_at}, first key at line {key_at}") + assert keymap_at is not None + assert key_at is None or keymap_at < key_at, ( + f"a key arrived at line {key_at} before the keymap at " + f"{keymap_at}; every symbol decoded before that is a guess" + ) + except Exception: + dump("the keymap did not reach the client", alpha) + raise + + with subtest("a second session takes focus, which is what subtest 4 needs"): + # Started here, and not in the subtest that needs it, because what + # makes it useful is that its window opened LAST: that is how it + # holds focus, and it is the situation `vm-pointer` found the hard + # way. Both sessions exist from here on. + try: + beta, beta_output = start_target() + print(f"session {beta} -> {beta_output}") + focused = [ + c.get("initialClass") + for c in compositor("clients") + if c.get("focusHistoryID") == 0 + ] + print(f"the compositor's focused window belongs to: {focused}") + assert focused and focused[0] == beta_output, ( + f"this check needs {beta} focused after it opened; {focused} is. " + "Every assertion below about acquire moving focus is " + "vacuous otherwise." + ) + # And it is the keyboard focus, not merely the stacking order: + # beta was told it has the keys. + wait_for( + lambda: events(beta, "keyboard enter"), + timeout=60, + what=f"{beta} to be told it holds keyboard focus", + ) + except Exception: + dump("the second session did not take focus", locals().get("beta")) + raise + + with subtest("acquire takes the KEYBOARD as well as the cursor"): + # The measurement this whole feature turns on, and the one a + # careless version of this check would fake. + # + # `pointer acquire` warps into alpha's container while BETA holds + # keyboard focus. A check that asserted only `pointer enter` on + # alpha would go green while alpha had the cursor, beta had the + # keys, and the first keystroke of the lease went to beta -- which + # is exactly what one warp does: Hyprland zeroes `m_mousePosDelta` + # when the previous movement was over 0.5s ago, and keyboard focus + # is that delta compared against `input:follow_mouse_threshold`. + # + # So acquire sends two motions a real pixel apart, and this subtest + # asserts BOTH halves: the cursor arrived (pointer enter on alpha) + # and the keys moved with it (keyboard enter on alpha, keyboard + # leave on beta). + try: + before_pointer = len(events(alpha, "pointer enter")) + before_enter = len(events(alpha, "keyboard enter")) + before_leave = len(events(beta, "keyboard leave")) + + reply = cli_json(f"pointer acquire --json {alpha}", timeout=120) + print(json.dumps(reply, indent=2, sort_keys=True)) + assert reply["bookmark"]["output"] == alpha_output, reply + assert reply["focus"] == "warp", ( + f"acquire reports focus={reply['focus']!r}; `warp` is the " + "path that should have run. `focuswindow` means the nudge " + "could not be sent, `none` that neither worked." + ) + + wait_for( + lambda: events(alpha, "pointer enter")[before_pointer:], + timeout=60, + what=f"{alpha} to be told the cursor arrived", + ) + entered = wait_for( + lambda: events(alpha, "keyboard enter")[before_enter:], + timeout=60, + what=( + f"{alpha} to be told it holds KEYBOARD focus after acquire. " + "The cursor arriving is not enough: see the comment above " + "this subtest" + ), + ) + left = wait_for( + lambda: events(beta, "keyboard leave")[before_leave:], + timeout=60, + what=f"{beta} to be told it lost keyboard focus", + ) + print(f"{alpha} entered: {entered}") + print(f"{beta} left: {left}") + lease = reply["lease_id"] + except Exception: + dump("acquire did not move keyboard focus to the aimed session", alpha) + raise + + with subtest("a capital is a modifier MASK and not a Shift keycode"): + # The worked example, and the one place a toolkit could be right + # for the wrong reason. Hyprland's virtual keyboard never runs + # `updateXkbStateWithKey`, so an injected KEY_LEFTSHIFT changes no + # modifier state at all -- the mask is the only thing that makes a + # capital, and sending both is how a client shifts twice or not at + # all. The client prints the mask and the sym, so both are checked. + try: + hold(alpha) + before = len(keys(alpha)) + before_masks = len(masks(alpha)) + machine.succeed(cli(f"keyboard type {alpha} A"), timeout=120) + + pair = wait_for( + lambda: ( + keys(alpha)[before:] if len(keys(alpha)) >= before + 2 else None + ), + timeout=60, + what="the client to report a press and a release of `A`", + ) + print(f"the client reports keys: {pair}") + assert [(c, s) for c, s, _ in pair] == [ + (KEY_A, PRESSED), + (KEY_A, RELEASED), + ], f"`type A` delivered {pair}; it must be one press and one release" + assert [sym for _, _, sym in pair] == ["A", "A"], ( + f"the client decoded {pair}, not `A`. A `sym=a` here means the " + "mask did not arrive before the key; a `sym=?` means no keymap " + "was ever uploaded and the character assertions are vacuous." + ) + assert not any(code == KEY_LEFTSHIFT for code, _, _ in pair), ( + f"a Shift keycode was injected for a capital: {pair}" + ) + + span = masks(alpha)[before_masks:] + print(f"the client reports masks: {span}") + # `any`, not `span[0]`, and the ordering is carried by `sym=A` + # instead. The focus change from the acquire sends its own + # `modifiers depressed=0`, which can land in this span or the + # previous one depending on when the log was polled -- so a + # positional assertion here would flake for a reason that has + # nothing to do with the capital. + # + # `sym=A` above is the stronger ordering proof anyway: the + # client decodes through its own xkb state, so it can only + # report `A` if Shift was in the mask it had been given WHEN + # the key arrived. A mask sent after the key decodes as `a`. + assert any(m != 0 for m in span), ( + f"no non-zero modifier mask arrived for `A`: {span}. Without " + "it a client that decodes from wl_keyboard.modifiers gets `a`." + ) + assert span[-1] == 0, ( + f"the mask was not cleared after the capital: {span}. A " + "virtual key-up clears no modifier state, so a mask left set " + "makes every later letter a capital." + ) + except Exception: + dump("a capital did not arrive as a capital", alpha) + raise + + with subtest("`hello` arrives on the holder and nowhere else"): + # Positive and negative in one subtest, because they need the same + # moment: a string delivered to alpha is only evidence if beta, + # which held focus until the acquire, was told nothing. + try: + hold(alpha) + before = len(keys(alpha)) + before_beta = len(keys(beta)) + machine.succeed(cli(f"keyboard type {alpha} hello"), timeout=120) + + wait_for( + lambda: len(typed(alpha, before)) >= 5 or keys(beta)[before_beta:], + timeout=60, + what=f"either {alpha} or {beta} to report the string", + ) + mine = typed(alpha, before) + theirs = keys(beta)[before_beta:] + print(f"the holder {alpha} decoded: {mine}") + print(f"the other {beta} reports: {theirs}") + assert not theirs, ( + f"the string was typed into the lease holder {alpha} and " + f"{beta} received {theirs}. One seat, one focus: this is the " + "failure the lease exists to prevent." + ) + assert mine == ["h", "e", "l", "l", "o"], ( + f"the holder decoded {mine}, not h,e,l,l,o. `?` symbols mean " + "no keymap was uploaded -- keycodes without decoded symbols " + "are a failure, not a pass (PLAN §14)." + ) + assert all(sym != "?" for _, _, sym in keys(alpha)[before:]), ( + "a key arrived with no decodable symbol" + ) + except Exception: + dump("the string did not arrive on the holder alone", alpha) + raise + + with subtest("`Return` is a key with no character, and arrives as one"): + # `keyboard key`, the verb `type` cannot express: Return, Tab, + # BackSpace and the arrows have no character to put in a string. + try: + hold(alpha) + before = len(keys(alpha)) + machine.succeed(cli(f"keyboard key {alpha} Return"), timeout=120) + pair = wait_for( + lambda: ( + keys(alpha)[before:] if len(keys(alpha)) >= before + 2 else None + ), + timeout=60, + what="the client to report Return pressed and released", + ) + print(f"the client reports: {pair}") + assert [sym for _, _, sym in pair] == ["Return", "Return"], pair + assert [s for _, s, _ in pair] == [PRESSED, RELEASED], ( + f"a tap must be exactly one press and one release: {pair}" + ) + except Exception: + dump("Return did not arrive", alpha) + raise + + with subtest("this layout's own keycodes, which is how `de` differs"): + # `type y` resolves keysym `y` against the uploaded layout and + # sends THAT layout's code for it. The client decodes the same code + # with the same keymap, so the sym is `y` on both layouts -- see + # the block at the top of this file -- and the CODE is what differs: + # 21 on us, 44 on de. They swap. + try: + hold(alpha) + for character, want_code in (("y", Y_CODE), ("z", Z_CODE)): + hold(alpha) + before = len(keys(alpha)) + machine.succeed(cli(f"keyboard type {alpha} {character}"), timeout=120) + pair = wait_for( + lambda: ( + keys(alpha)[before:] + if len(keys(alpha)) >= before + 2 + else None + ), + timeout=60, + what=f"the client to report `{character}`", + ) + print(f"`type {character}` on {LAYOUT} -> {pair}") + assert [sym for _, _, sym in pair] == [character, character], ( + f"the client decoded {pair}, not `{character}`" + ) + assert all(code == want_code for code, _, _ in pair), ( + f"`{character}` on {LAYOUT} arrived as code " + f"{pair[0][0]}, not {want_code}. us and de swap y and z, " + "so the wrong code here means the wrong layout was " + "uploaded even though the symbol decoded correctly." + ) + except Exception: + dump("this layout's keycodes are not what it should produce", alpha) + raise + + with subtest("a character this layout cannot produce is exit 2, and types nothing"): + # The behavioural difference between the two layouts that no + # decoding confusion can fake: `ü` is an ordinary key on `de` and + # has no keysym at all on a plain `us` map. + try: + hold(alpha) + before = len(keys(alpha)) + # Both branches assert on the broker's own fields rather than + # on prose, and both pin something a VM can get wrong + # independently of the layout: that the non-ASCII argument + # survived argv decoding as ONE scalar. `chars == 4` on the + # typeable path, and `scalar 3 (U+00FC)` on the other, are + # both false if it arrived as two surrogates. + if DIAERESIS_TYPEABLE: + reply = cli_json(f"keyboard type --json {alpha} 'cafü'") + print(f"`type cafü` on {LAYOUT}: {reply}") + assert reply["chars"] == 4, ( + f"the broker counted {reply['chars']} scalars in " + "`cafü`, not 4; the argument did not survive as UTF-8" + ) + symbols = wait_for( + lambda: ( + typed(alpha, before) + if len(typed(alpha, before)) >= 4 + else None + ), + timeout=60, + what="the client to report c,a,f,udiaeresis", + ) + print(f"the client decoded: {symbols}") + assert symbols == ["c", "a", "f", "udiaeresis"], symbols + else: + code, out = machine.execute( + cli(f"keyboard type --json {alpha} 'cafü'") + " 2>&1", + timeout=120, + ) + print(f"`type cafü` on {LAYOUT}: exit {code}: {out}") + assert code == 2, ( + f"an unmappable character exited {code}, not 2. Exit 10 " + "would be reporting the caller's typo as a compositor " + "failure -- see the verification doc's change 1." + ) + assert "ü" not in out, ( + f"the refusal quotes the character it refused: {out!r}. A " + "typed string is a password as often as not and this " + "reaches a log." + ) + assert "caf" not in out, ( + f"the refusal quotes the string it refused: {out!r}" + ) + # The index AND the codepoint: `scalar 3` alone would be + # printed for a mangled argument too, and `U+00FC` is what + # says the broker saw the character the operator typed. + assert "scalar 3" in out and "U+00FC" in out, ( + f"the refusal does not name scalar 3 (U+00FC): {out!r}" + ) + # And no prefix: `c`, `a` and `f` must not have been typed. + machine.sleep(3) + after = keys(alpha)[before:] + print(f"the client reports after the refusal: {after}") + assert after == [], ( + f"a refused string typed a prefix: {after}. Validation is " + "complete before the first event, so there is nothing to " + "clean up -- or there should be." + ) + except Exception: + dump("the unmappable-character path is wrong for this layout", alpha) + raise + + with subtest("a chord holds a modifier across a type and leaves it held"): + # The justified use of `down`: `Control_L` held, a character typed + # with its mask ORed in, and Control still down afterwards. The + # client sees the mask, which is the only thing a chord is. + try: + hold(alpha) + before_masks = len(masks(alpha)) + machine.succeed(cli(f"keyboard down {alpha} Control_L"), timeout=120) + held = cli_json("pointer state --json") + print(json.dumps(held, indent=2, sort_keys=True)) + assert held["keys"] == ["Control_L"], held + + control = wait_for( + lambda: [m for m in masks(alpha)[before_masks:] if m != 0], + timeout=60, + what="the client to be told Control is depressed", + ) + print(f"the client reports a depressed mask of {control}") + + before = len(keys(alpha)) + machine.succeed(cli(f"keyboard type {alpha} c"), timeout=120) + pair = wait_for( + lambda: ( + keys(alpha)[before:] if len(keys(alpha)) >= before + 2 else None + ), + timeout=60, + what="the client to report `c` under Control", + ) + print(f"Ctrl+c delivered: {pair}") + # Control is STILL held: a chord spans three CLI invocations, + # and a `type` that lifted it would make that impossible. + still = cli_json("pointer state --json") + assert still["keys"] == ["Control_L"], ( + f"`type` under a held modifier lifted it: {still}" + ) + machine.succeed(cli(f"keyboard up {alpha} Control_L"), timeout=120) + assert cli_json("pointer state --json")["keys"] == [] + except Exception: + dump("a chord did not hold across the type", alpha) + raise + + with subtest("a second acquire during a hold is refused with BUSY"): + # Held deliberately across the refusal: a contended acquire must + # not disturb a chord somebody is in the middle of. + try: + hold(alpha) + machine.succeed(cli(f"keyboard down {alpha} Shift_L"), timeout=120) + assert cli_json("pointer state --json")["keys"] == ["Shift_L"] + + code, out = machine.execute( + cli(f"pointer acquire {beta}") + " 2>&1", timeout=120 + ) + print(f"exit {code}: {out}") + assert code == 8, f"a contended acquire exited {code}, not 8 (BUSY)" + assert alpha in out, f"the refusal does not name the holder: {out!r}" + state = cli_json("pointer state --json") + assert state["holder"] == alpha, state + assert state["keys"] == ["Shift_L"], ( + f"the refused acquire disturbed the holder's chord: {state}" + ) + machine.succeed(cli(f"keyboard up {alpha} Shift_L"), timeout=120) + except Exception: + dump("a contended acquire was not refused cleanly", alpha) + raise + + with subtest("typing without the lease is exit 9, and reaches no client"): + try: + before = len(keys(alpha)) + before_beta = len(keys(beta)) + code, out = machine.execute( + cli(f"keyboard type {beta} nope") + " 2>&1", timeout=120 + ) + print(f"exit {code}: {out}") + assert code == 9, ( + f"typing with no lease exited {code}, not 9. 9 says `acquire " + "one`, 8 says `wait for someone`, and conflating them is how " + "a retry loop spins." + ) + machine.sleep(3) + assert keys(beta)[before_beta:] == [], "a refused type still typed" + assert keys(alpha)[before:] == [], "a refused type went to the holder" + except Exception: + dump("a type without a lease was not refused", beta) + raise + + with subtest("an expired lease lifts the key it left down, and clears the mask"): + # Real time, a caller-supplied TTL, nothing touching the lease. The + # sweeper is what makes the TTL a promise: without it expiry would + # only be noticed by the next verb, so an agent that held Shift and + # died would hold the keyboard -- with Shift down -- until somebody + # else happened to try. + # + # `Shift_L` on purpose, and code 42 is why: `type` must never emit + # a Shift keycode, so a `state=0` for 42 cannot be a leftover from + # any earlier subtest. A `state=0` for code 30 could be. + try: + short = 8 + state = cli_json("pointer state --json") + if state["holder"] is not None: + machine.succeed( + cli(f"pointer release {state['holder']}"), timeout=120 + ) + cli_json(f"pointer acquire --json --ttl {short}s {alpha}", timeout=120) + before = len(keys(alpha)) + before_masks = len(masks(alpha)) + machine.succeed(cli(f"keyboard down {alpha} Shift_L"), timeout=120) + + held = cli_json("pointer state --json") + print(json.dumps(held, indent=2, sort_keys=True)) + assert held["keys"] == ["Shift_L"], held + wait_for( + lambda: [ + k for k in keys(alpha)[before:] if k[0] == KEY_LEFTSHIFT + ], + timeout=60, + what="the client to be told Shift went down", + ) + + # One bounded wait for the deadline to arrive, not a retry of + # the assertion: the lease expires on its own or it does not. + machine.wait_until_succeeds( + cli("pointer state --json") + " | jq -e '.holder == null' >/dev/null", + timeout=short * 6 + 120, + ) + state = cli_json("pointer state --json") + print(json.dumps(state, indent=2, sort_keys=True)) + assert state["keys"] == [], ( + f"the lease expired with a key still down: {state}" + ) + assert state["buttons"] == [], state + + shift = wait_for( + lambda: ( + [k for k in keys(alpha)[before:] if k[0] == KEY_LEFTSHIFT] + if len( + [k for k in keys(alpha)[before:] if k[0] == KEY_LEFTSHIFT] + ) + >= 2 + else None + ), + timeout=60, + what="the client to be told Shift came back up", + ) + print(f"the client reports for code {KEY_LEFTSHIFT}: {shift}") + assert [s for _, s, _ in shift] == [PRESSED, RELEASED], ( + f"the application was told Shift went down and never that it " + f"came up: {shift}. On this compositor that is worse than a " + "stuck key: InputManager::onKeyboardKey drops the NEXT press " + "of a code it still believes is down, so the key is dead." + ) + span = masks(alpha)[before_masks:] + print(f"the client reports masks: {span}") + assert span and span[-1] == 0, ( + f"the mask was not cleared when the lease expired: {span}. " + "`release_pressed_on_close` would not have done it either -- " + "it emits key-ups and never a `modifiers` -- which is why " + "release_all sends modifiers(0, 0, 0, 0) itself." + ) + except Exception: + dump("the lease did not expire cleanly", alpha) + raise + + with subtest("release lifts a held key and says which"): + try: + hold(alpha) + machine.succeed(cli(f"keyboard down {alpha} Control_L"), timeout=120) + released = cli_json(f"pointer release --json {alpha}", timeout=120) + print(json.dumps(released, indent=2, sort_keys=True)) + assert released["keys_lifted"] == ["Control_L"], released + assert released["buttons_lifted"] == [], released + state = cli_json("pointer state --json") + assert state["holder"] is None and state["keys"] == [], state + except Exception: + dump("release did not lift the held key", alpha) + raise + + with subtest("the audit log counted the characters and kept none of them"): + # The CLI's own argv is visible to `ps` and that is out of scope; + # `events.jsonl` is what this project controls, and a typed string + # is a password as often as not. + try: + secret = "hunter2" + hold(alpha) + machine.succeed(cli(f"keyboard type {alpha} {secret}"), timeout=120) + machine.succeed(cli(f"pointer release {alpha}"), timeout=120) + + events_json = machine.succeed( + "cat /var/lib/hhstream/events.jsonl", timeout=120 + ) + typed_events = [ + json.loads(line) + for line in events_json.splitlines() + if '"keyboard_type"' in line + ] + print(json.dumps(typed_events[-3:], indent=2, sort_keys=True)) + assert typed_events, "no keyboard_type event was recorded at all" + assert any(e.get("chars") == len(secret) for e in typed_events), ( + f"no event recorded a character count of {len(secret)}: " + f"{typed_events[-3:]}" + ) + assert secret not in events_json, ( + "the audit log contains the typed string. It records a count " + "and never the text, deliberately." + ) + except Exception: + dump("the audit log is not what it should be", alpha) + raise + ''; + } +) diff --git a/checks/vm-pointer.nix b/checks/vm-pointer.nix index 4848aca..10712d6 100644 --- a/checks/vm-pointer.nix +++ b/checks/vm-pointer.nix @@ -47,8 +47,20 @@ # # 2. `input:follow_mouse = 0` SENDS POINTER EVENTS TO THE FOCUSED WINDOW ONLY, # and when the window under the cursor is not the focused one, to nobody at -# all. `nix/hyprland-conf.nix` ships it, justified by "No pointer will ever -# exist; do not let focus depend on one" -- a belief this build makes false. +# all. `nix/hyprland-conf.nix` USED TO ship it, justified by "No pointer +# will ever exist; do not let focus depend on one" -- a belief this build +# made false. **That is fixed: the conf file now sets `1`**, so the +# `extraConfig` override below is belt and braces rather than the only +# thing making this check pass. The measurement is kept because it is the +# reason the conf changed, and because a revert would make it current again. +# +# What `1` does NOT fix, measured later by `tests/keyboard_probe.py`: one +# warp moves the cursor and not KEYBOARD focus, because Hyprland zeroes +# `m_mousePosDelta` when the previous movement was over 0.5s ago. So +# `pointer acquire` sends two warps a real pixel apart, and the conf sets +# `input:follow_mouse_threshold = 0` explicitly because that is what the +# second one depends on. `checks/vm-keyboard.nix` is where that is asserted; +# this check asserts pointer delivery and says nothing about keys. # # MEASURED, against the shipped config, with two sessions and the second # one holding focus because its window opened last: @@ -68,6 +80,16 @@ # overrides the one line through the module's `extraConfig`, and the # subtest "the cursor reaches a session that does not hold focus" is the # assertion that goes red if the shipped default comes back. +# +# That subtest now has to ARRANGE its own situation rather than inherit it. +# It used to be free -- the second session's window took focus when it +# opened and `acquire` left it there -- but `pointer acquire` now takes the +# keyboard as well as the cursor, so the acquiring session ends up focused. +# The subtest moves focus back with one `hyprctl dispatch`, as setup. Worth +# knowing because the two bugs hid each other: the helper derivation that +# this check's victim comes from was not building at all (see +# checks/lib/session-tools.nix), so nothing ran here to notice the premise +# had gone stale. # `nix/hyprland-conf.nix` is not this slice's file; the fix belongs there, # and whether it should be `1` (Hyprland's own default, keyboard focus # follows the cursor too) or a looser setting that leaves keyboard focus @@ -425,9 +447,9 @@ testers.runNixOSTest ( raise with subtest("the cursor reaches a session that does not hold focus"): - # Two assertions in one, because they need the same situation: a - # second session exists and its window took focus when it opened - # (the BUSY subtest above started it). + # Two assertions in one, because they need the same situation: the + # lease is held by one session while a DIFFERENT session's window + # holds keyboard focus. # # 1. `acquire` restores the bookmark the previous lease left -- # the point of a bookmark is that a gesture is resumable, and @@ -438,6 +460,21 @@ testers.runNixOSTest ( # are worth nothing if a click aimed at one session arrives at # another, and `input:follow_mouse` is where that would go # wrong (see the block at the top of this file). + # + # HOW THE SITUATION IS SET UP, AND WHY IT CHANGED. It used to be + # free: the second session's window took focus when it opened, and + # `acquire` left it there, because one warp moves the cursor and + # not keyboard focus. `pointer acquire` now takes the keyboard too + # -- two warps a real pixel apart, see `_warp_taking_focus` -- so + # after the acquire below the focused window is the acquiring + # session's, and this subtest's premise no longer arranges itself. + # + # So focus is moved back explicitly. `hyprctl dispatch` is SETUP + # here and not the thing under test: what is measured is which + # client the compositor hands the warp to, and that is unaffected + # by how focus came to be where it is. (The keyboard check is where + # "acquire takes focus" is asserted; asserting it here as well + # would make this subtest about the acquire and not about routing.) try: before = len(positions(session_id)) reply = cli_json(f"pointer acquire --json {session_id}", timeout=120) @@ -446,6 +483,16 @@ testers.runNixOSTest ( f"acquire restored to {reply['bookmark']}, not where the " "previous lease left the cursor" ) + + other_window = [ + c for c in compositor("clients") + if c.get("initialClass") == f"hh-{other}" + ] + assert other_window, f"the other session {other} has no window" + address = other_window[0]["address"] + machine.succeed( + f"{HYPRCTL} dispatch focuswindow address:{address}", timeout=120 + ) focused = [ c.get("initialClass") for c in compositor("clients") @@ -453,7 +500,9 @@ testers.runNixOSTest ( ] print(f"the compositor's focused window belongs to: {focused}") assert focused and focused[0] != output, ( - f"this subtest needs the OTHER session focused; {focused} is" + f"this subtest needs the OTHER session focused; {focused} is. " + "The `dispatch focuswindow` above was supposed to arrange " + "that and did not." ) # Somewhere the cursor is not, so there is a motion to deliver diff --git a/docs/CONTRACT-sessions.md b/docs/CONTRACT-sessions.md index e470260..455ff0c 100644 --- a/docs/CONTRACT-sessions.md +++ b/docs/CONTRACT-sessions.md @@ -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` | diff --git a/docs/plans/2026-10-03-keyboard-input.md b/docs/plans/2026-10-03-keyboard-input.md new file mode 100644 index 0000000..7baab59 --- /dev/null +++ b/docs/plans/2026-10-03-keyboard-input.md @@ -0,0 +1,341 @@ +# Keyboard input for sessions + +> **Superseded in eight places. Read this first.** +> +> `docs/plans/2026-10-04-keyboard-verification.md` is an adversarial review of +> this file against the tree and against Hyprland v0.56.2. Its verdict is "safe +> to build on, not safe to implement as written", and the eight rows of its +> **"Changes required before code"** table **override this document wherever +> they differ**. Each one is also folded into the text below, marked +> `[SUPERSEDED]`, so nobody following a single paragraph gets the contradicted +> version: +> +> | # | What changed | +> | --- | --- | +> | 1 | Exit 2 vs `driver_refused` — §2's exit-code paragraph was wrong about what `_drive` does | +> | 2 | The keymap `size` includes the trailing NUL; `format = 1`; `time` is `_now_ms()` | +> | 3 | `release_all` no-ops its key half with no keyboard, and ends with `modifiers(0,0,0,0)` | +> | 4 | `input:virtualkeyboard:release_pressed_on_close = true` — destroy-while-held is no longer an open question | +> | 5 | The layout reaches the keymap **only** as `--xkb-layout` on the driver unit; no `[keyboard]` TOML table | +> | 6 | The modifier-keysym set is measured from the keymap; no Shift special case | +> | 7 | Stage 0's expectations, and `keyboard down` warns unconditionally | +> | 8 | Acquire's stderr mentions keyboard verbs; refusals carry a scalar index, never the string | +> +> **Stage 0 has run** (`tests/README-keyboard-probe.md`, with its transcript), +> and Stages 1–3 are built. The three open behavioural questions are answered, +> and one answer was worse than this document assumed: **a single idle warp +> does not move keyboard focus.** That is resolved rather than outstanding — +> `pointer acquire` now sends **two** warps a real pixel apart, and +> `nix/hyprland-conf.nix` pins the `follow_mouse_threshold` the second one +> depends on. See §6 risk 1, which is rewritten, and the Stage 3/4 rows, which +> are not pending work. +> +> **Where this file and `docs/CONTRACT-sessions.md` v3 disagree, the contract +> wins.** It describes what shipped; several paragraphs here describe what was +> planned before Stage 0 measured the compositor. + +Typing stops being a non-goal. `docs/PLAN-workspaces-and-pointer.md` §1 defers it, and §6.7 already specifies the shape: same seat, same serialisation, `zwp_virtual_keyboard_manager_v1`, and the existing pointer lease rather than a new lock. Stages 0–3 of that plan are what the tree implements today (broker lease in `src/hhstreamd/pointer.py`, driver in `src/hhstream_pointer/`, CLI in `src/hhstream_session/__init__.py`). This plan is §6.7, with one correction noted under lease semantics. + +The Chrome path in `examples/agent-eyes-demo.py` (`Input.insertText`) is not this feature. It never touches the seat. This plan is for whatever window is focused on the compositor's one seat. + +--- + +## 1. Protocol + +**Decision: `zwp_virtual_keyboard_v1`, spoken by the existing `hhstream-pointer` process. Not `wp_virtual_keyboard_v1`, not uinput/`ydotool`, not `wtype`.** + +| Option | Verdict | +| --- | --- | +| `zwp_virtual_keyboard_v1` | Use it. Unstable wayland-protocols interface (`virtual-keyboard-unstable-v1.xml`). Manager global `zwp_virtual_keyboard_manager_v1`. Requests are `keymap(format, fd, size)`, `key(time, keycode, state)`, `modifiers(depressed, latched, locked, group)`. Version 1 only. | +| `wp_virtual_keyboard_v1` | Do not bind it. Nothing in this repo claims that global. A stable `wp_` rename is not what §6.7 measured. | +| uinput / `ydotool` | Reject. Needs `/dev/uinput` and a seat that actually reads that device. The headless compositor is driven as a Wayland client today (`WaylandSink` in `src/hhstream_pointer/backend.py`); the driver runs as `hermes` with group `hhstream` so it can open the Wayland socket (`nix/module.nix`). A kernel device is a second privilege and a second focus story, and it cannot be unit-tested as a recording sink. | +| `wtype` | Reject as the mechanism. It is a short-lived client of the same `zwp_` protocol: new virtual keyboard per invocation, its own keymap, no `release_all` across calls, no lease. Useful only as a reference for how text becomes keycodes. | + +**What the running compositor exposes.** Not re-checked in this session (no registry dump). The only evidence in-tree is §6.7's **[RAN]** claim, against the Hyprland it measured (plan header: tag `v0.56.2`): `zwp_virtual_keyboard_manager_v1` is a live global. `wp_virtual_keyboard_v1` is not mentioned. Treat that as unverified until Stage 0 dumps the globals on `/run/hypr-stream`. If the dump shows a different name, stop. Do not probe uinput as a fallback. + +**Tradeoffs, as they apply here:** + +- **Keycode, not keysym, on the wire to the compositor.** `key` takes a Linux evdev code (the same value `wl_keyboard.key` carries; clients add 8 to reach an XKB keycode). Keysym names stay on our socket, the way button names stay on ours and evdev codes cross into `zwlr_virtual_pointer_v1` (`src/hhstream_pointer/buttons.py`). +- **Keymap upload is mandatory.** Until `keymap` is sent (format `xkb_v1`, memfd of an XKB text keymap), clients cannot decode a key to a character. Upload **once**, after connect and before `listen`, matching `__main__.py`'s rule that a listening socket is a promise the device works. Do not upload again per string: a second `keymap` resets client state under held keys. + + **[SUPERSEDED — change 2.]** Three values this bullet left unstated, each of which fails silently: + - the `size` argument **includes the trailing NUL**. Hyprland `mmap`s exactly `size` bytes and hands the pointer to `xkb_keymap_new_from_string`, which wants a C string, so `size = len(text)` reads off the end of the mapping. The symptom is a keymap that will not compile, which from our side is indistinguishable from a compositor with no keyboard at all; + - the fd must outlive a **round trip**, not a flush: the compositor has to have received and mapped it before we close our end; + - `format` is the integer **1** (`XKB_KEYMAP_FORMAT_TEXT_V1`). Hyprland ignores it and parses as `TEXT_V2`, which accepts a V1 string; do not send 2; + - `time` on every `key` is `backend._now_ms()`, the same monotonic source the pointer requests use. The protocol requires one clock per object. + + Also, a *second* upload is worse than "resets client state": Hyprland replaces its XKB state without walking the keys it believes are down, so re-uploading under a held modifier strands it. +- **No unicode request.** A codepoint is typeable only when the uploaded layout has a keysym for it. No `Ctrl+Shift+u`, no per-string custom keymap, no compose sequences in v1. +- **Modifiers are a separate request.** The compositor does not derive the modifier mask from `key`. Shifted text needs `modifiers` as well as the letter key. Details in §4. +- **No per-output target.** Unlike `create_virtual_pointer_with_output` (`backend.py`), a virtual keyboard is seat-global. Keys hit whichever surface has keyboard focus. There is no output argument to add. + +**Missing global is not fatal to the cursor.** `ManagerTooOld` aborts process start because a version-1 pointer aims at the wrong output (`backend.py`). A missing keyboard global must not do that. Pointer ops keep working. Keyboard ops return `{"ok": false, "error": ...}` and the broker surfaces that as exit **10 COMPOSITOR**. No silent no-op. + +--- + +## 2. Surface + +**Decision: new CLI group `session keyboard`, new broker verbs `keyboard.*`, new ops on the existing broker↔driver socket. No new process, unit, binary, or socket.** + +`CONTRACT-sessions.md` §5 freezes the binary `hhstream-pointer` and the socket `/run/hhstream/pointer.sock`. Renaming the package to "input" is churn with no behavioural gain. `server.py` already frames newline-delimited JSON at `MAX_LINE_BYTES` (1 MiB) and is unchanged. + +### CLI + +`pointer acquire` remains the only acquire. Keyboard verbs are gestures on that lease. They reuse `_lease_of`, `--lease`, and `$HHSTREAM_LEASE` (`src/hhstream_session/lease.py`). There is no `keyboard acquire` and no second cache file. + +``` +hhstream session pointer acquire ID # unchanged; also authorises typing +hhstream session pointer release ID # lifts buttons and keys +hhstream session pointer state # JSON gains "keys" + +hhstream session keyboard type ID TEXT # one argument, raw UTF-8, no backslash escapes +hhstream session keyboard key ID NAME # tap: down then up +hhstream session keyboard down ID NAME +hhstream session keyboard up ID NAME +``` + +`NAME` is an XKB keysym name (`a`, `A`, `Return`, `BackSpace`, `Left`, `Control_L`, `Shift_L`), not an evdev number. Help text on both groups must say keyboard commands refuse with exit 9 until `pointer acquire`. `pointer --help` stays about the cursor. + +`type` does not interpret `\n`. A newline is a real newline in the argument. The shell quotes it. The wire value is that string. + +### Broker control socket + +Extend `src/hhstreamd/protocol.py` (do not renumber `ExitCode`). Same codes as pointer: **8 BUSY** only on a second acquire, **9 NO_LEASE** when this session does not hold the lease, **2 USAGE** for a bad keysym or an unmappable character, **10 COMPOSITOR** when the driver has no keyboard global or the connection dies. + +**[SUPERSEDED — change 1.]** "Exit 2 for a bad keysym" and "`Rejected`, same as a bad button" are not the same code, and this paragraph asserted both. `SessionManager._drive` turns *every* driver `ok: false` into `ManagerError("driver_refused")`, which is exit **10** — that is why `test_an_unknown_button_is_refused_by_the_driver_not_invented` asserts `driver_refused` and not usage. Exit 2 happens only for an `invalid_argument` the broker raises *before* `_drive`. So: + +- the **broker** checks shape before it calls the driver: `text` must be a string, `state` must be `down`/`up`, `key` must be a non-empty string, and `text` must be within the 4096-scalar cap. Those are `invalid_argument`, exit 2; +- the **driver** tags a rejection it caused the caller to earn with a stable token, `kind: "invalid_argument"` (`hhstream_pointer.ops.KIND_INVALID`) — a bad keysym, an unmappable character, a dead key, a `type` under a held non-modifier. `_drive` maps that token to `invalid_argument`, exit 2; +- everything else keeps `kind: "refused"` and stays `driver_refused`, exit **10**: no keyboard global, no aimed output, a dead connection. + +The token exists because the alternative is the broker telling "no such keysym on your layout" from "this compositor has no keyboard" by matching on English. + +| Verb | Request beyond `verb`, `request_id` | Response | +| --- | --- | --- | +| `keyboard.key` | `id`, `lease_id`, `key`, `state` (`down`/`up`) | `keys[]` | +| `keyboard.type` | `id`, `lease_id`, `text` | `keys[]` (explicit holds still down; a `type` itself leaves none) | +| `pointer.state` | — | existing fields plus `keys[]` | +| `pointer.release` | unchanged | report lifted keys in the same place buttons are already reported (audit if that is where `buttons_lifted` lives today — do not invent a richer release body than buttons have) | + +`keyboard.key` and `keyboard.type` join the mutation set beside `pointer.click` (`protocol.py`): a replayed `request_id` returns the recorded answer and must not type twice. A new `request_id` types again. + +Neither verb calls `touch`. Same rule as every `pointer.*` verb (`CONTRACT-sessions.md` §4, module docstring of `src/hhstream_session/__init__.py`, `src/hhstreamd/manager.py`). + +Cap `text` at **4096** Unicode scalars in both broker and driver. Over the cap is `invalid_argument`, not a truncated type. + +**Audit:** `keyboard_key` records the keysym name and state. `keyboard_type` records `chars` (an integer) and **not the text**. Typed strings will include passwords; the audit log is the wrong place for them. + +**[SUPERSEDED — change 8.]** `events.jsonl` is not the only place a string leaks, and the plan secured only that one. Two more: + +- **Refusal messages and driver logs carry the scalar *index*, never the character and never the string.** "unmappable at scalar 3" is the whole of what a reader needs, and the alternative ends up in the journal. `AuditLog.emit` will happily write a `text` field if a caller passes one, so the rule is about every message, not only the audit event. +- **`pointer acquire`'s stderr is wrong once this lands.** It says "expires in … with no further **pointer** verb". A `keyboard.*` verb goes through `_refresh` and *does* move `expires_at`, so the sentence has to name both — otherwise an operator releases during a `type` that would have kept the lease, and the TTL test looks flaky against the help text. + +(What the shell and `ps` show of the CLI argument is outside this rule: the text is an argv word by the time anything here sees it.) + +### Driver socket (`CONTRACT-sessions.md` §3.4) + +The driver stays an executor with no lease (`ops.py` docstring, `driver.py` docstring). New ops: + +```json +{"op":"key","key":"Return","state":"down"} -> {"ok":true} +{"op":"key","key":"a","state":"up"} -> {"ok":true} +{"op":"type","text":"Hello"} -> {"ok":true} +{"op":"pressed"} -> {"ok":true,"buttons":["left"],"keys":["Control_L"]} +{"op":"release_all"} -> {"ok":true,"lifted":["left"],"lifted_keys":["Control_L"]} +``` + +There is no keyboard `frame`. `zwp_virtual_keyboard_v1` has none. Do not reuse the pointer's end-of-gesture `frame`; a key flushed only on `frame` would never arrive. `backend.py` already flushes every pointer request; keyboard requests flush the same way. + +`pressed` and `release_all` grow key fields. Do not add a parallel `release_all_keys` op. Expiry has one call site (`SessionManager._expire_pointer`). + +**[SUPERSEDED — change 3.]** Two things follow from there being exactly one call site, and this plan stated neither: + +- `release_all` must **no-op its key half when no virtual keyboard exists**. If the key half raised, the one `release_all` would abandon the buttons it had just been asked to lift — and a lease that expired with a mouse button down is the failure the whole TTL exists to prevent. +- `release_all` ends with `modifiers(0, 0, 0, 0)` **whenever a mask was set**, because a virtual key-up clears no modifier state on this compositor. Without it a lease that ended under Shift hands the next holder a keyboard where every letter is a capital. One `modifiers(0, 0, 0, 0)` also goes out immediately after the initial keymap upload, so a previous driver's mask is not inherited. + +Unknown keysym, non-finite or over-long text, and `type` while a non-modifier key is held are `Rejected` (answered, connection kept), same as a bad button. + +### File-by-file + +| File | Change | +| --- | --- | +| `src/hhstream_pointer/_protocol/virtual_keyboard_unstable_v1/` | Vendor pywayland output, same method as `_protocol/regenerate.py` (seed the import map with core `wl_*`, do not use `python -m pywayland.scanner` alone). XML is wayland-protocols `unstable/virtual-keyboard/virtual-keyboard-unstable-v1.xml`, not the wlr pointer XML. | +| `src/hhstream_pointer/_protocol/regenerate.py` | Second XML argument. State the path in the module docstring the way the pointer generator does. | +| `src/hhstream_pointer/keymap.py` | **New.** xkbcommon only here. Builds one keymap from rules (`evdev`, model, layout, variant, options). Resolves a keysym name or a string to a list of actions `(evdev_code, mods_depressed)` or raises. Resolves the **whole** string before returning, so a bad character emits nothing. | +| `src/hhstream_pointer/ops.py` | Extend `Dispatcher`. A small `Keymap` protocol (same idea as `PointerSink`) does the resolving, so this file still imports neither pywayland nor xkbcommon. New ops `key` and `type`. `_pressed` stays buttons. New insertion-ordered `_keys`. `release_all` lifts keys after buttons: key-up each held key in press order, then `modifiers(0, 0, 0, group)`. | +| `src/hhstream_pointer/backend.py` | Still the only pywayland importer. Bind the manager at version 1, `create_virtual_keyboard(seat)` **once** (not per output). `keymap` upload from a memfd. Sink methods `key(code, state)` and `modifiers(dep, latch, lock, group)` only — no names, no UTF-8. | +| `src/hhstream_pointer/__main__.py` | Flags below. Build the keymap and upload it before `listen`. `_lift_everything` already calls `release_all`; once that op lifts keys, shutdown covers them. Update the comment that today only mentions buttons. | +| `src/hhstream_pointer/server.py` | No change. | +| `src/hhstreamd/driver.py` | `key()`, `type_text()` on `PointerDriver`. `release_all` / `pressed` read the new fields. Same socket, same "do not retry a request that was written" rule. A failed `release_all` is still `DriverUnavailable`: a dropped lift leaves a key down. | +| `src/hhstreamd/pointer.py` | Not a new class. On `_Held`, a `keys` dict beside `buttons`. `press_key` / `unpress_key` / `keys_pressed`, mirroring `press` / `unpress` / `pressed`. `expire()` still returns `LeaseInfo` only — no keys. Callers read `keys_pressed()` first, as they must read `pressed()` first (`CONTRACT-sessions.md` §3.3). | +| `src/hhstreamd/manager.py` | `keyboard_key` and `keyboard_type` go through `_refresh` (live session, holder, not expired, container output required). Driver first, then the lease mirror — the `pointer_button` order, so a refused key is not recorded as down. `_expire_pointer` reads keys before `expire()` and uses the one `release_all`. Same on `pointer_release`, kill, reap, and driver loss. | +| `src/hhstreamd/protocol.py` | Verb allowlist plus the mutation set. | +| `src/hhstreamd/policy.py` | **[SUPERSEDED — change 5.] No change.** A `[keyboard]` table here would be read by nothing: `settings_from_dict` is read by `hhstreamd`, and the driver is a *different unit* that never opens that file. An operator could change the layout and every injected key would stay on `us`. The layout travels as `--xkb-layout` on the driver's argv, and nowhere else. | +| `src/hhstream_session/__init__.py` | `_build_keyboard` beside `_build_pointer`. | +| `src/hhstream_session/format.py` | `render_pointer_state` shows held keys. | +| `src/hhstream_session/lease.py` | No new store. `pointer-leases.json` remains the cache. | +| `nix/module.nix` | No new unit. Extend `hhstream-pointer.service` argv — **and nothing else**: **[SUPERSEDED — change 5]** the `[keyboard]` TOML emission is dropped, see `policy.py` above. Options under `sessions.keyboard`: `layout` (`lib.types.strMatching "[A-Za-z0-9_-]+"`, default `"us"` — the type is what refuses a comma-separated list), `variant` (default `""`), `options` (default `""`), `model` (default `"pc105"`). The driver also refuses a comma itself, before `xkb_keymap_new_from_names`, because the NixOS type cannot reach a binary run by hand. §3.4's "command line the module will pass, exactly" and the unit comment quoting it are amended in the same change. | +| `nix/package.nix`, `flake.nix` devshell, `pyproject.toml` | `xkbcommon` for the driver and for unit tests. No new console script. | +| `nix/hyprland-conf.nix` | Keep `input:follow_mouse = 1`. Extend the comment: keyboard events have no output, so the warp is what moves keyboard focus — but see §6 risk 1 and Stage 0, because **one** warp does not — and the lease is what stops another session stealing it mid-string. **[SUPERSEDED — change 4]** Also set `input:virtualkeyboard:release_pressed_on_close = true`, with the note that it releases keys and still does not clear the modifier mask. | +| `docs/CONTRACT-sessions.md` | Amend §3.3 (key mirror, `expire()` still carries no keys), §3.4 (ops above), §4 (verbs, idle rule). | +| `README.dev.md` item 3, `checks/vm-pointer.nix` header | Stale relative to the conf file as read: they still say `hyprland-conf.nix` ships `follow_mouse = 0` and that the keyboard task will choose. The conf file sets `1`. Fix the prose when implementing; do not set the conf back to `0`. | + +Flags the unit passes, defaults matching §5's style of frozen defaults: + +``` +hhstream-pointer --socket /run/hhstream/pointer.sock \ + --compositor-runtime-dir /run/hypr-stream \ + --xkb-layout us --xkb-model pc105 \ + --xkb-variant '' --xkb-options '' +``` + +A layout xkbcommon rejects, before any Wayland connect, exits **2**. Compositor failures stay **10**. + +--- + +## 3. Lease + +**Decision: one lease. Keyboard verbs require the pointer lease. Do not add a keyboard lease, a `keyboard` boolean, or a second sweeper.** + +§6.7 says the lease "gains a `keyboard` flag" and that no new mechanism is needed. The flag is the wrong reading of the code that shipped. `_Held.buttons` exists because `release_all` must know **which** buttons went down and in what order (`src/hhstreamd/pointer.py`, `ops.py`). A boolean cannot lift `Control_L` and not `a`. The key set is that pattern, not a new state machine. + +Why sharing is required by the seat, not just by the plan: there is one `wl_seat` and one keyboard focus. `follow_mouse = 1` (`nix/hyprland-conf.nix`) means another session's warp retargets the keys. Two leases would let session B move the pointer while session A believes it is typing into its own window. `LeaseBusy` on acquire is already the mutex (`PointerLease.acquire` refuses even the current holder a second id, so a drag — or a half-typed chord — cannot have its id silently replaced). + +Rules that keyboard inherits unchanged: + +- Acquire / refresh / hard cap (`ttl` 30 s, `max` 300 s, refresh moves only the idle deadline). +- `expire()` does not lift anything. The broker reads the mirror, drops the lease, then `release_all` on the driver (`_expire_pointer`). +- Driver death force-releases (`driver_gone`). The driver is not asked to remember who held the lease. +- Kill and reap of the holder drop the lease with the existing reasons (`kill` / `crash`). +- CLI cache is re-checked by the broker; a stale id is exit 9 and then forgotten. +- Gesture verbs do not mark activity. + +**TTL expiry with keys held down.** Same as buttons (`PLAN` §6.2 "Never leave a button down", implemented in `_expire_pointer` and in `_lift_everything`): + +1. Sweeper (or the next verb's `_refresh`) sees the deadline. +2. Broker reads `keys_pressed()` and `pressed()` **before** `expire()`. +3. `expire()` drops the lease. It is not kept open to finish the word. +4. Driver `release_all`: button-ups, then key-ups in press order, then `modifiers(0, 0, 0, group)`, then the pointer `frame`s it already sends for buttons. No keyboard frame. +5. Audit `pointer_lease_timeout` gains `keys_lifted`. The session's pointer bookmark is stamped `released_by: timeout` as today. +6. The next `acquire` is free. Nothing is replayed. A held Shift does not leak into the next holder. + +If `release_all` fails, do what the button path does: log it, still drop the lease, do not retry a request whose outcome is unknown (`driver.py`). The stuck-key case is a risk in §6, not a second expiry protocol. + +`type` refreshes **once per broker verb**, inside `_refresh`, not once per character. Explicit `down` of a modifier stays in the lease mirror across later `type` calls. `type` itself must not leave letters down. + +A warp while a key is held stays legal, same as a drag. Focus can follow that warp. That is another reason both devices share the lease: the holder is the only session allowed to move focus until release or TTL. + +--- + +## 4. Keymap and text + +**Decision: one seat-wide XKB layout, chosen in config, default `us` / `pc105` / empty variant / empty options. The virtual keyboard's keymap is the one we upload. Hyprland's `input:kb_layout` is not read and does not affect injected keys.** + +Do not query `hyprctl getoption` to fill a default. The broker's rule is that unverified fields stay null (`PLAN` §7); a layout guessed from the compositor would drift on reload. Operators who are not on `us` set `sessions.keyboard.layout`. + +**Decision: v1 is a single group.** A comma-separated layout (`us,ru`) is rejected at config load. Group in every `modifiers` request is **0**. No group-switch keysym. + +**Where it lives.** `[keyboard]` in the broker TOML (`policy.py`), rendered by `nix/module.nix`, passed as the flags in §2. The driver compiles it at startup and uploads that byte string. The session record does not gain a layout field. Per-session layouts would mean re-uploading `keymap` on every acquire, which drops held state; not in v1. + +**How text is expressed.** + +- `keyboard type` takes a Python `str` of Unicode scalars. The keymap maps each scalar to one keysym, then to one `(evdev code, modifier mask)`. +- Newline → keysym `Return`. Tab → `Tab`. Other C0 controls are rejected with the rest of the string, not skipped. +- `A` is Shift+`a` via the **mask**, not via a typed Shift key, unless the user also has Shift explicitly held. +- Explicit modifier holds are a baseline. `type` ORs each character's mask with that baseline, sends the letter, and restores the mask to the baseline afterwards. So `down Control_L` then `type c` is Ctrl+C, and Control is still down when `type` returns. +- If any **non-modifier** key is already held, `type` is rejected and emits nothing. +- Validation is complete before the first sink call. Unmappable character → the whole request fails, no prefix typed. This includes `é` on `us`. +- Dead keys (`dead_acute` and the like) are a rejection even if the layout names them. v1 does not emit a two-event compose. `us(intl)` is therefore a poor choice until a later stage; default `us` does not need it. +- No auto-repeat timer in our process. **[SUPERSEDED — change 7, and Stage 0 has measured it.]** Hyprland does not repeat on the wire: a key held 1.5 s produced exactly one `wl_keyboard.key`, and it publishes `repeat_info rate=25 delay=600` so the *client* repeats. That is not good news — a focused text field will insert characters from that one press until the key-up or the TTL — so the `down` help text warns **unconditionally** rather than only if a probe saw repeats, and v1 has no rate to offer because we do not generate them. + +**Modifier decision:** for a shifted character, send `modifiers(shift_mask, 0, 0, 0)` and the letter's `key` down/up, then restore the previous mask. Do **not** also synthesize `Shift_L` down/up for that character. For an explicit `keyboard down Shift_L`, send the Shift **key** and a matching `modifiers` update, and remember both in the held-key record so `release_all` undoes both. Sending both a synthetic Shift key and a mask for an ordinary capital is how toolkits apply Shift twice or not at all; the VM check in §5 is what proves the letter path against a real `wl_keyboard` client. + +Named non-character keysyms used by `key`/`down`/`up` go through the same resolver, not a second table that can disagree with the layout. `buttons.py` can stay a hand-written evdev table because the protocol takes those codes directly; keysyms cannot. + +**[SUPERSEDED — change 6.]** This section never defined "modifier", and a Shift-only reading of it is wrong: `@` on `de` is a **level-three** symbol, so a resolver that only knew about Shift would type the wrong character. The definition is *measured from the keymap*, not listed — press each keycode in a throwaway XKB state and read the serialised masks back: + +- a non-zero **depressed** mask and no locked mask makes it a **modifier**: on `us`/`pc105` that is exactly `Shift_L/R`, `Control_L/R`, `Alt_L/R`, `Super_L/R`, `ISO_Level3_Shift`, `ISO_Level5_Shift`. (`Meta_L/R` and `Hyper_L/R` are canonical modifier keysyms that **no keycode on this layout carries** — which is the argument for measuring rather than listing.) +- a non-zero **locked** mask makes it a **lock**: `Caps_Lock`, `Num_Lock`. A lock is not a modifier, and `type` refuses while one is held rather than producing a case nobody asked for. + +The resolver returns `(evdev code, mask)` for a keysym at *any* level, so one code path serves `us` and `de`. And `key`/`type` never call `_aimed()`: a keyboard has no output, so demanding a prior warp would refuse a caller who only ever wanted to type. + +--- + +## 5. Tests + +Match the split already in the tree: the dispatcher is tested against a recording sink and is not tested for authority (`tests/pointer/test_ops.py`); the lease is pure with `FakeClock` and no sleep (`tests/pointer/conftest.py`); the broker is tested with a real UNIX socket and `FakeDriver`, Wayland substituted (`tests/sessions/unit/test_pointer_verbs.py`). No integration test grows a fake compositor. `tests/sessions/integration/` does not gain Wayland. + +### Unit + +| Test | Asserts | +| --- | --- | +| `tests/pointer/test_keymap.py` | Real xkbcommon, layout `us`: `a` → evdev 30, mask 0; `A` → 30 plus Shift; `Return` and `\n` → `KEY_ENTER`; empty string → `[]`; `é` and a C0 control other than `\n`/`\t` raise; the raise happens with zero sink calls when driven through the dispatcher. Dead keysym raises. | +| `tests/pointer/test_ops.py` | Extend `RecordingSink` with `key(code, state)` and `modifiers(...)`. `key down` then `pressed` lists the name. `up` of a key that was not down reports it not lifted (same as `unpress`). `release_all` lifts keys in press order and ends with a zeroed `modifiers`, even if the last `warp` was to another output (keys are not per output). `type` emits down/up pairs and leaves `keys` empty. `type` with `Control_L` held ORs the mask and leaves Control down. `type` with `a` held emits nothing and returns `ok: false`. A keymap that raises on the third character emits nothing. | +| `tests/pointer/test_lease.py` | `press_key` / `keys_pressed` order. `expire()` still returns no key list; the test reads `keys_pressed()` first, then `expire()`, then sees an empty lease. Existing busy/stale/`lease_id` cases stay as they are. | +| `tests/pointer/test_vendored_protocol.py` | Interface name `zwp_virtual_keyboard_manager_v1` and requests `keymap`, `key`, `modifiers`. No display. | +| `tests/sessions/unit/test_keyboard_verbs.py` | New, harness copied from `test_pointer_verbs.py`. No lease → 9. Other session holds the lease → 9 (not 8). Second `pointer.acquire` while typing → 8. `type` refreshes TTL: advance the `ManualClock` by less than `ttl` after a type and the lease survives; advance past it and `release_all` runs with the held key. Driver rejection does not stick the key in the lease. `type` does not move `last_activity_boottime`. `pointer.release` and kill both lift keys. `pointer.state` includes `keys`. | +| ~~`tests/sessions/unit/test_settings.py`~~ | **[SUPERSEDED — change 5.] Dropped.** A TOML default of `us` that nothing uploads is precisely the false pass that file's own docstring warns about. Replaced by `tests/pointer/test_driver_flags.py`: an omitted `--xkb-layout` is `us`, `de` is `de`, and `us,ru` exits 2 **with an injected sink proving the compositor was never touched**. | +| CLI surface test (`tests/sessions/unit/test_cli_surface.py`) and broker verb list (`test_broker_protocol.py`) | `keyboard` in help; help says the pointer lease is required; `keyboard.type` / `keyboard.key` are known verbs and are in the mutation set. | + +`nix develop -c python -m pytest tests/pointer tests/sessions/unit -q` is the gate. Not run for this plan. + +### Integration / VM + +**Decision: a new `checks/vm-keyboard.nix`, same shape as `checks/vm-pointer.nix`. Do not call the feature done on unit tests alone.** `docs/TODO/scroll-has-no-compositor-proof.md` is the precedent: scroll shipped on the driver socket with no compositor proof. Keyboard's only purpose is that the client receives symbols. + +- Victim: a small Wayland client beside `checks/lib/pointer_target.py` (or an extension of it) that sets `xdg_toplevel` app id from `$HHSTREAM_APP_ID` and prints `wl_keyboard.enter`, each `key` (evdev code, state), each `modifiers` mask, and the keysym it decodes from the keymap the compositor forwarded. Read-back is `hhstream session logs`, as in `vm-pointer`. +- Assertions, real time, no injected clock (the unit clock already covers the arithmetic; `vm-pointer`'s expiry subtest states why): + 1. After `pointer acquire` on session A, A's log shows `wl_keyboard.enter`. This is the focus measurement, and it is asserted against acquire itself: acquire is two warps (§6 risk 1), so this is a live assertion rather than one expected red. `checks/vm-keyboard.nix` also requires the reply's `focus == "warp"`, so the nudge-failure fallback is not accepted as success, and it asserts `wl_pointer.enter` separately — a check that saw only the cursor arrive would pass while the first keystroke went elsewhere. Do not weaken it. + 2. `keyboard type A hello` decodes to the characters `hello` on A and to nothing on session B. + 3. `keyboard down A Shift_L`, wait out a short `--ttl`, A's log shows the key-up and a cleared mask, and `pointer state` shows no holder. + 4. A second acquire during the hold exits 8. +- Mutation, per `PLAN` §14: the character assertion must fail if `keymap` was never uploaded (keycodes without a decoded `hello` are a failure, not a pass). +- `globalTimeout` on the order of `vm-pointer` (1800). This check is slow; that is not a reason to fold it into a unit test. + +--- + +## 6. Risks, open questions, stages + +### Risks + +- **Focus does not follow a single virtual-pointer warp. [MEASURED — Stage 0, and this is the headline risk of the feature.]** One `motion_absolute` onto an unfocused window, after the cursor had been still for 0.8 s, delivered `wl_pointer.enter` and **no** `wl_keyboard.enter`; the focus change arrived only after a *later* motion that changed the floored pixel. The mechanism is `InputManager::onMouseWarp` → `mouseMoveUnified(refocus=false)`: the delta is set to 0 when the previous movement was over 0.5 s ago, `mouseMoveUnified` returns early when the floored pixel did not change at all, and keyboard focus is that delta compared against `input:follow_mouse_threshold` (measured 0.0, unset). Transcript in `tests/README-keyboard-probe.md`. + + **[RESOLVED in Stage 2 — `pointer acquire` is now two warps.]** This paragraph used to end "acquire is one warp, so the first key of a lease can land in whatever was already focused; the fallback is not built in Stages 1–2". Both halves are out of date, and `docs/CONTRACT-sessions.md` v3 §4 is the text that describes what shipped: + + - `pointer_acquire` calls `_warp_taking_focus`, which warps to a neighbouring pixel and *then* to the target. The second motion carries a non-zero `m_mousePosDelta`, so it moves keyboard focus; the cursor finishes on the target, so the bookmark is unchanged. `FOCUS_NUDGE` is 0.004, about 2.88 px at the frozen 1280×720 mode, which is what makes the *floored* pixel differ. + - This depends on `input:follow_mouse_threshold` being 0, so `nix/hyprland-conf.nix` now sets it **explicitly** rather than inheriting the default. Raise it and acquire stops taking the keyboard. + - `dispatch focuswindow` **is** built, and it is not what this risk needed: it runs only when the *nudge* warp could not be sent, and it selects on `address:` from the read-back (falling back to `pid:`), never on `stable_id`, which is not a Hyprland selector. The target warp is still attempted afterwards and its failure still drops the lease. The acquire reply and the audit event carry `focus`: `warp`, `focuswindow`, or `none`. + - Still *not* the fix, and worth keeping written down: warping twice to the same bookmark (the same floored pixel returns early, before the delta is touched) and waiting longer after one warp (the measured settle window was 0.4 s and contained the pointer enter alone). + + Measured end to end by `checks/vm-keyboard.nix` on both layouts: with session B holding keyboard focus, acquire on A delivers `wl_pointer.enter` **and** `wl_keyboard.enter` to A and `wl_keyboard.leave` to B. That subtest requires `focus == "warp"`, so it does not accept the fallback as success. + + What is **not** covered by a test: the `focuswindow` branch itself. A driver that is down fails the target warp too and the acquire aborts, so the branch is the narrow one where the nudge fails and the target warp succeeds. If both mechanisms fail, acquire still returns `ok` with `focus="none"` — a lease whose first key may go to the previously focused window. +- **Destroy of the virtual keyboard leaves a key down inside Hyprland. [MEASURED — Stage 0.]** `destroy` with a key held, with a second virtual keyboard keeping the seat's capability up, delivered no key-up; `input:virtualkeyboard:release_pressed_on_close` is `0` and unset. Worse than "stuck": `InputManager::onKeyboardKey` drops a *press* whose code is already in the seat's `m_pressed`, so the next driver's press of that code is ignored and the key is **dead** until something sends a matching up. Our shutdown path sends key-ups first (`_lift_everything`); a `-9` skips it, which is why **[change 4]** `nix/hyprland-conf.nix` now sets `release_pressed_on_close = true`. That setting emits key-ups only and still never clears the modifier mask, so `release_all` keeps sending `modifiers(0, 0, 0, 0)` regardless. Still no retry loop the button path does not have. +- **Auto-repeat is the client's, which does not make it harmless. [MEASURED — Stage 0.]** `press_count=1` over a 1.5 s hold, with `repeat_info rate=25 delay=600` published at bind time. So the flood is real and it is foot/GTK/Qt producing it from our one press, for as long as the key is down — up to the TTL (default 30 s). **[SUPERSEDED — change 7]** the help text for `down` therefore warns unconditionally; the old "if it does, the help text says so" is the false pass the review named. v1 has no repeat-rate control, and `zwp_virtual_keyboard_v1` has no `repeated` state to ask the compositor about. Chords (`Control_L` held across a `type`) remain the justified use of `down`. +- **Mask versus Shift keycode.** §4's letter path can still be wrong for a toolkit that ignores `modifiers` and only shifts when it sees `KEY_LEFTSHIFT`. The VM victim must print both the mask and the decoded sym. Chromium is not the first victim (`vm-pointer` avoided it; it is expensive and the app-id rule in `README.dev.md` item 4 only binds clients that honour `$HHSTREAM_APP_ID`). +- **The lease is not a security boundary.** `PLAN` §6.6: any client may bind the pointer global. The keyboard global is the same. Stage 4 sandboxing is unchanged and out of this work. +- **Concurrent typing is impossible** on one compositor, for the same reason concurrent pointers are (`PLAN` §1). A second seat is Stage 5 and still CPU-gated. This work does not pretend otherwise. +- **`xkbcommon` in the devshell** is a new dependency. Tests that import `keymap.py` cannot skip when it is absent; an optional dependency would let the unmappable-character path rot. + +### Open questions + +Questions 1–4 are **closed by Stage 0** (`tests/README-keyboard-probe.md` and its transcript). Question 5 is answered by the operator. + +1. ~~Stage 0 global name and version on the actual `/run/hypr-stream` socket.~~ **`zwp_virtual_keyboard_manager_v1` at version 1.** No `wp_virtual_keyboard_v1`. The gate holds. +2. ~~Does acquire's warp produce `wl_keyboard.enter`?~~ **Not from a single idle warp — so acquire stopped being a single warp.** See risk 1 above. Measured again end to end by `vm-keyboard` on both layouts, where the two-warp acquire does deliver `enter` to the aimed window and `leave` to the one that held focus. +3. ~~On destroy, does Hyprland release keys that were down?~~ **No.** See risk 2. +4. ~~Does Hyprland auto-repeat those keys?~~ **Not on the wire; the client does.** See the auto-repeat risk. +5. **Answered: `us`, and configurable.** The operator's decision is a NixOS option in the `hhstream` namespace, string, default `"us"`, documented in `README.dev.md` — reaching the keymap as `--xkb-layout` on the driver unit, per change 5. +6. A later stage, only if agents must type arbitrary UTF-8: a throwaway keymap that maps spare keycodes to `0x01000000 + codepoint` for the duration of one `type`, then restores the layout keymap. Not v1. It reintroduces the "upload resets held modifiers" problem, so it has to refuse to run while any key is held. + +### Stages + +| Stage | Work | Rough size | Gate | +| --- | --- | --- | --- | +| 0 | **Done.** `tests/keyboard_probe.py`, its README and its transcript. Two windows, not one; read-only `hyprctl` for the boxes; `(a1)` and `(a2)` measured separately; no `hyprctl dispatch`. | S | **Passed.** Named global is `zwp_virtual_keyboard_manager_v1` v1. | +| 1 | Driver: vendor, `keymap.py`, ops, backend upload, `__main__` flags, pointer unit tests. Pointer still runs if the global is missing. | M, about 3–5 days | `pytest tests/pointer` green. `type` of an unmappable character emits no events. | +| 2 | Broker mirror, verbs, CLI, module argv, session unit tests, contract doc amendments, stale `follow_mouse` comments. **No `policy.py` and no TOML table** (change 5). | M, about 2–4 days | `pytest tests/pointer tests/sessions/unit` green. Expiry test shows `release_all` lifting a held key. No new unit under `nix/module.nix`, and nothing there beyond argv. | +| 3 | **Done.** `checks/vm-keyboard.nix` and `checks/lib/keyboard_target.py`, exposed twice (`vm-keyboard`, `vm-keyboard-de`) because the layout reaches the keymap only through the driver unit's argv. Its enter subtest **is** written against acquire, because acquire is two warps now — see the risk paragraph above and the file's own header. | M | **Passed**, both layouts: characters on A, silence on B, key-up after a real TTL, second acquire is 8, red if the keymap was not uploaded. | +| ~~4~~ | **Does not exist as pending work.** It was "build `focuswindow` before the first key of a lease, if Stage 0 shows no enter". Stage 0 did show no enter after a *single* warp, and the answer was the second warp in `_warp_taking_focus`, not a focus dispatch — so the Stage 3 enter assertion is green without loosening it. `focuswindow` shipped in Stage 2 as the nudge-failure fallback *inside* acquire, which is a different mechanism for a different failure. Nothing here is outstanding. | — | — | + +Rollback of Stages 1–2 is reverting the commit: old brokers never send `key`/`type`, and an old driver rejects unknown ops with `ok: false` (`ops.py` already answers unknown `op` instead of dropping the connection). No registry schema bump. Bookmarks stay as they are. \ No newline at end of file diff --git a/docs/plans/2026-10-04-keyboard-verification.md b/docs/plans/2026-10-04-keyboard-verification.md new file mode 100644 index 0000000..4a86450 --- /dev/null +++ b/docs/plans/2026-10-04-keyboard-verification.md @@ -0,0 +1,351 @@ +# Keyboard plan — verification and tests + +Adversarial check of `docs/plans/2026-10-03-keyboard-input.md` (commit `14b3f69` on `feat/keyboard-input`; that file is not in this checkout). Source citations are from this tree. `git diff 14b3f69 HEAD -- src nix tests checks docs/CONTRACT-sessions.md docs/PLAN-workspaces-and-pointer.md` is empty, so the pointer/broker code the plan describes is the code reviewed here. + +Compositor claims below are from the Hyprland **v0.56.2** tree `PLAN-workspaces-and-pointer.md` says it measured (not from a registry dump on `/run/hypr-stream`). Stage 0 still has to confirm the running binary. Until it does, treat the source as the prior, not as a pass. + +**Bet, up front:** do not implement the plan as written. The shape is right (same driver, same lease, `zwp_virtual_keyboard_v1`, names on our JSON, evdev only on the Wayland `key` request, mask rather than a synthetic Shift key). Five plan edits are load-bearing and cheap only before Stage 1: the exit-2 vs `driver_refused` contradiction, NUL included in the keymap `size`, `release_pressed_on_close` (default is off, and destroy does not clear the modifier mask), focus is not a coin-flip, and the layout option reaches the keymap only via the pointer unit's argv. Detail below. + +--- + +## Layout option (operator decision, not re-litigated) + +The layout is a NixOS option on the pointer unit's command line. It is not a broker TOML key. `[pointer]` is read by `hhstreamd` (`policy.py` `settings_from_dict`, `__main__.py` around the `load_settings` call) for lease numbers only. The driver is a different unit (`nix/module.nix` `systemd.services.hhstream-pointer`) and never sees that file. Emitting `[keyboard]` "the way `[pointer]` is emitted" (plan §2 file table) does not upload a keymap. + +| | | +| --- | --- | +| Attribute | `services.hyprland-headless-stream.sessions.keyboard.layout` | +| Type | `lib.types.strMatching "[A-Za-z0-9_-]+"` | +| Default | `"us"` | +| Description | XKB layout the `hhstream-pointer` unit uploads once as the virtual keyboard keymap (`rules` `evdev`, model `pc105`). Injected keys are decoded with this keymap. Hyprland `input:kb_layout` is not read. One group: a comma-separated list does not match the type. `de` is the value the VM check uses for a non-`us` proof. | + +`variant` / `options` / `model` stay as the plan wrote them (`""`, `""`, `"pc105"`). They are not required for the `de` y/z proof. Do not add a `rules` option; the driver hardcodes `evdev`. + +Path to the upload, in order: + +1. `nix/module.nix` `hhstream-pointer` `ExecStart` (today the frozen two-flag line at the `ExecStart = lib.escapeShellArgs` block, ~986–992) gains `--xkb-layout ${cfg.sessions.keyboard.layout}` plus the plan's `--xkb-model`, `--xkb-variant`, `--xkb-options`. +2. `hhstream_pointer/__main__.py` parses them. A comma in `layout`, or a layout `xkb_keymap_new_from_names` rejects, returns `EXIT_USAGE` (2) **before** `WaylandSink.connect`. xkbcommon accepts `us,ru`; the driver must reject `,` itself. The Nix type does not cover a hand-run binary. +3. `keymap.py` compiles `rules=evdev`, `model`, `layout`, `variant`, `options` and returns one text keymap. Same object for every later `type`. +4. `backend.py` `create_virtual_keyboard(seat)` once, then one `keymap` request, then `listen`. Not on acquire, not per string. + +`CONTRACT-sessions.md` §3.4's "command line the module will pass, exactly" and the unit comment that quotes it (`module.nix` ~981–985) have to be amended in the same change. §5's binary and socket names do not change. + +--- + +## A. What the plan gets right + +Do not reopen these. + +- **Not a new service.** `CONTRACT-sessions.md` §5 freezes binary `hhstream-pointer` and socket `/run/hhstream/pointer.sock`. A CLI group on `hhstream session` is not a new binary. No second socket, no second unit. +- **No `touch`.** §4: `touch` is the only activity mark; every `pointer.*` verb leaves the idle clock alone. `pointer_click` never calls `registry.touch` (`manager.py` `pointer_click`). Routing `keyboard.*` through `_refresh` and not through `touch` is the same rule, and it is testable the way `test_pointer_verbs_do_not_reset_the_idle_clock` already is (`command_count`). +- **One lease, no `keyboard` flag.** `PLAN` §6.7's flag cannot name which keys to lift. `_Held.buttons` is an insertion-ordered dict because `release_all` must (`pointer.py` `_Held`, `ops.py` `_pressed`). A `keys` dict beside it is the same pattern. `acquire` already raises `LeaseBusy` for the current holder (`pointer.py` `acquire`), so a second id cannot replace a half-typed chord. Two leases would let session B warp while A types: one `wl_seat`, and `follow_mouse = 1` (`nix/hyprland-conf.nix`). +- **Exit 9 is implementable where the plan says.** Gesture verbs go through `_refresh` (`manager.py`): live session, `_expire_pointer`, then `PointerLease.refresh`, and `LeaseInvalid` becomes `no_lease`. The CLI already refuses with exit 9 before the broker when the cache is empty (`hhstream_session/__init__.py` `_lease_of` / `_no_lease`), using `lease.py`'s `pointer-leases.json`. There is no second cache to add. Another session's hold is 9, not 8; 8 is only `LeaseBusy` on a second `pointer.acquire` (`pointer_busy` → `ExitCode.BUSY`). +- **`expire()` stays `LeaseInfo` only.** §3.3. `_expire_pointer` already reads `pressed()` before `expire()` and then calls one `release_all`. Reading `keys_pressed()` on that same line is the whole of the lease-side change. Do not add `release_all_keys`. +- **Replay mechanism is the click mechanism.** `server.py` `_dispatch` looks up `request_id` before the handler and `remember`s after, success or failure. Membership is `MUTATING_VERBS` (`protocol.py`). `pointer.state` is not in that set. Putting `keyboard.key` and `keyboard.type` in it, and not `pointer.state`, matches `test_a_retried_click_with_the_same_request_id_clicks_once` (`tests/sessions/integration/test_containers.py`). +- **Names on our JSON, evdev only on the Wayland request.** This is what the plan's own driver examples say (`{"op":"key","key":"Return"}`), and it is what `buttons.py` does: names on the broker and driver sockets, `code_for` inside `ops.py`, integers only in `PointerSink.button`. The shorthand "evdev codes on the driver wire" is not the plan and would force a keymap into the broker. Do not "correct" the plan toward that. +- **No keyboard `frame`.** `zwp_virtual_keyboard_v1` v1 requests are `keymap`, `key`, `modifiers`, `destroy`. `backend.py` `display.flush()` on every pointer method is a socket flush, not a `wl_pointer.frame`. `ops.py` `frame` is a separate op because the pointer protocol delivers on `frame` (`PointerSink.frame` docstring; `driver.py` `frame` docstring). A key queued until `frame` would never be sent. Keyboard requests must flush inside the sink the way `button` does, and must not call `_aimed()` — keys are not per output (`ops.py` `_aimed` raises when nothing has been warped). +- **Missing keyboard global must not `ManagerTooOld`.** That exception is the pointer manager below version 2 (`backend.py`, `__main__.py` `connect`), because a v1 pointer aims at the desktop. A missing `zwp_virtual_keyboard_manager_v1` is a different failure. Pointer ops have to keep working. +- **Mask, not a synthetic Shift, for a capital.** Confirmed against v0.56.2 below. VM must print mask and keycode, not only the character. +- **Validate the whole string before the first sink call.** Same reason a bad axis emits nothing (`test_an_unknown_axis_is_refused_by_the_driver_not_invented`). +- **Audit stores a count.** `AuditLog.emit` writes every field it is given (`audit.py`). The generic `request` line in `server.py` stores the error **name**, not the body. A dedicated `keyboard_type` event is the leak. `chars` and not `text` is the right shape; click stores `button` and `count` (`pointer_click`). +- **VM proof is required.** `docs/TODO/scroll-has-no-compositor-proof.md` is the precedent the plan cites. Unit tests do not show a client decode a symbol. +- **Rollback.** Unknown `op` is `Rejected` and the connection stays (`ops.py` `_handle`). Old brokers never send `key` / `type`. + +--- + +## A. Protocol + +`zwp_virtual_keyboard_manager_v1` version 1 is what Hyprland v0.56.2 binds (`ProtocolManager.cpp` constructs `CVirtualKeyboardProtocol` with version 1). There is no `wp_virtual_keyboard_v1` in that tree. uinput is a second privilege the pointer path does not have (`WaylandSink` is a client; the unit's only extra privilege is group `hhstream` so it can open the Wayland socket, `module.nix` `SupplementaryGroups`). Rejecting `wtype` as the mechanism is right: one process, one keymap, one `release_all`. + +v1 requests and the values the plan never writes down: + +| Request | Arguments | Values that matter | +| --- | --- | --- | +| `keymap` | `format: uint`, `fd: fd`, `size: uint` | Protocol `keymap_format.xkb_v1 = 1`. That format is a **null-terminated** libxkbcommon text keymap. The `key` event's code is an evdev code; clients add 8. | +| `key` | `time: uint`, `key: uint`, `state: uint` | `key_state.released = 0`, `pressed = 1`. Same integers as `buttons.STATES`. `time` is milliseconds, undefined base, **one clock for the object**. | +| `modifiers` | four `uint`s | depressed, latched, locked, group. Not derived by this protocol from `key`. | +| `destroy` | destructor | See held keys below. | + +`key` or `modifiers` before `keymap` is protocol error `no_keymap` (0). Hyprland posts it and the client connection dies (`VirtualKeyboard.cpp` `setKey` / `setModifiers`). That is not `{"ok": false}` and not a retry. "Upload once, after connect, before `listen`" is the right order (`__main__.py` already treats a listening socket as a promise). A second `keymap` is not a refresh: Hyprland replaces the xkb state and does **not** walk `m_pressed` (`setKeymap` in the same file). + +What the plan gets wrong or leaves out: + +1. **`size` must include the trailing NUL.** Hyprland `mmap`s exactly `len` bytes and passes the pointer to `xkb_keymap_new_from_string` (`VirtualKeyboard.cpp` keymap handler). No NUL inside that map reads off the end. The plan says "memfd of an XKB text keymap" and never says `size == strlen + 1`. +2. **`time` is unspecified.** Pointer methods pass `_now_ms()` (`backend.py`, monotonic ms, low 32 bits). The keyboard sink has to use that same function. A constant 0 is one clock and therefore legal, but it is a second clock the moment anything else on the object uses monotonic time. +3. **Hyprland ignores `format` and parses as `XKB_KEYMAP_FORMAT_TEXT_V2`.** Send `format = 1` anyway. A `TEXT_V1` string from `xkb_keymap_get_as_string` is what V2 accepts. Do not pass `XKB_KEYMAP_FORMAT_TEXT_V2` (the integer 2) as the Wayland format. +4. **Do not vendor Hyprland's `protocols/virtual-keyboard-unstable-v1.xml`.** That v0.56.2 copy mentions `keymap_format` and `key_state` and does not define them. The plan's wayland-protocols path is the right file (`share/wayland-protocols/unstable/virtual-keyboard/virtual-keyboard-unstable-v1.xml`). `regenerate.py` must seed the import map from core `wl_*` the way it already does; scanning this XML alone `KeyError`s on `wl_seat`. +5. **`release_all` with no keyboard object must still lift buttons.** The plan says a missing global is not fatal, and also says `release_all` grows key-ups and a `modifiers(0,…)`. If the key half throws, `_expire_pointer`'s one `release_all` stops lifting buttons. Key-ups and `modifiers` run only when `create_virtual_keyboard` succeeded. +6. **Upload failure is exit 10 and must not `listen`.** A keymap Hyprland rejects is `noMemory` on that resource, i.e. a dead connection. Layout rejection before connect stays exit 2. The plan specifies only the second. + +`ManagerTooOld` wording in the plan matches the code. "No per-output target" matches the XML (`create_virtual_keyboard(seat)` only) and is why `key` must not go through `_aimed()`. + +--- + +## A. Surface and lease + +§4 and §5 hold, with one contract edit the plan already schedules (§3.3 key mirror, §3.4 ops and argv, §4 verb rows). Do not renumber `ExitCode`. New verbs do not call `touch`. + +**Exit codes do not match the pointer path the plan says it copies.** + +`_drive` turns every driver `ok: false` into `ManagerError("driver_refused")` (`manager.py`), and `driver_refused` is exit **10** (`protocol.py` `EXIT_CODE_FOR_ERROR`). An unknown button is not exit 2: `_button_name` only checks "non-empty string", and `test_an_unknown_button_is_refused_by_the_driver_not_invented` asserts `driver_refused`. The plan says both "Rejected, same as a bad button" and "exit 2 for a bad keysym or an unmappable character". Those are different codes. Exit 2 happens only for `invalid_argument` raised in the broker **before** `_drive` (`_checked_count`, a non-string button). + +So, as written: + +| Case | What the plan says | What the current mapping does if resolution stays in the driver | +| --- | --- | --- | +| text longer than 4096 scalars | `invalid_argument` (2) | 2, **if** the broker checks `len` before `_drive`. The driver check alone is 10. | +| bad keysym, `é` on `us`, C0 other than `\n`/`\t`, dead key, `type` while a non-modifier is held | 2 | **10** `driver_refused` | +| no keyboard global, or the Wayland connection died | 10 | 10. Right. | +| no lease / other holder | 9 | 9 via `_refresh`. Right. | +| second `pointer.acquire` | 8 | 8. Right. `keyboard.*` must not call `acquire`. | + +Pick one before Stage 1. Recommended, because a bad character is not a dead compositor: broker rejects non-string text, the 4096 cap, and a bad `state` as `invalid_argument`. Driver rejections that are caller errors carry a stable token (not only a sentence), and `_drive` maps that token to `invalid_argument`. `driver_refused` stays "the keyboard global is missing". Copying the button path and then asserting exit 2 in the tests will fail. + +**Acquire's own stderr contradicts the lease story.** `__init__.py` prints "expires in … with no further **pointer** verb". A `keyboard.*` verb that goes through `_refresh` moves `expires_at`. That sentence has to say any pointer or keyboard verb. Otherwise the TTL test looks "flaky" against the help text. + +`type` refreshes once per broker verb because `_refresh` is once per verb. It must not call `refresh` per character. Explicit modifier holds live in `_Held.keys` across later `type`s; `release()` drops the whole `_Held`, so the mirror does not leak into the next holder. `pointer_release` already calls `_release_all_buttons` before `PointerLease.release`. One extended `release_all` covers keys. Audit for release already has `buttons_lifted` from the **driver** list, not from `LeaseOutcome` (`pointer_release`). `keys_lifted` goes next to that field, not into a new release body. `pointer_lease_timeout` already records `pressed` and `buttons_lifted`; add `keys_lifted` there. + +`_refresh` still requires a container output (`_pointer_output`). Typing has no output argument, but the lease gate does. A session with no container gets `no_container` (exit 10) the same way a click does. That is existing behaviour, not a new keyboard rule. Do not special-case it. + +--- + +## A. Idempotency and audit + +A completed `keyboard.type` with a given `request_id` does not type twice, **for the same reason a completed click does not click twice**: lookup hits, the handler is not called, the reply is the stored object plus `deduplicated: true`. A stored failure is replayed too (`test_a_recorded_failure_is_replayed_as_the_failure_it_was`), so a retried unmappable `type` must not touch the sink either. + +The plan does not get a stronger guarantee than click, and it should not claim one: + +- The cache key is `request_id` alone (`IdempotencyCache.lookup`). A `keyboard.type` that reuses a `pointer.click` id returns the click reply and does not type. +- `remember` runs after the handler returns. Two connections in flight with the same id both miss the cache. The driver lock serialises the Wayland writes; it does not collapse them. Both strings are typed. +- Capacity is `DEDUP_ENTRIES` (64). An older id is forgotten and will type again. +- A driver death **mid-string** is not the unmappable case. Validation-before-emit stops a bad character from typing a prefix. A connection drop after character 2 of 5 still typed 2, the error is then cached, and the replay does not finish the word or undo it. Click has the same hole between down and up. Say so; do not let the "no prefix" sentence cover it. + +Audit: `keyboard_key` may store the keysym name and `down`/`up`. `keyboard_type` stores `chars` (scalar count) and nothing else from the string. Driver logs and `Rejected` messages must use an index ("unmappable at scalar 3"), not the character and not the string. `emit` will happily write a `text` field if a caller passes one. The shell and `ps` still show the CLI argument; that is outside this audit rule. + +--- + +## A. Correctness traps + +### Typing `A` (nothing else held, layout `us`, model `pc105`) + +Evdev `KEY_A` is **30**. The XKB keycode is 38. The Wayland `key` request and `wl_keyboard.key` both carry **30**. Shift's modifier index on the evdev `us` map is 0, so the depressed mask is `1 << 0` = **1**. Do not hardcode 1 in the resolver; ask xkbcommon (`xkb_keymap_key_get_mods_for_level` or the equivalent level lookup). On `us` the lookup returns 1. + +`devices/Keyboard.cpp` (libinput keyboards) calls `updateXkbStateWithKey`. `devices/VirtualKeyboard.cpp` does not: `updatePressed` only edits `m_pressed` (`IKeyboard.cpp`). A virtual `key(KEY_LEFTSHIFT)` does **not** change Hyprland's modifier mask and does **not** cause `wl_keyboard.modifiers`. The `modifiers` request is required. The plan is right. + +Sequence on `zwp_virtual_keyboard_v1`, one object, `time` from `_now_ms()`: + +``` +modifiers(mods_depressed=1, mods_latched=0, mods_locked=0, group=0) +key(time, key=30, state=1) # pressed +key(time, key=30, state=0) # released +modifiers(0, 0, 0, 0) +``` + +Not in that sequence: evdev 42 (`KEY_LEFTSHIFT`), XKB code 38, a pointer `frame`. `modifiers` goes **before** the key. A client that decodes with the mask from the last `wl_keyboard.modifiers` (foot, GTK) emits `a` if the key comes first. + +`keyboard down Shift_L` is the other path, and the plan is right to keep it different: send `key(42, pressed)` **and** `modifiers(1, 0, 0, 0)`, and remember both. `release_all` key-ups in press order, then `modifiers(0, 0, 0, group)`. The `modifiers(0)` is not optional. Virtual key-ups do not clear the mask, because `updateXkbStateWithKey` never runs for this device. A `release_all` that only key-ups leaves Shift latched in every client that trusts the mask. + +`type` while `Shift_L` is already held ORs the character mask with that baseline (still 1 for `a`) and must not emit a second Shift key. `type` while a non-modifier is held emits nothing. The plan never defines "modifier". Define it as the keysyms that contribute to the depressed mask on this keymap: `Shift_L/R`, `Control_L/R`, `Alt_L/R`, `Meta_L/R`, `Super_L/R`, `Hyper_L/R`, `ISO_Level3_Shift`, `ISO_Level5_Shift`. `Caps_Lock` and `Num_Lock` are locks, not that set; v1 rejects `type` while they are held. A Shift-only special case fails the `de` VM check (`@` is a level-3 mask, not Shift). + +Ctrl is index 2, mask 4, on the same map. `down Control_L` then `type c` is `modifiers(4)`, `key(KEY_C)`, `modifiers(4)`, and `Control_L` still in `keys`. + +### Warp does not guarantee `wl_keyboard.enter` + +The plan's risk is right, and understated. v0.56.2 already answers it for the shipped config. + +`onMouseWarp` calls `mouseMoveUnified(time)` with `refocus=false` (`InputManager.cpp`). With `follow_mouse == 1`, the distance added to `m_mousePosDelta` is the distance of **this** warp only when the previous cursor movement was **under 0.5 s** ago; otherwise the delta is set to 0. Keyboard focus then requires `m_mousePosDelta > follow_mouse_threshold` or `refocus`. The threshold option defaults to **0**, so the test is `> 0`. One warp after the cursor has been still does not pass it. + +Pointer focus is updated later in the same function with no threshold. That is why `vm-pointer` saw clicks land, and why `follow_mouse = 0` delivered clicks to nobody (`hyprland-conf.nix` comment, `checks/vm-pointer.nix` header). Those measurements are not `wl_keyboard.enter`. + +`rawWindowFocus` still runs if `keyboardFocus == nullptr`. A single mapped window is usually focused at map time, so a one-window probe prints `enter` and proves nothing about the warp. `cursor.no_warps = true` in our conf blocks `PointerController::warpTo`, not a virtual pointer's `warpAbsolute`. The cursor does move. Focus still does not. + +A second warp inside 0.5 s adds a non-zero delta and can focus. Stage 0 has to measure **one idle warp** and **a second warp inside the window** separately. `dispatch focuswindow` stays the fallback the plan names, and it is likely mandatory, not a surprise Stage 4. Do not build it in Stage 1. Do not write Stage 3's enter assertion against one window. + +**[AMENDED after Stage 2 — "likely mandatory" was the wrong prediction.]** Stage 0 measured exactly what this paragraph predicted, and the fix that shipped is the **second warp**, not the focus dispatch: `pointer_acquire` sends a nudge and then the target, which is the "second warp inside 0.5 s" above. `focuswindow` did ship, but as the narrow fallback for a nudge that could not be *sent*, inside acquire — not as the mechanism that moves focus. So Stage 4 is not pending work of any kind. See `docs/CONTRACT-sessions.md` v3 §4 and §B3 subtest 1 below. + +### Destroy, expiry, `kill -9` + +Three different paths. + +| Path | What runs | v0.56.2 result | +| --- | --- | --- | +| TTL, `pointer release`, kill/reap of the **holder** | Broker `release_all`: button-ups, key-ups, `modifiers(0,0,0,0)`. Object stays. | Keys and mask clear **if we send them**. `input:virtualkeyboard:release_pressed_on_close` is irrelevant. | +| Driver `SIGTERM` | `__main__.py` `finally` → `_lift_everything` → `release_all`, then `sink.close`. | Same, once `release_all` lifts keys. The comment today says buttons only. | +| `destroy` of the resource, client disconnect, `kill -9` | `CVirtualKeyboardV1Resource::destroy`. `releasePressed()` runs only when `input:virtualkeyboard:release_pressed_on_close` is true. | Default is **false** (`ConfigValues.cpp`; device default `INT{0}` in `ConfigManager.cpp`). No key-ups. `releasePressed` emits key-ups only, never `modifiers`. The destructor emits `destroy` and does not release. | + +Stuck keys are worse than "a key stays down". `InputManager::onKeyboardKey` drops a press whose code is already in the seat's `m_pressed`, and drops a release that is not (`if (CONTAINS && pressed) return`). After `kill -9` with the default config, that code stays in `m_pressed`. The next driver's `key down` for it is ignored. The seat looks dead for that key until some client sends a matching `key up`. + +Required plan change, one line in `nix/hyprland-conf.nix`: `input:virtualkeyboard:release_pressed_on_close = true`. Still send explicit ups on the clean path. Still send `modifiers(0, 0, 0, 0)` once after the initial keymap upload, because even the true setting does not clear a mask, and a client keeps the last `wl_keyboard.modifiers` until the next one. Stage 0 confirms the running binary; the default in this tree is not an open question with even odds. + +`share_states` defaults to 2 (`only_non_ime`). Our client is not an IME grab, so the mask Hyprland forwards is the OR of every sharing keyboard (`shareModsFromAllKBs`). Headless config sets `WLR_LIBINPUT_NO_DEVICES=1` (`module.nix`). With no second keyboard the OR is a no-op. A second virtual keyboard with Shift held will keep Shift in the forwarded mask after our `modifiers(0)`. Not v1's problem; do not paper over it with a retry loop. + +### Auto-repeat + +Hyprland does not re-send `wl_keyboard.key` for a held key. It stores `input:repeat_rate` (default **25**) and `input:repeat_delay` (default **600**) on the keyboard and sends `wl_keyboard.repeat_info` (`Seat.cpp`). The client repeats. `KeybindManager`'s timer repeats **binds**, and virtual keys go through `onKeyEvent` unless the client is the IME (`shouldIgnoreVirtualKeyboard`). A bound key may never reach the window, and the bind may repeat. + +The plan's "if Stage 0 shows no repeat, the help text stays quiet" is the wrong gate. A raw client that counts `wl_keyboard.key` will see one press. foot/GTK/Qt will insert characters until key-up or TTL (default 30 s) from that one press plus `repeat_info`. `keyboard down` of a non-modifier must say so in the help text regardless of the probe. `type` and `keyboard key` are taps (down then up) and stay under the delay if the pair is immediate. The justified hold is a modifier chord, which clients do not repeat as text. + +There is no `repeated` state on `zwp_virtual_keyboard_v1.key` (Wayland's `wl_keyboard.key_state.repeated = 2` is client-facing, since version 10). We cannot ask the compositor for a repeat rate. + +--- + +## A. Changes required before code, cheapest first + +| # | Change | If it waits until after Stage 1 | +| --- | --- | --- | +| 1 | Resolve exit 2 vs `driver_refused`. Broker-side checks for shape and the 4096 cap. A distinct driver token for "your keysym/character", mapped to `invalid_argument`. Missing global stays 10. | Help text, `test_exit_codes.py`, and every verb test encode the wrong code. | +| 2 | Keymap `size` includes the NUL; fd stays alive across `flush`. `format = 1`. `time` is `_now_ms()`. | First real `type` kills the driver or types nothing. Looks like "Hyprland has no global". | +| 3 | `release_all` no-ops the key half when no virtual keyboard exists. `modifiers(0,…)` after upload, and at the end of every `release_all` that touched a mask. | A missing global breaks button expiry. A crash mid-`A` leaves Shift on for the next holder. | +| 4 | Set `input:virtualkeyboard:release_pressed_on_close = true` in `hyprland-conf.nix`. Document that this still does not clear the mask. | First `kill -9` during Stage 1 poisons `m_pressed`. Later downs of that key vanish. | +| 5 | Layout option as specified above, on the unit argv. Driver rejects `,` before `xkb_keymap_new_from_names`. Do not treat `[keyboard]` in the TOML as the upload path. | VM "non-us" checks the broker file, the driver stays on `us`, test is a false pass or a surprise. | +| 6 | Write down the modifier-keysym set. Resolver returns `(evdev, mask)` for any level, not a Shift special case. `key`/`type` do not call `_aimed()`. | `de` and Ctrl+C get a second code path that disagrees with `us`. `type` without a prior warp fails only in a test that forgot to acquire. | +| 7 | Stage 0 expectations: one idle warp does not `enter`; destroy with the default config does not release; one held key is one `wl_keyboard.key`, while `repeat_info` is still sent. Help text for `down` warns unconditionally. Two-window probe, or the enter result is a false pass. | Stage 3 goes red, or goes green because the only window was focused at map time. Stage 4 arrives as a surprise. | +| 8 | Acquire stderr says keyboard verbs refresh the TTL. `Rejected` text and driver logs carry an index, not the string. | Operators release during a `type` that would have kept the lease. A password lands in the journal even though `events.jsonl` is clean. | + +Not required to change: the protocol choice, the process boundary, the single lease, names-vs-evdev, no `frame`, no `touch`, `expire()`'s return type, one `release_all`, mutation-set replay, `chars` not `text`, single group, xkbcommon as a hard test dependency, a real VM check. + +--- + +## B. Tests + +Gate for Stages 1–2 stays `nix develop -c python -m pytest tests/pointer tests/sessions/unit -q`. No test sleeps except the VM and the Stage 0 probe. No test in `tests/sessions/integration/` grows a fake compositor. + +### B1. Stage 0 probe + +One throwaway client, not committed, not run via the broker. It is not `hhstream`. It does not open `/run/hhstream/control.sock` or `pointer.sock`. + +Run it as the broker account (supplementary group `hhstream`, `module.nix` `sessions.user` description — that group is what makes `wayland-*` openable; the directory is `0750`): + +``` +sudo -u hermes -g hhstream env \ + XDG_RUNTIME_DIR=/run/hypr-stream \ + WAYLAND_DISPLAY="$(sudo -u hermes -g hhstream \ + find /run/hypr-stream -maxdepth 1 -name 'wayland-*' ! -name '*.lock' -printf '%f\n')" \ + python3 /tmp/kb-probe.py +``` + +Refuse to start if `find` prints more than one name (`backend.py` `find_wayland_display` does). Read-only `hyprctl` (`clients -j`, `monitors -j`, `getoption`) is allowed so the warp hits a known box. `hyprctl dispatch` is not allowed: `dispatch focuswindow` answers question (a) by cheating. + +The script uses pywayland. It binds `wl_compositor`, `wl_shm`, `xdg_wm_base`, `wl_seat`, `wl_output`, `zwlr_virtual_pointer_manager_v1`, `zwp_virtual_keyboard_manager_v1`. It prints every global as `global v` and exits 2 if the keyboard manager is missing or not version 1. Two `xdg_toplevel`s, app ids `kb-probe-a` and `kb-probe-b`, both mapped and acknowledged. `wl_keyboard` listener prints, flushed: + +``` +enter surface= serial= keys=[...] +leave surface= +repeat_info rate= delay= +keymap bytes= symbols= +modifiers depressed= latched= locked= group= +key code= state=<0|1|2> sym= +``` + +`sym` comes from `xkb_state` built from the **keymap fd the compositor sent**, updated with `xkb_state_update_mask` on `modifiers` and `xkb_state_key_get_one_sym(key+8)` on `key`. Not from a table inside the script. + +Sequence, printing a banner line before each step: + +1. Map A, map B. Sleep 0.6 s so the cursor has been still longer than Hyprland's 0.5 s window. +2. **(a1)** One `motion_absolute` of a virtual pointer bound to B's output, into A's box (normalised, from `hyprctl clients`). Sleep 0.3 s. Assert-by-printing: no new `enter` for A. An `enter` here means this binary does not match the v0.56.2 threshold logic; say so and continue. +3. **(a2)** A second warp, still inside A, immediately. Print whether A then gets `enter` and B gets `leave`. This is the double-warp question, separate from (a1). +4. Upload an `us` / `pc105` keymap (`format=1`, `size` includes NUL) on a virtual keyboard. Print `uploaded`. +5. **(c)** `key(KEY_A=30, pressed)` once. Sleep 1.5 s (longer than the 600 ms default delay). Print `press_count=` of `state=1` or `state=2` events for code 30. Do not key-up yet. +6. **(b)** `destroy` the virtual keyboard. Roundtrip. Sleep 0.2 s. Print `release_on_destroy=` and `mask_cleared=`. Do not send `key up` or `modifiers` before this. +7. Cleanup, required: a **new** virtual keyboard, keymap again, `key(30, released)`, `modifiers(0,0,0,0)`, destroy. Print `cleanup=sent`. This undoes a poisoned `m_pressed` if step 6 released nothing. + +**(a) passes** only if the log shows, in order: B entered at map; after (a1) A has no new `enter`; the line says which warp, if any, produced A's `enter`. A pass that is a lie: only one window, or `enter` counted with no check that it happened after the warp rather than at map, or a `hyprctl dispatch focuswindow` before the warp. + +**(b) passes** as a measurement, not as a green feature: print the `getoption` value of `input:virtualkeyboard:release_pressed_on_close` next to `release_on_destroy`. On v0.56.2 with the default, expect `release_on_destroy=no` and `mask_cleared=no`. A pass that is a lie: the script sent `key up` before `destroy`, or it counted a release from step 7. + +**(c) passes** as a measurement: `press_count` and the `repeat_info` line are both printed. Expect `press_count=1` and a non-zero rate on this source. Interpreting `press_count=1` as "`keyboard down` will not flood a text field" is the false pass. The flood is the client's repeat, which this probe does not implement on purpose. + +### B2. Unit tests (Stages 1 and 2) + +Match existing files. Dispatcher tests use a recording sink and do not grant authority (`tests/pointer/test_ops.py` module docstring). Lease tests use the injected clock (`tests/pointer/conftest.py`). Broker tests use the real UNIX socket and `FakeDriver` (`tests/sessions/unit/test_pointer_verbs.py`). + +`tests/pointer/test_keymap.py` — real xkbcommon, not a stub. + +| Case | Pass | False pass | +| --- | --- | --- | +| `us`: `a` → `(30, 0)`; `A` → `(30, mask)` with mask equal to `1 << xkb_keymap_mod_get_index(..., "Shift")`; `Return` and `"\n"` → `KEY_ENTER` (28); `Tab` and `"\t"` → 15 | Those tuples | Asserting xkb code 38, or hardcoding mask `1` without reading the index (breaks the day the resolver is used for `de`) | +| `""` → `[]` | Empty, no error | | +| `"é"`, `"\x01"`, keysym `dead_acute` raise | Exception type the dispatcher already maps to `Rejected` | Asserting the message contains `é` (that string would be logged) | +| `"abé"` through the dispatcher | `ok: false` and **zero** sink calls | Asserting only that no event carried `é`, while `a` and `b` were emitted | +| 4096 scalars of `a` accepted; 4097 rejected with zero sink calls; one case is 4096 scalars of `😀` (`len == 4096`) | Boundary as scalars | ASCII only: a byte cap and a scalar cap agree, so a `len(utf8)` check stays green | +| Two `type`s | The keymap **object** is built once, and the sink's `keymap` method is called once | Asserting only that `keymap.py` returns equal strings. A backend that uploads on every `type` stays green | + +`tests/pointer/test_ops.py` — extend `RecordingSink` with `key(code, state)` and `modifiers(dep, latch, lock, group)`. + +| Case | Pass | False pass | +| --- | --- | --- | +| `key` `down` then `pressed` | `keys == ["Return"]` (name, not 28) | | +| `up` of a key that was not down | `ok: true`, not listed as lifted. Same as `unpress` | | +| `release_all` after `Control_L` then `a` | key-ups in that order, then one `modifiers(0,0,0,0)`, even if the last warp was a different output. No `frame` added for the keys | A sink that ignores the output argument. Warp to output B and assert the key calls were not tagged with B | +| `type "A"` with nothing held | `modifiers(shift), key(30,1), key(30,0), modifiers(0,…)` and `keys == []`. No code 42 | Asserting the sink was called at all, or that some event's code was 30, without the mask before the press and without the absence of 42 | +| `type` with `Control_L` held | Mask ORed, `Control_L` still in `keys`, no Control key-up | | +| `type` with `a` held | `ok: false`, zero new sink calls, `a` still held | | +| `type "Hi"` with **no prior warp** | Keys emitted. Must not return the `_aimed()` error | Every test warps first because it copied `test_ops` helpers. Delete the warp in this one test | +| `release_all` when the sink has no keyboard | Buttons still lift; no exception | Only running it when the keyboard exists | + +`tests/pointer/test_lease.py` — `press_key` order matches `press`. `expire()`'s return has no key list. The test reads `keys_pressed()`, then `expire()`, then sees no holder. Existing busy / stale / `lease_id` tests stay. + +`tests/pointer/test_vendored_protocol.py` — interface `zwp_virtual_keyboard_manager_v1`; requests `keymap`, `key`, `modifiers` on `zwp_virtual_keyboard_v1`; enum values `xkb_v1 == 1`, `pressed == 1`, `released == 0`. No display. + +`tests/sessions/unit/test_keyboard_verbs.py` — copy the `test_pointer_verbs.py` harness. + +| Case | Pass | False pass | +| --- | --- | --- | +| No lease, and another session holds it | `no_lease` (exit 9), not `pointer_busy` | | +| Second `pointer.acquire` while a key is held | `pointer_busy` (8). The held key is still the first holder's | Acquiring from the holder and treating 8 as success | +| `type` and the clock | Advance less than `ttl` after `type`: holder remains. Advance past it: one `release_all`, and that reply's `lifted_keys` contains the key that was down | Advancing the clock without running `_expire_pointer` / the sweep. The unit test must call the sweep or the next verb, the way the pointer expiry test does | +| Driver `ok: false` on `key` | Lease `keys` unchanged | Asserting the error only | +| `type` | `last_activity_boottime` and `command_count` unchanged | `command_count` alone if a future change updates the timestamp without counting a command. Assert the timestamp | +| `pointer.release` and `kill` | Driver `lifted_keys` contains what was down; `pointer.state` holder is null; `keys` is `[]` | `kill` of a session that does not hold the lease (green, lifted nothing) | +| `pointer.state` | `keys` present, names not codes | | +| Replay | Same shape as `test_a_retried_click_…`: second reply `deduplicated: true`, sink `key` count unchanged. Also replay an **unmappable** `type`: still zero sink calls | Asserting `deduplicated` and not the sink. A handler that types and then sets the flag stays green | +| Unmappable / over cap at the broker | Exit 2 `invalid_argument` for the cap and for a non-string. Exit 2 for an unmappable character **only after change 1**; until that mapping exists this assertion fails, which is the point | Treating `driver_refused` as 2 because the CLI printed "usage" somewhere in the hint | + +`tests/sessions/unit/test_settings.py` — only if `[keyboard]` is actually read. If the option lives solely on the unit argv, this test does not belong here; a TOML default of `us` that nothing uploads is the false pass `test_settings.py`'s own docstring warns about. Prefer asserting the driver's flag parser: omitted `--xkb-layout` is `us`, `--xkb-layout de` is `de`, `--xkb-layout us,ru` exits 2 and does not connect (inject a connect function and assert it was not called). + +`test_cli_surface.py` — `keyboard` in `hhstream session --help`; the keyboard help says exit 9 until `pointer acquire`; `pointer --help` does not grow a keyboard tutorial. False pass: the word `keyboard` appears in the pointer help because of the acquire-stderr fix, and the test greps the whole binary help. + +`test_broker_protocol.py` — `keyboard.type` and `keyboard.key` in `VERBS` and `MUTATING_VERBS`; `pointer.state` still absent from the mutating set. `test_every_verb_the_protocol_names_is_one_the_daemon_answers` already fails if only one of the lists is updated. Keep it. + +`test_exit_codes.py` — no new integer. If a new error **name** is added for the driver token, map it in `EXIT_CODE_FOR_ERROR` and add a row. A name that is not in the table becomes exit 4 `BAD_STATE` (`exit_code_for`). That is the false pass for "we return 2": the CLI exits 4 and the test only checked `ok: false`. + +### B3. VM proof (Stage 3) + +New `checks/vm-keyboard.nix`, same shape as `checks/vm-pointer.nix` (`testers.runNixOSTest`, `session-machine.nix`, `session-prelude.nix`, `globalTimeout` on the order of `vm-pointer`'s 1800). Do not fold it into `vm-pointer`. Real time, no injected clock; the expiry subtest in `vm-pointer` says why. + +Victim: a sibling of `checks/lib/pointer_target.py`, not foot and not Chromium. It sets `xdg_toplevel` app id from `$HHSTREAM_APP_ID` (the reason `pointer_target.py` exists: foot ignores the variable and is quarantined). It prints the same keyboard lines as the Stage 0 probe, from the keymap fd. Read-back is `hhstream session logs`, as in `vm-pointer`. + +Subtests: + +1. **Enter.** Two sessions, A and B, B started last so B is focused (the `vm-pointer` measurement that already bit them). `pointer acquire` on A. A's log shows `enter` for A's app id **after** the acquire, and B's log shows `leave`. The assertion is not weakened to "cursor coordinates look right". + + **[AMENDED after Stage 0 and Stage 2 — this said "one warp", and "expected red until the double-warp or `focuswindow` fallback is in".]** Stage 0's (a1) did measure "no enter", and the answer shipped in Stage 2: **acquire is two warps**, a real pixel apart, which is the double-warp this sentence anticipated. So this subtest is a live assertion, not an expected red. `focuswindow` also shipped, but it is *not* what makes this pass — it runs only when the nudge warp cannot be sent — so the check additionally requires the reply's `focus == "warp"` and treats `focuswindow` or `none` as failure. And it asserts `wl_pointer.enter` on A separately from `wl_keyboard.enter`: a check that saw only the cursor arrive would go green while A had the cursor, B had the keys, and the first keystroke of the lease went to B. `docs/CONTRACT-sessions.md` v3 §4 is the authority on the mechanism. +2. **`keyboard type` of `A` then of `hello`.** A's log contains, in order, `modifiers depressed=1`, `key code=30 state=1 sym=A`, `key code=30 state=0`, `modifiers depressed=0`, and **no** `code=42` on that span; then five key downs decoding to `h,e,l,l,o`. B's log has no `key ` line from this span. +3. **TTL.** `keyboard down Shift_L`, `--ttl` of a few seconds, wait it out in real time. A's log shows code 42 released and `modifiers depressed=0`. `pointer state` has `holder` null and `keys` empty. A second `pointer acquire` from B during the hold, before the wait, exits 8. +4. **Layout.** Same VM expression with `sessions.keyboard.layout = "de"` (module argument, so the unit argv changes). Do **not** set Hyprland `input:kb_layout` (leave it unset / `us`). `keyboard type y` decodes to sym `z`; `keyboard type z` decodes to sym `y`. The keymap line from the fd contains the symbols name `de`. + +False passes: + +| Assertion | Looks green while broken | +| --- | --- | +| Characters on A | The log is searched for the substring `hello`, and the session log also contains the broker command or the test script echoing the argument. Match `sym=h` lines from the victim only. `pointer_target.py` prints what the **client** received for this reason | +| Silence on B | B never bound `wl_keyboard`, or B's window was never mapped, so B is silent even when focus is still on B and A also received nothing. (1) and (2) are one assertion: A positive and B negative | +| Keymap was uploaded | A decodes `hello` with a keymap compiled inside the victim. Require the sym to come from the fd, and fail the subtest if no `keymap bytes=` line precedes the keys. The plan's mutation rule (`PLAN` §14): keycodes without a decoded `hello` are a failure | +| Non-`us` | The test greps the guest's systemd unit for `--xkb-layout de` and never types `y`. Or Hyprland `kb_layout` was also set to `de`, so a client that ignored our keymap still decodes `z` | +| TTL key-up | The waiter matches a `state=0` from the earlier `hello` taps. Use code 42, which `type` must not emit | +| Second acquire exits 8 | A leftover holder from a previous subtest. This subtest acquires, holds, and only then has the other session acquire | +| Enter | One session. Map-time `enter` satisfies "A saw enter" | + +Stage 0's script is the wrong place to prove the broker lease. The VM is the wrong place to prove replay. Keep them apart. + +--- + +## If I had to bet + +The plan is safe to **build on** and not safe to **implement as written**. + +I would not reopen `zwp_virtual_keyboard_v1`, the pointer process, the single lease, keysym names on the broker and driver sockets, or "Shift for `A` is a mask". Those match the code and, for the mask, match Hyprland v0.56.2 (`updateXkbStateWithKey` is only on the libinput keyboard). + +I would refuse a Stage 1 that starts from the plan text unchanged. The exit-code paragraph disagrees with `_drive` and with `test_an_unknown_button_is_refused_by_the_driver_not_invented`. The keymap upload omits the NUL that Hyprland's `mmap` requires. Destroy-while-held is not an open question in this tree: `release_pressed_on_close` defaults to false, and the true setting still does not clear modifiers, so `kill -9` poisons `m_pressed`. A single idle warp does not send `wl_keyboard.enter` under `follow_mouse = 1` with the default threshold; a one-window VM check will say it did. The layout option the operator asked for reaches the keymap only as `--xkb-layout` on `hhstream-pointer`, not as a `[keyboard]` table copied from `[pointer]`. + +Those are plan edits, all cheaper than the first driver commit. After them, Stage 0 is a measurement against `/run/hypr-stream` with the expectations above, not a research project, and Stage 1 has a test that goes red for a prefix-typed `é`, a second keymap upload, a replay that types twice, and an `A` that was a Shift keycode instead of a mask. diff --git a/docs/reviews/2026-10-04-stage0-review.md b/docs/reviews/2026-10-04-stage0-review.md new file mode 100644 index 0000000..1f9295d --- /dev/null +++ b/docs/reviews/2026-10-04-stage0-review.md @@ -0,0 +1,128 @@ +# Stage 0 review — keyboard probe + +Reviewed `d07a1fd` (the plan fold-in) and `19e484b` (the probe, its README, and `tests/keyboard-probe-2026-10-04.txt`) against §B1 of `docs/plans/2026-10-04-keyboard-verification.md`. The three probe files are that commit, not an untracked add-on. Dirty Stage 1 files in the worktree were not reviewed and were not touched. The probe was not re-run: this environment has no `HYPRLAND_INSTANCE_SIGNATURE`, so the judgement is the committed transcript read against the script that prints those answer strings. + +## Verdict + +**Yes-with-fixes.** The run measured the gate and questions (a1), (b)'s key, and (c). The write-up then says things the log does not say, and `d07a1fd` did not edit the plan. Do not design Stage 3 from the README's (a) excerpt or from its mask sentence. The raw log, read with the script, is usable. + +## What the evidence actually shows + +The script is the B1 sequence with three real deviations and one hole. It is not a one-window probe, it does not call `hyprctl dispatch`, it refuses a runtime directory that does not contain exactly one `wayland-*` (`tests/keyboard_probe.py:378-389`), it dumps every global as `global v` (`:759-760`) and returns 2 when `zwp_virtual_keyboard_manager_v1` is missing or not version 1 (`:761-770`). `sym` is `xkb_state_key_get_one_sym(code+8)` on a state built from the keymap fd, updated with `update_mask` (`:575-609`, `:627-632`). Cleanup sends `key(30, released)` and `modifiers(0,…)` on a new virtual keyboard and prints `cleanup=sent` (`:940-945`). Deviations, all visible in the log: the keymap is uploaded before the windows rather than after (a); the idle wait is 0.8 s not 0.6 s; (a2) is 0.4 s after (a1), not immediate. + +### Gate + +Log lines 6–75 are the registry. Line 71 is `global zwp_virtual_keyboard_manager_v1 v1`. No `wp_virtual_keyboard_v1` line. Line 76: `ANSWER 1: zwp_virtual_keyboard_manager_v1 is present at version 1.` Line 59: `zwlr_virtual_pointer_manager_v1 v2`. That is the gate. The project continues. + +### (a) + +**The log does not prove "a warp onto an unfocused window delivered `wl_keyboard.enter`."** That sentence is the natural reading of the README's annotation "focus, one warp late" (`tests/README-keyboard-probe.md:129`) and of the commit message, which hangs both results on "warping into the margin that belongs to the first alone." The warp into that margin is (a1). It did not deliver keyboard enter. + +What the log actually contains, in order: + +``` +108| (a1) one warp after 0.8s of stillness +109| (a1) -> wl_pointer.enter surface=kb-probe-a at 13,7 +110| (a2) a second warp, immediately, still inside the same window +111| (a2) -> modifiers depressed=0 latched=0 locked=0 group=0 +112| (a2) -> leave surface=kb-probe-b +113| (a2) -> enter surface=kb-probe-a serial=371 keys=[] +117| a1_enter=no a2_enter=yes pointer_reached_kb-probe-a=yes +``` + +(a1) is the warp onto unfocused `kb-probe-a`. The only event in its bucket is `wl_pointer.enter` at 13,7, which is the chosen point: target `0.0100,0.0100` (log 107) on a 1280×720 output is about (12.8, 7.2), and B's box starts at 120,80 (log 105), so the point is inside A only. No `enter surface=kb-probe-a` keyboard line in that bucket. `a1_enter=no` is true, and the `startswith` test (`keyboard_probe.py:820-825`) is what keeps `wl_pointer.enter` from counting. Map-time focus was B (log 89–90 and 106), so this is not the one-window false pass. + +The keyboard `leave`/`enter` are the next bucket. That bucket is the second `motion_absolute` (`keyboard_probe.py:816`: same x, y plus 0.004), sent while the pointer was already on A. There is no second `wl_pointer.enter`, because the probe does not listen for `wl_pointer.motion` and pointer focus did not change. So the leave/enter arrived on the motion *after* the warp onto the window, not on the warp onto the window. + +The sentence the log supports is: an idle `motion_absolute` onto unfocused `kb-probe-a` delivered `wl_pointer.enter` and no `wl_keyboard.enter`; `wl_keyboard.leave` of B and `wl_keyboard.enter` of A (serial 371, `keys=[]`) were observed only in the settle window after a later `motion_absolute` that stayed inside A. + +Line 118's narrower claim — "one idle warp did NOT deliver enter; the SECOND warp did" — matches the buckets, with two caveats the file does not write down. The second request is not "immediate": `question_focus` pumps `SETTLE_S` (0.4 s, `keyboard_probe.py:124` and `:812`) and prints the (a1) lines before sending it, and the banner hardcodes the word (`:815`). And it is not a repeat of the same point. In the v0.56.2 `InputManager.cpp` on this machine, `mouseMoveUnified` returns immediately when the floored pixel did not change (`:239-240`), *before* it adds to `m_mousePosDelta` (`:253-256`). Keyboard focus is that delta compared with `follow_mouse_threshold` (`:711-715`). Log 98 says the threshold is 0 and unset, so any non-zero floored distance inside 0.5 s focuses, and a second warp to the same floored pixel does nothing. 0.004 of 720 px is about 3 px, so this nudge cleared that bar. The log never prints the second point, so a reader cannot see that it moved. + +`pointer acquire` is one `_warp` (`src/hhstreamd/manager.py:1620`). The consequence that the first key of a lease can hit whatever was already focused follows from (a1) alone, and (a1) supports it. It does not follow from "the landing warp delivered enter, one warp late." + +The README excerpt is not the log. It claims a verbatim transcript (`README-keyboard-probe.md:90-91`) and then prints `serial=336` (`:129`). This run's (a2) enter is serial 371 (log 113). Setup enters are 357 and 365 (log 84, 90), so 336 cannot be this run's focus change. The excerpt also drops log 111 (a `modifiers` line *before* `leave`) and the two `configured` lines that follow the enter (log 115–116). "Reproduced across six runs" (`README:89`) has one transcript. + +### (b) + +**No release: the log shows it. Mask not cleared: the log does not show what that sentence means.** + +``` +127| spare -> uploaded keymap format=1 size=35572 +128| release_on_destroy=no mask_cleared=no +131| cleanup -> uploaded keymap format=1 size=35572 +132| cleanup -> key code=30 state=0 sym=a +133| cleanup -> modifiers depressed=0 latched=0 locked=0 group=0 +``` + +There is no `after destroy ->` line. The post-destroy pump is 1.0 s (`keyboard_probe.py:915-916`) and it recorded nothing: no `key code=30 state=0`, no `modifiers`. The script did not send a key-up or a `modifiers` before `destroy` (`:912`). The release it did send is after the verdict, labeled `cleanup ->`. B1's named false pass (counting step 7, or releasing before destroy) is not this log. + +The spare keyboard does not weaken the "no release" half. It is created so the seat still has a keyboard (`:904-910`). Log 78–79 show why that matters: capabilities go `1` (pointer) then `3` (pointer|keyboard) only once a virtual keyboard exists, and the seat has no libinput keyboard. The spare never pressed code 30 — its only line is the local `uploaded keymap`. `shareKeyFromAllKBs` swallows a release only when some *other* sharing keyboard still has that code down (`InputManager.cpp:1891-1911`). The spare did not. Silence here is not "the release was delivered to a keyboard we stopped listening on." + +The stronger evidence is log 132, which the ANSWER paragraph does not cite. `onKeyboardKey` drops a release whose code is not in the seat `m_pressed` (`InputManager.cpp:1669-1670`). A `state=0` for code 30 from a *new* keyboard means 30 was still in that set after `destroy`. If destroy had released it, the cleanup up would have been dropped and the client would not have seen `state=0`. + +`mask_cleared=no` is a different predicate than the README's sentence. The code sets it when the post-destroy bucket contains `modifiers depressed=0` (`keyboard_probe.py:918-919`). The bucket is empty, so the flag is `no`. The depressed mask was already 0: the last modifiers lines are log 111 and 114, and the probe never sent `modifiers` with a non-zero mask. The held key is `KEY_A` (30), not Shift. "Destroy did not emit a modifiers event" is what was measured. "A non-zero mask survived destroy" was not. `releasePressed` emits key-ups only (`VirtualKeyboard.cpp:125-135`), so the source still says a mask would survive, but this run is not that measurement. Log 99 supports the option half only: `input:virtualkeyboard:release_pressed_on_close` is `{"int": 0, … "set": false}`. + +The Shift story (`README:156-161`, `keys=[42, 0, 0, 0]`) is not in this transcript. Every `enter` here has `keys=[]` (log 84, 90, 113). Do not treat the zeros, or the claim that a key outlived the process, as data from this file. + +The ANSWER's `kill -9` sentence is an inference. The transcript is an explicit `destroy` request. In this tree both that request and client disconnect call the same `CVirtualKeyboardV1Resource::destroy` (`VirtualKeyboard.cpp:38-39`, `:137-140`), which consults the option. Fair inference, not a second experiment. + +### (c) + +**The log shows exactly one press, and neither the spare, the window, nor `repeat_info` weakens that count.** + +``` +82| setup -> repeat_info rate=25 delay=600 +121| key code=30 state=1 sym=a +122| press_count=1 repeat_info=(25, 600) +``` + +`press_count` counts `state=1` or `state=2` for code 30 inside the hold pump (`keyboard_probe.py:875-879`). One line, state 1, no state 2. The hold is `REPEAT_HOLD_S = 1.5` (`:120`), which is longer than the 600 ms delay on log 101, not shorter. A compositor that repeated at 25 Hz after 600 ms would have put on the order of twenty more `key` lines in the remaining 0.9 s. It put none. `repeat_info` was delivered at bind time (log 82), before the hold, which is when Hyprland sends it; printing the stored tuple next to the count is what B1 asked. It does not mean the compositor also repeated. The spare keyboard is created in `question_destroy`, after this section, so it is not in the (c) setup. The ANSWER text (log 123) already refuses the false pass: `press_count=1` is not "a text field will not flood." That part of the file is right, and it is the reading Stage 1 should keep. + +`sym=a` is from the forwarded keymap, not a table. Log 80–81: uploaded `format=1 size=35572`, and `wl_keyboard.keymap format=1 bytes=35572 symbols=xkb_symbols "pc_us_inet(evdev)"`. The sizes match, which is consistent with the NUL-inclusive memfd (`keyboard_probe.py:312-326`) being what the compositor mapped. The symbols snippet is not the layout string `us`. + +## Defects + +1. **High. The (a) write-up states a causality the log does not have.** README `:114` and `:129`, and the `19e484b` message, read as "warping onto the unfocused window delivered keyboard enter, one warp late." Log 108–113 say the landing warp delivered `wl_pointer.enter` only, and leave/enter came on the next motion. "One warp late" is the wrong mechanism: the first warp's delta is set to 0 (`InputManager.cpp:255-256`); the enter belongs to the second motion's non-zero delta, not to a delayed effect of the first. Cheapest fix: replace the README excerpt with log 108–117 unchanged, and replace the annotation with the sentence in the (a) section above. Do not leave `serial=336` in the file. + +2. **High. `d07a1fd` did not fold the eight changes into the plan.** `git diff 14b3f69 HEAD -- docs/plans/2026-10-03-keyboard-input.md` is empty. The commit adds `docs/plans/2026-10-04-keyboard-verification.md` and nothing else. The commit message is an accurate list of what that review says, and the review text itself is not softened. The plan text is unchanged, so anyone told to follow the plan (the untracked brief says that, and it repeats exit codes 8/9/2/10) still has the contradicted text. Cheapest fix: a banner at the top of `2026-10-03-keyboard-input.md` stating that the eight rows in the verification doc's "Changes required before code" table supersede the plan where they differ. Not done here. + +3. **Medium. `mask_cleared=no` is reported as a measurement of a held mask.** README `:150-154`. The mask was 0 the whole time (log 111, 114; no `modifiers` request before destroy). Cheapest fix: one sentence in the README — destroy emitted no key-up and no modifiers event; a non-zero mask was not held, so this run does not show one surviving. Do not re-run unless Stage 2 wants a transcript of Shift specifically. Do not cite the unlogged `keys=[42, 0, 0, 0]` run. + +4. **Medium. "A second warp" is underspecified in a way Stage 3 will copy.** The report never says the second point differed, and the same floored pixel returns before the focus test (`InputManager.cpp:239-240`). Cheapest fix: in the README, say (a2) moved about 3 px and that a second `motion_absolute` of the same point is not this result. Printing the second normalised point from `question_focus` would make the next transcript show it. + +5. **Low. "Immediately" is hardcoded, and the gap is not logged.** 0.4 s plus the time to print (a1) is still under Hyprland's 0.5 s window, and the fact that (a2) focused is consistent with that. The word in log 110 is not a measurement. Cheapest fix: print the monotonic gap between the two `motion_absolute` calls. Not worth a re-run by itself. + +6. **Low. Claims with no transcript.** "Six runs" (README `:89`) and the Shift enter (README `:156-161`). Cheapest fix: delete both, or attach the log. The committed transcript does not contain them. + +Not defects: committing the probe (B1 said not to; the commissioning brief said to; the README says so); uploading the keymap before (a) (log 78–80: no keyboard capability until a virtual keyboard exists, so the listener could not have seen enter otherwise); idle 0.8 s instead of 0.6 s; fullscreen A so the two boxes are not the same 1040×560 (log 104–105 shows they were not); the spare keyboard, for the reason under (b). + +## What Stage 1 must not build on + +- **Do not assert `wl_keyboard.enter` on `pointer acquire`.** Acquire is one warp. (a1) did not enter. Stage 3's enter subtest stays red until a later motion that changes the floored pixel, or `focuswindow`. Do not "fix" it by warping twice to the same bookmark. +- **Do not read "one warp late" as "the enter is delayed, so wait longer."** The (a1) bucket was 0.4 s and contained the pointer enter. The keyboard enter was a different request. +- **Do not gate the `keyboard down` warning on this probe having seen repeats.** It saw one `wl_keyboard.key` and a `repeat_info` of 25/600. The warning stays unconditional. Log 123 already says this; the plan at `2026-10-03-keyboard-input.md:234` still says the opposite ("if it does, the help text says so"). +- **Do not cite `mask_cleared=no` as proof a held Shift survives `destroy`.** Keep sending `modifiers(0,0,0,0)` because `releasePressed` never emits modifiers, not because this log held a mask. +- **Do not treat `keys=[42, 0, 0, 0]` as a measured poison.** This transcript's enters are `keys=[]`. The cleanup `state=0` (log 132) is the poison evidence, and it is for code 30 after an explicit `destroy`. +- **Do not expect the scanner to emit `keymap_format` or `key_state`.** The Hyprland XML this probe used names both and defines neither (`protocols/virtual-keyboard-unstable-v1.xml` in the v0.56.2 tree: the request text says "keymap_format enumeration" / "key_state enumeration"; the only enums in the file are `error`). The constants in `keyboard_probe.py:89-95` are the right workaround. The symbols line to match later is `xkb_symbols "pc_us_inet(evdev)"`, not the bare layout name. +- **Do not implement exit 2, the NUL, or the layout path from the 2026-10-03 plan text.** Those paragraphs were not updated. See carried objections. + +## Carried objections + +`d07a1fd` preserved the eight pre-code changes intact inside the verification doc and dropped them from the plan. Nothing in the eight was rewritten into something unimplementable. Where the plan still disagrees: + +| # | Still binding, from the verification doc `:192-201` | Plan text that was not changed | +| --- | --- | --- | +| 1 | Broker checks shape and the 4096 cap. A driver token for a bad keysym or character maps to `invalid_argument` (exit 2). Missing global stays `driver_refused` (exit 10). | `:61` still says exit 2 for a bad keysym, which `_drive` turns into 10. | +| 2 | Keymap `size` includes the trailing NUL. `format = 1`. `time` is `_now_ms()`. | `:25` still says "memfd of an XKB text keymap" and never says `size == strlen + 1`. | +| 3 | `release_all` no-ops its key half when no virtual keyboard exists, and ends with `modifiers(0,0,0,0)` when a mask was touched. Also one `modifiers(0,…)` after the initial upload. | Not stated. | +| 4 | `input:virtualkeyboard:release_pressed_on_close = true` in `nix/hyprland-conf.nix`. The true setting still does not clear the mask. | `:233` still calls destroy-while-held unverified and does not set the option. This run confirms the default is 0 and that explicit destroy releases nothing. | +| 5 | Layout is `--xkb-layout` on the pointer unit. The driver rejects `,` before `xkb_keymap_new_from_names`. A `[keyboard]` table in the broker TOML is not the upload. | `:111`, `:115`, `:176`, `:208` still emit and test `[keyboard]` the way `[pointer]` is emitted. | +| 6 | The modifier-keysym set is written down. The resolver returns `(evdev, mask)` for any level. `key` / `type` do not call `_aimed()`. | `:189` still has the mask-vs-Shift decision and no keysym set. | +| 7 | Stage 0 expectations as B1 wrote them. `keyboard down` warns unconditionally. Two windows, or the enter result is a false pass. | `:234` and `:253` are still the vague originals. The probe did use two windows; the unconditional warning is the right reading of (c). | +| 8 | Acquire's stderr says keyboard verbs refresh the TTL. `Rejected` text and driver logs carry an index, not the string. | Not stated. | + +Objection 4 of the verification doc (do not vendor Hyprland's XML; use wayland-protocols `unstable/virtual-keyboard/…`) is the one item this stage showed is not implementable on this nixpkgs. The protocol's wayland-protocols MR never landed; the file the review names is not where the README looked, and the Hyprland copy is the one the probe compiled. Carry the review's actual reason — the copy does not define the enums — not the path. Switching later, if a nixpkgs grows the file, is a one-line change and does not move the integers. + +Unchanged and confirmed, so Stage 1 should not reopen them: `zwp_virtual_keyboard_v1` version 1 on the running compositor; no `wp_virtual_keyboard_v1`; one idle warp does not move keyboard focus under `follow_mouse = 1` and threshold 0; do not build `dispatch focuswindow` in Stage 1. + +Stage 1: implement from the eight rows in `docs/plans/2026-10-04-keyboard-verification.md`, not from the unedited 2026-10-03 plan; do not assert `wl_keyboard.enter` on acquire's single warp, do not treat a second warp to the same point as the fix, and do not cite `mask_cleared=no` as a held-mask result. diff --git a/docs/reviews/2026-10-04-stage1-review.md b/docs/reviews/2026-10-04-stage1-review.md new file mode 100644 index 0000000..9e8e476 --- /dev/null +++ b/docs/reviews/2026-10-04-stage1-review.md @@ -0,0 +1,178 @@ +# Stage 1 review — the driver learns to type + +Reviewed `f931858` only (keymap, vendored `zwp_virtual_keyboard_v1`, ops, backend upload, `__main__` flags, the pointer-side lease mirror, and `tests/pointer/`). Uncommitted edits under `src/hhstreamd/`, `src/hhstream_session/`, `nix/module.nix` and `nix/hyprland-conf.nix` are not this commit and were not reviewed. `b1f2744`, which lands after `f931858` and only edits the plan and the Stage 0 write-up, was not reviewed either. + +The suite was not re-run. The resolver and the dispatcher were executed against the installed libxkbcommon 1.13.2 (python-xkbcommon 1.5.1) for `us` and `de`. Line numbers below are `f931858`. + +## Verdict + +**Yes-with-fixes.** `type` of `A` on `us` is the worked example, and it is not a Shift special case: the same path sends level 3 for `de` `@`. The uploaded text is a real XKB keymap (`xkb_symbols "pc_us_inet(evdev)"`, TEXT_V1), and its NUL-inclusive size for `us`/`pc105` is 35572, the same number Stage 0 logged. The layout is `--xkb-layout` (default `us`), not a hardcoded string. Nothing in this commit treats `pointer acquire`'s one warp as keyboard focus. + +Two things are wrong enough that Stage 2 will encode them if it starts from this tree. `key` throws away the mask the resolver just computed, so `keyboard key A` types `a`. And the shutdown comment says `nix/hyprland-conf.nix` sets `input:virtualkeyboard:release_pressed_on_close`, which this commit does not do. + +## Findings + +1. **High. `key` drops `action.mask`, so any keysym above level 0 is sent as the bare key.** `keymap.py` `resolve_name("A")` returns `(code=30, mask=1)` and `resolve_text("@")` on `de` returns `(code=16, mask=128)`, which is `ISO_Level3_Shift`'s bit, not Shift. `_op_type` uses that mask (`ops.py:315`, mask before the down/up, restored after). `_op_key` does not. On down it sends `action.code` and then, only if `is_modifier(name)`, `modifier_mask` (`ops.py:261-266`). `A` and `at` are not modifiers, so the calls are `key(30, pressed)` and `key(16, pressed)` with no `modifiers` at all. Confirmed by running the dispatcher: `{"op":"key","key":"A"}` produces `[("key", 30, 1)]`; `{"op":"key","key":"at"}` on `de` produces `[("key", 16, 1)]`. The plan's `NAME` list includes `A` (`2026-10-03-keyboard-input.md` CLI block). Stage 2's `keyboard key` / `down` / `up` as a thin wrapper of this op will type the level-0 character. Stage 3's `keyboard type` assertion stays green while that is true, because `type` is the path that was tested (`tests/pointer/test_ops.py:513-527`). + + The same hole aliases two names onto one evdev code. `down A` then `down a` records both names and sends `key(30, pressed)` twice. Hyprland drops the second press (`m_pressed` already contains 30). `release_all` then emits two ups of 30 (`ops.py:351-352`); the second is dropped because the code is already up. The seat survives. The held set lied the whole time. + + Cheapest fix: in `_op_key`, if `action.mask` is non-zero, send `modifiers(baseline | action.mask)` *before* the down and restore the baseline on the matching up — the one-character `type` sequence — and refuse a second held name whose evdev code is already down, `kind=invalid_argument`. Do not store `action.mask` in `_keys` as the contribution: that field means "what this key adds", and `type` treats a zero contribution as "non-modifier, refuse". `Shift_L` must stay key-then-mask; the tests at `test_ops.py:481-486` lock that order, and it is the other path on purpose. + +2. **High. The comment says Hyprland releases keys on destroy. The conf file does not.** `__main__.py:186-193` says SIGKILL is safe because `nix/hyprland-conf.nix` sets `input:virtualkeyboard:release_pressed_on_close`. In `f931858` that file's `input` block is `follow_mouse = 1` and nothing else (`nix/hyprland-conf.nix:81-94`). The verification's change 4 was "required before code" because the default is 0 and `releasePressed` emits key-ups only when the option is true: a `kill -9` leaves the code in the seat's `m_pressed`, and the next driver's down of that code is ignored. The clean path is fine — `_lift_everything` calls `release_all`, and `release_all` does send the ups and, when a mask was touched, `modifiers(0,0,0,0)`. The comment describes the path the option exists for, and the option is not there. + + Cheapest fix: one line in `nix/hyprland-conf.nix`, `input:virtualkeyboard:release_pressed_on_close = true`, plus the sentence the verification asked for (the true setting still does not clear a mask, which is why `modifiers(0,…)` stays). Delete the claim from `__main__.py` until the line exists. This is not optional follow-up: it is the difference between a killed driver and a key that stays dead. + +3. **Medium. The upload is right, and no test would notice if it stopped being right.** `WaylandSink.upload_keymap` (`backend.py:209-253`) creates one keyboard, writes `text.encode("utf-8") + b"\0"`, passes `format=XKB_V1` (1) and `len(payload)`, `_sync()`s, and only then `os.close`s the fd. python-xkbcommon 1.5.1's `get_as_bytes` defaults to `XKB_KEYMAP_FORMAT_TEXT_V1` and `ffi.string` strips the NUL, so the extra byte is exactly one terminator, not two. For `us`/`pc105` that size is 35572. `__main__.py:155-173` calls it once, after `connect`, and returns exit 10 on `CompositorUnavailable` *before* `listen`. `type` never calls it. + + Nothing asserts any of that. `test_the_keymap_object_is_built_once_and_reused_across_types` (`test_keymap.py:279-293`) checks `dispatcher._keymap is us`. The sink has no `keymap` method. The verification named this false pass: a backend that uploads on every `type` stays green. `test_a_usable_layout_gets_as_far_as_the_compositor` (`test_driver_flags.py:128-138`) raises at `connect`, so upload, the NUL, format 1, and "before listen" are never reached. A `main` that connects and listens without uploading passes every test in the tree. `test_the_backend_binds_the_keyboard_manager_at_version_1_and_survives_its_absence` (`test_vendored_protocol.py:179-187`) constructs an unconnected `WaylandSink` and checks the flag is false. A `connect` that `ManagerTooOld`s when the keyboard global is missing stays green. + + Cheapest fix: one test with a sink whose `connect` succeeds and whose `upload_keymap` records `(text, caller)`. Assert `main` calls it once, with a payload whose last byte is NUL and whose length is `len(text.encode()) + 1`, and that `serve` is what runs next — inject `listen` so it does not need a socket. A second test calls `upload_keymap` on a fake keyboard object and asserts `keymap(1, fd, size)` sees `size == len(payload)` while `fd` still reads back the bytes. Do not assert only that `keymap.py` returns equal strings. + +4. **Low. `key` up forgets the name before the send, unlike `button`.** `_op_key` pops `_keys` and then calls `sink.key` (`ops.py:275-276`). `_op_button` updates `_pressed` only after the send (`ops.py:198-203`). A raise from the up — `KeyboardUnavailable` is caught in `__main__.py:211-214` and the process stays up — leaves `_keys` empty while the compositor still has the code down. `release_all` will not repeat the up. Confirmed with a sink that raises on `state=0`: after a failed `Shift_L` up the held set is `[]` and `_mask_touched` is still true, so the next `release_all` sends `modifiers(0,…)` and no key-up. Not reachable today unless the keyboard object disappears between down and up (`close` is the only thing that clears it, and it runs after the lift). Cheapest fix: pop after a successful send, same order as the button. + +5. **Low. Two layouts xkbcommon accepts are not the layout the caller named.** `CONTROL_KEYSYMS` maps `\r` to `Return` (`keymap.py:67`). The plan's C0 rule exempts `\n` and `\t` only; `\r` is a `Return` and not a refusal. And `build(layout="")` does not raise: xkbcommon compiles it as `xkb_symbols "pc_us_inet(evdev)"`, the same keymap as `us`. A hand-run `--xkb-layout ''` looks configured. The comma check (`keymap.py:144-153`) is the right idea and does not cover this. Cheapest fix: drop `\r` from `CONTROL_KEYSYMS`, and reject an empty layout in `build()` next to the comma check. + +Not defects, checked because they look like them: + +- **Shift is not hardcoded.** `A` on `us` is evdev 30 and mask `1 << mod_get_index("Shift")` (index 0, so 1). `de` `@` is evdev 16 and mask 128, equal to `modifier_mask("ISO_Level3_Shift")`, not equal to Shift. `type "@"` emits `modifiers(128), key(16, down), key(16, up), modifiers(0,…)` and no code 42. Control's contribution is 4 (index 2). The measured modifier set on `us`/`pc105` is exactly `EXPECTED_MODIFIERS`; Meta and Hyper are absent because no key produces them. Locks are `Caps_Lock` and `Num_Lock`, and `type` while either is held emits nothing. +- **Unmappable means no events.** `resolve_text("xéy")` raises `UnknownKey` with `scalar 1 (U+00E9)` and neither the character nor the string. The dispatcher calls `resolve_text` before any sink call (`ops.py:310-311`). `é`, a C0 other than the two (and `\r`) exemptions, a dead keysym, and 4097 scalars are the same shape. +- **The 4096 cap counts scalars.** `len(str)` is what `resolve_text` compares (`keymap.py:335-338`). 4096 copies of `😀` miss the cap and fail on scalar 0; a byte cap would have said "limit". +- **Degraded mode is the reachable one.** A missing manager makes `upload_keymap` return before `create_virtual_keyboard` (`backend.py:221-226`). `has_keyboard()` stays false. `key` / `type` answer `kind: refused` (`ops.py:391-396`). `release_all` sends key-ups only when `_keys` is non-empty and `modifiers(0,…)` only when `_mask_touched` (`ops.py:347-361`). Both stay empty if no keyboard op ever succeeded, so the button half still runs. The test uses a real `us` keymap plus a sink with no keyboard (`test_ops.py:703-723`), which is how the process actually starts: the keymap is compiled before connect (`__main__.py:132-138`) even when the global is absent. +- **No keyboard `frame`, no `_aimed()` on `key` or `type`, no `touch`.** `frame` remains the pointer op. `release_all` still frames pointer outputs and does not add one for keys (`ops.py:343-344`, locked by `test_ops.py:667-683`). There is no `touch` in the driver. This commit does not add broker verbs, so it does not add any to the mutation set either. +- **The driver token exists, on the driver reply only.** A bad keysym, an unmappable scalar, a bad `state`, and a string over the cap are `{"ok": false, "kind": "invalid_argument"}` (`ops.py:112-117`, `159-160`, `413-425`). A missing keyboard is `kind: "refused"`. A bad layout is process exit 2 *before* `WaylandSink` is constructed (`__main__.py:132-141`, `keymap.py:144-153`). Upload failure is exit 10 and does not `listen` (`__main__.py:155-164`). The committed broker does not read `kind`. That is the next section, not a second copy of this one. +- **Focus.** No Stage 1 path warps to deliver `wl_keyboard.enter`, warps twice, or calls `dispatch focuswindow`. `type` with no prior warp emits keys (`test_ops.py:420-432`). `pointer acquire` is still one `_warp`. The Stage 0 misreading was not built on. + +## Tests + +Dispatcher tests record tuples. They cannot see Wayland `time`, the keymap fd, or `format`. That seam is fine for ops and blind for the upload. Per test, what a pass requires, and where a pass is a lie: + +`tests/pointer/test_keymap.py` (real xkbcommon, not a stub): + +| Test | Passes only if | False pass | +| --- | --- | --- | +| `test_a_lower_case_letter_…` | `resolve_name("a")` is `(30, 0)` | Asserting the XKB code 38 would be the lie; this one asserts 30 | +| `test_a_capital_is_the_same_code_with_shift_in_the_mask` | code 30 and mask `== 1 << mod_get_index("Shift")`, and the code is not 42 | Hardcoding mask `1` is what this test refuses. It does not run `type` | +| `test_shift_is_a_key_in_its_own_right_…` | `Shift_L` is `(42, 0)` and `modifier_mask` equals that Shift bit | | +| `test_a_named_keysym_resolves_…` | `Return` 28, `Tab` 15, `BackSpace` 14, `Left` 105 | The mask is not checked. All four are level 0 on `us`, so a resolver that always returns mask 0 passes | +| `test_the_two_allowed_control_characters_…` | `\n` and `\t` are `Return` / `Tab`, mask 0 | Does not notice that `\r` is also `Return` | +| `test_an_empty_string_…` | `resolve_text("") == []` | | +| `test_a_character_this_layout_cannot_produce_…` | `UnknownKey`, message contains `scalar 0`, and the character is not in the message | A message that quoted `é` fails this. Logging the string elsewhere would not | +| `test_the_refusal_names_the_index_…` | `"abcé"` says `scalar 3` and not `é` | | +| `test_a_dead_keysym_is_refused_by_name` | `dead_acute` raises and the message contains `dead key` | The prefix check refuses the name even when it is not on the layout. The test does not prove a layout that *has* the key still refuses it; `us` does not have it | +| `test_an_unknown_keysym_name_…` | `NoSuchKeysymAtAll` raises `UnknownKey` | | +| `test_a_comma_separated_layout_…` | `build("us,ru")` raises `KeymapError` and the message contains `group` | Compiling the two-group keymap and *then* raising still passes. The user-visible failure (nothing uploaded) is the same | +| `test_a_layout_xkbcommon_rejects_…` | `zzz-no-such-layout` raises and the name is in the message | xkbcommon does reject it (NULL, not a silent `us`). Empty string is the case this does not cover: it compiles as `us` | +| `test_the_cap_is_exactly_at_the_limit` | 4096 `a`s resolve | | +| `test_one_scalar_over_the_cap_…` | 4097 raises and the message names 4096 | No sink. The dispatcher twin covers "zero calls" | +| `test_the_cap_counts_scalars_and_not_bytes` | 4096 emoji (`len == 4096`, UTF-8 longer) raises `scalar 0` and the message does not contain `limit` | An ASCII-only cap test would not tell a byte cap from a scalar cap. This one does | +| `test_the_modifier_set_is_measured_…` | `modifier_names() == EXPECTED_MODIFIERS` | An empty set fails. It does not fail a set that matches the constant and was then hardcoded — the constant is what `us`/`pc105` measures, which is the point of the constant | +| `test_a_lock_is_not_a_modifier` | locks are exactly `{Caps_Lock, Num_Lock}`, none of them modifiers | | +| `test_control_contributes_a_mask_that_is_not_shifts` | Control's mask is neither 0 nor Shift | **Alt's bit passes.** Nothing asks `mod_get_index("Control")`. The wire tests compare against `modifier_mask(...)`, so a consistently wrong bit stays green. Measured here: index 2, mask 4. The test does not lock that | +| `test_de_swaps_y_and_z_…` | `us` y/z are 21/44, `de` is 44/21 | A table beside the keymap that always returns the `us` codes fails | +| `test_on_de_the_at_sign_…` | `us` `@` has Shift's mask; `de` `@` is neither 0 nor Shift, and equals `modifier_mask("ISO_Level3_Shift")` | The two sides use different xkbcommon calls (level lookup vs a pressed key). Both are 128. A Shift special case for letters only would still pass, which is why the `de` case exists | +| `test_a_character_us_cannot_type_is_ordinary_on_de` | `ü` raises on `us`; on `de` it is `udiaeresis`, mask 0 | | +| `test_the_keymap_text_is_an_xkb_keymap_naming_its_layout` | text starts with `xkb_keymap {`; the `xkb_symbols` line contains `us` or `de` | `"us" in "pc_us_inet(evdev)"` is true of every `us`-family map. The `de` line is what fails if the layout argument is ignored. It does not require the symbols name `pc_de_inet(evdev)`, which is what the VM grep should match. Actual lines: `xkb_symbols "pc_us_inet(evdev)"` and `xkb_symbols "pc_de_inet(evdev)"` | +| `test_an_unmappable_character_emits_nothing_through_the_dispatcher` | `type "abcé"` is `ok: false`, `kind == invalid_argument`, `sink.calls == []` | "No event carried `é`" would pass with `a` and `b` typed. This assertion would not | +| `test_a_string_over_the_cap_emits_nothing_…` | 4097 `a`s, same three checks | | +| `test_the_keymap_object_is_built_once_…` | two `type`s leave `dispatcher._keymap` as the same object | **The false pass the verification named.** Re-uploading per string never calls this object twice and stays green | + +`tests/pointer/test_ops.py`, new cases. All of them talk to `RecordingSink`, which writes down whatever it was told. A pass means the dispatcher passed those tuples, not that `zwp_virtual_keyboard_v1.key` was marshalled. + +| Test | Passes only if | False pass | +| --- | --- | --- | +| `test_the_contracts_ops_are_exactly_what_is_implemented` | `Dispatcher._ops` equals a set literal that includes `key` and `type` and not `release_all_keys` | The docstring says the contract. The test never opens `CONTRACT-sessions.md`. §3.4 still lists neither op, and this stays green | +| `test_key_down_sends_the_code_and_lists_the_name` | `key down Return` → `[("key", 28, 1)]` and `pressed` says `["Return"]` | | +| `test_key_needs_no_warp` | `type "Hi"` and `key a` both `ok` on a dispatcher that never warped, and some call is `key(30, down)` | The `in sink.calls` check is weak (`H` is not code 30; the explicit `key a` supplies it). `ok is True` on `type "Hi"` is the real assertion, and a call to `_aimed()` fails it. Not a false pass of the aim rule | +| `test_a_key_is_not_tagged_with_an_output_…` | after a warp, `key a` is exactly `[("key", 30, 1)]` | A sink that accepted an output argument and ignored it would still look like this, because the dispatcher never passes one. That is what the arity assertion is for | +| `test_key_up_forgets_the_key` | down then up is down, up, and `lifted == ["a"]` | | +| `test_up_of_a_key_that_was_never_down_…` | `ok`, `lifted == []`, no sink calls | | +| `test_keys_are_reported_oldest_first` | `pressed` names are `Control_L`, `Shift_L`, `a` | Does not look at the sink, so a modifier down that forgot the mask still passes | +| `test_a_modifier_down_sends_the_key_and_the_mask` | `Shift_L` down is key 42 then `modifiers(mask, 0, 0, 0)` | | +| `test_a_modifier_up_restores_the_mask_…` | releasing Shift while Control is held sends key-up 42 then Control's mask, not zero | | +| `test_an_ordinary_key_down_sends_no_mask` | `key a` is exactly one key call | This is also why `key A` has no test. The ordinary-key assertion is what a capital would satisfy, wrongly | +| `test_type_of_a_capital_is_the_mask_and_not_a_shift_keycode` | exactly `modifiers(shift), key(30,1), key(30,0), modifiers(0,0,0,0)`, and no code 42 | "Some call had code 30" would be the lie. This list is the worked example. It uses `modifier_mask("Shift_L")`, which on this keymap is 1 | +| `test_type_leaves_no_key_held` | `type "Hello"` leaves `pressed` keys empty | Does not look at the sink | +| `test_type_emits_a_down_up_pair_per_character` | the key calls for `"ab"` are 30 and 48, down/up each | **Filters to `key` calls.** Omitting every `modifiers` stays green. The capital test is what locks the mask | +| `test_type_of_an_empty_string_…` | `ok`, no calls | | +| `test_type_ors_an_explicitly_held_modifier_…` | `down Control_L` then `type c` is `modifiers(control)`, key down/up of `c`'s code, `modifiers(control)` again; `pressed` is still `["Control_L"]`; no key 29 | Full sequence. Not a false pass | +| `test_type_of_a_capital_under_a_held_control_…` | first call is `modifiers(control\|shift)`, last is `modifiers(control)` | **`modifiers(both)` then `modifiers(control)` with no key events passes.** The key, and "no second Control down", are not in the assertion | +| `test_type_while_a_non_modifier_is_held_…` | `ok: false`, `kind` invalid, no new calls, `a` still held | | +| `test_type_while_a_lock_is_held_…` | `Caps_Lock` held, `type a` is `ok: false`, no new calls | Does not check `kind`. A `refused` (exit 10) passes | +| `test_a_string_that_fails_on_its_third_character_…` | `"abé"` is `ok: false` and `calls == []` | Same strength as the keymap twin. Does not check `kind` | +| `test_a_bad_character_is_a_usage_error_and_a_missing_keyboard_is_not` | `é`, `Nope`, and `state=sideways` are `invalid_argument`; the same `type a` on `KeyboardlessSink` is `refused` | This is the token. It does not check that anything maps the token to exit 2. Nothing in `f931858` does | +| `test_without_a_keymap_at_all_…` | `Dispatcher(sink, None)` still warps and buttons; `type` is `refused` | | +| `test_release_all_lifts_keys_in_press_order_then_zeroes_the_mask` | `Control_L` then `a` lifts 29, then 30, then `modifiers(0,0,0,0)` | | +| `test_release_all_lifts_keys_after_buttons_and_adds_no_keyboard_frame` | button up, one pointer `frame`, key up 42, `modifiers(0,…)` | Locks the frame *before* the key-up. The plan's step list puts the pointer frames last. Buttons and keys are different objects; the frame does not gate the key. Not a false pass, and not worth reordering unless a client is shown to care | +| `test_release_all_lifts_keys_even_after_a_warp_to_another_output` | after a warp to another output, the only call is `key(30, up)` | A plain `a` never touched the mask, so the absent `modifiers` is correct (`_mask_touched` is false). A sink that ignored an output argument cannot fake this: the call has no output slot | +| `test_release_all_without_a_keyboard_still_lifts_buttons` | keymap present, `has_keyboard` false, a held button: `lifted == ["left"]`, `lifted_keys == []`, and the calls are button up plus frame | `KeyboardlessSink.key` raises. If the key half ran, the test errors rather than passes. It does not hold a key, which is the only degraded state the process can reach | +| `test_release_all_after_a_type_zeroes_the_mask_once_more` | after `type A`, `release_all` is exactly one `modifiers(0,0,0,0)` | `_mask_touched` stays true after `type` restores the baseline. A `type` that never sent a non-zero mask would not take this branch; `type a` is not this test | + +`tests/pointer/test_driver_flags.py`: + +| Test | Passes only if | False pass | +| --- | --- | --- | +| `test_the_xkb_flags_default_to_the_frozen_values` | `parse_args([])` is `us` / `pc105` / empty variant / empty options | Parsing only. `main` could ignore them; the refusal tests below are what catch that for a *bad* value | +| `test_the_defaults_are_the_ones_the_module_option_defaults_to` | the two Python constants equal `("us", "pc105")` | **Does not read `nix/module.nix`.** In `f931858` the unit's `ExecStart` is still the two-flag line (`nix/module.nix:986-992`) and there is no `sessions.keyboard` option. The docstring says the module and the binary cannot drift. They are not compared | +| `test_a_layout_is_taken_from_the_flag` | `parse_args(["--xkb-layout", "de"]).xkb_layout == "de"` | Parsing only | +| `test_the_contract_command_line_still_parses` | the §3.4 line plus the four XKB flags parses | The contract text is not read, and it does not yet contain those flags | +| `test_a_comma_separated_layout_exits_2_without_connecting` | `main(["--xkb-layout", "us,ru"])` is exit 2 and `WaylandSink` was never constructed | The injected sink raises if constructed. A connect that happened would fail the test, not pass it | +| `test_a_layout_xkbcommon_rejects_exits_2_without_connecting` | `zzz-no-such-layout` is exit 2, same injection | Ignoring the flag and always compiling `us` would reach `connect` and fail this. The flag is actually wired | +| `test_a_usable_layout_gets_as_far_as_the_compositor` | `main(["--xkb-layout", "us"])` raises `_Unreached("connect")` | Stops at connect. See finding 3 | +| `test_the_exit_codes_match_the_brokers_table` | the three constants are 0, 2, 10 | Does not import `hhstreamd.protocol`. Two copies can diverge and this still passes | + +`tests/pointer/test_lease.py`, the new key cases. They call `press_key` on the lease directly. None of them opens a socket. A pass does not mean a verb updates the mirror; no verb in `f931858` does (`manager.py` never calls `press_key`). + +| Test | Passes only if | False pass | +| --- | --- | --- | +| `test_press_and_lift_one_key` | `press_key` / `keys_pressed` / `unpress_key`, and a later `release` has `keys_lifted == []` | | +| `test_lifting_a_key_that_is_not_down_…` | `unpress_key` of a key not held is `[]` | | +| `test_keys_are_kept_in_press_order` | order is press order, including after one is removed; `release().keys_lifted` is what remained | | +| `test_pressing_a_key_twice_leaves_one_down` | a dict, so the second `press_key` does not duplicate | The driver does not share this dict. A double `key down` still sends two presses; this test cannot see that | +| `test_keys_and_buttons_are_tracked_separately` | `release` reports buttons and keys independently | | +| `test_a_non_holder_cannot_press_a_key` | `LeaseInvalid` for the other session | | +| `test_expire_still_returns_no_key_list_…` | read `keys_pressed()`, then `expire()`; the return has no `keys_lifted` and no `buttons_lifted`; the lease is then empty | `hasattr` fails if someone adds the field to `LeaseInfo`. Widening the return is what this is for | +| `test_expiry_does_not_leak_keys_to_the_next_holder` | after `expire`, the next `acquire` sees no keys | | + +`tests/pointer/test_vendored_protocol.py`, the keyboard cases. The source-text tests pass if the generated file contains the substring, including in a comment. The two `skipif` tests import pywayland and check `hasattr` and `version == 1`, which is a real bind of the generated class, still with no display. + +| Test | Passes only if | False pass | +| --- | --- | --- | +| `test_the_keyboard_protocol_is_vendored_beside_the_pointer_one` | the package exists and every `.py` starts with the scanner banner | | +| `test_the_keyboard_manager_is_version_1_with_the_seat_only_request` | the source contains the interface name, `version = 1`, `create_virtual_keyboard(self, seat: WlSeat)`, and not `WlOutput` | A comment with that signature passes | +| `test_the_keyboard_carries_keymap_key_and_modifiers` | source contains the three signatures, `ArgumentType.FileDescriptor`, and no `def frame(` | Same | +| `test_the_integers_the_xml_names_but_does_not_define_live_in_our_code` | the generated file mentions `keymap_format` and does not define the enum; `XKB_V1 == 1`; `STATES` is 0 and 1 | Does not check that `upload_keymap` passes 1. A call with format 2 stays green | +| `test_the_shim_resolves_the_keyboard_relative_import` | the manager module imports `WlSeat` from `..wayland` | | +| `test_the_keyboard_protocol_binds_against_the_installed_pywayland` | import, name, version 1, and the four requests exist on the proxy | Skipped when pywayland is absent. The package check is what runs in the build | +| `test_the_backend_binds_…_and_survives_its_absence` | `KEYBOARD_MANAGER_VERSION == 1` and an unconnected sink reports no keyboard | See finding 3. It never runs `_on_global` | +| `test_the_backend_refuses_a_version_1_manager` | `ManagerTooOld(1)` mentions version 1 and `create_virtual_pointer_with_output` | This is the *pointer* manager. It says nothing about a keyboard global at the wrong version. `_on_global` binds `KEYBOARD_MANAGER_VERSION` whenever the name matches (`backend.py:362-366`) and does not reject a compositor that advertised something else | + +`tests/pointer/test_pointer_server.py` only grew `keys` / `lifted_keys` in two assertions. A pass means the JSON reply gained those fields. It does not send `key` or `type`. + +## What Stage 2 must not assume + +Three of these, left alone, make Stage 2 wrong. The rest are the same class of mistake at lower cost. + +1. **`{"op":"key","key":"A"}` does not type `A`.** Neither does `at` on `de`, or any other keysym whose producing mask is non-zero. `type` does, and it ORs that mask with the baseline of keys that are actually modifiers. `keyboard key` / `down` / `up` must not be "send the name through unchanged" until finding 1 is fixed, and a VM check that only runs `keyboard type` will not catch it. `a` and `A` are two held names for evdev 30. `Caps_Lock` down sends the key and never a locked mask; `type` then refuses. Do not document Caps as capitalization. + +2. **`kind` does not survive the broker client, and every refusal is exit 10.** `PointerDriver._exchange` raises `DriverRejected` from `reply["error"]` and drops everything else (`src/hhstreamd/driver.py:158-159` at `f931858`). `_drive` maps every `DriverRejected` to `driver_refused` (`manager.py:2047`). A Stage 2 test that asserts exit 2 for `é` fails, or it passes by reading the English. Read `kind` off the JSON *before* that conversion and map `invalid_argument` to exit 2. Leave `refused` as exit 10. The 4096 check lives only in `resolve_text`. A broker check of `len(text.encode())` disagrees with it on the emoji case the driver already got right. `Rejected` text carries an index; do not log `text`, and do not put it on `keyboard_type`. + +3. **Do not design the enter subtest, the unit argv, or `kill -9` from the comments in `__main__.py`.** `pointer acquire` is still one warp (`manager.py` `_warp`, unchanged in this commit) and Stage 0's (a1) did not deliver `wl_keyboard.enter`. A second warp to the same floored pixel is not the fix. `nix/module.nix` does not pass `--xkb-layout`; the flag defaults to `us`, so the running unit types `us` until Stage 2 adds the argv. A `[keyboard]` table in the broker TOML is still not the upload — the driver never opens that file. `input:virtualkeyboard:release_pressed_on_close` is not set, whatever `__main__.py:191-193` says. `upload_keymap` is not idempotent: a second call creates a second virtual keyboard and orphans the first (`backend.py:227`). Do not call it on acquire or per string. + +Also, because the mirror landed here and nothing uses it: + +- `expire()` still returns `LeaseInfo` with no keys (`pointer.py:178-196`). `_expire_pointer` reads `pressed()` and not `keys_pressed()` (`manager.py:1857`). Read the keys first. The driver's one `release_all` is what lifts them; do not add `release_all_keys`. +- The committed `PointerDriver.release_all` returns the button list only (`driver.py` `release_all`), and `_release_all_buttons` does `list(lifted)` (`manager.py:2058-2061`). The new reply field is `lifted_keys` beside `lifted`. Changing the client method to return a tuple without updating that `list()` turns the button names into the two lists. +- `pressed()` on the client still returns buttons only. The reply now also has `keys`. Do not widen the return of `pressed()` in place. +- `keyboard.key` and `keyboard.type` are not in `MUTATING_VERBS`. `pointer.state` must stay out of it. No keyboard verb calls `touch`. Acquire's stderr still says "pointer" only; a `keyboard.*` verb that goes through `_refresh` moves the deadline, and the help text has to say so. +- `CONTRACT-sessions.md` §3.4 is still the two-flag command line and a `pressed` / `release_all` with no key fields (`:262`, `:283-284`). Amend it in the same change as the unit argv. `test_the_contracts_ops_…` will not notice if you forget. + +## Carried objections + +From the Stage 0 review, still true of `f931858`, with one correction for where the branch tip is: + +- **The plan banner is not in this commit.** `git grep` of `f931858` for the supersession banner is empty, so anyone who builds Stage 1 from that commit alone still has the unedited exit-code paragraph, the `[keyboard]` TOML rows, and "if it repeats, the help text says so". `b1f2744` (after this commit, not reviewed here) adds the banner and folds the eight rows. Do not treat that as something Stage 1 did, and do not do it again. +- **Stage 0's (a) mechanism, as `f931858` inherited it.** This commit does not cite it. The parent commit's README did. `b1f2744` rewrites that README; it was not re-checked for this review. Stage 2 still must not read "one warp late" as "wait longer" or as "warp twice to the same point". +- **`mask_cleared=no` is not a held Shift.** `backend.py:246-250` cites `tests/README-keyboard-probe.md` for "destroy does not clear the modifier mask". The send of `modifiers(0,0,0,0)` after upload is right anyway — `releasePressed` never emits modifiers — but the citation is the sentence Stage 0 said the log does not support. The cleanup `state=0` for code 30 is the poison evidence, and it is why finding 2 is not theoretical. +- **The Hyprland XML, kept on purpose.** `regenerate.py` says wayland-protocols has no `virtual-keyboard` directory in this nixpkgs and vendors Hyprland's copy, which names `keymap_format` and `key_state` and defines neither. `XKB_V1 = 1` and `buttons.STATES` are the right workaround. Switching later, if a nixpkgs grows the file, does not move the integers. Do not vendor a second copy to get an enum. +- **Changes 5 and 8, the halves this stage did not take.** The driver half of 5 is done (flag, comma rejected before `xkb_keymap_new_from_names`, no `rules` flag, `evdev` hardcoded). The unit argv is not. The driver half of 8 is done (index and `U+` codepoint, and the server does not log the request line). Acquire's stderr is untouched. Change 7 (the probe's expectations, the unconditional `keyboard down` warning) is not this stage; the warning has nowhere to live until the CLI exists, and it is still unconditional when it does. +- **`xkbcommon` is a hard dependency** (`pyproject.toml`, `nix/package.nix`). Leave it that way. An optional one lets `test_keymap.py` skip, and the unmappable path is the one that rots. diff --git a/docs/reviews/2026-10-04-stage2-3-review.md b/docs/reviews/2026-10-04-stage2-3-review.md new file mode 100644 index 0000000..81573f2 --- /dev/null +++ b/docs/reviews/2026-10-04-stage2-3-review.md @@ -0,0 +1,178 @@ +# Stage 2 and Stage 3 review — the broker learns to type, and the VM has to show it + +Reviewed `e6f4c3b` (Stage 1 review fixes plus the broker, CLI and module), `7890315` (xkbcommon in the unit check, and the two-warp acquire tests), `a6a4094` (`checks/vm-keyboard.nix`, the keyboard victim, the helper derivation) and `54dd109` (the change to `checks/vm-pointer.nix`). Tip is `54dd109` on `feat/keyboard-input`. Line numbers below are that tip, not the individual commits. + +Nothing was rebuilt. Pytest was not run. The VM checks were not run — they are slow and are being run elsewhere. What follows is a reading of the code and of what each assertion would and would not catch. A green VM log from another machine is not evidence this review produced. + +The Stage 1 fixes that `e6f4c3b` claimed are in the tree and are not re-opened here. `key` of a capital sends the mask before the key (`tests/pointer/test_ops.py:510-528`). `type` under a held Control asserts the whole sequence, including the key, and the comment says why a first-and-last check would pass while typing nothing (`test_ops.py:653-688`). `release_pressed_on_close = true` is set (`nix/hyprland-conf.nix:134-136`). The keymap upload is ordered connect, upload, listen, serve (`tests/pointer/test_driver_flags.py:254-272`) and the payload test counts the NUL (`test_driver_flags.py:286`). A key-up forgets the name only after the sink accepts (`test_ops.py:589`). `checks/unit.nix:27` puts `xkbcommon` next to `pywayland`, so the resolver tests cannot skip. + +--- + +## Stage 2 — broker, CLI, module + +### Verdict + +**done-with-fixes.** The verbs, the exit codes, the driver token, the two warps, the layout argv and the audit count are implemented and the tests that exist mostly look at the bytes the driver would send. Two tests the verification named as false passes were not written. The behaviour they would lock is the shared cache and a call that is already in `kill()`. Fixing them is two tests, not a redesign. + +### What is in the tree + +**Verbs.** `keyboard.key` and `keyboard.type` are in `VERBS` and in `MUTATING_VERBS` (`src/hhstreamd/protocol.py:157-188`). There is no `keyboard.acquire`. Both go through `_refresh` (`manager.py:1882`, `1913`), so they refresh the lease and do not mark activity. `test_typing_does_not_count_as_activity` (`tests/sessions/unit/test_keyboard_verbs.py:523-543`) asserts the timestamp **and** `command_count`. `pointer.state` reports `keys` as names (`manager.py:1849-1851`). `pointer.release` reports `keys_lifted` beside `buttons_lifted` (`manager.py:1822-1837`). Expiry reads `keys_pressed()` before `expire()` and then one `release_all` (`manager.py:1962-1975`). + +**Exit codes, and they are the ones the plan names.** + +| Code | Name | How it is reached | +| --- | --- | --- | +| 2 | `invalid_argument` | Bad state, non-string text, over the scalar cap, at the broker before the driver (`manager.py:1884-1922`). A bad keysym or an unmappable character, after the driver says `kind`. | +| 8 | `pointer_busy` | A second `pointer.acquire` only (`manager.py:1628-1635`). Holding a key does not change that. `test_a_second_acquire_while_a_key_is_held_is_busy_and_leaves_the_key` (`test_keyboard_verbs.py:171-185`) checks the holder and the key both survive. | +| 9 | `no_lease` | No lease, or another session's lease id (`test_keyboard_verbs.py:144-168`). Not 8. The CLI prints the exit-9 sentence (`src/hhstream_session/format.py:399-404`, `KEYBOARD_LEASE_NOTE` at `__init__.py:491-498`). | +| 10 | `driver_refused` | Anything the driver refuses without `kind == "invalid_argument"`, including a missing keyboard global (`manager.py:2168-2177`, `test_keyboard_verbs.py:387-407`). Pointer move still works in that test. | + +**The token mapping landed.** The driver sets `kind` to `invalid_argument` for a bad keysym, a bad state, an unmappable character and an over-cap string (`src/hhstream_pointer/ops.py:107-117`, `457-466`). The client copies `reply["kind"]` onto `DriverRejected` (`src/hhstreamd/driver.py:218-221`). `_drive` maps that one token to `ManagerError("invalid_argument")` and leaves every other refusal, including a missing `kind`, as `driver_refused` (`manager.py:2168-2177`). `test_an_unmappable_character_is_exit_2_and_types_nothing` (`test_keyboard_verbs.py:288-304`) goes through the real manager, the real UNIX socket and the real dispatcher on a compiled `us` keymap (`tests/sessions/fakes.py:477-493`). It asserts the error name, `exit_code_for == USAGE`, and `sink.calls == []`. A driver that refused `é` as `driver_refused` fails it. A driver that typed `caf` and then refused fails it. This is not a fake that returns the error name by agreement. + +**Two warps, and the threshold is pinned.** `pointer_acquire` always calls `_warp_taking_focus` (`manager.py:1638-1639`). That sends a warp to `(x, _nudged(y))` and then a warp to `(x, y)` (`manager.py:2220-2234`). `FOCUS_NUDGE` is `0.004` (`manager.py:2392`), about 2.88 px at the frozen 1280×720 mode, so the floored pixels differ. The unit test asserts two warps, the second equal to the bookmark, the rounded pixels different, and `focus == "warp"` (`test_keyboard_verbs.py:624-651`). The integration test pins the nudge itself: after a restore to `(0.8, 0.2)` the sink saw `(0.8, 0.204)` then `(0.8, 0.2)` (`tests/sessions/integration/test_containers.py:580-585`). `follow_mouse = 1` and `follow_mouse_threshold = 0` are written out in `nix/hyprland-conf.nix:99-115`, not inherited. The comment says why raising the threshold stops acquire taking the keyboard. + +**The fallback is not where the plan's stage table puts it.** See finding 3. The second motion is real. The `focuswindow` call exists, on nudge failure only, and the contract describes that. The plan's stage table still says it is Stage 4. + +**CLI and module.** `hhstream session keyboard type|key|down|up` is built in `_build_keyboard` (`src/hhstream_session/__init__.py:501-627`). Each verb takes `--lease` and otherwise reuses the cached pointer lease, and refuses with `_no_lease` (exit 9) when there is none (`__init__.py:1232-1296`). `type` renders a character count, never the text (`__init__.py:1241-1248`). `sessions.keyboard.layout` is `strMatching "[A-Za-z0-9_-]+"`, default `"us"` (`nix/module.nix:630-638`). The only consumer is `hhstream-pointer`'s `ExecStart`, as `--xkb-layout` and the three sibling flags (`nix/module.nix:1060-1080`). There is no `[keyboard]` TOML table. The audit event is `chars=len(text)` (`manager.py:1927`). The generic `request` audit stores the verb, the error name and the request id, not the body (`server.py:233-242`). Driver refusals name a scalar index and a `U+` codepoint (`test_keyboard_verbs.py:307-317`). A non-string `text` can put `text!r` into an error reason (`manager.py:1915`); that is a shape check, not a typed string. Nothing in the broker, the CLI render or the audit line logs the text. The shell's own argv is out of scope, and the plan says so. + +### Findings + +Ordered by what they cost to fix. None of them is a missing verb. + +1. **The replay test asserts set membership, not the sink.** The verification's own false pass (`docs/plans/2026-10-04-keyboard-verification.md` §B2): "Asserting `deduplicated` and not the sink. A handler that types and then sets the flag stays green." What landed is `test_every_keyboard_verb_is_cached_for_the_same_reason` (`tests/sessions/unit/test_broker_protocol.py:175-184`), which checks that the two names are in `MUTATING_VERBS`. The cache itself is real and is not keyboard-specific: `_dispatch` looks up `request_id` before the handler and `remember`s after (`server.py:196-231`), and the key is the request id alone (`protocol.py:196-222`). `test_a_retried_click_with_the_same_request_id_clicks_once` (`test_containers.py:545-561`) is the shape the spec asked to copy, and it counts `sink.of("button")`. Nothing replays `keyboard.type`, and nothing replays an unmappable `type` and asserts the sink stayed empty. The CLI does not send a `request_id` on keyboard verbs (same as the pointer gestures; `--request-id` is on start/kill/gc/adopt/reconcile). Dedup only fires when a caller of the broker socket supplies one. A regression that removed the two names from the set fails the membership test. A regression that typed and then cached would not, because that test never calls the handler. + + Cheapest fix: copy the click integration test. One `keyboard.type` of `"ab"` with `request_id="retry-me"`, a second call with the same id, assert `deduplicated` and that the sink's `key` count did not grow. A second case, an unmappable string, same id twice, sink still empty. + +2. **Key-lift on kill is tested by calling the helper, not `kill()`.** `test_killing_the_holder_lifts_its_keys` (`test_keyboard_verbs.py:563-574`) calls `manager._drop_lease_for(..., "kill")` and then looks for the key-up on the sink. `SessionManager.kill` does call `_drop_lease_for(session, reason="kill")` (`manager.py:1232-1237`), so the production path is there. The spec named the false pass: a `kill` of a session that does not hold the lease, or a `kill` that no longer calls the helper, stays green. The existing integration kill test (`test_containers.py:520-529`) asserts `dispatcher._pressed == {}` and a null holder. It never holds a key, so removing the call from `kill()` while leaving `_drop_lease_for` itself correct stays green. + + Cheapest fix: in that integration test, `keyboard.key` down of `Shift_L` before `kill`, then assert the sink lifted it (or `pointer.state` `keys == []` after, which is weaker — prefer the sink). + +3. **`focuswindow` is inside acquire, on nudge failure, and the plan still says it is Stage 4.** The code matches `docs/CONTRACT-sessions.md` v3 (`:407-413`): two warps, reply field `focus` of `warp` / `focuswindow` / `none`, depending on a threshold the conf file sets. It does not match the plan. The risk paragraph still says acquire is one warp and the fallback "is still not built in Stages 1–2", on `window.stable_id`, immediately before the first key (`docs/plans/2026-10-03-keyboard-input.md:297`, stage table at `:324`). + + What the code actually does (`manager.py:2220-2260`): if the nudge warp raises, log it, call `hyprctl dispatch focuswindow` with `address:` from `session.container.window.address` or else `pid:{session.pid}`, then **still send the target warp**. The target warp's failure still drops the lease (`manager.py:1640-1644`). `address:` is the selector `vm-pointer` itself uses and treats as working (`checks/vm-pointer.nix:493-494`). `pid:` is the branch when no address has been read back, and nothing tests it. `stable_id` would be the wrong selector; the code is more correct than the plan's wording. + + The fallback does not cover the failure Stage 0 measured. That failure is "both warps were sent and the keyboard did not move", which is what the second warp is for, and only when the threshold is 0. The fallback covers a driver error on the nudge. A driver that is down fails the target warp too and the acquire aborts, so the path that returns `focuswindow` is the narrow one where the nudge fails and the target warp succeeds. Nothing tests it. `test_acquire_sends_two_motions_so_keyboard_focus_moves` requires `focus == "warp"`. The VM does the same (`checks/vm-keyboard.nix:511-515`), so a broken fallback stays green everywhere. If both mechanisms fail, acquire still succeeds and reports `focus="none"` (`manager.py:2233`). That is a lease whose first key goes to the previously focused window. The VM would catch it. No unit test does. + + Cheapest fix: edit the plan. Strike stage 4's "build `focuswindow` before the first key", and rewrite the risk paragraph so it describes the two warps and the nudge-failure fallback the contract already describes. Do not move the call to match the stale paragraph. A test that forces the nudge to raise and asserts one `focuswindow` plus the target warp is worth having; it is not what makes the two-warp true. + +4. **The broker chord test checks the first and last mask, not the key.** `test_a_held_modifier_survives_a_type_and_ors_into_it` (`test_keyboard_verbs.py:231-245`) asserts `calls[0]` and `calls[-1]` are the Control mask and that the lease still holds `Control_L`. It does not assert a `key` event for `c` between them. The comment on the driver test (`test_ops.py:680-682`) says that shape types nothing and stays green. The driver test is the real lock: the whole sequence, including the key (`test_ops.py:662-668`). The broker test is a weaker copy. Not a functional bug. + + Cheapest fix: assert the four-tuple the driver test already asserts, against `harness.fake.sink.calls`. + +5. **The tap's comment describes a behaviour the code does not have.** `_cmd_keyboard_key` says the up is sent even if the down was refused after sending (`src/hhstream_session/__init__.py:1257-1260`). The next lines return immediately when `down` is not `ok` (`:1269-1270`). A broker refusal (bad keysym, never pressed) should not send the up, and the early return is right for that. A reply lost after a successful down is a connection error, not `ok: false`, so the sentence is not implemented and should not be. Cheapest fix: delete the sentence. + +6. **`test_exactly_the_cap_is_accepted` does not look at the sink** (`test_keyboard_verbs.py:366-373`). It asserts `reply["chars"]`. A handler that returned the count and never called the driver stays green. The over-cap test does assert `sink.calls == []`. Cheapest fix: assert the sink is non-empty, or at least that its length is `2 * MAX_TYPE_SCALARS` key events. Low; the dispatcher has its own cap tests. + +7. **`test_the_module_passes_the_same_defaults_this_binary_has` is a substring of `nix/module.nix`** (`test_driver_flags.py:160-174`). `default = "us"` in a comment, or `"--xkb-layout"` anywhere in the file, satisfies it. The VM's `ExecStart` assertion is the one that would notice (`checks/vm-keyboard.nix:386-392`). Not worth a new unit test if Stage 3 stays. + +### What the merge request must not claim + +- That a replayed `keyboard.type` was shown not to type twice. Membership in `MUTATING_VERBS` was shown. The click replay test covers the cache for clicks. +- That `kill()` was shown to lift keys. `_drop_lease_for` was shown to. `kill()` contains the call; no test goes through it with a key down. +- That `focuswindow` is tested, or that it is the Stage 0 fix. The Stage 0 fix is the second warp. The fallback runs when the nudge cannot be sent, returns `focus="none"` without failing the acquire when the compositor call also fails, and no test enters that branch. +- That the plan's stage table was followed. The contract was. The plan still says Stage 4. +- That Wayland bytes were inspected. Broker tests see `RecordingSink` tuples from the real dispatcher. One test calls the real `upload_keymap` for the NUL size. That is the right layer for a unit test and it is not a compositor. + +### Carried objections + +- The plan's stage table and risk paragraph disagree with `CONTRACT-sessions.md` v3 and with the code. Fix the plan, or say in the merge request that the contract wins. Do not treat it as unfinished Stage 4 work. +- Keyboard CLI verbs do not generate `request_id`. Same as pointer gestures. Dedup is for a caller of the control socket. +- `ps` of the CLI's `type` argument shows the string. The plan excludes it. `events.jsonl` does not contain it, on the path the unit test checks (the `keyboard_type` event only; the VM greps the whole file). +- Every acquire moves the cursor by about 3 px and back. Clients see both warps. That is the mechanism, not an accident. `vm-pointer`'s repaired subtest prints the jiggle. +- No `[keyboard]` table. Layout is argv only. Hyprland `input:kb_layout` is not read. Both are what change 5 of the verification asked for. +- The unit pixel check uses `round(y * 720)` (`test_keyboard_verbs.py:650`). Hyprland floors. At `0.004` both differ (2.88 px). A future nudge under one pixel could pass `round` and fail `floor`, or the reverse. The integration assertion of `0.204` is the one that pins the constant. + +--- + +## Stage 3 — the VM check + +### Verdict + +**done.** Read as a check, not as a log this review produced: two windows, characters on one and silence on the other, a key-up after a real TTL, a second acquire refused, and the symbol taken from the keymap the compositor forwarded. `vm-keyboard-de` is a second run of the same script with `sessions.keyboard.layout = "de"`, and a hardcoded `us` fails it in more than one place. The `vm-pointer` edit repairs a premise the two-warp broke. The helper is on the path the check executes, and a missing binary fails the check rather than falling back. `vm-keyboard` and `vm-keyboard-de` would not pass on `main`. This review did not run them. + +### Does the check prove the claim? + +The victim compiles the fd from `wl_keyboard.keymap` with xkbcommon and decodes with that state (`checks/lib/keyboard_target.py:177-215`). No keymap, or one that will not compile, is printed as `UNREADABLE` / `WILL-NOT-COMPILE` / `sym=?`, not as a guessed character. The wrapper is `exec ${tools}/bin/hhs-keyboard-target` with no other program (`checks/vm-keyboard.nix:146-148`). Hyprland `input:kb_layout` is left at its default in both runs (`extraConfig` is empty on this machine; `session-machine.nix:55-57` only appends what the check passes). The header of `vm-keyboard.nix` (`:52-80`) records the two places the written spec is now wrong, and the assertions match that header rather than the stale sentences. + +What a false green would look like, and what the check does instead: + +| Claim | A false green | What is asserted | +| --- | --- | --- | +| Two windows, B focused first | One session, or A's map-time `keyboard enter` counted as the acquire. | `beta` is started second. `focusHistoryID == 0` must be beta's output **before** acquire (`vm-keyboard.nix:457-475`), and beta must already have `keyboard enter` (`:478-482`). The acquire subtest snapshots pointer-enter, keyboard-enter on alpha and keyboard-leave on beta **before** the acquire (`:504-506`) and waits for new ones (`:517-535`). | +| Acquire took the keyboard, not only the cursor | `pointer enter` on alpha, beta still has the keys, `focus` unchecked. That is what one warp does. | `reply["focus"] == "warp"` (`:511-515`). New pointer enter **and** keyboard enter on alpha, keyboard leave on beta (`:517-535`). `focuswindow` or `none` fails the reply assert, so this check does not accept the fallback as success. | +| `hello` on the holder | The log is searched for the substring `hello`, which a script that echoes its argv would satisfy. Or keycodes with no symbol, counted as success. | `typed()` is `sym=` from `keyboard key` lines only (`:241-249`, `:288`). The holder must decode `["h","e","l","l","o"]` (`:627-631`). Any `sym=?` fails (`:632-634`). | +| Silence on the other | Beta never bound a keyboard, so it is silent even when focus never moved. Or beta's key lines scrolled out of the log window (below). | The same subtest requires beta's new key lines to be `[]` (`:619-626`) **and** the positive decode above. Beta bound a keyboard in the focus subtest. The two are one subtest on purpose (`:603-606`). | +| Capital A is a mask | Some non-zero mask anywhere in the log, or a Shift keycode the client ignored. | Press and release are both `sym=A` (`:568-572`), no keycode 42 in the pair (`:573-575`), some mask in the span is non-zero, and the span ends at 0 (`:590-598`). `sym=A` is the ordering proof: the client decodes with the mask it had been given when the key arrived. The comment explains why `span[0]` would flake on the focus-change `modifiers depressed=0`. | +| Key-up after a real TTL | A `state=0` left over from `hello` (those are code 30 and others, not 42). Or an injected clock, which the unit suite already has. | `--ttl` of 8 seconds, `keyboard down Shift_L`, then `wait_until_succeeds` until `pointer state` has a null holder (`:862-889`). The client must report code 42 down then up (`:897-915`) and the mask span must end at 0 (`:916-923`). `type` is not allowed to emit 42, which is why Shift is the key. | +| Second acquire refused | A leftover holder from an earlier subtest, so any acquire of beta exits 8. | This subtest holds `Shift_L` on alpha, **then** has beta acquire (`:807-827`). Exit 8, the holder is still alpha, and `keys` is still `["Shift_L"]`. | +| Symbol from the compositor's keymap | The victim compiled its own `us` table and decoded `hello` from either layout. | `keymap_new_from_string` on the forwarded text (`keyboard_target.py:198`). Exactly one `keyboard keymap` line, not `UNREADABLE`, not `WILL-NOT-COMPILE`, `symbols=` matching the layout (`vm-keyboard.nix:415-438`), and that line's position is before any `keyboard key` line (`:445-452`). | + +Residual, not a false green of the happy path: `target_log` asks for `--lines 800` (`vm-keyboard.nix:229`). `keys(beta)[before:]` is a slice of that tail. If beta's older key lines scroll out of the window, the saved index lands past the new tail and the silence slice is `[]` while beta did receive keys. The `hello` subtest is early, and beta has almost no key lines yet, so this is unlikely there. It is a real hole in the negative assertion if a later edit moves the silence check down the script. A false **red** of the same shape (the positive slice starts in the middle of the new events) is the more likely failure if the window is hit. + +`format=1` (`vm-keyboard.nix:431-433`) is the format the **client** was given. Hyprland can ignore the format on the virtual-keyboard request and always forward format 1. The check does not prove we uploaded format 1. The unit test of `upload_keymap` is the one that sees the request we sent. + +### Does `vm-keyboard-de` exercise a non-`us` layout end to end? + +Yes, as written. `checks/default.nix:66-68` calls the same file with `keyboardLayout = "de"`. `session-machine.nix:87-91` sets `sessions.keyboard.layout` from that argument, which is the option the module puts on `ExecStart`. The `de` run then requires all of: + +- `--xkb-layout de` on the unit (`vm-keyboard.nix:390-392`); +- forwarded symbols `pc_de_inet(evdev)` (`:161-167`, `:434-438`); +- `type y` arriving as evdev 44 and `type z` as 21, with the sym still `y` and `z` (`:662-692`); +- `type cafü` succeeding, `chars == 4`, decoded as `c,a,f,udiaeresis` (`:710-727`). + +A hardcoded `us` fails the symbols line, fails y's code (21 ≠ 44), fails `ü` (exit 2, and the refusal must name `scalar 3` and `U+00FC` without quoting the string, `:728-761`), and fails the argv check. The argv check alone is the false pass the spec named ("greps the unit for `--xkb-layout de` and never types `y`"). It is not the only assertion. Leaving `input:kb_layout` at `us` is what makes a client that ignored our keymap decode the `us` answer on the `de` run. + +The spec's "`type y` on `de` decodes to sym `z`" (`docs/plans/2026-10-04-keyboard-verification.md` §B3 subtest 4) contradicts the same section's rule that the victim decodes the forwarded keymap. A correct driver sends `de`'s code for keysym `y`; the client, using that keymap, reads `y` back. The check documents this (`vm-keyboard.nix:52-69`) and asserts the code, the symbols name and whether `ü` is typeable. That is the right reading. Do not "fix" the check to expect `z`. + +### Was `vm-pointer` repaired or weakened? + +**Repaired.** `54dd109` does not drop the property. It changes how the situation is arranged. + +The property is: a warp is delivered to the session it was aimed at, and the window that holds keyboard focus is told nothing (`checks/vm-pointer.nix:449-462`). That is `input:follow_mouse`, not keyboard focus. It used to be free, because one warp did not move keyboard focus, so after acquire the other session was still focused. Two-warp acquire focuses the holder, so the old precondition ("the other window is focused") stopped arranging itself. The new code acquires, asserts the bookmark is still `(0.25, 0.75)` (`:482-485`), then `hyprctl dispatch focuswindow address:…` on the **other** session as setup (`:493-506`), asserts that window is the focused one, then `pointer move` to `(0.6, 0.4)`. The focused client's events since that setup must be empty (`:529-534`). The aimed client's last reported position must be near the aim (`:535-537`). + +`before` is taken before the acquire (`:479`), so `mine` includes the two acquire warps. `mine[-1]` against `(0.6, 0.4)` still requires the later move: the acquire restores `(0.25, 0.75)`, which is not close to the aim. `before_other` is taken after the focus command and before the move (`:511`), so the focused client's slice does not include anything from the acquire. + +The commit message says `nix build .#checks.x86_64-linux.vm-pointer` passed, 12/12. This review did not reproduce that. + +One residual flake, and it is a false **red**, not a false green. `wait_for` returns when **either** client has new events (`:519-523`). The aimed client already has the acquire warps in `positions(session_id)[before:]`, so the wait can return before the move is logged. `mine[-1]` is then the bookmark, the closeness assert fails, and the check goes red. It does not go green. + +This check would still pass on `main`. On `main`, acquire does not take keyboard focus, the other session is already focused, and the extra `focuswindow` is a no-op setup of a situation that already holds. The routing property predates the keyboard. That is correct. It is not a keyboard check, and a green `vm-pointer` on `main` says nothing about this feature. + +### The helper + +`checks/lib/session-tools.nix` builds `hhs-ipc-watch`, `hhs-pointer-target` and `hhs-keyboard-target`. The keyboard one is installed from `keyboard_target.py` and its shebang is rewritten to a Python with pywayland and xkbcommon (`:76-78`). The builder then `test -x`s all three and runs `--help` (`:84-89`), and compiles a real `us` keymap in that interpreter (`:95`). The comment at the top (`:14-35`) describes the old failure: an indented heredoc terminator swallowed the rest of the builder, the derivation still built, and `$out/bin` contained only `hhs-ipc-watch`. The self-tests had become text inside the shim, so they never ran. `writeTextFile` plus those `test -x` lines is what makes that failure a build failure now. + +The check uses that binary. `tools` is `session-tools.nix` (`vm-keyboard.nix:127`), the guest wrapper execs `${tools}/bin/hhs-keyboard-target` (`:146-148`), and the first subtest that needs a window fails if the target exits 127 (`:397-413`). There is no `||` and no foot fallback. Nix interpolation of the path depends on the derivation; it does not by itself notice a missing file inside `$out`. The derivation's own `test -x` does, and the check depends on the derivation, so a helper that was not installed fails the check's build. A runtime absence (self-test removed, file deleted after the build) fails in the guest as exit 127, which the "victim never got a window" subtest turns red. Same `tools` output supplies `hhs-pointer-target` to `vm-pointer` and `vm-containers`; those checks fail the same way if the pointer target is absent. The keyboard target is not optional on the keyboard check. + +### Would any of this pass on `main`? + +`vm-keyboard` and `vm-keyboard-de` would not. `main` has no `keyboard` CLI, no virtual keyboard on the seat (the headless seat has no keyboard capability, and "target: keyboard bound" is the subtest that requires one), no keymap upload, and an acquire that is one warp, so the keyboard-enter half of the acquire subtest fails. `vm-pointer` would. See above. That split is what "load-bearing" means here: the new checks go red without the feature, and the old check still measures the property it measured before. + +### Findings + +None that change the verdict. Two are worth fixing if the file is touched, and neither is a hole in the claim above. + +1. **The chord subtest does not look at the character.** `vm-keyboard.nix:766-805` holds `Control_L`, types `c`, waits until two key events have arrived, and asserts `pointer state` still lists `Control_L`. It never asserts the sym or the code. Two key events of anything, with Control still held, pass. The driver test is the lock (`test_ops.py:653-668`). Cheapest fix: assert the pair decodes to `c`, `c`. The spec's B3 list does not include this subtest; it is extra. Not a reason to call the stage open. + +2. **`wait_for` in the repaired `vm-pointer` subtest can return on the acquire warps.** False red, described above (`vm-pointer.nix:479`, `:519-523`). Cheapest fix: take `before` after the acquire, or wait until `mine[-1]` is near the aim. Do not "fix" it by dropping the closeness assert. + +### What the merge request must not claim + +- That §B3's "`type y` on `de` decodes to sym `z`" was implemented. It was not, correctly. The proof is the evdev code, the symbols name `pc_de_inet(evdev)`, and that `ü` is typeable on `de` and exit 2 on `us`. +- That this review ran `vm-keyboard` or `vm-keyboard-de`. It did not. The `vm-pointer` re-run claimed in `54dd109` was not reproduced here either. +- That `format=1` in the client log proves the driver uploaded format 1. +- That the `focuswindow` fallback was exercised. The check requires `focus == "warp"` and treats the other two values as failure. +- That `vm-pointer` going green is evidence of the keyboard. It is evidence the cursor still goes to the window under it. It would go green on `main`. +- That a silence assertion is safe at any point in a long script. It is a slice of an 800-line tail. + +### Carried objections + +- The plan's Stage 3 gate still says "do not design the enter subtest from acquire's single warp" (`2026-10-03-keyboard-input.md:323`) and the verification still says one warp (`2026-10-04-keyboard-verification.md` §B3 subtest 1). The check's header is the text that matches the code. Same docs drift as Stage 2 finding 3; one edit covers both. +- The chord subtest, as finding 1. Leaving it does not weaken `hello`, the capital, or the layout run. +- The 800-line tail, as above. Fine for this script's early silence check. Do not copy the pattern into a later subtest without counting lines. + +--- + +## One line + +After the two tests in Stage 2 findings 1 and 2, this branch is safe to merge; update the plan's stage table so it matches the contract (or say in the merge request that the contract wins), and nothing else has to happen first. diff --git a/flake.nix b/flake.nix index 17138a9..5a30480 100644 --- a/flake.nix +++ b/flake.nix @@ -40,7 +40,10 @@ grim ffmpeg # The client side of the contract (hhstream-client), so a shell can - # read the stream without a `nix build` first. + # read the stream without a `nix build` first. It also brings + # pywayland and xkbcommon, which `tests/pointer` imports directly -- + # `test_keymap.py` compiles a real `us` keymap rather than stubbing + # one, because a stub cannot tell you that `é` is unmappable. (callPackage ./nix/package.nix { }) # `websocket-client` drives Chromium over the DevTools protocol, which # is how the demo types into the page and reads the result back. diff --git a/nix/hyprland-conf.nix b/nix/hyprland-conf.nix index 6bc0a1a..dc459ec 100644 --- a/nix/hyprland-conf.nix +++ b/nix/hyprland-conf.nix @@ -90,7 +90,50 @@ in '' # aimed correctly and delivered nowhere. The cursor lease already # serialises input, so letting the pointer move keyboard focus cannot make # two sessions fight over the keyboard. + # + # It is also what moves the KEYBOARD, which matters now that the broker + # injects keys as well: a virtual keyboard is seat-global and has no + # output, so the warp is the only thing that decides which window the + # letters land in, and the lease is what stops another session retargeting + # them mid-string. follow_mouse = 1 + + # Set explicitly, at its default value, because `pointer acquire` now + # depends on it rather than merely benefiting from it. + # + # MEASURED (tests/README-keyboard-probe.md): one warp onto an idle cursor + # delivers `wl_pointer.enter` and NO `wl_keyboard.enter`. Hyprland's + # `onMouseWarp` goes through `mouseMoveUnified(refocus=false)`, which + # *sets* `m_mousePosDelta` to 0 when the previous movement was more than + # 0.5 s ago, and keyboard focus is that delta compared against this + # threshold. So acquire sends two motions a real pixel apart: the second + # carries a non-zero delta, and `> 0` is true only because this is 0. + # + # Raise it and `hhstream session pointer acquire` stops taking keyboard + # focus — the cursor would land in the session's window and the first + # keystroke would go to whatever was focused before. + follow_mouse_threshold = 0 + + # Release a virtual keyboard's held keys when its resource is destroyed. + # + # MEASURED, and the default is `false`: `destroy` with a key down + # delivered no key-up at all. That is worse than a stuck key, because + # `InputManager::onKeyboardKey` *drops* a press whose code is already in + # the seat's `m_pressed` — so a driver killed with `-9` leaves that code + # there and the next driver's press of it is ignored. The key is dead, + # not merely held, and nothing in the logs says so. + # + # The driver's own shutdown path lifts keys first + # (`hhstream_pointer.__main__._lift_everything`) and SIGKILL skips it; + # this is the backstop for that case. + # + # It does NOT clear the modifier mask: `releasePressed` emits key-ups and + # never a `modifiers`, and a client keeps the last mask it was sent. That + # is why `release_all` ends with `modifiers(0, 0, 0, 0)` on every path we + # control, and why this setting is a backstop rather than the mechanism. + virtualkeyboard { + release_pressed_on_close = true + } } # Frames cost capture bandwidth and CPU, and no one is watching the easing. diff --git a/nix/module.nix b/nix/module.nix index 2d7446b..14d4bd7 100644 --- a/nix/module.nix +++ b/nix/module.nix @@ -620,6 +620,80 @@ in { }; }; + # The keyboard has no `enable` of its own: it is the same unit, the same + # process and the same lease as the pointer (`hhstream session keyboard + # …` refuses with exit 9 until `pointer acquire`). What it needs from an + # operator is a layout, because the keymap the driver uploads is the only + # thing that decides which keycode a keysym is -- Hyprland's own + # `input:kb_layout` is not read and does not affect injected keys. + keyboard = { + layout = lib.mkOption { + # `strMatching` and not `str`, and the pattern is the point: it is + # what refuses `us,ru`. A comma-separated layout compiles perfectly + # well into a two-group keymap, and v1 sends `group = 0` in every + # `modifiers` request -- so the second group would be unreachable and + # an agent asking for a Cyrillic character would silently get a Latin + # one. The driver refuses a comma too, for a binary run by hand. + type = lib.types.strMatching "[A-Za-z0-9_-]+"; + default = "us"; + example = "de"; + description = '' + XKB layout the `hhstream-pointer` unit compiles once at start-up and + uploads as its virtual keyboard's keymap (rules `evdev`, model from + {option}`sessions.keyboard.model`). + + **This is the only thing that decides what an injected key means.** + Every `hhstream session keyboard` verb names an XKB *keysym* + (`a`, `A`, `Return`, `Control_L`), and the driver resolves that name + against this keymap to get the evdev code and the modifier mask the + compositor is sent. A character this layout cannot produce is + refused with exit 2 and nothing is typed -- there is no partial + type, so `é` on `us` fails the whole string rather than the letter. + + Hyprland's `input:kb_layout` is **not** read. 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. One group only: see the type. + ''; + }; + + model = lib.mkOption { + type = lib.types.strMatching "[A-Za-z0-9_-]*"; + default = "pc105"; + description = '' + XKB model for the same keymap. `pc105` unless an operator knows + otherwise; it decides little beyond which keys exist at all. + ''; + }; + + variant = lib.mkOption { + type = lib.types.str; + default = ""; + example = "intl"; + description = '' + XKB variant, empty by default. + + Worth knowing before setting one: a variant whose characters are + **dead keys** -- `us(intl)`'s accents, for instance -- cannot be + typed by this version. A dead key is half of a compose sequence and + v1 emits one event per character, so the driver refuses the name + rather than arming the next keystroke in the focused application. + ''; + }; + + options = lib.mkOption { + type = lib.types.str; + default = ""; + example = "ctrl:nocaps"; + description = '' + XKB options, empty by default. Passed through to + `xkb_keymap_new_from_names`; a value it rejects stops the driver + with exit 2 before it connects to the compositor, so a typo here is + a failed unit rather than a session that types the wrong thing. + ''; + }; + }; + stateDir = lib.mkOption { type = lib.types.str; default = "/var/lib/hhstream"; @@ -978,17 +1052,32 @@ in { # plainly that stopping the driver stops the driver and nothing else. KillMode = "process"; - # Frozen in docs/CONTRACT-sessions.md §3.4, word for word. The driver - # defaults to both of these paths anyway; they are passed explicitly - # because the contract specifies the command line, and a unit that - # relied on the defaults would stop matching it the moment either - # default moved. + # The first two flags are frozen in docs/CONTRACT-sessions.md §3.4, + # word for word. The driver defaults to both of those paths anyway; + # they are passed explicitly because the contract specifies the command + # line, and a unit that relied on the defaults would stop matching it + # the moment either default moved. + # + # The four XKB flags are the **only** path a layout has to the uploaded + # keymap, and that is worth being blunt about: the broker's TOML has a + # `[pointer]` table that `hhstreamd` reads for its lease numbers, and + # this is a different unit that never opens that file. A `[keyboard]` + # table there would be a setting an operator could change while every + # injected key stayed on `us`. ExecStart = lib.escapeShellArgs [ (lib.getExe' cfg.package "hhstream-pointer") "--socket" pointerSocket "--compositor-runtime-dir" runtimeDir + "--xkb-layout" + cfg.sessions.keyboard.layout + "--xkb-model" + cfg.sessions.keyboard.model + "--xkb-variant" + cfg.sessions.keyboard.variant + "--xkb-options" + cfg.sessions.keyboard.options ]; }; }; diff --git a/nix/package.nix b/nix/package.nix index fb402ca..b63567b 100644 --- a/nix/package.nix +++ b/nix/package.nix @@ -12,22 +12,29 @@ python3.pkgs.buildPythonApplication { build-system = [ python3.pkgs.setuptools ]; - # `hhstream-pointer` is a Wayland client, so it needs libwayland's marshalling. - # The wlr virtual-pointer protocol itself is *not* a build input: the generated - # module is vendored under src/hhstream_pointer/_protocol, so a checkout builds - # without a code generator. See that package's docstring for why, and - # hhstream_pointer._protocol.regenerate for how to refresh it. - dependencies = [ python3.pkgs.pywayland ]; + # `hhstream-pointer` is a Wayland client, so it needs libwayland's + # marshalling; and it resolves keysym names against the XKB layout it + # uploads, so it needs xkbcommon. + # + # Neither protocol XML is a build input: both generated modules are vendored + # under src/hhstream_pointer/_protocol, so a checkout builds without a code + # generator. See that package's docstring for why, and + # hhstream_pointer._protocol.regenerate for how to refresh them -- including + # the note that virtual-keyboard-unstable-v1.xml is not in wayland-protocols + # or wlr-protocols in this nixpkgs and comes from pkgs.hyprland.src. + dependencies = [ python3.pkgs.pywayland python3.pkgs.xkbcommon ]; # Unit tests are wired up in the flake's `checks` so they can run without # installing the package; see docs/CONTRACT.md. doCheck = false; - # Cheap proof that the vendored protocol still binds against this pywayland: - # importing it runs the scanner-generated `_gen_c()` for both interfaces. + # Cheap proof that the vendored protocols still bind against this pywayland: + # importing each runs the scanner-generated `_gen_c()` for its interfaces. pythonImportsCheck = [ "hhstream_pointer.ops" + "hhstream_pointer.keymap" "hhstream_pointer._protocol.wlr_virtual_pointer_unstable_v1" + "hhstream_pointer._protocol.virtual_keyboard_unstable_v1" ]; meta = { diff --git a/pyproject.toml b/pyproject.toml index 0e8c0f9..0645b84 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -8,11 +8,14 @@ version = "0.1.0" description = "Publish a headless Hyprland session's frames on a Unix socket" requires-python = ">=3.11" # The frame socket, the CLI and the broker are stdlib-only by policy -# (docs/CONTRACT-sessions.md §6, rule 3). The pointer driver is the one -# exception: talking Wayland means speaking the wire protocol, and -# re-implementing libwayland's marshalling here would be a worse idea than -# a dependency. -dependencies = ["pywayland>=0.4"] +# (docs/CONTRACT-sessions.md §6, rule 3). The input driver is the one +# exception, twice over: talking Wayland means speaking the wire protocol, and +# turning a keysym name into the keycode-plus-modifier-mask that *this* layout +# needs means compiling an XKB keymap. Re-implementing either here would be a +# worse idea than a dependency, and `xkbcommon` is deliberately NOT optional -- +# an optional one would let `tests/pointer/test_keymap.py` skip, and the +# unmappable-character path is exactly the one that must not rot. +dependencies = ["pywayland>=0.4", "xkbcommon>=1.0"] [project.scripts] hhstream-server = "hhstream.server:main" diff --git a/src/hhstream_pointer/__main__.py b/src/hhstream_pointer/__main__.py index fd99c32..97d81ac 100644 --- a/src/hhstream_pointer/__main__.py +++ b/src/hhstream_pointer/__main__.py @@ -3,15 +3,33 @@ The broker starts it with exactly: hhstream-pointer --socket /run/hhstream/pointer.sock \\ - --compositor-runtime-dir /run/hypr-stream + --compositor-runtime-dir /run/hypr-stream \\ + --xkb-layout us --xkb-model pc105 \\ + --xkb-variant '' --xkb-options '' -Both flags default to those frozen paths (§5) so the binary is also runnable by -hand when diagnosing a stuck cursor. +Every flag defaults to the value above, so the binary is also runnable by hand +when diagnosing a stuck cursor or a layout that will not type. -It connects to the compositor *before* it listens. A socket that exists is a -promise that warps will work, and a driver that accepted requests while still -looking for a version-2 manager would answer the first few with errors the -broker cannot tell apart from a bad output name. +**The XKB flags are the only way a layout reaches the uploaded keymap.** Not +the broker's TOML: `[pointer]` in that file is read by `hhstreamd` for its +lease numbers, and this is a different unit that never opens it. A `[keyboard]` +table there would be a setting an operator could change with no effect at all +— which is why `nix/module.nix` puts the layout on this command line instead. + +Order of start-up, and none of it is interchangeable: + +1. **Compile the keymap.** Before any Wayland call, because a layout + xkbcommon will not compile is a configuration error (exit 2) and has + nothing to do with the compositor. +2. **Connect.** A version-1 pointer manager or an unreachable display is + exit 10. +3. **Upload the keymap**, if the compositor has a keyboard manager at all. + ``key`` before ``keymap`` is the protocol error ``no_keymap``, which kills + the connection rather than returning something reportable. +4. **Then listen.** A socket that exists is a promise that warps and keys + work; a driver that accepted requests while still looking for a manager + would answer the first few with errors the broker cannot tell apart from a + bad output name. """ from __future__ import annotations @@ -23,7 +41,14 @@ import sys from pathlib import Path from typing import Any -from .backend import CompositorUnavailable, ManagerTooOld, OutputUnknown, WaylandSink +from . import keymap as keymaps +from .backend import ( + CompositorUnavailable, + KeyboardUnavailable, + ManagerTooOld, + OutputUnknown, + WaylandSink, +) from .ops import Dispatcher from .server import PointerServer @@ -39,6 +64,13 @@ EXIT_COMPOSITOR = 10 DEFAULT_SOCKET = Path("/run/hhstream/pointer.sock") DEFAULT_RUNTIME_DIR = Path("/run/hypr-stream") +#: Frozen defaults for the keymap, matching §5's style for the paths above. +#: ``us``/``pc105`` and empty variant/options is what the NixOS module's +#: ``sessions.keyboard.*`` defaults to as well, so a hand-run driver and the +#: unit type the same characters. +DEFAULT_LAYOUT = "us" +DEFAULT_MODEL = "pc105" + class _Terminated(Exception): """SIGTERM/SIGINT arrived; unwind through the normal shutdown path.""" @@ -69,6 +101,20 @@ def build_parser() -> argparse.ArgumentParser: default=0o660, help="octal mode for the driver socket (default 660)", ) + parser.add_argument( + "--xkb-layout", + default=DEFAULT_LAYOUT, + metavar="LAYOUT", + help="XKB layout uploaded as the virtual keyboard's keymap (default: " + f"{DEFAULT_LAYOUT}). One group only: a comma-separated list is refused, " + "because every `modifiers` request sends group 0 and the rest would be " + "unreachable.", + ) + parser.add_argument( + "--xkb-model", default=DEFAULT_MODEL, metavar="MODEL", help="XKB model" + ) + parser.add_argument("--xkb-variant", default="", metavar="VARIANT", help="XKB variant") + parser.add_argument("--xkb-options", default="", metavar="OPTIONS", help="XKB options") parser.add_argument("--log-level", default="info", help="debug, info, warning, error") return parser @@ -80,6 +126,20 @@ def main(argv: list[str] | None = None) -> int: format="%(levelname)s %(name)s: %(message)s", ) + # Step 1: the layout, before anything touches Wayland. A layout that will + # not compile is the operator's typo, not the compositor's fault, and + # reporting it as exit 10 would send them looking at the wrong unit. + try: + keymap = keymaps.build( + layout=args.xkb_layout, + model=args.xkb_model, + variant=args.xkb_variant, + options=args.xkb_options, + ) + except keymaps.KeymapError as exc: + log.error("%s", exc) + return EXIT_USAGE + sink = WaylandSink(args.compositor_runtime_dir, args.wayland_display) try: sink.connect() @@ -92,7 +152,18 @@ def main(argv: list[str] | None = None) -> int: log.error("%s", exc) return EXIT_COMPOSITOR - dispatcher = Dispatcher(sink) + try: + sink.upload_keymap(keymap.text()) + except CompositorUnavailable as exc: + # A keymap the compositor refuses leaves the resource dead, so there is + # nothing to listen for requests with. Exit 10 and let the unit restart + # us; exit 2 would claim the operator's layout was wrong when + # xkbcommon already accepted it. + log.error("the keymap upload failed: %s", exc) + sink.close() + return EXIT_COMPOSITOR + + dispatcher = Dispatcher(sink, keymap) server = PointerServer(args.socket, _handler(dispatcher), socket_mode=args.socket_mode) for sig in (signal.SIGTERM, signal.SIGINT): @@ -112,8 +183,17 @@ def main(argv: list[str] | None = None) -> int: log.error("socket %s: %s", args.socket, exc) return EXIT_USAGE finally: - # Never exit with a button held: the compositor would keep it down and - # the next session would inherit a drag it never started. + # Never exit with a button or a key held, and never with a modifier + # mask set. The compositor keeps all three: `destroy` of a virtual + # keyboard releases nothing and clears no mask on this build (measured, + # tests/README-keyboard-probe.md), and a code left in the seat's + # `m_pressed` makes the *next* driver's press of that code a no-op. So + # this is the only orderly guard there is -- and SIGKILL skips it, + # which is why nix/hyprland-conf.nix also sets + # `input:virtualkeyboard:release_pressed_on_close = true`. That setting + # emits key-ups only and never a `modifiers`, so it is a backstop for + # the keys and not for the mask: zeroing the mask is `release_all`'s, + # on every path we control. _lift_everything(dispatcher) server.close() sink.close() @@ -131,20 +211,28 @@ def _handler(dispatcher: Dispatcher): def handle(request: Any) -> dict[str, Any]: try: return dispatcher.handle(request) - except OutputUnknown as exc: - return {"ok": False, "error": str(exc)} + except (OutputUnknown, KeyboardUnavailable) as exc: + # Both are "the compositor does not have that", not "this + # connection is finished": the broker is told and keeps its lease. + return {"ok": False, "error": str(exc), "kind": "refused"} return handle def _lift_everything(dispatcher: Dispatcher) -> None: try: - lifted = dispatcher.handle({"op": "release_all"}).get("lifted") or [] + reply = dispatcher.handle({"op": "release_all"}) except Exception as exc: # shutdown is not a place to raise - log.warning("could not lift buttons on the way out: %s", exc) + log.warning("could not lift buttons and keys on the way out: %s", exc) return - if lifted: - log.info("lifted on shutdown: %s", ", ".join(lifted)) + lifted = reply.get("lifted") or [] + lifted_keys = reply.get("lifted_keys") or [] + if lifted or lifted_keys: + log.info( + "lifted on shutdown: buttons %s, keys %s", + ", ".join(lifted) or "none", + ", ".join(lifted_keys) or "none", + ) def _raise_terminated(signum: int, frame) -> None: diff --git a/src/hhstream_pointer/_protocol/__init__.py b/src/hhstream_pointer/_protocol/__init__.py index 0a07ab7..9bcf8d3 100644 --- a/src/hhstream_pointer/_protocol/__init__.py +++ b/src/hhstream_pointer/_protocol/__init__.py @@ -1,8 +1,18 @@ -"""The wlr virtual-pointer protocol, generated and vendored. +"""The two input protocols, generated and vendored. -``wlr_virtual_pointer_unstable_v1/`` is byte-for-byte pywayland scanner output -for ``wlr-virtual-pointer-unstable-v1.xml``; do not hand-edit it. Regenerate -with :mod:`hhstream_pointer._protocol.regenerate`, which prints the command. +``wlr_virtual_pointer_unstable_v1/`` and ``virtual_keyboard_unstable_v1/`` are +byte-for-byte pywayland scanner output for +``wlr-virtual-pointer-unstable-v1.xml`` and +``virtual-keyboard-unstable-v1.xml``; do not hand-edit either. Regenerate with +:mod:`hhstream_pointer._protocol.regenerate`, which prints the command and +records where each XML actually lives — the keyboard one is not where either +plan says it is, and its docstring says so at length. + +One thing the keyboard XML does *not* give us, and it matters: it names +``keymap_format`` and ``key_state`` in its request descriptions and defines +neither enum, so there is nothing generated to read ``xkb_v1 == 1`` or +``pressed == 1`` off. Those live in :data:`hhstream_pointer.keymap.XKB_V1` and +:data:`hhstream_pointer.buttons.STATES` instead, with the citation. Vendored rather than generated at build time for one reason: the scanner needs ``wlr-protocols`` and a working pywayland on the *build* host, so generating diff --git a/src/hhstream_pointer/_protocol/regenerate.py b/src/hhstream_pointer/_protocol/regenerate.py index dbcd99d..22dde98 100644 --- a/src/hhstream_pointer/_protocol/regenerate.py +++ b/src/hhstream_pointer/_protocol/regenerate.py @@ -1,17 +1,44 @@ -"""Regenerate the vendored protocol package. Run by hand after a bump. +"""Regenerate the vendored protocol packages. Run by hand after a bump. nix shell --impure --expr 'with (builtins.getFlake "nixpkgs").legacyPackages.${builtins.currentSystem}; [ (python3.withPackages (p: [ p.pywayland ])) wlr-protocols ]' \\ - --command python3 -m hhstream_pointer._protocol.regenerate + --command env HHSTREAM_PROTOCOL_DIR="$(nix eval --raw nixpkgs#hyprland.src)/protocols" \\ + python3 -m hhstream_pointer._protocol.regenerate -The XML lives at ``share/wlr-protocols/unstable/wlr-virtual-pointer-unstable-v1.xml`` +Two protocols, two XMLs, and they are in two different places. + +**The virtual pointer** is ``share/wlr-protocols/unstable/wlr-virtual-pointer-unstable-v1.xml`` in ``pkgs.wlr-protocols`` — note that this is *not* the path -``docs/CONTRACT-sessions.md`` §3.4 gives; see the slice report. +``docs/CONTRACT-sessions.md`` §3.4 originally gave; see the slice report and +the §3.4 amendment. -pywayland's own ``python -m pywayland.scanner`` is not usable here: it builds -its import map only from the files it was handed, so scanning the wlr XML alone -raises ``KeyError: 'wl_seat'``. We seed the map with the core interfaces -pywayland already ships, then let the scanner emit ``from ..wayland import ...`` -against the shim next door. +**The virtual keyboard** is ``protocols/virtual-keyboard-unstable-v1.xml`` in +``pkgs.hyprland.src``, and that needs saying because two plans name a different +path. ``docs/plans/2026-10-03-keyboard-input.md`` §2 and the review's +objection 4 both call for wayland-protocols' +``unstable/virtual-keyboard/virtual-keyboard-unstable-v1.xml``. **No such file +exists in this flake's nixpkgs.** Checked: wayland-protocols 1.49 has no +``virtual-keyboard`` directory under ``unstable``, ``staging`` or ``stable``; +``pkgs.wlr-protocols`` (nixpkgs' 2022-09-05 snapshot) ships ten XMLs and this +is not one of them, in its output or its source; ``pkgs.wlroots.src`` does not +have it either. Hyprland's own copy is the only one on the machine, so it is +the one vendored, and ``$HHSTREAM_PROTOCOL_DIR`` is how this script is told +where that is. + +One consequence of using that copy, and the reason the review wanted to avoid +it: it *names* ``keymap_format`` and ``key_state`` in its request descriptions +and defines neither enum. So the generated module has no enum to read those +integers off, and they are written down instead — :data:`hhstream_pointer.keymap.XKB_V1` +for the format, and the existing :data:`hhstream_pointer.buttons.STATES` for +``pressed``/``released``, which already holds the same two values because +``wl_pointer.button_state`` and ``wl_keyboard.key_state`` agree. If a future +nixpkgs grows the wayland-protocols copy, switching to it is a one-line change +here and those constants become redundant rather than wrong. + +pywayland's own ``python -m pywayland.scanner`` is not usable for either: it +builds its import map only from the files it was handed, so scanning one of +these alone raises ``KeyError: 'wl_seat'``. We seed the map with the core +interfaces pywayland already ships, then let the scanner emit +``from ..wayland import ...`` against the shim next door. """ from __future__ import annotations @@ -21,36 +48,55 @@ import os import sys from pathlib import Path -#: Where ``pkgs.wlr-protocols`` puts it, relative to the package root. -XML_SUFFIX = "share/wlr-protocols/unstable/wlr-virtual-pointer-unstable-v1.xml" +#: Where ``pkgs.wlr-protocols`` puts the pointer XML, relative to a package root. +POINTER_XML_SUFFIX = "share/wlr-protocols/unstable/wlr-virtual-pointer-unstable-v1.xml" + +#: Where wayland-protocols *would* put the keyboard XML if it had it. Searched +#: first anyway, so a nixpkgs that grows it is picked up without an edit. +KEYBOARD_XML_SUFFIX = ( + "share/wayland-protocols/unstable/virtual-keyboard/virtual-keyboard-unstable-v1.xml" +) + +#: The filename to look for in ``$HHSTREAM_PROTOCOL_DIR``, which is where +#: Hyprland's source keeps the only copy that exists here. +KEYBOARD_XML_NAME = "virtual-keyboard-unstable-v1.xml" + +#: Where to look for a package root that might contain either suffix. +ENV_PROTOCOL_DIR = "HHSTREAM_PROTOCOL_DIR" -def find_xml() -> Path | None: - """Look for the protocol XML on ``XDG_DATA_DIRS`` and in the nix profile.""" +def _roots() -> list[Path]: + """Package roots to search: ``XDG_DATA_DIRS``, then the usual profiles.""" roots = [Path(p).parent for p in os.environ.get("XDG_DATA_DIRS", "").split(":") if p] - roots += [Path("/run/current-system/sw"), Path.home() / ".nix-profile"] - for root in roots: - candidate = root / XML_SUFFIX + return roots + [Path("/run/current-system/sw"), Path.home() / ".nix-profile"] + + +def find_pointer_xml() -> Path | None: + for root in _roots(): + candidate = root / POINTER_XML_SUFFIX if candidate.is_file(): return candidate return None -def main(argv: list[str] | None = None) -> int: - parser = argparse.ArgumentParser(description=__doc__.splitlines()[0]) - parser.add_argument("--xml", type=Path, default=None, help=f"path to .../{XML_SUFFIX}") - parser.add_argument( - "--output-dir", - type=Path, - default=Path(__file__).resolve().parent, - help="where the protocol package is written (default: next to this file)", - ) - args = parser.parse_args(argv) +def find_keyboard_xml() -> Path | None: + """wayland-protocols if it ever has it, else ``$HHSTREAM_PROTOCOL_DIR``.""" - xml = args.xml or find_xml() - if xml is None: - parser.error(f"could not find {XML_SUFFIX}; pass --xml (is wlr-protocols in the shell?)") + for root in _roots(): + candidate = root / KEYBOARD_XML_SUFFIX + if candidate.is_file(): + return candidate + directory = os.environ.get(ENV_PROTOCOL_DIR) + if directory: + candidate = Path(directory) / KEYBOARD_XML_NAME + if candidate.is_file(): + return candidate + return None + + +def generate(xml: Path, output_dir: Path) -> str: + """Scanner output for one XML into ``output_dir``. Returns the module name.""" from pywayland.protocol import wayland as core from pywayland.scanner.protocol import Protocol @@ -58,13 +104,56 @@ def main(argv: list[str] | None = None) -> int: protocol = Protocol.parse_file(str(xml)) module = protocol.name.replace("-", "_") # Interface -> protocol module. The core interfaces resolve to the shim in - # this directory; ours resolve to themselves. + # this directory; this protocol's own resolve to themselves. core_dir = Path(core.__file__).parent imports = {p.stem: "wayland" for p in core_dir.glob("wl_*.py")} imports.update({iface.name: module for iface in protocol.interface}) - protocol.output(str(args.output_dir), imports) - print(f"generated {module} from {xml} into {args.output_dir}") + protocol.output(str(output_dir), imports) + print(f"generated {module} from {xml} into {output_dir}") + return module + + +def main(argv: list[str] | None = None) -> int: + parser = argparse.ArgumentParser(description=__doc__.splitlines()[0]) + parser.add_argument( + "--pointer-xml", type=Path, default=None, help=f"path to .../{POINTER_XML_SUFFIX}" + ) + parser.add_argument( + "--keyboard-xml", type=Path, default=None, help=f"path to .../{KEYBOARD_XML_NAME}" + ) + parser.add_argument( + "--only", + choices=("pointer", "keyboard"), + default=None, + help="regenerate one of the two; the default is both", + ) + parser.add_argument( + "--output-dir", + type=Path, + default=Path(__file__).resolve().parent, + help="where the protocol packages are written (default: next to this file)", + ) + args = parser.parse_args(argv) + + wanted = ("pointer", "keyboard") if args.only is None else (args.only,) + if "pointer" in wanted: + xml = args.pointer_xml or find_pointer_xml() + if xml is None: + parser.error( + f"could not find {POINTER_XML_SUFFIX}; pass --pointer-xml " + "(is wlr-protocols in the shell?)" + ) + generate(xml, args.output_dir) + if "keyboard" in wanted: + xml = args.keyboard_xml or find_keyboard_xml() + if xml is None: + parser.error( + f"could not find {KEYBOARD_XML_NAME}; pass --keyboard-xml, or set " + f"${ENV_PROTOCOL_DIR} to \"$(nix eval --raw nixpkgs#hyprland.src)/protocols\" " + "(it is not in wayland-protocols or wlr-protocols -- see the module docstring)" + ) + generate(xml, args.output_dir) return 0 diff --git a/src/hhstream_pointer/_protocol/virtual_keyboard_unstable_v1/__init__.py b/src/hhstream_pointer/_protocol/virtual_keyboard_unstable_v1/__init__.py new file mode 100644 index 0000000..34b8c79 --- /dev/null +++ b/src/hhstream_pointer/_protocol/virtual_keyboard_unstable_v1/__init__.py @@ -0,0 +1,28 @@ +# This file has been autogenerated by the pywayland scanner + +# Copyright © 2008-2011 Kristian Høgsberg +# Copyright © 2010-2013 Intel Corporation +# Copyright © 2012-2013 Collabora, Ltd. +# Copyright © 2018 Purism SPC +# +# Permission is hereby granted, free of charge, to any person obtaining a +# copy of this software and associated documentation files (the "Software"), +# to deal in the Software without restriction, including without limitation +# the rights to use, copy, modify, merge, publish, distribute, sublicense, +# and/or sell copies of the Software, and to permit persons to whom the +# Software is furnished to do so, subject to the following conditions: +# +# The above copyright notice and this permission notice (including the next +# paragraph) shall be included in all copies or substantial portions of the +# Software. +# +# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL +# THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING +# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER +# DEALINGS IN THE SOFTWARE. + +from .zwp_virtual_keyboard_manager_v1 import ZwpVirtualKeyboardManagerV1 # noqa: F401 +from .zwp_virtual_keyboard_v1 import ZwpVirtualKeyboardV1 # noqa: F401 diff --git a/src/hhstream_pointer/_protocol/virtual_keyboard_unstable_v1/zwp_virtual_keyboard_manager_v1.py b/src/hhstream_pointer/_protocol/virtual_keyboard_unstable_v1/zwp_virtual_keyboard_manager_v1.py new file mode 100644 index 0000000..2d692e1 --- /dev/null +++ b/src/hhstream_pointer/_protocol/virtual_keyboard_unstable_v1/zwp_virtual_keyboard_manager_v1.py @@ -0,0 +1,95 @@ +# This file has been autogenerated by the pywayland scanner + +# Copyright © 2008-2011 Kristian Høgsberg +# Copyright © 2010-2013 Intel Corporation +# Copyright © 2012-2013 Collabora, Ltd. +# Copyright © 2018 Purism SPC +# +# Permission is hereby granted, free of charge, to any person obtaining a +# copy of this software and associated documentation files (the "Software"), +# to deal in the Software without restriction, including without limitation +# the rights to use, copy, modify, merge, publish, distribute, sublicense, +# and/or sell copies of the Software, and to permit persons to whom the +# Software is furnished to do so, subject to the following conditions: +# +# The above copyright notice and this permission notice (including the next +# paragraph) shall be included in all copies or substantial portions of the +# Software. +# +# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL +# THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING +# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER +# DEALINGS IN THE SOFTWARE. + +from __future__ import annotations + +import enum + +from pywayland.protocol_core import ( + Argument, + ArgumentType, + Global, + Interface, + Proxy, + Resource, +) + +from ..wayland import WlSeat +from .zwp_virtual_keyboard_v1 import ZwpVirtualKeyboardV1 + + +class ZwpVirtualKeyboardManagerV1(Interface): + """Virtual keyboard manager + + A virtual keyboard manager allows an application to provide keyboard input + events as if they came from a physical keyboard. + """ + + name = "zwp_virtual_keyboard_manager_v1" + version = 1 + + class error(enum.IntEnum): + unauthorized = 0 + + +class ZwpVirtualKeyboardManagerV1Proxy(Proxy[ZwpVirtualKeyboardManagerV1]): + interface = ZwpVirtualKeyboardManagerV1 + + @ZwpVirtualKeyboardManagerV1.request( + Argument(ArgumentType.Object, interface=WlSeat), + Argument(ArgumentType.NewId, interface=ZwpVirtualKeyboardV1), + ) + def create_virtual_keyboard(self, seat: WlSeat) -> Proxy[ZwpVirtualKeyboardV1]: + """Create a new virtual keyboard + + Creates a new virtual keyboard associated to a seat. + + If the compositor enables a keyboard to perform arbitrary actions, it + should present an error when an untrusted client requests a new + keyboard. + + :param seat: + :type seat: + :class:`~pywayland.protocol.wayland.WlSeat` + :returns: + :class:`~pywayland.protocol.virtual_keyboard_unstable_v1.ZwpVirtualKeyboardV1` + """ + id = self._marshal_constructor(0, ZwpVirtualKeyboardV1, seat) + return id + + +class ZwpVirtualKeyboardManagerV1Resource(Resource): + interface = ZwpVirtualKeyboardManagerV1 + + +class ZwpVirtualKeyboardManagerV1Global(Global): + interface = ZwpVirtualKeyboardManagerV1 + + +ZwpVirtualKeyboardManagerV1._gen_c() +ZwpVirtualKeyboardManagerV1.proxy_class = ZwpVirtualKeyboardManagerV1Proxy +ZwpVirtualKeyboardManagerV1.resource_class = ZwpVirtualKeyboardManagerV1Resource +ZwpVirtualKeyboardManagerV1.global_class = ZwpVirtualKeyboardManagerV1Global diff --git a/src/hhstream_pointer/_protocol/virtual_keyboard_unstable_v1/zwp_virtual_keyboard_v1.py b/src/hhstream_pointer/_protocol/virtual_keyboard_unstable_v1/zwp_virtual_keyboard_v1.py new file mode 100644 index 0000000..cf84ac9 --- /dev/null +++ b/src/hhstream_pointer/_protocol/virtual_keyboard_unstable_v1/zwp_virtual_keyboard_v1.py @@ -0,0 +1,176 @@ +# This file has been autogenerated by the pywayland scanner + +# Copyright © 2008-2011 Kristian Høgsberg +# Copyright © 2010-2013 Intel Corporation +# Copyright © 2012-2013 Collabora, Ltd. +# Copyright © 2018 Purism SPC +# +# Permission is hereby granted, free of charge, to any person obtaining a +# copy of this software and associated documentation files (the "Software"), +# to deal in the Software without restriction, including without limitation +# the rights to use, copy, modify, merge, publish, distribute, sublicense, +# and/or sell copies of the Software, and to permit persons to whom the +# Software is furnished to do so, subject to the following conditions: +# +# The above copyright notice and this permission notice (including the next +# paragraph) shall be included in all copies or substantial portions of the +# Software. +# +# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL +# THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING +# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER +# DEALINGS IN THE SOFTWARE. + +from __future__ import annotations + +import enum + +from pywayland.protocol_core import ( + Argument, + ArgumentType, + Global, + Interface, + Proxy, + Resource, +) + + +class ZwpVirtualKeyboardV1(Interface): + """Virtual keyboard + + The virtual keyboard provides an application with requests which emulate + the behaviour of a physical keyboard. + + This interface can be used by clients on its own to provide raw input + events, or it can accompany the input method protocol. + """ + + name = "zwp_virtual_keyboard_v1" + version = 1 + + class error(enum.IntEnum): + no_keymap = 0 + + +class ZwpVirtualKeyboardV1Proxy(Proxy[ZwpVirtualKeyboardV1]): + interface = ZwpVirtualKeyboardV1 + + @ZwpVirtualKeyboardV1.request( + Argument(ArgumentType.Uint), + Argument(ArgumentType.FileDescriptor), + Argument(ArgumentType.Uint), + ) + def keymap(self, format: int, fd: int, size: int) -> None: + """Keyboard mapping + + Provide a file descriptor to the compositor which can be memory-mapped + to provide a keyboard mapping description. + + Format carries a value from the keymap_format enumeration. + + :param format: + keymap format + :type format: + `ArgumentType.Uint` + :param fd: + keymap file descriptor + :type fd: + `ArgumentType.FileDescriptor` + :param size: + keymap size, in bytes + :type size: + `ArgumentType.Uint` + """ + self._marshal(0, format, fd, size) + + @ZwpVirtualKeyboardV1.request( + Argument(ArgumentType.Uint), + Argument(ArgumentType.Uint), + Argument(ArgumentType.Uint), + ) + def key(self, time: int, key: int, state: int) -> None: + """Key event + + A key was pressed or released. The time argument is a timestamp with + millisecond granularity, with an undefined base. All requests regarding + a single object must share the same clock. + + Keymap must be set before issuing this request. + + State carries a value from the key_state enumeration. + + :param time: + timestamp with millisecond granularity + :type time: + `ArgumentType.Uint` + :param key: + key that produced the event + :type key: + `ArgumentType.Uint` + :param state: + physical state of the key + :type state: + `ArgumentType.Uint` + """ + self._marshal(1, time, key, state) + + @ZwpVirtualKeyboardV1.request( + Argument(ArgumentType.Uint), + Argument(ArgumentType.Uint), + Argument(ArgumentType.Uint), + Argument(ArgumentType.Uint), + ) + def modifiers(self, mods_depressed: int, mods_latched: int, mods_locked: int, group: int) -> None: + """Modifier and group state + + Notifies the compositor that the modifier and/or group state has + changed, and it should update state. + + The client should use :func:`WlKeyboard.modifiers() + ` event to synchronize + its internal state with seat state. + + Keymap must be set before issuing this request. + + :param mods_depressed: + depressed modifiers + :type mods_depressed: + `ArgumentType.Uint` + :param mods_latched: + latched modifiers + :type mods_latched: + `ArgumentType.Uint` + :param mods_locked: + locked modifiers + :type mods_locked: + `ArgumentType.Uint` + :param group: + keyboard layout + :type group: + `ArgumentType.Uint` + """ + self._marshal(2, mods_depressed, mods_latched, mods_locked, group) + + @ZwpVirtualKeyboardV1.request(version=1) + def destroy(self) -> None: + """Destroy the virtual keyboard keyboard object + """ + self._marshal(3) + self._destroy() + + +class ZwpVirtualKeyboardV1Resource(Resource): + interface = ZwpVirtualKeyboardV1 + + +class ZwpVirtualKeyboardV1Global(Global): + interface = ZwpVirtualKeyboardV1 + + +ZwpVirtualKeyboardV1._gen_c() +ZwpVirtualKeyboardV1.proxy_class = ZwpVirtualKeyboardV1Proxy +ZwpVirtualKeyboardV1.resource_class = ZwpVirtualKeyboardV1Resource +ZwpVirtualKeyboardV1.global_class = ZwpVirtualKeyboardV1Global diff --git a/src/hhstream_pointer/backend.py b/src/hhstream_pointer/backend.py index c82807d..c7d5a4d 100644 --- a/src/hhstream_pointer/backend.py +++ b/src/hhstream_pointer/backend.py @@ -1,10 +1,27 @@ -"""The pywayland half: one virtual pointer per output, created on demand. +"""The pywayland half: one virtual pointer per output, plus one virtual keyboard. This is the only module that imports pywayland, so everything above it can be tested without a compositor. It implements :class:`hhstream_pointer.ops.PointerSink` and nothing else; the decisions are all next door. -Three things here are load-bearing: +The keyboard half is deliberately unlike the pointer half in three ways, each +forced by the protocol rather than chosen: + +* **One device, not one per output.** ``create_virtual_keyboard(seat)`` takes + no output — a virtual keyboard is seat-global and keys go to whatever has + keyboard focus. There is nothing to aim and nothing to create on demand. +* **The keymap is uploaded once**, after connect and before the socket is + listening, because ``key`` or ``modifiers`` before ``keymap`` is the protocol + error ``no_keymap`` and kills the connection. A *second* upload is not a + refresh either: Hyprland replaces its XKB state without walking the keys it + thinks are down, so re-uploading under a held modifier strands it. +* **A missing global is survivable.** ``ManagerTooOld`` aborts start-up for + the *pointer* manager because a version-1 pointer aims at the whole desktop + and every click would land somewhere wrong. A compositor with no + ``zwp_virtual_keyboard_manager_v1`` still gets a working cursor, so the + keyboard is simply absent and the keyboard ops refuse. + +Three things on the pointer side are load-bearing: * ``zwlr_virtual_pointer_manager_v1`` is bound at **version 2** and pointers are created with :func:`create_virtual_pointer_with_output`. Version 1's @@ -32,7 +49,9 @@ from pathlib import Path from pywayland.client import Display from pywayland.protocol.wayland import WlOutput, WlSeat +from ._protocol.virtual_keyboard_unstable_v1 import ZwpVirtualKeyboardManagerV1 from ._protocol.wlr_virtual_pointer_unstable_v1 import ZwlrVirtualPointerManagerV1 +from .keymap import XKB_V1 log = logging.getLogger("hhstream_pointer.backend") @@ -46,6 +65,11 @@ OUTPUT_VERSION = 4 #: The manager version that first carried ``create_virtual_pointer_with_output``. MANAGER_VERSION = 2 +#: ``zwp_virtual_keyboard_manager_v1`` is version 1 and only version 1. +#: Measured on the running compositor by ``tests/keyboard_probe.py``, not +#: assumed: the plan's gate was that the global exists under this name. +KEYBOARD_MANAGER_VERSION = 1 + class CompositorUnavailable(Exception): """No display to connect to, or the connection died. Fatal; do not guess.""" @@ -71,6 +95,16 @@ class OutputUnknown(Exception): """The compositor advertises no output by that name.""" +class KeyboardUnavailable(Exception): + """No virtual keyboard: the global is absent, or the keymap never went up. + + Not fatal, and not :class:`CompositorUnavailable`: the display is fine and + the cursor still works. :mod:`hhstream_pointer.ops` asks + :meth:`WaylandSink.has_keyboard` instead of catching this, so the question + can be answered without provoking it — which is what ``release_all`` needs. + """ + + def find_wayland_display(runtime_dir: Path) -> str: """The name of the compositor's socket inside its runtime directory. @@ -118,6 +152,9 @@ class WaylandSink: self._manager = None self._manager_version = 0 self._output_version = 0 + self._keyboard_manager = None + self._keyboard_manager_version = 0 + self._keyboard = None #: registry global id -> output self._outputs: dict[int, _Output] = {} #: output name -> virtual pointer proxy @@ -162,16 +199,64 @@ class WaylandSink: "to learn output names" ) log.info( - "connected to %s: manager v%d, %d output(s)", + "connected to %s: manager v%d, %d output(s), keyboard manager %s", name, self._manager_version, len(self._outputs), + f"v{self._keyboard_manager_version}" if self._keyboard_manager else "absent", ) + def upload_keymap(self, text: str) -> None: + """Create the one virtual keyboard and give it ``text``, once. + + Called between :meth:`connect` and the socket being listened on, which + is where the ordering rule lives: a listening socket is a promise that + the device works, and ``key`` before ``keymap`` is a protocol error + that kills the connection rather than returning an error we could + report. + + No-op when the compositor advertises no keyboard manager. + """ + + if self._keyboard_manager is None: + log.warning( + "no zwp_virtual_keyboard_manager_v1: the cursor will work and every " + "keyboard op will be refused" + ) + return + self._keyboard = self._keyboard_manager.create_virtual_keyboard(self._seat) + payload = text.encode("utf-8") + b"\0" + fd = os.memfd_create("hhstream-keymap", 0) + try: + os.ftruncate(fd, len(payload)) + with os.fdopen(os.dup(fd), "wb", closefd=True) as handle: + handle.write(payload) + # The size on the wire **includes the NUL**. Hyprland maps exactly + # this many bytes and hands the pointer to + # `xkb_keymap_new_from_string`, which wants a C string, so a size + # of `len(text)` reads off the end of the mapping -- and the + # symptom is a keymap that silently will not compile, which looks + # from here exactly like a compositor that has no keyboard at all. + self._keyboard.keymap(XKB_V1, fd, len(payload)) + # A round trip, not a flush: the compositor has to have received + # and mapped the fd before we close our end of it. + self._sync() + finally: + os.close(fd) + # Once, here, and the reason is Hyprland-specific: `destroy` of a + # virtual keyboard does not clear the modifier mask (measured, see + # tests/README-keyboard-probe.md), and a client keeps the last + # `wl_keyboard.modifiers` it was sent. Starting from a known zero means + # a previous driver's stuck Shift is not inherited. + self._keyboard.modifiers(0, 0, 0, 0) + self._flush() + log.info("uploaded a %d-byte keymap to the virtual keyboard", len(payload)) + def close(self) -> None: if self._display is None: return self._pointers.clear() + self._keyboard = None try: self._display.disconnect() finally: @@ -201,8 +286,35 @@ class WaylandSink: self._pointer(output).frame() self._flush() + def has_keyboard(self) -> bool: + return self._keyboard is not None + + def key(self, code: int, state: int) -> None: + """An evdev code and a key state. Flushed, because there is no frame. + + ``zwp_virtual_keyboard_v1`` has no end-of-gesture request, so a key + that waited for one would never be delivered. The flush is the same + one every pointer method above does. + """ + + self._require_keyboard().key(_now_ms(), code, state) + self._flush() + + def modifiers(self, depressed: int, latched: int, locked: int, group: int) -> None: + self._require_keyboard().modifiers(depressed, latched, locked, group) + self._flush() + # -- internals -------------------------------------------------------- + def _require_keyboard(self): + keyboard = self._keyboard + if keyboard is None: + raise KeyboardUnavailable( + "no virtual keyboard: the compositor advertises no " + "zwp_virtual_keyboard_manager_v1" + ) + return keyboard + def _pointer(self, output: str): existing = self._pointers.get(output) if existing is not None: @@ -247,6 +359,11 @@ class WaylandSink: self._manager_version = version if version >= MANAGER_VERSION: self._manager = registry.bind(global_id, ZwlrVirtualPointerManagerV1, MANAGER_VERSION) + elif interface == ZwpVirtualKeyboardManagerV1.name: + self._keyboard_manager_version = version + self._keyboard_manager = registry.bind( + global_id, ZwpVirtualKeyboardManagerV1, KEYBOARD_MANAGER_VERSION + ) elif interface == WlSeat.name and self._seat is None: self._seat = registry.bind(global_id, WlSeat, min(version, WlSeat.version)) elif interface == WlOutput.name: diff --git a/src/hhstream_pointer/keymap.py b/src/hhstream_pointer/keymap.py new file mode 100644 index 0000000..f449da5 --- /dev/null +++ b/src/hhstream_pointer/keymap.py @@ -0,0 +1,394 @@ +"""Keysym names and text to ``(evdev code, modifier mask)``, via one XKB keymap. + +This is the only module that imports xkbcommon, the way :mod:`.backend` is the +only one that imports pywayland. Everything above it — :mod:`.ops`, the broker, +the CLI — speaks keysym *names*, which is the same division +:mod:`.buttons` draws for the pointer: names on our sockets, evdev integers only +on the Wayland request. + +``buttons.py`` can be a hand-written table because +``zwlr_virtual_pointer_v1.button`` takes those codes directly and there are +eight of them. Keysyms cannot: which code produces ``z`` and which modifiers +have to be held to get it are properties of *the layout we uploaded*, and a +second table beside the keymap would be a table that can disagree with it. So +every answer here is read out of the compiled keymap. + +Three decisions worth stating, because each one has a wrong version that looks +right: + +* **The mask, not a Shift keycode, is what makes a capital.** Hyprland's + virtual-keyboard device does not run ``updateXkbStateWithKey`` + (``devices/VirtualKeyboard.cpp`` vs ``devices/Keyboard.cpp`` at v0.56.2), so a + virtual ``key(KEY_LEFTSHIFT)`` changes no modifier state and produces no + ``wl_keyboard.modifiers``. The mask has to be sent explicitly, and sending + *both* a mask and a synthetic Shift key is how a toolkit applies Shift twice. + :meth:`Keymap.resolve_text` therefore returns a mask per character and never + a Shift action. +* **A modifier is whatever this keymap says is one.** Not a name list: a + layout where ``@`` is a level-3 symbol needs ``ISO_Level3_Shift``'s mask, and + a Shift-only special case would quietly produce the wrong character. The set + is computed by pressing each key in a throwaway XKB state and reading the + depressed mask back, which on ``us``/``pc105`` yields exactly the expected + names (see :data:`EXPECTED_MODIFIERS`). +* **A lock is not a modifier.** ``Caps_Lock`` and ``Num_Lock`` report a + *locked* mask, and a ``type`` performed while one of them is held would + produce a case we did not ask for, so ``type`` refuses rather than guessing. + +The whole string is resolved before anything is emitted, so an unmappable +character fails the request instead of typing a prefix. Errors carry the +scalar *index*, never the character and never the string: the typed text is a +password as often as not, and :class:`Rejected` messages reach the driver's log. +""" + +from __future__ import annotations + +from dataclasses import dataclass + +#: ``wl_keyboard.keymap_format.xkb_v1``. Written down rather than read off the +#: generated protocol module because the only copy of +#: ``virtual-keyboard-unstable-v1.xml`` available here (Hyprland's) *names* +#: ``keymap_format`` in the ``keymap`` request's description and never defines +#: the enum. See ``_protocol/regenerate.py``. +XKB_V1 = 1 + +#: A Wayland/evdev keycode is the XKB keycode minus 8. ``wl_keyboard.key`` and +#: ``zwp_virtual_keyboard_v1.key`` both carry the evdev value; xkbcommon's +#: tables are indexed by the XKB one. +EVDEV_OFFSET = 8 + +#: The largest ``type`` we accept, in Unicode scalars — not bytes. Scalars +#: because that is what the caller counts and what the resolver walks; a byte +#: cap would let 4096 emoji through on one side of the wire and not the other. +MAX_TEXT_SCALARS = 4096 + +#: Characters with no printable keysym that are still worth typing. Everything +#: else below U+0020 is refused: a C0 control is either one of these two or a +#: caller that pasted a terminal escape. +#: +#: ``\r`` is deliberately **not** here. The plan exempts ``\n`` and ``\t`` and +#: nothing else, and a carriage return silently typed as ``Return`` means a +#: caller who pasted CRLF gets two newlines per line with no way to find out. +CONTROL_KEYSYMS = {"\n": "Return", "\t": "Tab"} + +#: What the detection below **measures** on ``us``/``pc105``. Not used to +#: decide anything — the keymap decides — but asserted in the tests, because a +#: detection that silently returned an empty set would make every ``type`` look +#: modifier-free and every chord a no-op, and nothing else would notice. +#: +#: Shorter than the canonical list of modifier keysyms, and deliberately: the +#: review's set also names ``Meta_L/R`` and ``Hyper_L/R``, and **no keycode on +#: this layout carries them**, so a resolver that claimed them would be +#: claiming keys it cannot press. That is the whole argument for measuring +#: rather than listing. +EXPECTED_MODIFIERS = frozenset( + { + "Shift_L", + "Shift_R", + "Control_L", + "Control_R", + "Alt_L", + "Alt_R", + "Super_L", + "Super_R", + "ISO_Level3_Shift", + "ISO_Level5_Shift", + } +) + +#: Keysyms this layout treats as locks rather than modifiers. ``type`` refuses +#: while one of these is held; see :meth:`Keymap.is_modifier`. +EXPECTED_LOCKS = frozenset({"Caps_Lock", "Num_Lock"}) + + +class KeymapError(Exception): + """The layout itself is unusable. Fatal at start-up, exit 2.""" + + +class UnknownKey(Exception): + """A keysym name, or a character, that this layout cannot produce. + + A caller error, not a compositor failure: it carries no compositor state + and the same request will fail the same way forever. The driver answers it + with ``kind: invalid_argument`` so the broker can report exit 2 rather than + exit 10. + """ + + +@dataclass(frozen=True) +class Action: + """One keystroke: an evdev code and the modifier mask it needs. + + ``mask`` is what must be *depressed* for this keycode to produce the wanted + keysym — 0 for ``a``, Shift's bit for ``A``, LevelThree's for a ``de`` + ``@``. It is not a key to press; see the module docstring. + """ + + code: int + mask: int + #: The keysym name, for the held-key record and for log lines. A name and + #: not the character: `keys` on `pointer.state` reads as names everywhere. + name: str + + +def build( + *, + layout: str = "us", + model: str = "pc105", + variant: str = "", + options: str = "", + rules: str = "evdev", +) -> "Keymap": + """Compile one keymap, or raise :class:`KeymapError`. + + ``rules`` is an argument rather than a constant only so a test can prove + the failure path; there is deliberately no flag for it (the review: + "Do not add a `rules` option; the driver hardcodes `evdev`"). + """ + + if not layout: + # xkbcommon accepts an empty layout and compiles the *same keymap as + # `us`* -- `xkb_symbols "pc_us_inet(evdev)"`. So `--xkb-layout ''` + # would look configured, type `us`, and never say so. Refused for the + # same reason the comma is: a layout that silently is not the one the + # operator named. + raise KeymapError("no layout given; pass one (the default is 'us')") + if "," in layout: + # Refused here rather than by xkbcommon, which accepts `us,ru` happily + # and gives a two-group keymap. v1 sends `group = 0` in every + # `modifiers` request and has no group-switch keysym, so the second + # group would be unreachable and every caller asking for a Cyrillic + # character would get a silent Latin one. + raise KeymapError( + f"layout {layout!r} names more than one group; v1 uploads a single " + "group and always sends group 0, so the others would be unreachable" + ) + try: + from xkbcommon import xkb + except ImportError as exc: # pragma: no cover - the dependency is not optional + raise KeymapError(f"xkbcommon is unavailable: {exc}") from None + + try: + compiled = xkb.Context().keymap_new_from_names( + rules=rules, model=model, layout=layout, variant=variant, options=options + ) + except Exception as exc: + # xkbcommon logs its own multi-line complaint to stderr and then hands + # back a bare failure, so the layout is named again here: the operator + # set one string and that is what they need to see. + raise KeymapError( + f"xkbcommon will not compile rules={rules!r} model={model!r} " + f"layout={layout!r} variant={variant!r} options={options!r}: {exc}" + ) from None + return Keymap(compiled, xkb) + + +class Keymap: + """A compiled layout, plus the two lookups the driver needs from it. + + Built once, at start-up, and uploaded once. Not rebuilt per request: a + second ``keymap`` upload replaces the compositor's XKB state without + walking its set of held keys, so re-uploading under a held modifier is how + a chord gets stuck. + """ + + def __init__(self, compiled, xkb) -> None: + self._keymap = compiled + self._xkb = xkb + #: keysym name -> Action. Built eagerly: the whole point is that a + #: lookup cannot disagree with the uploaded keymap, and a lazy table + #: would be a second source of truth with a cache in front of it. + self._by_name: dict[str, Action] = {} + #: keysym number -> Action, which is what a character resolves through. + self._by_keysym: dict[int, Action] = {} + #: keysym name -> the mask this key *contributes* when held down. + self._modifier_masks: dict[str, int] = {} + #: keysym names that lock rather than modify (``Caps_Lock``). + self._locks: set[str] = set() + self._index() + + # -- the table -------------------------------------------------------- + + def _index(self) -> None: + keymap, xkb = self._keymap, self._xkb + #: (popcount, mask, keycode) -> the best candidate for a keysym, so a + #: keysym reachable both unshifted and shifted resolves unshifted, and + #: a tie between two keycodes resolves to the lower one. Deterministic + #: on purpose: "which keycode is `1`" must not depend on dict order. + best: dict[int, tuple[tuple[int, int, int], Action]] = {} + for keycode in range(keymap.min_keycode(), keymap.max_keycode() + 1): + evdev = keycode - EVDEV_OFFSET + if evdev < 0: + continue + self._index_modifier(keycode, evdev) + # Group 0 only: v1 is a single group (plan §4), so a level table + # read from another group would describe keys we can never reach. + for level in range(keymap.num_levels_for_key(keycode, 0)): + masks = keymap.key_get_mods_for_level(keycode, 0, level) or [0] + mask = min(masks, key=lambda m: (bin(m).count("1"), m)) + for keysym in keymap.key_get_syms_by_level(keycode, 0, level): + name = xkb.keysym_get_name(keysym) + if not name: + continue + rank = (bin(mask).count("1"), mask, keycode) + current = best.get(keysym) + if current is not None and current[0] <= rank: + continue + best[keysym] = (rank, Action(code=evdev, mask=mask, name=name)) + + for keysym, (_rank, action) in best.items(): + self._by_keysym[keysym] = action + # First name wins, and the names are unique per keysym because + # `keysym_get_name` is a function of the keysym alone. + self._by_name.setdefault(action.name, action) + + def _index_modifier(self, keycode: int, evdev: int) -> None: + """Record what holding this key does to the modifier masks. + + Measured rather than listed: press the key in a throwaway state and + read the serialised masks back. A key with a depressed mask and no + locked mask is a modifier; one with a locked mask is a lock, and the + two are not interchangeable for ``type``. + """ + + xkb = self._xkb + state = self._keymap.state_new() + state.update_key(keycode, xkb.XKB_KEY_DOWN) + depressed = state.serialize_mods(xkb.XKB_STATE_MODS_DEPRESSED) + locked = state.serialize_mods(xkb.XKB_STATE_MODS_LOCKED) + if not depressed and not locked: + return + for level in range(self._keymap.num_levels_for_key(keycode, 0)): + for keysym in self._keymap.key_get_syms_by_level(keycode, 0, level): + name = xkb.keysym_get_name(keysym) + if not name: + continue + if locked: + self._locks.add(name) + else: + self._modifier_masks.setdefault(name, depressed) + + # -- what the driver asks --------------------------------------------- + + def text(self) -> str: + """The keymap as the XKB text the ``keymap`` request wants uploaded.""" + + return self._keymap.get_as_bytes().decode("utf-8") + + def resolve_name(self, name: str) -> Action: + """One keysym name to an :class:`Action`, or :class:`UnknownKey`. + + The same resolver named keys and characters both go through, so + ``keyboard key z`` and ``keyboard type z`` cannot disagree about which + keycode ``z`` is on a ``de`` layout. + """ + + if not isinstance(name, str) or not name: + raise UnknownKey("a key name is required") + if name.startswith("dead_"): + # Named by many layouts and typeable by none of them in one event: + # a dead key is half of a compose sequence, and v1 does not emit + # the other half. Refused rather than sent, because sending it + # arms the next keystroke in the focused application. + raise UnknownKey( + f"{name!r} is a dead key; v1 does not emit compose sequences" + ) + action = self._by_name.get(name) + if action is not None: + return action + # Fall back through the keysym number so an alias (`Return` vs + # `KP_Enter` is not one, but `XF86...` spellings and `0x…` forms are) + # resolves to the same action rather than looking unknown. + keysym = self._xkb.keysym_from_name(name) + action = self._by_keysym.get(keysym) if keysym else None + if action is None: + raise UnknownKey( + f"{name!r} is not on the uploaded keymap; it has no keycode under " + "this layout" + ) + return action + + def is_modifier(self, name: str) -> bool: + """True for a key that contributes to the depressed mask. + + ``Caps_Lock`` is **not** one of these: it locks, and a ``type`` while a + lock is held would produce a case nobody asked for. + """ + + return name in self._modifier_masks + + def modifier_mask(self, name: str) -> int: + """The mask this key contributes while held, or 0 if it contributes none.""" + + return self._modifier_masks.get(name, 0) + + def modifier_names(self) -> frozenset[str]: + """Every keysym name this layout treats as a modifier. For tests and help.""" + + return frozenset(self._modifier_masks) + + def lock_names(self) -> frozenset[str]: + """Keysym names that lock (``Caps_Lock``, ``Num_Lock``).""" + + return frozenset(self._locks) + + def resolve_text(self, text: str) -> list[Action]: + """A whole string to actions, or :class:`UnknownKey` naming the index. + + Resolved completely before returning, which is the property the caller + depends on: a string whose fifth character is unmappable emits nothing + at all rather than four characters and an error. An empty string is + an empty list and not an error — it is a no-op the caller may well have + computed. + """ + + if not isinstance(text, str): + raise UnknownKey("text must be a string") + if len(text) > MAX_TEXT_SCALARS: + raise UnknownKey( + f"text is {len(text)} scalars, over the {MAX_TEXT_SCALARS} limit" + ) + actions: list[Action] = [] + for index, character in enumerate(text): + actions.append(self._resolve_character(character, index)) + return actions + + def _resolve_character(self, character: str, index: int) -> Action: + named = CONTROL_KEYSYMS.get(character) + if named is not None: + try: + return self.resolve_name(named) + except UnknownKey: + raise UnknownKey( + f"scalar {index} needs keysym {named!r}, which this layout " + "does not carry" + ) from None + keysym = _keysym_for(character) + action = self._by_keysym.get(keysym) + if action is None: + # The index and the codepoint, never the character: this message + # is logged, and the string it came from is often a password. + raise UnknownKey( + f"scalar {index} (U+{ord(character):04X}) is not typeable on the " + "uploaded layout" + ) + if action.name.startswith("dead_"): + raise UnknownKey( + f"scalar {index} (U+{ord(character):04X}) resolves to the dead key " + f"{action.name!r}; v1 does not emit compose sequences" + ) + return action + + +def _keysym_for(character: str) -> int: + """The X keysym for one Unicode scalar. + + The two-range rule from ``xproto``: Latin-1 is its own keysym value, and + everything else is ``0x01000000 + codepoint``. Not ``xkb.keysym_from_name`` + with a one-character string, which resolves ``"a"`` by *name* and would + make the digit ``1`` and the keysym ``1`` the same lookup by accident. + """ + + codepoint = ord(character) + if 0x20 <= codepoint <= 0x7E or 0xA0 <= codepoint <= 0xFF: + return codepoint + return 0x01000000 + codepoint diff --git a/src/hhstream_pointer/ops.py b/src/hhstream_pointer/ops.py index 594a4c0..e05b3b1 100644 --- a/src/hhstream_pointer/ops.py +++ b/src/hhstream_pointer/ops.py @@ -6,18 +6,33 @@ a rejected request is answered, never fatal, because the broker is a long-lived peer and dropping its connection would cost it a cursor it still holds a lease on. -This module is the whole of the driver's logic and it touches no Wayland. It -speaks to a :class:`PointerSink` — "send this to the virtual pointer bound to -*this* output" — which is the one thing pywayland is needed for. That seam is -why the dispatcher can be tested without a compositor, and the test suite does -exactly that. +This module is the whole of the driver's logic and it touches no Wayland and no +xkbcommon. It speaks to a :class:`PointerSink` — "send this to the virtual +pointer bound to *this* output", plus "send this to the one virtual keyboard" — +and to a :class:`Keymap`, which turns a keysym name or a string into evdev +codes and modifier masks. Those two seams are why the dispatcher can be tested +without a compositor and without a layout, and the test suite does exactly +that. -The dispatcher keeps two pieces of *device* state, which is not lease state: +The dispatcher keeps three pieces of *device* state, which is not lease state: * the output of the last ``warp``, because ``button`` and ``frame`` carry no output of their own and there is only one cursor to aim; * which buttons are down and on which pointer, because ``release_all`` has to - report what it lifted and must lift it through the pointer it went down on. + report what it lifted and must lift it through the pointer it went down on; +* which keys are down, in press order, because ``release_all`` has to lift + those too — and, unlike buttons, has to put the modifier mask back to zero + afterwards. A virtual key-up does not clear the mask: Hyprland's virtual + keyboard never runs ``updateXkbStateWithKey``, so the mask is only ever what + we last said it was. + +**There is no keyboard output and no keyboard frame.** ``key`` and ``type`` +deliberately do not call :meth:`Dispatcher._aimed`: a virtual keyboard is +seat-global, there is nothing to aim, and a ``type`` that first demanded a warp +would fail for a caller that only ever wanted to type. Nor is there an +end-of-gesture ``frame`` — ``zwp_virtual_keyboard_v1`` has none, and a key +queued until one would never arrive. The sink flushes each request the way it +already flushes each pointer request. It keeps no notion of who is allowed to ask. That is the lease, and the lease lives in the broker. @@ -28,6 +43,12 @@ from __future__ import annotations from typing import Any, Protocol from . import buttons +# A pure exception class, and the one import that crosses the keymap seam. It +# costs nothing: `keymap.py` imports xkbcommon inside `build()`, never at module +# level, so this file still pulls in neither xkbcommon nor pywayland. The +# alternative -- catching `Exception` around a resolver call -- would report a +# genuine bug in this process as the caller's bad keysym. +from .keymap import UnknownKey class PointerSink(Protocol): @@ -49,18 +70,96 @@ class PointerSink(Protocol): def frame(self, output: str) -> None: """Commit the queued events. Nothing is delivered until this.""" + def has_keyboard(self) -> bool: + """Whether a virtual keyboard was created at start-up. + + False is a normal state, not a failure: a compositor that does not + advertise ``zwp_virtual_keyboard_manager_v1`` still gets a working + cursor, and the keyboard ops answer ``ok: false`` instead. It exists + as a question rather than an exception because ``release_all`` has to + know not to try. + """ + + def key(self, code: int, state: int) -> None: + """An evdev key code and a ``wl_keyboard.key_state``. No output.""" + + def modifiers(self, depressed: int, latched: int, locked: int, group: int) -> None: + """Set the seat's modifier masks. Not derived from :meth:`key`.""" + + +class Keymap(Protocol): + """Keysym names and text to ``(evdev code, mask)``. Implemented by :mod:`.keymap`. + + The same shape as :class:`PointerSink`: a seam, so this module holds no + layout knowledge. Everything it raises is a caller error — see + :class:`Rejected` and the ``kind`` it carries. + """ + + def resolve_name(self, name: str): ... + + def resolve_text(self, text: str) -> list: ... + + def is_modifier(self, name: str) -> bool: ... + + def modifier_mask(self, name: str) -> int: ... + + +#: ``kind`` for a rejection the *caller* caused: a keysym this layout does not +#: have, an unmappable character, a bad state word, a string over the cap. The +#: broker maps it to ``invalid_argument`` (exit 2). Without it every refusal +#: would arrive as ``driver_refused`` (exit 10), which says "the compositor +#: failed" about a typo — see the review's change 1. +KIND_INVALID = "invalid_argument" + +#: ``kind`` for everything else: an unknown op, no aimed output, no keyboard +#: global. The broker maps it to ``driver_refused`` (exit 10), which is what +#: the button and axis paths already do and what their tests already assert. +KIND_REFUSED = "refused" + class Rejected(Exception): - """The request was understood and refused; the text goes to the broker.""" + """The request was understood and refused; the text goes to the broker. + + ``kind`` is the machine-readable half. The text is for a human and is + never trusted by the broker to carry meaning, which is why a token exists + at all: "unmappable character" and "the compositor has no keyboard" are + different exit codes and must not be told apart by reading English. + """ + + def __init__(self, message: str, *, kind: str = KIND_REFUSED) -> None: + super().__init__(message) + self.kind = kind class Dispatcher: - def __init__(self, sink: PointerSink) -> None: + def __init__(self, sink: PointerSink, keymap: Keymap | None = None) -> None: self._sink = sink + #: ``None`` when the process started without a usable layout. Keyboard + #: ops then refuse; pointer ops are untouched, which is the whole point + #: of the argument being optional. + self._keymap = keymap self._output: str | None = None #: button name -> the output its press was sent to. Insertion-ordered, #: so a release_all lifts in the order things went down. self._pressed: dict[str, str] = {} + #: keysym name -> the mask it *contributes* while held, which is 0 for + #: an ordinary key. Insertion-ordered for the same reason as + #: ``_pressed``. Deliberately not the mask the key *needs* to produce + #: its symbol: ``type`` reads a zero contribution as "not a modifier, + #: refuse", so storing ``A``'s Shift requirement here would make a held + #: capital look like a held modifier. + self._keys: dict[str, int] = {} + #: keysym name -> the evdev code it was pressed as, so a second name + #: for a code that is already down can be refused. ``A`` and ``a`` are + #: one keycode: holding both would send two presses, the compositor + #: would drop the second, and the held set would be a lie for as long + #: as the lease lasted. + self._codes: dict[str, int] = {} + #: Whether we have ever sent a non-zero modifier mask. ``release_all`` + #: zeroes the mask only if something set it: a mask we never touched is + #: not ours to clear, and on a compositor with no keyboard global + #: sending one at all would raise and stop the buttons being lifted. + self._mask_touched = False def handle(self, request: Any) -> dict[str, Any]: """One request object to one response object. Never raises.""" @@ -68,7 +167,7 @@ class Dispatcher: try: return self._handle(request) except Rejected as exc: - return {"ok": False, "error": str(exc)} + return {"ok": False, "error": str(exc), "kind": exc.kind} def _handle(self, request: Any) -> dict[str, Any]: if not isinstance(request, dict): @@ -149,13 +248,132 @@ class Dispatcher: self._sink.frame(self._aimed()) return {"ok": True} + def _op_key(self, request: dict) -> dict[str, Any]: + """One keysym down or up. + + No output and no ``frame``: see the module docstring. A ``down`` of a + key the layout calls a modifier also sends the mask, because a virtual + ``key`` does not change Hyprland's modifier state — and the mask is + remembered so ``release_all`` can undo both halves. + """ + + name = request.get("key") + if not isinstance(name, str) or not name: + raise Rejected("'key' must be a keysym name", kind=KIND_INVALID) + state = request.get("state") + if state not in ("down", "up"): + raise Rejected( + f"'state' must be 'down' or 'up', got {state!r}", kind=KIND_INVALID + ) + keymap = self._require_keymap() + action = _resolved(keymap.resolve_name, name) + + if state == "down": + held_as = {code: held for held, code in self._codes.items()} + clash = held_as.get(action.code) + if clash is not None and clash != name: + # `A` and `a` are the same keycode at two levels. Holding both + # would send `key(30, pressed)` twice; the compositor drops the + # second because the code is already in its `m_pressed`, and + # then `release_all` sends two ups of which one is also + # dropped. Nothing breaks and the held set is wrong the whole + # time, which is worse than a refusal. + raise Rejected( + f"{name!r} is the same key as {clash!r}, which is already held", + kind=KIND_INVALID, + ) + contribution = keymap.modifier_mask(name) if keymap.is_modifier(name) else 0 + # The mask the *symbol* needs, before the press, exactly as `type` + # does it. Without this `keyboard down A` sends a bare code 30 and + # the window receives `a` -- and on `de`, `at` loses its level-three + # mask and becomes `q`. A modifier key's own `action.mask` is 0, so + # this is a no-op for `Shift_L` and the key-then-mask order below + # is unchanged. + if action.mask: + self._set_mask(self._baseline() | action.mask) + self._sink.key(action.code, buttons.STATES["down"]) + self._keys[name] = contribution + self._codes[name] = action.code + if contribution: + self._set_mask(self._baseline()) + return {"ok": True, "keys": list(self._keys), "lifted": []} + + if name not in self._keys: + # Reported rather than invented, the way `unpress` reports a button + # that was never down: a duplicate `up` is a caller that lost + # track, and sending a key-up the compositor never had a key-down + # for is how its `m_pressed` gets out of step with ours. + return {"ok": True, "keys": list(self._keys), "lifted": []} + was_modifier = bool(self._keys[name]) + self._sink.key(action.code, buttons.STATES["up"]) + # Forgotten only after the send, the way `_op_button` updates + # `_pressed` only after its send: a raise from the sink between the two + # would otherwise leave us believing the key is up while the compositor + # still has it down, and `release_all` would not try again. + del self._keys[name] + self._codes.pop(name, None) + if was_modifier or action.mask: + # Back to whatever is still held -- which for a capital is the + # baseline it had before, since its Shift was never a hold. + self._set_mask(self._baseline()) + return {"ok": True, "keys": list(self._keys), "lifted": [name]} + + def _op_type(self, request: dict) -> dict[str, Any]: + """A whole string, as key pairs with the mask each character needs. + + Resolved completely before the first sink call, so an unmappable + character emits nothing at all. Explicit modifier holds are the + *baseline*: each character's mask is ORed onto them, and the baseline + is restored afterwards, so ``down Control_L`` then ``type c`` is Ctrl+C + and Control is still down when this returns. + + ``modifiers`` is sent before every character and once more at the end, + rather than only when the mask changes. Three requests per character + is nothing on a local socket, and the alternative keeps a running + "what did we last send" that is wrong exactly once — after which every + capital in the string is a lower-case letter. + """ + + text = request.get("text") + if not isinstance(text, str): + raise Rejected("'text' must be a string", kind=KIND_INVALID) + held = [name for name, mask in self._keys.items() if not mask] + if held: + # Refused rather than typed around: a character sent while `a` is + # down arrives in an application that believes `a` is still being + # held, and the auto-repeat it has already started does not stop. + raise Rejected( + f"a non-modifier key is held ({', '.join(held)}); release it before " + "typing", + kind=KIND_INVALID, + ) + keymap = self._require_keymap() + actions = _resolved(keymap.resolve_text, text) + + baseline = self._baseline() + for action in actions: + self._set_mask(baseline | action.mask) + self._sink.key(action.code, buttons.STATES["down"]) + self._sink.key(action.code, buttons.STATES["up"]) + if actions: + # Back to the baseline, so a held Control survives and a Shift we + # synthesised for one capital does not. + self._set_mask(baseline) + return {"ok": True, "keys": list(self._keys)} + def _op_pressed(self, request: dict) -> dict[str, Any]: - return {"ok": True, "buttons": list(self._pressed)} + return {"ok": True, "buttons": list(self._pressed), "keys": list(self._keys)} def _op_release_all(self, request: dict) -> dict[str, Any]: """Lift everything. The broker calls this when a lease expires, so it must not depend on an aim: each button is lifted through the pointer it - was pressed on, even if the cursor has since been warped elsewhere.""" + was pressed on, even if the cursor has since been warped elsewhere. + + Buttons first, then keys in press order, then one zeroed ``modifiers`` + — and the mask is the part that is easy to leave out. A virtual + key-up does not clear it, so a lease that ended with Shift down would + hand the next holder a keyboard where every letter is a capital. + """ lifted = list(self._pressed) outputs = list(dict.fromkeys(self._pressed.values())) @@ -164,13 +382,33 @@ class Dispatcher: self._pressed.clear() for output in outputs: self._sink.frame(output) - return {"ok": True, "lifted": lifted} + + lifted_keys: list[str] = [] + if self._keys and self._keymap is not None: + # `_require_keymap` deliberately not used: it raises, and this op is + # the whole of expiry (`SessionManager._expire_pointer` calls it + # once). A refusal here would abandon the lift it has already done. + for name in list(self._keys): + self._sink.key(self._keymap.resolve_name(name).code, buttons.STATES["up"]) + lifted_keys = list(self._keys) + self._keys.clear() + self._codes.clear() + if self._mask_touched: + # Only if something set it. With no keyboard global at all this is + # False, and the button lifting above has to keep working: one + # `release_all` is the whole of expiry (`_expire_pointer`), so an + # exception here would leave a mouse button down. + self._sink.modifiers(0, 0, 0, 0) + self._mask_touched = False + return {"ok": True, "lifted": lifted, "lifted_keys": lifted_keys} _ops = { "warp": _op_warp, "button": _op_button, "axis": _op_axis, "frame": _op_frame, + "key": _op_key, + "type": _op_type, "pressed": _op_pressed, "release_all": _op_release_all, } @@ -182,6 +420,51 @@ class Dispatcher: raise Rejected("no output is aimed; warp before button or frame") return self._output + def _require_keymap(self) -> Keymap: + """The layout, or a refusal that is *not* a usage error. + + No keymap means the process started without a keyboard: either the + compositor advertises no ``zwp_virtual_keyboard_manager_v1`` or the + upload failed. Either way the caller's request was fine, so this + carries :data:`KIND_REFUSED` and the broker reports exit 10. + """ + + if self._keymap is None or not self._sink.has_keyboard(): + raise Rejected( + "this driver has no virtual keyboard; the compositor advertises no " + "zwp_virtual_keyboard_manager_v1, or no keymap was uploaded", + kind=KIND_REFUSED, + ) + return self._keymap + + def _baseline(self) -> int: + """The mask the explicitly held modifier keys add up to.""" + + mask = 0 + for contribution in self._keys.values(): + mask |= contribution + return mask + + def _set_mask(self, depressed: int) -> None: + self._sink.modifiers(depressed, 0, 0, 0) + if depressed: + self._mask_touched = True + + +def _resolved(resolve, argument): + """Call a keymap resolver, turning its refusal into a usage-level one. + + One place, so the ``kind`` is the same for a bad keysym and a bad + character, and so the resolver's own message survives — it is the one that + names the scalar *index* rather than the character, which is what keeps a + typed password out of the driver's log. + """ + + try: + return resolve(argument) + except UnknownKey as exc: + raise Rejected(str(exc), kind=KIND_INVALID) from None + def _require_output(request: dict) -> str: output = request.get("output") diff --git a/src/hhstream_session/__init__.py b/src/hhstream_session/__init__.py index d4ae4c6..db35def 100644 --- a/src/hhstream_session/__init__.py +++ b/src/hhstream_session/__init__.py @@ -35,10 +35,17 @@ The verb tree, beyond the original eight: session pointer move ID ... warp, --to X,Y or --by DX,DY (0..1, per output) session pointer click/down/up/release ID session pointer state who holds the cursor and what is pressed + session keyboard type ID TEXT one argument, raw UTF-8, no escapes + session keyboard key ID NAME tap: down then up + session keyboard down/up ID NAME -The pointer verbs share one precondition — the lease — and the lease id lives -in :mod:`hhstream_session.lease` between invocations, because the wire requires -it on every gesture and the CLI is one process per verb. +The pointer *and keyboard* verbs share one precondition — the pointer lease — +and the lease id lives in :mod:`hhstream_session.lease` between invocations, +because the wire requires it on every gesture and the CLI is one process per +verb. There is no ``keyboard acquire``: one ``wl_seat`` means one keyboard +focus, and the shipped ``follow_mouse = 1`` means another session's warp +retargets the keys, so a second lease would let session B move the pointer +while session A believed it was typing into its own window. """ from __future__ import annotations @@ -293,6 +300,9 @@ def _build_namespace(parser: argparse.ArgumentParser) -> None: # ---- pointer ----------------------------------------------------- _build_pointer(verbs, common) + # ---- keyboard ---------------------------------------------------- + _build_keyboard(verbs, common) + #: Button names the driver knows (``hhstream_pointer.buttons.CODES``), mirrored #: here rather than imported: this module's whole integration promise is that it @@ -475,6 +485,148 @@ def _build_pointer(verbs: Any, common: argparse.ArgumentParser) -> None: ) +#: Printed under `keyboard --help` and under every one of its verbs. It is the +#: single fact an agent gets wrong about this group, exactly as ACTIVITY_NOTE is +#: for the namespace: the keyboard has no lease of its own. +KEYBOARD_LEASE_NOTE = ( + "LEASE: every keyboard verb needs the POINTER lease and refuses with exit 9 " + "until 'hhstream session pointer acquire '. There is no 'keyboard " + "acquire': the compositor has one seat and one keyboard focus, and another " + "session's pointer warp would retarget the keys mid-string. 'pointer " + "release' lifts held keys as well as held buttons, and so does a lease " + "timeout." +) + + +def _build_keyboard(verbs: Any, common: argparse.ArgumentParser) -> None: + """``session keyboard `` — typing into whatever the seat focuses. + + A nested namespace for the same reason ``pointer`` is one: these four verbs + share a precondition nothing else here has. It is the *pointer* lease, and + saying that once in a group description is better than four times in four + help strings -- though the note is repeated per verb anyway, because + ``--help`` on a leaf is what an agent actually reads. + """ + + namespace = verbs.add_parser( + "keyboard", + parents=[common], + help="type into the session the seat is focused on, under the pointer lease", + description=( + "Keys go to 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: 'pointer acquire' warps into the session's own container " + "and the lease is what stops another session moving focus while you " + "type.\n\n" + "NAME is an XKB keysym name, not a number: 'a', 'A', 'Return', " + "'BackSpace', 'Left', 'Control_L', 'Shift_L'. It is resolved against " + "the layout the driver uploaded (set by the operator; 'us' by " + "default), so a name that layout does not carry is exit 2.\n\n" + "TEXT is one argument of raw UTF-8 and backslash escapes are NOT " + "interpreted: a newline is a real newline in the argument and the " + "shell does the quoting. A character the layout cannot produce " + "fails the whole string and types nothing -- there is no partial " + "type.\n\n" + "No keyboard verb counts as activity, exactly as no pointer verb " + "does. Call 'touch'." + ), + epilog=f"{KEYBOARD_LEASE_NOTE}\n\n{ACTIVITY_NOTE}", + formatter_class=argparse.RawDescriptionHelpFormatter, + ) + keys = namespace.add_subparsers(dest="keyboard_verb", metavar="VERB") + # With no verb, print this group's help rather than guessing: unlike + # `pointer`, there is no read-only verb here that could be the default -- + # held keys are reported by `pointer state`, which is where buttons are. + namespace.set_defaults( + func=_cmd_keyboard_usage, hhstream_session_handler=_cmd_keyboard_usage, json=False + ) + namespace.set_defaults(keyboard_parser=namespace) + + def add_key_verb(name: str, handler, **kwargs: Any): + sub = keys.add_parser( + name, + parents=[common], + epilog=KEYBOARD_LEASE_NOTE, + formatter_class=argparse.RawDescriptionHelpFormatter, + **kwargs, + ) + sub.set_defaults(func=handler, hhstream_session_handler=handler) + sub.add_argument("--json", action="store_true", help="emit the protocol object on stdout") + sub.add_argument( + "--lease", + metavar="ID", + help="the lease id from 'pointer acquire'. Omitted, the one that " + f"acquire cached is used (${lease.ENV_LEASE} overrides that).", + ) + sub.add_argument("id", help="session id") + return sub + + type_ = add_key_verb( + "type", + _cmd_keyboard_type, + help="type one string into the focused window", + description=( + "Type TEXT. One argument, raw UTF-8, no backslash escapes: '\n' is " + "a backslash and an n, and a newline is a newline. Capitals and " + "symbols are sent as a modifier MASK plus the letter's key, not as " + "a synthesized Shift keypress, because this compositor does not " + "derive the mask from an injected key.\n\n" + "Validation is complete before the first event: a character the " + "uploaded layout cannot produce fails the request and types " + "nothing, so there is never a half-typed prefix to clean up. On the " + "default 'us' layout that includes 'e' with an acute accent, and " + "every C0 control except newline and tab.\n\n" + "A modifier held with 'keyboard down' is a baseline: its mask is " + "ORed into every character and it is STILL HELD when this returns, " + "which is how a chord is spelled. A non-modifier key held is a " + "refusal, because the application still believes it is being held." + ), + ) + type_.add_argument( + "text", + help="the string to type, as ONE argument (quote it; a newline is a newline)", + ) + + tap = add_key_verb( + "key", + _cmd_keyboard_key, + help="tap one keysym: down then up", + description=( + "Press and release one key. This is the verb for 'Return', 'Tab', " + "'BackSpace' and the arrows -- anything 'type' cannot express " + "because it has no character." + ), + ) + tap.add_argument("name", help="XKB keysym name, e.g. Return, BackSpace, Left") + + for verb, state in (("down", "down"), ("up", "up")): + sub = add_key_verb( + verb, + _cmd_keyboard_hold, + help=( + "hold a key down without releasing it" + if state == "down" + else "release a key that was held down" + ), + description=( + "Half a tap. The justified use is a chord: 'down Control_L', " + "then 'type c', then 'up Control_L'.\n\n" + "HOLDING 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 for as long as it is " + "down -- up to the whole lease TTL. This is not configurable " + "here: the repeats are not ours to rate-limit. Measured on this " + "build at 25/s after 600ms.\n\n" + "The broker lifts whatever is still down on 'pointer release' " + "or on a lease timeout, so a crashed agent cannot leave a key " + "held." + ), + ) + sub.set_defaults(key_state=state) + sub.add_argument("name", help="XKB keysym name, e.g. Control_L, Shift_L") + + def _button_help() -> str: return f"one of: {', '.join(BUTTONS)} (default: left)" @@ -938,7 +1090,8 @@ def _cmd_pointer_acquire(args: argparse.Namespace) -> int: ) print( f"expires in {_fmt_timeout(reply.get('expires_in_s'))} with no further " - f"pointer verb; release it with: hhstream session pointer release {args.id}", + f"pointer OR keyboard verb; release it with: hhstream session pointer " + f"release {args.id}", file=sys.stderr, ) return int(ExitCode.OK) @@ -1057,6 +1210,108 @@ def _cmd_pointer_state(args: argparse.Namespace) -> int: return _finish(args, reply, fmt.render_pointer_state) +# -------------------------------------------------------------------------- +# the keyboard, on the same lease +# -------------------------------------------------------------------------- + + +def _cmd_keyboard_usage(args: argparse.Namespace) -> int: + """`session keyboard` with no verb. Prints help, exits 2. + + Not a default verb: the only read-only thing to say about the keyboard is + which keys are held, and that is `pointer state`, beside the buttons. + """ + + parser = getattr(args, "keyboard_parser", None) + if parser is not None: + parser.print_help(sys.stderr) + return int(ExitCode.USAGE) + + +@_guard +def _cmd_keyboard_type(args: argparse.Namespace) -> int: + lease_id = _lease_of(args, args.id) + if not lease_id: + return _no_lease(args, args.id) + # `args.text` goes through untouched. No `.encode().decode('unicode_escape')` + # and no strip: the shell quoted it, and a CLI that interpreted backslashes + # would make a literal backslash-n untypeable. + reply = _request(args, "keyboard.type", id=args.id, lease_id=lease_id, text=args.text) + + def render(r: dict[str, Any]) -> str: + held = r.get("keys") or [] + # The COUNT, never the text: this line goes to a terminal that is + # often being logged, and the string is a password as often as not. + bits = [f"{r.get('id')}: typed {r.get('chars')} character(s)"] + if held: + bits.append(f"still held: {', '.join(held)}") + return "; ".join(bits) + + return _finish_gesture(args, reply, render, args.id) + + +@_guard +def _cmd_keyboard_key(args: argparse.Namespace) -> int: + """A tap: down then up, as two wire calls. + + Two calls and not a `count`-style loop in the broker, because a tap is the + only thing anyone wants and the pair is what `down`/`up` already are. + + A refused `down` returns without sending the `up`, and that is deliberate: + a refusal is the broker saying the key was never pressed -- a bad keysym, + no lease -- so an `up` would ask the compositor to release something it + never had. A reply *lost* after a successful down is a connection error + rather than ``ok: false``, and the broker's own `release_all` on expiry is + what covers that; the CLI cannot, because it does not know whether the + request arrived. + """ + + lease_id = _lease_of(args, args.id) + if not lease_id: + return _no_lease(args, args.id) + down = _request( + args, "keyboard.key", id=args.id, lease_id=lease_id, key=args.name, state="down" + ) + if not down.get("ok"): + return _finish_gesture(args, down, lambda r: "", args.id) + reply = _request( + args, "keyboard.key", id=args.id, lease_id=lease_id, key=args.name, state="up" + ) + + def render(r: dict[str, Any]) -> str: + held = r.get("keys") or [] + return ( + f"{r.get('id')}: tapped {args.name}; " + f"held: {', '.join(held) if held else 'nothing'}" + ) + + return _finish_gesture(args, reply, render, args.id) + + +@_guard +def _cmd_keyboard_hold(args: argparse.Namespace) -> int: + lease_id = _lease_of(args, args.id) + if not lease_id: + return _no_lease(args, args.id) + reply = _request( + args, + "keyboard.key", + id=args.id, + lease_id=lease_id, + key=args.name, + state=args.key_state, + ) + + def render(r: dict[str, Any]) -> str: + held = r.get("keys") or [] + return ( + f"{r.get('id')}: {args.name} {args.key_state}; " + f"held: {', '.join(held) if held else 'nothing'}" + ) + + return _finish_gesture(args, reply, render, args.id) + + # -------------------------------------------------------------------------- # standalone use # -------------------------------------------------------------------------- diff --git a/src/hhstream_session/format.py b/src/hhstream_session/format.py index 533c247..c113e9c 100644 --- a/src/hhstream_session/format.py +++ b/src/hhstream_session/format.py @@ -275,12 +275,19 @@ def render_bookmark(bookmark: dict[str, Any] | None) -> str: def render_pointer_state(reply: dict[str, Any]) -> str: holder = reply.get("holder") buttons = reply.get("buttons") or [] + keys = reply.get("keys") or [] lines = [ f"holder {holder if holder else 'free'}", f"lease {_cell(reply.get('lease_id'))}", # Loud, because a button left down is the one pointer failure that keeps # hurting after the lease is gone. f"buttons {', '.join(buttons) if buttons else 'none down'}", + # Keys are here and not under a `keyboard state` verb, because they are + # the same lease and the same kind of leak -- and a held key is the + # worse one: this compositor drops the *next* press of a code it still + # believes is down, so a leaked key is dead rather than merely stuck. + # Names, as everywhere else on this surface, never evdev codes. + f"keys {', '.join(keys) if keys else 'none down'}", f"bookmark {render_bookmark(reply.get('bookmark'))}", f"driver {_cell(reply.get('driver'))}", ] diff --git a/src/hhstreamd/driver.py b/src/hhstreamd/driver.py index 7ad09d6..efaf007 100644 --- a/src/hhstreamd/driver.py +++ b/src/hhstreamd/driver.py @@ -1,9 +1,9 @@ """The broker's end of the private driver socket (CONTRACT-sessions.md §3.4). -The pointer driver is a separate process because a Wayland client needs its own -connection; this module is the five-verb client that talks to it. It is the -only place in the broker that knows the driver's wire format, so the driver and -the broker can be read against each other in two files. +The input driver is a separate process because a Wayland client needs its own +connection; this module is the client that talks to it. It is the only place +in the broker that knows the driver's wire format, so the driver and the broker +can be read against each other in two files. **It holds no lease state and asks for none.** The driver is an executor: it will warp anywhere it is told, and the only thing that stops two sessions @@ -27,7 +27,10 @@ for EOF before each write and silently replaced — but a request that *was* written and then went unanswered is never sent again, because a repeated ``button down`` is a click the agent did not ask for. Every failure is :class:`DriverUnavailable` — never a guess, and never a silent no-op, because a -dropped ``release_all`` leaves a mouse button down. +dropped ``release_all`` leaves a mouse button down **and a key down**, and on +this compositor a key left in the seat's ``m_pressed`` is worse than stuck: the +*next* press of that code is dropped, so the key is dead until something sends +a matching up. """ from __future__ import annotations @@ -60,7 +63,22 @@ class DriverUnavailable(Exception): class DriverRejected(Exception): - """The driver understood the request and refused it (``ok: false``).""" + """The driver understood the request and refused it (``ok: false``). + + ``kind`` is the driver's machine-readable reason, straight off the wire + (``hhstream_pointer.ops.KIND_INVALID`` / ``KIND_REFUSED``). It exists + because two very different failures arrive through this one exception — "no + such keysym on your layout" and "this compositor has no virtual keyboard" + — and they are exit 2 and exit 10. Telling them apart by matching on the + message text would be a mapping that breaks when the wording improves. + + An older driver sends no ``kind`` at all; the default then keeps today's + behaviour, which is to report everything as a compositor-side refusal. + """ + + def __init__(self, message: str, *, kind: str | None = None) -> None: + super().__init__(message) + self.kind = kind class PointerDriver: @@ -73,7 +91,7 @@ class PointerDriver: self._sock: socket.socket | None = None self._stream = None - # -- the five verbs --------------------------------------------------- + # -- the verbs -------------------------------------------------------- def warp(self, output: str, x: float, y: float) -> None: """Aim at ``x``/``y``, each 0..1 in ``output``'s own frame.""" @@ -100,6 +118,30 @@ class PointerDriver: self.request({"op": "frame"}) + def key(self, key: str, state: str) -> list[str]: + """Press or release one keysym by name. Returns what is still held. + + A *name*, not a code: the driver owns the keymap, so it is the only + thing that can say which keycode ``z`` is on the uploaded layout. No + ``frame`` follows, because ``zwp_virtual_keyboard_v1`` has none. + """ + + reply = self.request({"op": "key", "key": key, "state": state}) + return _string_list(reply.get("keys"), "key") + + def type_text(self, text: str) -> list[str]: + """Type a whole string. Returns the keys still explicitly held. + + One request for the whole string, not one per character, and that is + load-bearing in two directions: the driver validates the string before + emitting anything, so an unmappable character types no prefix; and the + broker refreshes the lease once, which is what makes a long ``type`` + a single gesture rather than a thousand. + """ + + reply = self.request({"op": "type", "text": text}) + return _string_list(reply.get("keys"), "type") + def pressed(self) -> list[str]: """What the *driver* believes is down. @@ -110,11 +152,28 @@ class PointerDriver: reply = self.request({"op": "pressed"}) return _string_list(reply.get("buttons"), "pressed") - def release_all(self) -> list[str]: - """Lift everything, returning what came up. Called on expiry.""" + def keys_pressed(self) -> list[str]: + """Keysym names the *driver* believes are down. Same rule as above.""" + + reply = self.request({"op": "pressed"}) + return _string_list(reply.get("keys"), "pressed keys") + + def release_all(self) -> tuple[list[str], list[str]]: + """Lift everything, returning ``(buttons, keys)``. Called on expiry. + + One call for both, because there is one ``release_all`` op and one + expiry call site. A second op for keys would be a second thing to + forget, and the thing it would be forgotten in is the path that runs + when nobody is watching. + """ reply = self.request({"op": "release_all"}) - return _string_list(reply.get("lifted"), "release_all") + return ( + _string_list(reply.get("lifted"), "release_all"), + # Absent from an older driver's reply, and `[]` is the right answer + # for one: it cannot have had a key down. + _string_list(reply.get("lifted_keys") or [], "release_all keys"), + ) # -- plumbing --------------------------------------------------------- @@ -156,7 +215,11 @@ class PointerDriver: if not isinstance(reply, dict): raise ValueError(f"reply is not an object: {type(reply).__name__}") if not reply.get("ok"): - raise DriverRejected(str(reply.get("error") or "the driver refused the request")) + kind = reply.get("kind") + raise DriverRejected( + str(reply.get("error") or "the driver refused the request"), + kind=kind if isinstance(kind, str) else None, + ) return reply def _connect(self): @@ -208,14 +271,14 @@ class PointerDriver: def _string_list(value: Any, what: str) -> list[str]: - """A list of button names, or a malformed reply — never a silent ``[]``. + """A list of names, or a malformed reply — never a silent ``[]``. An empty list is a real answer ("nothing was down"); anything that is not a list of strings means the broker and the driver disagree about the protocol, and treating that as "nothing was down" is how a button stays - pressed forever. + pressed forever and a key stays dead. """ if not isinstance(value, list) or not all(isinstance(item, str) for item in value): - raise DriverUnavailable(f"{what}: expected a list of button names, got {value!r}") + raise DriverUnavailable(f"{what}: expected a list of names, got {value!r}") return list(value) diff --git a/src/hhstreamd/manager.py b/src/hhstreamd/manager.py index e869ff0..1cf3def 100644 --- a/src/hhstreamd/manager.py +++ b/src/hhstreamd/manager.py @@ -117,6 +117,19 @@ POINTER_SWEEP_S = 1.0 DEFAULT_CONTAINER_BASE = 1000 DEFAULT_CONTAINER_SLOTS = 4 +#: The driver's token for "this is the caller's mistake, not the compositor's" +#: (``hhstream_pointer.ops.KIND_INVALID``). Mirrored rather than imported: the +#: broker does not depend on the driver package -- they are separate processes +#: and separate installs -- which is the same reason ``hhstream_pointer`` keeps +#: its own copy of the exit codes. +DRIVER_KIND_INVALID = "invalid_argument" + +#: The longest ``keyboard.type``, in Unicode **scalars**. Mirrors +#: ``hhstream_pointer.keymap.MAX_TEXT_SCALARS``; checked in both places because +#: only a check here produces exit 2, and only the check there protects a +#: driver run by hand. +MAX_TYPE_SCALARS = 4096 + #: Clicks per ``pointer.click``. Bounded because a count comes off the wire #: and "click 10000 times" is not a gesture. MAX_CLICK_COUNT = 3 @@ -1591,6 +1604,12 @@ class SessionManager: or one belonging to an output this session no longer has — the cursor goes to the container's centre, which is the only other defensible place. + + **Acquire takes the keyboard as well as the cursor.** There is no + separate verb and no flag for it: a lease that aimed the pointer at one + window while the keys went to another would be a lease that cannot be + used to type, and finding that out costs a keystroke in someone else's + window. :meth:`_warp_taking_focus` is how, and why it is two motions. """ session = self._require_live(session_id) @@ -1617,7 +1636,7 @@ class SessionManager: bookmark = self._restore_point(session, output) if restore else None x, y = (bookmark["x"], bookmark["y"]) if bookmark else (0.5, 0.5) try: - await self._warp(output, x, y) + focus = await self._warp_taking_focus(session, output, x, y) except ManagerError: # Never hold a lease we could not aim: the next verb would move a # cursor that is somewhere else entirely. @@ -1631,12 +1650,17 @@ class SessionManager: output=output, restored=bool(bookmark), ttl_s=self.pointer.ttl_s, + # Which mechanism took keyboard focus, so a session that ends up + # typing into the wrong window can be told apart from one that + # never tried. See `_warp_taking_focus`. + focus=focus, ) return { "id": session.id, "lease_id": lease_id, "bookmark": mark, "expires_in_s": self.pointer.ttl_s, + "focus": focus, } async def pointer_move( @@ -1782,7 +1806,7 @@ class SessionManager: with contextlib.suppress(LeaseInvalid): self.pointer.mark(session.id, lease_id, mark) try: - lifted = await self._release_all_buttons() + lifted, lifted_keys = await self._release_all_buttons() except ManagerError: # The driver is gone, so the cursor's state is unknown — and # holding a lease over an unknown cursor helps nobody. Drop it @@ -1800,6 +1824,7 @@ class SessionManager: session=session.id, reason=outcome.reason, buttons_lifted=lifted, + keys_lifted=lifted_keys, ) return { "id": session.id, @@ -1807,6 +1832,9 @@ class SessionManager: "released_by": "lease", "released_at": released_at, "buttons_lifted": lifted, + # Beside `buttons_lifted` and nowhere richer: the release body + # reports what came up, and keys are another thing that came up. + "keys_lifted": lifted_keys, } def pointer_state(self) -> dict[str, Any]: @@ -1818,10 +1846,87 @@ class SessionManager: return { **state, "buttons": self.pointer.pressed(), + # Names, not evdev codes: the whole surface speaks keysym names, + # and a number here would be the one place it did not. + "keys": self.pointer.keys_pressed(), "bookmark": None if session is None else (session.pointer or {}).get("bookmark"), "driver": None if self.config.pointer_socket is None else str(self.config.pointer_socket), } + # ------------------------------------------------------------------ + # the keyboard, on the same lease + # ------------------------------------------------------------------ + # + # No `keyboard.acquire`, and that is not a simplification: there is one + # `wl_seat` and one keyboard focus, and `follow_mouse = 1` means another + # session's warp retargets the keys. Two leases would let session B move + # the pointer while session A believed it was typing into its own window. + # + # Both verbs go through `_refresh` -- live session, holder, not expired, + # container output required -- so they refresh the TTL and, like every + # `pointer.*` verb, do **not** count as activity. A session being typed + # into is still a session nobody has said they want kept. + + async def keyboard_key( + self, session_id: str, lease_id: str, key: Any, state: Any + ) -> dict[str, Any]: + """Hold or release one keysym by name. + + The driver first, then the lease's mirror of it -- the + ``pointer_button`` order, and for the same reason: a key the driver + refused must not be recorded as down. The reverse mistake is harmless, + because ``release_all`` lifts what the *driver* recorded and that is + the set the compositor saw. + """ + + session, _output = await self._refresh(session_id, lease_id) + name = _keysym_name(key) + if state not in ("down", "up"): + raise ManagerError( + "invalid_argument", f"key state must be 'down' or 'up', got {state!r}" + ) + await self._drive("key", name, state) + if state == "down": + self.pointer.press_key(session.id, name) + else: + self.pointer.unpress_key(session.id, name) + # The name and the state, which is all there is: a keysym name is not + # a secret the way typed text is. + self.audit.emit("keyboard_key", session=session.id, key=name, state=state) + return {"id": session.id, "keys": self.pointer.keys_pressed()} + + async def keyboard_type( + self, session_id: str, lease_id: str, text: Any + ) -> dict[str, Any]: + """Type a string. One driver request, one lease refresh. + + The cap and the type check happen **here**, before the driver is + called, because the broker raising ``invalid_argument`` is the only + thing that produces exit 2: a driver refusal arrives as + ``driver_refused`` unless it carries the token ``_drive`` looks for. + + Nothing of the string is recorded. The audit event carries a count, + because a typed string is a password as often as not and + ``events.jsonl`` is the wrong place for one. + """ + + session, _output = await self._refresh(session_id, lease_id) + if not isinstance(text, str): + raise ManagerError("invalid_argument", f"text must be a string, got {text!r}") + if len(text) > MAX_TYPE_SCALARS: + # Unicode scalars, not bytes: a byte cap would refuse a string the + # caller counted as short, and the two only agree on ASCII. + raise ManagerError( + "invalid_argument", + f"text is {len(text)} scalars, over the {MAX_TYPE_SCALARS} limit", + ) + await self._drive("type_text", text) + # `type` leaves no letter down; what comes back is whatever was + # explicitly held before it, so the mirror is re-read rather than + # assumed unchanged. + self.audit.emit("keyboard_type", session=session.id, chars=len(text)) + return {"id": session.id, "chars": len(text), "keys": self.pointer.keys_pressed()} + # -- lease internals -------------------------------------------------- async def _sweep_pointer(self) -> None: @@ -1855,22 +1960,31 @@ class SessionManager: if holder is None: return None pressed = self.pointer.pressed() + # Read **before** `expire()`, and for the same reason `pressed()` is: + # `expire()` drops the lease and its key set with it, and the lease + # cannot lift anything itself (CONTRACT-sessions.md §3.3). + keys_held = self.pointer.keys_pressed() info = self.pointer.expire() if info is None: return None self._restore_default_ttl() hard = self.clock.boottime() >= info.hard_deadline lifted: list[str] = [] + lifted_keys: list[str] = [] try: - lifted = await self._release_all_buttons() + lifted, lifted_keys = await self._release_all_buttons() except ManagerError as exc: - # Loud: a button is down and we could not lift it. There is no + # Loud: something is down and we could not lift it. There is no # caller to raise at, so the log and the audit trail are the alarm. + # A key is the worse half: on this compositor a code left in the + # seat's `m_pressed` makes the *next* press of it a no-op, so the + # key is dead rather than merely stuck. log.error( - "pointer lease for %s expired with %s pressed and the driver " - "unreachable (%s): a button may still be down", + "pointer lease for %s expired with buttons %s and keys %s down and " + "the driver unreachable (%s): they may still be held", holder, - pressed or "nothing", + pressed or "none", + keys_held or "none", exc.reason, ) session = self.registry.get(holder) @@ -1882,15 +1996,23 @@ class SessionManager: lease_id=info.lease_id, hard_cap=hard, pressed=pressed, + keys_pressed=keys_held, buttons_lifted=lifted, + keys_lifted=lifted_keys, ) log.warning( - "pointer lease for %s expired (%s); lifted %s", + "pointer lease for %s expired (%s); lifted buttons %s, keys %s", holder, "hard cap" if hard else "idle ttl", lifted or "nothing", + lifted_keys or "nothing", ) - return {"session": holder, "lease_id": info.lease_id, "buttons_lifted": lifted} + return { + "session": holder, + "lease_id": info.lease_id, + "buttons_lifted": lifted, + "keys_lifted": lifted_keys, + } async def _refresh(self, session_id: Any, lease_id: Any) -> tuple[Session, str]: """The gate every gesture verb goes through: live, holder, not expired.""" @@ -2044,6 +2166,14 @@ class SessionManager: try: return await asyncio.to_thread(getattr(driver, verb), *args) except DriverRejected as exc: + # Two refusals arrive here and they are different exit codes. The + # driver says which with a token, because the alternative is the + # broker matching on English: `invalid_argument` is "that keysym is + # not on your layout" (exit 2, the caller's), and everything else + # is `driver_refused` (exit 10, the compositor's). An older driver + # sends no token and keeps the old behaviour. + if exc.kind == DRIVER_KIND_INVALID: + raise ManagerError("invalid_argument", str(exc)) from exc raise ManagerError("driver_refused", f"the pointer driver refused {verb}: {exc}") from exc except DriverUnavailable as exc: raise ManagerError( @@ -2055,11 +2185,92 @@ class SessionManager: # Nothing the driver was sent reaches the compositor until a frame. await self._drive("frame") - async def _release_all_buttons(self) -> list[str]: - """Lift everything on the driver. The driver's set is the real one.""" + async def _warp_taking_focus( + self, session: Session, output: str, x: float, y: float + ) -> str: + """Warp so this session's own window holds pointer **and** keyboard focus. - lifted = await self._drive("release_all") - return list(lifted) + **Two motions, deliberately.** One is not enough, and that is measured + rather than assumed (``tests/README-keyboard-probe.md``): Hyprland's + ``onMouseWarp`` goes through ``mouseMoveUnified(refocus=false)``, which + *sets* ``m_mousePosDelta`` to 0 when the previous cursor movement was + more than 0.5 s ago, and keyboard focus is that delta compared against + ``input:follow_mouse_threshold``. A single warp onto an idle cursor + therefore delivers ``wl_pointer.enter`` and no ``wl_keyboard.enter``: + the aimed window has the cursor and the *previously focused* window + still has the keys. The first key of the lease then lands there. + + So: one motion to a neighbouring pixel, then one to the real target. + The second is within microseconds of the first, so the delta is the + distance between them, which is non-zero — and the threshold is 0 + (set explicitly in ``nix/hyprland-conf.nix``, because this now depends + on it). The cursor finishes at the target, so the bookmark is + unchanged and nothing else here has to know this happened. + + ``mouseMoveUnified`` also returns *before* it touches the delta when + the floored pixel has not changed, which is why the nudge is a real + pixel away rather than a sub-pixel one, and why warping twice to the + same bookmark is not a substitute. + + Returns how focus was taken, for the audit trail: ``"warp"``, + ``"focuswindow"`` if the nudge could not be sent and the compositor's + own focus command stood in, or ``"none"`` if neither worked. + """ + + method = "warp" + try: + await self._warp(output, x, _nudged(y)) + except ManagerError as exc: + # The *target* warp below is still attempted and its failure is + # still fatal, as it was before this existed. Only the focus half + # degrades here, to the one IPC call the plan already named. + log.warning( + "could not send the focus nudge for %s (%s); falling back to " + "the compositor's own focus command", + session.id, + exc.reason, + ) + method = "focuswindow" if self._focus_window(session) else "none" + await self._warp(output, x, y) + return method + + def _focus_window(self, session: Session) -> bool: + """``dispatch focuswindow`` at this session's window. Best effort. + + The fallback, and not the primary, for the reason the plan gives: it is + a second mechanism for something the warp already does, it needs the + compositor's request socket to be up, and it names a window by an + address the broker only has if a read-back has happened. Failure is + logged rather than raised: an acquire that aimed the cursor correctly + is still useful, and the caller is told which mechanism ran. + """ + + window = (session.container or {}).get("window") or {} + address = window.get("address") + selector = f"address:{address}" if address else None + if selector is None and session.pid: + selector = f"pid:{session.pid}" + if selector is None: + log.error("no window address or pid for %s; cannot focus it", session.id) + return False + try: + self.host.dispatch(["hyprctl", "dispatch", "focuswindow", selector]) + except (CompositorUnavailable, ValueError) as exc: + log.error("could not focus %s (%s): keys may go elsewhere", session.id, exc) + return False + return True + + async def _release_all_buttons(self) -> tuple[list[str], list[str]]: + """Lift everything on the driver: ``(buttons, keys)``. + + The driver's sets are the real ones -- they are what the compositor + saw -- and this is one call for both because the driver has one + ``release_all`` op. A second call for keys would be a second thing to + forget in the path that runs when nobody is watching. + """ + + lifted, lifted_keys = await self._drive("release_all") + return list(lifted), list(lifted_keys) def logs(self, session_id: str, *, lines: int = 100, offset: int | None = None) -> dict[str, Any]: """The daemon's capture of the app's stdout/stderr. @@ -2173,12 +2384,45 @@ def _clamp(value: float) -> float: return min(1.0, max(0.0, value)) +#: How far the focus nudge moves, as a fraction of the output. At the frozen +#: container mode of 1280x720 (CONTRACT-sessions.md §5) this is ~3 px +#: vertically, which is what makes the *floored* pixel change -- +#: ``mouseMoveUnified`` returns before it touches the delta otherwise, so a +#: sub-pixel nudge would move the cursor and not the focus. +FOCUS_NUDGE = 0.004 + + +def _nudged(value: float) -> float: + """A coordinate one real pixel away from ``value``, still inside 0..1. + + Away from whichever edge is closer, so aiming at a corner still produces a + pair of distinct positions rather than two clamped-identical ones. + """ + + if value + FOCUS_NUDGE <= 1.0: + return value + FOCUS_NUDGE + return max(0.0, value - FOCUS_NUDGE) + + def _button_name(value: Any) -> str: if not isinstance(value, str) or not value: raise ManagerError("invalid_argument", f"button must be a name, got {value!r}") return value +def _keysym_name(value: Any) -> str: + """A keysym name, checked only for shape. + + Whether the layout *has* it is the driver's question -- it owns the keymap + -- and the driver answers an unknown one with a token that becomes exit 2. + This is the same division ``_button_name`` draws. + """ + + if not isinstance(value, str) or not value: + raise ManagerError("invalid_argument", f"key must be a keysym name, got {value!r}") + return value + + def _axis_name(value: Any) -> str: if not isinstance(value, str) or not value: raise ManagerError("invalid_argument", f"axis must be a name, got {value!r}") diff --git a/src/hhstreamd/pointer.py b/src/hhstreamd/pointer.py index e293587..b075920 100644 --- a/src/hhstreamd/pointer.py +++ b/src/hhstreamd/pointer.py @@ -70,6 +70,10 @@ class LeaseOutcome: bookmark: Bookmark | None reason: str buttons_lifted: list[str] + #: Keysym names this lease believed were down. Beside ``buttons_lifted`` + #: and for the same reason: both are the *lease's* mirror, and the driver's + #: own answer is what the broker actually reports. + keys_lifted: list[str] = field(default_factory=list) @dataclass @@ -85,6 +89,11 @@ class _Held: #: Insertion-ordered set: a dict with ignored values. Order is kept so a #: forced release lifts buttons in the order they went down. buttons: dict[str, None] = field(default_factory=dict) + #: The same pattern for keysym names. A dict and not a ``keyboard`` + #: boolean, which is what PLAN §6.7 proposed: a flag cannot say to lift + #: ``Control_L`` and not ``a``, and order matters for the same reason it + #: does for buttons. + keys: dict[str, None] = field(default_factory=dict) def info(self) -> LeaseInfo: return LeaseInfo( @@ -163,15 +172,23 @@ class PointerLease: bookmark=held.bookmark, reason=reason, buttons_lifted=list(held.buttons), + keys_lifted=list(held.keys), ) def expire(self) -> LeaseInfo | None: """Force-release a lease past its TTL or its hard cap. Returns what was released, or ``None`` if nothing was due. The caller - lifts the buttons on the driver: this object's button set is a mirror - of the driver's, never the authority, so it is simply dropped here and - ``release_all`` on the driver is what actually ungrabs the mouse. + lifts the buttons *and the keys* on the driver: this object's sets are + a mirror of the driver's, never the authority, so they are simply + dropped here and ``release_all`` on the driver is what actually ungrabs + the mouse and lets the keys up. + + Deliberately still :class:`LeaseInfo` and not a richer return + (CONTRACT-sessions.md §3.3): callers that want to know what was held + read :meth:`pressed` and :meth:`keys_pressed` *first*. Widening it + would make the ordering rule optional, and the ordering rule is the + only thing stopping a key from being forgotten before it is lifted. """ held = self._held @@ -213,6 +230,33 @@ class PointerLease: return [] if self._held is None else list(self._held.buttons) + # -- keys ------------------------------------------------------------- + # + # Mirrors the three above exactly, and shares their rule: the lease's set + # is a mirror of the driver's and never the authority. The driver's is the + # one the compositor saw, and on this compositor a key the driver forgot is + # worse than a button it forgot -- `InputManager::onKeyboardKey` drops the + # *next* press of a code still in its `m_pressed`, so a leaked key makes + # that key dead rather than merely stuck. + + def press_key(self, session_id: str, key: str) -> None: + self._holder(session_id).keys[key] = None + + def unpress_key(self, session_id: str, key: str) -> list[str]: + """Lift one key. Returns what actually came up — ``[]`` if it was + never down, so a duplicate release is reported rather than invented.""" + + keys = self._holder(session_id).keys + if key not in keys: + return [] + del keys[key] + return [key] + + def keys_pressed(self) -> list[str]: + """Keysym names currently down, oldest first. Empty when unheld.""" + + return [] if self._held is None else list(self._held.keys) + # -- bookmark --------------------------------------------------------- def mark(self, session_id: str, lease_id: str, bookmark: Bookmark) -> None: diff --git a/src/hhstreamd/protocol.py b/src/hhstreamd/protocol.py index 94b6afc..73d5579 100644 --- a/src/hhstreamd/protocol.py +++ b/src/hhstreamd/protocol.py @@ -151,6 +151,11 @@ VERBS = ( "pointer.scroll", "pointer.release", "pointer.state", + # Keyboard verbs are gestures on the *pointer* lease -- there is one seat + # and one keyboard focus, and `follow_mouse = 1` means another session's + # warp retargets the keys. So there is no `keyboard.acquire`. + "keyboard.key", + "keyboard.type", ) #: Verbs whose reply is remembered by ``request_id``, so a caller that died @@ -174,6 +179,12 @@ MUTATING_VERBS = frozenset( "pointer.click", "pointer.scroll", "pointer.release", + # A retried `type` must not type twice, for exactly the reason a + # retried click must not click twice: it is the one failure an agent + # cannot undo. `pointer.state` stays out of this set -- it mutates + # nothing, and a cached one would be a stale one. + "keyboard.key", + "keyboard.type", } ) diff --git a/src/hhstreamd/server.py b/src/hhstreamd/server.py index f981298..0660994 100644 --- a/src/hhstreamd/server.py +++ b/src/hhstreamd/server.py @@ -73,6 +73,8 @@ class ControlServer: "pointer.scroll": self._op_pointer_scroll, "pointer.release": self._op_pointer_release, "pointer.state": self._op_pointer_state, + "keyboard.key": self._op_keyboard_key, + "keyboard.type": self._op_keyboard_type, } # ------------------------------------------------------------------ @@ -381,6 +383,33 @@ class ControlServer: ) -> dict[str, Any]: return protocol.ok(**self.manager.pointer_state()) + async def _op_keyboard_key( + self, request: dict[str, Any], caller: dict[str, Any] + ) -> dict[str, Any]: + return protocol.ok( + **await self.manager.keyboard_key( + request.get("id"), + request.get("lease_id"), + request.get("key"), + request.get("state"), + ) + ) + + async def _op_keyboard_type( + self, request: dict[str, Any], caller: dict[str, Any] + ) -> dict[str, Any]: + # `text` is passed through untouched -- no default, no strip, no + # escape handling. A newline in the argument is a newline on the wire; + # the shell did the quoting and inventing an escape language here + # would mean `\n` could never be typed literally. + return protocol.ok( + **await self.manager.keyboard_type( + request.get("id"), + request.get("lease_id"), + request.get("text"), + ) + ) + async def _op_logs(self, request: dict[str, Any], caller: dict[str, Any]) -> dict[str, Any]: return protocol.ok( **self.manager.logs( diff --git a/tests/README-keyboard-probe.md b/tests/README-keyboard-probe.md new file mode 100644 index 0000000..e4860fc --- /dev/null +++ b/tests/README-keyboard-probe.md @@ -0,0 +1,260 @@ +# `keyboard_probe.py` — Stage 0 of the keyboard plan + +Stage 0 of [`docs/plans/2026-10-03-keyboard-input.md`](../docs/plans/2026-10-03-keyboard-input.md), +written to the probe spec in +[`docs/plans/2026-10-04-keyboard-verification.md`](../docs/plans/2026-10-04-keyboard-verification.md) +§B1. It measures the things neither plan would let Stage 1 guess at, and prints +what it saw. + +It is **throwaway**: delete it once `checks/vm-keyboard.nix` asserts the same +properties in a VM. The review says not to commit it at all; the brief that +commissioned this work says to commit it under `examples/` or `tests/` with a +README, and that is what this is. Nothing downstream imports it. + +It speaks to the compositor and to nothing else — **no broker, no lease, no +`hhstreamd` control socket, no `hhstream` CLI, no session**. Read-only +`hyprctl` (`clients -j`, `getoption -j`) is used so the warp hits a box it +knows the coordinates of; `hyprctl dispatch` is never used, because +`dispatch focuswindow` would answer (a) by cheating. + +It does two things that are not read-only, because keyboard focus cannot be +measured without them: it opens two small windows of its own, and it moves the +one cursor. It refuses to send a key until it has seen `wl_keyboard.enter` on a +surface it owns, and it lifts everything it pressed on the way out — including +through a fresh virtual keyboard, because of what (b) turned out to be. + +## Running it + +It needs `pywayland` (the dev shell has it), `xkbcommon` (the dev shell does +not, until Stage 1 adds it), `hyprctl`, and the protocol XML. One command, in +the shape `hhstream_pointer._protocol.regenerate`'s docstring already uses for +"this needs something the dev shell lacks": + +```bash +cd /var/lib/hermes/projects/hhstream-keyboard # or wherever this checkout is +XML="$(nix eval --raw nixpkgs#hyprland.src)/protocols" + +sg hhstream -c "HHSTREAM_PROTOCOL_DIR='$XML' PYTHONPATH=src \ + nix shell --impure --expr 'with (builtins.getFlake \"nixpkgs\").legacyPackages.\${builtins.currentSystem}; [ (python3.withPackages (p: [ p.pywayland p.xkbcommon ])) hyprland ]' \ + --command python3 tests/keyboard_probe.py" +``` + +`sg hhstream` is not optional: `/run/hypr-stream` is `0750 hhstream:hhstream`, +so a login that predates the group membership cannot open the Wayland socket at +all. (The review's `sudo -u hermes -g hhstream env …` form does the same thing +and also works; `sg` is what the brief asked for and needs no root.) +`PYTHONPATH=src` is how it reaches the driver's already-vendored wlr *pointer* +protocol rather than growing a second copy. + +Flags: `--runtime-dir` (default `/run/hypr-stream`), `--xml`, `--output` (only +needed if the compositor has more than one), `--xkb-layout`, `--xkb-model`. + +### Where it deviates from the review's §B1 sequence + +All three are visible in the transcript and none of them changes an answer: + +- the keymap is uploaded **before** the windows are opened, not after. It has + to be: the seat has no libinput keyboard, so `wl_seat.capabilities` does not + include `keyboard` until a virtual one exists (the setup block goes `1` then + `3`), and a listener bound any later would have seen nothing at all; +- the idle wait before (a1) is 0.8 s rather than 0.6 s; +- (a2) follows (a1) after the settle window and a print — measured at 0.401 s + rather than being "immediate", and still inside the 0.5 s that matters. + +Exit codes: **2** if `zwp_virtual_keyboard_manager_v1` is missing or is not +version 1 — the gate the plan says stops the project — and 0 otherwise. The +answers are in the output, not in the exit status: a measurement that came back +"no" is still a successful measurement. + +### Where the XML is, and where both plans say it is + +Both plans say the XML is wayland-protocols' +`unstable/virtual-keyboard/virtual-keyboard-unstable-v1.xml`, and the review's +objection 4 says specifically *not* to use Hyprland's copy. **Neither is +possible here.** Checked, on this machine: + +| Source | Has it? | +| --- | --- | +| `wayland-protocols` 1.49 (this flake's own nixpkgs input), `unstable/`, `staging/`, `stable/` | no — there is no `virtual-keyboard` directory at all | +| `pkgs.wlr-protocols` (nixpkgs' 2022-09-05 snapshot), output *and* `.src` | no — ten XMLs, the virtual *pointer* among them, not this one | +| `pkgs.wlroots.src` | no | +| `pkgs.hyprland.src` → `protocols/virtual-keyboard-unstable-v1.xml` | **yes, and it is the only copy** | + +```bash +echo "$(nix eval --raw nixpkgs#hyprland.src)/protocols/virtual-keyboard-unstable-v1.xml" +``` + +So the probe, and Stage 1's vendoring, use the Hyprland copy. The review's +reason for avoiding it is real and is handled rather than ignored: that copy +*names* `keymap_format` and `key_state` in prose and never defines them, so the +generated module carries no enum for either. Both are therefore written down as +constants with a citation — in this file as `XKB_FORMAT_TEXT_V1` and +`RELEASED`/`PRESSED`, and in the driver as `hhstream_pointer.keymap.XKB_V1` +beside the existing `buttons.STATES` (which already holds the same two +integers, as the review notes). Same class of correction +`docs/CONTRACT-sessions.md` §3.4 already had to make for the wlr pointer XML +path. + +## What it answered + +One run, 2026-10-04, against the live `/run/hypr-stream`: Hyprland 0.56.2, one +output `Virtual-1` at 1280x720, two Chromium windows already on screen. The +committed transcript is that run and nothing else — +[`keyboard-probe-2026-10-04.txt`](keyboard-probe-2026-10-04.txt) — and every +excerpt below is copied from it, with the line numbers to check it against. An +earlier draft of this file claimed several reproductions and quoted a serial +from a run it had not kept. If a claim here is not in that file, it is not +evidence. + +The configuration the answers depend on, as the compositor reports it: + +``` +input:follow_mouse = 1 (set) +input:follow_mouse_threshold = 0.0 (default) +input:virtualkeyboard:release_pressed_on_close = 0 (default) +input:repeat_rate = 25 (default) +input:repeat_delay = 600 (default) +input:kb_layout = us (default) +``` + +### 1. The global — the gate the whole project hangs on + +**`zwp_virtual_keyboard_manager_v1` is present at version 1** (transcript +line 71, answered on line 76). §6.7's `[RAN]` claim holds against the running +binary. `wp_virtual_keyboard_v1` is not +advertised, as both plans predicted. `zwlr_virtual_pointer_manager_v1` is at +v2, so the driver's existing version-2 requirement is still met. The project +continues. + +### (a) Does a virtual-pointer warp move `wl_keyboard` focus? + +**One idle warp onto an unfocused window: NO.** It moved the cursor and +nothing else. The keyboard focus change arrived only after a *later* +`motion_absolute`, and it belongs to that motion rather than to the first. + +Transcript, lines 104–120, unedited: + +``` + box kb-probe-a at 0,0 size 1280x720 + box kb-probe-b at 120,80 size 1040x560 + focus at map time: kb-probe-b (expected kb-probe-b: it mapped last) + (a1) target 0.0100,0.0100 (inside kb-probe-a only) + (a2) target 0.0100,0.0140 — about 3px lower, so the FLOORED pixel changes. A second warp to the same point would return before mouseMoveUnified touched the delta, and would prove nothing. + (a1) one warp after 0.8s of stillness + (a1) -> wl_pointer.enter surface=kb-probe-a at 13,7 + (a2) a second warp, to the (a2) target above + (a2) -> modifiers depressed=0 latched=0 locked=0 group=0 + (a2) -> leave surface=kb-probe-b + (a2) -> enter surface=kb-probe-a serial=406 keys=[] + (a2) -> modifiers depressed=0 latched=0 locked=0 group=0 + (a2) -> configured surface=kb-probe-b 1040x560 + (a2) -> configured surface=kb-probe-a 1280x720 + gap between the two motion_absolute calls: 0.401s (under Hyprland's 0.5s delta window) + a1_enter=no a2_enter=yes pointer_reached_kb-probe-a=yes +``` + +The sentence this supports, and no stronger one: **an idle `motion_absolute` +onto unfocused `kb-probe-a` delivered `wl_pointer.enter` and no +`wl_keyboard.enter`; `kb-probe-b`'s `leave` and `kb-probe-a`'s `enter` were +observed only in the settle window after a later `motion_absolute` that stayed +inside `kb-probe-a`.** Map-time focus was `kb-probe-b`, and the two boxes +genuinely differ (`0,0 1280x720` against `120,80 1040x560`), so this is not the +one-window false pass. + +It is **not** "the enter was one warp late", which is what an earlier draft of +this file said. The mechanism is in `InputManager.cpp` at v0.56.2: +`mouseMoveUnified` returns before it touches `m_mousePosDelta` when the floored +pixel did not change; the delta is *set to* 0 when the previous movement was +more than 0.5 s ago; and keyboard focus compares that delta against +`input:follow_mouse_threshold`, which the options block above shows is `0.0` +and unset. So the first warp contributed nothing to the delta, and the second +warp's own non-zero delta is what focused. Two consequences the draft got +wrong: + +- **A second warp to the same point is not the fix.** It returns early. (a2) + moves about 3 px, deliberately, and the report prints both targets so a + reader can see that it moved. +- **"Immediately" was never measured.** The gap is 0.401 s, now printed, and it + matters only because it is under the 0.5 s window. + +**`pointer acquire` is one warp** (`src/hhstreamd/manager.py`, the `_warp` in +`pointer_acquire`), so the first key of a lease can be delivered to whatever +was already focused. Neither plan permits building the fallback in Stages 1–2 +(`docs/plans/2026-10-03-keyboard-input.md` §6 risk 1; the review's "Do not +build it in Stage 1"), so Stages 1–2 do not, and the final report carries the +objection. **Stage 3's enter subtest must not be written against acquire's +single warp**, and it must not be made to pass by warping twice to the same +bookmark. + +Two false passes this probe itself walked into, both worth carrying into the VM +check: + +- `"enter surface=kb-probe-a" in line` also matches + `wl_pointer.enter surface=kb-probe-a`, and an earlier version reported + `a1_enter=yes` off a *pointer* event. The match is `startswith` now. +- An earlier version used one window. A single mapped window is focused at map + time, so it prints `enter` whatever the warp does. + +### (b) Does destroying the virtual keyboard release a held key? + +**No release: `release_on_destroy=no`** (transcript line 131), measured with a +second virtual keyboard keeping the seat's keyboard capability up so a release +had somewhere to be delivered, and with nothing of ours having sent a key-up +before `destroy`. `input:virtualkeyboard:release_pressed_on_close` is `0` and +unset, which is the default the review read out of `ConfigValues.cpp`. + +**Read `mask_cleared=no` narrowly.** It says only that the post-destroy window +contained no `modifiers` event. The held key was `KEY_A`, a letter, so the +depressed mask was 0 for the whole run — **this is not a measurement of a +non-zero mask surviving `destroy`**, and an earlier draft of this file claimed +it was. `releasePressed` in `VirtualKeyboard.cpp` emits key-ups only and never +a `modifiers`, so the source still says a mask would survive; it is simply not +what this transcript shows. `release_all` sends `modifiers(0, 0, 0, 0)` for +that reason, not because of this line. + +The confirming evidence is the *cleanup*, transcript lines 136–138: + +``` + cleanup -> uploaded keymap format=1 size=35572 + cleanup -> key code=30 state=0 sym=a + cleanup -> modifiers depressed=0 latched=0 locked=0 group=0 +``` + +`InputManager::onKeyboardKey` **drops** a release whose code is not in the +seat's `m_pressed`. A `state=0` for code 30 that the client actually received, +sent from a *brand new* virtual keyboard, therefore means 30 was still in that +set after `destroy`. Had destroy released it, that cleanup key-up would have +been dropped and nothing would have reached the client. + +One thing the transcript does **not** contain, and which this file used to cite: +an earlier, unkept run whose first `wl_keyboard.enter` carried +`keys=[42, 0, 0, 0]`. Every `enter` in the committed log is `keys=[]`. + +So this is worse than "a key stays down": the code stays in `m_pressed`, and +`onKeyboardKey` also drops a *press* whose code is already there — the next +driver's `key down` for it is ignored, and the key is dead until something +sends a matching up. Handled in Stage 2 by +`input:virtualkeyboard:release_pressed_on_close = true` in +`nix/hyprland-conf.nix` (the review's change 4), with the explicit note that +the setting releases keys and still does not clear the modifier mask — which is +why `release_all` ends with `modifiers(0, 0, 0, 0)` on the clean path +regardless. + +### (c) Does Hyprland auto-repeat a held virtual key? + +**`press_count=1`, `repeat_info rate=25 delay=600`** (transcript lines +124–125). A key left down for `REPEAT_HOLD_S = 1.5` s — longer than the 600 ms +delay, not shorter — produced exactly one `key code=30 state=1` and no +`state=2`. A compositor repeating at 25 Hz after 600 ms would have added about +twenty more lines in the remaining 0.9 s; it added none. `repeat_info` arrives +at bind time, before the hold, and is printed next to the count because the +review asked for both — not because the compositor repeated. + +This is **not** "`keyboard down` will not flood a text field", and reading it +that way is the review's named false pass. The compositor does not repeat on +the wire; it publishes a rate and the *client* repeats. A focused foot, GTK or +Qt text field will insert characters from that one press until the key-up or +the lease TTL (default 30 s). So `keyboard down` of a non-modifier warns +unconditionally in the CLI help, and v1 has no repeat rate to offer because we +do not generate the repeats. `zwp_virtual_keyboard_v1` has no `repeated` state +and there is nothing to ask the compositor for. diff --git a/tests/keyboard-probe-2026-10-04.txt b/tests/keyboard-probe-2026-10-04.txt new file mode 100644 index 0000000..452bb20 --- /dev/null +++ b/tests/keyboard-probe-2026-10-04.txt @@ -0,0 +1,141 @@ +keyboard_probe.py, run 2026-10-04 against the live /run/hypr-stream. +Hyprland 0.56.2, one output Virtual-1 at 1280x720, two Chromium windows +already on screen. Verbatim; nothing edited. + +=== 1. globals on this compositor === + global ext_background_effect_manager_v1 v1 + global ext_data_control_manager_v1 v1 + global ext_foreign_toplevel_image_capture_source_manager_v1 v1 + global ext_foreign_toplevel_list_v1 v1 + global ext_idle_notifier_v1 v2 + global ext_image_copy_capture_manager_v1 v1 + global ext_output_image_capture_source_manager_v1 v1 + global ext_session_lock_manager_v1 v1 + global ext_workspace_manager_v1 v1 + global hyprland_ctm_control_manager_v1 v2 + global hyprland_focus_grab_manager_v1 v1 + global hyprland_global_shortcuts_manager_v1 v1 + global hyprland_input_capture_manager_v1 v1 + global hyprland_lock_notifier_v1 v1 + global hyprland_surface_manager_v1 v2 + global hyprland_toplevel_export_manager_v1 v2 + global hyprland_toplevel_mapping_manager_v1 v1 + global org_kde_kwin_server_decoration_manager v1 + global vicinae_hotkey_manager_v1 v1 + global wl_compositor v6 + global wl_data_device_manager v3 + global wl_drm v2 + global wl_output v4 + global wl_seat v9 + global wl_shm v2 + global wl_subcompositor v1 + global wp_alpha_modifier_v1 v1 + global wp_color_manager_v1 v3 + global wp_commit_timing_manager_v1 v1 + global wp_content_type_manager_v1 v1 + global wp_cursor_shape_manager_v1 v2 + global wp_drm_lease_device_v1 v1 + global wp_fifo_manager_v1 v1 + global wp_fractional_scale_manager_v1 v1 + global wp_pointer_warp_v1 v1 + global wp_presentation v2 + global wp_security_context_manager_v1 v1 + global wp_single_pixel_buffer_manager_v1 v1 + global wp_tearing_control_manager_v1 v1 + global wp_viewporter v1 + global xdg_activation_v1 v1 + global xdg_system_bell_v1 v1 + global xdg_toplevel_tag_manager_v1 v1 + global xdg_wm_base v7 + global xdg_wm_dialog_v1 v1 + global xwayland_shell_v1 v1 + global zwlr_data_control_manager_v1 v2 + global zwlr_foreign_toplevel_manager_v1 v3 + global zwlr_gamma_control_manager_v1 v1 + global zwlr_layer_shell_v1 v5 + global zwlr_output_manager_v1 v4 + global zwlr_output_power_manager_v1 v1 + global zwlr_screencopy_manager_v1 v3 + global zwlr_virtual_pointer_manager_v1 v2 + global zwp_idle_inhibit_manager_v1 v1 + global zwp_input_method_manager_v2 v1 + global zwp_keyboard_shortcuts_inhibit_manager_v1 v1 + global zwp_linux_dmabuf_v1 v5 + global zwp_pointer_constraints_v1 v1 + global zwp_pointer_gestures_v1 v3 + global zwp_primary_selection_device_manager_v1 v1 + global zwp_relative_pointer_manager_v1 v1 + global zwp_tablet_manager_v2 v1 + global zwp_text_input_manager_v1 v1 + global zwp_text_input_manager_v3 v1 + global zwp_virtual_keyboard_manager_v1 v1 + global zxdg_decoration_manager_v1 v2 + global zxdg_exporter_v2 v1 + global zxdg_importer_v2 v1 + global zxdg_output_manager_v1 v3 +ANSWER 1: zwp_virtual_keyboard_manager_v1 is present at version 1. + zwlr_virtual_pointer_manager_v1 v2 (needed for (a)). + setup -> seat capabilities=1 + setup -> seat capabilities=3 + setup -> uploaded keymap format=1 size=35572 + setup -> wl_keyboard.keymap format=1 bytes=35572 symbols=xkb_symbols "pc_us_inet(evdev)" { + setup -> repeat_info rate=25 delay=600 + setup -> configured surface=kb-probe-a 640x360 + setup -> enter surface=kb-probe-a serial=392 keys=[] + setup -> modifiers depressed=0 latched=0 locked=0 group=0 + setup -> configured surface=kb-probe-a 1280x720 + setup -> configured surface=kb-probe-b 640x360 + setup -> modifiers depressed=0 latched=0 locked=0 group=0 + setup -> leave surface=kb-probe-a + setup -> enter surface=kb-probe-b serial=400 keys=[] + setup -> modifiers depressed=0 latched=0 locked=0 group=0 + setup -> configured surface=kb-probe-b 1040x560 + setup -> configured surface=kb-probe-a 1280x720 + +=== (a) does a virtual-pointer warp move wl_keyboard focus? === + options this measurement depends on: + input:follow_mouse = {"int": 1, "option": "input:follow_mouse", "set": true} + input:follow_mouse_threshold = {"float": 0.0, "option": "input:follow_mouse_threshold", "set": false} + input:virtualkeyboard:release_pressed_on_close = {"int": 0, "option": "input:virtualkeyboard:release_pressed_on_close", "set": false} + input:repeat_rate = {"int": 25, "option": "input:repeat_rate", "set": false} + input:repeat_delay = {"int": 600, "option": "input:repeat_delay", "set": false} + input:kb_layout = {"option": "input:kb_layout", "set": false, "str": "us"} + output Virtual-1 mode 1280x720 + box kb-probe-a at 0,0 size 1280x720 + box kb-probe-b at 120,80 size 1040x560 + focus at map time: kb-probe-b (expected kb-probe-b: it mapped last) + (a1) target 0.0100,0.0100 (inside kb-probe-a only) + (a2) target 0.0100,0.0140 — about 3px lower, so the FLOORED pixel changes. A second warp to the same point would return before mouseMoveUnified touched the delta, and would prove nothing. + (a1) one warp after 0.8s of stillness + (a1) -> wl_pointer.enter surface=kb-probe-a at 13,7 + (a2) a second warp, to the (a2) target above + (a2) -> modifiers depressed=0 latched=0 locked=0 group=0 + (a2) -> leave surface=kb-probe-b + (a2) -> enter surface=kb-probe-a serial=406 keys=[] + (a2) -> modifiers depressed=0 latched=0 locked=0 group=0 + (a2) -> configured surface=kb-probe-b 1040x560 + (a2) -> configured surface=kb-probe-a 1280x720 + gap between the two motion_absolute calls: 0.401s (under Hyprland's 0.5s delta window) + a1_enter=no a2_enter=yes pointer_reached_kb-probe-a=yes +ANSWER (a): the idle warp onto unfocused kb-probe-a delivered wl_pointer.enter and NO wl_keyboard.enter. kb-probe-b's leave and kb-probe-a's enter arrived only after the LATER motion_absolute, the one that changed the floored pixel -- so the enter belongs to that motion's non-zero m_mousePosDelta and is NOT a delayed effect of the first warp. + Consequence: `pointer acquire` is one warp, so the first key of a lease can land in whatever was already focused. Stage 3's enter subtest must not be written against acquire's single warp, and warping twice to the same bookmark is not the fix -- the same floored pixel returns early. + +=== (c) is one held virtual key one wl_keyboard.key? === + key code=30 state=1 sym=a + press_count=1 repeat_info=(25, 600) +ANSWER (c): press_count=1 — the compositor does not repeat on the wire; it published repeat_info (25, 600) and the CLIENT repeats. This is NOT 'keyboard down will not flood a text field': foot/GTK/Qt will insert characters from this one press until the key-up or the lease TTL. The help text must warn unconditionally. + (key code=30 deliberately left down, for (b)) + +=== (b) does destroying the virtual keyboard release a held key? === + spare -> uploaded keymap format=1 size=35572 + release_on_destroy=no mask_cleared=no + (compare with input:virtualkeyboard:release_pressed_on_close, printed above) +ANSWER (b): NO RELEASE — destroy delivered no key-up, with a second keyboard keeping the seat's capability up and with nothing of ours having sent an up beforehand. + Read `mask_cleared` narrowly: it says only that destroy emitted no `modifiers` event. The held key is a letter, so the depressed mask was 0 throughout -- this is NOT a measurement of a non-zero mask surviving destroy. releasePressed emits key-ups only (VirtualKeyboard.cpp), which is why release_all sends modifiers(0,0,0,0) regardless. + The confirming evidence is the cleanup below: onKeyboardKey DROPS a release whose code is not in the seat's m_pressed, so a `key code=30 state=0` arriving from a BRAND NEW keyboard means the code was still in that set after destroy. A driver killed with -9 leaves it there and the next driver's press of it is dropped: dead, not merely stuck. _lift_everything is the only guard on the clean path and SIGKILL skips it. + cleanup -> uploaded keymap format=1 size=35572 + cleanup -> key code=30 state=0 sym=a + cleanup -> modifiers depressed=0 latched=0 locked=0 group=0 + cleanup=sent + +Done. Nothing here touched the broker, the lease or any session. diff --git a/tests/keyboard_probe.py b/tests/keyboard_probe.py new file mode 100644 index 0000000..d439558 --- /dev/null +++ b/tests/keyboard_probe.py @@ -0,0 +1,1070 @@ +#!/usr/bin/env python3 +"""Measure the keyboard behaviours neither plan would let Stage 1 guess at. + +`docs/plans/2026-10-03-keyboard-input.md` §6 lists four open questions about +the *running* compositor; `docs/plans/2026-10-04-keyboard-verification.md` §B1 +turns them into a script with expectations and a list of false passes. This is +that script. It prints what it saw, not what it hoped for. + + 1. Is the global really `zwp_virtual_keyboard_manager_v1`, at version 1? + Anything else stops the project. Exits 2 if so. + (a1) One warp, after the cursor has been still for longer than Hyprland's + 0.5 s window — does the aimed window get `wl_keyboard.enter`? + (a2) A second warp immediately after — does it then? + (b) `destroy` with a key still down: is the key released? Is the modifier + mask cleared? + (c) Is one held key one `wl_keyboard.key`, with `repeat_info` still sent? + +(a1) and (a2) are separate questions on purpose, and (a2) is not a repeat of +(a1). `InputManager::onMouseWarp` calls `mouseMoveUnified(refocus=false)`; +with `follow_mouse = 1`, keyboard focus needs +`m_mousePosDelta > follow_mouse_threshold`, that threshold is 0 by default, and +the delta is *set to* 0 when the previous cursor movement was more than 0.5 s +ago. So an idle warp is expected to move the cursor and not keyboard focus, +and a following motion that changes the floored pixel inside 0.5 s is expected +to focus. + +Two things follow, and both are printed rather than assumed: + +* **(a2) must land on a different pixel.** `mouseMoveUnified` returns before + it touches the delta when the floored position did not change, so a second + `motion_absolute` to the *same* point proves nothing. (a2) offsets by about + 3 px and the report prints both normalised points. +* **The gap between them is a measurement, not the word "immediately".** It + has to stay under 0.5 s for (a2) to be the in-window case, so the report + prints the monotonic gap it achieved. + +A probe that collapsed the two into one yes/no would hide exactly what the +lease's `acquire` does: *one* warp, and then a key. + +It talks to the compositor and to nothing else: **no broker, no lease, no +`hhstreamd` socket, no `hhstream` CLI**. Read-only `hyprctl` is used to learn +where the windows actually are and what the relevant options are set to; +`hyprctl dispatch` is *not* used, because `dispatch focuswindow` would answer +(a) by cheating. + +Two windows, `kb-probe-a` and `kb-probe-b`, because a one-window probe is the +review's first listed false pass: a single mapped window is focused at map +time, so it prints `enter` and proves nothing about the warp. The first is +made fullscreen, which on the deployment machine is the only way to get two +windows that do not cover each other exactly — its catch-all rule is `float +on, size 1040 560, center on`, so two ordinary windows would be the same box +in the same place and no warp could tell them apart. The probe prints both +boxes it read from `hyprctl clients -j` and the point it chose between them. + +Every key event is decoded with **the keymap the compositor forwarded**, not +with a table in this file: that is what makes the symbols evidence that our +upload arrived rather than evidence that we can spell. + +Throwaway on purpose. It generates the protocol bindings into a temporary +directory with pywayland's scanner instead of importing a vendored module, so +it ran before any of Stage 1 existed. The seeding trick is the one +`hhstream_pointer._protocol.regenerate` documents: the scanner builds its +import map only from the files it was handed, so `wl_seat` has to be put there +by hand. + +How to run it, and what it answered, is in `tests/README-keyboard-probe.md`. +""" + +from __future__ import annotations + +import argparse +import importlib +import json +import mmap +import os +import pathlib +import select +import struct +import subprocess +import sys +import tempfile +import time + +from pywayland.client import Display +from pywayland.protocol.wayland import WlCompositor, WlOutput, WlSeat, WlShm +from pywayland.protocol.xdg_shell import XdgWmBase + +#: The only copy of this XML on the machine is in `pkgs.hyprland.src`. It is +#: *not* where either plan says it is: wayland-protocols 1.49 (this flake's +#: nixpkgs) has no `unstable/virtual-keyboard/` at all, and neither +#: `pkgs.wlr-protocols` nor `pkgs.wlroots.src` carries it. Find it with: +#: +#: echo "$(nix eval --raw nixpkgs#hyprland.src)/protocols" +XML_NAME = "virtual-keyboard-unstable-v1.xml" + +#: `zwp_virtual_keyboard_manager_v1` is version 1 and only version 1. Anything +#: else is the gate the plan says stops the project. +WANTED_MANAGER_VERSION = 1 + +#: `wl_keyboard.keymap_format.xkb_v1`. Spelled out because the XML this is +#: generated from *names* `keymap_format` in prose and never defines it, so the +#: generated module carries no enum to read it from. +XKB_FORMAT_TEXT_V1 = 1 + +#: `wl_keyboard.key_state`. Same integers as `hhstream_pointer.buttons.STATES` +#: and, like the format above, documented-but-undefined in this XML. `2` is +#: `repeated`, which only a `wl_keyboard` version 10 client ever receives and +#: which `zwp_virtual_keyboard_v1` cannot send. +RELEASED, PRESSED, REPEATED = 0, 1, 2 + +#: evdev codes, readable against `linux/input-event-codes.h`. The XKB keycode +#: is 8 higher; that offset is applied only where a *keysym* is wanted. +KEY_A = 30 # KEY_A +EVDEV_OFFSET = 8 + +#: Opaque fill, as in `checks/lib/pointer_target.py`: a surface with no content +#: is never mapped, and an unmapped surface is never focused. +FILL = 0xFF205070 + +#: Coordinates on the wire are the output's own 0..1 frame scaled by a fixed +#: extent — `hhstream_pointer.backend.EXTENT`, repeated rather than imported +#: because the probe measures the driver's behaviour, not its code. +EXTENT = 0xFFFF + +#: Fallback size for a compositor that configures 0x0 ("you choose"). +DEFAULT_SIZE = (640, 360) + +#: Longer than Hyprland's 0.5 s `m_mousePosDelta` window, so (a1) really is the +#: idle case it claims to be. +IDLE_S = 0.8 + +#: Longer than the default `repeat_delay` of 600 ms, so (c) would see a repeat +#: if there were one. +REPEAT_HOLD_S = 1.5 + +#: After a warp. Generous: a missed event on a software-rendered two-core box +#: would be read as a NO. +SETTLE_S = 0.4 + +#: How far (a2) moves, as a fraction of the output's height. About 3 px on a +#: 720-line output, which is what makes the floored pixel change — +#: `mouseMoveUnified` returns early otherwise and never touches the delta +#: keyboard focus is compared against. +A2_OFFSET = 0.004 + +APP_A, APP_B = "kb-probe-a", "kb-probe-b" + +#: Hyprland options the answers depend on, printed so a reader never has to +#: take this script's word for the configuration it measured. +OPTIONS = ( + "input:follow_mouse", + "input:follow_mouse_threshold", + "input:virtualkeyboard:release_pressed_on_close", + "input:repeat_rate", + "input:repeat_delay", + "input:kb_layout", +) + + +def say(line: str = "") -> None: + """One line, flushed: the output is a report, read as it is produced.""" + + print(line, flush=True) + + +# -------------------------------------------------------------------------- +# protocol bindings, generated into a temporary directory +# -------------------------------------------------------------------------- + + +def load_virtual_keyboard(xml: pathlib.Path): + """Generate and import `virtual_keyboard_unstable_v1` from `xml`. + + The generated file asks its *sibling* for the core interfaces (`from + ..wayland import WlSeat`), so a shim is written beside it that re-exports + pywayland's own class — two Python classes for one Wayland interface would + each register a `wl_interface` and the registry would bind the wrong one. + """ + + from pywayland.protocol import wayland as core + from pywayland.scanner.protocol import Protocol + + protocol = Protocol.parse_file(str(xml)) + name = protocol.name.replace("-", "_") + root = pathlib.Path(tempfile.mkdtemp(prefix="hhs-probe-")) / "_probe_protocol" + root.mkdir() + (root / "__init__.py").write_text("") + (root / "wayland.py").write_text( + "from pywayland.protocol.wayland import WlSeat # noqa: F401\n" + ) + core_dir = pathlib.Path(core.__file__).parent + imports = {path.stem: "wayland" for path in core_dir.glob("wl_*.py")} + imports.update({interface.name: name for interface in protocol.interface}) + protocol.output(str(root), imports) + sys.path.insert(0, str(root.parent)) + return importlib.import_module(f"_probe_protocol.{name}") + + +def find_xml(explicit: pathlib.Path | None) -> pathlib.Path: + """`--xml`, else `$HHSTREAM_PROTOCOL_DIR`, else give up loudly.""" + + if explicit is not None: + return explicit + root = pathlib.Path(os.environ.get("HHSTREAM_PROTOCOL_DIR", "")) + candidate = root / XML_NAME + if candidate.is_file(): + return candidate + raise SystemExit( + f"keyboard-probe: cannot find {XML_NAME}. Pass --xml, or set " + '$HHSTREAM_PROTOCOL_DIR to "$(nix eval --raw nixpkgs#hyprland.src)/protocols".' + ) + + +# -------------------------------------------------------------------------- +# read-only compositor IPC +# -------------------------------------------------------------------------- + + +def hyprctl(*args: str) -> str | None: + """One read-only `hyprctl` call, or `None` if it is not usable. + + Allowed by the review's §B1 so the warp hits a known box. `dispatch` is + deliberately never passed here: there is one call site and it takes the + query words, so a reader can see the whole of what this probe asks for. + """ + + try: + done = subprocess.run( + ["hyprctl", "-i", "0", *args], + capture_output=True, + text=True, + timeout=5, + check=False, + ) + except (OSError, subprocess.SubprocessError) as exc: + say(f" hyprctl {' '.join(args)}: unavailable ({exc})") + return None + if done.returncode != 0: + say(f" hyprctl {' '.join(args)}: exit {done.returncode} {done.stderr.strip()}") + return None + return done.stdout + + +def report_options() -> None: + say(" options this measurement depends on:") + for option in OPTIONS: + raw = hyprctl("getoption", option, "-j") + if raw is None: + continue + try: + value = json.loads(raw) + except ValueError: + say(f" {option} = ") + continue + # Printed whole, including the zeros: `follow_mouse_threshold = 0` is + # the value (a) turns on, and a filter that hid falsy fields would hide + # exactly the number the reader came for. + say(f" {option} = {json.dumps(value, sort_keys=True)}") + + +def boxes() -> dict[str, tuple[int, int, int, int]]: + """`app-id -> (x, y, w, h)` for our own windows, from `hyprctl clients`.""" + + raw = hyprctl("clients", "-j") + if raw is None: + return {} + try: + clients = json.loads(raw) + except ValueError: + return {} + found = {} + for client in clients: + app_id = client.get("initialClass") or client.get("class") + if app_id in (APP_A, APP_B): + x, y = client.get("at", [0, 0]) + w, h = client.get("size", [0, 0]) + found[app_id] = (x, y, w, h) + return found + + +def pick_point( + target: tuple[int, int, int, int], + avoid: tuple[int, int, int, int] | None, + monitor: tuple[int, int], +) -> tuple[float, float] | None: + """A normalised point inside `target` and outside `avoid`. + + Returns `None` when there is no such point, which is a real outcome and not + a bug: with this machine's catch-all rule two ordinary windows are the same + box, and a probe that warped anyway would be measuring nothing. + """ + + tx, ty, tw, th = target + width, height = monitor + candidates = [] + for fx in (0.01, 0.05, 0.5, 0.95, 0.99): + for fy in (0.01, 0.05, 0.5, 0.95, 0.99): + candidates.append((tx + tw * fx, ty + th * fy)) + for px, py in candidates: + if avoid is not None: + ax, ay, aw, ah = avoid + if ax <= px <= ax + aw and ay <= py <= ay + ah: + continue + if not (0 <= px < width and 0 <= py < height): + continue + return (px / width, py / height) + return None + + +# -------------------------------------------------------------------------- +# the keymap we upload +# -------------------------------------------------------------------------- + + +def keymap_text(layout: str, model: str) -> str: + """A keymap for `layout`, compiled rather than written out by hand. + + xkbcommon because an uploaded keymap that does not compile is + indistinguishable, from the client side, from a compositor that ignored the + upload — and because this is the library Stage 1's `keymap.py` uses, so a + failure here is a failure that matters. + """ + + from xkbcommon import xkb + + keymap = xkb.Context().keymap_new_from_names( + rules="evdev", model=model, layout=layout, variant="", options="" + ) + return keymap.get_as_bytes().decode("utf-8") + + +def keymap_fd(text: str) -> tuple[int, int]: + """A memfd holding `text` **NUL-terminated**, and its size including the NUL. + + The terminator is load-bearing and is the review's change 2: Hyprland + `mmap`s exactly `size` bytes and hands the pointer to + `xkb_keymap_new_from_string`, which wants a C string, so a size that + excludes the NUL reads off the end of the mapping. + """ + + payload = text.encode("utf-8") + b"\0" + fd = os.memfd_create("hhs-probe-keymap", 0) + os.ftruncate(fd, len(payload)) + with os.fdopen(os.dup(fd), "wb", closefd=True) as handle: + handle.write(payload) + return fd, len(payload) + + +# -------------------------------------------------------------------------- +# the probe +# -------------------------------------------------------------------------- + + +class Probe: + def __init__(self, vk_module, *, layout: str, model: str, output_name: str | None) -> None: + self.vk = vk_module + self.layout = layout + self.model = model + self.output_name = output_name + + self.display: Display | None = None + self.compositor = None + self.shm = None + self.wm_base = None + self.seat = None + self.vk_manager = None + self.vk_manager_version = 0 + self.vp_manager: tuple | None = None + self.vp_manager_version = 0 + #: registry id -> [proxy, name-or-None, (width, height)] + self.outputs: dict[int, list] = {} + self.globals: list[tuple[str, int]] = [] + + self.keyboard = None + self.pointer = None + self.windows: list[_Window] = [] + self.virtual_pointer = None + self.virtual_keyboards: list = [] + + #: The compositor's own keymap, as forwarded over `wl_keyboard.keymap`, + #: and a state machine over it. Every `sym=` in the log comes from + #: here, which is the review's rule for the keymap-upload assertion. + self._keymap = None + self._state = None + self._mask = (0, 0, 0, 0) + + #: Observations. A list rather than counters: the order of a `leave` + #: and an `enter` is part of the answer to (a). + self.events: list[str] = [] + #: The app id that currently holds keyboard focus, `"other"` for a + #: window that is not ours, `None` for nothing. + self.focus: str | None = None + self.repeat_info: tuple[int, int] | None = None + + # -- lifecycle ----------------------------------------------------- + + def connect(self, runtime_dir: pathlib.Path) -> None: + names = sorted( + p.name + for p in runtime_dir.iterdir() + if p.name.startswith("wayland-") and not p.name.endswith(".lock") + ) + if len(names) != 1: + # `backend.find_wayland_display` refuses the same way: guessing + # which of two compositors to drive is a coin flip. + raise SystemExit( + f"keyboard-probe: expected one wayland-* socket in {runtime_dir}, " + f"found {names or 'none'}" + ) + os.environ["XDG_RUNTIME_DIR"] = str(runtime_dir) + self.display = Display(names[0]) + self.display.connect() + registry = self.display.get_registry() + registry.dispatcher["global"] = self._on_global + # Twice: the first trip delivers the globals, the second the `name` and + # `mode` events the bound outputs emit. + self.display.roundtrip() + self.display.roundtrip() + + def close(self) -> None: + if self.display is not None: + self.display.disconnect() + self.display = None + + def _on_global(self, registry, global_id: int, interface: str, version: int) -> None: + self.globals.append((interface, version)) + if interface == WlCompositor.name: + self.compositor = registry.bind(global_id, WlCompositor, min(version, 4)) + elif interface == WlShm.name: + self.shm = registry.bind(global_id, WlShm, 1) + elif interface == XdgWmBase.name: + self.wm_base = registry.bind(global_id, XdgWmBase, min(version, 2)) + self.wm_base.dispatcher["ping"] = lambda base, serial: base.pong(serial) + elif interface == WlSeat.name and self.seat is None: + self.seat = registry.bind(global_id, WlSeat, min(version, 5)) + self.seat.dispatcher["capabilities"] = lambda _s, caps: self.events.append( + f"seat capabilities={caps}" + ) + elif interface == WlOutput.name: + entry = [registry.bind(global_id, WlOutput, min(version, 4)), None, (0, 0)] + entry[0].dispatcher["name"] = lambda _p, name, e=entry: e.__setitem__(1, name) + entry[0].dispatcher["mode"] = ( + lambda _p, flags, w, h, refresh, e=entry: e.__setitem__(2, (w, h)) + ) + self.outputs[global_id] = entry + elif interface == self.vk.ZwpVirtualKeyboardManagerV1.name: + self.vk_manager_version = version + self.vk_manager = registry.bind( + global_id, self.vk.ZwpVirtualKeyboardManagerV1, WANTED_MANAGER_VERSION + ) + elif interface == "zwlr_virtual_pointer_manager_v1": + # Kept as (registry, id) and bound later: the class comes from the + # driver's vendored package, and importing it needs a `sys.path` + # edit that a registry callback should not be doing. + self.vp_manager_version = version + self.vp_manager = (registry, global_id) + + # -- event pump ---------------------------------------------------- + + def pump(self, seconds: float) -> None: + """Dispatch for `seconds`, then return. Never raises on a timeout. + + A `roundtrip()` is not enough for any of these questions: each one is a + *negative* as well as a positive — no `enter`, no release, no repeat — + so the probe has to wait out a real interval and report what did not + arrive. + """ + + assert self.display is not None + deadline = time.monotonic() + seconds + while True: + self.display.flush() + remaining = deadline - time.monotonic() + if remaining <= 0: + return + readable, _, _ = select.select([self.display.get_fd()], [], [], remaining) + if not readable: + return + self.display.read() + if self.display.dispatch(block=False) < 0: + raise SystemExit("keyboard-probe: the compositor closed the connection") + + # -- setup steps --------------------------------------------------- + + def output(self): + """The output to bind the virtual pointer to: proxy, name, and mode. + + Named rather than implicit for the same reason `backend.py` resolves by + name: warp coordinates are output-local, so a pointer bound to the + wrong output aims somewhere else entirely. + """ + + named = {entry[1]: entry for entry in self.outputs.values() if entry[1]} + if self.output_name: + if self.output_name not in named: + raise SystemExit( + f"keyboard-probe: no output named {self.output_name!r} " + f"(known: {', '.join(sorted(named)) or 'none'})" + ) + chosen = self.output_name + elif len(named) != 1: + raise SystemExit( + f"keyboard-probe: {len(named)} outputs ({', '.join(sorted(named))}); " + "pass --output to say which" + ) + else: + chosen = next(iter(named)) + entry = named[chosen] + return entry[0], chosen, entry[2] + + def bind_keyboard(self) -> None: + """Bind `wl_keyboard` and wire every event we measure. + + Bound *after* a virtual keyboard exists: this seat has no physical + keyboard (the headless unit sets `WLR_LIBINPUT_NO_DEVICES=1`, and + `hyprctl devices` lists none), so until something creates a virtual one + the seat advertises no keyboard capability and `get_keyboard` returns a + proxy that never speaks. + """ + + self.keyboard = self.seat.get_keyboard() + self.keyboard.dispatcher["keymap"] = self._on_keymap + self.keyboard.dispatcher["enter"] = self._on_enter + self.keyboard.dispatcher["leave"] = self._on_leave + self.keyboard.dispatcher["key"] = self._on_key + self.keyboard.dispatcher["modifiers"] = self._on_modifiers + self.keyboard.dispatcher["repeat_info"] = self._on_repeat_info + self.display.roundtrip() + + def bind_pointer(self) -> None: + self.pointer = self.seat.get_pointer() + self.pointer.dispatcher["enter"] = self._on_pointer_enter + self.pointer.dispatcher["leave"] = lambda _p, serial, surface: self.events.append( + "wl_pointer.leave" + ) + self.display.roundtrip() + + def create_virtual_pointer(self): + registry, global_id = self.vp_manager + # Version 2 for `create_virtual_pointer_with_output`, exactly as + # `hhstream_pointer.backend` requires: version 1's coordinates are the + # global layout, so a 0.5,0.5 warp would not be this output's centre. + manager = registry.bind(global_id, _wlr_pointer_manager(), 2) + proxy, name, mode = self.output() + self.virtual_pointer = manager.create_virtual_pointer_with_output(self.seat, proxy) + return name, mode + + def create_virtual_keyboard(self): + """Create one device and upload one keymap to it, in that order. + + One keymap per device, sent once: a second `keymap` on the same device + replaces Hyprland's xkb state without walking `m_pressed`, which is + exactly the state (b) and (c) are about. + """ + + keyboard = self.vk_manager.create_virtual_keyboard(self.seat) + fd, size = keymap_fd(keymap_text(self.layout, self.model)) + try: + keyboard.keymap(XKB_FORMAT_TEXT_V1, fd, size) + # Round-trip before the fd is closed: the compositor has to have + # received and mapped it, and a flush is not a receipt. + self.display.roundtrip() + finally: + os.close(fd) + self.virtual_keyboards.append(keyboard) + self.events.append(f"uploaded keymap format={XKB_FORMAT_TEXT_V1} size={size}") + return keyboard + + def open_windows(self) -> None: + """`kb-probe-a` fullscreen, then `kb-probe-b` on top of it. + + See the module docstring: the fullscreen one exists so the probe has an + unfocused window of its own to warp onto on a machine whose window rule + gives every window the same box. + """ + + first = _Window(self, APP_A) + first.toplevel.set_fullscreen(None) + first.surface.commit() + self.windows.append(first) + self.display.roundtrip() + self.display.roundtrip() + self.windows.append(_Window(self, APP_B)) + self.display.roundtrip() + self.display.roundtrip() + + # -- events -------------------------------------------------------- + + def _app_of(self, surface) -> str: + for window in self.windows: + if window.surface == surface: + return window.app_id + return "other" + + def _on_keymap(self, keyboard, format_: int, fd: int, size: int) -> None: + """Compile what the compositor forwarded, and decode every later key + with it. A symbol decoded from a table in this file would prove + nothing about whether our upload arrived.""" + + from xkbcommon import xkb + + try: + with os.fdopen(fd, "rb", closefd=True) as handle: + raw = handle.read(size) + except OSError as exc: + self.events.append(f"wl_keyboard.keymap bytes={size} UNREADABLE {exc}") + return + text = raw.split(b"\0", 1)[0].decode("utf-8", "replace") + symbols = next( + (line.strip() for line in text.splitlines() if "xkb_symbols" in line), "?" + ) + try: + self._keymap = xkb.Context().keymap_new_from_string(text) + self._state = self._keymap.state_new() + except Exception as exc: # a keymap we cannot compile is the finding + self.events.append(f"wl_keyboard.keymap bytes={size} WILL NOT COMPILE: {exc}") + return + self.events.append( + f"wl_keyboard.keymap format={format_} bytes={size} symbols={symbols}" + ) + + def _sym(self, code: int) -> str: + """The keysym name for an evdev code under the forwarded keymap.""" + + if self._state is None: + return "?" + from xkbcommon import xkb + + return xkb.keysym_get_name(self._state.key_get_one_sym(code + EVDEV_OFFSET)) + + def _on_enter(self, keyboard, serial, surface, keys) -> None: + app = self._app_of(surface) + self.focus = app + self.events.append( + f"enter surface={app} serial={serial} keys={list(keys) if keys else []}" + ) + + def _on_leave(self, keyboard, serial, surface) -> None: + app = self._app_of(surface) + if app == self.focus: + self.focus = None + self.events.append(f"leave surface={app}") + + def _on_key(self, keyboard, serial, time_, key: int, state: int) -> None: + self.events.append(f"key code={key} state={state} sym={self._sym(key)}") + + def _on_modifiers(self, keyboard, serial, depressed, latched, locked, group) -> None: + self._mask = (depressed, latched, locked, group) + if self._state is not None: + # Mask first, then the sym lookup above is the one a real client + # would do: `A` is only `A` because Shift is in this mask. + self._state.update_mask(depressed, latched, locked, 0, 0, group) + self.events.append( + f"modifiers depressed={depressed} latched={latched} " + f"locked={locked} group={group}" + ) + + def _on_repeat_info(self, keyboard, rate: int, delay: int) -> None: + self.repeat_info = (rate, delay) + self.events.append(f"repeat_info rate={rate} delay={delay}") + + def _on_pointer_enter(self, pointer, serial, surface, x, y) -> None: + self.events.append( + f"wl_pointer.enter surface={self._app_of(surface)} at {x:.0f},{y:.0f}" + ) + + # -- the two actions the probe performs ----------------------------- + + def warp(self, x: float, y: float) -> None: + self.virtual_pointer.motion_absolute( + _now_ms(), round(x * EXTENT), round(y * EXTENT), EXTENT, EXTENT + ) + self.virtual_pointer.frame() + self.display.flush() + + def key(self, keyboard, code: int, state: int) -> None: + keyboard.key(_now_ms(), code, state) + self.display.flush() + + def modifiers(self, keyboard, depressed: int) -> None: + keyboard.modifiers(depressed, 0, 0, 0) + self.display.flush() + + # -- reporting ------------------------------------------------------ + + def report(self, prefix: str = "") -> list[str]: + seen, self.events[:] = list(self.events), [] + for line in seen: + say(f" {prefix}{line}") + return seen + + +def _now_ms() -> int: + """A millisecond timestamp for the protocol's `time` arguments. + + The same function `hhstream_pointer.backend` uses, for the reason the + protocol gives: all requests on one object must share one clock, and the + compositor only compares them to each other. + """ + + return int(time.monotonic() * 1000) & 0xFFFFFFFF + + +def _wlr_pointer_manager(): + """The wlr virtual-pointer manager class, from the repo's vendored copy. + + Imported by path so the probe runs from a checkout without the package + being installed: Stage 0 has no reason to grow a second copy of a protocol + the driver already vendors. + """ + + sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent.parent / "src")) + from hhstream_pointer._protocol.wlr_virtual_pointer_unstable_v1 import ( + ZwlrVirtualPointerManagerV1, + ) + + return ZwlrVirtualPointerManagerV1 + + +class _Window: + """One toplevel, painted once, with an app id of its own. + + Modelled on `checks/lib/pointer_target.py` and deliberately not shared with + it: that client is a VM fixture with a contract of its own (it reads + `$HHSTREAM_APP_ID`, because a container's window rule is written against + it), and this one is a probe that will be deleted. + """ + + def __init__(self, probe: Probe, app_id: str) -> None: + self.probe = probe + self.app_id = app_id + self.size = DEFAULT_SIZE + self._pool = None + self._map: mmap.mmap | None = None + self.buffer = None + + self.surface = probe.compositor.create_surface() + self.xdg_surface = probe.wm_base.get_xdg_surface(self.surface) + self.xdg_surface.dispatcher["configure"] = self._on_configure + self.toplevel = self.xdg_surface.get_toplevel() + self.toplevel.set_app_id(app_id) + self.toplevel.set_title(app_id) + self.toplevel.dispatcher["configure"] = self._on_toplevel_configure + self.surface.commit() + + def _on_toplevel_configure(self, toplevel, width, height, states) -> None: + if width and height: + self.size = (width, height) + + def _on_configure(self, xdg_surface, serial) -> None: + xdg_surface.ack_configure(serial) + width, height = self.size + stride, size = width * 4, width * 4 * height + if self._map is None or self._map.size() < size: + fd = os.memfd_create(f"hhs-probe-{self.app_id}", 0) + os.ftruncate(fd, size) + self._map = mmap.mmap(fd, size) + self._pool = self.probe.shm.create_pool(fd, size) + os.close(fd) + self._map.seek(0) + self._map.write(struct.pack(" int: + say() + say("=== 1. globals on this compositor ===") + for interface, version in sorted(probe.globals): + say(f" global {interface} v{version}") + wanted = probe.vk.ZwpVirtualKeyboardManagerV1.name + if probe.vk_manager is None: + say(f"ANSWER 1: {wanted} is ABSENT. The plan says stop here.") + return 2 + if probe.vk_manager_version != WANTED_MANAGER_VERSION: + say( + f"ANSWER 1: {wanted} is version {probe.vk_manager_version}, not " + f"{WANTED_MANAGER_VERSION}. The plan says stop here." + ) + return 2 + say(f"ANSWER 1: {wanted} is present at version {probe.vk_manager_version}.") + if probe.vp_manager is None: + say(" ...but zwlr_virtual_pointer_manager_v1 is absent, so (a) cannot be measured.") + return 2 + say(f" zwlr_virtual_pointer_manager_v1 v{probe.vp_manager_version} (needed for (a)).") + return 0 + + +def question_focus(probe: Probe, output_name: str, mode: tuple[int, int]) -> None: + say() + say("=== (a) does a virtual-pointer warp move wl_keyboard focus? ===") + report_options() + geometry = boxes() + say(f" output {output_name} mode {mode[0]}x{mode[1]}") + for app, box in sorted(geometry.items()): + say(f" box {app} at {box[0]},{box[1]} size {box[2]}x{box[3]}") + say(f" focus at map time: {probe.focus} (expected {APP_B}: it mapped last)") + + if APP_A not in geometry: + say( + "SKIPPED (a): hyprctl did not report our windows, so there is no " + "known box to warp into. Re-run with hyprctl on PATH." + ) + return + target = pick_point(geometry[APP_A], geometry.get(APP_B), mode) + if target is None: + say( + f"SKIPPED (a): no point is inside {APP_A} and outside {APP_B} — the two " + "windows cover each other exactly, so no warp could tell them apart. " + "Measure it in vm-keyboard, where two sessions have two outputs." + ) + return + second = (target[0], min(1.0, target[1] + A2_OFFSET)) + say(f" (a1) target {target[0]:.4f},{target[1]:.4f} (inside {APP_A} only)") + say( + f" (a2) target {second[0]:.4f},{second[1]:.4f} — about " + f"{round(A2_OFFSET * mode[1])}px lower, so the FLOORED pixel changes. A " + "second warp to the same point would return before mouseMoveUnified " + "touched the delta, and would prove nothing." + ) + + # The whole point of (a1): the cursor must have been still for longer than + # Hyprland's 0.5 s window, or the delta from an earlier move carries it. + probe.pump(IDLE_S) + probe.report("idle -> ") + + say(f" (a1) one warp after {IDLE_S}s of stillness") + first_sent = time.monotonic() + probe.warp(*target) + probe.pump(SETTLE_S) + first_bucket = probe.report("(a1) -> ") + + say(" (a2) a second warp, to the (a2) target above") + gap = time.monotonic() - first_sent + probe.warp(*second) + probe.pump(SETTLE_S) + second_bucket = probe.report("(a2) -> ") + # Timed rather than asserted in prose: (a2) is the in-window case only + # while this stays under 0.5 s, and an earlier version of this script + # printed the word "immediately" about a gap it never measured. + say( + f" gap between the two motion_absolute calls: {gap:.3f}s " + f"({'under' if gap < 0.5 else 'OVER'} Hyprland's 0.5s delta window)" + ) + + # `startswith`, not `in`: `wl_pointer.enter surface=kb-probe-a` contains + # the substring `enter surface=kb-probe-a`, and an `in` test here reported + # a1_enter=yes off a pointer event. That is the review's own category of + # false pass, found in this probe. + entered_a1 = any(line.startswith(f"enter surface={APP_A}") for line in first_bucket) + entered_a2 = any(line.startswith(f"enter surface={APP_A}") for line in second_bucket) + pointer_moved = any( + line.startswith(f"wl_pointer.enter surface={APP_A}") + for line in first_bucket + second_bucket + ) + say( + f" a1_enter={'yes' if entered_a1 else 'no'} " + f"a2_enter={'yes' if entered_a2 else 'no'} " + f"pointer_reached_{APP_A}={'yes' if pointer_moved else 'no'}" + ) + if entered_a1: + say( + f"ANSWER (a): the idle warp DID deliver wl_keyboard.enter to {APP_A}. " + "That is not what v0.56.2's threshold logic predicts, so this binary " + "does not match the read of InputManager::onMouseWarp. Stage 3 must " + "still assert it rather than assume it." + ) + elif entered_a2: + say( + f"ANSWER (a): the idle warp onto unfocused {APP_A} delivered " + f"wl_pointer.enter and NO wl_keyboard.enter. {APP_B}'s leave and " + f"{APP_A}'s enter arrived only after the LATER motion_absolute, the " + "one that changed the floored pixel -- so the enter belongs to that " + "motion's non-zero m_mousePosDelta and is NOT a delayed effect of " + "the first warp." + ) + say( + " Consequence: `pointer acquire` is one warp, so the first " + "key of a lease can land in whatever was already focused. Stage 3's " + "enter subtest must not be written against acquire's single warp, " + "and warping twice to the same bookmark is not the fix -- the same " + "floored pixel returns early." + ) + elif pointer_moved: + say( + f"ANSWER (a): NO — the cursor reached {APP_A} (wl_pointer.enter above) " + "and keyboard focus never followed, on either warp. Stage 4 " + "(dispatch focuswindow before the first key of a lease) is required." + ) + else: + say( + "ANSWER (a): INCONCLUSIVE — the cursor never reached the aimed window " + "at all, so focus was never in question. Read the boxes above." + ) + + +def question_repeat(probe: Probe) -> None: + """(c), and it deliberately leaves the key down for (b).""" + + say() + say("=== (c) is one held virtual key one wl_keyboard.key? ===") + if probe.focus not in (APP_A, APP_B): + say("SKIPPED (c): no window of ours holds keyboard focus; refusing to type.") + return + keyboard = probe.virtual_keyboards[0] + probe.report("before -> ") + probe.key(keyboard, KEY_A, PRESSED) + probe.pump(REPEAT_HOLD_S) + held = probe.report("") + presses = sum( + 1 + for line in held + if f"key code={KEY_A} state={PRESSED}" in line or f"key code={KEY_A} state={REPEATED}" in line + ) + say(f" press_count={presses} repeat_info={probe.repeat_info}") + if presses > 1: + say(f"ANSWER (c): {presses} events in {REPEAT_HOLD_S}s — the compositor repeats.") + elif presses == 1: + say( + "ANSWER (c): press_count=1 — the compositor does not repeat on the " + f"wire; it published repeat_info {probe.repeat_info} and the CLIENT " + "repeats. This is NOT 'keyboard down will not flood a text field': " + "foot/GTK/Qt will insert characters from this one press until the " + "key-up or the lease TTL. The help text must warn unconditionally." + ) + else: + say("ANSWER (c): INCONCLUSIVE — the press itself never arrived.") + say(f" (key code={KEY_A} deliberately left down, for (b))") + + +def question_destroy(probe: Probe) -> None: + """(b): destroy with the key from (c) still down. No key-up first.""" + + say() + say("=== (b) does destroying the virtual keyboard release a held key? ===") + if probe.focus not in (APP_A, APP_B): + say("SKIPPED (b): no window of ours holds keyboard focus; refusing to type.") + return + # A second device first. With only one, `destroy` takes the seat's last + # keyboard away, `wl_keyboard` goes with it, and "no release arrived" would + # be ambiguous: no release *could* arrive. The spare keeps the capability + # up so a release has somewhere to be delivered. + spare = probe.create_virtual_keyboard() + probe.pump(0.3) + probe.report("spare -> ") + + victim = probe.virtual_keyboards[0] + victim.destroy() + probe.virtual_keyboards.remove(victim) + probe.pump(1.0) + after = probe.report("after destroy -> ") + + released = any(f"key code={KEY_A} state={RELEASED}" in line for line in after) + cleared = any("modifiers depressed=0" in line for line in after) + say( + f" release_on_destroy={'yes' if released else 'no'} " + f"mask_cleared={'yes' if cleared else 'no'}" + ) + say(" (compare with input:virtualkeyboard:release_pressed_on_close, printed above)") + if released: + say("ANSWER (b): YES — destroy released the held key.") + else: + say( + "ANSWER (b): NO RELEASE — destroy delivered no key-up, with a second " + "keyboard keeping the seat's capability up and with nothing of ours " + "having sent an up beforehand." + ) + say( + " Read `mask_cleared` narrowly: it says only that destroy " + "emitted no `modifiers` event. The held key is a letter, so the " + "depressed mask was 0 throughout -- this is NOT a measurement of a " + "non-zero mask surviving destroy. releasePressed emits key-ups only " + "(VirtualKeyboard.cpp), which is why release_all sends " + "modifiers(0,0,0,0) regardless." + ) + say( + " The confirming evidence is the cleanup below: " + "onKeyboardKey DROPS a release whose code is not in the seat's " + f"m_pressed, so a `key code={KEY_A} state=0` arriving from a BRAND " + "NEW keyboard means the code was still in that set after destroy. A " + "driver killed with -9 leaves it there and the next driver's press " + "of it is dropped: dead, not merely stuck. _lift_everything is the " + "only guard on the clean path and SIGKILL skips it." + ) + + # Required cleanup, and it is the review's step 7: a NEW virtual keyboard, + # its own keymap, then the key-up and a zeroed mask that undo a poisoned + # m_pressed. Without this the next run of anything inherits a dead key. + fresh = probe.create_virtual_keyboard() + probe.key(fresh, KEY_A, RELEASED) + probe.modifiers(fresh, 0) + probe.pump(0.4) + probe.report("cleanup -> ") + say(" cleanup=sent") + probe.modifiers(spare, 0) + + +def main(argv: list[str] | None = None) -> int: + parser = argparse.ArgumentParser( + prog="keyboard-probe", + description=__doc__.splitlines()[0], + epilog="Read-only with respect to the broker: it speaks to the compositor only.", + ) + parser.add_argument( + "--runtime-dir", + type=pathlib.Path, + default=pathlib.Path("/run/hypr-stream"), + help="the compositor's XDG_RUNTIME_DIR (default: %(default)s)", + ) + parser.add_argument("--xml", type=pathlib.Path, default=None, help=f"path to {XML_NAME}") + parser.add_argument("--output", default=None, help="output name; only needed if several") + parser.add_argument("--xkb-layout", default="us") + parser.add_argument("--xkb-model", default="pc105") + args = parser.parse_args(argv) + + module = load_virtual_keyboard(find_xml(args.xml)) + probe = Probe(module, layout=args.xkb_layout, model=args.xkb_model, output_name=args.output) + probe.connect(args.runtime_dir) + try: + gate = question_globals(probe) + if gate: + return gate + output_name, mode = probe.create_virtual_pointer() + # The device before the listener: with no physical keyboard on this + # seat, `wl_keyboard` has nothing to report until a virtual one exists. + probe.create_virtual_keyboard() + probe.bind_keyboard() + probe.bind_pointer() + probe.open_windows() + probe.pump(1.0) + setup = probe.report("setup -> ") + stale = [line for line in setup if "keys=[" in line and "keys=[]" not in line] + if stale: + # Worth shouting about: a key down in a *fresh* client's very first + # `enter` was left there by something that is no longer running. + # It is the evidence (b) asks for, arriving before (b) is asked. + say( + " NOTE: this connection was handed a key that was already " + f"down: {stale[-1].strip()}. Nothing of ours is holding it." + ) + + question_focus(probe, output_name, mode) + question_repeat(probe) + question_destroy(probe) + finally: + # Lift anything still down before the connection goes, because that is + # the only guard the driver has either + # (`hhstream_pointer.__main__._lift_everything`). + for keyboard in probe.virtual_keyboards: + probe.key(keyboard, KEY_A, RELEASED) + probe.modifiers(keyboard, 0) + probe.pump(0.3) + probe.close() + say() + say("Done. Nothing here touched the broker, the lease or any session.") + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/tests/pointer/test_driver_flags.py b/tests/pointer/test_driver_flags.py new file mode 100644 index 0000000..0087a4e --- /dev/null +++ b/tests/pointer/test_driver_flags.py @@ -0,0 +1,363 @@ +"""The driver's XKB flags — the only path a layout has to the uploaded keymap. + +This file exists where a `tests/sessions/unit/test_settings.py` case would have +gone, and that is the point. The broker's TOML is read by `hhstreamd` for its +lease numbers; `hhstream-pointer` is a different unit and never opens that +file. So a `[keyboard]` table there would be a setting an operator could change +with no effect at all, and a test asserting its default would be green while +every injected key stayed on `us`. + +The layout therefore arrives as `--xkb-layout`, and these are the assertions +about that flag: what it defaults to, that a bad value is exit **2**, and that +a bad value is exit 2 **without the compositor being touched** — because a +layout xkbcommon will not compile is the operator's typo, and reporting it as +exit 10 sends them to the wrong unit. +""" + +from __future__ import annotations + +import os +from pathlib import Path + +import pytest + +from hhstream_pointer import __main__ as entry + + +class _Unreached(Exception): + """Raised if the Wayland side is reached when it should not have been.""" + + +class _RefusingSink: + """A sink that fails the test if anything asks it to talk to a compositor. + + The review asked for an injected connect that can be asserted *not* to have + been called; this is that, as a type rather than a flag, so a future code + path that connects earlier fails loudly instead of silently reordering + start-up. + """ + + instances = 0 + + def __init__(self, runtime_dir, display_name=None) -> None: + type(self).instances += 1 + + def connect(self) -> None: + raise _Unreached("connect") + + def upload_keymap(self, text: str) -> None: + raise _Unreached("upload_keymap") + + def close(self) -> None: + pass + + +@pytest.fixture +def no_compositor(monkeypatch): + _RefusingSink.instances = 0 + monkeypatch.setattr(entry, "WaylandSink", _RefusingSink) + return _RefusingSink + + +# -- defaults --------------------------------------------------------------- + + +def test_the_xkb_flags_default_to_the_frozen_values(): + args = entry.build_parser().parse_args([]) + assert args.xkb_layout == "us" + assert args.xkb_model == "pc105" + assert (args.xkb_variant, args.xkb_options) == ("", "") + + +def test_the_defaults_are_the_ones_the_module_option_defaults_to(): + # Stated as constants so the NixOS option and the hand-run binary cannot + # drift into typing different characters. + assert (entry.DEFAULT_LAYOUT, entry.DEFAULT_MODEL) == ("us", "pc105") + + +def test_a_layout_is_taken_from_the_flag(): + assert entry.build_parser().parse_args(["--xkb-layout", "de"]).xkb_layout == "de" + + +def test_the_contract_command_line_still_parses(): + """CONTRACT-sessions.md §3.4's exact line, plus the keymap flags.""" + + args = entry.build_parser().parse_args( + [ + "--socket", + "/run/hhstream/pointer.sock", + "--compositor-runtime-dir", + "/run/hypr-stream", + "--xkb-layout", + "us", + "--xkb-model", + "pc105", + "--xkb-variant", + "", + "--xkb-options", + "", + ] + ) + assert str(args.socket) == "/run/hhstream/pointer.sock" + assert str(args.compositor_runtime_dir) == "/run/hypr-stream" + assert args.xkb_layout == "us" + + +# -- refusals, before any Wayland call -------------------------------------- + + +def test_a_comma_separated_layout_exits_2_without_connecting(no_compositor, caplog): + """v1 sends group 0 in every `modifiers`, so a second group is unreachable. + + xkbcommon accepts `us,ru` and hands back a two-group keymap, so nothing + downstream would notice: a caller asking for Cyrillic would get Latin and + no error. Refused here, and the NixOS option's type refuses it too — this + one is for the binary run by hand, which that type cannot reach. + """ + + code = entry.main(["--xkb-layout", "us,ru"]) + + assert code == entry.EXIT_USAGE + assert no_compositor.instances == 0, "the compositor must not be touched" + + +def test_a_layout_xkbcommon_rejects_exits_2_without_connecting(no_compositor): + code = entry.main(["--xkb-layout", "zzz-no-such-layout"]) + + assert code == entry.EXIT_USAGE + assert no_compositor.instances == 0 + + +def test_a_usable_layout_gets_as_far_as_the_compositor(no_compositor): + """The other half: exit 2 must not be how a *good* layout fails. + + A test that only asserted the refusals would pass against a `main` that + returned 2 for everything, so this one proves the good path reaches the + Wayland side and fails there instead. + """ + + with pytest.raises(_Unreached, match="connect"): + entry.main(["--xkb-layout", "us"]) + assert no_compositor.instances == 1 + + +def test_the_exit_codes_match_the_brokers_table(): + """Mirrored constants, compared against the table they mirror. + + The driver keeps its own copies on purpose -- it is a separate package and + must not import the broker's internals -- so the two can drift, and + asserting the literals alone would not notice. This imports the broker's + enum to compare, which a test may do where the shipped driver may not. + """ + + from hhstreamd.protocol import ExitCode + + assert entry.EXIT_OK == ExitCode.OK + assert entry.EXIT_USAGE == ExitCode.USAGE + assert entry.EXIT_COMPOSITOR == ExitCode.COMPOSITOR + + +def test_the_module_passes_the_same_defaults_this_binary_has(): + """The drift this guards is silent: a unit and a hand-run binary that type + different characters, with nothing to compare them against but prose.""" + + module = Path(__file__).resolve().parents[2] / "nix/module.nix" + if not module.is_file(): + pytest.skip("not running from a checkout") + text = module.read_text() + assert f'default = "{entry.DEFAULT_LAYOUT}";' in text + assert f'default = "{entry.DEFAULT_MODEL}";' in text + # And the unit really passes them, rather than relying on these defaults: + # a unit that relied on them would stop matching the contract's command + # line the moment either moved. + for flag in ("--xkb-layout", "--xkb-model", "--xkb-variant", "--xkb-options"): + assert f'"{flag}"' in text, f"{flag} is not on the unit's ExecStart" + + +# -- the keymap upload, which nothing else in the suite can see -------------- +# +# The dispatcher tests record tuples from a sink, so they are blind to the +# Wayland `keymap` request: its format, its fd and its size never reach them. +# That is the review's finding 3 -- a `main` that connected and listened +# WITHOUT ever uploading passed every other test in this tree, and so did a +# backend that re-uploaded on every `type`. + + +#: One ordering log shared by the sink and the server stand-ins, because the +#: assertion is about the order of events *between* the two objects: an upload +#: after `listen` is a socket that promised a working device before it had one. +ORDER: list[str] = [] + + +class _UploadingSink: + """A sink whose connect succeeds, recording what it was asked to upload.""" + + def __init__(self, runtime_dir, display_name=None) -> None: + self.uploads: list[str] = [] + self.connected = 0 + _UploadingSink.last = self + + def connect(self) -> None: + self.connected += 1 + ORDER.append("connect") + + def upload_keymap(self, text: str) -> None: + self.uploads.append(text) + ORDER.append("upload") + + def has_keyboard(self) -> bool: + return True + + def outputs(self) -> list[str]: + return [] + + def close(self) -> None: + pass + + +class _RecordingServer: + """Stands in for `PointerServer`, so no socket is bound. + + `serve_forever` raises, which is how the test gets control back at exactly + the point the real process would start answering requests -- and therefore + how it can assert the upload happened *before* that. + """ + + class Served(Exception): + pass + + def __init__(self, socket_path, handle, *, socket_mode=0o660) -> None: + self.events: list[str] = [] + _RecordingServer.last = self + + def listen(self) -> None: + self.events.append("listen") + ORDER.append("listen") + + def serve_forever(self) -> None: + self.events.append("serve") + ORDER.append("serve") + raise _RecordingServer.Served + + def close(self) -> None: + self.events.append("close") + + +@pytest.fixture +def uploading(monkeypatch): + ORDER.clear() + monkeypatch.setattr(entry, "WaylandSink", _UploadingSink) + monkeypatch.setattr(entry, "PointerServer", _RecordingServer) + return _UploadingSink + + +def test_the_keymap_is_uploaded_once_before_the_socket_listens(uploading): + """The ordering rule, asserted rather than described. + + `key` or `modifiers` before `keymap` is the protocol error `no_keymap`, + which kills the connection instead of returning something the broker could + report. So the upload has to happen between `connect` and `listen` -- a + listening socket is a promise that the device works. + """ + + with pytest.raises(_RecordingServer.Served): + entry.main([]) + + sink = _UploadingSink.last + assert sink.connected == 1 + assert len(sink.uploads) == 1, "uploaded once, not per request" + # The order across both objects, which is the whole assertion. A `main` + # that never uploaded, or uploaded after `listen`, fails here -- and before + # this test existed, both passed every other test in the tree. + assert ORDER == ["connect", "upload", "listen", "serve"] + + +def test_the_uploaded_text_is_the_keymap_for_the_flag(uploading): + with pytest.raises(_RecordingServer.Served): + entry.main(["--xkb-layout", "de"]) + + (text,) = _UploadingSink.last.uploads + assert text.lstrip().startswith("xkb_keymap {") + # The symbols name, which is what the VM check greps: a `de` layout that + # silently compiled as `us` would say `pc_us_inet(evdev)` here. + assert 'xkb_symbols "pc_de_inet(evdev)"' in text + + +def test_the_payload_is_nul_terminated_and_the_size_counts_the_nul(): + """The one value Hyprland reads off the end of the mapping if it is wrong. + + It `mmap`s exactly `size` bytes and hands the pointer to + `xkb_keymap_new_from_string`, which wants a C string. A `size` of + `len(text)` therefore has no terminator inside the mapping. The symptom is + a keymap that will not compile, which from our side looks exactly like a + compositor that has no keyboard at all -- so this is asserted on the real + `WaylandSink.upload_keymap`, against a keyboard object that records the + request. + """ + + pytest.importorskip("pywayland") + from hhstream_pointer import keymap as keymaps + from hhstream_pointer.backend import WaylandSink + + class _Keyboard: + def __init__(self) -> None: + self.keymap_calls: list[tuple[int, bytes, int]] = [] + self.modifier_calls: list[tuple] = [] + + def keymap(self, format_: int, fd: int, size: int) -> None: + # Read it back through the fd the compositor is handed, not through + # the string we started from: that is what the compositor sees. + with os.fdopen(os.dup(fd), "rb", closefd=True) as handle: + handle.seek(0) + self.keymap_calls.append((format_, handle.read(size), size)) + + def modifiers(self, *args) -> None: + self.modifier_calls.append(args) + + class _Manager: + def __init__(self, keyboard) -> None: + self.keyboard = keyboard + + def create_virtual_keyboard(self, seat): + return self.keyboard + + keyboard = _Keyboard() + sink = WaylandSink(Path("/nonexistent")) + sink._keyboard_manager = _Manager(keyboard) + sink._display = _NullDisplay() + + text = keymaps.build(layout="us").text() + sink.upload_keymap(text) + + (format_, payload, size) = keyboard.keymap_calls[0] + assert format_ == keymaps.XKB_V1 == 1 + assert payload.endswith(b"\0"), "no terminator inside the mapping" + assert payload.count(b"\0") == 1, "one terminator, not two" + assert size == len(text.encode("utf-8")) + 1 + assert payload[:-1].decode("utf-8") == text + # And the mask is zeroed straight afterwards, because `destroy` of a + # previous driver's keyboard cleared no mask and a client keeps the last + # one it was sent. + assert keyboard.modifier_calls == [(0, 0, 0, 0)] + assert sink.has_keyboard() is True + + +def test_a_compositor_with_no_keyboard_manager_uploads_nothing_and_still_works(): + pytest.importorskip("pywayland") + from hhstream_pointer.backend import WaylandSink + + sink = WaylandSink(Path("/nonexistent")) + sink._display = _NullDisplay() + # No `_keyboard_manager`: the global was never advertised. + sink.upload_keymap("xkb_keymap {};") + assert sink.has_keyboard() is False + + +class _NullDisplay: + """Enough of `pywayland.client.Display` for the two calls upload makes.""" + + def roundtrip(self) -> None: + pass + + def flush(self) -> None: + pass diff --git a/tests/pointer/test_keymap.py b/tests/pointer/test_keymap.py new file mode 100644 index 0000000..78ef99f --- /dev/null +++ b/tests/pointer/test_keymap.py @@ -0,0 +1,331 @@ +"""Keysym names and text to ``(evdev code, modifier mask)``, against real xkbcommon. + +A real keymap, not a stub, and that is the whole design of this file. A stub +can be made to agree with any resolver; only xkbcommon can tell you that ``é`` +is unmappable on ``us``, that ``@`` on ``de`` is a *level-three* symbol rather +than a shifted one, and that ``y`` and ``z`` swap keycodes between the two. +Those three facts are what the resolver exists for, so ``xkbcommon`` is a hard +dependency (``pyproject.toml`` says why) and these tests do not skip. + +Codes here are **evdev**, never XKB. ``a`` is 30 and not 38: 30 is what +``zwp_virtual_keyboard_v1.key`` carries and what the client reads back off +``wl_keyboard.key``, and asserting 38 would be asserting an internal index that +never reaches the wire. + +Masks are read out of the keymap, never written down. ``A`` needs +``1 << mod_get_index("Shift")``, which happens to be 1 on every layout here — +so the test computes it, because a hard-coded 1 passes today and is wrong the +first time a resolver is asked for a level-three character. +""" + +from __future__ import annotations + +import pytest + +from hhstream_pointer import keymap as keymaps +from hhstream_pointer.ops import KIND_INVALID, Dispatcher + +#: evdev codes from ``linux/input-event-codes.h``, spelled out so a failure +#: reads against the header rather than against another part of this suite. +KEY_A = 30 +KEY_ENTER = 28 +KEY_TAB = 15 +KEY_LEFTSHIFT = 42 +KEY_Y = 21 # the physical key that is `y` on us and `z` on de +KEY_Z = 44 # ...and `z` on us, `y` on de + + +@pytest.fixture(scope="module") +def us() -> keymaps.Keymap: + return keymaps.build(layout="us") + + +@pytest.fixture(scope="module") +def de() -> keymaps.Keymap: + return keymaps.build(layout="de") + + +def shift_mask(keymap: keymaps.Keymap) -> int: + """Shift's bit, asked of the keymap rather than assumed to be 1.""" + + return 1 << keymap._keymap.mod_get_index("Shift") + + +# -- the letter path -------------------------------------------------------- + + +def test_a_lower_case_letter_is_its_evdev_code_and_no_modifier(us): + action = us.resolve_name("a") + assert (action.code, action.mask) == (KEY_A, 0) + + +def test_a_capital_is_the_same_code_with_shift_in_the_mask(us): + action = us.resolve_name("A") + assert action.code == KEY_A + assert action.mask == shift_mask(us) + # The point of the mask: a capital is NOT a Shift keycode. Hyprland's + # virtual keyboard never runs updateXkbStateWithKey, so a synthetic + # KEY_LEFTSHIFT would change no modifier state at all. + assert action.code != KEY_LEFTSHIFT + + +def test_shift_is_a_key_in_its_own_right_with_no_mask_of_its_own(us): + action = us.resolve_name("Shift_L") + # Pressing Shift needs no modifier held; what it *contributes* is separate. + assert (action.code, action.mask) == (KEY_LEFTSHIFT, 0) + assert us.is_modifier("Shift_L") + assert us.modifier_mask("Shift_L") == shift_mask(us) + + +# -- the named keys --------------------------------------------------------- + + +@pytest.mark.parametrize( + "name, code", + [("Return", KEY_ENTER), ("Tab", KEY_TAB), ("BackSpace", 14), ("Left", 105)], +) +def test_a_named_keysym_resolves_to_its_evdev_code(us, name, code): + assert us.resolve_name(name).code == code + + +@pytest.mark.parametrize("character, code", [("\n", KEY_ENTER), ("\t", KEY_TAB)]) +def test_the_two_allowed_control_characters_are_named_keys(us, character, code): + (action,) = us.resolve_text(character) + assert action.code == code + assert action.mask == 0 + + +def test_a_carriage_return_is_refused_rather_than_aliased_to_return(us): + """Only `\n` and `\t` are exempt from the C0 rule. + + A `\r` silently typed as Return means a caller who pasted CRLF gets two + newlines per line and no way to find out, so it is refused with the rest + of the C0 block. + """ + + with pytest.raises(keymaps.UnknownKey) as caught: + us.resolve_text("\r") + assert "scalar 0" in str(caught.value) + assert "U+000D" in str(caught.value) + + +def test_an_empty_string_is_no_actions_and_not_an_error(us): + assert us.resolve_text("") == [] + + +# -- refusals --------------------------------------------------------------- + + +@pytest.mark.parametrize("character", ["é", "ü", "😀", "\x01", "\x1b", "\x7f"]) +def test_a_character_this_layout_cannot_produce_is_refused(us, character): + with pytest.raises(keymaps.UnknownKey) as caught: + us.resolve_text(character) + message = str(caught.value) + # The index and the codepoint, and NOT the character: this message reaches + # the driver's log, and the string it came from is a password as often as + # not. + assert "scalar 0" in message + assert character not in message + + +def test_the_refusal_names_the_index_of_the_offending_scalar(us): + with pytest.raises(keymaps.UnknownKey) as caught: + us.resolve_text("abcé") + assert "scalar 3" in str(caught.value) + assert "é" not in str(caught.value) + + +def test_a_dead_keysym_is_refused_by_name(us): + with pytest.raises(keymaps.UnknownKey) as caught: + us.resolve_name("dead_acute") + assert "dead key" in str(caught.value) + + +def test_an_unknown_keysym_name_is_refused(us): + with pytest.raises(keymaps.UnknownKey): + us.resolve_name("NoSuchKeysymAtAll") + + +def test_an_empty_layout_is_refused_rather_than_compiled_as_us(): + """xkbcommon compiles `""` as the *same keymap as `us`*. + + So `--xkb-layout ''` would look configured, type `us`, and never say + otherwise -- the same class of silent-wrong-layout as the comma below. + """ + + with pytest.raises(keymaps.KeymapError) as caught: + keymaps.build(layout="") + assert "layout" in str(caught.value) + + +def test_a_comma_separated_layout_is_refused_before_anything_is_compiled(): + # xkbcommon accepts `us,ru` happily and hands back a two-group keymap. v1 + # always sends group 0, so the second group would be silently unreachable: + # a caller asking for Cyrillic would get Latin and no error. + with pytest.raises(keymaps.KeymapError) as caught: + keymaps.build(layout="us,ru") + assert "group" in str(caught.value) + + +def test_a_layout_xkbcommon_rejects_is_a_keymap_error_naming_it(): + with pytest.raises(keymaps.KeymapError) as caught: + keymaps.build(layout="zzz-no-such-layout") + assert "zzz-no-such-layout" in str(caught.value) + + +# -- the cap ---------------------------------------------------------------- + + +def test_the_cap_is_exactly_at_the_limit(us): + assert len(us.resolve_text("a" * keymaps.MAX_TEXT_SCALARS)) == keymaps.MAX_TEXT_SCALARS + + +def test_one_scalar_over_the_cap_is_refused(us): + with pytest.raises(keymaps.UnknownKey) as caught: + us.resolve_text("a" * (keymaps.MAX_TEXT_SCALARS + 1)) + assert str(keymaps.MAX_TEXT_SCALARS) in str(caught.value) + + +def test_the_cap_counts_scalars_and_not_bytes(us): + # 4096 astral-plane scalars are 16384 UTF-8 bytes. A byte cap would refuse + # this for being too long; the scalar cap lets it through to the character + # check, which refuses it for being unmappable instead. The distinction is + # the whole test: a byte cap and a scalar cap agree on ASCII, so only a + # non-ASCII case can tell them apart. + text = "😀" * keymaps.MAX_TEXT_SCALARS + assert len(text) == keymaps.MAX_TEXT_SCALARS + assert len(text.encode("utf-8")) > keymaps.MAX_TEXT_SCALARS + with pytest.raises(keymaps.UnknownKey) as caught: + us.resolve_text(text) + assert "scalar 0" in str(caught.value) + assert "limit" not in str(caught.value) + + +# -- the modifier set ------------------------------------------------------- + + +def test_the_modifier_set_is_measured_and_not_empty(us): + assert us.modifier_names() == keymaps.EXPECTED_MODIFIERS + + +def test_a_lock_is_not_a_modifier(us): + # Caps_Lock reports a *locked* mask, so `type` refuses while it is held + # rather than producing a case nobody asked for. + assert us.lock_names() == keymaps.EXPECTED_LOCKS + for name in keymaps.EXPECTED_LOCKS: + assert not us.is_modifier(name) + assert us.modifier_mask(name) == 0 + + +def test_control_contributes_the_bit_the_keymap_gives_control(us): + """The *right* bit, not merely a different one from Shift's. + + "not 0 and not Shift" is satisfied by Alt's bit, and every wire assertion + compares against `modifier_mask(...)` -- so a consistently wrong bit would + be consistently wrong and green. This asks the keymap for the index. + """ + + expected = 1 << us._keymap.mod_get_index("Control") + assert us.modifier_mask("Control_L") == expected + assert us.modifier_mask("Control_R") == expected + assert expected not in (0, shift_mask(us)) + + +# -- a second layout, which is what stops a Shift special case --------------- + + +def test_de_swaps_y_and_z_against_us(us, de): + assert (us.resolve_name("y").code, us.resolve_name("z").code) == (KEY_Y, KEY_Z) + # Same keysyms, other codes: a resolver with a table beside the keymap + # rather than inside it would return the us answer here. + assert (de.resolve_name("y").code, de.resolve_name("z").code) == (KEY_Z, KEY_Y) + + +def test_on_de_the_at_sign_needs_a_level_three_mask_not_shift(us, de): + at_us = us.resolve_text("@")[0] + at_de = de.resolve_text("@")[0] + assert at_us.mask == shift_mask(us) + # The case a Shift-only special case gets wrong: `@` is AltGr+q on de. + assert at_de.mask not in (0, shift_mask(de)) + assert at_de.mask == de.modifier_mask("ISO_Level3_Shift") + + +def test_a_character_us_cannot_type_is_ordinary_on_de(us, de): + with pytest.raises(keymaps.UnknownKey): + us.resolve_text("ü") + (action,) = de.resolve_text("ü") + assert action.name == "udiaeresis" + assert action.mask == 0 + + +# -- the keymap text we upload ---------------------------------------------- + + +def test_the_keymap_text_is_an_xkb_keymap_naming_its_layout(us, de): + assert us.text().lstrip().startswith("xkb_keymap {") + # The exact symbols names, not `"us" in ...` -- which is true of every + # us-family map and would stay true of a `de` keymap that had silently + # compiled as `us`. These are also the strings the VM check should grep, + # so they are written down once here. + assert 'xkb_symbols "pc_us_inet(evdev)"' in _symbols_line(us) + assert 'xkb_symbols "pc_de_inet(evdev)"' in _symbols_line(de) + + +def _symbols_line(keymap: keymaps.Keymap) -> str: + return next(line for line in keymap.text().splitlines() if "xkb_symbols" in line) + + +# -- through the dispatcher: nothing is emitted for a bad string ------------- + + +class _Sink: + """Just enough of :class:`hhstream_pointer.ops.PointerSink` to count calls.""" + + def __init__(self) -> None: + self.calls: list[tuple] = [] + + def has_keyboard(self) -> bool: + return True + + def key(self, code, state): + self.calls.append(("key", code, state)) + + def modifiers(self, depressed, latched, locked, group): + self.calls.append(("modifiers", depressed, latched, locked, group)) + + +def test_an_unmappable_character_emits_nothing_through_the_dispatcher(us): + sink = _Sink() + reply = Dispatcher(sink, us).handle({"op": "type", "text": "abcé"}) + assert reply["ok"] is False + # The assertion that matters: not "no event carried é" -- which would also + # pass if a, b and c had been typed -- but that the sink was never called. + assert sink.calls == [] + assert reply["kind"] == KIND_INVALID + + +def test_a_string_over_the_cap_emits_nothing_through_the_dispatcher(us): + sink = _Sink() + reply = Dispatcher(sink, us).handle( + {"op": "type", "text": "a" * (keymaps.MAX_TEXT_SCALARS + 1)} + ) + assert reply["ok"] is False + assert reply["kind"] == KIND_INVALID + assert sink.calls == [] + + +def test_the_keymap_object_is_built_once_and_reused_across_types(us): + """Two ``type``s, one keymap. + + The false pass this guards is a backend that recompiles and re-*uploads* + per string: a second ``keymap`` request replaces Hyprland's XKB state + without walking the keys it believes are down, so re-uploading under a held + modifier strands it. The dispatcher is handed one object and never asks for + another, which is what makes the single upload in ``__main__`` sufficient. + """ + + sink = _Sink() + dispatcher = Dispatcher(sink, us) + assert dispatcher.handle({"op": "type", "text": "a"})["ok"] is True + assert dispatcher.handle({"op": "type", "text": "b"})["ok"] is True + assert dispatcher._keymap is us diff --git a/tests/pointer/test_lease.py b/tests/pointer/test_lease.py index ccda2fe..8bc23ee 100644 --- a/tests/pointer/test_lease.py +++ b/tests/pointer/test_lease.py @@ -243,3 +243,102 @@ def test_a_new_lease_starts_without_the_previous_bookmark(lease): def test_defaults_match_the_contract(): lease = PointerLease() assert (lease.ttl_s, lease.max_s) == (30.0, 300.0) + + +# -- keys: the same mirror, and the same ordering rule ---------------------- +# +# PLAN §6.7 proposed a `keyboard` flag on the lease. These tests are the +# argument against it: a boolean cannot say to lift `Control_L` and not `a`, +# and it cannot say which went down first. + + +def test_press_and_lift_one_key(lease): + lease_id = lease.acquire("alpha") + lease.press_key("alpha", "Shift_L") + assert lease.keys_pressed() == ["Shift_L"] + assert lease.unpress_key("alpha", "Shift_L") == ["Shift_L"] + assert lease.keys_pressed() == [] + assert lease.release("alpha", lease_id, "done").keys_lifted == [] + + +def test_lifting_a_key_that_is_not_down_reports_nothing(lease): + lease.acquire("alpha") + assert lease.unpress_key("alpha", "Shift_L") == [] + lease.press_key("alpha", "Shift_L") + lease.unpress_key("alpha", "Shift_L") + assert lease.unpress_key("alpha", "Shift_L") == [] + + +def test_keys_are_kept_in_press_order(lease): + lease_id = lease.acquire("alpha") + for name in ("Control_L", "Shift_L", "a"): + lease.press_key("alpha", name) + assert lease.keys_pressed() == ["Control_L", "Shift_L", "a"] + + assert lease.unpress_key("alpha", "Shift_L") == ["Shift_L"] + assert lease.keys_pressed() == ["Control_L", "a"] + + outcome = lease.release("alpha", lease_id, "timeout") + assert outcome.keys_lifted == ["Control_L", "a"] + assert lease.keys_pressed() == [] + + +def test_pressing_a_key_twice_leaves_one_down(lease): + lease.acquire("alpha") + lease.press_key("alpha", "a") + lease.press_key("alpha", "a") + assert lease.keys_pressed() == ["a"] + + +def test_keys_and_buttons_are_tracked_separately(lease): + lease_id = lease.acquire("alpha") + lease.press("alpha", "left") + lease.press_key("alpha", "Shift_L") + assert (lease.pressed(), lease.keys_pressed()) == (["left"], ["Shift_L"]) + + outcome = lease.release("alpha", lease_id, "done") + assert (outcome.buttons_lifted, outcome.keys_lifted) == (["left"], ["Shift_L"]) + + +def test_a_non_holder_cannot_press_a_key(lease): + lease.acquire("alpha") + with pytest.raises(LeaseInvalid): + lease.press_key("beta", "a") + with pytest.raises(LeaseInvalid): + lease.unpress_key("beta", "a") + + +def test_expire_still_returns_no_key_list_so_the_broker_must_read_first(lease, clock): + """CONTRACT-sessions.md §3.3, unchanged by the keyboard. + + `expire()` is still `LeaseInfo` and carries neither buttons nor keys. 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 + widening the return would make that ordering optional. + """ + + lease.acquire("alpha") + lease.press_key("alpha", "Shift_L") + clock.advance(31.0) + + # The broker's order, and it is not interchangeable. + held = lease.keys_pressed() + info = lease.expire() + + assert held == ["Shift_L"] + assert info is not None + assert not hasattr(info, "keys_lifted") + assert not hasattr(info, "buttons_lifted") + assert lease.keys_pressed() == [] + + +def test_expiry_does_not_leak_keys_to_the_next_holder(lease, clock): + """A held Shift must not become the next session's Shift.""" + + lease.acquire("alpha") + lease.press_key("alpha", "Shift_L") + clock.advance(31.0) + assert lease.expire() is not None + + lease.acquire("beta") + assert lease.keys_pressed() == [] diff --git a/tests/pointer/test_ops.py b/tests/pointer/test_ops.py index 041609c..0a99b3a 100644 --- a/tests/pointer/test_ops.py +++ b/tests/pointer/test_ops.py @@ -13,17 +13,34 @@ from __future__ import annotations import pytest -from hhstream_pointer import buttons -from hhstream_pointer.ops import Dispatcher +from hhstream_pointer import buttons, keymap as keymaps +from hhstream_pointer.ops import KIND_INVALID, KIND_REFUSED, Dispatcher LEFT = buttons.CODES["left"] RIGHT = buttons.CODES["right"] DOWN = buttons.STATES["down"] UP = buttons.STATES["up"] +#: evdev codes, from ``linux/input-event-codes.h``. Asserted as the integers +#: the wire carries, never as XKB codes: ``a`` is 30 there and 38 in xkbcommon's +#: tables, and only one of the two ever leaves this process. +KEY_A = 30 +KEY_B = 48 +KEY_ENTER = 28 +KEY_LEFTSHIFT = 42 +KEY_LEFTCTRL = 29 + class RecordingSink: - """Every call, in order, as a tuple. Nothing else.""" + """Every call, in order, as a tuple. Nothing else. + + ``has_keyboard`` answers True by default because most tests want one. The + keyboard calls carry **no output**: a virtual keyboard is seat-global, and + a sink that tagged them with one would be hiding the fact that a key after + a warp to another output still goes to whatever has focus. + """ + + keyboard = True def __init__(self) -> None: self.calls: list[tuple] = [] @@ -40,6 +57,31 @@ class RecordingSink: def frame(self, output): self.calls.append(("frame", output)) + def has_keyboard(self): + return self.keyboard + + def key(self, code, state): + self.calls.append(("key", code, state)) + + def modifiers(self, depressed, latched, locked, group): + self.calls.append(("modifiers", depressed, latched, locked, group)) + + +class KeyboardlessSink(RecordingSink): + """A compositor with no ``zwp_virtual_keyboard_manager_v1``. + + Not a failing sink: the methods are simply never meant to be reached, and + a call that got through would be the bug. + """ + + keyboard = False + + def key(self, code, state): + raise AssertionError("no virtual keyboard exists; key must not be sent") + + def modifiers(self, depressed, latched, locked, group): + raise AssertionError("no virtual keyboard exists; modifiers must not be sent") + class FailingSink(RecordingSink): """A sink whose motion raises, standing in for an output that vanished.""" @@ -56,9 +98,21 @@ def sink() -> RecordingSink: return RecordingSink() +@pytest.fixture(scope="module") +def us() -> keymaps.Keymap: + """A real ``us`` keymap. + + Real, not a fake, for the reason ``test_keymap.py`` gives at length: the + mask for ``A`` and the refusal of ``é`` are properties of the layout, and a + fake that agreed with the dispatcher would prove only that they agree. + """ + + return keymaps.build(layout="us") + + @pytest.fixture -def driver(sink) -> Dispatcher: - return Dispatcher(sink) +def driver(sink, us) -> Dispatcher: + return Dispatcher(sink, us) def warp(driver, output="hh-alpha", x=0.5, y=0.5): @@ -90,7 +144,7 @@ def test_a_click_is_warp_button_frame(driver, sink): ("button", "hh-alpha", LEFT, UP), ("frame", "hh-alpha"), ] - assert driver.handle({"op": "pressed"}) == {"ok": True, "buttons": []} + assert driver.handle({"op": "pressed"}) == {"ok": True, "buttons": [], "keys": []} def test_the_boundary_coordinates_are_accepted(driver, sink): @@ -160,7 +214,11 @@ def test_pressed_reports_what_is_down_oldest_first(driver): warp(driver) driver.handle({"op": "button", "button": "right", "state": "down"}) driver.handle({"op": "button", "button": "left", "state": "down"}) - assert driver.handle({"op": "pressed"}) == {"ok": True, "buttons": ["right", "left"]} + assert driver.handle({"op": "pressed"}) == { + "ok": True, + "buttons": ["right", "left"], + "keys": [], + } def test_release_all_lifts_everything_and_frames_once(driver, sink): @@ -169,17 +227,28 @@ def test_release_all_lifts_everything_and_frames_once(driver, sink): driver.handle({"op": "button", "button": "right", "state": "down"}) sink.calls.clear() - assert driver.handle({"op": "release_all"}) == {"ok": True, "lifted": ["left", "right"]} + assert driver.handle({"op": "release_all"}) == { + "ok": True, + "lifted": ["left", "right"], + "lifted_keys": [], + } assert sink.calls == [ ("button", "hh-alpha", LEFT, UP), ("button", "hh-alpha", RIGHT, UP), ("frame", "hh-alpha"), ] - assert driver.handle({"op": "pressed"}) == {"ok": True, "buttons": []} + assert driver.handle({"op": "pressed"}) == {"ok": True, "buttons": [], "keys": []} def test_release_all_on_a_quiet_driver_lifts_nothing(driver, sink): - assert driver.handle({"op": "release_all"}) == {"ok": True, "lifted": []} + assert driver.handle({"op": "release_all"}) == { + "ok": True, + "lifted": [], + "lifted_keys": [], + } + # Including no zeroed `modifiers`: a mask nothing ever set is not ours to + # clear, and on a sink with no keyboard at all sending one would raise and + # abandon the button lifting above. assert sink.calls == [] @@ -196,7 +265,11 @@ def test_release_all_lifts_through_the_pointer_the_press_went_to(driver, sink): driver.handle({"op": "button", "button": "right", "state": "down"}) sink.calls.clear() - assert driver.handle({"op": "release_all"}) == {"ok": True, "lifted": ["left", "right"]} + assert driver.handle({"op": "release_all"}) == { + "ok": True, + "lifted": ["left", "right"], + "lifted_keys": [], + } assert sink.calls == [ ("button", "hh-alpha", LEFT, UP), ("button", "hh-beta", RIGHT, UP), @@ -209,7 +282,11 @@ def test_a_lifted_button_is_forgotten(driver): warp(driver) driver.handle({"op": "button", "button": "left", "state": "down"}) driver.handle({"op": "button", "button": "left", "state": "up"}) - assert driver.handle({"op": "release_all"}) == {"ok": True, "lifted": []} + assert driver.handle({"op": "release_all"}) == { + "ok": True, + "lifted": [], + "lifted_keys": [], + } def test_every_known_button_name_round_trips(driver, sink): @@ -227,6 +304,10 @@ def test_button_before_any_warp_is_refused(driver, sink): assert driver.handle({"op": "button", "button": "left", "state": "down"}) == { "ok": False, "error": "no output is aimed; warp before button or frame", + # `refused` and not `invalid_argument`: the request was well formed, + # what is missing is a warp, and the broker reports that as exit 10 + # exactly as it already does for an unknown button. + "kind": "refused", } assert sink.calls == [] @@ -277,8 +358,8 @@ def test_a_failed_warp_does_not_change_the_aim(): ({"op": "axis", "value": -1e9}, "wheel-click limit"), ], ) -def test_malformed_requests_are_answered_not_fatal(sink, request_, fragment): - driver = Dispatcher(sink) +def test_malformed_requests_are_answered_not_fatal(sink, us, request_, fragment): + driver = Dispatcher(sink, us) # Aim first, so a refusal is about the field under test rather than the aim. warp(driver) sink.calls.clear() @@ -300,9 +381,11 @@ def test_the_contracts_ops_are_exactly_what_is_implemented() -> None: An op that exists here and nowhere in the contract -- or the reverse -- fails this test rather than surprising whoever reads the contract next. - ``axis`` is the one addition since the freeze, made deliberately so that a - session can scroll; the set is edited by hand, which is the reminder to - write it down. + ``axis`` was the first addition since the freeze, so a session could + scroll; ``key`` and ``type`` are the second, and there is deliberately no + keyboard ``frame`` or ``release_all_keys`` beside them -- the protocol has + no frame, and expiry has exactly one call site. The set is edited by hand, + which is the reminder to write it down. """ assert set(Dispatcher._ops) == { @@ -310,6 +393,461 @@ def test_the_contracts_ops_are_exactly_what_is_implemented() -> None: "button", "axis", "frame", + "key", + "type", "pressed", "release_all", } + + +# -- key: one keysym at a time ---------------------------------------------- +# +# Names on this socket, evdev codes on the Wayland request -- the same division +# `buttons.py` draws, and the reason `pressed` answers "Control_L" rather than +# 29. These tests assert both halves: the response names, the sink codes. + + +def test_key_down_sends_the_code_and_lists_the_name(driver, sink): + assert driver.handle({"op": "key", "key": "Return", "state": "down"}) == { + "ok": True, + "keys": ["Return"], + "lifted": [], + } + assert sink.calls == [("key", KEY_ENTER, DOWN)] + assert driver.handle({"op": "pressed"})["keys"] == ["Return"] + + +def test_key_needs_no_warp(sink, us): + """A keyboard has no output, so `type` must not demand an aim. + + Deliberately the one test in this file that never warps: a virtual keyboard + is seat-global, so requiring a warp first would refuse a caller who only + ever wanted to type -- and every other test here warps out of habit, which + is exactly how that bug would survive. + """ + + driver = Dispatcher(sink, us) + assert driver.handle({"op": "type", "text": "Hi"})["ok"] is True + assert driver.handle({"op": "key", "key": "a", "state": "down"})["ok"] is True + assert ("key", KEY_A, DOWN) in sink.calls + + +def test_a_key_is_not_tagged_with_an_output_even_after_a_warp(driver, sink): + warp(driver, output="hh-beta") + sink.calls.clear() + driver.handle({"op": "key", "key": "a", "state": "down"}) + # Two items, not three: no output travels with a key. A sink that accepted + # one would let a future change route keys per output, which the protocol + # cannot do. + assert sink.calls == [("key", KEY_A, DOWN)] + + +def test_key_up_forgets_the_key(driver, sink): + driver.handle({"op": "key", "key": "a", "state": "down"}) + assert driver.handle({"op": "key", "key": "a", "state": "up"}) == { + "ok": True, + "keys": [], + "lifted": ["a"], + } + assert sink.calls == [("key", KEY_A, DOWN), ("key", KEY_A, UP)] + + +def test_up_of_a_key_that_was_never_down_lifts_nothing_and_emits_nothing(driver, sink): + """Same rule as `unpress` for a button that was never pressed. + + Reported rather than invented, and silent on the wire: a key-up the + compositor has no matching key-down for puts its own `m_pressed` out of + step with ours, and on this build that makes the *next* press of the code + a no-op. + """ + + assert driver.handle({"op": "key", "key": "a", "state": "up"}) == { + "ok": True, + "keys": [], + "lifted": [], + } + assert sink.calls == [] + + +def test_keys_are_reported_oldest_first(driver): + for name in ("Control_L", "Shift_L", "a"): + driver.handle({"op": "key", "key": name, "state": "down"}) + assert driver.handle({"op": "pressed"})["keys"] == ["Control_L", "Shift_L", "a"] + + +# -- the modifier half, which a key-up does not undo ------------------------ + + +def test_a_modifier_down_sends_the_key_and_the_mask(driver, sink, us): + driver.handle({"op": "key", "key": "Shift_L", "state": "down"}) + assert sink.calls == [ + ("key", KEY_LEFTSHIFT, DOWN), + ("modifiers", us.modifier_mask("Shift_L"), 0, 0, 0), + ] + + +def test_a_modifier_up_restores_the_mask_of_whatever_is_still_held(driver, sink, us): + driver.handle({"op": "key", "key": "Shift_L", "state": "down"}) + driver.handle({"op": "key", "key": "Control_L", "state": "down"}) + sink.calls.clear() + + driver.handle({"op": "key", "key": "Shift_L", "state": "up"}) + + # Not zero: Control is still down, so the mask drops to Control's bit + # alone. A key-up changes no modifier state on this compositor, so the + # mask is only ever what we last said it was. + assert sink.calls == [ + ("key", KEY_LEFTSHIFT, UP), + ("modifiers", us.modifier_mask("Control_L"), 0, 0, 0), + ] + + +def test_an_ordinary_key_down_sends_no_mask(driver, sink): + driver.handle({"op": "key", "key": "a", "state": "down"}) + assert sink.calls == [("key", KEY_A, DOWN)] + + +def test_key_of_a_capital_sends_the_mask_the_symbol_needs(driver, sink, us): + """`keyboard key A` must type `A`, not `a`. + + The bug this locks: `key` resolved the action and then used only its + `code`, so a keysym above level 0 went on the wire as a bare keypress and + the window received the level-0 character. `A` typed `a`; on `de`, `at` + lost its level-three mask and typed `q`. `type` was the only path that used + the mask, so every `type` test stayed green. + """ + + assert driver.handle({"op": "key", "key": "A", "state": "down"})["keys"] == ["A"] + assert sink.calls == [ + # Mask first, exactly as `type` does it: a client that decodes with the + # mask from the last `wl_keyboard.modifiers` emits `a` otherwise. + ("modifiers", us.modifier_mask("Shift_L"), 0, 0, 0), + ("key", KEY_A, DOWN), + ] + # And still no Shift keycode. + assert not any(c[0] == "key" and c[1] == KEY_LEFTSHIFT for c in sink.calls) + + +def test_the_up_of_a_capital_restores_the_baseline(driver, sink, us): + driver.handle({"op": "key", "key": "A", "state": "down"}) + sink.calls.clear() + + driver.handle({"op": "key", "key": "A", "state": "up"}) + + assert sink.calls == [("key", KEY_A, UP), ("modifiers", 0, 0, 0, 0)] + assert driver.handle({"op": "pressed"})["keys"] == [] + + +def test_a_capital_is_not_treated_as_a_held_modifier(driver, sink): + """`A` held is a held *letter*, so `type` must refuse under it. + + The distinction is why the held record stores what a key *contributes* + rather than what it needs: storing `A`'s Shift requirement there would make + a held capital look like a held modifier, and `type` would carry on and OR + a Shift it did not ask for into every character. + """ + + driver.handle({"op": "key", "key": "A", "state": "down"}) + sink.calls.clear() + + reply = driver.handle({"op": "type", "text": "b"}) + + assert reply["ok"] is False + assert reply["kind"] == KIND_INVALID + assert sink.calls == [] + + +def test_two_names_for_one_keycode_cannot_both_be_held(driver, sink): + """`A` and `a` are the same keycode at two levels. + + Holding both sent `key(30, pressed)` twice. Hyprland drops the second + because the code is already in its `m_pressed`, then `release_all` sends + two ups of which one is also dropped -- so nothing visibly breaks and the + held set is a lie for as long as the lease lasts. A refusal is better. + """ + + driver.handle({"op": "key", "key": "A", "state": "down"}) + sink.calls.clear() + + reply = driver.handle({"op": "key", "key": "a", "state": "down"}) + + assert reply["ok"] is False + assert reply["kind"] == KIND_INVALID + assert "same key" in reply["error"] + assert sink.calls == [] + assert driver.handle({"op": "pressed"})["keys"] == ["A"] + + +def test_the_same_name_down_twice_is_still_one_key(driver): + """Not a clash with itself: a repeated `down` is idempotent, as for buttons.""" + + driver.handle({"op": "key", "key": "a", "state": "down"}) + assert driver.handle({"op": "key", "key": "a", "state": "down"})["ok"] is True + assert driver.handle({"op": "pressed"})["keys"] == ["a"] + + +def test_a_key_is_only_forgotten_after_the_up_reaches_the_sink(us): + """Order matters here for the same reason it does for `button`. + + If the name were dropped before the send, a raise from the sink would leave + us believing the key is up while the compositor still has it down -- and + `release_all` would not try again, because the set is empty. + """ + + class _Breaking(RecordingSink): + def key(self, code, state): + if state == UP: + raise RuntimeError("the keyboard went away") + super().key(code, state) + + driver = Dispatcher(_Breaking(), us) + driver.handle({"op": "key", "key": "Shift_L", "state": "down"}) + + with pytest.raises(RuntimeError): + driver.handle({"op": "key", "key": "Shift_L", "state": "up"}) + + # Still held, so the next `release_all` will try the up again. + assert driver.handle({"op": "pressed"})["keys"] == ["Shift_L"] + + +# -- type ------------------------------------------------------------------- + + +def test_type_of_a_capital_is_the_mask_and_not_a_shift_keycode(driver, sink, us): + assert driver.handle({"op": "type", "text": "A"}) == {"ok": True, "keys": []} + shift = us.modifier_mask("Shift_L") + assert sink.calls == [ + # The mask goes FIRST. A client that decodes with the mask from the + # last `wl_keyboard.modifiers` -- foot, GTK -- emits `a` if the key + # arrives before the mask. + ("modifiers", shift, 0, 0, 0), + ("key", KEY_A, DOWN), + ("key", KEY_A, UP), + ("modifiers", 0, 0, 0, 0), + ] + # And no synthetic Shift key anywhere: sending both a mask and KEY_LEFTSHIFT + # is how a toolkit applies Shift twice, or not at all. + assert not any(call[0] == "key" and call[1] == KEY_LEFTSHIFT for call in sink.calls) + + +def test_type_leaves_no_key_held(driver): + driver.handle({"op": "type", "text": "Hello"}) + assert driver.handle({"op": "pressed"})["keys"] == [] + + +def test_type_emits_a_down_up_pair_per_character(driver, sink): + driver.handle({"op": "type", "text": "ab"}) + assert [c for c in sink.calls if c[0] == "key"] == [ + ("key", KEY_A, DOWN), + ("key", KEY_A, UP), + ("key", KEY_B, DOWN), + ("key", KEY_B, UP), + ] + + +def test_type_of_an_empty_string_emits_nothing_and_succeeds(driver, sink): + assert driver.handle({"op": "type", "text": ""}) == {"ok": True, "keys": []} + assert sink.calls == [] + + +def test_type_ors_an_explicitly_held_modifier_and_leaves_it_down(driver, sink, us): + """`down Control_L` then `type c` is Ctrl+C, and Control is still down.""" + + driver.handle({"op": "key", "key": "Control_L", "state": "down"}) + sink.calls.clear() + + assert driver.handle({"op": "type", "text": "c"}) == {"ok": True, "keys": ["Control_L"]} + + control = us.modifier_mask("Control_L") + assert sink.calls == [ + ("modifiers", control, 0, 0, 0), + ("key", us.resolve_name("c").code, DOWN), + ("key", us.resolve_name("c").code, UP), + # Back to the BASELINE, not to zero: Control was not ours to lift. + ("modifiers", control, 0, 0, 0), + ] + assert not any(call[0] == "key" and call[1] == KEY_LEFTCTRL for call in sink.calls) + assert driver.handle({"op": "pressed"})["keys"] == ["Control_L"] + + +def test_type_of_a_capital_under_a_held_control_ors_both_masks(driver, sink, us): + driver.handle({"op": "key", "key": "Control_L", "state": "down"}) + sink.calls.clear() + + driver.handle({"op": "type", "text": "A"}) + + both = us.modifier_mask("Control_L") | us.modifier_mask("Shift_L") + # The whole sequence, not just the two masks: `modifiers(both)` followed by + # `modifiers(control)` with no key events in between would satisfy a + # first-and-last assertion while typing nothing at all. + assert sink.calls == [ + ("modifiers", both, 0, 0, 0), + ("key", KEY_A, DOWN), + ("key", KEY_A, UP), + ("modifiers", us.modifier_mask("Control_L"), 0, 0, 0), + ] + # And no second Control down, and no Shift keycode. + assert not any(c[0] == "key" and c[1] in (KEY_LEFTCTRL, KEY_LEFTSHIFT) for c in sink.calls) + + +def test_type_while_a_non_modifier_is_held_emits_nothing(driver, sink): + driver.handle({"op": "key", "key": "a", "state": "down"}) + sink.calls.clear() + + reply = driver.handle({"op": "type", "text": "bc"}) + + assert reply["ok"] is False + assert reply["kind"] == KIND_INVALID + assert sink.calls == [] + # And the held key is untouched: a refused request changes nothing. + assert driver.handle({"op": "pressed"})["keys"] == ["a"] + + +def test_type_while_a_lock_is_held_is_refused_too(driver, sink): + """Caps_Lock reports a *locked* mask, so it is not a modifier. + + Typing under it would produce a case the caller did not ask for, and v1 + refuses rather than guessing which one they meant. + """ + + driver.handle({"op": "key", "key": "Caps_Lock", "state": "down"}) + sink.calls.clear() + + reply = driver.handle({"op": "type", "text": "a"}) + assert reply["ok"] is False + # The caller's mistake, so exit 2 -- not `refused`, which would report a + # held Caps_Lock as a compositor failure. + assert reply["kind"] == KIND_INVALID + assert sink.calls == [] + + +def test_a_string_that_fails_on_its_third_character_emits_nothing(driver, sink): + reply = driver.handle({"op": "type", "text": "abé"}) + assert reply["ok"] is False + assert reply["kind"] == KIND_INVALID + # Not "no event carried é" -- that would also pass with a and b typed. + assert sink.calls == [] + + +def test_a_bad_character_is_a_usage_error_and_a_missing_keyboard_is_not(sink, us): + """The two refusals the broker must tell apart (the review's change 1). + + An unmappable character is the caller's; a compositor with no keyboard + global is not. They become exit 2 and exit 10, and the only thing carrying + the difference across the socket is this token. + """ + + usable = Dispatcher(sink, us) + assert usable.handle({"op": "type", "text": "é"})["kind"] == KIND_INVALID + assert usable.handle({"op": "key", "key": "Nope", "state": "down"})["kind"] == KIND_INVALID + assert usable.handle({"op": "key", "key": "a", "state": "sideways"})["kind"] == KIND_INVALID + + absent = Dispatcher(KeyboardlessSink(), us) + assert absent.handle({"op": "type", "text": "a"})["kind"] == KIND_REFUSED + assert absent.handle({"op": "key", "key": "a", "state": "down"})["kind"] == KIND_REFUSED + + +def test_without_a_keymap_at_all_the_keyboard_ops_refuse_and_the_cursor_works(sink): + """A driver started with no layout still moves the cursor.""" + + driver = Dispatcher(sink, None) + assert warp(driver)["ok"] is True + assert driver.handle({"op": "button", "button": "left", "state": "down"})["ok"] is True + reply = driver.handle({"op": "type", "text": "a"}) + assert reply["ok"] is False and reply["kind"] == KIND_REFUSED + + +# -- release_all, with keys ------------------------------------------------ + + +def test_release_all_lifts_keys_in_press_order_then_zeroes_the_mask(driver, sink): + driver.handle({"op": "key", "key": "Control_L", "state": "down"}) + driver.handle({"op": "key", "key": "a", "state": "down"}) + sink.calls.clear() + + assert driver.handle({"op": "release_all"}) == { + "ok": True, + "lifted": [], + "lifted_keys": ["Control_L", "a"], + } + assert sink.calls == [ + ("key", KEY_LEFTCTRL, UP), + ("key", KEY_A, UP), + # The part that is easy to leave out. A virtual key-up clears no + # modifier state, so without this the next holder gets a keyboard + # where every letter is a capital. + ("modifiers", 0, 0, 0, 0), + ] + assert driver.handle({"op": "pressed"})["keys"] == [] + + +def test_release_all_lifts_keys_after_buttons_and_adds_no_keyboard_frame(driver, sink): + warp(driver) + driver.handle({"op": "button", "button": "left", "state": "down"}) + driver.handle({"op": "key", "key": "Shift_L", "state": "down"}) + sink.calls.clear() + + driver.handle({"op": "release_all"}) + + assert sink.calls == [ + ("button", "hh-alpha", LEFT, UP), + ("frame", "hh-alpha"), + ("key", KEY_LEFTSHIFT, UP), + ("modifiers", 0, 0, 0, 0), + ] + # Exactly one frame, for the pointer. `zwp_virtual_keyboard_v1` has none, + # and a key that waited for one would never arrive. + assert sum(1 for call in sink.calls if call[0] == "frame") == 1 + + +def test_release_all_lifts_keys_even_after_a_warp_to_another_output(driver, sink): + """Keys are not per output, and this is the test that says so. + + The button path has to lift through the pointer the press went to; the key + path has nothing to choose, and a sink that silently ignored an output + argument would make a per-output implementation look correct here. + """ + + warp(driver, output="hh-alpha") + driver.handle({"op": "key", "key": "a", "state": "down"}) + warp(driver, output="hh-beta") + sink.calls.clear() + + assert driver.handle({"op": "release_all"})["lifted_keys"] == ["a"] + assert sink.calls == [("key", KEY_A, UP)] + + +def test_release_all_without_a_keyboard_still_lifts_buttons(us): + """The review's change 3, and the reason the mask is conditional. + + `SessionManager._expire_pointer` calls `release_all` exactly once, so an + exception from the key half would abandon the buttons -- and a lease that + expired with a mouse button down is the failure the whole TTL exists to + prevent. + """ + + sink = KeyboardlessSink() + driver = Dispatcher(sink, us) + warp(driver) + driver.handle({"op": "button", "button": "left", "state": "down"}) + sink.calls.clear() + + assert driver.handle({"op": "release_all"}) == { + "ok": True, + "lifted": ["left"], + "lifted_keys": [], + } + assert sink.calls == [("button", "hh-alpha", LEFT, UP), ("frame", "hh-alpha")] + + +def test_release_all_after_a_type_zeroes_the_mask_once_more(driver, sink): + """A `type` restored the baseline itself, and `release_all` still zeroes. + + Cheap, and it is the crash-mid-string case: the mask the last character set + is the compositor's until something says otherwise. + """ + + driver.handle({"op": "type", "text": "A"}) + sink.calls.clear() + driver.handle({"op": "release_all"}) + assert sink.calls == [("modifiers", 0, 0, 0, 0)] diff --git a/tests/pointer/test_pointer_server.py b/tests/pointer/test_pointer_server.py index 767b095..a518e31 100644 --- a/tests/pointer/test_pointer_server.py +++ b/tests/pointer/test_pointer_server.py @@ -78,7 +78,7 @@ class _Client: def test_one_request_gets_one_response(connection): client, _ = connection - assert client.call({"op": "pressed"}) == {"ok": True, "buttons": []} + assert client.call({"op": "pressed"}) == {"ok": True, "buttons": [], "keys": []} def test_many_requests_share_one_connection(connection): @@ -86,8 +86,16 @@ def test_many_requests_share_one_connection(connection): assert client.call({"op": "warp", "output": "hh-a", "x": 0.5, "y": 0.5}) == {"ok": True} assert client.call({"op": "button", "button": "left", "state": "down"}) == {"ok": True} assert client.call({"op": "frame"}) == {"ok": True} - assert client.call({"op": "pressed"}) == {"ok": True, "buttons": ["left"]} - assert client.call({"op": "release_all"}) == {"ok": True, "lifted": ["left"]} + assert client.call({"op": "pressed"}) == { + "ok": True, + "buttons": ["left"], + "keys": [], + } + assert client.call({"op": "release_all"}) == { + "ok": True, + "lifted": ["left"], + "lifted_keys": [], + } assert [c[0] for c in sink.calls] == ["motion", "button", "frame", "button", "frame"] diff --git a/tests/pointer/test_vendored_protocol.py b/tests/pointer/test_vendored_protocol.py index 5d4c143..a3abd11 100644 --- a/tests/pointer/test_vendored_protocol.py +++ b/tests/pointer/test_vendored_protocol.py @@ -29,6 +29,9 @@ assert _spec is not None and _spec.origin, "hhstream_pointer is not importable" PACKAGE = Path(_spec.origin).parent PROTOCOL_DIR = PACKAGE / "_protocol/wlr_virtual_pointer_unstable_v1" MANAGER = PROTOCOL_DIR / "zwlr_virtual_pointer_manager_v1.py" +KEYBOARD_DIR = PACKAGE / "_protocol/virtual_keyboard_unstable_v1" +KEYBOARD_MANAGER = KEYBOARD_DIR / "zwp_virtual_keyboard_manager_v1.py" +KEYBOARD = KEYBOARD_DIR / "zwp_virtual_keyboard_v1.py" #: Only present in a checkout; a build sandbox gets the test directory alone. PYPROJECT = Path(__file__).resolve().parents[2] / "pyproject.toml" @@ -57,10 +60,81 @@ def test_the_shim_resolves_the_generated_relative_import(): @pytest.mark.skipif(not PYPROJECT.is_file(), reason="not running from a checkout") -def test_pyproject_declares_the_entry_point_and_the_dependency(): +def test_pyproject_declares_the_entry_point_and_the_dependencies(): pyproject = PYPROJECT.read_text() assert 'hhstream-pointer = "hhstream_pointer.__main__:main"' in pyproject assert "pywayland" in pyproject + # Not optional, and the comment beside it in pyproject.toml says why: an + # optional xkbcommon would let test_keymap.py skip, and the + # unmappable-character path is the one that must not rot. + assert "xkbcommon" in pyproject + + +# -- the virtual keyboard -------------------------------------------------- + + +def test_the_keyboard_protocol_is_vendored_beside_the_pointer_one(): + assert (KEYBOARD_DIR / "__init__.py").is_file() + assert KEYBOARD_MANAGER.is_file() + assert KEYBOARD.is_file() + for path in KEYBOARD_DIR.glob("*.py"): + assert path.read_text().startswith("# This file has been autogenerated") + + +def test_the_keyboard_manager_is_version_1_with_the_seat_only_request(): + source = KEYBOARD_MANAGER.read_text() + assert 'name = "zwp_virtual_keyboard_manager_v1"' in source + assert " version = 1" in source + # Seat and nothing else: a virtual keyboard has no output argument, which + # is why `ops.py` must not route a key through `_aimed()`. + assert "def create_virtual_keyboard(self, seat: WlSeat)" in source + assert "WlOutput" not in source + + +def test_the_keyboard_carries_keymap_key_and_modifiers(): + source = KEYBOARD.read_text() + assert 'name = "zwp_virtual_keyboard_v1"' in source + assert " version = 1" in source + assert "def keymap(self, format: int, fd: int, size: int)" in source + assert "def key(self, time: int, key: int, state: int)" in source + assert ( + "def modifiers(self, mods_depressed: int, mods_latched: int, " + "mods_locked: int, group: int)" in source + ) + # The keymap fd really is an fd on the wire, not a number we invented. + assert "ArgumentType.FileDescriptor" in source + # No frame, and there is nothing to add one from: `ops.py` says why a key + # queued until one would never arrive. + assert "def frame(" not in source + + +def test_the_integers_the_xml_names_but_does_not_define_live_in_our_code(): + """The one real cost of using Hyprland's copy of the XML. + + It names `keymap_format` and `key_state` in the request descriptions and + defines neither enum, so the scanner emits no `IntEnum` for either. Both + are therefore written down with a citation, and this test is what notices + if a future regeneration against a *complete* XML makes them redundant -- + at which point they should be deleted rather than left to drift. + """ + + source = KEYBOARD.read_text() + assert "keymap_format" in source, "the description still refers to it" + assert "class keymap_format" not in source, "...and still does not define it" + assert "class key_state" not in source + + from hhstream_pointer import buttons + from hhstream_pointer.keymap import XKB_V1 + + assert XKB_V1 == 1 + # `wl_pointer.button_state` and `wl_keyboard.key_state` agree on these two, + # which is why there is one table rather than a second that can drift. + assert buttons.STATES["up"] == 0 + assert buttons.STATES["down"] == 1 + + +def test_the_shim_resolves_the_keyboard_relative_import(): + assert "from ..wayland import WlSeat" in KEYBOARD_MANAGER.read_text() @pytest.mark.skipif( @@ -80,6 +154,39 @@ def test_the_protocol_binds_against_the_installed_pywayland(): ) +@pytest.mark.skipif( + not HAVE_PYWAYLAND, + reason="pywayland is not in this environment (it is in the built package)", +) +def test_the_keyboard_protocol_binds_against_the_installed_pywayland(): + from hhstream_pointer._protocol.virtual_keyboard_unstable_v1 import ( + ZwpVirtualKeyboardManagerV1, + ZwpVirtualKeyboardV1, + ) + + assert ZwpVirtualKeyboardManagerV1.name == "zwp_virtual_keyboard_manager_v1" + assert ZwpVirtualKeyboardManagerV1.version == 1 + assert ZwpVirtualKeyboardV1.version == 1 + for request in ("keymap", "key", "modifiers", "destroy"): + assert hasattr(ZwpVirtualKeyboardV1.proxy_class, request) + assert hasattr(ZwpVirtualKeyboardManagerV1.proxy_class, "create_virtual_keyboard") + + +@pytest.mark.skipif( + not HAVE_PYWAYLAND, + reason="pywayland is not in this environment (it is in the built package)", +) +def test_the_backend_binds_the_keyboard_manager_at_version_1_and_survives_its_absence(): + from hhstream_pointer.backend import KEYBOARD_MANAGER_VERSION, WaylandSink + + assert KEYBOARD_MANAGER_VERSION == 1 + # A sink that never connected has no keyboard and says so rather than + # raising: `ops.release_all` asks this question precisely so that a + # compositor with no keyboard global still gets its buttons lifted. + sink = WaylandSink(Path("/nonexistent")) + assert sink.has_keyboard() is False + + @pytest.mark.skipif( not HAVE_PYWAYLAND, reason="pywayland is not in this environment (it is in the built package)", diff --git a/tests/sessions/fakes.py b/tests/sessions/fakes.py index fcbea53..9219999 100644 --- a/tests/sessions/fakes.py +++ b/tests/sessions/fakes.py @@ -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] = [] diff --git a/tests/sessions/integration/test_containers.py b/tests/sessions/integration/test_containers.py index 4ebd79f..b7eb962 100644 --- a/tests/sessions/integration/test_containers.py +++ b/tests/sessions/integration/test_containers.py @@ -450,6 +450,11 @@ def test_a_whole_gesture_runs_through_the_broker_and_the_driver(rig: Rig): assert released["buttons_lifted"] == [] assert rig.driver.sink.calls == [ + # Acquire is TWO warps: one warp onto an idle cursor moves the cursor + # and not keyboard focus, so acquire nudges to a neighbouring pixel and + # then lands on the target. The second one is the bookmark. + ("warp", output, 0.5, 0.504), + ("frame", output), ("warp", output, 0.5, 0.5), ("frame", output), ("warp", output, 0.25, 0.75), @@ -512,14 +517,42 @@ def test_a_button_left_down_is_lifted_when_the_lease_is_released(rig: Rig): def test_killing_a_session_that_holds_the_cursor_gives_it_back(rig: Rig): + """Through `kill`, with a button AND a key down. + + The key half is here rather than in a unit test on purpose. The unit test + calls `_drop_lease_for` directly, so it proves that helper lifts keys and + says nothing about whether `kill` still calls it -- removing the call would + leave that test green. This goes through the verb, and it asserts on the + SINK rather than on `pointer.state`: the lease forgetting a key is not the + same as the compositor being told it came up, and only the second one + matters to the application. + """ + first = start(rig.daemon, "sleeper") second = start(rig.daemon, "sleeper") lease = rig.daemon.call("pointer.acquire", id=first)["lease_id"] rig.daemon.call("pointer.button", id=first, lease_id=lease, button="right", state="down") + held = rig.daemon.call( + "keyboard.key", id=first, lease_id=lease, key="Shift_L", state="down" + ) + assert held["keys"] == ["Shift_L"], held + rig.driver.sink.calls.clear() rig.daemon.call("kill", id=first, grace_s=0) + # KEY_LEFTSHIFT, and `state=0`. Shift is the key to use because `type` + # never emits code 42, so a release of it cannot be a leftover from + # anything else this rig did. + assert ("key", 42, 0) in rig.driver.sink.calls, ( + f"kill did not lift the held key: {rig.driver.sink.calls}. On this " + "compositor a code left in the seat's m_pressed makes the NEXT press " + "of it a no-op, so the key is dead rather than merely stuck." + ) + # And the mask with it: a virtual key-up clears no modifier state, so + # without this the next holder inherits Shift. + assert ("modifiers", 0, 0, 0, 0) in rig.driver.sink.calls, rig.driver.sink.calls assert rig.driver.dispatcher._pressed == {} + assert rig.driver.dispatcher._keys == {} assert rig.daemon.call("pointer.state")["holder"] is None assert rig.daemon.call("pointer.acquire", id=second)["ok"] @@ -556,6 +589,81 @@ def test_a_retried_click_with_the_same_request_id_clicks_once(rig: Rig): assert len(rig.driver.sink.of("button")) == 2, "one press and one release, not two" +def test_a_retried_type_with_the_same_request_id_types_once(rig: Rig): + """A retried `type` is the keyboard's version of a second click. + + Asserted on the SINK and not on the `deduplicated` flag, because the flag + alone is the false pass the verification doc names: a handler that typed + the string and *then* set the flag would satisfy it. The thing that must + not happen twice is the key events, so those are what is counted. + + The cache is not keyboard-specific -- `_dispatch` looks the `request_id` up + before the handler and remembers it after, keyed on the id alone -- so what + this locks is that `keyboard.type` is in the mutating set and therefore + reaches that path at all. + """ + + session_id = start(rig.daemon, "sleeper") + lease = rig.daemon.call("pointer.acquire", id=session_id)["lease_id"] + rig.driver.sink.calls.clear() + + first = rig.daemon.call( + "keyboard.type", id=session_id, lease_id=lease, text="ab", request_id="retry-me" + ) + second = rig.daemon.call( + "keyboard.type", id=session_id, lease_id=lease, text="ab", request_id="retry-me" + ) + + assert first["ok"] and second["ok"] + assert second.get("deduplicated") is True + assert first["chars"] == 2 and second["chars"] == 2 + # Two characters, a down and an up each: four key events for one `type`, + # and the replay must not add a fifth. + assert len(rig.driver.sink.of("key")) == 4, ( + f"a replayed type sent {rig.driver.sink.of('key')}; the recorded answer " + "must be returned without typing again" + ) + + +def test_a_retried_unmappable_type_stays_refused_and_types_nothing(rig: Rig): + """The recorded answer includes a recorded refusal. + + An agent that retries a `type` which was refused must see the refusal + again, not a second attempt -- and the sink must still be untouched after + both calls, because validation happens before the first event either time. + """ + + session_id = start(rig.daemon, "sleeper") + lease = rig.daemon.call("pointer.acquire", id=session_id)["lease_id"] + rig.driver.sink.calls.clear() + + first = rig.daemon.call( + "keyboard.type", + id=session_id, + lease_id=lease, + text="caf\u00e9", + request_id="refuse-me", + ) + second = rig.daemon.call( + "keyboard.type", + id=session_id, + lease_id=lease, + text="caf\u00e9", + request_id="refuse-me", + ) + + assert first["ok"] is False and second["ok"] is False + assert first["error"] == "invalid_argument", first + assert second["error"] == "invalid_argument", second + assert second.get("deduplicated") is True, ( + "a recorded failure must be replayed as the failure it was" + ) + assert rig.driver.sink.of("key") == [], ( + f"an unmappable string typed something: {rig.driver.sink.calls}. There is " + "no partial type, on the first call or the replay." + ) + + def test_a_restored_bookmark_survives_a_daemon_restart(short_tmpdir: Path): """That is what putting it in the record, and not only in the lease, is for.""" @@ -572,7 +680,12 @@ def test_a_restored_bookmark_survives_a_daemon_restart(short_tmpdir: Path): acquired = rig.daemon.call("pointer.acquire", id=session_id) assert (acquired["bookmark"]["x"], acquired["bookmark"]["y"]) == (0.8, 0.2) - assert rig.driver.sink.of("warp") == [("warp", f"hh-{session_id}", 0.8, 0.2)] + # The nudge, then the restored position: the bookmark has to be the + # *second* warp, or every restore would be a few pixels off. + assert rig.driver.sink.of("warp") == [ + ("warp", f"hh-{session_id}", 0.8, 0.204), + ("warp", f"hh-{session_id}", 0.8, 0.2), + ] finally: _kill_everything(rig.daemon) rig.stop() diff --git a/tests/sessions/unit/test_broker_protocol.py b/tests/sessions/unit/test_broker_protocol.py index 85065ec..66f43ae 100644 --- a/tests/sessions/unit/test_broker_protocol.py +++ b/tests/sessions/unit/test_broker_protocol.py @@ -172,6 +172,30 @@ def test_every_pointer_verb_that_moves_something_is_cached(): assert "container.list" not in protocol.MUTATING_VERBS +def test_every_keyboard_verb_is_cached_for_the_same_reason(): + """A retried `type` that typed twice is also unrecoverable. + + And `pointer.state`, which now reports held keys, stays out of the set: it + mutates nothing, and a cached one would be a stale one. + """ + + assert {"keyboard.key", "keyboard.type"} <= protocol.MUTATING_VERBS + assert {"keyboard.key", "keyboard.type"} <= set(protocol.VERBS) + assert "pointer.state" not in protocol.MUTATING_VERBS + + +def test_there_is_no_keyboard_acquire_verb(): + """One seat, one keyboard focus, one lease. + + A `keyboard.acquire` would let session B warp the pointer while session A + believed it was typing into its own window, because `follow_mouse = 1` + means a warp retargets the keys. + """ + + assert not any(verb.startswith("keyboard.acquire") for verb in protocol.VERBS) + assert "keyboard.release" not in protocol.VERBS + + def test_every_verb_the_protocol_names_is_one_the_daemon_answers(): """One list, so a verb cannot be added to the dispatcher alone. diff --git a/tests/sessions/unit/test_cli_surface.py b/tests/sessions/unit/test_cli_surface.py index 25b9d7d..ae57403 100644 --- a/tests/sessions/unit/test_cli_surface.py +++ b/tests/sessions/unit/test_cli_surface.py @@ -105,12 +105,82 @@ def test_every_verb_the_contract_names_is_registered(host_cli): ["session", "pointer", "release", "foo-aaaaaa"], ["session", "pointer", "state"], ["session", "pointer", "state", "--json"], + ["session", "keyboard", "type", "foo-aaaaaa", "hello"], + ["session", "keyboard", "type", "foo-aaaaaa", "hello", "--lease", "abc"], + ["session", "keyboard", "key", "foo-aaaaaa", "Return"], + ["session", "keyboard", "down", "foo-aaaaaa", "Control_L"], + ["session", "keyboard", "up", "foo-aaaaaa", "Control_L"], ] for argv in surface: args = host_cli.parse_args(argv) assert callable(args.func), argv +def test_the_keyboard_help_says_the_pointer_lease_is_required(host_cli, capsys): + """Exit 9 until `pointer acquire` is the one fact an agent gets wrong here. + + Asserted on the `keyboard` group's own help and on a leaf's, because + `--help` on a leaf is what an agent actually reads -- and the group help is + what a human skims. + """ + + for argv in (["session", "keyboard", "--help"], ["session", "keyboard", "type", "--help"]): + with pytest.raises(SystemExit): + host_cli.parse_args(argv) + out = capsys.readouterr().out + assert "pointer acquire" in out + assert "9" in out, "the exit code an agent has to branch on" + + +def test_the_keyboard_help_warns_that_a_held_key_floods(host_cli, capsys): + """Unconditionally, and not because a probe saw repeats on the wire. + + It did not: the compositor sends one event and the application repeats, so + the flood is real and is not ours to rate-limit. + """ + + with pytest.raises(SystemExit): + host_cli.parse_args(["session", "keyboard", "down", "--help"]) + out = capsys.readouterr().out.lower() + assert "flood" in out + + +def test_the_pointer_help_does_not_grow_a_keyboard_tutorial(host_cli, capsys): + """`pointer --help` stays about the cursor. + + Narrow on purpose: `acquire`'s *stderr* had to start mentioning keyboard + verbs (they refresh the lease), so a test that grepped the whole binary's + help for the word would pass for the wrong reason. This reads the pointer + group's description only. + """ + + with pytest.raises(SystemExit): + host_cli.parse_args(["session", "pointer", "--help"]) + out = capsys.readouterr().out + assert "keysym" not in out + assert "keyboard type" not in out + + +def test_type_takes_its_text_as_one_argument_and_does_not_interpret_it(host_cli): + r"""A newline is a newline; a backslash-n is a backslash and an n. + + Interpreting escapes here would make a literal backslash-n untypeable, + and the shell has already done the quoting. + """ + + # A real newline survives as a real newline. + args = host_cli.parse_args(["session", "keyboard", "type", "foo-aaaaaa", "a\nb"]) + assert args.text == "a\nb" + assert len(args.text) == 3 + + # And a backslash followed by an n stays two characters: interpreting it + # would make a literal backslash-n untypeable. + args = host_cli.parse_args(["session", "keyboard", "type", "foo-aaaaaa", r"a\nb"]) + assert args.text == r"a\nb" + assert len(args.text) == 4 + assert "\n" not in args.text + + def test_a_move_needs_exactly_one_target(host_cli): with pytest.raises(SystemExit): host_cli.parse_args(["session", "pointer", "move", "x"]) diff --git a/tests/sessions/unit/test_driver_client.py b/tests/sessions/unit/test_driver_client.py index 314a6e2..2fd08a1 100644 --- a/tests/sessions/unit/test_driver_client.py +++ b/tests/sessions/unit/test_driver_client.py @@ -77,7 +77,10 @@ def test_release_all_lifts_everything_and_says_what_it_lifted(driver): client.button("left", "down") client.button("right", "down") - assert client.release_all() == ["left", "right"] + # One call, two lists: there is one `release_all` op and one expiry call + # site, so buttons and keys come back together rather than needing a + # second request that could be forgotten. + assert client.release_all() == (["left", "right"], []) assert client.pressed() == [] # Lifted through the pointer each went down on, then one frame for it. assert fake.sink.calls[-3:] == [ @@ -91,7 +94,7 @@ def test_release_all_on_an_idle_driver_is_an_empty_list_not_an_error(driver): """The expiry path calls this unconditionally; it must be safe.""" client, _ = driver - assert client.release_all() == [] + assert client.release_all() == ([], []) def test_a_refusal_is_carried_back_and_is_not_a_lost_connection(driver): @@ -215,7 +218,7 @@ def test_a_reply_that_is_not_the_protocol_is_unavailable_not_an_empty_answer( try: with pytest.raises(DriverUnavailable) as exc: client.pressed() - assert "list of button names" in str(exc.value) + assert "list of names" in str(exc.value) finally: client.close() thread.join(timeout=5.0) diff --git a/tests/sessions/unit/test_keyboard_verbs.py b/tests/sessions/unit/test_keyboard_verbs.py new file mode 100644 index 0000000..8d070ed --- /dev/null +++ b/tests/sessions/unit/test_keyboard_verbs.py @@ -0,0 +1,663 @@ +"""The keyboard verbs: the pointer lease, the key mirror, and the exit codes. + +Harness copied from ``test_pointer_verbs.py``, and the same things are real: +the manager, the lease, the driver client, and the shipped dispatcher and +server over a real ``AF_UNIX`` socket — plus a real compiled ``us`` keymap, so +an assertion about which evdev code went on the wire is an assertion about the +layout and not about a stub that agreed with it. Only the Wayland sink and the +clock are substituted. + +Two things these tests are careful about, both of them false passes the +verification doc names: + +* **the clock does not advance anything by itself.** A test that moves + ``ManualClock`` and then asserts the lease is gone would pass against a + broker that never expires anything: expiry runs in ``_expire_pointer``, from + the sweeper or from the next verb, so every expiry case here calls one of + those explicitly. +* **a refusal is asserted by its exit code and by the sink.** "The reply said + `ok: false`" is satisfied by a handler that typed the string and then + errored, so the sink's call list is checked too. +""" + +from __future__ import annotations + +import asyncio +from pathlib import Path + +import pytest +from fakes import KEY_A, KEY_LEFTCTRL, KEY_LEFTSHIFT, FakeDriver, us_keymap + +from hhstreamd.clock import ManualClock +from hhstreamd.manager import ManagerConfig, ManagerError, SessionManager +from hhstreamd.policy import Policy +from hhstreamd.protocol import ExitCode, exit_code_for +from hhstreamd.registry import ContainerState, Session, State, container_record + +DOWN, UP = 1, 0 + + +def make_session(session_id: str = "foot-aaaaaa", *, container: bool = True) -> Session: + return Session( + id=session_id, + app="foot", + argv=["/usr/bin/foot"], + pid=4242, + pgid=4242, + sid=4242, + pid_starttime=918342, + cmdline_sha256="9f2c", + home="/home/someone", + runtime_dir=f"/run/hhstream/sessions/{session_id}", + created_at="2026-10-01T09:14:02Z", + created_boottime=1000.0, + last_activity_at="2026-10-01T09:14:02Z", + last_activity_boottime=1000.0, + idle_timeout_s=10800.0, + state=State.READY, + container=( + container_record( + output=f"hh-{session_id}", + workspace=1000, + mode=(1280, 720), + created_by="broker", + state=ContainerState.OWNED, + ) + if container + else None + ), + ) + + +class Harness: + def __init__(self, manager: SessionManager, fake: FakeDriver, clock: ManualClock) -> None: + self.manager = manager + self.fake = fake + self.clock = clock + + def add(self, session_id: str = "foot-aaaaaa", **kwargs) -> Session: + return self.manager.registry.add(make_session(session_id, **kwargs)) + + def run(self, coro): + return asyncio.run(coro) + + def acquire(self, session_id: str = "foot-aaaaaa") -> str: + """Add the session if it is not there yet, then take the lease. + + Convenience, and deliberate: almost every test here is about what + happens *after* a lease exists, and spelling out the `add` each time + buys nothing. The tests that care about two sessions add them by hand. + """ + + if self.manager.registry.get(session_id) is None: + self.add(session_id) + lease = self.run(self.manager.pointer_acquire(session_id))["lease_id"] + # Acquire's own two focus warps are not what any of these tests are + # about, so they are dropped here rather than skipped past in every + # assertion. + self.fake.sink.calls.clear() + return lease + + def keys(self) -> list[str]: + return self.manager.pointer_state()["keys"] + + +def _harness(short_tmpdir: Path, *, keyboard: bool = True): + fake = FakeDriver(short_tmpdir / "p.sock", keyboard=keyboard) + clock = ManualClock(boottime=1000.0) + manager = SessionManager( + ManagerConfig( + state_dir=short_tmpdir / "state", + runtime_dir=short_tmpdir / "run", + policy=Policy(), + pointer_socket=fake.socket_path, + pointer_ttl_s=30.0, + pointer_max_s=300.0, + ), + clock=clock, + ) + try: + yield Harness(manager, fake, clock) + finally: + if manager.driver is not None: + manager.driver.close() + fake.stop() + + +@pytest.fixture +def harness(short_tmpdir: Path): + yield from _harness(short_tmpdir) + + +@pytest.fixture +def keyboardless(short_tmpdir: Path): + """A driver whose compositor advertises no virtual-keyboard global.""" + + yield from _harness(short_tmpdir, keyboard=False) + + +# --------------------------------------------------------------------------- +# the lease is the pointer's +# --------------------------------------------------------------------------- + + +def test_typing_without_a_lease_is_no_lease_and_not_busy(harness): + """Exit 9 and not 8: 9 says "acquire one", 8 says "wait for someone".""" + + harness.add() + + with pytest.raises(ManagerError) as exc: + harness.run(harness.manager.keyboard_type("foot-aaaaaa", "nonesuch", "hello")) + + assert exc.value.error == "no_lease" + assert exit_code_for(exc.value.error) == ExitCode.NO_LEASE + assert harness.fake.sink.calls == [] + + +def test_another_sessions_lease_is_also_no_lease(harness): + harness.add("foot-aaaaaa") + harness.add("foot-bbbbbb") + lease = harness.acquire("foot-aaaaaa") + + with pytest.raises(ManagerError) as exc: + harness.run(harness.manager.keyboard_type("foot-bbbbbb", lease, "hello")) + + # Not `pointer_busy`: B is not being told to wait its turn, it is being + # told this lease id is not its own. + assert exc.value.error == "no_lease" + assert harness.fake.sink.calls == [] + + +def test_a_second_acquire_while_a_key_is_held_is_busy_and_leaves_the_key(harness): + harness.add("foot-aaaaaa") + harness.add("foot-bbbbbb") + lease = harness.acquire("foot-aaaaaa") + harness.run(harness.manager.keyboard_key("foot-aaaaaa", lease, "Shift_L", "down")) + + with pytest.raises(ManagerError) as exc: + harness.run(harness.manager.pointer_acquire("foot-bbbbbb")) + + assert exc.value.error == "pointer_busy" + assert exit_code_for(exc.value.error) == ExitCode.BUSY + # Still the first holder's, and still held: a refused acquire must not + # disturb a chord someone is in the middle of. + assert harness.manager.pointer.state()["holder"] == "foot-aaaaaa" + assert harness.keys() == ["Shift_L"] + + +def test_the_holder_cannot_acquire_a_second_lease_either(harness): + """Unchanged by the keyboard, and asserted here because typing is where a + second id would do the most damage: a half-typed chord whose lease was + silently replaced fails with "stale lease" for no visible reason.""" + + harness.add() + harness.acquire() + + with pytest.raises(ManagerError) as exc: + harness.run(harness.manager.pointer_acquire("foot-aaaaaa")) + assert exc.value.error == "pointer_busy" + + +# --------------------------------------------------------------------------- +# what goes on the wire +# --------------------------------------------------------------------------- + + +def test_typing_a_capital_sends_the_mask_then_the_key(harness): + lease = harness.acquire() + + reply = harness.run(harness.manager.keyboard_type("foot-aaaaaa", lease, "A")) + + shift = us_keymap().modifier_mask("Shift_L") + assert harness.fake.sink.calls == [ + ("modifiers", shift, 0, 0, 0), + ("key", KEY_A, DOWN), + ("key", KEY_A, UP), + ("modifiers", 0, 0, 0, 0), + ] + # No synthetic Shift keycode: this compositor does not derive the mask from + # an injected key, and sending both is how a toolkit shifts twice. + assert not any(c[0] == "key" and c[1] == KEY_LEFTSHIFT for c in harness.fake.sink.calls) + assert reply["chars"] == 1 + assert reply["keys"] == [] + + +def test_typing_leaves_nothing_held(harness): + lease = harness.acquire() + harness.run(harness.manager.keyboard_type("foot-aaaaaa", lease, "hello")) + assert harness.keys() == [] + + +def test_a_held_modifier_survives_a_type_and_ors_into_it(harness): + lease = harness.acquire() + harness.run(harness.manager.keyboard_key("foot-aaaaaa", lease, "Control_L", "down")) + harness.fake.sink.calls.clear() + + reply = harness.run(harness.manager.keyboard_type("foot-aaaaaa", lease, "c")) + + control = us_keymap().modifier_mask("Control_L") + assert harness.fake.sink.calls[0] == ("modifiers", control, 0, 0, 0) + # Restored to the baseline, not to zero: Control was not this type's to + # lift, and `down Control_L` + `type c` + `up Control_L` is how a chord is + # spelled across three CLI invocations. + assert harness.fake.sink.calls[-1] == ("modifiers", control, 0, 0, 0) + assert reply["keys"] == ["Control_L"] + assert harness.keys() == ["Control_L"] + + +def test_a_key_down_is_mirrored_in_the_lease_by_name(harness): + lease = harness.acquire() + + reply = harness.run( + harness.manager.keyboard_key("foot-aaaaaa", lease, "Control_L", "down") + ) + + # The reply and the lease both speak names; only the sink sees the code. + assert reply["keys"] == ["Control_L"] + assert harness.keys() == ["Control_L"] + assert ("key", KEY_LEFTCTRL, DOWN) in harness.fake.sink.calls + + +def test_pointer_state_reports_held_keys_beside_held_buttons(harness): + lease = harness.acquire() + harness.run(harness.manager.pointer_button("foot-aaaaaa", lease, "left", "down")) + harness.run(harness.manager.keyboard_key("foot-aaaaaa", lease, "Shift_L", "down")) + + state = harness.manager.pointer_state() + + assert state["buttons"] == ["left"] + assert state["keys"] == ["Shift_L"] + + +def test_an_up_of_a_key_that_was_not_down_changes_nothing(harness): + lease = harness.acquire() + + reply = harness.run(harness.manager.keyboard_key("foot-aaaaaa", lease, "Shift_L", "up")) + + assert reply["keys"] == [] + # Nothing on the wire either: a key-up the compositor has no matching + # key-down for puts its `m_pressed` out of step with ours. + assert harness.fake.sink.calls == [] + + +# --------------------------------------------------------------------------- +# exit codes (the verification doc's change 1) +# --------------------------------------------------------------------------- + + +def test_an_unmappable_character_is_exit_2_and_types_nothing(harness): + """The driver's token is what makes this 2 rather than 10. + + Without it the refusal arrives as `driver_refused`, which is exit 10 and + says "the compositor failed" about a character that is simply not on the + layout. `é` is the case: perfectly well formed, unmappable on `us`. + """ + + lease = harness.acquire() + + with pytest.raises(ManagerError) as exc: + harness.run(harness.manager.keyboard_type("foot-aaaaaa", lease, "café")) + + assert exc.value.error == "invalid_argument" + assert exit_code_for(exc.value.error) == ExitCode.USAGE + # No prefix: "c", "a" and "f" must not have been typed. + assert harness.fake.sink.calls == [] + + +def test_the_refusal_does_not_carry_the_string_it_refused(harness): + """A typed string is a password as often as not, and this reason is logged.""" + + lease = harness.acquire() + + with pytest.raises(ManagerError) as exc: + harness.run(harness.manager.keyboard_type("foot-aaaaaa", lease, "hunter2é")) + + assert "hunter2" not in exc.value.reason + assert "é" not in exc.value.reason + assert "scalar 7" in exc.value.reason + + +def test_an_unknown_keysym_is_exit_2(harness): + lease = harness.acquire() + + with pytest.raises(ManagerError) as exc: + harness.run( + harness.manager.keyboard_key("foot-aaaaaa", lease, "NoSuchKeysym", "down") + ) + + assert exit_code_for(exc.value.error) == ExitCode.USAGE + assert harness.keys() == [] + + +@pytest.mark.parametrize( + "text, fragment", + [(None, "must be a string"), (7, "must be a string"), (["a"], "must be a string")], +) +def test_a_text_that_is_not_a_string_is_exit_2_before_the_driver(harness, text, fragment): + lease = harness.acquire() + + with pytest.raises(ManagerError) as exc: + harness.run(harness.manager.keyboard_type("foot-aaaaaa", lease, text)) + + assert exc.value.error == "invalid_argument" + assert fragment in exc.value.reason + assert harness.fake.sink.calls == [] + + +def test_a_string_over_the_cap_is_exit_2_at_the_broker(harness): + """Checked here and not only in the driver, because only a broker-side + `invalid_argument` produces exit 2 — a driver-side length refusal would + arrive as a compositor failure unless it carried the token.""" + + from hhstreamd.manager import MAX_TYPE_SCALARS + + lease = harness.acquire() + + with pytest.raises(ManagerError) as exc: + harness.run( + harness.manager.keyboard_type("foot-aaaaaa", lease, "a" * (MAX_TYPE_SCALARS + 1)) + ) + + assert exc.value.error == "invalid_argument" + assert str(MAX_TYPE_SCALARS) in exc.value.reason + assert harness.fake.sink.calls == [] + + +def test_exactly_the_cap_is_accepted(harness): + from hhstreamd.manager import MAX_TYPE_SCALARS + + lease = harness.acquire() + reply = harness.run( + harness.manager.keyboard_type("foot-aaaaaa", lease, "a" * MAX_TYPE_SCALARS) + ) + assert reply["chars"] == MAX_TYPE_SCALARS + + +@pytest.mark.parametrize("state", [None, "sideways", "DOWN", 1]) +def test_a_bad_key_state_is_exit_2(harness, state): + lease = harness.acquire() + + with pytest.raises(ManagerError) as exc: + harness.run(harness.manager.keyboard_key("foot-aaaaaa", lease, "a", state)) + + assert exc.value.error == "invalid_argument" + assert harness.fake.sink.calls == [] + + +def test_no_keyboard_global_is_exit_10_and_the_cursor_still_works(keyboardless): + """A compositor with no `zwp_virtual_keyboard_manager_v1`. + + Exit 10 and not 2: the caller's request was fine. And the pointer half has + to keep working, which is the whole reason a missing keyboard global does + not abort the driver's start-up the way a version-1 pointer manager does. + """ + + keyboardless.add() + lease = keyboardless.acquire() + + with pytest.raises(ManagerError) as exc: + keyboardless.run(keyboardless.manager.keyboard_type("foot-aaaaaa", lease, "hi")) + assert exc.value.error == "driver_refused" + assert exit_code_for(exc.value.error) == ExitCode.COMPOSITOR + + # The cursor is unaffected. + moved = keyboardless.run( + keyboardless.manager.pointer_move("foot-aaaaaa", lease, x=0.25, y=0.75) + ) + assert moved["bookmark"]["x"] == 0.25 + + +def test_a_refused_key_is_not_recorded_as_held(harness): + """The driver first, then the mirror — the `pointer_button` order. + + The reverse mistake is harmless (`release_all` lifts what the *driver* + recorded), but recording a key the driver refused means `release_all` later + asks it to lift something it never pressed. + """ + + lease = harness.acquire() + + with pytest.raises(ManagerError): + harness.run(harness.manager.keyboard_key("foot-aaaaaa", lease, "NoSuchKeysym", "down")) + + assert harness.keys() == [] + assert harness.manager.pointer_state()["keys"] == [] + + +# --------------------------------------------------------------------------- +# the TTL +# --------------------------------------------------------------------------- + + +def test_typing_refreshes_the_lease(harness): + """`type` goes through `_refresh`, so it moves the idle deadline. + + The clock is advanced in two steps with a `type` between them: 20s, type, + 20s. Without the refresh that is 40s against a 30s TTL and the lease is + gone; with it, the second 20s is measured from the type. + """ + + harness.add() + lease = harness.acquire() + + harness.clock.advance(20.0) + harness.run(harness.manager.keyboard_type("foot-aaaaaa", lease, "hello")) + harness.clock.advance(20.0) + # The next verb is what notices an expiry, so this is the honest way to ask + # "is the lease still alive" -- not reading `state()`, which never expires + # anything. + harness.run(harness.manager._expire_pointer()) + + assert harness.manager.pointer.state()["holder"] == "foot-aaaaaa" + + +def test_the_hard_cap_still_beats_a_typing_loop(harness): + harness.add() + lease = harness.acquire() + + for _ in range(20): + harness.clock.advance(20.0) + with __import__("contextlib").suppress(ManagerError): + harness.run(harness.manager.keyboard_type("foot-aaaaaa", lease, "x")) + + assert harness.manager.pointer.state()["holder"] is None + + +def test_an_expired_lease_lifts_the_key_it_left_down(harness): + """The expiry contract, with a key: read before `expire()`, then one + `release_all` on the driver, and the mask zeroed after the key-up.""" + + harness.add() + lease = harness.acquire() + harness.run(harness.manager.keyboard_key("foot-aaaaaa", lease, "Shift_L", "down")) + harness.fake.sink.calls.clear() + harness.clock.advance(31.0) + + expired = harness.run(harness.manager._expire_pointer()) + + assert expired["keys_lifted"] == ["Shift_L"] + assert harness.fake.sink.calls == [ + ("key", KEY_LEFTSHIFT, UP), + # Not optional. A virtual key-up clears no modifier state on this + # compositor, so without this the next holder inherits Shift. + ("modifiers", 0, 0, 0, 0), + ] + assert harness.manager.pointer.state()["holder"] is None + assert harness.keys() == [] + + +def test_expiry_lifts_buttons_and_keys_in_one_release_all(harness): + harness.add() + lease = harness.acquire() + harness.run(harness.manager.pointer_button("foot-aaaaaa", lease, "left", "down")) + harness.run(harness.manager.keyboard_key("foot-aaaaaa", lease, "Control_L", "down")) + harness.fake.sink.calls.clear() + harness.clock.advance(31.0) + + expired = harness.run(harness.manager._expire_pointer()) + + assert expired["buttons_lifted"] == ["left"] + assert expired["keys_lifted"] == ["Control_L"] + # Buttons first with their frame, then keys, then the mask. One round trip. + assert [c[0] for c in harness.fake.sink.calls] == [ + "button", + "frame", + "key", + "modifiers", + ] + + +def test_a_held_key_does_not_leak_to_the_next_holder(harness): + harness.add("foot-aaaaaa") + harness.add("foot-bbbbbb") + lease = harness.acquire("foot-aaaaaa") + harness.run(harness.manager.keyboard_key("foot-aaaaaa", lease, "Shift_L", "down")) + harness.clock.advance(31.0) + harness.run(harness.manager._expire_pointer()) + + harness.acquire("foot-bbbbbb") + + assert harness.keys() == [] + + +def test_typing_does_not_count_as_activity(harness): + """`touch` is the only mark of activity, and typing is not it. + + Both halves are asserted: the timestamp and the counter. A future change + that moved the timestamp without counting a command would pass a + counter-only test. + """ + + session = harness.add() + lease = harness.acquire() + before_at = session.last_activity_at + before_boottime = session.last_activity_boottime + before_count = session.command_count + harness.clock.advance(5.0) + + harness.run(harness.manager.keyboard_type("foot-aaaaaa", lease, "hello")) + harness.run(harness.manager.keyboard_key("foot-aaaaaa", lease, "Shift_L", "down")) + + assert session.last_activity_boottime == before_boottime + assert session.last_activity_at == before_at + assert session.command_count == before_count + + +# --------------------------------------------------------------------------- +# release, kill, and the audit +# --------------------------------------------------------------------------- + + +def test_release_lifts_held_keys_and_reports_them(harness): + harness.add() + lease = harness.acquire() + harness.run(harness.manager.keyboard_key("foot-aaaaaa", lease, "Shift_L", "down")) + + reply = harness.run(harness.manager.pointer_release("foot-aaaaaa", lease)) + + assert reply["keys_lifted"] == ["Shift_L"] + assert reply["buttons_lifted"] == [] + assert harness.manager.pointer_state()["keys"] == [] + + +def test_killing_the_holder_lifts_its_keys(harness): + harness.add() + lease = harness.acquire() + harness.run(harness.manager.keyboard_key("foot-aaaaaa", lease, "Control_L", "down")) + harness.fake.sink.calls.clear() + + harness.run(harness.manager._drop_lease_for(harness.manager.registry.get("foot-aaaaaa"), "kill")) + + assert ("key", KEY_LEFTCTRL, UP) in harness.fake.sink.calls + assert ("modifiers", 0, 0, 0, 0) in harness.fake.sink.calls + assert harness.manager.pointer.state()["holder"] is None + assert lease # the id is still the one we were given; nothing replayed it + + +def test_the_audit_records_a_character_count_and_never_the_text(harness): + harness.add() + lease = harness.acquire() + secret = "hunter2" + + harness.run(harness.manager.keyboard_type("foot-aaaaaa", lease, secret)) + + events = harness.manager.audit.tail(50, session="foot-aaaaaa") + typed = [e for e in events if e.get("event") == "keyboard_type"] + assert len(typed) == 1 + assert typed[0]["chars"] == len(secret) + assert "text" not in typed[0] + # And not hiding anywhere else in the line either. + assert secret not in str(typed[0]) + + +def test_the_audit_records_a_keysym_name_which_is_not_a_secret(harness): + harness.add() + lease = harness.acquire() + + harness.run(harness.manager.keyboard_key("foot-aaaaaa", lease, "Return", "down")) + + events = harness.manager.audit.tail(50, session="foot-aaaaaa") + pressed = [e for e in events if e.get("event") == "keyboard_key"] + assert pressed[-1]["key"] == "Return" + assert pressed[-1]["state"] == "down" + + +def test_the_expiry_audit_event_records_the_keys_it_lifted(harness): + harness.add() + lease = harness.acquire() + harness.run(harness.manager.keyboard_key("foot-aaaaaa", lease, "Shift_L", "down")) + harness.clock.advance(31.0) + + harness.run(harness.manager._expire_pointer()) + + events = harness.manager.audit.tail(50) + timeout = [e for e in events if e.get("event") == "pointer_lease_timeout"][-1] + assert timeout["keys_pressed"] == ["Shift_L"] + assert timeout["keys_lifted"] == ["Shift_L"] + + +# --------------------------------------------------------------------------- +# acquire takes the keyboard, not only the cursor +# --------------------------------------------------------------------------- + + +def test_acquire_sends_two_motions_so_keyboard_focus_moves(harness): + """One warp is not enough, and that is measured, not assumed. + + Hyprland zeroes `m_mousePosDelta` when the previous cursor movement was + over 0.5s ago and compares it against `follow_mouse_threshold` (0) to + decide keyboard focus, so a single warp onto an idle cursor delivers + `wl_pointer.enter` and no `wl_keyboard.enter`. The aimed window gets the + cursor and the previously focused one keeps the keys — and then the first + key of the lease goes to the wrong window. + + A check that only looked for pointer delivery would pass while that + happened, which is why this asserts the *pair*. + """ + + harness.add() + + reply = harness.run(harness.manager.pointer_acquire("foot-aaaaaa")) + + warps = harness.fake.sink.of("warp") + assert len(warps) == 2, "a single warp does not move keyboard focus" + # The second one is the bookmark, so a restore is not a few pixels off. + assert (warps[1][2], warps[1][3]) == (0.5, 0.5) + assert (reply["bookmark"]["x"], reply["bookmark"]["y"]) == (0.5, 0.5) + # And they are different *floored* pixels at the frozen 1280x720 container + # mode: `mouseMoveUnified` returns before it touches the delta when the + # floored position has not changed. + assert round(warps[0][3] * 720) != round(warps[1][3] * 720) + assert reply["focus"] == "warp" + + +def test_the_focus_mechanism_is_recorded_in_the_audit(harness): + harness.add() + + harness.run(harness.manager.pointer_acquire("foot-aaaaaa")) + + events = harness.manager.audit.tail(50, session="foot-aaaaaa") + acquired = [e for e in events if e.get("event") == "pointer_acquired"][-1] + # So a session that ends up typing into the wrong window can be told apart + # from one that never tried to take focus. + assert acquired["focus"] == "warp" diff --git a/tests/sessions/unit/test_pointer_verbs.py b/tests/sessions/unit/test_pointer_verbs.py index 007e553..e037737 100644 --- a/tests/sessions/unit/test_pointer_verbs.py +++ b/tests/sessions/unit/test_pointer_verbs.py @@ -114,10 +114,25 @@ def test_acquire_with_no_bookmark_aims_at_the_centre_of_the_container(harness): "output": "hh-foot-aaaaaa", "at": reply["bookmark"]["at"], } + # TWO motions, and the order is the point. One warp onto an idle cursor + # delivers wl_pointer.enter and no wl_keyboard.enter: Hyprland zeroes + # `m_mousePosDelta` when the previous movement was over 0.5s ago, and + # keyboard focus is that delta against `follow_mouse_threshold`. So the + # nudge goes first and the real target second, the second motion carries a + # non-zero delta, and the cursor finishes at the bookmark. assert harness.fake.sink.calls == [ + ("warp", "hh-foot-aaaaaa", 0.5, 0.504), + ("frame", "hh-foot-aaaaaa"), ("warp", "hh-foot-aaaaaa", 0.5, 0.5), ("frame", "hh-foot-aaaaaa"), ] + # And the two really are different pixels at the frozen 1280x720 container + # mode: `mouseMoveUnified` returns before it touches the delta when the + # floored position has not changed, so a sub-pixel nudge would move the + # cursor and leave the keys where they were. + first, second = harness.fake.sink.of("warp") + assert round(first[3] * 720) != round(second[3] * 720) + assert reply["focus"] == "warp" def test_acquire_restores_the_position_the_session_was_left_at(harness): @@ -130,8 +145,15 @@ def test_acquire_restores_the_position_the_session_was_left_at(harness): reply = harness.run(harness.manager.pointer_acquire("foot-aaaaaa")) assert (reply["bookmark"]["x"], reply["bookmark"]["y"]) == (0.25, 0.75) - assert harness.fake.sink.of("warp") == [("warp", "hh-foot-aaaaaa", 0.25, 0.75)] + # The nudge, then the restored position. The bookmark is where the cursor + # is left, so the second warp is the one that has to be the bookmark -- + # the reverse order would restore the session a few pixels off, every time. + assert harness.fake.sink.of("warp") == [ + ("warp", "hh-foot-aaaaaa", 0.25, 0.754), + ("warp", "hh-foot-aaaaaa", 0.25, 0.75), + ] assert session.pointer["bookmark"]["x"] == 0.25 + assert session.pointer["bookmark"]["y"] == 0.75 def test_restore_false_goes_to_the_centre_even_with_a_bookmark(harness): @@ -365,6 +387,10 @@ def test_an_idle_lease_expires_and_the_button_it_left_down_is_lifted(harness): "session": "foot-aaaaaa", "lease_id": lease, "buttons_lifted": ["left"], + # Empty, and reported rather than omitted: this lease held no key, and + # "no keys were lifted" is a different answer from "keys were not + # considered". + "keys_lifted": [], } assert harness.manager.pointer.state()["holder"] is None assert harness.fake.sink.calls[-2:] == [ @@ -441,7 +467,8 @@ def test_expiry_with_no_driver_is_loud_rather_than_silent(harness, caplog): with caplog.at_level("ERROR"): harness.run(harness.manager._expire_pointer()) - assert "a button may still be down" in caplog.text + assert "they may still be held" in caplog.text + assert "buttons ['left']" in caplog.text assert harness.manager.pointer.state()["holder"] is None