xbintsc 0.5.45 → 0.5.52

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

@@ -24,7 +24,7 @@ if (gl == null) {
 - 上下文记录到自己的 SDL_GPU 命令缓冲。`clear`/`draw*` 保持一个渲染 pass 打开；只有缓冲区/纹理上传或切换 framebuffer 才会结束它，并以 `LOAD` 开始新 pass，因此绘图缓冲在多次绘制之间保留，和 WebGL 一样；没有上传的绘制不会中断 pass。
 - 每帧一次，在页面自己的渲染 pass 之前，引擎提交所有 WebGL 命令缓冲。随后图像管线把颜色纹理当作普通 `PaintImage` 采样，没有 CPU 拷贝。
 - WebGL 原点在左下，SDL_GPU 渲染目标原点在左上，因此帧缓冲按自上而下存储：转换 `viewport`/`scissor`，`readPixels` 再把行翻回去，合成器看到的是正立的纹理。
-- 固定功能状态变化（`blendFunc`、`depthFunc`、`cullFace`、`colorMask` 等）会改变所需的 `SDL_GPUGraphicsPipeline`，因此管线按（程序、顶点布局、状态）惰性创建，并缓存在程序上。
+- 固定功能状态变化（`blendFunc`、`depthFunc`、`cullFace`、`colorMask` 等）会改变所需的 `SDL_GPUGraphicsPipeline`，因此管线惰性创建并缓存在程序上。键是这次绘制的**内容**：程序、图元模式、顶点布局的哈希（属性位置、格式、偏移、缓冲 pitch 与输入速率）、反射出的固定功能状态、附件格式。它刻意**不**包含上下文的单调版本计数器（`attribs_version_`、`framebuffer_version_`）与 GPU 缓冲句柄：这些值在每次绑定 VAO、切换帧缓冲或重建缓冲时都会前进，却不改变管线；用它们做键会让每帧绑定多个布局的场景（three.js 每帧为每个几何体绑定一个 VAO）每帧重建全部管线 —— 实测每帧 248 次 `SDL_CreateGPUGraphicsPipeline`，且程序级缓存无界增长。`tests/e2e/gui-webgl-pipeline-cache.test.ts` 固定了稳态：布局相同、缓冲不同的两次绘制在首帧之后不再创建管线。
 
 ## 性能
 
@@ -118,7 +118,7 @@ transform feedback（入口为空操作：SDL_GPU 没有 transform feedback 阶
 
 管线按 SDL_GPU 设备接受的着色器格式创建：Vulkan 上用 **SPIR-V**（`SDL_GPU_SHADERFORMAT_SPIRV`，Windows/Linux 选择的后端），macOS 上用 **MSL**（`SDL_GPU_SHADERFORMAT_MSL`，Metal 后端）。两个后端共用同一个 GLSL 前端，因此在一个后端能编译的着色器在另一个上也能编译。如果设备的后端两种格式都不接受——Direct3D 12 需要 DXIL——`getContext("webgl")` 与 `getContext("webgl2")` 都会返回 `null`；2D canvas 与页面其余部分仍然正常。
 
-`npm run gui` 会拉取并构建 glslang 与 SPIRV-Cross，合并进 `gui.a` / `gui.lib`（见[打包与构建](./build.md)）；只用 2D canvas 或 DOM 的程序除了归档体积之外没有运行时开销。
+`npm run gui` 会拉取并构建 glslang 并合并进 `gui.a` / `gui.lib`；SPIRV-Cross **只在 macOS 上**合并，因为其他 SDL_GPU 后端都不消费 MSL（见[打包与构建](./build.md)）。两者都通过可选的 **`gpu` 链接特性**访问：编译器在程序可能调用 `getContext("webgl…")` 或使用 `mix-blend-mode` 时选中它，只有那时 bridge 才会把翻译器成员从 `gui.a` 里取出。WebGL context 与 DOM 绑定是单独的 **`webgl` 特性**，它依赖 `gpu`；只用 2D canvas 或 DOM 的程序既不链接 glslang、SPIRV-Cross，也不链接任何 `webgl_*` 成员（见[链接特性](./build.md#链接特性)）。
 
 ## 测试
 
@@ -140,4 +140,4 @@ transform feedback（入口为空操作：SDL_GPU 没有 transform feedback 阶
 
 着色器改写器会把 three.js 的 `#pragma unroll_loop_start` 循环展开为常量索引（否则其采样器数组无法通过 Vulkan GLSL），`.js` 资源加载器则避免渲染器自带的展开器重复处理。`WebGLRenderer` 在本引擎真正的 WebGL 2 后端上原样运行，**不再打包 Canvas2D 回退**。已用 three.js r160 通过 SDL_GPU 验证：`MeshBasicMaterial`、`MeshStandardMaterial`、`MeshPhongMaterial`、`CanvasTexture`、线性雾、环境光/平行光/点光/聚光/半球光、`Sprite`、`Line`、`Points` 与 `InstancedMesh`。
 
-本引擎子集之外的能力仍无法模拟：transform feedback 与 MSAA。立方体贴图/环境贴图、深度纹理、HDR/浮点渲染目标、压缩纹理与比较型 `sampler2DShadow` 采样都已可用（three.js 阴影贴图可在两个后端使用硬件深度比较）。需要 transform feedback 或 MSAA 的场景无法正确渲染；此前 Canvas2D 回退能显示的内容现在全部走 GPU。
+本引擎子集之外的能力仍无法模拟：transform feedback 与 MSAA。立方体贴图/环境贴图、深度纹理、HDR/浮点渲染目标、压缩纹理与比较型 `sampler2DShadow` 采样都已可用（three.js 阴影贴图可在两个后端使用硬件深度比较，Intel Mac 上的驱动问题见[已知问题](./known-issues.md)）。需要 transform feedback 或 MSAA 的场景无法正确渲染；此前 Canvas2D 回退能显示的内容现在全部走 GPU。

package/doc/zh-CN/gui.md

@@ -2,17 +2,19 @@
 
 > 语言 / Language：[English](../gui.md) | **简体中文**
 
-状态：**M20** —— 功能（M1–M15）已全部完成：HTML 解析、CSS 选择器匹配、层叠（cascade）、计算样式与布局（块级、行内、Flexbox 与 CSS 定位）均已就位，引擎还会**绘制**：它构建一个由矩形、图像与排版后的文本 run 组成的显示列表，并通过 SDL_GPU 渲染。输入事件会经过命中测试并投递给原生 TS 处理器，`:hover`/`:focus` 会被动态匹配，`<img>` 依据其固有尺寸确定大小并从纹理绘制——位图（PNG/JPEG/…）与 SVG 文件皆可，后者按绘制尺寸光栅化，因此矢量图保持清晰——CSS transition 会为绘制属性做动画。**M16** 让内联 `<svg>` 子树获得同样的处理：子树被序列化回 SVG 文档，并按绘制设备尺寸光栅化，因此图标不再需要单独的文件。**M8** 增加了交互式 DOM：具有稳定标识的元素句柄、变更操作（`appendChild`、`textContent`、`classList`、`style` 等）以及支持捕获/冒泡的元素级事件。**M9** 会提前编译 `<script>` 主体（内联与 `<script src>`）——参见 `gui-scripts.md`。**M10** 增加 `requestAnimationFrame` 以及若干 DOM 辅助方法。**M11** 增加 `position: relative`/`absolute`/`fixed` 及其偏移，`examples/gui/pelican-bike`（一个可玩的 2D 游戏）就构建在它之上。**M12** 明确了 DOM 节点生命周期（哪些变更释放、哪些保留），并让引擎内存有界：参见[节点生命周期](./gui/dom.md)与[内存与 GC](./gui/runtime.md)。**M13** 真正播放
-`<video>`/`<audio>`——可选的 `media` 扩展用 vendored 的最小 FFmpeg 在主线程解码，
+状态：**M22** —— 功能（M1–M15）已全部完成：HTML 解析、CSS 选择器匹配、层叠（cascade）、计算样式与布局（块级、行内、Flexbox 与 CSS 定位）均已就位，引擎还会**绘制**：它构建一个由矩形、图像与排版后的文本 run 组成的显示列表，并通过 SDL_GPU 渲染。输入事件会经过命中测试并投递给原生 TS 处理器，`:hover`/`:focus` 会被动态匹配，`<img>` 依据其固有尺寸确定大小并从纹理绘制——位图（PNG/JPEG/…）与 SVG 文件皆可，后者按绘制尺寸光栅化，因此矢量图保持清晰——CSS transition 会为绘制属性做动画。**M16** 让内联 `<svg>` 子树获得同样的处理：子树被序列化回 SVG 文档，并按绘制设备尺寸光栅化，因此图标不再需要单独的文件。**M8** 增加了交互式 DOM：具有稳定标识的元素句柄、变更操作（`appendChild`、`textContent`、`classList`、`style` 等）以及支持捕获/冒泡的元素级事件。**M9** 会提前编译 `<script>` 主体（内联与 `<script src>`）——参见 `gui-scripts.md`。**M10** 增加 `requestAnimationFrame` 以及若干 DOM 辅助方法。**M11** 增加 `position: relative`/`absolute`/`fixed` 及其偏移，`examples/gui/pelican-bike`（一个可玩的 2D 游戏）就构建在它之上。**M12** 明确了 DOM 节点生命周期（哪些变更释放、哪些保留），并让引擎内存有界：参见[节点生命周期](./gui/dom.md)与[内存与 GC](./gui/runtime.md)。**M13** 真正播放
+`<video>`/`<audio>`——可选的 **`media` 链接特性**用 vendored 的最小 FFmpeg 在主线程解码，
 视频帧走图像纹理路径、音频进入 SDL 流，DOM 媒体 API 暴露
-`play`/`pause`/`currentTime`/… 与媒体事件。只启用 `gui` 不会链接 FFmpeg。浏览器全局还带有真正可用的 `AudioContext`：`runtime/ext_gui/audio_mixer.cpp` 中的 48 kHz 混音器，以及 `decodeAudioData`（WAV 由引擎内解码，压缩格式经 `media`）——见 [GUI API](./gui/api.md#web-audio)。**M14** 增加了 `<canvas>`，配一个自研的 2D 软件光栅器（抗锯齿
+`play`/`pause`/`currentTime`/… 与媒体事件。编译器会从程序里判断是否需要它
+（`<video>`/`<audio>` 元素、`new Audio()`、`decodeAudioData`，或运行时拼出的 HTML），
+因此只做 DOM/CSS 的程序不会链接 FFmpeg。浏览器全局还带有真正可用的 `AudioContext`：`runtime/ext_gui/audio_mixer.cpp` 中的 48 kHz 混音器，以及 `decodeAudioData`（WAV 由引擎内解码，压缩格式经 `media` 特性）——见 [GUI API](./gui/api.md#web-audio)。**M14** 增加了 `<canvas>`，配一个自研的 2D 软件光栅器（抗锯齿
 填充、路径、文本与 `drawImage`），并经图像纹理路径上传——参见
 [Canvas](./gui/canvas.md)。**M15** 增加了 CSS `transform` /
 `transform-origin`：每个布局盒一个合成好的 `Matrix2D`，由显示列表一路带到
 渲染器，因此盒子（以及其中的文本、图像与子元素）可以被平移、缩放与旋转而
 不触发任何重排——再加上 `transition: transform`，这些姿态可以动画（自绘的示例
 `examples/gui/pelican-svg` 正是用它让矢量画动起来）。参见
-[布局](./gui/layout.md#变换m15)与[动画](./gui/animation.md#css-transformm15)。**M17** 增加了真正的 **WebGL 1.0**，**M18** 增加了 **WebGL 2.0**：`<canvas>.getContext("webgl2")` 接受 `#version 300 es` 着色器、顶点数组对象、实例化绘制与采样器对象，全部由内置 glslang 编译为 SPIR-V（Metal 上再由内置 SPIRV-Cross 转成 MSL）并通过 SDL_GPU 渲染，几何、光照、纹理采样与混合都在 GPU 上完成，页面直接合成颜色纹理而无须读回——见 [WebGL](./gui/webgl.md)。**M19** 补齐 CSS 装饰层：`@media` 查询、生成内容（`::before`/`::after`）、线性/径向/重复多层背景、`text-shadow`、`clip-path`、`mix-blend-mode`（通过离屏合成器）与 `filter` 颜色/阴影效果。`backdrop-filter` 仍需要背景快照，真正的组模糊也仍是近似——见[绘制](./gui/rendering.md#背景生成内容与特效m19)。**M20** 让大文档保持可交互：`@media` 每条规则只求值一次，布局与绘制共享一个有界的整形缓存，一帧只做（也只提交）变更所要求的工作——见[性能](./gui/rendering.md#性能m20)。本总览记录了锁定决策、架构、里程碑计划与当前进度；引擎本身按功能拆分在以上各页中。
+[布局](./gui/layout.md#变换m15)与[动画](./gui/animation.md#css-transformm15)。**M17** 增加了真正的 **WebGL 1.0**，**M18** 增加了 **WebGL 2.0**：`<canvas>.getContext("webgl2")` 接受 `#version 300 es` 着色器、顶点数组对象、实例化绘制与采样器对象，全部由内置 glslang 编译为 SPIR-V（Metal 上再由内置 SPIRV-Cross 转成 MSL）并通过 SDL_GPU 渲染，几何、光照、纹理采样与混合都在 GPU 上完成，页面直接合成颜色纹理而无须读回——见 [WebGL](./gui/webgl.md)。glslang 是可选的 **`gpu` 链接特性**，与 `mix-blend-mode` 共享；WebGL context/DOM 绑定是单独的 **`webgl` 特性**（依赖 `gpu`），两者都不用时不链接。**M19** 补齐 CSS 装饰层：`@media` 查询、生成内容（`::before`/`::after`）、线性/径向/重复多层背景、`text-shadow`、`clip-path`、`mix-blend-mode`（通过离屏合成器）与 `filter` 颜色效果——见[绘制](./gui/rendering.md#背景生成内容与特效m19)。**M20** 让大文档保持可交互：`@media` 每条规则只求值一次，布局与绘制共享一个有界的整形缓存，一帧只做（也只提交）变更所要求的工作——见[性能](./gui/rendering.md#性能m20)。**M21** 补齐取值/动画缺口：凡接受长度处都支持 `calc()` 算术、真正的 `text-shadow`/`box-shadow` 高斯模糊、背景合成、`@keyframes` 与完整的 transition 时间函数——见[绘制](./gui/rendering.md#背景生成内容与特效m19)与[动画](./gui/animation.md#css-动画keyframes)。本总览记录了锁定决策、架构、里程碑计划与当前进度；引擎本身按功能拆分在以上各页中。
 
 ## 目录
 
@@ -52,7 +54,8 @@
 | 4 | 引擎**非自托管**（它是 C/C++，不是 TS），但不得影响编译器的平台无关设计。以按平台预构建的归档形式交付，通过 `nativeObjects` 链接。 |
 | 5 | **事件循环是通用的**：运行时暴露一个通用主循环钩子与一个轮询原语；任何 GUI 特定的东西都不会进入 `runtime/`。 |
 | 6 | 核心对象模型支持**多窗口**。 |
-| 7 | 第三方底层库**静态链接进扩展归档**，使发布版保持自包含；链接时只额外加入操作系统框架。`gui.a` 携带 SDL3/FreeType/HarfBuzz，可选的 `media.a` 携带 FFmpeg，仅在 `--ext media` 时链接。 |
+| 7 | 第三方底层库**静态链接进扩展归档**，使发布版保持自包含；链接时只额外加入操作系统框架。`gui.a` 携带 SDL3、用于可选 `shaping` 特性的 FreeType/HarfBuzz、glslang 和（仅 macOS）SPIRV-Cross；默认文本路径使用内置 stb_truetype。glslang 与 SPIRV-Cross 只有在编译器选中 **`gpu` 链接特性**时才会被从归档里取出。Metal 是唯一消费 MSL 的 SDL_GPU 后端，其他平台合并 SPIRV-Cross 只会多出约 2.5 MiB 没有任何驱动会请求的代码。WebGL context/DOM 代码是 **`webgl` 特性**（依赖 `gpu`），stb_image/NanoSVG 是 **`images` 特性**。可选的 `media.a` 携带 FFmpeg，仅在选中 **`media` 链接特性**时链接。所有特性都由程序的静态用法决定，可用 `--feature`/`--no-feature` 覆盖。 |
+| 8 | **可选的重型部分做成链接特性，而不是独立扩展。** FFmpeg 与 glslang 由打包后的 HTML/CSS/TS 里可能用到的东西决定；只有特性启用时才会编译一个很小的 C bridge，它安装分发表并迫使链接器取出实现归档。这样用户仍然只看到 `gui` 一个扩展，而只做 DOM 的程序两套栈都不链接。 |
 
 ## 架构
 
@@ -72,12 +75,13 @@
                 │
                 ▼
         窗口 + 输入（SDL3）── 多窗口
-        文本（HarfBuzz + FreeType）── 字形图集 / SDF
+        文本（stb_truetype）── 字形图集
         图像（stb_image；SVG 经 NanoSVG）
-        媒体 DOM + 音频 sink ── 可选的 media.a（FFmpeg）安装解码器
+        媒体 DOM + 音频 sink ── 可选的 media 链接特性（media.a / FFmpeg）安装解码器
 ```
 
-引擎从不与编译器通信。编译器只看到一个带有 `nativeObjects()`、`linkerFlags()` 和 `modules()` 的 `Extension`。
+引擎从不与编译器通信。编译器只看到一个带有 `nativeObjects()`、`linkerFlags()`、
+`modules()` 和 `linkFeatures()` 的 `Extension`；FFmpeg 与 glslang 由后者按需选择。
 
 ## 技术栈（已确认）
 
@@ -85,14 +89,18 @@
 | --- | --- | --- |
 | 窗口 + 输入 + 多窗口 | **SDL3** | 跨平台窗口、HiDPI、IME、剪贴板、拖放、关闭/隐藏事件 |
 | GPU | **SDL_GPU**（SDL3） | 一条覆盖 Metal / Vulkan / D3D12 的渲染路径；避免三套后端 |
-| 文本整形 | **HarfBuzz** | 正确处理复杂文种的整形 |
-| 字形光栅化 | **FreeType** | 字形轮廓 → GPU 图集 / SDF |
+| 文本整形 | **stb_truetype** 简单整形；可选 **`shaping`** 特性链接 HarfBuzz + FreeType | 默认让 DOM-only 二进制约 3 MiB；`shaping` 恢复连字/复杂文种整形 |
+| 字形光栅化 | **stb_truetype**；仅 `shaping` 下用 FreeType | 默认 TrueType 轮廓 → 灰度图集 |
 | 图像 | 位图用 **stb_image**（vendored 头文件），SVG 用 **NanoSVG**（vendored 头文件） | 起步阶段用单头文件；SVG 文件按需光栅化 |
-| 视频 + 音频 | **FFmpeg**（静态 vendored，最小化构建，可选 `media` 扩展） | 解码常用容器/编码；不依赖 WebView 或平台媒体框架 |
+| 视频 + 音频 | **FFmpeg**（静态 vendored，最小化构建，可选 `media` 链接特性） | 解码常用容器/编码；不依赖 WebView 或平台媒体框架 |
 
-固定版本：SDL3 `release-3.2.10`、FreeType `2.13.3`、HarfBuzz `10.1.0`、
-FFmpeg `7.1`（供可选的 `media` 归档使用；可用 `SDL3_TAG` /
-`FREETYPE_VERSION` / `HARFBUZZ_VERSION` / `FFMPEG_VERSION` 覆盖）。
+固定版本：SDL3 `release-3.2.10`、FreeType `2.13.3`、HarfBuzz `10.1.0`
+（供可选的 `shaping` 特性使用）、glslang `16.6.0`、SPIRV-Cross
+`vulkan-sdk-1.4.313.0`、FFmpeg `7.1`（供可选的 `media` 归档使用；可用
+`SDL3_TAG` / `FREETYPE_VERSION` / `HARFBUZZ_VERSION` / `GLSLANG_VERSION` /
+`SPIRV_CROSS_VERSION` / `FFMPEG_VERSION` 覆盖）。默认文本后端是内置的
+`stb_truetype.h`；它只接受 TrueType 轮廓（不支持 CFF/OTF 或可变字体）。
+`shaping` 特性会换成 HarfBuzz + FreeType，提供完整 OpenType 整形。
 
 如果否决 SDL3，备选是 **GLFW + OpenGL 3.3**（更简单，但 OpenGL 在 macOS 上
 已弃用，且不提供现代 GPU 抽象）。如果引擎用 Rust 编写，则用 **wgpu-native**。
@@ -118,10 +126,12 @@ FFmpeg `7.1`（供可选的 `media` 归档使用；可用 `SDL3_TAG` /
 4. **M4 — 绘制 + 文本 + 显示列表**
    - **M4a — 显示列表 + GPU 图形** ✅ 背景/边框显示列表、圆角矩形 SDL_GPU
      管线（`paint.*`、`renderer.*`）。
-   - **M4b-1 — 文本技术栈 + 度量** ✅ HarfBuzz + FreeType 链接进 `gui.a`、
-     字体解析/缓存、供布局使用的基于整形的文本度量
-     （`text.*`、`measureText`/`fontMetrics`）。
-   - **M4b-2 — 字形渲染** ✅ FreeType 光栅化、共享的 shelf 打包字形图集、
+   - **M4b-1 — 文本技术栈 + 度量** ✅ 文本模块（`text.*`）与字体解析/缓存、
+     供布局使用的基于整形的文本度量（`measureText`/`fontMetrics`）；CSS 族名列表、
+     字重和斜体样式会选择真实安装的字面，作者的 `@font-face` 规则会加载本地字体
+     文件（相对 URL 按 `file:` 路径相对进程工作目录解析）。最初用 HarfBuzz +
+     FreeType，现在用内置 stb_truetype。
+   - **M4b-2 — 字形渲染** ✅ stb_truetype 光栅化、共享的 shelf 打包字形图集、
      显示列表中的带纹理文本四边形与感知 HiDPI 的光栅缩放。渐变仍待完成。
 5. **M5 — 输入 + 事件** ✅
    - 命中测试（`LayoutTree::hitTest`）、带负载投递给 TS 处理器的指针/滚轮/
@@ -132,9 +142,9 @@ FFmpeg `7.1`（供可选的 `media` 归档使用；可用 `SDL3_TAG` /
    - **M6a — 图像** ✅ stb_image 解码（位图）与 NanoSVG 光栅化（SVG 文件，按
      绘制像素尺寸）、`<img>` 替换元素布局、按文件 GPU 纹理与带纹理四边形
      （`image.*`、`svg.*`、`paint.*`、`renderer.*`）。
-   - **M6b — transition/动画** ✅ `transition` 简写 + 长写、对
-     `background-color`/`color`/`border-color`/`border-radius` 的动画、重定向
-     与 `win.advance(ms)`。`@keyframes` 仍待完成。
+   - **M6b — transition/动画** ✅ `transition` 简写 + 长写、重定向、
+     `cubic-bezier()`/`steps()`、`win.advance(ms)` 与（M21）`@keyframes`
+     及全部动画长写。
 7. **M7 — CI 与发布** ✅（Linux/macOS 构建） / 🚧（运行 + Windows arm64）
    - `compile-examples` 在 Linux 与 macOS 上构建 `gui.a` 与 `media.a`（必需），
      然后在 Linux 上的 Xvfb + lavapipe 下运行示例与 `tests/e2e/gui-*.test.ts`
@@ -144,11 +154,12 @@ FFmpeg `7.1`（供可选的 `media` 归档使用；可用 `SDL3_TAG` /
      因此两者都会随现有 runtime 归档一起发布（`package-release` 复制整个
      `runtime/`），也会打进可选的 `@xbintsc/<os>-<arch>` npm 包。Windows x64
      已包含；Windows arm64 仍跳过。
-   - `vendor/`（GUI 归档的 SDL3/FreeType/HarfBuzz，以及 `media` 的 FFmpeg，
+   - `vendor/`（GUI 归档的 SDL3/FreeType/HarfBuzz/glslang，以及 `media` 的 FFmpeg，
      缓慢的部分）按 OS/arch 缓存，以 `scripts/build-gui.ts` /
      `scripts/build-media.ts` 为键。Windows x64 有独立的源码 + FFmpeg 安装前缀
      缓存。
-   - Windows x64 在 CI 中构建两个归档并链接一个 `gui,media` 程序；托管 runner
+   - Windows x64 在 CI 中构建两个归档并链接一个会触发 `media` 链接特性的 `gui`
+     程序（另有一条显式 `--feature media` 的构建）；托管 runner
      没有 GPU/Vulkan 驱动，因此 GUI/媒体示例的*运行*仍为试验性（失败只记录
      日志而不标注运行）。Windows arm64 仍跳过两个归档（见
      [待决问题](./gui/known-issues.md)）。CI 通过
@@ -198,14 +209,16 @@ FFmpeg `7.1`（供可选的 `media` 归档使用；可用 `SDL3_TAG` /
     - `win.stats()` 暴露引擎计数器；e2e 覆盖见
       `tests/e2e/gui-retention.test.ts`（见[内存与 GC](./gui/runtime.md)）。
 13. **M13 — 视频与音频** ✅
-    - `<video>` / `<audio>` 通过可选的 `media` 扩展（`runtime/ext_media/media.cpp`）
-      使用静态 vendored 的最小 FFmpeg 解码，帧沿用现有图像管线上传到 GPU 纹理，
+    - `<video>` / `<audio>` 通过可选的 `media` **链接特性**（`runtime/ext_media/media.cpp`）
+      使用静态 vendored 的最小 FFmpeg 解码。编译器从程序里检测到媒体用法时才编译
+      `media_bridge.c` 并链接 `media.a`，只做 DOM/CSS 的程序不会链接 FFmpeg。
+      帧沿用现有图像管线上传到 GPU 纹理，
       音频由 GUI 的音频 sink 在主线程推送进 SDL 流，并在元素句柄上暴露 DOM
       媒体 API 与 `loadedmetadata`/`play`/`pause`/`ended`/`timeupdate`/`error`
       事件（`dom_api_media.cpp`、`dom_api_proto.cpp`）。由 TS + CSS 控制；没有
       内置控件。示例见 `examples/gui/media.*`；e2e 见
-      `tests/e2e/gui-media.test.ts`（启用 `media`）与
-      `tests/e2e/gui-media-disabled.test.ts`（不启用）。
+      `tests/e2e/gui-media.test.ts`（自动选中 `media`）与
+      `tests/e2e/gui-media-disabled.test.ts`（`--no-feature media`）。
 14. **M14 — `<canvas>` 2D** ✅
     - `<canvas>` 是一个替换元素（`xtgui::Canvas2D`、`layout.*`），
       `getContext("2d")` 句柄与绘制 API 位于 `dom_api_canvas.cpp`，自研的抗锯齿
@@ -262,15 +275,16 @@ FFmpeg `7.1`（供可选的 `media` 归档使用；可用 `SDL3_TAG` /
       特性）；`matchMedia()` 使用同一个求值器。
     - 生成内容：`::before`/`::after` 选择器、继承的伪样式、`content` 字符串/
       转义/`attr()`，以及不会泄漏到 DOM 遍历的合成布局盒。
-    - 多层 `background-image`：线性渐变自下而上按纯色带绘制（18 条），径向渐变
-      逐像素光栅化成一张图像纹理（`renderer_gradient.cpp`）。
-    - `text-shadow` 作为阴影文本 run，并带九次采样模糊近似。
+    - 多层 `background-image`：线性与径向渐变都逐像素光栅化成一张图像纹理
+      （`renderer_gradient.cpp`），硬色标与亚像素细节（1px 分割线）因此能精确绘制。
+    - `text-shadow` 与 `box-shadow`（外/内阴影、spread、多层）用形状掩码上的
+      真正可分离高斯模糊（M21）。
     - `clip-path` 多边形（`inset`/`circle`/`ellipse`/`polygon`）解析到设备空间，
       用耳切法三角化，并在 `renderer_clip.cpp` 中与图形几何求交——不需要模板/
       shader 改动。
     - `filter` 颜色函数、九次采样 `blur()` 与轮廓 `drop-shadow()`；
-      `backdrop-filter` 会解析并参与层叠，但需要离屏背景通道（见
-      [已知问题](./gui/known-issues.md)）。
+      `backdrop-filter` 对场景做快照、应用高斯与一个合并颜色矩阵，再通过
+      边框盒掩码合成（M21）。
     - e2e 覆盖见 `tests/e2e/gui-effects.test.ts`；参见
       [绘制](./gui/rendering.md#背景生成内容与特效m19)。
 20. **M20 — 渲染性能** ✅
@@ -283,6 +297,27 @@ FFmpeg `7.1`（供可选的 `media` 归档使用；可用 `SDL3_TAG` /
       冗余的渲染状态绑定。
     - `win.stats()`/`XT_GUI_PERF` 计数器与 `tests/e2e/gui-perf.test.ts`；参见
       [性能](./gui/rendering.md#性能m20)。
+21. **M21 — CSS 取值/动画完整性** ✅
+    - `calc()` 被解析为未求值表达式树，由布局（`toPx`）与绘制共同求解；支持
+      嵌套算术、`min`/`max`/`clamp` 内的 `calc()`，以及阴影/transform/filter
+      中的 calc。
+    - `box-shadow`（外/内阴影、spread、多层）与带模糊的 `text-shadow` 被
+      光栅化为高斯掩码，缓存后作为一个带色调的图像四边形合成。
+    - `backdrop-filter` 对已绘制场景做快照，用运行时编译的 shader 通过边框盒
+      掩码合成高斯 + 颜色矩阵。
+    - `@keyframes` 与全部 `animation-*` 长写（延迟、迭代、方向、填充模式、
+      paused/running）与 transition 共享属性插值器；transition 现在还覆盖
+      opacity、布局长度、box-shadow 以及
+      `cubic-bezier()`/`steps()`/`step-start`/`step-end`。
+    - e2e：`tests/e2e/gui-css-features.test.ts`。
+22. **M22 — 拳击界面的 CSS 覆盖** ✅
+    - `letter-spacing`、`text-transform`、`font` 简写、长度形式的
+      `vertical-align`、`writing-mode`（仅文本竖排）、百分比 `border-radius`、
+      `inline-flex`/`inline-grid`、`grid-area`、`aspect-ratio`、自动外边距、
+      `outline` + `:focus-visible`/`:active`、`currentColor`、`skewX()`/
+      `skewY()`、`url()` 图层的 `background-size` 平铺，以及 SVG 子元素上的
+      文档 CSS（`fill`/`stroke`/…）均已生效。
+    - e2e：`tests/e2e/gui-css-coverage.test.ts`。
 
 ## 进度日志
 
@@ -295,9 +330,9 @@ FFmpeg `7.1`（供可选的 `media` 归档使用；可用 `SDL3_TAG` /
   Flexbox、`getBoundingClientRect`/`layoutTree`、e2e 覆盖。
 - **M4a** ✅ 显示列表（`paint.*`）与带 MSL 圆角矩形管线的 SDL_GPU 2D 渲染器
   （`renderer.*`）、`paintList`/`paintCount`、e2e 覆盖。
-- **M4b-1** ✅ FreeType + HarfBuzz 获取/构建/合并进 `gui.a`、带字体解析的文本
-  模块（`text.*`）、HarfBuzz 整形与 FreeType 度量、布局中的真实文本度量、
-  `measureText`/`fontMetrics`、e2e 覆盖。
+- **M4b-1** ✅ 文本模块（`text.*`）、字体解析、整形与度量、布局中的真实文本度量、
+  `measureText`/`fontMetrics`、e2e 覆盖。最初用 FreeType + HarfBuzz，现在用
+  stb_truetype（见技术栈表与 [构建](./gui/build.md#二进制体积)中的体积取舍）。
 - **M4b-2** ✅ `renderer.*` 中的字形图集 + 带纹理文本管线、`paint.*` 中的
   整形文本 run、`text.*` 中的 `xt_text_shape_run`/`xt_text_rasterize`、
   HiDPI 光栅缩放、e2e 覆盖。
@@ -347,13 +382,15 @@ FFmpeg `7.1`（供可选的 `media` 归档使用；可用 `SDL3_TAG` /
   失效；收集器的触发阈值改为跟随存活集，而不再只升不降。`win.stats()` 暴露
   引擎计数器，`tests/e2e/gui-retention.test.ts` 对其做断言；每帧重写精灵的游戏
   循环现在内存恒定（见[内存与 GC](./gui/runtime.md)）。
-- **M13** ✅ `<video>` / `<audio>` 支持。可选的 `media` 扩展 vendored 并构建一个
-  最小化的静态 FFmpeg（`scripts/build-media.ts`），合并进 `media.a`；
+- **M13** ✅ `<video>` / `<audio>` 支持。可选的 `media` **链接特性** vendored 并构建一个
+  最小化的静态 FFmpeg（`scripts/build-media.ts`），合并进 `media.a`。编译器从程序里
+  选中该特性后才编译 `media_bridge.c` 并链接 `media.a`；只做 DOM/CSS 的程序不会链接
+  FFmpeg。
   `runtime/ext_media/media.cpp` 在主线程把视频解码为 RGBA 帧、把音频解码为
   48 kHz 立体声 PCM，`runtime/ext_gui/gui_media.cpp` 持有播放器、实现 SDL 音频
   sink 并在每帧推进媒体时钟与事件，`renderer_image.cpp` 把每个新视频帧沿图像纹理
   路径上传，`dom_api_media.cpp` 在元素句柄上暴露 `play`/`pause`/`load` 与媒体
-  属性。`gui.a` 不含 FFmpeg；只启用 `media` 而不启用 `gui` 会被注册表拒绝。
+  属性。`gui.a` 不含 FFmpeg。
   `examples/gui/media.*` 演示 TS + CSS 控件的模式，
   `tests/e2e/gui-media.test.ts` 对其做断言。
 - **M14** ✅ `<canvas>` 支持。新的替换元素（`layout.*`）从 `width`/`height`
@@ -410,9 +447,23 @@ FFmpeg `7.1`（供可选的 `media` 归档使用；可用 `SDL3_TAG` /
   `gradient_values.cpp` 建模背景层列表（线性/径向、形状/尺寸/位置/色标），
   `paint_background.cpp` 解算并绘制它（径向层变成一个 `PaintGradient`，由
   `renderer_gradient.cpp` 光栅化成纹理），`paint_effects.cpp` 应用滤镜颜色函数
-  与九次采样模糊/投影并生成 `text-shadow` run，`paint_clip.cpp`/
-  `renderer_clip.cpp` 对三角化的 `clip-path` 多边形裁剪几何。e2e 见
-  `tests/e2e/gui-effects.test.ts`。
+  与九次采样模糊/投影，`paint_shadow.cpp` 光栅化高斯文字/盒子阴影，
+  `paint_backdrop.cpp` + `renderer_layer.cpp` 合成 `backdrop-filter`，
+  `paint_clip.cpp`/`renderer_clip.cpp` 对三角化的 `clip-path` 多边形裁剪几何。
+  e2e 见 `tests/e2e/gui-effects.test.ts`。
+- **M22** ✅ 拳击界面的 CSS 覆盖。层叠/声明解析新增 `letter-spacing`、
+  `text-transform`、`font` 简写、`vertical-align`、`writing-mode`、百分比
+  `border-radius`、`outline`、`background-size`、`currentColor` 与 SVG 表现
+  属性；布局新增行内级 flex/grid、`grid-area`、`aspect-ratio`、自动外边距与
+  仅文本竖排；绘制新增 outline 边框条、按尺寸平铺的图像背景与旋转的竖排文字；
+  `:focus-visible` 目前等同 `:focus`，`:active` 由指针按下/抬起驱动。e2e：
+  `tests/e2e/gui-css-coverage.test.ts`。
+- **M21** ✅ CSS 取值/动画完整性。`calc()` 被解析为未求值表达式树，由布局/
+  绘制求解；`box-shadow` 与带模糊的 `text-shadow` 使用可缓存为纹理的可分离
+  高斯掩码；`backdrop-filter` 获得离屏快照通道；`@keyframes`（含全部
+  `animation-*` 长写、延迟、迭代、方向与填充模式）与 transition 共享属性插值器，
+  transition 现在还覆盖 opacity、布局长度、box-shadow 以及
+  `cubic-bezier()`/`steps()`。e2e 见 `tests/e2e/gui-css-features.test.ts`。
 - **M20** ✅ 渲染性能。`@media` 每次重算样式时每条规则只求值一次；没有
   `::before`/`::after` 的样式表完全跳过生成内容；只有样式表包含
   `:hover`/`:focus` 规则时才因这两个状态重算样式（`style.cpp`、

package/doc/zh-CN/implemented/cli.md

@@ -28,6 +28,8 @@ xbintsc help                        帮助
     --emit <kind>     exe | obj | ir（默认 exe）
 -O0..-O3              优化级别（默认 -O2）
     --ext <names>     逗号分隔扩展（如 node）
+    --feature <names> 强制开启可选链接特性（media,gpu,images,shaping,webgl,all）
+    --no-feature <n>  即使检测到也不链接该可选特性
     --ext-native <m>  从 JSON manifest 注册 C++/Rust 扩展
     --config <path>   使用项目配置（默认自动查找 xbintsc.config.json）
     --no-config       不读取任何项目配置

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

@@ -2,10 +2,16 @@
 
 > 属于[已实现语法与功能](../implemented.md) · [English](../../implemented/extensions.md)
 
-实现位置：`src/extensions/registry.ts`、`src/extensions/node/`
+实现位置：`src/extensions/registry.ts`、`src/extensions/node/`、`src/extensions/link-feature.ts`、`src/driver/usage.ts`、`src/driver/link-features.ts`
 
-- 扩展是普通对象：`runtimeSources()`（额外 C 源）、`linkerFlags()`（额外链接参数）、`builtins()`（全局标识符 → 运行时符号，统一 `(argc, argv)` ABI）与 `modules()`（导入说明符 → 命名导出 / 命名空间）。
-- `ExtensionRegistry`：注册 / 注销 / 查询 / 汇总 builtins、modules、runtime 源、链接参数。
+- 扩展是普通对象：`runtimeSources()`（额外 C 源）、`linkerFlags()`（额外链接参数）、`builtins()`（全局标识符 → 运行时符号，统一 `(argc, argv)` ABI）、`modules()`（导入说明符 → 命名导出 / 命名空间）与 `linkFeatures()`（可选的重型能力）。
+- `ExtensionRegistry`：注册 / 注销 / 查询 / 汇总 builtins、modules、runtime 源、链接参数与链接特性。
+- **可选链接特性**（`media`、`gpu`、`images`、`shaping`、`webgl`）：
+  - 特性声明 `runtimeSources()`（只在启用时编译的 C bridge）、`nativeObjects()`（只在启用时链接的归档）、`linkerFlags()`、可选的 `requires`（依赖的另一个特性）与 `used(usage)`。
+  - driver 从打包后的 AST 构造 `ProgramUsage`（`src/driver/usage.ts` 的 `collectUsage`）：字符串字面量（含导入 HTML 与内联 CSS）、标识符/属性名、`getContext(...)` 的 kind，以及 markup 是否可能在运行时拼出。简单的 `const` 别名会被解析；无法解析的 markup 让程序走保守回退。
+  - `resolveLinkFeatures` 应用 `--feature` / `--no-feature`（以及 `all`），展开 `requires`，把自动检测到但不可用的特性报为 warning、把强制开启却不可用的报为 error，并返回要链接的 bridge/归档/参数。
+  - bridge 就是强引用：构造函数安装特性的分发表，其引用迫使链接器取出实现；没有 bridge 时表保持 null，实现成员永不被链接。
+  - 当前客户端：`media`（FFmpeg，`runtime/ext_media/media_bridge.c` + `media.a`）、`gpu`（glslang/SPIRV-Cross，`runtime/ext_gui/gpu_bridge.c` + `gui.a` 内的 `gpu_feature.cpp`）、`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`）与 `webgl`（context/DOM 绑定，`runtime/ext_gui/webgl_bridge.c` + `webgl_feature.cpp`，依赖 `gpu`）。
 - 内置核心扩展 `core`：暴露 `print`（映射 `xt_println`），始终注册。
 - Node 扩展 `node`：
   - 模块化组织：`src/extensions/node/fs/` + `runtime/ext_node/fs/read_file.c`

package/doc/zh-CN/npm-package.md

@@ -63,7 +63,8 @@ TypeScript 编译器。
 
 如果 npm 跳过了这个可选包（`--omit=optional`、不安装可选依赖的包管理器，或发布
 未覆盖的宿主平台），驱动会回退到从随包源码编译 C 运行时并缓存目标文件；这样仍能
-工作，但首次构建更慢，`--ext gui` / `--ext media` 也需要归档存在。
+工作，但首次构建更慢，`--ext gui`（以及自动选择的 `media`/`gpu`/`images`/`shaping`/`webgl` 链接特性）也需要
+归档存在。
 
 ## 环境要求
 
@@ -372,7 +373,7 @@ jobs:
 | --- | --- | --- |
 | 需要 Node.js | 是，22+ | 否 |
 | 首次构建 | 链接可选平台包里的预编译运行时 | 直接链接预编译运行时 |
-| GUI / media 扩展 | Linux/macOS 与 Windows x64（发布为这些平台构建）包含 | Linux/macOS 与 Windows x64 压缩包包含 |
+| GUI 引擎 + media 归档 | Linux/macOS 与 Windows x64（发布为这些平台构建）包含 | Linux/macOS 与 Windows x64 压缩包包含 |
 | 安装方式 | `npm install` + lockfile / provenance | 下载、校验 `.sha256`、解压 |
 | 编程 API | 有 | 无（仅 CLI） |
 | 交叉编译 | 否——只构建宿主平台 | 否——只构建宿主平台 |
@@ -407,7 +408,7 @@ npm 包通过可选平台包获得同一套预编译运行时，只有在跳过
 | 第一次构建很慢 | 可选包 `@xbintsc/<os>-<arch>` 被跳过（或该宿主没有预编译包），正在编译并缓存运行时 C 源码。用 `npm ls @xbintsc/<os>-<arch>` 检查，并去掉 `--omit=optional` 重新安装；`--time` 可确认。 |
 | 写 `.xbintsc/` 权限错误 | 用 `xbintsc_CACHE_DIR` 指向可写目录，或在可写目录中运行。 |
 | `module 'fs' is provided by the 'node' extension` | 加 `--ext node`，或在配置里写 `"extensions": ["node"]`。 |
-| `GUI native library not found` / `media native library not found` | 携带 `gui.a`/`gui.lib` 或 `media.a`/`media.lib` 的可选平台包被跳过，或该宿主没有预编译的 GUI/media 归档（Windows arm64）。去掉 `--omit=optional` 重新安装，或使用 Linux/macOS/Windows x64 发布压缩包，或从源码检出构建。 |
+| `GUI native library not found` / `media native library not found` | 携带 `gui.a`/`gui.lib` 或 `media.a`/`media.lib` 的可选平台包被跳过，或该宿主没有预编译的 GUI/media 归档（Windows arm64）。去掉 `--omit=optional` 重新安装，或使用 Linux/macOS/Windows x64 发布压缩包，或从源码检出构建。自动检测到的 `media` 特性缺归档只会 warning；`--feature media` 才会报错。 |
 | `require("xbintsc")` 失败 | 包只提供 ESM；使用 `import`（或动态 `import()`）。 |
 | Windows 链接时报缺少 MSVC 库 | 在 Native Tools 命令提示符中运行，安装 VS C++ 生成工具，并检查 `npx xbintsc doctor`。 |
 | `npm ci --omit=dev` 后构建找不到 `xbintsc` | 在构建阶段安装 devDependencies，或把 `xbintsc` 移到 `dependencies`。 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xbintsc",
-  "version": "0.5.45",
+  "version": "0.5.52",
   "description": "xbintsc - a TypeScript binary compiler (TypeScript -> LLVM IR -> native binary)",
   "type": "module",
   "license": "MIT",
@@ -72,12 +72,12 @@
     "vitest": "^2.1.8"
   },
   "optionalDependencies": {
-    "@xbintsc/linux-x64": "0.5.45",
-    "@xbintsc/linux-arm64": "0.5.45",
-    "@xbintsc/darwin-x64": "0.5.45",
-    "@xbintsc/darwin-arm64": "0.5.45",
-    "@xbintsc/win32-x64": "0.5.45",
-    "@xbintsc/win32-arm64": "0.5.45"
+    "@xbintsc/linux-x64": "0.5.52",
+    "@xbintsc/linux-arm64": "0.5.52",
+    "@xbintsc/darwin-x64": "0.5.52",
+    "@xbintsc/darwin-arm64": "0.5.52",
+    "@xbintsc/win32-x64": "0.5.52",
+    "@xbintsc/win32-arm64": "0.5.52"
   },
   "engines": {
     "node": ">=22"