xbintsc 0.3.87 → 0.5.20

package/doc/ai/zh-CN/contributing.md

@@ -16,15 +16,11 @@ npm test                 # 单元测试 + 端到端测试
 （见 [troubleshooting.md](./troubleshooting.md)）。`xbintsc emit` 既不需要 clang 也不需要
 运行时库，因此它是最快的内循环。
 
-可选但推荐——安装仓库钩子：
-
-```bash
-git config core.hooksPath .githooks
-```
-
-`.githooks/pre-commit` **会在每次提交时把补丁版本号 +1**，并把 `package.json` 与
-`package-lock.json` 一起折进该提交（`npm version patch --no-git-tag-version`）。请预期
-你的提交里会带版本号变更，不要对抗它。发布标签由 `release.yml` 创建，钩子从不打标签。
+可选：安装仓库钩子 `git config core.hooksPath .githooks`。它只在
+`main`/`master` 上把补丁版本号 +1（同时更新 `package.json`、
+`package-lock.json` 与 `src/driver/version.ts`）。功能分支从不改动这些文件，
+这正是两个功能分支不会在版本行上冲突的原因；不要在功能分支上改版本号。
+发布标签由 `release.yml` 创建，钩子从不打标签。
 
 ## 测试套件
 
@@ -67,11 +63,11 @@ gen2 --emit--> gen3.ll      # 必须等于 ref.ll
 必须逐字节确定——包括迭代顺序、生成的符号名与编号。绝不要把不确定性（未受控的
 `Map`/`Set` 迭代顺序、时间戳、依赖文件系统顺序的东西）引入代码生成。
 
-第二个推论是字符串模型：编译器自身源码文本在各代中必须含义一致。编译后的字符串是
-UTF-8 字节，所以自举后的 `readFileSync`（`--ext node`）交给扫描器的是文件字节，而
-Node 交给它的是同一个文件已解码后的文本——读取源码文件一律走 `decodeUtf8`
-（[src/diagnostics/utf8.ts](../../../src/diagnostics/utf8.ts)），不要假设一个码元就是
-一个字节或一个字符。弄错的表现是：`gen2.ll` 里非 ASCII 字面量（比如提示语里的 `—`）
+第二个推论是字符串模型：编译器自身源码文本在各代中必须含义一致。编译后的字符串以 UTF-8
+存储，但索引按 UTF-16 码元进行，所以自举后的 `readFileSync`（`--ext node`）交给扫描器的是
+字节串（一个码元一个字节，全部 `<= 0xFF`），而 Node 交给它的是同一个文件已解码后的文本——
+读取源码文件一律走 `sourceTextBytes`（[src/diagnostics/source-text.ts](../../../src/diagnostics/source-text.ts)），
+不要假设一个码元就是一个字节或一个字符。弄错的表现是：`gen2.ll` 里非 ASCII 字面量（比如提示语里的 `—`）
 被重新编码，这也正是这里逐字节比较 IR 而不是逐行比较的原因。
 
 本地验证：
@@ -111,7 +107,7 @@ npm run runtime            # tsx scripts/build-runtime.ts -> runtime/lib/<os>-<a
 npm run runtime:clean      # 删除 build/runtime-obj 与 runtime/lib
 ```
 
-新增 C 文件时必须同时更新列出运行时源文件的地方（[../../../src/driver/compiler.ts](../../../src/driver/compiler.ts)
+新增 C 文件时必须同时更新列出运行时源文件的地方（[../../../src/driver/runtime-objects.ts](../../../src/driver/runtime-objects.ts)
 里的 `RUNTIME_SOURCES`），因为那份列表决定什么会被编译和链接。扩展的 C 源由扩展自己声明。
 
 ## 新增或扩展一个扩展
@@ -153,13 +149,18 @@ src/extensions/node/fs/index.ts        runtime/ext_node/fs/read_file.c
 
 | 文档 | 何时更新 |
 | --- | --- |
-| [../../zh-CN/implemented.md](../../zh-CN/implemented.md) | 某特性开始可用 |
-| [../../zh-CN/unimplemented.md](../../zh-CN/unimplemented.md) | 出现或解除了某个限制 |
-| [../../zh-CN/node-implemented.md](../../zh-CN/node-implemented.md) / [../../zh-CN/node-unimplemented.md](../../zh-CN/node-unimplemented.md) | Node 模块覆盖变化 |
+| [../../zh-CN/implemented/](../../zh-CN/implemented/) 中拥有该功能的页面 | 某特性开始可用 |
+| [../../zh-CN/unimplemented/](../../zh-CN/unimplemented/) 中拥有该限制的页面 | 出现或解除了某个限制 |
+| [../../zh-CN/implemented.md](../../zh-CN/implemented.md) / [../../zh-CN/unimplemented.md](../../zh-CN/unimplemented.md) | 新增整页时（在索引里加链接） |
+| [../../zh-CN/implemented/node.md](../../zh-CN/implemented/node.md) / [../../zh-CN/unimplemented/node.md](../../zh-CN/unimplemented/node.md) | Node 模块覆盖变化 |
 | [language-support.md](./language-support.md) | 上述内容的 AI 摘要变化 |
 | [../../zh-CN/requirements.md](../../zh-CN/requirements.md) | 工具链或平台要求变化 |
 | [cli.md](./cli.md) | 参数、配置字段或环境变量变化 |
 
+每个功能域只拥有一个小页面，因此功能分支改自己领域的页面（以及它的中文翻译），
+而不是一份大文档。索引页的「改动应该写在哪一页？」表把改动映射到页面。
+`tests/docs/structure.test.ts` 会检查每个英文页面都有中文对应页，且都被索引链接。
+
 中文翻译（`doc/zh-CN/`、`doc/ai/zh-CN/`）要与英文源同步；半翻译的页面比没有更糟，因为
 它会静默过期。
 

package/doc/ai/zh-CN/extensions.md

@@ -49,11 +49,12 @@ xbintsc run app.ts --ext node
 | `util`、`querystring`、`url`、`assert`、`test`、`zlib` | |
 
 各模块的具体覆盖（确切函数与选项）见
-[../../zh-CN/node-implemented.md](../../zh-CN/node-implemented.md)，缺失项见
-[../../zh-CN/node-unimplemented.md](../../zh-CN/node-unimplemented.md)。
+[../../zh-CN/implemented/node.md](../../zh-CN/implemented/node.md)，缺失项见
+[../../zh-CN/unimplemented/node.md](../../zh-CN/unimplemented/node.md)。
 
 在 `net`/`http` 上搭东西之前，先记住运行时模型：事件循环在**程序主体之后**才运行，
-而 `async`/`await` 是同步微任务模型。见 [language-support.md](./language-support.md)。
+但 `async`/`await` 现在会在 pending Promise 上挂起，因此由套接字回调 settle 的 Promise
+可以被 await。见 [language-support.md](./language-support.md)。
 
 ### `gui` —— HTML/CSS 窗口
 
@@ -81,9 +82,10 @@ Windows 唯一不支持的：Windows 的 `gui.a` 不构建 FFmpeg，媒体槽位
 
 ## 第三方 npm 包
 
-没有被已启用扩展认领的裸说明符，会在 `node_modules` 里查找并**作为源码**打包。不是
-纯 ESM TypeScript/JavaScript 的包——或依赖 CommonJS、`require`、`__dirname`、循环
-依赖的包——都不会工作。`require()` 会被拒绝并提示改用 `import`。
+没有被已启用扩展认领的裸说明符，会在 `node_modules` 里查找并**作为源码**打包，
+CommonJS 包也在支持范围内（打包器会给它合成 `module`/`exports`，并降级其中的
+`require` 调用）。不支持的场景：动态 `require(<表达式>)`、依赖 `__dirname` 等 Node
+全局变量的包，以及循环依赖。自己源码里的 `require()` 会被拒绝并提示改用 `import`。
 
 实践结论：写 Node 程序时，正确做法通常就是开 `--ext node`；只有确实必要时才去依赖
 npm 包。
@@ -126,7 +128,8 @@ xbintsc build demo.ts --ext-native a.json,b.json      # 多个
 与值的辅助函数。关键 ABI 事实：值是 64 位 NaN-boxed 字；字符串**不**以 NUL 结尾，
 所以要把 `xt_string_data` 与 `xt_string_length_value` 配对使用；运行时交给你的内存
 不会被移动或释放。请使用与 xbintsc 解析到的同一个 clang/ABI 构建（`xbintsc doctor`
-会打印它）；在 Windows 上要在 **x64/ARM64 Native Tools 命令提示符**里构建。
+会打印它）。Windows 上必须是面向 MSVC 的 clang，通常就是 Visual Studio 自带的
+LLVM；不需要开发者命令提示符。
 
 可直接照抄的工程：[`examples/extensions/cpp`](../../../examples/extensions/cpp) 与
 [`examples/extensions/rust`](../../../examples/extensions/rust)；完整指南见

package/doc/ai/zh-CN/language-support.md

@@ -6,8 +6,8 @@ xbintsc 编译 TypeScript 的一个**实用子集**。本页用来判断你能
 权威细节（始终最新、篇幅长得多）：
 
 - [../../zh-CN/implemented.md](../../zh-CN/implemented.md) —— 所有已实现能力，按编译器阶段组织
-- [../../zh-CN/unimplemented.md](../../zh-CN/unimplemented.md) —— 不支持的语法、行为偏差、速查表
-- [../../zh-CN/node-implemented.md](../../zh-CN/node-implemented.md) / [../../zh-CN/node-unimplemented.md](../../zh-CN/node-unimplemented.md) —— Node 扩展
+- [../../zh-CN/unimplemented.md](../../zh-CN/unimplemented.md) —— 不支持的语法、行为偏差，按领域分页
+- [../../zh-CN/implemented/node.md](../../zh-CN/implemented/node.md) / [../../zh-CN/unimplemented/node.md](../../zh-CN/unimplemented/node.md) —— Node 扩展
 
 ## 图例
 
@@ -28,7 +28,7 @@ xbintsc 编译 TypeScript 的一个**实用子集**。本页用来判断你能
 | `function`、箭头函数、默认参数/剩余参数 | ✅ | |
 | `namespace`/`module` 声明 | 🚫 | 解析 ✓，代码生成 ✗ |
 | `with`、`debugger` | 🚫 | 不支持 |
-| 顶层 `await` | 🚫 | 请包进 `async` 函数 |
+| 顶层 `await` | ⚠️ | 会在事件循环上阻塞直到 Promise settle（不会像 ES module 那样让出模块主体）；建议包进 `async` 函数 |
 
 ## 表达式与运算符
 
@@ -60,7 +60,7 @@ xbintsc 编译 TypeScript 的一个**实用子集**。本页用来判断你能
 | `#private` 字段/方法/静态成员 | ⚠️ | 以字面量 `#x` 键存储；不做访问控制；父子类同名可能互相覆盖 |
 | `enum`/`const enum` | ✅ | 正向 + 反向映射 |
 | `private`/`protected`/`public`/`readonly`/`abstract`/`implements` | — | 被擦除，无访问控制 |
-| 生成器 `function*`、`yield`、`yield*` | ✅ | 不支持 `async` 生成器 |
+| 生成器 `function*`、`yield`、`yield*` | ✅ | 同步与 `async function*`；支持 `for await...of` 与 `Symbol.asyncIterator` |
 | `arguments` 对象 | ✅ | 隐式提供；箭头函数看到的是自己的参数 |
 | 参数个数校验 | 🚫 | 从不校验，虽然 `fn.length` 会报声明元数 |
 
@@ -68,10 +68,13 @@ xbintsc 编译 TypeScript 的一个**实用子集**。本页用来判断你能
 
 | 特性 | 状态 | 说明 |
 | --- | --- | --- |
-| `async`/`await`、`Promise`、`Promise.all` | ⚠️ | **同步微任务模型**——`await` 一个已敲定的 Promise 会同步继续 |
-| `setTimeout` 与回调 | ⚠️ | 事件循环在**程序主体之后**才运行，因此定时器里敲定的 Promise 无法被 await |
-| 套接字/服务端（`http`、`net`、`dgram`） | ⚠️ | 同一模型：回调在程序主体之后的循环里执行 |
-| 真正的异步事件循环、worker 线程 | 🚫 | 未实现 |
+| `async`/`await`、`Promise`、`Promise.all` | ✅ | 真实挂起：async 函数体运行在栈式协程上，等待**未 settle** 的 Promise 时暂停，settle 后恢复。每次 `await` 都会让出一次，已 settle 的值或非 Promise 也会像 Node 一样排入微任务 |
+| `setTimeout` 与回调 | ✅ | 定时器运行在核心事件循环上；`await new Promise(r => setTimeout(r, ms))` 可用 |
+| `queueMicrotask` / `setImmediate` / `performance.now` | ✅ | 微任务与 Promise 共用 FIFO 队列；`setImmediate` 是零延迟定时器，返回数字 id；`performance.now` 返回单调递增的毫秒小数 |
+| 套接字/服务端（`http`、`net`、`dgram`） | ✅ | 回调在事件循环上执行，可以 settle 你正在 await 的 Promise（测试含 `net`/`http` 示例） |
+| `fs/promises` | ⚠️ | 可以 await，但每次调用仍先同步完成 I/O 再 settle，I/O 期间不会让出 |
+| worker 线程 | 🚫 | worker 是子进程 |
+| `async` 生成器 | ✅ | 可在 `await` 与 `yield` 处挂起；每次 `.next()` 返回 Promise；支持 `for await...of` |
 
 ## 类型：解析后擦除
 
@@ -90,20 +93,22 @@ xbintsc 编译 TypeScript 的一个**实用子集**。本页用来判断你能
 
 ## 标准库
 
-已实现：`Math`、`JSON`、`Date`、`RegExp`、`Map`、`Set`、`WeakMap`/`WeakSet`、
+已实现：`Math`、`JSON`、`Date`、`RegExp`、`Map`、`Set`、`WeakMap`/`WeakSet`/`WeakRef`、
 `Symbol`、`Error` 家族、`BigInt`、`Array`/`String`/`Number`/`Object` 方法、TypedArray、
 带捕获组的 `String.prototype.match`/`split`/`replace`、不可变数组方法
-（`toReversed`、`toSorted`、`toSpliced`、`with`）、全局 URI 函数。
+（`toReversed`、`toSorted`、`toSpliced`、`with`）、全局 URI 函数、
+一等公民内建构造器（`const A = Array; new A(...)`、`A.isArray`、`x instanceof A`）
+与 `Object.prototype`（`Object.getPrototypeOf({}) === Object.prototype`）。
 
 | 缺失或行为不同 | 状态 |
 | --- | --- |
-| `String.prototype.normalize`、`structuredClone` | 🚫 |
+| `String.prototype.normalize` | 🚫 |
+| `structuredClone` | ✅ 数组、对象、Map、Set、Date、RegExp 与类型化数组 |
 | `Error.stack` 采集 | ⚠️ 函数级帧（名称/文件/行号），没有列号；生成器函数体不产生帧 |
-| `Object.getPrototypeOf({})` | ⚠️ 返回 `undefined`，而非 `Object.prototype` |
 | 全局 RegExp `lastIndex` | ⚠️ `/g`、`/y` 下 `test`/`exec` 忽略它 |
 | 稀疏数组空洞、数组越界 | ⚠️ 不区分空洞；越界读得 `undefined` |
 
-完整列表见 [../../zh-CN/unimplemented.md](../../zh-CN/unimplemented.md) 第 3 节。
+完整列表见[未实现：标准库](../../unimplemented/stdlib.md)。
 
 ## 模块
 
@@ -113,9 +118,9 @@ xbintsc 编译 TypeScript 的一个**实用子集**。本页用来判断你能
 | 相对路径多文件打包 | ✅ | `./helper.js` 会解析到 `helper.ts` |
 | `import * as ns`、默认导入与具名导入 | ✅ | |
 | Node 内置模块 | ✅ | 仅在 `--ext node` 下——见 [extensions.md](./extensions.md) |
-| 裸第三方 npm 包 | 🚫 | 只有当没有扩展认领该说明符时，`node_modules` 的 ESM 包才会作为源码打包 |
-| `require()` / CommonJS | 🚫 | 被拒绝，并提示改用 `import` |
-| 循环依赖 | 🚫 | |
+| 裸第三方 npm 包 | ⚠️ | 从 `node_modules` 解析并作为源码打包（ESM 和 CommonJS 均支持）；运行时不做包查找，循环依赖会被拒绝 |
+| `require()` / CommonJS | ⚠️ | 在自己的源码里会被拒绝并提示改用 `import`；`node_modules` 内的 CommonJS 包由打包器处理 |
+| 循环依赖 | 🚫 | 仅限值导入；`import type` / `export type` 会被擦除，不构成依赖边 |
 | 实时绑定 | ⚠️ | 导入与命名空间成员都是快照 |
 | `__dirname`、`__filename` | 🚫 | 请使用 `import.meta.dirname` / `import.meta.filename` |
 
@@ -123,17 +128,18 @@ xbintsc 编译 TypeScript 的一个**实用子集**。本页用来判断你能
 
 | 项目 | 行为 |
 | --- | --- |
-| `String.prototype.length` | ⚠️ 按 **UTF-8 字节**计，不是 UTF-16 码元：`"é".length === 1`，`"😀".length === 4`；`codePointAt` 相应不同 |
+| `String.prototype.length` | ✅ UTF-16 码元（`"中文😀".length === 4`）；索引、`slice`、`indexOf`、`split`、`padStart`、`codePointAt` 使用同一模型。底层仍以 UTF-8 存储 |
+| 正则 Unicode 匹配 | ⚠️ 引擎按字节工作：字面量 `中` 仍能匹配，但 `.` 与字符类每次只消费一个字节，`\d`/`\w` 仍是 ASCII。匹配偏移（`match.index`、`search`、替换回调）按 UTF-16 码元报告 |
 | 数字格式化与强转 | ✅ 与 Node 一致（`toFixed`、`toPrecision`、十六/八/二进制解析） |
 | `BigInt` | ✅ 已实现 |
-| 垃圾回收 | ✅ 非移动标记清扫；显式根 + C 栈保守扫描；单线程、stop-the-world；无弱引用 |
+| 垃圾回收 | ✅ 非移动标记清扫；显式根 + C 栈保守扫描；单线程、stop-the-world。`WeakMap`/`WeakSet` 键使用 ephemeron 不动点，`WeakRef` 目标不可达时清空；保守栈上的残留字可能延迟清空 |
 | 线程 | 🚫 单线程；`worker_threads` 只存在于 Node 扩展中 |
 
 ## 平台
 
 构建目标覆盖 macOS、Linux、Windows 的 x64 与 arm64。Windows 上是 **MSVC ABI**，
-clang 需要 MSVC/SDK 环境——见 [../../zh-CN/requirements.md](../../zh-CN/requirements.md)。
-需要 clang **16 或更新**。
+编译器必须是面向 MSVC 的 clang（Visual Studio 自带的 LLVM 即可）——见
+[../../zh-CN/requirements.md](../../zh-CN/requirements.md)。需要 clang **16 或更新**。
 
 ## 写大程序之前
 

package/doc/ai/zh-CN/troubleshooting.md

@@ -47,10 +47,10 @@ export xbintsc_CLANG=/usr/lib/llvm-18/bin/clang
 xbintsc run app.ts --ext node
 ```
 
-### `module '<pkg>' is not supported: xbintsc can import built-in platform modules, relative '.ts' files and ESM packages under node_modules; CommonJS packages are not supported`
+### `module '<pkg>' is not supported: expected a Node built-in (with --ext node), a relative .ts/.js file, or a package in node_modules`
 
-一个没人认领、也链不进来的裸第三方导入。要么该包是 CommonJS（不支持），要么它是
-打包失败的 ESM 包。优先改用 `node` 扩展提供的 Node 内置模块；可打包的范围见
+一个既没有被已启用扩展认领、也没能在 `node_modules` 里解析到的裸导入。检查包名和它的
+`exports`/`main` 字段，或改用 `node` 扩展提供的 Node 内置模块；可打包的范围见
 [extensions.md](./extensions.md)。
 
 ### ``CommonJS `require()` is not supported``
@@ -91,9 +91,10 @@ clang 自身失败。抛出的消息包含完整的 clang 命令与 stderr——
 第一行。常见原因：
 
 - 工具链太旧（见上文）；
-- Windows 上 clang 因为环境没导入而找不到 MSVC/SDK 头文件或库。请在
-  **x64 Native Tools Command Prompt for VS 2022**（ARM64 机器上是 **ARM64 Native
-  Tools**）里运行，或先导入环境：
+- Windows 上解析到的 clang 找不到 MSVC/SDK 头文件或库。`xbintsc doctor` 会显示
+  编译器及其目标；优先使用 Visual Studio 自带的 LLVM，它会自行定位 SDK。如果你的
+  安装仍需要显式导入环境，请在 **x64 Native Tools Command Prompt for VS 2022**
+  （ARM64 机器上是 **ARM64 Native Tools**）里运行，或先导入环境：
   ```powershell
   & "$env:ProgramFiles\Microsoft Visual Studio\2022\BuildTools\VC\Auxiliary\Build\vcvarsall.bat" x64
   ```
@@ -110,8 +111,8 @@ clang 自身失败。抛出的消息包含完整的 clang 命令与 stderr——
 ### `Icon file not found` / 图标工具缺失
 
 `--icon`/`app.icon` 的路径相对配置文件目录解析。Windows 上嵌入 PE 图标需要
-`llvm-rc` 或 `windres`；`doctor` 会报告找到了哪个，只有在确实请求了图标时缺失才是
-致命错误。
+`llvm-rc`（随 LLVM 一起安装）；`doctor` 会报告解析到的工具，只有在确实请求了
+图标时缺失才是致命错误。
 
 ## 怎么看堆栈
 
@@ -166,8 +167,9 @@ gdb ./build/app          # 或 lldb ./build/app，Windows 用 WinDbg 打开 .exe
 
 ### 程序输出顺序出乎意料
 
-`async`/`await` 是同步微任务模型，且事件循环只在程序主体之后运行，所以定时器和套接字
-回调会晚触发；见 [language-support.md](./language-support.md)。
+`async`/`await` 只在 **pending** Promise 上挂起；等待已 settle 的值会同步继续，而 Node
+会排入微任务，因此顺序可能不同。事件循环仍在程序主体之后启动，定时器与套接字回调依然
+在主体之后触发；见 [language-support.md](./language-support.md)。
 
 ## 该去源码哪里看
 

package/doc/gui/build.md

@@ -19,10 +19,19 @@
 - `src/extensions/gui/index.ts` exposes the archive through `nativeObjects()`
   (via `findRuntimeLibrary`, so `.a`/`.lib` both work) and the OS frameworks
   through `linkerFlags()`.
+- `scripts/build-gui.ts` compiles with the *same* clang the driver resolves
+  (`src/driver/toolchain-provider.ts`); on Windows that is the MSVC-targeting
+  LLVM bundled with Visual Studio, and its sibling `clang++`/`llvm-ar` are used
+  for CMake, the engine and the archive merge. There are no `gcc`/`g++`
+  fallbacks, and Windows always uses `llvm-ar`, so the archive cannot mix object
+  formats or C++ runtimes. The Visual Studio toolchain is found by absolute
+  path, so no developer prompt is required. On Windows SDL_GPU selects the
+  Vulkan backend; no DXIL/`dxc` toolchain is needed.
 - CI builds `gui.a` before assembling the release archive so it ships inside
   `runtime/lib/<slug>/` (the release tarball copies the whole `runtime/` tree).
   The archive is built and the example is run on Linux (under Xvfb, with the
-  lavapipe software Vulkan driver) and macOS; Windows is provisional.
+  lavapipe software Vulkan driver) and macOS; Windows is provisional because the
+  hosted runners have no GPU/Vulkan driver.
 - The existing cache fingerprint already hashes `nativeObjects()` contents, so
   rebuilding `gui.a` invalidates cached binaries automatically.
 - CMake build trees live *next to* their sources (`vendor/sdl-build`,
@@ -60,9 +69,9 @@ working directory, so run it from the repository root:
 Set `XT_GUI_AUTOCLOSE_MS=<n>` to close all windows after `n` milliseconds,
 which the e2e test (`tests/e2e/gui-*.test.ts`) uses to run headlessly.
 
-Those suites are skipped on Windows by default (the archive is built there but
-the run is not validated in CI). With a `gui.lib` and a working GPU, opt in with
-`xbintsc_GUI_TESTS=1`:
+Those suites are skipped on Windows by default (the archive is built and runs
+locally through Vulkan, but CI runners have no GPU driver to run it). With a
+`gui.lib` and a working GPU, opt in with `xbintsc_GUI_TESTS=1`:
 
 ```bat
 set xbintsc_GUI_TESTS=1

package/doc/gui/known-issues.md

@@ -57,14 +57,17 @@
   collide: `LNK2038: mismatch detected for 'RuntimeLibrary'` plus a wall of
   `LNK2005: already defined`, surfaced as `clang: linker command failed with exit
   code 1169`. `src/extensions/gui/index.ts` now lists only the OS libraries
-  (`user32`, `gdi32`, `d3d12`, …). A Windows link is also the only place the
-  MSVC environment matters, so build from an x64 Native Tools prompt.
+  (`user32`, `gdi32`, `d3d12`, …). `scripts/build-gui.ts` resolves the same
+  MSVC-targeting clang as the driver (the LLVM bundled with Visual Studio when
+  no newer one is on `PATH`), so a developer prompt is not required.
 - Windows: an MSVC-compatible `gui.lib` (COFF objects + `ar -M`/`llvm-ar`) is
   produced by `scripts/build-gui.ts` but is not validated in CI, so the Windows
   step is provisional (the job stays green) and `package` skips it. Building and
   running `examples/gui/pelican-svg` and `examples/gui/pelican-bike` on a
-  developer machine works. It also needs an SDL3 build with the D3D12/DXIL
-  backend (DXIL requires `dxc`).
+  developer machine works. SDL_GPU selects the **Vulkan** backend there
+  (`win.driver()` reports `"vulkan"`), so the archive needs no DXIL/`dxc`
+  toolchain; the hosted Windows runners have no GPU/Vulkan driver, which is why
+  the CI run stays provisional.
 - **Media on Windows:** the media decoders (FFmpeg) are only built and merged
   into the POSIX `gui.a`; the Windows `gui.lib` is produced without them, so
   `<video>`/`<audio>` are inert there (failures fire `error`). Enabling it needs
@@ -75,4 +78,5 @@
   and embedded, so the non-Metal path no longer skips geometry. DXIL remains
   unusable on **SDL 3.2.10**: its D3D12 backend rejects any graphics pipeline
   whose shaders declare a uniform buffer, and the engine passes the viewport that
-  way. Re-check after an SDL upgrade.
+  way. This does not affect Windows in practice because SDL_GPU selects Vulkan
+  there; re-check after an SDL upgrade if the D3D12 path is ever forced.

package/doc/gui/rendering.md

@@ -43,7 +43,9 @@ its own GPU scissor rectangle (scaled to device pixels), so painter order and
   Note that SDL 3.2.10's Direct3D 12 backend cannot create a graphics pipeline
   whose shaders declare a uniform buffer (it fails with `E_INVALIDARG`); the
   engine passes the viewport that way, so the DXIL path is built but not usable
-  until that is resolved upstream.
+  until that is resolved upstream. Windows does not hit this: SDL_GPU selects the
+  Vulkan backend there (confirmed by `win.driver()`), which consumes the SPIR-V
+  blobs.
 - A **rounded-rectangle distance field** in the shape fragment shader gives
   antialiased fills; the vertex carries `position`, `local`, `half extents`,
   `radius` and colour, and a viewport-size push constant does the projection.

package/doc/gui.md

@@ -179,9 +179,10 @@ engine were Rust.
      `runtime/`).
    - `vendor/` (SDL3/FreeType/HarfBuzz, the slow part) is cached per OS/arch,
      keyed by `scripts/build-gui.ts`.
-   - Windows (build + run) stays provisional until the MSVC-compatible
-     `gui.lib` and D3D12/DXIL shader path are validated; a failure is logged
-     without annotating the run (see [Open questions](./gui/known-issues.md#open-questions)).
+   - Windows (build + run) stays provisional in CI: the MSVC-compatible
+     `gui.lib` builds and runs locally through SDL_GPU's Vulkan backend, but the
+     hosted runners have no GPU/Vulkan driver. A failure is logged without
+     annotating the run (see [Open questions](./gui/known-issues.md#open-questions)).
 8. **M8 — interactive DOM** ✅
    - Element/document handles with stable identity, read/write properties via
      runtime accessors, traversal/attributes/queries, mutation with lazy

package/doc/icon.md

@@ -160,7 +160,8 @@ does).
 
 - `src/cli/main.ts`: `--icon`, `--bundle`, `--app-name`, `--app-id`, `--config`,
   `--no-config`; merged with the config (`mergeAppConfig`).
-- `src/driver/compiler.ts`: `BuildOptions.icon` and `BuildOptions.app`.
+- `src/driver/options.ts`: `BuildOptions.icon` and `BuildOptions.app` (assembled
+  into the cache key by `src/driver/build-key.ts`).
   - The icon **content hash** and the packaging options are part of the
     executable `cacheKey`, so changing the icon rebuilds.
   - The icon object and (on win32) the resource object are appended to the link
@@ -175,8 +176,8 @@ does).
 1. A PNG input is wrapped in a minimal ICO container (`ICONDIR` +
    `ICONDIRENTRY` pointing at the PNG payload); Vista+ accepts PNG-in-ICO.
 2. A `.rc` (`1 ICON "icon-<hash>.ico"`) is written next to it in the cache.
-3. `llvm-rc /fo app.res app.rc` (preferred, next to the resolved clang or on
-   `PATH`), else MinGW `windres app.rc -O coff -o app_res.o`. Override with
+3. `llvm-rc /fo app.res app.rc` (next to the resolved clang, or on `PATH`).
+   `llvm-rc` is probed with `/?` — it has no `--version`. Override it with
    `xbintsc_RC`.
 4. If no resource compiler exists, the build continues with the runtime icon only
    (a cosmetic feature never hard-fails a build).
@@ -234,7 +235,7 @@ ELF has no icon convention. The only in-binary use is the runtime window icon
 
 - `tests/driver/config.test.ts` — parse/validate, discovery, path resolution.
 - `tests/driver/icon.test.ts` — format sniffing, generated C, ICO conversion,
-  icon object caching, `llvm-rc`/`windres` command lines, mac bundle layout and
+  icon object caching, `llvm-rc` command lines, mac bundle layout and
   fallbacks, and `build()` integration (icon objects linked, missing icon ⇒
   `DiagnosticCode.IOError`).
 - `tests/e2e/icon.test.ts` — compiles a real GUI program with `app.icon`,

package/doc/implemented/async.md

@@ -0,0 +1,38 @@
+# Async, promises and generators
+
+> Part of [Implemented syntax and features](../implemented.md) · [简体中文](../zh-CN/implemented/async.md)
+
+Location: `runtime/xt_async.c`, `runtime/xt_coroutine.c`, `runtime/xt_promise.c`,
+`runtime/xt_generator.c`, `runtime/xt_loop.c`, `runtime/xt_performance.c`.
+
+## async / await
+
+- `async` closures are marked with `xt_function_set_async`; calling one runs the body on a stackful coroutine (`xt_coroutine.c`, `xt_async.c`) and immediately returns a promise.
+- The body runs synchronously until the first `await` of a pending promise, then suspends; settlement queues a microtask that resumes the coroutine.
+- An exception that escapes the body rejects that promise instead of throwing synchronously.
+- `await` on a non-promise or settled promise keeps the synchronous fast path and raises on rejection.
+- Each `async` call owns a private stack and swaps its `try` frame stack and GC stack region, so `await` survives `try`/`finally`, loops and closures. A promise settled from a timer, a socket callback or another coroutine resumes the suspended body on the microtask queue.
+
+## async generators
+
+- `async function*` closures are marked with `xt_function_set_async_generator`; each `.next()` / `.throw()` / `.return()` enqueues a request and returns a promise.
+- The body runs on the generator coroutine and may suspend at either `yield` or `await`; `xt_generator_await` parks it on the awaited promise and leaves the current request pending until the next yield or completion.
+- `for await...of` lowers to `xt_async_iter_open` / `xt_async_iter_next` + `xt_await`, so it consumes both async iterables and the synchronous iteration protocol. `Symbol.asyncIterator` is supported.
+
+## Generators
+
+- `function*` / `yield` / `yield*`, with `.next()` / `.throw()` / `.return()`, is implemented on the same stackful-coroutine runtime.
+- `for...of`, spread and delegation are supported.
+
+## Promise
+
+- Microtask queue (`xt_microtasks`); `xt_promise_ctor/resolve/reject/static` (including `withResolvers`), instance `then` / `catch` / `finally`.
+- `xt_drain_microtasks` empties the queue at program exit, and the event loop drains it between callbacks.
+- `xt_await` queues a microtask for a non-promise or settled value, and suspends the running async coroutine on a pending promise until it settles.
+
+## Timers and the event loop
+
+- `setTimeout` / `clearTimeout` / `setInterval` / `clearInterval` / `setImmediate` / `clearImmediate` / `queueMicrotask` and `performance.now` (monotonic fractional milliseconds).
+- Timers use numeric ids; `Timeout` / `Immediate` objects are not implemented.
+- A promise settled from a timer can be awaited: the async body suspends on the pending promise and resumes when the timer fires. Sockets and servers (`net`, `http`, `dgram`) deliver their callbacks on the same loop.
+- `fetch` is blocking and `fs/promises` performs its I/O synchronously before settling — see [Runtime deviations](../unimplemented/deviations.md). Async generator cleanup limits are listed on the same page.

package/doc/implemented/binder.md

@@ -0,0 +1,13 @@
+# Name binding and scopes (Binder)
+
+> Part of [Implemented syntax and features](../implemented.md) · [简体中文](../zh-CN/implemented/binder.md)
+
+Location: `src/binder/binder.ts`
+
+- Scope kinds: module, function, block, `for`, `catch`
+- Symbol kinds: `var` / `let` / `const` / `function` / `parameter` / `class` / `interface` / `type` / `enum` / `import` / `namespace`
+- `var` and function declarations hoist to the function scope; `let` / `const` stay block-scoped
+- Identifier → declaration resolution; unresolved identifier collection (`CannotFindName`)
+- Closure capture analysis: outer variables referenced by an inner function are marked `captured` / `boxed`, and capture indices are threaded through intermediate closures
+- Parameters are registered as local symbols; the self-name of a named function expression is registered as `const`
+- Type-only declarations (interface / type alias) do not participate in value capture

package/doc/implemented/cli.md

@@ -0,0 +1,47 @@
+# CLI and programmatic API
+
+> Part of [Implemented syntax and features](../implemented.md) · [简体中文](../zh-CN/implemented/cli.md)
+
+Location: `src/cli/main.ts`, `src/index.ts`, `bin/xbintsc.js`
+
+## CLI commands
+
+```
+xbintsc build <file.ts> [options]   compile to a native binary
+xbintsc run   <file.ts> [-- args]   compile and run
+xbintsc emit  <file.ts>             print LLVM IR
+xbintsc version                     print the version
+xbintsc help                        help
+```
+
+## CLI options
+
+```
+-o, --output <path>   Output path
+    --out <dir>       Output directory (default: build/)
+    --emit <kind>     exe | obj | ir (default: exe)
+-O0..-O3              Optimization level (default: -O2)
+    --ext <names>     Comma separated extensions (e.g. node)
+    --ext-native <m>  Register a C++/Rust extension from a JSON manifest
+    --config <path>   Use a project config (default: xbintsc.config.json)
+    --no-config       Do not read any project config
+    --icon <path>     Embed an application icon (PNG/ICO/ICNS)
+    --bundle          macOS: also produce a .app bundle
+    --app-name <name> Bundle / display name
+    --app-id <id>     macOS bundle identifier (e.g. com.example.demo)
+    --force           Ignore the incremental cache
+    --verbose         Print progress information
+```
+
+## Programmatic API
+
+```ts
+import { build, compileString } from "xbintsc";
+
+const { ir } = compileString("console.log(1 + 1);");
+const result = build("program.ts", { emit: "exe", outDir: "build" });
+```
+
+The option and result types (`BuildOptions`, `BuildResult`, `EmitKind`,
+`PhaseTiming`) live in `src/driver/options.ts` and are re-exported from
+`src/driver/compiler.ts` / `xbintsc`.

package/doc/implemented/codegen.md

@@ -0,0 +1,33 @@
+# LLVM IR code generation (Codegen)
+
+> Part of [Implemented syntax and features](../implemented.md) · [简体中文](../zh-CN/implemented/codegen.md)
+
+Location: `src/codegen/llvm.ts`
+
+- Emits LLVM IR text (`.ll`); no custom register allocation (relies on `alloca` + mem2reg).
+- Statement / block boundary values live in `alloca`; conditionals and short-circuits materialize into temporary slots instead of `phi`.
+- Property reads are inline-cached per source site: each access owns a zeroed `[2 x i64]` global (`@ic.N`) passed to `xt_get_ic`. Ordinary objects carry an interned hidden-class shape (`xt_shape`, a `(parent, key)` transition tree) and the cache stores `(shape, property index)`, so a hit is a shape-pointer compare plus one key check instead of a linear property scan. Inserts/deletes and integer-key reordering rebuild or transition the shape, which invalidates stale caches; arrays, functions and containers fall back to `xt_get`.
+- Numeric operators keep the inline two-double fast path; operands that are numeric literals skip their tag check. Conditions whose expression is a comparison, `in`, `instanceof` or `!` are already boolean tags, so codegen emits `icmp eq i64 value, XT_TRUE` instead of calling `xt_truthy` (this removes the call from the hot loop condition).
+- Control flow: `if` / `while` / `do` / `for` / `for...of` / `for...in`, `switch`, `try/catch/finally`, `break` / `continue` / `return`.
+  - `for...of` and spread iterate arrays, strings, typed arrays, `Map`, `Set`, generators and any object exposing `[Symbol.iterator]()` through `xt_iter_open` → `xt_iter_has` / `xt_iter_value` (`Map` yields `[key, value]` pairs); a non-iterable throws `TypeError`. Arrays also expose a stable `Array.prototype[Symbol.iterator]`; calling it returns an iterator object with `next()` that is itself iterable.
+  - `switch` tests each `case` with strict equality, executes on a hit, and falls through until `break`.
+  - `try/catch/finally` is implemented with a runtime `_setjmp` frame: `xt_try_enter` pushes, `_setjmp` catches, `xt_throw` long-jumps. The IR passes the caller's frame address (`@llvm.frameaddress(0)`) as the second `_setjmp` argument, matching clang's MSVC lowering: the Windows UCRT `_setjmp` stores that frame in `_JUMP_BUFFER.Frame` and `longjmp` feeds it to `RtlUnwind`, so omitting it made `longjmp` unwind to a bogus target (`STATUS_BAD_FUNCTION_TABLE`). `_setjmp` is used rather than the exported `setjmp` symbol, whose Windows ABI is an incompatible two-argument routine. Functions containing `try` force local variables to stay in memory (inline-asm escape points) so values survive a long jump.
+  - `for...in` reuses `xt_object_keys` to enumerate keys (arrays / strings yield string indices).
+- Expressions:
+  - Identifiers, numbers, BigInt (arbitrary precision), strings, templates, booleans, `null`, `undefined`, `arguments`
+  - Arithmetic / comparison / logical / short-circuit / conditional / bitwise / unary (including `typeof` `void`) / prefix-postfix increment-decrement / compound assignment / logical assignment
+  - Array literals (including spread `[...]`), object literals (including shorthand / methods / object spread `{...obj}`)
+  - Typed arrays, `ArrayBuffer`, `DataView`, `TextEncoder` / `TextDecoder`: see [Typed arrays and binary data](./typed-arrays.md) and [Strings and text](./strings.md)
+  - Property access (with a `length` special case, `Math` constants), element access, calls
+  - First-class built-in constructors (`const A = Array`, `const M = Map`, `const E = TypeError`, typed arrays): a bare reference lowers to `xt_builtin_constructor`, giving a cached function with `name` / `length`, a `prototype`, and its statics (`A.isArray`, `A.from`, `M.prototype`, ...). Calling or `new`-ing an alias dispatches to the same runtime constructor, and `x instanceof A` walks the shared prototype chain.
+  - Optional chaining `?.` / `?.[]` / `?.()`: nullish check short-circuits to `undefined`
+  - `delete`, `in`, `instanceof`
+  - `this` (saved to the function's `%saved.this`; arrow functions read from an environment slot), `super` (`super.x` / `super(...)`), `new`, `await`
+  - Closures (arrow functions / function expressions) and capture environment construction
+- Classes: constructor closure + prototype object, stored in an LLVM global (`@class.<id>`); instance fields are initialized before the constructor body; `static` members live in the constructor's property bag; `extends` sets up the prototype chain; `super(...)` is invoked through a hidden `__ctor` on the prototype.
+- `async` / `async function*`: closures are marked with `xt_function_set_async` / `xt_function_set_async_generator` and run on stackful coroutines — see [Async, promises and generators](./async.md).
+- Standard library calls dispatch through `xt_call_method` / `xt_math_call` / `xt_object_*` and the per-constructor `xt_*` entry points; the surface is listed in [Standard library](./stdlib.md).
+- Global string pool (`@.str.N` private constants, UTF-8 escaped).
+- Builtin calls: `console.log` / `info` / `warn` / `error`, `Math.*`, `Object.*`, array / string methods, global functions, extension builtins (uniform `(argc, argv)` ABI).
+- `main` entry point (returns 0, calls the module function, then drains microtasks and runs the event loop until no timers or descriptors remain).
+- Unsupported nodes uniformly report `UnsupportedFeature`; they never crash.

package/doc/implemented/collections.md

@@ -0,0 +1,26 @@
+# Collections
+
+> Part of [Implemented syntax and features](../implemented.md) · [简体中文](../zh-CN/implemented/collections.md)
+
+Location: `runtime/xt_stdlib2/container.inc` (Map / Set) and
+`runtime/xt_weak.c` (WeakMap / WeakSet / WeakRef).
+
+## Map and Set
+
+- `new Map()` / `new Map(iterable)` and `new Set()` / `new Set(iterable)`.
+- `Map`: `size`, `get` / `set` / `has` / `delete` / `clear` / `forEach` / `keys` / `values` / `entries`.
+- `Set`: `size`, `add` / `has` / `delete` / `clear` / `forEach` / `values` / `keys` / `entries`.
+- `for...of` and spread iterate them through `[Symbol.iterator]`; a `Map` yields `[key, value]` pairs, and `keys` / `values` / `entries` return arrays in insertion order.
+- `Object.keys` / `values` / `entries` do not see collection internals.
+- `structuredClone` supports `Map` and `Set`, preserving cycles and shared references.
+
+## WeakMap, WeakSet and WeakRef
+
+- `WeakMap`: `get` / `set` / `has` / `delete`; `WeakSet`: `add` / `has` / `delete`; `WeakRef`: `deref()`.
+- Keys (and `WeakRef` targets) do not keep their referents alive: `WeakMap` / `WeakSet` keys are **ephemerons** (a value is retained only while its key is reachable) and a `WeakRef` target is cleared when it becomes unreachable.
+- The stack scan is conservative, so a stale stack word can delay clearing a weak target. The full GC description is in [Runtime deviations](../unimplemented/deviations.md) and [Unimplemented: toolchain](../unimplemented/toolchain.md).
+
+## Iteration
+
+- Any object exposing `[Symbol.iterator]()` is iterable in `for...of` and spread. `Array.prototype[Symbol.iterator]` is stable, and calling it returns an iterator object with `next()` that is itself iterable.
+- Iteration is described further in [Codegen](./codegen.md#llvm-ir-code-generation-codegen) and [Symbol](./stdlib.md#symbol).

package/doc/implemented/driver.md

@@ -0,0 +1,19 @@
+# Driver, incremental compilation and toolchain
+
+> Part of [Implemented syntax and features](../implemented.md) · [简体中文](../zh-CN/implemented/driver.md)
+
+Location: `src/driver/compiler.ts` (orchestration), `src/driver/frontend.ts`,
+`src/driver/build-key.ts`, `src/driver/runtime-objects.ts`,
+`src/driver/app-artifacts.ts`, `src/driver/cache.ts`, `src/driver/toolchain.ts`,
+`src/driver/paths.ts`, `src/driver/version.ts`.
+
+- Compilation pipeline: read source → module bundling (`src/driver/modules.ts`, when the entry contains `import`/`export`) → parse → bind/check → IR → object file → link.
+- Incremental cache: keyed on "compiler version + source hash + emit kind + optimization level + LTO/PGO mode + platform + extension fingerprint (names, linker flags, native object contents)"; if the artifacts exist and are fresh, the build is skipped. `--pgo-use` always rebuilds because the profile data can change without the source. The key is assembled in `src/driver/build-key.ts`.
+- C runtime and extension sources are cached as object files by content hash and compiled only once (the cache key includes the LTO/PGO flags). `RUNTIME_SOURCES` in `src/driver/runtime-objects.ts` lists the core translation units.
+- Toolchain wrapper: locates `clang` (overridable with `xbintsc_CLANG`), compiles IR, compiles C, links.
+- LTO (`--lto` / `"lto": true`): the program and runtime compile to LLVM bitcode (`-flto`) and link with `-fuse-ld=lld`; lld is required.
+- PGO (`--pgo-generate[=dir]` then `--pgo-use[=dir]`, or `"pgo"` / `"pgoDir"`): the generated IR and runtime C are instrumented with `-fprofile-generate=<dir>`; after running the instrumented binary, `--pgo-use` merges `.profraw` files with `llvm-profdata` (preferring the copy next to clang, overridable with `xbintsc_LLVM_PROFDATA`) and rebuilds with `-fprofile-use=<dir>`.
+- Link flags: `-lm` is added automatically on non-Windows; extensions may append extra link flags.
+- Project config (`src/driver/config.ts`, `xbintsc.config.json`): `entry`, `outDir`, `output`, `optimize`, `lto`, `pgo`, `pgoDir`, `extensions`, `extNative`, `force` and `app` (`name`, `icon`, `bundle`, `bundleId`). Discovered by walking up from the entry/cwd, overridable with `--config`, disabled with `--no-config`; every path resolves against the config directory; CLI flags win over config values.
+- Application icon (`src/driver/icon.ts`, `win-icon.ts`, `mac-bundle.ts`, `--icon`/`app.icon`): PNG/ICO/ICNS is embedded as `xt_app_icon_*` symbols, synthesized into a PE resource via `llvm-rc` on Windows, and packaged into `Foo.app` (with `AppIcon.icns` via `sips`/`iconutil`) on macOS. The `gui` extension calls `SDL_SetWindowIcon` from the embedded bytes. `xbintsc_RC` overrides the resource compiler.
+- Compiler version: `COMPILER_VERSION` lives in `src/driver/version.ts` and is part of the cache key. The pre-commit hook bumps it (together with `package.json`) only on `main`/`master`, so feature branches never touch the version files.

package/doc/implemented/extensions.md

@@ -0,0 +1,19 @@
+# Extension mechanism
+
+> Part of [Implemented syntax and features](../implemented.md) · [简体中文](../zh-CN/implemented/extensions.md)
+
+Location: `src/extensions/registry.ts`, `src/extensions/node/`
+
+- An extension is a plain object: `runtimeSources()` (extra C sources), `linkerFlags()` (extra link flags), `builtins()` (global identifier → runtime symbol, uniform `(argc, argv)` ABI) and `modules()` (import specifier → named exports / namespace).
+- `ExtensionRegistry`: register / unregister / lookup / aggregate builtins, modules, runtime sources and link flags.
+- The built-in core extension `core`: exposes `print` (mapped to `xt_println`), always registered.
+- The Node extension `node`:
+  - Modular organisation: `src/extensions/node/fs/` + `runtime/ext_node/fs/read_file.c`
+  - Exposes importable modules (`fs`, `fs/promises`, `path`, `os`, `process`, ...) under both bare and `node:`-prefixed specifiers; `import { readFileSync } from "fs"` resolves to `xt_node_read_text_file`, and `path`/`os`/`process` map exports onto the namespace dispatchers.
+- Adding a new module only requires a new directory plus a C implementation; the core compiler never changes.
+- Native C++/Rust extensions (`src/extensions/native.ts`, `--ext-native`):
+  - `nativeObjects()` links pre-built objects/static archives that expose `extern "C"` symbols with the `(argc, argv)` ABI; a JSON manifest maps them onto builtins/modules (`linkerFlags` / `linkerFlagsByPlatform` cover C++/Rust runtimes).
+  - Authoring helpers live in `runtime/xt_ext.h` (C/C++) and `runtime/xt_ext.rs` (Rust); runnable projects are under `examples/extensions/`.
+  - The driver links the artifacts verbatim and the incremental cache fingerprints their contents, so a rebuilt library invalidates the cached binary.
+  - CI builds both language examples on Linux, macOS and Windows; on Windows the system clang links with the MSVC ABI (C++ `-lmsvcprt`, Rust `*-pc-windows-msvc` plus the Windows system libraries).
+- Node module coverage is documented in [Node extension](./node.md).