xbintsc 0.5.32 → 0.5.37

package/doc/gui/api.md

@@ -21,19 +21,55 @@ 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`.
+too: `addEventListener` / `removeEventListener` take the standard options bag
+(`capture`, `once`, `passive`, `signal`), and `closed` mirrors `isOpen()`, so a
+document written against the browser API runs unchanged.
+
+Element listeners accept the same options: `{ once }` drops the listener after
+its first call, `{ passive: true }` makes `preventDefault()` a no-op, and
+`{ signal }` (an `AbortSignal` from `new AbortController()`) removes it on
+abort, including a signal that was already aborted when the listener was added.
+`element.dispatchEvent(event)` dispatches the *same* event object (identity is
+observable), fills in `target` / `currentTarget` / `eventPhase` and records the
+path for `event.composedPath()`. `new Event(...)`, `new CustomEvent(...)`,
+`new MouseEvent(...)`, `new KeyboardEvent(...)`, `new PointerEvent(...)`,
+`new WheelEvent(...)`, `new FocusEvent(...)`, `new InputEvent(...)` and
+`new SubmitEvent(...)` keep every field of their `init` object (`detail`,
+`composed`, the mouse/keyboard members, …). Window listeners take the same bag
+(capture is part of listener identity; window delivery has no capture phase).
+
+Window navigation is real: `scrollTo(x, y)` / `scrollTo({ left, top })` /
+`scrollBy(...)` move the page viewport (clamped to the content bounds; painting
+and hit testing follow it), and `scrollX` / `scrollY` / `pageXOffset` /
+`pageYOffset` report it. `focus()` raises the OS window and sets
+`document.hasFocus()`; `blur()` clears it. Events emitted:
+`ready` (after the first presented frame), `load`, `close`, `resize`, `scroll`,
+`focus`, `blur` and the input events `mousemove`, `mousedown`, `mouseup`,
+`click`, `wheel`, `keydown`, `keyup`.
+
+`createWindow(options)` honours more than the title and size:
+`{ title, width, height, highDensity, resizable, borderless, alwaysOnTop,
+hidden, fullscreen, x, y, opacity, maximized, minimized }` map to the matching
+SDL window flags/calls instead of being ignored.
+
+`window.confirm(message)` / `window.prompt(message, defaultValue)` never drop
+their arguments: with `XT_GUI_DIALOGS=1` and a live window they show a native
+message box; otherwise the message goes to stderr and the documented default is
+returned (`confirm` → `false`, `prompt` → `defaultValue` or `""`).
 
 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).
 
+A host without a usable GPU cannot run the GUI at all. When SDL cannot open a
+video driver or create a Metal/Vulkan/D3D12 device, the engine prints the reason
+and exits with status **77** — the autotools "skip" convention, so CI and scripts
+can tell "this machine has no GUI" from "the program failed". A window that
+cannot be opened after that (an SDL window or GPU-claim error) makes
+`createWindow` throw a JavaScript `Error`; it no longer returns an `undefined`
+handle that fails a line later as `Cannot read properties of undefined`.
+
 ## Browser globals
 
 A document ported from the web rarely stops at `createWindow`. With `--ext gui`
@@ -54,12 +90,14 @@ requestAnimationFrame(frame);
 | `document` | that window's document handle |
 | `navigator` | `userAgent` (a desktop Chrome string ending in `xbintsc`), `platform`, `vendor`, `language(s)`, `hardwareConcurrency`, `maxTouchPoints`, `onLine`, `vibrate()` |
 | `localStorage` | an in-memory `getItem` / `setItem` / `removeItem` / `clear` / `key` / `length` store |
-| `AudioContext`, `webkitAudioContext` | a Web Audio graph builder (see below) |
-| `Event`, `CustomEvent`, `ProgressEvent`, … | event constructors |
+| `AudioContext`, `webkitAudioContext` | a Web Audio graph with a real mixer and decoder (see below) |
+| `Event`, `CustomEvent`, `ProgressEvent`, `MouseEvent`, `KeyboardEvent`, `PointerEvent`, `WheelEvent`, `FocusEvent`, `InputEvent`, `SubmitEvent` | event constructors; the `init` argument is kept as given (`detail`, `composed`, mouse/keyboard fields, …) |
+| `AbortController`, `AbortSignal` | a real controller/signal pair for `{ signal }` listener removal, with `abort()`, `aborted`, `reason`, `onabort` and `throwIfAborted()` |
 | `HTMLCanvasElement`, `HTMLImageElement`, `WebGLRenderingContext`, `WebGL2RenderingContext`, `WebGLBuffer`/`WebGLTexture`/`WebGLShader`/`WebGLProgram`/`WebGLFramebuffer`/`WebGLRenderbuffer`/`WebGLUniformLocation`/`WebGLActiveInfo`/`WebGLVertexArrayObject`/`WebGLSampler`/`WebGLQuery`/`WebGLSync`/`WebGLTransformFeedback` | real constructor values. `canvas.getContext("webgl")` and `getContext("webgl2")` return GPU contexts (see [WebGL](./webgl.md)). |
-| `ImageBitmap`, `ImageData`, `OffscreenCanvas`, `XRWebGL*`, `Request`, `Headers`, `Response`, `ReadableStream`, `DOMParser` | `typeof` probes answer `"undefined"` (no XR/fetch/streaming backend), which lets a page take its "unsupported" branch instead of calling a no-op stub. Three.js pages use its real renderer on this backend (see [Known issues](./known-issues.md)). |
+| `ImageBitmap`, `createImageBitmap(source)` | immutable bitmaps backed by decoded pixels (`<img>`, `<canvas>`, `<video>` frames and `ImageData` shapes); the promise resolves immediately and `texImage2D` accepts the result |
+| `ImageData`, `OffscreenCanvas`, `XRWebGL*`, `Request`, `Headers`, `Response`, `ReadableStream`, `DOMParser` | `typeof` probes answer `"undefined"` (no XR/fetch/streaming backend), which lets a page take its "unsupported" branch instead of calling a no-op stub. Three.js pages use its real renderer on this backend (see [Known issues](./known-issues.md)). |
 | `requestAnimationFrame` / `cancelAnimationFrame` | queued on the window's frame list; see [Runtime integration](./runtime.md) |
-| `alert` / `confirm` / `prompt`, `matchMedia`, `getComputedStyle`, `escape` | host implementations (Annex B `escape` encodes per UTF-16 code unit, matching `decodeURIComponent(escape(bytes))`) |
+| `alert` / `confirm` / `prompt`, `matchMedia`, `getComputedStyle`, `escape` | host implementations. `matchMedia` returns a **live** list (cached per query): `matches` is re-evaluated on resize and `change` listeners fire when it flips. `confirm`/`prompt` use a native dialog only with `XT_GUI_DIALOGS=1`; otherwise they report the message on stderr and return the documented default (Annex B `escape` encodes per UTF-16 code unit, matching `decodeURIComponent(escape(bytes))`) |
 
 `getElementById` / `querySelector` are answered even before `loadHTML` runs: the
 handle is *pending* and binds to the real node the first time it is used, so a
@@ -68,17 +106,56 @@ Once the page is parsed a miss answers `undefined`, like the browser.
 
 ### Web Audio
 
-`new AudioContext()` builds a graph but **does not mix or render audio**: there
-is no backend behind it. What is implemented is the surface a page needs to run
-and to read back its own state — `createGain` / `createOscillator` /
-`createBufferSource` / `createBiquadFilter` / `createDynamicsCompressor` /
-`createBuffer` (real `Float32Array` channels) / `decodeAudioData` (resolves with
-an empty buffer) / `resume` / `suspend` / `close`, `AudioParam` `value` plus
-`setValueAtTime` / `linearRampToValueAtTime` / `exponentialRampToValueAtTime` /
-`setTargetAtTime` / `cancelScheduledValues` / `cancelAndHoldAtTime`, and node
-`connect` (returns the destination, so chains chain) / `disconnect` / `start` /
-`stop`. `sampleRate` is 48000, `state` `"running"`, and `currentTime` advances
-only through the event loop.
+`new AudioContext()` builds a real graph and mixes it: `runtime/ext_gui/audio_mixer.cpp`
+renders 48 kHz stereo float in 128-frame quanta, multiple inputs are summed at
+every node, and the first `start()`/`resume()` opens the default SDL playback
+device (best effort — a headless host keeps rendering silently). The graph is
+rendered on the SDL audio thread from native state; the page never has to pump
+it, and no runtime value is touched off the main thread.
+
+Implemented nodes: `createGain`, `createOscillator` (sine, square, sawtooth,
+triangle), `createBufferSource` (buffer, loop, loopStart/loopEnd,
+playbackRate/detune), `createBiquadFilter` (lowpass, highpass, bandpass,
+lowshelf, highshelf, peaking, notch, allpass), `createDynamicsCompressor`,
+`createStereoPanner`, `createConstantSource` and `createDelay(maxDelayTime)`.
+`connect` returns the destination so chains chain (`src.connect(gain).connect(ctx.destination)`),
+`disconnect()` / `disconnect(target)` update the native graph, and `start(when, offset, duration)` /
+`stop(when)` are honoured on the graph's clock. Nodes outside this list
+(`createAnalyser`, `createConvolver`, `createWaveShaper`, `createChannelSplitter`,
+`createPeriodicWave`, …) are not provided, so their methods are simply absent.
+
+Every `AudioParam` has a live `value` plus `setValueAtTime` /
+`linearRampToValueAtTime` / `exponentialRampToValueAtTime` / `setTargetAtTime` /
+`cancelScheduledValues` / `cancelAndHoldAtTime`. The automation timeline is
+evaluated per sample, so a ramp keeps moving while the page is idle.
+`currentTime` advances with the rendered quanta.
+
+`createBuffer(channels, length, sampleRate)` returns an AudioBuffer whose
+`getChannelData(i)` is a real `Float32Array`, so samples can be generated
+procedurally. `decodeAudioData(bytes)` returns a promise for a decoded
+AudioBuffer: WAV (PCM 8/16/24/32-bit, IEEE float 32/64, A-law and µ-law) is
+decoded by the engine itself; MP3, AAC/M4A, Vorbis, Opus and FLAC need the
+optional `media` extension (`--ext gui,media`), whose FFmpeg decoder is used as
+the fallback. `bytes` may be an ArrayBuffer, a typed array, a Node `Buffer`, or
+the raw byte string `fs.readFileSync` returns (this runtime has no dedicated
+binary type, and that string's storage is exactly the file bytes). The result
+is resampled to the context's 48 kHz, so `buffer.sampleRate` matches
+`context.sampleRate`; the promise rejects with an `EncodingError` when nothing
+can decode the bytes.
+
+`resume()` / `suspend()` / `close()` control the device and the `state`
+property; `sampleRate` is 48000, like the media decoder.
+
+For tests and diagnostics an **offline** context renders synchronously:
+
+```ts
+const ctx = new AudioContext({ __offline: true });
+// … build the graph and start sources …
+const samples = ctx.__render(480);   // interleaved stereo Float32Array
+```
+
+This private hook never opens a device and is not part of the Web Audio API; it
+is what `tests/e2e/gui-audio.test.ts` uses to pin the mixer math.
 
 Input handlers receive a single payload object (lifecycle handlers receive none):
 

package/doc/gui/build.md

@@ -58,12 +58,19 @@
   rather than through `make install`.
 - CI builds `gui.a`/`gui.lib` and `media.a`/`media.lib` before assembling the
   release archive so they ship inside `runtime/lib/<slug>/` (the release tarball
-  copies the whole `runtime/` tree). The archives are built and the examples are
-  run on Linux (under Xvfb, with the lavapipe software Vulkan driver) and macOS;
+  copies the whole `runtime/` tree). The same folders are packed into the
+  optional `@xbintsc/<slug>` npm package, so `--ext gui`/`--ext media` work from
+  an npm install on the hosts the release builds for. The archives are built and
+  the examples are run on Linux (under Xvfb, with the lavapipe software Vulkan
+  driver) and macOS;
   the Windows x64 job builds both archives and links a `gui,media` program, so
   the MSVC build is validated even though *running* the examples there stays
-  provisional (the hosted runner has no GPU/Vulkan driver). Windows arm64 still
-  skips both archives: FFmpeg's MSVC arm64 build is not validated yet.
+  provisional (the hosted runner has no GPU/Vulkan driver). The macOS run is
+  provisional too: the Intel runner's virtualised GPU lacks
+  `MTLGPUFamilyMac2`, so the engine exits **77** ("cannot run a GUI here") and
+  the job records a skip instead of compiling a suite that cannot present.
+  Windows arm64 still skips both archives: FFmpeg's MSVC arm64 build is not
+  validated yet.
 - The Windows CI steps call `.github/actions/vs-toolchain` →
   `scripts/setup-vs-toolchain.ps1`, which imports the same Visual Studio
   `vcvarsall` environment and bundled LLVM a local build uses (no separate

package/doc/gui/canvas.md

@@ -36,12 +36,20 @@ 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.
 
+`getContext("2d", attributes)` honours `alpha` on the first call: with
+`{ alpha: false }` the bitmap starts (and clears) opaque black. The other
+attributes are reported by `getContextAttributes()` at their specification
+defaults (`antialias: true`, `depth: true`, `stencil: false`,
+`premultipliedAlpha: true`, `preserveDrawingBuffer: false`, `colorSpace:
+"srgb"`, …), so a feature test gets an honest answer.
+
 ## 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
+(so `arc`-shaped holes work when wound the other way) unless
+`fill("evenodd")` selects the even-odd rule. 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`.
 
@@ -63,10 +71,11 @@ matching GPU texture.
 
 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`, `getTransform` (returns an object with `a`…`f` and `is2D`).
-Transforms compose in canvas order: `translate(x, y); rotate(a)` rotates around
-the translated origin.
+`translate`, `rotate`, `scale`, `transform(a,b,c,d,e,f)` / `transform(matrix)`,
+`setTransform(a,b,c,d,e,f)` / `setTransform(matrix)`, `resetTransform`,
+`getTransform` (returns an object with `a`…`f` and `is2D`). A matrix is a
+`{ a, b, c, d, e, f }` object or a six-element array. Transforms compose in
+canvas order: `translate(x, y); rotate(a)` rotates around the translated origin.
 
 Styles and settings: `fillStyle` / `strokeStyle` (CSS colors understood by the
 cascade's color parser, or a `CanvasGradient`), `lineWidth`, `globalAlpha`,
@@ -86,10 +95,18 @@ distance from the **outer** circle's centre (`x1, y1`), so `x0`/`y0` are
 currently ignored: use concentric circles (`x0 == x1`, `y0 == y1`).
 
 Paths: `beginPath`, `closePath`, `moveTo`, `lineTo`, `rect`, `roundRect`,
-`arc`, `ellipse`, `quadraticCurveTo`, `bezierCurveTo`, then `fill` (multi-loop,
-non-zero winding) or `stroke`. Bezier and quadratic segments are flattened into
-line segments; arcs and ellipses are flattened too. `roundRect` accepts one
-radius number (the array form is not implemented).
+`arc`, `ellipse`, `quadraticCurveTo`, `bezierCurveTo`, then
+`fill(fillRule?)` / `fill(path, fillRule?)` (multi-loop; `"nonzero"` or
+`"evenodd"`) or `stroke(path?)`. Bezier and quadratic segments are flattened
+into line segments; arcs and ellipses are flattened too. `roundRect` accepts a
+single radius number or the CSS radius list (`[all]`, `[tl, br]`,
+`[tl, tr, br]`, `[tl, tr, br, bl]`, numbers or `{ x, y }` pairs; corners are
+drawn circular).
+
+`Path2D` is implemented with the same path commands (`moveTo`, `lineTo`,
+`closePath`, `rect`, `roundRect`, `arc`, `ellipse`, `quadraticCurveTo`,
+`bezierCurveTo`, `addPath`) and can be passed to `fill`/`stroke`, so a path can
+be built once and replayed under different transforms.
 
 Rectangles: `clearRect`, `fillRect`, `strokeRect`.
 
@@ -97,9 +114,12 @@ Dashes: `setLineDash(segments)` / `getLineDash()` / `lineDashOffset` implement
 the standard pattern rules (an odd-length list is duplicated, negative or
 non-finite entries are ignored, an all-zero list means a solid line).
 
-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.
+Text: `measureText(text)` (returns `{ width }`), `fillText(text, x, y,
+maxWidth?)` and `strokeText(text, x, y, maxWidth?)`. Text is shaped with
+HarfBuzz and rasterised with FreeType (the same stack as HTML text) at the
+transform's approximate scale. A positive `maxWidth` condenses advances and
+glyph bitmaps horizontally so the run is at most that wide (as the canvas API
+specifies) instead of being ignored.
 **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
@@ -119,14 +139,25 @@ 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.
 
+Patterns: `createPattern(source, repetition?)` accepts an `<img>` or another
+`<canvas>` and tiles it in user space (`repeat`, `repeat-x`, `repeat-y`,
+`no-repeat`), so the tiles follow the current transform. Assign the result to
+`fillStyle`/`strokeStyle`; assigning a colour replaces it.
+
+Image data and export: `createImageData(width, height)` allocates a blank
+`{ width, height, data }`, and `putImageData(imageData, dx, dy[, dirtyX, dirtyY,
+dirtyWidth, dirtyHeight])` copies bytes straight into the bitmap (no transform,
+blending or `globalAlpha`). `canvas.toDataURL(type?)` exports a PNG data URL and
+`canvas.toBlob(callback, type?)` delivers a Blob-shaped `{ type, size }` from a
+microtask (the bytes are on `__xt_gui_blob_data`; there is no
+`URL.createObjectURL`).
+
 ## Not implemented
 
-Patterns (`createPattern`), shadows, `clip()`, `globalCompositeOperation`,
-`putImageData`, `createImageData`, `isPointInPath`, `setTransform` with a
-`DOMMatrix`, `drawImage` with an image smoothing toggle, `toDataURL`/`toBlob`,
-`<canvas>` as a CSS `background-image`, and offscreen canvases
-(`OffscreenCanvas`, `transferControlToOffscreen`). `roundRect` takes a single
-radius, and radial gradients ignore the inner circle's offset.
+Shadows, `clip()`, `globalCompositeOperation`, `isPointInPath`, `drawImage` with
+an image smoothing toggle, `<canvas>` as a CSS `background-image`, and offscreen
+canvases (`OffscreenCanvas`, `transferControlToOffscreen`).
+Radial gradients ignore the inner circle's offset.
 
 See also [Media](./media.md) for the image/video/audio decode stack that
 `drawImage` and the texture upload share.

package/doc/gui/dom.md

@@ -14,9 +14,12 @@ close rules (`li`, `dt`/`dd`, `option`, `p`, headings, table cells/rows).
 **CSS parser** (`runtime/ext_gui/css.{h,cpp}`): comments are stripped; `@media`
 blocks are parsed recursively (nested queries combine with `and`, and a comma
 list distributes over the inner query) while other at-rules are skipped. Rules
-support multiple selectors and declarations. Selectors: type, `.class`, `#id`,
-attribute (`=`, `~=`, `|=`, `^=`, `$=`, `*=`), the four combinators
-(descendant, child, adjacent and general sibling), the pseudo-classes
+support multiple selectors and declarations; a selector list may be formatted
+across any number of lines (line breaks are ordinary whitespace, so a wrapped
+combinator stays a combinator), and a quoted attribute value may contain
+commas, brackets or parentheses without splitting the list. Selectors: type,
+`.class`, `#id`, attribute (`=`, `~=`, `|=`, `^=`, `$=`, `*=`), the four
+combinators (descendant, child, adjacent and general sibling), 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)), and the pseudo-elements `::before`/`::after`
@@ -69,18 +72,65 @@ created.textContent = "added";
 box.appendChild(created);
 box.removeChild(created);
 
+// Parent/child helpers accept nodes and strings in one call.
+box.append("text", doc.createElement("span"));
+box.prepend(doc.createElement("b"));
+box.insertAdjacentHTML("beforeend", "<i>tail</i>"); // beforebegin/afterbegin/beforeend/afterend
+box.replaceChildren("fresh", doc.createElement("em"));
+
+// Namespaces are recorded; foreign (SVG) element names keep their case.
+const gradient = doc.createElementNS("http://www.w3.org/2000/svg", "svg:linearGradient");
+console.log(gradient.namespaceURI, gradient.localName, gradient.prefix);
+
 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
 ```
 
+### Style properties, dataset, computed style and geometry
+
+The inline `style` object is a CSSOM declaration block. Named access reads and
+writes the same block as `setProperty` (`el.style.display = "none"`,
+`el.style.backgroundColor = "#f00"`, camelCase mapped to the CSS spelling, and
+`el.style["--accent"]` for custom properties); `setProperty(name, value,
+priority)` stores `!important` when `priority` is `"important"` (any other
+priority makes the call a no-op, and an empty value removes the property).
+`getPropertyValue` / `getPropertyPriority` read it back, `removeProperty`
+returns the previous value, `cssText` gets or replaces the whole block,
+`style.length` / `style.item(i)` enumerate it, and an unset property answers
+`""`.
+
+`el.dataset` is a live `DOMStringMap` over the element's `data-*` attributes:
+`dataset.fooBar` reads `data-foo-bar`, assignment writes the attribute, `delete`
+removes it, and `Object.keys(dataset)` / `for...in` list only the data keys.
+
+`getComputedStyle(el, pseudoElt)` answers from the **cascade** — the UA sheet,
+author rules, inheritance and the inline declarations — rather than echoing the
+inline block, so a stylesheet rule is visible. It exposes `getPropertyValue`,
+`getPropertyPriority` and named properties (`cs.width`, `cs.backgroundColor`,
+`cs["--accent"]`). Pass `"::before"`/`"::after"` to read generated content; any
+other pseudo-element answers empty values. Every read flushes a pending restyle,
+so a handle created early stays live after later mutations.
+
+`getBoundingClientRect()` carries the legacy `top` / `right` / `bottom` / `left`
+members next to `x` / `y` / `width` / `height`, and `document.title = …` writes
+the document's `<title>` (creating the element, and a `<head>`, when the page
+has none).
+
 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.
+Element events support capture and bubble phases, `stopPropagation`, `once`,
+`passive` and `signal` (an `AbortController`'s signal removes the listener), and
+bubble up to `document`/`window`. `dispatchEvent` dispatches the same event
+object and fills in `target`/`currentTarget`/`eventPhase`/`composedPath()`. 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.
+
+`element.focus()` scrolls the element into view (pass `{ preventScroll: true }`
+to keep the page offset), and `document.hasFocus()` reports the window state
+toggled by `window.focus()` / `window.blur()`.
 
 ### Node lifetime
 

package/doc/gui/media.md

@@ -112,6 +112,10 @@ platform media framework in the path either way.
 - **Threading.** The engine is single-threaded and not thread-aware, so all
   decoding happens on the main thread inside `xt_gui_media_tick` — no decode
   thread, no cross-thread GC exposure.
+- **`decodeAudioData`.** The same FFmpeg build also decodes an in-memory audio
+  file for `AudioContext.decodeAudioData` (`runtime/ext_media/decode_audio.cpp`,
+  through the media table); WAV is handled by the GUI engine itself
+  (`audio_decode.cpp`), so only compressed formats need this extension.
 - **DOM API.** Element handles expose the media surface directly (see
   `runtime/ext_gui/dom_api_media.cpp` and the prototype in
   `dom_api_proto.cpp`): `play()` / `pause()` / `load()`, and the

package/doc/gui/webgl.md

@@ -96,8 +96,7 @@ reflected offsets; `uniform1i` on a sampler stores the texture unit. The block
 is pushed with the dynamic uniform-buffer API on every draw.
 
 Limits of the translator: struct-typed uniforms, user uniform blocks, uniform
-arrays whose size is not resolved by the preprocessor, sampler arrays and cube
-maps are rejected (the link/shader info log says so). Shader code inside
+arrays whose size is not resolved by the preprocessor, sampler arrays are rejected (the link/shader info log says so). Shader code inside
 `#ifdef` is fine; non-sampler uniform declarations are moved to the enclosing
 top-level position so the block stays unconditional.
 
@@ -115,8 +114,11 @@ available from GLSL ES 3.00, which is what the instanced example uses.
 
 - **Context**: `getContext("webgl")`, `canvas`, `drawingBufferWidth/Height`,
   `getParameter`, `getError`, `getSupportedExtensions`, `getExtension`,
-  `getContextAttributes`, `isContextLost`, `getShaderPrecisionFormat`, and the
-  stencil entry points (accepted; the depth target has no stencil attachment).
+  `getContextAttributes`, `isContextLost`, `getShaderPrecisionFormat`, and an
+  8-bit stencil buffer (`getContextAttributes().stencil` is `true`,
+  `STENCIL_BITS` is 8). `WEBGL_lose_context`'s `loseContext`/`restoreContext`
+  really drop and rebuild the context (every object becomes invalid) and
+  dispatch `webglcontextlost`/`webglcontextrestored`.
 - **Shaders and programs**: `createShader`, `shaderSource`, `compileShader`,
   `getShaderParameter`, `getShaderInfoLog`, `getShaderSource`, `deleteShader`,
   `createProgram`, `attachShader`, `detachShader`, `linkProgram`,
@@ -131,7 +133,9 @@ available from GLSL ES 3.00, which is what the instanced example uses.
   `bufferSubData`, `deleteBuffer`, `getBufferParameter`,
   `enableVertexAttribArray`, `disableVertexAttribArray`,
   `vertexAttribPointer`, `vertexAttrib1f`…`4f` / `1fv`…`4fv`,
-  `getVertexAttrib`.
+  `getVertexAttrib`. The `usage` hint from `bufferData`
+  (`STREAM_DRAW`/`STATIC_DRAW`/`DYNAMIC_DRAW`) is recorded and reported by
+  `getBufferParameter(…, BUFFER_USAGE)`.
 - **Drawing**: `drawArrays`, `drawElements` (UNSIGNED_BYTE, UNSIGNED_SHORT,
   UNSIGNED_INT; `TRIANGLE_FAN` and `LINE_LOOP` are expanded to lists).
   `POINTS`, `LINES`, `LINE_STRIP`, `TRIANGLES` and `TRIANGLE_STRIP` map to the
@@ -140,22 +144,50 @@ available from GLSL ES 3.00, which is what the instanced example uses.
   `texParameteri`/`texParameterf`, `getTexParameter`, `texImage2D` (raw pixels,
   `<img>`, `<canvas>` and `ImageData` sources), `texSubImage2D`,
   `generateMipmap`, `deleteTexture`. `UNPACK_FLIP_Y_WEBGL` and
-  `UNPACK_PREMULTIPLY_ALPHA_WEBGL` are honoured. Everything is converted to
-  RGBA8; `RGBA`, `RGB`, `LUMINANCE`, `ALPHA` and `LUMINANCE_ALPHA` with
-  `UNSIGNED_BYTE` are accepted.
-- **Framebuffers**: `createFramebuffer`, `bindFramebuffer`,
-  `framebufferTexture2D` (colour attachment), `checkFramebufferStatus`,
-  `createRenderbuffer`, `bindRenderbuffer`, `renderbufferStorage` (depth),
-  `framebufferRenderbuffer`, `delete*`. This is enough for render-to-texture,
-  shadow maps and post-processing passes.
+  `UNPACK_PREMULTIPLY_ALPHA_WEBGL` are honoured. By default source data is
+  converted to RGBA8; `RGBA`, `RGB`, `LUMINANCE`, `ALPHA` and
+  `LUMINANCE_ALPHA` with `UNSIGNED_BYTE` are accepted. Float textures
+  (`RGBA32F`, `RGBA16F`, `RGB32F`, `RGB16F`, `RG32F`/`RG16F`, `R32F`/`R16F`
+  with `FLOAT` or `HALF_FLOAT` data, plus WebGL 1's
+  `OES_texture_float`/`OES_texture_half_float`) map to SDL's RGBA32F/RGBA16F,
+  and depth textures (`DEPTH_COMPONENT16/24/32F`, `DEPTH_STENCIL`,
+  `DEPTH24_STENCIL8`) map to `D32_FLOAT`/`D32_FLOAT_S8_UINT` and can be sampled
+  or used as depth attachments. Compressed textures upload through
+  `compressedTexImage2D`/`compressedTexSubImage2D` with
+  `WEBGL_compressed_texture_s3tc` (BC1/BC2/BC3),
+  `WEBGL_compressed_texture_s3tc_srgb` and `WEBGL_compressed_texture_astc`;
+  each extension is published only when the device can sample its formats.
+  `texImage2D` also accepts the latest decoded `<video>` frame and an
+  `ImageBitmap` produced by `createImageBitmap`. Cube maps
+  (`bindTexture(TEXTURE_CUBE_MAP)` plus six `texImage2D` faces) and 3D/array
+  textures (`texImage3D`/`texStorage3D`) are sampled through `samplerCube`,
+  `sampler3D` and `sampler2DArray`; `texSubImage3D` updates a sub-volume and
+  `framebufferTextureLayer` renders one array/cube layer as a colour
+  attachment.
+- **Framebuffers**: `createFramebuffer`, `bindFramebuffer`
+  (`FRAMEBUFFER`/`READ_FRAMEBUFFER`/`DRAW_FRAMEBUFFER`),
+  `framebufferTexture2D` (`COLOR_ATTACHMENT0`, `DEPTH_ATTACHMENT`,
+  `DEPTH_STENCIL_ATTACHMENT`), `checkFramebufferStatus`, `createRenderbuffer`,
+  `bindRenderbuffer`, `renderbufferStorage` (depth or depth-stencil),
+  `framebufferRenderbuffer`, `delete*`, and `blitFramebuffer` (colour
+  attachment; depth/stencil bits are accepted but not copied). This is enough
+  for render-to-texture, shadow maps and post-processing passes.
 - **State**: `enable`/`disable`/`isEnabled` for `BLEND`, `DEPTH_TEST`,
-  `CULL_FACE`, `SCISSOR_TEST` (stencil accepted but not applied),
-  `clearColor`/`clearDepth`/`clearStencil`, `clear`, `blendFunc`/
-  `blendFuncSeparate`, `blendEquation`/`blendEquationSeparate`, `depthFunc`,
-  `depthMask`, `colorMask`, `cullFace`, `frontFace`, `viewport`, `scissor`,
-  `pixelStorei`, `finish`.
+  `CULL_FACE`, `SCISSOR_TEST` and `STENCIL_TEST`,
+  `clearColor`/`clearDepth`/`clearStencil`, `clear` (with `SCISSOR_TEST` it
+  clears only the scissor rectangle, for colour, depth and stencil), `blendColor`,
+  `blendFunc`/`blendFuncSeparate`,
+  `blendEquation`/`blendEquationSeparate`, `depthFunc`,
+  `depthMask`, `colorMask`, `stencilFunc`/`stencilFuncSeparate`,
+  `stencilOp`/`stencilOpSeparate`, `stencilMask`/`stencilMaskSeparate`,
+  `cullFace`, `frontFace`, `viewport`, `scissor`,
+  `pixelStorei`, `finish`. The stencil test takes part in rasterisation and
+  `clear(STENCIL_BUFFER_BIT)` clears the stencil attachment; SDL_GPU exposes
+  one reference and one compare/write mask for both faces, so a front/back
+  pair that differs uses the front value.
 - **Readback**: `readPixels` (RGBA/UNSIGNED_BYTE) from the default framebuffer
-  or a bound framebuffer. It blocks until the GPU finishes; use it for tests and
+  or a bound RGBA8 framebuffer; a float/depth attachment is sampled into an
+  RGBA8 target first. It blocks until the GPU finishes; use it for tests and
   screenshots, not per frame.
 
 WebGL 2 adds:
@@ -174,38 +206,46 @@ WebGL 2 adds:
   texture's own filter/wrap state for that unit.
 - **Immutable textures and buffer copies**: `texStorage2D` (the backend always
   allocates the full mip chain), `copyBufferSubData`, `getBufferSubData`.
+- **Drawing buffer**: `drawingBufferStorage(width, height)` fixes the drawing
+  buffer size; `canvas.width`/`canvas.height` no longer rebuild it afterwards.
 - **Clears**: `clearBufferfv`, `clearBufferiv`, `clearBufferuiv`,
   `clearBufferfi`.
+- **Multiple render targets**: `drawBuffers` addresses up to four colour
+  attachments and `readBuffer` selects the attachment `readPixels` reads;
+  `framebufferTexture2D` accepts `COLOR_ATTACHMENT0`…`3`, and a fragment
+  shader's multiple `out` variables are written in order.
 - **Queries and fences**: the objects and entry points exist
   (`createQuery`/`beginQuery`/`endQuery`/`getQueryParameter`,
   `fenceSync`/`clientWaitSync`/`waitSync`/`getSyncParameter`) and degrade
   gracefully: a fence reports `ALREADY_SIGNALED` and query results are 0.
-- **Uniform blocks**: `getUniformBlockIndex` answers `INVALID_INDEX` so a
-  library falls back to individual uniforms; the block entry points are no-ops.
-- **Transform feedback, 3D textures and compressed formats**: the entry points
-  are present as no-ops so feature-probing libraries do not throw.
+- **Uniform blocks**: `getUniformBlockIndex`,
+  `getActiveUniformBlockParameter`, `getActiveUniformBlockName`,
+  `uniformBlockBinding`, `bindBufferBase`/`bindBufferRange` and
+  `getIndexedParameter`. Members are merged into the engine's single std140
+  block and copied from the bound buffer at draw time; scalars, vectors,
+  matrices and fixed-size arrays work, nested structs, sampler members and
+  blocks without an instance name are rejected.
+- **Transform feedback**: the entry points are present as no-ops so
+  feature-probing libraries do not throw.
 
 Textures are created with a full mip chain; sampling clamps to level 0 until
 `generateMipmap` runs. Matrix vertex attributes consume the right number of
 consecutive locations and read one column per location. A disabled attribute
 is supplied from the last `vertexAttrib*f` value through a small constant
-buffer.
+buffer. A vertex shader can sample textures just like a fragment shader:
+`MAX_VERTEX_TEXTURE_IMAGE_UNITS` reports 16, vertex samplers live in set 0 and
+are bound with `SDL_BindGPUVertexSamplers` on every draw. Depth values use the
+backend's `[0, 1]` clip space rather than GL's `[-1, 1] → [0, 1]` remap:
+`gl_Position.z = 0.5` stores depth `0.5` (real WebGL stores `0.75`).
 
 ## Not implemented
 
-Uniform buffer objects in shader source, transform feedback (the entry points
-are no-ops), cube maps, 3D/array textures, float/half textures, depth textures,
-compressed textures, multiple render targets (only the first fragment output is
-written), `blitFramebuffer`, MSAA/sample buffers, stencil operations (state is
-accepted, the stencil buffer is not written), constant blend colours,
-`drawingBufferStorage`, context loss, `bufferData` with a `usage` other than
-static/dynamic (the hint is ignored), `texImage2D` for
-`HTMLVideoElement`/`ImageBitmap` and scissored `clear` (a clear clears the whole
-attachment). Shaders that use built-in blocks, user uniform blocks or
-`gl_FragDepth` beyond the supported subset are rejected with a compile/link log.
-
-The engine advertises zero vertex texture units, so a well-behaved WebGL 1
-program will not try to sample a texture in a vertex shader.
+Transform feedback (the entry points are no-ops) and MSAA/sample buffers
+(SDL_GPU's Metal multisample resolve returns undefined pixels with scissor
+tests and instanced draws, so contexts stay single-sampled). `blitFramebuffer`
+copies the colour attachment only; depth/stencil bits are accepted but not
+copied. Shaders that use built-in blocks or `gl_FragDepth` are rejected with a
+compile/link log.
 
 ## Platform
 
@@ -225,10 +265,27 @@ uses the 2D canvas or the DOM pays no run-time cost beyond the archive size.
 ## Testing
 
 - `tests/e2e/gui-webgl.test.ts` compiles GLSL, draws a textured and a
-  depth-tested quad, checks face culling and reads the pixels back.
-- `tests/e2e/gui-webgl2.test.ts` covers the WebGL 2 additions: `#version 300 es`
-  shaders, a VAO round trip, instanced draws with a divisor, `texStorage2D`,
-  `clearBufferfv`, buffer copies, sampler objects and struct-uniform fields.
+  depth-tested quad, checks face culling and reads the pixels back; it also
+  covers blend constants, dynamic buffer usage, vertex-shader texture sampling,
+  `gl_FragDepth` diagnostics, context loss/restore and cube maps.
+- `tests/e2e/gui-webgl2.test.ts` covers the WebGL 2 shader/state additions:
+  `#version 300 es` shaders, a VAO round trip, instanced draws with a divisor,
+  `texStorage2D`, `clearBufferfv`, buffer copies, sampler objects, struct-uniform
+  fields and `drawingBufferStorage`.
+- `tests/e2e/gui-webgl2-formats.test.ts` covers stencil, float/depth textures,
+  compressed textures and `ImageBitmap`.
+- `tests/e2e/gui-webgl2-blit.test.ts` covers scissored colour/depth clears,
+  framebuffer blits, and the pixels around a partial blit that must survive
+  (a destination load-op that discards them fails there on Metal).
+- `tests/e2e/gui-media.test.ts` also uploads the latest decoded `<video>` frame
+  as a texture and reads it back.
+- `tests/e2e/gui-webgl2-3d.test.ts` covers 2D-array and 3D texture layer
+  sampling, `texSubImage3D` sub-volume updates and rendering to a colour
+  attachment layer.
+- `tests/e2e/gui-webgl2-mrt.test.ts` writes two fragment outputs to two
+  colour attachments and reads each back.
+- `tests/e2e/gui-webgl2-ubo.test.ts` binds a std140 block, updates its members
+  and verifies the drawn colour.
 - `examples/gui/webgl-cube` is a spinning, lit, textured cube; it runs in a
   browser unchanged and is covered by
   `tests/e2e/gui-example-webgl.test.ts`.
@@ -249,8 +306,10 @@ is bundled any more**. Verified with three.js r160 through SDL_GPU:
 `CanvasTexture`, linear fog, ambient/directional/point/spot/hemisphere lights,
 `Sprite`, `Line`, `Points` and `InstancedMesh`.
 
-Features outside this engine's subset still cannot be emulated: shadow maps
-(depth textures), cube textures/environment maps, HDR/float render targets,
-multiple render targets, transform feedback and compressed textures. A scene
-that needs one of those will not render correctly; everything the previous
-Canvas2D fallback could show now goes through the GPU.
+Features outside this engine's subset still cannot be emulated: transform
+feedback and MSAA.
+Depth textures, float render targets and compressed textures are available, but
+three.js shadow maps still need comparative `sampler2DShadow` sampling, which
+is not translated yet. A scene that needs one of those will not render
+correctly; everything the previous Canvas2D fallback could show now goes
+through the GPU.