887ed17be2e4fb34c44a23b116da30e813df3e9e
5
Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
|
|
0f2810afaa |
docs(sessions)!: sessions-v4, the per-session live stream
`docs/CONTRACT-sessions.md` goes to sessions-v4 with a change table at the top, for the reason mcp-v2 got one: everything in it is an addition, and a reader who learned v3 should be told what moved rather than diff it. The new §3.5 is the interface that needed freezing most, because it is the only one in this build that two *processes* have to agree on: `/run/hhstream/live.sock`, `LiveStreams.attach/detach/list/viewers`, the four JSON ops on the wire, and the `Attachment` the broker gets back. Its shape is §3.4's deliberately -- the broker holds the decision (which session streams, under which phrase), the daemon holds the capture -- so a reader who knows the pointer driver already knows this. Four rules in §3.5 are written out because each one is a thing a reasonable implementation would get wrong: * the daemon holds no session state and no idle clock; `viewers` is a reading, and what the broker does with it is the broker's; * `fps` is optional and omitting it is normal -- the default is the daemon's, from its own unit's argv, for the same reason the port is. A broker that sent its own default on every attach would turn `sessions.stream.fps` into a setting that changed nothing, which is the failure `--xkb-layout` exists to avoid; * `attach` is idempotent on the phrase, so a re-`enable` after a broker restart does not double the `grim` rate on one output; * the phrase is never logged by either side. It is the stream's only credential. §4 gains four verbs, the three `start` arguments, and the one genuinely new rule in this version: **a connected viewer is activity**. That is the first exception to "`touch` is the only mark of activity" since that rule was written, and it is there for one failure -- an operator watching a long job on his phone, saying nothing to the broker, and losing the session at three hours *because* watching was all he was doing. It cannot hold a session open by itself: an enabled stream with no viewer runs no `grim` and stamps nothing. No new exit numbers. The three error names map onto codes the frozen table already has (`stream_unavailable` -> 10, `stream_busy` -> 8, `stream_budget` -> 6), because no new *kind* of failure appeared: no container output is a compositor-side failure, a phrase collision is a busy, a viewer cap is a budget. §6 records schema 3 -> 4 (the record gains `stream`, older records migrate to `null`), and §5 names the socket, the unit and port 9988 beside the other frozen paths. What v4 deliberately withholds from the broker is the port, the bind address and the capture command. The broker learns the URL prefix *from* the daemon, in the `attach` reply -- a URL it assembled itself from a port it was told about once is a URL that lies the first time an operator moves the listener. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011ZeH65zd6pFTgBSu52W9PE |
||
|
|
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
|
||
|
|
6b395305e0 |
scroll: one verb, two axes, and the sign carries the direction
A session could move a cursor and press it, but not scroll. The protocol already had the request -- zwlr_virtual_pointer_v1.axis(time, axis, value) -- it had simply never been implemented, in the driver or the broker. hhstream session pointer scroll <id> --axis vertical --amount 3 Positive is down (vertical) or right (horizontal): the protocol's direction, not a choice of ours, which is why direction travels in the sign and there is deliberately no up/down vocabulary layered over it. The output is whatever the last warp aimed at, exactly like a button, so scrolling somewhere else is a warp first -- and the lease is what keeps the whole gesture atomic. Bounded at 100 wheel clicks per request on both sides, because a decimal-point slip should be a refusal rather than a session scrolled somewhere unrecoverable. The resume point is re-stamped, not moved: the cursor did not go anywhere, so the coordinates are re-affirmed and only the stamp advances. Recorded in the contract as an amendment to the frozen op set, because adding an op to a frozen interface should be visible rather than implied. Co-authored-by: Claude Opus 5 <noreply@anthropic.com> |
||
|
|
e8b3855a05 |
move every live default to /run/hypr-stream, and resolve the slices' contract gaps
Slice A renamed the runtime directory in the module, but the old path was still live in the code and checks it does not own, so the VM gates pointed at a directory the module no longer creates. This moves the 21 remaining live occurrences (client/server defaults, the unit tests that pin them, all three VM checks, the diagnostics script, both READMEs) and deliberately leaves the three mentions that are history rather than configuration: the plan's problem statement, module.nix's note about the previous name, and cli.py's explanation for spelling its default out. Also here: docs/CONTRACT-sessions.md is now v2 with every gap the four slices reported resolved as a decision (Monitor.id, stable_id, pid -1, Event.data, mark(), the quarantine argv type, the corrected wlr XML path, and the state dir/frame socket rows), and docs/CONTRACT.md is v2 because its documented socket default moved -- wire format unchanged. Two comments that stated the old, wrong diagnosis (a 'misnamed' IPC socket) now state the measured one: the event socket did not fit in sun_path. |
||
|
|
98374b8457 |
docs: the plan for workspaces and pointer input, and the frozen sessions contract
The plan is the researched design (one compositor, one output+workspace per session, serialised output-bound pointer input under a lease). The contract is the freeze point for a parallel build: file ownership per slice, the exact Python seams, the wire format, and the names and paths nobody may invent. Kept separate from docs/CONTRACT.md, which governs the frame socket and is untouched by this work. |