The session-stream web app: a single HTTP listener (9988) that serves a page
per enabled session, keyed by a spoken phrase.
src/hhstream_live/phrase.py four EFF-large words + a 5-char base-36 tail
(~77.5 bits); the phrase is the password
src/hhstream_live/publisher.py one capture thread + one frame slot per
output, one slot/no queue, capture paused at
zero viewers
src/hhstream_live/server.py the router: /, /<phrase>/, /stream.mjpg,
/frame.jpg, /status.json; unknown phrase is
an empty 404, rate-limited
src/hhstream_live/pages.py the built-in dark pages (no CDN, no build)
src/hhstream_live/__main__.py hhstream-live serve|phrase, standalone
The root page is a form, never a list: the phrase is known only by whoever
enabled the stream. Tests: tests/live (51), all green with the full suite
(958). Not yet wired to the broker -- that is stage 2.
From docs/reviews/2026-10-04-stage2-3-review.md (Stage 3 done; Stage 2
done-with-fixes). Its findings 1, 2, 3 and 5, which it called the only
things standing before merge.
(A) REPLAY, THROUGH THE SINK. What existed was
`test_every_keyboard_verb_is_cached_for_the_same_reason`, which
asserts the two verbs are in MUTATING_VERBS -- and the verification
doc had already named that as the false pass: "asserting
`deduplicated` and not the sink. A handler that types and then sets
the flag stays green." Two integration tests now, modelled on
`test_a_retried_click_with_the_same_request_id_clicks_once`:
test_a_retried_type_with_the_same_request_id_types_once
`keyboard.type` of "ab" twice with request_id="retry-me".
Asserts `deduplicated`, chars == 2 on both, and that the sink
still has exactly 4 key events -- two characters, a down and an
up each -- so a replay that typed again is caught by the count
and not by the flag.
test_a_retried_unmappable_type_stays_refused_and_types_nothing
`café` twice with one id. Both refusals are `invalid_argument`,
the second carries `deduplicated` (a recorded failure is
replayed as the failure it was), and the sink is empty after
both -- there is no partial type on either call.
Mutation-checked rather than assumed: removing `keyboard.key` and
`keyboard.type` from MUTATING_VERBS fails both.
(B) KILL, THROUGH kill(). `test_killing_the_holder_lifts_its_keys` calls
`_drop_lease_for` directly, so it proves that helper lifts keys and
says nothing about whether `kill` still calls it. The integration
kill test now holds `Shift_L` before the kill and asserts the SINK
saw `("key", 42, 0)` and `("modifiers", 0, 0, 0, 0)` -- the lease
forgetting a key is not the compositor being told it came up, and
only the second matters to the application. Code 42 because `type`
never emits it, so the release cannot be a leftover.
Mutation-checked: stubbing out the `_drop_lease_for` call in
`kill()` fails it. Before this it stayed green.
(C) DOCS. The plan's stage table and risk paragraph still said acquire
is one warp and that `focuswindow` was unbuilt Stage 4 work. The
contract (v3 §4) describes what shipped; the plan did not. Rewritten
so they agree, and the plan now says outright that the contract wins
where they differ:
* risk 1 marked RESOLVED, describing the two warps, the pinned
`follow_mouse_threshold`, and `focuswindow` as the
nudge-failure fallback selecting on `address:` (not
`stable_id`, which is not a Hyprland selector)
* Stage 3 marked Done; Stage 4 struck as not existing -- the
answer to Stage 0 was the second warp, not a focus dispatch
* the top banner, the §5 VM assertion list and open question 2
no longer say "one warp"
* verification §B3 subtest 1 amended: it is a live assertion
rather than an expected red, and the check additionally requires
`focus == "warp"` so the fallback is not accepted as success
Also amended one sentence the review did not list, because leaving
it would contradict the edit above inside the same document:
verification §"Warp does not guarantee wl_keyboard.enter" predicted
`focuswindow` was "likely mandatory". It was not; the second warp
was.
Written down rather than smoothed over: the `focuswindow` branch
itself has no test, and if both mechanisms fail acquire still
returns ok with `focus="none"` -- a lease whose first key may go to
the previously focused window.
(D) The tap docstring claimed the `up` is sent even if the `down` was
refused after sending. The next lines return early on `not ok`, and
that early return is right: a refusal means the key was never
pressed, so an `up` would ask the compositor to release something it
never had. Sentence replaced with why the early return is correct
and what actually covers a lost reply (the broker's `release_all`,
not the CLI, which cannot know whether the request arrived).
Not done, and not claimed: findings 4, 6 and 7 (the broker chord test
checking first/last mask rather than the key; the at-cap test not
looking at the sink; the module-defaults test being a substring match).
The review rates all three as not holes in the claim, and the driver
tests are the locks for the first two.
nix develop -c python -m pytest tests -q
907 passed in 67.71s
nix develop -c python -m pytest tests/pointer tests/sessions/unit -q
605 passed in 27.16s
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GhNPM6rGcuzxocM1nATnuM
The Stage 0 review (docs/reviews/2026-10-04-stage0-review.md, verdict
yes-with-fixes) found that the measurements were sound and the write-up
was not. All four of its high and medium defects, verified against the
committed transcript before fixing:
(1) 19e484b's README claimed a verbatim excerpt and printed serial=336
while the run's (a2) enter was serial 371. It also claimed six
reproductions with one transcript, and cited a `keys=[42, 0, 0, 0]`
enter from a run whose log was never kept -- every enter in the
committed file is `keys=[]`. The excerpt is now copied from the log
with line numbers to check it against, the reproduction claim is
gone, and the Shift observation is named as not-in-this-log.
(2) THE (a) CONCLUSION WAS WRONG, and it is the one that matters. The
first idle warp onto the unfocused window gave wl_pointer.enter and
NO keyboard enter; the leave/enter arrived on the LATER motion. So
it is not "enter, one warp late" -- the first warp's delta is set to
0, the threshold is 0.0, and the second motion's own non-zero delta
is what focused. Two corollaries the old text got backwards: a
second warp to the SAME point returns before mouseMoveUnified
touches the delta and proves nothing, and waiting longer does not
help. The probe now prints both targets and the measured gap
(0.401s) instead of hardcoding the word "immediately", and its
ANSWER string says the mechanism.
Consequence, now stated everywhere it belongs: `pointer acquire` is
one warp, so the first key of a lease can land on whatever was
already focused. Stage 3's enter subtest must not be designed from
acquire's single warp, and must not be made to pass by warping twice
to the same bookmark.
(3) d07a1fd did not edit the plan -- `git diff 14b3f69 HEAD --
docs/plans/2026-10-03-keyboard-input.md` was empty, so anyone told
to follow the plan still had the contradicted text. All eight
pre-code changes are now folded into that file, each marked
[SUPERSEDED], plus a banner at the top. Changes 5 and 7 were the
ones that had survived intact in four places: the [keyboard] TOML
table (dropped -- the broker reads that file and the driver is a
different unit, so it would have been a setting with no effect) and
"if it repeats, the help text says so" (now unconditional). The four
closed open questions and the stage table are updated with what
Stage 0 measured, including that Stage 4 is no longer contingent.
(4) mask_cleared=no was reported as a held mask surviving destroy. The
held key was a letter, so the mask was 0 throughout; the README now
says destroy emitted no key-up and no modifiers event, and that the
reason release_all still sends modifiers(0,0,0,0) is
VirtualKeyboard.cpp's releasePressed, not this line. The real
poison evidence is promoted: onKeyboardKey drops a release whose
code is not in m_pressed, so the cleanup's `key code=30 state=0`
arriving from a brand-new keyboard proves 30 was still in that set.
The transcript is a fresh run of the corrected probe, so the file and
the claims about it agree line for line.
19e484b's message carries defect (2)'s wrong causality. It is corrected
here rather than by rewriting that commit, so the hashes the reviewer
cites keep resolving.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GhNPM6rGcuzxocM1nATnuM
An adversarial read of 2026-10-03-keyboard-input.md against this tree and
against Hyprland v0.56.2. Its verdict is "safe to build on, not safe to
implement as written", and its §"Changes required before code" is the list
Stages 0-2 are built to rather than the original plan where the two differ:
1 exit 2 vs driver_refused -- _drive maps every `ok: false` to
driver_refused (exit 10), so the plan's "exit 2 for a bad keysym"
needs a token the broker can map to invalid_argument
2 the keymap `size` must include the trailing NUL
3 release_all must no-op its key half with no keyboard object, and
must end with modifiers(0, 0, 0, 0)
4 input:virtualkeyboard:release_pressed_on_close defaults to false
5 the layout reaches the keymap only as --xkb-layout on the driver
unit; a [keyboard] table in the broker TOML would be a false pass
6 the modifier-keysym set has to be written down; no Shift special case
7 Stage 0 expectations, including a two-window probe
8 acquire's stderr, and an index rather than the string in logs
It also writes the test specs for Stages 1-3, including the false pass
beside each assertion, which is the part the unit tests are written from.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GhNPM6rGcuzxocM1nATnuM
The operator rejected the port-range/token shape: a single port (9988) with
a router, four routes per session output, and a spoken phrase as the key.
Streams are opt-in per session (default off) and capture only while watched.
Phrase is four EFF-large words (~51.6 bits); index is loopback-only by
default. Supersedes 2026-10-03-network-stream.md.