Simplify the public event and CPU API

Applications now need far less ceremony: hello.c is a 20-line loop that
handles REFRESH, CLOSE and QUIT and draws into the surface's own pixels.

- Fold GEOMETRY, STATE and FOCUS into one WINDOW event carrying size,
  scale and state; unchanged values send nothing.
- Guarantee REFRESH once a window has a size and after every resize,
  never at size zero.
- Merge DROP_HOVER into DROP with over/leave/data actions and give drag
  and drop actions enums.
- Keep event strings valid until the next wait and drop
  yasl_event_release; empty or failed waits report NONE.
- Replace copy-in presentation with a lent pixel buffer:
  yasl_cpu_pixels and yasl_cpu_present.
- Remove yasl_poll_event, yasl_cpu_read_pixels, unused event fields and
  comments that restated names.
- Wayland: resize floating windows in request_size instead of reporting
  it unsupported, and stop marking new GPU surfaces as Vulkan so
  yasl_vulkan_create_surface no longer fails with NATIVE_WINDOW_IN_USE.

Also includes the in-progress public API refactor that was uncommitted
in the tree (removal of the app/loop layer, new surface, GL and Vulkan
entry points).

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

3 files changed, 19 insertions, 102 deletions

diff --git a/include/yasl/native/cocoa.h b/include/yasl/native/cocoa.h
index 9b221cf..bd92c98 100644
--- a/include/yasl/native/cocoa.h
+++ b/include/yasl/native/cocoa.h
@@ -1,55 +1,23 @@
-/**
- * @file
- * Typed borrowed Cocoa handles; available on macOS. Use on the main thread.
- */
 #ifndef YASL_NATIVE_COCOA_H
 #define YASL_NATIVE_COCOA_H
-
 #include "yasl/yasl.h"
-
 #ifdef __OBJC__
 @class NSApplication;
 @class NSWindow;
 @class NSView;
 #else
-typedef struct objc_object NSApplication; /**< Opaque Cocoa application in plain C/C++. */
-typedef struct objc_object NSWindow; /**< Opaque Cocoa window in plain C/C++. */
-typedef struct objc_object NSView; /**< Opaque Cocoa view in plain C/C++. */
+typedef struct objc_object NSApplication;
+typedef struct objc_object NSWindow;
+typedef struct objc_object NSView;
 #endif
-
 #ifdef __cplusplus
 extern "C" {
 #endif
-
-/* Return borrowed Cocoa handles (expire on display/surface destruction).
- * Return NULL / nil if display/surface is not a Cocoa object or NULL. */
-/**
- * Get the borrowed NSApplication for an object of the matching backend.
- * @param d Live display, or NULL.
- * @return The handle, or zero/NULL for NULL or a different backend.
- * Expires on display destruction. Available only when this backend is built.
- * Never pass a pointer to a destroyed object.
- */
-YASL_API NSApplication *yasl_cocoa_display_get_application(struct yasl_display *d);
-/**
- * Get the borrowed NSWindow for an object of the matching backend.
- * @param s Live surface, or NULL.
- * @return The handle, or zero/NULL for NULL or a different backend.
- * Expires on surface destruction. Available only when this backend is built.
- * Never pass a pointer to a destroyed object.
- */
-YASL_API NSWindow *yasl_cocoa_surface_get_window(struct yasl_surface *s);
-/**
- * Get the borrowed NSView for an object of the matching backend.
- * @param s Live surface, or NULL.
- * @return The handle, or zero/NULL for NULL or a different backend.
- * Expires on surface destruction. Available only when this backend is built.
- * Never pass a pointer to a destroyed object.
- */
-YASL_API NSView *yasl_cocoa_surface_get_view(struct yasl_surface *s);
-
+/** Borrowed native objects. Use on main thread, never change native ownership. */
+YASL_API NSApplication *yasl_cocoa_application(void);
+YASL_API NSWindow *yasl_cocoa_window(const yasl_surface *surface);
+YASL_API NSView *yasl_cocoa_view(const yasl_surface *surface);
 #ifdef __cplusplus
 }
 #endif
-
-#endif /* YASL_NATIVE_COCOA_H */
+#endif
diff --git a/include/yasl/native/wayland.h b/include/yasl/native/wayland.h
index b11e3b8..1b8881e 100644
--- a/include/yasl/native/wayland.h
+++ b/include/yasl/native/wayland.h
@@ -1,40 +1,15 @@
-/**
- * @file
- * Typed borrowed Wayland handles; available when built with Wayland support.
- */
 #ifndef YASL_NATIVE_WAYLAND_H
 #define YASL_NATIVE_WAYLAND_H
-
 #include "yasl/yasl.h"
-
+struct wl_display;
+struct wl_surface;
 #ifdef __cplusplus
 extern "C" {
 #endif
-
-struct wl_display;
-struct wl_surface;
-
-/* Return borrowed Wayland handles (expire on display/surface destruction).
- * Return NULL if display/surface is not a Wayland object or NULL. */
-/**
- * Get the borrowed Wayland connection for an object of the matching backend.
- * @param d Live display, or NULL.
- * @return The handle, or zero/NULL for NULL or a different backend.
- * Expires on display destruction. Available only when this backend is built.
- * Never pass a pointer to a destroyed object.
- */
-YASL_API struct wl_display *yasl_wayland_display_get_wl_display(struct yasl_display *d);
-/**
- * Get the borrowed Wayland surface for an object of the matching backend.
- * @param s Live surface, or NULL.
- * @return The handle, or zero/NULL for NULL or a different backend.
- * Expires on surface destruction. Available only when this backend is built.
- * Never pass a pointer to a destroyed object.
- */
-YASL_API struct wl_surface *yasl_wayland_surface_get_wl_surface(struct yasl_surface *s);
-
+/** Borrowed handles; never dispatch or close native connections independently. */
+YASL_API struct wl_display *yasl_wayland_display(const yasl_surface *surface);
+YASL_API struct wl_surface *yasl_wayland_surface(const yasl_surface *surface);
 #ifdef __cplusplus
 }
 #endif
-
-#endif /* YASL_NATIVE_WAYLAND_H */
+#endif
diff --git a/include/yasl/native/x11.h b/include/yasl/native/x11.h
index b719b4b..f8c37ae 100644
--- a/include/yasl/native/x11.h
+++ b/include/yasl/native/x11.h
@@ -1,40 +1,14 @@
-/**
- * @file
- * Typed borrowed X11 handles; available when built with X11 support.
- */
 #ifndef YASL_NATIVE_X11_H
 #define YASL_NATIVE_X11_H
-
 #include "yasl/yasl.h"
-#include <stdint.h>
-
+typedef struct _XDisplay Display;
 #ifdef __cplusplus
 extern "C" {
 #endif
-
-typedef struct _XDisplay Display; /**< Opaque Xlib connection, compatible with Xlib.h. */
-
-/* Return borrowed X11 handles (expire on display/surface destruction).
- * Return NULL / 0 if display/surface is not an X11 object or NULL. */
-/**
- * Get the borrowed X11 Display for an object of the matching backend.
- * @param d Live display, or NULL.
- * @return The handle, or zero/NULL for NULL or a different backend.
- * Expires on display destruction. Available only when this backend is built.
- * Never pass a pointer to a destroyed object.
- */
-YASL_API Display *yasl_x11_display_get_display(struct yasl_display *d);
-/**
- * Get the borrowed X11 Window ID for an object of the matching backend.
- * @param s Live surface, or NULL.
- * @return The handle, or zero/NULL for NULL or a different backend.
- * Expires on surface destruction. Available only when this backend is built.
- * Never pass a pointer to a destroyed object.
- */
-YASL_API uintptr_t yasl_x11_surface_get_window(struct yasl_surface *s);
-
+/** Borrowed handles; surface/window lifetime and native connection stay in YASL. */
+YASL_API Display *yasl_x11_display(const yasl_surface *surface);
+YASL_API uintptr_t yasl_x11_window(const yasl_surface *surface);
 #ifdef __cplusplus
 }
 #endif
-
-#endif /* YASL_NATIVE_X11_H */
+#endif