xbintsc 0.5.45 → 0.5.52

package/doc/gui.md

@@ -1,6 +1,6 @@
 # xbintsc GUI extension (self-hosted HTML/CSS renderer)
 
-Status: **M20** — features (M1–M15) are complete: HTML parsing, CSS selector
+Status: **M22** — 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
@@ -21,13 +21,15 @@ what `examples/gui/pelican-bike` — a playable 2D game — is built on. **M12**
 DOM node lifetime explicit (what a mutation releases, what it keeps) and gives the
 engine bounded memory: see [Node lifetime](./gui/dom.md#node-lifetime) and
 [Memory & GC](./gui/runtime.md#memory--gc). **M13** plays real
-`<video>`/`<audio>` — the optional `media` extension decodes them on the main
-thread with a vendored minimal FFmpeg, video frames go through the image texture
-path and audio to an SDL stream, with the DOM media API exposing
-`play`/`pause`/`currentTime`/… and media events. Enabling `gui` alone does not
+`<video>`/`<audio>` — the optional **`media` link feature** decodes them on the
+main thread with a vendored minimal FFmpeg, video frames go through the image
+texture path and audio to an SDL stream, with the DOM media API exposing
+`play`/`pause`/`currentTime`/… and media events. The compiler selects the
+feature from the program (a `<video>`/`<audio>` element, `new Audio()`,
+`decodeAudioData`, or markup built at run time), so a DOM/CSS program does not
 link FFmpeg. The browser globals also get a real `AudioContext`: a 48 kHz mixer
 in `runtime/ext_gui/audio_mixer.cpp` plus `decodeAudioData` (WAV in-engine,
-compressed formats through `media`) — see
+compressed formats through the `media` feature) — see
 [GUI API](./gui/api.md#web-audio).
 **M14** adds `<canvas>` with a self-written 2D software rasteriser (anti-aliased
 fills, paths, text and `drawImage`) uploaded through the image texture path —
@@ -38,17 +40,21 @@ 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).
+**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). glslang is an optional **`gpu` link feature** shared with `mix-blend-mode`; the WebGL context/DOM bindings are the separate **`webgl` feature**, which requires `gpu`. A DOM/2D-canvas page links neither.
 **M19** fills in the decorative CSS layer: `@media` queries, generated content
 (`::before`/`::after`), multi-layer linear/radial/repeating backgrounds,
 `text-shadow`, `clip-path`, `mix-blend-mode` (through an offscreen compositor)
-and the `filter` colour/shadow effects. `backdrop-filter` still needs a backdrop
-snapshot, and true group blur remains an approximation — see
+and the `filter` colour effects. See
 [Rendering](./gui/rendering.md#backgrounds-generated-content-and-effects-m19).
 **M20** makes large documents interactive: `@media` is evaluated once per rule,
 layout and paint share a bounded shaping cache, and a frame only does (and
 presents) the work a change requires — see
 [Performance](./gui/rendering.md#performance-m20).
+**M21** completes the value/animation gaps: `calc()` arithmetic everywhere a
+length is accepted, true Gaussian `text-shadow`/`box-shadow`, backdrop
+compositing, `@keyframes` and the full transition timing-function set. See
+[Rendering](./gui/rendering.md#backgrounds-generated-content-and-effects-m19)
+and [Animation](./gui/animation.md#css-animations-keyframes).
 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.
@@ -100,7 +106,8 @@ pages above.
 | 4 | The engine is **not self-hosted** (it is C/C++, not TS), but must not affect the compiler's platform-agnostic design. Delivered as a per-platform prebuilt archive linked via `nativeObjects`. |
 | 5 | The **event loop is generic**: the runtime exposes a generic main-loop hook and a poll primitive; nothing GUI-specific enters `runtime/`. |
 | 6 | **Multiple windows** are supported by the core object model. |
-| 7 | Third-party low-level libs are **statically linked into the extension archives** so releases stay self-contained; only OS frameworks are added at link time. `gui.a` carries SDL3/FreeType/HarfBuzz, and the optional `media.a` carries FFmpeg and is linked only with `--ext media`. |
+| 7 | Third-party low-level libs are **statically linked into the extension archives** so releases stay self-contained; only OS frameworks are added at link time. `gui.a` carries SDL3, FreeType/HarfBuzz for the optional `shaping` feature, glslang and (on macOS only) SPIRV-Cross; the default text path uses the bundled stb_truetype. glslang and SPIRV-Cross are only *extracted* when the compiler selects the **`gpu` link feature**; Metal is the only SDL_GPU backend that consumes MSL, so merging SPIRV-Cross elsewhere would add ~2.5 MiB no driver can ask for. The WebGL context/DOM code is the **`webgl` feature** (requires `gpu`), and stb_image/NanoSVG are the **`images` feature**. The optional `media.a` carries FFmpeg and is linked only when the **`media` link feature** is selected. All features are chosen from the program's static usage; `--feature`/`--no-feature` override the scan. |
+| 8 | **Heavy optional halves are link features, not extensions.** FFmpeg and glslang are selected by what the bundled HTML/CSS/TS may use, and a small C bridge (linked only when active) installs the feature's dispatch table and forces the linker to extract the implementation. This keeps one user-facing `gui` extension while a DOM-only program pays for neither stack. |
 
 ## Architecture
 
@@ -120,7 +127,7 @@ pages above.
                 │
                 ▼
         windowing + input (SDL3) ── multiple windows
-        text (HarfBuzz + FreeType) ── glyph atlas / SDF
+        text (stb_truetype) ── glyph atlas
         images (stb_image; SVG via NanoSVG)
         media DOM + audio sink ── optional media.a (FFmpeg) installs the decoder
 ```
@@ -134,14 +141,19 @@ with `nativeObjects()`, `linkerFlags()` and `modules()`.
 | --- | --- | --- |
 | Window + input + multi-window | **SDL3** | cross-platform windows, HiDPI, IME, clipboard, DnD, close/hide events |
 | GPU | **SDL_GPU** (SDL3) | one render path over Metal / Vulkan / D3D12; avoids three backends |
-| Text shaping | **HarfBuzz** | correct complex-script shaping |
-| Glyph raster | **FreeType** | glyph outlines → GPU atlas / SDF |
+| Text shaping | **stb_truetype** simple shaper; optional **`shaping`** feature links HarfBuzz + FreeType | default keeps the DOM-only binary near 3 MiB; `shaping` restores ligatures and complex-script shaping |
+| Glyph raster | **stb_truetype**; FreeType only under `shaping` | TrueType outlines → grayscale atlas by default |
 | Images | **stb_image** (vendored header) for bitmaps, **NanoSVG** (vendored headers) for SVG | single headers to start; SVG files rasterise on demand |
-| Video + audio | **FFmpeg** (statically vendored, minimal build, optional `media` extension) | decodes the common container/codec set; no WebView or platform media framework |
+| Video + audio | **FFmpeg** (statically vendored, minimal build, optional `media` link feature) | decodes the common container/codec set; no WebView or platform media framework |
 
-Pinned versions: SDL3 `release-3.2.10`, FreeType `2.13.3`, HarfBuzz `10.1.0`,
-FFmpeg `7.1` for the optional `media` archive (overridable with `SDL3_TAG` /
-`FREETYPE_VERSION` / `HARFBUZZ_VERSION` / `FFMPEG_VERSION`).
+Pinned versions: SDL3 `release-3.2.10`, FreeType `2.13.3`, HarfBuzz `10.1.0`
+(for the optional `shaping` feature), glslang `16.6.0`, SPIRV-Cross
+`vulkan-sdk-1.4.313.0`, FFmpeg `7.1` for the optional `media` archive
+(overridable with `SDL3_TAG` / `FREETYPE_VERSION` / `HARFBUZZ_VERSION` /
+`GLSLANG_VERSION` / `SPIRV_CROSS_VERSION` / `FFMPEG_VERSION`). The default text
+backend is the bundled `stb_truetype.h`; it accepts TrueType outlines (not
+CFF/OTF or variable fonts). The `shaping` feature swaps in HarfBuzz + FreeType
+for full OpenType shaping.
 
 Alternative if SDL3 is rejected: **GLFW + OpenGL 3.3** (simpler, but OpenGL is
 deprecated on macOS and gives no modern GPU abstraction). **wgpu-native** if the
@@ -169,10 +181,13 @@ engine were Rust.
 4. **M4 — paint + text + display list**
    - **M4a — display list + GPU shapes** ✅ background/border display list,
      rounded-rect SDL_GPU pipeline (`paint.*`, `renderer.*`).
-   - **M4b-1 — text stack + metrics** ✅ HarfBuzz + FreeType linked into
-     `gui.a`, font resolution/caching, shaping-based text metrics used by
-     layout (`text.*`, `measureText`/`fontMetrics`).
-   - **M4b-2 — glyph rendering** ✅ FreeType rasterisation, a shared shelf-packed
+   - **M4b-1 — text stack + metrics** ✅ the text module (`text.*`) with font
+     resolution/caching and shaping-based metrics used by layout
+     (`measureText`/`fontMetrics`); the CSS family list, weight and italic style
+     select real installed faces, and author `@font-face` rules load local font
+     files (relative URLs resolve as `file:` paths against the process working
+     directory). Originally HarfBuzz + FreeType, now the bundled stb_truetype.
+   - **M4b-2 — glyph rendering** ✅ stb_truetype rasterisation, a shared shelf-packed
      glyph atlas, textured text quads in the display list and HiDPI-aware raster
      scaling. Gradients remain.
 5. **M5 — input + events** ✅
@@ -186,8 +201,8 @@ engine were Rust.
      per-file GPU textures and textured quads (`image.*`, `svg.*`, `paint.*`,
      `renderer.*`).
    - **M6b — transitions/animations** ✅ `transition` shorthand + longhands,
-     animated `background-color`/`color`/`border-color`/`border-radius`, retargeting
-     and `win.advance(ms)`. `@keyframes` remain.
+     retargeting, `cubic-bezier()`/`steps()`, `win.advance(ms)` and (M21)
+     `@keyframes` with every animation longhand.
 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
@@ -199,16 +214,17 @@ engine were Rust.
      (`package-release` copies all of `runtime/`) and inside the optional
      `@xbintsc/<os>-<arch>` npm package. Windows x64 is included; Windows arm64
      still skips them.
-   - `vendor/` (SDL3/FreeType/HarfBuzz for the GUI archive, FFmpeg for `media`)
+   - `vendor/` (SDL3/FreeType/HarfBuzz/glslang 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
+   - Windows x64 builds both archives in CI and links a `gui` program that
+     exercises the `media` link feature (plus an explicit `--feature media`
+     build), 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
@@ -260,15 +276,17 @@ engine were Rust.
       `tests/e2e/gui-retention.test.ts` (see [Memory & GC](./gui/runtime.md#memory--gc)).
 13. **M13 — video & audio** ✅
     - `<video>` / `<audio>` decode through a statically vendored minimal FFmpeg
-      in the optional `media` extension (`runtime/ext_media/media.cpp`), frames
+      in the optional `media` link feature (`runtime/ext_media/media.cpp`); the
+      compiler selects it from the program and only then compiles the bridge and
+      links `media.a`. Frames
       upload to GPU textures through the existing image pipeline, audio is
       pushed to an SDL stream on the main thread by the GUI's audio sink, and
       the DOM media API plus `loadedmetadata`/`play`/`pause`/`ended`/
       `timeupdate`/`error` events are exposed on element handles
       (`dom_api_media.cpp`, `dom_api_proto.cpp`). Controlled from TS + CSS;
       there are no built-in controls. Example in `examples/gui/media.*`, e2e in
-      `tests/e2e/gui-media.test.ts` (with the `media` extension) and
-      `tests/e2e/gui-media-disabled.test.ts` (without it).
+      `tests/e2e/gui-media.test.ts` (auto-selected) and
+      `tests/e2e/gui-media-disabled.test.ts` (`--no-feature media`).
 14. **M14 — `<canvas>` 2D** ✅
     - `<canvas>` is a replaced element (`xtgui::Canvas2D`, `layout.*`), the
       `getContext("2d")` handle and drawing API live in `dom_api_canvas.cpp`,
@@ -336,16 +354,18 @@ engine were Rust.
     - 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 gradients painted bottom-up as
-      solid bands (18 strips) and radial gradients rasterised per pixel into one
-      image texture (`renderer_gradient.cpp`).
-    - `text-shadow` as shadow text runs, including a nine-tap blur approximate.
+    - Multi-layer `background-image` with linear and radial gradients rasterised
+      per pixel into one image texture (`renderer_gradient.cpp`), so hard stops
+      and sub-pixel details (a 1px divider) are exact.
+    - `text-shadow` and `box-shadow` (outer/inset, spread, multiple layers),
+      blurred with a true separable Gaussian over the shape mask (M21).
     - `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)).
+      `drop-shadow()`; `backdrop-filter` snapshots the scene, applies a Gaussian
+      and one combined colour matrix, and composites through the border-box mask
+      (M21).
     - E2E coverage in `tests/e2e/gui-effects.test.ts`; see
       [Rendering](./gui/rendering.md#backgrounds-generated-content-and-effects-m19).
 20. **M20 — rendering performance** ✅
@@ -360,6 +380,28 @@ engine were Rust.
       dirty frame, and redundant render-state binds removed.
     - `win.stats()`/`XT_GUI_PERF` counters and `tests/e2e/gui-perf.test.ts`; see
       [Performance](./gui/rendering.md#performance-m20).
+21. **M21 — CSS value/animation completeness** ✅
+    - `calc()` is parsed as an unresolved expression tree and resolved by both
+      layout (`toPx`) and paint; nested arithmetic, `calc()` inside
+      `min`/`max`/`clamp`, and calc in shadows/transforms/filters are covered.
+    - `box-shadow` (outer/inset, spread, multiple layers) and blurred
+      `text-shadow` are rasterised into a Gaussian mask, cached and composited
+      as one tinted image quad.
+    - `backdrop-filter` snapshots the painted scene and composites a Gaussian +
+      colour matrix through the border-box mask in a runtime-compiled shader.
+    - `@keyframes` plus every `animation-*` longhand (delay, iterations,
+      direction, fill mode, paused/running) share the property interpolator with
+      transitions; transitions now cover opacity, layout lengths, box shadows
+      and `cubic-bezier()`/`steps()`/`step-start`/`step-end`.
+    - E2E: `tests/e2e/gui-css-features.test.ts`.
+22. **M22 — CSS coverage for the boxing UI** ✅
+    - `letter-spacing`, `text-transform`, the `font` shorthand, length-form
+      `vertical-align`, `writing-mode` (text-only vertical layout), percentage
+      `border-radius`, `inline-flex`/`inline-grid`, `grid-area`, `aspect-ratio`,
+      auto margins, `outline` + `:focus-visible`/`:active`, `currentColor`,
+      `skewX()`/`skewY()`, `background-size` tiling for `url()` layers and
+      document CSS on SVG children (`fill`/`stroke`/…) are now honoured.
+    - E2E: `tests/e2e/gui-css-coverage.test.ts`.
 
 ## Progress log
 
@@ -373,9 +415,10 @@ engine were Rust.
   coverage.
 - **M4a** ✅ display list (`paint.*`) and the SDL_GPU 2D renderer with an MSL
   rounded-rect pipeline (`renderer.*`), `paintList`/`paintCount`, e2e coverage.
-- **M4b-1** ✅ FreeType + HarfBuzz fetched/built/merged into `gui.a`, the text
-  module (`text.*`) with font resolution, HarfBuzz shaping and FreeType metrics,
-  real text metrics in layout, `measureText`/`fontMetrics`, e2e coverage.
+- **M4b-1** ✅ the text module (`text.*`) with font resolution, shaping and
+  metrics, real text metrics in layout, `measureText`/`fontMetrics`, e2e
+  coverage. Originally HarfBuzz + FreeType; now stb_truetype (see the stack
+  table and the size trade-off in [build](./gui/build.md#binary-size)).
 - **M4b-2** ✅ glyph atlas + textured text pipeline in `renderer.*`, shaped text
   runs in `paint.*`, `xt_text_shape_run`/`xt_text_rasterize` in `text.*`, HiDPI
   raster scaling, e2e coverage.
@@ -430,17 +473,19 @@ engine were Rust.
   ratcheting upwards. `win.stats()` exposes the engine counters and
   `tests/e2e/gui-retention.test.ts` pins them; a game loop rewriting its sprite
   every frame now runs in constant memory (see [Memory & GC](./gui/runtime.md#memory--gc)).
-- **M13** ✅ `<video>` / `<audio>` support. The optional `media` extension
+- **M13** ✅ `<video>` / `<audio>` support. The optional `media` **link feature**
   vendors and builds a minimal static FFmpeg (`scripts/build-media.ts`) and
   merges it into `media.a` (or `media.lib` from clang-cl/MSVC objects on
-  Windows); `runtime/ext_media/media.cpp` decodes video to RGBA
+  Windows). The compiler selects the feature from the program and only then
+  compiles `media_bridge.c` and links `media.a`; a DOM/CSS program never links
+  FFmpeg. `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,
   `renderer_image.cpp` uploads each new video frame through the image texture
   path, and `dom_api_media.cpp` exposes `play`/`pause`/`load` plus the media
-  properties on element handles. `gui.a` stays FFmpeg-free; enabling `media`
-  without `gui` is rejected by the registry. `examples/gui/media.*` demonstrates
+  properties on element handles. `gui.a` stays FFmpeg-free.
+  `examples/gui/media.*` demonstrates
   the TS-plus-CSS-controls pattern and `tests/e2e/gui-media.test.ts` pins it.
 - **M14** ✅ `<canvas>` support. A new replaced element (`layout.*`) carries an
   intrinsic size from its `width`/`height` attributes (default `300x150`),
@@ -507,9 +552,27 @@ engine were Rust.
   `paint_background.cpp` resolves and paints it (radial layers become one
   `PaintGradient`, which `renderer_gradient.cpp` rasterises into a texture),
   `paint_effects.cpp` applies filter colour functions plus nine-tap
-  blur/drop-shadow and emits `text-shadow` runs, and
+  blur/drop-shadow, `paint_shadow.cpp` rasterises Gaussian text/box shadows,
+  `paint_backdrop.cpp` + `renderer_layer.cpp` composite `backdrop-filter`, and
   `paint_clip.cpp`/`renderer_clip.cpp` clip geometry against triangulated
   `clip-path` polygons. E2E: `tests/e2e/gui-effects.test.ts`.
+- **M22** ✅ CSS coverage for the boxing UI. The cascade/declaration parser
+  gained `letter-spacing`, `text-transform`, the `font` shorthand,
+  `vertical-align`, `writing-mode`, percentage `border-radius`, `outline`,
+  `background-size`, `currentColor` and the SVG presentation properties;
+  layout gained inline-level flex/grid, `grid-area`, `aspect-ratio`, auto
+  margins and text-only vertical writing mode; paint gained outline edges,
+  sized/tiled image backgrounds and rotated vertical text; `:focus-visible` is
+  an alias of `:focus` and `:active` is tracked from pointer down/up. E2E:
+  `tests/e2e/gui-css-coverage.test.ts`.
+- **M21** ✅ CSS value/animation completeness. `calc()` is parsed as an
+  unresolved expression tree and resolved by layout/paint; `box-shadow` and
+  blurred `text-shadow` use a separable Gaussian mask cached as a texture;
+  `backdrop-filter` gets an offscreen snapshot pass; `@keyframes` (plus every
+  `animation-*` longhand, delay, iteration, direction and fill mode) shares the
+  property interpolator with transitions, which now also cover opacity, layout
+  lengths, box shadows and `cubic-bezier()`/`steps()`. E2E:
+  `tests/e2e/gui-css-features.test.ts`.
 - **M20** ✅ rendering performance. `@media` is evaluated once per rule per
   restyle, generated content is skipped for sheets without `::before`/`::after`,
   and `:hover`/`:focus` only restyle when the sheet tracks them

package/doc/implemented/cli.md

@@ -29,6 +29,8 @@ default; `--no-check` skips it (and is part of the cache key). See
     --emit <kind>     exe | obj | ir (default: exe)
 -O0..-O3              Optimization level (default: -O2)
     --ext <names>     Comma separated extensions (e.g. node)
+    --feature <names> Force optional link features on (media,gpu,images,shaping,webgl,all)
+    --no-feature <n>  Keep optional link features out even when detected
     --ext-native <m>  Register a C++/Rust extension from a JSON manifest
     --config <path>   Use a project config (default: xbintsc.config.json)
     --no-config       Do not read any project config

package/doc/implemented/extensions.md

@@ -2,10 +2,16 @@
 
 > Part of [Implemented syntax and features](../implemented.md) · [简体中文](../zh-CN/implemented/extensions.md)
 
-Location: `src/extensions/registry.ts`, `src/extensions/node/`
+Location: `src/extensions/registry.ts`, `src/extensions/node/`, `src/extensions/link-feature.ts`, `src/driver/usage.ts`, `src/driver/link-features.ts`
 
-- An extension is a plain object: `runtimeSources()` (extra C sources), `linkerFlags()` (extra link flags), `builtins()` (global identifier → runtime symbol, uniform `(argc, argv)` ABI) and `modules()` (import specifier → named exports / namespace).
-- `ExtensionRegistry`: register / unregister / lookup / aggregate builtins, modules, runtime sources and link flags.
+- An extension is a plain object: `runtimeSources()` (extra C sources), `linkerFlags()` (extra link flags), `builtins()` (global identifier → runtime symbol, uniform `(argc, argv)` ABI), `modules()` (import specifier → named exports / namespace) and `linkFeatures()` (optional heavy capabilities).
+- `ExtensionRegistry`: register / unregister / lookup / aggregate builtins, modules, runtime sources, link flags and link features.
+- **Optional link features** (`media`, `gpu`, `images`, `shaping`, `webgl`):
+  - A feature declares `runtimeSources()` (a C bridge compiled only when active), `nativeObjects()` (archives linked only when active), `linkerFlags()`, optional `requires` (another feature it depends on) and `used(usage)`.
+  - The driver builds `ProgramUsage` from the bundled AST (`collectUsage` in `src/driver/usage.ts`): string literals (including imported HTML and inlined CSS), identifiers/property names, `getContext(...)` kinds, and whether markup can be built at run time. Simple `const` aliases are resolved; unresolved markup makes the program conservative.
+  - `resolveLinkFeatures` applies `--feature` / `--no-feature` (and `all`), expands `requires`, reports an unavailable auto-detected feature as a warning and a forced one as an error, and returns the bridges/archives/flags to link.
+  - The bridge is the strong reference: its constructor installs the feature's dispatch table and its references force the linker to extract the implementation. With no bridge, the table stays null and the implementation members are never linked.
+  - Current clients: `media` (FFmpeg, `runtime/ext_media/media_bridge.c` + `media.a`), `gpu` (glslang/SPIRV-Cross, `runtime/ext_gui/gpu_bridge.c` + `gpu_feature.cpp` inside `gui.a`), `images` (stb_image/NanoSVG, `runtime/ext_gui/image_bridge.c` + `image_feature.cpp`), `shaping` (HarfBuzz/FreeType, `runtime/ext_gui/text_bridge.c` + `text_hb.cpp`), and `webgl` (context/DOM bindings, `runtime/ext_gui/webgl_bridge.c` + `webgl_feature.cpp`, requiring `gpu`).
 - The built-in core extension `core`: exposes `print` (mapped to `xt_println`), always registered.
 - The Node extension `node`:
   - Modular organisation: `src/extensions/node/fs/` + `runtime/ext_node/fs/read_file.c`

package/doc/npm-package.md

@@ -69,8 +69,8 @@ The package does **not** contain:
 If npm skips the optional package (`--omit=optional`, a package manager that
 does not install optional dependencies, or a host the release does not build
 for), the driver falls back to compiling the C runtime from the shipped sources
-and caches the objects; that build works but is slower, and `--ext gui` /
-`--ext media` need the archive to be present.
+and caches the objects; that build works but is slower, and `--ext gui` (plus
+the auto-selected `media`/`gpu`/`images`/`shaping`/`webgl` link features) needs the archive to be present.
 
 ## Requirements
 
@@ -398,7 +398,7 @@ jobs:
 | --- | --- | --- |
 | Needs Node.js | Yes, 22+ | No |
 | First build | Links the prebuilt runtime from the optional platform package | Links the prebuilt runtime |
-| GUI / media extensions | Included on Linux/macOS and Windows x64 (the hosts the release builds them for) | Included in Linux/macOS and Windows x64 archives |
+| GUI engine + media archive | Included on Linux/macOS and Windows x64 (the hosts the release builds them for) | Included in Linux/macOS and Windows x64 archives |
 | Installation | `npm install` + lockfile / provenance | Download, verify `.sha256`, unpack |
 | Programmatic API | Yes | No (CLI only) |
 | Cross-compiles | No — host only | No — host only |
@@ -439,7 +439,7 @@ the same file under `node_modules/xbintsc/doc/ai/`.
 | The first build takes a long time | The optional `@xbintsc/<os>-<arch>` package was skipped (or this host has no prebuilt package), so the runtime C sources are compiled and cached. Check `npm ls @xbintsc/<os>-<arch>` and reinstall without `--omit=optional`; `--time` confirms. |
 | Permission errors writing `.xbintsc/` | Set `xbintsc_CACHE_DIR` to a writable directory, or run from a writable working directory. |
 | `module 'fs' is provided by the 'node' extension` | Add `--ext node`, or `"extensions": ["node"]` in the config. |
-| `GUI native library not found` / `media native library not found` | The optional platform package that ships `gui.a`/`gui.lib` or `media.a`/`media.lib` was skipped, or this host has no prebuilt GUI/media archive (Windows arm64). Reinstall without `--omit=optional`, use a Linux/macOS/Windows x64 release archive, or build the archive from a source checkout. |
+| `GUI native library not found` / `media native library not found` | The optional platform package that ships `gui.a`/`gui.lib` or `media.a`/`media.lib` was skipped, or this host has no prebuilt GUI/media archive (Windows arm64). Reinstall without `--omit=optional`, use a Linux/macOS/Windows x64 release archive, or build the archive from a source checkout. An auto-detected `media` feature with a missing archive only warns; `--feature media` makes it an error. |
 | `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/xbintsc.config.schema.json

@@ -48,6 +48,16 @@
       "items": { "type": "string" },
       "description": "Paths to native C++/Rust extension manifests."
     },
+    "features": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Optional link features to force on, e.g. [\"media\", \"gpu\", \"images\", \"shaping\", \"webgl\"] or [\"all\"]."
+    },
+    "noFeatures": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Optional link features to keep out even when auto-detection finds a use."
+    },
     "force": {
       "type": "boolean",
       "description": "Ignore the incremental cache."

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

@@ -30,27 +30,49 @@ transition 的属性时，会记录一个正在运行的 transition，并在每
 结束；引擎用真实帧间隔推进时钟（`XtDocument::advance`），`win.advance(ms)`
 让测试可以确定性地推进。
 
-- 支持的属性：`background-color`、`color`、`border-color`、
-  `border-radius` 与 `transform`；`transition: all` 覆盖它们。影响布局的
-  属性（width、position 等）仍不做动画——那会每帧重新布局——但 `transform`
-  是绘制期效果，因此为它做动画的代价只是每个被动画的盒子每帧一个矩阵
-  （见[布局](./layout.md#变换m15)）。
+- 支持的属性：`background-color`、`color`、`border-color`、`opacity`、
+  `border-radius`、`transform`、`text-shadow`、`box-shadow`、所有盒模型
+  偏移/尺寸长度（`width`/`height`/`top`/`left`/`margin-*`/`padding-*`/…）、
+  gap/flex-basis 长度，以及 `filter`（形状一致的滤镜列表会插值模糊长度、数值与
+  drop-shadow 颜色）；`transition: all` 覆盖整个列表。单位一致的长度会插值
+  （单位变化按 CSS 的离散回退处理），`opacity`、颜色与 `transform` 正常插值。
 - `transition` 简写与 `transition-property` / `-duration` / `-delay` /
-  `-timing-function` 长写都会被解析；时间值接受 `s` 与 `ms`；缓动函数为
-  `linear`、`ease`、`ease-in`、`ease-out` 与 `ease-in-out`（`ease` 是
-  smoothstep 近似）。
+  `-timing-function` 长写都会被解析；时间值接受 `s` 与 `ms`；简写/长写内
+  都接受 `calc()`。
+- 缓动函数支持 `linear`、`ease`、`ease-in`、`ease-out`、`ease-in-out`、
+  `cubic-bezier(x1, y1, x2, y2)`、`steps(n, start|end)` 及其 `jump-*` 拼写；
+  三次贝塞尔用数值求解，关键字曲线使用 CSS 控制点。
 - 在动画中途重定向会从当前插值启动一个新 transition，因此反转悬停会从它
   当前所在位置平滑动画。
 - `computedStyle()` 报告显示（已插值）的值，因此 transition 在测试中可直接
   观察。
 
-`transform` 列表按**逐项**插值（`document.cpp`、`xt_transform_interpolate`），
+`transform` 列表按**逐项**插值（`animation_values.cpp`、`xt_transform_interpolate`），
 这正是让常见的一对 `translateY(-4px) rotate(-0.35deg)` 与 `none` 之间平滑
 滑行而不是跳变的原因：缺失的一侧会用同类型的单位（identity）操作补齐。两个
 列表形状或单位对不上时（`rotate(10deg)` 对 `rotate(10rad)`，或函数个数不同）
 完全不做插值——transition 直接吸附到目标值，即 CSS 的离散回退，而不是一段
 看起来错误的扫过。
 
+## CSS 动画（`@keyframes`）
+
+`@keyframes` 会被解析进 `StyleSheet::keyframes`（`from`/`to`/百分比选择器产生的
+偏移会排序）。支持 `animation` 简写及全部 `animation-*` 长写：名称、时长、
+延迟、时间函数、迭代次数（含 `infinite`）、方向
+（`normal`/`reverse`/`alternate`/`alternate-reverse`）、填充模式
+（`none`/`forwards`/`backwards`/`both`）与 `paused`/`running`。
+
+当计算样式首次声明某个元素/名称时，`XtDocument` 启动一个活动动画；简写变化时
+重新启动，无关的 restyle 不会打断它。每帧把本地时间解析为迭代进度，**逐个
+关键帧区间**应用时间函数，并插值所有可动画属性。中间关键帧没有提到的属性会
+在最近两个声明了它的关键帧之间继续插值（因此 0% 与 100% 声明的 transform
+即使 50% 只改 `opacity` 也会贯穿全程）。缺失的 0%/100% 步骤使用元素的底层
+样式；`forwards`/`backwards` 在活动时间之外保持边缘值，`computedStyle()`
+报告动画后的值。
+
+动画与 transition 共享 `animation_values.cpp`，因此属性集合、阴影列表与
+`transform` 的 identity 补齐行为一致。
+
 ## CSS transform（M15）
 
 `transform` 与 `transform-origin` 作为*绘制期*效果得到支持
@@ -89,5 +111,6 @@ const tick = (t: number): void => {
 两种方式都由 `examples/gui/pelican-svg` 演示（逐帧摇摆 + 悬停时说明文字的
 transition），并由 `tests/e2e/gui-transform.test.ts` 固定住。
 
-动画仍需完成：`@keyframes` 动画与 `cubic-bezier(...)`。
+任意可动画长度都可以使用 `calc()`（例如
+`transition: width 300ms ease-out; width: calc(100% - 20px)`）。
 

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

@@ -128,7 +128,8 @@ requestAnimationFrame(frame);
 `getChannelData(i)` 是真正的 `Float32Array`，可以用代码逐样本填充。
 `decodeAudioData(bytes)` 返回解码后的 AudioBuffer Promise：WAV（PCM 8/16/24/32 位、
 IEEE float 32/64、A-law 与 µ-law）由引擎自身解码；MP3、AAC/M4A、Vorbis、Opus 与 FLAC
-需要可选的 `media` 扩展（`--ext gui,media`），以其中的 FFmpeg 解码器作为回退。
+需要可选的 `media` 链接特性（程序调用 `decodeAudioData` 时自动选中），以其中的
+FFmpeg 解码器作为回退。
 `bytes` 可以是 ArrayBuffer、类型化数组、Node `Buffer`，或 `fs.readFileSync`
 返回的原始字节字符串（本运行时没有专门的二进制类型，而该字符串的存储正是文件字节）。
 解码结果会重采样到上下文的 48 kHz，因此 `buffer.sampleRate` 与