xbintsc 0.5.31 → 0.5.32

package/doc/gui/webgl.md

@@ -0,0 +1,256 @@
+# WebGL (a `<canvas>` drawn on the GPU)
+
+> Part of the [GUI extension](../gui.md); the engine overview, locked
+> decisions and roadmap live there.
+
+A `<canvas>` can ask for a WebGL context instead of the 2D one:
+
+```ts
+const canvas: any = document.getElementById("scene");
+const gl: any = canvas.getContext("webgl2"); // or "webgl" / "experimental-webgl"
+if (gl == null) {
+  // no GPU backend that can consume WebGL's shaders on this platform
+}
+```
+
+Unlike the 2D context, which rasterises into a CPU bitmap and uploads it as a
+texture, a WebGL context **renders on the GPU**: vertex transform, lighting,
+texture sampling, depth testing and blending all execute in the SDL_GPU
+pipeline (Vulkan on Windows/Linux, Metal on macOS). The page composites the
+context's colour texture directly, so no pixels are read back to the CPU for
+display.
+
+Both **WebGL 1.0** and **WebGL 2.0** are available. A canvas keeps the first
+context kind it asks for: after `getContext("webgl2")` a later
+`getContext("webgl")` answers `null`, and the other way round. A WebGL 2 context
+also satisfies `instanceof WebGLRenderingContext` (its prototype inherits the
+WebGL 1 one) and adds the WebGL 2 constants and methods.
+
+## How a frame reaches the screen
+
+- Each context owns one offscreen `R8G8B8A8_UNORM` colour texture (the drawing
+  buffer) and a `D32_FLOAT` depth texture, sized from the canvas's `width` /
+  `height` attributes. `canvas.width = …` recreates them and discards the
+  contents, like the DOM rule.
+- The context records into its own SDL_GPU command buffer. `clear`/`draw*`
+  keep a render pass open; a buffer/texture upload or a framebuffer change ends
+  it and starts a new pass with `LOAD`, so the drawing buffer persists between
+  draws just like WebGL's.
+- Once per frame, before the page's own render pass, the engine submits every
+  WebGL command buffer. The image pipeline then samples the colour texture as
+  an ordinary `PaintImage`, with no CPU copy.
+- WebGL's origin is bottom-left while SDL_GPU render targets are top-left, so
+  the framebuffer is stored top-down: `viewport`/`scissor` are converted,
+  `readPixels` flips rows back, and the compositor sees an upright texture.
+- A fixed-function state change (`blendFunc`, `depthFunc`, `cullFace`,
+  `colorMask`, …) changes which `SDL_GPUGraphicsPipeline` is needed, so
+  pipelines are created lazily per (program, vertex layout, state) and cached on
+  the program.
+
+## Shaders: GLSL ES to SPIR-V (and on to MSL)
+
+SDL_GPU cannot compile GLSL at run time, and each backend consumes its own
+format, so the engine ships two statically linked translators:
+
+- **glslang** compiles the rewritten GLSL to SPIR-V, which the Vulkan backend
+  consumes directly;
+- **SPIRV-Cross** cross-compiles that same SPIR-V to Metal Shading Language text,
+  which the Metal backend compiles at run time.
+
+Both live in `gui.a` / `gui.lib`; the Metal path reuses the SPIR-V module rather
+than growing a second GLSL front end, so both backends accept exactly the same
+shader subset. The path is:
+
+1. `shaderSource` stores the GLSL ES text; `compileShader` translates it once
+   for `COMPILE_STATUS` / `getShaderInfoLog`.
+2. `linkProgram` translates both stages again with one shared attribute and
+   varying location map, compiles them with glslang, and then creates the
+   `SDL_GPUShader` objects: from the SPIR-V on Vulkan, or from the MSL text
+   SPIRV-Cross produced on Metal.
+3. The generated SPIR-V is reflected to obtain the exact std140 offsets, array
+   strides and matrix strides of the uniform block — the shader text may size an
+   array with a macro, but glslang has already resolved it. SPIRV-Cross keeps
+   those offsets in the MSL struct, so one uniform layout serves both backends.
+
+The translator (`runtime/ext_gui/webgl_glsl*.cpp`) handles GLSL ES 1.00 and
+3.00 sources:
+
+| WebGL spelling | Rewritten to |
+| --- | --- |
+| `attribute vec3 a_pos` | `layout(location = N) in vec3 a_pos` |
+| `varying vec2 v_uv` | `layout(location = N) out/in vec2 v_uv` (one shared name → location map) |
+| `gl_FragColor` | `layout(location = 0) out highp vec4 xt_FragColor` |
+| `texture2D`, `textureCube`, `texture2DProj` | `texture`, `texture`, `textureProj` |
+| `texture2DLodEXT` / `textureCubeLodEXT` | `textureLod` |
+| non-sampler uniforms | one `layout(std140) uniform XtUniforms { … }` block |
+| `uniform sampler2D u_tex` | `layout(set = 2, binding = N) uniform sampler2D u_tex` (fragment) or set 0 (vertex) |
+| `gl_FragData[0]` | `xt_FragColor` |
+| a missing `#version` / `#version 100` | `#version 310 es` |
+
+Non-sampler uniforms are merged across both stages and emitted as one block in
+each stage (set 1 for the vertex shader, set 3 for the fragment shader), which
+matches SDL_GPU's Vulkan descriptor layout. On Metal the same declarations
+become `[[buffer(0)]]` and `[[texture(N)]]`/`[[sampler(N)]]`, the slots SDL_GPU's
+Metal backend binds. `uniformMatrix4fv` writes column-major floats into the
+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
+`#ifdef` is fine; non-sampler uniform declarations are moved to the enclosing
+top-level position so the block stays unconditional.
+
+### GLSL ES 3.00 (WebGL 2)
+
+A `#version 300 es` source is accepted as-is apart from the version bump:
+top-level `in`/`out` declarations become attributes/varyings, a named fragment
+output (`out vec4 fragColor;`) becomes an `xt_FragColor`-style output, and
+`texture()` / `textureLod()` already match the Vulkan dialect. Multiple fragment
+outputs are given sequential locations, but the render pass has one colour
+target, so only the first is written. `gl_VertexID` and `gl_InstanceID` are
+available from GLSL ES 3.00, which is what the instanced example uses.
+
+## Supported API
+
+- **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).
+- **Shaders and programs**: `createShader`, `shaderSource`, `compileShader`,
+  `getShaderParameter`, `getShaderInfoLog`, `getShaderSource`, `deleteShader`,
+  `createProgram`, `attachShader`, `detachShader`, `linkProgram`,
+  `getProgramParameter`, `getProgramInfoLog`, `getAttachedShaders`,
+  `validateProgram`, `deleteProgram`, `useProgram`,
+  `getActiveUniform`/`getActiveAttrib`, `getUniformLocation`,
+  `getAttribLocation`, `bindAttribLocation`.
+- **Uniforms**: `uniform1f`…`uniform4f`, `uniform1i`…`uniform4i`,
+  `uniform1fv`…`uniform4fv`, `uniform1iv`…`uniform4iv`,
+  `uniformMatrix2fv`/`3fv`/`4fv`, `getUniform`.
+- **Buffers and attributes**: `createBuffer`, `bindBuffer`, `bufferData`,
+  `bufferSubData`, `deleteBuffer`, `getBufferParameter`,
+  `enableVertexAttribArray`, `disableVertexAttribArray`,
+  `vertexAttribPointer`, `vertexAttrib1f`…`4f` / `1fv`…`4fv`,
+  `getVertexAttrib`.
+- **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
+  matching SDL primitive.
+- **Textures**: `createTexture`, `bindTexture`, `activeTexture`,
+  `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.
+- **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`.
+- **Readback**: `readPixels` (RGBA/UNSIGNED_BYTE) from the default framebuffer
+  or a bound framebuffer. It blocks until the GPU finishes; use it for tests and
+  screenshots, not per frame.
+
+WebGL 2 adds:
+
+- **Vertex-array objects**: `createVertexArray`, `bindVertexArray`,
+  `deleteVertexArray`, `isVertexArray`. SDL_GPU has no VAO, so binding one
+  restores a saved copy of the attribute table and its element buffer.
+- **Instancing**: `drawArraysInstanced`, `drawElementsInstanced`,
+  `drawRangeElements`, `vertexAttribDivisor`. A divisor of 1 maps to SDL's
+  per-instance vertex input rate; SDL 3.2 reserves larger step rates, so a
+  divisor above 1 is clamped to 1.
+- **Integer attributes and uniforms**: `vertexAttribIPointer`, the
+  `vertexAttribI4*` family, `uniform1ui`…`uniform4ui`.
+- **Sampler objects**: `createSampler`, `bindSampler`, `deleteSampler`,
+  `samplerParameteri/f`, `getSamplerParameter`; a bound sampler overrides the
+  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`.
+- **Clears**: `clearBufferfv`, `clearBufferiv`, `clearBufferuiv`,
+  `clearBufferfi`.
+- **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.
+
+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.
+
+## 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.
+
+## Platform
+
+The pipeline is created with the shader format the SDL_GPU device accepts:
+**SPIR-V** (`SDL_GPU_SHADERFORMAT_SPIRV`) on Vulkan, which is what Windows and
+Linux select, or **MSL** (`SDL_GPU_SHADERFORMAT_MSL`) on Metal, which macOS
+selects. Both backends go through the same GLSL front end, so a shader that
+compiles on one compiles on the other. On a device whose backend accepts neither
+format — Direct3D 12, which would need DXIL — `getContext("webgl")` and
+`getContext("webgl2")` both answer `null`; the 2D canvas and the rest of the page
+still work.
+
+glslang and SPIRV-Cross are fetched and built by `npm run gui` and merged into
+`gui.a` / `gui.lib` (see [Packaging and build](./build.md)); a program that only
+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.
+- `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`.
+- `examples/gui/webgl2-cubes` draws 64 instanced cubes with one draw call,
+  `#version 300 es` and a VAO; covered by
+  `tests/e2e/gui-example-webgl2.test.ts`.
+
+These suites run against whichever backend the host selects: Vulkan on Linux
+(and Windows), Metal on macOS, so the SPIRV-Cross -> MSL path is covered by the
+same assertions as the SPIR-V one.
+
+## three.js
+
+The `.js` asset loader only patches three.js's shader unroller; `WebGLRenderer`
+runs unchanged on this engine's real WebGL 2 backend, so **no Canvas2D fallback
+is bundled any more**. Verified with three.js r160 through SDL_GPU:
+`MeshBasicMaterial`, `MeshStandardMaterial` and `MeshPhongMaterial`,
+`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.

package/doc/gui.md

@@ -1,6 +1,6 @@
 # xbintsc GUI extension (self-hosted HTML/CSS renderer)
 
-Status: **M16** — features (M1–M15) are complete: HTML parsing, CSS selector
+Status: **M19** — features (M1–M15) are complete: HTML parsing, CSS selector
 matching, the cascade, computed styles and layout (block, inline, Flexbox and
 CSS positioning) are
 in place, and the engine *paints*: it builds a display list of rectangles, images
@@ -35,6 +35,12 @@ them) can be translated, scaled and rotated without reflowing anything — and
 `transition: transform`, so those poses animate. See
 [Layout](./gui/layout.md#transforms-m15) and
 [Animation](./gui/animation.md#css-transforms-m15).
+**M17** adds real **WebGL 1.0**, and **M18** adds **WebGL 2.0**: `<canvas>.getContext("webgl2")` accepts `#version 300 es` shaders, vertex-array objects, instanced draws and sampler objects, all compiled to SPIR-V by the bundled glslang (and to MSL by the bundled SPIRV-Cross on Metal) and rendered through SDL_GPU. Geometry, lighting, texture sampling and blending run on the GPU and the page composites the colour texture without a readback — see [WebGL](./gui/webgl.md).
+**M19** fills in the decorative CSS layer: `@media` queries, generated content
+(`::before`/`::after`), multi-layer linear/radial backgrounds, `text-shadow`,
+`clip-path` and the `filter` colour/shadow effects. `backdrop-filter` and true
+group blur need an offscreen compositor and remain documented approximations or
+unsupported — see [Rendering](./gui/rendering.md#backgrounds-generated-content-and-effects-m19).
 This overview records the locked decisions, the architecture, the milestone plan
 and the current progress; the engine itself is documented by function in the
 pages above.
@@ -174,21 +180,27 @@ engine were Rust.
    - **M6b — transitions/animations** ✅ `transition` shorthand + longhands,
      animated `background-color`/`color`/`border-color`/`border-radius`, retargeting
      and `win.advance(ms)`. `@keyframes` remain.
-7. **M7 — CI & releases** ✅ (Linux/macOS build) / 🚧 (run + Windows)
+7. **M7 — CI & releases** ✅ (Linux/macOS/Windows x64 build) / 🚧 (run + Windows arm64)
    - `compile-examples` builds `gui.a` and `media.a` on Linux and macOS
      (required), then runs the examples and `tests/e2e/gui-*.test.ts` under
      Xvfb + lavapipe on Linux (required). The macOS run is provisional until a
      WindowServer is confirmed; it is guarded so a failure is logged without
      annotating the run.
-   - The `package` job builds `gui.a` and `media.a` before assembling the
-     release, so both ship inside the existing runtime archive
-     (`package-release` copies all of `runtime/`).
-   - `vendor/` (SDL3/FreeType/HarfBuzz for `gui.a`, FFmpeg for `media.a`) is
-     cached per OS/arch, keyed by `scripts/build-gui.ts` / `scripts/build-media.ts`.
-   - Windows (build + run) stays provisional in CI: the MSVC-compatible
-     `gui.lib` builds and runs locally through SDL_GPU's Vulkan backend, but the
-     hosted runners have no GPU/Vulkan driver. A failure is logged without
-     annotating the run (see [Open questions](./gui/known-issues.md#open-questions)).
+   - 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.
+   - `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
+     installed `vendor/ffmpeg-build-msvc/dist` prefix.
+   - Windows x64 builds both archives in CI and links a `gui,media` program,
+     using the same Visual Studio `vcvarsall` + bundled LLVM toolchain as a
+     local build (`.github/actions/vs-toolchain`); the host has no GPU/Vulkan
+     driver, so *running* the GUI/media examples there remains provisional (a
+     failure is logged without annotating the run). The Windows arm64 job still
+     skips both archives (see
+     [Open questions](./gui/known-issues.md#open-questions)).
 8. **M8 — interactive DOM** ✅
    - Element/document handles with stable identity, read/write properties via
      runtime accessors, traversal/attributes/queries, mutation with lazy
@@ -277,6 +289,54 @@ engine were Rust.
       NanoSVG cache as an SVG file (`svg.{h,cpp}`); the markup cache is bounded
       and a DOM mutation re-serializes on the next layout. e2e in
       `tests/e2e/gui-inline-svg.test.ts`.
+17. **M17 — WebGL** ✅
+    - `canvas.getContext("webgl")` creates a real GPU context
+      (`webgl.{h,cpp}`): an offscreen RGBA8 colour texture plus a depth texture,
+      its own SDL_GPU command buffer, and pipelines created lazily from the
+      program, vertex layout and fixed-function state. The page composites the
+      colour texture through the existing image path, with no CPU readback.
+    - `webgl_glsl*.cpp` rewrites GLSL ES 1.00/3.00 to Vulkan GLSL ES 3.10
+      (attribute/varying locations, `gl_FragColor`, `texture2D`, one std140
+      uniform block per stage, explicit sampler bindings), compiles it with a
+      statically bundled glslang, reflects the SPIR-V for uniform offsets, and
+      on Metal cross-compiles that same module to MSL with the bundled
+      SPIRV-Cross (`webgl_msl.cpp`).
+    - `dom_api_webgl*.cpp` exposes the WebGL 1.0 surface, including textures,
+      mipmaps, render-to-texture framebuffers and `readPixels`. See
+      [WebGL](./gui/webgl.md); e2e in `tests/e2e/gui-webgl.test.ts` and
+      `tests/e2e/gui-example-webgl.test.ts`, demo in
+      `examples/gui/webgl-cube`.
+18. **M18 — WebGL 2** ✅
+    - `canvas.getContext("webgl2")` returns a context whose prototype extends
+      the WebGL 1 one, with the WebGL 2 constants and methods.
+    - GLSL ES 3.00 sources (`#version 300 es`, `in`/`out`, named fragment
+      outputs, `gl_InstanceID`) compile through the same rewriter.
+    - Vertex-array objects save/restore the attribute table, instanced draws use
+      SDL's per-instance input rate, and sampler objects override a texture
+      unit's filter/wrap state. `texStorage2D`, `copyBufferSubData`,
+      `getBufferSubData` and `clearBuffer*` are implemented; query/fence/UBO and
+      transform-feedback entry points exist and degrade gracefully. See
+      [WebGL](./gui/webgl.md); e2e in `tests/e2e/gui-webgl2.test.ts` and
+      `tests/e2e/gui-example-webgl2.test.ts`, demo in
+      `examples/gui/webgl2-cubes`.
+19. **M19 — decorative CSS** ✅
+    - `@media` blocks are parsed recursively and evaluated against the viewport
+      (width/height ranges, orientation, hover/pointer and preference features);
+      `matchMedia()` uses the same evaluator.
+    - Generated content: `::before`/`::after` selectors, inherited pseudo styles,
+      `content` strings/escapes/`attr()`, and synthetic layout boxes that never
+      leak into DOM traversal.
+    - Multi-layer `background-image` with linear and radial gradients, painted
+      bottom-up as solid bands (18 strips / 32 concentric ellipses).
+    - `text-shadow` as shadow text runs, including a nine-tap blur approximate.
+    - `clip-path` polygons (`inset`/`circle`/`ellipse`/`polygon`) resolved to
+      device space, ear-clipped and intersected with shape geometry in
+      `renderer_clip.cpp` — no stencil/shader change.
+    - `filter` colour functions, nine-tap `blur()` and silhouette
+      `drop-shadow()`; `backdrop-filter` parses and cascades but needs an
+      offscreen backdrop pass (see [Known issues](./gui/known-issues.md)).
+    - E2E coverage in `tests/e2e/gui-effects.test.ts`; see
+      [Rendering](./gui/rendering.md#backgrounds-generated-content-and-effects-m19).
 
 ## Progress log
 
@@ -306,11 +366,12 @@ engine were Rust.
   pixel size and cached by that size, so scaling and HiDPI stay crisp.
 - **M6b** ✅ CSS transitions (parsing in `style.*`, an animation clock and
   transition state in `document.*`, `advance`/`advance(ms)` hooks, e2e coverage).
-- **M7** ✅ builds `gui.a` (and the optional `media.a`) in CI on Linux and macOS
-  (required) and runs the example plus the GUI e2e suite under Xvfb on Linux;
-  `package` ships both archives, `vendor/` is cached, and the `ar -M` merge
-  works on GNU/Linux and macOS. macOS runs and all of Windows remain provisional
-  in CI.
+- **M7** ✅ builds `gui.a`/`gui.lib` and `media.a`/`media.lib` in CI on Linux,
+  macOS and Windows x64 (required) and runs the example plus the GUI e2e suite
+  under Xvfb on Linux; `package` ships the archives (Windows x64 included),
+  `vendor/` is cached, and the `ar -M` merge works on GNU/Linux, macOS and
+  COFF/Windows. macOS runs, the Windows example *run* and Windows arm64 remain
+  provisional in CI.
 - **M8** ✅ element/document handles (`dom_api.*`), DOM mutation with lazy
   restyle/relayout (`document.*`, `xt_gui_flush_dom`), element event dispatch
   with capture/bubble and `stopPropagation` (`dom_api.*`, `gui.cpp`), and e2e
@@ -347,7 +408,8 @@ engine were Rust.
   every frame now runs in constant memory (see [Memory & GC](./gui/runtime.md#memory--gc)).
 - **M13** ✅ `<video>` / `<audio>` support. The optional `media` extension
   vendors and builds a minimal static FFmpeg (`scripts/build-media.ts`) and
-  merges it into `media.a`; `runtime/ext_media/media.cpp` decodes video to RGBA
+  merges it into `media.a` (or `media.lib` from clang-cl/MSVC objects on
+  Windows); `runtime/ext_media/media.cpp` decodes video to RGBA
   frames and audio to 48 kHz stereo PCM on the main thread,
   `runtime/ext_gui/gui_media.cpp` owns the players, implements the SDL audio
   sink and pumps the media clock and events each frame,
@@ -393,4 +455,33 @@ engine were Rust.
   NanoSVG cache (`svg.{h,cpp}`, bounded LRU for markup). The `win.inlineSvg`
   diagnostic exposes the serialized document, and `tests/e2e/gui-inline-svg.test.ts`
   pins sizing, hit testing, gradients, CSS box styling and mutation.
+- **M17** ✅ WebGL. `xtgui::WebGLContext` (`webgl.{h,cpp}`) owns the offscreen
+  colour/depth targets and the command buffer, `webgl_buffer/texture/draw/shader`
+  implement the GL object model, `webgl_glsl*.cpp` translate GLSL ES to SPIR-V
+  with the bundled glslang (`webgl_msl.cpp`/SPIRV-Cross turn that module into
+  MSL on Metal), and `dom_api_webgl*.cpp` bind the WebGL 1.0 API.
+  `renderer_image.cpp` returns the context's colour texture for a canvas id, so
+  the page composites GPU output directly. Demo: `examples/gui/webgl-cube`;
+  e2e: `tests/e2e/gui-webgl.test.ts`, `tests/e2e/gui-example-webgl.test.ts`.
+- **M18** ✅ WebGL 2. `webgl2_proto()` extends the WebGL 1 prototype with the
+  WebGL 2 constants/methods; `webgl_webgl2.cpp` implements vertex-array objects
+  and sampler/query/sync handles, `webgl_draw.cpp` adds instanced draws (input
+  rate from `vertexAttribDivisor`) and integer attributes, and
+  `webgl_texture.cpp` adds `texStorage2D` and `clearBuffer*`. The shader
+  rewriter gives `#version 300 es` outputs sequential locations, and the block
+  reflection flattens struct fields for three.js lights. three.js r160 runs on
+  the real renderer (basic/standard/Phong materials, textures, lights, fog,
+  sprites, lines, points and instancing); the Canvas2D fallback was removed.
+  Demo: `examples/gui/webgl2-cubes` (64 cubes, one instanced draw call);
+  e2e: `tests/e2e/gui-webgl2.test.ts`, `tests/e2e/gui-example-webgl2.test.ts`.
+- **M19** ✅ decorative CSS. `css_sheet.cpp` now parses nested `@media` blocks and
+  `media_query.cpp` evaluates them (and `matchMedia`) against the viewport;
+  `css_selector.cpp` understands `::before`/`::after`. `style.cpp` computes
+  pseudo styles into a per-restyle arena, resolves `content`, and layout inserts
+  their boxes before/after the DOM children. `gradient_values.cpp` models a
+  background layer list (linear/radial, shape/size/position/stops),
+  `paint_background.cpp` paints it, `paint_effects.cpp` applies filter colour
+  functions plus nine-tap blur/drop-shadow and emits `text-shadow` runs, and
+  `paint_clip.cpp`/`renderer_clip.cpp` clip geometry against triangulated
+  `clip-path` polygons. E2E: `tests/e2e/gui-effects.test.ts`.
 

package/doc/npm-package.md

@@ -358,8 +358,10 @@ jobs:
   cannot poison a new build.
 - xbintsc builds for the **host** platform. It is not a cross-compiler: use a CI
   matrix (one job per OS/arch) to produce artifacts for several platforms.
-- macOS runners already have Xcode Command Line Tools; Windows runners need
-  LLVM and the MSVC build tools, and the binary is `build\main.exe`.
+- macOS runners already have Xcode Command Line Tools; Windows runners need the
+  Visual Studio C++ build tools (MSVC + its bundled LLVM), and the binary is
+  `build\main.exe`. In a source checkout,
+  `pwsh -File scripts/setup-vs-toolchain.ps1` imports that toolchain explicitly.
 
 ## npm package or release archive?
 
@@ -367,7 +369,7 @@ jobs:
 | --- | --- | --- |
 | 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 archives |
+| GUI / media extensions | Not included | 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 |
@@ -409,7 +411,7 @@ the same file under `node_modules/xbintsc/doc/ai/`.
 | 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. |
 | 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`/`media.a`; use a Linux/macOS release archive or build them from a source checkout. |
+| `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. |
 | `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

@@ -124,22 +124,26 @@ Verify with `clang --version`. If xbintsc uses the wrong linker, set
 `xbintsc_CLANG` to the clang you want and/or pass extra flags through
 `xbintsc_LINKER_ARGS` (for example `-fuse-ld=lld`).
 
-## Windows — install the MSVC C++ build tools (and LLVM)
+## Windows — install the MSVC C++ build tools (with LLVM)
 
-xbintsc targets the **MSVC ABI** on Windows. Install the Visual Studio C++
-build tools plus LLVM with `winget`:
+xbintsc targets the **MSVC ABI** on Windows. One `winget` command installs the
+Visual Studio C++ workload, MSBuild and the Clang component that the local build
+scripts and CI use:
 
 ```powershell
-winget install -e --id LLVM.LLVM
 winget install -e --id Microsoft.VisualStudio.2022.BuildTools `
-  --override "--quiet --wait --add Microsoft.VisualStudio.Workload.VCTools --includeRecommended"
+  --override "--quiet --wait --add Microsoft.VisualStudio.Workload.VCTools --add Microsoft.VisualStudio.Component.VC.Llvm.Clang --includeRecommended"
 ```
 
 The LLVM bundled with Visual Studio 2022
-(`VC\Tools\Llvm\x64\bin\clang.exe`, version 19.1.5 in current installs) is
-enough, and so is a standalone LLVM. Either way the compiler must target the
-MSVC ABI (`Target: *-windows-msvc`): clang built for another Windows ABI cannot
-link with the MSVC runtime, so `xbintsc` rejects it with an explicit error.
+(`VC\Tools\Llvm\x64\bin\clang.exe`, version 19.1.5 in current installs) is what
+`scripts/setup-vs-toolchain.ps1` selects. A standalone LLVM also works for
+`xbintsc` itself (`winget install -e --id LLVM.LLVM`), but the GUI/media archive
+builds and the CI setup use the Visual Studio one so one toolchain produces the
+runtime, the archives and the final binary. Either way the compiler must target
+the MSVC ABI (`Target: *-windows-msvc`): clang built for another Windows ABI
+cannot link with the MSVC runtime, so `xbintsc` rejects it with an explicit
+error.
 
 A developer prompt is normally **not** required: `xbintsc` resolves the Visual
 Studio LLVM by absolute path, and that clang locates the MSVC/SDK headers,
@@ -151,6 +155,11 @@ imported, run the build from an **x64 Native Tools Command Prompt for VS 2022**
 & "$env:ProgramFiles\Microsoft Visual Studio\2022\BuildTools\VC\Auxiliary\Build\vcvarsall.bat" x64
 ```
 
+In a source checkout, `pwsh -File scripts/setup-vs-toolchain.ps1` does the same
+and also pins `xbintsc_CLANG` to the LLVM bundled with that Visual Studio
+installation. CI calls the same script, so a local build, the release archives
+and CI use one Visual Studio toolchain.
+
 Verify with `xbintsc doctor` (or `clang --version`); the report names the
 resolved compiler, its version and its target.
 

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

@@ -55,7 +55,8 @@ requestAnimationFrame(frame);
 | `localStorage` | 内存中的 `getItem` / `setItem` / `removeItem` / `clear` / `key` / `length` |
 | `AudioContext`、`webkitAudioContext` | Web Audio 图构建器（见下） |
 | `Event`、`CustomEvent`、`ProgressEvent` 等 | 事件构造器 |
-| `HTMLCanvasElement`、`HTMLImageElement`、`ImageBitmap`、`ImageData`、`OffscreenCanvas`、`WebGL*`、`XRWebGL*`、`Request`、`Headers`、`Response`、`ReadableStream`、`DOMParser` | `typeof` 探测返回 `"undefined"`（引擎没有 WebGL、XR、fetch 或流式后端），让页面走自己的“不支持”分支，而不是调用空壳 |
+| `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))` 一致） |
 
@@ -133,4 +134,4 @@ win.stats()                            // 引擎/运行时计数器（内存排
 
 多窗口由对象模型自然得出：`createWindow` 返回一个原生对象句柄；每个句柄
 拥有自己的 `SDL_Window`/GPU 表面与自己的 DOM 树。`run()` 驱动一个共享主循环，
-它每帧 tick 所有窗口，并在最后一个窗口关闭时退出。
+它每帧 tick 所有窗口，并在最后一个窗口关闭时退出。