Commit Graph
8 Commits
Author SHA1 Message Date
Hermenix 994fdb1cfb Merge keyboard input (feat/keyboard-input @561e0c2) for a live trial on this machine
The same shape as the merge that branch got on 2026-10-05 (edbf15f on
feat/session-live-stream): this machine's own config sets
`sessions.keyboard.layout`, so a ref without the keyboard work does not
evaluate -- and the point of this branch is to be consumed here.

The stream branch's own commit is the first parent, so PR #2 stays based on
main and carries none of this merge. Conflicts were additive on both sides
(new option blocks, new checks, new README rows) and are resolved by keeping
both.
2026-10-11 02:23:11 +00:00
Hermenix 7141900070 module: declare the stream's port, and the one hole it needs
`sessions.stream { port, bind, openFirewall }` -- the piece of stage 3 that
does not need the broker. It exists because a machine had to be able to *reach*
a stream before the rest of the app is settled: the operator asked for the port
to be open on the deployment machine, where the app still runs by hand, and a
bare `networking.firewall.allowedTCPPorts` line in one machine's config is the
wrong place for a fact about this flake.

- `openFirewall` defaults false and is deliberately not implied by
  `sessions.enable`: a live view of the desktop is readable by anyone who can
  reach the port, the phrase in the URL is its only credential, and there is no
  TLS. It opens exactly one port -- the one the option names.
- `bind` defaults to loopback and is *checked*: `openFirewall = true` beside a
  loopback bind is refused, because that is a hole with no service behind it.
- `checks/vm-stream-firewall.nix` boots the module with a configured port that
  is not the module's default, puts listeners on that port and on a neighbour,
  and asserts from a second machine on the same VLAN that the peer reaches the
  configured port and is refused on the other -- while both answer on loopback
  inside the guest, so the refusal is the firewall's doing and not an empty
  socket. The peer is a second machine because a probe from the test driver
  proves nothing: the driver is not on the test VLAN.

Nothing here turns a stream on -- no unit, no phrases, no `session stream`
verbs, which stay stage 2+3 -- and docs/plans/2026-10-04-session-stream-webapp.md
now records which part of its stage 3 landed and why out of order.
2026-10-11 02:22:00 +00:00
HermenixandClaude Opus 5 19338af17c fix(live): a phrase is four plain words and a tail, and nothing weaker
Two holes in the one credential a stream has.

The wordlist has four hyphenated entries (`drop-down`, `felt-tip`,
`t-shirt`, `yo-yo`). A phrase drawn from one is six tokens --
`abacus-drop-down-lantern-harbor-7k2qp` -- and a listener cannot hear where
the tail starts. `words()` now keeps only `^[a-z]+$`; 7772 words costs
0.003 bits, so the ~77.5-bit figure is unchanged. The shape test asserted
over 50 draws, which caught this about a tenth of the time; the property is
now asserted over the whole list.

`validate` accepted `a-b-c`. It is what an operator-supplied `--phrase` is
checked against, so everything it accepts is a password someone can choose
for a LAN-facing stream. The floor is now exactly what `generate` produces:
four `[a-z]{3,}` words and a five-character `[a-z0-9]` tail. The router
still looks phrases up without validating, so an unknown phrase is the same
empty 404 it was.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01URhyHGQnmKH9zBXxoznfQY
2026-10-06 16:19:41 +00:00
Hermenix 9744d35945 feat(live): one port, a router, and a phrase per session (stage 1)
The session-stream web app: a single HTTP listener (9988) that serves a page
per enabled session, keyed by a spoken phrase. Off by default, so a stream
exists only for the sessions it was enabled on.

  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. Transport is MJPEG (multipart/x-mixed-replace), reusing
the JPEG grim already produces. Not yet wired to the broker -- that is
stage 2. Tests: tests/live (51).
2026-10-06 13:32:00 +00:00
HermenixandClaude Opus 5 561e0c28f5 Stage 2 fixes: the two tests the review named, and the docs drift
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
2026-10-05 04:43:56 +00:00
HermenixandClaude Opus 5 b1f2744cf0 Stage 0 review: correct what the log does not say, and edit the plan
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
2026-10-04 03:46:53 +00:00
HermenixandClaude Opus 5 d07a1fd045 docs(plan): fold in the independent review of the keyboard plan
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
2026-10-04 03:21:01 +00:00
Hermenix 14b3f691c4 docs(plan): keyboard input for sessions — approach and open questions 2026-10-03 23:55:44 +00:00