xbintsc 0.3.79 → 0.3.87

package/doc/DESIGN.md

@@ -41,16 +41,21 @@ xt_value fn(xt_value env, int32_t argc, xt_value *argv);
 
 `env` threads captured variables by reference through boxes, so direct calls and
 closure calls share a single code path. JavaScript semantics that are awkward to
-inline (`+` coercion, relational comparison, property access, inspection) are
-delegated to `@xt_*` runtime calls.
+inline (`+` coercion, property access, inspection) are delegated to `@xt_*`
+runtime calls. Numeric arithmetic and comparison are the exception: codegen emits
+the double fast path inline (`numeric.ts`) and calls the runtime for the coercing
+cases.
 
 ### Runtime
 
-`runtime/xt_runtime.c` implements strings, objects, arrays, closures, arithmetic,
-comparison, exceptions and Node-like `console.log` inspection. It uses a
-non-moving mark-sweep collector behind `xt_alloc` (explicit roots, subsystem
-root providers and a conservative C-stack scan), so the collector's internals
-stay isolated from the compiler.
+`runtime/` implements strings, objects, arrays, closures, arithmetic, comparison,
+exceptions and Node-like `console.log` inspection. It is split by concern into
+translation units (`xt_values.c`, `xt_containers.c`, `xt_stdlib.c`,
+`xt_builtins.c`, `xt_io.c`, `xt_alloc.c`, …), each `#include`-ing its
+implementation fragments (`.inc`) so files stay small without changing the link
+surface. It uses a non-moving mark-sweep collector behind `xt_alloc` (explicit
+roots, subsystem root providers and a conservative C-stack scan), so the
+collector's internals stay isolated from the compiler.
 
 ### Replacing llc
 
@@ -103,15 +108,18 @@ found on `PATH` (the MSVC ABI when LLVM + the Visual Studio C++ build tools are
 installed), and each manifest declares any platform-specific linker flags. See
 `examples/extensions/` and `runtime/xt_ext.h` / `runtime/xt_ext.rs`.
 
-## Self-hosting roadmap
+## Self-hosting
 
-The compiler itself is written in TypeScript and emits IR text, and `runtime` is
-already decoupled from the compiler. Later, the runtime can be rewritten in TS
-and the compiler can compile itself, gradually reaching self-hosting.
+The compiler compiles itself: `xbintsc build src/cli/main.ts --ext node` produces
+a working `xbintsc` binary, and the emitted IR is a fixpoint from the first
+generation onward. CI builds those binaries for every supported platform and
+checks the fixpoint. The runtime stays in C; rewriting it in TypeScript is an
+option for later, not a prerequisite for self-hosting.
 
 ## Tests
 
 Organised by module: `tests/lexer`, `tests/parser`, `tests/binder`,
 `tests/codegen`, `tests/driver`, `tests/extensions`, `tests/cli`, `tests/e2e`.
-When `clang` is present, e2e tests really compile and run binaries; otherwise
+When a supported clang (16+, the same version gate `build` applies) is present,
+e2e tests really compile and run binaries; otherwise
 they are skipped automatically.

package/doc/ai/cli.md

@@ -36,6 +36,8 @@ unknown command prints an error plus the help text and exits 1.
     --app-id <id>     macOS bundle identifier (e.g. com.example.demo)
     --force           Ignore the incremental cache
     --verbose         Print progress information
+    --time            Print per-phase build timings
+    --debug           Emit debug info (DWARF/CodeView) and keep frame pointers
 ```
 
 Parsing details that occasionally surprise:
@@ -46,6 +48,11 @@ Parsing details that occasionally surprise:
   `run`, or is a positional for the other commands.
 - `-o` consumes the next argument unconditionally; the other value flags leave
   the value unset when the next argument starts with `-`.
+- `-o`/`output` may name a directory that does not exist yet: the driver creates
+  the parent directories of the output path. (`--out` likewise creates its
+  directory.) Without that, an explicit path such as `-o dist/app.exe` where
+  `dist/` was missing used to fail inside the linker, since clang — not xbintsc —
+  is what writes the executable.
 
 ## Project config
 

package/doc/ai/contributing.md

@@ -38,6 +38,7 @@ it. Release tags are created by `release.yml`, never by the hook.
 | `npm run test:watch` | vitest in watch mode |
 | `npm run coverage` | V8 coverage of the TypeScript compiler (`src/`) |
 | `npm run coverage:runtime` | LLVM coverage of the C runtime (`runtime/`) |
+| `npm run bench` | build and time the fixed benchmark suite (optionally vs Node) |
 
 Unit tests live one directory per module under `tests/` (`lexer`, `parser`,
 `binder`, `codegen`, `driver`, `extensions`, `cli`, `e2e`) and mirror the source
@@ -103,7 +104,12 @@ diff scratch/ref.ll scratch/gen2.ll
   in [../../src/codegen/values.ts](../../src/codegen/values.ts) and
   [../../runtime/rt.h](../../runtime/rt.h); change both together or not at all.
 - Awkward JS semantics (`+` coercion, relational comparison, property access,
-  inspection) are delegated to `@xt_*` runtime calls rather than inlined.
+  inspection) are delegated to `@xt_*` runtime calls. Numeric arithmetic and
+  comparison are the exception: codegen inlines the two-double fast path
+  (`src/codegen/generator/numeric.ts`) and calls the runtime for everything else.
+- String literals are interned: each distinct literal is materialised once in
+  `main`, stored in a GC-rooted global, and loaded at each use. Property names
+  therefore never allocate per access.
 - The GC is a non-moving mark-sweep collector: new heap objects go through
   `xt_alloc`, and a value must be reachable from an explicit root slot, a
   registered root provider (the event loop, the microtask queue) or the

package/doc/ai/extensions.md

@@ -76,7 +76,11 @@ with elements and CSS (see `examples/gui/media.ts`). Video frames and audio PCM
 are decoded on the main thread. `<canvas>` is supported too: `getContext("2d")`
 returns a context whose fills, paths, text and `drawImage` are rasterised by a
 self-written CPU rasteriser, and element handles expose `canvas` drawing plus
-`width`/`height`. If that archive is missing for
+`width`/`height`. CSS `transform`/`transform-origin` work as paint-time
+effects, so a box (and the text, images and children in it) can be translated,
+scaled and rotated without reflowing anything — animate it per frame from
+`requestAnimationFrame` or with `transition: transform` (see
+`examples/gui/pelican-svg`). If that archive is missing for
 your platform, the build fails with an actionable message; design and roadmap
 live in [../gui.md](../gui.md) (overview; the engine is documented by function
 under [`doc/gui/`](../gui/)), and the scripting surface in

package/doc/ai/language-support.md

@@ -45,8 +45,8 @@ Canonical detail (always current, much longer):
 | Destructuring (bindings, parameters, nested) | ✅ | defaults + rest supported |
 | `delete`, `in`, `instanceof`, `typeof` | ✅ | |
 | Comma operator, `void` | ✅ | |
-| `new.target` | 🚫 | not implemented |
-| `import.meta` | 🚫 | parsed but has no value |
+| `new.target` | 🚫 | parsed, then rejected with a clear `UnsupportedFeature` |
+| `import.meta` | ✅ | `url`, `dirname`, `filename` (resolved from the executable path) |
 | `super` | ⚠️ | single-level inheritance correct; depth > 1 may be inaccurate |
 
 ## Functions, classes, objects
@@ -103,7 +103,7 @@ URI functions.
 | Missing or different | Status |
 | --- | --- |
 | `String.prototype.normalize`, `structuredClone` | 🚫 |
-| `Error.stack` capture | 🚫 (not captured) |
+| `Error.stack` capture | ⚠️ function-level frames (name/file/line), no columns; generator bodies are omitted |
 | `Object.getPrototypeOf({})` | ⚠️ returns `undefined`, not `Object.prototype` |
 | Global RegExp `lastIndex` | ⚠️ `test`/`exec` ignore it for `/g` and `/y` |
 | Sparse array holes, array out-of-bounds | ⚠️ holes are not tracked distinctly; out-of-bounds reads give `undefined` |
@@ -122,7 +122,7 @@ See section 3 of [../unimplemented.md](../unimplemented.md) for the full list.
 | `require()` / CommonJS | 🚫 | rejected with a hint to use `import` |
 | Circular dependencies | 🚫 | |
 | Live bindings | ⚠️ | imports and namespace members are snapshots |
-| `import.meta`, `__dirname`, `__filename` | 🚫 | |
+| `__dirname`, `__filename` | 🚫 | use `import.meta.dirname` / `import.meta.filename` |
 
 ## Strings, numbers, memory
 

package/doc/ai/troubleshooting.md

@@ -22,8 +22,12 @@ D:\...\build\app.ll:382:37: error: '@.str.0' defined with type '[6 x i8]*' but e
 
 The compiler emits LLVM IR that relies on opaque pointers; typed pointers were
 removed in LLVM 16 ([LLVM release notes](https://github.com/llvm/llvm-project/blob/release/15.x/llvm/docs/ReleaseNotes.rst#changes-to-the-llvm-ir)).
-Confirm with `clang --version`; if the machine has an old system clang, install a
-newer LLVM and point xbintsc at it:
+`xbintsc build`/`run` check the version up front and stop with "reports clang
+15.0.2, but xbintsc requires clang 16 or newer", and `xbintsc doctor` prints
+`status : ok` or `status : too old` (exiting non-zero in the latter case). The
+search prefers a supported clang — including the LLVM bundled with Visual Studio
+on Windows — so an old `/usr/bin/clang` is skipped when a newer one is installed.
+To choose one explicitly:
 
 ```bash
 export xbintsc_CLANG=/usr/lib/llvm-18/bin/clang     # PowerShell: $env:xbintsc_CLANG = "C:\Program Files\LLVM\bin\clang.exe"
@@ -118,6 +122,39 @@ described in [../gui.md](../gui.md).
 Windows, embedding a PE icon needs `llvm-rc` or `windres`; `doctor` reports which
 one was found, and a missing one is only fatal when an icon was requested.
 
+## Reading a stack trace
+
+`Error.stack` is captured by codegen, not from the C runtime's native frames:
+every non-generator function pushes `{name, file, line}` on entry and pops it
+before returning. Frames look like
+
+```
+Error: boom
+    at inner (app.ts:12)
+    at module (app.ts:3)
+```
+
+Lines are function declaration lines, except that the innermost frame is moved
+to the `new Error(...)` line; there are no column numbers. Generator bodies are
+not tracked because they switch stacks. A fatal native signal prints
+`xbintsc: fatal signal …` followed by the same frames, so a crash without a
+debugger still shows which JavaScript functions were running.
+
+## Debugging with gdb / lldb / WinDbg
+
+`xbintsc build app.ts --debug` emits LLVM debug metadata and passes `-g
+-fno-omit-frame-pointer` to clang, so the object carries DWARF (Linux/macOS) or
+CodeView (Windows) line tables. Function symbols keep their source names
+(`xt_fn_3_add`) and every statement has a line location:
+
+```bash
+xbintsc build app.ts --debug
+gdb ./build/app          # or: lldb ./build/app, or open the .exe in WinDbg
+```
+
+The binary is larger and is cached separately from a normal build (the debug
+flag is part of the cache key). `Error.stack` works without `--debug`.
+
 ## Build behaviour that looks wrong but is not
 
 ### The build printed `(cached)` and did nothing

package/doc/ai/zh-CN/cli.md

@@ -33,6 +33,8 @@
     --app-id <id>     macOS bundle 标识（如 com.example.demo）
     --force           忽略增量缓存
     --verbose         打印进度信息
+    --time            打印各构建阶段耗时
+    --debug           生成调试信息（DWARF/CodeView）并保留帧指针
 ```
 
 少数容易踩的解析细节：

package/doc/ai/zh-CN/contributing.md

@@ -35,6 +35,7 @@ git config core.hooksPath .githooks
 | `npm run test:watch` | vitest 监听模式 |
 | `npm run coverage` | TypeScript 编译器（`src/`）的 V8 覆盖率 |
 | `npm run coverage:runtime` | C 运行时（`runtime/`）的 LLVM 覆盖率 |
+| `npm run bench` | 构建并计时固定基准套件（可与 Node 对比） |
 
 单元测试在 `tests/` 下按模块一个目录（`lexer`、`parser`、`binder`、`codegen`、
 `driver`、`extensions`、`cli`、`e2e`），与源码树镜像对应。边界用例放在它覆盖的模块
@@ -90,8 +91,11 @@ diff scratch/ref.ll scratch/gen2.ll
 - 每个值都是一个 64 位字：double 不装箱，其余都是带标签指针（16 位标签 + 48 位载荷）。
   该表示只定义一次：[../../../src/codegen/values.ts](../../../src/codegen/values.ts) 与
   [../../../runtime/rt.h](../../../runtime/rt.h)；要改就一起改，否则别动。
-- 别扭的 JS 语义（`+` 强转、关系比较、属性访问、打印）委托给 `@xt_*` 运行时调用，而
-  不是内联。
+- 别扭的 JS 语义（`+` 强转、关系比较、属性访问、打印）委托给 `@xt_*` 运行时调用。
+  数值算术与比较是例外：codegen 内联双 double 快路径
+  （`src/codegen/generator/numeric.ts`），其余情况调用运行时。
+- 字符串字面量会被驻留：每个不同字面量只在 `main` 中创建一次，存入 GC 根全局，
+  每次使用只做一次 load；属性名因此不再逐次分配。
 - GC 是非移动标记清扫：新堆对象走 `xt_alloc`；值存活期间必须能从显式根槽、已注册的
   根提供者（事件循环、微任务队列）或 C 栈保守扫描到达。只存在于未被扫描的 C 局部
   变量里的值就是 bug。

package/doc/ai/zh-CN/extensions.md

@@ -69,7 +69,11 @@ import { createWindow, run } from "gui";
 `loadedmetadata`/`play`/`pause`/`ended`/`timeupdate`/`error` 事件可让程序驱动播放。
 没有内置控件——用元素和 CSS 自绘控件（见 `examples/gui/media.ts`）；视频帧与音频 PCM
 都在主线程解码。也支持 `<canvas>`：`getContext("2d")` 返回的上下文，其填充、路径、
-文本与 `drawImage` 由自研 CPU 光栅器处理，元素句柄还暴露 `width`/`height`。因为主体是 C++，它以各平台预编译的 `gui.a`/`gui.lib` 形式分发。如果该
+文本与 `drawImage` 由自研 CPU 光栅器处理，元素句柄还暴露 `width`/`height`。CSS
+`transform`/`transform-origin` 作为绘制期效果可用，因此一个盒子（以及其中的文本、
+图像与子元素）可以被平移、缩放与旋转而不触发任何重排——可以用
+`requestAnimationFrame` 逐帧驱动，或写成 `transition: transform`（见
+`examples/gui/pelican-svg`）。因为主体是 C++，它以各平台预编译的 `gui.a`/`gui.lib` 形式分发。如果该
 平台的归档不存在，构建会以明确的提示失败；设计与路线图见 [../../zh-CN/gui.md](../../zh-CN/gui.md)（总览；引擎按功能拆分在 [`doc/zh-CN/gui/`](../../zh-CN/gui/) 下），
 脚本接口见 [../../zh-CN/gui-scripts.md](../../zh-CN/gui-scripts.md)。媒体播放是
 Windows 唯一不支持的：Windows 的 `gui.a` 不构建 FFmpeg，媒体槽位为空操作。Canvas API

package/doc/ai/zh-CN/language-support.md

@@ -42,8 +42,8 @@ xbintsc 编译 TypeScript 的一个**实用子集**。本页用来判断你能
 | 解构（绑定、参数、嵌套） | ✅ | 支持默认值与剩余 |
 | `delete`、`in`、`instanceof`、`typeof` | ✅ | |
 | 逗号运算符、`void` | ✅ | |
-| `new.target` | 🚫 | 未实现 |
-| `import.meta` | 🚫 | 能解析，但没有值 |
+| `new.target` | 🚫 | 能解析，但会给出明确的 `UnsupportedFeature` |
+| `import.meta` | ✅ | `url`、`dirname`、`filename`（由可执行文件路径解析） |
 | `super` | ⚠️ | 单层继承正确；继承深度 > 1 可能不准 |
 
 ## 函数、类与对象
@@ -98,7 +98,7 @@ xbintsc 编译 TypeScript 的一个**实用子集**。本页用来判断你能
 | 缺失或行为不同 | 状态 |
 | --- | --- |
 | `String.prototype.normalize`、`structuredClone` | 🚫 |
-| `Error.stack` 采集 | 🚫（不采集） |
+| `Error.stack` 采集 | ⚠️ 函数级帧（名称/文件/行号），没有列号；生成器函数体不产生帧 |
 | `Object.getPrototypeOf({})` | ⚠️ 返回 `undefined`，而非 `Object.prototype` |
 | 全局 RegExp `lastIndex` | ⚠️ `/g`、`/y` 下 `test`/`exec` 忽略它 |
 | 稀疏数组空洞、数组越界 | ⚠️ 不区分空洞；越界读得 `undefined` |
@@ -117,7 +117,7 @@ xbintsc 编译 TypeScript 的一个**实用子集**。本页用来判断你能
 | `require()` / CommonJS | 🚫 | 被拒绝，并提示改用 `import` |
 | 循环依赖 | 🚫 | |
 | 实时绑定 | ⚠️ | 导入与命名空间成员都是快照 |
-| `import.meta`、`__dirname`、`__filename` | 🚫 | |
+| `__dirname`、`__filename` | 🚫 | 请使用 `import.meta.dirname` / `import.meta.filename` |
 
 ## 字符串、数字与内存
 

package/doc/ai/zh-CN/troubleshooting.md

@@ -21,8 +21,11 @@ D:\...\build\app.ll:382:37: error: '@.str.0' defined with type '[6 x i8]*' but e
 
 编译器生成的 LLVM IR 依赖不透明指针（opaque pointers），而有类型指针在 LLVM 16
 中被移除（[LLVM 发布说明](https://github.com/llvm/llvm-project/blob/release/15.x/llvm/docs/ReleaseNotes.rst#changes-to-the-llvm-ir)）。
-用 `clang --version` 确认；如果机器上的系统 clang 太旧，装一个新版 LLVM 并让 xbintsc
-用它：
+`xbintsc build`/`run` 现在会先检查版本，直接停止并提示 "reports clang 15.0.2,
+but xbintsc requires clang 16 or newer"；`xbintsc doctor` 会打印
+`status : ok` 或 `status : too old`（后者以非零码退出）。搜索工具链时会优先选择受支持
+的 clang——包括 Windows 上 Visual Studio 自带的 LLVM——所以装了新版时旧的
+`/usr/bin/clang` 会被跳过。也可以显式指定：
 
 ```powershell
 $env:xbintsc_CLANG = "C:\Program Files\LLVM\bin\clang.exe"
@@ -110,6 +113,36 @@ clang 自身失败。抛出的消息包含完整的 clang 命令与 stderr——
 `llvm-rc` 或 `windres`；`doctor` 会报告找到了哪个，只有在确实请求了图标时缺失才是
 致命错误。
 
+## 怎么看堆栈
+
+`Error.stack` 由 codegen 采集，而不是依赖 C 运行时的原生帧：每个非生成器函数
+在入口压入 `{名称, 文件, 行号}`，返回前弹出。帧形如
+
+```
+Error: boom
+    at inner (app.ts:12)
+    at module (app.ts:3)
+```
+
+行号取函数声明行；最内层帧会更新为 `new Error(...)` 所在行。没有列号；生成器
+函数体因为会切换栈而不记录。原生致命信号会先打印 `xbintsc: fatal signal …`，
+再打印同一组帧，所以即使没有调试器也能看出崩溃时正在运行哪些 JS 函数。
+
+## 用 gdb / lldb / WinDbg 调试
+
+`xbintsc build app.ts --debug` 会生成 LLVM 调试元数据，并把 `-g
+-fno-omit-frame-pointer` 传给 clang，因此目标文件带有 DWARF（Linux/macOS）或
+CodeView（Windows）行号表。函数符号保留源码名（如 `xt_fn_3_add`），每条语句都有
+对应的行位置：
+
+```bash
+xbintsc build app.ts --debug
+gdb ./build/app          # 或 lldb ./build/app，Windows 用 WinDbg 打开 .exe
+```
+
+调试版二进制更大，并且与普通构建分开缓存（debug 标志参与缓存键）。`Error.stack`
+不需要 `--debug` 也能工作。
+
 ## 看起来不对、其实正常的构建行为
 
 ### 构建打印了 `(cached)` 并什么都没做

package/doc/gui/animation.md

@@ -31,8 +31,10 @@ the engine advances the clock with real frame deltas (`XtDocument::advance`),
 and `win.advance(ms)` lets tests step it deterministically.
 
 - Supported properties: `background-color`, `color`, `border-color`,
-  `border-radius`; `transition: all` covers them. Structural/layout-affecting
-  properties are not animated yet (that would relayout every frame).
+  `border-radius` and `transform`; `transition: all` covers them. A
+  layout-affecting property (width, position, …) is still not animated — that
+  would reflow every frame — but `transform` is paint-time, so animating it costs
+  one matrix per animated box per frame ([Layout](./layout.md#transforms-m15)).
 - Both the `transition` shorthand and the `transition-property` / `-duration` /
   `-delay` / `-timing-function` longhands are parsed; time values accept `s` and
   `ms`; timing functions are `linear`, `ease`, `ease-in`, `ease-out` and
@@ -42,5 +44,54 @@ and `win.advance(ms)` lets tests step it deterministically.
 - `computedStyle()` reports the displayed (interpolated) value, so transitions
   are directly observable in tests.
 
+`transform` lists interpolate **element-wise** (`document.cpp`,
+`xt_transform_interpolate`), which is what makes the common pair
+`translateY(-4px) rotate(-0.35deg)` <-> `none` glide instead of jumping: the
+missing side is filled with identity ops of the same kind. Two lists whose shapes
+or units do not line up (`rotate(10deg)` vs `rotate(10rad)`, or a different number
+of functions) are not interpolated at all — the transition snaps to the target,
+which is CSS's discrete fallback rather than a wrong-looking sweep.
+
+## CSS transforms (M15)
+
+`transform` and `transform-origin` are supported as *paint-time* effects
+(`translate`/`translate3d`/`translateX`/`translateY`,
+`scale`/`scale3d`/`scaleX`/`scaleY`, `rotate`/`rotateZ`, `matrix`; the `3d`
+spellings' `z` argument is parsed and dropped, since the engine is 2D;
+`deg`/`rad`/`grad`/`turn`; `%`, `px`, `em`, `rem`, `vw`, `vh`). Layout
+is not affected: geometry stays where flow put it, and only the painted result
+moves, so a size, a scroll position or a sibling's position never depends on an
+animation frame. See [Layout](./layout.md#transforms-m15) for the composition
+rules and [Rendering](./rendering.md) for how it reaches the GPU.
+
+Two ways to drive one:
+
+```ts
+// 1. Per frame — a pose from the frame clock. Nothing reflows: the string is
+//    parsed into matrices and the display list picks them up in the same frame.
+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. From a state change — a transitioned transform, like any other property. */
+#caption {
+  transform-origin: 50% 100%;
+  transition: transform 260ms ease-out;
+}
+#caption:hover { transform: translateY(-2px) scale(1.03); }
+```
+
+Both are exercised by `examples/gui/pelican-svg` (per-frame sway plus a
+hover transition on the caption) and pinned by
+`tests/e2e/gui-transform.test.ts`.
+
 Still to do for animation: `@keyframes` animations and `cubic-bezier(...)`.
 

package/doc/gui/api.md

@@ -60,7 +60,7 @@ exposes read-only hooks:
 ```ts
 win.computedStyle(selector, property)  // e.g. ("#main", "width") -> "60%"
 win.queryCount(selector)               // number of matching elements
-win.getBoundingClientRect(selector)    // { x, y, width, height } (border box)
+win.getBoundingClientRect(selector)    // { x, y, width, height } (border box, transformed)
 win.documentTree()                     // serialized DOM (debugging)
 win.layoutTree()                       // serialized layout boxes (debugging)
 win.paintCount()                       // number of shapes in the display list

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`.