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

+54
View File
@@ -302,6 +302,14 @@ def _build_namespace(parser: argparse.ArgumentParser) -> None:
#: and this list only buys a typo an exit 2 instead of an exit 10.
BUTTONS = ("left", "right", "middle", "side", "extra", "forward", "back", "task")
#: Axis names the driver knows (``hhstream_pointer.buttons.AXES``), mirrored for
#: the same reason and with the same caveat: the driver remains the authority.
#: Direction is the sign of the amount, so there is deliberately no "down" or
#: "up" here -- the protocol fixes positive as down (vertical) and right
#: (horizontal), and a second vocabulary over it is how a scroll ends up
#: backwards.
AXES = ("vertical", "horizontal")
def _build_pointer(verbs: Any, common: argparse.ArgumentParser) -> None:
"""``session pointer <verb>`` — the one cursor, under a lease (PLAN §6).
@@ -409,6 +417,29 @@ def _build_pointer(verbs: Any, common: argparse.ArgumentParser) -> None:
"--button", default="left", choices=BUTTONS, metavar="B", help=_button_help()
)
scroll = with_lease(add_gesture(
"scroll",
_cmd_pointer_scroll,
help="scroll the session's screen where the cursor is",
description=(
"Scroll the session's screen. --amount is signed wheel clicks: "
"positive scrolls down (vertical) or right (horizontal), which is "
"the protocol's direction rather than a choice of ours. The cursor "
"does not move, so the resume point keeps its coordinates -- but it "
"is re-stamped, because a scroll is the session acting and a later "
"resume should know when it last did."
),
))
scroll.add_argument("id", help="session id")
scroll.add_argument(
"--axis", default="vertical", choices=AXES, metavar="A",
help="vertical (default) or horizontal",
)
scroll.add_argument(
"--amount", type=float, default=3.0, metavar="N",
help="wheel clicks, signed; positive is down/right (default: 3)",
)
for name, state in (("down", "down"), ("up", "up")):
sub = with_lease(add_gesture(
name,
@@ -951,6 +982,29 @@ def _cmd_pointer_click(args: argparse.Namespace) -> int:
return _finish_gesture(args, reply, render, args.id)
@_guard
def _cmd_pointer_scroll(args: argparse.Namespace) -> int:
lease_id = _lease_of(args, args.id)
if not lease_id:
return _no_lease(args, args.id)
reply = _request(
args,
"pointer.scroll",
id=args.id,
lease_id=lease_id,
axis=args.axis,
amount=args.amount,
)
def render(r: dict[str, Any]) -> str:
return (
f"{r.get('id')}: scrolled {r.get('axis')} by {r.get('amount')} "
f"at {fmt.render_bookmark(r.get('bookmark'))}"
)
return _finish_gesture(args, reply, render, args.id)
@_guard
def _cmd_pointer_button(args: argparse.Namespace) -> int:
lease_id = _lease_of(args, args.id)