xbintsc 0.3.79 → 0.3.81

package/doc/gui/dom.md

@@ -20,7 +20,12 @@ pseudo-classes `:first-child`, `:last-child`, `:only-child`, `:empty`,
 stateful `:hover` and `:focus` (see [Input](./input.md)). Values:
 lengths (`px`, `%`, `em`, `rem`, `vw`, `vh`, `pt`, `pc`, `in`, `cm`, `mm`, `q`),
 colors (hex, `rgb()`/`rgba()`, a named subset), numbers, keywords and shorthands
-(`margin`/`padding`/`border`/`flex`).
+(`margin`/`padding`/`border`/`flex`). `transform` (`translate`/`translate3d`/
+`translateX`/`translateY`, `scale`/`scale3d`/`scaleX`/`scaleY`, `rotate`/
+`rotateZ`, `matrix`; the `3d` spellings' `z` argument is dropped) and
+`transform-origin` are parsed into the computed style as a list of operations
+plus two (unresolved) origin lengths; an unsupported function invalidates the
+whole declaration ([Layout](./layout.md#transforms-m15)).
 
 **Cascade & computed style** (`runtime/ext_gui/style.{h,cpp}`): a small built-in
 UA stylesheet, author rules sorted by `(!important, specificity, source order)`,

package/doc/gui/input.md

@@ -6,7 +6,10 @@
 
 `LayoutTree::hitTest` returns the deepest box containing a point (probing later
 siblings first so the topmost element wins), and `xt_dom_describe` turns the
-element into the `div#id.class` descriptor carried by event payloads.
+element into the `div#id.class` descriptor carried by event payloads. A
+transformed box maps the point through its inverse matrix first, so a rotated,
+scaled or translated element is hit exactly where it is drawn — and `:hover`
+follows the artwork, not the box flow left behind.
 
 - SDL pointer/wheel/key events are routed to the owning window, hit tested, and
 delivered to the handlers registered with `on`. `mousedown` also moves focus.

package/doc/gui/known-issues.md

@@ -48,11 +48,23 @@
   rectangles/text/images, so `<svg>` subtrees would need a whole second
   geometry+paint path. Vector art therefore has to arrive as an SVG/PNG file or
   be drawn from boxes, as `examples/gui/pelican-bike` does.
+- **Windows: the C++ runtime must not be named on the link line.** `gui.lib` is
+  built with the *static* CRT (`CMAKE_MSVC_RUNTIME_LIBRARY=MultiThreaded`) and
+  every engine object records `libcpmt` as a dependent library, which is also
+  clang's Windows default and what the xbintsc runtime objects use
+  (`scripts/build-gui.ts`). Asking for the DLL runtime as well — the gui
+  extension used to pass `-lmsvcprt` — makes the two copies of the same symbols
+  collide: `LNK2038: mismatch detected for 'RuntimeLibrary'` plus a wall of
+  `LNK2005: already defined`, surfaced as `clang: linker command failed with exit
+  code 1169`. `src/extensions/gui/index.ts` now lists only the OS libraries
+  (`user32`, `gdi32`, `d3d12`, …). A Windows link is also the only place the
+  MSVC environment matters, so build from an x64 Native Tools prompt.
 - Windows: an MSVC-compatible `gui.lib` (COFF objects + `ar -M`/`llvm-ar`) is
-  produced by `scripts/build-gui.ts`, but it has not been validated in CI yet,
-  so the Windows step is provisional (the job stays green) and `package` skips
-  it. It also needs an SDL3 build with the D3D12/DXIL backend (DXIL requires
-  `dxc`).
+  produced by `scripts/build-gui.ts` but is not validated in CI, so the Windows
+  step is provisional (the job stays green) and `package` skips it. Building and
+  running `examples/gui/pelican-svg` and `examples/gui/pelican-bike` on a
+  developer machine works. It also needs an SDL3 build with the D3D12/DXIL
+  backend (DXIL requires `dxc`).
 - **Media on Windows:** the media decoders (FFmpeg) are only built and merged
   into the POSIX `gui.a`; the Windows `gui.lib` is produced without them, so
   `<video>`/`<audio>` are inert there (failures fire `error`). Enabling it needs

package/doc/gui/layout.md

@@ -66,6 +66,42 @@ flex items from non-whitespace text, full `z-index` stacking contexts, and
 `float` affecting block children (only inline content wraps; a block must
 `clear`).
 
+## Transforms (M15)
+
+`transform` and `transform-origin` are a **paint-time** effect: the box model
+above is untouched (nothing reflows, no geometry is recomputed), and a second
+pass after `xt_layout_run` gives every `LayoutBox` a `Matrix2D world` — the
+transform of the whole ancestor chain — plus its `inverse`:
+
+- **Only element boxes contribute.** A text box shares its parent element's
+  `style` pointer, so letting both contribute would apply the element's list
+  twice; the pass composes an element's own list, its ancestors', and nothing
+  else.
+- **`transform-origin` is resolved here**, not in the cascade: the computed style
+  keeps the two (possibly `%`) `Length`s (default `50% 50%`) and layout resolves
+  them against the *border box*, applying `T(origin) · M · T(-origin)`. That is
+  why `computedStyle(el, "transform-origin")` still reports `50% 92%`. The
+  keywords are positional as in CSS: `top` alone is `center top`, and the
+  keyword pair may be given in either order (`bottom right` = `right bottom`).
+- **Lengths resolve against the box**: `%` in `translate()` is a share of the
+  border box's width/height, `em`/`rem` against the root font size (16px), and
+  `vw`/`vh` against the viewport.
+- **Composition order** follows CSS: the list applies right to left, so
+  `rotate(90deg) translate(10px)` moves the box *down* the screen, not right.
+
+Everything downstream follows the matrices:
+
+| Consumer | Behaviour |
+| --- | --- |
+| Paint | each op carries the matrix (see [Rendering](./rendering.md#paint-and-display-list-m4am4b)); a clipped subtree clips to the bounding box of its padding box through the matrix |
+| Hit testing | `hitTestBox` maps the point through each box's inverse before the containment test, so a rotated or scaled element is clickable where it is *drawn* |
+| `getBoundingClientRect` | the axis-aligned bounding box of the **transformed** border box (`xt_layout_transformed_bounds`) |
+| Layout geometry | unchanged — `layoutTree()` and `offsetWidth`/`offsetHeight` keep reporting the untransformed box |
+
+Unsupported transform functions (`skew`, `perspective`, …) invalidate the whole
+declaration, so a box is either correctly transformed or not transformed at all
+rather than partially applied.
+
 **Document** (`runtime/ext_gui/document.{h,cpp}`): owns the DOM tree, gathers
 `<style>` text into one stylesheet, computes styles and layout for a viewport and
 offers `querySelector`/`querySelectorAll`/`styleOf`/`boxOf`.

package/doc/gui/rendering.md

@@ -54,6 +54,21 @@ its own GPU scissor rectangle (scaled to device pixels), so painter order and
 - Geometry is uploaded only when the document or viewport changes
   (`geometry.dirty`), so steady-state frames are bind-and-draw.
 
+Each op also carries the `Matrix2D` of the box it came from
+(`runtime/ext_gui/transform.h`, `PaintRect::transform` and friends). It is
+applied while the vertex buffer is built, not in the shader: `pushRect` maps its
+four corners through the matrix (the distance-field `local`/half-extent/radius
+fields stay in the *box* frame, so a rounded corner stays round after a
+rotation), and `pushQuad`/`pushGlyph` map the glyph or image quad the same way.
+That kept the MSL/SPIR-V/DXIL shaders and the pipelines untouched — a transform
+costs a few multiplies per vertex and nothing per pixel. A clip rectangle of a
+transformed box is the bounding box of the transformed padding box, because the
+GPU scissor is axis aligned. Text is the one case that needs more than
+multiplying corners: a scaling transform would magnify an atlas raster, so the
+atlas is asked for glyphs at the device scale **times the matrix's
+magnification** (clamped to 0.5–4x, since the atlas is finite) and the quad is
+divided back into logical units, exactly the way HiDPI scaling already worked.
+
 The window background (`setBackground`) is the render-pass clear colour.
 
 Still to do in M4: gradients.

package/doc/gui.md

@@ -1,6 +1,6 @@
 # xbintsc GUI extension (self-hosted HTML/CSS renderer)
 
-Status: **M14** — features (M1–M13) are complete: HTML parsing, CSS selector
+Status: **M15** — features (M1–M14) are complete: HTML parsing, CSS selector
 matching, the cascade, computed styles and layout (block, inline, Flexbox and
 CSS positioning) are
 in place, and the engine *paints*: it builds a display list of rectangles, images
@@ -24,7 +24,13 @@ video frames go through the image texture path and audio to an SDL stream, with
 the DOM media API exposing `play`/`pause`/`currentTime`/… and media events.
 **M14** adds `<canvas>` with a self-written 2D software rasteriser (anti-aliased
 fills, paths, text and `drawImage`) uploaded through the image texture path —
-see [Canvas](./gui/canvas.md).
+see [Canvas](./gui/canvas.md). **M15** adds CSS `transform` /
+`transform-origin`: a composited `Matrix2D` per layout box that the display list
+carries into the renderer, so boxes (and the text, images and children inside
+them) can be translated, scaled and rotated without reflowing anything — and
+`transition: transform`, so those poses animate. See
+[Layout](./gui/layout.md#transforms-m15) and
+[Animation](./gui/animation.md#css-transforms-m15).
 This overview records the locked decisions, the architecture, the milestone plan
 and the current progress; the engine itself is documented by function in the
 pages above.
@@ -38,7 +44,7 @@ pages above.
 - [Media](./gui/media.md) — images, SVG, video and audio
 - [Canvas](./gui/canvas.md) — `<canvas>` and the 2D context
 - [Input](./gui/input.md) — hit testing, events and `:hover`/`:focus`
-- [Animation](./gui/animation.md) — `requestAnimationFrame` and CSS transitions
+- [Animation](./gui/animation.md) — `requestAnimationFrame`, CSS transitions and transforms
 - [Runtime integration](./gui/runtime.md) — event loop, native bridge and memory
 - [Packaging and build](./gui/build.md) — building `gui.a` and running examples
 - [Known issues and open questions](./gui/known-issues.md)
@@ -240,6 +246,16 @@ engine were Rust.
       GPU texture through the image path (`renderer_image.cpp`) and the display
       list carries a `canvas_id` (`paint.*`). See [Canvas](./gui/canvas.md);
       e2e in `tests/e2e/gui-canvas.test.ts`.
+15. **M15 — CSS `transform`** ✅
+    - `transform`/`transform-origin` parse into a `TransformOp` list
+      (`transform.{h,cpp}`, `style.*`), transition like any other paint
+      property (`document.*`), and are composed into a per-box `world` matrix
+      (plus its inverse) after layout (`layout.*`). Paint carries the matrix on
+      every op and the renderer maps quad corners through it, so the shaders are
+      untouched. Hit testing and `getBoundingClientRect` follow. See
+      [Layout](./gui/layout.md#transforms-m15) and
+      [Animation](./gui/animation.md#css-transforms-m15); e2e in
+      `tests/e2e/gui-transform.test.ts` and `tests/e2e/gui-example-svg.test.ts`.
 
 ## Progress log
 
@@ -325,4 +341,17 @@ engine were Rust.
   image texture path (`renderer_image.cpp`) and the display list carries a
   `canvas_id` (`paint.*`). See [Canvas](./gui/canvas.md); e2e in
   `tests/e2e/gui-canvas.test.ts`.
+- **M15** ✅ CSS `transform` / `transform-origin`. A new translation unit
+  (`transform.{h,cpp}`) parses `translate`/`translateX`/`translateY`/`scale`/
+  `scaleX`/`scaleY`/`rotate`/`matrix` (plus `translate3d`/`scale3d`, whose `z`
+  argument is dropped) into a `Matrix2D` list, reports them back through
+  `computedStyle`, and interpolates them for transitions (a shape or unit change
+  snaps). Layout composes a `world` matrix and its inverse per box after the
+  normal pass (`applyTransforms`), resolving `transform-origin` against the
+  border box — so layout geometry, and therefore flow, never changes. Paint
+  attaches the matrix to every shape/text/image op and the renderer maps quad
+  corners through it (no shader or uniform change), hit testing maps the point
+  through the inverse, and `getBoundingClientRect` returns the transformed AABB.
+  `examples/gui/pelican-svg` animates its artwork with it; e2e in
+  `tests/e2e/gui-transform.test.ts` and `tests/e2e/gui-example-svg.test.ts`.
 

package/doc/implemented.md

@@ -366,7 +366,7 @@ Location: `tests/` (`lexer` / `parser` / `binder` / `codegen` / `driver` / `exte
 | Value model | 64-bit NaN-boxing, uniform function ABI (including `this`), closure environments, object prototype chains |
 | Runtime | Strings / objects / arrays / typed arrays / closures / arithmetic / comparison / catchable exceptions / Promise / collections / symbols / generators / `fetch` / `console` |
 | Extensions | Extension registry, `core` (print), `node` (fs / path / os / process / buffer / stream / net / dgram / http imported by specifier) |
-| GUI (`gui` extension) | Self-hosted HTML/CSS renderer window (SDL3 + SDL_GPU): DOM/CSS/layout, `<img>`/SVG, `<video>`/`<audio>`, `<canvas>` 2D, events, transitions |
+| GUI (`gui` extension) | Self-hosted HTML/CSS renderer window (SDL3 + SDL_GPU): DOM/CSS/layout, CSS `transform`/`transform-origin`, `<img>`/SVG, `<video>`/`<audio>`, `<canvas>` 2D, events, transitions (including `transform`) |
 | Toolchain | clang compiles IR/C, linking, incremental cache |
 | Project config | `xbintsc.config.json` (`entry` / `outDir` / `optimize` / `extensions` / `app`), discovery + CLI precedence |
 | Application icon | compile-time embed (PNG/ICO/ICNS), PE resource on Windows, `.app` bundle on macOS, runtime window/Dock icon via `gui` |

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

@@ -31,8 +31,10 @@ transition 的属性时，会记录一个正在运行的 transition，并在每
 让测试可以确定性地推进。
 
 - 支持的属性：`background-color`、`color`、`border-color`、
-  `border-radius`；`transition: all` 覆盖它们。影响结构/布局的属性暂不做
-  动画（那会每帧重新布局）。
+  `border-radius` 与 `transform`；`transition: all` 覆盖它们。影响布局的
+  属性（width、position 等）仍不做动画——那会每帧重新布局——但 `transform`
+  是绘制期效果，因此为它做动画的代价只是每个被动画的盒子每帧一个矩阵
+  （见[布局](./layout.md#变换m15)）。
 - `transition` 简写与 `transition-property` / `-duration` / `-delay` /
   `-timing-function` 长写都会被解析；时间值接受 `s` 与 `ms`；缓动函数为
   `linear`、`ease`、`ease-in`、`ease-out` 与 `ease-in-out`（`ease` 是
@@ -42,5 +44,50 @@ transition 的属性时，会记录一个正在运行的 transition，并在每
 - `computedStyle()` 报告显示（已插值）的值，因此 transition 在测试中可直接
   观察。
 
+`transform` 列表按**逐项**插值（`document.cpp`、`xt_transform_interpolate`），
+这正是让常见的一对 `translateY(-4px) rotate(-0.35deg)` 与 `none` 之间平滑
+滑行而不是跳变的原因：缺失的一侧会用同类型的单位（identity）操作补齐。两个
+列表形状或单位对不上时（`rotate(10deg)` 对 `rotate(10rad)`，或函数个数不同）
+完全不做插值——transition 直接吸附到目标值，即 CSS 的离散回退，而不是一段
+看起来错误的扫过。
+
+## CSS transform（M15）
+
+`transform` 与 `transform-origin` 作为*绘制期*效果得到支持
+（`translate`/`translate3d`/`translateX`/`translateY`、
+`scale`/`scale3d`/`scaleX`/`scaleY`、`rotate`/`rotateZ`、`matrix`；`3d` 拼写的
+`z` 参数会被解析后丢弃，因为引擎是 2D 的；`deg`/`rad`/`grad`/`turn`；`%`、
+`px`、`em`、`rem`、`vw`、`vh`）。布局不受影响：几何仍是流式布局放下的位置，只有绘制结果移动，
+因此尺寸、滚动位置或兄弟节点的位置从不依赖某一动画帧。合成规则见
+[布局](./layout.md#变换m15)，如何到达 GPU 见[绘制](./rendering.md)。
+
+驱动方式有两种：
+
+```ts
+// 1. 逐帧——由帧时钟算出一个姿态。不会触发重排：字符串被解析成矩阵，
+//    显示列表在同一帧里就取用它们。
+const tick = (t: number): void => {
+  const s = t / 1000;
+  art.style.setProperty(
+    "transform",
+    "translateY(" + (Math.sin(s * 2.4) * 5).toFixed(2) + "px) " +
+      "rotate(" + (Math.sin(s * 1.15) * 1.1).toFixed(2) + "deg)",
+  );
+  win.requestAnimationFrame(tick);
+};
+```
+
+```css
+/* 2. 由状态变化驱动——和任何其他属性一样参与 transition 的 transform。 */
+#caption {
+  transform-origin: 50% 100%;
+  transition: transform 260ms ease-out;
+}
+#caption:hover { transform: translateY(-2px) scale(1.03); }
+```
+
+两种方式都由 `examples/gui/pelican-svg` 演示（逐帧摇摆 + 悬停时说明文字的
+transition），并由 `tests/e2e/gui-transform.test.ts` 固定住。
+
 动画仍需完成：`@keyframes` 动画与 `cubic-bezier(...)`。
 

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

@@ -59,7 +59,7 @@ win.on("keydown", (e) => console.log(e.key, e.code, e.ctrl, e.shift, e.alt, e.me
 ```ts
 win.computedStyle(selector, property)  // e.g. ("#main", "width") -> "60%"
 win.queryCount(selector)               // 匹配元素的数量
-win.getBoundingClientRect(selector)    // { x, y, width, height }（边框盒）
+win.getBoundingClientRect(selector)    // { x, y, width, height }（边框盒，含变换）
 win.documentTree()                     // 序列化的 DOM（调试用）
 win.layoutTree()                       // 序列化的布局盒（调试用）
 win.paintCount()                       // 显示列表中图形的数量

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

@@ -20,7 +20,12 @@ doctype 跳过，实体解码（命名 + 十进制/十六进制），空元素
 有状态的 `:hover` 与 `:focus`（见[输入](./input.md)）。值：长度
 （`px`、`%`、`em`、`rem`、`vw`、`vh`、`pt`、`pc`、`in`、`cm`、`mm`、`q`）、
 颜色（十六进制、`rgb()`/`rgba()`、一个命名子集）、数字、关键字与简写
-（`margin`/`padding`/`border`/`flex`）。
+（`margin`/`padding`/`border`/`flex`）。`transform`
+（`translate`/`translate3d`/`translateX`/`translateY`、
+`scale`/`scale3d`/`scaleX`/`scaleY`、`rotate`/`rotateZ`、`matrix`；`3d`
+拼写的 `z` 参数会被丢弃）与 `transform-origin`
+会被解析进计算样式：前者是操作列表，后者是两个（未解析的）原点长度；不支持的
+函数会让整条声明失效（见[布局](./layout.md#变换m15)）。
 
 **层叠与计算样式**（`runtime/ext_gui/style.{h,cpp}`）：一份小的内置 UA
 样式表，作者规则按 `(!important, 特异性, 源码顺序)` 排序，然后是内联

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

@@ -7,6 +7,8 @@
 
 `LayoutTree::hitTest` 返回包含某点的最深盒（先探测靠后的兄弟，使最上层元素
 胜出），`xt_dom_describe` 把元素转换为事件负载携带的 `div#id.class` 描述符。
+被变换的盒子先把点经其逆矩阵映射，因此旋转、缩放或平移过的元素恰好在它**被画
+出来**的位置被命中——`:hover` 跟着画面走，而不是跟着流式布局留下的盒子走。
 
 - SDL 指针/滚轮/键盘事件会被路由到所属窗口，进行命中测试，并投递给用 `on`
   注册的处理器。`mousedown` 还会移动焦点。

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

@@ -35,10 +35,20 @@
 
 - Linux 首发是只发布 X11、Wayland，还是两者都发布。（决定：先 X11，
   Wayland 随后。）
+- **Windows：链接命令行里不能点名 C++ 运行时。** `gui.lib` 用*静态* CRT 构建
+  （`CMAKE_MSVC_RUNTIME_LIBRARY=MultiThreaded`），引擎每个目标文件都把 `libcpmt`
+  记为默认依赖库；这既是 clang 在 Windows 上的默认，也是 xbintsc 运行时对象所用
+  的运行时（见 `scripts/build-gui.ts`）。如果再额外要求 DLL 版运行时——gui 扩展
+  过去会传 `-lmsvcprt`——同一批符号的两份定义就会冲突：`LNK2038: mismatch detected
+  for 'RuntimeLibrary'`，外加满屏 `LNK2005: already defined`，最终表现为
+  `clang: linker command failed with exit code 1169`。现在
+  `src/extensions/gui/index.ts` 只列系统库（`user32`、`gdi32`、`d3d12` 等）。
+  Windows 链接也是唯一需要 MSVC 环境的环节，请在 x64 Native Tools 命令行里构建。
 - Windows：`scripts/build-gui.ts` 会生成 MSVC 兼容的 `gui.lib`
   （COFF 对象 + `ar -M`/`llvm-ar`），但尚未在 CI 中验证，因此 Windows 步骤
-  为试验性（job 保持绿色），`package` 会跳过它。它还需要一个带 D3D12/DXIL
-  后端的 SDL3 构建（DXIL 需要 `dxc`）。
+  为试验性（job 保持绿色），`package` 会跳过它；在开发者机器上构建并运行
+  `examples/gui/pelican-svg` 与 `examples/gui/pelican-bike` 是可以的。它还需要
+  一个带 D3D12/DXIL 后端的 SDL3 构建（DXIL 需要 `dxc`）。
 - **Windows 上的媒体：** 媒体解码器（FFmpeg）只构建并合并进 POSIX 的
   `gui.a`；Windows 的 `gui.lib` 不含它们，因此那里的 `<video>`/`<audio>` 为空
   操作（失败会触发 `error`）。启用它需要 MSVC 兼容的 FFmpeg 构建，推迟到

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

@@ -54,6 +54,37 @@
 `z-index` 层叠上下文，以及 `float` 对块级子元素的影响（只有行内内容会绕排，
 块必须 `clear`）。
 
+## 变换（M15）
+
+`transform` 与 `transform-origin` 是**绘制期**效果：上面的盒模型完全不变
+（不重排、不重算几何），`xt_layout_run` 之后的一次额外遍历会给每个
+`LayoutBox` 一个 `Matrix2D world`（整条祖先链的变换）及其 `inverse`：
+
+- **只有元素盒参与。** 文本盒与其父元素共享同一个 `style` 指针，若两者都参与
+  就会把元素的列表应用两次；该遍历只合成元素自身的列表与祖先的。
+- **`transform-origin` 在这里解析**，而不是在层叠阶段：计算样式保留两个
+  （可能是 `%` 的）`Length`（默认 `50% 50%`），布局按*边框盒*解析它们，应用
+  `T(origin) · M · T(-origin)`。这就是
+  `computedStyle(el, "transform-origin")` 仍报告 `50% 92%` 的原因。关键字与
+  CSS 一样带方向：单独写 `top` 等于 `center top`，两个关键字可以任意顺序
+  （`bottom right` 等于 `right bottom`）。
+- **长度按盒子解析**：`translate()` 里的 `%` 是边框盒宽/高的比例，`em`/`rem`
+  按根字号（16px），`vw`/`vh` 按视口。
+- **合成顺序**遵循 CSS：列表从右往左应用，所以
+  `rotate(90deg) translate(10px)` 把盒子往屏幕**下方**移动，而不是往右。
+
+下游消费者都跟着矩阵走：
+
+| 消费者 | 行为 |
+| --- | --- |
+| 绘制 | 每个 op 携带矩阵（见[绘制](./rendering.md#绘制与显示列表m4am4b)）；被裁剪的子树按它的内边距盒经矩阵变换后的包围盒裁剪 |
+| 命中测试 | `hitTestBox` 先把点经每个盒的逆矩阵映射，再做包含判断，所以旋转或缩放的元素在它**被画出来**的位置可点击 |
+| `getBoundingClientRect` | **变换后**边框盒的轴对齐包围盒（`xt_layout_transformed_bounds`） |
+| 布局几何 | 不变——`layoutTree()` 与 `offsetWidth`/`offsetHeight` 仍报告未变换的盒子 |
+
+不支持的变换函数（`skew`、`perspective` 等）会让整条声明失效，因此一个盒子
+要么被正确变换、要么完全不变换，而不是只应用了一部分。
+
 **Document**（`runtime/ext_gui/document.{h,cpp}`）：持有 DOM 树，把 `<style>`
 文本汇总为一份样式表，为某个视口计算样式与布局，并提供
 `querySelector`/`querySelectorAll`/`styleOf`/`boxOf`。

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

@@ -47,6 +47,17 @@
 - 只有在文档或视口变化（`geometry.dirty`）时才上传几何数据，因此稳态帧
   只需绑定并绘制。
 
+每个 op 还携带它来自的那个盒子的 `Matrix2D`（`runtime/ext_gui/transform.h`、
+`PaintRect::transform` 等）。它在构建顶点缓冲时应用，而不是在着色器里：
+`pushRect` 把四个角经矩阵映射（距离场的 `local`/半尺寸/半径字段仍留在**盒子**
+坐标系，因此圆角旋转后依然是圆的），`pushQuad`/`pushGlyph` 同样映射字形或图像
+四边形。这样 MSL/SPIR-V/DXIL 着色器与管线都无需改动——一次变换的代价只是每个
+顶点几次乘法，与像素数无关。被变换盒子的裁剪矩形取其内边距盒经变换后的包围盒，
+因为 GPU 的 scissor 是轴对齐的。文本是唯一需要多于“乘一下四个角”的情况：
+缩放型的变换会放大图集中的位图，因此向图集请求字形时用的是设备缩放**乘以矩阵的
+放大倍率**（限制在 0.5–4 倍之间，图集容量有限），再把四边形除回逻辑单位——
+这正是 HiDPI 缩放原本就在用的做法。
+
 窗口背景（`setBackground`）是渲染通道的清除色。
 
 M4 仍需完成：渐变。

package/doc/zh-CN/gui.md

@@ -2,12 +2,17 @@
 
 > 语言 / Language：[English](../gui.md) | **简体中文**
 
-状态：**M14** —— 功能（M1–M13）已全部完成：HTML 解析、CSS 选择器匹配、层叠（cascade）、计算样式与布局（块级、行内、Flexbox 与 CSS 定位）均已就位，引擎还会**绘制**：它构建一个由矩形、图像与排版后的文本 run 组成的显示列表，并通过 SDL_GPU 渲染。输入事件会经过命中测试并投递给原生 TS 处理器，`:hover`/`:focus` 会被动态匹配，`<img>` 依据其固有尺寸确定大小并从纹理绘制——位图（PNG/JPEG/…）与 SVG 文件皆可，后者按绘制尺寸光栅化，因此矢量图保持清晰——CSS transition 会为绘制属性做动画。**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** 真正播放
+状态：**M15** —— 功能（M1–M14）已全部完成：HTML 解析、CSS 选择器匹配、层叠（cascade）、计算样式与布局（块级、行内、Flexbox 与 CSS 定位）均已就位，引擎还会**绘制**：它构建一个由矩形、图像与排版后的文本 run 组成的显示列表，并通过 SDL_GPU 渲染。输入事件会经过命中测试并投递给原生 TS 处理器，`:hover`/`:focus` 会被动态匹配，`<img>` 依据其固有尺寸确定大小并从纹理绘制——位图（PNG/JPEG/…）与 SVG 文件皆可，后者按绘制尺寸光栅化，因此矢量图保持清晰——CSS transition 会为绘制属性做动画。**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>`——一个 vendored 的最小 FFmpeg 在主线程解码，视频帧走图像
 纹理路径、音频进入 SDL 流，DOM 媒体 API 暴露 `play`/`pause`/`currentTime`/…
 与媒体事件。**M14** 增加了 `<canvas>`，配一个自研的 2D 软件光栅器（抗锯齿
 填充、路径、文本与 `drawImage`），并经图像纹理路径上传——参见
-[Canvas](./gui/canvas.md)。本总览记录了锁定决策、架构、里程碑计划与当前进度；引擎本身按功能拆分在以上各页中。
+[Canvas](./gui/canvas.md)。**M15** 增加了 CSS `transform` /
+`transform-origin`：每个布局盒一个合成好的 `Matrix2D`，由显示列表一路带到
+渲染器，因此盒子（以及其中的文本、图像与子元素）可以被平移、缩放与旋转而
+不触发任何重排——再加上 `transition: transform`，这些姿态可以动画（自绘的示例
+`examples/gui/pelican-svg` 正是用它让矢量画动起来）。参见
+[布局](./gui/layout.md#变换m15)与[动画](./gui/animation.md#css-transformm15)。本总览记录了锁定决策、架构、里程碑计划与当前进度；引擎本身按功能拆分在以上各页中。
 
 ## 目录
 
@@ -18,7 +23,7 @@
 - [媒体](./gui/media.md) —— 图像、SVG、视频与音频
 - [Canvas](./gui/canvas.md) —— `<canvas>` 与 2D 上下文
 - [输入](./gui/input.md) —— 命中测试、事件与 `:hover`/`:focus`
-- [动画](./gui/animation.md) —— `requestAnimationFrame` 与 CSS transition
+- [动画](./gui/animation.md) —— `requestAnimationFrame`、CSS transition 与 transform
 - [运行时集成](./gui/runtime.md) —— 事件循环、原生桥接与内存
 - [打包与构建](./gui/build.md) —— 构建 `gui.a` 与运行示例
 - [已知问题与待决问题](./gui/known-issues.md)
@@ -197,6 +202,15 @@ FFmpeg `7.1`（可用 `SDL3_TAG` / `FREETYPE_VERSION` / `HARFBUZZ_VERSION` /
       位图经图像路径上传为 GPU 纹理（`renderer_image.cpp`），显示列表携带
       `canvas_id`（`paint.*`）。参见 [Canvas](./gui/canvas.md)；e2e 见
       `tests/e2e/gui-canvas.test.ts`。
+15. **M15 — CSS `transform`** ✅
+    - `transform`/`transform-origin` 解析为 `TransformOp` 列表
+      （`transform.{h,cpp}`、`style.*`），和其他绘制属性一样参与 transition
+      （`document.*`），并在布局之后合成为每个盒子的 `world` 矩阵及其逆矩阵
+      （`layout.*`）。绘制把矩阵挂在每个 op 上，渲染器按矩阵映射四边形顶点，
+      因此着色器无需改动。命中测试与 `getBoundingClientRect` 同样跟随。参见
+      [布局](./gui/layout.md#变换m15)与[动画](./gui/animation.md#css-transformm15)；
+      e2e 见 `tests/e2e/gui-transform.test.ts` 与
+      `tests/e2e/gui-example-svg.test.ts`。
 
 ## 进度日志
 
@@ -273,4 +287,15 @@ FFmpeg `7.1`（可用 `SDL3_TAG` / `FREETYPE_VERSION` / `HARFBUZZ_VERSION` /
   图像纹理路径上传（`renderer_image.cpp`），显示列表携带 `canvas_id`
   （`paint.*`）。参见 [Canvas](./gui/canvas.md)；e2e 见
   `tests/e2e/gui-canvas.test.ts`。
+- **M15** ✅ CSS `transform` / `transform-origin`。新的翻译单元
+  （`transform.{h,cpp}`）把 `translate`/`translateX`/`translateY`/`scale`/
+  `scaleX`/`scaleY`/`rotate`/`matrix`（以及 `translate3d`/`scale3d`，其 `z` 参数被丢弃）
+  解析为 `Matrix2D` 列表，经 `computedStyle` 原样报告，并为 transition 插值
+  （形状或单位变化则吸附）。布局在常规遍历之后为每个盒子合成 `world` 矩阵与
+  逆矩阵（`applyTransforms`），`transform-origin` 按边框盒解析——所以布局几何
+  与流式排布永不改变。绘制把矩阵挂到每个形状/文本/图像 op 上，渲染器按矩阵
+  映射四边形顶点（不改着色器、不加 uniform）；命中测试把点经逆矩阵映射，
+  `getBoundingClientRect` 返回变换后的包围盒。`examples/gui/pelican-svg` 用它
+  为自己的画做动画；e2e 见 `tests/e2e/gui-transform.test.ts` 与
+  `tests/e2e/gui-example-svg.test.ts`。
 

package/doc/zh-CN/implemented.md

@@ -358,7 +358,7 @@ const result = build("program.ts", { emit: "exe", outDir: "build" });
 | 值模型 | 64 位 NaN-boxing、统一函数 ABI（含 `this`）、闭包环境、对象原型链 |
 | 运行时 | 字符串 / 对象 / 数组 / 类型化数组 / 闭包 / 算术 / 比较 / 可捕获异常 / Promise / 集合 / symbol / 生成器 / `fetch` / `console` |
 | 扩展 | 扩展注册表、`core`（print）、`node`（fs / path / os / process / buffer / stream / net / dgram / http，按说明符导入） |
-| GUI（`gui` 扩展） | 自托管 HTML/CSS 渲染器窗口（SDL3 + SDL_GPU）：DOM/CSS/布局、`<img>`/SVG、`<video>`/`<audio>`、`<canvas>` 2D、事件、transition |
+| GUI（`gui` 扩展） | 自托管 HTML/CSS 渲染器窗口（SDL3 + SDL_GPU）：DOM/CSS/布局、CSS `transform`/`transform-origin`、`<img>`/SVG、`<video>`/`<audio>`、`<canvas>` 2D、事件、transition（含 `transform`） |
 | 工具链 | clang 编译 IR/C、链接、增量缓存 |
 | 项目配置 | `xbintsc.config.json`（`entry` / `outDir` / `optimize` / `extensions` / `app`），支持查找与 CLI 优先级 |
 | 应用图标 | 编译期内嵌（PNG/ICO/ICNS），Windows PE 资源、macOS `.app` bundle、`gui` 运行时窗口/Dock 图标 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xbintsc",
-  "version": "0.3.79",
+  "version": "0.3.81",
   "description": "xbintsc - a TypeScript binary compiler (TypeScript -> LLVM IR -> native binary)",
   "type": "module",
   "license": "MIT",

package/runtime/ext_gui/document.cpp

@@ -119,7 +119,8 @@ void applyNumber(XtStyle *style, const std::string &property, float value) {
 
 void XtDocument::startTransitions() {
   if (display_.empty()) return;  // first style computation: nothing to animate from
-  static const char *const kProperties[] = {"background-color", "color", "border-color", "border-radius"};
+  static const char *const kProperties[] = {"background-color", "color", "border-color",
+                                           "border-radius", "transform"};
   for (auto &entry : styles_) {
     const Node *node = entry.first;
     const XtStyle &target = entry.second;
@@ -138,7 +139,18 @@ void XtDocument::startTransitions() {
         running.duration_ms = spec.duration * 1000.0f;
         running.delay_ms = spec.delay * 1000.0f;
         running.start_ms = (float)clock_ms_ + running.delay_ms;
-        if (isNumberProperty(property)) {
+        if (std::string(property) == "transform") {
+          if (xt_transform_equal(current.transform, target.transform)) continue;
+          std::vector<TransformOp> probe;
+          /* Lists of a different shape (or with clashing units) cannot be
+           * mixed; such a change snaps instead of animating. */
+          if (!xt_transform_interpolate(current.transform, target.transform, 0.5f, &probe)) {
+            continue;
+          }
+          running.is_transform = true;
+          running.from_transform = current.transform;
+          running.to_transform = target.transform;
+        } else if (isNumberProperty(property)) {
           float from = numberOf(current, property);
           float to = numberOf(target, property);
           if (from == to) continue;
@@ -184,7 +196,13 @@ void XtDocument::updateDisplay() {
     if (progress > 1.0f) progress = 1.0f;
     float eased = easeProgress(progress, transition.timing);
     XtStyle &style = node_it->second;
-    if (transition.is_color) {
+    if (transition.is_transform) {
+      std::vector<TransformOp> mixed;
+      if (xt_transform_interpolate(transition.from_transform, transition.to_transform, eased,
+                                   &mixed)) {
+        style.transform = mixed;
+      }
+    } else if (transition.is_color) {
       float rgba[4];
       for (int c = 0; c < 4; c++) rgba[c] = mix(transition.from_color[c], transition.to_color[c], eased);
       applyColor(&style, transition.property, rgba);

package/runtime/ext_gui/document.h

@@ -20,15 +20,18 @@
 
 namespace xtgui {
 
-/** A running CSS transition (only paint-affecting properties are supported). */
+/** A running CSS transition (paint-affecting properties, plus `transform`). */
 struct ActiveTransition {
   const Node *node = nullptr;
   std::string property;
   bool is_color = false;
+  bool is_transform = false;
   float from_color[4] = {0, 0, 0, 0};
   float to_color[4] = {0, 0, 0, 0};
   float from_number = 0;
   float to_number = 0;
+  std::vector<TransformOp> from_transform;
+  std::vector<TransformOp> to_transform;
   float start_ms = 0;     // when interpolation begins (after `delay`)
   float duration_ms = 0;
   float delay_ms = 0;

package/runtime/ext_gui/dom_api_node.cpp

@@ -217,11 +217,13 @@ METHOD(node_get_bounding_rect) {
   if (node == nullptr || win == nullptr || win->document == nullptr) return XT_UNDEFINED;
   const xtgui::LayoutBox *box = win->document->boxOf(node);
   if (box == nullptr) return XT_UNDEFINED;
+  /* Like the DOM: the rectangle of the *transformed* border box. */
+  xtgui::LayoutRect rect = xtgui::xt_layout_transformed_bounds(box);
   xt_value object = xt_object_new();
-  xt_object_set(object, xt_string_from_cstr("x"), xt_number(box->x));
-  xt_object_set(object, xt_string_from_cstr("y"), xt_number(box->y));
-  xt_object_set(object, xt_string_from_cstr("width"), xt_number(box->width));
-  xt_object_set(object, xt_string_from_cstr("height"), xt_number(box->height));
+  xt_object_set(object, xt_string_from_cstr("x"), xt_number(rect.x));
+  xt_object_set(object, xt_string_from_cstr("y"), xt_number(rect.y));
+  xt_object_set(object, xt_string_from_cstr("width"), xt_number(rect.width));
+  xt_object_set(object, xt_string_from_cstr("height"), xt_number(rect.height));
   return object;
 }