xbintsc 0.3.69 → 0.3.81

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, transformed)
+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,128 @@
+# 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`). `transform` (`translate`/`translate3d`/
+`translateX`/`translateY`, `scale`/`scale3d`/`scaleX`/`scaleY`, `rotate`/
+`rotateZ`, `matrix`; the `3d` spellings' `z` argument is dropped) and
+`transform-origin` are parsed into the computed style as a list of operations
+plus two (unresolved) origin lengths; an unsupported function invalidates the
+whole declaration ([Layout](./layout.md#transforms-m15)).
+
+**Cascade & computed style** (`runtime/ext_gui/style.{h,cpp}`): a small built-in
+UA stylesheet, author rules sorted by `(!important, specificity, source order)`,
+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,25 @@
+# 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. A
+transformed box maps the point through its inverse matrix first, so a rotated,
+scaled or translated element is hit exactly where it is drawn — and `:hover`
+follows the artwork, not the box flow left behind.
+
+- SDL pointer/wheel/key events are routed to the owning window, hit tested, and
+delivered to the handlers registered with `on`. `mousedown` also moves focus.
+- `: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,78 @@
+# 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: the C++ runtime must not be named on the link line.** `gui.lib` is
+  built with the *static* CRT (`CMAKE_MSVC_RUNTIME_LIBRARY=MultiThreaded`) and
+  every engine object records `libcpmt` as a dependent library, which is also
+  clang's Windows default and what the xbintsc runtime objects use
+  (`scripts/build-gui.ts`). Asking for the DLL runtime as well — the gui
+  extension used to pass `-lmsvcprt` — makes the two copies of the same symbols
+  collide: `LNK2038: mismatch detected for 'RuntimeLibrary'` plus a wall of
+  `LNK2005: already defined`, surfaced as `clang: linker command failed with exit
+  code 1169`. `src/extensions/gui/index.ts` now lists only the OS libraries
+  (`user32`, `gdi32`, `d3d12`, …). A Windows link is also the only place the
+  MSVC environment matters, so build from an x64 Native Tools prompt.
+- Windows: an MSVC-compatible `gui.lib` (COFF objects + `ar -M`/`llvm-ar`) is
+  produced by `scripts/build-gui.ts` but is not validated in CI, so the Windows
+  step is provisional (the job stays green) and `package` skips it. Building and
+  running `examples/gui/pelican-svg` and `examples/gui/pelican-bike` on a
+  developer machine works. It also needs an SDL3 build with the D3D12/DXIL
+  backend (DXIL requires `dxc`).
+- **Media on Windows:** the media decoders (FFmpeg) are only built and merged
+  into the POSIX `gui.a`; the Windows `gui.lib` is produced without them, so
+  `<video>`/`<audio>` are inert there (failures fire `error`). Enabling it needs
+  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.

package/doc/gui/layout.md

@@ -0,0 +1,108 @@
+# Layout
+
+> Part of the [GUI extension](../gui.md); the engine overview, locked
+> decisions and roadmap live there.
+
+## Layout engine (M3)
+
+`runtime/ext_gui/layout.{h,cpp}` turns the styled DOM into a `LayoutBox` tree
+with absolute (viewport-relative) geometry:
+
+- **Block flow** — block-level children stack vertically; `display: none`
+  generates no box; `width: auto` fills the containing block, `height: auto`
+  wraps the content. The box model (margin/padding/border) is resolved,
+  including percentages against the containing block width. Adjoining vertical
+  margins between siblings collapse to `max(positive) + min(negative)`; a
+  parent's bottom margin does not collapse with its last child's (see the
+  limitations below).
+- **Inline flow** — consecutive inline-level children form an anonymous inline
+  formatting context with greedy, word-based line breaking, `text-align` and
+  `line-height`. Inline elements get the union of their descendants' geometry;
+  `display: inline-block` is laid out atomically with a shrink-to-fit width.
+  Each line shrinks to the band left free by any floats (`float: left|right`)
+  that overlap it, so later lines wrap around them.
+  Each text fragment remembers the run it covers, so paint can shape it. Text is
+  measured with the HarfBuzz/FreeType stack (see [Text stack](./rendering.md#text-stack-m4b)).
+- **Flexbox** — `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). `flex-wrap: wrap`
+  breaks items into several lines, `align-content`
+  (`stretch`/`flex-start`/`flex-end`/`center`/`space-between`/`space-around`)
+  distributes the lines on the cross axis and `wrap-reverse` flips that axis.
+  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. Whitespace-only text
+  between items (source indentation) does not become a flex item.
+- **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. Stacking is approximated by
+  sorting each parent's children by `z-index` (negative → `auto` → positive)
+  before painting; this is a single level, not a full stacking context, so a
+  child cannot escape its parent's level.
+  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.
+- **Floats and clearance** — `float: left|right` takes a box out of flow,
+  shrink-to-fits its width, places it against the current line and lets later
+  inline lines wrap around it; `clear: left|right|both` pushes a following block
+  below the relevant floats, and a block that contains only floats grows to
+  enclose them.
+- **`overflow` clipping** — a box with `overflow: hidden` (or `scroll`/`auto`)
+  clips its subtree to its padding box, intersected with any ancestor clip; the
+  renderer applies the result with a GPU scissor rectangle. There is no
+  scrolling yet, so `scroll`/`auto` clip like `hidden`.
+
+Not yet implemented: parent/child and empty-block margin collapsing, anonymous
+flex items from non-whitespace text, full `z-index` stacking contexts, and
+`float` affecting block children (only inline content wraps; a block must
+`clear`).
+
+## Transforms (M15)
+
+`transform` and `transform-origin` are a **paint-time** effect: the box model
+above is untouched (nothing reflows, no geometry is recomputed), and a second
+pass after `xt_layout_run` gives every `LayoutBox` a `Matrix2D world` — the
+transform of the whole ancestor chain — plus its `inverse`:
+
+- **Only element boxes contribute.** A text box shares its parent element's
+  `style` pointer, so letting both contribute would apply the element's list
+  twice; the pass composes an element's own list, its ancestors', and nothing
+  else.
+- **`transform-origin` is resolved here**, not in the cascade: the computed style
+  keeps the two (possibly `%`) `Length`s (default `50% 50%`) and layout resolves
+  them against the *border box*, applying `T(origin) · M · T(-origin)`. That is
+  why `computedStyle(el, "transform-origin")` still reports `50% 92%`. The
+  keywords are positional as in CSS: `top` alone is `center top`, and the
+  keyword pair may be given in either order (`bottom right` = `right bottom`).
+- **Lengths resolve against the box**: `%` in `translate()` is a share of the
+  border box's width/height, `em`/`rem` against the root font size (16px), and
+  `vw`/`vh` against the viewport.
+- **Composition order** follows CSS: the list applies right to left, so
+  `rotate(90deg) translate(10px)` moves the box *down* the screen, not right.
+
+Everything downstream follows the matrices:
+
+| Consumer | Behaviour |
+| --- | --- |
+| Paint | each op carries the matrix (see [Rendering](./rendering.md#paint-and-display-list-m4am4b)); a clipped subtree clips to the bounding box of its padding box through the matrix |
+| Hit testing | `hitTestBox` maps the point through each box's inverse before the containment test, so a rotated or scaled element is clickable where it is *drawn* |
+| `getBoundingClientRect` | the axis-aligned bounding box of the **transformed** border box (`xt_layout_transformed_bounds`) |
+| Layout geometry | unchanged — `layoutTree()` and `offsetWidth`/`offsetHeight` keep reporting the untransformed box |
+
+Unsupported transform functions (`skew`, `perspective`, …) invalidate the whole
+declaration, so a box is either correctly transformed or not transformed at all
+rather than partially applied.
+
+**Document** (`runtime/ext_gui/document.{h,cpp}`): owns the DOM tree, gathers
+`<style>` text into one stylesheet, computes styles and layout for a viewport and
+offers `querySelector`/`querySelectorAll`/`styleOf`/`boxOf`.
+