xbintsc 0.5.41 → 0.5.43

package/doc/gui/rendering.md

@@ -15,12 +15,14 @@ up to two indices into the display list's triangulated `clip-path` polygons, so
 `overflow`/`clip-path` clipping and `z-index` ordering survive into the renderer.
 `DisplayList::dump()` feeds `paintList()`/`paintCount()`.
 
-`opacity` is honoured only at its extremes: a box whose computed `opacity` is
-`0` (and its whole subtree) paints nothing, and anything above `0` paints fully
-opaque. A shape carries its colour's alpha only, so there is no compositing of a
-partly transparent box — the `opacity` transitions the CSS parser accepts are
-therefore not visible either. Hiding and revealing a layer with `opacity: 0` on
-the hidden state is what `examples/gui/pelican-bike`'s game-over overlay does.
+`opacity` multiplies the alpha of every colour painted by the box and its
+descendants (the values multiply down the paint chain), so fractional opacity and
+the `opacity` transitions the CSS parser accepts are visible. It is a
+per-shape approximation, not an offscreen group: overlapping children of a
+translucent box composite individually, whereas a browser composes the group
+once and then applies the alpha. `opacity: 0` still skips the whole subtree.
+Hiding and revealing a layer with `opacity: 0` on the hidden state is what
+`examples/gui/pelican-bike`'s game-over overlay does.
 
 `runtime/ext_gui/renderer.{h,cpp}` turns that list into batched vertex buffers
 per window (shapes, glyph quads and images) and merges consecutive ops that
@@ -80,18 +82,31 @@ The window background (`setBackground`) is the render-pass clear colour.
 comma-separated layer list is painted bottom-up (the first declaration layer is
 topmost), and both gradient kinds are supported:
 
-- a **linear** gradient is sampled at 18 points and emitted as solid rectangles;
-  `to <side>`, `deg`/`grad`/`rad`/`turn`, percentage and multi-stop colours work
-  (the band walk is axis-aligned, so an oblique angle uses the nearest axis);
-- a **radial** gradient is 32 concentric ellipses. Each is a unit-radius rounded
-  rectangle mapped through the shape pipeline's transform slot, so a circle or
-  ellipse keeps the distance-field antialiasing. Shape/size keywords
+- a **linear** gradient is sampled at 18 points (64 when repeating) and emitted
+  as solid rectangles; `to <side>`, `deg`/`grad`/`rad`/`turn`, percentage or
+  length (`px`/`em`/…) offsets, the `color <start> <end>` shorthand and
+  multi-stop colours work (the band walk is axis-aligned, so an oblique angle
+  uses the nearest axis);
+- a **radial** gradient is resolved per pixel in `renderer_gradient.cpp` into one
+  RGBA texture that is drawn as a single image quad (`PaintGradient`). Nesting the
+  bands instead would composite their alpha once per band — since every band
+  covers the whole interior — so a vignette whose stops fade to `transparent`
+  painted an opaque disc over the scene. Shape/size keywords
   (`circle`/`ellipse`, `closest-side`/`farthest-side`/`closest-corner`/
-  `farthest-corner`, explicit radii) and `at <position>` are parsed.
+  `farthest-corner`, explicit radii) and `at <position>` are parsed; a
+  keyword-sized ellipse keeps the box's aspect ratio and is scaled until it meets
+  the side or corner, as CSS does. Stops interpolate in premultiplied alpha, and
+  the last stop extends past the ending shape over the rest of the box.
+
+`repeating-linear-gradient()` and `repeating-radial-gradient()` tile the stop
+pattern from 0 to the last stop's offset across the whole box; the stop list is
+not forced to end at 100%, so `red 0%, blue 10%` repeats every 10%. A normal
+gradient whose last stop is below 100% holds that colour for the rest of the box,
+as in CSS.
 
 The background colour sits under every layer. Gradients are partially
-transparent if their stops are, and the band approximation can show banding and
-alpha stacking on a very translucent multi-stop gradient.
+transparent if their stops are; a radial gradient is exact per pixel, while a
+linear one still samples 18 bands and can show banding on a large soft ramp.
 
 **Generated content** needs no new display-list kind: `::before`/`::after` are
 ordinary layout boxes owned by the per-restyle arena in `style.cpp`, so their
@@ -117,10 +132,24 @@ nesting keeps the outermost two.
 colour, so a box and its descendants see the filter. `blur()` and
 `drop-shadow()` are approximations at the display-list level: blur spreads nine
 translucent copies per shape, drop-shadow is a box/text silhouette. This keeps
-the single render pass — there is no offscreen render target — at the cost of
-group semantics: overlapping descendants of a blurred/filtered group can darken,
-and `backdrop-filter` cannot sample what is behind the element, so it parses and
-cascades but paints nothing.
+the ordinary painter single-pass at the cost of group semantics: overlapping
+descendants of a blurred/filtered group can darken, and `backdrop-filter` cannot
+sample what is behind the element, so it parses and cascades but paints nothing.
+
+**`mix-blend-mode`** is the exception that does need an offscreen layer. A box
+with a non-`normal` mode is wrapped in `LayerBegin`/`LayerEnd` markers (visible
+in `paintList()` as `layer blend=…` / `end-layer`); the renderer draws that group
+to a full-viewport offscreen texture and composites it over the scene with a
+small GLSL blend shader. All sixteen CSS modes (`multiply`, `screen`, `overlay`,
+`darken`, `lighten`, `color-dodge`, `color-burn`, `hard-light`, `soft-light`,
+`difference`, `exclusion`, `hue`, `saturation`, `color`, `luminosity`) are
+implemented with the compositing-spec formulas. The shader is compiled at run
+time by the bundled glslang (SPIR-V for Vulkan) and cross-compiled to MSL by
+SPIRV-Cross (Metal); the two scene textures per nesting level are reused across
+frames and ping-pong so the backdrop stays sampleable while it is written.
+Backends that consume neither format — the D3D12/DXIL path, which has no shader
+compiler here — keep painting the group with ordinary source-over blending.
+`backdrop-filter` still paints nothing.
 
 ## Text stack (M4b)
 

package/doc/gui.md

@@ -40,10 +40,11 @@ them) can be translated, scaled and rotated without reflowing anything — and
 [Animation](./gui/animation.md#css-transforms-m15).
 **M17** adds real **WebGL 1.0**, and **M18** adds **WebGL 2.0**: `<canvas>.getContext("webgl2")` accepts `#version 300 es` shaders, vertex-array objects, instanced draws and sampler objects, all compiled to SPIR-V by the bundled glslang (and to MSL by the bundled SPIRV-Cross on Metal) and rendered through SDL_GPU. Geometry, lighting, texture sampling and blending run on the GPU and the page composites the colour texture without a readback — see [WebGL](./gui/webgl.md).
 **M19** fills in the decorative CSS layer: `@media` queries, generated content
-(`::before`/`::after`), multi-layer linear/radial backgrounds, `text-shadow`,
-`clip-path` and the `filter` colour/shadow effects. `backdrop-filter` and true
-group blur need an offscreen compositor and remain documented approximations or
-unsupported — see [Rendering](./gui/rendering.md#backgrounds-generated-content-and-effects-m19).
+(`::before`/`::after`), multi-layer linear/radial/repeating backgrounds,
+`text-shadow`, `clip-path`, `mix-blend-mode` (through an offscreen compositor)
+and the `filter` colour/shadow effects. `backdrop-filter` still needs a backdrop
+snapshot, and true group blur remains an approximation — see
+[Rendering](./gui/rendering.md#backgrounds-generated-content-and-effects-m19).
 **M20** makes large documents interactive: `@media` is evaluated once per rule,
 layout and paint share a bounded shaping cache, and a frame only does (and
 presents) the work a change requires — see
@@ -335,8 +336,9 @@ engine were Rust.
     - Generated content: `::before`/`::after` selectors, inherited pseudo styles,
       `content` strings/escapes/`attr()`, and synthetic layout boxes that never
       leak into DOM traversal.
-    - Multi-layer `background-image` with linear and radial gradients, painted
-      bottom-up as solid bands (18 strips / 32 concentric ellipses).
+    - Multi-layer `background-image` with linear gradients painted bottom-up as
+      solid bands (18 strips) and radial gradients rasterised per pixel into one
+      image texture (`renderer_gradient.cpp`).
     - `text-shadow` as shadow text runs, including a nine-tap blur approximate.
     - `clip-path` polygons (`inset`/`circle`/`ellipse`/`polygon`) resolved to
       device space, ear-clipped and intersected with shape geometry in
@@ -502,8 +504,10 @@ engine were Rust.
   pseudo styles into a per-restyle arena, resolves `content`, and layout inserts
   their boxes before/after the DOM children. `gradient_values.cpp` models a
   background layer list (linear/radial, shape/size/position/stops),
-  `paint_background.cpp` paints it, `paint_effects.cpp` applies filter colour
-  functions plus nine-tap blur/drop-shadow and emits `text-shadow` runs, and
+  `paint_background.cpp` resolves and paints it (radial layers become one
+  `PaintGradient`, which `renderer_gradient.cpp` rasterises into a texture),
+  `paint_effects.cpp` applies filter colour functions plus nine-tap
+  blur/drop-shadow and emits `text-shadow` runs, and
   `paint_clip.cpp`/`renderer_clip.cpp` clip geometry against triangulated
   `clip-path` polygons. E2E: `tests/e2e/gui-effects.test.ts`.
 - **M20** ✅ rendering performance. `@media` is evaluated once per rule per

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

@@ -175,7 +175,7 @@ win.queryCount(selector)               // 匹配元素的数量
 win.getBoundingClientRect(selector)    // { x, y, width, height }（边框盒，含变换）
 win.documentTree()                     // 序列化的 DOM（调试用）
 win.layoutTree()                       // 序列化的布局盒（调试用）
-win.paintCount()                       // 显示列表中图形的数量
+win.paintCount()                       // 显示列表中填充矩形的数量
 win.paintList()                        // 序列化的显示列表（调试用）
 win.inlineSvg(selector)                // 序列化的内联 <svg>：{ markup, width, height, shapes }
 win.measureText(text, fontSize?, family?)  // 整形后的推进宽度（像素）

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

@@ -166,8 +166,10 @@ canvas 由脚本重绘而不是引擎重绘，因此开销按绘制调用计。
 9 参数（本引擎为**目标优先**：`dx, dy, dw, dh, sx, sy, sw, sh`）。完整的仿射变换
 （旋转/斜切/缩放）会被应用：目标矩形变为平行四边形，每个设备像素反查到源矩形。
 `source` 可以是 `<img>` 元素（经图像模块解码）、另一个 `<canvas>`、
-`OffscreenCanvas` 或 `ImageBitmap`。`imageSmoothingEnabled` 为 `true`（默认）时使用
-双线性采样，为 `false` 时使用最近邻。
+`OffscreenCanvas`、`ImageBitmap`，或——本引擎的扩展——直接传字符串路径/`data:` URL，
+由图像模块解码，因此 SVG 或位图的 data URL 无需 `<img>` 就能绘制。矢量源按目标尺寸
+（`dw`/`dh`）光栅化，放大时 SVG 依然清晰。`imageSmoothingEnabled` 为 `true`（默认）
+时使用双线性采样，为 `false` 时使用最近邻。
 
 测试钩子：`getImageData(x, y, w, h)` 把区域复制为 `{ width, height, data }`，其中
 `data` 是按行主序的 RGBA8 字节数组。越界像素为透明。
@@ -186,8 +188,8 @@ dirtyWidth, dirtyHeight])` 直接把字节写入位图（不受变换、混合
 `OffscreenCanvas.convertToBlob()` 解析为同一形状，`transferToImageBitmap()` 对位图
 做快照。
 
-CSS 背景：`background-image: url(...)` 接受文件路径或 `data:` URL，因此可以先把
-canvas 导出再作为 CSS 背景使用
+CSS 背景：`background-image: url(...)` 接受文件路径或 `data:` URL（位图载荷或 SVG
+文档，base64 或百分号编码均可），因此可以先把 canvas 导出再作为 CSS 背景使用
 （`element.style.backgroundImage = "url(" + canvas.toDataURL() + ")"`）。图像层会拉伸
 到元素的边框盒；`background-size`、`background-position` 与平铺尚未建模。
 

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

@@ -43,22 +43,26 @@
   `var()` 自定义属性、`inset` 简写、`box-sizing`、`visibility`/`pointer-events`、
   `@media` 查询、生成内容（`::before`/`::after`）、线性/径向多层背景、
   `text-shadow`、`clip-path`（`inset`/`circle`/`ellipse`/`polygon`）以及 `filter`
-  的颜色函数。仍有限制：`mix-blend-mode`、`background-clip`、
-  `background-position`/`size`/`repeat`、重复渐变与 `backdrop-filter` 合成都未实现
-  （`backdrop-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`（更深时保留外侧两层）；
   图像/画布除图像着色器能携带的亮度与透明度染色外不做颜色滤镜。Canvas 纹理使用
-  最近邻采样。背景渐变仍是纯色带（线性 18 条、径向 32 个同心椭圆），柔和渐变可能
-  出现轻微条带。
+  最近邻采样。背景线性渐变仍是纯色带（18 条，重复渐变 64 条），较大的柔和渐变
+  可能出现轻微条带；径向渐变则逐像素光栅化成纹理（每边最大 1024 px，超出后拉伸，
+  因此超大盒子上的硬色标会略微变软）。
 - **SVG 是 NanoSVG 的子集。** SVG *文件*（`<img src="logo.svg">`）与内联
   `<svg>` 子树共用 vendored 的 NanoSVG 解析/光栅化器（`runtime/ext_gui/svg.cpp`、
   `inline_svg.cpp`），它会渲染 `path`/`rect`/`circle`/`ellipse`/`line`/
   `polyline`/`polygon`、组、`defs` 渐变以及基于 `class` 的 `<style>` 规则。
   `<text>`、`<use>`、滤镜、遮罩与裁剪路径不会渲染，文档层叠的 CSS 也不会进入
-  图像内部（这里的 `fill`/`stroke` 是 SVG 表现属性，不是 CSS 属性）。需要这些
-  能力的矢量美术必须预先光栅化、用盒子绘制，或限制在受支持的语法内。参见
-  [媒体](./media.md#图像m6a)。
+  图像内部（这里的 `fill`/`stroke` 是 SVG 表现属性，不是 CSS 属性）。因此只靠滤镜
+  出图的 SVG（`feTurbulence` 噪声、模糊等）会显示未经过滤的形状——常见情况是一个
+  纯色矩形——而不是滤镜结果。需要这些能力的矢量美术必须预先光栅化、用盒子绘制，
+  或限制在受支持的语法内。参见[媒体](./media.md#图像m6a)。
 - **每次变更仍是整文档重算。** 一次 DOM 变更会重新计算层叠并重新布局整个文档
   （没有增量子树失效），只影响绘制的变更（例如 hover 颜色）同样会重排。带生成
   内容（`::before`/`::after`）的文档没有特殊处理。各阶段的实测开销由

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

@@ -35,6 +35,13 @@ PNG/JPEG/BMP/GIF/TGA 解码为 RGBA8，并带有解码缓存与仅头文件的
   （最近最少使用），动画文档不会让它无限增长。
 - 解析结果按路径缓存；解析与光栅化器状态在 `xt_svg_shutdown`
   （`xt_image_shutdown`）中释放。
+- `data:` URL 在内存中解码，凡接受路径的地方都可使用：`<img src>`、CSS
+  `background-image` 与 `canvas.drawImage(url, …)`。既支持 `;base64` 形式，也支持
+  百分号编码（或原样）的载荷，`base64` 标志大小写不敏感。MIME 类型只用于分类：
+  `image/svg+xml`（或 MIME 为通用/缺失时按内容嗅探出 SVG）走 NanoSVG——data URL
+  里的 SVG 与 SVG 文件一样按绘制尺寸光栅化；PNG/JPEG/BMP/GIF/TGA 走
+  `stb_image`。NanoSVG 的子集限制仍然生效：只靠 `<filter>`（`feTurbulence` 等）
+  出图的 SVG 能解码、能布局，但滤镜本身会被忽略。
 
 文档 CSS 只作用于 `<svg>` **盒子**——尺寸、外边距、背景、边框、`transform`、
 opacity、`display`——与任何其他元素一样。盒子内部的艺术内容保持 SVG 语义：
@@ -45,8 +52,8 @@ opacity、`display`——与任何其他元素一样。盒子内部的艺术内
 重写艺术内容的程序会为每个变体保留一张纹理；更好的做法是用 `transform`、
 `opacity` 给盒子做动画，或在一小组文档之间切换。
 
-图像仍需完成：CSS `background-image: url(...)`、`data:` URI、`object-fit`、
-九宫格边框。
+图像仍需完成：`object-fit`、九宫格边框。（CSS `background-image: url(...)` 与
+`data:` URL 已支持。）
 
 两种 SVG 都受限于 NanoSVG 的子集：`path`、`rect`、`circle`、`ellipse`、
 `line`、`polyline`、`polygon`、组（`g`）、带线性/径向渐变的 `defs` 以及基于

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

@@ -15,9 +15,10 @@
 顺序都能保留到渲染器。`DisplayList::dump()` 为 `paintList()`/`paintCount()`
 提供数据。
 
-`opacity` 只在两端生效：计算值为 `0` 的盒子（及其整棵子树）不绘制任何内容，
-大于 `0` 的一律按完全不透明绘制。图形只携带其颜色自身的 alpha，因此没有部分
-透明盒子的合成——CSS 解析器接受的 `opacity` 过渡因此也看不到效果。把隐藏态写成
+`opacity` 会乘到该盒子及其后代绘制的每个颜色 alpha 上（沿绘制链逐层相乘），
+因此小数 opacity 以及 CSS 解析器接受的 `opacity` 过渡都能看到效果。这是按图形
+逐个近似的，而不是离屏分组：半透明盒子的重叠子元素会各自合成，浏览器则先把整组
+合成一次再应用 alpha。`opacity: 0` 仍会跳过整棵子树。把隐藏态写成
 `opacity: 0` 来隐藏/显示一层，正是 `examples/gui/pelican-bike` 游戏结束遮罩的做法。
 
 `runtime/ext_gui/renderer.{h,cpp}` 把该列表转换为每个窗口的批处理顶点缓冲
@@ -67,16 +68,25 @@
 `background-color` 与每一条 `background-image` 层都会绘制。逗号分隔的层列表按
 从底到上的顺序绘制（声明中的第一层在最上面），两种渐变均受支持：
 
-- **线性**渐变在 18 个位置采样并输出为纯色矩形；支持 `to <side>`、
-  `deg`/`grad`/`rad`/`turn`、百分比与多色标（色带沿最近轴行走，因此斜角会退化为
+- **线性**渐变在 18 个位置采样（重复渐变 64 个）并输出为纯色矩形；支持
+  `to <side>`、`deg`/`grad`/`rad`/`turn`、百分比或长度（`px`/`em`/…）偏移、
+  `color <start> <end>` 简写与多色标（色带沿最近轴行走，因此斜角会退化为
   最近的轴向）；
-- **径向**渐变是 32 个同心椭圆。每个都是单位半径的圆角矩形，经图形管线的
-  transform 槽映射，因此圆/椭圆仍保留距离场抗锯齿。支持形状/尺寸关键字
-  （`circle`/`ellipse`、`closest-side`/`farthest-side`/`closest-corner`/
-  `farthest-corner`、显式半径）与 `at <position>`。
-
-背景色位于所有层下方。若渐变色标带透明度，渐变也会半透明；色带近似可能产生
-轻微条带，非常透明的多色标渐变会出现 alpha 叠加。
+- **径向**渐变由 `renderer_gradient.cpp` 逐像素解算成一张 RGBA 纹理，作为单个
+  图像四边形绘制（`PaintGradient`）。若沿用嵌套色带，由于每条色带都会覆盖整个
+  内部区域，alpha 会叠加多次——淡出到 `transparent` 的暗角会把整个场景涂成实心
+  黑盘。支持形状/尺寸关键字（`circle`/`ellipse`、`closest-side`/`farthest-side`/
+  `closest-corner`/`farthest-corner`、显式半径）与 `at <position>`；关键字尺寸
+  的椭圆保持盒子的宽高比并缩放到刚好接触对应边或角，与 CSS 一致。色标在预乘
+  alpha 空间中插值，最后一个色标会延伸覆盖结束形状之外的剩余盒子。
+
+`repeating-linear-gradient()` 与 `repeating-radial-gradient()` 会在整个盒子上
+从 0 平铺到最后一个色标的偏移量；色标列表不会被强制结束在 100%，因此
+`red 0%, blue 10%` 每 10% 重复一次。普通渐变的最后一个色标若小于 100%，则剩余
+区域保持该颜色，与 CSS 一致。
+
+背景色位于所有层下方。若渐变色标带透明度，渐变也会半透明；径向渐变逐像素精确，
+线性渐变仍采样 18 条色带，较大的柔和渐变可能出现条带。
 
 **生成内容**不需要新的显示列表类型：`::before`/`::after` 是 `style.cpp` 中
 每次重算样式时重建的普通布局盒，因此其背景、边框、文本与 transform 都走同一条
@@ -96,9 +106,21 @@ shader 改动，但边缘是硬边（没有解析抗锯齿）。支持两层嵌
 **`filter`** 的颜色函数（`brightness`、`contrast`、`grayscale`、`sepia`、
 `invert`、`saturate`、`hue-rotate`、`opacity`）会折进每个绘制颜色，因此盒子与
 其后代都会看到滤镜。`blur()` 与 `drop-shadow()` 是显示列表层面的近似：模糊把每个
-图形展开成九个半透明副本，投影用盒子/文字轮廓。这样保持单渲染通道（没有离屏
-渲染目标），代价是组语义：被模糊/滤镜的组内重叠后代可能加深；`backdrop-filter`
-无法采样元素背后的内容，因此会解析并参与层叠，但不绘制。
+图形展开成九个半透明副本，投影用盒子/文字轮廓。这样普通绘制保持单渲染通道，代价
+是组语义：被模糊/滤镜的组内重叠后代可能加深；`backdrop-filter` 无法采样元素背后
+的内容，因此会解析并参与层叠，但不绘制。
+
+**`mix-blend-mode`** 是唯一真正需要离屏图层的例外。非 `normal` 的盒子会被
+`LayerBegin`/`LayerEnd` 标记包住（在 `paintList()` 中显示为 `layer blend=…` /
+`end-layer`），渲染器把该组绘制到全视口离屏纹理，再用一个小型 GLSL 混合
+shader 合成到场景上。全部十六种 CSS 模式（`multiply`、`screen`、`overlay`、
+`darken`、`lighten`、`color-dodge`、`color-burn`、`hard-light`、`soft-light`、
+`difference`、`exclusion`、`hue`、`saturation`、`color`、`luminosity`）都按
+合成规范公式实现。shader 在运行时由内置 glslang 编译（Vulkan 用 SPIR-V），
+再由 SPIRV-Cross 交叉编译为 MSL（Metal）；每个嵌套层级的两张场景纹理跨帧复用，
+并通过 ping-pong 让背景在写入时仍可采样。既不吃 SPIR-V 也不吃 MSL 的后端
+（这里的 D3D12/DXIL 路径没有 shader 编译器）仍用普通 source-over 混合绘制该组。
+`backdrop-filter` 依旧不绘制。
 
 ## 文本技术栈（M4b）
 

package/doc/zh-CN/gui.md

@@ -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)。**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)。**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)。本总览记录了锁定决策、架构、里程碑计划与当前进度；引擎本身按功能拆分在以上各页中。
 
 ## 目录
 
@@ -262,8 +262,8 @@ FFmpeg `7.1`（供可选的 `media` 归档使用；可用 `SDL3_TAG` /
       特性）；`matchMedia()` 使用同一个求值器。
     - 生成内容：`::before`/`::after` 选择器、继承的伪样式、`content` 字符串/
       转义/`attr()`，以及不会泄漏到 DOM 遍历的合成布局盒。
-    - 多层 `background-image` 的线性与径向渐变，自下而上按纯色带绘制
-      （线性 18 条、径向 32 个同心椭圆）。
+    - 多层 `background-image`：线性渐变自下而上按纯色带绘制（18 条），径向渐变
+      逐像素光栅化成一张图像纹理（`renderer_gradient.cpp`）。
     - `text-shadow` 作为阴影文本 run，并带九次采样模糊近似。
     - `clip-path` 多边形（`inset`/`circle`/`ellipse`/`polygon`）解析到设备空间，
       用耳切法三角化，并在 `renderer_clip.cpp` 中与图形几何求交——不需要模板/
@@ -408,9 +408,10 @@ FFmpeg `7.1`（供可选的 `media` 归档使用；可用 `SDL3_TAG` /
   识别 `::before`/`::after`。`style.cpp` 把伪样式算进每次重算样式时重建的
   arena、解析 `content`，布局在真实子元素前后插入它们的盒子。
   `gradient_values.cpp` 建模背景层列表（线性/径向、形状/尺寸/位置/色标），
-  `paint_background.cpp` 绘制它，`paint_effects.cpp` 应用滤镜颜色函数与九次
-  采样模糊/投影并生成 `text-shadow` run，`paint_clip.cpp`/`renderer_clip.cpp`
-  对三角化的 `clip-path` 多边形裁剪几何。e2e 见
+  `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`。
 - **M20** ✅ 渲染性能。`@media` 每次重算样式时每条规则只求值一次；没有
   `::before`/`::after` 的样式表完全跳过生成内容；只有样式表包含

package/package.json

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

package/runtime/ext_gui/dom_api_canvas.cpp

@@ -468,41 +468,59 @@ METHOD(canvas_draw_image) {
   (void)env;
   xtgui::Canvas2D *canvas = context_canvas(self);
   if (canvas == nullptr || argc < 3) return XT_UNDEFINED;
+
+  const bool has_destination = argc >= 5;
+  const float dx = (float)number_arg(argc, argv, 1, 0.0);
+  const float dy = (float)number_arg(argc, argv, 2, 0.0);
+  const float destination_width =
+      has_destination ? (float)number_arg(argc, argv, 3, 0.0) : 0.0f;
+  const float destination_height =
+      has_destination ? (float)number_arg(argc, argv, 4, 0.0) : 0.0f;
+  auto raster_target = [](float value) -> int {
+    return value > 0.0f ? (int)(value + 0.5f) : 0;
+  };
+
   XtGuiWindow *win = nullptr;
   xt_value source_value = xt_arg(argc, argv, 0);
   const xtgui::Image *image = nullptr;
-  /* An `OffscreenCanvas` (or a transferred one) has no DOM node; its bitmap is
-   * reachable through the process-wide canvas id. */
-  if (XT_IS_OBJECT(source_value)) {
-    xt_value canvas_id = xt_object_get_cstr(source_value, "__xt_gui_canvas");
-    if (XT_IS_NUMBER(canvas_id)) {
-      xtgui::Canvas2D *offscreen = xtgui::xt_canvas_by_id((uint64_t)xt_to_number(canvas_id));
-      if (offscreen != nullptr) {
-        image = &offscreen->image();
+  if (XT_IS_STRING(source_value)) {
+    /* Engine extension: the source may be a path or a `data:` URL itself, so a
+     * data-URL bitmap/SVG can be drawn without an `<img>` element. */
+    const std::string source_url(xt_string_data(source_value));
+    image = xtgui::xt_image_load(source_url, raster_target(destination_width),
+                                 raster_target(destination_height));
+  } else {
+    /* An `OffscreenCanvas` (or a transferred one) has no DOM node; its bitmap
+     * is reachable through the process-wide canvas id. */
+    if (XT_IS_OBJECT(source_value)) {
+      xt_value canvas_id = xt_object_get_cstr(source_value, "__xt_gui_canvas");
+      if (XT_IS_NUMBER(canvas_id)) {
+        xtgui::Canvas2D *offscreen = xtgui::xt_canvas_by_id((uint64_t)xt_to_number(canvas_id));
+        if (offscreen != nullptr) image = &offscreen->image();
+      }
+    }
+    if (image == nullptr) {
+      xtgui::Node *source = resolve_node(source_value, &win);
+      if (source != nullptr && source->isElement() && source->isTag("img")) {
+        const std::string *src = source->attr("src");
+        if (src != nullptr) {
+          image = xtgui::xt_image_load(*src, raster_target(destination_width),
+                                       raster_target(destination_height));
+        }
+      } else if (source != nullptr) {
+        xtgui::Canvas2D *other = xt_gui_canvas_find(win, source);
+        if (other != nullptr) image = &other->image();
       }
     }
-  }
-  xtgui::Node *source = resolve_node(source_value, &win);
-  if (source != nullptr && source->isElement() && source->isTag("img")) {
-    const std::string *src = source->attr("src");
-    if (src != nullptr) image = xtgui::xt_image_load(*src);
-  } else if (source != nullptr) {
-    xtgui::Canvas2D *other = xt_gui_canvas_find(win, source);
-    if (other != nullptr) image = &other->image();
   }
   if (image == nullptr || image->width <= 0 || image->height <= 0) return XT_UNDEFINED;
-  float dx = (float)number_arg(argc, argv, 1, 0.0);
-  float dy = (float)number_arg(argc, argv, 2, 0.0);
-  float dw = (float)image->width;
-  float dh = (float)image->height;
+
+  const float dw = has_destination ? destination_width : (float)image->width;
+  const float dh = has_destination ? destination_height : (float)image->height;
   float sx = 0.0f;
   float sy = 0.0f;
   float sw = (float)image->width;
   float sh = (float)image->height;
-  if (argc >= 5) {
-    dw = (float)number_arg(argc, argv, 3, (double)dw);
-    dh = (float)number_arg(argc, argv, 4, (double)dh);
-  }
   if (argc >= 9) {
     sx = (float)number_arg(argc, argv, 5, 0.0);
     sy = (float)number_arg(argc, argv, 6, 0.0);

package/runtime/ext_gui/gradient_values.cpp

@@ -134,67 +134,59 @@ bool parseGradientColor(const std::string &token, Color *color, std::string *res
   return true;
 }
 
-/** Parse one `[<percent>]` / `<number>` offset. */
-bool parseGradientOffset(const std::string &raw, float *out) {
+/** Parse one gradient stop offset: a percentage, a length (`px`, `em`, …) or a
+ * bare number (0.5 = 50%, 50 = 50%). */
+bool parseGradientOffset(const std::string &raw, Length *out) {
   std::string text = xt_css_trim(raw);
   if (text.empty()) return false;
-  bool percent = text.back() == '%';
-  if (percent) text.pop_back();
+  if (text.back() == '%') {
+    float value = 0;
+    if (!xt_css_parse_number(text.substr(0, text.size() - 1), &value)) return false;
+    *out = Length{value, Unit::Percent};
+    return true;
+  }
   float value = 0;
-  if (!xt_css_parse_number(text, &value)) return false;
-  if (percent) value /= 100.0f;
-  else if (value > 1.0f) value /= 100.0f;
-  if (value < 0) value = 0;
-  if (value > 1) value = 1;
-  *out = value;
-  return true;
+  if (xt_css_parse_number(text, &value)) {
+    /* Unitless offsets are fractions of the gradient line, matching the old
+     * parser: `0.5` is 50% and `50` is also 50%. */
+    if (value > 1.0f) *out = Length{value, Unit::Percent};
+    else *out = Length{value * 100.0f, Unit::Percent};
+    return true;
+  }
+  Length length = xt_css_parse_length(text);
+  if (length.unit != Unit::Invalid && length.unit != Unit::Auto &&
+      length.unit != Unit::None && length.unit != Unit::Number) {
+    *out = length;
+    return true;
+  }
+  return false;
 }
 
-/** Parse a comma-separated `[color [offset [offset]]]` stop list. */
+/** Parse a comma-separated `[color [offset [offset]]]` stop list. Offsets stay
+ * unresolved here: `px` is resolved against the gradient line in paint. */
 bool parseStops(const std::string &text, std::vector<BackgroundGradientStop> *stops) {
   std::vector<std::string> parts = splitCommas(text);
   if (parts.size() < 2) return false;
-  float last = -1.0f;
   for (const std::string &part : parts) {
     Color color;
     std::string rest;
     if (!parseGradientColor(part, &color, &rest)) continue;
     BackgroundGradientStop stop;
     stop.color = color;
-    stop.offset = -1.0f;
-    if (!rest.empty()) {
-      std::vector<std::string> offsets = splitTokens(rest);
-      if (!offsets.empty()) {
-        float first = 0;
-        if (parseGradientOffset(offsets[0], &first)) {
-          stop.offset = first;
-          if (stop.offset < last) stop.offset = last;
-          last = stop.offset;
-        }
+    std::vector<std::string> offsets = splitTokens(rest);
+    if (!offsets.empty() && parseGradientOffset(offsets[0], &stop.offset)) {
+      /* `color <start> <end>` is shorthand for the same colour at both offsets
+       * (a hard band), so emit the second stop too. */
+      stops->push_back(stop);
+      if (offsets.size() > 1) {
+        BackgroundGradientStop end = stop;
+        if (parseGradientOffset(offsets[1], &end.offset)) stops->push_back(end);
       }
+    } else {
+      stops->push_back(stop);
     }
-    stops->push_back(stop);
-  }
-  if (stops->size() < 2) return false;
-  /* Fill implicit offsets by distributing them between their neighbours. */
-  size_t i = 0;
-  while (i < stops->size()) {
-    if ((*stops)[i].offset >= 0) {
-      i++;
-      continue;
-    }
-    size_t j = i;
-    while (j < stops->size() && (*stops)[j].offset < 0) j++;
-    float before = (i == 0) ? 0.0f : (*stops)[i - 1].offset;
-    float after = (j >= stops->size()) ? 1.0f : (*stops)[j].offset;
-    size_t count = j - i;
-    for (size_t k = 0; k < count; k++)
-      (*stops)[i + k].offset = before + (after - before) * (float)(k + 1) / (float)(count + 1);
-    i = j;
   }
-  stops->front().offset = 0.0f;
-  stops->back().offset = 1.0f;
-  return true;
+  return stops->size() >= 2;
 }
 
 /** CSS gradient direction/angle. Returns true when `text` was a direction. */
@@ -395,14 +387,18 @@ bool parseRadialGradient(const std::string &body, BackgroundLayer *layer) {
 /** Parse one layer, appending it when it is a supported gradient or image. */
 bool parseLayer(const std::string &part, BackgroundLayer *layer) {
   std::string body;
-  if (findCall(part, "linear-gradient", &body) ||
-      findCall(part, "repeating-linear-gradient", &body)) {
+  /* The repeating prefix is checked first: a plain substring search for
+   * `linear-gradient(` would also match inside `repeating-linear-gradient(`. */
+  if (findCall(part, "repeating-linear-gradient", &body)) {
+    layer->repeating = true;
     return parseLinearGradient(body, layer);
   }
-  if (findCall(part, "radial-gradient", &body) ||
-      findCall(part, "repeating-radial-gradient", &body)) {
+  if (findCall(part, "linear-gradient", &body)) return parseLinearGradient(body, layer);
+  if (findCall(part, "repeating-radial-gradient", &body)) {
+    layer->repeating = true;
     return parseRadialGradient(body, layer);
   }
+  if (findCall(part, "radial-gradient", &body)) return parseRadialGradient(body, layer);
   if (findCall(part, "url", &body)) {
     std::string source = xt_css_trim(body);
     if (source.size() >= 2 && (source.front() == '"' || source.front() == '\'') &&