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>
This commit is contained in:
HermenixandClaude Opus 5 committed 2026-10-03 19:05:39 +00:00
1 parent d0efba0877
commit 6b395305e0
17 files changed
+642 -2

No files matched your search

+11
View File
@@ -83,6 +83,17 @@ class PointerDriver:
def button(self, button: str, state: str) -> None:
self.request({"op": "button", "button": button, "state": state})
def axis(self, axis_name: str, value: float) -> None:
"""Scroll the aimed output by ``value`` wheel clicks along ``axis_name``.
Positive vertical is down, positive horizontal is right (the protocol's
direction). The output is whatever the last ``warp`` aimed at, so a
scroll into another session is a warp first -- which is also what the
lease serialises.
"""
self.request({"op": "axis", "axis": axis_name, "value": float(value)})
def frame(self) -> None:
"""Commit what was queued. Nothing the driver was sent is delivered
to the compositor until this, so every gesture ends with one."""
+73
View File
@@ -116,6 +116,12 @@ DEFAULT_CONTAINER_SLOTS = 4
#: and "click 10000 times" is not a gesture.
MAX_CLICK_COUNT = 3
#: The largest scroll one request may carry, in wheel clicks. The driver
#: enforces the same ceiling with its own copy (they are separate processes and
#: neither imports the other); this one exists so the broker refuses early with a
#: message naming the caller's value rather than relaying the driver's.
MAX_SCROLL_AMOUNT = 100.0
SIGNALS_BY_NAME = {
"TERM": signal.SIGTERM,
"SIGTERM": signal.SIGTERM,
@@ -1658,6 +1664,44 @@ class SessionManager:
"bookmark": self._restore_point(session, output),
}
async def pointer_scroll(
self, session_id: str, lease_id: str, axis: Any = "vertical", amount: Any = 3
) -> dict[str, Any]:
"""Scroll the session's screen.
Same shape as a click -- the lease is checked first, then the driver is
told, then the resume point is re-stamped -- with one difference that is
worth being precise about: **the cursor does not move**. The
coordinates are therefore re-affirmed rather than changed. The stamp
advances, because a scroll is the session acting and a later resume
should know when it last did -- but not one pixel of the position
changes, and a bookmark that claimed otherwise would be fiction.
"""
session, output = await self._refresh(session_id, lease_id)
name = _axis_name(axis if axis is not None else "vertical")
clicks = _checked_amount(amount)
await self._drive("axis", name, clicks)
await self._drive("frame")
# A bookmark from a container this session no longer has is not a
# position in this one, so a missing or stale one falls back to the
# centre that the acquire would have aimed at.
known = self._restore_point(session, output) or {}
mark = self._mark(
session,
lease_id,
output,
float(known.get("x", 0.5)),
float(known.get("y", 0.5)),
)
self.audit.emit("pointer_scroll", session=session.id, axis=name, amount=clicks)
return {
"id": session.id,
"axis": name,
"amount": clicks,
"bookmark": mark,
}
async def pointer_release(self, session_id: str, lease_id: str) -> dict[str, Any]:
"""Give the cursor back, leaving nothing pressed and a bookmark behind."""
@@ -2079,6 +2123,35 @@ def _button_name(value: Any) -> str:
return value
def _axis_name(value: Any) -> str:
if not isinstance(value, str) or not value:
raise ManagerError("invalid_argument", f"axis must be a name, got {value!r}")
return value
def _checked_amount(value: Any) -> float:
"""A scroll amount in wheel clicks, signed.
Signed rather than split into `--up`/`--down`: the protocol carries direction
in the sign (positive vertical is down), and a second vocabulary on top of it
is how a scroll ends up backwards. Zero is refused because it is never
intended -- it is a caller that forgot to pass an amount.
"""
if isinstance(value, bool) or not isinstance(value, (int, float)):
raise ManagerError(
"invalid_argument", f"amount must be a number of wheel clicks, got {value!r}"
)
amount = float(value)
if amount == 0 or abs(amount) > MAX_SCROLL_AMOUNT:
raise ManagerError(
"invalid_argument",
f"amount must be non-zero and at most {MAX_SCROLL_AMOUNT:g} wheel clicks, "
f"got {amount}",
)
return amount
def _checked_count(value: Any) -> int:
if isinstance(value, bool) or not isinstance(value, int):
raise ManagerError("invalid_argument", f"count must be an integer, got {value!r}")
+2
View File
@@ -148,6 +148,7 @@ VERBS = (
"pointer.move",
"pointer.button",
"pointer.click",
"pointer.scroll",
"pointer.release",
"pointer.state",
)
@@ -171,6 +172,7 @@ MUTATING_VERBS = frozenset(
"pointer.move",
"pointer.button",
"pointer.click",
"pointer.scroll",
"pointer.release",
}
)
+13
View File
@@ -70,6 +70,7 @@ class ControlServer:
"pointer.move": self._op_pointer_move,
"pointer.button": self._op_pointer_button,
"pointer.click": self._op_pointer_click,
"pointer.scroll": self._op_pointer_scroll,
"pointer.release": self._op_pointer_release,
"pointer.state": self._op_pointer_state,
}
@@ -356,6 +357,18 @@ class ControlServer:
)
)
async def _op_pointer_scroll(
self, request: dict[str, Any], caller: dict[str, Any]
) -> dict[str, Any]:
return protocol.ok(
**await self.manager.pointer_scroll(
request.get("id"),
request.get("lease_id"),
request.get("axis", "vertical"),
request.get("amount", 3),
)
)
async def _op_pointer_release(
self, request: dict[str, Any], caller: dict[str, Any]
) -> dict[str, Any]: