xbintsc 0.5.31 → 0.5.32

package/doc/zh-CN/gui.md

@@ -2,7 +2,7 @@
 
 > 语言 / Language：[English](../gui.md) | **简体中文**
 
-状态：**M16** —— 功能（M1–M15）已全部完成：HTML 解析、CSS 选择器匹配、层叠（cascade）、计算样式与布局（块级、行内、Flexbox 与 CSS 定位）均已就位，引擎还会**绘制**：它构建一个由矩形、图像与排版后的文本 run 组成的显示列表，并通过 SDL_GPU 渲染。输入事件会经过命中测试并投递给原生 TS 处理器，`:hover`/`:focus` 会被动态匹配，`<img>` 依据其固有尺寸确定大小并从纹理绘制——位图（PNG/JPEG/…）与 SVG 文件皆可，后者按绘制尺寸光栅化，因此矢量图保持清晰——CSS transition 会为绘制属性做动画。**M16** 让内联 `<svg>` 子树获得同样的处理：子树被序列化回 SVG 文档，并按绘制设备尺寸光栅化，因此图标不再需要单独的文件。**M8** 增加了交互式 DOM：具有稳定标识的元素句柄、变更操作（`appendChild`、`textContent`、`classList`、`style` 等）以及支持捕获/冒泡的元素级事件。**M9** 会提前编译 `<script>` 主体（内联与 `<script src>`）——参见 `gui-scripts.md`。**M10** 增加 `requestAnimationFrame` 以及若干 DOM 辅助方法。**M11** 增加 `position: relative`/`absolute`/`fixed` 及其偏移，`examples/gui/pelican-bike`（一个可玩的 2D 游戏）就构建在它之上。**M12** 明确了 DOM 节点生命周期（哪些变更释放、哪些保留），并让引擎内存有界：参见[节点生命周期](./gui/dom.md)与[内存与 GC](./gui/runtime.md)。**M13** 真正播放
+状态：**M19** —— 功能（M1–M15）已全部完成：HTML 解析、CSS 选择器匹配、层叠（cascade）、计算样式与布局（块级、行内、Flexbox 与 CSS 定位）均已就位，引擎还会**绘制**：它构建一个由矩形、图像与排版后的文本 run 组成的显示列表，并通过 SDL_GPU 渲染。输入事件会经过命中测试并投递给原生 TS 处理器，`:hover`/`:focus` 会被动态匹配，`<img>` 依据其固有尺寸确定大小并从纹理绘制——位图（PNG/JPEG/…）与 SVG 文件皆可，后者按绘制尺寸光栅化，因此矢量图保持清晰——CSS transition 会为绘制属性做动画。**M16** 让内联 `<svg>` 子树获得同样的处理：子树被序列化回 SVG 文档，并按绘制设备尺寸光栅化，因此图标不再需要单独的文件。**M8** 增加了交互式 DOM：具有稳定标识的元素句柄、变更操作（`appendChild`、`textContent`、`classList`、`style` 等）以及支持捕获/冒泡的元素级事件。**M9** 会提前编译 `<script>` 主体（内联与 `<script src>`）——参见 `gui-scripts.md`。**M10** 增加 `requestAnimationFrame` 以及若干 DOM 辅助方法。**M11** 增加 `position: relative`/`absolute`/`fixed` 及其偏移，`examples/gui/pelican-bike`（一个可玩的 2D 游戏）就构建在它之上。**M12** 明确了 DOM 节点生命周期（哪些变更释放、哪些保留），并让引擎内存有界：参见[节点生命周期](./gui/dom.md)与[内存与 GC](./gui/runtime.md)。**M13** 真正播放
 `<video>`/`<audio>`——可选的 `media` 扩展用 vendored 的最小 FFmpeg 在主线程解码，
 视频帧走图像纹理路径、音频进入 SDL 流，DOM 媒体 API 暴露
 `play`/`pause`/`currentTime`/… 与媒体事件。只启用 `gui` 不会链接 FFmpeg。**M14** 增加了 `<canvas>`，配一个自研的 2D 软件光栅器（抗锯齿
@@ -12,7 +12,7 @@
 渲染器，因此盒子（以及其中的文本、图像与子元素）可以被平移、缩放与旋转而
 不触发任何重排——再加上 `transition: transform`，这些姿态可以动画（自绘的示例
 `examples/gui/pelican-svg` 正是用它让矢量画动起来）。参见
-[布局](./gui/layout.md#变换m15)与[动画](./gui/animation.md#css-transformm15)。本总览记录了锁定决策、架构、里程碑计划与当前进度；引擎本身按功能拆分在以上各页中。
+[布局](./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)。本总览记录了锁定决策、架构、里程碑计划与当前进度；引擎本身按功能拆分在以上各页中。
 
 ## 目录
 
@@ -135,19 +135,24 @@ FFmpeg `7.1`（供可选的 `media` 归档使用；可用 `SDL3_TAG` /
    - **M6b — transition/动画** ✅ `transition` 简写 + 长写、对
      `background-color`/`color`/`border-color`/`border-radius` 的动画、重定向
      与 `win.advance(ms)`。`@keyframes` 仍待完成。
-7. **M7 — CI 与发布** ✅（Linux/macOS 构建） / 🚧（运行 + Windows）
+7. **M7 — CI 与发布** ✅（Linux/macOS 构建） / 🚧（运行 + Windows arm64）
    - `compile-examples` 在 Linux 与 macOS 上构建 `gui.a` 与 `media.a`（必需），
      然后在 Linux 上的 Xvfb + lavapipe 下运行示例与 `tests/e2e/gui-*.test.ts`
      （必需）。macOS 运行在确认 WindowServer 之前为试验性；它被保护起来，失败
      只记录日志而不标注运行。
-   - `package` job 在组装发布之前构建 `gui.a` 与 `media.a`，因此两者都会随现有
-     runtime 归档一起发布（`package-release` 复制整个 `runtime/`）。
-   - `vendor/`（`gui.a` 的 SDL3/FreeType/HarfBuzz，以及 `media.a` 的 FFmpeg，
+   - `package` job 在组装发布之前构建 `gui.a`/`gui.lib` 与 `media.a`/`media.lib`，
+     因此两者都会随现有 runtime 归档一起发布（`package-release` 复制整个
+     `runtime/`）。Windows x64 已包含；Windows arm64 仍跳过。
+   - `vendor/`（GUI 归档的 SDL3/FreeType/HarfBuzz，以及 `media` 的 FFmpeg，
      缓慢的部分）按 OS/arch 缓存，以 `scripts/build-gui.ts` /
-     `scripts/build-media.ts` 为键。
-   - Windows（构建 + 运行）在 CI 中保持试验性：MSVC 兼容的 `gui.lib` 可在本机
-     通过 SDL_GPU 的 Vulkan 后端构建并运行，但托管 runner 没有 GPU/Vulkan
-     驱动。失败只记录日志而不标注运行（见[待决问题](./gui/known-issues.md)）。
+     `scripts/build-media.ts` 为键。Windows x64 有独立的源码 + FFmpeg 安装前缀
+     缓存。
+   - Windows x64 在 CI 中构建两个归档并链接一个 `gui,media` 程序；托管 runner
+     没有 GPU/Vulkan 驱动，因此 GUI/媒体示例的*运行*仍为试验性（失败只记录
+     日志而不标注运行）。Windows arm64 仍跳过两个归档（见
+     [待决问题](./gui/known-issues.md)）。CI 通过
+     `.github/actions/vs-toolchain` → `scripts/setup-vs-toolchain.ps1` 使用与
+     本地构建相同的 Visual Studio MSVC + 自带 LLVM 工具链。
 8. **M8 — 交互式 DOM** ✅
    - 具有稳定标识的元素/文档句柄、通过运行时访问器读写属性、遍历/特性/查询、
      带有延迟重算样式/重新布局的变更
@@ -225,6 +230,47 @@ FFmpeg `7.1`（供可选的 `media` 归档使用；可用 `SDL3_TAG` /
       通过与 SVG 文件相同的 NanoSVG 缓存（`svg.{h,cpp}`）解析并光栅化；markup
       缓存有界，DOM 变更会在下一次布局时重新序列化。e2e 见
       `tests/e2e/gui-inline-svg.test.ts`。
+17. **M17 — WebGL** ✅
+    - `canvas.getContext("webgl")` 创建真正的 GPU 上下文（`webgl.{h,cpp}`）：
+      一张离屏 RGBA8 颜色纹理加一张深度纹理、自己的 SDL_GPU 命令缓冲，并根据
+      程序、顶点布局与固定功能状态惰性创建管线。页面通过既有图像路径直接合成
+      颜色纹理，不需要 CPU 读回。
+    - `webgl_glsl*.cpp` 把 GLSL ES 1.00/3.00 改写为 Vulkan GLSL ES 3.10
+      （属性/`varying` 位置、`gl_FragColor`、`texture2D`、每阶段一个 std140
+      uniform 块、显式采样器绑定），用静态打包的 glslang 编译，反射 SPIR-V
+      得到 uniform 偏移，并在 Metal 上用内置 SPIRV-Cross（`webgl_msl.cpp`）
+      把同一份模块交叉编译为 MSL。
+    - `dom_api_webgl*.cpp` 暴露 WebGL 1.0 接口，包括纹理、mipmap、
+      渲染到纹理的 framebuffer 与 `readPixels`。见 [WebGL](./gui/webgl.md)；
+      e2e 见 `tests/e2e/gui-webgl.test.ts` 与
+      `tests/e2e/gui-example-webgl.test.ts`，示例见 `examples/gui/webgl-cube`。
+18. **M18 — WebGL 2** ✅
+    - `canvas.getContext("webgl2")` 返回的上下文原型继承 WebGL 1 原型，并带有
+      WebGL 2 常量与方法。
+    - GLSL ES 3.00 源码（`#version 300 es`、`in`/`out`、命名片元输出、
+      `gl_InstanceID`）走同一个改写器编译。
+    - 顶点数组对象保存/恢复属性表，实例化绘制使用 SDL 的按实例输入频率，采样器
+      对象覆盖纹理单元的过滤/环绕状态。`texStorage2D`、`copyBufferSubData`、
+      `getBufferSubData` 与 `clearBuffer*` 已实现；查询/栅栏/UBO 与 transform
+      feedback 入口存在并优雅降级。见 [WebGL](./gui/webgl.md)；e2e 见
+      `tests/e2e/gui-webgl2.test.ts` 与 `tests/e2e/gui-example-webgl2.test.ts`，
+      示例见 `examples/gui/webgl2-cubes`。
+19. **M19 — 装饰性 CSS** ✅
+    - `@media` 块递归解析，并按视口求值（宽高范围、朝向、hover/pointer 与偏好
+      特性）；`matchMedia()` 使用同一个求值器。
+    - 生成内容：`::before`/`::after` 选择器、继承的伪样式、`content` 字符串/
+      转义/`attr()`，以及不会泄漏到 DOM 遍历的合成布局盒。
+    - 多层 `background-image` 的线性与径向渐变，自下而上按纯色带绘制
+      （线性 18 条、径向 32 个同心椭圆）。
+    - `text-shadow` 作为阴影文本 run，并带九次采样模糊近似。
+    - `clip-path` 多边形（`inset`/`circle`/`ellipse`/`polygon`）解析到设备空间，
+      用耳切法三角化，并在 `renderer_clip.cpp` 中与图形几何求交——不需要模板/
+      shader 改动。
+    - `filter` 颜色函数、九次采样 `blur()` 与轮廓 `drop-shadow()`；
+      `backdrop-filter` 会解析并参与层叠，但需要离屏背景通道（见
+      [已知问题](./gui/known-issues.md)）。
+    - e2e 覆盖见 `tests/e2e/gui-effects.test.ts`；参见
+      [绘制](./gui/rendering.md#背景生成内容与特效m19)。
 
 ## 进度日志
 
@@ -252,10 +298,13 @@ FFmpeg `7.1`（供可选的 `media` 归档使用；可用 `SDL3_TAG` /
   按绘制设备像素尺寸光栅化并按该尺寸缓存，因此缩放与 HiDPI 保持清晰。
 - **M6b** ✅ CSS transition（在 `style.*` 中解析、在 `document.*` 中维护动画
   时钟与 transition 状态、`advance`/`advance(ms)` 钩子、e2e 覆盖）。
-- **M7** ✅ 在 CI 中于 Linux 与 macOS 上构建 `gui.a`（以及可选的 `media.a`，
-  必需），并在 Linux 的 Xvfb 下运行示例与 GUI e2e 套件；`package` 发布两个归档，
-  `vendor/` 被缓存，`ar -M` 合并在 GNU/Linux 与 macOS 上可用。macOS 运行与所有
-  Windows 在 CI 中仍为试验性。
+- **M7** ✅ 在 CI 中于 Linux、macOS 与 Windows x64 上构建 `gui.a`/`gui.lib` 与
+  `media.a`/`media.lib`（必需），并在 Linux 的 Xvfb 下运行示例与 GUI e2e 套件；
+  `package` 发布这些归档（Windows x64 已包含），`vendor/` 被缓存，`ar -M` 合并
+  在 GNU/Linux、macOS 与 COFF/Windows 上可用。macOS 运行、Windows 示例的*运行*
+  以及 Windows arm64 在 CI 中仍为试验性。Windows job 通过
+  `.github/actions/vs-toolchain` 使用与本地构建相同的 Visual Studio MSVC +
+  自带 LLVM 工具链。
 - **M8** ✅ 元素/文档句柄（`dom_api.*`）、带延迟重算样式/重新布局的 DOM 变更
   （`document.*`、`xt_gui_flush_dom`）、带捕获/冒泡与 `stopPropagation` 的
   元素事件分发（`dom_api.*`、`gui.cpp`），以及
@@ -325,4 +374,30 @@ FFmpeg `7.1`（供可选的 `media` 归档使用；可用 `SDL3_TAG` /
   markup 采用有界 LRU）按绘制设备像素尺寸光栅化。`win.inlineSvg` 诊断钩子
   暴露序列化文档，`tests/e2e/gui-inline-svg.test.ts` 固定了尺寸、命中测试、
   渐变、CSS 盒样式与 DOM 变更。
+- **M17** ✅ WebGL。`xtgui::WebGLContext`（`webgl.{h,cpp}`）拥有离屏颜色/深度
+  目标与命令缓冲，`webgl_buffer/texture/draw/shader` 实现 GL 对象模型，
+  `webgl_glsl*.cpp` 用内置 glslang 把 GLSL ES 翻译为 SPIR-V
+  （`webgl_msl.cpp`/SPIRV-Cross 在 Metal 上把该模块转成 MSL），
+  `dom_api_webgl*.cpp` 绑定 WebGL 1.0 接口。`renderer_image.cpp` 按 canvas id
+  返回上下文的颜色纹理，页面直接合成 GPU 输出。示例
+  `examples/gui/webgl-cube`；e2e 见 `tests/e2e/gui-webgl.test.ts` 与
+  `tests/e2e/gui-example-webgl.test.ts`。
+- **M18** ✅ WebGL 2。`webgl2_proto()` 在 WebGL 1 原型上增加 WebGL 2 常量与
+  方法；`webgl_webgl2.cpp` 实现顶点数组对象与采样器/查询/栅栏句柄，
+  `webgl_draw.cpp` 增加实例化绘制（由 `vertexAttribDivisor` 决定输入频率）与
+  整数属性，`webgl_texture.cpp` 增加 `texStorage2D` 与 `clearBuffer*`。着色器
+  改写器为 `#version 300 es` 输出分配连续 location，块反射会把结构体字段展开
+  成 three.js 灯光可寻址的成员。three.js r160 已在真实渲染器上跑通基础/标准/
+  Phong 材质、纹理、灯光、雾、精灵、线段、点与实例化；Canvas2D 回退已删除。
+  示例 `examples/gui/webgl2-cubes`（64 个立方体，一次实例化绘制）；e2e 见
+  `tests/e2e/gui-webgl2.test.ts` 与 `tests/e2e/gui-example-webgl2.test.ts`。
+- **M19** ✅ 装饰性 CSS。`css_sheet.cpp` 解析嵌套 `@media` 块，
+  `media_query.cpp` 按视口求值（`matchMedia` 也用它）；`css_selector.cpp`
+  识别 `::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 见
+  `tests/e2e/gui-effects.test.ts`。
 

package/doc/zh-CN/npm-package.md

@@ -58,8 +58,9 @@ TypeScript 编译器。
 - 预编译的运行时归档（`runtime/lib/<os>-<arch>/core.a`）。驱动会在首次使用时
   从随包发布的源码编译 C 运行时并缓存目标文件，所以第一次构建会更慢
   （见[首次构建与缓存](#首次构建与缓存)）；
-- GUI/media 的原生归档（`gui.a`、`media.a`）。如果你需要 `--ext gui` 或
-  `--ext media`，请使用 Linux/macOS 的发布压缩包，或从源码检出中构建这些归档。
+- GUI/media 的原生归档（`gui.a`/`gui.lib`、`media.a`/`media.lib`）。如果你需要
+  `--ext gui` 或 `--ext media`，请使用 Linux/macOS/Windows x64 的发布压缩包，
+  或从源码检出中构建这些归档。
 
 ## 环境要求
 
@@ -339,8 +340,10 @@ jobs:
   目标文件名是内容哈希，因此旧缓存不会污染新构建。
 - xbintsc 只为**宿主**平台构建，不是交叉编译器：要给多个平台产出产物，请使用
   CI matrix（每个 OS/arch 一个 job）。
-- macOS runner 已经带有 Xcode Command Line Tools；Windows runner 需要安装 LLVM
-  与 MSVC 生成工具，产物是 `build\main.exe`。
+- macOS runner 已经带有 Xcode Command Line Tools；Windows runner 需要安装
+  Visual Studio C++ 生成工具（MSVC + 自带的 LLVM），产物是 `build\main.exe`。
+  在源码检出中可运行 `pwsh -File scripts/setup-vs-toolchain.ps1` 显式导入该
+  工具链。
 
 ## npm 包还是发布压缩包？
 
@@ -348,7 +351,7 @@ jobs:
 | --- | --- | --- |
 | 需要 Node.js | 是，22+ | 否 |
 | 首次构建 | 从源码编译 C 运行时 | 直接链接预编译运行时 |
-| GUI / media 扩展 | 不包含 | Linux/macOS 压缩包包含 |
+| GUI / media 扩展 | 不包含 | Linux/macOS 与 Windows x64 压缩包包含 |
 | 安装方式 | `npm install` + lockfile / provenance | 下载、校验 `.sha256`、解压 |
 | 编程 API | 有 | 无（仅 CLI） |
 | 交叉编译 | 否——只构建宿主平台 | 否——只构建宿主平台 |
@@ -383,7 +386,7 @@ jobs:
 | 第一次构建很慢 | 正常：正在编译并缓存运行时 C 源码。后续构建会复用 `.xbintsc/`；`--time` 可确认。如果冷启动必须快，请使用发布压缩包。 |
 | 写 `.xbintsc/` 权限错误 | 用 `xbintsc_CACHE_DIR` 指向可写目录，或在可写目录中运行。 |
 | `module 'fs' is provided by the 'node' extension` | 加 `--ext node`，或在配置里写 `"extensions": ["node"]`。 |
-| `GUI native library not found` / `media native library not found` | npm 包不包含 `gui.a`/`media.a`；请使用 Linux/macOS 发布压缩包，或从源码检出构建。 |
+| `GUI native library not found` / `media native library not found` | npm 包不包含 `gui.a`/`gui.lib` 或 `media.a`/`media.lib`；请使用 Linux/macOS/Windows x64 发布压缩包，或从源码检出构建。 |
 | `require("xbintsc")` 失败 | 包只提供 ESM；使用 `import`（或动态 `import()`）。 |
 | Windows 链接时报缺少 MSVC 库 | 在 Native Tools 命令提示符中运行，安装 VS C++ 生成工具，并检查 `npx xbintsc doctor`。 |
 | `npm ci --omit=dev` 后构建找不到 `xbintsc` | 在构建阶段安装 devDependencies，或把 `xbintsc` 移到 `dependencies`。 |

package/doc/zh-CN/requirements.md

@@ -116,19 +116,21 @@ sudo apk add clang lld                   # Alpine
 用 `clang --version` 验证。如果 xbintsc 用错了链接器，可用 `xbintsc_CLANG` 指定
 clang，并通过 `xbintsc_LINKER_ARGS` 追加参数（例如 `-fuse-ld=lld`）。
 
-## Windows —— 安装 MSVC C++ 生成工具（与 LLVM）
+## Windows —— 安装 MSVC C++ 生成工具（含 LLVM）
 
-Windows 上的 xbintsc 面向 **MSVC ABI**。用 `winget` 安装 Visual Studio C++
-生成工具和 LLVM：
+Windows 上的 xbintsc 面向 **MSVC ABI**。一条 `winget` 命令即可安装 Visual
+Studio C++ 工作负载、MSBuild，以及本地构建脚本与 CI 使用的 Clang 组件：
 
 ```powershell
-winget install -e --id LLVM.LLVM
 winget install -e --id Microsoft.VisualStudio.2022.BuildTools `
-  --override "--quiet --wait --add Microsoft.VisualStudio.Workload.VCTools --includeRecommended"
+  --override "--quiet --wait --add Microsoft.VisualStudio.Workload.VCTools --add Microsoft.VisualStudio.Component.VC.Llvm.Clang --includeRecommended"
 ```
 
 Visual Studio 2022 自带的 LLVM（`VC\Tools\Llvm\x64\bin\clang.exe`，当前版本
-19.1.5）已经够用，独立安装的 LLVM 也可以。但编译器必须以 MSVC ABI 为目标
+19.1.5）就是 `scripts/setup-vs-toolchain.ps1` 选择的工具链。独立安装的 LLVM
+（`winget install -e --id LLVM.LLVM`）对 `xbintsc` 本身也可用，但 GUI/媒体
+归档构建与 CI 都使用 Visual Studio 这一套，从而让运行时、预编译归档与最终
+二进制出自同一条工具链。无论哪种，编译器必须以 MSVC ABI 为目标
 （`Target: *-windows-msvc`）：面向其他 Windows ABI 的 clang 无法与 MSVC
 运行库链接，`xbintsc` 会直接给出明确错误并拒绝使用。
 
@@ -141,6 +143,10 @@ Visual Studio 2022 自带的 LLVM（`VC\Tools\Llvm\x64\bin\clang.exe`，当前
 & "$env:ProgramFiles\Microsoft Visual Studio\2022\BuildTools\VC\Auxiliary\Build\vcvarsall.bat" x64
 ```
 
+在源码检出中，`pwsh -File scripts/setup-vs-toolchain.ps1` 会完成同样的导入，
+并把 `xbintsc_CLANG` 指向该 Visual Studio 安装自带的 LLVM。CI 调用的是同一个
+脚本，因此本地构建、发布归档与 CI 共用一条 Visual Studio 工具链。
+
 用 `xbintsc doctor`（或 `clang --version`）验证；输出会列出解析到的编译器、
 版本与目标。
 

package/llms.txt

@@ -75,6 +75,8 @@
   - [doc/gui/input.md](https://raw.githubusercontent.com/zy445566/xbintsc/main/doc/gui/input.md): hit testing, events and `:hover`/`:focus`
   - [doc/gui/animation.md](https://raw.githubusercontent.com/zy445566/xbintsc/main/doc/gui/animation.md): `requestAnimationFrame` and CSS transitions
   - [doc/gui/runtime.md](https://raw.githubusercontent.com/zy445566/xbintsc/main/doc/gui/runtime.md): event loop integration, the native bridge and memory
+  - [doc/gui/canvas.md](https://raw.githubusercontent.com/zy445566/xbintsc/main/doc/gui/canvas.md): `<canvas>` and the 2D context
+  - [doc/gui/webgl.md](https://raw.githubusercontent.com/zy445566/xbintsc/main/doc/gui/webgl.md): WebGL 1.0 on the GPU — GLSL ES to SPIR-V, textures, framebuffers and readback
   - [doc/gui/build.md](https://raw.githubusercontent.com/zy445566/xbintsc/main/doc/gui/build.md): building `gui.a` and running the examples
   - [doc/gui/known-issues.md](https://raw.githubusercontent.com/zy445566/xbintsc/main/doc/gui/known-issues.md): known issues and open questions
 - [doc/gui-scripts.md](https://raw.githubusercontent.com/zy445566/xbintsc/main/doc/gui-scripts.md): the GUI scripting surface

package/package.json

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

package/runtime/ext_gui/browser.cpp

@@ -156,15 +156,25 @@ xt_value win_location_get(xt_value self, xt_value env, int32_t argc, xt_value *a
   return g_location;
 }
 
-/** `matchMedia(query)` -> a MediaQueryList-shaped object. The engine has no
- * media queries of its own; a coarse-pointer probe is always false because a
- * window is driven by a mouse and a keyboard. */
+xt_value media_list_build(const std::string &query, bool matches);
+
+/** `matchMedia(query)` -> a MediaQueryList-shaped object evaluated against the
+ * current window's viewport, using the same evaluator as `@media` rules. The
+ * list is a snapshot (there is no live change event), which matches the
+ * engine's restyle-on-resize model. */
 xt_value win_match_media(xt_value self, xt_value env, int32_t argc, xt_value *argv) {
-  (void)self;
   (void)env;
-  (void)argc;
-  (void)argv;
-  return g_media_list;
+  std::string query;
+  if (argc >= 1) query = cstr(xt_arg(argc, argv, 0));
+  XtGuiWindow *win = xt_gui_window_from_this(self);
+  if (win == NULL) {
+    xt_value handle = xt_gui_ensure_window();
+    win = xt_gui_window_from_this(handle);
+  }
+  float width = 0.0f;
+  float height = 0.0f;
+  if (win != NULL) xt_gui_window_viewport(win, &width, &height);
+  return media_list_build(query, xtgui::xt_css_media_matches(query, width, height));
 }
 
 /** `getComputedStyle(el)`: the engine exposes the element's style handle, which
@@ -243,10 +253,10 @@ xt_value location_build(void) {
   return location;
 }
 
-xt_value media_list_build(void) {
+xt_value media_list_build(const std::string &query, bool matches) {
   xt_value list = xt_object_new();
-  set_prop(list, "media", string_of(""));
-  set_prop(list, "matches", XT_FALSE);
+  set_prop(list, "media", xt_string_from_cstr(query.c_str()));
+  set_prop(list, "matches", matches ? XT_TRUE : XT_FALSE);
   set_method(list, "addListener", (void *)noop);
   set_method(list, "removeListener", (void *)noop);
   set_method(list, "addEventListener", (void *)noop);
@@ -332,6 +342,21 @@ xt_value type_proto(const std::string &name) {
     return domapi::event_proto();
   }
   if (name == "AudioContext" || name == "webkitAudioContext") return xt_gui_audio_proto();
+  if (name == "WebGLRenderingContext") return domapi::webgl_proto();
+  if (name == "WebGL2RenderingContext") return domapi::webgl2_proto();
+  if (name == "WebGLBuffer") return domapi::webgl_object_proto("buffer");
+  if (name == "WebGLTexture") return domapi::webgl_object_proto("texture");
+  if (name == "WebGLShader") return domapi::webgl_object_proto("shader");
+  if (name == "WebGLProgram") return domapi::webgl_object_proto("program");
+  if (name == "WebGLFramebuffer") return domapi::webgl_object_proto("framebuffer");
+  if (name == "WebGLRenderbuffer") return domapi::webgl_object_proto("renderbuffer");
+  if (name == "WebGLUniformLocation") return domapi::webgl_object_proto("uniform");
+  if (name == "WebGLActiveInfo") return domapi::webgl_object_proto("info");
+  if (name == "WebGLVertexArrayObject") return domapi::webgl_object_proto("vertexarray");
+  if (name == "WebGLSampler") return domapi::webgl_object_proto("sampler");
+  if (name == "WebGLQuery") return domapi::webgl_object_proto("query");
+  if (name == "WebGLSync") return domapi::webgl_object_proto("sync");
+  if (name == "WebGLTransformFeedback") return domapi::webgl_object_proto("transformfeedback");
   return domapi::node_proto();
 }
 
@@ -382,6 +407,8 @@ void install_window_globals(xt_value win) {
   set_prop(win, "Audio", type_value("Audio"));
   set_prop(win, "Event", type_value("Event"));
   set_prop(win, "CustomEvent", type_value("CustomEvent"));
+  set_prop(win, "WebGLRenderingContext", type_value("WebGLRenderingContext"));
+  set_prop(win, "WebGL2RenderingContext", type_value("WebGL2RenderingContext"));
   set_prop(win, "isSecureContext", XT_TRUE);
   set_number(win, "screenX", 0);
   set_number(win, "screenY", 0);
@@ -402,7 +429,7 @@ void ensure_singletons(void) {
     xt_gc_add_root(&g_location);
   }
   if (!XT_IS_OBJECT(g_media_list)) {
-    g_media_list = media_list_build();
+    g_media_list = media_list_build("", false);
     xt_gc_add_root(&g_media_list);
   }
 }
@@ -500,8 +527,7 @@ xt_value xt_browser_type(int32_t argc, xt_value *argv) {
   (void)argv;
   if (argc < 1) return XT_UNDEFINED;
   std::string name = cstr(xt_arg(argc, argv, 0));
-  if (name == "WebGLRenderingContext" || name == "WebGL2RenderingContext" ||
-      name == "XRWebGLLayer" || name == "XRWebGLBinding" || name == "OffscreenCanvas" ||
+  if (name == "XRWebGLLayer" || name == "XRWebGLBinding" || name == "OffscreenCanvas" ||
       name == "ImageBitmap" || name == "ImageData" || name == "Response" ||
       name == "ReadableStream" || name == "Request" || name == "Headers" ||
       name == "DOMParser") {

package/runtime/ext_gui/canvas.cpp

@@ -457,24 +457,9 @@ void Canvas2D::draw_image(const Image &source, float dx, float dy, float dw, flo
     canvas_detail::draw_image(image_.pixels, image_.width, image_.height, source, x0, y0, x1 - x0,
                               y1 - y0, sx, sy, sw, sh, state_.global_alpha);
   } else {
-    float cornersX[4], cornersY[4];
-    const float corners[4][2] = {
-        {dx, dy}, {dx + dw, dy}, {dx + dw, dy + dh}, {dx, dy + dh}};
-    float minX = 0.0f, minY = 0.0f, maxX = 0.0f, maxY = 0.0f;
-    for (int i = 0; i < 4; i++) {
-      to_device(corners[i][0], corners[i][1], &cornersX[i], &cornersY[i]);
-      if (i == 0) {
-        minX = maxX = cornersX[i];
-        minY = maxY = cornersY[i];
-      } else {
-        minX = std::min(minX, cornersX[i]);
-        maxX = std::max(maxX, cornersX[i]);
-        minY = std::min(minY, cornersY[i]);
-        maxY = std::max(maxY, cornersY[i]);
-      }
-    }
-    canvas_detail::draw_image(image_.pixels, image_.width, image_.height, source, minX, minY,
-                              maxX - minX, maxY - minY, sx, sy, sw, sh, state_.global_alpha);
+    canvas_detail::draw_image_affine(image_.pixels, image_.width, image_.height, source, dx, dy,
+                                     dw, dh, sx, sy, sw, sh, state_.transform,
+                                     state_.global_alpha);
   }
   generation_++;
 }

package/runtime/ext_gui/canvas_internal.h

@@ -48,6 +48,16 @@ void draw_image(std::vector<unsigned char> &pixels, int width, int height, const
                 float dx, float dy, float dw, float dh, float sx, float sy, float sw, float sh,
                 float alpha);
 
+/** Blit an RGBA8 source through a full affine transform. The destination
+ * rectangle is mapped to a parallelogram by `transform`; each device pixel is
+ * inverse-mapped and sampled from the source rectangle. This is the path that
+ * makes rotated/skewed `drawImage` (and perspective-grid canvas textures) draw
+ * the image instead of squashing it into the bounding box. */
+void draw_image_affine(std::vector<unsigned char> &pixels, int width, int height,
+                       const Image &source, float dx, float dy, float dw, float dh, float sx,
+                       float sy, float sw, float sh, const CanvasTransform &transform,
+                       float alpha);
+
 /** Composite one grayscale glyph bitmap at `(x, baselineY)` with `paint`. */
 void blit_glyph(std::vector<unsigned char> &pixels, int width, int height,
                 const std::vector<unsigned char> &glyph, int glyphWidth, int glyphHeight, int left,

package/runtime/ext_gui/canvas_raster.cpp

@@ -269,6 +269,66 @@ void draw_image(std::vector<unsigned char> &pixels, int width, int height, const
   }
 }
 
+
+void draw_image_affine(std::vector<unsigned char> &pixels, int width, int height,
+                       const Image &source, float dx, float dy, float dw, float dh, float sx,
+                       float sy, float sw, float sh, const CanvasTransform &transform,
+                       float alpha) {
+  if (source.width <= 0 || source.height <= 0 || dw <= 0.0f || dh <= 0.0f || sw <= 0.0f ||
+      sh <= 0.0f)
+    return;
+  CanvasTransform inverse = transform.inverted();
+  float cornersX[4];
+  float cornersY[4];
+  const float corners[4][2] = {{dx, dy}, {dx + dw, dy}, {dx + dw, dy + dh}, {dx, dy + dh}};
+  float minX = 0.0f, minY = 0.0f, maxX = 0.0f, maxY = 0.0f;
+  for (int i = 0; i < 4; i++) {
+    transform.apply(corners[i][0], corners[i][1], &cornersX[i], &cornersY[i]);
+    if (i == 0) {
+      minX = maxX = cornersX[i];
+      minY = maxY = cornersY[i];
+    } else {
+      minX = std::min(minX, cornersX[i]);
+      maxX = std::max(maxX, cornersX[i]);
+      minY = std::min(minY, cornersY[i]);
+      maxY = std::max(maxY, cornersY[i]);
+    }
+  }
+  int ix0 = std::max(0, (int)std::floor(minX));
+  int ix1 = std::min(width, (int)std::ceil(maxX));
+  int iy0 = std::max(0, (int)std::floor(minY));
+  int iy1 = std::min(height, (int)std::ceil(maxY));
+  for (int py = iy0; py < iy1; py++) {
+    for (int px = ix0; px < ix1; px++) {
+      float ux = 0.0f;
+      float uy = 0.0f;
+      inverse.apply((float)px + 0.5f, (float)py + 0.5f, &ux, &uy);
+      float u = (ux - dx) / dw;
+      float v = (uy - dy) / dh;
+      if (u < 0.0f || u >= 1.0f || v < 0.0f || v >= 1.0f) continue;
+      int sxi = (int)(sx + u * sw);
+      int syi = (int)(sy + v * sh);
+      if (sxi < 0) sxi = 0;
+      if (syi < 0) syi = 0;
+      if (sxi >= source.width) sxi = source.width - 1;
+      if (syi >= source.height) syi = source.height - 1;
+      const unsigned char *texel =
+          source.pixels.data() + ((size_t)syi * (size_t)source.width + (size_t)sxi) * 4;
+      unsigned char *dst = pixels.data() + ((size_t)py * (size_t)width + (size_t)px) * 4;
+      if (alpha >= 0.999f) {
+        const unsigned char ta = texel[3];
+        if (ta == 255) {
+          dst[0] = texel[0]; dst[1] = texel[1]; dst[2] = texel[2]; dst[3] = 255;
+          continue;
+        }
+        if (ta == 0) continue;
+      }
+      float color[4] = {texel[0] / 255.0f, texel[1] / 255.0f, texel[2] / 255.0f, texel[3] / 255.0f};
+      blend_pixel(dst, color, 1.0f, alpha);
+    }
+  }
+}
+
 void blit_glyph(std::vector<unsigned char> &pixels, int width, int height,
                 const std::vector<unsigned char> &glyph, int glyphWidth, int glyphHeight, int left,
                 int top, float x, float baselineY, const CanvasPaint &paint, float alpha) {