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.

2 files changed, 13 insertions, 3 deletions

diff --git a/tests/cocoa/test_native.c b/tests/cocoa/test_native.c
index 41df79a..0c101dd 100644
--- a/tests/cocoa/test_native.c
+++ b/tests/cocoa/test_native.c
@@ -1,4 +1,6 @@
 #define _POSIX_C_SOURCE 200809L
+#include "yasl/native.h"
+#include "yasl/loop.h"
 #include "yasl/yasl.h"
 
 #include <assert.h>
@@ -16,20 +18,24 @@ static void draw(struct yasl_surface *surface, struct yasl_frame *frame, void *u
     assert(surface == state->surface && frame->surface == surface);
     assert(yasl_surface_display(surface) == state->display);
     assert(frame->target.pixels);
-    struct yasl_vector2i size = yasl_surface_size(surface);
+    struct yasl_native_frame native;
+    assert(yasl_surface_get_native_frame(surface, &frame->target, &native));
+    assert(native.drawable);
+    struct yasl_vector2i size = yasl_surface_geometry(surface).size;
     assert(size.x == frame->target.size.x && size.y == frame->target.size.y);
     for (int i = 0; i < size.x * size.y; i++) frame->target.pixels[i] = 0xff4080c0;
     struct yasl_damage_list damage = {.n = YASL_DAMAGE_MAX + 1};
     assert(!yasl_surface_present(surface, &frame->target, &damage));
     damage.n = -1;
     struct yasl_framebuffer invalid = frame->target;
-    invalid.buffer++;
+    invalid.size.x++;
     assert(!yasl_surface_present(surface, &invalid, &damage));
     invalid = frame->target;
     invalid.generation--;
     assert(!yasl_surface_present(surface, &invalid, &damage));
     assert(!yasl_surface_present(surface, &frame->target, NULL));
     assert(yasl_surface_present(surface, &frame->target, &damage));
+    assert(!yasl_surface_get_native_frame(surface, &frame->target, &native));
     assert(!yasl_surface_present(surface, &frame->target, &damage));
     state->draws++;
     yasl_surface_destroy(surface);
@@ -51,7 +57,7 @@ static void test_window(enum yasl_backend request, bool null_spec)
     yasl_surface_schedule_redraw(state.surface);
     uint64_t deadline = yasl_loop_now_ns() + 3000000000ull;
     while (!state.draws && yasl_loop_now_ns() < deadline) {
-        yasl_display_dispatch(state.display);
+        yasl_display_dispatch(state.display, 0);
         yasl_display_flush(state.display);
         nanosleep(&(struct timespec){.tv_nsec = 1000000}, NULL);
     }
diff --git a/tests/cocoa/test_ownership.m b/tests/cocoa/test_ownership.m
index aa75b1c..168a47b 100644
--- a/tests/cocoa/test_ownership.m
+++ b/tests/cocoa/test_ownership.m
@@ -1,3 +1,4 @@
+#include "yasl/native.h"
 #import <AppKit/AppKit.h>
 #include "yasl/yasl.h"
 #include <assert.h>
@@ -11,6 +12,9 @@ int main(void)
     struct yasl_surface_spec spec = {.title = "Ownership test", .size = {160, 100}};
     struct yasl_surface *s = yasl_surface_create_toplevel(d, &spec);
     assert(s);
+    assert(yasl_display_get_native_handle(d) == (void *)NSApp);
+    NSWindow *window = (NSWindow *)yasl_surface_get_native_handle(s);
+    assert([window isKindOfClass:[NSWindow class]] && window.contentView);
     struct yasl_input_event event;
     while (yasl_surface_input_poll(s, &event)) {}
     @autoreleasepool {