xbintsc 0.5.38 → 0.5.41

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

@@ -11,9 +11,11 @@ CSS 盒中。
 
 引擎侧的对象是 `xtgui::Canvas2D`（`runtime/ext_gui/canvas.{h,cpp}`）——一块 RGBA8 位图
 加上 2D 绘制状态。光栅器位于 `canvas_raster.cpp`，描边几何（端点、连接、虚线）位于
-`canvas_stroke.cpp`，渐变位于 `canvas_gradient.cpp`，绘制状态解析位于
-`canvas_style.cpp`；DOM 绑定位于 `dom_api_canvas.cpp` / `dom_api_canvas_extra.cpp`；
-按窗口的生命周期位于 `gui_canvas.cpp`。
+`canvas_stroke.cpp`，渐变位于 `canvas_gradient.cpp`，合成模式位于
+`canvas_composite.cpp`，裁剪与命中测试位于 `canvas_clip.cpp`，阴影位于
+`canvas_shadow.cpp`，绘制状态解析位于 `canvas_style.cpp`；DOM 绑定位于
+`dom_api_canvas*.cpp` / `dom_api_offscreen.cpp`；按窗口的生命周期位于
+`gui_canvas.cpp`。
 
 ## 获取上下文
 
@@ -31,6 +33,15 @@ const ctx = canvas.getContext("2d"); // 或 "webgl" 取得 GPU 上下文
 元素上，因此每次都返回**同一个**对象，绘制状态（变换、样式、路径）按 canvas 而非按调用
 保存。`ctx.canvas` 是所属元素的句柄。
 
+`OffscreenCanvas` 提供同样的 2D 接口，但没有 DOM 元素：
+`new OffscreenCanvas(width, height)` 分配一块由窗口拥有的位图，`getContext("2d")`
+返回的上下文其 `canvas` 指向离屏对象；`canvas.transferControlToOffscreen()` 会把一个
+活动元素的位图交给离屏对象（此后元素的 `getContext(…)` 返回 `null`）。
+`drawImage`、`createPattern`、`createImageBitmap` 与 `texImage2D` 都接受
+`OffscreenCanvas` 作为源。`transferToImageBitmap()` 返回 `ImageBitmap`，
+`convertToBlob()` 解析为与 `toBlob` 相同的 PNG blob 形状（本运行时没有 worker，
+离屏画布也不提供 WebGL 上下文）。
+
 `getContext("2d", attributes)` 在首次调用时会尊重 `alpha`：传入 `{ alpha: false }`
 时位图以不透明黑色初始化（清除也回到不透明黑）。其余属性由
 `getContextAttributes()` 按规范默认值报告（`antialias: true`、`depth: true`、
@@ -42,8 +53,30 @@ const ctx = canvas.getContext("2d"); // 或 "webgl" 取得 GPU 上下文
 光栅器刻意保持精简且为自研（不依赖 Skia/Cairo）。它按每条像素行 **4 条垂直子扫描线**
 进行抗锯齿，并做一次**水平解析覆盖率**计算；路径默认采用**非零环绕规则**填充（因此当弧线
 以相反方向环绕时能形成空洞），`fill("evenodd")` 则改用奇偶规则。轴对齐矩形（变换中
-`b == 0 && c == 0`）走直接的覆盖率快速路径。混合为非预乘 source-over，并按
-`globalAlpha` 缩放。
+`b == 0 && c == 0`）走直接的覆盖率快速路径。
+
+混合默认是非预乘 source-over。`globalCompositeOperation` 支持完整的 canvas 集合：
+Porter-Duff 算子（`source-over`、`source-in`、`source-out`、`source-atop`、
+`destination-over`、`destination-in`、`destination-out`、`destination-atop`、
+`lighter`、`copy`、`xor`）以及可分离/不可分离混合模式（`multiply`、`screen`、
+`overlay`、`darken`、`lighten`、`color-dodge`、`color-burn`、`hard-light`、
+`soft-light`、`difference`、`exclusion`、`hue`、`saturation`、`color`、
+`luminosity`）。抗锯齿与裁剪区域产生的部分覆盖率会在“未改动的目标”与“完整合成结果”
+之间插值，因此每个算子在部分覆盖的像素上都正确。
+
+`clip()` 用当前路径（或 `Path2D` 加可选的 `"nonzero"`/`"evenodd"` 规则）与当前裁剪区
+求交。区域以设备空间覆盖率掩码保存，因此它固定在调用 `clip()` 时的变换下；
+`save`/`restore` 会一并恢复，位图尺寸变化会清空它。所有填充、描边、文本、图像绘制与
+`clearRect` 都遵守该掩码。
+
+阴影（`shadowColor`、`shadowBlur`、`shadowOffsetX`、`shadowOffsetY`）由绘制操作自身的
+alpha 生成：先把操作渲染到临时图层，对其 alpha 做偏移与盒式模糊（三次可分离模糊），用
+`shadowColor` 着色后合成，最后把未处理的图层画在其上。偏移与模糊使用画布（设备）单位，
+不受变换影响，符合 API 规定。`clearRect` 与 `putImageData` 从不产生阴影。
+
+`isPointInPath(x, y[, fillRule])`、`isPointInPath(path, x, y[, fillRule])`、
+`isPointInStroke(x, y)` 与 `isPointInStroke(path, x, y)` 在当前变换下对当前路径（或
+传入的 `Path2D`）做命中测试；描边命中测试使用到各展平线段的设备空间距离与当前线宽。
 
 填充或描边可以使用纯色，也可以使用 **`CanvasGradient`**。渐变的坐标属于用户空间，
 因此光栅器会先用当前变换的逆矩阵把每个设备像素映射回用户空间再采样——形状被平移、
@@ -54,6 +87,27 @@ Canvas 像素**不参与垃圾回收**：canvas 由窗口拥有、以 DOM 节点
 `<video>`/`<audio>` 解码表结构相同）。当节点被丢弃（`loadHTML`、窗口关闭/退出，或丢弃
 子树的变更操作）时随之释放，并释放对应的 GPU 纹理。
 
+## 性能
+
+canvas 由脚本重绘而不是引擎重绘，因此开销按绘制调用计。多元素场景下的热路径刻意
+保持少分支：
+
+- 纯色不透明的 `fillRect` 直接按字节写入位图（小数边缘仍走抗锯齿路径），覆盖整张
+  位图的 `clearRect` 退化为一次 `memset`；
+- 路径覆盖率使用逐行**活动边表**光栅化，并且只物化每一行**实际覆盖的区间**——一条
+  细对角线描边只花它自己的像素，而不是整个包围盒；
+- 一次 `stroke()` 把所有线段四边形、连接与端点合并成一次非零环绕填充，而不是每段
+  各做一次覆盖率计算（先统一每个多边形的绕向，重叠处才能覆盖而不是抵消）；
+- `fillText` 与布局共享整形缓存（`text_cache.cpp`），并使用有界两代字形位图缓存
+  （`text_glyph_cache.cpp`）；
+- 整数偏移、无缩放的 `drawImage` 逐像素只取一个纹素，不再跑双线性采样器。
+
+位图通过**脏矩形**到达屏幕：每次绘制把它的设备空间包围盒并入待上传区域，渲染器只
+拷贝该区域到 canvas 纹理。一帧内所有 canvas 与视频上传共用帧的唯一上传命令缓冲，
+因此 K 张动画 canvas 只需一次提交而不是 K 次。`getImageData` 始终读取 CPU 位图，
+不受影响。`tests/e2e/gui-draw-perf.test.ts` 测量这些多元素路径并固定计数器行为
+（每帧一次上传、只传脏字节）。
+
 ## 支持的 API
 
 状态与变换：`save` / `restore`（会恢复变换、线宽、透明度、字体/文本设置**以及**
@@ -64,30 +118,37 @@ Canvas 像素**不参与垃圾回收**：canvas 由窗口拥有、以 DOM 节点
 `translate(x, y); rotate(a)` 围绕平移后的原点旋转。
 
 样式与设置：`fillStyle` / `strokeStyle`（层叠所用的颜色解析器能识别的 CSS 颜色，或
-`CanvasGradient`）、`lineWidth`、`globalAlpha`、`lineCap`（`butt`/`round`/`square`）、
+`CanvasGradient`）、`lineWidth`、`globalAlpha`、`globalCompositeOperation`、
+`shadowColor` / `shadowBlur` / `shadowOffsetX` / `shadowOffsetY`、
+`imageSmoothingEnabled` / `imageSmoothingQuality`、`lineCap`（`butt`/`round`/`square`）、
 `lineJoin`（`miter`/`round`/`bevel`）、`miterLimit`、`lineDashOffset`、`font`
 （CSS 字体简写，解析出字体族、字号与粗体/斜体——默认 `10px sans-serif`）、
 `textAlign`（`start`/`left`、`center`、`right`/`end`）与 `textBaseline`
 （`alphabetic`、`top`、`middle`、`bottom`、`hanging`、`ideographic`）。读取属性返回
-上次赋予的值；赋予无法解析的颜色会保留原值。
+上次赋予的值；赋予无法解析的颜色会保留原值。`imageSmoothingEnabled` 默认为 `true`
+（双线性采样）；`imageSmoothingQuality` 报告 `low`、`medium` 或 `high`，本后端都使用
+同一种双线性过滤。
 
 渐变：`createLinearGradient(x0, y0, x1, y1)` 与
 `createRadialGradient(x0, y0, r0, x1, y1, r1)` 返回带
 `addColorStop(offset, color)` 的 `CanvasGradient`。色标是**活的**：在
 `fillStyle = gradient` 之后追加的色标会影响后续填充，且 `fillStyle`/`strokeStyle`
-的读取返回同一个渐变句柄。径向渐变按到**外圆**圆心（`x1, y1`）的距离插值，因此目前
-会忽略 `x0`/`y0`——请使用同心圆（`x0 == x1`、`y0 == y1`）。
+的读取返回同一个渐变句柄。径向渐变是通用的双圆锥：点上的颜色由插值圆
+（`圆心 = c0 + t·(c1 − c0)`、`半径 = r0 + t·(r1 − r0)`）解出，因此内圆有偏移、两圆
+半径不同时都与浏览器一致。内圆内部的点采样色标 0。
 
 路径：`beginPath`、`closePath`、`moveTo`、`lineTo`、`rect`、`roundRect`、`arc`、
 `ellipse`、`quadraticCurveTo`、`bezierCurveTo`，然后
-`fill(fillRule?)` / `fill(path, fillRule?)`（多环；`"nonzero"` 或 `"evenodd"`）或
-`stroke(path?)`。贝塞尔与二次曲线段会被展平为线段；弧线与椭圆同样被展平。
+`fill(fillRule?)` / `fill(path, fillRule?)`（多环；`"nonzero"` 或 `"evenodd"`）、
+`stroke(path?)`、`clip(path?, fillRule?)` 以及 `isPointInPath`/`isPointInStroke`
+命中测试。贝塞尔与二次曲线段会被展平为线段；弧线与椭圆同样被展平。
 `roundRect` 接受单个半径数字，或 CSS 半径列表（`[all]`、`[tl, br]`、
 `[tl, tr, br]`、`[tl, tr, br, bl]`，元素为数字或 `{ x, y }` 对；圆角按圆弧绘制）。
 
 `Path2D` 支持同一组路径命令（`moveTo`、`lineTo`、`closePath`、`rect`、
 `roundRect`、`arc`、`ellipse`、`quadraticCurveTo`、`bezierCurveTo`、`addPath`），
-并可传给 `fill`/`stroke`，因此一次构建的路径可以在不同变换下重复使用。
+并可传给 `fill`/`stroke`/`clip` 以及 `isPointIn*` 命中测试，因此一次构建的路径可以在
+不同变换下重复使用。
 
 矩形：`clearRect`、`fillRect`、`strokeRect`。
 
@@ -103,29 +164,37 @@ Canvas 像素**不参与垃圾回收**：canvas 由窗口拥有、以 DOM 节点
 
 图像：`drawImage(source, …)` 支持 3 参数（`dx, dy`）、5 参数（`dx, dy, dw, dh`）与
 9 参数（本引擎为**目标优先**：`dx, dy, dw, dh, sx, sy, sw, sh`）。完整的仿射变换
-（旋转/斜切/缩放）会被应用：目标矩形变为平行四边形，每个设备像素反查到源矩形
-（最近邻采样）。`source` 可以是 `<img>` 元素（经图像
-模块解码）或另一个 `<canvas>` 元素（取其当前位图）。采样为最近邻，因此把小图大幅放大
-会有块状感——适合图标与像素画，不适合照片管线。
+（旋转/斜切/缩放）会被应用：目标矩形变为平行四边形，每个设备像素反查到源矩形。
+`source` 可以是 `<img>` 元素（经图像模块解码）、另一个 `<canvas>`、
+`OffscreenCanvas` 或 `ImageBitmap`。`imageSmoothingEnabled` 为 `true`（默认）时使用
+双线性采样，为 `false` 时使用最近邻。
 
 测试钩子：`getImageData(x, y, w, h)` 把区域复制为 `{ width, height, data }`，其中
 `data` 是按行主序的 RGBA8 字节数组。越界像素为透明。
 
-图案：`createPattern(source, repetition?)` 接受 `<img>` 或另一个 `<canvas>`，在用户
-空间中平铺（`repeat`、`repeat-x`、`repeat-y`、`no-repeat`），因此平铺会跟随当前
-变换。把结果赋给 `fillStyle`/`strokeStyle`；重新赋颜色会替换掉图案。
+图案：`createPattern(source, repetition?)` 接受 `<img>`、`<canvas>`、
+`OffscreenCanvas` 或 `ImageBitmap`，在用户空间中平铺（`repeat`、`repeat-x`、
+`repeat-y`、`no-repeat`），因此平铺会跟随当前变换。把结果赋给
+`fillStyle`/`strokeStyle`；重新赋颜色会替换掉图案。
 
 图像数据与导出：`createImageData(width, height)` 分配一个空的
 `{ width, height, data }`，`putImageData(imageData, dx, dy[, dirtyX, dirtyY,
-dirtyWidth, dirtyHeight])` 直接把字节写入位图（不受变换、混合或 `globalAlpha`
-影响）。`canvas.toDataURL(type?)` 导出 PNG data URL，`canvas.toBlob(callback,
-type?)` 从微任务中交付 Blob 形状的 `{ type, size }`（字节在
-`__xt_gui_blob_data` 上；本运行时没有 `URL.createObjectURL`）。
+dirtyWidth, dirtyHeight])` 直接把字节写入位图（不受变换、混合、裁剪或
+`globalAlpha` 影响）。`canvas.toDataURL(type?)` 导出 PNG data URL，
+`canvas.toBlob(callback, type?)` 从微任务中交付 Blob 形状的 `{ type, size }`
+（字节在 `__xt_gui_blob_data` 上；本运行时没有 `URL.createObjectURL`）。
+`OffscreenCanvas.convertToBlob()` 解析为同一形状，`transferToImageBitmap()` 对位图
+做快照。
+
+CSS 背景：`background-image: url(...)` 接受文件路径或 `data:` URL，因此可以先把
+canvas 导出再作为 CSS 背景使用
+（`element.style.backgroundImage = "url(" + canvas.toDataURL() + ")"`）。图像层会拉伸
+到元素的边框盒；`background-size`、`background-position` 与平铺尚未建模。
 
 ## 尚未实现
 
-阴影、`clip()`、`globalCompositeOperation`、`isPointInPath`、可切换图像平滑的
-`drawImage`、把 `<canvas>` 用作 CSS `background-image`，以及离屏画布
-（`OffscreenCanvas`、`transferControlToOffscreen`）。径向渐变会忽略内圆偏移。
+本后端的平滑质量只有一种过滤（双线性）。离屏画布只支持 2D 上下文（WebGL 上下文需要
+DOM 元素来维护纹理表）。旋转的字形位图仍不会随变换旋转，`strokeText` 仍用描边样式
+填充而非生成轮廓。
 
 另见[媒体](./media.md)：`drawImage` 与纹理上传所共享的图像/视频/音频解码栈。

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

@@ -11,13 +11,15 @@
   [WebGL](./webgl.md)）：GLSL ES 着色器由内置 glslang 翻译为 SPIR-V——Vulkan
   后端直接消费，Metal 上再由内置 SPIRV-Cross 交叉编译为 MSL——绘图缓冲
   是一张离屏颜色纹理，页面直接合成而无须读回。WebGL 2 增加了 VAO、实例化、
-  整数属性、采样器对象、`texStorage2D` 与缓冲拷贝。Uniform 块、transform
-  feedback、立方体贴图、3D 纹理、浮点/深度纹理、压缩纹理、多渲染目标、
-  `blitFramebuffer`、MSAA 与模板操作尚未实现；`clear` 会忽略 scissor 矩形。
+  整数属性、采样器对象、`texStorage2D`、缓冲拷贝、Uniform 块、立方体/3D/数组
+  纹理、浮点/深度/压缩纹理、多渲染目标与 scissor 清除。`blitFramebuffer` 复制
+  颜色与深度；transform feedback、MSAA 与模板 blit 尚未实现（SDL_GPU 没有
+  transform feedback 阶段，其 Metal 多采样 resolve 不可靠，模板附件也无法采样）。
   在两种格式都不接受的 SDL_GPU 后端（Direct3D 12，需要 DXIL）上两种上下文都为
   `null`。`.js` 资源加载器现在只修补 three.js 的着色器循环展开；
   `WebGLRenderer` 直接运行在真实后端上，不再有 Canvas2D 回退。阴影贴图
-  （深度纹理）、立方体贴图/环境贴图与 HDR 渲染目标仍未支持。
+  （比较型 `sampler2DShadow` 采样深度纹理）、立方体贴图/环境贴图与 HDR 渲染目标
+  均已支持。
 
 
 - **自动关闭时的偶发崩溃。** 设置 `XT_GUI_AUTOCLOSE_MS` 结束运行时，约五次中有两次会以原生
@@ -57,6 +59,21 @@
   图像内部（这里的 `fill`/`stroke` 是 SVG 表现属性，不是 CSS 属性）。需要这些
   能力的矢量美术必须预先光栅化、用盒子绘制，或限制在受支持的语法内。参见
   [媒体](./media.md#图像m6a)。
+- **每次变更仍是整文档重算。** 一次 DOM 变更会重新计算层叠并重新布局整个文档
+  （没有增量子树失效），只影响绘制的变更（例如 hover 颜色）同样会重排。带生成
+  内容（`::before`/`::after`）的文档没有特殊处理。各阶段的实测开销由
+  `win.stats()`/`XT_GUI_PERF` 暴露，后续优化以它为依据；参见
+  [性能](./rendering.md#性能m20)。
+- **绘制调用遵循画家顺序。** 只有当 run 在画家顺序上相邻且 pipeline、裁剪与
+  纹理都相同时才会合并，因此"背景与文本逐行交替"的列表每行要付一个图形 run 和
+  一个文本 run（见 `win.stats()` 的 `drawCalls`）。要减少绘制调用需要感知重叠的
+  合并器（文本可能被后续背景覆盖），目前未实现。实测：200 行基准页发出 400 次
+  绘制调用，绘制阶段约耗时 0.4 ms，因此它是"绘制调用占主导"的页面的后续优化项，
+  而不是当前的瓶颈。
+- **文本整形缓存有界。** 两代、每代最多 2 MiB 字形 / 8,192 条条目保存
+  `(face, text) -> 字形`。不同单词数超过上限的文档在缓存轮换后会重新整形一部分；
+  `win.stats()` 的 `textCacheBytes`/`textShapeHits` 能看出它是否成为瓶颈。
+  元素自带的 `style="…"` 内联属性在该元素每次重算样式时都会重新解析。
 
 ## 待决问题
 

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

@@ -128,3 +128,62 @@ shader 改动，但边缘是硬边（没有解析抗锯齿）。支持两层嵌
 - 布局使用这些真实度量进行文本宽度、断行与 `line-height: normal` 计算；
   `measureText`/`fontMetrics` 把它们暴露给测试。
 
+## 性能（M20）
+
+引擎是保留模式管线：一次 DOM 变更会重算样式、重新布局、重建显示列表并上传
+顶点数组；没有任何变化的帧不产生 CPU 或 GPU 工作。为了让上千个元素的文档保持
+可交互，每个阶段都有预算，并且都可以测量。设置 `XT_GUI_PERF=1` 会逐帧打印一行
+（`XT_GUI_PERF=<N>` 则每 N 帧聚合一行）；`win.stats()` 返回同样的计数器，
+`tests/e2e/gui-perf.test.ts` 断言的正是这些计数。
+
+- **层叠。** 每次重算样式时，`@media` 前导条件**每条规则只求值一次**（过去是
+  每条规则 × 每个节点各解析一次，这是大文档上最大的一笔开销）。样式表里没有
+  `::before`/`::after` 规则时完全跳过生成内容；声明候选列表在深度优先遍历中
+  复用而不是每个元素分配一次；只有样式表真的包含 `:hover`/`:focus` 规则时，
+  这两个状态变化才会触发重算。
+- **文本。** 布局与绘制共享一个有界的整形缓存（`text_cache.cpp`）：
+  `(face, text) -> 字形 + 前进宽度`。它使用两代、每代最多 2 MiB 字形 / 8,192 条
+  条目；某一代写满时丢弃**备用**代并切换过去，因此热路径上没有 LRU 记账。
+  一个词只整形一次，之后每次布局和重绘都复用它。主字体查找也按
+  （字体族类别，字号）缓存。
+- **帧循环。** 只有文档发生变化（或首帧）时才把媒体/画布表与 DOM 对齐，不再每帧
+  遍历整棵树。只有确实发生了事情才提交呈现（present）——DOM 变更、滚动、动画帧、
+  过渡、新的视频/画布帧、expose/resize 事件——因此静态页面完全不获取 swapchain、
+  也不绘制。expose 是唯一由窗口系统（而非页面）要求的呈现，`exposes` 统计这些帧，
+  因此即使窗口服务器很晚才映射窗口，`presents - exposes - deferred` 仍然只是
+  文档自身的工作量。取不到交换链图像的帧（GPU 仍持有图像时 SDL 的非阻塞获取会跳过
+  该帧，最小化的窗口则完全没有图像）不会丢弃这次失效，而是保留到下一帧再呈现，
+  这类呈现计为 `deferred`。调试"漏掉的失效"时可用 `XT_GUI_ALWAYS_PRESENT=1`
+  恢复旧的每帧提交。
+- **绘制与上传。** 显示列表和顶点暂存数组挂在窗口中按帧清理，容量得以保留。
+  一个脏帧的所有顶点/图集上传共用一个命令缓冲区（一次提交），几何体的暂存
+  transfer buffer 被复用（上一帧的拷贝可能仍在飞行中，因此按 cycle 方式映射），
+  没有任何子元素带 z-index 时绘制会跳过排序和临时数组。
+- **绘制调用。** 相邻且 pipeline、裁剪和纹理相同的 op 仍会合并为一个 run，
+  渲染器现在只在 pipeline / 顶点缓冲 / 裁剪矩形真正变化时才重新绑定。
+  `win.stats()` 里的 `drawCalls`/`drawMs` 报告 run 数量与其开销，它们是后续工作
+  （感知重叠的合并）的度量依据——在它落地之前，画家顺序要求背景与文本交替的
+  run 必须保持独立。
+- **立即模式绘制表面。** `<canvas>` 2D 与 WebGL 由脚本驱动，开销按调用次数计
+  而不是按文档变更计；上面的计数器只覆盖保留模式管线。
+  `tests/e2e/gui-draw-perf.test.ts` 测量它们：在参考的 Windows x64/Vulkan 机器上，
+  一帧 1280×720、包含 5,000 个纯色 `fillRect`、200 条 8 点折线、300 次
+  `fillText` 和 200 次 1:1 `drawImage` 的场景从 231ms 降到 158ms（填充 4.3ms、
+  描边 151ms、文本 1.4ms、图像 1.6ms）；2,000 次带逐次矩阵的 WebGL
+  `drawElements` 从 38.6ms 降到 27.5ms，同时每帧打开的渲染 pass 从 2,001 次
+  降到 1 次，向 4 MiB 缓冲写入 64 KiB 的 `bufferSubData` 不再重传整个缓冲。
+  100×100 的画布局部重绘现在只上传 40 KB，而不是整张 1.2 MB 位图。测试断言的是
+  计数器（每帧一次上传、稳定状态不新建管线、只传脏字节），因此墙钟数字仅供
+  参考，CI 上的软件 GPU 不会被误判。
+
+已知限制：一次变更仍会对**整个**文档重算样式并重新布局（没有增量子树失效），
+只影响绘制的变更（例如 hover 颜色）目前同样会重排；后续工作应以 `win.stats()`
+的数据为依据。元素自带的 `style="…"` 内联属性在该元素每次重算样式时都会重新解析。
+
+作为参照，`tests/e2e/gui-perf.test.ts` 会构建一个 200 行的列表（约 1,000 个元素、
+400 个绘制 run）并打印实测数字，例如在 Windows x64/Vulkan 机器上修改一个
+`textContent` 字段得到
+`textFrame=5.2ms restyle=3.6ms layout=1.7ms paint=1.0ms upload=0.8ms draw=0.4ms`。
+绝对值因机器而异；测试断言的是**计数器**（一次重算、一次布局、命中缓存而不是
+重新整形、空闲帧不做任何工作），回归时变化的正是这些。
+

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

@@ -19,11 +19,21 @@ GUI 引擎既可以通过 `xt_loop_set_main` 注册自己的循环，也可以
 普通原生调用。每次 tick 它都会：
 
 1. 为每个窗口泵送 SDL 窗口/输入事件，
-2. 当显示列表变化时构建/上传它，并渲染每个打开的窗口（清除通道 + 图形几何
+2. **只在文档发生变化（或首帧）时**把解码器/画布表与 DOM 对齐，
+3. 当显示列表变化时构建/上传它，并渲染每个打开的窗口（清除通道 + 图形几何
    + 文本几何），
-3. 调用 `xt_loop_poll(0)` 与 `xt_drain_microtasks()`，使 socket/定时器与
+4. 调用 `xt_loop_poll(0)` 与 `xt_drain_microtasks()`，使 socket/定时器与
    `await` 续体持续取得进展，
-4. 重复直到所有窗口关闭或调用 `quit()`。
+5. 重复直到所有窗口关闭或调用 `quit()`。
+
+只有**确实发生了事情**帧才会呈现：DOM 变更、滚动、已排队的动画帧、正在运行的
+过渡、新的视频/画布帧、expose/resize 事件，或首帧。因此静态文档不会获取
+swapchain、也不会绘制，而循环仍在处理事件、定时器与 promise。expose/shown/restore
+事件是唯一由窗口系统（而非文档）要求的呈现，它们在 `win.stats()` 中计为
+`exposes`；取不到交换链图像而被推迟的呈现计为 `deferred`，`presents - exposes -
+deferred` 才是页面自身造成的工作。调试"漏掉的失效"时可用
+`XT_GUI_ALWAYS_PRESENT=1` 恢复旧的每帧提交行为。`XT_GUI_PERF=1` 会打印每一帧
+做了哪些工作（见[性能](./rendering.md#性能m20)）。
 
 `xt_loop_set_main` 钩子仍保留给希望自行掌控循环的宿主。
 

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

@@ -21,11 +21,26 @@ if (gl == null) {
 ## 一帧如何到达屏幕
 
 - 每个上下文拥有一张离屏 `R8G8B8A8_UNORM` 颜色纹理（绘图缓冲）和一张 `D32_FLOAT` 深度纹理，尺寸取自 canvas 的 `width` / `height` 属性。`canvas.width = …` 会重建它们并丢弃内容，与 DOM 规则一致。
-- 上下文记录到自己的 SDL_GPU 命令缓冲。`clear`/`draw*` 保持一个渲染 pass 打开；缓冲区/纹理上传或切换 framebuffer 会结束它，并以 `LOAD` 开始新 pass，因此绘图缓冲在多次绘制之间保留，和 WebGL 一样。
+- 上下文记录到自己的 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`，因此管线按（程序、顶点布局、状态）惰性创建，并缓存在程序上。
 
+## 性能
+
+重复绘制命中缓存，而不是每次重建：当前（程序、属性布局、固定功能状态、附件格式）
+对应的管线、顶点布局与缓冲绑定只准备一次并复用（`webgl_draw_setup.cpp`）；状态变化时
+缓存未命中并新建管线。固定功能状态被哈希进 128 位键，而不是每次 draw 拼字符串；活动
+属性在链接时解析一次。上传被前移到渲染 pass 之前：没有上传的绘制不会结束 pass，禁用
+的顶点属性读取持久的常量缓冲而不是每次 draw 分配 GPU 缓冲，状态未变的绘制不重复绑定。
+`bufferSubData` 只拷贝写入的字节区间，增长中的缓冲按 2 的幂扩容。
+
+`win.stats()` 报告 `webglDraws`、`webglPasses`、`webglPipelineMisses` 与
+`webglBufferUploadBytes`；`tests/e2e/gui-draw-perf.test.ts` 正是用它们固定行为
+（2,000 次绘制只开一个 pass、稳定状态不再创建管线、4 MiB 缓冲只重传 64 KiB 区间）。
+剩余的每次 draw 开销来自后端自身的提交；大量相同对象仍应由应用改用
+`drawElementsInstanced`。
+
 ## 着色器：GLSL ES 到 SPIR-V（再到 MSL）
 
 SDL_GPU 不能在运行时编译 GLSL，且每个后端只消费自己的格式，因此引擎静态链接了两个翻译器：
@@ -51,12 +66,16 @@ SDL_GPU 不能在运行时编译 GLSL，且每个后端只消费自己的格式
 | 非采样器 uniform | 一个 `layout(std140) uniform XtUniforms { … }` 块 |
 | `uniform sampler2D u_tex` | `layout(set = 2, binding = N) uniform sampler2D u_tex`（片元）或 set 0（顶点） |
 | `gl_FragData[0]` | `xt_FragColor` |
+| `gl_FragDepth` / `gl_FragDepthEXT` | 保留（SPIR-V `DepthReplacing`；MSL `[[depth(any)]]`） |
+| `sampler2DShadow` / `samplerCubeShadow` / `sampler2DArrayShadow` | 保留；绑定为 SDL_GPU 比较采样器 |
 | 缺少 `#version` / `#version 100` | `#version 310 es` |
 
 实现限制：结构体 uniform、用户 uniform 块、预处理阶段无法确定长度的 uniform 数组，以及用非常量表达式索引的采样器数组会被拒绝（shader/link info log 会说明）。`#pragma unroll_loop_start` 循环会在改写前展开，因此 three.js 生成的 `sampler2D shadowMap[ NUM_DIR_LIGHT_SHADOWS ]` / `shadowMap[ i ]` 会变成常量索引。`#ifdef` 内的着色器代码可用；非采样器 uniform 声明会被移动到顶层，保证块保持无条件。两个阶段的非采样器 uniform 会合并成同一个块，并在每个阶段各声明一次（顶点 set 1、片元 set 3），与 SDL_GPU 的 Vulkan 描述符布局一致。在 Metal 上同一批声明会变成 `[[buffer(0)]]` 与 `[[texture(N)]]`/`[[sampler(N)]]`，正是 SDL_GPU Metal 后端绑定的槽位。`uniformMatrix4fv` 按列主序写入反射出的偏移；对采样器调用 `uniform1i` 时记录纹理单元。每次绘制都用动态 uniform 缓冲接口推送该块。
 
 翻译器的限制：结构体 uniform、用户 uniform 块、预处理后仍无法确定长度的 uniform 数组、采样器数组与采样器类型不匹配的声明会被拒绝（着色器/链接日志会说明）。`#ifdef` 内的代码没问题；非采样器 uniform 声明会被移到外层顶层位置，保证块是无条件的。
 
+片元着色器可以写 `gl_FragDepth`：glslang 会把 SPIR-V 标记为 `DepthReplacing`，SPIRV-Cross 会生成 `[[depth(any)]]`，因此两个后端上深度写入都会到达深度附件。比较采样器（`sampler2DShadow`、`samplerCubeShadow`、`sampler2DArrayShadow`）复用 SDL_GPU 采样器对象并设置 `enable_compare`；`TEXTURE_COMPARE_MODE` 与 `TEXTURE_COMPARE_FUNC` 从纹理读取（WebGL 2 也可从绑定的采样器对象读取）。
+
 ### GLSL ES 3.00（WebGL 2）
 
 `#version 300 es` 源码除版本号提升外会被原样接受：顶层 `in`/`out` 声明会变成属性/`varying`，命名片元输出（`out vec4 fragColor;`）会变成 `xt_FragColor` 形式的输出，`texture()` / `textureLod()` 本就与 Vulkan 方言一致。多个片元输出会分配连续 location，但渲染 pass 只有一个颜色目标，因此只写入第一个。GLSL ES 3.00 提供 `gl_VertexID` 与 `gl_InstanceID`，实例化示例正是用它。
@@ -69,7 +88,7 @@ SDL_GPU 不能在运行时编译 GLSL，且每个后端只消费自己的格式
 - **缓冲与顶点属性**：`createBuffer`、`bindBuffer`、`bufferData`、`bufferSubData`、`deleteBuffer`、`getBufferParameter`、`enableVertexAttribArray`、`disableVertexAttribArray`、`vertexAttribPointer`、`vertexAttrib1f`…`4f` / `1fv`…`4fv`、`getVertexAttrib`。`bufferData` 的 `usage` 提示（`STREAM_DRAW`/`STATIC_DRAW`/`DYNAMIC_DRAW`）会被记录，`getBufferParameter(…, BUFFER_USAGE)` 可读回。
 - **绘制**：`drawArrays`、`drawElements`（UNSIGNED_BYTE、UNSIGNED_SHORT、UNSIGNED_INT；`TRIANGLE_FAN` 与 `LINE_LOOP` 会展开为列表）。`POINTS`、`LINES`、`LINE_STRIP`、`TRIANGLES`、`TRIANGLE_STRIP` 映射到对应的 SDL 图元。
 - **纹理**：`createTexture`、`bindTexture`、`activeTexture`、`texParameteri`/`texParameterf`、`getTexParameter`、`texImage2D`（原始像素、`<img>`、`<canvas>`、`ImageData`）、`texSubImage2D`、`generateMipmap`、`deleteTexture`。支持 `UNPACK_FLIP_Y_WEBGL` 与 `UNPACK_PREMULTIPLY_ALPHA_WEBGL`。默认转换为 RGBA8；`RGBA`/`RGB`/`LUMINANCE`/`ALPHA`/`LUMINANCE_ALPHA` 配 `UNSIGNED_BYTE` 可用。浮点纹理（`RGBA32F`、`RGBA16F`、`RGB32F`、`RGB16F`、`RG32F`/`RG16F`、`R32F`/`R16F`，`FLOAT` 或 `HALF_FLOAT` 数据，以及 WebGL 1 的 `OES_texture_float`/`OES_texture_half_float`）映射到 SDL 的 RGBA32F/RGBA16F；深度纹理（`DEPTH_COMPONENT16/24/32F`、`DEPTH_STENCIL`、`DEPTH24_STENCIL8`）映射到 `D32_FLOAT`/`D32_FLOAT_S8_UINT`，可作为采样源或深度附件。压缩纹理通过 `compressedTexImage2D`/`compressedTexSubImage2D` 上传，支持 `WEBGL_compressed_texture_s3tc`（BC1/BC2/BC3）、`WEBGL_compressed_texture_s3tc_srgb` 与 `WEBGL_compressed_texture_astc`；扩展只在设备确实支持对应格式时公布。`texImage2D` 还接受 `<video>` 的最新解码帧与 `createImageBitmap` 产生的 `ImageBitmap`。立方体贴图（`bindTexture(TEXTURE_CUBE_MAP)` + 六个 `texImage2D` 面）与 3D/数组纹理（`texImage3D`/`texStorage3D`）可用对应采样器（`samplerCube`、`sampler3D`、`sampler2DArray`）采样；`texSubImage3D` 可更新 3D/数组纹理的子区域，`framebufferTextureLayer` 可把数组/立方体贴图的指定层作为颜色附件渲染。
-- **Framebuffer**：`createFramebuffer`、`bindFramebuffer`（`FRAMEBUFFER`/`READ_FRAMEBUFFER`/`DRAW_FRAMEBUFFER`）、`framebufferTexture2D`（`COLOR_ATTACHMENT0`、`DEPTH_ATTACHMENT`、`DEPTH_STENCIL_ATTACHMENT`）、`checkFramebufferStatus`、`createRenderbuffer`、`bindRenderbuffer`、`renderbufferStorage`（深度/深度模板）、`framebufferRenderbuffer`、`delete*`，以及 `blitFramebuffer`（颜色附件；深度/模板位被接受但不复制）。足以实现渲染到纹理、阴影贴图与后处理。
+- **Framebuffer**：`createFramebuffer`、`bindFramebuffer`（`FRAMEBUFFER`/`READ_FRAMEBUFFER`/`DRAW_FRAMEBUFFER`）、`framebufferTexture2D`（`COLOR_ATTACHMENT0`、`DEPTH_ATTACHMENT`、`DEPTH_STENCIL_ATTACHMENT`）、`checkFramebufferStatus`、`createRenderbuffer`、`bindRenderbuffer`、`renderbufferStorage`（深度/深度模板）、`framebufferRenderbuffer`、`delete*`，以及 `blitFramebuffer`（颜色走 SDL blit；深度走一个写 `gl_FragDepth` 的采样 pass；模板位被接受但不复制）。足以实现渲染到纹理、阴影贴图与后处理。
 - **状态**：`enable`/`disable`/`isEnabled`（`BLEND`、`DEPTH_TEST`、`CULL_FACE`、`SCISSOR_TEST`、`STENCIL_TEST`）、`clearColor`/`clearDepth`/`clearStencil`、`clear`（开启 `SCISSOR_TEST` 时颜色、深度与模板都只清除 scissor 矩形）、`blendColor`、`blendFunc`/`blendFuncSeparate`、`blendEquation`/`blendEquationSeparate`、`depthFunc`、`depthMask`、`colorMask`、`stencilFunc`/`stencilFuncSeparate`、`stencilOp`/`stencilOpSeparate`、`stencilMask`/`stencilMaskSeparate`、`cullFace`、`frontFace`、`viewport`、`scissor`、`pixelStorei`、`finish`。模板测试真正参与光栅化，`clear(STENCIL_BUFFER_BIT)` 会清空模板附件；SDL_GPU 只有一份前后脸共用的 reference 与 compare/write mask，若前后脸设置不同，使用前脸值。
 - **读回**：`readPixels`（RGBA/UNSIGNED_BYTE），可从默认帧缓冲或绑定的 RGBA8 framebuffer 读取；浮点/深度附件先采样到 RGBA8 目标再读回。它会阻塞到 GPU 完成；用于测试和截图，不要每帧调用。
 
@@ -91,7 +110,9 @@ WebGL 2 额外提供：
 
 ## 未实现
 
-transform feedback（入口为空操作）与 MSAA/采样缓冲（SDL_GPU 的 Metal 多采样 resolve 在 scissor 与实例化绘制下返回未定义像素，因此上下文保持单采样）。`blitFramebuffer` 只复制颜色附件，深度/模板位被接受但不复制。使用内建块或 `gl_FragDepth` 的着色器会以编译/链接日志报错。
+transform feedback（入口为空操作：SDL_GPU 没有 transform feedback 阶段）与 MSAA/采样缓冲（SDL_GPU 3.2 能解析多采样颜色目标，但其 Metal resolve 在 scissor 与实例化绘制下会返回未定义像素，因此上下文保持单采样，`SAMPLE_BUFFERS` 报告 0）。`blitFramebuffer` 复制颜色与深度；模板位被接受但不复制，因为 SDL_GPU 无法采样模板附件。
+
+仍存在的着色器限制：结构体 uniform 与用户 uniform 块会被展平，但内建接口块（如重声明 `gl_PerVertex`）不在翻译子集内；使用它的着色器仍会以编译/链接日志失败，而不是静默出错。
 
 ## 平台
 
@@ -101,7 +122,8 @@ transform feedback（入口为空操作）与 MSAA/采样缓冲（SDL_GPU 的 Me
 
 ## 测试
 
-- `tests/e2e/gui-webgl.test.ts` 编译 GLSL、绘制带纹理和深度测试的四边形、检查面剔除，并读回像素；它还覆盖混合常量色、动态缓冲 usage、顶点着色器纹理采样、`gl_FragDepth` 诊断、上下文丢失/恢复与立方体贴图。
+- `tests/e2e/gui-webgl.test.ts` 编译 GLSL、绘制带纹理和深度测试的四边形、检查面剔除，并读回像素；它还覆盖混合常量色、动态缓冲 usage、顶点着色器纹理采样、`gl_FragDepth`、上下文丢失/恢复与立方体贴图。
+- `tests/e2e/gui-webgl2-shadow-sampler.test.ts` 覆盖硬件 `sampler2DShadow` 比较、着色器写 `gl_FragDepth` 遮挡后续绘制，以及 `blitFramebuffer` 的部分深度复制。
 - `tests/e2e/gui-webgl2.test.ts` 覆盖 WebGL 2 的着色器/状态新增能力：`#version 300 es` 着色器、VAO 往返、带 divisor 的实例化绘制、`texStorage2D`、`clearBufferfv`、缓冲拷贝、采样器对象、结构体 uniform 字段与 `drawingBufferStorage`。
 - `tests/e2e/gui-webgl2-formats.test.ts` 覆盖模板、浮点/深度纹理、压缩纹理与 `ImageBitmap`。
 - `tests/e2e/gui-webgl2-blit.test.ts` 覆盖带 scissor 的颜色/深度清除、framebuffer blit，以及局部 blit 之外必须保留的像素（在 Metal 上，若目标 load-op 丢弃这些像素，该测试就会失败）。
@@ -118,4 +140,4 @@ transform feedback（入口为空操作）与 MSAA/采样缓冲（SDL_GPU 的 Me
 
 着色器改写器会把 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/浮点渲染目标与压缩纹理已经可用。需要这些能力的场景无法正确渲染；此前 Canvas2D 回退能显示的内容现在全部走 GPU。
+本引擎子集之外的能力仍无法模拟：transform feedback 与 MSAA。立方体贴图/环境贴图、深度纹理、HDR/浮点渲染目标、压缩纹理与比较型 `sampler2DShadow` 采样都已可用（three.js 阴影贴图可在两个后端使用硬件深度比较）。需要 transform feedback 或 MSAA 的场景无法正确渲染；此前 Canvas2D 回退能显示的内容现在全部走 GPU。

package/doc/zh-CN/gui.md

@@ -2,7 +2,7 @@
 
 > 语言 / Language：[English](../gui.md) | **简体中文**
 
-状态：**M19** —— 功能（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** 真正播放
+状态：**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 在主线程解码，
 视频帧走图像纹理路径、音频进入 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 软件光栅器（抗锯齿
@@ -12,7 +12,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)。**M19** 补齐 CSS 装饰层：`@media` 查询、生成内容（`::before`/`::after`）、线性/径向多层背景、`text-shadow`、`clip-path` 与 `filter` 颜色/阴影效果。`backdrop-filter` 与真正的组模糊需要离屏合成器，仍为有文档说明的近似或未支持——见[绘制](./gui/rendering.md#背景生成内容与特效m19)。本总览记录了锁定决策、架构、里程碑计划与当前进度；引擎本身按功能拆分在以上各页中。
+[布局](./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` 与 `filter` 颜色/阴影效果。`backdrop-filter` 与真正的组模糊需要离屏合成器，仍为有文档说明的近似或未支持——见[绘制](./gui/rendering.md#背景生成内容与特效m19)。**M20** 让大文档保持可交互：`@media` 每条规则只求值一次，布局与绘制共享一个有界的整形缓存，一帧只做（也只提交）变更所要求的工作——见[性能](./gui/rendering.md#性能m20)。本总览记录了锁定决策、架构、里程碑计划与当前进度；引擎本身按功能拆分在以上各页中。
 
 ## 目录
 
@@ -273,6 +273,16 @@ FFmpeg `7.1`（供可选的 `media` 归档使用；可用 `SDL3_TAG` /
       [已知问题](./gui/known-issues.md)）。
     - e2e 覆盖见 `tests/e2e/gui-effects.test.ts`；参见
       [绘制](./gui/rendering.md#背景生成内容与特效m19)。
+20. **M20 — 渲染性能** ✅
+    - `@media` 每次重算样式时每条规则只求值一次；没有伪元素的样式表跳过生成
+      内容；只有样式表跟踪 `:hover`/`:focus` 时才因它们重算样式。
+    - 有界的两代整形缓存同时服务布局与绘制，并缓存主字体。
+    - 帧循环：只在文档变化时对齐媒体/画布表，只在发生事情时提交呈现，并据此
+      决定是否执行整帧工作。
+    - 复用显示列表/顶点暂存/transfer buffer，一个脏帧只提交一次上传，去掉
+      冗余的渲染状态绑定。
+    - `win.stats()`/`XT_GUI_PERF` 计数器与 `tests/e2e/gui-perf.test.ts`；参见
+      [性能](./gui/rendering.md#性能m20)。
 
 ## 进度日志
 
@@ -402,4 +412,17 @@ FFmpeg `7.1`（供可选的 `media` 归档使用；可用 `SDL3_TAG` /
   采样模糊/投影并生成 `text-shadow` run，`paint_clip.cpp`/`renderer_clip.cpp`
   对三角化的 `clip-path` 多边形裁剪几何。e2e 见
   `tests/e2e/gui-effects.test.ts`。
+- **M20** ✅ 渲染性能。`@media` 每次重算样式时每条规则只求值一次；没有
+  `::before`/`::after` 的样式表完全跳过生成内容；只有样式表包含
+  `:hover`/`:focus` 规则时才因这两个状态重算样式（`style.cpp`、
+  `css_sheet.cpp`）。一个有界的两代整形缓存（`text_cache.cpp`）同时服务布局与
+  绘制，因此一个词只整形一次，而不是每次布局和重绘都整形一次；主字体也按
+  （类别，字号）缓存。帧循环只在文档变化时对齐解码器/画布，并且只在确实发生了
+  事情时提交呈现（`gui_events.cpp`），因此静态页面不产生任何 GPU 工作
+  （调试时可用 `XT_GUI_ALWAYS_PRESENT=1` 恢复旧行为）。显示列表、顶点暂存与
+  transfer buffer 都被复用，一个脏帧的多次上传共用一次命令缓冲区提交，渲染器
+  只在状态真正变化时重新绑定（`renderer*.cpp`、`gui_engine.h`）。
+  `win.stats()` 报告帧耗时与累计工作量计数器，`XT_GUI_PERF` 打印它们
+  （`perf.{h,cpp}`）；`tests/e2e/gui-perf.test.ts` 用 200 行列表固化这些断言。
+  参见[性能](./gui/rendering.md#性能m20)。
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xbintsc",
-  "version": "0.5.38",
+  "version": "0.5.41",
   "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.38",
-    "@xbintsc/linux-arm64": "0.5.38",
-    "@xbintsc/darwin-x64": "0.5.38",
-    "@xbintsc/darwin-arm64": "0.5.38",
-    "@xbintsc/win32-x64": "0.5.38",
-    "@xbintsc/win32-arm64": "0.5.38"
+    "@xbintsc/linux-x64": "0.5.41",
+    "@xbintsc/linux-arm64": "0.5.41",
+    "@xbintsc/darwin-x64": "0.5.41",
+    "@xbintsc/darwin-arm64": "0.5.41",
+    "@xbintsc/win32-x64": "0.5.41",
+    "@xbintsc/win32-arm64": "0.5.41"
   },
   "engines": {
     "node": ">=22"

package/runtime/ext_gui/browser.cpp

@@ -337,6 +337,7 @@ xt_value type_proto(const std::string &name) {
   if (name == "WebGLSync") return domapi::webgl_object_proto("sync");
   if (name == "WebGLTransformFeedback") return domapi::webgl_object_proto("transformfeedback");
   if (name == "Path2D") return domapi::path2d_proto();
+  if (name == "OffscreenCanvas") return domapi::offscreen_canvas_proto();
   if (name == "ImageBitmap") {
     /* A bitmap is a plain immutable object, not a DOM node: a node proto would
      * expose the element width/height accessors and answer 0. */
@@ -383,6 +384,7 @@ xt_value host_type_construct(xt_value self, xt_value env, int32_t argc, xt_value
     return domapi::event_construct(xt_arg(argc, argv, 0), xt_arg(argc, argv, 1));
   }
   if (name == "Path2D") return domapi::path2d_create(xt_arg(argc, argv, 0));
+  if (name == "OffscreenCanvas") return domapi::offscreen_canvas_create(argc, argv);
   xt_value target = xt_object_new_with_proto(type_proto(name));
   set_prop(target, "constructor", type_value(name));
   return target;
@@ -518,7 +520,7 @@ xt_value xt_browser_type(int32_t argc, xt_value *argv) {
   (void)argv;
   if (argc < 1) return XT_UNDEFINED;
   std::string name = cstr(xt_arg(argc, argv, 0));
-  if (name == "XRWebGLLayer" || name == "XRWebGLBinding" || name == "OffscreenCanvas" ||
+  if (name == "XRWebGLLayer" || name == "XRWebGLBinding" ||
       name == "ImageData" || name == "Response" ||
       name == "ReadableStream" || name == "Request" || name == "Headers" ||
       name == "DOMParser") {