xbintsc 0.5.42 → 0.5.45

package/doc/zh-CN/gui/rendering.md

@@ -72,18 +72,21 @@
   `to <side>`、`deg`/`grad`/`rad`/`turn`、百分比或长度（`px`/`em`/…）偏移、
   `color <start> <end>` 简写与多色标（色带沿最近轴行走，因此斜角会退化为
   最近的轴向）；
-- **径向**渐变是 32 个同心椭圆（重复渐变 64 个）。每个都是单位半径的圆角矩形，
-  经图形管线的 transform 槽映射，因此圆/椭圆仍保留距离场抗锯齿。支持形状/尺寸
-  关键字（`circle`/`ellipse`、`closest-side`/`farthest-side`/`closest-corner`/
-  `farthest-corner`、显式半径）与 `at <position>`。
+- **径向**渐变由 `renderer_gradient.cpp` 逐像素解算成一张 RGBA 纹理，作为单个
+  图像四边形绘制（`PaintGradient`）。若沿用嵌套色带，由于每条色带都会覆盖整个
+  内部区域，alpha 会叠加多次——淡出到 `transparent` 的暗角会把整个场景涂成实心
+  黑盘。支持形状/尺寸关键字（`circle`/`ellipse`、`closest-side`/`farthest-side`/
+  `closest-corner`/`farthest-corner`、显式半径）与 `at <position>`；关键字尺寸
+  的椭圆保持盒子的宽高比并缩放到刚好接触对应边或角，与 CSS 一致。色标在预乘
+  alpha 空间中插值，最后一个色标会延伸覆盖结束形状之外的剩余盒子。
 
 `repeating-linear-gradient()` 与 `repeating-radial-gradient()` 会在整个盒子上
 从 0 平铺到最后一个色标的偏移量；色标列表不会被强制结束在 100%，因此
 `red 0%, blue 10%` 每 10% 重复一次。普通渐变的最后一个色标若小于 100%，则剩余
 区域保持该颜色，与 CSS 一致。
 
-背景色位于所有层下方。若渐变色标带透明度，渐变也会半透明；色带近似可能产生
-轻微条带，非常透明的多色标渐变会出现 alpha 叠加。
+背景色位于所有层下方。若渐变色标带透明度，渐变也会半透明；径向渐变逐像素精确，
+线性渐变仍采样 18 条色带，较大的柔和渐变可能出现条带。
 
 **生成内容**不需要新的显示列表类型：`::before`/`::after` 是 `style.cpp` 中
 每次重算样式时重建的普通布局盒，因此其背景、边框、文本与 transform 都走同一条

package/doc/zh-CN/gui-scripts.md

@@ -314,8 +314,8 @@ Event 的 `target` 是句柄，其描述符（`toString`）与同一 `div#id.cla
   导入的资产会）。如有需要，M9d 会处理。
 - **外部 `<script src>` 文件之间的 import 绑定冲突。** 会被检测并报告
   （给 import 起别名）；之后可以做到带引用重写的按脚本重命名。
-- **资产。** `<script src>` 相对 HTML 资产解析；URL `src` 值被忽略。没有
-  fetch/网络加载。
+- **资产。** `<script src>` 相对 HTML 资产解析；URL `src` 值被忽略。
+  加载器不会请求网络 URL；运行时全局 `fetch` 是另一套 API。
 
 ## 测试
 

package/doc/zh-CN/gui.md

@@ -262,8 +262,8 @@ FFmpeg `7.1`（供可选的 `media` 归档使用；可用 `SDL3_TAG` /
       特性）；`matchMedia()` 使用同一个求值器。
     - 生成内容：`::before`/`::after` 选择器、继承的伪样式、`content` 字符串/
       转义/`attr()`，以及不会泄漏到 DOM 遍历的合成布局盒。
-    - 多层 `background-image` 的线性与径向渐变，自下而上按纯色带绘制
-      （线性 18 条、径向 32 个同心椭圆）。
+    - 多层 `background-image`：线性渐变自下而上按纯色带绘制（18 条），径向渐变
+      逐像素光栅化成一张图像纹理（`renderer_gradient.cpp`）。
     - `text-shadow` 作为阴影文本 run，并带九次采样模糊近似。
     - `clip-path` 多边形（`inset`/`circle`/`ellipse`/`polygon`）解析到设备空间，
       用耳切法三角化，并在 `renderer_clip.cpp` 中与图形几何求交——不需要模板/
@@ -408,9 +408,10 @@ FFmpeg `7.1`（供可选的 `media` 归档使用；可用 `SDL3_TAG` /
   识别 `::before`/`::after`。`style.cpp` 把伪样式算进每次重算样式时重建的
   arena、解析 `content`，布局在真实子元素前后插入它们的盒子。
   `gradient_values.cpp` 建模背景层列表（线性/径向、形状/尺寸/位置/色标），
-  `paint_background.cpp` 绘制它，`paint_effects.cpp` 应用滤镜颜色函数与九次
-  采样模糊/投影并生成 `text-shadow` run，`paint_clip.cpp`/`renderer_clip.cpp`
-  对三角化的 `clip-path` 多边形裁剪几何。e2e 见
+  `paint_background.cpp` 解算并绘制它（径向层变成一个 `PaintGradient`，由
+  `renderer_gradient.cpp` 光栅化成纹理），`paint_effects.cpp` 应用滤镜颜色函数
+  与九次采样模糊/投影并生成 `text-shadow` run，`paint_clip.cpp`/
+  `renderer_clip.cpp` 对三角化的 `clip-path` 多边形裁剪几何。e2e 见
   `tests/e2e/gui-effects.test.ts`。
 - **M20** ✅ 渲染性能。`@media` 每次重算样式时每条规则只求值一次；没有
   `::before`/`::after` 的样式表完全跳过生成内容；只有样式表包含

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xbintsc",
-  "version": "0.5.42",
+  "version": "0.5.45",
   "description": "xbintsc - a TypeScript binary compiler (TypeScript -> LLVM IR -> native binary)",
   "type": "module",
   "license": "MIT",
@@ -72,12 +72,12 @@
     "vitest": "^2.1.8"
   },
   "optionalDependencies": {
-    "@xbintsc/linux-x64": "0.5.42",
-    "@xbintsc/linux-arm64": "0.5.42",
-    "@xbintsc/darwin-x64": "0.5.42",
-    "@xbintsc/darwin-arm64": "0.5.42",
-    "@xbintsc/win32-x64": "0.5.42",
-    "@xbintsc/win32-arm64": "0.5.42"
+    "@xbintsc/linux-x64": "0.5.45",
+    "@xbintsc/linux-arm64": "0.5.45",
+    "@xbintsc/darwin-x64": "0.5.45",
+    "@xbintsc/darwin-arm64": "0.5.45",
+    "@xbintsc/win32-x64": "0.5.45",
+    "@xbintsc/win32-arm64": "0.5.45"
   },
   "engines": {
     "node": ">=22"

package/runtime/ext_gui/audio.cpp

@@ -500,6 +500,24 @@ uint64_t audio_context_id(xt_value object) {
 
 xt_value xt_gui_audio_proto(void) { return audio_proto(); }
 
+/** Close every live context before `SDL_Quit`. The mixers hold SDL audio
+ * streams whose destructors must not run after the audio subsystem (and its
+ * device objects) were torn down; keeping the registry alive until static
+ * destruction was a crash on exit for every program that played a sound. */
+void xt_gui_audio_shutdown(void) {
+  std::vector<std::shared_ptr<AudioMixer>> mixers;
+  {
+    std::lock_guard<std::mutex> lock(g_registry_mutex);
+    mixers.reserve(g_mixers.size());
+    for (const auto &entry : g_mixers) mixers.push_back(entry.second);
+    g_mixers.clear();
+  }
+  for (const std::shared_ptr<AudioMixer> &mixer : mixers) {
+    mixer->close_device();
+    mixer->shutdown();
+  }
+}
+
 xt_value xt_gui_audio_create(int32_t argc, xt_value *argv) {
   bool offline = false;
   xt_value options = xt_arg(argc, argv, 0);

package/runtime/ext_gui/audio_device.cpp

@@ -13,6 +13,7 @@
 
 #include <SDL3/SDL.h>
 
+#include <cstdio>
 #include <vector>
 
 namespace xtgui {
@@ -39,14 +40,23 @@ bool AudioMixer::start_device() {
   if (stream_ != nullptr) return true;
   if (device_tried_) return false;
   device_tried_ = true;
-  if (!SDL_InitSubSystem(SDL_INIT_AUDIO)) return false;
+  if (!SDL_InitSubSystem(SDL_INIT_AUDIO)) {
+    /* A missing device is not fatal (the page keeps its graph and clock), but
+     * silently staying quiet is indistinguishable from a broken mixer. */
+    std::fprintf(stderr, "xt_gui: audio subsystem unavailable: %s\n", SDL_GetError());
+    return false;
+  }
   SDL_AudioSpec spec;
   spec.format = SDL_AUDIO_F32;
   spec.channels = kAudioMixChannels;
   spec.freq = kAudioMixRate;
   stream_ = SDL_OpenAudioDeviceStream(SDL_AUDIO_DEVICE_DEFAULT_PLAYBACK, &spec, stream_callback,
                                       this);
-  if (stream_ == nullptr) return false;
+  if (stream_ == nullptr) {
+    std::fprintf(stderr, "xt_gui: could not open the default audio device: %s\n",
+                 SDL_GetError());
+    return false;
+  }
   SDL_ResumeAudioStreamDevice(stream_);
   return true;
 }

package/runtime/ext_gui/browser.cpp

@@ -393,7 +393,7 @@ xt_value host_type_construct(xt_value self, xt_value env, int32_t argc, xt_value
 /** Host constructors are window members too — a page writes
  * `new window.AudioContext()` as often as `new AudioContext()`. */
 void install_window_globals(xt_value win) {
-  if (xt_seq(win, g_installed_window)) return;
+  if (xt_truthy(xt_seq(win, g_installed_window))) return;
   g_installed_window = win;
   xt_gc_add_root(&g_installed_window);
   if (XT_IS_OBJECT(g_navigator)) set_prop(win, "navigator", g_navigator);
@@ -479,7 +479,7 @@ xt_value xt_browser_document(int32_t argc, xt_value *argv) {
   xt_value win = xt_browser_window(0, NULL);
   if (XT_IS_UNDEFINED(win)) return XT_UNDEFINED;
   xt_value doc = xt_gui_document_handle(xt_gui_window_from_this(win));
-  if (!xt_seq(doc, g_document_global)) {
+  if (!xt_truthy(xt_seq(doc, g_document_global))) {
     g_document_global = doc;
     xt_gc_add_root(&g_document_global);
   }

package/runtime/ext_gui/dom_api_events.cpp

@@ -28,7 +28,8 @@ static xt_value make_dom_event(XtGuiWindow *win, const char *type, const xtgui::
     static const char *const fields[] = {
         "x",     "y",    "clientX", "clientY", "button", "clicks",
         "deltaX", "deltaY", "key",  "code",    "repeat", "ctrl",
-        "shift", "alt",  "meta",
+        "shift", "alt",  "meta",  "ctrlKey", "shiftKey", "altKey",
+        "metaKey",
     };
     for (const char *field : fields) {
       xt_value value = xt_object_get_cstr(legacy, field);

package/runtime/ext_gui/gui.cpp

@@ -460,6 +460,10 @@ extern "C" xt_value xt_gui_run(int32_t argc, xt_value *argv) {
     SDL_DestroyGPUDevice(device);
     g_device = NULL;
   }
+  /* Audio streams belong to SDL, so close them before quitting the audio
+   * subsystem; otherwise a still-live AudioMixer's destructor runs after
+   * `SDL_Quit` and touches freed SDL state. */
+  xt_gui_audio_shutdown();
   if (g_sdl_initialized) {
     SDL_Quit();
     g_sdl_initialized = 0;
@@ -478,5 +482,8 @@ extern "C" xt_value xt_gui_quit(int32_t argc, xt_value *argv) {
   for (int i = 0; i < g_window_count; i++) {
     if (g_windows[i].open) xt_gui_quit_window(&g_windows[i]);
   }
+  /* A browser-style page never enters `xt_gui_run`, so stop its audio here
+   * too instead of leaving the device open until process exit. */
+  xt_gui_audio_shutdown();
   return XT_UNDEFINED;
 }

package/runtime/ext_gui/gui_engine.h

@@ -314,6 +314,15 @@ void xt_gui_dispatch_pointer(XtGuiWindow *win, const char *type, float x, float
 void xt_gui_dispatch_wheel(XtGuiWindow *win, float x, float y, float delta_x, float delta_y);
 /** Synthesise a key event (`keydown`/`keyup`). */
 void xt_gui_dispatch_key(XtGuiWindow *win, const char *type, const char *key, const char *code);
+/** Translate one physical key (SDL scancode/keycode + modifiers) to the browser
+ * `key`/`code` names and dispatch it to the DOM and window listeners. */
+void xt_gui_dispatch_physical_key(XtGuiWindow *win, const char *type, int scancode, int keycode,
+                                  bool repeat, bool ctrl, bool shift, bool alt, bool meta,
+                                  bool caps_lock);
+/** Close every AudioContext's device and drop its graph. Called before
+ * `SDL_Quit` so an AudioMixer's destructor never touches an SDL stream after
+ * the audio subsystem was shut down. */
+void xt_gui_audio_shutdown(void);
 
 /** The decoder for one media element, opening it (and its `src`) on first use.
  * Returns `nullptr` for a non-media element or an unreadable source. */

package/runtime/ext_gui/gui_events.cpp

@@ -4,6 +4,7 @@
  */
 
 #include "gui_internal.h"
+#include "gui_keymap.h"
 #include "listener_options.h"
 
 #include "paint.h"
@@ -216,21 +217,64 @@ static xt_value xt_gui_key_payload(const char *type, const char *key, const char
   xt_object_set(payload, xt_string_from_cstr("key"), xt_string_from_cstr(key));
   xt_object_set(payload, xt_string_from_cstr("code"), xt_string_from_cstr(code));
   xt_object_set(payload, xt_string_from_cstr("repeat"), repeat ? XT_TRUE : XT_FALSE);
+  /* Legacy DOM fields and their current `*Key` spellings: a page may read
+   * either, and WheelEvent/MouseEvent already expose both where they apply. */
   xt_object_set(payload, xt_string_from_cstr("ctrl"), ctrl ? XT_TRUE : XT_FALSE);
   xt_object_set(payload, xt_string_from_cstr("shift"), shift ? XT_TRUE : XT_FALSE);
   xt_object_set(payload, xt_string_from_cstr("alt"), alt ? XT_TRUE : XT_FALSE);
   xt_object_set(payload, xt_string_from_cstr("meta"), meta ? XT_TRUE : XT_FALSE);
+  xt_object_set(payload, xt_string_from_cstr("ctrlKey"), ctrl ? XT_TRUE : XT_FALSE);
+  xt_object_set(payload, xt_string_from_cstr("shiftKey"), shift ? XT_TRUE : XT_FALSE);
+  xt_object_set(payload, xt_string_from_cstr("altKey"), alt ? XT_TRUE : XT_FALSE);
+  xt_object_set(payload, xt_string_from_cstr("metaKey"), meta ? XT_TRUE : XT_FALSE);
   return payload;
 }
 
-void xt_gui_dispatch_key(XtGuiWindow *win, const char *type, const char *key, const char *code) {
+static const xtgui::Node *xt_gui_find_body(const xtgui::Node *node) {
+  if (node == nullptr) return nullptr;
+  if (node->isElement() && node->tag == "body") return node;
+  for (const std::unique_ptr<xtgui::Node> &child : node->children) {
+    if (const xtgui::Node *found = xt_gui_find_body(child.get())) return found;
+  }
+  return nullptr;
+}
+
+/** The element a keyboard event targets when nothing is focused: `<body>`,
+ * like a browser, or the document root for a page without one. */
+static const xtgui::Node *xt_gui_key_target(XtGuiWindow *win) {
+  if (win->document == nullptr) return nullptr;
+  if (const xtgui::Node *focused = win->document->focus()) return focused;
+  const xtgui::Node *root = win->document->root();
+  if (const xtgui::Node *body = xt_gui_find_body(root)) return body;
+  return root;
+}
+
+/** Deliver one fully built keyboard payload to the DOM (bubbling from the
+ * focused element / body to `document`) and then to `window` listeners. */
+static void xt_gui_dispatch_key_payload(XtGuiWindow *win, const char *type, xt_value payload) {
   if (win == NULL || !win->open) return;
-  xt_value payload = xt_gui_key_payload(type, key, code, false, false, false, false, false);
-  const xtgui::Node *node = win->document != nullptr ? win->document->focus() : nullptr;
+  const xtgui::Node *node = xt_gui_key_target(win);
   if (node != nullptr) xt_gui_emit_dom_event(win, type, node, payload);
   xt_gui_emit_payload(win, type, payload);
 }
 
+void xt_gui_dispatch_key(XtGuiWindow *win, const char *type, const char *key, const char *code) {
+  xt_value payload = xt_gui_key_payload(type, key, code, false, false, false, false, false);
+  xt_gui_dispatch_key_payload(win, type, payload);
+}
+
+void xt_gui_dispatch_physical_key(XtGuiWindow *win, const char *type, int scancode, int keycode,
+                                  bool repeat, bool ctrl, bool shift, bool alt, bool meta,
+                                  bool caps_lock) {
+  std::string key;
+  std::string code;
+  xt_gui_key_names(static_cast<SDL_Scancode>(scancode), static_cast<SDL_Keycode>(keycode), shift,
+                   caps_lock, &key, &code);
+  xt_value payload = xt_gui_key_payload(type, key.c_str(), code.c_str(), repeat, ctrl, shift, alt,
+                                        meta);
+  xt_gui_dispatch_key_payload(win, type, payload);
+}
+
 namespace guidev {
 
 void handle_event(const SDL_Event *event) {
@@ -306,13 +350,11 @@ void handle_event(const SDL_Event *event) {
     XtGuiWindow *win = xt_gui_find_by_window_id(event->key.windowID);
     if (win == NULL || !win->open) return;
     const char *type = event->type == SDL_EVENT_KEY_DOWN ? "keydown" : "keyup";
-    xt_gui_emit_payload(win, type,
-                        xt_gui_key_payload(type, SDL_GetKeyName(event->key.key),
-                                           SDL_GetScancodeName(event->key.scancode),
-                                           event->key.repeat, (event->key.mod & SDL_KMOD_CTRL) != 0,
-                                           (event->key.mod & SDL_KMOD_SHIFT) != 0,
-                                           (event->key.mod & SDL_KMOD_ALT) != 0,
-                                           (event->key.mod & SDL_KMOD_GUI) != 0));
+    xt_gui_dispatch_physical_key(
+        win, type, static_cast<int>(event->key.scancode), static_cast<int>(event->key.key),
+        event->key.repeat, (event->key.mod & SDL_KMOD_CTRL) != 0,
+        (event->key.mod & SDL_KMOD_SHIFT) != 0, (event->key.mod & SDL_KMOD_ALT) != 0,
+        (event->key.mod & SDL_KMOD_GUI) != 0, (event->key.mod & SDL_KMOD_CAPS) != 0);
     return;
   }
 }

package/runtime/ext_gui/gui_keymap.cpp

@@ -0,0 +1,254 @@
+/*
+ * xbintsc GUI engine — browser KeyboardEvent names from SDL key events.
+ *
+ * `code` is the *physical* key, which is what the DOM's `KeyboardEvent.code`
+ * reports and what games normally bind to. `key` is the produced value, so it
+ * follows Shift/Caps Lock for letters and Shift for the US punctuation row.
+ * The mapping is intentionally the US layout: SDL's key names are US-based,
+ * and a page that needs another layout should use `code` anyway.
+ */
+
+#include "gui_keymap.h"
+
+#include <cstdio>
+
+namespace guidev {
+
+namespace {
+
+void set_names(std::string *key, std::string *code, const char *key_name, const char *code_name) {
+  *key = key_name;
+  *code = code_name;
+}
+
+/** Digits and their shifted symbols, indexed 0..9 for keys 1..0. */
+const char *const kDigitKeys = "1234567890";
+const char *const kDigitShifted = "!@#$%^&*()";
+
+/** Keypad digits, indexed 0..9 for KP_1..KP_0. */
+const char *const kKeypadDigits = "1234567890";
+
+}  // namespace
+
+void xt_gui_key_names(SDL_Scancode scancode, SDL_Keycode keycode, bool shift, bool caps_lock,
+                      std::string *key, std::string *code) {
+  key->clear();
+  code->clear();
+
+  /* Letters: SDL numbers A..Z consecutively. Caps Lock and Shift cancel out. */
+  if (scancode >= SDL_SCANCODE_A && scancode <= SDL_SCANCODE_Z) {
+    char letter = static_cast<char>('A' + (scancode - SDL_SCANCODE_A));
+    *code = "Key";
+    code->push_back(letter);
+    bool upper = shift != caps_lock;
+    key->push_back(upper ? letter : static_cast<char>(letter + ('a' - 'A')));
+    return;
+  }
+
+  /* Number row. */
+  if (scancode >= SDL_SCANCODE_1 && scancode <= SDL_SCANCODE_0) {
+    int index = static_cast<int>(scancode - SDL_SCANCODE_1);
+    *code = "Digit";
+    code->push_back(kDigitKeys[index]);
+    key->push_back(shift ? kDigitShifted[index] : kDigitKeys[index]);
+    return;
+  }
+
+  /* Function keys: F1..F12 and F13..F24 are two contiguous runs; the gap
+   * between F12 and F13 contains PrintScreen, arrows and the keypad. */
+  if ((scancode >= SDL_SCANCODE_F1 && scancode <= SDL_SCANCODE_F12) ||
+      (scancode >= SDL_SCANCODE_F13 && scancode <= SDL_SCANCODE_F24)) {
+    int number;
+    if (scancode <= SDL_SCANCODE_F12) {
+      number = static_cast<int>(scancode - SDL_SCANCODE_F1) + 1;
+    } else {
+      number = static_cast<int>(scancode - SDL_SCANCODE_F13) + 13;
+    }
+    char name[8];
+    std::snprintf(name, sizeof(name), "F%d", number);
+    *key = name;
+    *code = name;
+    return;
+  }
+
+  /* Keypad digits, same 1..9,0 order. */
+  if (scancode >= SDL_SCANCODE_KP_1 && scancode <= SDL_SCANCODE_KP_0) {
+    int index = static_cast<int>(scancode - SDL_SCANCODE_KP_1);
+    *code = "Numpad";
+    code->push_back(kKeypadDigits[index]);
+    key->push_back(kKeypadDigits[index]);
+    return;
+  }
+
+  switch (scancode) {
+    case SDL_SCANCODE_RETURN:
+    case SDL_SCANCODE_RETURN2:
+      set_names(key, code, "Enter", "Enter");
+      return;
+    case SDL_SCANCODE_ESCAPE:
+      set_names(key, code, "Escape", "Escape");
+      return;
+    case SDL_SCANCODE_BACKSPACE:
+      set_names(key, code, "Backspace", "Backspace");
+      return;
+    case SDL_SCANCODE_TAB:
+      set_names(key, code, "Tab", "Tab");
+      return;
+    case SDL_SCANCODE_SPACE:
+      set_names(key, code, " ", "Space");
+      return;
+    case SDL_SCANCODE_CAPSLOCK:
+      set_names(key, code, "CapsLock", "CapsLock");
+      return;
+    case SDL_SCANCODE_PRINTSCREEN:
+      set_names(key, code, "PrintScreen", "PrintScreen");
+      return;
+    case SDL_SCANCODE_SCROLLLOCK:
+      set_names(key, code, "ScrollLock", "ScrollLock");
+      return;
+    case SDL_SCANCODE_PAUSE:
+      set_names(key, code, "Pause", "Pause");
+      return;
+    case SDL_SCANCODE_INSERT:
+      set_names(key, code, "Insert", "Insert");
+      return;
+    case SDL_SCANCODE_HOME:
+      set_names(key, code, "Home", "Home");
+      return;
+    case SDL_SCANCODE_PAGEUP:
+      set_names(key, code, "PageUp", "PageUp");
+      return;
+    case SDL_SCANCODE_DELETE:
+      set_names(key, code, "Delete", "Delete");
+      return;
+    case SDL_SCANCODE_END:
+      set_names(key, code, "End", "End");
+      return;
+    case SDL_SCANCODE_PAGEDOWN:
+      set_names(key, code, "PageDown", "PageDown");
+      return;
+    case SDL_SCANCODE_RIGHT:
+      set_names(key, code, "ArrowRight", "ArrowRight");
+      return;
+    case SDL_SCANCODE_LEFT:
+      set_names(key, code, "ArrowLeft", "ArrowLeft");
+      return;
+    case SDL_SCANCODE_DOWN:
+      set_names(key, code, "ArrowDown", "ArrowDown");
+      return;
+    case SDL_SCANCODE_UP:
+      set_names(key, code, "ArrowUp", "ArrowUp");
+      return;
+    case SDL_SCANCODE_NUMLOCKCLEAR:
+      set_names(key, code, "NumLock", "NumLock");
+      return;
+    case SDL_SCANCODE_KP_ENTER:
+      set_names(key, code, "Enter", "NumpadEnter");
+      return;
+    case SDL_SCANCODE_KP_DIVIDE:
+      set_names(key, code, "/", "NumpadDivide");
+      return;
+    case SDL_SCANCODE_KP_MULTIPLY:
+      set_names(key, code, "*", "NumpadMultiply");
+      return;
+    case SDL_SCANCODE_KP_MINUS:
+      set_names(key, code, "-", "NumpadSubtract");
+      return;
+    case SDL_SCANCODE_KP_PLUS:
+      set_names(key, code, "+", "NumpadAdd");
+      return;
+    case SDL_SCANCODE_KP_PERIOD:
+    case SDL_SCANCODE_KP_DECIMAL:
+      set_names(key, code, ".", "NumpadDecimal");
+      return;
+    case SDL_SCANCODE_KP_EQUALS:
+      set_names(key, code, "=", "NumpadEqual");
+      return;
+    case SDL_SCANCODE_KP_COMMA:
+      set_names(key, code, ",", "NumpadComma");
+      return;
+    case SDL_SCANCODE_APPLICATION:
+    case SDL_SCANCODE_MENU:
+      set_names(key, code, "ContextMenu", "ContextMenu");
+      return;
+    case SDL_SCANCODE_LCTRL:
+      set_names(key, code, "Control", "ControlLeft");
+      return;
+    case SDL_SCANCODE_RCTRL:
+      set_names(key, code, "Control", "ControlRight");
+      return;
+    case SDL_SCANCODE_LSHIFT:
+      set_names(key, code, "Shift", "ShiftLeft");
+      return;
+    case SDL_SCANCODE_RSHIFT:
+      set_names(key, code, "Shift", "ShiftRight");
+      return;
+    case SDL_SCANCODE_LALT:
+      set_names(key, code, "Alt", "AltLeft");
+      return;
+    case SDL_SCANCODE_RALT:
+      set_names(key, code, "Alt", "AltRight");
+      return;
+    case SDL_SCANCODE_LGUI:
+      set_names(key, code, "Meta", "MetaLeft");
+      return;
+    case SDL_SCANCODE_RGUI:
+      set_names(key, code, "Meta", "MetaRight");
+      return;
+    default:
+      break;
+  }
+
+  /* Remaining US punctuation, keyed by scancode. */
+  switch (scancode) {
+    case SDL_SCANCODE_MINUS:
+      set_names(key, code, shift ? "_" : "-", "Minus");
+      return;
+    case SDL_SCANCODE_EQUALS:
+      set_names(key, code, shift ? "+" : "=", "Equal");
+      return;
+    case SDL_SCANCODE_LEFTBRACKET:
+      set_names(key, code, shift ? "{" : "[", "BracketLeft");
+      return;
+    case SDL_SCANCODE_RIGHTBRACKET:
+      set_names(key, code, shift ? "}" : "]", "BracketRight");
+      return;
+    case SDL_SCANCODE_BACKSLASH:
+    case SDL_SCANCODE_NONUSHASH:
+      set_names(key, code, shift ? "|" : "\\", "Backslash");
+      return;
+    case SDL_SCANCODE_SEMICOLON:
+      set_names(key, code, shift ? ":" : ";", "Semicolon");
+      return;
+    case SDL_SCANCODE_APOSTROPHE:
+      set_names(key, code, shift ? "\"" : "'", "Quote");
+      return;
+    case SDL_SCANCODE_GRAVE:
+      set_names(key, code, shift ? "~" : "`", "Backquote");
+      return;
+    case SDL_SCANCODE_COMMA:
+      set_names(key, code, shift ? "<" : ",", "Comma");
+      return;
+    case SDL_SCANCODE_PERIOD:
+      set_names(key, code, shift ? ">" : ".", "Period");
+      return;
+    case SDL_SCANCODE_SLASH:
+      set_names(key, code, shift ? "?" : "/", "Slash");
+      return;
+    case SDL_SCANCODE_NONUSBACKSLASH:
+      set_names(key, code, "\\", "IntlBackslash");
+      return;
+    default:
+      break;
+  }
+
+  /* Unknown key: keep SDL's human-readable names. `key` comes from the
+   * keycode so a consumer matching "Up" still sees it on a layout whose
+   * scancode name differs. */
+  const char *key_name = SDL_GetKeyName(keycode);
+  const char *code_name = SDL_GetScancodeName(scancode);
+  set_names(key, code, key_name != nullptr ? key_name : "",
+            code_name != nullptr ? code_name : "");
+}
+
+}  // namespace guidev

package/runtime/ext_gui/gui_keymap.h

@@ -0,0 +1,31 @@
+/*
+ * xbintsc GUI engine — SDL key event to browser KeyboardEvent names.
+ *
+ * The DOM exposes the browser spellings `KeyboardEvent.key` (the produced
+ * character / action name) and `code` (the physical key), while SDL reports a
+ * scancode and keycode. A page written for a browser matches on `code`
+ * ("KeyW", "ArrowUp", …), so translating `SDL_GetScancodeName` directly
+ * ("W", "Up") is not enough.
+ */
+#ifndef XT_GUI_KEYMAP_H
+#define XT_GUI_KEYMAP_H
+
+#include <SDL3/SDL.h>
+
+#include <string>
+
+namespace guidev {
+
+/** Fill `key` and `code` with the browser names for one physical key press.
+ *
+ * `scancode` selects the physical `code`; `keycode` and the modifier state
+ * select the produced `key` (letters honour Shift and Caps Lock, digits and
+ * punctuation use the US layout, which matches SDL's default key names).
+ * Unrecognised keys fall back to SDL's own names rather than an empty string,
+ * so a page that only logs events still sees something useful. */
+void xt_gui_key_names(SDL_Scancode scancode, SDL_Keycode keycode, bool shift, bool caps_lock,
+                      std::string *key, std::string *code);
+
+}  // namespace guidev
+
+#endif /* XT_GUI_KEYMAP_H */

package/runtime/ext_gui/paint.cpp

@@ -380,7 +380,22 @@ std::string DisplayList::dump() const {
     } else {
       const PaintImage &image = images[op.index];
       suffix = transformSuffix(image.transform);
-      if (image.media_id != 0) {
+      if (image.gradient != nullptr) {
+        const PaintGradient &gradient = *image.gradient;
+        std::snprintf(buffer, sizeof(buffer),
+                      "image x=%.1f y=%.1f w=%.1f h=%.1f gradient=%s center=%.1f,%.1f "
+                      "radius=%.1f,%.1f stops=",
+                      image.x, image.y, image.width, image.height,
+                      gradient.repeating ? "repeating-radial" : "radial", gradient.center_x,
+                      gradient.center_y, gradient.radius_x, gradient.radius_y);
+        text += prefix + buffer;
+        for (size_t stop = 0; stop < gradient.stops.size(); stop++) {
+          std::snprintf(buffer, sizeof(buffer), "%s%s@%.4f", stop == 0 ? "" : ",",
+                        formatColor(gradient.stops[stop].color).c_str(),
+                        gradient.stops[stop].offset);
+          text += buffer;
+        }
+      } else if (image.media_id != 0) {
         std::snprintf(buffer, sizeof(buffer), "image x=%.1f y=%.1f w=%.1f h=%.1f media=%llu",
                       image.x, image.y, image.width, image.height,
                       (unsigned long long)image.media_id);