xbintsc 0.3.68 → 0.3.79

package/doc/ai/extensions.md

@@ -67,10 +67,23 @@ import { createWindow, run } from "gui";
 
 It is a self-contained GPU-accelerated renderer (own HTML parser, CSS cascade,
 layout and compositor) — not a system WebView. It ships as a per-platform
-prebuilt `gui.a`/`gui.lib` because it is C++. If that archive is missing for
+prebuilt `gui.a`/`gui.lib` because it is C++. `<img>`, `<video>` and `<audio>`
+really decode: a minimal static FFmpeg is bundled into the archive, and the DOM
+media API (`play`/`pause`/`currentTime`/`volume`/…) plus the
+`loadedmetadata`/`play`/`pause`/`ended`/`timeupdate`/`error` events let a
+program drive playback. There are no built-in controls — draw your own chrome
+with elements and CSS (see `examples/gui/media.ts`). Video frames and audio PCM
+are decoded on the main thread. `<canvas>` is supported too: `getContext("2d")`
+returns a context whose fills, paths, text and `drawImage` are rasterised by a
+self-written CPU rasteriser, and element handles expose `canvas` drawing plus
+`width`/`height`. If that archive is missing for
 your platform, the build fails with an actionable message; design and roadmap
-live in [../gui.md](../gui.md), and the scripting surface in
-[../gui-scripts.md](../gui-scripts.md).
+live in [../gui.md](../gui.md) (overview; the engine is documented by function
+under [`doc/gui/`](../gui/)), and the scripting surface in
+[../gui-scripts.md](../gui-scripts.md). Media playback is the one part that
+Windows does not get: the Windows `gui.a` is built without FFmpeg and media
+slots are inert. See [../gui/canvas.md](../gui/canvas.md) for the canvas API and
+its limits.
 
 ## Third-party npm packages
 

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

@@ -64,9 +64,16 @@ import { createWindow, run } from "gui";
 ```
 
 它是自带渲染引擎的 GPU 加速实现（自己的 HTML 解析器、CSS 级联、布局与合成器），不是
-系统 WebView。因为主体是 C++，它以各平台预编译的 `gui.a`/`gui.lib` 形式分发。如果该
-平台的归档不存在，构建会以明确的提示失败；设计与路线图见 [../../zh-CN/gui.md](../../zh-CN/gui.md)，
-脚本接口见 [../../zh-CN/gui-scripts.md](../../zh-CN/gui-scripts.md)。
+系统 WebView。`<img>`、`<video>`、`<audio>` 都是真正解码：归档内打入一个最小化的
+静态 FFmpeg，DOM 媒体 API（`play`/`pause`/`currentTime`/`volume`/…）与
+`loadedmetadata`/`play`/`pause`/`ended`/`timeupdate`/`error` 事件可让程序驱动播放。
+没有内置控件——用元素和 CSS 自绘控件（见 `examples/gui/media.ts`）；视频帧与音频 PCM
+都在主线程解码。也支持 `<canvas>`：`getContext("2d")` 返回的上下文，其填充、路径、
+文本与 `drawImage` 由自研 CPU 光栅器处理，元素句柄还暴露 `width`/`height`。因为主体是 C++，它以各平台预编译的 `gui.a`/`gui.lib` 形式分发。如果该
+平台的归档不存在，构建会以明确的提示失败；设计与路线图见 [../../zh-CN/gui.md](../../zh-CN/gui.md)（总览；引擎按功能拆分在 [`doc/zh-CN/gui/`](../../zh-CN/gui/) 下），
+脚本接口见 [../../zh-CN/gui-scripts.md](../../zh-CN/gui-scripts.md)。媒体播放是
+Windows 唯一不支持的：Windows 的 `gui.a` 不构建 FFmpeg，媒体槽位为空操作。Canvas API
+及其限制见 [../../zh-CN/gui/canvas.md](../../zh-CN/gui/canvas.md)。
 
 ## 第三方 npm 包
 

package/doc/gui/animation.md

@@ -0,0 +1,46 @@
+# Animation: frames and transitions
+
+> Part of the [GUI extension](../gui.md); the engine overview, locked
+> decisions and roadmap live there.
+
+## Animation frames (M10)
+
+`requestAnimationFrame` runs a callback once on the next frame; the callback
+receives the frame timestamp (ms) and may mutate the DOM, which is restyled and
+repainted in the same frame. Re-queue from inside the callback to animate:
+
+```ts
+const win = createWindow({ title: "anim", width: 320, height: 240 });
+let n = 0;
+const tick = (t: number) => {
+  win.document.getElementById("label").textContent = String(n++);
+  if (n < 120) win.requestAnimationFrame(tick); // id returned; cancelAnimationFrame(id) drops it
+};
+win.on("ready", () => win.requestAnimationFrame(tick));
+win.loadHTML("<div id='label'>0</div>");
+run();
+```
+
+## CSS transitions (M6b)
+
+`XtDocument` runs CSS transitions between the *target* computed styles (the
+cascade for the current `:hover`/`:focus` state) and the *displayed* styles used
+for layout and paint. When a state change alters a transitioned property, a
+running transition is recorded and re-applied every frame until it finishes;
+the engine advances the clock with real frame deltas (`XtDocument::advance`),
+and `win.advance(ms)` lets tests step it deterministically.
+
+- Supported properties: `background-color`, `color`, `border-color`,
+  `border-radius`; `transition: all` covers them. Structural/layout-affecting
+  properties are not animated yet (that would relayout every frame).
+- Both the `transition` shorthand and the `transition-property` / `-duration` /
+  `-delay` / `-timing-function` longhands are parsed; time values accept `s` and
+  `ms`; timing functions are `linear`, `ease`, `ease-in`, `ease-out` and
+  `ease-in-out` (`ease` is a smoothstep approximation).
+- Retargeting mid-flight starts a new transition from the current interpolated
+  value, so reversing a hover animates smoothly from wherever it was.
+- `computedStyle()` reports the displayed (interpolated) value, so transitions
+  are directly observable in tests.
+
+Still to do for animation: `@keyframes` animations and `cubic-bezier(...)`.
+

package/doc/gui/api.md

@@ -0,0 +1,92 @@
+# GUI API
+
+> Part of the [GUI extension](../gui.md); the engine overview, locked
+> decisions and roadmap live there.
+
+## TS-facing API
+
+```ts
+import { createWindow, run, quit } from "gui";
+
+const win = createWindow({ title: "Demo", width: 900, height: 600 });
+win.setBackground("#14161c");
+win.loadHTML(INDEX_HTML);              // parses HTML/CSS and computes styles
+win.on("ready", () => console.log("first frame presented"));
+win.on("close", () => console.log("window closed"));
+
+run();                                 // drives the main loop until all windows close
+```
+
+Methods implemented on a window handle: `setTitle` / `setSize` / `loadHTML` /
+`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). The Web spellings are available
+too: `addEventListener` / `removeEventListener` are aliases of `on` / `off` (their
+`options` argument is accepted and ignored) and the `closed` getter mirrors
+`isOpen()`, so a document written against the browser API runs unchanged.
+Events emitted:
+`ready` (after the first presented frame), `load`, `close`, `resize` 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
+win.on("click", (e) => console.log(e.x, e.y, e.button, e.target));
+win.on("wheel", (e) => console.log(e.deltaX, e.deltaY));
+win.on("keydown", (e) => console.log(e.key, e.code, e.ctrl, e.shift, e.alt, e.meta));
+```
+
+| Field | Events | Meaning |
+| --- | --- | --- |
+| `x`, `y` / `clientX`, `clientY` | pointer, wheel | viewport-relative logical pixels |
+| `button` | pointer | `0` left, `1` middle, `2` right (`-1` for move) |
+| `clicks` | pointer | click count reported by the OS |
+| `deltaX`, `deltaY` | wheel | scroll amount (`deltaY` positive = down) |
+| `key`, `code` | keyboard | key name and physical scancode name |
+| `repeat`, `ctrl`, `shift`, `alt`, `meta` | keyboard | modifiers |
+| `target` | pointer, wheel | deepest element under the point as a CSS-like descriptor (`div#main.card`), or absent |
+
+## Diagnostics
+
+So the HTML/CSS/paint pipeline is testable without a GPU, a window handle
+exposes read-only hooks:
+
+```ts
+win.computedStyle(selector, property)  // e.g. ("#main", "width") -> "60%"
+win.queryCount(selector)               // number of matching elements
+win.getBoundingClientRect(selector)    // { x, y, width, height } (border box)
+win.documentTree()                     // serialized DOM (debugging)
+win.layoutTree()                       // serialized layout boxes (debugging)
+win.paintCount()                       // number of shapes in the display list
+win.paintList()                        // serialized display list (debugging)
+win.measureText(text, fontSize?, family?)  // shaped advance width in pixels
+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](./dom.md#node-lifetime)).
+
+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.
+
+## Multiple windows
+
+Multiple windows fall out of the object model: `createWindow` returns a native
+object handle; each handle owns its own `SDL_Window`/GPU surface and its own DOM
+tree. `run()` drives one shared main loop that ticks every window and exits when
+the last one closes.

package/doc/gui/build.md

@@ -0,0 +1,91 @@
+# Packaging and build
+
+> Part of the [GUI extension](../gui.md); the engine overview, locked
+> decisions and roadmap live there.
+
+- Sources live in `runtime/ext_gui/` (C/C++) plus vendored libs under `vendor/`
+  (gitignored; fetched on demand).
+- `npm run gui` (`scripts/build-gui.ts`) fetches a pinned SDL3 (`SDL3_TAG`,
+  default `release-3.2.10`), builds a static SDL3, fetches and builds static
+  FreeType (`FREETYPE_VERSION`) and HarfBuzz (`HARFBUZZ_VERSION`), compiles the
+  engine and merges everything into `runtime/lib/<os>-<arch>/gui.a` (or
+  `gui.lib` with the MSVC ABI on Windows), same convention as `core.a`,
+  statically bundling all three. It also fetches, configures and builds a
+  minimal static **FFmpeg** (`FFMPEG_VERSION`, default `7.1`) with only the
+  demuxers/parsers/decoders the media elements need and merges those archives
+  into `gui.a`, defining `XT_GUI_WITH_FFMPEG` for the engine. The merge uses
+  `libtool` on macOS and `ar -M` (GNU/LLVM) elsewhere; CMake archives are
+  discovered under the build root or `Release/` for either generator style.
+- `src/extensions/gui/index.ts` exposes the archive through `nativeObjects()`
+  (via `findRuntimeLibrary`, so `.a`/`.lib` both work) and the OS frameworks
+  through `linkerFlags()`.
+- CI builds `gui.a` before assembling the release archive so it ships inside
+  `runtime/lib/<slug>/` (the release tarball copies the whole `runtime/` tree).
+  The archive is built and the example is run on Linux (under Xvfb, with the
+  lavapipe software Vulkan driver) and macOS; Windows is provisional.
+- The existing cache fingerprint already hashes `nativeObjects()` contents, so
+  rebuilding `gui.a` invalidates cached binaries automatically.
+- CMake build trees live *next to* their sources (`vendor/sdl-build`,
+  `vendor/freetype-build`, `vendor/harfbuzz-build`), never inside them: a
+  `CMakeCache.txt` records the machine it was configured on, and SDL's video
+  backends are `option()`s, so the first configure to run wins. A cached
+  `vendor/SDL` tree that also carried `build/` therefore restored one machine's
+  `SDL_X11`/`SDL_WAYLAND` choices into another's configure — SDL then aborts
+  with "SDL could not find X11 or Wayland development libraries" even though the
+  headers are installed. The CI cache is keyed per OS/arch and omits the build
+  trees; `npm run gui` also checks the X11/Wayland headers up front on
+  Debian/Ubuntu and reports the missing development packages by name (set
+  `xbintsc_SKIP_HEADER_CHECK=1` when they live under a prefix that check does
+  not know).
+
+## Running the example
+
+```sh
+npm run runtime      # rebuild core.a after a runtime change
+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.
+
+`media.ts` (with `media.html`) demonstrates `<video>`/`<audio>`: it overlays a
+CSS progress bar on the video and drives playback with `play()` / `pause()` /
+`currentTime` / `volume`. Media `src` paths resolve relative to the process
+working directory, so run it from the repository root:
+`xbintsc run examples/gui/media.ts --ext gui`.
+
+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:
+
+```sh
+sudo sh scripts/install-gui-deps.sh   # clang, cmake, X11/Wayland headers, Vulkan, Xvfb
+npm run runtime && npm run gui
+xvfb-run -a --server-args="-screen 0 1280x720x24" \
+  npx tsx src/cli/main.ts run examples/gui/hello.ts --ext gui
+```
+
+`scripts/install-gui-deps.sh` holds the package list (`apt-get install -y clang
+cmake libx11-dev libxext-dev libxrandr-dev libxcursor-dev libxi-dev
+libxinerama-dev libxfixes-dev libxkbcommon-dev libwayland-dev wayland-protocols
+libdecor-0-dev libasound2-dev libpulse-dev libdbus-1-dev libudev-dev libdrm-dev
+libgbm-dev libgl1-mesa-dev libegl1-mesa-dev libvulkan-dev mesa-vulkan-drivers
+xvfb`) so that every Linux job which builds `gui.a` installs the same set: the
+X11 backend is used by default, Wayland is enabled too but not yet exercised.
+Install it before `npm run gui` anywhere the archive is built — SDL3 cannot
+find a window backend without those headers.
+

package/doc/gui/canvas.md

@@ -0,0 +1,98 @@
+# Canvas: `<canvas>` and the 2D context (M14)
+
+> Part of the [GUI extension](../gui.md); the engine overview, locked
+> decisions and roadmap live there.
+
+`<canvas>` is a **replaced element** laid out like `<img>`: its intrinsic size
+comes from the `width`/`height` attributes (default `300x150`, the CSS default
+canvas size), an explicit CSS `width`/`height` wins, and the aspect ratio is
+preserved when only one axis is constrained. Paint emits one `PaintImage` per
+canvas, carrying a `canvas_id` instead of a `src`/`media_id`; the renderer
+uploads the bitmap to an RGBA texture through the same image path as bitmaps and
+video frames (`renderer_image.cpp`), so the GPU scales it into the CSS box.
+
+The engine-side object is `xtgui::Canvas2D`
+(`runtime/ext_gui/canvas.{h,cpp}`) — one RGBA8 bitmap plus the 2D drawing state.
+The rasteriser lives in `canvas_raster.cpp`; the DOM bindings live in
+`dom_api_canvas.cpp`, and the per-window lifetime in `gui_canvas.cpp`.
+
+## Getting a context
+
+```ts
+const canvas: any = document.getElementById("c");
+const ctx = canvas.getContext("2d"); // or null for any other context kind
+```
+
+`getContext("2d")` returns a context handle whose methods and accessors live on
+a shared prototype. The handle is cached on the element, so every call returns
+the **same** object and the drawing state (transform, styles, path) is per
+canvas, not per call. `ctx.canvas` is the owning element handle.
+
+## Drawing model
+
+The rasteriser is deliberately small and self-written (no Skia/Cairo). It
+anti-aliases with **4 vertical sub-scanlines** per pixel row and an **analytic
+horizontal coverage** pass, and fills paths with the **non-zero winding rule**
+(so `arc`-shaped holes work when wound the other way). An axis-aligned rectangle
+(`b == 0 && c == 0` in the transform) takes a direct coverage fast path.
+Blending is non-premultiplied source-over, scaled by `globalAlpha`.
+
+Canvas pixels are **not** touched by the garbage collector: a canvas is owned by
+the window, keyed by its DOM node (the same shape as the `<video>`/`<audio>`
+decode table). It is released when the node is dropped (`loadHTML`, window
+close/quit, or a mutation that discards the subtree), which also releases the
+matching GPU texture.
+
+## Supported API
+
+State and transforms: `save` / `restore` (which restore the transform, line
+width, alpha, font/text settings **and** the fill/stroke styles),
+`translate`, `rotate`, `scale`, `transform(a,b,c,d,e,f)`, `setTransform`,
+`resetTransform`.
+
+Styles and settings: `fillStyle` / `strokeStyle` (CSS colors understood by the
+cascade's color parser), `lineWidth`, `globalAlpha`, `font` (a CSS font
+shorthand resolving to family, size and bold/italic — default
+`10px sans-serif`), `textAlign` (`start`/`left`, `center`, `right`/`end`) and
+`textBaseline` (`alphabetic`, `top`, `middle`, `bottom`, `hanging`,
+`ideographic`). Reading a property returns the value last assigned; assigning an
+unparseable color keeps the previous one.
+
+Paths: `beginPath`, `closePath`, `moveTo`, `lineTo`, `rect`, `arc`,
+`quadraticCurveTo`, `bezierCurveTo`, then `fill` (multi-loop, non-zero winding)
+or `stroke`. Bezier and quadratic segments are flattened into line segments;
+arcs are flattened too and each subpath is stroked as segment quads plus a disc
+at each joint.
+
+Rectangles: `clearRect`, `fillRect`, `strokeRect`.
+
+Text: `measureText(text)` (returns `{ width }`), `fillText(text, x, y)` and
+`strokeText(text, x, y)`. Text is shaped with HarfBuzz and rasterised with
+FreeType (the same stack as HTML text) at the transform's approximate scale.
+**Only translation and uniform scale are honoured** — a rotated or skewed
+transform still places each glyph at its transformed baseline point but does not
+rotate the glyph bitmaps. `strokeText` currently fills with the stroke style
+rather than producing an outline.
+
+Images: `drawImage(source, …)` in the 3-argument (`dx, dy`), 5-argument
+(`dx, dy, dw, dh`) and 9-argument (`dx, dy, dw, dh, sx, sy, sw, sh`) forms.
+`source` may be an `<img>` element (decoded through the image module) or another
+`<canvas>` element (its current bitmap). Sampling is nearest-neighbour, so a
+large upscale of a small source is blocky — fine for icons and pixel art, not a
+photo pipeline.
+
+Test hook: `getImageData(x, y, w, h)` copies a region to
+`{ width, height, data }` where `data` is a row-major RGBA8 byte array.
+Out-of-bounds pixels are transparent.
+
+## Not implemented
+
+Gradients and patterns, shadows, `clip()`, `globalCompositeOperation`, line
+joins/caps/dashes/mitre, `setLineDash`, `createLinearGradient`/`createPattern`,
+`putImageData`, `createImageData`, `isPointInPath`, `getTransform`,
+`setTransform` with a `DOMMatrix`, `drawImage` with an image smoothing toggle,
+`toDataURL`/`toBlob`, `<canvas>` as a CSS `background-image`, and offscreen
+canvases (`OffscreenCanvas`, `transferControlToOffscreen`).
+
+See also [Media](./media.md) for the image/video/audio decode stack that
+`drawImage` and the texture upload share.

package/doc/gui/dom.md

@@ -0,0 +1,123 @@
+# DOM, HTML, CSS and AOT scripts
+
+> Part of the [GUI extension](../gui.md); the engine overview, locked
+> decisions and roadmap live there. The scripting surface has its own
+> document, [gui-scripts.md](../gui-scripts.md).
+
+## HTML/CSS subset (M3a)
+
+**HTML parser** (`runtime/ext_gui/dom.{h,cpp}`): tags/attributes/text,
+comments and doctype skipped, entity decoding (named + numeric/hex), void
+elements, raw-text elements (`<style>`/`<script>`), and the common implicit
+close rules (`li`, `dt`/`dd`, `option`, `p`, headings, table cells/rows).
+
+**CSS parser** (`runtime/ext_gui/css.{h,cpp}`): comments and at-rules skipped
+(for now), rules with multiple selectors, and declarations. Selectors: type,
+`.class`, `#id`, attribute (`=`, `~=`, `|=`, `^=`, `$=`, `*=`), the four
+combinators (descendant, child, adjacent and general sibling) and the
+pseudo-classes `:first-child`, `:last-child`, `:only-child`, `:empty`,
+`:root`, `:not(...)`, `:nth-child(an+b)`, `:disabled`, `:checked`, plus the
+stateful `:hover` and `:focus` (see [Input](./input.md)). Values:
+lengths (`px`, `%`, `em`, `rem`, `vw`, `vh`, `pt`, `pc`, `in`, `cm`, `mm`, `q`),
+colors (hex, `rgb()`/`rgba()`, a named subset), numbers, keywords and shorthands
+(`margin`/`padding`/`border`/`flex`).
+
+**Cascade & computed style** (`runtime/ext_gui/style.{h,cpp}`): a small built-in
+UA stylesheet, author rules sorted by `(!important, specificity, source order)`,
+then inline `style=""` (highest specificity, but non-`!important` inline loses to
+`!important`), plus CSS inheritance of the text properties. Relative lengths are
+kept unresolved until layout, except `font-size` (resolved against the *parent*
+font size) and `line-height`.
+
+## Interactive DOM (M8)
+
+`win.document` returns the document handle; element handles have stable identity
+and read/write properties, attributes, traversal and geometry:
+
+```ts
+const doc = win.document;
+const box = doc.querySelector("#box");
+const inner = doc.querySelector("#inner");
+inner.textContent = "hi";              // write
+inner.classList.add("hot");
+inner.style.setProperty("color", "#0f0");
+inner.setAttribute("data-role", "lead");
+console.log(inner.id, inner.tagName, doc.querySelector("#box") === box);
+
+const created = doc.createElement("div");
+created.textContent = "added";
+box.appendChild(created);
+box.removeChild(created);
+
+inner.addEventListener("click", (e) => console.log(e.target.id, e.currentTarget.id));
+inner.click();                          // synthesise a click at the element
+console.log(box.offsetWidth, box.offsetHeight);   // rounded border box
+console.log(box.contains(inner));                 // descendant test
+```
+
+Mutations mark the document dirty; the engine restyles + relayouts lazily (before
+the next read or frame). `inner = …`/`innerHTML = …` do **not** run scripts.
+Element events support capture and bubble phases, `stopPropagation`, `once`, and
+bubble up to `document`/`window`. The legacy `win.on(type, fn)` payload keeps its
+**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
+loader compiles each body into a native function and `win.loadHTML(page)` runs
+them once the document is parsed (no JavaScript engine, no runtime `eval`):
+
+```ts
+import { createWindow, run } from "gui";
+import page from "./page.html";
+
+const win = createWindow({ title: "counter", width: 320, height: 240 });
+win.loadHTML(page);
+run();
+```
+
+```html
+<button id="b">0</button>
+<script lang="ts">
+  const b = document.getElementById("b");
+  let n = 0;
+  b.addEventListener("click", () => { b.textContent = String(++n); });
+</script>
+```
+
+The two parameters (`window`, `document`) are ordinary function arguments, so
+script locals need no global-object machinery. External scripts work too:
+`<script src="./counter.ts">` is read at compile time, its imports are hoisted
+(rewritten to resolve from the HTML file) and its body is wrapped the same way —
+so a script module can `import` helpers and still see `document`. Scripts are
+**compile-time assets**: HTML created at runtime (`innerHTML`, fetched over the
+network) never executes, and `src` URLs (`https://…`, `data:…`) are ignored.
+Everything runs in document order after parsing (effectively deferred). See
+`doc/gui-scripts.md` for the full design.
+

package/doc/gui/input.md

@@ -0,0 +1,22 @@
+# Input and events (M5)
+
+> Part of the [GUI extension](../gui.md); the engine overview, locked
+> decisions and roadmap live there. The public event API is in
+> [api.md](./api.md).
+
+`LayoutTree::hitTest` returns the deepest box containing a point (probing later
+siblings first so the topmost element wins), and `xt_dom_describe` turns the
+element into the `div#id.class` descriptor carried by event payloads.
+
+- SDL pointer/wheel/key events are routed to the owning window, hit tested, and
+delivered to the handlers registered with `on`. `mousedown` also moves focus.
+- `:hover` matches the hovered element **and its ancestors** (so hovering a child
+  lights up its parents); `:focus` matches the focused element. When either
+  changes, `XtDocument::setHover`/`setFocus` recompute styles and layout and mark
+  the window's geometry dirty, so the change is painted on the next frame.
+- `win.hitTest(x, y)` and `win.sendEvent(type, options)` expose hit testing and
+  synthetic input so the whole path is testable headlessly (the e2e suite drives
+  clicks, wheels and keys without a real mouse).
+
+Still to do for full input: text selection, drag, IME and clipboard.
+

package/doc/gui/known-issues.md

@@ -0,0 +1,66 @@
+# Known issues and open questions
+
+> Part of the [GUI extension](../gui.md); the engine overview, locked
+> decisions and roadmap live there.
+
+## 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. 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
+  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:** SVG *files* are supported through the image loader
+  (`<img src="logo.svg">`): `runtime/ext_gui/svg.cpp` wraps the vendored
+  **NanoSVG** parser/rasteriser and `image.{h,cpp}` treats an SVG as a vector
+  image, rasterised at the drawn pixel size. Inline `<svg>` **trees** in a
+  document are still not supported: the HTML parser knows elements and
+  attributes, the layout engine knows boxes, and paint knows
+  rectangles/text/images, so `<svg>` subtrees would need a whole second
+  geometry+paint path. Vector art therefore has to arrive as an SVG/PNG file or
+  be drawn from boxes, as `examples/gui/pelican-bike` does.
+- Windows: an MSVC-compatible `gui.lib` (COFF objects + `ar -M`/`llvm-ar`) is
+  produced by `scripts/build-gui.ts`, but it has not been validated in CI yet,
+  so the Windows step is provisional (the job stays green) and `package` skips
+  it. It also needs an SDL3 build with the D3D12/DXIL backend (DXIL requires
+  `dxc`).
+- **Media on Windows:** the media decoders (FFmpeg) are only built and merged
+  into the POSIX `gui.a`; the Windows `gui.lib` is produced without them, so
+  `<video>`/`<audio>` are inert there (failures fire `error`). Enabling it needs
+  an MSVC-compatible FFmpeg build and is deferred until the Windows GUI path
+  itself is validated. `<video controls>` is likewise deferred — the intended
+  pattern is TS + a CSS overlay, as in `examples/gui/media.ts`.
+- **D3D12 shaders:** the SPIR-V (Vulkan) and DXIL (Direct3D 12) blobs are built
+  and embedded, so the non-Metal path no longer skips geometry. DXIL remains
+  unusable on **SDL 3.2.10**: its D3D12 backend rejects any graphics pipeline
+  whose shaders declare a uniform buffer, and the engine passes the viewport that
+  way. Re-check after an SDL upgrade.