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

diff --git a/include/yasl/loop.h b/include/yasl/loop.h
new file mode 100644
index 0000000..a65fa12
--- /dev/null
+++ b/include/yasl/loop.h
@@ -0,0 +1,46 @@
+#ifndef YASL_LOOP_H
+#define YASL_LOOP_H
+
+#include "yasl/yasl.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/* Optional event loop. Use the display's loop when adding application timers.
+ * A step waits at most timeout_ms: zero polls, a negative value waits indefinitely.
+ * Calls and callbacks use the loop's owning thread. */
+YASL_API struct yasl_loop *yasl_loop_create(void);
+YASL_API void yasl_loop_destroy(struct yasl_loop *l);
+YASL_API int yasl_loop_run(struct yasl_loop *l);
+YASL_API int yasl_loop_step(struct yasl_loop *l, int timeout_ms);
+YASL_API void yasl_loop_quit(struct yasl_loop *l);
+YASL_API void yasl_loop_kick(struct yasl_loop *l);
+YASL_API uint64_t yasl_loop_now_ns(void);
+YASL_API struct yasl_loop *yasl_display_loop(struct yasl_display *d);
+YASL_API int yasl_loop_add_fd(struct yasl_loop *l, int fd, short events,
+                             int (*fn)(int fd, short revents, void *ud), void *ud);
+YASL_API int yasl_loop_del_fd(struct yasl_loop *l, int id);
+YASL_API int yasl_loop_set_fd_events(struct yasl_loop *l, int id, short events);
+
+/* Timers use nanoseconds. Return the next interval to repeat/reschedule, or zero
+ * to remove the timer. A zero ID indicates failure. Loop timers live until they
+ * stop, are deleted, or the loop is destroyed. Surface timers are also canceled
+ * when their surface is destroyed. */
+typedef uint32_t yasl_timer_id;
+typedef uint64_t (*yasl_timer_cb)(void *ud, yasl_timer_id id, uint64_t interval_ns);
+
+#define YASL_MS_TO_NS(ms) ((uint64_t)(ms) * 1000000ull)
+
+YASL_API yasl_timer_id yasl_loop_add_timer(struct yasl_loop *l, uint64_t interval_ns,
+                                          yasl_timer_cb cb, void *ud);
+YASL_API bool yasl_loop_del_timer(struct yasl_loop *l, yasl_timer_id id);
+YASL_API yasl_timer_id yasl_surface_add_timer(struct yasl_surface *s, uint64_t interval_ns,
+                                             yasl_timer_cb cb, void *ud);
+YASL_API bool yasl_surface_del_timer(struct yasl_surface *s, yasl_timer_id id);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* YASL_LOOP_H */