Redefine public and rendering APIs with explicit contracts

1 files changed, 10 insertions, 3 deletions

diff --git a/include/yasl/native/wayland.h b/include/yasl/native/wayland.h
index 1b8881e..5c18a80 100644
--- a/include/yasl/native/wayland.h
+++ b/include/yasl/native/wayland.h
@@ -1,3 +1,4 @@
+/** @file Borrowed wayland handles for an initialized, connected surface. */
 #ifndef YASL_NATIVE_WAYLAND_H
 #define YASL_NATIVE_WAYLAND_H
 #include "yasl/yasl.h"
@@ -6,9 +7,15 @@ struct wl_surface;
 #ifdef __cplusplus
 extern "C" {
 #endif
-/** 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);
+struct yasl_wayland_handles {
+    struct wl_display *display;
+    struct wl_surface *surface;
+};
+/** Owner thread only. Returns -ENOTSUP for another backend and -ENOTCONN
+ * while disconnected. Clears out on failure. Handles expire on display loss
+ * or surface destruction; query again after DISPLAY_RESTORED. Never destroy
+ * borrowed objects or dispatch/close the connection independently. */
+YASL_API int yasl_wayland_get_native(const yasl_surface *surface, struct yasl_wayland_handles *out);
 #ifdef __cplusplus
 }
 #endif