xbintsc 0.5.45 → 0.5.52

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

@@ -7,13 +7,29 @@
 - 源码位于 `runtime/ext_gui/`（C/C++），外加 `vendor/` 下的 vendored 库
   （被 gitignore；按需获取）。媒体解码位于 `runtime/ext_media/`，单独构建。
 - `npm run gui`（`scripts/build-gui.ts`）获取固定版本的 SDL3（`SDL3_TAG`，
-  默认 `release-3.2.10`），构建静态 SDL3，获取并构建静态 FreeType
-  （`FREETYPE_VERSION`）与 HarfBuzz（`HARFBUZZ_VERSION`），并获取、构建静态
+  默认 `release-3.2.10`），构建静态 SDL3，获取并构建静态 **FreeType**
+  （`FREETYPE_VERSION`，默认 `2.13.3`）与 **HarfBuzz**（`HARFBUZZ_VERSION`，
+  默认 `10.1.0`）供可选的 `shaping` 特性使用，并获取、构建静态
   **glslang**（`GLSLANG_VERSION`，默认 `16.6.0`）、固定版本的 SPIR-V 头文件
-  （`SPIRV_HEADERS_VERSION`）以及 **SPIRV-Cross**（`SPIRV_CROSS_VERSION`，默认
-  `vulkan-sdk-1.4.313.0`）。glslang 是 WebGL 背后的运行时 GLSL ES 编译器，
-  SPIRV-Cross 把它的 SPIR-V 转成 Metal 后端使用的 MSL（见
-  [WebGL](./webgl.md)），两者都与其他库一样合并进归档。随后编译引擎，并把
+  （`SPIRV_HEADERS_VERSION`）以及——**仅 macOS**——**SPIRV-Cross**
+  （`SPIRV_CROSS_VERSION`，默认 `vulkan-sdk-1.4.313.0`）。glslang 是 WebGL
+  背后的运行时 GLSL ES 编译器，SPIRV-Cross 把它的 SPIR-V 转成 Metal 后端使用的
+  MSL（见 [WebGL](./webgl.md)），两者都与其他库一样合并进归档。Metal 是唯一消费
+  MSL 的 SDL_GPU 后端，因此 Windows/Linux 上脚本既不获取也不合并 SPIRV-Cross：
+  那里的 `webgl_msl.cpp` 编译为空，合并进来只会多出约 2.5 MiB 不可达代码。
+  默认文本路径使用内置的 **stb_truetype**（`runtime/ext_gui/stb_truetype.h`）；
+  HarfBuzz/FreeType 只在 `shaping` 特性启用时被取出。
+  每个库（SDL3、FreeType、HarfBuzz、glslang、SPIRV-Cross 与引擎）都用
+  `-ffunction-sections -fdata-sections` 编译；SDL 关闭引擎从不调用的子系统
+  （`SDL_JOYSTICK`、`SDL_HAPTIC`、`SDL_SENSOR`、`SDL_CAMERA`、`SDL_RENDER`、
+  `SDL_OPENGL`/`SDL_OPENGLES`、`SDL_OFFSCREEN`、`SDL_HIDAPI`）；HarfBuzz 关闭
+  整形后端从不使用的 API（`HB_NO_DRAW`/`PAINT`/`COLOR`/`NAME`/`STYLE`/`METRICS`/…，
+  但保留 `CFF`/`OPEN`/`VAR` 以支持 OTF 与可变字体），并以
+  `HB_NO_PRAGMA_GCC_DIAGNOSTIC_ERROR` 编译：`src/hb.hh` 会把自身警告集提升为
+  错误，而两个精简宏（`HB_NO_MMAP` 与 `HB_NO_OT_FONT_GLYPH_NAMES`）会让
+  macOS/CoreText 的辅助函数变成未引用。链接器随后丢弃
+  不可达函数（`--gc-sections`、`-dead_strip` 或 link.exe 默认的 `/OPT:REF`）。
+  随后编译引擎，并把
   所有内容合并到 `runtime/lib/<os>-<arch>/gui.a`（Windows 上 MSVC ABI 则为
   `gui.lib`），与 `core.a` 采用相同约定，静态打包这些库。合并使用 macOS 上的
   `libtool` 与其他平台上的 `ar -M`（GNU/LLVM）；CMake 归档会在构建根目录或
@@ -23,12 +39,15 @@
   demuxer/parser/decoder 的最小静态构建，用它编译
   `runtime/ext_media/media.cpp`，并把所有内容合并到
   `runtime/lib/<os>-<arch>/media.a`（Windows 上 MSVC ABI 则为 `media.lib`）。
-  `gui.a` **不会**链接 FFmpeg：程序通过 `--ext media` 显式启用播放能力。
+  `gui.a` **不会**链接 FFmpeg：编译器为可能播放媒体的程序选中 `media` 链接特性后
+  才链接 `media.a`（见[链接特性](#链接特性)）。
 - `src/extensions/gui/index.ts` 通过 `nativeObjects()` 暴露引擎归档（经由
   `findRuntimeLibrary`，因此 `.a`/`.lib` 都可用），并通过 `linkerFlags()`
-  暴露操作系统框架。`src/extensions/media/index.ts` 对 `media.a`/`media.lib`
-  做同样的暴露，并把注册桥（`runtime/ext_media/media_bridge.c`）作为普通
-  runtime 源编译。
+  暴露操作系统框架。它的 `linkFeatures()`（位于
+  `src/extensions/gui/features.ts`）声明 `media`、`gpu`、`images`、`shaping` 与 `webgl`；driver 只在该特性
+  启用时编译对应的 bridge。
+- glslang（以及 macOS 上的 SPIRV-Cross）与 SDL3 一样合并进 `gui.a`，但引擎只
+  通过 `gpu` 特性的分发表访问它；从不编译 GLSL 的程序不会取出这些归档成员。
 - `scripts/build-gui.ts` 使用与驱动**相同**的 clang
   （`src/driver/toolchain-provider.ts`）；Windows 上就是 Visual Studio 自带的、
   面向 MSVC 的 LLVM，并配套使用其同目录下的 `clang++`/`llvm-ar` 来配置 CMake、
@@ -53,9 +72,10 @@
 - CI 在组装发布归档之前构建 `gui.a`/`gui.lib` 与 `media.a`/`media.lib`，因此它们
   会随 `runtime/lib/<slug>/` 一起发布（发布 tarball 会复制整个 `runtime/` 树）。
   同一批目录还会打进可选的 `@xbintsc/<slug>` npm 包，因此发布覆盖的宿主平台从
-  npm 安装后也能使用 `--ext gui`/`--ext media`。归档在 Linux（Xvfb 下，使用
+  npm 安装后也能使用 `--ext gui`（`media`/`gpu`/`images`/`shaping`/`webgl` 自动选择）。归档在 Linux（Xvfb 下，使用
   lavapipe 软件 Vulkan 驱动）与 macOS 上构建并运行
-  示例；Windows x64 也会构建两个归档并链接一个 `gui,media` 程序，因此 MSVC
+  示例；Windows x64 也会构建两个归档并链接一个会触发 `media` 特性的 `gui` 程序
+  （另有一条显式 `--feature media` 的构建），因此 MSVC
   构建在 CI 中得到验证，只是*运行*示例仍为试验性（托管 runner 没有 GPU/Vulkan
   驱动）。macOS 的运行同样是试验性的：Intel runner 的虚拟 GPU 缺少
   `MTLGPUFamilyMac2`，引擎会以 **77**（“此机器无法运行 GUI”）退出，任务记录为跳过，
@@ -69,8 +89,9 @@
   configure/make 构建树本身不缓存（其中记录了另一台机器的绝对路径与编译选项）。
 - 现有的缓存指纹已经会对 `nativeObjects()` 的内容与 `runtimeSources()` 的内容
   做哈希，因此重建任一归档都会自动使缓存二进制失效。
-- CMake 构建树位于其源码**旁边**（`vendor/sdl-build`、`vendor/freetype-build`、
-  `vendor/harfbuzz-build`），绝不放在源码内部：`CMakeCache.txt` 记录的是配置它
+- CMake 构建树位于其源码**旁边**（`vendor/sdl-build-lean`、
+  `vendor/freetype-build-lean`、`vendor/harfbuzz-build-lean`、
+  `vendor/glslang-build-lean`、`vendor/spirv-cross-build-lean`），绝不放在源码内部：`CMakeCache.txt` 记录的是配置它
   的那台机器，而 SDL 的视频后端是 `option()`，因此先运行的那次配置会一直生效。
   所以一个同时携带 `build/` 的 `vendor/SDL` 缓存树，会把某台机器的
   `SDL_X11`/`SDL_WAYLAND` 选择带进另一台机器的配置——即使头文件已安装，SDL 也会
@@ -79,6 +100,78 @@
   检查 X11/Wayland 头文件，并按名称报告缺失的开发包（当头文件位于该检查未知的
   前缀下时，可设置 `xbintsc_SKIP_HEADER_CHECK=1`）。
 
+## 链接特性
+
+用户只启用一个 `gui` 扩展，但其中的重型部分是可选的**链接特性**，按程序选择：
+
+| 特性 | 链接什么 | 程序可能用到时 |
+| --- | --- | --- |
+| `media` | `media_bridge.c` + `media.a`（FFmpeg） | HTML 里有 `<video>`/`<audio>`、`createElement("video"/"audio")`、`new Audio()`、`decodeAudioData`，或运行时拼出的 HTML |
+| `gpu` | `gpu_bridge.c`（实现本身已在 `gui.a`） | `getContext("webgl"/"webgl2"/"experimental-webgl")`（或运行时决定的 kind）、任意 `webgl` 字符串、`mix-blend-mode`/`mixBlendMode`，或运行时拼出的 HTML |
+| `images` | `image_bridge.c`（实现本身已在 `gui.a`） | `<img>`、内联 `<svg>`、`background-image`/`url(...)`、`.svg` 路径、`drawImage`/`createImageBitmap`/`Image`，或运行时拼出的 HTML |
+| `shaping` | `text_bridge.c`（实现本身已在 `gui.a`） | 非 ASCII 文本（CJK/西里尔/希腊文等）、转义或实体码点、作者的 `@font-face` 规则（自定义字体可能是 CFF/OTF），或运行时拼出的 HTML |
+| `webgl` | `webgl_bridge.c`（实现本身已在 `gui.a`，依赖 `gpu`） | WebGL 的 `getContext(...)`、`webgl` 字符串，或运行时拼出的 HTML |
+
+driver 会扫描打包后的 AST（`src/driver/usage.ts`）：所有字符串字面量（包括导入的
+`.html` 与内联进来的 CSS）、标识符与属性名、每个 `getContext(...)` 的 kind，以及
+HTML/CSS 是否可能来自编译器看不见的数据。简单的 `const` 别名会被解析；无法解析的
+markup 会让程序按“动态 markup”保守处理，启用可选特性。
+
+特性启用时，driver 只为本构建编译它的 C **bridge**，并链接在 `gui.a` 之前：
+
+- `media` → `runtime/ext_media/media_bridge.c`；构造函数安装解码表并引用
+  `xt_media_backend_*`，从而把 FFmpeg 成员从 `media.a` 里取出。
+- `gpu` → `runtime/ext_gui/gpu_bridge.c`；构造函数调用 `gpu_feature.cpp` 里的
+  `xt_gpu_feature_register`，安装 `XtGpuShaderApi` 表并引用 `compile_glsl` /
+  `cross_compile_msl` / 反射函数，从而取出 glslang（macOS 上还有 SPIRV-Cross）。
+- `images` → `runtime/ext_gui/image_bridge.c`；构造函数通过 `image_feature.cpp`
+  安装 `XtImageApi`，其引用取出 stb_image 与 NanoSVG。layout、paint、canvas
+  `drawImage` 与应用图标都走这张表，因此纯文本页面不链接这两个解码器。
+- `shaping` → `runtime/ext_gui/text_bridge.c`；构造函数通过 `text_hb.cpp` 安装
+  `TextApi`，其引用取出 HarfBuzz 与 FreeType。没有它时引擎使用内置 stb_truetype，
+  纯拉丁页面两个库都不链接。
+- `webgl` → `runtime/ext_gui/webgl_bridge.c`；构造函数通过 `webgl_feature.cpp` 安装
+  `XtWebglApi`，其引用取出 WebGL context 与 DOM 绑定。core 的 `getContext`、
+  canvas 宽高 setter、`createImageBitmap`、host type 与 renderer 都走这张表，因此
+  不用 WebGL 的页面不链接任何 `webgl_*`/`dom_api_webgl*`。
+
+bridge 就是让链接器搜索归档的“强引用”；没有 bridge 时引擎的表保持 null，
+实现成员永不被取出。因此大库可以留在现有归档里，不需要新的包布局。
+
+覆盖方式：`--feature media,gpu,images,shaping,webgl`（或 `all`）强制开启；
+`--no-feature media` 即使检测到也不链接。`webgl` 依赖 `gpu`，resolver 会一起
+激活；配置应用图标会强制 `images`，因为图标走同一条解码管线。`--ext media` 是
+`--ext gui --feature media` 的弃用别名。
+自动检测到的特性归档缺失时构建打印 warning 并继续（元素/上下文按文档降级）；
+显式强制的特性则报错。
+
+> 检测是静态的。用 `fetch`、`readFileSync` 等运行时数据拼 HTML/CSS 的页面应传
+> `--feature all`（或具体特性）。`--verbose` 会打印选中的集合，例如
+> `xbintsc: link features: none`。
+
+### 二进制体积
+
+DOM-only 程序的小体积来自上述 lean 构建。Windows x64 上，一个 `hello` 规模的程序
+从约 6.4 MiB 降到约 3.1 MiB：SDL 按上面的选项配置，function/data sections 让
+`/OPT:REF` 丢弃页面触达不到的函数，WebGL/图片链接特性保持关闭，文本改用内置
+stb_truetype 而不是 HarfBuzz + FreeType。剩余重量主要是静态 CRT、lean SDL
+（约 1 MiB）、stb_truetype（约 0.1 MiB）以及 DOM/CSS/layout/paint 引擎本身
+（约 1.2 MiB）。Linux 与 macOS 使用各自的链接器 section（`--gc-sections`/
+`-dead_strip`），数字会有差异，但相对排序相同。
+
+WebGL 与图片/SVG 是链接特性（约 0.4 MiB 的 WebGL context/DOM 代码与 0.23 MiB 的
+stb_image/NanoSVG，DOM-only 页面不链接）。Canvas2D、Web Audio 与
+`mix-blend-mode` 合成器尚未按需化；不使用它们的程序仍要付出其 API 面积（每项大约
+0.1–0.2 MiB）。
+
+文本替换是有意的取舍。默认后端是 stb_truetype：只接受 TrueType 轮廓，整形是逐码点
+映射加字体的 `kern` 表，因此 CFF/OTF 与可变字体、OpenType 连字以及复杂文种
+（阿拉伯/印度/泰文）整形不可用；fallback 链仍会在主字体缺字时切换到其他字体。
+选中可选的 **`shaping`** 特性（非 ASCII 文本或作者的 `@font-face` 规则会自动
+选中，也可用 `--feature shaping`）会重新链接 HarfBuzz + FreeType（约 1.2 MiB），
+恢复完整的 OpenType 整形与 CFF/OTF/可变字体支持。纯拉丁 DOM 页面因此保持约
+3.1 MiB；中文/复杂文种页面更接近 4.3 MiB。
+
 ## 运行示例
 
 ```sh
@@ -117,9 +210,10 @@ Chocolatey/独立 LLVM，CI、本地构建与预编译归档共用同一条编
 
 `examples/gui/media.ts`（配合 `media.html`）演示 `<video>`/`<audio>`：它在
 `<video>` 上叠一个 CSS 进度条，并用 `play()`/`pause()`/`currentTime`/
-`volume` 驱动播放。它需要单独的可选 `media` 扩展，因此要构建并同时启用两者。
+`volume` 驱动播放。编译器从 `media.html` 里看到这些元素后会自动选中 `media`
+特性；先用 `npm run media` 构建一次 `media.a`。
 媒体 `src` 相对于进程工作目录解析，因此从仓库根目录运行：
-`xbintsc run examples/gui/media.ts --ext gui,media`。几何报告见该目录的 README。
+`xbintsc run examples/gui/media.ts --ext gui`。几何报告见该目录的 README。
 
 这些测试套件在 Windows 上默认跳过（归档可以在本机通过 Vulkan 运行，但 CI
 runner 没有可用的 GPU 驱动）。如果本机有 `gui.lib` 与可用的 GPU，可用

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

@@ -156,7 +156,7 @@ canvas 由脚本重绘而不是引擎重绘，因此开销按绘制调用计。
 （奇数长度列表会复制一遍，负数/非有限值会被忽略，全零列表表示实线）。
 
 文本：`measureText(text)`（返回 `{ width }`）、`fillText(text, x, y, maxWidth?)` 与
-`strokeText(text, x, y, maxWidth?)`。文本经 HarfBuzz 排版、FreeType 光栅化（与 HTML
+`strokeText(text, x, y, maxWidth?)`。文本经 stb_truetype 整形与光栅化（与 HTML
 文本相同的技术栈），按变换的近似缩放绘制。正的 `maxWidth` 会按比例压缩步进与字形位图，
 使文本宽度不超过该值（与 canvas API 一致），而不是忽略该参数。**仅支持平移与均匀
 缩放**——旋转或斜切变换仍会把每个字形放到其变换后的基线点，但不会旋转字形位图。

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

@@ -20,11 +20,24 @@ doctype 跳过，实体解码（命名 + 十进制/十六进制），空元素
 （`=`、`~=`、`|=`、`^=`、`$=`、`*=`）、四种组合器（后代、子、相邻兄弟与
 通用兄弟）、伪类 `:first-child`、`:last-child`、`:only-child`、`:empty`、
 `:root`、`:not(...)`、`:nth-child(an+b)`、`:disabled`、`:checked`、有状态的
-`:hover` 与 `:focus`（见[输入](./input.md)），以及伪元素
+`:hover`、`:focus`、`:focus-visible`（目前等同 `:focus`）与 `:active`
+（见[输入](./input.md)），以及伪元素
 `::before`/`::after`（也接受旧式 `:before`/`:after`）。值：长度
 （`px`、`%`、`em`、`rem`、`vw`、`vh`、`pt`、`pc`、`in`、`cm`、`mm`、`q`）、
 颜色（十六进制、`rgb()`/`rgba()`、一个命名子集）、数字、关键字与简写
-（`margin`/`padding`/`border`/`flex`）。`transform`
+（`margin`/`padding`/`border`/`flex`/`font`/`outline`）。
+`display: inline-flex`/`inline-grid` 生成行内级 flex/grid 容器；`grid-area`、
+`aspect-ratio`、`letter-spacing`、`text-transform`、`writing-mode`
+（`vertical-rl`/`vertical-lr` 文本）、`vertical-align`（长度形式）、百分比
+`border-radius`、`background-size`（`url()` 图层按尺寸与默认 repeat 平铺）与
+`currentColor` 都已支持。`font-variant-numeric`、`text-wrap`、`text-rendering`、
+`touch-action`、`user-select`、`overscroll-behavior`、`scroll-behavior`、
+`isolation`、`vector-effect` 会被接受但不产生引擎行为（文本栈不暴露 OpenType 特性，引擎也没有触摸/选择/平滑滚动子系统）；
+`cursor` 映射到 SDL 系统光标。文档 CSS 可用 `fill`、`fill-opacity`、`fill-rule`、
+`stroke`、`stroke-opacity`、`stroke-width`、`stroke-dasharray`、
+`stroke-dashoffset`、`stroke-linecap`、`stroke-linejoin` 给 SVG 子元素上色；
+序列化器会把它们写成 NanoSVG 可读的内联样式。`skewX()`/`skewY()`/`skew()`
+变换函数也已支持。`transform`
 （`translate`/`translate3d`/`translateX`/`translateY`、
 `scale`/`scale3d`/`scaleX`/`scaleY`、`rotate`/`rotateZ`、`matrix`；`3d`
 拼写的 `z` 参数会被丢弃）与 `transform-origin`
@@ -32,7 +45,7 @@ doctype 跳过，实体解码（命名 + 十进制/十六进制），空元素
 函数会让整条声明失效（见[布局](./layout.md#变换m15)）。M19 增加了
 `background-image` 层列表（线性/径向）、`clip-path`
 （`inset`/`circle`/`ellipse`/`polygon`）、`filter`/`backdrop-filter` 函数列表、
-`text-shadow` 与 `content`。
+`text-shadow`、`box-shadow` 与 `content`。
 
 **层叠与计算样式**（`runtime/ext_gui/style.{h,cpp}`）：一份小的内置 UA
 样式表，作者规则按 `(!important, 特异性, 源码顺序)` 排序，然后是内联

package/doc/zh-CN/gui/known-issues.md

@@ -20,6 +20,15 @@
   `WebGLRenderer` 直接运行在真实后端上，不再有 Canvas2D 回退。阴影贴图
   （比较型 `sampler2DShadow` 采样深度纹理）、立方体贴图/环境贴图与 HDR 渲染目标
   均已支持。
+- **部分 Intel Mac 上比较型采样器会被错误编译。** 在 Intel GPU（在 Intel Iris
+  Plus Graphics + macOS 26 上观察到）上，Metal 着色器编译器会丢弃调用
+  `sample_compare` 的片元函数：绘制不产生任何像素，于是
+  `texture(sampler2DShadow, …)` 读到黑色，阴影贴图消失。MSL 本身是正确的
+  （`depth2d<float>` + `sample_compare`），采样器也带比较操作，而同一个程序在
+  打开 Metal GPU 着色器校验后渲染正常——在这类机器上以
+  `MTL_SHADER_VALIDATION=1` 运行即可让
+  `tests/e2e/gui-webgl2-shadow-sampler.test.ts` 通过。这指向驱动的着色器编译器
+  而非引擎，因此以环境变量作为绕过办法；其他 Apple GPU 未必存在该问题。
 
 
 - **自动关闭时的偶发崩溃。** 设置 `XT_GUI_AUTOCLOSE_MS` 结束运行时，约五次中有两次会以原生
@@ -39,21 +48,30 @@
   `tests/e2e/gui-example-browser.test.ts` 中。
 - **`display: none -> flex` 的重排。** 通过类名切换让隐藏元素显示在 flex 容器上时，也曾观察
   到同样的崩溃；`examples/gui/pelican-bike` 改用 `opacity` 显示游戏结束遮罩。
-- **CSS 覆盖范围是有意为之的子集。** 已实现 Grid、`clamp()`/`min()`/`max()`/`env()`、
+- **CSS 覆盖范围是有意为之的子集。** 已实现 Grid、`calc()`（含嵌套算术及
+  `min()`/`max()`/`clamp()` 内的 `calc()`）、`clamp()`/`min()`/`max()`/`env()`、
   `var()` 自定义属性、`inset` 简写、`box-sizing`、`visibility`/`pointer-events`、
   `@media` 查询、生成内容（`::before`/`::after`）、线性/径向多层背景、
-  `text-shadow`、`clip-path`（`inset`/`circle`/`ellipse`/`polygon`）以及 `filter`
-  的颜色函数。仍有限制：`background-clip`、`background-position`/`size`/`repeat`
-  与 `backdrop-filter` 合成都未实现（`backdrop-filter` 会解析并参与层叠，但采样
-  背景需要离屏图层，因此不绘制）；`mix-blend-mode` 与重复渐变已实现（见
-  [渲染](./rendering.md)），但组 `opacity` 是按图形 alpha 近似而非真正的组合成，
-  且 D3D12/DXIL 后端没有混合合成器，那里会退回普通 source-over 绘制；
-  `filter: blur()` 是按图形做九次偏移的近似，而不是真正的组模糊，重叠的子元素会加深；
-  `drop-shadow` 用盒子轮廓近似；最多只交叉两层嵌套 `clip-path`（更深时保留外侧两层）；
+  `text-shadow`（真正的高斯）、`box-shadow`（外阴影/内阴影、spread、多层）、
+  `clip-path`（`inset`/`circle`/`ellipse`/`polygon`）、`filter` 颜色函数、
+  `@keyframes` 动画、完整的 `transition` 时间函数、`letter-spacing`、
+  `text-transform`、行内级 `flex`/`grid`、`grid-area`、`aspect-ratio`、自动
+  外边距、百分比 `border-radius`、`outline`、`url()` 图层的 `background-size`
+  平铺，以及 SVG 子元素上的文档 CSS（`fill`/`stroke`/…）均已实现。仍有限制：
+  `background-clip`、`background-position`、`background-repeat` 未实现
+  （`background-size` 只覆盖默认平铺场景）；`font-variant-numeric`、
+  `text-wrap`、`text-rendering`、`touch-action`、`user-select`、
+  `overscroll-behavior`、`scroll-behavior`、`isolation`、`vector-effect`
+  可解析但不产生行为；竖排书写模式仅
+  支持文本（嵌套/混排内容回退横排）；组 `opacity` 是按图形 alpha
+  近似而非真正的组合成；D3D12/DXIL 后端没有混合与 `backdrop-filter` 合成器，
+  那里会退回普通 source-over 绘制并跳过背景滤镜。`filter: blur()` 仍是按图形做
+  九次偏移的近似，而不是真正的组模糊，重叠的子元素会加深；`drop-shadow` 用盒子
+  轮廓近似；最多只交叉两层嵌套 `clip-path`（更深时保留外侧两层）；
   图像/画布除图像着色器能携带的亮度与透明度染色外不做颜色滤镜。Canvas 纹理使用
-  最近邻采样。背景线性渐变仍是纯色带（18 条，重复渐变 64 条），较大的柔和渐变
-  可能出现轻微条带；径向渐变则逐像素光栅化成纹理（每边最大 1024 px，超出后拉伸，
-  因此超大盒子上的硬色标会略微变软）。
+  最近邻采样。背景渐变（线性与径向）都逐像素光栅化成纹理，盒子大于纹理时再拉伸
+  （径向每边最大 1024 px；线性沿渐变线最大 4096 px，且沿渐变线之外只有一像素厚），
+  因此超大盒子上的硬色标会略微变软。
 - **SVG 是 NanoSVG 的子集。** SVG *文件*（`<img src="logo.svg">`）与内联
   `<svg>` 子树共用 vendored 的 NanoSVG 解析/光栅化器（`runtime/ext_gui/svg.cpp`、
   `inline_svg.cpp`），它会渲染 `path`/`rect`/`circle`/`ellipse`/`line`/
@@ -79,6 +97,17 @@
   `win.stats()` 的 `textCacheBytes`/`textShapeHits` 能看出它是否成为瓶颈。
   元素自带的 `style="…"` 内联属性在该元素每次重算样式时都会重新解析。
 
+- **文本整形是简单整形器。** stb_truetype 覆盖拉丁/CJK/西里尔/希腊文、基础
+  `kern` 与逐码点回退，但不执行 OpenType 连字或复杂文种（阿拉伯/印度/泰文）整形，
+  且只接受 TrueType 轮廓（不支持 CFF/OTF 或可变字体）；彩色 emoji 也不会以彩色
+  渲染。这是 DOM-only 二进制约 3 MiB 的代价；可选的 `shaping` 特性会重新链接
+  HarfBuzz + FreeType，恢复完整整形。
+- **链接特性检测是静态的。** `media`/`gpu`/`images`/`shaping`/`webgl` 从打包后的 HTML/CSS/TS（包括导入的
+  `.html` 与其内联 CSS）里选择。用运行时数据（`fetch`、`readFileSync`、函数返回值）
+  拼 HTML/CSS 的页面无法被看到；扫描器在能证明 sink 是动态时会保守地启用可选特性，
+  但对于它无法分类的不透明值，需要显式 `--feature media`/`gpu`/`images`/`shaping`/`webgl`（或 `all`）。
+  `--verbose` 会打印选中的集合。见[链接特性](./build.md#链接特性)。
+
 ## 待决问题
 
 - Linux 首发是只发布 X11、Wayland，还是两者都发布。（决定：先 X11，
@@ -97,7 +126,8 @@
 - Windows：`scripts/build-gui.ts` 会生成 MSVC 兼容的 `gui.lib`
   （COFF 对象 + `ar -M`/`llvm-ar`）。Windows x64 的 CI job 使用 Visual Studio
   工具链（`.github/actions/vs-toolchain` 导入 `vcvarsall` 并采用 VS 自带的
-  LLVM）构建它、链接一个 `gui,media` 程序，并随 x64 发布归档一起发布。示例在
+  LLVM）构建它、链接一个会触发 `media` 链接特性的 `gui` 程序，并随 x64 发布归档
+  一起发布。示例在
   托管 runner 上的*运行*仍为试验性，因为那里没有 GPU/Vulkan 驱动（SDL_GPU 在
   Windows 上选择 **Vulkan** 后端，因此不需要 DXIL/`dxc` 工具链）。Windows
   arm64 仍跳过两个归档。在开发者机器上构建并运行
@@ -105,12 +135,12 @@
 - **Windows：x64 在 CI 中构建，arm64 与运行时验证仍为试验性。**
   `scripts/build-media.ts` 用 FFmpeg 的 MSVC 工具链
   （`--toolchain=msvc --cc=clang-cl`）生成 `media.lib`，其 COFF 对象与静态 CRT
-  和 `gui.lib` 一致，`--ext media` 在 Windows 上可以正常链接并播放。构建它需要
+  和 `gui.lib` 一致，自动选中的 `media` 特性在 Windows 上可以正常链接并播放。构建它需要
   POSIX shell 运行 FFmpeg 的 `configure` 以及 GNU make；shell 来自 Git for
   Windows（克隆 SDL3 本来就需要 Git），make 是原生 GNU make（Chocolatey 的
   `make`，或 `xbintsc_MAKE`）。CI 会显式安装 make，在
   Windows x64 上使用与本地构建相同的 Visual Studio `vcvarsall` + 自带 LLVM
-  构建 `gui.lib` 与 `media.lib`，链接 `gui,media` 程序，并把两个归档放进
+  构建 `gui.lib` 与 `media.lib`，链接一个会触发该特性的 `gui` 程序，并把两个归档放进
   Windows x64 发布包；示例的*运行*仍因托管 runner 没有 GPU/Vulkan 驱动而保持
   试验性。Windows arm64 仍跳过两个归档；`<video controls>` 同样推迟——预期模式
   是 TS + CSS 叠层，如 `examples/gui/media.ts`。

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

@@ -18,11 +18,14 @@
   基于单词的断行、`text-align` 与 `line-height`。行内元素获得其后代几何信息
   的并集；`display: inline-block` 以 shrink-to-fit 宽度原子化布局。每一行会收缩到
   与之重叠的浮动（`float: left|right`）所留出的空白带，因此后续行会绕开它们。
-  每个文本片段会记住它覆盖的 run，以便绘制时对它整形。文本使用 HarfBuzz/FreeType
+  每个文本片段会记住它覆盖的 run，以便绘制时对它整形。文本使用 stb_truetype
   技术栈测量（见[文本技术栈](./rendering.md)）。
 - **Flexbox** —— `row`/`column`（以及 `-reverse` 变体），支持 `gap`、
   `flex-basis`/`flex-grow`/`flex-shrink`、`justify-content` 与 `align-items`
-  （当交叉轴尺寸确定时包括 `stretch`）。`flex-wrap: wrap` 会把项断成多行，
+  （当交叉轴尺寸确定时包括 `stretch`）。两个方向的主轴尺寸都先取
+  `flex-basis`（为 `auto` 时用测量尺寸）：有剩余空间按 `flex-grow` 分配，
+  空间不足按 `flex-shrink` 收缩；单个项的 `align-self` 可覆盖容器的
+  `align-items`。`flex-wrap: wrap` 会把项断成多行，
   `align-content`（`stretch`/`flex-start`/`flex-end`/`center`/`space-between`/
   `space-around`）在交叉轴上分配这些行，`wrap-reverse` 则翻转交叉轴。
   flex 项的外边距参与其外框尺寸，因此
@@ -33,11 +36,25 @@
   `repeat(...)`）、`gap`/`row-gap`/`column-gap`、按行自动放置、简单的
   `grid-column`/`grid-row` 线定位，以及 `align/justify-items` 与
   `align/justify-self`（含 `place-items`/`place-self`）。隐式行/列由项目撑开；
-  单单元格网格配合 `place-items: center` 可把卡片居中到整个覆盖层。项目测量是
+  网格高度确定时，先布置固定行与 auto 行，剩余高度再按 `fr` 分给 `fr` 行，
+  因此 `aspect-ratio` 可以驱动 `repeat(n, 1fr)` 网格。单单元格网格配合
+  `place-items: center` 可把卡片居中到整个覆盖层。项目测量是
   两遍布局（先固有尺寸、再最终放置），因此两遍之间会清空文本片段。
-- **CSS 值函数与自定义属性** —— `clamp(min, value, max)`、`min(...)` 与
-  `max(...)` 在计算样式中保留参数，布局时结合元素字号与视口（`vw`/`vh`）求值；
-  桌面窗口中 `env(safe-area-inset-*)` 解析为 0。`var(--name[, fallback])` 在
+- **行内级容器、自动外边距与宽高比** —— `display: inline-flex`/`inline-grid`
+  仍用 flex/grid 算法排列子元素，但作为单个原子行内盒参与父级行流
+  （`vertical-align` 的长度值会平移它）。块级盒的 `margin-left: auto` /
+  `margin-right: auto` 会吸收行内剩余空间（双 auto 则居中）；flex 项主轴的 auto
+  外边距在 `justify-content` 之前吸收该行剩余空间，因此可把页脚或按钮提示推到
+  末端。`aspect-ratio` 在 `height: auto` 时由已用宽度推导高度（反向的由高推宽
+  未实现）。`border-radius` 支持百分比，并按 border box 较小边解析。
+- **竖排书写模式** —— `writing-mode: vertical-rl|vertical-lr` 按每列一个字符
+  步进排字：CJK/假名/谚文字符保持直立，其他文字在绘制时旋转 90°。高度确定时
+  另起一列；flex 容器的 row/column 轴随书写模式互换。这是面向文本的实现：
+  竖排容器中的嵌套块与横竖混排内容仍回退为横排。
+- **CSS 值函数与自定义属性** —— `calc()` 算术（含嵌套 `calc()` 以及其它函数
+  内部的 `calc()`）、`clamp(min, value, max)`、`min(...)` 与 `max(...)` 在计算
+  样式中保留表达式，布局时结合元素字号与视口（`vw`/`vh`）求值；桌面窗口中
+  `env(safe-area-inset-*)` 解析为 0。`var(--name[, fallback])` 在
   层叠期间从继承的自定义属性替换。`inset` 是四值 `top/right/bottom/left`
   简写；`box-sizing: border-box` 会从显式宽高里扣除 padding 与边框；
   `visibility: hidden` 跳过绘制与命中测试；`pointer-events: none` 使盒子不接收输入

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

@@ -62,7 +62,8 @@ opacity、`display`——与任何其他元素一样。盒子内部的艺术内
 
 ## 视频与音频（M13）
 
-媒体播放横跨两个扩展，因此只做界面的 GUI 程序不必为用不到的解码器付出体积：
+媒体播放拆在 `gui` 扩展内部，因此只做界面的 GUI 程序不必为用不到的解码器付出
+体积。解码是可选的 **`media` 链接特性**，不是独立扩展：
 
 - **`gui`**（`gui.a`/`gui.lib`）负责 `<video>`/`<audio>` 元素、DOM API、渲染器
   集成与 SDL 音频 sink，但**不含 FFmpeg**。`runtime/ext_gui/media.{h,cpp}`
@@ -71,12 +72,16 @@ opacity、`display`——与任何其他元素一样。盒子内部的艺术内
 - **`media`**（`media.a`，Windows 上 MSVC ABI 则为 `media.lib`；
   `runtime/ext_media/`）是可选的解码后端：`runtime/ext_media/media.cpp`
   封装静态 vendored 的 **FFmpeg** 构建，`runtime/ext_media/media_bridge.c`
-  把它注册进引擎。用 `--ext media`（或 `--ext gui,media`）启用。`media`
-  依赖 `gui`；注册表会拒绝错误的组合。
+  把它注册进引擎。编译器在程序可能用到媒体时（导入 HTML 里的
+  `<video>`/`<audio>`、`createElement("video"/"audio")`、`new Audio()`、
+  `decodeAudioData`，或运行时拼出的 HTML）自动选中该特性，只在那时才编译
+  bridge 并链接 `media.a`。`--feature media` 强制开启，`--no-feature media`
+  保持关闭；见[链接特性](./build.md#链接特性)。
 
-没有 `media` 扩展时，元素仍然存在、DOM API 仍可调用，但打开源会失败并触发
-`error`。任何没有构建该归档的宿主（先运行 `npm run media`）都是如此；
-Windows 已不再特殊：`media.lib` 是用 clang-cl 为 MSVC ABI 编译的 FFmpeg，
+没有 `media` 特性时，元素仍然存在、DOM API 仍可调用，但打开源会失败并触发
+`error`。任何没有构建该归档的宿主（先运行 `npm run media`）都是如此——自动
+检测到但归档缺失时构建给出 warning 并按此降级，显式 `--feature media` 则直接
+报错。Windows 已不再特殊：`media.lib` 是用 clang-cl 为 MSVC ABI 编译的 FFmpeg，
 因此可以和 `gui.lib` 一起链接并正常播放。两条路径都没有 WebView，也没有平台
 媒体框架。
 

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

@@ -63,15 +63,22 @@
 
 窗口背景（`setBackground`）是渲染通道的清除色。
 
+`url()` 图层上的 `background-size` 会按平铺尺寸为每块生成一个图像四边形
+（默认 `repeat`，上限 4096 块），而不是把图片拉伸到整个盒子；百分比尺寸相对
+盒子解析，`auto` 保留盒子的对应尺寸。`outline` 在边框之后、内容之前绘制边框盒
+之外的四条矩形（含 offset）。竖排文本通过把字形四边形旋转 90° 绘制
+（CJK 字形保持直立并在列内居中）。
+
 ### 背景、生成内容与特效（M19）
 
 `background-color` 与每一条 `background-image` 层都会绘制。逗号分隔的层列表按
 从底到上的顺序绘制（声明中的第一层在最上面），两种渐变均受支持：
 
-- **线性**渐变在 18 个位置采样（重复渐变 64 个）并输出为纯色矩形；支持
+- **线性**渐变沿 CSS 渐变线（过盒子中心、按声明角度，盒子在该方向上的投影即
+  渐变线长度，因此百分比与 `calc()` 内的百分比都相对该长度解算）逐像素解算，
+  与径向渐变相同。渐变只沿线变化，所以纹理只有一行（或一列）设备像素；支持
   `to <side>`、`deg`/`grad`/`rad`/`turn`、百分比或长度（`px`/`em`/…）偏移、
-  `color <start> <end>` 简写与多色标（色带沿最近轴行走，因此斜角会退化为
-  最近的轴向）；
+  `color <start> <end>` 简写与多色标；
 - **径向**渐变由 `renderer_gradient.cpp` 逐像素解算成一张 RGBA 纹理，作为单个
   图像四边形绘制（`PaintGradient`）。若沿用嵌套色带，由于每条色带都会覆盖整个
   内部区域，alpha 会叠加多次——淡出到 `transparent` 的暗角会把整个场景涂成实心
@@ -80,21 +87,39 @@
   的椭圆保持盒子的宽高比并缩放到刚好接触对应边或角，与 CSS 一致。色标在预乘
   alpha 空间中插值，最后一个色标会延伸覆盖结束形状之外的剩余盒子。
 
+两种渐变共用这条逐像素路径：用一串纯色矩形绘制时，半透明色标会逐条叠加 alpha，
+而且宽度小于一条色带的色标无法表达——`transparent … calc(100% - 1px),
+rgba(…) calc(100% - 1px)` 这样的 1px 分割线要么落在两次采样之间（直接消失），
+要么被撑成一整条色带。`calc()` 给出的色标位置会保留相对渐变线的百分比，解算后
+为负的偏移也停留在声明的位置，而不会被当成「未声明偏移」重新分配。
+
 `repeating-linear-gradient()` 与 `repeating-radial-gradient()` 会在整个盒子上
 从 0 平铺到最后一个色标的偏移量；色标列表不会被强制结束在 100%，因此
 `red 0%, blue 10%` 每 10% 重复一次。普通渐变的最后一个色标若小于 100%，则剩余
 区域保持该颜色，与 CSS 一致。
 
-背景色位于所有层下方。若渐变色标带透明度，渐变也会半透明；径向渐变逐像素精确，
-线性渐变仍采样 18 条色带，较大的柔和渐变可能出现条带。
+背景色位于所有层下方。若渐变色标带透明度，渐变也会半透明；两种渐变都逐像素精确，
+因此硬色标与 1px 细节保持锐利，不再出现条带。
 
 **生成内容**不需要新的显示列表类型：`::before`/`::after` 是 `style.cpp` 中
 每次重算样式时重建的普通布局盒，因此其背景、边框、文本与 transform 都走同一条
 绘制路径。`content` 支持字符串、`attr()` 与 open/close quote。
 
-**`text-shadow`** 会作为阴影 `PaintText` run 排在真实 run 之前，因此文本管线
-无需新 shader 就能绘制。带模糊的阴影是围绕偏移量展开的九个半透明副本（与
-`filter: blur()` 相同的近似）。
+**`text-shadow`** 在不带模糊时作为阴影 `PaintText` run 排在真实 run 之前，文本
+管线无需新 shader 就能清晰绘制。带模糊的阴影是真正的高斯：`paint_shadow.cpp`
+光栅化字形覆盖度，用可分离核做卷积（`sigma = blur / 2`，截断在 ±3σ），再发出
+一个带色调的图像四边形。掩码按 文本/字体/模糊 缓存，因此动画颜色只改变色调。
+
+**`box-shadow`** 使用同一套高斯掩码：圆角矩形轮廓被光栅化（spread 扩张或收缩）、
+卷积，再合成到背景之后；`inset` 阴影反转掩码、裁剪到 padding box 并绘制在背景
+之上。零模糊的外阴影仍使用精确的圆角矩形。声明列表按最后一层最先绘制，与 CSS
+一致。
+
+**`backdrop-filter`** 与 `mix-blend-mode` 共用离屏机制：绘制器到达该盒子时，
+渲染器把此前场景复制到暂存纹理，用全屏 shader 应用高斯和一个合并的颜色矩阵
+（brightness/contrast/grayscale/sepia/invert/saturate/hue-rotate/opacity 相乘），
+再通过盒子的圆角边框盒掩码合成回来。因此 `backdrop-filter` 在 `paintList()` 中
+显示为 `backdrop …` op。
 
 **`clip-path`** 在 `paint_clip.cpp` 中解析为设备空间多边形（每个点都应用盒子的
 transform），用耳切法三角化，并存入 `DisplayList::clip_paths`。每个 op 的
@@ -107,8 +132,8 @@ shader 改动，但边缘是硬边（没有解析抗锯齿）。支持两层嵌
 `invert`、`saturate`、`hue-rotate`、`opacity`）会折进每个绘制颜色，因此盒子与
 其后代都会看到滤镜。`blur()` 与 `drop-shadow()` 是显示列表层面的近似：模糊把每个
 图形展开成九个半透明副本，投影用盒子/文字轮廓。这样普通绘制保持单渲染通道，代价
-是组语义：被模糊/滤镜的组内重叠后代可能加深；`backdrop-filter` 无法采样元素背后
-的内容，因此会解析并参与层叠，但不绘制。
+是组语义：被模糊/滤镜的组内重叠后代可能加深。`backdrop-filter` 是例外，它有
+自己的离屏快照/滤镜通道（见上）。
 
 **`mix-blend-mode`** 是唯一真正需要离屏图层的例外。非 `normal` 的盒子会被
 `LayerBegin`/`LayerEnd` 标记包住（在 `paintList()` 中显示为 `layer blend=…` /
@@ -120,29 +145,48 @@ shader 合成到场景上。全部十六种 CSS 模式（`multiply`、`screen`
 再由 SPIRV-Cross 交叉编译为 MSL（Metal）；每个嵌套层级的两张场景纹理跨帧复用，
 并通过 ping-pong 让背景在写入时仍可采样。既不吃 SPIR-V 也不吃 MSL 的后端
 （这里的 D3D12/DXIL 路径没有 shader 编译器）仍用普通 source-over 混合绘制该组。
-`backdrop-filter` 依旧不绘制。
+`backdrop-filter` 使用同一条运行时编译路径；shader 后端不可用时会跳过它，页面
+其余内容仍照常绘制。
 
 ## 文本技术栈（M4b）
 
-`runtime/ext_gui/text.{h,cpp}` 封装 **HarfBuzz**（整形）与 **FreeType**（度量
-与最终光栅化）。两者都静态构建，并由 `scripts/build-gui.ts` 链接进 `gui.a`。
+`runtime/ext_gui/text.{h,cpp}` 是前端，通过一个小型后端表分发。默认后端是内置的
+**stb_truetype**（`text_stb.cpp`、`runtime/ext_gui/stb_truetype.h`）。可选的
+**`shaping`** 链接特性会安装 `text_hb.cpp`（HarfBuzz + FreeType 后端），非 ASCII
+文本或作者的 `@font-face` 规则会自动选中它。两个后端共享 `text_font_db.cpp` 中的
+字体数据库（发现与索引）、`text_fonts.cpp` 中的 CSS 匹配器和
+`text_font_sfnt.cpp` 中的 sfnt 元数据读取器，因此同一个 CSS 样式无论链接哪个整形
+后端都会解析到同一个真实字面。
 
-- 字体从常见系统路径解析（macOS 上的 Helvetica/Arial、Linux 上的
-  DejaVu/Liberation、Windows 上的 Segoe UI/Arial），可用 `XT_GUI_FONT`
-  （以及 `XT_GUI_FONT_MONO`）覆盖，并按 `(字体类别, 字号)` 缓存。目前只使用
-  常规直立字面；字重/斜体选择是后续细化。
+- 字体从已安装的系统字面解析。`font-family` 列表按大小写不敏感匹配；
+  `sans-serif`、`serif`、`monospace`（以及 `system-ui`/`ui-*` 别名）映射到平台
+  默认族，其他族名会一次性扫描平台字体目录。`font-weight`（1–1000）和
+  `font-style: italic` 按 CSS Fonts 的字重匹配顺序选择该族真实的粗体/斜体字面；
+  缺少对应字重时选择最接近的字面，族没有斜体字面时使用其直立字面——不做合成
+  粗体或斜体。字面按 `(文件, 集合索引, 字号)` 缓存。`XT_GUI_FONT` /
+  `XT_GUI_FONT_MONO` 仍可覆盖通用族的默认值。
+- 支持作者 **`@font-face`**：加载本地 sfnt 字面（`.ttf`、`.ttc`、`.otf`、
+  `.otc`）。`src` 列表从左到右尝试；`local(...)`、远程 URL 和 `data:` 条目会被
+  跳过。相对 URL 按本地 `file:` 路径处理，相对进程工作目录解析（与图片资源的
+  策略一致）；也接受 `file://` URL（包括百分号编码路径）。`font-weight` /
+  `font-style` 描述符选择字面，支持 `font-weight: 100 900` 这类范围；同族同
+  描述符的后一条规则覆盖前一条。CSS 匹配声明中的族名，即使它与字体文件内部的
+  族名不同。所有来源都不可读时，该族会继续回退到 CSS 列表中的下一个族。
+- 默认候选优先选择 **CJK 覆盖的 TrueType/TTC** 字面（Windows 的 Microsoft
+  YaHei、macOS 的 PingFang/STHeiti、Linux 的 Noto Sans CJK/WenQuanYi），
+  再是纯拉丁字面。同一族的字重/样式变体会跨文件解析；stb_truetype 无法解析的
+  候选（例如 CFF/OTF 集合）会被跳过，`shaping` 后端则会加载它。
 - **主字面缺少的码点会回退到其他字面。** 引擎维护一条小的回退链——先平台的
   符号字体（Segoe UI Symbol、Apple Symbols、Noto Sans Symbols、DejaVu Sans），
-  再是另一字体类别——并为每个码点解析出回退链中第一个拥有该字形的字面。
+  再是默认的 sans、serif 和 monospace 字面——并为每个码点解析出回退链中第一个
+  拥有该字形的字面。
   run 以每个字面一段的方式整形，因此混合 run（拉丁文加箭头、制表符或几何图形，
   或 CJK 中的拉丁文）会绘制每个字形，而不是把缺失的字形当作 `.notdef` 丢弃。
-  这正是让诸如 `▮`/`▯`（U+25AE/U+25AF，鹈鹕自行车速度条所用）这样的字符在
-  CJK 主字面没有几何图形时仍能显示的原因。每个整形后的字形携带自己的字面
-  （`ShapedGlyph::font`），渲染器据此从正确的图集条目光栅化；`xt_text_scale`
-  把字面映射到显示的缩放系数。
-- `xt_text_measure_width` 用 HarfBuzz 对 run 整形（因此字距调整与连字会生效），
-  `xt_text_metrics` 返回 FreeType 的 ascent / descent / 正常行高。当找不到
-  字体文件时，模块回退到确定性的逐字节近似，因此布局仍可工作。
+  每个整形后的字形携带自己的字面（`ShapedGlyph::font`），渲染器据此从正确的
+  图集条目光栅化；`xt_text_scale` 把字面映射到显示的缩放系数。
+- `xt_text_measure_width` 把每个码点映射为字形并累加 advance 与字体的 `kern`
+  表；`xt_text_metrics` 返回 stb_truetype 的 ascent / descent / 正常行高。
+  当找不到字体文件时，模块回退到确定性的逐字节近似，因此布局仍可工作。
 - `xt_text_shape_run` 返回定位后的字形，`xt_text_rasterize` 渲染 8 位位图；
   渲染器把它们打包进图集。在 HiDPI 显示器上，字形以
   `font_size * SDL_GetWindowPixelDensity` 光栅化，而四边形以逻辑像素定位，
@@ -150,6 +194,13 @@ shader 合成到场景上。全部十六种 CSS 模式（`multiply`、`screen`
 - 布局使用这些真实度量进行文本宽度、断行与 `line-height: normal` 计算；
   `measureText`/`fontMetrics` 把它们暴露给测试。
 
+整形取舍：默认是简单整形器，不是完整的 OpenType 引擎。它覆盖拉丁/CJK/西里尔/
+希腊文、基础字距与逐码点回退，但不执行连字或复杂文种（阿拉伯/印度/泰文）整形，
+且 stb_truetype 只接受 TrueType 轮廓，不支持 CFF/OTF 或可变字体。该选择让
+DOM-only 二进制约 3 MiB。可选的 **`shaping`** 链接特性会安装 HarfBuzz + FreeType
+后端（约 1.2 MiB），恢复完整 OpenType 整形与 CFF/OTF/可变字体支持；非 ASCII 文本
+会自动选中，也可用 `--feature shaping` 强制。
+
 ## 性能（M20）
 
 引擎是保留模式管线：一次 DOM 变更会重算样式、重新布局、重建显示列表并上传
@@ -167,7 +218,14 @@ shader 合成到场景上。全部十六种 CSS 模式（`multiply`、`screen`
   `(face, text) -> 字形 + 前进宽度`。它使用两代、每代最多 2 MiB 字形 / 8,192 条
   条目；某一代写满时丢弃**备用**代并切换过去，因此热路径上没有 LRU 记账。
   一个词只整形一次，之后每次布局和重绘都复用它。主字体查找也按
-  （字体族类别，字号）缓存。
+  （字体族、字重、样式、字号）缓存；字体数据库本身只在第一次遇到非通用族名时
+  扫描一次平台目录。
+- **空写不生效。** 当节点已经显示该值时，`textContent` 与 `style.<属性>` 不做任何
+  事：文档不会被标脏，也就没有重算样式、重新布局、重绘或上传。因此每帧都写入相同
+  计时文本、相同血条宽度或相同 transform 的 HUD 不产生任何开销 —— 在此之前，每次
+  赋值都会重建文本节点（一次分配，收集器随后还要清扫）或重写整条内联样式，并把
+  文档标脏触发全文重算。`classList` 与 `removeAttribute` 早就是这样；`setAttribute`
+  仍会无条件标脏。
 - **帧循环。** 只有文档发生变化（或首帧）时才把媒体/画布表与 DOM 对齐，不再每帧
   遍历整棵树。只有确实发生了事情才提交呈现（present）——DOM 变更、滚动、动画帧、
   过渡、新的视频/画布帧、expose/resize 事件——因此静态页面完全不获取 swapchain、

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

@@ -48,6 +48,9 @@ deferred` 才是页面自身造成的工作。调试"漏掉的失效"时可用
   动画帧回调，因此页面可以自行停止）；
 - 只有在**仍有回调**时才重新排程，空闲页面会让事件循环排空并退出进程 ——
   这正是浏览器标签页的生命周期；
+- 下一次 tick 排在**帧开始 + 16 ms**，而不是帧结束后再等 16 ms：帧自身耗时不再
+  叠加到间隔上，10 ms 的帧以 16 ms 周期运行（而不是 26 ms），比 16 ms 更慢的页面
+  则以全速运行，而不是每帧再落后一帧的时间；
 - 当 `xt_gui_run_active()` 为真（程序自己调用了 `run()`）时它会让路，避免同一
   窗口每 tick 被渲染两次；
 - `XT_GUI_AUTOCLOSE_MS=n` 让帧泵在 `n` 毫秒后退出，测试用它来运行不会自行