xbintsc 0.5.32 → 0.5.37

package/doc/gui.md

@@ -25,7 +25,10 @@ engine bounded memory: see [Node lifetime](./gui/dom.md#node-lifetime) and
 thread with a vendored minimal FFmpeg, video frames go through the image texture
 path and audio to an SDL stream, with the DOM media API exposing
 `play`/`pause`/`currentTime`/… and media events. Enabling `gui` alone does not
-link FFmpeg.
+link FFmpeg. The browser globals also get a real `AudioContext`: a 48 kHz mixer
+in `runtime/ext_gui/audio_mixer.cpp` plus `decodeAudioData` (WAV in-engine,
+compressed formats through `media`) — see
+[GUI API](./gui/api.md#web-audio).
 **M14** adds `<canvas>` with a self-written 2D software rasteriser (anti-aliased
 fills, paths, text and `drawImage`) uploaded through the image texture path —
 see [Canvas](./gui/canvas.md). **M15** adds CSS `transform` /
@@ -188,8 +191,9 @@ engine were Rust.
      annotating the run.
    - The `package` job builds `gui.a`/`gui.lib` and `media.a`/`media.lib` before
      assembling the release, so both ship inside the existing runtime archive
-     (`package-release` copies all of `runtime/`). Windows x64 is included;
-     Windows arm64 still skips them.
+     (`package-release` copies all of `runtime/`) and inside the optional
+     `@xbintsc/<os>-<arch>` npm package. Windows x64 is included; Windows arm64
+     still skips them.
    - `vendor/` (SDL3/FreeType/HarfBuzz for the GUI archive, FFmpeg for `media`)
      is cached per OS/arch, keyed by `scripts/build-gui.ts` /
      `scripts/build-media.ts`. Windows x64 gets its own source cache plus the

package/doc/npm-package.md

@@ -36,8 +36,9 @@ If you are an agent asked to build a project that already depends on `xbintsc`:
 4. Run the artifact (`./build/<name>`, `.exe` on Windows) and report its path.
 5. If the build reports unsupported syntax, read the installed subset guide at
    `node_modules/xbintsc/doc/ai/language-support.md`; do not assume
-   Node-compatible TypeScript. The first build also compiles the C runtime, so
-   allow more time than for an incremental build.
+   Node-compatible TypeScript. With the optional platform package installed the
+   first build links a prebuilt runtime; without it, the C runtime is compiled
+   from source and that build is noticeably slower.
 
 Do not run `npm install` inside `node_modules/xbintsc`, and do not substitute
 `tsc`/`esbuild` for xbintsc: the native artifact must come from `npx xbintsc`.
@@ -54,15 +55,22 @@ The package contains:
 It runs the compiler through Node.js. The binary it produces is still
 standalone: it does not embed Node, V8 or a TypeScript compiler.
 
+Installing it also installs the optional `@xbintsc/<os>-<arch>` package for the
+host (for example `@xbintsc/linux-x64`). That package contains the prebuilt
+runtime archives under `runtime/lib/<os>-<arch>/`: `core`, `ext_node` and, where
+the release publishes them, `gui` and `media`. The driver links those archives
+in place, so the first build does not compile the C runtime and needs no extra
+download from the release page.
+
 The package does **not** contain:
 
-- a C compiler — you need clang 16+ on the machine that builds;
-- prebuilt runtime archives (`runtime/lib/<os>-<arch>/core.a`). The driver
-  compiles the C runtime from the shipped sources on first use and caches the
-  objects, so the first build is slower (see [the cache](#the-first-build-and-the-cache));
-- the GUI/media native archives (`gui.a`, `media.a`). If you need `--ext gui` or
-  `--ext media`, use a Linux/macOS release archive or build those archives from
-  a source checkout.
+- a C compiler — you need clang 16+ on the machine that builds.
+
+If npm skips the optional package (`--omit=optional`, a package manager that
+does not install optional dependencies, or a host the release does not build
+for), the driver falls back to compiling the C runtime from the shipped sources
+and caches the objects; that build works but is slower, and `--ext gui` /
+`--ext media` need the archive to be present.
 
 ## Requirements
 
@@ -182,7 +190,7 @@ npm run build:native
 ./build/main          # .\build\main.exe on Windows
 ```
 
-Expected output (the first build also compiles the C runtime):
+Expected output:
 
 ```text
 xbintsc: wrote /absolute/path/my-app/build/main
@@ -195,17 +203,38 @@ pass the file explicitly: `xbintsc build src/main.ts --out build`.
 
 ## The first build and the cache
 
-The runtime objects are cached by source/header content hash. The default cache
-is `.xbintsc/` **in the directory you run the command from** (not necessarily
-next to the config file); set `xbintsc_CACHE_DIR` to put it elsewhere.
+With the platform package installed, the first build links the prebuilt
+`runtime/lib/<os>-<arch>/core.a` (`.lib` on Windows) and does not compile C at
+all, so it takes about as long as an incremental build.
+
+If the optional package is missing — `npm install --omit=optional`, a package
+manager that does not install optional dependencies, or a host the release does
+not build for — the driver compiles the C runtime from the shipped sources
+instead. The runtime objects are cached by source/header content hash. The
+default cache is `.xbintsc/` **in the directory you run the command from** (not
+necessarily next to the config file); set `xbintsc_CACHE_DIR` to put it
+elsewhere. Expect that fallback build to take noticeably longer than the ones
+after it.
+
+To ignore the platform archive on purpose and compile the runtime from the
+sources shipped in the package — for example after patching `runtime/`, or when
+the prebuilt archive does not match the environment — set:
+
+```bash
+xbintsc_PREFER_PREBUILT=0 npx xbintsc build src/main.ts --out build
+```
+
+The objects are still cached in `.xbintsc/`; point `xbintsc_CACHE_DIR` at an
+empty directory (or delete `.xbintsc/`) for a full rebuild. `--force` alone
+does not bypass a prebuilt archive. The archive files themselves are produced
+by `npm run runtime` in a source checkout; users never need to regenerate them
+just to compile.
 
-Because the npm package ships the runtime as C sources but not as a prebuilt
-`core.a`, the first build compiles each runtime translation unit. Expect that
-build to take noticeably longer than the ones after it. `--time` shows where the
-time went:
+`--time` shows where the time went:
 
 ```bash
 npx xbintsc build src/main.ts --out build --time
+# fallback without the platform package:
 # xbintsc: timing (frontend 4ms, codegen 7ms, clang 1089ms, runtime 37770ms, link 1966ms)
 ```
 
@@ -220,7 +249,7 @@ Practical consequences:
 
 - add `.xbintsc/` to `.gitignore`;
 - keep `.xbintsc/` between CI runs (or point `xbintsc_CACHE_DIR` at a persistent
-  directory) to avoid paying the runtime-compile cost every time;
+  directory) so a fallback build does not recompile the runtime every time;
 - deleting `.xbintsc/` is safe — the next build recreates it;
 - `--force` ignores the build freshness record, but cached runtime objects are
   still reused. Delete `.xbintsc/` if you want to force a full C rebuild.
@@ -368,17 +397,16 @@ jobs:
 | | npm package (`xbintsc`) | Prebuilt release archive |
 | --- | --- | --- |
 | Needs Node.js | Yes, 22+ | No |
-| First build | Compiles the C runtime from source | Links the prebuilt runtime |
-| GUI / media extensions | Not included | Included in Linux/macOS and Windows x64 archives |
+| First build | Links the prebuilt runtime from the optional platform package | Links the prebuilt runtime |
+| GUI / media extensions | Included on Linux/macOS and Windows x64 (the hosts the release builds them for) | Included in Linux/macOS and Windows x64 archives |
 | Installation | `npm install` + lockfile / provenance | Download, verify `.sha256`, unpack |
 | Programmatic API | Yes | No (CLI only) |
 | Cross-compiles | No — host only | No — host only |
-| Best for | Node projects and CI, familiar npm workflow | Machines without Node, fastest first build, GUI apps |
+| Best for | Node projects and CI, familiar npm workflow | Machines without Node, GUI apps, a fully self-contained install |
 
-If you only need the core runtime and the `node` extension, the npm package is
-the most convenient option. If you need the fastest possible cold build or the
-GUI/media archives, use a release archive (or build from source for
-development).
+The npm package gets the same prebuilt runtime through its optional platform
+package, so the cold-build penalty only applies when that package is skipped.
+Use a release archive when Node is not available.
 
 ## Things that differ from a regular Node build
 
@@ -408,10 +436,10 @@ the same file under `node_modules/xbintsc/doc/ai/`.
 | `npx xbintsc` uses an unexpected version | Run `npx --no-install xbintsc version` and `npm ls xbintsc`; pin the version in `package.json` and use `npm ci` in CI. |
 | `requires Node.js 22` / engine error | Upgrade Node; the compiler uses modern Node APIs. |
 | `No C compiler found` or `requires clang 16 or newer` | Install clang 16+ and run `npx xbintsc doctor`; set `xbintsc_CLANG` to a specific clang if needed. |
-| The first build takes a long time | Expected: the runtime C sources are compiled and cached. Later builds reuse `.xbintsc/`; `--time` confirms. Use a release archive if cold builds must be fast. |
+| The first build takes a long time | The optional `@xbintsc/<os>-<arch>` package was skipped (or this host has no prebuilt package), so the runtime C sources are compiled and cached. Check `npm ls @xbintsc/<os>-<arch>` and reinstall without `--omit=optional`; `--time` confirms. |
 | Permission errors writing `.xbintsc/` | Set `xbintsc_CACHE_DIR` to a writable directory, or run from a writable working directory. |
 | `module 'fs' is provided by the 'node' extension` | Add `--ext node`, or `"extensions": ["node"]` in the config. |
-| `GUI native library not found` / `media native library not found` | The npm package does not ship `gui.a`/`gui.lib` or `media.a`/`media.lib`; use a Linux/macOS/Windows x64 release archive or build them from a source checkout. |
+| `GUI native library not found` / `media native library not found` | The optional platform package that ships `gui.a`/`gui.lib` or `media.a`/`media.lib` was skipped, or this host has no prebuilt GUI/media archive (Windows arm64). Reinstall without `--omit=optional`, use a Linux/macOS/Windows x64 release archive, or build the archive from a source checkout. |
 | `require("xbintsc")` fails | The package is ESM-only; use `import` (or dynamic `import()`). |
 | Windows link errors about missing MSVC libraries | Run from a Native Tools prompt, install the VS C++ build tools, and check `npx xbintsc doctor`. |
 | `npm ci --omit=dev` then the build cannot find `xbintsc` | Install devDependencies for the build stage, or move `xbintsc` to `dependencies`. |

package/doc/requirements.md

@@ -81,8 +81,12 @@ xbintsc-<os>-<arch>/
   runtime/               C runtime sources + prebuilt runtime/lib/<os>-<arch>/
 ```
 
-Windows archives omit the prebuilt `runtime/lib/`; the driver compiles the C
-runtime on demand with the user's clang.
+Every archive carries the prebuilt runtime for its host under
+`runtime/lib/<os>-<arch>/`: `core` and `ext_node` on all platforms (`.lib`
+instead of `.a` with the MSVC ABI on Windows), plus `gui`/`media` where the
+release builds them. The npm package receives the same archives from its
+optional `@xbintsc/<os>-<arch>` dependency, so an npm install does not compile
+the C runtime either.
 
 Unpack it, put `bin/` on `PATH` (or call `bin/xbintsc` directly), and install the
 toolchain for your platform below. Verify the download against the checksum

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

@@ -22,14 +22,48 @@ run();                                 // 驱动主循环，直到所有窗口
 `getHTML` / `setBackground` / `close` / `isOpen` / `on` / `off`，以及
 `driver()`——它报告当前使用的 SDL_GPU 后端（`"vulkan"`、`"direct3d12"`、
 `"metal"` 等，由 SDL 挑选设备支持的最佳后端）。同时也提供 Web 写法：
-`addEventListener` / `removeEventListener` 是 `on` / `off` 的别名（其
-`options` 参数会被接受并忽略），`closed` getter 对应 `isOpen()`，因此按浏览器
+`addEventListener` / `removeEventListener` 接受标准的选项对象（`capture`、
+`once`、`passive`、`signal`），`closed` getter 对应 `isOpen()`，因此按浏览器
 API 编写的文档可以原样运行。
 
+元素监听器支持同一组选项：`{ once }` 在首次调用后移除监听器，`{ passive: true }`
+使 `preventDefault()` 变成无操作，`{ signal }`（来自 `new AbortController()` 的
+`AbortSignal`）在 abort 时移除监听器，包括添加时就已经 abort 的信号。
+`element.dispatchEvent(event)` 派发的就是**同一个**事件对象（身份可观察），并填充
+`target` / `currentTarget` / `eventPhase`、记录路径供 `event.composedPath()` 使用。
+`new Event(...)`、`new CustomEvent(...)`、`new MouseEvent(...)`、
+`new KeyboardEvent(...)`、`new PointerEvent(...)`、`new WheelEvent(...)`、
+`new FocusEvent(...)`、`new InputEvent(...)` 与 `new SubmitEvent(...)` 会保留 `init`
+对象的全部字段（`detail`、`composed`、鼠标/键盘成员等）。窗口监听器接受同一组
+选项（`capture` 参与监听器身份匹配；窗口投递没有捕获阶段）。
+
+窗口导航是真实实现的：`scrollTo(x, y)` / `scrollTo({ left, top })` /
+`scrollBy(...)` 移动页面视口（会按内容边界夹取，绘制与命中测试随之偏移），
+`scrollX` / `scrollY` / `pageXOffset` / `pageYOffset` 报告偏移量。`focus()`
+提升操作系统窗口并置位 `document.hasFocus()`，`blur()` 清除它。事件：
+`ready`（首帧呈现后）、`load`、`close`、`resize`、`scroll`、`focus`、`blur`，
+以及输入事件 `mousemove`、`mousedown`、`mouseup`、`click`、`wheel`、
+`keydown`、`keyup`。
+
+`createWindow(options)` 除标题与尺寸外还支持：`{ title, width, height,
+highDensity, resizable, borderless, alwaysOnTop, hidden, fullscreen, x, y,
+opacity, maximized, minimized }`，它们会映射到对应的 SDL 窗口标志/调用，而不是
+被忽略。
+
+`window.confirm(message)` / `window.prompt(message, defaultValue)` 不会再丢弃
+参数：设置 `XT_GUI_DIALOGS=1` 且存在窗口时显示原生消息框；否则把消息写到 stderr
+并返回文档化的默认值（`confirm` → `false`，`prompt` → `defaultValue` 或 `""`）。
+
 在 Windows 上，GUI 程序会被链接为 **Windows 子系统**可执行文件，因此启动时不会闪出控制台
 窗口；这也意味着从资源管理器启动时 stdout/stderr 无处可去，调试时可在
 `xbintsc.config.json` 里设置 `app.console: true` 保留控制台子系统。
 
+没有可用 GPU 的宿主无法运行 GUI。当 SDL 无法打开视频驱动，或无法创建
+Metal/Vulkan/D3D12 设备时，引擎会打印原因并以状态码 **77** 退出——这是 autotools
+的“跳过”约定，CI 与脚本因此可以区分“这台机器没有 GUI”和“程序失败”。此后若窗口仍
+无法打开（SDL 窗口或 GPU claim 错误），`createWindow` 会抛出 JavaScript `Error`，
+而不再返回 `undefined` 句柄、让下一行以 `Cannot read properties of undefined` 失败。
+
 触发的事件：
 `ready`（首个呈现帧之后）、`load`、`close`、`resize`，以及输入事件
 `mousemove`、`mousedown`、`mouseup`、`click`、`wheel`、`keydown`、`keyup`。
@@ -53,12 +87,14 @@ requestAnimationFrame(frame);
 | `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` 等 | 事件构造器 |
+| `AudioContext`、`webkitAudioContext` | 带真实混音器与解码器的 Web Audio 图（见下） |
+| `Event`、`CustomEvent`、`ProgressEvent`、`MouseEvent`、`KeyboardEvent`、`PointerEvent`、`WheelEvent`、`FocusEvent`、`InputEvent`、`SubmitEvent` | 事件构造器；`init` 参数按原样保留（`detail`、`composed`、鼠标/键盘字段等） |
+| `AbortController`、`AbortSignal` | 真实的 controller/signal 对，用于 `{ signal }` 移除监听器，支持 `abort()`、`aborted`、`reason`、`onabort` 与 `throwIfAborted()` |
 | `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)）。 |
+| `ImageBitmap`、`createImageBitmap(source)` | 由已解码像素支撑的不可变位图（`<img>`、`<canvas>`、`<video>` 帧与 `ImageData` 形状）；promise 立即 settle，`texImage2D` 可直接接受该对象 |
+| `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))` 一致） |
+| `alert` / `confirm` / `prompt`、`matchMedia`、`getComputedStyle`、`escape` | 宿主实现。`matchMedia` 返回**实时**列表（按查询缓存）：`matches` 在窗口尺寸变化时重新求值，翻转时触发 `change` 监听器。`confirm`/`prompt` 仅在 `XT_GUI_DIALOGS=1` 时使用原生对话框，否则把消息写到 stderr 并返回文档化的默认值（Annex B `escape` 按 UTF-16 码元编码，与 `decodeURIComponent(escape(bytes))` 一致） |
 
 `getElementById` / `querySelector` 在 `loadHTML` 之前也能回答：此时得到的是**挂起**句柄，
 首次使用时才绑定到真实节点，因此在模块初始化阶段缓存 `document.querySelector("#id")`
@@ -66,15 +102,49 @@ requestAnimationFrame(frame);
 
 ### Web Audio
 
-`new AudioContext()` 会构建音频图，但**不做混音也不渲染音频**：背后没有后端。已实现的是
-页面运行与自检所需的接口 —— `createGain` / `createOscillator` / `createBufferSource` /
-`createBiquadFilter` / `createDynamicsCompressor` / `createBuffer`（真实的
-`Float32Array` 声道）/ `decodeAudioData`（以空缓冲区兑现）/ `resume` / `suspend` /
-`close`，`AudioParam` 的 `value` 与 `setValueAtTime` / `linearRampToValueAtTime` /
+`new AudioContext()` 会构建**真正参与混音的音频图**：`runtime/ext_gui/audio_mixer.cpp`
+以 48 kHz 立体声 float、128 帧为一个渲染量子进行混音，每个节点对多路输入求和；
+首次 `start()`/`resume()` 会尽力打开默认 SDL 播放设备（无头环境下保持静音但仍在渲染）。
+音频在 SDL 音频线程上基于原生状态渲染，页面无须自行驱动，音频线程也不会触碰任何运行时值。
+
+已实现的节点：`createGain`、`createOscillator`（sine、square、sawtooth、triangle）、
+`createBufferSource`（buffer、loop、loopStart/loopEnd、playbackRate/detune）、
+`createBiquadFilter`（lowpass、highpass、bandpass、lowshelf、highshelf、peaking、notch、allpass）、
+`createDynamicsCompressor`、`createStereoPanner`、`createConstantSource` 与
+`createDelay(maxDelayTime)`。`connect` 返回目标节点，因此可链式连接
+（`src.connect(gain).connect(ctx.destination)`）；`disconnect()` / `disconnect(target)`
+会更新原生图；`start(when, offset, duration)` / `stop(when)` 按图的时钟生效。
+列表之外的节点（`createAnalyser`、`createConvolver`、`createWaveShaper`、
+`createChannelSplitter`、`createPeriodicWave` 等）不提供，其方法就是缺失的。
+
+每个 `AudioParam` 都有实时 `value`，以及 `setValueAtTime` / `linearRampToValueAtTime` /
 `exponentialRampToValueAtTime` / `setTargetAtTime` / `cancelScheduledValues` /
-`cancelAndHoldAtTime`，节点 `connect`（返回目标节点，因此可链式连接）/ `disconnect` /
-`start` / `stop`。`sampleRate` 为 48000、`state` 为 `"running"`，`currentTime` 仅随
-事件循环推进。
+`cancelAndHoldAtTime`。自动化时间线**逐采样**求值，因此页面空闲时斜坡仍会继续推进；
+`currentTime` 随渲染量子前进。
+
+`createBuffer(channels, length, sampleRate)` 返回的 AudioBuffer 的
+`getChannelData(i)` 是真正的 `Float32Array`，可以用代码逐样本填充。
+`decodeAudioData(bytes)` 返回解码后的 AudioBuffer Promise：WAV（PCM 8/16/24/32 位、
+IEEE float 32/64、A-law 与 µ-law）由引擎自身解码；MP3、AAC/M4A、Vorbis、Opus 与 FLAC
+需要可选的 `media` 扩展（`--ext gui,media`），以其中的 FFmpeg 解码器作为回退。
+`bytes` 可以是 ArrayBuffer、类型化数组、Node `Buffer`，或 `fs.readFileSync`
+返回的原始字节字符串（本运行时没有专门的二进制类型，而该字符串的存储正是文件字节）。
+解码结果会重采样到上下文的 48 kHz，因此 `buffer.sampleRate` 与
+`context.sampleRate` 一致；若没有可用的解码器，Promise 会以 `EncodingError` 拒绝。
+
+`resume()` / `suspend()` / `close()` 控制设备与 `state` 属性；`sampleRate` 为 48000，
+与媒体解码器一致。
+
+测试与诊断可以创建**离线**上下文同步渲染：
+
+```ts
+const ctx = new AudioContext({ __offline: true });
+// … 构建音频图并启动音源 …
+const samples = ctx.__render(480);   // 交错立体声 Float32Array
+```
+
+这个私有钩子不会打开设备，也不属于 Web Audio API；`tests/e2e/gui-audio.test.ts`
+用它来固定混音数学。
 
 输入处理器接收单个负载对象（生命周期处理器不接收任何参数）：
 

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

@@ -52,10 +52,15 @@
   `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 上构建并运行
+  同一批目录还会打进可选的 `@xbintsc/<slug>` npm 包，因此发布覆盖的宿主平台从
+  npm 安装后也能使用 `--ext gui`/`--ext media`。归档在 Linux（Xvfb 下，使用
+  lavapipe 软件 Vulkan 驱动）与 macOS 上构建并运行
   示例；Windows x64 也会构建两个归档并链接一个 `gui,media` 程序，因此 MSVC
   构建在 CI 中得到验证，只是*运行*示例仍为试验性（托管 runner 没有 GPU/Vulkan
-  驱动）。Windows arm64 仍跳过两个归档（FFmpeg 的 MSVC arm64 构建尚未验证）。
+  驱动）。macOS 的运行同样是试验性的：Intel runner 的虚拟 GPU 缺少
+  `MTLGPUFamilyMac2`，引擎会以 **77**（“此机器无法运行 GUI”）退出，任务记录为跳过，
+  而不是去编译一套无法呈现的测试。Windows arm64 仍跳过两个归档（FFmpeg 的
+  MSVC arm64 构建尚未验证）。
 - Windows CI 通过 `.github/actions/vs-toolchain` →
   `scripts/setup-vs-toolchain.ps1` 使用与本地构建相同的 Visual Studio
   `vcvarsall` 环境和自带的 LLVM（不再单独安装 Chocolatey LLVM）。媒体构建时该

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

@@ -31,12 +31,19 @@ const ctx = canvas.getContext("2d"); // 或 "webgl" 取得 GPU 上下文
 元素上，因此每次都返回**同一个**对象，绘制状态（变换、样式、路径）按 canvas 而非按调用
 保存。`ctx.canvas` 是所属元素的句柄。
 
+`getContext("2d", attributes)` 在首次调用时会尊重 `alpha`：传入 `{ alpha: false }`
+时位图以不透明黑色初始化（清除也回到不透明黑）。其余属性由
+`getContextAttributes()` 按规范默认值报告（`antialias: true`、`depth: true`、
+`stencil: false`、`premultipliedAlpha: true`、`preserveDrawingBuffer: false`、
+`colorSpace: "srgb"` 等），特性探测因此能得到诚实的答案。
+
 ## 绘制模型
 
 光栅器刻意保持精简且为自研（不依赖 Skia/Cairo）。它按每条像素行 **4 条垂直子扫描线**
-进行抗锯齿，并做一次**水平解析覆盖率**计算；路径采用**非零环绕规则**填充（因此当弧线
-以相反方向环绕时能形成空洞）。轴对齐矩形（变换中 `b == 0 && c == 0`）走直接的覆盖率
-快速路径。混合为非预乘 source-over，并按 `globalAlpha` 缩放。
+进行抗锯齿，并做一次**水平解析覆盖率**计算；路径默认采用**非零环绕规则**填充（因此当弧线
+以相反方向环绕时能形成空洞），`fill("evenodd")` 则改用奇偶规则。轴对齐矩形（变换中
+`b == 0 && c == 0`）走直接的覆盖率快速路径。混合为非预乘 source-over，并按
+`globalAlpha` 缩放。
 
 填充或描边可以使用纯色，也可以使用 **`CanvasGradient`**。渐变的坐标属于用户空间，
 因此光栅器会先用当前变换的逆矩阵把每个设备像素映射回用户空间再采样——形状被平移、
@@ -50,9 +57,11 @@ Canvas 像素**不参与垃圾回收**：canvas 由窗口拥有、以 DOM 节点
 ## 支持的 API
 
 状态与变换：`save` / `restore`（会恢复变换、线宽、透明度、字体/文本设置**以及**
-填充/描边样式）、`translate`、`rotate`、`scale`、`transform(a,b,c,d,e,f)`、
-`setTransform`、`resetTransform`、`getTransform`（返回带 `a`…`f` 与 `is2D` 的对象）。
-变换按 canvas 的顺序组合：`translate(x, y); rotate(a)` 围绕平移后的原点旋转。
+填充/描边样式）、`translate`、`rotate`、`scale`、`transform(a,b,c,d,e,f)` /
+`transform(matrix)`、`setTransform(a,b,c,d,e,f)` / `setTransform(matrix)`、
+`resetTransform`、`getTransform`（返回带 `a`…`f` 与 `is2D` 的对象）。矩阵可以是
+`{ a, b, c, d, e, f }` 对象或六元素数组。变换按 canvas 的顺序组合：
+`translate(x, y); rotate(a)` 围绕平移后的原点旋转。
 
 样式与设置：`fillStyle` / `strokeStyle`（层叠所用的颜色解析器能识别的 CSS 颜色，或
 `CanvasGradient`）、`lineWidth`、`globalAlpha`、`lineCap`（`butt`/`round`/`square`）、
@@ -70,20 +79,27 @@ Canvas 像素**不参与垃圾回收**：canvas 由窗口拥有、以 DOM 节点
 会忽略 `x0`/`y0`——请使用同心圆（`x0 == x1`、`y0 == y1`）。
 
 路径：`beginPath`、`closePath`、`moveTo`、`lineTo`、`rect`、`roundRect`、`arc`、
-`ellipse`、`quadraticCurveTo`、`bezierCurveTo`，然后 `fill`（多环、非零环绕）或
-`stroke`。贝塞尔与二次曲线段会被展平为线段；弧线与椭圆同样被展平。`roundRect` 只接受
-单个圆角半径数字（数组形式尚未实现）。
+`ellipse`、`quadraticCurveTo`、`bezierCurveTo`，然后
+`fill(fillRule?)` / `fill(path, fillRule?)`（多环；`"nonzero"` 或 `"evenodd"`）或
+`stroke(path?)`。贝塞尔与二次曲线段会被展平为线段；弧线与椭圆同样被展平。
+`roundRect` 接受单个半径数字，或 CSS 半径列表（`[all]`、`[tl, br]`、
+`[tl, tr, br]`、`[tl, tr, br, bl]`，元素为数字或 `{ x, y }` 对；圆角按圆弧绘制）。
+
+`Path2D` 支持同一组路径命令（`moveTo`、`lineTo`、`closePath`、`rect`、
+`roundRect`、`arc`、`ellipse`、`quadraticCurveTo`、`bezierCurveTo`、`addPath`），
+并可传给 `fill`/`stroke`，因此一次构建的路径可以在不同变换下重复使用。
 
 矩形：`clearRect`、`fillRect`、`strokeRect`。
 
 虚线：`setLineDash(segments)` / `getLineDash()` / `lineDashOffset` 实现标准规则
 （奇数长度列表会复制一遍，负数/非有限值会被忽略，全零列表表示实线）。
 
-文本：`measureText(text)`（返回 `{ width }`）、`fillText(text, x, y)` 与
-`strokeText(text, x, y)`。文本经 HarfBuzz 排版、FreeType 光栅化（与 HTML 文本相同的
-技术栈），按变换的近似缩放绘制。**仅支持平移与均匀缩放**——旋转或斜切变换仍会把每个
-字形放到其变换后的基线点，但不会旋转字形位图。`strokeText` 目前用描边样式执行填充，
-而非生成轮廓。
+文本：`measureText(text)`（返回 `{ width }`）、`fillText(text, x, y, maxWidth?)` 与
+`strokeText(text, x, y, maxWidth?)`。文本经 HarfBuzz 排版、FreeType 光栅化（与 HTML
+文本相同的技术栈），按变换的近似缩放绘制。正的 `maxWidth` 会按比例压缩步进与字形位图，
+使文本宽度不超过该值（与 canvas API 一致），而不是忽略该参数。**仅支持平移与均匀
+缩放**——旋转或斜切变换仍会把每个字形放到其变换后的基线点，但不会旋转字形位图。
+`strokeText` 目前用描边样式执行填充，而非生成轮廓。
 
 图像：`drawImage(source, …)` 支持 3 参数（`dx, dy`）、5 参数（`dx, dy, dw, dh`）与
 9 参数（本引擎为**目标优先**：`dx, dy, dw, dh, sx, sy, sw, sh`）。完整的仿射变换
@@ -95,12 +111,21 @@ Canvas 像素**不参与垃圾回收**：canvas 由窗口拥有、以 DOM 节点
 测试钩子：`getImageData(x, y, w, h)` 把区域复制为 `{ width, height, data }`，其中
 `data` 是按行主序的 RGBA8 字节数组。越界像素为透明。
 
+图案：`createPattern(source, repetition?)` 接受 `<img>` 或另一个 `<canvas>`，在用户
+空间中平铺（`repeat`、`repeat-x`、`repeat-y`、`no-repeat`），因此平铺会跟随当前
+变换。把结果赋给 `fillStyle`/`strokeStyle`；重新赋颜色会替换掉图案。
+
+图像数据与导出：`createImageData(width, height)` 分配一个空的
+`{ width, height, data }`，`putImageData(imageData, dx, dy[, dirtyX, dirtyY,
+dirtyWidth, dirtyHeight])` 直接把字节写入位图（不受变换、混合或 `globalAlpha`
+影响）。`canvas.toDataURL(type?)` 导出 PNG data URL，`canvas.toBlob(callback,
+type?)` 从微任务中交付 Blob 形状的 `{ type, size }`（字节在
+`__xt_gui_blob_data` 上；本运行时没有 `URL.createObjectURL`）。
+
 ## 尚未实现
 
-图案（`createPattern`）、阴影、`clip()`、`globalCompositeOperation`、
-`putImageData`、`createImageData`、`isPointInPath`、以 `DOMMatrix` 调用的
-`setTransform`、可切换图像平滑的 `drawImage`、`toDataURL`/`toBlob`、把 `<canvas>` 用作
-CSS `background-image`，以及离屏画布（`OffscreenCanvas`、
-`transferControlToOffscreen`）。`roundRect` 只接受单个半径，径向渐变会忽略内圆偏移。
+阴影、`clip()`、`globalCompositeOperation`、`isPointInPath`、可切换图像平滑的
+`drawImage`、把 `<canvas>` 用作 CSS `background-image`，以及离屏画布
+（`OffscreenCanvas`、`transferControlToOffscreen`）。径向渐变会忽略内圆偏移。
 
 另见[媒体](./media.md)：`drawImage` 与纹理上传所共享的图像/视频/音频解码栈。

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

@@ -14,7 +14,9 @@ doctype 跳过，实体解码（命名 + 十进制/十六进制），空元素
 
 **CSS 解析器**（`runtime/ext_gui/css.{h,cpp}`）：会剥离注释；`@media` 块递归解析
 （嵌套查询用 `and` 合并，逗号列表会分配到内层查询），其他 at-rule 跳过。规则支持
-多选择器与声明。选择器：类型、`.class`、`#id`、属性
+多选择器与声明；选择器列表可以跨任意多行书写（换行就是普通空白，换行后的
+组合器仍按组合器处理），引号内的属性值即使包含逗号、方括号或圆括号也不会
+拆开列表。选择器：类型、`.class`、`#id`、属性
 （`=`、`~=`、`|=`、`^=`、`$=`、`*=`）、四种组合器（后代、子、相邻兄弟与
 通用兄弟）、伪类 `:first-child`、`:last-child`、`:only-child`、`:empty`、
 `:root`、`:not(...)`、`:nth-child(an+b)`、`:disabled`、`:checked`、有状态的
@@ -66,17 +68,59 @@ created.textContent = "added";
 box.appendChild(created);
 box.removeChild(created);
 
+// 父子变更辅助方法可在同一次调用中混用节点与字符串。
+box.append("text", doc.createElement("span"));
+box.prepend(doc.createElement("b"));
+box.insertAdjacentHTML("beforeend", "<i>tail</i>"); // beforebegin/afterbegin/beforeend/afterend
+box.replaceChildren("fresh", doc.createElement("em"));
+
+// 命名空间会被记录；外部（SVG）元素名保留大小写。
+const gradient = doc.createElementNS("http://www.w3.org/2000/svg", "svg:linearGradient");
+console.log(gradient.namespaceURI, gradient.localName, gradient.prefix);
+
 inner.addEventListener("click", (e) => console.log(e.target.id, e.currentTarget.id));
 inner.click();                          // 在该元素处合成一次点击
 console.log(box.offsetWidth, box.offsetHeight);   // 取整后的边框盒
 console.log(box.contains(inner));                 // 后代判断
 ```
 
+### style 属性、dataset、计算样式与几何
+
+内联 `style` 对象是一个 CSSOM 声明块。以属性名赋值/读取的是与 `setProperty`
+相同的声明块（`el.style.display = "none"`、`el.style.backgroundColor = "#f00"`，
+驼峰名会映射到 CSS 拼写，`el.style["--accent"]` 用于自定义属性）；
+`setProperty(name, value, priority)` 在 `priority` 为 `"important"` 时以
+`!important` 保存该声明（其他优先级值会让本次调用成为无操作，空值则移除该属性）。
+`getPropertyValue` / `getPropertyPriority` 读回声明，`removeProperty` 返回旧值，
+`cssText` 读取或整体替换声明块，`style.length` / `style.item(i)` 枚举声明块，
+未设置的属性返回 `""`。
+
+`el.dataset` 是元素 `data-*` 属性之上的实时 `DOMStringMap`：
+`dataset.fooBar` 读取 `data-foo-bar`，赋值写入属性，`delete` 移除属性，
+`Object.keys(dataset)` / `for...in` 只列出 data 键。
+
+`getComputedStyle(el, pseudoElt)` 从**层叠结果**读取——UA 样式表、作者规则、
+继承和内联声明——而不是回显内联块，因此写在样式表里的规则同样可见。它支持
+`getPropertyValue`、`getPropertyPriority` 与命名属性（`cs.width`、
+`cs.backgroundColor`、`cs["--accent"]`）。传入 `"::before"` 或 `"::after"`
+可读取生成内容盒；其他伪元素返回空值。每次读取都会先结算待处理的重新样式，
+因此早先创建的句柄在后续变更后仍然有效。
+
+`getBoundingClientRect()` 在 `x` / `y` / `width` / `height` 之外还带有旧式的
+`top` / `right` / `bottom` / `left` 成员；`document.title = …` 写入文档的
+`<title>`（页面没有该元素时会创建它以及 `<head>`）。
+
 变更操作会把文档标记为脏；引擎会延迟地（在下一次读取或下一帧之前）重新计算
 样式并重新布局。`inner = …`/`innerHTML = …` **不会**执行脚本。元素事件支持
-捕获与冒泡阶段、`stopPropagation`、`once`，并向上冒泡到 `document`/`window`。
-旧式 `win.on(type, fn)` 负载保留其**字符串** `e.target`（`div#id.class`）；
-元素 `Event.target` 是一个句柄，其描述符与同一字符串匹配。
+捕获与冒泡阶段、`stopPropagation`、`once`、`passive` 与 `signal`（`AbortController`
+的信号会在 abort 时移除监听器），并向上冒泡到 `document`/`window`。
+`dispatchEvent` 派发同一个事件对象，并填充 `target`/`currentTarget`/`eventPhase`/
+`composedPath()`。旧式 `win.on(type, fn)` 负载保留其**字符串** `e.target`
+（`div#id.class`）；元素 `Event.target` 是一个句柄，其描述符与同一字符串匹配。
+
+`element.focus()` 会把元素滚动到可见区域（传入 `{ preventScroll: true }` 则保持
+当前页面偏移）；`document.hasFocus()` 报告由 `window.focus()` / `window.blur()`
+切换的窗口焦点状态。
 
 ### 节点生命周期
 

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

@@ -91,6 +91,9 @@ Windows 已不再特殊：`media.lib` 是用 clang-cl 为 MSVC ABI 编译的 FFm
   `media.a`/`media.lib` 只依赖 FFmpeg。
 - **线程。** 引擎是单线程且非线程感知，因此所有解码都在主线程的
   `xt_gui_media_tick` 内完成——没有解码线程，也没有跨线程 GC 暴露。
+- **`decodeAudioData`。** 同一套 FFmpeg 还会为 `AudioContext.decodeAudioData`
+  解码内存中的音频文件（`runtime/ext_media/decode_audio.cpp`，经媒体表分发）；
+  WAV 由 GUI 引擎自身处理（`audio_decode.cpp`），因此只有压缩格式需要该扩展。
 - **DOM API。** 元素句柄直接暴露媒体接口（见
   `runtime/ext_gui/dom_api_media.cpp` 与 `dom_api_proto.cpp` 中的原型）：
   `play()` / `pause()` / `load()`，以及 `paused` / `ended` / `duration` /