@relu-interactives/spatial-ecs 0.2.2

package/dist/docs/guide/spawning/sphere.md

@@ -0,0 +1,29 @@
+# Sphere
+
+A radius `0.5` `THREE.SphereGeometry` (24 width × 24 height segments) with a default white `MeshStandardMaterial`.
+
+```ts
+import { Behaviour, ObjectManagementSystem } from "@relu-interactives/spatial-ecs";
+
+export default class SpawnSphere extends Behaviour {
+  init() {
+    const objects = this.world.getSystem(ObjectManagementSystem);
+    objects?.requestCreate("sphere", {
+      name: "Ball",
+      transform: { position: { x: 0, y: 0.5, z: 0 } },
+    });
+  }
+}
+```
+
+## Payload
+
+| Field | Type | Default | Description |
+| --- | --- | --- | --- |
+| `name` | `string` | `"Sphere"` | Display name. |
+| `transform` | `TransformData` | identity | Position / rotation (radians) / scale. |
+| `parentId` | `EntityId \| null` | `null` | Optional parent entity. |
+
+## Components attached
+
+`Transform`, `Object3DRef`, `Name`, `EntityType`, `ParentId`, `Selectable`, `Mesh`, `Material`, `MeshGeometry`.

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

@@ -0,0 +1,32 @@
+# Spot Light
+
+A cone-shaped light with adjustable angle, penumbra, and distance falloff.
+
+```ts
+import { Behaviour, ObjectManagementSystem } from "@relu-interactives/spatial-ecs";
+
+export default class SpawnSpot extends Behaviour {
+  init() {
+    const objects = this.world.getSystem(ObjectManagementSystem);
+    objects?.requestCreate("spotLight", {
+      name: "Stage",
+      transform: { position: { x: 0, y: 5, z: 0 } },
+    });
+  }
+}
+```
+
+## Payload
+
+| Field | Type | Default | Description |
+| --- | --- | --- | --- |
+| `name` | `string` | `"Spot Light"` | Display name. |
+| `transform.position` | `{ x, y, z }` | `(2, 5, 2)` | Light position (direction is `target − position`). |
+| `transform.rotation` / `scale` | — | identity | Standard transform fields. |
+| `parentId` | `EntityId \| null` | `null` | Optional parent entity. |
+
+Default color `#ffffff`, intensity `1`, distance `20`, angle `π/6`, penumbra `0.1`, decay `1`.
+
+## Components attached
+
+`Transform`, `Object3DRef`, `Name`, `EntityType`, `ParentId`, `Selectable`, `Light`.

package/dist/docs/guide/spawning/sprite.md

@@ -0,0 +1,31 @@
+# Sprite
+
+A camera-facing `THREE.Sprite` textured with an image. Always faces the active camera.
+
+```ts
+import { Behaviour, ObjectManagementSystem } from "@relu-interactives/spatial-ecs";
+
+export default class SpawnIcon extends Behaviour {
+  init() {
+    const objects = this.world.getSystem(ObjectManagementSystem);
+    objects?.requestCreate("sprite", {
+      name: "Marker",
+      path: "/assets/images/marker.png",
+      transform: { position: { x: 0, y: 2, z: 0 } },
+    });
+  }
+}
+```
+
+## Payload
+
+| Field | Type | Default | Description |
+| --- | --- | --- | --- |
+| `name` | `string` | `"Sprite"` | Display name. |
+| `path` | `string` | `""` | URL or local-asset path to the sprite image. |
+| `transform` | `TransformData` | identity | Position / rotation / scale. |
+| `parentId` | `EntityId \| null` | `null` | Optional parent entity. |
+
+## Components attached
+
+`Transform`, `Object3DRef`, `Name`, `EntityType`, `ParentId`, `Selectable`, `Sprite`.

package/dist/docs/guide/spawning/video.md

@@ -0,0 +1,53 @@
+# Video
+
+A textured plane playing a video file, with optional chroma-keying (green-screen) so you can composite the video over the live scene.
+
+```ts
+import { Behaviour, ObjectManagementSystem } from "@relu-interactives/spatial-ecs";
+
+export default class SpawnVideo extends Behaviour {
+  init() {
+    const objects = this.world.getSystem(ObjectManagementSystem);
+    objects?.requestCreate("video", {
+      name: "Promo",
+      path: "/assets/videos/promo.mp4",
+      transform: { position: { x: 0, y: 1.5, z: -3 } },
+      options: {
+        autoplay: true,
+        loop: true,
+        volume: 0.8,
+        width: 1.6,
+        height: 0.9,
+      },
+    });
+  }
+}
+```
+
+## Payload
+
+| Field | Type | Default | Description |
+| --- | --- | --- | --- |
+| `name` | `string` | `"Video"` | Display name. |
+| `path` | `string` | `""` | URL or local-asset path to the video file. |
+| `transform` | `TransformData` | identity | Position / rotation / scale. |
+| `parentId` | `EntityId \| null` | `null` | Optional parent entity. |
+
+### `options`
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `autoplay` | `boolean` | `false` | Start playback as soon as the video is ready. |
+| `loop` | `boolean` | `true` | Loop playback. |
+| `volume` | `number` (0–1) | `1` | Playback volume. |
+| `width` | `number` | `1` | Plane width in world units. |
+| `height` | `number` | `1` | Plane height in world units. |
+| `isGreenScreen` | `boolean` | `false` | Enable chroma-key shader. |
+| `backgroundColor` | `string` | `"#00ff00"` | Color to key out (CSS hex). |
+| `similarity` | `number` (0.01–1) | `0.4` | Chroma similarity threshold. |
+| `smoothness` | `number` (0.001–1) | `0.08` | Edge smoothing. |
+| `spill` | `number` (0–1) | `0.12` | Spill-suppression strength. |
+
+## Components attached
+
+`Transform`, `Object3DRef`, `Name`, `EntityType`, `ParentId`, `Selectable`, `Video`.

package/dist/docs/guide/system-overview.md

@@ -0,0 +1,73 @@
+# System Overview
+
+Every frame in `@relu-interactives/spatial-ecs` is driven by a deterministic sequence of systems. This catalog lists every system shipped in the package, grouped by responsibility. Each entry links to a dedicated page with queried components, behavior notes, and ordering details.
+
+> [!TIP]
+> Browsing the API? The auto-generated TypeDoc reference lives under [API Reference → systems](../api/index/index.md).
+
+## Entity lifecycle
+
+- [ObjectManagementSystem](./systems/object-management-system) — core entity lifecycle: flushes the creation queue, reconciles the THREE.js scene graph hierarchy, and maintains entity/component factory registries. **Runs first each frame.**
+
+## Transform & visibility
+
+- [TransformSyncSystem](./systems/transform-sync-system) — writes `TransformComponent` position, rotation, and scale to the linked THREE.js `Object3D` every frame.
+- [ObjectVisibilitySystem](./systems/object-visibility-system) — syncs the `Object3DRef` `visibility` flag to the THREE.js `Object3D.visible` property.
+
+## Geometry & rendering
+
+- [MeshGeometrySystem](./systems/mesh-geometry-system) — creates and updates `BufferGeometry` on primitive mesh entities from their `MeshGeometryComponent` kind and parameters.
+- [MaterialSyncSystem](./systems/material-sync-system) — applies `MaterialComponent` authoring values (type, PBR properties, texture slots) to THREE.js materials.
+- [LightSyncSystem](./systems/light-sync-system) — syncs `LightComponent` values to THREE.js light objects (directional, ambient, point, spot, hemisphere, area).
+- [EnvironmentSyncSystem](./systems/environment-sync-system) — applies the scene-level `Environment` component (background, fog, HDRI) to the THREE.js scene.
+- [PostprocessingSyncSystem](./systems/postprocessing-sync-system) — builds and manages an `EffectComposer` pipeline from the `Postprocessing` component state.
+- [RenderSystem](./systems/render-system) — final system in the loop; submits the frame to the WebGL renderer. **Runs last each frame.**
+
+## Animation
+
+- [AnimationSystem](./systems/animation-system) — drives the `AnimationStateMachine` for entities with `AnimationComponent`: advances the THREE.js `AnimationMixer`, loads clip sources, and applies cross-fade transitions.
+
+## Camera
+
+- [CameraSyncSystem](./systems/camera-sync-system) — syncs `CameraComponent` authoring values to the live THREE.js camera (perspective and orthographic).
+
+## Physics
+
+- [PhysicsSyncSystem](./systems/physics-sync-system) — initializes the Rapier physics world, creates rigid bodies and colliders from `PhysicsComponent` state, steps the simulation, and writes results back to entity transforms.
+
+## Audio & video
+
+- [AudioSystem](./systems/audio-system) — reconciles `AudioComponent` state with THREE.js positional audio objects. **Preview mode only.**
+- [VideoSystem](./systems/video-system) — reconciles `VideoComponent` state with the HTML `<video>` element and THREE.js mesh/material. **Preview mode only.**
+
+## Scripting
+
+- [ScriptBehaviourSystem](./systems/script-behaviour-system) — dynamically imports user-authored Behaviour scripts, instantiates their classes, and drives the full lifecycle (`init`, `onUpdate`, `onDestroy`) each frame.
+
+## Input
+
+- [InputSystem](./systems/input-system) — captures and normalizes keyboard and mouse events, exposing them via direct methods on `this.world` (e.g. `this.world.getKey()`, `this.world.getMouseDown()`) inside Behaviour scripts.
+
+## System execution order
+
+Systems run in the following order each frame. You can inspect and extend this ordering via `World.setup`.
+
+| Order | System |
+|-------|--------|
+| 1 | `ObjectManagementSystem` |
+| 2 | `MeshGeometrySystem` |
+| 3 | *(custom systems)* |
+| 4 | `TransformSyncSystem` |
+| 5 | `ObjectVisibilitySystem` |
+| 6 | `LightSyncSystem` |
+| 7 | `MaterialSyncSystem` |
+| 8 | `CameraSyncSystem` |
+| 9 | `EnvironmentSyncSystem` |
+| 10 | `PostprocessingSyncSystem` |
+| 11 | `AnimationSystem` |
+| 12 | `PhysicsSyncSystem` |
+| 13 | `AudioSystem` |
+| 14 | `VideoSystem` |
+| 15 | `ScriptBehaviourSystem` |
+| 16 | `InputSystem` |
+| 17 | `RenderSystem` |

package/dist/docs/guide/systems/_sidebar.json

@@ -0,0 +1,66 @@
+[
+  {
+    "text": "AnimationSystem",
+    "link": "/guide/systems/animation-system"
+  },
+  {
+    "text": "AudioSystem",
+    "link": "/guide/systems/audio-system"
+  },
+  {
+    "text": "CameraSyncSystem",
+    "link": "/guide/systems/camera-sync-system"
+  },
+  {
+    "text": "EnvironmentSyncSystem",
+    "link": "/guide/systems/environment-sync-system"
+  },
+  {
+    "text": "InputSystem",
+    "link": "/guide/systems/input-system"
+  },
+  {
+    "text": "LightSyncSystem",
+    "link": "/guide/systems/light-sync-system"
+  },
+  {
+    "text": "MaterialSyncSystem",
+    "link": "/guide/systems/material-sync-system"
+  },
+  {
+    "text": "MeshGeometrySystem",
+    "link": "/guide/systems/mesh-geometry-system"
+  },
+  {
+    "text": "ObjectManagementSystem",
+    "link": "/guide/systems/object-management-system"
+  },
+  {
+    "text": "ObjectVisibilitySystem",
+    "link": "/guide/systems/object-visibility-system"
+  },
+  {
+    "text": "PhysicsSyncSystem",
+    "link": "/guide/systems/physics-sync-system"
+  },
+  {
+    "text": "PostprocessingSyncSystem",
+    "link": "/guide/systems/postprocessing-sync-system"
+  },
+  {
+    "text": "RenderSystem",
+    "link": "/guide/systems/render-system"
+  },
+  {
+    "text": "ScriptBehaviourSystem",
+    "link": "/guide/systems/script-behaviour-system"
+  },
+  {
+    "text": "TransformSyncSystem",
+    "link": "/guide/systems/transform-sync-system"
+  },
+  {
+    "text": "VideoSystem",
+    "link": "/guide/systems/video-system"
+  }
+]

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

@@ -0,0 +1,32 @@
+# AnimationSystem
+
+Drives the animation state machine for every entity that has an `AnimationComponent`. Each frame it advances the THREE.js `AnimationMixer`, processes clip source loads (model clips and external GLTF sources), and applies the active state's cross-fade transitions.
+
+## Overview
+
+`AnimationSystem` runs every frame and is responsible for:
+
+- Loading clips from external GLTF sources on demand and merging them with model-embedded clips.
+- Building and maintaining a `THREE.AnimationMixer` per entity.
+- Playing, pausing, stopping, and reversing clips via `THREE.AnimationAction`.
+- Executing cross-fades between animation states using the state machine configured on `AnimationComponent`.
+- Replaying the last persisted state after hydration (saved `activeState`, `paused`, `reverse`, `timeScale`).
+
+## Queried components
+
+| Component | Access |
+| --- | --- |
+| [`AnimationComponent`](../components/animation) | Read + mutate (`clips`, `clipCatalog`, `availableClips`, mixer state) |
+| [`ModelComponent`](../components/model) | Read (source URL, loaded model clips) |
+
+## Behavior notes
+
+- **Editor vs preview** — the system runs in both editor and preview runtimes. In the editor it powers the viewport animation preview. In preview it drives live playback.
+- **External clip sources** — if `AnimationComponent.externalClipSources` lists remote URLs, the system loads each via `GLTFLoader` (with optional DRACO support). Loaded clips are merged into the entity's catalog and catalog entries are kept stable across reloads.
+- **State machine** — transitions call `THREE.AnimationAction.crossFadeTo()` using `AnimationComponent.crossFadeDuration`. The active action's time scale is negated automatically when `reverse` is `true`.
+- **Delta time clamping** — the delta time passed to each mixer is clamped to `[0, +∞)` and non-finite values are treated as `0` to prevent unstable playback after tab focus returns.
+
+## API reference
+
+- Class: [`AnimationComponent`](../../api/components/classes/AnimationComponent.md)
+- Source: [`core/systems/AnimationSystem.ts`](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/main/core/systems/AnimationSystem.ts)

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

@@ -0,0 +1,28 @@
+# AudioSystem
+
+Reconciles `AudioComponent` state with the underlying THREE.js positional audio objects each frame. Only active in **preview** mode — editor viewports are unaffected.
+
+## Overview
+
+`AudioSystem` runs every frame in preview and is responsible for:
+
+- Driving `play()`, `pause()`, and `stop()` on the THREE.js `PositionalAudio` node based on the intent flags set by `AudioComponent.play()`, `.pause()`, and `.stop()`.
+- Detecting when a non-looping clip ends naturally (THREE.js stops on its own) and resetting component state accordingly.
+- Syncing `loop`, `pitch`, `volume`, `refDistance`, `distanceModel`, and `rolloffFactor` to the live audio node whenever they change. Changes take effect on the next frame.
+
+## Queried components
+
+| Component | Access |
+| --- | --- |
+| [`AudioComponent`](../components/audio) | Read + mutate (`isPlaying`, `isPaused` flags; option properties) |
+
+## Behavior notes
+
+- **Editor skip** — when constructed with `{ isEditor: true }` the `update` method returns immediately, so no audio state is applied in the editor.
+- **Natural end detection** — the system compares the THREE.js `isPlaying` state between frames. If the audio node stopped on its own while the component still believed it was playing (and not paused), the component flags are reset and a warning is suppressed.
+- **Change detection** — option sync uses a per-entity snapshot from the previous frame, so `AudioComponent` options can be mutated freely in scripts without causing redundant THREE.js calls on every frame.
+
+## API reference
+
+- Class: [`AudioComponent`](../../api/components/classes/AudioComponent.md)
+- Source: [`core/systems/AudioSystem.ts`](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/main/core/systems/AudioSystem.ts)

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

@@ -0,0 +1,31 @@
+# CameraSyncSystem
+
+Syncs `CameraComponent` authoring values to the live THREE.js camera object each frame, handling both perspective and orthographic projection modes.
+
+## Overview
+
+`CameraSyncSystem` runs every frame and is responsible for:
+
+- Updating `fov`, `near`, `far`, and `zoom` on `THREE.PerspectiveCamera` from the component values.
+- Updating `left`, `right`, `top`, `bottom`, `near`, `far`, and `zoom` on `THREE.OrthographicCamera`.
+- Clamping all values to safe ranges (`near ≥ 0.001`, `far > near`, `fov` in `[1, 179]`, `zoom ≥ 0.001`) so an invalid inspector value never breaks the camera projection matrix.
+- Normalizing orthographic bounds so that `right > left` and `top > bottom` are always satisfied.
+- Calling `updateProjectionMatrix()` whenever a change is detected.
+
+## Queried components
+
+| Component | Access |
+| --- | --- |
+| [`CameraComponent`](../components/camera) | Read + sanitize (clamps written back to component fields) |
+| [`Object3DRef`](../components/object3d-ref) | Read (the live THREE.js camera object) |
+
+## Behavior notes
+
+- **Projection type** — the system checks the concrete type of the object in `Object3DRef` (`instanceof THREE.PerspectiveCamera` / `THREE.OrthographicCamera`) and applies the matching update path. If neither type matches, the entity is skipped.
+- **Aspect ratio** — perspective cameras auto-update aspect from `window.innerWidth / window.innerHeight` each frame when a window is available.
+- **Change detection** — property values are compared before writing to avoid redundant `updateProjectionMatrix()` calls on every frame.
+
+## API reference
+
+- Class: [`CameraComponent`](../../api/components/classes/CameraComponent.md)
+- Source: [`core/systems/CameraSyncSystem.ts`](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/main/core/systems/CameraSyncSystem.ts)

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

@@ -0,0 +1,31 @@
+# EnvironmentSyncSystem
+
+Applies the scene-level `Environment` component to the THREE.js scene each frame — background color, gradient textures, HDRI environment maps, and fog.
+
+## 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`.
+- 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.
+
+## Queried components
+
+| Component | Access |
+| --- | --- |
+| [`Environment`](../scene/environment) | Read (background type, colors, fog state) |
+
+## 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.
+
+## API reference
+
+- Class: [`Environment`](../../api/components/classes/Environment.md)
+- Source: [`core/systems/EnvironmentSyncSystem.ts`](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/main/core/systems/EnvironmentSyncSystem.ts)

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

@@ -0,0 +1,217 @@
+# InputSystem
+
+Captures and normalizes keyboard and mouse input events from the browser, then exposes a clean query API accessible directly on `this.world` inside Behaviour scripts.
+
+## Overview
+
+`InputSystem` manages input state for the current frame and is responsible for:
+
+- Listening to `keydown` / `keyup` DOM events and tracking which keys are currently held, newly pressed (`down`), or just released (`up`) this frame.
+- Listening to `mousedown` / `mouseup` / `mousemove` / `wheel` events for left, middle, and right buttons plus pointer position and scroll deltas.
+- Flushing pending input changes at the start of each frame so `getKeyDown` / `getKeyUp` are only `true` for a single frame.
+- Providing pointer-lock support: when a lock target element is set, mouse position and delta calculations are bounded to that element's rect.
+
+## API exposed to scripts
+
+Call these methods directly on `this.world` from any Behaviour script. There is no `world.input` accessor.
+
+| Method | Description |
+| --- | --- |
+| `this.world.getKey(key)` | `true` while the key is held this frame. |
+| `this.world.getKeyDown(key)` | `true` only on the first frame the key is pressed. |
+| `this.world.getKeyUp(key)` | `true` only on the frame the key is released. |
+| `this.world.getMouse(button)` | `true` while the mouse button is held. |
+| `this.world.getMouseDown(button)` | `true` only on the first frame the button is pressed. |
+| `this.world.getMouseUp(button)` | `true` only on the frame the button is released. |
+| `this.world.getMousePosition()` | `{ x, y }` in viewport pixels. |
+| `this.world.getMouseDelta()` | `{ x, y }` movement delta since the previous frame. |
+| `this.world.consumeMouseDelta()` | `{ x, y }` movement delta; zeroes after reading. |
+| `this.world.getScrollDelta()` | `{ x, y }` scroll delta since the previous frame. |
+
+Mouse buttons can be specified as `"left"`, `"middle"`, or `"right"` (or the numeric indices `0`, `1`, `2`).
+
+## KeyboardKeys reference
+
+Import `KeyboardKeys` from `@relu-interactives/spatial-ecs` to access all available key constants with full TypeScript autocomplete.
+
+```ts
+import { KeyboardKeys } from "@relu-interactives/spatial-ecs";
+```
+
+### Letters
+
+| Constant | Value |
+| --- | --- |
+| `KeyboardKeys.A` … `KeyboardKeys.Z` | `"a"` … `"z"` |
+
+### Digits
+
+| Constant | Value |
+| --- | --- |
+| `KeyboardKeys.Digit0` … `KeyboardKeys.Digit9` | `"0"` … `"9"` |
+
+### Navigation & editing
+
+| Constant | Value |
+| --- | --- |
+| `KeyboardKeys.ArrowUp` | `"arrowup"` |
+| `KeyboardKeys.ArrowDown` | `"arrowdown"` |
+| `KeyboardKeys.ArrowLeft` | `"arrowleft"` |
+| `KeyboardKeys.ArrowRight` | `"arrowright"` |
+| `KeyboardKeys.Space` | `" "` |
+| `KeyboardKeys.Enter` | `"enter"` |
+| `KeyboardKeys.Escape` | `"escape"` |
+| `KeyboardKeys.Tab` | `"tab"` |
+| `KeyboardKeys.Backspace` | `"backspace"` |
+| `KeyboardKeys.Delete` | `"delete"` |
+| `KeyboardKeys.Insert` | `"insert"` |
+| `KeyboardKeys.Home` | `"home"` |
+| `KeyboardKeys.End` | `"end"` |
+| `KeyboardKeys.PageUp` | `"pageup"` |
+| `KeyboardKeys.PageDown` | `"pagedown"` |
+
+### Modifier keys
+
+Generic variants match either left or right physical key. Use the specific variants when the side matters.
+
+| Constant | Value | Notes |
+| --- | --- | --- |
+| `KeyboardKeys.Shift` | `"shift"` | Either shift key |
+| `KeyboardKeys.ShiftLeft` | `"shiftleft"` | Left Shift only |
+| `KeyboardKeys.ShiftRight` | `"shiftright"` | Right Shift only |
+| `KeyboardKeys.Control` | `"control"` | Either Ctrl key |
+| `KeyboardKeys.ControlLeft` | `"controlleft"` | Left Ctrl only |
+| `KeyboardKeys.ControlRight` | `"controlright"` | Right Ctrl only |
+| `KeyboardKeys.Alt` | `"alt"` | Alt / Option |
+| `KeyboardKeys.Meta` | `"meta"` | Cmd (macOS) / Win (Windows) |
+| `KeyboardKeys.CapsLock` | `"capslock"` | |
+
+### Function keys
+
+| Constant | Value |
+| --- | --- |
+| `KeyboardKeys.F1` … `KeyboardKeys.F12` | `"f1"` … `"f12"` |
+
+### Punctuation & symbols
+
+| Constant | Value |
+| --- | --- |
+| `KeyboardKeys.Minus` | `"-"` |
+| `KeyboardKeys.Equal` | `"="` |
+| `KeyboardKeys.BracketLeft` | `"["` |
+| `KeyboardKeys.BracketRight` | `"]"` |
+| `KeyboardKeys.Backslash` | `"\\"` |
+| `KeyboardKeys.Semicolon` | `";"` |
+| `KeyboardKeys.Quote` | `"'"` |
+| `KeyboardKeys.Backquote` | `` "`" `` |
+| `KeyboardKeys.Comma` | `","` |
+| `KeyboardKeys.Period` | `"."` |
+| `KeyboardKeys.Slash` | `"/"` |
+
+### Other
+
+| Constant | Value |
+| --- | --- |
+| `KeyboardKeys.NumLock` | `"numlock"` |
+| `KeyboardKeys.ScrollLock` | `"scrolllock"` |
+| `KeyboardKeys.Pause` | `"pause"` |
+| `KeyboardKeys.PrintScreen` | `"printscreen"` |
+| `KeyboardKeys.ContextMenu` | `"contextmenu"` |
+
+## Script examples
+
+### Basic movement
+
+Move an object along the X/Z plane with WASD and sprint with Shift.
+
+```ts
+import { KeyboardKeys, Behaviour } from "@relu-interactives/spatial-ecs";
+
+export default class PlayerMovement extends Behaviour {
+  speed = 5;
+  sprintMultiplier = 2;
+
+  protected onUpdate() {
+    const sprint = this.world.getKey(KeyboardKeys.Shift) ? this.sprintMultiplier : 1;
+    const step = this.speed * sprint * this.deltaTime;
+
+    if (this.world.getKey(KeyboardKeys.W)) this.transform.position.z -= step;
+    if (this.world.getKey(KeyboardKeys.S)) this.transform.position.z += step;
+    if (this.world.getKey(KeyboardKeys.A)) this.transform.position.x -= step;
+    if (this.world.getKey(KeyboardKeys.D)) this.transform.position.x += step;
+  }
+}
+```
+
+### One-shot action on key press
+
+Toggle visibility on Space, fire on left-click.
+
+```ts
+import { KeyboardKeys, Behaviour } from "@relu-interactives/spatial-ecs";
+
+export default class ActionHandler extends Behaviour {
+  protected onUpdate() {
+    // getKeyDown fires only on the first frame the key is pressed.
+    if (this.world.getKeyDown(KeyboardKeys.Space)) {
+      this.transform.visible = !this.transform.visible;
+    }
+
+    // Left mouse button
+    if (this.world.getMouseDown("left")) {
+      console.log("Fired!");
+    }
+  }
+}
+```
+
+### Distinguishing left vs right modifier
+
+```ts
+import { KeyboardKeys, Behaviour } from "@relu-interactives/spatial-ecs";
+
+export default class ModifierDemo extends Behaviour {
+  protected onUpdate() {
+    if (this.world.getKeyDown(KeyboardKeys.ControlLeft)) {
+      console.log("Left Ctrl pressed");
+    }
+
+    if (this.world.getKeyDown(KeyboardKeys.ControlRight)) {
+      console.log("Right Ctrl pressed");
+    }
+
+    // Generic: matches either left or right Shift
+    if (this.world.getKey(KeyboardKeys.Shift)) {
+      console.log("A Shift key is held");
+    }
+  }
+}
+```
+
+### Reading mouse delta (camera look)
+
+```ts
+import { Behaviour } from "@relu-interactives/spatial-ecs";
+
+export default class CameraLook extends Behaviour {
+  sensitivity = 0.002;
+
+  protected onUpdate() {
+    const { x, y } = this.world.consumeMouseDelta();
+    this.transform.rotation.y -= x * this.sensitivity;
+    this.transform.rotation.x -= y * this.sensitivity;
+  }
+}
+```
+
+## Behavior notes
+
+- **Frame flush** — pending input queued during the previous frame's browser event callbacks is promoted to the current frame's `down`/`up` sets at the start of `update()`. This guarantees `getKeyDown` is never missed even if the frame rate drops.
+- **Key normalization** — key names are lowercased before storage so `"ArrowUp"` and `"arrowup"` are treated identically.
+- **Left/right modifiers** — the system tracks both `event.key` (e.g. `"shift"`) and `event.code` (e.g. `"shiftleft"`) so generic and specific modifier queries both work simultaneously.
+- **Register / unregister** — call `register(element)` to attach all DOM listeners to a specific element, and `unregister()` to remove them. This should be called during world setup and teardown.
+
+## API reference
+
+- Source: [`core/systems/InputSystem.ts`](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/main/core/systems/InputSystem.ts)
+- Related: [`KeyboardKey`](../../api/index/type-aliases/KeyboardKey.md) type alias for valid key string constants.

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

@@ -0,0 +1,29 @@
+# LightSyncSystem
+
+Applies `LightComponent` authoring values to the underlying THREE.js light objects each frame, supporting directional, ambient, point, spot, hemisphere, and area light types.
+
+## Overview
+
+`LightSyncSystem` runs every frame and is responsible for:
+
+- Writing `color`, `intensity`, `castShadow`, and `frustumCulled` to every light object.
+- Writing `distance` and `decay` for `THREE.PointLight` and `THREE.SpotLight`.
+- Writing `angle` and `penumbra` for `THREE.SpotLight`.
+- Writing `width` and `height` for `THREE.RectAreaLight`.
+
+## Queried components
+
+| Component | Access |
+| --- | --- |
+| [`LightComponent`](../components/light) | Read (`values` sub-state) |
+
+## 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.
+
+## API reference
+
+- Class: [`LightComponent`](../../api/components/classes/LightComponent.md)
+- Source: [`core/systems/LightSyncSystem.ts`](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/main/core/systems/LightSyncSystem.ts)