xbintsc 0.5.6 → 0.5.21

package/doc/unimplemented.md

@@ -1,7 +1,7 @@
 # xbintsc Unimplemented Syntax and Features
 
-This document was compiled by checking the source (`src/`, `runtime/`) and tests
-(`tests/`) file by file, and lists the syntax and features that are
+This documentation was compiled by checking the source (`src/`, `runtime/`) and
+tests (`tests/`) file by file, and lists the syntax and features that are
 **currently unimplemented / only partially implemented / semantically different
 from the standard**.
 
@@ -11,278 +11,21 @@ Criteria (ordered by severity):
 2. **Parsed but codegen errors**: the AST / binding can be built, but `codegen` reports `UnsupportedFeature`.
 3. **Parsed and compilable, but semantics are missing or differ**: a binary is produced, but the runtime result does not match ECMAScript / TypeScript semantics.
 
-> Language: **English** | [简体中文](./zh-CN/unimplemented.md)
-
-> Recently completed: **ECMAScript semantics + differential testing** — number
-> formatting / coercion (`toFixed` / `toPrecision` / `toExponential`, hex / octal
-> / binary parsing, full `+` and relational `ToPrimitive`), `JSON.stringify`
-> omission rules, default `Array.prototype.sort` (stable, string order),
-> insertion-ordered integer keys, whole-chain optional chaining, `finally` on
-> early `return` / `break` / `continue`, object-key insertion order, UTF-8-aware
-> `console` inspection with circular references, `Array.prototype.splice`,
-> `String.prototype.match` / `lastIndexOf` / `split` with limit, RegExp capture
-> groups (`exec` / `match` / `replace` / `split` / `search`), immutable array
-> methods (`toReversed` / `toSorted` / `toSpliced` / `with`),
-> `Object.getOwnPropertyNames` / `groupBy`, global URI functions, labeled
-> statements, `#private` fields / methods / statics, tagged templates (with raw
-> strings and `String.raw`), and `import * as ns` for relative modules. The test
-> suite now includes a **differential harness** that runs every case through both
-> xbintsc and Node and compares output byte-for-byte.
-
-> Also completed: `class` declarations / class expressions, `new` / `this`,
-> inheritance `extends` / `super`, `instanceof`, methods / static members /
-> instance fields / getters and setters / constructor parameter properties,
-> `async` / `await` + `Promise`, multi-file `import` / `export` bundling
-> (including `.js` → `.ts` specifier resolution and namespace imports), `Map` /
-> `Set` / `Date` / `RegExp` / `JSON` / `BigInt`, destructuring bindings and
-> parameters, `enum` / `const enum`, and **self-hosting** (the emitted LLVM IR
-> reaches a byte-identical fixpoint).
-
----
-
-## 1. Unimplemented at the statement level
-
-### 1.1 Parsed but codegen reports `UnsupportedFeature`
-
-| Syntax | Status | Notes |
-| --- | --- | --- |
-| `namespace` / `module` declarations | parse ✓, codegen ✗ | → "does not yet support this statement (module declaration)" |
-
-> Labeled statements (`label: statement`, `break label`, `continue label`) are
-> implemented, including labels on non-loop statements.
-
-### 1.2 Not supported by the parser (immediate syntax error)
-
-None known at the statement level. The parser is intentionally permissive and
-accepts most TypeScript statement syntax; unsupported forms are rejected later
-by code generation (see above).
-
----
-
-## 2. Unimplemented at the expression level
-
-### 2.1 Parsed but codegen reports `UnsupportedFeature`
-
-None — generators are implemented.
-
-> Tagged templates are implemented, including raw strings and `String.raw`.
-> Generators (`function*`, `yield`, `yield*`) are implemented with stackful
-> coroutines, including `next`/`throw`/`return`, `for...of`, spread and
-> delegation. `import.meta` exposes `url`, `dirname` and `filename`, resolved
-> from the running executable's path. `async function*` is **rejected with
-> `UnsupportedFeature`** instead of silently producing a synchronous generator.
-
-### 2.2 Not supported by the parser
-
-None known at the expression level.
-
-### 2.3 Unimplemented operators
-
-| Operator | Status | Notes |
-| --- | --- | --- |
-| `new.target` | ✗ | parsed, then rejected with `UnsupportedFeature` (no `new.target` semantics) |
-| `typeof` / `void` / `in` / `delete` / `instanceof` | ✓ | mapped to runtime helpers (`xt_typeof`, `xt_in`, `xt_delete`, `xt_instance_of`) |
-
----
-
-## 3. Unimplemented standard library
-
-### 3.1 Implemented (summary)
-
-- Arrays: `push` `pop` `shift` `unshift` `join` `slice` `splice` `indexOf` `lastIndexOf` `includes` `concat` `reverse` `forEach` `map` `filter` `reduce` `reduceRight` `find` `findIndex` `findLast` `findLastIndex` `some` `every` `sort` `flat` `flatMap` `fill` `copyWithin` `at` `keys` `values` `entries` and the immutable `toReversed` / `toSorted` / `toSpliced` / `with`
-- Strings: `charAt` `charCodeAt` `codePointAt` `indexOf` `lastIndexOf` `includes` `startsWith` `endsWith` `slice` `substring` `substr` `split` `match` `replace` `replaceAll` `search` `toUpperCase` `toLowerCase` `trim` `trimStart` `trimEnd` `padStart` `padEnd` `repeat` `concat` `at` `localeCompare` `valueOf`
-- `Math`: full set of functions and constants
-- `Object.keys` / `values` / `entries` / `assign` / `getOwnPropertyNames` / `groupBy`, object spread `{...obj}`
-- Global functions: `parseInt` `parseFloat` `isNaN` `isFinite` `Number` `String` `Boolean` `encodeURI` `decodeURI` `encodeURIComponent` `decodeURIComponent`
-- `console.log` / `info` / `warn` / `error` / `dir` / `trace` / `assert` / `count` / `group` / `table` / `time`
-
-### 3.2 Completed
-
-- `JSON.parse` / `JSON.stringify`
-- `Date`, `RegExp` (POSIX ERE subset with capture groups), `Map`, `Set`, `Promise`, `BigInt`
-- `Array` statics (`isArray/of/from`), `Object` statics, `Number` statics, `String` statics (`fromCharCode` / `fromCodePoint` / `raw`)
-- Built-in constructors as first-class values (`const A = Array`, `new A(...)`, `A.isArray`, `x instanceof A`) and `Object.prototype` (`hasOwnProperty`, `toString`, `valueOf`, `isPrototypeOf`, `propertyIsEnumerable`, `__proto__`), with `Object.getPrototypeOf({}) === Object.prototype`
-- `Error` family (`Error`, `TypeError`, `RangeError`, `SyntaxError`, `ReferenceError`, `EvalError`, `URIError`, `AggregateError`): `new`, `instanceof`, `extends`, `String(err)` / `err.toString()` and `.stack`
-
-### 3.3 Still unimplemented
-
-| Category | Status |
-| --- | --- |
-| `Symbol` constructor and symbol primitives | ✓ `Symbol(description)`, well-known symbols, `Symbol.for` / `Symbol.keyFor`, symbol property keys and `Object.getOwnPropertySymbols` |
-| `String.prototype.normalize` | ✗ not implemented |
-| `structuredClone` | ✗ not implemented |
-| Built-in error subclasses (`TypeError`, `RangeError`, …) | ✓ first-class constructors and prototypes; `instanceof Error` holds for the whole family |
-| `AggregateError` constructor | ✓ `new AggregateError(errors, message)`; `Promise.any` now rejects with one |
-| Iterator protocol / `Symbol.iterator` / custom `for...of` iterables | ✓ arrays, strings, `Map`, `Set`, generators and any object exposing `[Symbol.iterator]()` are iterable in `for...of` / spread |
-| Generators (`function*`, `yield`, `yield*`, `next`/`throw`/`return`) | ✓ implemented with stackful coroutines; `for...of`, spread and delegation supported. `return()` completes without running `finally` |
-| Timers | ✓ `setTimeout` / `clearTimeout` / `setInterval` / `clearInterval` on the core event loop (numeric ids, no `Timeout` object; no `setImmediate` / `queueMicrotask`). A promise settled from a timer can be awaited: the async body suspends on the pending promise and resumes when the timer fires |
-| I/O / process and other host APIs | only via extensions (e.g. Node `fs`) |
-
-### 3.4 Typed arrays
-
-Implemented: `Uint8Array`, `Int8Array`, `Uint8ClampedArray`, `Uint16Array`,
-`Int16Array`, `Uint32Array`, `Int32Array`, `Float32Array`, `Float64Array` with
-`new X(n)` / `new X(arrayLike)`, `X.from` / `X.of`, `BYTES_PER_ELEMENT`, coerced
-element writes, and `fill` / `set` / `slice` / `subarray` / `join` / `toString` /
-`indexOf` / `lastIndexOf` / `includes` / `forEach` / `map` / `filter` / `every` /
-`some` / `find` / `findIndex` / `reduce` / `reverse` / `sort` / `copyWithin` /
-`at` / `keys` / `values` / `entries`. Known divergences:
-
-| Feature | Status |
-| --- | --- |
-| `subarray` | ~ returns a copy, not a view over a shared buffer |
-| `keys` / `values` / `entries` | ~ return arrays, not iterator objects |
-| `ArrayBuffer` / `DataView` / `.buffer` / `.byteOffset` semantics | ✗ no backing buffer type; `.byteOffset` is always 0 |
-| `BigInt64Array` / `BigUint64Array` | ✗ not implemented |
-| `instanceof` built-in constructors | ✓ `instanceof Array` / `Object` / `Map` / `Set` / `Date` / `RegExp` / `Promise` / `Error` family / typed arrays are recognised by name **and through a first-class constructor value** (`const A = Array; x instanceof A`); constructors can be stored, passed, aliased, called and used with `new` |
-| Typed-array views over a `Buffer` / `ArrayBuffer` | ✗ constructors copy from a length / array-like / typed array only |
-
----
+The pages are split by area so a limitation for one feature is recorded in one
+small file. When a limitation is lifted, move the entry to the matching page
+under [implemented](./implemented.md); git history records when it changed.
 
-## 4. Module system
-
-| Feature | Status |
-| --- | --- |
-| Multi-file / module resolution and linking | ✓ driver-layer AST bundling (`src/driver/modules.ts`): parse each module, rename top-level symbols by module prefix, rewrite references, merge into one file and rebind |
-| Named import/export | ✓ `import { a, b as c }` / `export { a as b }` / `export const/let/var/function/class` |
-| Default import/export | ✓ `export default` / `import d from` |
-| Re-export `export { x } from` / `export * from` | ✓ (`export *` copies the dependency's exports) |
-| Namespace import `import * as ns` | ✓ lowered to a synthetic object literal holding every export |
-| Circular dependencies | ✗ errors out (no circular initialization semantics) |
-| Live bindings | ✗ namespace objects and imported bindings are snapshots at module-evaluation time |
-| ESM `node_modules` packages | ✓ bare specifiers resolve up the tree through `exports` / `module` / `main`, including scoped packages and subpaths; the package sources are bundled like relative modules |
-| CommonJS `require` / `module.exports` | ✓ inside `node_modules` only: the bundler gives each CommonJS package a synthetic `module` / `exports` pair, lowers `require("x")` to the bundled dependency's exports, and hoists external/built-in `require`s into ESM imports. `require()` in user code (outside `node_modules`) is still rejected with a diagnostic pointing at the ESM `import` form. |
-
-> Extension modules (such as `fs`) are importable by bare or `node:`-prefixed
-> specifier — `import { readFileSync } from "fs"` / `import path from "path"` —
-> and resolve to their runtime entries (named, default and namespace forms).
-> Relative modules and ESM packages under `node_modules` are bundled at the driver layer.
-
----
-
-## 5. Unimplemented function features (or missing semantics)
-
-| Feature | Parse | Semantics |
-| --- | --- | --- |
-| Default parameters `function f(a = 5)` | ✓ | ✓ implemented |
-| Rest parameters `function f(...args)` | ✓ | ✓ implemented |
-| Spread in call arguments `f(...args)` | ✓ | ✓ implemented |
-| Destructuring parameters / bindings | ✓ | ✓ implemented |
-| `arguments` object | ✓ (implicit) | ✓ implemented (arrow functions get their own parameters, not the outer function's `arguments`, unlike JS) |
-| `this` binding / method call semantics | ✓ | ✓ implemented (`this` is threaded as the first ABI parameter; arrow functions inherit lexically) |
-| `async` / `await` / Promise | ✓ | ✓ implemented with stackful-coroutine suspension: awaiting a pending promise pauses the body and the event loop resumes it (see the deviations table for the remaining differences) |
-| `new.target` | ✗ | parsed, then rejected with `UnsupportedFeature` (no `new.target` semantics) |
-| Generators / iterators / `yield` | ✓ implemented | `function*`, `yield`, `yield*`, `.next/.throw/.return`; `async` generators are rejected with `UnsupportedFeature` |
-| Closure `arity` | — | `xt_closure_arity` is always -1, never filled in |
-| `fn.call` / `fn.apply` / `fn.bind` | ✓ | ✓ implemented (the bound closure does not track partial-argument `length`) |
-| `fn.name` / `fn.length` | ✓ | ✓ implemented (inferred from the declaration / assignment / property key; bound functions use `"bound ..."` and adjusted arity) |
-| First-class built-in constructors (`const A = Array`, `new A(...)`, `typeof Map`) | ✓ | ✓ constructors are ordinary function values with `name`/`length`, a `prototype`, their statics (`A.isArray`) and the full `instanceof` protocol |
-| First-class built-in methods (`typeof arr.map`, `const f = arr.push`, `obj.method?.()`) | ✓ | ✓ implemented as *unbound* method values: reading `arr.map` yields a function, `arr.map?.(cb)` and `obj.method?.()` bind the receiver as `this`, and a detached call (`const f = arr.map; f(cb)`) throws exactly like JavaScript. Method `name`/`length` are exposed |
-| `fn.toString()` | ~ | returns a native-style placeholder (`function name() { [native code] }`) instead of the original source text |
-
----
-
-## 6. Classes and object orientation
-
-| Feature | Status |
-| --- | --- |
-| `class` declarations / class expressions | ✓ implemented |
-| `constructor` | ✓ |
-| Instance fields / property declarations | ✓ |
-| Methods | ✓ |
-| `static` fields / methods | ✓ |
-| Inheritance `extends` / `super` | ✓ (single level correct; `super` takes the prototype of `this`'s prototype — see section 8) |
-| Prototype chain / method lookup | ✓ |
-| `instanceof` | ✓ |
-| `new` / instantiation | ✓ |
-| `get` / `set` accessors | ✓ implemented |
-| Parameter properties `constructor(public x: T)` | ✓ implemented |
-| Private fields `#x` | ✓ implemented (stored under a literal `#x` key; no accessibility enforcement) |
-| `enum` / `const enum` | ✓ implemented (forward + reverse mapping) |
-| `private` / `protected` / `public` / `readonly` modifiers | ✗ no access control (erased) |
-| `abstract` / `implements` | ✗ (erased) |
-| Parent/child `#x` name collisions | ✗ may alias (same literal key) |
-
----
-
-## 7. Unimplemented type system (parsed only, not checked)
-
-Type syntax is parsed into the AST and then **erased entirely** during binding /
-code generation; no type checking is performed:
-
-- Type annotations, return types, type parameters, type aliases, interfaces, generic constraints, etc.: parse ✓, check ✗.
-- Checker diagnostic codes (`TypeMismatch` `NotCallable` `PropertyNotFound` `ArgumentCountMismatch`) are defined but **unused**.
-- `as` / `satisfies` / non-null assertion `!`: erased directly, no assertion semantics.
-- Generics: no runtime instantiation; type parameters are ignored.
-- Optional chaining `?.` type narrowing: none (runtime short-circuit is implemented, but there is no type-level narrowing).
-
----
-
-## 8. Runtime / semantics differing from the standard (known deviations)
-
-These features **compile and run**, but the result does not fully match ECMAScript:
-
-| Item | Deviation |
-| --- | --- |
-| RegExp byte-oriented matching | The engine matches UTF-8 bytes: literal multi-byte text works, but `.` and character classes consume one byte per repetition (`\d` / `\w` stay ASCII). Offsets returned by `exec` / `search` / replacement callbacks are converted to UTF-16 code units |
-| Global RegExp `lastIndex` | `test` / `exec` do not advance or honour a caller-set `lastIndex` for `/g` / `/y` regexes |
-| String `normalize` / `structuredClone` | Not implemented |
-| First-class built-in methods | Implemented as unbound method values (see section 5); `fn.toString()` returns a placeholder rather than source text |
-| `for...in` | Enumerates own keys of objects / arrays / strings; does not include prototype-chain properties |
-| Array out-of-bounds / sparse | Out-of-bounds access returns `undefined`; assigning `arr.length` truncates / extends, but sparse holes are not tracked distinctly |
-| Memory management | Non-moving mark-sweep collector behind `xt_alloc`: explicit roots, subsystem root providers and a conservative C-stack scan. Single-threaded and stop-the-world; no moving/compaction or generational mode |
-| Function `arity` / argument count | No argument count validation; `fn.length` reports the declared arity but calls are never checked against it |
-| `async` / `await` | Real suspension on a stackful coroutine, but `await` on a value that is **already settled** continues synchronously instead of queueing a microtask as the specification requires, so interleaving with pending `.then` callbacks can differ. Top-level `await` blocks on the event loop rather than yielding the module body. `fs/promises` still performs the I/O synchronously before settling; `fetch` is blocking; `async` generators are unsupported |
-| `super` | `super.x` / `super(...)` takes the prototype of `this`'s prototype; single-level inheritance is correct, but depth > 1 may be inaccurate |
-| `Error.stack` | Function-level frames only: each frame is `at name (file:line)` with the function's declaration line (updated to the construction line for the innermost frame); no column numbers and no frames for generator / `async` bodies (they switch stacks) |
-| Module live bindings | Namespace imports and imported bindings are snapshots (see section 4) |
-| `import.meta` | ✓ `import.meta.url` / `.dirname` / `.filename`, resolved from the executable path |
-
-> Number formatting, loose equality, `+` / relational `ToPrimitive`, whole-chain
-> optional chaining, `finally` on early exit and object-key ordering have all
-> been brought in line with Node and are covered by the differential tests, so
-> they are no longer listed as deviations.
-
----
-
-## 9. Unimplemented toolchain / platform / engineering
-
-| Item | Status |
-| --- | --- |
-| GC (garbage collection) | ✓ non-moving mark-sweep in `xt_alloc.c`, armed by a live-heap threshold (`XT_GC_THRESHOLD` pins it) or `xt_gc_collect()`; after each collection the threshold becomes twice the surviving heap (floor 1 MiB), so the resident set follows the live set instead of only growing. `XT_GC_TRACE=1` prints one line per collection to stderr. Explicit roots + root providers + conservative active-stack scan. No compaction, weak references or background collection — without weak references an extension must keep a strong reference to every value it caches (the GUI's element handles do) |
-| Self-hosting | ✓ the compiler compiles itself: `xbintsc build src/cli/main.ts` produces a working binary, and the emitted IR is stable from generation 1 onward. The runtime is still C |
-| Type checker | ✗ only diagnostic codes are defined; no checker |
-| Full standard library | partial: Math / JSON / Date / Map / Set / RegExp / `Error` / `BigInt` / `Symbol` implemented; String.normalize / structuredClone missing |
-| Multi-file module bundling | partial: relative-path `.ts` bundling, ESM `node_modules` packages, namespace imports and bare-specifier extension module imports implemented; circular dependencies / CommonJS / live bindings not implemented |
-| Real async runtime | ✓ `async`/`await` suspends on pending promises on the `select(2)` reactor: timers, TCP sockets and promise callbacks resume the coroutine. Still missing: truly asynchronous I/O scheduling (`fs/promises` blocks before settling), a non-blocking `fetch` and worker threads (workers are child processes) |
-| Windows binary artifact verification | adapted at the build layer (`.exe` suffix, link flag branch), verified in CI |
-| Precise ECMAScript number / string / comparison semantics | partial, see section 8 |
-
----
-
-## 10. Quick reference: unimplemented / partially implemented list
-
-```
-Unimplemented (statements): namespace/module declarations
-
-Unimplemented (expressions): new.target (clear UnsupportedFeature)
-
-Unimplemented (functions): `fn.toString()` source text, async generators (rejected)
-
-Unimplemented (classes/OO): abstract/implements, access control,
-                            parent/child #x collision
-
-Unimplemented (standard library): String.normalize, structuredClone
-
-Unimplemented (modules): circular dependencies, live bindings, dynamic
-                           `require(expr)`, `require.resolve` / `require.cache`,
-                           `__dirname` / `__filename`
-
-Unimplemented (type system): type checking, generic instantiation, assertion
-                             semantics, optional-chaining narrowing
-
-Unimplemented (runtime): asynchronous I/O scheduling,
-                         global-regex lastIndex
+> Language: **English** | [简体中文](./zh-CN/unimplemented.md)
 
-Unimplemented (engineering): type checker
-```
+## Contents
+
+- [Statements](./unimplemented/statements.md) — statement forms that do not lower
+- [Expressions and operators](./unimplemented/expressions.md) — expression forms and operators that do not lower
+- [Standard library](./unimplemented/stdlib.md) — what the built-in objects are still missing, including typed arrays
+- [Module system](./unimplemented/modules.md) — circular dependencies, live bindings, CommonJS boundaries
+- [Functions](./unimplemented/functions.md) — missing function semantics
+- [Classes and OO](./unimplemented/classes.md) — access control, `abstract`/`implements`, private-name collisions
+- [Type system](./unimplemented/types.md) — parsed but never checked
+- [Runtime deviations](./unimplemented/deviations.md) — compiles and runs, but differs from ECMAScript
+- [Toolchain and platform](./unimplemented/toolchain.md) — type checker, async I/O, GC modes, platform gaps
+- [Node extension](./unimplemented/node.md) — Node module gaps, one page per area

package/doc/xbintsc.config.schema.json

@@ -26,6 +26,18 @@
       "description": "Optimization level (default: 2).",
       "enum": ["0", "1", "2", "3"]
     },
+    "lto": {
+      "type": "boolean",
+      "description": "Compile program and runtime to LTO bitcode and link with lld."
+    },
+    "pgo": {
+      "enum": ["generate", "use"],
+      "description": "Profile-guided optimization stage."
+    },
+    "pgoDir": {
+      "type": "string",
+      "description": "Profile directory for pgo (default: <outDir>/pgo)."
+    },
     "extensions": {
       "type": "array",
       "items": { "type": "string" },

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

@@ -64,6 +64,7 @@ win.documentTree()                     // 序列化的 DOM（调试用）
 win.layoutTree()                       // 序列化的布局盒（调试用）
 win.paintCount()                       // 显示列表中图形的数量
 win.paintList()                        // 序列化的显示列表（调试用）
+win.inlineSvg(selector)                // 序列化的内联 <svg>：{ markup, width, height, shapes }
 win.measureText(text, fontSize?, family?)  // 整形后的推进宽度（像素）
 win.fontMetrics(fontSize?, family?)    // { ascent, descent, lineHeight, ready }
 win.hitTest(x, y)                      // 最深的元素描述符，或 ""
@@ -72,6 +73,12 @@ win.advance(ms)                        // 推进 CSS transition 时钟（测试
 win.stats()                            // 引擎/运行时计数器（内存排查用）
 ```
 
+`win.inlineSvg(selector)` 返回引擎为第一个匹配 `selector` 的 `<svg>` 元素构建的
+独立 SVG 文档（`markup`），以及 NanoSVG 从它解析出的固有尺寸与图形数量；没有
+匹配或元素不是 `<svg>` 时返回 `undefined`。它让序列化器的规范大小写
+（`viewBox`、`linearGradient`、`gradientUnits` 等）无需 GPU 即可测试——HTML
+解析器会把它们全部小写化。
+
 `win.stats()` 返回 `{ heapBytes, heapAllocations, treeNodes, detachedRoots,`
 `detachedNodes, handles, handleSlots, listeners }`：运行时存活堆、DOM 树规模、
 分离节点池（detached pool）以及元素句柄表。稳定状态下它们都应保持常量——若

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

@@ -19,10 +19,17 @@
 - `src/extensions/gui/index.ts` 通过 `nativeObjects()` 暴露该归档（经由
   `findRuntimeLibrary`，因此 `.a`/`.lib` 都可用），并通过 `linkerFlags()`
   暴露操作系统框架。
+- `scripts/build-gui.ts` 使用与驱动**相同**的 clang
+  （`src/driver/toolchain-provider.ts`）；Windows 上就是 Visual Studio 自带的、
+  面向 MSVC 的 LLVM，并配套使用其同目录下的 `clang++`/`llvm-ar` 来配置 CMake、
+  编译引擎和合并归档。脚本不提供 `gcc`/`g++` 回退，Windows 上也始终使用
+  `llvm-ar`，因此归档不会混入其他目标文件格式或 C++ 运行时。Visual Studio
+  工具链按绝对路径查找，无需开发者命令提示符。Windows 上 SDL_GPU 会选择 Vulkan
+  后端，不需要 DXIL/`dxc` 工具链。
 - CI 在组装发布归档之前构建 `gui.a`，因此它会随 `runtime/lib/<slug>/` 一起
   发布（发布 tarball 会复制整个 `runtime/` 树）。归档在 Linux（Xvfb 下，
   使用 lavapipe 软件 Vulkan 驱动）与 macOS 上构建并运行示例；Windows 为
-  试验性。
+  试验性，因为托管 runner 没有 GPU/Vulkan 驱动。
 - 现有的缓存指纹已经会对 `nativeObjects()` 的内容做哈希，因此重建 `gui.a`
   会自动使缓存二进制失效。
 - CMake 构建树位于其源码**旁边**（`vendor/sdl-build`、`vendor/freetype-build`、
@@ -55,8 +62,9 @@ xbintsc run examples/gui/hello.ts --ext gui
 `volume` 驱动播放。媒体 `src` 相对于进程工作目录解析，因此从仓库根目录运行：
 `xbintsc run examples/gui/media.ts --ext gui`。几何报告见该目录的 README。
 
-这些测试套件在 Windows 上默认跳过（该平台会构建归档，但 CI 未验证运行）。
-如果本机有 `gui.lib` 与可用的 GPU，可用 `xbintsc_GUI_TESTS=1` 选择启用：
+这些测试套件在 Windows 上默认跳过（归档可以在本机通过 Vulkan 运行，但 CI
+runner 没有可用的 GPU 驱动）。如果本机有 `gui.lib` 与可用的 GPU，可用
+`xbintsc_GUI_TESTS=1` 选择启用：
 
 ```bat
 set xbintsc_GUI_TESTS=1

package/doc/zh-CN/gui/known-issues.md

@@ -23,13 +23,14 @@
   `tests/e2e/gui-example-browser.test.ts` 中。
 - **`display: none -> flex` 的重排。** 通过类名切换让隐藏元素显示在 flex 容器上时，也曾观察
   到同样的崩溃；`examples/gui/pelican-bike` 改用 `opacity` 显示游戏结束遮罩。
-- **SVG：** 支持 SVG *文件*，经图像加载器处理（`<img src="logo.svg">`）：
-  `runtime/ext_gui/svg.cpp` 封装 vendored **NanoSVG** 解析/光栅化器，
-  `image.{h,cpp}` 把 SVG 视为矢量图像并按绘制像素尺寸光栅化。文档中的内联
-  `<svg>` **子树**仍不支持：HTML 解析器只认识元素与属性，布局只认识盒子，
-  绘制只认识矩形/文本/图像；`<svg>` 子树需要另一套几何与绘制路径。因此矢量
-  美术要么以 SVG/PNG 文件形式提供，要么像 `examples/gui/pelican-bike` 那样用
-  盒子绘制。
+- **SVG 是 NanoSVG 的子集。** SVG *文件*（`<img src="logo.svg">`）与内联
+  `<svg>` 子树共用 vendored 的 NanoSVG 解析/光栅化器（`runtime/ext_gui/svg.cpp`、
+  `inline_svg.cpp`），它会渲染 `path`/`rect`/`circle`/`ellipse`/`line`/
+  `polyline`/`polygon`、组、`defs` 渐变以及基于 `class` 的 `<style>` 规则。
+  `<text>`、`<use>`、滤镜、遮罩与裁剪路径不会渲染，文档层叠的 CSS 也不会进入
+  图像内部（这里的 `fill`/`stroke` 是 SVG 表现属性，不是 CSS 属性）。需要这些
+  能力的矢量美术必须预先光栅化、用盒子绘制，或限制在受支持的语法内。参见
+  [媒体](./media.md#图像m6a)。
 
 ## 待决问题
 
@@ -43,12 +44,16 @@
   for 'RuntimeLibrary'`，外加满屏 `LNK2005: already defined`，最终表现为
   `clang: linker command failed with exit code 1169`。现在
   `src/extensions/gui/index.ts` 只列系统库（`user32`、`gdi32`、`d3d12` 等）。
-  Windows 链接也是唯一需要 MSVC 环境的环节，请在 x64 Native Tools 命令行里构建。
+  Windows 链接不再需要手动准备 MSVC 环境：`scripts/build-gui.ts` 会解析与驱动
+  相同的、面向 MSVC 的 clang（`PATH` 上没有更新版本时就是 Visual Studio 自带的
+  LLVM）。
 - Windows：`scripts/build-gui.ts` 会生成 MSVC 兼容的 `gui.lib`
   （COFF 对象 + `ar -M`/`llvm-ar`），但尚未在 CI 中验证，因此 Windows 步骤
   为试验性（job 保持绿色），`package` 会跳过它；在开发者机器上构建并运行
-  `examples/gui/pelican-svg` 与 `examples/gui/pelican-bike` 是可以的。它还需要
-  一个带 D3D12/DXIL 后端的 SDL3 构建（DXIL 需要 `dxc`）。
+  `examples/gui/pelican-svg` 与 `examples/gui/pelican-bike` 是可以的。那里
+  SDL_GPU 会选择 **Vulkan** 后端（`win.driver()` 返回 `"vulkan"`），因此归档
+  不需要 DXIL/`dxc` 工具链；托管 Windows runner 没有 GPU/Vulkan 驱动，这才是
+  CI 运行仍为试验性的原因。
 - **Windows 上的媒体：** 媒体解码器（FFmpeg）只构建并合并进 POSIX 的
   `gui.a`；Windows 的 `gui.lib` 不含它们，因此那里的 `<video>`/`<audio>` 为空
   操作（失败会触发 `error`）。启用它需要 MSVC 兼容的 FFmpeg 构建，推迟到
@@ -57,4 +62,5 @@
 - **D3D12 着色器：** SPIR-V（Vulkan）与 DXIL（Direct3D 12）二进制块均已构建并
   内嵌，非 Metal 路径不再跳过几何绘制。但在 **SDL 3.2.10** 上 DXIL 仍不可用：
   其 D3D12 后端会拒绝任何着色器中声明了 uniform buffer 的图形管线，而引擎正是
-  用这种方式传视口。SDL 升级后需重新确认。
+  用这种方式传视口。Windows 实际会选择 Vulkan，因此不受影响；若将来强制走
+  D3D12，需在 SDL 升级后重新确认。

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

@@ -12,7 +12,8 @@ PNG/JPEG/BMP/GIF/TGA 解码为 RGBA8，并带有解码缓存与仅头文件的
 `runtime/ext_gui/svg.{h,cpp}` 在其上增加 SVG：它封装 vendored **NanoSVG**
 库（解析 + 抗锯齿扫描线光栅化），按扩展名或内容识别 SVG，并产出与既有管线
 相同的 RGBA8 `Image`。`stb_image` 无法解码 SVG，这正是
-`<img src="logo.svg">` 能工作的原因。
+`<img src="logo.svg">` 能工作的原因。内联 `<svg>` 子树会先被序列化成一个
+独立文档（`inline_svg.{h,cpp}`），再交给同一个解析器。
 
 - `<img>` 是一个替换元素（`display: inline-block`）：设置了 CSS 尺寸时布局
   采用该尺寸，否则采用固有像素尺寸；当只约束一个轴时保持宽高比。构建盒树时
@@ -23,11 +24,34 @@ PNG/JPEG/BMP/GIF/TGA 解码为 RGBA8，并带有解码缓存与仅头文件的
   **位图**按固有分辨率解码并按路径缓存；**矢量图**（SVG）按设备像素下的绘制
   尺寸（逻辑尺寸 × 窗口像素密度）光栅化并保持 viewBox 宽高比，再按该尺寸缓存，
   因此缩放或 HiDPI 得到的是清晰渲染而非放大的位图。
+- **内联** `<svg>` 元素与 `<img>` 一样是替换元素，但它的来源就是 DOM 子树
+  本身。`runtime/ext_gui/inline_svg.{h,cpp}` 把该子树序列化回独立 SVG 文档，
+  还原 HTML 解析器会小写掉的、NanoSVG 又按大小写精确匹配的拼写（`viewBox`、
+  `preserveAspectRatio`、`linearGradient`、`gradientUnits` 等）。布局先取
+  `width`/`height` 属性、其次 `viewBox`、最后 300x150 作为固有尺寸；绘制把
+  markup 挂在图像 op 上，渲染器按绘制设备像素尺寸，通过与 SVG 文件相同的
+  NanoSVG 缓存解析并光栅化。DOM 变更会在下一次布局时重新序列化（因此
+  `setAttribute` 与 `innerHTML` 都会重绘图像），markup 缓存有界
+  （最近最少使用），动画文档不会让它无限增长。
 - 解析结果按路径缓存；解析与光栅化器状态在 `xt_svg_shutdown`
   （`xt_image_shutdown`）中释放。
 
+文档 CSS 只作用于 `<svg>` **盒子**——尺寸、外边距、背景、边框、`transform`、
+opacity、`display`——与任何其他元素一样。盒子内部的艺术内容保持 SVG 语义：
+表现属性与 SVG `<style>` 中基于 `class` 的规则由 NanoSVG 读取，而不是 HTML
+层叠，所以这里的 `fill`/`stroke` 不是 CSS 属性。对布局、绘制、命中测试与事件
+而言整个 `<svg>` 就是一个替换盒：其子元素没有 DOM 盒，因此点击的 `e.target`
+是 `<svg>` 元素而不是某个 `<rect>`。渲染器按 markup 与尺寸缓存纹理，所以每帧
+重写艺术内容的程序会为每个变体保留一张纹理；更好的做法是用 `transform`、
+`opacity` 给盒子做动画，或在一小组文档之间切换。
+
 图像仍需完成：CSS `background-image: url(...)`、`data:` URI、`object-fit`、
-九宫格边框与内联 `<svg>` 元素（仅支持 SVG *文件*，参见[待决问题](./known-issues.md)）。
+九宫格边框。
+
+两种 SVG 都受限于 NanoSVG 的子集：`path`、`rect`、`circle`、`ellipse`、
+`line`、`polyline`、`polygon`、组（`g`）、带线性/径向渐变的 `defs` 以及基于
+`class` 的 `<style>` 规则会被光栅化；`<text>`、`<use>`、滤镜、遮罩与裁剪路径
+不会渲染（见[已知问题](./known-issues.md)）。
 
 ## 视频与音频（M13）
 

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

@@ -37,7 +37,8 @@
   各自的描述性名称。
   需注意：SDL 3.2.10 的 Direct3D 12 后端无法创建着色器中声明了 uniform buffer 的
   图形管线（返回 `E_INVALIDARG`）；引擎正是用这种方式传视口，因此 DXIL 这条路已
-  构建但在上游修复前不可用。
+  构建但在上游修复前不可用。Windows 不受影响：SDL_GPU 在那里会选择 Vulkan 后端
+  （由 `win.driver()` 确认），使用 SPIR-V 二进制块。
 - 图形片元着色器中的**圆角矩形距离场**提供抗锯齿填充；顶点携带
   `position`、`local`、`half extents`、`radius` 与颜色，一个视口尺寸的
   push constant 负责投影。启用 alpha 混合。

package/doc/zh-CN/gui.md

@@ -2,7 +2,7 @@
 
 > 语言 / Language：[English](../gui.md) | **简体中文**
 
-状态：**M15** —— 功能（M1–M14）已全部完成：HTML 解析、CSS 选择器匹配、层叠（cascade）、计算样式与布局（块级、行内、Flexbox 与 CSS 定位）均已就位，引擎还会**绘制**：它构建一个由矩形、图像与排版后的文本 run 组成的显示列表，并通过 SDL_GPU 渲染。输入事件会经过命中测试并投递给原生 TS 处理器，`:hover`/`:focus` 会被动态匹配，`<img>` 依据其固有尺寸确定大小并从纹理绘制——位图（PNG/JPEG/…）与 SVG 文件皆可，后者按绘制尺寸光栅化，因此矢量图保持清晰——CSS transition 会为绘制属性做动画。**M8** 增加了交互式 DOM：具有稳定标识的元素句柄、变更操作（`appendChild`、`textContent`、`classList`、`style` 等）以及支持捕获/冒泡的元素级事件。**M9** 会提前编译 `<script>` 主体（内联与 `<script src>`）——参见 `gui-scripts.md`。**M10** 增加 `requestAnimationFrame` 以及若干 DOM 辅助方法。**M11** 增加 `position: relative`/`absolute`/`fixed` 及其偏移，`examples/gui/pelican-bike`（一个可玩的 2D 游戏）就构建在它之上。**M12** 明确了 DOM 节点生命周期（哪些变更释放、哪些保留），并让引擎内存有界：参见[节点生命周期](./gui/dom.md)与[内存与 GC](./gui/runtime.md)。**M13** 真正播放
+状态：**M16** —— 功能（M1–M15）已全部完成：HTML 解析、CSS 选择器匹配、层叠（cascade）、计算样式与布局（块级、行内、Flexbox 与 CSS 定位）均已就位，引擎还会**绘制**：它构建一个由矩形、图像与排版后的文本 run 组成的显示列表，并通过 SDL_GPU 渲染。输入事件会经过命中测试并投递给原生 TS 处理器，`:hover`/`:focus` 会被动态匹配，`<img>` 依据其固有尺寸确定大小并从纹理绘制——位图（PNG/JPEG/…）与 SVG 文件皆可，后者按绘制尺寸光栅化，因此矢量图保持清晰——CSS transition 会为绘制属性做动画。**M16** 让内联 `<svg>` 子树获得同样的处理：子树被序列化回 SVG 文档，并按绘制设备尺寸光栅化，因此图标不再需要单独的文件。**M8** 增加了交互式 DOM：具有稳定标识的元素句柄、变更操作（`appendChild`、`textContent`、`classList`、`style` 等）以及支持捕获/冒泡的元素级事件。**M9** 会提前编译 `<script>` 主体（内联与 `<script src>`）——参见 `gui-scripts.md`。**M10** 增加 `requestAnimationFrame` 以及若干 DOM 辅助方法。**M11** 增加 `position: relative`/`absolute`/`fixed` 及其偏移，`examples/gui/pelican-bike`（一个可玩的 2D 游戏）就构建在它之上。**M12** 明确了 DOM 节点生命周期（哪些变更释放、哪些保留），并让引擎内存有界：参见[节点生命周期](./gui/dom.md)与[内存与 GC](./gui/runtime.md)。**M13** 真正播放
 `<video>`/`<audio>`——一个 vendored 的最小 FFmpeg 在主线程解码，视频帧走图像
 纹理路径、音频进入 SDL 流，DOM 媒体 API 暴露 `play`/`pause`/`currentTime`/…
 与媒体事件。**M14** 增加了 `<canvas>`，配一个自研的 2D 软件光栅器（抗锯齿
@@ -143,8 +143,9 @@ FFmpeg `7.1`（可用 `SDL3_TAG` / `FREETYPE_VERSION` / `HARFBUZZ_VERSION` /
      一起发布（`package-release` 复制整个 `runtime/`）。
    - `vendor/`（SDL3/FreeType/HarfBuzz，缓慢的部分）按 OS/arch 缓存，以
      `scripts/build-gui.ts` 为键。
-   - Windows（构建 + 运行）保持试验性，直到验证 MSVC 兼容的 `gui.lib` 与
-     D3D12/DXIL 着色器路径；失败只记录日志而不标注运行（见[待决问题](./gui/known-issues.md)）。
+   - Windows（构建 + 运行）在 CI 中保持试验性：MSVC 兼容的 `gui.lib` 可在本机
+     通过 SDL_GPU 的 Vulkan 后端构建并运行，但托管 runner 没有 GPU/Vulkan
+     驱动。失败只记录日志而不标注运行（见[待决问题](./gui/known-issues.md)）。
 8. **M8 — 交互式 DOM** ✅
    - 具有稳定标识的元素/文档句柄、通过运行时访问器读写属性、遍历/特性/查询、
      带有延迟重算样式/重新布局的变更
@@ -211,6 +212,16 @@ FFmpeg `7.1`（可用 `SDL3_TAG` / `FREETYPE_VERSION` / `HARFBUZZ_VERSION` /
       [布局](./gui/layout.md#变换m15)与[动画](./gui/animation.md#css-transformm15)；
       e2e 见 `tests/e2e/gui-transform.test.ts` 与
       `tests/e2e/gui-example-svg.test.ts`。
+16. **M16 — 内联 `<svg>`** ✅
+    - `<svg>` 是替换元素（`layout.*`）：固有尺寸先取 `width`/`height` 属性，
+      其次 `viewBox`，最后 300x150；常规盒树遍历不再进入其子元素。
+    - `inline_svg.{h,cpp}` 把子树序列化为独立 SVG 文档，并还原 HTML 解析器
+      小写掉的、区分大小写的名称（`viewBox`、`preserveAspectRatio`、
+      `linearGradient`、`gradientUnits` 等）。
+    - 绘制把 markup 挂在图像 op 上（`PaintImage::svg`），渲染器按绘制设备尺寸、
+      通过与 SVG 文件相同的 NanoSVG 缓存（`svg.{h,cpp}`）解析并光栅化；markup
+      缓存有界，DOM 变更会在下一次布局时重新序列化。e2e 见
+      `tests/e2e/gui-inline-svg.test.ts`。
 
 ## 进度日志
 
@@ -298,4 +309,11 @@ FFmpeg `7.1`（可用 `SDL3_TAG` / `FREETYPE_VERSION` / `HARFBUZZ_VERSION` /
   `getBoundingClientRect` 返回变换后的包围盒。`examples/gui/pelican-svg` 用它
   为自己的画做动画；e2e 见 `tests/e2e/gui-transform.test.ts` 与
   `tests/e2e/gui-example-svg.test.ts`。
+- **M16** ✅ 内联 `<svg>`。`buildBoxTree` 把 `<svg>` 元素当作替换盒（固有尺寸
+  依次取 `width`/`height`、`viewBox`、300x150）并停止下探，
+  `inline_svg.{h,cpp}` 以规范 SVG 大小写序列化子树，绘制把 markup 放进
+  `PaintImage::svg`，`renderer_image.cpp` 通过 NanoSVG 缓存（`svg.{h,cpp}`，
+  markup 采用有界 LRU）按绘制设备像素尺寸光栅化。`win.inlineSvg` 诊断钩子
+  暴露序列化文档，`tests/e2e/gui-inline-svg.test.ts` 固定了尺寸、命中测试、
+  渐变、CSS 盒样式与 DOM 变更。
 

package/doc/zh-CN/icon.md

@@ -148,7 +148,8 @@ const unsigned int       xt_app_icon_height;
 
 - `src/cli/main.ts`：新增 `--icon`、`--bundle`、`--app-name`、`--app-id`、
   `--config`、`--no-config`，并与配置合并（`mergeAppConfig`）。
-- `src/driver/compiler.ts`：`BuildOptions.icon` 与 `BuildOptions.app`。
+- `src/driver/options.ts`：`BuildOptions.icon` 与 `BuildOptions.app`（由
+  `src/driver/build-key.ts` 计入缓存键）。
   - 图标的**内容哈希**与打包选项计入可执行文件 `cacheKey`，图标变化即重建。
   - 图标对象以及（win32 上）资源对象追加到链接输入。
   - 链接后生成 macOS `.app` bundle；`BuildResult.bundlePath` 返回其路径
@@ -161,8 +162,8 @@ const unsigned int       xt_app_icon_height;
 1. PNG 输入被包进最小 ICO 容器（`ICONDIR` + 指向 PNG 载荷的 `ICONDIRENTRY`）；
    Vista+ 接受 PNG-in-ICO。
 2. 在缓存中写入 `.rc`（`1 ICON "icon-<hash>.ico"`）。
-3. 优先 `llvm-rc /fo app.res app.rc`（解析出的 clang 同目录或 `PATH`），
-   否则 MinGW `windres app.rc -O coff -o app_res.o`。可用 `xbintsc_RC` 覆盖。
+3. 运行 `llvm-rc /fo app.res app.rc`（解析出的 clang 同目录或 `PATH`）。
+   `llvm-rc` 用 `/?` 探测（它没有 `--version`）。可用 `xbintsc_RC` 覆盖。
 4. 找不到资源编译器时继续构建（仅运行时图标），装饰性功能绝不导致构建硬失败。
 
 #### macOS（`MyApp.app` bundle）—— `src/driver/mac-bundle.ts`
@@ -213,7 +214,7 @@ Wayland。
 
 - `tests/driver/config.test.ts` —— 解析/校验、发现、路径解析。
 - `tests/driver/icon.test.ts` —— 格式识别、生成的 C、ICO 转换、图标对象缓存、
-  `llvm-rc`/`windres` 命令行、mac bundle 布局与退化路径，以及 `build()` 集成
+  `llvm-rc` 命令行、mac bundle 布局与退化路径，以及 `build()` 集成
   （链接图标对象；图标缺失 ⇒ `DiagnosticCode.IOError`）。
 - `tests/e2e/icon.test.ts` —— 用 `app.icon` 编译真实 GUI 程序，断言可执行文件中
   存在 PNG 字节，并在无头模式运行；darwin 上校验 `.app` bundle 与 `.icns`。

package/doc/zh-CN/implemented/async.md

@@ -0,0 +1,49 @@
+# 异步、Promise 与生成器
+
+> 属于[已实现语法与功能](../implemented.md) · [English](../../implemented/async.md)
+
+实现位置：`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` 闭包用 `xt_function_set_async` 标记；调用时在栈式协程（`xt_coroutine.c`、`xt_async.c`）上运行函数体并立即返回 promise。
+- 函数体同步执行到第一个等待**未 settle** promise 的 `await` 后挂起；promise settle 时排入微任务恢复协程。
+- 逃出函数体的异常会让该 promise reject，而不是同步抛出。
+- `await` 非 promise 或已 settle 的值仍走同步快路径，rejection 触发异常。
+- 每次 `async` 调用拥有私有栈，切换异常帧栈与 GC 栈区间，因此 `await` 可跨越 `try`/`finally`、循环与闭包。由定时器、套接字回调或另一个协程 settle 的 promise 会在微任务队列上恢复挂起的函数体。
+
+## 异步生成器
+
+- `async function*` 闭包用 `xt_function_set_async_generator` 标记；每次 `.next()` / `.throw()` / `.return()` 入队一个请求并返回 promise。
+- 函数体在生成器协程上运行，可在 `yield` 或 `await` 处挂起；`xt_generator_await` 将协程挂在被等待的 promise 上，并让当前请求保持 pending，直到下一次 yield 或函数体结束。
+- `for await...of` 降级为 `xt_async_iter_open` / `xt_async_iter_next` + `xt_await`，因此同时支持异步可迭代对象与同步迭代协议。`Symbol.asyncIterator` 已支持。
+
+## 生成器
+
+- `function*` / `yield` / `yield*`，以及 `.next()` / `.throw()` / `.return()`，基于同一套栈式协程运行时实现。
+- 支持 `for...of`、展开与委托。
+
+## Promise
+
+- 微任务队列（`xt_microtasks`）；`xt_promise_ctor/resolve/reject/static`（含 `withResolvers`）、实例 `then` / `catch` / `finally`。
+- `xt_drain_microtasks` 在程序结束时清空队列，事件循环也会在回调之间清空它。
+- `xt_await` 对非 Promise / 已 settle 值排入一次微任务，对 pending promise 则挂起当前 async 协程直到 settle。
+
+## 定时器与事件循环
+
+- `setTimeout` / `clearTimeout` / `setInterval` / `clearInterval` / `setImmediate` / `clearImmediate` / `queueMicrotask` 与 `performance.now`（单调递增的小数毫秒）。
+- 定时器使用数字 id；未实现 `Timeout` / `Immediate` 对象。
+- 定时器 settle 的 promise 可以被 await：async 函数体在 pending promise 上挂起，定时器触发时恢复。套接字与服务端（`net`、`http`、`dgram`）的回调在同一事件循环上投递。
+- `fetch` 与 `fs/promises` 由 reactor 驱动而不是阻塞 —— 见下一节。
+
+## 异步 I/O offload
+
+- `runtime/xt_async_io.c` 维护一个小型工作线程池（默认 4 个，惰性创建）。每个 job 分成两半：worker 上的 `run` 只能访问纯 C 内存；主线程上的 `complete` 才构造值并 settle promise。这个拆分让回收器与值模型保持单线程。
+- job 完成后通过自管道（POSIX）或回环 UDP 套接字（Windows）唤醒 `select(2)`；reactor 也会轮询线程池，因此唤醒失败只会退化为短暂等待，而不会挂起。
+- job 排队或运行期间，每个 job 最多四个值（promise；对 `fetch` 还有 headers 对象）保存在 job 的 root 槽中，由回收器扫描。
+- `fetch` 把每一跳请求/重定向作为 job 执行；`fs/promises` 把每个文件与描述符操作作为 job 执行。两者都不会阻塞定时器、套接字或其他 `await`。
+- 仍有 job 未完成时事件循环保持存活（`xt_loop_has_work`），线程池空闲后退出。
+
+异步表面的已知限制（`fetch` 无 TLS/流式、`fs.watch` 不触发、线程池固定 4 个 worker）列在[运行时偏差](../unimplemented/deviations.md)与各 Node 页面。