@relu-interactives/spatial-ecs 0.8.0 → 0.9.0

package/dist/components/index.d.cts

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

package/dist/components/index.js

@@ -1,4 +1,4 @@
-export { AnimationComponent, AudioComponent, BoneAttachmentComponent, CameraComponent, DEFAULT_COLLIDER_STATE, DEFAULT_ENVIRONMENT_LIGHTING, 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, IKComponent, ImageComponent, ImageTarget, ImageTargetAnchor, InstanceSlotComponent, InstancedMeshComponent, LightComponent, MODEL_NO_PATH_MESSAGE, MaterialComponent, MeshComponent, MeshGeometryComponent, ModelComponent, Name, NetworkIdentityComponent, NetworkSpawnerComponent, NetworkTransformComponent, NetworkedPropsComponent, 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, normalizeEnvironmentLighting, normalizeIKChain, normalizePhysicsState, setModelLoadState, setPhysicsLiveRef } from '../chunk-NNDUOQ7O.js';
+export { AnimationComponent, AudioComponent, BoneAttachmentComponent, CameraComponent, DEFAULT_COLLIDER_STATE, DEFAULT_ENVIRONMENT_LIGHTING, 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, IKComponent, ImageComponent, ImageTarget, ImageTargetAnchor, InstanceSlotComponent, InstancedMeshComponent, LightComponent, MODEL_NO_PATH_MESSAGE, MaterialComponent, MeshComponent, MeshGeometryComponent, ModelComponent, Name, NetworkIdentityComponent, NetworkSpawnerComponent, NetworkTransformComponent, NetworkedPropsComponent, 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, normalizeEnvironmentLighting, normalizeIKChain, normalizePhysicsState, setModelLoadState, setPhysicsLiveRef } from '../chunk-JNYPJB55.js';
 import '../chunk-CKTHDXPS.js';
 import '../chunk-XE4OXN2W.js';
 //# sourceMappingURL=index.js.map

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/factories/index.cjs

@@ -2680,6 +2680,127 @@ function createXRInteractorSideComponent(world, entityId, ...args) {
 }
 __name(createXRInteractorSideComponent, "createXRInteractorSideComponent");
 
+// core/ui/uiStyle.ts
+var isRecord = /* @__PURE__ */ __name((value) => typeof value === "object" && value !== null && !Array.isArray(value), "isRecord");
+var finite = /* @__PURE__ */ __name((value) => typeof value === "number" && Number.isFinite(value), "finite");
+var nonEmpty = /* @__PURE__ */ __name((value) => typeof value === "string" && value.length > 0, "nonEmpty");
+function normalizeStops(value) {
+  if (!Array.isArray(value)) return null;
+  const stops = [];
+  for (const stop of value) {
+    if (isRecord(stop) && finite(stop.at) && nonEmpty(stop.color)) {
+      stops.push({ at: Math.min(1, Math.max(0, stop.at)), color: stop.color });
+    }
+  }
+  return stops.length >= 2 ? stops : null;
+}
+__name(normalizeStops, "normalizeStops");
+function normalizePaint(value) {
+  if (!isRecord(value)) return void 0;
+  if (value.kind === "solid" && nonEmpty(value.color)) {
+    return { kind: "solid", color: value.color };
+  }
+  if (value.kind === "linear") {
+    const stops = normalizeStops(value.stops);
+    if (stops) {
+      return {
+        kind: "linear",
+        angle: finite(value.angle) ? value.angle : 180,
+        stops
+      };
+    }
+  }
+  if (value.kind === "radial") {
+    const stops = normalizeStops(value.stops);
+    if (stops) return { kind: "radial", stops };
+  }
+  if (value.kind === "image" && nonEmpty(value.src)) {
+    const fit = value.fit === "contain" || value.fit === "fill" ? value.fit : "cover";
+    return {
+      kind: "image",
+      src: value.src,
+      fit,
+      ...nonEmpty(value.tint) ? { tint: value.tint } : {}
+    };
+  }
+  return void 0;
+}
+__name(normalizePaint, "normalizePaint");
+function normalizeShadow(value) {
+  if (!isRecord(value) || !nonEmpty(value.color)) return void 0;
+  return {
+    x: finite(value.x) ? value.x : 0,
+    y: finite(value.y) ? value.y : 0,
+    blur: finite(value.blur) ? Math.max(0, value.blur) : 0,
+    color: value.color
+  };
+}
+__name(normalizeShadow, "normalizeShadow");
+function normalizeText(value) {
+  if (!isRecord(value)) return void 0;
+  const text = {};
+  if (nonEmpty(value.font)) text.font = value.font;
+  if (finite(value.weight)) text.weight = value.weight;
+  if (finite(value.tracking)) text.tracking = value.tracking;
+  if (value.transform === "upper" || value.transform === "lower") {
+    text.transform = value.transform;
+  }
+  const paint = normalizePaint(value.paint);
+  if (paint) text.paint = paint;
+  if (finite(value.maxLines) && value.maxLines >= 1) {
+    text.maxLines = Math.floor(value.maxLines);
+  }
+  const shadow = normalizeShadow(value.shadow);
+  if (shadow) text.shadow = shadow;
+  return Object.keys(text).length > 0 ? text : void 0;
+}
+__name(normalizeText, "normalizeText");
+function normalizeUiStyle(value) {
+  if (!isRecord(value)) return void 0;
+  const style = {};
+  const fill = normalizePaint(value.fill);
+  if (fill) style.fill = fill;
+  if (isRecord(value.border) && finite(value.border.width)) {
+    const paint = normalizePaint(value.border.paint);
+    if (paint) {
+      style.border = { width: Math.max(0, value.border.width), paint };
+    }
+  }
+  if (finite(value.radius)) {
+    style.radius = Math.max(0, value.radius);
+  } else if (Array.isArray(value.radius) && value.radius.length === 4 && value.radius.every(finite)) {
+    style.radius = value.radius.map((r) => Math.max(0, r));
+  }
+  if (Array.isArray(value.shadows)) {
+    const shadows = value.shadows.map(normalizeShadow).filter((s) => !!s);
+    if (shadows.length > 0) style.shadows = shadows;
+  }
+  if (isRecord(value.edge) && finite(value.edge.width) && nonEmpty(value.edge.color)) {
+    style.edge = {
+      width: Math.max(0, value.edge.width),
+      color: value.edge.color
+    };
+  }
+  if (finite(value.opacity)) {
+    style.opacity = Math.min(1, Math.max(0, value.opacity));
+  }
+  const text = normalizeText(value.text);
+  if (text) style.text = text;
+  return Object.keys(style).length > 0 ? style : void 0;
+}
+__name(normalizeUiStyle, "normalizeUiStyle");
+function normalizeUiTokens(value) {
+  if (!isRecord(value)) return void 0;
+  const tokens = {};
+  for (const [key, token] of Object.entries(value)) {
+    if (nonEmpty(token) && key.length > 0 && !key.includes("/")) {
+      tokens[key] = token;
+    }
+  }
+  return Object.keys(tokens).length > 0 ? tokens : void 0;
+}
+__name(normalizeUiTokens, "normalizeUiTokens");
+
 // core/components/UIButton.ts
 var _UIButtonComponent = class _UIButtonComponent extends Component {
   constructor(options) {
@@ -2696,6 +2817,13 @@ var _UIButtonComponent = class _UIButtonComponent extends Component {
     this.cornerRadius = options?.cornerRadius ?? 0.02;
     this.borderWidth = options?.borderWidth ?? 2e-3;
     this.borderColor = options?.borderColor ?? "#3a3a3a";
+    if (options?.pixelDensity !== void 0) {
+      this.pixelDensity = options.pixelDensity;
+    }
+    const style = normalizeUiStyle(options?.style);
+    if (style) this.style = style;
+    if (options?.icon) this.icon = options.icon;
+    if (options?.iconPosition) this.iconPosition = options.iconPosition;
   }
 };
 __name(_UIButtonComponent, "UIButtonComponent");
@@ -2722,6 +2850,10 @@ var _UIPanelComponent = class _UIPanelComponent extends Component {
     this.borderColor = options?.borderColor ?? "#333333";
     this.pixelDensity = options?.pixelDensity ?? 1024;
     this.follow = options?.follow ?? "world";
+    const style = normalizeUiStyle(options?.style);
+    if (style) this.style = style;
+    const tokens = normalizeUiTokens(options?.tokens);
+    if (tokens) this.tokens = tokens;
   }
 };
 __name(_UIPanelComponent, "UIPanelComponent");
@@ -2750,6 +2882,14 @@ var _UISliderComponent = class _UISliderComponent extends Component {
     this.trackColor = options?.trackColor ?? "#2a2a2a";
     this.accentColor = options?.accentColor ?? "#ff6b35";
     this.knobColor = options?.knobColor ?? "#ffffff";
+    if (options?.pixelDensity !== void 0) {
+      this.pixelDensity = options.pixelDensity;
+    }
+    const style = normalizeUiStyle(options?.style);
+    if (style) this.style = style;
+    if (options?.variant) this.variant = options.variant;
+    if (options?.step !== void 0) this.step = options.step;
+    if (options?.readOnly !== void 0) this.readOnly = options.readOnly;
   }
 };
 __name(_UISliderComponent, "UISliderComponent");
@@ -2777,6 +2917,11 @@ var _UITextComponent = class _UITextComponent extends Component {
     this.valign = options?.valign ?? "middle";
     this.lineHeight = options?.lineHeight ?? 1.25;
     this.padding = options?.padding ?? 0.01;
+    if (options?.pixelDensity !== void 0) {
+      this.pixelDensity = options.pixelDensity;
+    }
+    const style = normalizeUiStyle(options?.style);
+    if (style) this.style = style;
   }
 };
 __name(_UITextComponent, "UITextComponent");
@@ -2801,6 +2946,12 @@ var _UIToggleComponent = class _UIToggleComponent extends Component {
     this.trackColor = options?.trackColor ?? "#2a2a2a";
     this.accentColor = options?.accentColor ?? "#ff6b35";
     this.knobColor = options?.knobColor ?? "#ffffff";
+    if (options?.pixelDensity !== void 0) {
+      this.pixelDensity = options.pixelDensity;
+    }
+    const style = normalizeUiStyle(options?.style);
+    if (style) this.style = style;
+    if (options?.variant) this.variant = options.variant;
   }
 };
 __name(_UIToggleComponent, "UIToggleComponent");