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:
1 parent
d0efba0877
commit
6b395305e0
17 files changed
+642
-2
No files matched your search
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
Reference in new issue
Block a user