xbintsc 0.5.32 → 0.5.36

package/doc/gui/dom.md

@@ -14,9 +14,12 @@ close rules (`li`, `dt`/`dd`, `option`, `p`, headings, table cells/rows).
 **CSS parser** (`runtime/ext_gui/css.{h,cpp}`): comments are stripped; `@media`
 blocks are parsed recursively (nested queries combine with `and`, and a comma
 list distributes over the inner query) while other at-rules are skipped. Rules
-support multiple selectors and declarations. Selectors: type, `.class`, `#id`,
-attribute (`=`, `~=`, `|=`, `^=`, `$=`, `*=`), the four combinators
-(descendant, child, adjacent and general sibling), the pseudo-classes
+support multiple selectors and declarations; a selector list may be formatted
+across any number of lines (line breaks are ordinary whitespace, so a wrapped
+combinator stays a combinator), and a quoted attribute value may contain
+commas, brackets or parentheses without splitting the list. Selectors: type,
+`.class`, `#id`, attribute (`=`, `~=`, `|=`, `^=`, `$=`, `*=`), the four
+combinators (descendant, child, adjacent and general sibling), the pseudo-classes
 `:first-child`, `:last-child`, `:only-child`, `:empty`, `:root`, `:not(...)`,
 `:nth-child(an+b)`, `:disabled`, `:checked`, plus the stateful `:hover` and
 `:focus` (see [Input](./input.md)), and the pseudo-elements `::before`/`::after`

package/doc/gui/media.md

@@ -112,6 +112,10 @@ platform media framework in the path either way.
 - **Threading.** The engine is single-threaded and not thread-aware, so all
   decoding happens on the main thread inside `xt_gui_media_tick` — no decode
   thread, no cross-thread GC exposure.
+- **`decodeAudioData`.** The same FFmpeg build also decodes an in-memory audio
+  file for `AudioContext.decodeAudioData` (`runtime/ext_media/decode_audio.cpp`,
+  through the media table); WAV is handled by the GUI engine itself
+  (`audio_decode.cpp`), so only compressed formats need this extension.
 - **DOM API.** Element handles expose the media surface directly (see
   `runtime/ext_gui/dom_api_media.cpp` and the prototype in
   `dom_api_proto.cpp`): `play()` / `pause()` / `load()`, and the

package/doc/gui/webgl.md

@@ -96,8 +96,7 @@ reflected offsets; `uniform1i` on a sampler stores the texture unit. The block
 is pushed with the dynamic uniform-buffer API on every draw.
 
 Limits of the translator: struct-typed uniforms, user uniform blocks, uniform
-arrays whose size is not resolved by the preprocessor, sampler arrays and cube
-maps are rejected (the link/shader info log says so). Shader code inside
+arrays whose size is not resolved by the preprocessor, sampler arrays are rejected (the link/shader info log says so). Shader code inside
 `#ifdef` is fine; non-sampler uniform declarations are moved to the enclosing
 top-level position so the block stays unconditional.
 
@@ -115,8 +114,11 @@ available from GLSL ES 3.00, which is what the instanced example uses.
 
 - **Context**: `getContext("webgl")`, `canvas`, `drawingBufferWidth/Height`,
   `getParameter`, `getError`, `getSupportedExtensions`, `getExtension`,
-  `getContextAttributes`, `isContextLost`, `getShaderPrecisionFormat`, and the
-  stencil entry points (accepted; the depth target has no stencil attachment).
+  `getContextAttributes`, `isContextLost`, `getShaderPrecisionFormat`, and an
+  8-bit stencil buffer (`getContextAttributes().stencil` is `true`,
+  `STENCIL_BITS` is 8). `WEBGL_lose_context`'s `loseContext`/`restoreContext`
+  really drop and rebuild the context (every object becomes invalid) and
+  dispatch `webglcontextlost`/`webglcontextrestored`.
 - **Shaders and programs**: `createShader`, `shaderSource`, `compileShader`,
   `getShaderParameter`, `getShaderInfoLog`, `getShaderSource`, `deleteShader`,
   `createProgram`, `attachShader`, `detachShader`, `linkProgram`,
@@ -131,7 +133,9 @@ available from GLSL ES 3.00, which is what the instanced example uses.
   `bufferSubData`, `deleteBuffer`, `getBufferParameter`,
   `enableVertexAttribArray`, `disableVertexAttribArray`,
   `vertexAttribPointer`, `vertexAttrib1f`…`4f` / `1fv`…`4fv`,
-  `getVertexAttrib`.
+  `getVertexAttrib`. The `usage` hint from `bufferData`
+  (`STREAM_DRAW`/`STATIC_DRAW`/`DYNAMIC_DRAW`) is recorded and reported by
+  `getBufferParameter(…, BUFFER_USAGE)`.
 - **Drawing**: `drawArrays`, `drawElements` (UNSIGNED_BYTE, UNSIGNED_SHORT,
   UNSIGNED_INT; `TRIANGLE_FAN` and `LINE_LOOP` are expanded to lists).
   `POINTS`, `LINES`, `LINE_STRIP`, `TRIANGLES` and `TRIANGLE_STRIP` map to the
@@ -140,22 +144,50 @@ available from GLSL ES 3.00, which is what the instanced example uses.
   `texParameteri`/`texParameterf`, `getTexParameter`, `texImage2D` (raw pixels,
   `<img>`, `<canvas>` and `ImageData` sources), `texSubImage2D`,
   `generateMipmap`, `deleteTexture`. `UNPACK_FLIP_Y_WEBGL` and
-  `UNPACK_PREMULTIPLY_ALPHA_WEBGL` are honoured. Everything is converted to
-  RGBA8; `RGBA`, `RGB`, `LUMINANCE`, `ALPHA` and `LUMINANCE_ALPHA` with
-  `UNSIGNED_BYTE` are accepted.
-- **Framebuffers**: `createFramebuffer`, `bindFramebuffer`,
-  `framebufferTexture2D` (colour attachment), `checkFramebufferStatus`,
-  `createRenderbuffer`, `bindRenderbuffer`, `renderbufferStorage` (depth),
-  `framebufferRenderbuffer`, `delete*`. This is enough for render-to-texture,
-  shadow maps and post-processing passes.
+  `UNPACK_PREMULTIPLY_ALPHA_WEBGL` are honoured. By default source data is
+  converted to RGBA8; `RGBA`, `RGB`, `LUMINANCE`, `ALPHA` and
+  `LUMINANCE_ALPHA` with `UNSIGNED_BYTE` are accepted. Float textures
+  (`RGBA32F`, `RGBA16F`, `RGB32F`, `RGB16F`, `RG32F`/`RG16F`, `R32F`/`R16F`
+  with `FLOAT` or `HALF_FLOAT` data, plus WebGL 1's
+  `OES_texture_float`/`OES_texture_half_float`) map to SDL's RGBA32F/RGBA16F,
+  and depth textures (`DEPTH_COMPONENT16/24/32F`, `DEPTH_STENCIL`,
+  `DEPTH24_STENCIL8`) map to `D32_FLOAT`/`D32_FLOAT_S8_UINT` and can be sampled
+  or used as depth attachments. Compressed textures upload through
+  `compressedTexImage2D`/`compressedTexSubImage2D` with
+  `WEBGL_compressed_texture_s3tc` (BC1/BC2/BC3),
+  `WEBGL_compressed_texture_s3tc_srgb` and `WEBGL_compressed_texture_astc`;
+  each extension is published only when the device can sample its formats.
+  `texImage2D` also accepts the latest decoded `<video>` frame and an
+  `ImageBitmap` produced by `createImageBitmap`. Cube maps
+  (`bindTexture(TEXTURE_CUBE_MAP)` plus six `texImage2D` faces) and 3D/array
+  textures (`texImage3D`/`texStorage3D`) are sampled through `samplerCube`,
+  `sampler3D` and `sampler2DArray`; `texSubImage3D` updates a sub-volume and
+  `framebufferTextureLayer` renders one array/cube layer as a colour
+  attachment.
+- **Framebuffers**: `createFramebuffer`, `bindFramebuffer`
+  (`FRAMEBUFFER`/`READ_FRAMEBUFFER`/`DRAW_FRAMEBUFFER`),
+  `framebufferTexture2D` (`COLOR_ATTACHMENT0`, `DEPTH_ATTACHMENT`,
+  `DEPTH_STENCIL_ATTACHMENT`), `checkFramebufferStatus`, `createRenderbuffer`,
+  `bindRenderbuffer`, `renderbufferStorage` (depth or depth-stencil),
+  `framebufferRenderbuffer`, `delete*`, and `blitFramebuffer` (colour
+  attachment; depth/stencil bits are accepted but not copied). This is enough
+  for render-to-texture, shadow maps and post-processing passes.
 - **State**: `enable`/`disable`/`isEnabled` for `BLEND`, `DEPTH_TEST`,
-  `CULL_FACE`, `SCISSOR_TEST` (stencil accepted but not applied),
-  `clearColor`/`clearDepth`/`clearStencil`, `clear`, `blendFunc`/
-  `blendFuncSeparate`, `blendEquation`/`blendEquationSeparate`, `depthFunc`,
-  `depthMask`, `colorMask`, `cullFace`, `frontFace`, `viewport`, `scissor`,
-  `pixelStorei`, `finish`.
+  `CULL_FACE`, `SCISSOR_TEST` and `STENCIL_TEST`,
+  `clearColor`/`clearDepth`/`clearStencil`, `clear` (with `SCISSOR_TEST` it
+  clears only the scissor rectangle, for colour, depth and stencil), `blendColor`,
+  `blendFunc`/`blendFuncSeparate`,
+  `blendEquation`/`blendEquationSeparate`, `depthFunc`,
+  `depthMask`, `colorMask`, `stencilFunc`/`stencilFuncSeparate`,
+  `stencilOp`/`stencilOpSeparate`, `stencilMask`/`stencilMaskSeparate`,
+  `cullFace`, `frontFace`, `viewport`, `scissor`,
+  `pixelStorei`, `finish`. The stencil test takes part in rasterisation and
+  `clear(STENCIL_BUFFER_BIT)` clears the stencil attachment; SDL_GPU exposes
+  one reference and one compare/write mask for both faces, so a front/back
+  pair that differs uses the front value.
 - **Readback**: `readPixels` (RGBA/UNSIGNED_BYTE) from the default framebuffer
-  or a bound framebuffer. It blocks until the GPU finishes; use it for tests and
+  or a bound RGBA8 framebuffer; a float/depth attachment is sampled into an
+  RGBA8 target first. It blocks until the GPU finishes; use it for tests and
   screenshots, not per frame.
 
 WebGL 2 adds:
@@ -174,38 +206,46 @@ WebGL 2 adds:
   texture's own filter/wrap state for that unit.
 - **Immutable textures and buffer copies**: `texStorage2D` (the backend always
   allocates the full mip chain), `copyBufferSubData`, `getBufferSubData`.
+- **Drawing buffer**: `drawingBufferStorage(width, height)` fixes the drawing
+  buffer size; `canvas.width`/`canvas.height` no longer rebuild it afterwards.
 - **Clears**: `clearBufferfv`, `clearBufferiv`, `clearBufferuiv`,
   `clearBufferfi`.
+- **Multiple render targets**: `drawBuffers` addresses up to four colour
+  attachments and `readBuffer` selects the attachment `readPixels` reads;
+  `framebufferTexture2D` accepts `COLOR_ATTACHMENT0`…`3`, and a fragment
+  shader's multiple `out` variables are written in order.
 - **Queries and fences**: the objects and entry points exist
   (`createQuery`/`beginQuery`/`endQuery`/`getQueryParameter`,
   `fenceSync`/`clientWaitSync`/`waitSync`/`getSyncParameter`) and degrade
   gracefully: a fence reports `ALREADY_SIGNALED` and query results are 0.
-- **Uniform blocks**: `getUniformBlockIndex` answers `INVALID_INDEX` so a
-  library falls back to individual uniforms; the block entry points are no-ops.
-- **Transform feedback, 3D textures and compressed formats**: the entry points
-  are present as no-ops so feature-probing libraries do not throw.
+- **Uniform blocks**: `getUniformBlockIndex`,
+  `getActiveUniformBlockParameter`, `getActiveUniformBlockName`,
+  `uniformBlockBinding`, `bindBufferBase`/`bindBufferRange` and
+  `getIndexedParameter`. Members are merged into the engine's single std140
+  block and copied from the bound buffer at draw time; scalars, vectors,
+  matrices and fixed-size arrays work, nested structs, sampler members and
+  blocks without an instance name are rejected.
+- **Transform feedback**: the entry points are present as no-ops so
+  feature-probing libraries do not throw.
 
 Textures are created with a full mip chain; sampling clamps to level 0 until
 `generateMipmap` runs. Matrix vertex attributes consume the right number of
 consecutive locations and read one column per location. A disabled attribute
 is supplied from the last `vertexAttrib*f` value through a small constant
-buffer.
+buffer. A vertex shader can sample textures just like a fragment shader:
+`MAX_VERTEX_TEXTURE_IMAGE_UNITS` reports 16, vertex samplers live in set 0 and
+are bound with `SDL_BindGPUVertexSamplers` on every draw. Depth values use the
+backend's `[0, 1]` clip space rather than GL's `[-1, 1] → [0, 1]` remap:
+`gl_Position.z = 0.5` stores depth `0.5` (real WebGL stores `0.75`).
 
 ## Not implemented
 
-Uniform buffer objects in shader source, transform feedback (the entry points
-are no-ops), cube maps, 3D/array textures, float/half textures, depth textures,
-compressed textures, multiple render targets (only the first fragment output is
-written), `blitFramebuffer`, MSAA/sample buffers, stencil operations (state is
-accepted, the stencil buffer is not written), constant blend colours,
-`drawingBufferStorage`, context loss, `bufferData` with a `usage` other than
-static/dynamic (the hint is ignored), `texImage2D` for
-`HTMLVideoElement`/`ImageBitmap` and scissored `clear` (a clear clears the whole
-attachment). Shaders that use built-in blocks, user uniform blocks or
-`gl_FragDepth` beyond the supported subset are rejected with a compile/link log.
-
-The engine advertises zero vertex texture units, so a well-behaved WebGL 1
-program will not try to sample a texture in a vertex shader.
+Transform feedback (the entry points are no-ops) and MSAA/sample buffers
+(SDL_GPU's Metal multisample resolve returns undefined pixels with scissor
+tests and instanced draws, so contexts stay single-sampled). `blitFramebuffer`
+copies the colour attachment only; depth/stencil bits are accepted but not
+copied. Shaders that use built-in blocks or `gl_FragDepth` are rejected with a
+compile/link log.
 
 ## Platform
 
@@ -225,10 +265,27 @@ uses the 2D canvas or the DOM pays no run-time cost beyond the archive size.
 ## Testing
 
 - `tests/e2e/gui-webgl.test.ts` compiles GLSL, draws a textured and a
-  depth-tested quad, checks face culling and reads the pixels back.
-- `tests/e2e/gui-webgl2.test.ts` covers the WebGL 2 additions: `#version 300 es`
-  shaders, a VAO round trip, instanced draws with a divisor, `texStorage2D`,
-  `clearBufferfv`, buffer copies, sampler objects and struct-uniform fields.
+  depth-tested quad, checks face culling and reads the pixels back; it also
+  covers blend constants, dynamic buffer usage, vertex-shader texture sampling,
+  `gl_FragDepth` diagnostics, context loss/restore and cube maps.
+- `tests/e2e/gui-webgl2.test.ts` covers the WebGL 2 shader/state additions:
+  `#version 300 es` shaders, a VAO round trip, instanced draws with a divisor,
+  `texStorage2D`, `clearBufferfv`, buffer copies, sampler objects, struct-uniform
+  fields and `drawingBufferStorage`.
+- `tests/e2e/gui-webgl2-formats.test.ts` covers stencil, float/depth textures,
+  compressed textures and `ImageBitmap`.
+- `tests/e2e/gui-webgl2-blit.test.ts` covers scissored colour/depth clears,
+  framebuffer blits, and the pixels around a partial blit that must survive
+  (a destination load-op that discards them fails there on Metal).
+- `tests/e2e/gui-media.test.ts` also uploads the latest decoded `<video>` frame
+  as a texture and reads it back.
+- `tests/e2e/gui-webgl2-3d.test.ts` covers 2D-array and 3D texture layer
+  sampling, `texSubImage3D` sub-volume updates and rendering to a colour
+  attachment layer.
+- `tests/e2e/gui-webgl2-mrt.test.ts` writes two fragment outputs to two
+  colour attachments and reads each back.
+- `tests/e2e/gui-webgl2-ubo.test.ts` binds a std140 block, updates its members
+  and verifies the drawn colour.
 - `examples/gui/webgl-cube` is a spinning, lit, textured cube; it runs in a
   browser unchanged and is covered by
   `tests/e2e/gui-example-webgl.test.ts`.
@@ -249,8 +306,10 @@ is bundled any more**. Verified with three.js r160 through SDL_GPU:
 `CanvasTexture`, linear fog, ambient/directional/point/spot/hemisphere lights,
 `Sprite`, `Line`, `Points` and `InstancedMesh`.
 
-Features outside this engine's subset still cannot be emulated: shadow maps
-(depth textures), cube textures/environment maps, HDR/float render targets,
-multiple render targets, transform feedback and compressed textures. A scene
-that needs one of those will not render correctly; everything the previous
-Canvas2D fallback could show now goes through the GPU.
+Features outside this engine's subset still cannot be emulated: transform
+feedback and MSAA.
+Depth textures, float render targets and compressed textures are available, but
+three.js shadow maps still need comparative `sampler2DShadow` sampling, which
+is not translated yet. A scene that needs one of those will not render
+correctly; everything the previous Canvas2D fallback could show now goes
+through the GPU.

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

@@ -30,6 +30,12 @@ API 编写的文档可以原样运行。
 窗口；这也意味着从资源管理器启动时 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,10 +59,11 @@ 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 图构建器（见下） |
+| `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)）。 |
+| `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))` 一致） |
 
@@ -66,15 +73,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/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`、有状态的

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` /