Redefine public and rendering APIs with explicit contracts

3 files changed, 31 insertions, 10 deletions

diff --git a/include/yasl/native/cocoa.h b/include/yasl/native/cocoa.h
index bd92c98..2d2d432 100644
--- a/include/yasl/native/cocoa.h
+++ b/include/yasl/native/cocoa.h
@@ -1,3 +1,4 @@
+/** @file Borrowed cocoa handles for an initialized, connected surface. */
 #ifndef YASL_NATIVE_COCOA_H
 #define YASL_NATIVE_COCOA_H
 #include "yasl/yasl.h"
@@ -13,10 +14,16 @@ typedef struct objc_object NSView;
 #ifdef __cplusplus
 extern "C" {
 #endif
-/** 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);
+struct yasl_cocoa_handles {
+    NSApplication *application;
+    NSWindow *window;
+    NSView *view;
+};
+/** 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_cocoa_get_native(const yasl_surface *surface, struct yasl_cocoa_handles *out);
 #ifdef __cplusplus
 }
 #endif
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
diff --git a/include/yasl/native/x11.h b/include/yasl/native/x11.h
index f8c37ae..6cc85fb 100644
--- a/include/yasl/native/x11.h
+++ b/include/yasl/native/x11.h
@@ -1,3 +1,4 @@
+/** @file Borrowed x11 handles for an initialized, connected surface. */
 #ifndef YASL_NATIVE_X11_H
 #define YASL_NATIVE_X11_H
 #include "yasl/yasl.h"
@@ -5,9 +6,15 @@ typedef struct _XDisplay Display;
 #ifdef __cplusplus
 extern "C" {
 #endif
-/** 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);
+struct yasl_x11_handles {
+    Display *display;
+    uintptr_t window;
+};
+/** 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_x11_get_native(const yasl_surface *surface, struct yasl_x11_handles *out);
 #ifdef __cplusplus
 }
 #endif