@relu-interactives/spatial-ecs 0.4.5 → 0.5.1

package/dist/components/index.d.cts

@@ -1,6 +1,6 @@
-export { A as AnimationComponent, a as AnimationComponentOptions, b as AudioComponent, C as CameraComponent, c as CameraComponentOptions, d as CameraProjection, e as CameraRuntimeType, f as ColliderShape, g as ColliderState, h as CubeMeshParameters, D as DEFAULT_COLLIDER_STATE, i as DEFAULT_INSTANCED_MESH_PARAMETERS, j as DEFAULT_INSTANCE_TRANSFORM, k as DEFAULT_MESH_GEOMETRY_PARAMETERS, l as DEFAULT_PHYSICS_STATE, m as DEFAULT_POSE_CURLS, n as DEFAULT_POSE_DIRECTIONS, o as DEFAULT_RIGIDBODY_STATE, E as EditableMeshObjectKind, p as EntityType, I as ImageComponent, q as ImageTarget, r as ImageTargetAnchor, s as ImageTargetAnchorOptions, t as ImageTargetReference, u as InstanceSlotComponent, v as InstanceTransform, w as InstancedMeshComponent, x as InstancedMeshKind, L as LightComponent, y as LightValueState, M as MaterialComponent, z as MaterialTypeValue, B as MaterialValueState, F as MeshComponent, G as MeshGeometryComponent, H as MeshGeometryParameters, J as MeshGeometryParametersByKind, K as ModelComponent, N as Name, O as Object3DRef, P as PhysicsComponent, Q as PhysicsState, R as PlaneMeshParameters, S as RadiusHeightMeshParameters, T as RadiusMeshParameters, U as RigidbodyState, V as RigidbodyType, W as ScriptComponent, X as ScriptEntry, Y as ScriptObjectComponent, Z as ScriptObjectComponentInput, _ as ScriptObjectRuntimeState, $ as Selectable, a0 as SelectionTransformState, a1 as SpriteComponent, a2 as TextureFilteringValue, a3 as TransformModeValue, a4 as TransformSpaceValue, a5 as VRTeleportAreaComponent, a6 as VRTeleportAreaOptions, a7 as VideoComponent, a8 as VrTeleportShape, a9 as XRAnchorComponent, aa as XRAnchorOptions, ab as XRHandPoseComponent, ac as XRHandPoseOptions, ad as XRInteractableComponent, ae as XRInteractableOptions, af as XRInteractorComponent, ag as XRInteractorOptions, ah as XRInteractorSideComponent, ai as XRRigComponent, aj as XRRigOptions, ak as XrAttachPoint, al as XrDistanceGrabBehavior, am as XrEnvironmentPhysics, an as XrGrabGesture, ao as XrGrabHands, ap as XrGrabReach, aq as XrHandPoseEntry, ar as XrHandPreset, as as XrInteractorSide, at as XrInteractorType, au as XrLocomotionMode, av as XrTrackingOrigin, aw as XrTwoHandRotation, ax as createAttachPoint, ay as createHandPoseEntry, az as defaultMaterialValue, aA as handPoseDefinitionFor, aB as normalizePhysicsState, aC as setPhysicsLiveRef } from '../XRHandPose-CxPv-LBo.cjs';
-export { D as DEFAULT_ENVIRONMENT_STATE, a as DEFAULT_POSTPROCESSING_STATE, E as Environment, b as EnvironmentFogState, c as EnvironmentFogType, d as EnvironmentGradientEffect, e as EnvironmentSkyboxState, f as EnvironmentSkyboxType, g as EnvironmentState, P as ParentId, h as Postprocessing, i as PostprocessingState, T as TransformComponent, j as TransformData, V as Vec3 } from '../System-ln4Q7Eot.cjs';
-export { P as PrefabInstance, a as PrefabNode, X as XREnvironmentComponent, b as XrEnvironmentKind, c as XrEnvironmentOrientation } from '../index-CQsHUez3.cjs';
+export { A as AnimationComponent, a as AnimationComponentOptions, b as AudioComponent, C as CameraComponent, c as CameraComponentOptions, d as CameraProjection, e as CameraRuntimeType, f as ColliderShape, g as ColliderState, h as CubeMeshParameters, D as DEFAULT_COLLIDER_STATE, i as DEFAULT_INSTANCED_MESH_PARAMETERS, j as DEFAULT_INSTANCE_TRANSFORM, k as DEFAULT_MESH_GEOMETRY_PARAMETERS, l as DEFAULT_PHYSICS_STATE, m as DEFAULT_POSE_CURLS, n as DEFAULT_POSE_DIRECTIONS, o as DEFAULT_RIGIDBODY_STATE, E as EditableMeshObjectKind, p as EntityType, I as ImageComponent, q as ImageTarget, r as ImageTargetAnchor, s as ImageTargetAnchorOptions, t as ImageTargetReference, u as InstanceSlotComponent, v as InstanceTransform, w as InstancedMeshComponent, x as InstancedMeshKind, L as LightComponent, y as LightValueState, M as MaterialComponent, z as MaterialTypeValue, B as MaterialValueState, F as MeshComponent, G as MeshGeometryComponent, H as MeshGeometryParameters, J as MeshGeometryParametersByKind, K as ModelComponent, N as Name, O as Object3DRef, P as PhysicsComponent, Q as PhysicsState, R as PlaneMeshParameters, S as RadiusHeightMeshParameters, T as RadiusMeshParameters, U as RigidbodyState, V as RigidbodyType, W as ScriptComponent, X as ScriptEntry, Y as ScriptObjectComponent, Z as ScriptObjectComponentInput, _ as ScriptObjectRuntimeState, $ as Selectable, a0 as SelectionTransformState, a1 as SpriteComponent, a2 as TextureFilteringValue, a3 as TransformModeValue, a4 as TransformSpaceValue, a5 as UIButtonComponent, a6 as UIButtonOptions, a7 as UIPanelComponent, a8 as UIPanelOptions, a9 as UISliderComponent, aa as UISliderOptions, ab as UITextComponent, ac as UITextOptions, ad as UIToggleComponent, ae as UIToggleOptions, af as UiFollowMode, ag as UiTextAlign, ah as UiTextVAlign, ai as VRTeleportAreaComponent, aj as VRTeleportAreaOptions, ak as VideoComponent, al as VrTeleportShape, am as XRAnchorComponent, an as XRAnchorOptions, ao as XRHandPoseComponent, ap as XRHandPoseOptions, aq as XRInteractableComponent, ar as XRInteractableOptions, as as XRInteractorComponent, at as XRInteractorOptions, au as XRInteractorSideComponent, av as XRRigComponent, aw as XRRigOptions, ax as XrAttachPoint, ay as XrDistanceGrabBehavior, az as XrEnvironmentPhysics, aA as XrGrabGesture, aB as XrGrabHands, aC as XrGrabReach, aD as XrHandPoseEntry, aE as XrHandPreset, aF as XrInteractorSide, aG as XrInteractorType, aH as XrLocomotionMode, aI as XrTrackingOrigin, aJ as XrTwoHandRotation, aK as createAttachPoint, aL as createHandPoseEntry, aM as defaultMaterialValue, aN as handPoseDefinitionFor, aO as normalizePhysicsState, aP as setPhysicsLiveRef } from '../XRHandPose-CQTLGxFC.cjs';
+export { D as DEFAULT_ENVIRONMENT_STATE, a as DEFAULT_POSTPROCESSING_STATE, E as Environment, b as EnvironmentFogState, c as EnvironmentFogType, d as EnvironmentGradientEffect, e as EnvironmentSkyboxState, f as EnvironmentSkyboxType, g as EnvironmentState, P as ParentId, h as Postprocessing, i as PostprocessingState, T as TransformComponent, j as TransformData, V as Vec3 } from '../System-V_mv07le.cjs';
+export { P as PrefabInstance, a as PrefabNode, X as XREnvironmentComponent, b as XrEnvironmentKind, c as XrEnvironmentOrientation } from '../index-Dlr-7-4m.cjs';
 import 'three';
 import '@dimforge/rapier3d-compat';
 import '../handPose-DlcTtqgx.cjs';

package/dist/components/index.d.ts

@@ -1,6 +1,6 @@
-export { A as AnimationComponent, a as AnimationComponentOptions, b as AudioComponent, C as CameraComponent, c as CameraComponentOptions, d as CameraProjection, e as CameraRuntimeType, f as ColliderShape, g as ColliderState, h as CubeMeshParameters, D as DEFAULT_COLLIDER_STATE, i as DEFAULT_INSTANCED_MESH_PARAMETERS, j as DEFAULT_INSTANCE_TRANSFORM, k as DEFAULT_MESH_GEOMETRY_PARAMETERS, l as DEFAULT_PHYSICS_STATE, m as DEFAULT_POSE_CURLS, n as DEFAULT_POSE_DIRECTIONS, o as DEFAULT_RIGIDBODY_STATE, E as EditableMeshObjectKind, p as EntityType, I as ImageComponent, q as ImageTarget, r as ImageTargetAnchor, s as ImageTargetAnchorOptions, t as ImageTargetReference, u as InstanceSlotComponent, v as InstanceTransform, w as InstancedMeshComponent, x as InstancedMeshKind, L as LightComponent, y as LightValueState, M as MaterialComponent, z as MaterialTypeValue, B as MaterialValueState, F as MeshComponent, G as MeshGeometryComponent, H as MeshGeometryParameters, J as MeshGeometryParametersByKind, K as ModelComponent, N as Name, O as Object3DRef, P as PhysicsComponent, Q as PhysicsState, R as PlaneMeshParameters, S as RadiusHeightMeshParameters, T as RadiusMeshParameters, U as RigidbodyState, V as RigidbodyType, W as ScriptComponent, X as ScriptEntry, Y as ScriptObjectComponent, Z as ScriptObjectComponentInput, _ as ScriptObjectRuntimeState, $ as Selectable, a0 as SelectionTransformState, a1 as SpriteComponent, a2 as TextureFilteringValue, a3 as TransformModeValue, a4 as TransformSpaceValue, a5 as VRTeleportAreaComponent, a6 as VRTeleportAreaOptions, a7 as VideoComponent, a8 as VrTeleportShape, a9 as XRAnchorComponent, aa as XRAnchorOptions, ab as XRHandPoseComponent, ac as XRHandPoseOptions, ad as XRInteractableComponent, ae as XRInteractableOptions, af as XRInteractorComponent, ag as XRInteractorOptions, ah as XRInteractorSideComponent, ai as XRRigComponent, aj as XRRigOptions, ak as XrAttachPoint, al as XrDistanceGrabBehavior, am as XrEnvironmentPhysics, an as XrGrabGesture, ao as XrGrabHands, ap as XrGrabReach, aq as XrHandPoseEntry, ar as XrHandPreset, as as XrInteractorSide, at as XrInteractorType, au as XrLocomotionMode, av as XrTrackingOrigin, aw as XrTwoHandRotation, ax as createAttachPoint, ay as createHandPoseEntry, az as defaultMaterialValue, aA as handPoseDefinitionFor, aB as normalizePhysicsState, aC as setPhysicsLiveRef } from '../XRHandPose-BImIa4ZS.js';
-export { D as DEFAULT_ENVIRONMENT_STATE, a as DEFAULT_POSTPROCESSING_STATE, E as Environment, b as EnvironmentFogState, c as EnvironmentFogType, d as EnvironmentGradientEffect, e as EnvironmentSkyboxState, f as EnvironmentSkyboxType, g as EnvironmentState, P as ParentId, h as Postprocessing, i as PostprocessingState, T as TransformComponent, j as TransformData, V as Vec3 } from '../System-ln4Q7Eot.js';
-export { P as PrefabInstance, a as PrefabNode, X as XREnvironmentComponent, b as XrEnvironmentKind, c as XrEnvironmentOrientation } from '../index-CuGqxuk-.js';
+export { A as AnimationComponent, a as AnimationComponentOptions, b as AudioComponent, C as CameraComponent, c as CameraComponentOptions, d as CameraProjection, e as CameraRuntimeType, f as ColliderShape, g as ColliderState, h as CubeMeshParameters, D as DEFAULT_COLLIDER_STATE, i as DEFAULT_INSTANCED_MESH_PARAMETERS, j as DEFAULT_INSTANCE_TRANSFORM, k as DEFAULT_MESH_GEOMETRY_PARAMETERS, l as DEFAULT_PHYSICS_STATE, m as DEFAULT_POSE_CURLS, n as DEFAULT_POSE_DIRECTIONS, o as DEFAULT_RIGIDBODY_STATE, E as EditableMeshObjectKind, p as EntityType, I as ImageComponent, q as ImageTarget, r as ImageTargetAnchor, s as ImageTargetAnchorOptions, t as ImageTargetReference, u as InstanceSlotComponent, v as InstanceTransform, w as InstancedMeshComponent, x as InstancedMeshKind, L as LightComponent, y as LightValueState, M as MaterialComponent, z as MaterialTypeValue, B as MaterialValueState, F as MeshComponent, G as MeshGeometryComponent, H as MeshGeometryParameters, J as MeshGeometryParametersByKind, K as ModelComponent, N as Name, O as Object3DRef, P as PhysicsComponent, Q as PhysicsState, R as PlaneMeshParameters, S as RadiusHeightMeshParameters, T as RadiusMeshParameters, U as RigidbodyState, V as RigidbodyType, W as ScriptComponent, X as ScriptEntry, Y as ScriptObjectComponent, Z as ScriptObjectComponentInput, _ as ScriptObjectRuntimeState, $ as Selectable, a0 as SelectionTransformState, a1 as SpriteComponent, a2 as TextureFilteringValue, a3 as TransformModeValue, a4 as TransformSpaceValue, a5 as UIButtonComponent, a6 as UIButtonOptions, a7 as UIPanelComponent, a8 as UIPanelOptions, a9 as UISliderComponent, aa as UISliderOptions, ab as UITextComponent, ac as UITextOptions, ad as UIToggleComponent, ae as UIToggleOptions, af as UiFollowMode, ag as UiTextAlign, ah as UiTextVAlign, ai as VRTeleportAreaComponent, aj as VRTeleportAreaOptions, ak as VideoComponent, al as VrTeleportShape, am as XRAnchorComponent, an as XRAnchorOptions, ao as XRHandPoseComponent, ap as XRHandPoseOptions, aq as XRInteractableComponent, ar as XRInteractableOptions, as as XRInteractorComponent, at as XRInteractorOptions, au as XRInteractorSideComponent, av as XRRigComponent, aw as XRRigOptions, ax as XrAttachPoint, ay as XrDistanceGrabBehavior, az as XrEnvironmentPhysics, aA as XrGrabGesture, aB as XrGrabHands, aC as XrGrabReach, aD as XrHandPoseEntry, aE as XrHandPreset, aF as XrInteractorSide, aG as XrInteractorType, aH as XrLocomotionMode, aI as XrTrackingOrigin, aJ as XrTwoHandRotation, aK as createAttachPoint, aL as createHandPoseEntry, aM as defaultMaterialValue, aN as handPoseDefinitionFor, aO as normalizePhysicsState, aP as setPhysicsLiveRef } from '../XRHandPose-CU3vNFuS.js';
+export { D as DEFAULT_ENVIRONMENT_STATE, a as DEFAULT_POSTPROCESSING_STATE, E as Environment, b as EnvironmentFogState, c as EnvironmentFogType, d as EnvironmentGradientEffect, e as EnvironmentSkyboxState, f as EnvironmentSkyboxType, g as EnvironmentState, P as ParentId, h as Postprocessing, i as PostprocessingState, T as TransformComponent, j as TransformData, V as Vec3 } from '../System-V_mv07le.js';
+export { P as PrefabInstance, a as PrefabNode, X as XREnvironmentComponent, b as XrEnvironmentKind, c as XrEnvironmentOrientation } from '../index-C3ik3sA1.js';
 import 'three';
 import '@dimforge/rapier3d-compat';
 import '../handPose-DlcTtqgx.js';

package/dist/components/index.js

@@ -1,4 +1,4 @@
-export { AnimationComponent, AudioComponent, CameraComponent, DEFAULT_COLLIDER_STATE, DEFAULT_ENVIRONMENT_STATE, DEFAULT_INSTANCED_MESH_PARAMETERS, DEFAULT_INSTANCE_TRANSFORM, DEFAULT_MESH_GEOMETRY_PARAMETERS, DEFAULT_PHYSICS_STATE, DEFAULT_POSE_CURLS, DEFAULT_POSE_DIRECTIONS, DEFAULT_POSTPROCESSING_STATE, DEFAULT_RIGIDBODY_STATE, EntityType, Environment, ImageComponent, ImageTarget, ImageTargetAnchor, InstanceSlotComponent, InstancedMeshComponent, LightComponent, MaterialComponent, MeshComponent, MeshGeometryComponent, ModelComponent, Name, Object3DRef, ParentId, PhysicsComponent, Postprocessing, PrefabInstance, PrefabNode, ScriptComponent, ScriptObjectComponent, Selectable, SelectionTransformState, SpriteComponent, TransformComponent, VRTeleportAreaComponent, VideoComponent, XRAnchorComponent, XREnvironmentComponent, XRHandPoseComponent, XRInteractableComponent, XRInteractorComponent, XRInteractorSideComponent, XRRigComponent, createAttachPoint, createHandPoseEntry, defaultMaterialValue, handPoseDefinitionFor, normalizePhysicsState, setPhysicsLiveRef } from '../chunk-4AK4I3QF.js';
+export { AnimationComponent, AudioComponent, CameraComponent, DEFAULT_COLLIDER_STATE, DEFAULT_ENVIRONMENT_STATE, DEFAULT_INSTANCED_MESH_PARAMETERS, DEFAULT_INSTANCE_TRANSFORM, DEFAULT_MESH_GEOMETRY_PARAMETERS, DEFAULT_PHYSICS_STATE, DEFAULT_POSE_CURLS, DEFAULT_POSE_DIRECTIONS, DEFAULT_POSTPROCESSING_STATE, DEFAULT_RIGIDBODY_STATE, EntityType, Environment, ImageComponent, ImageTarget, ImageTargetAnchor, InstanceSlotComponent, InstancedMeshComponent, LightComponent, MaterialComponent, MeshComponent, MeshGeometryComponent, ModelComponent, Name, Object3DRef, ParentId, PhysicsComponent, Postprocessing, PrefabInstance, PrefabNode, ScriptComponent, ScriptObjectComponent, Selectable, SelectionTransformState, SpriteComponent, TransformComponent, UIButtonComponent, UIPanelComponent, UISliderComponent, UITextComponent, UIToggleComponent, VRTeleportAreaComponent, VideoComponent, XRAnchorComponent, XREnvironmentComponent, XRHandPoseComponent, XRInteractableComponent, XRInteractorComponent, XRInteractorSideComponent, XRRigComponent, createAttachPoint, createHandPoseEntry, defaultMaterialValue, handPoseDefinitionFor, normalizePhysicsState, setPhysicsLiveRef } from '../chunk-BUEKOSR5.js';
 import '../chunk-OY7ZODZP.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

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

@@ -0,0 +1,165 @@
+# Spatial UI
+
+Menus, HUDs, labels and settings panels that live **in the world**. UI is built
+from five widget entities — **panel**, **text**, **button**, **toggle**,
+**slider** — each a real entity with its own transform: move it with the gizmo,
+parent it like anything else, save it with the scene.
+
+Widgets render on both XR headsets (point with the ray or gaze, click with
+trigger or pinch) and flat 3D experiences (hover and click with the mouse).
+Hover and press feedback is built in — you never script your own highlight.
+
+## The one sizing rule
+
+**Widget size is authored in metres on the component — never with transform
+scale.** The widget's face is a texture rasterised for the authored size;
+scaling the entity stretches those texels into blur. To make a panel bigger,
+raise its `width`/`height` fields and it re-renders crisply.
+
+## Building a menu
+
+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.
+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
+   entity first, then **bubble up the parent chain** — so the panel script
+   hears every child widget and can switch on `actionId`:
+
+```ts
+import { Behaviour, type UiInteractionEvent } from "@relu-interactives/spatial-ecs";
+
+export class MenuController extends Behaviour {
+  onUiPress(event: UiInteractionEvent) {
+    switch (event.actionId) {
+      case "start-game":
+        // A button under this panel was clicked.
+        break;
+      case "quit":
+        break;
+    }
+  }
+
+  onUiToggle(event: UiInteractionEvent) {
+    if (event.actionId === "music") {
+      const on = event.value === true;
+      console.log("music enabled:", on);
+    }
+  }
+
+  onUiChange(event: UiInteractionEvent) {
+    if (event.actionId === "volume" && typeof event.value === "number") {
+      console.log("volume:", event.value);
+    }
+  }
+}
+```
+
+Bubbling — not broadcast — is what keeps two copies of the same menu prefab
+independent: each panel script hears only its own children.
+
+## The widgets
+
+| Widget | Component | What it is |
+| --- | --- | --- |
+| Panel | `UIPanelComponent` | The flat backdrop. Rounded corners, border, translucency, follow mode. |
+| Text | `UITextComponent` | Wrapped, aligned text. `fontSize` is metres of glyph height. |
+| Button | `UIButtonComponent` | Pressable. Fires `onUiPress` on release. |
+| 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.
+
+### Press semantics
+
+A click is **press, then release while still pointing at the same widget** —
+sliding off before releasing cancels, exactly like every platform's buttons.
+While a press or slider drag is held, that hand cannot accidentally teleport
+(suppressed the same way grabbing suppresses it).
+
+`onUiChange` streams while a slider is dragged (only on real value changes)
+and always fires once more with the final value on release.
+
+### Text sizing
+
+`fontSize` is **how tall the glyphs stand in the world**, in metres —
+`0.035` reads like comfortable body text at arm's length, independent of the
+panel's texture density. Lines wrap automatically to the component's `width`;
+overflow past `height` is clamped with an ellipsis.
+
+## Follow modes
+
+- `follow: "world"` (default) — the panel stays where you put it.
+- `follow: "billboard"` — the panel yaw-rotates to face the player every frame
+  at runtime (in the editor it holds still so you can work on it).
+
+For a **wrist menu**, don't billboard — parent the panel under an XR
+Interactor's **Left** or **Right** slot entity (the same slots used for custom
+hand meshes). It then rides the hand like a watch.
+
+## Reading and driving widgets from scripts
+
+Widget state is ordinary component data:
+
+```ts
+import { Behaviour } from "@relu-interactives/spatial-ecs";
+import {
+  UISliderComponent,
+  UITextComponent,
+} from "@relu-interactives/spatial-ecs/components";
+
+export class ScoreHud extends Behaviour {
+  private score = 0;
+
+  addPoint() {
+    this.score += 1;
+    // This entity is the HUD text; editing the component re-renders it.
+    const text = this.world.getComponent(this.entityId, UITextComponent);
+    if (text) text.text = `Score: ${this.score}`;
+  }
+
+  readVolume(sliderEntityId: number): number {
+    const slider = this.world.getComponent(sliderEntityId, UISliderComponent);
+    return slider ? slider.value : 0;
+  }
+}
+```
+
+Style/text edits re-render the widget's texture on the next frame. Toggle and
+slider `value` are authored state — what you set in the editor is the state
+the experience starts with.
+
+## Event payload
+
+Every UI hook receives the same shape:
+
+```ts
+import { Behaviour, type UiInteractionEvent } from "@relu-interactives/spatial-ecs";
+
+export class Inspect extends Behaviour {
+  onUiPress(event: UiInteractionEvent) {
+    event.targetEntityId; // the widget that was activated
+    event.actionId;       // its actionId, or its entity name
+    event.input;          // the XR input source, or null for mouse clicks
+    event.value;          // boolean (toggle) / number (slider); absent for presses
+  }
+
+  onUiHoverStart(event: UiInteractionEvent) {
+    // The pointer moved onto the widget (also fires for mouse hover).
+    console.log("hovering", event.targetEntityId);
+  }
+}
+```
+
+## Performance notes
+
+- A widget's face redraws only when its **style or content** changes — an
+  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.