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, 35 insertions, 0 deletions

diff --git a/src/common/native.c b/src/common/native.c
new file mode 100644
index 0000000..2d9c06f
--- /dev/null
+++ b/src/common/native.c
@@ -0,0 +1,35 @@
+#include "backend.h"
+
+#include <errno.h>
+
+void *yasl_display_get_native_handle(struct yasl_display *d)
+{
+    return d && d->ops->display_get_native_handle ?
+        d->ops->display_get_native_handle(d) : NULL;
+}
+
+void *yasl_surface_get_native_handle(struct yasl_surface *s)
+{
+    return s && s->display->ops->surface_get_native_handle ?
+        s->display->ops->surface_get_native_handle(s) : NULL;
+}
+
+struct yasl_surface *yasl_surface_create_native(struct yasl_display *d,
+        const struct yasl_surface_spec *spec, void *graphics_device)
+{
+    if (!graphics_device) {
+        errno = EINVAL;
+        return NULL;
+    }
+    return yasl_create_toplevel(d, spec, graphics_device);
+}
+
+bool yasl_surface_get_native_frame(struct yasl_surface *s,
+        const struct yasl_framebuffer *target, struct yasl_native_frame *out)
+{
+    if (!s || !target || !out || !target->generation ||
+        target->generation != s->frame_generation ||
+        !s->display->ops->surface_get_native_frame)
+        return false;
+    return s->display->ops->surface_get_native_frame(s, target, out);
+}