Files
hyprland-headless-stream-pl…/docs/TODO/pointer-needs-a-container-or-a-screen.md
T
Hermenix 336474793f docs: the pointer is unusable while containers are off
Found live while trying to demonstrate the scroll verb that was just deployed:
every cursor verb resolves its target through _pointer_output, which requires a
container output, and no session has one -- because containers are off. So the
verb exists and cannot be used, and the acceptance video's missing cursor was
never a capture artefact: nothing could have moved it.

Recorded with the routes out (aim at the shared output when a session owns no
container; or fix the binding first and leave this alone), the cost of the
quick one, and the misleading hint that blames the compositor for a switched-off
feature.
2026-10-03 19:19:24 +00:00

3.5 KiB

The pointer is unusable whenever containers are off

The issue

Every pointer verb — acquire, move, click, scroll — resolves its target through SessionManager._pointer_output, which returns the session's container output and refuses with no_container if there is none. Containers are off on the deployment machine (see containers-do-not-bind), so no session has a container output, so no cursor can be moved at all.

That is why the acceptance video showed no cursor: not a capture artefact, not a missing beat — nothing could have moved it. Verified live:

$ hhstream session pointer acquire foot-7xrsyi --json
{"ok": false, "error": "no_container", "id": "foot-7xrsyi",
 "container": {"state": "degraded", "output": null, ...},
 "reason": "session foot-7xrsyi has no container output to aim at",
 "hint": "the compositor was unreachable when this session started; ..."}

The refusal itself is deliberate and worth keeping: as the code says, aiming at "wherever the cursor is" is how a click lands in another session's window. The defect is that the refusal is the only behaviour available in the configuration we actually run, and that its hint blames the compositor when the cause is a switched-off feature — the same confusion the container host was fixed to avoid at its own layer.

Ideas

  1. Aim at the shared output when a session owns no container. (recommended) With containers off there is one screen, so "the session's output" is that screen; the broker can ask the compositor which output is primary (it already has an IPC client and a CompositorTarget independent of the container host) and aim the lease at it. Small, and it restores the pre-container semantics without weakening the refusal for the case where the compositor genuinely cannot be reached.
  2. Fix the container binding first, then leave this alone. The pid-join route in containers-do-not-bind gives each session a real output, and the pointer's per-session isolation comes back with it — but it is the larger change, and until it lands the pointer stays dead.
  3. Both, in that order — (1) to unblock the current machine, (2) as the real fix. What (1) costs: with one shared output, the lease still serialises order between sessions but can no longer prevent one session's click landing over another's window. That is already the documented advisory state; it would need saying out loud rather than being implied.
  4. Correct the hint regardless of which route is chosen. It should name the reason it can actually see ("this session has no container output — containers are switched off"), because a wrong cause in an error message is worse than no hint: it sends the reader to a compositor that was never broken.

Why it matters

This is the difference between a feature that exists and one that can be used. scroll was implemented, unit-tested, merged and deployed to this machine — and it still cannot scroll anything, because the layer underneath refuses to aim. A whole class of work (cursor movement, clicks, scrolling, the acceptance video that depends on them) is blocked by a configuration choice made for an unrelated reason, and the error message points at the wrong suspect.

It is also a reminder about the shape of this system: the pointer, the containers and the compositor are one dependency chain, and the part that was switched off is upstream of the part being demonstrated. Anything verified only in the enabled configuration says nothing about the one that runs.