xbintsc 0.3.49 → 0.3.61

package/doc/gui.md

@@ -1,7 +1,8 @@
 # xbintsc GUI extension (self-hosted HTML/CSS renderer)
 
-Status: **M10** — features (M1–M10) are complete: HTML parsing, CSS selector
-matching, the cascade, computed styles and layout (block, inline and Flexbox) are
+Status: **M11** — features (M1–M11) 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
 and shaped text runs and renders them through SDL_GPU. Input events are hit
 tested and delivered to native TS handlers, `:hover`/`:focus` are matched
@@ -11,6 +12,8 @@ DOM: element handles with stable identity, mutation (`appendChild`, `textContent
 `classList`, `style`, …) and element-level events with capture/bubbling.
 **M9** compiles `<script>` bodies ahead of time (inline and `<script src>`) — see
 `doc/gui-scripts.md`. **M10** adds `requestAnimationFrame` plus a few DOM helpers.
+**M11** adds `position: relative`/`absolute`/`fixed` with their offsets, which is
+what `examples/gui/pelican-bike` — a playable 2D game — is built on.
 This document records the locked decisions, the architecture, the milestone plan
 and the current progress of a cross-platform GUI extension that renders an
 HTML/CSS UI with its own GPU-accelerated engine.
@@ -111,10 +114,17 @@ run();                                 // drives the main loop until all windows
 ```
 
 Methods implemented on a window handle: `setTitle` / `setSize` / `loadHTML` /
-`getHTML` / `setBackground` / `close` / `isOpen` / `on` / `off`. Events emitted:
+`getHTML` / `setBackground` / `close` / `isOpen` / `on` / `off`, plus `driver()`,
+which reports the SDL_GPU backend in use (`"vulkan"`, `"direct3d12"`, `"metal"`,
+… — SDL picks the best one the device supports). Events emitted:
 `ready` (after the first presented frame), `load`, `close`, and the input events
 `mousemove`, `mousedown`, `mouseup`, `click`, `wheel`, `keydown`, `keyup`.
 
+On Windows a GUI program is linked as a **Windows-subsystem** executable, so
+launching it does not flash a console window. That also means stdout/stderr go
+nowhere when it is started from Explorer; set `app.console: true` in
+`xbintsc.config.json` to keep the console subsystem (useful while debugging).
+
 Input handlers receive a single payload object (lifecycle handlers receive none):
 
 ```ts
@@ -284,10 +294,29 @@ with absolute (viewport-relative) geometry:
   measured with the HarfBuzz/FreeType stack (see *Implemented text*).
 - **Flexbox** — single-line `row`/`column` (and the `-reverse` variants) with
   `gap`, `flex-basis`/`flex-grow`/`flex-shrink`, `justify-content` and
-  `align-items` (including `stretch` when the cross size is definite).
-
-Not yet implemented: margin collapsing, multi-line flex wrapping, `position`
-offsets (`relative`/`absolute`/`fixed`), `overflow` clipping and floats.
+  `align-items` (including `stretch` when the cross size is definite). Item
+  margins are part of the item's outer size on both axes, so a negative
+  `margin-top` pulls an item up instead of being ignored.
+- **Positioning** — `position: relative` offsets a box (and its subtree) by
+  `top`/`right`/`bottom`/`left` without changing the space it reserved;
+  `position: absolute` (and `fixed`, which resolves against the viewport) takes
+  the box out of flow and places it against the padding box of the nearest
+  positioned ancestor — the viewport when there is none. An `auto` inset keeps
+  the static position on that axis, an `auto` width is shrink-to-fit unless both
+  `left` and `right` are set (then it fills the space between them), and
+  percentages resolve against the containing block. There is no `z-index`
+  stacking yet: painting stays in document order.
+  Note the consequence of that shrink-to-fit rule: an absolutely positioned box
+  with `width: auto` and no explicit size gets **no** available width for its own
+  inline content (its preferred width comes from its text or its non-absolute
+  children only), so inline runs inside it are laid out at zero available width
+  and each one wraps onto its own line. Give such a box an explicit `width`, or
+  place its children with `left`/`width` (as
+  `examples/gui/pelican-bike` does for its sprite runs), instead of relying on
+  line flow inside it.
+
+Not yet implemented: margin collapsing, multi-line flex wrapping, `z-index`
+stacking, `overflow` clipping and floats.
 
 **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
@@ -302,6 +331,13 @@ emits a backend-agnostic `DisplayList` with two parallel lists: **rectangles**
 lets the renderer draw all rectangles, then all text on top, with one draw call
 per list. `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.
+
 `runtime/ext_gui/renderer.{h,cpp}` turns that list into two batched vertex
 buffers per window (one for shapes, one for glyph quads) drawn through two
 SDL_GPU graphics pipelines:
@@ -406,6 +442,12 @@ Still to do for animation: `@keyframes` animations and `cubic-bezier(...)`.
   `XT_GUI_FONT` (and `XT_GUI_FONT_MONO`), and cached per `(family class, size)`.
   Only regular upright faces are used for now; weight/italic selection is a
   later refinement.
+- The default candidates prefer a **CJK-capable** face (Microsoft YaHei on
+  Windows, PingFang on macOS, Noto Sans CJK/WenQuanYi on Linux) before the
+  Latin-only ones, because a run is shaped with a *single* face: without this,
+  Chinese/Japanese/Korean text renders as blank or `.notdef` boxes. Set
+  `XT_GUI_FONT` to a Latin-only face to get its Latin design instead (at the
+  cost of CJK coverage).
 - `xt_text_measure_width` shapes the run with HarfBuzz (so kerning and
   ligatures are honoured), `xt_text_metrics` returns FreeType's ascent /
   descent / normal line height. When no font file can be found the module falls
@@ -487,9 +529,23 @@ npm run gui          # build runtime/lib/<os>-<arch>/gui.a (fetches SDL3 once)
 xbintsc run examples/gui/hello.ts --ext gui
 ```
 
+Two examples live here: `hello.ts` (HTML/CSS + a reactive counter) and
+[`pelican-bike/`](../examples/gui/pelican-bike), a playable 2D game that uses
+positioned layers, CSS sprites, `requestAnimationFrame` and keyboard input — see
+its README for controls and the geometry report it prints.
+
 Set `XT_GUI_AUTOCLOSE_MS=<n>` to close all windows after `n` milliseconds,
 which the e2e test (`tests/e2e/gui-*.test.ts`) uses to run headlessly.
 
+Those suites are skipped on Windows by default (the archive is built there but
+the run is not validated in CI). With a `gui.lib` and a working GPU, opt in with
+`xbintsc_GUI_TESTS=1`:
+
+```bat
+set xbintsc_GUI_TESTS=1
+npx vitest run tests/e2e/gui-layout.test.ts tests/e2e/gui-example.test.ts
+```
+
 On a headless Linux box, install the SDL3 build headers and run under Xvfb with a
 software Vulkan driver:
 
@@ -579,6 +635,16 @@ used by default; Wayland is enabled too but not yet exercised.
       DOM (`gui.cpp`, `window.cpp`, `gui_engine.h`).
     - `Element.offsetWidth` / `offsetHeight` (rounded border box, flushes pending
       mutations) and `Element.contains(other)` (`dom_api.cpp`).
+11. **M11 — CSS positioning** ✅
+    - `position: relative` / `absolute` / `fixed` with `top`/`right`/`bottom`/
+      `left`, resolved against the nearest positioned ancestor (the viewport when
+      there is none), `auto` insets keeping the static position, shrink-to-fit
+      for an out-of-flow `width: auto` and fill-available when both horizontal
+      insets are set (`layout_flow.cpp`, `layout.h`).
+    - Item margins are honoured in the flex algorithm, so a negative margin
+      participates in the layout instead of being dropped (`layout_flex.cpp`).
+    - Drives `examples/gui/pelican-bike` and e2e coverage in
+      `tests/e2e/gui-layout.test.ts`.
 
 ## Progress log
 
@@ -629,11 +695,51 @@ used by default; Wayland is enabled too but not yet exercised.
   (callbacks run with the frame timestamp before layout each frame) plus
   `offsetWidth`/`offsetHeight`/`contains` on element handles; e2e coverage in
   `tests/e2e/gui-*.test.ts`.
+- **M11** ✅ `position: relative`/`absolute`/`fixed` with `top`/`right`/`bottom`/
+  `left`. Layout keeps a containing block per box (the nearest positioned
+  ancestor's padding box, published only once that ancestor has its final size,
+  so `bottom`/`right` are exact), absolute boxes are laid out after in-flow
+  content so they never affect it, shrink-to-fit/fill-available width rules are
+  applied, and flex items now account for their margins. e2e coverage in
+  `tests/e2e/gui-layout.test.ts`; `examples/gui/pelican-bike` is built on it.
+
+## Known issues
+
+- **Intermittent crash at auto-close.** `XT_GUI_AUTOCLOSE_MS` can end a run
+  with a native access violation in roughly two runs out of five; a clean exit
+  looks identical otherwise. Windows reports it as the NTSTATUS exit code
+  `0xC0000005`; on Linux/macOS the process dies with a signal — an access
+  violation is `SIGSEGV`, so `spawnSync` reports `status: null` plus a
+  `signal`. It only reproduces with a *running animation-frame loop* (a static
+  document closes fine) and it is **not** the game's own code: no exception is
+  reported, the crash usually lands inside the first second regardless of the
+  deadline, and raising `XT_GC_THRESHOLD` hides it, so it looks like a
+  GC/teardown race. Interactive runs (no auto-close) are stable for minutes.
+  A leading cause was that the engine cached `xt_value`s in C++ containers
+  the mark-sweep collector cannot see — the AOT `<script>` registry, element
+  handles, element listeners and the queued/currently-running
+  `requestAnimationFrame` callbacks. They are now marked by GC root providers
+  (`xt_gui_script_gc_scan` and `xt_gui_gc_scan_roots`), which removes that
+  class of use-after-free. `tests/e2e/gui-example.test.ts` still treats either
+  crash spelling as an acceptable outcome — the archive is built per platform
+  and the run is timing-sensitive — and the behavioural assertions live in
+  `tests/e2e/gui-example-browser.test.ts` (no GPU, deterministic).
+- **`display: none -> flex` restyle.** A hidden element being shown by a
+  *class change* on a flex container has also been observed to crash the same
+  way; `examples/gui/pelican-bike` reveals its game-over overlay with `opacity`
+  instead.
 
 ## Open questions
 
 - Whether Linux ships X11, Wayland, or both in the first cut. (Decision:
   X11 first, Wayland later.)
+- **SVG:** there is no SVG support and none is planned. The HTML parser knows
+  elements and attributes, the layout engine knows boxes, and paint knows
+  rectangles/text/images, so `<svg>` trees would need a whole second
+  geometry+paint path. An SVG *file* works only through the image loader
+  (`<img src="logo.svg">`), which needs an SVG rasteriser (`stb_image` does not
+  decode SVG); vector art therefore has to arrive as a raster (PNG) or be drawn
+  from boxes, as `examples/gui/pelican-bike` does.
 - 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

package/doc/xbintsc.config.schema.json

@@ -60,6 +60,10 @@
         "bundleId": {
           "type": "string",
           "description": "macOS CFBundleIdentifier, e.g. com.example.demo."
+        },
+        "console": {
+          "type": "boolean",
+          "description": "Windows only: keep the console subsystem (a console window) instead of the default Windows subsystem, so stdout/stderr are visible while debugging a GUI program."
         }
       }
     }

package/doc/zh-CN/gui.md

@@ -2,7 +2,7 @@
 
 > 语言 / Language：[English](../gui.md) | **简体中文**
 
-状态：**M10** —— 功能（M1–M10）已全部完成：HTML 解析、CSS 选择器匹配、层叠（cascade）、计算样式与布局（块级、行内与 Flexbox）均已就位，引擎还会**绘制**：它构建一个由矩形、图像与排版后的文本 run 组成的显示列表，并通过 SDL_GPU 渲染。输入事件会经过命中测试并投递给原生 TS 处理器，`:hover`/`:focus` 会被动态匹配，`<img>` 依据其固有尺寸确定大小并从纹理绘制，CSS transition 会为绘制属性做动画。**M8** 增加了交互式 DOM：具有稳定标识的元素句柄、变更操作（`appendChild`、`textContent`、`classList`、`style` 等）以及支持捕获/冒泡的元素级事件。**M9** 会提前编译 `<script>` 主体（内联与 `<script src>`）——参见 `gui-scripts.md`。**M10** 增加 `requestAnimationFrame` 以及若干 DOM 辅助方法。本文档记录了一个跨平台 GUI 扩展的锁定决策、架构、里程碑计划与当前进度；该扩展使用自有的 GPU 加速引擎渲染 HTML/CSS UI。
+状态：**M11** —— 功能（M1–M11）已全部完成：HTML 解析、CSS 选择器匹配、层叠（cascade）、计算样式与布局（块级、行内、Flexbox 与 CSS 定位）均已就位，引擎还会**绘制**：它构建一个由矩形、图像与排版后的文本 run 组成的显示列表，并通过 SDL_GPU 渲染。输入事件会经过命中测试并投递给原生 TS 处理器，`:hover`/`:focus` 会被动态匹配，`<img>` 依据其固有尺寸确定大小并从纹理绘制，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 游戏）就构建在它之上。本文档记录了一个跨平台 GUI 扩展的锁定决策、架构、里程碑计划与当前进度；该扩展使用自有的 GPU 加速引擎渲染 HTML/CSS UI。
 
 ## 目标
 
@@ -88,7 +88,15 @@ run();                                 // 驱动主循环，直到所有窗口
 ```
 
 窗口句柄上已实现的方法：`setTitle` / `setSize` / `loadHTML` /
-`getHTML` / `setBackground` / `close` / `isOpen` / `on` / `off`。触发的事件：
+`getHTML` / `setBackground` / `close` / `isOpen` / `on` / `off`，以及
+`driver()`——它报告当前使用的 SDL_GPU 后端（`"vulkan"`、`"direct3d12"`、
+`"metal"` 等，由 SDL 挑选设备支持的最佳后端）。
+
+在 Windows 上，GUI 程序会被链接为 **Windows 子系统**可执行文件，因此启动时不会闪出控制台
+窗口；这也意味着从资源管理器启动时 stdout/stderr 无处可去，调试时可在
+`xbintsc.config.json` 里设置 `app.console: true` 保留控制台子系统。
+
+触发的事件：
 `ready`（首个呈现帧之后）、`load`、`close`，以及输入事件
 `mousemove`、`mousedown`、`mouseup`、`click`、`wheel`、`keydown`、`keyup`。
 
@@ -252,10 +260,21 @@ run();
   技术栈测量（见 *已实现的文本*）。
 - **Flexbox** —— 单行 `row`/`column`（以及 `-reverse` 变体），支持 `gap`、
   `flex-basis`/`flex-grow`/`flex-shrink`、`justify-content` 与 `align-items`
-  （当交叉轴尺寸确定时包括 `stretch`）。
-
-尚未实现：外边距折叠、多行 flex 换行、`position` 偏移
-（`relative`/`absolute`/`fixed`）、`overflow` 裁剪与浮动。
+  （当交叉轴尺寸确定时包括 `stretch`）。flex 项的外边距参与其外框尺寸，因此
+  负的 `margin-top` 会把该项上移，而不是被忽略。
+- **定位** —— `position: relative` 会按 `top`/`right`/`bottom`/`left` 偏移该盒子
+  及其子树，但不改变它在流中占用的空间；`position: absolute`（以及针对视口解析
+  的 `fixed`）使其脱离文档流，并相对最近的已定位祖先的 padding box 定位（没有
+  这样的祖先时则相对视口）。`auto` 的 inset 在该轴上保留静态位置；宽度 `auto`
+  时使用 shrink-to-fit，除非 `left` 与 `right` 同时给出（此时填满两者之间的空间）；
+  百分比相对包含块解析。目前还没有 `z-index` 层叠，绘制仍按文档顺序进行。
+  注意该 shrink-to-fit 规则的后果：一个 `width: auto` 且没有显式尺寸的绝对定位
+  盒子，其内部行内内容得到的**可用宽度为 0**（它的首选宽度只来自文本与
+  非绝对定位的子元素），因此其中的行内 run 会各自换到独立的一行。请为此类盒子
+  给出显式 `width`，或用 `left`/`width` 摆放其子元素（`examples/gui/pelican-bike`
+  的精灵 run 就是这样做的），而不要依赖其内部的行流。
+
+尚未实现：外边距折叠、多行 flex 换行、`z-index` 层叠、`overflow` 裁剪与浮动。
 
 **Document**（`runtime/ext_gui/document.{h,cpp}`）：持有 DOM 树，把 `<style>`
 文本汇总为一份样式表，为某个视口计算样式与布局，并提供
@@ -269,6 +288,11 @@ run();
 把它们分开可以让渲染器先绘制所有矩形，再在其上绘制所有文本，每个列表一次
 绘制调用。`DisplayList::dump()` 为 `paintList()`/`paintCount()` 提供数据。
 
+`opacity` 只在两端生效：计算值为 `0` 的盒子（及其整棵子树）不绘制任何内容，
+大于 `0` 的一律按完全不透明绘制。图形只携带其颜色自身的 alpha，因此没有部分
+透明盒子的合成——CSS 解析器接受的 `opacity` 过渡因此也看不到效果。把隐藏态写成
+`opacity: 0` 来隐藏/显示一层，正是 `examples/gui/pelican-bike` 游戏结束遮罩的做法。
+
 `runtime/ext_gui/renderer.{h,cpp}` 把该列表转换为每个窗口两个批处理顶点缓冲
 （一个用于图形，一个用于字形四边形），通过两条 SDL_GPU 图形管线绘制：
 
@@ -441,6 +465,19 @@ xbintsc run examples/gui/hello.ts --ext gui
 设置 `XT_GUI_AUTOCLOSE_MS=<n>` 可在 `n` 毫秒后关闭所有窗口，e2e 测试
 （`tests/e2e/gui-*.test.ts`）用它来无头运行。
 
+这里有两个示例：`hello.ts`（HTML/CSS + 响应式计数器）与
+[`pelican-bike/`](../examples/gui/pelican-bike)（一个可玩的 2D 游戏，使用分层
+定位、CSS 像素精灵、`requestAnimationFrame` 与键盘输入）——操作方式与它输出的
+几何报告见该目录的 README。
+
+这些测试套件在 Windows 上默认跳过（该平台会构建归档，但 CI 未验证运行）。
+如果本机有 `gui.lib` 与可用的 GPU，可用 `xbintsc_GUI_TESTS=1` 选择启用：
+
+```bat
+set xbintsc_GUI_TESTS=1
+npx vitest run tests/e2e/gui-layout.test.ts tests/e2e/gui-example.test.ts
+```
+
 在无头 Linux 机器上，安装 SDL3 构建头文件，并在 Xvfb 与软件 Vulkan 驱动下
 运行：
 
@@ -525,6 +562,15 @@ xvfb-run -a --server-args="-screen 0 1280x720x24" \
       （`gui.cpp`、`window.cpp`、`gui_engine.h`）。
     - `Element.offsetWidth` / `offsetHeight`（取整后的边框盒，会冲刷待处理
       的变更）与 `Element.contains(other)`（`dom_api.cpp`）。
+11. **M11 — CSS 定位** ✅
+    - `position: relative` / `absolute` / `fixed` 与 `top`/`right`/`bottom`/
+      `left`，相对最近的已定位祖先解析（没有时相对视口）；`auto` inset 保留
+      静态位置；脱离文档流的 `width: auto` 使用 shrink-to-fit，两个水平 inset
+      都给出时则填满可用宽度（`layout_flow.cpp`、`layout.h`）。
+    - flex 算法现在会计入项的外边距，负外边距参与布局而不再被丢弃
+      （`layout_flex.cpp`）。
+    - `examples/gui/pelican-bike` 基于它实现，e2e 覆盖见
+      `tests/e2e/gui-layout.test.ts`。
 
 ## 进度日志
 
@@ -573,6 +619,28 @@ xvfb-run -a --server-args="-screen 0 1280x720x24" \
   （回调在每帧布局之前以帧时间戳运行），以及元素句柄上的
   `offsetWidth`/`offsetHeight`/`contains`；e2e 覆盖在
   `tests/e2e/gui-*.test.ts` 中。
+- **M11** ✅ `position: relative`/`absolute`/`fixed` 与 `top`/`right`/`bottom`/
+  `left`。布局为每个盒子保留包含块（最近的已定位祖先的 padding box，且只在
+  该祖先拥有最终尺寸后才发布，因此 `bottom`/`right` 精确）；绝对定位的盒子
+  在正常流内容之后布局，因此不影响它们；实现了 shrink-to-fit / 填满可用宽度
+  两种规则；flex 项现在会计入外边距。e2e 覆盖在
+  `tests/e2e/gui-layout.test.ts`；`examples/gui/pelican-bike` 基于它实现。
+
+## 已知问题
+
+- **自动关闭时的偶发崩溃。** 设置 `XT_GUI_AUTOCLOSE_MS` 结束运行时，约五次中有两次会以原生
+  访问违例（`0xC0000005`）退出，其余运行与正常退出无异。该问题只在**动画帧循环运行中**复现
+  （静态文档可以正常关闭），且**不是示例游戏自身**的代码：没有任何异常信息，崩溃多发生在
+  启动后一秒内、与截止时间无关，而提高 `XT_GC_THRESHOLD` 可以掩盖它，因此看起来是
+  GC/析构竞态。交互式运行（不设自动关闭）可稳定运行数分钟。`tests/e2e/gui-example.test.ts`
+  因此把该退出码视为可接受结果，行为断言放在不依赖 GPU 的
+  `tests/e2e/gui-example-browser.test.ts` 中。
+- **`display: none -> flex` 的重排。** 通过类名切换让隐藏元素显示在 flex 容器上时，也曾观察
+  到同样的崩溃；`examples/gui/pelican-bike` 改用 `opacity` 显示游戏结束遮罩。
+- **SVG：** 引擎不支持也不计划支持 SVG 元素。HTML 解析器只认识元素与属性，布局只认识盒子，
+  绘制只认识矩形/文本/图像；`<svg>` 子树需要另一套几何与绘制路径。SVG *文件* 也只能走图像
+  加载器（`<img src="logo.svg">`），而这需要 SVG 光栅化器（`stb_image` 不解码 SVG）。因此
+  矢量美术要么以位图（PNG）形式提供，要么像 `examples/gui/pelican-bike` 那样用盒子绘制。
 
 ## 待决问题
 

package/package.json

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

package/runtime/ext_gui/dom_api.cpp

@@ -136,6 +136,25 @@ xt_value xt_gui_node_handle(XtGuiWindow *win, const xtgui::Node *node) {
   return handle;
 }
 
+void xt_gui_node_handle_forget(XtGuiWindow *win, const xtgui::Node *node) {
+  if (win == nullptr || node == nullptr) return;
+  /* The node is about to be destroyed (a removal, or `innerHTML = …` dropping
+   * the old children). Drop its slot as well as its handle: the slot is what
+   * `resolve_node` reads, and leaving a freed pointer there is a
+   * use-after-free the next time any handle is resolved. Existing handles keep
+   * resolving to "stale" and no-op, which is the documented tombstone
+   * behaviour. */
+  auto index = win->node_index.find(node);
+  if (index != win->node_index.end()) {
+    int slot = index->second;
+    if (slot >= 0 && slot < (int)win->node_order.size()) {
+      win->node_order[(size_t)slot] = nullptr;
+    }
+    win->node_index.erase(index);
+  }
+  win->node_handles.erase(node);
+}
+
 xt_value xt_gui_document_handle(XtGuiWindow *win) {
   if (win == nullptr) return XT_UNDEFINED;
   if (!XT_IS_OBJECT(win->document_object)) {

package/runtime/ext_gui/dom_api_node.cpp

@@ -177,7 +177,10 @@ METHOD(node_replace_child) {
   xtgui::Node *newChild = resolve_node(xt_arg(argc, argv, 0), nullptr);
   xtgui::Node *oldChild = resolve_node(xt_arg(argc, argv, 1), nullptr);
   if (newChild == nullptr || oldChild == nullptr) return XT_UNDEFINED;
-  return xt_gui_node_handle(win, win->document->replaceChild(node, newChild, oldChild));
+  /* `replaceChild` frees the node it replaces, so its slot may not survive. */
+  xtgui::Node *replaced = win->document->replaceChild(node, newChild, oldChild);
+  if (replaced != oldChild) xt_gui_node_handle_forget(win, oldChild);
+  return xt_gui_node_handle(win, replaced);
 }
 
 METHOD(node_remove) {

package/runtime/ext_gui/dom_api_node_read.cpp

@@ -25,6 +25,13 @@ static void collect_text(const xtgui::Node *node, std::string &out) {
   for (const std::unique_ptr<xtgui::Node> &child : node->children) collect_text(child.get(), out);
 }
 
+/** Forget the handles of `node` and every descendant: they are about to be
+ * freed, and a slot left behind would dangle. */
+static void forget_subtree(XtGuiWindow *win, const xtgui::Node *node) {
+  xt_gui_node_handle_forget(win, node);
+  for (const std::unique_ptr<xtgui::Node> &child : node->children) forget_subtree(win, child.get());
+}
+
 #define METHOD(name) xt_value name(xt_value self, xt_value env, int32_t argc, xt_value *argv)
 
 METHOD(node_tag_name_get) {
@@ -105,6 +112,7 @@ METHOD(node_text_content_set) {
   std::vector<xtgui::Node *> existing;
   for (const std::unique_ptr<xtgui::Node> &child : node->children) existing.push_back(child.get());
   for (xtgui::Node *child : existing) win->document->removeChild(node, child);
+  for (xtgui::Node *child : existing) forget_subtree(win, child);
   if (!text.empty()) node->addText(text);
   mark_dirty(win);
   return XT_UNDEFINED;
@@ -132,6 +140,10 @@ METHOD(node_inner_html_set) {
   std::vector<xtgui::Node *> existing;
   for (const std::unique_ptr<xtgui::Node> &child : node->children) existing.push_back(child.get());
   for (xtgui::Node *child : existing) win->document->removeChild(node, child);
+  /* The old children are dropped here (only `removeChild` keeps a detached node
+   * alive), so forget them *and everything below them* before they are freed:
+   * a leftover slot would be a dangling pointer for the next handle lookup. */
+  for (xtgui::Node *child : existing) forget_subtree(win, child);
   std::unique_ptr<xtgui::Node> fragment = xtgui::xt_html_parse(html);
   for (std::unique_ptr<xtgui::Node> &child : fragment->children) node->append(std::move(child));
   mark_dirty(win);

package/runtime/ext_gui/gui.cpp

@@ -64,10 +64,36 @@ void xt_gui_apply_icon(SDL_Window *window) {
   SDL_DestroySurface(surface);
 }
 
+/* -- garbage collector roots ---------------------------------------------- */
+
+/**
+ * GC root provider: the engine caches `xt_value`s in C++ containers that the
+ * mark-sweep collector cannot see — per-window element handles, element
+ * listeners, the document handle and the queued/currently-running
+ * `requestAnimationFrame` callbacks. Rooting the window object alone does not
+ * reach these (they are not its properties), so without this provider a
+ * collection frees values the engine still uses and the next frame or DOM read
+ * crashes. The process-wide AOT `<script>` registry registers its own
+ * provider (`xt_gui_script_gc_scan`).
+ */
+static void xt_gui_gc_scan_roots(void) {
+  for (int i = 0; i < g_window_count; i++) {
+    const XtGuiWindow &win = g_windows[i];
+    xt_gc_mark_value(win.object);
+    xt_gc_mark_value(win.document_object);
+    for (const auto &entry : win.node_handles) xt_gc_mark_value(entry.second);
+    for (const auto &entry : win.node_listeners) {
+      for (const XtGuiNodeListener &listener : entry.second) xt_gc_mark_value(listener.fn);
+    }
+    for (const XtGuiAnimationFrame &frame : win.animation_frames) xt_gc_mark_value(frame.fn);
+    for (const XtGuiAnimationFrame &frame : win.running_frames) xt_gc_mark_value(frame.fn);
+  }
+}
+
 /* -- initialisation ------------------------------------------------------- */
 
-static int ensure_init(void) {
-  if (g_sdl_initialized) return 1;
+static int ensure_init(void) {  if (g_sdl_initialized) return 1;
+  xt_gc_register_root_provider(xt_gui_gc_scan_roots);
   if (!SDL_Init(SDL_INIT_VIDEO)) {
     fprintf(stderr, "xt_gui: SDL_Init failed: %s\n", SDL_GetError());
     return 0;
@@ -102,6 +128,12 @@ static XtGuiWindow *window_by_object(xt_value object) {
 
 using namespace guidev;
 
+const char *xt_gui_driver(void) {
+  if (g_device == NULL) return "";
+  const char *driver = SDL_GetGPUDeviceDriver(g_device);
+  return driver != NULL ? driver : "";
+}
+
 XtGuiWindow *xt_gui_window_from_this(xt_value thisValue) {
   return window_by_object(thisValue);
 }
@@ -206,6 +238,14 @@ extern "C" xt_value xt_gui_create_window(int32_t argc, xt_value *argv) {
   xt_object_set(object, xt_string_from_cstr("__xt_gui_index"), xt_number((double)index));
   xt_object_set(object, xt_string_from_cstr("__xt_gui_html"), xt_string_from_cstr(""));
   xt_object_set(object, xt_string_from_cstr("__xt_gui_events"), xt_object_new());
+  /* The engine owns a graph of values on the window's behalf — element
+   * handles (`node_handles`), their event listeners and the queued animation
+   * frame closures. Most of them are referenced from TypeScript too, but not
+   * all: a handle the script queried once and dropped (or one only reachable
+   * through an ancestor element) would otherwise be collected while the engine
+   * still uses it, which is a use-after-free. Rooting the window object makes
+   * everything hanging off it reachable. */
+  xt_gc_add_root(&record->object);
 
   return object;
 }

package/runtime/ext_gui/gui_engine.h

@@ -24,6 +24,9 @@ xt_value xt_gui_run(int32_t argc, xt_value *argv);
 xt_value xt_gui_quit(int32_t argc, xt_value *argv);
 /** `__registerScript(id, fn)`: record an AOT-compiled `<script>` body. */
 xt_value xt_register_script(int32_t argc, xt_value *argv);
+/** Which SDL_GPU backend the device is using (`"vulkan"`, `"direct3d12"`,
+ * `"metal"`, …), or `""` before the device exists. */
+const char *xt_gui_driver(void);
 
 #ifdef __cplusplus
 } /* extern "C" */
@@ -84,6 +87,11 @@ struct XtGuiWindow {
   int struct_dirty = 0;
   /** Callbacks queued for the next frame, plus the id counter. */
   std::vector<XtGuiAnimationFrame> animation_frames;
+  /** The batch currently running: its callbacks have been swapped out of
+   * `animation_frames`, and a collection triggered by one of them must still
+   * see the rest. Kept on the record (not a local) so the GC root provider can
+   * mark it. Empty except while `xt_gui_run_animation_frames` runs. */
+  std::vector<XtGuiAnimationFrame> running_frames;
   int next_animation_frame_id = 1;
 };
 
@@ -93,6 +101,10 @@ XtGuiWindow *xt_gui_window_from_this(xt_value thisValue);
 xt_value xt_gui_document_handle(XtGuiWindow *win);
 /** Node handle for `node` (created and cached on first use). */
 xt_value xt_gui_node_handle(XtGuiWindow *win, const xtgui::Node *node);
+/** Forget a node's slot and handle because it is about to be destroyed (a
+ * removal that frees it, or `innerHTML = …` dropping the old children). Without
+ * this the node table would keep a dangling pointer. */
+void xt_gui_node_handle_forget(XtGuiWindow *win, const xtgui::Node *node);
 /** Drop every cached handle/listener and bump the document generation. */
 void xt_gui_handles_reset(XtGuiWindow *win);
 /** Deliver `type` to element listeners along the propagation path. */
@@ -105,6 +117,9 @@ void xt_gui_flush_dom(XtGuiWindow *win);
 /** Run every registered `<script data-xt-id>` body found in the document, in
  * document order, passing `(windowHandle, documentHandle)`. */
 void xt_gui_run_scripts(XtGuiWindow *win);
+/** GC root provider: mark every AOT-compiled `<script>` function in the
+ * process-wide registry. Registered with the collector by `xt_register_script`. */
+void xt_gui_script_gc_scan(void);
 /** Shared prototype carrying the window methods. */
 xt_value xt_gui_window_proto(void);
 /** Release GPU claim + destroy the window and mark the record closed. */

package/runtime/ext_gui/gui_events.cpp

@@ -220,15 +220,18 @@ void handle_event(const SDL_Event *event) {
 
 void xt_gui_run_animation_frames(XtGuiWindow *win, double timestamp_ms) {
   if (win == NULL || win->animation_frames.empty()) return;
-  /* Swap the queue out first: a callback that calls requestAnimationFrame
-   * again schedules for the *next* frame, not this one. */
-  std::vector<XtGuiAnimationFrame> frames;
+  /* Swap the queue into a member, not a local: the GC root provider marks
+   * `running_frames` too, so a collection triggered while one callback runs
+   * cannot free the rest of the batch. Re-queueing from a callback lands in
+   * `animation_frames` and runs on the *next* frame, not this one. */
+  std::vector<XtGuiAnimationFrame> &frames = win->running_frames;
   frames.swap(win->animation_frames);
   for (const XtGuiAnimationFrame &frame : frames) {
     if (!win->open) break;
     xt_value arg = xt_number(timestamp_ms);
     xt_call_with_this(frame.fn, win->object, 1, &arg);
   }
+  frames.clear();
 }
 
 void xt_gui_render_window(XtGuiWindow *win) {
@@ -244,6 +247,10 @@ void xt_gui_render_window(XtGuiWindow *win) {
   /* Animation-frame callbacks run before layout, so any DOM mutation they make
    * is picked up by this same frame. */
   xt_gui_run_animation_frames(win, now);
+  /* A callback may have closed the window (directly or through the
+   * auto-close guard): `xt_gui_quit_window` released the document and the GPU
+   * geometry, so there is nothing left to lay out or paint. */
+  if (!win->open) return;
   if (win->document != nullptr && win->document->advance(delta)) win->geometry.dirty = 1;
 
   /* A DOM mutation from a handler invalidates the tree: restyle/relayout

package/runtime/ext_gui/layout.cpp

@@ -96,6 +96,12 @@ void LayoutTree::compute(const Node *root, const std::unordered_map<const Node *
   root_->node = root;
   root_->style = &root_style_;
   root_->display = Display::Block;
+  /* The initial containing block: absolute boxes with no positioned ancestor
+   * resolve their insets against the viewport. */
+  root_->cb_x = 0;
+  root_->cb_y = 0;
+  root_->cb_width = viewportWidth;
+  root_->cb_height = viewportHeight;
   if (root != nullptr) {
     if (root->type == NodeType::Document) {
       for (const std::unique_ptr<Node> &child : root->children) {

package/runtime/ext_gui/layout.h

@@ -59,6 +59,10 @@ struct LayoutBox {
   float content_x = 0, content_y = 0, content_width = 0, content_height = 0;
   float baseline = 0;
 
+  /* The padding box of the nearest positioned ancestor (the viewport when there
+   * is none): the containing block `position: absolute` resolves against. */
+  float cb_x = 0, cb_y = 0, cb_width = 0, cb_height = 0;
+
   LayoutBox *parent = nullptr;
   std::vector<std::unique_ptr<LayoutBox>> children;
 };

package/runtime/ext_gui/layout_flex.cpp

@@ -19,9 +19,12 @@ float Layouter::layoutFlex(LayoutBox *container, float contentWidth, float defin
                  containerStyle.flex_direction == FlexDirection::ColumnReverse;
   float gap = px(containerStyle.gap, contentWidth, containerStyle.font_size, 0.0f);
 
+  /* An absolutely positioned child is out of flow: it takes no part in the flex
+   * algorithm and is placed against the container's padding box instead. */
   std::vector<LayoutBox *> items;
   for (const std::unique_ptr<LayoutBox> &child : container->children) {
-    if (child->display != Display::None) items.push_back(child.get());
+    if (child->display == Display::None || isAbsoluteChild(child.get())) continue;
+    items.push_back(child.get());
   }
   if (items.empty()) return 0;
   size_t count = items.size();
@@ -71,6 +74,7 @@ float Layouter::layoutFlex(LayoutBox *container, float contentWidth, float defin
     for (size_t i = 0; i < count; i++) {
       float contentW = mainSizes[i] - horizontalEdges(items[i]);
       if (contentW < 0) contentW = 0;
+      setContainingBlock(items[i], containingBlockAncestor(items[i]));
       layoutBlock(items[i], container->content_x, container->content_y, contentWidth,
                   definiteHeight, contentW);
       cross[i] = verticalEdges(items[i]) + items[i]->height;
@@ -98,8 +102,8 @@ float Layouter::layoutFlex(LayoutBox *container, float contentWidth, float defin
     for (size_t k = 0; k < count; k++) {
       size_t i = reverse ? (count - 1 - k) : k;
       float crossOffset = crossOffsetFor(containerStyle.align_items, crossSize, cross[i]);
-      float dx = cursor - items[i]->x;
-      float dy = container->content_y + crossOffset - items[i]->y;
+      float dx = cursor + items[i]->margin_left - items[i]->x;
+      float dy = container->content_y + crossOffset + items[i]->margin_top - items[i]->y;
       translate(items[i], dx, dy);
       cursor += mainSizes[i] + between;
     }
@@ -111,6 +115,7 @@ float Layouter::layoutFlex(LayoutBox *container, float contentWidth, float defin
   std::vector<float> outer(count, 0.0f);
   float sumBase = 0;
   for (size_t i = 0; i < count; i++) {
+    setContainingBlock(items[i], containingBlockAncestor(items[i]));
     layoutBlock(items[i], container->content_x, container->content_y, contentWidth, definiteHeight);
     outer[i] = verticalEdges(items[i]) + items[i]->height;
     sumBase += outer[i];
@@ -142,8 +147,11 @@ float Layouter::layoutFlex(LayoutBox *container, float contentWidth, float defin
   float cursor = container->content_y + offset;
   for (size_t k = 0; k < count; k++) {
     size_t i = reverse ? (count - 1 - k) : k;
-    float dx = container->content_x - items[i]->x;
-    float dy = cursor - items[i]->y;
+    float dx = container->content_x + items[i]->margin_left - items[i]->x;
+    /* Margins keep the item's outer box on the main axis, exactly like block
+     * flow — a negative `margin-top` pulls the item up instead of being
+     * silently dropped. */
+    float dy = cursor + items[i]->margin_top - items[i]->y;
     translate(items[i], dx, dy);
     cursor += mainSizes[i] + between;
   }