xbintsc 0.5.52 → 0.6.8

package/doc/zh-CN/post/make-js-great-again.md

@@ -0,0 +1,32 @@
+# 这可能是今年最让JS开发者激动的事情了
+
+![3D鹈鹕骑自行车](../../../examples/gui/pelican-3d/preview.png)
+
+上面是我用JS+HTML+WebGL2做的鹈鹕3D骑自行车，FPS也非常不错。
+
+你可能会说“这不是用Ai有手就行了么？”
+
+但是，如果我说我把这上面用xbintsc编译成原生二进制，还不到10MB,还能在没有WebView环境上跑，还能支持Node.js和HTML混写，如下：
+
+```html
+<html>
+    <body>
+    <div id="out">loading...</div>
+    <script lang="ts">
+        import { readFileSync } from "fs";
+
+        const out = document.getElementById("out");
+        const world = readFileSync("data.txt", "utf8");
+        out.textContent = "hello " + world;
+    </script>
+    </body>
+</html>
+```
+
+要知道以前光chrome最少也得有100MB，用xbintsc编译产物10MB还不需要WebView环境，这可不仅仅代表桌面端开发体积极大减小和更加正确的实现路径的问题。
+
+更加具有划时代意义的是，JS开发者在嵌入式设备跑你想要做的应用成为了可能。
+
+[xbintsc开源地址](https://github.com/zy445566/xbintsc)
+
+

package/doc/zh-CN/requirements.md

@@ -14,6 +14,27 @@ xbintsc 不再自带编译器，因此每个平台都需要安装一个兼容 cl
 如果通过 npm 安装编译器而不是使用发布压缩包，Node.js 22+ 会直接运行编译器本身；
 见[通过 npm 包使用 xbintsc](./npm-package.md)。
 
+## 支持的平台
+
+发布二进制和预编译运行库归档面向 xbintsc 支持的最低平台版本。CI 使用**各宿主仍
+能产出发布包的最老工具链**构建它们，因此你机器上更新的 Xcode 或 Visual Studio 可以链接
+这些产物；反过来（旧工具链链接新产物）才会出现 `LNK2038`、`Undefined symbols` 或
+`was built for newer macOS version`。
+
+| 平台 | 生成的二进制可运行于 | 构建基线（CI） |
+| --- | --- | --- |
+| macOS x64 / arm64 | **macOS 11.0**（Big Sur）及以上 | 镜像中最老的 clang 16+ Xcode，`MACOSX_DEPLOYMENT_TARGET=11.0` |
+| Windows x64 | **Windows 11** 及以上 | `windows-2025` 镜像自带的工具链（当前为 VS 2026） |
+| Windows arm64 | **Windows 11** | `windows-11-arm` 镜像自带的工具链（当前为 VS 2026；没有更老的 arm64 镜像） |
+| Linux x64 / arm64 | **glibc 2.39**（Ubuntu 24.04）及以上 | `ubuntu-24.04` 上的 clang 16 + lld 16 |
+
+编译器工具链下限为：macOS 上的 Xcode 16（Apple clang 16）、Windows 上 `windows-2025`
+镜像自带的 Visual Studio（当前为 VS 2026）、Linux 上的 clang 16。因此构建机的要求比生成二进制的
+运行要求更高：Xcode 16 本身需要 macOS 14.5+，macOS 11–14 的构建机需要另外安装
+LLVM 16+（例如 Homebrew 的 `llvm`）。`xbintsc doctor` 会打印当前宿主的支持下限。如果归档是用比本机更新的工具链构建的，`build` 会自动改用随包 C 源码
+重试（见 [npm 包指南](./npm-package.md#首次构建与缓存)）；随包的 `gui.a`/`media.a`
+无法这样重编，因为 SDL3/FFmpeg 的源码不在包里。
+
 clang 15 及更旧版本会在任何程序的第一个字符串字面量处失败：
 
 ```
@@ -104,6 +125,10 @@ xcode-select -p            # 打印当前开发者目录
 xcrun --show-sdk-path      # 打印 SDK 路径
 ```
 
+xbintsc 会自己执行第二条命令，并把结果以 `-isysroot` 传给 clang，因此即使 clang
+是用绝对路径选中的（CI 的基线 Xcode，或 `xbintsc_CLANG`），也仍能找到 SDK 里的
+C 头文件与链接桩。自己设置 `SDKROOT` 优先，可用它固定某个 SDK。
+
 ## Linux —— 安装 clang 与 lld
 
 常规的 glibc 发行版加上 `clang`、`lld` 即可：

package/doc/zh-CN/unimplemented/deviations.md

@@ -16,6 +16,7 @@
 | 内存管理 | 非移动标记-清扫回收器（在 `xt_alloc` 之后）：显式根、子系统根提供者与保守 C 栈扫描。单线程、stop-the-world；无移动/压缩与分代 |
 | 函数 `arity` / 调用参数个数 | 对本地可见函数的直接调用由默认[语义检查](../implemented/checker.md)校验（`TS4004`）；通过属性、导入、展开实参或重新赋值后的绑定发起的调用不校验。`fn.length` 报告声明的 arity |
 | `async` / `await` | 已在栈式协程上真实挂起；`await` 总会排入一次微任务（非 Promise 与已 settle 的 Promise 也一样），因此与 pending `.then` 回调的交错顺序符合规范。顶层 `await` 会阻塞事件循环等待，而不是让出模块主体。`fs/promises` 与 `fetch` 把阻塞工作 offload 到 4 线程池并在 reactor 上 settle。异步生成器可在 `await` 与 `yield` 处挂起，`for await...of` 每次迭代等待一步 |
+| 未处理的 rejection | 在程序结束时才报告，而不是在当轮 tick 结束时：无人观察的 rejection 会在事件循环排空后打印并使进程以状态码 1 退出，因此长期运行的进程（如服务端）会一直运行到退出，稍后补挂的处理函数也仍会抑制该报告。Node 在微任务队列排空后立即抛出致命错误 |
 | 异步生成器清理 | `for await...of` 提前退出时不会调用迭代器的 `return()`。异步生成器中的 `yield*` 只委托同步可迭代对象。在挂起的 `yield` 处调用 `.return()` 会直接完成而不执行 `finally`（与同步生成器相同的限制） |
 | `super` | `super.x` / `super[x]` 从当前执行类的父级持有者读取（实例方法中是父原型，`static` 方法或静态块中是父构造函数），因此任意继承深度都正确 |
 | `Error.stack` | 仅函数级帧：每帧为 `at 名称 (文件:行)`，行号取自函数声明（最内层帧会更新为错误构造处）；没有列号，生成器 / `async` 函数体不产生帧（它们会切换栈） |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xbintsc",
-  "version": "0.5.52",
+  "version": "0.6.8",
   "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.52",
-    "@xbintsc/linux-arm64": "0.5.52",
-    "@xbintsc/darwin-x64": "0.5.52",
-    "@xbintsc/darwin-arm64": "0.5.52",
-    "@xbintsc/win32-x64": "0.5.52",
-    "@xbintsc/win32-arm64": "0.5.52"
+    "@xbintsc/linux-x64": "0.6.8",
+    "@xbintsc/linux-arm64": "0.6.8",
+    "@xbintsc/darwin-x64": "0.6.8",
+    "@xbintsc/darwin-arm64": "0.6.8",
+    "@xbintsc/win32-x64": "0.6.8",
+    "@xbintsc/win32-arm64": "0.6.8"
   },
   "engines": {
     "node": ">=22"

package/runtime/ext_node/child_process/child_process.c

@@ -7,9 +7,10 @@
  *   const result = spawnSync("clang", ["--version"], { cwd, encoding: "utf8" });
  *   result.status / result.stdout / result.stderr
  *
- * `options.cwd` is honoured; stdout/stderr are always captured as UTF-8
- * strings. On Windows the process is run with `_spawnvp` and redirected
- * through temporary files (which also avoids pipe-buffer deadlocks).
+ * `options.cwd` and `options.env` are honoured (the latter with Node's replace
+ * semantics); stdout/stderr are always captured as UTF-8 strings. On Windows
+ * the child runs under `CreateProcess` with anonymous pipes drained by reader
+ * threads (which also avoids pipe-buffer deadlocks).
  */
 
 #include "rt.h"
@@ -60,6 +61,58 @@ static int option_stdio_inherit(xt_value options) {
   return stdio && XT_IS_STRING(stdio) && strcmp(xt_string_data(stdio), "inherit") == 0;
 }
 
+/*
+ * `options.env` replaces the child's environment, exactly like Node: an absent
+ * option inherits the parent's environment, while a present one is the complete
+ * environment (spread `process.env` into it to extend rather than replace).
+ *
+ * The runtime used to ignore this option, which made every `spawnSync` inherit:
+ * a caller passing `SDKROOT` or `INCLUDE` silently got nothing, and a
+ * self-hosted compiler could not hand the macOS SDK to clang.
+ */
+
+/** The `env` object, or `XT_UNDEFINED` when the child should inherit. */
+static xt_value option_env(xt_value options) {
+  if (!XT_IS_OBJECT(options)) return XT_UNDEFINED;
+  xt_value env = xt_object_get(options, xt_string_from_cstr("env"));
+  return XT_IS_OBJECT(env) ? env : XT_UNDEFINED;
+}
+
+/** The number of `KEY=VALUE` entries the environment object provides. */
+static int32_t env_size(xt_value env) {
+  xt_value keys = xt_object_keys(env);
+  return XT_IS_ARRAY(keys) ? xt_array_size(keys) : 0;
+}
+
+static void free_env_entries(char **entries, int32_t count) {
+  if (entries == NULL) return;
+  for (int32_t i = 0; i < count; i++) free(entries[i]);
+  free(entries);
+}
+
+/** `KEY=VALUE` entries for the environment object, in object key order. */
+static char **env_entries(xt_value env, int32_t count) {
+  char **entries = (char **)calloc((size_t)(count > 0 ? count : 1), sizeof(char *));
+  if (entries == NULL) return NULL;
+  xt_value keys = xt_object_keys(env);
+  xt_value *items = XT_IS_ARRAY(keys) ? xt_array_items(keys) : NULL;
+  for (int32_t i = 0; i < count; i++) {
+    xt_value key = items[i];
+    xt_value raw = xt_object_get(env, key);
+    /* Node ignores `undefined` values instead of passing "undefined". */
+    if (XT_IS_UNDEFINED(raw)) continue;
+    const char *name = xt_string_data(xt_to_string(key));
+    const char *value = xt_string_data(xt_to_string(raw));
+    if (name == NULL || value == NULL) continue;
+    size_t length = strlen(name) + strlen(value) + 2;
+    char *entry = (char *)malloc(length);
+    if (entry == NULL) continue;
+    snprintf(entry, length, "%s=%s", name, value);
+    entries[i] = entry;
+  }
+  return entries;
+}
+
 static xt_value make_result(double status, const char *out, const char *err) {
   xt_value result = xt_object_new();
   xt_set(result, xt_string_from_cstr("status"), xt_number(status));
@@ -181,18 +234,60 @@ static char *build_command_line(char **child_argv, int count) {
   return line;
 }
 
+/* `CreateProcessA` wants one ANSI block, entries sorted case-insensitively. */
+static int compare_env_entries(const void *left, const void *right) {
+  const char *a = *(const char *const *)left;
+  const char *b = *(const char *const *)right;
+  if (a == NULL) return b == NULL ? 0 : 1;
+  if (b == NULL) return -1;
+  return _stricmp(a, b);
+}
+
+/** The environment block for `CreateProcessA`, or NULL to inherit. */
+static char *build_env_block(xt_value env) {
+  if (!XT_IS_OBJECT(env)) return NULL;
+  int32_t count = env_size(env);
+  char **entries = env_entries(env, count);
+  if (entries == NULL) return NULL;
+  qsort(entries, (size_t)count, sizeof(char *), compare_env_entries);
+  size_t total = 1;
+  for (int32_t i = 0; i < count; i++) total += entries[i] != NULL ? strlen(entries[i]) + 1 : 0;
+  char *block = (char *)malloc(total + 1);
+  if (block == NULL) {
+    free_env_entries(entries, count);
+    return NULL;
+  }
+  char *cursor = block;
+  for (int32_t i = 0; i < count; i++) {
+    if (entries[i] == NULL) continue;
+    size_t length = strlen(entries[i]) + 1;
+    memcpy(cursor, entries[i], length);
+    cursor += length;
+  }
+  /* The block ends with an extra terminator; an empty environment is "\0\0". */
+  *cursor++ = 0;
+  *cursor = 0;
+  free_env_entries(entries, count);
+  return block;
+}
+
 xt_value xt_child_process_spawn_sync(int32_t argc, xt_value *argv) {
   const char *command = argc > 0 ? xt_string_data(xt_to_string(argv[0])) : NULL;
   if (!command) command = "";
   xt_value args = argc > 1 ? argv[1] : XT_UNDEFINED;
   const char *cwd = argc > 2 ? option_cwd(argv[2]) : NULL;
+  char *env_block = build_env_block(option_env(argc > 2 ? argv[2] : XT_UNDEFINED));
 
   int count = 0;
   char **child_argv = (char **)build_argv(command, args, &count);
-  if (!child_argv) return make_result(-1, "", "out of memory");
+  if (!child_argv) {
+    free(env_block);
+    return make_result(-1, "", "out of memory");
+  }
   char *command_line = build_command_line(child_argv, count);
   if (!command_line) {
     free(child_argv);
+    free(env_block);
     return make_result(-1, "", "out of memory");
   }
 
@@ -204,9 +299,10 @@ xt_value xt_child_process_spawn_sync(int32_t argc, xt_value *argv) {
 
   if (option_stdio_inherit(argc > 2 ? argv[2] : XT_UNDEFINED)) {
     BOOL created = CreateProcessA(
-      NULL, command_line, NULL, NULL, TRUE, 0, NULL, cwd, &startup, &process);
+      NULL, command_line, NULL, NULL, TRUE, 0, env_block, cwd, &startup, &process);
     free(command_line);
     free(child_argv);
+    free(env_block);
     if (!created) return make_result(-1, "", "failed to start process");
     WaitForSingleObject(process.hProcess, INFINITE);
     DWORD exit_code = 0;
@@ -229,6 +325,7 @@ xt_value xt_child_process_spawn_sync(int32_t argc, xt_value *argv) {
     close_capture_pipe(&err_pipe);
     free(command_line);
     free(child_argv);
+    free(env_block);
     return make_result(-1, "", "could not create pipes");
   }
   startup.dwFlags = STARTF_USESTDHANDLES;
@@ -237,9 +334,10 @@ xt_value xt_child_process_spawn_sync(int32_t argc, xt_value *argv) {
   startup.hStdError = err_write;
 
   BOOL created = CreateProcessA(
-    NULL, command_line, NULL, NULL, TRUE, 0, NULL, cwd, &startup, &process);
+    NULL, command_line, NULL, NULL, TRUE, 0, env_block, cwd, &startup, &process);
   free(command_line);
   free(child_argv);
+  free(env_block);
   CloseHandle(out_write);
   CloseHandle(err_write);
   if (!created) {
@@ -285,30 +383,68 @@ static void append_chunk(char **buffer, size_t *length, size_t *capacity, const
   (*buffer)[*length] = 0;
 }
 
+/** A NULL-terminated `envp` for `exec`, or NULL when the child inherits. */
+static char **build_envp(xt_value env) {
+  if (!XT_IS_OBJECT(env)) return NULL;
+  int32_t count = env_size(env);
+  char **entries = env_entries(env, count);
+  if (entries == NULL) return NULL;
+  char **envp = (char **)calloc((size_t)count + 1, sizeof(char *));
+  if (envp == NULL) {
+    free_env_entries(entries, count);
+    return NULL;
+  }
+  int32_t kept = 0;
+  for (int32_t i = 0; i < count; i++) {
+    if (entries[i] != NULL) envp[kept++] = entries[i];
+  }
+  envp[kept] = NULL;
+  /* The strings now belong to `envp`; only the index array is released here. */
+  free(entries);
+  return envp;
+}
+
+/** Release an `envp` built by {@link build_envp}. */
+static void free_envp(char **envp) {
+  if (envp == NULL) return;
+  for (char **entry = envp; *entry != NULL; entry++) free(*entry);
+  free(envp);
+}
+
 xt_value xt_child_process_spawn_sync(int32_t argc, xt_value *argv) {
   const char *command = argc > 0 ? xt_string_data(xt_to_string(argv[0])) : NULL;
   if (!command) command = "";
   xt_value args = argc > 1 ? argv[1] : XT_UNDEFINED;
   const char *cwd = argc > 2 ? option_cwd(argv[2]) : NULL;
+  char **envp = build_envp(option_env(argc > 2 ? argv[2] : XT_UNDEFINED));
 
   int count = 0;
   char **child_argv = (char **)build_argv(command, args, &count);
-  if (!child_argv) return make_result(-1, "", "out of memory");
+  if (!child_argv) {
+    free_envp(envp);
+    return make_result(-1, "", "out of memory");
+  }
 
   if (option_stdio_inherit(argc > 2 ? argv[2] : XT_UNDEFINED)) {
     pid_t inherit_pid = fork();
     if (inherit_pid < 0) {
       free(child_argv);
+      free_envp(envp);
       return make_result(-1, "", "failed to fork");
     }
     if (inherit_pid == 0) {
       if (cwd) chdir(cwd);
+      if (envp != NULL) {
+        extern char **environ;
+        environ = envp;
+      }
       execvp(command, child_argv);
       _exit(127);
     }
     int inherit_status = 0;
     waitpid(inherit_pid, &inherit_status, 0);
     free(child_argv);
+    free_envp(envp);
     return make_result(
       WIFEXITED(inherit_status) ? (double)WEXITSTATUS(inherit_status) : -1.0, "", "");
   }
@@ -317,6 +453,7 @@ xt_value xt_child_process_spawn_sync(int32_t argc, xt_value *argv) {
   int err_pipe[2];
   if (pipe(out_pipe) != 0 || pipe(err_pipe) != 0) {
     free(child_argv);
+    free_envp(envp);
     return make_result(-1, "", "could not create pipes");
   }
 
@@ -329,6 +466,10 @@ xt_value xt_child_process_spawn_sync(int32_t argc, xt_value *argv) {
     close(err_pipe[0]);
     close(err_pipe[1]);
     if (cwd) chdir(cwd);
+    if (envp != NULL) {
+      extern char **environ;
+      environ = envp;
+    }
     execvp(command, child_argv);
     _exit(127);
   }
@@ -371,6 +512,7 @@ xt_value xt_child_process_spawn_sync(int32_t argc, xt_value *argv) {
   free(buffers[0]);
   free(buffers[1]);
   free(child_argv);
+  free_envp(envp);
   return result;
 }
 

package/runtime/rt.h

@@ -334,6 +334,10 @@ xt_value xt_promise_static(xt_value name, int32_t argc, xt_value *argv);
 xt_value xt_await(xt_value value);
 /** Run queued promise reactions; called once the program body finishes. */
 void xt_drain_microtasks(void);
+/** Mark `value` (a promise) as observed, so its rejection is not reported. */
+void xt_promise_observe_value(xt_value value);
+/** Print rejected promises that no handler ever observed; returns how many. */
+int xt_promise_report_unhandled(void);
 
 /* -- host event loop ------------------------------------------------------ */
 /* A small select(2) reactor for host extensions (node's net/dgram/http). The

package/runtime/xt_async.c

@@ -122,6 +122,10 @@ void xt_async_wake(void *asyncPointer, xt_value value, int rejected) {
  * queues a microtask before resuming, so an await always interleaves with
  * pending `.then` callbacks exactly like the specification. */
 xt_value xt_await(xt_value value) {
+  /* The awaiting code observes the outcome, so a rejection here is handled by
+   * definition — it is rethrown inside the coroutine, and the promise of the
+   * enclosing `async` function is what gets reported if nobody catches it. */
+  xt_promise_observe_value(value);
   /* An `await` inside an async generator suspends that generator's coroutine
    * while leaving the current `.next()` promise pending. */
   xt_value generatorResult;

package/runtime/xt_generator.c

@@ -395,6 +395,8 @@ int xt_generator_await(xt_value value, xt_value *result) {
   /* A nested async function inside the generator runs on its own coroutine;
    * its awaits must not suspend the generator. */
   if (!xt_coroutine_is_current(gen->coroutine)) return 0;
+  /* The generator's body observes the outcome, so this rejection is handled. */
+  xt_promise_observe_value(value);
   int state = xt_promise_state_of(value);
   if (state == XT_PROMISE_PENDING) {
     gen->await_threw = 0;

package/runtime/xt_loop.c

@@ -449,11 +449,15 @@ void xt_run_event_loop(void) {
      responsible for calling `xt_loop_poll` while it runs. */
   if (xt_loop_main != NULL) {
     xt_loop_main();
-    return;
-  }
-  while (xt_loop_has_work()) {
-    if (xt_loop_poll(-1) < 0) break;
+  } else {
+    while (xt_loop_has_work()) {
+      if (xt_loop_poll(-1) < 0) break;
+    }
   }
+  /* A rejection that no handler ever observed is fatal, like Node's default
+   * `--unhandled-rejections=throw`. Without this an `async main()` that throws
+   * exits 0 with no output at all, which hides the failure completely. */
+  if (xt_promise_report_unhandled() > 0) exit(1);
 }
 
 int xt_loop_has_work(void) {

package/runtime/xt_promise.c

@@ -11,6 +11,7 @@
 
 #include "rt_internal.h"
 
+#include <stdio.h>
 #include <stdlib.h>
 #include <string.h>
 
@@ -33,6 +34,12 @@ struct xt_promise {
   xt_reaction **reactions;
   uint32_t reaction_count;
   uint32_t reaction_capacity;
+  /* Unhandled-rejection tracking. `observed` is set once something can see
+   * this promise's outcome: a `.then`/`.catch` registration, an `await`, or
+   * adoption by another promise. `report_index` is its slot in `xt_unhandled`
+   * (`XT_PROMISE_UNLISTED` while it is not queued). */
+  int observed;
+  uint32_t report_index;
 };
 
 /* -- microtask queue ------------------------------------------------------ */
@@ -64,6 +71,58 @@ static xt_value xt_promise_value(xt_promise *promise) {
   return XT_FROM_PTR(XT_TAG_OBJECT, promise);
 }
 
+/* -- unhandled rejections ------------------------------------------------- */
+/*
+ * A promise that rejects without anybody observing the outcome is a bug, and
+ * an invisible one here: a compiled program's entry point is usually `async`,
+ * so an escaping exception rejects *its* promise and nothing else looks at it.
+ * The process used to print nothing and exit 0, which hides the failure.
+ *
+ * A rejected promise joins this queue and leaves it the moment a handler (or
+ * an `await`) is registered — including one attached later, from a timer. What
+ * is still queued once the event loop drains is reported on stderr and the
+ * process exits non-zero, like Node's default `unhandled-rejections=throw`.
+ */
+#define XT_PROMISE_UNLISTED 0xFFFFFFFFu
+
+static xt_promise **xt_unhandled = NULL;
+static uint32_t xt_unhandled_count = 0;
+static uint32_t xt_unhandled_capacity = 0;
+
+static void xt_unhandled_remove(xt_promise *promise) {
+  uint32_t index = promise->report_index;
+  if (index == XT_PROMISE_UNLISTED) return;
+  uint32_t last = xt_unhandled_count - 1;
+  if (index != last) {
+    xt_promise *moved = xt_unhandled[last];
+    xt_unhandled[index] = moved;
+    moved->report_index = index;
+  }
+  xt_unhandled_count = last;
+  promise->report_index = XT_PROMISE_UNLISTED;
+}
+
+static void xt_unhandled_add(xt_promise *promise) {
+  if (promise->observed || promise->report_index != XT_PROMISE_UNLISTED) return;
+  if (xt_unhandled_count >= xt_unhandled_capacity) {
+    xt_unhandled_capacity = xt_unhandled_capacity == 0 ? 8 : xt_unhandled_capacity * 2;
+    xt_unhandled = (xt_promise **)realloc(xt_unhandled, sizeof(xt_promise *) * xt_unhandled_capacity);
+    if (!xt_unhandled) abort();
+  }
+  promise->report_index = xt_unhandled_count;
+  xt_unhandled[xt_unhandled_count++] = promise;
+}
+
+/* Something is listening now, so this promise can never be "unhandled". */
+static void xt_promise_observe(xt_promise *promise) {
+  if (!promise) return;
+  promise->observed = 1;
+  xt_unhandled_remove(promise);
+}
+
+/** Mark `value` (when it is a promise) as observed; see `xt_promise_observe`. */
+void xt_promise_observe_value(xt_value value) { xt_promise_observe(xt_as_promise(value)); }
+
 static void xt_promise_gc_register(void);
 
 static xt_promise *xt_promise_new(void) {
@@ -73,6 +132,8 @@ static xt_promise *xt_promise_new(void) {
   promise->reactions = NULL;
   promise->reaction_count = 0;
   promise->reaction_capacity = 0;
+  promise->observed = 0;
+  promise->report_index = XT_PROMISE_UNLISTED;
   xt_promise_gc_register();
   return promise;
 }
@@ -90,6 +151,9 @@ static void xt_promise_gc_scan_roots(void) {
     xt_gc_mark_header((xt_header *)reaction->result);
     if (reaction->async) xt_gc_mark_header((xt_header *)reaction->async);
   }
+  /* Pending rejections are reported by identity, and the reason must survive
+   * long enough to be printed. */
+  for (uint32_t i = 0; i < xt_unhandled_count; i++) xt_gc_mark_header((xt_header *)xt_unhandled[i]);
 }
 
 static void xt_promise_gc_register(void) {
@@ -115,6 +179,8 @@ void xt_promise_gc_trace(xt_header *header) {
 
 void xt_promise_gc_release(xt_header *header) {
   xt_promise *promise = (xt_promise *)header;
+  /* A listed rejection is a GC root, so this is only a safety net. */
+  xt_unhandled_remove(promise);
   /* Pending reactions are owned solely by the promise; queued ones live in
    * `xt_microtasks` and are freed as they run. */
   for (uint32_t i = 0; i < promise->reaction_count; i++) free(promise->reactions[i]);
@@ -129,6 +195,9 @@ static void xt_promise_resolve_into(xt_promise *result, xt_value value) {
     xt_promise_settle(result, XT_PROMISE_FULFILLED, value);
     return;
   }
+  /* `result` follows `other`, so `other`'s rejection is consumed here even if
+   * `result` ends up unhandled itself (Node reports only the outermost). */
+  xt_promise_observe(other);
   if (other->state == XT_PROMISE_PENDING) {
     xt_reaction *reaction = (xt_reaction *)malloc(sizeof(xt_reaction));
     if (!reaction) abort();
@@ -152,6 +221,7 @@ static void xt_promise_settle(xt_promise *promise, int state, xt_value value) {
   if (promise->state != XT_PROMISE_PENDING) return;
   promise->state = state;
   promise->value = value;
+  if (state == XT_PROMISE_REJECTED) xt_unhandled_add(promise);
   for (uint32_t i = 0; i < promise->reaction_count; i++) xt_microtask_push(promise->reactions[i]);
   promise->reaction_count = 0;
 }
@@ -206,6 +276,8 @@ void xt_promise_queue_async_wake(void *asyncPointer, xt_value settled, int rejec
   xt_promise *promise = xt_promise_new();
   promise->state = rejected ? XT_PROMISE_REJECTED : XT_PROMISE_FULFILLED;
   promise->value = settled;
+  /* An internal handoff to a coroutine, never a rejection anyone can see. */
+  promise->observed = 1;
   xt_reaction *reaction = (xt_reaction *)malloc(sizeof(xt_reaction));
   if (!reaction) abort();
   reaction->promise = promise;
@@ -239,6 +311,8 @@ xt_value xt_promise_value_of(xt_value value) {
 void xt_promise_add_async_waiter(xt_value promiseValue, void *async) {
   xt_promise *promise = xt_as_promise(promiseValue);
   if (!promise || promise->state != XT_PROMISE_PENDING) return;
+  /* The coroutine sees the rejection, so this promise is handled. */
+  xt_promise_observe(promise);
   xt_reaction *reaction = (xt_reaction *)malloc(sizeof(xt_reaction));
   if (!reaction) abort();
   reaction->promise = promise;
@@ -346,6 +420,9 @@ xt_value xt_promise_static(xt_value name, int32_t argc, xt_value *argv) {
       for (uint32_t i = 0; i < array->length; i++) {
         xt_value item = array->items[i];
         xt_promise *inner = xt_is_promise(item) ? xt_as_promise(item) : NULL;
+        /* The combinator reads every element's outcome, including a rejection
+         * it forwards to its own result. */
+        xt_promise_observe(inner);
         int rejected = inner && inner->state == XT_PROMISE_REJECTED;
         if (strcmp(fn, "allSettled") == 0) {
           xt_value record = xt_object_new();
@@ -400,6 +477,10 @@ xt_value xt_promise_method(xt_value target, const char *method, int32_t argc, xt
     return XT_UNDEFINED;
   }
   if (strcmp(method, "then") == 0) {
+    /* `.then` with no rejection handler still consumes this promise's
+     * rejection: the derivative carries it on and is reported if nobody
+     * handles *that* one, exactly like Node. */
+    xt_promise_observe(promise);
     xt_promise *result = xt_promise_new();
     xt_reaction *reaction = (xt_reaction *)malloc(sizeof(xt_reaction));
     if (!reaction) abort();
@@ -448,3 +529,25 @@ xt_value xt_queue_microtask(int32_t argc, xt_value *argv) {
   xt_promise_method(promise, "then", 1, &callback, &handled);
   return XT_UNDEFINED;
 }
+
+/* -- reporting ------------------------------------------------------------ */
+
+int xt_promise_report_unhandled(void) {
+  int reported = 0;
+  for (uint32_t i = 0; i < xt_unhandled_count; i++) {
+    xt_promise *promise = xt_unhandled[i];
+    if (!promise || promise->observed) continue;
+    reported++;
+    /* `Error` (and its subclasses) carry a captured stack; everything else is
+     * stringified the way Node prints a rejection reason. */
+    xt_value text = xt_error_stack(promise->value);
+    if (text == XT_UNDEFINED) text = xt_to_string(promise->value);
+    xt_string *bytes = xt_as_string(text);
+    if (bytes) {
+      fprintf(stderr, "Unhandled promise rejection\n%s\n", xt_string_bytes(bytes));
+    } else {
+      fprintf(stderr, "Unhandled promise rejection\n");
+    }
+  }
+  return reported;
+}