Draft ext-input-triggers

[AlanGriffiths]

No description provided.

[Saviq]

I see this is still a draft, but just leaving some notes on it.

[tarek-y-ismail]

Activation part is mostly fine except handling oneshot/continuous actions, but I think registration still needs more discussion

[tarek-y-ismail]

A few minor nits, but I think it might be good enough for a quick spike.

[tarek-y-ismail]

So I used Copilot as a rubber duck, here's a quick "summary" of the points it brought up about the protocol and my opinions/responses. Apologies in advance for the wall of text.

---

Concrete protocol bug (must fix)

• enum name mismatch in register_modifier_tap_trigger
• Fix: change enum="modifier" to enum="modifiers" and/or rename arg to modifiers if you intend a bitfield (and document if multiple modifiers are allowed).

It's worth discussing whether we want to allow just one modifier in this request, or multiple ones. The use case I recall from when we discussed this was tapping both the left and right shifts to toggle mute, which would require us to specify two modifiers.

---

High priority semantic and security issues

1. Token/auth model is underspecified: token generation properties (entropy, unguessability), token format / length,

Tokens are mostly meant to be opaque strings similar to tokens used in ext_activation_v1.

2. No seat/device scoping (multi-seat/multi-device implications)

This is true. Do we want to take this into account for v1?

3. register_pointer_trigger takes edges but does not say whether edges are per-output, global screen-space, or per-monitor; it doesn’t accept an output id or bounding region.

I think we discussed this before. We settled on this being compositor-defined.

4. Lack of ownership/consumption semantics for captured input

• When a trigger is “done” and the manager “owns” it, the docs say “This client is now responsible for handling this input trigger.” That is vague:
  • Does the compositor stop delivering the underlying raw input events to normal clients?
  • Does the compositor synthesize events for the manager only (i.e., exclusive grab) or are events still delivered to applications?

We should clear this up. From memory, we decided that all inputs will be delivered to the focused client as usual. Once a registered trigger is invoked, that input will be consumed by the compositor and diverted to the listening client.

Implementation details: As @RAOF mentioned before, the modifier state will need to be reset by synthesizing events to clear the pressed modifiers so the focused client is not confused when focus returns to it.

Example, Ctrl + Shift + X. The focused client would get Ctrl, then Shift. If another app takes focus temporarily and the user lets go of the two modifiers before returning to the first app, then the app will still think the two modifiers are still down.

5. Concurrency and correlation of begin/update/end events
   • ext_input_trigger_action_v1 has begin, update, end events but no identifier to correlate multiple simultaneous activations for the same action token. The protocol doesn't forbid simultaneous activations; it doesn't state whether begin/end pairs are strictly nested or distinct, or whether multiple begins can be outstanding.

Is this even possible? Unless you have multiple input devices (keyboards / mice), I don't think it is.

6. Time/timestamp semantics unclear
   • Each event includes time (uint) "timestamp with millisecond granularity" but it doesn't state the epoch or clock reference (compositor monotonic clock? boot time?), wrap-around behavior, or whether the client should use it for ordering vs the Wayland event order.

I think we should specify this. For us, our clocks are usually relative to the UNIX epoch, right? I don't think we need to worry about wrap-around. And ordering of the events should match the Wayland event order so that's also a non-issue.

7. activation_token semantics and lifecycle are ambiguous
   • activation_token is a string described as “an xdg_activation token” but there’s no link to exact usage: should clients call xdg_activation_v1.activate with it? Is it optional/nullable? Who issues these tokens and when do they expire?

We should clear up the usage of the token. From the API, it's obviously not nullable/optional, so that's not a concern. We should specify that tokens are issued by the compositor and expire after a certain (compositor-defined) period of time.

Medium priority design omissions / missing error handling

8. Poor/few error codes and lack of failure reasons
   • ext_input_trigger_v1 has done/failed with no failure reason, and the action manager only has invalid_token as an error. There is no reason code taxonomy (e.g., conflict, unsupported capability, insufficient privileges, out of resources).

Maybe we want to explore this a bit. I believe we discussed the conflict case before and settled on leaving it up to the DE maintainers to handle conflicts between the various previliged clients externally. Though, this doesn't rule out the user modifying a trigger and accidentally using one that's already taken. Which in this case would just call failed. I'm not so sure about the other modes of failure.

9. Missing constraints, thresholds and configuration options for gestures
   • Touch drag/tap triggers have touches, direction, hold_delay, but no tolerances:
     • angle tolerance for "direction",
     • minimum/maximum movement distance to classify as drag vs tap,
     • inter-tap timeout for tap_count,
     • maximum finger spread or bounding box, velocity thresholds.
   • Result: different compositors may implement wildly different behavior; false positives/negatives are likely.

Again, I believe we discussed this before and agreed that it should be up to the compositor to define these to ensure a consistent experience.

10. Pointer trigger hysteresis and debouncing unspecified
    • For screen edge triggers: what counts as “pushed to the target edge(s)”? If a pointer is at x=1 pixel from edge, does that count? Without hysteresis, you can get flapping between begin/end as the pointer hovers near the edge.

Compositor defined, again.

11. register_keyboard_sym_trigger vs register_keyboard_code_trigger implications & layout issues
    • Using keysyms is layout-dependent; the semantics are currently “interpreted according to xkbcommon-keysyms.h” but there’s no guidance on how layout changes affect registered triggers, or whether triggers bind to physical key locations vs interpreted symbols (i.e., Ctrl+comma vs Ctrl+less).

I think Copilot got a bit confused, but this probably means we need to clarify things a bit. Code triggers should not change with the layout, but sym triggers should. Though the more I think about it, the more I see sym triggers as superfluous, what was their use case again?

12. Tap/hold semantics vagueness
    • register_modifier_hold_trigger and register_modifier_tap_trigger are underspecified: what exactly is a 'tap' (press+release within time/without movement), maximum allowed inter-key times for multi-taps, etc.

Fair point. I think this should also be compositor-defined to ensure consistency.

13. Lack of clarity about lifecycle interactions between cancel vs destroy
    • ext_input_trigger_action_control_v1 has cancel (destructor) making actions unavailable and destroy (destructor) that leaves created action objects unaffected. This is potentially confusing: documentation should explain use-cases for each and guarantee ordering semantics when clients hold existing ext_input_trigger_action_v1 objects.
    • Also, ext_input_trigger_action_manager_v1.get_input_trigger_action is supposed to emit unavailable if the token is no longer available — the relationship between cancel, destroy, and token invalidation needs to be clarified.

I agree with this. I confuse all three quite a bit.

Lower priority / niceties / improvements

14. Missing documentation about key repeat and update events
    • For keyboard triggers, how should repeated key events (auto-repeat) be treated? Should they produce update events? The document states begin on depression and end on change, but it should clarify how repeats are treated.

I just had to handle this in the spike. I don't have a use case in mind where repeat would be that useful, so I believe we should specify that it's should not emit update events.

15. progress fixed type precision and range
    • progress is a Wayland fixed normalized to [0.0, 1.0]. It’s good to specify whether values must be clamped, whether 1.0 must be sent before end, and how to interpret fractional precision (Wayland fixed is 16.16 usually — but calling out the expected precision is helpful).

Fair point, my opinion at the moment is that 1.0 must be sent.

16. No means to enumerate current triggers or query which triggers belong to an action
    • Once you create an action and add triggers, there is no introspection API to list them later. This can make debugging and synchronization complex.

Again, I remember that we agreed that this should not be a part of these two protocols.

17. No way to attach metadata to tokens or actions
    • name is a free-form description but there’s no capability for richer metadata / display name / icon that the compositor might show to users. Consider allowing optional metadata.

This might be a minor issue for applications that want to show button icons instead of Ctrl + Shift + C, but I don't believe it's a major issue at the moment.

18. Unclear how gloves/virtual keyboard input is handled
    • Not critical, but worth mentioning: the protocol assumes physical devices; if applications synthesize input, should synthesized events trigger global actions?

I don't think virtual devices or OSKs should trigger global actions.

19. Documentation comments in XML mention “This protocol allows for a privileged Wayland client” but the actual interface offers no way for the compositor/ecosystem to differentiate privileged vs normal clients. You must define how compositors expose these globals (e.g., only to trusted clients) and how clients obtain the global.

We talked about this before as well. "Priviliged clients" can mean clients launched explicitly by the compositor. In which case we would advertise the globals. Otherwise, we don't.

[tarek-y-ismail]

Fair point, my opinion at the moment is that 1.0 must be sent.

Thinking about this again, maybe this isn't the best idea as it might introduce some unwanted jank. For example, if a user is moving to the right workspace via a gesture, the DE might have a threshold of 0.5 progress after which the move is done whether the gesture is cancelled or not. Requiring compositors to send 1.0 will just introduce complexity as they'll have to handle and ignore sudden jumps in progress.

[Saviq]

I think we decided against introducing that (yet)?

[tarek-y-ismail]

Yeah that was shorty after I updated the PR. Haven't gotten around to it again, sorry

[github-actions]

TICS Quality Gate

✔️ Passed

No changed files applicable for TICS analysis quality gating.

TICS / TICS / Run TICS analysis