@viamrobotics/motion-tools 1.26.1 → 1.27.0

package/dist/components/overlay/left-pane/Tree.svelte

@@ -1,13 +1,15 @@
 <script lang="ts">
+	import type { Entity } from 'koota'
+
 	import { normalizeProps, useMachine } from '@zag-js/svelte'
 	import * as tree from '@zag-js/tree-view'
 	import { VirtualList } from 'svelte-virtuallists'
 	import { SvelteSet } from 'svelte/reactivity'
 
-	import { traits } from '../../../ecs'
+	import { relations, traits } from '../../../ecs'
 	import { useSelectedEntity } from '../../../hooks/useSelection.svelte'
 
-	import type { TreeNode as TreeNodeType } from './buildTree'
+	import type { TreeNode as TreeNodeType } from './useTree.svelte'
 
 	import TreeNode from './TreeNode.svelte'
 
@@ -15,12 +17,11 @@
 
 	interface Props {
 		rootNode: TreeNodeType
-		nodeMap: Record<string, TreeNodeType | undefined>
 		dragElement?: HTMLElement
 		onSelectionChange?: (event: tree.SelectionChangeDetails) => void
 	}
 
-	let { rootNode, nodeMap, onSelectionChange, dragElement = $bindable() }: Props = $props()
+	let { rootNode, onSelectionChange, dragElement = $bindable() }: Props = $props()
 
 	const collection = $derived(
 		tree.collection<TreeNodeType>({
@@ -34,11 +35,10 @@
 	const expandedValues = new SvelteSet<string>()
 
 	$effect(() => {
-		let name = selected.current?.get(traits.Name)
-		let node = nodeMap[name ?? '']
-		while (node) {
-			expandedValues.add(`${node.entity}`)
-			node = node.parent
+		let entity: Entity | undefined = selected.current
+		while (entity) {
+			expandedValues.add(`${entity}`)
+			entity = entity.targetFor(relations.ChildOf)
 		}
 	})
 

package/dist/components/overlay/left-pane/Tree.svelte.d.ts

@@ -1,8 +1,7 @@
 import * as tree from '@zag-js/tree-view';
-import type { TreeNode as TreeNodeType } from './buildTree';
+import type { TreeNode as TreeNodeType } from './useTree.svelte';
 interface Props {
     rootNode: TreeNodeType;
-    nodeMap: Record<string, TreeNodeType | undefined>;
     dragElement?: HTMLElement;
     onSelectionChange?: (event: tree.SelectionChangeDetails) => void;
 }

package/dist/components/overlay/left-pane/TreeContainer.svelte

@@ -1,36 +1,26 @@
 <script lang="ts">
 	import { type Entity, IsExcluded } from 'koota'
 
-	import { traits, useQuery, useWorld } from '../../../ecs'
-	import { useFrames } from '../../../hooks/useFrames.svelte'
+	import { traits, useWorld } from '../../../ecs'
 	import { useSelectedEntity } from '../../../hooks/useSelection.svelte'
 
 	import FloatingPanel from '../FloatingPanel.svelte'
-	import { buildTreeNodes, type TreeNode } from './buildTree'
 	import Tree from './Tree.svelte'
 	import { provideTreeExpandedContext } from './useExpanded.svelte'
+	import { type TreeNode, useTree } from './useTree.svelte'
 
 	provideTreeExpandedContext()
 
 	const selectedEntity = useSelectedEntity()
-
-	const frames = useFrames()
 	const world = useWorld()
 
 	const worldEntity = world.spawn(IsExcluded, traits.Name('World'))
 
-	const allEntities = useQuery(traits.Name)
-
-	const { rootNodes, nodeMap } = $derived.by(() => {
-		// This ensures the tree rebuilds when frame parent relationships change
-		// eslint-disable-next-line @typescript-eslint/no-unused-expressions
-		frames.current
-		return buildTreeNodes(allEntities.current)
-	})
+	const tree = useTree()
 
 	const rootNode = $derived<TreeNode>({
 		entity: worldEntity,
-		children: rootNodes,
+		children: tree.current,
 	})
 </script>
 
@@ -44,7 +34,6 @@
 >
 	<Tree
 		{rootNode}
-		{nodeMap}
 		onSelectionChange={(event) => {
 			const value = event.selectedValue[0]
 

package/dist/components/overlay/left-pane/TreeNode.svelte

@@ -6,7 +6,7 @@
 
 	import { traits, useTrait } from '../../../ecs'
 
-	import type { TreeNode } from './buildTree'
+	import type { TreeNode } from './useTree.svelte'
 
 	import Self from './TreeNode.svelte'
 

package/dist/components/overlay/left-pane/TreeNode.svelte.d.ts

@@ -1,5 +1,5 @@
 import type { Api } from '@zag-js/tree-view';
-import type { TreeNode } from './buildTree';
+import type { TreeNode } from './useTree.svelte';
 interface Props {
     node: TreeNode;
     indexPath: number[];

package/dist/components/overlay/left-pane/useTree.svelte.d.ts

@@ -0,0 +1,14 @@
+import { type Entity } from 'koota';
+export interface TreeNode {
+    entity: Entity;
+    children?: TreeNode[];
+}
+/**
+ * Reactive top-down tree built from `ChildOf` relations. Rebuilds when any
+ * named entity is added, removed, renamed, or gains/loses a `ChildOf` or
+ * `Orphan` edge. Orphans are hidden from the tree — they reappear once
+ * `provideHierarchy` resolves them to a real `ChildOf` parent.
+ */
+export declare const useTree: () => {
+    readonly current: TreeNode[];
+};

package/dist/components/overlay/left-pane/useTree.svelte.js

@@ -0,0 +1,63 @@
+import { Not } from 'koota';
+import { createSubscriber } from 'svelte/reactivity';
+import { relations, traits, useWorld } from '../../../ecs';
+const compareByName = (a, b) => (a.get(traits.Name) ?? '').localeCompare(b.get(traits.Name) ?? '');
+const buildTree = (world) => {
+    const walk = (entity) => {
+        const node = { entity };
+        const children = world.query(relations.ChildOf(entity)).toSorted(compareByName);
+        if (children.length > 0) {
+            node.children = children.map((child) => walk(child));
+        }
+        return node;
+    };
+    const rootEntities = [];
+    for (const entity of world.query(traits.Name, Not(traits.Orphan))) {
+        if (entity.targetFor(relations.ChildOf))
+            continue;
+        rootEntities.push(entity);
+    }
+    rootEntities.sort(compareByName);
+    return rootEntities.map((entity) => walk(entity));
+};
+/**
+ * Reactive top-down tree built from `ChildOf` relations. Rebuilds when any
+ * named entity is added, removed, renamed, or gains/loses a `ChildOf` or
+ * `Orphan` edge. Orphans are hidden from the tree — they reappear once
+ * `provideHierarchy` resolves them to a real `ChildOf` parent.
+ */
+export const useTree = () => {
+    const world = useWorld();
+    let cached;
+    let dirty = true;
+    const subscribe = createSubscriber((update) => {
+        const invalidate = () => {
+            dirty = true;
+            update();
+        };
+        const unsubs = [
+            world.onAdd(traits.Name, invalidate),
+            world.onRemove(traits.Name, invalidate),
+            world.onChange(traits.Name, invalidate),
+            world.onAdd(relations.ChildOf, invalidate),
+            world.onChange(relations.ChildOf, invalidate),
+            world.onRemove(relations.ChildOf, invalidate),
+            world.onAdd(traits.Orphan, invalidate),
+            world.onRemove(traits.Orphan, invalidate),
+        ];
+        return () => {
+            for (const unsub of unsubs)
+                unsub();
+        };
+    });
+    return {
+        get current() {
+            subscribe();
+            if (dirty || !cached) {
+                cached = buildTree(world);
+                dirty = false;
+            }
+            return cached;
+        },
+    };
+};

package/dist/draw.js

@@ -1,4 +1,4 @@
-import { Vector3, Vector4 } from 'three';
+import { Matrix4, Vector3, Vector4 } from 'three';
 import { NURBSCurve } from 'three/addons/curves/NURBSCurve.js';
 import { UuidTool } from 'uuid-tool';
 import { createBufferGeometry, preAllocateBufferGeometry, updateBufferGeometry, writeBufferGeometryRange, } from './attribute';
@@ -6,7 +6,7 @@ import { asFloat32Array, asOpacity, asRGB, inMeters, isSingleColor, isVertexColo
 import { hierarchy, relations, traits } from './ecs';
 import { parsePcdInWorker } from './loaders/pcd';
 import { metadataFromStruct } from './metadata';
-import { createPose } from './transform';
+import { createPose, poseToMatrix } from './transform';
 import { ColorFormat } from './buf/draw/v1/metadata_pb';
 import { isPointCloud } from './geometry';
 const vec3 = new Vector3();
@@ -38,7 +38,7 @@ const isModel = (drawing) => {
 export const drawTransform = (world, { referenceFrame, poseInObserverFrame, physicalObject, metadata, uuid }, api, { removable = true } = {}) => {
     const entityTraits = [
         traits.Name(referenceFrame),
-        traits.Pose(createPose(poseInObserverFrame?.pose)),
+        traits.Matrix(poseToMatrix(createPose(poseInObserverFrame?.pose), new Matrix4())),
         api,
     ];
     const uuidStr = uuidBytesToString(uuid);
@@ -88,7 +88,7 @@ export const drawDrawing = (world, drawing, api, { removable = true } = {}) => {
     const uuidStr = uuidBytesToString(uuid);
     if (uuidStr)
         uuidTraits.push(traits.UUID(uuidStr));
-    const entity = world.spawn(traits.Name(referenceFrame), traits.Pose(createPose(poseInObserverFrame?.pose)), api, ...hierarchy.parentTraits(poseInObserverFrame?.referenceFrame), ...uuidTraits);
+    const entity = world.spawn(traits.Name(referenceFrame), traits.Matrix(poseToMatrix(createPose(poseInObserverFrame?.pose), new Matrix4())), api, ...hierarchy.parentTraits(poseInObserverFrame?.referenceFrame), ...uuidTraits);
     if (removable)
         entity.add(traits.Removable);
     if (metadata?.showAxesHelper)
@@ -99,7 +99,14 @@ export const drawDrawing = (world, drawing, api, { removable = true } = {}) => {
     return { entity, relationships: metadata?.relationships };
 };
 export const updateTransform = (entity, { poseInObserverFrame, physicalObject, metadata }, { removable = true } = {}) => {
-    entity.set(traits.Pose, createPose(poseInObserverFrame?.pose));
+    const matrix = entity.get(traits.Matrix);
+    if (matrix) {
+        poseToMatrix(createPose(poseInObserverFrame?.pose), matrix);
+        entity.changed(traits.Matrix);
+    }
+    else {
+        entity.add(traits.Matrix(poseToMatrix(createPose(poseInObserverFrame?.pose), new Matrix4())));
+    }
     hierarchy.setParent(entity, poseInObserverFrame?.referenceFrame);
     if (physicalObject) {
         traits.updateGeometryTrait(entity, physicalObject);
@@ -144,7 +151,14 @@ export const updateDrawing = (world, entity, drawing, { removable = true } = {})
     const { poseInObserverFrame, metadata } = drawing;
     if (!world.has(entity))
         return { entity, relationships: metadata?.relationships };
-    entity.set(traits.Pose, createPose(poseInObserverFrame?.pose));
+    const matrix = entity.get(traits.Matrix);
+    if (matrix) {
+        poseToMatrix(createPose(poseInObserverFrame?.pose), matrix);
+        entity.changed(traits.Matrix);
+    }
+    else {
+        entity.add(traits.Matrix(poseToMatrix(createPose(poseInObserverFrame?.pose), new Matrix4())));
+    }
     hierarchy.setParent(entity, poseInObserverFrame?.referenceFrame);
     if (metadata?.showAxesHelper)
         entity.add(traits.ShowAxesHelper);
@@ -270,7 +284,7 @@ const drawModel = (world, model, api, { removable = true }) => {
     const { animationName, assets, scale } = physicalObject.geometryType.value;
     const baseTraits = [
         traits.Name(referenceFrame),
-        traits.Pose(createPose(poseInObserverFrame?.pose)),
+        traits.Matrix(poseToMatrix(createPose(poseInObserverFrame?.pose), new Matrix4())),
         api,
         ...hierarchy.parentTraits(poseInObserverFrame?.referenceFrame),
     ];
@@ -291,8 +305,9 @@ const drawModel = (world, model, api, { removable = true }) => {
             relations.ChildOf(root),
             api,
         ];
-        if (scale)
-            subEntityTraits.push(traits.Scale(scale));
+        if (scale) {
+            subEntityTraits.push(traits.Matrix(new Matrix4().makeScale(scale.x ?? 1, scale.y ?? 1, scale.z ?? 1)));
+        }
         if (metadata?.invisible)
             subEntityTraits.push(traits.Invisible);
         if (metadata?.showAxesHelper)

package/dist/ecs/index.d.ts

@@ -4,6 +4,7 @@ export { useTrait } from './useTrait.svelte';
 export { useTarget } from './useTarget.svelte';
 export { useParentName } from './useParentName.svelte';
 export { provideHierarchy } from './provideHierarchy.svelte';
+export { provideWorldMatrix } from './provideWorldMatrix.svelte';
 export * as traits from './traits';
 export * as relations from './relations';
 export * as hierarchy from './hierarchy';

package/dist/ecs/index.js

@@ -4,6 +4,7 @@ export { useTrait } from './useTrait.svelte';
 export { useTarget } from './useTarget.svelte';
 export { useParentName } from './useParentName.svelte';
 export { provideHierarchy } from './provideHierarchy.svelte';
+export { provideWorldMatrix } from './provideWorldMatrix.svelte';
 export * as traits from './traits';
 export * as relations from './relations';
 export * as hierarchy from './hierarchy';

package/dist/ecs/provideWorldMatrix.svelte.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Mount the world-matrix reactor: keeps `WorldMatrix` in sync with the
+ * cumulative `parent.WorldMatrix × local rendered` for every entity whose
+ * `Matrix` / `EditedMatrix` / `LiveMatrix` / `Scale` / `ChildOf` changes.
+ * Microtask-deferred so a burst of changes (e.g. one `useFrames` reconcile
+ * tick) coalesces into a single subtree walk.
+ */
+export declare const provideWorldMatrix: () => void;

package/dist/ecs/provideWorldMatrix.svelte.js

@@ -0,0 +1,13 @@
+import { useWorld } from './useWorld';
+import { installWorldMatrixListeners } from './worldMatrix';
+/**
+ * Mount the world-matrix reactor: keeps `WorldMatrix` in sync with the
+ * cumulative `parent.WorldMatrix × local rendered` for every entity whose
+ * `Matrix` / `EditedMatrix` / `LiveMatrix` / `Scale` / `ChildOf` changes.
+ * Microtask-deferred so a burst of changes (e.g. one `useFrames` reconcile
+ * tick) coalesces into a single subtree walk.
+ */
+export const provideWorldMatrix = () => {
+    const world = useWorld();
+    $effect(() => installWorldMatrixListeners(world));
+};

package/dist/ecs/traits.d.ts

@@ -1,7 +1,7 @@
 import type { GLTF as ThreeGltf } from 'three/examples/jsm/loaders/GLTFLoader.js';
 import { Geometry as ViamGeometry } from '@viamrobotics/sdk';
 import { type Entity } from 'koota';
-import { BufferGeometry as ThreeBufferGeometry } from 'three';
+import { Matrix4, BufferGeometry as ThreeBufferGeometry } from 'three';
 export declare const Name: import("koota").Trait<() => string>;
 export declare const UUID: import("koota").Trait<() => string>;
 /**
@@ -12,33 +12,12 @@ export declare const UUID: import("koota").Trait<() => string>;
  * adding this trait directly.
  */
 export declare const Orphan: import("koota").Trait<() => string>;
-export declare const Pose: import("koota").Trait<{
-    x: number;
-    y: number;
-    z: number;
-    oX: number;
-    oY: number;
-    oZ: number;
-    theta: number;
-}>;
-export declare const EditedPose: import("koota").Trait<{
-    x: number;
-    y: number;
-    z: number;
-    oX: number;
-    oY: number;
-    oZ: number;
-    theta: number;
-}>;
-export declare const LivePose: import("koota").Trait<{
-    x: number;
-    y: number;
-    z: number;
-    oX: number;
-    oY: number;
-    oZ: number;
-    theta: number;
-}>;
+/**
+ * Static positional offset (e.g. center of a geometry). Stored as a Pose
+ * for the rare cases that need OV+theta semantics (currently unused).
+ * Never composed through the parent chain — the `WorldMatrix` system
+ * doesn't read it.
+ */
 export declare const Center: import("koota").Trait<{
     x: number;
     y: number;
@@ -48,25 +27,42 @@ export declare const Center: import("koota").Trait<{
     oZ: number;
     theta: number;
 }>;
-export declare const InstancedPose: import("koota").Trait<{
-    x: number;
-    y: number;
-    z: number;
-    oX: number;
-    oY: number;
-    oZ: number;
-    theta: number;
+/**
+ * Local-to-parent transform. Stored AoS — one `Matrix4` instance per entity —
+ * not as 16 SoA fields. Every consumer reads all 16 elements of one entity at
+ * a time (`Object3D.matrix.copy`, batched-mesh per-instance writes, the
+ * world-matrix walk). SoA would allocate a fresh 16-field object on every
+ * `entity.get(Matrix)`; AoS returns the `Matrix4` reference, zero allocation
+ * per read, and plugs straight into Three.js. The trade-off — losing
+ * column-iteration locality — is fine because no system iterates a single
+ * matrix element across entities.
+ *
+ * Update pattern: read the `Matrix4` and mutate in place, then call
+ * `entity.changed(Matrix)` so `onChange` listeners (the `WorldMatrix` system,
+ * etc.) fire. Allocate a fresh `Matrix4` only on add.
+ */
+export declare const Matrix: import("koota").Trait<() => Matrix4>;
+/** User-staged local transform during a `FrameEditSession`. */
+export declare const EditedMatrix: import("koota").Trait<() => Matrix4>;
+/**
+ * Live local transform from the robot's kinematics. Composed with `Matrix`
+ * (network baseline) and `EditedMatrix` to produce the rendered transform.
+ */
+export declare const LiveMatrix: import("koota").Trait<() => Matrix4>;
+/**
+ * Cumulative world-space transform — `parent.WorldMatrix × local rendered`.
+ * Maintained by `provideWorldMatrix`. Read by hover label placement,
+ * batched-mesh population, and any other consumer that needs world-space.
+ */
+export declare const WorldMatrix: import("koota").Trait<() => Matrix4>;
+/**
+ * World-space transform of a hovered instance inside a points/arrows batch,
+ * paired with the instance index in the parent batched mesh.
+ */
+export declare const InstancedMatrix: import("koota").Trait<() => {
+    matrix: Matrix4;
     index: number;
 }>;
-export declare const WorldPose: import("koota").Trait<{
-    x: number;
-    y: number;
-    z: number;
-    oX: number;
-    oY: number;
-    oZ: number;
-    theta: number;
-}>;
 export declare const Hovered: import("koota").Trait<() => boolean>;
 export declare const Invisible: import("koota").Trait<() => boolean>;
 /**
@@ -147,11 +143,6 @@ export declare const GLTF: import("koota").Trait<() => {
     };
     animationName: string;
 }>;
-export declare const Scale: import("koota").Trait<{
-    x: number;
-    y: number;
-    z: number;
-}>;
 export declare const FramesAPI: import("koota").Trait<() => boolean>;
 export declare const GeometriesAPI: import("koota").Trait<() => boolean>;
 export declare const DrawAPI: import("koota").Trait<() => boolean>;

package/dist/ecs/traits.js

@@ -1,6 +1,6 @@
 import { Geometry as ViamGeometry } from '@viamrobotics/sdk';
 import { trait } from 'koota';
-import { BufferGeometry as ThreeBufferGeometry } from 'three';
+import { Matrix4, BufferGeometry as ThreeBufferGeometry } from 'three';
 import { createBufferGeometry, updateBufferGeometry } from '../attribute';
 import { ColorFormat } from '../buf/draw/v1/metadata_pb';
 import { createBox, createCapsule, createSphere } from '../geometry';
@@ -16,29 +16,49 @@ export const UUID = trait(() => '');
  * adding this trait directly.
  */
 export const Orphan = trait(() => '');
-export const Pose = trait({ x: 0, y: 0, z: 0, oX: 0, oY: 0, oZ: 1, theta: 0 });
-export const EditedPose = trait({ x: 0, y: 0, z: 0, oX: 0, oY: 0, oZ: 1, theta: 0 });
-export const LivePose = trait({ x: 0, y: 0, z: 0, oX: 0, oY: 0, oZ: 1, theta: 0 });
+/**
+ * Static positional offset (e.g. center of a geometry). Stored as a Pose
+ * for the rare cases that need OV+theta semantics (currently unused).
+ * Never composed through the parent chain — the `WorldMatrix` system
+ * doesn't read it.
+ */
 export const Center = trait({ x: 0, y: 0, z: 0, oX: 0, oY: 0, oZ: 1, theta: 0 });
-export const InstancedPose = trait({
-    x: 0,
-    y: 0,
-    z: 0,
-    oX: 0,
-    oY: 0,
-    oZ: 1,
-    theta: 0,
+/**
+ * Local-to-parent transform. Stored AoS — one `Matrix4` instance per entity —
+ * not as 16 SoA fields. Every consumer reads all 16 elements of one entity at
+ * a time (`Object3D.matrix.copy`, batched-mesh per-instance writes, the
+ * world-matrix walk). SoA would allocate a fresh 16-field object on every
+ * `entity.get(Matrix)`; AoS returns the `Matrix4` reference, zero allocation
+ * per read, and plugs straight into Three.js. The trade-off — losing
+ * column-iteration locality — is fine because no system iterates a single
+ * matrix element across entities.
+ *
+ * Update pattern: read the `Matrix4` and mutate in place, then call
+ * `entity.changed(Matrix)` so `onChange` listeners (the `WorldMatrix` system,
+ * etc.) fire. Allocate a fresh `Matrix4` only on add.
+ */
+export const Matrix = trait(() => new Matrix4());
+/** User-staged local transform during a `FrameEditSession`. */
+export const EditedMatrix = trait(() => new Matrix4());
+/**
+ * Live local transform from the robot's kinematics. Composed with `Matrix`
+ * (network baseline) and `EditedMatrix` to produce the rendered transform.
+ */
+export const LiveMatrix = trait(() => new Matrix4());
+/**
+ * Cumulative world-space transform — `parent.WorldMatrix × local rendered`.
+ * Maintained by `provideWorldMatrix`. Read by hover label placement,
+ * batched-mesh population, and any other consumer that needs world-space.
+ */
+export const WorldMatrix = trait(() => new Matrix4());
+/**
+ * World-space transform of a hovered instance inside a points/arrows batch,
+ * paired with the instance index in the parent batched mesh.
+ */
+export const InstancedMatrix = trait(() => ({
+    matrix: new Matrix4(),
     index: -1,
-});
-export const WorldPose = trait({
-    x: 0,
-    y: 0,
-    z: 0,
-    oX: 0,
-    oY: 0,
-    oZ: 1,
-    theta: 0,
-});
+}));
 export const Hovered = trait(() => true);
 export const Invisible = trait(() => true);
 /**
@@ -100,7 +120,6 @@ export const GLTF = trait(() => ({
     source: { url: '' },
     animationName: '',
 }));
-export const Scale = trait({ x: 1, y: 1, z: 1 });
 export const FramesAPI = trait(() => true);
 export const GeometriesAPI = trait(() => true);
 export const DrawAPI = trait(() => true);
@@ -174,30 +193,39 @@ export const updateGeometryTrait = (entity, geometry) => {
         return;
     }
     if (geometry.geometryType.case === 'box') {
+        const next = createBox(geometry.geometryType.value);
         if (entity.has(Box)) {
-            entity.set(Box, createBox(geometry.geometryType.value));
+            const cur = entity.get(Box);
+            if (cur.x !== next.x || cur.y !== next.y || cur.z !== next.z)
+                entity.set(Box, next);
         }
         else {
             entity.remove(Capsule, Sphere, BufferGeometry);
-            entity.add(Box(createBox(geometry.geometryType.value)));
+            entity.add(Box(next));
         }
     }
     else if (geometry.geometryType.case === 'capsule') {
+        const next = createCapsule(geometry.geometryType.value);
         if (entity.has(Capsule)) {
-            entity.set(Capsule, createCapsule(geometry.geometryType.value));
+            const cur = entity.get(Capsule);
+            if (cur.r !== next.r || cur.l !== next.l)
+                entity.set(Capsule, next);
         }
         else {
             entity.remove(Box, Sphere, BufferGeometry);
-            entity.add(Capsule(createCapsule(geometry.geometryType.value)));
+            entity.add(Capsule(next));
         }
     }
     else if (geometry.geometryType.case === 'sphere') {
+        const next = createSphere(geometry.geometryType.value);
         if (entity.has(Sphere)) {
-            entity.set(Sphere, createSphere(geometry.geometryType.value));
+            const cur = entity.get(Sphere);
+            if (cur.r !== next.r)
+                entity.set(Sphere, next);
         }
         else {
             entity.remove(Box, Capsule, BufferGeometry);
-            entity.add(Sphere(createSphere(geometry.geometryType.value)));
+            entity.add(Sphere(next));
         }
     }
     else if (geometry.geometryType.case === 'mesh') {

package/dist/ecs/useTrait.svelte.d.ts

@@ -6,14 +6,9 @@ type Schema = {
 type TraitRecordFromSchema<T extends Schema> = T extends AoSFactory ? ReturnType<T> : {
     [P in keyof T]: T[P] extends (...args: never[]) => unknown ? ReturnType<T[P]> : T[P];
 };
-/**
- * The record of a trait.
- * For SoA it is a snapshot of the state for a single entity.
- * For AoS it is the state instance for a single entity.
- */
 type TraitRecord<T extends Trait | Schema> = T extends Trait ? TraitRecordFromSchema<T['schema']> : TraitRecordFromSchema<T>;
 export declare function isWorld(target: Entity | World | null | undefined): target is World;
 export declare function useTrait<T extends Trait>(target: () => Entity | World | undefined | null, trait: T): {
-    current: TraitRecord<T> | undefined;
+    readonly current: TraitRecord<T> | undefined;
 };
 export {};

package/dist/ecs/useTrait.svelte.js

@@ -1,30 +1,37 @@
 import { $internal as internal } from 'koota';
+import { untrack } from 'svelte';
 import { useWorld } from './useWorld';
 export function isWorld(target) {
     return typeof target?.spawn === 'function';
 }
 export function useTrait(target, trait) {
     const contextWorld = useWorld();
-    const targetEntity = $derived(target());
-    const world = $derived(isWorld(targetEntity) ? targetEntity : contextWorld);
-    const entity = $derived(isWorld(targetEntity) ? targetEntity[internal].worldEntity : targetEntity);
-    // Initialize the state with the current value of the trait.
-    let value = $derived(entity?.get(trait));
+    let value = $state.raw();
+    // Version counter to force reactivity when the value reference is the same (AoS traits).
+    // Only read in the getter, never in the effect.
+    let version = $state(0);
     $effect(() => {
-        const onAddUnsub = world.onAdd(trait, (e) => {
+        const t = target();
+        if (!t) {
+            value = undefined;
+            return;
+        }
+        const world = isWorld(t) ? t : contextWorld;
+        const entity = isWorld(t) ? t[internal].worldEntity : t;
+        value = entity.has(trait) ? entity.get(trait) : undefined;
+        const onChangeUnsub = world.onChange(trait, (e) => {
             if (e === entity) {
                 value = e.get(trait);
+                untrack(() => version++);
             }
         });
+        const onAddUnsub = world.onAdd(trait, (e) => {
+            if (e === entity)
+                value = e.get(trait);
+        });
         const onRemoveUnsub = world.onRemove(trait, (e) => {
-            if (e === entity) {
+            if (e === entity)
                 value = undefined;
-            }
-        });
-        const onChangeUnsub = world.onChange(trait, (e) => {
-            if (e === entity) {
-                value = e.get(trait);
-            }
         });
         return () => {
             onChangeUnsub();
@@ -34,6 +41,7 @@ export function useTrait(target, trait) {
     });
     return {
         get current() {
+            void version;
             return value;
         },
     };