xbintsc 0.3.87 → 0.5.20

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,277 +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`)
-- `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`) |
-| 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; the constructors are still not first-class values (`const A = Array` fails) |
-| 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 (synchronous microtask model) |
-| `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 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 |
-| --- | --- |
-| String `length` | Counted in UTF-8 bytes, not UTF-16 code units (`"\u00e9".length` reports 1 instead of 2; `"\u{1F600}".length` reports 4 instead of 2; `codePointAt` likewise differs) |
-| `Object.getPrototypeOf({})` | Returns `undefined` instead of the `Object.prototype` object |
-| 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` | **Synchronous microtask model**: `await` on an already-settled promise continues synchronously. Timers and sockets run on the event loop only after the program body, so a promise settled from a timer callback cannot be awaited |
-| `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 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 |
-| A real async runtime / event loop | ✗ (Promise is a synchronous microtask model) |
-| 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): a real async event loop, UTF-16 string length,
-                         Object.prototype identity, 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/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

@@ -43,12 +43,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 +61,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/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

@@ -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** ✅
    - 具有稳定标识的元素/文档句柄、通过运行时访问器读写属性、遍历/特性/查询、
      带有延迟重算样式/重新布局的变更

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,38 @@
+# 异步、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_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` 在 settle 前同步完成 I/O —— 见[运行时偏差](../unimplemented/deviations.md)。异步生成器清理限制也在同一页列出。

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

@@ -0,0 +1,13 @@
+# 名字绑定与作用域（Binder）
+
+> 属于[已实现语法与功能](../implemented.md) · [English](../../implemented/binder.md)
+
+实现位置：`src/binder/binder.ts`
+
+- 作用域种类：模块、函数、块、`for`、`catch`
+- 符号种类：`var` / `let` / `const` / `function` / `parameter` / `class` / `interface` / `type` / `enum` / `import` / `namespace`
+- `var` 与函数声明提升到函数作用域；`let` / `const` 保持块作用域
+- 标识符 → 声明 的解析；未解析标识符收集（`CannotFindName`）
+- 闭包捕获分析：被内层函数引用的外部变量标记 `captured` / `boxed`，并穿过中间闭包传递捕获索引
+- 参数登记为局部符号；命名函数表达式自名登记为 `const`
+- 类型专用声明（interface / type alias）不参与值捕获

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

@@ -0,0 +1,46 @@
+# CLI 与编程接口
+
+> 属于[已实现语法与功能](../implemented.md) · [English](../../implemented/cli.md)
+
+实现位置：`src/cli/main.ts`、`src/index.ts`、`bin/xbintsc.js`
+
+## CLI 命令
+
+```
+xbintsc build <file.ts> [options]   编译为原生二进制
+xbintsc run   <file.ts> [-- args]   编译并执行
+xbintsc emit  <file.ts>             打印 LLVM IR
+xbintsc version                     打印版本
+xbintsc help                        帮助
+```
+
+## CLI 选项
+
+```
+-o, --output <path>   输出路径
+    --out <dir>       输出目录（默认 build/）
+    --emit <kind>     exe | obj | ir（默认 exe）
+-O0..-O3              优化级别（默认 -O2）
+    --ext <names>     逗号分隔扩展（如 node）
+    --ext-native <m>  从 JSON manifest 注册 C++/Rust 扩展
+    --config <path>   使用项目配置（默认自动查找 xbintsc.config.json）
+    --no-config       不读取任何项目配置
+    --icon <path>     内嵌应用图标（PNG/ICO/ICNS）
+    --bundle          macOS：同时生成 .app bundle
+    --app-name <name> bundle / 显示名称
+    --app-id <id>     macOS bundle 标识符（如 com.example.demo）
+    --force           忽略增量缓存
+    --verbose         打印进度信息
+```
+
+## 编程接口
+
+```ts
+import { build, compileString } from "xbintsc";
+
+const { ir } = compileString("console.log(1 + 1);");
+const result = build("program.ts", { emit: "exe", outDir: "build" });
+```
+
+选项与结果类型（`BuildOptions`、`BuildResult`、`EmitKind`、`PhaseTiming`）位于
+`src/driver/options.ts`，并由 `src/driver/compiler.ts` / `xbintsc` 重新导出。

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

@@ -0,0 +1,33 @@
+# LLVM IR 代码生成（Codegen）
+
+> 属于[已实现语法与功能](../implemented.md) · [English](../../implemented/codegen.md)
+
+实现位置：`src/codegen/llvm.ts`
+
+- 生成 LLVM IR 文本（`.ll`），无需自建寄存器分配（依赖 `alloca` + mem2reg）。
+- 语句 / 块边界值放在 `alloca`；条件与短路运算物化为临时槽，不使用 `phi`。
+- 属性读取按源码位置生成内联缓存：每个访问点拥有一个零初始化的 `[2 x i64]` 全局（`@ic.N`），传给 `xt_get_ic`。普通对象带有驻留的隐藏类 shape（`xt_shape`，`(parent, key)` 转移树），缓存保存 `(shape, 属性下标)`，命中时只需比较 shape 指针并校验一次键，无需线性扫描属性表。插入/删除属性以及整数键重排会重建或转移 shape，从而使旧缓存失效；数组、函数与容器回退到 `xt_get`。
+- 数值运算符保留内联双精度快路径；数值字面量操作数跳过标签检查。若条件表达式本身是比较、`in`、`instanceof` 或 `!`，其值已经是布尔标签，代码生成用 `icmp eq i64 value, XT_TRUE` 代替调用 `xt_truthy`（热循环条件因此少一次调用）。
+- 控制流：`if` / `while` / `do` / `for` / `for...of` / `for...in`，`switch`，`try/catch/finally`，`break` / `continue` / `return`。
+  - `for...of` 与展开通过 `xt_iter_open` → `xt_iter_has` / `xt_iter_value` 迭代数组、字符串、类型化数组、`Map`、`Set`、生成器以及任何暴露 `[Symbol.iterator]()` 的对象（`Map` 产出 `[key, value]` 对）；非可迭代值抛出 `TypeError`。数组还暴露稳定的 `Array.prototype[Symbol.iterator]`，调用后返回带 `next()` 且自身可迭代的迭代器对象。
+  - `switch` 以严格相等逐 `case` 测试，命中后执行并在 `break` 前穿透。
+  - `try/catch/finally` 通过运行时 `_setjmp` 帧实现：`xt_try_enter` 入栈、`_setjmp` 捕获、`xt_throw` 长跳转；IR 会把调用方的帧地址（`@llvm.frameaddress(0)`）作为 `_setjmp` 的第二个参数传入，与 clang 编译 MSVC 时的降级方式一致：Windows UCRT 的 `_setjmp` 会把这个帧存入 `_JUMP_BUFFER.Frame`，`longjmp` 再交给 `RtlUnwind` 执行栈展开；若不传该参数，`longjmp` 会展开到错误目标（`STATUS_BAD_FUNCTION_TABLE`）。使用 `_setjmp` 而非导出的 `setjmp` 符号，因为后者的 Windows ABI 是不兼容的双参数例程。含 `try` 的函数会强制局部变量驻留内存（内联汇编逃生点）以保证长跳转后值不丢失。
+  - `for...in` 复用 `xt_object_keys` 枚举键（数组 / 字符串得到字符串下标）。
+- 表达式：
+  - 标识符、数字、BigInt（任意精度）、字符串、模板、布尔、`null`、`undefined`、`arguments`
+  - 算术 / 比较 / 逻辑 / 短路 / 条件 / 位运算 / 一元（含 `typeof` `void`）/ 前后缀增减 / 复合赋值 / 逻辑赋值
+  - 数组字面量（含展开 `[...]`）、对象字面量（含简写 / 方法 / 对象展开 `{...obj}`）
+  - 类型化数组、`ArrayBuffer`、`DataView`、`TextEncoder` / `TextDecoder`：见[类型化数组与二进制数据](./typed-arrays.md)与[字符串与文本](./strings.md)
+  - 属性访问（含 `length` 特判、`Math` 常量）、元素访问、调用
+  - 一等公民内建构造器（`const A = Array`、`const M = Map`、`const E = TypeError`、类型化数组）：裸引用下降为 `xt_builtin_constructor`，得到带 `name` / `length`、`prototype` 与静态成员（`A.isArray`、`A.from`、`M.prototype` 等）的缓存函数。通过别名调用或 `new` 会分派到同一运行时构造器，`x instanceof A` 沿共享原型链判断。
+  - 可选链 `?.` / `?.[]` / `?.()`：以空值判断短路到 `undefined`
+  - `delete`、`in`、`instanceof`
+  - `this`（保存到函数 `%saved.this`；箭头函数从环境槽读）、`super`（`super.x` / `super(...)`）、`new`、`await`
+  - 闭包（箭头函数 / 函数表达式）与捕获环境构建
+- 类：构造器闭包 + 原型对象，存入 LLVM 全局（`@class.<id>`）；实例字段在构造器体前初始化；`static` 成员存于构造器属性包；`extends` 设置原型链；`super(...)` 通过原型上的隐藏 `__ctor` 调用。
+- `async` / `async function*`：闭包分别用 `xt_function_set_async` / `xt_function_set_async_generator` 标记，并在栈式协程上运行——见[异步、Promise 与生成器](./async.md)。
+- 标准库调用统一走 `xt_call_method` / `xt_math_call` / `xt_object_*` 与各构造器的 `xt_*` 入口；完整表面见[标准库](./stdlib.md)。
+- 全局字符串池（`@.str.N` 私有常量，UTF-8 转义）。
+- 内置调用：`console.log` / `info` / `warn` / `error`、`Math.*`、`Object.*`、数组 / 字符串方法、全局函数、扩展 builtins（统一 `(argc, argv)` ABI）。
+- `main` 入口（返回 0，调用模块函数，并在返回前 `xt_drain_microtasks`）。
+- 未支持节点统一报 `UnsupportedFeature`，不会崩溃。

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

@@ -0,0 +1,26 @@
+# 集合
+
+> 属于[已实现语法与功能](../implemented.md) · [English](../../implemented/collections.md)
+
+实现位置：`runtime/xt_stdlib2/container.inc`（Map / Set）与
+`runtime/xt_weak.c`（WeakMap / WeakSet / WeakRef）。
+
+## Map 与 Set
+
+- `new Map()` / `new Map(iterable)`、`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` 与展开通过 `[Symbol.iterator]` 迭代；`Map` 产出 `[key, value]` 对，`keys` / `values` / `entries` 按插入序返回数组。
+- `Object.keys` / `values` / `entries` 不会看到集合内部结构。
+- `structuredClone` 支持 `Map` 与 `Set`，保留循环引用与共享引用。
+
+## WeakMap、WeakSet 与 WeakRef
+
+- `WeakMap`：`get` / `set` / `has` / `delete`；`WeakSet`：`add` / `has` / `delete`；`WeakRef`：`deref()`。
+- 键（以及 `WeakRef` 目标）不会让被引用对象存活：`WeakMap` / `WeakSet` 的键是 **ephemeron**（只有键可达时才保留值），`WeakRef` 目标不可达时会被清空。
+- 栈扫描是保守的，残留的栈字可能延迟弱目标清空。完整 GC 描述见[运行时偏差](../unimplemented/deviations.md)与[未实现：工具链](../unimplemented/toolchain.md)。
+
+## 迭代
+
+- 任何暴露 `[Symbol.iterator]()` 的对象都可在 `for...of` 与展开中使用。`Array.prototype[Symbol.iterator]` 稳定，调用后返回带 `next()` 且自身可迭代的迭代器对象。
+- 迭代细节另见[代码生成](./codegen.md)与 [Symbol](./stdlib.md)。

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

@@ -0,0 +1,19 @@
+# 驱动、增量编译与工具链
+
+> 属于[已实现语法与功能](../implemented.md) · [English](../../implemented/driver.md)
+
+实现位置：`src/driver/compiler.ts`（编排）、`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`。
+
+- 编译流水线：读源 → 模块打包（`src/driver/modules.ts`，当入口含 `import`/`export` 时）→ 解析 → 绑定/检查 → IR → 目标文件 → 链接。
+- 增量缓存：以「编译器版本 + 源码哈希 + emit 类型 + 优化级别 + LTO/PGO 模式 + 平台 + 扩展指纹（名称、链接参数、原生对象内容）」为键，产物存在且新鲜则跳过构建。`--pgo-use` 总是重新构建，因为 profile 数据可能变化而源码不变。缓存键在 `src/driver/build-key.ts` 中组装。
+- C 运行时与扩展源按内容哈希缓存目标文件，只编译一次（缓存键包含 LTO/PGO 参数）。核心翻译单元列表 `RUNTIME_SOURCES` 位于 `src/driver/runtime-objects.ts`。
+- 工具链封装：查找 `clang`（可用 `xbintsc_CLANG` 覆盖）、编译 IR、编译 C、链接。
+- LTO（`--lto` / `"lto": true`）：程序与运行时都编译为 LLVM bitcode（`-flto`），并用 `-fuse-ld=lld` 链接；需要 lld。
+- PGO（先 `--pgo-generate[=dir]`，再 `--pgo-use[=dir]`，或配置 `"pgo"` / `"pgoDir"`）：生成 IR 与运行时 C 都用 `-fprofile-generate=<dir>` 插桩；运行插桩后的二进制，`--pgo-use` 会用 `llvm-profdata` 合并 `.profraw`（优先使用 clang 旁边的副本，可用 `xbintsc_LLVM_PROFDATA` 覆盖），再以 `-fprofile-use=<dir>` 重新构建。
+- 链接参数：非 Windows 自动加 `-lm`；扩展可追加链接参数。
+- 项目编译配置（`src/driver/config.ts`、`xbintsc.config.json`）：`entry`、`outDir`、`output`、`optimize`、`lto`、`pgo`、`pgoDir`、`extensions`、`extNative`、`force` 与 `app`（`name`、`icon`、`bundle`、`bundleId`）。从入口/当前目录向上查找，可用 `--config` 指定、`--no-config` 关闭；所有路径以配置文件所在目录为基准；CLI 参数优先于配置。
+- 应用图标（`src/driver/icon.ts`、`win-icon.ts`、`mac-bundle.ts`，`--icon`/`app.icon`）：PNG/ICO/ICNS 以 `xt_app_icon_*` 符号内嵌；Windows 上通过 `llvm-rc` 合成 PE 资源；macOS 上打包为 `Foo.app`（用 `sips`/`iconutil` 生成 `AppIcon.icns`）。`gui` 扩展用内嵌字节调用 `SDL_SetWindowIcon`；`xbintsc_RC` 可覆盖资源编译器。
+- 编译器版本：`COMPILER_VERSION` 位于 `src/driver/version.ts`，是缓存键的一部分。pre-commit 钩子只在 `main`/`master` 上（与 `package.json` 一起）提升它，因此功能分支不会改动版本文件。