xbintsc 0.3.69 → 0.3.79

package/doc/gui.md

@@ -1,13 +1,15 @@
 # xbintsc GUI extension (self-hosted HTML/CSS renderer)
 
-Status: **M12** — features (M1–M11) are complete: HTML parsing, CSS selector
+Status: **M14** — features (M1–M13) are complete: HTML parsing, CSS selector
 matching, the cascade, computed styles and layout (block, inline, Flexbox and
 CSS positioning) are
 in place, and the engine *paints*: it builds a display list of rectangles, images
 and shaped text runs and renders them through SDL_GPU. Input events are hit
 tested and delivered to native TS handlers, `:hover`/`:focus` are matched
 dynamically, `<img>` is sized from its intrinsic dimensions and drawn from a
-texture, and CSS transitions animate paint properties. **M8** adds an interactive
+texture — PNG/JPEG/… bitmaps and SVG files alike, the latter rasterised at the
+drawn size so vector art stays crisp — and CSS transitions animate paint
+properties. **M8** adds an interactive
 DOM: element handles with stable identity, mutation (`appendChild`, `textContent`,
 `classList`, `style`, …) and element-level events with capture/bubbling.
 **M9** compiles `<script>` bodies ahead of time (inline and `<script src>`) — see
@@ -15,10 +17,31 @@ DOM: element handles with stable identity, mutation (`appendChild`, `textContent
 **M11** adds `position: relative`/`absolute`/`fixed` with their offsets, which is
 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.
+engine bounded memory: see [Node lifetime](./gui/dom.md#node-lifetime) and
+[Memory & GC](./gui/runtime.md#memory--gc). **M13** plays real
+`<video>`/`<audio>` — a vendored minimal FFmpeg decodes them on the main thread,
+video frames go through the image texture path and audio to an SDL stream, with
+the DOM media API exposing `play`/`pause`/`currentTime`/… and media events.
+**M14** adds `<canvas>` with a self-written 2D software rasteriser (anti-aliased
+fills, paths, text and `drawImage`) uploaded through the image texture path —
+see [Canvas](./gui/canvas.md).
+This overview records the locked decisions, the architecture, the milestone plan
+and the current progress; the engine itself is documented by function in the
+pages above.
+
+## Contents
+
+- [API](./gui/api.md) — window handles, events and diagnostics
+- [DOM, HTML and CSS](./gui/dom.md) — parsing, cascade, interactive DOM and AOT scripts
+- [Layout](./gui/layout.md) — block, inline, Flexbox and positioning
+- [Rendering](./gui/rendering.md) — display list, GPU pipelines and text
+- [Media](./gui/media.md) — images, SVG, video and audio
+- [Canvas](./gui/canvas.md) — `<canvas>` and the 2D context
+- [Input](./gui/input.md) — hit testing, events and `:hover`/`:focus`
+- [Animation](./gui/animation.md) — `requestAnimationFrame` and CSS transitions
+- [Runtime integration](./gui/runtime.md) — event loop, native bridge and memory
+- [Packaging and build](./gui/build.md) — building `gui.a` and running examples
+- [Known issues and open questions](./gui/known-issues.md)
 
 ## Goals
 
@@ -74,7 +97,7 @@ HTML/CSS UI with its own GPU-accelerated engine.
                 ▼
         windowing + input (SDL3) ── multiple windows
         text (HarfBuzz + FreeType) ── glyph atlas / SDF
-        images (stb_image)
+        images (stb_image; SVG via NanoSVG)
 ```
 
 The engine never talks to the compiler. The compiler only sees an `Extension`
@@ -88,10 +111,12 @@ with `nativeObjects()`, `linkerFlags()` and `modules()`.
 | GPU | **SDL_GPU** (SDL3) | one render path over Metal / Vulkan / D3D12; avoids three backends |
 | Text shaping | **HarfBuzz** | correct complex-script shaping |
 | Glyph raster | **FreeType** | glyph outlines → GPU atlas / SDF |
-| Images | **stb_image** (vendored header) | single header to start |
+| Images | **stb_image** (vendored header) for bitmaps, **NanoSVG** (vendored headers) for SVG | single headers to start; SVG files rasterise on demand |
+| Video + audio | **FFmpeg** (statically vendored, minimal build) | decodes the common container/codec set; no WebView or platform media framework |
 
-Pinned versions: SDL3 `release-3.2.10`, FreeType `2.13.3`, HarfBuzz `10.1.0`
-(overridable with `SDL3_TAG` / `FREETYPE_VERSION` / `HARFBUZZ_VERSION`).
+Pinned versions: SDL3 `release-3.2.10`, FreeType `2.13.3`, HarfBuzz `10.1.0`,
+FFmpeg `7.1` (overridable with `SDL3_TAG` / `FREETYPE_VERSION` /
+`HARFBUZZ_VERSION` / `FFMPEG_VERSION`).
 
 Alternative if SDL3 is rejected: **GLFW + OpenGL 3.3** (simpler, but OpenGL is
 deprecated on macOS and gives no modern GPU abstraction). **wgpu-native** if the
@@ -101,508 +126,6 @@ engine were Rust.
 > xbintsc stays "download and run"; only OS frameworks are added by
 > `linkerFlags()`.
 
-## 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 |
-
-### Implemented 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 *Implemented input*). 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`.
-
-### 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" 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.
-
-### 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.
-
-### 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();
-```
-
-### Implemented layout (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 (no margin collapsing
-  yet); `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.
-- **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 text fragment remembers the run it covers, so paint can shape it. Text is
-  measured with the HarfBuzz/FreeType stack (see *Implemented text*).
-- **Flexbox** — single-line `row`/`column` (and the `-reverse` variants) with
-  `gap`, `flex-basis`/`flex-grow`/`flex-shrink`, `justify-content` and
-  `align-items` (including `stretch` when the cross size is definite). Item
-  margins are part of the item's outer size on both axes, so a negative
-  `margin-top` pulls an item up instead of being ignored.
-- **Positioning** — `position: relative` offsets a box (and its subtree) by
-  `top`/`right`/`bottom`/`left` without changing the space it reserved;
-  `position: absolute` (and `fixed`, which resolves against the viewport) takes
-  the box out of flow and places it against the padding box of the nearest
-  positioned ancestor — the viewport when there is none. An `auto` inset keeps
-  the static position on that axis, an `auto` width is shrink-to-fit unless both
-  `left` and `right` are set (then it fills the space between them), and
-  percentages resolve against the containing block. There is no `z-index`
-  stacking yet: painting stays in document order.
-  Note the consequence of that shrink-to-fit rule: an absolutely positioned box
-  with `width: auto` and no explicit size gets **no** available width for its own
-  inline content (its preferred width comes from its text or its non-absolute
-  children only), so inline runs inside it are laid out at zero available width
-  and each one wraps onto its own line. Give such a box an explicit `width`, or
-  place its children with `left`/`width` (as
-  `examples/gui/pelican-bike` does for its sprite runs), instead of relying on
-  line flow inside it.
-
-Not yet implemented: margin collapsing, multi-line flex wrapping, `z-index`
-stacking, `overflow` clipping and floats.
-
-**Document** (`runtime/ext_gui/document.{h,cpp}`): owns the DOM tree, gathers
-`<style>` text into one stylesheet, computes styles and layout for a viewport and
-offers `querySelector`/`querySelectorAll`/`styleOf`/`boxOf`.
-
-### Implemented paint (M4a/M4b)
-
-`runtime/ext_gui/paint.{h,cpp}` walks the layout tree in painter's order and
-emits a backend-agnostic `DisplayList` with two parallel lists: **rectangles**
-(backgrounds and four solid border edges, with `border-radius`) and **text runs**
-(each carrying its text, colour and resolved `FontSpec`). Keeping them separate
-lets the renderer draw all rectangles, then all text on top, with one draw call
-per list. `DisplayList::dump()` feeds `paintList()`/`paintCount()`.
-
-`opacity` is honoured only at its extremes: a box whose computed `opacity` is
-`0` (and its whole subtree) paints nothing, and anything above `0` paints fully
-opaque. A shape carries its colour's alpha only, so there is no compositing of a
-partly transparent box — the `opacity` transitions the CSS parser accepts are
-therefore not visible either. Hiding and revealing a layer with `opacity: 0` on
-the hidden state is what `examples/gui/pelican-bike`'s game-over overlay does.
-
-`runtime/ext_gui/renderer.{h,cpp}` turns that list into two batched vertex
-buffers per window (one for shapes, one for glyph quads) drawn through two
-SDL_GPU graphics pipelines:
-
-- The shared pipelines are created lazily from the device's supported shader
-  format. Each of SDL_GPU's three backends consumes a different binary and none
-  of them compiles GLSL/HLSL at runtime, so the engine ships all three and
-  `selectShader` (`renderer_shaders.h`) picks the one the device accepts:
-  **MSL** for Metal (compiled by SDL from the embedded source),
-  **SPIR-V** for Vulkan (`runtime/ext_gui/spirv/*.{vert,frag}`, compiled by
-  `glslc`), and **DXIL** for Direct3D 12 (`shaders.hlsl`, compiled by `dxc`).
-  `scripts/build-gui-shaders.mjs` regenerates the embedded blobs and the result
-  is committed, so nothing extra is needed to build the engine.
-  The descriptor bindings differ per format — SPIR-V follows what
-  `SDL_gpu_vulkan.c` builds (uniforms `set=1, binding=0`, samplers
-  `set=2, binding=0`, textures `set=2, binding=1`) — and glslc names every entry
-  point `main` where MSL/DXIL keep the descriptive names.
-  Note that SDL 3.2.10's Direct3D 12 backend cannot create a graphics pipeline
-  whose shaders declare a uniform buffer (it fails with `E_INVALIDARG`); the
-  engine passes the viewport that way, so the DXIL path is built but not usable
-  until that is resolved upstream.
-- A **rounded-rectangle distance field** in the shape fragment shader gives
-  antialiased fills; the vertex carries `position`, `local`, `half extents`,
-  `radius` and colour, and a viewport-size push constant does the projection.
-  Alpha blending is enabled.
-- The text pipeline samples a **single shared grayscale glyph atlas**
-  (`R8_UNORM`, 2048², shelf-packed, LINEAR filtering) and draws each glyph as a
-  textured quad (`position`, `uv`, colour), modulating alpha by the coverage.
-- Geometry is uploaded only when the document or viewport changes
-  (`geometry.dirty`), so steady-state frames are bind-and-draw.
-
-The window background (`setBackground`) is the render-pass clear colour.
-
-Still to do in M4: gradients.
-
-### Implemented input (M5)
-
-`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.
-
-### Implemented images (M6a)
-
-`runtime/ext_gui/image.{h,cpp}` wraps the vendored **stb_image** header
-decoding PNG/JPEG/BMP/GIF/TGA to RGBA8, with a decode cache and a header-only
-size cache (`stbi_info`). Paths accept a `file://` prefix and percent-encoding.
-
-- `<img>` is a replaced element (`display: inline-block`): layout gives it the
-  CSS size when set, otherwise the intrinsic pixel size, and preserves the
-  aspect ratio when only one axis is constrained. The intrinsic size is read
-  from the file header (no full decode) while building the box tree.
-- Paint emits one `PaintImage` per `<img>`; the renderer decodes/uploads each
-  unique `src` to an RGBA texture (cached by path) and draws textured quads,
-  batching consecutive quads that share a texture.
-
-Still to do for images: CSS `background-image: url(...)`, `data:` URIs,
-`object-fit` and 9-slice borders.
-
-### Implemented 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(...)`.
-
-### Implemented text stack (M4b)
-
-`runtime/ext_gui/text.{h,cpp}` wraps **HarfBuzz** (shaping) and **FreeType**
-(metrics + eventual rasterisation). Both are built statically and linked into
-`gui.a` by `scripts/build-gui.ts`.
-
-- Fonts are resolved from well-known system paths (Helvetica/Arial on macOS,
-  DejaVu/Liberation on Linux, Segoe UI/Arial on Windows), overridable with
-  `XT_GUI_FONT` (and `XT_GUI_FONT_MONO`), and cached per `(family class, size)`.
-  Only regular upright faces are used for now; weight/italic selection is a
-  later refinement.
-- The default candidates prefer a **CJK-capable** face (Microsoft YaHei on
-  Windows, PingFang on macOS, Noto Sans CJK/WenQuanYi on Linux) before the
-  Latin-only ones, because a run is shaped with a *single* face: without this,
-  Chinese/Japanese/Korean text renders as blank or `.notdef` boxes. Set
-  `XT_GUI_FONT` to a Latin-only face to get its Latin design instead (at the
-  cost of CJK coverage).
-- `xt_text_measure_width` shapes the run with HarfBuzz (so kerning and
-  ligatures are honoured), `xt_text_metrics` returns FreeType's ascent /
-  descent / normal line height. When no font file can be found the module falls
-  back to a deterministic per-byte approximation, so layout still works.
-- `xt_text_shape_run` returns positioned glyphs and `xt_text_rasterize` renders
-  an 8-bit bitmap; the renderer packs those into the atlas. On HiDPI displays
-  glyphs are rasterised at `font_size * SDL_GetWindowPixelDensity` while quads
-  are positioned in logical pixels, so text stays crisp.
-- Layout uses these real metrics for text widths, line breaking and
-  `line-height: normal`; `measureText`/`fontMetrics` expose them to tests.
-
-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.
-
-## Event loop integration
-
-The runtime change (already landed):
-
-- `int xt_loop_poll(int timeout_ms)` — one reactor iteration; `0` polls without
-  blocking, `< 0` blocks.
-- `void xt_loop_set_main(xt_main_loop_fn fn)` — a host may take over the main
-  loop. `xt_run_event_loop()` delegates to it; the generated `main` is unchanged.
-- `xt_loop_set_main(NULL)` restores the default `select(2)` loop.
-
-The GUI engine can either register its own loop through `xt_loop_set_main`, or
-expose an explicit `run()`; **M2 uses the explicit `run()`** so the window is a
-plain native call the TypeScript program controls. Each tick it:
-
-1. pumps SDL window/input events for every window,
-2. builds/uploads the display list when it changed and renders every open
-   window (clear pass + shape geometry + text geometry),
-3. calls `xt_loop_poll(0)` and `xt_drain_microtasks()` so sockets/timers and
-   `await` continuations keep making progress,
-4. repeats until all windows close or `quit()` is called.
-
-The `xt_loop_set_main` hook remains available for hosts that want to own the
-loop themselves.
-
-This keeps network I/O, timers and `await` working inside a GUI program.
-
-## Native ↔ TS bridge
-
-- **TS → engine**: direct `xt_gui_*` calls / window methods.
-- **Engine → TS**: `xt_call_with_this(fn, thisValue, argc, argv)` with function
-  values captured from TS (e.g. event handlers registered with `win.on(...)`).
-- **Future page→native RPC**: not needed while there is no page JS; native TS is
-  the controller. If a declarative layer is added later, it will use the same
-  `xt_call_*` entry points.
-
-## Packaging & build
-
-- 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. 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.
-
-### 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.
-
-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 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
-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
-```
-
-Those are the packages the CI `compile-examples` job installs. The X11 backend is
-used by default; Wayland is enabled too but not yet exercised.
-
 ## Milestones
 
 1. **M1 — foundation** ✅
@@ -633,8 +156,10 @@ used by default; Wayland is enabled too but not yet exercised.
      restyle (`css.*`, `style.*`, `document.*`, `gui.cpp`), plus the
      `hitTest`/`sendEvent` test hooks.
 6. **M6 — images, then CSS transitions/animations**
-   - **M6a — images** ✅ stb_image decode, `<img>` replaced-element layout,
-     per-file GPU textures and textured quads (`image.*`, `paint.*`, `renderer.*`).
+   - **M6a — images** ✅ stb_image decode (bitmaps) and NanoSVG rasterisation
+     (SVG files, at the drawn pixel size), `<img>` replaced-element layout,
+     per-file GPU textures and textured quads (`image.*`, `svg.*`, `paint.*`,
+     `renderer.*`).
    - **M6b — transitions/animations** ✅ `transition` shorthand + longhands,
      animated `background-color`/`color`/`border-color`/`border-radius`, retargeting
      and `win.advance(ms)`. `@keyframes` remain.
@@ -650,7 +175,7 @@ used by default; Wayland is enabled too but not yet exercised.
      keyed by `scripts/build-gui.ts`.
    - Windows (build + run) stays provisional until the MSVC-compatible
      `gui.lib` and D3D12/DXIL shader path are validated; a failure is logged
-     without annotating the run (see *Open questions*).
+     without annotating the run (see [Open questions](./gui/known-issues.md#open-questions)).
 8. **M8 — interactive DOM** ✅
    - Element/document handles with stable identity, read/write properties via
      runtime accessors, traversal/attributes/queries, mutation with lazy
@@ -697,7 +222,24 @@ used by default; Wayland is enabled too but not yet exercised.
       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").
+      `tests/e2e/gui-retention.test.ts` (see [Memory & GC](./gui/runtime.md#memory--gc)).
+13. **M13 — video & audio** ✅
+    - `<video>` / `<audio>` decode through a statically vendored minimal FFmpeg
+      (`media.*`, `gui_media.cpp`), frames upload to GPU textures through the
+      existing image pipeline, audio is pushed to an SDL stream on the main
+      thread, and the DOM media API plus `loadedmetadata`/`play`/`pause`/
+      `ended`/`timeupdate`/`error` events are exposed on element handles
+      (`dom_api_media.cpp`, `dom_api_proto.cpp`). Controlled from TS + CSS;
+      there are no built-in controls. Example in `examples/gui/media.*`, e2e in
+      `tests/e2e/gui-media.test.ts`.
+14. **M14 — `<canvas>` 2D** ✅
+    - `<canvas>` is a replaced element (`xtgui::Canvas2D`, `layout.*`), the
+      `getContext("2d")` handle and drawing API live in `dom_api_canvas.cpp`,
+      the self-written anti-aliased software rasteriser in `canvas_raster.cpp`,
+      and the per-window lifetime in `gui_canvas.cpp`. The bitmap uploads to a
+      GPU texture through the image path (`renderer_image.cpp`) and the display
+      list carries a `canvas_id` (`paint.*`). See [Canvas](./gui/canvas.md);
+      e2e in `tests/e2e/gui-canvas.test.ts`.
 
 ## Progress log
 
@@ -722,7 +264,9 @@ used by default; Wayland is enabled too but not yet exercised.
   `hitTest`/`sendEvent` test hooks, e2e coverage.
 - **M6a** ✅ image decoding (`image.*`, vendored stb_image), `<img>` intrinsic
   sizing in layout, `PaintImage` in the display list, per-file RGBA textures and
-  an image pipeline in `renderer.*`, e2e coverage.
+  an image pipeline in `renderer.*`, e2e coverage. SVG files are decoded too
+  (`svg.*`, vendored NanoSVG): a vector source is rasterised at the drawn device
+  pixel size and cached by that size, so scaling and HiDPI stay crisp.
 - **M6b** ✅ CSS transitions (parsing in `style.*`, an animation clock and
   transition state in `document.*`, `advance`/`advance(ms)` hooks, e2e coverage).
 - **M7** ✅ builds `gui.a` in CI on Linux and macOS (required) and runs the
@@ -762,99 +306,23 @@ used by default; Wayland is enabled too but not yet exercised.
   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
-
-- **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
+  every frame now runs in constant memory (see [Memory & GC](./gui/runtime.md#memory--gc)).
+- **M13** ✅ `<video>` / `<audio>` support. A minimal static FFmpeg is vendored
+  and merged into `gui.a` (`scripts/build-gui.ts`), `media.*` decodes video to
+  RGBA frames and audio to 48 kHz stereo PCM on the main thread, `gui_media.cpp`
+  owns the players and pumps the media clock and events each frame,
+  `renderer_image.cpp` uploads each new video frame through the image texture
+  path, and `dom_api_media.cpp` exposes `play`/`pause`/`load` plus the media
+  properties on element handles. `examples/gui/media.*` demonstrates the
+  TS-plus-CSS-controls pattern and `tests/e2e/gui-media.test.ts` pins it.
+- **M14** ✅ `<canvas>` support. A new replaced element (`layout.*`) carries an
+  intrinsic size from its `width`/`height` attributes (default `300x150`),
+  `xtgui::Canvas2D` (`canvas.{h,cpp}`) owns the RGBA8 bitmap and drawing state,
+  `canvas_raster.cpp` is a self-written anti-aliased software rasteriser
+  (4 sub-scanlines + analytic horizontal coverage, non-zero winding), the
+  `getContext("2d")` handle and its API are bound in `dom_api_canvas.cpp`, and
+  `gui_canvas.cpp` owns the per-window lifetime. The bitmap uploads through the
+  image texture path (`renderer_image.cpp`) and the display list carries a
+  `canvas_id` (`paint.*`). See [Canvas](./gui/canvas.md); e2e in
+  `tests/e2e/gui-canvas.test.ts`.
 
-- Whether Linux ships X11, Wayland, or both in the first cut. (Decision:
-  X11 first, Wayland later.)
-- **SVG:** there is no SVG support and none is planned. The HTML parser knows
-  elements and attributes, the layout engine knows boxes, and paint knows
-  rectangles/text/images, so `<svg>` trees would need a whole second
-  geometry+paint path. An SVG *file* works only through the image loader
-  (`<img src="logo.svg">`), which needs an SVG rasteriser (`stb_image` does not
-  decode SVG); vector art therefore has to arrive as a raster (PNG) or be drawn
-  from boxes, as `examples/gui/pelican-bike` does.
-- Windows: an MSVC-compatible `gui.lib` (COFF objects + `ar -M`/`llvm-ar`) is
-  produced by `scripts/build-gui.ts`, but it has not been validated in CI yet,
-  so the Windows step is provisional (the job stays green) and `package` skips
-  it. It also needs an SDL3 build with the D3D12/DXIL backend (DXIL requires
-  `dxc`).
-- **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.