xbintsc 0.5.31 → 0.5.32

package/doc/gui/build.md

@@ -8,8 +8,14 @@
   `runtime/ext_media/` and is built separately.
 - `npm run gui` (`scripts/build-gui.ts`) fetches a pinned SDL3 (`SDL3_TAG`,
   default `release-3.2.10`), builds a static SDL3, fetches and builds static
-  FreeType (`FREETYPE_VERSION`) and HarfBuzz (`HARFBUZZ_VERSION`), compiles the
-  engine and merges everything into `runtime/lib/<os>-<arch>/gui.a` (or
+  FreeType (`FREETYPE_VERSION`) and HarfBuzz (`HARFBUZZ_VERSION`), and fetches
+  and builds static **glslang** (`GLSLANG_VERSION`, default `16.6.0`) against
+  the pinned SPIR-V headers (`SPIRV_HEADERS_VERSION`), and **SPIRV-Cross**
+  (`SPIRV_CROSS_VERSION`, default `vulkan-sdk-1.4.313.0`). glslang is the
+  runtime GLSL ES compiler behind WebGL and SPIRV-Cross turns its SPIR-V into
+  MSL for the Metal backend (see [WebGL](./webgl.md)); both are merged into the
+  archive like the other libraries. The script then compiles the engine and
+  merges everything into `runtime/lib/<os>-<arch>/gui.a` (or
   `gui.lib` with the MSVC ABI on Windows), same convention as `core.a`,
   statically bundling all three. The merge uses `libtool` on macOS and
   `ar -M` (GNU/LLVM) elsewhere; CMake archives are discovered under the build
@@ -18,12 +24,13 @@
   backend. It fetches FFmpeg (`FFMPEG_VERSION`, default `7.1`), configures a
   minimal static build with only the demuxers/parsers/decoders the media
   elements need, compiles `runtime/ext_media/media.cpp` against it and merges
-  everything into `runtime/lib/<os>-<arch>/media.a`. `gui.a` does **not** link
-  FFmpeg: a program enables playback explicitly with `--ext media`.
+  everything into `runtime/lib/<os>-<arch>/media.a` (`media.lib` with the MSVC
+  ABI on Windows). `gui.a` does **not** link FFmpeg: a program enables playback
+  explicitly with `--ext media`.
 - `src/extensions/gui/index.ts` exposes the engine archive through
   `nativeObjects()` (via `findRuntimeLibrary`, so `.a`/`.lib` both work) and the
   OS frameworks through `linkerFlags()`. `src/extensions/media/index.ts` does
-  the same for `media.a` and compiles the registration bridge
+  the same for `media.a`/`media.lib` and compiles the registration bridge
   (`runtime/ext_media/media_bridge.c`) as a normal runtime source.
 - `scripts/build-gui.ts` compiles with the *same* clang the driver resolves
   (`src/driver/toolchain-provider.ts`); on Windows that is the MSVC-targeting
@@ -32,14 +39,39 @@
   fallbacks, and Windows always uses `llvm-ar`, so the archive cannot mix object
   formats or C++ runtimes. The Visual Studio toolchain is found by absolute
   path, so no developer prompt is required. On Windows SDL_GPU selects the
-  Vulkan backend; no DXIL/`dxc` toolchain is needed. `scripts/build-media.ts`
-  uses the same resolved toolchain for FFmpeg and the player.
-- CI builds `gui.a` and `media.a` before assembling the release archive so they
-  ship inside `runtime/lib/<slug>/` (the release tarball copies the whole
-  `runtime/` tree). The archives are built and the examples are run on Linux
-  (under Xvfb, with the lavapipe software Vulkan driver) and macOS; Windows is
-  provisional because the hosted runners have no GPU/Vulkan driver, and the
-  media archive is POSIX-only.
+  Vulkan backend; no DXIL/`dxc` toolchain is needed.
+- `scripts/build-media.ts` uses the same resolved toolchain. On Windows it
+  drives FFmpeg's own MSVC mode: `configure --toolchain=msvc --cc=clang-cl`
+  compiles static FFmpeg against the static MSVC CRT, `clang++` compiles the
+  player, and `llvm-ar` merges the COFF archives into `media.lib`. The compiler
+  chain is entirely Visual Studio (clang-cl, `cl.exe`, `lib.exe`, `llvm-ar`).
+  FFmpeg's configure is a POSIX shell script and its
+  Makefiles need GNU make, so those two build drivers remain: the shell is Git
+  for Windows' bundled bash (Git is already required to clone SDL3), and make is
+  a native GNU make such as Chocolatey's `make` (or `xbintsc_MAKE`). The script
+  rewrites the generated source path to a drive-letter form and skips dependency
+  extraction, which native make cannot pass through the MSVC `/showIncludes` awk
+  pipeline. The MSVC tools are only needed by configure's toolchain probe; they
+  are resolved from the Visual Studio installation, not from a developer prompt.
+  `xbintsc_SHELL` and `xbintsc_MAKE` override the discovered shell/make. Headers
+  and libraries are copied into `vendor/ffmpeg-build-msvc/dist` by the script
+  rather than through `make install`.
+- CI builds `gui.a`/`gui.lib` and `media.a`/`media.lib` before assembling the
+  release archive so they ship inside `runtime/lib/<slug>/` (the release tarball
+  copies the whole `runtime/` tree). The archives are built and the examples are
+  run on Linux (under Xvfb, with the lavapipe software Vulkan driver) and macOS;
+  the Windows x64 job builds both archives and links a `gui,media` program, so
+  the MSVC build is validated even though *running* the examples there stays
+  provisional (the hosted runner has no GPU/Vulkan driver). Windows arm64 still
+  skips both archives: FFmpeg's MSVC arm64 build is not validated yet.
+- The Windows CI steps call `.github/actions/vs-toolchain` →
+  `scripts/setup-vs-toolchain.ps1`, which imports the same Visual Studio
+  `vcvarsall` environment and bundled LLVM a local build uses (no separate
+  Chocolatey LLVM). For the media build the action also installs GNU make
+  through Chocolatey and points `xbintsc_MAKE` at it; the FFmpeg source and the
+  installed `vendor/ffmpeg-build-msvc/dist` prefix are cached by script hash.
+  The configure/make tree itself is not cached (absolute paths and compiler
+  options from another machine).
 - The existing cache fingerprint already hashes `nativeObjects()` contents and
   `runtimeSources()` content, so rebuilding either archive invalidates cached
   binaries automatically.
@@ -65,6 +97,28 @@ npm run media        # optional: build media.a (fetches and builds FFmpeg once)
 xbintsc run examples/gui/hello.ts --ext gui
 ```
 
+On Windows the same commands produce `gui.lib` and `media.lib` from a normal
+PowerShell — no developer command prompt. The Visual Studio installation
+supplies the MSVC-targeting `clang++`, `clang-cl`, `cl.exe` and `lib.exe`, and
+`npm run media` additionally needs a POSIX shell and GNU make for FFmpeg's
+`configure`: Git for Windows supplies the shell (and is already needed to clone
+SDL3), while GNU make is a native binary — install it with `choco install make`,
+or point `xbintsc_MAKE` at one. The script reports whichever tool is missing and
+accepts `xbintsc_SHELL` / `xbintsc_MAKE` overrides.
+
+To select that toolchain explicitly (useful in a fresh shell or to pin the same
+compiler CI uses), run:
+
+```powershell
+pwsh -File scripts/setup-vs-toolchain.ps1
+```
+
+It imports `vcvarsall` (MSVC, Windows SDK, MSBuild) and points `xbintsc_CLANG`
+at the LLVM bundled with that Visual Studio installation. GitHub Actions uses
+the same script through `.github/actions/vs-toolchain`, so no separate
+Chocolatey/standalone LLVM is installed there and CI, local builds and the
+prebuilt archives share one compiler chain.
+
 Two examples live here: `hello.ts` (HTML/CSS + a reactive counter) and
 [`pelican-bike/`](../../examples/gui/pelican-bike), a playable 2D game that uses
 positioned layers, CSS sprites, `requestAnimationFrame` and keyboard input — see
@@ -82,11 +136,13 @@ which the e2e test (`tests/e2e/gui-*.test.ts`) uses to run headlessly.
 
 Those suites are skipped on Windows by default (the archive is built and runs
 locally through Vulkan, but CI runners have no GPU driver to run it). With a
-`gui.lib` and a working GPU, opt in with `xbintsc_GUI_TESTS=1`:
+`gui.lib` and a working GPU, opt in with `xbintsc_GUI_TESTS=1`; if you also ran
+`npm run media`, the media suite then exercises the real decoder on Windows too:
 
 ```bat
 set xbintsc_GUI_TESTS=1
 npx vitest run tests/e2e/gui-layout.test.ts tests/e2e/gui-example.test.ts
+npx vitest run tests/e2e/gui-media.test.ts
 ```
 
 On a headless Linux box, install the SDL3 build headers and run under Xvfb with a
@@ -101,8 +157,8 @@ xvfb-run -a --server-args="-screen 0 1280x720x24" \
 ```
 
 The media e2e suite (`tests/e2e/gui-media.test.ts`) skips itself unless both
-`gui.a` and `media.a` exist; `tests/e2e/gui-media-disabled.test.ts` covers the
-GUI-only build and runs with `gui.a` alone.
+`gui.a`/`gui.lib` and `media.a`/`media.lib` exist; `tests/e2e/gui-media-disabled.test.ts`
+covers the GUI-only build and runs with the GUI archive alone.
 
 `scripts/install-gui-deps.sh` holds the package list (`apt-get install -y clang
 cmake libx11-dev libxext-dev libxrandr-dev libxcursor-dev libxi-dev

package/doc/gui/canvas.md

@@ -23,9 +23,14 @@ state parsing in `canvas_style.cpp`; the DOM bindings live in
 
 ```ts
 const canvas: any = document.getElementById("c");
-const ctx = canvas.getContext("2d"); // or null for any other context kind
+const ctx = canvas.getContext("2d"); // or "webgl" for a GPU context
 ```
 
+A canvas has one context kind. `getContext("webgl")` or `getContext("webgl2")`
+returns a WebGL context (see [WebGL](./webgl.md)); once a canvas has a 2D context,
+asking for either WebGL kind answers `null`, and vice versa. A canvas that never
+asked for a context stays transparent.
+
 `getContext("2d")` returns a context handle whose methods and accessors live on
 a shared prototype. The handle is cached on the element, so every call returns
 the **same** object and the drawing state (transform, styles, path) is per
@@ -101,8 +106,11 @@ rotate the glyph bitmaps. `strokeText` currently fills with the stroke style
 rather than producing an outline.
 
 Images: `drawImage(source, …)` in the 3-argument (`dx, dy`), 5-argument
-(`dx, dy, dw, dh`) and 9-argument (`dx, dy, dw, dh, sx, sy, sw, sh`) forms.
-`source` may be an `<img>` element (decoded through the image module) or another
+(`dx, dy, dw, dh`) and 9-argument (`dx, dy, dw, dh, sx, sy, sw, sh`; this
+engine's 9-argument form is destination-first) forms. A full affine transform
+(rotation/skew/scale) is honoured: the destination rectangle becomes a
+parallelogram and every device pixel is inverse-mapped to the source rectangle
+(nearest-neighbour). `source` may be an `<img>` element (decoded through the image module) or another
 `<canvas>` element (its current bitmap). Sampling is nearest-neighbour, so a
 large upscale of a small source is blocky — fine for icons and pixel art, not a
 photo pipeline.

package/doc/gui/dom.md

@@ -11,28 +11,43 @@ comments and doctype skipped, entity decoding (named + numeric/hex), void
 elements, raw-text elements (`<style>`/`<script>`), and the common implicit
 close rules (`li`, `dt`/`dd`, `option`, `p`, headings, table cells/rows).
 
-**CSS parser** (`runtime/ext_gui/css.{h,cpp}`): comments and at-rules skipped
-(for now), rules with multiple selectors, and declarations. Selectors: type,
-`.class`, `#id`, attribute (`=`, `~=`, `|=`, `^=`, `$=`, `*=`), the four
-combinators (descendant, child, adjacent and general sibling) and 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)). Values:
-lengths (`px`, `%`, `em`, `rem`, `vw`, `vh`, `pt`, `pc`, `in`, `cm`, `mm`, `q`),
-colors (hex, `rgb()`/`rgba()`, a named subset), numbers, keywords and shorthands
-(`margin`/`padding`/`border`/`flex`). `transform` (`translate`/`translate3d`/
-`translateX`/`translateY`, `scale`/`scale3d`/`scaleX`/`scaleY`, `rotate`/
-`rotateZ`, `matrix`; the `3d` spellings' `z` argument is dropped) and
-`transform-origin` are parsed into the computed style as a list of operations
-plus two (unresolved) origin lengths; an unsupported function invalidates the
-whole declaration ([Layout](./layout.md#transforms-m15)).
+**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
+`: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`
+(legacy `:before`/`:after` too). Values: lengths (`px`, `%`, `em`, `rem`, `vw`,
+`vh`, `pt`, `pc`, `in`, `cm`, `mm`, `q`), colors (hex, `rgb()`/`rgba()`, a named
+subset), numbers, keywords and shorthands (`margin`/`padding`/`border`/`flex`).
+`transform` (`translate`/`translate3d`/`translateX`/`translateY`, `scale`/
+`scale3d`/`scaleX`/`scaleY`, `rotate`/`rotateZ`, `matrix`; the `3d` spellings'
+`z` argument is dropped) and `transform-origin` are parsed into the computed
+style as a list of operations plus two (unresolved) origin lengths; an
+unsupported function invalidates the whole declaration
+([Layout](./layout.md#transforms-m15)). M19 adds `background-image` layer lists
+(linear/radial), `clip-path` (`inset`/`circle`/`ellipse`/`polygon`), the
+`filter`/`backdrop-filter` function lists, `text-shadow` and `content`.
 
 **Cascade & computed style** (`runtime/ext_gui/style.{h,cpp}`): a small built-in
 UA stylesheet, author rules sorted by `(!important, specificity, source order)`,
 then inline `style=""` (highest specificity, but non-`!important` inline loses to
-`!important`), plus CSS inheritance of the text properties. Relative lengths are
-kept unresolved until layout, except `font-size` (resolved against the *parent*
-font size) and `line-height`.
+`!important`), plus CSS inheritance of the text properties. `@media` rules are
+filtered against the current viewport on every restyle, so a resize switches
+them. Relative lengths are kept unresolved until layout, except `font-size`
+(resolved against the *parent* font size) and `line-height`.
+
+`::before`/`::after` styles are computed after their originating element: the
+selector's last compound must name the pseudo-element, and the rest of the
+selector is matched against the origin (so `.card.info::before` works). The
+pseudo style inherits the origin's computed style, `content` is resolved
+(strings, escapes, `attr()`, quotes), and a synthetic node is placed in a
+per-restyle arena. Layout inserts its box before/after the real children;
+traversal, queries, `innerHTML` and `elementIndex()` never see it, and hit
+testing targets the origin element.
 
 ## Interactive DOM (M8)
 

package/doc/gui/known-issues.md

@@ -5,15 +5,24 @@
 
 ## Known issues
 
-- **No WebGL.** `getContext("webgl")` / `getContext("webgl2")` answer `null` and
-  the `WebGL*` / `WebGL2RenderingContext` / `XRWebGL*` globals are `undefined`,
-  so a WebGL page such as a Three.js scene fails with the library's own
-  "Error creating WebGL context" and is expected to show its fallback panel.
-  Only `getContext("2d")` is backed by a rasteriser (see
-  [Canvas](./canvas.md)). Everything else about a ported page — module graph,
-  DOM handles, events, the browser globals in [API](./api.md#browser-globals),
-  the frame pump — works, so a Three.js program *compiles and starts*; it just
-  cannot draw.
+- **WebGL 1.0 and 2.0 run on the GPU, with a subset of each.**
+  `canvas.getContext("webgl")` / `"webgl2"` return real GPU contexts (see
+  [WebGL](./webgl.md)): GLSL ES shaders are translated to SPIR-V by the bundled
+  glslang — consumed directly by the Vulkan backend, or cross-compiled to MSL by
+  the bundled SPIRV-Cross for Metal — and the drawing buffer is an offscreen
+  colour texture that the page composites without a readback. WebGL 2 adds VAOs,
+  instancing, integer attributes, sampler objects, `texStorage2D` and buffer
+  copies. Uniform blocks, transform feedback, cube maps, 3D textures,
+  float/depth textures, compressed textures, multiple render targets,
+  `blitFramebuffer`, MSAA and stencil operations are not implemented; `clear`
+  ignores the scissor rectangle. On an SDL_GPU backend that accepts neither
+  SPIR-V nor MSL (Direct3D 12, which would need DXIL) both context kinds are
+  `null`. The `.js` asset loader now patches only three.js's shader unroller;
+  `WebGLRenderer` runs on the real backend and there is no Canvas2D fallback.
+  Shadow maps (depth textures), cube textures/environment maps and HDR render
+  targets remain unsupported.
+
+
 
 - **Intermittent crash at auto-close.** `XT_GUI_AUTOCLOSE_MS` can end a run
   with a native access violation in roughly two runs out of five; a clean exit
@@ -44,6 +53,23 @@
   *class change* on a flex container has also been observed to crash the same
   way; `examples/gui/pelican-bike` reveals its game-over overlay with `opacity`
   instead.
+- **CSS coverage is a deliberate subset.** Grid, `clamp()`/`min()`/`max()`/`env()`,
+  `var()` custom properties, the `inset` shorthand, `box-sizing`, `visibility` and
+  `pointer-events`, `@media` queries, generated content (`::before`/`::after`),
+  multi-layer linear/radial backgrounds, `text-shadow`, `clip-path`
+  (`inset`/`circle`/`ellipse`/`polygon`) and `filter` colour functions are
+  implemented. Known limits: `mix-blend-mode`, `background-clip`,
+  `background-position`/`size`/`repeat`, repeating gradients and `backdrop-filter`
+  compositing are not implemented (`backdrop-filter` parses and cascades, but
+  sampling the backdrop needs an offscreen layer, so it paints nothing);
+  `filter: blur()` is a nine-tap per-shape spread rather than a true group blur,
+  so overlapping descendants can darken; `drop-shadow` is approximated from box
+  silhouettes; at most two nested `clip-path` shapes are intersected (deeper
+  nesting keeps the outer two); and images/canvases are not colour-filtered
+  except for the brightness/opacity tint the image shader can carry. Canvas
+  textures are sampled nearest-neighbour. Background gradients remain solid
+  bands (18 for linear, 32 concentric ellipses for radial), so a soft gradient
+  may show slight banding.
 - **SVG is NanoSVG's subset.** SVG *files* (`<img src="logo.svg">`) and inline
   `<svg>` trees share the vendored NanoSVG parser/rasteriser
   (`runtime/ext_gui/svg.cpp`, `inline_svg.cpp`), which renders
@@ -72,23 +98,30 @@
   MSVC-targeting clang as the driver (the LLVM bundled with Visual Studio when
   no newer one is on `PATH`), so a developer prompt is not required.
 - Windows: an MSVC-compatible `gui.lib` (COFF objects + `ar -M`/`llvm-ar`) is
-  produced by `scripts/build-gui.ts` but is not validated in CI, so the Windows
-  step is provisional (the job stays green) and `package` skips it. Building and
-  running `examples/gui/pelican-svg` and `examples/gui/pelican-bike` on a
-  developer machine works. SDL_GPU selects the **Vulkan** backend there
-  (`win.driver()` reports `"vulkan"`), so the archive needs no DXIL/`dxc`
-  toolchain; the hosted Windows runners have no GPU/Vulkan driver, which is why
-  the CI run stays provisional.
-- **Media on Windows:** the `media` extension is POSIX-only for now. The GUI
-  engine itself builds on Windows, but without the extension `<video>`/`<audio>`
-  are inert there (an open fails and fires `error`), and `--ext media` reports an
-  actionable error instead of linking. Enabling it needs an MSVC-compatible
-  FFmpeg build and is deferred until the Windows GUI path itself is validated.
-  `<video controls>` is likewise deferred — the intended pattern is TS + a CSS
-  overlay, as in `examples/gui/media.ts`.
+  produced by `scripts/build-gui.ts`. The Windows x64 CI job builds it with the
+  Visual Studio toolchain (`.github/actions/vs-toolchain` imports `vcvarsall`
+  and uses VS's bundled LLVM), links a `gui,media` program, and ships it in the
+  x64 release. *Running* the examples on the hosted runner stays provisional
+  because it has no GPU/Vulkan driver (SDL_GPU selects the **Vulkan** backend
+  there, so no DXIL/`dxc` toolchain is needed). Windows arm64 still skips both
+  archives. Building and running `examples/gui/pelican-svg` and
+  `examples/gui/pelican-bike` on a developer machine works.
+- **Windows: x64 builds in CI, arm64 and runtime validation stay provisional.**
+  `media.lib` is produced by `scripts/build-media.ts` with FFmpeg's MSVC
+  toolchain (`--toolchain=msvc --cc=clang-cl`) so its COFF objects and static CRT
+  match `gui.lib`, and `--ext media` links and plays there. Building it needs a
+  POSIX shell to run FFmpeg's `configure` and GNU make; the shell comes from Git
+  for Windows (already needed to clone SDL3), and make is a native GNU make
+  (Chocolatey's `make`, or `xbintsc_MAKE`). CI installs make explicitly,
+  builds `gui.lib` + `media.lib` on Windows x64 (using the same Visual Studio
+  `vcvarsall` + bundled LLVM as a local build), links a `gui,media` program, and
+  ships both archives in the Windows x64 release; the example *run* remains
+  provisional because hosted runners have no GPU/Vulkan driver. Windows arm64
+  still skips both archives, and `<video controls>` is likewise deferred — the
+  intended pattern is TS + a CSS overlay, as in `examples/gui/media.ts`.
 - **D3D12 shaders:** the SPIR-V (Vulkan) and DXIL (Direct3D 12) blobs are built
   and embedded, so the non-Metal path no longer skips geometry. DXIL remains
   unusable on **SDL 3.2.10**: its D3D12 backend rejects any graphics pipeline
   whose shaders declare a uniform buffer, and the engine passes the viewport that
   way. This does not affect Windows in practice because SDL_GPU selects Vulkan
-  there; re-check after an SDL upgrade if the D3D12 path is ever forced.
+  there; re-check after an SDL upgrade if the D3D12 path is ever forced.

package/doc/gui/layout.md

@@ -32,6 +32,24 @@ with absolute (viewport-relative) geometry:
   Item margins are part of the item's outer size on both axes, so a negative
   `margin-top` pulls an item up instead of being ignored. Whitespace-only text
   between items (source indentation) does not become a flex item.
+- **Grid** — `display: grid` with `grid-template-columns` / `grid-template-rows`
+  (fixed lengths, `auto`, `<n>fr`, `minmax(...)`, `repeat(...)`), `gap` /
+  `row-gap` / `column-gap`, row-major auto-placement, simple `grid-column` /
+  `grid-row` line placement, and `align/justify-items` plus
+  `align/justify-self` (including `place-items` / `place-self`). Implicit rows
+  and columns grow from the items; a single-cell grid with `place-items: center` centres a card in the whole overlay. Item measurement is a two-pass
+  layout (intrinsic size, then final placement), so text fragments are cleared
+  between passes.
+- **CSS value functions and custom properties** — `clamp(min, value, max)`,
+  `min(...)` and `max(...)` keep their arguments unresolved in the computed style
+  and are evaluated at layout time against the element's font size and the
+  viewport (`vw`/`vh`); `env(safe-area-inset-*)` resolves to zero in a desktop
+  window. `var(--name[, fallback])` is substituted from inherited custom
+  properties during the cascade. `inset` is the four-value
+  `top/right/bottom/left` shorthand, `box-sizing: border-box` subtracts padding
+  and borders from an explicit width/height, `visibility: hidden` skips painting
+  and hit testing, and `pointer-events: none` makes a box transparent to input
+  (its descendants can opt back in with `auto`).
 - **Positioning** — `position: relative` offsets a box (and its subtree) by
   `top`/`right`/`bottom`/`left` without changing the space it reserved;
   `position: absolute` (and `fixed`, which resolves against the viewport) takes

package/doc/gui/media.md

@@ -68,21 +68,24 @@ clip paths are not rendered (see [Known issues](./known-issues.md)).
 Media playback is split across two extensions so a GUI program does not pay for
 a decoder it never uses:
 
-- **`gui`** (`gui.a`) owns the `<video>`/`<audio>` elements, the DOM API, the
-  renderer integration and the SDL audio sink, but contains **no FFmpeg**.
-  `runtime/ext_gui/media.{h,cpp}` declares the player interface and dispatches
-  through a table the media backend installs at startup
+- **`gui`** (`gui.a`/`gui.lib`) owns the `<video>`/`<audio>` elements, the DOM
+  API, the renderer integration and the SDL audio sink, but contains **no
+  FFmpeg**. `runtime/ext_gui/media.{h,cpp}` declares the player interface and
+  dispatches through a table the media backend installs at startup
   (`runtime/ext_gui/media_api.h`).
-- **`media`** (`media.a`, `runtime/ext_media/`) is the optional decoder
-  backend: `runtime/ext_media/media.cpp` wraps a statically vendored **FFmpeg**
-  build, and `runtime/ext_media/media_bridge.c` registers it with the engine.
-  Enable it with `--ext media` (or `--ext gui,media`). `media` requires `gui`;
-  the registry rejects the combination in the wrong order.
+- **`media`** (`media.a`, or `media.lib` with the MSVC ABI on Windows;
+  `runtime/ext_media/`) is the optional decoder backend:
+  `runtime/ext_media/media.cpp` wraps a statically vendored **FFmpeg** build,
+  and `runtime/ext_media/media_bridge.c` registers it with the engine. Enable it
+  with `--ext media` (or `--ext gui,media`). `media` requires `gui`; the
+  registry rejects the combination in the wrong order.
 
 Without the `media` extension the element still exists and its DOM API is
-callable, but opening a source fails and fires `error`. That is also how Windows
-behaves today: the archive is POSIX-only. There is no WebView and no platform
-media framework in the path either way.
+callable, but opening a source fails and fires `error`. The same happens on any
+host where the archive has not been built (run `npm run media`); Windows is no
+longer special: `media.lib` is FFmpeg compiled with clang-cl for the MSVC ABI,
+so it links against `gui.lib` and plays normally. There is no WebView and no
+platform media framework in the path either way.
 
 - **Decoding.** `avformat_open_input` opens the `src` (a path — `file://` is
   accepted, but media paths are *not* percent-decoded, unlike images), the
@@ -104,7 +107,8 @@ media framework in the path either way.
   push mode (`NULL` callback), buffering about 0.25 s ahead at 48 kHz stereo
   `SDL_AUDIO_F32`. `volume` maps to `SDL_SetAudioStreamGain`; audio is
   best-effort and is skipped when no device is available (headless CI). Keeping
-  the sink in `gui.a` means `media.a` depends only on FFmpeg.
+  the sink in the GUI archive means `media.a`/`media.lib` depends only on
+  FFmpeg.
 - **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.

package/doc/gui/rendering.md

@@ -10,8 +10,9 @@ emits a backend-agnostic `DisplayList`: a painter-order `ops` list of
 **rectangles** (backgrounds and four solid border edges, with `border-radius`),
 **text runs** (each carrying its text, colour and resolved `FontSpec`) and
 **images**, backed by parallel payload arrays. Each op also carries the active
-clip rectangle (the padding box of the nearest `overflow: hidden` ancestor), so
-`overflow` clipping and `z-index` ordering survive into the renderer.
+clip rectangle (the padding box of the nearest `overflow: hidden` ancestor) and
+up to two indices into the display list's triangulated `clip-path` polygons, so
+`overflow`/`clip-path` clipping and `z-index` ordering survive into the renderer.
 `DisplayList::dump()` feeds `paintList()`/`paintCount()`.
 
 `opacity` is honoured only at its extremes: a box whose computed `opacity` is
@@ -73,7 +74,53 @@ divided back into logical units, exactly the way HiDPI scaling already worked.
 
 The window background (`setBackground`) is the render-pass clear colour.
 
-Still to do in M4: gradients.
+### Backgrounds, generated content and effects (M19)
+
+`background-color` and every `background-image` layer are painted. A
+comma-separated layer list is painted bottom-up (the first declaration layer is
+topmost), and both gradient kinds are supported:
+
+- a **linear** gradient is sampled at 18 points and emitted as solid rectangles;
+  `to <side>`, `deg`/`grad`/`rad`/`turn`, percentage and multi-stop colours work
+  (the band walk is axis-aligned, so an oblique angle uses the nearest axis);
+- a **radial** gradient is 32 concentric ellipses. Each is a unit-radius rounded
+  rectangle mapped through the shape pipeline's transform slot, so a circle or
+  ellipse keeps the distance-field antialiasing. Shape/size keywords
+  (`circle`/`ellipse`, `closest-side`/`farthest-side`/`closest-corner`/
+  `farthest-corner`, explicit radii) and `at <position>` are parsed.
+
+The background colour sits under every layer. Gradients are partially
+transparent if their stops are, and the band approximation can show banding and
+alpha stacking on a very translucent multi-stop gradient.
+
+**Generated content** needs no new display-list kind: `::before`/`::after` are
+ordinary layout boxes owned by the per-restyle arena in `style.cpp`, so their
+background, border, text and transforms flow through the same paint walk.
+`content` is resolved from strings, `attr()` and open/close quotes.
+
+**`text-shadow`** is emitted as shadow `PaintText` runs *before* the real run, so
+the text pipeline draws them without a new shader. A blurred shadow is nine
+translucent copies spread around the offset (the same approximation `filter:
+blur()` uses).
+
+**`clip-path`** is resolved in `paint_clip.cpp` to a device-space polygon (the
+box transform is applied to every point), triangulated with ear clipping, and
+stored on `DisplayList::clip_paths`. Ops carry up to two path indices on their
+`PaintClip`; `renderer_clip.cpp` intersects each convex shape/glyph/image quad
+with those triangles at upload time. The result is exact even for concave
+`polygon()` shapes, needs no stencil or shader change, and the edges are hard
+(no analytic antialiasing). Intersecting two nested paths is supported; deeper
+nesting keeps the outermost two.
+
+**`filter`** colour functions (`brightness`, `contrast`, `grayscale`, `sepia`,
+`invert`, `saturate`, `hue-rotate`, `opacity`) are folded into each painted
+colour, so a box and its descendants see the filter. `blur()` and
+`drop-shadow()` are approximations at the display-list level: blur spreads nine
+translucent copies per shape, drop-shadow is a box/text silhouette. This keeps
+the single render pass — there is no offscreen render target — at the cost of
+group semantics: overlapping descendants of a blurred/filtered group can darken,
+and `backdrop-filter` cannot sample what is behind the element, so it parses and
+cascades but paints nothing.
 
 ## Text stack (M4b)