Implement relative pointer mode on Wayland

yasl_surface_set_pointer_mode(YASL_POINTER_RELATIVE) now takes a
persistent zwp_locked_pointer_v1 on the surface and hides its cursor.
While the compositor keeps the lock engaged, zwp_relative_pointer_v1
motion is pushed as POINTER_MOTION with pos frozen and delta in device
pixels. When the lock disengages, as on focus loss, motion is absolute
again with a delta derived by the input queue.

The lock follows the pointer's seat: it moves to another seat when its
seat loses the pointer, and is released on NORMAL and on surface
destruction. Compositors without both protocols return false.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

6 files changed, 155 insertions, 3 deletions

diff --git a/src/platform/wayland/api.h b/src/platform/wayland/api.h
index aabc182..e5e933e 100644
--- a/src/platform/wayland/api.h
+++ b/src/platform/wayland/api.h
@@ -29,6 +29,7 @@ bool wayland_surface_poll_event(struct wayland_surface *s, struct yasl_event *ev
 struct yasl_geometry wayland_surface_geometry(const struct wayland_surface *s);
 struct yasl_timing wayland_surface_timing(const struct wayland_surface *s);
 void wayland_surface_set_cursor(struct wayland_surface *s, enum yasl_cursor cursor);
+bool wayland_surface_set_pointer_mode(struct wayland_surface *s, enum yasl_pointer_mode mode);
 void wayland_surface_set_background_color(struct wayland_surface *s, uint32_t bg);
 bool wayland_surface_ime_preedit_cursor(const struct wayland_surface *s, int *begin, int *end);
 void wayland_surface_set_ime_caret(struct wayland_surface *s, struct yasl_rect2i caret);
diff --git a/src/platform/wayland/backend.c b/src/platform/wayland/backend.c
index 1d83ec6..c3c7bed 100644
--- a/src/platform/wayland/backend.c
+++ b/src/platform/wayland/backend.c
@@ -126,6 +126,11 @@ static void impl_surface_set_cursor(struct yasl_surface *s, enum yasl_cursor cur
     wayland_surface_set_cursor((struct wayland_surface *)s, cursor);
 }
 
+static bool impl_surface_set_pointer_mode(struct yasl_surface *s, enum yasl_pointer_mode mode)
+{
+    return wayland_surface_set_pointer_mode((struct wayland_surface *)s, mode);
+}
+
 static void impl_surface_set_background_color(struct yasl_surface *s, uint32_t bg)
 {
     wayland_surface_set_background_color((struct wayland_surface *)s, bg);
@@ -206,6 +211,7 @@ const struct yasl_backend_ops yasl_wayland_backend = {
     .surface_schedule_redraw = impl_surface_schedule_redraw,
     .surface_present = impl_surface_present,
     .surface_poll_event = impl_surface_poll_event,
+    .surface_set_pointer_mode = impl_surface_set_pointer_mode,
     .surface_geometry = impl_surface_geometry,
     .surface_timing = impl_surface_timing,
     .surface_frame_time_ns = impl_surface_frame_time_ns,
diff --git a/src/platform/wayland/internal.h b/src/platform/wayland/internal.h
index d619dba..c35db7f 100644
--- a/src/platform/wayland/internal.h
+++ b/src/platform/wayland/internal.h
@@ -23,6 +23,8 @@
 #include "protocols/commit-timing-v1-client-protocol.h"
 #include "protocols/xdg-toplevel-drag-v1-client-protocol.h"
 #include "protocols/primary-selection-unstable-v1-client-protocol.h"
+#include "protocols/relative-pointer-unstable-v1-client-protocol.h"
+#include "protocols/pointer-constraints-unstable-v1-client-protocol.h"
 
 #include <fcntl.h>
 #include <limits.h>
@@ -131,6 +133,7 @@ struct seat {
     struct wl_pointer *pointer;
     struct wl_touch *touch;
     struct wp_cursor_shape_device_v1 *cursor_shape_dev;
+    struct zwp_relative_pointer_v1 *relative_pointer;
     struct wl_surface *cursor_surface;
     struct wp_viewport *cursor_viewport;
     struct zwp_tablet_seat_v2 *tablet_seat;
@@ -212,6 +215,8 @@ struct wayland_display {
     struct wl_data_device_manager *data_manager;
     struct zwp_primary_selection_device_manager_v1 *primary_selection_mgr;
     struct wp_cursor_shape_manager_v1 *cursor_shape_mgr;
+    struct zwp_relative_pointer_manager_v1 *relative_pointer_mgr;
+    struct zwp_pointer_constraints_v1 *pointer_constraints;
     struct wl_cursor_theme *cursor_theme;
     const char *cursor_theme_name;
     struct zwp_tablet_manager_v2 *tablet_mgr;
@@ -275,6 +280,9 @@ struct wayland_surface {
     struct wp_fifo_v1 *fifo;
     struct wp_commit_timer_v1 *commit_timer;
     struct wl_callback *frame_cb;
+    /* Persistent lock held while relative; lock_seat owns the locked wl_pointer. */
+    struct zwp_locked_pointer_v1 *pointer_lock;
+    struct seat *lock_seat;
     const struct yasl_window_cbs *cbs;
     void *ud;
     uint64_t frames_skipped;
@@ -316,6 +324,8 @@ struct wayland_surface {
     bool destroyed;
     bool opaque;
     bool want_draw;
+    bool relative;
+    bool pointer_locked;
 };
 
 
@@ -388,6 +398,7 @@ int  seat_modifiers(const struct seat *s);
 void surface_init_cursor(struct wayland_display *c);
 void seat_destroy_tablet(struct seat *s);
 void seat_pointer_reset(struct seat *s);
+void surface_unlock_pointer(struct wayland_surface *w);
 
 extern const struct zwp_text_input_v3_listener text_input_listener;
 void ime_reset(struct wayland_surface *w);
diff --git a/src/platform/wayland/pointer.c b/src/platform/wayland/pointer.c
index 83f6e2f..cdc5780 100644
--- a/src/platform/wayland/pointer.c
+++ b/src/platform/wayland/pointer.c
@@ -152,8 +152,10 @@ static uint32_t cursor_shape_of(enum yasl_cursor shape)
     }
 }
 
-static void seat_set_cursor(struct seat *s, struct wayland_surface *w, enum yasl_cursor shape)
+/* Relative mode hides the pointer but keeps w->cursor for the return to NORMAL. */
+static void seat_set_cursor(struct seat *s, struct wayland_surface *w)
 {
+    enum yasl_cursor shape = w->relative ? YASL_CURSOR_HIDDEN : w->cursor;
     if (!s->pointer || !s->pointer_serial || s->pointer_focus != w ||
         s->cursor_shape == (int)shape)
         return;
@@ -183,7 +185,7 @@ void wayland_surface_set_cursor(struct wayland_surface *w, enum yasl_cursor shap
     if (!w || !w->conn || w->destroyed || (unsigned)shape > YASL_CURSOR_HIDDEN) return;
     w->cursor = shape;
     for (struct seat *s = w->conn->seats; s; s = s->next) {
-        seat_set_cursor(s, w, shape);
+        seat_set_cursor(s, w);
         if (s->tool && s->tablet_focus == w)
             tool_set_cursor(s->tool, shape);
     }
@@ -279,7 +281,7 @@ static void pointer_enter(void *data, struct wl_pointer *pointer,
     s->pointer_pos = device_from_fixed(w, surface_x, surface_y);
     s->pointer_serial = serial;
     s->cursor_shape = -1;
-    seat_set_cursor(s, w, w->cursor);
+    seat_set_cursor(s, w);
     s->motion_pending = true;
     pointer_event_done(s);
 }
@@ -448,6 +450,105 @@ static void pointer_axis_relative_direction(void *data, struct wl_pointer *point
 static void pointer_warp(void *data, struct wl_pointer *pointer, wl_fixed_t x, wl_fixed_t y)
 { (void)data; (void)pointer; (void)x; (void)y; }
 
+static void relative_motion(void *data, struct zwp_relative_pointer_v1 *pointer,
+        uint32_t utime_hi, uint32_t utime_lo, wl_fixed_t dx, wl_fixed_t dy,
+        wl_fixed_t dx_unaccel, wl_fixed_t dy_unaccel)
+{
+    (void)pointer; (void)utime_hi; (void)utime_lo; (void)dx_unaccel; (void)dy_unaccel;
+    struct seat *s = data;
+    struct wayland_surface *w = s->pointer_focus;
+    /* Unlocked movement arrives as wl_pointer.motion; the queue derives its delta. */
+    if (!w || !w->pointer_locked || w->lock_seat != s) return;
+    flush_pending_motion(s, w);
+    push_pointer(s, w, YASL_EVENT_POINTER_MOTION, (struct yasl_pointer_event){
+        .pos = s->pointer_pos,
+        .delta = {wl_fixed_to_double(dx) * w->scale_factor,
+                  wl_fixed_to_double(dy) * w->scale_factor},
+    });
+}
+
+static const struct zwp_relative_pointer_v1_listener relative_pointer_listener = {
+    .relative_motion = relative_motion,
+};
+
+static void pointer_locked(void *data, struct zwp_locked_pointer_v1 *lock)
+{
+    (void)lock;
+    struct wayland_surface *w = data;
+    w->pointer_locked = true;
+    surface_root(w)->input.relative = true;
+}
+
+static void pointer_unlocked(void *data, struct zwp_locked_pointer_v1 *lock)
+{
+    (void)lock;
+    struct wayland_surface *w = data;
+    w->pointer_locked = false;
+    surface_root(w)->input.relative = false;
+}
+
+static const struct zwp_locked_pointer_v1_listener locked_pointer_listener = {
+    .locked = pointer_locked,
+    .unlocked = pointer_unlocked,
+};
+
+/* A persistent lock re-engages each time the compositor focuses the surface. */
+static void surface_lock_pointer(struct wayland_surface *w, struct seat *s)
+{
+    struct wayland_display *c = w->conn;
+    if (!w->relative || w->pointer_lock || w->destroyed || !s->pointer)
+        return;
+    w->pointer_lock = zwp_pointer_constraints_v1_lock_pointer(c->pointer_constraints,
+            w->surface, s->pointer, NULL, ZWP_POINTER_CONSTRAINTS_V1_LIFETIME_PERSISTENT);
+    if (!w->pointer_lock)
+        return;
+    w->lock_seat = s;
+    zwp_locked_pointer_v1_add_listener(w->pointer_lock, &locked_pointer_listener, w);
+}
+
+void surface_unlock_pointer(struct wayland_surface *w)
+{
+    if (!w->pointer_lock)
+        return;
+    zwp_locked_pointer_v1_destroy(w->pointer_lock);
+    w->pointer_lock = NULL;
+    w->lock_seat = NULL;
+    if (w->pointer_locked) {
+        w->pointer_locked = false;
+        surface_root(w)->input.relative = false;
+    }
+}
+
+static void seat_lock_surfaces(struct seat *s)
+{
+    for (struct wayland_surface *w = s->conn->surfaces; w; w = w->conn_next)
+        surface_lock_pointer(w, s);
+}
+
+bool wayland_surface_set_pointer_mode(struct wayland_surface *w, enum yasl_pointer_mode mode)
+{
+    if (!w || !w->conn || w->destroyed)
+        return false;
+    struct wayland_display *c = w->conn;
+    bool relative = mode == YASL_POINTER_RELATIVE;
+    if (relative && (!c->relative_pointer_mgr || !c->pointer_constraints))
+        return false;
+    w->relative = relative;
+    if (relative) {
+        /* Prefer the seat that last delivered input; others lock once it goes away. */
+        struct seat *seat = c->active_seat && c->active_seat->pointer ? c->active_seat : NULL;
+        for (struct seat *s = c->seats; s && !seat; s = s->next)
+            if (s->pointer) seat = s;
+        if (seat)
+            surface_lock_pointer(w, seat);
+    } else {
+        surface_unlock_pointer(w);
+    }
+    for (struct seat *s = c->seats; s; s = s->next)
+        seat_set_cursor(s, w);
+    return true;
+}
+
 static const struct wl_pointer_listener pointer_listener = {
     .axis_relative_direction = pointer_axis_relative_direction,
     .warp = pointer_warp,
@@ -984,6 +1085,18 @@ void seat_clipboard_ensure(struct seat *s)
 
 static void seat_drop_pointer(struct seat *s)
 {
+    struct wayland_display *c = s->conn;
+    bool unlocked = false;
+    for (struct wayland_surface *w = c->surfaces; w; w = w->conn_next) {
+        if (w->lock_seat == s) {
+            surface_unlock_pointer(w);
+            unlocked = true;
+        }
+    }
+    if (s->relative_pointer) {
+        zwp_relative_pointer_v1_destroy(s->relative_pointer);
+        s->relative_pointer = NULL;
+    }
     if (s->cursor_shape_dev) {
         wp_cursor_shape_device_v1_destroy(s->cursor_shape_dev);
         s->cursor_shape_dev = NULL;
@@ -998,6 +1111,9 @@ static void seat_drop_pointer(struct seat *s)
     seat_pointer_reset(s);
     s->pointer_focus = s->ptr_left = NULL;
     s->ptr_presses.n = 0;
+    for (struct seat *o = c->seats; unlocked && o; o = o->next)
+        if (o != s && o->pointer)
+            seat_lock_surfaces(o);
 }
 
 static void seat_drop_keyboard(struct seat *s)
@@ -1057,6 +1173,15 @@ static void seat_capabilities(void *data, struct wl_seat *proxy, uint32_t caps)
             if (s->pointer && c->cursor_shape_mgr)
                 s->cursor_shape_dev = wp_cursor_shape_manager_v1_get_pointer(
                         c->cursor_shape_mgr, s->pointer);
+            if (s->pointer && c->relative_pointer_mgr) {
+                s->relative_pointer = zwp_relative_pointer_manager_v1_get_relative_pointer(
+                        c->relative_pointer_mgr, s->pointer);
+                if (s->relative_pointer)
+                    zwp_relative_pointer_v1_add_listener(s->relative_pointer,
+                            &relative_pointer_listener, s);
+            }
+            if (s->pointer)
+                seat_lock_surfaces(s);
         }
     } else if (s->pointer) {
         seat_drop_pointer(s);
diff --git a/src/platform/wayland/shell.c b/src/platform/wayland/shell.c
index 92c89d1..a12bd4d 100644
--- a/src/platform/wayland/shell.c
+++ b/src/platform/wayland/shell.c
@@ -208,6 +208,12 @@ static void registry_global(void *data, struct wl_registry *registry,
     } else if (strcmp(interface, wp_cursor_shape_manager_v1_interface.name) == 0) {
         c->cursor_shape_mgr = wl_registry_bind(registry, name,
                 &wp_cursor_shape_manager_v1_interface, 1);
+    } else if (strcmp(interface, zwp_relative_pointer_manager_v1_interface.name) == 0) {
+        c->relative_pointer_mgr = wl_registry_bind(registry, name,
+                &zwp_relative_pointer_manager_v1_interface, 1);
+    } else if (strcmp(interface, zwp_pointer_constraints_v1_interface.name) == 0) {
+        c->pointer_constraints = wl_registry_bind(registry, name,
+                &zwp_pointer_constraints_v1_interface, 1);
     } else if (strcmp(interface, wp_fractional_scale_manager_v1_interface.name) == 0) {
         c->scale_mgr = wl_registry_bind(registry, name,
                 &wp_fractional_scale_manager_v1_interface, 1);
diff --git a/src/platform/wayland/surface.c b/src/platform/wayland/surface.c
index ad3a24c..b17d203 100644
--- a/src/platform/wayland/surface.c
+++ b/src/platform/wayland/surface.c
@@ -200,6 +200,8 @@ static void display_free(struct wayland_display *c)
     if (c->primary_selection_mgr) zwp_primary_selection_device_manager_v1_destroy(c->primary_selection_mgr);
     if (c->data_manager) wl_data_device_manager_destroy(c->data_manager);
     if (c->cursor_shape_mgr) wp_cursor_shape_manager_v1_destroy(c->cursor_shape_mgr);
+    if (c->relative_pointer_mgr) zwp_relative_pointer_manager_v1_destroy(c->relative_pointer_mgr);
+    if (c->pointer_constraints) zwp_pointer_constraints_v1_destroy(c->pointer_constraints);
     if (c->cursor_theme) wl_cursor_theme_destroy(c->cursor_theme);
     if (c->tablet_mgr) zwp_tablet_manager_v2_destroy(c->tablet_mgr);
     if (c->text_input_mgr) zwp_text_input_manager_v3_destroy(c->text_input_mgr);
@@ -399,6 +401,7 @@ void wayland_surface_destroy(struct wayland_surface *w)
     if (!w || w->destroyed) return;
     for (struct wayland_surface *o = w->conn ? w->conn->surfaces : NULL; o; o = o->conn_next)
         assert(o->parent != w && "destroy a popup before its parent");
+    surface_unlock_pointer(w);
     input_queue_clear(&w->input);
     free(w->ime_preedit);
     free(w->ime_commit);