xbintsc 0.5.45 → 0.5.52

package/doc/ai/zh-CN/extensions.md

@@ -1,8 +1,9 @@
-# 扩展：Node 模块、GUI、媒体、C++/Rust 库
+# 扩展：Node 模块、GUI、链接特性、C++/Rust 库
 
 编译器核心与平台无关。任何与平台相关的东西——Node 的 `fs`、一个 HTML/CSS 渲染器、
 你自己的 C++ 库——都以**扩展**的形式接入：它既贡献模块绑定，也贡献要一起编译/链接的
-C/C++ 源码或目标文件。
+C/C++ 源码或目标文件。扩展里的重型可选部分（FFmpeg、glslang）做成**链接特性**，
+由程序用法选择，而不是单独的扩展开关。
 
 ## 最容易踩的规则
 
@@ -70,8 +71,9 @@ import { createWindow, run } from "gui";
 `<style>` 块（运行时解析器只读取内联 `<style>`）；并让随包引入的 Three.js 的
 `WebGLRenderer` 先探测 WebGL 上下文：引擎有上下文时使用 Three.js 自己的渲染器，
 直接使用真实的 WebGL 2 后端（只修补其着色器循环展开，不再打包 Canvas2D 回退）。
-`<img>` 由引擎自身解码；而 `<video>`/`<audio>` 在只启用 `gui` 时**不可用**
-——它们需要单独的 [`media`](#media--视频音频解码) 扩展。也支持 `<canvas>`：
+`<img>` 由引擎自身解码；`<video>`/`<audio>` 解码（FFmpeg）与 GLSL 翻译（glslang）
+是**可选的链接特性**，由程序自动选择——见
+[可选链接特性](#可选链接特性media-gpu-images-shaping-webgl)。也支持 `<canvas>`：
 `getContext("2d")` 返回的上下文，其填充、路径、
 渐变、文本与 `drawImage` 由自研 CPU 光栅器处理（另有线段端点/连接、虚线描边、
 `ellipse` 与 `roundRect`），元素句柄还暴露 `width`/`height`。CSS
@@ -79,8 +81,13 @@ import { createWindow, run } from "gui";
 图像与子元素）可以被平移、缩放与旋转而不触发任何重排——可以用
 `requestAnimationFrame` 逐帧驱动，或写成 `transition: transform`（见
 `examples/gui/pelican-svg`）。CSS 子集还覆盖 `@media`、`::before`/`::after`
-生成内容、线性/径向多层背景、`text-shadow`、`clip-path` 与 `filter`
-颜色/阴影效果；`backdrop-filter` 与真正的组模糊是有文档说明的近似或未支持。
+生成内容、线性/径向多层背景、`calc()`、真正的 `text-shadow`/`box-shadow`
+高斯模糊、`clip-path`、`filter` 颜色效果、`backdrop-filter` 合成、
+`@keyframes` 与 `transition`/`animation` 时间函数、`letter-spacing`、
+`text-transform`、行内级 `flex`/`grid`、`grid-area`、`aspect-ratio`、自动
+外边距、百分比 `border-radius`、`outline`、`url()` 图层的平铺
+`background-size`、SVG 子元素上的文档 CSS，以及仅文本的竖排书写模式。`filter: blur()`
+仍是有文档说明的近似。
 因为主体是 C++，它以各平台预编译的 `gui.a`/`gui.lib` 形式分发。如果该
 平台的归档不存在，构建会以明确的提示失败；设计与路线图见 [../../zh-CN/gui.md](../../zh-CN/gui.md)（总览；引擎按功能拆分在 [`doc/zh-CN/gui/`](../../zh-CN/gui/) 下），
 脚本接口见 [../../zh-CN/gui-scripts.md](../../zh-CN/gui-scripts.md)。Canvas API
@@ -91,38 +98,57 @@ import { createWindow, run } from "gui";
 `getComputedStyle`、`alert`/`prompt`、`escape`、`Event` 家族，以及可用的 Web Audio
 实现（`AudioContext` 提供 gain、oscillator、buffer-source、biquad、compressor、
 stereo-panner、constant-source 与 delay 节点、真实的 48 kHz 混音器、逐采样的
-AudioParam 自动化，`decodeAudioData` 引擎内解码 WAV，压缩格式则通过 `media`）—— 另外还有帧泵：
+AudioParam 自动化，`decodeAudioData` 引擎内解码 WAV，压缩格式则通过 `media` 特性）—— 另外还有帧泵：
 它在 `loadHTML` 时启动，仅在仍有动画帧回调时重新排程，因此从不调用 `run()` 的页面
 也能绘制并最终退出。**WebGL 1.0 与 2.0 已实现**：`canvas.getContext("webgl")` /
 `"webgl2"` 返回 GPU 上下文，其 GLSL ES 着色器由内置 glslang 编译为 SPIR-V
 （Vulkan 直接消费，Metal 上由内置 SPIRV-Cross 转成 MSL），
 并通过 SDL_GPU 绘制；页面直接合成颜色纹理而无须 CPU 读回，WebGL 2 还增加
 VAO、实例化、整数属性、采样器对象、`texStorage2D` 与缓冲拷贝（见
-[../../zh-CN/gui/webgl.md](../../zh-CN/gui/webgl.md)）。WebXR、未启用
-`media` 时的 `<video>`/`<audio>` 与流式接口**尚未实现**：`typeof` 会回答
+[../../zh-CN/gui/webgl.md](../../zh-CN/gui/webgl.md)）。WebXR 与流式接口**尚未实现**：
+`typeof` 会回答
 `"undefined"`，让页面走自己的降级分支。`fetch` 不是 GUI 扩展的功能——它由核心
 运行时提供（`http://`，以及本地 `file://` 与相对路径；不支持 HTTPS 与流式），
 因此 GUI 程序同样可用。见 [../../implemented/fetch.md](../../implemented/fetch.md)。
 
-### `media` —— 视频/音频解码
-
-用 `--ext media` **与 `gui` 一起**开启（`--ext gui,media`；注册表会拒绝单独启用
-`media`）。它链接单独的 FFmpeg 后端 `media.a`/`media.lib`，因此加入
-`<video>`/`<audio>` 播放不会让只做界面的二进制变大。
+### 可选链接特性（media、gpu、images、shaping、webgl）
+
+`gui` 仍然只有一个扩展，但其中的重型部分是可选的**链接特性**。编译器扫描打包后的
+HTML/CSS/TS（导入的 `.html` 与内联 CSS 都属于 bundle），按程序自动选择；不需要额外
+扩展参数：
+
+- **`media`** —— `<video>`/`<audio>` 与压缩格式 `decodeAudioData` 的 FFmpeg 解码。
+  由 `<video>`/`<audio>` 元素、`createElement("video"/"audio")`、`new Audio()`、
+  `decodeAudioData` 或运行时拼出的 markup 触发，链接 FFmpeg 后端
+  `media.a`/`media.lib`。
+- **`gpu`** —— WebGL 与 `mix-blend-mode` 共用的 glslang/SPIRV-Cross GLSL 翻译器。
+  由 `getContext("webgl"/"webgl2"/…)`（或运行时决定的 kind）、任意 `webgl` 字符串、
+  `mix-blend-mode` 触发。
+- **`images`** —— `<img>`、内联 `<svg>`、CSS `background-image`/`url(...)`、
+  `drawImage`/`createImageBitmap`/`Image` 与应用图标所需的 stb_image/NanoSVG 解码。
+  纯文本页面两个解码器都不链接。
+- **`shaping`** —— HarfBuzz + FreeType 提供的完整 OpenType 整形（连字、复杂文种）
+  与 CFF/OTF/可变字体支持。非 ASCII 文本（或转义/实体码点）或作者的
+  `@font-face` 规则会自动选中；纯拉丁页面保持 stb_truetype 后端，两个库都不链接。
+- **`webgl`** —— WebGL context 与 DOM 绑定。由 WebGL 的 `getContext(...)` 或
+  `webgl` 字符串触发；它依赖 `gpu`，两者一起激活。不用 WebGL 的页面两者都不链接。
+
+用 `--feature media,gpu,images,shaping,webgl`（或 `all`）覆盖扫描，用 `--no-feature media`
+强制不链接。`--verbose` 会打印选中的集合。只渲染 HTML/CSS/2D canvas 的程序既不链接
+FFmpeg、glslang，也不链接图片解码器、HarfBuzz/FreeType 或 WebGL context；用运行时数据拼 HTML/CSS 的
+页面应传 `--feature all`，因为扫描看不到它。
+自动检测到的特性归档缺失时构建打印 warning，能力在运行时降级（媒体元素触发
+`error`）；显式强制的特性则报错。
 
 DOM API 与普通 HTML 媒体元素一致：`play()` / `pause()` / `load()`，以及
 `paused` / `ended` / `duration` / `currentTime` / `volume` / `muted` / `loop` /
 `autoplay` / `videoWidth` / `videoHeight` / `readyState` / `src` 属性，还有
 `loadedmetadata`/`play`/`pause`/`ended`/`timeupdate`/`error` 事件。没有内置
 控件——用元素和 CSS 自绘控件（见 `examples/gui/media.ts`）。视频帧与音频 PCM
-都在主线程解码；视频走图像纹理路径。没有该扩展时，打开媒体源会失败并触发
-`error`（元素与 API 仍然存在）。归档会为每个宿主平台构建：POSIX 产出
-`media.a`，Windows 则用面向 MSVC 的 `clang-cl` 编译 FFmpeg 并产出 `media.lib`，
-因此可与 `gui.lib` 链接。Windows 上构建它需要 POSIX shell（Git for Windows
-自带的 bash）与原生 GNU make（Chocolatey `make`，或 `xbintsc_MAKE`）。见
-[../../zh-CN/gui/build.md](../../zh-CN/gui/build.md)。
-没有归档、或宿主上还没运行 `npm run media` 时，媒体元素会触发 `error`；见
-[../../zh-CN/gui/known-issues.md](../../zh-CN/gui/known-issues.md)。
+都在主线程解码；视频走图像纹理路径。Windows 上构建归档需要 POSIX shell（Git for
+Windows 自带的 bash）与原生 GNU make（Chocolatey `make`，或 `xbintsc_MAKE`）。见
+[../../zh-CN/gui/build.md](../../zh-CN/gui/build.md) 与
+[../../zh-CN/gui/media.md](../../zh-CN/gui/media.md)。
 
 ## 第三方 npm 包
 

package/doc/ai/zh-CN/troubleshooting.md

@@ -113,14 +113,15 @@ npm 包会提供它（去掉 `--omit=optional` 重新安装），但普通源码
 
 ### `media native library not found at …`
 
-`<video>`/`<audio>` 播放需要可选的 `media` 归档（`media.a`，Windows 上是
+`<video>`/`<audio>` 解码需要可选的 `media` 链接特性及其归档（`media.a`，Windows 上是
 `media.lib`）。发布为其构建时，`@xbintsc/<os>-<arch>` npm 包会提供它；否则用
-`npm run media` 单独构建。构建它，或去掉 `--ext media`；
-仅启用 `gui` 的构建仍可链接，媒体元素只会触发 `error`。`media` 扩展还依赖
-`gui`，单独 `--ext media` 会被拒绝并提示应传的 flag。Windows 上 FFmpeg 的
+`npm run media` 构建。自动选中该特性而归档缺失时，构建打印 **warning** 后继续，
+媒体元素只会触发 `error`；显式 `--feature media`（或弃用的 `--ext media`）则直接
+报错。可以用 `--no-feature media` 主动关闭。Windows 上 FFmpeg 的
 构建还需要 POSIX shell（Git for Windows 的 bash）与原生 GNU make
 （Chocolatey `make`，或 `xbintsc_MAKE`）。脚本会指出缺失的是哪一个。见
-[../../zh-CN/gui/build.md](../../zh-CN/gui/build.md)。
+[../../zh-CN/gui/build.md](../../zh-CN/gui/build.md) 与
+[../../zh-CN/gui/build.md#链接特性](../../zh-CN/gui/build.md#链接特性)。
 
 ### `Icon file not found` / 图标工具缺失
 

package/doc/gui/animation.md

@@ -30,21 +30,27 @@ running transition is recorded and re-applied every frame until it finishes;
 the engine advances the clock with real frame deltas (`XtDocument::advance`),
 and `win.advance(ms)` lets tests step it deterministically.
 
-- Supported properties: `background-color`, `color`, `border-color`,
-  `border-radius` and `transform`; `transition: all` covers them. A
-  layout-affecting property (width, position, …) is still not animated — that
-  would reflow every frame — but `transform` is paint-time, so animating it costs
-  one matrix per animated box per frame ([Layout](./layout.md#transforms-m15)).
+- Supported properties: `background-color`, `color`, `border-color`, `opacity`,
+  `border-radius`, `transform`, `text-shadow`, `box-shadow`, every box offset
+  and size length (`width`/`height`/`top`/`left`/`margin-*`/`padding-*`/…), the
+  gap/flex-basis lengths and `filter` (matching filter lists interpolate their
+  blur lengths, amounts and drop-shadow colours). `transition: all` covers the
+  whole list. Lengths
+  interpolate when their units line up (a mixed-unit change is CSS's discrete
+  fallback); `opacity`, colours and `transform` interpolate normally.
 - Both the `transition` shorthand and the `transition-property` / `-duration` /
   `-delay` / `-timing-function` longhands are parsed; time values accept `s` and
-  `ms`; timing functions are `linear`, `ease`, `ease-in`, `ease-out` and
-  `ease-in-out` (`ease` is a smoothstep approximation).
+  `ms`; `calc()` is accepted inside the shorthand and longhands.
+- Timing functions are `linear`, `ease`, `ease-in`, `ease-out`, `ease-in-out`,
+  `cubic-bezier(x1, y1, x2, y2)`, `steps(n, start|end)` and their `jump-*`
+  spellings. The engine solves the cubic Bézier numerically; keyword curves use
+  the CSS control points.
 - Retargeting mid-flight starts a new transition from the current interpolated
   value, so reversing a hover animates smoothly from wherever it was.
 - `computedStyle()` reports the displayed (interpolated) value, so transitions
   are directly observable in tests.
 
-`transform` lists interpolate **element-wise** (`document.cpp`,
+`transform` lists interpolate **element-wise** (`animation_values.cpp`,
 `xt_transform_interpolate`), which is what makes the common pair
 `translateY(-4px) rotate(-0.35deg)` <-> `none` glide instead of jumping: the
 missing side is filled with identity ops of the same kind. Two lists whose shapes
@@ -52,6 +58,29 @@ or units do not line up (`rotate(10deg)` vs `rotate(10rad)`, or a different numb
 of functions) are not interpolated at all — the transition snaps to the target,
 which is CSS's discrete fallback rather than a wrong-looking sweep.
 
+## CSS animations (`@keyframes`)
+
+`@keyframes` rules are parsed into `StyleSheet::keyframes` (offsets from
+`from`/`to`/percent selectors, sorted). `animation` and every `animation-*`
+longhand are supported: name, duration, delay, timing function, iteration count
+(including `infinite`), direction (`normal`/`reverse`/`alternate`/
+`alternate-reverse`), fill mode (`none`/`forwards`/`backwards`/`both`) and
+`paused`/`running`.
+
+`XtDocument` starts one active animation per element/name when the computed
+style first declares it, restarts it when the shorthand changes, and leaves it
+alone across unrelated restyles. Each frame it resolves the local time to an
+iteration progress, applies the timing function **per keyframe interval**, and
+interpolates every animatable property. A property that a middle keyframe does
+not mention keeps interpolating between the nearest keyframes that do declare
+it (so a transform declared at 0% and 100% runs straight through a 50% step that
+only changes `opacity`). Missing 0%/100% steps use the element's underlying
+style. `forwards`/`backwards` hold the edge value outside the active time, and
+`computedStyle()` reports the animated value.
+
+Animations and transitions share `animation_values.cpp`, so both understand the
+same property set, shadow lists and `transform` identity filling.
+
 ## CSS transforms (M15)
 
 `transform` and `transform-origin` are supported as *paint-time* effects
@@ -93,5 +122,6 @@ Both are exercised by `examples/gui/pelican-svg` (per-frame sway plus a
 hover transition on the caption) and pinned by
 `tests/e2e/gui-transform.test.ts`.
 
-Still to do for animation: `@keyframes` animations and `cubic-bezier(...)`.
+`calc()` can be used in any animated length (for example
+`transition: width 300ms ease-out; width: calc(100% - 20px)`).
 

package/doc/gui/api.md

@@ -137,7 +137,8 @@ evaluated per sample, so a ramp keeps moving while the page is idle.
 procedurally. `decodeAudioData(bytes)` returns a promise for a decoded
 AudioBuffer: WAV (PCM 8/16/24/32-bit, IEEE float 32/64, A-law and µ-law) is
 decoded by the engine itself; MP3, AAC/M4A, Vorbis, Opus and FLAC need the
-optional `media` extension (`--ext gui,media`), whose FFmpeg decoder is used as
+optional `media` link feature (auto-selected when the program calls
+`decodeAudioData`), whose FFmpeg decoder is used as
 the fallback. `bytes` may be an ArrayBuffer, a typed array, a Node `Buffer`, or
 the raw byte string `fs.readFileSync` returns (this runtime has no dedicated
 binary type, and that string's storage is exactly the file bytes). The result

package/doc/gui/build.md

@@ -8,13 +8,33 @@
   `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`), 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
+  **FreeType** (`FREETYPE_VERSION`, default `2.13.3`) and **HarfBuzz**
+  (`HARFBUZZ_VERSION`, default `10.1.0`) for the optional `shaping` feature,
+  and fetches and builds static **glslang** (`GLSLANG_VERSION`, default
+  `16.6.0`) against the pinned SPIR-V headers (`SPIRV_HEADERS_VERSION`), and —
+  **on macOS only** — **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. Metal is the only SDL_GPU backend that consumes MSL, so on
+  Windows/Linux the script neither fetches nor merges SPIRV-Cross:
+  `webgl_msl.cpp` compiles to nothing there and the ~2.5 MiB it contributes
+  would be unreachable. The default text path uses the bundled
+  **stb_truetype** (`runtime/ext_gui/stb_truetype.h`); HarfBuzz + FreeType are
+  only extracted when the `shaping` feature is active.
+  Every library (SDL3, FreeType, HarfBuzz, glslang, SPIRV-Cross and the engine)
+  is compiled with `-ffunction-sections -fdata-sections`, and SDL is configured
+  without the subsystems the engine never calls (`SDL_JOYSTICK`, `SDL_HAPTIC`,
+  `SDL_SENSOR`, `SDL_CAMERA`, `SDL_RENDER`, `SDL_OPENGL`/`SDL_OPENGLES`,
+  `SDL_OFFSCREEN`, `SDL_HIDAPI`). HarfBuzz omits the APIs the shaping backend
+  never uses (`HB_NO_DRAW`/`PAINT`/`COLOR`/`NAME`/`STYLE`/`METRICS`/…, while
+  keeping `CFF`/`OPEN`/`VAR` for OTF and variable fonts) and is built with
+  `HB_NO_PRAGMA_GCC_DIAGNOSTIC_ERROR`, because `src/hb.hh` raises its warning
+  set to errors and two lean defines leave macOS/CoreText helpers unreferenced
+  (`HB_NO_MMAP` and `HB_NO_OT_FONT_GLYPH_NAMES`). The linker then drops
+  the unreachable functions (`--gc-sections`, `-dead_strip`, or link.exe's
+  default `/OPT:REF`). 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
@@ -25,13 +45,17 @@
   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` (`media.lib` with the MSVC
-  ABI on Windows). `gui.a` does **not** link FFmpeg: a program enables playback
-  explicitly with `--ext media`.
+  ABI on Windows). `gui.a` does **not** link FFmpeg: the compiler selects the
+  `media` link feature for a program that may play media and only then links
+  `media.a` (see [Link features](#link-features)).
 - `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`/`media.lib` and compiles the registration bridge
-  (`runtime/ext_media/media_bridge.c`) as a normal runtime source.
+  OS frameworks through `linkerFlags()`. Its `linkFeatures()` (in
+  `src/extensions/gui/features.ts`) declares `media`, `gpu`, `images`, `shaping` and `webgl`; the driver
+  compiles their bridges only when a feature is active.
+- glslang (and SPIRV-Cross on macOS) is merged into `gui.a` like SDL3, but the
+  engine reaches it only through the `gpu` feature's dispatch table. A program
+  that never compiles GLSL does not extract those archive members.
 - `scripts/build-gui.ts` compiles with the *same* clang the driver resolves
   (`src/driver/toolchain-provider.ts`); on Windows that is the MSVC-targeting
   LLVM bundled with Visual Studio, and its sibling `clang++`/`llvm-ar` are used
@@ -59,11 +83,12 @@
 - 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 same folders are packed into the
-  optional `@xbintsc/<slug>` npm package, so `--ext gui`/`--ext media` work from
+  optional `@xbintsc/<slug>` npm package, so `--ext gui` (with automatic
+  `media`/`gpu`/`images`/`shaping`/`webgl` selection) works from
   an npm install on the hosts the release builds for. 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 Windows x64 job builds both archives and links a `gui` program, so
   the MSVC build is validated even though *running* the examples there stays
   provisional (the hosted runner has no GPU/Vulkan driver). The macOS run is
   provisional too: the Intel runner's virtualised GPU lacks
@@ -82,8 +107,9 @@
 - The existing cache fingerprint already hashes `nativeObjects()` contents and
   `runtimeSources()` content, so rebuilding either archive invalidates cached
   binaries automatically.
-- CMake build trees live *next to* their sources (`vendor/sdl-build`,
-  `vendor/freetype-build`, `vendor/harfbuzz-build`), never inside them: a
+- CMake build trees live *next to* their sources (`vendor/sdl-build-lean`,
+  `vendor/freetype-build-lean`, `vendor/harfbuzz-build-lean`,
+  `vendor/glslang-build-lean`, `vendor/spirv-cross-build-lean`), never inside them: a
   `CMakeCache.txt` records the machine it was configured on, and SDL's video
   backends are `option()`s, so the first configure to run wins. A cached
   `vendor/SDL` tree that also carried `build/` therefore restored one machine's
@@ -95,6 +121,97 @@
   `xbintsc_SKIP_HEADER_CHECK=1` when they live under a prefix that check does
   not know).
 
+## Link features
+
+`gui` is the only user-facing extension, but two heavy halves are **optional link
+features** selected per program:
+
+| Feature | What it links | Selected when the program may use it |
+| --- | --- | --- |
+| `media` | `media_bridge.c` + `media.a` (FFmpeg) | an HTML `<video>`/`<audio>` tag, `createElement("video"/"audio")`, `new Audio()`, `decodeAudioData`, or runtime-built markup |
+| `gpu` | `gpu_bridge.c` (the implementation is already in `gui.a`) | a `getContext("webgl"/"webgl2"/"experimental-webgl")` (or a kind decided at run time), any `webgl` string, `mix-blend-mode`/`mixBlendMode`, or runtime-built markup |
+| `images` | `image_bridge.c` (the implementation is already in `gui.a`) | `<img>`, inline `<svg>`, `background-image`/`url(...)`, a `.svg` path, `drawImage`/`createImageBitmap`/`Image`, or runtime-built markup |
+| `shaping` | `text_bridge.c` (the implementation is already in `gui.a`) | non-ASCII text (CJK/Cyrillic/Greek/…), an escaped/entity codepoint, an author `@font-face` rule (custom fonts may be CFF/OTF), or runtime-built markup |
+| `webgl` | `webgl_bridge.c` (the implementation is already in `gui.a`; requires `gpu`) | a WebGL `getContext(...)`, a `webgl` string, or runtime-built markup |
+
+The driver scans the bundled AST (`src/driver/usage.ts`): every string literal
+(including imported `.html` and the CSS inlined from it), identifiers and
+property names, each `getContext(...)` kind, and whether HTML/CSS can be built
+from data the compiler cannot see. Simple `const` aliases are resolved;
+anything unresolved makes the program “dynamic markup” and enables the optional
+features conservatively.
+
+When a feature is active, the driver compiles its C **bridge only for that
+build** and links it before `gui.a`:
+
+- `media` → `runtime/ext_media/media_bridge.c`; its constructor installs the
+  decoder table and references `xt_media_backend_*`, which is what extracts the
+  FFmpeg members from `media.a`.
+- `gpu` → `runtime/ext_gui/gpu_bridge.c`; its constructor calls
+  `xt_gpu_feature_register` in `gpu_feature.cpp`, which installs the
+  `XtGpuShaderApi` table and references `compile_glsl` / `cross_compile_msl` /
+  the reflection helpers, extracting glslang (and SPIRV-Cross on macOS).
+- `images` → `runtime/ext_gui/image_bridge.c`; its constructor installs
+  `XtImageApi` via `image_feature.cpp`, which references stb_image and NanoSVG.
+  Layout, paint, the canvas `drawImage` path and the app-icon path call through
+  that table, so a text-only page links neither decoder.
+- `shaping` → `runtime/ext_gui/text_bridge.c`; its constructor installs
+  `TextApi` via `text_hb.cpp`, which references HarfBuzz and FreeType. Without
+  it the engine uses the built-in stb_truetype backend, so a Latin-only page
+  links neither library.
+- `webgl` → `runtime/ext_gui/webgl_bridge.c`; its constructor installs
+  `XtWebglApi` via `webgl_feature.cpp`, which references the WebGL context and
+  DOM bindings. The core reaches `getContext`, the canvas width/height setters,
+  `createImageBitmap`, the host types and the renderer through that table, so a
+  page with no WebGL links none of `webgl_*`/`dom_api_webgl*`.
+
+A bridge is the “strong reference” that makes the linker search the archive; with
+no bridge, the engine's table stays null and the implementation members are never
+extracted. That is why the large libraries can stay in the existing archives
+without a new package layout.
+
+Overrides: `--feature media,gpu,images,shaping,webgl` (or `all`) forces a
+feature on; `--no-feature media` keeps it out even when detection finds a use.
+`webgl` requires `gpu`, and the resolver activates both together. An app icon
+forces `images` because the icon is decoded through the same pipeline. `--ext media`
+is a deprecated alias for `--ext gui --feature media`. If an auto-detected
+feature's archive is missing, the build warns and continues (the element/context
+degrades as documented); a forced feature makes it an error.
+
+> Detection is static by design. A page that builds HTML/CSS from `fetch`,
+> `readFileSync` or other runtime data should pass `--feature all` (or the
+> specific feature). `--verbose` prints the selected set, e.g.
+> `xbintsc: link features: none`.
+
+### Binary size
+
+The lean build is what makes a DOM-only program small. On Windows x64 a
+`hello`-sized program drops from roughly 6.4 MiB to about 3.1 MiB once SDL is
+configured as above, function/data sections let `/OPT:REF` discard what the page
+never reaches, the WebGL/images link features stay off, and text uses the
+bundled stb_truetype instead of HarfBuzz + FreeType. The remaining weight is
+mostly the static CRT, the lean SDL (~1 MiB), stb_truetype (~0.1 MiB), and the
+DOM/CSS/layout/paint engine itself (~1.2 MiB). Linux and macOS use their own
+linker sections (`--gc-sections`/`-dead_strip`) and differ somewhat, but the
+relative ranking is the same.
+
+WebGL and images/SVG are link features (roughly 0.4 MiB of WebGL context/DOM
+code and 0.23 MiB of stb_image/NanoSVG that a DOM-only page does not link).
+Canvas2D, Web Audio and the `mix-blend-mode` compositor are not gated yet; a
+program that uses none of them still pays for their API surface (roughly
+0.1–0.2 MiB each).
+
+The text trade-off is deliberate. The default backend is stb_truetype: only
+TrueType outlines and a per-codepoint mapping plus the font's `kern` table, so
+CFF/OTF and variable fonts, OpenType ligatures and complex-script shaping
+(Arabic/Indic/Thai) are not available. The fallback chain still selects another
+face for codepoints the primary lacks. Selecting the optional **`shaping`**
+feature (automatically for non-ASCII text or an author `@font-face` rule, or
+with `--feature shaping`) links HarfBuzz + FreeType back in (~1.2 MiB) and
+restores full OpenType shaping and CFF/OTF/variable-font support. A Latin-only
+DOM page therefore stays near 3.1 MiB; a Chinese/complex-script page is closer
+to 4.3 MiB.
+
 ## Running the example
 
 ```sh
@@ -133,10 +250,11 @@ its README for controls and the geometry report it prints.
 
 `media.ts` (with `media.html`) demonstrates `<video>`/`<audio>`: it overlays a
 CSS progress bar on the video and drives playback with `play()` / `pause()` /
-`currentTime` / `volume`. It needs the separate `media` extension, so build and
-enable both. Media `src` paths resolve relative to the process working
+`currentTime` / `volume`. The compiler sees the elements in `media.html` and
+links the `media` feature automatically; build `media.a` once with
+`npm run media`. Media `src` paths resolve relative to the process working
 directory, so run it from the repository root:
-`xbintsc run examples/gui/media.ts --ext gui,media`.
+`xbintsc run examples/gui/media.ts --ext gui`.
 
 Set `XT_GUI_AUTOCLOSE_MS=<n>` to close all windows after `n` milliseconds,
 which the e2e test (`tests/e2e/gui-*.test.ts`) uses to run headlessly.

package/doc/gui/canvas.md

@@ -191,7 +191,7 @@ non-finite entries are ignored, an all-zero list means a solid line).
 
 Text: `measureText(text)` (returns `{ width }`), `fillText(text, x, y,
 maxWidth?)` and `strokeText(text, x, y, maxWidth?)`. Text is shaped with
-HarfBuzz and rasterised with FreeType (the same stack as HTML text) at the
+stb_truetype (shaped and rasterised) (the same stack as HTML text) at the
 transform's approximate scale. A positive `maxWidth` condenses advances and
 glyph bitmaps horizontally so the run is at most that wide (as the canvas API
 specifies) instead of being ignored.

package/doc/gui/dom.md

@@ -21,11 +21,26 @@ 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`
+`:nth-child(an+b)`, `:disabled`, `:checked`, plus the stateful `:hover`,
+`:focus`, `:focus-visible` (currently an alias of `:focus`) and `:active` (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`).
+subset), numbers, keywords and shorthands (`margin`/`padding`/`border`/`flex`/
+`font`/`outline`). `display: inline-flex`/`inline-grid` make a flex/grid
+container inline-level; `grid-area`, `aspect-ratio`, `letter-spacing`,
+`text-transform`, `writing-mode` (`vertical-rl`/`vertical-lr` text),
+`vertical-align` (length form), percentage `border-radius`, `background-size`
+(size + default repeat for `url()` layers) and `currentColor` are parsed too.
+`font-variant-numeric`, `text-wrap`, `text-rendering`, `touch-action`,
+`user-select`, `overscroll-behavior`, `scroll-behavior`, `isolation` and
+`vector-effect` are accepted but have no engine behaviour (the text stack exposes no OpenType features and the engine
+has no touch/selection/smooth-scroll subsystem); `cursor` maps to the SDL system
+cursor. A document rule may style SVG children with the presentation properties
+`fill`, `fill-opacity`, `fill-rule`, `stroke`, `stroke-opacity`, `stroke-width`,
+`stroke-dasharray`, `stroke-dashoffset`, `stroke-linecap` and `stroke-linejoin`;
+the serializer writes them into the inline `<svg>` markup as NanoSVG-readable
+inline styles. `skewX()`/`skewY()`/`skew()` transform functions are supported.
 `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
@@ -33,7 +48,8 @@ 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`.
+`filter`/`backdrop-filter` function lists, `text-shadow`, `box-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)`,

package/doc/gui/known-issues.md

@@ -22,6 +22,16 @@
   shader unroller; `WebGLRenderer` runs on the real backend and there is no
   Canvas2D fallback. Shadow maps (comparative `sampler2DShadow` targeting depth
   textures), cube textures/environment maps and HDR render targets are supported.
+- **Comparative samplers can miscompile on Intel Macs.** On an Intel GPU (seen
+  on Intel Iris Plus Graphics with macOS 26), the Metal shader compiler drops a
+  fragment function that calls `sample_compare`: the draw produces no pixels at
+  all, so `texture(sampler2DShadow, …)` reads black and shadow maps disappear.
+  The MSL is correct (`depth2d<float>` + `sample_compare`), the sampler carries
+  the comparison op, and the same program renders correctly once Metal GPU
+  shader validation is enabled — running with `MTL_SHADER_VALIDATION=1` makes
+  `tests/e2e/gui-webgl2-shadow-sampler.test.ts` pass on such a machine. That
+  points at the driver's shader compiler rather than the engine, so the
+  workaround is the environment variable; other Apple GPUs may not show it.
 
 
 
@@ -54,29 +64,37 @@
   *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: `background-clip`,
-  `background-position`/`size`/`repeat` and `backdrop-filter` compositing are not
-  implemented (`backdrop-filter` parses and cascades, but sampling the backdrop
-  needs an offscreen layer, so it paints nothing); `mix-blend-mode` and repeating
-  gradients are implemented (see [Rendering](./rendering.md)), but group
-  `opacity` is a per-shape alpha rather than a true group composite, and the
-  blend compositor is unavailable on the D3D12/DXIL backend, where groups fall
-  back to normal source-over painting;
-  `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. A background linear gradient remains
-  solid bands (18 strips, 64 while repeating), so a large soft ramp may show
-  slight banding; a radial gradient is rasterised per pixel into a texture
-  (capped at 1024 px per edge, then stretched, so a hard stop in a very large
-  box comes out slightly soft).
+- **CSS coverage is a deliberate subset.** Grid, `calc()` (including
+  nested arithmetic and `calc()` inside `min()`/`max()`/`clamp()`),
+  `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` (true Gaussian), `box-shadow` (outer/inset, spread,
+  multiple layers), `clip-path` (`inset`/`circle`/`ellipse`/`polygon`),
+  `filter` colour functions, `@keyframes` animations, the full `transition`
+  timing-function set, `letter-spacing`, `text-transform`, inline-level
+  `flex`/`grid`, `grid-area`, `aspect-ratio`, auto margins, percentage
+  `border-radius`, `outline`, `background-size` tiling for `url()` layers and
+  document CSS on SVG children (`fill`/`stroke`/…) are implemented. Known
+  limits: `background-clip`, `background-position` and `background-repeat`
+  remain unimplemented (`background-size` covers the tiled default);
+  `font-variant-numeric`, `text-wrap`, `text-rendering`, `touch-action`,
+  `user-select`, `overscroll-behavior`, `scroll-behavior`, `isolation` and
+  `vector-effect` are parsed but inert; vertical writing mode is text-only (nested/mixed content falls back to
+  horizontal); group `opacity` is
+  a per-shape alpha rather than a true group composite; the blend and
+  `backdrop-filter` compositors are unavailable on the D3D12/DXIL backend, where
+  groups fall back to normal source-over painting and the backdrop filter is
+  skipped. `filter: blur()` is still 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
+  (linear and radial) are rasterised per pixel into a texture and then stretched
+  when the box is larger than the texture (1024 px per edge for a radial ramp,
+  4096 px along the line for a linear one, which is only one texel thick across
+  it), so a hard stop in a very large box can come out slightly soft.
 - **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
@@ -111,6 +129,22 @@
   bottleneck. Inline `style="…"` attributes are re-parsed on each restyle of
   the element that carries them.
 
+- **Text shaping is a simple shaper.** stb_truetype handles Latin/CJK/Cyrillic/
+  Greek with basic `kern` and per-codepoint fallback, but it does not run
+  OpenType ligatures or complex-script shaping (Arabic/Indic/Thai), and it only
+  accepts TrueType outlines (no CFF/OTF or variable fonts). Colour emoji are not
+  rendered as colour. This is the price of the ~3 MiB DOM-only binary; the
+  optional `shaping` feature restores HarfBuzz + FreeType (and full
+  complex-script shaping).
+- **Link-feature detection is static.** `media`/`gpu`/`images`/`shaping`/`webgl` are selected from the
+  bundled HTML/CSS/TS (including imported `.html` and the CSS inlined from it).
+  A page that builds markup or CSS from runtime data (`fetch`, `readFileSync`,
+  a value returned by a function) cannot be seen; the scanner falls back to
+  enabling both when it can prove the sink is dynamic, but an opaque value that
+  it cannot classify needs an explicit `--feature media`/`gpu`/`images`/`shaping`/`webgl` (or `all`).
+  `--verbose` prints the selected set. See
+  [Link features](./build.md#link-features).
+
 ## Open questions
 
 - Whether Linux ships X11, Wayland, or both in the first cut. (Decision:
@@ -130,7 +164,8 @@
 - Windows: an MSVC-compatible `gui.lib` (COFF objects + `ar -M`/`llvm-ar`) is
   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
+  and uses VS's bundled LLVM), links a `gui` program that exercises the `media`
+  link feature, 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
@@ -139,12 +174,14 @@
 - **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
+  match `gui.lib`, and the auto-selected `media` feature 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
+  `vcvarsall` + bundled LLVM as a local build), links a `gui` program that
+  exercises the feature, 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