Files
hyprland-headless-stream-pl…/docs/TODO/scroll-has-no-compositor-proof.md
T
HermenixandClaude Opus 5 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>
2026-10-03 19:05:39 +00:00

2.7 KiB

Scrolling works, but nothing proves it against a real compositor

The issue

hhstream session pointer scroll <id> --amount N now exists end to end: CLI → pointer.scroll → the lease check → driver axis op → zwlr_virtual_pointer_v1.axis(time, axis, value) → frame. Validation is covered by unit tests, and the lease behaviour matches the other gestures.

What is not covered is the half that matters: no test scrolls a real application on a real compositor. The vm-pointer gate has no axis case, and the fake compositor can only prove the wiring — that the broker said the right thing to the driver, not that a window moved.

Also unproven, and worth knowing before trusting it: whether an app on a headless output honours a bare axis event at all. GTK and Chromium smooth-scrolling both look at axis_source and axis_discrete, which the driver does not send today. If they are required, the symptom will be a scroll that silently does nothing — indistinguishable from a page that would not move.

Ideas

  1. An axis case in vm-pointer that reads the app's own state. (recommended) Scroll a real app and assert its state changed, not the pixels — the contract already sets this bar for clicks ("verified by reading the app's own state"). A foot running a script that appends a line on scroll, or a page whose scroll offset the app can report, keeps the assertion honest.
  2. Send axis_source and axis_discrete alongside axis if (1) shows the event arriving and the app ignoring it. Small, confined to the driver's axis op.
  3. Keep the direction convention in one place. Positive vertical is down and positive horizontal is right, per the protocol. It is documented in hhstream_pointer/buttons.py and mirrored in the CLI's AXES — if a third copy ever appears, that is the point to notice, because two vocabularies over one sign is how a scroll ends up backwards.
  4. A live check on this machine, not only in a VM. The video that prompted this work is a real scroll on a real app; making that reproducible as a command (like examples/proof-video.py) is worth as much as the VM case.

Why it matters

An unimplemented feature is honest; a plausible one is not. A scroll that does nothing, a scroll that goes the wrong way, and a scroll the app ignores all present as "the page would not move", and all three would be found by a human watching a video — which is not a test.

This is the same shape as the bug that made foot exit 230 with every test green: the tests exercised what was built, and the built thing was fine, and the app exited anyway. Anything whose acceptance proof runs through a real window needs a real window in the test.