Unify core and runner events into struct yasl_event

The core input queue and the yasl_run() runner each had their own event
type, and the runner translated one into the other. Both now share
struct yasl_event in <yasl/yasl.h>: yasl_surface_poll_event() returns the
same events the app event callback receives, so the runner forwards them
unchanged.

Pointer input becomes POINTER_DOWN/UP/MOTION/SCROLL/LEAVE with a named
yasl_pointer_button and a motion delta computed in the input queue. TEXT,
PASTE and DROP share one text payload, scale changes fold into
WINDOW_RESIZE, and every event carries a monotonic time_ns.
yasl_surface_set_mouse_mode() is replaced by
yasl_surface_set_pointer_mode(); no backend implements relative mode yet.

The export check now only counts YASL_API declarations, so function
pointer fields returning enum yasl_app_result are not mistaken for
exports.

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

1 files changed, 111 insertions, 82 deletions

diff --git a/include/yasl/yasl.h b/include/yasl/yasl.h
index 3b3b712..22ed308 100644
--- a/include/yasl/yasl.h
+++ b/include/yasl/yasl.h
@@ -282,15 +282,6 @@ enum yasl_mod : uint32_t {
     YASL_MOD_CAPS  = 1 << 4, /**< Caps Lock modifier. */
 };
 
-/** Pointer transition or motion type; fields are meaningful according to this tag. */
-enum yasl_pointer_kind {
-    YASL_PTR_PRESS, /**< Button/tip pressed. */
-    YASL_PTR_RELEASE, /**< Button/tip released. */
-    YASL_PTR_MOTION, /**< Position or tablet axes changed. */
-    YASL_PTR_LEAVE, /**< Pointer/tool left the surface. */
-    YASL_PTR_SCROLL, /**< Scroll sample. */
-};
-
 /** Pointer source class; capability support does not imply an attached device. */
 enum yasl_pointer_device {
     YASL_PTR_DEV_MOUSE, /**< Mouse or trackpad pointer. */
@@ -299,6 +290,24 @@ enum yasl_pointer_device {
     YASL_PTR_DEV_ERASER, /**< Tablet eraser tool. */
 };
 
+/** Pointer button; meaningful only for POINTER_DOWN and POINTER_UP. */
+enum yasl_pointer_button {
+    YASL_BUTTON_PRIMARY = 0, /**< Left button, pen tip, or touch contact. */
+    YASL_BUTTON_MIDDLE = 1, /**< Middle button / wheel click. */
+    YASL_BUTTON_SECONDARY = 2, /**< Right button or pen barrel button. */
+    YASL_BUTTON_BACK = 3, /**< Side "back" button. */
+    YASL_BUTTON_FORWARD = 4, /**< Side "forward" button. */
+};
+
+/** Pointer capture mode for a surface. */
+enum yasl_pointer_mode {
+    YASL_POINTER_NORMAL = 0, /**< Absolute positions; cursor per yasl_surface_set_cursor(). */
+    /** Cursor hidden and locked in place while the surface has focus. POINTER_MOTION
+     * reports unbounded relative motion in delta; pos stays at the lock position.
+     * The lock is released on focus loss and re-acquired on focus gain. */
+    YASL_POINTER_RELATIVE,
+};
+
 /** Normalized tablet axes; zero for unavailable axes and non-tablet devices. */
 struct yasl_pointer_pen {
     /** 0..65535 normalized to device range. Zero alone does not end contact. */
@@ -309,13 +318,36 @@ struct yasl_pointer_pen {
     int8_t tilt_y;
 };
 
+/** Event tag. Each tag lists the union member it selects. */
+enum yasl_event_type {
+    YASL_EVENT_NONE = 0,
+
+    /* Input: produced by backends, returned by yasl_surface_poll_event(). */
+    YASL_EVENT_KEY, /**< .key */
+    YASL_EVENT_TEXT, /**< .text — committed UTF-8; insert this, not key codepoints. */
+    YASL_EVENT_POINTER_DOWN, /**< .pointer — button/tip pressed; button valid. */
+    YASL_EVENT_POINTER_UP, /**< .pointer — button/tip released; button valid. */
+    YASL_EVENT_POINTER_MOTION, /**< .pointer — position, relative motion, or pen axes changed. */
+    YASL_EVENT_POINTER_SCROLL, /**< .pointer — scroll valid. */
+    YASL_EVENT_POINTER_LEAVE, /**< .pointer — last known pos/device; cancel hover state. */
+    YASL_EVENT_FOCUS, /**< .focus — keyboard focus changed; cancel held state on loss. */
+    YASL_EVENT_PASTE, /**< .text — UTF-8 from yasl_display_paste(). */
+    YASL_EVENT_DROP, /**< .text — dropped text/uri-list: CRLF-separated file URLs, not paths. */
+    YASL_EVENT_INPUT_RESET, /**< No payload. Input stream interrupted; clear held keys, buttons, strokes, IME. */
+
+    /* Window and application: delivered only through yasl_app_desc.event().
+     * Low-level users receive the same information via yasl_window_cbs. */
+    YASL_EVENT_WINDOW_RESIZE, /**< .resize — size and/or scale changed; reallocate and redraw. */
+    YASL_EVENT_WINDOW_CLOSE, /**< No payload. User asked to close the window. */
+    YASL_EVENT_USER, /**< .user — posted with yasl_post_event(). */
+};
+
 /** Physical keyboard transition with optional layout labels.
  * key is independent of modifiers/layout and stable between press and release.
  * codepoint and shifted are optional single Unicode scalars for the current
  * layout at levels zero/one, not text input. Zero means unavailable, a control
- * key, or a layout mapping that produces multiple characters. Native scancodes
- * are backend-specific. Insert committed YASL_INPUT_TEXT into documents.
- */
+ * key, or a layout mapping that produces multiple characters. Insert committed
+ * YASL_EVENT_TEXT into documents instead. */
 struct yasl_key_event {
     /** Portable physical key; YASL_KEY_UNKNOWN when unmapped. */
     enum yasl_key key;
@@ -331,89 +363,75 @@ struct yasl_key_event {
     uint32_t native_code;
 };
 
-/** Pointer sample. Pen and eraser events share this structure with mouse input.
-Track contact with primary press/release, not pressure alone. Leave, focus loss,
-and YASL_INPUT_RESET must cancel held application input state. This is not a
-multi-contact touch API. Scroll offsets use fractional line units: positive x
-means right and positive y means down, after system scroll preferences. */
-struct yasl_mouse_event {
-    /** Surface-relative device-pixel position. */
+/** Pointer sample shared by all POINTER_* events. Pen and eraser share it with
+ * mouse input. Track contact with DOWN/UP of the primary button, not pressure.
+ * This is not a multi-contact touch API. */
+struct yasl_pointer_event {
+    /** Surface-relative device-pixel position. Frozen while YASL_POINTER_RELATIVE is locked. */
     struct yasl_vector2i pos;
-    /** Press/release: 0 primary/tip, 1 middle, 2 secondary. Unused for scroll. */
-    int16_t button;
-    /** Sample type. */
-    enum yasl_pointer_kind kind;
+    /** MOTION: device-pixel movement since the previous sample on this surface.
+     * Unbounded under YASL_POINTER_RELATIVE; zero after enter, leave, or reset. */
+    struct yasl_vector2d delta;
+    /** SCROLL: fractional line offsets after system preferences; positive right/down. */
+    struct yasl_vector2d scroll;
+    /** DOWN/UP: which button changed. */
+    enum yasl_pointer_button button;
     /** Mouse, touch, pen, or eraser. */
     enum yasl_pointer_device device;
     /** yasl_mod bitmask at this event. */
     uint32_t mods;
-    /** Fractional line offsets, valid for SCROLL only; positive right/down. */
-    struct yasl_vector2d scroll;
-
     /** Current tablet axes, including on pressure-only motion; missing axes are zero. */
     struct yasl_pointer_pen pen;
 };
 
-/** Input union tag. RESET has no payload and requires clearing held state. */
-enum yasl_input_kind {
-    YASL_INPUT_KEY, /**< key member. */
-    YASL_INPUT_MOUSE, /**< mouse member. */
-    YASL_INPUT_FOCUS, /**< focus member. */
-    YASL_INPUT_PASTE, /**< paste member. */
-    YASL_INPUT_DROP_FILES, /**< drop_files member. */
-    YASL_INPUT_TEXT, /**< text member, containing committed UTF-8. */
-    /* The input stream was interrupted (e.g. allocation failure or device
-     * removal). Clear held keys/buttons and composition state. */
-    YASL_INPUT_RESET, /**< No payload. Clear held keys/buttons and composition after an interruption. */
+/** Borrowed NUL-terminated UTF-8, shared by TEXT, PASTE and DROP. */
+struct yasl_text_event {
+    /** Borrowed NUL-terminated bytes; see yasl_surface_poll_event() for lifetime. */
+    const char *data;
+    /** Length in bytes excluding the terminating NUL. */
+    size_t len;
 };
 
-/** Keyboard focus transition; cancel held state when focus is lost. */
+/** Keyboard focus transition. */
 struct yasl_focus_event {
     /** true on focus gain, false on loss. */
     bool focused;
 };
 
-/** Committed UTF-8 text; insert this instead of deriving characters from key events. */
-struct yasl_text_event {
-    /** Borrowed NUL-terminated UTF-8. */
-    const char *text;
-    /** Length in bytes excluding the terminating NUL. */
-    size_t len;
+/** New configured geometry for a surface. */
+struct yasl_resize_event {
+    /** Content size in device pixels and display scale. */
+    struct yasl_geometry geometry;
+    /** true when scale_120 differs from the previous resize of this surface. */
+    bool scale_changed;
 };
 
-/** UTF-8 text received from an explicit selection request. */
-struct yasl_paste_event {
-    /** Borrowed NUL-terminated UTF-8. */
-    const char *text;
-    /** Length in bytes excluding the terminating NUL. */
-    size_t len;
+/** Application message posted with yasl_post_event(). */
+struct yasl_user_event {
+    /** Application-defined message code. */
+    uint32_t code;
+    /** Pointer passed through unchanged; ownership stays with the application. */
+    void *payload;
+    /** Optional payload size, passed through unchanged. */
+    size_t size;
 };
 
-/** File URLs in text/uri-list form, separated by CRLF; not filesystem paths. */
-struct yasl_drop_files_event {
-    /** Borrowed NUL-terminated text/uri-list; parse URLs and percent escapes. */
-    const char *files;
-    /** Length in bytes excluding the terminating NUL. */
-    size_t len;
-};
-
-/** One tagged input event; read only the union member selected by kind.
-Payload strings follow yasl_surface_input_poll() lifetime rules. RESET carries
-no union payload; clear keys, buttons, strokes, and composition state. */
-struct yasl_input_event {
-    /** Recipient; can differ from the polled surface for routed popup input. */
-    struct yasl_surface *surface;
+/** One tagged event; read only the union member selected by type. */
+struct yasl_event {
     /** Selects the valid union member. */
-    enum yasl_input_kind kind;
-    /** Reserved for YASL; applications must not interpret it. */
-    uint32_t reserved;
+    enum yasl_event_type type;
+    /** Recipient surface, or NULL for display-wide events. Can differ from the
+     * polled surface for routed popup input. */
+    struct yasl_surface *surface;
+    /** Monotonic timestamp in nanoseconds, same clock as yasl_loop_now_ns(). */
+    uint64_t time_ns;
     union {
-        struct yasl_key_event key; /**< Keyboard payload. */
-        struct yasl_mouse_event mouse; /**< Pointer payload. */
-        struct yasl_focus_event focus; /**< Focus payload. */
-        struct yasl_text_event text; /**< Committed text payload. */
-        struct yasl_paste_event paste; /**< Selection text payload. */
-        struct yasl_drop_files_event drop_files; /**< File URL list payload. */
+        struct yasl_key_event key; /**< KEY */
+        struct yasl_pointer_event pointer; /**< POINTER_* */
+        struct yasl_text_event text; /**< TEXT, PASTE, DROP */
+        struct yasl_focus_event focus; /**< FOCUS */
+        struct yasl_resize_event resize; /**< WINDOW_RESIZE */
+        struct yasl_user_event user; /**< USER */
     };
 };
 
@@ -556,7 +574,7 @@ YASL_API void yasl_display_copy(struct yasl_display *d, enum yasl_selection sel,
  * @param d Display that owns target.
  * @param sel YASL_CLIPBOARD or YASL_PRIMARY.
  * @param target Destination surface; NULL or a surface on another display does nothing.
- * Results arrive as YASL_INPUT_PASTE, possibly during a later dispatch. No result
+ * Results arrive as YASL_EVENT_PASTE, possibly during a later dispatch. No result
  * is promised for unavailable data or a failed transfer. Destroying target cancels
  * delivery. Unsupported selections do nothing.
  */
@@ -722,18 +740,29 @@ YASL_API bool yasl_surface_present(struct yasl_surface *s, const struct yasl_fra
  * the next SUCCESSFUL poll on this surface or surface destruction. Dispatch,
  * flush and unsuccessful polls do not invalidate them. Copy to keep longer. */
 /**
- * Remove one event from a surface's input queue without waiting.
+ * Remove one input event from a surface's queue without waiting.
  * @param s Surface whose queue to drain.
  * @param ev Required output event; unchanged when no event is available.
  * @return true for an event, false for an empty queue or NULL arguments.
- * Dispatch receives native input; polling only drains the queue. Read the union
- * member selected by kind. Payload strings are borrowed, NUL-terminated, and
- * valid until the next successful poll on this queue or its destruction; dispatch,
- * flush, and unsuccessful polls do not invalidate them. On Wayland, popup pointer
- * and keyboard input can be routed through the root parent's queue; inspect
+ * Dispatch receives native input; polling only drains the queue. Only input
+ * types (KEY through INPUT_RESET) are returned. Read the union member selected
+ * by type. Payload strings are borrowed, NUL-terminated, and valid until the
+ * next successful poll on this queue or its destruction; dispatch, flush, and
+ * unsuccessful polls do not invalidate them. On Wayland, popup pointer and
+ * keyboard input can be routed through the root parent's queue; inspect
  * ev->surface to identify the receiving surface.
  */
-YASL_API bool yasl_surface_input_poll(struct yasl_surface *s, struct yasl_input_event *ev);
+YASL_API bool yasl_surface_poll_event(struct yasl_surface *s, struct yasl_event *ev);
+/**
+ * Select absolute or relative (locked) pointer input for a surface.
+ * @param s Surface.
+ * @param mode YASL_POINTER_NORMAL or YASL_POINTER_RELATIVE.
+ * @return true if the mode is supported by the backend; false leaves NORMAL.
+ * RELATIVE hides the cursor and locks it while the surface is focused;
+ * POINTER_MOTION then carries unbounded delta. Returning to NORMAL restores
+ * the cursor selected with yasl_surface_set_cursor().
+ */
+YASL_API bool yasl_surface_set_pointer_mode(struct yasl_surface *s, enum yasl_pointer_mode mode);
 
 /* Current device-pixel size and scale, matching the configure callback. */
 /**
@@ -794,7 +823,7 @@ YASL_API void yasl_surface_set_background_color(struct yasl_surface *s, uint32_t
  * @param s Surface, or NULL.
  * @return Borrowed NUL-terminated text, or NULL if absent/unsupported.
  * Copy to retain across the next dispatch or surface destruction. Composition
- * changes can schedule a redraw. Insert committed YASL_INPUT_TEXT into documents,
+ * changes can schedule a redraw. Insert committed YASL_EVENT_TEXT into documents,
  * not preedit text.
  */
 YASL_API const char *yasl_surface_ime_preedit(const struct yasl_surface *s);