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
 };

backend/sdl.c

@@ -1,6 +1,6 @@
 /*
  * Twin - A Tiny Window System
- * Copyright (c) 2024 National Cheng Kung University, Taiwan
+ * Copyright (c) 2024-2025 National Cheng Kung University, Taiwan
  * All rights reserved.
  */
 
@@ -9,6 +9,10 @@
 #include <stdio.h>
 #include <twin.h>
 
+#ifdef __EMSCRIPTEN__
+#include <emscripten.h>
+#endif
+
 #include "twin_private.h"
 
 typedef struct {
@@ -65,6 +69,14 @@ static void _twin_sdl_destroy(twin_screen_t *screen maybe_unused,
     SDL_Quit();
 }
 
+#ifdef __EMSCRIPTEN__
+/* Placeholder main loop to prevent SDL from complaining during initialization.
+ * This will be replaced by the real main loop in main().
+ */
+static void twin_sdl_placeholder_loop(void) {}
+static bool twin_sdl_placeholder_set = false;
+#endif
+
 static void twin_sdl_damage(twin_screen_t *screen, twin_sdl_t *tx)
 {
     int width, height;
@@ -92,7 +104,17 @@ twin_context_t *twin_sdl_init(int width, int height)
         return NULL;
     }
 
-    if (SDL_Init(SDL_INIT_VIDEO) < 0) {
+#ifdef __EMSCRIPTEN__
+    /* Tell SDL we will manage the main loop externally via
+     * emscripten_set_main_loop, preventing SDL from trying to set up its own
+     * timing before we are ready.
+     */
+    SDL_SetMainReady();  // Prevent SDL from taking over main()
+    SDL_SetHint(SDL_HINT_EMSCRIPTEN_ASYNCIFY, "0");
+    SDL_SetHint(SDL_HINT_EMSCRIPTEN_KEYBOARD_ELEMENT, "#canvas");
+#endif
+
+    if (SDL_Init(SDL_INIT_VIDEO | SDL_INIT_EVENTS) < 0) {
         log_error("%s", SDL_GetError());
         goto bail;
     }
@@ -109,8 +131,23 @@ twin_context_t *twin_sdl_init(int width, int height)
     }
 
     tx->pixels = malloc(width * height * sizeof(*tx->pixels));
+    if (!tx->pixels) {
+        log_error("Failed to allocate pixel buffer");
+        goto bail_window;
+    }
     memset(tx->pixels, 255, width * height * sizeof(*tx->pixels));
 
+#ifdef __EMSCRIPTEN__
+    /* Set up a placeholder main loop to prevent SDL_CreateRenderer from
+     * complaining about missing main loop. The real main loop will be set
+     * up in main() after all initialization is complete.
+     */
+    if (!twin_sdl_placeholder_set) {
+        emscripten_set_main_loop(twin_sdl_placeholder_loop, 0, 0);
+        twin_sdl_placeholder_set = true;
+    }
+#endif
+
     tx->render = SDL_CreateRenderer(tx->win, -1, SDL_RENDERER_ACCELERATED);
     if (!tx->render) {
         log_error("%s", SDL_GetError());
@@ -121,16 +158,30 @@ twin_context_t *twin_sdl_init(int width, int height)
 
     tx->texture = SDL_CreateTexture(tx->render, SDL_PIXELFORMAT_ARGB8888,
                                     SDL_TEXTUREACCESS_STREAMING, width, height);
+    if (!tx->texture) {
+        log_error("%s", SDL_GetError());
+        goto bail_renderer;
+    }
 
     ctx->screen = twin_screen_create(width, height, _twin_sdl_put_begin,
                                      _twin_sdl_put_span, ctx);
+    if (!ctx->screen) {
+        log_error("Failed to create screen");
+        goto bail_texture;
+    }
 
     twin_set_work(twin_sdl_work, TWIN_WORK_REDISPLAY, ctx);
 
     return ctx;
 
+bail_texture:
+    SDL_DestroyTexture(tx->texture);
+bail_renderer:
+    SDL_DestroyRenderer(tx->render);
 bail_pixels:
     free(tx->pixels);
+bail_window:
+    SDL_DestroyWindow(tx->win);
 bail:
     free(ctx->priv);
     free(ctx);
@@ -150,7 +201,9 @@ static bool twin_sdl_poll(twin_context_t *ctx)
     twin_sdl_t *tx = PRIV(ctx);
 
     SDL_Event ev;
+    bool has_event = false;
     while (SDL_PollEvent(&ev)) {
+        has_event = true;
         twin_event_t tev;
         switch (ev.type) {
         case SDL_WINDOWEVENT:
@@ -188,23 +241,88 @@ static bool twin_sdl_poll(twin_context_t *ctx)
             break;
         }
     }
+
+    /* Yield CPU when idle to avoid busy-waiting.
+     * Skip delay if events were processed or screen needs update.
+     */
+    if (!has_event && !twin_screen_damaged(screen)) {
+        SDL_Delay(1); /* 1ms sleep reduces CPU usage when idle */
+    }
+
     return true;
 }
 
 static void twin_sdl_exit(twin_context_t *ctx)
 {
     if (!ctx)
         return;
-    free(PRIV(ctx)->pixels);
+
+    twin_sdl_t *tx = PRIV(ctx);
+
+    /* Clean up SDL resources */
+    if (tx->texture)
+        SDL_DestroyTexture(tx->texture);
+    if (tx->render)
+        SDL_DestroyRenderer(tx->render);
+    if (tx->win)
+        SDL_DestroyWindow(tx->win);
+    SDL_Quit();
+
+    /* Free memory */
+    free(tx->pixels);
     free(ctx->priv);
     free(ctx);
 }
 
+#ifdef __EMSCRIPTEN__
+/* Emscripten main loop state */
+static void (*g_wasm_init_callback)(twin_context_t *) = NULL;
+static bool g_wasm_initialized = false;
+
+/* Main loop callback for Emscripten */
+static void twin_sdl_wasm_loop(void *arg)
+{
+    twin_context_t *ctx = (twin_context_t *) arg;
+
+    /* Perform one-time initialization on first iteration */
+    if (!g_wasm_initialized && g_wasm_init_callback) {
+        g_wasm_init_callback(ctx);
+        g_wasm_initialized = true;
+    }
+
+    twin_dispatch_once(ctx);
+}
+#endif
+
+/* Backend start function: unified entry point for both native and WebAssembly
+ */
+static void twin_sdl_start(twin_context_t *ctx,
+                           void (*init_callback)(twin_context_t *))
+{
+#ifdef __EMSCRIPTEN__
+    /* WebAssembly: Set up Emscripten main loop */
+    g_wasm_init_callback = init_callback;
+    g_wasm_initialized = false;
+
+    emscripten_cancel_main_loop(); /* Cancel placeholder from init */
+    emscripten_set_main_loop_arg(twin_sdl_wasm_loop, ctx, 0, 1);
+#else
+    /* Native: Initialize immediately and enter standard dispatch loop */
+    if (init_callback)
+        init_callback(ctx);
+
+    /* Use twin_dispatch_once() to ensure work queue and timeouts run */
+    while (twin_dispatch_once(ctx))
+        ;
+#endif
+}
+
 /* Register the SDL backend */
 
 const twin_backend_t g_twin_backend = {
     .init = twin_sdl_init,
     .configure = twin_sdl_configure,
     .poll = twin_sdl_poll,
+    .start = twin_sdl_start,
     .exit = twin_sdl_exit,
 };