xbintsc 0.5.32 → 0.5.37

package/runtime/ext_gui/gui.cpp

@@ -19,6 +19,7 @@
 #include "paint.h"
 
 #include <stdio.h>
+#include <stdlib.h>
 #include <string.h>
 
 namespace guidev {
@@ -89,20 +90,49 @@ static void xt_gui_gc_scan_roots(void) {
     xt_gc_mark_value(win.document_object);
     for (const auto &entry : win.node_handles) xt_gc_mark_value(entry.second);
     for (const auto &entry : win.node_listeners) {
-      for (const XtGuiNodeListener &listener : entry.second) xt_gc_mark_value(listener.fn);
+      for (const XtGuiNodeListener &listener : entry.second) {
+        xt_gc_mark_value(listener.fn);
+        xt_gc_mark_value(listener.signal);
+      }
+    }
+    for (const XtGuiWindowListener &listener : win.window_listeners) {
+      xt_gc_mark_value(listener.fn);
+      xt_gc_mark_value(listener.signal);
     }
     for (const XtGuiAnimationFrame &frame : win.animation_frames) xt_gc_mark_value(frame.fn);
     for (const XtGuiAnimationFrame &frame : win.running_frames) xt_gc_mark_value(frame.fn);
+    for (const xt_value list : win.media_lists) xt_gc_mark_value(list);
   }
 }
 
 /* -- initialisation ------------------------------------------------------- */
 
-static int ensure_init(void) {  if (g_sdl_initialized) return 1;
-  xt_gc_register_root_provider(xt_gui_gc_scan_roots);
+/**
+ * Exit status for "this host cannot run a GUI program": no video driver, or no
+ * GPU device the SDL_GPU backends accept. It is deliberately distinct from a
+ * failed program so a CI script (or a user) can skip the run instead of
+ * reporting a crash. 77 is the autotools "skip" convention; `ci.yml` treats it
+ * that way for the provisional macOS job.
+ */
+const int kGuiUnavailableExit = 77;
+
+/** Report a window that could not be created as a JavaScript `Error`. Returning
+ * `undefined` used to surface one line later as `Cannot read properties of
+ * undefined (reading 'on')`, which hid the real diagnostic. */
+static void throw_gui_error(const char *message) {
+  xt_value text = xt_string_from_cstr(message);
+  xt_throw(xt_error_ctor_by_name(xt_string_from_cstr("Error"), 1, &text));
+}
+
+static void ensure_init(void) {
+  if (g_sdl_initialized) return;
   if (!SDL_Init(SDL_INIT_VIDEO)) {
     fprintf(stderr, "xt_gui: SDL_Init failed: %s\n", SDL_GetError());
-    return 0;
+    fprintf(stderr,
+            "xt_gui: the GUI extension needs a display (or a virtual one such as Xvfb); "
+            "exiting with status %d.\n",
+            kGuiUnavailableExit);
+    exit(kGuiUnavailableExit);
   }
   /* Accept every shader format so the same code runs on Metal, Vulkan and
    * D3D12; the backend only needs the one it supports. The engine ships MSL,
@@ -113,11 +143,17 @@ static int ensure_init(void) {  if (g_sdl_initialized) return 1;
   g_device = SDL_CreateGPUDevice(formats, false, NULL);
   if (g_device == NULL) {
     fprintf(stderr, "xt_gui: SDL_CreateGPUDevice failed: %s\n", SDL_GetError());
+    fprintf(stderr,
+            "xt_gui: the GUI extension needs a Metal (macOS), Vulkan or D3D12 device; "
+            "this host does not provide a usable one. Exiting with status %d.\n",
+            kGuiUnavailableExit);
     SDL_Quit();
-    return 0;
+    exit(kGuiUnavailableExit);
   }
+  /* Registered only once a window can exist: a failed init has nothing to
+   * mark, and a caller that cannot retry never needs a second provider. */
+  xt_gc_register_root_provider(xt_gui_gc_scan_roots);
   g_sdl_initialized = 1;
-  return 1;
 }
 
 /* -- window lookup -------------------------------------------------------- */
@@ -149,6 +185,9 @@ void xt_gui_quit_window(XtGuiWindow *win) {
   win->open = 0;
   xt_gui_emit(win, "close");
   win->animation_frames.clear();
+  win->media_lists.clear();
+  win->media_lists_by_query.clear();
+  win->window_listeners.clear();
   xt_gui_media_shutdown(win);
   xt_gui_canvas_shutdown(win);
   xt_gui_handles_reset(win);
@@ -190,12 +229,12 @@ static int xt_gui_int_or(xt_value value, int fallback) {
 /* Build (and record) one window. Shared by `createWindow` and the implicit
  * window a page written against `window`/`document` gets on first access. */
 static XtGuiWindow *create_window_record(const char *title, int width, int height,
-                                         bool high_density) {
+                                         bool high_density, SDL_WindowFlags extra_flags) {
   if (g_window_count >= XT_GUI_MAX_WINDOWS) {
     fprintf(stderr, "xt_gui: too many windows (max %d)\n", XT_GUI_MAX_WINDOWS);
     return NULL;
   }
-  SDL_WindowFlags flags = SDL_WINDOW_RESIZABLE;
+  SDL_WindowFlags flags = extra_flags;
   if (high_density) flags |= SDL_WINDOW_HIGH_PIXEL_DENSITY;
   SDL_Window *window = SDL_CreateWindow(title, width, height, flags);
   if (window == NULL) {
@@ -225,6 +264,11 @@ static XtGuiWindow *create_window_record(const char *title, int width, int heigh
   record->animation_frames.clear();
   record->media_players.clear();
   record->next_animation_frame_id = 1;
+  record->scroll_x = 0.0f;
+  record->scroll_y = 0.0f;
+  record->focused = 0;
+  record->media_lists.clear();
+  record->media_lists_by_query.clear();
   record->background[0] = 0.08f;
   record->background[1] = 0.09f;
   record->background[2] = 0.11f;
@@ -254,20 +298,43 @@ xt_value xt_gui_ensure_window(void) {
   for (int i = g_window_count - 1; i >= 0; i--) {
     if (g_windows[i].open) return g_windows[i].object;
   }
-  if (!ensure_init()) return XT_UNDEFINED;
-  XtGuiWindow *record = create_window_record("xbintsc gui", 800, 600, true);
-  if (record == NULL) return XT_UNDEFINED;
+  ensure_init();
+  XtGuiWindow *record =
+      create_window_record("xbintsc gui", 800, 600, true, SDL_WINDOW_RESIZABLE);
+  if (record == NULL) {
+    throw_gui_error("xbintsc gui: could not open the implicit window (see the diagnostic above)");
+    return XT_UNDEFINED;
+  }
   g_implicit_window = 1;
   return record->object;
 }
 
 extern "C" xt_value xt_gui_create_window(int32_t argc, xt_value *argv) {
-  if (!ensure_init()) return XT_UNDEFINED;
+  ensure_init();
 
   const char *title = "xbintsc gui";
   int width = 800;
   int height = 600;
   bool high_density = true;
+  SDL_WindowFlags flags = SDL_WINDOW_RESIZABLE;
+  bool has_x = false;
+  bool has_y = false;
+  bool has_opacity = false;
+  int x = 0;
+  int y = 0;
+  float opacity = 1.0f;
+  bool maximized = false;
+  bool minimized = false;
+  auto option_bool = [](xt_value options, const char *name, bool fallback) {
+    xt_value value = xt_object_get_cstr(options, name);
+    return XT_IS_BOOL(value) ? (xt_truthy(value) != 0) : fallback;
+  };
+  auto option_number = [](xt_value options, const char *name, bool *present, double fallback) {
+    xt_value value = xt_object_get_cstr(options, name);
+    if (!XT_IS_NUMBER(value)) return fallback;
+    *present = true;
+    return xt_to_number(value);
+  };
   xt_value options = xt_arg(argc, argv, 0);
   if (XT_IS_OBJECT(options)) {
     title = xt_gui_string_or(xt_object_get_cstr(options, "title"), title);
@@ -275,6 +342,19 @@ extern "C" xt_value xt_gui_create_window(int32_t argc, xt_value *argv) {
     height = xt_gui_int_or(xt_object_get_cstr(options, "height"), height);
     xt_value density = xt_object_get_cstr(options, "highDensity");
     if (!XT_IS_UNDEFINED(density)) high_density = xt_truthy(density);
+    /* Window flags and placement: the rest of the options object used to be
+     * ignored, which made `{ resizable: false }` or `{ borderless: true }`
+     * silently open a plain window. */
+    if (!option_bool(options, "resizable", true)) flags &= ~SDL_WINDOW_RESIZABLE;
+    if (option_bool(options, "borderless", false)) flags |= SDL_WINDOW_BORDERLESS;
+    if (option_bool(options, "alwaysOnTop", false)) flags |= SDL_WINDOW_ALWAYS_ON_TOP;
+    if (option_bool(options, "hidden", false)) flags |= SDL_WINDOW_HIDDEN;
+    if (option_bool(options, "fullscreen", false)) flags |= SDL_WINDOW_FULLSCREEN;
+    x = (int)option_number(options, "x", &has_x, 0);
+    y = (int)option_number(options, "y", &has_y, 0);
+    opacity = (float)option_number(options, "opacity", &has_opacity, 1.0);
+    maximized = option_bool(options, "maximized", false);
+    minimized = option_bool(options, "minimized", false);
   } else if (XT_IS_STRING(options)) {
     title = xt_string_data(options);
     width = xt_gui_int_or(xt_arg(argc, argv, 1), width);
@@ -303,8 +383,17 @@ extern "C" xt_value xt_gui_create_window(int32_t argc, xt_value *argv) {
     return record->object;
   }
 
-  XtGuiWindow *record = create_window_record(title, width, height, high_density);
-  return record != NULL ? record->object : XT_UNDEFINED;
+  XtGuiWindow *record = create_window_record(title, width, height, high_density, flags);
+  if (record == NULL) {
+    throw_gui_error("xbintsc gui: could not open a window (see the diagnostic above)");
+    return XT_UNDEFINED;
+  }
+  if (has_x || has_y) SDL_SetWindowPosition(record->window, has_x ? x : SDL_WINDOWPOS_CENTERED,
+                                            has_y ? y : SDL_WINDOWPOS_CENTERED);
+  if (has_opacity) SDL_SetWindowOpacity(record->window, opacity);
+  if (maximized) SDL_MaximizeWindow(record->window);
+  if (minimized) SDL_MinimizeWindow(record->window);
+  return record->object;
 }
 
 /* -- run() / quit() ------------------------------------------------------- */

package/runtime/ext_gui/gui_engine.h

@@ -45,6 +45,9 @@ xt_value xt_browser_local_storage(int32_t argc, xt_value *argv);
 xt_value xt_browser_missing(int32_t argc, xt_value *argv);
 /** A DOM type name (`Image`, `HTMLCanvasElement`, …) as a constructor value. */
 xt_value xt_browser_type(int32_t argc, xt_value *argv);
+/** `createImageBitmap(source)`, exposed as a global *value*: returns the
+ * closure the compiler stores for the bare identifier. */
+xt_value xt_browser_create_image_bitmap(int32_t argc, xt_value *argv);
 xt_value xt_browser_request_animation_frame(int32_t argc, xt_value *argv);
 xt_value xt_browser_cancel_animation_frame(int32_t argc, xt_value *argv);
 xt_value xt_browser_match_media(int32_t argc, xt_value *argv);
@@ -52,6 +55,8 @@ xt_value xt_browser_computed_style(int32_t argc, xt_value *argv);
 xt_value xt_browser_escape(int32_t argc, xt_value *argv);
 xt_value xt_browser_alert(int32_t argc, xt_value *argv);
 xt_value xt_browser_prompt(int32_t argc, xt_value *argv);
+/** The bare `confirm(message)` global (the window method shares the engine). */
+xt_value xt_browser_confirm_global(int32_t argc, xt_value *argv);
 /** Install `innerWidth`, `setTimeout`, `navigator`, … on the window prototype. */
 void xt_browser_install_window(xt_value proto);
 /** Poll and dispatch pending SDL input events once (the browser frame pump in
@@ -63,11 +68,13 @@ void xt_browser_schedule_frame(void);
 /** Whether `run()` currently owns the frame loop (the pump then stays idle). */
 int xt_gui_run_active(void);
 
-/* Web Audio objects (`audio.cpp`). */
-/** `AudioContext.prototype` — also the `instanceof AudioContext` target. */
+/* Web Audio objects (`audio.cpp`).
+ * `AudioContext.prototype` — also the `instanceof AudioContext` target. */
 xt_value xt_gui_audio_proto(void);
-/** `new AudioContext(...)`: it has no mixer backend yet, so the graph records
- * its shape and parameters but nothing is rendered to the sound device. */
+/** `new AudioContext(...)`: builds a real graph (mixer in `audio_mixer.cpp`)
+ * and decodes through `audio_decode.cpp` + the optional media backend. The
+ * device opens on the first `start()`/`resume()`; a headless host stays silent
+ * while the graph still renders. */
 xt_value xt_gui_audio_create(int32_t argc, xt_value *argv);
 
 #ifdef __cplusplus
@@ -92,6 +99,22 @@ struct XtGuiNodeListener {
   xt_value fn;
   bool once;
   bool capture;
+  /** `{ passive: true }`: `preventDefault()` is ignored while it runs. */
+  bool passive;
+  /** `{ signal }`: the listener is skipped once the signal is aborted. */
+  xt_value signal;
+};
+
+/** One window-level listener (`window.addEventListener`). Window delivery has
+ * no capture phase, but `capture` is still part of listener identity, as in the
+ * DOM; `once`, `passive` and `signal` behave like the element ones. */
+struct XtGuiWindowListener {
+  std::string type;
+  xt_value fn;
+  bool once;
+  bool capture;
+  bool passive;
+  xt_value signal;
 };
 
 /** One pending `requestAnimationFrame` callback. */
@@ -137,6 +160,14 @@ struct XtGuiWindow {
   float background[4];
   int width;
   int height;
+  /** Page scroll offset (CSS pixels); painting and hit testing subtract it. */
+  float scroll_x = 0;
+  float scroll_y = 0;
+  /** `document.hasFocus()` state, toggled by `window.focus()` / `blur()`. */
+  int focused = 0;
+  /** Live `matchMedia` lists for this window (one per query string). */
+  std::vector<xt_value> media_lists;
+  std::unordered_map<std::string, xt_value> media_lists_by_query;
 
   /* -- DOM object model (element handles + events) ----------------------- */
   /** `document` handle for this window (lazily created). */
@@ -151,6 +182,8 @@ struct XtGuiWindow {
   std::unordered_map<const xtgui::Node *, xt_value> node_handles;
   /** Element-level listeners, keyed by node. */
   std::unordered_map<const xtgui::Node *, std::vector<XtGuiNodeListener>> node_listeners;
+  /** Window-level listeners registered through `window.addEventListener`. */
+  std::vector<XtGuiWindowListener> window_listeners;
   /** Set by a DOM mutation; consumed by the frame loop before repainting. */
   int struct_dirty = 0;
   /** Callbacks queued for the next frame, plus the id counter. */
@@ -208,6 +241,9 @@ void xt_gui_run_scripts(XtGuiWindow *win);
 void xt_gui_script_gc_scan(void);
 /** Shared prototype carrying the window methods. */
 xt_value xt_gui_window_proto(void);
+/** Install `on` / `off` / `addEventListener` / `removeEventListener` (the
+ * listener options bag is parsed in `window_events.cpp`). */
+void xt_gui_install_window_events(xt_value proto);
 /** Release GPU claim + destroy the window and mark the record closed. */
 void xt_gui_quit_window(XtGuiWindow *win);
 /** Deliver `event` (no arguments) to handlers registered with `on`. */
@@ -221,6 +257,22 @@ void xt_gui_render_window(XtGuiWindow *win);
 void xt_gui_run_animation_frames(XtGuiWindow *win, double timestamp_ms);
 /** Current logical window size (CSS viewport), in pixels. */
 void xt_gui_window_viewport(XtGuiWindow *win, float *width, float *height);
+/** Scroll the page to `(x, y)` (clamped to the content bounds), repaint and
+ * notify live `matchMedia` lists. */
+void xt_gui_scroll_to(XtGuiWindow *win, float x, float y);
+/** The largest valid scroll offset for the current layout. */
+void xt_gui_scroll_bounds(XtGuiWindow *win, float *max_x, float *max_y);
+/** Re-evaluate every live `matchMedia` list (window resize / scroll). */
+void xt_gui_media_lists_notify(XtGuiWindow *win);
+/** `window.matchMedia(query)`: the cached live list for this window. */
+xt_value xt_browser_media_list(xt_value window, const std::string &query);
+/** `window.confirm` / `window.prompt` (native dialog only when
+ * `XT_GUI_DIALOGS=1`; otherwise the message goes to stderr and the documented
+ * default is returned). */
+xt_value xt_browser_confirm(XtGuiWindow *win, int32_t argc, xt_value *argv);
+xt_value xt_browser_prompt(XtGuiWindow *win, int32_t argc, xt_value *argv);
+/** Install `scrollTo`/`scrollBy`/`scrollX`/`scrollY`/`focus`/`blur`. */
+void xt_browser_install_window_navigation(xt_value proto);
 /** CSS-like descriptor of the deepest element at (x, y), or `""` (test/debug). */
 std::string xt_gui_hit_test(XtGuiWindow *win, float x, float y);
 /** Synthesise a pointer event (`mousemove`/`mousedown`/`mouseup`/`click`). */

package/runtime/ext_gui/gui_events.cpp

@@ -4,9 +4,11 @@
  */
 
 #include "gui_internal.h"
+#include "listener_options.h"
 
 #include "paint.h"
 
+#include <algorithm>
 #include <stdio.h>
 #include <string.h>
 
@@ -20,22 +22,39 @@ void xt_gui_emit(XtGuiWindow *win, const char *event) {
   xt_gui_emit_payload(win, event, XT_UNDEFINED);
 }
 
+/** Drop one window listener (by identity: type + fn + capture). */
+static void remove_window_listener(XtGuiWindow *win, const XtGuiWindowListener &listener) {
+  std::vector<XtGuiWindowListener> &listeners = win->window_listeners;
+  for (auto it = listeners.begin(); it != listeners.end(); ++it) {
+    if (it->type == listener.type && it->capture == listener.capture &&
+        xt_truthy(xt_seq(it->fn, listener.fn))) {
+      listeners.erase(it);
+      return;
+    }
+  }
+}
+
 void xt_gui_emit_payload(XtGuiWindow *win, const char *event, xt_value payload) {
   if (win == NULL || !XT_IS_OBJECT(win->object)) return;
-  xt_value listeners = xt_object_get_cstr(win->object, "__xt_gui_events");
-  if (!XT_IS_OBJECT(listeners)) return;
-  xt_value array = xt_object_get(listeners, xt_string_from_cstr(event));
-  if (!XT_IS_ARRAY(array)) return;
   xt_value args[1];
   int32_t count = 0;
   if (!XT_IS_UNDEFINED(payload)) {
     args[0] = payload;
     count = 1;
   }
-  int32_t listener_count = (int32_t)xt_to_number(xt_array_length(array));
-  for (int32_t i = 0; i < listener_count; i++) {
-    xt_value fn = xt_array_get(array, xt_number((double)i));
-    if (XT_IS_FUNCTION(fn)) xt_call_with_this(fn, win->object, count, args);
+  /* Snapshot the list: a handler may register or remove listeners while it
+   * runs, and the DOM runs the batch as it stood when dispatch started. */
+  std::vector<XtGuiWindowListener> snapshot = win->window_listeners;
+  for (const XtGuiWindowListener &listener : snapshot) {
+    if (listener.type != event) continue;
+    /* `{ signal }` removes the listener at abort time (checked here, so no
+     * callback plumbing is needed inside the signal). */
+    if (xt_gui_signal_aborted(listener.signal)) {
+      remove_window_listener(win, listener);
+      continue;
+    }
+    if (listener.once) remove_window_listener(win, listener);
+    if (XT_IS_FUNCTION(listener.fn)) xt_call_with_this(listener.fn, win->object, count, args);
   }
 }
 
@@ -52,6 +71,53 @@ void xt_gui_flush_dom(XtGuiWindow *win) {
   win->geometry.dirty = 1;
 }
 
+/* -- page scroll ---------------------------------------------------------- */
+
+namespace {
+
+void content_bounds(const xtgui::LayoutBox *box, float *max_x, float *max_y) {
+  if (box == nullptr) return;
+  float right = box->x + box->width;
+  float bottom = box->y + box->height;
+  if (right > *max_x) *max_x = right;
+  if (bottom > *max_y) *max_y = bottom;
+  for (const std::unique_ptr<xtgui::LayoutBox> &child : box->children) {
+    content_bounds(child.get(), max_x, max_y);
+  }
+}
+
+}  // namespace
+
+void xt_gui_scroll_bounds(XtGuiWindow *win, float *max_x, float *max_y) {
+  float content_x = 0;
+  float content_y = 0;
+  if (win != nullptr && win->document != nullptr) {
+    xt_gui_flush_dom(win);
+    content_bounds(win->document->layout().root(), &content_x, &content_y);
+  }
+  float viewport_width = 0;
+  float viewport_height = 0;
+  if (win != nullptr) xt_gui_window_viewport(win, &viewport_width, &viewport_height);
+  *max_x = content_x > viewport_width ? content_x - viewport_width : 0.0f;
+  *max_y = content_y > viewport_height ? content_y - viewport_height : 0.0f;
+}
+
+void xt_gui_scroll_to(XtGuiWindow *win, float x, float y) {
+  if (win == nullptr) return;
+  float max_x = 0;
+  float max_y = 0;
+  xt_gui_scroll_bounds(win, &max_x, &max_y);
+  if (x < 0.0f) x = 0.0f;
+  if (y < 0.0f) y = 0.0f;
+  if (x > max_x) x = max_x;
+  if (y > max_y) y = max_y;
+  if (x == win->scroll_x && y == win->scroll_y) return;
+  win->scroll_x = x;
+  win->scroll_y = y;
+  win->geometry.dirty = 1;
+  xt_gui_emit(win, "scroll");
+}
+
 static XtGuiWindow *xt_gui_find_by_window_id(SDL_WindowID id) {
   SDL_Window *window = SDL_GetWindowFromID(id);
   if (window == NULL) return NULL;
@@ -66,7 +132,8 @@ static XtGuiWindow *xt_gui_find_by_window_id(SDL_WindowID id) {
 /** Deepest element under (x, y), or NULL. */
 static const xtgui::Node *xt_gui_hit_node(XtGuiWindow *win, float x, float y) {
   if (win->document == nullptr) return nullptr;
-  const xtgui::LayoutBox *box = win->document->layout().hitTest(x, y);
+  const xtgui::LayoutBox *box =
+      win->document->layout().hitTest(x + win->scroll_x, y + win->scroll_y);
   const xtgui::Node *node = box != nullptr ? box->node : nullptr;
   while (node != nullptr && !node->isElement()) node = node->parent;
   return node;
@@ -122,6 +189,8 @@ void xt_gui_dispatch_wheel(XtGuiWindow *win, float x, float y, float delta_x, fl
   const xtgui::Node *node = xt_gui_hit_node(win, x, y);
   if (node != nullptr) xt_gui_emit_dom_event(win, "wheel", node, payload);
   xt_gui_emit_payload(win, "wheel", payload);
+  /* Default action: scroll the page (content that fits does not move). */
+  xt_gui_scroll_to(win, win->scroll_x + delta_x, win->scroll_y + delta_y);
 }
 
 static xt_value xt_gui_key_payload(const char *type, const char *key, const char *code, bool repeat,
@@ -168,6 +237,7 @@ void handle_event(const SDL_Event *event) {
     /* Web 'resize', so a document can re-measure on a window change in every
      * host (a browser already fires one). */
     xt_gui_emit(win, "resize");
+    xt_gui_media_lists_notify(win);
     return;
   }
 
@@ -273,6 +343,7 @@ void xt_gui_render_window(XtGuiWindow *win) {
   if (can_paint && win->geometry.dirty && win->document != nullptr) {
     xtgui::DisplayList list;
     xtgui::xt_paint_build(win->document->layout().root(), list, viewport_width, viewport_height);
+    xt_paint_translate(list, -win->scroll_x, -win->scroll_y);
     xt_gui_geometry_upload(g_device, &win->geometry, list);
     float density = SDL_GetWindowPixelDensity(win->window);
     float text_scale = density > 0.0f ? density : 1.0f;

package/runtime/ext_gui/image_bitmap.cpp

@@ -0,0 +1,28 @@
+/*
+ * xbintsc GUI engine — `ImageBitmap` pixel storage.
+ */
+
+#include "image_bitmap.h"
+
+#include <unordered_map>
+
+namespace xtgui {
+namespace {
+
+std::unordered_map<uint64_t, Image> g_bitmaps;
+uint64_t g_next_bitmap = 1;
+
+}  // namespace
+
+uint64_t xt_image_bitmap_add(const Image &image) {
+  const uint64_t id = g_next_bitmap++;
+  g_bitmaps[id] = image;
+  return id;
+}
+
+const Image *xt_image_bitmap_get(uint64_t id) {
+  auto found = g_bitmaps.find(id);
+  return found == g_bitmaps.end() ? nullptr : &found->second;
+}
+
+}  // namespace xtgui

package/runtime/ext_gui/image_bitmap.h

@@ -0,0 +1,26 @@
+/*
+ * xbintsc GUI engine — `ImageBitmap` storage.
+ *
+ * `createImageBitmap(source)` returns a settled promise of an immutable
+ * bitmap. The pixels stay in C++ so `texImage2D` can consume them without
+ * materialising a JavaScript array; the handle object carries the numeric id
+ * under `__xt_bitmap`.
+ */
+#ifndef XT_GUI_IMAGE_BITMAP_H
+#define XT_GUI_IMAGE_BITMAP_H
+
+#include <cstdint>
+
+#include "image.h"
+
+namespace xtgui {
+
+/** Store a decoded bitmap and return its process-wide id. */
+uint64_t xt_image_bitmap_add(const Image &image);
+
+/** Look up a bitmap; null when the id is unknown. */
+const Image *xt_image_bitmap_get(uint64_t id);
+
+}  // namespace xtgui
+
+#endif /* XT_GUI_IMAGE_BITMAP_H */

package/runtime/ext_gui/image_bitmap_browser.cpp

@@ -0,0 +1,136 @@
+/*
+ * xbintsc GUI engine — `createImageBitmap`.
+ *
+ * The browser entry point returns a promise (as it does on the web), so code
+ * that writes `const bitmap = await createImageBitmap(canvas)` works unchanged.
+ * The pixels are kept in `image_bitmap.cpp`; `texImage2D` reads the same
+ * registry through the bitmap's `__xt_bitmap` id.
+ */
+
+#include "gui_engine.h"
+#include "dom_api_internal.h"
+
+#include <cstring>
+#include <string>
+#include <vector>
+
+#include "image_bitmap.h"
+#include "webgl.h"
+
+namespace {
+
+void flip_rows(std::vector<unsigned char> *pixels, int width, int height) {
+  const size_t stride = (size_t)width * 4;
+  std::vector<unsigned char> row(stride);
+  for (int y = 0; y < height / 2; y++) {
+    unsigned char *top = pixels->data() + (size_t)y * stride;
+    unsigned char *bottom = pixels->data() + (size_t)(height - 1 - y) * stride;
+    memcpy(row.data(), top, stride);
+    memcpy(top, bottom, stride);
+    memcpy(bottom, row.data(), stride);
+  }
+}
+
+bool source_pixels(xt_value source, xtgui::Image *out) {
+  /* ImageData / another bitmap-like object: width, height, data. */
+  xt_value width_value = xt_object_get_cstr(source, "width");
+  xt_value height_value = xt_object_get_cstr(source, "height");
+  xt_value data = xt_object_get_cstr(source, "data");
+  if (XT_IS_OBJECT(data) && XT_IS_NUMBER(width_value) && XT_IS_NUMBER(height_value)) {
+    const int width = (int)xt_to_number(width_value);
+    const int height = (int)xt_to_number(height_value);
+    const std::vector<uint8_t> bytes = domapi::webgl_bytes(data);
+    if (width <= 0 || height <= 0 || bytes.size() < (size_t)width * height * 4) return false;
+    out->width = width;
+    out->height = height;
+    out->pixels.assign(bytes.begin(), bytes.begin() + (size_t)width * height * 4);
+    return true;
+  }
+
+  XtGuiWindow *win = nullptr;
+  xtgui::Node *node = domapi::resolve_node(source, &win);
+  if (node == nullptr || !node->isElement()) return false;
+  if (node->isTag("img")) {
+    const std::string *src = node->attr("src");
+    const xtgui::Image *image = src != nullptr ? xtgui::xt_image_load(*src) : nullptr;
+    if (image == nullptr) return false;
+    *out = *image;
+    return true;
+  }
+  if (node->isTag("canvas")) {
+    if (xtgui::Canvas2D *canvas = xt_gui_canvas_find(win, node)) {
+      *out = canvas->image();
+      return true;
+    }
+    if (xtgui::WebGLContext *context = xt_gui_webgl_find(win, node)) {
+      out->width = context->width();
+      out->height = context->height();
+      out->pixels.resize((size_t)out->width * out->height * 4);
+      if (!context->read_pixels(0, 0, out->width, out->height, out->pixels.data())) {
+        return false;
+      }
+      /* readPixels is GL-ordered (bottom-up); bitmaps are stored top-down. */
+      flip_rows(&out->pixels, out->width, out->height);
+      return true;
+    }
+    return false;
+  }
+  if (node->isTag("video")) {
+    xtgui::MediaPlayer *player = xt_gui_media_player(win, node);
+    const xtgui::Image *frame = player != nullptr ? player->frame() : nullptr;
+    if (frame == nullptr || frame->width <= 0 || frame->height <= 0) return false;
+    *out = *frame;
+    return true;
+  }
+  return false;
+}
+
+xt_value bitmap_object(const xtgui::Image &image) {
+  const uint64_t id = xtgui::xt_image_bitmap_add(image);
+  xt_value name = xt_string_from_cstr("ImageBitmap");
+  xt_value constructor = xt_browser_type(1, &name);
+  xt_value prototype = xt_object_get_cstr(constructor, "prototype");
+  xt_value bitmap = XT_IS_OBJECT(prototype) ? xt_object_new_with_proto(prototype)
+                                            : xt_object_new();
+  xt_object_set(bitmap, xt_string_from_cstr("width"), xt_number(image.width));
+  xt_object_set(bitmap, xt_string_from_cstr("height"), xt_number(image.height));
+  xt_object_set(bitmap, xt_string_from_cstr("__xt_bitmap"), xt_number((double)id));
+  return bitmap;
+}
+
+}  // namespace
+
+namespace {
+
+xt_value create_bitmap(int32_t argc, xt_value *argv) {
+  if (argc < 1) return xt_promise_reject(xt_string_from_cstr("TypeError"));
+  xtgui::Image image;
+  if (!source_pixels(xt_arg(argc, argv, 0), &image)) {
+    return xt_promise_reject(xt_string_from_cstr("InvalidStateError"));
+  }
+  return xt_promise_resolve(bitmap_object(image));
+}
+
+/** The closure ABI the runtime calls for a first-class function value. */
+xt_value create_bitmap_call(xt_value self, xt_value env, int32_t argc, xt_value *argv) {
+  (void)self;
+  (void)env;
+  return create_bitmap(argc, argv);
+}
+
+xt_value g_create_bitmap = XT_UNDEFINED;
+
+}  // namespace
+
+/* `createImageBitmap` is a *global value*: the compiler calls this getter once
+ * and stores the returned closure, which is then called like any function. */
+xt_value xt_browser_create_image_bitmap(int32_t argc, xt_value *argv) {
+  (void)argc;
+  (void)argv;
+  if (!XT_IS_OBJECT(g_create_bitmap)) {
+    g_create_bitmap = xt_closure_new((void *)create_bitmap_call, 0, nullptr);
+    xt_gc_add_root(&g_create_bitmap);
+  }
+  return g_create_bitmap;
+}
+