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, 26 insertions, 15 deletions

diff --git a/docs/guide.md b/docs/guide.md
index 1bd1aef..f195e5e 100644
--- a/docs/guide.md
+++ b/docs/guide.md
@@ -45,7 +45,9 @@ in `event`, and render into `frame->cpu.pixels` in `frame`. Present with
 `yasl_frame_present_cpu(frame, NULL, 0)` and return `YASL_APP_QUIT` from an event
 handler to exit. The runner handles dispatch, input polling, resize redraws,
 and remaining surface/display cleanup. Display quit stops the runner; connection
-loss and dispatch failures return an error after cleanup.
+loss and dispatch failures return an error after cleanup. The runner delivers
+input exactly as `yasl_surface_poll_event()` returns it, plus
+`YASL_EVENT_WINDOW_RESIZE`, `YASL_EVENT_WINDOW_CLOSE`, and `YASL_EVENT_USER`.
 
 Unified pointer button and motion events retain `device` and `pen` axes,
 including erasers and pressure-only motion. Cancel held input or active strokes
@@ -159,19 +161,21 @@ clock; it does not establish actual scanout time.
 
 ## Input, text, and payload lifetime
 
-Dispatch receives native input. `yasl_surface_input_poll()` only drains it and
+Dispatch receives native input. `yasl_surface_poll_event()` only drains it and
 never waits. Poll every live surface queue until empty. Wayland routes popup
 pointer and keyboard events through the root parent's queue; inspect
 `event.surface` to identify the recipient. Do not assume it equals the object
 whose queue you polled.
 
-Read the union member selected by `event.kind`. The `reserved` field is internal
-and must not be interpreted. Text, paste, and file-drop payloads are UTF-8 byte
-strings, NUL-terminated; `len` excludes the NUL. They remain valid until the
+Read the union member selected by `event.type`; `time_ns` is a monotonic
+timestamp on the `yasl_loop_now_ns()` clock. Polling returns only input types,
+`YASL_EVENT_KEY` through `YASL_EVENT_INPUT_RESET`. Text, paste, and file-drop
+payloads share `event.text`: UTF-8 byte strings, NUL-terminated; `len` excludes
+the NUL. They remain valid until the
 next **successful** poll on the queue or queue destruction. Dispatch, flush,
 and unsuccessful polls do not invalidate them. Copy data to keep it longer.
 
-Use `YASL_INPUT_TEXT` for document text insertion, including committed IME text.
+Use `YASL_EVENT_TEXT` for document text insertion, including committed IME text.
 It contains UTF-8 and can contain several characters. Key actions are for
 commands and held-key state; releases and repeats have separate tags. A text
 commit need not correspond to one key event, and a key need not produce text.
@@ -192,11 +196,11 @@ are useful for displaying shortcuts or
 choosing layout-sensitive commands; they are never document text. For example:
 
 ```c
-if (event.kind == YASL_INPUT_KEY && event.key.action == YASL_KEY_PRESS &&
+if (event.type == YASL_EVENT_KEY && event.key.action == YASL_KEY_PRESS &&
     event.key.key == YASL_KEY_ESCAPE) {
     running = false;
 }
-/* Insert event.text.text[0..event.text.len) only for YASL_INPUT_TEXT. */
+/* Insert event.text.data[0..event.text.len) only for YASL_EVENT_TEXT. */
 ```
 
 Wayland uses the supplied XKB layout and locale compose rules for ordinary text
@@ -209,14 +213,21 @@ not change the process locale. IME availability and system configuration still
 determine which compositions work. Physical key events
 remain available for commands; input methods may consume keys while composing.
 
-Pointer events use `YASL_INPUT_MOUSE`, with `device` distinguishing mouse, touch,
-pen, and eraser. Press/release button 0 is primary/tip, 1 middle, and 2 secondary.
-Track those transitions; motion/leave button values are informational. Pen
+Pointer events use the `YASL_EVENT_POINTER_*` types and share `event.pointer`,
+with `device` distinguishing mouse, touch, pen, and eraser. `POINTER_DOWN` and
+`POINTER_UP` carry a `YASL_BUTTON_*` value: `PRIMARY` is the left button, pen tip,
+or touch contact. Track those transitions; other types leave `button`
+meaningless. `POINTER_MOTION` reports `delta`, the device-pixel movement since
+the previous sample, which restarts from zero after enter, leave, or reset.
+`yasl_surface_set_pointer_mode()` with `YASL_POINTER_RELATIVE` hides and locks the
+cursor while the surface is focused; motion then carries unbounded `delta` and
+`pos` stays at the lock position. No backend implements it yet, so it
+currently returns false and leaves the surface in `YASL_POINTER_NORMAL`. Pen
 pressure is normalized to 0..65535, signed tilt is in degrees, and missing axes
 are zero. Pressure-only changes can produce motion. Zero pressure alone does
 not mean release. This interface does not expose simultaneous touch contacts.
 
-For `YASL_PTR_SCROLL`, read `mouse.scroll.x` and `.y`: fractional line offsets,
+For `YASL_EVENT_POINTER_SCROLL`, read `pointer.scroll.x` and `.y`: fractional line offsets,
 positive right and down, after system scroll preferences. Both axes may be
 nonzero in one event. Preserve fractions and choose your application's own
 pixels per line; one wheel detent normally gives one line. `button` is unused
@@ -225,7 +236,7 @@ discrete/raw descriptions. Smooth Wayland offsets and precise Cocoa offsets
 use ten native units per line. X11 currently reports whole wheel steps, so it
 does not provide the same smooth-scroll precision as the other backends.
 
-Cancel held keys, buttons, active strokes, and composition on `YASL_INPUT_RESET`,
+Cancel held keys, buttons, active strokes, and composition on `YASL_EVENT_INPUT_RESET`,
 focus loss, or pointer leave as appropriate to your application. RESET has no
 union payload. It is emitted after input-queue allocation failure and certain
 device interruptions; ignoring it can leave application input stuck.
@@ -234,7 +245,7 @@ device interruptions; ignoring it can leave application input stuck.
 
 `yasl_display_copy()` copies a NUL-terminated UTF-8 string during the call.
 `yasl_display_paste()` requests delivery to the original target as
-`YASL_INPUT_PASTE`; destroying the target cancels delivery. There is no transfer
+`YASL_EVENT_PASTE`; destroying the target cancels delivery. There is no transfer
 ID or error callback, so unavailable or failed transfers may produce no event.
 Wayland selection offers can require a recent input serial. X11 currently does
 not implement incremental (`INCR`) selection transfers and may reject large
@@ -245,7 +256,7 @@ and never aliases the clipboard. Cocoa uses a YASL named pasteboard to emulate p
 this is not a desktop-wide macOS select-to-copy convention.
 
 External file drag hover uses the surface `drop` callback; actual file URLs
-arrive as `YASL_INPUT_DROP_FILES`. `files` is a `text/uri-list` string separated by
+arrive as `YASL_EVENT_DROP`. `text.data` is a `text/uri-list` string separated by
 CRLF, not a list of native paths. Parse URL encoding, skip blank/comment lines,
 and decide which schemes/hosts your application accepts before opening files.