xbintsc 0.5.51 → 0.5.52

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/build.md

@@ -109,7 +109,7 @@
 | `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/西里尔/希腊文等）、转义或实体码点，或运行时拼出的 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`）：所有字符串字面量（包括导入的
@@ -167,10 +167,10 @@ stb_image/NanoSVG，DOM-only 页面不链接）。Canvas2D、Web Audio 与
 文本替换是有意的取舍。默认后端是 stb_truetype：只接受 TrueType 轮廓，整形是逐码点
 映射加字体的 `kern` 表，因此 CFF/OTF 与可变字体、OpenType 连字以及复杂文种
 （阿拉伯/印度/泰文）整形不可用；fallback 链仍会在主字体缺字时切换到其他字体。
-选中可选的 **`shaping`** 特性（非 ASCII 文本会自动选中，也可用
-`--feature shaping`）会重新链接 HarfBuzz + FreeType（约 1.2 MiB），恢复完整的
-OpenType 整形与 CFF/OTF/可变字体支持。纯拉丁 DOM 页面因此保持约 3.1 MiB；
-中文/复杂文种页面更接近 4.3 MiB。
+选中可选的 **`shaping`** 特性（非 ASCII 文本或作者的 `@font-face` 规则会自动
+选中，也可用 `--feature shaping`）会重新链接 HarfBuzz + FreeType（约 1.2 MiB），
+恢复完整的 OpenType 整形与 CFF/OTF/可变字体支持。纯拉丁 DOM 页面因此保持约
+3.1 MiB；中文/复杂文种页面更接近 4.3 MiB。
 
 ## 运行示例
 

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

@@ -48,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`/

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

@@ -22,7 +22,10 @@
   技术栈测量（见[文本技术栈](./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/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,26 +145,41 @@ 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}` 是前端，通过一个小型后端表分发。默认后端是内置的
 **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 集合）会被跳过，
-  继续尝试下一个。
+  再是纯拉丁字面。同一族的字重/样式变体会跨文件解析；stb_truetype 无法解析的
+  候选（例如 CFF/OTF 集合）会被跳过，`shaping` 后端则会加载它。
 - **主字面缺少的码点会回退到其他字面。** 引擎维护一条小的回退链——先平台的
   符号字体（Segoe UI Symbol、Apple Symbols、Noto Sans Symbols、DejaVu Sans），
-  再是另一字体类别——并为每个码点解析出回退链中第一个拥有该字形的字面。
+  再是默认的 sans、serif 和 monospace 字面——并为每个码点解析出回退链中第一个
+  拥有该字形的字面。
   run 以每个字面一段的方式整形，因此混合 run（拉丁文加箭头、制表符或几何图形，
   或 CJK 中的拉丁文）会绘制每个字形，而不是把缺失的字形当作 `.notdef` 丢弃。
   每个整形后的字形携带自己的字面（`ShapedGlyph::font`），渲染器据此从正确的
@@ -178,7 +218,8 @@ DOM-only 二进制约 3 MiB。可选的 **`shaping`** 链接特性会安装 Harf
   `(face, text) -> 字形 + 前进宽度`。它使用两代、每代最多 2 MiB 字形 / 8,192 条
   条目；某一代写满时丢弃**备用**代并切换过去，因此热路径上没有 LRU 记账。
   一个词只整形一次，之后每次布局和重绘都复用它。主字体查找也按
-  （字体族类别，字号）缓存。
+  （字体族、字重、样式、字号）缓存；字体数据库本身只在第一次遇到非通用族名时
+  扫描一次平台目录。
 - **空写不生效。** 当节点已经显示该值时，`textContent` 与 `style.<属性>` 不做任何
   事：文档不会被标脏，也就没有重算样式、重新布局、重绘或上传。因此每帧都写入相同
   计时文本、相同血条宽度或相同 transform 的 HUD 不产生任何开销 —— 在此之前，每次

package/doc/zh-CN/gui.md

@@ -2,7 +2,7 @@
 
 > 语言 / 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** 真正播放
+状态：**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`/… 与媒体事件。编译器会从程序里判断是否需要它
@@ -14,7 +14,7 @@
 渲染器，因此盒子（以及其中的文本、图像与子元素）可以被平移、缩放与旋转而
 不触发任何重排——再加上 `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)。glslang 是可选的 **`gpu` 链接特性**，与 `mix-blend-mode` 共享；WebGL context/DOM 绑定是单独的 **`webgl` 特性**（依赖 `gpu`），两者都不用时不链接。**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)。本总览记录了锁定决策、架构、里程碑计划与当前进度；引擎本身按功能拆分在以上各页中。
 
 ## 目录
 
@@ -127,8 +127,10 @@
    - **M4a — 显示列表 + GPU 图形** ✅ 背景/边框显示列表、圆角矩形 SDL_GPU
      管线（`paint.*`、`renderer.*`）。
    - **M4b-1 — 文本技术栈 + 度量** ✅ 文本模块（`text.*`）与字体解析/缓存、
-     供布局使用的基于整形的文本度量（`measureText`/`fontMetrics`）；最初用
-     HarfBuzz + FreeType，现在用内置 stb_truetype。
+     供布局使用的基于整形的文本度量（`measureText`/`fontMetrics`）；CSS 族名列表、
+     字重和斜体样式会选择真实安装的字面，作者的 `@font-face` 规则会加载本地字体
+     文件（相对 URL 按 `file:` 路径相对进程工作目录解析）。最初用 HarfBuzz +
+     FreeType，现在用内置 stb_truetype。
    - **M4b-2 — 字形渲染** ✅ stb_truetype 光栅化、共享的 shelf 打包字形图集、
      显示列表中的带纹理文本四边形与感知 HiDPI 的光栅缩放。渐变仍待完成。
 5. **M5 — 输入 + 事件** ✅
@@ -140,9 +142,9 @@
    - **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`
@@ -273,15 +275,16 @@
       特性）；`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 — 渲染性能** ✅
@@ -294,6 +297,27 @@
       冗余的渲染状态绑定。
     - `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`。
 
 ## 进度日志
 
@@ -423,9 +447,23 @@
   `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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xbintsc",
-  "version": "0.5.51",
+  "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.51",
-    "@xbintsc/linux-arm64": "0.5.51",
-    "@xbintsc/darwin-x64": "0.5.51",
-    "@xbintsc/darwin-arm64": "0.5.51",
-    "@xbintsc/win32-x64": "0.5.51",
-    "@xbintsc/win32-arm64": "0.5.51"
+    "@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"