Files
hyprland-headless-stream-pl…/nix/hyprland-conf.nix
T
HermenixandClaude Opus 5 e6f4c3bb3f Stage 1 review fixes, and Stage 2: the broker, the CLI and the module
The Stage 1 review (docs/reviews/2026-10-04-stage1-review.md, verdict
yes-with-fixes) found a real bug, and it was the kind Stage 2 would have
cemented. All five findings:

(1) HIGH, and reproduced before fixing: `key` resolved the action and
    then used only its `code`. So `keyboard key A` sent a bare code 30
    and the window received `a`; on `de`, `at` lost its level-three mask
    and typed `q`. `type` was the only path that used the mask, which is
    why every `type` test stayed green. `key` now sends
    modifiers(baseline | mask) before the down and restores the baseline
    on the up -- the one-character `type` sequence -- and `Shift_L`
    keeps its key-then-mask order, which is the other path on purpose.

    The same hole aliased two names onto one keycode: `down A` then
    `down a` recorded both and pressed 30 twice, Hyprland dropped the
    second, and the held set lied until the lease ended. A second name
    for a code already down is now refused.

(2) HIGH: the shutdown comment claimed hyprland-conf.nix sets
    input:virtualkeyboard:release_pressed_on_close. It did not. The line
    is there now, with the note that it releases keys and still never
    clears a mask -- which is why release_all zeroes the mask on every
    path we control rather than relying on it.

(3) MEDIUM: nothing would have noticed the keymap upload stopping. A
    `main` that connected and listened without uploading passed every
    test in the tree. Now asserted on the real sink: uploaded once,
    before `listen` (one shared ordering log across both stand-ins), the
    payload NUL-terminated with `size == len(utf8) + 1` read back
    through the fd, format 1, one terminator not two, and modifiers(0)
    straight after.

(4) LOW: `key` up now forgets the name only after a successful send,
    like `button` -- otherwise a raise between the two leaves us
    believing a key is up that the compositor still has down, and
    release_all will not try again.

(5) LOW: `\r` no longer aliases to Return (CRLF would have become two
    newlines silently), and an empty layout is refused -- xkbcommon
    compiles "" as the same keymap as `us`, so `--xkb-layout ''` looked
    configured and typed `us`.

Several of the review's named false passes are closed too: Control's
mask is compared against mod_get_index("Control") rather than merely
"not Shift's"; the keymap text assertion names pc_us_inet/pc_de_inet
instead of substring-matching "us"; the capital-under-Control case
asserts the whole sequence; the exit-code mirror is compared against
hhstreamd.protocol; and the module's defaults are read out of
nix/module.nix rather than asserted against themselves.

Stage 2 proper:

  * broker verbs keyboard.key / keyboard.type, both in the mutation set,
    both through _refresh (so they refresh the lease and, like every
    pointer verb, do NOT count as activity)
  * the driver's `kind` token mapped: a bad keysym or character is
    invalid_argument (exit 2), a missing keyboard global stays
    driver_refused (exit 10). The 4096-scalar cap and the shape checks
    are broker-side, because only a broker-side invalid_argument is 2
  * keys[] on pointer.state, keys_lifted[] on pointer.release and on
    pointer_lease_timeout, one release_all for both halves
  * CLI `session keyboard type|key|down|up`, reusing the pointer lease
    and its cache; `type` takes one raw argument and interprets nothing;
    the audit records a character count and never the text
  * sessions.keyboard.{layout,model,variant,options} on the unit's argv,
    layout defaulting to "us" with a type that refuses a comma. NO
    [keyboard] TOML table: hhstreamd reads that file and the driver is a
    different unit, so it would be a setting with no effect
  * CONTRACT-sessions.md bumped to v3; README.dev.md item 3 and
    vm-pointer.nix's header corrected (both still said the conf ships
    follow_mouse = 0 and that the keyboard work would choose)

And the operator decision that acquire grabs both devices: it now sends
two warps a real pixel apart, because one warp onto an idle cursor moves
the cursor and not keyboard focus. follow_mouse_threshold = 0 is set
explicitly in hyprland-conf.nix since the second warp depends on it,
`dispatch focuswindow` is the fallback when the nudge cannot be sent,
and the reply and audit carry which mechanism ran. The acquire test
asserts the pair and that they floor to different pixels -- a test that
only saw wl_pointer.enter would pass while the first keystroke went to
the wrong window.

  nix develop -c python -m pytest tests/pointer tests/sessions/unit -q
  605 passed in 27.11s

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GhNPM6rGcuzxocM1nATnuM
2026-10-04 04:11:24 +00:00

159 lines
6.5 KiB
Nix

# The hyprland.conf for a session nobody sits in front of.
#
# Split out of module.nix so the rendering is readable on its own (and diffable
# when an output list changes). Returns the file *text*; the caller puts it in
# the store.
{
lib,
outputs,
extraConfig,
}: let
# `monitor = <name>, <width>x<height>@<refresh>, auto, <scale>` -- "auto"
# lets the compositor lay the outputs out left to right.
#
# The name is a *rule selector*, not an output the compositor will create: it
# is matched as a regex against the names the backend hands up (`eDP-1`,
# `Virtual-1`, ...). Hyprland never invents an output to satisfy a rule, so a
# name that no connector has is a rule that is silently ignored.
#
# An empty name is the wildcard form -- the same shape as Hyprland's own
# shipped `monitor=,preferred,auto,1` -- and applies to every output the
# machine actually has. That is what a session which does not know the host's
# connector names wants, and it is the module's default.
monitorLine = o: "monitor = ${o.name}, ${toString o.width}x${toString o.height}@${toString o.refresh}, auto, ${toString o.scale}";
in ''
# Generated by services.hyprland-headless-stream. Do not edit.
#
# There is no seat, no libinput device, no cursor and no human here: the only
# consumer of this session is the frame server. Everything below either sets
# the mode of the outputs this machine has or switches off something that
# assumes a user.
${lib.concatMapStringsSep "\n" monitorLine outputs}
misc {
# Nothing should draw itself over the captured output.
disable_hyprland_logo = true
disable_splash_rendering = true
force_default_wallpaper = 0
background_color = 0x000000
# The config lives in the store and never changes under us; watching it
# would only cost inotify watches on a read-only path.
disable_autoreload = true
# A virtual output has no variable refresh rate to negotiate.
vrr = 0
# DPMS on a virtual output is meaningless, and there is no key or pointer
# event coming to wake it back up.
key_press_enables_dpms = false
mouse_move_enables_dpms = false
# Both of these check for a desktop that is not here: the Qt helper
# dialogs, and the XDG portal environment.
disable_hyprland_guiutils_check = true
disable_xdg_env_checks = true
}
debug {
# Capture wants a steady frame rate. With variable frame rate the
# compositor only renders on damage, so an idle session would starve the
# stream.
vfr = false
# The session is a systemd unit: its log belongs in the journal, not in a
# file under a runtime directory nobody will look in.
enable_stdout_logs = true
colored_stdout_logs = false
}
cursor {
# No hardware planes, no cursor theme on disk, nobody to warp.
invisible = true
no_hardware_cursors = true
enable_hyprcursor = false
no_warps = true
hide_on_key_press = false
inactive_timeout = 0
}
input {
# Focus follows the pointer. This was `0`, on the reasoning written here
# that no pointer would ever exist — true when it was written, and false
# now that the broker injects one.
#
# It is not a preference. With `0` Hyprland delivers pointer events only to
# the keyboard-focused window: measured in `vm-pointer`, a click aimed at
# 0.25,0.75 of a session's container placed the cursor at x=299 y=519,
# inside that window, and **both** clients reported nothing — the click was
# 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.
animations {
enabled = false
}
decoration {
blur {
enabled = false
}
shadow {
enabled = false
}
}
# Nothing here may reach the network or nag a user who is not there.
ecosystem {
no_update_news = true
no_donation_nag = true
}
${lib.optionalString (extraConfig != "") "\n${extraConfig}"}''