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
32 KiB
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
-
High.
keydropsaction.mask, so any keysym above level 0 is sent as the bare key.keymap.pyresolve_name("A")returns(code=30, mask=1)andresolve_text("@")ondereturns(code=16, mask=128), which isISO_Level3_Shift's bit, not Shift._op_typeuses that mask (ops.py:315, mask before the down/up, restored after)._op_keydoes not. On down it sendsaction.codeand then, only ifis_modifier(name),modifier_mask(ops.py:261-266).Aandatare not modifiers, so the calls arekey(30, pressed)andkey(16, pressed)with nomodifiersat all. Confirmed by running the dispatcher:{"op":"key","key":"A"}produces[("key", 30, 1)];{"op":"key","key":"at"}ondeproduces[("key", 16, 1)]. The plan'sNAMElist includesA(2026-10-03-keyboard-input.mdCLI block). Stage 2'skeyboard key/down/upas a thin wrapper of this op will type the level-0 character. Stage 3'skeyboard typeassertion stays green while that is true, becausetypeis the path that was tested (tests/pointer/test_ops.py:513-527).The same hole aliases two names onto one evdev code.
down Athendown arecords both names and sendskey(30, pressed)twice. Hyprland drops the second press (m_pressedalready contains 30).release_allthen 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, ifaction.maskis non-zero, sendmodifiers(baseline | action.mask)before the down and restore the baseline on the matching up — the one-charactertypesequence — and refuse a second held name whose evdev code is already down,kind=invalid_argument. Do not storeaction.maskin_keysas the contribution: that field means "what this key adds", andtypetreats a zero contribution as "non-modifier, refuse".Shift_Lmust stay key-then-mask; the tests attest_ops.py:481-486lock that order, and it is the other path on purpose. -
High. The comment says Hyprland releases keys on destroy. The conf file does not.
__main__.py:186-193says SIGKILL is safe becausenix/hyprland-conf.nixsetsinput:virtualkeyboard:release_pressed_on_close. Inf931858that file'sinputblock isfollow_mouse = 1and nothing else (nix/hyprland-conf.nix:81-94). The verification's change 4 was "required before code" because the default is 0 andreleasePressedemits key-ups only when the option is true: akill -9leaves the code in the seat'sm_pressed, and the next driver's down of that code is ignored. The clean path is fine —_lift_everythingcallsrelease_all, andrelease_alldoes 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 whymodifiers(0,…)stays). Delete the claim from__main__.pyuntil the line exists. This is not optional follow-up: it is the difference between a killed driver and a key that stays dead. -
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, writestext.encode("utf-8") + b"\0", passesformat=XKB_V1(1) andlen(payload),_sync()s, and only thenos.closes the fd. python-xkbcommon 1.5.1'sget_as_bytesdefaults toXKB_KEYMAP_FORMAT_TEXT_V1andffi.stringstrips the NUL, so the extra byte is exactly one terminator, not two. Forus/pc105that size is 35572.__main__.py:155-173calls it once, afterconnect, and returns exit 10 onCompositorUnavailablebeforelisten.typenever calls it.Nothing asserts any of that.
test_the_keymap_object_is_built_once_and_reused_across_types(test_keymap.py:279-293) checksdispatcher._keymap is us. The sink has nokeymapmethod. The verification named this false pass: a backend that uploads on everytypestays green.test_a_usable_layout_gets_as_far_as_the_compositor(test_driver_flags.py:128-138) raises atconnect, so upload, the NUL, format 1, and "before listen" are never reached. Amainthat 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 unconnectedWaylandSinkand checks the flag is false. AconnectthatManagerTooOlds when the keyboard global is missing stays green.Cheapest fix: one test with a sink whose
connectsucceeds and whoseupload_keymaprecords(text, caller). Assertmaincalls it once, with a payload whose last byte is NUL and whose length islen(text.encode()) + 1, and thatserveis what runs next — injectlistenso it does not need a socket. A second test callsupload_keymapon a fake keyboard object and assertskeymap(1, fd, size)seessize == len(payload)whilefdstill reads back the bytes. Do not assert only thatkeymap.pyreturns equal strings. -
Low.
keyup forgets the name before the send, unlikebutton._op_keypops_keysand then callssink.key(ops.py:275-276)._op_buttonupdates_pressedonly after the send (ops.py:198-203). A raise from the up —KeyboardUnavailableis caught in__main__.py:211-214and the process stays up — leaves_keysempty while the compositor still has the code down.release_allwill not repeat the up. Confirmed with a sink that raises onstate=0: after a failedShift_Lup the held set is[]and_mask_touchedis still true, so the nextrelease_allsendsmodifiers(0,…)and no key-up. Not reachable today unless the keyboard object disappears between down and up (closeis the only thing that clears it, and it runs after the lift). Cheapest fix: pop after a successful send, same order as the button. -
Low. Two layouts xkbcommon accepts are not the layout the caller named.
CONTROL_KEYSYMSmaps\rtoReturn(keymap.py:67). The plan's C0 rule exempts\nand\tonly;\ris aReturnand not a refusal. Andbuild(layout="")does not raise: xkbcommon compiles it asxkb_symbols "pc_us_inet(evdev)", the same keymap asus. 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\rfromCONTROL_KEYSYMS, and reject an empty layout inbuild()next to the comma check.
Not defects, checked because they look like them:
- Shift is not hardcoded.
Aonusis evdev 30 and mask1 << mod_get_index("Shift")(index 0, so 1).de@is evdev 16 and mask 128, equal tomodifier_mask("ISO_Level3_Shift"), not equal to Shift.type "@"emitsmodifiers(128), key(16, down), key(16, up), modifiers(0,…)and no code 42. Control's contribution is 4 (index 2). The measured modifier set onus/pc105is exactlyEXPECTED_MODIFIERS; Meta and Hyper are absent because no key produces them. Locks areCaps_LockandNum_Lock, andtypewhile either is held emits nothing. - Unmappable means no events.
resolve_text("xéy")raisesUnknownKeywithscalar 1 (U+00E9)and neither the character nor the string. The dispatcher callsresolve_textbefore 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 whatresolve_textcompares (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_keymapreturn beforecreate_virtual_keyboard(backend.py:221-226).has_keyboard()stays false.key/typeanswerkind: refused(ops.py:391-396).release_allsends key-ups only when_keysis non-empty andmodifiers(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 realuskeymap 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()onkeyortype, notouch.frameremains the pointer op.release_allstill frames pointer outputs and does not add one for keys (ops.py:343-344, locked bytest_ops.py:667-683). There is notouchin 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 iskind: "refused". A bad layout is process exit 2 beforeWaylandSinkis constructed (__main__.py:132-141,keymap.py:144-153). Upload failure is exit 10 and does notlisten(__main__.py:155-164). The committed broker does not readkind. 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 callsdispatch focuswindow.typewith no prior warp emits keys (test_ops.py:420-432).pointer acquireis 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 as 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 as, same three checks |
|
test_the_keymap_object_is_built_once_… |
two types 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.
-
{"op":"key","key":"A"}does not typeA. Neither doesatonde, or any other keysym whose producing mask is non-zero.typedoes, and it ORs that mask with the baseline of keys that are actually modifiers.keyboard key/down/upmust not be "send the name through unchanged" until finding 1 is fixed, and a VM check that only runskeyboard typewill not catch it.aandAare two held names for evdev 30.Caps_Lockdown sends the key and never a locked mask;typethen refuses. Do not document Caps as capitalization. -
kinddoes not survive the broker client, and every refusal is exit 10.PointerDriver._exchangeraisesDriverRejectedfromreply["error"]and drops everything else (src/hhstreamd/driver.py:158-159atf931858)._drivemaps everyDriverRejectedtodriver_refused(manager.py:2047). A Stage 2 test that asserts exit 2 foréfails, or it passes by reading the English. Readkindoff the JSON before that conversion and mapinvalid_argumentto exit 2. Leaverefusedas exit 10. The 4096 check lives only inresolve_text. A broker check oflen(text.encode())disagrees with it on the emoji case the driver already got right.Rejectedtext carries an index; do not logtext, and do not put it onkeyboard_type. -
Do not design the enter subtest, the unit argv, or
kill -9from the comments in__main__.py.pointer acquireis still one warp (manager.py_warp, unchanged in this commit) and Stage 0's (a1) did not deliverwl_keyboard.enter. A second warp to the same floored pixel is not the fix.nix/module.nixdoes not pass--xkb-layout; the flag defaults tous, so the running unit typesusuntil 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_closeis not set, whatever__main__.py:191-193says.upload_keymapis 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 returnsLeaseInfowith no keys (pointer.py:178-196)._expire_pointerreadspressed()and notkeys_pressed()(manager.py:1857). Read the keys first. The driver's onerelease_allis what lifts them; do not addrelease_all_keys.- The committed
PointerDriver.release_allreturns the button list only (driver.pyrelease_all), and_release_all_buttonsdoeslist(lifted)(manager.py:2058-2061). The new reply field islifted_keysbesidelifted. Changing the client method to return a tuple without updating thatlist()turns the button names into the two lists. pressed()on the client still returns buttons only. The reply now also haskeys. Do not widen the return ofpressed()in place.keyboard.keyandkeyboard.typeare not inMUTATING_VERBS.pointer.statemust stay out of it. No keyboard verb callstouch. Acquire's stderr still says "pointer" only; akeyboard.*verb that goes through_refreshmoves the deadline, and the help text has to say so.CONTRACT-sessions.md§3.4 is still the two-flag command line and apressed/release_allwith 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 grepoff931858for 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
f931858inherited it. This commit does not cite it. The parent commit's README did.b1f2744rewrites 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=nois not a held Shift.backend.py:246-250citestests/README-keyboard-probe.mdfor "destroy does not clear the modifier mask". The send ofmodifiers(0,0,0,0)after upload is right anyway —releasePressednever emits modifiers — but the citation is the sentence Stage 0 said the log does not support. The cleanupstate=0for code 30 is the poison evidence, and it is why finding 2 is not theoretical.- The Hyprland XML, kept on purpose.
regenerate.pysays wayland-protocols has novirtual-keyboarddirectory in this nixpkgs and vendors Hyprland's copy, which nameskeymap_formatandkey_stateand defines neither.XKB_V1 = 1andbuttons.STATESare 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, norulesflag,evdevhardcoded). The unit argv is not. The driver half of 8 is done (index andU+codepoint, and the server does not log the request line). Acquire's stderr is untouched. Change 7 (the probe's expectations, the unconditionalkeyboard downwarning) is not this stage; the warning has nowhere to live until the CLI exists, and it is still unconditional when it does. xkbcommonis a hard dependency (pyproject.toml,nix/package.nix). Leave it that way. An optional one letstest_keymap.pyskip, and the unmappable path is the one that rots.