Pace frame requests by the frame presented after them

A frame request now only records intent. Each loop step resolves it after
the callbacks that present, so a request made before the present waits for
that frame. An animation that asked first got two REFRESH events per frame
on X11 and with GL.

With no frame in flight, the REFRESH comes one refresh interval after the
last present or answer, so a request without a present cannot spin.

Queued events now go before an owed REFRESH. Input reaches the application
before it draws, and a queued REFRESH pays an owed one for the same surface.

The loop prepare only peeks at a lost event, so deliver can report it as a
final loss. A failed push from another thread wakes the loop.

Signals and posts run at the end of a step, after descriptors and timers.
A signal handler now sees the output that came with it.

A render-thread GL swap counts as in flight on Wayland.

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

1 files changed, 8 insertions, 6 deletions

diff --git a/include/yasl/yasl.h b/include/yasl/yasl.h
index dab1091..6139bc3 100644
--- a/include/yasl/yasl.h
+++ b/include/yasl/yasl.h
@@ -114,9 +114,11 @@ YASL_API int yasl_surface_set_title(yasl_surface *surface, const char *title);
 enum yasl_request { YASL_REQUEST_RESTORE, YASL_REQUEST_FULLSCREEN, YASL_REQUEST_MAXIMIZE, YASL_REQUEST_MINIMIZE };
 YASL_API int yasl_surface_request(yasl_surface *surface, enum yasl_request request);
 YASL_API int yasl_surface_request_size(yasl_surface *surface, int width, int height);
-/** Asks for a REFRESH when the window can show a new frame: at once when none
- * is in flight, otherwise once the system shows the current one. Requests
- * coalesce. Use it to pace animation; draw at once for input. */
+/** Asks for a REFRESH after the next frame is shown. A frame presented after
+ * the request, in the same callback, is that frame, so an animation can ask
+ * before it draws. With no frame in flight, the REFRESH comes one refresh
+ * interval after the last present or REFRESH. Requests coalesce. Use it to
+ * pace animation; draw at once for input. */
 YASL_API int yasl_surface_request_frame(yasl_surface *surface);
 
 enum yasl_cursor {
@@ -306,9 +308,9 @@ YASL_API yasl_loop *yasl_loop_create(void);
 /** EBUSY while a step runs or the display runs on it. Leaves descriptors open. */
 YASL_API int yasl_loop_destroy(yasl_loop *loop);
 /** Waits at most timeout_ms (0 polls, -1 waits) and runs what is ready:
- * display events, then descriptors, then due timers. Returns how many
- * descriptor and timer callbacks ran. EBUSY inside a step; EPERM off the
- * loop's thread. */
+ * display events, then descriptors, then due timers, then signals. Returns
+ * how many descriptor and timer callbacks ran. EBUSY inside a step; EPERM off
+ * the loop's thread. */
 YASL_API int yasl_loop_step(yasl_loop *loop, int timeout_ms);
 /** Steps until yasl_loop_quit. A quit made before the run ends it at once. */
 YASL_API int yasl_loop_run(yasl_loop *loop);