@relu-interactives/spatial-ecs 0.5.3 → 0.9.0

package/dist/docs/guide/scene/postprocessing.md

@@ -11,7 +11,7 @@ It is a **singleton** there is exactly one `Postprocessing` entity per scene, ow
 
 ## Get the component from the world
 
-Use `world.getPostprocessingComponent()` — a convenience method that handles the entity lookup for you:
+Use `world.getPostprocessingComponent()`, a convenience method that handles the entity lookup for you:
 
 ```ts
 import { Behaviour } from "@relu-interactives/spatial-ecs";
@@ -26,7 +26,7 @@ export default class ReadPostprocessing extends Behaviour {
 }
 ```
 
-`post.values` is the live state object — mutate fields on it directly. The `PostprocessingSyncSystem` reads it every frame and rebuilds the composer pipeline as effects are toggled.
+`post.values` is the live state object, mutate fields on it directly. The `PostprocessingSyncSystem` reads it every frame and rebuilds the effect chain as effects are toggled.
 
 ## Change values at runtime
 
@@ -73,6 +73,68 @@ post.values.hueSaturation.hue = 0.05;       // radians
 post.values.hueSaturation.saturation = 0.2; // 0 = unchanged
 ```
 
+### Lens and retro effects
+
+Since 0.5.4, chromatic aberration, pixelation, SMAA and tone mapping all render. Earlier versions accepted these fields and drew nothing.
+
+```ts
+import { Behaviour } from "@relu-interactives/spatial-ecs";
+
+export default class RetroLook extends Behaviour {
+  init() {
+    const post = this.world.getPostprocessingComponent();
+    if (!post) return;
+
+    post.values.postEnabled = true;
+
+    // Red/blue fringing. The (x, y) offset sets direction and strength, in UV units.
+    post.values.chromAberration.enabled = true;
+    post.values.chromAberration.offsetX = 0.002;
+    post.values.chromAberration.offsetY = 0.001;
+
+    // Mosaic blocks, `granularity` CSS pixels wide.
+    post.values.pixelation.enabled = true;
+    post.values.pixelation.granularity = 4;
+
+    // Edge antialiasing for the composed image.
+    post.values.smaa.enabled = true;
+
+    // ACES tone mapping at this exposure.
+    post.values.toneMapping.enabled = true;
+    post.values.toneMapping.exposure = 1.2;
+  }
+}
+```
+
+- **Chromatic aberration** runs three's `RGBShiftShader`. The pass shifts red by the offset and blue by the opposite offset.
+- **Pixelation** samples the centre of each block. It pixelates everything earlier in the chain, bloom included.
+- **SMAA** runs three's `SMAAPass` right before the output pass. Turn it on when the canvas was created without `antialias`, or whenever the composer is active: render targets do not use the canvas's built-in MSAA.
+- **Tone mapping** has no pass of its own. It sets the renderer's tone mapping and exposure, which the final `OutputPass` applies. When the scene's `Environment.values.lighting.toneMapping` names an operator, that operator wins and this effect only sets the exposure. With no environment operator it uses ACES Filmic. The [Environment page](./environment#tone-mapping-and-the-post-processing-stack) has the full table.
+
+The composer applies effects in this order: scene → depth of field → bloom → vignette → hue/saturation → sepia → film noise → dot screen → SSAO → glitch → chromatic aberration → pixelation → SMAA → output (tone mapping and sRGB).
+
+## Support per renderer
+
+The same component drives both renderers. On WebGL the chain is an `EffectComposer`; with `WebGPURenderer` and `webgpuBackend` it is a TSL `RenderPipeline` ([WebGPU and TSL](../webgpu-and-tsl)).
+
+| Effect | WebGL | WebGPU |
+| --- | --- | --- |
+| Depth of field | ✅ `BokehPass` | ✅ `DepthOfFieldNode` (`focusDistance` / `focalLength` in world units) |
+| Bloom | ✅ `UnrealBloomPass` | ✅ `BloomNode` |
+| Vignette | ✅ | ✅ same formula |
+| Hue / saturation | ✅ | ✅ `hue()` / `saturation()` with the same curves |
+| Sepia | ✅ | ✅ |
+| Film noise | ✅ `FilmPass` | ✅ `FilmNode` |
+| Dot screen | ✅ `DotScreenPass` | ✅ `DotScreenNode` |
+| SSAO | ✅ `SSAOPass` | ≈ GTAO (`GTAONode`); `intensity` is the occlusion exponent, normals come from depth |
+| Chromatic aberration | ✅ `RGBShiftShader` | ✅ `RGBShiftNode` |
+| Pixelation | ✅ | ✅ |
+| SMAA | ✅ `SMAAPass` | ✅ `SMAANode` |
+| Tone mapping | ✅ | ✅ |
+| Glitch | ✅ `GlitchPass` | ❌ skipped, with one warning |
+
+On WebGPU, changing a parameter (bloom strength, vignette darkness, ...) updates the running chain in place. Switching an effect on or off rebuilds it. A `WebGPURenderer` without `webgpuBackend` renders with no post-processing at all.
+
 ## Authorable values
 
 Top-level master toggle:
@@ -88,10 +150,10 @@ Each effect lives under its own key with `enabled` plus parameters:
 | Depth of field | `dof` | `focusDistance`, `focalLength`, `bokehScale` |
 | Bloom | `bloom` | `intensity`, `threshold`, `radius` |
 | Vignette | `vignette` | `offset`, `darkness` |
-| Chromatic aberration | `chromAberration` | `offsetX`, `offsetY` |
+| Chromatic aberration | `chromAberration` | `offsetX`, `offsetY` (UV units) |
 | Film noise | `noise` | `opacity` |
-| Pixelation | `pixelation` | `granularity` |
-| Tone mapping | `toneMapping` | `exposure` |
+| Pixelation | `pixelation` | `granularity` (CSS pixels) |
+| Tone mapping | `toneMapping` | `exposure` (ACES unless the environment picks an operator) |
 | Hue / saturation | `hueSaturation` | `hue`, `saturation` |
 | Sepia | `sepia` | `intensity` |
 | SMAA | `smaa` | _(toggle only)_ |

package/dist/docs/guide/spatial-ui.md

@@ -21,8 +21,9 @@ raise its `width`/`height` fields and it re-renders crisply.
 1. Create a **UI Panel** — the backdrop. A comfortable read is 1–2 m from the
    player, centred around eye height (y ≈ 1.2–1.6).
 2. Create **Text**, **Button**, **Toggle**, **Slider** entities and parent
-   them under the panel. Place them with local transforms, a hair in front of
-   the backdrop (local z ≈ 0.01) so they draw over it.
+   them under the panel. Place them with local transforms. Children always
+   draw over their parent, from any angle, so local z is only for depth you
+   want to see.
 3. Give each interactive widget an `actionId` (empty means "use the entity's
    name").
 4. Attach **one Behaviour to the panel**. UI events fire on the widget's own
@@ -71,7 +72,9 @@ independent: each panel script hears only its own children.
 | Toggle | `UIToggleComponent` | On/off switch. Fires `onUiToggle`; `value` persists with the scene. |
 | Slider | `UISliderComponent` | Draggable value in `[min, max]`. Fires `onUiChange`. |
 
-Images need no widget: parent an ordinary `image` entity under the panel.
+Images need no widget: parent an ordinary `image` entity under the panel. A
+transparent mesh under a widget draws with it, in front of that widget and
+behind the widget's own children.
 
 ### Press semantics
 
@@ -90,6 +93,65 @@ and always fires once more with the final value on release.
 panel's texture density. Lines wrap automatically to the component's `width`;
 overflow past `height` is clamped with an ellipsis.
 
+## Styling
+
+Every widget takes a `style`, which wins over its plain colour fields. Leave it
+out and the widget draws as it always has.
+
+```ts
+import { UIPanelComponent } from "@relu-interactives/spatial-ecs/components";
+
+const panel = new UIPanelComponent({
+  width: 0.9,
+  height: 0.6,
+  tokens: { plate: "#1b2432", plateDeep: "#121824" },
+  style: {
+    fill: {
+      kind: "linear",
+      angle: 160,
+      stops: [
+        { at: 0, color: "$plate" },
+        { at: 1, color: "$plateDeep" },
+      ],
+    },
+    radius: 0.036,
+    shadows: [{ x: 0, y: -0.02, blur: 0.06, color: "#00000099" }],
+    edge: { width: 0.0035, color: "#ffffff30" },
+  },
+});
+```
+
+| Field | What it does |
+| --- | --- |
+| `fill` | `solid`, `linear` (angle in degrees, reads like CSS), `radial`, or `image` (`cover`, `contain`, `fill`, with an optional `tint`) |
+| `border` | Width in metres and a paint |
+| `radius` | One radius, or four: top-left, top-right, bottom-right, bottom-left |
+| `shadows` | Drop shadows, in metres, outside the shape only. They don't change what a pointer can hit |
+| `edge` | A thin highlight along the top inner edge |
+| `opacity` | 0–1. Multiplies down the widget tree, so fading a panel fades its menu, and a fade never redraws anything |
+| `text` | `font`, `weight`, `tracking`, `transform`, `paint`, `maxLines`, `shadow` |
+
+### Tokens
+
+`tokens` on a panel name values for every widget under it, as `$name` in any
+colour or file field, the nearest panel winning. A theme therefore travels with
+a prefab, and one edit restyles a whole menu, redrawing only the widgets that
+use that token.
+
+### Fonts and images
+
+`style.text.font` takes a font file in the project, and `fill` with
+`kind: "image"` or a button's `icon` takes an image or SVG. Files load on
+demand and the widget redraws when they arrive. Until then text uses a system
+face.
+
+### Variants
+
+- Toggle `variant`: `switch` (default), `checkbox`, `radio`.
+- Slider `variant`: `slider` (default), `progress`, `ring`. The last two only
+  show a value. `readOnly` does the same for a plain slider, and `step` snaps
+  a dragged value.
+
 ## Follow modes
 
 - `follow: "world"` (default) — the panel stays where you put it.
@@ -148,7 +210,8 @@ export class Inspect extends Behaviour {
   }
 
   onUiHoverStart(event: UiInteractionEvent) {
-    // The pointer moved onto the widget (also fires for mouse hover).
+    // A ray or the mouse moved onto the widget. Two hands on one widget count
+    // as one hover. Vision Pro has no hover before a pinch.
     console.log("hovering", event.targetEntityId);
   }
 }
@@ -160,6 +223,19 @@ export class Inspect extends Behaviour {
   idle menu costs nothing per frame.
 - Slider drags and toggle flips move **geometry** (the knob and fill quads),
   not pixels, so dragging never re-renders the texture.
-- `pixelDensity` (panel) trades texture memory for sharpness: the default
-  1024 px/m is crisp at arm's length; raise it only for panels the player
-  inspects up close.
+- `pixelDensity` (every widget) trades texture memory for sharpness: the
+  default 1024 px/m is crisp at arm's length; raise it only for widgets the
+  player inspects up close.
+
+## Draw order and blending
+
+Widgets draw in a fixed order: within one UI tree, parents before children;
+between trees, back to front by plane distance. Widgets on one plane that are
+not parented to each other draw large before small, so parent them when the
+order matters.
+
+Text and controls show from the front only. A panel keeps its back.
+
+On a WebGPU project a translucent widget over a bright background looks a
+little duller than on WebGL, because WebGPU blends in linear light. Over dark
+backgrounds the two match. Opaque widgets are identical on both.

package/dist/docs/guide/spawning/area-light.md

@@ -27,6 +27,8 @@ export default class SpawnSoftbox extends Behaviour {
 
 Default color `#ffffff`, intensity `5`, dimensions `4 × 4`.
 
+Area lights shade through lookup tables. The engine loads them the first time an area light is spawned this way (WebGL fetches them on demand; `webgpuBackend` installs them at start-up). If a script builds a `THREE.RectAreaLight` by hand instead, call `this.world.getRenderBackend().prepareAreaLights?.(this.world)` first, or the light renders black on WebGL. A `WebGPURenderer` without `webgpuBackend` cannot render area lights.
+
 ## Components attached
 
 `Transform`, `Object3DRef`, `Name`, `EntityType`, `ParentId`, `Selectable`, `Light`.

package/dist/docs/guide/systems/environment-sync-system.md

@@ -1,13 +1,15 @@
 # EnvironmentSyncSystem
 
-Applies the scene-level `Environment` component to the THREE.js scene each frame — background color, gradient textures, HDRI environment maps, and fog.
+Applies the scene-level `Environment` component to the THREE.js scene: background color, gradient textures, image skyboxes, fog, and the optional `lighting` block (HDRI environment map, tone mapping, exposure).
 
 ## Overview
 
 `EnvironmentSyncSystem` runs every frame and is responsible for:
 
 - Generating canvas-based gradient textures (`linear`, `radial`, `angular`) from the color stops defined in the `Environment` component and setting them as `scene.background`.
-- Loading HDRI or image URLs via `THREE.TextureLoader` and assigning them as `scene.background` and/or `scene.environment`.
+- Loading image skyboxes: a flat screen backdrop through `THREE.TextureLoader` by default, or a 360° panorama when `skybox.imageProjection` is `"equirect"` (`.hdr` and `.exr` supported).
+- Loading `lighting.envMapUrl` (`HDRLoader` for `.hdr`, `EXRLoader` for `.exr`, `TextureLoader` otherwise), pre-filtering it with `PMREMGenerator` on WebGL (on WebGPU the equirect texture is assigned as is and `WebGPURenderer` pre-filters it) and assigning `scene.environment`, `scene.environmentIntensity` and `scene.environmentRotation`. With `lighting.useAsBackground` it also becomes `scene.background` with the authored blur, intensity and rotation.
+- Setting `renderer.toneMapping` and `renderer.toneMappingExposure` from `lighting.toneMapping` / `lighting.exposure`, combined with the post-processing tone-mapping effect as described on the [Environment page](../scene/environment#tone-mapping-and-the-post-processing-stack).
 - Applying solid color backgrounds directly as `THREE.Color`.
 - Configuring `THREE.FogExp2` or `THREE.Fog` from the fog sub-state (`near`, `far`, `density`, `color`).
 - Disposing previous textures when the background changes to prevent GPU memory leaks.
@@ -20,10 +22,13 @@ Applies the scene-level `Environment` component to the THREE.js scene each frame
 
 ## Behavior notes
 
-- **Signature-based change detection** — the system serializes the entire Environment state into a string signature each frame. Texture regeneration and scene assignments only happen when the signature changes, so frequent re-renders don't rebuild the background every frame.
-- **Gradient texture** — generated on a 512×512 `<canvas>` element. In server-side or non-DOM environments a single-pixel `DataTexture` fallback is used instead.
-- **Fog clamping** — fog `near` and `far` values are clamped so `far > near + 0.001` and density is clamped to `≥ 0`. Invalid values are replaced with safe defaults.
-- **Pending image URL** — image/HDRI loads are queued via an internal pending URL field; a stale load result is discarded if the component signature changed again before the load finished.
+- **Signature-based change detection**: the system keeps one signature each for the skybox, fog and lighting. A part is re-applied only when its own signature changes, so animating `lighting.envIntensity` never rebuilds the skybox texture.
+- **Lighting is opt-in**: without a `lighting` block the system never writes `scene.environment` or the renderer's tone mapping. Removing the block, or disposing the system, restores the values they had before.
+- **Async env maps**: a newer `envMapUrl` always wins over a load still in flight, and the previous PMREM target and source texture are disposed when the new map swaps in.
+- **Passthrough**: while `world.isXrPassthrough()` is true the background stays `null` so the real room shows. Fog and image-based lighting keep applying.
+- **Gradient texture**: generated on a 512×512 `<canvas>` element. In server-side or non-DOM environments a single-pixel `DataTexture` fallback is used instead.
+- **Fog clamping**: fog `near` and `far` values are clamped so `far > near + 0.001` and density is clamped to `≥ 0`. Invalid values are replaced with safe defaults.
+- **Pending image URL**: image/HDRI loads are queued via an internal pending URL field; a stale load result is discarded if the component signature changed again before the load finished.
 
 ## API reference
 

package/dist/docs/guide/systems/light-sync-system.md

@@ -10,6 +10,7 @@ Applies `LightComponent` authoring values to the underlying THREE.js light objec
 - Writing `distance` and `decay` for `THREE.PointLight` and `THREE.SpotLight`.
 - Writing `angle` and `penumbra` for `THREE.SpotLight`.
 - Writing `width` and `height` for `THREE.RectAreaLight`.
+- Applying the optional `values.shadow` block (`mapSize`, `bias`, `normalBias`, `radius`, `cameraSize`, `near`, `far`) to shadow-casting lights. See [Tune shadow quality](../components/light#tune-shadow-quality).
 
 ## Queried components
 
@@ -19,9 +20,10 @@ Applies `LightComponent` authoring values to the underlying THREE.js light objec
 
 ## Behavior notes
 
-- **Signature-based change detection** — per-entity signatures are computed from the serialized `values` object each frame. Light properties are only written when the signature changes, preventing redundant THREE.js mutations on every frame.
-- **Value clamping** — `intensity` is clamped to `≥ 0`. `distance` is clamped to `≥ 0`. `angle` is clamped to `[0, π/2]`. `penumbra` is clamped to `[0, 1]`. Non-finite values use safe defaults.
-- **Stale entity cleanup** — when an entity is destroyed the system removes its entry from the signature map to prevent unbounded memory growth.
+- **Signature-based change detection**: per-entity signatures are computed from the serialized `values` object each frame. Light properties are only written when the signature changes, preventing redundant THREE.js mutations on every frame.
+- **Value clamping**: `intensity` is clamped to `≥ 0`. `distance` is clamped to `≥ 0`. `angle` is clamped to `[0, π/2]`. `penumbra` is clamped to `[0, 1]`. Non-finite values use safe defaults.
+- **Shadow fields**: only the fields present in `values.shadow` are written; a light without the block keeps three's defaults. Removing a field restores its default. A new `mapSize` disposes the allocated shadow map so three rebuilds it at the new size, and any camera change calls `shadow.camera.updateProjectionMatrix()`. `mapSize` is clamped to `[16, 8192]`.
+- **Stale entity cleanup**: when an entity is destroyed the system removes its entry from the signature map to prevent unbounded memory growth.
 
 ## API reference
 

package/dist/docs/guide/systems/postprocessing-sync-system.md

@@ -1,13 +1,13 @@
 # PostprocessingSyncSystem
 
-Builds and manages a THREE.js `EffectComposer` pipeline from the `Postprocessing` component's state, enabling full-screen visual effects in the rendered scene.
+Builds and manages the post-processing chain from the `Postprocessing` component's state, enabling full-screen visual effects in the rendered scene. The chain comes from the world's render backend: an `EffectComposer` on WebGL, a TSL `RenderPipeline` with [`webgpuBackend`](../webgpu-and-tsl).
 
 ## Overview
 
 `PostprocessingSyncSystem` runs every frame and is responsible for:
 
-- Building an `EffectComposer` with a `RenderPass` base and adding post-process passes derived from the enabled effects in `Postprocessing`.
-- Rebuilding the composer pipeline when the effect configuration changes (detected by signature).
+- Asking the backend (`world.getRenderBackend().createPostprocessing(...)`) for a chain built from the enabled effects in `Postprocessing`. On WebGL that is an `EffectComposer` with a `RenderPass` base and one pass per effect.
+- Rebuilding the chain when the effect configuration changes (detected by signature), or updating it in place when the backend supports that (WebGPU does for parameter-only changes).
 - Handing off the composer to `RenderSystem` via `scene.userData.ecsPostprocessingComposer` so the render pass uses it instead of the default `renderer.render()`.
 - Disposing old composers and passes when the configuration changes or the component is removed.
 
@@ -19,6 +19,8 @@ Builds and manages a THREE.js `EffectComposer` pipeline from the `Postprocessing
 
 ## Supported effects
 
+WebGL backend (the WebGPU mapping is on the [WebGPU and TSL page](../webgpu-and-tsl#post-processing-effects-per-backend)):
+
 | Effect | THREE.js pass |
 | --- | --- |
 | `bloom` | `UnrealBloomPass` |
@@ -30,12 +32,20 @@ Builds and manages a THREE.js `EffectComposer` pipeline from the `Postprocessing
 | `hueSaturation` | `ShaderPass` (HueSaturationShader) |
 | `sepia` | `ShaderPass` (SepiaShader) |
 | `vignette` | `ShaderPass` (VignetteShader) |
+| `chromAberration` | `ShaderPass` (RGBShiftShader) |
+| `pixelation` | Pixelation `ShaderPass` (block sampling, sized in device pixels) |
+| `smaa` | `SMAAPass`, placed right before `OutputPass` |
+| `toneMapping` | No pass: sets `renderer.toneMapping` / `toneMappingExposure`, which `OutputPass` applies |
+
+Pass order: render → `dof` → `bloom` → `vignette` → `hueSaturation` → `sepia` → `noise` → `dotScreen` → `ssao` → `glitch` → `chromAberration` → `pixelation` → `smaa` → `OutputPass`.
 
 ## Behavior notes
 
-- **Composer handoff** — when the composer is active, `scene.userData.ecsPostprocessingComposerActive` is set to `true` and `scene.userData.ecsPostprocessingComposer` holds the composer reference. `RenderSystem` checks this flag and delegates rendering to the composer instead of calling `renderer.render()` directly.
-- **Signature-based rebuild** — the full effect configuration is serialized each frame. The composer is only rebuilt when the signature changes, so parameter tweaks during runtime (e.g. adjusting bloom strength from the inspector) are applied efficiently.
-- **Cleanup** — when the `Postprocessing` component is removed from the scene, or when the composer is rebuilt, all existing passes are disposed and the composer is torn down.
+- **Composer handoff**: when the composer is active, `scene.userData.ecsPostprocessingComposerActive` is set to `true` and `scene.userData.ecsPostprocessingComposer` holds the chain (on WebGL, the `EffectComposer` itself). `RenderSystem` checks this flag and delegates rendering to the chain instead of calling `renderer.render()` directly. `scene.userData.ecsPostprocessing` holds the values it was built from.
+- **Signature-based rebuild**: the full effect configuration is serialized each frame and nothing happens while it is unchanged. On a change the WebGL backend rebuilds the composer; the WebGPU backend writes new parameters into its uniforms and rebuilds only when an effect is switched on or off.
+- **WebGPU without `webgpuBackend`**: the world warns once and builds no chain (tone mapping still applies through the renderer). `EffectComposer` never runs on a `WebGPURenderer`.
+- **Tone mapping**: the `toneMapping` effect (with `postEnabled` on) uses ACES Filmic unless `Environment.values.lighting.toneMapping` names an operator, and its `exposure` overrides the environment's. Turning the effect off hands the renderer back to the environment's settings, or to its original values when there are none.
+- **Cleanup**: when the `Postprocessing` component is removed from the scene, or when the composer is rebuilt, all existing passes are disposed and the composer is torn down.
 
 ## API reference
 

package/dist/docs/guide/systems/render-system.md

@@ -1,21 +1,22 @@
 # RenderSystem
 
-The final system in the update loop. Submits the frame to the WebGL renderer, delegating to an `EffectComposer` when postprocessing is active.
+The final system in the update loop. Submits the frame to the renderer (`WebGLRenderer` or `WebGPURenderer`), delegating to the post-processing chain when one is active.
 
 ## Overview
 
 `RenderSystem` runs **last** in the world update loop and is responsible for:
 
 - Calling `renderer.render(scene, camera)` to produce the final frame.
-- Detecting whether `PostprocessingSyncSystem` has placed an active `EffectComposer` on `scene.userData.ecsPostprocessingComposer`.
-- When a composer is active: resizing it to the current renderer element dimensions and calling `composer.render()` instead of the default render path.
+- Detecting whether `PostprocessingSyncSystem` (or a script) has placed an active chain on `scene.userData.ecsPostprocessingComposer`: an `EffectComposer` from the WebGL backend, a TSL `RenderPipeline` from [`webgpuBackend`](../webgpu-and-tsl), or any object with a `render()` method.
+- When a chain is active: resizing it to the current renderer element dimensions (if it has `setSize`) and calling its `render()` instead of the default render path.
 - Invoking an optional `afterRender` callback after every frame (used by editor overlays or custom render hooks).
 
 ## Behavior notes
 
-- **Composer precedence** — the system checks `scene.userData.ecsPostprocessingComposerActive` each frame. If `true`, the `EffectComposer` path is used; otherwise the standard `renderer.render()` path is used. This coupling with `PostprocessingSyncSystem` means both systems must be present for postprocessing to work.
-- **Dynamic resize** — before calling `composer.render()`, the system reads `renderer.domElement.clientWidth/Height` (clamped to `≥ 1`) and updates the composer size to match. This ensures the effect pipeline stays correct after window resizes without an explicit resize event handler.
-- **Ordering** — `RenderSystem` must be registered last in `World.setup`. All scene mutations (transform sync, visibility, etc.) must have already run.
+- **Composer precedence**: the system checks `scene.userData.ecsPostprocessingComposerActive` each frame. If `true`, the chain in `scene.userData.ecsPostprocessingComposer` renders the frame; otherwise the standard `renderer.render()` path is used. This coupling with `PostprocessingSyncSystem` means both systems must be present for postprocessing to work.
+- **Dynamic resize**: before calling `composer.render()`, the system reads `renderer.domElement.clientWidth/Height` (clamped to `≥ 1`) and the renderer's pixel ratio. It calls `composer.setPixelRatio` / `composer.setSize` only when one of them changed or the composer was rebuilt, and only when the chain has those methods. A WebGPU `RenderPipeline` has neither: it reads the renderer's size every frame.
+- **WebGPU start-up**: `WebGPURenderer.render()` throws until `await renderer.init()` has resolved. While `renderer.initialized` is `false` the system skips the frame (and `afterRender`) and warns once.
+- **Ordering**: `RenderSystem` must be registered last in `World.setup`. All scene mutations (transform sync, visibility, etc.) must have already run.
 
 ## API reference
 

package/dist/docs/guide/systems/script-behaviour-system.md

@@ -27,14 +27,16 @@ The system resolves the `Behaviour` constructor from the imported module using:
 2. `default` export as a fallback.
 3. A `__reluBehaviourClass` static marker check to handle cases where esbuild bundles a second copy of `@relu-interactives/spatial-ecs` into the script blob (breaking the `instanceof` identity check).
 
-If no valid `Behaviour` subclass is found the entry is skipped and an error is written to the console.
+If no valid `Behaviour` subclass is found, the entry goes to `"error"` with the message `Failed to load script: Missing Behaviour export ...` and the error is reported with phase `"load"`.
 
 ## Behavior notes
 
-- **Instance keying** — each script instance is keyed by `entityId + scriptUrl + className`. A new instance is created only when any of these three values changes.
-- **Error isolation** — errors thrown inside `init()` or `onUpdate()` are caught per-instance and logged to the console. A failing script does not crash the frame loop or affect other scripts.
-- **Destroyed entity cleanup** — when an entity is removed from the world, all of its script instances are destroyed and removed from the registry on the next update.
-- **Editor vs preview** — Behaviours execute **only** at preview/runtime. In an editor world (`isEditorMode()`), every `ScriptComponent` entry stays in `idle` state and `init()`/`onUpdate()` never run. For visuals that must render in the editor, use [`ScriptObjectSystem`](./script-object-system) + [`ScriptObject`](../authoring-a-script-object).
+- **Instance keying**: each script instance is keyed by `entityId + scriptUrl + className`. A new instance is created only when any of these three values changes.
+- **Error isolation**: errors thrown inside `init()` or `onUpdate()` are caught per-instance. A failing script does not crash the frame loop or affect other scripts. The entry's `runtimeState` becomes `"error"` and `runtimeMessage` holds the message.
+- **One log per distinct error**: the first occurrence of an error is logged with `console.error` (entity name and id, class, phase) and delivered to [`world.onScriptError`](../world-api#catch-script-errors) listeners. Repeats of the same error are not logged again.
+- **Retry backoff**: after a load, `init()` or `onUpdate()` error the system waits `DEFAULT_SCRIPT_ERROR_RETRY_DELAY` (1 s of world time) before it re-initialises the script. Pass `{ errorRetryDelay }` as the third constructor argument to change it. Disabling and re-enabling the entry retries at once.
+- **Destroyed entity cleanup**: when an entity is removed from the world, all of its script instances are destroyed and removed from the registry on the next update.
+- **Editor vs preview**: Behaviours execute **only** at preview/runtime. In an editor world (`isEditorMode()`), every `ScriptComponent` entry stays in `idle` state and `init()`/`onUpdate()` never run. For visuals that must render in the editor, use [`ScriptObjectSystem`](./script-object-system) + [`ScriptObject`](../authoring-a-script-object).
 
 ## API reference
 

package/dist/docs/guide/systems/script-object-system.md

@@ -13,6 +13,8 @@ For each entity with an enabled `ScriptObjectComponent` that has a `scriptUrl` +
 
 `runtimeState` is written **only on transitions** (never every frame). A `build()`/`update()` error sets `runtimeState: "error"` with a sanitized message and tombstones the record so a broken script doesn't reload every frame (cleared by a script/enabled change or `invalidate*()`).
 
+Each distinct error is logged once with `console.error` and delivered to [`world.onScriptError`](../world-api#catch-script-errors) listeners with `source: "scriptObject"` and phase `"load"`, `"init"`, `"build"` or `"update"`. `invalidate*()` also clears the reported-error memory for the affected scripts, so an error that survives a hot reload reports again.
+
 ## Keying
 
 Instances are keyed by **entity id** — a duplicated entity gets its own fresh instance, and two entities sharing one `scriptUrl` get independent instances.
@@ -48,5 +50,5 @@ world.setup({
 ## API reference
 
 - Class: [`ScriptObjectComponent`](../../api/components/classes/ScriptObjectComponent.md)
-- Base class: [`ScriptObject`](../../api/classes/ScriptObject.md)
+- Base class: [`ScriptObject`](../../api/index/classes/ScriptObject.md)
 - Source: [`core/systems/ScriptObjectSystem.ts`](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/main/core/systems/ScriptObjectSystem.ts)

package/dist/docs/guide/systems/video-system.md

@@ -9,7 +9,7 @@ Reconciles `VideoComponent` state with the underlying HTML `<video>` element and
 - Driving `play()`, `pause()`, and stop (pause + seek to 0) on the HTML `<video>` element based on the intent flags set by `VideoComponent.play()`, `.pause()`, and `.stop()`.
 - Detecting when a non-looping video ends naturally and resetting the component flags.
 - Syncing `loop`, `volume`, `width`, `height`, `positional`, `refDistance`, `distanceModel`, and `rolloffFactor` to the video element and THREE.js mesh material.
-- Updating the green-screen chroma key shader uniforms (`backgroundColor`, `similarity`, `smoothness`, `spill`) live when they change.
+- Updating the green-screen chroma key (`backgroundColor`, `similarity`, `smoothness`, `spill`) live when it changes. The keying material belongs to the world's render backend (a GLSL `ShaderMaterial` on WebGL, a TSL `MeshBasicNodeMaterial` with `webgpuBackend`), which applies the update.
 
 ## Queried components