Files
hyprland-headless-stream-pl…/flake.nix
T
HermenixandClaude Opus 5 f931858f30 Stage 1: the driver learns to type
`zwp_virtual_keyboard_v1`, spoken by the process that already speaks
`zwlr_virtual_pointer_v1`. One device for the seat, one keymap uploaded
once, keysym names on our socket and evdev codes only on the Wayland
request -- the division buttons.py already draws.

keymap.py is the new seam, and it holds the three decisions that have a
wrong version which looks right:

  * A capital is the MASK, not a synthetic Shift keycode. Hyprland's
    virtual keyboard never runs updateXkbStateWithKey, so a virtual
    KEY_LEFTSHIFT changes no modifier state at all -- and sending both
    is how a toolkit applies Shift twice.
  * A modifier is whatever the keymap says is one, measured by pressing
    each key in a throwaway xkb state. Not a name list: `@` on `de` is a
    level-three symbol, and a Shift-only special case types the wrong
    character. (The measured set is also smaller than the canonical one,
    because no keycode on us/pc105 carries Meta or Hyper.)
  * A lock is not a modifier. Caps_Lock reports a *locked* mask, so
    `type` refuses while it is held rather than guessing the case.

The whole string resolves before anything is emitted, and every refusal
names the scalar INDEX, never the character: these messages reach the
driver's log and the string is a password as often as not.

Folding in the review's changes 1, 2, 3 and 6:

  1 a Rejected now carries a `kind`. A bad keysym or an unmappable
    character is `invalid_argument`; a missing keyboard global is
    `refused`. Without the token the broker would have to tell exit 2
    from exit 10 by reading English, and _drive maps every `ok: false`
    to driver_refused today.
  2 the keymap `size` on the wire includes the trailing NUL, and the fd
    outlives a roundtrip rather than a flush. Hyprland mmaps exactly
    that many bytes and hands the pointer to xkb_keymap_new_from_string.
  3 release_all lifts buttons, then keys in press order, then zeroes the
    mask -- and the mask only if something set it, so a compositor with
    no keyboard global still gets its buttons lifted. One release_all is
    the whole of expiry; an exception in the key half would abandon it.
  6 `key` and `type` never call _aimed(). A keyboard has no output, and
    one test deliberately never warps so that stays true.

Also: `--xkb-layout/-model/-variant/-options`, compiled BEFORE any
Wayland call so a bad layout is exit 2 rather than exit 10; a comma in
the layout refused outright, because v1 always sends group 0 and
xkbcommon would hand back a second group nothing could reach; the
keymap uploaded after connect and before listen, with one
modifiers(0,0,0,0) after it; and xkbcommon as a hard, non-optional
dependency -- an optional one would let test_keymap.py skip, and the
unmappable-character path is the one that must not rot.

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

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

66 lines
2.7 KiB
Nix

{
description = "Stream a headless Hyprland session to a persistent Unix socket";
# Matches the nixpkgs this was developed against; consumers can override with
# inputs.nixpkgs.follows = "nixpkgs" and nothing breaks.
inputs.nixpkgs.url = "https://flakehub.com/f/NixOS/nixpkgs/0.1";
outputs = { self, nixpkgs, ... }: let
systems = [ "x86_64-linux" "aarch64-linux" ];
forAllSystems = f: nixpkgs.lib.genAttrs systems (system: f (import nixpkgs { inherit system; }));
# `checks` needs the system name as well as the package set, to reach
# self.packages.<system>; forAllSystems only hands over pkgs.
forAllSystems' = f: nixpkgs.lib.genAttrs systems (system:
f { inherit system; pkgs = import nixpkgs { inherit system; }; });
in {
packages = forAllSystems (pkgs: rec {
hhstream = pkgs.callPackage ./nix/package.nix {};
default = hhstream;
});
nixosModules = rec {
hyprland-headless-stream = import ./nix/module.nix;
default = hyprland-headless-stream;
};
# Unit tests + the two VM integration tests. See checks/default.nix and
# README.dev.md; the interface they assert is docs/CONTRACT.md.
checks = forAllSystems' ({ pkgs, system }:
import ./checks { inherit pkgs self system; });
devShells = forAllSystems (pkgs: {
default = pkgs.mkShell {
packages = with pkgs; [
python3
python3.pkgs.pytest
git
tmux
jq
hyprland
grim
ffmpeg
# The client side of the contract (hhstream-client), so a shell can
# 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.
python3.pkgs.websocket-client
# Something to *put on* the headless screen. Chromium is the only
# browser here that both runs on Wayland and can be driven over the
# DevTools protocol, which is how examples/agent-eyes-demo.py types
# into a page. Kept in the dev shell rather than installed globally.
chromium
];
shellHook = ''
export PYTHONPATH="$PWD/src''${PYTHONPATH:+:$PYTHONPATH}"
echo "hhstream dev shell -- python $(python3 --version 2>&1 | cut -d' ' -f2)"
'';
};
});
formatter = forAllSystems (pkgs: pkgs.alejandra);
};
}