refactor: simplify public API and isolate native extensions

Separate loop/timer and native interoperability APIs from the portable surface header. Unify dispatch, geometry queries, and timer callbacks; keep framebuffer bookkeeping and frame clocks private, and hide implementation symbols.

Update backends, documentation, examples, and API/integration coverage. Verify exports, strict C/C++ installed consumers, and normal plus ASan/UBSan suites.

1 files changed, 44 insertions, 0 deletions

diff --git a/include/yasl/native.h b/include/yasl/native.h
new file mode 100644
index 0000000..f7e3020
--- /dev/null
+++ b/include/yasl/native.h
@@ -0,0 +1,44 @@
+#ifndef YASL_NATIVE_H
+#define YASL_NATIVE_H
+
+#include "yasl/yasl.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/* Optional platform interoperability. All handles are borrowed and expire on
+ * object destruction. Check yasl_display_backend() before casting:
+ *
+ *              display                  surface
+ * Wayland      struct wl_display *       struct wl_surface *
+ * X11          Display *                 Window (cast through uintptr_t)
+ * Cocoa        NSApplication *           NSWindow * (view: window.contentView)
+ */
+YASL_API void *yasl_display_get_native_handle(struct yasl_display *d);
+YASL_API void *yasl_surface_get_native_handle(struct yasl_surface *s);
+
+/* Create a surface for application-managed native rendering. graphics_device
+ * must be non-NULL; currently an id<MTLDevice> on Cocoa, retained by the surface.
+ * Other backends return NULL with errno=ENOTSUP. CPU rendering uses the ordinary
+ * yasl_surface_create_toplevel() and requires no native device. */
+YASL_API struct yasl_surface *yasl_surface_create_native(struct yasl_display *d,
+        const struct yasl_surface_spec *spec, void *graphics_device);
+
+struct yasl_native_frame {
+    void *drawable; /* id<CAMetalDrawable> on Cocoa */
+    bool transaction; /* CAMetalLayer.presentsWithTransaction */
+};
+
+/* Query the current draw target's native drawable. Returns false for unsupported
+ * backends, stale targets, or outside the draw callback. The result expires on
+ * successful present, callback return, or surface destruction. Native renderers
+ * submit/present the drawable, then call yasl_surface_present() to record it. */
+YASL_API bool yasl_surface_get_native_frame(struct yasl_surface *s,
+        const struct yasl_framebuffer *target, struct yasl_native_frame *out);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* YASL_NATIVE_H */