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, 73 insertions, 5 deletions

diff --git a/tests/common/test_contracts.c b/tests/common/test_contracts.c
index 65eebcd..4e22de1 100644
--- a/tests/common/test_contracts.c
+++ b/tests/common/test_contracts.c
@@ -1,5 +1,6 @@
 #include "common/backend.h"
 #include "common/input.h"
+#include "common/timing.h"
 
 #include <assert.h>
 #include <errno.h>
@@ -7,6 +8,23 @@
 #include <stdlib.h>
 #include <string.h>
 
+static void test_timing_clock(void)
+{
+    struct yasl_frame_clock clock = {.refresh_ns = YASL_REFRESH_DEFAULT_NS};
+    yasl_clock_presented(&clock, 1000000000, true);
+    assert(clock.last_present_ns == 1000000000);
+    uint64_t next = yasl_clock_next_present_ns(&clock);
+    assert(next > 1000000000);
+    assert(yasl_clock_extend_ms(1000, 1000000000) == 1000000000);
+    assert(yasl_clock_frame_timestamp_ns(&clock, next) == next);
+
+    yasl_clock_note_resize(&clock, 500000);
+    struct yasl_resize_stats stats;
+    yasl_clock_resize_stats(&clock, &stats);
+    assert(stats.count == 1);
+    assert(stats.max_us == 500.0);
+}
+
 static void test_queue(void)
 {
     struct input_queue q = {0};
@@ -96,8 +114,56 @@ static void copy(struct yasl_display *d, enum yasl_selection sel, const char *te
 { (void)d; (void)sel; (void)text; copies++; }
 static void paste(struct yasl_display *d, enum yasl_selection sel, struct yasl_surface *s)
 { (void)d; (void)sel; (void)s; pastes++; }
-static struct yasl_surface *create(struct yasl_display *d, const struct yasl_surface_spec *spec)
-{ (void)d; (void)spec; creates++; return NULL; }
+static struct yasl_surface *create(struct yasl_display *d, const struct yasl_surface_spec *spec, void *graphics_device)
+{ (void)d; (void)spec; (void)graphics_device; creates++; return NULL; }
+
+static void *native_device;
+static int native_queries;
+static struct yasl_surface native_surface;
+static uint32_t native_caps(const struct yasl_display *d)
+{ (void)d; return YASL_CAP_NATIVE_GRAPHICS; }
+static struct yasl_surface *native_create(struct yasl_display *d,
+        const struct yasl_surface_spec *spec, void *device)
+{
+    (void)spec;
+    native_device = device;
+    native_surface = (struct yasl_surface){.display = d, .frame_generation = 1};
+    return &native_surface;
+}
+static bool native_frame(struct yasl_surface *s, const struct yasl_framebuffer *fb,
+                         struct yasl_native_frame *out)
+{
+    (void)s; (void)fb;
+    native_queries++;
+    *out = (struct yasl_native_frame){.drawable = native_device};
+    return true;
+}
+
+static void test_native(void)
+{
+    const struct yasl_backend_ops ops = {.display_caps = native_caps,
+        .surface_create_toplevel = native_create, .surface_get_native_frame = native_frame};
+    struct yasl_display d = {.ops = &ops};
+    struct yasl_surface_spec spec = {.size = {100, 80}};
+    assert(yasl_surface_create_toplevel(&d, &spec) == &native_surface);
+    assert(!native_device);
+    assert(yasl_surface_create_native(&d, &spec, &d) == &native_surface);
+    assert(native_device == &d);
+
+    struct yasl_framebuffer fb = {.generation = 1, .size = {100, 80}};
+    struct yasl_native_frame out = {0};
+    assert(!yasl_surface_get_native_frame(NULL, &fb, &out));
+    assert(!yasl_surface_get_native_frame(&native_surface, NULL, &out));
+    assert(!yasl_surface_get_native_frame(&native_surface, &fb, NULL));
+    fb.generation = 0;
+    assert(!yasl_surface_get_native_frame(&native_surface, &fb, &out));
+    fb.generation = 2;
+    assert(!yasl_surface_get_native_frame(&native_surface, &fb, &out));
+    assert(!native_queries && !out.drawable);
+    fb.generation = 1;
+    assert(yasl_surface_get_native_frame(&native_surface, &fb, &out));
+    assert(native_queries == 1 && out.drawable == &d);
+}
 
 static void test_validation(void)
 {
@@ -143,9 +209,9 @@ static void test_validation(void)
     yasl_display_copy(&d, YASL_CLIPBOARD, "yes");
     yasl_display_paste(&d, YASL_CLIPBOARD, &s);
     assert(copies == 1 && pastes == 1);
-    struct yasl_surface_spec spec = {.size = {100, 80}, .graphics_device = &d};
-    assert(!yasl_surface_create_toplevel(&d, &spec) && errno == ENOTSUP);
-    spec.graphics_device = NULL;
+    struct yasl_surface_spec spec = {.size = {100, 80}};
+    assert(!yasl_surface_create_native(&d, &spec, &d) && errno == ENOTSUP);
+    assert(!yasl_surface_create_native(&d, &spec, NULL) && errno == EINVAL);
     spec.size.x = 0;
     assert(!yasl_surface_create_toplevel(&d, &spec) && errno == EINVAL);
     assert(!creates);
@@ -168,8 +234,10 @@ static void test_scale(void)
 
 int main(void)
 {
+    test_timing_clock();
     test_queue();
     test_validation();
+    test_native();
     test_scale();
     return 0;
 }