Improve backend architecture and memory safety

Backend improvements:
- SDL: Add comprehensive error handling with proper resource cleanup
- SDL: Implement smart conditional delay to prevent CPU busy-wait
- SDL: Fix resource leaks in initialization and exit paths
- fbdev: Fix critical memory leaks and invalid return statements
- fbdev: Add NULL checks for screen creation
- All backends: Standardize main loop using twin_dispatch_once()

API refactoring:
- Add twin_run() as unified application entry point
- Hide platform-specific details from public API

Performance:
- Reduce idle CPU usage from 100% to <1% in SDL backend
- Maintain zero-latency event handling and screen updates

Author: jserv

apps/main.c

@@ -82,6 +82,39 @@ static void sigint_handler(int sig)
     exit(1);
 }
 
+/* Initialize demo applications based on build configuration.
+ * Shared by both native and WebAssembly builds.
+ */
+static void init_demo_apps(twin_context_t *ctx)
+{
+    twin_screen_t *screen = ctx->screen;
+#if defined(CONFIG_DEMO_MULTI)
+    apps_multi_start(screen, "Demo", 100, 100, 400, 400);
+#endif
+#if defined(CONFIG_DEMO_HELLO)
+    apps_hello_start(screen, "Hello, World", 0, 0, 200, 200);
+#endif
+#if defined(CONFIG_DEMO_CLOCK)
+    apps_clock_start(screen, "Clock", 10, 10, 200, 200);
+#endif
+#if defined(CONFIG_DEMO_CALCULATOR)
+    apps_calc_start(screen, "Calculator", 100, 100, 200, 200);
+#endif
+#if defined(CONFIG_DEMO_LINE)
+    apps_line_start(screen, "Line", 0, 0, 200, 200);
+#endif
+#if defined(CONFIG_DEMO_SPLINE)
+    apps_spline_start(screen, "Spline", 20, 20, 400, 400);
+#endif
+#if defined(CONFIG_DEMO_ANIMATION)
+    apps_animation_start(screen, "Viewer", ASSET_PATH "nyancat.gif", 20, 20);
+#endif
+#if defined(CONFIG_DEMO_IMAGE)
+    apps_image_start(screen, "Viewer", 20, 20);
+#endif
+    twin_screen_set_active(screen, screen->top);
+}
+
 int main(void)
 {
     tx = twin_create(WIDTH, HEIGHT);
@@ -106,34 +139,8 @@ int main(void)
     twin_screen_set_background(
         tx->screen, load_background(tx->screen, ASSET_PATH "/tux.png"));
 
-#if defined(CONFIG_DEMO_MULTI)
-    apps_multi_start(tx->screen, "Demo", 100, 100, 400, 400);
-#endif
-#if defined(CONFIG_DEMO_HELLO)
-    apps_hello_start(tx->screen, "Hello, World", 0, 0, 200, 200);
-#endif
-#if defined(CONFIG_DEMO_CLOCK)
-    apps_clock_start(tx->screen, "Clock", 10, 10, 200, 200);
-#endif
-#if defined(CONFIG_DEMO_CALCULATOR)
-    apps_calc_start(tx->screen, "Calculator", 100, 100, 200, 200);
-#endif
-#if defined(CONFIG_DEMO_LINE)
-    apps_line_start(tx->screen, "Line", 0, 0, 200, 200);
-#endif
-#if defined(CONFIG_DEMO_SPLINE)
-    apps_spline_start(tx->screen, "Spline", 20, 20, 400, 400);
-#endif
-#if defined(CONFIG_DEMO_ANIMATION)
-    apps_animation_start(tx->screen, "Viewer", ASSET_PATH "nyancat.gif", 20,
-                         20);
-#endif
-#if defined(CONFIG_DEMO_IMAGE)
-    apps_image_start(tx->screen, "Viewer", 20, 20);
-#endif
-
-    twin_screen_set_active(tx->screen, tx->screen->top);
-    twin_dispatch(tx);
+    /* Start application with unified API (handles native and WebAssembly) */
+    twin_run(tx, init_demo_apps);
 
     return 0;
 }

backend/fbdev.c

@@ -236,7 +236,7 @@ twin_context_t *twin_fbdev_init(int width, int height)
         return NULL;
     ctx->priv = calloc(1, sizeof(twin_fbdev_t));
     if (!ctx->priv)
-        return NULL;
+        goto bail;
 
     twin_fbdev_t *tx = ctx->priv;
 
@@ -264,7 +264,7 @@ twin_context_t *twin_fbdev_init(int width, int height)
     /* Examine if framebuffer mapping is valid */
     if (tx->fb_base == MAP_FAILED) {
         log_error("Failed to map framebuffer memory");
-        return;
+        goto bail_vt_fd;
     }
 
     const twin_put_span_t fbdev_put_spans[] = {
@@ -276,6 +276,10 @@ twin_context_t *twin_fbdev_init(int width, int height)
     ctx->screen = twin_screen_create(
         width, height, NULL, fbdev_put_spans[tx->fb_var.bits_per_pixel / 8 - 2],
         ctx);
+    if (!ctx->screen) {
+        log_error("Failed to create screen");
+        goto bail_fb_unmap;
+    }
 
     /* Create Linux input system object */
     tx->input = twin_linux_input_create(ctx->screen);
@@ -294,6 +298,9 @@ twin_context_t *twin_fbdev_init(int width, int height)
 
 bail_screen:
     twin_screen_destroy(ctx->screen);
+bail_fb_unmap:
+    if (tx->fb_base != MAP_FAILED)
+        munmap(tx->fb_base, tx->fb_len);
 bail_vt_fd:
     close(tx->vt_fd);
 bail_fb_fd:
@@ -327,9 +334,27 @@ static void twin_fbdev_exit(twin_context_t *ctx)
     free(ctx);
 }
 
+/* Start function for fbdev backend
+ * Note: fbdev uses Linux input system with background thread for events,
+ * so we use the standard dispatcher for work queue and timeout processing.
+ */
+static void twin_fbdev_start(twin_context_t *ctx,
+                             void (*init_callback)(twin_context_t *))
+{
+    if (init_callback)
+        init_callback(ctx);
+
+    /* Use standard dispatcher to ensure work queue and timeouts run.
+     * Events are handled by linux_input background thread.
+     */
+    while (twin_dispatch_once(ctx))
+        ;
+}
+
 /* Register the Linux framebuffer backend */
 const twin_backend_t g_twin_backend = {
     .init = twin_fbdev_init,
     .configure = twin_fbdev_configure,
+    .start = twin_fbdev_start,
     .exit = twin_fbdev_exit,
 };

backend/headless.c

@@ -401,19 +401,42 @@ static twin_context_t *twin_headless_init_dummy(int width, int height)
     (void) height;
     return NULL;
 }
+
+static void twin_headless_start_dummy(twin_context_t *ctx,
+                                      void (*init_callback)(twin_context_t *))
+{
+    (void) ctx;
+    (void) init_callback;
+}
 #endif /* HAVE_POSIX_SHM */
 
+#ifdef HAVE_POSIX_SHM
+/* Start function for headless backend */
+static void twin_headless_start(twin_context_t *ctx,
+                                void (*init_callback)(twin_context_t *))
+{
+    if (init_callback)
+        init_callback(ctx);
+
+    /* Use standard dispatcher to ensure work queue and timeouts run */
+    while (twin_dispatch_once(ctx))
+        ;
+}
+#endif
+
 /* Register the headless backend */
 const twin_backend_t g_twin_backend = {
 #ifdef HAVE_POSIX_SHM
     .init = twin_headless_init,
     .configure = twin_headless_configure,
     .poll = twin_headless_poll,
+    .start = twin_headless_start,
     .exit = twin_headless_exit,
 #else
     .init = twin_headless_init_dummy,
     .configure = twin_headless_config_dummy,
     .poll = twin_headless_poll_dummy,
+    .start = twin_headless_start_dummy,
     .exit = twin_headless_exit_dummy,
 #endif
 };