xbintsc 0.5.6 → 0.5.21

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 扩展
 
 ## 图例
 
@@ -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,11 +68,14 @@ xbintsc 编译 TypeScript 的一个**实用子集**。本页用来判断你能
 
 | 特性 | 状态 | 说明 |
 | --- | --- | --- |
-| `async`/`await`、`Promise`、`Promise.all` | ✅ | 真实挂起：async 函数体运行在栈式协程上，等待**未 settle** 的 Promise 时暂停，settle 后恢复。等待已 settle 的值仍同步继续 |
+| `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 期间不会让出 |
-| `async` 生成器、worker 线程 | 🚫 | `async function*` 被拒绝；worker 是子进程 |
+| `fs/promises` | ✅ | 文件、目录与 `FileHandle` 操作跑在异步 I/O 线程池上，并在 reactor 上 settle，等待期间定时器与套接字继续运行 |
+| 全局 `fetch` | ✅ | HTTP/1.1 客户端，connect/send/receive 跑在同一线程池；`await fetch(...)` 会让出，重定向在 reactor 上处理。仅 `http://`（无 TLS），resolve 前缓冲整个响应体 |
+| worker 线程 | 🚫 | worker 是子进程 |
+| `async` 生成器 | ✅ | 可在 `await` 与 `yield` 处挂起；每次 `.next()` 返回 Promise；支持 `for await...of` |
 
 ## 类型：解析后擦除
 
@@ -91,7 +94,7 @@ 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 函数、
@@ -100,12 +103,13 @@ xbintsc 编译 TypeScript 的一个**实用子集**。本页用来判断你能
 
 | 缺失或行为不同 | 状态 |
 | --- | --- |
-| `String.prototype.normalize`、`structuredClone` | 🚫 |
+| `String.prototype.normalize` | 🚫 |
+| `structuredClone` | ✅ 数组、对象、Map、Set、Date、RegExp 与类型化数组 |
 | `Error.stack` 采集 | ⚠️ 函数级帧（名称/文件/行号），没有列号；生成器函数体不产生帧 |
 | 全局 RegExp `lastIndex` | ⚠️ `/g`、`/y` 下 `test`/`exec` 忽略它 |
 | 稀疏数组空洞、数组越界 | ⚠️ 不区分空洞；越界读得 `undefined` |
 
-完整列表见 [../../zh-CN/unimplemented.md](../../zh-CN/unimplemented.md) 第 3 节。
+完整列表见[未实现：标准库](../../unimplemented/stdlib.md)。
 
 ## 模块
 
@@ -115,9 +119,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` |
 
@@ -129,14 +133,14 @@ xbintsc 编译 TypeScript 的一个**实用子集**。本页用来判断你能
 | 正则 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` 会报告解析到的工具，只有在确实请求了
+图标时缺失才是致命错误。
 
 ## 怎么看堆栈
 

package/doc/gui/api.md

@@ -65,6 +65,7 @@ win.documentTree()                     // serialized DOM (debugging)
 win.layoutTree()                       // serialized layout boxes (debugging)
 win.paintCount()                       // number of shapes in the display list
 win.paintList()                        // serialized display list (debugging)
+win.inlineSvg(selector)                // serialized inline <svg>: { markup, width, height, shapes }
 win.measureText(text, fontSize?, family?)  // shaped advance width in pixels
 win.fontMetrics(fontSize?, family?)    // { ascent, descent, lineHeight, ready }
 win.hitTest(x, y)                      // deepest element descriptor, or ""
@@ -73,6 +74,13 @@ win.advance(ms)                        // step the CSS transition clock (testing
 win.stats()                            // engine/runtime counters (memory debugging)
 ```
 
+`win.inlineSvg(selector)` returns the standalone SVG document the engine builds
+from the first `<svg>` element matching `selector` (`markup`), together with the
+intrinsic size and shape count NanoSVG parses out of it; it is `undefined` when
+nothing matches or the element is not an `<svg>`. It makes the serializer's
+canonical casing (`viewBox`, `linearGradient`, `gradientUnits`, …) testable
+without a GPU — the HTML parser delivers those names lowercased.
+
 `win.stats()` returns `{ heapBytes, heapAllocations, treeNodes, detachedRoots,`
 `detachedNodes, handles, handleSlots, listeners }`: the live runtime heap, the
 size of the DOM tree, the detached-node pool, and the element-handle tables. In a

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

@@ -34,20 +34,21 @@
   *class change* on a flex container has also been observed to crash the same
   way; `examples/gui/pelican-bike` reveals its game-over overlay with `opacity`
   instead.
+- **SVG is NanoSVG's subset.** SVG *files* (`<img src="logo.svg">`) and inline
+  `<svg>` trees share the vendored NanoSVG parser/rasteriser
+  (`runtime/ext_gui/svg.cpp`, `inline_svg.cpp`), which renders
+  `path`/`rect`/`circle`/`ellipse`/`line`/`polyline`/`polygon`, groups, `defs`
+  gradients and class-based `<style>` rules. `<text>`, `<use>`, filters, masks
+  and clip paths are not rendered, and CSS applied by the document cascade does
+  not reach inside the artwork (fill/stroke are SVG presentation attributes,
+  not CSS properties here). Vector art that needs those has to be rasterised
+  beforehand, drawn from boxes, or restricted to the supported syntax. See
+  [Media](./media.md#images-m6a).
 
 ## Open questions
 
 - Whether Linux ships X11, Wayland, or both in the first cut. (Decision:
   X11 first, Wayland later.)
-- **SVG:** SVG *files* are supported through the image loader
-  (`<img src="logo.svg">`): `runtime/ext_gui/svg.cpp` wraps the vendored
-  **NanoSVG** parser/rasteriser and `image.{h,cpp}` treats an SVG as a vector
-  image, rasterised at the drawn pixel size. Inline `<svg>` **trees** in a
-  document are still not supported: the HTML parser knows elements and
-  attributes, the layout engine knows boxes, and paint knows
-  rectangles/text/images, so `<svg>` subtrees would need a whole second
-  geometry+paint path. Vector art therefore has to arrive as an SVG/PNG file or
-  be drawn from boxes, as `examples/gui/pelican-bike` does.
 - **Windows: the C++ runtime must not be named on the link line.** `gui.lib` is
   built with the *static* CRT (`CMAKE_MSVC_RUNTIME_LIBRARY=MultiThreaded`) and
   every engine object records `libcpmt` as a dependent library, which is also
@@ -57,14 +58,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 +79,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/media.md

@@ -12,7 +12,9 @@ size cache (`stbi_info`). Paths accept a `file://` prefix and percent-encoding.
 library (parse + anti-aliased scanline rasteriser), detects an SVG by extension
 or by its contents, and produces the same RGBA8 `Image` the pipeline already
 consumes. `stb_image` cannot decode SVG, so this is what makes
-`<img src="logo.svg">` work.
+`<img src="logo.svg">` work. The same parser is used for an inline `<svg>`
+subtree, whose DOM nodes are serialized into a document first
+(`inline_svg.{h,cpp}`).
 
 - `<img>` is a replaced element (`display: inline-block`): layout gives it the
   CSS size when set, otherwise the intrinsic pixel size, and preserves the
@@ -27,12 +29,39 @@ consumes. `stb_image` cannot decode SVG, so this is what makes
   pixels (logical size × the window's pixel density), preserving the viewBox
   aspect ratio, and cached by that size, so scaling or a HiDPI display produces
   a crisp render instead of a magnified bitmap.
+- An **inline** `<svg>` element is a replaced element like `<img>`, but its
+  source is the DOM subtree itself. `runtime/ext_gui/inline_svg.{h,cpp}`
+  serializes that subtree back into a standalone SVG document, restoring the
+  case-sensitive spellings NanoSVG matches (`viewBox`, `preserveAspectRatio`,
+  `linearGradient`, `gradientUnits`, …) that the HTML parser lowercased. Layout
+  sizes the box from the `width`/`height` attributes, else the `viewBox`, else
+  300x150; paint carries the markup on its image op and the renderer parses and
+  rasterises it at the drawn device pixel size through the same NanoSVG cache as
+  an SVG file. A DOM mutation re-serializes the subtree on the next layout (so
+  `setAttribute` and `innerHTML` both repaint the artwork), and the markup cache
+  is bounded (least-recently-used) so an animated document cannot grow it
+  without limit.
 - The parse is cached per path; the parse and rasteriser state are released in
   `xt_svg_shutdown` (`xt_image_shutdown`).
 
+Document CSS styles the `<svg>` **box** — size, margins, background, borders,
+`transform`, opacity, `display` — exactly as it styles any other element. The
+artwork inside it keeps SVG semantics: presentation attributes and the
+`class`-based rules of an SVG `<style>` block are read by NanoSVG, not by the
+HTML cascade, so `fill`/`stroke` are not CSS properties here. For layout, paint,
+hit testing and events the whole `<svg>` is one replaced box: its children get no
+DOM boxes, so a click's `e.target` is the `<svg>` element, not a `<rect>`. The
+renderer caches one texture per markup-and-size pair, so a program that rewrites
+its artwork every frame keeps a texture per variant; prefer animating the box
+(`transform`, `opacity`) or swapping between a small set of documents.
+
 Still to do for images: CSS `background-image: url(...)`, `data:` URIs,
-`object-fit`, 9-slice borders and inline `<svg>` elements (only SVG *files* are
-supported; see [Open questions](./known-issues.md#open-questions)).
+`object-fit` and 9-slice borders.
+
+Both kinds of SVG share NanoSVG's subset: `path`, `rect`, `circle`, `ellipse`,
+`line`, `polyline`, `polygon`, groups (`g`), `defs` with linear/radial gradients
+and class-based `<style>` rules rasterise; `<text>`, `<use>`, filters, masks and
+clip paths are not rendered (see [Known issues](./known-issues.md)).
 
 ## Video & audio (M13)
 

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

@@ -1,6 +1,6 @@
 # xbintsc GUI extension (self-hosted HTML/CSS renderer)
 
-Status: **M15** — features (M1–M14) are complete: HTML parsing, CSS selector
+Status: **M16** — features (M1–M15) are complete: HTML parsing, CSS selector
 matching, the cascade, computed styles and layout (block, inline, Flexbox and
 CSS positioning) are
 in place, and the engine *paints*: it builds a display list of rectangles, images
@@ -9,7 +9,9 @@ tested and delivered to native TS handlers, `:hover`/`:focus` are matched
 dynamically, `<img>` is sized from its intrinsic dimensions and drawn from a
 texture — PNG/JPEG/… bitmaps and SVG files alike, the latter rasterised at the
 drawn size so vector art stays crisp — and CSS transitions animate paint
-properties. **M8** adds an interactive
+properties. **M16** gives inline `<svg>` trees the same treatment: the subtree is
+serialized back into an SVG document and rasterised at the drawn device size, so
+an icon needs no separate file. **M8** adds an interactive
 DOM: element handles with stable identity, mutation (`appendChild`, `textContent`,
 `classList`, `style`, …) and element-level events with capture/bubbling.
 **M9** compiles `<script>` bodies ahead of time (inline and `<script src>`) — see
@@ -179,9 +181,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
@@ -256,6 +259,18 @@ engine were Rust.
       [Layout](./gui/layout.md#transforms-m15) and
       [Animation](./gui/animation.md#css-transforms-m15); e2e in
       `tests/e2e/gui-transform.test.ts` and `tests/e2e/gui-example-svg.test.ts`.
+16. **M16 — inline `<svg>`** ✅
+    - `<svg>` is a replaced element (`layout.*`): its intrinsic size comes from
+      the `width`/`height` attributes, else the `viewBox`, else 300x150, and the
+      normal box walk does not descend into its children.
+    - `inline_svg.{h,cpp}` serializes the subtree into a standalone SVG document,
+      restoring the case-sensitive names the HTML parser lowercased (`viewBox`,
+      `preserveAspectRatio`, `linearGradient`, `gradientUnits`, …).
+    - Paint carries the markup on its image op (`PaintImage::svg`) and the
+      renderer parses/rasterises it at the drawn device size through the same
+      NanoSVG cache as an SVG file (`svg.{h,cpp}`); the markup cache is bounded
+      and a DOM mutation re-serializes on the next layout. e2e in
+      `tests/e2e/gui-inline-svg.test.ts`.
 
 ## Progress log
 
@@ -354,4 +369,12 @@ engine were Rust.
   through the inverse, and `getBoundingClientRect` returns the transformed AABB.
   `examples/gui/pelican-svg` animates its artwork with it; e2e in
   `tests/e2e/gui-transform.test.ts` and `tests/e2e/gui-example-svg.test.ts`.
+- **M16** ✅ inline `<svg>`. `buildBoxTree` treats an `<svg>` element as a
+  replaced box (intrinsic size from `width`/`height`, then `viewBox`, then
+  300x150) and stops descending, `inline_svg.{h,cpp}` serializes the subtree with
+  canonical SVG casing, paint carries the markup on `PaintImage::svg`, and
+  `renderer_image.cpp` rasterises it at the drawn device pixel size through the
+  NanoSVG cache (`svg.{h,cpp}`, bounded LRU for markup). The `win.inlineSvg`
+  diagnostic exposes the serialized document, and `tests/e2e/gui-inline-svg.test.ts`
+  pins sizing, hit testing, gradients, CSS box styling and mutation.
 

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,51 @@
+# 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_async_io.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, an offloaded file operation 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` and `fs/promises` are reactor-driven rather than blocking — see the next section.
+
+## Asynchronous I/O offload
+
+- `runtime/xt_async_io.c` owns a small pool of worker threads (four by default, created lazily). Jobs are split in two halves: a `run` function on a worker that may only touch plain C memory, and a `complete` function on the main thread that builds values and settles the promise. The split is what keeps the collector and the value model single-threaded.
+- A completed job wakes `select(2)` through a self-pipe (POSIX) or a loopback UDP socket (Windows); the reactor also polls the pool, so a failed wakeup degrades to a short wait instead of a hang.
+- While a job is queued or running, up to four values per job (its promise, and for `fetch` the headers object) are kept in the job's root slots and scanned by the collector.
+- `fetch` runs each request/redirect hop as a job; `fs/promises` runs every file and descriptor operation as a job. Neither blocks timers, sockets or other `await`s.
+- The event loop stays alive while jobs are outstanding (`xt_loop_has_work`), and exits once the pool is idle again.
+
+Known limits of the asynchronous surface (no TLS/streaming `fetch`, inert
+`fs.watch`, four-worker pool) are listed in
+[Runtime deviations](../unimplemented/deviations.md) and the Node pages.

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.