xbintsc 0.5.23 → 0.5.32

package/doc/support-matrix.md

@@ -0,0 +1,83 @@
+# Support matrix
+
+> Language: **English** | [简体中文](./zh-CN/support-matrix.md)
+
+> **Generated** by `npm run docs:matrix` from the executable catalogue in
+> [`tests/conformance/test262/manifest.ts`](../tests/conformance/test262/manifest.ts). Do not edit this
+> file by hand: change a case and regenerate.
+
+Every supported case is an unmodified [test262](https://github.com/tc39/test262)
+file (pinned at `d53ebc8b1931d9f1541e43d59650776e4b766248`) that xbintsc compiles **and runs**; the
+[test262 suite](../tests/conformance/test262.test.ts) fails if one stops passing. The corpus is a
+representative subset, not a full test262 run. Every unsupported case
+is valid JavaScript that xbintsc currently rejects, pinned with the diagnostic
+code it produces. See [`SOURCE.md`](../tests/conformance/test262/SOURCE.md) for the harness adaptation.
+Because the suite runs on every CI platform, this table cannot claim more than
+the compiler does.
+
+## Coverage by area
+
+| Area | Supported | Unsupported | Reference |
+| --- | ---: | ---: | --- |
+| Values and operators | 2 | 1 | [reference](implemented/operators.md) |
+| Strings (UTF-16 semantics) | 2 | 0 | [reference](implemented/strings.md) |
+| Arrays | 2 | 0 | [reference](implemented/stdlib.md) |
+| Objects | 2 | 0 | [reference](implemented/stdlib.md) |
+| Classes and inheritance | 2 | 0 | [reference](implemented/codegen.md) |
+| Closures and functions | 2 | 1 | [reference](implemented/binder.md) |
+| Exceptions | 2 | 0 | [reference](implemented/runtime-core.md) |
+| Async and promises | 2 | 0 | [reference](implemented/async.md) |
+| JSON | 2 | 0 | [reference](implemented/stdlib.md) |
+| Map and Set | 2 | 0 | [reference](implemented/collections.md) |
+| Regular expressions | 2 | 0 | [reference](implemented/stdlib.md) |
+| Typed arrays and binary data | 2 | 0 | [reference](implemented/typed-arrays.md) |
+| Date | 2 | 0 | [reference](implemented/stdlib.md) |
+| Generators | 2 | 0 | [reference](implemented/async.md) |
+| Modules | 2 | 1 | [reference](implemented/modules.md) |
+| Optional chaining and templates | 2 | 1 | [reference](implemented/operators.md) |
+
+## Supported cases (test262, compiled and executed)
+
+| test262 case | Area | What it pins down |
+| --- | --- | --- |
+| `built-ins/Number/isInteger/integers.js` | Values and operators | Number.isInteger accepts every integer, including ±2^53 |
+| `built-ins/Number/isSafeInteger/infinity.js` | Values and operators | Number.isSafeInteger rejects ±Infinity |
+| `built-ins/String/prototype/padStart/fill-string-empty.js` | Strings (UTF-16 semantics) | padStart leaves the string unchanged when the fill string is empty |
+| `built-ins/String/prototype/includes/String.prototype.includes_Success.js` | Strings (UTF-16 semantics) | includes finds a substring at the requested position |
+| `built-ins/Array/prototype/map/15.4.4.19-1-1.js` | Arrays | map throws a TypeError when its receiver is undefined |
+| `built-ins/Array/prototype/at/index-non-numeric-argument-tointeger.js` | Arrays | at coerces false, null, undefined and the empty string to index 0 |
+| `built-ins/Object/keys/15.2.3.14-0-1.js` | Objects | Object.keys is a callable function |
+| `built-ins/Object/assign/Override.js` | Objects | Object.assign lets a later source override an earlier key |
+| `language/statements/class/subclass/class-definition-evaluation-empty-constructor-heritage-present.js` | Classes and inheritance | a derived class without a constructor forwards its arguments to super |
+| `language/statements/class/definition/class-method-returns-promise.js` | Classes and inheritance | an async class method returns a promise instance |
+| `language/expressions/arrow-function/cannot-override-this-with-thisArg.js` | Closures and functions | arrow functions cannot have this overridden by thisArg |
+| `language/expressions/function/S10.1.1_A1_T2.js` | Closures and functions | named, anonymous and parenthesised function expressions all evaluate |
+| `language/statements/try/12.14-10.js` | Exceptions | catch introduces its own scope for name lookup |
+| `built-ins/Error/length.js` | Exceptions | the Error constructor reports length 1 |
+| `language/expressions/await/async-await-interleaved.js` | Async and promises | await and promise continuations interleave on the microtask queue |
+| `built-ins/Promise/all/S25.4.4.1_A1.1_T1.js` | Async and promises | Promise.all is callable |
+| `built-ins/JSON/stringify/property-order.js` | JSON | JSON.stringify emits keys in property order |
+| `built-ins/JSON/parse/15.12.1.1-0-9.js` | JSON | JSON.parse accepts whitespace before and after a token |
+| `built-ins/Map/prototype/set/append-new-values.js` | Map and Set | Map.set appends new entries in insertion order |
+| `built-ins/Set/prototype/add/does-not-have-setdata-internal-slot-array.js` | Map and Set | Set.prototype.add rejects a non-Set receiver |
+| `built-ins/RegExp/prototype/test/S15.10.6.3_A1_T1.js` | Regular expressions | test() applies /1|12/ to the string "123" |
+| `built-ins/String/prototype/replace/15.5.4.11-1.js` | Regular expressions | replace passes the correct this to the replacer function |
+| `built-ins/DataView/prototype/getUint8/index-is-out-of-range.js` | Typed arrays and binary data | getUint8 throws a RangeError past the end of the view |
+| `built-ins/DataView/prototype/setUint32/no-value-arg.js` | Typed arrays and binary data | setUint32 stores 0 when the value argument is omitted |
+| `built-ins/Date/prototype/getUTCFullYear/this-value-valid-date.js` | Date | getUTCFullYear reads a valid date |
+| `built-ins/Date/parse/year-zero.js` | Date | Date.parse rejects the -000000 extended year |
+| `language/statements/generators/declaration.js` | Generators | generator function declarations are supported |
+| `language/expressions/generators/default-proto.js` | Generators | generator functions share the intrinsic generator prototype |
+| `language/module-code/eval-export-cls-semi.js` | Modules | an exported class declaration needs no trailing semicolon |
+| `language/module-code/eval-export-fun-semi.js` | Modules | an exported function declaration needs no trailing semicolon |
+| `language/expressions/optional-chaining/call-expression.js` | Optional chaining and templates | optional chaining applies to call expressions |
+| `language/expressions/template-literal/evaluation-order.js` | Optional chaining and templates | template substitutions evaluate from left to right |
+
+## Unsupported cases (valid JavaScript, expected diagnostics)
+
+| test262 case | Area | Diagnostic | Why |
+| --- | --- | ---: | --- |
+| `language/statements/with/12.10-0-1.js` | Optional chaining and templates | TS2001 | `with` statements are not implemented |
+| `language/expressions/new.target/value-via-call.js` | Closures and functions | TS4005 | `new.target` has no lowering |
+| `language/expressions/comma/S11.14_A2.1_T3.js` | Values and operators | TS3002 | an unbound name is a compile-time error, not a runtime `ReferenceError` |
+| `language/expressions/dynamic-import/always-create-new-promise.js` | Modules | TS2001 | dynamic `import()` is not implemented |

package/doc/unimplemented/classes.md

@@ -9,6 +9,9 @@
 | Instance fields / property declarations | ✓ |
 | Methods | ✓ |
 | `static` fields / methods | ✓ |
+| `static { ... }` blocks | ✓ implemented (runs once at class definition; static fields and blocks run in declaration order, static methods are installed first; `this` is the class, `super.x` reads the parent constructor) |
+| `static get` / `static set` accessors | ✓ (accessors on the constructor value; inherited static setters are honoured) |
+| `super[key]` / `super[key](...)` | ✓ |
 | Inheritance `extends` / `super` | ✓ (single level correct; `super` takes the prototype of `this`'s prototype — see [Runtime deviations](./deviations.md)) |
 | Prototype chain / method lookup | ✓ |
 | `instanceof` | ✓ |

package/doc/unimplemented/deviations.md

@@ -13,11 +13,12 @@ These features **compile and run**, but the result does not fully match ECMAScri
 | `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 |
+| Function `arity` / argument count | Direct calls to a locally visible function are checked by the default [semantic checker](../implemented/checker.md) (`TS4004`); calls through properties, imports, spread arguments or a reassigned binding are not. `fn.length` reports the declared arity |
 | `async` / `await` | Real suspension on a stackful coroutine; `await` always queues a microtask (non-promises and already-settled promises included), so interleaving with pending `.then` callbacks matches the specification. Top-level `await` blocks on the event loop rather than yielding the module body. `fs/promises` and `fetch` offload their blocking work to a four-worker pool and settle on the reactor. Async generators suspend at both `await` and `yield`; `for await...of` awaits one step per iteration |
 | Async generator cleanup | `for await...of` does not call the iterator's `return()` when the loop exits early. `yield*` inside an async generator delegates to synchronous iterables only. `.return()` at a suspended `yield` completes without running `finally` (the same limitation as synchronous generators) |
-| `super` | `super.x` / `super(...)` takes the prototype of `this`'s prototype; single-level inheritance is correct, but depth > 1 may be inaccurate |
+| `super` | `super.x` / `super[x]` read from the parent holder of the class whose body is running (in an instance method: the parent prototype; in a `static` method or static block: the parent constructor), so any inheritance depth is correct |
 | `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) |
+| `let` in a `for` loop header | One binding per loop, not one per iteration: closures created inside the body all observe the final value (`for (let i = 0; i < 3; i++) fns.push(() => i)` gives `3,3,3`) |
 | Module live bindings | Namespace imports and imported bindings are snapshots (see [Module system](./modules.md)) |
 | `import.meta` | ✓ `import.meta.url` / `.dirname` / `.filename`, resolved from the executable path |
 

package/doc/unimplemented/toolchain.md

@@ -6,7 +6,7 @@
 | --- | --- |
 | 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. `WeakMap`/`WeakSet` keys are ephemerons (a value is retained only while its key is reachable) and `WeakRef` targets are cleared when unreachable; because the stack scan is conservative, a stale stack word can delay that clearing. No compaction or background collection |
 | 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 |
+| Type checker | partial: the default [semantic checker](../implemented/checker.md) reports unresolved names, redeclarations, call arity, property existence and definite assignability mismatches, with structural interfaces/classes, simple generics and basic flow narrowing; there is no full inference or strict-null pass |
 | Full standard library | partial: Math / JSON / Date / Map / Set / RegExp / `Error` / `BigInt` / `Symbol` / `structuredClone` implemented; String.normalize missing |
 | Multi-file module bundling | partial: relative-path `.ts` bundling, ESM `node_modules` packages, namespace imports and bare-specifier extension module imports implemented; CommonJS is handled only inside `node_modules`; circular dependencies / live bindings are not implemented |
 | Real async runtime | ✓ `async`/`await` suspends on pending promises on the `select(2)` reactor: timers, TCP sockets, offloaded file/HTTP work and promise callbacks resume the coroutine. Still missing: real OS-level file watching, non-blocking `net.connect`, TLS for `fetch`, and user-visible worker threads (`worker_threads` uses child processes) |

package/doc/unimplemented/types.md

@@ -2,11 +2,27 @@
 
 > Part of [Unimplemented syntax and features](../unimplemented.md) · [简体中文](../zh-CN/unimplemented/types.md)
 
-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).
+Type syntax is **not** erased blindly any more: the default
+[semantic checker](../implemented/checker.md) resolves the subset of TypeScript
+types it can model and checks assignability, property existence and simple flow
+narrowing. Type syntax is still erased during code generation, and the checker
+is deliberately incomplete:
+
+- **No full inference.** An unannotated function returns `any`; generic
+  constraints, higher-order inference and return-type inference are not
+  attempted.
+- **No strict-null mode.** `null` / `undefined` are assignable wherever a value
+  is expected.
+- **No excess-property check** on fresh object literals.
+- **No overload resolution, mapped types, conditional types or template-literal
+  types.** They resolve to `any`.
+- **`as` / `satisfies` / non-null `!`** are still erased and do not validate
+  anything; the checker treats them as assertions.
+- **Complex generics.** Simple type parameters are inferred from arguments
+  (`T`, `T[]`, `Array<T>`); mapped/conditional generic machinery is not.
+- **Type arguments are not checked for arity**; an unknown type parameter is
+  just `any`.
+
+All six checker diagnostic codes are now used: `DuplicateIdentifier` (TS3001),
+`CannotFindName` (TS3002), `TypeMismatch` (TS4001), `NotCallable` (TS4002),
+`PropertyNotFound` (TS4003) and `ArgumentCountMismatch` (TS4004).

package/doc/unimplemented.md

@@ -25,7 +25,7 @@ under [implemented](./implemented.md); git history records when it changed.
 - [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
+- [Type system](./unimplemented/types.md) — parsed and erased; only inference-free facts are 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/zh-CN/gui/api.md

@@ -34,6 +34,48 @@ API 编写的文档可以原样运行。
 `ready`（首个呈现帧之后）、`load`、`close`、`resize`，以及输入事件
 `mousemove`、`mousedown`、`mouseup`、`click`、`wheel`、`keydown`、`keyup`。
 
+## 浏览器全局
+
+从 Web 迁移过来的页面很少只用到 `createWindow`。启用 `--ext gui` 后，运行时同样提供
+这类移植需要的那一层浏览器接口，程序不必自己声明：
+
+```ts
+const ctx = new AudioContext();            // 也可 window.AudioContext
+ctx.createGain().connect(ctx.destination);
+document.querySelector("#start").addEventListener("click", () => {});
+console.log(navigator.userAgent, window.innerWidth, location.href);
+requestAnimationFrame(frame);
+```
+
+| 全局 | 取值 |
+| --- | --- |
+| `window`、`self` | 最近打开的窗口句柄（若程序尚未创建窗口，会隐式打开一个），因此 `window.innerWidth`、`window.addEventListener`、`window.setTimeout`、`window.localStorage`、`window.location`、`window.devicePixelRatio`、`window.matchMedia` 都可用 |
+| `document` | 该窗口的 document 句柄 |
+| `navigator` | `userAgent`（以 `xbintsc` 结尾的桌面 Chrome 字符串）、`platform`、`vendor`、`language(s)`、`hardwareConcurrency`、`maxTouchPoints`、`onLine`、`vibrate()` |
+| `localStorage` | 内存中的 `getItem` / `setItem` / `removeItem` / `clear` / `key` / `length` |
+| `AudioContext`、`webkitAudioContext` | Web Audio 图构建器（见下） |
+| `Event`、`CustomEvent`、`ProgressEvent` 等 | 事件构造器 |
+| `HTMLCanvasElement`、`HTMLImageElement`、`WebGLRenderingContext`、`WebGL2RenderingContext`、`WebGLBuffer`/`WebGLTexture`/`WebGLShader`/`WebGLProgram`/`WebGLFramebuffer`/`WebGLRenderbuffer`/`WebGLUniformLocation`/`WebGLActiveInfo`/`WebGLVertexArrayObject`/`WebGLSampler`/`WebGLQuery`/`WebGLSync`/`WebGLTransformFeedback` | 真实的构造函数值。`canvas.getContext("webgl")` 与 `getContext("webgl2")` 返回 GPU 上下文（见 [WebGL](./webgl.md)）。 |
+| `ImageBitmap`、`ImageData`、`OffscreenCanvas`、`XRWebGL*`、`Request`、`Headers`、`Response`、`ReadableStream`、`DOMParser` | `typeof` 探测返回 `"undefined"`（没有 XR/fetch/流式后端），让页面走自己的“不支持”分支，而不是调用空壳。Three.js 页面在本后端上使用真实渲染器（见[已知问题](./known-issues.md)）。 |
+| `requestAnimationFrame` / `cancelAnimationFrame` | 排入窗口的动画帧列表，见[运行时集成](./runtime.md) |
+| `alert` / `confirm` / `prompt`、`matchMedia`、`getComputedStyle`、`escape` | 宿主实现（Annex B `escape` 按 UTF-16 码元编码，与 `decodeURIComponent(escape(bytes))` 一致） |
+
+`getElementById` / `querySelector` 在 `loadHTML` 之前也能回答：此时得到的是**挂起**句柄，
+首次使用时才绑定到真实节点，因此在模块初始化阶段缓存 `document.querySelector("#id")`
+的页面依然可用。页面解析完成后未命中则回答 `undefined`，与浏览器一致。
+
+### Web Audio
+
+`new AudioContext()` 会构建音频图，但**不做混音也不渲染音频**：背后没有后端。已实现的是
+页面运行与自检所需的接口 —— `createGain` / `createOscillator` / `createBufferSource` /
+`createBiquadFilter` / `createDynamicsCompressor` / `createBuffer`（真实的
+`Float32Array` 声道）/ `decodeAudioData`（以空缓冲区兑现）/ `resume` / `suspend` /
+`close`，`AudioParam` 的 `value` 与 `setValueAtTime` / `linearRampToValueAtTime` /
+`exponentialRampToValueAtTime` / `setTargetAtTime` / `cancelScheduledValues` /
+`cancelAndHoldAtTime`，节点 `connect`（返回目标节点，因此可链式连接）/ `disconnect` /
+`start` / `stop`。`sampleRate` 为 48000、`state` 为 `"running"`，`currentTime` 仅随
+事件循环推进。
+
 输入处理器接收单个负载对象（生命周期处理器不接收任何参数）：
 
 ```ts
@@ -92,4 +134,4 @@ win.stats()                            // 引擎/运行时计数器（内存排
 
 多窗口由对象模型自然得出：`createWindow` 返回一个原生对象句柄；每个句柄
 拥有自己的 `SDL_Window`/GPU 表面与自己的 DOM 树。`run()` 驱动一个共享主循环，
-它每帧 tick 所有窗口，并在最后一个窗口关闭时退出。
+它每帧 tick 所有窗口，并在最后一个窗口关闭时退出。

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

@@ -8,34 +8,60 @@
   （被 gitignore；按需获取）。媒体解码位于 `runtime/ext_media/`，单独构建。
 - `npm run gui`（`scripts/build-gui.ts`）获取固定版本的 SDL3（`SDL3_TAG`，
   默认 `release-3.2.10`），构建静态 SDL3，获取并构建静态 FreeType
-  （`FREETYPE_VERSION`）与 HarfBuzz（`HARFBUZZ_VERSION`），编译引擎，并把
+  （`FREETYPE_VERSION`）与 HarfBuzz（`HARFBUZZ_VERSION`），并获取、构建静态
+  **glslang**（`GLSLANG_VERSION`，默认 `16.6.0`）、固定版本的 SPIR-V 头文件
+  （`SPIRV_HEADERS_VERSION`）以及 **SPIRV-Cross**（`SPIRV_CROSS_VERSION`，默认
+  `vulkan-sdk-1.4.313.0`）。glslang 是 WebGL 背后的运行时 GLSL ES 编译器，
+  SPIRV-Cross 把它的 SPIR-V 转成 Metal 后端使用的 MSL（见
+  [WebGL](./webgl.md)），两者都与其他库一样合并进归档。随后编译引擎，并把
   所有内容合并到 `runtime/lib/<os>-<arch>/gui.a`（Windows 上 MSVC ABI 则为
-  `gui.lib`），与 `core.a` 采用相同约定，静态打包三者。合并使用 macOS 上的
+  `gui.lib`），与 `core.a` 采用相同约定，静态打包这些库。合并使用 macOS 上的
   `libtool` 与其他平台上的 `ar -M`（GNU/LLVM）；CMake 归档会在构建根目录或
   `Release/` 下按任一生成器风格被发现。
 - `npm run media`（`scripts/build-media.ts`）构建可选的 **FFmpeg** 后端。它获取
   FFmpeg（`FFMPEG_VERSION`，默认 `7.1`），配置一个只启用媒体元素所需
   demuxer/parser/decoder 的最小静态构建，用它编译
   `runtime/ext_media/media.cpp`，并把所有内容合并到
-  `runtime/lib/<os>-<arch>/media.a`。`gui.a` **不会**链接 FFmpeg：程序通过
-  `--ext media` 显式启用播放能力。
+  `runtime/lib/<os>-<arch>/media.a`（Windows 上 MSVC ABI 则为 `media.lib`）。
+  `gui.a` **不会**链接 FFmpeg：程序通过 `--ext media` 显式启用播放能力。
 - `src/extensions/gui/index.ts` 通过 `nativeObjects()` 暴露引擎归档（经由
   `findRuntimeLibrary`，因此 `.a`/`.lib` 都可用），并通过 `linkerFlags()`
-  暴露操作系统框架。`src/extensions/media/index.ts` 对 `media.a` 做同样的暴露，
-  并把注册桥（`runtime/ext_media/media_bridge.c`）作为普通 runtime 源编译。
+  暴露操作系统框架。`src/extensions/media/index.ts` 对 `media.a`/`media.lib`
+  做同样的暴露，并把注册桥（`runtime/ext_media/media_bridge.c`）作为普通
+  runtime 源编译。
 - `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` 工具链。`scripts/build-media.ts` 对 FFmpeg 与播放器
-  使用同一套已解析的工具链。
-- CI 在组装发布归档之前构建 `gui.a` 与 `media.a`，因此它们会随
-  `runtime/lib/<slug>/` 一起发布（发布 tarball 会复制整个 `runtime/` 树）。
+  后端，不需要 DXIL/`dxc` 工具链。
+- `scripts/build-media.ts` 使用同一套已解析的工具链。Windows 上它走 FFmpeg
+  自带的 MSVC 模式：`configure --toolchain=msvc --cc=clang-cl` 把静态 FFmpeg
+  编译为使用静态 MSVC CRT 的 COFF 对象，`clang++` 编译播放器，`llvm-ar`
+  把 COFF 归档合并成 `media.lib`。编译器链完全来自 Visual Studio
+  （clang-cl、`cl.exe`、`lib.exe`、`llvm-ar`）。FFmpeg 的
+  configure 是 POSIX shell 脚本、Makefile 是 GNU make 格式，因此仍需要这两个
+  构建驱动：shell 来自 Git for Windows 自带的 bash（克隆 SDL3 本来就需要
+  Git），make 是原生 GNU make（如 Chocolatey 的 `make`，或用 `xbintsc_MAKE`
+  指定）。脚本会把 configure 写出的源码路径改写成盘符路径，并跳过依赖提取，
+  因为原生 make 无法原样传递 MSVC `/showIncludes` 的 awk 管道。
+  `cl.exe`/`lib.exe` 只被 configure 的工具链探测使用，由脚本从 Visual Studio
+  安装目录解析，不需要开发者命令提示符。`xbintsc_SHELL` 与 `xbintsc_MAKE`
+  可覆盖自动发现的 shell/make。头文件与库由脚本复制到
+  `vendor/ffmpeg-build-msvc/dist`，而不是执行 `make install`。
+- CI 在组装发布归档之前构建 `gui.a`/`gui.lib` 与 `media.a`/`media.lib`，因此它们
+  会随 `runtime/lib/<slug>/` 一起发布（发布 tarball 会复制整个 `runtime/` 树）。
   归档在 Linux（Xvfb 下，使用 lavapipe 软件 Vulkan 驱动）与 macOS 上构建并运行
-  示例；Windows 为试验性，因为托管 runner 没有 GPU/Vulkan 驱动，且 media 归档
-  目前仅支持 POSIX。
+  示例；Windows x64 也会构建两个归档并链接一个 `gui,media` 程序，因此 MSVC
+  构建在 CI 中得到验证，只是*运行*示例仍为试验性（托管 runner 没有 GPU/Vulkan
+  驱动）。Windows arm64 仍跳过两个归档（FFmpeg 的 MSVC arm64 构建尚未验证）。
+- Windows CI 通过 `.github/actions/vs-toolchain` →
+  `scripts/setup-vs-toolchain.ps1` 使用与本地构建相同的 Visual Studio
+  `vcvarsall` 环境和自带的 LLVM（不再单独安装 Chocolatey LLVM）。媒体构建时该
+  action 还会通过 Chocolatey 安装 GNU make 并把 `xbintsc_MAKE` 指向它；FFmpeg
+  源码与已安装的 `vendor/ffmpeg-build-msvc/dist` 前缀按脚本哈希缓存。
+  configure/make 构建树本身不缓存（其中记录了另一台机器的绝对路径与编译选项）。
 - 现有的缓存指纹已经会对 `nativeObjects()` 的内容与 `runtimeSources()` 的内容
   做哈希，因此重建任一归档都会自动使缓存二进制失效。
 - CMake 构建树位于其源码**旁边**（`vendor/sdl-build`、`vendor/freetype-build`、
@@ -57,6 +83,26 @@ npm run media        # 可选：构建 media.a（首次会获取并构建 FFmpeg
 xbintsc run examples/gui/hello.ts --ext gui
 ```
 
+Windows 上同样的命令在普通 PowerShell 中即可产出 `gui.lib` 与 `media.lib`，
+不需要开发者命令提示符。Visual Studio 安装提供面向 MSVC 的 `clang++`、
+`clang-cl`、`cl.exe` 与 `lib.exe`；`npm run media` 还需要 POSIX shell 与
+GNU make 来运行 FFmpeg 的 `configure`：shell 来自 Git for Windows（克隆
+SDL3 本来就需要 Git），GNU make 使用原生二进制——可 `choco install make`，
+或用 `xbintsc_MAKE` 指定。脚本会指出缺失的工具，并支持
+`xbintsc_SHELL` / `xbintsc_MAKE` 覆盖。
+
+如果需要显式选择这套工具链（例如在全新终端中，或想与 CI 使用同一个编译器），
+运行：
+
+```powershell
+pwsh -File scripts/setup-vs-toolchain.ps1
+```
+
+它会导入 `vcvarsall`（MSVC、Windows SDK、MSBuild），并把 `xbintsc_CLANG` 指向
+该 Visual Studio 安装自带的 LLVM。GitHub Actions 通过
+`.github/actions/vs-toolchain` 调用同一个脚本，因此 CI 不再单独安装
+Chocolatey/独立 LLVM，CI、本地构建与预编译归档共用同一条编译链。
+
 设置 `XT_GUI_AUTOCLOSE_MS=<n>` 可在 `n` 毫秒后关闭所有窗口，e2e 测试
 （`tests/e2e/gui-*.test.ts`）用它来无头运行。
 
@@ -72,11 +118,13 @@ xbintsc run examples/gui/hello.ts --ext gui
 
 这些测试套件在 Windows 上默认跳过（归档可以在本机通过 Vulkan 运行，但 CI
 runner 没有可用的 GPU 驱动）。如果本机有 `gui.lib` 与可用的 GPU，可用
-`xbintsc_GUI_TESTS=1` 选择启用：
+`xbintsc_GUI_TESTS=1` 选择启用；如果还运行过 `npm run media`，媒体套件也会在
+Windows 上走真实的解码路径：
 
 ```bat
 set xbintsc_GUI_TESTS=1
 npx vitest run tests/e2e/gui-layout.test.ts tests/e2e/gui-example.test.ts
+npx vitest run tests/e2e/gui-media.test.ts
 ```
 
 在无头 Linux 机器上，安装 SDL3 构建头文件，并在 Xvfb 与软件 Vulkan 驱动下
@@ -90,8 +138,9 @@ xvfb-run -a --server-args="-screen 0 1280x720x24" \
   npx tsx src/cli/main.ts run examples/gui/hello.ts --ext gui
 ```
 
-媒体 e2e 套件（`tests/e2e/gui-media.test.ts`）只有在 `gui.a` 与 `media.a` 都
-存在时才会运行；`tests/e2e/gui-media-disabled.test.ts` 覆盖仅 `gui.a` 的构建。
+媒体 e2e 套件（`tests/e2e/gui-media.test.ts`）只有在 `gui.a`/`gui.lib` 与
+`media.a`/`media.lib` 都存在时才会运行；`tests/e2e/gui-media-disabled.test.ts`
+覆盖仅 GUI 归档的构建。
 
 包清单集中在 `scripts/install-gui-deps.sh`（`apt-get install -y clang cmake
 libx11-dev libxext-dev libxrandr-dev libxcursor-dev libxi-dev libxinerama-dev

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

@@ -19,9 +19,14 @@ CSS 盒中。
 
 ```ts
 const canvas: any = document.getElementById("c");
-const ctx = canvas.getContext("2d"); // 其他上下文类型返回 null
+const ctx = canvas.getContext("2d"); // 或 "webgl" 取得 GPU 上下文
 ```
 
+一个 canvas 只有一种上下文。`getContext("webgl")` 或 `getContext("webgl2")`
+返回 WebGL 上下文（见 [WebGL](./webgl.md)）；一旦 canvas 有了 2D 上下文，
+再申请任一 WebGL 类型都会返回 `null`，反之亦然。从未申请过上下文的 canvas
+保持透明。
+
 `getContext("2d")` 返回一个上下文句柄，其方法与访问器位于共享原型上。该句柄会缓存在
 元素上，因此每次都返回**同一个**对象，绘制状态（变换、样式、路径）按 canvas 而非按调用
 保存。`ctx.canvas` 是所属元素的句柄。
@@ -81,7 +86,9 @@ Canvas 像素**不参与垃圾回收**：canvas 由窗口拥有、以 DOM 节点
 而非生成轮廓。
 
 图像：`drawImage(source, …)` 支持 3 参数（`dx, dy`）、5 参数（`dx, dy, dw, dh`）与
-9 参数（`dx, dy, dw, dh, sx, sy, sw, sh`）形式。`source` 可以是 `<img>` 元素（经图像
+9 参数（本引擎为**目标优先**：`dx, dy, dw, dh, sx, sy, sw, sh`）。完整的仿射变换
+（旋转/斜切/缩放）会被应用：目标矩形变为平行四边形，每个设备像素反查到源矩形
+（最近邻采样）。`source` 可以是 `<img>` 元素（经图像
 模块解码）或另一个 `<canvas>` 元素（取其当前位图）。采样为最近邻，因此把小图大幅放大
 会有块状感——适合图标与像素画，不适合照片管线。
 

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

@@ -12,12 +12,14 @@ doctype 跳过，实体解码（命名 + 十进制/十六进制），空元素
 （`<style>`/`<script>`），以及常见的隐式闭合规则（`li`、`dt`/`dd`、`option`、
 `p`、标题、表格单元格/行）。
 
-**CSS 解析器**（`runtime/ext_gui/css.{h,cpp}`）：注释与 at-rule 暂时跳过，
-支持多选择器的规则以及声明。选择器：类型、`.class`、`#id`、属性
+**CSS 解析器**（`runtime/ext_gui/css.{h,cpp}`）：会剥离注释；`@media` 块递归解析
+（嵌套查询用 `and` 合并，逗号列表会分配到内层查询），其他 at-rule 跳过。规则支持
+多选择器与声明。选择器：类型、`.class`、`#id`、属性
 （`=`、`~=`、`|=`、`^=`、`$=`、`*=`）、四种组合器（后代、子、相邻兄弟与
-通用兄弟）以及伪类 `:first-child`、`:last-child`、`:only-child`、`:empty`、
-`:root`、`:not(...)`、`:nth-child(an+b)`、`:disabled`、`:checked`，再加上
-有状态的 `:hover` 与 `:focus`（见[输入](./input.md)）。值：长度
+通用兄弟）、伪类 `:first-child`、`:last-child`、`:only-child`、`:empty`、
+`:root`、`:not(...)`、`:nth-child(an+b)`、`:disabled`、`:checked`、有状态的
+`:hover` 与 `:focus`（见[输入](./input.md)），以及伪元素
+`::before`/`::after`（也接受旧式 `:before`/`:after`）。值：长度
 （`px`、`%`、`em`、`rem`、`vw`、`vh`、`pt`、`pc`、`in`、`cm`、`mm`、`q`）、
 颜色（十六进制、`rgb()`/`rgba()`、一个命名子集）、数字、关键字与简写
 （`margin`/`padding`/`border`/`flex`）。`transform`
@@ -25,14 +27,25 @@ doctype 跳过，实体解码（命名 + 十进制/十六进制），空元素
 `scale`/`scale3d`/`scaleX`/`scaleY`、`rotate`/`rotateZ`、`matrix`；`3d`
 拼写的 `z` 参数会被丢弃）与 `transform-origin`
 会被解析进计算样式：前者是操作列表，后者是两个（未解析的）原点长度；不支持的
-函数会让整条声明失效（见[布局](./layout.md#变换m15)）。
+函数会让整条声明失效（见[布局](./layout.md#变换m15)）。M19 增加了
+`background-image` 层列表（线性/径向）、`clip-path`
+（`inset`/`circle`/`ellipse`/`polygon`）、`filter`/`backdrop-filter` 函数列表、
+`text-shadow` 与 `content`。
 
 **层叠与计算样式**（`runtime/ext_gui/style.{h,cpp}`）：一份小的内置 UA
 样式表，作者规则按 `(!important, 特异性, 源码顺序)` 排序，然后是内联
 `style=""`（特异性最高，但非 `!important` 的内联会输给 `!important`），
-再加上文本属性的 CSS 继承。相对长度保持未解析状态直到布局阶段，`font-size`
+再加上文本属性的 CSS 继承。每次重算样式都会按当前视口过滤 `@media` 规则，
+因此调整窗口大小会切换它们。相对长度保持未解析状态直到布局阶段，`font-size`
 除外（相对*父级*字号解析）以及 `line-height`。
 
+`::before`/`::after` 的样式在原始元素之后计算：选择器最后一个复合选择器必须写
+伪元素，其余部分对原始元素匹配（因此 `.card.info::before` 可用）。伪样式继承
+原始元素的计算样式，`content` 会被解析（字符串、转义、`attr()`、引号），
+生成的合成节点存放在每次重算样式时重建的 arena 中。布局把它的盒子插在真实子元素
+之前/之后；遍历、查询、`innerHTML` 与 `elementIndex()` 永远看不到它，命中测试
+则指向原始元素。
+
 ## 交互式 DOM（M8）
 
 `win.document` 返回文档句柄；元素句柄具有稳定标识，并提供可读写的属性、

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

@@ -6,6 +6,20 @@
 
 ## 已知问题
 
+- **WebGL 1.0 与 2.0 运行在 GPU 上，但只实现了各自的子集。**
+  `canvas.getContext("webgl")` / `"webgl2"` 返回真正的 GPU 上下文（见
+  [WebGL](./webgl.md)）：GLSL ES 着色器由内置 glslang 翻译为 SPIR-V——Vulkan
+  后端直接消费，Metal 上再由内置 SPIRV-Cross 交叉编译为 MSL——绘图缓冲
+  是一张离屏颜色纹理，页面直接合成而无须读回。WebGL 2 增加了 VAO、实例化、
+  整数属性、采样器对象、`texStorage2D` 与缓冲拷贝。Uniform 块、transform
+  feedback、立方体贴图、3D 纹理、浮点/深度纹理、压缩纹理、多渲染目标、
+  `blitFramebuffer`、MSAA 与模板操作尚未实现；`clear` 会忽略 scissor 矩形。
+  在两种格式都不接受的 SDL_GPU 后端（Direct3D 12，需要 DXIL）上两种上下文都为
+  `null`。`.js` 资源加载器现在只修补 three.js 的着色器循环展开；
+  `WebGLRenderer` 直接运行在真实后端上，不再有 Canvas2D 回退。阴影贴图
+  （深度纹理）、立方体贴图/环境贴图与 HDR 渲染目标仍未支持。
+
+
 - **自动关闭时的偶发崩溃。** 设置 `XT_GUI_AUTOCLOSE_MS` 结束运行时，约五次中有两次会以原生
   访问违例（`0xC0000005`）退出，其余运行与正常退出无异。该问题只在**动画帧循环运行中**复现
   （静态文档可以正常关闭），且**不是示例游戏自身**的代码：没有任何异常信息，崩溃多发生在
@@ -23,6 +37,18 @@
   `tests/e2e/gui-example-browser.test.ts` 中。
 - **`display: none -> flex` 的重排。** 通过类名切换让隐藏元素显示在 flex 容器上时，也曾观察
   到同样的崩溃；`examples/gui/pelican-bike` 改用 `opacity` 显示游戏结束遮罩。
+- **CSS 覆盖范围是有意为之的子集。** 已实现 Grid、`clamp()`/`min()`/`max()`/`env()`、
+  `var()` 自定义属性、`inset` 简写、`box-sizing`、`visibility`/`pointer-events`、
+  `@media` 查询、生成内容（`::before`/`::after`）、线性/径向多层背景、
+  `text-shadow`、`clip-path`（`inset`/`circle`/`ellipse`/`polygon`）以及 `filter`
+  的颜色函数。仍有限制：`mix-blend-mode`、`background-clip`、
+  `background-position`/`size`/`repeat`、重复渐变与 `backdrop-filter` 合成都未实现
+  （`backdrop-filter` 会解析并参与层叠，但采样背景需要离屏图层，因此不绘制）；
+  `filter: blur()` 是按图形做九次偏移的近似，而不是真正的组模糊，重叠的子元素会加深；
+  `drop-shadow` 用盒子轮廓近似；最多只交叉两层嵌套 `clip-path`（更深时保留外侧两层）；
+  图像/画布除图像着色器能携带的亮度与透明度染色外不做颜色滤镜。Canvas 纹理使用
+  最近邻采样。背景渐变仍是纯色带（线性 18 条、径向 32 个同心椭圆），柔和渐变可能
+  出现轻微条带。
 - **SVG 是 NanoSVG 的子集。** SVG *文件*（`<img src="logo.svg">`）与内联
   `<svg>` 子树共用 vendored 的 NanoSVG 解析/光栅化器（`runtime/ext_gui/svg.cpp`、
   `inline_svg.cpp`），它会渲染 `path`/`rect`/`circle`/`ellipse`/`line`/
@@ -48,20 +74,27 @@
   相同的、面向 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` 是可以的。那里
-  SDL_GPU 会选择 **Vulkan** 后端（`win.driver()` 返回 `"vulkan"`），因此归档
-  不需要 DXIL/`dxc` 工具链；托管 Windows runner 没有 GPU/Vulkan 驱动，这才是
-  CI 运行仍为试验性的原因。
-- **Windows 上的媒体：** `media` 扩展目前仅支持 POSIX。GUI 引擎本身可在
-  Windows 上构建，但没有该扩展时 `<video>`/`<audio>` 为空操作（打开失败并触发
-  `error`），`--ext media` 会给出可操作的错误而不是继续链接。启用它需要
-  MSVC 兼容的 FFmpeg 构建，推迟到 Windows GUI 路径本身验证之后。
-  `<video controls>` 同样推迟——预期模式是 TS + CSS 叠层，如
-  `examples/gui/media.ts`。
+  （COFF 对象 + `ar -M`/`llvm-ar`）。Windows x64 的 CI job 使用 Visual Studio
+  工具链（`.github/actions/vs-toolchain` 导入 `vcvarsall` 并采用 VS 自带的
+  LLVM）构建它、链接一个 `gui,media` 程序，并随 x64 发布归档一起发布。示例在
+  托管 runner 上的*运行*仍为试验性，因为那里没有 GPU/Vulkan 驱动（SDL_GPU 在
+  Windows 上选择 **Vulkan** 后端，因此不需要 DXIL/`dxc` 工具链）。Windows
+  arm64 仍跳过两个归档。在开发者机器上构建并运行
+  `examples/gui/pelican-svg` 与 `examples/gui/pelican-bike` 是可以的。
+- **Windows：x64 在 CI 中构建，arm64 与运行时验证仍为试验性。**
+  `scripts/build-media.ts` 用 FFmpeg 的 MSVC 工具链
+  （`--toolchain=msvc --cc=clang-cl`）生成 `media.lib`，其 COFF 对象与静态 CRT
+  和 `gui.lib` 一致，`--ext media` 在 Windows 上可以正常链接并播放。构建它需要
+  POSIX shell 运行 FFmpeg 的 `configure` 以及 GNU make；shell 来自 Git for
+  Windows（克隆 SDL3 本来就需要 Git），make 是原生 GNU make（Chocolatey 的
+  `make`，或 `xbintsc_MAKE`）。CI 会显式安装 make，在
+  Windows x64 上使用与本地构建相同的 Visual Studio `vcvarsall` + 自带 LLVM
+  构建 `gui.lib` 与 `media.lib`，链接 `gui,media` 程序，并把两个归档放进
+  Windows x64 发布包；示例的*运行*仍因托管 runner 没有 GPU/Vulkan 驱动而保持
+  试验性。Windows arm64 仍跳过两个归档；`<video controls>` 同样推迟——预期模式
+  是 TS + CSS 叠层，如 `examples/gui/media.ts`。
 - **D3D12 着色器：** SPIR-V（Vulkan）与 DXIL（Direct3D 12）二进制块均已构建并
   内嵌，非 Metal 路径不再跳过几何绘制。但在 **SDL 3.2.10** 上 DXIL 仍不可用：
   其 D3D12 后端会拒绝任何着色器中声明了 uniform buffer 的图形管线，而引擎正是
   用这种方式传视口。Windows 实际会选择 Vulkan，因此不受影响；若将来强制走
-  D3D12，需在 SDL 升级后重新确认。
+  D3D12，需在 SDL 升级后重新确认。

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

@@ -28,6 +28,20 @@
   flex 项的外边距参与其外框尺寸，因此
   负的 `margin-top` 会把该项上移，而不是被忽略。项之间的纯空白文本
   （源码缩进）不会成为 flex 项。
+- **Grid** —— `display: grid`，支持 `grid-template-columns` /
+  `grid-template-rows`（固定长度、`auto`、`<n>fr`、`minmax(...)`、
+  `repeat(...)`）、`gap`/`row-gap`/`column-gap`、按行自动放置、简单的
+  `grid-column`/`grid-row` 线定位，以及 `align/justify-items` 与
+  `align/justify-self`（含 `place-items`/`place-self`）。隐式行/列由项目撑开；
+  单单元格网格配合 `place-items: center` 可把卡片居中到整个覆盖层。项目测量是
+  两遍布局（先固有尺寸、再最终放置），因此两遍之间会清空文本片段。
+- **CSS 值函数与自定义属性** —— `clamp(min, value, max)`、`min(...)` 与
+  `max(...)` 在计算样式中保留参数，布局时结合元素字号与视口（`vw`/`vh`）求值；
+  桌面窗口中 `env(safe-area-inset-*)` 解析为 0。`var(--name[, fallback])` 在
+  层叠期间从继承的自定义属性替换。`inset` 是四值 `top/right/bottom/left`
+  简写；`box-sizing: border-box` 会从显式宽高里扣除 padding 与边框；
+  `visibility: hidden` 跳过绘制与命中测试；`pointer-events: none` 使盒子不接收输入
+  （后代可用 `auto` 重新启用）。
 - **定位** —— `position: relative` 会按 `top`/`right`/`bottom`/`left` 偏移该盒子
   及其子树，但不改变它在流中占用的空间；`position: absolute`（以及针对视口解析
   的 `fixed`）使其脱离文档流，并相对最近的已定位祖先的 padding box 定位（没有

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

@@ -57,17 +57,21 @@ opacity、`display`——与任何其他元素一样。盒子内部的艺术内
 
 媒体播放横跨两个扩展，因此只做界面的 GUI 程序不必为用不到的解码器付出体积：
 
-- **`gui`**（`gui.a`）负责 `<video>`/`<audio>` 元素、DOM API、渲染器集成与 SDL
-  音频 sink，但**不含 FFmpeg**。`runtime/ext_gui/media.{h,cpp}` 声明播放器接口，
-  并通过媒体后端在启动时安装的函数表分发（`runtime/ext_gui/media_api.h`）。
-- **`media`**（`media.a`、`runtime/ext_media/`）是可选的解码后端：
-  `runtime/ext_media/media.cpp` 封装静态 vendored 的 **FFmpeg** 构建，
-  `runtime/ext_media/media_bridge.c` 把它注册进引擎。用 `--ext media`（或
-  `--ext gui,media`）启用。`media` 依赖 `gui`；注册表会拒绝错误的组合。
+- **`gui`**（`gui.a`/`gui.lib`）负责 `<video>`/`<audio>` 元素、DOM API、渲染器
+  集成与 SDL 音频 sink，但**不含 FFmpeg**。`runtime/ext_gui/media.{h,cpp}`
+  声明播放器接口，并通过媒体后端在启动时安装的函数表分发
+  （`runtime/ext_gui/media_api.h`）。
+- **`media`**（`media.a`，Windows 上 MSVC ABI 则为 `media.lib`；
+  `runtime/ext_media/`）是可选的解码后端：`runtime/ext_media/media.cpp`
+  封装静态 vendored 的 **FFmpeg** 构建，`runtime/ext_media/media_bridge.c`
+  把它注册进引擎。用 `--ext media`（或 `--ext gui,media`）启用。`media`
+  依赖 `gui`；注册表会拒绝错误的组合。
 
 没有 `media` 扩展时，元素仍然存在、DOM API 仍可调用，但打开源会失败并触发
-`error`。Windows 目前也是如此：该归档仅支持 POSIX。两条路径都没有 WebView，也
-没有平台媒体框架。
+`error`。任何没有构建该归档的宿主（先运行 `npm run media`）都是如此；
+Windows 已不再特殊：`media.lib` 是用 clang-cl 为 MSVC ABI 编译的 FFmpeg，
+因此可以和 `gui.lib` 一起链接并正常播放。两条路径都没有 WebView，也没有平台
+媒体框架。
 
 - **解码。** `avformat_open_input` 打开 `src`（是路径——接受 `file://`，但与
   图像不同，媒体路径*不做*百分号解码），为每种媒体选取最佳流，软件解码器
@@ -83,8 +87,8 @@ opacity、`display`——与任何其他元素一样。盒子内部的艺术内
   `xtgui::AudioSink`。GUI 在 `gui_media.cpp` 中用 push 模式（`NULL` 回调）的
   `SDL_OpenAudioDeviceStream` 实现该 sink，在前方缓冲约 0.25 秒，格式为
   48 kHz 立体声 `SDL_AUDIO_F32`。`volume` 映射到 `SDL_SetAudioStreamGain`；
-  音频是尽力而为，无设备时（无头 CI）跳过。把 sink 留在 `gui.a` 中意味着
-  `media.a` 只依赖 FFmpeg。
+  音频是尽力而为，无设备时（无头 CI）跳过。把 sink 留在 GUI 归档中意味着
+  `media.a`/`media.lib` 只依赖 FFmpeg。
 - **线程。** 引擎是单线程且非线程感知，因此所有解码都在主线程的
   `xt_gui_media_tick` 内完成——没有解码线程，也没有跨线程 GC 暴露。
 - **DOM API。** 元素句柄直接暴露媒体接口（见