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

+13
View File
@@ -278,11 +278,24 @@ blocked driver must not stall the broker.
```json
{"op": "warp", "output": "hh-x", "x": 0.42, "y": 0.61} -> {"ok": true}
{"op": "button", "button": "left", "state": "down"} -> {"ok": true}
{"op": "axis", "axis": "vertical", "value": 3.0} -> {"ok": true}
{"op": "frame"} -> {"ok": true}
{"op": "pressed"} -> {"ok": true, "buttons": ["left"]}
{"op": "release_all"} -> {"ok": true, "lifted": ["left"]}
```
**Amended after the freeze — `axis`, for scrolling.** Added to the op set above
and to the broker's verbs as `pointer.scroll`. Positive vertical is *down* and
positive horizontal is *right*: the protocol's direction, not a choice of ours,
and the reason there is no `up`/`down` vocabulary layered over it. The output is
whatever the last `warp` aimed at, exactly like `button`, so scrolling somewhere
else is a warp first — which is what keeps the whole gesture atomic under the
lease. The magnitude is bounded at 100 wheel clicks per request, in both the
driver and the broker, because a decimal-point slip should be a refusal rather
than a session scrolled somewhere unrecoverable. Unit tests cover validation and
the lease; a real-compositor case is still missing — see
`docs/TODO/scroll-has-no-compositor-proof.md`.
`{"ok": false, "error": "<text>"}` for anything rejected. The driver holds **no
lease state** — the broker owns the lease; the driver is an executor that must
never be trusted to serialise anything.
+24
View File
@@ -0,0 +1,24 @@
# TODO
Known, unfixed problems — each one real, none of them guessed at.
Each file answers three questions and stops:
- **The issue** — what is actually wrong, with the evidence for it.
- **Ideas** — more than one, and which one is the recommended route.
- **Why it matters** — the impact, not the principle.
| item | severity | state |
| --- | --- | --- |
| [containers-do-not-bind](containers-do-not-bind.md) | high | containers built, tested, **switched off** in production |
| [scroll-has-no-compositor-proof](scroll-has-no-compositor-proof.md) | medium | implemented; unit-tested; unproven against a real compositor |
| [cursor-visibility-in-captures](cursor-visibility-in-captures.md) | medium | unverified — the acceptance video shows no cursor |
| [reconcile-while-containers-are-off](reconcile-while-containers-are-off.md) | medium | worked around by restarting the compositor |
Severity here means "how much of the feature is actually delivered", not
"how loud the failure is". The high one is high because a working feature is
turned off; the others are medium because they are gaps in proof, where the
symptom of a real fault and the symptom of a working thing look identical.
When one of these is fixed, delete its file and the row — this folder is a list
of what is still true, not a history of what was thought.
+54
View File
@@ -0,0 +1,54 @@
# Containers are built, tested, and switched off
## The issue
A session can be given its own container — its own headless output and a
numbered workspace — but **no window can be assigned to it**.
The broker stamps an identity on each session's app and matches a windowrule on
`match:initial_class`, on the assumption that an allowlisted app will carry that
stamp. None of them does: chromium reaches the compositor through a wrapper
script whose flags do not set a per-session class, and `foot` has no such
option. Every allowlisted app therefore lands in the *base* class set, the
broker judges it foreign to every container, and quarantines it.
The consequence is that enabling containers makes sessions unusable — which is
how this was found: not in tests, but live, immediately after the first switch
that enabled them. Containers are now off
(`containers_enabled = false`), and every session reports
`container: {state: "degraded", output: null}`, deliberately, so a disabled
machine cannot be mistaken for one whose compositor is down.
## Ideas
1. **Adopt windows by the pid the compositor already reports.** *(recommended)*
`hyprctl clients -j` gives each client's pid, and the broker already knows each
session's pid — so the join is a lookup, and **no app has to take part**. No
stamp, no per-app flags, and it works for programs that will never co-operate.
It must use `(pid, starttime)` rather than pid alone, because the wrapper
replaces its own argv and that is exactly the pid-reuse confusion already
fixed once in `procmon`.
2. **Per-app identity argument, where one exists.** chromium accepts
`--class=hh-<id>`, so the wrapper could pass the session's value. Cheap for
chromium, and dead weight for every other app: it makes the allowlist a list of
apps that cooperate.
3. **Keep the stamp, set it in each wrapper.** Same shape as (2), more moving
parts, same ceiling.
4. **Hybrid: pid first, stamp as a fallback.** Only worth it if some app reports
no pid at all; the compositor's `-1` sentinel for "absent pid" already covers
the reporting side.
## Why it matters
The isolation milestone does not deliver while this is open. Sessions still
share one output and tile over each other on the same screen — two concurrent
sessions are both `ready` and both visible at once. Per-session ownership today
is bookkeeping only: a runtime directory, an idle clock, captured output, an
audit trail.
So the difference between what the design claims ("a session owns a workspace")
and what the machine does ("a session is an app on a shared screen") is entirely
this one join. And note which failure mode to expect on the way: the *first*
half of the feature — creating outputs and workspaces — worked on the first
attempt and looked fine right up until an app was put in one. A green container
test proves the compositor accepted the commands, not that anything arrived.
@@ -0,0 +1,53 @@
# The cursor may not appear in captures at all
## The issue
The acceptance video shows the browser searching, opening listings in separate
tabs, and a terminal running cowsay — and **no cursor anywhere**. Two candidate
causes, and they are not exclusive:
1. **The demo never moved it.** The browser beats were driven over Chromium's
CDP HTTP endpoints (`/json/new`, `/json/activate`, navigation), which inject
no pointer input at all. Nothing moved the cursor because nothing was asked
to. This part is a gap in the demo, not in the machine, and it is now
fixable: `pointer.move` warps the real cursor.
2. **A headless capture may not include the cursor image.** The compositor
normally draws the cursor as its own plane, on top of the scene, so a buffer
read back from the output can legitimately contain everything except the
pointer. Whether that is what happens here has **not been checked**.
Which one it is decides the fix, so the first step is to find out rather than
pick.
## Ideas
1. **Check before changing anything.** *(recommended)* Start a session, warp the
pointer to a known point with `pointer.move`, take a `shot`, and look —
once with the pointer parked in a corner and once beside it. One comparison
separates the two causes.
2. **If the cursor is missing from the buffer, force software cursors** in the
compositor configuration (`cursor { no_hardware_cursors = true }`). That draws
the cursor into the scene, so it lands in the capture, at the cost of a redraw
per frame — the same cost this box already pays, since there is no GPU and
rendering is software anyway. Worth measuring rather than assuming.
3. **Verify motion without pixels, for tests.** `hyprctl cursorpos` answers on
this build, so a test can assert *where* the cursor is without any image at
all. That belongs in the gates; (2) is only for the human eye.
4. **Last resort: a synthetic marker** drawn by the driver. Honest only if it is
labelled as an overlay — it proves the driver thinks the cursor is at (x, y),
which is not the same claim as the compositor putting it there.
## Why it matters
The point of moving a pointer is to act somewhere visible. If the cursor cannot
be seen in the artifact the operator is shown, then the acceptance proof for all
input work is missing, and the failure it hides is specifically the one that
matters: **a click on the wrong element looks exactly like a click on the right
one.** Both produce a screen that changed; neither shows where it happened.
There is a second-order cost too. Everything learned about the cursor — that the
compositor remembers no position per-device, that `motion_absolute` speaks
output-normalised coordinates, that a bookmark has to live in the session
record — was hard-won and is all invisible in a video with no cursor in it. The
operator cannot check any of it. That is a documentation problem the video was
supposed to solve.
@@ -0,0 +1,48 @@
# Cleanup depends on the feature it is cleaning up after
## The issue
Start-up reconciliation for stray `hh-*` outputs lives inside the container
host, so it runs **only when containers are enabled**. Turning containers off
therefore also turned off the broker's ability to see what it had already left
on the compositor.
That is not theoretical: an output created while the feature was on survived the
rollback switch. With containers off, nothing reconciled it, and the frame
capture stayed **2560×720 instead of 1280×720** — the extra width being the
orphan sitting beside the real one. The symptom is a *capture* problem, which is
where it would be looked for, and it was fixed by restarting the compositor,
which drops every session.
## Ideas
1. **Reconcile always, not conditionally.** *(recommended)* On start-up, list the
compositor's outputs, find `hh-*` ones that no live session owns, and remove
them — regardless of whether containers are enabled. "Disabled" should mean
*create none*, not *leave the machine as it was found*.
2. **Never start a session onto an unowned output.** If a leftover is found that
cannot be removed, refuse to place a session on it rather than silently
sharing it — the ambiguity is what makes the capture width unexplainable.
3. **Record removals in the audit trail.** The `hyprctl output remove` calls are
already logged individually; a reconcile pass that removes three outputs
should say so once, with the names, so a later "why is my screen narrower"
has an answer.
4. **Make it a check.** A VM case that creates a container, disables the feature,
and asserts the output is gone — the rollback path deserves the same gate as
the forward path, because it is the one that runs when something is already
wrong.
## Why it matters
A feature that cannot be turned off safely is worse than one that was never
turned on, and this one fails asymmetrically: the *forward* path is tested
(containers are created and torn down in `vm-sessions` and `vm-containers`),
while the *rollback* path was never exercised before it was needed. That is
precisely when it is used.
It also cost a compositor restart — the bluntest tool available, and one that
kills every session — to clean up a state the broker itself had created and
could no longer see. The general rule worth keeping: **teardown code belongs
outside the thing being torn down**, or there will be exactly one configuration
where it does not run, and it will be the configuration you are in when you
need it.
@@ -0,0 +1,50 @@
# 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.