xbintsc 0.3.65 → 0.3.68

package/README.md

@@ -67,7 +67,11 @@ reclaimed by a non-moving mark-sweep collector: roots are explicit value slots
 (module globals, prototype caches), runtime root providers (the event loop,
 the promise microtask queue) and a conservative scan of the active C stack.
 Collection is armed automatically once the live heap crosses a threshold
-(`XT_GC_THRESHOLD`) and can also run on demand.
+(`XT_GC_THRESHOLD` pins it) and can also run on demand. After every collection the
+threshold becomes twice the surviving heap (floor 1 MiB), so a program with a
+small live set collects often and keeps a small resident set;
+`XT_GC_TRACE=1` prints one line per collection (heap and live-allocation counts,
+the next trigger and the live set by object kind) to stderr.
 
 ## Usage
 

package/dist/tests/e2e/gui-retention.test.d.ts

@@ -0,0 +1,14 @@
+/**
+ * End-to-end test for the `gui` extension — DOM memory retention.
+ *
+ * A game loop mutates the document every frame: `innerHTML = …` rebuilds a
+ * sprite, `textContent = …` refreshes a HUD field. The engine used to park every
+ * replaced subtree in the document's detached-node pool and keep an element
+ * handle (plus its slot) for every node it ever handed out, so both grew with
+ * the frame count and a long run leaked tens of megabytes per minute.
+ *
+ * The counters come from `window.stats()`. Everything the churn is allowed to
+ * change is the tree itself: the detached pool, the handle table and the handle
+ * slots must come back to where they started.
+ */
+export {};

package/dist/tests/e2e/gui-retention.test.js

@@ -0,0 +1,100 @@
+/**
+ * End-to-end test for the `gui` extension — DOM memory retention.
+ *
+ * A game loop mutates the document every frame: `innerHTML = …` rebuilds a
+ * sprite, `textContent = …` refreshes a HUD field. The engine used to park every
+ * replaced subtree in the document's detached-node pool and keep an element
+ * handle (plus its slot) for every node it ever handed out, so both grew with
+ * the frame count and a long run leaked tens of megabytes per minute.
+ *
+ * The counters come from `window.stats()`. Everything the churn is allowed to
+ * change is the tree itself: the detached pool, the handle table and the handle
+ * slots must come back to where they started.
+ */
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { createGuiHarness, guiAvailable } from "./gui-helpers.js";
+const harness = createGuiHarness();
+describe.skipIf(!guiAvailable)("gui extension — dom retention", () => {
+    beforeAll(() => harness.setup());
+    afterAll(() => harness.cleanup());
+    it("releases the nodes innerHTML/textContent/replaceChild drop", () => {
+        const { value } = harness.compileAndRun("dom-retention", `
+      import { createWindow, run } from "gui";
+
+      const HTML = \`
+      <html><head><style>
+        body { margin: 0; }
+        #box { width: 100px; height: 50px; }
+        .row { display: block; width: 40px; height: 10px; }
+      </style></head><body>
+        <div id="box"></div>
+      </body></html>\`;
+
+      const win = createWindow({ title: "retention", width: 400, height: 300 });
+      win.on("ready", () => {
+        const doc = win.document;
+        const box = doc.getElementById("box");
+        /* Growth of the pooled nodes, the handles and the handle slots. The
+           document tree itself is allowed to change; these three are not. */
+        const leak = (a: any, b: any): string =>
+          (b.detachedRoots - a.detachedRoots) + ":" + (b.detachedNodes - a.detachedNodes) +
+          ":" + (b.handles - a.handles) + ":" + (b.handleSlots - a.handleSlots);
+
+        const before = win.stats();
+        console.log("empty=" + before.treeNodes + ":" + leak(before, before));
+        const sprite = "<div class='row'><span>a</span></div><div class='row'><span>b</span></div>";
+        for (let i = 0; i < 500; i++) box.innerHTML = sprite;
+        const afterInner = win.stats();
+        console.log("inner=" + leak(before, afterInner));
+        const treeAfterInner = afterInner.treeNodes;
+        for (let i = 0; i < 500; i++) box.innerHTML = sprite;
+        console.log("innerAgain=" + leak(afterInner, win.stats()) + ":" +
+          (win.stats().treeNodes === treeAfterInner));
+        for (let i = 0; i < 500; i++) box.textContent = "value " + i;
+        console.log("text=" + leak(afterInner, win.stats()));
+
+        /* A node the script removed itself is *not* dropped: DOM semantics keep
+           it alive and usable until it is re-attached. */
+        const held = doc.createElement("b");
+        held.textContent = "held";
+        box.appendChild(held);
+        box.removeChild(held);
+        console.log("removed=" + held.isConnected + ":" + held.textContent + ":" + win.stats().detachedRoots);
+        box.appendChild(held);
+        console.log("reattached=" + held.isConnected + ":" + win.stats().detachedRoots);
+
+        /* replaceChild drops the node it replaces, so its handle goes stale. */
+        const first = box.firstElementChild;
+        const replacement = doc.createElement("i");
+        box.replaceChild(replacement, first);
+        console.log("replaced=" + replacement.isConnected + ":" + first.isConnected + ":" +
+          win.stats().detachedRoots);
+
+        /* A create/drop loop must reuse handle slots rather than grow the table:
+           each iteration creates an element, attaches it and replaces it with a
+           plain text node, which releases it again. */
+        const slotsBefore = win.stats().handleSlots;
+        for (let i = 0; i < 200; i++) {
+          const node = doc.createElement("u");
+          box.appendChild(node);
+          box.innerHTML = "x";
+        }
+        const recycled = win.stats();
+        console.log("recycled=" + (recycled.handleSlots - slotsBefore) + ":" + recycled.detachedNodes);
+        win.close();
+      });
+      win.loadHTML(HTML);
+      run();
+      `);
+        expect(value("empty")).toBe("10:0:0:0:0");
+        // 500 sprite writes, then 500 more: no pooled node, handle or slot survives.
+        expect(value("inner")).toBe("0:0:0:0");
+        expect(value("innerAgain")).toBe("0:0:0:0:true");
+        expect(value("text")).toBe("0:0:0:0");
+        expect(value("removed")).toBe("false:held:1");
+        expect(value("reattached")).toBe("true:0");
+        expect(value("replaced")).toBe("true:false:0");
+        expect(value("recycled")).toBe("0:0");
+    });
+});
+//# sourceMappingURL=gui-retention.test.js.map

package/dist/tests/e2e/gui-retention.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gui-retention.test.js","sourceRoot":"","sources":["../../../tests/e2e/gui-retention.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAC;AACnE,OAAO,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAElE,MAAM,OAAO,GAAG,gBAAgB,EAAE,CAAC;AAEnC,QAAQ,CAAC,MAAM,CAAC,CAAC,YAAY,CAAC,CAAC,+BAA+B,EAAE,GAAG,EAAE;IACnE,SAAS,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC;IACjC,QAAQ,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;IAElC,EAAE,CAAC,4DAA4D,EAAE,GAAG,EAAE;QACpE,MAAM,EAAE,KAAK,EAAE,GAAG,OAAO,CAAC,aAAa,CACrC,eAAe,EACf;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAmEC,CACF,CAAC;QAEF,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;QAC1C,6EAA6E;QAC7E,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QACvC,MAAM,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;QACjD,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QACtC,MAAM,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;QAC9C,MAAM,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAC3C,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;QAC/C,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACxC,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/doc/gui.md

@@ -1,6 +1,6 @@
 # xbintsc GUI extension (self-hosted HTML/CSS renderer)
 
-Status: **M11** — features (M1–M11) are complete: HTML parsing, CSS selector
+Status: **M12** — 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
@@ -13,7 +13,9 @@ DOM: element handles with stable identity, mutation (`appendChild`, `textContent
 **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.
+what `examples/gui/pelican-bike` — a playable 2D game — is built on. **M12** makes
+DOM node lifetime explicit (what a mutation releases, what it keeps) and gives the
+engine bounded memory: see "Node lifetime" and "Memory & GC".
 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.
@@ -191,8 +193,16 @@ win.fontMetrics(fontSize?, family?)    // { ascent, descent, lineHeight, ready }
 win.hitTest(x, y)                      // deepest element descriptor, or ""
 win.sendEvent(type, options?)          // synthesise input (testing)
 win.advance(ms)                        // step the CSS transition clock (testing)
+win.stats()                            // engine/runtime counters (memory debugging)
 ```
 
+`win.stats()` returns `{ heapBytes, heapAllocations, treeNodes, detachedRoots,`
+`detachedNodes, handles, handleSlots, listeners }`: the live runtime heap, the
+size of the DOM tree, the detached-node pool, and the element-handle tables. In a
+steady state every one of them is constant — a climbing `detachedNodes` or
+`handles` means the program removes nodes faster than it releases them (see
+"Node lifetime" below).
+
 They are used by `tests/e2e/gui-*.test.ts` to assert parsing, selector matching,
 specificity, inheritance, `!important` and layout geometry. They will stay useful
 afterwards for debugging.
@@ -230,6 +240,31 @@ bubble up to `document`/`window`. The legacy `win.on(type, fn)` payload keeps it
 **string** `e.target` (`div#id.class`); the element `Event.target` is a handle
 whose descriptor matches the same string.
 
+#### Node lifetime
+
+A mutation decides whether the nodes it removes can still be reached, and the
+engine releases exactly those it cannot:
+
+| Mutation | Removed nodes |
+| --- | --- |
+| `innerHTML = …`, `inner = …`, `textContent = …`, `replaceChild` | **released** — the script has no way to refer to them again |
+| `removeChild`, `remove` | **kept** in the document's detached pool — the DOM keeps a removed node alive and usable, so it can be re-attached |
+
+Released nodes free their C++ subtree as well as their handle, so the counters
+from `win.stats()` (`detachedNodes`, `handles`, `handleSlots`) return to their
+previous values. That is what makes the usual game pattern — rewriting a sprite
+with `innerHTML` every frame — run in constant memory; before, every replaced
+subtree stayed pooled forever and a loop writing ten nodes per frame leaked
+several megabytes per second.
+
+The one case the engine cannot see is a node the script creates and then drops
+without ever attaching it: `document.createElement("div")` parks the node in the
+pool *and* keeps its handle reachable, because the mark-sweep collector has no
+weak references, so the engine cannot tell that the script threw the handle
+away. A loop that creates elements without attaching them therefore grows the
+pool. Reuse the elements (or build the content with `innerHTML`, which releases
+what it replaces) instead of creating fresh ones per frame.
+
 ### AOT scripts (M9)
 
 Import an `.html` file that contains inline `<script lang="ts">` bodies; the
@@ -650,6 +685,19 @@ used by default; Wayland is enabled too but not yet exercised.
       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`.
+12. **M12 — node lifetime + memory** ✅
+    - What a mutation releases and what it keeps is now explicit: the
+      `innerHTML`/`inner`/`textContent`/`replaceChild` paths free the subtrees
+      they drop (`XtDocument::discard`, `domapi::discard_subtree`), while
+      `removeChild`/`remove` keep DOM semantics (`document.*`, `dom_api_*.cpp`).
+    - Handle slots are recycled with a per-slot generation, so a stale handle
+      stays inert while the table stops growing with churn (`dom_api.cpp`,
+      `gui_engine.h`).
+    - The collector's trigger follows the live set instead of only ratcheting up,
+      so a leaking or spiking program cannot spiral (`runtime/xt_alloc.c`).
+      `XT_GC_TRACE=1` reports every collection.
+    - `win.stats()` exposes the engine counters; e2e coverage in
+      `tests/e2e/gui-retention.test.ts` (see "Memory & GC").
 
 ## Progress log
 
@@ -707,6 +755,55 @@ used by default; Wayland is enabled too but not yet exercised.
   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.
+- **M12** ✅ DOM node lifetime and memory. `innerHTML`/`textContent`/
+  `replaceChild` now release the subtrees they drop instead of parking them in
+  the detached pool forever, `removeChild` keeps its documented DOM semantics,
+  handle slots are recycled with a per-slot generation so stale handles stay
+  inert, and the collector's trigger follows the live set instead of only
+  ratcheting upwards. `win.stats()` exposes the engine counters and
+  `tests/e2e/gui-retention.test.ts` pins them; a game loop rewriting its sprite
+  every frame now runs in constant memory (see "Memory & GC").
+
+## Memory & GC
+
+The engine owns most of a GUI program's memory outside the runtime heap: the DOM
+tree, the detached-node pool, the element-handle tables, the layout box tree and
+the display list are C++, so the mark-sweep collector cannot see them. `stats()`
+(see "Diagnostics") reports the parts that can grow:
+
+| Counter | Expected in a steady state |
+| --- | --- |
+| `treeNodes` | constant — the authored document |
+| `detachedRoots`, `detachedNodes` | 0, or constant for nodes the script removed itself and still holds |
+| `handles`, `handleSlots` | constant — one per element the script still refers to |
+| `listeners` | constant — one entry per element with listeners |
+| `heapBytes`, `heapAllocations` | sawtooth around the collector's threshold |
+
+Everything else is per-frame scratch (boxes, display list, vertex staging) that is
+freed before the next frame. A counter that climbs with the frame count is the
+leak signature to look for first; `tests/e2e/gui-retention.test.ts` asserts that
+the usual mutation patterns leave all of them unchanged.
+
+Two engine details matter when reading those numbers:
+
+- **What releases nodes.** `innerHTML`/`inner`/`textContent`/`replaceChild`
+  release the subtrees they drop; `removeChild`/`remove` keep them (see "Node
+  lifetime"). A game that rebuilds a sprite with `innerHTML` therefore runs in
+  constant memory.
+- **What can still accumulate.** A node created with `createElement` and never
+  attached stays in the pool, because the collector has no weak references and
+  the engine cannot tell that the script dropped its handle. The same applies to
+  a node removed and then forgotten by the script. Both are bounded by the number
+  of *live* handles, but a program that creates elements per frame without
+  attaching them grows the pool with the frame count.
+
+The collector behind `heapBytes` is a non-moving mark-sweep (`runtime/xt_alloc.c`).
+Its trigger follows the live set: after every collection the threshold becomes
+twice the surviving heap (floor 1 MiB), so a small live set means small, frequent
+collections and a bounded resident set. `XT_GC_THRESHOLD=<bytes>` pins the
+threshold instead, and `XT_GC_TRACE=1` prints one line per collection (heap and
+live-allocation counts before and after, the next trigger, and the live set by
+object kind) to stderr — that is how the DOM leak was traced to the node pool.
 
 ## Known issues
 
@@ -725,9 +822,15 @@ used by default; Wayland is enabled too but not yet exercised.
   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
+  class of use-after-free. Since the M12 node-lifetime work it has not
+  reproduced at all: 44 auto-close runs of `examples/gui/pelican-bike` (deadlines
+  800 ms–4 s, with the default, a 1 MiB and a 64 MiB collector threshold, where
+  the old report said roughly two in five) all exited cleanly, which points at
+  the same root cause — a detached-node pool and handle table that grew with the
+  frame count while the collector's threshold ratcheted up. It stays listed
+  because the archive is built per platform and the failure is timing-sensitive;
+  `tests/e2e/gui-example.test.ts` still treats either crash spelling as an
+  acceptable outcome, 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

package/doc/unimplemented.md

@@ -247,7 +247,7 @@ These features **compile and run**, but the result does not fully match ECMAScri
 
 | Item | Status |
 | --- | --- |
-| GC (garbage collection) | ✓ non-moving mark-sweep in `xt_alloc.c`, armed by a live-heap threshold (`XT_GC_THRESHOLD`) or `xt_gc_collect()`; explicit roots + root providers + conservative active-stack scan. No compaction, weak references or background collection |
+| GC (garbage collection) | ✓ non-moving mark-sweep in `xt_alloc.c`, armed by a live-heap threshold (`XT_GC_THRESHOLD` pins it) or `xt_gc_collect()`; after each collection the threshold becomes twice the surviving heap (floor 1 MiB), so the resident set follows the live set instead of only growing. `XT_GC_TRACE=1` prints one line per collection to stderr. Explicit roots + root providers + conservative active-stack scan. No compaction, weak references or background collection — without weak references an extension must keep a strong reference to every value it caches (the GUI's element handles do) |
 | Self-hosting | ✓ the compiler compiles itself: `xbintsc build src/cli/main.ts` produces a working binary, and the emitted IR is stable from generation 1 onward. The runtime is still C |
 | Type checker | ✗ only diagnostic codes are defined; no checker |
 | Full standard library | partial: Math / JSON / Date / Map / Set / RegExp / `Error` / `BigInt` / `Symbol` implemented; String.normalize / structuredClone missing |

package/doc/zh-CN/gui.md

@@ -2,7 +2,7 @@
 
 > 语言 / Language：[English](../gui.md) | **简体中文**
 
-状态：**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。
+状态：**M12** —— 功能（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 游戏）就构建在它之上。**M12** 明确了 DOM 节点生命周期（哪些变更释放、哪些保留），并让引擎内存有界：参见"节点生命周期"与"内存与 GC"。本文档记录了一个跨平台 GUI 扩展的锁定决策、架构、里程碑计划与当前进度；该扩展使用自有的 GPU 加速引擎渲染 HTML/CSS UI。
 
 ## 目标
 
@@ -161,8 +161,15 @@ win.fontMetrics(fontSize?, family?)    // { ascent, descent, lineHeight, ready }
 win.hitTest(x, y)                      // 最深的元素描述符，或 ""
 win.sendEvent(type, options?)          // 合成输入（测试用）
 win.advance(ms)                        // 推进 CSS transition 时钟（测试用）
+win.stats()                            // 引擎/运行时计数器（内存排查用）
 ```
 
+`win.stats()` 返回 `{ heapBytes, heapAllocations, treeNodes, detachedRoots,`
+`detachedNodes, handles, handleSlots, listeners }`：运行时存活堆、DOM 树规模、
+分离节点池（detached pool）以及元素句柄表。稳定状态下它们都应保持常量——若
+`detachedNodes` 或 `handles` 持续上升，说明程序移除节点的速度快于释放速度
+（见下文"节点生命周期"）。
+
 它们被 `tests/e2e/gui-*.test.ts` 用来断言解析、选择器匹配、特异性、继承、
 `!important` 与布局几何。它们在之后仍可用于调试。
 
@@ -198,6 +205,26 @@ console.log(box.contains(inner));                 // 后代判断
 旧式 `win.on(type, fn)` 负载保留其**字符串** `e.target`（`div#id.class`）；
 元素 `Event.target` 是一个句柄，其描述符与同一字符串匹配。
 
+#### 节点生命周期
+
+一次变更会决定它移除的节点是否仍可到达，引擎只释放那些确实不可到达的节点：
+
+| 变更 | 被移除的节点 |
+| --- | --- |
+| `innerHTML = …`、`inner = …`、`textContent = …`、`replaceChild` | **被释放**——脚本再也无法引用它们 |
+| `removeChild`、`remove` | **保留**在文档的分离节点池中——DOM 语义要求被移除的节点继续存活且可用，以便重新插入 |
+
+被释放的节点会同时释放其 C++ 子树与句柄，因此 `win.stats()` 的计数器
+（`detachedNodes`、`handles`、`handleSlots`）会回到先前的数值。这正是常见游戏
+写法——每帧用 `innerHTML` 重写精灵——能保持常量内存的原因；在此之前，每个被
+替换的子树都会永久留在池中，每帧写入十个节点的循环会以每秒数 MB 的速度泄漏。
+
+引擎唯一无法察觉的情况是：脚本创建了一个节点，随后从未插入就丢弃它。
+`document.createElement("div")` 会把节点放进池中，**并且**让它的句柄保持可达，
+因为标记-清扫收集器没有弱引用，引擎无法知道脚本已经丢弃了该句柄。因此，
+只创建、不插入的循环会让池持续增长。请复用元素，或用 `innerHTML` 构建内容
+（它会释放被替换的节点），而不要每帧新建元素。
+
 ### AOT 脚本（M9）
 
 导入一个包含内联 `<script lang="ts">` 主体的 `.html` 文件；加载器会把每个
@@ -574,6 +601,17 @@ xvfb-run -a --server-args="-screen 0 1280x720x24" \
       （`layout_flex.cpp`）。
     - `examples/gui/pelican-bike` 基于它实现，e2e 覆盖见
       `tests/e2e/gui-layout.test.ts`。
+12. **M12 — 节点生命周期 + 内存** ✅
+    - 明确区分变更释放与保留的内容：`innerHTML`/`inner`/`textContent`/
+      `replaceChild` 会释放被丢弃的子树（`XtDocument::discard`、
+      `domapi::discard_subtree`），而 `removeChild`/`remove` 保留 DOM 语义
+      （`document.*`、`dom_api_*.cpp`）。
+    - 句柄槽位带"每槽代次"地复用，过期句柄保持惰性失效，同时句柄表不再随
+      变更次数增长（`dom_api.cpp`、`gui_engine.h`）。
+    - 收集器触发阈值改为跟随存活集而非只升不降，避免泄漏或存活集尖峰演变成
+      内存失控（`runtime/xt_alloc.c`）。`XT_GC_TRACE=1` 会报告每次回收。
+    - `win.stats()` 暴露引擎计数器；e2e 覆盖见
+      `tests/e2e/gui-retention.test.ts`（见"内存与 GC"）。
 
 ## 进度日志
 
@@ -628,6 +666,45 @@ xvfb-run -a --server-args="-screen 0 1280x720x24" \
   在正常流内容之后布局，因此不影响它们；实现了 shrink-to-fit / 填满可用宽度
   两种规则；flex 项现在会计入外边距。e2e 覆盖在
   `tests/e2e/gui-layout.test.ts`；`examples/gui/pelican-bike` 基于它实现。
+- **M12** ✅ DOM 节点生命周期与内存。`innerHTML`/`textContent`/`replaceChild`
+  现在会释放它们丢弃的子树，而不是把它们永久留在分离节点池里；`removeChild`
+  保留其文档化的 DOM 语义；句柄槽位会带"每槽代次"地复用，使过期句柄保持惰性
+  失效；收集器的触发阈值改为跟随存活集，而不再只升不降。`win.stats()` 暴露
+  引擎计数器，`tests/e2e/gui-retention.test.ts` 对其做断言；每帧重写精灵的游戏
+  循环现在内存恒定（见"内存与 GC"）。
+
+## 内存与 GC
+
+GUI 程序的大部分内存不在运行时堆里：DOM 树、分离节点池、元素句柄表、布局盒树
+与显示列表都是 C++，标记-清扫收集器看不到它们。`stats()`（见"诊断"）报告其中
+可能增长的部分：
+
+| 计数器 | 稳定状态下的期望值 |
+| --- | --- |
+| `treeNodes` | 常量——即编写的文档 |
+| `detachedRoots`、`detachedNodes` | 0；若脚本自己移除了节点并仍持有，则为常量 |
+| `handles`、`handleSlots` | 常量——每个脚本仍引用的元素一个 |
+| `listeners` | 常量——每个注册了监听器的元素一个 |
+| `heapBytes`、`heapAllocations` | 在收集器阈值附近呈锯齿波动 |
+
+其余都是每帧用完即释放的临时数据（盒、显示列表、顶点暂存）。若某个计数器随帧数
+持续上升，那就是最该先查的泄漏特征；`tests/e2e/gui-retention.test.ts` 断言常见
+变更模式不会改变这些计数。
+
+读这些数字时有两处引擎细节需要注意：
+
+- **谁会释放节点。** `innerHTML`/`inner`/`textContent`/`replaceChild` 会释放它们
+  丢弃的子树；`removeChild`/`remove` 会保留（见"节点生命周期"）。因此用
+  `innerHTML` 每帧重建精灵的游戏内存恒定。
+- **什么仍会累积。** 用 `createElement` 创建却从未插入的节点会留在池中：收集器
+  没有弱引用，引擎无法知道脚本已丢弃其句柄。脚本移除后又不再引用的节点同理。
+  两者都以*存活句柄*数量为界，但每帧创建元素却不插入的程序会让池随帧数增长。
+
+`heapBytes` 背后的收集器是 `runtime/xt_alloc.c` 中的非移动标记-清扫。它的触发
+阈值跟随存活集：每次回收后阈值变为存活堆的 2 倍（下限 1 MiB），因此存活集小
+就意味着回收频繁而轻量、常驻内存有界。用 `XT_GC_THRESHOLD=<bytes>` 可以固定
+阈值；`XT_GC_TRACE=1` 会为每次回收向 stderr 打印一行（回收前后的堆与存活分配数、
+下一次触发阈值，以及按对象类型统计的存活集）——DOM 泄漏正是这样被定位到节点池的。
 
 ## 已知问题
 
@@ -635,7 +712,15 @@ xvfb-run -a --server-args="-screen 0 1280x720x24" \
   访问违例（`0xC0000005`）退出，其余运行与正常退出无异。该问题只在**动画帧循环运行中**复现
   （静态文档可以正常关闭），且**不是示例游戏自身**的代码：没有任何异常信息，崩溃多发生在
   启动后一秒内、与截止时间无关，而提高 `XT_GC_THRESHOLD` 可以掩盖它，因此看起来是
-  GC/析构竞态。交互式运行（不设自动关闭）可稳定运行数分钟。`tests/e2e/gui-example.test.ts`
+  GC/析构竞态。交互式运行（不设自动关闭）可稳定运行数分钟。此前的一个已知成因是引擎在标记-清扫
+  收集器看不见的 C++ 容器里缓存 `xt_value`（AOT `<script>` 注册表、元素句柄、元素监听器、
+  排队/正在运行的 `requestAnimationFrame` 回调），现在它们由 GC 根提供者标记
+  （`xt_gui_script_gc_scan` 与 `xt_gui_gc_scan_roots`），该类 use-after-free 已消除。
+  在 M12 的节点生命周期改动之后它已完全无法复现：对
+  `examples/gui/pelican-bike` 做了 44 次自动关闭运行（截止 800 ms–4 s，分别使用默认、
+  1 MiB 与 64 MiB 的收集阈值，而旧记录称约五次两次崩溃），全部正常退出，指向与内存问题
+  相同的根因——分离节点池与句柄表随帧数增长，同时收集器阈值只升不降。此处仍保留该条目，
+  因为该归档按平台构建且故障与时机相关。`tests/e2e/gui-example.test.ts`
   因此把该退出码视为可接受结果，行为断言放在不依赖 GPU 的
   `tests/e2e/gui-example-browser.test.ts` 中。
 - **`display: none -> flex` 的重排。** 通过类名切换让隐藏元素显示在 flex 容器上时，也曾观察

package/doc/zh-CN/post/xbintsc-build-pelican.md

@@ -0,0 +1,31 @@
+# 使用xbintsc编译了一款小游戏的体验
+起因想要用TS/JS做一个桌面端小游戏，但选择框架的时候，但是发现并没有一个很好的选择。
+1. Electron 过于庞大，内部集成了node.js和chrome谷歌浏览器
+2. Tauri 虽然客户端小，但是使用系统自带的 WebView 渲染，会导致不同机器运行结果不一致
+
+于是我准备使用xbintsc,去编译这款桌面小游戏。
+
+首先xbintsc优势：
+1. 构建体积小，最小可达200kb，编译可选node扩展(支持部分node.js的API)最小可达300kb，编译可选GUI扩展(可视化界面HTML渲染)最小可达3MB
+2. 冷启动速度是node.js的120倍+，且原生支持HTML+CSS渲染。
+3. 全平台支持(使用LLVM构建不同平台二进制产物，使用GPU的SDL进行渲染并在不同平台使用Vulkan/Metal进行编译)
+
+直接让AI开发了鹈鹕骑车小游戏，并使用xbintsc编译了，截图如下：
+![鹈鹕骑车小游戏截图](./pelican-bike.png)
+
+编译后的结果大概是5M左右，运行效果很流畅，当然直接打开源码的HTML也可以直接玩。
+
+小游戏源码地址：[https://github.com/zy445566/xbintsc/tree/main/examples/gui/pelican-bike](https://github.com/zy445566/xbintsc/tree/main/examples/gui/pelican-bike)
+
+当然有兴趣下载鹈鹕骑车小游戏编译结果，也编译了多个不同平台windows/mac/ubutun26+的版本。
+
+编译结果地址：[https://github.com/zy445566/xbintsc/releases/tag/v0.3.65](https://github.com/zy445566/xbintsc/releases/tag/v0.3.65)
+
+选择pelican-bike-demo-v0.3.65-multi-platform.zip下载，解压后选择自己的平台就能运行。
+
+由于该游戏目前没有做签名，所以可能会有系统的安全性拦截。
+macOS 打开后需要：打开“系统设置” → “隐私与安全性”，向下滚动到“安全性”，选择“仍要打开”运行。
+Windows 打开后，如出现“Windows 已保护你的电脑”，点击“更多信息”，点击“仍要运行”。
+
+
+大家有兴趣，也可以用xbintsc编译一款自己的小游戏，甚至可以跟Ai Agent说“用xbintsc(https://github.com/zy445566/xbintsc)帮我生成一个鹈鹕骑车小游戏”

package/doc/zh-CN/unimplemented.md

@@ -211,7 +211,7 @@
 
 | 项 | 现状 |
 | --- | --- |
-| GC（垃圾回收） | ✓ `xt_alloc.c` 中的非移动标记-清扫，按存活堆阈值（`XT_GC_THRESHOLD`）或 `xt_gc_collect()` 触发；显式根 + 根提供者 + 保守活动栈扫描。无压缩、弱引用或后台回收 |
+| GC（垃圾回收） | ✓ `xt_alloc.c` 中的非移动标记-清扫，按存活堆阈值（`XT_GC_THRESHOLD` 可固定该阈值）或 `xt_gc_collect()` 触发；每次回收后阈值变为存活堆的 2 倍（下限 1 MiB），因此常驻内存跟随存活集而不是只增不减；`XT_GC_TRACE=1` 会为每次回收向 stderr 打印一行统计。显式根 + 根提供者 + 保守活动栈扫描。无压缩、弱引用或后台回收（缺少弱引用意味着扩展必须对它缓存的每个值做强引用，例如 GUI 的元素句柄） |
 | 自举（self-hosting） | ✓ 编译器已能自编译：`xbintsc build src/cli/main.ts` 可产出可用二进制，且从第 1 代起产出的 IR 保持稳定。运行时仍为 C |
 | 类型检查器 | ✗ 仅定义诊断码，无 checker |
 | 完整标准库 | 部分：Math / JSON / Date / Map / Set / RegExp / `Error` / `BigInt` / `Symbol` 已实现；String.normalize / structuredClone 缺失 |

package/package.json

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

package/runtime/ext_gui/document.cpp

@@ -351,4 +351,31 @@ void XtDocument::detach(Node *node) {
   invalidate();
 }
 
+void XtDocument::discard(Node *node) {
+  if (node == nullptr || node == root_.get()) return;
+  auto it = detached_.find(node);
+  if (it == detached_.end()) return;
+  /* Children are owned by their parent, never by the pool (takeNode erases the
+   * pool entry when a node is attached), so dropping the root drops it all. */
+  detached_.erase(it);
+}
+
+namespace {
+
+size_t countSubtree(const Node *node) {
+  size_t total = 1;
+  for (const std::unique_ptr<Node> &child : node->children) total += countSubtree(child.get());
+  return total;
+}
+
+}  // namespace
+
+size_t XtDocument::treeNodeCount() const { return root_ == nullptr ? 0 : countSubtree(root_.get()); }
+
+size_t XtDocument::detachedNodeCount() const {
+  size_t total = 0;
+  for (const auto &entry : detached_) total += countSubtree(entry.second.get());
+  return total;
+}
+
 }  // namespace xtgui

package/runtime/ext_gui/document.h

@@ -75,6 +75,18 @@ class XtDocument {
   Node *replaceChild(Node *parent, Node *newChild, Node *oldChild);
   /** Release a node from the document entirely (still owned, detached). */
   void detach(Node *node);
+  /** Free a detached node and its subtree. The caller must already have
+   * forgotten every handle in that subtree (see `domapi::discard_subtree`), so
+   * no slot is left pointing at freed memory. Nodes still attached to the tree
+   * are ignored: use `removeChild`/`detach` for those. */
+  void discard(Node *node);
+
+  /** Nodes in the document tree (diagnostics). */
+  size_t treeNodeCount() const;
+  /** Nodes held by the detached pool, subtrees included (diagnostics). */
+  size_t detachedNodeCount() const;
+  /** Top-level entries in the detached pool (diagnostics). */
+  size_t detachedRootCount() const { return detached_.size(); }
 
   /** Mark the document as needing a restyle/relayout before the next paint. */
   void invalidate() { dirty_ = true; }

package/runtime/ext_gui/dom_api.cpp

@@ -64,7 +64,13 @@ xtgui::Node *resolve_node(xt_value self, XtGuiWindow **winOut) {
   if (!XT_IS_NUMBER(index)) return nullptr;
   int slot = (int)xt_to_number(index);
   if (slot < 0 || slot >= (int)win->node_order.size()) return nullptr;
-  return win->node_order[(size_t)slot];
+  /* A recycled slot must not answer for the handle that used to own it. */
+  xt_value generation = xt_object_get_cstr(self, "__xt_gui_slot_gen");
+  if (!XT_IS_NUMBER(generation) ||
+      (int)xt_to_number(generation) != win->node_order[(size_t)slot].generation) {
+    return nullptr;
+  }
+  return const_cast<xtgui::Node *>(win->node_order[(size_t)slot].node);
 }
 
 void mark_dirty(XtGuiWindow *win) {
@@ -123,15 +129,26 @@ xt_value xt_gui_node_handle(XtGuiWindow *win, const xtgui::Node *node) {
   auto found = win->node_index.find(node);
   if (found != win->node_index.end()) {
     slot = found->second;
+  } else if (!win->free_node_slots.empty()) {
+    /* Reuse a forgotten slot instead of growing the table forever. The
+     * generation bump below makes the handle that used to own it inert. */
+    slot = win->free_node_slots.back();
+    win->free_node_slots.pop_back();
+    win->node_order[(size_t)slot].node = node;
+    win->node_index[node] = slot;
   } else {
     slot = (int)win->node_order.size();
-    win->node_order.push_back(const_cast<xtgui::Node *>(node));
+    XtGuiNodeSlot entry;
+    entry.node = node;
+    win->node_order.push_back(entry);
     win->node_index[node] = slot;
   }
   xt_value handle = xt_object_new_with_proto(domapi::node_proto());
   xt_object_set(handle, xt_string_from_cstr("__xt_gui_win"), win->object);
   xt_object_set(handle, xt_string_from_cstr("__xt_gui_gen"), xt_number(win->doc_generation));
   xt_object_set(handle, xt_string_from_cstr("__xt_gui_node"), xt_number((double)slot));
+  xt_object_set(handle, xt_string_from_cstr("__xt_gui_slot_gen"),
+                xt_number((double)win->node_order[(size_t)slot].generation));
   win->node_handles[node] = handle;
   return handle;
 }
@@ -143,18 +160,36 @@ void xt_gui_node_handle_forget(XtGuiWindow *win, const xtgui::Node *node) {
    * `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. */
+   * behaviour — the generation bump makes the recycled slot unavailable to
+   * them. */
   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_order[(size_t)slot].node = nullptr;
+      win->node_order[(size_t)slot].generation++;
+      win->free_node_slots.push_back(slot);
     }
     win->node_index.erase(index);
   }
   win->node_handles.erase(node);
 }
 
+/** Forget the handles of `node` and every descendant. Runs before the subtree
+ * is freed, so the walk still reads live children. */
+static void forget_subtree_handles(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_handles(win, child.get());
+  }
+}
+
+void domapi::discard_subtree(XtGuiWindow *win, xtgui::Node *node) {
+  if (win == nullptr || node == nullptr || win->document == nullptr) return;
+  forget_subtree_handles(win, node);
+  win->document->discard(node);
+}
+
 xt_value xt_gui_document_handle(XtGuiWindow *win) {
   if (win == nullptr) return XT_UNDEFINED;
   if (!XT_IS_OBJECT(win->document_object)) {
@@ -172,6 +207,7 @@ void xt_gui_handles_reset(XtGuiWindow *win) {
   if (win == nullptr) return;
   win->doc_generation += 1.0;
   win->node_order.clear();
+  win->free_node_slots.clear();
   win->node_index.clear();
   win->node_handles.clear();
   win->node_listeners.clear();

package/runtime/ext_gui/dom_api_internal.h

@@ -49,6 +49,12 @@ std::string class_name_of(const xtgui::Node *node);
 void set_class_name(XtGuiWindow *win, xtgui::Node *node, const std::string &value);
 void remove_listener(XtGuiWindow *win, xtgui::Node *node, const std::string &type, xt_value fn,
                      bool capture);
+/** Forget the handles of `node` and its descendants, then free the subtree from
+ * the document's detached pool. Use this only for nodes the script can no longer
+ * reach (the children `innerHTML = …` replaces, the node `replaceChild` drops):
+ * an existing handle then resolves to "stale" and no-ops, exactly like a handle
+ * to a node the document already removed and released. */
+void discard_subtree(XtGuiWindow *win, xtgui::Node *node);
 
 /* -- method definitions (uniform `(self, env, argc, argv)` ABI) ----------- */
 

package/runtime/ext_gui/dom_api_node.cpp

@@ -177,9 +177,13 @@ 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;
-  /* `replaceChild` frees the node it replaces, so its slot may not survive. */
+  /* `replaceChild` does not give the replaced node back to the script: the
+   * engine drops it (and its subtree) outright, so its handle may not survive.
+   * A null result means nothing was replaced (the old node was not a child of
+   * `node`, or the move was refused), and then the old node is still live and
+   * must keep its handle. */
   xtgui::Node *replaced = win->document->replaceChild(node, newChild, oldChild);
-  if (replaced != oldChild) xt_gui_node_handle_forget(win, oldChild);
+  if (replaced != nullptr && replaced != oldChild) discard_subtree(win, oldChild);
   return xt_gui_node_handle(win, replaced);
 }
 

package/runtime/ext_gui/dom_api_node_read.cpp

@@ -25,13 +25,6 @@ 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) {
@@ -112,7 +105,10 @@ 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);
+  /* The replaced children are unreachable now: `removeChild` only parks them in
+   * the detached pool, and this setter is what drops them. Forgetting their
+   * handles without releasing them would leak a node per write. */
+  for (xtgui::Node *child : existing) discard_subtree(win, child);
   if (!text.empty()) node->addText(text);
   mark_dirty(win);
   return XT_UNDEFINED;
@@ -140,10 +136,12 @@ 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);
+  /* The old children are dropped here: `removeChild` only parks them in the
+   * detached pool (so a script that detached a node itself can re-append it),
+   * and replacing them wholesale is what releases them. Forgetting their
+   * handles without releasing the nodes would leak one subtree per assignment —
+   * a per-frame `innerHTML` write in a game loop then grows without bound. */
+  for (xtgui::Node *child : existing) discard_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_engine.h

@@ -55,6 +55,15 @@ struct XtGuiAnimationFrame {
   xt_value fn;
 };
 
+/** One row of the window's node table: the node a handle addresses, plus the
+ * generation that row was issued for. A slot is recycled after its node is
+ * forgotten, and the generation is what keeps an old handle from resolving
+ * through the recycled slot to an unrelated node. */
+struct XtGuiNodeSlot {
+  const xtgui::Node *node = nullptr;
+  int generation = 0;
+};
+
 /* One live window. `object` is the JavaScript-visible handle; the record is
  * addressed from it through the hidden `__xt_gui_index` property. */
 struct XtGuiWindow {
@@ -78,7 +87,9 @@ struct XtGuiWindow {
   /** Bumped on every `loadHTML`; stale handles no-op. */
   double doc_generation = 1.0;
   /** Node -> table index / cached handle, so identity is stable. */
-  std::vector<xtgui::Node *> node_order;
+  std::vector<XtGuiNodeSlot> node_order;
+  /** Slots whose node was forgotten and which a later handle may reuse. */
+  std::vector<int> free_node_slots;
   std::unordered_map<const xtgui::Node *, int> node_index;
   std::unordered_map<const xtgui::Node *, xt_value> node_handles;
   /** Element-level listeners, keyed by node. */

package/runtime/ext_gui/window.cpp

@@ -461,6 +461,40 @@ static xt_value win_send_event(xt_value self, xt_value env, int32_t argc, xt_val
   return XT_TRUE;
 }
 
+/** Diagnostic/test hook: engine counters as one object. `heapBytes` and
+ * `heapAllocations` are the live runtime heap, `treeNodes`/`detachedNodes` the
+ * DOM tree and the detached pool, and `handles`/`listeners` the element-handle
+ * tables. `detachedNodes` should stay flat in a steady state: a climbing value
+ * means the program keeps removing nodes faster than it releases them. */
+static xt_value win_stats(xt_value self, xt_value env, int32_t argc, xt_value *argv) {
+  (void)env;
+  (void)argc;
+  (void)argv;
+  XtGuiWindow *win = xt_gui_window_from_this(self);
+  xt_value object = xt_object_new();
+  xt_object_set(object, xt_string_from_cstr("heapBytes"), xt_number((double)xt_heap_bytes()));
+  xt_object_set(object, xt_string_from_cstr("heapAllocations"),
+                xt_number((double)xt_heap_allocations()));
+  double tree_nodes = 0;
+  double detached_roots = 0;
+  double detached_nodes = 0;
+  if (win != nullptr && win->document != nullptr) {
+    tree_nodes = (double)win->document->treeNodeCount();
+    detached_roots = (double)win->document->detachedRootCount();
+    detached_nodes = (double)win->document->detachedNodeCount();
+  }
+  xt_object_set(object, xt_string_from_cstr("treeNodes"), xt_number(tree_nodes));
+  xt_object_set(object, xt_string_from_cstr("detachedRoots"), xt_number(detached_roots));
+  xt_object_set(object, xt_string_from_cstr("detachedNodes"), xt_number(detached_nodes));
+  xt_object_set(object, xt_string_from_cstr("handles"),
+                xt_number(win != nullptr ? (double)win->node_handles.size() : 0));
+  xt_object_set(object, xt_string_from_cstr("handleSlots"),
+                xt_number(win != nullptr ? (double)win->node_order.size() : 0));
+  xt_object_set(object, xt_string_from_cstr("listeners"),
+                xt_number(win != nullptr ? (double)win->node_listeners.size() : 0));
+  return object;
+}
+
 /* -- prototype ------------------------------------------------------------ */
 
 static void define_method(xt_value proto, const char *name, void *fn) {
@@ -505,6 +539,7 @@ xt_value xt_gui_window_proto(void) {
   define_method(proto, "removeEventListener", (void *)win_remove_event_listener);
   define_method(proto, "hitTest", (void *)win_hit_test);
   define_method(proto, "sendEvent", (void *)win_send_event);
+  define_method(proto, "stats", (void *)win_stats);
   g_window_proto = proto;
   return proto;
 }

package/runtime/xt_alloc.c

@@ -47,6 +47,19 @@ static int g_gc_threshold_pinned = 0;
 static size_t g_gc_threshold = (size_t)16 << 20; /* 16 MiB */
 #define XT_GC_MIN_THRESHOLD ((size_t)1 << 20)
 
+/* `XT_GC_TRACE=1` prints one line per collection (live bytes, allocation count
+ * and the next trigger) to stderr, for diagnosing heap growth. */
+static int g_gc_trace = -1;
+static size_t g_gc_collections = 0;
+
+static int xt_gc_trace_enabled(void) {
+  if (g_gc_trace < 0) {
+    const char *env = getenv("XT_GC_TRACE");
+    g_gc_trace = (env != NULL && env[0] != '\0' && env[0] != '0') ? 1 : 0;
+  }
+  return g_gc_trace;
+}
+
 /* ------------------------------------------------------------------------- */
 /* Roots                                                                     */
 /* ------------------------------------------------------------------------- */
@@ -441,6 +454,9 @@ void xt_gc_collect(void) {
   if (g_gc_running) return;
   if (!g_gc_initialised) xt_gc_init();
   g_gc_running = 1;
+  const int trace = xt_gc_trace_enabled();
+  const size_t heap_before = g_heap_bytes;
+  const size_t allocations_before = g_heap_allocations;
 
   xt_gc_table_build();
   xt_gc_mark_roots();
@@ -451,11 +467,22 @@ void xt_gc_collect(void) {
 
   xt_header **link = &g_heap_head;
   xt_header *header = g_heap_head;
+  size_t live_by_kind[16];
+  size_t bytes_by_kind[16];
+  for (int i = 0; i < 16; i++) {
+    live_by_kind[i] = 0;
+    bytes_by_kind[i] = 0;
+  }
   while (header) {
     xt_header *next = header->gc_next;
     if (header->flags & XT_GC_MARK) {
       header->flags &= (uint8_t)~XT_GC_MARK;
       link = &header->gc_next;
+      if (trace) {
+        size_t kind = header->kind < 16 ? header->kind : 0;
+        live_by_kind[kind]++;
+        bytes_by_kind[kind] += header->size;
+      }
     } else {
       *link = next;
       g_heap_bytes -= header->size;
@@ -469,7 +496,33 @@ void xt_gc_collect(void) {
   g_gc_running = 0;
 
   if (!g_gc_threshold_pinned) {
-    if (g_gc_threshold < g_heap_bytes * 2) g_gc_threshold = g_heap_bytes * 2;
-    if (g_gc_threshold < XT_GC_MIN_THRESHOLD) g_gc_threshold = XT_GC_MIN_THRESHOLD;
+    /* Follow the live set: twice the surviving heap is the headroom a
+     * mark-sweep wants between collections, and the floor keeps a tiny heap
+     * from collecting on nearly every allocation.
+     *
+     * The threshold must *shrink* again, not just ratchet upwards. A doubling
+     * threshold with a monotonic floor turns any transient growth of the live
+     * set into exponentially rarer collections: each sweep only reclaims the
+     * newly dead part of a larger heap, so the heap (and with it the resident
+     * set) grows without bound. A GUI program that keeps a few extra nodes
+     * alive for one frame is enough to start that spiral. */
+    size_t next = g_heap_bytes * 2;
+    if (next < XT_GC_MIN_THRESHOLD) next = XT_GC_MIN_THRESHOLD;
+    g_gc_threshold = next;
+  }
+
+  g_gc_collections++;
+  if (trace) {
+    fprintf(stderr,
+            "xt_gc: #%zu heap %zu -> %zu bytes, allocations %zu -> %zu, next trigger %zu\n",
+            g_gc_collections, heap_before, g_heap_bytes, allocations_before, g_heap_allocations,
+            g_gc_threshold);
+    fprintf(stderr, "xt_gc:   live kinds");
+    for (int i = 1; i < 16; i++) {
+      if (live_by_kind[i] != 0) {
+        fprintf(stderr, " %d:%zu/%zuB", i, live_by_kind[i], bytes_by_kind[i]);
+      }
+    }
+    fprintf(stderr, "\n");
   }
 }