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

51 lines
2.7 KiB
Markdown

# 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.