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, 15 insertions, 88 deletions

diff --git a/src/common/backend.c b/src/common/backend.c
index 27ab297..ad4d908 100644
--- a/src/common/backend.c
+++ b/src/common/backend.c
@@ -78,22 +78,11 @@ uint32_t yasl_display_caps(const struct yasl_display *d)
     return d->ops->display_caps(d);
 }
 
-void yasl_display_dispatch(struct yasl_display *d)
-{
-    if (!d || !d->ops->display_dispatch)
-        return;
-    d->ops->display_dispatch(d);
-}
-
-int yasl_display_dispatch_timeout(struct yasl_display *d, int timeout_ms)
+int yasl_display_dispatch(struct yasl_display *d, int timeout_ms)
 {
     if (!d) return -1;
     if (d->ops->display_dispatch_timeout)
         return d->ops->display_dispatch_timeout(d, timeout_ms);
-    if (d->ops->display_dispatch) {
-        d->ops->display_dispatch(d);
-        return 0;
-    }
     return -1;
 }
 
@@ -147,7 +136,8 @@ void yasl_display_drag_cancel(struct yasl_display *d)
     d->ops->display_drag_cancel(d);
 }
 
-struct yasl_surface *yasl_surface_create_toplevel(struct yasl_display *d, const struct yasl_surface_spec *spec)
+struct yasl_surface *yasl_create_toplevel(struct yasl_display *d,
+        const struct yasl_surface_spec *spec, void *graphics_device)
 {
     if (!d || !d->ops->surface_create_toplevel || !spec ||
         spec->size.x <= 0 || spec->size.y <= 0 ||
@@ -156,11 +146,17 @@ struct yasl_surface *yasl_surface_create_toplevel(struct yasl_display *d, const
         errno = EINVAL;
         return NULL;
     }
-    if (spec->graphics_device && !(yasl_display_caps(d) & YASL_CAP_NATIVE_GRAPHICS)) {
+    if (graphics_device && !(yasl_display_caps(d) & YASL_CAP_NATIVE_GRAPHICS)) {
         errno = ENOTSUP;
         return NULL;
     }
-    return d->ops->surface_create_toplevel(d, spec);
+    return d->ops->surface_create_toplevel(d, spec, graphics_device);
+}
+
+struct yasl_surface *yasl_surface_create_toplevel(struct yasl_display *d,
+        const struct yasl_surface_spec *spec)
+{
+    return yasl_create_toplevel(d, spec, NULL);
 }
 
 struct yasl_surface *yasl_surface_create_popup(struct yasl_surface *parent, const struct yasl_popup_spec *spec)
@@ -247,18 +243,11 @@ bool yasl_surface_input_poll(struct yasl_surface *s, struct yasl_input_event *ev
     return s->display->ops->surface_input_poll(s, ev);
 }
 
-struct yasl_vector2i yasl_surface_size(const struct yasl_surface *s)
-{
-    if (!s || !s->display->ops->surface_size)
-        return (struct yasl_vector2i){0};
-    return s->display->ops->surface_size(s);
-}
-
-uint32_t yasl_surface_scale_120(const struct yasl_surface *s)
+struct yasl_geometry yasl_surface_geometry(const struct yasl_surface *s)
 {
-    if (!s || !s->display->ops->surface_scale_120)
-        return YASL_SCALE_UNIT;
-    return s->display->ops->surface_scale_120(s);
+    if (!s || !s->display->ops->surface_geometry)
+        return (struct yasl_geometry){.scale_120 = YASL_SCALE_UNIT};
+    return s->display->ops->surface_geometry(s);
 }
 
 uint32_t yasl_surface_state(const struct yasl_surface *s)
@@ -356,20 +345,6 @@ bool yasl_surface_place_under_pointer(struct yasl_surface *s, struct yasl_vector
     return s->display->ops->surface_place_under_pointer(s, at);
 }
 
-void *yasl_display_get_native_handle(struct yasl_display *d)
-{
-    if (!d || !d->ops->display_get_native_handle)
-        return 0;
-    return d->ops->display_get_native_handle(d);
-}
-
-void *yasl_surface_get_native_handle(struct yasl_surface *s)
-{
-    if (!s || !s->display->ops->surface_get_native_handle)
-        return 0;
-    return s->display->ops->surface_get_native_handle(s);
-}
-
 void yasl_surface_clear_timers(struct yasl_surface *s)
 {
     if (!s || !s->timers) return;
@@ -408,29 +383,6 @@ yasl_timer_id yasl_surface_add_timer(struct yasl_surface *s, uint64_t interval_n
     return id;
 }
 
-yasl_timer_id yasl_surface_add_timer_ms(struct yasl_surface *s, uint32_t interval_ms,
-                                        yasl_timer_ms_cb cb, void *ud)
-{
-    if (!s || !s->display || !s->display->loop || !cb || interval_ms == 0)
-        return 0;
-
-    yasl_timer_id id = yasl_loop_add_timer_ms(s->display->loop, interval_ms, cb, ud);
-    if (!id) return 0;
-
-    if (s->timer_count >= s->timer_capacity) {
-        int new_cap = s->timer_capacity ? s->timer_capacity * 2 : 4;
-        yasl_timer_id *nt = realloc(s->timers, (size_t)new_cap * sizeof(*nt));
-        if (!nt) {
-            yasl_loop_del_timer(s->display->loop, id);
-            return 0;
-        }
-        s->timers = nt;
-        s->timer_capacity = new_cap;
-    }
-    s->timers[s->timer_count++] = id;
-    return id;
-}
-
 bool yasl_surface_del_timer(struct yasl_surface *s, yasl_timer_id id)
 {
     if (!s || id == 0) return false;
@@ -445,32 +397,7 @@ bool yasl_surface_del_timer(struct yasl_surface *s, yasl_timer_id id)
     return false;
 }
 
-yasl_timer_id yasl_display_add_timer(struct yasl_display *d, uint64_t interval_ns,
-                                     yasl_timer_cb cb, void *ud)
-{
-    if (!d || !d->loop) return 0;
-    return yasl_loop_add_timer(d->loop, interval_ns, cb, ud);
-}
-
-yasl_timer_id yasl_display_add_timer_ms(struct yasl_display *d, uint32_t interval_ms,
-                                        yasl_timer_ms_cb cb, void *ud)
-{
-    if (!d || !d->loop) return 0;
-    return yasl_loop_add_timer_ms(d->loop, interval_ms, cb, ud);
-}
-
-bool yasl_display_del_timer(struct yasl_display *d, yasl_timer_id id)
-{
-    if (!d || !d->loop) return false;
-    return yasl_loop_del_timer(d->loop, id);
-}
-
 struct yasl_loop *yasl_display_loop(struct yasl_display *d)
 {
     return d ? d->loop : NULL;
 }
-
-struct yasl_loop *yasl_surface_loop(struct yasl_surface *s)
-{
-    return (s && s->display) ? s->display->loop : NULL;
-}